@swiftuijs/twill-shell 0.0.0-stage → 0.2.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,38 @@
-# 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, available in 0.2.0.
+
+```sh
+npm install @swiftuijs/twill-shell
+# For .twill source scripts:
+npm install --save-dev @swiftuijs/twill
+```
+
+Commands execute through one Rust process engine with literal argv, without shell interpretation or command compilation (`shell: false`). The prebuilt implementation dependency installs automatically; users need no Rust toolchain and do not choose a backend. Native JS/TS needs no Twill compiler. One async reactor per Node environment coordinates already-started children and pipes independently of libuv's worker pool.
+
+Supported prebuilds: Linux glibc x64/ARM64 (glibc 2.28+), Linux musl x64/ARM64 (musl 1.2.5+), macOS x64/ARM64 and Windows x64/ARM64. Missing/incompatible binaries and unsupported platforms reject before launch, without fallback, install-time builds or downloads. See [performance](https://twill.evecalm.com/performance#rust-shell-backend) for measured warm gains and cold/polling limits.
+
+```twill
+#!/usr/bin/env twill
+import { Command, Output, Subprocess } from '@swiftuijs/twill-shell';
+
+const result = await Subprocess.run(Command.name('git', ['status', '--short']), {
+  output: Output.text({ limit: 64 * 1024 }),
+  timeoutMs: 5000,
+});
+console.log(result.standardOutput);
+```
+
+The compiler runner supplies the `twill` binary. Save this as `status.twill`, then use `twill status.twill` or `twill run status.twill`. On Linux/macOS, `chmod +x status.twill` enables `./status.twill` when `twill` is on PATH; `pnpm exec ./status.twill` uses a project-local binary. Windows uses the explicit CLI. Arguments after the script path pass through unchanged. Application dependencies resolve from the script's location. Use the compiler and SDK from 0.2.0 or newer.
+
+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.
+
+Named Unix signals use Node names; unnamed signals retain their numeric OS value. 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/).
+
+Worker termination cancels that environment's children. Explicit `process.exit()` and environment teardown use a native cleanup barrier bounded to 1.1 seconds; JS callbacks do not run during exit. OS creation/uninterruptible kernel waits are not hard real-time guarantees, and SIGKILL/native faults cannot run cleanup handlers.

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","sourceRoot":"","sources":["../src/cwd.ts"],"names":[],"mappings":"AACA,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,kBAAmB,EAC3B,MAAM,SAAgB,GACrB,MAAM,CAQR"}

package/dist/cwd.js

@@ -0,0 +1,11 @@
+import { isAbsolute, win32 } from 'node:path';
+export function cwdSnapshot(cwd, platform = process.platform, parent = process.cwd()) {
+    return cwd === undefined
+        ? parent
+        : platform === 'win32'
+            ? win32.resolve(parent, cwd)
+            : isAbsolute(cwd)
+                ? cwd
+                : `${parent}/${cwd}`;
+}
+//# sourceMappingURL=cwd.js.map

package/dist/cwd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cwd.js","sourceRoot":"","sources":["../src/cwd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAC9C,MAAM,UAAU,WAAW,CACzB,GAAuB,EACvB,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAC3B,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;IAEtB,OAAO,GAAG,KAAK,SAAS;QACtB,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,QAAQ,KAAK,OAAO;YACpB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;YAC5B,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;gBACf,CAAC,CAAC,GAAG;gBACL,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC;AAC7B,CAAC"}

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","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB/C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,kBAAmB,EAC3B,MAAM,oBAAc;;EAgBrB"}

package/dist/environment.js

@@ -0,0 +1,32 @@
+import { childEnvironment } from './values.js';
+// Match Node/libuv's mandatory Windows spawn environment additions (including
+// replacement/removal policies). Explicit empty values still override defaults.
+const windowsRequired = [
+    'HOMEDRIVE',
+    'HOMEPATH',
+    'LOGONSERVER',
+    'PATH',
+    'SYSTEMDRIVE',
+    'SYSTEMROOT',
+    'TEMP',
+    'USERDOMAIN',
+    'USERNAME',
+    'USERPROFILE',
+    'WINDIR',
+];
+export 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 !== undefined)
+                environment[key] = value;
+        }
+    }
+    return environment;
+}
+//# sourceMappingURL=environment.js.map

package/dist/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG/C,8EAA8E;AAC9E,gFAAgF;AAChF,MAAM,eAAe,GAAG;IACtB,WAAW;IACX,UAAU;IACV,aAAa;IACb,MAAM;IACN,aAAa;IACb,YAAY;IACZ,MAAM;IACN,YAAY;IACZ,UAAU;IACV,aAAa;IACb,QAAQ;CACT,CAAC;AACF,MAAM,UAAU,mBAAmB,CACjC,MAA+B,EAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAC3B,MAAM,GAAG,OAAO,CAAC,GAAG;IAEpB,MAAM,WAAW,GAAG,EAAE,GAAG,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,EAAE,CAAC;IAC1E,IAAI,MAAM,CAAC,gBAAgB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,kBAAkB,CAAC;QAC5E,WAAW,CAAC,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACzD,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACnF,MAAM,SAAS,GAAG,IAAI,GAAG,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,KAAK,CAAC,CAAC,CACzE,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,SAAS;gBAAE,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC"}

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","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAErE,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAC9C,QAAQ,CAAC,aAAa,EAAE,SAAS,KAAK,EAAE,CAAM;gBAClC,OAAO,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKhF;AACD,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,KAAK,EAAE,OAAO;CAG3B;AACD,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;CAIjB;AACD,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,iBAAiB,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO;CAGnE;AACD,qBAAa,mBAAoB,SAAQ,YAAY;IAEjD,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM,EAC1B,iBAAiB,EAAE,MAAM,GAAG,SAAS;CAIxC;AACD,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;CAIxC;AACD,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,iBAAiB,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAIvD;AACD,qBAAa,gBAAiB,SAAQ,YAAY;IACpC,QAAQ,CAAC,MAAM,EAAE,eAAe;gBAAvB,MAAM,EAAE,eAAe;CAI7C"}

package/dist/errors.js

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

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,iBAAiB,CAAU;IAC3B,iBAAiB,CAAqB;IACtC,cAAc,CAAmB;IACjC,aAAa,CAAmB;IAChC,2BAA2B,CAAU;IACrC,aAAa,GAAqB,EAAE,CAAC;IAC9C,YAAY,OAAe,EAAE,iBAA0B,EAAE,OAAsB;QAC7E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC7C,CAAC;CACF;AACD,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAClD,YAAY,KAAc;QACxB,KAAK,CAAC,4BAA4B,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF;AACD,MAAM,OAAO,cAAe,SAAQ,YAAY;IAEnC;IADX,YACW,MAAqC,EAC9C,iBAAqC,EACrC,KAAc;QAEd,KAAK,CAAC,cAAc,MAAM,SAAS,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAJ1D,WAAM,GAAN,MAAM,CAA+B;IAKhD,CAAC;CACF;AACD,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjD,YAAY,iBAAqC,EAAE,MAAe;QAChE,KAAK,CAAC,oBAAoB,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IACpE,CAAC;CACF;AACD,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IAExC;IADX,YACW,SAAiB,EAC1B,iBAAqC;QAErC,KAAK,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;QAHxC,cAAS,GAAT,SAAS,CAAQ;IAI5B,CAAC;CACF;AACD,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAErC;IACA;IAFX,YACW,MAA2B,EAC3B,KAAa,EACtB,iBAAqC;QAErC,KAAK,CAAC,cAAc,MAAM,0BAA0B,EAAE,iBAAiB,CAAC,CAAC;QAJhE,WAAM,GAAN,MAAM,CAAqB;QAC3B,UAAK,GAAL,KAAK,CAAQ;IAIxB,CAAC;CACF;AACD,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,iBAAyB,EAAE,KAAe;QACpD,KAAK,CAAC,0CAA0C,EAAE,iBAAiB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QAChF,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,2BAA2B,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAC1E,CAAC;CACF;AACD,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAC3B;IAArB,YAAqB,MAAuB;QAC1C,KAAK,CAAC,kCAAkC,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;QADjD,WAAM,GAAN,MAAM,CAAiB;QAE1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type Command, type RunOptions, type OutputPolicy, type OutputValue, 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>>(command: 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","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,eAAe,EACf,UAAU,EACV,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAAA;CAAE,CAAC;AAC5E,MAAM,WAAW,eAAe,CAC9B,CAAC,SAAS,YAAY,GAAG,YAAY,EACrC,CAAC,SAAS,YAAY,GAAG,YAAY;IAErC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACxC;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7E,KAAK,cAAc,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,SAAS,SAAS,CAAC,GAAG,eAAe,GAAG,KAAK,CAAC,CAAC;AASpG,iBAAS,GAAG,CAAC,OAAO,SAAS,UAAU,GAAG,UAAU,CAAC,eAAe,EAAE,eAAe,CAAC,EACpF,OAAO,EAAE,OAAO,EAChB,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,CAyJ/F;AACD,eAAO,MAAM,UAAU;;EAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,168 @@
+import { addAbortListener } from 'node:events';
+import { constants } from 'node:os';
+import { cwdSnapshot } from './cwd.js';
+import { environmentSnapshot } from './environment.js';
+import { settings, } from './values.js';
+import { ProcessError, ProcessLaunchError, ProcessAbortError, ProcessTimeoutError, ProcessExitError, ProcessIOError, OutputLimitError, ProcessTeardownError, } from './errors.js';
+import { loadBackend } from '@swiftuijs/twill-shell-native';
+export { Command, Environment, Input, Output } from './values.js';
+export { ProcessError, ProcessLaunchError, ProcessAbortError, ProcessTimeoutError, ProcessExitError, ProcessIOError, OutputLimitError, ProcessTeardownError, } from './errors.js';
+const emptyOptions = Object.freeze({});
+function cause(failure) {
+    return Object.assign(new Error(failure.message), {
+        code: failure.code,
+        errno: failure.osCode,
+    });
+}
+function run(command, options = emptyOptions) {
+    return new Promise((resolve, reject) => {
+        const config = settings(command, options);
+        const { signal } = config;
+        if (signal?.aborted) {
+            reject(new ProcessAbortError(undefined, signal.reason));
+            return;
+        }
+        const input = typeof config.input === 'string'
+            ? Buffer.from(config.input)
+            : config.input instanceof Uint8Array
+                ? Buffer.from(config.input.buffer, config.input.byteOffset, config.input.byteLength)
+                : undefined;
+        const inputPolicy = typeof config.input === 'object' && !(config.input instanceof Uint8Array)
+            ? config.input
+            : undefined;
+        let backend, job;
+        try {
+            backend = loadBackend();
+            job = backend.start({
+                executable: command.executable,
+                arguments: command.arguments,
+                cwd: cwdSnapshot(config.cwd),
+                environment: environmentSnapshot(config.environment),
+                input,
+                inheritInput: inputPolicy?.kind === 'inherit',
+                outputLimit: 'limit' in config.output ? config.output.limit : undefined,
+                errorLimit: 'limit' in config.error ? config.error.limit : undefined,
+                discardOutput: config.output.kind === 'discard',
+                discardError: config.error.kind === 'discard',
+                timeoutMs: config.timeoutMs,
+                gracePeriodMs: config.gracePeriodMs,
+                killTimeoutMs: config.killTimeoutMs,
+            });
+        }
+        catch (error) {
+            reject(new ProcessLaunchError(error));
+            return;
+        }
+        let abortReason, setupFailure;
+        let listener;
+        const abort = () => {
+            abortReason = signal.reason;
+            backend.cancel(job.id, false);
+        };
+        if (signal) {
+            if (signal.aborted)
+                abort();
+            else {
+                try {
+                    listener = addAbortListener(signal, abort);
+                }
+                catch (error) {
+                    setupFailure = error;
+                    backend.cancel(job.id, true);
+                }
+            }
+        }
+        const failure = (value, pid) => {
+            switch (value.kind) {
+                case 'launch':
+                    return new ProcessLaunchError(cause(value));
+                case 'abort':
+                    return new ProcessAbortError(pid, abortReason);
+                case 'timeout':
+                    return new ProcessTimeoutError(config.timeoutMs, pid);
+                case 'io':
+                    return new ProcessIOError(value.stream, pid, cause(value));
+                case 'limit': {
+                    const policy = value.stream === 'stdout' ? config.output : config.error;
+                    return new OutputLimitError(value.stream, policy.limit, pid);
+                }
+                case 'teardown':
+                    return new ProcessTeardownError(pid, cause(value));
+                case 'setup':
+                    return new ProcessError('Subprocess cancellation setup failed', pid, {
+                        cause: setupFailure,
+                    });
+                default:
+                    return new ProcessError(value.message, pid, { cause: cause(value) });
+            }
+        };
+        const complete = (outcome) => {
+            listener?.[Symbol.dispose]();
+            const pid = outcome.processIdentifier;
+            const terminationStatus = outcome.windowsSignal !== undefined
+                ? Object.freeze({ kind: 'signaled', signal: outcome.windowsSignal })
+                : outcome.signal !== undefined
+                    ? Object.freeze({
+                        kind: 'signaled',
+                        signal: Object.keys(constants.signals).find((key) => constants.signals[key] === outcome.signal) ?? outcome.signal,
+                    })
+                    : outcome.code !== undefined
+                        ? Object.freeze({ kind: 'exited', code: outcome.code })
+                        : undefined;
+            let primary = outcome.failure ? failure(outcome.failure, pid) : undefined;
+            const secondary = outcome.cleanupErrors.map((value) => failure(value, pid));
+            if (setupFailure !== undefined && outcome.failure?.kind !== 'setup') {
+                const error = new ProcessError('Subprocess cancellation setup failed', pid, {
+                    cause: setupFailure,
+                });
+                if (primary)
+                    secondary.push(error);
+                else
+                    primary = error;
+            }
+            const capture = (bytes, policy, stream) => {
+                try {
+                    return policy.kind === 'text' ? bytes?.toString('utf8') : bytes;
+                }
+                catch (error) {
+                    const value = new ProcessIOError(stream, pid, error);
+                    if (primary)
+                        secondary.push(value);
+                    else
+                        primary = value;
+                    return undefined;
+                }
+            };
+            const standardOutput = capture(outcome.standardOutput, config.output, 'stdout');
+            const standardError = capture(outcome.standardError, config.error, 'stderr');
+            if (primary) {
+                primary.cleanupErrors.push(...secondary);
+                Object.assign(primary, {
+                    terminationStatus,
+                    standardOutput,
+                    standardError,
+                    unresolvedProcessIdentifier: outcome.unresolvedProcessIdentifier,
+                });
+                reject(primary);
+            }
+            else {
+                const result = Object.freeze({
+                    processIdentifier: pid,
+                    terminationStatus: terminationStatus,
+                    standardOutput,
+                    standardError,
+                });
+                if (config.check && (terminationStatus.kind !== 'exited' || terminationStatus.code !== 0))
+                    reject(new ProcessExitError(result));
+                else
+                    resolve(result);
+            }
+        };
+        job.promise.then(complete).catch((error) => {
+            listener?.[Symbol.dispose]();
+            reject(new ProcessError('Native subprocess operation failed', undefined, { cause: error }));
+        });
+    });
+}
+export const Subprocess = Object.freeze({ run });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/values.js

@@ -0,0 +1,200 @@
+import { isAbsolute } from 'node:path';
+import { constants } from 'node:buffer';
+const commandBrand = Symbol.for('@swiftuijs/twill-shell/command/v1');
+const environmentBrand = Symbol.for('@swiftuijs/twill-shell/environment/v1');
+const outputBrand = Symbol.for('@swiftuijs/twill-shell/output/v1');
+const 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),
+    });
+}
+export const 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 !== undefined)
+            string(value, 'environment value', true);
+        snapshot[key] = value;
+    }
+    return Object.freeze({
+        [environmentBrand]: true,
+        kind,
+        values: Object.freeze(snapshot),
+    });
+}
+export const Environment = Object.freeze({
+    inherit(updates = {}) {
+        return environment('inherit', updates);
+    },
+    replace(values) {
+        return environment('replace', values);
+    },
+});
+const inheritedOutput = Object.freeze({
+    [outputBrand]: true,
+    kind: 'inherit',
+});
+const 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 });
+}
+export const Output = Object.freeze({
+    inherit() {
+        return inheritedOutput;
+    },
+    discard() {
+        return discardedOutput;
+    },
+    text(options) {
+        return capture('text', options);
+    },
+    bytes(options) {
+        return capture('bytes', options);
+    },
+});
+const noInput = Object.freeze({ [inputBrand]: true, kind: 'none' });
+const inheritedInput = Object.freeze({ [inputBrand]: true, kind: 'inherit' });
+export const Input = Object.freeze({
+    none() {
+        return noInput;
+    },
+    inherit() {
+        return inheritedInput;
+    },
+});
+const optionKeys = 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`);
+}
+export 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 = 1000, } = options;
+    if (cwd !== undefined)
+        string(cwd, 'cwd');
+    if (env !== undefined && (!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 !== undefined && !(signal instanceof AbortSignal))
+        throw new TypeError('signal must be an AbortSignal');
+    if (timeoutMs !== undefined)
+        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. */
+export function childEnvironment(policy, platform = process.platform) {
+    if (policy === undefined)
+        return undefined;
+    const env = Object.assign(Object.create(null), policy.kind === 'inherit' ? process.env : undefined);
+    if (platform === 'win32') {
+        const keys = new Map();
+        for (const key of Object.keys(env)) {
+            const normalized = key.toUpperCase();
+            const previous = keys.get(normalized);
+            if (previous !== undefined)
+                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 !== undefined)
+                delete env[previous];
+            keys.set(normalized, key);
+            if (value !== undefined)
+                env[key] = value;
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(policy.values)) {
+            if (value === undefined)
+                delete env[key];
+            else
+                env[key] = value;
+        }
+    }
+    return env;
+}
+//# sourceMappingURL=values.js.map

package/dist/values.js.map

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

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@swiftuijs/twill-shell",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.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",
+    "@swiftuijs/twill": "0.2.0",
+    "@swiftuijs/twill-formatter": "0.2.0",
+    "@swiftuijs/twill-export": "0.2.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
+    }
+  },
+  "dependencies": {
+    "@swiftuijs/twill-shell-native": "0.2.0"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:package": "node tests/consumer.mjs",
+    "benchmark": "node benchmarks/run.mjs"
+  }
 }