@gajae-code/utils 0.4.4 → 0.5.0

package/dist/types/dirs.d.ts

@@ -18,6 +18,22 @@ export declare const CONFIG_DIR_NAME: string;
 export declare const VERSION: string;
 /** Minimum Bun version */
 export declare const MIN_BUN_VERSION: string;
+/**
+ * Build the diagnostic shown when the Bun runtime executing `gjc` is older
+ * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
+ * failure (issue #525): `bun install -g gajae-code` probes a recent Bun while
+ * the `gjc` launcher resolves an older Bun still on PATH. The message names the
+ * exact detected runtime path and gives a platform-specific upgrade + PATH fix
+ * instead of a bare `bun upgrade`.
+ *
+ * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ */
+export declare function formatBunRuntimeError(opts: {
+    currentVersion: string;
+    minVersion: string;
+    execPath?: string;
+    platform?: NodeJS.Platform;
+}): string;
 export declare function resolveEquivalentPath(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string): string;
 export declare function pathIsWithin(root: string, candidate: string): boolean;

package/dist/types/env.d.ts

@@ -37,6 +37,9 @@ export declare function $inheritedEnv(name: string): string | undefined;
  * All users should import this env module (import { $env } from "@gajae-code/utils")
  * before using environment variables. This ensures that .env files have been loaded and
  * overrides (project, home) have been applied, so $env always reflects the correct values.
+ *
+ * Provider credential resolution must not use this merged view because it includes the
+ * caller's cwd/.env. Use $credentialEnv/$pickCredentialEnv for model authentication.
  */
 export declare const $env: Record<string, string>;
 /**
@@ -45,6 +48,17 @@ export declare const $env: Record<string, string>;
  * @returns The first environment variable value, or undefined if no value is found.
  */
 export declare function $pickenv(...keys: string[]): string | undefined;
+/**
+ * Resolve credential-bearing environment variables without consulting the caller's project .env.
+ *
+ * GJC loads cwd/.env into $env for project-aware tools, but model-provider authentication should
+ * only use values explicitly inherited from the launching shell or GJC/user-owned config files.
+ */
+export declare function $credentialEnv(name: string): string | undefined;
+/**
+ * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
+ */
+export declare function $pickCredentialEnv(...keys: string[]): string | undefined;
 /**
  * Parses a positive decimal integer from `$env[name]`.
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.

package/package.json

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

package/src/dirs.ts

@@ -28,6 +28,58 @@ export const VERSION: string = version;
 /** Minimum Bun version */
 export const MIN_BUN_VERSION: string = engines.bun.replace(/[^0-9.]/g, "");
 
+/**
+ * Build the diagnostic shown when the Bun runtime executing `gjc` is older
+ * than {@link MIN_BUN_VERSION}. This is the most common Windows native-install
+ * failure (issue #525): `bun install -g gajae-code` probes a recent Bun while
+ * the `gjc` launcher resolves an older Bun still on PATH. The message names the
+ * exact detected runtime path and gives a platform-specific upgrade + PATH fix
+ * instead of a bare `bun upgrade`.
+ *
+ * Pure and platform-parameterized so it can be unit-tested cross-platform.
+ */
+export function formatBunRuntimeError(opts: {
+	currentVersion: string;
+	minVersion: string;
+	execPath?: string;
+	platform?: NodeJS.Platform;
+}): string {
+	const platform = opts.platform ?? process.platform;
+	const lines = [
+		`error: ${APP_NAME} requires Bun >= ${opts.minVersion}, but the running Bun is v${opts.currentVersion}.`,
+	];
+	if (opts.execPath) {
+		lines.push(`  detected Bun runtime: ${opts.execPath}`);
+	}
+	if (platform === "win32") {
+		lines.push(
+			"",
+			"The 'gjc' launcher is using an older Bun than the one used to install it.",
+			"Upgrade Bun, then restart your terminal so PATH and the runtime refresh:",
+			"",
+			'  powershell -c "irm bun.sh/install.ps1|iex"',
+			"",
+			"After restarting the terminal, verify both versions match:",
+			"  bun --version",
+			"  gjc --version",
+			"",
+			"If 'gjc' still loads the old runtime, make sure %USERPROFILE%\\.bun\\bin is",
+			"first on PATH and remove any stale Bun installs shadowing it.",
+		);
+	} else {
+		lines.push(
+			"",
+			"Upgrade Bun, then restart your terminal:",
+			"  bun upgrade",
+			"",
+			"Then verify:",
+			"  bun --version",
+			"  gjc --version",
+		);
+	}
+	return `${lines.join("\n")}\n`;
+}
+
 // =============================================================================
 // Project directory
 // =============================================================================

package/src/env.ts

@@ -135,16 +135,32 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 	return result;
 }
 
-const inheritedEnv = filterProcessEnv(Bun.env);
-
-export function $inheritedEnv(name: string): string | undefined {
+function resolveFileEnvValue(file: Record<string, string>, name: string): string | undefined {
 	if (!isSafeEnvName(name)) return undefined;
-	const value = inheritedEnv[name];
+	const value = file[name];
 	if (value === undefined || !isSafeEnvValue(value)) return undefined;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+function filterCredentialInheritedEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const result: Record<string, string> = {};
+	for (const key in env) {
+		const value = env[key];
+		if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) continue;
+
+		// Bun may have already loaded cwd/.env before JS runs. It does not expose the
+		// source of each entry, so an exact match with projectEnv is ambiguous. Use
+		// the safer credential rule: ambiguous project matches are excluded from the
+		// credential-only inherited snapshot, while remaining available through $env.
+		const projectValue = resolveFileEnvValue(projectEnv, key);
+		if (projectValue !== undefined && projectValue === value) continue;
+
+		result[key] = value;
+	}
+	return result;
+}
+
 // Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
 const homeShellEnv = {
 	...parseShellEnvFile(path.join(os.homedir(), ".zshenv")),
@@ -158,11 +174,29 @@ const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
 const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
 const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
 
-for (const key of Object.keys(Bun.env)) {
-	const value = Bun.env[key];
-	if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) {
-		delete Bun.env[key];
+const inheritedEnv = filterCredentialInheritedEnv(Bun.env);
+
+export function $inheritedEnv(name: string): string | undefined {
+	return resolveFileEnvValue(inheritedEnv, name);
+}
+
+function resolveLiveCredentialEnvValue(name: string): string | undefined {
+	if (!isSafeEnvName(name)) return undefined;
+	const value = Bun.env[name];
+	if (value === undefined || !isSafeEnvValue(value)) return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+
+	const projectValue = resolveFileEnvValue(projectEnv, name);
+	if (
+		projectValue !== undefined &&
+		projectValue === trimmed &&
+		resolveFileEnvValue(inheritedEnv, name) === undefined
+	) {
+		return undefined;
 	}
+
+	return trimmed;
 }
 
 for (const file of [projectEnv, agentEnv, piEnv, homeEnv, homeShellEnv]) {
@@ -179,6 +213,9 @@ for (const file of [projectEnv, agentEnv, piEnv, homeEnv, homeShellEnv]) {
  * All users should import this env module (import { $env } from "@gajae-code/utils")
  * before using environment variables. This ensures that .env files have been loaded and
  * overrides (project, home) have been applied, so $env always reflects the correct values.
+ *
+ * Provider credential resolution must not use this merged view because it includes the
+ * caller's cwd/.env. Use $credentialEnv/$pickCredentialEnv for model authentication.
  */
 export const $env: Record<string, string> = Bun.env as Record<string, string>;
 
@@ -197,6 +234,34 @@ export function $pickenv(...keys: string[]): string | undefined {
 	return undefined;
 }
 
+/**
+ * Resolve credential-bearing environment variables without consulting the caller's project .env.
+ *
+ * GJC loads cwd/.env into $env for project-aware tools, but model-provider authentication should
+ * only use values explicitly inherited from the launching shell or GJC/user-owned config files.
+ */
+export function $credentialEnv(name: string): string | undefined {
+	return (
+		$inheritedEnv(name) ??
+		resolveLiveCredentialEnvValue(name) ??
+		resolveFileEnvValue(agentEnv, name) ??
+		resolveFileEnvValue(piEnv, name) ??
+		resolveFileEnvValue(homeEnv, name) ??
+		resolveFileEnvValue(homeShellEnv, name)
+	);
+}
+
+/**
+ * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
+ */
+export function $pickCredentialEnv(...keys: string[]): string | undefined {
+	for (const key of keys) {
+		const value = $credentialEnv(key);
+		if (value) return value;
+	}
+	return undefined;
+}
+
 /**
  * Parses a positive decimal integer from `$env[name]`.
  * Empty, invalid, NaN, zero, or negative values return `defaultValue`.