feat(onboarding-kit): enforce the no-fuze-prefix slug convention + build the migration path

[izzywdev]

Base — read this first

Branched from origin/claude/fuze-registration-gate (PR #518), which is not yet merged, because deliverable 1 extends validate-registration.mjs — a file that exists only on that branch. Merge #518 first; this rebases cleanly onto master afterwards.

This PR's diff therefore contains #518's commit as well, and #518's commit already includes 15 packages/mcp-gateway/** files (src/, test/, tsconfig*, vitest.config.ts, …). That contamination is pre-existing on #518, not introduced here — it disappears from this PR the moment #518 merges.

My own commit (9253884) is clean: 9 files, all under packages/onboarding-kit/, .github/workflows/onboarding-kit-tests.yml and docs/runbooks/. The mcp-gateway work still in flight in the shared checkout was staged by explicit path and deliberately excluded — nothing uncommitted was swept in.

The rule

Every Fuze product registers on FuzeFront without the Fuze prefix — slug service, name Service. FuzePicker already registered as picker, so the convention existed; it was simply never enforced, and twelve products registered against it.

Why this is a migration and not an edit

slug is immutable — PUT /apps/{slug} states that slug, builtin and manifestVersion "are immutable and must match", and the contract has no rename. Correcting a registration is therefore two operations on two rows:

1. POST /apps with the short slug
2. DELETE /apps/{prefixed}

register.sh does step 1 only. A product that de-prefixes its manifest and redeploys ends up registered twice, with the prefixed row still activated and still in the launcher. Twelve products doing that is twelve ghost tiles, and nothing errors.

What's here

1. The gate — validate-registration.mjs. Rejects a slug or name starting with fuze, at authoring time, in the product's own repo.

Deliberately not a pattern on the contract's Slug. Twelve live rows hold prefixed slugs, and both migration steps talk to the registry about those slugs — plus register.sh re-PUTs the manifest on every pod start. A contract-level ban would reject the very requests that repair the damage. Banning a value at the API is only safe when no existing row holds it. So the registry keeps accepting the old value while the migration is in flight, and the kit stops anyone authoring a new one.

2. The tool — bin/migrate-slug.mjs (npx fuzefront-migrate-slug). Dry run by default; idempotent; resumes a half-finished run.

The safety property: the product is never left unregistered. DELETE is the last operation and is guarded by a fresh re-read of the registry — the replacement must be present, at the same status the original had (a suspended app is not silently switched on), with manifest.slug actually correct. Every failure path aborts before the delete, so the worst outcome it can produce is a duplicate tile: visible, harmless, fixed by re-running.

It refuses built-ins (DELETE 403s them, so it could only ever add a permanent duplicate) and suite parents — see below.

3. The runbook — docs/runbooks/app-slug-deprefix-migration.md.

The Permit answer

Changing the slug renames every Permit key the product owns and orphans every grant against the old ones. Nothing errors. Affected users silently lose their roles.

• sync-permit-schema.ts → loadRegisteredPolicyResult() builds each policy as { ...raw, product: row.slug }. The registry slug is the Permit namespace, whatever the policy file's own product field says.
• namespaceKey() joins the slug and the bare key with an underscore, so resource fuzeservice_Ticket becomes service_Ticket and role fuzeservice_agent becomes service_agent.
• Role assignments store the namespaced role key and keep pointing at fuzeservice_agent.
• syncPermitSchema() is get-or-create/update and never deletes, so the old role survives in Permit indefinitely. The assignment stays valid and un-erroring — it grants permissions on a resource type nothing checks any more.
• Runtime checks resolve the namespaced key from the new slug, find no grant, and deny. Fail-closed, which is correct, and exactly why nobody gets an alert.

Is it acceptable? Not as a default, and not on a "probably nobody has grants yet" hand-wave. Two things narrow it, one keeps it real:

1. Platform roles are unaffected. admin/editor/viewer are not namespaced. Org membership and platform admin survive untouched. Only product-declared roles are at risk.
2. In-repo, nothing assigns a product role yet. assignProductRole, checkProductPermission and requireProductPermission have zero call sites anywhere in FuzeFront — the product-role runtime path is declared but not wired here.
3. But FuzeFront is not the only writer. The whole point of PUT /apps/{slug}/policy is that products use their own roles from their own backends. The platform cannot assert the grant count is zero on a product's behalf — it must be measured per product. The runbook gives the query.

The fix is cheap, because of the overlap window. mergeProductPolicy throws only on a key collision, and the old and new namespaces do not collide — so while both slugs are registered, Permit holds both complete namespaces. The remap is a pure add-then-remove with no instant at which a user holds neither role. That is why DELETE is last: it is a Permit reason, not just a portal one.

A second silent loss the brief didn't name

app_installations.app_id references apps.id ON DELETE CASCADE (migration 017). Deleting the prefixed row destroys every personal and organization install of the product. Installs are not in the frozen contract at all (they live on legacy /api/apps/:id/install), so the tool can neither read nor restore them.

Both losses are gated by explicit flags — --apply refuses without --permit-grants and --installs. A dry run warns instead of refusing: the flags gate the delete, not the preview, because a confirmation you must bypass to get any output stops being a decision and becomes a habit.

Scoped out: FuzeHub

fuzehub registers five rows — parent plus four sibling surfaces grouped by an identical nav.suite.id. Migrating the parent alone splits the menu group, leaves four slugs prefixed forever, and moves the product-level policy/billing (which bind to the primary slug) to a row the siblings no longer relate to. Doing it right needs five registrations, four suite-id repoints and five deletes as one atomic operation — and the contract offers no transaction. A simulated transaction across five deletes is precisely where a tool leaves a product showing three tiles.

The tool detects siblings and refuses. FuzeHub is a maintenance-window, human-driven migration, documented as such.

Verified

Check	Result
npm test (kit)	100 checks pass — 16 policy + 31 registration + 34 migration + 19 register.sh behaviours
node scripts/build-schema.mjs --check	clean — the contract is untouched
validate-policy templates/policy.json, validate-registration templates	pass
CLI end to end vs tests/fake-registry.mjs	dry run / refusal / apply / idempotent re-run / typo'd flag all behave correctly

Every migration failure case asserts not just that the tool reported failure but that the old app is still registered afterwards.

templates/manifest.json needed no change — it already uses myapp/MyApp, which is conformant, so the brief's premise there was false. Rather than churn it, I added a regression test pinning the shipped template as conformant, so the gate cannot later be undermined by the one manifest it isn't otherwise run against.

The new suite is wired into .github/workflows/onboarding-kit-tests.yml, so it is gated as hard as register.sh rather than only ever run by hand.

Could NOT verify without a live registry

• The real app-registry service's DELETE /apps/{slug} semantics (403-on-builtin, 204 body, cascade behaviour) — exercised only against fake-registry.mjs, which I extended to match the frozen contract.
• The real GET /apps list shape. listApps() tolerates a bare array, {items} and {apps}; if prod returns something else, suite detection degrades to "unreadable" → refuse, which fails safe.
• Whether any product actually holds Permit grants today. Measurable only with a Permit API key against the live environment.
• The actual app_installations row counts per product.
• The migration was NOT run against any registry. Prod is GitOps and infra is a FuzeInfra delegation.

Owner actions to execute

1. Merge feat: registration fleet-policy gate + OpenAPI→MCP SSE gateway #518, then this.
2. Per product: measure the Permit grants (runbook §2) and capture install rows (§3c).
3. Open the overlap window — redeploy with the de-prefixed manifest, or --apply once 2 is ready.
4. Run the schema sync; confirm /health reports permitSync.outcome == "ok".
5. Remap grants add-then-remove (§3b).
6. --apply --permit-grants --installs.
7. Verify, then hand-delete the orphaned old-namespace keys in Permit (the sync never will).

Do fuzeservice first, alone, and let it sit a day. Not all twelve in one window — a quietly-lost role takes hours to surface and twelve simultaneous migrations make it unattributable. fuzepicker needs no migration (slug already picker; only its display name changes, and name is mutable via the ordinary manifest refresh). fuzecontact and fuzesales need the slug half only.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.