@forwardimpact/libcli 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libcli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Agent-friendly CLIs — self-documenting entry points that humans and agents reach through the same interface.",
   "keywords": [
     "cli",
@@ -40,7 +40,7 @@
     "test": "bun test test/*.test.js"
   },
   "devDependencies": {
-    "@forwardimpact/libharness": "^0.1.14"
+    "@forwardimpact/libmock": "^0.1.0"
   },
   "engines": {
     "bun": ">=1.2.0",

package/src/cli.js

@@ -134,8 +134,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 +156,7 @@ export class Cli {
       data,
       args,
       options: parsed.values,
+      deps,
     });
     return command.handler(ctx);
   }
@@ -178,8 +179,18 @@ 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. 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.
+ * @param {object} definition - The CLI definition.
+ * @param {object} [options]
+ * @param {import('@forwardimpact/libutil/runtime').Runtime} [options.runtime]
+ * @returns {Cli}
+ */
+export function createCli(definition, { runtime } = {}) {
+  const proc = runtime ? runtime.proc : process;
+  const helpRenderer = new HelpRenderer({ process: proc });
+  return new Cli(definition, { process: proc, helpRenderer });
 }

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),
   });
 }