padrone 1.3.0 → 1.5.0

package/src/help.ts

@@ -1,5 +1,6 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec';
-import { extractSchemaMetadata, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import { extractSchemaMetadata, JSON_SCHEMA_OPTS, type PadroneArgsSchemaMeta, parsePositionalConfig, parseStdinConfig } from './args.ts';
+import type { ColorConfig, ColorTheme } from './colorizer.ts';
 import { findCommandByName } from './command-utils.ts';
 import {
   createFormatter,
@@ -16,6 +17,9 @@ import { getRootCommand } from './utils.ts';
 export type HelpPreferences = {
   format?: HelpFormat | 'auto';
   detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig;
+  /** Show all global commands and flags in full detail */
+  all?: boolean;
 };
 
 /**
@@ -35,7 +39,7 @@ function extractPositionalArgsInfo(
   const positionalConfig = parsePositionalConfig(meta.positional);
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
 
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
       const properties = jsonSchema.properties as Record<string, any>;
@@ -54,6 +58,7 @@ function extractPositionalArgsInfo(
           optional: !required.includes(name),
           default: prop.default,
           type: variadic ? `array<${prop.items?.type || 'string'}>` : prop.type,
+          enum: (prop.enum ?? prop.items?.enum) as string[] | undefined,
         });
       }
     }
@@ -74,7 +79,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
   const argsMeta = meta?.fields;
 
   try {
-    const jsonSchema = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    const jsonSchema = schema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
 
     // Handle object: z.object({ key: z.string(), ... })
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
@@ -133,6 +138,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
           examples: optMeta?.examples ?? prop?.examples,
           variadic: propType === 'array',
           negatable: isNegatable,
+          group: optMeta?.group,
         });
       }
     }
@@ -153,7 +159,7 @@ function extractArgsInfo(schema: StandardJSONSchemaV1, meta?: PadroneArgsSchemaM
  * @param cmd - The command to build help info for
  * @param detail - The level of detail ('minimal', 'standard', or 'full')
  */
-export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard'): HelpInfo {
+export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['detail'] = 'standard', all?: boolean): HelpInfo {
   const rootCmd = getRootCommand(cmd);
   // A command is a "default" command if its name is '' or it has '' as an alias
   const isDefaultCommand = cmd.parent && (!cmd.name || cmd.aliases?.includes(''));
@@ -175,6 +181,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     name: commandName,
     title: cmd.title,
     description: cmd.description,
+    examples: cmd.examples,
     aliases: displayAliases,
     deprecated: cmd.deprecated,
     hidden: cmd.hidden,
@@ -183,7 +190,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
       hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
       hasPositionals,
       hasArguments: false, // updated below after extracting arguments
-      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin).field : undefined,
+      stdinField: cmd.meta?.stdin ? parseStdinConfig(cmd.meta.stdin) : undefined,
     },
   };
 
@@ -221,6 +228,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               aliases: displayAliases?.length ? displayAliases : undefined,
               deprecated: c.deprecated,
               hidden: c.hidden,
+              group: c.group,
             },
             {
               name: displayName,
@@ -229,6 +237,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
               deprecated: c.deprecated,
               hidden: c.hidden,
               hasSubcommands: true,
+              group: c.group,
             },
           ];
         }
@@ -242,6 +251,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
             deprecated: c.deprecated,
             hidden: c.hidden,
             hasSubcommands,
+            group: c.group,
           },
         ];
       }),
@@ -284,40 +294,64 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
     }
   }
 
-  // Add built-in commands/flags for root command only
-  if (!cmd.parent) {
+  // Add global commands/flags (root command by default, all commands when --all is passed)
+  if (!cmd.parent || all) {
     const builtins: HelpInfo['builtins'] = [];
 
-    if (!findCommandByName('help', cmd.commands)) {
+    if (!findCommandByName('help', rootCmd.commands)) {
       builtins.push({
         name: 'help [command], -h, --help',
         description: 'Show help for a command',
         sub: [
+          { name: '--all', description: 'Show all global commands and flags' },
           { name: '--detail <level>', description: 'Detail level (minimal, standard, full)' },
           { name: '--format <format>', description: 'Output format (text, ansi, json, markdown, html)' },
         ],
       });
     }
 
-    if (!findCommandByName('version', cmd.commands)) {
+    if (!findCommandByName('version', rootCmd.commands)) {
       builtins.push({
         name: 'version, -v, --version',
         description: 'Show version information',
       });
     }
 
-    if (!findCommandByName('completion', cmd.commands)) {
+    if (!findCommandByName('completion', rootCmd.commands)) {
       builtins.push({
         name: 'completion [shell]',
         description: 'Generate shell completions (bash, zsh, fish, powershell)',
       });
     }
 
+    if (!findCommandByName('man', rootCmd.commands)) {
+      builtins.push({
+        name: 'man',
+        description: 'Show or install man pages (--setup to install, --remove to uninstall) (experimental)',
+      });
+    }
+
     builtins.push({
       name: '[command] --repl',
       description: 'Start interactive REPL scoped to a command',
     });
 
+    if (!findCommandByName('mcp', rootCmd.commands)) {
+      builtins.push({
+        name: 'mcp [http|stdio]',
+        description: 'Start a Model Context Protocol server to expose commands as AI tools (experimental)',
+        sub: [
+          { name: '--port <port>', description: 'HTTP port (default: 3000)' },
+          { name: '--host <host>', description: 'HTTP host (default: 127.0.0.1)' },
+        ],
+      });
+    }
+
+    builtins.push({
+      name: '--color [theme], --no-color',
+      description: 'Set color theme (default, ocean, warm, monochrome) or disable colors',
+    });
+
     if (builtins.length > 0) {
       helpInfo.builtins = builtins;
     }
@@ -331,7 +365,7 @@ export function getHelpInfo(cmd: AnyPadroneCommand, detail: HelpPreferences['det
 // ============================================================================
 
 export function generateHelp(rootCommand: AnyPadroneCommand, commandObj: AnyPadroneCommand = rootCommand, prefs?: HelpPreferences): string {
-  const helpInfo = getHelpInfo(commandObj, prefs?.detail);
-  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail);
+  const helpInfo = getHelpInfo(commandObj, prefs?.detail, prefs?.all);
+  const formatter = createFormatter(prefs?.format ?? 'auto', prefs?.detail, prefs?.theme, prefs?.all);
   return formatter.format(helpInfo);
 }

package/src/index.ts

@@ -1,10 +1,24 @@
+export type { AnsiStyle, ColorConfig, ColorTheme } from './colorizer.ts';
+export { colorThemes } from './colorizer.ts';
 export { asyncSchema, buildReplCompleter, createPadrone } from './create.ts';
 export type { PadroneErrorOptions } from './errors.ts';
 export { ActionError, ConfigError, PadroneError, RoutingError, ValidationError } from './errors.ts';
 export type { HelpInfo } from './formatter.ts';
-export type { InteractiveMode, InteractivePromptConfig, PadroneRuntime } from './runtime.ts';
+export type { PadroneMcpPreferences } from './mcp.ts';
+export type {
+  InteractiveMode,
+  InteractivePromptConfig,
+  PadroneProgressIndicator,
+  PadroneProgressOptions,
+  PadroneRuntime,
+  PadroneSpinnerConfig,
+  PadroneSpinnerPreset,
+} from './runtime.ts';
 export { REPL_SIGINT } from './runtime.ts';
+export type { AsyncStreamMeta } from './stream.ts';
+export { asyncStream } from './stream.ts';
 export type { InferArgsInput, InferArgsOutput, InferCommand } from './type-helpers.ts';
+export type { Drained } from './type-utils.ts';
 export type {
   AnyPadroneBuilder,
   AnyPadroneCommand,
@@ -14,10 +28,24 @@ export type {
   PadroneBuilder,
   PadroneCommand,
   PadroneCommandResult,
+  PadroneDrainResult,
   PadroneParseResult,
   PadronePlugin,
   PadroneProgram,
+  PadroneProgressMessage,
+  PadroneProgressPrefs as PadroneProgressConfig,
   PadroneSchema,
+  PluginBaseContext,
+  PluginErrorContext,
+  PluginErrorResult,
+  PluginExecuteContext,
+  PluginExecuteResult,
+  PluginParseContext,
+  PluginParseResult,
+  PluginShutdownContext,
+  PluginStartContext,
+  PluginValidateContext,
+  PluginValidateResult,
 } from './types.ts';
 export type { UpdateCheckConfig } from './update-check.ts';
 export type { WrapConfig, WrapResult } from './wrap.ts';

package/src/interactive.ts

@@ -1,3 +1,4 @@
+import { JSON_SCHEMA_OPTS } from './args.ts';
 import type { InteractivePromptConfig, ResolvedPadroneRuntime } from './runtime.ts';
 import type { AnyPadroneCommand } from './types.ts';
 
@@ -44,6 +45,46 @@ export function detectPromptConfig(
   return { name, message, type: 'input', default: propSchema.default };
 }
 
+/**
+ * Prompt a single field and validate it against the command's schema.
+ * Re-prompts with a warning until the user provides a valid value.
+ */
+async function promptWithValidation(
+  field: string,
+  config: InteractivePromptConfig,
+  currentData: Record<string, unknown>,
+  command: AnyPadroneCommand,
+  runtime: ResolvedPadroneRuntime,
+): Promise<unknown> {
+  let promptConfig = config;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const value = await runtime.prompt!(promptConfig);
+
+    if (!command.argsSchema) return value;
+
+    // Validate the full object with the new value to catch field-level issues
+    const testData = { ...currentData, [field]: value };
+    const validated = await command.argsSchema['~standard'].validate(testData);
+
+    if (!validated.issues) return value;
+
+    // Only keep issues whose path starts with this field
+    const fieldIssues = validated.issues.filter((issue: { path?: ReadonlyArray<PropertyKey> }) => {
+      const rootKey = issue.path?.[0];
+      return rootKey !== undefined && String(rootKey) === field;
+    });
+
+    if (fieldIssues.length === 0) return value;
+
+    // Warn the user and re-prompt with the invalid value as default
+    const messages = fieldIssues.map((i: { message: string }) => i.message).join('; ');
+    runtime.error(`Invalid value for "${field}": ${messages}`);
+    promptConfig = { ...config, default: value };
+  }
+}
+
 /**
  * Prompt for missing interactive fields.
  * Runs after env/config preprocessing and before schema validation.
@@ -69,7 +110,7 @@ export async function promptInteractiveFields(
   let requiredFields: Set<string> = new Set();
   if (command.argsSchema) {
     try {
-      const jsonSchema = command.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+      const jsonSchema = command.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
       if (jsonSchema.type === 'object' && jsonSchema.properties) {
         jsonProperties = jsonSchema.properties;
       }
@@ -108,14 +149,14 @@ export async function promptInteractiveFields(
     }
   }
 
-  // Prompt each required interactive field
+  // Prompt each required interactive field with per-field validation
   for (const field of fieldsToPrompt) {
     const config = detectPromptConfig(field, jsonProperties[field], fieldDescriptions[field]);
     // When forced, use the current value as the default
     if (force && result[field] !== undefined) {
       config.default = result[field];
     }
-    result[field] = await runtime.prompt(config);
+    result[field] = await promptWithValidation(field, config, result, command, runtime);
   }
 
   // Determine optional interactive fields
@@ -160,7 +201,7 @@ export async function promptInteractiveFields(
         if (force && result[field] !== undefined) {
           config.default = result[field];
         }
-        result[field] = await runtime.prompt(config);
+        result[field] = await promptWithValidation(field, config, result, command, runtime);
       }
     }
   }