@bluewombat/isolator 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# Isolator
+
+Transformer: runs **one Isolation**. It takes a Parent directory that
+already exists and creates a Child directory that did not. The Child is a
+snapshot of the Parent's working files at Isolation time, then independent of
+the Parent.
+
+Behavioural contract: [SPECS.md](./SPECS.md).
+
+## Stack
+
+Repository stack — TypeScript, Node 24.20, Biome, `node:test`. See [docs/DEVELOPMENT.md](../../../docs/DEVELOPMENT.md).
+
+## Setup
+
+From the repository root:
+
+```bash
+nvm use
+npm install
+```
+
+## Commands
+
+| Task      | Command          |
+| --------- | ---------------- |
+| Lint      | `npm run lint`   |
+| Format    | `npm run format` |
+| Typecheck | `npm run tsc`    |
+| Test      | `npm test`       |
+| Build     | `npm run build`  |
+
+Binary after build: `dist/cli.js` (package bin name `isolator`).
+
+## Run
+
+Parent must already exist. Child must not. Missing ancestors of `--child` are
+created. Example:
+
+```bash
+npm run build
+node dist/cli.js \
+  --id feat-1 \
+  --parent /absolute/path/to/parent \
+  --child /absolute/path/to/child \
+  --duration-ms 60000 \
+  --strategy @bluewombat/isolation-copy
+```
+
+The CLI requires `--strategy`: a package name or path that exports `strategy` with an `isolation` backend. Isolator does not sniff `.git` and does not choose git versus copy.
+
+Progress is JSON lines on stdout (`status`, `isolation-started`,
+`isolation-finished`). Exit codes: `0` isolated, `1` failed, `2`
+invalid-invocation, `130` interrupted.
+
+## Import
+
+Same Transformer, in process. `cli.ts` is an adapter over this function — it reads argv
+and stdin, calls `runIsolator`, and maps the outcome to an exit code. Nothing the CLI
+can do is unreachable from here.
+
+```ts
+import { strategy } from "@bluewombat/isolation-copy";
+import { runIsolator } from "@bluewombat/isolator";
+
+const result = await runIsolator({
+  invocation,                       // same shape the CLI builds from argv
+  backend: strategy.isolation,      // Host / CLI loads a strategy package
+  write: (line) => events.push(line), // progress as values, not stdout
+});
+```
+
+`src/index.ts` exports `runIsolator`, `IsolationBackend`, `RunOptions` /
+`RunResult`, `ProgressWriter`, and this Transformer's domain types. Isolation
+strategies live under `packages/plugins/isolation-*`.
+
+## Layout
+
+```
+SPECS.md                 behavioural contract
+README.md                how to build and run
+src/
+  cli.ts                 entry
+  types.ts               Transformer-owned types
+  args/                  CLI parsing
+  status/                Status labels and --on-status
+  progress/              JSON-line progress writer
+  child/                 spawn (--on-status)
+  isolate/               snapshot via injected IsolationBackend (stop + create-child)
+  run/                   invocation orchestration
+fixtures/                fake --on-status scripts for tests
+```
+
+Sources stay colocated: helpers used once live next to their caller.

package/SPECS.md

@@ -0,0 +1,294 @@
+# Isolator
+
+Independent Transformer: it has a binary, a contract, and nothing else. Isolator is
+alone. Its code, identifiers, comments, and messages name only what it owns: the
+Isolation, its arguments, the Parent path, the Child path, Status, clocks, and
+the Isolation outcome. No other component is mentioned there, because none of
+them exist inside this perimeter.
+
+Isolator runs **one Isolation**. It takes a Parent directory it did not create
+and produces a Child directory that did not exist. The Child is a snapshot of
+the Parent's working files at Isolation time, then independent of the Parent.
+
+The invocation is always the same. How Isolator produces the Child is an
+injected **Isolation backend** (`attach` / `abort`). Isolator does not choose a
+strategy. The CLI requires `--strategy <specifier>`; Host loads the package
+named in `workLine.isolation`. Strategies live under `packages/plugins/isolation-*`.
+
+Isolator does not run work in either directory. It does not fold the Child back
+into the Parent. It does not delete a Child that reached `isolated`.
+
+Stack and binary layout: [README.md](./README.md).
+
+## 1. Job
+
+```
+  arguments                      Isolator                         disk
+  ---------                      --------                         ----
+  Isolation                      one invocation                   create the Child
+  Parent                         snapshot Parent working files    do not write Parent working files
+  Child path                     then independent
+  bounds
+                             ←   Isolation outcome + Child path + Status
+```
+
+**In:** arguments. **Out:** one Isolation outcome, the Child path when the
+outcome is `isolated`, and a live Status each time it changes. Isolator does
+not wait for a listener to acknowledge.
+
+A Child of one Isolation may be the Parent of a later Isolation. Isolator does
+not know or care; every invocation is the same job.
+
+## 2. Options
+
+Isolator is invoked with arguments. It does not read an input file. It does not
+read configuration from the Parent or the Child.
+
+| Argument                 | Content                                                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `--id`                   | Isolation id. Copied onto every Status and progress line. Non-empty.                               |
+| `--parent`               | Absolute path. Must already exist as a directory. Working files here are the snapshot source.      |
+| `--child`                | Absolute path. Must not exist. Isolator creates this directory, including missing ancestors.       |
+| `--duration-ms`          | Positive integer. Wall clock of the Isolation, from the moment Isolator starts creating the Child. |
+| `--strategy`             | Package name or path. CLI only. Loads `strategy.isolation`. `runIsolator` receives the backend as an argument; it never chooses one. |
+| `--on-status -- <argv…>` | Optional. Command to run each time Status changes. Omitted: Status still goes to stdout.           |
+
+No other argument is read.
+
+Malformed arguments, empty id, non-absolute path, missing Parent, Parent not a
+directory, Child already exists, Child's containing path exists but is not a
+directory, Parent and Child the same path, Parent a prefix of Child, Child a
+prefix of Parent, or a non-positive `--duration-ms` → Isolation outcome
+`invalid-invocation`. No Child is created. Parent is left as it was.
+
+## 3. Workflow
+
+One invocation runs one Isolation. There is no loop.
+
+```
+Check arguments and paths (§2). Unusable → `invalid-invocation`.
+Announce Status `isolating`.
+Start the Isolation clock.
+Create the Child as a snapshot of the Parent's working files (§4).
+  If the clock fires, a stop signal arrives, or creation cannot complete
+    → remove any incomplete Child → Isolation outcome `failed` or `interrupted` (§5).
+  If creation completes
+    → Isolation outcome `isolated`. The Child stays.
+```
+
+```mermaid
+flowchart TD
+  START[Check arguments] --> OK{Usable?}
+  OK -->|no| INV[invalid-invocation]
+  OK -->|yes| ISO[Create Child from Parent]
+  ISO -->|complete| DONE[isolated]
+  ISO -->|clock| FAIL[failed — incomplete Child removed]
+  ISO -->|stop signal| INT[interrupted — incomplete Child removed]
+  ISO -->|cannot complete| FAIL
+```
+
+## 4. Isolation
+
+Isolation is a property of two directories after a successful invocation. It is
+not a later process, not a merge, and not a lock on the Parent.
+
+### Isolation backend
+
+Isolator does not choose a strategy. The caller injects an `IsolationBackend`
+(`attach` / `abort`). Strategies live under `packages/plugins/isolation-*` and export
+`strategy: { isolation, fold }`.
+
+| Field on `attach` | Meaning |
+| ----------------- | ------- |
+| `id?`             | Isolation id; a strategy may derive a branch or other label from it |
+| `parent` / `child` | Absolute paths |
+| `timeoutMs` / `shouldInterrupt` / `shouldStop` | Budgets and stop signals |
+
+The binary's `cli.ts` requires `--strategy <specifier>` and loads that package.
+Host resolves `workLine.isolation` the same way. There is no `.git` sniff and no
+`"git"` / `"copy"` alias. A strategy failure is `failed`, not a silent switch.
+
+Git bookkeeping under the Parent (when using `@bluewombat/isolation-git`) is
+Isolation bookkeeping, not working files. A copy strategy writes nothing on the
+Parent.
+
+Same `--id`, `--parent`, `--child`. Same outcomes. Snapshot and independence
+(§4) hold either way.
+
+### Snapshot
+
+At Isolation start, Isolator reads the Parent's **working files**: the tree a
+process with that directory as its working directory would see as the work.
+When the Isolation outcome is `isolated`, the Child has the same relative paths
+and the same content for those working files.
+
+Isolator adds no working file of its own under the Child. The Child is the
+snapshot, not a wrapper around it.
+
+The contract is the working files. Git vs copy is how Isolator produces them.
+
+### Independence
+
+After `isolated`:
+
+- A write under the Child does not change the Parent's working files.
+- A write under the Parent does not change the Child's working files.
+
+The two trees may then diverge. Isolator does not keep them in sync. A new
+Isolation is a new invocation.
+
+### Parent
+
+Isolator does not add, remove, or edit the Parent's working files. After any
+outcome, those files are what they were at invocation start.
+
+Isolator may write Isolation bookkeeping that is not working content, if the
+Parent's storage requires it to attach a Child. That bookkeeping is not a
+working file.
+
+Isolator never deletes the Parent.
+
+### Child
+
+Isolator creates `--child`. Missing ancestor directories are created. A
+containing path that already exists and is not a directory is
+`invalid-invocation`.
+
+Isolator does not delete a Child whose Isolation outcome is `isolated`.
+Callers that destroy a Child do so outside this process.
+
+If Isolation does not complete, Isolator removes the incomplete Child so a
+retry with the same `--child` is not blocked by a half-created directory. A
+directory that already existed before this invocation is never that incomplete
+Child — that case is `invalid-invocation` and Isolator does not touch it.
+
+### What Isolator does not do
+
+- Interpret files in the Parent or the Child.
+- Spawn a worker whose job is the content.
+- Fold the Child into the Parent.
+- Reuse an existing Child.
+- Overwrite `--child`.
+- Choose a Child path of its own: `--child` is the path.
+
+## 5. Clocks and interrupt
+
+**Isolation clock.** Starts when Isolator begins creating the Child. On
+`--duration-ms`, Isolator stops creation, removes any incomplete Child, Isolation
+outcome `failed`. The report names the clock.
+
+**Interrupt.** SIGINT and SIGTERM stop this invocation. Isolator stops creation,
+removes any incomplete Child, Isolation outcome `interrupted`. It does **not**
+delete the Parent. It does **not** delete a Child that already reached
+`isolated` (that Isolation is finished).
+
+A stop signal that races a clock uses `interrupted`.
+
+## 6. Status
+
+Status is the live snapshot of this invocation. It changes at phase boundaries
+(Isolation about to run, Isolation outcome known). It is not a history. The
+`label` is meant to be shown as-is.
+
+### Shape
+
+| Field   | Content                                                          |
+| ------- | ---------------------------------------------------------------- |
+| `phase` | `isolating`, `isolated`, `failed`, `interrupted`, or `invalid`   |
+| `id`    | From `--id`. Absent on `invalid` when `--id` itself is unusable. |
+| `label` | Canonical display string. See below.                             |
+
+### Label
+
+Built by Isolator. Do not invent another spelling.
+
+| `phase`       | `label`            | Example              |
+| ------------- | ------------------ | -------------------- |
+| `isolating`   | `isolating:<id>`   | `isolating:feat-1`   |
+| `isolated`    | `isolated:<id>`    | `isolated:feat-1`    |
+| `failed`      | `failed:<id>`      | `failed:feat-1`      |
+| `interrupted` | `interrupted:<id>` | `interrupted:feat-1` |
+| `invalid`     | `invalid`          | `invalid`            |
+
+`<id>` is the `--id` argument, as given.
+
+### When it is announced
+
+| Moment                                                  | `phase`      |
+| ------------------------------------------------------- | ------------ |
+| Arguments or paths unusable                             | `invalid`    |
+| Child about to be created                               | `isolating`  |
+| Isolation outcome `isolated` / `failed` / `interrupted` | that outcome |
+
+Announced on stdout as a JSON line (`event`: `status`) carrying the fields
+above. If `--on-status` was given, Isolator also runs that command, cwd
+unchanged (not the Parent, not the Child), and appends:
+
+| Argument  | Content                    |
+| --------- | -------------------------- |
+| `--id`    | Isolation id, when present |
+| `--label` | The label                  |
+| `--phase` | The phase                  |
+
+`--on-status` does not count against the Isolation clock. A non-zero exit, a
+missing command, or a hang that Isolator must kill does **not** change the
+Isolation outcome. Visibility must not take the Isolation down.
+
+## 7. Progress
+
+JSON lines on stdout. A `status` line is the live snapshot (§6). The other
+lines record the Isolation.
+
+| `event`              | When                       |
+| -------------------- | -------------------------- |
+| `status`             | Each time Status changes   |
+| `isolation-started`  | Child about to be created  |
+| `isolation-finished` | Isolation outcome is known |
+
+Each line carries `id` when the Isolation id is usable.
+
+`isolation-finished` also carries:
+
+| Field     | Content                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| `outcome` | The Isolation outcome (§8).                                                |
+| `child`   | Absolute `--child` path. Present only when `outcome` is `isolated`.        |
+| `report`  | Why, when `outcome` is `failed` or `invalid-invocation`. Absent otherwise. |
+
+Isolator creates no working file under the Parent. It creates no working file
+under the Child other than the snapshot. It deletes nothing under the Parent.
+
+## 8. Isolation outcomes
+
+Exactly one per invocation. The meaning is entirely inside this process.
+
+| Outcome              | Meaning                                                                                                         |
+| -------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `invalid-invocation` | Arguments or paths unusable. No Child created. Parent untouched.                                                |
+| `isolated`           | Child exists, snapshot taken, independence holds. Child stays.                                                  |
+| `failed`             | Isolation started and could not complete (clock, I/O, spawn of Isolator's own tools). Incomplete Child removed. |
+| `interrupted`        | Stop signal before `isolated`. Incomplete Child removed.                                                        |
+
+No partial Isolation. A Child that exists after this process exits was either
+already there (`invalid-invocation`, left alone) or fully `isolated`.
+
+## 9. Acceptance
+
+1. Parent has working files; Isolation completes → `isolated`; Child has those files at the same relative paths; Parent working files unchanged.
+2. After `isolated`, a new file written only under the Child is absent from the Parent.
+3. After `isolated`, a new file written only under the Parent is absent from the Child.
+4. `--child` already exists → `invalid-invocation`; that directory unchanged; Parent unchanged.
+5. Missing Parent, relative path, empty `--id`, `--child` inside `--parent`, or `--parent` inside `--child` → `invalid-invocation`; no Child created.
+6. SIGTERM during creation → `interrupted`; `--child` does not exist afterwards; Parent remains.
+7. Isolation clock fires during creation → `failed`; `--child` does not exist afterwards; Parent remains.
+8. Isolator never deletes the Parent, never deletes an `isolated` Child, never writes a working file of its own into the Child, never folds the Child into the Parent.
+9. A Child produced by one Isolation can be `--parent` of another Isolation; that second Isolation is the same job.
+10. Entering creation with `--id feat-1` announces `label` `isolating:feat-1` on stdout, and via `--on-status` when that argument is set.
+11. `--on-status` exiting non-zero does not change an `isolated` Isolation.
+12. `@bluewombat/isolation-git` → `isolated` via git; Child is a worktree; Parent working files unchanged; independence holds.
+13. `@bluewombat/isolation-copy` → `isolated` via copy; same snapshot and independence; Parent unchanged.
+14. `@bluewombat/isolation-git` and git cannot complete → `failed`, not a copy.
+15. `--child` whose containing directory is missing → Isolator creates the ancestors; `isolated`.
+16. The CLI requires `--strategy <specifier>`; `runIsolator` never chooses a strategy.
+
+How to build and run this Transformer: [README.md](./README.md).

package/dist/args/parse-args.d.ts

@@ -0,0 +1,6 @@
+import type { ParseResult } from "../types.js";
+/**
+ * Parse Isolator CLI argv (without node/script). Malformed input → not ok.
+ */
+export declare function parseArgs(argv: string[]): ParseResult;
+//# sourceMappingURL=parse-args.d.ts.map

package/dist/args/parse-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../../src/args/parse-args.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,aAAa,CAAC;AAgH3D;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CAyJrD"}

package/dist/args/parse-args.js

@@ -0,0 +1,223 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+const ISOLATOR_FLAGS = new Set([
+    "--id",
+    "--parent",
+    "--child",
+    "--duration-ms",
+    "--on-status",
+    "--strategy",
+]);
+function isIsolatorFlag(token) {
+    return ISOLATOR_FLAGS.has(token);
+}
+function takeValue(argv, index) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        return null;
+    }
+    return { value, next: index + 2 };
+}
+function takeCommandArgv(argv, start) {
+    if (argv[start] !== "--") {
+        return null;
+    }
+    const command = [];
+    let i = start + 1;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token !== undefined && isIsolatorFlag(token)) {
+            break;
+        }
+        if (token !== undefined) {
+            command.push(token);
+        }
+        i += 1;
+    }
+    if (command.length === 0) {
+        return null;
+    }
+    return { command, next: i };
+}
+function parsePositiveInt(raw) {
+    if (!/^\d+$/.test(raw)) {
+        return null;
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < 1) {
+        return null;
+    }
+    return value;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function pathsOverlap(parent, child) {
+    const parentResolved = resolve(parent);
+    const childResolved = resolve(child);
+    if (parentResolved === childResolved) {
+        return true;
+    }
+    const fromParent = relative(parentResolved, childResolved);
+    const fromChild = relative(childResolved, parentResolved);
+    const childInsideParent = fromParent !== "" && !fromParent.startsWith("..") && !isAbsolute(fromParent);
+    const parentInsideChild = fromChild !== "" && !fromChild.startsWith("..") && !isAbsolute(fromChild);
+    return childInsideParent || parentInsideChild;
+}
+function snapshotPartial(id, onStatusArgv) {
+    const partial = {};
+    if (id !== undefined && id.length > 0) {
+        partial.id = id;
+    }
+    if (onStatusArgv !== undefined) {
+        partial.onStatusArgv = onStatusArgv;
+    }
+    return partial;
+}
+function withPartial(reason, id, onStatusArgv) {
+    const failure = { ok: false, reason };
+    const partial = snapshotPartial(id, onStatusArgv);
+    if (partial.id !== undefined) {
+        failure.id = partial.id;
+    }
+    if (partial.onStatusArgv !== undefined) {
+        failure.onStatusArgv = partial.onStatusArgv;
+    }
+    return failure;
+}
+/**
+ * Parse Isolator CLI argv (without node/script). Malformed input → not ok.
+ */
+export function parseArgs(argv) {
+    let id;
+    let parent;
+    let child;
+    let durationMs;
+    let strategy;
+    let onStatusArgv;
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === undefined) {
+            break;
+        }
+        if (token === "--id") {
+            const taken = takeValue(argv, i);
+            if (!taken) {
+                return withPartial("Missing value for --id.", id, onStatusArgv);
+            }
+            id = taken.value;
+            i = taken.next;
+            continue;
+        }
+        if (token === "--parent") {
+            const taken = takeValue(argv, i);
+            if (!taken) {
+                return withPartial("Missing value for --parent.", id, onStatusArgv);
+            }
+            parent = taken.value;
+            i = taken.next;
+            continue;
+        }
+        if (token === "--child") {
+            const taken = takeValue(argv, i);
+            if (!taken) {
+                return withPartial("Missing value for --child.", id, onStatusArgv);
+            }
+            child = taken.value;
+            i = taken.next;
+            continue;
+        }
+        if (token === "--duration-ms") {
+            const taken = takeValue(argv, i);
+            if (!taken) {
+                return withPartial("Missing value for --duration-ms.", id, onStatusArgv);
+            }
+            const value = parsePositiveInt(taken.value);
+            if (value === null) {
+                return withPartial("--duration-ms must be a positive integer.", id, onStatusArgv);
+            }
+            durationMs = value;
+            i = taken.next;
+            continue;
+        }
+        if (token === "--strategy") {
+            const taken = takeValue(argv, i);
+            if (!taken) {
+                return withPartial("Missing value for --strategy.", id, onStatusArgv);
+            }
+            if (taken.value.length === 0) {
+                return withPartial("--strategy must be a non-empty package name or path.", id, onStatusArgv);
+            }
+            strategy = taken.value;
+            i = taken.next;
+            continue;
+        }
+        if (token === "--on-status") {
+            const command = takeCommandArgv(argv, i + 1);
+            if (!command) {
+                return withPartial("Missing non-empty command after --on-status --.", id, onStatusArgv);
+            }
+            onStatusArgv = command.command;
+            i = command.next;
+            continue;
+        }
+        return withPartial(`Unknown argument "${token}".`, id, onStatusArgv);
+    }
+    if (id === undefined) {
+        return withPartial("Missing required --id.", id, onStatusArgv);
+    }
+    if (id.length === 0) {
+        return withPartial("--id must be non-empty.", undefined, onStatusArgv);
+    }
+    if (parent === undefined) {
+        return withPartial("Missing required --parent.", id, onStatusArgv);
+    }
+    if (child === undefined) {
+        return withPartial("Missing required --child.", id, onStatusArgv);
+    }
+    if (durationMs === undefined) {
+        return withPartial("Missing required --duration-ms.", id, onStatusArgv);
+    }
+    if (strategy === undefined) {
+        return withPartial("Missing required --strategy. Pass a package name or path that exports strategy.", id, onStatusArgv);
+    }
+    if (!isAbsolute(parent)) {
+        return withPartial("--parent must be an absolute path.", id, onStatusArgv);
+    }
+    if (!isAbsolute(child)) {
+        return withPartial("--child must be an absolute path.", id, onStatusArgv);
+    }
+    if (!existsSync(parent)) {
+        return withPartial(`--parent does not exist: ${parent}`, id, onStatusArgv);
+    }
+    if (!isDirectory(parent)) {
+        return withPartial(`--parent is not a directory: ${parent}`, id, onStatusArgv);
+    }
+    if (existsSync(child)) {
+        return withPartial(`--child already exists: ${child}`, id, onStatusArgv);
+    }
+    const childContainer = dirname(child);
+    if (existsSync(childContainer) && !isDirectory(childContainer)) {
+        return withPartial(`Child containing directory is not a directory: ${childContainer}`, id, onStatusArgv);
+    }
+    if (pathsOverlap(parent, child)) {
+        return withPartial("--parent and --child must not be the same path, and neither may be a prefix of the other.", id, onStatusArgv);
+    }
+    const invocation = {
+        id,
+        parent: resolve(parent),
+        child: resolve(child),
+        durationMs,
+    };
+    if (onStatusArgv !== undefined) {
+        invocation.onStatusArgv = onStatusArgv;
+    }
+    return { ok: true, invocation, strategy };
+}
+//# sourceMappingURL=parse-args.js.map

package/dist/args/parse-args.js.map

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

package/dist/child/run-child.d.ts

@@ -0,0 +1,39 @@
+import type { ClockName } from "../types.js";
+export type SpawnRequest = {
+    argv: string[];
+    /** Undefined lets the child inherit the caller's directory. */
+    cwd?: string | undefined;
+    /** Wall-clock budget for this child (ms). */
+    timeoutMs: number;
+    /** Which clock owns the nearer deadline when timeoutMs hits. */
+    timeoutClock: ClockName;
+    /** When true, treat kill as interrupted (stop signal). */
+    shouldInterrupt: () => boolean;
+    /** Undefined lets the child inherit the caller's environment. */
+    env?: NodeJS.ProcessEnv | undefined;
+};
+export type SpawnOutcome = {
+    kind: "exited";
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+} | {
+    kind: "timed_out";
+    clock: ClockName;
+    stdout: string;
+    stderr: string;
+} | {
+    kind: "interrupted";
+    stdout: string;
+    stderr: string;
+} | {
+    kind: "spawn_error";
+    detail: string;
+};
+/**
+ * Run one child with a wall-clock timeout. Does not inherit Isolator stdin.
+ */
+export declare function runChild(request: SpawnRequest): Promise<SpawnOutcome>;
+export declare function combinedOutput(stdout: string, stderr: string): string;
+//# sourceMappingURL=run-child.d.ts.map

package/dist/child/run-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../../src/child/run-child.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,YAAY,EAAE,SAAS,CAAC;IACxB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,OAAO,CAAC;IAC/B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,YAAY,GACpB;IACE,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAiBN;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAsHrE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrE"}