@gajae-code/utils 0.17.1 → 0.17.2

package/dist/types/dirs.d.ts

@@ -11,6 +11,8 @@
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, gjc trusts that the migration has been done.
  */
+import { canonicalEnvKey } from "./env-file";
+export { canonicalEnvKey };
 /** App name (e.g. "gjc") */
 export declare const APP_NAME: string;
 /** Config directory name (e.g. ".gjc") */
@@ -50,14 +52,6 @@ export declare function relativePathWithinRoot(root: string, candidate: string):
 export declare function getProjectDir(): string;
 /** Set the project directory. */
 export declare function setProjectDir(dir: string): void;
-/**
- * Windows environment variable names are case-insensitive, so a project dotenv
- * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
- * provenance lookup here is spelled in upper case, so the snapshot must be
- * keyed the same way or the declaration is invisible to the guard while still
- * being live in the process. POSIX names are case-sensitive and must not fold.
- */
-export declare function canonicalEnvKey(name: string): string;
 export declare function getConfigAgentDirName(): string;
 /** Get the config root directory (~/.gjc). */
 export declare function getConfigRootDir(): string;
@@ -109,6 +103,29 @@ export declare function getReportsDir(): string;
 export declare function getLogsDir(): string;
 /** Get the path to a dated log file (~/.gjc/logs/gjc.YYYY-MM-DD.log). */
 export declare function getLogPath(date?: Date): string;
+/**
+ * The logs directory the process actually reads and writes.
+ *
+ * A trusted `GJC_LOG_DIR` redirects the sink — the test preload pins it to a
+ * per-process temp directory so `bun test` stops appending fixture
+ * `level:error` records to the operator's shared log (issue #5618) — and
+ * everything else falls back to {@link getLogsDir}.
+ *
+ * The override is provenance-checked through the same {@link trustedValue} rule
+ * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise redirect where the
+ * operator's production logs are written. A dynamic (`$`/backtick) declaration
+ * is rejected there too, which fails closed onto the canonical path.
+ *
+ * This is deliberately *not* folded into {@link getLogsDir}: that function's
+ * config-root semantics are pinned by tests, and the preload sets `GJC_LOG_DIR`
+ * for every test process, so folding the override in would move it under every
+ * test. Writers and readers must both come through here instead — the split
+ * between the two is what let the transport and the log readers disagree.
+ */
+export declare function getEffectiveLogsDir(): string;
+/** Get the dated log file under {@link getEffectiveLogsDir}. */
+export declare function getEffectiveLogPath(date?: Date): string;
 /**
  * Get the plugins directory (~/.gjc/plugins or its XDG equivalent).
  *

package/dist/types/env-file.d.ts

@@ -32,3 +32,40 @@ export declare function parseShellEnvFile(filePath: string): Record<string, stri
 export declare function parseEnvFile(filePath: string): Record<string, string>;
 /** Parse dotenv content that has already been read from a trusted file. */
 export declare function parseEnvFileContent(content: string): Record<string, string>;
+/**
+ * What the caller's checkout declares through its dotenv files.
+ *
+ * `values` is the merged declaration set, later layers winning. `dynamic` holds
+ * the keys whose surviving declaration is one Bun expands at load time, which
+ * every provenance guard refuses outright because a value comparison cannot see
+ * what such a declaration became.
+ */
+export interface ProjectEnvSnapshot {
+    values: Record<string, string>;
+    dynamic: Set<string>;
+}
+/**
+ * Windows environment variable names are case-insensitive, so a project dotenv
+ * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
+ * provenance lookup is spelled in upper case, so the snapshot must be keyed the
+ * same way or the declaration is invisible to the guard while still being live
+ * in the process. POSIX names are case-sensitive and must not fold.
+ */
+export declare function canonicalEnvKey(name: string): string;
+/**
+ * The layered dotenv declarations Bun overlays into `process.env` for a cwd.
+ *
+ * Lives in this leaf module so every consumer shares ONE notion of provenance.
+ * `dirs.ts` resolves the config, agent and log directories from it, and
+ * `scripts/test-preload.ts` decides test isolation from it — a second, narrower
+ * reader (only `cwd/.env`, its own regex, its own dynamic test) is how a
+ * `GJC_LOG_DIR` declared in `.env.local` / `.env.$NODE_ENV` came to be honored
+ * by the preload and then rejected in production, silently routing test log
+ * records to the operator's canonical sink. This module imports only `node:fs`,
+ * `node:path` and the import-free `./spawn-env`, so importing it has no side
+ * effects and cannot freeze resolver state the way importing `dirs.ts` would.
+ *
+ * `.env.local` is deliberately skipped when `NODE_ENV === "test"`, matching the
+ * convention that a local override file is not part of a test run.
+ */
+export declare function projectEnvSnapshot(cwd?: string): ProjectEnvSnapshot;

package/package.json

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

package/src/dirs.ts

@@ -16,7 +16,15 @@ 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 { parseEnvFile } from "./env-file";
+import { canonicalEnvKey, type ProjectEnvSnapshot, projectEnvSnapshot } from "./env-file";
+
+// The provenance snapshot and its key fold live in the leaf `env-file` module so
+// `scripts/test-preload.ts` can share this exact logic without importing this
+// module (whose load-time resolver construction would freeze state before the
+// preload sets its isolation variables). Re-exported here because `env.ts` and
+// `test/env-provenance.windows.test.ts` import `canonicalEnvKey` from this
+// module's public surface.
+export { canonicalEnvKey };
 
 /** App name (e.g. "gjc") */
 export const APP_NAME: string = "gjc";
@@ -170,39 +178,6 @@ function sanitizeConfigDirName(value: string | undefined): string | undefined {
 	return trimmed;
 }
 
-/**
- * Windows environment variable names are case-insensitive, so a project dotenv
- * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
- * provenance lookup here is spelled in upper case, so the snapshot must be
- * keyed the same way or the declaration is invisible to the guard while still
- * being live in the process. POSIX names are case-sensitive and must not fold.
- */
-export function canonicalEnvKey(name: string): string {
-	return process.platform === "win32" ? name.toUpperCase() : name;
-}
-
-function projectEnvSnapshot(cwd = process.cwd()): { values: Record<string, string>; dynamic: Set<string> } {
-	const nodeEnv = process.env.NODE_ENV;
-	const validNodeEnv = nodeEnv && /^[A-Za-z0-9_-]+$/.test(nodeEnv) ? nodeEnv : undefined;
-	const files = [
-		".env",
-		...(validNodeEnv ? [`.env.${validNodeEnv}`] : []),
-		...(validNodeEnv !== "test" ? [".env.local"] : []),
-		...(validNodeEnv ? [`.env.${validNodeEnv}.local`] : []),
-	];
-	const values: Record<string, string> = {};
-	const dynamic = new Set<string>();
-	for (const file of files) {
-		for (const [rawKey, value] of Object.entries(parseEnvFile(path.join(cwd, file)))) {
-			const key = canonicalEnvKey(rawKey);
-			values[key] = value;
-			if (/[$`]/.test(value)) dynamic.add(key);
-			else dynamic.delete(key);
-		}
-	}
-	return { values, dynamic };
-}
-
 /**
  * Resolve an environment value only when it is not supplied by the caller's
  * project dotenv (or when the inherited value is observably distinct).
@@ -220,10 +195,7 @@ function projectEnvSnapshot(cwd = process.cwd()): { values: Record<string, strin
  * happens to carry the identical value loses the override, which is the same
  * trade-off `resolveLiveCredentialEnvValue` already makes.
  */
-function trustedValue(
-	name: string,
-	project: { values: Record<string, string>; dynamic: Set<string> },
-): string | undefined {
+function trustedValue(name: string, project: ProjectEnvSnapshot): string | undefined {
 	const value = process.env[name];
 	if (!value) return undefined;
 	const key = canonicalEnvKey(name);
@@ -232,7 +204,7 @@ function trustedValue(
 	return value;
 }
 
-function resolveConfigDirName(project: { values: Record<string, string>; dynamic: Set<string> }): string {
+function resolveConfigDirName(project: ProjectEnvSnapshot): string {
 	return (
 		sanitizeConfigDirName(trustedValue("GJC_CONFIG_DIR", project)) ??
 		sanitizeConfigDirName(trustedValue("PI_CONFIG_DIR", project)) ??
@@ -369,7 +341,7 @@ function accountHomeFromSystem(): AccountHome | undefined {
  * per call is what makes the contract call-time; the provenance comparison above
  * is what keeps an untrusted mutable home from being honored.
  */
-function resolveTrustedHome(project: { values: Record<string, string>; dynamic: Set<string> }): string {
+function resolveTrustedHome(project: ProjectEnvSnapshot): string {
 	const authoritativeHomeKey = process.platform === "win32" ? "USERPROFILE" : "HOME";
 	const declaredHomeKey = canonicalEnvKey(authoritativeHomeKey);
 	const declaredHome = project.values[declaredHomeKey];
@@ -425,7 +397,7 @@ type XdgCategory = "data" | "state" | "cache";
 class DirResolver {
 	configRoot: string;
 	agentDir: string;
-	readonly #projectEnv: { values: Record<string, string>; dynamic: Set<string> };
+	readonly #projectEnv: ProjectEnvSnapshot;
 	#configDirName: string;
 	readonly #agentDirOverride: boolean;
 	#trustedHome: string;
@@ -491,10 +463,7 @@ class DirResolver {
 	 * change storage lane when a home refresh made its path coincide with the
 	 * new default.
 	 */
-	private refreshCategoryDirs(
-		snapshot: { values: Record<string, string>; dynamic: Set<string> },
-		isDefault: boolean,
-	): void {
+	private refreshCategoryDirs(snapshot: ProjectEnvSnapshot, isDefault: boolean): void {
 		let xdgData: string | undefined;
 		let xdgState: string | undefined;
 		let xdgCache: string | undefined;
@@ -619,7 +588,7 @@ class DirResolver {
 		this.refreshConfigDirOverride();
 		if (!this.#homeAvailable) throw new Error("User state is unavailable: no trustworthy home directory");
 	}
-	get trustSnapshot(): { values: Record<string, string>; dynamic: Set<string> } {
+	get trustSnapshot(): ProjectEnvSnapshot {
 		return this.#projectEnv;
 	}
 }
@@ -735,9 +704,44 @@ export function getLogsDir(): string {
 	return dirs.rootSubdir("logs", "state");
 }
 
+/** Dated log file name, shared by the canonical and effective log paths so they cannot drift. */
+function datedLogFileName(date: Date): string {
+	return `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`;
+}
+
 /** Get the path to a dated log file (~/.gjc/logs/gjc.YYYY-MM-DD.log). */
 export function getLogPath(date = new Date()): string {
-	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`);
+	return path.join(getLogsDir(), datedLogFileName(date));
+}
+
+/**
+ * The logs directory the process actually reads and writes.
+ *
+ * A trusted `GJC_LOG_DIR` redirects the sink — the test preload pins it to a
+ * per-process temp directory so `bun test` stops appending fixture
+ * `level:error` records to the operator's shared log (issue #5618) — and
+ * everything else falls back to {@link getLogsDir}.
+ *
+ * The override is provenance-checked through the same {@link trustedValue} rule
+ * as the config and agent directories: Bun loads `cwd/.env` into `process.env`
+ * before any module runs, so a repository could otherwise redirect where the
+ * operator's production logs are written. A dynamic (`$`/backtick) declaration
+ * is rejected there too, which fails closed onto the canonical path.
+ *
+ * This is deliberately *not* folded into {@link getLogsDir}: that function's
+ * config-root semantics are pinned by tests, and the preload sets `GJC_LOG_DIR`
+ * for every test process, so folding the override in would move it under every
+ * test. Writers and readers must both come through here instead — the split
+ * between the two is what let the transport and the log readers disagree.
+ */
+export function getEffectiveLogsDir(): string {
+	const override = trustedValue("GJC_LOG_DIR", dirs.trustSnapshot)?.trim();
+	return override || getLogsDir();
+}
+
+/** Get the dated log file under {@link getEffectiveLogsDir}. */
+export function getEffectiveLogPath(date = new Date()): string {
+	return path.join(getEffectiveLogsDir(), datedLogFileName(date));
 }
 
 /**

package/src/env-file.ts

@@ -6,6 +6,7 @@
  * below both of them.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { isSafeEnvValue } from "./spawn-env";
 
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -155,3 +156,65 @@ export function parseEnvFileContent(content: string): Record<string, string> {
 
 	return result;
 }
+
+/**
+ * What the caller's checkout declares through its dotenv files.
+ *
+ * `values` is the merged declaration set, later layers winning. `dynamic` holds
+ * the keys whose surviving declaration is one Bun expands at load time, which
+ * every provenance guard refuses outright because a value comparison cannot see
+ * what such a declaration became.
+ */
+export interface ProjectEnvSnapshot {
+	values: Record<string, string>;
+	dynamic: Set<string>;
+}
+
+/**
+ * Windows environment variable names are case-insensitive, so a project dotenv
+ * line `userprofile=...` is what `process.env.USERPROFILE` resolves to. Every
+ * provenance lookup is spelled in upper case, so the snapshot must be keyed the
+ * same way or the declaration is invisible to the guard while still being live
+ * in the process. POSIX names are case-sensitive and must not fold.
+ */
+export function canonicalEnvKey(name: string): string {
+	return process.platform === "win32" ? name.toUpperCase() : name;
+}
+
+/**
+ * The layered dotenv declarations Bun overlays into `process.env` for a cwd.
+ *
+ * Lives in this leaf module so every consumer shares ONE notion of provenance.
+ * `dirs.ts` resolves the config, agent and log directories from it, and
+ * `scripts/test-preload.ts` decides test isolation from it — a second, narrower
+ * reader (only `cwd/.env`, its own regex, its own dynamic test) is how a
+ * `GJC_LOG_DIR` declared in `.env.local` / `.env.$NODE_ENV` came to be honored
+ * by the preload and then rejected in production, silently routing test log
+ * records to the operator's canonical sink. This module imports only `node:fs`,
+ * `node:path` and the import-free `./spawn-env`, so importing it has no side
+ * effects and cannot freeze resolver state the way importing `dirs.ts` would.
+ *
+ * `.env.local` is deliberately skipped when `NODE_ENV === "test"`, matching the
+ * convention that a local override file is not part of a test run.
+ */
+export function projectEnvSnapshot(cwd = process.cwd()): ProjectEnvSnapshot {
+	const nodeEnv = process.env.NODE_ENV;
+	const validNodeEnv = nodeEnv && /^[A-Za-z0-9_-]+$/.test(nodeEnv) ? nodeEnv : undefined;
+	const files = [
+		".env",
+		...(validNodeEnv ? [`.env.${validNodeEnv}`] : []),
+		...(validNodeEnv !== "test" ? [".env.local"] : []),
+		...(validNodeEnv ? [`.env.${validNodeEnv}.local`] : []),
+	];
+	const values: Record<string, string> = {};
+	const dynamic = new Set<string>();
+	for (const file of files) {
+		for (const [rawKey, value] of Object.entries(parseEnvFile(path.join(cwd, file)))) {
+			const key = canonicalEnvKey(rawKey);
+			values[key] = value;
+			if (/[$`]/.test(value)) dynamic.add(key);
+			else dynamic.delete(key);
+		}
+	}
+	return { values, dynamic };
+}

package/src/logger.ts

@@ -12,7 +12,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
 import type * as winston from "winston";
-import { getLogsDir } from "./dirs";
+import { getEffectiveLogsDir } from "./dirs";
 
 /** Ensure a logs directory exists; return the resolved path. */
 function ensureDir(dir: string): string {
@@ -73,10 +73,22 @@ function makeLogFormat(winston: WinstonModule): winston.Logform.Format {
 	);
 }
 
-/** Build a rotating file transport, materializing the target directory lazily. */
+/**
+ * Build a rotating file transport, materializing the target directory lazily.
+ *
+ * Destination precedence:
+ *   1. `dir` — an explicit path from {@link setTransports}(`{ file: "<path>" }`).
+ *   2. {@link getEffectiveLogsDir} — the provenance-checked `GJC_LOG_DIR`
+ *      override, else the real config root (`~/.gjc/logs`).
+ *
+ * The resolution is centralized in `dirs.ts` rather than read from the
+ * environment here: the log *readers* (report bundles, the debug log view, the
+ * HTTP dump directory) call the same helper, and a second env read in this file
+ * is what let the transport write somewhere the readers never looked.
+ */
 function makeFileTransport(DailyRotateFile: DailyRotateFileCtor, dir?: string): Transport {
 	return new DailyRotateFile({
-		dirname: ensureDir(dir ?? getLogsDir()),
+		dirname: ensureDir(dir ?? getEffectiveLogsDir()),
 		filename: "gjc.%DATE%.log",
 		datePattern: "YYYY-MM-DD",
 		maxSize: "10m",