stitchkit 0.92.0 → 0.94.0

package/dist/{index-7n145nbe.js → index-n6hxg8as.js}

@@ -3,39 +3,149 @@ import {
 } from "./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-2c2bjw3s.js";
+} from "./index-vcvkq30w.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-mzvgxp0n.js";
+} from "./index-2cr1cqhn.js";
 import {
   toolErrorFromResult,
   toolResultFromError
-} from "./index-yn8remb1.js";
-import {
-  formatZodError,
-  validateDeclaredOutput
-} from "./index-e0znv5gn.js";
+} from "./index-j05z5gn4.js";
 import {
   coerceJsonArgs
-} from "./index-7zbps32p.js";
+} from "./index-1zbbzgfh.js";
 import {
   assertUniqueToolName,
   buildToolPresentationSchema,
   objectShapeKeys
-} from "./index-h9etkkyk.js";
+} from "./index-dydjcp8z.js";
 import {
   jsonSchemaFields
-} from "./index-cby4ar3v.js";
+} from "./index-eqqvgdb3.js";
+import {
+  validateDeclaredOutput
+} from "./index-znfs20ss.js";
+import {
+  formatZodError
+} from "./index-p5r7qpdd.js";
 import {
   isUnsafeKey,
   safeJsonParse
 } from "./index-kzfs85xp.js";
 import {
   isRecord
-} from "./index-77fekveh.js";
+} from "./index-hffjpmq9.js";
+
+// src/tools/cli/command.ts
+function defineCliCommand(definition) {
+  return definition;
+}
+function cliCommandReturnsResult(definition) {
+  return definition.output !== undefined;
+}
+function cliCommandSuccessExitCode(definition, data) {
+  const successExitCode = definition.exitCode?.(data) ?? 0;
+  if (!Number.isSafeInteger(successExitCode) || successExitCode < 0 || successExitCode > 255) {
+    throw new Error("CLI success exit code must be an integer from 0 to 255");
+  }
+  return successExitCode;
+}
+function prepareCliCommandEmission(definition, result, options) {
+  if (!result.ok || definition.output === undefined) {
+    return { result, successExitCode: 0 };
+  }
+  try {
+    const successExitCode = cliCommandSuccessExitCode(definition, result.data);
+    const presentation = definition.present?.({ result: result.data, options });
+    if (presentation !== undefined && typeof presentation !== "string") {
+      throw new Error("CLI result presenter must return a string");
+    }
+    return { result, presentation, successExitCode };
+  } catch (error) {
+    return {
+      result: toolResultFromError(new Error("CLI result policy failed", { cause: error })),
+      successExitCode: 0
+    };
+  }
+}
+function cliCommandPresentationSchema(definition) {
+  return buildToolPresentationSchema({
+    inputSchema: definition.input,
+    unrepresentable: "any"
+  });
+}
+async function executeCliCommand(definition, rawArgs, options, writers, coerceJson, globals = {}) {
+  let parsed;
+  try {
+    parsed = definition.input.safeParse(coerceJson ? coerceJsonArgs(rawArgs, definition.input) : rawArgs);
+  } catch (error) {
+    return toolResultFromError(error);
+  }
+  if (!parsed.success) {
+    return {
+      ok: false,
+      code: "VALIDATION_ERROR",
+      details: { message: `Invalid input: ${formatZodError(parsed.error)}` }
+    };
+  }
+  try {
+    const data = await definition.handler({
+      input: parsed.data,
+      options,
+      globals,
+      ...writers
+    });
+    const checked = validateDeclaredOutput(definition.output, data);
+    if (!checked.ok) {
+      return {
+        ok: false,
+        code: "INTERNAL_SERVER_ERROR",
+        details: { message: checked.message }
+      };
+    }
+    return { ok: true, data: checked.data };
+  } catch (error) {
+    return toolResultFromError(error);
+  }
+}
+
+// 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,
+  WAIT_FAILED: 1,
+  INTERNAL_SERVER_ERROR: 1
+};
+function cliExitCode(result, exitCodes) {
+  if (result.ok)
+    return 0;
+  const codes = { ...DEFAULT_EXIT_CODES, ...exitCodes };
+  return Object.hasOwn(codes, result.code) ? codes[result.code] ?? 1 : 1;
+}
+function emitResult(result, writers, opts) {
+  if (result.ok) {
+    if (result.data === undefined)
+      return 0;
+    const text2 = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text2}
+`);
+    return 0;
+  }
+  const error = formatToolError(result, opts.toolName, opts.errorHint);
+  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
+  writers.stderr(`${text}
+`);
+  return cliExitCode(result, opts.exitCodes);
+}
 
-// src/tools/cli-args.ts
+// src/tools/cli/args.ts
 import { z } from "zod";
 var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
 var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help", "ascending"]);
@@ -665,108 +775,7 @@ function resolveCliView(flags, ascending) {
   throw new CliArgumentError("--top needs --sort, --by, --count-by or --sum to rank");
 }
 
-// src/tools/cli-command.ts
-function defineCliCommand(definition) {
-  return definition;
-}
-function prepareCliCommandEmission(definition, result, options) {
-  if (!result.ok || definition.output === undefined) {
-    return { result, successExitCode: 0 };
-  }
-  try {
-    const successExitCode = definition.exitCode?.(result.data) ?? 0;
-    if (!Number.isSafeInteger(successExitCode) || successExitCode < 0 || successExitCode > 255) {
-      throw new Error("CLI success exit code must be an integer from 0 to 255");
-    }
-    const presentation = definition.present?.({ result: result.data, options });
-    if (presentation !== undefined && typeof presentation !== "string") {
-      throw new Error("CLI result presenter must return a string");
-    }
-    return { result, presentation, successExitCode };
-  } catch (error) {
-    return {
-      result: toolResultFromError(new Error("CLI result policy failed", { cause: error })),
-      successExitCode: 0
-    };
-  }
-}
-function cliCommandPresentationSchema(definition) {
-  return buildToolPresentationSchema({
-    inputSchema: definition.input,
-    unrepresentable: "any"
-  });
-}
-async function executeCliCommand(definition, rawArgs, options, writers, coerceJson, globals = {}) {
-  let parsed;
-  try {
-    parsed = definition.input.safeParse(coerceJson ? coerceJsonArgs(rawArgs, definition.input) : rawArgs);
-  } catch (error) {
-    return toolResultFromError(error);
-  }
-  if (!parsed.success) {
-    return {
-      ok: false,
-      code: "VALIDATION_ERROR",
-      details: { message: `Invalid input: ${formatZodError(parsed.error)}` }
-    };
-  }
-  try {
-    const data = await definition.handler({
-      input: parsed.data,
-      options,
-      globals,
-      ...writers
-    });
-    const checked = validateDeclaredOutput(definition.output, data);
-    if (!checked.ok) {
-      return {
-        ok: false,
-        code: "INTERNAL_SERVER_ERROR",
-        details: { message: checked.message }
-      };
-    }
-    return { ok: true, data: checked.data };
-  } catch (error) {
-    return toolResultFromError(error);
-  }
-}
-
-// 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,
-  WAIT_FAILED: 1,
-  INTERNAL_SERVER_ERROR: 1
-};
-function cliExitCode(result, exitCodes) {
-  if (result.ok)
-    return 0;
-  const codes = { ...DEFAULT_EXIT_CODES, ...exitCodes };
-  return Object.hasOwn(codes, result.code) ? codes[result.code] ?? 1 : 1;
-}
-function emitResult(result, writers, opts) {
-  if (result.ok) {
-    if (result.data === undefined)
-      return 0;
-    const text2 = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
-    writers.stdout(`${text2}
-`);
-    return 0;
-  }
-  const error = formatToolError(result, opts.toolName, opts.errorHint);
-  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
-  writers.stderr(`${text}
-`);
-  return cliExitCode(result, opts.exitCodes);
-}
-
-// src/tools/cli-policy.ts
+// src/tools/cli/policy.ts
 var SHORT_ALIAS = /^[A-Za-z]$/;
 var RESERVED_SHORT_OPTIONS = new Set(["h"]);
 function fieldMap(descriptor) {
@@ -846,7 +855,7 @@ function assertCliPoliciesResolved(commands, config) {
   }
 }
 
-// src/tools/cli-invoke.ts
+// src/tools/cli/invoke.ts
 function parseCliGlobals(schema, globals) {
   if (!schema)
     return globals ?? {};
@@ -877,21 +886,29 @@ function cliInvocationResult(result, toolName, config) {
 async function createCliInvoker(config, globals) {
   const typedGlobals = parseCliGlobals(config.globalOptions, globals);
   const auth = await (config.resolveAuth ? config.resolveAuth(typedGlobals) : config.auth);
+  const natives = new Map((config.commands ?? []).filter(cliCommandReturnsResult).map((definition) => [definition.name, definition]));
+  const nativeHelp = new Map([...natives].map(([name, definition]) => [
+    name,
+    { description: definition.description, argumentSchema: {}, presentationSchema: {} }
+  ]));
   const { tools, help } = buildCliSurface(config, auth, new Map, new Set);
   const runTool = createToolRunner({
     source: "cli",
+    toolSurface: true,
     context: { ...config.context?.(auth, typedGlobals), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
     coerceJsonArgs: config.coerceJsonArgs
   });
   return {
-    commands: [...help].map(([name, presentation]) => ({
+    commands: [...nativeHelp, ...help].map(([name, presentation]) => ({
       name,
       description: presentation.description
     })),
     invoke: async (command, args) => {
+      const native = natives.get(command);
+      if (native)
+        return runNativeCommand(native, args, config, typedGlobals);
       const tool = tools.get(command);
       if (!tool) {
         return cliInvocationResult({
@@ -910,6 +927,42 @@ async function createCliInvoker(config, globals) {
     }
   };
 }
+var IN_PROCESS_RUN_OPTIONS = Object.freeze({
+  json: false,
+  wait: false,
+  quiet: true,
+  dryRun: false,
+  help: false
+});
+async function runNativeCommand(definition, args, config, globals) {
+  let out = "";
+  let err = "";
+  const result = await executeCliCommand(definition, args, IN_PROCESS_RUN_OPTIONS, {
+    stdout: (text) => {
+      out += text;
+    },
+    stderr: (text) => {
+      err += text;
+    }
+  }, config.coerceJsonArgs ?? true, globals);
+  let invocation = cliInvocationResult(result, definition.name, config);
+  if (invocation.ok) {
+    try {
+      invocation = {
+        ...invocation,
+        exitCode: cliCommandSuccessExitCode(definition, result.ok ? result.data : undefined)
+      };
+    } catch (error) {
+      invocation = cliInvocationResult(toolResultFromError(error), definition.name, config);
+    }
+  }
+  if (out === "" && err === "")
+    return invocation;
+  return {
+    ...invocation,
+    written: { ...out !== "" && { stdout: out }, ...err !== "" && { stderr: err } }
+  };
+}
 function buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertShape) {
   const services = typeof config.services === "function" ? config.services(auth) : config.services ?? [];
   const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools ?? [];
@@ -935,7 +988,7 @@ function managedCliDescriptor(tool) {
   };
 }
 
-// src/tools/cli-view.ts
+// src/tools/cli/view.ts
 var ABSENT = "(absent)";
 function selectRecords(data) {
   if (Array.isArray(data))
@@ -1082,7 +1135,7 @@ function renderCliView(data, view) {
   return { kind: "json", data: ordered(totals, view.top) };
 }
 
-// src/tools/wait-core.ts
+// src/tools/operations/wait-core.ts
 var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
 var DEFAULT_TIMEOUT = 600;
 
@@ -1178,7 +1231,7 @@ function runWaitOperation(params) {
   });
 }
 
-// src/tools/cli-wait.ts
+// src/tools/cli/wait.ts
 var DEFAULT_TIMEOUT2 = 600;
 function waitFailure(tool, result) {
   return {
@@ -1232,8 +1285,58 @@ async function pollUntilDone(params) {
   return state;
 }
 
-// src/tools/cli.ts
+// src/tools/cli/io.ts
 import { writeSync } from "node:fs";
+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 createCliIo(config) {
+  let pendingWrite;
+  let writeFailed = false;
+  const writeFd = (fd, text) => {
+    const bytes = Buffer.from(text, "utf8");
+    let offset = 0;
+    while (offset < bytes.length) {
+      try {
+        offset += writeSync(fd, bytes, offset, bytes.length - offset);
+      } catch (error) {
+        if (isRecord(error) && error.code === "EAGAIN") {
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+          continue;
+        }
+        const stream = fd === 1 ? process.stdout : process.stderr;
+        const rest = bytes.subarray(offset);
+        pendingWrite = new Promise((resolve) => {
+          stream.write(rest, (failure) => {
+            if (failure)
+              writeFailed = true;
+            resolve();
+          });
+        });
+        return;
+      }
+    }
+  };
+  const stdout = config.stdout ?? ((text) => writeFd(1, text));
+  const stderr = config.stderr ?? ((text) => writeFd(2, text));
+  const exit = config.exit ?? ((code) => {
+    if (pendingWrite === undefined)
+      process.exit(code);
+    else
+      pendingWrite.then(() => process.exit(writeFailed ? 1 : code));
+  });
+  const readStdin = config.stdin ?? readPipedStdin;
+  return { stdout, stderr, exit, readStdin };
+}
+
+// src/tools/cli/download.ts
 import { basename, resolve } from "node:path";
 
 // src/internal/secure-fetch.ts
@@ -1398,6 +1501,10 @@ async function fetchGuarded(start, allowPrivate, options = {}) {
       clearTimeout(headerTimer);
   }
 }
+
+class PrivateAddressRefusal extends Error {
+  name = "PrivateAddressRefusal";
+}
 async function resolvePublicAddress(url, signal) {
   assertHttpUrl(url);
   const host = url.hostname.replace(/^\[|\]$/g, "");
@@ -1406,20 +1513,20 @@ async function resolvePublicAddress(url, signal) {
   const ipFamily = isIP(host);
   if (ipFamily) {
     if (isPrivateIp(host))
-      throw new Error("refusing to fetch a private address");
+      throw new PrivateAddressRefusal("refusing to fetch a private address");
     return { address: host, family: ipFamily === 6 ? 6 : 4 };
   }
   if (NUMERIC_HOST.test(host)) {
-    throw new Error("refusing to fetch a non-canonical numeric host");
+    throw new PrivateAddressRefusal("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");
+    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 record2 of records) {
     if (isPrivateIp(record2.address)) {
-      throw new Error("refusing to fetch a host that resolves to a private address");
+      throw new PrivateAddressRefusal("refusing to fetch a host that resolves to a private address");
     }
   }
   const record = records[0];
@@ -1542,7 +1649,34 @@ async function writeDownload(root, target, data) {
   await writeFile(target, data);
 }
 
-// src/tools/cli.ts
+// src/tools/cli/download.ts
+var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
+async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes, timeoutMs) {
+  const root = resolve(dir);
+  let succeeded = true;
+  for (const file of files) {
+    try {
+      const res = await fetchGuarded(new URL(file.url), allowPrivate, { timeoutMs });
+      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));
+      await writeDownload(root, target, buffer);
+      if (!quiet)
+        stderr(`saved ${target} (${(buffer.length / 1024).toFixed(0)}KB)
+`);
+    } catch (err) {
+      succeeded = false;
+      stderr(`failed to download ${file.url}: ${err instanceof Error ? err.message : String(err)}
+`);
+    }
+  }
+  return succeeded;
+}
+
+// src/tools/cli/help.ts
 var GLOBAL_OPTIONS = [
   ["--json", "Emit compact success/error JSON records (for scripts)"],
   ["--wait", "Block-poll an async result to a terminal state"],
@@ -1559,16 +1693,6 @@ var GLOBAL_OPTIONS = [
   ["--top <n>", "Keep the n leading entries of the view asked for"],
   ["--table <a,b>", "Render the named fields as an aligned table"]
 ];
-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("|");
@@ -1588,44 +1712,6 @@ function summarize(desc) {
   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 applicationOptionLines(fields) {
   if (fields.length === 0)
     return [];
@@ -1720,6 +1806,8 @@ function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
 `)}
 `;
 }
+
+// src/tools/cli/session.ts
 function nativeDescriptor(definition) {
   return {
     description: definition.description,
@@ -1745,101 +1833,7 @@ function assertCommandShape(name, descriptor, exists, passthroughField, applicat
     throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
   }
 }
-async function prepareInvocation(command, commandArgv, descriptor, config, readStdin) {
-  let parsed;
-  try {
-    parsed = parseCliArgs(commandArgv, descriptor.argumentSchema, {
-      allowUnknown: config.passthrough?.[command] !== undefined,
-      knownFields: jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name),
-      optionAliases: new Map([...descriptor.aliases].map(([field, alias]) => [alias, field])),
-      positionals: descriptor.positionals
-    });
-  } catch (error) {
-    if (!(error instanceof CliArgumentError))
-      throw error;
-    return { ok: false, message: error.message };
-  }
-  const { toolArgs, options } = parsed;
-  const firstUnset = jsonSchemaFields(descriptor.presentationSchema).find((field) => field.required && !(field.name in toolArgs) && field.schema.type !== "boolean");
-  if (firstUnset) {
-    const piped = await readStdin();
-    if (piped !== null) {
-      if (descriptor.positionals === undefined) {
-        toolArgs[firstUnset.name] = piped;
-      } else {
-        const stdinArgs = parseCliArgs([`--${firstUnset.name}`, piped], descriptor.argumentSchema);
-        toolArgs[firstUnset.name] = stdinArgs.toolArgs[firstUnset.name];
-      }
-    }
-  }
-  const passthroughField = config.passthrough?.[command];
-  if (passthroughField) {
-    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(descriptor.argumentSchema));
-  }
-  return { ok: true, toolArgs, options };
-}
-var DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;
-async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes, timeoutMs) {
-  const root = resolve(dir);
-  let succeeded = true;
-  for (const file of files) {
-    try {
-      const res = await fetchGuarded(new URL(file.url), allowPrivate, { timeoutMs });
-      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));
-      await writeDownload(root, target, buffer);
-      if (!quiet)
-        stderr(`saved ${target} (${(buffer.length / 1024).toFixed(0)}KB)
-`);
-    } catch (err) {
-      succeeded = false;
-      stderr(`failed to download ${file.url}: ${err instanceof Error ? err.message : String(err)}
-`);
-    }
-  }
-  return succeeded;
-}
-async function createCli(config) {
-  let pendingWrite;
-  let writeFailed = false;
-  const writeFd = (fd, text) => {
-    const bytes = Buffer.from(text, "utf8");
-    let offset = 0;
-    while (offset < bytes.length) {
-      try {
-        offset += writeSync(fd, bytes, offset, bytes.length - offset);
-      } catch (error) {
-        if (isRecord(error) && error.code === "EAGAIN") {
-          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
-          continue;
-        }
-        const stream = fd === 1 ? process.stdout : process.stderr;
-        const rest = bytes.subarray(offset);
-        pendingWrite = new Promise((resolve2) => {
-          stream.write(rest, (failure) => {
-            if (failure)
-              writeFailed = true;
-            resolve2();
-          });
-        });
-        return;
-      }
-    }
-  };
-  const stdout = config.stdout ?? ((text) => writeFd(1, text));
-  const stderr = config.stderr ?? ((text) => writeFd(2, text));
-  const exit = config.exit ?? ((code) => {
-    if (pendingWrite === undefined)
-      process.exit(code);
-    else
-      pendingWrite.then(() => process.exit(writeFailed ? 1 : code));
-  });
-  const argv = config.argv ?? process.argv.slice(2);
-  const readStdin = config.stdin ?? readPipedStdin;
+function createCliSession(config, io) {
   if (config.auth !== undefined && config.resolveAuth !== undefined) {
     throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
   }
@@ -1856,11 +1850,23 @@ async function createCli(config) {
   const nativeCommands = new Map;
   const nativeHelp = new Map;
   for (const definition of config.commands ?? []) {
-    const descriptor2 = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
-    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
+    const descriptor = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
+    assertCommandShape(definition.name, descriptor, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
     nativeCommands.set(definition.name, definition);
-    nativeHelp.set(definition.name, descriptor2);
+    nativeHelp.set(definition.name, descriptor);
   }
+  return {
+    config,
+    io,
+    applicationOptions,
+    applicationGlobalNames,
+    nativeCommands,
+    nativeHelp
+  };
+}
+function resolveCliRoute(session, argv) {
+  const { config } = session;
+  const { stdout, stderr, exit } = session.io;
   let globals;
   let routableArgv;
   try {
@@ -1872,135 +1878,188 @@ async function createCli(config) {
       throw error;
     stderr(`${error.message}
 `);
-    return exit(2);
+    exit(2);
+    return;
   }
   const typedGlobals = globals;
   const route = routeCliArgv(routableArgv, config.defaultCommand);
   if (route.error) {
     stderr(`${route.error}
 `);
-    return exit(2);
+    exit(2);
+    return;
   }
   const { command, commandArgv } = route;
   if (route.version || command === "--version" || command === "version") {
     stdout(`${config.name} ${config.version}
 `);
-    return exit(0);
+    exit(0);
+    return;
   }
   const beforeSeparator = commandArgv.indexOf("--") === -1 ? commandArgv : commandArgv.slice(0, commandArgv.indexOf("--"));
   const helpRequested = beforeSeparator.includes("--help") || beforeSeparator.includes("-h");
-  const native = command === undefined ? undefined : nativeCommands.get(command);
-  if (native && command !== undefined) {
-    const descriptor2 = nativeHelp.get(command);
-    if (!descriptor2)
-      throw new Error("[stitchkit] native CLI descriptor invariant failed");
-    if (helpRequested) {
-      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
-      return exit(0);
-    }
-    const prepared2 = await prepareInvocation(command, commandArgv, descriptor2, config, readStdin);
-    if (!prepared2.ok) {
-      stderr(`${prepared2.message}
-`);
-      return exit(2);
-    }
-    const { toolArgs: toolArgs2, options: options2 } = prepared2;
-    if (options2.help) {
-      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
-      return exit(0);
-    }
-    if (options2.wait) {
-      stderr(`--wait is not configured for native command "${command}"
-`);
-      return exit(2);
-    }
-    if (options2.waitTimeout !== undefined) {
-      stderr(`--wait-timeout requires --wait
-`);
-      return exit(2);
-    }
-    if (options2.outputDir !== undefined) {
-      stderr(`--output-dir is not configured for native commands
-`);
-      return exit(2);
-    }
-    if (options2.dryRun) {
-      stdout(`${JSON.stringify({ command, args: toolArgs2 }, null, 2)}
-`);
-      return exit(0);
-    }
-    const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true, globals);
-    const emission = prepareCliCommandEmission(native, result2, options2);
-    let emittedExitCode;
-    if (emission.result.ok && emission.presentation !== undefined) {
-      stdout(emission.presentation);
-      emittedExitCode = 0;
-    } else {
-      emittedExitCode = emitResult(emission.result, { stdout, stderr }, {
-        json: options2.json,
-        toolName: command,
-        errorHint: config.errorHint,
-        exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-      });
-    }
-    return exit(emission.result.ok ? emission.successExitCode : emittedExitCode);
-  }
+  return {
+    globals,
+    typedGlobals,
+    route,
+    command,
+    commandArgv,
+    beforeSeparator,
+    helpRequested
+  };
+}
+function emitOptionsFor(config, json, toolName) {
+  return {
+    json,
+    toolName,
+    errorHint: config.errorHint,
+    exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
+  };
+}
+
+// src/tools/cli/managed-surface.ts
+async function buildManagedSurface(session, typedGlobals, forExecution) {
+  const { config, nativeHelp, applicationGlobalNames } = session;
   let authPromise;
   const resolveIdentity = () => {
     authPromise ??= (async () => config.resolveAuth ? await config.resolveAuth(typedGlobals) : await config.auth)();
     return authPromise;
   };
   const dynamicSurface = typeof config.services === "function" || typeof config.runtimeTools === "function";
-  const buildManagedSurface = async (forExecution) => {
-    let auth;
-    if (dynamicSurface || forExecution) {
-      try {
-        auth = await resolveIdentity();
-      } catch (error) {
-        const failure = toolResultFromError(error);
-        const normalized = toolErrorFromResult(failure);
-        return {
-          resolved: false,
-          failure,
-          reason: `${normalized.code}: ${normalized.message}`,
-          help: new Map(nativeHelp)
-        };
+  let auth;
+  if (dynamicSurface || forExecution) {
+    try {
+      auth = await resolveIdentity();
+    } catch (error) {
+      const failure = toolResultFromError(error);
+      const normalized = toolErrorFromResult(failure);
+      return {
+        resolved: false,
+        failure,
+        reason: `${normalized.code}: ${normalized.message}`,
+        help: new Map(nativeHelp)
+      };
+    }
+  }
+  const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertCommandShape);
+  return { resolved: true, auth, help, tools };
+}
+
+// src/tools/cli/prepare.ts
+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;
+}
+async function prepareInvocation(command, commandArgv, descriptor, config, readStdin) {
+  let parsed;
+  try {
+    parsed = parseCliArgs(commandArgv, descriptor.argumentSchema, {
+      allowUnknown: config.passthrough?.[command] !== undefined,
+      knownFields: jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name),
+      optionAliases: new Map([...descriptor.aliases].map(([field, alias]) => [alias, field])),
+      positionals: descriptor.positionals
+    });
+  } catch (error) {
+    if (!(error instanceof CliArgumentError))
+      throw error;
+    return { ok: false, message: error.message };
+  }
+  const { toolArgs, options } = parsed;
+  const firstUnset = jsonSchemaFields(descriptor.presentationSchema).find((field) => field.required && !(field.name in toolArgs) && field.schema.type !== "boolean");
+  if (firstUnset) {
+    const piped = await readStdin();
+    if (piped !== null) {
+      if (descriptor.positionals === undefined) {
+        toolArgs[firstUnset.name] = piped;
+      } else {
+        const stdinArgs = parseCliArgs([`--${firstUnset.name}`, piped], descriptor.argumentSchema);
+        toolArgs[firstUnset.name] = stdinArgs.toolArgs[firstUnset.name];
       }
     }
-    const { tools, help } = buildCliSurface(config, auth, nativeHelp, applicationGlobalNames, assertCommandShape);
-    return { resolved: true, auth, help, tools };
-  };
-  const topLevelHelp = route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h" || command.startsWith("--help=") && !isReservedBoolWord(command.slice("--help=".length));
-  const managed = await buildManagedSurface(!topLevelHelp && !helpRequested);
-  if (topLevelHelp) {
-    const helpFilter = route.helpFilter ?? (command !== undefined ? commandArgv[0] : undefined);
-    const filter = helpFilter !== undefined && !helpFilter.startsWith("-") ? helpFilter : undefined;
-    if (filter !== undefined && filterCommands(managed.help, filter).size === 0) {
-      stderr(`no command matches "${filter}" (${managed.help.size} available)
-` + (managed.resolved ? "" : `Managed commands are unavailable: ${managed.reason}
-`));
-      const codes = { ...DEFAULT_EXIT_CODES, ...config.exitCodes };
-      return exit(codes.NOT_FOUND ?? 4);
-    }
-    stdout(renderTopHelp({
-      name: config.name,
-      version: config.version,
-      commands: managed.help,
-      defaultCommand: config.defaultCommand,
-      applicationOptions,
-      ...filter !== undefined && { filter },
-      ...managed.resolved ? {} : { unavailable: managed.reason }
-    }));
-    return exit(0);
   }
+  const passthroughField = config.passthrough?.[command];
+  if (passthroughField) {
+    collectPassthrough(toolArgs, passthroughField, objectShapeKeys(descriptor.argumentSchema));
+  }
+  return { ok: true, toolArgs, options };
+}
+
+// src/tools/cli/run-managed.ts
+async function runManagedInvocation(session, route) {
+  const { config } = session;
+  const { stdout, stderr, exit } = session.io;
+  const { command, helpRequested, beforeSeparator } = route;
+  const topLevelHelp = route.route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h" || command.startsWith("--help=") && !isReservedBoolWord(command.slice("--help=".length));
+  const managed = await buildManagedSurface(session, route.typedGlobals, !topLevelHelp && !helpRequested);
+  if (topLevelHelp)
+    return respondTopLevelHelp(session, route, managed);
   if (!managed.resolved) {
-    return exit(emitResult(managed.failure, { stdout, stderr }, {
-      json: beforeSeparator.includes("--json"),
-      toolName: command ?? config.name,
-      errorHint: config.errorHint,
-      exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-    }));
+    return exit(emitResult(managed.failure, { stdout, stderr }, emitOptionsFor(config, beforeSeparator.includes("--json"), command ?? config.name)));
+  }
+  return runManagedCommand(session, route, command, managed);
+}
+function respondTopLevelHelp(session, route, managed) {
+  const { config, applicationOptions } = session;
+  const { stdout, stderr, exit } = session.io;
+  const { command, commandArgv } = route;
+  const helpFilter = route.route.helpFilter ?? (command !== undefined ? commandArgv[0] : undefined);
+  const filter = helpFilter !== undefined && !helpFilter.startsWith("-") ? helpFilter : undefined;
+  if (filter !== undefined && filterCommands(managed.help, filter).size === 0) {
+    stderr(`no command matches "${filter}" (${managed.help.size} available)
+` + (managed.resolved ? "" : `Managed commands are unavailable: ${managed.reason}
+`));
+    const codes = { ...DEFAULT_EXIT_CODES, ...config.exitCodes };
+    exit(codes.NOT_FOUND ?? 4);
+    return;
   }
+  stdout(renderTopHelp({
+    name: config.name,
+    version: config.version,
+    commands: managed.help,
+    defaultCommand: config.defaultCommand,
+    applicationOptions,
+    ...filter !== undefined && { filter },
+    ...managed.resolved ? {} : { unavailable: managed.reason }
+  }));
+  exit(0);
+}
+async function runManagedCommand(session, route, command, managed) {
+  const { config, applicationOptions } = session;
+  const { stdout, stderr, exit, readStdin } = session.io;
   const tool = managed.tools.get(command);
   if (!tool) {
     stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
@@ -2010,11 +2069,11 @@ async function createCli(config) {
   const descriptor = managed.help.get(command);
   if (!descriptor)
     throw new Error("[stitchkit] managed CLI descriptor invariant failed");
-  if (helpRequested) {
+  if (route.helpRequested) {
     stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
-  const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
+  const prepared = await prepareInvocation(command, route.commandArgv, descriptor, config, readStdin);
   if (!prepared.ok) {
     stderr(`${prepared.message}
 `);
@@ -2045,12 +2104,21 @@ async function createCli(config) {
 `);
     return exit(0);
   }
+  const result = await executeManagedTool(session, route, command, managed, tool, {
+    toolArgs,
+    options
+  });
+  return emitManagedResult(session, command, result, options);
+}
+async function executeManagedTool(session, route, command, managed, tool, { toolArgs, options }) {
+  const { config } = session;
+  const { stderr } = session.io;
   const runTool = createToolRunner({
     source: "cli",
-    context: { ...config.context?.(managed.auth, typedGlobals), signal: config.signal },
+    toolSurface: true,
+    context: { ...config.context?.(managed.auth, route.typedGlobals), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
-    errorHint: config.errorHint,
     coerceJsonArgs: config.coerceJsonArgs
   });
   let result;
@@ -2081,6 +2149,12 @@ async function createCli(config) {
       signal: config.signal
     });
   }
+  return result;
+}
+async function emitManagedResult(session, command, initial, options) {
+  const { config } = session;
+  const { stdout, stderr, exit } = session.io;
+  let result = initial;
   let downloadsOk = true;
   if (options.outputDir && result.ok && config.download) {
     downloadsOk = await downloadResults(config.download(result.data), options.outputDir, stderr, options.quiet, config.allowPrivateDownloadHosts ?? false, config.maxDownloadBytes ?? DEFAULT_DOWNLOAD_MAX_BYTES, config.downloadTimeoutMs);
@@ -2102,13 +2176,82 @@ async function createCli(config) {
     }
     result = { ...result, data: viewed.data };
   }
-  const exitCode = emitResult(result, { stdout, stderr }, {
-    json: options.json,
-    toolName: command,
-    errorHint: config.errorHint,
-    exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-  });
+  const exitCode = emitResult(result, { stdout, stderr }, emitOptionsFor(config, options.json, command));
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, cliInvocationResult, createCliInvoker, renderCliView, pollUntilDone, createCli };
+// src/tools/cli/run-native.ts
+async function runNativeCommand2(session, route, command, native) {
+  const { config, applicationOptions, nativeHelp } = session;
+  const { stdout, stderr, exit, readStdin } = session.io;
+  const { commandArgv, helpRequested, globals } = route;
+  const descriptor = nativeHelp.get(command);
+  if (!descriptor)
+    throw new Error("[stitchkit] native CLI descriptor invariant failed");
+  if (helpRequested) {
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
+    return exit(0);
+  }
+  const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
+  if (!prepared.ok) {
+    stderr(`${prepared.message}
+`);
+    return exit(2);
+  }
+  const { toolArgs, options } = prepared;
+  if (options.help) {
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
+    return exit(0);
+  }
+  if (options.wait) {
+    stderr(`--wait is not configured for native command "${command}"
+`);
+    return exit(2);
+  }
+  if (options.waitTimeout !== undefined) {
+    stderr(`--wait-timeout requires --wait
+`);
+    return exit(2);
+  }
+  if (options.outputDir !== undefined) {
+    stderr(`--output-dir is not configured for native commands
+`);
+    return exit(2);
+  }
+  if (options.dryRun) {
+    stdout(`${JSON.stringify({ command, args: toolArgs }, null, 2)}
+`);
+    return exit(0);
+  }
+  const result = await executeCliCommand(native, toolArgs, options, { stdout, stderr }, config.coerceJsonArgs ?? true, globals);
+  const emission = prepareCliCommandEmission(native, result, options);
+  let emittedExitCode;
+  if (emission.result.ok && emission.presentation !== undefined) {
+    stdout(emission.presentation);
+    emittedExitCode = 0;
+  } else {
+    emittedExitCode = emitResult(emission.result, { stdout, stderr }, emitOptionsFor(config, options.json, command));
+  }
+  return exit(emission.result.ok ? emission.successExitCode : emittedExitCode);
+}
+
+// src/tools/cli/create-cli.ts
+async function createCli(config) {
+  const io = createCliIo(config);
+  const argv = config.argv ?? process.argv.slice(2);
+  if (config.auth !== undefined && config.resolveAuth !== undefined) {
+    throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
+  }
+  const session = createCliSession(config, io);
+  const route = resolveCliRoute(session, argv);
+  if (route === undefined)
+    return;
+  const { command } = route;
+  const native = command === undefined ? undefined : session.nativeCommands.get(command);
+  if (native && command !== undefined) {
+    return runNativeCommand2(session, route, command, native);
+  }
+  return runManagedInvocation(session, route);
+}
+
+export { fetchGuarded, PrivateAddressRefusal, fetchPinnedDocument, readCapped, WaitTimeoutError, runWaitOperation, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, cliInvocationResult, createCliInvoker, renderCliView, pollUntilDone, createCli };