padrone 1.3.0 → 1.5.0

package/src/command-utils.ts

@@ -1,5 +1,6 @@
-import { extractSchemaMetadata } from './args.ts';
-import { type ResolvedPadroneRuntime, resolveRuntime } from './runtime.ts';
+import { extractSchemaMetadata, JSON_SCHEMA_OPTS } from './args.ts';
+import { type PadroneProgressIndicator, type ResolvedPadroneRuntime, resolveRuntime } from './runtime.ts';
+import type { Thenable } from './type-utils.ts';
 import type {
   AnyPadroneCommand,
   PadronePlugin,
@@ -10,6 +11,42 @@ import type {
   PluginStartContext,
 } from './types.ts';
 
+// ---------------------------------------------------------------------------
+// Lazy command resolution
+// ---------------------------------------------------------------------------
+
+export const lazyResolver = Symbol('lazyResolver');
+
+/** Resolves a lazy command in place by calling its stored resolver. No-op if already resolved. */
+export function resolveCommand(cmd: AnyPadroneCommand): AnyPadroneCommand {
+  const resolver = (cmd as any)[lazyResolver];
+  if (resolver) {
+    delete (cmd as any)[lazyResolver];
+    resolver(cmd);
+  }
+  return cmd;
+}
+
+/** Recursively resolves a command and all its descendants. */
+export function resolveAllCommands(cmd: AnyPadroneCommand): void {
+  resolveCommand(cmd);
+  if (cmd.commands) {
+    for (const sub of cmd.commands) resolveAllCommands(sub);
+  }
+}
+
+/** Checks whether a value is a Padrone program/builder. */
+export function isPadroneProgram(value: unknown): value is object {
+  return !!value && typeof value === 'object' && commandSymbol in value;
+}
+
+/** Extracts the underlying command from a program/builder and resolves the full command tree. */
+export function getCommand(program: object): AnyPadroneCommand {
+  const cmd = commandSymbol in program ? ((program as any)[commandSymbol] as AnyPadroneCommand) : (program as AnyPadroneCommand);
+  resolveAllCommands(cmd);
+  return cmd;
+}
+
 /**
  * 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()`,
@@ -45,6 +82,7 @@ export const configKeys = [
   'version',
   'deprecated',
   'hidden',
+  'mutation',
   'needsApproval',
   'autoOutput',
   'updateCheck',
@@ -57,6 +95,8 @@ export const configKeys = [
  * - Subcommands are recursively merged by name.
  */
 export function mergeCommands(existing: AnyPadroneCommand, override: AnyPadroneCommand): AnyPadroneCommand {
+  resolveCommand(existing);
+  resolveCommand(override);
   const merged: AnyPadroneCommand = { ...existing };
 
   // Merge config fields
@@ -75,6 +115,7 @@ export function mergeCommands(existing: AnyPadroneCommand, override: AnyPadroneC
   if (override.runtime !== existing.runtime) merged.runtime = override.runtime;
   if (override.plugins !== existing.plugins) merged.plugins = override.plugins;
   if (override.aliases !== existing.aliases) merged.aliases = override.aliases;
+  if (override.progress !== existing.progress) merged.progress = override.progress;
 
   // Recursively merge subcommands by name
   if (override.commands) {
@@ -103,6 +144,63 @@ export function thenMaybe<T, U>(value: T | Promise<T>, fn: (v: T) => U | Promise
   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';
 }
@@ -157,6 +255,95 @@ export function outputValue(value: unknown, output: (...args: unknown[]) => void
   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,
+  });
+}
+
+/**
+ * Deduplicates plugins by `id`. When multiple plugins share the same `id`,
+ * only the last one in the array is kept. Plugins without an `id` are always kept.
+ */
+function deduplicatePlugins(plugins: PadronePlugin<any, any>[]): PadronePlugin<any, any>[] {
+  // Fast path: no ids at all
+  if (!plugins.some((p) => p.id)) return plugins;
+
+  // Find the last index for each id
+  const lastIndex = new Map<string, number>();
+  for (let i = 0; i < plugins.length; i++) {
+    const id = plugins[i]!.id;
+    if (id) lastIndex.set(id, i);
+  }
+
+  return plugins.filter((p, i) => !p.id || lastIndex.get(p.id) === i);
+}
+
 /**
  * Runs a plugin chain for a given phase using the onion/middleware pattern.
  * Plugins are sorted by `order` (ascending, stable), then composed so that
@@ -165,12 +352,13 @@ export function outputValue(value: unknown, output: (...args: unknown[]) => void
  */
 export function runPluginChain<TCtx, TResult>(
   phase: 'start' | 'parse' | 'validate' | 'execute' | 'error' | 'shutdown',
-  plugins: PadronePlugin[],
+  plugins: PadronePlugin<any, any>[],
   ctx: TCtx,
   core: () => TResult | Promise<TResult>,
 ): TResult | Promise<TResult> {
-  // Filter to plugins that have a handler for this phase, preserve insertion order
-  const phasePlugins = plugins.filter((p) => p[phase]);
+  // Deduplicate by id (last wins), then filter to plugins that have a handler for this phase
+  const deduped = deduplicatePlugins(plugins);
+  const phasePlugins = deduped.filter((p) => p[phase]);
   if (phasePlugins.length === 0) return core();
 
   // Stable sort by order (lower = outermost). Equal order preserves registration order.
@@ -197,7 +385,7 @@ export function runPluginChain<TCtx, TResult>(
  * - Always: `shutdown` plugins run (success or failure).
  */
 export function wrapWithLifecycle<T>(
-  plugins: PadronePlugin[],
+  plugins: PadronePlugin<any, any>[],
   command: AnyPadroneCommand,
   state: Record<string, unknown>,
   input: string | undefined,
@@ -208,10 +396,54 @@ export function wrapWithLifecycle<T>(
   const hasError = plugins.some((p) => p.error);
   const hasShutdown = plugins.some((p) => p.shutdown);
 
-  // Fast path: no lifecycle plugins
-  if (!hasStart && !hasError && !hasShutdown) return pipeline();
+  const cleanupProgress = (error?: unknown, result?: unknown) => {
+    const indicator = state._progress as PadroneProgressIndicator | undefined;
+    if (indicator) {
+      // If there's no progress config (lazy/manual indicator), just stop it silently
+      const hasProgressConfig = '_progressMsg' in state;
+      if (!hasProgressConfig) {
+        indicator.stop();
+      } else if (error !== undefined) {
+        const fallback = error instanceof Error ? error.message : String(error);
+        const { message: errorMsg, indicator: errorIcon } = resolveProgressMessage(state._progressError, error, fallback);
+        indicator.fail(errorMsg, errorIcon !== undefined ? { indicator: errorIcon } : undefined);
+      } else {
+        const { message: successMsg, indicator: successIcon } = resolveProgressMessage(state._progressSuccess, result);
+        indicator.succeed(successMsg, successIcon !== undefined ? { indicator: successIcon } : undefined);
+      }
+      (state._restoreOutput as (() => void) | undefined)?.();
+      state._progress = undefined;
+      state._restoreOutput = undefined;
+    }
+  };
+
+  // Fast path: no lifecycle plugins — still need progress cleanup
+  if (!hasStart && !hasError && !hasShutdown) {
+    let result: T | Promise<T>;
+    try {
+      result = pipeline();
+    } catch (e) {
+      cleanupProgress(e);
+      throw e;
+    }
+    if (result instanceof Promise) {
+      return result.then(
+        (r) => {
+          cleanupProgress();
+          return r;
+        },
+        (e) => {
+          cleanupProgress(e);
+          throw e;
+        },
+      );
+    }
+    cleanupProgress();
+    return result;
+  }
 
   const runShutdown = (error?: unknown, result?: unknown) => {
+    cleanupProgress(error);
     if (!hasShutdown) return;
     const ctx: PluginShutdownContext = { command, state, error, result };
     return runPluginChain('shutdown', plugins, ctx, () => {});
@@ -276,6 +508,85 @@ export function getCommandRuntime(cmd: AnyPadroneCommand): ResolvedPadroneRuntim
   return resolveRuntime();
 }
 
+/** No-op progress indicator returned when the runtime doesn't provide a `progress` factory. */
+const noopIndicator: PadroneProgressIndicator = {
+  update() {},
+  succeed() {},
+  fail() {},
+  stop() {},
+  pause() {},
+  resume() {},
+};
+
+/** Creates a progress indicator from the runtime, or returns a no-op if unavailable. */
+export function createProgress(
+  runtime: ResolvedPadroneRuntime,
+  message: string,
+  options?: import('./runtime.ts').PadroneProgressOptions,
+): PadroneProgressIndicator {
+  return runtime.progress?.(message, options) ?? noopIndicator;
+}
+
+/**
+ * Creates a lazy progress indicator that defers real indicator creation until first use.
+ * This allows `ctx.progress` to work even without `.progress()` config, as long as the
+ * runtime provides a progress factory.
+ */
+export function createLazyIndicator(runtime: ResolvedPadroneRuntime, state: Record<string, unknown>): PadroneProgressIndicator {
+  if (!runtime.progress) return noopIndicator;
+
+  let real: PadroneProgressIndicator | undefined;
+  const ensure = (message?: string) => {
+    if (!real) {
+      real = runtime.progress!(message ?? '', undefined);
+      state._progress = real;
+    }
+    return real;
+  };
+
+  return {
+    update(msg) {
+      ensure(msg).update(msg);
+    },
+    succeed(msg) {
+      if (real) real.succeed(msg);
+    },
+    fail(msg) {
+      if (real) real.fail(msg);
+    },
+    stop() {
+      if (real) real.stop();
+    },
+    pause() {
+      if (real) real.pause();
+    },
+    resume() {
+      if (real) real.resume();
+    },
+  };
+}
+
+/**
+ * Resolves a progress message field (static or callback) into the arguments for succeed/fail.
+ * Handles string, null, `{ message, indicator }` objects, and callback functions.
+ */
+export function resolveProgressMessage(
+  field: unknown,
+  value: unknown,
+  fallback?: string,
+): { message: string | null | undefined; indicator?: string } {
+  const raw = typeof field === 'function' ? (field as (v: unknown) => unknown)(value) : field;
+  if (raw === undefined) return { message: fallback };
+  if (raw === null || typeof raw === 'string') return { message: raw };
+  if (typeof raw === 'object' && raw !== null) {
+    const obj = raw as { message?: string | null; indicator?: string };
+    return { message: obj.message, indicator: obj.indicator };
+  }
+  return { message: fallback };
+}
+
+export { noopIndicator };
+
 export function isAsyncBranded(schema: unknown): boolean {
   return !!schema && typeof schema === 'object' && '~async' in schema && (schema as any)['~async'] === true;
 }
@@ -308,6 +619,7 @@ export function repathCommandTree(
   parentPath: string,
   parent: AnyPadroneCommand,
 ): AnyPadroneCommand {
+  resolveCommand(cmd);
   const newPath = parentPath ? `${parentPath} ${newName}` : newName;
   const remounted: AnyPadroneCommand = {
     ...cmd,
@@ -335,6 +647,7 @@ export function buildReplCompleter(
     inScope?: boolean;
   },
 ): (line: string) => [string[], string] {
+  resolveAllCommands(rootCommand);
   return (line: string): [string[], string] => {
     const trimmed = line.trimStart();
     const parts = trimmed.split(/\s+/);
@@ -354,9 +667,12 @@ export function buildReplCompleter(
       const commandParts = parts.slice(0, -1).filter((p) => !p.startsWith('-'));
       let targetCommand = rootCommand;
       for (const part of commandParts) {
+        resolveCommand(targetCommand);
         const sub = targetCommand.commands?.find((c) => c.name === part || c.aliases?.includes(part));
-        if (sub) targetCommand = sub;
-        else break;
+        if (sub) {
+          resolveCommand(sub);
+          targetCommand = sub;
+        } else break;
       }
 
       // Get options for this command
@@ -365,7 +681,7 @@ export function buildReplCompleter(
         try {
           const argsMeta = targetCommand.meta?.fields;
           const { flags, aliases } = extractSchemaMetadata(targetCommand.argsSchema, argsMeta, targetCommand.meta?.autoAlias);
-          const jsonSchema = targetCommand.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+          const jsonSchema = targetCommand.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
           if (jsonSchema.type === 'object' && jsonSchema.properties) {
             for (const key of Object.keys(jsonSchema.properties)) {
               options.push(`--${key}`);
@@ -393,9 +709,12 @@ export function buildReplCompleter(
     // Walk into subcommands for all but the last token
     let targetCommand = rootCommand;
     for (let i = 0; i < commandParts.length - 1; i++) {
+      resolveCommand(targetCommand);
       const sub = targetCommand.commands?.find((c) => c.name === commandParts[i] || c.aliases?.includes(commandParts[i]!));
-      if (sub) targetCommand = sub;
-      else break;
+      if (sub) {
+        resolveCommand(sub);
+        targetCommand = sub;
+      } else break;
     }
 
     const candidates: string[] = [];
@@ -477,28 +796,87 @@ export function findCommandByName(name: string, commands?: AnyPadroneCommand[]):
   if (!commands) return undefined;
 
   const foundByName = commands.find((cmd) => cmd.name === name);
-  if (foundByName) return foundByName;
+  if (foundByName) return resolveCommand(foundByName);
 
   // Check for aliases
   const foundByAlias = commands.find((cmd) => cmd.aliases?.includes(name));
-  if (foundByAlias) return foundByAlias;
+  if (foundByAlias) return resolveCommand(foundByAlias);
 
   for (const cmd of commands) {
-    if (cmd.commands && name.startsWith(`${cmd.name} `)) {
-      const subCommandName = name.slice(cmd.name.length + 1);
-      const subCommand = findCommandByName(subCommandName, cmd.commands);
-      if (subCommand) return subCommand;
+    if (name.startsWith(`${cmd.name} `)) {
+      resolveCommand(cmd);
+      if (cmd.commands) {
+        const subCommandName = name.slice(cmd.name.length + 1);
+        const subCommand = findCommandByName(subCommandName, cmd.commands);
+        if (subCommand) return subCommand;
+      }
     }
     // Check aliases for nested commands
-    if (cmd.commands && cmd.aliases) {
+    if (cmd.aliases) {
       for (const alias of cmd.aliases) {
         if (name.startsWith(`${alias} `)) {
-          const subCommandName = name.slice(alias.length + 1);
-          const subCommand = findCommandByName(subCommandName, cmd.commands);
-          if (subCommand) return subCommand;
+          resolveCommand(cmd);
+          if (cmd.commands) {
+            const subCommandName = name.slice(alias.length + 1);
+            const subCommand = findCommandByName(subCommandName, cmd.commands);
+            if (subCommand) return subCommand;
+          }
         }
       }
     }
   }
   return undefined;
 }
+
+// ---------------------------------------------------------------------------
+// Shared utilities for MCP and serve
+// ---------------------------------------------------------------------------
+
+export type CollectedEndpoint = { name: string; command: AnyPadroneCommand };
+
+/** Collect all actionable commands recursively. Hidden commands are excluded. */
+export function collectEndpoints(commands: AnyPadroneCommand[] | undefined, prefix: string): CollectedEndpoint[] {
+  if (!commands) return [];
+  const endpoints: CollectedEndpoint[] = [];
+  for (const cmd of commands) {
+    resolveCommand(cmd);
+    if (cmd.hidden) continue;
+    const path = cmd.name ? (prefix ? `${prefix}.${cmd.name}` : cmd.name) : prefix;
+    if (cmd.action || cmd.argsSchema) {
+      endpoints.push({ name: path, command: cmd });
+    }
+    if (cmd.commands?.length) {
+      endpoints.push(...collectEndpoints(cmd.commands, path));
+    }
+  }
+  return endpoints;
+}
+
+/** Build the JSON Schema for a command's arguments. */
+export function buildInputSchema(cmd: AnyPadroneCommand): Record<string, unknown> {
+  if (!cmd.argsSchema) {
+    return { type: 'object', additionalProperties: false };
+  }
+  try {
+    return cmd.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, unknown>;
+  } catch {
+    return { type: 'object', additionalProperties: false };
+  }
+}
+
+/** Serialize a record of args into CLI flag strings. */
+export function serializeArgsToFlags(args: Record<string, unknown>): string[] {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined) continue;
+    if (typeof value === 'boolean') {
+      parts.push(value ? `--${key}` : `--no-${key}`);
+    } else if (Array.isArray(value)) {
+      for (const v of value) parts.push(`--${key}=${String(v)}`);
+    } else {
+      const strVal = String(value);
+      parts.push(strVal.includes(' ') ? `--${key}="${strVal}"` : `--${key}=${strVal}`);
+    }
+  }
+  return parts;
+}