@codeyam-editor/codeyam-editor 0.1.1 → 0.1.2

package/npm/cloud.js

@@ -0,0 +1,1521 @@
+#!/usr/bin/env node
+
+/**
+ * cloud.js — one-command orchestrator for hosting a codeyam-editor session
+ * on a GCE VM. Reuses `scripts/gcp-bootstrap.sh` and
+ * `scripts/gcp-project-bootstrap.sh` verbatim by streaming them over
+ * `gcloud compute ssh`. Per-project state lives in `.codeyam/cloud.json`
+ * (gitignored) so the second invocation is zero-arg. See
+ * `docs/cloud-gcp.md` for the runbook this wraps.
+ */
+
+const { spawn, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+const {
+  rootDir,
+  isPortInUse,
+  waitForPort,
+  deepMergeJson,
+  killChildProcess,
+} = require("./utils");
+const { open } = require("./open");
+// `FORWARD_ENV_KEYS_ENV` is the env-var name (`CY_FORWARD_ENV_KEYS`) the
+// fleet dashboard sets on `cloud:up`'s child to name the subset of
+// `process.env` keys that came from the operator-supplied launch form.
+// Imported from `fleet-env` (single source of truth) so the dashboard and
+// cloud:up can never drift on the contract — a string mismatch would
+// silently disable the forwarding.
+const { FORWARD_ENV_KEYS_ENV } = require("./fleet-env");
+// Deterministic fleet-ingress URL derivation. `resolveFleetDomain` reads the
+// operator's owned domain from env (null when unset); `vmUrls` derives a VM's
+// stable `https://vm-<N>.preview.<domain>` previewOrigin from its number. When
+// no domain is configured these stay dormant and the legacy quick-tunnel seed
+// path runs unchanged.
+const { resolveFleetDomain, vmUrls } = require("./vm-urls");
+// Shared fleet-roster writer. `cloud:up` rosters the VM it just provisioned so
+// the dashboard, the cloudflared-monitor tunnel publisher, and the watchdog see
+// it within one poll cycle — without a manual fleet-vms.json edit (the
+// invisible-VM gap improve38 closes).
+const { addToRoster } = require("./fleet-roster");
+
+// =============================================================================
+// Pure helpers — every export here is unit-tested in cloud.test.js without
+// touching `gcloud` or the network.
+// =============================================================================
+
+const AGENT_ENV_VARS = {
+  claude: "ANTHROPIC_API_KEY",
+  codex: "OPENAI_API_KEY",
+  gemini: "GEMINI_API_KEY",
+};
+
+const KNOWN_FLAGS = [
+  "repo", "branch", "instance-name", "project", "zone", "agent",
+  // Editor-source selection, decoupled from the client project (repo/branch):
+  "editor-repo", "editor-branch", "editor-variant",
+  // Greenfield: launch against a NEW empty folder (no repo to clone) named
+  // <name>; the bootstrap mkdir+git-init+inits it and the editor's onboarding
+  // workflow takes over. Mutually exclusive with --repo.
+  "new-project",
+  // Provisioning-only: skip cloud:up's own laptop tunnel (the caller opens its
+  // own). Lets cloud:up exit cleanly + avoids parallel runs contending on the
+  // fixed local ports 14199/5173.
+  "no-tunnel",
+  // Opt out of the project's `npm run setup` at provision time. The bootstrap
+  // runs setup by default when the project ships one; pass this for projects
+  // where a cloud setup is genuinely wrong (the script's --skip-setup hatch).
+  "skip-setup",
+];
+
+// Flags that take no value (presence = true). parseFlags must not demand a
+// value for these or `--no-tunnel` would error "requires a value".
+const BOOLEAN_FLAGS = ["no-tunnel", "skip-setup"];
+
+const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
+const INSTANCE_TAG = "codeyam-editor";
+const EDITOR_PORT = 14199;
+const VITE_PORT = 5173;
+
+// Sentinel stamped into editor.local.json's `_managedPreviewOrigin` whenever
+// WE (cloud:up's seed, or the operator's cloudflared-monitor) write the
+// previewOrigin. It lets the monitor tell its own writes (overwrite freely on
+// respawn) apart from a user-pinned origin (never clobber). Must match the
+// literal the bash monitor writes — see scripts/operator/cloudflared-monitor.sh.
+const MANAGED_PREVIEW_ORIGIN = "cloudflared-monitor";
+
+// The reserved same-origin path the Live Preview is served under. Seeded as the
+// quick-tunnel `previewOrigin` so the iframe loads the app from the editor's own
+// origin (relative path, no `localhost:<port>` URL) — killing Chrome's Private
+// Network Access block and any cross-VM port collision. A constant relative path
+// never rotates, so the cloudflared-monitor has nothing to push for it. Mirrors
+// the Rust `preview_proxy_route::PREVIEW_PATH_PREFIX`.
+const SAME_ORIGIN_PREVIEW_PATH = "/__codeyam_preview";
+
+// Operator-laptop sidecar the cloudflared-monitor writes per-VM tunnel URLs
+// into. cloud:up reads it to seed a VM's previewOrigin with the public
+// `<N>-preview` URL when the monitor has already published one. Same default
+// path + env override the monitor and fleet dashboard use.
+const CLOUDFLARED_URLS_FILE =
+  process.env.URLS_FILE ||
+  path.join(rootDir, ".codeyam", "logs", "cloudflared-urls.json");
+
+// Canonical codeyam-editor repository — the default source for the editor
+// IMAGE, independent of the CLIENT project being edited (cfg.repo). Decoupling
+// these is what lets one VM edit client project A while running the editor
+// built from codeyam-editor branch B. Before this split, cfg.repo/cfg.branch
+// fed BOTH the image build and the /workspace clone, so only the self-host case
+// (client === editor) worked; a non-self-host VM tried to build the editor
+// image out of the client repo.
+const CANONICAL_EDITOR_REPO = "https://github.com/codeyam-ai/codeyam-editor.git";
+
+// The editor distribution channels an operator can pick per VM:
+//   dev        — build the editor image from the editor repo @ editorBranch
+//                (today's path; the only one wired into provisioning so far)
+//   staging    — `npm i -g @codeyam-editor/codeyam-editor@staging` (Phase 2)
+//   production — `npm i -g @codeyam-editor/codeyam-editor`          (Phase 2)
+const EDITOR_VARIANTS = ["dev", "staging", "production"];
+
+/** Map an agent name to its API-key env var. Throws on unknown agents so
+ *  adding an agent is a one-entry change in `AGENT_ENV_VARS`, never a
+ *  silent fallthrough that ships unauthenticated. */
+function agentEnvVarName(agent) {
+  if (!Object.prototype.hasOwnProperty.call(AGENT_ENV_VARS, agent)) {
+    throw new Error(
+      `Unknown agent: ${agent}. Supported: ${Object.keys(AGENT_ENV_VARS).join(", ")}`,
+    );
+  }
+  return AGENT_ENV_VARS[agent];
+}
+
+/** Parse `--flag value` argv into an object. Unknown flags or missing values
+ *  throw with a usage hint — silently dropping them would let typos like
+ *  `--branchh main` succeed with no branch flag at all. */
+function parseFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      throw new Error(
+        `Unexpected positional argument: ${arg}\n` +
+          `Usage: npm run cloud:<up|tunnel|stop|destroy|status> -- [${KNOWN_FLAGS
+            .map((f) => `--${f} <value>`)
+            .join("] [")}]`,
+      );
+    }
+    const key = arg.slice(2);
+    if (!KNOWN_FLAGS.includes(key)) {
+      throw new Error(`Unknown flag: ${arg}. Known: --${KNOWN_FLAGS.join(", --")}`);
+    }
+    const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (BOOLEAN_FLAGS.includes(key)) {
+      flags[camel] = true;
+      continue;
+    }
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`${arg} requires a value`);
+    }
+    flags[camel] = value;
+    i++;
+  }
+  return flags;
+}
+
+/** Strip `.git`, take the basename, lowercase, collapse non-alphanumerics to
+ *  hyphens. Mirrors the existing `scripts/gcp-project-bootstrap.sh` derivation
+ *  so the directory layout on the VM matches the instance name 1:1. */
+function repoBasename(repoUrl) {
+  const stripped = repoUrl.replace(/\.git$/i, "");
+  const parts = stripped.split(/[/:]+/).filter(Boolean);
+  return parts[parts.length - 1] || "project";
+}
+
+/** Construct a deterministic instance name from a repo URL. GCE caps
+ *  instance names at 63 chars; we cap at 40 to keep room for hyphen
+ *  separators and stay well below the limit. */
+function deriveInstanceName(repoUrl) {
+  const base = repoBasename(repoUrl);
+  let slug = base
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  if (!slug) slug = "project";
+  let name = `codeyam-editor-${slug}`;
+  if (name.length > 40) name = name.slice(0, 40).replace(/-+$/g, "");
+  return name;
+}
+
+/** Normalize two repo URLs for equality: strip a trailing `.git`, lowercase.
+ *  Used to detect the self-host case (client repo IS the editor repo). */
+function sameRepo(a, b) {
+  const norm = (s) => String(s || "").replace(/\.git$/i, "").toLowerCase();
+  return !!a && !!b && norm(a) === norm(b);
+}
+
+/** Pick the default GCE instance name a freshly launched `cloud:up` should
+ *  mint for `repoUrl`. The canonical fleet repo (`codeyam-editor`) is part of
+ *  the numbered fleet — VM-1 must match the dashboard's `INSTANCE_PREFIX + 1`
+ *  shape (`<base>-1`), every VM is `<base>-<n>`. A client repo (single-VM)
+ *  keeps the un-suffixed base (`codeyam-editor-<slug>`). Pure / disk-free so
+ *  the convention is testable without going through loadOrInitCloudConfig. */
+function defaultInstanceNameFor(repoUrl) {
+  const base = deriveInstanceName(repoUrl);
+  return sameRepo(repoUrl, CANONICAL_EDITOR_REPO) ? `${base}-1` : base;
+}
+
+/** Resolve the fleet VM number from an instance name, or null when the name
+ *  isn't a fleet self-host instance. The fleet base is the instance name
+ *  `deriveInstanceName` returns for the canonical editor repo; every VM is
+ *  `<base>-<n>` (VM-1 = `<base>-1`, VM-N = `<base>-N`), matching the
+ *  dashboard's INSTANCE_PREFIX + n. As a back-compat read path the bare
+ *  `<base>` (no suffix) also resolves to VM-1, so any lingering legacy
+ *  instance or old log is still recognized. A non-fleet client project
+ *  (`codeyam-editor-<slug>`) returns null so its previewOrigin seed never
+ *  picks up a fleet tunnel URL. */
+function resolveFleetVmNumber(instanceName) {
+  const base = deriveInstanceName(CANONICAL_EDITOR_REPO);
+  const name = String(instanceName || "");
+  if (name === base) return 1;
+  const m = new RegExp(`^${base}-(\\d+)$`).exec(name);
+  return m ? Number(m[1]) : null;
+}
+
+/** Roster a just-provisioned VM into the fleet dashboard's view so it (and the
+ *  cloudflared-monitor + watchdog that read the same roster) pick it up within
+ *  one poll cycle — closing the invisible-VM gap where a CLI `cloud:up` left the
+ *  VM out of `fleet-vms.json` until a manual edit.
+ *
+ *  Best-effort and non-fatal: a roster-write failure warns loudly (surfacing it
+ *  is the whole point of this fix) but never aborts an otherwise-successful
+ *  provision. A non-fleet instance name (`resolveFleetVmNumber` → null, e.g. a
+ *  guest/standalone editor) is skipped — only fleet-numbered VMs roster.
+ *
+ *  Returns `{ status, vm }` where `status` is `"rostered" | "skipped" |
+ *  "failed"`. `deps` is injectable so the unit test drives every branch without
+ *  touching the real roster file. */
+function rosterProvisionedVm(instanceName, deps = {}) {
+  const resolve = deps.resolveFleetVmNumber || resolveFleetVmNumber;
+  const add = deps.addToRoster || addToRoster;
+  const log = deps.log || ((m) => console.error(m));
+  const n = resolve(instanceName);
+  if (n == null) {
+    log(`(instance '${instanceName}' is not a fleet VM — skipping dashboard roster)`);
+    return { status: "skipped", vm: null };
+  }
+  try {
+    add(n);
+    log(`✓ rostered VM-${n} into the fleet dashboard`);
+    return { status: "rostered", vm: n };
+  } catch (e) {
+    log(
+      `⚠ failed to roster VM-${n} (${e && e.message}). The VM is provisioned ` +
+        "but the dashboard won't show it until it's rostered — add it via the " +
+        "dashboard's Adopt action or re-run cloud:up.",
+    );
+    return { status: "failed", vm: n };
+  }
+}
+
+/** Resolve the app's dev-server port from a parsed editor.json plus an optional
+ *  editor.local.json overlay, mirroring `EditorConfig::resolved_port()`:
+ *  `apps[0].port` wins, then the top-level `port`, then `VITE_PORT` (5173) as
+ *  the final fallback for a config that specifies neither. editor.local.json
+ *  fields override editor.json (deep-merge precedence — the same rule the editor
+ *  applies via `load_config_with_overrides`). The runtime env override
+ *  (`CODEYAM_APP_PORT_OVERRIDE`) is intentionally NOT consulted here: cloud:up
+ *  reads the static, committed config at provision time. */
+function resolveConfiguredAppPort(editorJson = {}, editorLocalJson = {}) {
+  const merged = deepMergeJson(editorJson || {}, editorLocalJson || {});
+  const apps0 =
+    Array.isArray(merged.apps) && merged.apps[0] ? merged.apps[0] : {};
+  const raw = apps0.port != null ? apps0.port : merged.port;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : VITE_PORT;
+}
+
+/** Decide the previewOrigin patch to seed into a VM's editor.local.json.
+ *
+ *  Named-tunnel mode (FLEET_DOMAIN set, the VM is a fleet self-host VM): the
+ *  previewOrigin is the VM's *deterministic* preview hostname
+ *  (`https://vm-<N>.preview.<domain>`), derived purely from the VM number. It
+ *  never rotates, so there is no monitor URL to look up and — crucially — no
+ *  `http://localhost:<port>` fallback that could silently point the iframe at an
+ *  unreachable origin (the failure class improve38 closes). The named tunnel
+ *  fronts the dev server on whatever port it serves, so the seed stays
+ *  port-agnostic in this mode.
+ *
+ *  Legacy quick-tunnel mode (no FLEET_DOMAIN, or a non-fleet client project):
+ *  when the operator's cloudflared-monitor has already published a `<N>-preview`
+ *  quick-tunnel URL in cloudflared-urls.json, that URL is the steady-state
+ *  origin; otherwise fall back to the in-VM dev-server port (`appPort`, defaults
+ *  to 5173) — the bootstrap value for the window before the monitor's first
+ *  tick. This is the unchanged behavior for any fleet that hasn't adopted a
+ *  named-tunnel domain yet.
+ *
+ *  Either way we stamp `_managedPreviewOrigin` so the (legacy) monitor
+ *  recognises the value as ours and won't mistake the cloud:up seed for a user
+ *  pin. `env` is injectable so the unit test can drive both modes. */
+function resolveSeedPreviewOrigin(
+  instanceName,
+  urls = {},
+  appPort = VITE_PORT,
+  env = process.env,
+) {
+  const vm = resolveFleetVmNumber(instanceName);
+  const domain = resolveFleetDomain(env);
+  // Named tunnels are per fleet-VM; a non-fleet client project (vm == null)
+  // keeps the legacy localhost seed even when a domain is configured.
+  if (domain && vm != null) {
+    return {
+      previewOrigin: vmUrls(vm, domain).preview,
+      _managedPreviewOrigin: MANAGED_PREVIEW_ORIGIN,
+    };
+  }
+  // Quick-tunnel / domain-free mode: serve the app same-origin under the
+  // reserved relative path. The editor mounts `/__codeyam_preview` on its own
+  // origin and forwards to the in-VM app-port reverse proxy, so the iframe loads
+  // from the exact origin the editor is served on (public quick-tunnel,
+  // SSH-tunnel localhost, anything). This replaces the prior
+  // `http://localhost:${appPort}` seed — a loopback URL a public editor page
+  // could not load (Private Network Access block) — and the monitor's rotating
+  // `<N>-preview` quick-tunnel URL, which a constant relative path makes moot.
+  // `appPort` / `urls` are retained in the signature for callers but no longer
+  // seeded — the same-origin path is a constant.
+  return {
+    previewOrigin: SAME_ORIGIN_PREVIEW_PATH,
+    _managedPreviewOrigin: MANAGED_PREVIEW_ORIGIN,
+  };
+}
+
+/** Read the operator-laptop cloudflared-urls.json sidecar. Missing/unparseable
+ *  → {} (the monitor may not have run yet; the seed falls back to localhost). */
+function readCloudflaredUrls() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CLOUDFLARED_URLS_FILE, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Resolve the editor-source config (repo/branch/variant) from cfg, applying
+ *  defaults. `editorRepo` defaults to CANONICAL_EDITOR_REPO so a non-self-host
+ *  client project still builds its editor image from the editor source, not the
+ *  client repo. Self-host back-compat: when the client repo IS the editor repo
+ *  and no explicit editorBranch was given, the client branch doubles as the
+ *  editor source branch — so `cloud:up --repo codeyam-editor --branch X` still
+ *  builds the editor at X, exactly as it did before the decoupling. */
+function resolveEditorConfig(cfg = {}) {
+  const editorRepo = cfg.editorRepo || CANONICAL_EDITOR_REPO;
+  let editorBranch = cfg.editorBranch;
+  if ((editorBranch == null || editorBranch === "") && sameRepo(cfg.repo, editorRepo)) {
+    editorBranch = cfg.branch;
+  }
+  const editorVariant = cfg.editorVariant || "dev";
+  return { editorRepo, editorBranch: editorBranch || undefined, editorVariant };
+}
+
+/** Throw on an unknown editor variant (a typo'd `--editor-variant` should fail,
+ *  not silently fall through to dev). */
+function validateEditorVariant(variant) {
+  if (!EDITOR_VARIANTS.includes(variant)) {
+    throw new Error(
+      `Unknown editor variant: ${variant}. Supported: ${EDITOR_VARIANTS.join(", ")}`,
+    );
+  }
+  return variant;
+}
+
+/** Phase-1 gate: only `dev` is wired into cloud provisioning. The
+ *  staging/production npm-install container image lands in Phase 2. Fails loud
+ *  with an actionable message rather than silently building a dev image. */
+function assertVariantProvisionable(variant) {
+  validateEditorVariant(variant);
+  if (variant !== "dev") {
+    throw new Error(
+      `Editor variant '${variant}' is not yet wired for cloud provisioning ` +
+        `(Phase 2 — the @staging/production npm-install image). Use --editor-variant dev.`,
+    );
+  }
+  return variant;
+}
+
+/** Args for scripts/gcp-bootstrap.sh, which builds the codeyam-editor:local
+ *  image from the EDITOR source — NOT the client project. */
+function editorImageBootstrapArgs(cfg) {
+  const { editorRepo, editorBranch } = resolveEditorConfig(cfg);
+  const args = ["--agent", cfg.agent, "--repo", editorRepo];
+  if (editorBranch) args.push("--branch", editorBranch);
+  return args;
+}
+
+/** Resolve the CLIENT project from cfg: either an existing repo to clone, or a
+ *  greenfield new folder to scaffold. `name` is the on-VM directory basename
+ *  (under ~/projects/) — derived from the repo for the clone case, or the
+ *  given folder name for greenfield. */
+/** --repo and --new-project are mutually exclusive. When one is explicitly
+ *  passed THIS run, drop the other from the (possibly cloud.json-merged) config
+ *  so a stale value — e.g. a prior greenfield's `newProject` left in cloud.json
+ *  — can't override the new intent. Without this, launching `--repo X` after a
+ *  greenfield run silently provisions the greenfield project (resolveProject
+ *  prioritizes newProject). Mutates and returns cfg. */
+function reconcileProjectExclusivity(cfg, flags = {}) {
+  if (flags.repo) delete cfg.newProject;
+  if (flags.newProject) { delete cfg.repo; delete cfg.branch; }
+  return cfg;
+}
+
+function resolveProject(cfg = {}) {
+  if (cfg.newProject) {
+    return { greenfield: true, name: cfg.newProject, repo: null, branch: null };
+  }
+  return {
+    greenfield: false,
+    name: cfg.repo ? repoBasename(cfg.repo) : null,
+    repo: cfg.repo || null,
+    branch: cfg.branch || null,
+  };
+}
+
+/** Args for scripts/gcp-project-bootstrap.sh. For an existing repo: the repo URL
+ *  (+ optional --branch) to clone. For greenfield: --new-project <name>, so the
+ *  bootstrap creates an empty git-init'd folder and inits it instead of cloning. */
+function clientProjectBootstrapArgs(cfg) {
+  const p = resolveProject(cfg);
+  // The bootstrap now runs `npm run setup` by default when the project ships
+  // one; --skip-setup is the opt-out, threaded from the cloud:up flag. (A
+  // greenfield launch starts from an empty git-init'd folder with no setup
+  // script, so the flag is a harmless no-op there.)
+  const setupArgs = cfg.skipSetup ? ["--skip-setup"] : [];
+  if (p.greenfield) return ["--new-project", p.name, ...setupArgs];
+  const args = [cfg.repo];
+  if (cfg.branch) args.push("--branch", cfg.branch);
+  args.push(...setupArgs);
+  return args;
+}
+
+function cloudConfigPath(projectDir) {
+  return path.join(projectDir, ".codeyam", "cloud.json");
+}
+
+/** Returns the parsed config, or `null` when the file is absent. Throws
+ *  with the full path on malformed JSON so the user knows which file to
+ *  fix — silently returning `null` would mask corruption as "no config". */
+function loadCloudConfig(projectDir) {
+  const p = cloudConfigPath(projectDir);
+  if (!fs.existsSync(p)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(p, "utf8");
+  } catch (e) {
+    throw new Error(`Failed to read ${p}: ${e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Failed to parse ${p}: ${e.message}`);
+  }
+}
+
+function saveCloudConfig(projectDir, cfg) {
+  const p = cloudConfigPath(projectDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+/** Build the JSON patch to merge into the VM's `editor.local.json` so the
+ *  configured agent picks up the user's local API key on first launch.
+ *  Returns `null` when the key isn't set locally — the wrapper then prints
+ *  the interactive-auth fallback line instead of writing an empty patch. */
+function buildEditorLocalEnvPatch(localEnv, agent) {
+  const varName = agentEnvVarName(agent);
+  const value = localEnv[varName];
+  if (!value) return null;
+  return { env: { [varName]: value } };
+}
+
+/** Parse `docker compose ps --format json` (compose v2 — one JSON object per
+ *  line) and return the editor service's `State` string, or null when the
+ *  service is absent / output is unparseable. Two callers shared an identical
+ *  inline parser; this centralizes the shape so a compose-output change is
+ *  one update, not two. */
+function parseEditorComposeState(stdout) {
+  if (!stdout) return null;
+  const lines = String(stdout).trim().split("\n").filter(Boolean);
+  for (const line of lines) {
+    let svc;
+    try {
+      svc = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (svc && svc.Service === "editor") {
+      return svc.State || null;
+    }
+  }
+  return null;
+}
+
+/** Translate one of the wrapper's verbs into the exact `gcloud` argv. The
+ *  switch's job is to keep every per-verb command shape in one reviewable
+ *  place — tests assert the arrays without ever spawning a process. */
+function buildGcloudArgs(verb, cfg = {}, extras = {}) {
+  const { project, zone, instanceName } = cfg;
+  switch (verb) {
+    case "config-get-project":
+      return ["config", "get-value", "project"];
+    case "config-get-zone":
+      return ["config", "get-value", "compute/zone"];
+    case "instances-create":
+      // The VM keeps the default ephemeral external IP so apt / docker /
+      // NodeSource / npm can reach the public internet during bootstrap.
+      // Inbound is still IAP-SSH-only via the firewall rule above; the
+      // external IP is for egress, not exposure. `--no-address` was the
+      // earlier default but produced a VM that could not install Docker
+      // without a Cloud NAT + Cloud Router pair the wrapper does not set up.
+      return [
+        "compute", "instances", "create", instanceName,
+        "--project", project, "--zone", zone,
+        "--machine-type=e2-standard-4",
+        "--image-family=debian-12",
+        "--image-project=debian-cloud",
+        "--boot-disk-size=100GB",
+        "--boot-disk-type=pd-balanced",
+        `--tags=${INSTANCE_TAG}`,
+      ];
+    case "instances-start":
+      return ["compute", "instances", "start", instanceName, "--project", project, "--zone", zone];
+    case "instances-stop":
+      return ["compute", "instances", "stop", instanceName, "--project", project, "--zone", zone];
+    case "instances-delete":
+      return ["compute", "instances", "delete", instanceName, "--project", project, "--zone", zone, "--quiet"];
+    case "instances-describe":
+      return ["compute", "instances", "describe", instanceName, "--project", project, "--zone", zone, "--format=json"];
+    case "instances-list-tagged":
+      return [
+        "compute", "instances", "list",
+        "--project", project,
+        `--filter=tags.items:${INSTANCE_TAG}`,
+        "--format=value(name)",
+      ];
+    case "firewall-describe":
+      return ["compute", "firewall-rules", "describe", FIREWALL_RULE_NAME, "--project", project, "--format=json"];
+    case "firewall-create":
+      return [
+        "compute", "firewall-rules", "create", FIREWALL_RULE_NAME,
+        "--project", project,
+        "--direction=INGRESS",
+        "--action=ALLOW",
+        "--rules=tcp:22",
+        "--source-ranges=35.235.240.0/20",
+        `--target-tags=${INSTANCE_TAG}`,
+      ];
+    case "firewall-delete":
+      return ["compute", "firewall-rules", "delete", FIREWALL_RULE_NAME, "--project", project, "--quiet"];
+    case "ssh-probe":
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--command", extras.command,
+      ];
+    case "ssh-script":
+      // Stream a script body as base64 over --command so we don't fight
+      // shell-quoting through gcloud → ssh → remote bash. The script body
+      // is delivered as one argument; the wrapper feeds the base64 into
+      // `extras.command` and the caller sets `input` to the script body.
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--command", extras.command,
+      ];
+    case "ssh-tunnel": {
+      // Bind BOTH IPv4 and IPv6 loopback for each port. The IPv4 `-L` is
+      // load-bearing for everything that explicitly dials 127.0.0.1; the
+      // `[::1]` `-L` exists because cloudflared (`tunnel --url
+      // http://localhost:N`) resolves `localhost` to `[::1]` first and,
+      // with an IPv4-only forward, hits connect:connection-refused until
+      // the QUIC stream cancels and the tunnel proc exits (~80% of
+      // cloudflared deaths in the 2026-05-21 fleet session). Binding the
+      // IPv6 loopback too lets that first dial succeed.
+      //
+      // The preview forward uses the resolved app port (extras.appPort,
+      // default VITE_PORT) on BOTH ends — laptop:<appPort> → VM:<appPort> —
+      // so the whole single-user path uses one number for a Vite 5173, a
+      // Next.js 3000, anything. The editor `-L` (14199) is unconditional.
+      const appPort = extras.appPort != null ? extras.appPort : VITE_PORT;
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--",
+        "-L", `${EDITOR_PORT}:127.0.0.1:${EDITOR_PORT}`,
+        "-L", `[::1]:${EDITOR_PORT}:127.0.0.1:${EDITOR_PORT}`,
+        "-L", `${appPort}:127.0.0.1:${appPort}`,
+        "-L", `[::1]:${appPort}:127.0.0.1:${appPort}`,
+        "-N",
+      ];
+    }
+    default:
+      throw new Error(`Unknown gcloud verb: ${verb}`);
+  }
+}
+
+// =============================================================================
+// Side-effecting helpers — exercised end-to-end by `npm run cloud:up` in
+// real use. Unit tests pin their exports so a refactor cannot drop them.
+// =============================================================================
+
+function runGcloud(args, opts = {}) {
+  return spawnSync("gcloud", args, {
+    stdio: opts.stdio || "inherit",
+    input: opts.input,
+    encoding: opts.encoding || "utf8",
+  });
+}
+
+function ensureGcloud() {
+  const result = spawnSync("gcloud", ["version"], { stdio: "ignore" });
+  if (result.error || result.status !== 0) {
+    console.error(
+      "gcloud is not on PATH. Install: https://cloud.google.com/sdk/docs/install",
+    );
+    process.exit(1);
+  }
+}
+
+function gcloudGetValue(verb) {
+  const result = runGcloud(buildGcloudArgs(verb), { stdio: ["ignore", "pipe", "ignore"] });
+  if (result.error || result.status !== 0) return null;
+  const val = String(result.stdout || "").trim();
+  if (!val || val === "(unset)") return null;
+  return val;
+}
+
+/** Run `gcloud compute instances describe ... --format=json` and return the
+ *  parsed `.status` field (e.g. "RUNNING", "TERMINATED", "PROVISIONING"), or
+ *  null when the instance is absent or describe returned unparseable output.
+ *  Centralizes the describe-and-parse pattern shared by ensureInstance (used
+ *  twice — initial probe + poll), cmdTunnel, and cmdStatus. */
+function fetchInstanceState(cfg) {
+  const result = runGcloud(buildGcloudArgs("instances-describe", cfg), {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.status !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return parsed && typeof parsed.status === "string" ? parsed.status : null;
+  } catch {
+    return null;
+  }
+}
+
+function loadOrInitCloudConfig(projectDir, flags) {
+  const existing = loadCloudConfig(projectDir);
+  // noTunnel is a per-invocation behavior, never persisted — else a later manual
+  // `cloud:up` (zero-arg, reading cloud.json) would silently skip its tunnel.
+  const persist = (c) => { const { noTunnel, ...rest } = c; return rest; };
+  if (existing) {
+    const merged = reconcileProjectExclusivity({ ...existing, ...flags }, flags);
+    const toSave = persist(merged);
+    if (JSON.stringify(toSave) !== JSON.stringify(existing)) {
+      saveCloudConfig(projectDir, toSave);
+    }
+    return merged;
+  }
+
+  const cfg = reconcileProjectExclusivity({ ...flags }, flags);
+  cfg.project = cfg.project || gcloudGetValue("config-get-project");
+  cfg.zone = cfg.zone || gcloudGetValue("config-get-zone");
+  cfg.agent = cfg.agent || "claude";
+  agentEnvVarName(cfg.agent);
+
+  if (!cfg.repo && !cfg.newProject) {
+    throw new Error(
+      "--repo <url> (clone an existing project) or --new-project <name> (greenfield) " +
+        "is required on first run. Subsequent runs read .codeyam/cloud.json.",
+    );
+  }
+  if (!cfg.project) {
+    throw new Error(
+      "--project not provided and `gcloud config get-value project` returned no default.\n" +
+        "Run `gcloud config set project <id>` or pass --project <id>.",
+    );
+  }
+  if (!cfg.zone) {
+    throw new Error(
+      "--zone not provided and `gcloud config get-value compute/zone` returned no default.\n" +
+        "Run `gcloud config set compute/zone <zone>` or pass --zone <zone>.",
+    );
+  }
+
+  cfg.instanceName = cfg.instanceName || defaultInstanceNameFor(cfg.repo || cfg.newProject);
+  saveCloudConfig(projectDir, persist(cfg));
+  return cfg;
+}
+
+async function ensureFirewallRule(cfg) {
+  console.error(`Checking firewall rule ${FIREWALL_RULE_NAME}...`);
+  const describe = runGcloud(buildGcloudArgs("firewall-describe", cfg), {
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (describe.status === 0) {
+    console.error(`  ✓ ${FIREWALL_RULE_NAME} already exists`);
+    return;
+  }
+  console.error(`  creating ${FIREWALL_RULE_NAME}...`);
+  const create = runGcloud(buildGcloudArgs("firewall-create", cfg));
+  if (create.status !== 0) {
+    throw new Error(`Failed to create firewall rule ${FIREWALL_RULE_NAME}`);
+  }
+}
+
+async function ensureInstance(cfg) {
+  console.error(`Checking instance ${cfg.instanceName}...`);
+  const initialState = fetchInstanceState(cfg);
+  if (initialState === "RUNNING") {
+    console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
+    return;
+  }
+  if (initialState === "TERMINATED") {
+    console.error(`  ${cfg.instanceName} is TERMINATED — starting...`);
+    const start = runGcloud(buildGcloudArgs("instances-start", cfg));
+    if (start.status !== 0) {
+      throw new Error(`Failed to start instance ${cfg.instanceName}`);
+    }
+  } else if (initialState === null) {
+    console.error(`  ${cfg.instanceName} not found — creating...`);
+    const create = runGcloud(buildGcloudArgs("instances-create", cfg));
+    if (create.status !== 0) {
+      throw new Error(`Failed to create instance ${cfg.instanceName}`);
+    }
+  } else {
+    console.error(`  ${cfg.instanceName} is ${initialState}; waiting...`);
+  }
+
+  for (let i = 0; i < 60; i++) {
+    if (fetchInstanceState(cfg) === "RUNNING") {
+      console.error(`  ✓ ${cfg.instanceName} is RUNNING`);
+      await waitForIapReady(cfg);
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  throw new Error(`Instance ${cfg.instanceName} did not reach RUNNING within 2 minutes`);
+}
+
+/** GCE reports the instance as RUNNING the moment the boot disk is attached,
+ *  but the IAP control plane has its own catalog that updates a few seconds
+ *  later. The first `gcloud compute ssh --tunnel-through-iap` after a fresh
+ *  create races that catalog and fails with `[4047: 'Failed to lookup
+ *  instance']`. Probe an IAP-tunneled SSH that just runs `true` until it
+ *  succeeds — cheap on the warm path (one ~1s round-trip) and bounded so a
+ *  genuinely unreachable VM fails loud rather than silently. */
+async function waitForIapReady(cfg) {
+  console.error(`  waiting for IAP to register ${cfg.instanceName}...`);
+  // 180s, not 60s: on a fresh instance the IAP catalog + SSH-key (osLogin)
+  // propagation can take well over a minute under fleet load, and each failed
+  // probe burns ~25-30s before gcloud gives up — so a 60s budget fit only ~2
+  // probes and aborted cloud:up before the VM was ever reachable, leaving a
+  // RUNNING-but-unbootstrapped instance.
+  const deadline = Date.now() + 180_000;
+  let attempts = 0;
+  let lastErr = "";
+  while (Date.now() < deadline) {
+    attempts++;
+    const probe = runGcloud(
+      buildGcloudArgs("ssh-probe", cfg, { command: "true" }),
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+    if (probe.status === 0) {
+      console.error(`  ✓ IAP ready (${attempts} ${attempts === 1 ? "probe" : "probes"})`);
+      return;
+    }
+    lastErr = String(probe.stderr || "").trim().split("\n").slice(-1)[0] || "";
+    // Exponential-ish backoff: 2s, 3s, 5s, 8s, then cap at 8s.
+    const delay = Math.min(2000 * Math.pow(1.5, attempts - 1), 8000);
+    await new Promise((r) => setTimeout(r, delay));
+  }
+  throw new Error(
+    `IAP did not become ready for ${cfg.instanceName} within 180s ` +
+      `(${attempts} probes; last error: ${lastErr || "unknown"})`,
+  );
+}
+
+/** Read `process.env[FORWARD_ENV_KEYS_ENV]` (comma-separated key list set by
+ *  the fleet dashboard) and return the subset of `process.env` that should
+ *  ride along into the VM's project-bootstrap shell. Whitelisted to the
+ *  named keys: a fork of the dashboard's launch-form env, never the whole
+ *  laptop env (which would leak PATH / NODE_OPTIONS / unrelated secrets).
+ *  Empty / unset → {} so the standalone `cloud:up` path is unchanged. */
+function resolveSetupForwardEnv(env = process.env) {
+  const list = env[FORWARD_ENV_KEYS_ENV];
+  if (!list) return {};
+  const out = {};
+  for (const raw of String(list).split(",")) {
+    const k = raw.trim();
+    if (!k) continue;
+    const v = env[k];
+    if (v == null || v === "") continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+function sshScriptCommand(scriptBody, scriptArgs = [], envVars = {}) {
+  const b64 = Buffer.from(scriptBody, "utf8").toString("base64");
+  const argsString = scriptArgs.map((a) => `'${String(a).replace(/'/g, "'\\''")}'`).join(" ");
+  // Prefix each env var as `KEY='value'` so they're set for the bash -s
+  // process only — no persistence in the VM's shell history, no /etc/environment
+  // edit. Single-quoted values are safe against shell metacharacters; an
+  // embedded apostrophe in the value would be exotic for these (token,
+  // bool flag), but escape it the same way as scriptArgs for symmetry.
+  const envString = Object.entries(envVars)
+    .filter(([, v]) => v !== undefined && v !== null && v !== "")
+    .map(([k, v]) => `${k}='${String(v).replace(/'/g, "'\\''")}'`)
+    .join(" ");
+  const envPrefix = envString ? `${envString} ` : "";
+  return `echo '${b64}' | base64 -d | ${envPrefix}bash -s -- ${argsString}`.trim();
+}
+
+async function ensureBootstrapped(cfg) {
+  console.error("Checking VM bootstrap state...");
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: "command -v docker >/dev/null && docker image inspect codeyam-editor:local >/dev/null 2>&1",
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (probe.status === 0) {
+    console.error("  ✓ VM already bootstrapped (docker + codeyam-editor:local present)");
+    return;
+  }
+  console.error("  streaming scripts/gcp-bootstrap.sh to VM (this may take ~10 minutes)...");
+  const scriptPath = path.join(rootDir, "scripts", "gcp-bootstrap.sh");
+  const scriptBody = fs.readFileSync(scriptPath, "utf8");
+  // GITHUB_TOKEN is passed through to the bootstrap script so it can clone
+  // a private editor repo (the bootstrap clones $REPO_URL to build the
+  // codeyam-editor:local image). Without this the git clone hits the
+  // "could not read Username for 'https://github.com'" wall whenever the
+  // repo isn't public — codeyam-editor itself today.
+  //
+  // Build the editor image from the EDITOR source (cfg.editorRepo/editorBranch),
+  // decoupled from the client project (cfg.repo/branch) which gets cloned into
+  // /workspace by ensureProjectBootstrapped. --branch matters when testing
+  // wrapper / Dockerfile patches from a feature branch; without it the image
+  // build uses the editor repo's default branch.
+  const bootstrapArgs = editorImageBootstrapArgs(cfg);
+  // CODEYAM_GHCR_TOKEN lets the bootstrap `docker login ghcr.io` and pull the
+  // PRIVATE prebuilt base + branch-binary packages — without it every pull
+  // 403s and the bootstrap silently slow-builds (~14 min) from source.
+  // CODEYAM_GHCR_USER is an optional login-username override (the bootstrap
+  // otherwise derives it from the registry owner). Empty values are dropped by
+  // sshScriptCommand, so the no-registry / local-only path is unchanged.
+  const command = sshScriptCommand(scriptBody, bootstrapArgs, {
+    GITHUB_TOKEN: resolveGithubToken(),
+    CODEYAM_GHCR_TOKEN: resolveGhcrToken(),
+    CODEYAM_GHCR_USER: process.env.CODEYAM_GHCR_USER || "",
+  });
+  const result = runGcloud(
+    buildGcloudArgs("ssh-script", cfg, { command }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error("scripts/gcp-bootstrap.sh failed on the VM");
+  }
+}
+
+async function ensureProjectBootstrapped(cfg) {
+  const repoName = resolveProject(cfg).name;
+  console.error(`Checking project bootstrap state for ${repoName}...`);
+  // Probe both .codeyam/ (created by `editor init`) AND
+  // docker-compose.cloud.yml (written near the end of the script). A previous
+  // run that crashed between init and the compose write would leave the
+  // first marker but not the second; the old probe wrongly considered the
+  // project bootstrapped and the next `cloud:up` then hit
+  // "open docker-compose.cloud.yml: no such file or directory".
+  // The probe is the seam where idempotency lives — make sure it gates on
+  // the LAST artifact the script produces, not the first.
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        `test -d ~/projects/${repoName}/.codeyam ` +
+        `&& test -f ~/projects/${repoName}/docker-compose.cloud.yml`,
+    }),
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  if (probe.status === 0) {
+    console.error(`  ✓ ${repoName} already bootstrapped on VM`);
+    return;
+  }
+  console.error(`  streaming scripts/gcp-project-bootstrap.sh to VM for ${cfg.repo}...`);
+  const scriptPath = path.join(rootDir, "scripts", "gcp-project-bootstrap.sh");
+  const scriptBody = fs.readFileSync(scriptPath, "utf8");
+  const scriptArgs = clientProjectBootstrapArgs(cfg);
+  // Forward the laptop's git author identity so the rendered compose file
+  // carries CY_GIT_USER_{NAME,EMAIL} → the entrypoint writes them to
+  // `git config --global` → plan_claim_refs::create_claim's commit-tree call
+  // succeeds. Empty strings are fine (laptop has no identity, e.g. a CI
+  // runner); the entrypoint warns and proceeds.
+  const laptopGit = resolveLaptopGitIdentity();
+  // Forward the operator's launch-form env keys (DATABASE_URL, etc.) into the
+  // bootstrap shell so the bootstrap-time `npm run setup` sees them on the
+  // first try — without this, Prisma `db:push`/`db:seed` fail for lack of
+  // env and the bootstrap's fail-soft branch leaves the app schema-less until
+  // the post-add `reapplyVmEnv` re-fires setup. See
+  // `improve37-launch-form-env-injected-into-cloud-up-bootstrap-not-just-applied-after`.
+  // Whitelisted by the dashboard via CY_FORWARD_ENV_KEYS — empty on the
+  // standalone `cloud:up` path, so that flow is unchanged.
+  const forwardEnv = resolveSetupForwardEnv();
+  const command = sshScriptCommand(scriptBody, scriptArgs, {
+    GITHUB_TOKEN: resolveGithubToken(),
+    CY_GIT_USER_NAME: laptopGit.name,
+    CY_GIT_USER_EMAIL: laptopGit.email,
+    ...forwardEnv,
+  });
+  const result = runGcloud(
+    buildGcloudArgs("ssh-script", cfg, { command }),
+    { stdio: "inherit" },
+  );
+  if (result.status !== 0) {
+    throw new Error("scripts/gcp-project-bootstrap.sh failed on the VM");
+  }
+}
+
+async function ensureEditorContainerUp(cfg) {
+  const repoName = resolveProject(cfg).name;
+  // -f docker-compose.cloud.yml everywhere: the editor repo's own
+  // docker-compose.yml does `build: .` from source and would shadow the
+  // cloud variant when self-hosting (see gcp-project-bootstrap.sh).
+  const composeCmd = `docker compose -f docker-compose.cloud.yml`;
+  console.error("Checking editor container state...");
+  const probe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} && ${composeCmd} ps --format json 2>/dev/null || true`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (probe.status === 0 && parseEditorComposeState(probe.stdout) === "running") {
+    console.error("  ✓ editor container is already running");
+    return;
+  }
+  console.error("  starting editor container (docker compose up -d)...");
+  const up = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} && ${composeCmd} up -d`,
+    }),
+    { stdio: "inherit" },
+  );
+  if (up.status !== 0) {
+    throw new Error("docker compose up -d failed on the VM");
+  }
+}
+
+/** Read the laptop's git author identity (`user.name`, `user.email`) so
+ *  cloud:up can forward it to the VM's container entrypoint, which writes
+ *  it to `git config --global`. Without identity in the container,
+ *  plan_claim_refs::create_claim's `git commit-tree` fails with "Author
+ *  identity unknown" and plan-claim refs are silently never created — the
+ *  In-Flight panel goes blind to that VM's work. Returns `{ name, email }`
+ *  with empty strings for whichever field is unset locally; the entrypoint
+ *  fails-soft on either-empty, so a CI runner without git config simply
+ *  warns and boots. The two `git config` calls are cheap (single fs read)
+ *  and not memoized so a user can `git config --global user.email …`
+ *  between operations and have it picked up on the next cloud:up. */
+function resolveLaptopGitIdentity(spawnImpl = spawnSync) {
+  const read = (key) => {
+    const r = spawnImpl("git", ["config", "--get", key], { encoding: "utf8" });
+    if (r.status !== 0) return "";
+    return String(r.stdout || "").trim();
+  };
+  return { name: read("user.name"), email: read("user.email") };
+}
+
+/** Look up a GitHub token from local environment, falling back to `gh auth
+ *  token`. Returns empty string if neither is available — callers should
+ *  treat empty as "no auth" and either skip or print a hint. Memoizing
+ *  intentionally not done: the cost of one `gh` subprocess per cloud:up is
+ *  trivial and lets a user `gh auth login` between operations. */
+function resolveGithubToken() {
+  const env = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+  if (env) return env;
+  const ghOut = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
+  if (ghOut.status === 0) {
+    return ghOut.stdout.trim();
+  }
+  return "";
+}
+
+/** A `read:packages`-scoped token the VM bootstrap uses to `docker login
+ *  ghcr.io` and pull the PRIVATE prebuilt cloud-smoke base + branch-binary
+ *  packages. Prefer an explicit CODEYAM_GHCR_TOKEN (the operator's scoped
+ *  fleet secret); fall back to the same GitHub token already used for the
+ *  git clone, which carries read:packages for a classic PAT / `gh auth token`
+ *  in the common fleet setup. Empty string when neither is available — the
+ *  bootstrap then skips login and the private pulls fall back to a source
+ *  build (today's behavior, never worse). Threaded into gcp-bootstrap.sh via
+ *  the env channel in ensureBootstrapped; never passed as an argv. */
+function resolveGhcrToken() {
+  return process.env.CODEYAM_GHCR_TOKEN || resolveGithubToken();
+}
+
+/** Write the laptop's GitHub token into ~/.codeyam-cloud-git-credentials on
+ *  the VM so the cloud compose can mount it into /root/.git-credentials —
+ *  without this, claude / codex / gemini inside the container can clone the
+ *  initial repo (the wrapper does that step out-of-band with a one-shot
+ *  inlined URL) but cannot `git pull` / `git push` afterward. The file is
+ *  chmod 600 and never committed; if the local environment has no token,
+ *  the placeholder file from gcp-project-bootstrap.sh stays in place. */
+async function seedGithubCredentials(cfg) {
+  const token = resolveGithubToken();
+  if (!token) {
+    console.error(
+      "\nNo GITHUB_TOKEN / GH_TOKEN set and `gh auth token` is unavailable —\n" +
+        "claude inside the cloud container will not be able to git pull/push.\n" +
+        "Export GITHUB_TOKEN or run `gh auth login` locally, then `cloud:up` again.\n",
+    );
+    return;
+  }
+  console.error("Writing GitHub token into ~/.codeyam-cloud-git-credentials on the VM...");
+  const credLine = `https://x-access-token:${token}@github.com`;
+  // Quote the token through one shell layer (gcloud ssh --command); the
+  // value is base64'd to keep it out of the shell history.
+  const b64 = Buffer.from(`${credLine}\n`).toString("base64");
+  const remoteCmd =
+    `f=$HOME/.codeyam-cloud-git-credentials && ` +
+    `echo ${b64} | base64 -d > $f && chmod 600 $f && echo OK`;
+  const result = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, { command: remoteCmd }),
+    { stdio: ["ignore", "pipe", "inherit"] },
+  );
+  if (result.status !== 0) {
+    throw new Error("Failed to write ~/.codeyam-cloud-git-credentials on the VM");
+  }
+}
+
+/** Best-effort read of the VM's resolved app dev-server port so cloud:up's
+ *  laptop `-L` forward, readiness probe, and previewOrigin seed all target the
+ *  port the app actually serves on instead of a hardcoded 5173. Cats the VM's
+ *  editor.json and editor.local.json in one SSH round-trip and resolves via
+ *  `resolveConfiguredAppPort`. Any failure (SSH error, missing/corrupt JSON)
+ *  falls back to `VITE_PORT` — the same default `resolved_port()` lands on for
+ *  a portless config, so a 5173/greenfield project sees no behavior change. */
+async function readVmAppPort(cfg) {
+  const repoName = resolveProject(cfg).name;
+  const base = `~/projects/${repoName}/.codeyam`;
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        `cat ${base}/editor.json 2>/dev/null || echo '{}'; ` +
+        `echo '<<<LOCAL>>>'; ` +
+        `cat ${base}/editor.local.json 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  if (read.status !== 0 || typeof read.stdout !== "string") return VITE_PORT;
+  const parse = (s) => {
+    try {
+      const v = JSON.parse(s);
+      return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    } catch {
+      return {};
+    }
+  };
+  const [baseJson = "", localJson = ""] = read.stdout.split("<<<LOCAL>>>");
+  return resolveConfiguredAppPort(parse(baseJson), parse(localJson));
+}
+
+/** Build the shell command that seeds a JSON patch into a host-side
+ *  `editor.local.json` over SSH. The pre-chown matters: the file lives at
+ *  `~/projects/<repo>/.codeyam/editor.local.json` on the VM host, but it is
+ *  bind-mounted into the running container at `/workspace/.codeyam/`. When
+ *  the container writes the file (e.g. provider-auth updates, dashboard
+ *  edits), the write runs as root inside the container, so the host file
+ *  lands `root:root 0600` on the bind-mount. The next `cloud:up` —
+ *  triggered by dashboard Reconfigure — runs as the unprivileged SSH user
+ *  (`jaredcosulich` on fleet) and EACCES'es trying to overwrite it. The
+ *  `sudo chown $USER:$USER ${remotePath} 2>/dev/null || true` flips
+ *  ownership back when the file is root-owned, no-ops when the file
+ *  doesn't exist yet (`|| true` swallows the missing-file error), and
+ *  silently fails on the rare missing-sudo misconfig (so we never make
+ *  things worse than they were). Leaving the file under SSH-user
+ *  ownership permanently also keeps subsequent host-side reads
+ *  (`docker compose` `.env` interpolation, operator scripts) from
+ *  EACCESsing. Sister fix to `buildEnvApplyCommand` in launch-config.js
+ *  (which solves the symmetric `.env` problem with
+ *  `chown --reference=/workspace`). Pure; no I/O. */
+function buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }) {
+  return (
+    `sudo chown $USER:$USER ${remotePath} 2>/dev/null || true && ` +
+    `mkdir -p ~/projects/${repoName}/.codeyam && ` +
+    `echo '${b64}' | base64 -d > ${remotePath}`
+  );
+}
+
+/** Seed a *bootstrap* `previewOrigin` into the VM's `editor.local.json` so the
+ *  Live Preview iframe URL the laptop browser loads is decoupled from the
+ *  in-VM dev-server port. `appPort` is the VM's resolved app port (see
+ *  readVmAppPort); it defaults to `VITE_PORT` for a Vite/greenfield app or any
+ *  unresolvable config. Two topologies:
+ *
+ *  - SSH-tunneled laptop user: the seed is `http://localhost:${appPort}`,
+ *    which the user's `-L ${appPort}:…` tunnel (openTunnel) forwards into the
+ *    VM. Works for a Vite 5173, a Next.js 3000, anything.
+ *  - Operator public trycloudflare URL: a localhost origin points at the laptop
+ *    itself, not the VM, so the iframe sticks on "Reconnecting Live Preview"
+ *    forever. The fix is a sibling `<N>-preview` cloudflared tunnel; once the
+ *    operator's cloudflared-monitor publishes its URL, that public origin is
+ *    seeded instead (see resolveSeedPreviewOrigin).
+ *
+ *  This is the bootstrap value only — the cloudflared-monitor owns the
+ *  steady-state value and rewrites it on every respawn (matching our
+ *  `_managedPreviewOrigin` sentinel). We stamp the sentinel here too so the
+ *  monitor doesn't mistake the cloud:up seed for a user pin. The
+ *  skip-on-already-set guard stays: a non-empty previewOrigin (whether a user
+ *  pin or a monitor write) is left untouched on every `cloud:up`. */
+async function seedPreviewOrigin(cfg, appPort = VITE_PORT) {
+  const repoName = resolveProject(cfg).name;
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  const seed = resolveSeedPreviewOrigin(
+    cfg.instanceName,
+    readCloudflaredUrls(),
+    appPort,
+  );
+
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cat ${remotePath} 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  let current = {};
+  if (read.status === 0) {
+    try {
+      const parsed = JSON.parse(read.stdout);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch {
+      // Unparseable remote content is treated as `{}` — overwriting a
+      // corrupt local override file with a known-good one is the safer
+      // move than refusing to seed at all.
+    }
+  }
+  if (typeof current.previewOrigin === "string" && current.previewOrigin.length > 0) {
+    return;
+  }
+
+  console.error(`Seeding previewOrigin=${seed.previewOrigin} into ${remotePath}...`);
+  const merged = deepMergeJson(current, seed);
+  const mergedJson = JSON.stringify(merged, null, 2);
+  const b64 = Buffer.from(mergedJson, "utf8").toString("base64");
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }),
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
+async function seedAgentApiKey(cfg) {
+  const patch = buildEditorLocalEnvPatch(process.env, cfg.agent);
+  if (!patch) {
+    console.error(
+      `\nNo ${agentEnvVarName(cfg.agent)} set locally — skipping agent auth seed.\n` +
+        `Authenticate ${cfg.agent} later with:\n` +
+        `  gcloud compute ssh ${cfg.instanceName} --project ${cfg.project} --zone ${cfg.zone} ` +
+        `--tunnel-through-iap -- ${cfg.agent} auth login\n`,
+    );
+    return;
+  }
+  const repoName = resolveProject(cfg).name;
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  console.error(`Seeding ${agentEnvVarName(cfg.agent)} into ${remotePath}...`);
+
+  const read = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cat ${remotePath} 2>/dev/null || echo '{}'`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  let current = {};
+  if (read.status === 0) {
+    try {
+      const parsed = JSON.parse(read.stdout);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch {
+      // Treat unparseable remote content as `{}` — overwriting a corrupt
+      // local override file with a known-good one is the safer move than
+      // refusing to seed at all.
+    }
+  }
+  const merged = deepMergeJson(current, patch);
+  const mergedJson = JSON.stringify(merged, null, 2);
+  const b64 = Buffer.from(mergedJson, "utf8").toString("base64");
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: buildEditorLocalSeedWriteCommand({ repoName, remotePath, b64 }),
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
+async function openTunnel(cfg, appPort = VITE_PORT) {
+  console.error(`Opening IAP tunnel to ${cfg.instanceName}...`);
+  const child = spawn("gcloud", buildGcloudArgs("ssh-tunnel", cfg, { appPort }), { stdio: "inherit" });
+  const readyEditor = await waitForPort(EDITOR_PORT, 30000, 500);
+  const readyApp = await waitForPort(appPort, 30000, 500);
+  if (!readyEditor || !readyApp) {
+    console.error(
+      `Warning: tunnel ports not reachable on localhost (${EDITOR_PORT}=${readyEditor}, ${appPort}=${readyApp}).`,
+    );
+  }
+  console.error(`  Editor UI:    http://localhost:${EDITOR_PORT}`);
+  console.error(`  Live Preview: http://localhost:${appPort}`);
+  console.error("  (Ctrl+C to tear down the tunnel)");
+  return child;
+}
+
+function attachKeepAliveAndTeardown(child) {
+  const keepAlive = setInterval(() => {}, 60_000);
+  process.on("SIGINT", () => {
+    clearInterval(keepAlive);
+    killChildProcess(child);
+    process.exit(0);
+  });
+}
+
+function promptForInstanceName(expected) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stderr,
+    });
+    rl.question(
+      `Type the instance name '${expected}' to confirm destroy: `,
+      (ans) => {
+        rl.close();
+        resolve(ans.trim() === expected);
+      },
+    );
+  });
+}
+
+// =============================================================================
+// Subcommand handlers
+// =============================================================================
+
+async function cmdUp(args) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const cfg = loadOrInitCloudConfig(rootDir, flags);
+  // Fail loud BEFORE creating a GCE instance if an unprovisionable editor
+  // variant was requested — otherwise we'd spin up a VM, build a dev image,
+  // and silently ignore the operator's staging/production intent.
+  assertVariantProvisionable(resolveEditorConfig(cfg).editorVariant);
+
+  await ensureFirewallRule(cfg);
+  await ensureInstance(cfg);
+  await ensureBootstrapped(cfg);
+  await ensureProjectBootstrapped(cfg);
+  // Resolve the app's dev-server port from the VM's now-bootstrapped config so
+  // the previewOrigin seed and the laptop tunnel both target it (not 5173).
+  const appPort = await readVmAppPort(cfg);
+  await seedPreviewOrigin(cfg, appPort);
+  // Write the GitHub token BEFORE compose up so the credentials file exists
+  // when the bind-mount happens — bind-mounting a missing file would silently
+  // create a directory instead and the agent's first `git pull` would fail.
+  await seedGithubCredentials(cfg);
+  await ensureEditorContainerUp(cfg);
+  await seedAgentApiKey(cfg);
+  // Roster the VM into the fleet dashboard NOW that it's provisioned and the
+  // editor container is up. Runs BEFORE the --no-tunnel early-return so the
+  // dashboard's own `cloud:up --no-tunnel` Add path also rosters (idempotent
+  // with the dashboard's onSuccess roster — a double-add is a harmless no-op).
+  rosterProvisionedVm(cfg.instanceName);
+  // --no-tunnel: provisioning-only mode (the fleet dashboard opens its own
+  // per-VM tunnel). Skipping openTunnel lets cloud:up EXIT cleanly instead of
+  // hanging on a tunnel, and — critically for parallel multi-add — avoids N
+  // invocations all contending on the fixed local ports 14199/5173.
+  if (cfg.noTunnel) {
+    console.error("--no-tunnel: provisioning complete; skipping local tunnel + browser open.");
+    return;
+  }
+  const tunnelChild = await openTunnel(cfg, appPort);
+  open(`http://localhost:${EDITOR_PORT}`);
+  attachKeepAliveAndTeardown(tunnelChild);
+}
+
+async function cmdTunnel(args) {
+  ensureGcloud();
+  const flags = parseFlags(args);
+  const existing = loadCloudConfig(rootDir);
+  if (!existing) {
+    throw new Error(
+      "No .codeyam/cloud.json found. Run `npm run cloud:up -- --repo <url>` first.",
+    );
+  }
+  const cfg = { ...existing, ...flags };
+
+  const state = fetchInstanceState(cfg);
+  if (state === null) {
+    throw new Error(
+      `Instance ${cfg.instanceName} not found in project ${cfg.project} / zone ${cfg.zone}. ` +
+        "Has it been deleted? Try `npm run cloud:up`.",
+    );
+  }
+  if (state !== "RUNNING") {
+    throw new Error(
+      `Instance ${cfg.instanceName} is ${state}; run \`npm run cloud:up\` to start it.`,
+    );
+  }
+
+  // Forward the laptop preview `-L` to the VM's resolved app port, not 5173.
+  const appPort = await readVmAppPort(cfg);
+  const tunnelChild = await openTunnel(cfg, appPort);
+  open(`http://localhost:${EDITOR_PORT}`);
+  attachKeepAliveAndTeardown(tunnelChild);
+}
+
+async function cmdStop(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Nothing to stop.");
+  }
+  console.error(`Stopping ${cfg.instanceName}...`);
+  const result = runGcloud(buildGcloudArgs("instances-stop", cfg));
+  if (result.status !== 0) {
+    throw new Error(`Failed to stop instance ${cfg.instanceName}`);
+  }
+  console.error(
+    `\n  ✓ ${cfg.instanceName} is stopped.\n` +
+      "  Persistent-disk billing continues (~$10/month for 100 GB pd-balanced).\n" +
+      "  Resume with `npm run cloud:up`.\n",
+  );
+}
+
+async function cmdDestroy(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    throw new Error("No .codeyam/cloud.json found. Nothing to destroy.");
+  }
+
+  const confirmed = await promptForInstanceName(cfg.instanceName);
+  if (!confirmed) {
+    console.error("Aborted.");
+    return;
+  }
+
+  console.error(`Deleting instance ${cfg.instanceName}...`);
+  const del = runGcloud(buildGcloudArgs("instances-delete", cfg));
+  if (del.status !== 0) {
+    throw new Error(`Failed to delete instance ${cfg.instanceName}`);
+  }
+
+  const list = runGcloud(buildGcloudArgs("instances-list-tagged", cfg), {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const others = String(list.stdout || "").trim().split("\n").filter(Boolean);
+  if (others.length === 0) {
+    console.error(`No other ${INSTANCE_TAG}-tagged instances remain — deleting firewall rule...`);
+    const fwDel = runGcloud(buildGcloudArgs("firewall-delete", cfg));
+    if (fwDel.status !== 0) {
+      console.error(`  Warning: failed to delete firewall rule ${FIREWALL_RULE_NAME}.`);
+    }
+  } else {
+    console.error(
+      `Leaving ${FIREWALL_RULE_NAME} in place (${others.length} other ${INSTANCE_TAG}-tagged instance(s) still use it).`,
+    );
+  }
+
+  try {
+    fs.unlinkSync(cloudConfigPath(rootDir));
+    console.error("Deleted .codeyam/cloud.json");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+}
+
+async function cmdStatus(args) {
+  ensureGcloud();
+  parseFlags(args);
+  const cfg = loadCloudConfig(rootDir);
+  if (!cfg) {
+    console.error("No .codeyam/cloud.json found. Run `npm run cloud:up` first.");
+    return;
+  }
+
+  const vmState = fetchInstanceState(cfg) || "NOT_FOUND";
+  console.error(`VM: ${cfg.instanceName} (${cfg.zone}) — ${vmState}`);
+
+  if (vmState !== "RUNNING") {
+    console.error("  (image / container / tunnel checks skipped — VM is not RUNNING)");
+    return;
+  }
+
+  const imgProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command:
+        "docker image inspect codeyam-editor:local >/dev/null 2>&1 && echo built || echo missing",
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const imgStatus = String(imgProbe.stdout || "").trim() || "?";
+  console.error(`  image:            ${imgStatus}`);
+
+  const repoName = resolveProject(cfg).name;
+  const containerProbe = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `cd ~/projects/${repoName} 2>/dev/null && docker compose -f docker-compose.cloud.yml ps --format json 2>/dev/null || echo`,
+    }),
+    { stdio: ["ignore", "pipe", "ignore"] },
+  );
+  const containerStatus = parseEditorComposeState(containerProbe.stdout) || "missing";
+  console.error(`  editor container: ${containerStatus}`);
+
+  const appPort = await readVmAppPort(cfg);
+  const pEditor = await isPortInUse(EDITOR_PORT);
+  const pApp = await isPortInUse(appPort);
+  console.error(
+    `  tunnel:           ${EDITOR_PORT} ${pEditor ? "✓" : "✗"}   ${appPort} ${pApp ? "✓" : "✗"}`,
+  );
+}
+
+const HANDLERS = {
+  up: cmdUp,
+  tunnel: cmdTunnel,
+  stop: cmdStop,
+  destroy: cmdDestroy,
+  status: cmdStatus,
+};
+
+async function cloudMain() {
+  const subcmd = process.argv[2];
+  const args = process.argv.slice(3);
+  if (!subcmd || !Object.prototype.hasOwnProperty.call(HANDLERS, subcmd)) {
+    console.error(
+      `Usage: npm run cloud:<${Object.keys(HANDLERS).join("|")}> [-- flags]`,
+    );
+    process.exit(2);
+  }
+  try {
+    await HANDLERS[subcmd](args);
+  } catch (e) {
+    console.error(`Error: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  // pure helpers
+  agentEnvVarName,
+  AGENT_ENV_VARS,
+  KNOWN_FLAGS,
+  FIREWALL_RULE_NAME,
+  INSTANCE_TAG,
+  EDITOR_PORT,
+  VITE_PORT,
+  parseFlags,
+  repoBasename,
+  deriveInstanceName,
+  defaultInstanceNameFor,
+  CANONICAL_EDITOR_REPO,
+  EDITOR_VARIANTS,
+  MANAGED_PREVIEW_ORIGIN,
+  SAME_ORIGIN_PREVIEW_PATH,
+  sameRepo,
+  resolveFleetVmNumber,
+  rosterProvisionedVm,
+  resolveConfiguredAppPort,
+  resolveSeedPreviewOrigin,
+  resolveEditorConfig,
+  validateEditorVariant,
+  assertVariantProvisionable,
+  editorImageBootstrapArgs,
+  reconcileProjectExclusivity,
+  resolveGhcrToken,
+  resolveProject,
+  clientProjectBootstrapArgs,
+  cloudConfigPath,
+  loadCloudConfig,
+  saveCloudConfig,
+  buildEditorLocalEnvPatch,
+  buildEditorLocalSeedWriteCommand,
+  buildGcloudArgs,
+  sshScriptCommand,
+  resolveSetupForwardEnv,
+  FORWARD_ENV_KEYS_ENV,
+  parseEditorComposeState,
+  fetchInstanceState,
+  // side-effecting handlers
+  cmdUp,
+  cmdTunnel,
+  cmdStop,
+  cmdDestroy,
+  cmdStatus,
+  cloudMain,
+  seedGithubCredentials,
+  readVmAppPort,
+  resolveLaptopGitIdentity,
+};
+
+if (require.main === module) {
+  cloudMain();
+}