@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/fleet-pool.js

@@ -0,0 +1,401 @@
+'use strict';
+
+// npm/fleet-pool.js — the warm-VM-pool state layer (improve38).
+//
+// Standing up a VM on demand pays for an image pull, a branch rebrand and —
+// the slow part — an interactive auth approval. The warm pool removes that
+// latency from the request path: keep N pre-provisioned, pre-authed, READY
+// idle VMs and CLAIM them in seconds (rebrand-only, no OAuth). This module is
+// the state seam for that pool — it answers "which VMs are idle-and-claimable
+// vs already-assigned" and performs the ATOMIC claim that guarantees two
+// operators never grab the same VM.
+//
+// Why a SEPARATE file from the roster (`fleet-vms.json`): the roster is a
+// shared contract — a plain JSON array of VM-number integers that the
+// dashboard, vm-watchdog, cloudflared-monitor and the bash publishers all
+// read. Widening it to carry per-VM status would break every reader (they
+// `jq -r '.[]'` it as scalars). So pool membership lives alongside the roster
+// in `.codeyam/logs/fleet-pool.json`, keyed by VM number, and the roster keeps
+// meaning "these VM numbers exist". A VM can be in the roster without being in
+// the pool (e.g. an operator's hand-driven VM); the pool only tracks the warm
+// set.
+//
+// On-disk shape (tolerant: a missing or malformed file is the empty pool):
+//   { "vms": { "<n>": { status, branch, freshAt, claimedAt } } }
+//     status:    "pool"      idle, claim-ready
+//                "assigned"  claimed by an operator, rebranded to `branch`
+//     branch:    the branch the VM is on (base branch while pooled)
+//     freshAt:   ISO timestamp of the last successful auth/health refresh —
+//                drives evict-before-claim of a member whose token lapsed
+//     claimedAt: ISO timestamp of the claim (null while pooled)
+//
+// The pure functions (normalize / select / refill / staleness) operate on a
+// plain state object and return a new one — no I/O — so they unit-test without
+// touching disk. readState/writeState/withLock add the atomic file layer, and
+// main() is the CLI seam the bash orchestrators (fleet-claim.sh,
+// fleet-pool-keeper.sh) call instead of re-implementing the logic in shell.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+
+const POOL_STATE_FILE = process.env.POOL_STATE_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-pool.json');
+
+const POOL = 'pool';
+const ASSIGNED = 'assigned';
+
+// ── Pure state helpers ──────────────────────────────────────────────────────
+
+// Coerce arbitrary parsed JSON into the canonical `{ vms: { <n>: entry } }`
+// shape. Drops entries whose key is not a positive integer or whose status is
+// unrecognized, so a truncated write or a hand-edit never feeds a malformed
+// entry into the claim path. Returned object is a fresh copy — callers mutate
+// it freely.
+function normalizeState(raw) {
+  const out = { vms: {} };
+  const vms = raw && typeof raw === 'object' ? raw.vms : null;
+  if (!vms || typeof vms !== 'object') return out;
+  for (const key of Object.keys(vms)) {
+    const n = Number(key);
+    if (!Number.isInteger(n) || n <= 0) continue;
+    const e = vms[key] || {};
+    const status = e.status === ASSIGNED ? ASSIGNED : e.status === POOL ? POOL : null;
+    if (!status) continue;
+    out.vms[n] = {
+      status,
+      branch: typeof e.branch === 'string' ? e.branch : null,
+      freshAt: typeof e.freshAt === 'string' ? e.freshAt : null,
+      claimedAt: typeof e.claimedAt === 'string' ? e.claimedAt : null,
+    };
+  }
+  return out;
+}
+
+// VM numbers in a given status, sorted ascending. Ascending order makes claim
+// selection deterministic (lowest-numbered idle VM first) so tests and two
+// concurrent callers agree on which VM a claim takes.
+function membersByStatus(state, status) {
+  return Object.keys(state.vms)
+    .map(Number)
+    .filter((n) => state.vms[n].status === status)
+    .sort((a, b) => a - b);
+}
+
+function poolMembers(state) {
+  return membersByStatus(state, POOL);
+}
+
+function assignedMembers(state) {
+  return membersByStatus(state, ASSIGNED);
+}
+
+// True when a pool entry's auth/health is older than `ttlMs` (its token may
+// have lapsed). An entry with no `freshAt` is treated as stale — "freshness
+// not proven" fails closed, mirroring fleet-ready's auth gate. Only meaningful
+// for pooled VMs; an assigned VM is the operator's concern, not the keeper's.
+function isStale(entry, nowMs, ttlMs) {
+  if (!entry || entry.status !== POOL) return false;
+  if (!entry.freshAt) return true;
+  const t = Date.parse(entry.freshAt);
+  if (Number.isNaN(t)) return true;
+  return nowMs - t > ttlMs;
+}
+
+// Pool VM numbers whose freshness has lapsed — the evict-before-claim set the
+// keeper drops (and replaces) so a claim never hands a caller a stale VM.
+function staleMembers(state, nowMs, ttlMs) {
+  return poolMembers(state).filter((n) => isStale(state.vms[n], nowMs, ttlMs));
+}
+
+// How many NEW pool VMs the keeper must provision to reach `target` idle
+// members. Assigned VMs do not count toward the pool — once claimed they're
+// gone from the warm set until released — so a claim naturally triggers a
+// refill. Never negative (an over-target pool is shrunk by policy, not here).
+function refillCount(state, target) {
+  const have = poolMembers(state).length;
+  return Math.max(0, target - have);
+}
+
+// The heart of the claim: deterministically move up to `count` idle pool VMs to
+// `assigned` on `branch`. Pure — returns { next, claimed, shortfall } without
+// touching disk; the caller persists `next` under the lock. Lowest-numbered
+// VMs are taken first. `shortfall` (requested minus granted) is the signal the
+// orchestrator uses to fall back to on-demand provisioning when the pool can't
+// satisfy the whole request — an empty pool yields claimed=[] , shortfall=count
+// rather than an error.
+function selectForClaim(state, count, branch, nowIso) {
+  const next = normalizeState(state);
+  const idle = poolMembers(next);
+  const take = idle.slice(0, Math.max(0, count));
+  for (const n of take) {
+    next.vms[n] = {
+      ...next.vms[n],
+      status: ASSIGNED,
+      branch,
+      claimedAt: nowIso,
+    };
+  }
+  return { next, claimed: take, shortfall: Math.max(0, count - take.length) };
+}
+
+// Register (or overwrite) a VM in the pool state. The keeper calls this after
+// provisioning a fresh READY VM (status=pool) and the claim path can re-add an
+// assigned VM. `freshAt` defaults to now for a pool member so a just-verified
+// VM isn't immediately stale.
+function applyAdd(state, n, status, branch, nowIso) {
+  const next = normalizeState(state);
+  const st = status === ASSIGNED ? ASSIGNED : POOL;
+  next.vms[n] = {
+    status: st,
+    branch: branch || null,
+    freshAt: st === POOL ? nowIso : (next.vms[n] && next.vms[n].freshAt) || null,
+    claimedAt: st === ASSIGNED ? nowIso : null,
+  };
+  return next;
+}
+
+// Return an assigned VM to the idle pool (operator finished with it). A no-op
+// for an absent VM. `freshAt` is reset to now: a just-released VM was live and
+// authed, so it's claim-ready again without waiting for the keeper's refresh.
+function applyRelease(state, n, nowIso) {
+  const next = normalizeState(state);
+  if (!next.vms[n]) return next;
+  next.vms[n] = {
+    ...next.vms[n],
+    status: POOL,
+    freshAt: nowIso,
+    claimedAt: null,
+  };
+  return next;
+}
+
+// Drop a VM from the pool state entirely (the keeper evicts a stale/unhealthy
+// member before replacing it). A no-op for an absent VM.
+function applyEvict(state, n) {
+  const next = normalizeState(state);
+  delete next.vms[n];
+  return next;
+}
+
+// Stamp a pool member as freshly auth/health-verified. The keeper calls this
+// after a successful credential refresh so the member's eviction clock resets.
+function applyMarkFresh(state, n, nowIso) {
+  const next = normalizeState(state);
+  if (!next.vms[n]) return next;
+  next.vms[n] = { ...next.vms[n], freshAt: nowIso };
+  return next;
+}
+
+// ── Atomic file layer ───────────────────────────────────────────────────────
+
+// Synchronous millisecond sleep without a busy CPU spin — used by withLock's
+// retry. Atomics.wait blocks the (single) thread for `ms`; a fresh 4-byte
+// SharedArrayBuffer that nothing else holds means the wait always times out
+// rather than being woken early.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Run `fn` while holding a cross-PROCESS mutex around the pool-state file, so a
+// read-modify-write (the claim) is atomic even when two operators run
+// `fleet-claim` at the same moment. The lock is a directory next to the state
+// file: `mkdir` is atomic on POSIX, so exactly one process wins the create and
+// the rest retry. A lock older than `staleMs` is assumed abandoned (a crashed
+// claimer) and stolen, so a dead process can't wedge the pool forever.
+function withLock(fn, { retries = 100, delayMs = 25, staleMs = 30000 } = {}) {
+  const lockDir = `${POOL_STATE_FILE}.lock`;
+  fs.mkdirSync(path.dirname(POOL_STATE_FILE), { recursive: true });
+  let held = false;
+  for (let i = 0; i < retries && !held; i += 1) {
+    try {
+      fs.mkdirSync(lockDir);
+      held = true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      // Steal an abandoned lock (claimer crashed mid-operation).
+      try {
+        const age = Date.now() - fs.statSync(lockDir).mtimeMs;
+        if (age > staleMs) {
+          fs.rmdirSync(lockDir);
+          continue; // retry the mkdir immediately
+        }
+      } catch { /* lock vanished between stat and now — just retry */ }
+      sleepSync(delayMs);
+    }
+  }
+  if (!held) throw new Error(`fleet-pool: could not acquire lock ${lockDir} after ${retries} tries`);
+  try {
+    return fn();
+  } finally {
+    try { fs.rmdirSync(lockDir); } catch { /* already gone */ }
+  }
+}
+
+// Read + normalize the pool state. A missing or malformed file is the empty
+// pool `{ vms: {} }` (the documented tolerant contract), so a truncated write
+// never throws into the keeper's reconcile loop.
+function readState() {
+  try {
+    return normalizeState(JSON.parse(fs.readFileSync(POOL_STATE_FILE, 'utf8')));
+  } catch {
+    return { vms: {} };
+  }
+}
+
+// Persist `state` atomically: write a pid-tagged temp file then `rename` over
+// the target so a concurrent reader never observes a half-written file (same
+// discipline as fleet-roster.writeRoster). Returns the normalized state.
+function writeState(state) {
+  const next = normalizeState(state);
+  fs.mkdirSync(path.dirname(POOL_STATE_FILE), { recursive: true });
+  const tmp = `${POOL_STATE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, POOL_STATE_FILE);
+  return next;
+}
+
+module.exports = {
+  POOL_STATE_FILE,
+  POOL,
+  ASSIGNED,
+  normalizeState,
+  poolMembers,
+  assignedMembers,
+  isStale,
+  staleMembers,
+  refillCount,
+  selectForClaim,
+  applyAdd,
+  applyRelease,
+  applyEvict,
+  applyMarkFresh,
+  withLock,
+  readState,
+  writeState,
+  main,
+};
+
+// ── CLI seam ────────────────────────────────────────────────────────────────
+// The bash orchestrators call these subcommands instead of re-deriving the
+// logic in shell. Each mutating subcommand runs its read-modify-write inside
+// withLock so concurrent callers serialize. Output is line-oriented and
+// machine-parseable (space-separated VM numbers / a single integer) so the
+// shell side stays a thin `$(node fleet-pool.js ...)` capture.
+
+function parsePoolFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[(i += 1)] : 'true';
+      flags[key] = val;
+    }
+  }
+  return flags;
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const flags = parsePoolFlags(rest);
+  const now = flags.now || new Date().toISOString();
+
+  switch (cmd) {
+    case 'list':
+      process.stdout.write(`${JSON.stringify(readState(), null, 2)}\n`);
+      return 0;
+    case 'pool-members':
+      process.stdout.write(`${poolMembers(readState()).join(' ')}\n`);
+      return 0;
+    case 'assigned-members':
+      process.stdout.write(`${assignedMembers(readState()).join(' ')}\n`);
+      return 0;
+    case 'refill-count': {
+      const target = Number(flags.target);
+      if (!Number.isInteger(target) || target < 0) {
+        process.stderr.write('fleet-pool: refill-count needs --target <non-negative int>\n');
+        return 2;
+      }
+      process.stdout.write(`${refillCount(readState(), target)}\n`);
+      return 0;
+    }
+    case 'stale': {
+      const ttl = Number(flags['ttl-seconds']);
+      if (!Number.isInteger(ttl) || ttl < 0) {
+        process.stderr.write('fleet-pool: stale needs --ttl-seconds <non-negative int>\n');
+        return 2;
+      }
+      const out = staleMembers(readState(), Date.parse(now), ttl * 1000);
+      process.stdout.write(`${out.join(' ')}\n`);
+      return 0;
+    }
+    case 'claim': {
+      const count = Number(flags.count);
+      const branch = flags.branch;
+      if (!Number.isInteger(count) || count <= 0 || !branch || branch === 'true') {
+        process.stderr.write('fleet-pool: claim needs --count <pos int> --branch <name>\n');
+        return 2;
+      }
+      const result = withLock(() => {
+        const { next, claimed, shortfall } = selectForClaim(readState(), count, branch, now);
+        writeState(next);
+        return { claimed, shortfall };
+      });
+      // VM numbers on stdout (the orchestrator rebrands each); shortfall on
+      // stderr so an empty/short pool is visible without polluting the capture.
+      process.stdout.write(`${result.claimed.join(' ')}\n`);
+      if (result.shortfall > 0) {
+        process.stderr.write(`fleet-pool: shortfall ${result.shortfall} (pool could not satisfy full claim)\n`);
+      }
+      return 0;
+    }
+    case 'add': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: add needs --vm <pos int>\n');
+        return 2;
+      }
+      const status = flags.status === ASSIGNED ? ASSIGNED : POOL;
+      withLock(() => writeState(applyAdd(readState(), vm, status, flags.branch, now)));
+      return 0;
+    }
+    case 'release': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: release needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyRelease(readState(), vm, now)));
+      return 0;
+    }
+    case 'evict': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: evict needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyEvict(readState(), vm)));
+      return 0;
+    }
+    case 'mark-fresh': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: mark-fresh needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyMarkFresh(readState(), vm, now)));
+      return 0;
+    }
+    default:
+      process.stderr.write(
+        'fleet-pool: usage: <list|pool-members|assigned-members|refill-count|stale|claim|add|release|evict|mark-fresh> [--flags]\n',
+      );
+      return 2;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}

package/npm/fleet-queue.js

@@ -0,0 +1,40 @@
+'use strict';
+// Pure helpers for the fleet dashboard's commit-queue auto-release logic
+// (scripts/operator/fleet-dashboard/server.js requires this). The decision
+// of whether to auto-release a queue head lives here so server.js's
+// orchestration stays thin and this piece can be unit-tested in isolation
+// (npm/fleet-queue.test.js).
+//
+// Auto-release fires only on the deterministic "owning VM left the fleet"
+// signal — a VM that is absent from the roster AND has no in-flight
+// provisioning job. The ambiguous "in roster but unreachable" case is
+// explicitly out of scope: a transient blip could trigger a spurious
+// release. That case is surfaced as a badge for the operator to act on.
+
+/** Decide whether the current queue head should be auto-released.
+ *
+ *  Conditions that must ALL hold:
+ *    1. The head entry's `vm` field is non-null (the machine name matched the
+ *       fleet's INSTANCE_PREFIX-…-<n> shape via vmFromMachine). An
+ *       unattributable head (vm===null) is never auto-released.
+ *    2. That VM number is absent from the live `vms` roster array.
+ *    3. There is no in-flight or queued provisioning job for that number
+ *       (guards the Add→addVm gap where a VM is being created but not yet
+ *       rostered). Also guards known-orphan VM numbers.
+ *
+ *  Returns { release: false } or { release: true, uuid, vm, reason }.
+ *  Pure; no I/O.
+ */
+function decideAutoReleaseGoneHead({ queue, vms, jobs, orphans }) {
+  const head = queue && queue[0];
+  if (!head || head.vm == null) return { release: false };
+  const n = head.vm;
+  if (vms.includes(n)) return { release: false };
+  const job = jobs[n];
+  const provisioning = job && (job.state === 'queued' || job.state === 'running')
+    && /add|cloud:up/.test(job.action || '');
+  if (provisioning || orphans[n]) return { release: false };
+  return { release: true, uuid: head.uuid, vm: n, reason: `owning VM-${n} left the fleet` };
+}
+
+module.exports = { decideAutoReleaseGoneHead };

package/npm/fleet-reconcile.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// npm/fleet-reconcile.js — pure reconciliation helpers for the fleet dashboard's
+// "unrostered VM" safety net (improve38). The dashboard lists running GCP
+// instances and surfaces any that aren't in the roster (provisioned out-of-band
+// — raw `gcloud`, or a `cloud:up` whose roster write failed). The gcloud I/O
+// lives in server.js (the untestable server shell); the pure parse + set
+// difference live here so they're unit-tested without invoking gcloud.
+
+// Parse `gcloud compute instances list --format='value(name)'` output into the
+// sorted, de-duped fleet VM numbers it names — instances whose name matches
+// `<prefix><n>`. Non-matching lines (other instances, blank lines, gcloud/SSH
+// warning noise) are ignored.
+function parseRunningFleetVms(stdout, prefix) {
+  const re = new RegExp(`^${String(prefix).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)$`);
+  const ns = String(stdout || '')
+    .split('\n')
+    .map((line) => {
+      const m = line.trim().match(re);
+      return m ? Number(m[1]) : null;
+    })
+    .filter((n) => n != null);
+  return [...new Set(ns)].sort((a, b) => a - b);
+}
+
+// Set difference: the `running` VM numbers that are NOT already accounted for in
+// `shown` (the roster plus any provisioning/orphan numbers already rendered as a
+// card). Returns a sorted, de-duped array — the numbers that need an Adopt card.
+function computeUnrostered(running, shown) {
+  const accounted = new Set(shown);
+  return [...new Set(running)]
+    .filter((n) => !accounted.has(n))
+    .sort((a, b) => a - b);
+}
+
+// Map a single degraded reason to the live health signal that resolves it.
+// Returns true only when that signal now passes; a reason with no mapped signal
+// returns false (retained — a genuine config problem, never a false-green).
+// Start with the two observed classes (improve41); extend the table as new
+// degraded reasons gain a corresponding live signal.
+function reasonClearedByHealth(reason, { reachableServing, authed }) {
+  const r = String(reason || '');
+  if (/claude auth|claude\.json|login/i.test(r)) return authed;
+  if (/container|never came up|provisioning failed/i.test(r)) return reachableServing;
+  return false;
+}
+
+// Given a terminal add-job badge and the VM's live health, return the corrected
+// badge — or null when nothing changes. Conservative by construction: clears a
+// degraded reason only when its live health signal now passes; flips a bare
+// `error` add to `done` when the VM is reachable + serving; leaves any reason
+// with no health signal intact (no false-green). The poll loop supplies the live
+// facts (I/O at the edge) and applies the result; the verdict itself is pure.
+//   job:    { state: 'done'|'error', degraded, degradedReasons }
+//   health: { reachable, editorHttpOk, providerAuthState }
+//   → null | { state, degraded, degradedReasons, transition }
+function reconcileTerminalAddBadge({ job, health } = {}) {
+  if (!job || !health) return null;
+  const reachableServing = !!(health.reachable && health.editorHttpOk);
+  const authed = health.providerAuthState === 'authenticated';
+
+  // Bare `error` add (no degraded reasons): flip to `done` once the VM is
+  // reachable + serving — the VM3 case (a manual `cloud:up` recovered the editor
+  // outside the dashboard's view).
+  if (job.state === 'error') {
+    const reasons = job.degradedReasons || [];
+    if (reasons.length === 0 && reachableServing) {
+      return { state: 'done', degraded: false, degradedReasons: [], transition: 'error→done (editor 200)' };
+    }
+    return null;
+  }
+
+  // Terminal `done` that is degraded: clear each reason whose live signal now
+  // passes; retain the rest. Drop `degraded` only when no reasons remain.
+  if (job.state === 'done' && job.degraded) {
+    const reasons = job.degradedReasons || [];
+    const remaining = reasons.filter((reason) => !reasonClearedByHealth(reason, { reachableServing, authed }));
+    if (remaining.length === reasons.length) return null; // nothing cleared → no-op
+    const cleared = reasons.length - remaining.length;
+    return {
+      state: 'done',
+      degraded: remaining.length > 0,
+      degradedReasons: remaining,
+      transition: remaining.length > 0
+        ? `degraded: cleared ${cleared} reason(s), ${remaining.length} remain`
+        : 'degraded→clear (health restored)',
+    };
+  }
+
+  return null;
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered, reconcileTerminalAddBadge };