@procedures/shell 0.0.0-stage → 0.1.0

package/dist/procedures/shell/run.js

@@ -0,0 +1,40 @@
+/**
+ * shell.run procedure
+ *
+ * Run a command with arguments and return output.
+ */
+import { runCommand } from "../../command/run.js";
+/**
+ * Most output kept per stream. Output beyond it is dropped (and reported), so a command
+ * that prints without end cannot exhaust memory. The process is not killed.
+ */
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+/**
+ * Run a command with its arguments and no shell. The timeout and `ctx.signal` kill the whole
+ * process tree (deep dive WRP-10).
+ */
+export async function shellRun(input, ctx) {
+    const result = await runCommand(input.command, {
+        args: input.args,
+        cwd: input.cwd,
+        env: input.env,
+        timeout: input.timeout,
+        signal: ctx?.signal,
+        maxOutputBytes: MAX_OUTPUT_BYTES,
+        encoding: input.encoding,
+    });
+    const note = `\n[output truncated at ${MAX_OUTPUT_BYTES} bytes]`;
+    const output = {
+        exitCode: result.exitCode,
+        stdout: result.truncated?.stdout ? result.stdout + note : result.stdout,
+        stderr: result.truncated?.stderr ? result.stderr + note : result.stderr,
+        success: result.success,
+        duration: result.duration,
+    };
+    // A signal means the process was killed (for example by the timeout)
+    if (result.signal) {
+        output.signal = result.signal;
+    }
+    return output;
+}
+//# sourceMappingURL=run.js.map

package/dist/procedures/shell/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/procedures/shell/run.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD;;;GAGG;AACH,MAAM,gBAAgB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAoB,EACpB,GAA0C;IAE1C,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE;QAC7C,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,GAAG,EAAE,MAAM;QACnB,cAAc,EAAE,gBAAgB;QAChC,QAAQ,EAAE,KAAK,CAAC,QAA0B;KAC3C,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,0BAA0B,gBAAgB,SAAS,CAAC;IACjE,MAAM,MAAM,GAAmB;QAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;QACvE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;QACvE,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC;IACF,qEAAqE;IACrE,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/procedures/shell/stream.d.ts

@@ -0,0 +1,20 @@
+/**
+ * shell.stream procedure
+ *
+ * Run a command and stream each output line as it arrives. The procedure is a generator: the
+ * caller reads `{ type: "stdout" | "stderr", line }` items while the command runs, then one
+ * `{ type: "exit" }` item. When the caller stops reading, or its signal aborts, the command and
+ * the programs that it started end.
+ *
+ * The queue to the reader has a limit: when the reader is slow, the command waits in its next
+ * write (deep dive WRP-9). A character whose bytes arrive in two chunks stays whole (deep dive
+ * WRP-2). The work is done by `streamCommand`.
+ */
+import type { ShellStreamInput, ShellStreamItem } from "../../types.js";
+/**
+ * Run a command and stream each output line as it arrives
+ */
+export declare function shellStream(input: ShellStreamInput, ctx?: {
+    signal?: AbortSignal | undefined;
+}): AsyncGenerator<ShellStreamItem, void, undefined>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/procedures/shell/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/procedures/shell/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAExE;;GAEG;AACH,wBAAuB,WAAW,CAChC,KAAK,EAAE,gBAAgB,EACvB,GAAG,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,GACzC,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC,CAoBlD"}

package/dist/procedures/shell/stream.js

@@ -0,0 +1,39 @@
+/**
+ * shell.stream procedure
+ *
+ * Run a command and stream each output line as it arrives. The procedure is a generator: the
+ * caller reads `{ type: "stdout" | "stderr", line }` items while the command runs, then one
+ * `{ type: "exit" }` item. When the caller stops reading, or its signal aborts, the command and
+ * the programs that it started end.
+ *
+ * The queue to the reader has a limit: when the reader is slow, the command waits in its next
+ * write (deep dive WRP-9). A character whose bytes arrive in two chunks stays whole (deep dive
+ * WRP-2). The work is done by `streamCommand`.
+ */
+import { streamCommand } from "../../command/stream.js";
+/**
+ * Run a command and stream each output line as it arrives
+ */
+export async function* shellStream(input, ctx) {
+    // No shell: the arguments cannot inject commands
+    for await (const item of streamCommand(input.command, {
+        args: input.args,
+        cwd: input.cwd,
+        env: input.env,
+        timeout: input.timeout,
+        signal: ctx?.signal,
+    })) {
+        if (item.type === "exit") {
+            yield {
+                type: "exit",
+                exitCode: item.exitCode,
+                duration: item.duration,
+                ...(item.signal ? { signal: item.signal } : {}),
+            };
+        }
+        else {
+            yield item;
+        }
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/procedures/shell/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../../src/procedures/shell/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAGxD;;GAEG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,CAChC,KAAuB,EACvB,GAA0C;IAE1C,iDAAiD;IACjD,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE;QACpD,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,GAAG,EAAE,MAAM;KACpB,CAAC,EAAE,CAAC;QACH,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC;QACb,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/procedures/shell/which.d.ts

@@ -0,0 +1,10 @@
+/**
+ * shell.which procedure
+ *
+ * Find the full path to a command.
+ */
+import type { ShellWhichInput, ShellWhichOutput } from "../../types.js";
+export declare function shellWhich(input: ShellWhichInput, ctx?: {
+    signal?: AbortSignal | undefined;
+}): Promise<ShellWhichOutput>;
+//# sourceMappingURL=which.d.ts.map

package/dist/procedures/shell/which.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"which.d.ts","sourceRoot":"","sources":["../../../src/procedures/shell/which.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAExE,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,GAAG,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAA;CAAE,GACzC,OAAO,CAAC,gBAAgB,CAAC,CAa3B"}

package/dist/procedures/shell/which.js

@@ -0,0 +1,21 @@
+/**
+ * shell.which procedure
+ *
+ * Find the full path to a command.
+ */
+import { runCommand } from "../../command/run.js";
+export async function shellWhich(input, ctx) {
+    // The name is one argument of where/which, with no shell. (Before, `where ${command}` ran in a
+    // shell, so a name such as `x & calc` ran a second command: deep dive WRP-6.)
+    if (input.command.startsWith("-")) {
+        return { path: null, found: false };
+    }
+    const program = process.platform === "win32" ? "where" : "which";
+    const result = await runCommand(program, { args: [input.command], signal: ctx?.signal, timeout: 30_000 });
+    if (!result.success) {
+        return { path: null, found: false };
+    }
+    const path = result.stdout.trim().split(/\r?\n/)[0]?.trim() ?? "";
+    return path.length > 0 ? { path, found: true } : { path: null, found: false };
+}
+//# sourceMappingURL=which.js.map

package/dist/procedures/shell/which.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"which.js","sourceRoot":"","sources":["../../../src/procedures/shell/which.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAsB,EACtB,GAA0C;IAE1C,+FAA+F;IAC/F,8EAA8E;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IACjE,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1G,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAClE,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAChF,CAAC"}

package/dist/register.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Importing this file registers the procedures of @procedures/shell in the global registry
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as data
+ * are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+export * from "./module.js";
+export declare function registerShellProcedures(): void;
+//# sourceMappingURL=register.d.ts.map

package/dist/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,cAAc,aAAa,CAAC;AAE5B,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/register.js

@@ -0,0 +1,14 @@
+/**
+ * Importing this file registers the procedures of @procedures/shell in the global registry
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as data
+ * are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+import { registerProcedures } from "@procedures/client";
+import { shellModule } from "./module.js";
+export * from "./module.js";
+export function registerShellProcedures() {
+    registerProcedures(shellModule.procedures);
+}
+// Auto-register when this module is loaded
+registerShellProcedures();
+//# sourceMappingURL=register.js.map

package/dist/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../src/register.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,cAAc,aAAa,CAAC;AAE5B,MAAM,UAAU,uBAAuB;IACrC,kBAAkB,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED,2CAA2C;AAC3C,uBAAuB,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shell command types
+ */
+import { z } from "zod";
+export declare const ShellRunInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    encoding: z.ZodDefault<z.ZodString>;
+}>;
+export type ShellRunInput = z.infer<typeof ShellRunInputSchema>;
+export interface ShellRunOutput {
+    /** Exit code */
+    exitCode: number;
+    /** Standard output */
+    stdout: string;
+    /** Standard error */
+    stderr: string;
+    /** Whether command succeeded (exit code 0) */
+    success: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+    /** The signal that ended the process, if it was killed (for example by the timeout) */
+    signal?: string | undefined;
+}
+export declare const ShellExecInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    shell: z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    maxBuffer: z.ZodOptional<z.ZodNumber>;
+    stdin: z.ZodOptional<z.ZodString>;
+}>;
+export type ShellExecInput = z.infer<typeof ShellExecInputSchema>;
+export interface ShellExecOutput {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    success: boolean;
+    duration: number;
+    /** Signal that terminated the process (if any) */
+    signal?: string | undefined;
+}
+export declare const ShellWhichInputSchema: z.ZodObject<{
+    command: z.ZodString;
+}>;
+export type ShellWhichInput = z.infer<typeof ShellWhichInputSchema>;
+export interface ShellWhichOutput {
+    /** Full path to command, or null if not found */
+    path: string | null;
+    /** Whether command was found */
+    found: boolean;
+}
+export declare const ShellStreamInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}>;
+export type ShellStreamInput = z.infer<typeof ShellStreamInputSchema>;
+/** One item of shell.stream: an output line, or the exit of the command (the last item). */
+export type ShellStreamItem = {
+    type: "stdout" | "stderr";
+    line: string;
+} | {
+    type: "exit";
+    exitCode: number;
+    duration: number;
+    signal?: string | undefined;
+};
+export declare const ShellRunOutputSchema: z.ZodType<ShellRunOutput>;
+export declare const ShellExecOutputSchema: z.ZodType<ShellExecOutput>;
+export declare const ShellWhichOutputSchema: z.ZodType<ShellWhichOutput>;
+export declare const ShellStreamItemSchema: z.ZodType<ShellStreamItem>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,89 @@
+/**
+ * Shell command types
+ */
+import { z } from "zod";
+// =============================================================================
+// shell.run Types
+// =============================================================================
+export const ShellRunInputSchema = z.object({
+    /** Command to run */
+    command: z.string().describe("Command to run"),
+    /** Arguments to pass */
+    args: z.array(z.string()).default([]).describe("Arguments to pass"),
+    /** Working directory */
+    cwd: z.string().optional().describe("Working directory"),
+    /** Environment variables to set */
+    env: z.record(z.string(), z.string()).optional().describe("Environment variables to set"),
+    /** Timeout in milliseconds */
+    timeout: z.number().optional().describe("Timeout in milliseconds"),
+    /** Encoding for output (default: utf8) */
+    encoding: z.string().default("utf8").describe("Encoding for output (default: utf8)"),
+});
+// =============================================================================
+// shell.exec Types (more options)
+// =============================================================================
+export const ShellExecInputSchema = z.object({
+    /** Full command string to execute via shell */
+    command: z.string().describe("Full command string to execute via shell"),
+    /** Working directory */
+    cwd: z.string().optional().describe("Working directory"),
+    /** Environment variables */
+    env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+    /** Timeout in milliseconds. At the timeout, the shell and the programs that it started are killed. */
+    timeout: z.number().optional().describe("Timeout in milliseconds. At the timeout, the shell and the programs that it started are killed."),
+    /** Shell to use: a path, or `true` for the system shell (`cmd.exe` or `/bin/sh`). `false` is the same as `true`. */
+    shell: z.union([z.boolean(), z.string()]).default(true).describe("Shell to use: a path, or `true` for the system shell (`cmd.exe` or `/bin/sh`). `false` is the same as `true`."),
+    /** The most bytes kept of each output stream (default: 64 MiB). The procedure drops the rest. */
+    maxBuffer: z.number().optional().describe("The most bytes kept of each output stream (default: 64 MiB). The procedure drops the rest."),
+    /** Text to write to stdin. Without it, stdin is empty. */
+    stdin: z.string().optional().describe("Text to write to stdin. Without it, stdin is empty."),
+});
+// =============================================================================
+// shell.which Types
+// =============================================================================
+export const ShellWhichInputSchema = z.object({
+    /** Command to find */
+    command: z.string().describe("Command to find"),
+});
+// =============================================================================
+// shell.stream Types - Run a command and stream each output line as it arrives
+// =============================================================================
+export const ShellStreamInputSchema = z.object({
+    command: z.string().describe("The program to start (no shell: arguments go in args)"),
+    args: z.array(z.string()).default([]).describe("The arguments of the program"),
+    cwd: z.string().optional().describe("Working directory"),
+    env: z.record(z.string(), z.string()).optional().describe("Environment variables (added to the environment of the host)"),
+    timeout: z.number().optional().describe("Timeout in milliseconds. At the timeout, the program and its children are killed."),
+});
+// =============================================================================
+// Output schemas (roadmap 2.1)
+// =============================================================================
+// Loose objects: a field that a schema does not name stays in the result (a strict schema would
+// remove it when the output is validated).
+const commandResult = {
+    exitCode: z.number().describe("The exit code (0 is success, -1 when a signal ended the program)"),
+    stdout: z.string().describe("The standard output"),
+    stderr: z.string().describe("The standard error"),
+    success: z.boolean().describe("True when the exit code is 0"),
+    duration: z.number().describe("The time of the command, in milliseconds"),
+    signal: z.string().optional().describe("The signal that ended the program (for example at the timeout)"),
+};
+export const ShellRunOutputSchema = z.looseObject(commandResult);
+export const ShellExecOutputSchema = z.looseObject(commandResult);
+export const ShellWhichOutputSchema = z.looseObject({
+    path: z.string().nullable().describe("The full path of the program, or null when it is not found"),
+    found: z.boolean().describe("True when the program is found"),
+});
+export const ShellStreamItemSchema = z.union([
+    z.looseObject({
+        type: z.enum(["stdout", "stderr"]).describe("The stream of the line"),
+        line: z.string().describe("One line of output, without its line end"),
+    }),
+    z.looseObject({
+        type: z.literal("exit").describe("The end of the stream (the last item)"),
+        exitCode: z.number().describe("The exit code (-1 when a signal ended the program)"),
+        duration: z.number().describe("The time of the command, in milliseconds"),
+        signal: z.string().optional().describe("The signal that ended the program"),
+    }),
+]);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -1,6 +1,81 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.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",
+    "exec",
+    "spawn",
+    "child-process",
+    "streaming",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-shell"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./command": {
+      "types": "./dist/command/index.d.ts",
+      "import": "./dist/command/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "dependencies": {
+    "@procedures/client": "0.1.0",
+    "zod": "^4.6.5"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/command/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `@procedures/shell/command`: the helpers that start programs (roadmap 2.2).
+ *
+ * Each wrapper package starts its program through these helpers:
+ * - an argument list, never a shell string;
+ * - `ctx.signal` and a timeout kill the whole process tree;
+ * - each output stream has a limit;
+ * - a long-running process has a record in `processes`, and ends with the host.
+ *
+ * This entry point has no side effects: unlike the package root, it registers no procedures.
+ */
+
+export { runCommand, type CommandOptions, type CommandResult } from "./run.js";
+export { streamCommand, type StreamCommandOptions, type CommandStreamItem } from "./stream.js";
+export {
+  ProcessRegistry,
+  processes,
+  type ManagedProcessInfo,
+  type StartProcessOptions,
+  type StopResult,
+} from "./processes.js";
+export { killTree } from "./tree-kill.js";
+export type { SpawnOptions } from "./spawn.js";
+export { DEFAULT_MAX_OUTPUT_BYTES } from "./output.js";

package/src/command/output.ts

@@ -0,0 +1,67 @@
+/**
+ * Collect the output of a stream as bytes, with a limit.
+ *
+ * The collector decodes the bytes once at the end, so a multibyte character split across two
+ * chunks stays whole (BUGS-2026-07 L4). Past the limit, it keeps the first bytes ("head") or the
+ * last bytes ("tail"), so a program that prints without end cannot fill the memory.
+ */
+
+/** The default limit of each output stream. */
+export const DEFAULT_MAX_OUTPUT_BYTES: number = 64 * 1024 * 1024;
+
+export class OutputCollector {
+  private chunks: Buffer[] = [];
+  private bytes = 0;
+  truncated = false;
+
+  constructor(
+    private readonly limit: number = DEFAULT_MAX_OUTPUT_BYTES,
+    private readonly keep: "head" | "tail" = "head",
+  ) {}
+
+  add(chunk: Buffer): void {
+    if (this.keep === "head") {
+      const room = this.limit - this.bytes;
+      if (room <= 0) {
+        this.truncated = true;
+        return;
+      }
+      const kept = chunk.length > room ? chunk.subarray(0, room) : chunk;
+      if (kept.length < chunk.length) this.truncated = true;
+      this.chunks.push(kept);
+      this.bytes += kept.length;
+      return;
+    }
+    this.chunks.push(chunk);
+    this.bytes += chunk.length;
+    // Drop whole chunks from the start while the rest is above the limit, then cut the first one
+    while (this.bytes > this.limit && this.chunks.length > 0) {
+      const first = this.chunks[0]!;
+      const excess = this.bytes - this.limit;
+      this.truncated = true;
+      if (first.length <= excess) {
+        this.chunks.shift();
+        this.bytes -= first.length;
+      } else {
+        this.chunks[0] = first.subarray(excess);
+        this.bytes -= excess;
+      }
+    }
+  }
+
+  /** The collected bytes. */
+  buffer(): Buffer {
+    let data = Buffer.concat(this.chunks);
+    // A cut tail can start inside a UTF-8 character: drop its continuation bytes
+    if (this.keep === "tail" && this.truncated) {
+      let start = 0;
+      while (start < data.length && start < 4 && (data[start]! & 0xc0) === 0x80) start++;
+      data = data.subarray(start);
+    }
+    return data;
+  }
+
+  text(encoding: BufferEncoding = "utf8"): string {
+    return this.buffer().toString(encoding);
+  }
+}