@mypolis.eu/command 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyPolis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @mypolis.eu/command
+
+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';
+
+// 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.
+const branch = await $`git branch --show-current`.text();
+const {stdout, stderr} = await $`git status --short`.output();
+
+// Each interpolation is a whole argument; arrays expand into arguments.
+const paths = ['notes with spaces.md', 'draft.md'];
+await $`git diff -- ${paths}`;
+```
+
+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.
+
+## Arguments, not Bash
+
+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:
+
+```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
+
+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;
+
+## Failures and limits
+
+```js
+try {
+  await $`git status`.timeout(5_000).output();
+} catch (error) {
+  if (!(error instanceof CommandError)) throw error;
+  console.error(error.reason, error.exitCode, error.signal);
+  console.error(error.stdout, error.stderr);
+}
+```
+
+## License
+
+MIT © MyPolis

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+type Argument = string | number;
+type Values = (Argument | readonly Argument[])[];
+type Output = {
+    stdout: string;
+    stderr: string;
+};
+type FailureReason = "spawn" | "exit" | "signal" | "timeout" | "overflow";
+export declare class CommandError extends Error {
+    readonly reason: FailureReason;
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly code: string | undefined;
+    readonly stdout: string | undefined;
+    readonly stderr: string | undefined;
+    constructor(message: string, details: {
+        reason: FailureReason;
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+        code?: string;
+        output?: Output;
+    });
+}
+type Command = PromiseLike<undefined> & {
+    timeout(ms: number): 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;
+export {};

package/dist/index.js

@@ -0,0 +1,196 @@
+import { spawn } from "node:child_process";
+const CAPTURE_LIMIT = 1024 * 1024; // Bytes per stream; overflow terminates rather than silently truncating.
+const TERMINATION_GRACE_MS = 500;
+export class CommandError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.name = "CommandError";
+        this.reason = details.reason;
+        this.exitCode = details.exitCode;
+        this.signal = details.signal;
+        this.code = details.code;
+        this.stdout = details.output?.stdout;
+        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;
+    };
+    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 command;
+}
+async function execute(options, strings, values) {
+    const args = [];
+    for (const [index, text] of strings.entries()) {
+        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 === "")) {
+            throw new Error("Interpolations must be separated from other arguments by whitespace.");
+        }
+        args.push(...text.split(/\s+/).filter(Boolean));
+        if (index < values.length) {
+            const value = values[index];
+            const items = Array.isArray(value) ? value : [value];
+            for (const item of items) {
+                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));
+            }
+        }
+    }
+    const command = args.shift();
+    if (!command)
+        throw new Error("A command is required.");
+    let child;
+    try {
+        child = spawn(command, args, {
+            stdio: options.capture ? ["inherit", "pipe", "pipe"] : "inherit",
+            shell: false
+        });
+    }
+    catch (error) {
+        const { code } = error;
+        throw new CommandError(`Command could not be spawned (${code ?? "process error"}).`, {
+            reason: "spawn",
+            exitCode: null,
+            signal: null,
+            code,
+            output: options.capture ? { stdout: "", stderr: "" } : undefined
+        });
+    }
+    return new Promise((resolve, reject) => {
+        let interrupted;
+        let failure;
+        let stopped;
+        let overflowStream;
+        let timeout;
+        let escalation;
+        const chunks = { stdout: [], stderr: [] };
+        const bytes = { stdout: 0, stderr: 0 };
+        const terminate = (reason) => {
+            if (stopped)
+                return;
+            stopped = reason;
+            child.kill("SIGTERM");
+            escalation = setTimeout(() => child.kill("SIGKILL"), TERMINATION_GRACE_MS);
+        };
+        const collect = (stream, chunk) => {
+            const remaining = CAPTURE_LIMIT - bytes[stream];
+            if (remaining > 0) {
+                const retained = Buffer.from(chunk.subarray(0, remaining));
+                chunks[stream].push(retained);
+                bytes[stream] += 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 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) => {
+            clearTimeout(timeout);
+            clearTimeout(escalation);
+            process.removeListener("SIGINT", onInterrupt);
+            process.removeListener("SIGTERM", onTerminate);
+            child.removeListener("error", onError);
+            child.stdout?.removeListener("data", onStdout);
+            child.stderr?.removeListener("data", onStderr);
+            let output;
+            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;
+                message = `Command timed out after ${options.timeoutMs} ms.`;
+            }
+            else if (stopped === "overflow") {
+                reason = stopped;
+                message = `Command ${overflowStream} exceeded the ${CAPTURE_LIMIT}-byte capture limit.`;
+            }
+            else if (failure) {
+                reason = "spawn";
+                message = `Command failed (${failure.code ?? "process error"}).`;
+            }
+            else if (interrupted || signal) {
+                reason = "signal";
+                message = `Command failed (${interrupted ?? signal}).`;
+            }
+            else if (exitCode !== 0) {
+                reason = "exit";
+                message = `Command failed (exit ${exitCode}).`;
+            }
+            else {
+                resolve(output ?? { stdout: "", stderr: "" });
+                return;
+            }
+            reject(new CommandError(message, { reason, exitCode, signal: interrupted ?? signal, code: failure?.code, output }));
+        });
+    });
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@mypolis.eu/command",
+	"version": "0.1.0",
+	"description": "Lazy, terminal-first, shell-free commands for Node.js.",
+	"type": "module",
+	"license": "MIT",
+	"author": "MyPolis",
+	"engines": {
+		"node": ">=24"
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"files": ["dist/index.js", "dist/index.d.ts", "README.md", "LICENSE"],
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"check": "tsc -p tsconfig.json --noEmit"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"devDependencies": {
+		"@types/node": "24.13.2",
+		"typescript": "5.9.3"
+	}
+}