@compilr-dev/cli 0.4.0

package/dist/commands/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Custom Command Types
+ *
+ * Type definitions for custom slash commands.
+ */
+/** Project-level commands directory */
+export declare const PROJECT_COMMANDS_DIR = ".compilr-dev/commands";
+/** User-level commands directory */
+export declare const USER_COMMANDS_DIR: string;
+/** Where the command is defined */
+export type CommandLocation = 'project' | 'personal';
+/** Custom command definition */
+export interface CustomCommand {
+    /** Command name (from filename, e.g., "review") */
+    name: string;
+    /** Short description (from frontmatter) */
+    description: string;
+    /** The prompt template content */
+    prompt: string;
+    /** Where this command is defined */
+    location: CommandLocation;
+    /** Full path to the .md file */
+    filePath: string;
+}
+/**
+ * Validate command name format
+ * - Lowercase letters, numbers, hyphens only
+ * - Must start with a letter
+ * - 2-30 characters
+ */
+export declare function isValidCommandName(name: string): boolean;

package/dist/commands/types.js

@@ -0,0 +1,26 @@
+/**
+ * Custom Command Types
+ *
+ * Type definitions for custom slash commands.
+ */
+import * as path from 'path';
+import * as os from 'os';
+// =============================================================================
+// Directory Constants
+// =============================================================================
+/** Project-level commands directory */
+export const PROJECT_COMMANDS_DIR = '.compilr-dev/commands';
+/** User-level commands directory */
+export const USER_COMMANDS_DIR = path.join(os.homedir(), '.compilr-dev', 'commands');
+// =============================================================================
+// Validation
+// =============================================================================
+/**
+ * Validate command name format
+ * - Lowercase letters, numbers, hyphens only
+ * - Must start with a letter
+ * - 2-30 characters
+ */
+export function isValidCommandName(name) {
+    return /^[a-z][a-z0-9-]{1,29}$/.test(name);
+}

package/dist/commands.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Slash Commands Registry
+ *
+ * Single source of truth for all slash commands.
+ * Used by: help menu, autocomplete dropdown, and command handler.
+ */
+/**
+ * Example with optional description
+ */
+export interface CommandExample {
+    /** The command to run (e.g., '/backlog') */
+    code: string;
+    /** What this example demonstrates */
+    description?: string;
+}
+export interface SlashCommand {
+    /** Command name without slash (e.g., 'help') */
+    name: string;
+    /** Short description for help/autocomplete */
+    description: string;
+    /** Alternative names (e.g., 'q' for 'exit') */
+    aliases?: string[];
+    /** Detailed explanation of what the command does */
+    details?: string;
+    /** Usage examples with optional descriptions */
+    examples?: CommandExample[];
+    /** UI interaction hints (keyboard shortcuts, navigation) */
+    interactions?: string[];
+}
+export declare const COMMANDS: SlashCommand[];
+/**
+ * Get commands formatted for autocomplete dropdown
+ * Includes both built-in and custom commands
+ */
+export declare function getAutocompleteCommands(): {
+    command: string;
+    description: string;
+}[];
+/**
+ * Get commands formatted for help menu
+ */
+export declare function getHelpCommands(): {
+    name: string;
+    description: string;
+}[];
+/**
+ * Resolve command name (handles aliases)
+ * Returns the canonical command name or null if not found
+ */
+export declare function resolveCommand(input: string): string | null;
+/**
+ * Check if a command exists
+ */
+export declare function isValidCommand(input: string): boolean;
+/**
+ * Check if a command is a custom command (starts with the input but isn't a built-in)
+ * This is used to allow custom command names that aren't in the registry
+ */
+export declare function isCustomCommand(_input: string): boolean;
+/**
+ * Get full command details by index (for help overlay man page)
+ */
+export declare function getCommandByIndex(index: number): SlashCommand | null;

package/dist/commands.js

@@ -0,0 +1,324 @@
+/**
+ * Slash Commands Registry
+ *
+ * Single source of truth for all slash commands.
+ * Used by: help menu, autocomplete dropdown, and command handler.
+ */
+import { getCustomCommandRegistry } from './commands/index.js';
+// =============================================================================
+// Command Registry
+// =============================================================================
+export const COMMANDS = [
+    {
+        name: 'agents',
+        description: 'Manage sub-agent configurations',
+        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',
+        ],
+    },
+    {
+        name: 'arch',
+        description: 'Create architecture documentation (ADRs, diagrams, etc.)',
+        details: 'Guides you through creating architecture documentation. Choose from ADRs (Architecture Decision Records), system diagrams, data models, or API designs. The agent asks questions and generates properly formatted documentation.',
+        examples: [
+            { code: '/arch', description: 'Interactive type selection' },
+            { code: '/arch decision', description: 'Create ADR directly' },
+            { code: '/arch diagram', description: 'Create system diagram' },
+        ],
+        interactions: [
+            '↑/↓ or 1-5 to select type',
+            'Enter to confirm',
+            'Esc to cancel',
+        ],
+    },
+    {
+        name: 'backlog',
+        description: 'View and manage project backlog',
+        details: 'Opens an interactive overlay to browse, filter, and manage backlog items. You can add new items, change status/priority, search, and view details.',
+        examples: [{ code: '/backlog' }],
+        interactions: [
+            'Tab cycles: All → Feature → Bug → Tech-Debt → Chore → Active',
+            '↑/↓ to navigate, ←/→ for pages',
+            'Enter for details, Space to toggle status',
+            '/ to search, n for new item',
+            'Esc to close',
+        ],
+    },
+    {
+        name: 'build',
+        description: 'Implement a backlog item',
+        details: 'Picks the highest priority backlog item (or a specific one) and guides the agent through implementing it. Includes planning, coding, testing, and committing. Auto-detects if project scaffold is needed first.',
+        examples: [
+            { code: '/build', description: 'Pick highest priority item' },
+            { code: '/build REQ-003', description: 'Build specific item' },
+            { code: '/build scaffold', description: 'Create project structure first' },
+        ],
+    },
+    {
+        name: 'clear',
+        description: 'Clear the screen',
+        details: 'Clears the terminal screen. Does not affect conversation history or context.',
+        examples: [{ code: '/clear' }],
+    },
+    {
+        name: 'commands',
+        description: 'Manage custom commands',
+        details: 'Create, edit, or delete custom slash commands. Custom commands are markdown files that expand into prompts when invoked.',
+        examples: [{ code: '/commands' }],
+        interactions: [
+            '↑/↓ to navigate commands',
+            'Enter to select or create new',
+            'Esc to close',
+        ],
+    },
+    {
+        name: 'compact',
+        description: 'Summarize old messages to free context',
+        details: 'When context is running low, use this to summarize older messages. The agent creates a summary and removes old messages to free up token space.',
+        examples: [{ code: '/compact' }],
+    },
+    {
+        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',
+            '↑/↓ to navigate in Config tab',
+            'Enter/Space to toggle or open submenu',
+            'Esc to exit',
+        ],
+    },
+    {
+        name: 'context',
+        description: 'Show context window usage',
+        details: 'Displays current context window utilization including token count, percentage used, and number of messages.',
+        examples: [{ code: '/context' }],
+    },
+    {
+        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.',
+        examples: [{ code: '/design' }],
+    },
+    {
+        name: 'exit',
+        description: 'Exit the REPL',
+        aliases: ['quit', 'q'],
+        details: 'Exits the CLI. Your conversation is not saved unless you export it first.',
+        examples: [
+            { code: '/exit' },
+            { code: '/quit', description: 'Alias' },
+            { code: '/q', description: 'Short alias' },
+        ],
+    },
+    {
+        name: 'export',
+        description: 'Export conversation to file or clipboard',
+        details: 'Export the current conversation to a file or clipboard for later reference.',
+        examples: [{ code: '/export' }],
+    },
+    {
+        name: 'help',
+        description: 'Show this help menu',
+        aliases: ['?'],
+        details: 'Opens the help overlay with tabs for general info, commands list, and custom commands.',
+        examples: [
+            { code: '/help' },
+            { code: '/?', description: 'Short alias' },
+        ],
+        interactions: [
+            'Tab cycles: general → commands → custom-commands',
+            '↑/↓ to navigate command list',
+            'Enter to view command details',
+            'Esc to go back or close',
+        ],
+    },
+    {
+        name: 'keys',
+        description: 'Manage API keys for LLM providers',
+        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',
+        ],
+    },
+    {
+        name: 'init',
+        description: 'Initialize 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' }],
+        interactions: [
+            '8-step wizard (0-7)',
+            '↑/↓ for selection steps, type for input steps',
+            'Enter to confirm, Esc to go back',
+        ],
+    },
+    {
+        name: 'model',
+        description: 'Show the current model',
+        details: 'Displays the currently active LLM model (e.g., claude-3-5-sonnet, gpt-4o).',
+        examples: [{ code: '/model' }],
+    },
+    {
+        name: 'note',
+        description: 'Create a session note capturing work done',
+        details: 'Creates a structured markdown note summarizing the current session including changes made, decisions, blockers, and next steps. Optionally provide a title.',
+        examples: [
+            { code: '/note', description: 'Auto-generated title' },
+            { code: '/note "Fixed auth bug"', description: 'Custom title' },
+        ],
+    },
+    {
+        name: 'plan',
+        description: 'Switch to Plan mode',
+        details: 'Enters plan mode where the agent focuses on planning and design rather than implementation. Useful for complex tasks that need thinking through first.',
+        examples: [{ code: '/plan' }],
+    },
+    {
+        name: 'prd',
+        description: 'Amend or enhance the Product Requirements Document',
+        details: 'Update or refine the PRD created during /design. The agent reads the existing PRD and guides you through updating specific sections.',
+        examples: [
+            { code: '/prd', description: 'Interactive section selection' },
+            { code: '/prd vision', description: 'Update vision section' },
+            { code: '/prd scope', description: 'Update scope section' },
+        ],
+    },
+    {
+        name: 'refine',
+        description: 'Refine and expand existing requirements',
+        details: 'Iteratively refine backlog items. Can focus on a specific item or let the agent suggest what to refine. Useful for breaking down large items or adding acceptance criteria.',
+        examples: [
+            { code: '/refine', description: 'Agent picks item to refine' },
+            { code: '/refine REQ-003', description: 'Refine specific item' },
+        ],
+    },
+    {
+        name: 'scaffold',
+        description: 'Create project foundation/structure',
+        details: 'Creates the base project structure (folders, config files, dependencies) based on tech stack from COMPILR.md. Use this before implementing features if starting from scratch. Alias for /build scaffold.',
+        examples: [{ code: '/scaffold' }],
+    },
+    {
+        name: 'sketch',
+        description: 'Quick project outline with simple questions',
+        details: 'Lightweight alternative to /design. Asks 6 quick questions and creates 3-8 backlog items. Good for small projects or when you want to get started quickly.',
+        examples: [{ code: '/sketch' }],
+    },
+    {
+        name: 'status',
+        description: 'Show version, model, mode, and context',
+        details: 'Displays current session status including CLI version, active model, mode, and context usage.',
+        examples: [{ code: '/status' }],
+    },
+    {
+        name: 'todos',
+        description: 'List current todo items',
+        details: 'Shows the current todo list that the agent uses to track work in progress.',
+        examples: [{ code: '/todos' }],
+    },
+    {
+        name: 'tokens',
+        description: 'Show session token usage',
+        details: 'Displays token usage statistics for the current session including input/output tokens and estimated cost.',
+        examples: [{ code: '/tokens' }],
+    },
+    {
+        name: 'tools',
+        description: 'List available tools',
+        details: 'Shows all tools available to the agent including file operations, bash, git, and custom tools.',
+        examples: [{ code: '/tools' }],
+    },
+    {
+        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.',
+        examples: [{ code: '/tutorial' }],
+        interactions: [
+            '↑/↓ to navigate options and topics',
+            '←/→ or Enter to navigate pages',
+            'Esc to go back or exit',
+        ],
+    },
+];
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get commands formatted for autocomplete dropdown
+ * Includes both built-in and custom commands
+ */
+export function getAutocompleteCommands() {
+    // Built-in commands
+    const builtIn = COMMANDS.map((cmd) => ({
+        command: `/${cmd.name}`,
+        description: cmd.description,
+    }));
+    // Custom commands
+    const customRegistry = getCustomCommandRegistry();
+    const custom = customRegistry.getAll().map((cmd) => ({
+        command: `/${cmd.name}`,
+        description: cmd.description,
+    }));
+    // Merge: built-in first, then custom
+    return [...builtIn, ...custom];
+}
+/**
+ * Get commands formatted for help menu
+ */
+export function getHelpCommands() {
+    return COMMANDS.map((cmd) => {
+        const aliases = cmd.aliases?.length ? ` (also /${cmd.aliases.join(', /')})` : '';
+        return {
+            name: `/${cmd.name}`,
+            description: `${cmd.description}${aliases}`,
+        };
+    });
+}
+/**
+ * Resolve command name (handles aliases)
+ * Returns the canonical command name or null if not found
+ */
+export function resolveCommand(input) {
+    const lower = input.toLowerCase();
+    for (const cmd of COMMANDS) {
+        if (cmd.name === lower)
+            return cmd.name;
+        if (cmd.aliases?.includes(lower))
+            return cmd.name;
+    }
+    return null;
+}
+/**
+ * Check if a command exists
+ */
+export function isValidCommand(input) {
+    return resolveCommand(input) !== null;
+}
+/**
+ * Check if a command is a custom command (starts with the input but isn't a built-in)
+ * This is used to allow custom command names that aren't in the registry
+ */
+export function isCustomCommand(_input) {
+    // Custom commands use the same format but aren't in the built-in list
+    // The custom command registry handles this separately
+    return false; // Placeholder - actual check happens in REPL
+}
+/**
+ * Get full command details by index (for help overlay man page)
+ */
+export function getCommandByIndex(index) {
+    if (index < 0 || index >= COMMANDS.length) {
+        return null;
+    }
+    return COMMANDS[index];
+}

package/dist/db/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Database module for compilr-cli
+ *
+ * Provides SQLite database connection and initialization.
+ * Database location: ~/.compilr-dev/projects.db
+ */
+import Database from 'better-sqlite3';
+export * from './schema.js';
+/**
+ * Get the database directory path
+ */
+export declare function getDbDir(): string;
+/**
+ * Get the database file path
+ */
+export declare function getDbPath(): string;
+/**
+ * Get or create the database connection
+ */
+export declare function getDb(): Database.Database;
+/**
+ * Close the database connection
+ */
+export declare function closeDb(): void;
+/**
+ * Check if the database exists
+ */
+export declare function dbExists(): boolean;
+/**
+ * Get database stats for debugging
+ */
+export declare function getDbStats(): {
+    exists: boolean;
+    path: string;
+    size: number | null;
+    projectCount: number;
+    workItemCount: number;
+};
+/**
+ * Transaction helper for running multiple operations atomically
+ */
+export declare function transaction<T>(fn: (db: Database.Database) => T): T;

package/dist/db/index.js

@@ -0,0 +1,146 @@
+/**
+ * Database module for compilr-cli
+ *
+ * Provides SQLite database connection and initialization.
+ * Database location: ~/.compilr-dev/projects.db
+ */
+import Database from 'better-sqlite3';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { SCHEMA_SQL, SCHEMA_VERSION } from './schema.js';
+// Re-export types
+export * from './schema.js';
+// Database instance (singleton)
+let dbInstance = null;
+/**
+ * Get the database directory path
+ */
+export function getDbDir() {
+    return path.join(os.homedir(), '.compilr-dev');
+}
+/**
+ * Get the database file path
+ */
+export function getDbPath() {
+    return path.join(getDbDir(), 'projects.db');
+}
+/**
+ * Initialize the database directory if it doesn't exist
+ */
+function ensureDbDir() {
+    const dbDir = getDbDir();
+    if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+    }
+}
+/**
+ * Get or create the database connection
+ */
+export function getDb() {
+    if (dbInstance) {
+        return dbInstance;
+    }
+    ensureDbDir();
+    const dbPath = getDbPath();
+    // Create/open database
+    dbInstance = new Database(dbPath);
+    // Enable foreign keys
+    dbInstance.pragma('foreign_keys = ON');
+    // Enable WAL mode for better concurrency
+    dbInstance.pragma('journal_mode = WAL');
+    // Initialize schema if needed
+    initializeSchema(dbInstance);
+    return dbInstance;
+}
+/**
+ * Initialize the database schema
+ */
+function initializeSchema(db) {
+    // Check if schema_version table exists
+    const tableExists = db
+        .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='schema_version'`)
+        .get();
+    if (!tableExists) {
+        // Fresh database - create all tables
+        db.exec(SCHEMA_SQL);
+        // Record schema version
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(SCHEMA_VERSION);
+        return;
+    }
+    // Check current schema version
+    const currentVersion = db
+        .prepare('SELECT MAX(version) as version FROM schema_version')
+        .get();
+    if (!currentVersion || currentVersion.version < SCHEMA_VERSION) {
+        // Run migrations (for future use)
+        runMigrations(db, currentVersion?.version ?? 0, SCHEMA_VERSION);
+    }
+}
+/**
+ * Run database migrations from one version to another
+ */
+function runMigrations(db, fromVersion, toVersion) {
+    // Future migrations go here
+    // For now, just update the version
+    if (fromVersion < toVersion) {
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(toVersion);
+    }
+}
+/**
+ * Close the database connection
+ */
+export function closeDb() {
+    if (dbInstance) {
+        dbInstance.close();
+        dbInstance = null;
+    }
+}
+/**
+ * Check if the database exists
+ */
+export function dbExists() {
+    return fs.existsSync(getDbPath());
+}
+/**
+ * Get database stats for debugging
+ */
+export function getDbStats() {
+    const dbPath = getDbPath();
+    const exists = fs.existsSync(dbPath);
+    let size = null;
+    let projectCount = 0;
+    let workItemCount = 0;
+    if (exists) {
+        try {
+            const stats = fs.statSync(dbPath);
+            size = stats.size;
+            const db = getDb();
+            const projectResult = db
+                .prepare('SELECT COUNT(*) as count FROM projects')
+                .get();
+            const workItemResult = db
+                .prepare('SELECT COUNT(*) as count FROM work_items')
+                .get();
+            projectCount = projectResult.count;
+            workItemCount = workItemResult.count;
+        }
+        catch {
+            // Ignore errors, return defaults
+        }
+    }
+    return {
+        exists,
+        path: dbPath,
+        size,
+        projectCount,
+        workItemCount,
+    };
+}
+/**
+ * Transaction helper for running multiple operations atomically
+ */
+export function transaction(fn) {
+    const db = getDb();
+    return db.transaction(() => fn(db))();
+}