@forwardimpact/libcli 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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 {
@@ -134,8 +135,8 @@ export class Cli {
     return null;
   }
 
-  /** Match parsed positionals to a subcommand and invoke its handler with a frozen invocation context. */
-  dispatch(parsed, { data }) {
+  /** Match parsed positionals to a subcommand and invoke its handler with a frozen invocation context. `deps` carries host-injected collaborators (the runtime bag); `data` carries host-loaded domain values. */
+  dispatch(parsed, { data, deps } = {}) {
     const command = this.#findCommand(parsed.positionals);
     if (!command) {
       throw new Error(`${this.#definition.name}: no matching subcommand`);
@@ -156,6 +157,7 @@ export class Cli {
       data,
       args,
       options: parsed.values,
+      deps,
     });
     return command.handler(ctx);
   }
@@ -178,8 +180,26 @@ export class Cli {
   }
 }
 
-/** Create a Cli instance wired to the real process and a default HelpRenderer. */
-export function createCli(definition) {
-  const helpRenderer = new HelpRenderer({ process });
-  return new Cli(definition, { process, helpRenderer });
+/**
+ * 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 {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, 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/index.js

@@ -1,4 +1,5 @@
 export { Cli, createCli } from "./cli.js";
+export { resolveVersion } from "./version.js";
 export { freezeInvocationContext } from "./invocation-context.js";
 export { HelpRenderer } from "./help.js";
 export { SummaryRenderer } from "./summary.js";

package/src/invocation-context.js

@@ -35,14 +35,20 @@
  *   empty-valued query parameter), or an array of strings (when the same
  *   key appears more than once). Absent options are not present in the
  *   object — 'foo' in ctx.options is the membership test.
+ *
+ * @property {Readonly<Object>} deps
+ *   Host-injected ambient collaborators (the `runtime` bag and typed
+ *   clients). The handler treats deps as immutable input.
+ *   Distinct from `data` (host-loaded domain values). Defaults to
+ *   `undefined` for hosts that do not inject collaborators.
  */
 
 /**
  * Deep-freeze an invocation context so handlers may assume immutability.
- * @param {{ data: Object, args: Object<string,string>, options: Object<string,string|boolean|string[]> }} raw
+ * @param {{ data: Object, args: Object<string,string>, options: Object<string,string|boolean|string[]>, deps?: Object }} raw
  * @returns {InvocationContext}
  */
-export function freezeInvocationContext({ data, args, options }) {
+export function freezeInvocationContext({ data, args, options, deps }) {
   for (const v of Object.values(options)) {
     if (Array.isArray(v)) Object.freeze(v);
   }
@@ -50,5 +56,6 @@ export function freezeInvocationContext({ data, args, options }) {
     data,
     args: Object.freeze({ ...args }),
     options: Object.freeze({ ...options }),
+    deps: deps === undefined ? undefined : Object.freeze(deps),
   });
 }

package/src/version.js

@@ -0,0 +1,23 @@
+/**
+ * Resolve a CLI's version string. In a `bun build --compile` binary,
+ * `process.env.LIBCLI_VERSION` is replaced at build time by `just build-binary`'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_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_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_VERSION; // literal — the --define target
+  if (injected) return injected;
+  const text = runtime.fsSync.readFileSync(packageJsonUrl, "utf8");
+  return JSON.parse(text).version;
+}