stitchkit 0.104.1 → 0.105.0

package/dist/{index-6drst9sg.js → index-ksfagmyz.js}

@@ -1,13 +1,13 @@
 import {
   validateDeclaredOutput
-} from "./index-kb8styz3.js";
+} from "./index-rpzewktb.js";
 import {
   toolResultFromError,
   toolErrorFromResult
-} from "./index-2vnh05w4.js";
+} from "./index-2k91mewf.js";
 import {
   coerceJsonArgs2
-} from "./index-9pw0a51a.js";
+} from "./index-6yxhe58g.js";
 import {
   jsonSchemaFields
 } from "./index-ct75c3at.js";
@@ -15,17 +15,24 @@ import {
   objectShapeKeys,
   assertUniqueToolName,
   buildToolPresentationSchema
-} from "./index-77nxk6ay.js";
+} from "./index-r393tnfp.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-2hyavjjj.js";
+} from "./index-wbhdzxar.js";
+import {
+  fetchGuarded,
+  readCapped
+} from "./index-3h0ztg0z.js";
 import {
   isWithinDir2
 } from "./index-5cc6r990.js";
+import {
+  sleep
+} from "./index-eemvahkc.js";
 import {
   collectToolSurface
-} from "./index-a0zzh8ak.js";
+} from "./index-pz3y6b6g.js";
 import {
   formatZodError2
 } from "./index-1eeqpadm.js";
@@ -726,6 +733,9 @@ function routeCliArgv2(argv, defaultCommand) {
   };
 }
 
+// src/tools/cli/args.ts
+import { z as z2 } from "zod";
+
 // src/tools/cli/args-view.ts
 function resolveCliView(flags, ascending) {
   if (flags.size === 0) {
@@ -839,7 +849,6 @@ function readCliTokens(argv, fields, config) {
       continue;
     }
     if (tok === "-h") {
-      appendCliOptionValue(frameworkFlags, "help", "true", { kind: "boolean" });
       options.help = true;
       continue;
     }
@@ -885,9 +894,11 @@ function readCliTokens(argv, fields, config) {
       const separate = value === undefined ? separateBoolValue(argv[i + 1]) : undefined;
       if (separate !== undefined)
         i++;
-      appendCliOptionValue(frameworkFlags, name, value ?? String(separate ?? true), {
-        kind: "boolean"
-      });
+      if (name !== "help") {
+        appendCliOptionValue(frameworkFlags, name, value ?? String(separate ?? true), {
+          kind: "boolean"
+        });
+      }
       const enabled = value === undefined ? separate ?? true : parseReservedBool(name, value);
       if (name === "dry-run")
         options.dryRun = enabled;
@@ -900,7 +911,7 @@ function readCliTokens(argv, fields, config) {
       else if (name === "ascending")
         ascending = enabled;
       else
-        options.help = enabled;
+        options.help = options.help || enabled;
       continue;
     }
     if (option.globalKind === "value") {
@@ -1022,6 +1033,11 @@ function parseCliArgs2(argv, schema, config = {}) {
     options.view = view;
   return { toolArgs: buildToolArgs(tokens, fields, config.positionals), options };
 }
+function refuseGlobalOption(issue) {
+  const field = issue?.path[0];
+  const where = typeof field === "string" ? `--${field}` : "application option";
+  throw new CliArgumentError2(`${where}: ${issue?.message ?? "invalid value"}`);
+}
 function extractCliGlobalOptions2(argv, schema) {
   if (schema === undefined)
     return { argv: [...argv], globals: {} };
@@ -1062,13 +1078,17 @@ function extractCliGlobalOptions2(argv, schema) {
   for (const [name, values] of raw) {
     args[name] = coerceField(fields.get(name), values, `--${name}`);
   }
-  const parsed = schema.safeParse(coerceJsonArgs2(args, schema));
-  if (!parsed.success) {
-    const issue = parsed.error.issues[0];
-    const field = issue?.path[0];
-    const where = typeof field === "string" ? `--${field}` : "application option";
-    throw new CliArgumentError2(`${where}: ${issue?.message ?? "invalid value"}`);
+  let coerced;
+  try {
+    coerced = coerceJsonArgs2(args, schema);
+  } catch (error) {
+    if (error instanceof z2.ZodError)
+      refuseGlobalOption(error.issues[0]);
+    throw error;
   }
+  const parsed = schema.safeParse(coerced);
+  if (!parsed.success)
+    refuseGlobalOption(parsed.error.issues[0]);
   return { argv: rest, globals: parsed.data };
 }
 
@@ -1229,35 +1249,11 @@ class WaitTimeoutError extends Error {
     this.name = "WaitTimeoutError";
   }
 }
-var defaultSleep = (ms, signal) => {
-  signal?.throwIfAborted();
-  return new Promise((resolve, reject) => {
-    let settled = false;
-    const settle = (action) => {
-      if (settled)
-        return;
-      settled = true;
-      signal?.removeEventListener("abort", onAbort);
-      action();
-    };
-    const timer = setTimeout(() => {
-      settle(resolve);
-    }, ms);
-    timer.unref?.();
-    const onAbort = () => {
-      clearTimeout(timer);
-      settle(() => reject(signal?.reason ?? new Error("aborted")));
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-    if (signal?.aborted)
-      onAbort();
-  });
-};
 async function pollUntil(params) {
   const backoff = params.backoff?.length ? params.backoff : DEFAULT_BACKOFF;
   const lastBackoff = backoff[backoff.length - 1] ?? 5;
   const timeoutSec = params.timeoutSec ?? DEFAULT_TIMEOUT;
-  const sleep = params.sleepFn ?? defaultSleep;
+  const pause = params.sleepFn ?? sleep;
   const now = params.nowFn ?? (() => performance.now());
   const startedAt = now();
   const deadline = startedAt + timeoutSec * 1000;
@@ -1299,7 +1295,7 @@ async function pollUntil(params) {
     if (elapsedSec >= timeoutSec)
       return { state, timedOut: true };
     const waitSec = backoff[Math.min(attempt, backoff.length - 1)] ?? lastBackoff;
-    await sleep(Math.min(waitSec * 1000, Math.max(0, deadline - now())), params.signal);
+    await pause(Math.min(waitSec * 1000, Math.max(0, deadline - now())), params.signal);
   }
 }
 function runWaitOperation(params) {
@@ -1459,305 +1455,6 @@ function createCliIo(config) {
 // src/tools/cli/download.ts
 import { basename, resolve } from "node:path";
 
-// src/internal/secure-fetch.ts
-import { lookup } from "node:dns/promises";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
-import { isIP } from "node:net";
-var NUMERIC_HOST = /^(0x[0-9a-f]+|[0-9.]+)$/i;
-var MAX_REDIRECTS = 5;
-function assertHttpUrl(url) {
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`refusing to fetch a non-http(s) URL (${url.protocol})`);
-  }
-}
-function mappedIpv4FromIpv6(ip) {
-  const rest = ip.startsWith("::ffff:") ? ip.slice("::ffff:".length) : ip.startsWith("0:0:0:0:0:ffff:") ? ip.slice("0:0:0:0:0:ffff:".length) : null;
-  if (rest === null)
-    return null;
-  if (isIP(rest) === 4)
-    return rest;
-  const [hiRaw, loRaw, extra] = rest.split(":");
-  if (hiRaw === undefined || loRaw === undefined || extra !== undefined)
-    return null;
-  if (!/^[0-9a-f]{1,4}$/i.test(hiRaw) || !/^[0-9a-f]{1,4}$/i.test(loRaw))
-    return null;
-  const hi = Number.parseInt(hiRaw, 16);
-  const lo = Number.parseInt(loRaw, 16);
-  return [hi >> 8, hi & 255, lo >> 8, lo & 255].join(".");
-}
-function ipv6Words(ip) {
-  const halves = ip.toLowerCase().split("::");
-  if (halves.length > 2)
-    return null;
-  const head = halves[0] ? halves[0].split(":") : [];
-  const tail = halves[1] ? halves[1].split(":") : [];
-  const missing = 8 - head.length - tail.length;
-  if (halves.length === 1 && missing !== 0 || missing < 0)
-    return null;
-  const parts = halves.length === 2 ? [...head, ...Array(missing).fill("0"), ...tail] : head;
-  if (parts.length !== 8)
-    return null;
-  const words = [];
-  for (const part of parts) {
-    if (!/^[0-9a-f]{1,4}$/i.test(part))
-      return null;
-    words.push(Number.parseInt(part, 16));
-  }
-  return words;
-}
-function isPrivateIp(ip) {
-  const normalized = ip.replace(/^\[|\]$/g, "");
-  const family = isIP(normalized);
-  if (family === 4) {
-    const [a, b] = normalized.split(".").map(Number);
-    if (a === undefined || b === undefined)
-      return true;
-    const value = normalized.split(".").map(Number).reduce((total, octet) => total * 256 + octet, 0);
-    const inCidr = (base, prefix) => {
-      const baseValue = base.split(".").map(Number).reduce((total, octet) => total * 256 + octet, 0);
-      const size = 2 ** (32 - prefix);
-      return value >= baseValue && value < baseValue + size;
-    };
-    const blockedRanges = [
-      ["0.0.0.0", 8],
-      ["10.0.0.0", 8],
-      ["100.64.0.0", 10],
-      ["127.0.0.0", 8],
-      ["169.254.0.0", 16],
-      ["172.16.0.0", 12],
-      ["192.0.0.0", 24],
-      ["192.0.2.0", 24],
-      ["192.31.196.0", 24],
-      ["192.52.193.0", 24],
-      ["192.88.99.0", 24],
-      ["192.168.0.0", 16],
-      ["192.175.48.0", 24],
-      ["198.18.0.0", 15],
-      ["198.51.100.0", 24],
-      ["203.0.113.0", 24],
-      ["224.0.0.0", 4],
-      ["240.0.0.0", 4]
-    ];
-    return blockedRanges.some(([base, prefix]) => inCidr(base, prefix));
-  }
-  if (family === 6) {
-    const lower = normalized.toLowerCase();
-    const mapped = mappedIpv4FromIpv6(lower);
-    if (mapped)
-      return isPrivateIp(mapped);
-    const words = ipv6Words(lower);
-    if (!words)
-      return true;
-    const [first, second, third] = words;
-    if (first === undefined || second === undefined || third === undefined)
-      return true;
-    return first === 0 || first === 100 && second === 65435 && third === 1 || first === 256 && second === 0 || first === 8193 && (second <= 511 || second === 3512) || first === 8194 || first === 16383 || first === 24320 || (first & 65024) === 64512 || (first & 65472) === 65152 || (first & 65280) === 65280;
-  }
-  return false;
-}
-function raceWithAbort(promise, signal) {
-  if (signal.aborted) {
-    promise.catch(() => {
-      return;
-    });
-    return Promise.reject(signal.reason ?? new Error("aborted"));
-  }
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(signal.reason ?? new Error("aborted"));
-    signal.addEventListener("abort", onAbort, { once: true });
-    promise.then((value) => {
-      signal.removeEventListener("abort", onAbort);
-      resolve(value);
-    }, (error) => {
-      signal.removeEventListener("abort", onAbort);
-      reject(error);
-    });
-  });
-}
-async function assertPublicUrl(url, signal) {
-  await resolvePublicAddress(url, signal);
-}
-async function fetchGuarded(start, allowPrivate, options = {}) {
-  const timeoutMs = options.timeoutMs ?? 15000;
-  const bodyTimeoutMs = options.bodyTimeoutMs ?? 120000;
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    throw new Error("timeoutMs must be positive");
-  }
-  if (!Number.isFinite(bodyTimeoutMs) || bodyTimeoutMs <= 0) {
-    throw new Error("bodyTimeoutMs must be positive");
-  }
-  const controller = new AbortController;
-  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
-  const headerTimer = setTimeout(() => {
-    controller.abort(new Error(`fetch did not produce response headers within ${timeoutMs}ms`));
-  }, timeoutMs);
-  headerTimer.unref?.();
-  let settled = false;
-  try {
-    let url = start;
-    for (let hop = 0;hop <= MAX_REDIRECTS; hop++) {
-      if (allowPrivate)
-        assertHttpUrl(url);
-      else
-        await assertPublicUrl(url, signal);
-      const res = await fetch(url, { redirect: "manual", signal });
-      const location = res.status >= 300 && res.status < 400 ? res.headers.get("location") : null;
-      if (location === null) {
-        settled = true;
-        clearTimeout(headerTimer);
-        const bodyTimer = setTimeout(() => {
-          controller.abort(new Error(`fetch body was not consumed within ${bodyTimeoutMs}ms`));
-        }, bodyTimeoutMs);
-        bodyTimer.unref?.();
-        return res;
-      }
-      await res.body?.cancel();
-      url = new URL(location, url);
-    }
-    throw new Error("too many redirects");
-  } finally {
-    if (!settled)
-      clearTimeout(headerTimer);
-  }
-}
-
-class PrivateAddressRefusal extends Error {
-  name = "PrivateAddressRefusal";
-}
-async function resolvePublicAddress(url, signal) {
-  assertHttpUrl(url);
-  const host = url.hostname.replace(/^\[|\]$/g, "");
-  if (!host)
-    throw new Error("refusing to fetch a URL with no host");
-  const ipFamily = isIP(host);
-  if (ipFamily) {
-    if (isPrivateIp(host))
-      throw new PrivateAddressRefusal("refusing to fetch a private address");
-    return { address: host, family: ipFamily === 6 ? 6 : 4 };
-  }
-  if (NUMERIC_HOST.test(host)) {
-    throw new PrivateAddressRefusal("refusing to fetch a non-canonical numeric host");
-  }
-  if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
-    throw new PrivateAddressRefusal("refusing to fetch an internal host");
-  }
-  const pending = lookup(host, { all: true });
-  const records = signal ? await raceWithAbort(pending, signal) : await pending;
-  for (const record of records) {
-    if (isPrivateIp(record.address)) {
-      throw new PrivateAddressRefusal("refusing to fetch a host that resolves to a private address");
-    }
-  }
-  const record = records[0];
-  if (!record)
-    throw new Error("public hostname resolved to no addresses");
-  return { address: record.address, family: record.family === 6 ? 6 : 4 };
-}
-async function fetchPinnedDocument(start, options) {
-  if (!Number.isInteger(options.maxBytes) || options.maxBytes < 1) {
-    throw new Error("maxBytes must be a positive integer");
-  }
-  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
-    throw new Error("timeoutMs must be positive");
-  }
-  let url = start;
-  const maxRedirects = options.maxRedirects ?? MAX_REDIRECTS;
-  if (!Number.isInteger(maxRedirects) || maxRedirects < 0) {
-    throw new Error("maxRedirects must be a non-negative integer");
-  }
-  const signal = AbortSignal.timeout(options.timeoutMs);
-  for (let hop = 0;hop <= maxRedirects; hop++) {
-    if (options.requireHttps && url.protocol !== "https:") {
-      throw new Error("document URL and every redirect must use https");
-    }
-    if (url.username || url.password) {
-      throw new Error("document URL cannot contain credentials");
-    }
-    const resolved = await resolvePublicAddress(url, signal);
-    const transport = url.protocol === "https:" ? httpsRequest : httpRequest;
-    const response = await new Promise((resolve, reject) => {
-      const request = transport({
-        protocol: url.protocol,
-        hostname: resolved.address,
-        family: resolved.family,
-        port: url.port || undefined,
-        path: `${url.pathname}${url.search}`,
-        method: "GET",
-        signal,
-        servername: url.hostname,
-        headers: {
-          host: url.host,
-          accept: "application/json",
-          ...options.headers
-        }
-      }, (incoming) => {
-        const headers = new Headers;
-        for (const [name, value] of Object.entries(incoming.headers)) {
-          if (Array.isArray(value)) {
-            for (const item of value)
-              headers.append(name, item);
-          } else if (value !== undefined) {
-            headers.set(name, value);
-          }
-        }
-        const chunks = [];
-        let total = 0;
-        incoming.on("data", (chunk) => {
-          total += chunk.byteLength;
-          if (total > options.maxBytes) {
-            incoming.destroy(new Error("response body exceeds configured byte limit"));
-            return;
-          }
-          chunks.push(chunk);
-        });
-        incoming.once("error", reject);
-        incoming.once("end", () => {
-          const body = new Uint8Array(total);
-          let offset = 0;
-          for (const chunk of chunks) {
-            body.set(chunk, offset);
-            offset += chunk.byteLength;
-          }
-          resolve({ status: incoming.statusCode ?? 0, headers, body, url });
-        });
-      });
-      request.once("error", reject);
-      request.end();
-    });
-    if (response.status < 300 || response.status >= 400)
-      return response;
-    const location = response.headers.get("location");
-    if (!location)
-      return response;
-    url = new URL(location, url);
-  }
-  throw new Error("too many redirects");
-}
-async function readCapped(res, max) {
-  const reader = res.body?.getReader();
-  if (!reader)
-    return Buffer.alloc(0);
-  const chunks = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      total += value.length;
-      if (total > max) {
-        await reader.cancel();
-        return null;
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  return Buffer.concat(chunks);
-}
-
 // src/internal/write-download.ts
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
@@ -1836,8 +1533,11 @@ function constraintLabel(schema) {
   ];
   for (const [keyword, label] of bounds) {
     const bound = schema[keyword];
-    if (typeof bound === "number")
-      limits.push(`${label}${bound}`);
+    if (typeof bound !== "number")
+      continue;
+    if (schema.type === "integer" && Math.abs(bound) === Number.MAX_SAFE_INTEGER)
+      continue;
+    limits.push(`${label}${bound}`);
   }
   const compositions = [
     ["anyOf", "any of", " | "],
@@ -2418,4 +2118,4 @@ async function createCli2(config) {
   return runManagedInvocation(session, route);
 }
 
-export { fetchGuarded, PrivateAddressRefusal, fetchPinnedDocument, readCapped, WaitTimeoutError, runWaitOperation, defineCliCommand2, DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };
+export { WaitTimeoutError, runWaitOperation, defineCliCommand2, DEFAULT_EXIT_CODES2, cliExitCode2, emitResult2, CliArgumentError2, cliInvocationResult2, createCliInvoker2, routeCliArgv2, parseCliArgs2, extractCliGlobalOptions2, renderCliView2, pollUntilDone2, createCli2 };

package/dist/index-m616f0yz.js

@@ -0,0 +1,120 @@
+import {
+  closeAfter
+} from "./index-b56nnscm.js";
+
+// src/internal/bounded-file-read.ts
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+class BoundedFileReadError extends Error {
+  code;
+  observation;
+  constructor(code, message, observation, options) {
+    super(message, options);
+    this.code = code;
+    this.observation = observation;
+    this.name = "BoundedFileReadError";
+  }
+}
+var observationOf = (info) => ({
+  dev: info.dev,
+  ino: info.ino,
+  size: info.size,
+  nlink: info.nlink,
+  mtimeMs: info.mtimeMs,
+  ctimeMs: info.ctimeMs
+});
+function missingCode(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
+}
+async function openChecked(target, options, openDescriptor) {
+  if (options.rejectSymlinks && !constants.O_NOFOLLOW)
+    throw new BoundedFileReadError("FILE_UNSUPPORTED", "strict leaf nofollow is unavailable");
+  const flags = constants.O_RDONLY | (options.rejectSymlinks ? constants.O_NOFOLLOW ?? 0 : 0) | (constants.O_NONBLOCK ?? 0);
+  let handle;
+  try {
+    handle = await openDescriptor(target, flags);
+  } catch (error) {
+    if (options.rejectSymlinks && missingCode(error) === "ELOOP")
+      throw new BoundedFileReadError("FILE_UNSAFE_LINK", "managed file leaf is a symlink", undefined, { cause: error });
+    throw error;
+  }
+  try {
+    const before = await handle.stat();
+    if (!before.isFile())
+      throw new BoundedFileReadError("FILE_NOT_REGULAR", "managed path is not a regular file");
+    if (options.singleLink && before.nlink !== 1)
+      throw new BoundedFileReadError("FILE_UNSAFE_LINK", "managed file has multiple links", observationOf(before));
+    return { handle, before };
+  } catch (error) {
+    await handle.close().catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+function openRegularFile(target, options = {}) {
+  return openChecked(target, options, open);
+}
+var tooLarge = (maxBytes, observation) => new BoundedFileReadError("FILE_TOO_LARGE", `file exceeds the ${maxBytes}-byte cap`, observation);
+async function readBoundedFile(target, maxBytes, options = {}, openDescriptor = open) {
+  options.signal?.throwIfAborted();
+  const { handle, before } = await openChecked(target, options, openDescriptor);
+  return closeAfter(handle, async () => {
+    try {
+      options.signal?.throwIfAborted();
+      if (before.size > maxBytes)
+        throw tooLarge(maxBytes);
+      const bytes = await readHandle(handle, maxBytes, options.signal);
+      const after = await handle.stat();
+      if (options.stable && (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.nlink !== after.nlink || bytes.length !== after.size))
+        throw new BoundedFileReadError("FILE_CHANGED", "managed file changed during read");
+      options.signal?.throwIfAborted();
+      return { bytes, observation: observationOf(after) };
+    } catch (error) {
+      if (error instanceof BoundedFileReadError && error.code === "FILE_TOO_LARGE") {
+        const current = await handle.stat().catch(() => {
+          return;
+        });
+        if (current?.isFile() && current.dev === before.dev && current.ino === before.ino)
+          throw tooLarge(maxBytes, observationOf(current));
+      }
+      throw error;
+    }
+  });
+}
+async function readHandle(handle, maxBytes, signal) {
+  const chunks = [];
+  let total = 0;
+  let ended = false;
+  while (!ended) {
+    const capacity = Math.min(64 * 1024, maxBytes + 1 - total);
+    if (capacity <= 0)
+      throw tooLarge(maxBytes);
+    const chunk = new Uint8Array(capacity);
+    let filled = 0;
+    while (filled < capacity) {
+      signal?.throwIfAborted();
+      const { bytesRead } = await handle.read(chunk, filled, capacity - filled);
+      if (bytesRead === 0) {
+        ended = true;
+        break;
+      }
+      filled += bytesRead;
+      total += bytesRead;
+      if (total > maxBytes)
+        throw tooLarge(maxBytes);
+    }
+    if (filled > 0)
+      chunks.push(chunk.subarray(0, filled));
+  }
+  signal?.throwIfAborted();
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+
+export { BoundedFileReadError, openRegularFile, readBoundedFile };