@caelo-cms/provisioning 0.10.47 → 0.10.48

package/src/state-attach.test.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `attach --project` (#696, state-attach.ts) against a fake bucket, and the
+ * install-dir archive `state migrate` takes first (state-command.ts).
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { GcloudResult } from "./gcloud.js";
+import { attachInstall } from "./state-attach.js";
+import { gcsBackendRecord, hasLocalPulumiState } from "./state-backend.js";
+import { backupInstallDir } from "./state-command.js";
+import { acquireBucketStateLock, acquireLocalStateLock, type SyncGcloud } from "./state-store.js";
+
+const ok = (stdout = ""): GcloudResult => ({ ok: true, stdout, stderr: "", exitCode: 0 });
+const fail = (stderr: string): GcloudResult => ({ ok: false, stdout: "", stderr, exitCode: 1 });
+
+const GCS = gcsBackendRecord("acme-site", "europe-west1");
+const META = {
+  installId: "gcp-firebase-acme-site",
+  provider: "gcp-firebase",
+  projectId: "acme-site",
+  domain: "acme.com",
+  ownerEmail: "o@acme.com",
+  region: "europe-west1",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  stateBackend: GCS,
+};
+
+function bucket(objects: Record<string, string>): SyncGcloud {
+  return (args) => {
+    if (args[1] === "cat") {
+      const v = objects[args[2] ?? ""];
+      return v === undefined ? fail("matched no objects") : ok(v);
+    }
+    return fail(`unexpected ${args.join(" ")}`);
+  };
+}
+
+let home = "";
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "caelo-attach-"));
+});
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+});
+
+const deps = (objects: Record<string, string>) => ({
+  run: bucket(objects),
+  rootFor: (id: string) => join(home, `.caelo-${id}`),
+  hasLocalState: hasLocalPulumiState,
+});
+const url = (f: string) => `gs://acme-site-caelo-ops/install/${f}`;
+
+describe("attachInstall", () => {
+  it("mirrors install.json + progress.json from the bucket into a new install dir", () => {
+    const r = attachInstall(
+      "acme-site",
+      deps({
+        [url("install.json")]: JSON.stringify(META),
+        [url("progress.json")]: JSON.stringify({ lastCompletedStep: "x", steps: {} }),
+      }),
+    );
+    expect(r).toEqual({
+      ok: true,
+      installId: META.installId,
+      domain: "acme.com",
+      status: "attached",
+    });
+    const root = join(home, `.caelo-${META.installId}`);
+    expect(JSON.parse(readFileSync(join(root, "install.json"), "utf8")).stateBackend).toEqual(GCS);
+    expect(existsSync(join(root, "progress.json"))).toBe(true);
+    expect(statSync(root).mode & 0o777).toBe(0o700);
+  });
+
+  it("re-attaching is a refresh", () => {
+    const objects = { [url("install.json")]: JSON.stringify(META) };
+    attachInstall("acme-site", deps(objects));
+    expect(attachInstall("acme-site", deps(objects))).toMatchObject({
+      ok: true,
+      status: "refreshed",
+    });
+  });
+
+  it("an empty bucket points at state migrate on the installing machine", () => {
+    const r = attachInstall("acme-site", deps({}));
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain("state migrate");
+  });
+
+  it("refuses an install whose state went back to a machine", () => {
+    const r = attachInstall(
+      "acme-site",
+      deps({ [url("install.json")]: JSON.stringify({ ...META, stateBackend: { kind: "local" } }) }),
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it("refuses a record for another project", () => {
+    const r = attachInstall(
+      "acme-site",
+      deps({ [url("install.json")]: JSON.stringify({ ...META, projectId: "other" }) }),
+    );
+    expect(r.ok).toBe(false);
+  });
+
+  it("never hides this machine's un-migrated local state", () => {
+    const root = join(home, `.caelo-${META.installId}`);
+    mkdirSync(join(root, "state", ".pulumi", "stacks", "caelo-gcp-firebase"), { recursive: true });
+    writeFileSync(join(root, "install.json"), JSON.stringify({ ...META, stateBackend: undefined }));
+    const r = attachInstall("acme-site", deps({ [url("install.json")]: JSON.stringify(META) }));
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toContain("state migrate --install");
+    expect(
+      JSON.parse(readFileSync(join(root, "install.json"), "utf8")).stateBackend,
+    ).toBeUndefined();
+  });
+});
+
+describe("attachInstall — local state without install.json", () => {
+  it("still refuses to hide it", () => {
+    const root = join(home, `.caelo-${META.installId}`);
+    mkdirSync(join(root, "state", ".pulumi", "stacks", "caelo-gcp-firebase"), { recursive: true });
+    const r = attachInstall("acme-site", deps({ [url("install.json")]: JSON.stringify(META) }));
+    expect(r.ok).toBe(false);
+    expect(existsSync(join(root, "install.json"))).toBe(false);
+  });
+});
+
+describe("backupInstallDir", () => {
+  for (const hasZstd of [true, false]) {
+    it(`archives the install dir privately (${hasZstd ? "tar.zst" : "tar.gz fallback"})`, () => {
+      if (hasZstd && Bun.spawnSync(["zstd", "--version"]).exitCode !== 0) return;
+      const root = join(home, ".caelo-gcp-acme");
+      mkdirSync(join(root, "secrets"), { recursive: true });
+      writeFileSync(join(root, "secrets", "pulumi-passphrase"), "pp\n");
+      const out = backupInstallDir("gcp-acme", {
+        home,
+        hasZstd,
+        now: new Date("2026-10-13T10:00:00Z"),
+      });
+      expect(out).toBe(
+        join(
+          home,
+          ".caelo-backups",
+          `gcp-acme-2026-10-13T10-00-00-000Z.tar.${hasZstd ? "zst" : "gz"}`,
+        ),
+      );
+      expect(statSync(out).mode & 0o777).toBe(0o600);
+      expect(statSync(join(home, ".caelo-backups")).mode & 0o777).toBe(0o700);
+      const list = hasZstd
+        ? Bun.spawnSync(["sh", "-c", `zstd -dc "${out}" | tar -tf -`])
+        : Bun.spawnSync(["tar", "-tzf", out]);
+      expect(new TextDecoder().decode(list.stdout)).toContain(
+        ".caelo-gcp-acme/secrets/pulumi-passphrase",
+      );
+      expect(existsSync(out.replace(/\.zst$/, ""))).toBe(!hasZstd);
+    });
+  }
+});
+
+describe("state locks", () => {
+  it("bucket lock: created only if absent, released by deleting it", () => {
+    const objects = new Map<string, string>();
+    const run: SyncGcloud = (args, input) => {
+      const url = args[2] === "-" ? (args[3] ?? "") : (args[2] ?? "");
+      if (args[1] === "cp") {
+        if (args.includes("--if-generation-match=0") && objects.has(url)) {
+          return fail(
+            "HTTPError 412: At least one of the pre-conditions you specified did not hold.",
+          );
+        }
+        objects.set(url, input ?? "");
+        return ok();
+      }
+      if (args[1] === "cat")
+        return objects.has(url) ? ok(objects.get(url)) : fail("matched no objects");
+      if (args[1] === "rm") return objects.delete(url) ? ok() : fail("matched no objects");
+      return fail("unexpected");
+    };
+    const release = acquireBucketStateLock("acme-site-caelo-ops", "state migrate", run);
+    expect(() => acquireBucketStateLock("acme-site-caelo-ops", "installer pulumi up", run)).toThrow(
+      /gcloud storage rm gs:\/\/acme-site-caelo-ops\/install\/state.lock/,
+    );
+    release();
+    acquireBucketStateLock("acme-site-caelo-ops", "installer pulumi up", run)();
+    expect(objects.size).toBe(0);
+  });
+
+  it("local lock: exclusive file next to the state, mode 600", () => {
+    const root = join(home, ".caelo-gcp-acme");
+    mkdirSync(root, { recursive: true });
+    const release = acquireLocalStateLock(root, "installer pulumi up");
+    expect(statSync(join(root, "state.lock")).mode & 0o777).toBe(0o600);
+    expect(() => acquireLocalStateLock(root, "state migrate")).toThrow(/installer pulumi up/);
+    release();
+    acquireLocalStateLock(root, "state migrate")();
+    expect(existsSync(join(root, "state.lock"))).toBe(false);
+  });
+});

package/src/state-attach.ts

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * `cms-provision attach --project <id>` (#696): make an install whose state
+ * lives in its ops bucket manageable from this machine (a new laptop, Cloud
+ * Shell). It reads `gs://<project>-caelo-ops/install/install.json`, checks
+ * it, and mirrors install.json + progress.json into `~/.caelo-<id>/`. No
+ * secret is copied, because none exists outside the operator's Google
+ * login: Pulumi reaches the state and its KMS key with that login.
+ *
+ * Refuses rather than overwrites: an install directory here that holds this
+ * install's local state (it was never migrated) or another backend.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { selfCommand } from "./self-command.js";
+import { opsBucketName, parseStateBackend } from "./state-backend.js";
+import { GcsStateStore, LocalStateStore, type SyncGcloud } from "./state-store.js";
+
+export type AttachResult =
+  | {
+      readonly ok: true;
+      readonly installId: string;
+      readonly domain: string;
+      readonly status: "attached" | "refreshed";
+    }
+  | { readonly ok: false; readonly error: string };
+
+/** Install ids are `<provider>-<slug>` (install-state.ts deriveInstallId). */
+const INSTALL_ID = /^[a-z0-9][a-z0-9-]{0,80}$/;
+
+/**
+ * Attach the install in `projectId` to this machine.
+ *
+ * @param deps.run gcloud runner (tests pass a fake bucket)
+ * @param deps.rootFor `~/.caelo-<id>` for an install id
+ * @param deps.hasLocalState whether a dir holds a local Pulumi stack
+ */
+export function attachInstall(
+  projectId: string,
+  deps: {
+    run: SyncGcloud;
+    rootFor: (installId: string) => string;
+    hasLocalState: (root: string) => boolean;
+  },
+): AttachResult {
+  const bucket = opsBucketName(projectId);
+  let text: string | null;
+  try {
+    // Peek: the directory to mirror into isn't known (or checked) yet.
+    text = new GcsStateStore(bucket, "/nonexistent", deps.run).peek("install.json");
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+  if (text === null) {
+    return {
+      ok: false,
+      error: `gs://${bucket} holds no install.json. If this install's state is still on the machine that installed it, run \`${selfCommand("state", "migrate")}\` there first.`,
+    };
+  }
+  let remote: {
+    installId?: unknown;
+    domain?: unknown;
+    projectId?: unknown;
+    stateBackend?: unknown;
+  };
+  try {
+    remote = JSON.parse(text) as typeof remote;
+  } catch {
+    return { ok: false, error: `gs://${bucket}/install/install.json is not valid JSON.` };
+  }
+  const installId = typeof remote.installId === "string" ? remote.installId : "";
+  if (!INSTALL_ID.test(installId) || remote.projectId !== projectId) {
+    return {
+      ok: false,
+      error: `gs://${bucket}/install/install.json does not describe an install in project ${projectId}; refusing to attach.`,
+    };
+  }
+  let backend: ReturnType<typeof parseStateBackend>;
+  try {
+    backend = parseStateBackend(remote.stateBackend);
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+  if (backend?.kind !== "gcs") {
+    return {
+      ok: false,
+      error: `${installId}'s state was moved back to a machine (state migrate --to local); there is nothing in gs://${bucket} to attach to. Run \`state migrate --to remote\` on that machine first.`,
+    };
+  }
+  if (backend.bucket !== bucket) {
+    return {
+      ok: false,
+      error: `install.json in gs://${bucket} names another bucket (${backend.bucket}); refusing to attach.`,
+    };
+  }
+
+  const root = deps.rootFor(installId);
+  const localText = new LocalStateStore(root).read("install.json");
+  // Local Pulumi state blocks the attach whether or not an install.json
+  // sits next to it: attaching would hide it.
+  if (deps.hasLocalState(root)) {
+    return {
+      ok: false,
+      error: `${root} holds a local Pulumi state of this install. Attaching would hide it; run \`${selfCommand("state", "migrate", "--install", installId)}\` instead, or move ${root} aside if that state is stale.`,
+    };
+  }
+  let status: "attached" | "refreshed" = "attached";
+  if (localText !== null) {
+    const local = JSON.parse(localText) as { stateBackend?: unknown };
+    const localBackend = parseStateBackend(local.stateBackend);
+    if (localBackend?.kind === "gcs" && localBackend.bucket === bucket) {
+      status = "refreshed";
+    } else {
+      return {
+        ok: false,
+        error: `${root}/install.json exists and names another backend. Move ${root} aside, then re-run attach.`,
+      };
+    }
+  }
+  if (!existsSync(root)) mkdirSync(root, { recursive: true, mode: 0o700 });
+  // Mirror exactly the install.json validated above (a re-read could fetch
+  // a different one written meanwhile); progress.json is bookkeeping.
+  new LocalStateStore(root).write("install.json", JSON.parse(text));
+  new GcsStateStore(bucket, root, deps.run).read("progress.json");
+  return {
+    ok: true,
+    installId,
+    domain: typeof remote.domain === "string" ? remote.domain : installId,
+    status,
+  };
+}

package/src/state-backend.test.ts

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Backend resolution (#696, state-backend.ts): the one place a Pulumi
+ * backend URL, secrets provider and environment come from.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  backendShellEnv,
+  chooseInstallBackend,
+  gcsBackendRecord,
+  hasLocalPulumiState,
+  parseStateBackend,
+  resolveBackend,
+} from "./state-backend.js";
+
+const ROOT = "/home/op/.caelo-gcp-acme";
+const GCS = gcsBackendRecord("acme", "europe-west1");
+
+describe("resolveBackend", () => {
+  it("local: file:// under the install dir, passphrase provider, passphrase in the env", () => {
+    const b = resolveBackend(
+      { installId: "gcp-acme" },
+      { installRoot: ROOT, readPassphrase: () => "pp" },
+    );
+    expect(b).toEqual({
+      kind: "local",
+      url: `file://${ROOT}/state`,
+      secretsProvider: "passphrase",
+      envVars: {
+        PULUMI_BACKEND_URL: `file://${ROOT}/state`,
+        PULUMI_CONFIG_PASSPHRASE: "pp",
+        PULUMI_FALLBACK_TO_STATE_SECRETS_MANAGER: "true",
+      },
+    });
+  });
+
+  it("local without a passphrase fails loudly instead of letting Pulumi prompt", () => {
+    expect(() =>
+      resolveBackend({ installId: "gcp-acme" }, { installRoot: ROOT, readPassphrase: () => null }),
+    ).toThrow(/pulumi-passphrase is missing/);
+  });
+
+  it("gcs: the ops bucket + KMS key, no passphrase read or passed", () => {
+    let read = false;
+    const b = resolveBackend(
+      { installId: "gcp-acme", stateBackend: GCS },
+      {
+        installRoot: ROOT,
+        readPassphrase: () => {
+          read = true;
+          return "pp";
+        },
+      },
+    );
+    expect(read).toBe(false);
+    expect(b.kind).toBe("gcs");
+    expect(b.url).toBe("gs://acme-caelo-ops/pulumi");
+    expect(b.secretsProvider).toBe(
+      "gcpkms://projects/acme/locations/europe-west1/keyRings/caelo/cryptoKeys/pulumi-state",
+    );
+    expect(b.envVars).toEqual({
+      PULUMI_BACKEND_URL: "gs://acme-caelo-ops/pulumi",
+      PULUMI_FALLBACK_TO_STATE_SECRETS_MANAGER: "true",
+    });
+  });
+});
+
+describe("parseStateBackend", () => {
+  it("accepts absent, local and a well-formed gcs record", () => {
+    expect(parseStateBackend(undefined)).toBeUndefined();
+    expect(parseStateBackend({ kind: "local" })).toEqual({ kind: "local" });
+    expect(parseStateBackend({ ...GCS })).toEqual(GCS);
+  });
+
+  it("throws on anything else rather than pointing Pulumi at a guess", () => {
+    expect(() => parseStateBackend({ kind: "s3" })).toThrow(/malformed/);
+    expect(() =>
+      parseStateBackend({ kind: "gcs", bucket: "gs://x", kmsKey: GCS.kmsKey }),
+    ).toThrow();
+    expect(() =>
+      parseStateBackend({ kind: "gcs", bucket: "acme-caelo-ops", kmsKey: "k" }),
+    ).toThrow();
+  });
+});
+
+describe("backendShellEnv (recovery commands the CLI prints)", () => {
+  it("never inlines the passphrase", () => {
+    const local = backendShellEnv({}, ROOT);
+    expect(local).toContain(`PULUMI_BACKEND_URL=file://${ROOT}/state`);
+    expect(local).toContain(`"$(cat ${ROOT}/secrets/pulumi-passphrase)"`);
+  });
+
+  it("gcs needs no secret at all", () => {
+    expect(backendShellEnv({ stateBackend: GCS }, ROOT)).toBe(
+      "PULUMI_BACKEND_URL=gs://acme-caelo-ops/pulumi PULUMI_FALLBACK_TO_STATE_SECRETS_MANAGER=true",
+    );
+  });
+});
+
+describe("chooseInstallBackend", () => {
+  it("new GCP installs go to the ops bucket", () => {
+    expect(chooseInstallBackend({ provider: "gcp" }, false)).toBe("gcs");
+    expect(chooseInstallBackend({ provider: "gcp-firebase" }, false)).toBe("gcs");
+  });
+
+  it("an older install with state on this machine stays local (never moved by a re-run)", () => {
+    expect(chooseInstallBackend({ provider: "gcp-firebase" }, true)).toBe("local");
+  });
+
+  it("a deployed install with no state anywhere stops instead of starting an empty stack", () => {
+    expect(() =>
+      chooseInstallBackend({ installId: "gcp-acme", provider: "gcp" }, false, true),
+    ).toThrow(/neither recorded/);
+  });
+
+  it("a recorded backend wins; self-hosted stays local", () => {
+    expect(chooseInstallBackend({ provider: "gcp", stateBackend: GCS }, true)).toBe("gcs");
+    expect(chooseInstallBackend({ provider: "gcp", stateBackend: { kind: "local" } }, false)).toBe(
+      "local",
+    );
+    expect(chooseInstallBackend({ provider: "self-hosted" }, false)).toBe("local");
+  });
+});
+
+describe("hasLocalPulumiState", () => {
+  it("is true only when the DIY backend holds a stack", () => {
+    const root = mkdtempSync(join(tmpdir(), "caelo-state-"));
+    try {
+      expect(hasLocalPulumiState(root)).toBe(false);
+      mkdirSync(join(root, "state", ".pulumi", "stacks", "caelo-gcp"), { recursive: true });
+      expect(hasLocalPulumiState(root)).toBe(true);
+      rmSync(join(root, "state", ".pulumi", "stacks", "caelo-gcp"), { recursive: true });
+      expect(hasLocalPulumiState(root)).toBe(false);
+      writeFileSync(join(root, "state", ".pulumi", "stacks", "production.json"), "{}");
+      expect(hasLocalPulumiState(root)).toBe(true);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});