@procedures/shell 0.34.0 → 0.35.1

package/dist/cli/argv.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The argument helpers of a CLI tool (dedupe review F2). A wrapper starts its program with argv,
+ * never through a shell, so these helpers only keep a value from becoming an option.
+ */
+/**
+ * This function gives a value that the program reads as an argument (a package, a branch, a
+ * path). It throws when the value starts with "-", because the program then reads it as an option.
+ */
+export declare function cliArg(name: string, value: string): string;
+/** The value of a named argument of `buildArgv()`. */
+export type ArgValue = string | number | boolean | readonly string[];
+/** A flag name: lowercase letters, digits and hyphens. */
+export declare const FLAG_NAME: RegExp;
+/**
+ * This function gives the argv: the path, then each named argument, then `--` and the positional
+ * arguments. `true` gives `--key`, `false` gives nothing, a list gives `--key=value` for each
+ * value, and another value gives `--key=value`.
+ */
+export declare function buildArgv(input: {
+    readonly path: readonly string[];
+    readonly args?: Readonly<Record<string, ArgValue>> | undefined;
+    readonly positional?: readonly string[] | undefined;
+    readonly flags?: readonly string[] | undefined;
+}): string[];
+/** This function reads one JSON document from a standard output. Output that is not JSON gives undefined. */
+export declare function parseJsonDocument(stdout: string): unknown;
+/** This function reads JSON output: one document, or one document on each line (NDJSON). */
+export declare function parseJsonOutput(stdout: string): unknown;
+//# sourceMappingURL=argv.d.ts.map

package/dist/cli/argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../../src/cli/argv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED,sDAAsD;AACtD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;AAErE,0DAA0D;AAC1D,eAAO,MAAM,SAAS,EAAE,MAA4B,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CAChD,GAAG,MAAM,EAAE,CAWX;AAED,6GAA6G;AAC7G,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAavD"}

package/dist/cli/argv.js

@@ -0,0 +1,71 @@
+/**
+ * The argument helpers of a CLI tool (dedupe review F2). A wrapper starts its program with argv,
+ * never through a shell, so these helpers only keep a value from becoming an option.
+ */
+/**
+ * This function gives a value that the program reads as an argument (a package, a branch, a
+ * path). It throws when the value starts with "-", because the program then reads it as an option.
+ */
+export function cliArg(name, value) {
+    if (value.startsWith("-")) {
+        throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+    }
+    return value;
+}
+/** A flag name: lowercase letters, digits and hyphens. */
+export const FLAG_NAME = /^[a-z][a-z0-9-]*$/;
+/**
+ * This function gives the argv: the path, then each named argument, then `--` and the positional
+ * arguments. `true` gives `--key`, `false` gives nothing, a list gives `--key=value` for each
+ * value, and another value gives `--key=value`.
+ */
+export function buildArgv(input) {
+    const argv = [...input.path, ...(input.flags ?? [])];
+    for (const [key, value] of Object.entries(input.args ?? {})) {
+        if (!FLAG_NAME.test(key))
+            throw new Error(`The argument name "${key}" is not a flag name (lowercase letters, digits, hyphens)`);
+        if (value === false)
+            continue;
+        if (value === true)
+            argv.push(`--${key}`);
+        else if (Array.isArray(value))
+            for (const item of value)
+                argv.push(`--${key}=${item}`);
+        else
+            argv.push(`--${key}=${String(value)}`);
+    }
+    if (input.positional && input.positional.length > 0)
+        argv.push("--", ...input.positional);
+    return argv;
+}
+/** This function reads one JSON document from a standard output. Output that is not JSON gives undefined. */
+export function parseJsonDocument(stdout) {
+    const text = stdout.trim();
+    if (text === "")
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** This function reads JSON output: one document, or one document on each line (NDJSON). */
+export function parseJsonOutput(stdout) {
+    const text = stdout.trim();
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+        try {
+            return lines.map((line) => JSON.parse(line));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=argv.js.map

package/dist/cli/argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../src/cli/argv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa;IAChD,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,uBAAuB,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAKD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAW,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAKzB;IACC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;IACrD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,2DAA2D,CAAC,CAAC;QAChI,IAAI,KAAK,KAAK,KAAK;YAAE,SAAS;QAC9B,IAAI,KAAK,KAAK,IAAI;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;aACrC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;;YAClF,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAClC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC;YACH,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC,CAAC;QAC1D,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@procedures/shell/cli`: the shared parts of the CLI wrapper packages (dedupe review F2).
+ *
+ * - `defineCliTool()` gives the runner of a program: `run`, `runJson`, `output`, `json` and the
+ *   argument guard. Each command goes as argv to the `shell.run` procedure, never as a shell string.
+ * - `cliArg()`, `buildArgv()`, `parseJsonDocument()` and `parseJsonOutput()` build the argv and
+ *   read the output.
+ * - `CliToolOutput` and `cliToolOutputSchema()` are the shared result and its schema.
+ * - `nodeScript()`, `execPathProgram()` and `findInPath()` find the program without a shell.
+ *
+ * This entry point has no side effects: it registers no procedures.
+ */
+export { cliArg, buildArgv, parseJsonDocument, parseJsonOutput, FLAG_NAME, type ArgValue } from "./argv.js";
+export { cliToolOutputFields, cliToolOutputSchema, cliToolJsonOutputSchema, type CliToolOutput, type CliToolJsonOutput, type CliToolOutputFields, } from "./output.js";
+export { nodeScript, execPathProgram, findInPath, type CliProgram } from "./program.js";
+export { defineCliTool, CliToolError, type CliTool, type CliToolOptions, type CliToolContext, type CliRunOptions, type CliShellInput, } from "./tool.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACxF,OAAO,EACL,aAAa,EACb,YAAY,EACZ,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@procedures/shell/cli`: the shared parts of the CLI wrapper packages (dedupe review F2).
+ *
+ * - `defineCliTool()` gives the runner of a program: `run`, `runJson`, `output`, `json` and the
+ *   argument guard. Each command goes as argv to the `shell.run` procedure, never as a shell string.
+ * - `cliArg()`, `buildArgv()`, `parseJsonDocument()` and `parseJsonOutput()` build the argv and
+ *   read the output.
+ * - `CliToolOutput` and `cliToolOutputSchema()` are the shared result and its schema.
+ * - `nodeScript()`, `execPathProgram()` and `findInPath()` find the program without a shell.
+ *
+ * This entry point has no side effects: it registers no procedures.
+ */
+export { cliArg, buildArgv, parseJsonDocument, parseJsonOutput, FLAG_NAME } from "./argv.js";
+export { cliToolOutputFields, cliToolOutputSchema, cliToolJsonOutputSchema, } from "./output.js";
+export { nodeScript, execPathProgram, findInPath } from "./program.js";
+export { defineCliTool, CliToolError, } from "./tool.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAiB,MAAM,WAAW,CAAC;AAC5G,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,GAIxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAmB,MAAM,cAAc,CAAC;AACxF,OAAO,EACL,aAAa,EACb,YAAY,GAMb,MAAM,WAAW,CAAC"}

package/dist/cli/output.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The shared output of a CLI tool procedure: the result of `shell.run` with `success` and the
+ * time of the call. The schemas are loose, so a field that a schema does not name stays.
+ */
+import { z } from "zod";
+/** The result of one command of a CLI tool. */
+export interface CliToolOutput {
+    /** The exit code of the program (0 is success) */
+    exitCode: number;
+    /** The standard output */
+    stdout: string;
+    /** The standard error, or the error message when the program did not start */
+    stderr: string;
+    /** True when the exit code is 0 */
+    success: boolean;
+    /** The time of the command, in milliseconds */
+    duration: number;
+}
+/** The result of a command that writes JSON: `data` is its parsed standard output. */
+export interface CliToolJsonOutput extends CliToolOutput {
+    /** The parsed JSON of the standard output. It is absent when the output is not JSON. */
+    data?: unknown;
+}
+/** The fields of the output schema of a tool, as a shape for `z.looseObject()`. */
+export interface CliToolOutputFields {
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    success: z.ZodBoolean;
+    duration: z.ZodNumber;
+}
+/** This function gives the fields of the output schema, with descriptions that name the program. */
+export declare function cliToolOutputFields(program: string): CliToolOutputFields;
+/** This function gives the loose output schema of a command of the program. */
+export declare function cliToolOutputSchema(program: string): z.ZodType<CliToolOutput>;
+/** This function gives the loose output schema of a command of the program that writes JSON. */
+export declare function cliToolJsonOutputSchema(program: string): z.ZodType<CliToolJsonOutput>;
+//# sourceMappingURL=output.d.ts.map

package/dist/cli/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sFAAsF;AACtF,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;IACtB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC;IACpB,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC;IACtB,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC;CACvB;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAQxE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAE7E;AAED,gGAAgG;AAChG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAKrF"}

package/dist/cli/output.js

@@ -0,0 +1,27 @@
+/**
+ * The shared output of a CLI tool procedure: the result of `shell.run` with `success` and the
+ * time of the call. The schemas are loose, so a field that a schema does not name stays.
+ */
+import { z } from "zod";
+/** This function gives the fields of the output schema, with descriptions that name the program. */
+export function cliToolOutputFields(program) {
+    return {
+        exitCode: z.number().describe(`The exit code of ${program} (0 is success)`),
+        stdout: z.string().describe(`The standard output of ${program}`),
+        stderr: z.string().describe(`The standard error of ${program}, or the error message when ${program} did not start`),
+        success: z.boolean().describe("True when the exit code is 0"),
+        duration: z.number().describe("The time of the command, in milliseconds"),
+    };
+}
+/** This function gives the loose output schema of a command of the program. */
+export function cliToolOutputSchema(program) {
+    return z.looseObject(cliToolOutputFields(program));
+}
+/** This function gives the loose output schema of a command of the program that writes JSON. */
+export function cliToolJsonOutputSchema(program) {
+    return z.looseObject({
+        ...cliToolOutputFields(program),
+        data: z.unknown().optional().describe("The parsed JSON of the standard output, when it is JSON"),
+    });
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA+BxB,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO;QACL,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oBAAoB,OAAO,iBAAiB,CAAC;QAC3E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,OAAO,EAAE,CAAC;QAChE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,OAAO,+BAA+B,OAAO,gBAAgB,CAAC;QACnH,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAC7D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,CAAC,CAAC,WAAW,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,uBAAuB,CAAC,OAAe;IACrD,OAAO,CAAC,CAAC,WAAW,CAAC;QACnB,GAAG,mBAAmB,CAAC,OAAO,CAAC;QAC/B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;KACjG,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/program.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The lookup of the program of a CLI tool. On Windows, a package manager is often a `.cmd` file,
+ * and Node runs a `.cmd` file only through a shell. So a tool finds the real program: an
+ * executable, or the script that the `.cmd` file starts, run with Node.
+ */
+/** The program and the first arguments that start a CLI tool without a shell. */
+export interface CliProgram {
+    /** The program that `shell.run` starts */
+    command: string;
+    /** The arguments before the arguments of the command (for example the script of the tool) */
+    prefix: string[];
+}
+/** This function gives the program that runs a JavaScript script with the Node of this process. */
+export declare function nodeScript(script: string): CliProgram;
+/**
+ * This function gives the program of `npm_execpath`, when the package manager that runs this
+ * process matches. A `script` match runs with Node, and an `executable` match runs directly.
+ * The file must exist.
+ */
+export declare function execPathProgram(match: {
+    script?: RegExp | undefined;
+    executable?: RegExp | undefined;
+}): CliProgram | undefined;
+/**
+ * This function gives the first program that `find` gives for a folder of PATH, in the order of
+ * PATH. It skips empty entries, and it gives undefined when no folder has the program.
+ */
+export declare function findInPath(find: (dir: string) => CliProgram | undefined, path?: string): CliProgram | undefined;
+//# sourceMappingURL=program.d.ts.map

package/dist/cli/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,mGAAmG;AACnG,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAErD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,UAAU,GAAG,SAAS,CAM/H;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU,GAAG,SAAS,EAAE,IAAI,GAAE,MAAkC,GAAG,UAAU,GAAG,SAAS,CAO1I"}

package/dist/cli/program.js

@@ -0,0 +1,41 @@
+/**
+ * The lookup of the program of a CLI tool. On Windows, a package manager is often a `.cmd` file,
+ * and Node runs a `.cmd` file only through a shell. So a tool finds the real program: an
+ * executable, or the script that the `.cmd` file starts, run with Node.
+ */
+import { existsSync } from "node:fs";
+import { delimiter } from "node:path";
+/** This function gives the program that runs a JavaScript script with the Node of this process. */
+export function nodeScript(script) {
+    return { command: process.execPath, prefix: [script] };
+}
+/**
+ * This function gives the program of `npm_execpath`, when the package manager that runs this
+ * process matches. A `script` match runs with Node, and an `executable` match runs directly.
+ * The file must exist.
+ */
+export function execPathProgram(match) {
+    const execPath = process.env["npm_execpath"];
+    if (!execPath || !existsSync(execPath))
+        return undefined;
+    if (match.script?.test(execPath))
+        return nodeScript(execPath);
+    if (match.executable?.test(execPath))
+        return { command: execPath, prefix: [] };
+    return undefined;
+}
+/**
+ * This function gives the first program that `find` gives for a folder of PATH, in the order of
+ * PATH. It skips empty entries, and it gives undefined when no folder has the program.
+ */
+export function findInPath(find, path = process.env["PATH"] ?? "") {
+    for (const dir of path.split(delimiter)) {
+        if (!dir)
+            continue;
+        const program = find(dir);
+        if (program !== undefined)
+            return program;
+    }
+    return undefined;
+}
+//# sourceMappingURL=program.js.map

package/dist/cli/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAUtC,mGAAmG;AACnG,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAuE;IACrG,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC7C,IAAI,CAAC,QAAQ,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IACzD,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAC/E,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAA6C,EAAE,IAAI,GAAW,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;IAChH,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACxC,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/cli/tool.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `defineCliTool()`: the one runner of the CLI wrapper packages (dedupe review F2).
+ *
+ * Each command goes as an argument list to the `shell.run` procedure, through `ctx.client`. No
+ * shell runs, so a value cannot start a second command. The nested call keeps the rules of the
+ * host: the declared calls, the effects, the root of the files and the signal of the call.
+ * `packages/documentation/SERVER-LAYERS.md` gives the reason for this run path.
+ */
+import type { ProcedureContext } from "@procedures/client";
+import type { CliToolJsonOutput, CliToolOutput } from "./output.js";
+import type { CliProgram } from "./program.js";
+/** The part of the procedure context that a CLI tool uses: the client of the nested call. */
+export type CliToolContext = Pick<ProcedureContext, "client">;
+/** The options of one command of a CLI tool. */
+export interface CliRunOptions {
+    /** The working folder of the program */
+    cwd?: string | undefined;
+    /** The time limit, in milliseconds. At the limit, `shell.run` kills the process tree. */
+    timeout?: number | undefined;
+    /** The environment variables that the program gets in addition to the environment of the host */
+    env?: Record<string, string> | undefined;
+}
+/** The input of a `shell.run` call that a CLI tool makes. */
+export interface CliShellInput {
+    command: string;
+    args: string[];
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+}
+/** A failed command of a CLI tool: its exit code and its standard error. */
+export declare class CliToolError extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly name: string;
+    constructor(message: string, exitCode: number, stderr: string);
+}
+/** The definition of a CLI tool. */
+export interface CliToolOptions {
+    /** The name of the program in the error messages. Without `resolve`, it is also the program. */
+    readonly name: string;
+    /**
+     * This function gives the program at each command: a command name, or a program with the first
+     * arguments. A throw is the error of the command (the program was not found).
+     */
+    readonly resolve?: (() => CliProgram | string) | undefined;
+    /** This function makes the error of a failed command for `output()` and `json()` (default: `CliToolError`). */
+    readonly error?: ((message: string, exitCode: number, stderr: string) => Error) | undefined;
+}
+/** The runner of a CLI tool that `defineCliTool()` gives. */
+export interface CliTool {
+    /** The name of the program */
+    readonly name: string;
+    /** This function gives a value that the program reads as an argument. It throws for a value that starts with "-". */
+    arg(name: string, value: string): string;
+    /** This function gives the `shell.run` input of a command. It throws when the program is not found. */
+    shellInput(args: readonly string[], options?: CliRunOptions): CliShellInput;
+    /** This function runs a command and gives its result. It throws when the program is not found or `shell.run` fails. */
+    call(args: readonly string[], options: CliRunOptions, ctx: CliToolContext): Promise<CliToolOutput>;
+    /** This function runs a command and gives its result. It does not throw: an error gives exit code 1 and its message as `stderr`. */
+    run(args: readonly string[], options: CliRunOptions, ctx: CliToolContext): Promise<CliToolOutput>;
+    /** This function runs a command that writes JSON, and gives `data` when `parse` reads the output. It does not throw. */
+    runJson(args: readonly string[], options: CliRunOptions, ctx: CliToolContext, parse?: (stdout: string) => unknown): Promise<CliToolJsonOutput>;
+    /** This function runs a command and gives its standard output. It throws the tool error for an exit code other than 0. */
+    output(args: readonly string[], options: CliRunOptions, ctx: CliToolContext): Promise<string>;
+    /** This function runs a command that writes JSON and gives the parsed value. It throws the tool error for a failure or for output that is not JSON. */
+    json<T>(args: readonly string[], options: CliRunOptions, ctx: CliToolContext): Promise<T>;
+}
+/**
+ * This function defines the runner of a CLI tool. The wrapper package keeps its procedures, its
+ * schemas and its own argument rules. The runner gives the run, the JSON, the argument guard
+ * and the shared result.
+ */
+export declare function defineCliTool(options: CliToolOptions): CliTool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/cli/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/cli/tool.ts"],"names":[],"mappings":"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"}

package/dist/cli/tool.js

@@ -0,0 +1,104 @@
+/**
+ * `defineCliTool()`: the one runner of the CLI wrapper packages (dedupe review F2).
+ *
+ * Each command goes as an argument list to the `shell.run` procedure, through `ctx.client`. No
+ * shell runs, so a value cannot start a second command. The nested call keeps the rules of the
+ * host: the declared calls, the effects, the root of the files and the signal of the call.
+ * `packages/documentation/SERVER-LAYERS.md` gives the reason for this run path.
+ */
+import { cliArg, parseJsonDocument } from "./argv.js";
+/** A failed command of a CLI tool: its exit code and its standard error. */
+export class CliToolError extends Error {
+    exitCode;
+    stderr;
+    name = "CliToolError";
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+/** The first two words of a command, for an error message. */
+function commandWords(name, args) {
+    return `${name} ${args[0] ?? ""} ${args[1] ?? ""}`;
+}
+/**
+ * This function defines the runner of a CLI tool. The wrapper package keeps its procedures, its
+ * schemas and its own argument rules. The runner gives the run, the JSON, the argument guard
+ * and the shared result.
+ */
+export function defineCliTool(options) {
+    const { name } = options;
+    const makeError = options.error ?? ((message, exitCode, stderr) => new CliToolError(message, exitCode, stderr));
+    const shellInput = (args, run = {}) => {
+        const resolved = options.resolve?.() ?? name;
+        const program = typeof resolved === "string" ? { command: resolved, prefix: [] } : resolved;
+        const input = { command: program.command, args: [...program.prefix, ...args] };
+        if (run.cwd !== undefined)
+            input.cwd = run.cwd;
+        if (run.timeout !== undefined)
+            input.timeout = run.timeout;
+        if (run.env !== undefined)
+            input.env = run.env;
+        return input;
+    };
+    const call = async (args, run, ctx) => {
+        const startTime = Date.now();
+        const result = await ctx.client.call(["shell", "run"], shellInput(args, run));
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            success: result.exitCode === 0,
+            duration: Date.now() - startTime,
+        };
+    };
+    const runCommand = async (args, run, ctx) => {
+        const startTime = Date.now();
+        try {
+            return await call(args, run, ctx);
+        }
+        catch (error) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error),
+                success: false,
+                duration: Date.now() - startTime,
+            };
+        }
+    };
+    const output = async (args, run, ctx) => {
+        const result = await call(args, run, ctx);
+        if (result.exitCode !== 0) {
+            const text = result.stderr.trim() || result.stdout.trim();
+            throw makeError(`${commandWords(name, args)} failed (exit ${result.exitCode}): ${text}`.trim(), result.exitCode, result.stderr);
+        }
+        return result.stdout;
+    };
+    return {
+        name,
+        arg: cliArg,
+        shellInput,
+        call,
+        run: runCommand,
+        async runJson(args, run, ctx, parse = parseJsonDocument) {
+            const result = await runCommand(args, run, ctx);
+            const data = parse(result.stdout);
+            if (data !== undefined)
+                result.data = data;
+            return result;
+        },
+        output,
+        async json(args, run, ctx) {
+            const stdout = await output(args, run, ctx);
+            try {
+                return JSON.parse(stdout);
+            }
+            catch {
+                throw makeError(`${commandWords(name, args)} gave no JSON: ${stdout.slice(0, 200)}`, 0, "");
+            }
+        },
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/cli/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/cli/tool.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -10,7 +10,9 @@
  * - shell.stream - Run command with args and stream each output line
  *
  * The command helpers (`runCommand`, `streamCommand`, `processes`) are also available without
- * the registration of the procedures, from `@procedures/shell/command`.
+ * the registration of the procedures, from `@procedures/shell/command`. The runner of the CLI
+ * wrapper packages (`defineCliTool`) is in `@procedures/shell/cli`, and the fake shell of their
+ * tests (`fakeShell`) is in `@procedures/shell/testing`.
  *
  * @example
  * ```typescript
@@ -27,5 +29,6 @@ export type { ShellRunInput, ShellRunOutput, ShellExecInput, ShellExecOutput, Sh
 export { ShellRunInputSchema, ShellExecInputSchema, ShellWhichInputSchema, ShellStreamInputSchema, } from "./types.js";
 export { shellRun, shellExec, shellWhich, shellStream } from "./procedures/shell/index.js";
 export * from "./command/index.js";
+export * from "./cli/index.js";
 export { registerShellProcedures } from "./module.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG3F,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG3F,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -10,7 +10,9 @@
  * - shell.stream - Run command with args and stream each output line
  *
  * The command helpers (`runCommand`, `streamCommand`, `processes`) are also available without
- * the registration of the procedures, from `@procedures/shell/command`.
+ * the registration of the procedures, from `@procedures/shell/command`. The runner of the CLI
+ * wrapper packages (`defineCliTool`) is in `@procedures/shell/cli`, and the fake shell of their
+ * tests (`fakeShell`) is in `@procedures/shell/testing`.
  *
  * @example
  * ```typescript
@@ -28,6 +30,8 @@ export { ShellRunInputSchema, ShellExecInputSchema, ShellWhichInputSchema, Shell
 export { shellRun, shellExec, shellWhich, shellStream } from "./procedures/shell/index.js";
 // Command helpers
 export * from "./command/index.js";
+// The runner of the CLI wrapper packages (also from `@procedures/shell/cli`)
+export * from "./cli/index.js";
 // Registration
 export { registerShellProcedures } from "./module.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAcH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,aAAa;AACb,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE3F,kBAAkB;AAClB,cAAc,oBAAoB,CAAC;AAEnC,eAAe;AACf,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,aAAa;AACb,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE3F,kBAAkB;AAClB,cAAc,oBAAoB,CAAC;AAEnC,6EAA6E;AAC7E,cAAc,gBAAgB,CAAC;AAE/B,eAAe;AACf,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/module.d.ts

@@ -3,7 +3,7 @@
  *
  * Procedure Registration for shell operations
  */
-import { type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+import { type ProcedureModule, type PackageDefinition } from "@procedures/client";
 /**
  * The module of this package, for `createRegistry()`: its procedures as data. Importing this
  * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
@@ -15,5 +15,5 @@ export default shellModule;
  * a registry. The default is the global registry. Importing this file registers nothing: the
  * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
  */
-export declare function registerShellProcedures(registry?: ProcedureRegistry): void;
+export declare const registerShellProcedures: PackageDefinition["register"];
 //# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA+C,KAAK,eAAe,EAAuC,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAqGpK;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,eAKtB,CAAC;eAEU,WAAW;AAE1B;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,GAAE,iBAAsC,GAAG,IAAI,CAE9F"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAgD,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA4GhI;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,eAAqC,CAAC;eAEjD,WAAW;AAE1B;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,UAAU,CAAyB,CAAC"}

package/dist/module.js

@@ -3,7 +3,7 @@
  *
  * Procedure Registration for shell operations
  */
-import { createProcedure, defineModule, PROCEDURE_REGISTRY, registerModules } from "@procedures/client";
+import { definePackage, createProcedure } from "@procedures/client";
 import { shellRun } from "./procedures/shell/run.js";
 import { shellExec } from "./procedures/shell/exec.js";
 import { shellWhich } from "./procedures/shell/which.js";
@@ -83,23 +83,22 @@ const shellStreamProcedure = createProcedure()
 })
     .handler(shellStream)
     .build();
-/**
- * The module of this package, for `createRegistry()`: its procedures as data. Importing this
- * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
- */
-export const shellModule = defineModule("@procedures/shell", [
+const shellPackage = definePackage("@procedures/shell", [
     shellRunProcedure,
     shellExecProcedure,
     shellWhichProcedure,
     shellStreamProcedure,
 ]);
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const shellModule = shellPackage.module;
 export default shellModule;
 /**
  * This function registers the procedures of @procedures/shell, and of the modules that it requires, in
  * a registry. The default is the global registry. Importing this file registers nothing: the
  * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
  */
-export function registerShellProcedures(registry = PROCEDURE_REGISTRY) {
-    registerModules(registry, [shellModule]);
-}
+export const registerShellProcedures = shellPackage.register;
 //# sourceMappingURL=module.js.map