@gajae-code/utils 0.16.7 → 0.17.1

package/dist/types/dirs.d.ts

@@ -80,6 +80,13 @@ export declare function getTrustedConfigRootDir(): string;
  * selection and resolve the same storage lane.
  */
 export declare function setAgentDir(dir: string): void;
+/**
+ * Rebuild the resolver from the current trusted environment. Callers that
+ * temporarily used {@link setAgentDir} must first restore the original
+ * GJC_CODING_AGENT_DIR / PI_CODING_AGENT_DIR values, then call this function;
+ * an originally absent override remains absent and keeps following HOME.
+ */
+export declare function resetAgentDirFromEnvironment(): void;
 /** Get the agent config directory (~/.gjc/agent). */
 export declare function getAgentDir(): string;
 /** Resolver-owned profile classification, stable across HOME refreshes. */

package/dist/types/index.d.ts

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

@@ -39,16 +39,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.
  */

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 "@gajae-code/utils";
+ *
+ * try {
+ *     await risky();
+ * } catch (error) {
+ *     logger.warn("risky failed", { error: safeErrorDescription(error) });
+ * }
+ * ```
+ */
+export declare function safeErrorDescription(value: unknown): string;

package/package.json

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

package/src/crash-redaction.ts

@@ -25,6 +25,16 @@ export function redactCrashSecrets(text: string): string {
 	redacted = redacted.replace(/\bgh[opsur]_[A-Za-z0-9]{16,}\b/g, "«redacted-github-token»");
 	redacted = redacted.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "«redacted-github-token»");
 	redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g, "«redacted-slack-token»");
+	// The five shapes below are the ones `crash/upstream/envelope.ts` already
+	// classifies as credential-like and refuses to transmit. That refusal only
+	// guards the Sentry frame fields; the persisted crash log and the
+	// `gjc crash report` body — which the user files as a public issue — reach
+	// egress through this function alone, so the same shapes have to be named here.
+	redacted = redacted.replace(/\bnpm_[A-Za-z0-9]{20,}\b/g, "«redacted-npm-token»");
+	redacted = redacted.replace(/\bglpat-[A-Za-z0-9_-]{20,}\b/g, "«redacted-gitlab-token»");
+	// Stripe separates with `_`, so the `sk-` rule above never matched one.
+	redacted = redacted.replace(/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, "«redacted-api-key»");
+	redacted = redacted.replace(/\bhf_[A-Za-z0-9]{20,}\b/g, "«redacted-api-key»");
 	// A PEM block carries the key material itself, so it is redacted whole rather
 	// than line by line. It runs before the narrower rules because they would
 	// otherwise chew on the base64 body and leave a truncated key behind.
@@ -70,6 +80,8 @@ export const CRASH_REDACTION_MARKERS: readonly string[] = [
 	"«redacted-api-key»",
 	"«redacted-github-token»",
 	"«redacted-slack-token»",
+	"«redacted-npm-token»",
+	"«redacted-gitlab-token»",
 	"«redacted-aws-key»",
 	"«redacted-private-key»",
 	"«redacted-google-api-key»",

package/src/dirs.ts

@@ -673,6 +673,18 @@ export function setAgentDir(dir: string): void {
 	process.env.GJC_CODING_AGENT_DIR = dir;
 }
 
+/**
+ * Rebuild the resolver from the current trusted environment. Callers that
+ * temporarily used {@link setAgentDir} must first restore the original
+ * GJC_CODING_AGENT_DIR / PI_CODING_AGENT_DIR values, then call this function;
+ * an originally absent override remains absent and keeps following HOME.
+ */
+export function resetAgentDirFromEnvironment(): void {
+	const snapshot = dirs.trustSnapshot;
+	const override = trustedValue("GJC_CODING_AGENT_DIR", snapshot) ?? trustedValue("PI_CODING_AGENT_DIR", snapshot);
+	dirs = new DirResolver(override, snapshot);
+}
+
 /** Get the agent config directory (~/.gjc/agent). */
 export function getAgentDir(): string {
 	dirs.refreshConfigDirOverride();
@@ -743,7 +755,14 @@ export function getPluginsDir(home?: string): string {
 	if (home !== undefined) {
 		const explicitPath = () => path.join(home, resolveConfigDirName(dirs.trustSnapshot), "plugins");
 		try {
-			if (home !== dirs.trustedHome) return explicitPath();
+			const canonical = (value: string): string => {
+				try {
+					return fs.realpathSync.native(value);
+				} catch {
+					return path.resolve(value);
+				}
+			};
+			if (canonical(home) !== canonical(dirs.trustedHome)) return explicitPath();
 		} catch {
 			// An explicit home is the caller's documented escape hatch. If the
 			// authoritative home is unavailable, do not let its fail-closed resolver

package/src/index.ts

@@ -24,6 +24,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/src/logger.ts

@@ -94,6 +94,7 @@ function applyTransports(
 	modules: { winston: WinstonModule; DailyRotateFile: DailyRotateFileCtor },
 ): void {
 	logger.clear();
+	logger.silent = !transportOptions.console && !transportOptions.file;
 	if (transportOptions.file) {
 		logger.add(
 			makeFileTransport(
@@ -249,21 +250,21 @@ export function printTimings(): void {
 	}
 
 	gRootSpan.end = performance.now();
+	// Close still-open spans (e.g. cli:dispatch, which wraps the very run that
+	// prints) so they report elapsed-at-print instead of a misleading 0ms.
+	const root = gRootSpan;
+	const printNow = root.end;
+	const closeOpenSpans = (span: Span): void => {
+		for (const child of span.children) closeOpenSpans(child);
+		if (span.end === undefined && !span.point) span.end = printNow;
+	};
+	closeOpenSpans(root);
 	const lines: string[] = [];
 	lines.push("");
 	lines.push("--- Startup timings (hierarchical) ---");
-	const work: Span[] = [];
-	const loads: Span[] = [];
-	for (const child of gRootSpan.children) {
-		if (isModuleLoadSpan(child)) loads.push(child);
-		else work.push(child);
-	}
-	for (const child of work.sort((a, b) => a.start - b.start)) {
+	for (const child of [...gRootSpan.children].sort((a, b) => a.start - b.start)) {
 		printSpan(child, 0, lines);
 	}
-	if (loads.length > 0) {
-		printModuleLoadSummary(loads, 0, lines);
-	}
 	const totalMs = (gRootSpan.end - gRootSpan.start).toFixed(1);
 	lines.push(`Total: ${totalMs}ms`);
 	lines.push("--------------------------------------");
@@ -274,46 +275,28 @@ export 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 function startTiming(): void {
 	if (gRecordTimings) return;
 	gRootSpan = {
 		op: "(root)",
-		start: performance.now(),
+		start: 0,
 		parent: undefined,
 		children: [],
 	};
 	gRecordTimings = true;
 }
 
-/**
- * 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 function recordModuleLoadSpan(path: string, start: number, durationMs: number): void {
-	if (!gRecordTimings || !gRootSpan) return;
-	const parent = spanStorage.getStore() ?? gRootSpan;
-	const span: Span = {
-		op: `load:${shortenLoadPath(path)}`,
-		start,
-		end: start + durationMs,
-		parent,
-		children: [],
-	};
-	parent.children.push(span);
-}
-
-function shortenLoadPath(p: string): string {
-	const cwd = process.cwd();
-	if (p.startsWith(`${cwd}/`)) return p.slice(cwd.length + 1);
-	const home = process.env.HOME;
-	if (home && p.startsWith(`${home}/`)) return `~/${p.slice(home.length + 1)}`;
-	return p;
-}
-
 /**
  * End timing window and clear buffers.
  */
@@ -359,13 +342,6 @@ function fmtMs(ms: number): string {
 	return `${ms.toFixed(0)}ms`;
 }
 
-const MODULE_LOAD_PREFIX = "load:";
-const MODULE_LOAD_VERBOSE_TOP = 10;
-
-function isModuleLoadSpan(span: Span): boolean {
-	return span.op.startsWith(MODULE_LOAD_PREFIX);
-}
-
 function printSpan(span: Span, depth: number, lines: string[]): void {
 	const indent = "  ".repeat(depth);
 	if (span.point) {
@@ -380,51 +356,9 @@ function printSpan(span: Span, depth: number, lines: string[]): void {
 	const selfStr = span.children.length > 0 && self > LOGGED_TIMING_THRESHOLD_MS ? ` (self ${fmtMs(self)})` : "";
 	lines.push(`${indent}${span.op}: ${fmtMs(dur)}${selfStr}${tag}`);
 
-	// Split children into work spans and module-load spans for summarization.
-	const work: Span[] = [];
-	const loads: Span[] = [];
-	for (const child of span.children) {
-		if (isModuleLoadSpan(child)) loads.push(child);
-		else work.push(child);
-	}
-	for (const child of work.sort((a, b) => a.start - b.start)) {
+	for (const child of [...span.children].sort((a, b) => a.start - b.start)) {
 		printSpan(child, depth + 1, lines);
 	}
-	if (loads.length > 0) {
-		printModuleLoadSummary(loads, depth + 1, lines);
-	}
-}
-
-/** Collapse the (typically hundreds of) module-load spans into one summary line. */
-function printModuleLoadSummary(loads: Span[], depth: number, lines: string[]): void {
-	const childIndent = "  ".repeat(depth);
-	const grandIndent = "  ".repeat(depth + 1);
-	let unionStart = Number.POSITIVE_INFINITY;
-	let unionEnd = 0;
-	let totalSelf = 0;
-	for (const span of loads) {
-		if (span.end === undefined) continue;
-		if (span.start < unionStart) unionStart = span.start;
-		if (span.end > unionEnd) unionEnd = span.end;
-		totalSelf += span.end - span.start;
-	}
-	const wall = unionEnd > unionStart ? unionEnd - unionStart : 0;
-	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}, sum ${fmtMs(totalSelf)}`);
-	// Resolve GJC-first with PI fallback inline (no ./env import) so this
-	// foundational logger stays off the env module's dependency graph, which the
-	// tab-worker native-free runtime contract (issue-2598-repro) walks.
-	const showAll = (process.env.GJC_TIMING?.trim() || process.env.PI_TIMING?.trim()) === "full";
-	const sorted = [...loads].sort((a, b) => durationOf(b) - durationOf(a));
-	const visible = showAll ? sorted : sorted.slice(0, MODULE_LOAD_VERBOSE_TOP);
-	for (const span of visible) {
-		const dur = durationOf(span);
-		if (dur < LOGGED_TIMING_THRESHOLD_MS) break;
-		const tag = isParallel(span) ? " [parallel]" : "";
-		lines.push(`${grandIndent}${span.op}: ${fmtMs(dur)}${tag}`);
-	}
-	if (!showAll && sorted.length > MODULE_LOAD_VERBOSE_TOP) {
-		lines.push(`${grandIndent}… ${sorted.length - MODULE_LOAD_VERBOSE_TOP} more (PI_TIMING=full to show all)`);
-	}
 }
 
 /** A span is parallel if it overlaps a sibling that started before it. */

package/src/safe-error.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 "@gajae-code/utils";
+ *
+ * try {
+ *     await risky();
+ * } catch (error) {
+ *     logger.warn("risky failed", { error: safeErrorDescription(error) });
+ * }
+ * ```
+ */
+export function safeErrorDescription(value: unknown): string {
+	let isError = false;
+	try {
+		isError = value instanceof Error;
+	} catch {
+		// Hostile proxies can throw from getPrototypeOf during instanceof.
+	}
+	if (isError) {
+		try {
+			const message = (value as { message?: unknown }).message;
+			if (typeof message === "string") return message;
+		} catch {
+			// Hostile error getters must not replace the primary failure.
+		}
+	}
+	try {
+		return String(value);
+	} catch {
+		return "<unprintable error>";
+	}
+}