Skip to content

feat(cli): cloudhal import --replace and --revert (#47, step 4) - #132

Merged
Madraka merged 2 commits into
mainfrom
feat/issue-47-replace
Oct 26, 2026
Merged

Madraka merged 2 commits into
mainfrom
feat/issue-47-replace

Conversation

@Madraka

@Madraka Madraka commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

What

Step 4 of RFC-0039's rollout for #47: cloudhal import <file> --replace [--dry-run], the before import snapshot, and the switch to the archive's site id. It also adds cloudhal import --revert <snapshot-id> [--dry-run] as the undo (see "For the owner").

  • --replace
    • The local site's nodes become the archive's, including its published snapshot. This is the same as pull --replace; push still keeps a deployment's own pointer, so a local replace never moves production.
    • When the project already holds the site and its nodes would change, the current graph is saved as before import <file> and the result as import <file>. The summary prints (undo: cloudhal import --revert <id>).
    • A new or unchanged site gets no snapshot. An unchanged site is checked again just before the write; if another process changed it in the meantime, the import is refused.
  • --revert <id>
    • restoreBundle (new, core-ts, Worker-safe) rebuilds the site from that snapshot's stored bodies, and importSite applies it in replace mode. The published snapshot is restored too.
    • The current graph is saved first as before revert import <file>, so a revert can itself be reverted.
    • Revs only move forward, so a Studio tab still holding an old rev gets a conflict instead of silently overwriting.
  • Site id switch: when the archive's site is not listed in cloudhal.json, only siteId and the old id's entry in sites are edited. The layout and other keys stay as written. The edit is atomic, happens after the import has landed, and a concurrent edit of the file is refused. The old site stays in the local store, untouched; writing the old id back undoes the switch. A deployed project gets a warning that its deployment serves the old site. That warning reads only state.json, never the secrets.
  • Refused before anything is written:
    • open releases of the site (cancel them in Studio);
    • an unfinished field operation (RFC-0041);
    • a hostname another local site serves. This is now a refusal that --dry-run reports, for bootstrap imports too.
  • --cancel-schedules is now refused by every command except push.

For the owner

  1. RFC-0039 / ADR-0041 amendments, please review:
    • The undo. RFC §2 says --replace "can be undone with a rollback", but no such rollback exists: Studio's rollback only moves the published pointer, and only to an ancestor of the published snapshot. The before import snapshot is never an ancestor, so --revert was added. It follows the repo's existing --revert <id> pattern (media import-urls, migrate).
    • The published pointer. --replace takes the archive's published pointer, like pull --replace. The issue mentioned "like push --replace" (keep the target's). For a local restore, the archive's pointer is what brings the backup back, and the deployment keeps its own on push.
  2. Rev limitation of --replace: archive nodes keep their revs, as with pull --replace, so the local site equals the archive and later push/pull against its deployment don't conflict. A Studio tab holding the same rev could therefore save over a replaced node without a conflict. The summary and dry run count those nodes and say to reload open tabs. --revert doesn't have this problem because its revs move forward.

Verification (local)

  • packages/core-ts: the full suite passes, 56 files and 1002 tests. That includes the new sync-restore.test.ts and the sqlite and Miniflare D1 behavioural suites.
  • packages/cli: import-replace (14), import-switch (10), import-cli (25), export-cli, cli-commands and archive-* all pass, 206 tests in one process. Two mutation checks confirm the tests catch regressions:
    • writing cloudhal.json before the import fails the switch tests;
    • dropping the recheck of an unchanged site fails its test.
  • Smoke test with the real bin on scratch projects:
    • init → snapshot --publish → export → local edit → import --replace --dry-run (exit 0, shows the snapshots and the pointer change).
    • import --replace, then import --revert <before-id> --dry-run, then --revert: the edit came back and its revs moved forward.
    • A switch into a second project changed cloudhal.json by exactly one line, and site list shows both sites.
  • Typecheck (core-ts, cli), declarations, Biome and pnpm size:check pass.

Checklist

  • pnpm check and cargo test --workspace pass locally. Full core-ts suite plus the CLI pieces that cover this change; there is no Rust or contract change, and CI runs the rest.
  • Contract change? No.
  • User-visible change in a published package? Yes:
    • .changeset/site-archive-replace.md (cli)
    • .changeset/restore-bundle.md (core-ts)
    • site-archive-import.md updated
  • Commits are signed off (git commit -s, DCO)
  • Docs / AGENTS.md updated if behaviour or commands changed. help.ts and the RFC/ADR amendments are updated; the guide comes in step 5.

Refs #47

🤖 Generated with Claude Code

Madraka and others added 2 commits October 26, 2026 04:23
restoreBundle(from, snapshot) rebuilds a site bundle from a snapshot's
stored node bodies, for importSite in replace mode, so a site's working
copy and published pointer can become that snapshot's again (the undo of
`cloudhal import --replace`, RFC-0039). Revs only move forward: a node
the site holds at the snapshot's rev or later, with other content, comes
back at the rev after its current one, so a stale editor gets a conflict.
It lists the media the nodes need and carries the store's takedowns. A
missing or mismatched body is refused before anything is written.
exportSite's output is unchanged; its takedown query and media rule are
shared.

Refs #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
RFC-0039 rollout step 4.

- `import <file> --replace` makes the local site's nodes the archive's,
  its published snapshot included (as pull --replace; push still keeps a
  deployment's own). When it changes a site the project holds, the
  current graph is saved first as `before import <file>` and the result
  as `import <file>`; the summary prints the undo.
- `import --revert <snapshot-id>` brings the site back to such a
  snapshot through restoreBundle and importSite, saving the current graph
  first, so a revert can itself be reverted. Studio's rollback only moves
  the published pointer to an ancestor, which cannot undo a replace.
- An archive of a site cloudhal.json does not list switches siteId (and
  the old id's place in sites), editing only those values once the
  import has landed; the old site stays in the store, untouched.
- Refused before anything is written: open releases, an unfinished
  field operation, a hostname another local site serves.
- --cancel-schedules is now refused by every command but push.

RFC-0039 §2 and invariant 6 and ADR-0041 decision 4 are amended to name
the undo and the published-pointer choice.

Refs #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
@Madraka
Madraka enabled auto-merge October 26, 2026 01:24
@Madraka
Madraka merged commit a95b711 into main Oct 26, 2026
4 checks passed
@Madraka
Madraka deleted the feat/issue-47-replace branch October 26, 2026 01:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant