@codeyam-editor/codeyam-editor 0.1.5 → 0.1.6

package/npm/codesign-plan.js

@@ -0,0 +1,68 @@
+"use strict";
+// Pure helpers for scripts/package-mcpb.js's darwin code-signing step.
+//
+// Dependency-free and unit-tested (npm/codesign-plan.test.js) so the packaging
+// script keeps the sign decision + argv rendering out of its execSync path:
+// signDarwinBinary stays thin boundary glue while every branch of "do we sign,
+// and with which command" is exercised here without invoking codesign.
+
+/**
+ * The `codesign` argv for a Developer ID signature with a secure timestamp.
+ * Pure — takes the identity and binary path, returns the flag list. `--force`
+ * replaces cargo's ad-hoc signature (codesign refuses an already-signed binary
+ * otherwise); `--timestamp` embeds the secure timestamp a later notarization
+ * needs.
+ */
+function codesignArgs(identity, binaryPath) {
+  return ["--force", "--timestamp", "--sign", identity, binaryPath];
+}
+
+/**
+ * The shell-quoted `codesign …` command string for signing `binaryPath` with
+ * `identity`. Pure: quotes each argv element so a path or identity with spaces
+ * survives the shell.
+ */
+function codesignCommand(identity, binaryPath) {
+  const quoted = codesignArgs(identity, binaryPath)
+    .map((a) => `"${a}"`)
+    .join(" ");
+  return `codesign ${quoted}`;
+}
+
+/**
+ * Decide whether/how to sign the staged darwin binary, given the target
+ * `platform`, the configured Developer ID `identity`, the `hostPlatform`
+ * (process.platform), and a `serverLabel` for the warning text. Pure — no I/O,
+ * no env, no clock — so the decision and its warnings are unit-testable.
+ *
+ * Returns `{ action: "sign", identity }` when a real Developer ID signature is
+ * possible, otherwise `{ action: "skip", warning? }`: the non-darwin target is a
+ * silent skip (its binary is not Mach-O), while a missing identity or a
+ * non-macOS host skips WITH a warning so an unsigned local bundle stays testable
+ * on the machine that built it rather than failing the build.
+ */
+function signPlan({ platform, identity, hostPlatform, serverLabel }) {
+  if (platform !== "darwin") {
+    return { action: "skip" };
+  }
+  if (!identity) {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  ${serverLabel} is ad-hoc signed — set MCPB_SIGN_IDENTITY (or ` +
+        `APPLE_SIGNING_IDENTITY) to a Developer ID identity to sign it. An unsigned ` +
+        `binary has no stable Keychain identity and re-prompts for access.`,
+    };
+  }
+  if (hostPlatform !== "darwin") {
+    return {
+      action: "skip",
+      warning:
+        `⚠️  cannot codesign ${serverLabel} on ${hostPlatform} — ` +
+        `sign the darwin binary on a macOS host.`,
+    };
+  }
+  return { action: "sign", identity };
+}
+
+module.exports = { codesignArgs, codesignCommand, signPlan };

package/npm/empty-project-dir.js

@@ -1,13 +1,14 @@
 "use strict";
 
 /**
- * Launcher-side mirror of `is_empty_project_dir` in
+ * Launcher-side mirrors of `is_empty_project_dir` and
+ * `looks_like_onboardable_project` in
  * `crates/codeyam-editor/src/commands/init.rs`. The Rust side decides
- * which `/codeyam-…` skill the init binary points at; this JS mirror
- * decides the same for the launcher's post-launch tail banner. Keep
- * both in sync — the test `empty-project-dir.test.js` and Rust's
- * `is_empty_project_dir_ignores_hidden_entries` /
- * `is_empty_project_dir_detects_visible_entry` pin the contract.
+ * which `/codeyam-…` skill the init binary points at; these JS mirrors
+ * decide the same for the launcher's post-launch tail banner. Keep both
+ * predicates in sync with Rust — the test `empty-project-dir.test.js`
+ * and Rust's `is_empty_project_dir_*` / `looks_like_onboardable_project_*`
+ * tests pin the contracts.
  *
  * A "fresh" project directory has no non-hidden entries — only things
  * like `.git/`, `.gitignore`, or other dotfiles. Hidden entries don't
@@ -19,6 +20,7 @@
  */
 
 const fs = require("node:fs");
+const path = require("node:path");
 
 function isEmptyProjectDir(projectDir) {
   let entries;
@@ -30,4 +32,87 @@ function isEmptyProjectDir(projectDir) {
   return entries.every((name) => name.startsWith("."));
 }
 
-module.exports = { isEmptyProjectDir };
+// Root files that signal a real project: dependency/build manifests,
+// lockfiles, and the static-site `index.html`. Mirror of the Rust
+// `MANIFEST_MARKERS` list.
+const MANIFEST_MARKERS = new Set([
+  "package.json",
+  "Cargo.toml",
+  "pyproject.toml",
+  "requirements.txt",
+  "setup.py",
+  "go.mod",
+  "Gemfile",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "composer.json",
+  "pubspec.yaml",
+  "Package.swift",
+  "mix.exs",
+  "deno.json",
+  "CMakeLists.txt",
+  "Makefile",
+  "tsconfig.json",
+  "index.html",
+]);
+
+// Subdirectories that signal an organized source tree. Mirror of the Rust
+// `SOURCE_DIR_MARKERS` list.
+const SOURCE_DIR_MARKERS = new Set([
+  "src",
+  "app",
+  "lib",
+  "pages",
+  "components",
+  "crates",
+  "packages",
+  "source",
+  "include",
+]);
+
+/**
+ * Does this directory contain a *project* worth onboarding, as opposed to
+ * being empty or holding only a stray file or two? Mirror of Rust
+ * `looks_like_onboardable_project`. A folder "contains a project" when it
+ * holds a recognized manifest / lockfile, a `.csproj` / `.xcodeproj`, a root
+ * `index.html`, OR an organized source subdirectory. Intentionally
+ * marker-based, not file-count based: a home dir full of loose files is still
+ * not a project. A read error returns false (not a project → the
+ * auto-init/open path), matching Rust's `Err(_) => false`.
+ */
+function looksLikeOnboardableProject(projectDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(projectDir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    const name = entry.name;
+    if (MANIFEST_MARKERS.has(name)) {
+      return true;
+    }
+    if (name.endsWith(".csproj") || name.endsWith(".xcodeproj")) {
+      return true;
+    }
+    // Source-tree markers only count as directories, not like-named files.
+    if (SOURCE_DIR_MARKERS.has(name)) {
+      let isDir = entry.isDirectory();
+      // A symlinked source dir surfaces as a symlink Dirent; resolve it.
+      if (!isDir && entry.isSymbolicLink()) {
+        try {
+          isDir = fs.statSync(path.join(projectDir, name)).isDirectory();
+        } catch {
+          isDir = false;
+        }
+      }
+      if (isDir) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = { isEmptyProjectDir, looksLikeOnboardableProject };

package/npm/fleet-add-failure.js

@@ -0,0 +1,252 @@
+'use strict';
+
+const fc = require('./fleet-cleanup');
+const { parseRosterMarkers } = require('./fleet-early-roster');
+
+// npm/fleet-add-failure.js — pure classifier for a FAILED fleet-dashboard `add`
+// provision. Before this, every failed add rendered an identical red "add error"
+// badge whose only action was "Clear badge", and a restart mid-add collapsed the
+// message to a content-free `(re-attached after restart — detached provision
+// exited 1)`. The real cause — captured to the provision transcript on disk — was
+// thrown away. This happened live with VM9/VM10: both aborted at the streamed-
+// script drift guard because a bootstrap script had uncommitted local edits, but
+// the operator saw only "exited 1" and had to dig through /tmp/dash-add-vm-N.log.
+//
+// classifyAddFailure turns a transcript tail + exit code into a differentiated,
+// ACTIONABLE verdict: a plain-language headline, a concrete recovery instruction,
+// and — crucially — a `retryable` flag that is true ONLY where a one-click retry
+// provably cannot orphan or duplicate a GCP box: either nothing was provisioned,
+// or the remaining work is re-entrant so the retry converges on the existing VM.
+// Both grounds are spelled out on ADD_FAILURE_RETRYABLE below. The decision logic
+// lives here as a pure module (like fleet-job-badge.js::canClearBadge) so the
+// whole failure matrix is unit-tested without a live VM; server.js is the thin
+// I/O shell that gathers the transcript and turns the verdict into a card + a
+// server-re-guarded retry action.
+
+// The SINGLE source of truth for which categories are safe to auto-retry.
+// `retryable` on every returned verdict is stamped from this Set, so the
+// invariant `retryable === has(category)` holds by construction and the server
+// can re-guard a retry against the same Set.
+//
+// A category earns membership on EITHER of two grounds — both of which
+// guarantee a one-click retry cannot silently orphan or duplicate a GCP box:
+//
+//   1. NOTHING WAS PROVISIONED. The classifier can prove no cloud resource was
+//      created (`preflight-drift` aborts before the first gcloud call;
+//      `instance-vanished` confirms the instance is gone). Retry starts clean.
+//
+//   2. THE REMAINING WORK IS RE-ENTRANT. A real VM exists, but every step the
+//      retry would re-run is skip-on-exists or re-attaching, so the retry
+//      CONVERGES on the existing box instead of building a second one.
+//      `project-bootstrap-timeout` is this shape: the VM is up and its detached
+//      bootstrap is still running, `ensureInstance` reuses the live instance,
+//      `ensureBootstrapped` skips on the present image, and
+//      `ensureProjectBootstrapped` re-attaches to the in-flight install rather
+//      than starting a second `npm install` over the first.
+//
+// Ground 2 is deliberately narrow — it is NOT "the VM probably still works".
+// `container-stuck` and `incomplete-workspace` also leave a live VM, but their
+// remaining work is NOT provably re-entrant, so they stay non-retryable.
+const ADD_FAILURE_RETRYABLE = new Set([
+  'preflight-drift',
+  'instance-vanished',
+  'project-bootstrap-timeout',
+]);
+
+// Collect the `    - <path>` bullets the drift guard prints AFTER the "following
+// files differ" header (see npm/cloud.js), stopping at the first non-bullet line
+// so an unrelated "- " elsewhere in the transcript can't leak in. Returns [] when
+// no drift block is present.
+function extractDriftFiles(logTail) {
+  const lines = String(logTail || '').split('\n');
+  const files = [];
+  let inBlock = false;
+  for (const line of lines) {
+    if (!inBlock) {
+      if (/following files differ/i.test(line)) inBlock = true;
+      continue;
+    }
+    const m = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (m) { files.push(m[1]); continue; }
+    break; // first non-bullet after the header ends the block
+  }
+  return files;
+}
+
+// Pure transform: the last `maxLines` non-empty lines of a transcript, each
+// right-trimmed. Extracted from readProvisionTail (server.js) so the aggregation
+// is unit-tested and that function stays a thin filesystem-boundary call. Returns
+// '' for empty/whitespace-only input.
+function lastNonEmptyLines(text, maxLines = 50) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((l) => l.replace(/\s+$/, ''))
+    .filter((l) => l.length > 0)
+    .slice(-maxLines);
+  return lines.join('\n');
+}
+
+// True iff the provision transcript reached the early-roster marker (`CY_ROSTER
+// <n>`) — i.e. the instance exists and the container gate passed, so the VM is
+// rostered. Reuses parseRosterMarkers (npm/fleet-early-roster.js) so the
+// `CY_ROSTER` grammar has a single owner rather than a second inlined regex. Any
+// valid marker means "rostered"; the specific VM number is irrelevant here — a
+// provision transcript only ever carries its own VM's marker. Never throws.
+function transcriptRostered(logTail) {
+  return parseRosterMarkers(String(logTail || '')).length > 0;
+}
+
+// Build a verdict, stamping `retryable` from the single-source-of-truth Set so it
+// can never drift from the category.
+function buildFailureVerdict(category, headline, recovery, extra) {
+  const out = { category, headline, recovery, retryable: ADD_FAILURE_RETRYABLE.has(category) };
+  if (extra && extra.files) out.files = extra.files;
+  return out;
+}
+
+// Classify a failed add from its transcript tail + exit code.
+//
+//   logTail   the last lines of the provision transcript (string; '' when the
+//             log was unreadable — must never throw)
+//   exitCode  the provision's exit code (number; used for signal-kill detection)
+//
+// Returns { category, headline, recovery, retryable, files? }.
+//
+// Detection is ORDER-SENSITIVE. The provision shell echoes cloud:up's tail, so a
+// drift / instance-vanished / container-stuck transcript ALSO contains the
+// generic `cloud:up FAILED (exit N)` line. Each specific (and every retryable)
+// signature is therefore tested BEFORE the generic cloud-up-failed signature, or
+// a retryable drift would misclassify as a non-retryable cloud:up failure and the
+// operator would lose the safe one-click recovery.
+function classifyAddFailure({ logTail, exitCode } = {}) {
+  const log = String(logTail || '');
+
+  // 1. preflight-drift — the streamed-script drift guard aborted BEFORE any
+  //    gcloud call, so nothing was provisioned. Retryable once the file is fixed.
+  //    We match the unambiguous abort header / verdict label, NOT the bare
+  //    `CODEYAM_SKIP_SCRIPT_DRIFT_CHECK` token: that token ALSO appears in the
+  //    "bypass active — skipping drift check" warning, so keying on it would
+  //    misclassify a bypass-active add that later failed for a real reason as a
+  //    (retryable!) drift — inviting an unsafe retry. The header below is printed
+  //    only on a genuine drift abort.
+  if (/Streamed scripts carry unreviewed local content/i.test(log)
+      || /UNCOMMITTED LOCAL EDITS/.test(log)) {
+    const files = extractDriftFiles(log);
+    const fileList = files.length ? files.join(', ') : 'the streamed scripts';
+    const fix = files.length
+      ? `Commit & push them, or discard with \`git checkout -- ${files.join(' ')}\`, then Retry add.`
+      : 'Commit & push them, or discard the local edits, then Retry add.';
+    return buildFailureVerdict('preflight-drift', 'Blocked by local edits',
+      `Uncommitted local edits in ${fileList} tripped the streamed-script drift guard, which aborts before any cloud resource is created. ${fix}`,
+      { files });
+  }
+
+  // 2. instance-vanished — the GCP instance is confirmed gone; nothing to orphan.
+  if (/instance .* is gone/i.test(log)) {
+    return buildFailureVerdict('instance-vanished', 'Instance never came up',
+      'The GCP instance is gone — provisioning failed before the container started, so nothing was left behind. Retrying the add is safe.');
+  }
+
+  // 3. project-bootstrap-timeout — the VM came up and its DETACHED project
+  //    bootstrap is still running; we merely stopped waiting on it. This is the
+  //    VM-8 / six-self-host-VM incident: a heavy `npm install` (a ~293 MB
+  //    playwright postinstall, a large `git clone`) outran a local budget, the
+  //    SIGTERM'd gcloud child returned `status: null`, and the abort path read
+  //    that as a broken bootstrap script and DELETED A COMPLETELY HEALTHY VM.
+  //
+  //    Retryable on re-entrancy grounds (see ADD_FAILURE_RETRYABLE): the retry
+  //    re-attaches to the in-flight install rather than starting a second one.
+  //    Tested BEFORE cloud-up-failed because the provision shell echoes cloud:up's
+  //    tail, so this transcript ALSO carries the generic `cloud:up FAILED (exit N)`
+  //    line — matching that first would strip the safe recovery and steer the
+  //    operator to destroy a healthy, still-provisioning VM. The signature is the
+  //    wording ensureProjectBootstrapped (npm/cloud.js) throws for both its
+  //    overall-deadline and its launch-budget timeouts.
+  if (/project bootstrap exceeded the local/i.test(log)) {
+    return buildFailureVerdict('project-bootstrap-timeout', 'Still installing — we stopped waiting',
+      'The VM provisioned fine and its project bootstrap is still running on it; only the local wait budget elapsed. Nothing is broken and nothing was left half-built. Retry the add to re-attach to the running install — each bootstrap step is skip-on-exists. Do NOT destroy this VM.');
+  }
+
+  // 4. container-stuck — the instance exists but the editor container never
+  //    became healthy, so a half-provisioned box may exist. Not retryable.
+  if (/container never came up/i.test(log)) {
+    return buildFailureVerdict('container-stuck', 'Container never became healthy',
+      'The instance came up but the editor container never became healthy — it may be half-provisioned. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 5. incomplete-workspace — the container came up but the project was never
+  //    scaffolded: no `.codeyam/editor.json` exists under ~/projects on the VM,
+  //    so the greenfield `init` did not complete onboarding. This is specific
+  //    and more actionable than the generic cloud-up-failed below, so it is
+  //    tested first. The VM exists and is half-provisioned, so it is NOT
+  //    auto-retryable — reconcile finishes the scaffold, then re-add.
+  if (/no \.codeyam\/editor\.json found under ~\/projects/i.test(log)) {
+    return buildFailureVerdict('incomplete-workspace', 'Workspace never scaffolded',
+      'The container came up but the project was never scaffolded (no .codeyam/editor.json on the VM), so provisioning did not finish onboarding. Reconcile this VM to complete the scaffold, then re-add.');
+  }
+
+  // 6. cloud-up-failed — a generic cloud:up failure, reached ONLY when the drift /
+  //    vanished / stuck signatures above did not match. A partial instance may
+  //    exist, so not retryable.
+  if (/cloud:up FAILED \(exit/i.test(log)) {
+    return buildFailureVerdict('cloud-up-failed', 'Provisioning failed',
+      'cloud:up failed during provisioning, so a partial instance may exist. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 7. interrupted — a signal kill (OOM 137, SIGTERM 143, …) or an explicit
+  //    Killed / out-of-memory marker. The real VM state is unknown. Not retryable.
+  if (fc.isSignalKillExit(Number(exitCode)) || /\bKilled\b/.test(log) || /Out of memory/i.test(log)) {
+    return buildFailureVerdict('interrupted', 'Provisioning interrupted',
+      'The provision was interrupted (killed or out of memory), so the VM state is unknown. Reconcile or destroy this VM before re-adding.');
+  }
+
+  // 8. converging — the add reached the early-roster marker (`CY_ROSTER`): the
+  //    container gate passed, the instance is real, and the VM is rostered, yet it
+  //    exited non-zero WITHOUT matching any specific hard-failure signature above.
+  //    By construction of the provision script, every genuine hard failure (drift,
+  //    instance-vanished, container-stuck, incomplete-workspace, cloud-up-failed,
+  //    interrupted) is printed BEFORE `CY_ROSTER`, so a rostered transcript that
+  //    fell through to here is a still-wiring box owned by the detached
+  //    wire-add-tail / reconcile-ingress — NOT an add failure. Surface it as an
+  //    honest in-flight state instead of the scary red `unknown`. Not retryable:
+  //    the VM exists and its detached wiring owns finishing it, so a one-click
+  //    retry could duplicate/orphan a live box. Tested LAST so a hard-failure
+  //    signature (all printed pre-roster) always wins — `converging` can never
+  //    shadow a proven failure.
+  if (transcriptRostered(log)) {
+    return buildFailureVerdict('converging', 'Add still converging',
+      'The container is up and the VM is rostered; the LB ingress is still wiring in the background. This resolves on its own once the editor is reachable over the LB — no action needed unless it persists past the wiring deadline.');
+  }
+
+  // 9. unknown — fallback. Never invite an unproven retry.
+  return buildFailureVerdict('unknown', 'Add failed',
+    'The add failed for an unclassified reason — inspect the transcript below, then reconcile or destroy this VM before re-adding.');
+}
+
+// Pure guard for the operator "Retry add" action: given a VM number and its
+// carried job, decide whether a one-click retry is SAFE. Retry is allowed ONLY
+// for a terminal add-error whose classifier verdict is retryable (a category
+// where nothing was provisioned). Returns { ok, reason } — reason is a stable
+// code the server shell (actionRetryAdd) maps to an operator message. Mirrors
+// fleet-job-badge.js::canClearBadge so the handler stays a thin I/O shell and the
+// safety decision is unit-tested without a live dashboard.
+function canRetryAdd({ n, job } = {}) {
+  if (!Number.isInteger(n) || n < 1) return { ok: false, reason: 'invalid-vm' };
+  if (!job || job.action !== 'add' || job.state !== 'error') return { ok: false, reason: 'no-failed-add' };
+  if (!job.retryable) return { ok: false, reason: 'not-retryable' };
+  return { ok: true, reason: null };
+}
+
+// Pure badge-hold predicate for deriveStatus (server.js): hold the calm in-flight
+// `add-converging` card — instead of the red add-failed — ONLY when the add was
+// classified `converging` AND its detached first-wiring is still in flight. Once
+// the wire-add-tail fails/deadlines (`addTailFailed`) or is gone (`addTailInflight`
+// false), or the category is anything else, return false so the caller falls
+// through to the red add-failed status — the operator-chosen escalation. Kept pure
+// (like canRetryAdd / canClearBadge) so the badge decision is unit-tested without a
+// live dashboard.
+function holdConvergingBadge({ category, addTailInflight, addTailFailed } = {}) {
+  return category === 'converging' && !!addTailInflight && !addTailFailed;
+}
+
+module.exports = { classifyAddFailure, extractDriftFiles, lastNonEmptyLines, canRetryAdd, transcriptRostered, holdConvergingBadge, ADD_FAILURE_RETRYABLE };

package/npm/fleet-asset-version.js

@@ -0,0 +1,37 @@
+'use strict';
+// Pure content-hash UI versioning for the fleet dashboard's cache-busting
+// (vm: Honest VM Card Display + Dashboard Cache-Busting).
+//
+// The dashboard serves its single-file UI (public/index.html) with `no-store`,
+// so a hard-refresh always fetches the new code — but an already-OPEN tab never
+// refetches the HTML and silently runs the pre-restart UI until the operator
+// manually reloads. To fix that, the server stamps a short content hash of the
+// served HTML into every /data response; the client records the version it
+// booted with and `location.reload()`s on a mismatch, so a dashboard restart
+// with new UI reaches an open tab automatically.
+//
+// This module is the PURE half — a deterministic hash of the HTML string, no
+// I/O — mirroring the pure/impure split the other fleet-* modules follow
+// (server.js owns reading the file; this owns turning bytes into a version).
+// Unit-tested in npm/fleet-asset-version.test.js.
+//
+// Stack note: this is fleet-operator dashboard infrastructure (the GCE fleet
+// that runs codeyam-editor itself). A project that never runs the dashboard
+// never reaches it.
+const crypto = require('crypto');
+
+// computeAssetVersion returns a stable, short (12 hex chars) fingerprint of the
+// served UI. Same HTML in ⇒ same version out (so an unchanged deploy never
+// spuriously reloads open tabs); any byte change ⇒ a different version (so a
+// real UI change always reloads them). 12 hex chars of SHA-1 is ample to make
+// an accidental collision between two distinct UI builds negligible while
+// keeping the badge short.
+function computeAssetVersion(html) {
+  return crypto
+    .createHash('sha1')
+    .update(String(html == null ? '' : html))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+module.exports = { computeAssetVersion };