stitchkit 0.2.0 → 0.4.0

package/dist/index-0ma1eqv4.js

@@ -0,0 +1,1007 @@
+import {
+  jsonSchemaFields,
+  toJsonSchema
+} from "./index-0ed3bx43.js";
+import {
+  isWithinDir
+} from "./index-x3fcszf8.js";
+import {
+  formatZodError,
+  normalizeError,
+  validateHandlerOutput
+} from "./index-vhdvv00d.js";
+import {
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-kzfs85xp.js";
+import {
+  isRecord
+} from "./index-809wc1tt.js";
+
+// src/tools/coerce.ts
+import { z } from "zod";
+function needsJsonCoercion(field) {
+  if (field instanceof z.ZodArray || field instanceof z.ZodObject || field instanceof z.ZodRecord) {
+    return true;
+  }
+  if (field instanceof z.ZodOptional || field instanceof z.ZodNullable || field instanceof z.ZodDefault) {
+    return needsJsonCoercion(field.unwrap());
+  }
+  return false;
+}
+function coerceJsonArgs(args, schema) {
+  if (!(schema instanceof z.ZodObject))
+    return args;
+  const shape = schema.shape;
+  const out = {};
+  for (const [key, value] of Object.entries(args)) {
+    const field = shape[key];
+    if (field && needsJsonCoercion(field) && typeof value === "string") {
+      try {
+        out[key] = safeJsonParse(value);
+        continue;
+      } catch {}
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// src/tools/flatten.ts
+import { z as z2 } from "zod";
+function flattenDiscriminatedUnion(union) {
+  const discriminator = union.def.discriminator;
+  const literalValues = [];
+  const fieldToVariants = new Map;
+  const fieldSchemas = {};
+  for (const opt of union.def.options) {
+    if (!(opt instanceof z2.ZodObject)) {
+      throw new Error(`flattenDiscriminatedUnion: variant for discriminator '${discriminator}' is not a ZodObject`);
+    }
+    const discField = opt.shape[discriminator];
+    if (!(discField instanceof z2.ZodLiteral)) {
+      throw new Error(`flattenDiscriminatedUnion: discriminator field '${discriminator}' must be z.literal()`);
+    }
+    const [literalValue] = discField.def.values;
+    if (typeof literalValue !== "string") {
+      throw new Error("flattenDiscriminatedUnion: discriminator literal must be a string");
+    }
+    literalValues.push(literalValue);
+    for (const [key, field] of Object.entries(opt.shape)) {
+      if (key === discriminator)
+        continue;
+      const variants = fieldToVariants.get(key) ?? [];
+      variants.push(literalValue);
+      fieldToVariants.set(key, variants);
+      if (!(key in fieldSchemas)) {
+        fieldSchemas[key] = field instanceof z2.ZodOptional ? field : z2.optional(field);
+      }
+    }
+  }
+  const [firstLiteral, ...restLiterals] = literalValues;
+  if (!firstLiteral) {
+    throw new Error("flattenDiscriminatedUnion: union has no options");
+  }
+  const shape = {
+    [discriminator]: z2.enum([firstLiteral, ...restLiterals])
+  };
+  for (const [key, field] of Object.entries(fieldSchemas)) {
+    const variants = fieldToVariants.get(key) ?? [];
+    const hint = `Required if ${discriminator} = ${variants.join(" | ")}`;
+    shape[key] = field.describe(hint);
+  }
+  return z2.object(shape);
+}
+
+// src/tools/mount.ts
+import { z as z4 } from "zod";
+
+// src/tools/schema.ts
+import { z as z3 } from "zod";
+function objectShapeKeys(schema) {
+  return schema instanceof z3.ZodObject ? Object.keys(schema.shape) : [];
+}
+function mergeSchemas(paramsSchema, inputSchema) {
+  if (paramsSchema && !(paramsSchema instanceof z3.ZodObject)) {
+    throw new Error("Tool params schema must be a z.object()");
+  }
+  const paramsObject = paramsSchema instanceof z3.ZodObject ? paramsSchema : undefined;
+  if (!inputSchema) {
+    return paramsObject ?? z3.object({});
+  }
+  if (inputSchema instanceof z3.ZodObject) {
+    if (paramsObject) {
+      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
+      if (conflicts.length > 0) {
+        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
+      }
+    }
+    return z3.object({ ...paramsObject?.shape ?? {}, ...inputSchema.shape });
+  }
+  return paramsObject ? z3.intersection(paramsObject, inputSchema) : inputSchema;
+}
+
+// src/tools/execute.ts
+function toolResultFromError(err) {
+  const appErr = normalizeError(err);
+  return {
+    ok: false,
+    code: appErr.code,
+    details: appErr.details ?? { message: appErr.message },
+    ...appErr.hint && { hint: appErr.hint }
+  };
+}
+async function executeToolMethod(method, toolName, rawArgs, context, hooks, lifecycle, coerceJson = false) {
+  const startedAt = Date.now();
+  const finish = async (result) => {
+    await hooks?.afterToolCall?.(toolName, rawArgs, result, Date.now() - startedAt, context);
+    return result;
+  };
+  if (hooks?.beforeToolCall) {
+    try {
+      await hooks.beforeToolCall(toolName, rawArgs, context);
+    } catch (err) {
+      return finish(toolResultFromError(err));
+    }
+  }
+  const paramKeys = new Set(objectShapeKeys(method.paramsSchema));
+  let paramArgs = {};
+  let inputArgs = {};
+  for (const [key, value] of Object.entries(rawArgs)) {
+    if (isUnsafeKey(key))
+      continue;
+    if (paramKeys.has(key))
+      paramArgs[key] = value;
+    else
+      inputArgs[key] = value;
+  }
+  if (coerceJson) {
+    paramArgs = coerceJsonArgs(paramArgs, method.paramsSchema);
+    inputArgs = coerceJsonArgs(inputArgs, method.inputSchema);
+  }
+  let params;
+  if (method.paramsSchema) {
+    const result = method.paramsSchema.safeParse(paramArgs);
+    if (!result.success) {
+      return finish({
+        ok: false,
+        code: "VALIDATION_ERROR",
+        details: { message: `Invalid params: ${formatZodError(result.error)}` }
+      });
+    }
+    params = result.data;
+  }
+  let input;
+  if (method.inputSchema) {
+    const result = method.inputSchema.safeParse(inputArgs);
+    if (!result.success) {
+      return finish({
+        ok: false,
+        code: "VALIDATION_ERROR",
+        details: { message: `Invalid input: ${formatZodError(result.error)}` }
+      });
+    }
+    input = result.data;
+  }
+  try {
+    const ctx = { ...context, params, input, source: context.source };
+    if (lifecycle?.beforeHandle) {
+      await lifecycle.beforeHandle(ctx, method);
+    }
+    let data = await method.handler(ctx);
+    if (lifecycle?.afterHandle) {
+      const transformed = await lifecycle.afterHandle(ctx, data, method);
+      if (transformed !== undefined)
+        data = transformed;
+    }
+    if (method.outputSchema) {
+      const checked = validateHandlerOutput(method.outputSchema, data);
+      if (!checked.ok) {
+        return finish({
+          ok: false,
+          code: "INTERNAL_SERVER_ERROR",
+          details: { message: checked.message }
+        });
+      }
+      data = checked.data;
+    }
+    const output = (data === undefined || data === null) && !method.outputSchema ? { status: "ok" } : data;
+    return finish({ ok: true, data: output });
+  } catch (err) {
+    return finish(toolResultFromError(err));
+  }
+}
+
+// src/tools/names.ts
+var SINGULAR_EXCEPTIONS = new Set([
+  "analytics",
+  "status",
+  "stats",
+  "settings",
+  "media",
+  "progress",
+  "news"
+]);
+function singularize(name) {
+  if (SINGULAR_EXCEPTIONS.has(name))
+    return name;
+  if (name.endsWith("ies"))
+    return `${name.slice(0, -3)}y`;
+  if (name.endsWith("s") && !name.endsWith("ss"))
+    return name.slice(0, -1);
+  return name;
+}
+function toToolName(serviceName, methodName) {
+  const normalized = serviceName.replace(/-/g, "_");
+  const singular = singularize(normalized);
+  if (methodName === "list")
+    return `list_${normalized}`;
+  if (methodName === "get")
+    return `get_${singular}`;
+  if (methodName === "create")
+    return `create_${singular}`;
+  if (methodName === "update")
+    return `update_${singular}`;
+  if (methodName === "delete")
+    return `delete_${singular}`;
+  const snake = methodName.replace(/([A-Z])/g, "_$1").toLowerCase();
+  return `${snake}_${singular}`.replace(/^_/, "");
+}
+
+// src/tools/mount.ts
+function applyExtend(base, extra) {
+  if (base instanceof z4.ZodObject) {
+    const conflicts = Object.keys(extra).filter((key) => (key in base.shape));
+    if (conflicts.length > 0) {
+      throw new Error(`Tool extend conflict: ${conflicts.join(", ")} already declared by the contract`);
+    }
+    return z4.object({ ...extra, ...base.shape });
+  }
+  return z4.intersection(z4.object(extra), base);
+}
+function collectTools(service, transport, config = {}) {
+  const { extend, flattenUnionInput = false } = config;
+  const tools = [];
+  for (const [methodName, method] of Object.entries(service.methods)) {
+    if (transport === "CLI") {
+      if (!method.expose?.includes("CLI"))
+        continue;
+    } else if (method.expose && !method.expose.includes(transport)) {
+      continue;
+    }
+    if (method.multipart)
+      continue;
+    const name = method.toolName ?? toToolName(service.name, methodName);
+    let baseSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
+    if (flattenUnionInput && baseSchema instanceof z4.ZodDiscriminatedUnion) {
+      baseSchema = flattenDiscriminatedUnion(baseSchema);
+    }
+    const shouldExtend = !!extend && (!extend.filter || extend.filter(service, method));
+    const schema = shouldExtend && extend ? applyExtend(baseSchema, extend.schema) : baseSchema;
+    tools.push({ method, name, schema, shouldExtend });
+  }
+  return tools;
+}
+function createToolRunner(config) {
+  const extendKeys = config.extend ? new Set(Object.keys(config.extend.schema)) : null;
+  return async (tool, rawArgs) => {
+    let extraContext = {};
+    if (tool.shouldExtend && config.extend) {
+      extraContext = await config.extend.resolve(rawArgs);
+    }
+    const cleanArgs = extendKeys ? Object.fromEntries(Object.entries(rawArgs).filter(([key]) => !extendKeys.has(key))) : rawArgs;
+    return executeToolMethod(tool.method, tool.name, cleanArgs, { ...config.context, ...extraContext, source: config.source }, config.hooks, config.lifecycle, config.coerceJsonArgs ?? true);
+  };
+}
+function formatToolError(result, toolName, errorHint) {
+  const err = { error: result.code };
+  if (result.details)
+    err.details = result.details;
+  const hints = [];
+  if (result.hint)
+    hints.push(result.hint);
+  if (errorHint && toolName) {
+    const global = errorHint(toolName, result.code);
+    if (global)
+      hints.push(global);
+  }
+  if (hints.length > 0)
+    err._hint = hints.join(" ");
+  return err;
+}
+
+// src/tools/cli-args.ts
+import { z as z5 } from "zod";
+var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help"]);
+var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir"]);
+function unwrap(field) {
+  if (field instanceof z5.ZodOptional || field instanceof z5.ZodNullable || field instanceof z5.ZodDefault) {
+    return unwrap(field.unwrap());
+  }
+  return field;
+}
+function classify(field) {
+  if (field instanceof z5.ZodBoolean)
+    return "boolean";
+  if (field instanceof z5.ZodNumber)
+    return "number";
+  if (field instanceof z5.ZodBigInt)
+    return "bigint";
+  if (field instanceof z5.ZodDate)
+    return "date";
+  if (field instanceof z5.ZodEnum)
+    return "enum";
+  if (field instanceof z5.ZodArray)
+    return "array";
+  if (field instanceof z5.ZodObject)
+    return "object";
+  if (field instanceof z5.ZodString || field instanceof z5.ZodLiteral)
+    return "string";
+  return "other";
+}
+function describeSchemaFields(schema) {
+  const fields = new Map;
+  if (!(schema instanceof z5.ZodObject))
+    return fields;
+  for (const [name, raw] of Object.entries(schema.shape)) {
+    const base = unwrap(raw);
+    const kind = classify(base);
+    if (kind === "array" && base instanceof z5.ZodArray) {
+      fields.set(name, { kind, elementKind: classify(unwrap(base.element)) });
+    } else {
+      fields.set(name, { kind });
+    }
+  }
+  return fields;
+}
+function parseBool(value) {
+  const v = value.toLowerCase();
+  if (v === "false" || v === "0" || v === "no" || v === "off")
+    return false;
+  return true;
+}
+function coerceScalar(kind, value) {
+  switch (kind) {
+    case "boolean":
+      return parseBool(value);
+    case "number": {
+      const n = Number(value);
+      return value.trim() !== "" && !Number.isNaN(n) ? n : value;
+    }
+    case "bigint":
+      try {
+        return BigInt(value);
+      } catch {
+        return value;
+      }
+    case "date": {
+      const d = new Date(value);
+      return Number.isNaN(d.getTime()) ? value : d;
+    }
+    default:
+      return value;
+  }
+}
+function looseCoerce(value) {
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  const n = Number(value);
+  return value.trim() !== "" && !Number.isNaN(n) ? n : value;
+}
+function looksLikeJson(value) {
+  const t = value.trim();
+  return t.startsWith("[") || t.startsWith("{");
+}
+function coerceField(info, values) {
+  const last = values[values.length - 1] ?? "";
+  if (!info)
+    return values.length > 1 ? values : last;
+  if (info.kind === "array") {
+    if (values.length === 1 && looksLikeJson(last))
+      return last;
+    return values.map((v) => coerceScalar(info.elementKind ?? "string", v));
+  }
+  if (info.kind === "object")
+    return last;
+  return coerceScalar(info.kind, last);
+}
+function setNested(target, path, value) {
+  if (path.some(isUnsafeKey))
+    return;
+  let node = target;
+  for (let i = 0;i < path.length - 1; i++) {
+    const key = path[i];
+    if (key === undefined)
+      return;
+    const next = node[key];
+    if (isRecord(next)) {
+      node = next;
+    } else {
+      const created = {};
+      node[key] = created;
+      node = created;
+    }
+  }
+  const leaf = path[path.length - 1];
+  if (leaf !== undefined)
+    node[leaf] = value;
+}
+function parseCliArgs(argv, schema) {
+  const options = {
+    json: false,
+    wait: false,
+    quiet: false,
+    dryRun: false,
+    help: false
+  };
+  const rest = [];
+  for (let i = 0;i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === undefined)
+      continue;
+    if (tok === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (tok.startsWith("--")) {
+      const eq = tok.indexOf("=");
+      const name = eq >= 0 ? tok.slice(2, eq) : tok.slice(2);
+      const inline = eq >= 0 ? tok.slice(eq + 1) : undefined;
+      if (BOOL_OPTIONS.has(name)) {
+        const on = inline === undefined ? true : parseBool(inline);
+        if (name === "dry-run")
+          options.dryRun = on;
+        else if (name === "json")
+          options.json = on;
+        else if (name === "wait")
+          options.wait = on;
+        else if (name === "quiet")
+          options.quiet = on;
+        else if (name === "help")
+          options.help = on;
+        continue;
+      }
+      if (VALUE_OPTIONS.has(name)) {
+        const value = inline ?? argv[++i];
+        if (value !== undefined) {
+          if (name === "wait-timeout") {
+            const n = Number(value);
+            if (!Number.isNaN(n))
+              options.waitTimeout = n;
+          } else if (name === "output-dir") {
+            options.outputDir = value;
+          }
+        }
+        continue;
+      }
+    }
+    rest.push(tok);
+  }
+  const fields = describeSchemaFields(schema);
+  const flags = new Map;
+  const boolFlags = new Map;
+  const positionals = [];
+  const pushFlag = (name, value) => {
+    const existing = flags.get(name);
+    if (existing)
+      existing.push(value);
+    else
+      flags.set(name, [value]);
+  };
+  for (let i = 0;i < rest.length; i++) {
+    const tok = rest[i];
+    if (tok === undefined)
+      continue;
+    if (!tok.startsWith("--")) {
+      positionals.push(tok);
+      continue;
+    }
+    const eq = tok.indexOf("=");
+    const name = eq >= 0 ? tok.slice(2, eq) : tok.slice(2);
+    let value = eq >= 0 ? tok.slice(eq + 1) : undefined;
+    if (value === undefined && name.startsWith("no-") && fields.get(name.slice(3))?.kind === "boolean") {
+      boolFlags.set(name.slice(3), false);
+      continue;
+    }
+    const info = fields.get(name);
+    if (value === undefined) {
+      if (info?.kind === "boolean") {
+        boolFlags.set(name, true);
+        continue;
+      }
+      const next = rest[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        value = next;
+        i++;
+      } else {
+        boolFlags.set(name, true);
+        continue;
+      }
+    }
+    pushFlag(name, value);
+  }
+  const toolArgs = {};
+  const fillable = [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name);
+  let pi = 0;
+  for (const key of fillable) {
+    if (pi >= positionals.length)
+      break;
+    if (flags.has(key))
+      continue;
+    const value = positionals[pi++];
+    if (value !== undefined)
+      toolArgs[key] = coerceField(fields.get(key), [value]);
+  }
+  for (const [key, value] of boolFlags) {
+    if (isUnsafeKey(key))
+      continue;
+    toolArgs[key] = value;
+  }
+  for (const [key, values] of flags) {
+    if (key.includes(".")) {
+      setNested(toolArgs, key.split("."), looseCoerce(values[values.length - 1] ?? ""));
+      continue;
+    }
+    if (isUnsafeKey(key))
+      continue;
+    toolArgs[key] = coerceField(fields.get(key), values);
+  }
+  return { toolArgs, options };
+}
+
+// src/tools/cli-format.ts
+var DEFAULT_EXIT_CODES = {
+  VALIDATION_ERROR: 1,
+  BAD_REQUEST: 1,
+  UNAUTHORIZED: 2,
+  FORBIDDEN: 3,
+  NOT_FOUND: 4,
+  CONFLICT: 5,
+  RATE_LIMITED: 6,
+  TIMEOUT: 7,
+  INTERNAL_SERVER_ERROR: 1
+};
+function emitResult(result, writers, opts) {
+  if (result.ok) {
+    if (result.data === undefined)
+      return 0;
+    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text}
+`);
+    return 0;
+  }
+  const error = formatToolError(result, opts.toolName, opts.errorHint);
+  writers.stderr(`${JSON.stringify(error, null, 2)}
+`);
+  const codes = opts.exitCodes ?? DEFAULT_EXIT_CODES;
+  return codes[result.code] ?? 1;
+}
+
+// src/tools/wait-core.ts
+var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
+var DEFAULT_TIMEOUT = 600;
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+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 startedAt = Date.now();
+  for (let attempt = 0;; attempt++) {
+    const state = await params.poll();
+    if (params.done(state))
+      return { state, timedOut: false };
+    const elapsedSec = (Date.now() - startedAt) / 1000;
+    params.onTick?.(attempt + 1, elapsedSec);
+    if (elapsedSec >= timeoutSec)
+      return { state, timedOut: true };
+    const waitSec = backoff[Math.min(attempt, backoff.length - 1)] ?? lastBackoff;
+    await sleep(waitSec * 1000);
+  }
+}
+
+// src/tools/cli-wait.ts
+var DEFAULT_TIMEOUT2 = 600;
+async function pollUntilDone(params) {
+  const { initial, wait, call } = params;
+  if (!initial.ok)
+    return initial;
+  if (wait.done(initial.data))
+    return initial;
+  const pollArgs = wait.poll(initial.data);
+  if (!pollArgs)
+    return initial;
+  const timeoutSec = params.timeoutSec ?? wait.timeout ?? DEFAULT_TIMEOUT2;
+  const { state, timedOut } = await pollUntil({
+    poll: () => call(wait.tool, pollArgs),
+    done: (result) => !result.ok || wait.done(result.data),
+    backoff: wait.backoff,
+    timeoutSec,
+    sleepFn: params.sleepFn,
+    onTick: params.onTick
+  });
+  if (timedOut) {
+    return {
+      ok: false,
+      code: "TIMEOUT",
+      details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
+    };
+  }
+  return state;
+}
+
+// src/tools/cli.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import process from "node:process";
+
+// src/internal/secure-fetch.ts
+import { lookup } from "node:dns/promises";
+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 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;
+    return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 100 && b >= 64 && b <= 127;
+  }
+  if (family === 6) {
+    const lower = normalized.toLowerCase();
+    const mapped = mappedIpv4FromIpv6(lower);
+    if (mapped)
+      return isPrivateIp(mapped);
+    if (lower === "::1" || lower === "::")
+      return true;
+    if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb") || lower.startsWith("fc") || lower.startsWith("fd")) {
+      return true;
+    }
+    return false;
+  }
+  return false;
+}
+async function assertPublicUrl(url) {
+  assertHttpUrl(url);
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (!host)
+    throw new Error("refusing to fetch a URL with no host");
+  if (isIP(host)) {
+    if (isPrivateIp(host))
+      throw new Error("refusing to fetch a private address");
+    return;
+  }
+  if (NUMERIC_HOST.test(host)) {
+    throw new Error("refusing to fetch a non-canonical numeric host");
+  }
+  if (host === "localhost" || host.endsWith(".local") || host.endsWith(".internal")) {
+    throw new Error("refusing to fetch an internal host");
+  }
+  const records = await lookup(host, { all: true });
+  for (const record of records) {
+    if (isPrivateIp(record.address)) {
+      throw new Error("refusing to fetch a host that resolves to a private address");
+    }
+  }
+}
+async function fetchGuarded(start, allowPrivate) {
+  let url = start;
+  for (let hop = 0;hop <= MAX_REDIRECTS; hop++) {
+    if (allowPrivate)
+      assertHttpUrl(url);
+    else
+      await assertPublicUrl(url);
+    const res = await fetch(url, { redirect: "manual" });
+    if (res.status < 300 || res.status >= 400)
+      return res;
+    const location = res.headers.get("location");
+    if (!location)
+      return res;
+    await res.body?.cancel();
+    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/tools/cli.ts
+var GLOBAL_OPTIONS = [
+  ["--json", "Emit raw JSON on stdout (for piping / scripts)"],
+  ["--wait", "Block-poll an async result to a terminal state"],
+  ["--wait-timeout <s>", "Override the --wait timeout in seconds"],
+  ["--output-dir <dir>", "Download result media into a directory"],
+  ["--quiet", "Suppress non-essential stderr output"],
+  ["--dry-run", "Print the resolved call without executing it"],
+  ["--help, -h", "Show help for a command"]
+];
+async function readPipedStdin() {
+  if (process.stdin.isTTY)
+    return null;
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  return text.length > 0 ? text : null;
+}
+function typeLabel(schema) {
+  if (Array.isArray(schema.enum))
+    return schema.enum.join("|");
+  if (schema.type === "array")
+    return "value…";
+  if (typeof schema.type === "string")
+    return schema.type;
+  return "value";
+}
+function padRight(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function summarize(desc) {
+  const firstLine = desc.split(`
+`)[0]?.trim() ?? "";
+  const firstSentence = firstLine.split(". ")[0]?.trim() ?? firstLine;
+  const max = 72;
+  return firstSentence.length > max ? `${firstSentence.slice(0, max - 1).trimEnd()}…` : firstSentence;
+}
+function looseCoerceValue(value) {
+  if (Array.isArray(value))
+    return value.map(looseCoerceValue);
+  if (typeof value !== "string")
+    return value;
+  if (value === "true")
+    return true;
+  if (value === "false")
+    return false;
+  const n = Number(value);
+  return value.trim() !== "" && !Number.isNaN(n) ? n : value;
+}
+function passthroughBase(value) {
+  if (isRecord(value))
+    return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = safeJsonParse(value);
+      if (isRecord(parsed))
+        return parsed;
+    } catch {}
+  }
+  return;
+}
+function collectPassthrough(toolArgs, field, knownKeys) {
+  const known = new Set(knownKeys);
+  const bag = {};
+  for (const key of Object.keys(toolArgs)) {
+    if (key === field || known.has(key))
+      continue;
+    bag[key] = looseCoerceValue(toolArgs[key]);
+    delete toolArgs[key];
+  }
+  if (Object.keys(bag).length === 0)
+    return;
+  const base = passthroughBase(toolArgs[field]);
+  toolArgs[field] = base ? { ...base, ...bag } : bag;
+}
+function renderTopHelp(name, version, tools) {
+  const lines = [
+    `${name} ${version}`,
+    "",
+    `Usage: ${name} <command> [args] [--flags]`,
+    "",
+    "Commands:"
+  ];
+  const width = Math.max(0, ...[...tools.keys()].map((k) => k.length));
+  for (const [command, tool] of tools) {
+    lines.push(`  ${padRight(command, width)}  ${summarize(tool.method.desc)}`);
+  }
+  lines.push("", "Global options:");
+  const optWidth = Math.max(...GLOBAL_OPTIONS.map(([flag]) => flag.length));
+  for (const [flag, desc] of GLOBAL_OPTIONS)
+    lines.push(`  ${padRight(flag, optWidth)}  ${desc}`);
+  lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
+  return `${lines.join(`
+`)}
+`;
+}
+function renderCommandHelp(name, command, tool) {
+  const lines = [tool.method.desc, "", `Usage: ${name} ${command} [args] [--flags]`, ""];
+  let fields = [];
+  try {
+    fields = jsonSchemaFields(toJsonSchema(tool.schema, "input"));
+  } catch {
+    lines.push("(arguments: pass a JSON object — this command has a complex schema)", "");
+  }
+  if (fields.length > 0) {
+    lines.push("Arguments:");
+    const width = Math.max(...fields.map((f) => f.name.length));
+    for (const f of fields) {
+      const req = f.required ? " (required)" : "";
+      const desc = f.description ? ` — ${f.description}` : "";
+      lines.push(`  --${padRight(f.name, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
+    }
+    lines.push("");
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
+async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes) {
+  const root = resolve(dir);
+  await mkdir(root, { recursive: true });
+  for (const file of files) {
+    try {
+      const res = await fetchGuarded(new URL(file.url), allowPrivate);
+      if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+      const buffer = await readCapped(res, maxBytes);
+      if (!buffer)
+        throw new Error(`file exceeds the ${maxBytes}-byte cap`);
+      const target = resolve(root, basename(file.name));
+      if (!isWithinDir(root, target))
+        throw new Error("download name escapes the output dir");
+      await writeFile(target, buffer);
+      if (!quiet)
+        stderr(`saved ${target} (${(buffer.length / 1024).toFixed(0)}KB)
+`);
+    } catch (err) {
+      stderr(`failed to download ${file.url}: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+  }
+}
+async function createCli(config) {
+  const stdout = config.stdout ?? ((text) => void process.stdout.write(text));
+  const stderr = config.stderr ?? ((text) => void process.stderr.write(text));
+  const exit = config.exit ?? ((code) => void process.exit(code));
+  const argv = config.argv ?? process.argv.slice(2);
+  const readStdin = config.stdin ?? readPipedStdin;
+  const auth = config.auth === undefined ? undefined : await config.auth;
+  const services = typeof config.services === "function" ? config.services(auth) : config.services;
+  const context = config.context?.(auth);
+  const tools = new Map;
+  for (const service of services) {
+    for (const mountable of collectTools(service, "CLI")) {
+      if (tools.has(mountable.name)) {
+        throw new Error(`Duplicate CLI command "${mountable.name}" across mounted services`);
+      }
+      tools.set(mountable.name, mountable);
+    }
+  }
+  const runTool = createToolRunner({
+    source: "cli",
+    context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    errorHint: config.errorHint,
+    coerceJsonArgs: config.coerceJsonArgs
+  });
+  const [command, ...commandArgv] = argv;
+  if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+    stdout(renderTopHelp(config.name, config.version, tools));
+    return exit(0);
+  }
+  if (command === "--version" || command === "version") {
+    stdout(`${config.name} ${config.version}
+`);
+    return exit(0);
+  }
+  const tool = tools.get(command);
+  if (!tool) {
+    stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
+`);
+    return exit(1);
+  }
+  const { toolArgs, options } = parseCliArgs(commandArgv, tool.schema);
+  if (options.help) {
+    stdout(renderCommandHelp(config.name, command, tool));
+    return exit(0);
+  }
+  const fields = jsonSchemaFields(safeInputSchema(tool));
+  const firstUnset = fields.find((f) => !(f.name in toolArgs) && f.schema.type !== "boolean");
+  if (firstUnset) {
+    const piped = await readStdin();
+    if (piped !== null)
+      toolArgs[firstUnset.name] = piped;
+  }
+  const passthroughField = config.passthrough?.[command];
+  if (passthroughField) {
+    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(tool.schema));
+  }
+  if (options.dryRun) {
+    stdout(`${JSON.stringify({ command, args: toolArgs }, null, 2)}
+`);
+    return exit(0);
+  }
+  let result;
+  try {
+    result = await runTool(tool, toolArgs);
+  } catch (err) {
+    result = toolResultFromError(err);
+  }
+  const waitConfig = config.wait?.[command];
+  if (options.wait && waitConfig) {
+    result = await pollUntilDone({
+      initial: result,
+      wait: waitConfig,
+      call: async (toolName, args) => {
+        const pollTool = tools.get(toolName);
+        if (!pollTool) {
+          return {
+            ok: false,
+            code: "NOT_FOUND",
+            details: { message: `--wait: no command "${toolName}" to poll` }
+          };
+        }
+        return runTool(pollTool, args);
+      },
+      timeoutSec: options.waitTimeout,
+      onTick: options.quiet ? undefined : (attempt) => stderr(`waiting… (poll ${attempt})
+`)
+    });
+  }
+  if (options.outputDir && result.ok && config.download) {
+    await downloadResults(config.download(result.data), options.outputDir, stderr, options.quiet, config.allowPrivateDownloadHosts ?? false, config.maxDownloadBytes ?? DEFAULT_DOWNLOAD_MAX_BYTES);
+  }
+  const exitCode = emitResult(result, { stdout, stderr }, {
+    json: options.json,
+    toolName: command,
+    errorHint: config.errorHint,
+    exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
+  });
+  return exit(exitCode);
+}
+function safeInputSchema(tool) {
+  try {
+    return toJsonSchema(tool.schema, "input");
+  } catch {
+    return {};
+  }
+}
+
+export { coerceJsonArgs, toolResultFromError, flattenDiscriminatedUnion, collectTools, createToolRunner, formatToolError, fetchGuarded, readCapped, parseCliArgs, DEFAULT_EXIT_CODES, emitResult, pollUntil, pollUntilDone, createCli };