@gajae-code/utils 0.8.2 → 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.2",
+	"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.2",
+		"@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/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);
+	}
 }
 
 /**