wotann 0.5.91 → 0.5.92

package/dist/cli/npx-self-update-hint.d.ts

@@ -0,0 +1,60 @@
+/**
+ * npx-self-update-hint — one-line nudge at startup when a wotann
+ * binary is running from the `~/.npm/_npx/<hash>/` cache AND a newer
+ * version is published on the npm registry.
+ *
+ * Background: `npx wotann` caches packages by name-hash for ~7 days.
+ * When wotann ships a new version, users on the cached older copy
+ * silently miss the fix until either (a) the cache expires, (b) they
+ * `npx --yes -p wotann@latest wotann`, or (c) they install globally.
+ * This module surfaces the upgrade path BEFORE the TUI mounts so the
+ * stale-cache failure mode is self-explanatory.
+ *
+ * Design: pure functions where possible, dependency-injected network +
+ * stderr for tests, short timeout (~1.5 s) so a slow registry never
+ * blocks startup, swallow all errors (a hint is best-effort, never a
+ * gate). Skip in CI/non-interactive contexts.
+ */
+export interface NpxUpdateHintOptions {
+    readonly currentVersion: string;
+    /** `__dirname` of the wotann install — used to detect npx cache path. */
+    readonly currentDirname: string;
+    /** Override the registry fetch (tests). */
+    readonly fetchLatest?: (timeoutMs: number) => Promise<string | null>;
+    /** Override the output sink (tests). */
+    readonly stderr?: {
+        write(s: string): unknown;
+    };
+    /** Maximum time to wait for the registry call. */
+    readonly timeoutMs?: number;
+    /** Skip the hint entirely when CI=true (default: true). */
+    readonly skipInCI?: boolean;
+    /** Skip when env signals non-interactive (default: true). */
+    readonly skipNonInteractive?: boolean;
+}
+/**
+ * True iff the given directory path is inside an npm npx cache slot
+ * (`~/.npm/_npx/<hash>/` on POSIX, `npm-cache\_npx\<hash>` on Windows).
+ */
+export declare function isRunningFromNpxCache(dirname: string): boolean;
+/**
+ * Returns `1` if `a > b`, `-1` if `a < b`, `0` if equal. Stable for
+ * unequal-length segments (treats missing trailers as 0).
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * GET https://registry.npmjs.org/wotann/latest with a hard timeout.
+ * Returns the published version string, or `null` on any failure
+ * (network error, non-JSON response, timeout, missing version field).
+ * Never throws.
+ */
+export declare function fetchLatestWotannVersion(timeoutMs: number): Promise<string | null>;
+/**
+ * Run the full hint sequence: detect cache path → fetch latest →
+ * compare → optionally print. Never blocks longer than `timeoutMs`,
+ * never throws, never gates the rest of the startup.
+ *
+ * Returns the printed hint string (for tests) or `null` if no hint
+ * was printed.
+ */
+export declare function printNpxUpgradeHint(opts: NpxUpdateHintOptions): Promise<string | null>;

package/dist/cli/npx-self-update-hint.js

@@ -0,0 +1,145 @@
+/**
+ * npx-self-update-hint — one-line nudge at startup when a wotann
+ * binary is running from the `~/.npm/_npx/<hash>/` cache AND a newer
+ * version is published on the npm registry.
+ *
+ * Background: `npx wotann` caches packages by name-hash for ~7 days.
+ * When wotann ships a new version, users on the cached older copy
+ * silently miss the fix until either (a) the cache expires, (b) they
+ * `npx --yes -p wotann@latest wotann`, or (c) they install globally.
+ * This module surfaces the upgrade path BEFORE the TUI mounts so the
+ * stale-cache failure mode is self-explanatory.
+ *
+ * Design: pure functions where possible, dependency-injected network +
+ * stderr for tests, short timeout (~1.5 s) so a slow registry never
+ * blocks startup, swallow all errors (a hint is best-effort, never a
+ * gate). Skip in CI/non-interactive contexts.
+ */
+import { request as httpsRequest } from "node:https";
+/**
+ * True iff the given directory path is inside an npm npx cache slot
+ * (`~/.npm/_npx/<hash>/` on POSIX, `npm-cache\_npx\<hash>` on Windows).
+ */
+export function isRunningFromNpxCache(dirname) {
+    const normalized = dirname.replace(/\\/g, "/");
+    return normalized.includes("/.npm/_npx/") || normalized.includes("/npm-cache/_npx/");
+}
+/**
+ * Parse a dot-separated semver-ish version into numeric segments.
+ * Non-numeric trailers (e.g. "-rc.1") are dropped — npm registry
+ * "latest" tag points at stable releases so leading numeric segments
+ * are enough for the "is current older than latest?" decision.
+ */
+function parseNumericVersionPrefix(v) {
+    const trimmed = v.trim();
+    const head = trimmed.split(/[-+]/)[0] ?? trimmed;
+    return head.split(".").map((s) => {
+        const n = Number.parseInt(s, 10);
+        return Number.isFinite(n) ? n : 0;
+    });
+}
+/**
+ * Returns `1` if `a > b`, `-1` if `a < b`, `0` if equal. Stable for
+ * unequal-length segments (treats missing trailers as 0).
+ */
+export function compareVersions(a, b) {
+    const A = parseNumericVersionPrefix(a);
+    const B = parseNumericVersionPrefix(b);
+    const len = Math.max(A.length, B.length);
+    for (let i = 0; i < len; i++) {
+        const x = A[i] ?? 0;
+        const y = B[i] ?? 0;
+        if (x > y)
+            return 1;
+        if (x < y)
+            return -1;
+    }
+    return 0;
+}
+/**
+ * GET https://registry.npmjs.org/wotann/latest with a hard timeout.
+ * Returns the published version string, or `null` on any failure
+ * (network error, non-JSON response, timeout, missing version field).
+ * Never throws.
+ */
+export function fetchLatestWotannVersion(timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(v);
+        };
+        const req = httpsRequest({
+            host: "registry.npmjs.org",
+            path: "/wotann/latest",
+            method: "GET",
+            headers: { "user-agent": "wotann-startup-check", accept: "application/json" },
+        }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                finish(null);
+                return;
+            }
+            const chunks = [];
+            res.on("data", (c) => chunks.push(c));
+            res.on("end", () => {
+                try {
+                    const body = Buffer.concat(chunks).toString("utf-8");
+                    const parsed = JSON.parse(body);
+                    finish(typeof parsed.version === "string" ? parsed.version : null);
+                }
+                catch {
+                    finish(null);
+                }
+            });
+            res.on("error", () => finish(null));
+        });
+        req.on("error", () => finish(null));
+        req.setTimeout(timeoutMs, () => {
+            req.destroy();
+            finish(null);
+        });
+        req.end();
+    });
+}
+const HINT_LINE = (current, latest) => `[wotann] You're running v${current} from the npx cache; v${latest} is available. ` +
+    `Refresh with: npx --yes -p wotann@latest wotann\n`;
+/**
+ * Run the full hint sequence: detect cache path → fetch latest →
+ * compare → optionally print. Never blocks longer than `timeoutMs`,
+ * never throws, never gates the rest of the startup.
+ *
+ * Returns the printed hint string (for tests) or `null` if no hint
+ * was printed.
+ */
+export async function printNpxUpgradeHint(opts) {
+    if ((opts.skipInCI ?? true) && process.env["CI"] === "true")
+        return null;
+    if ((opts.skipNonInteractive ?? true) && !process.stdout.isTTY)
+        return null;
+    if (!isRunningFromNpxCache(opts.currentDirname))
+        return null;
+    const fetcher = opts.fetchLatest ?? fetchLatestWotannVersion;
+    let latest;
+    try {
+        latest = await fetcher(opts.timeoutMs ?? 1500);
+    }
+    catch {
+        return null;
+    }
+    if (latest === null)
+        return null;
+    if (compareVersions(opts.currentVersion, latest) >= 0)
+        return null;
+    const sink = opts.stderr ?? process.stderr;
+    const line = HINT_LINE(opts.currentVersion, latest);
+    try {
+        sink.write(line);
+    }
+    catch {
+        return null;
+    }
+    return line;
+}

package/dist/index.js

@@ -349,10 +349,26 @@ program
             return; // thin TUI rendered and exited
         // else fall through to full runtime
     }
-    const ReactModule = await import("react");
-    const { bootstrapInteractiveSession } = await import("./ui/bootstrap.js");
+    // Parallel-load the 3 heavy boot modules + the lightweight npx
+    // self-update-hint module, then fire the hint check in parallel
+    // with the runtime bootstrap. Net cost: zero added latency in the
+    // common case (the registry call completes during bootstrap);
+    // worst case: a sub-second wait if the network is slow.
+    const [ReactModule, { bootstrapInteractiveSession }, { printNpxUpgradeHint }] = await Promise.all([
+        import("react"),
+        import("./ui/bootstrap.js"),
+        import("./cli/npx-self-update-hint.js"),
+    ]);
     const React = ReactModule.default;
+    const npxHintPromise = printNpxUpgradeHint({
+        currentVersion: VERSION,
+        currentDirname: dirname(fileURLToPath(import.meta.url)),
+    }).catch(() => null);
     let interactive = await bootstrapInteractiveSession(process.cwd(), options);
+    // Drain the hint promise so the line lands BEFORE the TUI takes
+    // the screen (or before we exit on refusal). It's a best-effort
+    // no-op when not applicable.
+    await npxHintPromise;
     if (options.workspace !== undefined) {
         const { writeWorkspaceResumeRecord } = await import("./cli/workspace-resume.js");
         writeWorkspaceResumeRecord({

package/dist/ui/mount-interactive-ink.d.ts

@@ -21,6 +21,7 @@
  */
 import type { ReactElement } from "react";
 import type { Instance } from "ink";
+import { type StdinDiagnosis } from "./raw-mode-guard.js";
 /** Actionable guidance when there is no raw-mode-capable terminal. */
 export declare const DEFAULT_REFUSAL_MESSAGE: string;
 type InkRender = (el: ReactElement, opts?: {
@@ -53,6 +54,14 @@ export interface MountInteractiveOptions {
      * the stderr diagnostic stays visible in the main buffer.
      */
     readonly onResolved?: () => void;
+    /**
+     * Override the stdin diagnostic walker (tests). Default: the real
+     * `diagnoseStdin` from raw-mode-guard. The diagnosis is appended to
+     * the DEFAULT refusal message — when a `refusalMessage` is provided
+     * explicitly, the diagnosis is NOT appended (preserve strict-equality
+     * test contracts and let callers control the full output).
+     */
+    readonly diagnoseStdinFn?: () => StdinDiagnosis;
 }
 export interface MountInteractiveResult {
     /**

package/dist/ui/mount-interactive-ink.js

@@ -20,7 +20,7 @@
  * bug class cannot silently regress when a new mount is added.
  */
 import { ensureRenderableViewport } from "./viewport-guard.js";
-import { resolveInteractiveStdin } from "./raw-mode-guard.js";
+import { resolveInteractiveStdin, diagnoseStdin, formatStdinDiagnosis, } from "./raw-mode-guard.js";
 /** Actionable guidance when there is no raw-mode-capable terminal. */
 export const DEFAULT_REFUSAL_MESSAGE = "[wotann] No raw-mode-capable terminal available for the interactive TUI.\n" +
     "  stdin is piped or the launcher degraded the TTY (some `npx`\n" +
@@ -51,7 +51,24 @@ export async function mountInteractiveInk(element, opts = {}) {
     const inputStdin = resolve();
     if (inputStdin === null) {
         const sink = opts.stderr ?? process.stderr;
-        sink.write(opts.refusalMessage ?? DEFAULT_REFUSAL_MESSAGE);
+        if (opts.refusalMessage !== undefined) {
+            // Caller provided a full custom message — write it verbatim, no
+            // diagnosis appended (preserves strict-equality test contracts).
+            sink.write(opts.refusalMessage);
+        }
+        else {
+            sink.write(DEFAULT_REFUSAL_MESSAGE);
+            // Append a per-step diagnosis so the user sees WHY the guard
+            // refused (which step failed and what it observed). Future bug
+            // reports include the evidence automatically.
+            try {
+                const diagnose = opts.diagnoseStdinFn ?? diagnoseStdin;
+                sink.write(formatStdinDiagnosis(diagnose()));
+            }
+            catch {
+                // Diagnostic must never block the refusal — swallow.
+            }
+        }
         return { instance: null, refused: true };
     }
     const inkRender = opts.inkRender ?? (await import("ink")).render;

package/dist/ui/raw-mode-guard.d.ts

@@ -53,3 +53,40 @@ export interface ResolveStdinOptions {
  * Never throws.
  */
 export declare function resolveInteractiveStdin(stdin?: unknown, opts?: ResolveStdinOptions): NodeJS.ReadStream | null;
+/**
+ * Structured per-step diagnosis of why the resolver did or did not return
+ * a raw-capable stream. The shape mirrors the steps of
+ * `resolveInteractiveStdin` so a "guard refused under a raw-capable
+ * terminal" report carries enough evidence to identify which step failed
+ * without shipping a custom diagnostic build.
+ */
+export interface StdinDiagnosis {
+    /** Whatever `stdin.isTTY` returned (true/false/undefined/etc.). */
+    readonly stdinIsTTY: unknown;
+    /** Whether `stdin.setRawMode` is a function (not whether it works). */
+    readonly stdinHasSetRawMode: boolean;
+    /** "ok" if the probe call succeeded, "missing" if no setRawMode, else the error message. */
+    readonly stdinProbeResult: string;
+    /** "ok", "not-attempted", "returned null", or the open error message. */
+    readonly ttyOpenResult: string;
+    /** Whatever the opened /dev/tty stream's `isTTY` returned, when applicable. */
+    readonly ttyIsTTY?: unknown;
+    /** Whether the opened /dev/tty stream has a `setRawMode` function. */
+    readonly ttyHasSetRawMode?: boolean;
+    /** "ok", "missing", or the error message — only set when /dev/tty open succeeded. */
+    readonly ttyProbeResult?: string;
+}
+/**
+ * Walks the same `resolveInteractiveStdin` steps and records what each
+ * one saw. Use this when the resolver returns `null` to print a
+ * self-explanatory refusal — future bug reports will include the
+ * diagnosis automatically instead of just "guard refused, why?".
+ */
+export declare function diagnoseStdin(stdin?: unknown, opts?: ResolveStdinOptions): StdinDiagnosis;
+/**
+ * Format a `StdinDiagnosis` as a short multi-line human-readable block
+ * suitable for stderr. Compact (~4 lines) so it doesn't dominate the
+ * refusal output but carries every piece of evidence needed to
+ * identify which step failed.
+ */
+export declare function formatStdinDiagnosis(d: StdinDiagnosis): string;

package/dist/ui/raw-mode-guard.js

@@ -91,3 +91,96 @@ export function resolveInteractiveStdin(stdin = process.stdin, opts = {}) {
     }
     return isRawModeCapable(tty) ? tty : null;
 }
+/**
+ * Same observation pattern as `isRawModeCapable` but captures the
+ * probe outcome instead of collapsing to true/false. Pure, never throws.
+ */
+function probeStdinDetail(stream) {
+    if (stream === null || typeof stream !== "object") {
+        return { isTTY: stream, hasSetRawMode: false, probeResult: "missing" };
+    }
+    const s = stream;
+    const hasSetRawMode = typeof s.setRawMode === "function";
+    if (s.isTTY !== true || !hasSetRawMode) {
+        return {
+            isTTY: s.isTTY,
+            hasSetRawMode,
+            probeResult: hasSetRawMode ? "skipped (isTTY!=true)" : "missing",
+        };
+    }
+    try {
+        const setRawMode = s.setRawMode;
+        const currentIsRaw = s.isRaw === true;
+        setRawMode(currentIsRaw);
+        return { isTTY: true, hasSetRawMode: true, probeResult: "ok" };
+    }
+    catch (e) {
+        return {
+            isTTY: true,
+            hasSetRawMode: true,
+            probeResult: e instanceof Error ? e.message : String(e),
+        };
+    }
+}
+/**
+ * Walks the same `resolveInteractiveStdin` steps and records what each
+ * one saw. Use this when the resolver returns `null` to print a
+ * self-explanatory refusal — future bug reports will include the
+ * diagnosis automatically instead of just "guard refused, why?".
+ */
+export function diagnoseStdin(stdin = process.stdin, opts = {}) {
+    const stdinProbe = probeStdinDetail(stdin);
+    if (stdinProbe.probeResult === "ok") {
+        return {
+            stdinIsTTY: stdinProbe.isTTY,
+            stdinHasSetRawMode: stdinProbe.hasSetRawMode,
+            stdinProbeResult: stdinProbe.probeResult,
+            ttyOpenResult: "not-attempted",
+        };
+    }
+    const open = opts.openControllingTty ?? defaultOpenControllingTty;
+    let tty = null;
+    let ttyOpenResult;
+    try {
+        tty = open();
+        ttyOpenResult = tty === null ? "returned null" : "ok";
+    }
+    catch (e) {
+        ttyOpenResult = e instanceof Error ? e.message : String(e);
+    }
+    if (tty === null) {
+        return {
+            stdinIsTTY: stdinProbe.isTTY,
+            stdinHasSetRawMode: stdinProbe.hasSetRawMode,
+            stdinProbeResult: stdinProbe.probeResult,
+            ttyOpenResult,
+        };
+    }
+    const ttyProbe = probeStdinDetail(tty);
+    return {
+        stdinIsTTY: stdinProbe.isTTY,
+        stdinHasSetRawMode: stdinProbe.hasSetRawMode,
+        stdinProbeResult: stdinProbe.probeResult,
+        ttyOpenResult,
+        ttyIsTTY: ttyProbe.isTTY,
+        ttyHasSetRawMode: ttyProbe.hasSetRawMode,
+        ttyProbeResult: ttyProbe.probeResult,
+    };
+}
+/**
+ * Format a `StdinDiagnosis` as a short multi-line human-readable block
+ * suitable for stderr. Compact (~4 lines) so it doesn't dominate the
+ * refusal output but carries every piece of evidence needed to
+ * identify which step failed.
+ */
+export function formatStdinDiagnosis(d) {
+    const lines = [
+        "  Diagnostic:",
+        `    stdin: isTTY=${String(d.stdinIsTTY)} setRawMode=${d.stdinHasSetRawMode ? "yes" : "no"} probe=${d.stdinProbeResult}`,
+        `    /dev/tty: open=${d.ttyOpenResult}`,
+    ];
+    if (d.ttyProbeResult !== undefined) {
+        lines.push(`      isTTY=${String(d.ttyIsTTY)} setRawMode=${d.ttyHasSetRawMode ? "yes" : "no"} probe=${d.ttyProbeResult}`);
+    }
+    return lines.join("\n") + "\n";
+}

package/install.sh

@@ -96,10 +96,42 @@ if ! command -v npm >/dev/null 2>&1; then
   exit 1
 fi
 
+# ---------------------------------------------------------------- Disk-space pre-flight
+# Partial installs are the #1 silent-failure class on disk-pressured
+# systems: `npm install -g` exits 0, but dist/index.js gets truncated
+# during the atomic rename, leaving a wotann binary on PATH that runs
+# `node empty.js` → exits 0 with zero output. Refuse install when free
+# space is below 5GB so the user notices BEFORE the install pretends
+# to succeed. Override with WOTANN_FORCE_INSTALL=1 if you know better.
+AVAIL_KB="$(df -k "$HOME" 2>/dev/null | awk 'NR==2 {print $4}')"
+if [ -n "${AVAIL_KB:-}" ] && [ "$AVAIL_KB" -lt 5242880 ]; then
+  AVAIL_GB="$(( AVAIL_KB / 1048576 ))"
+  echo -e "${YELLOW}WARN: Only ${AVAIL_GB}GB free on \$HOME — risky for npm install -g.${NC}"
+  echo -e "${DIM}      Below 5GB, partial installs can leave a broken binary on PATH"
+  echo -e "${DIM}      (causes 'wotann does nothing'). Free some space or override:${NC}"
+  echo -e "${DIM}        WOTANN_FORCE_INSTALL=1 ./install.sh${NC}"
+  if [ "${WOTANN_FORCE_INSTALL:-0}" != "1" ]; then
+    exit 1
+  fi
+fi
+
 # ---------------------------------------------------------------- Idempotency
+# Broken-install detection: if wotann is on PATH but `--version` doesn't
+# print a `\d+\.\d+\.\d+` within 5 seconds, the previous install is
+# half-applied. Uninstall before reinstalling so we don't keep the
+# broken bin on PATH and shadow the fresh `npm install -g` we're about
+# to run. This is the failure mode that masked 3 prior "fixes" — see
+# case_npm_install_global_postinstall.md.
 if command -v wotann >/dev/null 2>&1; then
-  CURRENT="$(wotann --version 2>/dev/null || echo unknown)"
-  echo -e "${DIM}Existing install detected: ${CURRENT}. Reinstalling...${NC}"
+  CURRENT="$(perl -e 'alarm 5; exec @ARGV' wotann --version 2>/dev/null || true)"
+  if [ -z "$CURRENT" ] || ! printf "%s" "$CURRENT" | grep -qE "^[0-9]+\.[0-9]+\.[0-9]+"; then
+    echo -e "${YELLOW}Existing wotann install is broken (no version output).${NC}"
+    echo -e "${DIM}Uninstalling before fresh install...${NC}"
+    npm uninstall -g wotann >/dev/null 2>&1 || true
+    hash -r 2>/dev/null || true
+  else
+    echo -e "${DIM}Existing install detected: ${CURRENT}. Reinstalling...${NC}"
+  fi
 fi
 
 # ---------------------------------------------------------------- Install
@@ -161,7 +193,20 @@ if ! command -v wotann >/dev/null 2>&1; then
   case ":$PATH:" in *":$NPM_BIN:"*) ;; *) PATH="$NPM_BIN:$PATH" ;; esac
 fi
 if command -v wotann >/dev/null 2>&1; then
-  echo -e "${GREEN}OK: WOTANN $(wotann --version) installed${NC}"
+  # Post-install verification: a successful `npm install -g` doesn't
+  # imply a working binary. Time-limit the version probe so a hang
+  # from a partially-installed dist/index.js doesn't lock the script.
+  VERIFY_OUT="$(perl -e 'alarm 10; exec @ARGV' wotann --version 2>&1 || true)"
+  if [ -z "$VERIFY_OUT" ] || ! printf "%s" "$VERIFY_OUT" | grep -qE "^[0-9]+\.[0-9]+\.[0-9]+"; then
+    echo -e "${RED}ERROR: wotann installed but \`--version\` returned no version string.${NC}"
+    echo -e "${DIM}        Captured output: ${VERIFY_OUT:-<empty>}${NC}"
+    echo -e "${DIM}        This is the partial-install class — likely disk pressure or"
+    echo -e "${DIM}        a postinstall script that didn't complete. Recovery:${NC}"
+    echo -e "${DIM}          npm uninstall -g wotann${NC}"
+    echo -e "${DIM}          # free disk space (need ≥5GB), then re-run install.sh${NC}"
+    exit 1
+  fi
+  echo -e "${GREEN}OK: WOTANN ${VERIFY_OUT} installed and verified${NC}"
 else
   echo -e "${RED}wotann command still not on PATH. Add npm global bin to PATH:${NC}"
   echo -e "${DIM}  export PATH=\"\$(npm bin -g):\$PATH\"${NC}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wotann",
-  "version": "0.5.91",
+  "version": "0.5.92",
   "description": "WOTANN — The All-Father of AI Agent Harnesses",
   "type": "module",
   "main": "dist/index.js",