@codeyam-editor/codeyam-editor 0.1.0-staging.0f231be

package/npm/cloud.js

@@ -0,0 +1,966 @@
+#!/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");
+
+// =============================================================================
+// 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"];
+
+const FIREWALL_RULE_NAME = "codeyam-editor-iap-ssh";
+const INSTANCE_TAG = "codeyam-editor";
+const EDITOR_PORT = 14199;
+const VITE_PORT = 5173;
+
+/** 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 value = argv[i + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new Error(`${arg} requires a value`);
+    }
+    const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    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;
+}
+
+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":
+      return [
+        "compute", "ssh", instanceName,
+        "--project", project, "--zone", zone,
+        "--tunnel-through-iap",
+        "--",
+        "-L", `${EDITOR_PORT}:127.0.0.1:${EDITOR_PORT}`,
+        "-L", `${VITE_PORT}:127.0.0.1:${VITE_PORT}`,
+        "-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);
+  if (existing) {
+    const merged = { ...existing, ...flags };
+    if (JSON.stringify(merged) !== JSON.stringify(existing)) {
+      saveCloudConfig(projectDir, merged);
+    }
+    return merged;
+  }
+
+  const cfg = { ...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) {
+    throw new Error(
+      "--repo <url> 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 || deriveInstanceName(cfg.repo);
+  saveCloudConfig(projectDir, 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}...`);
+  const deadline = Date.now() + 60_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 60s ` +
+      `(${attempts} probes; last error: ${lastErr || "unknown"})`,
+  );
+}
+
+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.
+  //
+  // --branch is mandatory when the user is testing wrapper / Dockerfile
+  // patches from a feature branch: without it, the bootstrap clones the
+  // repo's default branch and the image build uses a stale Dockerfile,
+  // even though the user invoked cloud:up with --branch.
+  const bootstrapArgs = ["--agent", cfg.agent, "--repo", cfg.repo];
+  if (cfg.branch) {
+    bootstrapArgs.push("--branch", cfg.branch);
+  }
+  const command = sshScriptCommand(scriptBody, bootstrapArgs, {
+    GITHUB_TOKEN: resolveGithubToken(),
+  });
+  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 = repoBasename(cfg.repo);
+  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 = [cfg.repo];
+  if (cfg.branch) {
+    scriptArgs.push("--branch", cfg.branch);
+  }
+  const command = sshScriptCommand(scriptBody, scriptArgs, {
+    GITHUB_TOKEN: resolveGithubToken(),
+  });
+  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 = repoBasename(cfg.repo);
+  // -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");
+  }
+}
+
+/** 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 "";
+}
+
+/** 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");
+  }
+}
+
+/** Write a default `previewOrigin` into the VM's `editor.local.json` so the
+ *  Live Preview iframe URL the laptop browser loads is whatever the SSH
+ *  tunnel exposes, decoupled from the in-VM dev-server port. Without this,
+ *  the iframe falls back to `http://localhost:${apps[0].port}` — fine when
+ *  the user happens to have a same-port tunnel (today's `VITE_PORT=5173`),
+ *  but broken the moment they tunnel a different local port. Skips when
+ *  the user has already set `previewOrigin` themselves so per-VM overrides
+ *  aren't clobbered on every `cloud:up`. */
+async function seedPreviewOrigin(cfg) {
+  const repoName = repoBasename(cfg.repo);
+  const remotePath = `~/projects/${repoName}/.codeyam/editor.local.json`;
+  const desiredOrigin = `http://localhost:${VITE_PORT}`;
+
+  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=${desiredOrigin} into ${remotePath}...`);
+  const merged = deepMergeJson(current, { previewOrigin: desiredOrigin });
+  const mergedJson = JSON.stringify(merged, null, 2);
+  const b64 = Buffer.from(mergedJson, "utf8").toString("base64");
+  const write = runGcloud(
+    buildGcloudArgs("ssh-probe", cfg, {
+      command: `mkdir -p ~/projects/${repoName}/.codeyam && echo '${b64}' | base64 -d > ${remotePath}`,
+    }),
+    { 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 = repoBasename(cfg.repo);
+  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: `mkdir -p ~/projects/${repoName}/.codeyam && echo '${b64}' | base64 -d > ${remotePath}`,
+    }),
+    { stdio: ["ignore", "inherit", "inherit"] },
+  );
+  if (write.status !== 0) {
+    throw new Error(`Failed to write ${remotePath} on VM`);
+  }
+}
+
+async function openTunnel(cfg) {
+  console.error(`Opening IAP tunnel to ${cfg.instanceName}...`);
+  const child = spawn("gcloud", buildGcloudArgs("ssh-tunnel", cfg), { stdio: "inherit" });
+  const ready14199 = await waitForPort(EDITOR_PORT, 30000, 500);
+  const ready5173 = await waitForPort(VITE_PORT, 30000, 500);
+  if (!ready14199 || !ready5173) {
+    console.error(
+      `Warning: tunnel ports not reachable on localhost (${EDITOR_PORT}=${ready14199}, ${VITE_PORT}=${ready5173}).`,
+    );
+  }
+  console.error(`  Editor UI:    http://localhost:${EDITOR_PORT}`);
+  console.error(`  Live Preview: http://localhost:${VITE_PORT}`);
+  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);
+
+  await ensureFirewallRule(cfg);
+  await ensureInstance(cfg);
+  await ensureBootstrapped(cfg);
+  await ensureProjectBootstrapped(cfg);
+  await seedPreviewOrigin(cfg);
+  // 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);
+  const tunnelChild = await openTunnel(cfg);
+  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.`,
+    );
+  }
+
+  const tunnelChild = await openTunnel(cfg);
+  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 = repoBasename(cfg.repo);
+  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 p14199 = await isPortInUse(EDITOR_PORT);
+  const p5173 = await isPortInUse(VITE_PORT);
+  console.error(
+    `  tunnel:           ${EDITOR_PORT} ${p14199 ? "✓" : "✗"}   ${VITE_PORT} ${p5173 ? "✓" : "✗"}`,
+  );
+}
+
+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,
+  cloudConfigPath,
+  loadCloudConfig,
+  saveCloudConfig,
+  buildEditorLocalEnvPatch,
+  buildGcloudArgs,
+  sshScriptCommand,
+  parseEditorComposeState,
+  fetchInstanceState,
+  // side-effecting handlers
+  cmdUp,
+  cmdTunnel,
+  cmdStop,
+  cmdDestroy,
+  cmdStatus,
+  cloudMain,
+  seedGithubCredentials,
+};
+
+if (require.main === module) {
+  cloudMain();
+}