stitchkit 0.59.0 → 0.59.2

package/dist/cli.d.ts

@@ -20,5 +20,6 @@ export { type CliConfig, type CliSurfaceSource, createCli } from './tools/cli';
 export { type CliRunOptions, type ParsedCliArgs, parseCliArgs } from './tools/cli-args';
 export { type CliCommandContext, type CliCommandDefinition, type CliCommandDefinitionBase, type CliCommandDefinitionWithOutput, type CliCommandDefinitionWithoutOutput, defineCliCommand, } from './tools/cli-command';
 export { type CliWriters, DEFAULT_EXIT_CODES, type EmitOptions, type ExitCodeMap, emitResult, } from './tools/cli-format';
+export type { CliPresentationPolicyConfig } from './tools/cli-policy';
 export { type CliWaitConfig, type PollParams, pollUntilDone } from './tools/cli-wait';
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACtC,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACxF,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EACnC,KAAK,iCAAiC,EACtC,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,UAAU,EACf,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-zk5zn2nh.js";
+} from "./index-3nwng7hs.js";
 import"./index-sa2mbwa7.js";
 import"./index-sbdmyz75.js";
 import"./index-1tkyng3g.js";

package/dist/{index-zk5zn2nh.js → index-3nwng7hs.js}

@@ -182,6 +182,105 @@ 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 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
+  };
+}
+function routeCliArgv(argv, defaultCommand) {
+  if (defaultCommand === undefined) {
+    const [command, ...commandArgv] = argv;
+    return { command, commandArgv, topLevelHelp: false, version: false };
+  }
+  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 "--"'
+      };
+    }
+    if (token === "--help" || token === "-h") {
+      return { commandArgv: [], topLevelHelp: true, version: false };
+    }
+    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") {
+          return { commandArgv: [], topLevelHelp: true, version: false };
+        }
+        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
+  };
+}
 
 class CliArgumentError extends Error {
   name = "CliArgumentError";
@@ -383,14 +482,38 @@ function parseCliArgs(argv, schema, config = {}) {
       continue;
     }
     if (!tok.startsWith("--")) {
-      throw new CliArgumentError(`Unknown option "${tok}"`);
+      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;
     }
-    const eq = tok.indexOf("=");
-    const name = eq >= 0 ? tok.slice(2, eq) : tok.slice(2);
-    let value = eq >= 0 ? tok.slice(eq + 1) : undefined;
+    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 (BOOL_OPTIONS.has(name)) {
+    if (option.globalKind === "boolean") {
       const enabled = value === undefined ? true : parseReservedBool(name, value);
       if (name === "dry-run")
         options.dryRun = enabled;
@@ -404,13 +527,13 @@ function parseCliArgs(argv, schema, config = {}) {
         options.help = enabled;
       continue;
     }
-    if (VALUE_OPTIONS.has(name)) {
+    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 (eq < 0)
+      if (!option.inline)
         i++;
       if (name === "wait-timeout") {
         const timeout = Number(value);
@@ -452,7 +575,7 @@ function parseCliArgs(argv, schema, config = {}) {
     pushFlag(name, value);
   }
   const toolArgs = {};
-  const fillable = [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name);
+  const fillable = config.positionals === undefined ? [...fields.entries()].filter(([, info]) => info.kind !== "boolean").map(([name]) => name) : [...config.positionals];
   let pi = 0;
   for (const key of fillable) {
     if (pi >= positionals.length)
@@ -501,6 +624,27 @@ function parseCliArgs(argv, schema, config = {}) {
 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,
@@ -1032,6 +1176,86 @@ async function writeDownload(root, target, data) {
   await writeFile(target, data);
 }
 
+// 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);
+  }
+  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 (kinds.get(name)?.kind === "boolean") {
+      throw new Error(`[stitchkit] CLI command "${command}" boolean field "${name}" cannot be positional`);
+    }
+    if (optionalSeen && field.required) {
+      throw new Error(`[stitchkit] CLI command "${command}" required positional "${name}" cannot follow an optional positional`);
+    }
+    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}"`);
+    }
+  }
+}
+
 // src/tools/surface.ts
 function collectToolSurface({
   surface,
@@ -1149,17 +1373,17 @@ function collectPassthrough(toolArgs, field, knownKeys) {
   const base = passthroughBase(toolArgs[field]);
   toolArgs[field] = base ? { ...base, ...bag } : bag;
 }
-function renderTopHelp(name, version, commands) {
+function renderTopHelp(name, version, commands, defaultCommand) {
   const lines = [
     `${name} ${version}`,
     "",
-    `Usage: ${name} <command> [args] [--flags]`,
+    `Usage: ${name} ${defaultCommand ? "[command]" : "<command>"} [args] [--flags]`,
     "",
     "Commands:"
   ];
   const width = Math.max(0, ...[...commands.keys()].map((key) => key.length));
   for (const [command, descriptor] of commands) {
-    lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}`);
+    lines.push(`  ${padRight(command, width)}  ${summarize(descriptor.description)}${command === defaultCommand ? " (default)" : ""}`);
   }
   lines.push("", "Global options:");
   const optWidth = Math.max(...GLOBAL_OPTIONS.map(([flag]) => flag.length));
@@ -1174,9 +1398,8 @@ function renderCommandHelp(name, command, descriptor) {
   const fields = jsonSchemaFields(descriptor.presentationSchema);
   const fieldsByName = new Map(fields.map((field) => [field.name, field]));
   const positionals = [];
-  for (const [fieldName, info] of describeSchemaFields(descriptor.argumentSchema)) {
-    if (info.kind === "boolean")
-      continue;
+  const positionalNames = descriptor.positionals ?? [...describeSchemaFields(descriptor.argumentSchema)].filter(([, info]) => info.kind !== "boolean").map(([fieldName]) => fieldName);
+  for (const fieldName of positionalNames) {
     const field = fieldsByName.get(fieldName);
     if (field)
       positionals.push(field);
@@ -1195,10 +1418,9 @@ function renderCommandHelp(name, command, descriptor) {
     lines.push("Arguments:");
     const labels = new Map(fields.map((field) => {
       const positional = positionalSyntax.get(field.name);
-      return [
-        field.name,
-        positional ? `${positional} | --${field.name}` : `--${field.name}`
-      ];
+      const alias = descriptor.aliases.get(field.name);
+      const option = alias ? `-${alias}, --${field.name}` : `--${field.name}`;
+      return [field.name, positional ? `${positional} | ${option}` : option];
     }));
     const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
     for (const f of fields) {
@@ -1227,7 +1449,7 @@ function nativeDescriptor(definition) {
     presentationSchema: cliCommandPresentationSchema(definition)
   };
 }
-function assertCommandShape(name, descriptor, exists) {
+function assertCommandShape(name, descriptor, exists, passthroughField) {
   assertUniqueToolName(name, exists, "CLI command");
   if (name === "help" || name === "version") {
     throw new Error(`[stitchkit] CLI command "${name}" is reserved`);
@@ -1236,13 +1458,18 @@ function assertCommandShape(name, descriptor, exists) {
   if (conflicting.length > 0) {
     throw new Error(`[stitchkit] CLI command "${name}" declares reserved option field(s): ${conflicting.join(", ")}`);
   }
+  if (passthroughField !== undefined && descriptor.aliases.has(passthroughField)) {
+    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)
+      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))
@@ -1253,8 +1480,14 @@ async function prepareInvocation(command, commandArgv, descriptor, config, readS
   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)
-      toolArgs[firstUnset.name] = piped;
+    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) {
@@ -1306,13 +1539,19 @@ async function createCli(config) {
   const nativeCommands = new Map;
   const nativeHelp = new Map;
   for (const definition of config.commands ?? []) {
-    const descriptor2 = nativeDescriptor(definition);
-    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name));
+    const descriptor2 = applyCliPresentationPolicy(definition.name, nativeDescriptor(definition), config);
+    assertCommandShape(definition.name, descriptor2, nativeCommands.has(definition.name), config.passthrough?.[definition.name]);
     nativeCommands.set(definition.name, definition);
     nativeHelp.set(definition.name, descriptor2);
   }
-  const [command, ...commandArgv] = argv;
-  if (command === "--version" || command === "version") {
+  const route = routeCliArgv(argv, config.defaultCommand);
+  if (route.error) {
+    stderr(`${route.error}
+`);
+    return exit(2);
+  }
+  const { command, commandArgv } = route;
+  if (route.version || command === "--version" || command === "version") {
     stdout(`${config.name} ${config.version}
 `);
     return exit(0);
@@ -1360,13 +1599,20 @@ async function createCli(config) {
       return exit(0);
     }
     const result2 = await executeCliCommand(native, toolArgs2, options2, { stdout, stderr }, config.coerceJsonArgs ?? true);
-    const exitCode2 = emitResult(result2, { stdout, stderr }, {
-      json: options2.json,
-      toolName: command,
-      errorHint: config.errorHint,
-      exitCodes: { ...DEFAULT_EXIT_CODES, ...config.exitCodes }
-    });
-    return exit(exitCode2);
+    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);
   }
   let authPromise;
   const resolveIdentity = () => {
@@ -1384,17 +1630,18 @@ async function createCli(config) {
       surface: { services, runtimeTools },
       transport: "CLI"
     })) {
-      const descriptor2 = managedDescriptor(mountable);
-      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name));
+      const descriptor2 = applyCliPresentationPolicy(mountable.name, managedDescriptor(mountable), config);
+      assertCommandShape(mountable.name, descriptor2, help.has(mountable.name), config.passthrough?.[mountable.name]);
       tools.set(mountable.name, mountable);
       help.set(mountable.name, descriptor2);
     }
+    assertCliPoliciesResolved(help, config);
     return { auth, help, tools };
   };
-  const topLevelHelp = command === undefined || command === "help" || command === "--help" || command === "-h";
+  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));
+    stdout(renderTopHelp(config.name, config.version, managed.help, config.defaultCommand));
     return exit(0);
   }
   const tool = managed.tools.get(command);
@@ -1403,7 +1650,9 @@ async function createCli(config) {
 `);
     return exit(1);
   }
-  const descriptor = managedDescriptor(tool);
+  const descriptor = managed.help.get(command);
+  if (!descriptor)
+    throw new Error("[stitchkit] managed CLI descriptor invariant failed");
   if (helpRequested) {
     stdout(renderCommandHelp(config.name, command, descriptor));
     return exit(0);