perf(cli): enable V8 compile cache in bin/run (#90)

[Rinse12]

What

• 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). Honors NODE_COMPILE_CACHE and NODE_DISABLE_COMPILE_CACHE=1.
• community list -q doc — the flag summary (and generated README) now note that -q is much faster because it skips the per-community started lookup.

Implements #90. Documents part of #76 (the real fix for the started-column cost is tracked upstream in pkcprotocol/pkc-js#141).

Why

Profiling bitsocial community list on a slow host (Node v22.22.2, pkc-js 0.0.47) decomposed as:

Layer	Median
bare node -e 0	~0.07s
import @pkcprotocol/pkc-js alone	~1.73s (was ~9s — pkc-js now self-caches)
bitsocial --version (oclif boot)	~0.51s
community list -q (floor)	~3.1s
community list (full)	~5.1s median, 15.6s spike

pkc-js already enables the compile cache for its own graph, but everything the CLI loads around it (its own ~600 dist/ files, oclif, other deps) was still compiled uncached on every run. This recovers ~0.5–1s of that per-command floor on second-and-later runs; the win is larger on real commands than on --version (which compiles less of the graph).

Testing

• Full npm run test:cli green: 301 passed, 1 skipped, 0 failed (39 files, incl. the kubo/daemon integration suite).
• New 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 is populated 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 on --version: 0.55s → 0.46s with the cache warm.

Drawbacks (low)

• A few MB of bytecode under os.tmpdir()/node-compile-cache (ephemeral; cleared on reboot / per container lifetime).
• A one-time extra write on the first run after each upgrade or tmp wipe; every later run is faster.
• Graceful: if tmp is full/read-only/noexec or Node < 22.8, it's a no-op — never throws. Entries are validated by source hash + Node/V8 version, so stale/corrupt entries are recompiled, not mis-executed.

Notes

• The prod speedup lands once this ships and is reinstalled there (prod runs the published CLI via npm + systemd).
• The biggest lever for community list specifically is still the started column (community list: default (non-quiet) is 2-30s slower than -q because the 'started' column spins up every community #76) — deliberately documentation-only here; structural fix proposed in feat(rpc): carry per-community state in the communities subscription (pkc.communities -> {address, started}[]) so RPC clients don't instantiate every community pkcprotocol/pkc-js#141.

Summary by CodeRabbit

• Performance

  • Enabled V8 compile cache to improve CLI startup performance.

• Documentation

  • Clarified that the --quiet flag provides faster performance by skipping per-community lookups.

• Tests

  • Added tests for compile cache functionality.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9d42c945-806f-42ed-a561-930a727a7425

📥 Commits

Reviewing files that changed from the base of the PR and between 4fb0d42 and c04145f.

📒 Files selected for processing (4)

• README.md
• bin/run
• src/cli/commands/community/list.ts
• test/cli/compile-cache.test.ts

---

📝 Walkthrough

Walkthrough

The PR enables V8 compile cache at CLI startup for faster subsequent invocations, documents the --quiet flag's performance benefit in both README and command definition, and adds comprehensive tests verifying compile cache behavior on supported Node versions.

Changes

Documentation: --quiet Flag Performance Clarification

Layer / File(s)	Summary
--quiet flag documentation src/cli/commands/community/list.ts, README.md	The --quiet flag summary is expanded in both the command definition and README to clarify it is "much faster" because it skips the per-community started lookup.

V8 Compile Cache Startup Enablement

Layer / File(s)	Summary
V8 compile cache startup integration bin/run	The CLI entrypoint now calls enableCompileCache() from node:module before importing oclif, with optional chaining to safely no-op on unsupported Node versions or failures.
Compile cache behavior tests test/cli/compile-cache.test.ts	Test suite adds a runBitsocial() helper to spawn and monitor the CLI, and two test cases: one verifies the compile-cache directory is created on first run, the other confirms NODE_DISABLE_COMPILE_CACHE=1 prevents creation while the CLI still exits successfully. Tests are skipped on Node versions without enableCompileCache support (pre-22.8).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• #90: Directly related; this PR implements the proposed change to call node:module.enableCompileCache() at the top of bin/run to enable V8 compile cache before importing oclif and its dependencies.

Poem

🐰 A speedier CLI hops through the cache,
As compile bytes dance (no more slow pass),
The quiet flag whispers why it's so fleet—
Tests verify each bounce's complete.
Faster startup, happier fleet! 🚀

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'perf(cli): enable V8 compile cache in bin/run (#90)' directly and precisely describes the main change: enabling V8 compile caching in the CLI's entrypoint, with a clear performance focus.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/compile-cache-bin-run-90

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}