Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/restore-bundle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@cloudhal/core-ts": patch
---

New `restoreBundle(from, snapshot)`: a site bundle of one snapshot's nodes, rebuilt from the stored node bodies, for `importSite(…, { mode: "replace" })`, which checks it like any bundle. The site's working copy and published pointer become that snapshot's again (`cloudhal import --revert`, RFC-0039). Revs only move forward: a node the site holds at the snapshot's rev or a later one, with other content, comes back at the rev after its current one, so a Studio tab or agent still holding a rev that node had gets a conflict instead of saving over it; a node whose content already is the snapshot's is left as it is. It lists the media those nodes need and carries the store's takedowns among them, so taken-down content stays down; a missing node body, or one that is not the node its snapshot ref names, is refused before anything is written. `exportSite`'s output is unchanged.
2 changes: 1 addition & 1 deletion .changeset/site-archive-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
New `cloudhal import <file> [--dry-run]` (RFC-0039, #47) reads a `.cloudhal` file written by `cloudhal export` into the local project, keeping the site's id.

- It reads the file twice. First it verifies every file's size and SHA-256, every row and every node body (each must be the node its snapshot refs name), and checks the archive against the project. A damaged or edited file, invalid content, an archive of another site, a site whose nodes differ, or missing media is therefore refused before anything is written. Then it reads the file again, refusing it if it changed in between, copies the media the project lacks and imports the graph, keeping the archive's published snapshot as `cloudhal pull` does.
- Only bootstrap imports for now. The archive's site must be `cloudhal.json`'s `siteId` or listed in `sites`, and the project must not hold it yet or hold exactly its nodes; missing snapshots, node bodies and media are added. A site whose nodes differ is refused; `--replace` is not available yet.
- By default a bootstrap import. The archive's site must be `cloudhal.json`'s `siteId` or listed in `sites`, and the project must not hold it yet or hold exactly its nodes; missing snapshots, node bodies and media are added. A site whose nodes differ is refused; `--replace` replaces them (see its own note).
- An archive written with `--no-media` imports only when the project already has its media.
- Taken-down content stays down: the archive's takedowns are recorded and their bytes never written, a local copy of content the archive's ledger took down is deleted (the summary says how many), and an archive carrying content this project has taken down is refused.
- `--dry-run` prints the manifest and what the import would add, change or remove (nodes by kind and title, snapshots, media to copy), writes nothing, and exits 1 when the import would be refused.
Expand Down
13 changes: 13 additions & 0 deletions .changeset/site-archive-replace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
"@cloudhal/cli": patch
---

`cloudhal import <file> --replace [--dry-run]` (RFC-0039 rollout step 4, #47) makes the local site's nodes the archive's, its published snapshot included, as `cloudhal pull --replace` does. `cloudhal push` still keeps a deployment's own published snapshot, so a local replace never moves production. Snapshots are only ever added.

- When it changes a site the project already holds, the current graph is saved first as a snapshot labelled `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; a site the plan found unchanged is checked again just before the write, and refused if another process changed it meanwhile. A run that stopped after the first snapshot reuses it the next time.
- The archive's nodes keep their revs, as with `pull --replace`. A Studio tab or agent still holding a node at the rev the archive gives it can save over it without a conflict, so the summary counts those nodes and says to reload open Studio tabs.
- New `cloudhal import --revert <snapshot-id> [--dry-run]` brings the site back to a `before import` snapshot, its published snapshot included, saving the current graph first as `before revert import <file>`, so a revert can itself be reverted. Its revs only move forward: a node edited since comes back at the rev after its current one, so a stale editor gets a conflict. Studio's rollback only moves the published pointer to an earlier snapshot, which cannot undo a replace.
- An archive of a site `cloudhal.json` does not list switches its `siteId`, and the old id's place in `sites`, to the archive's, editing only those values in the file (layout and other keys stay as written), once the import has landed. The old site stays in the local store, unlisted and untouched; writing the old id back by hand undoes the switch (`--revert` restores nodes only), and the summary names `cloudhal site delete` to remove the old site for good. A deployed project is warned that its deployment serves the old site, and that a deployment of the imported site is updated from the project that deployed it.
- Refused before anything is written: open releases of the site (cancel them in Studio), an unfinished field operation, a hostname another local site serves (now a refusal `--dry-run` reports, for bootstrap imports too), and an archive site id `cloudhal.json` cannot name.
- `--dry-run` shows the snapshots it would take, the published-snapshot change and the `cloudhal.json` change; it exits 0, or 1 when the import would be refused.
- `--cancel-schedules` is now refused by every command but `cloudhal push`.
3 changes: 2 additions & 1 deletion docs/adr/0041-site-archives.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
- Status: Accepted
- Date: 2026-10-22 (decided by Halil)
- Amendment (2026-10-25, RFC-0039 rollout step 1): deterministic bytes hold for the same Node/zlib build; the tar stream and the manifest's SHA-256s on every platform. See rule 6.
- Amendment (2026-10-26, RFC-0039 rollout step 4): `--replace` takes the archive's published snapshot (a deployment keeps its own on `push`) and is undone with `cloudhal import --revert <snapshot-id>`, which restores the `before import` snapshot. See decision 4.
- Related: RFC-0039, RFC-0004, RFC-0010, ADR-0002, #47
- Sources: [Sanity datasets](https://www.sanity.io/docs/cli-reference/dataset) · [Strapi data management](https://docs.strapi.io/cms/data-management/export) · [Contentful CLI export](https://github.com/contentful/contentful-cli/tree/main/docs/space/export) · [Ghost migration](https://docs.ghost.org/migration/ghost) · [WordPress export](https://wordpress.org/documentation/article/tools-export-screen/)

Expand All @@ -14,7 +15,7 @@ A site's content can only leave a project through a deployment (`push`, `pull`),
3. **Ids are kept.** An imported site is the same site.
4. **Import modes:**
- bootstrap (default): adds what is missing and refuses differing nodes;
- `--replace`: first saves the current graph as a `before import` snapshot, so the import can be undone;
- `--replace`: first saves the current graph as a `before import` snapshot, so the import can be undone (amended: with `cloudhal import --revert <snapshot-id>`, a site id switch by writing the old `siteId` back; the published snapshot becomes the archive's);
- `--dry-run`: shows the difference and writes nothing.

Never erase-then-import.
Expand Down
13 changes: 11 additions & 2 deletions docs/rfcs/0039-site-archive-export-import.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

- Status: Accepted (2026-10-22, by Halil; ADR-0041). Open questions decided as recommended. Revised before acceptance after a comparison with Sanity, Strapi, Contentful, Ghost, WordPress, Directus and Webflow (see Prior art): NDJSON parts instead of one JSON file, per-file checksums, contract versions in the manifest, and a snapshot before `--replace`.
- Amendment (2026-10-25, rollout step 1): identical `.cloudhal` bytes need the same Node/zlib build; the tar stream inside, and so every SHA-256 in the manifest, is identical on every platform. See invariant 7.
- Amendment (2026-10-26, rollout step 4): `--replace` takes the archive's published snapshot (the site node carries it, as `pull --replace`; `push` keeps a deployment's own); it saves `before import <file>` and the result as `import <file>`; the "rollback" that undoes it is `cloudhal import --revert <snapshot-id>`, since Studio's rollback moves only the published pointer, to an ancestor; and `cloudhal site delete` already deletes a local site. See §2 and invariant 6.
- Author: Halil (Madraka), drafted with Claude · Date: 2026-10-21
- Related:
- #47 (found while building cloudhal.com: no way to keep or move a site's content without a deployment, so it was written as code).
Expand Down Expand Up @@ -69,6 +70,7 @@ interface SiteArchiveManifest {
```text
cloudhal export [--out <file>] [--site <id>] [--no-media] [--latest-only]
cloudhal import <file> [--replace] [--dry-run]
cloudhal import --revert <snapshot-id> [--dry-run] (amended 2026-10-26)
```

- **export:**
Expand All @@ -79,6 +81,13 @@ cloudhal import <file> [--replace] [--dry-run]
- **import:** checks the manifest and every file's SHA-256 as it streams (media files are named by their hash as well), then calls `importSite`. Three modes:
- **bootstrap** (default), into a project with no site or one whose site is the archive's (same `siteId`). Like `pull`, it adds what is missing and refuses nodes that differ: never Strapi's "erase the target first".
- **`--replace`:** the local nodes become the archive's. Snapshots are only ever added. First, the current local graph is saved as a snapshot labelled `before import <file>`, so the import can be undone with a rollback. Into a project whose site has another id, `--replace` switches `cloudhal.json`'s `siteId` to the archive's. The old site stays in the local store, unlisted; there is no command to delete a local site yet.
*Amended 2026-10-26 (rollout step 4):*
- The published snapshot is the archive's: the site node carries it, so `--replace` takes it as `pull --replace` does. A deployment keeps its own, since `push` applies with the deployment's pointer.
- The snapshot is taken only when the project holds the site and its nodes would change (none for a new or unchanged site), with the file's base name; the result is saved as `import <file>` right after, so the latest snapshot is the imported graph.
- The undo is `cloudhal import --revert <snapshot-id>`: it restores that snapshot's nodes, the site node and so its published snapshot included, through `importSite`'s replace, saving the current graph first as `before revert import <file>`. Studio's rollback only moves the published pointer to an ancestor of the published snapshot, which a `before import` snapshot is not.
- Revs: the store's compare-and-swap checks only a node's rev. `--revert` moves revs forward (a node edited since comes back at the rev after its current one), so a Studio tab or agent holding a rev the node had gets a conflict. `--replace` keeps the archive's revs, as `pull --replace` does, so the local site equals the archive; its summary counts the nodes given a rev no higher than they had, which such an editor could save over, and says to reload.
- The switch edits only `siteId` and the old id's entry in `sites`, after the import has landed. It is undone by writing the old id back by hand: the old site is untouched, and `--revert` restores nodes only. `cloudhal site delete <id> --confirm <slug>` deletes the old site for good.
- Refused before anything is written: open releases (their pinned versions point into the replaced graph; cancelled in Studio, no `--cancel-schedules` here), an unfinished field operation (RFC-0041; its marker is on the site node), and a hostname another local site serves (never released: that would write the old site).
- **`--dry-run`:** prints the manifest and the difference the import would make (nodes added, changed and removed by kind and title; snapshots added; media to copy) and writes nothing.

### 3. Invariants
Expand All @@ -88,7 +97,7 @@ cloudhal import <file> [--replace] [--dry-run]
3. Every file is verified against the manifest (SHA-256 and size), and every media file against its own name, before it is used. A missing or wrong file fails the import before any node is written (the bundle's `missing_media` rule).
4. An archive written by a newer format or a newer contracts `schemaVersion` is refused with the CLI version needed. Older ones are read, and migrated forward if a later schema version requires it.
5. Taken-down content stays taken down: the `purged` ledger travels and the import never restores those bytes.
6. Import writes the graph in atomic batches (no interactive transactions, AGENTS.md rule 4), guarded like `importSite` today. A failure leaves the project as it was, and `--replace` can always be undone through its `before import` snapshot.
6. Import writes the graph in atomic batches (no interactive transactions, AGENTS.md rule 4), guarded like `importSite` today. A failure leaves the project as it was, and `--replace` can always be undone through its `before import` snapshot. *Amended 2026-10-26:* with `cloudhal import --revert <snapshot-id>` (§2), and a site id switch by writing the old `siteId` back (the old site is untouched); a failure after that snapshot was taken leaves it, holding the graph as it was, and the message names it.
7. Same content, same file: rows and files are written in a fixed order, with zero timestamps and fixed modes in the tar headers, so exporting an unchanged site twice gives identical bytes (good for git and for diffing). *Amended 2026-10-25:* identical bytes hold for the same Node/zlib build. gzip output differs between zlib builds (Homebrew's zlib and the Chromium zlib that official Node binaries ship compress the same input differently), and only a dependency or uncompressed output would avoid that. The tar stream inside the gzip, and so every SHA-256 in the manifest, is identical on every platform. A committed archive (step 5's demo) is regenerated on one pinned Node in CI, or compared through its decompressed tar.

### 4. What is not in an archive
Expand Down Expand Up @@ -125,7 +134,7 @@ The manifest says so, and `export` prints it. People and personal data never lea
1. The streaming tar writer and reader, with tests (round trip, damaged file, wrong hash, path traversal, deterministic bytes).
2. `export`.
3. `import` with `--dry-run`.
4. `--replace`, the `before import` snapshot, and the site id switch.
4. `--replace`, the `before import` snapshot, and the site id switch. *Amended 2026-10-26:* with `import --revert` as the undo.
5. Docs and a starter demo archive (regenerated on one pinned Node, or compared through its decompressed tar: invariant 7).

## Security & policy impact
Expand Down
1 change: 1 addition & 0 deletions packages/cli/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,7 @@ const ONLY_FOR: Readonly<
site: { commands: ["export"], note: "; every other command acts on cloudhal.json's siteId" },
"no-media": { commands: ["export"] },
"latest-only": { commands: ["export"] },
"cancel-schedules": { commands: ["push"] },
};

function refuseForeignFlags(command: string, values: Record<string, unknown>): void {
Expand Down
33 changes: 23 additions & 10 deletions packages/cli/src/cli/commands-content.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ import {
import { describeExport, exportArchive } from "../commands/export.ts";
import { fieldsCommand } from "../commands/fields.ts";
import { ImportInterruptedError, importArchive } from "../commands/import.ts";
import { describeImport } from "../commands/import-describe.ts";
import { describeImport, describeRevert } from "../commands/import-describe.ts";
import { revertImport } from "../commands/import-revert.ts";
import { describeMediaImport, mediaGc, mediaImportUrls, mediaVerify } from "../commands/media.ts";
import { describePlaceholders, mediaPlaceholders } from "../commands/media-placeholders.ts";
import { describeMigration, migrateTags } from "../commands/migrate.ts";
Expand Down Expand Up @@ -171,25 +172,37 @@ const exportCommand: CliCommand = async (rest, values, { projectDir }) => {
}
};

const IMPORT_USAGE =
"usage: cloudhal import <file> [--replace] [--dry-run] | --revert <snapshot-id> [--dry-run]";

/** `cloudhal import --revert <snapshot-id> [--dry-run]`; a dry run that would be refused exits 1. */
const revertCommand: CliCommand = async (rest, values, { projectDir }) => {
if (rest.length > 0 || values.replace || !values.revert) throw new Error(IMPORT_USAGE);
const result = await revertImport({
projectDir,
snapshotId: values.revert,
dryRun: values["dry-run"] === true,
});
for (const line of describeRevert(result)) console.log(line);
return result.refusals.length > 0 ? 1 : 0;
};

/**
* `cloudhal import <file> [--dry-run]` (bootstrap only; `--replace` is RFC-0039 step 4). Ctrl-C or
* `cloudhal import <file> [--replace] [--dry-run]` (RFC-0039 §2), or `--revert <id>`. Ctrl-C or
* SIGTERM before the graph is written stops it (exit 130/143); a dry run that would be refused
* exits 1.
*/
const importCommand: CliCommand = async (rest, values, { projectDir }) => {
const importCommand: CliCommand = async (rest, values, context) => {
if (values.revert !== undefined) return revertCommand(rest, values, context);
const [file] = rest;
if (file === undefined || rest.length !== 1)
throw new Error("usage: cloudhal import <file> [--dry-run]");
if (values.replace)
throw new Error(
"cloudhal import --replace is not available yet; this version imports in bootstrap mode only",
);
if (file === undefined || rest.length !== 1) throw new Error(IMPORT_USAGE);
const interrupt = abortOnSignal();
try {
const result = await importArchive({
projectDir,
projectDir: context.projectDir,
file,
dryRun: values["dry-run"] === true,
replace: values.replace === true,
signal: interrupt.signal,
log: (l) => process.stderr.write(`${l}\n`),
});
Expand Down
Loading
Loading