stitchkit 0.90.2 → 0.90.4

package/dist/{index-8dph3pw6.js → index-y47z614h.js}

@@ -3,14 +3,15 @@ import {
 } from "./index-sbdmyz75.js";
 import {
   collectToolSurface
-} from "./index-wb15909q.js";
+} from "./index-kzxpsf8y.js";
 import {
   createToolRunner,
   formatToolError
-} from "./index-2hrfpw2c.js";
+} from "./index-32vjke6q.js";
 import {
+  toolErrorFromResult,
   toolResultFromError
-} from "./index-44ht2790.js";
+} from "./index-vcnfwrtr.js";
 import {
   formatZodError,
   validateDeclaredOutput
@@ -26,7 +27,7 @@ import {
   assertUniqueToolName,
   buildToolPresentationSchema,
   objectShapeKeys
-} from "./index-r159gjwy.js";
+} from "./index-fenaekmk.js";
 import {
   jsonSchemaFields
 } from "./index-cby4ar3v.js";
@@ -38,7 +39,8 @@ import {
 import { z } from "zod";
 var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
 var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help"]);
-var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir"]);
+var VIEW_OPTIONS = new Set(["count-by", "sum", "by", "top", "table"]);
+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 === "--")
@@ -314,6 +316,7 @@ function parseCliArgs(argv, schema, config = {}) {
   }
   const flags = new Map;
   const boolFlags = new Map;
+  const viewFlags = new Map;
   const positionals = [];
   const pushFlag = (name, value) => {
     const existing = flags.get(name);
@@ -399,6 +402,10 @@ function parseCliArgs(argv, schema, config = {}) {
           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;
       }
@@ -432,12 +439,24 @@ function parseCliArgs(argv, schema, config = {}) {
     }
     pushFlag(name, value);
   }
+  const view = resolveCliView(viewFlags);
+  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;
+    }
     if (flags.has(key))
       continue;
     const value = positionals[pi++];
@@ -477,6 +496,112 @@ function parseCliArgs(argv, schema, config = {}) {
   }
   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);
+      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++;
+      } else {
+        throw new CliArgumentError(`--${option.name} requires a value`);
+      }
+    }
+    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 { argv: rest, globals: parsed.data };
+}
+function resolveCliView(flags) {
+  if (flags.size === 0)
+    return;
+  const countBy = flags.get("count-by");
+  const sum = flags.get("sum");
+  const table = flags.get("table");
+  const by = flags.get("by");
+  const rawTop = flags.get("top");
+  const named = [
+    ["--count-by", countBy],
+    ["--sum", sum],
+    ["--table", table]
+  ].filter(([, value]) => value !== undefined);
+  if (named.length > 1) {
+    throw new CliArgumentError(`${named.map(([flag]) => flag).join(" and ")} ask for different shapes — pass one`);
+  }
+  let top;
+  if (rawTop !== undefined) {
+    top = Number(rawTop);
+    if (!Number.isInteger(top) || top <= 0) {
+      throw new CliArgumentError("--top must be a positive whole number");
+    }
+  }
+  if (table !== undefined) {
+    if (by !== undefined || top !== undefined) {
+      throw new CliArgumentError("--table lists records; it takes neither --by nor --top");
+    }
+    const fields = table.split(",").map((field) => field.trim()).filter(Boolean);
+    if (fields.length === 0)
+      throw new CliArgumentError("--table needs at least one field");
+    return { kind: "table", fields };
+  }
+  if (sum !== undefined) {
+    if (top !== undefined && by === undefined) {
+      throw new CliArgumentError("--top needs --by: a single sum has nothing to rank");
+    }
+    return {
+      kind: "sum",
+      field: sum,
+      ...by !== undefined && { by },
+      ...top !== undefined && { top }
+    };
+  }
+  if (countBy !== undefined) {
+    if (by !== undefined) {
+      throw new CliArgumentError("--count-by already names the grouping field; drop --by");
+    }
+    return { kind: "count", field: countBy, ...top !== undefined && { top } };
+  }
+  if (by !== undefined) {
+    if (top === undefined) {
+      throw new CliArgumentError("--by groups a view; pass --count-by, --sum or --top with it");
+    }
+    return { kind: "count", field: by, top };
+  }
+  throw new CliArgumentError("--top needs --by, --count-by or --sum to rank");
+}
 
 // src/tools/cli-command.ts
 function defineCliCommand(definition) {
@@ -509,7 +634,7 @@ function cliCommandPresentationSchema(definition) {
     unrepresentable: "any"
   });
 }
-async function executeCliCommand(definition, rawArgs, options, writers, coerceJson) {
+async function executeCliCommand(definition, rawArgs, options, writers, coerceJson, globals = {}) {
   let parsed;
   try {
     parsed = definition.input.safeParse(coerceJson ? coerceJsonArgs(rawArgs, definition.input) : rawArgs);
@@ -527,6 +652,7 @@ async function executeCliCommand(definition, rawArgs, options, writers, coerceJs
     const data = await definition.handler({
       input: parsed.data,
       options,
+      globals,
       ...writers
     });
     const checked = validateDeclaredOutput(definition.output, data);
@@ -573,6 +699,126 @@ function emitResult(result, writers, opts) {
   return codes[result.code] ?? 1;
 }
 
+// src/tools/cli-view.ts
+var ABSENT = "(absent)";
+function selectRecords(data) {
+  if (Array.isArray(data))
+    return data;
+  if (isRecord(data)) {
+    const arrays = Object.entries(data).filter(([, value]) => Array.isArray(value));
+    const only = arrays[0];
+    if (arrays.length === 1 && only && Array.isArray(only[1]))
+      return only[1];
+    if (arrays.length > 1) {
+      throw new CliArgumentError(`an aggregate needs one collection, but the result carries several: ${arrays.map(([key]) => key).join(", ")} — name the shape you want with jq instead`);
+    }
+  }
+  throw new CliArgumentError("an aggregate needs a collection; this result is not one");
+}
+function readField(record, path) {
+  let current = record;
+  for (const segment of path) {
+    if (!isRecord(current))
+      return;
+    current = current[segment];
+  }
+  return current;
+}
+function fieldPath(field) {
+  const path = field.split(".");
+  if (path.some((segment) => segment.length === 0 || isUnsafeKey(segment))) {
+    throw new CliArgumentError(`"${field}" is not a readable field path`);
+  }
+  return path;
+}
+function availableFields(records) {
+  const keys = new Set;
+  for (const record of records) {
+    if (isRecord(record))
+      for (const key of Object.keys(record))
+        keys.add(key);
+  }
+  return [...keys].sort();
+}
+function assertFieldPresent(records, field) {
+  const path = fieldPath(field);
+  const present = records.some((record) => readField(record, path) !== undefined);
+  if (!present) {
+    const available = availableFields(records);
+    throw new CliArgumentError(`no record carries the field "${field}"${available.length > 0 ? ` — available: ${available.join(", ")}` : ""}`);
+  }
+  return path;
+}
+function groupKey(value) {
+  if (value === undefined)
+    return ABSENT;
+  if (value === null)
+    return "null";
+  if (typeof value === "object")
+    return JSON.stringify(value);
+  return String(value);
+}
+function ordered(totals, top) {
+  const entries = [...totals].sort(([leftKey, left], [rightKey, right]) => right === left ? leftKey.localeCompare(rightKey) : right - left);
+  const sliced = top === undefined ? entries : entries.slice(0, top);
+  return Object.fromEntries(sliced);
+}
+function numericValue(value, field) {
+  if (value === undefined || value === null)
+    return;
+  if (typeof value === "number" && Number.isFinite(value))
+    return value;
+  if (typeof value === "bigint")
+    return Number(value);
+  throw new CliArgumentError(`--sum ${field}: "${groupKey(value)}" is not a number`);
+}
+function renderTable(records, fields) {
+  const paths = fields.map((field) => assertFieldPresent(records, field));
+  const cell = (value) => {
+    if (value === undefined)
+      return "";
+    if (value === null)
+      return "null";
+    if (typeof value === "object")
+      return JSON.stringify(value);
+    return String(value);
+  };
+  const rows = records.map((record) => paths.map((path) => cell(readField(record, path))));
+  const widths = fields.map((field, column) => Math.max(field.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const line = (cells) => cells.map((value, column) => value.padEnd(widths[column] ?? value.length)).join("  ").trimEnd();
+  return `${[line(fields), line(widths.map((width) => "-".repeat(width))), ...rows.map(line)].join(`
+`)}
+`;
+}
+function renderCliView(data, view) {
+  const records = selectRecords(data);
+  if (view.kind === "table")
+    return { kind: "text", text: renderTable(records, view.fields) };
+  if (view.kind === "count") {
+    const path2 = assertFieldPresent(records, view.field);
+    const totals2 = new Map;
+    for (const record of records) {
+      const key = groupKey(readField(record, path2));
+      totals2.set(key, (totals2.get(key) ?? 0) + 1);
+    }
+    return { kind: "json", data: ordered(totals2, view.top) };
+  }
+  const path = assertFieldPresent(records, view.field);
+  if (view.by === undefined) {
+    let total = 0;
+    for (const record of records)
+      total += numericValue(readField(record, path), view.field) ?? 0;
+    return { kind: "json", data: total };
+  }
+  const byPath = assertFieldPresent(records, view.by);
+  const totals = new Map;
+  for (const record of records) {
+    const key = groupKey(readField(record, byPath));
+    totals.set(key, (totals.get(key) ?? 0) + (numericValue(readField(record, path), view.field) ?? 0));
+  }
+  return { kind: "json", data: ordered(totals, view.top) };
+}
+
 // src/tools/wait-core.ts
 var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
 var DEFAULT_TIMEOUT = 600;
@@ -1121,7 +1367,11 @@ var GLOBAL_OPTIONS = [
   ["--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"]
+  ["--help, -h", "Show help for a command"],
+  ["--count-by <field>", "Count records per distinct value of a field"],
+  ["--sum <field>", "Total a numeric field, optionally grouped by --by"],
+  ["--top <n> --by <f>", "Keep only the n largest groups"],
+  ["--table <a,b>", "Render the named fields as an aligned table"]
 ];
 async function readPipedStdin() {
   if (process.stdin.isTTY)
@@ -1190,7 +1440,19 @@ function collectPassthrough(toolArgs, field, knownKeys) {
   const base = passthroughBase(toolArgs[field]);
   toolArgs[field] = base ? { ...base, ...bag } : bag;
 }
-function renderTopHelp(name, version, commands, defaultCommand) {
+function applicationOptionLines(fields) {
+  if (fields.length === 0)
+    return [];
+  const labels = new Map(fields.map((field) => [field.name, `--${field.name} <${typeLabel(field.schema)}>`]));
+  const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
+  return [
+    "",
+    "Application options:",
+    ...fields.map((field) => `  ${padRight(labels.get(field.name) ?? `--${field.name}`, width)}  ${field.description ?? ""}`.trimEnd())
+  ];
+}
+function renderTopHelp(input) {
+  const { name, version, commands, defaultCommand } = input;
   const lines = [
     `${name} ${version}`,
     "",
@@ -1202,29 +1464,35 @@ function renderTopHelp(name, version, commands, defaultCommand) {
   for (const [command, descriptor] of commands) {
     lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}${command === defaultCommand ? " (default)" : ""}`);
   }
+  if (input.unavailable !== undefined) {
+    lines.push("", `Managed commands are unavailable: ${input.unavailable}`);
+  }
   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(...applicationOptionLines(input.applicationOptions));
   lines.push("", `Run "${name} <command> --help" for command-specific flags.`);
   return `${lines.join(`
 `)}
 `;
 }
-function renderCommandHelp(name, command, descriptor) {
+function renderCommandHelp(name, command, descriptor, applicationOptions = []) {
   const fields = jsonSchemaFields(descriptor.presentationSchema);
   const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+  const kinds = describeSchemaFields(descriptor.argumentSchema);
   const positionals = [];
-  const positionalNames = descriptor.positionals ?? [...describeSchemaFields(descriptor.argumentSchema)].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
+  const positionalNames = descriptor.positionals ?? [...kinds].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
   for (const fieldName of positionalNames) {
     const field = fieldsByName.get(fieldName);
     if (field)
       positionals.push(field);
   }
-  const positionalSyntax = new Map(positionals.map((field) => [
-    field.name,
-    field.required ? `<${field.name}>` : `[${field.name}]`
-  ]));
+  const variadicTail = descriptor.positionals !== undefined && kinds.get(descriptor.positionals[descriptor.positionals.length - 1] ?? "")?.kind === "array" ? descriptor.positionals[descriptor.positionals.length - 1] : undefined;
+  const positionalSyntax = new Map(positionals.map((field) => {
+    const label = field.name === variadicTail ? `${field.name}...` : field.name;
+    return [field.name, field.required ? `<${label}>` : `[${label}]`];
+  }));
   const usage = [
     `Usage: ${name} ${command}`,
     ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
@@ -1248,6 +1516,9 @@ function renderCommandHelp(name, command, descriptor) {
     }
     lines.push("");
   }
+  const applicationLines = applicationOptionLines(applicationOptions);
+  if (applicationLines.length > 0)
+    lines.push(...applicationLines.slice(1), "");
   return `${lines.join(`
 `)}
 `;
@@ -1266,15 +1537,20 @@ function nativeDescriptor(definition) {
     presentationSchema: cliCommandPresentationSchema(definition)
   };
 }
-function assertCommandShape(name, descriptor, exists, passthroughField) {
+function assertCommandShape(name, descriptor, exists, passthroughField, applicationGlobals = new Set) {
   assertUniqueToolName(name, exists, "CLI command");
   if (name === "help" || name === "version") {
     throw new Error(`[stitchkit] CLI command "${name}" is reserved`);
   }
-  const conflicting = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name).filter((field) => RESERVED_CLI_OPTIONS.has(field));
+  const fieldNames = jsonSchemaFields(descriptor.presentationSchema).map((field) => field.name);
+  const conflicting = fieldNames.filter((field) => RESERVED_CLI_OPTIONS.has(field));
   if (conflicting.length > 0) {
     throw new Error(`[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`);
   }
+  const shadowed = fieldNames.filter((field) => applicationGlobals.has(field));
+  if (shadowed.length > 0) {
+    throw new Error(`[stitchkit] CLI command "${name}" declares field(s) shadowed by application global options: ${shadowed.join(", ")}`);
+  }
   if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
     throw new Error(`[stitchkit] CLI command "${name}" cannot alias passthrough field "${passthroughField}"`);
   }
@@ -1338,30 +1614,78 @@ async function downloadResults(files, dir, stderr, quiet, allowPrivate, maxBytes
   return succeeded;
 }
 async function createCli(config) {
+  let pendingWrite;
+  let writeFailed = false;
   const writeFd = (fd, text) => {
-    try {
-      writeSync(fd, text);
-    } catch {
-      (fd === 1 ? process.stdout : process.stderr).write(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) => void process.exit(code));
+  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;
   if (config.auth !== undefined && config.resolveAuth !== undefined) {
     throw new Error("[stitchkit] createCli: use either auth or resolveAuth, not both");
   }
+  const applicationOptions = config.globalOptions ? jsonSchemaFields(buildToolPresentationSchema({
+    inputSchema: config.globalOptions,
+    unrepresentable: "any"
+  })) : [];
+  const applicationGlobalNames = new Set(applicationOptions.map((field) => field.name));
+  for (const name of applicationGlobalNames) {
+    if (RESERVED_CLI_OPTIONS.has(name)) {
+      throw new Error(`[stitchkit] CLI global option "--${name}" is reserved by the framework`);
+    }
+  }
   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]);
+    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name], applicationGlobalNames);
     nativeCommands.set(definition.name, definition);
     nativeHelp.set(definition.name, descriptor2);
   }
-  const route = routeCliArgv(argv, config.defaultCommand);
+  let globals;
+  let routableArgv;
+  try {
+    const lifted = extractCliGlobalOptions(argv, config.globalOptions);
+    globals = lifted.globals;
+    routableArgv = lifted.argv;
+  } catch (error) {
+    if (!(error instanceof CliArgumentError))
+      throw error;
+    stderr(`${error.message}
+`);
+    return exit(2);
+  }
+  const typedGlobals = globals;
+  const route = routeCliArgv(routableArgv, config.defaultCommand);
   if (route.error) {
     stderr(`${route.error}
 `);
@@ -1381,7 +1705,7 @@ async function createCli(config) {
     if (!descriptor2)
       throw new Error("[stitchkit] native CLI descriptor invariant failed");
     if (helpRequested) {
-      stdout(renderCommandHelp(config.name, command, descriptor2));
+      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
       return exit(0);
     }
     const prepared2 = await prepareInvocation(command, commandArgv, descriptor2, config, readStdin);
@@ -1392,7 +1716,7 @@ async function createCli(config) {
     }
     const { toolArgs: toolArgs2, options: options2 } = prepared2;
     if (options2.help) {
-      stdout(renderCommandHelp(config.name, command, descriptor2));
+      stdout(renderCommandHelp(config.name, command, descriptor2, applicationOptions));
       return exit(0);
     }
     if (options2.wait) {
@@ -1415,7 +1739,7 @@ async function createCli(config) {
 `);
       return exit(0);
     }
-    const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true);
+    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) {
@@ -1433,12 +1757,26 @@ async function createCli(config) {
   }
   let authPromise;
   const resolveIdentity = () => {
-    authPromise ??= Promise.resolve(config.resolveAuth ? config.resolveAuth() : config.auth);
+    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) => {
-    const auth = dynamicSurface || forExecution ? await resolveIdentity() : undefined;
+    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 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;
@@ -1448,19 +1786,34 @@ async function createCli(config) {
       transport: "CLI"
     })) {
       const descriptor2 = applyCliPresentationPolicy(mountable.name, managedDescriptor(mountable), config);
-      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name), config.passthrough?.[mountable.name]);
+      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name), config.passthrough?.[mountable.name], applicationGlobalNames);
       tools.set(mountable.name, mountable);
       help.set(mountable.name, descriptor2);
     }
     assertCliPoliciesResolved(help, config);
-    return { auth, help, tools };
+    return { resolved: true, auth, help, tools };
   };
   const topLevelHelp = route.topLevelHelp || command === undefined || command === "help" || command === "--help" || command === "-h";
   const managed = await buildManagedSurface(!topLevelHelp && !helpRequested);
   if (topLevelHelp) {
-    stdout(renderTopHelp(config.name, config.version, managed.help, config.defaultCommand));
+    stdout(renderTopHelp({
+      name: config.name,
+      version: config.version,
+      commands: managed.help,
+      defaultCommand: config.defaultCommand,
+      applicationOptions,
+      ...managed.resolved ? {} : { unavailable: managed.reason }
+    }));
     return exit(0);
   }
+  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 }
+    }));
+  }
   const tool = managed.tools.get(command);
   if (!tool) {
     stderr(`Unknown command "${command}". Run "${config.name} --help" for the command list.
@@ -1471,7 +1824,7 @@ async function createCli(config) {
   if (!descriptor)
     throw new Error("[stitchkit] managed CLI descriptor invariant failed");
   if (helpRequested) {
-    stdout(renderCommandHelp(config.name, command, descriptor));
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
   const prepared = await prepareInvocation(command, commandArgv, descriptor, config, readStdin);
@@ -1497,7 +1850,7 @@ async function createCli(config) {
     return exit(2);
   }
   if (options.help) {
-    stdout(renderCommandHelp(config.name, command, descriptor));
+    stdout(renderCommandHelp(config.name, command, descriptor, applicationOptions));
     return exit(0);
   }
   if (options.dryRun) {
@@ -1507,7 +1860,7 @@ async function createCli(config) {
   }
   const runTool = createToolRunner({
     source: "cli",
-    context: { ...config.context?.(managed.auth), signal: config.signal },
+    context: { ...config.context?.(managed.auth, typedGlobals), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,
@@ -1545,6 +1898,23 @@ async function createCli(config) {
   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);
   }
+  if (options.view && result.ok) {
+    let viewed;
+    try {
+      viewed = renderCliView(result.data, options.view);
+    } catch (error) {
+      if (!(error instanceof CliArgumentError))
+        throw error;
+      stderr(`${error.message}
+`);
+      return exit(2);
+    }
+    if (viewed.kind === "text") {
+      stdout(viewed.text);
+      return exit(downloadsOk ? 0 : 1);
+    }
+    result = { ...result, data: viewed.data };
+  }
   const exitCode = emitResult(result, { stdout, stderr }, {
     json: options.json,
     toolName: command,
@@ -1554,4 +1924,4 @@ async function createCli(config) {
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };
+export { WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, routeCliArgv, CliArgumentError, parseCliArgs, extractCliGlobalOptions, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, renderCliView, pollUntilDone, createCli };

package/dist/testing.js

@@ -48,7 +48,7 @@ import {
   mcpProjectionCandidate,
   prepareProjectedMcpTools,
   projectToolSurface
-} from "./index-r159gjwy.js";
+} from "./index-fenaekmk.js";
 import {
   toJsonSchema
 } from "./index-cby4ar3v.js";