@procedures/shell 0.34.0 → 0.35.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @procedures/shell
 
+## 0.35.0
+
+### Patch Changes
+
+- 0b0cb42: One CLI-tool runner in `@procedures/shell` (dedupe review F2, tracker item O60).
+  
+  PATCH: new exports `defineCliTool` and `./testing`, no break. Before 1.0.0, a feature raises the PATCH, and the fixed group shares one version.
+  
+  - The new entry `@procedures/shell/cli` gives `defineCliTool({ name, resolve, error })`. Its runner has `run`, `runJson`, `output`, `json`, `arg` and `shellInput`. Each command goes as argv to `shell.run` through `ctx.client`, never as a shell string.
+  - The entry also gives `cliArg()`, `buildArgv()`, `parseJsonDocument()`, `parseJsonOutput()`, the shared result `CliToolOutput` with `cliToolOutputSchema()`, and the program lookup `nodeScript()`, `execPathProgram()` and `findInPath()`. The package root exports them too.
+  - The new entry `@procedures/shell/testing` gives `fakeShell(results)`: the shell procedures with their real schemas, effects and root rules, and handlers that record each input. Use `shell.module` in `createRegistry()`, or `shell.client` as `ctx.client`.
+  - gh, npm, pnpm, docker and `cli.run` run their program through `defineCliTool()`. Each procedure keeps its path, its schemas, its effects and its behavior. The exported helpers (`resolveNpm`, `resolvePnpm`, the output types and schemas) stay.
+  - `PnpmCommandOutput`, `NpmCommandOutput`, `DockerCommandOutput` and `CliRunOutput` extend `CliToolOutput`. Their schemas come from `cliToolOutputSchema()`. The `stderr` description of pnpm and `cli.run` now also names the error message when the program did not start.
+  - `@procedures/restic` and `@procedures/tailscale` re-export `buildArgv`, `parseJsonOutput`, `FLAG_NAME` and `ArgValue` from `@procedures/shell/cli`. The two copies of `argv.ts` are gone.
+  - `@procedures/vite` and `@procedures/vitest` use `cliArg()` for their argument guard.
+  - `SERVER-LAYERS.md` records the one run path of a CLI wrapper, and the reasons.
+- @procedures/client@0.35.0
+
 ## 0.34.0
 
 ### Patch Changes

package/README.md

@@ -326,22 +326,31 @@ const { path, found } = await client.exec(["shell", "which"], {
 
 ### Building CLI Wrappers
 
-The `shell.run` procedure is the foundation for CLI wrapper packages:
+A CLI wrapper package (gh, npm, pnpm, docker, `cli.run`) defines its runner with `defineCliTool()` of `@procedures/shell/cli`. Each command goes as an argument list to `shell.run`, through `ctx.client`, so the host applies its rules to the nested call. `packages/documentation/SERVER-LAYERS.md` ("The run path of a CLI wrapper") gives the reasons.
 
 ```typescript
-// In client-git/src/procedures/git/status.ts
-export async function gitStatus(input: GitStatusInput, ctx: ProcedureContext) {
-  const args = ["status"];
-  if (input.short) args.push("--short");
-
-  const result = await ctx.client.call(["shell", "run"], {
-    command: "git",
-    args,
-    cwd: input.cwd,
-  });
-
-  return parseGitStatus(result.stdout);
-}
+import { cliToolOutputSchema, defineCliTool } from "@procedures/shell/cli";
+
+const docker = defineCliTool({ name: "docker" });
+
+// In a handler: a value that starts with "-" is refused, and no shell runs
+const result = await docker.run(["ps", "--filter", docker.arg("filter", input.filter)], { cwd: input.cwd }, ctx);
+// result: { exitCode, stdout, stderr, success, duration }, the shape of cliToolOutputSchema("docker")
+```
+
+- `run` and `runJson` give a failed result and do not throw. `output` and `json` throw the error of the tool.
+- `resolve` finds the program at each command. `nodeScript()`, `execPathProgram()` and `findInPath()` help to find a script of a `.cmd` file.
+- `buildArgv()`, `parseJsonDocument()` and `parseJsonOutput()` build an argv and read JSON output.
+
+The tests of a wrapper use `fakeShell(results)` of `@procedures/shell/testing`:
+
+```typescript
+import { fakeShell } from "@procedures/shell/testing";
+
+const shell = fakeShell([{ stdout: "[]" }, { exitCode: 1, stderr: "not found" }]);
+const registry = createRegistry(shell.module, dockerModule); // the first module of a name counts
+// or, for a handler that a test calls directly: { client: shell.client }
+expect(shell.args()).toEqual(["ps"]);
 ```
 
 ### Checking Command Availability