portmap

Ваш агент захардкодил localhost:3000. Здесь показано, что реально запущено.

git clone https://github.com/paladini/portmap.git && cd portmap
npm ci && npm run build && node dist/cli.js scan /path/to/your-app

Детерминировано · Без LLM · Без сети · Только чтение

Что это?

portmap — это инструмент командной строки + MCP-сервер, который отвечает на один вопрос:

Прежде чем ваш агент запустит curl localhost:3000, действительно ли там кто-то слушает порт?

Он объединяет три слоя реальности локальной разработки в единую карту:

1. Заявленное — порты в vite.config, скриптах package.json, URL из .env, docker-compose

2. Фактическое — что ваша ОС сообщает о слушающих портах прямо сейчас (Windows, macOS, Linux)

3. Связанное — как переменные окружения (VITE_API_URL, API_URL, …) связывают сервисы между собой

Результат: .portmap.json + практичные выводы (PRT-01 … PRT-07), которые агенты и CI могут использовать без угадывания.

Для кого это?

• Разработчики, которых достал дрейф портов — «убей порт 3000» и «работает на моей машине»

• Команды, использующие AI-агентов для написания кода (Cursor, Claude Code, Copilot), которые захардкожили неверные localhost URL

• Монорепозитории, где фронтенд и API живут в соседних папках, а env-ссылки выходят за пределы репозитория

• Все, кто хочет быструю проверку за 5 секунд перед отладкой подключения к API

Чем это не является

Если нужно убить процесс — используйте инструменты ОС. portmap подскажет, какой порт использовать, прежде чем вы потратите двадцать минут.

Related MCP server: devenv-doctor-mcp

Проблема

Каждая AI-ассистируемая сессия разработки рано или поздно упирается в это:

Agent:  fetch('http://localhost:3000/api/users')
Reality: Vite on :5173, API on :8080, nothing on :3000

Почему так происходит:

• Next.js по умолчанию выбирает :3000 — агенты это запоминают

• Vite по умолчанию выбирает :5173 — другой стек, другой порт

• Docker переопределяет 8080:3000 — приложение слушает порт внутри контейнера, а не там, где вы думаете

• .env.local указывает на порт, который сегодня никто не запускал

• 20 минут отладки CORS, авторизации и «network error», а настоящая причина — PRT-04

portmap выявляет расхождения за считанные секунды — заявленное, фактическое и env — так что вы исправляете URL, а не симптом.

Как это работает

Два сканера, один шаг сверки, ни одного LLM:

┌─────────────────────────────────────────────────────────────┐
│  Your repo on disk                                          │
├─────────────────────────────────────────────────────────────┤
│  1. Static discovery                                        │
│     package.json scripts · vite.config · .env localhost URLs│
│     docker-compose port mappings                            │
├─────────────────────────────────────────────────────────────┤
│  2. Runtime scan (optional)                                 │
│     OS listeners → port, PID, process, command line           │
├─────────────────────────────────────────────────────────────┤
│  3. Reconcile                                               │
│     declared ↔ actual ↔ env references → service graph        │
│     → .portmap.json + findings (PRT-01 … PRT-07)            │
└─────────────────────────────────────────────────────────────┘
         ↓                    ↓                    ↓
    CLI pretty          MCP tools            CI --min-findings

Полный список правил: docs/FINDINGS.md · Примеры до/после исправлений: docs/EXAMPLES.md · JSON-спецификация: docs/SCHEMA.md

Попробовать за 30 секунд

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build

npm run demo:mismatch     # classic agent mistake → 3 errors
npm run demo:workspace    # frontend + API in sibling folders → resolved

Как выглядит demo:mismatch

portmap — mismatch-app
root: …/fixtures/mismatch

Services:
  [down] vite — Vite dev server
    declared :5173 (vite.config.ts:server.port)
    not listening

Env references:
  NEXT_PUBLIC_API_URL=http://localhost:3000 → :3000 [unresolved]
  VITE_API_URL=http://localhost:8080 → :8080 [unresolved]

Findings: 3 error(s), 0 warning(s)
  ✖ PRT-01 Declared port 5173 is not listening …
  ✖ PRT-04 NEXT_PUBLIC_API_URL points to localhost:3000 but nothing is listening …
  ✖ PRT-04 VITE_API_URL points to localhost:8080 but nothing is listening …

Вот она, вся сессия отладки, которую агент пропускает, если сначала читает .portmap.json.

Установка и запуск

Вариант A — склонировать (работает уже сегодня)

git clone https://github.com/paladini/portmap.git
cd portmap
npm ci && npm run build
node dist/cli.js scan /path/to/your-app

Вариант B — npm (после публикации)

npx portmap scan .

Типичный сценарий

1. Запустите portmap scan . (или portmap declare ., если сейчас ничего не запущено)

2. Прочитайте references[] — там верные localhost URL; не думайте, что это всегда :3000

3. Исправьте PRT-04 (нерабочий env URL), прежде чем отлаживать подключение к API

4. Запишите .portmap.json для будущих агент-сессий: portmap scan . --write

5. Опционально: добавьте в CI блокирующую проверку --min-findings 1 --min-severity error

Команды

Флаги: --json · --markdown · --write (сохраняет .portmap.json) · --out <file> · --min-findings N · --quiet

Находки вкратце

Полный каталог с исправлениями: docs/FINDINGS.md

MCP для агентов (только чтение)

Добавьте в .cursor/mcp.json или в конфиг Claude Code:

{
  "mcpServers": {
    "portmap": {
      "command": "node",
      "args": ["/path/to/portmap/dist/cli.js", "mcp"]
    }
  }
}

Скилл для Cursor/Claude: .cursor/skills/portmap/SKILL.md

.portmap.json — артефакт, который читают агенты

portmap scan . --write
git add .portmap.json   # optional: commit for stable agent context

Спецификация: docs/SCHEMA.md

Пайплайн готовности агентов

Часть набора инструментов paladini для агентов — три детерминированные проверки, ни одного LLM:

harness-score  →  Is the repo harness ready for agents?
portmap        →  Do ports and env URLs align locally?
unhappypath    →  Is the UI ready for real users?

Ограничения (честно)

• Сопоставление PID → репозиторий — эвристика; низкая уверенность помечается, а не скрывается

• WSL / Docker networking — то, что слушает внутри контейнера, на хосте может отображаться не так, как вы ожидаете

• Runtime-only порты (захардкожены в JS без конфига) не будут отдекларированы — возможно предупреждение PRT-02

• YAML compose — v1 понимает типичные паттерны ports:; экзотические возможности compose не поддерживаются

• Лучше пропустить находку, чем выдавать шумные ложные срабатывания — если сомнительно, portmap молчит

Участие

Приветствуются баг-репорты, сообщения об ложных срабатываниях и новые парсеры.

См. CONTRIBUTING.md · ROADMAP.md · CODE_OF_CONDUCT.md

Проблемы безопасности: SECURITY.md — пожалуйста, не открывайте их публично.

Разработка

npm ci
npm run build
npm test
npm run demo:mismatch
npm run demo:workspace

Гайд для агентов и контрибьюторов: AGENTS.md

License

MIT © 2026 Fernando Paladini