@caelo-cms/provisioning 0.10.52 → 0.10.55

package/src/audit-job-setup.ts

@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #875 — set up (and converge) the parallel quality-audit job on a Google
+ * Cloud install (`gcp`, `gcp-firebase`). Run by the wizard after `pulumi up`
+ * and by `cms-provision upgrade`'s converge, both as the operator's own
+ * gcloud identity. App-roll moves the job's image with the admin's
+ * (upgrade/app-roll.ts), because the job runs the admin image.
+ *
+ * Why a separate job at all (CLAUDE.md §11.B Tier 5 exception): Lighthouse
+ * is CPU-bound and simulates the CPU slowdown from observed task durations,
+ * so a run that shares a CPU with another run or with the editor's chat
+ * measures that interference too. One task per run measures the page alone,
+ * and all runs finish in about the time of one.
+ *
+ * Why the CLI owns it and not the stacks: `upgrade` never runs Pulumi, so
+ * existing installs get the job only from here, and a bucket or job both
+ * Pulumi and `upgrade` create would collide on the next wizard re-run (the
+ * same reasoning as operator-access.ts and upgrader-setup.ts).
+ *
+ * Trust boundary. The job's service account, `caelo-<env>-audit`, holds:
+ *
+ *   - `roles/storage.objectCreator` on the audit results bucket — create
+ *     only: it can neither read results back nor overwrite one;
+ *   - on `gcp` only, `roles/storage.objectViewer` on the staging and static
+ *     buckets: it serves the staged build to its own browser, as the admin's
+ *     audit does (admin-core quality/staged-origin.ts). gcp-firebase audits
+ *     the public preview channel and needs no bucket;
+ *   - `roles/logging.logWriter`.
+ *
+ * Nothing else: no Secret Manager, no Cloud SQL, and no VPC egress, so the
+ * database's private IP is not even routable from a task. Plugin data on a
+ * page comes the way any visitor gets it: the task's browser calls the
+ * site's public `/api/*` (the gateway, behind Cloud Armor) over the
+ * internet. The admin's run
+ * SA may run the job WITH overrides (`roles/run.jobsExecutorWithOverrides`:
+ * it passes each audit's batch of orders), read its executions
+ * (`roles/run.viewer`) and read the results bucket. Unlike the
+ * operator-access and upgrader jobs, overrides are acceptable here: a
+ * compromised admin can make the job load other URLs, but the job holds
+ * nothing worth taking. {@link AUDIT_FORBIDDEN_ROLES} names that line; the
+ * tests assert no grant crosses it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gcloud as defaultGcloud, type GcloudResult } from "./gcloud.js";
+import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
+import {
+  auditJobName,
+  auditServiceAccountEmail,
+  auditServiceAccountId,
+  gcpBucketName,
+  runServiceAccountEmail,
+} from "./gcp-names.js";
+import { readAdminConfig } from "./migration-runner.js";
+import type { GcpProvider } from "./stack-contract.js";
+import { describeAuditJobImage } from "./upgrade/audit-job-roll.js";
+
+/** Where the admin image ships the task's entry point. */
+export const AUDIT_TASK_SCRIPT = "/app/packages/admin-core/src/quality/audit-task.ts";
+
+/** How many audit tasks run at once by default: 5 pages x 3 runs. */
+export const AUDIT_PARALLELISM_DEFAULT = 15;
+
+/**
+ * Per task: container start, browser start, CPU benchmark and one
+ * Lighthouse run. Matches admin-core `parallelAuditTimeoutMs`, which the
+ * admin also passes per execution.
+ */
+const TASK_TIMEOUT = "5m";
+
+/**
+ * Roles the audit job's identity must never hold anywhere. Prefix matches
+ * (`roles/secretmanager.` = every Secret Manager role).
+ */
+export const AUDIT_FORBIDDEN_ROLES = [
+  "roles/owner",
+  "roles/editor",
+  "roles/run.",
+  "roles/iam.",
+  "roles/secretmanager.",
+  "roles/cloudsql.",
+  "roles/compute.",
+  "roles/resourcemanager.",
+  "roles/storage.admin",
+  "roles/storage.objectAdmin",
+  "roles/storage.objectUser",
+] as const;
+
+/** Delete results after a day: the admin reads them within minutes. */
+export const AUDIT_RESULTS_LIFECYCLE = {
+  rule: [{ action: { type: "Delete" }, condition: { age: 1 } }],
+};
+
+export interface AuditJobTarget {
+  readonly provider: GcpProvider;
+  readonly projectId: string;
+  readonly region: string;
+  /** Pulumi stack name (`production`). */
+  readonly env: string;
+  /** The admin image the job runs, digest-pinned (`…/admin@sha256:…`). */
+  readonly adminImageRef: string;
+  /**
+   * Tasks at once (`auditParallelism`, 1–15). Absent on converge: an
+   * existing job keeps the value it has, so an operator's choice survives
+   * `upgrade`; a job the converge creates gets
+   * {@link AUDIT_PARALLELISM_DEFAULT}, as a fresh install's does.
+   */
+  readonly parallelism?: number;
+}
+
+export type AuditJobResult =
+  | { readonly ok: true; readonly done: string[] }
+  | { readonly ok: false; readonly done: string[]; readonly error: string };
+
+/** Ensure the audit job and everything it needs. Never throws for a gcloud failure. */
+export async function ensureAuditJob(
+  target: AuditJobTarget,
+  deps: { run?: GcloudRunner; sleep?: Sleep } = {},
+): Promise<AuditJobResult> {
+  const run = deps.run ?? defaultGcloud;
+  const sleep = deps.sleep ?? realSleep;
+  const retry = (args: string[]) => runWithRetry(run, sleep, args);
+  const { projectId, region, env, provider } = target;
+  const project = `--project=${projectId}`;
+  const sa = auditServiceAccountEmail(projectId, env);
+  const member = `serviceAccount:${sa}`;
+  const runSaMember = `serviceAccount:${runServiceAccountEmail(projectId, env)}`;
+  const job = auditJobName(env);
+  const results = gcpBucketName(projectId, env, "audit-results");
+  const resultsUrl = `gs://${results}`;
+  const done: string[] = [];
+  const fail = (step: string, r: GcloudResult): AuditJobResult => ({
+    ok: false,
+    done,
+    error: `${step}: ${r.stderr.trim()}`,
+  });
+
+  if (!/@sha256:[0-9a-f]{64}$/.test(target.adminImageRef)) {
+    return {
+      ok: false,
+      done,
+      error: `the audit job's image must be pinned by digest, got ${target.adminImageRef}`,
+    };
+  }
+  if (
+    target.parallelism !== undefined &&
+    (!Number.isInteger(target.parallelism) || target.parallelism < 1 || target.parallelism > 15)
+  ) {
+    return {
+      ok: false,
+      done,
+      error: `auditParallelism must be a whole number from 1 to 15, got ${target.parallelism}`,
+    };
+  }
+
+  // 1. The job's own service account.
+  const describe = await run([
+    "iam",
+    "service-accounts",
+    "describe",
+    sa,
+    project,
+    "--format=value(email)",
+  ]);
+  if (!describe.ok) {
+    const create = await run([
+      "iam",
+      "service-accounts",
+      "create",
+      auditServiceAccountId(env),
+      "--display-name=Caelo quality audit",
+      "--description=Runs the quality audit's Lighthouse runs in parallel; reads the staged build, writes audit results, nothing else.",
+      project,
+    ]);
+    if (!create.ok && !/already exists/i.test(create.stderr)) return fail(`create ${sa}`, create);
+  }
+  done.push(`service account ${sa}`);
+
+  // 2. The results bucket: private, results deleted after a day.
+  const owned = await run(["storage", "buckets", "list", project, "--format=value(name)"]);
+  if (!owned.ok) return fail(`list the buckets of project ${projectId}`, owned);
+  const names = owned.stdout.split("\n").map((l) =>
+    l
+      .trim()
+      .replace(/^gs:\/\//, "")
+      .replace(/\/$/, ""),
+  );
+  if (!names.includes(results)) {
+    const created = await run([
+      "storage",
+      "buckets",
+      "create",
+      resultsUrl,
+      project,
+      `--location=${region}`,
+      "--default-storage-class=STANDARD",
+      "--uniform-bucket-level-access",
+      "--public-access-prevention",
+      "--soft-delete-duration=0",
+    ]);
+    if (!created.ok) {
+      return {
+        ok: false,
+        done,
+        error: /already exists|409/i.test(created.stderr)
+          ? `${resultsUrl} exists but does not belong to project ${projectId}; delete or rename that bucket, this install needs the name`
+          : `create ${resultsUrl}: ${created.stderr.trim()}`,
+      };
+    }
+  }
+  // A private directory (mkdtemp, mode 700): no other local user can swap
+  // the file between write and read.
+  const dir = mkdtempSync(join(tmpdir(), "caelo-audit-"));
+  try {
+    const file = join(dir, "lifecycle.json");
+    writeFileSync(file, JSON.stringify(AUDIT_RESULTS_LIFECYCLE), { mode: 0o600 });
+    const lifecycle = await run([
+      "storage",
+      "buckets",
+      "update",
+      resultsUrl,
+      project,
+      `--lifecycle-file=${file}`,
+    ]);
+    if (!lifecycle.ok) return fail(`set the lifecycle of ${resultsUrl}`, lifecycle);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  done.push(`bucket ${resultsUrl} (results deleted after 1 day)`);
+
+  // 3. Bucket grants: the job creates results and (gcp) reads the build;
+  //    the admin reads results.
+  const bucketGrants: { bucket: string; member: string; role: string; why: string }[] = [
+    { bucket: results, member, role: "roles/storage.objectCreator", why: "tasks write results" },
+    ...(provider === "gcp"
+      ? (["staging", "static"] as const).map((b) => ({
+          bucket: gcpBucketName(projectId, env, b),
+          member,
+          role: "roles/storage.objectViewer",
+          why: "tasks serve the staged build to their browser",
+        }))
+      : []),
+    {
+      bucket: results,
+      member: runSaMember,
+      role: "roles/storage.objectViewer",
+      why: "the admin reads the results",
+    },
+  ];
+  for (const g of bucketGrants) {
+    const r = await retry([
+      "storage",
+      "buckets",
+      "add-iam-policy-binding",
+      `gs://${g.bucket}`,
+      `--member=${g.member}`,
+      `--role=${g.role}`,
+      project,
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!r.ok) return fail(`grant ${g.role} on gs://${g.bucket} (${g.why})`, r);
+    done.push(`${g.member === member ? "audit job" : "admin"}: ${g.role} on gs://${g.bucket}`);
+  }
+
+  // 4. Logs.
+  const logs = await retry([
+    "projects",
+    "add-iam-policy-binding",
+    projectId,
+    `--member=${member}`,
+    "--role=roles/logging.logWriter",
+    "--condition=None",
+    "--quiet",
+    "--format=none",
+  ]);
+  if (!logs.ok) return fail("grant the audit job roles/logging.logWriter", logs);
+  done.push("audit job: roles/logging.logWriter on the project");
+
+  // 5. The job: the admin image, its own SA, no secrets, no VPC. A job
+  //    created without a parallelism would run every task at once with no
+  //    cap; an existing job keeps its own.
+  let parallelism = target.parallelism;
+  if (parallelism === undefined) {
+    const existing = await describeAuditJobImage(run, { projectId, region, env });
+    if (!existing.ok) return { ok: false, done, error: `read job ${job}: ${existing.error}` };
+    if (existing.image === null) parallelism = AUDIT_PARALLELISM_DEFAULT;
+  }
+  const envVars = [
+    `CAELO_PROVIDER=${provider}`,
+    `CAELO_AUDIT_RESULTS_BUCKET=${results}`,
+    ...(provider === "gcp"
+      ? [
+          `CAELO_STAGING_BUCKET=${gcpBucketName(projectId, env, "staging")}`,
+          `CAELO_STATIC_BUCKET=${gcpBucketName(projectId, env, "static")}`,
+        ]
+      : []),
+  ];
+  const deploy = await run([
+    "run",
+    "jobs",
+    "deploy",
+    job,
+    `--image=${target.adminImageRef}`,
+    `--region=${region}`,
+    project,
+    `--service-account=${sa}`,
+    "--command=bun",
+    `--args=--bun,${AUDIT_TASK_SCRIPT}`,
+    `--set-env-vars=${envVars.join(",")}`,
+    "--max-retries=0",
+    `--task-timeout=${TASK_TIMEOUT}`,
+    // Lighthouse wants two cores: the browser and the trace processing.
+    "--cpu=2",
+    "--memory=2Gi",
+    ...(parallelism !== undefined ? [`--parallelism=${parallelism}`] : []),
+    "--quiet",
+  ]);
+  if (!deploy.ok) return fail(`deploy job ${job}`, deploy);
+  done.push(`job ${job} (${target.adminImageRef.split("@")[1]?.slice(0, 19)}...)`);
+
+  // 6. The admin may run it with its batch and read its executions.
+  for (const role of ["roles/run.jobsExecutorWithOverrides", "roles/run.viewer"]) {
+    const r = await retry([
+      "run",
+      "jobs",
+      "add-iam-policy-binding",
+      job,
+      `--region=${region}`,
+      project,
+      `--member=${runSaMember}`,
+      `--role=${role}`,
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!r.ok) return fail(`grant the admin ${role} on ${job}`, r);
+    done.push(`admin: ${role} on ${job}`);
+  }
+  return { ok: true, done };
+}
+
+/**
+ * {@link ensureAuditJob}'s image: the deployed admin's, so the job runs the
+ * code the admin runs.
+ */
+export async function resolveAdminImage(
+  opts: { readonly projectId: string; readonly region: string; readonly env: string },
+  deps: { run?: GcloudRunner } = {},
+): Promise<{ ok: true; imageRef: string } | { ok: false; error: string }> {
+  const cfg = await readAdminConfig(opts, deps.run ?? defaultGcloud);
+  if (!cfg)
+    return {
+      ok: false,
+      error: "could not read the admin service's image (is the admin deployed?)",
+    };
+  return { ok: true, imageRef: cfg.imageRef };
+}

package/src/aws-task-roles.ts

@@ -14,7 +14,6 @@
 export type AwsSecret =
   | "postgres-password"
   | "public-role-password"
-  | "gateway-role-password"
   | "csrf-secret"
   | "cookie-secret"
   | "anthropic-api-key"
@@ -32,7 +31,6 @@ export const AWS_SERVICE_SECRETS: Readonly<Record<AwsTaskService, readonly AwsSe
   admin: [
     "postgres-password",
     "public-role-password",
-    "gateway-role-password",
     "csrf-secret",
     "cookie-secret",
     "anthropic-api-key",

package/src/caddy-redirects.docker.test.ts

@@ -47,6 +47,8 @@ const LIVE = "example.test";
 const STAGING = "staging.example.test";
 const CADDY_DIR = resolve(import.meta.dir, "../caddy");
 const SERVED = ["index.html", "about/index.html", "blog/index.html"];
+/** Consecutive matching answers that count as "the reload settled". */
+const SETTLED_PROBES = 5;
 
 function docker(args: string[]): { ok: boolean; out: string } {
   const r = Bun.spawnSync(["docker", ...args], { stdout: "pipe", stderr: "pipe" });
@@ -100,11 +102,25 @@ describe.skipIf(!dockerUp)(`self-hosted redirects through ${CADDY_IMAGE}`, () =>
     const location = head.match(/^location: ([^\r\n]*)/im)?.[1]?.trim() ?? null;
     return { status, location };
   };
+  /**
+   * Waits until `path` answers with `location` on {@link SETTLED_PROBES}
+   * consecutive connections. One matching answer is not enough: Caddy's
+   * graceful reload keeps the old config's listener open next to the new
+   * one (SO_REUSEPORT) while it drains, so the connection after the first
+   * new answer can still reach the old config (CI runs 38867358899 and
+   * 39242522450). Only a streak of new answers shows the reload settled.
+   */
   const eventually = async (host: string, path: string, location: string | null) => {
     const deadline = Date.now() + 30_000;
+    let streak = 0;
     for (;;) {
       const got = probe(host, path).location;
-      if (got === location) return;
+      streak = got === location ? streak + 1 : 0;
+      if (streak >= SETTLED_PROBES) return;
+      if (got === location) {
+        await Bun.sleep(200);
+        continue;
+      }
       if (Date.now() > deadline) {
         throw new Error(
           `${host}${path} → ${got}, expected ${location}: ${docker(["logs", name]).out}`,
@@ -241,11 +257,8 @@ describe.skipIf(!dockerUp)(`self-hosted redirects through ${CADDY_IMAGE}`, () =>
   it("the reload loop picks up a deploy's new snippet", async () => {
     write("production", snippet([["/brand-new", "/blog", 301]]));
     await eventually(LIVE, "/brand-new", "/blog/");
-    // Caddy's graceful reload keeps the old config's listener open for a
-    // moment next to the new one (SO_REUSEPORT), so a connection right
-    // after the first new answer can still reach the old config: the old
-    // redirect may answer once more (CI run 38867358899). What must hold is
-    // that the new snippet REPLACES the old one once the reload settled.
+    // What must hold is that the new snippet REPLACES the old one once the
+    // reload settled (see `eventually` for why one answer is not enough).
     await eventually(LIVE, "/old", null);
     expect(probe(LIVE, "/old").status).toBe(404);
     expect(probe(LIVE, "/brand-new").location).toBe("/blog/");

package/src/caddy-redirects.test.ts

@@ -61,7 +61,7 @@ describe("Compose — Caddy picks up new redirects (#587)", () => {
   const yaml = generateDockerCompose({
     domain: "example.com",
     postgresPassword: "pgpw",
-    rolePasswords: { admin: "a", public: "p", gateway: "g" },
+    rolePasswords: { admin: "a", public: "p" },
     caeloSecretKek: "0".repeat(64),
     diskSize: "20Gi",
     ports: { http: 80, https: 443 },

package/src/caddy.test.ts

@@ -3,6 +3,7 @@
 import { describe, expect, it } from "bun:test";
 import {
   type CaddyfileSpec,
+  caddyTokenProblem,
   generateCaddyfile,
   selfHostedAdminHost,
   selfHostedSeedDomains,
@@ -105,4 +106,33 @@ describe("Caddyfile TLS", () => {
     const out = generateCaddyfile({ ...spec, tls: "internal" });
     expect(out.startsWith("{\n  email owner@example.com\n  local_certs\n}\n")).toBe(true);
   });
+
+  it("rejects unsafe characters in ownerEmail and domain hostnames", () => {
+    expect(() => generateCaddyfile({ ...spec, ownerEmail: "owner@example.com\n  debug" })).toThrow(
+      /invalid ownerEmail/,
+    );
+    expect(() =>
+      generateCaddyfile({
+        ...spec,
+        domains: [
+          { hostname: "evil.example.com {\n  respond 200\n}", kind: "public", env: "production" },
+        ],
+      }),
+    ).toThrow(/invalid hostname/);
+  });
+
+  it("refuses a comma in a site address — it would add a second address to the block", () => {
+    // `admin.example.com,:80` would serve the admin on every host on port 80.
+    expect(() =>
+      generateCaddyfile({
+        ...spec,
+        domains: [{ hostname: "admin.example.com,:80", kind: "admin", env: "production" }],
+      }),
+    ).toThrow(/invalid hostname/);
+    // A comma is harmless inside a token like the email.
+    expect(caddyTokenProblem("a,b@example.com", "token")).toBeNull();
+    expect(caddyTokenProblem("a,b.example.com", "address")).toMatch(/','/);
+    expect(caddyTokenProblem("", "token")).toBe("it is empty");
+    expect(caddyTokenProblem("192.168.1.10", "address")).toBeNull();
+  });
 });

package/src/caddy.ts

@@ -103,9 +103,52 @@ export function selfHostedSeedDomains(domain: string, stagingDomain: string): Ca
   ];
 }
 
+/**
+ * Characters that would let a value end its Caddyfile token and start new
+ * directives or blocks: whitespace (incl. newlines), both quote styles Caddy
+ * tokenizes (`"` and backtick), braces (blocks and `{placeholders}`), the
+ * comment marker, escapes and semicolons. A site address additionally may
+ * not hold a comma, which would add further addresses to the same block.
+ */
+const UNSAFE_CADDY_TOKEN_RE = /[\s"`{}#\\;]/;
+const UNSAFE_CADDY_ADDRESS_RE = /[\s"`{}#\\;,]/;
+
+/**
+ * Why `value` cannot go into the Caddyfile as one token, or null when it can.
+ * `init` checks the operator's domains and email with this before it writes
+ * anything, so a bad value never leaves a half-made install behind.
+ *
+ * @param kind `address` for a site address (hostname), `token` for any other value
+ */
+export function caddyTokenProblem(value: string, kind: "address" | "token"): string | null {
+  if (value.length === 0) return "it is empty";
+  const unsafe = kind === "address" ? UNSAFE_CADDY_ADDRESS_RE : UNSAFE_CADDY_TOKEN_RE;
+  if (unsafe.test(value)) {
+    return `it contains whitespace, a quote, a brace, '#', '\\', ';'${kind === "address" ? " or ','" : ""}`;
+  }
+  return null;
+}
+
+function assertSafeCaddyToken(label: string, value: string, kind: "address" | "token"): void {
+  const problem = caddyTokenProblem(value, kind);
+  if (problem) {
+    throw new Error(
+      `Caddyfile: invalid ${label} ${JSON.stringify(value)} — ${problem}. Fix the value in .caelo/config.json (or the domain you added) and run the command again.`,
+    );
+  }
+}
+
+/** Every caller-supplied value is checked before any of it is emitted (#888). */
 export function generateCaddyfile(spec: CaddyfileSpec): string {
+  assertSafeCaddyToken("ownerEmail", spec.ownerEmail, "token");
+  assertSafeCaddyToken("publicSiteRoot", spec.publicSiteRoot, "token");
+  assertSafeCaddyToken("stagingSiteRoot", spec.stagingSiteRoot, "token");
+  assertSafeCaddyToken("adminUpstream", spec.adminUpstream, "token");
+  assertSafeCaddyToken("gatewayUpstream", spec.gatewayUpstream, "token");
+
   const hostnames = new Set<string>();
   for (const d of spec.domains) {
+    assertSafeCaddyToken("hostname", d.hostname, "address");
     if (hostnames.has(d.hostname)) {
       // Caddy refuses a config with two site blocks for one address, so a
       // duplicate would take every vhost down, not just this one.

package/src/checkpoint-secrets.test.ts

@@ -294,7 +294,6 @@ describe("rotationHints", () => {
       [
         { path: "a", kind: "credential-url", user: "admin_role" },
         { path: "b", kind: "credential-url", user: "public_role" },
-        { path: "c", kind: "credential-url", user: "gateway_role" },
         { path: "d", kind: "credential-url", user: "admin_role" },
       ],
       "gcp-acme",
@@ -302,7 +301,6 @@ describe("rotationHints", () => {
     expect(hints).toEqual([
       `admin_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret postgres-password --install gcp-acme`,
       `public_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret public-role-password --install gcp-acme`,
-      `gateway_role's password was stored in progress.json. Rotate it: bunx @caelo-cms/provisioning@${CAELO_VERSION} rotate-secret gateway-role-password --install gcp-acme`,
     ]);
   });
 

package/src/cli-init-validation.test.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MPL-2.0
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+const CLI = resolve(import.meta.dir, "cli.ts");
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "caelo-init-validation-"));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function init(...args: string[]) {
+  return Bun.spawnSync([process.execPath, CLI, "init", ...args], {
+    env: { ...process.env, CAELO_SELF_HOSTED_DIR: join(dir, ".caelo") },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+}
+
+describe("cms-provision init refuses a value the Caddyfile cannot hold before writing anything", () => {
+  // Checked only when the Caddyfile was generated, a bad value left
+  // config.json behind, and the re-run stopped at "config already exists".
+  for (const [flag, value] of [
+    ["--domain", "example.com,:80"],
+    ["--domain", "example.com {\n  respond 200\n}"],
+    ["--owner-email", "owner@example.com\n  debug"],
+    ["--staging-domain", "staging.example.com #"],
+  ] as const) {
+    it(`${flag} ${JSON.stringify(value)}`, () => {
+      const base: Record<string, string> = {
+        "--domain": "example.com",
+        "--owner-email": "owner@example.com",
+      };
+      base[flag] = value;
+      const r = init(...Object.entries(base).flat());
+      expect(r.exitCode).toBe(2);
+      expect(r.stderr.toString()).toContain(flag);
+      expect(existsSync(join(dir, ".caelo"))).toBe(false);
+    });
+  }
+});

package/src/cli-routing.test.ts

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: MPL-2.0
 
 import { describe, expect, it } from "bun:test";
-import { initDelegatesToWizard, resolveCliRoute } from "./cli-routing.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CLI_COMMANDS, cliUsage, initDelegatesToWizard, resolveCliRoute } from "./cli-routing.js";
 
 const HANDLERS = ["init", "upgrade", "wizard", "version", "--version", "-v"];
 const argv = (...rest: string[]) => ["bun", "cli.js", ...rest];
@@ -55,3 +57,27 @@ describe("initDelegatesToWizard", () => {
     expect(initDelegatesToWizard("self-hosted")).toBe(false);
   });
 });
+
+describe("CLI_COMMANDS / cliUsage", () => {
+  it("prints the usage line operators already know, built from the catalogue", () => {
+    expect(cliUsage().split("\n")[0]).toBe(
+      "Usage: cms-provision [wizard] [--provider <name> --domain <d> [--staging-domain <host>] --owner-email <e> --region <r>] [--local|--install-job] | <init|up|migrate|status|upgrade|backup|restore|rotate-secret|truncate|destroy|regenerate-caddy|admin-domain|staging-domain|owner-reset|state migrate|attach|pulumi-output-sync|version> [options]",
+    );
+  });
+
+  it("documents only sub-commands cli.ts actually dispatches", () => {
+    const cliSource = readFileSync(join(import.meta.dir, "cli.ts"), "utf8");
+    const handlerBlock = cliSource.slice(cliSource.indexOf("const handlers"));
+    for (const c of CLI_COMMANDS) {
+      const head = c.name.split(" ")[0] as string;
+      expect(handlerBlock).toMatch(new RegExp(`\\n\\s+"?${head}"?[:,]`));
+    }
+  });
+
+  it("gives every command a one-sentence summary", () => {
+    for (const c of CLI_COMMANDS) {
+      expect(c.summary.length).toBeGreaterThan(10);
+      expect(c.summary.endsWith(".")).toBe(true);
+    }
+  });
+});