padrone 1.5.0 → 1.7.0

package/src/extension/update-check.ts

@@ -0,0 +1,77 @@
+import { thenMaybe } from '#src/core/results.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { UpdateCheckConfig } from '../feature/update-check.ts';
+import type { AnyPadroneBuilder, CommandTypesBase } from '../types/index.ts';
+import { getVersion } from '../util/utils.ts';
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+function createUpdateCheckInterceptor(config: UpdateCheckConfig) {
+  return defineInterceptor({ id: 'padrone:update-check', name: 'padrone:update-check', order: 1000 }, () => {
+    let checkPromise: Promise<(() => void) | undefined> | undefined;
+    let suppressed = false;
+
+    return {
+      start(ctx, next) {
+        const rootCommand = ctx.command;
+        const runtime = ctx.runtime;
+
+        checkPromise = Promise.resolve(getVersion(rootCommand.version)).then((currentVersion) =>
+          import('../feature/update-check.ts').then(({ createUpdateChecker }) =>
+            createUpdateChecker(rootCommand.name, currentVersion, config, runtime),
+          ),
+        );
+
+        return next();
+      },
+      parse(_ctx, next) {
+        return thenMaybe(next(), (res) => {
+          if ('update-check' in res.rawArgs) {
+            if (res.rawArgs['update-check'] === false) suppressed = true;
+            delete res.rawArgs['update-check'];
+          }
+          return res;
+        });
+      },
+      shutdown(_ctx, next) {
+        const result = next();
+        if (suppressed || !checkPromise) return result;
+
+        // Try to show notification synchronously if the check already resolved
+        let resolved: (() => void) | undefined | null = null;
+        checkPromise.then(
+          (fn) => {
+            resolved = fn;
+          },
+          () => {
+            resolved = undefined;
+          },
+        );
+
+        if (resolved !== null) {
+          (resolved as (() => void) | undefined)?.();
+        }
+
+        return result;
+      },
+    };
+  });
+}
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds background update checking:
+ * - Checks for newer versions on npm (or custom registry) in the background
+ * - Shows an update notification after command execution
+ * - Respects `--no-update-check` flag to suppress
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))
+ * ```
+ */
+export function padroneUpdateCheck(config: UpdateCheckConfig = {}): <T extends CommandTypesBase>(builder: T) => T {
+  return ((builder: AnyPadroneBuilder) => builder.intercept(createUpdateCheckInterceptor(config))) as any;
+}

package/src/extension/utils.ts

@@ -0,0 +1,51 @@
+import type { AnyPadroneCommand, PadroneSchema } from '../types/index.ts';
+
+type SchemaShape = Record<string, 'string' | 'string[]' | 'boolean'>;
+
+type InferPassthroughSchema<T extends SchemaShape> = {
+  [K in keyof T]: T[K] extends 'string' ? string : T[K] extends 'string[]' ? string[] : T[K] extends 'boolean' ? boolean : never;
+};
+
+/** Minimal Standard Schema that passes through known fields, ignoring unknown ones. */
+export function passthroughSchema<TShape extends SchemaShape>(fields: TShape): PadroneSchema<InferPassthroughSchema<TShape>> {
+  return {
+    '~standard': {
+      version: 1 as const,
+      vendor: 'padrone' as const,
+      jsonSchema: {
+        input: () => ({}),
+        output: () => ({}),
+      },
+      validate: (value) => {
+        const input = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+        const result: Record<string, unknown> = {};
+        for (const [name, type] of Object.entries(fields)) {
+          const v = input[name];
+          if (v === undefined) continue;
+          if (type === 'string[]') {
+            if (Array.isArray(v)) result[name] = v.map(String);
+            else if (typeof v === 'string') result[name] = [v];
+          } else if (type === 'string') {
+            if (typeof v === 'string') result[name] = v;
+            else if (Array.isArray(v) && v.length > 0) result[name] = String(v[0]);
+          } else if (type === 'boolean') {
+            result[name] = v === true || v === 'true';
+          }
+        }
+        return { value: result as InferPassthroughSchema<TShape> };
+      },
+    },
+  };
+}
+
+/** Find a command by space-separated name in the command tree. */
+export function findCommandInTree(name: string, rootCommand: AnyPadroneCommand): AnyPadroneCommand | undefined {
+  const parts = name.split(' ').filter(Boolean);
+  let current = rootCommand;
+  for (const part of parts) {
+    const found = current.commands?.find((c) => c.name === part || c.aliases?.includes(part));
+    if (!found) return undefined;
+    current = found;
+  }
+  return current;
+}

package/src/extension/version.ts

@@ -0,0 +1,63 @@
+import { thenMaybe } from '#src/core/results.ts';
+import { resolveCommand } from '../core/commands.ts';
+import { defineInterceptor } from '../core/interceptors.ts';
+import type { AnyPadroneBuilder, CommandTypesBase, PadroneCommand } from '../types/index.ts';
+import type { PadroneSchema } from '../types/schema.ts';
+import type { WithCommand } from '../util/type-utils.ts';
+import { getRootCommand, getVersion } from '../util/utils.ts';
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type VersionCommand = PadroneCommand<'version', '', PadroneSchema<void>, string, [], [], false>;
+
+export type WithVersion<T> = WithCommand<T, 'version', VersionCommand>;
+
+// ── Interceptor ─────────────────────────────────────────────────────────
+
+const versionInterceptor = defineInterceptor({ id: 'padrone:version', name: 'padrone:version', order: -1000 }, () => ({
+  parse(_ctx, next) {
+    return thenMaybe(next(), (res) => {
+      const hasVersionFlag = res.rawArgs.version || res.rawArgs.v || res.rawArgs.V;
+
+      // Only show version for root command (no subcommand matched)
+      if (hasVersionFlag && !res.command.parent) {
+        delete res.rawArgs.version;
+        delete res.rawArgs.v;
+        delete res.rawArgs.V;
+
+        // Route to the version command so its action handles the rest
+        const versionCmd = res.command.commands?.find((c) => c.name === 'version');
+        if (versionCmd) {
+          resolveCommand(versionCmd);
+          return { ...res, command: versionCmd, rawArgs: {}, positionalArgs: [] };
+        }
+      }
+
+      return res;
+    });
+  },
+}));
+
+// ── Extension ────────────────────────────────────────────────────────────
+
+/**
+ * Extension that adds version support:
+ * - `version` command
+ * - `--version` / `-v` / `-V` flags (root command only)
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneVersion())
+ * ```
+ */
+export function padroneVersion(): <T extends CommandTypesBase>(builder: T) => WithVersion<T> {
+  return ((builder: AnyPadroneBuilder) =>
+    builder
+      .command('version', (c) =>
+        c.configure({ description: 'Display the version number', hidden: true }).action((_args, ctx) => {
+          const rootCommand = getRootCommand(ctx.command);
+          return getVersion(rootCommand.version);
+        }),
+      )
+      .intercept(versionInterceptor)) as any;
+}

package/src/{completion.ts → feature/completion.ts}

@@ -1,8 +1,8 @@
-import { extractSchemaMetadata, JSON_SCHEMA_OPTS } from './args.ts';
-import { detectShell, getRcFile, type ShellType, writeToRcFile } from './shell-utils.ts';
-import type { AnyPadroneCommand } from './types.ts';
+import { extractSchemaMetadata, getJsonSchema } from '../core/args.ts';
+import type { AnyPadroneCommand } from '../types/index.ts';
+import { detectShell, getRcFile, type ShellType, writeToRcFile } from '../util/shell-utils.ts';
 
-export { detectShell, escapeRegExp, getRcFile, type ShellType, writeToRcFile } from './shell-utils.ts';
+export { detectShell, escapeRegExp, getRcFile, type ShellType, writeToRcFile } from '../util/shell-utils.ts';
 
 /**
  * Collects all commands from a program recursively.
@@ -48,7 +48,7 @@ function extractArguments(cmd: AnyPadroneCommand): ExtractedArg[] {
       if (!argToAlias[argName]) argToAlias[argName] = aliasName;
     }
 
-    const jsonSchema = cmd.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+    const jsonSchema = getJsonSchema(cmd.argsSchema) as Record<string, any>;
 
     if (jsonSchema.type === 'object' && jsonSchema.properties) {
       for (const [key, prop] of Object.entries(jsonSchema.properties as Record<string, any>)) {
@@ -439,7 +439,7 @@ ${programName} completion powershell >> $PROFILE`;
  * Generates the completion output with automatic shell detection.
  * If shell is not specified, detects the current shell and provides instructions.
  */
-export function generateCompletionOutput(program: AnyPadroneCommand, shell?: ShellType): string {
+export async function generateCompletionOutput(program: AnyPadroneCommand, shell?: ShellType): Promise<string> {
   const programName = program.name;
 
   if (shell) {
@@ -447,7 +447,7 @@ export function generateCompletionOutput(program: AnyPadroneCommand, shell?: She
   }
 
   // Auto-detect shell and provide instructions
-  const detectedShell = detectShell();
+  const detectedShell = await detectShell();
 
   if (detectedShell) {
     const instructions = getCompletionInstallInstructions(programName, detectedShell);
@@ -492,10 +492,10 @@ export interface SetupCompletionsResult {
  * Sets up shell completions by writing an eval snippet to the appropriate shell config file.
  * Uses marker comments for idempotency — re-running replaces the existing block.
  */
-export function setupCompletions(programName: string, shell: ShellType): SetupCompletionsResult {
-  const { existsSync, mkdirSync, writeFileSync } = require('node:fs') as typeof import('node:fs');
-  const { join } = require('node:path') as typeof import('node:path');
-  const { homedir } = require('node:os') as typeof import('node:os');
+export async function setupCompletions(programName: string, shell: ShellType): Promise<SetupCompletionsResult> {
+  const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
+  const { join } = await import('node:path');
+  const { homedir } = await import('node:os');
 
   const beginMarker = `###-begin-${programName}-completion-###`;
   const endMarker = `###-end-${programName}-completion-###`;
@@ -510,7 +510,7 @@ export function setupCompletions(programName: string, shell: ShellType): SetupCo
     return { file: filePath, updated: existed };
   }
 
-  const rcFile = getRcFile(shell);
+  const rcFile = await getRcFile(shell);
   if (!rcFile) {
     throw new Error(`Could not determine config file for ${shell}.`);
   }

package/src/{interactive.ts → feature/interactive.ts}

@@ -1,6 +1,6 @@
-import { JSON_SCHEMA_OPTS } from './args.ts';
-import type { InteractivePromptConfig, ResolvedPadroneRuntime } from './runtime.ts';
-import type { AnyPadroneCommand } from './types.ts';
+import { getJsonSchema } from '../core/args.ts';
+import type { InteractivePromptConfig, ResolvedPadroneRuntime } from '../core/runtime.ts';
+import type { AnyPadroneCommand } from '../types/index.ts';
 
 /**
  * Auto-detect the prompt type for a field based on its JSON schema property definition.
@@ -110,7 +110,7 @@ export async function promptInteractiveFields(
   let requiredFields: Set<string> = new Set();
   if (command.argsSchema) {
     try {
-      const jsonSchema = command.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
+      const jsonSchema = getJsonSchema(command.argsSchema) as Record<string, any>;
       if (jsonSchema.type === 'object' && jsonSchema.properties) {
         jsonProperties = jsonSchema.properties;
       }

package/src/{mcp.ts → feature/mcp.ts}

@@ -1,6 +1,7 @@
-import { buildInputSchema, collectEndpoints, serializeArgsToFlags } from './command-utils.ts';
-import { generateHelp } from './help.ts';
-import type { AnyPadroneCommand, AnyPadroneProgram } from './types.ts';
+import { buildInputSchema, collectEndpoints, serializeArgsToFlags } from '../core/commands.ts';
+import { generateHelp } from '../output/help.ts';
+import type { AnyPadroneCommand, AnyPadroneProgram } from '../types/index.ts';
+import { readStreamAsText } from '../util/stream.ts';
 
 export type PadroneMcpPreferences = {
   /** Server name. Defaults to the program name. */
@@ -158,7 +159,7 @@ export function createMcpHandler(
           const output: string[] = [];
           const errors: string[] = [];
           const result = await evalCommand(input as any, {
-            autoOutput: false,
+            caller: 'mcp',
             runtime: {
               output: (...outArgs: unknown[]) => output.push(outArgs.map(String).join(' ')),
               error: (text: string) => errors.push(text),
@@ -237,6 +238,7 @@ async function startHttpTransport(
   handleRequest: (req: JsonRpcRequest) => Promise<JsonRpcResponse | undefined>,
   prefs: PadroneMcpPreferences,
   log: (msg: string) => void,
+  onSignal?: (callback: () => void) => () => void,
 ): Promise<void> {
   const http = await import('node:http');
   const crypto = await import('node:crypto');
@@ -317,11 +319,7 @@ async function startHttpTransport(
     }
 
     // Read request body
-    const chunks: Buffer[] = [];
-    for await (const chunk of req) {
-      chunks.push(chunk);
-    }
-    const body = Buffer.concat(chunks).toString('utf-8');
+    const body = await readStreamAsText(req as AsyncIterable<Uint8Array>);
 
     let rpcRequest: JsonRpcRequest;
     try {
@@ -363,11 +361,10 @@ async function startHttpTransport(
       log(`MCP server listening on http://${host}:${port}${endpoint}`);
     });
     server.on('error', reject);
-    const onSignal = () => {
+    const unsubscribe = onSignal?.(() => {
       server.close(() => resolve());
-    };
-    process.on('SIGINT', onSignal);
-    process.on('SIGTERM', onSignal);
+    });
+    server.on('close', () => unsubscribe?.());
   });
 }
 
@@ -384,7 +381,7 @@ export async function startMcpServer(
     return startStdioTransport(handleRequest);
   }
 
-  const { getCommandRuntime } = await import('./command-utils.ts');
+  const { getCommandRuntime } = await import('../core/commands.ts');
   const runtime = getCommandRuntime(existingCommand);
-  return startHttpTransport(handleRequest, prefs ?? {}, (msg) => runtime.error(msg));
+  return startHttpTransport(handleRequest, prefs ?? {}, (msg) => runtime.error(msg), runtime.onSignal);
 }

package/src/{repl-loop.ts → feature/repl-loop.ts}

@@ -1,8 +1,9 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { buildReplCompleter, findCommandByName, getCommandRuntime } from './command-utils.ts';
-import { createTerminalReplSession, REPL_SIGINT, type ReplSessionConfig } from './runtime.ts';
-import type { AnyPadroneCommand, PadroneEvalPreferences, PadroneReplPreferences } from './types.ts';
-import { getVersion } from './utils.ts';
+import { buildReplCompleter, findCommandByName, getCommandRuntime } from '../core/commands.ts';
+import { createTerminalReplSession } from '../core/default-runtime.ts';
+import { REPL_SIGINT, type ReplSessionConfig } from '../core/runtime.ts';
+import type { AnyPadroneCommand, PadroneEvalPreferences, PadroneReplPreferences } from '../types/index.ts';
+import { getVersion } from '../util/utils.ts';
 
 export type ReplDeps = {
   existingCommand: AnyPadroneCommand;
@@ -25,9 +26,8 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
   const runtime = getCommandRuntime(existingCommand);
 
   const programName = existingCommand.name || 'padrone';
-  const useAnsi =
-    runtime.format === 'ansi' ||
-    (runtime.format === 'auto' && typeof process !== 'undefined' && !process.env.NO_COLOR && !process.env.CI && process.stdout?.isTTY);
+  const env = runtime.env();
+  const useAnsi = runtime.format === 'ansi' || (runtime.format === 'auto' && !env.NO_COLOR && !env.CI && runtime.terminal?.isTTY === true);
 
   // Track command history for .history built-in
   const commandHistory: string[] = [];
@@ -60,7 +60,7 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
         runtime.output(options.greeting);
       } else {
         const displayName = existingCommand.title || programName;
-        const version = existingCommand.version ? getVersion(existingCommand.version) : undefined;
+        const version = existingCommand.version ? await getVersion(existingCommand.version) : undefined;
         const greeting = version ? `Welcome to ${displayName} v${version}` : `Welcome to ${displayName}`;
         runtime.output(greeting);
       }
@@ -264,10 +264,7 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
 
         const emitSpacingLine = (value: boolean | string) => {
           if (typeof value === 'string') {
-            const sep =
-              value.length === 1
-                ? value.repeat(typeof process !== 'undefined' && process.stdout?.columns ? process.stdout.columns : 80)
-                : value;
+            const sep = value.length === 1 ? value.repeat(runtime.terminal?.columns ?? 80) : value;
             runtime.output(sep);
           } else if (value) {
             runtime.output('');
@@ -289,7 +286,7 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
         const scopedInput = scopePath ? (evalInput ? `${scopePath} ${evalInput}` : scopePath) : evalInput;
 
         try {
-          const replEvalPrefs: PadroneEvalPreferences | undefined = options?.autoOutput === false ? { autoOutput: false } : undefined;
+          const replEvalPrefs: PadroneEvalPreferences | undefined = { caller: 'repl' };
           const result = await evalCommand(scopedInput, replEvalPrefs);
           if (result.error) {
             const msg = result.error instanceof Error ? result.error.message : String(result.error);

package/src/{serve.ts → feature/serve.ts}

@@ -1,7 +1,8 @@
-import { buildInputSchema, type CollectedEndpoint, collectEndpoints, serializeArgsToFlags } from './command-utils.ts';
-import { RoutingError, ValidationError } from './errors.ts';
-import { generateHelp } from './help.ts';
-import type { AnyPadroneCommand, AnyPadroneProgram } from './types.ts';
+import { buildInputSchema, type CollectedEndpoint, collectEndpoints, serializeArgsToFlags } from '../core/commands.ts';
+import { RoutingError, ValidationError } from '../core/errors.ts';
+import { generateHelp } from '../output/help.ts';
+import type { AnyPadroneCommand, AnyPadroneProgram } from '../types/index.ts';
+import { readStreamAsText } from '../util/stream.ts';
 
 export type PadroneServePreferences = {
   /** Port to listen on. Default: 3000 */
@@ -229,7 +230,7 @@ export function createServeHandler(
     const output: string[] = [];
     const errors: string[] = [];
     const result = await evalCommand(commandString || (undefined as any), {
-      autoOutput: false,
+      caller: 'serve',
       runtime: {
         output: (...args: unknown[]) => output.push(args.map(String).join(' ')),
         error: (text: string) => errors.push(text),
@@ -414,7 +415,7 @@ export async function startServeServer(
     res.end(body);
   });
 
-  const { getCommandRuntime } = await import('./command-utils.ts');
+  const { getCommandRuntime } = await import('../core/commands.ts');
   const runtime = getCommandRuntime(existingCommand);
 
   return new Promise<void>((resolve, reject) => {
@@ -424,19 +425,14 @@ export async function startServeServer(
       if (builtins.docs) runtime.error(`API docs: http://${host}:${port}${basePath}_docs`);
     });
     server.on('error', reject);
-    const onSignal = () => {
+    const unsubscribe = runtime.onSignal?.(() => {
       server.close(() => resolve());
-    };
-    process.on('SIGINT', onSignal);
-    process.on('SIGTERM', onSignal);
+    });
+    server.on('close', () => unsubscribe?.());
   });
 }
 
 /** Read the full body from a Node.js IncomingMessage. */
 async function readBody(req: import('node:http').IncomingMessage): Promise<string> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of req) {
-    chunks.push(chunk as Buffer);
-  }
-  return Buffer.concat(chunks).toString('utf-8');
+  return readStreamAsText(req as AsyncIterable<Uint8Array>);
 }