@caelo-cms/provisioning 0.10.47 → 0.10.48

package/src/index.test.ts

@@ -0,0 +1,332 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONTENT_HASHED_PATH_PATTERN, IMMUTABLE_CACHE_CONTROL } from "@caelo-cms/shared";
+import { generateBootstrapToken } from "./bootstrap-token.js";
+import { generateCaddyfile } from "./caddy.js";
+import { loadCdnCopyAdapter, selfHostedCdnCopy } from "./cdn-copy.js";
+import { generateDockerCompose } from "./compose.js";
+import {
+  emitRedirectsAzureFrontDoor,
+  emitRedirectsCloudFront,
+  emitRedirectsCloudflare,
+  type RedirectRow,
+} from "./redirects-emit.js";
+
+describe("Caddyfile generator", () => {
+  it("emits a vhost per domain + email block", () => {
+    const out = generateCaddyfile({
+      ownerEmail: "owner@example.com",
+      publicSiteRoot: "/srv/caelo/output/production/current",
+      stagingSiteRoot: "/srv/caelo/output/staging/current",
+      adminPort: 5173,
+      gatewayPort: 8090,
+      domains: [
+        { hostname: "example.com", kind: "public", env: "production" },
+        { hostname: "staging.example.com", kind: "public", env: "staging" },
+        { hostname: "admin.example.com", kind: "admin", env: "production" },
+      ],
+    });
+    expect(out).toContain("email owner@example.com");
+    expect(out).toContain("example.com {");
+    expect(out).toContain("staging.example.com {");
+    expect(out).toContain("admin.example.com {");
+    // Staging gets noindex.
+    const stagingBlock = out.match(/staging\.example\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(stagingBlock).toContain('X-Robots-Tag "noindex"');
+    // Production does NOT get noindex.
+    const productionBlock =
+      out.match(/(?<!staging\.|admin\.)example\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(productionBlock).not.toContain('X-Robots-Tag "noindex"');
+  });
+
+  it("falls back to a localhost dev block when no domains configured", () => {
+    const out = generateCaddyfile({
+      ownerEmail: "x@y.z",
+      publicSiteRoot: "/srv/caelo/output/production/current",
+      stagingSiteRoot: "/srv/caelo/output/staging/current",
+      adminPort: 5173,
+      gatewayPort: 8090,
+      domains: [],
+    });
+    expect(out).toContain(":8081 {");
+    expect(out).toContain("reverse_proxy localhost:5173");
+  });
+});
+
+describe("Caddy cache policy for content-hashed assets", () => {
+  const spec = {
+    ownerEmail: "owner@example.com",
+    publicSiteRoot: "/srv/caelo/output/production/current",
+    stagingSiteRoot: "/srv/caelo/output/staging/current",
+    adminPort: 5173,
+    gatewayPort: 8090,
+    domains: [
+      { hostname: "example.com", kind: "public", env: "production" },
+      { hostname: "admin.example.com", kind: "admin", env: "production" },
+    ],
+  } as const;
+
+  it("public vhosts mark only CONTENT_HASHED_PATH_PATTERN paths immutable", () => {
+    const out = generateCaddyfile(spec);
+    const publicBlock = out.match(/\nexample\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    // `file` ANDs an existence check onto the path match, so a 404 for
+    // a hashed URL is never served with a year-long Cache-Control.
+    expect(publicBlock).toContain(
+      `@content_hashed {\n    path_regexp content_hashed ${CONTENT_HASHED_PATH_PATTERN}\n    file\n  }\n`,
+    );
+    expect(publicBlock).toContain(
+      `header @content_hashed Cache-Control "${IMMUTABLE_CACHE_CONTROL}"`,
+    );
+    // No blanket Cache-Control: pages + slug media keep file_server's
+    // ETag/Last-Modified revalidation.
+    expect(publicBlock.match(/Cache-Control/g)?.length).toBe(1);
+    const adminBlock = out.match(/admin\.example\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(adminBlock).not.toContain("Cache-Control");
+  });
+
+  it("the checked-in compose Caddyfiles carry the same pattern as @caelo-cms/shared", () => {
+    for (const name of ["Caddyfile.production", "Caddyfile.staging"]) {
+      const body = readFileSync(join(import.meta.dir, "..", "caddy", name), "utf8");
+      expect(body).toContain(
+        `@content_hashed {\n\t\tpath_regexp content_hashed ${CONTENT_HASHED_PATH_PATTERN}\n\t\tfile\n\t}\n`,
+      );
+      expect(body).toContain(`header @content_hashed Cache-Control "${IMMUTABLE_CACHE_CONTROL}"`);
+      expect(body).toContain('\t@ico path *.ico\n\theader @ico Content-Type "image/x-icon"\n');
+    }
+  });
+
+  it("public vhosts serve .ico favicons as image/x-icon; admin vhosts are untouched", () => {
+    const out = generateCaddyfile(spec);
+    const publicBlock = out.match(/\nexample\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(publicBlock).toContain('  @ico path *.ico\n  header @ico Content-Type "image/x-icon"\n');
+    const adminBlock = out.match(/admin\.example\.com \{[\s\S]*?\n\}/)?.[0] ?? "";
+    expect(adminBlock).not.toContain("@ico");
+  });
+});
+
+const RELEASE_IMAGES = {
+  mode: "release",
+  admin: `ghcr.io/caelo-cms/admin@sha256:${"a".repeat(64)}`,
+  gateway: `ghcr.io/caelo-cms/gateway@sha256:${"b".repeat(64)}`,
+} as const;
+
+describe("docker-compose generator", () => {
+  it("emits postgres + caddy + caelo services with the supplied secrets", () => {
+    const out = generateDockerCompose({
+      domain: "example.com",
+      postgresPassword: "supersecret",
+      rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
+      minioRootUser: "caelo",
+      minioRootPassword: "miniopass",
+      caeloSecretKek: "0".repeat(64),
+      anthropicApiKey: "sk-ant-…",
+      diskSize: "20Gi",
+      images: RELEASE_IMAGES,
+    });
+    expect(out).toContain("caelo-postgres");
+    expect(out).toContain("caelo-caddy");
+    expect(out).toContain("caelo-admin");
+    expect(out).toContain("caelo-gateway");
+    expect(out).toContain("supersecret");
+    expect(out).toContain("miniopass");
+    expect(out).toContain("ANTHROPIC_API_KEY");
+    expect(out).toContain("CAELO_SECRET_KEK");
+  });
+
+  it("gives the gateway gateway_role + public_role and no admin credential (#613)", () => {
+    const out = generateDockerCompose({
+      domain: "example.com",
+      postgresPassword: "supersecret",
+      rolePasswords: { admin: "adminpw", public: "publicpw", gateway: "gatewaypw" },
+      minioRootUser: "caelo",
+      minioRootPassword: "miniopass",
+      caeloSecretKek: "0".repeat(64),
+      diskSize: "20Gi",
+      images: RELEASE_IMAGES,
+    });
+    const gateway = out.slice(out.indexOf("caelo-gateway:"), out.indexOf("\nvolumes:"));
+    expect(gateway).toContain(
+      'GATEWAY_DATABASE_URL: "postgres://gateway_role:gatewaypw@postgres:5432/cms_admin"',
+    );
+    expect(gateway).toContain(
+      'PUBLIC_DATABASE_URL: "postgres://public_role:publicpw@postgres:5432/cms_public"',
+    );
+    expect(gateway).not.toMatch(/ADMIN_DATABASE|admin_role|adminpw|supersecret|CAELO_SECRET_KEK/);
+    // bootstrap.sh creates the three roles from these.
+    expect(out).toContain('GATEWAY_ROLE_PASSWORD: "gatewaypw"');
+  });
+
+  it("escapes secrets containing quotes safely", () => {
+    const out = generateDockerCompose({
+      domain: "example.com",
+      postgresPassword: 'pa"ss',
+      rolePasswords: { admin: "a", public: "b", gateway: "g" },
+      minioRootUser: "caelo",
+      minioRootPassword: "x",
+      caeloSecretKek: "0".repeat(64),
+      diskSize: "1Gi",
+      images: RELEASE_IMAGES,
+    });
+    expect(out).toContain('pa\\"ss');
+  });
+});
+
+describe("bootstrap token generator", () => {
+  it("emits 64 hex chars + ~24h expiry", () => {
+    const t = generateBootstrapToken();
+    expect(t.token).toMatch(/^[0-9a-f]{64}$/);
+    const ttlHours = (Date.parse(t.expiresAt) - Date.now()) / 3600_000;
+    expect(ttlHours).toBeGreaterThan(23);
+    expect(ttlHours).toBeLessThan(25);
+  });
+
+  it("each call returns a unique token", () => {
+    const a = generateBootstrapToken().token;
+    const b = generateBootstrapToken().token;
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("redirects-emit", () => {
+  const rows: RedirectRow[] = [
+    { fromPath: "/old", toPath: "/new", statusCode: 301 },
+    { fromPath: "/blog/2024", toPath: "/blog", statusCode: 302 },
+    { fromPath: "/legacy", toPath: "/modern", statusCode: 308 },
+  ];
+
+  describe("emitRedirectsCloudflare", () => {
+    it("emits one line per row in `<from> <to> <status>` format", () => {
+      const out = emitRedirectsCloudflare(rows);
+      expect(out).toContain("/old /new 301\n");
+      expect(out).toContain("/blog/2024 /blog 302\n");
+      expect(out).toContain("/legacy /modern 308\n");
+      expect(out.startsWith("# Generated by @caelo-cms/provisioning")).toBe(true);
+    });
+
+    it("empty rows → header only, no trailing newline noise", () => {
+      const out = emitRedirectsCloudflare([]);
+      expect(out).toBe("# Generated by @caelo-cms/provisioning — do not edit by hand.\n");
+    });
+
+    it("is byte-identical for the same input (deterministic)", () => {
+      expect(emitRedirectsCloudflare(rows)).toBe(emitRedirectsCloudflare([...rows]));
+    });
+  });
+
+  describe("emitRedirectsCloudFront", () => {
+    it("returns parseable JSON config + a Lambda source that consumes it", () => {
+      const out = emitRedirectsCloudFront(rows);
+      const parsed = JSON.parse(out.jsonConfig) as {
+        redirects: Array<{ from: string; to: string; status: number }>;
+      };
+      expect(parsed.redirects).toHaveLength(3);
+      expect(parsed.redirects[0]).toEqual({ from: "/old", to: "/new", status: 301 });
+      expect(out.lambdaSource).toContain("exports.handler");
+      expect(out.lambdaSource).toContain('require("./redirects.json")');
+    });
+
+    it("preserves status codes verbatim (301/302/307/308)", () => {
+      const allStatuses: RedirectRow[] = [
+        { fromPath: "/a", toPath: "/x", statusCode: 301 },
+        { fromPath: "/b", toPath: "/x", statusCode: 302 },
+        { fromPath: "/c", toPath: "/x", statusCode: 307 },
+        { fromPath: "/d", toPath: "/x", statusCode: 308 },
+      ];
+      const out = emitRedirectsCloudFront(allStatuses);
+      const parsed = JSON.parse(out.jsonConfig) as {
+        redirects: Array<{ status: number }>;
+      };
+      expect(parsed.redirects.map((r) => r.status)).toEqual([301, 302, 307, 308]);
+    });
+  });
+
+  describe("emitRedirectsAzureFrontDoor", () => {
+    it("emits one rule per row with monotonically-increasing order", () => {
+      const out = emitRedirectsAzureFrontDoor(rows);
+      expect(out).toHaveLength(3);
+      expect(out[0]?.name).toBe("redirect-1");
+      expect(out[0]?.order).toBe(1);
+      expect(out[2]?.order).toBe(3);
+    });
+
+    it("maps status codes to Front Door redirectType vocabulary", () => {
+      const out = emitRedirectsAzureFrontDoor([
+        { fromPath: "/a", toPath: "/x", statusCode: 301 },
+        { fromPath: "/b", toPath: "/x", statusCode: 302 },
+        { fromPath: "/c", toPath: "/x", statusCode: 307 },
+        { fromPath: "/d", toPath: "/x", statusCode: 308 },
+      ]);
+      expect(out.map((r) => r.actions[0]?.parameters.redirectType)).toEqual([
+        "Moved",
+        "Found",
+        "TemporaryRedirect",
+        "PermanentRedirect",
+      ]);
+    });
+
+    it("RequestUri condition matches the from path exactly", () => {
+      const out = emitRedirectsAzureFrontDoor(rows);
+      expect(out[1]?.conditions[0]?.parameters.matchValues).toEqual(["/blog/2024"]);
+      expect(out[1]?.actions[0]?.parameters.destinationPath).toBe("/blog");
+    });
+  });
+
+  describe("path-validation guard (review-pass #9)", () => {
+    it("Cloudflare emitter rejects fromPath with whitespace", () => {
+      expect(() =>
+        emitRedirectsCloudflare([{ fromPath: "/old path", toPath: "/new", statusCode: 301 }]),
+      ).toThrow(/contains whitespace/);
+    });
+
+    it("CloudFront emitter rejects toPath with newline", () => {
+      expect(() =>
+        emitRedirectsCloudFront([{ fromPath: "/old", toPath: "/new\nlies", statusCode: 301 }]),
+      ).toThrow(/contains whitespace/);
+    });
+
+    it("every emitter rejects an off-site or URL-embedding toPath (#657)", () => {
+      for (const toPath of ["//evil.example/x", "/https://example.com/x"]) {
+        const rows = [{ fromPath: "/old", toPath, statusCode: 301 as const }];
+        expect(() => emitRedirectsCloudflare(rows)).toThrow(/redirects-emit: toPath/);
+        expect(() => emitRedirectsCloudFront(rows)).toThrow(/redirects-emit: toPath/);
+        expect(() => emitRedirectsAzureFrontDoor(rows)).toThrow(/redirects-emit: toPath/);
+      }
+    });
+
+    it("Azure emitter rejects tab in path", () => {
+      expect(() =>
+        emitRedirectsAzureFrontDoor([{ fromPath: "/old\there", toPath: "/x", statusCode: 301 }]),
+      ).toThrow(/contains whitespace/);
+    });
+
+    it("hyphens, dots, slashes, unicode in path segments are accepted", () => {
+      // Regression guard for the original buggy regex `[\s -]` which
+      // rejected hyphens.
+      expect(() =>
+        emitRedirectsCloudflare([
+          { fromPath: "/blog/spring-launch", toPath: "/blog/sommer-2026", statusCode: 301 },
+        ]),
+      ).not.toThrow();
+    });
+  });
+});
+
+describe("cdn-copy adapter loader", () => {
+  it("returns the no-op self-hosted adapter when provider is unset/empty/self-hosted", async () => {
+    expect(await loadCdnCopyAdapter(undefined)).toBe(selfHostedCdnCopy);
+    expect(await loadCdnCopyAdapter("")).toBe(selfHostedCdnCopy);
+    expect(await loadCdnCopyAdapter("self-hosted")).toBe(selfHostedCdnCopy);
+  });
+
+  it("self-hosted adapter pin returns a /media/<key> URL", async () => {
+    const url = await selfHostedCdnCopy.pin("photos/2026/april/sunset.webp");
+    expect(url).toBe("/media/photos/2026/april/sunset.webp");
+  });
+
+  it("rejects unknown provider names loudly (no silent fallback per CLAUDE.md §2)", async () => {
+    await expect(loadCdnCopyAdapter("digitalocean")).rejects.toThrow(/unknown CAELO_PROVIDER/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @caelo-cms/provisioning — P14.
+ *
+ * Pulumi-driven self-hosted stack + cms-provision CLI helpers.
+ *
+ * Public surface:
+ *   - generateCaddyfile(spec) → string
+ *   - generateDockerCompose(spec) → string
+ *   - generateBootstrapToken() → { token, expiresAt }
+ *
+ * The CLI (cli.ts) wires these into init / up / regenerate-caddy /
+ * backup / restore / status sub-commands. The Pulumi stack files
+ * (stacks/self-hosted/*) are imported by the CLI's `up` path and
+ * declare the actual Docker resources.
+ */
+
+export type {
+  CloudAdapterInputs,
+  CloudAdapterOutputs,
+  DnsRecord,
+  Environment,
+  ProvisioningOutputsJson,
+  SupportedProvider,
+} from "./adapter.js";
+export type {
+  AgentDbConnection,
+  AgentHeartbeat,
+  AgentQueue,
+  OpenAgentQueue,
+  OpenedAgentQueue,
+} from "./agent/queue.js";
+export {
+  type BootstrapToken,
+  generateBootstrapToken,
+} from "./bootstrap-token.js";
+export {
+  type CaddyDomainSpec,
+  type CaddyfileSpec,
+  generateCaddyfile,
+} from "./caddy.js";
+export {
+  type CdnCopyAdapter,
+  loadCdnCopyAdapter,
+  selfHostedCdnCopy,
+} from "./cdn-copy.js";
+export { type ComposeSpec, generateDockerCompose, type RolePasswords } from "./compose.js";
+export { INFRA_CONTRACT_VERSION } from "./infra-contract.js";
+export {
+  type CloudFrontRedirectArtifact,
+  emitRedirectsAzureFrontDoor,
+  emitRedirectsCloudFront,
+  emitRedirectsCloudflare,
+  type FrontDoorRule,
+  type RedirectRow,
+  type RedirectStatusCode,
+} from "./redirects-emit.js";
+export {
+  INFRA_CONTRACT_PATHS,
+  isInfraContractPath,
+  RELEASE_MIN_FROM_VERSION,
+} from "./release-contract.js";
+export {
+  assessAutoInstall,
+  channelForVersion,
+  compareImageDigests,
+  compareSemver,
+  type DigestMismatch,
+  fetchVerifiedReleaseManifest,
+  type InstallAssessment,
+  type InstalledRelease,
+  type InstallMode,
+  RELEASE_CHANNELS,
+  RELEASE_IMAGES,
+  RELEASE_MANIFEST_ARTIFACT_TYPE,
+  RELEASE_MANIFEST_MEDIA_TYPE,
+  RELEASE_MANIFEST_REGISTRY,
+  RELEASE_MANIFEST_REPOSITORY,
+  RELEASE_OIDC_ISSUER,
+  type ReleaseChannel,
+  type ReleaseImage,
+  type ReleaseManifest,
+  type ReleaseManifestDeps,
+  type ReleaseManifestError,
+  type ReleaseManifestErrorCode,
+  type ReleaseManifestResult,
+  ReleaseManifestSchema,
+  releaseManifestSignerIdentity,
+  SIGSTORE_BUNDLE_MEDIA_TYPE,
+} from "./release-manifest.js";
+export { AGENT_DB_ROLE, roleConvergenceScript } from "./self-hosted-roles.js";
+export {
+  assessUpgradeRequest,
+  type InstalledState,
+  type RefusalCode,
+  type RequestDecision,
+} from "./upgrader-assess.js";
+export {
+  gcpUpgraderDeps,
+  type UpgraderPlacement,
+  upgraderDatabaseHost,
+} from "./upgrader-gcp.js";
+export {
+  type ClaimedUpdate,
+  runUpgraderJob,
+  type UpdateEnd,
+  type UpdateEndStatus,
+  type UpdateFacts,
+  type UpdateQueue,
+  type UpgraderJobDeps,
+  type UpgraderRunResult,
+} from "./upgrader-job.js";
+export type { JobLog } from "./upgrader-reporter.js";

package/src/infra-contract.ts

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The infrastructure contract version (epic #696).
+ *
+ * An upgrade has two halves (packages/provisioning/src/upgrade/): the
+ * *converge* half changes IAM, service accounts, secrets and other cloud
+ * resources the stacks declare; the *app-roll* half only runs migrations and
+ * moves the two Cloud Run services onto new images. The app-roll half can run
+ * under an identity without IAM-write or secret-create rights (the in-cloud
+ * upgrader job), but only while the install's infrastructure already is what
+ * the release expects.
+ *
+ * This number names that expectation. A release that needs a converge step
+ * the installs out there have not had yet (a new secret, a new IAM binding, a
+ * new service account) bumps it; `cms-provision upgrade` records the version
+ * it converged to in install.json, and the upgrader job refuses an app-roll
+ * while the recorded version is lower (`needsConverge` in upgrade/converge.ts),
+ * sending the operator to the converge path instead.
+ *
+ * Bump it in the same PR that adds the converge step, never later: a release
+ * whose app-roll references infrastructure an install does not have yet fails
+ * at roll time, after migrations ran.
+ */
+export const INFRA_CONTRACT_VERSION = 2;
+
+// History (why each bump happened — an install below a number needs the
+// converge that introduced it):
+//   1 — epic #696 split: converge vs app-roll.
+//   2 — the upgrader job (#696 Phase 2): its service account + scoped
+//       grants, the Cloud SQL backup role, its IAM database user, the job,
+//       the admin's run-only grant and CAELO_UPGRADER_JOB on the admin.

package/src/install-job-runner.ts

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `caelo-ops install-job --project <id>` — the install job's entry point
+ * (epic #696, Phase 3; install-job.ts has the design). Runs inside the Cloud
+ * Run job, as `caelo-provisioner`, from the signed ops image:
+ *
+ *   1. attach the install from its ops bucket (the container starts empty);
+ *   2. record `running` in `install/install-job.json`;
+ *   3. run the converge half of the GCP install (wizards/gcp.ts
+ *      runGcpConverge) non-interactively, recording each phase;
+ *   4. record `succeeded` — or, from an exit hook, `failed` with the last
+ *      lines of output, whatever made the process stop.
+ *
+ * It takes the project and nothing else: every input is the install's own
+ * record in its bucket, which only the operator and the provisioner can write.
+ */
+
+import { CAELO_VERSION } from "@caelo-cms/shared";
+import { assertNoSecrets } from "./checkpoint-secrets.js";
+import {
+  type InstallJobStatus,
+  readInstallJobStatus,
+  writeInstallJobStatus,
+} from "./install-job.js";
+import { currentMetadata, installRoot, readLocalMetadata } from "./install-state.js";
+import { attachInstall } from "./state-attach.js";
+import { hasLocalPulumiState, opsBucketName, resolveBackend } from "./state-backend.js";
+import { realSyncGcloud, type SyncGcloud } from "./state-store.js";
+
+const PROJECT_ID = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[A-Za-z]`, "g");
+
+/** The `--project` value of `argv`, validated. */
+export function installJobProject(argv: readonly string[]): string {
+  const i = argv.indexOf("--project");
+  const value = i === -1 ? undefined : argv[i + 1];
+  if (!value || !PROJECT_ID.test(value)) {
+    throw new Error("install-job needs --project <gcp-project-id>");
+  }
+  return value;
+}
+
+/**
+ * The failure detail recorded for the operator's terminal: the last
+ * non-empty lines of output, colour codes stripped, credentials removed.
+ * Anything the secrets guard still objects to is replaced by a pointer to
+ * the logs rather than written to the bucket.
+ */
+export function failureDetail(lines: readonly string[], code: number): string {
+  const tail = lines
+    .map((l) => l.replace(ANSI, "").trim())
+    .filter((l) => l !== "" && !/^[│┌└◇◆●■▲]+$/.test(l))
+    .slice(-6)
+    .join(" | ");
+  // Stricter than redactCredentials' `user:***@`, which the bucket's guard
+  // still (rightly) reads as a credential URL: drop the password and any
+  // token-like query value entirely.
+  const detail = `exit ${code}: ${tail}`
+    .replace(/([a-z][a-z0-9+.-]{0,31}:\/\/[^\s:@/]*):[^\s@/]+@/gi, "$1@")
+    .replace(
+      /([?&](?:token|secret|password|passwd|pwd|api[_-]?key|access[_-]?key|sig|signature)=)[^&\s#]+/gi,
+      "$1",
+    )
+    .slice(0, 1500);
+  try {
+    assertNoSecrets({ detail }, "install-job.json detail");
+    return detail;
+  } catch {
+    return `exit ${code} — see the job's logs`;
+  }
+}
+
+/** Keep the last `max` lines written to stdout + stderr. */
+function captureOutputTail(max: number): () => string[] {
+  const lines: string[] = [];
+  for (const stream of [process.stdout, process.stderr]) {
+    const write = stream.write.bind(stream) as (chunk: unknown, ...rest: unknown[]) => boolean;
+    stream.write = ((chunk: unknown, ...rest: unknown[]) => {
+      const text = typeof chunk === "string" ? chunk : Buffer.from(chunk as Uint8Array).toString();
+      for (const l of text.split(/\r?\n/)) if (l.trim() !== "") lines.push(l);
+      if (lines.length > max) lines.splice(0, lines.length - max);
+      return write(chunk, ...rest);
+    }) as typeof stream.write;
+  }
+  return () => [...lines];
+}
+
+/** Run the install job for `--project` in `argv`. */
+export async function installJobCommand(
+  argv: readonly string[],
+  run: SyncGcloud = realSyncGcloud,
+): Promise<void> {
+  const projectId = installJobProject(argv);
+  const attached = attachInstall(projectId, {
+    run,
+    rootFor: installRoot,
+    hasLocalState: hasLocalPulumiState,
+  });
+  if (!attached.ok) throw new Error(attached.error);
+  const local = readLocalMetadata(attached.installId);
+  if (!local) throw new Error(`attach wrote no install.json for ${attached.installId}`);
+  const meta = currentMetadata(local);
+  if (meta.provider !== "gcp" && meta.provider !== "gcp-firebase") {
+    throw new Error(`install-job runs gcp / gcp-firebase installs; this one is ${meta.provider}.`);
+  }
+  if (!meta.region) throw new Error(`install.json of ${meta.installId} records no region.`);
+
+  const bucket = opsBucketName(projectId);
+  // Cloud Run sets it; the launcher recorded the same name when it started us.
+  const execution = process.env.CLOUD_RUN_EXECUTION ?? "local-run";
+  const previous = readInstallJobStatus(bucket, run);
+  const now = new Date().toISOString();
+  let status: InstallJobStatus = {
+    statusVersion: 1,
+    installId: meta.installId,
+    execution,
+    state: "running",
+    phase: "Starting",
+    caeloVersion: CAELO_VERSION,
+    startedAt: previous?.execution === execution ? previous.startedAt : now,
+    updatedAt: now,
+  };
+  const record = (patch: Partial<InstallJobStatus>): void => {
+    status = { ...status, ...patch, updatedAt: new Date().toISOString() };
+    if (patch.detail === undefined) delete status.detail;
+    try {
+      writeInstallJobStatus(bucket, status, run);
+    } catch (e) {
+      // The install goes on; the terminal falls back to the execution state.
+      console.error(`could not record progress: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  };
+  record({});
+
+  const outputTail = captureOutputTail(40);
+  // The wizard's steps end the process with process.exit on failure; the
+  // hook runs synchronously (the bucket write is a spawnSync) either way.
+  process.on("exit", (code) => {
+    if (status.state !== "running") return;
+    record({ state: "failed", detail: failureDetail(outputTail(), code) });
+  });
+
+  const backend = resolveBackend(meta, {
+    installRoot: installRoot(meta.installId),
+    readPassphrase: () => null,
+  });
+  if (backend.kind !== "gcs") {
+    throw new Error(
+      `${meta.installId}'s state is not in its ops bucket; run the installer with --local.`,
+    );
+  }
+  const { runGcpConverge } = await import("./wizards/gcp.js");
+  await runGcpConverge({
+    installId: meta.installId,
+    projectId,
+    region: meta.region,
+    provider: meta.provider,
+    impersonateServiceAccount: null,
+    backend,
+    nonInteractive: true,
+    setupLink: "secret",
+    onPhase: (phase, detail) => record({ phase, detail }),
+  });
+  record({ state: "succeeded", phase: "Done" });
+}