padrone 1.4.0 → 1.6.0

package/src/core/program-methods.ts

@@ -0,0 +1,301 @@
+import type { Schema } from 'ai';
+import type { ShellType } from '../feature/completion.ts';
+import { createReplIterator } from '../feature/repl-loop.ts';
+import { generateHelp } from '../output/help.ts';
+import type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  InterceptorExecuteContext,
+  InterceptorExecuteResult,
+  PadroneActionContext,
+  PadroneAPI,
+  PadroneReplPreferences,
+} from '../types/index.ts';
+import { parsePositionalConfig } from './args.ts';
+import { findCommandByName, getCommandRuntime, resolveAllCommands } from './commands.ts';
+import { RoutingError } from './errors.ts';
+import type { ExecContext } from './exec.ts';
+import { collectInterceptors, errorResultWithSignal, execCommand } from './exec.ts';
+import { resolveRegisteredInterceptors, runInterceptorChain } from './interceptors.ts';
+import { errorResult, makeThenable, thenMaybe, warnIfUnexpectedAsync, withDrain, withPromiseDrain } from './results.ts';
+import { coreValidateForParse } from './validate.ts';
+
+export function createProgramMethods(ctx: ExecContext, evalCommand: AnyPadroneProgram['eval']) {
+  const { rootCommand } = ctx;
+
+  // A never-aborted signal for contexts that don't need signal handling (parse, run).
+  const inertSignal = new AbortController().signal;
+
+  const stringify: AnyPadroneProgram['stringify'] = (command = '' as any, args) => {
+    const commandObj = typeof command === 'string' ? findCommandByName(command, rootCommand.commands) : (command as AnyPadroneCommand);
+    if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
+
+    const parts: string[] = [];
+
+    if (commandObj.path) parts.push(commandObj.path);
+
+    const positionalConfig = commandObj.meta?.positional ? parsePositionalConfig(commandObj.meta.positional) : [];
+    const positionalNames = new Set(positionalConfig.map((p) => p.name));
+
+    if (args && typeof args === 'object') {
+      for (const { name, variadic } of positionalConfig) {
+        const value = (args as Record<string, unknown>)[name];
+        if (value === undefined) continue;
+
+        if (variadic && Array.isArray(value)) {
+          for (const v of value) {
+            const vStr = String(v);
+            if (vStr.includes(' ')) parts.push(`"${vStr}"`);
+            else parts.push(vStr);
+          }
+        } else {
+          const argStr = String(value);
+          if (argStr.includes(' ')) parts.push(`"${argStr}"`);
+          else parts.push(argStr);
+        }
+      }
+
+      const stringifyValue = (key: string, value: unknown) => {
+        if (value === undefined) return;
+
+        if (typeof value === 'boolean') {
+          if (value) parts.push(`--${key}`);
+          else parts.push(`--no-${key}`);
+        } else if (Array.isArray(value)) {
+          for (const v of value) {
+            const vStr = String(v);
+            if (vStr.includes(' ')) parts.push(`--${key}="${vStr}"`);
+            else parts.push(`--${key}=${vStr}`);
+          }
+        } else if (typeof value === 'object' && value !== null) {
+          for (const [nestedKey, nestedValue] of Object.entries(value)) {
+            stringifyValue(`${key}.${nestedKey}`, nestedValue);
+          }
+        } else if (typeof value === 'string') {
+          if (value.includes(' ')) parts.push(`--${key}="${value}"`);
+          else parts.push(`--${key}=${value}`);
+        } else {
+          parts.push(`--${key}=${value}`);
+        }
+      };
+
+      for (const [key, value] of Object.entries(args)) {
+        if (value === undefined || positionalNames.has(key)) continue;
+        stringifyValue(key, value);
+      }
+    }
+
+    return parts.join(' ');
+  };
+
+  const resolveContext = (command: AnyPadroneCommand, initialContext: unknown): unknown => {
+    const chain: AnyPadroneCommand[] = [];
+    let current: AnyPadroneCommand | undefined = command;
+    while (current) {
+      chain.unshift(current);
+      current = current.parent;
+    }
+    let resolved = initialContext;
+    for (const cmd of chain) {
+      if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);
+    }
+    return resolved;
+  };
+
+  const run: AnyPadroneProgram['run'] = (command, args, prefs?: { context?: unknown }) => {
+    try {
+      const commandObj = typeof command === 'string' ? findCommandByName(command, rootCommand.commands) : (command as AnyPadroneCommand);
+      if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
+      if (!commandObj.action) throw new RoutingError(`Command "${commandObj.path}" has no action`, { command: commandObj.path });
+
+      const resolvedCtx = resolveContext(commandObj, prefs?.context);
+      const commandRuntime = getCommandRuntime(commandObj);
+      const executeCtx: InterceptorExecuteContext = {
+        command: commandObj,
+        input: undefined,
+        rawArgs: {},
+        positionalArgs: [],
+        args,
+        signal: inertSignal,
+        context: resolvedCtx,
+        runtime: commandRuntime,
+        program: ctx.builder as any,
+        caller: 'run',
+      };
+
+      const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {
+        const actionCtx: PadroneActionContext = {
+          runtime: executeCtx.runtime,
+          command: executeCtx.command,
+          program: ctx.builder as any,
+          signal: inertSignal,
+          context: executeCtx.context,
+          caller: 'run',
+        };
+        const result = commandObj.action!(executeCtx.args as any, actionCtx);
+        return { result };
+      };
+
+      const commandInterceptors = resolveRegisteredInterceptors(collectInterceptors(commandObj, rootCommand), new Map());
+      const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);
+
+      const toResult = (e: InterceptorExecuteResult) => withDrain({ command: commandObj as any, args: args as any, result: e.result });
+
+      if (executedOrPromise instanceof Promise) {
+        return executedOrPromise.then(toResult).catch((err: unknown) => errorResult(err, { command: commandObj, args })) as any;
+      }
+      return toResult(executedOrPromise);
+    } catch (err) {
+      return errorResult(err) as any;
+    }
+  };
+
+  const tool: AnyPadroneProgram['tool'] = () => {
+    resolveAllCommands(rootCommand);
+    const helpText = generateHelp(rootCommand, undefined, { format: 'text' });
+
+    const description = `Run a command. Pass the full command string including arguments. Use "help <command>" for detailed usage.\n\n${helpText}`;
+
+    return {
+      type: 'function',
+      name: rootCommand.name,
+      strict: true,
+      title: rootCommand.description,
+      description,
+      inputExamples: [{ input: { command: '<command> [positionals...] [arguments...]' } }],
+      inputSchema: {
+        [Symbol.for('vercel.ai.schema') as keyof Schema & symbol]: true,
+        jsonSchema: {
+          type: 'object',
+          properties: { command: { type: 'string' } },
+          additionalProperties: false,
+        },
+        _type: undefined as unknown as { command: string },
+        validate: (value) => {
+          const command = (value as any)?.command;
+          if (typeof command === 'string') return { success: true, value: { command } };
+          return { success: false, error: new Error('Expected an object with command property as string.') };
+        },
+      } satisfies Schema<{ command: string }> as Schema<{ command: string }>,
+      needsApproval: async (input) => {
+        const parsed = await parse(input.command);
+        if (typeof parsed.command.needsApproval === 'function') return parsed.command.needsApproval(parsed.args);
+        if (parsed.command.needsApproval != null) return !!parsed.command.needsApproval;
+        return !!parsed.command.mutation;
+      },
+      execute: async (input) => {
+        const output: string[] = [];
+        const errors: string[] = [];
+        const result = await evalCommand(input.command, {
+          caller: 'tool',
+          runtime: {
+            output: (...args) => output.push(args.map(String).join(' ')),
+            error: (text) => errors.push(text),
+            interactive: 'unsupported',
+            format: 'text',
+          },
+        });
+        return { result: result.result, logs: output.join('\n'), error: errors.join('\n') };
+      },
+    };
+  };
+
+  const replActiveRef = { value: false };
+  const replFn = (options?: PadroneReplPreferences) =>
+    createReplIterator({ existingCommand: rootCommand, evalCommand, replActiveRef }, options);
+
+  const cli: AnyPadroneProgram['cli'] = (cliOptions) => {
+    try {
+      const runtime = getCommandRuntime(rootCommand);
+      const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;
+
+      const result = execCommand(resolvedInput, ctx, cliOptions, 'hard', 'cli');
+
+      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResultWithSignal(err))) as any;
+      return makeThenable(result);
+    } catch (err) {
+      return makeThenable(errorResultWithSignal(err)) as any;
+    }
+  };
+
+  const find: AnyPadroneProgram['find'] = (command) => {
+    if (typeof command !== 'string') return findCommandByName(command.path, rootCommand.commands) as any;
+    return findCommandByName(command, rootCommand.commands) as any;
+  };
+
+  const parse: AnyPadroneProgram['parse'] = (input) => {
+    const { command, rawArgs, args } = ctx.parseCommandFn(input as string | undefined);
+
+    const validatedOrPromise = coreValidateForParse(command, rawArgs, args);
+
+    return makeThenable(
+      warnIfUnexpectedAsync(
+        thenMaybe(validatedOrPromise, (v: any) => ({ command: command as any, args: v.args, argsResult: v.argsResult })),
+        command,
+      ),
+    ) as any;
+  };
+
+  const help: AnyPadroneProgram['help'] = (command, prefs) => {
+    resolveAllCommands(rootCommand);
+    const commandObj = !command
+      ? rootCommand
+      : typeof command === 'string'
+        ? findCommandByName(command, rootCommand.commands)
+        : (command as AnyPadroneCommand);
+    if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
+    const runtime = getCommandRuntime(rootCommand);
+    return generateHelp(rootCommand, commandObj, {
+      ...prefs,
+      format: prefs?.format ?? runtime.format,
+      theme: prefs?.theme ?? runtime.theme,
+      terminal: prefs?.terminal ?? runtime.terminal,
+      env: prefs?.env ?? runtime.env(),
+    });
+  };
+
+  const api: AnyPadroneProgram['api'] = () => {
+    resolveAllCommands(rootCommand);
+    function buildApi(command: AnyPadroneCommand) {
+      const runCommand = ((args) => run(command, args).result) as PadroneAPI<AnyPadroneCommand>;
+      if (!command.commands) return runCommand;
+      for (const cmd of command.commands) runCommand[cmd.name] = buildApi(cmd);
+      return runCommand;
+    }
+    return buildApi(rootCommand);
+  };
+
+  const completion: AnyPadroneProgram['completion'] = async (shell) => {
+    resolveAllCommands(rootCommand);
+    const { generateCompletionOutput } = await import('../feature/completion.ts');
+    return generateCompletionOutput(rootCommand, shell as ShellType | undefined);
+  };
+
+  const mcp: AnyPadroneProgram['mcp'] = async (prefs) => {
+    resolveAllCommands(rootCommand);
+    const { startMcpServer } = await import('../feature/mcp.ts');
+    return startMcpServer(ctx.builder as any, rootCommand, evalCommand, prefs);
+  };
+
+  const serve: AnyPadroneProgram['serve'] = async (prefs) => {
+    resolveAllCommands(rootCommand);
+    const { startServeServer } = await import('../feature/serve.ts');
+    return startServeServer(ctx.builder as any, rootCommand, evalCommand, prefs);
+  };
+
+  return {
+    find,
+    parse,
+    stringify,
+    run,
+    eval: evalCommand,
+    cli,
+    tool,
+    repl: replFn,
+    api,
+    help,
+    completion,
+    mcp,
+    serve,
+  };
+}

package/src/core/results.ts

@@ -0,0 +1,229 @@
+import type { AnyPadroneCommand, PadroneSchema } from '../types/index.ts';
+import type { Thenable } from '../util/type-utils.ts';
+import { getCommandRuntime } from './commands.ts';
+
+/**
+ * Brands a schema as async, signaling that its `validate()` may return a Promise.
+ * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command's `parse()` and `cli()` will return Promises.
+ */
+export function asyncSchema<T extends PadroneSchema>(schema: T): T & { '~async': true } {
+  return Object.assign(schema, { '~async': true as const });
+}
+
+export const noop = <TRes>() => undefined as TRes;
+
+/**
+ * Maps over a value that may or may not be a Promise.
+ * If the value is a Promise, chains with `.then()`. Otherwise, calls the function synchronously.
+ * This preserves sync behavior for sync schemas and async behavior for async schemas.
+ */
+export function thenMaybe<T, U>(value: T | Promise<T>, fn: (v: T) => U | Promise<U>): U | Promise<U> {
+  if (value instanceof Promise) return value.then(fn);
+  return fn(value);
+}
+
+/**
+ * Makes a sync result object thenable by adding `.then()`, `.catch()`, and `.finally()` methods.
+ * If the value is already a Promise, returns it as-is.
+ * This allows users to write `await program.cli()` or `program.cli().then(...)` regardless of sync/async.
+ *
+ * The `.then()` resolves with a plain copy (without thenable methods) to avoid infinite
+ * recursive unwrapping by the Promise resolution algorithm.
+ */
+export function makeThenable<T>(value: T | Promise<T>): Thenable<T> {
+  if (value instanceof Promise) return value as any;
+  if (value !== null && typeof value === 'object' && !('then' in value)) {
+    const toPlain = () => {
+      const plain = { ...value } as any;
+      delete plain.then;
+      delete plain.catch;
+      delete plain.finally;
+      return plain as T;
+    };
+    // biome-ignore lint/suspicious/noThenProperty: intentional thenable shim for sync results
+    (value as any).then = (onfulfilled?: (v: T) => any, onrejected?: (reason: any) => any) => {
+      try {
+        const result = onfulfilled ? onfulfilled(toPlain()) : toPlain();
+        return Promise.resolve(result);
+      } catch (err) {
+        if (onrejected) return Promise.resolve(onrejected(err));
+        return Promise.reject(err);
+      }
+    };
+    (value as any).catch = (onrejected?: (reason: any) => any) => (value as any).then(undefined, onrejected);
+    (value as any).finally = (onfinally?: () => void) =>
+      (value as any).then(
+        (v: any) => {
+          onfinally?.();
+          return v;
+        },
+        (err: any) => {
+          onfinally?.();
+          throw err;
+        },
+      );
+  }
+  return value as any;
+}
+
+/**
+ * Wraps a Promise to include a `drain()` method at the top level.
+ * This allows `await promise.drain()` without first awaiting the promise.
+ * Since cli/eval never reject, this just delegates to the resolved result's `drain()`.
+ */
+export function withPromiseDrain<T extends Promise<any>>(promise: T): T & { drain: () => Promise<any> } {
+  (promise as any).drain = async () => {
+    const resolved = await promise;
+    return resolved.drain();
+  };
+  return promise as any;
+}
+
+export function isIterator(value: unknown): value is Iterator<unknown> {
+  return typeof value === 'object' && value !== null && Symbol.iterator in value && typeof (value as any)[Symbol.iterator] === 'function';
+}
+
+export function isAsyncIterator(value: unknown): value is AsyncIterator<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Symbol.asyncIterator in value &&
+    typeof (value as any)[Symbol.asyncIterator] === 'function'
+  );
+}
+
+/**
+ * Writes a command's return value to output, handling promises, iterators, and async iterators.
+ * Values are passed directly to the output function without stringification —
+ * runtimes like Node/Bun already format objects via console.log.
+ * Returns void or a Promise depending on whether async consumption is needed.
+ */
+export function outputValue(value: unknown, output: (...args: unknown[]) => void): void | Promise<void> {
+  if (value == null) return;
+
+  // Async iterator — consume and output each yielded value
+  if (isAsyncIterator(value)) {
+    return (async () => {
+      const iter = (value as any)[Symbol.asyncIterator]();
+      while (true) {
+        const { done, value: item } = await iter.next();
+        if (done) break;
+        if (item != null) output(item);
+      }
+    })();
+  }
+
+  // Sync iterator (but not a plain string/array which also have Symbol.iterator)
+  if (typeof value !== 'string' && !Array.isArray(value) && isIterator(value)) {
+    const iter = (value as any)[Symbol.iterator]();
+    while (true) {
+      const { done, value: item } = iter.next();
+      if (done) break;
+      if (item != null) output(item);
+    }
+    return;
+  }
+
+  // Promise — await then output
+  if (value instanceof Promise) {
+    return value.then((resolved) => outputValue(resolved, output));
+  }
+
+  // Pass value directly — runtime handles formatting
+  output(value);
+}
+
+/**
+ * Resolves a result value by unwrapping Promises and collecting iterables into arrays.
+ * This is the runtime counterpart of the `Drained<T>` type.
+ */
+export async function drainValue(value: unknown): Promise<unknown> {
+  // Unwrap promises first
+  if (value instanceof Promise) {
+    return drainValue(await value);
+  }
+
+  // Async iterator — collect into array
+  if (isAsyncIterator(value)) {
+    const items: unknown[] = [];
+    const iter = (value as any)[Symbol.asyncIterator]();
+    while (true) {
+      const { done, value: item } = await iter.next();
+      if (done) break;
+      items.push(item);
+    }
+    return items;
+  }
+
+  // Sync iterator (but not string/array)
+  if (typeof value !== 'string' && !Array.isArray(value) && isIterator(value)) {
+    const items: unknown[] = [];
+    const iter = (value as any)[Symbol.iterator]();
+    while (true) {
+      const { done, value: item } = iter.next();
+      if (done) break;
+      items.push(item);
+    }
+    return items;
+  }
+
+  return value;
+}
+
+/**
+ * Attaches a `drain()` method to a command result object.
+ * If the result has an `error` field, `drain()` returns `{ error }`.
+ * Otherwise, resolves the result (unwrapping Promises, collecting iterables), catches errors,
+ * and returns a discriminated union `{ value } | { error }` that never throws.
+ */
+export function withDrain<T extends Record<string, unknown>>(obj: T): T & { drain: () => Promise<any> } {
+  (obj as any).drain = async () => {
+    if ('error' in obj && obj.error !== undefined) {
+      return { error: obj.error };
+    }
+    try {
+      const value = await drainValue(obj.result);
+      return { value };
+    } catch (err) {
+      return { error: err };
+    }
+  };
+  return obj as any;
+}
+
+/**
+ * Creates an error command result with a `drain()` that returns the error.
+ */
+export function errorResult(error: unknown, partial?: { command?: unknown; args?: unknown; argsResult?: unknown }) {
+  return withDrain({
+    error,
+    result: undefined,
+    command: partial?.command,
+    args: partial?.args,
+    argsResult: partial?.argsResult,
+  });
+}
+
+export function isAsyncBranded(schema: unknown): boolean {
+  return !!schema && typeof schema === 'object' && '~async' in schema && (schema as any)['~async'] === true;
+}
+
+export function hasInteractiveConfig(meta: unknown): boolean {
+  if (!meta || typeof meta !== 'object') return false;
+  const m = meta as Record<string, unknown>;
+  return m.interactive === true || Array.isArray(m.interactive) || m.optionalInteractive === true || Array.isArray(m.optionalInteractive);
+}
+
+export function warnIfUnexpectedAsync<T>(value: T, command: AnyPadroneCommand): T {
+  const runtime = getCommandRuntime(command);
+  if (runtime.env().NODE_ENV === 'production') return value;
+  if (value instanceof Promise && !command.isAsync) {
+    runtime.error(
+      `[padrone] Command "${command.path || command.name}" returned a Promise from validation, ` +
+        `but was not marked as async. Use \`.async()\` on the builder or \`asyncSchema()\` to brand your schema. ` +
+        `Without this, TypeScript will infer a sync return type and the result will be a Promise at runtime.`,
+    );
+  }
+  return value;
+}