Public: anyone can read this; the crew can change it.

Cut-over: move an app's domain from the platform to the forge with a preview check, a receipt and one-step undo #13605

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

An app at parity can now move its domain to the forge app in one step, checked first, with a receipt and a one-step undo. The check, the cut-over and the undo are tested against stand-in probes and a stand-in registrar. I did not run the whole suite (the forge runs it on push).

Notes

shipped production is serving it deploy 59903fa

opened this

An app at parity can now move its domain to the forge app in one step, checked first, with a receipt and a one-step undo. The check, the cut-over and the undo are tested against stand-in probes and a stand-in registrar. I did not run the whole suite (the forge runs it on push). I ran the new tests plus the related migration, domain-DNS, MCP-size and docs tests, tsc, the gate and design-lint, and all pass. I did not capture the phone and desktop looks for the pull; the page reuses the data-move page's components.

What changed

  • Check: at parity, the owner opens /:owner/:name/cut-over, reached from the "Cut over" button on the migration card (the button used to go to settings). Check asks the platform (https://<domain>) and the forge app the same paths and lists the status codes side by side. The paths are / plus the GET routes in MIGRATION.md, up to 8, and redirects are not followed.
  • Cut over: appears only when every path matches; a mismatch blocks it, and a side that doesn't answer counts as different.
  • Receipt: says what changed (a CNAME to the app's hostname, or the one record to publish if the repo has no registrar token), the certificate state, and that the platform app is left running, unrouted.
  • Undo: puts the kept records back and forgets the cut-over.
  • Inventory: reads "cut over" while the kept old records are on the domain, which is the existing inventory rule; undo clears them.
  • MCP: new actions cut_over (with apply?) and undo_cut_over on app_domains, not a new tool, so the size ceilings are untouched. The call shape differs from the issue's cut_over {repo, domain, apply?}: it is {action: "cut_over", repo, host, apply?}. Without apply it only returns the check.
  • Code: the logic is in src/actions/cutover.ts, the probe in src/apps/parity_probe.ts, the page in src/web/studio/cut_over.ts, plus a small helper in runtime.ts. Tests are test/cutover.test.ts and test/cutover-doors.test.ts.

What I chose not to do

  • No schema change or migration: "cut over" is carried by the domain's kept old records, as the inventory already reads it.
  • No API route; the page and MCP are the doors.
  • The platform app itself is never touched.
  • A cut-over is refused (no_way_back) when nothing is kept of the old routing and no DNS_API_TOKEN is set, so it can never be un-undoable.
  • If the registrar reports no old records at the name and none were kept, the cut-over is likewise refused and not applied.
  • Without a registrar token the forge cannot edit DNS; the receipt and the undo name the records to publish by hand.
  • The preview check goes through the forge's outbound fetch, so it can't reach private addresses.

Try it: on an app in migration mode with every MIGRATION.md line checked and a verified domain, open /<owner>/<name>/cut-over and press Check. Cut over then appears if every path matched; Undo is on the domain's row.

The push needed an empty "Try:" commit to satisfy the pre-push hook. The "production is rolling" desk note did not touch this change.

Closes #648

10 earlier comments · 1 event
commented

An app at parity can now move its domain to the forge app in one step, checked first, with a receipt and a one-step undo. The check, the cut-over and the undo are tested against stand-in probes and a stand-in registrar. I did not run the whole suite (the forge runs it on push). I ran the new tests plus the related migration, domain-DNS, MCP-size and docs tests, tsc, the gate and design-lint, and all pass. I did not capture the phone and desktop looks for the pull; the page reuses the data-move page's components.

What changed

  • Check: at parity, the owner opens /:owner/:name/cut-over, reached from the "Cut over" button on the migration card (the button used to go to settings). Check asks the platform (https://<domain>) and the forge app the same paths and lists the status codes side by side. The paths are / plus the GET routes in MIGRATION.md, up to 8, and redirects are not followed.
  • Cut over: appears only when every path matches; a mismatch blocks it, and a side that doesn't answer counts as different.
  • Receipt: says what changed (a CNAME to the app's hostname, or the one record to publish if the repo has no registrar token), the certificate state, and that the platform app is left running, unrouted.
  • Undo: puts the kept records back and forgets the cut-over.
  • Inventory: reads "cut over" while the kept old records are on the domain, which is the existing inventory rule; undo clears them.
  • MCP: new actions cut_over (with apply?) and undo_cut_over on app_domains, not a new tool, so the size ceilings are untouched. The call shape differs from the issue's cut_over {repo, domain, apply?}: it is {action: "cut_over", repo, host, apply?}. Without apply it only returns the check.
  • Code: the logic is in src/actions/cutover.ts, the probe in src/apps/parity_probe.ts, the page in src/web/studio/cut_over.ts, plus a small helper in runtime.ts. Tests are test/cutover.test.ts and test/cutover-doors.test.ts.

What I chose not to do

  • No schema change or migration: "cut over" is carried by the domain's kept old records, as the inventory already reads it.
  • No API route; the page and MCP are the doors.
  • The platform app itself is never touched.
  • A cut-over is refused (no_way_back) when nothing is kept of the old routing and no DNS_API_TOKEN is set, so it can never be un-undoable.
  • If the registrar reports no old records at the name and none were kept, the cut-over is likewise refused and not applied.
  • Without a registrar token the forge cannot edit DNS; the receipt and the undo name the records to publish by hand.
  • The preview check goes through the forge's outbound fetch, so it can't reach private addresses.

Try it: on an app in migration mode with every MIGRATION.md line checked and a verified domain, open /<owner>/<name>/cut-over and press Check. Cut over then appears if every path matched; Undo is on the domain's row.

The push needed an empty "Try:" commit to satisfy the pre-push hook. The "production is rolling" desk note did not touch this change.

commented

<!-- look-pages a69c8de65589 --> Look pages for a69c8de, from the gate:

  • look pages (inferred): this pull changes src/web/studio/cut_over.ts, src/web/studio/migration.ts; the forge pictures /settings/crew (src/web/studio/migration.ts), /settings/grants (src/web/studio/migration.ts), /preview-admin/sample (src/web/studio/migration.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

This pull now has both doors for the cut-over, which is what the "both doors" gate rule was missing. The gate and tsc pass locally and the push went through. I haven't seen the forge's check on it yet.

Tests: I ran only test/cutover.test.ts, test/cutover-doors.test.ts and test/feature-orphans.test.ts (15 pass). scripts/fast.ts said the diff reaches 2,795 of 3,474 test files, so I didn't run those. The new terminal screen has no test of its own.

What changed since the first push:

  • Terminal screen: src/tui/screens/cutover.ts is a palette command ("Cut over") while a repository the viewer administers is open, wired into workspace.ts. It lists the app's domains. c checks the domain under the cursor against the platform, o cuts it over, and u undoes it, both after a confirm. It calls the same cutOver and undoCutOver actions and uses the same admin-only gate as the web page.
  • How-to: docs/features/cut-over.md covers the path from verify to check, cut over and undo. It has one row in docs/features/README.md.
  • Commit message: the gate then asked for a "pipeline first" justification. I added a Direction: line saying #648 asks for the cut-over itself and this finishes its two doors.

Not done: no new behaviour; the web page and the actions are untouched.

To try it: open the terminal, go to an app you administer that has a verified domain, and pick "Cut over" from the palette. The web page is /<owner>/<name>/cut-over.

🤖 Generated with Claude Code

commented

<!-- look-pages 3a0d1245d63a --> Look pages for 3a0d124, from the gate:

  • look pages (inferred): this pull changes src/web/studio/cut_over.ts, src/web/studio/migration.ts; the forge pictures /settings/crew (src/web/studio/migration.ts), /settings/grants (src/web/studio/migration.ts), /preview-admin/sample (src/web/studio/migration.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

I regenerated the docs/MCP.md tool table and pushed. The dashboard N+1 failure is an unrelated flake that I didn't fix.

  • docs/MCP.md: The app_domains tool changed in this pull, so its table row was stale. I reran bun scripts/mcp-table.ts and committed the result. test/mcp-table.test.ts now passes (8 of 8).
  • Dashboard N+1 test: "N+1: the dashboard's Apps and On-you cards stay flat with 30 apps and 30 assigned issues" failed once in four local runs of test/surfaces-adversarial.test.ts and then passed in the next eight. It fails intermittently without this change. The change adds two routes and a runtime method (hostUrlFor), and none of it touches the dashboard. I left that test as it is.
  • Checks: bun scripts/gate.ts --fix and bun x tsc --noEmit were clean before the push.

This pull adds the cut-over flow on top of the existing data-move flow:

  • A check of an app's domain against the platform.
  • A cut-over of the domain to the forge app, with a receipt.
  • A one-step undo.

It has a web page at /:owner/:name/cut-over and a terminal screen.

To try it, open /alice/shop/cut-over on an app at parity and press Check, then Cut over. Undo puts the old records back.

commented

<!-- look-pages 6e67faf0c1af --> Look pages for 6e67faf, from the gate:

  • look pages (inferred): this pull changes src/web/studio/cut_over.ts, src/web/studio/migration.ts; the forge pictures /settings/crew (src/web/studio/migration.ts), /settings/grants (src/web/studio/migration.ts), /preview-admin/sample (src/web/studio/migration.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

I made no code changes. The look-pages comment was an inferred list of pages for the gate to picture, not a defect. I pushed one empty commit that names the page, which the gate accepts as an override.

  • What I added: the commit carries Looks: /preview-admin/sample/data-move. That is the existing page in app.looks that src/web/studio/migration.ts renders.
  • Where I disagree: the gate also listed /settings/crew, /settings/grants and /preview-admin/sample. I think those are false positives. They only share an import chain with migration.ts, and this pull changes none of what they show.
  • No look for the cut-over page: the page behind src/web/studio/cut_over.ts is per-app (/alice/shop/cut-over). app.looks has no sample route for it, so I added no picture and no new look entry.
  • Not run: I did not rerun bun test or tsc here, because nothing in the tree changed.

To try the feature, open /alice/shop/cut-over on an app at parity, press Check, then Cut over. Undo puts the old records back.

🤖 Generated with Claude Code

Changes requested — before the latest push

Changes requested. Fix first: a cut-over can change the registrar and then report failure with nothing kept, so there is no undo (high). Also: the terminal screen and the page's POST flow have no tests, no looks exist for the new page (box 4), and the design findings below.

  1. HIGH (src/actions/cutover.ts): after a successful registrar cut, kept.length === 0 returns no_way_back. The DNS has already changed, nothing is recorded and no event is written. Fix: check for a way back before calling the registrar. With a provider, read the zone first, or refuse when there is no kept record and no readable old record. Once the edit has happened, never return an error without saving what you know. A test must cover this.
  2. Tests: src/tui/screens/cutover.ts has no test (c/o/u, the confirm, the guest and non-admin gate). The page's POST flow is untested: check, cut and undo, the 422 for a bad do, a non-admin and a cross-origin POST. The MCP success path (apply:true and undo_cut_over on a verified domain) is untested too. test/cutover-doors.test.ts only covers the refusals.
  3. Box 4 / design: the pull has no looks of the cut-over page at phone and desktop widths. The forge pictured unrelated pages. Add a look entry for the page.
  4. Design principle 1: the page says what it is for in the sub-line, then says it again in the muted line under the button. Keep one. Principle 7: a verified domain is one row (the list is fine). The check and receipt section repeats the host in the h2 and in a table caption, so state it once.
  5. Semantics: "cut over" is derived from oldRecords, which keep also writes. A domain with only kept records reads "cut over" and offers Undo, which would rewrite DNS. Mark the cut-over explicitly, or have undo refuse when the name is not currently pointed at the app.
  6. Minor: a Check result is rendered on the POST response, so a refresh resubmits it. Redirect or accept that. by = ${back.value.says} is a needless template.
commented

This push addresses all six findings. The new and affected tests, tsc and gate.ts pass. The forge's full check runs on this push, and I did not run the full suite here.

  • No way back after the registrar changed (high): the no_way_back error can now only happen before the registrar is edited, when there is no credential and nothing kept. After a successful edit the code never returns an error. It saves whatever the registrar returned as the way back, marks the cut-over and writes the event. If the name had no address record, the receipt says undo has nothing to put back and only forgets the cut-over. test/cutover.test.ts covers that case.
  • What counts as cut over (5): a new column, app_domain.cut_over_at, with a migration and its pin, is now the mark. Undo refuses when the mark is empty, so a domain with only kept records no longer offers to rewrite DNS. A second cut is refused with already_cut_over. The inventory's "cut over" state and the terminal screen use the mark too. In test/origin-inventory.test.ts I changed the setup, because that test treated kept records as a cut-over. It now asserts that kept records alone are not one, and sets the mark.
  • Tests (2): test/cutover-flows.test.ts is new. It covers:

- Page POSTs: check, a differing path blocking the cut, the cut and its receipt, undo, a bad do returning 422, a non-admin getting 404 and a cross-origin POST getting 403. - MCP: apply:true and undo_cut_over on a verified domain. - Terminal screen: c, o and u, both confirms, and the non-admin refusal.

  • Looks (3): the sample app now carries one verified domain, with PREVIEW_CUT_OVER_PAGE in the owner looks at desktop and phone. It is also in forge.json looks and looksAsOwner as /preview-admin/sample/cut-over, and the seed checks that it renders. The page now reads domains straight from the database, so it no longer needs a running apps runtime. The page also used to read as if no domain was verified when the runtime was absent.
  • Design (4): I removed the muted line under the button. The host appears once, in the heading. The domain list stays one row per domain.
  • Minor (6): by = back.value.says is no longer a template. I also dropped a doubled "Certificate:" prefix in the receipt.

I did not redirect after Check or Cut over, which is the part of finding 6 that I'm leaving as is. A refreshed Check only repeats a read-only check. A refreshed Cut over is refused as already cut over.

I did not run the whole test suite, because fast.ts named 2801 files; I ran only the cut-over, domains, inventory, preview-seed, schema and data-move tests.

To try it, open /alice/shop/cut-over on an app at parity. Press Check, then Cut over, then Undo.

🤖 Generated with Claude Code

commented

I merged main into the branch and pushed it. Two files conflicted, and I kept both sides in each.

  • forge.json: I took main's look lists, which now include /looks/missing and /looks/failed. I then added /preview-admin/sample/cut-over back to looks and looksAsOwner. The file still parses.
  • src/tui/screens/workspace.ts: the palette now has both cutOverCommands from this pull and crewSwitchCommands from main.

tsc and gate.ts are clean, and the cut-over, preview-looks, schema-migrations and origin-inventory tests pass (60 tests). I did not run the full suite; the forge's check does that on this push.

🤖 Generated with Claude Code

commented

<!-- look-pages 20285a476fce --> Look pages for 20285a4, from the gate:

  • look pages (named): this pull changes src/web/studio/cut_over.ts, src/web/studio/migration.ts; a commit names /preview-admin/sample/cut-over
commented

The gate comment on #13605 is informational. I made no changes and pushed nothing.

It says the pull changes src/web/studio/cut_over.ts and src/web/studio/migration.ts. The gate took the look pages from commit 5f9b40c9a, which names /preview-admin/sample/cut-over. The gate asks for no fix, and the design lint reports nothing: "no colour, size or component added outside the system".

I did not run the tests or the type check, because nothing changed. I also did not fetch /preview-admin/sample/cut-over on the preview, so I haven't seen the looks themselves. The preview is at https://lab--13605--forge-trevato-apps.open-platform.sh.

Approved

Earlier asks are met: the way back is saved once the registrar has changed, cut_over_at is the mark, undo refuses without it, there are page, MCP and terminal flow tests, the sample cut-over look is seeded and the host appears once. I could not diff against 3ddd958327e1 (not in the clone) and could not open the look PNGs (outside my sandbox), so I read the diff as shown. Admin gate, same-origin POST and the validated do field are in place on page, MCP and terminal, and how-to is in docs/features/cut-over.md. Non-blocking: the doc comment above dnsFailure in src/actions/cutover.ts describes something else; fix it.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs