@forwardimpact/libcli 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Agent-friendly CLIs — self-documenting entry points that humans and agents reach through the same interface.",
   "keywords": [
     "cli",

package/src/cli.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
 import { HelpRenderer } from "./help.js";
 import { freezeInvocationContext } from "./invocation-context.js";
+import { resolveVersion } from "./version.js";
 
 /** Command-line interface that parses argv against a definition of commands, options, and help. */
 export class Cli {
@@ -180,17 +181,25 @@ export class Cli {
 }
 
 /**
- * Create a Cli instance. When `runtime` is provided, error,
- * usage-error, and help output route through `runtime.proc` instead of the
- * global `process`. The zero-arg form keeps reading the global `process` as a
- * deprecated alias for one migration cycle.
+ * Create a Cli instance. Error, usage-error, and help output route through the
+ * injected `runtime.proc`.
  * @param {object} definition - The CLI definition.
- * @param {object} [options]
- * @param {import('@forwardimpact/libutil/runtime').Runtime} [options.runtime]
+ * @param {object} options
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} options.runtime
+ * @param {URL|string} [options.packageJsonUrl] - When provided and the definition
+ *   carries no explicit `version`, resolve it via {@link resolveVersion} so every
+ *   bin shares one compile-time version literal. Explicit `definition.version` wins.
  * @returns {Cli}
  */
-export function createCli(definition, { runtime } = {}) {
-  const proc = runtime ? runtime.proc : process;
+export function createCli(definition, { runtime, packageJsonUrl } = {}) {
+  if (!runtime) throw new Error("runtime is required");
+  if (definition.version === undefined && packageJsonUrl !== undefined) {
+    definition = {
+      ...definition,
+      version: resolveVersion({ packageJsonUrl, runtime }),
+    };
+  }
+  const proc = runtime.proc;
   const helpRenderer = new HelpRenderer({ process: proc });
   return new Cli(definition, { process: proc, helpRenderer });
 }

package/src/embed.js

@@ -0,0 +1,117 @@
+/**
+ * Embedded assets for `bun build --compile` binaries.
+ *
+ * A compiled CLI runs from Bun's virtual `/$bunfs` filesystem with no
+ * `node_modules` tree, so the runtime tricks that locate package data
+ * directories on disk — `import.meta.resolve("@scope/pkg")` plus
+ * `readFileSync(join(dir, name))` — both fail. The `--help` smoke gate never
+ * exercises those paths, so the breakage ships silently.
+ *
+ * This module is the runtime half of the fix. The build half (driven by a
+ * CLI's `assets` block in `build/cli-manifest.json`, see `build/gen-embed.mjs`)
+ * inlines each asset file's text into the bundle and calls {@link registerAssets}
+ * at startup. Consumers then resolve asset directories through {@link embeddedDir}
+ * and overlay their runtime with {@link withEmbeddedAssets} so the existing
+ * `fsSync`-based loaders read embedded content transparently — no loader changes.
+ *
+ * In source/npx execution nothing registers, so {@link embeddedAssetsActive}
+ * is false, {@link withEmbeddedAssets} is a no-op, and callers fall back to the
+ * on-disk resolution they already use.
+ */
+
+import { normalize, sep } from "node:path";
+
+// Sentinel root for embedded asset paths. Chosen to never collide with a real
+// filesystem path. `embeddedDir(mount)` hangs logical mounts off it, and the
+// fs overlay recognises this prefix to serve content from the registry.
+const EMBED_ROOT = "/__fit_embed__";
+
+/** @type {Map<string, string>} logical path (`<mount>/<relPosix>`) → file text. */
+const registry = new Map();
+
+/**
+ * Register a mount's files. Called by the generated barrel that the compile
+ * step prepends to the entry point.
+ *
+ * @param {string} mount - Logical namespace, e.g. `"libsyntheticprose/prompts"`.
+ * @param {Record<string, string>} files - Map of posix relative path → text.
+ */
+export function registerAssets(mount, files) {
+  for (const [rel, content] of Object.entries(files)) {
+    registry.set(`${mount}/${rel}`, content);
+  }
+}
+
+/** Whether any embedded assets were registered (true only in compiled builds). */
+export function embeddedAssetsActive() {
+  return registry.size > 0;
+}
+
+/**
+ * True when this process is a `bun build --compile` standalone binary.
+ *
+ * `build/build-binary.sh` passes `--define process.env.LIBCLI_IS_COMPILED="1"`,
+ * so Bun substitutes the literal member expression `process.env.LIBCLI_IS_COMPILED`
+ * with `"1"` across the whole bundle (this file included) at compile time and
+ * the comparison folds to `true`. In source/npx/test execution the env var is
+ * normally unset, so it is `false`. This mirrors the `LIBCLI_PACKAGE_VERSION`
+ * literal trick in version.js — an explicit, platform-independent build-time
+ * contract rather than sniffing Bun's internal `/$bunfs` path convention.
+ *
+ * The read must stay the literal token `process.env.LIBCLI_IS_COMPILED` — that
+ * is what `--define` replaces; a dynamic `process.env[name]` would not be.
+ *
+ * @type {boolean}
+ */
+export const LIBCLI_IS_COMPILED = process.env.LIBCLI_IS_COMPILED === "1";
+
+/**
+ * Virtual directory for a registered mount. Joining a filename onto it yields a
+ * path the {@link withEmbeddedAssets} overlay resolves from the registry, so a
+ * directory-based loader (`join(dir, name)` → `readFileSync`) works unchanged.
+ *
+ * @param {string} mount - Same namespace passed to {@link registerAssets}.
+ * @returns {string}
+ */
+export function embeddedDir(mount) {
+  return `${EMBED_ROOT}/${mount}`;
+}
+
+/**
+ * Map a filesystem path under {@link EMBED_ROOT} to its registry key, or null
+ * if the path is not an embedded-asset path (normal file → delegate to disk).
+ */
+function toLogicalKey(p) {
+  if (typeof p !== "string") return null;
+  const posix = normalize(p).split(sep).join("/");
+  if (posix !== EMBED_ROOT && !posix.startsWith(`${EMBED_ROOT}/`)) return null;
+  return posix.slice(EMBED_ROOT.length + 1);
+}
+
+/**
+ * Return a runtime whose `fsSync` serves embedded assets for paths under the
+ * sentinel root and delegates everything else to the real filesystem. No-op
+ * when no assets are registered, so it is safe to call unconditionally.
+ *
+ * @template {{ fsSync: object }} R
+ * @param {R} runtime
+ * @returns {R}
+ */
+export function withEmbeddedAssets(runtime) {
+  if (!embeddedAssetsActive()) return runtime;
+  const base = runtime.fsSync;
+  const fsSync = {
+    ...base,
+    existsSync(p) {
+      const key = toLogicalKey(p);
+      if (key !== null && registry.has(key)) return true;
+      return base.existsSync(p);
+    },
+    readFileSync(p, ...rest) {
+      const key = toLogicalKey(p);
+      if (key !== null && registry.has(key)) return registry.get(key);
+      return base.readFileSync(p, ...rest);
+    },
+  };
+  return Object.freeze({ ...runtime, fsSync });
+}

package/src/index.js

@@ -1,4 +1,12 @@
 export { Cli, createCli } from "./cli.js";
+export { resolveVersion } from "./version.js";
+export {
+  registerAssets,
+  embeddedAssetsActive,
+  LIBCLI_IS_COMPILED,
+  embeddedDir,
+  withEmbeddedAssets,
+} from "./embed.js";
 export { freezeInvocationContext } from "./invocation-context.js";
 export { HelpRenderer } from "./help.js";
 export { SummaryRenderer } from "./summary.js";

package/src/version.js

@@ -0,0 +1,27 @@
+/**
+ * Resolve a CLI's version string — the version of the package the binary was
+ * built from (e.g. fit-terrain's), which libcli merely surfaces; not libcli's
+ * own version. In a `bun build --compile` binary,
+ * `process.env.LIBCLI_PACKAGE_VERSION` is replaced at build time by
+ * `build/build-binary.sh`'s `--define`, so this returns the injected literal and
+ * the package.json read below is dead code (it never executes — and tree-shakes).
+ * In source/npx execution the env var is normally unset and the read supplies the
+ * version; setting LIBCLI_PACKAGE_VERSION in the environment overrides it (used by
+ * bin-smoke integration tests).
+ *
+ * The read must be written as the literal member expression
+ * `process.env.LIBCLI_PACKAGE_VERSION` — that is the token `bun build --define`
+ * substitutes across the whole bundle, including this bundled library. A dynamic
+ * `process.env[name]` would not be replaced.
+ *
+ * @param {object} args
+ * @param {URL|string} args.packageJsonUrl - `new URL("../package.json", import.meta.url)`
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} args.runtime
+ * @returns {string}
+ */
+export function resolveVersion({ packageJsonUrl, runtime }) {
+  const injected = process.env.LIBCLI_PACKAGE_VERSION; // literal — the --define target
+  if (injected) return injected;
+  const text = runtime.fsSync.readFileSync(packageJsonUrl, "utf8");
+  return JSON.parse(text).version;
+}