heyspex 0.1.0 → 0.2.0

package/bin/spexcode.mjs

@@ -0,0 +1,262 @@
+#!/usr/bin/env node
+/**
+ * bin/spexcode.mjs — `spexcode`, the named PATH launcher for SpexCode
+ * (formerly SpexHarness — historical name only), HeySpex's own agent
+ * harness. Running `spexcode` opens a SpexCode session: it forwards to the
+ * chat front (`hs chat`, i.e. `bin/hs.mjs`'s `chat` verb dispatching to
+ * `spex-console/bin/hs-chat.ts`).
+ *
+ * Epic: [[HS-MSDL-8CMW-EPIC-spexcode-ships-as-a-named-path-launcher]]
+ * Research: [[HS-TJKO-8CMW-RES-spexcode-powershell-launcher-seat-model]]
+ *
+ * This file is a THIN forwarder plus a `--seat` guard — no chat-loop code,
+ * no model logic. Every real behavior lives in `hs chat`
+ * (spex-console/src/lib/cli/chat.ts, spexharness/src/chat/*.mjs).
+ *
+ * Two responsibilities, both pure-testable (see the exported functions
+ * below, exercised without spawning a real process or touching the real
+ * `dev-factory/seats.json`):
+ *
+ *  1. HS-FWTK — before forwarding, if `--seat <id>` / `--seat=<id>` is
+ *     present, refuse the seat when its `dev-factory/seats.json`
+ *     `fill.backends[]` has no entry whose `kind` is `SPEXCODE_BACKEND_KIND`
+ *     ("spexcode") — naming the seat and the exact registry entry to change
+ *     — and exit 2 without spawning anything.
+ *  2. HS-HF24 — otherwise, spawn `node bin/hs.mjs chat <...args>` with every
+ *     argument forwarded unchanged, `stdio: "inherit"`, SIGINT forwarded to
+ *     the child so its own graceful-shutdown path
+ *     (spexharness/src/chat/chat-sigint.mjs) runs, and exit with the
+ *     child's exit code (or 1 on a spawn error).
+ */
+import { spawn } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** `bin/hs.mjs`, resolved relative to THIS file (not the caller's cwd) so
+ *  `spexcode` works from any directory once it's on PATH. */
+const HS_PATH = path.join(__dirname, "hs.mjs");
+
+/** `dev-factory/seats.json`, resolved relative to this file's location
+ *  (`bin/` is one level under the repo root). */
+const SEATS_JSON_PATH = path.resolve(__dirname, "..", "dev-factory", "seats.json");
+
+/**
+ * The `fill.backends[].kind` string a seat must carry for `spexcode` to
+ * launch it. NOT one of the coarse categories already in use elsewhere in
+ * `seats.json` (`cloud-api`, `ide-session`, `local`, `human`, `routed`) —
+ * per research §"Seats & Backend Routing", "SpexCode is one more backend
+ * kind alongside Claude Code, Cursor, OpenCode, and CommandCode", so it gets
+ * its own kind value rather than overloading an existing category. The
+ * `coo-phase-1` seat's `fill.backends[]` carries a `"spexcode/hs-chat"`
+ * entry with this kind (see dev-factory/seats.json) so bare `spexcode` and
+ * `spexcode --seat coo-phase-1` are never refused.
+ */
+export const SPEXCODE_BACKEND_KIND = "spexcode";
+
+/** Every argument `spexcode` receives is forwarded unchanged to `hs chat`. */
+export function buildForwardArgs(argv) {
+  return ["chat", ...argv];
+}
+
+/**
+ * Parse `--seat X` or `--seat=X` out of argv. Returns `null` when no `--seat`
+ * flag is present (or `--seat` is the last token with no value — `hs chat`'s
+ * own parser reports that usage error once forwarded).
+ */
+export function parseSeatArg(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--seat") {
+      const value = argv[i + 1];
+      return value !== undefined ? value : null;
+    }
+    if (token.startsWith("--seat=")) {
+      return token.slice("--seat=".length);
+    }
+  }
+  return null;
+}
+
+/** Find a seat by id in a parsed `seats.json` object. `null` when absent. */
+export function findSeat(seatsRegistry, seatId) {
+  const seats = Array.isArray(seatsRegistry?.seats) ? seatsRegistry.seats : [];
+  return seats.find((seat) => seat && seat.id === seatId) ?? null;
+}
+
+/** True when `seat.fill.backends[]` has an entry with kind `"spexcode"`. */
+export function seatHasSpexCodeBackend(seat) {
+  const backends = Array.isArray(seat?.fill?.backends) ? seat.fill.backends : [];
+  return backends.some((backend) => backend && backend.kind === SPEXCODE_BACKEND_KIND);
+}
+
+/**
+ * Decide whether `argv` (as given to `spexcode`, before the `chat` verb is
+ * prepended) may forward to `hs chat`. Pure — takes the already-parsed
+ * `seats.json` object so tests never touch the filesystem.
+ *
+ * @param {readonly string[]} argv
+ * @param {{seats?: Array}} seatsRegistry
+ * @returns {{allowed: true} | {allowed: false, message: string}}
+ */
+export function resolveSeatGuard(argv, seatsRegistry) {
+  const seatId = parseSeatArg(argv);
+  if (seatId === null) return { allowed: true };
+
+  const seat = findSeat(seatsRegistry, seatId);
+  if (seat && seatHasSpexCodeBackend(seat)) {
+    return { allowed: true };
+  }
+
+  const reason = seat
+    ? `has no fill.backends[] entry with kind "${SPEXCODE_BACKEND_KIND}"`
+    : "is not a known seat in dev-factory/seats.json";
+
+  return {
+    allowed: false,
+    message:
+      `spexcode: refusing --seat "${seatId}" — seat "${seatId}" ${reason}. ` +
+      `Fix: add a backend with kind "${SPEXCODE_BACKEND_KIND}" to dev-factory/seats.json's ` +
+      `seats[${seatId}].fill.backends (see the "coo-phase-1" seat's "spexcode/hs-chat" entry ` +
+      `for an example), then retry. Nothing was started.`,
+  };
+}
+
+/** Load + JSON.parse `dev-factory/seats.json`. Isolated so tests can stub it. */
+export function loadSeatsRegistry(seatsJsonPath = SEATS_JSON_PATH) {
+  return JSON.parse(readFileSync(seatsJsonPath, "utf8"));
+}
+
+/**
+ * Spawn `node hs.mjs chat <...argv>`, inheriting stdio, forwarding SIGINT to
+ * the child so its own graceful-shutdown path runs, and resolving with the
+ * child's exit code (or `1` on a spawn error or an unclean signal exit).
+ * `spawnFn` is injectable so tests never spawn a real process.
+ *
+ * @param {readonly string[]} argv
+ * @param {{hsPath?: string, spawnFn?: typeof spawn}} [opts]
+ * @returns {Promise<number>}
+ */
+export function runForward(argv, { hsPath = HS_PATH, spawnFn = spawn } = {}) {
+  return new Promise((resolve) => {
+    const child = spawnFn(process.execPath, [hsPath, ...buildForwardArgs(argv)], {
+      stdio: "inherit",
+      shell: false,
+    });
+
+    const forwardSigint = () => {
+      child.kill("SIGINT");
+    };
+    process.on("SIGINT", forwardSigint);
+
+    const cleanup = () => {
+      process.removeListener("SIGINT", forwardSigint);
+    };
+
+    child.on("error", () => {
+      cleanup();
+      resolve(1);
+    });
+
+    child.on("exit", (code, signal) => {
+      cleanup();
+      if (typeof code === "number") {
+        resolve(code);
+        return;
+      }
+      resolve(signal ? 1 : 0);
+    });
+  });
+}
+
+/**
+ * The full orchestration — seat guard, then forward — with every dependency
+ * injectable so tests exercise it end to end without touching the real
+ * filesystem or spawning a real process.
+ *
+ * @param {readonly string[]} argv
+ * @param {{spawnFn?: typeof spawn, hsPath?: string, loadRegistry?: typeof loadSeatsRegistry, stderr?: {write: Function}}} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runSpexcode(argv, deps = {}) {
+  const {
+    spawnFn = spawn,
+    hsPath = HS_PATH,
+    loadRegistry = loadSeatsRegistry,
+    stderr = process.stderr,
+  } = deps;
+
+  const seatId = parseSeatArg(argv);
+  if (seatId !== null) {
+    let registry;
+    try {
+      registry = loadRegistry();
+    } catch (err) {
+      stderr.write(
+        `spexcode: could not read dev-factory/seats.json to check --seat "${seatId}": ` +
+          `${err && err.message ? err.message : err}\n`,
+      );
+      return 2;
+    }
+
+    const guard = resolveSeatGuard(argv, registry);
+    if (!guard.allowed) {
+      stderr.write(guard.message + "\n");
+      return 2;
+    }
+  }
+
+  return runForward(argv, { hsPath, spawnFn });
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  process.exitCode = await runSpexcode(argv);
+}
+
+/**
+ * Same fix as bin/hs.mjs's `isSameFile`/`isMain` ([[HS-561M]]): a naive
+ * `pathToFileURL(process.argv[1]).href === import.meta.url` idiom breaks
+ * under `npm link`. The global shim invokes
+ * `node "<npm-prefix>/node_modules/heyspex/bin/spexcode.mjs"`; that path is
+ * a symlink (npm link's install shape), and Node's default module
+ * resolution realpaths it for `import.meta.url` but leaves `process.argv[1]`
+ * as the ORIGINAL (symlinked) path the shim passed. The two never match,
+ * `isMain` comes out false, and the globally-installed `spexcode` silently
+ * prints nothing and exits 0 for every invocation. Fix: realpath BOTH sides
+ * before comparing (case-insensitively on Windows, where drive-letter casing
+ * can differ between how a shim built the path and how realpath reports it).
+ */
+function isSameFile(a, b) {
+  const normalize = (p) => {
+    let real;
+    try {
+      real = realpathSync.native(p);
+    } catch {
+      real = path.resolve(p);
+    }
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  };
+  return normalize(a) === normalize(b);
+}
+
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    if (isSameFile(process.argv[1], fileURLToPath(import.meta.url))) return true;
+  } catch {
+    // fall through to the basename fallback below
+  }
+  // Belt-and-suspenders fallback for install shapes realpath can't reconcile:
+  // recognize this file by its own known bin name rather than failing closed
+  // into silent no-output.
+  const base = path.basename(process.argv[1]).toLowerCase();
+  return base === "spexcode.mjs" || base === "spexcode";
+})();
+
+if (isMain) {
+  main();
+}