@cruxy/cli 1.6.0 → 1.7.1

package/dist/tui/restore.js

@@ -0,0 +1,137 @@
+/**
+ * The terminal-restore backstop (Q4 track 1).
+ *
+ * `TuiRenderer.close()` hands the terminal back — it erases the frame, and from
+ * track 3 on it also leaves the alternate screen and shows the cursor again.
+ * That covers exactly one way a run ends: the orderly one. Every other way, the
+ * process dies with the shell still painted and the terminal still configured
+ * the way the TUI left it, and the user's next prompt lands in the middle of a
+ * frame that nothing will ever erase. `kill -TERM`, a hangup when the terminal
+ * window closes, an `ssh` session dropping, `kill -INT` from another pane — all
+ * of them terminate the process by DEFAULT DISPOSITION, which runs no JavaScript
+ * at all.
+ *
+ * So the restore is registered with the process rather than left to the caller:
+ *
+ * - **`SIGINT` / `SIGTERM` / `SIGHUP`** — restore, then exit with the shell's
+ *   conventional 128 + signal code. `process.exit` rather than re-raising is
+ *   deliberate: Node restores the original termios (`ResetStdio`, an `atexit`
+ *   hook) on a normal exit but not when the default disposition fells the
+ *   process, and the TUI holds stdin in RAW MODE for most of its life. Dying
+ *   from the signal itself would leave a terminal with no echo and no line
+ *   editing — a worse outcome than the painted frame this module exists to
+ *   clean up.
+ * - **`exit`** — the last line, for the paths no signal handler sees: an
+ *   uncaught throw, an explicit `process.exit` somewhere else, and the signal
+ *   handlers that other modules install first ({@link ../utils/child-tree.js}
+ *   registers `SIGINT` too, and whichever ran first calls `process.exit`
+ *   straight away). Synchronous work only, which a write to a TTY is.
+ *
+ * Handlers are installed on the FIRST registration and removed when the last
+ * guard goes away, so a closed TUI leaves the process exactly as it found it and
+ * N renderers (a test file builds dozens) still cost one listener per event.
+ * This is the same shape as the child-process exit backstop in
+ * {@link ../utils/child-tree.js}, for the same reason.
+ */
+/** Signals that end a run before the normal teardown gets a turn. */
+export const RESTORE_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * The exit code a shell reports for a process felled by each signal: 128 + n.
+ * Stated rather than inherited, because these handlers exit explicitly (see the
+ * raw-mode note above) and an exit code of 0 after a `kill -TERM` would tell
+ * every script that reads one that the run succeeded.
+ */
+export const SIGNAL_EXIT_CODES = {
+    SIGINT: 130,
+    SIGTERM: 143,
+    SIGHUP: 129,
+};
+/** Live guards, in registration order. Each entry is its own idempotent runner. */
+const guards = new Set();
+/** The installed listeners, or null when no guard is registered. */
+let handlers = null;
+/**
+ * Run every registered restore, once each. Exported because it IS what the
+ * handlers run: a test that calls this is testing the real path rather than a
+ * reimplementation of it.
+ *
+ * Iterates a copy — a restore deregisters itself as it runs — and a restore
+ * that throws does not stop the others. There is nowhere to report an error
+ * from here (the process is on its way out, and the screen is the thing that
+ * would show it), and one guard failing must not leave the next one's terminal
+ * in the alternate screen forever.
+ */
+export function restoreAllScreens() {
+    for (const run of [...guards])
+        run();
+}
+function installHandlers(host) {
+    if (handlers !== null)
+        return;
+    const entries = [
+        ["exit", restoreAllScreens],
+        ...RESTORE_SIGNALS.map((signal) => [
+            signal,
+            () => {
+                restoreAllScreens();
+                host.exit(SIGNAL_EXIT_CODES[signal]);
+            },
+        ]),
+    ];
+    for (const [event, listener] of entries)
+        host.on(event, listener);
+    handlers = { host, entries };
+}
+function removeHandlers() {
+    if (handlers === null)
+        return;
+    for (const [event, listener] of handlers.entries) {
+        handlers.host.off(event, listener);
+    }
+    handlers = null;
+}
+/**
+ * Register `restore` to run if the process is signalled or exits, and return the
+ * handle that also lets the owner run it directly.
+ *
+ * The first registration installs the handlers; the last one to go removes
+ * them. `host` is read only on that first call — it names the process the
+ * handlers are installed on, and there is only ever one.
+ */
+export function installScreenGuard(restore, host = process) {
+    let restored = false;
+    let live = true;
+    const deregister = () => {
+        if (!live)
+            return;
+        live = false;
+        guards.delete(run);
+        if (guards.size === 0)
+            removeHandlers();
+    };
+    const run = () => {
+        if (restored)
+            return;
+        restored = true;
+        // Deregistered BEFORE the restore runs, so a throwing restore still gives
+        // the handlers up rather than pinning them for the life of the process.
+        deregister();
+        try {
+            restore();
+        }
+        catch {
+            // See `restoreAllScreens`: there is no surface left to report on.
+        }
+    };
+    guards.add(run);
+    installHandlers(host);
+    return {
+        restoreScreen: run,
+        restored: () => restored,
+        dispose: deregister,
+    };
+}
+/** Guards currently registered — for tests, the way `trackedTreeCount` is. */
+export function screenGuardCount() {
+    return guards.size;
+}

package/dist/tui/supports.js

@@ -1,3 +1,4 @@
+import { isSet } from "../render/capabilities.js";
 /**
  * Whether the environment can host the full-viewport TUI.
  *
@@ -18,3 +19,24 @@
 export function supportsTui(caps) {
     return caps.interactive && !caps.screenReader;
 }
+/**
+ * Whether the TUI runs on the ALTERNATE SCREEN (Q4 track 3) — the terminal's
+ * second buffer, the one `less` and `vim` use.
+ *
+ * Gated on {@link supportsTui} and nothing new: a terminal that cannot host the
+ * shell has no business being switched to another buffer, and the two questions
+ * have exactly one answer between them. Adding a second capability check here
+ * would only create a state where the TUI runs but its screen management does
+ * not — which is the drift the one gate exists to prevent.
+ *
+ * `CRUXY_NO_ALT_SCREEN` opts out, following the same set-and-non-empty rule as
+ * every other cruxy flag. The opt-out exists because the alternate screen is not
+ * universally available or wanted: multiplexers and terminal emulators can be
+ * configured to refuse it, some capture-and-replay tooling reads only the normal
+ * buffer, and a user who prefers the shell to keep the frame in its scrollback
+ * should not have to stop using the TUI to get that. Opting out changes nothing
+ * else — the shell, the row addressing and the restore backstop are unaffected.
+ */
+export function usesAltScreen(caps, env = process.env) {
+    return supportsTui(caps) && !isSet(env.CRUXY_NO_ALT_SCREEN);
+}

package/dist/tui/tool-versions.js

@@ -1,4 +1,9 @@
 import { execFile } from "node:child_process";
+import path from "node:path";
+// The concrete module, not `lsp/index.js`: that barrel pulls in the transport,
+// the pool and the client, and this panel exists to keep cost off the startup
+// path. `resolveBinary` is a leaf over `node:fs`.
+import { resolveBinary } from "../lsp/registry.js";
 /**
  * Host tool versions for the rail (P4 track 5).
  *
@@ -20,9 +25,82 @@ import { execFile } from "node:child_process";
  * DAEMON and reports a stopped Docker as absent. This panel is reporting what
  * is INSTALLED, so it asks the client (`docker --version`), which answers with
  * the daemon down.
+ *
+ * WHICH tsc, though. The panel sits beside a repo, and the toolchain that
+ * matters there is the repo's: a project pinning TypeScript 5.4 in its
+ * devDependencies was being reported at whatever version happens to be global,
+ * or as "not found" when nothing is global at all — the ordinary case, since
+ * `pnpm`/`npx` run these out of `node_modules/.bin` and most people never
+ * install them globally. So each tool is looked for in `node_modules/.bin`,
+ * walking up from the working directory the way Node's own resolution does,
+ * before falling back to `PATH`.
+ *
+ * That lookup is {@link resolveBinary}, the LSP registry's — which also fixes a
+ * latent Windows bug this module had on the PATH half. Windows installs
+ * npm-shipped tools as `.cmd` shims, and `execFile("tsc")` there resolves
+ * nothing: `tsc.cmd` needs the `PATHEXT` sweep the registry already does by
+ * stat, and then needs `cmd.exe` to run it at all.
  */
 /** Hard ceiling on one probe; a hung binary must never wedge the panel. */
 const PROBE_TIMEOUT_MS = 5000;
+/**
+ * Every `node_modules/.bin` from `from` up to the filesystem root, nearest
+ * first — the same walk Node's module resolution does, and the same order
+ * `pnpm`/`npx` pick a binary in. Directories that do not exist cost nothing:
+ * `resolveBinary` stats the candidate and moves on.
+ */
+export function binDirsFrom(from) {
+    const dirs = [];
+    let dir = path.resolve(from);
+    for (;;) {
+        dirs.push(path.join(dir, "node_modules", ".bin"));
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return dirs;
+        dir = parent;
+    }
+}
+/**
+ * Where a probe should actually spawn `bin` from: the nearest project-local
+ * copy, else whatever `PATH` offers, else `null` — which is an ANSWER ("not
+ * installed"), reached without spawning anything.
+ */
+export function resolveToolBinary(bin, from) {
+    return resolveBinary(bin, binDirsFrom(from)) ?? resolveBinary(bin);
+}
+/**
+ * How to invoke a resolved binary.
+ *
+ * On win32 a `.cmd`/`.bat` is a script, not an image: `CreateProcess` cannot run
+ * one, and Node has REFUSED to try since the CVE-2024-27980 fix — it throws
+ * EINVAL rather than silently handing the arguments to a shell. So a shim is run
+ * through `cmd.exe` explicitly. Everything else is spawned directly, unchanged.
+ *
+ * THE DOUBLE WRAP IS NOT A TYPO, and it is the whole reason this is a named
+ * function with its own tests. cmd.exe strips the first and last quote of the
+ * `/c` string when the string both begins and ends with one. Quoting only the
+ * path gives `cmd /c "C:\Program Files\x\t.cmd"` — begins and ends with a quote,
+ * so cmd removes both and then tries to run `C:\Program`. Appending `--version`
+ * happens to hide it (the string no longer ends in a quote), which is the worst
+ * kind of working: it breaks the day a probe takes no arguments, and every tool
+ * here is one `args: []` away from that.
+ *
+ * Wrapping the whole command line in a second pair makes `/s` the rule instead
+ * of an accident: `/s` strips exactly the outer pair and preserves the rest
+ * verbatim, so the inner quotes reach the parser intact either way. Node must
+ * not re-quote on top, hence `windowsVerbatimArguments` at the spawn.
+ */
+export function invocationFor(file, args, platform = process.platform, comSpec = process.env.ComSpec ?? "cmd.exe") {
+    if (platform === "win32" && /\.(cmd|bat)$/i.test(file)) {
+        const line = [`"${file}"`, ...args].join(" ");
+        return {
+            file: comSpec,
+            args: ["/d", "/s", "/c", `"${line}"`],
+            verbatim: true,
+        };
+    }
+    return { file, args: [...args], verbatim: false };
+}
 /**
  * Pull a semantic version out of a tool's `--version` line.
  *
@@ -35,24 +113,47 @@ const PROBE_TIMEOUT_MS = 5000;
 export function parseVersion(output) {
     return /\d+\.\d+\.\d+(?:[-+][\w.]+)?/.exec(output)?.[0] ?? null;
 }
-/** Default probe: spawn, capture, and treat any failure as "not installed". */
-const spawnProbe = (bin, args) => new Promise((resolve) => {
-    try {
-        execFile(bin, [...args], { encoding: "utf8", timeout: PROBE_TIMEOUT_MS, windowsHide: true }, (err, stdout, stderr) => {
-            // Some tools print their version to stderr; a non-zero exit with a
-            // parseable version still tells us the tool is there.
-            const text = `${stdout ?? ""}${stderr ?? ""}`;
-            if (err && text.trim() === "")
-                resolve(null);
-            else
-                resolve(text);
-        });
-    }
-    catch {
-        // execFile can throw synchronously on a malformed binary path.
-        resolve(null);
-    }
-});
+/**
+ * The default probe: resolve, spawn, capture — and treat any failure as "not
+ * installed". Resolution comes first, so a tool that is nowhere costs a few
+ * `stat` calls rather than a process that has to fail.
+ *
+ * `from` exists so the win32 e2e can point a real probe at a real `.cmd` shim in
+ * a temp project. Left unset it reads `process.cwd()` PER CALL, never once at
+ * module load — the panel must follow the session's directory, not the one the
+ * process happened to start in.
+ */
+export function makeSpawnProbe(from) {
+    return (bin, args) => new Promise((resolve) => {
+        const resolved = resolveToolBinary(bin, from ?? process.cwd());
+        if (resolved === null) {
+            resolve(null);
+            return;
+        }
+        const call = invocationFor(resolved, args);
+        try {
+            execFile(call.file, call.args, {
+                encoding: "utf8",
+                timeout: PROBE_TIMEOUT_MS,
+                windowsHide: true,
+                ...(call.verbatim ? { windowsVerbatimArguments: true } : {}),
+            }, (err, stdout, stderr) => {
+                // Some tools print their version to stderr; a non-zero exit with a
+                // parseable version still tells us the tool is there.
+                const text = `${stdout ?? ""}${stderr ?? ""}`;
+                if (err && text.trim() === "")
+                    resolve(null);
+                else
+                    resolve(text);
+            });
+        }
+        catch {
+            // execFile can throw synchronously on a malformed binary path.
+            resolve(null);
+        }
+    });
+}
+const spawnProbe = makeSpawnProbe();
 /**
  * The tools reported, in display order.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
     "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.5.0"
+    "@cruxy/sdk": "0.6.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.11.1"