@gajae-code/utils 0.4.5 → 0.5.1

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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.4.5",
+	"version": "0.5.1",
 	"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.5",
+		"@gajae-code/natives": "0.5.1",
 		"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

@@ -180,6 +180,25 @@ 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]) {
 	for (const key in file) {
 		if (!Bun.env[key]) {
@@ -224,6 +243,7 @@ export function $pickenv(...keys: string[]): string | undefined {
 export function $credentialEnv(name: string): string | undefined {
 	return (
 		$inheritedEnv(name) ??
+		resolveLiveCredentialEnvValue(name) ??
 		resolveFileEnvValue(agentEnv, name) ??
 		resolveFileEnvValue(piEnv, name) ??
 		resolveFileEnvValue(homeEnv, name) ??