apcore-cli 0.2.1 → 0.3.1

package/dist/{src/index.d.ts → index.d.ts}

@@ -30,31 +30,86 @@ interface ModuleDescriptor {
     annotations?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
 }
+/** Built-in command names that cannot be overridden by modules. */
+declare const BUILTIN_COMMANDS: string[];
 /**
  * Dynamically loads apcore modules as Commander subcommands from Registry.
- *
- * TODO: Implement lazy loading — commands should only be fully built when
- * actually invoked, not at registration time.
  */
 declare class LazyModuleGroup {
-    private readonly registry;
+    protected readonly registry: Registry;
     readonly executor: Executor;
-    private readonly helpTextMaxLength;
-    private commandCache;
+    protected readonly helpTextMaxLength: number;
+    protected commandCache: Map<string, Command>;
+    /** alias -> canonical module_id (populated lazily) */
+    protected aliasMap: Map<string, string>;
+    /** module_id -> descriptor cache (populated during alias map build) */
+    protected descriptorCache: Map<string, ModuleDescriptor>;
+    protected aliasMapBuilt: boolean;
     constructor(registry: Registry, executor: Executor, helpTextMaxLength?: number);
+    /**
+     * Build alias->module_id map from display overlay metadata.
+     */
+    buildAliasMap(): void;
     /**
      * List all available command names from the Registry.
-     *
-     * TODO: Implement registry enumeration.
      */
     listCommands(): string[];
     /**
      * Get or lazily build a Commander Command for the given module.
-     *
-     * TODO: Implement lazy command construction with schema-based options.
      */
     getCommand(cmdName: string): Command | null;
 }
+/**
+ * Command group for a single namespace — lazily builds subcommands.
+ */
+declare class LazyGroup {
+    private readonly members;
+    private readonly _executor;
+    private readonly _helpTextMaxLength;
+    private readonly _cmdCache;
+    readonly command: Command;
+    constructor(members: Map<string, [string, ModuleDescriptor]>, executor: Executor, name: string, helpTextMaxLength?: number);
+    listCommands(): string[];
+    getCommand(cmdName: string): Command | null;
+}
+/**
+ * Extended LazyModuleGroup that organises modules into named groups.
+ *
+ * Modules with dotted IDs (e.g., "math.add") are automatically grouped
+ * by their namespace prefix. The display overlay can override grouping
+ * via metadata.display.cli.group.
+ */
+declare class GroupedModuleGroup extends LazyModuleGroup {
+    /** groupName -> { cmdName -> [moduleId, descriptor] } */
+    private groupMap;
+    /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
+    private topLevelModules;
+    /** Cached LazyGroup instances */
+    private groupCache;
+    private groupMapBuilt;
+    /**
+     * Determine (groupName | null, commandName) for a module from its display overlay.
+     */
+    static resolveGroup(moduleId: string, descriptor: ModuleDescriptor): [string | null, string];
+    /**
+     * Build the group map from registry modules.
+     */
+    buildGroupMap(): void;
+    /**
+     * List all available command names: builtins + group names + top-level module names.
+     */
+    listCommands(): string[];
+    /**
+     * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
+     */
+    getCommand(cmdName: string): Command | null;
+    /** Expose groupMap for testing. */
+    getGroupMap(): Map<string, Map<string, [string, ModuleDescriptor]>>;
+    /** Expose topLevelModules for testing. */
+    getTopLevelModules(): Map<string, [string, ModuleDescriptor]>;
+    /** Expose groupMapBuilt for testing. */
+    isGroupMapBuilt(): boolean;
+}
 
 /**
  * CLI entry point — createCli / main equivalents.
@@ -90,6 +145,13 @@ interface OptionConfig {
  * @param progName       Program name shown in help (default: apcore-cli)
  */
 declare function createCli(extensionsDir?: string, progName?: string): Command;
+/**
+ * Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).
+ *
+ * Uses dynamic import so the dependency remains optional — if apcore-toolkit
+ * is not installed, a warning is printed and the CLI continues without it.
+ */
+declare function applyToolkitIntegration(commandsDir?: string, bindingPath?: string): Promise<void>;
 /**
  * Parse argv and run the CLI. Handles top-level error catching and exit codes.
  */
@@ -97,7 +159,7 @@ declare function main(progName?: string): void;
 /**
  * Build a Commander Command for a single apcore module.
  */
-declare function buildModuleCommand(moduleDef: ModuleDescriptor, executor: Executor, helpTextMaxLength?: number): Command;
+declare function buildModuleCommand(moduleDef: ModuleDescriptor, executor: Executor, helpTextMaxLength?: number, cmdName?: string): Command;
 /**
  * Validate that a module ID conforms to the expected format.
  * Pattern: [a-z][a-z0-9_]*(.[a-z][a-z0-9_])* — max 128 chars.
@@ -113,6 +175,30 @@ declare function collectInput(stdinFlag?: string, cliKwargs?: Record<string, unk
  */
 declare function reconvertEnumValues(kwargs: Record<string, unknown>, options: OptionConfig[]): Record<string, unknown>;
 
+/**
+ * Display overlay helpers — shared resolution logic for CLI surfaces.
+ */
+
+/**
+ * Extract resolved display overlay from a ModuleDescriptor's metadata.
+ */
+declare function getDisplay(descriptor: ModuleDescriptor): Record<string, unknown>;
+/**
+ * Return [displayName, description, tags] resolved from the display overlay.
+ *
+ * Falls back to scanner-provided values when no overlay is present.
+ */
+declare function getCliDisplayFields(descriptor: ModuleDescriptor): [string, string, string[]];
+
+/**
+ * Init command — scaffold new apcore modules (Phase 1).
+ */
+
+/**
+ * Register the init command group on the CLI program.
+ */
+declare function registerInitCommand(cli: Command): void;
+
 /**
  * ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).
  *
@@ -419,4 +505,4 @@ declare class Sandbox {
     private sandboxedExecute;
 }
 
-export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, buildModuleCommand, checkApproval, collectInput, createCli, debug, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getLogLevel, info, main, mapType, reconvertEnumValues, registerDiscoveryCommands, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setLogLevel, truncate, validateModuleId, warn };
+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, checkApproval, collectInput, createCli, debug, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerDiscoveryCommands, registerInitCommand, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setLogLevel, truncate, validateModuleId, warn };