Global installation of forgeplan/web without project initialization. Incremental ports. Tabs for switching between multiple instances

[fedorovvvv]

Multi-instance management for @forgeplan/web — make it possible to run several forgeplan-web instances simultaneously across projects, install once per user (instead of per project), and switch between running instances from the UI.

Original idea

1. Remove init from the project flow and move the dist directory to a user-level scope.
2. Instances should use incremental ports automatically.
3. Add a persistent store to track all running instances.
4. If more than one instance is running, display tabs in the active instance for switching between them, including information about which project each instance belongs to.

Refined plan (post-decomposition)

After Shape-phase routing, the literal "remove init" is replaced with dual-scope (--scope user|project) — backwards compatible, no breakage for existing users. Project-scope keeps the current behavior; user-scope (~/.forgeplan-web/) is the new default for fresh installs. The "tabs" requirement becomes a Combobox (searchable, scales beyond 5+ instances) in the existing HealthBar.

Sub-issues

• [109a] CLI library + arg parser overhaul (citty in bin/) #110 — [109a] CLI library + arg parser overhaul (citty in bin/). Gating refactor: subcommands, prompts, --scope flag plumbing.
• [109b] --scope user/project for init + interactive prompt #111 — [109b] --scope user/project for init + interactive prompt fallback when omitted.
• [109c] start resolution chain (project → user → prompt-init) + --scope #112 — [109c] start resolution chain (project → user → prompt-init) + --scope override.
• [109d] Instance registry — multi-port, global JSON, stale invalidation #113 — [109d] Instance registry at ~/.forgeplan-web/instances.json: incremental ports, project metadata (name/path/pid/port/heartbeat), stale invalidation on every start via process.kill(pid, 0) liveness probe.
• [109e] Combobox primitive in shared/ui (bits-ui port) #114 — [109e] Combobox primitive in shared/ui/ (bits-ui port), showcased on /playground. Reusable across widgets.
• [109f] HealthBar instance switcher (Combobox wired to /api/instances) #115 — [109f] HealthBar instance switcher — Combobox listing registered instances; selecting one navigates to http://host:port. Instance ID = host:port.

Forgeplan artifacts (Shape phase)

Artifact	Scope
ADR-003	Amend .claude/rules/23-bin-zero-deps.md to permit citty (~5KB ESM, zero transitive deps) by name. Gates 109a.
ADR-004	Registry path + JSON-format choice (~/.forgeplan-web/instances.json + atomic rename writes). Gates 109d.
PRD-024 + RFC-020	citty integration + bin/ split (bin/cli.mjs + bin/commands/*.mjs).
PRD-025 + RFC-021	--scope flag + interactive prompt + user-scope path resolver.
PRD-026 + RFC-022	start resolution algorithm + error UX.
PRD-027 + SPEC-003 + RFC-023	Registry schema + port allocator + pid-liveness probe + /api/instances endpoint. Rule 22 amendment captured here.
PRD-028 + RFC-024	Combobox primitive.
PRD-029 + RFC-025	HealthBar wiring.

Dependency order

ADR-003 ─┐
         ├─ 109a ─┬─ 109b ─ 109c ─ 109d ─┐
                 └─ 109e ────────────────├─ 109f
ADR-004 ─────────────────────────────────┘

109a is the gating refactor (citty + arg parser). After it: 109b/109c/109e parallel. 109d serializes after 109c (needs user-scope path conventions). 109f closes the loop after 109d (needs /api/instances) + 109e (needs Combobox).

Out-of-scope (deferred to follow-ups)

• Cross-host federation (talking to instances on other machines).
• Auth / per-instance access control.
• Migration tool for existing project-scope .forgeplan-web/ → user-scope.
• Full XDG compliance (XDG_CONFIG_HOME etc.) — RFC-021 keeps ~/.forgeplan-web/ for predictability.

Acceptance

• All 6 sub-issues closed via PRs merged into develop.
• 3-OS smoke (npm run smoke) green.
• 3 concurrent instances on incremental ports, all visible from each other's HealthBar Combobox.
• R_eff > 0 and active for every PRD/RFC/ADR/Spec before the parent issue closes.
• A user installing @forgeplan/web for the first time can npx @forgeplan/web init (interactive prompt picks scope), then start works in any project directory.

[fedorovvvv]

Decomposed into 6 sub-issues (Shape phase, before code). Per maintainer clarification the literal "remove init" is replaced with dual-scope (--scope user|project) — backwards compatible.

Sub-issue checklist

• [109a] CLI library + arg parser overhaul (citty in bin/) #110 — [109a] CLI library + arg parser overhaul (citty)
• [109b] --scope user/project for init + interactive prompt #111 — [109b] --scope user/project for init + interactive prompt
• [109c] start resolution chain (project → user → prompt-init) + --scope #112 — [109c] start resolution chain (project → user → prompt-init)
• [109d] Instance registry — multi-port, global JSON, stale invalidation #113 — [109d] Instance registry — multi-port, global JSON, stale invalidation
• [109e] Combobox primitive in shared/ui (bits-ui port) #114 — [109e] Combobox primitive in shared/ui (bits-ui port)
• [109f] HealthBar instance switcher (Combobox wired to /api/instances) #115 — [109f] HealthBar instance switcher (Combobox wired to /api/instances)

Forgeplan artifacts (Shape phase)

• ADR-003 — amend rule 23 to permit citty in bin/ (gates 109a)
• ADR-004 — registry path + format choice (gates 109d)
• PRD-024..029 — one per sub-issue
• RFC-019..024 — one per sub-issue (implementation)
• Spec-001 — registry JSON schema

Dependency order

ADR-003 ─┐
         ├─ 109a ─┬─ 109b ─ 109c ─ 109d ─┐
                 └─ 109e ────────────────├─ 109f
ADR-004 ─────────────────────────────────┘

109a is the gating refactor; 109b/109c/109e can run parallel after; 109d depends on 109c; 109f closes the loop.

[fedorovvvv]

All 6 sub-issues closed via #118 (merged to develop, commit a6fcaef). 8 forgeplan artifacts activated. Multi-instance management ships in the next release/v* cut.