@codeyam-editor/codeyam-editor 0.1.8 → 0.1.9

package/npm/fleet-vm-readiness.js

@@ -71,6 +71,12 @@
 //   'cli-missing'  — the editor is up but the build-agent CLI isn't installed
 //                    (`providerAuth.cliInstalled === false`): a provisioning
 //                    fault, not a usable VM.
+//   'cli-broken'   — the CLI IS installed but will not execute
+//                    (`providerAuth.cliRunnable === false`): a provisioning
+//                    fault whose remedy is repair/reinstall, not a fresh
+//                    install and not re-authentication. Distinct from
+//                    'cli-missing' because sending an operator to "install it"
+//                    when it is already installed wastes the incident.
 //   'auth-unsettled' — the auth probe is wedged at `unknown` (timing out — the
 //                    exact VM5 auth shape): we can't even tell if login is
 //                    needed. A provisioning fault distinct from a clean
@@ -89,6 +95,7 @@ const READINESS_STATES = [
   'broker-down',
   'ws-dead',
   'cli-missing',
+  'cli-broken',
   'auth-unsettled',
   'needs-login',
   'ready',
@@ -100,23 +107,41 @@ const fpub = require('./fleet-public-url');
 
 // Classify the build-agent usability axis from the editor's own `providerAuth`
 // subtree (vm: Readiness Verifies Real Usability). control-api emits the SAME
-// `providerAuth` (with `cliInstalled` + settled `state`) on BOTH /api/config and
-// /api/session-info via build_provider_auth_json, so the dashboard reads it
-// straight off the gathered VM record — no re-derivation. Returns one verdict:
+// `providerAuth` (with `cliInstalled` + `cliRunnable` + settled `state`) on BOTH
+// /api/config and /api/session-info via build_provider_auth_json, so the
+// dashboard reads it straight off the gathered VM record — no re-derivation.
+// Returns one verdict:
 //   'cli-missing'    — `cliInstalled === false`: a provisioning fault.
-//   'auth-unsettled' — CLI installed but `state === 'unknown'` (probe wedged /
-//                      timing out — the VM5 shape): a provisioning fault.
-//   'needs-login'    — CLI installed, `state === 'needs-login'`: a LEGITIMATE,
+//   'cli-broken'     — CLI installed but `cliRunnable === false`: it resolves
+//                      and will not execute. A provisioning fault.
+//   'auth-unsettled' — CLI installed and runnable (or unprobed) but
+//                      `state === 'unknown'` (probe wedged / timing out — the
+//                      VM5 shape): a provisioning fault.
+//   'needs-login'    — CLI usable, `state === 'needs-login'`: a LEGITIMATE,
 //                      actionable state, not a fault.
-//   'ready'          — CLI installed, `state === 'authenticated'`: usable.
+//   'ready'          — CLI usable, `state === 'authenticated'`: usable.
 //   'unknown'        — providerAuth absent (older editor / probe never landed),
 //                      or any other shape: absence of evidence, never a fault.
-// Only an EXPLICIT `cliInstalled === false` / `state === 'unknown'` is a fault;
-// missing fields stay 'unknown' so an older editor never reads as broken.
+// Only an EXPLICIT `cliInstalled === false` / `cliRunnable === false` /
+// `state === 'unknown'` is a fault; missing fields stay 'unknown' so an older
+// editor never reads as broken.
+//
+// The `cli-broken` check sits BEFORE the state checks deliberately, and that
+// ordering IS the fix. A CLI that will not execute cannot have authenticated,
+// so `state: 'authenticated'` alongside `cliRunnable: false` is not a
+// contradiction to be resolved in the state's favour — it is precisely the
+// false green observed on VM-2 and VM-7 through the whole 2026-08-19/20 npm
+// publish race, where the card read `cliInstalled: true, state: "authenticated"`
+// while both boxes were unusable and the breakage was found only by ssh.
+//
+// `cliRunnable` is deliberately NOT required to be `true` to proceed: an older
+// editor server omits it entirely (`undefined`), and treating that as a fault
+// would mark every not-yet-upgraded VM in the fleet broken.
 function classifyAgentUsability(providerAuth) {
   if (!providerAuth || typeof providerAuth !== 'object') return 'unknown';
   if (providerAuth.cliInstalled === false) return 'cli-missing';
   if (providerAuth.cliInstalled !== true) return 'unknown';
+  if (providerAuth.cliRunnable === false) return 'cli-broken';
   if (providerAuth.state === 'unknown') return 'auth-unsettled';
   if (providerAuth.state === 'needs-login') return 'needs-login';
   if (providerAuth.state === 'authenticated') return 'ready';
@@ -126,8 +151,13 @@ function classifyAgentUsability(providerAuth) {
 // Map the agent-usability verdict to the tri-state the rostering gate
 // (fleet-cleanup's reapVerdict) consumes, mirroring `projectWired`'s
 // true|false|null contract so a flaky probe can never strand a healthy VM:
-//   false — a PROVISIONING FAULT ('cli-missing' / 'auth-unsettled'): the box is
-//           not usable, so don't roster it as healthy (the VM5 false-green).
+//   false — a PROVISIONING FAULT ('cli-missing' / 'cli-broken' /
+//           'auth-unsettled'): the box is not usable, so don't roster it as
+//           healthy (the VM5 false-green). 'cli-broken' joins the fault set
+//           because a CLI that will not execute makes the VM exactly as
+//           unusable as one that was never installed — the two differ only in
+//           the remedy an operator should reach for, not in whether the box can
+//           do work.
 //   true  — usable enough to roster: 'ready', or a legitimate 'needs-login'
 //           (the user must auth, but that's an expected state, not a
 //           half-provisioned box that should be held back).
@@ -135,7 +165,13 @@ function classifyAgentUsability(providerAuth) {
 //           evidence must NEVER block rostering, exactly like reapVerdict's null
 //           tolerance for projectWired.
 function agentRosterReady(verdict) {
-  if (verdict === 'cli-missing' || verdict === 'auth-unsettled') return false;
+  if (
+    verdict === 'cli-missing' ||
+    verdict === 'cli-broken' ||
+    verdict === 'auth-unsettled'
+  ) {
+    return false;
+  }
   if (verdict === 'ready' || verdict === 'needs-login') return true;
   return null;
 }
@@ -206,12 +242,17 @@ function deriveVmReadiness(v, ctx) {
     if (v.publicWsHealth === 'unwired' && !(bh && bh.editor === 'healthy')) return 'ws-dead';
   }
   // 6. Agent usability: the box is up and the WS path carries frames, but the
-  //    build agent itself may not be usable — CLI not installed, or the auth
-  //    probe wedged at 'unknown'. A legitimate 'needs-login' surfaces as its own
-  //    actionable state (Authenticate), distinct from a provisioning fault.
-  //    Absence of providerAuth (older editor / unprobed) falls through to ready.
+  //    build agent itself may not be usable — CLI not installed, CLI installed
+  //    but not executable, or the auth probe wedged at 'unknown'. A legitimate
+  //    'needs-login' surfaces as its own actionable state (Authenticate),
+  //    distinct from a provisioning fault. Absence of providerAuth (older
+  //    editor / unprobed) falls through to ready.
   const usability = classifyAgentUsability(v.providerAuth);
   if (usability === 'cli-missing') return 'cli-missing';
+  // Surfaced as its own readiness state rather than folded into 'cli-missing':
+  // the card's whole job here is to send an operator to the right remedy, and
+  // "reinstall the broken CLI" is not "install the missing one".
+  if (usability === 'cli-broken') return 'cli-broken';
   if (usability === 'auth-unsettled') return 'auth-unsettled';
   if (usability === 'needs-login') return 'needs-login';
   // 6b. Preview-host IAP gap: the editor surface grants access (the URL routes

package/npm/launch-config.js

@@ -119,6 +119,79 @@ function validateLaunchConfig(cfg) {
   return { ok: true };
 }
 
+/** The branch refs a launch config asks git to resolve, as
+ *  `[{ field, repo, branch }]` — one entry per branch-carrying field that is
+ *  actually populated. This is the input to a ref-existence preflight; it lives
+ *  beside normalizeLaunchConfig (rather than in a second parser at the add
+ *  endpoint or in cloud.js) because it reads the SAME canonical field names that
+ *  normalizer produces, so a field rename can never leave the two disagreeing.
+ *
+ *  BOTH fields are reported, deliberately. In the 2026-08-25 incident the dead
+ *  ref sat in `clientBranch` AND `editorBranch`, and it was `clientBranch` that
+ *  actually killed the bootstrap — an editor-only check would have missed it.
+ *
+ *  A greenfield add (`newProjectName`, no `clientRepo`) has no client repo to
+ *  resolve a branch against, so its clientBranch is skipped rather than probed
+ *  against a repo URL that does not exist. `editorRepo` is passed in because the
+ *  launch config carries an editor BRANCH but not an editor REPO — the repo is
+ *  the caller's (cloud:up resolves it via resolveEditorConfig; the dashboard
+ *  holds it in REPO). Pure; no I/O. */
+function branchRefTargets(cfg, { editorRepo } = {}) {
+  const c = cfg || {};
+  const targets = [];
+  if (c.clientRepo && c.clientBranch) {
+    targets.push({ field: "clientBranch", repo: c.clientRepo, branch: c.clientBranch });
+  }
+  if (editorRepo && c.editorBranch) {
+    targets.push({ field: "editorBranch", repo: editorRepo, branch: c.editorBranch });
+  }
+  return targets;
+}
+
+/** Partition branchRefTargets by whether each ref still resolves, using an
+ *  INJECTED probe so the decision logic is unit-tested with no network and no
+ *  git. `refExists({ repo, branch })` returns true when the ref is present,
+ *  false when it is provably gone.
+ *
+ *  A probe that cannot reach the remote at all must NOT report false — a network
+ *  or credential fault is not evidence a branch was deleted, and treating it as
+ *  such would refuse every add the moment GitHub blipped. The probe signals that
+ *  by returning `null`/`undefined`, which this treats as "unknown, let it
+ *  through": the classifier arm downstream still catches a genuinely dead ref,
+ *  at the cost this preflight normally saves. Fail-open is the right default
+ *  here precisely because the preflight is an OPTIMIZATION over a failure that
+ *  is already handled, never the only line of defence. Pure; no I/O. */
+function missingBranchRefs(targets, refExists) {
+  const missing = [];
+  for (const t of targets || []) {
+    if (refExists(t) === false) missing.push(t);
+  }
+  return missing;
+}
+
+/** Operator-facing copy for a failed branch-ref preflight. States the OUTCOME
+ *  first (nothing was created), then the mechanism, then the remedy — and never
+ *  the "a partial instance may exist — reconcile or destroy it" language the
+ *  generic provisioning failure uses, which is what made the real incident
+ *  confusing: at preflight time no instance, disk, NEG or backend service has
+ *  been created, so there is nothing to reconcile and nothing to destroy.
+ *
+ *  Names which FIELD carried the dead ref, because the two are configured in
+ *  different places and an operator who only corrects one re-issues a request
+ *  that fails identically. Pure; no I/O. */
+function missingBranchRefMessage(missing) {
+  const list = (missing || [])
+    .map((m) => `${m.field}: branch '${m.branch}' is not on ${m.repo}`)
+    .join("; ");
+  return (
+    `Branch no longer exists on origin — ${list}. ` +
+    "Nothing was provisioned: this is checked before any instance is created, so " +
+    "there is no VM, disk or backend service to clean up. This repo prunes branches " +
+    "when they merge, so a stored branch name expires silently. Re-add on a live " +
+    "branch (the current fleet branch, or any branch that still exists on origin)."
+  );
+}
+
 /** 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,
@@ -522,11 +595,42 @@ function recentlyLaunchedWithin(ts, nowMs, graceMs) {
  *                  variant(@branch) fallback.
  *   - source       "live" when editorIdentity drove editorLabel, else
  *                  "history" — the affordance the card uses to mark inferred
- *                  data. Pure; no I/O. */
+ *                  data.
+ *   - deployedBranch the branch the fleet ADVANCED this VM to, from the editor's
+ *                  `editorDeployment` (which reads the record the refresh script
+ *                  writes at install time); null when the editor reports none.
+ *   - deployedTag  the full artifact tag behind that branch, for the hover.
+ *   - deployedSource "live" when the editor reported a deployment, else
+ *                  "unknown".
+ *   - deployedState the card's three-way presentation verdict, resolved HERE
+ *                  rather than in the browser so the rule is unit-tested in one
+ *                  place and index.html carries no copy of it (the compromise
+ *                  groupVmsByProject's own comment apologizes for, avoidable
+ *                  here because this value rides in the /data payload):
+ *                    "agrees"  deployment and provenance name the same branch
+ *                    "differs" they disagree — the EXPECTED plan-only-retag
+ *                              state, to be shown as a pair, never badged
+ *                    "unknown" no deployment reported
+ *
+ *  editorLabel and deployedBranch answer DIFFERENT questions and are routinely
+ *  expected to disagree. editorLabel is build provenance — what source the
+ *  binary was compiled from — and stays exactly as it was; it is the right
+ *  answer to "what code is this actually running?" and is what fragility #33's
+ *  fix was built for. deployedBranch is the deployment target. After a plan-only
+ *  advance, where fleet-advance-to.sh correctly retags the base branch's CI
+ *  binary, provenance `main` + deployment `editor-improvements-78` is the
+ *  CORRECT state, so the card must present the pair rather than badge it.
+ *
+ *  A missing deployment resolves to null / "unknown" and is NEVER filled in from
+ *  cfg.editorBranch, though that value is right there: it is written at
+ *  reconfigure and is not updated by a binary refresh, so it is stale for
+ *  precisely this question — the same live-over-history discipline the rest of
+ *  this function applies, and the same `source` honesty. Pure; no I/O. */
 function resolveCardIdentity(live, historyCfg) {
   const cfg = historyCfg || {};
   const lcp = live && live.clientProject;
   const lei = live && live.editorIdentity;
+  const led = live && live.editorDeployment;
 
   const historyName = cfg.clientRepo ? repoBasename(cfg.clientRepo) : (cfg.newProjectName || "");
   const project = (lcp && lcp.name) || historyName || null;
@@ -547,7 +651,24 @@ function resolveCardIdentity(live, historyCfg) {
     source = "history";
   }
 
-  return { project, clientBranch, editorLabel, source };
+  const deployedBranch = (led && led.branch) || null;
+  const deployedTag = (led && led.tag) || null;
+  const deployedSource = deployedBranch || deployedTag ? "live" : "unknown";
+  let deployedState;
+  if (!deployedBranch) deployedState = "unknown";
+  else if (deployedBranch === editorLabel) deployedState = "agrees";
+  else deployedState = "differs";
+
+  return {
+    project,
+    clientBranch,
+    editorLabel,
+    source,
+    deployedBranch,
+    deployedTag,
+    deployedSource,
+    deployedState,
+  };
 }
 
 /** Sticky-merge a VM poll's `clientProject` against the last-known-good value
@@ -1215,6 +1336,9 @@ module.exports = {
   EMPTY_CONFIG,
   normalizeLaunchConfig,
   validateLaunchConfig,
+  branchRefTargets,
+  missingBranchRefs,
+  missingBranchRefMessage,
   addPreflight,
   isVariantProvisionable,
   isVariantRebuildable,