@compilr-dev/cli 0.5.0 → 0.5.1

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

@@ -12,4 +12,6 @@ export declare const toolsCommand: CommandHandlerV2;
 export declare const keysCommand: CommandHandlerV2;
 export declare const mascotCommand: CommandHandlerV2;
 export declare const agentsCommand: CommandHandlerV2;
+export declare const updateCommand: CommandHandlerV2;
+export declare const permissionsCommand: CommandHandlerV2;
 export declare const settingsCommands: CommandHandlerV2[];

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

@@ -3,15 +3,26 @@
  *
  * 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 { ThemeOverlayV2, ModelOverlayV2, ToolsOverlayV2, KeysOverlayV2, MascotOverlayV2, AgentsOverlayV2, ConfigOverlayV2, PermissionsOverlayV2 } from '../../ui/overlay/index.js';
+import { getSetting, getSettings, recordUpdateCheck, permissionModeToAgentMode } from '../../settings/index.js';
 import { getToolPermissionInfo } from '../../agent.js';
+import { checkForUpdates, performUpdate } from '../../utils/update-checker.js';
+import { getRegisteredMetaTools, TOOL_NAMES, getToolStats } from '../../tools.js';
 // =============================================================================
 // Theme Command
 // =============================================================================
 export const themeCommand = {
     name: 'theme',
     description: 'Change color 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',
+    ],
     async execute(_args, ctx) {
         const themeOverlay = new ThemeOverlayV2();
         await ctx.ui.showOverlay(themeOverlay);
@@ -24,23 +35,52 @@ export const themeCommand = {
 export const configCommand = {
     name: 'config',
     description: 'Open settings panel',
+    details: 'Opens the configuration overlay where you can change model, theme, permissions, and other settings.',
+    examples: [{ code: '/config' }],
+    interactions: [
+        'Tab cycles: Status → Config → Usage → Environment',
+        '↑/↓ to navigate in Config tab',
+        'Enter/Space to toggle or open submenu',
+        'Esc to exit',
+    ],
     async execute(_args, ctx) {
         // Gather current session info
         const currentModel = getSetting('defaultModel') || 'unknown';
         const currentProvider = getSetting('defaultProvider');
+        // Calculate tool counts from actual tool registry
+        const toolStats = getToolStats();
+        const metaTools = getRegisteredMetaTools();
+        // Agent gets: direct tools + 5 additional tools:
+        //   - list_tools, get_tool_info, use_tool (meta-tool access)
+        //   - task (subagent spawning)
+        //   - suggest (next action suggestions)
+        const directToolCount = toolStats.directTools + 5;
+        // metaTools.length is the actual count from the registry
+        const totalToolCount = directToolCount + metaTools.length;
+        // Calculate total message count across all team agents if team exists
+        let messageCount = ctx.getHistory?.().length ?? 0;
+        if (ctx.team) {
+            messageCount = 0;
+            for (const agent of ctx.team.getAll()) {
+                messageCount += agent.getContextStats().messageCount;
+            }
+        }
         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
+            toolCount: totalToolCount,
+            directToolCount,
+            metaToolCount: metaTools.length,
+            hasTeam: ctx.team !== undefined && ctx.team.size > 1,
             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,
+            messageCount,
         });
         const result = await ctx.ui.showOverlay(configOverlay);
         if (result?.settingsChanged) {
@@ -55,6 +95,8 @@ export const configCommand = {
 export const verboseCommand = {
     name: 'verbose',
     description: 'Toggle verbose mode',
+    details: 'Toggles verbose mode on or off. When enabled, shows additional debug information during agent execution.',
+    examples: [{ code: '/verbose' }],
     execute(_args, ctx) {
         const config = ctx.ui.getConfig();
         const newVerbose = !config.verbose;
@@ -72,6 +114,16 @@ export const verboseCommand = {
 export const modelCommand = {
     name: 'model',
     description: 'Change AI 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 view model details',
+        'In details: e Edit · t Test · a Set Active · d Reset Default',
+        'Esc to go back/close',
+    ],
     async execute(_args, ctx) {
         const currentModel = getSetting('defaultModel') ?? undefined;
         const currentProvider = getSetting('defaultProvider');
@@ -79,21 +131,9 @@ export const modelCommand = {
             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}`,
-                });
-            }
-        }
+        await ctx.ui.showOverlay(modelOverlay);
+        // Model changes are handled in the detail screen via setSetting()
+        // No need to process result here
         return true;
     },
 };
@@ -103,6 +143,13 @@ export const modelCommand = {
 export const toolsCommand = {
     name: 'tools',
     description: 'Show available tools',
+    details: 'Shows all tools available to the agent including file operations, bash, git, and custom tools. View tool parameters and permission levels.',
+    examples: [{ code: '/tools' }],
+    interactions: [
+        '↑/↓ or j/k to navigate tools',
+        'Enter to view tool details',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
         // Get tools from agent if available, otherwise use fallback list
         const tools = ctx.agent ? getAgentTools(ctx) : getDefaultTools();
@@ -113,11 +160,18 @@ export const toolsCommand = {
 };
 /**
  * Get tool definitions from the agent with full parameter and permission info.
+ * Includes both direct tools and meta-registry tools.
  */
 function getAgentTools(ctx) {
     if (!ctx.agent)
         return getDefaultTools();
-    return ctx.agent.getToolDefinitions().map((t) => {
+    // Get direct tools from agent
+    const directTools = ctx.agent.getToolDefinitions();
+    // Get meta-registry tools
+    const metaTools = getRegisteredMetaTools();
+    // Combine and map to ToolInfo format
+    const allTools = [...directTools, ...metaTools.map(t => t.definition)];
+    return allTools.map((t) => {
         // Extract parameters from inputSchema
         const parameters = [];
         const props = t.inputSchema.properties;
@@ -140,9 +194,11 @@ function getAgentTools(ctx) {
         if (t.name === 'task' && description.includes('Available agent types:')) {
             description = description.split('Available agent types:')[0].trim();
         }
+        // Mark meta-registry tools (not directly callable, use via use_tool)
+        const isMeta = metaTools.some(mt => mt.definition.name === t.name);
         return {
             name: t.name,
-            description,
+            description: isMeta ? `[via use_tool] ${description}` : description,
             parameters,
             permission,
         };
@@ -150,23 +206,32 @@ function getAgentTools(ctx) {
 }
 /**
  * Fallback tool definitions when agent is not available.
+ * Uses TOOL_NAMES constants for consistency across the codebase.
  */
 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' },
+    // Direct tools (always available)
+    const directTools = [
+        { name: TOOL_NAMES.READ_FILE, description: 'Read contents of a file' },
+        { name: TOOL_NAMES.WRITE_FILE, description: 'Write contents to a file' },
+        { name: TOOL_NAMES.EDIT, description: 'Edit a file with find/replace' },
+        { name: TOOL_NAMES.GLOB, description: 'Find files matching a pattern' },
+        { name: TOOL_NAMES.GREP, description: 'Search for text in files' },
+        { name: TOOL_NAMES.BASH, description: 'Execute a bash command' },
+        { name: TOOL_NAMES.BASH_OUTPUT, description: 'Get output from background shell' },
+        { name: TOOL_NAMES.KILL_SHELL, description: 'Kill a background shell' },
+        { name: TOOL_NAMES.TODO_WRITE, description: 'Write items to the todo list' },
+        { name: TOOL_NAMES.TODO_READ, description: 'Read the current todo list' },
+        { name: TOOL_NAMES.ASK_USER, description: 'Ask the user a question' },
+        { name: TOOL_NAMES.ASK_USER_SIMPLE, description: 'Ask the user a simple question' },
+        { name: TOOL_NAMES.DELEGATE, description: 'Delegate to a specialist agent' },
+    ];
+    // Meta-tools (for accessing specialized tools)
+    const metaToolsList = [
+        { name: TOOL_NAMES.LIST_TOOLS, description: 'List all available specialized tools' },
+        { name: TOOL_NAMES.GET_TOOL_INFO, description: 'Get detailed info about a tool' },
+        { name: TOOL_NAMES.USE_TOOL, description: 'Execute a specialized tool' },
     ];
+    return [...directTools, ...metaToolsList];
 }
 // =============================================================================
 // Keys Command
@@ -174,6 +239,14 @@ function getDefaultTools() {
 export const keysCommand = {
     name: 'keys',
     description: 'Manage API keys',
+    details: 'Opens an interactive overlay to view, set, and delete API keys for LLM providers (Anthropic, OpenAI, Google). Keys are encrypted and stored locally in ~/.compilr-dev/credentials.enc.',
+    examples: [{ code: '/keys' }],
+    interactions: [
+        '↑/↓ to navigate providers',
+        'Enter to edit key',
+        'd to delete stored key',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
         const keysOverlay = new KeysOverlayV2();
         const result = await ctx.ui.showOverlay(keysOverlay);
@@ -189,6 +262,13 @@ export const keysCommand = {
 export const mascotCommand = {
     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',
+    ],
     async execute(_args, ctx) {
         const currentMascot = getSettings().mascot;
         const mascotOverlay = new MascotOverlayV2({ currentMascot });
@@ -205,6 +285,14 @@ export const mascotCommand = {
 export const agentsCommand = {
     name: 'agents',
     description: 'View and manage agents',
+    details: 'View and configure sub-agents that can be spawned for specialized tasks like code review, testing, or exploration.',
+    examples: [{ code: '/agents' }],
+    interactions: [
+        'Tab to switch: built-in ↔ custom',
+        '↑/↓ to navigate agents',
+        'Enter to select or create new',
+        'Esc to close',
+    ],
     async execute(_args, ctx) {
         const agentsOverlay = new AgentsOverlayV2();
         const result = await ctx.ui.showOverlay(agentsOverlay);
@@ -221,6 +309,98 @@ export const agentsCommand = {
     },
 };
 // =============================================================================
+// Update Command
+// =============================================================================
+export const updateCommand = {
+    name: 'update',
+    description: 'Check for CLI updates',
+    details: 'Checks npm for new versions of the CLI. Use --install flag to automatically install updates.',
+    examples: [
+        { code: '/update', description: 'Check for updates' },
+        { code: '/update --install', description: 'Install available update' },
+    ],
+    async execute(args, ctx) {
+        ctx.ui.print({ type: 'info', message: 'Checking for updates...' });
+        const updateInfo = await checkForUpdates();
+        recordUpdateCheck();
+        if (!updateInfo.updateAvailable) {
+            ctx.ui.print({
+                type: 'success',
+                message: `You're on the latest version (v${updateInfo.currentVersion})`,
+            });
+            return true;
+        }
+        ctx.ui.print({
+            type: 'warning',
+            message: `Update available: v${updateInfo.currentVersion} → v${updateInfo.latestVersion}`,
+        });
+        // If --install flag is passed, perform the update
+        if (args.includes('--install') || args.includes('-i')) {
+            ctx.ui.print({ type: 'info', message: 'Installing update...' });
+            const result = await performUpdate();
+            ctx.ui.print({
+                type: result.success ? 'success' : 'error',
+                message: result.message,
+            });
+        }
+        else {
+            ctx.ui.print({
+                type: 'info',
+                message: 'Run "/update --install" or "npm update -g @compilr-dev/cli" to install',
+            });
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Permissions Command
+// =============================================================================
+export const permissionsCommand = {
+    name: 'permissions',
+    description: 'Manage tool permissions',
+    details: 'Opens a 3-tab overlay to manage tool permissions. Configure permission rules with wildcard patterns, set global permission modes, and view/revoke session grants.',
+    examples: [{ code: '/permissions' }],
+    interactions: [
+        'Tab cycles: Rules → Mode → Session',
+        '↑/↓ to navigate, ←/→ for pages',
+        'a to add rule, e/Enter to edit, d to delete',
+        'r to reset to defaults (Rules tab)',
+        'Enter/Space to select mode (Mode tab)',
+        'r to revoke, c to clear all (Session tab)',
+    ],
+    async execute(_args, ctx) {
+        // Get session grants from agent and convert to Map<string, Date>
+        // The overlay expects timestamps, but PermissionManager only stores names
+        // Use current time as placeholder for all grants
+        const sessionGrants = new Map();
+        if (ctx.agent) {
+            const grants = ctx.agent.getSessionPermissions();
+            const now = new Date();
+            for (const toolName of grants) {
+                sessionGrants.set(toolName, now);
+            }
+        }
+        // Create callbacks that capture the agent reference
+        const agent = ctx.agent;
+        const permissionsOverlay = new PermissionsOverlayV2({
+            sessionGrants,
+            onRevokeGrant: agent
+                ? (toolName) => agent.revokeSessionPermission(toolName)
+                : undefined,
+            onClearGrants: agent
+                ? () => { agent.clearSessionPermissions(); }
+                : undefined,
+            onModeChange: (newMode) => {
+                // Sync UI mode when permission mode changes in overlay
+                const uiMode = permissionModeToAgentMode(newMode);
+                ctx.ui.setMode(uiMode);
+            },
+        });
+        await ctx.ui.showOverlay(permissionsOverlay);
+        return true;
+    },
+};
+// =============================================================================
 // Export All Settings Commands
 // =============================================================================
 export const settingsCommands = [
@@ -232,4 +412,6 @@ export const settingsCommands = [
     keysCommand,
     mascotCommand,
     agentsCommand,
+    updateCommand,
+    permissionsCommand,
 ];

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

@@ -0,0 +1,5 @@
+/**
+ * Tasks Command Handler - View and manage background shell tasks
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const tasksCommand: CommandHandlerV2;

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

@@ -0,0 +1,36 @@
+/**
+ * Tasks Command Handler - View and manage background shell tasks
+ */
+import { TasksOverlayV2 } from '../../ui/overlay/impl/tasks-overlay-v2.js';
+export const tasksCommand = {
+    name: 'tasks',
+    aliases: ['bg', 'background'],
+    description: 'View and manage background shell tasks',
+    details: `
+Shows background shell processes started via the bash tool with run_in_background=true.
+
+From the overlay you can:
+- View running and completed tasks
+- See task output
+- Kill running tasks
+- Clear completed tasks
+
+Keyboard shortcut: Ctrl+B opens this overlay.
+  `.trim(),
+    examples: [
+        { code: '/tasks', description: 'Open background tasks overlay' },
+        { code: '/bg', description: 'Alias for /tasks' },
+    ],
+    interactions: [
+        '↑↓ or j/k to navigate task list',
+        'Enter to view task output',
+        'x to kill running task',
+        'c to clear completed tasks',
+        'r to refresh output (in detail view)',
+    ],
+    async execute(_args, ctx) {
+        const overlay = new TasksOverlayV2();
+        await ctx.ui.showOverlay(overlay);
+        return true;
+    },
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Team Commands for REPL V2
+ *
+ * Commands for managing multi-agent teams.
+ */
+import type { CommandHandlerV2 } from '../types.js';
+export declare const teamCommand: CommandHandlerV2;
+export declare const artifactCommand: CommandHandlerV2;
+export declare const teamCommands: CommandHandlerV2[];