@mypolis.eu/command 0.1.0 → 0.2.0

package/README.md

@@ -2,46 +2,31 @@
 
 Lazy, terminal-first commands without a shell. ESM JavaScript with TypeScript declarations, for Node.js 24+. No runtime dependencies.
 
-```sh
-npm install @mypolis.eu/command
-```
-
 ```js
-import {$, CommandError} from '@mypolis.eu/command';
+import {$, createRunner, CommandError} from '@mypolis.eu/command';
 
-// Inherit the terminal, including interactive stdin. Resolves to undefined.
-await $`git status`;
-
-// Optional timeout, configured before execution; no timeout by default.
-await $`git fetch`.timeout(30_000);
-
-// Capture raw UTF-8 stdout without trimming whitespace or trailing newlines.
+await $`git status`; // inherited terminal, no timeout
 const branch = await $`git branch --show-current`.text();
-const {stdout, stderr} = await $`git status --short`.output();
+const result = await $`git status --short`.output();
+await $`git fetch`.timeout(30_000);
 
-// Each interpolation is a whole argument; arrays expand into arguments.
-const paths = ['notes with spaces.md', 'draft.md'];
-await $`git diff -- ${paths}`;
+const controller = new AbortController();
+const run = createRunner({timeoutMs: 30_000, maxBufferBytes: 4 * 1024 * 1024});
+await run`some-command`.signal(controller.signal).output();
+await run`interactive-command`.timeout(null); // disable an inherited timeout
 ```
 
-Commands inherit the current working directory and environment. Awaiting a command streams stdout and stderr to the terminal. `.text()` and `.output()` instead capture **both** streams; stdin remains inherited. `.text()` returns only stdout, while `.output()` returns both streams.
+Awaiting a command streams stdout and stderr to the terminal. `.text()` captures raw stdout and stderr for failures; `.output()` returns both captured streams. Captured output has a 4 MiB combined byte budget by default. Use `.maxBuffer(bytes)` or `createRunner({maxBufferBytes})` to change it. Output is never implicitly trimmed.
 
-## Arguments, not Bash
+`.timeout(ms)` accepts a positive finite millisecond value; `$` has no default timeout. `.signal(signal)` accepts an `AbortSignal`; aborting terminates the command with SIGTERM and escalates to SIGKILL after 500 ms. A pre-aborted signal does not spawn the command, and its reason is available as `CommandError.cause`. `.processGroup()` opts into a separate Linux/macOS process group so timeout, abort, overflow and forwarded signals target the command's group. Group mode is false by default; configured runners may set it true, and `.processGroup(false)` overrides it. Normal execution settles when the immediate child closes. Controlled group termination waits for the escalation grace period, then signals the original process group ID before settling. This is best effort: descendants that detach into another group or session can escape.
 
-Literal text is split on whitespace. Interpolate strings or numbers for whole arguments; interpolate arrays of strings or numbers for multiple arguments. Empty strings are preserved and empty arrays add no arguments. Separate interpolations from adjacent arguments with whitespace. To combine a prefix and value, interpolate the complete string:
+Construction is lazy and awaiting, `.then()`, `.text()` or `.output()` starts one shared execution. Capture mode and options must be selected before starting. Repeated use returns the original result or failure. `.timeout(null)` explicitly disables a configured runner timeout.
 
-```js
-const count = 5;
-await $`git log ${`--max-count=${count}`}`;
-```
-
-Quoting, pipes, redirects, globs, environment expansion and other shell syntax in literal text are rejected. Characters in interpolated values are passed literally, not evaluated by a shell. This prevents shell expansion, not interpretation of options by the executable: use `--` where supported when passing untrusted filenames. Choose the executable and its arguments appropriately.
-
-## Lazy execution and reuse
+## Arguments, not Bash
 
-Construction does not spawn a process. Awaiting or calling `.then()`, `.text()` or `.output()` starts one shared execution. Repeated use returns the original result or failure, not a new process. `.text()` and `.output()` can share the same capture execution. Switching between inherited and captured stdio after starting is rejected. `.timeout(ms)` must be called before starting;
+Literal text is split on whitespace. Interpolate strings or numbers for whole arguments; arrays expand into multiple arguments. Quoting, pipes, redirects, globs, environment expansion and other shell syntax in literal text are rejected. Interpolated values are passed literally. Use `--` where supported when passing untrusted filenames.
 
-## Failures and limits
+## Failures
 
 ```js
 try {
@@ -53,6 +38,8 @@ try {
 }
 ```
 
+`CommandError.reason` is one of `spawn`, `exit`, `signal`, `timeout`, `overflow`, or `abort`. Captured failures retain only the bounded output prefix; overflow is an explicit failure, not successful truncation.
+
 ## License
 
 MIT © MyPolis

package/dist/index.d.ts

@@ -4,7 +4,12 @@ type Output = {
     stdout: string;
     stderr: string;
 };
-type FailureReason = "spawn" | "exit" | "signal" | "timeout" | "overflow";
+type FailureReason = "spawn" | "exit" | "signal" | "timeout" | "overflow" | "abort";
+export type RunnerOptions = {
+    timeoutMs?: number;
+    maxBufferBytes?: number;
+    processGroup?: boolean;
+};
 export declare class CommandError extends Error {
     readonly reason: FailureReason;
     readonly exitCode: number | null;
@@ -18,19 +23,20 @@ export declare class CommandError extends Error {
         signal: NodeJS.Signals | null;
         code?: string;
         output?: Output;
+        cause?: unknown;
     });
 }
 type Command = PromiseLike<undefined> & {
-    timeout(ms: number): Command;
+    timeout(ms: number | null): Command;
+    maxBuffer(bytes: number): Command;
+    processGroup(enabled?: boolean): Command;
+    signal(signal: AbortSignal): Command;
     text(): Promise<string>;
     output(): Promise<Output>;
 };
-/**
- * Lazy, shell-free command; awaiting inherits cwd, environment and stdio.
- * Interpolations occupy whole arguments; arrays expand into multiple arguments.
- * .text()/.output() capture raw UTF-8 (1 MiB per stream); .timeout(ms) configures before execution.
- * Execution is shared; capture mode cannot change and timeout is frozen after starting.
- * Timeout/overflow sends SIGTERM, then SIGKILL after 500 ms; settlement always waits for close.
- */
-export declare function $(strings: TemplateStringsArray, ...values: Values): Command;
+type Runner = (strings: TemplateStringsArray, ...values: Values) => Command;
+/** Creates a command tag with reusable timeout, capture-budget and process-group defaults. */
+export declare function createRunner(defaults?: RunnerOptions): Runner;
+/** Lazy, shell-free command tag. Awaiting streams to the terminal; text/output capture raw UTF-8. */
+export declare const $: Runner;
 export {};

package/dist/index.js

@@ -1,9 +1,11 @@
 import { spawn } from "node:child_process";
-const CAPTURE_LIMIT = 1024 * 1024; // Bytes per stream; overflow terminates rather than silently truncating.
+import { addAbortListener } from "node:events";
+const DEFAULT_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
 const TERMINATION_GRACE_MS = 500;
+const MAX_TIMEOUT_MS = 2_147_483_647;
 export class CommandError extends Error {
     constructor(message, details) {
-        super(message);
+        super(message, details.cause === undefined ? undefined : { cause: details.cause });
         this.name = "CommandError";
         this.reason = details.reason;
         this.exitCode = details.exitCode;
@@ -13,58 +15,106 @@ export class CommandError extends Error {
         this.stderr = details.output?.stderr;
     }
 }
-/**
- * Lazy, shell-free command; awaiting inherits cwd, environment and stdio.
- * Interpolations occupy whole arguments; arrays expand into multiple arguments.
- * .text()/.output() capture raw UTF-8 (1 MiB per stream); .timeout(ms) configures before execution.
- * Execution is shared; capture mode cannot change and timeout is frozen after starting.
- * Timeout/overflow sends SIGTERM, then SIGKILL after 500 ms; settlement always waits for close.
- */
-export function $(strings, ...values) {
-    let execution;
-    const options = {};
-    const start = (capture) => {
-        if (execution) {
-            if (options.capture !== capture)
-                throw new Error("Command capture mode cannot change after execution starts.");
-            return execution;
-        }
-        options.capture = capture;
-        execution = execute(options, strings, values);
-        return execution;
+/** Creates a command tag with reusable timeout, capture-budget and process-group defaults. */
+export function createRunner(defaults = {}) {
+    if (defaults === null || typeof defaults !== "object" || Array.isArray(defaults))
+        throw new TypeError("Runner options must be an object.");
+    for (const key of Object.keys(defaults)) {
+        if (key !== "timeoutMs" && key !== "maxBufferBytes" && key !== "processGroup")
+            throw new TypeError(`Unknown runner option: ${key}.`);
+    }
+    if (defaults.timeoutMs !== undefined &&
+        (!Number.isFinite(defaults.timeoutMs) || defaults.timeoutMs <= 0 || defaults.timeoutMs > MAX_TIMEOUT_MS)) {
+        throw new TypeError("Timeout must be finite, positive and at most 2147483647 ms.");
+    }
+    if (defaults.maxBufferBytes !== undefined &&
+        (!Number.isSafeInteger(defaults.maxBufferBytes) || defaults.maxBufferBytes <= 0)) {
+        throw new TypeError("Maximum buffer must be a positive safe integer.");
+    }
+    if (defaults.processGroup !== undefined && typeof defaults.processGroup !== "boolean")
+        throw new TypeError("Process group must be a boolean.");
+    if (defaults.processGroup && process.platform !== "darwin" && process.platform !== "linux")
+        throw new Error("Process groups are only supported on Linux and macOS.");
+    const runnerDefaults = {
+        timeoutMs: defaults.timeoutMs,
+        maxBufferBytes: defaults.maxBufferBytes,
+        processGroup: defaults.processGroup === true
     };
-    const command = {
-        // biome-ignore lint/suspicious/noThenProperty: Awaiting this lazy command intentionally starts shared execution.
-        then(onfulfilled, onrejected) {
-            return start(false)
-                .then(() => undefined)
-                .then(onfulfilled, onrejected);
-        },
-        timeout(ms) {
-            if (!Number.isFinite(ms) || ms <= 0 || ms > 2_147_483_647) {
-                throw new TypeError("Timeout must be finite, positive and at most 2147483647 ms.");
-            }
-            if (execution)
-                throw new Error("Command timeout cannot change after execution starts.");
-            options.timeoutMs = ms;
-            return command;
-        },
-        async text() {
-            const { stdout } = await start(true);
-            return stdout;
-        },
-        output() {
-            return start(true);
-        }
+    return (strings, ...values) => {
+        let execution;
+        const options = { ...runnerDefaults };
+        const start = (capture) => {
+            if (execution) {
+                if (options.capture !== capture)
+                    throw new Error("Command capture mode cannot change after execution starts.");
+                return execution;
+            }
+            options.capture = capture;
+            execution = execute(options, strings, values);
+            return execution;
+        };
+        const command = {
+            // biome-ignore lint/suspicious/noThenProperty: Awaiting this lazy command intentionally starts shared execution.
+            then(onfulfilled, onrejected) {
+                return start(false)
+                    .then(() => undefined)
+                    .then(onfulfilled, onrejected);
+            },
+            timeout(ms) {
+                if (execution)
+                    throw new Error("Command timeout cannot change after execution starts.");
+                if (ms === null)
+                    delete options.timeoutMs;
+                else {
+                    if (!Number.isFinite(ms) || ms <= 0 || ms > MAX_TIMEOUT_MS)
+                        throw new TypeError("Timeout must be finite, positive and at most 2147483647 ms.");
+                    options.timeoutMs = ms;
+                }
+                return command;
+            },
+            maxBuffer(bytes) {
+                if (execution)
+                    throw new Error("Command maximum buffer cannot change after execution starts.");
+                if (!Number.isSafeInteger(bytes) || bytes <= 0)
+                    throw new TypeError("Maximum buffer must be a positive safe integer.");
+                options.maxBufferBytes = bytes;
+                return command;
+            },
+            processGroup(enabled = true) {
+                if (execution)
+                    throw new Error("Command process group cannot change after execution starts.");
+                if (typeof enabled !== "boolean")
+                    throw new TypeError("Process group must be a boolean.");
+                if (enabled && process.platform !== "darwin" && process.platform !== "linux")
+                    throw new Error("Process groups are only supported on Linux and macOS.");
+                options.processGroup = enabled;
+                return command;
+            },
+            signal(signal) {
+                if (execution)
+                    throw new Error("Command signal cannot change after execution starts.");
+                if (!(signal instanceof AbortSignal))
+                    throw new TypeError("Signal must be an AbortSignal.");
+                options.signal = signal;
+                return command;
+            },
+            text() {
+                return start(true).then(({ stdout }) => stdout);
+            },
+            output() {
+                return start(true);
+            }
+        };
+        return command;
     };
-    return command;
 }
+/** Lazy, shell-free command tag. Awaiting streams to the terminal; text/output capture raw UTF-8. */
+export const $ = createRunner();
 async function execute(options, strings, values) {
     const args = [];
     for (const [index, text] of strings.entries()) {
-        if (/["'`\\$|&;<>*?()[\]{}~#\0]/.test(text)) {
+        if (/["'`\\$|&;<>*?()[\]{}~#\0]/.test(text))
             throw new Error("Shell syntax is not supported. Interpolate argument values instead.");
-        }
         if ((index > 0 && text !== "" && !/^\s/.test(text)) ||
             (index < values.length && text !== "" && !/\s$/.test(text)) ||
             (index > 0 && index < values.length && text === "")) {
@@ -72,12 +122,10 @@ async function execute(options, strings, values) {
         }
         args.push(...text.split(/\s+/).filter(Boolean));
         if (index < values.length) {
-            const value = values[index];
-            const items = Array.isArray(value) ? value : [value];
+            const items = Array.isArray(values[index]) ? values[index] : [values[index]];
             for (const item of items) {
-                if (typeof item !== "string" && typeof item !== "number") {
+                if (typeof item !== "string" && typeof item !== "number")
                     throw new TypeError("Arguments must be strings or numbers.");
-                }
                 if (String(item).includes("\0"))
                     throw new TypeError("Arguments must not contain null bytes.");
                 args.push(String(item));
@@ -87,15 +135,26 @@ async function execute(options, strings, values) {
     const command = args.shift();
     if (!command)
         throw new Error("A command is required.");
+    if (options.signal?.aborted)
+        throw new CommandError("Command was aborted.", {
+            reason: "abort",
+            exitCode: null,
+            signal: null,
+            output: options.capture ? { stdout: "", stderr: "" } : undefined,
+            cause: options.signal.reason
+        });
     let child;
     try {
         child = spawn(command, args, {
             stdio: options.capture ? ["inherit", "pipe", "pipe"] : "inherit",
-            shell: false
+            shell: false,
+            detached: options.processGroup === true
         });
     }
     catch (error) {
-        const { code } = error;
+        let code;
+        if (error instanceof Error && "code" in error && typeof error.code === "string")
+            code = error.code;
         throw new CommandError(`Command could not be spawned (${code ?? "process error"}).`, {
             reason: "spawn",
             exitCode: null,
@@ -111,86 +170,165 @@ async function execute(options, strings, values) {
         let overflowStream;
         let timeout;
         let escalation;
+        let closed = false;
+        let escalationDone = true;
+        let settled = false;
+        let managedSignal;
         const chunks = { stdout: [], stderr: [] };
-        const bytes = { stdout: 0, stderr: 0 };
-        const terminate = (reason) => {
+        let capturedBytes = 0;
+        const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+        const groupPid = child.pid;
+        const send = (signal) => {
+            try {
+                if (options.processGroup === true) {
+                    if (groupPid === undefined) {
+                        failure ??= new Error("Command process group has no process ID.");
+                        return;
+                    }
+                    process.kill(-groupPid, signal);
+                }
+                else
+                    child.kill(signal);
+            }
+            catch (error) {
+                if (error instanceof Error && !("code" in error && error.code === "ESRCH"))
+                    failure ??= error;
+            }
+        };
+        const terminate = (reason, initialSignal = "SIGTERM") => {
             if (stopped)
                 return;
             stopped = reason;
-            child.kill("SIGTERM");
-            escalation = setTimeout(() => child.kill("SIGKILL"), TERMINATION_GRACE_MS);
+            managedSignal = initialSignal;
+            // Only managed group cancellation waits beyond direct-child close.
+            escalationDone = options.processGroup !== true;
+            send(initialSignal);
+            escalation = setTimeout(() => {
+                managedSignal = "SIGKILL";
+                send("SIGKILL");
+                escalationDone = true;
+                finish();
+            }, TERMINATION_GRACE_MS);
         };
         const collect = (stream, chunk) => {
-            const remaining = CAPTURE_LIMIT - bytes[stream];
+            const remaining = maxBufferBytes - capturedBytes;
             if (remaining > 0) {
                 const retained = Buffer.from(chunk.subarray(0, remaining));
                 chunks[stream].push(retained);
-                bytes[stream] += retained.length;
+                capturedBytes += retained.length;
             }
             if (chunk.length > remaining) {
                 overflowStream ??= stream;
                 terminate("overflow");
             }
         };
-        const onStdout = (chunk) => collect("stdout", chunk);
-        const onStderr = (chunk) => collect("stderr", chunk);
         const onError = (error) => {
             failure ??= error;
         };
-        const forwardSignal = (signal) => {
-            interrupted ??= signal;
-            child.kill(signal);
+        const onAbort = () => terminate("abort");
+        const onInterrupt = () => {
+            if (!stopped) {
+                interrupted = "SIGINT";
+                terminate("signal", "SIGINT");
+            }
+            else
+                send("SIGINT");
         };
-        const onInterrupt = () => forwardSignal("SIGINT");
-        const onTerminate = () => forwardSignal("SIGTERM");
-        process.on("SIGINT", onInterrupt);
-        process.on("SIGTERM", onTerminate);
-        child.on("error", onError);
-        child.stdout?.on("data", onStdout);
-        child.stderr?.on("data", onStderr);
-        if (options.timeoutMs !== undefined)
-            timeout = setTimeout(() => terminate("timeout"), options.timeoutMs);
-        child.once("close", (exitCode, signal) => {
+        const onTerminate = () => {
+            if (!stopped) {
+                interrupted = "SIGTERM";
+                terminate("signal", "SIGTERM");
+            }
+            else
+                send("SIGTERM");
+        };
+        let abortListener;
+        const finish = () => {
+            if (settled || !closed || !escalationDone)
+                return;
+            settled = true;
             clearTimeout(timeout);
-            clearTimeout(escalation);
+            if (escalation)
+                clearTimeout(escalation);
             process.removeListener("SIGINT", onInterrupt);
             process.removeListener("SIGTERM", onTerminate);
+            abortListener?.[Symbol.dispose]();
             child.removeListener("error", onError);
             child.stdout?.removeListener("data", onStdout);
             child.stderr?.removeListener("data", onStderr);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
             let output;
-            if (options.capture)
+            if (options.capture) {
                 output = {
                     stdout: Buffer.concat(chunks.stdout).toString("utf8"),
                     stderr: Buffer.concat(chunks.stderr).toString("utf8")
                 };
+            }
             let reason;
             let message;
-            if (stopped === "timeout") {
-                reason = stopped;
+            let actualSignal = interrupted ?? signal ?? (managedSignal === "SIGKILL" ? managedSignal : null);
+            let actualExitCode = exitCode;
+            if (stopped === "abort") {
+                reason = "abort";
+                message = "Command was aborted.";
+            }
+            else if (stopped === "timeout") {
+                reason = "timeout";
                 message = `Command timed out after ${options.timeoutMs} ms.`;
             }
             else if (stopped === "overflow") {
-                reason = stopped;
-                message = `Command ${overflowStream} exceeded the ${CAPTURE_LIMIT}-byte capture limit.`;
+                reason = "overflow";
+                message = `Command ${overflowStream} exceeded the ${maxBufferBytes}-byte combined capture limit.`;
             }
             else if (failure) {
                 reason = "spawn";
-                message = `Command failed (${failure.code ?? "process error"}).`;
+                message = `Command could not be spawned (${failure.code ?? "process error"}).`;
+                actualExitCode = null;
+                actualSignal = null;
             }
-            else if (interrupted || signal) {
+            else if (stopped === "signal" || interrupted || signal) {
                 reason = "signal";
-                message = `Command failed (${interrupted ?? signal}).`;
+                message = `Command failed (${interrupted ?? signal ?? managedSignal}).`;
             }
             else if (exitCode !== 0) {
                 reason = "exit";
                 message = `Command failed (exit ${exitCode}).`;
+                actualSignal = signal;
             }
             else {
                 resolve(output ?? { stdout: "", stderr: "" });
                 return;
             }
-            reject(new CommandError(message, { reason, exitCode, signal: interrupted ?? signal, code: failure?.code, output }));
+            reject(new CommandError(message, {
+                reason,
+                exitCode: actualExitCode,
+                signal: actualSignal,
+                code: reason === "spawn" ? failure?.code : undefined,
+                output,
+                cause: reason === "abort" ? options.signal?.reason : undefined
+            }));
+        };
+        let exitCode = null;
+        let signal = null;
+        const onStdout = (chunk) => collect("stdout", chunk);
+        const onStderr = (chunk) => collect("stderr", chunk);
+        process.on("SIGINT", onInterrupt);
+        process.on("SIGTERM", onTerminate);
+        if (options.signal)
+            abortListener = addAbortListener(options.signal, onAbort);
+        child.on("error", onError);
+        child.stdout?.on("data", onStdout);
+        child.stderr?.on("data", onStderr);
+        if (options.timeoutMs !== undefined)
+            timeout = setTimeout(() => terminate("timeout"), options.timeoutMs);
+        child.once("close", (code, childSignal) => {
+            closed = true;
+            exitCode = code;
+            signal = childSignal;
+            finish();
         });
+        if (options.signal?.aborted)
+            onAbort();
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mypolis.eu/command",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Lazy, terminal-first, shell-free commands for Node.js.",
 	"type": "module",
 	"license": "MIT",
@@ -12,7 +12,12 @@
 		"access": "public",
 		"registry": "https://registry.npmjs.org/"
 	},
-	"files": ["dist/index.js", "dist/index.d.ts", "README.md", "LICENSE"],
+	"files": [
+		"dist/index.js",
+		"dist/index.d.ts",
+		"README.md",
+		"LICENSE"
+	],
 	"scripts": {
 		"build": "tsc -p tsconfig.build.json",
 		"prepack": "npm run build",