fix(build): use build-time constants for binary detection and pretty stream logger (#982)

* fix(build): use build-time constants for binary detection and pretty stream logger

Replaces runtime detection of compiled binaries (env sniffing via
import.meta.dir / process.execPath) with a build-time BUNDLED_IS_BINARY
constant in @archon/paths/bundled-build.ts, rewritten by
scripts/build-binaries.sh and restored on EXIT via a trap.

Also rewrites @archon/paths/logger.ts to use pino-pretty as a destination
stream instead of a worker-thread transport. The formatter now runs on
the main thread, eliminating the require.resolve('pino-pretty') lookup
that crashes inside Bun's /\$bunfs/ virtual filesystem in compiled
binaries. The same code path runs in dev and binaries — no environment
detection in the logger at all.

isBinaryBuild() in @archon/workflows is kept as a one-line wrapper
around BUNDLED_IS_BINARY so existing spyOn-based test mocking in
loader.test.ts continues to work without modification.

Closes #960
Closes #961
Closes #979
Supersedes #962
Supersedes #963

Co-Authored-By: leex279 <leex279@users.noreply.github.com>

* style(workflows): hoist BUNDLED_IS_BINARY import to top of file

* fix(build,logger): harden pretty init and trap restore

- logger: wrap pino-pretty init in try/catch and fall back to JSON so a
  broken TTY or missing peer can't crash module load.
- build-binaries.sh: drop '2>/dev/null || true' from the EXIT trap so a
  failed bundled-build.ts restore is visible instead of silently leaving
  the dev tree with BUNDLED_IS_BINARY=true.
- bundled-defaults: unmark isBinaryBuild() @deprecated and document why
  the wrapper is the intentional test seam (mock.module pollution in Bun).

---------

Co-authored-by: leex279 <leex279@users.noreply.github.com>

Author: Wirasm

bun.lock

@@ -1,17 +1,21 @@
 /**
  * Version command - displays version info
  *
- * For compiled binaries, version and git commit are embedded via bundled-version.ts
- * For development (Bun), reads from package.json and retrieves git commit at runtime
+ * For compiled binaries, version and git commit are embedded via `@archon/paths`
+ * build-time constants (rewritten by `scripts/build-binaries.sh`).
+ * For development (Bun), reads from package.json and retrieves git commit at runtime.
  */
 import { readFile } from 'fs/promises';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { execFileAsync } from '@archon/git';
-import { createLogger } from '@archon/paths';
+import {
+  BUNDLED_GIT_COMMIT,
+  BUNDLED_IS_BINARY,
+  BUNDLED_VERSION,
+  createLogger,
+} from '@archon/paths';
 import { getDatabaseType } from '@archon/core';
-import { isBinaryBuild } from '@archon/workflows/defaults';
-import { BUNDLED_VERSION, BUNDLED_GIT_COMMIT } from './bundled-version';
 
 const log = createLogger('cli:version');
 
@@ -72,7 +76,7 @@ export async function versionCommand(): Promise<void> {
   let version: string;
   let gitCommit: string;
 
-  if (isBinaryBuild()) {
+  if (BUNDLED_IS_BINARY) {
     // Compiled binary: use embedded version and commit
     version = BUNDLED_VERSION;
     gitCommit = BUNDLED_GIT_COMMIT;
@@ -86,7 +90,7 @@ export async function versionCommand(): Promise<void> {
   const platform = process.platform;
   const arch = process.arch;
   const dbType = getDatabaseType();
-  const buildType = isBinaryBuild() ? 'binary' : 'source (bun)';
+  const buildType = BUNDLED_IS_BINARY ? 'binary' : 'source (bun)';
 
   console.log(`Archon CLI v${version}`);
   console.log(`  Platform: ${platform}-${arch}`);

packages/cli/src/commands/bundled-version.ts

@@ -12,9 +12,7 @@
     "type-check": "bun x tsc --noEmit"
   },
   "dependencies": {
-    "pino": "^9"
-  },
-  "optionalDependencies": {
+    "pino": "^9",
     "pino-pretty": "^13"
   },
   "peerDependencies": {

packages/cli/src/commands/version.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'bun:test';
+import { BUNDLED_GIT_COMMIT, BUNDLED_IS_BINARY, BUNDLED_VERSION } from './bundled-build';
+
+describe('bundled-build', () => {
+  // In dev/test mode the placeholders must be the dev defaults.
+  // `scripts/build-binaries.sh` rewrites this file only during binary
+  // compilation and restores it afterwards via an EXIT trap.
+  it('BUNDLED_IS_BINARY is false in dev mode', () => {
+    expect(BUNDLED_IS_BINARY).toBe(false);
+  });
+
+  it('BUNDLED_VERSION is the dev placeholder', () => {
+    expect(BUNDLED_VERSION).toBe('dev');
+  });
+
+  it('BUNDLED_GIT_COMMIT is the dev placeholder', () => {
+    expect(BUNDLED_GIT_COMMIT).toBe('unknown');
+  });
+});

packages/paths/package.json

@@ -0,0 +1,18 @@
+/**
+ * Build-time constants embedded into compiled binaries.
+ *
+ * In dev/test mode, the placeholders below are used and BUNDLED_IS_BINARY
+ * is `false`. Compiled binaries get this file overwritten by
+ * `scripts/build-binaries.sh` before `bun build --compile` is invoked,
+ * and restored afterwards via an EXIT trap.
+ *
+ * Lives in `@archon/paths` (the bottom of the dep graph) so any package
+ * can import these constants without creating dependency cycles.
+ *
+ * See GitHub issue #979 for the rationale (replaces runtime detection
+ * heuristics that were brittle across Bun's ESM/CJS compile modes).
+ */
+
+export const BUNDLED_IS_BINARY = false;
+export const BUNDLED_VERSION = 'dev';
+export const BUNDLED_GIT_COMMIT = 'unknown';

packages/paths/src/bundled-build.test.ts

@@ -30,3 +30,6 @@ export {
 // Logger
 export { createLogger, setLogLevel, getLogLevel, rootLogger } from './logger';
 export type { Logger } from './logger';
+
+// Build-time constants (rewritten by scripts/build-binaries.sh)
+export { BUNDLED_IS_BINARY, BUNDLED_VERSION, BUNDLED_GIT_COMMIT } from './bundled-build';

packages/paths/src/bundled-build.ts

@@ -23,6 +23,7 @@
 
 import pino from 'pino';
 import type { Logger } from 'pino';
+import pretty from 'pino-pretty';
 
 export type { Logger } from 'pino';
 
@@ -44,36 +45,48 @@ function getInitialLevel(): string {
 }
 
 /**
- * Uses pino-pretty when stdout is a TTY and NODE_ENV !== 'production';
- * outputs newline-delimited JSON otherwise.
+ * Build the root Pino logger.
+ *
+ * Uses `pino-pretty` as a **destination stream** (not a worker-thread transport)
+ * when stdout is a TTY and NODE_ENV !== 'production'. Running pino-pretty as a
+ * destination stream keeps the formatter on the main thread, which avoids the
+ * `require.resolve('pino-pretty')` lookup that crashes inside Bun's `/$bunfs/`
+ * virtual filesystem in compiled binaries (see GitHub issue #960 / #979).
+ *
+ * The same code path runs in dev and compiled binaries — no environment
+ * detection required.
  */
-function buildLoggerOptions(): pino.LoggerOptions {
+function buildLogger(): Logger {
   const level = getInitialLevel();
   const usePretty = process.stdout.isTTY && process.env.NODE_ENV !== 'production';
 
   if (usePretty) {
-    return {
-      level,
-      transport: {
-        target: 'pino-pretty',
-        options: {
-          colorize: true,
-          levelFirst: true,
-          translateTime: 'SYS:standard',
-          ignore: 'pid,hostname',
-        },
-      },
-    };
+    try {
+      const stream = pretty({
+        colorize: true,
+        levelFirst: true,
+        translateTime: 'SYS:standard',
+        ignore: 'pid,hostname',
+      });
+      return pino({ level }, stream);
+    } catch (err) {
+      // pino-pretty failed to initialize (missing peer, broken TTY descriptor,
+      // or incompatible runtime). Fall back to plain JSON so logging keeps
+      // working instead of crashing the entire process at module import time.
+      console.warn(
+        `[logger] pino-pretty failed to initialize, falling back to JSON output: ${(err as Error).message}`
+      );
+    }
   }
 
-  return { level };
+  return pino({ level });
 }
 
 /**
  * Root Pino logger instance.
  * Children inherit the root's level at creation time (not dynamically updated).
  */
-export const rootLogger: Logger = pino(buildLoggerOptions());
+export const rootLogger: Logger = buildLogger();
 
 /**
  * Create a child logger with a module binding.

packages/paths/src/index.ts

@@ -1,40 +1,13 @@
 import { describe, it, expect } from 'bun:test';
-import {
-  isBinaryBuild,
-  isBunVirtualFs,
-  BUNDLED_COMMANDS,
-  BUNDLED_WORKFLOWS,
-} from './bundled-defaults';
+import { isBinaryBuild, BUNDLED_COMMANDS, BUNDLED_WORKFLOWS } from './bundled-defaults';
 
 describe('bundled-defaults', () => {
-  describe('isBunVirtualFs', () => {
-    it('should detect Linux/macOS virtual filesystem paths', () => {
-      expect(isBunVirtualFs('/$bunfs/root/bundled-defaults')).toBe(true);
-      expect(isBunVirtualFs('/$bunfs/root/')).toBe(true);
-    });
-
-    it('should detect Windows virtual filesystem paths (backslash)', () => {
-      expect(isBunVirtualFs('B:\\~BUN\\root\\bundled-defaults')).toBe(true);
-      expect(isBunVirtualFs('B:\\~BUN\\root')).toBe(true);
-    });
-
-    it('should detect Windows virtual filesystem paths (forward slash)', () => {
-      expect(isBunVirtualFs('B:/~BUN/root/bundled-defaults')).toBe(true);
-      expect(isBunVirtualFs('B:/~BUN/root')).toBe(true);
-    });
-
-    it('should return false for real filesystem paths', () => {
-      expect(isBunVirtualFs('/home/user/project/src')).toBe(false);
-      expect(isBunVirtualFs('C:\\Users\\user\\project\\src')).toBe(false);
-      expect(isBunVirtualFs('/tmp/test')).toBe(false);
-    });
-  });
-
   describe('isBinaryBuild', () => {
-    it('should return false when running in test environment (not compiled)', () => {
-      // The true path requires an actual compiled binary (import.meta.dir points to
-      // Bun's virtual FS only inside compiled binaries). Coverage of the true branch
-      // relies on isBunVirtualFs tests above + manual binary smoke testing in CI.
+    it('should return false in dev/test mode', () => {
+      // `isBinaryBuild()` reads the build-time constant `BUNDLED_IS_BINARY` from
+      // `@archon/paths`. In dev/test mode it is `false`. It is only rewritten to
+      // `true` by `scripts/build-binaries.sh` before `bun build --compile`.
+      // Coverage of the `true` branch is via local binary smoke testing (see #979).
       expect(isBinaryBuild()).toBe(false);
     });
   });

packages/paths/src/logger.ts

@@ -8,6 +8,8 @@
  * Import syntax uses `with { type: 'text' }` to import file contents as strings.
  */
 
+import { BUNDLED_IS_BINARY } from '@archon/paths';
+
 // =============================================================================
 // Default Commands (21 total)
 // =============================================================================
@@ -102,23 +104,19 @@ export const BUNDLED_WORKFLOWS: Record<string, string> = {
   'archon-workflow-builder': archonWorkflowBuilderWf,
 };
 
-/**
- * Check if a given module directory path belongs to a compiled Bun binary.
- *
- * Compiled Bun binaries use a virtual filesystem for bundled modules:
- * - Linux/macOS: `/$bunfs/root/`
- * - Windows: `B:\~BUN\root\` or `B:/~BUN/root/`
- */
-export function isBunVirtualFs(dir: string): boolean {
-  return dir.startsWith('/$bunfs/') || dir.startsWith('B:\\~BUN\\') || dir.startsWith('B:/~BUN/');
-}
-
 /**
  * Check if the current process is running as a compiled binary (not via Bun CLI).
  *
- * Note: `process.versions.bun` is still set in compiled binaries as of Bun 1.3.5,
- * so we use the virtual filesystem path prefix for detection instead.
+ * Reads the build-time constant `BUNDLED_IS_BINARY` from `@archon/paths`.
+ * `scripts/build-binaries.sh` rewrites that file to set it to `true` before
+ * `bun build --compile` and restores it afterwards. See GitHub issue #979.
+ *
+ * Kept as a function (rather than a direct re-export of `BUNDLED_IS_BINARY`)
+ * so tests can use `spyOn(bundledDefaults, 'isBinaryBuild').mockReturnValue(...)`
+ * without resorting to `mock.module('@archon/paths', ...)` — which is
+ * process-global and irreversible in Bun and would pollute other test files.
+ * See `.claude/rules/dx-quirks.md` and `loader.test.ts` for context.
  */
 export function isBinaryBuild(): boolean {
-  return isBunVirtualFs(import.meta.dir);
+  return BUNDLED_IS_BINARY;
 }