Skip to content

README.ru.md

Latest commit

 

History

History
254 lines (184 loc) · 13.2 KB

README.ru.md

File metadata and controls

254 lines (184 loc) · 13.2 KB
Raw

@forgeplan/web

@forgeplan/web — интерактивная карта Forgeplan-воркспейса

Смотри Forgeplan-воркспейс как интерактивный граф

Маленький npm CLI, который разворачивает в твоём проекте уже собранный SvelteKit-вьювер. Без установок на стороне пользователя: npx @forgeplan/web init -y копирует self-contained приложение, npx @forgeplan/web start поднимает force-directed карту всех PRD, RFC, ADR, Spec, Epic и EvidencePack из твоего .forgeplan/.


License: MIT npm CI cross-platform

Forgeplan · Документация · Использование · Релизы · npm


English · Русский


    ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
    │  INIT  │ ─▶ │  COPY  │ ─▶ │  START │ ─▶ │ BROWSE │
    └────────┘    └────────┘    └────────┘    └────────┘
     verify       cp -r dist    spawn node     map @ 5174

Read-only. Cross-platform. Без установок.

Зачем

До

  • forgeplan list — плоский текст, без связей
  • Связи PRD ↔ RFC ↔ Evidence — неявные
  • ASCII-mermaid из forgeplan graph — одноразовый
  • Чтобы прочитать тело артефакта — лезешь в markdown
  • Поднимать SvelteKit-дев чтобы просто посмотреть данные

После

  • Force-directed карта артефактов, размер по R_eff
  • Типизированные стрелки (informs, refines, supersedes, …)
  • Живой, pannable, zoomable, пять режимов отображения
  • Side-панель рендерит markdown-тело + переходы по связям
  • Один npx — без установок, сервер поднимается за секунды

Установка

# Разово (рекомендуется)
npx @forgeplan/web init -y
npx @forgeplan/web start
# Или глобально на PATH
npm install -g @forgeplan/web
forgeplan-web init -y
forgeplan-web start

Требует Node ^20.19.0 || >=22.12.0, бинарник forgeplan на PATH и наличие .forgeplan/ в текущей директории. Полная справка — docs/USAGE.md.

Образы (images): stable (по умолчанию) и nightly

npx @forgeplan/web init -y                   # stable (по умолчанию)
npx @forgeplan/web init -y --image nightly   # pre-release ветка

Каждый релиз шипит два именованных образа (image) скаффолда. Байты у обоих одинаковые — self-contained ~1.4 MB single-file bundle (без node_modules/, никакого npm install на стороне пользователя); разница в наборе фичефлагов, которые несёт каждый образ. v1 шипит оба образа с нулём флагов — фреймворк готов к опт-ин фичам без того чтобы пользователи stable за них платили.

  • stable — дефолт для init / update. Шипит только флаги, чей rollout достиг stable.
  • nightly — early-access ветка. Шипит все флаги, включая alpha/beta. Используй когда хочешь pre-release поведение и не против изменений между minor-версиями.

Сменить ветку: npx @forgeplan/web update --image <name>. Выбор запоминается в forgeplan-web.json для будущих обновлений.

--experimental — устаревший alias для --image nightly (живёт ещё один minor-релиз; удаляется в 0.3.0).

Maintainer-вью на образы и флаги: config/IMAGES.md.

Демо за 60 секунд

$ cd ~/projects/my-app/                     # первый запуск, директория с .forgeplan/

$ npx @forgeplan/web init -y
  → creating /Users/me/projects/my-app/.forgeplan-web
  → created .gitignore (added .forgeplan-web/)

  ✓ ready (no install needed)
    npx @forgeplan/web start
    # or: node .forgeplan-web/index.js

$ npx @forgeplan/web start
  → starting forgeplan-web on http://127.0.0.1:5174
    workspace: /Users/me/projects/my-app
  Listening on http://127.0.0.1:5174

Повторные запуски показывают → updating ... и → appended .forgeplan-web/ to .gitignore (идемпотентно — строка добавляется один раз и сохраняется).

Открой URL — воркспейс отрендерится как force-directed граф. Фильтруй по kind, status, диапазону R_eff; кликни узел — увидишь markdown-тело и переходы по связям. Браузер опрашивает каждые 10 секунд, поэтому изменения на диске появляются за пару секунд (после forgeplan reindex).

Что получаешь
📦 Без установок у пользователя Пакет содержит один self-contained ~1.4 MB single-file bundle на каждый объявленный образ (dist/ для stable, dist-nightly/ для nightly). init — это cp -r. У пользователя ничего не ставится.
🪟 По-настоящему cross-platform Smoke-матрица ubuntu-latest / macos-latest / windows-latest × Node 22, зелёная на каждом push с v0.1.3.
🔒 Read-only by design /api/* дёргает только read-only подкоманды forgeplan (правило 22). Вьювер не может изменить воркспейс.
🌐 Пять видов графа Force, Lanes, Matrix, Radial, Tree. Каждый отвечает на свой вопрос — поток, смежность, иерархия, parent/child.
⚡ Живой polling UI обновляется каждые 10 секунд. Без ручного reload, без websocket-обвязки.
🤖 Agent-aware Hooks + CLAUDE.md + гайды лежат в репо для безопасной работы AI-агентов.
🏷️ Forgeplan-native Говорит на языке методологии — PRD, RFC, ADR, Evidence, R_eff scoring, типизированные связи — из коробки.

Что показывает

Поверхность Источник
Force-directed карта артефактов forgeplan list --json
Типизированные связи-стрелки forgeplan graph --json
Side-панель с markdown-телом forgeplan get <id> --json
Health-полоса вживую forgeplan health --json
Insights-табы (Recent / Agents / Blocked / Drafts / Health) forgeplan log --json, claims --json, blocked --json, …
Фильтры (kind, status, диапазон R_eff) client-side, сохраняются в localStorage

Полный каталог фич — docs/USAGE.md.

Документация

Три точки входа — выбирай ту, что соответствует твоей задаче сейчас.

Я хочу… Начать отсюда
Использовать пакет docs/USAGE.md — install, CLI, env, endpoints
Контрибьютить docs/CONTRIBUTING.md — layout, dev-loop, CI, release flow
Работать с AI-агентами CLAUDE.md · guides/INDEX.md

Dogfood

~1.4 МБ
на образ (esbuild-бандл)		 ~870 КБ
tarball (~3 МБ распакованный)		 3 OS × Node 22
зелёная smoke-матрица		 1 dep
в bin/ (citty, 0 транзитивных)

Этот репозиторий использует свою же методологию — каждый PRD, RFC, ADR и EvidencePack лежит в .forgeplan/ (на HEAD — 100+ артефактов, листать можно в этом же UI, который пакет шипит). Локально валидируется и скорится; ничего не уходит в main без R_eff > 0, активного артефакта и зелёной smoke-матрицы.

Contributing

# Ветвимся от develop (main трогаем только через release/* и hotfix/*)
git checkout develop && git pull
git checkout -b feature/my-thing

# Цикл: route → shape → build → smoke → evidence → activate → PR
# CI должен быть зелёным на ubuntu/macos/windows × Node 22 до merge
gh pr create --base develop

Branch protection защищает правила на сервере — прямой push в main или develop, force-push в любую из них, и rewrite тегов v*.*.* отвергаются с GH006 / GH013. Полный гайд — CLAUDE.md.

Локальные dev-режимы

npm run dev              # HMR против собственного .forgeplan/ репо (100+ артефактов)
npm run dev:playground   # HMR против playground/.forgeplan/ (~123 засеянных Helios-артефакта)

playground/ — вымышленный, repo-internal Forgeplan-воркспейс (PRD, RFC, ADR, Spec, Epic, EvidencePack для несуществующей observability-платформы «Helios»), нужный чтобы прогонять вьювер на реалистичном объёме данных — фильтры, пять режимов отображения, плотность связей, производительность. В пакет не публикуется и в проекты пользователей не копируется.

Лицензия

MIT — см. LICENSE.


Read-only. Cross-platform. Без установок.

→ Установить сейчас и npx @forgeplan/web start.


Спутник @ForgePlan/forgeplan · English version