@codeyam-editor/codeyam-editor 0.1.5 → 0.1.6

package/npm/launch-config.js

@@ -119,6 +119,52 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
+/** Pre-flight the operator-host CONFIG a dashboard Add depends on, BEFORE
+ *  spawning the ~20-min cloud:up. Pure classifier: it takes the ALREADY-resolved
+ *  zone, project, and GitHub token (the side-effecting resolution — env lookups,
+ *  `gh auth token`, gcloud defaults — is the caller's job) and returns { ok, msg }
+ *  naming the exact fix for the FIRST blocking gap. This turns a config fault into
+ *  a seconds-fast, actionable add-rejection instead of a cryptic `cloud:up FAILED
+ *  (exit 1)` the operator has to dig out of a 20-min job log.
+ *
+ *  It guards the two config faults that silently broke every fleet add on
+ *  2026-07-20:
+ *   - no resolvable compute zone → cloud:up aborts at its own --zone check in ~15s
+ *     before creating any instance;
+ *   - no GitHub token → the fresh VM's bootstrap dies cloning the PRIVATE editor
+ *     repo at `could not read Username for 'https://github.com'`.
+ *  `allowNoGitCredentials` mirrors cloud:up's --allow-no-git-credentials opt-out
+ *  for an intentionally read-only VM (no push token needed). Pure; no I/O. */
+function addPreflight({ zone, project, token, allowNoGitCredentials = false } = {}) {
+  const blank = (v) => typeof v !== "string" || v.trim() === "";
+  if (blank(zone)) {
+    return {
+      ok: false,
+      msg:
+        "no compute zone configured — set ZONE in /etc/codeyam/operator-host.env " +
+        "(or `gcloud config set compute/zone <zone>`) before adding a VM.",
+    };
+  }
+  if (blank(project)) {
+    return {
+      ok: false,
+      msg:
+        "no GCP project configured — set GCP_PROJECT (or a non-placeholder " +
+        "project in .codeyam/cloud.json) before adding a VM.",
+    };
+  }
+  if (!allowNoGitCredentials && blank(token)) {
+    return {
+      ok: false,
+      msg:
+        "no GitHub token — set GITHUB_TOKEN/GH_TOKEN in /etc/codeyam/operator-host.env " +
+        "(the VM bootstrap needs it to clone the private editor repo), or provision a " +
+        "read-only VM with --allow-no-git-credentials.",
+    };
+  }
+  return { ok: true };
+}
+
 /** Gate mirror of cloud.js::assertVariantProvisionable — which editor variants
  *  can be provisioned onto a cloud VM. All three variants now provision: `dev`
  *  builds the editor image from source, while `staging`/`production` run the
@@ -186,8 +232,10 @@ function isPlaceholderProject(value) {
  *  image from editorBranch); the client repo/branch is what lands in
  *  /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) {
+ *  carries every launch choice. Decoupled exactly as cloud.js consumes them.
+ *  `zone` is the resolved compute zone (the dashboard's ZONE); passing it
+ *  explicitly is what keeps an add off the ambient gcloud default. */
+function cloudUpArgs(cfg, instanceName, project, zone) {
   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
@@ -200,6 +248,13 @@ function cloudUpArgs(cfg, instanceName, project) {
   // preserve the pre-existing arg shape (cloud.js then falls back to the gcloud
   // default, as before).
   if (project) args.push("--project", project);
+  // Pass the resolved compute zone explicitly, for the SAME reason as --project:
+  // a bare cloud:up otherwise falls back to `gcloud config get-value
+  // compute/zone`, and an operator host with no default compute/zone aborts
+  // EVERY add at cloud:up's own --zone check in ~15s, before any instance is
+  // created (the 2026-07-20 fleet-wide add failure). Omitted only when the caller
+  // resolves no zone, preserving the pre-existing arg shape for legacy callers.
+  if (zone) args.push("--zone", zone);
   // Greenfield (new folder) vs clone an existing repo.
   if (cfg.newProjectName) args.push("--new-project", cfg.newProjectName);
   else args.push("--repo", cfg.clientRepo);
@@ -497,6 +552,61 @@ function stickyAppPort(prevAppPort, info) {
   return typeof prevAppPort === 'number' && !Number.isNaN(prevAppPort) ? prevAppPort : null;
 }
 
+/** Resolve a VM's preview-tunnel reachability stickily, mirroring `stickyAppPort`.
+ *  A single flaky preview probe must not blink the 👁 Live Preview link off:
+ *  an explicit `true`/`false` from the fresh poll passes through (a genuine
+ *  dead/alive transition always wins), but a missing / null / undefined
+ *  `info.previewReachable` (transient poll — the probe was skipped, timed out,
+ *  or the whole probe object is absent) retains the last-known-good
+ *  `prevPreviewReachable` instead of blanking it to null. `null` results only
+ *  when neither a fresh boolean nor a previous boolean exists — the true
+ *  never-probed first-poll case. Pure; no I/O.
+ *
+ *  @param prevPreviewReachable the previous `state.vms[n].previewReachable`
+ *  @param info                 the fresh probe result ({ previewReachable } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewReachable(prevPreviewReachable, info) {
+  const fresh = info && info.previewReachable;
+  if (fresh === true || fresh === false) return fresh;
+  return prevPreviewReachable === true || prevPreviewReachable === false
+    ? prevPreviewReachable
+    : null;
+}
+
+/** Resolve a VM's preview-SERVING signal — "is the VM's dev server up?" —
+ *  stickily from the `previewState` field the editor already emits on
+ *  `/api/session-info`. This is the operator-host-safe replacement for the
+ *  loopback-only `previewReachable` probe: session-info reaches every VM over
+ *  the IAP-LB seam on the GCE operator host, where the `127.0.0.1` preview
+ *  forward `previewReachable` depended on cannot exist (so it read `false`
+ *  fleet-wide there). It measures the SAME thing the old loopback probe did —
+ *  "the dev server serves" — not public LB ingress; that is `previewIngress`'s job.
+ *
+ *  `compute_preview_state` classifies it authoritatively from inside the VM
+ *  (immune to tunnel flakiness, with a recompile-grace debounce):
+ *    `"forwarding"`   → true  (dev server up / serving).
+ *    `"placeholder"`  → false (dev server down or never started).
+ *    anything else    → sticky: a missing field (legacy editor predating
+ *                       `previewState`, or `info` null on a transient/failed
+ *                       poll) retains the last-known-good `prevPreviewServing`
+ *                       rather than blinking the 👁 link off. `null` only when
+ *                       neither a fresh state nor a previous boolean exists —
+ *                       the true never-probed first-poll case. Pure; no I/O.
+ *
+ *  Mirrors `stickyPreviewReachable`'s tri-state stickiness exactly.
+ *
+ *  @param prevPreviewServing the previous `state.vms[n].previewServing`
+ *  @param info               the fresh `/api/session-info` result ({ previewState } | null)
+ *  @returns true | false | null per the rules above. */
+function stickyPreviewServing(prevPreviewServing, info) {
+  const state = info && info.previewState;
+  if (state === 'forwarding') return true;
+  if (state === 'placeholder') return false;
+  return prevPreviewServing === true || prevPreviewServing === false
+    ? prevPreviewServing
+    : 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
@@ -674,6 +784,61 @@ function claudeAuthSeeded(mode) {
 // the server.js helper so callers don't have to thread one through.
 function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 
+/** Build a `docker exec … bash -c` sink that stages stdin to a same-directory
+ *  `.cytmp` sibling and only `mv`s it onto `target` when the staged file is
+ *  NON-EMPTY — exiting 1 (so the caller's `… || echo CY_DEGRADED` fires) and
+ *  leaving any existing `target` UNTOUCHED on empty/unreadable input.
+ *
+ *  Closes the truncate-to-0 hazard the plan targets: an empty/unreadable donor's
+ *  `base64 -d > /root/.claude/.credentials.json` used to clobber the live creds
+ *  to a 0-byte file AND still report success, because the pipeline's exit status
+ *  is the sink's, not the empty upstream's. This mirrors the non-empty `-s` guard
+ *  the git-cred cache path already uses (scripts/cloud-editor-entrypoint.sh).
+ *
+ *  `decode:true` base64-decodes stdin (the donor / host-stash cred copies);
+ *  `decode:false` copies stdin verbatim (the Rebuild onboarding-state re-seed).
+ *
+ *  `requireCredentialShape:true` adds, ON TOP of the non-empty guard, a Claude
+ *  `.credentials.json` shape check before the `mv`: a positive plausible
+ *  `expiresAt` (rejects the observed corrupt-write `expiresAt: 0`) AND non-empty
+ *  access/refresh tokens. A non-empty-but-malformed donor (valid-looking file
+ *  with a sentinel expiry or empty tokens) therefore never overwrites the
+ *  target — closing the remaining gap the non-empty `[ -s ]` guard alone leaves.
+ *  The checks are quote-free single-quoted ERE patterns (no `"`), which stay
+ *  intact through the ssh→docker→`bash -c "…"` quoting layers without escaping.
+ *  The editor-side self-heal (control-api `creds_refresh` / `auth_session`)
+ *  remains the durable defense against a bad credential from ANY writer; this
+ *  hardens the in-repo copy path so it is not itself a source.
+ *
+ *  Deliberately uses NO shell variables or command substitution: a fixed
+ *  `<target>.cytmp` sibling keeps the script free of `$var`, which the VM-host
+ *  shell that runs the `gcloud … --command` would otherwise expand (to empty)
+ *  before docker exec ever sees it. The `.cytmp` sibling sits in the same
+ *  directory as `target`, so the `mv` is an atomic same-filesystem rename. */
+function verifyBeforeMoveSink(
+  container,
+  target,
+  { decode = true, requireCredentialShape = false } = {},
+) {
+  const tmp = `${target}.cytmp`;
+  const read = decode ? "base64 -d" : "cat";
+  // Positive plausible `expiresAt` (13+ digit millis, first digit non-zero — so
+  // `0`/negatives/tiny values fail), plus non-empty access + refresh tokens
+  // (≥20 token-ish chars). `[^0-9-]*` / `[^A-Za-z0-9]*` bridge the `":"`
+  // punctuation without literal quotes; the value `0` in a corrupt file is a
+  // digit that blocks the skip, so the pattern can't false-match a later field.
+  const shape = requireCredentialShape
+    ? ` && grep -Eq 'expiresAt[^0-9-]*[1-9][0-9]{12,}' ${tmp}` +
+      ` && grep -Eq 'accessToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}` +
+      ` && grep -Eq 'refreshToken[^A-Za-z0-9]*[A-Za-z0-9_-]{20,}' ${tmp}`
+    : "";
+  const script =
+    `umask 077; ${read} > ${tmp}; ` +
+    `if [ -s ${tmp} ]${shape}; then mv ${tmp} ${target} && chmod 600 ${target}; ` +
+    `else rm -f ${tmp}; exit 1; fi`;
+  return `docker exec -i ${container} bash -c "${script}"`;
+}
+
 /** Build the shell steps that seed a freshly-added VM's claude + git credentials,
  *  for the resolved `mode` (see `resolveCredsSource`). Returns an array of shell
  *  strings the caller newline-joins into the larger provisioning script — each
@@ -699,15 +864,22 @@ function _shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
  *
  *  Pure; no I/O. */
 function buildCredsSteps({ mode, refInst = "", inst, container, gcloud, zone, n, claudeCredsSrc = "" } = {}) {
-  const claudeSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude/.credentials.json && chmod 600 /root/.claude/.credentials.json"`;
-  const claudeJsonSink = `docker exec -i ${container} bash -c "umask 077; base64 -d > /root/.claude.json && chmod 600 /root/.claude.json"`;
+  // The `.credentials.json` copy additionally validates the donor's credential
+  // shape (positive `expiresAt`, non-empty tokens) before overwriting — a
+  // non-empty-but-corrupt donor must not clobber a working target. The
+  // `.claude.json` (onboarding-state) copy has a different shape, so it keeps
+  // the plain non-empty guard.
+  const claudeSink = verifyBeforeMoveSink(container, "/root/.claude/.credentials.json", {
+    requireCredentialShape: true,
+  });
+  const claudeJsonSink = verifyBeforeMoveSink(container, "/root/.claude.json");
   const loginHint = `run: docker exec -it ${container} claude /login on ${inst}`;
   if (mode === "donor") {
     return [
       `echo "copying git creds from ${refInst}..."`,
       `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='cat $HOME/.codeyam-cloud-git-credentials' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command='umask 077; cat > $HOME/.codeyam-cloud-git-credentials' 2>/dev/null || echo "CY_DEGRADED git creds copy failed on VM-${n} — re-copy creds from a live donor (the agent can't git pull/push until then)"`,
       `echo "copying claude auth from ${refInst} (container->container)..."`,
-      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude/.credentials.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth copied" || echo "CY_DEGRADED claude auth copy failed on VM-${n} — ${loginHint}"`,
+      `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude/.credentials.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeSink)} 2>/dev/null && echo "claude auth copied" || echo "CY_DEGRADED claude auth copy failed on VM-${n} (empty/unreadable/malformed donor — existing creds left untouched, not overwritten with a corrupt credential) — ${loginHint}"`,
       `echo "copying claude.json (onboarding state) from ${refInst} (container->container)..."`,
       `${gcloud} compute ssh ${refInst} --tunnel-through-iap --zone=${zone} --command='docker exec ${container} base64 /root/.claude.json' 2>/dev/null | ${gcloud} compute ssh ${inst} --tunnel-through-iap --zone=${zone} --command=${_shq(claudeJsonSink)} 2>/dev/null && echo "claude.json copied" || echo "CY_DEGRADED claude.json copy failed on VM-${n} — first interactive claude launch may show 'Select login method' menu; ${loginHint} once to complete onboarding"`,
     ];
@@ -758,7 +930,7 @@ function buildClaudeJsonPreserveSteps({ container, n = "", bakVar = "CY_CLAUDE_J
     `if docker exec ${container} cat /root/.claude.json > "$${bakVar}" 2>/dev/null && [ -s "$${bakVar}" ]; then echo "captured /root/.claude.json ($(wc -c < "$${bakVar}") bytes) to preserve onboarding state across recreate"; else echo "no /root/.claude.json to preserve (new container will use the image baseline)"; : > "$${bakVar}"; fi`,
   ];
   const restore = [
-    `if [ -s "$${bakVar}" ]; then docker exec -i ${container} bash -c 'umask 077; cat > /root/.claude.json && chmod 600 /root/.claude.json' < "$${bakVar}" && echo "re-seeded /root/.claude.json (onboarding state preserved across recreate)" || echo "CY_DEGRADED claude.json re-seed failed on VM-${n} after Rebuild — first interactive claude launch may show 'Select login method'; ${loginHint} once to complete onboarding"; else echo "no preserved /root/.claude.json; ${loginHint} if the Build tab shows the welcome menu"; fi`,
+    `if [ -s "$${bakVar}" ]; then ${verifyBeforeMoveSink(container, "/root/.claude.json", { decode: false })} < "$${bakVar}" && echo "re-seeded /root/.claude.json (onboarding state preserved across recreate)" || echo "CY_DEGRADED claude.json re-seed failed on VM-${n} after Rebuild — first interactive claude launch may show 'Select login method'; ${loginHint} once to complete onboarding"; else echo "no preserved /root/.claude.json; ${loginHint} if the Build tab shows the welcome menu"; fi`,
     `rm -f "$${bakVar}"`,
   ];
   return { capture, restore };
@@ -890,6 +1062,7 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,
   variantNpmDistTag,
@@ -909,10 +1082,13 @@ module.exports = {
   resolveCardIdentity,
   stickyClientProject,
   stickyAppPort,
+  stickyPreviewReachable,
+  stickyPreviewServing,
   classifyProjectKind,
   resolveCredsSource,
   claudeAuthSeeded,
   buildCredsSteps,
+  verifyBeforeMoveSink,
   buildClaudeJsonPreserveSteps,
   buildEnvApplyCommand,
   resolveEditorSource,