@sayknow-cli/utils 0.3.6 → 0.3.8

package/dist/types/which.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cache policy for which lookups.
+ */
+export declare const enum WhichCachePolicy {
+    /**
+     * Use cached result if available.
+     */
+    Cached = 0,
+    /**
+     * Bypass cache and perform a new lookup.
+     */
+    Bypass = 1,
+    /**
+     * Always update cache.
+     */
+    Fresh = 2,
+    /**
+     * Read-only, serves from cache if present, but doesn't write.
+     */
+    ReadOnly = 3
+}
+export interface WhichOptions extends Bun.WhichOptions {
+    /**
+     * Cache policy for the lookup.
+     * Defaults to `WhichCachePolicy.Fresh`.
+     */
+    cache?: WhichCachePolicy;
+}
+export declare const whichFresh: typeof Bun.which;
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export declare function $which(command: string, options?: WhichOptions): string | null;

package/package.json

@@ -1,9 +1,9 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/utils",
-	"version": "0.3.6",
+	"version": "0.3.8",
 	"description": "Shared utilities for pi packages",
-	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
+	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
 	"license": "MIT",
 	"repository": {
@@ -21,7 +21,7 @@
 		"streams"
 	],
 	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "biome check . && bun run check:types",
 		"check:types": "tsgo -p tsconfig.json --noEmit",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/natives": "0.3.6",
+		"@sayknow-cli/natives": "0.3.8",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
@@ -44,15 +44,16 @@
 		"bun": ">=1.3.14"
 	},
 	"files": [
-		"src"
+		"src",
+		"dist/types"
 	],
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
+			"types": "./dist/types/index.d.ts",
 			"import": "./src/index.ts"
 		},
 		"./*": {
-			"types": "./src/*.ts",
+			"types": "./dist/types/*.d.ts",
 			"import": "./src/*.ts"
 		},
 		"./*.js": "./src/*.ts"

package/src/cli.ts

@@ -68,6 +68,18 @@ export const Args = {
 	},
 };
 
+/**
+ * Thrown when CLI argument/flag parsing or validation fails (unknown flag,
+ * bad option value, missing required arg, etc.). `run()` catches this to print
+ * the message and render usage instead of crashing as an uncaught exception.
+ */
+export class CliParseError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CliParseError";
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Parse result types — mirrors oclif's typed output from this.parse()
 // ---------------------------------------------------------------------------
@@ -174,12 +186,22 @@ export abstract class Command {
 
 		// strict=false when command declares args (positionals must pass through)
 		// or when the command itself opts out
-		const { values: rawValues, positionals } = nodeParseArgs({
-			args: this.argv,
-			options,
-			allowPositionals: true,
-			strict,
-		});
+		let rawValues: Record<string, string | boolean | Array<string | boolean> | undefined>;
+		let positionals: string[];
+		try {
+			const parsed = nodeParseArgs({
+				args: this.argv,
+				options,
+				allowPositionals: true,
+				strict,
+			});
+			rawValues = parsed.values;
+			positionals = parsed.positionals;
+		} catch (err) {
+			// node:util parseArgs throws on unknown flags / malformed input — surface
+			// it as a CliParseError so run() renders usage instead of crashing.
+			throw new CliParseError(err instanceof Error ? err.message : String(err));
+		}
 
 		// Convert raw values to proper types and validate
 		const flags: Record<string, unknown> = {};
@@ -191,7 +213,7 @@ export abstract class Command {
 				} else {
 					const n = Number.parseInt(raw as string, 10);
 					if (Number.isNaN(n)) {
-						throw new Error(`Expected integer for --${name}, got "${raw}"`);
+						throw new CliParseError(`Expected integer for --${name}, got "${raw}"`);
 					}
 					flags[name] = n;
 				}
@@ -204,14 +226,16 @@ export abstract class Command {
 				// Validate options constraint
 				if (val !== undefined && desc.options && !Array.isArray(val)) {
 					if (!desc.options.includes(val as string)) {
-						throw new Error(`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`);
+						throw new CliParseError(
+							`Expected --${name} to be one of: ${[...desc.options].join(", ")}; got "${val}"`,
+						);
 					}
 				}
 				flags[name] = val;
 			}
 			// Validate required
 			if (desc.required && flags[name] === undefined) {
-				throw new Error(`Missing required flag: --${name}`);
+				throw new CliParseError(`Missing required flag: --${name}`);
 			}
 		}
 
@@ -230,13 +254,15 @@ export abstract class Command {
 			}
 			// Validate required
 			if (desc.required && args[argName] === undefined) {
-				throw new Error(`Missing required argument: ${argName}`);
+				throw new CliParseError(`Missing required argument: ${argName}`);
 			}
 			// Validate options constraint
 			const argVal = args[argName];
 			if (argVal !== undefined && desc.options && typeof argVal === "string") {
 				if (!desc.options.includes(argVal)) {
-					throw new Error(`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`);
+					throw new CliParseError(
+						`Expected ${argName} to be one of: ${[...desc.options].join(", ")}; got "${argVal}"`,
+					);
 				}
 			}
 		}
@@ -407,7 +433,7 @@ export async function run(opts: RunOptions): Promise<void> {
 			const instance = new Cmd(commandArgv, config);
 			await instance.run();
 		} else {
-			const config = await loadAllCommands(opts);
+			const config: CliConfig = { bin, version, commands: new Map([[entry.name, Cmd]]) };
 			renderCommandHelp(bin, entry.name, config.commands.get(entry.name) ?? Cmd);
 		}
 		return;
@@ -425,7 +451,19 @@ export async function run(opts: RunOptions): Promise<void> {
 	const Cmd = await entry.load();
 	const config: CliConfig = { bin, version, commands: new Map([[entry.name, Cmd]]) };
 	const instance = new Cmd(commandArgv, config);
-	await instance.run();
+	try {
+		await instance.run();
+	} catch (err) {
+		if (err instanceof CliParseError) {
+			// Invalid args/flags for a real command: print the problem + usage and
+			// exit with a usage error, instead of crashing as an uncaught exception.
+			process.stderr.write(`${err.message}\n\n`);
+			renderCommandHelp(bin, entry.name, Cmd);
+			process.exitCode = 2;
+			return;
+		}
+		throw err;
+	}
 }
 
 /** Resolve all command loaders for help/alias display. */

package/src/env.ts

@@ -272,7 +272,10 @@ export function isCompiledBinary(): boolean {
 
 const TRUTHY: Dict<boolean> = { "1": true, Y: true, TRUE: true, YES: true, ON: true };
 export function $flag(name: string, def: boolean = false): boolean {
-	const value = $env[name];
+	const value = $env[name]?.trim();
 	if (!value) return def;
-	return TRUTHY[value] === true;
+	// Boolean-like env values are documented as case-insensitive (`1`/`true`/`yes`/`on`),
+	// so normalize before the lookup — otherwise `FOO=true` (the common lowercase spelling)
+	// would silently read as false while only `FOO=TRUE`/`FOO=1` worked.
+	return TRUTHY[value.toUpperCase()] === true;
 }

package/src/format.ts

@@ -33,9 +33,9 @@ export function formatDuration(ms: number): string {
 export function formatNumber(n: number): string {
 	if (n < 1_000) return n.toString();
 	if (n < 10_000) return `${trim1(n / 1_000)}K`;
-	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 1_000_000) return `${roundBelow(n / 1_000, 1_000)}K`;
 	if (n < 10_000_000) return `${trim1(n / 1_000_000)}M`;
-	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 1_000_000_000) return `${roundBelow(n / 1_000_000, 1_000)}M`;
 	if (n < 10_000_000_000) return `${trim1(n / 1_000_000_000)}B`;
 	return `${Math.round(n / 1_000_000_000)}B`;
 }
@@ -46,15 +46,26 @@ function trim1(n: number): string {
 	return s.endsWith(".0") ? s.slice(0, -2) : s;
 }
 
+/** Round to an integer without crossing the next compact suffix boundary. */
+function roundBelow(n: number, nextUnit: number): number {
+	return Math.min(Math.round(n), nextUnit - 1);
+}
+
 /**
  * Format a byte count to a human-readable string.
  * Examples: "512B", "1.5KB", "2.3MB", "1.2GB"
  */
 export function formatBytes(bytes: number): string {
 	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+	if (bytes < 1024 * 1024) return `${formatByteUnit(bytes, 1024)}KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${formatByteUnit(bytes, 1024 * 1024)}MB`;
+	return `${formatByteUnit(bytes, 1024 * 1024 * 1024)}GB`;
+}
+
+/** Format bytes to 1 decimal without rounding up into the next byte unit. */
+function formatByteUnit(bytes: number, unit: number): string {
+	const tenths = Math.min(Math.round((bytes / unit) * 10), 1024 * 10 - 1);
+	return (tenths / 10).toFixed(1);
 }
 
 /**

package/src/frontmatter.ts

@@ -17,15 +17,27 @@ function stripLooseScalarTrailingCommas(metadata: string): string {
 		.join("\n");
 }
 
+function asFrontmatterRecord(parsed: unknown): Record<string, unknown> | null {
+	if (parsed === null) return null;
+	if (typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error("YAML frontmatter root must be an object");
+	}
+	const prototype = Object.getPrototypeOf(parsed);
+	if (prototype !== Object.prototype && prototype !== null) {
+		throw new Error("YAML frontmatter root must be an object");
+	}
+	return parsed as Record<string, unknown>;
+}
+
 function parseYamlMetadata(metadata: string): Record<string, unknown> | null {
 	const normalized = metadata.replaceAll("\t", "  ");
 	try {
-		return YAML.parse(normalized) as Record<string, unknown> | null;
+		return asFrontmatterRecord(YAML.parse(normalized));
 	} catch (strictError) {
 		const loose = stripLooseScalarTrailingCommas(normalized);
 		if (loose === normalized) throw strictError;
 		try {
-			return YAML.parse(loose) as Record<string, unknown> | null;
+			return asFrontmatterRecord(YAML.parse(loose));
 		} catch {
 			throw strictError;
 		}

package/src/glob.ts

@@ -70,20 +70,25 @@ function parseGitignorePatterns(content: string, gitignoreDir: string, baseDir:
 			} else {
 				patterns.push(pattern);
 			}
+		} else if (pattern.includes("/") && !pattern.startsWith("**/")) {
+			// Separator in the middle: git anchors these to the .gitignore's
+			// directory, same as rooted patterns
+			const absolutePattern = path.join(gitignoreDir, pattern);
+			const relativeToBase = path.relative(baseDir, absolutePattern);
+			if (relativeToBase.startsWith("..")) {
+				// Pattern is outside the search directory, skip
+				continue;
+			}
+			pattern = relativeToBase.replace(/\\/g, "/");
+			patterns.push(pattern);
+			if (isDirectoryOnly) {
+				patterns.push(`${pattern}/**`);
+			}
 		} else {
-			// Unrooted pattern: match anywhere in the tree
-			if (pattern.includes("/")) {
-				// Contains slash: match from any directory level
-				patterns.push(`**/${pattern}`);
-				if (isDirectoryOnly) {
-					patterns.push(`**/${pattern}/**`);
-				}
-			} else {
-				// No slash: match file/dir name anywhere
-				patterns.push(`**/${pattern}`);
-				if (isDirectoryOnly) {
-					patterns.push(`**/${pattern}/**`);
-				}
+			// No middle separator: match file/dir name anywhere in the tree
+			patterns.push(`**/${pattern}`);
+			if (isDirectoryOnly) {
+				patterns.push(`**/${pattern}/**`);
 			}
 		}
 	}
@@ -145,8 +150,13 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 		effectiveExclude = [...effectiveExclude, ...gitignorePatterns];
 	}
 
+	const excludeGlobs = effectiveExclude.map(pattern => new Glob(pattern));
+
 	const base = cwd ?? getProjectDir();
 	const allResults: string[] = [];
+	// Overlapping patterns (e.g. `["**/*.ts", "src/*.ts"]`) can both match the same
+	// file; dedupe so a path is returned at most once regardless of pattern overlap.
+	const seen = new Set<string>();
 
 	// Combine timeout and abort signals
 	const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
@@ -171,17 +181,14 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 
 			// Check exclusion patterns
 			const normalized = entry.replace(/\\/g, "/");
-			let excluded = false;
-			for (const excludePattern of effectiveExclude) {
-				const excludeGlob = new Glob(excludePattern);
-				if (excludeGlob.match(normalized)) {
-					excluded = true;
-					break;
-				}
+			if (excludeGlobs.some(excludeGlob => excludeGlob.match(normalized))) {
+				continue;
 			}
-			if (!excluded) {
-				allResults.push(normalized);
+			if (seen.has(normalized)) {
+				continue;
 			}
+			seen.add(normalized);
+			allResults.push(normalized);
 		}
 	}
 

package/src/postmortem.ts

@@ -7,7 +7,7 @@
  */
 import inspector from "node:inspector";
 import { isMainThread } from "node:worker_threads";
-import { logger } from ".";
+import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
 // Cleanup reasons, in order of priority/meaning.
@@ -39,6 +39,9 @@ function runCleanup(reason: Reason): Promise<void> {
 			cleanupStage = "running";
 			break;
 		case "running":
+			if (reason === Reason.EXIT) {
+				return Promise.resolve();
+			}
 			logger.error("Cleanup invoked recursively", { stack: new Error().stack });
 			return Promise.resolve();
 		case "complete":

package/src/tab-spacing.ts

@@ -13,6 +13,9 @@ export const DEFAULT_TAB_WIDTH = 3;
 const EDITORCONFIG_NAME = ".editorconfig";
 
 let defaultTabWidth = DEFAULT_TAB_WIDTH;
+type TabWidthChangeListener = (width: number) => void;
+
+const tabWidthChangeListeners = new Set<TabWidthChangeListener>();
 
 const editorConfigCache = new Map<string, ParsedEditorConfig>();
 const editorConfigChainCache = new Map<string, ChainEntry[]>();
@@ -278,13 +281,25 @@ function resolveEditorConfigTabWidth(match: EditorConfigMatch | undefined, fallb
 
 	return undefined;
 }
+export function onDefaultTabWidthChange(listener: TabWidthChangeListener): () => void {
+	tabWidthChangeListeners.add(listener);
+	return () => {
+		tabWidthChangeListeners.delete(listener);
+	};
+}
 
 export function getDefaultTabWidth(): number {
 	return defaultTabWidth;
 }
 
 export function setDefaultTabWidth(width: number): void {
-	defaultTabWidth = clampTabWidth(width);
+	const next = clampTabWidth(width);
+	if (defaultTabWidth === next) return;
+	defaultTabWidth = next;
+	indentationCache.clear();
+	for (const listener of tabWidthChangeListeners) {
+		listener(next);
+	}
 }
 
 /**