@cloudhal/cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,114 @@
+/**
+ * Reader comments for `cloudhal studio` and `cloudhal mcp` (RFC-0007 §15.2): the project's SQLite
+ * store, and the keys from `CLOUDHAL_COMMENTS_KEY` or the data directory's `comments.key` (which
+ * `cloudhal dev` creates on the first comment request). Without a key the queue, moderation and
+ * MCP tools still work; commenter emails and stored secrets answer 503 until there is one.
+ *
+ * There is no cron on Node, so `startLocalCommentsJob` runs the admin Worker's hourly job (the
+ * same `runCommentsHourly`: retention, comments of deleted entries, threads closed by time, old
+ * salts) at start and every hour while the process runs. There is no edge cache either: the job
+ * empties the purge queue moderation filled, so nothing waits for a purge that never comes.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runCommentsHourly } from "@cloudhal/cloudflare/comments";
+import {
+                   
+  deriveCommentKeys,
+  MIN_SECRET_LENGTH,
+  randomBytes,
+  toBase64Url,
+} from "@cloudhal/comments";
+import { SqlCommentStore } from "@cloudhal/comments/sql";
+                                                        
+                                                   
+
+const usable = (k         )              => typeof k === "string" && k.length >= MIN_SECRET_LENGTH;
+
+/** The data directory's key file (`cloudhal dev` creates the same one). */
+export const LOCAL_KEY_FILE = "comments.key";
+
+/**
+ * The project's comments keys: `CLOUDHAL_COMMENTS_KEY`, else `<dataDir>/comments.key`; with
+ * `create`, a missing file is created (256 random bits, owner-only), as `cloudhal dev` does.
+ */
+export async function localCommentsKeys(
+  dataDir        ,
+  o                                                                 = {},
+)                                   {
+  const env = o.env ?? process.env;
+  let secret = env.CLOUDHAL_COMMENTS_KEY;
+  if (!usable(secret)) {
+    try {
+      secret = (await readFile(path.join(dataDir, LOCAL_KEY_FILE), "utf8")).trim();
+    } catch {
+      secret = undefined;
+    }
+  }
+  if (!usable(secret) && o.create) {
+    secret = toBase64Url(randomBytes(32));
+    await writeFile(path.join(dataDir, LOCAL_KEY_FILE), `${secret}\n`, { mode: 0o600 });
+  }
+  return usable(secret) ? deriveCommentKeys(secret) : undefined;
+}
+
+export async function localComments(
+  sql           ,
+  dataDir        ,
+  env                                     = process.env,
+) {
+  const keys = await localCommentsKeys(dataDir, { env });
+  const store = new SqlCommentStore(sql);
+  return {
+    store,
+    ...(keys ? { keys } : {}),
+    // no edge cache locally: a queued purge is done at once (Studio shows nothing waiting)
+    onQueued: (siteId        ) => {
+      drainPurgeQueue(store, siteId).catch(() => {});
+    },
+  };
+}
+
+/** Empties a site's (or every site's) comment purge queue: locally there is nothing to purge. */
+export async function drainPurgeQueue(store                 , siteId         )                  {
+  let drained = 0;
+  for (const id of siteId ? [siteId] : await store.purgeQueue.sites()) {
+    const r = await store.sql.run("DELETE FROM comment_purge_queue WHERE site_id = ?", [id]);
+    drained += r.changes;
+  }
+  return drained;
+}
+
+/** One run of the local hourly job; returns what it did (for logs and tests). */
+export async function runLocalCommentsJob(
+  graph                ,
+  store                 ,
+  now       = new Date(),
+) {
+  const report = await runCommentsHourly({ graph, store, now });
+  return { ...report, drained: await drainPurgeQueue(store) };
+}
+
+/**
+ * Starts the hourly comments job on its own timer: once now, then every hour; errors are logged,
+ * never thrown. Returns a stop function.
+ *
+ * @deprecated `cloudhal studio`, `mcp` and `dev` run the job as the `comments.hourly` system job
+ * of the scheduler's Node ticker (RFC-0008 §8.4, `scheduler-local.ts`).
+ */
+export function startLocalCommentsJob(
+  graph                ,
+  store                 ,
+  log                         = (l) => process.stderr.write(`${l}\n`),
+  intervalMs = 3_600_000,
+)             {
+  const tick = () => {
+    runLocalCommentsJob(graph, store).catch((e) =>
+      log(`comments hourly job failed: ${e instanceof Error ? e.message : String(e)}`),
+    );
+  };
+  tick();
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}

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

@@ -0,0 +1,45 @@
+import { type CommentsStatus, type ImportProblem } from "@cloudhal/comments/sql";
+import { type SyncOptions } from "./sync.js";
+export interface CommentsCliOptions extends SyncOptions {
+    /** Talk to the deployment (deployment token) instead of the local SQLite. */
+    readonly remote?: boolean;
+}
+export interface CommentsStatusResult extends CommentsStatus {
+    /** The comments key is there (emails and stored secrets can be read). */
+    readonly key: boolean;
+    /** `cloudhal.json` `comments.available` (local), or the deployment answered (remote). */
+    readonly available: boolean;
+    readonly where: "local" | "remote";
+}
+/** `cloudhal comments status [--remote]`: counts, pending, the daily cap and the purge queue. */
+export declare function commentsStatusCli(options: CommentsCliOptions & {
+    readonly now?: () => Date;
+}): Promise<CommentsStatusResult>;
+export declare function describeCommentsStatus(s: CommentsStatusResult): string[];
+export interface CommentsExportCliOptions extends CommentsCliOptions {
+    /** Also export commenters' emails (`--with-personal-data`). */
+    readonly personal?: boolean;
+    /** Write here instead of returning the text. */
+    readonly out?: string;
+    readonly now?: () => Date;
+}
+/** `cloudhal comments export [--remote] [--with-personal-data] [--out file]`. */
+export declare function commentsExportCli(options: CommentsExportCliOptions): Promise<{
+    text: string;
+    comments: number;
+    commenters: number;
+}>;
+export interface CommentsImportCliOptions extends CommentsCliOptions {
+    /** The JSON-lines file (`--in`). */
+    readonly file: string;
+    readonly now?: () => Date;
+}
+export interface CommentsImportResult {
+    readonly imported: number;
+    readonly skipped: number;
+    readonly commenters: number;
+    /** Line numbers are the file's. */
+    readonly invalid: readonly ImportProblem[];
+}
+/** `cloudhal comments import --in <file> [--remote]`: idempotent; safe to run again. */
+export declare function commentsImportCli(options: CommentsImportCliOptions): Promise<CommentsImportResult>;

package/dist/src/commands/comments.js

@@ -0,0 +1,285 @@
+/**
+ * `cloudhal comments status|export|import` (RFC-0007 §9.4, §15.4, D8). Comments are not in
+ * push/pull bundles: they move as JSON lines (a header, then `Comment` records oldest first, then,
+ * with `--with-personal-data`, commenter lines with their email).
+ *
+ * Locally the commands work on the project's SQLite; `--remote` talks to the deployment's admin
+ * Worker with the deployment token (`/api/admin/sites/:siteId/comments/…`): the export is fetched
+ * page by page, the import sent in batches of at most 50 lines. Import is idempotent (by id, and
+ * by importer origin), so an interrupted import can simply be run again. Replies whose parent
+ * arrives in a later batch are retried once at the end.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+                      
+  commentsStatus,
+  exportPage,
+                     
+                    
+  importLines,
+  PARENT_MISSING,
+  SqlCommentStore,
+} from "@cloudhal/comments/sql";
+import { openLocalStore } from "@cloudhal/core-ts/local";
+import { commentsAvailable, readProjectConfig } from "../config.js";
+import { localComments, localCommentsKeys } from "./comments-local.js";
+import { brief, deployment,                  } from "./sync.js";
+
+                                                         
+                                                                               
+                            
+ 
+
+/** Lines per import request, and their size (the admin route takes 200 lines). */
+const BATCH_LINES = 50;
+const BATCH_BYTES = 1024 * 1024;
+
+                                                              
+                                                                           
+                        
+                                                                                           
+                              
+                                     
+ 
+
+async function remote(
+  options             ,
+  pathname        ,
+  init              = {},
+)                    {
+  const { cfg, adminUrl, token, fetch: f } = await deployment(options);
+  const url = new URL(
+    `/api/admin/sites/${encodeURIComponent(cfg.siteId)}/comments${pathname}`,
+    adminUrl,
+  );
+  const res = await f(url, {
+    ...init,
+    headers: { authorization: `Bearer ${token}`, "content-type": "application/x-ndjson" },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(
+      res.status === 404 && /not enabled/.test(body)
+        ? "reader comments are not available on this deployment (comments.available is false, or the Workers have no CLOUDHAL_COMMENTS_KEY yet: run `cloudhal deploy`)"
+        : `${url.pathname} failed (${res.status}): ${brief(body)}`,
+    );
+  }
+  return res;
+}
+
+/** `cloudhal comments status [--remote]`: counts, pending, the daily cap and the purge queue. */
+export async function commentsStatusCli(
+  options                                                    ,
+)                                {
+  if (options.remote) {
+    const s = (await (await remote(options, "/status")).json())                      
+                   
+     ;
+    return { ...s, available: true, where: "remote" };
+  }
+  const cfg = await readProjectConfig(options.projectDir);
+  const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+  try {
+    const c = await localComments(local.sql, local.dataDir);
+    const s = await commentsStatus(c.store, cfg.siteId, options.now?.() ?? new Date());
+    return { ...s, key: Boolean(c.keys), available: commentsAvailable(cfg), where: "local" };
+  } finally {
+    await local.close();
+  }
+}
+
+export function describeCommentsStatus(s                      )           {
+  const c = s.counts;
+  const age = (at               ) => {
+    if (!at) return "";
+    const h = Math.max(0, Math.round((Date.now() - Date.parse(at)) / 3_600_000));
+    return h < 1 ? " (oldest under an hour)" : ` (oldest ${h} h)`;
+  };
+  return [
+    `comments: ${s.available ? "available" : "unavailable"} for this ${s.where === "remote" ? "deployment" : "project (cloudhal.json)"}${s.key ? "" : "; no comments key yet, so emails and stored secrets cannot be read"}`,
+    `site ${s.siteId}: ${s.settings.enabled ? "on" : "off"}${s.settings.stored ? "" : " (never turned on)"}${s.settings.enabled ? ` · collections ${s.settings.collections.join(", ") || "none"} · ${s.settings.protection === "turnstile" ? "Turnstile" : "proof of work"}${s.settings.allowWithoutScript ? " · posts without JavaScript allowed" : ""} · threads close ${s.settings.closeAfterDays === null ? "never" : `after ${s.settings.closeAfterDays} days`}` : ""}`,
+    `comments: ${c.approved} approved · ${c.pending} pending${age(s.pending.oldestAt)} · ${c.reported} reported · ${c.hidden} hidden · ${c.spam} spam · ${c.deleted} deleted`,
+    `today (UTC): ${s.today.stored} of ${s.today.cap} stored submissions${s.today.withoutScript ? ` (${s.today.withoutScript} without JavaScript)` : ""}${s.today.paused ? " · PAUSED until midnight UTC" : ""}`,
+    `purge queue: ${s.purge.queued} tag(s)${s.purge.takedowns ? `, ${s.purge.takedowns} takedown(s)` : ""}${s.purge.oldestAt ? `, oldest ${s.purge.oldestAt}` : ""} · purge requests in the last minute: ${s.purge.lastMinute} (Workers Cache allows 5 a minute)`,
+  ];
+}
+
+                                                                      
+                                                                 
+                              
+                                                  
+                        
+                            
+ 
+
+/** `cloudhal comments export [--remote] [--with-personal-data] [--out file]`. */
+export async function commentsExportCli(
+  options                          ,
+)                                                                  {
+  const lines           = [];
+  let comments = 0;
+  let commenters = 0;
+  const count = (page          ) => {
+    for (const l of page) {
+      if (l.startsWith('{"commenter"')) commenters++;
+      else if (!l.startsWith('{"cloudhal"')) comments++;
+    }
+  };
+  if (options.remote) {
+    let cursor                    ;
+    for (let calls = 0; calls < 100_000; calls++) {
+      const q = new URLSearchParams({
+        ...(cursor ? { cursor } : {}),
+        ...(options.personal ? { personal: "1" } : {}),
+      });
+      const res = await remote(options, `/export${q.size ? `?${q}` : ""}`);
+      const page = (await res.text()).split("\n").filter((l) => l.trim() !== "");
+      count(page);
+      lines.push(...page);
+      cursor = res.headers.get("cloudhal-next-cursor") ?? undefined;
+      options.log?.(
+        `exported ${comments} comment(s)${commenters ? `, ${commenters} commenter(s)` : ""}`,
+      );
+      if (!cursor) break;
+    }
+  } else {
+    const cfg = await readProjectConfig(options.projectDir);
+    const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+    try {
+      const c = await localComments(local.sql, local.dataDir);
+      if (options.personal && !c.keys)
+        throw new Error(
+          "no comments key in this project (.cloudhal/comments.key or CLOUDHAL_COMMENTS_KEY), so there are no readable emails to export",
+        );
+      let cursor                    ;
+      for (;;) {
+        const page = await exportPage(c.store, cfg.siteId, {
+          cursor,
+          personal: options.personal,
+          keys: c.keys,
+          now: options.now?.() ?? new Date(),
+        });
+        count(page.lines);
+        lines.push(...page.lines);
+        cursor = page.next;
+        if (!cursor) break;
+      }
+    } finally {
+      await local.close();
+    }
+  }
+  const text = `${lines.join("\n")}\n`;
+  if (options.out)
+    await writeFile(path.resolve(options.projectDir, options.out), text, {
+      // personal data: readable by the owner only
+      mode: options.personal ? 0o600 : 0o644,
+    });
+  return { text, comments, commenters };
+}
+
+                                                                      
+                                      
+                        
+                            
+ 
+
+                                       
+                            
+                           
+                              
+                                     
+                                             
+ 
+
+/** `cloudhal comments import --in <file> [--remote]`: idempotent; safe to run again. */
+export async function commentsImportCli(
+  options                          ,
+)                                {
+  const text = await readFile(path.resolve(options.projectDir, options.file), "utf8");
+  const all = text.split("\n").map((l, i) => ({ line: i + 1, text: l }));
+  const filled = all.filter((l) => l.text.trim() !== "");
+  const first = filled[0];
+  if (!first) throw new Error(`${options.file} is empty`);
+  try {
+    const head = JSON.parse(first.text)                                             ;
+    if (head.cloudhal !== "comments" || head.version !== 1) throw new Error("no header");
+  } catch {
+    throw new Error(
+      `${options.file} is not a Cloudhal comments export (the first line must be {"cloudhal":"comments","version":1,…})`,
+    );
+  }
+
+  let send                                            ;
+  let close = async () => {};
+  if (options.remote) {
+    send = async (lines) =>
+      (await (
+        await remote(options, "/import", { method: "POST", body: `${lines.join("\n")}\n` })
+      ).json())                ;
+  } else {
+    const cfg = await readProjectConfig(options.projectDir);
+    const local = await openLocalStore(path.join(options.projectDir, cfg.dataDir));
+    close = () => local.close();
+    const personal = filled.some((l) => l.text.startsWith('{"commenter"'));
+    // emails are encrypted under the project's key: create it when the file brings some
+    const keys = await localCommentsKeys(local.dataDir, { create: personal });
+    const store = new SqlCommentStore(local.sql);
+    send = (lines) =>
+      importLines(store, cfg.siteId, lines, {
+        keys,
+        now: options.now?.() ?? new Date(),
+        entries: async (ids) => {
+          const wanted = new Set(ids);
+          const found = new Set        ();
+          for (const e of await local.store.listContentEntries(cfg.siteId))
+            if (wanted.has(e.id)) found.add(e.id);
+          return found;
+        },
+      });
+  }
+
+  let imported = 0;
+  let skipped = 0;
+  let commenters = 0;
+  const invalid                  = [];
+  const run = async (batch                                  ) => {
+    const r = await send(batch.map((l) => l.text));
+    imported += r.imported;
+    skipped += r.skipped;
+    commenters += r.commenters;
+    const refused = r.invalid.map((p) => ({ ...p, line: batch[p.line - 1]?.line ?? p.line }));
+    options.log?.(`imported ${imported}, already there ${skipped}`);
+    return refused;
+  };
+  try {
+    const later                                   = [];
+    const lineOf = new Map(filled.map((l) => [l.line, l]));
+    let batch                                   = [];
+    let bytes = 0;
+    const flush = async () => {
+      if (batch.length === 0) return;
+      for (const p of await run(batch)) {
+        // a reply whose parent is in a later batch: once more at the end
+        const l = lineOf.get(p.line);
+        if (p.error === PARENT_MISSING && l) later.push(l);
+        else invalid.push(p);
+      }
+      batch = [];
+      bytes = 0;
+    };
+    for (const l of filled) {
+      if (batch.length >= BATCH_LINES || (batch.length > 0 && bytes + l.text.length > BATCH_BYTES))
+        await flush();
+      batch.push(l);
+      bytes += l.text.length;
+    }
+    await flush();
+    for (let i = 0; i < later.length; i += BATCH_LINES)
+      invalid.push(...(await run(later.slice(i, i + BATCH_LINES))));
+  } finally {
+    await close();
+  }
+  invalid.sort((a, b) => a.line - b.line);
+  return { imported, skipped, commenters, invalid };
+}

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

@@ -0,0 +1,2 @@
+import type { DeployOptions, DeployResult } from "./options.js";
+export declare function deployAttached(options: DeployOptions): Promise<DeployResult>;

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

@@ -0,0 +1,190 @@
+/**
+ * `cloudhal deploy` in a project with `cloudhal.json` `installation` (RFC-0034 §4): a site Worker
+ * for another theme that joins an existing installation instead of creating one.
+ *
+ * - It binds the installation's D1 database, R2 bucket and analytics dataset (its names derive
+ *   from the installation's deployment name) and takes the installation's preview, purge, comments
+ *   and deployment secrets, so previews, purges and comments work across both Workers.
+ * - Only the site Worker is deployed (`<installation>-site-<slug>`); the installation's Studio
+ *   stays where it is. The served sites must exist on the installation and use this theme.
+ * - It registers itself (`PUT /api/admin/site-workers/:name`). The installation's next
+ *   `cloudhal deploy` binds it to the admin Worker, which from then on sends these sites' purges
+ *   here; until then they go to the installation's own site Worker.
+ */
+import { chmod, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readExistingIds, SITE_CONFIG_FILE, workerNames } from "../../cloudflare/config.js";
+import { deployedUrls, must } from "../../cloudflare/wrangler.js";
+import { readProjectConfig } from "../../config.js";
+import { listSites } from "../site.js";
+import { pushSite, setPrimaryDomain } from "../sync.js";
+                                                  
+                                                                
+import { analyticsAndComments, buildSite, deploySettings, loadDeploy } from "./prepare.js";
+import { deployDir, loadOrCreateSecrets, readDeployState, writeDeployState } from "./state.js";
+
+/** The secrets an attached site Worker shares with its installation. */
+const SHARED = [
+  "CLOUDHAL_PREVIEW_SECRET",
+  "CLOUDHAL_PURGE_TOKEN",
+  "CLOUDHAL_COMMENTS_KEY",
+  "CLOUDHAL_DEPLOY_TOKEN",
+]         ;
+
+async function installationOf(projectDir        , folder        ) {
+  const dir = path.resolve(projectDir, folder);
+  const cfg = await readProjectConfig(dir).catch(() => {
+    throw new Error(`cloudhal.json installation: no Cloudhal project in ${dir}`);
+  });
+  const state = await readDeployState(dir, cfg.dataDir);
+  if (!state?.adminUrl)
+    throw new Error(
+      `cloudhal.json installation: ${dir} is not deployed yet (run \`cloudhal deploy\` there first)`,
+    );
+  const secrets = JSON.parse(
+    await readFile(path.join(deployDir(dir, cfg.dataDir), "secrets.json"), "utf8"),
+  )                          ;
+  const { databaseId } = await readExistingIds(path.join(dir, SITE_CONFIG_FILE));
+  if (!databaseId) throw new Error(`cloudhal.json installation: no D1 database id in ${dir}`);
+  return { dir, cfg, state: { ...state, adminUrl: state.adminUrl }, secrets, databaseId };
+}
+
+export async function deployAttached(options               )                        {
+  const own = await readProjectConfig(options.projectDir);
+  const inst = await installationOf(options.projectDir, own.installation          );
+  const loaded = await loadDeploy({ ...options, name: inst.state.name });
+  const base = { ...loaded.base, siteName: `${inst.state.name}-site-${loaded.site.slug}` };
+  const previous = {
+    ...(loaded.previous ?? inst.state),
+    name: inst.state.name,
+    adminUrl: inst.state.adminUrl,
+  };
+  const ctx                = { ...loaded, base, names: workerNames(base), previous };
+  const { cfg, log, names } = ctx;
+  log(`joining the installation ${inst.state.name} (${inst.dir}) as ${names.site}`);
+
+  // The installation's secrets, kept here too so remote commands (push, pull) reach it.
+  const secrets = await loadOrCreateSecrets(ctx.dir);
+  for (const key of SHARED) if (inst.secrets[key]) secrets[key] = inst.secrets[key];
+  const secretsFile = path.join(ctx.dir, "secrets.json");
+  await writeFile(secretsFile, `${JSON.stringify(secrets, null, 2)}\n`, { mode: 0o600 });
+  await chmod(secretsFile, 0o600);
+
+  const { analytics, comments } = await analyticsAndComments(ctx);
+  const { observability, scheduler, schedules, plan } = await deploySettings(ctx);
+  const withIds = { ...base, databaseId: inst.databaseId };
+  const site = await buildSite(ctx, { withIds, analytics, comments, observability });
+  const result = {
+    names,
+    siteConfig: site.siteConfig,
+    adminConfig: "",
+    scheduler,
+    schedules,
+    analytics: analytics ? { enabled: true, dataset: analytics.dataset } : { enabled: false },
+    comments: { available: comments.available },
+  };
+  if (options.dryRun) {
+    await must(
+      ctx.run,
+      ["deploy", "--dry-run", "--outdir", path.join(ctx.dir, "out/site")],
+      options.projectDir,
+    );
+    log("dry run complete: the site Worker's bundle is in .cloudhal/deploy/out");
+    return { dryRun: true, ...result };
+  }
+
+  const siteSecrets = path.join(ctx.dir, "site-secrets.json");
+  let siteUrl                    ;
+  try {
+    await writeFile(
+      siteSecrets,
+      JSON.stringify({
+        CLOUDHAL_PREVIEW_SECRET: secrets.CLOUDHAL_PREVIEW_SECRET,
+        CLOUDHAL_PURGE_TOKEN: secrets.CLOUDHAL_PURGE_TOKEN,
+        CLOUDHAL_COMMENTS_KEY: secrets.CLOUDHAL_COMMENTS_KEY,
+      }),
+      { mode: 0o600 },
+    );
+    log(`deploying ${names.site}`);
+    const deployed = await must(
+      ctx.run,
+      ["deploy", "--secrets-file", siteSecrets],
+      options.projectDir,
+    );
+    siteUrl = deployedUrls(deployed.records)[0];
+  } finally {
+    await rm(siteSecrets, { force: true });
+  }
+  await writeDeployState(options.projectDir, cfg.dataDir, {
+    name: inst.state.name,
+    adminUrl: inst.state.adminUrl,
+    ...(siteUrl ? { siteUrl } : {}),
+    deployedAt: new Date().toISOString(),
+    analytics: analytics ? "on" : "off",
+    comments: comments.available ? "on" : "off",
+    scheduler,
+    plan,
+  });
+  // This project's own site joins the installation if it is not there yet.
+  const { pushed } = await pushSite({
+    projectDir: options.projectDir,
+    adminUrl: inst.state.adminUrl,
+    ifAbsent: true,
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+    log,
+  });
+  await register(ctx, {
+    adminUrl: inst.state.adminUrl,
+    token: secrets.CLOUDHAL_DEPLOY_TOKEN,
+    siteUrl,
+  });
+  // A site without a hostname gets the Worker's workers.dev address as its primary one, as a
+  // first deploy does: previews, hreflang across editions and same-origin checks need one.
+  if (siteUrl) {
+    const sites = await listSites({
+      projectDir: options.projectDir,
+      remote: true,
+      adminUrl: inst.state.adminUrl,
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    if (sites.find((x) => x.id === cfg.siteId)?.hosts.length === 0)
+      await setPrimaryDomain({
+        projectDir: options.projectDir,
+        adminUrl: inst.state.adminUrl,
+        hostname: new URL(siteUrl).host,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+      });
+  }
+  log(
+    `run \`cloudhal deploy\` in ${inst.dir} once, so the installation's Studio sends these sites' cache purges to ${names.site}`,
+  );
+  return {
+    dryRun: false,
+    ...result,
+    ...(siteUrl ? { siteUrl } : {}),
+    adminUrl: inst.state.adminUrl,
+    pushed,
+  };
+}
+
+async function register(
+  ctx               ,
+  input                                                                  ,
+)                {
+  const { cfg, site, names, options, log } = ctx;
+  const f = options.fetch ?? fetch;
+  const res = await f(new URL(`/api/admin/site-workers/${names.site}`, input.adminUrl), {
+    method: "PUT",
+    headers: { authorization: `Bearer ${input.token}`, "content-type": "application/json" },
+    body: JSON.stringify({
+      url: input.siteUrl ?? `https://${names.site}.workers.dev`,
+      theme: site.theme.name,
+      siteIds: cfg.sites ?? [cfg.siteId],
+    }),
+  });
+  if (!res.ok)
+    throw new Error(
+      `registering ${names.site} failed: ${res.status} ${(await res.text()).slice(0, 300)}`,
+    );
+  log(`registered ${names.site} with the installation`);
+}

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

@@ -0,0 +1,21 @@
+/** What every phase of `cloudhal deploy` reads: the options, the project, its site and names. */
+import type { Site } from "@cloudhal/core-contracts";
+import type { DeploymentNames, workerNames } from "../../cloudflare/config.js";
+import type { WranglerRunner } from "../../cloudflare/wrangler.js";
+import type { ProjectConfig } from "../../config.js";
+import type { DeployOptions } from "./options.js";
+import type { DeployState } from "./state.js";
+export interface DeployContext {
+    readonly options: DeployOptions;
+    readonly log: (line: string) => void;
+    /** `cloudhal.json`, with the analytics decision made (asked once in a terminal). */
+    readonly cfg: ProjectConfig;
+    /** `<dataDir>/deploy`: secrets, state and generated configs. */
+    readonly dir: string;
+    readonly run: WranglerRunner;
+    readonly site: Site;
+    /** The last deploy of this project, if any. */
+    readonly previous: DeployState | undefined;
+    readonly base: DeploymentNames;
+    readonly names: ReturnType<typeof workerNames>;
+}

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

@@ -0,0 +1,22 @@
+/** What every phase of `cloudhal deploy` reads: the options, the project, its site and names. */
+                                                     
+                                                                               
+                                                                   
+                                                     
+                                                  
+                                              
+
+                                
+                                  
+                                       
+                                                                                      
+                              
+                                                                  
+                       
+                               
+                      
+                                                 
+                                             
+                                 
+                                                 
+