@andrei.fyi/picocli 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1175 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var zod = require('zod');
+var async_hooks = require('async_hooks');
+
+// src/flags/tokenizer.ts
+var readBooleanFlagValue = (value) => value !== "false" && value !== "0" && value !== "no";
+var isLongFlagToken = (token) => {
+  return token.startsWith("--") && token.length > 2;
+};
+var pushFlag = (flags, name, value) => {
+  const values = flags.get(name);
+  if (values) values.push(value);
+  else flags.set(name, [value]);
+};
+var readNextValueToken = (argv, index) => {
+  const next = argv[index + 1];
+  if (next === void 0 || next === "--" || isLongFlagToken(next)) return void 0;
+  return { nextIndex: index + 1, value: next };
+};
+var parseLongFlagToken = (token) => {
+  const body = token.slice(2);
+  const eq = body.indexOf("=");
+  return {
+    name: eq === -1 ? body : body.slice(0, eq),
+    inlineValue: eq === -1 ? void 0 : body.slice(eq + 1)
+  };
+};
+var readKnownLongFlag = (flag, inlineValue, argv, index, state) => {
+  if (flag.isBoolean) {
+    pushFlag(state.flags, flag.name, inlineValue === void 0 ? true : readBooleanFlagValue(inlineValue));
+    return index;
+  }
+  if (inlineValue !== void 0) {
+    pushFlag(state.flags, flag.name, inlineValue);
+    return index;
+  }
+  const spaced = readNextValueToken(argv, index);
+  if (spaced) {
+    pushFlag(state.flags, flag.name, spaced.value);
+    return spaced.nextIndex;
+  }
+  state.missing.push(flag.name);
+  return index;
+};
+var readLongFlagToken = (token, argv, index, model, state) => {
+  const { name, inlineValue } = parseLongFlagToken(token);
+  if (name.startsWith("no-")) {
+    const negated = model.negatable(name);
+    if (negated) {
+      pushFlag(state.flags, negated, false);
+      return index;
+    }
+  }
+  const canonical = model.long(name);
+  if (canonical) {
+    return readKnownLongFlag(
+      { name: canonical, isBoolean: model.isBoolean(canonical) },
+      inlineValue,
+      argv,
+      index,
+      state
+    );
+  }
+  state.unknown.push(`--${name}`);
+  return index;
+};
+var tokenizeArgv = (argv, model) => {
+  const flags = /* @__PURE__ */ new Map();
+  const state = {
+    flags,
+    positionals: [],
+    rest: [],
+    unknown: [],
+    missing: []
+  };
+  let afterDashDash = false;
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === void 0) continue;
+    if (afterDashDash) {
+      state.rest.push(tok);
+      continue;
+    }
+    if (tok === "--") {
+      afterDashDash = true;
+      continue;
+    }
+    if (tok.startsWith("--")) {
+      i = readLongFlagToken(tok, argv, i, model, state);
+      continue;
+    }
+    state.positionals.push(tok);
+  }
+  return {
+    flags,
+    positionals: state.positionals,
+    rest: state.rest,
+    unknown: state.unknown,
+    missing: state.missing
+  };
+};
+
+// src/schemas/zod.ts
+var WRAPPERS = /* @__PURE__ */ new Set(["catch", "default", "nonoptional", "nullable", "optional", "prefault", "readonly"]);
+var toKebabCase = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+var getShape = (obj) => {
+  if (!obj) return void 0;
+  return obj.shape;
+};
+var getBaseType = (schema) => {
+  let cur = schema;
+  for (let i = 0; i < 12; i++) {
+    const def = cur?._zod?.def;
+    if (!def?.type) return void 0;
+    if (WRAPPERS.has(def.type)) {
+      cur = def.innerType;
+      continue;
+    }
+    return def.type;
+  }
+  return void 0;
+};
+var isBooleanOption = (s) => getBaseType(s) === "boolean";
+var isArrayOption = (s) => getBaseType(s) === "array";
+var isOptional = (s) => {
+  let cur = s;
+  for (let i = 0; i < 12; i++) {
+    const def = cur?._zod?.def;
+    if (!def?.type) return false;
+    if (def.type === "default" || def.type === "optional" || def.type === "prefault" || def.type === "catch") {
+      return true;
+    }
+    if (WRAPPERS.has(def.type)) {
+      cur = def.innerType;
+      continue;
+    }
+    return false;
+  }
+  return false;
+};
+var getDescription = (s) => {
+  const meta = s?.meta?.();
+  return meta?.description;
+};
+var getShapeKeys = (obj) => {
+  return Object.keys(getShape(obj) ?? {});
+};
+var getField = (obj, key) => {
+  return getShape(obj)?.[key];
+};
+
+// src/schemas/object.ts
+var overrideDateJsonSchema = (ctx) => {
+  if (ctx.zodSchema?._zod?.def?.type === "date") {
+    const jsonSchema = ctx.jsonSchema;
+    jsonSchema.type = "string";
+    jsonSchema.format = "date-time";
+  }
+};
+var mergeObjects = (parts) => {
+  const shapes = parts.map(getShape).filter((shape) => shape !== void 0);
+  if (shapes.length === 0) return void 0;
+  return zod.z.object(Object.assign({}, ...shapes));
+};
+var getDuplicateKeys = (parts) => {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicate = /* @__PURE__ */ new Set();
+  for (const part of parts) {
+    const shape = getShape(part);
+    for (const key of Object.keys(shape ?? {})) {
+      if (seen.has(key)) duplicate.add(key);
+      else seen.add(key);
+    }
+  }
+  return [...duplicate].sort();
+};
+var getDuplicateKeyMessage = (keys) => {
+  return `schema fields must be unique across merged inputs: ${keys.join(", ")}`;
+};
+var toJsonSchema = (schema) => {
+  if (!schema) return { type: "object", properties: {}, additionalProperties: false };
+  return zod.z.toJSONSchema(schema, {
+    unrepresentable: "any",
+    override: overrideDateJsonSchema
+  });
+};
+
+// src/command/tree.ts
+var isValidCommandName = (name) => name.length > 0 && !isLongFlagToken(name) && name !== "--";
+var commandTreeIssueCache = /* @__PURE__ */ new WeakMap();
+var commandChildrenMap = /* @__PURE__ */ new WeakMap();
+var emptyCommandChildren = /* @__PURE__ */ new Map();
+var getCommandAliases = (def) => typeof def.alias === "string" ? [def.alias] : def.alias ?? [];
+var clearCommandTreeIssueCache = (root) => {
+  commandTreeIssueCache.delete(root);
+};
+var getCommandChildren = (node) => {
+  return commandChildrenMap.get(node) ?? emptyCommandChildren;
+};
+var setCommandChild = (node, name, child) => {
+  const children = commandChildrenMap.get(node) ?? /* @__PURE__ */ new Map();
+  children.set(name, child);
+  commandChildrenMap.set(node, children);
+};
+var createCommandNodeView = (node, def) => {
+  const view = { name: node.name, def };
+  const children = commandChildrenMap.get(node);
+  if (children) commandChildrenMap.set(view, children);
+  return view;
+};
+var findCommandTreeIssue = (root) => {
+  if (commandTreeIssueCache.has(root)) return commandTreeIssueCache.get(root);
+  const walk = (node) => {
+    const owner = node.name;
+    const seen = /* @__PURE__ */ new Map();
+    const children = getCommandChildren(node);
+    for (const [name, child] of children) {
+      if (!isValidCommandName(name)) return `invalid command name "${name}" under "${owner}"`;
+      const existing = seen.get(name);
+      if (existing) return `command name "${name}" for "${name}" conflicts with ${existing}`;
+      seen.set(name, `command "${name}"`);
+      for (const alias of getCommandAliases(child.def)) {
+        if (!isValidCommandName(alias)) return `invalid alias "${alias}" for command "${name}"`;
+        const conflict = seen.get(alias);
+        if (conflict) return `alias "${alias}" for command "${name}" conflicts with ${conflict}`;
+        seen.set(alias, `command "${name}"`);
+      }
+    }
+    for (const child of children.values()) {
+      const issue2 = walk(child);
+      if (issue2) return issue2;
+    }
+    return void 0;
+  };
+  const issue = walk(root);
+  commandTreeIssueCache.set(root, issue);
+  return issue;
+};
+var getChildNames = (node) => {
+  const names = [];
+  for (const [name, child] of getCommandChildren(node)) names.push(name, ...getCommandAliases(child.def));
+  return names;
+};
+var findCommandChild = (node, token) => {
+  const children = getCommandChildren(node);
+  const direct = children.get(token);
+  if (direct) return [token, direct];
+  for (const [name, child] of children) {
+    if (getCommandAliases(child.def).includes(token)) return [name, child];
+  }
+  return void 0;
+};
+var getCommandChain = (root, commandPath) => {
+  const chain = [root];
+  let node = root;
+  for (const name of commandPath) {
+    const child = getCommandChildren(node).get(name);
+    if (!child) throw new Error(`internal command path missing: ${commandPath.join(" ")}`);
+    chain.push(child);
+    node = child;
+  }
+  return chain;
+};
+var getEffectiveCommandDefinition = (chain) => {
+  const node = chain[chain.length - 1];
+  if (!node) return {};
+  return {
+    ...node.def,
+    options: mergeObjects(chain.map((n) => n.def.options)),
+    env: mergeObjects(chain.map((n) => n.def.env))
+  };
+};
+var collectCommandEntries = (root) => {
+  const entries = [];
+  const walk = (node, commandPath, ancestors) => {
+    if (node.def.hidden) return;
+    const chain = [...ancestors, node];
+    entries.push({ commandPath, node, chain, def: getEffectiveCommandDefinition(chain) });
+    for (const [name, child] of getCommandChildren(node)) walk(child, [...commandPath, name], chain);
+  };
+  walk(root, [], []);
+  return entries;
+};
+
+// src/errors.ts
+var PicocliError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "PicocliError";
+    this.code = code;
+  }
+};
+var isPicocliError = (e) => e instanceof PicocliError || typeof e === "object" && e !== null && e.name === "PicocliError";
+var getExitCodeForError = (code) => code === "UNKNOWN" ? 1 : 2;
+
+// src/render/format.ts
+var renderError = (code, message, paint) => {
+  const prefix = `error (${code}):`;
+  return `${paint(prefix, "red", "bold")} ${message}
+`;
+};
+
+// src/flags/globals.ts
+var GLOBAL_FLAGS = [
+  { name: "help", bool: true, description: "show help" },
+  { name: "version", bool: true, description: "print version" },
+  { name: "json", bool: true, description: "emit JSON output" },
+  { name: "format", bool: false, description: "output format: pretty | json" },
+  { name: "color", bool: true, description: "force/disable color (--color / --no-color)" },
+  { name: "mcp", bool: true, description: "run as an MCP stdio server" },
+  { name: "llms", bool: true, description: "print a Markdown command manifest" },
+  { name: "schema", bool: true, description: "print input/output JSON Schemas for the command" }
+];
+var FEATURE_GLOBAL_FLAGS = /* @__PURE__ */ new Set(["llms", "mcp", "schema"]);
+var isFeatureGlobalFlag = (name) => {
+  return FEATURE_GLOBAL_FLAGS.has(name);
+};
+var getActiveGlobalFlags = (optionKeys, features) => {
+  const taken = new Set(optionKeys);
+  return GLOBAL_FLAGS.filter((g) => !taken.has(g.name) && (!isFeatureGlobalFlag(g.name) || features[g.name]));
+};
+
+// src/render/help.ts
+var getArgumentUsage = (args) => {
+  const keys = getShapeKeys(args);
+  return keys.map((k, i) => {
+    const f = getField(args, k);
+    const variadic = i === keys.length - 1 && isArrayOption(f);
+    const inner = variadic ? `${k}...` : k;
+    return isOptional(f) || variadic ? `[${inner}]` : `<${inner}>`;
+  }).join(" ");
+};
+var getOptionLines = (options, paint) => {
+  return getShapeKeys(options).map((k) => {
+    const f = getField(options, k);
+    const optionName = `--${toKebabCase(k)}`;
+    const names = `    ${paint(optionName, "yellow")}`;
+    const type = getBaseType(f) ?? "string";
+    const valueLabel = `<${type}>`;
+    const value = isBooleanOption(f) ? "" : ` ${paint(valueLabel, "gray")}`;
+    const requiredLabel = isOptional(f) ? "" : paint(" (required)", "gray");
+    const desc = getDescription(f);
+    const description = desc ? `  ${desc}` : "";
+    return `  ${names}${value}${requiredLabel}${description}`;
+  });
+};
+var getUsageLine = (node, commandPath, binName, paint) => {
+  const usageParts = [paint([binName, ...commandPath].join(" "), "cyan", "bold")];
+  if (getCommandChildren(node).size > 0) usageParts.push("<command>");
+  if (node.def.options && getShapeKeys(node.def.options).length > 0) usageParts.push("[options]");
+  const args = getArgumentUsage(node.def.args);
+  if (args) usageParts.push(args);
+  return `${paint("Usage:", "bold")} ${usageParts.join(" ")}`;
+};
+var pushArgumentLines = (lines, node, paint) => {
+  const argKeys = getShapeKeys(node.def.args);
+  if (argKeys.length === 0) return;
+  lines.push("", paint("Arguments:", "bold"));
+  for (const k of argKeys) {
+    const f = getField(node.def.args, k);
+    const d = getDescription(f);
+    const typeLabel = `<${getBaseType(f) ?? "string"}>`;
+    const description = d ? `  ${d}` : "";
+    lines.push(`  ${paint(k, "cyan")} ${paint(typeLabel, "gray")}${description}`);
+  }
+};
+var pushOptionLines = (lines, node, paint) => {
+  if (!node.def.options || getShapeKeys(node.def.options).length === 0) return;
+  lines.push("", paint("Options:", "bold"));
+  lines.push(...getOptionLines(node.def.options, paint));
+};
+var pushCommandLines = (lines, node, paint) => {
+  const children = getCommandChildren(node);
+  if (children.size === 0) return;
+  lines.push("", paint("Commands:", "bold"));
+  for (const [name, child] of children) {
+    if (child.def.hidden) continue;
+    const aliases = getCommandAliases(child.def);
+    const label = aliases.length > 0 ? `${name} (${aliases.join(", ")})` : name;
+    const description = child.def.description ? `  ${child.def.description}` : "";
+    lines.push(`  ${paint(label, "cyan")}${description}`);
+  }
+};
+var pushExampleLines = (lines, node, paint) => {
+  if (!node.def.examples || node.def.examples.length === 0) return;
+  lines.push("", paint("Examples:", "bold"));
+  for (const ex of node.def.examples) {
+    if (ex.description) lines.push(`  ${paint("#", "gray")} ${ex.description}`);
+    lines.push(`  ${ex.command}`);
+  }
+};
+var getGlobalLabel = (g) => {
+  if (g.name === "color") return "--color / --no-color";
+  const value = g.bool ? "" : " <value>";
+  return `--${toKebabCase(g.name)}${value}`;
+};
+var renderHelp = (node, commandPath, binName, paint, globals = GLOBAL_FLAGS) => {
+  const lines = [getUsageLine(node, commandPath, binName, paint)];
+  if (node.def.description) lines.push("", node.def.description);
+  pushArgumentLines(lines, node, paint);
+  pushOptionLines(lines, node, paint);
+  pushCommandLines(lines, node, paint);
+  pushExampleLines(lines, node, paint);
+  lines.push("", paint("Global options:", "bold"));
+  for (const g of globals) lines.push(`  ${paint(getGlobalLabel(g), "yellow")}  ${g.description}`);
+  return `${lines.join("\n")}
+`;
+};
+var getFieldDescriptions = (obj, prefix) => {
+  return getShapeKeys(obj).map((k) => {
+    const f = getField(obj, k);
+    const req = isOptional(f) ? "optional" : "required";
+    const d = getDescription(f);
+    const description = d ? `: ${d}` : "";
+    return `- ${prefix} \`${k}\` (${getBaseType(f) ?? "string"}, ${req})${description}`;
+  });
+};
+var getOutputDescriptions = (schema) => {
+  if (!schema) return [];
+  if (getBaseType(schema) !== "object") return [`- output (${getBaseType(schema) ?? "unknown"}, required)`];
+  return getFieldDescriptions(schema, "output");
+};
+var renderLlms = (binName, entries) => {
+  const lines = [`# ${binName}`, ""];
+  for (const e of entries) {
+    if (e.def.hidden) continue;
+    const name = [binName, ...e.commandPath].join(" ");
+    lines.push(`## ${name}`);
+    if (e.def.description) lines.push(e.def.description);
+    const args = getFieldDescriptions(e.def.args, "arg");
+    const opts = getFieldDescriptions(e.def.options, "option");
+    const env = getFieldDescriptions(e.def.env, "env");
+    const output = getOutputDescriptions(e.def.outputSchema);
+    lines.push(...args, ...opts, ...env, ...output, "");
+  }
+  return `${lines.join("\n").trimEnd()}
+`;
+};
+
+// src/render/result.ts
+var createSuccessResult = (data) => {
+  return {
+    ok: true,
+    data: data === void 0 ? null : data
+  };
+};
+var createErrorResult = (code, message) => {
+  return { ok: false, error: { code, message } };
+};
+
+// src/render/suggest.ts
+var getLevenshteinDistance = (a, b) => {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const row = Array.from({ length: n + 1 });
+  for (let j = 0; j <= n; j++) row[j] = j;
+  for (let i = 1; i <= m; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const tmp = row[j];
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + cost);
+      prev = tmp;
+    }
+  }
+  return row[n];
+};
+var suggest = (input, candidates, max = 2) => {
+  return candidates.map((c) => ({ c, d: getLevenshteinDistance(input, c) })).filter((x) => x.d >= 1 && x.d <= max).sort((a, b) => a.d - b.d || a.c.localeCompare(b.c)).map((x) => x.c);
+};
+
+// src/schemas/input-model.ts
+var buildInputModel = (def) => {
+  return {
+    args: def.args,
+    options: def.options,
+    env: def.env,
+    argKeys: getShapeKeys(def.args),
+    optionKeys: getShapeKeys(def.options),
+    envKeys: getShapeKeys(def.env)
+  };
+};
+var getInputSchemas = (model, parts) => {
+  return parts.map((part) => model[part]);
+};
+var assertUniqueInputKeys = (model, parts) => {
+  const conflicts = getDuplicateKeys(getInputSchemas(model, parts));
+  if (conflicts.length > 0) throw new PicocliError("VALIDATION", getDuplicateKeyMessage(conflicts));
+};
+var getInputJsonSchema = (model, parts) => {
+  return toJsonSchema(mergeObjects(getInputSchemas(model, parts)));
+};
+var getEnvInputForKeys = (envKeys, processEnv) => {
+  const input = {};
+  for (const key of envKeys) {
+    const value = processEnv[key];
+    if (value !== void 0) input[key] = value;
+  }
+  return input;
+};
+var getSchemaEnvInput = (env, processEnv) => {
+  return getEnvInputForKeys(getShapeKeys(env), processEnv);
+};
+
+// src/command/resolve.ts
+var resolveCommandPath = (root, argv, getShouldConsumeValue) => {
+  let node = root;
+  const commandPath = [];
+  const remainingArgv = [];
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token.startsWith("--") && token.length < 3) {
+      remainingArgv.push(...argv.slice(i));
+      break;
+    }
+    if (isLongFlagToken(token)) {
+      remainingArgv.push(token);
+      const shouldConsumeValue = getShouldConsumeValue?.(token, commandPath) ?? false;
+      if (shouldConsumeValue && !token.includes("=")) {
+        const value = argv[i + 1];
+        if (value !== void 0) {
+          remainingArgv.push(value);
+          i++;
+        }
+      }
+      continue;
+    }
+    const child = findCommandChild(node, token);
+    if (child) {
+      const [name, next] = child;
+      node = next;
+      commandPath.push(name);
+      continue;
+    }
+    remainingArgv.push(...argv.slice(i));
+    break;
+  }
+  return { node, commandPath, remainingArgv };
+};
+
+// src/flags/model.ts
+var toCamelCase = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+var buildFlagModel = (options, globals) => {
+  const optKeys = getShapeKeys(options);
+  const known = new Set(optKeys);
+  const longMap = /* @__PURE__ */ new Map();
+  const boolNames = /* @__PURE__ */ new Set();
+  for (const key of optKeys) {
+    longMap.set(key, key);
+    longMap.set(toKebabCase(key), key);
+    if (isBooleanOption(getField(options, key))) boolNames.add(key);
+  }
+  for (const flag of globals) {
+    if (known.has(flag.name)) continue;
+    longMap.set(flag.name, flag.name);
+    longMap.set(toKebabCase(flag.name), flag.name);
+    if (flag.bool) boolNames.add(flag.name);
+  }
+  return {
+    long: (raw) => longMap.get(raw) ?? (known.has(toCamelCase(raw)) ? toCamelCase(raw) : void 0),
+    negatable: (no) => {
+      const raw = no.slice(3);
+      const name = longMap.get(raw) ?? (known.has(toCamelCase(raw)) ? toCamelCase(raw) : void 0);
+      return name && boolNames.has(name) ? name : void 0;
+    },
+    isBoolean: (name) => boolNames.has(name)
+  };
+};
+var getShouldConsumeFlagValue = (options) => {
+  const optionKeys = new Set(getShapeKeys(options));
+  const model = buildFlagModel(options, GLOBAL_FLAGS);
+  const valueGlobals = new Set(GLOBAL_FLAGS.filter((flag) => !flag.bool).map((flag) => flag.name));
+  return (flagToken) => {
+    if (flagToken.startsWith("--")) {
+      let raw = flagToken.slice(2);
+      if (raw.includes("=")) return false;
+      if (raw.startsWith("no-")) raw = raw.slice(3);
+      const name = model.long(raw);
+      if (!name) return false;
+      if (optionKeys.has(name)) return !model.isBoolean(name);
+      return valueGlobals.has(name);
+    }
+    return false;
+  };
+};
+
+// src/render/color.ts
+var getShouldUseAnsi = (params) => {
+  if (params.colorFlag === false) return false;
+  if (params.colorFlag === true) return true;
+  const fc = params.env.FORCE_COLOR;
+  if (fc !== void 0) return !(fc === "0" || fc === "false" || fc === "");
+  if (params.env.NO_COLOR !== void 0 && params.env.NO_COLOR !== "") return false;
+  return params.isTTY;
+};
+var CODES = {
+  bold: 1,
+  red: 31,
+  green: 32,
+  yellow: 33,
+  cyan: 36,
+  gray: 90
+};
+var makePaint = (shouldUseAnsi) => {
+  return (s, ...attributes) => {
+    if (!shouldUseAnsi || attributes.length === 0) return s;
+    const open = attributes.map((attribute) => `\x1B[${CODES[attribute]}m`).join("");
+    return `${open}${s}\x1B[0m`;
+  };
+};
+
+// src/runtime/argv.ts
+var resolveInvocation = (root, argv) => {
+  const treeIssue = findCommandTreeIssue(root);
+  if (treeIssue) throw new PicocliError("VALIDATION", treeIssue);
+  const { node, commandPath, remainingArgv } = resolveCommandPath(root, argv, (flagToken, path) => {
+    const def2 = getEffectiveCommandDefinition(getCommandChain(root, [...path]));
+    return getShouldConsumeFlagValue(def2.options)(flagToken);
+  });
+  const chain = getCommandChain(root, commandPath);
+  const def = getEffectiveCommandDefinition(chain);
+  const input = buildInputModel(def);
+  return {
+    node,
+    helpNode: createCommandNodeView(node, def),
+    commandPath,
+    remainingArgv,
+    commandName: [root.name, ...commandPath].join(" "),
+    hasSubcommands: getCommandChildren(node).size > 0,
+    def,
+    input
+  };
+};
+var parseGlobals = (params) => {
+  const { input, remainingArgv, opts, env, isTTY, features } = params;
+  const optionKeys = input.optionKeys;
+  const globals = getActiveGlobalFlags(optionKeys, features);
+  const globalNames = new Set(globals.map((flag) => flag.name));
+  const tokens = tokenizeArgv(remainingArgv, buildFlagModel(input.options, globals));
+  const lastValue = (name) => {
+    const values = tokens.flags.get(name);
+    return values ? values[values.length - 1] : void 0;
+  };
+  const has = (name) => globalNames.has(name) && tokens.flags.has(name) && lastValue(name) !== false;
+  const colorFlag = globalNames.has("color") && tokens.flags.has("color") ? lastValue("color") === true : void 0;
+  const fmtVal = has("format") ? lastValue("format") : void 0;
+  return {
+    tokens,
+    optionKeys,
+    globals,
+    globalNames,
+    paint: makePaint(getShouldUseAnsi({ colorFlag, env, isTTY })),
+    isJSON: opts.format === "json" || opts.format !== "pretty" && (has("json") || fmtVal === "json"),
+    has,
+    lastValue
+  };
+};
+
+// src/runtime/input.ts
+var collectOptionInput = (options, flags) => {
+  const optionsInput = {};
+  for (const key of getShapeKeys(options)) {
+    const flagValues = flags.get(key);
+    if (flagValues && flagValues.length > 0) {
+      optionsInput[key] = isArrayOption(getField(options, key)) ? flagValues : flagValues[flagValues.length - 1];
+    }
+  }
+  return optionsInput;
+};
+var collectArgsInput = (args, positionals) => {
+  const argKeys = getShapeKeys(args);
+  const lastIndex = argKeys.length - 1;
+  const lastArgKey = argKeys.at(-1);
+  const lastIsArray = lastArgKey !== void 0 && isArrayOption(getField(args, lastArgKey));
+  const argsInput = {};
+  let excessPositionals = [];
+  for (const [index, argKey] of argKeys.entries()) {
+    if (index === lastIndex && lastIsArray) {
+      const collected = positionals.slice(index);
+      if (collected.length > 0) argsInput[argKey] = collected;
+    } else if (positionals[index] !== void 0) {
+      argsInput[argKey] = positionals[index];
+    }
+  }
+  if (!lastIsArray && positionals.length > argKeys.length) {
+    excessPositionals = positionals.slice(argKeys.length);
+  }
+  return { argsInput, excessPositionals };
+};
+var parseCommandInput = (params) => {
+  const { args, options, env, flags, positionals, processEnv } = params;
+  const optionsInput = collectOptionInput(options, flags);
+  const { argsInput, excessPositionals } = collectArgsInput(args, positionals);
+  const envInput = getSchemaEnvInput(env, processEnv);
+  return { argsInput, optionsInput, envInput, excessPositionals };
+};
+
+// src/schemas/validate.ts
+var parseSchema = (schema, input, kind) => {
+  const result = schema.safeParse(input);
+  if (result.success) return result.data;
+  const issue = result.error.issues[0] ?? {};
+  const field = issue.path?.join(".") || "(input)";
+  const expected = "expected" in issue ? String(issue.expected) : void 0;
+  const coercible = expected === "number" || expected === "int" || expected === "bigint";
+  const hint = coercible ? ` (CLI values arrive as strings \u2014 use z.coerce.${expected}() for non-string ${kind}s)` : "";
+  const message = `invalid ${kind} "${field}": ${issue.message}${hint}`;
+  throw new PicocliError("VALIDATION", message);
+};
+var parseOutputSchema = (schema, data) => {
+  const result = schema.safeParse(data);
+  if (result.success) return result.data;
+  const issue = result.error.issues[0] ?? {};
+  const field = issue.path?.join(".") || "(output)";
+  const message = `invalid output "${field}": ${issue.message}`;
+  throw new PicocliError("VALIDATION", message);
+};
+var validateAll = (params) => {
+  const { args, options, env, argsInput, optionsInput, envInput } = params;
+  return {
+    args: args ? parseSchema(args, argsInput, "argument") : {},
+    options: options ? parseSchema(options, optionsInput, "option") : {},
+    env: env ? parseSchema(env, envInput, "environment variable") : {}
+  };
+};
+var METHODS = ["log", "info", "debug", "warn", "error"];
+var consoleCaptureStorage = new async_hooks.AsyncLocalStorage();
+var depth = 0;
+var original;
+var createConsoleRouter = (method) => (...args) => {
+  const capture = consoleCaptureStorage.getStore();
+  const handler = capture?.[method];
+  if (handler) handler(args);
+  else original?.[method](...args);
+};
+var installConsoleCapture = () => {
+  if (depth++ > 0) return;
+  original = Object.fromEntries(METHODS.map((method) => [method, console[method].bind(console)]));
+  for (const method of METHODS) {
+    console[method] = createConsoleRouter(method);
+  }
+};
+var uninstallConsoleCapture = () => {
+  depth--;
+  if (depth > 0 || !original) return;
+  for (const method of METHODS) console[method] = original[method];
+  original = void 0;
+};
+var withConsoleCapture = async (capture, runCaptured) => {
+  installConsoleCapture();
+  try {
+    return await consoleCaptureStorage.run(capture, runCaptured);
+  } finally {
+    uninstallConsoleCapture();
+  }
+};
+var suppressedConsole = Object.fromEntries(
+  METHODS.map((method) => [method, () => {
+  }])
+);
+
+// src/runtime/run.ts
+var shouldValidateOutput = (mode, nodeEnv) => {
+  const resolved = mode ?? "development";
+  if (resolved === true) return true;
+  if (resolved === false) return false;
+  return nodeEnv === "development";
+};
+var createUnknownErrorResult = (error, debug) => {
+  debug?.(`${error.stack ?? String(error)}
+`);
+  return {
+    ok: false,
+    error: { code: "UNKNOWN", message: error.message ?? String(error) },
+    exitCode: 1
+  };
+};
+var createThrownErrorResult = (error, debug) => {
+  if (isPicocliError(error)) {
+    return {
+      ok: false,
+      error: { code: error.code, message: error.message },
+      exitCode: getExitCodeForError(error.code)
+    };
+  }
+  return createUnknownErrorResult(error, debug);
+};
+var runCommand = async (def, baseContext, opts = {}) => {
+  const run = async () => {
+    try {
+      const retval = await def.run(baseContext);
+      const returnedData = retval === void 0 ? null : retval;
+      const data = def.outputSchema && shouldValidateOutput(def.validateOutput, opts.nodeEnv) ? parseOutputSchema(def.outputSchema, returnedData) : returnedData;
+      return { ok: true, data };
+    } catch (error) {
+      return createThrownErrorResult(error, opts.debug);
+    }
+  };
+  return opts.suppressConsole ? withConsoleCapture(suppressedConsole, run) : run();
+};
+
+// src/runtime/invoke.ts
+var validateCommandInput = (input, values) => {
+  try {
+    return validateAll({
+      args: input.args,
+      options: input.options,
+      env: input.env,
+      argsInput: values.argsInput,
+      optionsInput: values.optionsInput,
+      envInput: values.envInput
+    });
+  } catch (error) {
+    if (!isPicocliError(error)) throw error;
+    return error;
+  }
+};
+var createValidationResult = (error) => ({
+  ok: false,
+  result: createErrorResult(error.code, error.message),
+  error: { code: error.code, message: error.message },
+  exitCode: getExitCodeForError(error.code)
+});
+var createInvocationResult = (result) => {
+  if (result.ok) {
+    return {
+      ok: true,
+      result: createSuccessResult(result.data),
+      exitCode: 0
+    };
+  }
+  return {
+    ok: false,
+    result: createErrorResult(result.error.code, result.error.message),
+    error: result.error,
+    exitCode: result.exitCode
+  };
+};
+var invokeCommand = async (params) => {
+  const { def, input, name, inputs, isTTY, isJSON, rest, readStdin, suppressConsole, debug, nodeEnv } = params;
+  const parsed = validateCommandInput(input, inputs);
+  if (isPicocliError(parsed)) return createValidationResult(parsed);
+  const result = await runCommand(
+    def,
+    {
+      name,
+      args: parsed.args,
+      options: parsed.options,
+      env: parsed.env,
+      isTTY,
+      isJSON,
+      rest,
+      readStdin
+    },
+    { suppressConsole, debug, nodeEnv }
+  );
+  return createInvocationResult(result);
+};
+
+// src/runtime/serve.ts
+var loadMcp = async () => {
+  const distSpecifier = "./mcp/index.js";
+  try {
+    return await import(distSpecifier);
+  } catch (error) {
+    const sourceSpecifier = "../mcp/index";
+    try {
+      return await import(sourceSpecifier);
+    } catch {
+      throw error;
+    }
+  }
+};
+var readProcessStdin = async () => {
+  const stdin = process.stdin;
+  if (stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+};
+var createServeContext = (root, argv, opts) => {
+  const stdout = opts.stdout ?? ((s) => void process.stdout.write(s));
+  const stderr = opts.stderr ?? ((s) => void process.stderr.write(s));
+  const exit = opts.exit ?? ((c) => process.exit(c));
+  const env = opts.env ?? process.env;
+  const isTTY = opts.isTTY ?? Boolean(process.stdout.isTTY);
+  const invocation = resolveInvocation(root, argv);
+  const parsedGlobals = parseGlobals({
+    input: invocation.input,
+    remainingArgv: invocation.remainingArgv,
+    opts,
+    env,
+    isTTY,
+    features: root.features
+  });
+  return { root, opts, stdout, stderr, exit, env, isTTY, invocation, parsedGlobals };
+};
+var writeJsonLine = (write, value) => {
+  write(`${JSON.stringify(value)}
+`);
+};
+var writeFailure = (ctx, error) => {
+  if (ctx.parsedGlobals.isJSON) writeJsonLine(ctx.stdout, createErrorResult(error.code, error.message));
+  else ctx.stderr(renderError(error.code, error.message, ctx.parsedGlobals.paint));
+  return ctx.exit(getExitCodeForError(error.code));
+};
+var finishCommand = (ctx, result) => {
+  if (ctx.parsedGlobals.isJSON) writeJsonLine(ctx.stdout, result.ok ? result.result.data : result.result);
+  else if (!result.ok) {
+    ctx.stderr(renderError(result.error.code, result.error.message, ctx.parsedGlobals.paint));
+  }
+  return ctx.exit(result.exitCode);
+};
+var writeHelp = (ctx) => {
+  ctx.stdout(
+    renderHelp(
+      ctx.invocation.helpNode,
+      ctx.invocation.commandPath,
+      ctx.root.name,
+      ctx.parsedGlobals.paint,
+      ctx.parsedGlobals.globals
+    )
+  );
+};
+var handleHelpOrVersion = async (ctx) => {
+  if (ctx.parsedGlobals.has("help")) {
+    writeHelp(ctx);
+    ctx.exit(0);
+    return true;
+  }
+  if (ctx.parsedGlobals.has("version")) {
+    ctx.stdout(`${ctx.invocation.def.version ?? ctx.root.def.version ?? "0.0.0"}
+`);
+    ctx.exit(0);
+    return true;
+  }
+  return false;
+};
+var handleGlobalParseError = (ctx) => {
+  const { parsedGlobals } = ctx;
+  if (parsedGlobals.tokens.missing.length > 0) {
+    writeFailure(
+      ctx,
+      new PicocliError(
+        "VALIDATION",
+        `option "--${toKebabCase(parsedGlobals.tokens.missing[0])}" requires a value`
+      )
+    );
+    return true;
+  }
+  if (parsedGlobals.has("format")) {
+    const value = parsedGlobals.lastValue("format");
+    if (value !== "json" && value !== "pretty") {
+      const sugg = suggest(String(value), ["pretty", "json"]);
+      const hint = sugg.length > 0 ? `; did you mean "${sugg[0]}"?` : "";
+      writeFailure(
+        ctx,
+        new PicocliError("VALIDATION", `invalid --format "${value}"; expected pretty or json${hint}`)
+      );
+      return true;
+    }
+  }
+  return false;
+};
+var handleSchemaManifestOrMcp = async (ctx) => {
+  const { env, invocation, parsedGlobals, root } = ctx;
+  if (parsedGlobals.has("schema")) {
+    try {
+      assertUniqueInputKeys(invocation.input, ["args", "options"]);
+    } catch (error) {
+      if (isPicocliError(error)) writeFailure(ctx, error);
+      else throw error;
+      return true;
+    }
+    ctx.stdout(
+      `${JSON.stringify(
+        {
+          input: getInputJsonSchema(invocation.input, ["args", "options"]),
+          output: invocation.def.outputSchema ? toJsonSchema(invocation.def.outputSchema) : null
+        },
+        null,
+        2
+      )}
+`
+    );
+    ctx.exit(0);
+    return true;
+  }
+  if (parsedGlobals.has("llms")) {
+    ctx.stdout(renderLlms(root.name, collectCommandEntries(root)));
+    ctx.exit(0);
+    return true;
+  }
+  if (parsedGlobals.has("mcp")) {
+    const mcp = await loadMcp();
+    await mcp.serveMcp(root, { env });
+    return true;
+  }
+  return false;
+};
+var handleUnknownOption = (ctx) => {
+  const { parsedGlobals } = ctx;
+  if (parsedGlobals.tokens.unknown.length === 0) return false;
+  const bad = parsedGlobals.tokens.unknown[0];
+  const known = [
+    ...parsedGlobals.optionKeys.map(toKebabCase),
+    ...parsedGlobals.globals.map((flag) => flag.name)
+  ];
+  const sugg = bad.startsWith("--") ? suggest(bad.slice(2), known) : [];
+  const hint = sugg.length > 0 ? `; did you mean "--${sugg[0]}"?` : "";
+  writeFailure(ctx, new PicocliError("VALIDATION", `unknown option "${bad}"${hint}`));
+  return true;
+};
+var handleNonRunnableCommand = (ctx) => {
+  const { invocation, parsedGlobals } = ctx;
+  if (invocation.hasSubcommands && !invocation.def.run) {
+    if (parsedGlobals.tokens.positionals.length > 0) {
+      const first = parsedGlobals.tokens.positionals[0];
+      const sugg = suggest(first, getChildNames(invocation.node));
+      const hint = sugg.length > 0 ? `; did you mean "${sugg[0]}"?` : "";
+      writeFailure(ctx, new PicocliError("COMMAND_NOT_FOUND", `unknown command "${first}"${hint}`));
+      return true;
+    }
+    writeHelp(ctx);
+    ctx.exit(0);
+    return true;
+  }
+  if (!invocation.def.run) {
+    writeHelp(ctx);
+    ctx.exit(0);
+    return true;
+  }
+  return false;
+};
+var runCommandInvocation = async (ctx) => {
+  const { env, invocation, isTTY, opts, parsedGlobals, stderr } = ctx;
+  const cmdFlags = new Map(
+    [...parsedGlobals.tokens.flags].filter(([name]) => !parsedGlobals.globalNames.has(name))
+  );
+  const commandInput = parseCommandInput({
+    args: invocation.input.args,
+    options: invocation.input.options,
+    env: invocation.input.env,
+    flags: cmdFlags,
+    positionals: parsedGlobals.tokens.positionals,
+    processEnv: env
+  });
+  if (commandInput.excessPositionals.length > 0) {
+    return writeFailure(
+      ctx,
+      new PicocliError("VALIDATION", `unexpected argument "${commandInput.excessPositionals[0]}"`)
+    );
+  }
+  const result = await invokeCommand({
+    def: invocation.def,
+    input: invocation.input,
+    name: invocation.commandName,
+    inputs: {
+      argsInput: commandInput.argsInput,
+      optionsInput: commandInput.optionsInput,
+      envInput: commandInput.envInput
+    },
+    isTTY,
+    isJSON: parsedGlobals.isJSON,
+    rest: parsedGlobals.tokens.rest,
+    readStdin: opts.stdin ?? readProcessStdin,
+    suppressConsole: parsedGlobals.isJSON,
+    debug: env.DEBUG ? stderr : void 0,
+    nodeEnv: env.NODE_ENV
+  });
+  return finishCommand(ctx, result);
+};
+var serve = async (root, argv, opts) => {
+  const ctx = createServeContext(root, argv, opts);
+  if (await handleHelpOrVersion(ctx)) return;
+  if (handleGlobalParseError(ctx)) return;
+  if (await handleSchemaManifestOrMcp(ctx)) return;
+  if (handleUnknownOption(ctx)) return;
+  if (handleNonRunnableCommand(ctx)) return;
+  return runCommandInvocation(ctx);
+};
+
+// src/create.ts
+var parentCliMap = /* @__PURE__ */ new WeakMap();
+var commandCliSet = /* @__PURE__ */ new WeakSet();
+var resolveCliFeatures = (features) => ({
+  mcp: features?.mcp ?? true,
+  schema: features?.schema ?? true,
+  llms: features?.llms ?? true
+});
+var clearCachedTreeIssues = (cli2) => {
+  clearCommandTreeIssueCache(cli2);
+  for (const parent of parentCliMap.get(cli2) ?? []) clearCachedTreeIssues(parent);
+};
+var containsCommandNode = (root, target, seen = /* @__PURE__ */ new WeakSet()) => {
+  if (root === target) return true;
+  if (seen.has(root)) return false;
+  seen.add(root);
+  for (const [, child] of getCommandChildren(root)) {
+    if (containsCommandNode(child, target, seen)) return true;
+  }
+  return false;
+};
+var Cli = class {
+  name;
+  def;
+  features;
+  constructor(name, def, features) {
+    this.name = name;
+    this.def = def ?? {};
+    this.features = resolveCliFeatures(features);
+  }
+  command(a, b) {
+    const name = typeof a === "string" ? a : a.name;
+    if (getCommandChildren(this).has(name)) {
+      throw new PicocliError("VALIDATION", `command "${name}" already exists under "${this.name}"`);
+    }
+    if (typeof a === "string") setCommandChild(this, name, { name, def: b ?? {} });
+    else {
+      if (!commandCliSet.has(a)) {
+        throw new PicocliError("VALIDATION", `command "${name}" must be created with cli.command(...)`);
+      }
+      if (containsCommandNode(a, this)) {
+        throw new PicocliError("VALIDATION", `command "${name}" cannot be mounted into its own tree`);
+      }
+      const parents = parentCliMap.get(a) ?? /* @__PURE__ */ new Set();
+      parents.add(this);
+      parentCliMap.set(a, parents);
+      setCommandChild(this, name, a);
+    }
+    clearCachedTreeIssues(this);
+    return this;
+  }
+  serve(argv, opts) {
+    return serve(this, argv ?? process.argv.slice(2), opts ?? {});
+  }
+};
+var cli = {
+  create: (name, def) => {
+    const { features, ...commandDefinition } = def ?? {};
+    return new Cli(
+      name,
+      commandDefinition,
+      features
+    );
+  },
+  command: (name, def) => {
+    const command2 = new Cli(
+      name,
+      def
+    );
+    commandCliSet.add(command2);
+    return command2;
+  }
+};
+var create_default = cli;
+
+// src/index.ts
+var src_default = create_default;
+var create = create_default.create;
+var command = create_default.command;
+
+exports.Cli = Cli;
+exports.PicocliError = PicocliError;
+exports.command = command;
+exports.create = create;
+exports.default = src_default;
+exports.isPicocliError = isPicocliError;