Skip to content

feat(cli): cloudhal export writes a site archive (#47, step 2) - #130

Merged
3 commits merged into
mainfrom
feat/issue-47-export
Oct 25, 2026
Merged

3 commits merged into
mainfrom
feat/issue-47-export

Conversation

@Madraka

@Madraka Madraka commented Oct 25, 2026

Copy link
Copy Markdown
Contributor

What

This is step 2 of RFC-0039's rollout for #47: cloudhal export [--out <file>] [--site <id>] [--no-media] [--latest-only]. It writes one site of the local project to a .cloudhal file, using the container from #129.

  • Content: exportSite's bundle written as NDJSON parts (project.json, nodes, snapshots, and the blobs those snapshots reference). Media streams from the local blob store and is verified against its SHA-256. The takedown ledger is included; taken-down bytes never are.
  • Default name: <site-slug>-<YYYYMMDD>.cloudhal. The date is the newest row timestamp in the archive, not the clock, so an unchanged site exports to identical bytes (invariant 7 as amended in feat(cli): site archive container for export and import (#47, step 1) #129). If a file with the default name already exists, it is replaced only by the same archive. A different one (an edit later the same day, other flags, a deletion) is refused with a message asking for --out, so a full backup is never silently overwritten by a --no-media or --latest-only export. --out replaces whatever file is there.
  • --site <id>: exports another site, which must be listed in cloudhal.json sites. --site, --no-media and --latest-only are refused on every other command. They live in the shared OPTIONS table, so without that check cloudhal push --site x would have parsed and acted on the main site.
  • --latest-only: keeps only the published and latest snapshots (store.latestSnapshot), plus the blobs and media those snapshots and the current nodes need. It is refused while a field operation is unfinished, because it would drop that operation's before snapshot.
  • Interrupts: Ctrl-C and SIGTERM abort the write and remove the temporary file (exit codes 130 and 143).
  • Summary output: prints the file, its size and counts, and the RFC §4 list of what an archive never holds. It also says plainly that the history names who made each change (see below).
  • Converters: archive-bundle.ts converts a bundle to archive content. archive-reassemble.ts converts archive items back to exactly the SiteBundle that exportSite returns, with strict row checks and fixed error messages that never echo untrusted input. Step 3 (cloudhal import) reuses the second. bundle.media's mediaType is rebuilt from the asset bodies, the same way exportSite builds it.
  • fix(core-ts) (separate commit, its own changeset): importSite now checks a bundle's project row. It must be the site node's project, a valid Project, and its id and rev must match its body. Before this, a crafted bundle (pull, the admin bundle route, the coming import) could plant any projects row.

Known limitation (stated in the module doc): graph rows are held in memory, because exportSite returns a whole bundle and importSite's single batch already limits a site to about 1000 nodes. Media bytes stream.

For the owner

  • RFC-0039 §4 / Security wording. The archive holds no accounts, sessions, roles, keys, comments, readers, analytics, audit log, automations or secrets. But its history does name staff: snapshot actors, asset uploadedBy, block provenance, translation reviews and takedown by carry user or agent ids, and mostly display names. Push and pull carry the same data. The sentence "People and personal data never leave in a file by accident" is therefore not exact. The help text and summary now say this openly. Should the RFC be amended, or should export gain an option to strip actor names? This PR leaves the Accepted RFC text alone.

Verification (local)

  • vitest run archive- export-cli cli-commands in packages/cli: 9 files, 157 tests. They cover:
    • the round trip deep-equals exportSite, and two exports give identical bytes;
    • --no-media, --latest-only (including two snapshots with the same created_at, and an unfinished field operation), and --site (listed and unlisted);
    • the default-name guard and the date (the rows are dated by fake timers);
    • a corrupted media blob leaves no file;
    • Ctrl-C returns 130 with no file and no .partial;
    • foreign flags are refused on other commands;
    • crafted asset bodies and project rows are refused without quoting them.
  • packages/core-ts: sync, multi-site, site-time-zone and entry-gates tests (28) pass with the project-row check.
  • CLI typecheck, declaration build, Biome and pnpm size:check pass.
  • I ran the real bin on a copy of a local test site: tar -tzvf lists manifest.json, project.json, the three parts and one media file, all 0 0, 1970, -rw-r--r--.

Checklist

  • pnpm check and cargo test --workspace pass locally. I ran the pieces that cover this change; CI runs the full set, including the Cloudflare push/pull suites that exercise the project-row check.
  • Contract change? No.
  • User-visible change in a published package? .changeset/site-archive-export.md (@cloudhal/cli patch) and .changeset/bundle-project-row.md (@cloudhal/core-ts patch).
  • Commits are signed off (git commit -s, DCO)
  • Docs / AGENTS.md updated if behaviour or commands changed. help.ts is updated, and the docs site's CLI reference is generated from it. The guide comes in step 5.

Refs #47

🤖 Generated with Claude Code

Madraka and others added 2 commits October 26, 2026 00:42
importSite inserted bundle.project as given when the target lacked it,
so a crafted bundle could plant any projects row. The row must now be the
site node's project, a valid Project, with id and rev matching its body.
Covers pull, the admin bundle route behind push, and the coming
`cloudhal import`.

Refs #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
RFC-0039 rollout step 2. `cloudhal export [--out <file>] [--site <id>]
[--no-media] [--latest-only]` writes one site of the local project to a
.cloudhal file: exportSite's bundle as NDJSON parts, media streamed from
the local blob store and verified, and the takedown ledger.

- Default name <site-slug>-<YYYYMMDD>.cloudhal, dated by the newest row
  it holds (never the clock), so an unchanged site exports identically.
  A file at the default name is replaced only by the same archive; --out
  replaces any.
- --site takes a site listed in cloudhal.json sites; --site, --no-media
  and --latest-only are refused on every other command.
- --latest-only keeps the published and the latest snapshot and what
  they need; refused while a field operation is unfinished.
- Ctrl-C and SIGTERM remove the partial file.
- The summary lists what an archive never holds (RFC-0039 §4) and that
  its history names who made each change.

archive-bundle.ts and archive-reassemble.ts convert a bundle to archive
content and back (step 3's import reuses the second); the tests check
the round trip deep-equals exportSite's bundle.

Refs #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
@Madraka
Madraka enabled auto-merge October 25, 2026 21:43
… test

The seed's clock moves in 20 ms steps, so other snapshots can already
share the newest one's created_at; the test picked the first earlier row
with a larger id instead of the largest, and failed when another tied row
sorted after it (CI on #130).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
@Madraka Madraka closed this pull request by merging all changes into main in e8a558f Oct 25, 2026
@Madraka
Madraka deleted the feat/issue-47-export branch October 25, 2026 23:48
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