@sayknow-cli/utils 0.7.11 → 0.7.12

package/dist/types/fetch-retry.d.ts

@@ -22,15 +22,18 @@ export interface FetchWithRetryOptions extends RequestInit {
     /**
      * Per-delay cap. Server-provided `Retry-After` hints exceeding this return
      * the current response immediately — caller deals with the `!response.ok`.
-     * Default `60_000`.
+     * Scheduled values are also capped at the platform timer ceiling. Default
+     * `60_000`.
      */
     maxDelayMs?: number;
     /**
      * Fallback delay schedule when no server hint is present. Number, array
      * (indexed by attempt, clamped to last), or function. Default exponential
-     * `500ms * 2 ** attempt` capped at `maxDelayMs`.
+     * `500ms * 2 ** attempt` capped at `maxDelayMs` and the platform timer
+     * ceiling. Values that remain negative or non-finite after capping retry
+     * immediately.
      */
-    defaultDelayMs?: number | readonly number[] | ((attempt: number) => number);
+    defaultDelayMs?: number | readonly number[] | ((attempt: number, error?: unknown) => number);
     /**
      * Optional per-attempt overlay merged into the base `RequestInit` each try.
      * Headers from the overlay shallow-merge over the base. Useful for auth

package/dist/types/header-value.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sanitize a value destined for an HTTP header.
+ *
+ * OS-derived components (kernel release, hostname, os.version) can contain
+ * non-ASCII characters — e.g. Android kernel releases such as
+ * `4.4.302-Minimal™-EAS-QTI_Haptic-R26` — which `Headers`/`fetch` reject
+ * before the request is ever sent. Strip everything outside printable
+ * ASCII so header construction can never throw on runtime-derived values.
+ */
+export declare function sanitizeHeaderComponent(value: string): string;

package/dist/types/index.d.ts

@@ -2,13 +2,18 @@ export { createAbortableStream, once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./broken-pipe";
 export * from "./color";
+export * from "./crash-fingerprint";
+export * from "./crash-journal";
+export * from "./crash-redaction";
 export * from "./dirs";
 export * from "./env";
+export * from "./error-classification";
 export * from "./fetch-retry";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
 export * from "./glob";
+export * from "./header-value";
 export * from "./hook-fetch";
 export * from "./json";
 export * as logger from "./logger";
@@ -20,6 +25,7 @@ export * as procmgr from "./procmgr";
 export * as prompt from "./prompt";
 export * as ptree from "./ptree";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./safe-error";
 export * from "./safe-stderr";
 export * from "./sanitize-text";
 export * from "./snowflake";

package/dist/types/logger.d.ts

@@ -1,3 +1,14 @@
+type LogPathPlatform = NodeJS.Platform | "posix";
+/** A filesystem root. On POSIX a backslash is a file name, not a root or a separator. */
+export declare function isFsRoot(target: string, platform?: LogPathPlatform): boolean;
+/**
+ * Drop trailing separators without changing the directory name.
+ * POSIX removes only `/`. Windows also removes `\`.
+ * A root keeps one separator so `C:\` does not become the drive-relative name `C:`.
+ */
+export declare function lexicalLogPath(target: string, platform?: LogPathPlatform): string;
+/** True when "." / ".." collapse to a filesystem root. Does not follow symlinks. */
+export declare function resolvesAsFsRoot(target: string, platform?: LogPathPlatform): boolean;
 /**
  * Replace the active log transports. Pass `console: true, file: false` for
  * long-running services (the auth broker, etc.) that want their structured
@@ -39,16 +50,18 @@ export declare function debug(message: string, context?: Record<string, unknown>
 export declare function printTimings(): void;
 /**
  * Begin recording startup timings under a new root span.
- * Idempotent: a second call while already recording is a no-op so that side-effect
- * starters (see module-timer.ts) and explicit starters (main.ts) can coexist.
+ * Idempotent: a second call while already recording is a no-op so that the
+ * early starter (cli.ts, the first CLI statement) and the explicit starter
+ * (main.ts) can coexist.
+ *
+ * The root is anchored at the process-start origin rather than at the call:
+ * `performance.now()` counts milliseconds since `performance.timeOrigin`
+ * (process start) on Bun, so `start: 0` makes `Total` the true
+ * time-since-process-start. Runtime bootstrap plus static module linking and
+ * evaluation then land in the root's self time instead of being invisible
+ * before the first statement of cli.ts.
  */
 export declare function startTiming(): void;
-/**
- * Record an externally-measured span as a leaf child of the active span (or root
- * when no span is active). Used by the module-load timing plugin to splice load
- * events into the tree retroactively.
- */
-export declare function recordModuleLoadSpan(path: string, start: number, durationMs: number): void;
 /**
  * End timing window and clear buffers.
  */
@@ -64,3 +77,4 @@ export declare function endTiming(): void;
  */
 export declare function time(op: string): void;
 export declare function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;
+export {};

package/dist/types/native-process.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lazy synchronous binding for @sayknow-cli/natives process control.
+ *
+ * The natives package entry loads the compiled addon at import time, so a
+ * static import anywhere in the `@sayknow-cli/utils` root barrel graph would
+ * materialize the addon for every barrel consumer. The W5b S1/idle
+ * module-trace gate requires that merely importing the barrel never loads
+ * @sayknow-cli/natives; process-control callers bind at first real use instead.
+ */
+type NativeProcessBindings = Pick<typeof import("@sayknow-cli/natives"), "Process" | "ProcessStatus">;
+export declare function nativeProcessBindings(): NativeProcessBindings;
+export {};

package/dist/types/procmgr.d.ts

@@ -1,39 +1,5 @@
 import type { Subprocess } from "bun";
-export interface ShellConfig {
-    shell: string;
-    args: string[];
-    env: Record<string, string>;
-    prefix: string | undefined;
-}
-/**
- * Strip disabled macOS malloc-stack-logging vars from `process.env` in place.
- *
- * macOS leaves `MallocStackLogging=0` (or similar) inherited by debug-attached
- * shells. Bun's libc init then prints `MallocStackLogging: can't turn off
- * malloc stack logging because it was not enabled.` to stderr for every
- * subprocess. Scrubbing once at startup means every child we spawn — bash,
- * bun subagents, plugin installs, ptree commands — inherits a clean env.
- */
-export declare function scrubProcessEnv(): void;
-/**
- * Resolve a basic shell (bash or sh) as fallback.
- */
-export declare function resolveBasicShell(): string | undefined;
-/**
- * Get shell configuration based on platform.
- * Resolution order:
- * 1. User-specified shellPath in settings.json
- * 2. On Windows: Git Bash in known locations, then bash on PATH
- * 3. On Unix: $SHELL if bash/zsh, then fallback paths
- * 4. Fallback: sh
- */
-export declare function getShellConfig(customShellPath?: string): ShellConfig;
-/**
- * Clear the memoized shell configuration so the next {@link getShellConfig}
- * call re-resolves the shell and re-reads the environment (shell selection and
- * the bash CI/login flags). Primarily for tests that vary those inputs.
- */
-export declare function resetShellConfigCache(): void;
+export { getShellConfig, resetShellConfigCache, resolveBasicShell, type ShellConfig, scrubProcessEnv, } from "./shell-config";
 /**
  * Check if a process is running.
  */

package/dist/types/safe-error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Throw-proof error description.
+ *
+ * Hostile or exotic thrown values can make `String(value)` throw (a `toString`
+ * that throws, a revoked proxy, a null-prototype object) and a `message` getter
+ * can throw too. Logging or recording a failure must never become a second
+ * failure, so every failure path that stringifies a caught value uses this.
+ *
+ * @example
+ * ```ts
+ * import { safeErrorDescription } from "@sayknow-cli/utils";
+ *
+ * try {
+ *     await risky();
+ * } catch (error) {
+ *     logger.warn("risky failed", { error: safeErrorDescription(error) });
+ * }
+ * ```
+ */
+export declare function safeErrorDescription(value: unknown): string;

package/dist/types/sanitize-text.d.ts

@@ -12,3 +12,13 @@
  * string after the control probe.
  */
 export declare function sanitizeText(text: string): string;
+/**
+ * Sanitize untrusted text that must occupy exactly one rendered row.
+ *
+ * {@link sanitizeText} deliberately preserves `\n`, and width-based truncation
+ * treats it as zero-width, so a value carrying line breaks can still inject
+ * extra rows and evade a single-line width budget. Flatten every CR/LF run to a
+ * single space before the usual control/ANSI strip, then remove directional
+ * format controls that can visually reorder an otherwise safe row.
+ */
+export declare function sanitizeDisplayLine(text: string): string;

package/dist/types/shell-config.d.ts

@@ -0,0 +1,58 @@
+export interface ShellConfig {
+    shell: string;
+    args: string[];
+    env: Record<string, string>;
+    prefix: string | undefined;
+}
+/**
+ * Strip disabled macOS malloc-stack-logging vars from `process.env` in place.
+ *
+ * macOS leaves `MallocStackLogging=0` (or similar) inherited by debug-attached
+ * shells. Bun's libc init then prints `MallocStackLogging: can't turn off
+ * malloc stack logging because it was not enabled.` to stderr for every
+ * subprocess. Scrubbing once at startup means every child we spawn — bash,
+ * bun subagents, plugin installs, ptree commands — inherits a clean env.
+ */
+export declare function scrubProcessEnv(): void;
+/**
+ * Names of hook-capable variables whose live value came from the project `.env`.
+ *
+ * Provenance comes from `$inheritedEnv`, the same launch snapshot that guards
+ * credentials: a value the launching shell exported with a different value than
+ * the project declaration is kept. Bun does not reveal which source supplied a
+ * value, so an inherited value the project repeats verbatim, or a key the project
+ * declares dynamically, is ambiguous and fails closed (dropped).
+ */
+export declare function projectDeclaredSpawnHookNames(env?: Record<string, string | undefined>): string[];
+/**
+ * Remove project-declared hook variables from a spawn environment in place.
+ * If removing a home selector leaves `HOME` unset, provide the trusted account
+ * home when one exists rather than allowing a Windows profile fallback.
+ */
+export declare function stripProjectSpawnHooks(env: Record<string, string>): Record<string, string>;
+/**
+ * The process environment without project-declared hook variables, for spawning
+ * the bash tool's shell processes (isolated worker chain and PTY sessions).
+ */
+export declare function projectSafeSpawnEnv(): Record<string, string>;
+/** Provide the trusted HOME override needed when PTY hook filtering removes a home selector. */
+export declare function projectSafeHomeOverride(explicit?: Record<string, string>): Record<string, string>;
+/**
+ * Resolve a basic shell (bash or sh) as fallback.
+ */
+export declare function resolveBasicShell(): string | undefined;
+/**
+ * Get shell configuration based on platform.
+ * Resolution order:
+ * 1. User-specified shellPath in settings.json
+ * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 3. On Unix: $SHELL if bash/zsh, then fallback paths
+ * 4. Fallback: sh
+ */
+export declare function getShellConfig(customShellPath?: string): ShellConfig;
+/**
+ * Clear the memoized shell configuration so the next {@link getShellConfig}
+ * call re-resolves the shell and re-reads the environment (shell selection and
+ * the bash CI/login flags). Primarily for tests that vary those inputs.
+ */
+export declare function resetShellConfigCache(): void;

package/dist/types/stream.d.ts

@@ -1,5 +1,6 @@
 export declare function readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
-export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T>;
+export type JsonlLineObserver = (raw: string) => void;
+export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onLine?: JsonlLineObserver): AsyncGenerator<T>;
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *

package/dist/types/which.d.ts

@@ -26,7 +26,7 @@ export interface WhichOptions extends Bun.WhichOptions {
      */
     cache?: WhichCachePolicy;
 }
-declare function darwinWhich(command: string, _options?: Bun.WhichOptions): string | null;
+declare function darwinWhich(command: string, options?: Bun.WhichOptions): string | null;
 export declare const whichFresh: typeof darwinWhich;
 /**
  * Locate binary on PATH (with flexible caching).

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/utils",
-	"version": "0.7.11",
+	"version": "0.7.12",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.7.11",
+		"@sayknow-cli/natives": "0.7.12",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/broken-pipe.ts

@@ -9,6 +9,16 @@
 import * as fs from "node:fs";
 
 const KNOWN_SINK_PEER_CLOSED_CODES = new Set(["EPIPE", "ERR_STREAM_DESTROYED"]);
+/**
+ * Errno codes that mean the process's own stdout sink has gone away because
+ * the peer (terminal emulator, pager, pipe reader, or pty) was torn down. On
+ * macOS a torn-down pty slave produces `EIO`; a closed fd produces `EBADF`;
+ * a closed pipe produces `EPIPE`. All three are the same benign condition:
+ * the terminal disconnected.
+ *
+ * Mirrors `CLOSED_STDERR_ERROR_CODES` in `safe-stderr.ts`; keep in sync.
+ */
+const PROCESS_STDOUT_PEER_CLOSED_CODES = new Set(["EIO", "EPIPE", "EBADF"]);
 
 type ErrorProperty = "code" | "fd" | "syscall";
 
@@ -70,9 +80,10 @@ export function isBrokenPipeError(error: unknown): boolean {
 }
 
 /**
- * A classifier for process-level stdout `EPIPE` errors. Its direct-write
- * evidence is private to each factory instance, so only the owner that
- * intercepted `process.stdout.write` can mark an error for this classifier.
+ * A classifier for process-level stdout peer-closed errors (`EPIPE`, `EIO`,
+ * `EBADF`). Its direct-write evidence is private to each factory instance, so
+ * only the owner that intercepted `process.stdout.write` can mark an error
+ * for this classifier.
  */
 export interface ProcessStdoutEpipeClassifier {
 	markDirectProcessStdoutWriteError(error: unknown): void;
@@ -109,7 +120,8 @@ export function createProcessStdoutEpipeClassifier(): ProcessStdoutEpipeClassifi
 			if (!isObjectLike(error)) return false;
 
 			const code = readErrorProperty(error, "code");
-			if (!code.available || code.value !== "EPIPE") return false;
+			if (!code.available || typeof code.value !== "string" || !PROCESS_STDOUT_PEER_CLOSED_CODES.has(code.value))
+				return false;
 
 			if (directProcessStdoutWriteErrors.has(error)) return true;
 

package/src/canonical-log-dir.ts

@@ -0,0 +1,59 @@
+import * as path from "node:path";
+
+interface ProjectEnvSnapshotLike {
+	values: Record<string, string>;
+	dynamic: Set<string>;
+}
+
+interface CanonicalLogDirInput {
+	home: string;
+	env: Record<string, string | undefined>;
+	projectEnv: ProjectEnvSnapshotLike;
+	xdgEligible: boolean;
+	pathExists?: (target: string) => boolean;
+}
+
+const APP_NAME = "skc";
+const DEFAULT_CONFIG_DIR_NAME = ".skc";
+
+function canonicalEnvKey(name: string): string {
+	return process.platform === "win32" ? name.toUpperCase() : name;
+}
+
+function sanitizeConfigDirName(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	if (!trimmed || path.normalize(trimmed).split(/[\\/]/).includes("..")) return undefined;
+	return trimmed;
+}
+
+/** Resolve a caller environment value only when its dotenv provenance is trusted. */
+function trustedValue(name: string, input: CanonicalLogDirInput): string | undefined {
+	const value = input.env[name];
+	if (!value) return undefined;
+	const key = canonicalEnvKey(name);
+	if (input.projectEnv.dynamic.has(key) || input.projectEnv.values[key] === value) return undefined;
+	return value;
+}
+
+/**
+ * Resolve the canonical user log directory without mutating the environment.
+ *
+ * The caller supplies filesystem existence checks so this leaf stays free of
+ * filesystem and resolver side effects. Both the production directory resolver
+ * and the test preload use this exact path selection logic.
+ */
+export function resolveCanonicalLogsDir(input: CanonicalLogDirInput): string {
+	const configDirName =
+		sanitizeConfigDirName(trustedValue("SKC_CONFIG_DIR", input)) ??
+		sanitizeConfigDirName(trustedValue("PI_CONFIG_DIR", input)) ??
+		DEFAULT_CONFIG_DIR_NAME;
+	const xdgStateHome =
+		input.xdgEligible && (process.platform === "linux" || process.platform === "darwin")
+			? trustedValue("XDG_STATE_HOME", input)?.trim()
+			: undefined;
+	if (xdgStateHome) {
+		const xdgRoot = path.join(xdgStateHome, APP_NAME);
+		if (input.pathExists?.(xdgRoot) === true) return path.join(xdgRoot, "logs");
+	}
+	return path.join(input.home, configDirName, "logs");
+}

package/src/cli-metadata.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure CLI metadata leaf.
+ *
+ * The actual `skc` entry (`packages/coding-agent/src/cli.ts`) must stay inert on
+ * import: no directory resolution, logger construction, NSS lookup, native load
+ * or environment probing may run before argv routing. `dirs.ts` performs all of
+ * those at module scope, so the handful of constants the entry really needs live
+ * here and `dirs.ts` re-exports them for its existing callers.
+ *
+ * Only build-time package metadata may be imported here.
+ */
+
+import { engines, version } from "../package.json" with { type: "json" };
+
+/** App name (e.g. "skc") */
+export const APP_NAME: string = "skc";
+
+/** Version (e.g. "1.0.0") */
+export const VERSION: string = version;
+
+/** Minimum Bun version */
+export const MIN_BUN_VERSION: string = engines.bun.replace(/[^0-9.]/g, "");
+
+/**
+ * Build the diagnostic shown when the Bun runtime executing `skc` is older
+ * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
+ * failure (issue #525): `bun install -g sayknow-cli` probes a recent Bun while
+ * the `skc` launcher resolves an older Bun still on PATH. The message names the
+ * exact detected runtime path and gives a platform-specific upgrade + PATH fix
+ * instead of a bare `bun upgrade`.
+ *
+ * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ */
+export function formatBunRuntimeError(opts: {
+	currentVersion: string;
+	minVersion: string;
+	execPath?: string;
+	platform?: NodeJS.Platform;
+}): string {
+	const platform = opts.platform ?? process.platform;
+	const lines = [
+		`error: ${APP_NAME} requires Bun >= ${opts.minVersion}, but the running Bun is v${opts.currentVersion}.`,
+	];
+	if (opts.execPath) {
+		lines.push(`  detected Bun runtime: ${opts.execPath}`);
+	}
+	if (platform === "win32") {
+		lines.push(
+			"",
+			"The 'skc' launcher is using an older Bun than the one used to install it.",
+			"Upgrade Bun, then restart your terminal so PATH and the runtime refresh:",
+			"",
+			'  powershell -c "irm bun.sh/install.ps1|iex"',
+			"",
+			"After restarting the terminal, verify both versions match:",
+			"  bun --version",
+			"  skc --version",
+			"",
+			"If 'skc' still loads the old runtime, make sure %USERPROFILE%\\.bun\\bin is",
+			"first on PATH and remove any stale Bun installs shadowing it.",
+		);
+	} else {
+		lines.push(
+			"",
+			"Upgrade Bun, then restart your terminal:",
+			"  bun upgrade",
+			"",
+			"Then verify:",
+			"  bun --version",
+			"  skc --version",
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}

package/src/cli.ts

@@ -23,6 +23,8 @@ export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "st
 	multiple?: boolean;
 	options?: readonly string[];
 	required?: boolean;
+	/** The string value may be omitted; parsers decide whether to consume it. */
+	optionalValue?: boolean;
 }
 
 export interface ArgDescriptor {
@@ -40,6 +42,8 @@ interface FlagInput {
 	multiple?: boolean;
 	options?: readonly string[];
 	required?: boolean;
+	/** The string value may be omitted; parsers decide whether to consume it. */
+	optionalValue?: boolean;
 }
 
 interface ArgInput {
@@ -352,7 +356,14 @@ function renderCommandBody(lines: string[], Cmd: CommandCtor): void {
 		for (const [name, desc] of flagEntries) {
 			const charPart = desc.char ? `-${desc.char}, ` : "    ";
 			const namePart = `--${name}`;
-			const typePart = desc.kind === "boolean" ? "" : desc.kind === "integer" ? "=<int>" : "=<value>";
+			const typePart =
+				desc.kind === "boolean"
+					? ""
+					: desc.kind === "integer"
+						? "=<int>"
+						: desc.optionalValue
+							? "[=<value>]"
+							: "=<value>";
 			formatted.push([`  ${charPart}${namePart}${typePart}`, desc.description ?? ""]);
 		}
 		const maxLeft = Math.max(...formatted.map(([l]) => l.length));
@@ -383,6 +394,15 @@ export interface CommandEntry {
 	name: string;
 	load: () => Promise<CommandCtor>;
 	aliases?: string[];
+	/** Owns parsing, help, loading and failures for this family when supplied. */
+	dispatch?: (argv: string[], context: CommandEntryContext) => Promise<void>;
+}
+
+export interface CommandEntryContext {
+	bin: string;
+	version: string;
+	/** Canonical registered entry name, including when invoked through an alias. */
+	command: string;
 }
 
 export interface RunOptions {
@@ -428,9 +448,17 @@ export async function run(opts: RunOptions): Promise<void> {
 		return;
 	}
 
+	const dispatchedEntry = findEntry(opts.commands, commandId);
+	if (dispatchedEntry?.dispatch) {
+		await dispatchedEntry.dispatch(commandArgv, { bin, version, command: dispatchedEntry.name });
+		return;
+	}
+
 	// Per-command help. Commands with nested subcommands can opt into receiving
 	// help flags themselves so `cmd subcommand --help` can render subcommand help.
-	if (commandArgv.includes("--help") || commandArgv.includes("-h")) {
+	const delimiterIndex = commandArgv.indexOf("--");
+	const helpArgs = delimiterIndex === -1 ? commandArgv : commandArgv.slice(0, delimiterIndex);
+	if (helpArgs.includes("--help") || helpArgs.includes("-h")) {
 		const entry = findEntry(opts.commands, commandId);
 		if (!entry) {
 			process.stderr.write(`Unknown command: ${commandId}\n`);