Skip to content

docs: site archives guide and starter demo archive (#47, step 5) - #133

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

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

Conversation

@Madraka

@Madraka Madraka commented Oct 26, 2026

Copy link
Copy Markdown
Contributor

What

This is the last step (5) of RFC-0039's rollout. It closes #47. Steps 1–4 were #129, #130, #131 and #132.

  • Guide: a new docs/guides/site-archives.md. It covers:
    • What an archive holds and leaves out. Besides accounts, comments, analytics and secrets, it also leaves out scheduled releases, pending approvals and open edit suggestions; export now prints these too. The guide also says plainly that the history names who made each change.
    • Recipes:
    • Every export/import flag, with real output captured from the bin.
    • --replace and its --revert undo, the site-id switch and its undo, and takedowns.
    • Determinism, untrusted files (pipe through age/gpg for confidentiality), and troubleshooting by message.
  • Wiring:
    • The guide is listed on the docs index and the quickstart. The docs site picks up sidebar, llms.txt and sitemap entries automatically.
    • The CLI-reference test now expects export and import.
    • Short pointers were added in the CLI README, the starter README (commit content/site.cloudhal), installation.md, the threat model (an accepted risk: archives are unsigned) and AGENTS.md (the Layout line, plus pnpm demo:archive).
  • Starter demo archive:
    • packages/cli/test/fixtures/site-archives/starter-blog.cloudhal (2.9 KiB) holds the site cloudhal init seeds plus one published snapshot.
    • pnpm demo:archive writes it with a fixed clock and counter ids, using init's own seeding code. seedStarter was split out of seed-site.ts with no behaviour change.
    • node scripts/demo-archive.ts --check runs in pnpm check and CI. It compares the committed archive's manifest, not its gzip bytes (invariant 7 as amended), and fails when the current code would export something else.
    • .gitattributes marks *.cloudhal as binary, and archives exported inside starters/ are ignored.
    • The fixture is not shipped. Shipping it waits for init --from (Later).
  • RFC-0039 / ADR-0041, step-5 amendment:
    • Graph rows are held in memory on both sides; only the container and the media stream.
    • An import's node set is one atomic batch of at most 1000 statements, as for push and pull. Node bodies, snapshots and the ledger are written in batches of their own: a storage failure between them can leave part of an import, and re-running the import completes it.
    • Streaming and larger imports are added under Later, and the RFC is marked implemented.

For the owner

  • The RFC/ADR amendments above record limits found while building this. Please review them.
  • Not added, for you to decide: the per-site AI settings and usage (ai_settings/ai_usage) and the schedule kill switch and cap (schedule_settings) are not exported either. They could be added to the "never in an archive" list.
  • The guide's "Try it" curl URL points at main, so it works once this merges. npx cloudhal import needs the next CLI release (release PR chore(release): version packages #125).

Verification (local)

  • node scripts/demo-archive.ts --check reports up to date. Two negative tests fail it as expected: a --no-media export swapped in, and a changed node. Regenerating the archive is byte-identical, and tar -tzvf lists 5 entries, all 0 0, 1970.
  • Importing the committed demo into an empty project whose cloudhal.json names site_starter0001 behaves as documented: the dry run lists 9 nodes and 1 snapshot, the import writes them, and a second run prints "nothing to import".
  • @cloudhal/docs: tests (33, including the link checker and the CLI reference), typecheck, and the build (118 pages, guide and llms.txt entry present).
  • packages/cli: 13 files and 208 tests (archive-*, export-cli, import-*, cli-commands, demo-archive) in one process.
  • pnpm lint, pnpm size:check and the CLI typecheck pass. git check-attr reports the fixture as binary.
  • Every command example in the guide was run on scratch projects, and its output matches.

Checklist

  • pnpm check and cargo test --workspace pass locally. I ran the 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? export now also prints scheduled releases, pending approvals and open edit suggestions. That is folded into the still-unreleased .changeset/site-archive-export.md.
  • Commits are signed off (git commit -s, DCO)
  • Docs / AGENTS.md updated if behaviour or commands changed.

Closes #47

🤖 Generated with Claude Code

Madraka and others added 2 commits October 26, 2026 05:55
RFC-0039 rollout step 5, the demo half. packages/cli/test/fixtures/
site-archives/starter-blog.cloudhal is the site `cloudhal init` seeds
plus one published snapshot, written by `pnpm demo:archive` with a fixed
clock and counter ids through init's own seeding code (seedStarter,
split out of seed-site.ts with no behaviour change). `node
scripts/demo-archive.ts --check` (in pnpm check and CI) compares the
committed archive's manifest, never its gzip bytes (invariant 7 as
amended), and fails when the current code would export something else.
.gitattributes marks *.cloudhal binary; archives exported inside a
starter are ignored. The fixture does not ship.

Refs #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
RFC-0039 rollout step 5, the docs half. docs/guides/site-archives.md
covers what an archive holds and leaves out (now also scheduled
releases, pending approvals and open edit suggestions, which export
prints too), backups, moving a site, keeping content in git (fresh
clones and later --replace imports), demos, every export and import
flag with real output, --replace and its --revert undo, the site-id
switch, takedowns, determinism, untrusted files and troubleshooting by
message. It is listed on the docs index and quickstart; the CLI README,
the starter README, installation, the threat model and AGENTS.md point
to it.

RFC-0039 and ADR-0041 record what step 5 found: graph rows are held in
memory and an import is one node batch of at most 1000 statements (as
push and pull), with streaming and larger imports listed under Later;
the RFC is marked implemented.

Closes #47

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: Madraka <[email protected]>
@Madraka
Madraka enabled auto-merge October 26, 2026 02:55
@Madraka
Madraka merged commit fb9dc16 into main Oct 26, 2026
6 checks passed
@Madraka
Madraka deleted the feat/issue-47-docs branch October 26, 2026 03:16
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.

cli: export and import a site as a local bundle file

1 participant