@cloudhal/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,174 @@
+/**
+ * The phases of `cloudhal deploy` that change Cloudflare: both Workers (secrets through files that
+ * exist only while wrangler runs), the first push and the site's domains, the one-time cache purge.
+ */
+import { chmod, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+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 { CRON_REFUSED_MESSAGE } from "./schedules-guard.js";
+                                                
+
+                                                                    
+
+/**
+ * `wrangler deploy` for the site Worker, then the admin Worker. When Cloudflare refuses the cron
+ * trigger (RFC-0008 §8.3: Workers Free allows 5 per account), the same Worker goes without it and
+ * the SchedulerClock alarm ticks instead.
+ */
+export async function shipWorkers(
+  ctx               ,
+  input   
+                           
+                         
+                                                                      
+                               
+   ,
+)           
+                              
+                               
+                             
+   {
+  const { options, run, names, log, dir } = ctx;
+  const { secrets, admin } = input;
+  let scheduler = input.scheduler;
+  // Secrets go to wrangler through files that exist only while it runs (0600, then removed).
+  const siteSecretsFile = path.join(dir, "site-secrets.json");
+  const adminSecretsFile = path.join(dir, "admin-secrets.json");
+  const writeSecret = async (file        , value        ) => {
+    await writeFile(file, JSON.stringify(value), { mode: 0o600 });
+    await chmod(file, 0o600);
+  };
+  let siteDeploy                                  ;
+  let adminDeploy                                  ;
+  try {
+    await writeSecret(siteSecretsFile, {
+      CLOUDHAL_PREVIEW_SECRET: secrets.CLOUDHAL_PREVIEW_SECRET,
+      CLOUDHAL_PURGE_TOKEN: secrets.CLOUDHAL_PURGE_TOKEN,
+      // RFC-0007: the same value as the admin Worker's (proof of work, emails, stored secrets)
+      CLOUDHAL_COMMENTS_KEY: secrets.CLOUDHAL_COMMENTS_KEY,
+    });
+    await writeSecret(adminSecretsFile, secrets);
+    log(`deploying ${names.site}`);
+    siteDeploy = await must(run, ["deploy", "--secrets-file", siteSecretsFile], options.projectDir);
+    log(`deploying ${names.admin}`);
+    const adminArgs = ["deploy", "-c", admin.configPath, "--secrets-file", adminSecretsFile];
+    adminDeploy = await run(adminArgs, { cwd: admin.dir });
+    if (
+      adminDeploy.code !== 0 &&
+      scheduler === "cron" &&
+      isCronLimitError(adminDeploy.stderr + adminDeploy.stdout)
+    ) {
+      log(CRON_REFUSED_MESSAGE);
+      scheduler = "alarm";
+      await input.prepareAdmin(scheduler);
+      adminDeploy = await run(adminArgs, { cwd: admin.dir });
+    }
+    if (adminDeploy.code !== 0)
+      throw new WranglerError(
+        `wrangler ${adminArgs.join(" ")} failed:\n${(adminDeploy.stderr || adminDeploy.stdout).slice(-3000)}`,
+      );
+  } finally {
+    await rm(siteSecretsFile, { force: true });
+    await rm(adminSecretsFile, { force: true });
+  }
+  return {
+    siteUrl: deployedUrls(siteDeploy.records)[0],
+    adminUrl: deployedUrls(adminDeploy.records)[0],
+    scheduler,
+  };
+}
+
+/**
+ * 5. first deploy: push the local site, and make the site's hostname primary (the custom domain
+ * when there is one). Returns whether the site was pushed.
+ */
+export async function afterDeploy(
+  ctx               ,
+  { siteUrl, adminUrl }                                                               ,
+)                   {
+  const { options, cfg, site, previous, log } = ctx;
+  if (!adminUrl) return false;
+  // A brand-new workers.dev hostname can take a while to answer; wait instead of failing.
+  await waitForHealth(adminUrl, options.fetch ?? fetch, log, options.healthTimeoutMs ?? 120_000);
+  if (siteUrl && !(site.domains ?? []).length) {
+    // Preview links need the public hostname of the site.
+    const l = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+    const current = await l.store.getSite(cfg.siteId);
+    if (current)
+      await l.store.updateSite({
+        ...current,
+        domains: [{ hostname: new URL(siteUrl).hostname, primary: true }],
+      });
+    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({
+      projectDir: options.projectDir,
+      hostname: cfg.domains.site,
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    log(
+      `site domain: https://${cfg.domains.site} (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 } : {}),
+    });
+    log(
+      `site domain ${previous.siteDomain} removed from cloudhal.json; if Cloudflare still lists it under the Worker's Domains & Routes, remove it there`,
+    );
+  }
+  return result.pushed;
+}
+
+/**
+ * Analytics switched on (or off): purge the site's cache once, so cached pages gain (or lose)
+ * the script tag. The admin Worker ran migration 0014 on the health check; until it has, the Site
+ * Worker counts analytics as off (fail closed). Comments availability likewise (RFC-0007): pages
+ * cached before carry no `cloudhal-comments-<id>` tag, so a site turning comments on later could
+ * not reach them.
+ */
+export async function purgeIfSwitched(
+  ctx               ,
+  input   
+                                
+                                               
+                                 
+                       
+   ,
+)                                                                                    {
+  const { previous, options, log } = ctx;
+  const { siteUrl, analytics, comments } = input;
+  let purged = false;
+  const analyticsChanged = (previous?.analytics ?? "off") !== (analytics ? "on" : "off");
+  const commentsChanged = (previous?.comments ?? "off") !== (comments.available ? "on" : "off");
+  if (siteUrl && (analyticsChanged || commentsChanged)) {
+    purged = await purgeSite(siteUrl, input.purgeToken, options.fetch ?? fetch, log);
+    const what = [
+      ...(analyticsChanged ? [`analytics ${analytics ? "on" : "off"}`] : []),
+      ...(commentsChanged ? [`comments ${comments.available ? "available" : "unavailable"}`] : []),
+    ];
+    if (purged) log(`${what.join(", ")}: purged the site cache`);
+  }
+  return { purged, analyticsChanged, commentsChanged };
+}

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

@@ -0,0 +1,30 @@
+import type { SchedulerTicker, WorkersPlan } from "../../cloudflare/config.js";
+export declare const SECRET_KEYS: readonly ["BETTER_AUTH_SECRET", "MCP_STATE_KEY", "CLOUDHAL_PREVIEW_SECRET", "CLOUDHAL_PURGE_TOKEN", "CLOUDHAL_DEPLOY_TOKEN", "CLOUDHAL_SETUP_TOKEN", "CLOUDHAL_COMMENTS_KEY"];
+export type DeploySecrets = Record<(typeof SECRET_KEYS)[number], string>;
+export interface DeployState {
+    name: string;
+    adminUrl?: string;
+    siteUrl?: string;
+    deployedAt?: string;
+    /** The custom site domain this deploy routed, so removing it later restores workers.dev. */
+    siteDomain?: string;
+    /** Whether the last deploy had analytics on (a change purges the site's cache once). */
+    analytics?: "on" | "off";
+    /** Whether the last deploy had reader comments available (a change purges once too). */
+    comments?: "on" | "off";
+    /** Where a deploy of this project created the D1 database (absent: before RFC-0007). */
+    jurisdiction?: Jurisdiction;
+    /** What drives the scheduler (RFC-0008 §8.3): the cron trigger, or the Durable Object alarm. */
+    scheduler?: SchedulerTicker;
+    /** The Workers plan the tick budget was sized for (`--plan`, RFC-0008 §8.2). */
+    plan?: WorkersPlan;
+}
+/** D1 data location (RFC-0007 D7): `auto` (Cloudflare picks) or the EU jurisdiction. */
+export type Jurisdiction = "auto" | "eu";
+export declare function exists(p: string): Promise<boolean>;
+export declare const deployDir: (projectDir: string, dataDir: string) => string;
+export declare function randomSecret(): string;
+/** Secrets are generated once per project and reused on every deploy. */
+export declare function loadOrCreateSecrets(dir: string): Promise<DeploySecrets>;
+export declare function readDeployState(projectDir: string, dataDir: string): Promise<DeployState | undefined>;
+export declare function writeDeployState(projectDir: string, dataDir: string, state: DeployState): Promise<void>;

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

@@ -0,0 +1,102 @@
+/** Deploy secrets (generated once per project) and the last deploy's state under `.cloudhal/deploy`. */
+import { access, chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+                                                                               
+
+export const SECRET_KEYS = [
+  "BETTER_AUTH_SECRET",
+  "MCP_STATE_KEY",
+  "CLOUDHAL_PREVIEW_SECRET",
+  "CLOUDHAL_PURGE_TOKEN",
+  "CLOUDHAL_DEPLOY_TOKEN",
+  "CLOUDHAL_SETUP_TOKEN",
+  // RFC-0007: proof-of-work MACs, email encryption and hashes, stored secrets; both Workers.
+  "CLOUDHAL_COMMENTS_KEY",
+]         ;
+                                                                         
+
+                              
+               
+                    
+                   
+                      
+                                                                                              
+                      
+                                                                                          
+                           
+                                                                                          
+                          
+                                                                                          
+                              
+                                                                                                  
+                              
+                                                                                  
+                     
+ 
+
+/** D1 data location (RFC-0007 D7): `auto` (Cloudflare picks) or the EU jurisdiction. */
+                                         
+
+export async function exists(p        )                   {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export const deployDir = (projectDir        , dataDir        ) =>
+  path.join(projectDir, dataDir, "deploy");
+
+export function randomSecret()         {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/** Secrets are generated once per project and reused on every deploy. */
+export async function loadOrCreateSecrets(dir        )                         {
+  const file = path.join(dir, "secrets.json");
+  let current                         = {};
+  try {
+    current = JSON.parse(await readFile(file, "utf8"))                          ;
+  } catch {
+    // first deploy
+  }
+  const secrets = { ...current }                 ;
+  let changed = false;
+  for (const key of SECRET_KEYS)
+    if (!secrets[key] || secrets[key].length < 32) {
+      secrets[key] = randomSecret();
+      changed = true;
+    }
+  if (changed) {
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, `${JSON.stringify(secrets, null, 2)}\n`, { mode: 0o600 });
+    await chmod(file, 0o600);
+  }
+  return secrets;
+}
+
+export async function readDeployState(
+  projectDir        ,
+  dataDir        ,
+)                                   {
+  try {
+    return JSON.parse(
+      await readFile(path.join(deployDir(projectDir, dataDir), "state.json"), "utf8"),
+    )               ;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeDeployState(projectDir        , dataDir        , state             ) {
+  await writeFile(
+    path.join(deployDir(projectDir, dataDir), "state.json"),
+    `${JSON.stringify(state, null, 2)}\n`,
+  );
+}

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

@@ -0,0 +1,52 @@
+/**
+ * `cloudhal deploy` — puts the project on Cloudflare (ADR-0012):
+ *
+ *   1. D1 database + R2 bucket (created if missing; ids recorded in the wrangler configs)
+ *   2. secrets generated once into `<dataDir>/deploy/secrets.json` (0600, never committed)
+ *   3. site Worker: `astro build` for the cloudflare target, `wrangler deploy`
+ *   4. admin Worker: generated entry + bundled skills + built Studio, `wrangler deploy`
+ *   5. push: the local site (graph, snapshots, blobs) through the admin API — first deploy only;
+ *      afterwards the deployment is the source of truth (use `cloudhal pull`).
+ *   6. analytics (RFC-0006 §11): with `analytics` on in cloudhal.json both configs get their
+ *      bindings and vars (wrangler ≥ 4.145 is required); a project without the key is asked once in
+ *      a terminal (non-interactive: off). When analytics switch on or off the site's cache is purged
+ *      once, so pages gain or lose the script tag. `analytics.rateLimit` adds the beacon's Workers
+ *      Rate Limiting binding (`ANALYTICS_RL`).
+ *   7. reader comments (RFC-0007 §15.4): available unless `comments.available` is `false`, and
+ *      still off for every site until someone turns them on in Studio. `CLOUDHAL_COMMENTS_KEY` is
+ *      generated once with the other secrets and given to both Workers; the admin Worker gets
+ *      `CLOUDHAL_COMMENTS_AVAILABLE`; `comments.rateLimit` adds `COMMENTS_RL`. When availability
+ *      changes the site's cache is purged once (pages gain or lose the comments tag).
+ *   8. data location (RFC-0007 D7): only when this deploy creates the D1 database, `--jurisdiction
+ *      eu` (or the terminal question) creates it in the EU jurisdiction. It cannot change later;
+ *      existing databases are never touched.
+ *   9. the scheduler (RFC-0008 §8.2–§8.3, §16): the admin Worker gets the minute cron trigger
+ *      (`* * * * *`, the slot the hourly jobs used), the `SchedulerClock` Durable Object binding and
+ *      migration (always), and `CLOUDHAL_SCHEDULER`. When Cloudflare refuses the trigger (Workers
+ *      Free allows 5 per account) it redeploys without it and with `CLOUDHAL_SCHEDULER=alarm`; the
+ *      ticker is remembered in `state.json` (`--scheduler cron` tries the trigger again). A
+ *      deployment last deployed with the legacy `CLOUDHAL_*_CRON=off` starts as `alarm`.
+ *  10. the downgrade guard (RFC-0008 Compatibility): code whose schedules level is lower than the
+ *      deployment's would ignore holds and time gates, so it is refused while the deployment has
+ *      open releases or gated pages and entries, unless `--force-downgrade`.
+ *  11. the tick budget and the automations switch (RFC-0008 §8.2, §11.6): the admin Worker always
+ *      gets `CLOUDHAL_TICK_BUDGET` (`free` unless `--plan paid` or `schedules.plan` says `paid`; the
+ *      plan is remembered in `state.json`) and `CLOUDHAL_AUTOMATIONS` (`off` when
+ *      `schedules.automations` is `false`). Cloudflare offers no cheap, reliable way to read an
+ *      account's Workers plan with wrangler's login, so the owner says it once.
+ *  12. the Studio build: running from the monorepo, the admin Worker gets `apps/studio/dist`, which
+ *      only a build keeps current. When it is missing or older than the newest file in
+ *      `apps/studio/src`, `apps/studio/index.html` or `packages/ui/src`, the deploy runs
+ *      `pnpm --filter @cloudhal/studio build` first; `--no-build-studio` fails instead. A published
+ *      install ships Studio prebuilt and is never checked.
+ *
+ * `--dry-run` runs everything up to wrangler's own `--dry-run` (bundles, configs) and skips
+ * provisioning, deployment and push — no Cloudflare account needed.
+ */
+import type { DeployOptions, DeployResult } from "./deploy/options.js";
+export type { DeployOptions, DeployResult } from "./deploy/options.js";
+export { BUNDLE_LIFECYCLE_DAYS, BUNDLE_LIFECYCLE_RULE } from "./deploy/resources.js";
+export { CRON_REFUSED_MESSAGE, projectSchedulesLevel, type SchedulesStatus, } from "./deploy/schedules-guard.js";
+export { commentsRateLimitDeployment, DEFAULT_QUERY_BUDGET, observabilityOf, rateLimitDeployment, } from "./deploy/settings.js";
+export { type DeploySecrets, type DeployState, deployDir, type Jurisdiction, loadOrCreateSecrets, readDeployState, SECRET_KEYS, } from "./deploy/state.js";
+export declare function deploy(options: DeployOptions): Promise<DeployResult>;

package/dist/src/commands/deploy.js

@@ -0,0 +1,223 @@
+/**
+ * `cloudhal deploy` — puts the project on Cloudflare (ADR-0012):
+ *
+ *   1. D1 database + R2 bucket (created if missing; ids recorded in the wrangler configs)
+ *   2. secrets generated once into `<dataDir>/deploy/secrets.json` (0600, never committed)
+ *   3. site Worker: `astro build` for the cloudflare target, `wrangler deploy`
+ *   4. admin Worker: generated entry + bundled skills + built Studio, `wrangler deploy`
+ *   5. push: the local site (graph, snapshots, blobs) through the admin API — first deploy only;
+ *      afterwards the deployment is the source of truth (use `cloudhal pull`).
+ *   6. analytics (RFC-0006 §11): with `analytics` on in cloudhal.json both configs get their
+ *      bindings and vars (wrangler ≥ 4.145 is required); a project without the key is asked once in
+ *      a terminal (non-interactive: off). When analytics switch on or off the site's cache is purged
+ *      once, so pages gain or lose the script tag. `analytics.rateLimit` adds the beacon's Workers
+ *      Rate Limiting binding (`ANALYTICS_RL`).
+ *   7. reader comments (RFC-0007 §15.4): available unless `comments.available` is `false`, and
+ *      still off for every site until someone turns them on in Studio. `CLOUDHAL_COMMENTS_KEY` is
+ *      generated once with the other secrets and given to both Workers; the admin Worker gets
+ *      `CLOUDHAL_COMMENTS_AVAILABLE`; `comments.rateLimit` adds `COMMENTS_RL`. When availability
+ *      changes the site's cache is purged once (pages gain or lose the comments tag).
+ *   8. data location (RFC-0007 D7): only when this deploy creates the D1 database, `--jurisdiction
+ *      eu` (or the terminal question) creates it in the EU jurisdiction. It cannot change later;
+ *      existing databases are never touched.
+ *   9. the scheduler (RFC-0008 §8.2–§8.3, §16): the admin Worker gets the minute cron trigger
+ *      (`* * * * *`, the slot the hourly jobs used), the `SchedulerClock` Durable Object binding and
+ *      migration (always), and `CLOUDHAL_SCHEDULER`. When Cloudflare refuses the trigger (Workers
+ *      Free allows 5 per account) it redeploys without it and with `CLOUDHAL_SCHEDULER=alarm`; the
+ *      ticker is remembered in `state.json` (`--scheduler cron` tries the trigger again). A
+ *      deployment last deployed with the legacy `CLOUDHAL_*_CRON=off` starts as `alarm`.
+ *  10. the downgrade guard (RFC-0008 Compatibility): code whose schedules level is lower than the
+ *      deployment's would ignore holds and time gates, so it is refused while the deployment has
+ *      open releases or gated pages and entries, unless `--force-downgrade`.
+ *  11. the tick budget and the automations switch (RFC-0008 §8.2, §11.6): the admin Worker always
+ *      gets `CLOUDHAL_TICK_BUDGET` (`free` unless `--plan paid` or `schedules.plan` says `paid`; the
+ *      plan is remembered in `state.json`) and `CLOUDHAL_AUTOMATIONS` (`off` when
+ *      `schedules.automations` is `false`). Cloudflare offers no cheap, reliable way to read an
+ *      account's Workers plan with wrangler's login, so the owner says it once.
+ *  12. the Studio build: running from the monorepo, the admin Worker gets `apps/studio/dist`, which
+ *      only a build keeps current. When it is missing or older than the newest file in
+ *      `apps/studio/src`, `apps/studio/index.html` or `packages/ui/src`, the deploy runs
+ *      `pnpm --filter @cloudhal/studio build` first; `--no-build-studio` fails instead. A published
+ *      install ships Studio prebuilt and is never checked.
+ *
+ * `--dry-run` runs everything up to wrangler's own `--dry-run` (bundles, configs) and skips
+ * provisioning, deployment and push — no Cloudflare account needed.
+ */
+
+import path from "node:path";
+import { prepareAdminWorker } from "../cloudflare/admin.js";
+                                                               
+import { must } from "../cloudflare/wrangler.js";
+import { readProjectConfig } from "../config.js";
+import { deployAttached } from "./deploy/attach.js";
+                                                                       
+import {
+  analyticsAndComments,
+  buildSite,
+  checkOptions,
+  deploySettings,
+  loadDeploy,
+  provision,
+  studioDirFor,
+} from "./deploy/prepare.js";
+import { downgradeGuard } from "./deploy/schedules-guard.js";
+import { attachedWorkers } from "./deploy/served-sites.js";
+import { commentsResult } from "./deploy/settings.js";
+import { afterDeploy, purgeIfSwitched, shipWorkers } from "./deploy/ship.js";
+import { loadOrCreateSecrets, writeDeployState } from "./deploy/state.js";
+import { resolveSkillsDir } from "./mcp.js";
+
+                                                                       
+export { BUNDLE_LIFECYCLE_DAYS, BUNDLE_LIFECYCLE_RULE } from "./deploy/resources.js";
+export {
+  CRON_REFUSED_MESSAGE,
+  projectSchedulesLevel,
+                       
+} from "./deploy/schedules-guard.js";
+export {
+  commentsRateLimitDeployment,
+  DEFAULT_QUERY_BUDGET,
+  observabilityOf,
+  rateLimitDeployment,
+} from "./deploy/settings.js";
+export {
+                     
+                   
+  deployDir,
+                    
+  loadOrCreateSecrets,
+  readDeployState,
+  SECRET_KEYS,
+} from "./deploy/state.js";
+
+export async function deploy(options               )                        {
+  checkOptions(options);
+  // RFC-0034 §4: a site Worker that joins another installation deploys only itself.
+  if ((await readProjectConfig(options.projectDir)).installation) return deployAttached(options);
+  const ctx = await loadDeploy(options);
+  const { cfg, log, previous, base, names } = ctx;
+  const { analytics, comments } = await analyticsAndComments(ctx);
+  const studioDir = await studioDirFor(ctx);
+  const { withIds, databaseCreated } = await provision(ctx);
+  // 2. secrets; 2b. RFC-0008: never deploy code that ignores holds and gates over open releases
+  const secrets = await loadOrCreateSecrets(ctx.dir);
+  if (!options.dryRun && previous?.adminUrl)
+    await downgradeGuard(options, previous.adminUrl, secrets.CLOUDHAL_DEPLOY_TOKEN, log);
+  const settings = await deploySettings(ctx);
+  const { plan, schedules, observability } = settings;
+  const site = await buildSite(ctx, { withIds, analytics, comments, observability });
+
+  // 4. admin Worker, bound to every site Worker attached to this installation (RFC-0034 §4)
+  const skillsDir = await resolveSkillsDir(options.projectDir);
+  const siteWorkers = await attachedWorkers(ctx);
+  const prepareAdmin = (ticker                 ) =>
+    prepareAdminWorker({
+      projectDir: options.projectDir,
+      dataDir: cfg.dataDir,
+      names: withIds,
+      siteId: cfg.siteId,
+      ...(cfg.sites ? { siteIds: cfg.sites } : {}),
+      siteWorkers,
+      studioDir,
+      skillsDir,
+      blockTypes: site.blockTypes,
+      themeSettings: site.themeSettings,
+      themeDesign: site.themeDesign,
+      domain: cfg.domains?.studio,
+      analytics,
+      comments,
+      scheduler: ticker,
+      schedules,
+      mail: cfg.mail,
+      ai: Boolean(cfg.ai),
+      browser: cfg.render !== false,
+      observability,
+      placement: cfg.placement,
+    });
+  const admin = await prepareAdmin(settings.scheduler);
+
+  if (options.dryRun) {
+    await must(
+      ctx.run,
+      ["deploy", "--dry-run", "--outdir", path.join(ctx.dir, "out/site")],
+      options.projectDir,
+    );
+    await must(
+      ctx.run,
+      ["deploy", "-c", admin.configPath, "--dry-run", "--outdir", path.join(ctx.dir, "out/admin")],
+      admin.dir,
+    );
+    log("dry run complete: bundles in .cloudhal/deploy/out");
+    return {
+      dryRun: true,
+      names,
+      siteConfig: site.siteConfig,
+      adminConfig: admin.configPath,
+      scheduler: settings.scheduler,
+      schedules,
+      analytics: analytics
+        ? { enabled: true, dataset: analytics.dataset, cron: settings.scheduler === "cron" }
+        : { enabled: false },
+      comments: commentsResult(comments, settings.scheduler),
+    };
+  }
+
+  const { siteUrl, adminUrl, scheduler } = await shipWorkers(ctx, {
+    secrets,
+    admin,
+    prepareAdmin,
+    scheduler: settings.scheduler,
+  });
+  // where the database lives, when a deploy of this deployment name created it
+  const jurisdiction =
+    databaseCreated ?? (previous?.name === base.name ? previous.jurisdiction : undefined);
+  await writeDeployState(options.projectDir, cfg.dataDir, {
+    name: base.name,
+    ...(adminUrl ? { adminUrl } : {}),
+    ...(siteUrl ? { siteUrl } : {}),
+    deployedAt: new Date().toISOString(),
+    ...(cfg.domains?.site ? { siteDomain: cfg.domains.site } : {}),
+    analytics: analytics ? "on" : "off",
+    comments: comments.available ? "on" : "off",
+    ...(jurisdiction ? { jurisdiction } : {}),
+    scheduler,
+    plan,
+  });
+  const pushed = await afterDeploy(ctx, { siteUrl, adminUrl });
+  const { purged, analyticsChanged, commentsChanged } = await purgeIfSwitched(ctx, {
+    siteUrl,
+    analytics,
+    comments,
+    purgeToken: secrets.CLOUDHAL_PURGE_TOKEN,
+  });
+
+  // First deploy: the owner account can only be created through this one-time link.
+  const setupUrl =
+    pushed && adminUrl
+      ? `${adminUrl.replace(/\/$/, "")}/login#setup=${secrets.CLOUDHAL_SETUP_TOKEN}`
+      : undefined;
+  return {
+    dryRun: false,
+    names,
+    siteConfig: site.siteConfig,
+    adminConfig: admin.configPath,
+    siteUrl,
+    adminUrl,
+    pushed,
+    ...(setupUrl ? { setupUrl } : {}),
+    ...(cfg.domains?.site ? { customSiteUrl: `https://${cfg.domains.site}` } : {}),
+    ...(cfg.domains?.studio ? { customStudioUrl: `https://${cfg.domains.studio}` } : {}),
+    scheduler,
+    schedules,
+    analytics: analytics
+      ? {
+          enabled: true,
+          dataset: analytics.dataset,
+          cron: scheduler === "cron",
+          purged: purged && analyticsChanged,
+        }
+      : { enabled: false, ...(purged && analyticsChanged ? { purged } : {}) },
+    comments: commentsResult(comments, scheduler, purged && commentsChanged),
+    ...(databaseCreated ? { databaseCreated } : {}),
+  };
+}

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

@@ -0,0 +1,15 @@
+import { type ProjectConfig } from "../config.js";
+export type DomainTarget = "site" | "studio";
+export interface DomainOptions {
+    readonly projectDir: string;
+    /** Hostnames to set (others stay as they are). */
+    readonly set?: {
+        readonly site?: string;
+        readonly studio?: string;
+    };
+    /** Domains to forget. */
+    readonly remove?: readonly DomainTarget[];
+}
+/** A hostname as typed → normalised, or an error that says why it cannot be used. */
+export declare function checkHostname(input: string): string;
+export declare function domain(options: DomainOptions): Promise<ProjectConfig["domains"]>;

package/dist/src/commands/domain.js

@@ -0,0 +1,44 @@
+/**
+ * `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.
+ */
+import { isHostname, normalizeHostname } from "@cloudhal/core-ts";
+import {                     readProjectConfig, writeProjectConfig } from "../config.js";
+
+                                             
+
+                                
+                              
+                                                    
+                                                                      
+                           
+                                            
+ 
+
+/** A hostname as typed → normalised, or an error that says why it cannot be used. */
+export function checkHostname(input        )         {
+  const host = normalizeHostname(input);
+  if (!isHostname(host)) throw new Error(`"${input}" is not a hostname (e.g. news.example.com)`);
+  if (host.endsWith(".workers.dev"))
+    throw new Error("workers.dev addresses are assigned by Cloudflare; set your own domain here");
+  return host;
+}
+
+export async function domain(options               )                                    {
+  const cfg = await readProjectConfig(options.projectDir);
+  const next                                     = { ...cfg.domains };
+  for (const target of options.remove ?? []) delete next[target];
+  if (options.set?.site) next.site = checkHostname(options.set.site);
+  if (options.set?.studio) next.studio = checkHostname(options.set.studio);
+  if (next.site && next.site === next.studio)
+    throw new Error("the site and Studio need different hostnames");
+  if (options.set || options.remove) {
+    const { domains: _old, ...rest } = cfg;
+    await writeProjectConfig(options.projectDir, {
+      ...rest,
+      ...(next.site || next.studio ? { domains: next } : {}),
+    });
+  }
+  return next.site || next.studio ? next : undefined;
+}

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

@@ -0,0 +1,18 @@
+export interface InitOptions {
+    readonly dir: string;
+    readonly name?: string;
+    readonly starter?: string;
+    readonly log?: (line: string) => void;
+}
+/** Walks up from `dir` to find a pnpm workspace root (so copied starters keep `workspace:*` links). */
+export declare function findWorkspaceRoot(dir: string): Promise<string | undefined>;
+export interface InitResult {
+    readonly projectDir: string;
+    readonly siteId: string;
+    /**
+     * The `@cloudhal/*` dependencies are `link:`s to the monorepo checkout this CLI runs from (its
+     * versions may not be on npm yet); such a project installs with pnpm.
+     */
+    readonly linked: boolean;
+}
+export declare function init(options: InitOptions): Promise<InitResult>;