@gajae-code/utils 0.17.2 → 0.17.4

package/dist/types/canonical-log-dir.d.ts

@@ -0,0 +1,20 @@
+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;
+}
+/**
+ * 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 declare function resolveCanonicalLogsDir(input: CanonicalLogDirInput): string;
+export {};

package/dist/types/cli.d.ts

@@ -111,6 +111,14 @@ 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 {
     bin: string;

package/dist/types/crash-fingerprint.d.ts

@@ -59,6 +59,15 @@ export declare function normalizeCrashMessage(message: string, options?: CrashFi
 export declare function normalizeCrashFrames(stack: string, options?: CrashFingerprintOptions): string[];
 /** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
 export declare function computeCrashFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export declare function computeHandledErrorFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
 /** The machine-readable identity line appended to every new crash record. */
 export declare function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string;
 export interface CrashRecordMarker {

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

@@ -0,0 +1,12 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export declare const DESIGNED_ERROR: unique symbol;
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export declare function markDesignedError<T extends Error>(error: T): T;
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export declare function isDesignedError(error: unknown): boolean;

package/dist/types/index.d.ts

@@ -7,6 +7,7 @@ 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";

package/dist/types/postmortem.d.ts

@@ -5,6 +5,7 @@
  * in response to process exit, signals, or fatal exceptions. It is intended to
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
+import { type CrashFingerprint } from "./crash-fingerprint";
 import type { CrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 export declare enum Reason {
@@ -63,6 +64,7 @@ interface CrashRecordOptions {
     path?: string;
     now?: Date;
     provenance?: CrashProvenance;
+    fingerprint?: CrashFingerprint;
 }
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.

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

@@ -18,6 +18,7 @@ export declare function sanitizeText(text: string): string;
  * {@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.
+ * 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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.17.2",
+	"version": "0.17.4",
 	"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.17.2",
+		"@gajae-code/natives": "0.17.4",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

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 = "gjc";
+const DEFAULT_CONFIG_DIR_NAME = ".gjc";
+
+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("GJC_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.ts

@@ -394,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 {
@@ -439,6 +448,12 @@ 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.
 	const delimiterIndex = commandArgv.indexOf("--");

package/src/crash-fingerprint.ts

@@ -224,17 +224,18 @@ function canonicalSerialization(fields: readonly string[]): Buffer {
 	return Buffer.concat(parts);
 }
 
-/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
-export function computeCrashFingerprint(
+function computeFingerprint(
 	input: CrashFingerprintInput,
-	options: CrashFingerprintOptions = {},
+	options: CrashFingerprintOptions,
+	includeMessage: boolean,
 ): CrashFingerprint {
 	const errorName = truncateUtf8(normalizeCrashMessage(input.name, options) || "Error", 128);
 	const messageClass = normalizeCrashMessage(input.message, options);
 	const frames = normalizeCrashFrames(input.stack, options);
-	const digest = createHash("sha256")
-		.update(canonicalSerialization(["gjc-crash-fp.v1", errorName, messageClass, ...frames]))
-		.digest();
+	const identity = includeMessage
+		? ["gjc-crash-fp.v1", errorName, messageClass, ...frames]
+		: ["gjc-crash-fp.v1", "handled", errorName, frames[0] ?? NO_APP_FRAME];
+	const digest = createHash("sha256").update(canonicalSerialization(identity)).digest();
 	return {
 		fingerprint: digest.subarray(0, CRASH_FINGERPRINT_HEX_LENGTH / 2).toString("hex"),
 		version: CRASH_FINGERPRINT_VERSION,
@@ -244,6 +245,29 @@ export function computeCrashFingerprint(
 	};
 }
 
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export function computeCrashFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, true);
+}
+
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export function computeHandledErrorFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, false);
+}
+
 /** The machine-readable identity line appended to every new crash record. */
 export function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string {
 	return `${CRASH_RECORD_MARKER} fp:${fingerprint} fpv:${version} id:${recordId}`;

package/src/dirs.ts

@@ -16,6 +16,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { engines, version } from "../package.json" with { type: "json" };
+import { resolveCanonicalLogsDir } from "./canonical-log-dir";
 import { canonicalEnvKey, type ProjectEnvSnapshot, projectEnvSnapshot } from "./env-file";
 
 // The provenance snapshot and its key fold live in the leaf `env-file` module so
@@ -701,7 +702,18 @@ export function getReportsDir(): string {
 
 /** Get the logs directory (~/.gjc/logs). */
 export function getLogsDir(): string {
-	return dirs.rootSubdir("logs", "state");
+	const home = getTrustedHomeDir();
+	return resolveCanonicalLogsDir({
+		home,
+		env: {
+			GJC_CONFIG_DIR: process.env.GJC_CONFIG_DIR,
+			PI_CONFIG_DIR: process.env.PI_CONFIG_DIR,
+			XDG_STATE_HOME: process.env.XDG_STATE_HOME,
+		},
+		projectEnv: dirs.trustSnapshot,
+		xdgEligible: dirs.profileAuthority === "default",
+		pathExists: fs.existsSync,
+	});
 }
 
 /** Dated log file name, shared by the canonical and effective log paths so they cannot drift. */

package/src/error-classification.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export const DESIGNED_ERROR = Symbol.for("gajae-code.designed-error");
+
+type MarkedError = object & { readonly [DESIGNED_ERROR]?: unknown };
+
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export function markDesignedError<T extends Error>(error: T): T {
+	Object.defineProperty(error, DESIGNED_ERROR, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false,
+	});
+	return error;
+}
+
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export function isDesignedError(error: unknown): boolean {
+	if ((typeof error !== "object" && typeof error !== "function") || error === null) return false;
+	try {
+		return (error as MarkedError)[DESIGNED_ERROR] === true;
+	} catch {
+		return false;
+	}
+}

package/src/index.ts

@@ -7,6 +7,7 @@ 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";

package/src/postmortem.ts

@@ -12,11 +12,17 @@ import inspector from "node:inspector";
 import * as path from "node:path";
 import { isMainThread } from "node:worker_threads";
 import { BROKEN_PIPE_EXIT_CODE, createProcessStdoutEpipeClassifier } from "./broken-pipe";
-import { type CrashFingerprint, computeCrashFingerprint, formatCrashRecordMarker } from "./crash-fingerprint";
+import {
+	type CrashFingerprint,
+	computeCrashFingerprint,
+	computeHandledErrorFingerprint,
+	formatCrashRecordMarker,
+} from "./crash-fingerprint";
 import type { CrashProvenance } from "./crash-journal";
 import { appendCrashEvent, appendFatalCrashEvent, detectCrashProvenance } from "./crash-journal";
 import { redactCrashSecrets } from "./crash-redaction";
 import { getCrashEventsPath, getCrashLogPath, getHandledErrorEventsPath, getHandledErrorLogPath } from "./dirs";
+import { isDesignedError } from "./error-classification";
 import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
@@ -512,9 +518,15 @@ export function recordHandledError(
 	options: HandledErrorRecordOptions = {},
 ): string | undefined {
 	try {
-		if (!(error instanceof Error) || typeof error.stack !== "string" || error.stack.length === 0) return undefined;
+		if (
+			!(error instanceof Error) ||
+			isDesignedError(error) ||
+			typeof error.stack !== "string" ||
+			error.stack.length === 0
+		)
+			return undefined;
 		const fatal = describeFatal(error);
-		const fingerprint = computeCrashFingerprint(fatal).fingerprint;
+		const fingerprint = computeHandledErrorFingerprint(fatal).fingerprint;
 		if (handledErrorFingerprints.has(fingerprint)) {
 			// Still hot: dedupe, but refresh recency so an actively failing class
 			// is not the one evicted under pressure.
@@ -530,6 +542,7 @@ export function recordHandledError(
 		const written = writeCrashRecord(label, fatal, {
 			path: options.path ?? getHandledErrorLogPath(),
 			now: options.now,
+			fingerprint: computeHandledErrorFingerprint(fatal),
 		});
 		if (!written) {
 			handledErrorFingerprints.delete(fingerprint);
@@ -562,6 +575,7 @@ interface CrashRecordOptions {
 	path?: string;
 	now?: Date;
 	provenance?: CrashProvenance;
+	fingerprint?: CrashFingerprint;
 }
 
 interface WrittenCrashRecord {
@@ -595,7 +609,7 @@ function writeCrashRecord(
 		const payload = fatal.payload ? `${redactCrashSecrets(fatal.payload)}\n` : "";
 		// Identity is computed from the already-captured diagnostic text only; the
 		// throwable is never read again here.
-		const fingerprint = computeCrashFingerprint(fatal);
+		const fingerprint = options.fingerprint ?? computeCrashFingerprint(fatal);
 		const recordId = randomBytes(8).toString("hex");
 		const markerLine = `${formatCrashRecordMarker(fingerprint.fingerprint, fingerprint.version, recordId)}\n`;
 		// The marker is the record's identity, so it is budgeted first and appended

package/src/sanitize-text.ts

@@ -17,6 +17,7 @@ const ESC_CHAR = "\x1b";
 // Well-formed strings only need control/ANSI detection: C0 (excl. \t \n),
 // CR, DEL, and C1. ESC (0x1B) is in \x0B-\x1F.
 const CONTROL_RE = /[\x00-\x08\x0B-\x1F\x7F-\x9F]/g;
+const DISPLAY_FORMAT_RE = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu;
 
 const REPLACEMENT_CHAR = "\ufffd";
 
@@ -34,10 +35,11 @@ export function sanitizeText(text: string): string {
  * {@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.
+ * single space before the usual control/ANSI strip, then remove directional
+ * format controls that can visually reorder an otherwise safe row.
  */
 export function sanitizeDisplayLine(text: string): string {
-	return sanitizeText(text.replace(/[\r\n]+/gu, " "));
+	return sanitizeText(text.replace(/[\r\n]+/gu, " ")).replace(DISPLAY_FORMAT_RE, "");
 }
 
 function sanitizeWellFormedText(text: string): string {