@procedures/shell 0.34.0 → 0.35.0

package/dist/testing.js

@@ -0,0 +1,114 @@
+/**
+ * `@procedures/shell/testing`: a fake shell for the tests of the wrapper packages (dedupe review F2).
+ *
+ * `fakeShell(results)` gives the shell procedures with their real schemas, effects and rules of
+ * the root, and handlers that record each input and answer with a scripted result. No program
+ * starts. It gives the same fake in two forms:
+ * - `module`: put it before the module of the wrapper in `createRegistry()`. The first module of
+ *   a name counts, so the fake takes the place of the real shell.
+ * - `client`: give it as `ctx.client` to a handler that a test calls directly.
+ *
+ * This entry point has no side effects: it registers no procedures.
+ */
+import { defineModule } from "@procedures/client";
+import { shellModule } from "./module.js";
+/** The full output of a scripted result. */
+function outputOf(result) {
+    const exitCode = result.exitCode ?? 0;
+    const output = { exitCode, stdout: result.stdout ?? "", stderr: result.stderr ?? "", success: exitCode === 0, duration: 1 };
+    if (result.signal !== undefined)
+        output.signal = result.signal;
+    return output;
+}
+/** The lines of a text, without the line ends and without a last empty line. */
+function linesOf(text) {
+    const lines = text.split(/\r?\n/);
+    if (lines.at(-1) === "")
+        lines.pop();
+    return lines;
+}
+/**
+ * This function gives a fake shell. Each `shell.run` call records its input in `calls` and gives
+ * the next scripted result. Each `shell.stream` call records its input in `streams` and gives the
+ * lines of the result, then the exit item. `shell.exec` throws: a wrapper never runs a shell string.
+ */
+export function fakeShell(results = {}, options = {}) {
+    const calls = [];
+    const streams = [];
+    let index = 0;
+    const next = (input) => {
+        const at = index++;
+        if (typeof results === "function")
+            return results(input, at);
+        if (Array.isArray(results))
+            return results[at] ?? options.fallback ?? {};
+        return results;
+    };
+    const run = (input) => {
+        calls.push(input);
+        return outputOf(next(input));
+    };
+    async function* stream(input) {
+        streams.push(input);
+        const output = outputOf(next(input));
+        for (const line of linesOf(output.stdout))
+            yield { type: "stdout", line };
+        for (const line of linesOf(output.stderr))
+            yield { type: "stderr", line };
+        const exit = { type: "exit", exitCode: output.exitCode, duration: output.duration };
+        if (output.signal !== undefined)
+            exit.signal = output.signal;
+        yield exit;
+    }
+    const procedures = shellModule.procedures.map((procedure) => {
+        switch (procedure.path.join(".")) {
+            case "shell.run":
+                return { ...procedure, handler: async (input) => run(input) };
+            case "shell.stream":
+                return { ...procedure, handler: stream };
+            case "shell.exec":
+                return {
+                    ...procedure,
+                    handler: async () => {
+                        throw new Error("fakeShell: shell.exec runs a shell string, and a wrapper must call shell.run with argv");
+                    },
+                };
+            default:
+                return procedure;
+        }
+    });
+    const refuse = (path) => new Error(`fakeShell: the fake client answers only shell.run and shell.stream, not ${path.join(".")}`);
+    const client = {
+        async call(path, input) {
+            const key = path.join(".");
+            if (key === "shell.run")
+                return run(input);
+            if (key === "shell.stream") {
+                let last;
+                for await (const item of stream(input))
+                    last = item;
+                return last;
+            }
+            throw refuse(path);
+        },
+        stream(path, input) {
+            if (path.join(".") === "shell.stream")
+                return stream(input);
+            throw refuse(path);
+        },
+    };
+    return {
+        calls,
+        streams,
+        procedures,
+        module: defineModule("@procedures/shell", procedures),
+        client,
+        args(at = 0) {
+            const call = calls[at];
+            if (call === undefined)
+                throw new Error(`fakeShell: there is no shell.run call ${at} (${calls.length} calls)`);
+            return call.args;
+        },
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/shell",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Safe command execution for TypeScript: shell.run with argv and no shell, shell.stream line streaming with backpressure, process-tree kill, timeouts and output caps.",
   "keywords": [
     "shell",
@@ -41,6 +41,14 @@
     "./command": {
       "types": "./dist/command/index.d.ts",
       "import": "./dist/command/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
     }
   },
   "files": [
@@ -63,13 +71,13 @@
   },
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.0",
-    "@procedures/fs": "0.34.0",
+    "@procedures/fs": "0.35.0",
     "@types/node": "^22.0.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },
   "dependencies": {
-    "@procedures/client": "0.34.0",
+    "@procedures/client": "0.35.0",
     "zod": "^4.6.5"
   },
   "client": {

package/src/cli/argv.ts

@@ -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: string, value: string): string {
+  if (value.startsWith("-")) {
+    throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+  }
+  return value;
+}
+
+/** 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 const FLAG_NAME: RegExp = /^[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: {
+  readonly path: readonly string[];
+  readonly args?: Readonly<Record<string, ArgValue>> | undefined;
+  readonly positional?: readonly string[] | undefined;
+  readonly flags?: readonly string[] | undefined;
+}): string[] {
+  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: string): unknown {
+  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: string): unknown {
+  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) as unknown);
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,32 @@
+/**
+ * `@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";

package/src/cli/output.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 function cliToolOutputFields(program: string): CliToolOutputFields {
+  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: string): z.ZodType<CliToolOutput> {
+  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: string): z.ZodType<CliToolJsonOutput> {
+  return z.looseObject({
+    ...cliToolOutputFields(program),
+    data: z.unknown().optional().describe("The parsed JSON of the standard output, when it is JSON"),
+  });
+}

package/src/cli/program.ts

@@ -0,0 +1,47 @@
+/**
+ * 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";
+
+/** 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 function nodeScript(script: string): CliProgram {
+  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: { script?: RegExp | undefined; executable?: RegExp | undefined }): CliProgram | undefined {
+  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: (dir: string) => CliProgram | undefined, path: string = process.env["PATH"] ?? ""): CliProgram | undefined {
+  for (const dir of path.split(delimiter)) {
+    if (!dir) continue;
+    const program = find(dir);
+    if (program !== undefined) return program;
+  }
+  return undefined;
+}

package/src/cli/tool.ts

@@ -0,0 +1,164 @@
+/**
+ * `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 { cliArg, parseJsonDocument } from "./argv.js";
+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 class CliToolError extends Error {
+  override readonly name: string = "CliToolError";
+  constructor(
+    message: string,
+    readonly exitCode: number,
+    readonly stderr: string,
+  ) {
+    super(message);
+  }
+}
+
+/** 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>;
+}
+
+/** The first two words of a command, for an error message. */
+function commandWords(name: string, args: readonly string[]): string {
+  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: CliToolOptions): CliTool {
+  const { name } = options;
+  const makeError = options.error ?? ((message: string, exitCode: number, stderr: string) => new CliToolError(message, exitCode, stderr));
+
+  const shellInput = (args: readonly string[], run: CliRunOptions = {}): CliShellInput => {
+    const resolved = options.resolve?.() ?? name;
+    const program: CliProgram = typeof resolved === "string" ? { command: resolved, prefix: [] } : resolved;
+    const input: CliShellInput = { 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: readonly string[], run: CliRunOptions, ctx: CliToolContext): Promise<CliToolOutput> => {
+    const startTime = Date.now();
+    const result = await ctx.client.call<CliShellInput, { exitCode: number; stdout: string; stderr: string }>(["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: readonly string[], run: CliRunOptions, ctx: CliToolContext): Promise<CliToolOutput> => {
+    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: readonly string[], run: CliRunOptions, ctx: CliToolContext): Promise<string> => {
+    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: CliToolJsonOutput = await runCommand(args, run, ctx);
+      const data = parse(result.stdout);
+      if (data !== undefined) result.data = data;
+      return result;
+    },
+    output,
+    async json<T>(args: readonly string[], run: CliRunOptions, ctx: CliToolContext): Promise<T> {
+      const stdout = await output(args, run, ctx);
+      try {
+        return JSON.parse(stdout) as T;
+      } catch {
+        throw makeError(`${commandWords(name, args)} gave no JSON: ${stdout.slice(0, 200)}`, 0, "");
+      }
+    },
+  };
+}

package/src/index.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
@@ -49,5 +51,8 @@ export { shellRun, shellExec, shellWhich, shellStream } from "./procedures/shell
 // 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";