stitchkit 0.94.0 → 0.94.1

package/dist/{index-n6hxg8as.js → index-t9rhjr9f.js}

@@ -3,15 +3,15 @@ import {
 } from "./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-vcvkq30w.js";
+} from "./index-hmp4800j.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-2cr1cqhn.js";
+} from "./index-khtgb21r.js";
 import {
   toolErrorFromResult,
   toolResultFromError
-} from "./index-j05z5gn4.js";
+} from "./index-55hkhm67.js";
 import {
   coerceJsonArgs
 } from "./index-1zbbzgfh.js";
@@ -19,7 +19,7 @@ import {
   assertUniqueToolName,
   buildToolPresentationSchema,
   objectShapeKeys
-} from "./index-dydjcp8z.js";
+} from "./index-np4m8hd3.js";
 import {
   jsonSchemaFields
 } from "./index-eqqvgdb3.js";
@@ -145,149 +145,13 @@ function emitResult(result, writers, opts) {
   return cliExitCode(result, opts.exitCodes);
 }
 
-// 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"]);
-var VIEW_OPTIONS = new Set(["count-by", "sum", "by", "top", "table", "sort"]);
-var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir", ...VIEW_OPTIONS]);
-var RESERVED_CLI_OPTIONS = new Set([...BOOL_OPTIONS, ...VALUE_OPTIONS]);
-function classifyLongOptionToken(token) {
-  if (!token.startsWith("--") || token === "--")
-    return;
-  const equals = token.indexOf("=");
-  const name = equals >= 0 ? token.slice(2, equals) : token.slice(2);
-  return {
-    name,
-    value: equals >= 0 ? token.slice(equals + 1) : undefined,
-    inline: equals >= 0,
-    globalKind: BOOL_OPTIONS.has(name) ? "boolean" : VALUE_OPTIONS.has(name) ? "value" : undefined
-  };
-}
-var HELP_TOKENS = new Set(["--help", "-h", "help"]);
-function helpFilterFrom(token, rest) {
-  if (token?.startsWith("--help=")) {
-    const value = token.slice("--help=".length).trim();
-    if (value.length === 0 || isReservedBoolWord(value))
-      return;
-    return value;
-  }
-  if (token === undefined || !HELP_TOKENS.has(token))
-    return;
-  const next = rest[0];
-  return next !== undefined && !next.startsWith("-") ? next : undefined;
-}
-function routeCliArgv(argv, defaultCommand) {
-  if (defaultCommand === undefined) {
-    const [command, ...commandArgv] = argv;
-    const helpFilter = helpFilterFrom(command, commandArgv);
-    return {
-      command,
-      commandArgv,
-      topLevelHelp: false,
-      version: false,
-      ...helpFilter !== undefined && { helpFilter }
-    };
-  }
-  const globals = [];
-  let index = 0;
-  while (index < argv.length) {
-    const token = argv[index];
-    if (token === undefined)
-      break;
-    if (token === "--") {
-      return {
-        commandArgv: [],
-        topLevelHelp: false,
-        version: false,
-        error: 'A command is required before "--"'
-      };
-    }
-    const inlineHelpFilter = token.startsWith("--help=") && !isReservedBoolWord(token.slice("--help=".length));
-    if (token === "--help" || token === "-h" || inlineHelpFilter) {
-      const helpFilter = helpFilterFrom(token, argv.slice(index + 1));
-      return {
-        commandArgv: [],
-        topLevelHelp: true,
-        version: false,
-        ...helpFilter !== undefined && { helpFilter }
-      };
-    }
-    if (token === "--version" || token === "version") {
-      return { commandArgv: [], topLevelHelp: false, version: true };
-    }
-    if (!token.startsWith("-") || token === "-") {
-      return {
-        command: token,
-        commandArgv: [...globals, ...argv.slice(index + 1)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    if (!token.startsWith("--")) {
-      return {
-        command: defaultCommand,
-        commandArgv: [...globals, ...argv.slice(index)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    const option = classifyLongOptionToken(token);
-    if (!option) {
-      return {
-        command: defaultCommand,
-        commandArgv: [...globals, ...argv.slice(index)],
-        topLevelHelp: false,
-        version: false
-      };
-    }
-    if (option.globalKind === "boolean") {
-      globals.push(token);
-      index += 1;
-      continue;
-    }
-    if (option.globalKind === "value") {
-      globals.push(token);
-      if (!option.inline) {
-        const value = argv[index + 1];
-        if (value === "--help" || value === "-h") {
-          const helpFilter = helpFilterFrom(value, argv.slice(index + 2));
-          return {
-            commandArgv: [],
-            topLevelHelp: true,
-            version: false,
-            ...helpFilter !== undefined && { helpFilter }
-          };
-        }
-        if (value === "--version" || value === "version") {
-          return { commandArgv: [], topLevelHelp: false, version: true };
-        }
-        if (value !== undefined)
-          globals.push(value);
-        index += value === undefined ? 1 : 2;
-      } else {
-        index += 1;
-      }
-      continue;
-    }
-    return {
-      command: defaultCommand,
-      commandArgv: [...globals, ...argv.slice(index)],
-      topLevelHelp: false,
-      version: false
-    };
-  }
-  return {
-    command: defaultCommand,
-    commandArgv: globals,
-    topLevelHelp: false,
-    version: false
-  };
-}
-
+// src/tools/cli/argument-error.ts
 class CliArgumentError extends Error {
   name = "CliArgumentError";
 }
+
+// src/tools/cli/args-fields.ts
+import { z } from "zod";
 function unwrap(field) {
   if (field instanceof z.ZodOptional || field instanceof z.ZodNullable || field instanceof z.ZodDefault) {
     return unwrap(field.unwrap());
@@ -334,9 +198,15 @@ function collectSchemaFields(schema, fields) {
       const fieldBase = unwrap(raw);
       const kind = classify(fieldBase);
       if (kind === "array" && fieldBase instanceof z.ZodArray) {
-        mergeField(fields, name, { kind, elementKind: classify(unwrap(fieldBase.element)) });
+        mergeField(fields, name, {
+          kind,
+          elementKind: classify(unwrap(fieldBase.element))
+        });
       } else {
-        mergeField(fields, name, { kind });
+        mergeField(fields, name, {
+          kind,
+          ...fieldBase instanceof z.ZodNumber && fieldBase.isInt && { integer: true }
+        });
       }
     }
     return;
@@ -412,18 +282,38 @@ function looksLikeJson(value) {
   const t = value.trim();
   return t.startsWith("[") || t.startsWith("{");
 }
-function coerceField(info, values) {
+function expectedValue(kind, integer) {
+  if (kind === "number")
+    return integer ? "a whole number" : "a number";
+  if (kind === "bigint")
+    return "a whole number";
+  if (kind === "date")
+    return "a date";
+  return;
+}
+function coerceNamed(label, kind, integer, value) {
+  const coerced = coerceScalar(kind, value);
+  const expected = expectedValue(kind, integer);
+  if (expected !== undefined && typeof coerced === "string") {
+    throw new CliArgumentError(`${label} expects ${expected}, got "${value}"`);
+  }
+  if (integer && typeof coerced === "number" && !Number.isInteger(coerced)) {
+    throw new CliArgumentError(`${label} expects ${expected}, got "${value}"`);
+  }
+  return coerced;
+}
+function coerceField(info, values, label) {
   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));
+    return values.map((v) => coerceNamed(label, info.elementKind ?? "string", false, v));
   }
   if (info.kind === "object")
     return last;
-  return coerceScalar(info.kind, last);
+  return coerceNamed(label, info.kind, info.integer, last);
 }
 function setNested(target, path, value) {
   const unsafe = path.find(isUnsafeKey);
@@ -448,253 +338,365 @@ function setNested(target, path, value) {
   if (leaf !== undefined)
     node[leaf] = value;
 }
-function parseCliArgs(argv, schema, config = {}) {
-  const options = {
-    json: false,
-    wait: false,
-    quiet: false,
-    dryRun: false,
-    help: false
-  };
-  const fields = describeSchemaFields(schema);
-  for (const name of config.knownFields ?? []) {
-    if (!fields.has(name))
-      fields.set(name, { kind: "other" });
+
+// src/tools/cli/policy.ts
+var SHORT_ALIAS = /^[A-Za-z]$/;
+var RESERVED_SHORT_OPTIONS = new Set(["h"]);
+function fieldMap(descriptor) {
+  return new Map(jsonSchemaFields(descriptor.presentationSchema).map((field) => [field.name, field]));
+}
+function resolveAliases(command, descriptor, configured) {
+  if (!configured)
+    return new Map;
+  const fields = fieldMap(descriptor);
+  const aliases = new Map;
+  for (const [alias, target] of Object.entries(configured)) {
+    if (!SHORT_ALIAS.test(alias)) {
+      throw new Error(`[stitchkit] CLI command "${command}" alias "${alias}" must be one ASCII letter`);
+    }
+    if (RESERVED_SHORT_OPTIONS.has(alias)) {
+      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" is reserved`);
+    }
+    if (isUnsafeKey(target) || !fields.has(target)) {
+      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" targets unknown field "${target}"`);
+    }
+    const existing = aliases.get(target);
+    if (existing !== undefined) {
+      throw new Error(`[stitchkit] CLI command "${command}" field "${target}" has multiple aliases: -${existing}, -${alias}`);
+    }
+    aliases.set(target, alias);
   }
-  const flags = new Map;
-  const boolFlags = new Map;
-  const viewFlags = new Map;
-  let ascending = false;
-  const positionals = [];
-  const pushFlag = (name, value) => {
-    const existing = flags.get(name);
-    if (existing)
-      existing.push(value);
-    else
-      flags.set(name, [value]);
-  };
-  let optionsEnded = false;
-  for (let i = 0;i < argv.length; i++) {
-    const tok = argv[i];
-    if (tok === undefined)
-      continue;
-    if (!optionsEnded && tok === "--") {
-      optionsEnded = true;
-      continue;
+  return aliases;
+}
+function resolvePositionals(command, descriptor, configured) {
+  if (configured === undefined)
+    return;
+  const fields = fieldMap(descriptor);
+  const kinds = describeSchemaFields(descriptor.argumentSchema);
+  const seen = new Set;
+  let optionalSeen = false;
+  for (const name of configured) {
+    const field = fields.get(name);
+    if (isUnsafeKey(name) || !field || !kinds.has(name)) {
+      throw new Error(`[stitchkit] CLI command "${command}" positional targets unknown field "${name}"`);
     }
-    if (optionsEnded || !tok.startsWith("-") || tok === "-") {
-      positionals.push(tok);
-      continue;
+    if (seen.has(name)) {
+      throw new Error(`[stitchkit] CLI command "${command}" repeats positional field "${name}"`);
     }
-    if (tok === "-h") {
-      options.help = true;
-      continue;
+    if (kinds.get(name)?.kind === "boolean") {
+      throw new Error(`[stitchkit] CLI command "${command}" boolean field "${name}" cannot be positional`);
     }
-    if (!tok.startsWith("--")) {
-      const match = /^-([A-Za-z])(?:=(.*))?$/.exec(tok);
-      const alias = match?.[1];
-      const field = alias === undefined ? undefined : config.optionAliases?.get(alias);
-      if (!alias || !field)
-        throw new CliArgumentError(`Unknown option "${tok}"`);
-      const inline = match?.[2];
-      const info2 = fields.get(field);
-      if (info2?.kind === "boolean") {
-        boolFlags.set(field, inline === undefined ? true : parseReservedBool(field, inline));
-        continue;
-      }
-      let value2 = inline;
-      if (value2 === undefined) {
-        const next = argv[i + 1];
-        if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-          value2 = next;
-          i++;
-        } else {
-          throw new CliArgumentError(`--${field} requires a value`);
-        }
-      }
-      pushFlag(field, value2);
-      continue;
+    if (optionalSeen && field.required) {
+      throw new Error(`[stitchkit] CLI command "${command}" required positional "${name}" cannot follow an optional positional`);
     }
-    const option = classifyLongOptionToken(tok);
-    if (!option)
-      throw new CliArgumentError(`Unknown option "${tok}"`);
-    const { name } = option;
-    let { value } = option;
-    if (name.length === 0)
-      throw new CliArgumentError("Invalid empty option name");
-    if (option.globalKind === "boolean") {
-      const enabled = value === undefined ? true : parseReservedBool(name, value);
-      if (name === "dry-run")
-        options.dryRun = enabled;
-      else if (name === "json")
-        options.json = enabled;
-      else if (name === "wait")
-        options.wait = enabled;
-      else if (name === "quiet")
-        options.quiet = enabled;
-      else if (name === "ascending")
-        ascending = enabled;
-      else
-        options.help = enabled;
-      continue;
-    }
-    if (option.globalKind === "value") {
-      const next = argv[i + 1];
-      value = value ?? next;
-      if (value === undefined || value.startsWith("-") && !NUMERIC_VALUE.test(value)) {
-        throw new CliArgumentError(`--${name} requires a value`);
-      }
-      if (!option.inline)
-        i++;
-      if (name === "wait-timeout") {
-        const timeout = Number(value);
-        if (!Number.isFinite(timeout) || timeout <= 0) {
-          throw new CliArgumentError("--wait-timeout must be a positive number");
-        }
-        options.waitTimeout = timeout;
-      } else if (VIEW_OPTIONS.has(name)) {
-        if (viewFlags.has(name))
-          throw new CliArgumentError(`--${name} was given twice`);
-        viewFlags.set(name, value);
-      } else {
-        options.outputDir = value;
-      }
-      continue;
-    }
-    if (value === undefined && name.startsWith("no-") && fields.get(name.slice(3))?.kind === "boolean") {
-      boolFlags.set(name.slice(3), false);
-      continue;
-    }
-    const unsafeSegment = name.split(".").find(isUnsafeKey);
-    if (unsafeSegment !== undefined) {
-      throw new CliArgumentError(`Unsafe option name "--${name}"`);
+    if (!field.required)
+      optionalSeen = true;
+    seen.add(name);
+  }
+  return [...configured];
+}
+function applyCliPresentationPolicy(command, descriptor, config) {
+  const base = { ...descriptor, aliases: new Map };
+  const configuredAliases = config.optionAliases && Object.hasOwn(config.optionAliases, command) ? config.optionAliases[command] : undefined;
+  const configuredPositionals = config.positionals && Object.hasOwn(config.positionals, command) ? config.positionals[command] : undefined;
+  return {
+    ...base,
+    aliases: resolveAliases(command, base, configuredAliases),
+    positionals: resolvePositionals(command, base, configuredPositionals)
+  };
+}
+function assertCliPoliciesResolved(commands, config) {
+  const configuredNames = new Set([
+    ...Object.keys(config.optionAliases ?? {}),
+    ...Object.keys(config.positionals ?? {})
+  ]);
+  if (config.defaultCommand !== undefined)
+    configuredNames.add(config.defaultCommand);
+  for (const name of configuredNames) {
+    if (!commands.has(name)) {
+      throw new Error(`[stitchkit] CLI policy targets unavailable command "${name}"`);
     }
-    const info = fields.get(name);
-    const rootName = name.split(".")[0] ?? name;
-    if (!fields.has(rootName) && !config.allowUnknown) {
-      throw new CliArgumentError(`Unknown option "--${name}"`);
+  }
+}
+
+// src/tools/cli/invoke.ts
+function parseCliGlobals(schema, globals) {
+  if (!schema)
+    return globals ?? {};
+  return schema.parse(globals ?? {});
+}
+function cliInvocationResult(result, toolName, config) {
+  if (result.ok)
+    return { ok: true, exitCode: 0, data: result.data };
+  const normalized = toolErrorFromResult(result);
+  const hints = [];
+  if (result.hint)
+    hints.push(result.hint);
+  const global = config.errorHint?.(toolName, result.code);
+  if (global)
+    hints.push(global);
+  return {
+    ok: false,
+    exitCode: cliExitCode(result, config.exitCodes),
+    error: {
+      code: result.code,
+      message: normalized.message,
+      ...result.details !== undefined && { details: result.details },
+      ...hints.length > 0 && { hint: hints.join(" ") },
+      ...result.retryable !== undefined && { retryable: result.retryable }
     }
-    if (value === undefined) {
-      if (info?.kind === "boolean") {
-        boolFlags.set(name, true);
-        continue;
+  };
+}
+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,
+    coerceJsonArgs: config.coerceJsonArgs
+  });
+  return {
+    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({
+          ok: false,
+          code: "NOT_FOUND",
+          details: { message: `Unknown command "${command}"` }
+        }, command, config);
       }
-      const next = argv[i + 1];
-      if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-        value = next;
-        i++;
-      } else {
-        throw new CliArgumentError(`--${name} requires a value`);
+      let result;
+      try {
+        result = await runTool(tool, args);
+      } catch (error) {
+        result = toolResultFromError(error);
       }
+      return cliInvocationResult(result, command, config);
     }
-    pushFlag(name, value);
-  }
-  const view = resolveCliView(viewFlags, ascending);
-  if (view)
-    options.view = view;
-  const toolArgs = {};
-  const fillable = config.positionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...config.positionals];
-  const variadicTail = config.positionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
-  let pi = 0;
-  for (const key of fillable) {
-    if (pi >= positionals.length)
-      break;
-    if (key === variadicTail) {
-      if (flags.has(key)) {
-        throw new CliArgumentError(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
-      }
-      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi));
-      pi = positionals.length;
-      break;
+  };
+}
+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 (flags.has(key))
-      continue;
-    const value = positionals[pi++];
-    if (value !== undefined)
-      toolArgs[key] = coerceField(fields.get(key), [value]);
   }
-  if (pi < positionals.length) {
-    throw new CliArgumentError(`Unexpected positional argument "${positionals[pi]}"`);
+  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 ?? [];
+  const tools = new Map;
+  const help = new Map(nativeHelp);
+  for (const { mountable } of collectToolSurface({
+    surface: { services, runtimeTools },
+    transport: "CLI"
+  })) {
+    const descriptor = applyCliPresentationPolicy(mountable.name, managedCliDescriptor(mountable), config);
+    assertShape?.(mountable.name, descriptor, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
+    tools.set(mountable.name, mountable);
+    help.set(mountable.name, descriptor);
   }
-  for (const [key, value] of boolFlags) {
-    toolArgs[key] = value;
+  assertCliPoliciesResolved(help, config);
+  return { tools, help };
+}
+function managedCliDescriptor(tool) {
+  return {
+    description: tool.method.desc,
+    argumentSchema: tool.argumentSchema,
+    presentationSchema: tool.presentationSchema
+  };
+}
+
+// src/tools/cli/args-route.ts
+function isOptionToken(token) {
+  return token.startsWith("--") || /^-[A-Za-z](?:=|$)/.test(token);
+}
+function looksLikeOption(token) {
+  return token.startsWith("--") || /^-[A-Za-z]/.test(token);
+}
+var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help", "ascending"]);
+var VIEW_OPTIONS = new Set(["count-by", "sum", "by", "top", "table", "sort"]);
+var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir", ...VIEW_OPTIONS]);
+var RESERVED_CLI_OPTIONS = new Set([...BOOL_OPTIONS, ...VALUE_OPTIONS]);
+function classifyLongOptionToken(token) {
+  if (!token.startsWith("--") || token === "--")
+    return;
+  const equals = token.indexOf("=");
+  const name = equals >= 0 ? token.slice(2, equals) : token.slice(2);
+  return {
+    name,
+    value: equals >= 0 ? token.slice(equals + 1) : undefined,
+    inline: equals >= 0,
+    globalKind: BOOL_OPTIONS.has(name) ? "boolean" : VALUE_OPTIONS.has(name) ? "value" : undefined
+  };
+}
+var HELP_TOKENS = new Set(["--help", "-h", "help"]);
+function helpFilterFrom(token, rest) {
+  if (token?.startsWith("--help=")) {
+    const value = token.slice("--help=".length).trim();
+    if (value.length === 0 || isReservedBoolWord(value))
+      return;
+    return value;
   }
-  const dottedRoots = new Map;
-  for (const key of flags.keys()) {
-    const dot = key.indexOf(".");
-    if (dot > 0)
-      dottedRoots.set(key.slice(0, dot), key);
+  if (token === undefined || !HELP_TOKENS.has(token))
+    return;
+  const next = rest[0];
+  return next !== undefined && !next.startsWith("-") ? next : undefined;
+}
+function routeCliArgv(argv, defaultCommand) {
+  if (defaultCommand === undefined) {
+    const [command, ...commandArgv] = argv;
+    const helpFilter = helpFilterFrom(command, commandArgv);
+    return {
+      command,
+      commandArgv,
+      topLevelHelp: false,
+      version: false,
+      ...helpFilter !== undefined && { helpFilter }
+    };
   }
-  for (const [root, dotted] of dottedRoots) {
-    if (flags.has(root)) {
-      throw new CliArgumentError(`--${root} conflicts with --${dotted} — pass one form, not both`);
+  const globals = [];
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === undefined)
+      break;
+    if (token === "--") {
+      return {
+        commandArgv: [],
+        topLevelHelp: false,
+        version: false,
+        error: 'A command is required before "--"'
+      };
     }
-  }
-  for (const [key, values] of flags) {
-    if (key.includes(".")) {
-      if (values.length > 1) {
-        throw new CliArgumentError(`--${key} was passed ${values.length} times`);
-      }
-      setNested(toolArgs, key.split("."), looseCoerce(values[0] ?? ""));
-      continue;
+    const inlineHelpFilter = token.startsWith("--help=") && !isReservedBoolWord(token.slice("--help=".length));
+    if (token === "--help" || token === "-h" || inlineHelpFilter) {
+      const helpFilter = helpFilterFrom(token, argv.slice(index + 1));
+      return {
+        commandArgv: [],
+        topLevelHelp: true,
+        version: false,
+        ...helpFilter !== undefined && { helpFilter }
+      };
+    }
+    if (token === "--version" || token === "version") {
+      return { commandArgv: [], topLevelHelp: false, version: true };
+    }
+    if (!token.startsWith("-") || token === "-") {
+      return {
+        command: token,
+        commandArgv: [...globals, ...argv.slice(index + 1)],
+        topLevelHelp: false,
+        version: false
+      };
     }
-    const info = fields.get(key);
-    if (values.length > 1 && info !== undefined && info.kind !== "array" && info.kind !== "other") {
-      throw new CliArgumentError(`--${key} was passed ${values.length} times`);
+    if (!token.startsWith("--")) {
+      return {
+        command: defaultCommand,
+        commandArgv: [...globals, ...argv.slice(index)],
+        topLevelHelp: false,
+        version: false
+      };
     }
-    toolArgs[key] = coerceField(info, values);
-  }
-  return { toolArgs, options };
-}
-function extractCliGlobalOptions(argv, schema) {
-  if (schema === undefined)
-    return { argv: [...argv], globals: {} };
-  const fields = describeSchemaFields(schema);
-  const rest = [];
-  const raw = new Map;
-  let ended = false;
-  for (let i = 0;i < argv.length; i++) {
-    const token = argv[i];
-    if (token === undefined)
-      continue;
-    if (!ended && token === "--")
-      ended = true;
-    const option = ended ? undefined : classifyLongOptionToken(token);
-    const info = option && option.globalKind === undefined ? fields.get(option.name) : undefined;
-    if (!option || !info) {
-      rest.push(token);
+    const option = classifyLongOptionToken(token);
+    if (!option) {
+      return {
+        command: defaultCommand,
+        commandArgv: [...globals, ...argv.slice(index)],
+        topLevelHelp: false,
+        version: false
+      };
+    }
+    if (option.globalKind === "boolean") {
+      globals.push(token);
+      index += 1;
       continue;
     }
-    let { value } = option;
-    if (value === undefined && info.kind === "boolean") {
-      value = "true";
-    } else if (value === undefined) {
-      const next = argv[i + 1];
-      if (next !== undefined && (!next.startsWith("-") || NUMERIC_VALUE.test(next))) {
-        value = next;
-        i++;
+    if (option.globalKind === "value") {
+      globals.push(token);
+      if (!option.inline) {
+        const value = argv[index + 1];
+        if (value === "--help" || value === "-h") {
+          const helpFilter = helpFilterFrom(value, argv.slice(index + 2));
+          return {
+            commandArgv: [],
+            topLevelHelp: true,
+            version: false,
+            ...helpFilter !== undefined && { helpFilter }
+          };
+        }
+        if (value === "--version" || value === "version") {
+          return { commandArgv: [], topLevelHelp: false, version: true };
+        }
+        if (value !== undefined)
+          globals.push(value);
+        index += value === undefined ? 1 : 2;
       } else {
-        throw new CliArgumentError(`--${option.name} requires a value`);
+        index += 1;
       }
+      continue;
     }
-    const existing = raw.get(option.name);
-    if (existing)
-      existing.push(value);
-    else
-      raw.set(option.name, [value]);
-  }
-  const args = {};
-  for (const [name, values] of raw)
-    args[name] = coerceField(fields.get(name), values);
-  const parsed = schema.safeParse(coerceJsonArgs(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 CliArgumentError(`${where}: ${issue?.message ?? "invalid value"}`);
+    return {
+      command: defaultCommand,
+      commandArgv: [...globals, ...argv.slice(index)],
+      topLevelHelp: false,
+      version: false
+    };
   }
-  return { argv: rest, globals: parsed.data };
+  return {
+    command: defaultCommand,
+    commandArgv: globals,
+    topLevelHelp: false,
+    version: false
+  };
 }
+
+// src/tools/cli/args-view.ts
 function resolveCliView(flags, ascending) {
   if (flags.size === 0) {
     if (ascending) {
@@ -775,217 +777,264 @@ function resolveCliView(flags, ascending) {
   throw new CliArgumentError("--top needs --sort, --by, --count-by or --sum to rank");
 }
 
-// src/tools/cli/policy.ts
-var SHORT_ALIAS = /^[A-Za-z]$/;
-var RESERVED_SHORT_OPTIONS = new Set(["h"]);
-function fieldMap(descriptor) {
-  return new Map(jsonSchemaFields(descriptor.presentationSchema).map((field) => [field.name, field]));
-}
-function resolveAliases(command, descriptor, configured) {
-  if (!configured)
-    return new Map;
-  const fields = fieldMap(descriptor);
-  const aliases = new Map;
-  for (const [alias, target] of Object.entries(configured)) {
-    if (!SHORT_ALIAS.test(alias)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "${alias}" must be one ASCII letter`);
+// src/tools/cli/args.ts
+function readCliTokens(argv, fields, config) {
+  const options = {
+    json: false,
+    wait: false,
+    quiet: false,
+    dryRun: false,
+    help: false
+  };
+  const flags = new Map;
+  const boolFlags = new Map;
+  const viewFlags = new Map;
+  let ascending = false;
+  const positionals = [];
+  const pushFlag = (name, value) => {
+    const existing = flags.get(name);
+    if (existing)
+      existing.push(value);
+    else
+      flags.set(name, [value]);
+  };
+  let optionsEnded = false;
+  for (let i = 0;i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === undefined)
+      continue;
+    if (!optionsEnded && tok === "--") {
+      optionsEnded = true;
+      continue;
     }
-    if (RESERVED_SHORT_OPTIONS.has(alias)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" is reserved`);
+    if (optionsEnded || !looksLikeOption(tok)) {
+      positionals.push(tok);
+      continue;
     }
-    if (isUnsafeKey(target) || !fields.has(target)) {
-      throw new Error(`[stitchkit] CLI command "${command}" alias "-${alias}" targets unknown field "${target}"`);
+    if (tok === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (!tok.startsWith("--")) {
+      const match = /^-([A-Za-z])(?:=(.*))?$/.exec(tok);
+      const alias = match?.[1];
+      const field = alias === undefined ? undefined : config.optionAliases?.get(alias);
+      if (!alias || !field)
+        throw new CliArgumentError(`Unknown option "${tok}"`);
+      const inline = match?.[2];
+      const info2 = fields.get(field);
+      if (info2?.kind === "boolean") {
+        boolFlags.set(field, inline === undefined ? true : parseReservedBool(field, inline));
+        continue;
+      }
+      let value2 = inline;
+      if (value2 === undefined) {
+        const next = argv[i + 1];
+        if (next !== undefined && !isOptionToken(next)) {
+          value2 = next;
+          i++;
+        } else {
+          throw new CliArgumentError(`--${field} requires a value`);
+        }
+      }
+      pushFlag(field, value2);
+      continue;
+    }
+    const option = classifyLongOptionToken(tok);
+    if (!option)
+      throw new CliArgumentError(`Unknown option "${tok}"`);
+    const { name } = option;
+    let { value } = option;
+    if (name.length === 0)
+      throw new CliArgumentError("Invalid empty option name");
+    if (option.globalKind === "boolean") {
+      const enabled = value === undefined ? true : parseReservedBool(name, value);
+      if (name === "dry-run")
+        options.dryRun = enabled;
+      else if (name === "json")
+        options.json = enabled;
+      else if (name === "wait")
+        options.wait = enabled;
+      else if (name === "quiet")
+        options.quiet = enabled;
+      else if (name === "ascending")
+        ascending = enabled;
+      else
+        options.help = enabled;
+      continue;
+    }
+    if (option.globalKind === "value") {
+      const next = argv[i + 1];
+      value = value ?? next;
+      if (value === undefined || !option.inline && isOptionToken(value)) {
+        throw new CliArgumentError(`--${name} requires a value`);
+      }
+      if (!option.inline)
+        i++;
+      if (name === "wait-timeout") {
+        const timeout = Number(value);
+        if (!Number.isFinite(timeout) || timeout <= 0) {
+          throw new CliArgumentError("--wait-timeout must be a positive number");
+        }
+        options.waitTimeout = timeout;
+      } else if (VIEW_OPTIONS.has(name)) {
+        if (viewFlags.has(name))
+          throw new CliArgumentError(`--${name} was given twice`);
+        viewFlags.set(name, value);
+      } else {
+        options.outputDir = value;
+      }
+      continue;
+    }
+    if (value === undefined && name.startsWith("no-") && fields.get(name.slice(3))?.kind === "boolean") {
+      boolFlags.set(name.slice(3), false);
+      continue;
+    }
+    const unsafeSegment = name.split(".").find(isUnsafeKey);
+    if (unsafeSegment !== undefined) {
+      throw new CliArgumentError(`Unsafe option name "--${name}"`);
+    }
+    const info = fields.get(name);
+    const rootName = name.split(".")[0] ?? name;
+    if (!fields.has(rootName) && !config.allowUnknown) {
+      throw new CliArgumentError(`Unknown option "--${name}"`);
+    }
+    if (value === undefined) {
+      if (info?.kind === "boolean") {
+        boolFlags.set(name, true);
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !isOptionToken(next)) {
+        value = next;
+        i++;
+      } else {
+        throw new CliArgumentError(`--${name} requires a value`);
+      }
+    }
+    pushFlag(name, value);
+  }
+  return { options, flags, boolFlags, viewFlags, ascending, positionals };
+}
+function buildToolArgs(tokens, fields, declaredPositionals) {
+  const { flags, boolFlags, positionals } = tokens;
+  const toolArgs = {};
+  const fillable = declaredPositionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...declaredPositionals];
+  const variadicTail = declaredPositionals !== undefined && fields.get(fillable[fillable.length - 1] ?? "")?.kind === "array" ? fillable[fillable.length - 1] : undefined;
+  let pi = 0;
+  for (const key of fillable) {
+    if (pi >= positionals.length)
+      break;
+    if (key === variadicTail) {
+      if (flags.has(key)) {
+        throw new CliArgumentError(`--${key} conflicts with the positional values for "${key}" — pass one form, not both`);
+      }
+      toolArgs[key] = coerceField(fields.get(key), positionals.slice(pi), `<${key}>`);
+      pi = positionals.length;
+      break;
     }
-    const existing = aliases.get(target);
-    if (existing !== undefined) {
-      throw new Error(`[stitchkit] CLI command "${command}" field "${target}" has multiple aliases: -${existing}, -${alias}`);
+    if (flags.has(key))
+      continue;
+    const value = positionals[pi++];
+    if (value !== undefined) {
+      toolArgs[key] = coerceField(fields.get(key), [value], `<${key}>`);
     }
-    aliases.set(target, alias);
   }
-  return aliases;
-}
-function resolvePositionals(command, descriptor, configured) {
-  if (configured === undefined)
-    return;
-  const fields = fieldMap(descriptor);
-  const kinds = describeSchemaFields(descriptor.argumentSchema);
-  const seen = new Set;
-  let optionalSeen = false;
-  for (const name of configured) {
-    const field = fields.get(name);
-    if (isUnsafeKey(name) || !field || !kinds.has(name)) {
-      throw new Error(`[stitchkit] CLI command "${command}" positional targets unknown field "${name}"`);
-    }
-    if (seen.has(name)) {
-      throw new Error(`[stitchkit] CLI command "${command}" repeats positional field "${name}"`);
+  if (pi < positionals.length) {
+    throw new CliArgumentError(`Unexpected positional argument "${positionals[pi]}"`);
+  }
+  for (const [key, value] of boolFlags) {
+    toolArgs[key] = value;
+  }
+  const dottedRoots = new Map;
+  for (const key of flags.keys()) {
+    const dot = key.indexOf(".");
+    if (dot > 0)
+      dottedRoots.set(key.slice(0, dot), key);
+  }
+  for (const [root, dotted] of dottedRoots) {
+    if (flags.has(root)) {
+      throw new CliArgumentError(`--${root} conflicts with --${dotted} — pass one form, not both`);
     }
-    if (kinds.get(name)?.kind === "boolean") {
-      throw new Error(`[stitchkit] CLI command "${command}" boolean field "${name}" cannot be positional`);
+  }
+  for (const [key, values] of flags) {
+    if (key.includes(".")) {
+      if (values.length > 1) {
+        throw new CliArgumentError(`--${key} was passed ${values.length} times`);
+      }
+      setNested(toolArgs, key.split("."), looseCoerce(values[0] ?? ""));
+      continue;
     }
-    if (optionalSeen && field.required) {
-      throw new Error(`[stitchkit] CLI command "${command}" required positional "${name}" cannot follow an optional positional`);
+    const info = fields.get(key);
+    if (values.length > 1 && info !== undefined && info.kind !== "array" && info.kind !== "other") {
+      throw new CliArgumentError(`--${key} was passed ${values.length} times`);
     }
-    if (!field.required)
-      optionalSeen = true;
-    seen.add(name);
+    toolArgs[key] = coerceField(info, values, `--${key}`);
   }
-  return [...configured];
-}
-function applyCliPresentationPolicy(command, descriptor, config) {
-  const base = { ...descriptor, aliases: new Map };
-  const configuredAliases = config.optionAliases && Object.hasOwn(config.optionAliases, command) ? config.optionAliases[command] : undefined;
-  const configuredPositionals = config.positionals && Object.hasOwn(config.positionals, command) ? config.positionals[command] : undefined;
-  return {
-    ...base,
-    aliases: resolveAliases(command, base, configuredAliases),
-    positionals: resolvePositionals(command, base, configuredPositionals)
-  };
+  return toolArgs;
 }
-function assertCliPoliciesResolved(commands, config) {
-  const configuredNames = new Set([
-    ...Object.keys(config.optionAliases ?? {}),
-    ...Object.keys(config.positionals ?? {})
-  ]);
-  if (config.defaultCommand !== undefined)
-    configuredNames.add(config.defaultCommand);
-  for (const name of configuredNames) {
-    if (!commands.has(name)) {
-      throw new Error(`[stitchkit] CLI policy targets unavailable command "${name}"`);
-    }
+function parseCliArgs(argv, schema, config = {}) {
+  const fields = describeSchemaFields(schema);
+  for (const name of config.knownFields ?? []) {
+    if (!fields.has(name))
+      fields.set(name, { kind: "other" });
   }
+  const tokens = readCliTokens(argv, fields, config);
+  const { options } = tokens;
+  const view = resolveCliView(tokens.viewFlags, tokens.ascending);
+  if (view)
+    options.view = view;
+  return { toolArgs: buildToolArgs(tokens, fields, config.positionals), options };
 }
-
-// src/tools/cli/invoke.ts
-function parseCliGlobals(schema, globals) {
-  if (!schema)
-    return globals ?? {};
-  return schema.parse(globals ?? {});
-}
-function cliInvocationResult(result, toolName, config) {
-  if (result.ok)
-    return { ok: true, exitCode: 0, data: result.data };
-  const normalized = toolErrorFromResult(result);
-  const hints = [];
-  if (result.hint)
-    hints.push(result.hint);
-  const global = config.errorHint?.(toolName, result.code);
-  if (global)
-    hints.push(global);
-  return {
-    ok: false,
-    exitCode: cliExitCode(result, config.exitCodes),
-    error: {
-      code: result.code,
-      message: normalized.message,
-      ...result.details !== undefined && { details: result.details },
-      ...hints.length > 0 && { hint: hints.join(" ") },
-      ...result.retryable !== undefined && { retryable: result.retryable }
+function extractCliGlobalOptions(argv, schema) {
+  if (schema === undefined)
+    return { argv: [...argv], globals: {} };
+  const fields = describeSchemaFields(schema);
+  const rest = [];
+  const raw = new Map;
+  let ended = false;
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === undefined)
+      continue;
+    if (!ended && token === "--")
+      ended = true;
+    const option = ended ? undefined : classifyLongOptionToken(token);
+    const info = option && option.globalKind === undefined ? fields.get(option.name) : undefined;
+    if (!option || !info) {
+      rest.push(token);
+      continue;
     }
-  };
-}
-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,
-    coerceJsonArgs: config.coerceJsonArgs
-  });
-  return {
-    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({
-          ok: false,
-          code: "NOT_FOUND",
-          details: { message: `Unknown command "${command}"` }
-        }, command, config);
-      }
-      let result;
-      try {
-        result = await runTool(tool, args);
-      } catch (error) {
-        result = toolResultFromError(error);
+    let { value } = option;
+    if (value === undefined && info.kind === "boolean") {
+      value = "true";
+    } else if (value === undefined) {
+      const next = argv[i + 1];
+      if (next !== undefined && !isOptionToken(next)) {
+        value = next;
+        i++;
+      } else {
+        throw new CliArgumentError(`--${option.name} requires a value`);
       }
-      return cliInvocationResult(result, command, config);
-    }
-  };
-}
-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);
     }
+    const existing = raw.get(option.name);
+    if (existing)
+      existing.push(value);
+    else
+      raw.set(option.name, [value]);
   }
-  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 ?? [];
-  const tools = new Map;
-  const help = new Map(nativeHelp);
-  for (const { mountable } of collectToolSurface({
-    surface: { services, runtimeTools },
-    transport: "CLI"
-  })) {
-    const descriptor = applyCliPresentationPolicy(mountable.name, managedCliDescriptor(mountable), config);
-    assertShape?.(mountable.name, descriptor, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
-    tools.set(mountable.name, mountable);
-    help.set(mountable.name, descriptor);
+  const args = {};
+  for (const [name, values] of raw) {
+    args[name] = coerceField(fields.get(name), values, `--${name}`);
   }
-  assertCliPoliciesResolved(help, config);
-  return { tools, help };
-}
-function managedCliDescriptor(tool) {
-  return {
-    description: tool.method.desc,
-    argumentSchema: tool.argumentSchema,
-    presentationSchema: tool.presentationSchema
-  };
+  const parsed = schema.safeParse(coerceJsonArgs(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 CliArgumentError(`${where}: ${issue?.message ?? "invalid value"}`);
+  }
+  return { argv: rest, globals: parsed.data };
 }
 
 // src/tools/cli/view.ts
@@ -2254,4 +2303,4 @@ async function createCli(config) {
   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 };
+export { fetchGuarded, PrivateAddressRefusal, fetchPinnedDocument, readCapped, WaitTimeoutError, runWaitOperation, defineCliCommand, DEFAULT_EXIT_CODES, cliExitCode, emitResult, CliArgumentError, cliInvocationResult, createCliInvoker, routeCliArgv, parseCliArgs, extractCliGlobalOptions, renderCliView, pollUntilDone, createCli };