@swiftuijs/twill-shell 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saiya and twill contributors
+
+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

@@ -1,4 +1,73 @@
-# Temporary Holding Version
+# <img src="https://twill.evecalm.com/logo.png" alt="Twill hummingbird" align="right" width="40" height="40" /> Twill shell
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Swift-inspired subprocess tools for Twill and ordinary Node JS/TS scripts, Node-based in 0.3.0.
+
+## Install in your project
+
+Use Node 24 LTS for a new setup (supported range: `^20.19.0 || >=22.12.0`). Run from the directory containing your `package.json`; for a new project, run `npm init -y` first. Install the SDK as a production dependency:
+
+```sh
+npm install @swiftuijs/twill-shell@0.3.0
+```
+
+With pnpm, use `pnpm add @swiftuijs/twill-shell@0.3.0`. This package supplies the process API; `@swiftuijs/twill` supplies the optional Twill source runner. A global compiler does not make this SDK available to project imports. Keep Twill packages on the same version.
+
+## Run ordinary JavaScript
+
+The SDK uses Node spawn/streams with literal argv (`shell: false`), bounded capture and owned cancellation/timeout teardown. It has zero production dependencies; native JS/TS needs no Twill compiler or Rust toolchain.
+
+Changed in 0.3.0: the SDK no longer depends on `@swiftuijs/twill-shell-native`. Older npm 0.2.0 still requires the retired Rust addon; its versions remain downloadable for compatibility. The public command/policy/error API remains; abrupt worker/process-exit cleanup and unnamed Unix signal reporting change to Node's boundaries. See the [scripting guide](https://twill.evecalm.com/scripting#execution-and-version-boundary).
+
+Save this as `command.mjs`:
+
+```js
+import { Command, Output, Subprocess } from '@swiftuijs/twill-shell';
+
+const result = await Subprocess.run(
+  Command.path(process.execPath, ['-e', 'console.log("Hello from a child process")']),
+  { output: Output.text({ limit: 64 * 1024 }), timeoutMs: 5000 },
+);
+console.log(result.standardOutput.trim());
+```
+
+Run `node command.mjs`. Expected output is `Hello from a child process`. This works without Git, a Twill compiler or a global installation. Native TypeScript uses your existing TS runner/build.
+
+## Run Twill source
+
+Install the compiler as well:
+
+```sh
+npm install --save-dev @swiftuijs/twill@0.3.0
+# pnpm add -D @swiftuijs/twill@0.3.0
+```
+
+Copy the JavaScript example to `command.twill` and add `#!/usr/bin/env twill` as its first line. Use the local command:
+
+```sh
+npm exec -- twill command.twill
+# pnpm exec twill command.twill
+```
+
+On Linux/macOS, `chmod +x command.twill` enables `npm exec --call './command.twill'` or `pnpm exec ./command.twill`. To run `./command.twill` directly, install the compiler globally with `npm install --global @swiftuijs/twill@0.3.0` and keep its executable directory on PATH. Windows uses the explicit CLI. Arguments after the script path pass through unchanged. Application dependencies resolve from the script's location. Use compiler and SDK 0.3.0 or newer.
+
+For package scripts, Node type declarations, error handling and troubleshooting, follow the [complete shell scripting guide](https://twill.evecalm.com/scripting). [Getting started](https://twill.evecalm.com/getting-started) covers application modules and build integration.
+
+## Process contracts
+
+Use `Command.path(absolutePath, args)` for a trusted executable; `Command.name(name, args)` uses native PATH search. Arguments are immutable snapshots and remain literal strings, including spaces, quotes, newlines and shell metacharacters. Tool-specific options still matter: use `--` before user-supplied filenames when the executable supports it.
+
+Stdin defaults to EOF; stdout/stderr inherit without capture. `Input.inherit()` inherits stdin; a string or `Uint8Array` writes input with native backpressure. Byte input is copied at submission; cwd and environment are snapshotted then. `Output.text({limit})` and `Output.bytes({limit})` require positive byte limits; `Output.discard()` retains nothing. Output-limit failure rejects after teardown, never returns silent truncation. Capture limits bound retained stream bytes, not total process memory or the final UTF-8 string/buffer allocation.
+
+From 0.3.0, statuses follow Node reports, including its unnamed-signal limitations. Released 0.2.0 preserves numeric unnamed Unix signals. A successful result contains `processIdentifier`, `terminationStatus`, `standardOutput` and `standardError`. Nonzero/signal exits reject with `ProcessExitError`; `check: false` returns that status. Launch/I/O failures, abort, timeout and output overflow always reject. Use ordinary `try/catch` and exported error classes. Errors can carry bounded output and native causes; the SDK never logs them automatically.
+
+`cwd` and `Environment.inherit(updates)` / `.replace(values)` apply only to the child. Pass an `AbortSignal` or `timeoutMs` for cancellation. The default grace period is 250 ms before forced termination, followed by at most 1000 ms joining time. Settlement normally waits for child close and owned I/O. Failed teardown reports `unresolvedProcessIdentifier` and `cleanupErrors`, preserving the first failure. Ownership covers the direct child; descendants and arbitrary process trees are outside this contract. Windows uses its native process handle for termination, without POSIX graceful-signal guarantees.
+
+This first stage does not implement scoped streaming, pipelines, shell templates or shell-text execution. Node ESM is required (`^20.19.0 || >=22.12.0`). Twill source execution uses its existing loader; exported/native JS only needs this SDK. See the [scripting guide](https://twill.evecalm.com/scripting), [RFC 0034](https://github.com/swiftuijs/twill/blob/main/docs/rfcs/0034-shell-scripting-toolkit.md) and [official AI skill](https://twill.evecalm.com/ai). Twill's sibling UI project is [SwiftUI.js](https://swiftuijs.evecalm.com/).
+
+Cancel and await outstanding work before a worker shuts down. Set `process.exitCode` after awaited work; forced `Worker.terminate()` and `process.exit()` cannot perform an asynchronous join. Version 0.3.0 removes the old native cleanup barrier. OS creation and event-loop scheduling are not hard real-time deadlines.
+
+Bounded capture and lifecycle checks add overhead. The reviewed Linux/Node 24 report measured about 17% median overhead for native dual 1 MiB capture and 11% for full duplex, accepted for 0.3.0. See the [recorded costs](https://twill.evecalm.com/performance#node-shell-sdk); this is not a universal native-parity guarantee.
+
+## Development
+
+This package's implementation uses Twill and emits ordinary JavaScript. Build and check a checkout with the workspace tools; see [developing tooling in Twill](https://github.com/swiftuijs/twill/blob/main/docs/contributing/dogfooding.md) for bootstrap and contribution instructions.

package/dist/cwd.d.ts

@@ -0,0 +1,2 @@
+export declare function cwdSnapshot(cwd: string | undefined, platform?: NodeJS.Platform, parent?: string): string;
+//# sourceMappingURL=cwd.d.ts.map

package/dist/cwd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd.d.ts","mappings":"AACA,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,kBAAmB,EAC3B,MAAM,SAAgB,GACrB,MAAM","names":[],"ignoreList":[],"sources":["../src/cwd.twill"]}

package/dist/cwd.js

@@ -0,0 +1,9 @@
+import { isAbsolute, win32 } from "node:path";
+//#region src/cwd.twill
+function cwdSnapshot(cwd, platform = process.platform, parent = process.cwd()) {
+	return cwd === void 0 ? parent : platform === "win32" ? win32.resolve(parent, cwd) : isAbsolute(cwd) ? cwd : `${parent}/${cwd}`;
+}
+//#endregion
+export { cwdSnapshot };
+
+//# sourceMappingURL=cwd.js.map

package/dist/cwd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd.js","names":[],"sources":["../src/cwd.twill"],"mappings":";;AACA,SAAgB,YACd,KACA,WAAW,QAAQ,UACnB,SAAS,QAAQ,IAAG,GAAE;CAEtB,OAAO,QAAQ,KAAA,IACX,SACA,aAAa,UACX,MAAM,QAAQ,QAAQ,GAAG,IACzB,WAAW,GAAG,IACZ,MACA,GAAG,OAAM,GAAI;AACvB"}

package/dist/environment.d.ts

@@ -0,0 +1,5 @@
+import type { Environment } from './values.js';
+export declare function environmentSnapshot(policy: Environment | undefined, platform?: NodeJS.Platform, parent?: NodeJS.ProcessEnv): {
+    [key: string]: string | undefined;
+};
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAgB;AAiBjD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,kBAAmB,EAC3B,MAAM,oBAAc","names":[],"ignoreList":[],"sources":["../src/environment.twill"]}

package/dist/environment.js

@@ -0,0 +1,32 @@
+import { childEnvironment } from "./values.js";
+//#region src/environment.twill
+var windowsRequired = [
+	"HOMEDRIVE",
+	"HOMEPATH",
+	"LOGONSERVER",
+	"PATH",
+	"SYSTEMDRIVE",
+	"SYSTEMROOT",
+	"TEMP",
+	"USERDOMAIN",
+	"USERNAME",
+	"USERPROFILE",
+	"WINDIR"
+];
+function environmentSnapshot(policy, platform = process.platform, parent = process.env) {
+	const environment = { ...childEnvironment(policy, platform) ?? parent };
+	if (parent.NODE_V8_COVERAGE && !Object.hasOwn(environment, "NODE_V8_COVERAGE")) environment.NODE_V8_COVERAGE = parent.NODE_V8_COVERAGE;
+	if (platform === "win32") {
+		const selected = new Set(Object.keys(environment).map((key) => key.toUpperCase()));
+		const inherited = new Map(Object.entries(parent).map(([key, value]) => [key.toUpperCase(), value]));
+		for (const key of windowsRequired) {
+			const value = inherited.get(key);
+			if (!selected.has(key) && value !== void 0) environment[key] = value;
+		}
+	}
+	return environment;
+}
+//#endregion
+export { environmentSnapshot };
+
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","names":[],"sources":["../src/environment.twill"],"mappings":";;AAKA,IAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACD;AACD,SAAgB,oBACd,QACA,WAAW,QAAQ,UACnB,SAAS,QAAQ,KAAG;CAEpB,MAAM,cAAc,EAAE,GAAI,iBAAiB,QAAQ,QAAQ,KAAK,OAAO;CACvE,IAAI,OAAO,oBAAoB,CAAC,OAAO,OAAO,aAAa,kBAAkB,GAC3E,YAAY,mBAAmB,OAAO;CACxC,IAAI,aAAa,SAAS;EACxB,MAAM,WAAW,IAAI,IAAI,OAAO,KAAK,WAAW,CAAC,CAAC,KAAK,QAAQ,IAAI,YAAW,CAAE,CAAC;EACjF,MAAM,YAAY,IAAI,IACpB,OAAO,QAAQ,MAAM,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,IAAI,YAAW,GAAI,KAAK,CAAC,CAAC;EAE1E,KAAK,MAAM,OAAO,iBAAiB;GACjC,MAAM,QAAQ,UAAU,IAAI,GAAG;GAC/B,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,UAAU,KAAA,GAAW,YAAY,OAAO;EACpE;CACF;CACA,OAAO;AACT"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+import type { ExecutionResult, TerminationStatus } from './index.js';
+export declare class ProcessError extends Error {
+    readonly processIdentifier?: number;
+    readonly terminationStatus?: TerminationStatus;
+    readonly standardOutput?: string | Buffer;
+    readonly standardError?: string | Buffer;
+    readonly unresolvedProcessIdentifier?: number;
+    readonly cleanupErrors: readonly Error[];
+    constructor(message: string, processIdentifier?: number, options?: ErrorOptions);
+}
+export declare class ProcessLaunchError extends ProcessError {
+    constructor(cause: unknown);
+}
+export declare class ProcessIOError extends ProcessError {
+    readonly stream: 'stdin' | 'stdout' | 'stderr';
+    constructor(stream: 'stdin' | 'stdout' | 'stderr', processIdentifier: number | undefined, cause: unknown);
+}
+export declare class ProcessAbortError extends ProcessError {
+    constructor(processIdentifier: number | undefined, reason: unknown);
+}
+export declare class ProcessTimeoutError extends ProcessError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, processIdentifier: number | undefined);
+}
+export declare class OutputLimitError extends ProcessError {
+    readonly stream: 'stdout' | 'stderr';
+    readonly limit: number;
+    constructor(stream: 'stdout' | 'stderr', limit: number, processIdentifier: number | undefined);
+}
+export declare class ProcessTeardownError extends ProcessError {
+    constructor(processIdentifier: number, cause?: unknown);
+}
+export declare class ProcessExitError extends ProcessError {
+    readonly result: ExecutionResult;
+    constructor(result: ExecutionResult);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAe;AAEvE,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB;IAC9C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM;IACxC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM;IAC7C,QAAQ,CAAC,aAAa,EAAE,SAAS,KAAK,EAAE;gBAC5B,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;;AAMjF,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,KAAK,EAAE,OAAO;;AAI5B,qBAAa,cAAe,SAAQ,YAAY;IAE5C,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ;gBAArC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,EAC9C,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,KAAK,EAAE,OAAO;;AAKlB,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO;;AAIpE,qBAAa,mBAAoB,SAAQ,YAAY;IAEjD,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,GAAG,SAAS;;AAKzC,qBAAa,gBAAiB,SAAQ,YAAY;IAE9C,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM;gBADb,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,KAAK,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,GAAG,SAAS;;AAKzC,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,iBAAiB,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;;AAKxD,qBAAa,gBAAiB,SAAQ,YAAY;IACpC,QAAQ,CAAC,MAAM,EAAE,eAAe;gBAAvB,MAAM,EAAE,eAAe","names":[],"ignoreList":[],"sources":["../src/errors.twill"]}

package/dist/errors.js

@@ -0,0 +1,65 @@
+//#region src/errors.twill
+var ProcessError = class extends Error {
+	processIdentifier;
+	terminationStatus;
+	standardOutput;
+	standardError;
+	unresolvedProcessIdentifier;
+	cleanupErrors = [];
+	constructor(message, processIdentifier, options) {
+		super(message, options);
+		this.name = new.target.name;
+		this.processIdentifier = processIdentifier;
+	}
+};
+var ProcessLaunchError = class extends ProcessError {
+	constructor(cause) {
+		super("Subprocess could not start", void 0, { cause });
+	}
+};
+var ProcessIOError = class extends ProcessError {
+	stream;
+	constructor(stream, processIdentifier, cause) {
+		super(`Subprocess ${stream} failed`, processIdentifier, { cause });
+		this.stream = stream;
+	}
+};
+var ProcessAbortError = class extends ProcessError {
+	constructor(processIdentifier, reason) {
+		super("Subprocess aborted", processIdentifier, { cause: reason });
+	}
+};
+var ProcessTimeoutError = class extends ProcessError {
+	timeoutMs;
+	constructor(timeoutMs, processIdentifier) {
+		super("Subprocess timed out", processIdentifier);
+		this.timeoutMs = timeoutMs;
+	}
+};
+var OutputLimitError = class extends ProcessError {
+	stream;
+	limit;
+	constructor(stream, limit, processIdentifier) {
+		super(`Subprocess ${stream} exceeded its byte limit`, processIdentifier);
+		this.stream = stream;
+		this.limit = limit;
+	}
+};
+var ProcessTeardownError = class extends ProcessError {
+	constructor(processIdentifier, cause) {
+		super("Owned subprocess could not be terminated", processIdentifier, { cause });
+		Object.assign(this, { unresolvedProcessIdentifier: processIdentifier });
+	}
+};
+var ProcessExitError = class extends ProcessError {
+	result;
+	constructor(result) {
+		super("Subprocess exited unsuccessfully", result.processIdentifier);
+		this.result = result;
+		Object.assign(this, result);
+	}
+};
+//#endregion
+export { OutputLimitError, ProcessAbortError, ProcessError, ProcessExitError, ProcessIOError, ProcessLaunchError, ProcessTeardownError, ProcessTimeoutError };
+
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.twill"],"mappings":";AAEA,IAAa,eAAb,cAAkC,MAAK;CAC5B;CACA;CACA;CACA;CACA;CACA,gBAAkC,CAAA;CAC3C,YAAY,SAAiB,mBAA4B,SAAsB;EAC7E,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO,WAAW;EACvB,KAAK,oBAAoB;CAC3B;AACF;AACA,IAAa,qBAAb,cAAwC,aAAY;CAClD,YAAY,OAAc;EACxB,MAAM,8BAA8B,KAAA,GAAW,EAAE,MAAK,CAAE;CAC1D;AACF;AACA,IAAa,iBAAb,cAAoC,aAAY;CAEnC;CADX,YACW,QACT,mBACA,OAAc;EAEd,MAAM,cAAc,OAAM,UAAW,mBAAmB,EAAE,MAAK,CAAE;EAJxD,KAAA,SAAA;CAKX;AACF;AACA,IAAa,oBAAb,cAAuC,aAAY;CACjD,YAAY,mBAAuC,QAAe;EAChE,MAAM,sBAAsB,mBAAmB,EAAE,OAAO,OAAM,CAAE;CAClE;AACF;AACA,IAAa,sBAAb,cAAyC,aAAY;CAExC;CADX,YACW,WACT,mBAAqC;EAErC,MAAM,wBAAwB,iBAAiB;EAHtC,KAAA,YAAA;CAIX;AACF;AACA,IAAa,mBAAb,cAAsC,aAAY;CAErC;CACA;CAFX,YACW,QACA,OACT,mBAAqC;EAErC,MAAM,cAAc,OAAM,2BAA4B,iBAAiB;EAJ9D,KAAA,SAAA;EACA,KAAA,QAAA;CAIX;AACF;AACA,IAAa,uBAAb,cAA0C,aAAY;CACpD,YAAY,mBAA2B,OAAe;EACpD,MAAM,4CAA4C,mBAAmB,EAAE,MAAK,CAAE;EAC9E,OAAO,OAAO,MAAM,EAAE,6BAA6B,kBAAiB,CAAE;CACxE;AACF;AACA,IAAa,mBAAb,cAAsC,aAAY;CAC3B;CAArB,YAAqB,QAAuB;EAC1C,MAAM,oCAAoC,OAAO,iBAAiB;EAD/C,KAAA,SAAA;EAEnB,OAAO,OAAO,MAAM,MAAM;CAC5B;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { Command, type OutputPolicy, type OutputValue, type RunOptions, type InheritedOutput } from './values.js';
+export { Command, Environment, Input, Output } from './values.js';
+export type { OutputPolicy, OutputValue, RunOptions, ProcessInput, InputPolicy, InheritedOutput, DiscardedOutput, TextOutput, ByteOutput, } from './values.js';
+export { ProcessError, ProcessLaunchError, ProcessAbortError, ProcessTimeoutError, ProcessExitError, ProcessIOError, OutputLimitError, ProcessTeardownError, } from './errors.js';
+export type TerminationStatus = {
+    readonly kind: 'exited';
+    readonly code: number;
+} | {
+    readonly kind: 'signaled';
+    readonly signal: NodeJS.Signals | number;
+};
+export interface ExecutionResult<O extends OutputPolicy = OutputPolicy, E extends OutputPolicy = OutputPolicy> {
+    readonly processIdentifier: number;
+    readonly terminationStatus: TerminationStatus;
+    readonly standardOutput: OutputValue<O>;
+    readonly standardError: OutputValue<E>;
+}
+type ExactOptions<O> = O & Record<Exclude<keyof O, keyof RunOptions>, never>;
+type SelectedOutput<P> = Extract<P, OutputPolicy> | (undefined extends P ? InheritedOutput : never);
+declare function run<Options extends RunOptions = RunOptions<InheritedOutput, InheritedOutput>>(cmd: Command, options?: ExactOptions<Options>): Promise<ExecutionResult<SelectedOutput<Options['output']>, SelectedOutput<Options['error']>>>;
+export declare const Subprocess: Readonly<{
+    run: typeof run;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","mappings":"AAMA,OAAO,EACL,OAAO,EAEP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACrB,MAAM,aAAgB;AAWvB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAgB;AACpE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,eAAe,EACf,UAAU,EACV,UAAU,GACX,MAAM,aAAgB;AACvB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,aAAgB;AAEvB,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;CAAC,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM;CAAE;AAC3E,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,YAAY,GAAG,YAAY;IAErC,QAAQ,CAAC,iBAAiB,EAAE,MAAM;IAClC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB;IAC7C,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC;;AA4CxC,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,UAAU,CAAC,EAAE,KAAK,CAAC;AAC5E,KAAK,cAAc,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,SAAS,SAAS,CAAC,GAAG,eAAe,GAAG,KAAK,CAAC;AACnG,iBAAS,GAAG,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,eAAe,CAAC,EACpF,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,YAAY,CAAC,OAAO,CAAyC,GACrE,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAuOhG,eAAO,MAAM,UAAU;;EAAyB","names":[],"ignoreList":[],"sources":["../src/index.twill"]}

package/dist/index.js

@@ -0,0 +1,224 @@
+import { cwdSnapshot } from "./cwd.js";
+import { Command, Environment, Input, Output, settings } from "./values.js";
+import { environmentSnapshot } from "./environment.js";
+import { OutputLimitError, ProcessAbortError, ProcessError, ProcessExitError, ProcessIOError, ProcessLaunchError, ProcessTeardownError, ProcessTimeoutError } from "./errors.js";
+import childProcess from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { addAbortListener } from "node:events";
+//#region src/index.twill
+var Capture = class {
+	reader;
+	policy;
+	chunks = [];
+	size = 0;
+	constructor(reader, policy, channel, pid, fail, failed) {
+		this.reader = reader;
+		this.policy = policy;
+		this.onData = (chunk) => {
+			if (failed()) return;
+			if (this.size + chunk.length > policy.limit) {
+				fail(new OutputLimitError(channel, policy.limit, pid));
+				return;
+			}
+			this.size += chunk.length;
+			this.chunks.push(chunk);
+		};
+		this.onError = (cause) => fail(pid === void 0 ? new ProcessLaunchError(cause) : new ProcessIOError(channel, pid, cause));
+		reader.on("data", this.onData).on("error", this.onError);
+	}
+	onData;
+	onError;
+	value() {
+		const bytes = this.chunks.length === 1 ? this.chunks[0] : Buffer.concat(this.chunks, this.size);
+		return this.policy.kind === "text" ? bytes.toString("utf8") : bytes;
+	}
+	detach() {
+		this.reader.off("data", this.onData).off("error", this.onError);
+	}
+};
+var stdio = (policy) => policy.kind === "inherit" ? "inherit" : policy.kind === "discard" ? "ignore" : "pipe";
+var emptyOptions = Object.freeze({});
+function run(cmd, options = emptyOptions) {
+	return new Promise((resolve, reject) => {
+		const config = settings(cmd, options);
+		const { signal } = config;
+		const submitted = config.timeoutMs === void 0 ? void 0 : performance.now();
+		if (signal?.aborted) {
+			reject(new ProcessAbortError(void 0, signal.reason));
+			return;
+		}
+		let child;
+		const input = typeof config.input === "string" ? config.input : config.input instanceof Uint8Array ? Buffer.from(Buffer.from(config.input.buffer, config.input.byteOffset, config.input.byteLength)) : void 0;
+		try {
+			child = childProcess.spawn(cmd.executable, cmd.arguments, {
+				shell: false,
+				cwd: config.cwd === void 0 ? void 0 : cwdSnapshot(config.cwd),
+				env: config.environment === void 0 ? void 0 : environmentSnapshot(config.environment),
+				stdio: [
+					typeof config.input === "object" && !(config.input instanceof Uint8Array) ? config.input.kind === "inherit" ? "inherit" : "ignore" : "pipe",
+					stdio(config.output),
+					stdio(config.error)
+				]
+			});
+		} catch (cause) {
+			reject(new ProcessLaunchError(cause));
+			return;
+		}
+		let primary;
+		let closed = false, settled = false, inputClosed = child.stdin === null;
+		let status;
+		let timeout;
+		let grace;
+		let forced;
+		let stdout, stderr;
+		let abortListener;
+		const failed = () => primary !== void 0;
+		const clearTimers = () => {
+			clearTimeout(timeout);
+			clearTimeout(grace);
+			clearTimeout(forced);
+		};
+		const destroyIO = () => {
+			child.stdin?.destroy();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+		};
+		const cleanup = () => {
+			clearTimers();
+			abortListener?.[Symbol.dispose]();
+			child.off("error", onError).off("exit", onExit).off("close", onClose);
+			child.stdin?.off("error", onInputError).off("close", onInputClose);
+			stdout?.detach();
+			stderr?.detach();
+		};
+		const captured = (capture, stream) => {
+			try {
+				return capture?.value();
+			} catch (cause) {
+				const error = new ProcessIOError(stream, child.pid, cause);
+				if (primary) primary.cleanupErrors.push(error);
+				else primary = error;
+				return;
+			}
+		};
+		const finish = () => {
+			if (settled || !closed || !inputClosed) return;
+			settled = true;
+			cleanup();
+			const standardOutput = captured(stdout, "stdout"), standardError = captured(stderr, "stderr");
+			if (primary) {
+				Object.assign(primary, {
+					terminationStatus: status,
+					standardOutput,
+					standardError
+				});
+				reject(primary);
+			} else {
+				const result = Object.freeze({
+					processIdentifier: child.pid,
+					terminationStatus: status,
+					standardOutput,
+					standardError
+				});
+				if (config.check && (status.kind !== "exited" || status.code !== 0)) reject(new ProcessExitError(result));
+				else resolve(result);
+			}
+		};
+		const secondary = (error) => primary.cleanupErrors.push(error);
+		const kill = (signal) => {
+			const errors = primary.cleanupErrors.length;
+			try {
+				if (!child.kill(signal) && child.exitCode === null && child.signalCode === null && child.pid !== void 0 && primary.cleanupErrors.length === errors) secondary(new ProcessError("Subprocess termination signal failed", child.pid));
+			} catch (cause) {
+				secondary(new ProcessError("Subprocess termination signal failed", child.pid, { cause }));
+			}
+		};
+		const fail = (error) => {
+			if (settled) return;
+			if (primary) {
+				secondary(error);
+				return;
+			}
+			primary = error;
+			clearTimeout(timeout);
+			if (child.pid === void 0 || child.exitCode !== null || child.signalCode !== null) {
+				destroyIO();
+				return;
+			}
+			kill("SIGTERM");
+			grace = setTimeout(() => {
+				if (closed) return;
+				kill("SIGKILL");
+				destroyIO();
+				forced = setTimeout(() => {
+					if (closed) return;
+					const alive = child.exitCode === null && child.signalCode === null;
+					secondary(alive ? new ProcessTeardownError(child.pid) : new ProcessError("Subprocess I/O did not close", child.pid));
+					Object.assign(primary, {
+						unresolvedProcessIdentifier: alive ? child.pid : void 0,
+						standardOutput: captured(stdout, "stdout"),
+						standardError: captured(stderr, "stderr")
+					});
+					settled = true;
+					cleanup();
+					child.unref();
+					reject(primary);
+				}, config.killTimeoutMs);
+				forced.unref();
+			}, config.gracePeriodMs);
+			grace.unref();
+		};
+		const onAbort = () => {
+			if (!closed) fail(new ProcessAbortError(child.pid, signal.reason));
+		};
+		const onError = (cause) => fail(child.pid === void 0 ? new ProcessLaunchError(cause) : new ProcessError("Subprocess process control failed", child.pid, { cause }));
+		const onExit = () => {
+			if (primary) destroyIO();
+		};
+		const onClose = (code, signal) => {
+			closed = true;
+			clearTimers();
+			if (child.pid !== void 0) status = Object.freeze(signal !== null ? {
+				kind: "signaled",
+				signal
+			} : {
+				kind: "exited",
+				code
+			});
+			finish();
+		};
+		const onInputError = (cause) => fail(child.pid === void 0 ? new ProcessLaunchError(cause) : new ProcessIOError("stdin", child.pid, cause));
+		const onInputClose = () => {
+			inputClosed = true;
+			finish();
+		};
+		child.on("error", onError).once("exit", onExit).once("close", onClose);
+		if (child.stdout) stdout = new Capture(child.stdout, config.output, "stdout", child.pid, fail, failed);
+		if (child.stderr) stderr = new Capture(child.stderr, config.error, "stderr", child.pid, fail, failed);
+		if (child.stdin) {
+			child.stdin.on("error", onInputError).once("close", onInputClose);
+			try {
+				child.stdin.end(input);
+			} catch (cause) {
+				fail(new ProcessIOError("stdin", child.pid, cause));
+			}
+		}
+		if (signal) {
+			if (signal.aborted) onAbort();
+			else try {
+				abortListener = addAbortListener(signal, onAbort);
+			} catch (cause) {
+				fail(new ProcessError("Subprocess cancellation setup failed", child.pid, { cause }));
+			}
+		}
+		if (config.timeoutMs !== void 0 && !primary) {
+			timeout = setTimeout(() => fail(new ProcessTimeoutError(config.timeoutMs, child.pid)), Math.max(0, config.timeoutMs - (performance.now() - submitted)));
+			timeout.unref();
+		}
+	});
+}
+var Subprocess = Object.freeze({ run });
+//#endregion
+export { Command, Environment, Input, Output, OutputLimitError, ProcessAbortError, ProcessError, ProcessExitError, ProcessIOError, ProcessLaunchError, ProcessTeardownError, ProcessTimeoutError, Subprocess };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/values.d.ts

@@ -0,0 +1,90 @@
+declare const commandBrand: unique symbol;
+declare const environmentBrand: unique symbol;
+declare const outputBrand: unique symbol;
+declare const inputBrand: unique symbol;
+export interface Command {
+    readonly [commandBrand]: true;
+    readonly executable: string;
+    readonly arguments: readonly string[];
+}
+export declare const Command: Readonly<{
+    name(executable: string, args?: readonly string[]): Command;
+    path(executable: string, args?: readonly string[]): Command;
+}>;
+export interface Environment {
+    readonly [environmentBrand]: true;
+    readonly kind: 'inherit' | 'replace';
+    readonly values: Readonly<Record<string, string | undefined>>;
+}
+export declare const Environment: Readonly<{
+    inherit(updates?: Record<string, string | undefined>): Environment;
+    replace(values: Record<string, string | undefined>): Environment;
+}>;
+interface OutputBrand {
+    readonly [outputBrand]: true;
+}
+export interface InheritedOutput extends OutputBrand {
+    readonly kind: 'inherit';
+}
+export interface DiscardedOutput extends OutputBrand {
+    readonly kind: 'discard';
+}
+export interface TextOutput extends OutputBrand {
+    readonly kind: 'text';
+    readonly limit: number;
+}
+export interface ByteOutput extends OutputBrand {
+    readonly kind: 'bytes';
+    readonly limit: number;
+}
+export type OutputPolicy = InheritedOutput | DiscardedOutput | TextOutput | ByteOutput;
+export type OutputValue<P extends OutputPolicy> = P extends TextOutput ? string : P extends ByteOutput ? Buffer : undefined;
+export declare const Output: Readonly<{
+    inherit(): InheritedOutput;
+    discard(): DiscardedOutput;
+    text(options: {
+        limit: number;
+    }): TextOutput;
+    bytes(options: {
+        limit: number;
+    }): ByteOutput;
+}>;
+export interface InputPolicy {
+    readonly [inputBrand]: true;
+    readonly kind: 'none' | 'inherit';
+}
+export declare const Input: Readonly<{
+    none(): InputPolicy;
+    inherit(): InputPolicy;
+}>;
+export type ProcessInput = string | Uint8Array | InputPolicy;
+export interface RunOptions<O extends OutputPolicy = OutputPolicy, E extends OutputPolicy = OutputPolicy> {
+    readonly cwd?: string;
+    readonly environment?: Environment;
+    readonly input?: ProcessInput;
+    readonly output?: O;
+    readonly error?: E;
+    readonly check?: boolean;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    /** Time allowed after SIGTERM, before SIGKILL. Defaults to 250 ms. */
+    readonly gracePeriodMs?: number;
+    /** Maximum join time after forced termination. Defaults to 1000 ms. */
+    readonly killTimeoutMs?: number;
+}
+export declare function settings(cmd: Command, options: RunOptions): {
+    cwd: string | undefined;
+    environment: Environment | undefined;
+    input: ProcessInput;
+    output: OutputPolicy;
+    error: OutputPolicy;
+    check: boolean;
+    signal: AbortSignal | undefined;
+    timeoutMs: number | undefined;
+    gracePeriodMs: number;
+    killTimeoutMs: number;
+};
+/** Internal helper; parameter permits testing Windows key behavior on other hosts. */
+export declare function childEnvironment(policy: Environment | undefined, platform?: NodeJS.Platform): NodeJS.ProcessEnv | undefined;
+export {};
+//# sourceMappingURL=values.d.ts.map

package/dist/values.d.ts.map

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

package/dist/values.js

@@ -0,0 +1,176 @@
+import { isAbsolute } from "node:path";
+import { constants } from "node:buffer";
+//#region src/values.twill
+var commandBrand = Symbol.for("@swiftuijs/twill-shell/command/v1");
+var environmentBrand = Symbol.for("@swiftuijs/twill-shell/environment/v1");
+var outputBrand = Symbol.for("@swiftuijs/twill-shell/output/v1");
+var inputBrand = Symbol.for("@swiftuijs/twill-shell/input/v1");
+function string(value, label, empty = false) {
+	if (typeof value !== "string" || !empty && value.length === 0 || value.includes("\0")) throw new TypeError(`${label} must be a ${empty ? "" : "nonempty "}string without NUL`);
+}
+function command(executable, args) {
+	if (!Array.isArray(args)) throw new TypeError("arguments must be an array of strings");
+	const snapshot = Array.from(args);
+	for (const arg of snapshot) string(arg, "argument", true);
+	return Object.freeze({
+		[commandBrand]: true,
+		executable,
+		arguments: Object.freeze(snapshot)
+	});
+}
+var Command = Object.freeze({
+	name(executable, args = []) {
+		string(executable, "executable");
+		if (/[\\/:]/.test(executable)) throw new TypeError("Command.name requires a name without path separators");
+		return command(executable, args);
+	},
+	path(executable, args = []) {
+		string(executable, "executable");
+		if (!isAbsolute(executable)) throw new TypeError("Command.path requires an absolute path");
+		return command(executable, args);
+	}
+});
+function environment(kind, values) {
+	if (!values || typeof values !== "object" || Array.isArray(values)) throw new TypeError("environment values must be an object");
+	const snapshot = Object.create(null);
+	for (const [key, value] of Object.entries(values)) {
+		string(key, "environment key");
+		if (key.includes("=")) throw new TypeError("environment key cannot contain =");
+		if (value !== void 0) string(value, "environment value", true);
+		snapshot[key] = value;
+	}
+	return Object.freeze({
+		[environmentBrand]: true,
+		kind,
+		values: Object.freeze(snapshot)
+	});
+}
+var Environment = Object.freeze({
+	inherit(updates = {}) {
+		return environment("inherit", updates);
+	},
+	replace(values) {
+		return environment("replace", values);
+	}
+});
+var inheritedOutput = Object.freeze({
+	[outputBrand]: true,
+	kind: "inherit"
+});
+var discardedOutput = Object.freeze({
+	[outputBrand]: true,
+	kind: "discard"
+});
+function captureLimit(limit) {
+	if (!Number.isSafeInteger(limit) || limit <= 0 || limit > constants.MAX_LENGTH) throw new TypeError("output limit must be a positive safe byte count within Buffer.MAX_LENGTH");
+}
+function capture(kind, options) {
+	const limit = options?.limit;
+	captureLimit(limit);
+	return Object.freeze({
+		[outputBrand]: true,
+		kind,
+		limit
+	});
+}
+var Output = Object.freeze({
+	inherit() {
+		return inheritedOutput;
+	},
+	discard() {
+		return discardedOutput;
+	},
+	text(options) {
+		return capture("text", options);
+	},
+	bytes(options) {
+		return capture("bytes", options);
+	}
+});
+var noInput = Object.freeze({
+	[inputBrand]: true,
+	kind: "none"
+});
+var inheritedInput = Object.freeze({
+	[inputBrand]: true,
+	kind: "inherit"
+});
+var Input = Object.freeze({
+	none() {
+		return noInput;
+	},
+	inherit() {
+		return inheritedInput;
+	}
+});
+var optionKeys = /* @__PURE__ */ new Set([
+	"cwd",
+	"environment",
+	"input",
+	"output",
+	"error",
+	"check",
+	"signal",
+	"timeoutMs",
+	"gracePeriodMs",
+	"killTimeoutMs"
+]);
+function duration(value, label, minimum) {
+	if (!Number.isInteger(value) || value < minimum || value > 2147483647) throw new TypeError(`${label} must be an integer between ${minimum} and 2147483647`);
+}
+function settings(cmd, options) {
+	if (!cmd || cmd[commandBrand] !== true) throw new TypeError("Use Command.name or Command.path");
+	if (!options || typeof options !== "object" || Array.isArray(options)) throw new TypeError("run options must be an object");
+	for (const key of Object.keys(options)) if (!optionKeys.has(key)) throw new TypeError(`Unknown run option: ${key}`);
+	const { cwd, environment: env, input = noInput, output = inheritedOutput, error = inheritedOutput, check = true, signal, timeoutMs, gracePeriodMs = 250, killTimeoutMs = 1e3 } = options;
+	if (cwd !== void 0) string(cwd, "cwd");
+	if (env !== void 0 && (!env || env[environmentBrand] !== true)) throw new TypeError("Use Environment.inherit or Environment.replace");
+	if (!output || output[outputBrand] !== true || !error || error[outputBrand] !== true) throw new TypeError("Use Output policies");
+	for (const policy of [output, error]) if (policy.kind === "text" || policy.kind === "bytes") captureLimit(policy.limit);
+	else if (policy.kind !== "inherit" && policy.kind !== "discard") throw new TypeError("Unknown output policy");
+	if (typeof input !== "string" && !(input instanceof Uint8Array) && (!input || input[inputBrand] !== true)) throw new TypeError("input must be a string, Uint8Array or Input policy");
+	if (typeof check !== "boolean") throw new TypeError("check must be a boolean");
+	if (signal !== void 0 && !(signal instanceof AbortSignal)) throw new TypeError("signal must be an AbortSignal");
+	if (timeoutMs !== void 0) duration(timeoutMs, "timeoutMs", 1);
+	duration(gracePeriodMs, "gracePeriodMs", 0);
+	duration(killTimeoutMs, "killTimeoutMs", 1);
+	return {
+		cwd,
+		environment: env,
+		input,
+		output,
+		error,
+		check,
+		signal,
+		timeoutMs,
+		gracePeriodMs,
+		killTimeoutMs
+	};
+}
+/** Internal helper; parameter permits testing Windows key behavior on other hosts. */
+function childEnvironment(policy, platform = process.platform) {
+	if (policy === void 0) return void 0;
+	const env = Object.assign(Object.create(null), policy.kind === "inherit" ? process.env : void 0);
+	if (platform === "win32") {
+		const keys = /* @__PURE__ */ new Map();
+		for (const key of Object.keys(env)) {
+			const normalized = key.toUpperCase();
+			const previous = keys.get(normalized);
+			if (previous !== void 0) delete env[previous];
+			keys.set(normalized, key);
+		}
+		for (const [key, value] of Object.entries(policy.values)) {
+			const normalized = key.toUpperCase();
+			const previous = keys.get(normalized);
+			if (previous !== void 0) delete env[previous];
+			keys.set(normalized, key);
+			if (value !== void 0) env[key] = value;
+		}
+	} else for (const [key, value] of Object.entries(policy.values)) if (value === void 0) delete env[key];
+	else env[key] = value;
+	return env;
+}
+//#endregion
+export { Command, Environment, Input, Output, childEnvironment, settings };
+
+//# sourceMappingURL=values.js.map

package/dist/values.js.map

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

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@swiftuijs/twill-shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Swift-inspired subprocess toolkit for Twill and native Node scripts: explicit arguments, bounded output and owned teardown.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swiftuijs/twill.git",
+    "directory": "packages/shell"
+  },
+  "homepage": "https://twill.evecalm.com/",
+  "bugs": {
+    "url": "https://github.com/swiftuijs/twill/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "^26.6.4",
+    "vitest": "^5.0.3",
+    "@vitest/coverage-v8": "^5.0.3",
+    "prettier": "^3.9.9",
+    "vite": "^8.3.2",
+    "@swiftuijs/twill": "0.3.0",
+    "@swiftuijs/twill-export": "0.3.0",
+    "@swiftuijs/twill-formatter": "0.3.0"
+  },
+  "author": {
+    "name": "forth.ink",
+    "url": "https://forth.ink"
+  },
+  "keywords": [
+    "twill",
+    "shell",
+    "subprocess",
+    "scripting",
+    "swift",
+    "typescript",
+    "node"
+  ],
+  "peerDependencies": {
+    "@types/node": "^20.0.0 || ^22.0.0 || ^24.0.0 || ^26.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "vite build && twill declarations -p tsconfig.build.json -o dist && node scripts/compact-maps.mjs",
+    "typecheck": "twill check -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:package": "node tests/consumer.mjs",
+    "benchmark": "node benchmarks/run.mjs",
+    "benchmark:complete": "node benchmarks/complete.mjs"
+  }
 }