@codeyam-editor/codeyam-editor 0.1.3 → 0.1.5

package/npm/launch-config.js

@@ -8,7 +8,16 @@
 // runs on a VM; the history is the cache that makes the last choice the default
 // and past launches one click to re-run.
 
-const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename } = require("./cloud");
+const { CANONICAL_EDITOR_REPO, EDITOR_VARIANTS, repoBasename, AGENT_ENV_VARS } = require("./cloud");
+const { normalizeVmSlug } = require("./vm-urls");
+const { normalizeAccessList } = require("./fleet-vm-access");
+
+/** The build agents a VM's editor terminal can run, as the keys of cloud.js's
+ *  AGENT_ENV_VARS. Deriving the selectable set from that map keeps it a single
+ *  source of truth with the agent→API-key-env-var mapping (cloud.js) and the
+ *  gcp-bootstrap CLI installer, so adding an agent is still a one-line change in
+ *  AGENT_ENV_VARS rather than a list to keep in sync here. */
+const AGENTS = Object.freeze(Object.keys(AGENT_ENV_VARS));
 
 const EMPTY_CONFIG = Object.freeze({
   clientRepo: "",
@@ -18,20 +27,52 @@ const EMPTY_CONFIG = Object.freeze({
   newProjectName: "",
   editorVariant: "dev",
   editorBranch: "",
+  // Build agent provider the VM's editor terminal runs (claude | codex | gemini).
+  // Defaults to claude; cloudUpArgs forwards it as cloud:up's --agent flag.
+  agent: "claude",
+  // Optional human-readable hostname slug for a SINGLE VM. When set, cloudUpArgs
+  // forwards it as cloud:up's --vm-slug flag so the VM's public URLs become
+  // `<slug>.editor.<domain>`. Empty ⇒ the numeric vm-<N> scheme (unchanged).
+  vmSlug: "",
+  // Optional per-VM IAP access whitelist for a SINGLE VM: a comma-separated list
+  // of principals (user:/group:/domain:, a bare email defaults to user:) granted
+  // resource-level access to this VM's surfaces. cloudUpArgs forwards it as
+  // cloud:up's --vm-access flag. Empty ⇒ only the owner's project-wide grant.
+  vmAccess: "",
 });
 
+/** Collapse a free-text access list (the add-form textarea, where the operator
+ *  may separate principals by newlines or commas) into the canonical
+ *  comma-separated string cloud:up's --vm-access expects. Pure + never throws —
+ *  shape validation is validateLaunchConfig's job. */
+function normalizeAccessText(raw) {
+  if (typeof raw !== "string") return "";
+  return raw
+    .split(/[\n,]+/)
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .join(",");
+}
+
 /** Coerce a raw form/query object into the canonical launch-config shape: trim
  *  strings, default the variant to a known value. Never throws — validation is
  *  a separate, explicit step. */
 function normalizeLaunchConfig(input = {}) {
   const str = (v) => (typeof v === "string" ? v.trim() : "");
   const editorVariant = EDITOR_VARIANTS.includes(input.editorVariant) ? input.editorVariant : "dev";
+  // Coerce an unknown/absent agent to the default rather than rejecting — the
+  // form's agent selector only ever submits a known value, so an out-of-set
+  // agent is a stale query param, not an error.
+  const agent = AGENTS.includes(input.agent) ? input.agent : "claude";
   return {
     clientRepo: str(input.clientRepo),
     clientBranch: str(input.clientBranch),
     newProjectName: str(input.newProjectName),
     editorVariant,
     editorBranch: str(input.editorBranch),
+    agent,
+    vmSlug: str(input.vmSlug),
+    vmAccess: normalizeAccessText(input.vmAccess),
   };
 }
 
@@ -55,6 +96,26 @@ function validateLaunchConfig(cfg) {
   if (!EDITOR_VARIANTS.includes(cfg.editorVariant)) {
     return { ok: false, msg: `unknown editor variant: ${cfg.editorVariant}` };
   }
+  // A custom slug, when supplied, must be a single DNS label (same rule cloud:up
+  // enforces) — surface a friendly reason here rather than letting the spawned
+  // job fail loud later. Empty ⇒ numeric vm-<N>, no check.
+  if (cfg.vmSlug) {
+    try {
+      normalizeVmSlug(cfg.vmSlug);
+    } catch (e) {
+      return { ok: false, msg: e.message };
+    }
+  }
+  // A per-VM access whitelist, when supplied, must be a list of valid principals
+  // (same rule cloud:up enforces) — surface a friendly reason here rather than
+  // letting the spawned job fail loud later. Empty ⇒ no check.
+  if (cfg.vmAccess) {
+    try {
+      normalizeAccessList(cfg.vmAccess);
+    } catch (e) {
+      return { ok: false, msg: e.message };
+    }
+  }
   return { ok: true };
 }
 
@@ -108,18 +169,52 @@ function variantImageTag(variant) {
   return null; // dev / unknown — no packaged image
 }
 
+/** Return true if the value matches a known test-fixture placeholder (e.g., "gcp-proj"),
+ *  is null, empty, or whitespace, signaling that it is not a valid GCP project name.
+ *  Documented as the home for future fixture sentinels. Pure; no I/O. */
+function isPlaceholderProject(value) {
+  if (!value) return true;
+  if (typeof value !== "string") return true;
+  const trimmed = value.trim();
+  if (trimmed === "") return true;
+  if (trimmed.toLowerCase() === "gcp-proj") return true;
+  return false;
+}
+
 /** Build the `cloud:up` flag array for a launch config + instance name. The
  *  editor source is the canonical codeyam-editor repo (dev variant builds the
  *  image from editorBranch); the client repo/branch is what lands in
- *  /workspace. Decoupled exactly as cloud.js consumes them. */
-function cloudUpArgs(cfg, instanceName, agent = "claude") {
+ *  /workspace. The build agent rides on `cfg.agent` (normalizeLaunchConfig
+ *  guarantees a known value, defaulting to claude), so a single config object
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them. */
+function cloudUpArgs(cfg, instanceName, project) {
   const args = ["--instance-name", instanceName];
+  // Pass the authoritative GCP project (the dashboard's resolved PROJECT)
+  // explicitly so cloud:up never relies on the spawning shell's ambient
+  // `gcloud config get-value project`. Critically, a `--project` flag OVERRIDES
+  // a persisted .codeyam/cloud.json `project` (cloud.js merges
+  // `{ ...existing, ...flags }`), which a bare cloud:up reuses verbatim with no
+  // gcloud fallback — the sticky-wrong-project failure mode where a stale
+  // placeholder in cloud.json (validated via isPlaceholderProject) wedges every
+  // re-provision with a firewall-create PERMISSION_DENIED. Omitted when unset to
+  // preserve the pre-existing arg shape (cloud.js then falls back to the gcloud
+  // default, as before).
+  if (project) args.push("--project", project);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
-  args.push("--agent", agent, "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
+  args.push("--agent", cfg.agent || "claude", "--editor-repo", CANONICAL_EDITOR_REPO, "--editor-variant", cfg.editorVariant);
   if (!cfg.newProjectName && cfg.clientBranch) args.push("--branch", cfg.clientBranch);
   if (cfg.editorBranch) args.push("--editor-branch", cfg.editorBranch);
+  // Forward an optional custom hostname slug. Only single-VM Adds carry one (the
+  // dashboard strips it for batch count > 1 — N VMs can't share one hostname), so
+  // cloudUpArgs simply emits it when present and trusts the caller's batch guard.
+  if (cfg.vmSlug) args.push("--vm-slug", cfg.vmSlug);
+  // Forward an optional per-VM access whitelist. Like the slug, only single-VM
+  // Adds carry one (the dashboard strips it for batch count > 1 — the same guard
+  // actionAdd applies to vmSlug), so cloudUpArgs emits it when present and trusts
+  // the caller's batch guard.
+  if (cfg.vmAccess) args.push("--vm-access", cfg.vmAccess);
   // The dashboard opens its own per-VM tunnel, so cloud:up must NOT open one:
   // it lets cloud:up exit cleanly and avoids parallel batches colliding on the
   // fixed local ports 14199/5173 (the cause of multi-add "false failures").
@@ -237,6 +332,40 @@ function distinctConfigs(history, limit = 12) {
   return out;
 }
 
+/** Display-side companion to `distinctConfigs`: derive the two label strings the
+ *  "recent launches" picker renders for one config, so two configs that differ
+ *  only by build agent (or greenfield project name) look different instead of
+ *  collapsing to identical rows. `distinctConfigs` de-dups on the FULL config, so
+ *  the rows are genuinely distinct launches — the old inline label just never
+ *  surfaced the distinguishing fields (agent, greenfield name).
+ *
+ *  Returns { primary, secondary }:
+ *   - primary:   greenfield (`!clientRepo && newProjectName`) → `new: <name>` so
+ *                two different greenfield projects no longer both read `(none)`;
+ *                else `repoBasename(clientRepo)` + (`@<branch>` when set); else
+ *                `(none)` when there's neither a repo nor a project name.
+ *   - secondary: `editor <variant>` + (`@<editorBranch>` when set) + ` · <agent>`.
+ *
+ *  Normalizes through EMPTY_CONFIG so a pre-`agent` history entry still renders
+ *  `· claude`. Reuses `repoBasename` (cloud.js) so server/browser basename
+ *  semantics stay single-sourced. Pure; no I/O. */
+function recentLaunchDisplay(config) {
+  const cfg = { ...EMPTY_CONFIG, ...(config || {}) };
+  let primary;
+  if (!cfg.clientRepo && cfg.newProjectName) {
+    primary = `new: ${cfg.newProjectName}`;
+  } else if (cfg.clientRepo) {
+    primary = repoBasename(cfg.clientRepo) + (cfg.clientBranch ? `@${cfg.clientBranch}` : "");
+  } else {
+    primary = "(none)";
+  }
+  const secondary =
+    `editor ${cfg.editorVariant || "dev"}` +
+    (cfg.editorBranch ? `@${cfg.editorBranch}` : "") +
+    ` · ${cfg.agent || "claude"}`;
+  return { primary, secondary };
+}
+
 /** The default config to pre-fill the launch form: the most recent launch's
  *  config, or an empty config when there's no history. */
 function defaultConfig(history) {
@@ -252,6 +381,28 @@ function configForVm(history, n) {
   return h && h.config ? { ...EMPTY_CONFIG, ...h.config } : null;
 }
 
+/** The most-recent launch timestamp for VM `n`, or null when it has no recorded
+ *  launch. The history is newest-first (pushHistory unshifts), so the FIRST entry
+ *  for the VM is its latest launch — the same lookup shape configForVm uses.
+ *  Powers the editor-starting grace window (server.js's deriveStatus): "was this
+ *  unreachable VM launched recently enough to still be starting up?" Pure. */
+function latestLaunchTs(history, n) {
+  const h = (Array.isArray(history) ? history : []).find((e) => e && e.vm === n);
+  return h && typeof h.ts === "string" ? h.ts : null;
+}
+
+/** True when ISO launch timestamp `ts` is within `graceMs` of `nowMs` — the
+ *  editor-starting grace window. A null/unparseable `ts` (no launch on record) is
+ *  never "recent", so a VM with no history never reads as starting. Half-open
+ *  window: exactly at the boundary (`nowMs - ts === graceMs`) is NOT recent, so
+ *  the calm-blue window has a crisp, testable end. Pure; caller owns `nowMs`. */
+function recentlyLaunchedWithin(ts, nowMs, graceMs) {
+  if (typeof ts !== "string") return false;
+  const t = Date.parse(ts);
+  if (Number.isNaN(t)) return false;
+  return nowMs - t < graceMs;
+}
+
 /** Resolve the card's display identity, preferring LIVE truth (the editor's
  *  `/api/session-info` `clientProject` + `editorIdentity`) over STALE launch
  *  history. This is the fix for fragility #33's lying label: a CLI branch
@@ -321,6 +472,31 @@ function stickyClientProject(prev, info) {
   return prev || null;
 }
 
+/** Resolve a VM's app dev-server port stickily: prefer the freshly-polled
+ *  numeric port, else retain the last-known-good `prevAppPort`, so a transient
+ *  null poll (timeout / partial probe) never blanks a port the VM has already
+ *  reported. Mirrors `stickyClientProject` — a populated `prev` survives a
+ *  null/absent fresh poll, a genuinely-changed fresh poll always wins
+ *  (stickiness must NOT pin a stale port: a real 3000→4321 move is honored),
+ *  and `null` results ONLY when neither a polled nor a previous port exists —
+ *  the true first-provision case, where the caller applies its 5173 bootstrap
+ *  fallback.
+ *
+ *  Without this, `appPort` was `(info && info.appPort) || null`, so one
+ *  timed-out poll blanked the resolved port; the tunnel-open fallback then
+ *  re-seeded the hardcoded 5173 Vite default and the next poll saw a 5173→3000
+ *  drift and re-wired — a churn loop that never converged. Pure; no I/O.
+ *
+ *  @param prevAppPort  the previous `state.vms[n].appPort` (null/undefined ok)
+ *  @param info         the fresh poll result object (null when the probe failed)
+ *  @returns the app port to store: fresh numeric port when present, else the
+ *           last-known-good `prevAppPort`, else null. */
+function stickyAppPort(prevAppPort, info) {
+  const fresh = info && info.appPort;
+  if (typeof fresh === 'number' && !Number.isNaN(fresh)) return fresh;
+  return typeof prevAppPort === 'number' && !Number.isNaN(prevAppPort) ? prevAppPort : null;
+}
+
 /** Classify a VM's project KIND as `"self-host"` vs `"guest"` from the live
  *  identity reported in `/api/session-info` (`clientProject.repo`), with
  *  launch-history `clientRepo` as a fallback when live is absent. A guest is
@@ -479,6 +655,21 @@ function resolveCredsSource({ reachableDonors = [], claudeCredsSrc = "", githubT
   return { mode: "none", donor: null };
 }
 
+/** True when the resolved creds `mode` (see `resolveCredsSource`) carries a real
+ *  Claude-auth seed source, so the add path can seed it automatically and must
+ *  NOT raise the `claude-auth-not-seeded` setup step:
+ *    - "donor"      — copies the donor's `.credentials.json` + `.claude.json`.
+ *    - "host-stash" — pushes the operator's CLAUDE_CREDS_SRC `.credentials.json`.
+ *  The token-only and none modes carry NO Claude credentials — a GITHUB_TOKEN
+ *  seeds *git* auth at boot but not Claude, so those genuinely have nothing to
+ *  seed Claude from and the add path raises `claude-auth-not-seeded` (rendered
+ *  as the calm Plan-1 `auth` setup step with the one-click Login). Branching on
+ *  this instead of unconditionally landing degraded is what keeps the reason from
+ *  appearing when a donor/stash WAS available. Pure; no I/O. */
+function claudeAuthSeeded(mode) {
+  return mode === "donor" || mode === "host-stash";
+}
+
 // Single-quote a string for safe inclusion in a remote shell command. Mirrors
 // the server.js helper so callers don't have to thread one through.
 function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
@@ -591,7 +782,111 @@ function buildEnvApplyCommand({ gcloud, instance, zone, envFile, container, edit
   return `base64 < ${_shq(envFile)} | ${gcloud} compute ssh ${instance} --tunnel-through-iap --zone=${zone} --command=${_shq(sink)}`;
 }
 
+/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
+ *  EDITOR reachability forward (`editorPort` → VM:14199) as its OWN ssh process,
+ *  logging to `/tmp/ssh-tunnel-vm-<n>.log`. The editor forward is the dashboard's
+ *  reachability signal — the probe to `PORT_BASE+N` connects through it — so it
+ *  must have a lifetime INDEPENDENT of the preview forward (whose port legitimately
+ *  changes as the app's dev server is resolved). Splitting the two forwards into
+ *  separate ssh processes is what makes a preview re-wire non-disruptive: a
+ *  preview-port change restarts only the preview tunnel and never blips :14199, so
+ *  the reachability probe can't flip the VM to a false "unreachable" (the
+ *  VM-1/2/3 flapping observed 2026-06-22). Pairs with `previewTunnelCmd`; the two
+ *  builders are the single source of truth for the attach (addVm) and re-wire call
+ *  sites so neither forward's `-L` spec can drift back into the other's process.
+ *  Pure; no I/O. */
+function editorTunnelCmd({ gcloud, inst, zone, editorPort, n } = {}) {
+  return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${editorPort}:127.0.0.1:14199 > /tmp/ssh-tunnel-vm-${n}.log 2>&1 &`;
+}
+
+/** Build the `nohup … gcloud compute ssh … -N -L …` shell string that opens the
+ *  LIVE-PREVIEW forward (`previewPort` → VM:<appPort>) as its OWN ssh process,
+ *  logging to `/tmp/ssh-preview-vm-<n>.log`. The preview forward's target port
+ *  changes whenever the app's dev-server port is (re)resolved, so it lives apart
+ *  from the editor reachability forward (`editorTunnelCmd`): a preview re-wire
+ *  pkills + respawns ONLY this process, leaving the editor :14199 forward — and
+ *  the reachability probe riding it — untouched. The preview local port is unique
+ *  per VM and never collides with the editor port, so the re-wire/destroy
+ *  `pkill -f "<previewPort>:127.0.0.1:"` targets exactly this process. Pure; no
+ *  I/O. */
+function previewTunnelCmd({ gcloud, inst, zone, previewPort, appPort, n } = {}) {
+  return `nohup ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} -- -N -L ${previewPort}:127.0.0.1:${appPort} > /tmp/ssh-preview-vm-${n}.log 2>&1 &`;
+}
+
+/** Build the shell snippet the Add script runs to AWAIT cloud:up's clean exit at
+ *  container-healthy instead of reaping it mid-flight.
+ *
+ *  History — two bugs, one helper: (1) vm-add-ingress-survives-bes-create: the Add
+ *  used to `kill $UP_PID` ~15s after the container was Up, SIGTERMing
+ *  `backend-services create` mid-flight (the 503 strand), so this began polling
+ *  `cloud:up` to exit on its own rather than reaping it. (2)
+ *  vm--async-add-time-lb-ingress-wiring: `cloud:up` no longer BLOCKS on the wiring
+ *  tail — it kicks the EXTERNAL_MANAGED `backend-services create` + propagation off
+ *  DETACHED (see cloud.js startDetachedAddWiring) and returns at container-healthy,
+ *  so the detached child can no longer be reaped by anything that kills `cloud:up`.
+ *  This poll therefore now resolves in ~seconds on the happy path (cloud:up has
+ *  already exited); it stays only as the bounded backstop that reaps a `cloud:up`
+ *  genuinely wedged BEFORE the early return (e.g. a stuck container gate). The
+ *  background wiring converges via the dashboard's auto-rewire gather, so
+ *  `deadlineSec` shrinks from the old 900s wiring budget to a container-readiness
+ *  bound. `pidVar` is referenced by name so it expands at run time. Pure; no I/O. */
+function awaitWiringCmd({ inst, deadlineSec = 180, pidVar = "UP_PID" } = {}) {
+  return [
+    `echo "awaiting cloud:up exit at container-healthy for ${inst} (up to ${deadlineSec}s; LB wiring converges in the background)..."`,
+    `__cy_wiring_waited=0`,
+    `while kill -0 $${pidVar} 2>/dev/null; do`,
+    `  if [ "$__cy_wiring_waited" -ge ${deadlineSec} ]; then`,
+    `    echo "WARN cloud:up still running after ${deadlineSec}s (wedged before the container-healthy early return) — reaping it (the dashboard self-heal will converge any half-wired backend)"`,
+    `    kill $${pidVar} 2>/dev/null; pkill -f "cloud.js up --instance-name ${inst}" 2>/dev/null; break`,
+    `  fi`,
+    `  sleep 5; __cy_wiring_waited=$((__cy_wiring_waited + 5))`,
+    `done`,
+    `wait $${pidVar} 2>/dev/null || true`,
+  ].join("\n");
+}
+
+/** Get authenticated Git URL for checking client branch. */
+function getAuthRepoUrl(repo, token) {
+  if (!repo) return "";
+  if (!token) return repo;
+  const sshRegex = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/;
+  const sshMatch = repo.match(sshRegex);
+  if (sshMatch) {
+    return `https://x-access-token:${token}@github.com/${sshMatch[1]}/${sshMatch[2]}`;
+  }
+  if (repo.startsWith("https://github.com/")) {
+    return repo.replace(/^https:\/\/github\.com\//, `https://x-access-token:${token}@github.com/`);
+  }
+  return repo;
+}
+
+/** Interpret the output of git ls-remote to see if a branch exists. */
+function interpretLsRemote({ stdout = "", code = 0, err = null, repo = "", branch = "" } = {}) {
+  const b = (branch || "").trim();
+  if (!b) {
+    return { ok: true, msg: "using repo default branch" };
+  }
+  if (err || code !== 0) {
+    const errMsg = (err && (err.message || String(err))) || "command failed";
+    return {
+      ok: false,
+      soft: true,
+      msg: `couldn't verify branch: ${errMsg.trim()}`
+    };
+  }
+  const trimmed = (stdout || "").trim();
+  if (trimmed) {
+    return { ok: true };
+  } else {
+    return {
+      ok: false,
+      msg: `branch '${b}' not found in ${repo || "repository"}`
+    };
+  }
+}
+
 module.exports = {
+  AGENTS,
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
@@ -606,12 +901,17 @@ module.exports = {
   queuedStatusForAction,
   pushHistory,
   distinctConfigs,
+  recentLaunchDisplay,
   defaultConfig,
   configForVm,
+  latestLaunchTs,
+  recentlyLaunchedWithin,
   resolveCardIdentity,
   stickyClientProject,
+  stickyAppPort,
   classifyProjectKind,
   resolveCredsSource,
+  claudeAuthSeeded,
   buildCredsSteps,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,
@@ -619,4 +919,10 @@ module.exports = {
   editorSourceShellResolve,
   rebuildStrategy,
   decideStartJob,
+  editorTunnelCmd,
+  previewTunnelCmd,
+  awaitWiringCmd,
+  getAuthRepoUrl,
+  interpretLsRemote,
+  isPlaceholderProject,
 };