apcore-cli 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -17,6 +17,43 @@ interface Registry {
 /** Placeholder for apcore-js Executor. */
 interface Executor {
     execute(moduleId: string, input: Record<string, unknown>): Promise<unknown>;
+    /** Validate inputs without executing. Returns a PreflightResult. */
+    validate?(moduleId: string, input: Record<string, unknown>): Promise<PreflightResult>;
+    /** Execute with pipeline trace. Returns [result, PipelineTrace]. */
+    callWithTrace?(moduleId: string, input: Record<string, unknown>, options?: {
+        strategy?: string;
+    }): Promise<[unknown, PipelineTrace]>;
+    /** Stream execution — async iterator of chunks. */
+    stream?(moduleId: string, input: Record<string, unknown>): AsyncIterable<unknown>;
+    /** Call a module (synchronous-style, used by system commands). */
+    call?(moduleId: string, input: Record<string, unknown>): Promise<unknown>;
+}
+/** Result of a preflight validation check. */
+interface PreflightCheck {
+    check: string;
+    passed: boolean;
+    error?: unknown;
+    warnings?: string[];
+}
+/** Result of executor.validate(). */
+interface PreflightResult {
+    valid: boolean;
+    requires_approval: boolean;
+    checks: PreflightCheck[];
+}
+/** A single step in a pipeline trace. */
+interface PipelineTraceStep {
+    name: string;
+    duration_ms: number;
+    skipped: boolean;
+    skip_reason?: string;
+}
+/** Pipeline execution trace returned by callWithTrace(). */
+interface PipelineTrace {
+    strategy_name: string;
+    total_duration_ms: number;
+    success: boolean;
+    steps: PipelineTraceStep[];
 }
 /** Placeholder for apcore-js ModuleDescriptor. */
 interface ModuleDescriptor {
@@ -89,8 +126,13 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
     private groupMapBuilt;
     /**
      * Determine (groupName | null, commandName) for a module from its display overlay.
+     *
+     * @param groupDepth  Number of dotted segments to consume as the group prefix.
+     *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
+     *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
+     *                    group="math.trig", cmd="sin").
      */
-    static resolveGroup(moduleId: string, descriptor: ModuleDescriptor): [string | null, string];
+    static resolveGroup(moduleId: string, descriptor: ModuleDescriptor, groupDepth?: number): [string | null, string];
     /**
      * Build the group map from registry modules.
      */
@@ -115,6 +157,9 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
  * CLI entry point — createCli / main equivalents.
  *
  * Protocol spec: CLI bootstrapping & command registration
+ * Implements: F1 (dry-run), F3 (enhanced errors), F4 (trace),
+ * F5 (approval handler), F6 (stream), F8 (strategy), F9 (output formats),
+ * F11 (extra commands)
  */
 
 /** Whether --verbose was passed (controls help detail level). */
@@ -151,13 +196,34 @@ interface OptionConfig {
     /** Parser function for Commander (e.g. parseInt, parseFloat). */
     parseArg?: (value: string) => unknown;
 }
+/**
+ * Emit structured JSON error to stderr for AI agents.
+ */
+declare function emitErrorJson(e: unknown, exitCode: number): void;
+/**
+ * Emit human-readable error to stderr with guidance fields.
+ */
+declare function emitErrorTty(e: unknown, exitCode: number): void;
+/** Options for createCli. */
+interface CreateCliOptions {
+    extensionsDir?: string;
+    progName?: string;
+    verbose?: boolean;
+    /** Pre-populated Registry instance. Skips filesystem discovery when provided. */
+    registry?: Registry;
+    /** Pre-built Executor instance. Used alongside registry. */
+    executor?: Executor;
+    /** Extra commands to register after built-in commands (FE-11 F11). */
+    extraCommands?: Command[];
+}
 /**
  * Build and return the top-level Commander program.
  *
- * @param extensionsDir  Path to the extensions directory (default: ./extensions)
+ * @param extensionsDirOrOpts  Path to extensions directory, or a CreateCliOptions object.
  * @param progName       Program name shown in help (default: apcore-cli)
+ * @param verbose        Show verbose help output
  */
-declare function createCli(extensionsDir?: string, progName?: string, verbose?: boolean): Command;
+declare function createCli(extensionsDirOrOpts?: string | CreateCliOptions, progName?: string, verbose?: boolean): Command;
 /**
  * Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).
  *
@@ -171,6 +237,9 @@ declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: str
 declare function main(progName?: string): void;
 /**
  * Build a Commander Command for a single apcore module.
+ *
+ * Includes all 11 FE-11 options: --dry-run, --trace, --stream, --strategy,
+ * --approval-timeout, --approval-token, --fields, and enhanced --format choices.
  */
 declare function buildModuleCommand(moduleDef: ModuleDescriptor, executor: Executor, helpTextMaxLength?: number, cmdName?: string, verbose?: boolean): Command;
 /**
@@ -188,6 +257,35 @@ declare function collectInput(stdinFlag?: string, cliKwargs?: Record<string, unk
  */
 declare function reconvertEnumValues(kwargs: Record<string, unknown>, options: OptionConfig[]): Record<string, unknown>;
 
+/**
+ * Interactive approval prompts with timeout.
+ *
+ * Protocol spec: Approval workflow
+ */
+
+/**
+ * CLI ApprovalHandler that prompts in TTY, auto-denies in non-TTY.
+ *
+ * Implements the apcore ApprovalHandler protocol:
+ * - `requestApproval(request) -> ApprovalResult`
+ * - `checkApproval(approvalId) -> ApprovalResult`
+ *
+ * Pass to Executor via `executor.setApprovalHandler(handler)`.
+ */
+declare class CliApprovalHandler {
+    autoApprove: boolean;
+    timeout: number;
+    constructor(autoApprove?: boolean, timeout?: number);
+    requestApproval(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    checkApproval(_approvalId: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Check if module requires approval and handle accordingly.
+ * Returns normally if approved (or approval not required).
+ * Calls process.exit(46) if denied/timed out/non-TTY.
+ */
+declare function checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean, timeout?: number): Promise<void>;
+
 /**
  * Display overlay helpers — shared resolution logic for CLI surfaces.
  */
@@ -256,7 +354,7 @@ declare class ConfigResolver {
 }
 
 /**
- * Discovery commands — list and describe modules.
+ * Discovery commands — list, describe, validate (FE-04, FE-11).
  *
  * Protocol spec: Module discovery & introspection
  */
@@ -265,11 +363,15 @@ declare class ConfigResolver {
  * Register list and describe commands on the CLI group.
  */
 declare function registerDiscoveryCommands(cli: Command, registry: Registry): void;
+/**
+ * Register the standalone validate command.
+ */
+declare function registerValidateCommand(cli: Command, registry: Registry, executor: Executor): void;
 
 /**
- * TTY-adaptive output formatting (table/json).
+ * TTY-adaptive output formatting (table/json/csv/yaml/jsonl).
  *
- * Protocol spec: Output formatting
+ * Protocol spec: Output formatting (FE-09 enhanced)
  */
 
 /**
@@ -283,15 +385,26 @@ declare function truncate(text: string, maxLength?: number): string;
 /**
  * Format and print a list of modules.
  */
-declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[]): void;
+declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[], showDeps?: boolean): void;
 /**
  * Format and print full module metadata.
  */
 declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string): void;
 /**
  * Format and print module execution result.
+ *
+ * Supports formats: json, table, csv, yaml, jsonl.
+ * The `fields` option allows dot-path field selection on dict results.
  */
-declare function formatExecResult(result: unknown, format?: string): void;
+declare function formatExecResult(result: unknown, format?: string, fields?: string): void;
+/**
+ * Format and print a PreflightResult to stdout.
+ */
+declare function formatPreflightResult(result: PreflightResult, format?: string): void;
+/**
+ * Return the exit code for the first failed check in a PreflightResult.
+ */
+declare function firstFailedExitCode(result: PreflightResult): number;
 
 /**
  * JSON Schema $ref resolver.
@@ -327,19 +440,6 @@ declare function extractHelp(propSchema: Record<string, unknown>, maxLength?: nu
  */
 declare function schemaToCliOptions(schema: Record<string, unknown>, maxHelpLength?: number): OptionConfig[];
 
-/**
- * Interactive approval prompts with timeout.
- *
- * Protocol spec: Approval workflow
- */
-
-/**
- * Check if module requires approval and handle accordingly.
- * Returns normally if approved (or approval not required).
- * Calls process.exit(46) if denied/timed out/non-TTY.
- */
-declare function checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean): Promise<void>;
-
 /**
  * Shell completion + man page generation.
  *
@@ -365,6 +465,27 @@ declare function configureManHelp(program: Command, progName: string, version: s
  */
 declare function registerShellCommands(cli: Command, progName?: string): void;
 
+/**
+ * System management commands — health, usage, enable, disable, reload, config (FE-11 F2).
+ *
+ * Each delegates to system.* modules via executor.
+ * No-op if system modules are unavailable (graceful probe).
+ */
+
+/**
+ * Register system management commands. No-op if system modules are not available.
+ */
+declare function registerSystemCommands(cli: Command, executor: Executor): Promise<void>;
+
+/**
+ * Pipeline strategy commands — describe-pipeline (FE-11 F8).
+ */
+
+/**
+ * Register the describe-pipeline command.
+ */
+declare function registerPipelineCommand(cli: Command, executor: Executor): void;
+
 /**
  * Error classes and exit code mapping for apcore-cli.
  *
@@ -416,6 +537,7 @@ declare const EXIT_CODES: {
     readonly CONFIG_NAMESPACE_RESERVED: 78;
     readonly CONFIG_NAMESPACE_DUPLICATE: 78;
     readonly CONFIG_ENV_PREFIX_CONFLICT: 78;
+    readonly CONFIG_ENV_MAP_CONFLICT: 78;
     readonly CONFIG_MOUNT_ERROR: 66;
     readonly CONFIG_BIND_ERROR: 65;
     readonly ERROR_FORMATTER_DUPLICATE: 70;
@@ -543,4 +665,4 @@ declare class Sandbox {
     private sandboxedExecute;
 }
 
-export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, BUILTIN_COMMANDS, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerConfigNamespace, registerDiscoveryCommands, registerInitCommand, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };
+export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, BUILTIN_COMMANDS, CliApprovalHandler, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, type CreateCliOptions, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type PipelineTrace, type PipelineTraceStep, type PreflightCheck, type PreflightResult, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, emitErrorJson, emitErrorTty, error, exitCodeForError, extractHelp, firstFailedExitCode, formatExecResult, formatModuleDetail, formatModuleList, formatPreflightResult, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerConfigNamespace, registerDiscoveryCommands, registerInitCommand, registerPipelineCommand, registerShellCommands, registerSystemCommands, registerValidateCommand, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };