@caelo-cms/provisioning 0.10.47 → 0.10.48

package/src/migration-runner.ts

@@ -0,0 +1,365 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P21 ship 3 — shared migration runner. Used by both the GCP wizard
+ * (apps/admin/scripts/wizards/gcp.ts) AND the lifecycle `upgrade`
+ * command (lifecycle.ts).
+ *
+ * Spawns a one-shot Cloud Run Job that invokes
+ * `bun /app/packages/migrations/src/migrate.ts <target>` against the
+ * private-IP Cloud SQL instance. The job inherits the running admin
+ * Cloud Run's image (so it always carries the matching migration set)
+ * + its database host + its network/subnet. Its database env follows the
+ * env contract (stack-contract.ts): password-less URLs plus the password
+ * as a Secret Manager reference, so the job spec never holds a password.
+ *
+ * Idempotent: drizzle's `__drizzle_migrations` table tracks applied
+ * versions, so re-runs only apply NEW migrations. Returns `{ok}` so
+ * callers (especially `upgrade`) can abort cleanly when a migration
+ * fails BEFORE traffic shifts to the new revision.
+ */
+
+import { spinner } from "@clack/prompts";
+import { green, red } from "kleur/colors";
+import { gcloud as defaultGcloud } from "./gcloud.js";
+import type { GcloudRunner } from "./gcloud-retry.js";
+import { GCP_STACK_ENV, gcpSecretId, runServiceAccountEmail } from "./gcp-names.js";
+import { databaseUrls, SERVICE_SECRET_ENV } from "./stack-contract.js";
+import { liveContainerEnv, liveDatabaseHost } from "./stack-converge.js";
+
+interface MigrationRunnerOpts {
+  readonly projectId: string;
+  readonly region: string;
+}
+
+interface AdminConfig {
+  readonly imageRef: string;
+  /** Cloud SQL private IP, from the admin's ADMIN_DATABASE_URL. */
+  readonly databaseHost: string;
+  readonly networkRef: string;
+  readonly subnetRef: string;
+  /**
+   * Whether the admin already reads the database password from Secret
+   * Manager. If not, its image may predate `databaseUrlFromEnv` and can't
+   * run a job with password-less URLs.
+   */
+  readonly secretEnv: boolean;
+}
+
+/** Why a job on the installed admin image would fail, for an install `upgrade` hasn't moved over. */
+const NEEDS_UPGRADE =
+  "the admin still reads the database password from its plain env, so its image may predate Secret Manager runtime secrets and can't run a job with password-less URLs. Run `upgrade` first.";
+
+/**
+ * The database env of a migration/truncate job: the admin's URLs (no
+ * password) as plain vars, the password vars as Secret Manager references
+ * — the same pairs the admin service carries. The job runs as the admin's
+ * run SA, which can read them.
+ */
+export function migrationJobEnvArgs(databaseHost: string, env = GCP_STACK_ENV): string[] {
+  const urls = databaseUrls(databaseHost);
+  const passwords = (["ADMIN_DATABASE_PASSWORD", "PUBLIC_ADMIN_DATABASE_PASSWORD"] as const).map(
+    (name) => {
+      const secret = SERVICE_SECRET_ENV.admin[name];
+      if (!secret) throw new Error(`the admin env contract has no ${name}`);
+      return `${name}=${gcpSecretId(env, secret)}:latest`;
+    },
+  );
+  return [
+    `--set-env-vars=ADMIN_DATABASE_URL=${urls.admin},PUBLIC_ADMIN_DATABASE_URL=${urls.publicAdmin}`,
+    `--set-secrets=${passwords.join(",")}`,
+  ];
+}
+
+/**
+ * Resolve the running admin Cloud Run service's image + database host +
+ * VPC config. Returns null on any failure; caller surfaces the error.
+ */
+export async function readAdminConfig(
+  opts: MigrationRunnerOpts,
+  gcloud: GcloudRunner,
+): Promise<AdminConfig | null> {
+  // Find the actual deployed service name (Pulumi appends a 7-char
+  // suffix; hardcoding the bare name 404s).
+  const list = await gcloud([
+    "run",
+    "services",
+    "list",
+    "--region",
+    opts.region,
+    "--project",
+    opts.projectId,
+    "--filter",
+    "metadata.name~^caelo-production-admin",
+    "--format=value(metadata.name)",
+  ]);
+  if (!list.ok) return null;
+  const serviceName = list.stdout.trim().split("\n")[0]?.trim();
+  if (!serviceName) return null;
+
+  const descr = await gcloud([
+    "run",
+    "services",
+    "describe",
+    serviceName,
+    "--region",
+    opts.region,
+    "--project",
+    opts.projectId,
+    "--format=json",
+  ]);
+  if (!descr.ok) return null;
+  return parseAdminConfig(descr.stdout);
+}
+
+/**
+ * The job config from the admin service (`gcloud run services describe
+ * --format=json`), or null when something the job needs is missing.
+ */
+export function parseAdminConfig(serviceJson: string): AdminConfig | null {
+  try {
+    const d = JSON.parse(serviceJson) as {
+      spec: {
+        template: {
+          metadata?: { annotations?: Record<string, string> };
+          spec: {
+            containers: { image?: string }[];
+            vpcAccess?: { networkInterfaces?: { network?: string; subnetwork?: string }[] };
+          };
+        };
+      };
+    };
+    const c = d.spec.template.spec.containers[0];
+    const imageRef = c?.image ?? "";
+    const liveEnv = liveContainerEnv(serviceJson);
+    const host = liveDatabaseHost(liveEnv);
+    let networkRef = "";
+    let subnetRef = "";
+    const niAnnotation =
+      d.spec.template.metadata?.annotations?.["run.googleapis.com/network-interfaces"];
+    if (niAnnotation) {
+      try {
+        const parsed = JSON.parse(niAnnotation) as { network?: string; subnetwork?: string }[];
+        networkRef = parsed[0]?.network ?? "";
+        subnetRef = parsed[0]?.subnetwork ?? "";
+      } catch {
+        // fall through
+      }
+    }
+    if (!networkRef || !subnetRef) {
+      const ni = d.spec.template.spec.vpcAccess?.networkInterfaces?.[0];
+      networkRef ||= ni?.network ?? "";
+      subnetRef ||= ni?.subnetwork ?? "";
+    }
+    if (!imageRef || !host.ok || !networkRef || !subnetRef) return null;
+    return {
+      imageRef,
+      databaseHost: host.host,
+      networkRef,
+      subnetRef,
+      secretEnv: liveEnv.get("ADMIN_DATABASE_PASSWORD")?.kind === "secret",
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run admin + public migrations against Cloud SQL. Returns `{ok}` so
+ * callers can decide what to do on failure (the wizard exits the
+ * process; upgrade aborts before rolling Cloud Run).
+ */
+/**
+ * v0.4.0 — Run TRUNCATE against cms_admin + cms_public via the same
+ * one-shot Cloud Run Job pattern the migrator uses. Wipes content /
+ * history / chat tables; keeps users / roles / providers / domains /
+ * site_defaults / provisioning_outputs / site_ai_memory.
+ *
+ * Useful after a schema change (e.g. v0.4.0's module/content split)
+ * when the operator wants the AI to start fresh against the new shape
+ * without destroying the install.
+ */
+export async function truncateViaCloudRunJob(
+  opts: MigrationRunnerOpts,
+): Promise<{ ok: boolean; error?: string }> {
+  const gcloud = defaultGcloud;
+  const sAdmin = spinner();
+  sAdmin.start("Reading admin Cloud Run config for truncate job...");
+  const cfg = await readAdminConfig(opts, gcloud);
+  if (!cfg) {
+    sAdmin.stop(red("Couldn't resolve admin config — admin may not be deployed yet"));
+    return { ok: false, error: "admin-config-unresolved" };
+  }
+  if (!cfg.secretEnv) {
+    sAdmin.stop(red(`Not truncating: ${NEEDS_UPGRADE}`));
+    return { ok: false, error: NEEDS_UPGRADE };
+  }
+  sAdmin.stop(green(`Admin config resolved (${cfg.imageRef.slice(-19)})`));
+
+  for (const target of ["admin", "public"] as const) {
+    const s = spinner();
+    s.start(`TRUNCATEing ${target} tables via one-shot Cloud Run Job...`);
+    await gcloud([
+      "run",
+      "jobs",
+      "delete",
+      `caelo-truncate-${target}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--quiet",
+    ]);
+    const create = await gcloud([
+      "run",
+      "jobs",
+      "create",
+      `caelo-truncate-${target}`,
+      `--image=${cfg.imageRef}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--service-account",
+      runServiceAccountEmail(opts.projectId, GCP_STACK_ENV),
+      "--network",
+      cfg.networkRef.split("/").pop() ?? cfg.networkRef,
+      "--subnet",
+      cfg.subnetRef.split("/").pop() ?? cfg.subnetRef,
+      "--vpc-egress=private-ranges-only",
+      "--command=bun",
+      `--args=--bun,/app/packages/migrations/src/truncate.ts,${target}`,
+      ...migrationJobEnvArgs(cfg.databaseHost),
+      "--max-retries=0",
+      "--task-timeout=5m",
+      "--quiet",
+    ]);
+    if (!create.ok) {
+      s.stop(red(`Job create failed: ${create.stderr.trim()}`));
+      return { ok: false, error: `truncate-${target}-create: ${create.stderr.trim()}` };
+    }
+    const exec = await gcloud([
+      "run",
+      "jobs",
+      "execute",
+      `caelo-truncate-${target}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--wait",
+    ]);
+    if (!exec.ok) {
+      s.stop(red(`${target} truncate failed: ${exec.stderr.trim()}`));
+      return { ok: false, error: `truncate-${target}-exec: ${exec.stderr.trim()}` };
+    }
+    s.stop(green(`${target} truncated`));
+  }
+  return { ok: true };
+}
+
+export async function runMigrationsViaCloudRunJob(
+  opts: MigrationRunnerOpts & {
+    /**
+     * v0.9.2 — explicit image to run migrations against. When omitted,
+     * falls back to the admin Cloud Run's CURRENT image (pre-upgrade
+     * shape). The upgrade lifecycle MUST pass the NEW image being
+     * rolled to — otherwise migrations run with the old image, which
+     * doesn't carry the new migration files, so the bookkeeping
+     * silently reports "no new migrations to apply" and the new admin
+     * image then hits "column does not exist" on every query for new
+     * schema. Operator-side recovery: `gcloud run jobs update
+     * caelo-migrate-admin --image=<new-version>` then execute.
+     */
+    readonly imageOverride?: string;
+  },
+  deps: { readonly run?: GcloudRunner } = {},
+): Promise<{ ok: boolean; error?: string }> {
+  const gcloud = deps.run ?? defaultGcloud;
+  const sAdmin = spinner();
+  sAdmin.start("Reading admin Cloud Run config for migration job...");
+  const cfg = await readAdminConfig(opts, gcloud);
+  if (!cfg) {
+    sAdmin.stop(red("Couldn't resolve admin config — admin may not be deployed yet"));
+    return { ok: false, error: "admin-config-unresolved" };
+  }
+  // With an override (upgrade) the job runs the NEW release, which reads
+  // the split env; without one it runs the installed image.
+  if (!opts.imageOverride && !cfg.secretEnv) {
+    sAdmin.stop(red(`Not migrating: ${NEEDS_UPGRADE}`));
+    return { ok: false, error: NEEDS_UPGRADE };
+  }
+  const migrationImage = opts.imageOverride ?? cfg.imageRef;
+  if (opts.imageOverride && opts.imageOverride !== cfg.imageRef) {
+    sAdmin.stop(
+      green(
+        `Admin config resolved; migrating against NEW image (${migrationImage.slice(-19)}) instead of current (${cfg.imageRef.slice(-19)})`,
+      ),
+    );
+  } else {
+    sAdmin.stop(green(`Admin config resolved (${migrationImage.slice(-19)})`));
+  }
+
+  for (const target of ["admin", "public"] as const) {
+    const s = spinner();
+    s.start(`Applying ${target} migrations via one-shot Cloud Run Job...`);
+    // Delete-then-create so each invocation runs with the freshest
+    // image + env (no stale job specs).
+    await gcloud([
+      "run",
+      "jobs",
+      "delete",
+      `caelo-migrate-${target}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--quiet",
+    ]);
+    const create = await gcloud([
+      "run",
+      "jobs",
+      "create",
+      `caelo-migrate-${target}`,
+      `--image=${migrationImage}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--service-account",
+      runServiceAccountEmail(opts.projectId, GCP_STACK_ENV),
+      "--network",
+      cfg.networkRef.split("/").pop() ?? cfg.networkRef,
+      "--subnet",
+      cfg.subnetRef.split("/").pop() ?? cfg.subnetRef,
+      "--vpc-egress=private-ranges-only",
+      "--command=bun",
+      `--args=--bun,/app/packages/migrations/src/migrate.ts,${target}`,
+      ...migrationJobEnvArgs(cfg.databaseHost),
+      "--max-retries=0",
+      "--task-timeout=10m",
+      "--quiet",
+    ]);
+    if (!create.ok) {
+      s.stop(red(`Job create failed: ${create.stderr.trim()}`));
+      return { ok: false, error: `migrate-${target}-create: ${create.stderr.trim()}` };
+    }
+    const exec = await gcloud([
+      "run",
+      "jobs",
+      "execute",
+      `caelo-migrate-${target}`,
+      "--region",
+      opts.region,
+      "--project",
+      opts.projectId,
+      "--wait",
+    ]);
+    if (!exec.ok) {
+      s.stop(red(`${target} migrations failed: ${exec.stderr.trim()}`));
+      return { ok: false, error: `migrate-${target}-exec: ${exec.stderr.trim()}` };
+    }
+    s.stop(green(`${target} migrations applied`));
+  }
+  return { ok: true };
+}

package/src/operator-access-stacks.test.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The stacks must give the admin's run SA no IAM-policy rights for operator
+ * access: the sync job (operator-access.ts, CLI-owned) is the only principal
+ * allowed to change who passes IAP. What the stacks DO carry for it: the
+ * Cloud SQL flag that lets the job log in as its service account, and the
+ * admin env var naming the job (stack-contract.ts). Pure-string checks, like
+ * mcp-iap-stacks.test.ts.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { adminEnvContract, databaseUrls } from "./stack-contract.js";
+
+const stack = (provider: string) =>
+  readFileSync(resolve(import.meta.dir, `../stacks/${provider}/index.ts`), "utf8");
+
+describe.each(["gcp", "gcp-firebase"])("%s stack — operator access", (provider) => {
+  const src = stack(provider);
+
+  it("grants no IAM-policy-writing role to anyone for operator access", () => {
+    expect(src).not.toContain("caeloOperatorAccess");
+    expect(src).not.toContain("caeloAdminIapLookup");
+    expect(src).not.toContain("IAMCustomRole");
+    expect(src).not.toMatch(/setIamPolicy|roles\/iap\.admin|roles\/iam\.serviceAccountAdmin/);
+  });
+
+  it("turns on Cloud SQL IAM database authentication for the job's read-only user", () => {
+    expect(src).toContain('{ name: "cloudsql.iam_authentication", value: "on" }');
+  });
+
+  it("deploys the admin with the env contract, which names the sync job", () => {
+    expect(src).toContain("adminEnvContract(");
+  });
+});
+
+describe("admin env contract — operator access", () => {
+  it("names the sync job the admin may start", () => {
+    const env = adminEnvContract({
+      provider: "gcp",
+      projectId: "acme",
+      env: "production",
+      domain: "acme.com",
+      stagingHost: "staging.acme.com",
+      region: "europe-west1",
+      databaseUrls: databaseUrls("10.0.0.3"),
+    });
+    expect(env).toContainEqual({
+      name: "CAELO_OPERATOR_ACCESS_JOB",
+      value: "projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync",
+    });
+  });
+});