@andrei.fyi/picocli 0.1.0

package/dist/mcp/index.js

@@ -0,0 +1,502 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { AsyncLocalStorage } from 'async_hooks';
+
+// src/mcp/server.ts
+
+// src/flags/tokenizer.ts
+var isLongFlagToken = (token) => {
+  return token.startsWith("--") && token.length > 2;
+};
+
+// src/schemas/zod.ts
+var getShape = (obj) => {
+  if (!obj) return void 0;
+  return obj.shape;
+};
+var getShapeKeys = (obj) => {
+  return Object.keys(getShape(obj) ?? {});
+};
+
+// 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 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 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 getCommandChildren = (node) => {
+  return commandChildrenMap.get(node) ?? emptyCommandChildren;
+};
+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 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/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/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 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/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 splitNamedInput = (model, rawInput) => {
+  const argKeys = new Set(model.argKeys);
+  const optionKeys = new Set(model.optionKeys);
+  const argsInput = {};
+  const optionsInput = {};
+  let unknownKey;
+  for (const [key, value] of Object.entries(rawInput)) {
+    if (argKeys.has(key)) argsInput[key] = value;
+    else if (optionKeys.has(key)) optionsInput[key] = value;
+    else unknownKey ??= key;
+  }
+  return { argsInput, optionsInput, unknownKey };
+};
+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 getEnvInput = (model, processEnv) => {
+  return getEnvInputForKeys(model.envKeys, processEnv);
+};
+
+// src/mcp/tools.ts
+var createToolResult = (result) => {
+  const structuredContent = result;
+  return {
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    structuredContent,
+    isError: !structuredContent.ok
+  };
+};
+var createToolErrorResult = (code, message) => createToolResult(createErrorResult(code, message));
+var createUnknownToolResult = (toolName) => createToolErrorResult("COMMAND_NOT_FOUND", `unknown tool: ${toolName}`);
+var getToolInputSchema = (entry) => {
+  const model = buildInputModel(entry.def);
+  assertUniqueInputKeys(model, ["args", "options"]);
+  return getInputJsonSchema(model, ["args", "options"]);
+};
+var getToolOutputSchema = (entry) => {
+  if (!entry.def.outputSchema) return void 0;
+  return {
+    type: "object",
+    anyOf: [
+      {
+        type: "object",
+        properties: {
+          ok: { const: true },
+          data: toJsonSchema(entry.def.outputSchema)
+        },
+        required: ["ok", "data"],
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        properties: {
+          ok: { const: false },
+          error: {
+            type: "object",
+            properties: {
+              code: { type: "string" },
+              message: { type: "string" }
+            },
+            required: ["code", "message"],
+            additionalProperties: false
+          }
+        },
+        required: ["ok", "error"],
+        additionalProperties: false
+      }
+    ]
+  };
+};
+var getToolEntries = (root) => {
+  const treeIssue = findCommandTreeIssue(root);
+  if (treeIssue) throw new Error(treeIssue);
+  const tools = [];
+  const names = /* @__PURE__ */ new Set();
+  for (const entry of collectCommandEntries(root)) {
+    if (!entry.node.def.run) continue;
+    const name = entry.commandPath.length > 0 ? entry.commandPath.join("_") : root.name;
+    if (names.has(name)) throw new Error(`duplicate MCP tool name: ${name}`);
+    names.add(name);
+    tools.push({
+      name,
+      description: entry.node.def.description ?? "",
+      node: entry.node,
+      commandPath: entry.commandPath,
+      def: entry.def
+    });
+  }
+  return tools;
+};
+var listTools = (root) => {
+  return getToolEntries(root).map((entry) => ({
+    name: entry.name,
+    description: entry.description,
+    inputSchema: getToolInputSchema(entry),
+    ...entry.def.outputSchema ? { outputSchema: getToolOutputSchema(entry) } : {}
+  }));
+};
+var invokeToolCommand = async (root, entry, rawArgs, opts) => {
+  const def = entry.def;
+  const model = buildInputModel(def);
+  const namedInput = splitNamedInput(model, rawArgs);
+  assertUniqueInputKeys(model, ["args", "options"]);
+  if (namedInput.unknownKey) {
+    throw new PicocliError("VALIDATION", `unknown tool argument "${namedInput.unknownKey}"`);
+  }
+  const result = await invokeCommand({
+    def,
+    input: model,
+    name: [root.name, ...entry.commandPath].join(" "),
+    inputs: {
+      argsInput: namedInput.argsInput,
+      optionsInput: namedInput.optionsInput,
+      envInput: getEnvInput(model, opts.env)
+    },
+    isTTY: false,
+    isJSON: true,
+    rest: [],
+    readStdin: async () => "",
+    suppressConsole: true,
+    nodeEnv: opts.env.NODE_ENV
+  });
+  return result.result;
+};
+var invokeToolEntry = async (root, entry, rawArgs, opts) => {
+  try {
+    return createToolResult(await invokeToolCommand(root, entry, rawArgs, opts));
+  } catch (error) {
+    const message = isPicocliError(error) ? error.message : error.message ?? String(error);
+    const code = isPicocliError(error) ? error.code : "UNKNOWN";
+    return createToolErrorResult(code, message);
+  }
+};
+var invokeTool = async (root, toolName, args = {}, opts = {}) => {
+  const runtimeOptions = { env: opts.env ?? process.env };
+  const entry = getToolEntries(root).find((tool) => tool.name === toolName);
+  if (!entry) return createUnknownToolResult(toolName);
+  return invokeToolEntry(root, entry, args, runtimeOptions);
+};
+
+// src/mcp/server.ts
+var buildServer = (root, opts = {}) => {
+  const runtimeOptions = { env: opts.env ?? process.env };
+  const tools = getToolEntries(root);
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+  const toolDefinitions = tools.map((entry) => ({
+    name: entry.name,
+    description: entry.description,
+    inputSchema: getToolInputSchema(entry),
+    ...entry.def.outputSchema ? { outputSchema: getToolOutputSchema(entry) } : {}
+  }));
+  const server = new Server(
+    { name: root.name, version: root.def.version ?? "0.0.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: toolDefinitions
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const entry = byName.get(req.params.name);
+    if (!entry) return createUnknownToolResult(req.params.name);
+    return invokeToolEntry(
+      root,
+      entry,
+      req.params.arguments ?? {},
+      runtimeOptions
+    );
+  });
+  return server;
+};
+var serveMcp = async (root, opts = {}) => {
+  await buildServer(root, opts).connect(new StdioServerTransport());
+};
+
+export { buildServer, invokeTool, listTools, serveMcp };

package/dist/testing/testkit.cjs

@@ -0,0 +1,115 @@
+'use strict';
+
+var util = require('util');
+var async_hooks = require('async_hooks');
+
+// src/testing/testkit.ts
+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();
+  }
+};
+Object.fromEntries(
+  METHODS.map((method) => [method, () => {
+  }])
+);
+
+// src/testing/testkit.ts
+var formatConsoleArgs = (args) => `${util.format(...args)}
+`;
+var createConsoleCapture = (output) => ({
+  log: (args) => void output.stdout.push(formatConsoleArgs(args)),
+  info: (args) => void output.stdout.push(formatConsoleArgs(args)),
+  debug: (args) => void output.stdout.push(formatConsoleArgs(args)),
+  error: (args) => void output.stderr.push(formatConsoleArgs(args)),
+  warn: (args) => void output.stderr.push(formatConsoleArgs(args))
+});
+var parseJsonResult = (stdout) => {
+  try {
+    const json = JSON.parse(stdout);
+    return { stdout: `${JSON.stringify(json)}
+`, json, hasJson: true };
+  } catch {
+    return { stdout, json: void 0, hasJson: false };
+  }
+};
+var runCliWithOutputFormat = async (app, argv, opts, outputFormat) => {
+  const output = {
+    stdout: [],
+    stderr: [],
+    exitCode: 0,
+    wroteFrameworkStdout: false
+  };
+  const stdin = opts.stdin;
+  const readStdin = stdin === void 0 ? void 0 : async () => stdin;
+  await withConsoleCapture(createConsoleCapture(output), async () => {
+    await app.serve(argv, {
+      stdout: (s) => {
+        output.wroteFrameworkStdout = true;
+        output.stdout.push(s);
+      },
+      stderr: (s) => {
+        output.stderr.push(s);
+      },
+      exit: (code) => {
+        output.exitCode = code;
+      },
+      env: opts.env ?? {},
+      isTTY: opts.isTTY ?? false,
+      stdin: readStdin,
+      format: outputFormat
+    });
+  });
+  const stdout = output.stdout.join("");
+  const stderr = output.stderr.join("");
+  if (outputFormat !== "json" && !output.wroteFrameworkStdout) {
+    return { stdout, stderr, exitCode: output.exitCode, json: void 0, hasJson: false };
+  }
+  const parsed = parseJsonResult(stdout);
+  return {
+    stdout: parsed.stdout,
+    stderr,
+    exitCode: output.exitCode,
+    json: parsed.json,
+    hasJson: parsed.hasJson
+  };
+};
+var runCli = async (app, argv, opts = {}) => {
+  const { hasJson: _, ...result } = await runCliWithOutputFormat(app, argv, opts, void 0);
+  return result;
+};
+var runJson = async (app, argv, opts = {}) => {
+  const result = await runCliWithOutputFormat(app, argv, opts, "json");
+  if (!result.hasJson) throw new Error("runJson expected JSON output");
+  const { hasJson: _, ...publicResult } = result;
+  return publicResult;
+};
+
+exports.runCli = runCli;
+exports.runJson = runJson;

package/dist/testing/testkit.d.cts

@@ -0,0 +1,23 @@
+import { e as CommandErrorResult, b as Cli } from '../create-eQnnIhZu.cjs';
+import 'zod';
+
+type TestJsonValue<T = unknown> = CommandErrorResult | T;
+interface TestRunResult<T = unknown> {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    json: TestJsonValue<T> | undefined;
+}
+interface TestJsonRunResult<T = unknown> extends TestRunResult<T> {
+    json: TestJsonValue<T>;
+}
+interface TestRunOptions {
+    env?: Record<string, string | undefined>;
+    isTTY?: boolean;
+    stdin?: string;
+}
+
+declare const runCli: <T = unknown>(app: Cli, argv: string[], opts?: TestRunOptions) => Promise<TestRunResult<T>>;
+declare const runJson: <T = unknown>(app: Cli, argv: string[], opts?: TestRunOptions) => Promise<TestJsonRunResult<T>>;
+
+export { type TestJsonRunResult, type TestJsonValue, type TestRunOptions, type TestRunResult, runCli, runJson };

package/dist/testing/testkit.d.ts

@@ -0,0 +1,23 @@
+import { e as CommandErrorResult, b as Cli } from '../create-eQnnIhZu.js';
+import 'zod';
+
+type TestJsonValue<T = unknown> = CommandErrorResult | T;
+interface TestRunResult<T = unknown> {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    json: TestJsonValue<T> | undefined;
+}
+interface TestJsonRunResult<T = unknown> extends TestRunResult<T> {
+    json: TestJsonValue<T>;
+}
+interface TestRunOptions {
+    env?: Record<string, string | undefined>;
+    isTTY?: boolean;
+    stdin?: string;
+}
+
+declare const runCli: <T = unknown>(app: Cli, argv: string[], opts?: TestRunOptions) => Promise<TestRunResult<T>>;
+declare const runJson: <T = unknown>(app: Cli, argv: string[], opts?: TestRunOptions) => Promise<TestJsonRunResult<T>>;
+
+export { type TestJsonRunResult, type TestJsonValue, type TestRunOptions, type TestRunResult, runCli, runJson };