stitchkit 0.103.10 → 0.103.12

package/dist/index-f330qqyg.js

@@ -0,0 +1,653 @@
+import {
+  raceAbort
+} from "./index-mbnnw3f2.js";
+
+// src/process/contract.ts
+import { z } from "zod";
+var NativeCommandSettlementSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("exit"),
+    exitCode: z.number().int().nullable(),
+    signal: z.string().nullable()
+  }),
+  z.object({ kind: z.literal("error"), cause: z.unknown() })
+]);
+var NativeCommandOptionsSchema = z.strictObject({
+  executable: z.string().min(1),
+  args: z.array(z.string()).default([]),
+  cwd: z.string().optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  envPolicy: z.enum(["declared-only", "ambient"]).default("declared-only"),
+  signal: z.custom((v) => v instanceof AbortSignal).optional(),
+  timeoutMs: z.number().int().positive().max(2147483647).optional(),
+  maxOutputBytes: z.number().int().positive().optional(),
+  capture: z.boolean().default(false),
+  stdin: z.custom((v) => v instanceof Uint8Array).optional(),
+  maxStdinBytes: z.number().int().positive().default(1024 * 1024),
+  onOutput: z.custom((v) => typeof v === "function").optional(),
+  onLeaderSettled: z.custom((v) => typeof v === "function").optional(),
+  killGraceMs: z.number().int().nonnegative().max(1e4).default(100),
+  cleanupTimeoutMs: z.number().int().positive().max(30000).default(2000)
+}).superRefine((input, ctx) => {
+  if (!input.signal && input.timeoutMs === undefined)
+    ctx.addIssue({ code: "custom", message: "Declare a caller signal or a finite timeout" });
+  if (input.capture && input.maxOutputBytes === undefined)
+    ctx.addIssue({
+      code: "custom",
+      message: "Capture requires a finite combined output budget"
+    });
+  if (input.stdin && input.stdin.byteLength > input.maxStdinBytes)
+    ctx.addIssue({ code: "custom", message: "stdin exceeds maxStdinBytes" });
+});
+var NativeCommandResultSchema = z.object({
+  exitCode: z.number().int().nullable(),
+  signal: z.string().nullable(),
+  stdout: z.instanceof(Uint8Array),
+  stderr: z.instanceof(Uint8Array)
+});
+var NativeCommandLimitReasonSchema = z.enum(["deadline", "output-budget"]);
+
+class NativeCommandError2 extends Error {
+  code;
+  reason;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    if (options?.reason !== undefined && code !== "COMMAND_LIMIT")
+      throw new TypeError("Only COMMAND_LIMIT accepts a limit reason");
+    this.reason = options?.reason === undefined ? undefined : NativeCommandLimitReasonSchema.parse(options.reason);
+    this.name = "NativeCommandError";
+  }
+}
+
+// src/process/group.ts
+function createCommandDeadline(timeoutMs, reason) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+    throw new RangeError("Command deadline must be a positive safe integer");
+  const controller = new AbortController;
+  const deadline = performance.now() + timeoutMs;
+  let timer;
+  const schedule = () => {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0)
+      controller.abort(reason);
+    else
+      timer = setTimeout(schedule, Math.min(remaining, 2147483647));
+  };
+  schedule();
+  return {
+    signal: controller.signal,
+    cancel() {
+      if (timer !== undefined)
+        clearTimeout(timer);
+    }
+  };
+}
+function deniedOnDarwin(error) {
+  return process.platform === "darwin" && error instanceof Error && "code" in error && error.code === "EPERM";
+}
+function signalGroup(pid, signal) {
+  if (pid === undefined)
+    return;
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    if (!(error instanceof Error && ("code" in error) && error.code === "ESRCH"))
+      throw error;
+  }
+}
+function exists(pid) {
+  if (pid === undefined)
+    return false;
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ESRCH")
+      return false;
+    if (deniedOnDarwin(error))
+      return true;
+    throw error;
+  }
+}
+async function signalUntilSettled(pid, signal, deadline) {
+  for (;; ) {
+    try {
+      signalGroup(pid, signal);
+      return;
+    } catch (error) {
+      if (!deniedOnDarwin(error) || performance.now() >= deadline)
+        throw error;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(10, deadline - performance.now())));
+    }
+  }
+}
+async function stopCommandGroup(pid, graceMs, cleanupTimeoutMs = 2000, force = false) {
+  const deadline = performance.now() + graceMs + cleanupTimeoutMs;
+  if (force) {
+    await signalUntilSettled(pid, "SIGKILL", deadline);
+    return;
+  }
+  await signalUntilSettled(pid, "SIGTERM", deadline);
+  const until = performance.now() + graceMs;
+  while (performance.now() < until && exists(pid))
+    await new Promise((resolve) => setTimeout(resolve, Math.min(10, until - performance.now())));
+  await signalUntilSettled(pid, "SIGKILL", deadline);
+}
+function commandCleanupError(cause) {
+  return new NativeCommandError2("COMMAND_CLEANUP", "Command cleanup did not complete", {
+    cause
+  });
+}
+function waitForCommandClose(closed, timeoutMs) {
+  const deadline = createCommandDeadline(timeoutMs, new DOMException("Command settlement timed out", "TimeoutError"));
+  return raceAbort(closed, deadline.signal).finally(() => deadline.cancel());
+}
+
+// src/process/cleanup.ts
+async function cleanupNativeCommand(input) {
+  const cleanup = await Promise.allSettled([
+    input.settle(input.event ?? { kind: "error", cause: input.error }),
+    Promise.resolve().then(() => input.transport?.destroy()),
+    Promise.resolve().then(input.signal).then(async () => {
+      if (!input.transport)
+        return;
+      try {
+        await waitForCommandClose(input.transport.released, input.timeoutMs);
+      } catch (cause) {
+        throw new Error(`Command handles remained open: ${[...input.transport.pendingHandles].join(", ")}`, { cause });
+      }
+    })
+  ]);
+  const failures = cleanup.flatMap((item) => item.status === "rejected" && item.reason !== input.error ? [item.reason] : []);
+  if (failures.length)
+    throw commandCleanupError(new AggregateError([input.error, ...failures], "Command failed and cleanup failed"));
+}
+
+// src/process/command-lifetime.ts
+function createCommandLifetime(input) {
+  const acceptSettlement = (error) => {
+    if (error instanceof NativeCommandError2 && error.code === "COMMAND_CLEANUP")
+      throw error;
+  };
+  return {
+    result: input.result,
+    async terminate() {
+      let refused = false;
+      let refusal;
+      if (!input.finished()) {
+        try {
+          await input.signal();
+        } catch (error) {
+          refused = true;
+          refusal = error;
+          input.controller.abort(error);
+        }
+        try {
+          await waitForCommandClose(input.result, input.cleanupTimeoutMs);
+        } catch (error) {
+          if (!input.finished())
+            input.controller.abort(error);
+        }
+      }
+      await input.result.then(() => {
+        return;
+      }, acceptSettlement);
+      if (refused)
+        throw commandCleanupError(refusal);
+    },
+    async stop() {
+      if (!input.finished())
+        input.controller.abort(new DOMException("Command stopped", "AbortError"));
+      await input.result.then(() => {
+        return;
+      }, acceptSettlement);
+    }
+  };
+}
+
+// src/process/launch.ts
+import { Readable as Readable2 } from "node:stream";
+
+// src/process/owned-child.ts
+import { spawn } from "node:child_process";
+var groups = new WeakSet;
+function spawnOwnedCommand(input) {
+  const child = spawn(input.executable, [...input.args], {
+    cwd: input.cwd,
+    env: input.env,
+    detached: input.group,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  if (input.group)
+    groups.add(child);
+  return child;
+}
+function ownsCommandGroup(child) {
+  return groups.has(child);
+}
+
+// src/process/transport.ts
+import { Readable, Writable } from "node:stream";
+function createCommandTransport(child) {
+  const leader = Promise.withResolvers();
+  const closed = Promise.withResolvers();
+  const released = Promise.withResolvers();
+  const pendingHandles = new Set(["leader", "launcher", "stdout", "stderr"]);
+  const destructors = new Map;
+  let stdout;
+  let stderr;
+  let stdin;
+  let isClosed = false;
+  const release = (name) => {
+    pendingHandles.delete(name);
+    if (pendingHandles.size === 0)
+      released.resolve();
+  };
+  const settled = (event) => {
+    leader.resolve(event);
+    release("leader");
+  };
+  const pipe = (name, source) => {
+    if (isClosed || source.closed)
+      release(name);
+    else
+      source.once("close", () => release(name));
+  };
+  return {
+    child,
+    leader: leader.promise,
+    closed: closed.promise,
+    released: released.promise,
+    pendingHandles,
+    get stdin() {
+      return stdin;
+    },
+    observe(onFailure) {
+      child.on("close", (exitCode, signal) => {
+        isClosed = true;
+        closed.resolve({ exitCode, signal });
+        settled({ kind: "exit", exitCode, signal });
+        pendingHandles.clear();
+        released.resolve();
+      });
+      child.on("error", (cause) => {
+        settled({ kind: "error", cause });
+        onFailure(cause);
+      });
+      child.on("exit", (exitCode, signal) => settled({ kind: "exit", exitCode, signal }));
+      if (child.exitCode !== null || child.signalCode !== null)
+        settled({ kind: "exit", exitCode: child.exitCode, signal: child.signalCode });
+    },
+    capture() {
+      stdout = child.stdout;
+      destructors.set("stdout", () => stdout?.destroy());
+      stderr = child.stderr;
+      destructors.set("stderr", () => stderr?.destroy());
+      const input = "stdin" in child ? child.stdin : undefined;
+      if (input instanceof Writable) {
+        stdin = input;
+        pendingHandles.add("stdin");
+        destructors.set("stdin", () => input.destroy());
+        pipe("stdin", input);
+      }
+      if (stdout instanceof Readable)
+        pipe("stdout", stdout);
+      if (stderr instanceof Readable)
+        pipe("stderr", stderr);
+      if (stdout instanceof Readable && stderr instanceof Readable)
+        release("launcher");
+      return { stdout, stderr };
+    },
+    pipeDestructor(name, destroy) {
+      destructors.set(name, destroy);
+    },
+    destroy() {
+      const failures = [];
+      for (const name of ["stdin", "stdout", "stderr"]) {
+        try {
+          const destroy = destructors.get(name);
+          if (destroy)
+            destroy();
+          else if (name === "stdout")
+            child.stdout.destroy();
+          else if (name === "stderr")
+            child.stderr.destroy();
+          else if ("stdin" in child && child.stdin instanceof Writable)
+            child.stdin.destroy();
+        } catch (cause) {
+          failures.push(cause);
+        }
+      }
+      if (failures.length)
+        throw new AggregateError(failures, "Command pipe teardown failed");
+    }
+  };
+}
+
+// src/process/launch.ts
+function nativeCommandBudgets(options, driver) {
+  const cleanupTimeoutMs = driver?.cleanupTimeoutMs ?? options.cleanupTimeoutMs;
+  const timeoutMs = driver?.timeoutMs ?? options.timeoutMs;
+  for (const [name, value] of [
+    ["cleanup", cleanupTimeoutMs],
+    ["execution", timeoutMs],
+    ["close", driver?.closeTimeoutMs]
+  ])
+    if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0))
+      throw new RangeError(`Command ${name} deadline must be a positive safe integer`);
+  return { cleanupTimeoutMs, timeoutMs };
+}
+var owners = new WeakMap;
+function registerNativeCommandOwner(child, owner) {
+  owners.set(child, owner);
+}
+function nativeCommandOwner(child) {
+  return owners.get(child);
+}
+function outputStream(source, closed, maxBufferedBytes) {
+  if (source instanceof Readable2)
+    return {
+      bytes: source,
+      destroy() {
+        source.destroy();
+      }
+    };
+  const queue = [];
+  let buffered = 0;
+  let ended = false;
+  let failure;
+  let wake = Promise.withResolvers();
+  const notify = () => {
+    wake.resolve();
+    wake = Promise.withResolvers();
+  };
+  source.on("data", (chunk) => {
+    if (ended || failure)
+      return;
+    if (!(chunk instanceof Uint8Array)) {
+      failure = new TypeError("Expected binary command output");
+      notify();
+      return;
+    }
+    if (chunk.byteLength === 0)
+      return;
+    const available = maxBufferedBytes - buffered;
+    if (available > 0) {
+      const kept = Uint8Array.from(chunk.subarray(0, available));
+      queue.push(kept);
+      buffered += kept.byteLength;
+    }
+    if (chunk.byteLength > available)
+      failure = new NativeCommandError2("COMMAND_LIMIT", "Command output budget exceeded", {
+        reason: "output-budget"
+      });
+    notify();
+  });
+  closed.then(() => {
+    ended = true;
+    notify();
+  });
+  return {
+    bytes: {
+      async* [Symbol.asyncIterator]() {
+        for (;; ) {
+          const chunk = queue.shift();
+          if (chunk) {
+            buffered -= chunk.byteLength;
+            yield chunk;
+          } else if (failure)
+            throw failure;
+          else if (ended)
+            return;
+          else
+            await wake.promise;
+        }
+      }
+    },
+    destroy() {
+      ended = true;
+      queue.length = 0;
+      buffered = 0;
+      notify();
+      source.destroy();
+    }
+  };
+}
+function launchNativeCommand(options, driver, onSpawn, onFailure, onInputFailure, onAcquired) {
+  let native;
+  const launch = driver?.launch;
+  if (!launch)
+    native = spawnOwnedCommand({
+      executable: options.executable,
+      args: options.args,
+      cwd: options.cwd,
+      env: options.envPolicy === "ambient" ? { ...process.env, ...options.env } : options.env ?? {},
+      group: driver?.group ?? true
+    });
+  const child = launch ? launch() : native;
+  if (!child)
+    throw new Error("Native command launcher did not supply a process");
+  const transport = createCommandTransport(child);
+  onAcquired(transport);
+  transport.observe(onFailure);
+  const pipes = transport.capture();
+  const stdout = outputStream(pipes.stdout, transport.closed, driver?.maxBufferedBytes ?? 1024 * 1024);
+  transport.pipeDestructor("stdout", () => stdout.destroy());
+  const stderr = outputStream(pipes.stderr, transport.closed, driver?.maxBufferedBytes ?? 1024 * 1024);
+  transport.pipeDestructor("stderr", () => stderr.destroy());
+  const stdin = transport.stdin;
+  stdin?.on("error", (error) => {
+    if (!(("code" in error) && error.code === "EPIPE"))
+      onInputFailure(error);
+  });
+  return {
+    ...transport,
+    stdout: stdout.bytes,
+    stderr: stderr.bytes,
+    start() {
+      if (native)
+        onSpawn?.(native);
+      stdin?.end(options.stdin);
+    }
+  };
+}
+
+// src/process/leader-settlement.ts
+function createLeaderCloseDeadline(leader, timeoutMs, controller) {
+  let finished = false;
+  let deadline;
+  const expired = () => controller.abort(deadline?.signal.reason);
+  if (timeoutMs !== undefined)
+    leader.then(() => {
+      if (finished)
+        return;
+      deadline = createCommandDeadline(timeoutMs, commandCleanupError(new Error("Command close deadline exceeded after leader exit")));
+      deadline.signal.addEventListener("abort", expired, { once: true });
+    });
+  return () => {
+    finished = true;
+    deadline?.cancel();
+    deadline?.signal.removeEventListener("abort", expired);
+  };
+}
+function createLeaderSettlement(options, signal) {
+  let pending;
+  return (event) => {
+    if (pending)
+      return pending;
+    pending = (async () => {
+      if (!options.onLeaderSettled)
+        return;
+      const controller = new AbortController;
+      const deadline = createCommandDeadline(options.cleanupTimeoutMs, new Error("Leader settlement deadline exceeded"));
+      const expired = () => controller.abort(deadline.signal.reason);
+      if (deadline.signal.aborted)
+        expired();
+      else
+        deadline.signal.addEventListener("abort", expired, { once: true });
+      const abort = () => controller.abort(signal.reason);
+      if (!signal.aborted)
+        signal.addEventListener("abort", abort, { once: true });
+      try {
+        await raceAbort(Promise.resolve(options.onLeaderSettled(event, controller.signal)), controller.signal);
+      } catch (cause) {
+        if (signal.aborted && cause === signal.reason)
+          throw cause;
+        throw commandCleanupError(new AggregateError([event, cause], "Leader settlement failed"));
+      } finally {
+        deadline.cancel();
+        deadline.signal.removeEventListener("abort", expired);
+        signal.removeEventListener("abort", abort);
+        controller.abort(new Error("Leader settlement completed"));
+      }
+    })();
+    pending.catch(() => {
+      return;
+    });
+    return pending;
+  };
+}
+
+// src/process/start-failure.ts
+async function failedCommandStart(cause, cleanup) {
+  const error = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
+    cause
+  });
+  await cleanup(error);
+  throw error;
+}
+
+// src/process/command-owner.ts
+function startNativeCommand(input, onSpawn, driver) {
+  const options = NativeCommandOptionsSchema.parse(input);
+  options.signal?.throwIfAborted();
+  if (process.platform === "win32" && driver?.group !== false)
+    throw new NativeCommandError2("COMMAND_UNAVAILABLE", "POSIX process groups are required");
+  const { cleanupTimeoutMs, timeoutMs } = nativeCommandBudgets(options, driver);
+  const controller = new AbortController;
+  const abort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", abort, { once: true });
+  if (options.signal?.aborted)
+    abort();
+  const deadline = timeoutMs === undefined ? undefined : createCommandDeadline(timeoutMs, new NativeCommandError2("COMMAND_LIMIT", "Command deadline exceeded", {
+    reason: "deadline"
+  }));
+  const expired = () => controller.abort(deadline?.signal.reason);
+  if (deadline?.signal.aborted)
+    expired();
+  else
+    deadline?.signal.addEventListener("abort", expired, { once: true });
+  const settle = createLeaderSettlement({ ...options, cleanupTimeoutMs }, controller.signal);
+  let acquired;
+  let finished = false;
+  const completion = Promise.withResolvers();
+  const result = completion.promise.finally(() => {
+    finished = true;
+  });
+  result.catch(() => {
+    return;
+  });
+  const signalOwned = (force = driver?.force) => {
+    const child = acquired?.child;
+    if (!child)
+      return Promise.resolve();
+    return driver?.group === false || !ownsCommandGroup(child) ? Promise.resolve().then(() => {
+      if (child.exitCode === null && child.signalCode === null && !child.kill("SIGKILL"))
+        throw new Error("Command leader termination was refused");
+    }) : stopCommandGroup(child.pid, options.killGraceMs, cleanupTimeoutMs, force);
+  };
+  const owner = createCommandLifetime({
+    result,
+    controller,
+    finished: () => finished,
+    signal: () => signalOwned(true),
+    cleanupTimeoutMs
+  });
+  let spawnFailure;
+  let launched;
+  try {
+    launched = launchNativeCommand(options, driver, onSpawn, (error) => {
+      spawnFailure = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
+        cause: error
+      });
+      controller.abort(spawnFailure);
+    }, (error) => controller.abort(error), (transport) => {
+      acquired = transport;
+      registerNativeCommandOwner(transport.child, owner);
+    });
+  } catch (cause) {
+    deadline?.cancel();
+    deadline?.signal.removeEventListener("abort", expired);
+    options.signal?.removeEventListener("abort", abort);
+    controller.abort(cause);
+    failedCommandStart(cause, (error) => cleanupNativeCommand({
+      error,
+      transport: acquired,
+      settle,
+      event: { kind: "error", cause },
+      signal: () => signalOwned(),
+      timeoutMs: cleanupTimeoutMs
+    })).then(completion.resolve, completion.reject);
+    return owner;
+  }
+  const stdout = [];
+  const stderr = [];
+  let total = 0;
+  const { stdout: output, stderr: errorOutput, leader, closed } = launched;
+  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs, controller);
+  const drain = async (stream, channel, captured) => {
+    for await (const chunk of stream) {
+      controller.signal.throwIfAborted();
+      if (!(chunk instanceof Uint8Array))
+        throw new TypeError("Expected binary command output");
+      total += chunk.byteLength;
+      if (options.maxOutputBytes !== undefined && total > options.maxOutputBytes)
+        throw new NativeCommandError2("COMMAND_LIMIT", "Command output budget exceeded", {
+          reason: "output-budget"
+        });
+      if (options.capture)
+        captured.push(Uint8Array.from(chunk));
+      if (options.onOutput)
+        await raceAbort(Promise.resolve().then(() => {
+          controller.signal.throwIfAborted();
+          return options.onOutput?.(chunk, channel, controller.signal);
+        }), controller.signal);
+    }
+  };
+  const run = (async () => {
+    try {
+      launched.start();
+      const drains = Promise.all([
+        drain(output, "stdout", stdout),
+        drain(errorOutput, "stderr", stderr)
+      ]);
+      await raceAbort(Promise.all([drains, leader.then(settle)]), controller.signal);
+      const status = await raceAbort(closed, controller.signal);
+      if (spawnFailure !== undefined)
+        throw spawnFailure;
+      return { ...status, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr) };
+    } catch (error) {
+      controller.abort(error);
+      await cleanupNativeCommand({
+        error,
+        transport: acquired,
+        settle,
+        signal: () => signalOwned(),
+        timeoutMs: cleanupTimeoutMs
+      });
+      throw error;
+    } finally {
+      finished = true;
+      cancelCloseDeadline();
+      deadline?.cancel();
+      deadline?.signal.removeEventListener("abort", expired);
+      options.signal?.removeEventListener("abort", abort);
+      controller.abort(new Error("Command completed"));
+    }
+  })();
+  run.then(completion.resolve, completion.reject);
+  return owner;
+}
+
+export { NativeCommandError2, stopCommandGroup, spawnOwnedCommand, ownsCommandGroup, nativeCommandOwner, startNativeCommand };