stitchkit 0.103.9 → 0.103.11

package/dist/index-32jkwkdm.js

@@ -0,0 +1,565 @@
+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) || Date.now() >= deadline)
+        throw error;
+      await new Promise((resolve) => setTimeout(resolve, Math.min(10, deadline - Date.now())));
+    }
+  }
+}
+async function stopCommandGroup(pid, graceMs, cleanupTimeoutMs = 2000, force = false) {
+  const deadline = Date.now() + graceMs + cleanupTimeoutMs;
+  if (force) {
+    await signalUntilSettled(pid, "SIGKILL", deadline);
+    return;
+  }
+  await signalUntilSettled(pid, "SIGTERM", deadline);
+  const until = Date.now() + graceMs;
+  while (Date.now() < until && exists(pid))
+    await new Promise((resolve) => setTimeout(resolve, Math.min(10, until - Date.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/launch.ts
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+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 Readable)
+    return {
+      bytes: source,
+      released: new Promise((resolve) => source.closed ? resolve() : source.once("close", resolve)),
+      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;
+        }
+      }
+    },
+    released: closed.then(() => {
+      return;
+    }),
+    destroy() {
+      ended = true;
+      queue.length = 0;
+      buffered = 0;
+      notify();
+      source.destroy();
+    }
+  };
+}
+function launchNativeCommand(options, driver, onSpawn, onFailure, onInputFailure) {
+  let native;
+  const launch = driver?.launch;
+  if (!launch)
+    native = spawn(options.executable, options.args, {
+      cwd: options.cwd,
+      env: options.envPolicy === "ambient" ? { ...process.env, ...options.env } : options.env ?? {},
+      detached: driver?.group ?? true,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  const child = launch ? launch() : native;
+  if (!child)
+    throw new Error("Native command launcher did not supply a process");
+  const pendingHandles = new Set(["leader"]);
+  const leader = new Promise((resolve) => {
+    child.on("exit", (exitCode, signal) => resolve({ kind: "exit", exitCode, signal }));
+    child.on("error", (cause) => resolve({ kind: "error", cause }));
+    if (child.exitCode !== null || child.signalCode !== null)
+      resolve({ kind: "exit", exitCode: child.exitCode, signal: child.signalCode });
+  });
+  const closed = new Promise((resolve) => {
+    child.on("error", onFailure);
+    child.on("close", (exitCode, signal) => resolve({ exitCode, signal }));
+  });
+  const stdout = outputStream(child.stdout, closed, driver?.maxBufferedBytes ?? 1024 * 1024);
+  const stderr = outputStream(child.stderr, closed, driver?.maxBufferedBytes ?? 1024 * 1024);
+  const stdin = "stdin" in child && child.stdin instanceof Writable ? child.stdin : undefined;
+  const handles = [
+    ["stdout", stdout.released],
+    ["stderr", stderr.released]
+  ];
+  if (stdin)
+    handles.push([
+      "stdin",
+      new Promise((resolve) => stdin.closed ? resolve() : stdin.once("close", resolve))
+    ]);
+  const released = Promise.all([
+    leader.then(() => pendingHandles.delete("leader")),
+    ...handles.map(([name, released]) => {
+      pendingHandles.add(name);
+      return released.then(() => pendingHandles.delete(name));
+    }),
+    ...child.stdout instanceof Readable && child.stderr instanceof Readable ? [] : [closed.then(() => pendingHandles.delete("launcher"))]
+  ]);
+  if (!(child.stdout instanceof Readable && child.stderr instanceof Readable))
+    pendingHandles.add("launcher");
+  stdin?.on("error", (error) => {
+    if (!(("code" in error) && error.code === "EPIPE"))
+      onInputFailure(error);
+  });
+  return {
+    child,
+    stdout: stdout.bytes,
+    stderr: stderr.bytes,
+    leader,
+    closed,
+    released,
+    pendingHandles,
+    start() {
+      if (native)
+        onSpawn?.(native);
+      stdin?.end(options.stdin);
+    },
+    destroy() {
+      const failures = [];
+      for (const handle of [stdin, stdout, stderr]) {
+        try {
+          handle?.destroy();
+        } catch (cause) {
+          failures.push(cause);
+        }
+      }
+      if (failures.length)
+        throw new AggregateError(failures, "Command pipe teardown failed");
+    }
+  };
+}
+
+// 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
+function failedCommandStart(cause, settle) {
+  const error = new NativeCommandError2("COMMAND_UNAVAILABLE", "Command could not start", {
+    cause
+  });
+  const result = (async () => {
+    try {
+      await settle({ kind: "error", cause });
+    } catch (cleanup) {
+      throw commandCleanupError(new AggregateError([error, cleanup], "Command failed and cleanup failed"));
+    }
+    throw error;
+  })();
+  result.catch(() => {
+    return;
+  });
+  return {
+    result,
+    async stop() {
+      await result.catch((failure) => {
+        if (failure instanceof NativeCommandError2 && failure.code === "COMMAND_CLEANUP")
+          throw failure;
+      });
+    }
+  };
+}
+
+// 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 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));
+  } catch (cause) {
+    deadline?.cancel();
+    deadline?.signal.removeEventListener("abort", expired);
+    options.signal?.removeEventListener("abort", abort);
+    controller.abort(cause);
+    return failedCommandStart(cause, settle);
+  }
+  const stdout = [];
+  const stderr = [];
+  let total = 0;
+  let finished = false;
+  const {
+    child,
+    stdout: output,
+    stderr: errorOutput,
+    leader,
+    closed,
+    released,
+    pendingHandles
+  } = launched;
+  const cancelCloseDeadline = createLeaderCloseDeadline(leader, driver?.closeTimeoutMs, controller);
+  const signalOwned = (force = driver?.force) => driver?.group === false || driver?.launch && child.pid === undefined ? 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 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 result = (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);
+      const cleanup = await Promise.allSettled([
+        settle({ kind: "error", cause: error }),
+        Promise.resolve().then(() => launched.destroy()),
+        signalOwned().then(async () => {
+          try {
+            await waitForCommandClose(released, cleanupTimeoutMs);
+          } catch (cause) {
+            throw new Error(`Command handles remained open: ${[...pendingHandles].join(", ")}`, {
+              cause
+            });
+          }
+        })
+      ]);
+      const failures = cleanup.flatMap((item) => item.status === "rejected" && item.reason !== error ? [item.reason] : []);
+      if (failures.length) {
+        throw commandCleanupError(new AggregateError([error, ...failures], "Command failed and cleanup failed"));
+      }
+      throw error;
+    } finally {
+      finished = true;
+      cancelCloseDeadline();
+      deadline?.cancel();
+      deadline?.signal.removeEventListener("abort", expired);
+      options.signal?.removeEventListener("abort", abort);
+      controller.abort(new Error("Command completed"));
+    }
+  })();
+  result.catch(() => {
+    return;
+  });
+  const owner = {
+    result,
+    async terminate() {
+      let refused = false;
+      let refusal;
+      if (!finished) {
+        try {
+          await signalOwned(true);
+        } catch (error) {
+          refused = true;
+          refusal = error;
+          controller.abort(error);
+        }
+        try {
+          await waitForCommandClose(result, cleanupTimeoutMs);
+        } catch (error) {
+          if (!finished)
+            controller.abort(error);
+        }
+      }
+      await result.then(() => {
+        return;
+      }, (error) => {
+        if (error instanceof NativeCommandError2 && error.code === "COMMAND_CLEANUP")
+          throw error;
+      });
+      if (refused)
+        throw commandCleanupError(refusal);
+    },
+    async stop() {
+      if (!finished)
+        controller.abort(new DOMException("Command stopped", "AbortError"));
+      await result.then(() => {
+        return;
+      }, (error) => {
+        if (error instanceof NativeCommandError2 && error.code === "COMMAND_CLEANUP")
+          throw error;
+      });
+    }
+  };
+  registerNativeCommandOwner(child, owner);
+  return owner;
+}
+
+export { NativeCommandError2, stopCommandGroup, nativeCommandOwner, startNativeCommand };