@yagni-app/code-staging 1.1.1-staging.1352.1 → 1.1.1-staging.1355.1

package/README.md

@@ -23,6 +23,9 @@ correct, autonomous work than a coding agent that starts blank.
 npm install -g @yagni-app/code
 ```
 
+Requires Node.js 22.19 or newer (`node --version`); an older Node stops at
+launch with an upgrade message instead of crashing mid-session.
+
 The command it installs is `yagni`:
 
 ```bash

package/dist/bin.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * yagni — the published bin entry.
+ *
+ * Deliberately tiny: the only static imports are the dependency-free Node
+ * version gate and the (equally dependency-free) distribution record that
+ * names the installed channel. Everything else (`cli.js` and the module graph
+ * behind it) is loaded dynamically AFTER the check passes, so an old Node
+ * prints one clear message and exits instead of blowing up inside a
+ * dependency — or failing to parse one. `cli.js` stays directly runnable
+ * (`node dist/cli.js`) for the e2e lanes; its own entrypoint guard is false
+ * when this shim is argv[1], so the shim calls `runAsEntrypoint()` explicitly.
+ *
+ * Both failure paths set `process.exitCode` and return instead of calling
+ * `process.exit()`: stderr on a pipe is asynchronous on Windows, and an
+ * immediate exit can truncate the very diagnostic this shim exists to print.
+ * Letting the event loop drain flushes it.
+ *
+ * Behavioral coverage lives in `test/bin.test.ts`, which spawns this file
+ * under a faked-old `process.versions.node` and against a stub launcher that
+ * fails to load.
+ */
+import { DISTRIBUTION } from "./distribution.js";
+import { nodeCheckSkipped, nodeVersionProblem } from "./nodeVersion.js";
+function debugEnabled() {
+    const value = process.env.YAGNI_DEBUG;
+    return value !== undefined && value !== "" && value !== "0";
+}
+async function main() {
+    const problem = nodeCheckSkipped() ? null : nodeVersionProblem(process.versions.node, DISTRIBUTION);
+    if (problem !== null) {
+        process.stderr.write(`${problem}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    // A launcher that fails to LOAD (corrupt or partial install, a dependency
+    // missing from node_modules) would otherwise die as a raw unhandled
+    // rejection before the launcher's crash handlers exist — the same opaque
+    // failure this shim is here to prevent. No crash report is possible at this
+    // point (the reporter is part of what failed to load), so say what to do
+    // instead. The message carries the error class and message; YAGNI_DEBUG=1
+    // adds the full stack (resolution chain, parse location) for a support thread.
+    let launcher;
+    try {
+        launcher = await import("./cli.js");
+    }
+    catch (err) {
+        const name = err instanceof Error && err.name ? err.name : "Error";
+        const message = err instanceof Error ? err.message : String(err);
+        const lines = [
+            `${DISTRIBUTION.displayName} failed to load: ${name}: ${message}`,
+            "",
+            "The install looks incomplete or corrupt. Reinstall it:",
+            "",
+            `  npm install -g ${DISTRIBUTION.packageName}`,
+            "",
+        ];
+        if (debugEnabled()) {
+            const stack = err instanceof Error && err.stack ? err.stack : "(no stack)";
+            const cause = err instanceof Error && err.cause !== undefined ? `\ncause: ${String(err.cause)}` : "";
+            lines.push(`${stack}${cause}`, "");
+        }
+        else {
+            lines.push("(YAGNI_DEBUG=1 prints the full stack.)", "");
+        }
+        process.stderr.write(lines.join("\n"));
+        process.exitCode = 1;
+        return;
+    }
+    launcher.runAsEntrypoint();
+}
+await main();
+//# sourceMappingURL=bin.js.map

package/dist/cli.d.ts

@@ -166,5 +166,11 @@ export declare function main(argv: string[]): Promise<number>;
  * test import (argv[1] points at the test runner) does not.
  */
 export declare function isEntrypoint(argv1: string | undefined, moduleUrl: string): boolean;
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export declare function runAsEntrypoint(): void;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -889,9 +889,12 @@ export function isEntrypoint(argv1, moduleUrl) {
     };
     return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
 }
-// Only auto-run when invoked as the CLI entry, so tests can import this module
-// (e.g. to exercise wantsHelp) without spawning the agent.
-if (isEntrypoint(process.argv[1], import.meta.url)) {
+/**
+ * Run the launcher as the process entrypoint. Called by the published bin
+ * shim (`bin.js`, after the Node version gate) and by the guard below when
+ * this module is executed directly (`node dist/cli.js`, the e2e lanes).
+ */
+export function runAsEntrypoint() {
     // Crash reporting for the LAUNCHER process only (pi runs as a child and the
     // extension covers the session side). Fire-and-forget, sanitized, bounded;
     // YAGNI_DISABLE_CRASH_REPORTS=1 turns it off. Registered before main() so a
@@ -904,4 +907,9 @@ if (isEntrypoint(process.argv[1], import.meta.url)) {
         process.exit(1);
     });
 }
+// Only auto-run when invoked as the CLI entry, so tests can import this module
+// (e.g. to exercise wantsHelp) without spawning the agent.
+if (isEntrypoint(process.argv[1], import.meta.url)) {
+    runAsEntrypoint();
+}
 //# sourceMappingURL=cli.js.map

package/dist/crashReport.d.ts

@@ -77,6 +77,13 @@ export interface SanitizedCrash {
  * payloads…) are never touched.
  */
 export declare function sanitizeCrashError(err: unknown, opts?: SanitizeCrashOptions): SanitizedCrash;
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 export type CrashClient = "cli" | "desktop" | "desktop-driver";
 export interface CrashReportInput {
     client: CrashClient;

package/dist/crashReport.js

@@ -177,6 +177,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version. The runtime is a first-class crash cause
+ * (an old Node dies inside undici on `zlib.createZstdDecompress`), and it
+ * rides the existing `platform` field so the backend and its Sentry tag need
+ * no change. Mirrored in `pi-extension-yagni/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Sanitize + POST one crash report from pre-extracted fields. Resolves on
  * every outcome — timeout, network error, non-2xx, disabled — and never
@@ -199,7 +208,7 @@ export async function sendCrashReport(input) {
         const payload = {
             client: input.client,
             clientVersion: input.clientVersion,
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             errorClass: sanitizeCrashText(input.errorClass, opts).slice(0, MAX_CRASH_ERROR_CLASS),
             message: sanitizeCrashText(input.message, opts).slice(0, MAX_CRASH_MESSAGE),
             ...(stack !== undefined ? { stack } : {}),

package/dist/doctor.d.ts

@@ -50,6 +50,13 @@ export type BackendProbe = {
 } | {
     kind: "network";
 };
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export declare function checkNodeVersion(version: string): CheckResult;
 export declare function checkPiEngine(probe: PiEngineProbe): CheckResult;
 export declare function checkExtension(probe: ExtensionProbe): CheckResult;
 export declare function checkProfileToken(profile: Pick<Profile, "name" | "token">): CheckResult;
@@ -115,6 +122,8 @@ export declare function buildDoctorReport(checks: CheckResult[]): DoctorReport;
 export declare function formatDoctorReport(report: DoctorReport): string;
 export interface DoctorDeps {
     now?: () => number;
+    /** Running Node version (defaults to process.versions.node). */
+    nodeVersion?: string;
     probePiEngine?: () => PiEngineProbe;
     probeExtension?: () => ExtensionProbe;
     readActiveProfile?: () => Promise<Profile>;

package/dist/doctor.js

@@ -21,7 +21,27 @@ import { otelChildEnv, resolveOtelLaunchWithWorkspace } from "./otel.js";
 import { resolveExtensionPath, resolvePiCliPath, resolvePiPackageDir, resolveTelemetryProbePath } from "./paths.js";
 import { readActiveProfile } from "./profiles.js";
 import { resolveMcpConfigPath } from "./mcpCommand.js";
+import { MIN_NODE_VERSION, nodeVersionSatisfies } from "./nodeVersion.js";
 // ── Pure check builders ─────────────────────────────────────────────────────
+/**
+ * The Node floor, first in the list because every other check is moot
+ * without it: an old Node dies inside pi's HTTP client mid-request (Sentry
+ * YAGNI-BACKEND-4S: `zlib.createZstdDecompress is not a function`). The bin
+ * shim refuses to launch below the floor; doctor explains it in the same terms.
+ */
+export function checkNodeVersion(version) {
+    const shown = version.startsWith("v") ? version : `v${version}`;
+    if (!nodeVersionSatisfies(version, MIN_NODE_VERSION)) {
+        return {
+            name: "node",
+            status: "fail",
+            detail: `${shown} is older than the ${MIN_NODE_VERSION} floor`,
+            hint: "upgrade Node.js (https://nodejs.org or `nvm install 22`); older Node crashes mid-request on missing zlib APIs",
+            required: true,
+        };
+    }
+    return { name: "node", status: "ok", detail: `${shown} (needs ${MIN_NODE_VERSION}+)`, required: true };
+}
 export function checkPiEngine(probe) {
     if (!probe.binPath || !probe.binExists) {
         return {
@@ -512,6 +532,7 @@ export async function gatherChecks(deps = {}) {
     const probeBash = deps.probeBash ?? (() => bashOnWindowsDefault());
     const probeLatestVersion = deps.probeLatestVersion ?? (() => fetchLatestVersion());
     const checks = [];
+    checks.push(checkNodeVersion(deps.nodeVersion ?? process.versions.node));
     checks.push(checkPiEngine(probePiEngine()));
     checks.push(checkExtension(probeExtension()));
     // win32 only, and skipped means NOT SHOWN: on macOS/Linux there is nothing

package/dist/extension/crashReport.d.ts

@@ -72,6 +72,13 @@ export interface CrashReporterOpts {
     timeoutMs?: number;
 }
 export type CrashReporter = (error: unknown, context?: string, repoRoot?: string) => Promise<void>;
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export declare function platformLabel(): string;
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell

package/dist/extension/crashReport.js

@@ -145,6 +145,15 @@ export function sanitizeCrashError(err, opts = {}) {
         ...(cappedStack !== undefined ? { stack: cappedStack } : {}),
     };
 }
+/**
+ * OS, arch AND the Node version: the runtime is a first-class crash cause (an
+ * old Node dies inside undici on `zlib.createZstdDecompress`), and it rides
+ * the existing `platform` field so the backend and its Sentry tag need no
+ * change. Mirrored in `yagni-code-cli/src/crashReport.ts`.
+ */
+export function platformLabel() {
+    return `${process.platform} ${process.arch} node ${process.version}`;
+}
 /**
  * Build the fail-soft reporter. The extension runs inside pi's process, so
  * the client label follows the surface: `desktop` under the desktop shell
@@ -163,7 +172,7 @@ export function makeCrashReporter(opts) {
             const payload = {
                 client: isDesktopSurface() ? "desktop" : "cli",
                 clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-                platform: `${process.platform} ${process.arch}`,
+                platform: platformLabel(),
                 ...sanitized,
                 ...(context !== undefined ? { context } : {}),
                 timestamp: new Date().toISOString(),
@@ -234,7 +243,7 @@ export function reportFatalCrash(error, opts, context) {
         const payload = {
             client: isDesktopSurface() ? "desktop" : "cli",
             clientVersion: env.YAGNI_CODE_VERSION?.trim() || "unknown",
-            platform: `${process.platform} ${process.arch}`,
+            platform: platformLabel(),
             ...sanitized,
             ...(context !== undefined ? { context } : {}),
             timestamp: new Date().toISOString(),

package/dist/nodeVersion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Node.js floor gate.
+ *
+ * `engines.node` in package.json is advisory: npm prints an EBADENGINE
+ * warning on a global install and carries on, so a machine running an older
+ * Node ends up with a working `yagni` command that dies deep inside a
+ * dependency instead of failing cleanly. The first real report (Sentry
+ * YAGNI-BACKEND-4S, 2026-09-09) was pi's bundled undici 8 calling
+ * `zlib.createZstdDecompress` — added in Node 22.15 — the moment the backend
+ * answered a request with `content-encoding: zstd`. Node's own default fatal
+ * printer showed an undici stack trace, and nothing said "your Node is too
+ * old".
+ *
+ * `MIN_NODE_VERSION` mirrors `engines.node` (the manifest test pins the two
+ * together). This module is imported by `bin.ts` BEFORE anything else loads,
+ * so it must stay dependency-free and use only syntax every Node this could
+ * plausibly run under can parse.
+ */
+export declare const MIN_NODE_VERSION = "22.19.0";
+/**
+ * Escape hatch for the preflight (`YAGNI_SKIP_NODE_CHECK=1`). Same
+ * truthiness rule as the other switches: set and not "" / "0".
+ */
+export declare const NODE_CHECK_SKIP_ENV = "YAGNI_SKIP_NODE_CHECK";
+export declare function nodeCheckSkipped(env?: NodeJS.ProcessEnv): boolean;
+/** `"v22.19.0"` / `"22.19.0-nightly..."` → `[22, 19, 0]`; anything else → null. */
+export declare function parseNodeVersion(raw: string): [number, number, number] | null;
+/**
+ * Whether `actual` meets the floor. An unparseable version passes: the gate
+ * exists to stop a KNOWN-old Node with a clear message, never to lock out a
+ * runtime whose version string we merely failed to read.
+ */
+export declare function nodeVersionSatisfies(actual: string, min?: string): boolean;
+/**
+ * The names the message speaks in. The same shim ships on two channels
+ * (`@yagni-app/code` as `yagni`, `@yagni-app/code-staging` as
+ * `yagni-staging`), so the caller passes the installed distribution
+ * (`distribution.ts` owns the names; a `CodeDistribution` satisfies this
+ * shape) rather than this module keeping a copy that could drift.
+ */
+export interface NodeGateNames {
+    packageName: string;
+    commandName: string;
+    displayName: string;
+}
+/**
+ * The user-facing explanation when the floor is not met, or null when it is.
+ * Names the symptom the gate prevents so someone who already hit the crash
+ * recognizes it, and spells out the nvm gotcha (global packages live per
+ * Node version there, so the CLI needs a reinstall after switching).
+ */
+export declare function nodeVersionProblem(actual: string, names: NodeGateNames, min?: string): string | null;
+//# sourceMappingURL=nodeVersion.d.ts.map

package/dist/nodeVersion.js

@@ -0,0 +1,79 @@
+/**
+ * The Node.js floor gate.
+ *
+ * `engines.node` in package.json is advisory: npm prints an EBADENGINE
+ * warning on a global install and carries on, so a machine running an older
+ * Node ends up with a working `yagni` command that dies deep inside a
+ * dependency instead of failing cleanly. The first real report (Sentry
+ * YAGNI-BACKEND-4S, 2026-09-09) was pi's bundled undici 8 calling
+ * `zlib.createZstdDecompress` — added in Node 22.15 — the moment the backend
+ * answered a request with `content-encoding: zstd`. Node's own default fatal
+ * printer showed an undici stack trace, and nothing said "your Node is too
+ * old".
+ *
+ * `MIN_NODE_VERSION` mirrors `engines.node` (the manifest test pins the two
+ * together). This module is imported by `bin.ts` BEFORE anything else loads,
+ * so it must stay dependency-free and use only syntax every Node this could
+ * plausibly run under can parse.
+ */
+export const MIN_NODE_VERSION = "22.19.0";
+/**
+ * Escape hatch for the preflight (`YAGNI_SKIP_NODE_CHECK=1`). Same
+ * truthiness rule as the other switches: set and not "" / "0".
+ */
+export const NODE_CHECK_SKIP_ENV = "YAGNI_SKIP_NODE_CHECK";
+export function nodeCheckSkipped(env = process.env) {
+    const value = env[NODE_CHECK_SKIP_ENV];
+    return value !== undefined && value !== "" && value !== "0";
+}
+/** `"v22.19.0"` / `"22.19.0-nightly..."` → `[22, 19, 0]`; anything else → null. */
+export function parseNodeVersion(raw) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(raw.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/**
+ * Whether `actual` meets the floor. An unparseable version passes: the gate
+ * exists to stop a KNOWN-old Node with a clear message, never to lock out a
+ * runtime whose version string we merely failed to read.
+ */
+export function nodeVersionSatisfies(actual, min = MIN_NODE_VERSION) {
+    const a = parseNodeVersion(actual);
+    const b = parseNodeVersion(min);
+    if (!a || !b)
+        return true;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] > b[i];
+    }
+    return true;
+}
+/**
+ * The user-facing explanation when the floor is not met, or null when it is.
+ * Names the symptom the gate prevents so someone who already hit the crash
+ * recognizes it, and spells out the nvm gotcha (global packages live per
+ * Node version there, so the CLI needs a reinstall after switching).
+ */
+export function nodeVersionProblem(actual, names, min = MIN_NODE_VERSION) {
+    if (nodeVersionSatisfies(actual, min))
+        return null;
+    const shown = actual.startsWith("v") ? actual : `v${actual}`;
+    return [
+        `${names.displayName} needs Node.js ${min} or newer, but this is Node ${shown}.`,
+        "",
+        "Older Node is missing APIs the agent's HTTP client relies on (zstd",
+        "decompression, for one), so a session would crash mid-request with an",
+        'error like "zlib.createZstdDecompress is not a function" instead of',
+        "failing cleanly.",
+        "",
+        "Upgrade Node (https://nodejs.org, or `nvm install 22 && nvm use 22`),",
+        `then run \`${names.commandName}\` again. If your Node comes from nvm, reinstall the CLI`,
+        "afterwards so it lives under the new version:",
+        "",
+        `  npm install -g ${names.packageName}`,
+        "",
+        `(${NODE_CHECK_SKIP_ENV}=1 bypasses this check at your own risk.)`,
+    ].join("\n");
+}
+//# sourceMappingURL=nodeVersion.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.1-staging.1352.1",
+  "version": "1.1.1-staging.1355.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -25,7 +25,7 @@
     "node": ">=22.19.0"
   },
   "bin": {
-    "yagni-staging": "dist/cli.js"
+    "yagni-staging": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "1a93f050375804c9206e4660c812aebbb1ec338a"
+  "yagniSourceSha": "e319781c1b81806a857f6a846d15b7e9ace2447e"
 }