@cloudhal/cli 0.3.8 → 0.3.10

package/README.md

@@ -163,7 +163,7 @@ Locally, `cloudhal studio` reads the project's SQLite (`analytics_events`), roll
 
 **From Git (Workers Builds).** With `WORKERS_CI=1`, which Cloudflare sets in [Workers Builds](https://developers.cloudflare.com/workers/ci-cd/builds/), `cloudhal deploy` works from a fresh clone. It takes the names from the committed `wrangler.jsonc`, seeds the starter site when the checkout has none, keeps the secrets on the Workers and does not print the setup link. This is what the Deploy to Cloudflare button runs: see [docs/guides/deploy-button.md](../../docs/guides/deploy-button.md).
 
-**Custom domain.** `cloudhal domain set news.example.com --studio studio.example.com` records the hostnames in `cloudhal.json`; the next `cloudhal deploy` routes them to the Workers as [Cloudflare Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) (the zone must be in the same Cloudflare account — Cloudflare creates the DNS record and certificate) and makes the site's one its primary hostname, so preview links use it (canonical URLs in the starter are not rendered yet). The workers.dev addresses keep working. `cloudhal domain remove` and a deploy undo it.
+**Custom domain.** `cloudhal domain set news.example.com --studio studio.example.com` records the hostnames in `cloudhal.json`; the next `cloudhal deploy` routes them to the Workers as [Cloudflare Custom Domains](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/) (the zone must be in the same Cloudflare account — Cloudflare creates the DNS record and certificate) and makes the site's one its primary hostname on the deployment. `domain set` makes it primary in the local store right away, so `cloudhal dev`, `render` and `build` write it into canonical links, the sitemap and feeds before any deploy. The workers.dev addresses keep working. `cloudhal domain remove` and a deploy undo it. `--redirect www.news.example.com` (repeatable) adds hosts that answer with a 301 to the site's domain, path and query kept: the next deploy routes them to the site Worker as Custom Domains too, so Cloudflare creates their DNS records and certificates. `cloudhal domain remove redirects` drops them.
 
 **Email (RFC-0011).** Add `"mail": { "from": "studio@example.com", "fromName": "Example Studio" }` to `cloudhal.json` and the next `cloudhal deploy` gives the admin Worker a [Cloudflare Email Service](https://developers.cloudflare.com/email-service/) `send_email` binding locked to that address. Invites can then be emailed, and staff can reset a forgotten password from the sign-in screen. Onboard the address's domain in Email Service first. Sending to any recipient needs Workers Paid (3,000 emails a month included); on Free, Email Service delivers only to verified destination addresses of your account. Locally, `cloudhal studio` prints these emails in the terminal instead of sending them.
 

package/dist/assets/starters/blog/package.json

@@ -14,18 +14,18 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@cloudhal/astro-renderer": "0.3.8",
-    "@cloudhal/core-ts": "0.3.8",
+    "@cloudhal/astro-renderer": "0.3.10",
+    "@cloudhal/core-ts": "0.3.10",
     "@tailwindcss/vite": "^4.3.3",
     "astro": "7.3.6",
     "better-sqlite3": "13.0.3",
     "tailwindcss": "^4.3.3",
     "@astrojs/cloudflare": "14.3.4",
-    "@cloudhal/cli": "0.3.8"
+    "@cloudhal/cli": "0.3.10"
   },
   "devDependencies": {
     "wrangler": "^4.148.0",
-    "@cloudhal/cloudflare": "0.3.8"
+    "@cloudhal/cloudflare": "0.3.10"
   },
   "trustedDependencies": [
     "better-sqlite3",

package/dist/src/cli/commands-local.js

@@ -45,6 +45,10 @@ const snapshotCommand             = async (_rest, values, { projectDir }) => {
     ...(values.label ? { label: values.label } : {}),
     ...(values.publish ? { publish: true } : {}),
   });
+  if (snap.unchanged) {
+    console.log(`nothing changed since ${snap.id} (live); no new snapshot`);
+    return 0;
+  }
   console.log(
     `${snap.id}  nodes=${snap.nodes.length}  +${snap.summary.added} ~${snap.summary.changed} -${snap.summary.removed}${values.publish ? "  (published)" : ""}`,
   );

package/dist/src/cli/commands-remote.js

@@ -60,23 +60,27 @@ const deployCommand             = async (_rest, values, { projectDir }) => {
 function changeDomain(rest          , values           , projectDir        ) {
   const [action, arg] = rest;
   if (action === "set") {
-    if (!arg && !values.studio)
-      throw new Error("usage: cloudhal domain set <hostname> [--studio <hostname>]");
+    const redirects = (values.redirect ?? []).flatMap((v) => v.split(","));
+    if (!arg && !values.studio && redirects.length === 0)
+      throw new Error(
+        "usage: cloudhal domain set <hostname> [--studio <hostname>] [--redirect <hostname>]…",
+      );
     return domain({
       projectDir,
       set: {
         ...(arg ? { site: arg } : {}),
         ...(values.studio ? { studio: values.studio } : {}),
+        ...(redirects.length > 0 ? { redirects } : {}),
       },
     });
   }
   if (action === "remove") {
     const which = arg ?? "all";
-    if (!["site", "studio", "all"].includes(which))
-      throw new Error("usage: cloudhal domain remove [site|studio|all]");
+    if (!["site", "studio", "redirects", "all"].includes(which))
+      throw new Error("usage: cloudhal domain remove [site|studio|redirects|all]");
     return domain({
       projectDir,
-      remove: which === "all" ? ["site", "studio"] : [which                ],
+      remove: which === "all" ? ["site", "studio", "redirects"] : [which                ],
     });
   }
   if (action === undefined) return domain({ projectDir });
@@ -87,7 +91,7 @@ const domainCommand             = async (rest, values, { projectDir }) => {
   const result = await changeDomain(rest, values, projectDir);
   console.log(
     result
-      ? `site:   ${result.site ? `https://${result.site}` : "(workers.dev)"}\nstudio: ${result.studio ? `https://${result.studio}` : "(workers.dev)"}`
+      ? `site:   ${result.site ? `https://${result.site}` : "(workers.dev)"}\nstudio: ${result.studio ? `https://${result.studio}` : "(workers.dev)"}${result.redirects ? `\n301:    ${result.redirects.join(", ")} → https://${result.site}` : ""}`
       : "no custom domains; the Workers answer on workers.dev",
   );
   if (rest[0])

package/dist/src/cli/help.d.ts

@@ -1,2 +1,2 @@
 /** `cloudhal --help`; every command it names has an entry in `COMMANDS` (cli.ts). */
-export declare const HELP = "cloudhal \u2014 agent-native sites\n\nUsage:\n  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store\n  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)\n  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)\n  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot\n  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)\n  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]\n                                                          MCP server over stdio for this project\n  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]\n                  [--force-downgrade] [--no-build-studio]\n                                                          site + admin Workers on Cloudflare (uses wrangler login);\n                                                          --jurisdiction eu keeps a newly created D1 database\n                                                          in the EU (cannot be changed later); --scheduler picks\n                                                          the minute cron trigger or the Durable Object alarm;\n                                                          --plan sizes scheduler ticks for the account's Workers\n                                                          plan (default free; remembered);\n                                                          --force-downgrade deploys older schedules code over\n                                                          open releases and time gates; from the monorepo a\n                                                          stale apps/studio/dist is rebuilt first\n                                                          (--no-build-studio: fail instead)\n  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]\n                                                          custom domains for the next deploy\n  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]\n                                                          local site \u2192 deployment (refused while releases are\n                                                          open unless --cancel-schedules cancels them)\n  cloudhal pull [--replace] [--admin-url <url>]           deployment \u2192 local site\n  cloudhal owner transfer --to <email> [--admin-url <url>]\n                                                          make a member the deployment's Owner\n                                                          (lockout recovery; uses the deployment token)\n  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]\n                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]\n                                                          the installation's sites (RFC-0034): one Studio,\n                                                          many isolated sites; nothing is published\n  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]\n                                                          move entry tags into tag terms (RFC-0002);\n                                                          resumable; --revert <id> undoes a run\n  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]\u2026 | --revert <id>\n                                                          copy linked images into the media library\n                                                          (RFC-0004); revertible\n  cloudhal media verify [<assetId>]                       recompute media checksums\n  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)\n  cloudhal media placeholders [--remote] [--all] [--dry-run]\n                                                          draw missing image placeholders in local Chrome\n  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget\n  cloudhal analytics rollup [--days <n>] [--remote] [--redo]\n                                                          compute daily totals (--remote backfills the\n                                                          deployment from WAE, up to 92 days)\n  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only\n  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]\n                                                          daily totals as CSV (default: 30 days)\n  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges\n  cloudhal comments export [--remote] [--with-personal-data --out <file>]\n                                                          comments as JSON lines (stdout or --out)\n  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun\n  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages\n  cloudhal schedules list [--remote] [--limit <n>]        the site's releases\n  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from\n                                                          the system's cron every minute)\n  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]\n                        [--design] [--look] [--judge <model>|none]\n                                                          compare models on Build chat's turn, in memory\n                                                          (real model calls; RFC-0020 open question 7);\n                                                          --design renders each result: failed checks and\n                                                          a vision model's score (RFC-0021 21c); --look lets\n                                                          the model see its render first, as Build chat does\n  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty \u2192 strong) with the\n                                                          design judge; fails when it does not rank them\n  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]\n                        [--frames <n>] [--base <url>] [--out <dir>]\n                                                          screenshots and render_page's checks for a page\n                                                          (of cloudhal dev by default; RFC-0024)\n  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets\n  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file\n                                                          (Figma, Style Dictionary; RFC-0023)\n  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON\n                                                          (RFC-0025)\n  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot\n                                                          (publishing keeps it current; for restored backups)\n  cloudhal --help\n";
+export declare const HELP = "cloudhal \u2014 agent-native sites\n\nUsage:\n  cloudhal init <dir> [--name <name>] [--starter blog]   create a site project with a seeded local store\n  cloudhal dev [--port <n>] [--host]                      live preview (drafts visible)\n  cloudhal snapshot [--label <text>] [--publish]          freeze the current graph (optionally publish)\n  cloudhal build [--snapshot <id>]                        static HTML from the published/latest snapshot\n  cloudhal studio [--port <n>] [--no-auth]                API + Studio UI for this project (default :8787)\n  cloudhal mcp [--mode plan|manual|edits|auto|bypass] [--scopes a,b] [--skills <dir>] [--preview-url <url>]\n                                                          MCP server over stdio for this project\n  cloudhal deploy [--name <base>] [--dry-run] [--jurisdiction eu] [--scheduler cron|alarm] [--plan free|paid]\n                  [--force-downgrade] [--no-build-studio]\n                                                          site + admin Workers on Cloudflare (uses wrangler login);\n                                                          --jurisdiction eu keeps a newly created D1 database\n                                                          in the EU (cannot be changed later); --scheduler picks\n                                                          the minute cron trigger or the Durable Object alarm;\n                                                          --plan sizes scheduler ticks for the account's Workers\n                                                          plan (default free; remembered);\n                                                          --force-downgrade deploys older schedules code over\n                                                          open releases and time gates; from the monorepo a\n                                                          stale apps/studio/dist is rebuilt first\n                                                          (--no-build-studio: fail instead)\n  cloudhal domain [set <hostname>] [--studio <hostname>] [--redirect <hostname>]\u2026 | remove [site|studio|redirects|all]\n                                                          custom domains for the next deploy\n  cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]\n                                                          local site \u2192 deployment (refused while releases are\n                                                          open unless --cancel-schedules cancels them)\n  cloudhal pull [--replace] [--admin-url <url>]           deployment \u2192 local site\n  cloudhal owner transfer --to <email> [--admin-url <url>]\n                                                          make a member the deployment's Owner\n                                                          (lockout recovery; uses the deployment token)\n  cloudhal site list | create --name <name> --slug <slug> [--locale <tag>] [--project <id>] [--theme <name>] [--from <siteId>]\n                     | delete <siteId> --confirm <slug>  [--remote] [--admin-url <url>]\n                                                          the installation's sites (RFC-0034): one Studio,\n                                                          many isolated sites; nothing is published\n  cloudhal migrate tags-to-terms [--dry-run] [--revert <id>]\n                                                          move entry tags into tag terms (RFC-0002);\n                                                          resumable; --revert <id> undoes a run\n  cloudhal media import-urls [--dry-run] [--include-markdown] [--allow-host <host>]\u2026 | --revert <id>\n                                                          copy linked images into the media library\n                                                          (RFC-0004); revertible\n  cloudhal media verify [<assetId>]                       recompute media checksums\n  cloudhal media gc [--dry-run]                           delete unreferenced media bytes (> 24 h old)\n  cloudhal media placeholders [--remote] [--all] [--dry-run]\n                                                          draw missing image placeholders in local Chrome\n  cloudhal analytics status [--remote]                    site analytics: settings, daily totals, budget\n  cloudhal analytics rollup [--days <n>] [--remote] [--redo]\n                                                          compute daily totals (--remote backfills the\n                                                          deployment from WAE, up to 92 days)\n  cloudhal analytics seed [--days <n>] [--views <n>]      demo traffic in the local SQLite only\n  cloudhal analytics export [--from <date> --to <date>] [--remote] [--out <file>]\n                                                          daily totals as CSV (default: 30 days)\n  cloudhal comments status [--remote]                     reader comments: counts, pending, daily cap, purges\n  cloudhal comments export [--remote] [--with-personal-data --out <file>]\n                                                          comments as JSON lines (stdout or --out)\n  cloudhal comments import --in <file> [--remote]         JSON lines back in; idempotent, safe to rerun\n  cloudhal schedules status [--remote]                    the scheduler's health, open releases, gated pages\n  cloudhal schedules list [--remote] [--limit <n>]        the site's releases\n  cloudhal schedules run-due [--remote]                   one scheduler tick now (self-hosting: run it from\n                                                          the system's cron every minute)\n  cloudhal ai build-eval [--remote] [--models a,b] [--briefs landing,faq] [--out <file>]\n                        [--design] [--look] [--judge <model>|none]\n                                                          compare models on Build chat's turn, in memory\n                                                          (real model calls; RFC-0020 open question 7);\n                                                          --design renders each result: failed checks and\n                                                          a vision model's score (RFC-0021 21c); --look lets\n                                                          the model see its render first, as Build chat does\n  cloudhal ai judge-check [--remote] [--judge <model>]   score the reference pages (empty \u2192 strong) with the\n                                                          design judge; fails when it does not rank them\n  cloudhal render <path|url> [--width 1440,390] [--scheme dark] [--motion static|reduce|full]\n                        [--frames <n>] [--base <url>] [--out <dir>]\n                                                          screenshots and render_page's checks for a page\n                                                          (of cloudhal dev by default; RFC-0024)\n  cloudhal motion audit [--path <p>]                      the motion each page asks for, against its budgets\n  cloudhal tokens export [--format dtcg] [--out <file>]   the site's design tokens as a W3C Design Tokens file\n                                                          (Figma, Style Dictionary; RFC-0023)\n  cloudhal chrome get [--file <f>] | set --file <f>       the site's header, footer and brand as JSON\n                                                          (RFC-0025)\n  cloudhal search reindex [--remote]                      rebuild the search index from the live snapshot\n                                                          (publishing keeps it current; for restored backups)\n  cloudhal --help\n";

package/dist/src/cli/help.js

@@ -21,7 +21,7 @@ Usage:
                                                           open releases and time gates; from the monorepo a
                                                           stale apps/studio/dist is rebuilt first
                                                           (--no-build-studio: fail instead)
-  cloudhal domain [set <hostname>] [--studio <hostname>] | remove [site|studio|all]
+  cloudhal domain [set <hostname>] [--studio <hostname>] [--redirect <hostname>]… | remove [site|studio|redirects|all]
                                                           custom domains for the next deploy
   cloudhal push [--replace] [--cancel-schedules] [--admin-url <url>]
                                                           local site → deployment (refused while releases are

package/dist/src/cli.d.ts

@@ -53,6 +53,10 @@ export declare const OPTIONS: {
     readonly studio: {
         readonly type: "string";
     };
+    readonly redirect: {
+        readonly type: "string";
+        readonly multiple: true;
+    };
     readonly revert: {
         readonly type: "string";
     };

package/dist/src/cli.js

@@ -26,6 +26,7 @@ export const OPTIONS = {
   replace: { type: "boolean" },
   "admin-url": { type: "string" },
   studio: { type: "string" },
+  redirect: { type: "string", multiple: true },
   revert: { type: "string" },
   to: { type: "string" },
   "include-markdown": { type: "boolean" },

package/dist/src/cloudflare/config.d.ts

@@ -102,6 +102,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
     domain?: string;
     /** RFC-0034 §5: every other site's hostnames, one Custom Domain route each. */
     domains?: readonly string[];
+    /** Hosts that answer with a 301 to `domain` (#49), each routed as a Custom Domain too. */
+    redirects?: readonly string[];
     analytics?: AnalyticsDeployment;
     comments?: CommentsDeployment;
     /** Extra hostnames the site answers on (custom domains): analytics and comments check them. */
@@ -150,6 +152,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -157,6 +161,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -164,6 +170,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -171,6 +179,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -223,6 +233,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -230,6 +242,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -237,6 +251,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -244,6 +260,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -296,6 +314,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -303,6 +323,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -310,6 +332,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -317,6 +341,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;
@@ -366,6 +392,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -373,6 +401,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER: string;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT: string;
@@ -380,6 +410,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     } | {
         CLOUDHAL_SEARCH_PROVIDER?: never;
         CLOUDHAL_SEARCH_MONTHLY_LIMIT?: never;
@@ -387,6 +419,8 @@ export declare function siteWorkerConfig(n: DeploymentNames & {
         CLOUDHAL_ANALYTICS?: string;
         CLOUDHAL_ANALYTICS_DEFAULTS?: string;
         CLOUDHAL_SITE_HOSTS?: string;
+        CLOUDHAL_REDIRECT_HOSTS?: string;
+        CLOUDHAL_REDIRECT_TO?: string;
     };
     cache: {
         enabled: boolean;

package/dist/src/cloudflare/config.js

@@ -180,6 +180,8 @@ export function siteWorkerConfig(
                     
                                                                                    
                                 
+                                                                                              
+                                  
                                     
                                   
                                                                                                    
@@ -191,6 +193,7 @@ export function siteWorkerConfig(
   const a = n.analytics;
   const c = n.comments?.available ? n.comments : undefined;
   const hosts = [...new Set([...(n.siteHosts ?? []), ...(a?.siteHosts ?? [])])];
+  const redirects = n.domain ? (n.redirects ?? []) : [];
   const ratelimits = [
     // Optional cross-isolate beacon limit (RFC-0006 §5.5): one key per client (an HMAC, never the IP).
     ...(a?.rateLimit
@@ -237,8 +240,11 @@ export function siteWorkerConfig(
         : {}),
       // RFC-0006 §5.2 / RFC-0007 §6.2 step 2: the same-origin checks accept these hosts too.
       ...((a || c) && hosts.length > 0 ? { CLOUDHAL_SITE_HOSTS: hosts.join(",") } : {}),
+      ...(n.domain && redirects.length > 0
+        ? { CLOUDHAL_REDIRECT_HOSTS: redirects.join(","), CLOUDHAL_REDIRECT_TO: n.domain }
+        : {}),
     },
-    ...customDomain(n.domain, n.domains),
+    ...customDomain(n.domain, [...(n.domains ?? []), ...redirects]),
     // Workers Cache: published pages are cached until a publish purges `cloudhal-site-<id>`.
     cache: { enabled: true },
     observability: observabilitySettings(n.observability),

package/dist/src/commands/deploy/prepare.js

@@ -292,6 +292,7 @@ export async function buildSite(
       ...(served.siteIds ? { siteIds: served.siteIds } : {}),
       ...(served.hosts.length > 0 ? { domains: served.hosts } : {}),
       ...(cfg.domains?.site ? { domain: cfg.domains.site, siteHosts: [cfg.domains.site] } : {}),
+      ...(cfg.domains?.redirects ? { redirects: cfg.domains.redirects } : {}),
       ...(input.analytics ? { analytics: input.analytics } : {}),
       comments: input.comments,
       observability: input.observability,

package/dist/src/commands/deploy/resources.d.ts

@@ -24,5 +24,15 @@ export declare const BUNDLE_LIFECYCLE_DAYS = 30;
  */
 export declare function ensureBundleLifecycle(run: WranglerRunner, cwd: string, bucket: string, log: (l: string) => void): Promise<void>;
 export declare function waitForHealth(adminUrl: string, f: typeof fetch, log: (line: string) => void, timeoutMs: number): Promise<void>;
+/**
+ * Runs `step` again while it fails with 401. Right after a deploy the edge can still answer from
+ * the previous admin Worker version, which holds the previous deployment token (Workers Builds
+ * makes a new one on every build), for a few seconds. Gives up after `timeoutMs`.
+ */
+export declare function whileTokenPropagates<T>(step: () => Promise<T>, options: {
+    log: (line: string) => void;
+    timeoutMs?: number;
+    waitMs?: number;
+}): Promise<T>;
 /** Purges the site Worker's whole cache once (the script tag lives in cached HTML). */
 export declare function purgeSite(siteUrl: string, token: string, f: typeof fetch, log: (line: string) => void): Promise<boolean>;

package/dist/src/commands/deploy/resources.js

@@ -139,6 +139,31 @@ export async function waitForHealth(
   }
 }
 
+/**
+ * Runs `step` again while it fails with 401. Right after a deploy the edge can still answer from
+ * the previous admin Worker version, which holds the previous deployment token (Workers Builds
+ * makes a new one on every build), for a few seconds. Gives up after `timeoutMs`.
+ */
+export async function whileTokenPropagates   (
+  step                  ,
+  options                                                                      ,
+)             {
+  const deadline = Date.now() + (options.timeoutMs ?? 90_000);
+  let announced = false;
+  for (;;) {
+    try {
+      return await step();
+    } catch (e) {
+      if (!/\(401\)/.test(e instanceof Error ? e.message : "") || Date.now() > deadline) throw e;
+      if (!announced) {
+        options.log("the deployment does not accept the new token yet; retrying while it spreads…");
+        announced = true;
+      }
+      await new Promise((r) => setTimeout(r, options.waitMs ?? 5000));
+    }
+  }
+}
+
 /** Purges the site Worker's whole cache once (the script tag lives in cached HTML). */
 export async function purgeSite(
   siteUrl        ,

package/dist/src/commands/deploy/ship.js

@@ -14,7 +14,7 @@ import { openLocalStore } from "@cloudhal/core-ts/local";
 import { deployedUrls, isCronLimitError, must, WranglerError } from "../../cloudflare/wrangler.js";
 import { pushSite, setPrimaryDomain } from "../sync.js";
                                                   
-import { purgeSite, waitForHealth } from "./resources.js";
+import { purgeSite, waitForHealth, whileTokenPropagates } from "./resources.js";
 import { CRON_REFUSED_MESSAGE } from "./schedules-guard.js";
                                                 
 
@@ -111,29 +111,35 @@ export async function afterDeploy(
       });
     await l.close();
   }
-  const result = await pushSite({
-    projectDir: options.projectDir,
-    ifAbsent: true,
-    log,
-    ...(options.fetch ? { fetch: options.fetch } : {}),
-  });
-  // A custom domain becomes the site's primary hostname (the workers.dev one stays secondary).
-  if (cfg.domains?.site) {
-    await setPrimaryDomain({
+  const retry =    (step                  ) => whileTokenPropagates(step, { log });
+  const result = await retry(() =>
+    pushSite({
       projectDir: options.projectDir,
-      hostname: cfg.domains.site,
+      ifAbsent: true,
+      log,
       ...(options.fetch ? { fetch: options.fetch } : {}),
-    });
-    log(
-      `site domain: https://${cfg.domains.site} (Cloudflare issues the certificate on first use)`,
+    }),
+  );
+  // A custom domain becomes the site's primary hostname (the workers.dev one stays secondary).
+  const domain = cfg.domains?.site;
+  if (domain) {
+    await retry(() =>
+      setPrimaryDomain({
+        projectDir: options.projectDir,
+        hostname: domain,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+      }),
     );
+    log(`site domain: https://${domain} (Cloudflare issues the certificate on first use)`);
   } else if (previous?.siteDomain && siteUrl) {
     // The custom domain was removed from cloudhal.json: workers.dev is primary again.
-    await setPrimaryDomain({
-      projectDir: options.projectDir,
-      hostname: new URL(siteUrl).hostname,
-      ...(options.fetch ? { fetch: options.fetch } : {}),
-    });
+    await retry(() =>
+      setPrimaryDomain({
+        projectDir: options.projectDir,
+        hostname: new URL(siteUrl).hostname,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+      }),
+    );
     log(
       `site domain ${previous.siteDomain} removed from cloudhal.json; if Cloudflare still lists it under the Worker's Domains & Routes, remove it there`,
     );

package/dist/src/commands/domain.d.ts

@@ -1,11 +1,15 @@
 import { type ProjectConfig } from "../config.js";
-export type DomainTarget = "site" | "studio";
+export type DomainTarget = "site" | "studio" | "redirects";
 export interface DomainOptions {
     readonly projectDir: string;
-    /** Hostnames to set (others stay as they are). */
+    /**
+     * Hostnames to set (others stay as they are). `redirects` replaces the list of hosts that
+     * answer with a 301 to the site's domain (#49).
+     */
     readonly set?: {
         readonly site?: string;
         readonly studio?: string;
+        readonly redirects?: readonly string[];
     };
     /** Domains to forget. */
     readonly remove?: readonly DomainTarget[];

package/dist/src/commands/domain.js

@@ -2,16 +2,28 @@
  * `cloudhal domain` — the custom domains `cloudhal deploy` routes to this project's Workers
  * (Cloudflare Custom Domains: the zone must be in the same Cloudflare account; wrangler creates
  * the DNS record and certificate). Kept in cloudhal.json so the setting travels with the project.
+ * The site's own hostname also becomes its primary domain in the local store, so `cloudhal build`
+ * writes it into canonical links, the sitemap and feeds before any deploy (#48); `deploy` does the
+ * same on the deployment.
  */
-import { isHostname, normalizeHostname } from "@cloudhal/core-ts";
+import path from "node:path";
+import { isHostname, normalizeHostname, withPrimaryDomain } from "@cloudhal/core-ts";
+import { openLocalStore } from "@cloudhal/core-ts/local";
 import {                     readProjectConfig, writeProjectConfig } from "../config.js";
 
-                                             
+                                                           
 
                                 
                               
-                                                    
-                                                                      
+     
+                                                                                            
+                                                  
+     
+                  
+                           
+                             
+                                           
+    
                            
                                             
  
@@ -27,18 +39,47 @@ export function checkHostname(input        )         {
 
 export async function domain(options               )                                    {
   const cfg = await readProjectConfig(options.projectDir);
-  const next                                     = { ...cfg.domains };
+  const next                                                                    = {
+    ...cfg.domains,
+  };
   for (const target of options.remove ?? []) delete next[target];
+  // redirects go to the site's domain: without it they have nowhere to go
+  if (options.remove?.includes("site")) delete next.redirects;
   if (options.set?.site) next.site = checkHostname(options.set.site);
   if (options.set?.studio) next.studio = checkHostname(options.set.studio);
+  if (options.set?.redirects)
+    next.redirects = [...new Set(options.set.redirects.map(checkHostname))];
   if (next.site && next.site === next.studio)
     throw new Error("the site and Studio need different hostnames");
+  checkRedirects(next);
+  if (!next.redirects?.length) delete next.redirects;
+  const any = next.site || next.studio || next.redirects;
   if (options.set || options.remove) {
     const { domains: _old, ...rest } = cfg;
-    await writeProjectConfig(options.projectDir, {
-      ...rest,
-      ...(next.site || next.studio ? { domains: next } : {}),
-    });
+    await writeProjectConfig(options.projectDir, { ...rest, ...(any ? { domains: next } : {}) });
+  }
+  if (next.site && options.set?.site) await makePrimary(options.projectDir, cfg, next.site);
+  return any ? next : undefined;
+}
+
+/** Redirect hosts need a site domain to go to, and are neither it nor Studio's. */
+function checkRedirects(d                                                                   ) {
+  if (!d.redirects?.length) return;
+  if (!d.site)
+    throw new Error("redirects need the site's own domain: cloudhal domain set <hostname>");
+  for (const host of d.redirects)
+    if (host === d.site || host === d.studio)
+      throw new Error(`${host} is already the site's or Studio's domain; it cannot redirect`);
+}
+
+/** `hostname` becomes the local site's primary domain (other domains stay, as secondary). */
+async function makePrimary(projectDir        , cfg               , hostname        ) {
+  const local = await openLocalStore(path.join(projectDir, cfg.dataDir));
+  try {
+    const site = await local.store.getSite(cfg.siteId);
+    if (site && site.domains.find((d) => d.primary)?.hostname !== hostname)
+      await local.store.updateSite({ ...site, domains: withPrimaryDomain(site.domains, hostname) });
+  } finally {
+    await local.close();
   }
-  return next.site || next.studio ? next : undefined;
 }

package/dist/src/commands/snapshot.d.ts

@@ -4,7 +4,15 @@ export interface SnapshotOptions {
     readonly label?: string;
     readonly publish?: boolean;
 }
-/** Creates a snapshot of the live site (and optionally publishes it). */
-export declare function snapshot(options: SnapshotOptions): Promise<Snapshot>;
+/** A snapshot, or (`unchanged`) the live one when publishing would change nothing. */
+export type SnapshotResult = Snapshot & {
+    readonly unchanged?: true;
+};
+/**
+ * Creates a snapshot of the live site (and optionally publishes it). Publishing a site whose
+ * graph matches its live snapshot makes no new one (#51): re-running a setup script does not pad
+ * the history with empty snapshots.
+ */
+export declare function snapshot(options: SnapshotOptions): Promise<SnapshotResult>;
 /** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
 export declare function resolveBuildSnapshot(projectDir: string): Promise<Snapshot>;

package/dist/src/commands/snapshot.js

@@ -1,6 +1,6 @@
 import path from "node:path";
                                                          
-import { openLocalStore } from "@cloudhal/core-ts/local";
+import {                  openLocalStore } from "@cloudhal/core-ts/local";
 import { readProjectConfig } from "../config.js";
 
                                   
@@ -9,11 +9,22 @@ import { readProjectConfig } from "../config.js";
                              
  
 
-/** Creates a snapshot of the live site (and optionally publishes it). */
-export async function snapshot(options                 )                    {
+/** A snapshot, or (`unchanged`) the live one when publishing would change nothing. */
+                                                                      
+
+/**
+ * Creates a snapshot of the live site (and optionally publishes it). Publishing a site whose
+ * graph matches its live snapshot makes no new one (#51): re-running a setup script does not pad
+ * the history with empty snapshots.
+ */
+export async function snapshot(options                 )                          {
   const cfg = await readProjectConfig(options.projectDir);
   const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
   try {
+    if (options.publish) {
+      const live = await unchangedLive(local.store, cfg.siteId);
+      if (live) return { ...live, unchanged: true };
+    }
     const snap = await local.store.createSnapshot(cfg.siteId, {
       actor: { kind: "human", id: "user_localcli0001", name: "cloudhal CLI" },
       reason: options.publish ? "publish" : "manual",
@@ -30,6 +41,18 @@ export async function snapshot(options                 )                    {
   }
 }
 
+/** The live snapshot when the site has one and nothing is pending against it. */
+async function unchangedLive(
+  store                     ,
+  siteId        ,
+)                                {
+  const site = await store.getSite(siteId);
+  if (!site?.publishedSnapshotId) return undefined;
+  const d = await store.pendingChanges(siteId);
+  if (d.added.length || d.removed.length || d.changed.length) return undefined;
+  return (await store.getSnapshot(site.publishedSnapshotId)) ?? undefined;
+}
+
 /** The snapshot `cloudhal build` renders: the published one, else the latest, else a fresh one. */
 export async function resolveBuildSnapshot(projectDir        )                    {
   const cfg = await readProjectConfig(projectDir);

package/dist/src/config.d.ts

@@ -104,11 +104,13 @@ export interface ProjectConfig {
     readonly dataDir: string;
     /**
      * Custom domains `cloudhal deploy` routes to the Workers (Cloudflare Custom Domains; the zone
-     * must be in the same account). The workers.dev addresses keep working.
+     * must be in the same account). The workers.dev addresses keep working. `redirects` answer with
+     * a 301 to `site` (#49), e.g. `www.example.com`.
      */
     readonly domains?: {
         readonly site?: string;
         readonly studio?: string;
+        readonly redirects?: readonly string[];
     };
     /** Site analytics (RFC-0006); absent = off. */
     readonly analytics?: AnalyticsConfig;

package/dist/src/config.js

@@ -117,9 +117,14 @@ const MAIL_ADDRESS = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
                            
      
                                                                                                 
-                                                                          
+                                                                                                  
+                                                   
      
-                                                                          
+                      
+                           
+                             
+                                           
+    
                                                  
                                        
                                                                       
@@ -167,6 +172,21 @@ const OWN_KEYS = new Set([
 
 const VITALS = [0, 1, 2, 5, 10, 20];
 
+/** `domains`, leniently: values of the wrong type are left out. */
+function parseDomains(input         )                           {
+  if (!input || typeof input !== "object") return undefined;
+  const d = input                           ;
+  const redirects = Array.isArray(d.redirects)
+    ? d.redirects.filter((h)              => typeof h === "string" && h !== "")
+    : [];
+  const out = {
+    ...(typeof d.site === "string" && d.site ? { site: d.site } : {}),
+    ...(typeof d.studio === "string" && d.studio ? { studio: d.studio } : {}),
+    ...(redirects.length > 0 ? { redirects } : {}),
+  };
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** Leniently parsed, like `domains`: values of the wrong type are left out. */
 export function parseAnalyticsConfig(input         )                              {
   if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
@@ -297,7 +317,7 @@ export async function readProjectConfig(projectDir        )
   }
   const cfg = JSON.parse(raw)                          ;
   if (typeof cfg.siteId !== "string") throw new Error(`${CONFIG_FILE}: missing siteId`);
-  const domains = cfg.domains && typeof cfg.domains === "object" ? cfg.domains : undefined;
+  const domains = parseDomains(cfg.domains);
   const analytics = parseAnalyticsConfig(cfg.analytics);
   const comments = parseCommentsConfig(cfg.comments);
   const schedules = parseSchedulesConfig(cfg.schedules);
@@ -314,14 +334,7 @@ export async function readProjectConfig(projectDir        )
       ? { installation: cfg.installation }
       : {}),
     dataDir: cfg.dataDir ?? ".cloudhal",
-    ...(domains && (domains.site || domains.studio)
-      ? {
-          domains: {
-            ...(typeof domains.site === "string" ? { site: domains.site } : {}),
-            ...(typeof domains.studio === "string" ? { studio: domains.studio } : {}),
-          },
-        }
-      : {}),
+    ...(domains ? { domains } : {}),
     ...(analytics ? { analytics } : {}),
     ...(comments ? { comments } : {}),
     ...(schedules ? { schedules } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudhal/cli",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "cloudhal — create, run and build Cloudhal sites locally",
   "license": "Apache-2.0",
   "homepage": "https://cloudhal.dev",
@@ -27,16 +27,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@cloudhal/agent-runtime": "0.3.8",
-    "@cloudhal/analytics": "0.3.8",
-    "@cloudhal/api": "0.3.8",
-    "@cloudhal/cloudflare": "0.3.8",
-    "@cloudhal/comments": "0.3.8",
-    "@cloudhal/core-contracts": "0.3.8",
-    "@cloudhal/core-ts": "0.3.8",
-    "@cloudhal/mcp-server": "0.3.8",
-    "@cloudhal/schedules": "0.3.8",
-    "@cloudhal/storage": "0.3.8",
+    "@cloudhal/agent-runtime": "0.3.10",
+    "@cloudhal/analytics": "0.3.10",
+    "@cloudhal/api": "0.3.10",
+    "@cloudhal/cloudflare": "0.3.10",
+    "@cloudhal/comments": "0.3.10",
+    "@cloudhal/core-contracts": "0.3.10",
+    "@cloudhal/core-ts": "0.3.10",
+    "@cloudhal/mcp-server": "0.3.10",
+    "@cloudhal/schedules": "0.3.10",
+    "@cloudhal/storage": "0.3.10",
     "@hono/node-server": "^2.1.4",
     "better-sqlite3": "13.0.3"
   },