pty-spawn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Hiroki Osame <hiroki.osame@gmail.com>
+
+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,181 @@
+# pty-spawn
+
+Spawn a PTY process and `await` it like a promise. Built on [`node-pty`](https://github.com/microsoft/node-pty).
+
+## Install
+
+```sh
+npm install pty-spawn
+```
+
+## Quick start
+
+```ts
+import { spawn, waitFor } from 'pty-spawn'
+
+const subprocess = spawn('node', ['server.js'])
+
+// Wait for specific output
+await waitFor(subprocess, output => output.includes('Listening on port 3000'))
+
+// Interact
+subprocess.stdin.write('quit\n')
+
+// Await final result
+const result = await subprocess
+console.log(result.output)
+```
+
+## Why?
+
+`node-pty` gives you low-level event wiring. `pty-spawn` wraps it into a single awaitable object:
+
+| Without `pty-spawn` | With `pty-spawn` |
+| --- | --- |
+| Wire up promise + event cleanup | `await subprocess` |
+| Buffer output + poll + handle exit/timeout | `waitFor(subprocess, predicate)` |
+| Abort/exit race conditions | Late abort never overrides a clean exit |
+| Manual output accumulation loop | `subprocess.output` (live string) |
+
+## API
+
+### `spawn(file, args?, options?)`
+
+Spawns a PTY process. Returns a [`Subprocess`](#subprocess).
+
+```ts
+const subprocess = spawn('node', ['server.js'], { timeout: 5000 })
+
+// Without args
+const subprocess = spawn('bash', { window: { cols: 120 } })
+```
+
+#### Options
+
+All [`node-pty` options](https://github.com/microsoft/node-pty) are supported, plus:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `window` | `{ cols?, rows? }` | — | PTY window size |
+| `timeout` | `number` | `0` (disabled) | Auto-abort after _N_ ms |
+| `signal` | `AbortSignal` | — | Abort control |
+| `reject` | `boolean` | `true` | Reject on non-zero exit, signal, or abort. When `false`, always resolves |
+
+### Subprocess
+
+A `Promise<Result>` with control properties attached.
+
+#### Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `pid` | `number` | Process ID |
+| `output` | `string` | Accumulated output (live — grows as the process writes) |
+
+#### `stdin.write(data)`
+
+Write to the process stdin.
+
+```ts
+subprocess.stdin.write('hello\n')
+```
+
+#### `kill(signal?, options?)`
+
+Terminate the process and wait for exit.
+
+```ts
+await subprocess.kill()
+await subprocess.kill('SIGTERM')
+await subprocess.kill('SIGTERM', { forceKill: 3000 })
+await subprocess.kill({ forceKill: 3000 })
+```
+
+`forceKill` escalates to `SIGKILL` after the given milliseconds if the process traps the initial signal. Safe to call after exit.
+
+#### `resize(cols, rows)`
+
+Resize the PTY window. Safe to call after exit.
+
+#### Async iteration
+
+The subprocess itself is `AsyncIterable<string>` — stream output chunks in real time:
+
+```ts
+for await (const chunk of subprocess) {
+    process.stdout.write(chunk)
+}
+```
+
+#### Async disposal
+
+Supports [`await using`](https://github.com/tc39/proposal-explicit-resource-management) for automatic cleanup:
+
+```ts
+{
+    await using subprocess = spawn('node', ['server.js'])
+    // killed when scope exits
+}
+```
+
+### Result
+
+`await subprocess` resolves with:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `output` | `string` | All terminal output |
+| `exitCode` | `number` | Process exit code |
+| `signalName` | `string?` | Signal name if terminated (e.g. `'SIGTERM'`) |
+| `file` | `string` | Spawned file path |
+| `args` | `string[]` | Arguments passed |
+| `durationMs` | `number` | Wall-clock duration in ms |
+
+> [!NOTE]
+> PTYs combine stdout and stderr into a single stream. `output` contains everything the process wrote to the terminal.
+
+### SubprocessError
+
+Non-zero exit or signal termination rejects with `SubprocessError`, which extends `Error` and includes all `Result` fields.
+
+```ts
+import { spawn, SubprocessError } from 'pty-spawn'
+
+try {
+    await subprocess
+} catch (error) {
+    if (error instanceof SubprocessError) {
+        error.exitCode // e.g. 1
+        error.signalName // e.g. 'SIGTERM'
+        error.output // captured output
+    }
+}
+```
+
+Abort and timeout behavior:
+- `timeout` and `signal` abort the process, rejecting with `SubprocessError`
+- `error.cause` contains the underlying reason (e.g. `TimeoutError`)
+- If the process exits cleanly before the abort fires, success wins the race
+
+### `waitFor(subprocess, predicate, options?)`
+
+Wait for output to satisfy a predicate.
+
+```ts
+await waitFor(subprocess, output => output.includes('Ready'))
+
+// With timeout
+await waitFor(subprocess, output => output.includes('Ready'), {
+    signal: AbortSignal.timeout(5000)
+})
+```
+
+The predicate receives accumulated output (since `waitFor` was called) and can be async. Calls are serialized — a slow predicate won't run concurrently.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `signal` | `AbortSignal` | Abort control (use `AbortSignal.timeout()` for timeouts) |
+
+## Inspiration
+
+Thanks to [execa](https://github.com/sindresorhus/execa) and [nano-spawn](https://github.com/sindresorhus/nano-spawn) for the inspiration. They proved that `await spawn(...)` is the right primitive for child processes — pty-spawn brings that model to pseudo-terminals.

package/dist/index.d.mts

@@ -0,0 +1,59 @@
+import { IPtyForkOptions } from 'node-pty';
+
+type Result = {
+    output: string;
+    exitCode: number;
+    signalName?: string;
+    file: string;
+    args: readonly string[];
+    durationMs: number;
+};
+type WindowOptions = {
+    cols?: number;
+    rows?: number;
+};
+type Options = Omit<IPtyForkOptions, 'cols' | 'rows'> & {
+    window?: WindowOptions;
+    signal?: AbortSignal;
+    timeout?: number;
+    reject?: boolean;
+};
+declare class SubprocessError extends Error implements Result {
+    output: string;
+    exitCode: number;
+    signalName?: string;
+    file: string;
+    args: readonly string[];
+    durationMs: number;
+    constructor(message: string, { cause, ...result }: Result & {
+        cause?: unknown;
+    });
+}
+type KillOptions = {
+    forceKill?: number;
+};
+type Subprocess = Promise<Result> & {
+    readonly pid: number;
+    readonly output: string;
+    kill: {
+        (signal?: string, options?: KillOptions): Promise<void>;
+        (options?: KillOptions): Promise<void>;
+    };
+    resize: (cols: number, rows: number) => void;
+    stdin: {
+        write: (data: string) => void;
+    };
+    [Symbol.asyncIterator]: () => AsyncIterator<string>;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+declare function spawn(file: string, args: readonly string[], options?: Options): Subprocess;
+declare function spawn(file: string, options?: Options): Subprocess;
+
+type WaitForOptions = {
+    signal?: AbortSignal;
+};
+type WaitForPredicate = (output: string) => boolean | Promise<boolean>;
+declare const waitFor: (subprocess: Subprocess, predicate: WaitForPredicate, { signal, }?: WaitForOptions) => Promise<void>;
+
+export { SubprocessError, spawn, waitFor };
+export type { KillOptions, Options, Result, Subprocess, WaitForOptions, WaitForPredicate, WindowOptions };

package/dist/index.mjs

@@ -0,0 +1,271 @@
+import { EventEmitter, on } from 'node:events';
+import { constants } from 'node:os';
+import { spawn as spawn$1 } from 'node-pty';
+
+const getSignalName = (signal) => {
+  if (signal === void 0) {
+    return void 0;
+  }
+  for (const [name, number] of Object.entries(constants.signals)) {
+    if (number === signal) {
+      return name;
+    }
+  }
+  return void 0;
+};
+const createAbortSignal = (userSignal, timeout) => {
+  if (!userSignal && timeout <= 0) {
+    return void 0;
+  }
+  if (!userSignal) {
+    return AbortSignal.timeout(timeout);
+  }
+  if (timeout <= 0) {
+    return userSignal;
+  }
+  return AbortSignal.any([userSignal, AbortSignal.timeout(timeout)]);
+};
+class SubprocessError extends Error {
+  output;
+  exitCode;
+  signalName;
+  file;
+  args;
+  durationMs;
+  constructor(message, { cause, ...result }) {
+    super(message, { cause });
+    this.name = "SubprocessError";
+    Object.assign(this, result);
+  }
+}
+function spawn(file, argsOrOptions = [], maybeOptions = {}) {
+  const args = Array.isArray(argsOrOptions) ? [...argsOrOptions] : [];
+  const options = Array.isArray(argsOrOptions) ? maybeOptions : argsOrOptions;
+  const {
+    window,
+    signal: userSignal,
+    timeout = 0,
+    reject: shouldReject = true,
+    ...ptyOptions
+  } = options;
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new TypeError("options.timeout must be a non-negative finite number.");
+  }
+  const startedAt = Date.now();
+  const ptyProcess = spawn$1(file, args, {
+    ...ptyOptions,
+    cols: window?.cols,
+    rows: window?.rows
+  });
+  const signal = createAbortSignal(userSignal, timeout);
+  const emitter = new EventEmitter();
+  let output = "";
+  let exitCode;
+  let exitSignalName;
+  let lastDataAt = 0;
+  let settled = false;
+  let abortedBeforeExit = false;
+  let settleQuietTimer;
+  let settleMaxTimer;
+  const quietMs = 50;
+  const maxMs = 3e3;
+  let resolveResult;
+  let rejectResult;
+  const resultPromise = new Promise((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+  const safeKill = (killSignal) => {
+    try {
+      ptyProcess.kill(killSignal);
+    } catch {
+    }
+  };
+  const settle = (code) => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    if (settleQuietTimer) {
+      clearTimeout(settleQuietTimer);
+    }
+    if (settleMaxTimer) {
+      clearTimeout(settleMaxTimer);
+    }
+    signal?.removeEventListener("abort", onAbort);
+    const result = {
+      output,
+      exitCode: code,
+      signalName: exitSignalName,
+      file,
+      args,
+      durationMs: Date.now() - startedAt
+    };
+    if (!shouldReject) {
+      resolveResult(result);
+      return;
+    }
+    if (signal?.aborted && abortedBeforeExit) {
+      rejectResult(new SubprocessError("Subprocess aborted.", {
+        ...result,
+        cause: signal.reason
+      }));
+      return;
+    }
+    if (code !== 0 || exitSignalName) {
+      const message = exitSignalName ? `Subprocess terminated by signal ${exitSignalName}.` : `Subprocess exited with code ${code}.`;
+      rejectResult(new SubprocessError(message, result));
+      return;
+    }
+    resolveResult(result);
+  };
+  const scheduleSettle = () => {
+    if (exitCode === void 0) {
+      return;
+    }
+    const elapsedSinceLastData = lastDataAt === 0 ? 0 : Date.now() - lastDataAt;
+    const quietDelayMs = Math.max(0, quietMs - elapsedSinceLastData);
+    if (settleQuietTimer) {
+      clearTimeout(settleQuietTimer);
+    }
+    const code = exitCode;
+    settleQuietTimer = setTimeout(() => {
+      settle(code);
+    }, quietDelayMs);
+  };
+  const onAbort = () => {
+    if (exitCode === void 0) {
+      abortedBeforeExit = true;
+    }
+    safeKill();
+  };
+  if (signal?.aborted) {
+    onAbort();
+  } else {
+    signal?.addEventListener("abort", onAbort, { once: true });
+  }
+  ptyProcess.onData((data) => {
+    lastDataAt = Date.now();
+    output += data;
+    emitter.emit("data", data);
+    if (exitCode !== void 0) {
+      scheduleSettle();
+    }
+  });
+  ptyProcess.onExit(({ exitCode: nextExitCode, signal: exitSignal }) => {
+    exitCode = nextExitCode;
+    exitSignalName = getSignalName(exitSignal);
+    emitter.emit("exit", nextExitCode);
+    scheduleSettle();
+    settleMaxTimer = setTimeout(() => {
+      settle(nextExitCode);
+    }, maxMs);
+  });
+  const iterateOutput = async function* iterateOutput2() {
+    if (exitCode !== void 0) {
+      await resultPromise;
+      return;
+    }
+    const iteratorAbort = new AbortController();
+    const onIteratorExit = () => {
+      iteratorAbort.abort();
+    };
+    emitter.once("exit", onIteratorExit);
+    if (exitCode !== void 0) {
+      iteratorAbort.abort();
+    }
+    try {
+      for await (const [chunk] of on(emitter, "data", { signal: iteratorAbort.signal })) {
+        yield chunk;
+      }
+    } catch (error) {
+      if (!iteratorAbort.signal.aborted) {
+        throw error;
+      }
+    } finally {
+      emitter.off("exit", onIteratorExit);
+      await resultPromise;
+    }
+  };
+  const kill = async (signalOrOptions, killOptions) => {
+    const killSignal = typeof signalOrOptions === "string" ? signalOrOptions : void 0;
+    const { forceKill } = typeof signalOrOptions === "object" ? signalOrOptions : killOptions ?? {};
+    safeKill(killSignal);
+    const forceKillTimer = forceKill === void 0 ? void 0 : setTimeout(() => safeKill("SIGKILL"), forceKill);
+    await resultPromise.catch(() => {
+    });
+    if (forceKillTimer) {
+      clearTimeout(forceKillTimer);
+    }
+  };
+  const subprocess = Object.assign(resultPromise, {
+    pid: ptyProcess.pid,
+    kill,
+    resize: (cols, rows) => {
+      try {
+        ptyProcess.resize(cols, rows);
+      } catch {
+      }
+    },
+    stdin: {
+      write: (data) => {
+        ptyProcess.write(data);
+      }
+    },
+    [Symbol.asyncIterator]: iterateOutput,
+    [Symbol.asyncDispose]: kill
+  });
+  Object.defineProperty(subprocess, "output", {
+    get: () => output,
+    enumerable: true,
+    configurable: true
+  });
+  return subprocess;
+}
+
+const waitFor = async (subprocess, predicate, {
+  signal
+} = {}) => {
+  if (signal?.aborted) {
+    throw signal.reason;
+  }
+  let output = "";
+  const iterator = subprocess[Symbol.asyncIterator]();
+  let removeAbortListener;
+  const abortPromise = signal ? new Promise((_resolve, reject) => {
+    const handler = () => reject(signal.reason);
+    signal.addEventListener("abort", handler, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", handler);
+  }) : void 0;
+  abortPromise?.catch(() => {
+  });
+  try {
+    while (true) {
+      const next = abortPromise ? await Promise.race([iterator.next(), abortPromise]) : await iterator.next();
+      if (next.done) {
+        break;
+      }
+      output += next.value;
+      if (await predicate(output)) {
+        return;
+      }
+      if (signal?.aborted) {
+        throw signal.reason;
+      }
+    }
+  } catch (error) {
+    if (signal?.aborted) {
+      throw signal.reason;
+    }
+    throw error;
+  } finally {
+    removeAbortListener?.();
+  }
+  const exitCode = await subprocess.then((result) => result.exitCode).catch((error) => error.exitCode);
+  throw new Error(
+    `Process exited with code ${exitCode} before waitFor predicate was satisfied.
+Last output: ${JSON.stringify(output.slice(-200))}`
+  );
+};
+
+export { SubprocessError, spawn, waitFor };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "pty-spawn",
+  "version": "1.0.0",
+  "description": "Tiny pseudo-terminal spawning for humans",
+  "keywords": [
+    "pty",
+    "terminal",
+    "spawn",
+    "subprocess",
+    "node-pty"
+  ],
+  "license": "MIT",
+  "repository": "privatenumber/pty-spawn",
+  "funding": "https://github.com/privatenumber/pty-spawn?sponsor=1",
+  "author": {
+    "name": "Hiroki Osame",
+    "email": "hiroki.osame@gmail.com"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.mts",
+    "default": "./dist/index.mjs"
+  },
+  "imports": {
+    "#pty-spawn": {
+      "dev": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "engines": {
+    "node": ">=20.20.0"
+  },
+  "dependencies": {
+    "node-pty": "1.2.0-beta.10"
+  }
+}