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
2 changes: 1 addition & 1 deletion .changeset/site-archive-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@ New `cloudhal export` (RFC-0039, #47) writes one site of the local project to a
- `--no-media` writes the graph only.
- `--latest-only` keeps only the published and the latest snapshot, and only the media they and the current content need. It is refused while a field operation is unfinished (`cloudhal fields continue|revert`).

A damaged or missing local media file stops the export (run `cloudhal media verify`); so do Ctrl-C and SIGTERM. Either way no file is written and an existing one is left as it was. Exporting an unchanged site again with the same CLI and Node version gives the same bytes. An archive never contains user accounts, sessions, roles, agent keys, comments, readers, analytics, the audit log, automations, schedule runs, deployment secrets or webhook credentials. Its history does name who made each change (the user or agent of each snapshot, upload, block edit, review and takedown).
A damaged or missing local media file stops the export (run `cloudhal media verify`); so do Ctrl-C and SIGTERM. Either way no file is written and an existing one is left as it was. Exporting an unchanged site again with the same CLI and Node version gives the same bytes. An archive never contains user accounts, sessions, roles, agent keys, comments, readers, analytics, the audit log, scheduled releases, automations, schedule runs, pending approvals, open edit suggestions, deployment secrets or webhook credentials, and the export prints this list. Its history does name who made each change (the user or agent of each snapshot, upload, block edit, review and takedown).
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# RFC-0039 site archives are gzip-compressed tar files: never convert line endings, diff or merge them.
*.cloudhal binary
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ jobs:
- run: pnpm size:check
- run: node scripts/font-fallbacks.ts --check
- run: node scripts/mcp-tools-doc.ts --check
# RFC-0039 invariant 7: the committed demo archive's content (its manifest), not its gzip bytes.
- run: node scripts/demo-archive.ts --check
- run: pnpm turbo run typecheck
# Each vitest starts a worker per core; more than two packages at once oversubscribes the
# 4-vCPU runner and slow tests (auth, D1, workerd) hit their timeouts.
Expand Down
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ packages/core-contracts/schemas/.bundled/

# The starters' own local site (a project created from a starter commits its cloudhal.json)
starters/*/cloudhal.json
# and its site archives (`cloudhal export` in a starter; a user project may commit its own)
starters/**/*.cloudhal

# Package build output
.build/
Expand Down
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ cargo clippy --workspace --all-targets -- -D warnings
pnpm gen # JSON Schema → TypeScript + Rust (requires cargo-typify 0.8.0)
pnpm drift # gen + fail if generated files changed
pnpm changeset # add a release note for a published package
pnpm demo:archive # regenerate the starter demo archive (RFC-0039; --check runs in pnpm check)
pnpm design:lint [files…] # Kumo design rules for apps/studio + packages/ui blocks (also a Claude Code hook)
pnpm design:shots -- <routes> # headless screenshots at 1440/390 px; fails on sideways scroll / console errors
pnpm kumo ls|doc <Name>|blocks|add <Block>|ai # Kumo CLI: component list, API docs, blocks, usage guide
Expand All @@ -30,7 +31,7 @@ pnpm i18n:export / pnpm i18n:import [--locale xx] # translations as nested ICU
- `packages/core-ts` — `SiteGraphStore` (CAS on `rev`, snapshots, diff, publish, rollback). Behavioural suite in `src/testing.ts` runs on sqlite and Miniflare D1. `./local` opens the offline store; `seedStarterSite` seeds a demo. `./surfaces` is RFC-0020's generative UI: the catalog (primitives + block types), eval-free surface checks, bindings, repairs, JSON Patch (`patchPage`), `catalogPrompt`; `./interop` converts A2UI v0.9 and json-render to and from surfaces; `./design` is RFC-0021's DESIGN.md lint and guidance. `./fields` is RFC-0041's typed custom fields (definition and value checks, `resolveFields`, `formatFieldValue`, the agents' JSON Schema, the conversion table); `src/fields-operations/` runs rename/retype/localize/remove. `search.ts` is RFC-0019's FTS5 site search (index written with the publish batch; articles, pages, terms and authors, RFC-0029); `search-provider.ts` is RFC-0029's `SearchProvider` (`fts5`, `memory`, `withFallback`), set with `SiteGraphStoreOptions.search`; `search-ai.ts` is the experimental Cloudflare AI Search provider (`hybridProvider`, `searchProviderFromEnv`, `cloudhal.json` `search`, docs/guides/search.md).
- `packages/schedules` — RFC-0008: time model (only `temporal-polyfill/implementation`, `now` injected, never `Temporal.Now`), RRULE subset, release model (`rl1:`), automation/run state, taint and budgets, `runDue`; `./sql` is `SqlScheduleStore`, `./engine` the Temporal-free part core-ts and the site Worker use. Worker-safe; conformance suites in `src/testing.ts` on sqlite and Miniflare D1.
- `packages/astro-renderer` — `GraphSource` (live/snapshot), `cloudhal()` integration (virtual config + dev route-cache watcher), `.astro` section components (`Surface.astro` for RFC-0020 surfaces; `./surfaces` renders them, `./kit` has the table of contents and reading time; `./fields` and `EntryFields.astro` render typed field values, RFC-0041). Routes live in starters, not here.
- `packages/cli` — the `cloudhal` CLI (`init`, `dev`, `studio`, `mcp`, `deploy`, `push`, `pull`, …; every command is in `src/cli/help.ts`, which `cloudhal --help` prints and the docs site's CLI reference is generated from); TS bin run by Node 24 type stripping. `src/cli.ts` parses flags and dispatches through `COMMANDS`, built from `src/cli/commands-{local,remote,content,ops,site}.ts` (a new command is one handler plus one line in `src/cli/help.ts`). E2E test spawns the bin (Astro disables dev middleware under `VITEST`). Cloudflare tests run both Workers on workerd via wrangler's `createTestHarness`; test files run serially (shared starter caches).
- `packages/cli` — the `cloudhal` CLI (`init`, `dev`, `studio`, `mcp`, `deploy`, `push`, `pull`, `export`, `import`, …; every command is in `src/cli/help.ts`, which `cloudhal --help` prints and the docs site's CLI reference is generated from); TS bin run by Node 24 type stripping. `src/cli.ts` parses flags and dispatches through `COMMANDS`, built from `src/cli/commands-{local,remote,content,ops,site}.ts` (a new command is one handler plus one line in `src/cli/help.ts`). `src/archive/` is RFC-0039's `.cloudhal` container (tar, gzip, manifest, limits), read and written by `src/commands/export.ts` and `import*.ts` (`archive-bundle.ts`, `archive-reassemble.ts`); the starter demo archive `test/fixtures/site-archives/starter-blog.cloudhal` is written by `pnpm demo:archive`, and `pnpm check` fails when it is stale. E2E test spawns the bin (Astro disables dev middleware under `VITEST`). Cloudflare tests run both Workers on workerd via wrangler's `createTestHarness`; test files run serially (shared starter caches).
- `packages/cloudflare` — the admin Worker (`createAdminWorker`); `./playground` is RFC-0036's playground Worker (`createPlaygroundWorker`, the `PlaygroundSite` Durable Object, signed session cookies). Generated entries must import `@cloudhal/cloudflare/workerd-prelude` first (ADR-0012).
- `packages/agent-runtime` / `packages/mcp-server` — policy, skills, audit; MCP tools and transports (ADR-0011). `@cloudhal/mcp-server/render` is RFC-0021's `render_page` core: a small DevTools client, the in-page checks and limits; the CLI drives local Chrome with it (`render-chrome.ts`), the admin Worker Browser Rendering (`browser-render.ts`).
- `starters/blog` — the theme boundary: `src/pages/[...path].astro`, `src/layouts`, `src/theme.ts`.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ packages/astro-renderer Astro 7 integration, live/snapshot data sources, secti
packages/analytics cookie-less site analytics: beacon handler, WAE and SQLite stores, rollups
packages/comments reader comments (RFC-0007): rules, proof of work, submission pipeline, SQLite/D1 store
packages/schedules schedules (RFC-0008): time model, RRULE subset, releases, automations, taint, budgets, runDue, SQLite/D1 store
packages/cli the cloudhal CLI: init, dev, studio, mcp, deploy, push, pull, … (all commands: cloudhal --help, https://cloudhal.dev/docs/reference/cli)
packages/cli the cloudhal CLI: init, dev, studio, mcp, deploy, push, pull, export, import, … (all commands: cloudhal --help, https://cloudhal.dev/docs/reference/cli)
packages/api Hono HTTP API + Better Auth + /mcp endpoint + agent API keys (Node and Workers)
packages/agent-runtime policy engine, skill loader, audit log (SDK-free)
packages/mcp-server MCP server: over 100 tools (README tool reference), approval gate, agent modes, skills as resources; stdio + HTTP
Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/lib/site-pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ const docsIndex: SitePage = {
- [Typed custom fields](/docs/guides/fields): definitions, operations, languages and themes
- [Structured data, expiry and listings](/docs/guides/structured-data): JSON-LD presets, entries that end on a date, listings by field and collection feeds
- [Several sites in one deployment](/docs/guides/multi-site)
- [Site archives](/docs/guides/site-archives): backups, moving a site, templates; \`cloudhal export\` and \`import\`
- [Analytics and privacy](/docs/guides/analytics-privacy)
- [Translations with Weblate](/docs/guides/translations-weblate)

Expand Down
3 changes: 2 additions & 1 deletion apps/docs/test/repo-docs.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,8 @@ describe("the CLI reference", () => {
it("has a section per command of cloudhal --help, with its flags", async () => {
const { cliReference } = await import("../src/lib/reference.ts");
const { body } = cliReference();
for (const command of ["init", "dev", "studio", "mcp", "deploy", "push", "pull", "schedules"]) {
const commands = ["init", "dev", "studio", "mcp", "deploy", "push", "pull", "export", "import"];
for (const command of [...commands, "schedules"]) {
expect(body).toContain(`\n## ${command}\n`);
}
expect(body).toContain("cloudhal mcp [--mode plan|manual|edits|auto|bypass]");
Expand Down
3 changes: 2 additions & 1 deletion docs/adr/0041-site-archives.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
- 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.
- Amendment (2026-10-26, RFC-0039 rollout step 5): the committed demo archive is checked through its manifest without `createdBy`. The graph rows are held in memory, and import writes the node set in one batch of at most 1000 statements, as `push` and `pull`; only the container and the media stream. This corrects the risk below that says memory stays flat. Both are in RFC-0039's Later. Decision 5's list also leaves out scheduled releases, pending approvals and open edit suggestions, which live outside the graph like automations.
- 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 Down Expand Up @@ -34,4 +35,4 @@ A site's content can only leave a project through a deployment (`push`, `pull`),
- The format is versioned and must be read forever.
- Risks:
- A file is as trustworthy as its source until archives are signed.
- Large media sets make big files; `--no-media` and the parts limit keep memory flat, not size small.
- Large media sets make big files; `--no-media` and the parts limit keep memory flat, not size small (amended: flat for the media; the graph rows are held in memory).
2 changes: 1 addition & 1 deletion docs/guides/fields.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Collections without definitions keep `fields` as free-form JSON, exactly as befo
- **Studio:** open the collection's settings, then **Fields**. Add fields (the key follows the label until you save), reorder them, and edit labels, help, limits and options. Only people who may change site settings can edit fields. Entries of that collection then get a **Fields** card in the editor, one control per type.
- **Agents (MCP):** `list_collections` returns each collection's `fields` and `fieldsSchema` (the JSON Schema of the values, with labels and help in the caller's language). `update_collection` changes definitions, and `create_entry` / `update_entry` take `fields` (`null` removes a value). Definition changes always wait for a person who may change site settings, in every mode.
- **API:** `PUT /api/sites/:siteId/collections/:key` with `fields` in the settings; entry routes take `fields` like any other property. Invalid values answer `422 invalid_fields` with one issue per problem (`fields/startsAt/at`).
- **Files:** definitions travel in the site node, values in entries, so `cloudhal push`/`pull` and archives carry them unchanged.
- **Files:** definitions travel in the site node, values in entries, so `cloudhal push`/`pull` and [site archives](site-archives.md) carry them unchanged.

### Changes that touch values: field operations

Expand Down
Loading
Loading