Enable the V8 compile cache in bin/run to cut CLI startup time (~1.2s on slow hosts)

[Rinse12]

Problem

Every CLI invocation re-parses and re-compiles the CLI's own module graph: the ~600 files under dist/, @oclif/core, and the rest of the dependency closure. On a production server (slow host, Node v22.22.2) this costs about 1.2s of every command, measured while decomposing time bitsocial community list (see the breakdown in pkc-js docs/protocol/import-performance.md, "Decomposition of the remaining ~5.5s"):

Layer	Median (steady state)
bare node -e 0	~0.05s
import("@pkcprotocol/pkc-js") alone	~1.8s
command graph (list.js -> BaseCommand -> pkc-js)	~2.5s (~0.7s CLI dist on top of pkc-js)
oclif boot (bitsocial --version)	~0.5s

pkc-js already enables the compile cache for its own graph: its npm import entry calls module.enableCompileCache() and then dynamic-imports the real graph. But that only covers modules compiled after the call. Everything the CLI loads before reaching pkc-js (its own dist/ files, oclif, other deps) is compiled first, uncached, on every run.

Proposed fix

Call enableCompileCache() at the very top of bin/run, before importing @oclif/core. bin/run already delays oclif behind a dynamic import (for DEBUG stripping), so the whole framework + command graph compiles after the cache is on:

#!/usr/bin/env node

// Enable the V8 compile cache before anything is imported so the CLI's own dist/,
// oclif and all deps get bytecode-cached across invocations (no-op on Node < 22.8).
const { enableCompileCache } = await import("node:module");
enableCompileCache?.();

// ... existing DEBUG stripping ...

const oclif = await import("@oclif/core");

Notes:

• module.enableCompileCache() exists since Node 22.8; the optional call keeps older Node working (no-op).
• Default cache dir is os.tmpdir()/node-compile-cache, overridable with NODE_COMPILE_CACHE, opt-out with NODE_DISABLE_COMPILE_CACHE=1.
• First run after an upgrade pays a small one-time cache-population cost; every later run skips parse/compile for the whole graph.

Validation

On a slow host, compare time bitsocial --version (oclif boot only) and time bitsocial community list before/after, second-and-later runs. Expected: most of the ~1.2s CLI-graph share recovered; pkc-js numbers unchanged (it caches itself already).

[Rinse12]

Implemented.

Change: bin/run now calls module.enableCompileCache() before the dynamic @oclif/core import, so the CLI's own dist/ graph + oclif + the rest of the dependency closure get bytecode-cached across invocations. Optional-chained (enableCompileCache?.()) so it's a no-op on Node < 22.8 and never throws (failures are reported via its return value). Cache dir defaults to os.tmpdir()/node-compile-cache; honors NODE_COMPILE_CACHE and NODE_DISABLE_COMPILE_CACHE=1.

Test: test/cli/compile-cache.test.ts spawns the built bin/run --version with an isolated TMPDIR (and NODE_COMPILE_CACHE stripped) and asserts the default cache dir gets populated — proving the cache is active from bin/run itself, not from an inherited env var. A second case asserts NODE_DISABLE_COMPILE_CACHE=1 writes nothing and the CLI still works. Skipped on Node < 22.8.

Local before/after (fast dev box, --version only — loads oclif but not the full command graph):

	median
cache disabled (NODE_DISABLE_COMPILE_CACHE=1)	0.55s
cache warm	0.46s

Re-profiling on the slow prod host (Node v22.22.2) also confirmed the pkc-js import is now ~1.7s (down from ~9s) because pkc-js already self-enables the compile cache — so this change targets the remaining CLI-own/oclif graph, not pkc-js. The larger absolute win shows up on real commands (e.g. community list) that compile more of dist/ than --version does.

Status: implemented + tested locally; prod numbers to be re-measured after this ships. Not closing yet.