@gajae-code/utils 0.8.1 → 0.9.0

package/dist/types/cli.d.ts

@@ -39,6 +39,14 @@ export declare const Flags: {
 export declare const Args: {
     string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
 };
+/**
+ * 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 declare class CliParseError extends Error {
+    constructor(message: string);
+}
 type FlagValue<D extends FlagDescriptor> = D["kind"] extends "boolean" ? D extends {
     default: boolean;
 } ? boolean : boolean | undefined : D["kind"] extends "integer" ? D extends {

package/dist/types/tab-spacing.d.ts

@@ -1,9 +1,12 @@
 export declare const MIN_TAB_WIDTH = 1;
 export declare const MAX_TAB_WIDTH = 16;
 export declare const DEFAULT_TAB_WIDTH = 3;
+type TabWidthChangeListener = (width: number) => void;
+export declare function onDefaultTabWidthChange(listener: TabWidthChangeListener): () => void;
 export declare function getDefaultTabWidth(): number;
 export declare function setDefaultTabWidth(width: number): void;
 /**
  * Visible tab width in columns for `file` (from `.editorconfig` + default), or the default when `file` is omitted.
  */
 export declare function getIndentation(file?: string | null, projectDir?: string | null): number;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.8.1",
+	"version": "0.9.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.8.1",
+		"@gajae-code/natives": "0.9.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

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/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}/**`);
 			}
 		}
 	}
@@ -149,6 +154,9 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 
 	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;
@@ -176,6 +184,10 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 			if (excludeGlobs.some(excludeGlob => excludeGlob.match(normalized))) {
 				continue;
 			}
+			if (seen.has(normalized)) {
+				continue;
+			}
+			seen.add(normalized);
 			allResults.push(normalized);
 		}
 	}

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);
+	}
 }
 
 /**