@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/ui/live-region-facade.js

@@ -0,0 +1,205 @@
+/**
+ * LiveRegion facade.
+ *
+ * Extracted from TerminalUI — owns the LiveRegion instance and active
+ * bash tracking. Methods that need to commit items to the scrolling
+ * zone or emit events go through the host interface.
+ */
+import { formatTokens } from './base/index.js';
+import { LiveRegion } from './live-region.js';
+export class LiveRegionFacade {
+    /** The underlying LiveRegion (exposed for render pipeline). */
+    region = new LiveRegion();
+    /** Active bash command tracking (for Ctrl+B background feature). */
+    activeBashToolUseId = null;
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    // ===========================================================================
+    // Subagents
+    // ===========================================================================
+    addSubagent(id, agentType, description) {
+        const item = {
+            id,
+            type: 'subagent',
+            status: 'running',
+            startTime: Date.now(),
+            agentType,
+            description,
+            toolCount: 0,
+            tokenCount: 0,
+            lastAction: '',
+            lastActionDetails: [],
+        };
+        this.region.addItem(item);
+        this.host.requestRender();
+    }
+    updateSubagentTool(id, toolName, summary) {
+        const item = this.region.getItem(id);
+        if (item && item.type === 'subagent') {
+            const newAction = `${toolName}: ${summary}`;
+            const updatedDetails = item.lastAction
+                ? [...item.lastActionDetails, item.lastAction]
+                : [...item.lastActionDetails];
+            this.region.updateItem(id, {
+                toolCount: item.toolCount + 1,
+                lastAction: newAction,
+                lastActionDetails: updatedDetails,
+            });
+            this.host.requestRender();
+        }
+    }
+    completeSubagent(id, success, tokenCount, _error) {
+        const item = this.region.getItem(id);
+        if (item && item.type === 'subagent') {
+            this.region.updateItem(id, {
+                status: success ? 'done' : 'error',
+                tokenCount: tokenCount ?? item.tokenCount,
+                endTime: Date.now(),
+            });
+            this.region.completeItem(id, success ? 'done' : 'error');
+            this.host.requestRender();
+        }
+    }
+    removeSubagent(id) {
+        const item = this.region.removeItem(id);
+        this.host.requestRender();
+        return item;
+    }
+    commitSubagent(id, resultContent, success) {
+        const item = this.region.removeItem(id);
+        if (item && item.type === 'subagent') {
+            const toolCount = item.toolCount;
+            const tokenCount = item.tokenCount;
+            const duration = item.endTime
+                ? Math.round((item.endTime - item.startTime) / 1000)
+                : Math.round((Date.now() - item.startTime) / 1000);
+            const tokenStr = tokenCount > 0 ? `, ${formatTokens(tokenCount)} tokens` : '';
+            const summary = `${String(toolCount)} tool calls${tokenStr}, ${String(duration)}s`;
+            this.host.print({
+                type: 'tool-result',
+                name: item.agentType,
+                params: item.description,
+                summary,
+                content: resultContent || undefined,
+                success,
+            });
+            this.host.setSpinnerText(null);
+        }
+        this.host.requestRender();
+        return item;
+    }
+    // ===========================================================================
+    // Bash commands
+    // ===========================================================================
+    addBashCommand(id, command) {
+        const item = {
+            id,
+            type: 'bash',
+            status: 'running',
+            startTime: Date.now(),
+            command,
+            output: [],
+        };
+        this.region.addItem(item);
+        this.activeBashToolUseId = id;
+        this.host.requestRender();
+    }
+    updateBashOutput(id, line) {
+        const item = this.region.getItem(id);
+        if (item && item.type === 'bash') {
+            item.output.push(line);
+            this.region.updateItem(id, { output: [...item.output] });
+            this.host.requestRender();
+        }
+    }
+    completeBashCommand(id, exitCode) {
+        const item = this.region.getItem(id);
+        if (item && item.type === 'bash') {
+            this.region.updateItem(id, {
+                status: exitCode === 0 ? 'done' : 'error',
+                exitCode,
+                endTime: Date.now(),
+            });
+            this.region.completeItem(id, exitCode === 0 ? 'done' : 'error');
+            if (this.activeBashToolUseId === id) {
+                this.activeBashToolUseId = null;
+            }
+            this.host.requestRender();
+        }
+    }
+    commitBashCommand(id) {
+        if (this.activeBashToolUseId === id) {
+            this.activeBashToolUseId = null;
+        }
+        const item = this.region.removeItem(id);
+        if (item && item.type === 'bash') {
+            const output = item.output.join('\n') || '(no output)';
+            const exitCode = item.exitCode ?? 0;
+            this.host.print({
+                type: 'tool-result',
+                name: 'Bash',
+                params: item.command,
+                summary: exitCode === 0 ? 'Completed' : `Exit code ${String(exitCode)}`,
+                content: output,
+                success: exitCode === 0,
+            });
+        }
+        this.host.requestRender();
+    }
+    backgroundBashCommand() {
+        if (!this.activeBashToolUseId)
+            return;
+        const item = this.region.getItem(this.activeBashToolUseId);
+        if (!item || item.type !== 'bash')
+            return;
+        const bashItem = item;
+        const id = this.activeBashToolUseId;
+        this.region.updateItem(id, { background: true });
+        this.region.removeItem(id);
+        this.activeBashToolUseId = null;
+        this.host.print({
+            type: 'info',
+            message: `Task moved to background (id: ${id.slice(0, 8)}). Use /tasks or Ctrl+B to view.`,
+        });
+        this.host.emit('backgroundBash', {
+            toolUseId: id,
+            command: bashItem.command,
+            partialOutput: bashItem.output.join('\n'),
+            startTime: bashItem.startTime,
+        });
+        this.host.requestRender();
+    }
+    // ===========================================================================
+    // Queries
+    // ===========================================================================
+    hasActiveBash() {
+        return this.activeBashToolUseId !== null;
+    }
+    getActiveBashInfo() {
+        if (!this.activeBashToolUseId)
+            return null;
+        const item = this.region.getItem(this.activeBashToolUseId);
+        if (!item || item.type !== 'bash')
+            return null;
+        return {
+            toolUseId: this.activeBashToolUseId,
+            startTime: item.startTime,
+        };
+    }
+    clearLiveRegion() {
+        this.region.clear();
+        this.host.requestRender();
+    }
+    toggleLiveRegionExpanded() {
+        this.region.toggleExpanded();
+        this.host.requestRender();
+    }
+    hasLiveItems() {
+        return this.region.hasItems();
+    }
+    getLiveRegion() {
+        return this.region;
+    }
+}

package/dist/ui/live-region.d.ts

@@ -146,10 +146,6 @@ export declare class LiveRegion {
     private renderBashItem;
     private renderToolItem;
     private renderEphemeralNotification;
-    /**
-     * Format token count for display (e.g., 18.1k)
-     */
-    private formatTokens;
     /**
      * Truncate a line to fit within width.
      */

package/dist/ui/live-region.js

@@ -12,6 +12,7 @@
  */
 import { getStyles } from '../themes/index.js';
 import { getVisibleLength } from './line-utils.js';
+import { formatTokens } from './base/index.js';
 // =============================================================================
 // Constants
 // =============================================================================
@@ -206,7 +207,7 @@ export class LiveRegion {
         if (item.status === 'done') {
             // Completed: show summary
             const duration = item.endTime ? Math.round((item.endTime - item.startTime) / 1000) : 0;
-            const tokenStr = options.showTokens ? ` · ${this.formatTokens(item.tokenCount)} tokens` : '';
+            const tokenStr = options.showTokens ? ` · ${formatTokens(item.tokenCount)} tokens` : '';
             const summary = `  ${RESULT_MARKER}  Done (${String(item.toolCount)} tool uses${tokenStr} · ${String(duration)}s)`;
             lines.push(s.muted(summary));
         }
@@ -229,7 +230,7 @@ export class LiveRegion {
                 }
             }
             // Hints
-            lines.push(`     ${s.muted('ctrl+b to run in background')}`);
+            // ctrl+b background: coming soon
         }
         return lines;
     }
@@ -259,7 +260,7 @@ export class LiveRegion {
             const branch = isLast ? TREE_END : TREE_BRANCH;
             const continuation = isLast ? '   ' : `${TREE_CONTINUE}  `;
             // Agent line: description · tool count · tokens
-            const tokenStr = options.showTokens ? ` · ${this.formatTokens(item.tokenCount)} tokens` : '';
+            const tokenStr = options.showTokens ? ` · ${formatTokens(item.tokenCount)} tokens` : '';
             const toolWord = item.toolCount === 1 ? 'tool use' : 'tool uses';
             const agentLine = `   ${branch} ${item.description} · ${String(item.toolCount)} ${toolWord}${tokenStr}`;
             lines.push(agentLine);
@@ -276,7 +277,7 @@ export class LiveRegion {
         }
         // Hint at the end
         if (!allDone) {
-            lines.push(`   ${s.muted('ctrl+b to run in background')}`);
+            // ctrl+b background: coming soon
         }
         return lines;
     }
@@ -323,7 +324,7 @@ export class LiveRegion {
         }
         // Hint for running bash
         if (item.status === 'running') {
-            lines.push(`     ${s.muted('ctrl+b to run in background')}`);
+            // ctrl+b background: coming soon
         }
         return lines;
     }
@@ -352,15 +353,6 @@ export class LiveRegion {
     // =========================================================================
     // Helpers
     // =========================================================================
-    /**
-     * Format token count for display (e.g., 18.1k)
-     */
-    formatTokens(tokens) {
-        if (tokens >= 1000) {
-            return `${(tokens / 1000).toFixed(1)}k`;
-        }
-        return String(tokens);
-    }
     /**
      * Truncate a line to fit within width.
      */

package/dist/ui/mascot/renderer.d.ts

@@ -16,4 +16,4 @@ export declare function combineHorizontally(left: string[], right: string[], gap
  * @param version - Version string to append to logo
  * @param projectName - Optional active project name to show
  */
-export declare function renderMascotWithLogo(mascotSetting: MascotSetting, version: string, projectName?: string | null): string[];
+export declare function renderMascotWithLogo(mascotSetting: MascotSetting, version: string, projectName?: string | null, highlights?: string[]): string[];

package/dist/ui/mascot/renderer.js

@@ -5,6 +5,11 @@
  */
 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 = [
     "   ___  ___  _ __ ___  _ __ (_) |_ __",
@@ -36,7 +41,7 @@ export function combineHorizontally(left, right, gap) {
  * @param version - Version string to append to logo
  * @param projectName - Optional active project name to show
  */
-export function renderMascotWithLogo(mascotSetting, version, projectName) {
+export function renderMascotWithLogo(mascotSetting, version, projectName, highlights) {
     const s = getStyles();
     // Get mascot expression (or null for 'none')
     const mascotLines = getExpressionForSetting(mascotSetting);
@@ -65,7 +70,7 @@ export function renderMascotWithLogo(mascotSetting, version, projectName) {
         result.push(`Project: ${projectName}`);
     }
     // Apply colors: mascot gets secondary color, logo gets accent
-    return result.map((line, index) => {
+    const colored = result.map((line, index) => {
         if (!mascotLines) {
             // No mascot - color the logo with accent
             if (index < logoWithVersion.length) {
@@ -94,4 +99,34 @@ export function renderMascotWithLogo(mascotSetting, version, projectName) {
         }
         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;