@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/commands-v2/handlers/settings.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Settings Commands for REPL V2
+ *
+ * Commands for configuration: theme, config, verbose, model, tools, agents
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const themeCommand: CommandHandlerV2;
+export declare const configCommand: CommandHandlerV2;
+export declare const verboseCommand: CommandHandlerV2;
+export declare const modelCommand: CommandHandlerV2;
+export declare const toolsCommand: CommandHandlerV2;
+export declare const keysCommand: CommandHandlerV2;
+export declare const mascotCommand: CommandHandlerV2;
+export declare const agentsCommand: CommandHandlerV2;
+export declare const settingsCommands: CommandHandlerV2[];

package/dist/commands-v2/handlers/settings.js

@@ -0,0 +1,235 @@
+/**
+ * Settings Commands for REPL V2
+ *
+ * Commands for configuration: theme, config, verbose, model, tools, agents
+ */
+import { ThemeOverlayV2, ModelOverlayV2, ToolsOverlayV2, KeysOverlayV2, MascotOverlayV2, AgentsOverlayV2, ConfigOverlayV2 } from '../../ui/overlay/index.js';
+import { getSetting, getSettings } from '../../settings/index.js';
+import { getToolPermissionInfo } from '../../agent.js';
+// =============================================================================
+// Theme Command
+// =============================================================================
+export const themeCommand = {
+    name: 'theme',
+    description: 'Change color theme',
+    async execute(_args, ctx) {
+        const themeOverlay = new ThemeOverlayV2();
+        await ctx.ui.showOverlay(themeOverlay);
+        return true;
+    },
+};
+// =============================================================================
+// Config Command
+// =============================================================================
+export const configCommand = {
+    name: 'config',
+    description: 'Open settings panel',
+    async execute(_args, ctx) {
+        // Gather current session info
+        const currentModel = getSetting('defaultModel') || 'unknown';
+        const currentProvider = getSetting('defaultProvider');
+        const configOverlay = new ConfigOverlayV2({
+            version: ctx.version,
+            model: currentModel,
+            provider: currentProvider === 'auto' ? 'claude' : currentProvider,
+            cwd: process.cwd(),
+            toolCount: 13, // TODO: Get actual tool count from context
+            startTime: ctx.startTime ?? new Date(),
+            inputTokens: ctx.sessionInputTokens ?? 0,
+            outputTokens: ctx.sessionOutputTokens ?? 0,
+            requests: ctx.sessionRequests ?? 0,
+            contextUsed: 0, // TODO: Get from context manager
+            contextMax: 200000,
+            messageCount: ctx.getHistory?.().length ?? 0,
+        });
+        const result = await ctx.ui.showOverlay(configOverlay);
+        if (result?.settingsChanged) {
+            ctx.ui.print({ type: 'info', message: 'Settings updated' });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Verbose Command
+// =============================================================================
+export const verboseCommand = {
+    name: 'verbose',
+    description: 'Toggle verbose mode',
+    execute(_args, ctx) {
+        const config = ctx.ui.getConfig();
+        const newVerbose = !config.verbose;
+        ctx.ui.setConfig({ verbose: newVerbose });
+        ctx.ui.print({
+            type: 'info',
+            message: `Verbose mode: ${newVerbose ? 'ON' : 'OFF'}`,
+        });
+        return Promise.resolve(true);
+    },
+};
+// =============================================================================
+// Model Command
+// =============================================================================
+export const modelCommand = {
+    name: 'model',
+    description: 'Change AI model',
+    async execute(_args, ctx) {
+        const currentModel = getSetting('defaultModel') ?? undefined;
+        const currentProvider = getSetting('defaultProvider');
+        const modelOverlay = new ModelOverlayV2({
+            currentModel: currentModel ?? undefined,
+            currentProvider: currentProvider === 'auto' ? undefined : currentProvider,
+        });
+        const result = await ctx.ui.showOverlay(modelOverlay);
+        if (result?.modelChanged) {
+            if (result.requiresRestart) {
+                ctx.ui.print({
+                    type: 'warning',
+                    message: `Switched to ${result.provider ?? 'unknown'} provider. Restart required.`,
+                });
+            }
+            else {
+                ctx.ui.print({
+                    type: 'success',
+                    message: `Model changed to ${result.modelChanged}`,
+                });
+            }
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Tools Command
+// =============================================================================
+export const toolsCommand = {
+    name: 'tools',
+    description: 'Show available tools',
+    async execute(_args, ctx) {
+        // Get tools from agent if available, otherwise use fallback list
+        const tools = ctx.agent ? getAgentTools(ctx) : getDefaultTools();
+        const toolsOverlay = new ToolsOverlayV2({ tools });
+        await ctx.ui.showOverlay(toolsOverlay);
+        return true;
+    },
+};
+/**
+ * Get tool definitions from the agent with full parameter and permission info.
+ */
+function getAgentTools(ctx) {
+    if (!ctx.agent)
+        return getDefaultTools();
+    return ctx.agent.getToolDefinitions().map((t) => {
+        // Extract parameters from inputSchema
+        const parameters = [];
+        const props = t.inputSchema.properties;
+        const required = t.inputSchema.required ?? [];
+        for (const [name, schema] of Object.entries(props)) {
+            parameters.push({
+                name,
+                type: schema.type ?? 'unknown',
+                description: schema.description,
+                required: required.includes(name),
+            });
+        }
+        // Look up permission info
+        const permissionInfo = getToolPermissionInfo(t.name);
+        const permission = permissionInfo
+            ? { level: permissionInfo.level, description: permissionInfo.description }
+            : undefined;
+        // For task tool, extract just the intro (before verbose agent types list)
+        let description = t.description;
+        if (t.name === 'task' && description.includes('Available agent types:')) {
+            description = description.split('Available agent types:')[0].trim();
+        }
+        return {
+            name: t.name,
+            description,
+            parameters,
+            permission,
+        };
+    });
+}
+/**
+ * Fallback tool definitions when agent is not available.
+ */
+function getDefaultTools() {
+    return [
+        { name: 'read_file', description: 'Read contents of a file' },
+        { name: 'write_file', description: 'Write contents to a file' },
+        { name: 'edit', description: 'Edit a file with find/replace' },
+        { name: 'glob', description: 'Find files matching a pattern' },
+        { name: 'grep', description: 'Search for text in files' },
+        { name: 'bash', description: 'Execute a bash command' },
+        { name: 'task', description: 'Spawn a sub-agent for complex tasks' },
+        { name: 'todoWrite', description: 'Write items to the todo list' },
+        { name: 'todoRead', description: 'Read the current todo list' },
+        { name: 'suggest', description: 'Suggest text for the input prompt' },
+        { name: 'webFetch', description: 'Fetch content from a URL' },
+        { name: 'askUser', description: 'Ask the user a question' },
+        { name: 'askUserSimple', description: 'Ask the user a simple question' },
+    ];
+}
+// =============================================================================
+// Keys Command
+// =============================================================================
+export const keysCommand = {
+    name: 'keys',
+    description: 'Manage API keys',
+    async execute(_args, ctx) {
+        const keysOverlay = new KeysOverlayV2();
+        const result = await ctx.ui.showOverlay(keysOverlay);
+        if (result?.changed) {
+            ctx.ui.print({ type: 'success', message: 'API keys updated' });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Mascot Command
+// =============================================================================
+export const mascotCommand = {
+    name: 'mascot',
+    description: 'Select mascot expression',
+    async execute(_args, ctx) {
+        const currentMascot = getSettings().mascot;
+        const mascotOverlay = new MascotOverlayV2({ currentMascot });
+        const result = await ctx.ui.showOverlay(mascotOverlay);
+        if (result?.mascotChanged) {
+            ctx.ui.print({ type: 'success', message: `Mascot changed to: ${result.mascotChanged}` });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Agents Command
+// =============================================================================
+export const agentsCommand = {
+    name: 'agents',
+    description: 'View and manage agents',
+    async execute(_args, ctx) {
+        const agentsOverlay = new AgentsOverlayV2();
+        const result = await ctx.ui.showOverlay(agentsOverlay);
+        if (result?.created) {
+            ctx.ui.print({ type: 'success', message: `Agent created: ${result.created}` });
+        }
+        else if (result?.edited) {
+            ctx.ui.print({ type: 'success', message: `Agent updated: ${result.edited}` });
+        }
+        else if (result?.deleted) {
+            ctx.ui.print({ type: 'info', message: `Agent deleted: ${result.deleted}` });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Export All Settings Commands
+// =============================================================================
+export const settingsCommands = [
+    themeCommand,
+    configCommand,
+    verboseCommand,
+    modelCommand,
+    toolsCommand,
+    keysCommand,
+    mascotCommand,
+    agentsCommand,
+];

package/dist/commands-v2/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Commands V2 Module
+ *
+ * Command system for the new TerminalUI-based REPL.
+ */
+export type { CommandContextV2, CommandHandlerV2, CommandResultV2 } from './types.js';
+export { registerCommand, registerCommands, getCommand, executeCommand, getCommandNames, hasCommand, clearCommands, } from './registry.js';
+export { allCommands } from './handlers/index.js';
+export { coreCommands } from './handlers/core.js';
+export { settingsCommands } from './handlers/settings.js';
+export { contextCommands } from './handlers/context.js';
+export { projectCommands } from './handlers/project.js';
+export { debugCommands } from './handlers/debug.js';

package/dist/commands-v2/index.js

@@ -0,0 +1,15 @@
+/**
+ * Commands V2 Module
+ *
+ * Command system for the new TerminalUI-based REPL.
+ */
+// Registry
+export { registerCommand, registerCommands, getCommand, executeCommand, getCommandNames, hasCommand, clearCommands, } from './registry.js';
+// All handlers
+export { allCommands } from './handlers/index.js';
+// Individual handler modules (for selective imports)
+export { coreCommands } from './handlers/core.js';
+export { settingsCommands } from './handlers/settings.js';
+export { contextCommands } from './handlers/context.js';
+export { projectCommands } from './handlers/project.js';
+export { debugCommands } from './handlers/debug.js';

package/dist/commands-v2/registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Command Registry for REPL V2
+ *
+ * Central registry for all V2 command handlers.
+ * Handles command resolution (including aliases) and execution.
+ */
+import type { CommandHandlerV2, CommandContextV2, CommandResultV2 } from './types.js';
+/**
+ * Register a command handler.
+ */
+export declare function registerCommand(handler: CommandHandlerV2): void;
+/**
+ * Register multiple command handlers.
+ */
+export declare function registerCommands(handlerList: CommandHandlerV2[]): void;
+/**
+ * Get a command handler by name or alias.
+ */
+export declare function getCommand(nameOrAlias: string): CommandHandlerV2 | undefined;
+/**
+ * Execute a command by name or alias.
+ *
+ * @returns true to continue, false to exit, null if command not found
+ */
+export declare function executeCommand(nameOrAlias: string, args: string, ctx: CommandContextV2): Promise<CommandResultV2>;
+/**
+ * Get all registered command names (excluding aliases).
+ */
+export declare function getCommandNames(): string[];
+/**
+ * Check if a command exists (by name or alias).
+ */
+export declare function hasCommand(nameOrAlias: string): boolean;
+/**
+ * Clear all registered commands (for testing).
+ */
+export declare function clearCommands(): void;

package/dist/commands-v2/registry.js

@@ -0,0 +1,80 @@
+/**
+ * Command Registry for REPL V2
+ *
+ * Central registry for all V2 command handlers.
+ * Handles command resolution (including aliases) and execution.
+ */
+// =============================================================================
+// Registry State
+// =============================================================================
+const handlers = new Map();
+const aliasMap = new Map();
+// =============================================================================
+// Registry Functions
+// =============================================================================
+/**
+ * Register a command handler.
+ */
+export function registerCommand(handler) {
+    handlers.set(handler.name, handler);
+    // Register aliases
+    if (handler.aliases) {
+        for (const alias of handler.aliases) {
+            aliasMap.set(alias, handler.name);
+        }
+    }
+}
+/**
+ * Register multiple command handlers.
+ */
+export function registerCommands(handlerList) {
+    for (const handler of handlerList) {
+        registerCommand(handler);
+    }
+}
+/**
+ * Get a command handler by name or alias.
+ */
+export function getCommand(nameOrAlias) {
+    // Try direct lookup first
+    const handler = handlers.get(nameOrAlias);
+    if (handler)
+        return handler;
+    // Try alias lookup
+    const resolvedName = aliasMap.get(nameOrAlias);
+    if (resolvedName) {
+        return handlers.get(resolvedName);
+    }
+    return undefined;
+}
+/**
+ * Execute a command by name or alias.
+ *
+ * @returns true to continue, false to exit, null if command not found
+ */
+export async function executeCommand(nameOrAlias, args, ctx) {
+    const handler = getCommand(nameOrAlias);
+    if (!handler) {
+        return null; // Command not found
+    }
+    return handler.execute(args, ctx);
+}
+/**
+ * Get all registered command names (excluding aliases).
+ */
+export function getCommandNames() {
+    return Array.from(handlers.keys());
+}
+/**
+ * Check if a command exists (by name or alias).
+ */
+export function hasCommand(nameOrAlias) {
+    return handlers.has(nameOrAlias) || aliasMap.has(nameOrAlias);
+}
+/**
+ * Clear all registered commands (for testing).
+ */
+export function clearCommands() {
+    handlers.clear();
+    aliasMap.clear();
+}

package/dist/commands-v2/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Command Handler Types for REPL V2
+ *
+ * Command system for the new TerminalUI-based REPL.
+ * Uses TerminalUI instead of Footer, with real agent integration.
+ */
+import type { Agent, ContextManager } from '@compilr-dev/agents';
+import type { TerminalUI, AgentMessage } from '../ui/terminal-ui.js';
+/**
+ * Context passed to V2 command handlers.
+ * Provides access to agent, UI, and session information.
+ */
+export interface CommandContextV2 {
+    /** TerminalUI instance for output and overlays */
+    ui: TerminalUI;
+    /** CLI version string */
+    version: string;
+    /** Re-print the welcome screen (logo + hints for REPL mode) */
+    printWelcome: () => void;
+    /** Print just the logo (for dashboard mode) */
+    printLogo: () => void;
+    /** The main agent instance (may be undefined in simulation mode) */
+    agent?: Agent;
+    /** Current LLM model ID */
+    model?: string;
+    /** Current LLM provider (claude, openai, gemini, ollama) */
+    provider?: string;
+    /** Get the context manager from agent (for token/context stats) */
+    getContextManager?: () => ContextManager | null;
+    /** Get conversation history from agent */
+    getHistory?: () => Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /**
+     * Queue a message to be sent to the agent after the command returns.
+     * The displayMessage (if provided) is shown to the user, while the
+     * full message is sent to the agent.
+     */
+    queueAgentMessage: (options: AgentMessage) => void;
+    /** Session start time */
+    startTime?: Date;
+    /** Total input tokens used in session */
+    sessionInputTokens?: number;
+    /** Total output tokens used in session */
+    sessionOutputTokens?: number;
+    /** Total requests in session */
+    sessionRequests?: number;
+}
+/**
+ * Interface for a V2 command handler.
+ */
+export interface CommandHandlerV2 {
+    /** Primary command name (without leading slash) */
+    name: string;
+    /** Optional aliases that resolve to this command */
+    aliases?: string[];
+    /** Short description for help text */
+    description: string;
+    /**
+     * Execute the command.
+     *
+     * @param args - Arguments passed after the command
+     * @param ctx - Command context with dependencies
+     * @returns true to continue REPL, false to exit
+     */
+    execute(args: string, ctx: CommandContextV2): Promise<boolean>;
+}
+/**
+ * Result of executing a command.
+ * - true: Command handled successfully, continue REPL
+ * - false: Exit REPL (e.g., /exit command)
+ * - null: Command not found in registry
+ */
+export type CommandResultV2 = boolean | null;

package/dist/commands-v2/types.js

@@ -0,0 +1,7 @@
+/**
+ * Command Handler Types for REPL V2
+ *
+ * Command system for the new TerminalUI-based REPL.
+ * Uses TerminalUI instead of Footer, with real agent integration.
+ */
+export {};

package/dist/commands.js

@@ -21,6 +21,20 @@ export const COMMANDS = [
             'Esc to close',
         ],
     },
+    {
+        name: 'anchors',
+        description: 'View and manage anchors (persistent context)',
+        details: 'Anchors are critical pieces of information that survive context compaction. They are always included at the top of the context window. Manage both global anchors and project-specific anchors.',
+        examples: [{ code: '/anchors' }],
+        interactions: [
+            '↑/↓ to navigate anchors',
+            '[a] Add new anchor',
+            '[e] or Enter to edit',
+            '[d] to delete',
+            '[r] to refresh',
+            'Esc to close',
+        ],
+    },
     {
         name: 'arch',
         description: 'Create architecture documentation (ADRs, diagrams, etc.)',
@@ -103,9 +117,23 @@ export const COMMANDS = [
     {
         name: 'design',
         description: 'Design your project and populate the backlog',
-        details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /init.',
+        details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /new.',
         examples: [{ code: '/design' }],
     },
+    {
+        name: 'docs',
+        description: 'View project documents (PRD, architecture, etc.)',
+        details: 'Opens an overlay to browse and read documents stored in the database for the active project. Documents are created by /design, /arch, and other workflow commands.',
+        examples: [
+            { code: '/docs', description: 'List all documents' },
+        ],
+        interactions: [
+            '↑/↓ or j/k to navigate',
+            'Enter to view document',
+            '↑/↓ to scroll content',
+            'Esc to go back or close',
+        ],
+    },
     {
         name: 'exit',
         description: 'Exit the REPL',
@@ -152,21 +180,57 @@ export const COMMANDS = [
         ],
     },
     {
-        name: 'init',
-        description: 'Initialize a new project with structured workflow',
+        name: 'menu',
+        description: 'Return to Project Dashboard',
+        details: 'Opens the Project Dashboard where you can see current project info, switch projects, or start new work. From the dashboard you can create new projects, open existing ones, or start Quick Chat mode.',
+        examples: [{ code: '/menu' }],
+        interactions: [
+            '↑/↓ or j/k to navigate',
+            '←/→ or h/l to switch tabs (Dashboard ↔ More)',
+            'Enter to select, q/Esc to exit',
+            'n for /new, p for projects, c for chat, w for workflow',
+        ],
+    },
+    {
+        name: 'new',
+        description: 'Create a new project with structured workflow',
         details: 'Interactive wizard to scaffold a new project. Asks about project name, type, tech stack, and documentation preferences. Creates project structure with COMPILR.md, backlog, and optional separate docs repo.',
-        examples: [{ code: '/init' }],
+        examples: [{ code: '/new' }],
         interactions: [
             '8-step wizard (0-7)',
             '↑/↓ for selection steps, type for input steps',
             'Enter to confirm, Esc to go back',
         ],
     },
+    {
+        name: 'init',
+        description: 'View CLI setup status (placeholder)',
+        details: 'Shows current CLI configuration status including API keys, provider settings, and startup preferences. Directs users to /config, /keys, and other commands for configuration. Full setup wizard coming in a future release.',
+        examples: [{ code: '/init' }],
+    },
+    {
+        name: 'mascot',
+        description: 'Select mascot expression',
+        details: 'Opens the mascot selector overlay. Choose the mascot expression shown in the CLI. Options include various expressions, random (changes each startup), or none.',
+        examples: [{ code: '/mascot' }],
+        interactions: [
+            '↑/↓ or j/k to navigate options',
+            'Enter/Space to select mascot',
+            'q/Esc to close without changing',
+        ],
+    },
     {
         name: 'model',
-        description: 'Show the current model',
-        details: 'Displays the currently active LLM model (e.g., claude-3-5-sonnet, gpt-4o).',
+        description: 'Select LLM model',
+        details: 'Opens the model selector overlay. Choose from Claude, OpenAI, Gemini, or Ollama models. Changes within the same provider apply immediately; switching providers requires restart.',
         examples: [{ code: '/model' }],
+        interactions: [
+            'Tab/Shift+Tab to switch providers',
+            '1-4 for quick provider selection',
+            '↑/↓ or j/k to navigate models',
+            'Enter to select model',
+            'Esc to close',
+        ],
     },
     {
         name: 'note',
@@ -193,6 +257,21 @@ export const COMMANDS = [
             { code: '/prd scope', description: 'Update scope section' },
         ],
     },
+    {
+        name: 'projects',
+        description: 'View and manage projects',
+        details: 'Opens an interactive overlay to browse, filter, and manage projects tracked in the database. You can view details, open projects, archive, restore, or delete them.',
+        examples: [{ code: '/projects' }],
+        interactions: [
+            'Tab cycles: All → Active → Paused → Completed → Archived',
+            '↑/↓ or j/k to navigate',
+            'Enter to view details and actions',
+            'x to archive/restore project',
+            'd to delete project',
+            'a to show/hide archived',
+            'Esc to close',
+        ],
+    },
     {
         name: 'refine',
         description: 'Refine and expand existing requirements',
@@ -220,6 +299,19 @@ export const COMMANDS = [
         details: 'Displays current session status including CLI version, active model, mode, and context usage.',
         examples: [{ code: '/status' }],
     },
+    {
+        name: 'theme',
+        description: 'Select UI theme',
+        details: 'Opens the theme selector overlay. Browse themes with tabs for Curated, All, Dark, and Light. Themes are terminal color schemes that change the UI appearance.',
+        examples: [{ code: '/theme' }],
+        interactions: [
+            'Tab cycles: Curated → All → Dark → Light',
+            '↑/↓ or j/k to navigate, ←/→ for pages',
+            '/ to search themes by name',
+            '1-9,0 for quick selection (Curated tab)',
+            'Enter/Space to select, q/Esc to close',
+        ],
+    },
     {
         name: 'todos',
         description: 'List current todo items',
@@ -238,10 +330,21 @@ export const COMMANDS = [
         details: 'Shows all tools available to the agent including file operations, bash, git, and custom tools.',
         examples: [{ code: '/tools' }],
     },
+    {
+        name: 'workflow',
+        description: 'Show workflow status and next steps',
+        details: 'Displays the current project workflow status, progress through phases (init → design → backlog → scaffold → build), and recommended next actions. Helps you understand where you are in the development process.',
+        examples: [{ code: '/workflow' }],
+        interactions: [
+            '↑/↓ to navigate actions',
+            'Enter to run selected action',
+            'Esc to close',
+        ],
+    },
     {
         name: 'tutorial',
         description: 'Interactive tutorial for the workflow',
-        details: 'Opens an interactive tutorial that guides you through the compilr.dev workflow. Choose a guided tour to learn everything step-by-step, or jump directly to specific topics like /init, /design, or /build.',
+        details: 'Opens an interactive tutorial that guides you through the compilr.dev workflow. Choose a guided tour to learn everything step-by-step, or jump directly to specific topics like /new, /design, or /build.',
         examples: [{ code: '/tutorial' }],
         interactions: [
             '↑/↓ to navigate options and topics',