@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

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,36 @@
+'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);
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered };

package/npm/fleet-reset.js

@@ -0,0 +1,222 @@
+'use strict';
+// Pure bash-script builders for the fleet dashboard's RESET actions
+// (scripts/operator/fleet-dashboard/server.js requires this). String
+// construction only — no I/O, no gcloud/docker exec — so the reset *recipe*
+// (what the remote bash actually does) stays unit-testable in isolation
+// (npm/fleet-reset.test.js), exactly like launch-config.js / fleet-env.js.
+// The dispatch (gcloud ssh → docker exec → startJob) stays in server.js as
+// platform-glue; only the decision-bearing script shape lives here.
+
+// The `.codeyam` deep-clean preserve→pause→wipe→restore sequence, shared by every
+// reset that hard-cleans a /workspace. `git reset --hard` + `session-reset`
+// leave the git-IGNORED runtime state behind (workflow step files,
+// scenario-*.js, server-state, logs, caches), so we explicitly wipe and
+// restore the tracked `.codeyam`. Two gitignored files MUST survive the wipe:
+//   - editor.local.json — previewOrigin + the agent API key (a blind wipe
+//     breaks Live Preview + auth).
+//   - server-state.json — the running pid + control port the restart's verify
+//     reads.
+// Both are cp'd aside, `.codeyam` is wiped, restored from the branch (tracked,
+// e.g. self-host) or re-`init`'d (greenfield, where `.codeyam` is gitignored),
+// then the two files are copied back. Returned as step strings the caller
+// joins into its own `&&`-chain (the surrounding `( …; true )` guards keep each
+// best-effort cp from breaking the chain when a file is absent).
+//
+// First step: release any commit-queue entries this VM owns. The wipe
+// regenerates `.codeyam/run/queue-origin-id`, which would otherwise orphan
+// the prior session's entry (different origin_id, same machine — invisible
+// to the two-key adoption path until the next enqueue's same-machine guard
+// reaps it). Routing through `branch-queue release-mine` makes the
+// queue-side cleanup intentional and visible in the queue log instead.
+// Best-effort: a no-remote / queue-disabled project legitimately exits
+// non-zero, and we should not block the reset.
+//
+// Before the wipe we QUIESCE ALL WRITERS: park the editor server
+// (`stop-server --hold-for-restart`) AND stop the PTY broker
+// (`pty-broker stop`). Parking only the editor server is insufficient — the
+// broker is a SEPARATE process (and hooks / agent subprocesses can fire), so
+// it keeps re-creating `.codeyam/logs/` and `.codeyam/run/` between when the
+// wipe enumerates the dir and when it removes it. That race surfaced live
+// (VM-1, 2026-06-01) as `rm: cannot remove '.codeyam': Directory not empty`,
+// aborting the whole reset. Both quiesce calls are fail-soft `|| true` so a
+// server/broker that's already dead (e.g. the reset is rerun after a partial
+// failure) doesn't block the chain.
+//
+// The wipe itself is RETRY-RESILIENT instead of a single `rm -rf .codeyam`
+// that aborts the &&-chain on one transient re-creation: a bounded loop of
+// `find .codeyam -mindepth 1 -delete` empties the contents and tolerates a
+// brief re-create, then proceeds even if `.codeyam` is still non-empty after
+// best-effort (a soft retry, never a hard failure — `git checkout`/`init`
+// repopulates over whatever remains). Emptying contents (not removing the dir)
+// also sidesteps the `rmdir` race entirely.
+//
+// The destructive region (park → broker-stop → wipe → restore) is made
+// FAILURE-SAFE with an EXIT trap installed before the park and disarmed after
+// a successful restore. If ANY step in that region aborts the chain, the trap
+// still restores tracked `.codeyam` (or re-inits), copies the two preserved
+// infra files back, and runs `restart-server --force-in-container` before
+// exiting non-zero — so a failed deep-clean self-recovers to a working
+// (un-reset, but UP) VM instead of leaving it parked-and-down with a
+// half-wiped `.codeyam`, and still reports the failure. The happy path is
+// unchanged: the restore steps run, the trap is disarmed, and the caller's
+// own trailing `restart-server` resurrects the parked server.
+function codeyamDeepCleanSteps(E) {
+  // Restore primitives shared by the happy path and the trap recovery body.
+  const restoreCodeyam = `git checkout HEAD -- .codeyam 2>/dev/null || ${E} init`;
+  const restoreElj =
+    'test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json';
+  const restoreSs =
+    'test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json';
+  // Recovery body: restore .codeyam + the two infra backups, then resurrect the
+  // parked server. Runs ONLY on the failure path (the happy path's own restore
+  // steps remove the backups; recovery here intentionally leaves them in place
+  // because on a mid-region abort those steps never ran).
+  const recover =
+    `${restoreCodeyam}; ( ${restoreElj}; true ); ( ${restoreSs}; true ); ` +
+    `${E} editor restart-server --force-in-container || true`;
+  return [
+    `( ${E} editor branch-queue release-mine --yes 2>/dev/null; true )`,
+    '( cp .codeyam/editor.local.json /tmp/cy-elj.bak 2>/dev/null; true )',
+    '( cp .codeyam/server-state.json /tmp/cy-ss.bak 2>/dev/null; true )',
+    // A brace group (NOT a subshell) so the function + trap persist into the
+    // current shell where the rest of the &&-chain runs.
+    `{ __cy_recover() { ${recover}; }; trap '__cy_recover; exit 1' EXIT; }`,
+    `(${E} editor stop-server --hold-for-restart --force-in-container || true)`,
+    `(${E} editor pty-broker stop || true)`,
+    '( for i in 1 2 3 4 5; do find .codeyam -mindepth 1 -delete 2>/dev/null; [ -z "$(ls -A .codeyam 2>/dev/null)" ] && break; sleep 0.2; done; true )',
+    `( ${restoreCodeyam} )`,
+    `( ${restoreElj} && rm -f /tmp/cy-elj.bak; true )`,
+    `( ${restoreSs} && rm -f /tmp/cy-ss.bak; true )`,
+    // Restore succeeded — disarm the failure-safe trap so normal completion
+    // (and the caller's trailing session-reset + restart) doesn't re-trigger it.
+    'trap - EXIT',
+  ];
+}
+
+// Belt-and-suspenders broker-ensure, appended after the trailing
+// `restart-server` in every reset recipe. The PRIMARY fix lives in the
+// editor server's `ensure_broker_running`: it now `rm -f`s the stale
+// socket and retries the spawn, so the reexec'd `start` (which
+// restart-server triggers) reliably respawns the broker with no
+// down-window. This step is the safety net for an OLDER in-container
+// binary whose `restart-server` predates that fix — it mirrors the
+// vm-watchdog's recovery so a reset still ends broker-up regardless of
+// which binary is installed.
+//
+// Shape: status-gated and idempotent. `pty-broker status` exits non-zero
+// only when no broker is reachable; ONLY then does the `||` branch fire
+// (`rm -f` the stale socket — mirroring the watchdog — then `nohup` a
+// detached daemon). When a broker is already alive the status succeeds
+// and the respawn branch never runs, so a healthy broker is NEVER killed.
+// Wrapped in `( …; true )` so it can never break the reset's &&-chain
+// (a down broker that fails to respawn must not abort the rest of the
+// reset). The socket glob + `pty-broker daemon` invocation match the
+// watchdog (`scripts/operator/vm-watchdog.sh`) and the per-project
+// `$TMPDIR`/`/tmp` socket layout (`socket_path_for`).
+function codeyamBrokerEnsureStep(E) {
+  return (
+    `( ${E} editor pty-broker status >/dev/null 2>&1 || ` +
+    `( rm -f /tmp/codeyam-pty-broker-*.sock; ` +
+    `nohup ${E} editor pty-broker daemon </dev/null >/tmp/broker-spawn.log 2>&1 & disown ); ` +
+    'true )'
+  );
+}
+
+// Build the in-container bash for "Reset client" — hard-clean the CLIENT
+// project (/workspace) on ANY VM shape. The decisions encoded here:
+//   - Reset to HEAD, NOT origin: `git reset --hard` (bare) discards uncommitted
+//     churn but PRESERVES committed work. Advancing to origin tip is the
+//     separate "Update client" action — this must never `git fetch`/reset to
+//     `origin/<branch>`.
+//   - `git reset --hard` leaves untracked files, so node_modules + a per-VM
+//     .env survive (no forced re-install / lost secrets).
+//   - Stop the broker FIRST so abandoned agent WIP can't be re-written to disk
+//     mid-reset; drop a stale LOCAL credential.helper (fragility #29) so the
+//     re-seed + the agent's git ops fall back to the working system helper.
+//   - Re-seed the git credential cache AFTER the restart so the agent can
+//     pull/push immediately; the re-seed is a self-contained subshell whose
+//     own `|| echo` never masks an earlier &&-chain failure.
+// `E` is the in-container editor binary; `gitReseedBody` is the re-seed bash
+// body (passed in so this stays a pure function of its inputs).
+function resetClientScript({ E, gitReseedBody }) {
+  return [
+    'cd /workspace',
+    `command -v ${E} >/dev/null`,
+    'echo ">> [1/5] stopping agent session"',
+    `(${E} editor pty-broker stop || true)`,
+    '(git config --local --unset-all credential.helper || true)',
+    'echo ">> [2/5] discarding uncommitted changes (git reset --hard to HEAD; keeps committed work + untracked files)"',
+    'git reset --hard',
+    'echo ">> [3/5] deep-cleaning .codeyam (clears ignored runtime state; keeps editor.local.json + server-state.json)"',
+    ...codeyamDeepCleanSteps(E),
+    `${E} editor session-reset`,
+    'echo ">> [4/5] restarting server to respawn the broker (no rebuild)"',
+    `(${E} editor restart-server --force-in-container || true)`,
+    // Belt-and-suspenders: ensure a broker is live even on an older binary
+    // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
+    codeyamBrokerEnsureStep(E),
+    'echo ">> [5/5] re-seeding git credential cache"',
+    `( ( ${gitReseedBody} ) || echo "WARN git cache re-seed failed" )`,
+  ].join(' && ');
+}
+
+// Build the in-container bash for "Reset editor" — the editor-state recipe:
+// stop the agent, drop a stale local credential.helper, advance the VM's branch
+// to origin tip (skipped on a greenfield local-only repo), deep-clean .codeyam
+// (preserving editor.local.json + server-state.json via codeyamDeepCleanSteps),
+// run session-reset, and restart the server. This is the SAME &&-chain
+// previously inlined in actionResetEditorSource in scripts/operator/
+// fleet-dashboard/server.js — extracted so the standalone Reset editor action
+// AND the composite Update & Reset Everything action share one definition and
+// it gets unit-test coverage like the other reset builders.
+//
+// Binary-existence gate FIRST so a broken binary aborts BEFORE the destructive
+// `git reset --hard` / `rm -rf .codeyam`. The composite action relies on this
+// same gate as its safety contract — a failed rebuild that leaves no binary
+// will short-circuit the trailing recipe before any wipe happens.
+function resetEditorStateScript({ E }) {
+  return [
+    'cd /workspace',
+    `command -v ${E} >/dev/null`,
+    // Tolerate a missing broker: `pty-broker stop` exits non-zero when none is
+    // running; the subshell + `|| true` keeps it non-fatal without swallowing
+    // the binary-existence gate above.
+    'echo ">> [1/4] stopping agent session + clearing workflow state"',
+    `(${E} editor pty-broker stop || true)`,
+    // Drop a stale LOCAL credential.helper (fragility #29) so `git fetch` falls
+    // back to the working system helper. No-op when none is set.
+    '(git config --local --unset-all credential.helper || true)',
+    // Advance the VM's own branch to origin (skip on a greenfield local-only repo
+    // with no remote). fetch + `reset --hard origin/<branch>`, NOT `pull --ff-only`
+    // (which dies "Cannot fast-forward to multiple branches" on some VM states).
+    'if git remote | grep -qx origin; then ' +
+      'BR=$(git branch --show-current); ' +
+      'echo ">> [2/4] advancing source on $BR to origin tip"; ' +
+      'git reset --hard && git fetch origin "$BR" && git reset --hard "origin/$BR"; ' +
+    'else echo ">> [2/4] no origin remote (greenfield project) — skipping source advance"; fi',
+    // Deep-clean .codeyam: `git reset --hard` + session-reset leave git-IGNORED /
+    // untracked state (workflow + design-step state, server-state, logs, caches).
+    // Preserve editor.local.json (previewOrigin + agent API key — a blind wipe
+    // breaks Live Preview + auth) and server-state.json (runtime pid + control
+    // port the restart's verify reads), wipe .codeyam, restore it from the branch
+    // (tracked, e.g. self-host) or re-init (greenfield), then put both files back.
+    'echo ">> [3/4] deep-cleaning .codeyam (clears ignored state; keeps editor.local.json + server-state.json)"',
+    ...codeyamDeepCleanSteps(E),
+    `${E} editor session-reset`,
+    // No rebuild here (that's Rebuild binary). Restart the server in place to
+    // respawn the broker we stopped: restart-server SIGUSR1s pid 1 and the
+    // docker-exec returns cleanly, so `|| true` keeps a broker-down VM green.
+    'echo ">> [4/4] restarting server to respawn the broker (no rebuild)"',
+    `(${E} editor restart-server --force-in-container || true)`,
+    // Belt-and-suspenders: ensure a broker is live even on an older binary
+    // whose restart-server doesn't yet respawn it. Idempotent / status-gated.
+    codeyamBrokerEnsureStep(E),
+  ].join(' && ');
+}
+
+module.exports = {
+  codeyamDeepCleanSteps,
+  codeyamBrokerEnsureStep,
+  resetClientScript,
+  resetEditorStateScript,
+};

package/npm/fleet-roster.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// npm/fleet-roster.js — the fleet roster (`.codeyam/logs/fleet-vms.json`) is a
+// shared contract: the dashboard, the CLI provisioner (`cloud:up`), the
+// `cloud:branch-switch` orchestrator, the vm-watchdog, and the bash tunnel
+// publishers (`vm-urls.sh` / `cloudflared-monitor.sh`) all read it to learn
+// which VMs exist. Before improve38 the *writer* lived only inside the dashboard
+// process (`server.js::saveVmsState`), so a VM provisioned by the CLI never
+// appeared until someone hand-edited the file. This module is the single
+// read+write seam every Node consumer shares, so the writer is no longer locked
+// inside the dashboard.
+//
+// File format (unchanged): a JSON array of VM-number integers. Readers tolerate
+// a missing or malformed file by treating it as the empty roster.
+//
+// Env override: `VMS_STATE_FILE` relocates the file (honored by server.js and
+// cloud-branch-switch.js already); resolved once at module load.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+
+const VMS_STATE_FILE = process.env.VMS_STATE_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-vms.json');
+
+// Canonical roster shape: a sorted, de-duped set of integers. Every read and
+// write funnels through here so on-disk content stays normalized regardless of
+// which consumer last wrote it (or hand-edited it).
+function normalizeRoster(arr) {
+  return [...new Set((arr || []).filter(Number.isInteger))].sort((a, b) => a - b);
+}
+
+// Read the roster, returning a normalized integer array. A missing or malformed
+// file is treated as the empty roster `[]` (the documented contract the previous
+// `readRoster`/`loadVmsState` duplicates shared) so a truncated write or an
+// absent file never throws into a consumer's poll loop.
+function readRoster() {
+  try {
+    const data = JSON.parse(fs.readFileSync(VMS_STATE_FILE, 'utf8'));
+    if (Array.isArray(data)) return normalizeRoster(data);
+  } catch { /* missing or malformed — treated as empty */ }
+  return [];
+}
+
+// Persist `arr` as the roster, atomically: write a temp file then `rename` it
+// over the target so a concurrent reader never observes a half-written file.
+// The temp name carries the pid so two *processes* writing at once (CLI +
+// dashboard) don't clobber each other's temp file before their renames land.
+// Returns the normalized roster that was written.
+function writeRoster(arr) {
+  const next = normalizeRoster(arr);
+  fs.mkdirSync(path.dirname(VMS_STATE_FILE), { recursive: true });
+  const tmp = `${VMS_STATE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, VMS_STATE_FILE); // atomic replace
+  return next;
+}
+
+// Append `n` to the roster if absent (idempotent), returning the new roster.
+// A double-roster — e.g. the CLI rosters on `cloud:up` and the dashboard's Add
+// onSuccess rosters again — is a harmless no-op, which is exactly what closes
+// the race where one writer's roster write could fail.
+function addToRoster(n) {
+  return writeRoster([...readRoster(), n]);
+}
+
+// Remove `n` from the roster, returning the new roster. Removing an absent
+// entry is a no-op.
+function removeFromRoster(n) {
+  return writeRoster(readRoster().filter((x) => x !== n));
+}
+
+module.exports = {
+  VMS_STATE_FILE,
+  normalizeRoster,
+  readRoster,
+  writeRoster,
+  addToRoster,
+  removeFromRoster,
+};