@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/mascot/renderer.js

@@ -0,0 +1,132 @@
+/**
+ * Mascot Renderer
+ *
+ * Handles rendering the mascot alongside the logo and applying colors.
+ */
+import { getStyles } from '../../themes/index.js';
+import { getExpressionForSetting } from './expressions.js';
+import { getTerminalWidth } from '../terminal.js';
+function stripAnsi(str) {
+    // eslint-disable-next-line no-control-regex
+    return str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+}
+// The compilr logo (6 lines to match mascot height)
+const LOGO_LINES = [
+    "   ___  ___  _ __ ___  _ __ (_) |_ __",
+    "  / __|/ _ \\| '_ ` _ \\| '_ \\| | | '__|",
+    " | (__| (_) | | | | | | |_) | | | |",
+    "  \\___|\\___/|_| |_| |_| .__/|_|_|_|",
+    "                      | | .dev",
+    "                      |_|",
+];
+/**
+ * Combine two sets of lines horizontally with a gap
+ */
+export function combineHorizontally(left, right, gap) {
+    const maxLines = Math.max(left.length, right.length);
+    const leftWidth = Math.max(...left.map((l) => l.length));
+    const result = [];
+    for (let i = 0; i < maxLines; i++) {
+        const leftLine = (left[i] || '').padEnd(leftWidth);
+        const rightLine = right[i] || '';
+        result.push(leftLine + ' '.repeat(gap) + rightLine);
+    }
+    return result;
+}
+/**
+ * Render mascot with logo side by side
+ * Returns the combined lines ready for output
+ *
+ * @param mascotSetting - The mascot setting (expression or 'none'/'random')
+ * @param version - Version string to append to logo
+ * @param projectName - Optional active project name to show
+ */
+export function renderMascotWithLogo(mascotSetting, version, projectName, highlights) {
+    const s = getStyles();
+    // Get mascot expression (or null for 'none')
+    const mascotLines = getExpressionForSetting(mascotSetting);
+    // Create logo lines with version
+    const logoWithVersion = [...LOGO_LINES];
+    logoWithVersion[5] = `                      |_| v${version}`;
+    // Add tagline and project info below logo
+    const tagline = '@compilr-dev/cli - AI-powered coding assistant';
+    let result;
+    if (mascotLines) {
+        // Combine mascot + logo horizontally (5 space gap)
+        result = combineHorizontally(mascotLines, logoWithVersion, 5);
+        // Add empty line and tagline
+        result.push('');
+        result.push(tagline);
+    }
+    else {
+        // No mascot - just show logo
+        result = [...logoWithVersion];
+        result.push('');
+        result.push(tagline);
+    }
+    // Add project info if available
+    if (projectName) {
+        result.push('');
+        result.push(`Project: ${projectName}`);
+    }
+    // Apply colors: mascot gets secondary color, logo gets accent
+    const colored = result.map((line, index) => {
+        if (!mascotLines) {
+            // No mascot - color the logo with accent
+            if (index < logoWithVersion.length) {
+                return s.primary(line);
+            }
+            // Tagline and project info get muted color
+            if (line.startsWith('Project:')) {
+                return s.muted(line);
+            }
+            return s.muted(line);
+        }
+        // With mascot - split the line at the gap point
+        const mascotWidth = Math.max(...mascotLines.map((l) => l.length));
+        const gap = 5;
+        if (index < mascotLines.length) {
+            // Lines that have mascot + logo
+            const mascotPart = line.slice(0, mascotWidth);
+            const logoPart = line.slice(mascotWidth + gap);
+            return s.secondary(mascotPart) + ' '.repeat(gap) + s.primary(logoPart);
+        }
+        else if (line.startsWith('Project:')) {
+            return s.muted(line);
+        }
+        else if (line === tagline) {
+            return s.muted(line);
+        }
+        return line;
+    });
+    // Append "What's New" highlights column (wide terminals only)
+    if (highlights && highlights.length > 0) {
+        const termWidth = getTerminalWidth();
+        const baseWidth = Math.max(...colored.map((l) => stripAnsi(l).length));
+        const highlightsGap = 3;
+        const minHighlightsCol = 25;
+        if (termWidth >= baseWidth + highlightsGap + minHighlightsCol) {
+            // Build styled highlights column (6 lines to match mascot height)
+            const hlLines = [];
+            hlLines.push(s.primaryBold("[^_^] What's New"));
+            hlLines.push(s.muted('───────────────────'));
+            for (const h of highlights.slice(0, 3)) {
+                hlLines.push(`${s.secondary('+')} ${h}`);
+            }
+            hlLines.push(s.muted('/changelog for more'));
+            while (hlLines.length < 6) {
+                hlLines.push('');
+            }
+            // Append highlights to the first 6 lines of the colored result
+            return colored.map((line, i) => {
+                if (i < hlLines.length && hlLines[i]) {
+                    const visualLen = stripAnsi(line).length;
+                    const pad = Math.max(1, baseWidth - visualLen + highlightsGap);
+                    return line + ' '.repeat(pad) + hlLines[i];
+                }
+                return line;
+            });
+        }
+    }
+    return colored;
+}

package/dist/ui/overlay/data/tutorial-content.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tutorial Content
+ *
+ * Re-exports the tutorial registry for use by tutorial-overlay-v2.
+ * This file maintains backward compatibility while the actual content
+ * is now organized in separate files under ./tutorials/.
+ */
+export type { TutorialPage, TutorialItem, TutorialTab } from './tutorial-types.js';
+export { buildTutorialRegistry as buildTutorialContent } from './tutorial-registry.js';

package/dist/ui/overlay/data/tutorial-content.js

@@ -0,0 +1,9 @@
+/**
+ * Tutorial Content
+ *
+ * Re-exports the tutorial registry for use by tutorial-overlay-v2.
+ * This file maintains backward compatibility while the actual content
+ * is now organized in separate files under ./tutorials/.
+ */
+// Re-export the builder from the registry
+export { buildTutorialRegistry as buildTutorialContent } from './tutorial-registry.js';

package/dist/ui/overlay/data/tutorial-registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tutorial Registry
+ *
+ * Combines all individual tutorials into the tab structure.
+ * Add new tutorials here as they are created.
+ */
+import type { ThemeStyleFunctions } from '../../../themes/index.js';
+import type { TutorialTab } from './tutorial-types.js';
+/**
+ * Build all tutorial content organized into tabs.
+ */
+export declare function buildTutorialRegistry(s: ThemeStyleFunctions): TutorialTab[];

package/dist/ui/overlay/data/tutorial-registry.js

@@ -0,0 +1,116 @@
+/**
+ * Tutorial Registry
+ *
+ * Combines all individual tutorials into the tab structure.
+ * Add new tutorials here as they are created.
+ */
+// Import individual tutorials
+import { welcomeTutorial } from './tutorials/basics/welcome.js';
+import { firstProjectTutorial } from './tutorials/basics/first-project.js';
+import { firstConversationTutorial } from './tutorials/basics/first-conversation.js';
+import { navigationTutorial } from './tutorials/basics/navigation.js';
+import { newProjectTutorial } from './tutorials/projects/new-project.js';
+import { managingProjectsTutorial } from './tutorials/projects/managing-projects.js';
+import { sessionManagementTutorial } from './tutorials/projects/session-management.js';
+import { anchorsTutorial } from './tutorials/projects/anchors.js';
+import { importProjectTutorial } from './tutorials/projects/import-project.js';
+import { designTutorial } from './tutorials/planning/design.js';
+import { backlogTutorial } from './tutorials/planning/backlog.js';
+import { sketchTutorial } from './tutorials/planning/sketch.js';
+import { scaffoldTutorial } from './tutorials/planning/scaffold.js';
+import { buildTutorial } from './tutorials/planning/build.js';
+import { prdTutorial } from './tutorials/planning/prd.js';
+import { archTutorial } from './tutorials/planning/arch.js';
+import { docsTutorial } from './tutorials/planning/docs.js';
+import { teamOverviewTutorial } from './tutorials/teams/team-overview.js';
+import { workingWithAgentsTutorial } from './tutorials/teams/working-with-agents.js';
+import { backgroundExecutionTutorial } from './tutorials/teams/background-execution.js';
+import { taskAssignmentTutorial } from './tutorials/teams/task-assignment.js';
+import { multiTerminalTutorial } from './tutorials/teams/multi-terminal.js';
+import { modelSelectionTutorial } from './tutorials/config/model-selection.js';
+import { settingsConfigTutorial } from './tutorials/config/settings-config.js';
+import { contextManagementTutorial } from './tutorials/config/context-management.js';
+import { permissionsSafetyTutorial } from './tutorials/config/permissions-safety.js';
+import { mcpServersTutorial } from './tutorials/config/mcp-servers.js';
+// =============================================================================
+// Registry Builder
+// =============================================================================
+/**
+ * Build all tutorial content organized into tabs.
+ */
+export function buildTutorialRegistry(s) {
+    return [
+        // =========================================================================
+        // Tab 1: Basics
+        // =========================================================================
+        {
+            id: 'basics',
+            label: 'Basics',
+            items: [
+                welcomeTutorial(s),
+                firstProjectTutorial(s),
+                firstConversationTutorial(s),
+                navigationTutorial(s),
+            ],
+        },
+        // =========================================================================
+        // Tab 2: Projects
+        // =========================================================================
+        {
+            id: 'projects',
+            label: 'Projects',
+            items: [
+                newProjectTutorial(s),
+                importProjectTutorial(s),
+                managingProjectsTutorial(s),
+                sessionManagementTutorial(s),
+                anchorsTutorial(s),
+            ],
+        },
+        // =========================================================================
+        // Tab 3: Plan & Build
+        // =========================================================================
+        {
+            id: 'plan-build',
+            label: 'Plan & Build',
+            items: [
+                designTutorial(s),
+                sketchTutorial(s),
+                backlogTutorial(s),
+                prdTutorial(s),
+                archTutorial(s),
+                docsTutorial(s),
+                scaffoldTutorial(s),
+                buildTutorial(s),
+            ],
+        },
+        // =========================================================================
+        // Tab 4: Teams
+        // =========================================================================
+        {
+            id: 'teams',
+            label: 'Teams',
+            items: [
+                teamOverviewTutorial(s),
+                workingWithAgentsTutorial(s),
+                backgroundExecutionTutorial(s),
+                taskAssignmentTutorial(s),
+                multiTerminalTutorial(s),
+            ],
+        },
+        // =========================================================================
+        // Tab 5: Config
+        // =========================================================================
+        {
+            id: 'config',
+            label: 'Config',
+            items: [
+                modelSelectionTutorial(s),
+                settingsConfigTutorial(s),
+                contextManagementTutorial(s),
+                permissionsSafetyTutorial(s),
+                mcpServersTutorial(s),
+            ],
+        },
+    ];
+}

package/dist/ui/overlay/data/tutorial-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tutorial Types
+ *
+ * Shared types for the tutorial system.
+ */
+import type { ThemeStyleFunctions } from '../../../themes/index.js';
+/**
+ * A single page within a tutorial.
+ * Each tutorial can have multiple pages that the user navigates through.
+ */
+export interface TutorialPage {
+    title: string;
+    lines: string[];
+}
+/**
+ * A tutorial item representing a complete tutorial topic.
+ */
+export interface TutorialItem {
+    id: string;
+    title: string;
+    description: string;
+    pages: TutorialPage[];
+}
+/**
+ * A tab grouping related tutorials together.
+ */
+export interface TutorialTab {
+    id: string;
+    label: string;
+    items: TutorialItem[];
+}
+/**
+ * Function signature for building a tutorial with theme styles.
+ */
+export type TutorialBuilder = (s: ThemeStyleFunctions) => TutorialItem;

package/dist/ui/overlay/data/tutorial-types.js

@@ -0,0 +1,6 @@
+/**
+ * Tutorial Types
+ *
+ * Shared types for the tutorial system.
+ */
+export {};

package/dist/ui/overlay/data/tutorials/basics/first-conversation.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Your First Conversation Tutorial
+ *
+ * How to interact with the AI in REPL mode.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const firstConversationTutorial: TutorialBuilder;

package/dist/ui/overlay/data/tutorials/basics/first-conversation.js

@@ -0,0 +1,220 @@
+/**
+ * Your First Conversation Tutorial
+ *
+ * How to interact with the AI in REPL mode.
+ */
+export const firstConversationTutorial = (s) => ({
+    id: 'first-conversation',
+    title: 'Your First Conversation',
+    description: 'How to chat with the AI assistant',
+    pages: [
+        // Page 1: Starting from Dashboard
+        {
+            title: 'Starting from Dashboard',
+            lines: [
+                '',
+                `  After creating a project, you'll see the Dashboard:`,
+                '',
+                `    ${s.muted('─'.repeat(50))}`,
+                `       ${s.muted('Dashboard')}  │  ${s.muted('More')}`,
+                `    ${s.muted('─'.repeat(50))}`,
+                '',
+                `      ${s.secondary('CURRENT PROJECT')}`,
+                `      ${s.primaryBold('★ My First Project')}`,
+                `        ${s.muted('/workspace/projects/my-first-project │ active │ flexible')}`,
+                '',
+                `      ${s.secondary('ACTIONS')}`,
+                `      ${s.primary('❯')} Continue with My First Project   ${s.muted('Resume working on current project')}`,
+                '',
+                `      ${s.muted('↑↓/jk Navigate   Enter Select   q Quit')}`,
+                '',
+                `  Press ${s.primary('Enter')} to continue with your project.`,
+                '',
+            ],
+        },
+        // Page 2: The REPL
+        {
+            title: 'The REPL',
+            lines: [
+                '',
+                `  After pressing Enter, you'll see the REPL (Read-Eval-Print Loop):`,
+                '',
+                `    ${s.muted('✓ Agent connected')}`,
+                '',
+                `    ${s.muted('Model: gemini-2.5-flash')}`,
+                `    ${s.muted('Provider: gemini')}`,
+                `    ${s.muted('[^_^] Switched to project: My First Project')}`,
+                '',
+                `    ${s.muted('─'.repeat(40))}`,
+                `    ${s.primary('compilr>')} ${s.muted('█')}`,
+                `    ${s.muted('─'.repeat(40))}`,
+                `    ${s.muted('mode: Normal                    Project: My First Project')}`,
+                '',
+                `  Type your message and press ${s.primary('Enter')} to chat with the AI.`,
+                '',
+            ],
+        },
+        // Page 3: File References
+        {
+            title: 'File References with @',
+            lines: [
+                '',
+                `  Reference files by typing ${s.primary('@')} followed by a path:`,
+                '',
+                `    ${s.primary('compilr>')} Fix the bug in ${s.secondary('@src/utils.ts')}`,
+                '',
+                `  ${s.secondary('Autocomplete:')} Press ${s.primary('Tab')} after ${s.primary('@')} to see matches.`,
+                '',
+                `    ${s.primary('compilr>')} Explain ${s.secondary('@src/')}`,
+                `        ${s.muted('src/index.ts')}`,
+                `        ${s.muted('src/utils.ts')}`,
+                `        ${s.muted('src/config.ts')}`,
+                '',
+                `  ${s.secondary('Multiple files:')}`,
+                '',
+                `    ${s.primary('compilr>')} Compare ${s.secondary('@src/old.ts')} with ${s.secondary('@src/new.ts')}`,
+                '',
+                `  The AI will read the files and understand the context.`,
+                '',
+            ],
+        },
+        // Page 4: Slash Commands
+        {
+            title: 'Slash Commands',
+            lines: [
+                '',
+                `  Commands start with ${s.primary('/')}:`,
+                '',
+                `    ${s.primary('/help')}       Show available commands`,
+                `    ${s.primary('/clear')}      Clear the screen`,
+                `    ${s.primary('/exit')}       Exit the CLI`,
+                `    ${s.primary('/design')}     Start requirements gathering`,
+                `    ${s.primary('/backlog')}    View your work items`,
+                '',
+                `  ${s.secondary('Autocomplete:')} Type ${s.primary('/')} and press ${s.primary('Tab')}`,
+                '',
+                `    ${s.primary('compilr>')} /he`,
+                `        ${s.muted('/help')}`,
+                `        ${s.muted('/health')}`,
+                '',
+                `  ${s.warning('TIP:')} Run ${s.primary('/help')} to see all commands,`,
+                `       or ${s.primary('/tutorial')} to browse these guides!`,
+                '',
+            ],
+        },
+        // Page 5: What the AI Can Do
+        {
+            title: 'What the AI Can Do',
+            lines: [
+                '',
+                `  The AI can help with:`,
+                '',
+                `    ${s.success('✓')} ${s.primary('Read files')} - Understand your code`,
+                `    ${s.success('✓')} ${s.primary('Write files')} - Create or modify code`,
+                `    ${s.success('✓')} ${s.primary('Run commands')} - Execute shell commands`,
+                `    ${s.success('✓')} ${s.primary('Search code')} - Find patterns in your codebase`,
+                `    ${s.success('✓')} ${s.primary('Git operations')} - Commit, diff, status`,
+                `    ${s.success('✓')} ${s.primary('Answer questions')} - Explain code, debug issues`,
+                '',
+                `  ${s.secondary('Example requests:')}`,
+                '',
+                `    ${s.muted('"Create a login component"')}`,
+                `    ${s.muted('"Why is this test failing?"')}`,
+                `    ${s.muted('"Refactor this function to use async/await"')}`,
+                '',
+            ],
+        },
+        // Page 6: Permission Prompts
+        {
+            title: 'Permission Prompts',
+            lines: [
+                '',
+                `  The AI asks permission before making changes:`,
+                '',
+                `    ┌─ Permission Required ───────────────────────┐`,
+                `    │                                             │`,
+                `    │  The agent wants to create a file:          │`,
+                `    │  ${s.primary('src/components/Login.tsx')}                   │`,
+                `    │                                             │`,
+                `    │  ${s.success('[Allow]')}  ${s.muted('[Allow Always]')}  ${s.error('[Deny]')}            │`,
+                `    │                                             │`,
+                `    └─────────────────────────────────────────────┘`,
+                '',
+                `    ${s.success('Allow')}        - Approve this specific action`,
+                `    ${s.muted('Allow Always')} - Auto-approve this tool for the session`,
+                `    ${s.error('Deny')}         - Reject this action`,
+                '',
+                `  ${s.muted('You\'re always in control of what changes are made.')}`,
+                '',
+            ],
+        },
+        // Page 7: Stopping and Canceling
+        {
+            title: 'Stopping and Canceling',
+            lines: [
+                '',
+                `  ${s.secondary('While the AI is working:')}`,
+                '',
+                `    ${s.primary('Esc')}      Stop the current operation`,
+                `                ${s.muted('The AI will finish its current thought')}`,
+                '',
+                `    ${s.primary('Ctrl+C')}   Force stop immediately`,
+                `                ${s.muted('Use when Esc doesn\'t respond')}`,
+                '',
+                `  ${s.secondary('While typing:')}`,
+                '',
+                `    ${s.primary('Ctrl+C')}   Clear current input`,
+                `    ${s.primary('Ctrl+C')} ${s.muted('twice')}  Exit the CLI`,
+                '',
+                `  ${s.warning('TIP:')} If the AI is taking too long, just press Esc.`,
+                `       You can continue the conversation afterward.`,
+                '',
+            ],
+        },
+        // Page 8: Context and Memory
+        {
+            title: 'Context and Memory',
+            lines: [
+                '',
+                `  The AI remembers your conversation within a session.`,
+                '',
+                `  ${s.secondary('What the AI knows:')}`,
+                `    ${s.muted('•')} Your project info (from COMPILR.md)`,
+                `    ${s.muted('•')} Files you've referenced`,
+                `    ${s.muted('•')} Previous messages in this session`,
+                `    ${s.muted('•')} Anchors (persistent notes)`,
+                '',
+                `  ${s.secondary('Context commands:')}`,
+                `    ${s.primary('/context')}   See current context usage`,
+                `    ${s.primary('/compact')}   Summarize old messages (free up space)`,
+                `    ${s.primary('/anchors')}   View/add persistent notes`,
+                '',
+                `  ${s.muted('Sessions auto-save. Use')} ${s.primary('/resume')} ${s.muted('to continue later.')}`,
+                '',
+            ],
+        },
+        // Page 9: Next Steps
+        {
+            title: 'Next Steps',
+            lines: [
+                '',
+                `  ${s.secondary('You\'re ready to start building!')}`,
+                '',
+                `  ${s.primary('Recommended workflow:')}`,
+                '',
+                `    ${s.muted('1.')} Run ${s.primary('/design')} to plan your features`,
+                `        ${s.muted('The AI will help create a PRD and backlog')}`,
+                '',
+                `    ${s.muted('2.')} Run ${s.primary('/backlog')} to see your work items`,
+                `        ${s.muted('Pick one to start building')}`,
+                '',
+                `    ${s.muted('3.')} Ask the AI to implement features`,
+                `        ${s.muted('"Build the user authentication from REQ-001"')}`,
+                '',
+                `  ${s.warning('TIP:')} Browse the other tutorials to learn about`,
+                `       ${s.primary('/design')}, ${s.primary('/backlog')}, and team agents!`,
+                '',
+            ],
+        },
+    ],
+});

package/dist/ui/overlay/data/tutorials/basics/first-project.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Your First Project Tutorial
+ *
+ * Guides users through the dashboard and /new wizard.
+ */
+import type { TutorialBuilder } from '../../tutorial-types.js';
+export declare const firstProjectTutorial: TutorialBuilder;