import type { Command } from 'commander';
export interface CLIContext {
    configPath: string;
    workspacePath: string;
    isVerbose: boolean;
    argv: string[];
}
export declare function createDefaultContext(argv?: string[], opts?: {
    config?: string;
    workspace?: string;
    verbose?: boolean;
}): CLIContext;
export interface CommandMetadata {
    category?: 'setup' | 'runtime' | 'maintenance' | 'utility';
    hidden?: boolean;
    unstable?: boolean;
    examples?: string[];
}
export interface CommandDefinition {
    id: string;
    name: string;
    description: string;
    factory: (ctx: CLIContext, getCtx?: () => CLIContext) => Command;
    metadata?: CommandMetadata;
}
export declare class CommandRegistry {
    private commands;
    private initialized;
    private suppressLateRegistrationWarnings;
    /**
     * Temporarily silence the "registered after initialization" warning. Used by
     * commands that need to bulk-load other command modules to harvest their
     * side effects during initialization.
     */
    setSuppressLateRegistrationWarnings(value: boolean): void;
    register(def: CommandDefinition): void;
    registerAll(defs: CommandDefinition[]): void;
    getCommands(): ReadonlyArray<CommandDefinition>;
    getCommandsByCategory(category: CommandMetadata['category']): ReadonlyArray<CommandDefinition>;
    findById(id: string): CommandDefinition | undefined;
    findByName(name: string): CommandDefinition | undefined;
    install(program: Command, ctx: CLIContext, getCtx?: () => CLIContext): void;
    installOne(program: Command, name: string, ctx: CLIContext, getCtx?: () => CLIContext): boolean;
    getStats(): {
        total: number;
        byCategory: Record<string, number>;
    };
}
export declare const registry: CommandRegistry;
export declare function register(def: CommandDefinition): void;
export declare function formatExamples(examples: string[]): string;