@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/guide/tutorial-helpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Tutorial Helpers
+ *
+ * Functions to convert shared content into styled tutorial pages.
+ * These helpers apply consistent styling to plain text content.
+ */
+import type { ThemeStyleFunctions } from '../themes/index.js';
+import type { TutorialPage } from '../ui/overlay/data/tutorial-types.js';
+import type { ContentTopic, ContentSection } from './shared-content.js';
+/**
+ * Style a command (e.g., /help, /design).
+ */
+export declare function styleCommand(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Style a keyboard shortcut (e.g., [n], Esc, Tab).
+ */
+export declare function styleShortcut(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Style an agent reference (e.g., $arch, $pm).
+ */
+export declare function styleAgent(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Style a file reference (e.g., @src/index.ts).
+ */
+export declare function styleFileRef(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Style a path or filename.
+ */
+export declare function stylePath(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Apply all styling to a line of text.
+ */
+export declare function styleLine(text: string, s: ThemeStyleFunctions): string;
+/**
+ * Convert a content section to styled lines.
+ */
+export declare function sectionToLines(section: ContentSection, s: ThemeStyleFunctions, indent?: string): string[];
+/**
+ * Convert a content topic to a single tutorial page.
+ */
+export declare function topicToPage(topic: ContentTopic, s: ThemeStyleFunctions): TutorialPage;
+/**
+ * Convert a content topic to multiple tutorial pages (one per section).
+ */
+export declare function topicToPages(topic: ContentTopic, s: ThemeStyleFunctions): TutorialPage[];
+/**
+ * Convert multiple content topics to a single tutorial page each.
+ */
+export declare function topicsToPages(topicIds: string[], topics: ContentTopic[], s: ThemeStyleFunctions): TutorialPage[];
+/**
+ * Build a tutorial page with custom styling on top of shared content.
+ * Allows mixing shared content with custom tutorial-specific elements.
+ */
+export declare function buildHybridPage(title: string, sections: ContentSection[], s: ThemeStyleFunctions, options?: {
+    prefix?: string[];
+    suffix?: string[];
+}): TutorialPage;

package/dist/guide/tutorial-helpers.js

@@ -0,0 +1,147 @@
+/**
+ * Tutorial Helpers
+ *
+ * Functions to convert shared content into styled tutorial pages.
+ * These helpers apply consistent styling to plain text content.
+ */
+// =============================================================================
+// Text Styling Helpers
+// =============================================================================
+/**
+ * Style a command (e.g., /help, /design).
+ */
+export function styleCommand(text, s) {
+    return text.replace(/\/\w+/g, (match) => s.primary(match));
+}
+/**
+ * Style a keyboard shortcut (e.g., [n], Esc, Tab).
+ */
+export function styleShortcut(text, s) {
+    // Style bracketed shortcuts like [n], [p]
+    let result = text.replace(/\[([a-z0-9])\]/gi, (_, key) => s.primary(`[${key}]`));
+    // Style named keys like Esc, Tab, Enter
+    result = result.replace(/\b(Esc|Tab|Enter|↑|↓|←|→)\b/g, (match) => s.primary(match));
+    return result;
+}
+/**
+ * Style an agent reference (e.g., $arch, $pm).
+ */
+export function styleAgent(text, s) {
+    return text.replace(/\$\w+/g, (match) => s.primary(match));
+}
+/**
+ * Style a file reference (e.g., @src/index.ts).
+ */
+export function styleFileRef(text, s) {
+    return text.replace(/@[\w/.]+/g, (match) => s.primary(match));
+}
+/**
+ * Style a path or filename.
+ */
+export function stylePath(text, s) {
+    // Style paths like COMPILR.md, .compilr/, src/
+    return text.replace(/(?:\.?[\w-]+\/)+[\w.-]*|[\w-]+\.(md|ts|js|json)/g, (match) => s.primary(match));
+}
+/**
+ * Apply all styling to a line of text.
+ */
+export function styleLine(text, s) {
+    let result = text;
+    result = styleCommand(result, s);
+    result = styleShortcut(result, s);
+    result = styleAgent(result, s);
+    result = styleFileRef(result, s);
+    result = stylePath(result, s);
+    // Style "TIP:" prefix
+    if (result.startsWith('TIP:')) {
+        result = s.warning('TIP:') + result.slice(4);
+    }
+    return result;
+}
+// =============================================================================
+// Section to Lines Conversion
+// =============================================================================
+/**
+ * Convert a content section to styled lines.
+ */
+export function sectionToLines(section, s, indent = '    ') {
+    const lines = [];
+    if (section.title) {
+        lines.push(`  ${s.secondary(section.title)}`);
+        lines.push('');
+    }
+    for (const item of section.items) {
+        const styledItem = styleLine(item, s);
+        lines.push(`${indent}${styledItem}`);
+    }
+    return lines;
+}
+// =============================================================================
+// Topic to Tutorial Page Conversion
+// =============================================================================
+/**
+ * Convert a content topic to a single tutorial page.
+ */
+export function topicToPage(topic, s) {
+    const lines = [''];
+    for (const section of topic.sections) {
+        lines.push(...sectionToLines(section, s));
+        lines.push('');
+    }
+    return {
+        title: topic.title,
+        lines,
+    };
+}
+/**
+ * Convert a content topic to multiple tutorial pages (one per section).
+ */
+export function topicToPages(topic, s) {
+    const pages = [];
+    for (let i = 0; i < topic.sections.length; i++) {
+        const section = topic.sections[i];
+        const lines = ['', ...sectionToLines(section, s), ''];
+        pages.push({
+            title: section.title || topic.title,
+            lines,
+        });
+    }
+    return pages;
+}
+/**
+ * Convert multiple content topics to a single tutorial page each.
+ */
+export function topicsToPages(topicIds, topics, s) {
+    const pages = [];
+    for (const id of topicIds) {
+        const topic = topics.find((t) => t.id === id);
+        if (topic) {
+            pages.push(topicToPage(topic, s));
+        }
+    }
+    return pages;
+}
+// =============================================================================
+// Hybrid Page Builder
+// =============================================================================
+/**
+ * Build a tutorial page with custom styling on top of shared content.
+ * Allows mixing shared content with custom tutorial-specific elements.
+ */
+export function buildHybridPage(title, sections, s, options) {
+    const lines = [''];
+    // Add prefix lines
+    if (options?.prefix) {
+        lines.push(...options.prefix, '');
+    }
+    // Add sections
+    for (const section of sections) {
+        lines.push(...sectionToLines(section, s));
+        lines.push('');
+    }
+    // Add suffix lines
+    if (options?.suffix) {
+        lines.push(...options.suffix, '');
+    }
+    return { title, lines };
+}

package/dist/handlers/ask-user-handlers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ask-user handler factories — extracted from index.ts.
+ *
+ * Registers the `ask_user` and `ask_user_simple` handlers.
+ * The deps object is SharedState passed by reference, so live mutations
+ * (e.g. overlay callbacks wired after REPL starts) work exactly as before.
+ */
+import { type AskUserQuestion } from '../shared-handlers.js';
+export interface AskUserHandlerDeps {
+    flushTextBuffer?: () => void;
+    getActiveBackgroundAgentId?: () => string | null;
+    isBackgroundAgent?: (agentId?: string) => boolean;
+    getBackgroundAgentInfo?: (agentId: string) => {
+        mascot: string;
+    } | null;
+    showAskUserOverlayV2?: (options: {
+        questions: AskUserQuestion[];
+        context?: string;
+    }) => Promise<{
+        answers: Record<string, string | string[]>;
+        skipped: string[];
+    }>;
+    showAskUserSimpleOverlayV2?: (options: {
+        question: string;
+        options?: string[];
+        allowCustom?: boolean;
+    }) => Promise<{
+        answer: string;
+        skipped: boolean;
+    }>;
+}
+export declare function registerAskUserHandlers(deps: AskUserHandlerDeps): void;

package/dist/handlers/ask-user-handlers.js

@@ -0,0 +1,104 @@
+/**
+ * Ask-user handler factories — extracted from index.ts.
+ *
+ * Registers the `ask_user` and `ask_user_simple` handlers.
+ * The deps object is SharedState passed by reference, so live mutations
+ * (e.g. overlay callbacks wired after REPL starts) work exactly as before.
+ */
+import { registerAskUserHandler, registerAskUserSimpleHandler, } from '../shared-handlers.js';
+import { getPendingRequestsManager } from '../multi-agent/index.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function registerAskUserHandlers(deps) {
+    // Register ask_user handler that coordinates with footer
+    registerAskUserHandler(async (input) => {
+        // Wait for event loop to process any pending tool_end events
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush any accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Phase 3b: Background agent question handling
+        // If this request comes from a background agent, enqueue it instead of showing overlay
+        const backgroundAgentId = deps.getActiveBackgroundAgentId?.();
+        if (backgroundAgentId && deps.isBackgroundAgent?.(backgroundAgentId)) {
+            const agentInfo = deps.getBackgroundAgentInfo?.(backgroundAgentId);
+            const pendingManager = getPendingRequestsManager();
+            // Build prompt from all questions for display in /pending
+            const questionTexts = input.questions.map(q => q.question);
+            const prompt = questionTexts.length === 1
+                ? questionTexts[0]
+                : questionTexts.map((q, i) => `${String(i + 1)}. ${q}`).join(' | ');
+            try {
+                const response = await pendingManager.enqueue({
+                    agentId: backgroundAgentId,
+                    mascot: agentInfo?.mascot ?? '[•_•]',
+                    type: 'question',
+                    prompt,
+                    context: {
+                        toolType: 'ask_user',
+                        originalInput: input,
+                    },
+                });
+                // Response comes from the standard overlay shown via /pending
+                return response.overlayResult;
+            }
+            catch {
+                // Request was cancelled/rejected - skip all questions
+                return {
+                    answers: {},
+                    skipped: input.questions.map(q => q.id),
+                };
+            }
+        }
+        // Use TerminalUI overlay system
+        if (!deps.showAskUserOverlayV2) {
+            throw new Error('ask_user overlay not initialized');
+        }
+        return deps.showAskUserOverlayV2({
+            questions: input.questions,
+            context: input.context,
+        });
+    });
+    // Register ask_user_simple handler for smaller models (flat schema)
+    registerAskUserSimpleHandler(async (input) => {
+        // Wait for event loop to process any pending tool_end events
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush any accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Phase 3b: Background agent question handling
+        // If this request comes from a background agent, enqueue it instead of showing overlay
+        const backgroundAgentId = deps.getActiveBackgroundAgentId?.();
+        if (backgroundAgentId && deps.isBackgroundAgent?.(backgroundAgentId)) {
+            const agentInfo = deps.getBackgroundAgentInfo?.(backgroundAgentId);
+            const pendingManager = getPendingRequestsManager();
+            try {
+                const response = await pendingManager.enqueue({
+                    agentId: backgroundAgentId,
+                    mascot: agentInfo?.mascot ?? '[•_•]',
+                    type: 'question',
+                    prompt: input.question,
+                    options: input.options,
+                    context: {
+                        toolType: 'ask_user_simple',
+                        originalInput: input,
+                    },
+                });
+                // Response comes from the standard overlay shown via /pending
+                return response.overlayResult;
+            }
+            catch {
+                // Request was cancelled/rejected
+                return { answer: '', skipped: true };
+            }
+        }
+        // Use TerminalUI overlay system
+        if (!deps.showAskUserSimpleOverlayV2) {
+            throw new Error('ask_user_simple overlay not initialized');
+        }
+        return deps.showAskUserSimpleOverlayV2({
+            question: input.question,
+            options: input.options,
+            allowCustom: input.allowCustom,
+        });
+    });
+}

package/dist/handlers/delegation-handlers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Delegation handler factories — extracted from index.ts.
+ *
+ * Registers the `delegate`, `delegate_background`, and `handoff` handlers.
+ * The deps object is SharedState passed by reference, so live mutations
+ * (e.g. team set after REPL starts) work exactly as before.
+ */
+import type { AgentTeam } from '../multi-agent/index.js';
+export interface DelegationHandlerDeps {
+    flushTextBuffer?: () => void;
+    team?: AgentTeam;
+    pendingDelegation?: {
+        agentId: string;
+        task: string;
+    } | null;
+    showDelegateOverlayV2?: (options: {
+        agentId: string;
+        agentDisplayName: string;
+        task: string;
+        reason?: string;
+    }) => Promise<{
+        approved: boolean;
+    }>;
+    showAskUserSimpleOverlayV2?: (options: {
+        question: string;
+        options?: string[];
+        allowCustom?: boolean;
+    }) => Promise<{
+        answer: string;
+        skipped: boolean;
+    }>;
+    runBackgroundDelegation?: (agentId: string, message: string) => 'running' | 'queued' | null;
+}
+export declare function registerDelegationHandlers(deps: DelegationHandlerDeps): void;

package/dist/handlers/delegation-handlers.js

@@ -0,0 +1,291 @@
+/**
+ * Delegation handler factories — extracted from index.ts.
+ *
+ * Registers the `delegate`, `delegate_background`, and `handoff` handlers.
+ * The deps object is SharedState passed by reference, so live mutations
+ * (e.g. team set after REPL starts) work exactly as before.
+ */
+import { registerDelegateHandler, registerDelegateBackgroundHandler, registerHandoffHandler, } from '../shared-handlers.js';
+import { getDelegationTracker } from '../multi-agent/delegation-tracker.js';
+import chalk from 'chalk';
+import { truncate } from '../ui/base/index.js';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function registerDelegationHandlers(deps) {
+    // Register delegate handler for multi-agent delegation
+    registerDelegateHandler(async (input) => {
+        // Wait for event loop to process any pending tool_end events
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush any accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Validate team exists
+        if (!deps.team) {
+            return {
+                success: false,
+                declined: false,
+                error: 'Multi-agent team not initialized. Delegation requires an active team.',
+            };
+        }
+        // Validate target agent exists
+        const targetAgent = deps.team.get(input.agentId);
+        if (!targetAgent) {
+            return {
+                success: false,
+                declined: false,
+                error: `Agent '${input.agentId}' not found in team. Available agents: ${deps.team.getAgentIds().join(', ')}`,
+            };
+        }
+        // Validate coordinator is active (only coordinator can delegate)
+        if (!deps.team.isActiveCoordinator()) {
+            return {
+                success: false,
+                declined: false,
+                error: 'Only the coordinator can delegate tasks. Use $<agent> to switch agents manually.',
+            };
+        }
+        // V2 mode: use TerminalUI overlay for approval
+        if (deps.showDelegateOverlayV2) {
+            const result = await deps.showDelegateOverlayV2({
+                agentId: input.agentId,
+                agentDisplayName: targetAgent.displayName,
+                task: input.task,
+                reason: input.reason,
+            });
+            if (!result.approved) {
+                return {
+                    success: false,
+                    declined: true,
+                };
+            }
+            // Set pending delegation - REPL will handle the switch after agent finishes
+            deps.pendingDelegation = {
+                agentId: input.agentId,
+                task: input.task,
+            };
+            return {
+                success: true,
+                declined: false,
+            };
+        }
+        // Fallback: no V2 overlay available, use simple ask_user_simple handler
+        const askHandler = deps.showAskUserSimpleOverlayV2;
+        if (askHandler) {
+            const question = input.reason
+                ? `Delegate to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Reason: ${input.reason}`)}\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`
+                : `Delegate to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`;
+            const result = await askHandler({
+                question,
+                options: ['Yes', 'No'],
+                allowCustom: false,
+            });
+            if (result.skipped || result.answer === 'No') {
+                return {
+                    success: false,
+                    declined: true,
+                };
+            }
+            // Set pending delegation
+            deps.pendingDelegation = {
+                agentId: input.agentId,
+                task: input.task,
+            };
+            return {
+                success: true,
+                declined: false,
+            };
+        }
+        // No handler available
+        return {
+            success: false,
+            declined: false,
+            error: 'Delegation UI not available. Ensure you are running in interactive mode.',
+        };
+    });
+    // Register delegate_background handler for coordinator mode
+    registerDelegateBackgroundHandler(async (input) => {
+        // Yield to event loop (consistent with delegate handler pattern)
+        await new Promise((resolve) => setImmediate(resolve));
+        // Validate team exists
+        if (!deps.team) {
+            return {
+                delegationId: '',
+                status: 'running',
+                error: 'Multi-agent team not initialized. Background delegation requires an active team.',
+            };
+        }
+        // Validate target agent exists
+        const targetAgent = deps.team.get(input.agentId);
+        if (!targetAgent) {
+            return {
+                delegationId: '',
+                status: 'running',
+                error: `Agent '${input.agentId}' not found in team. Available agents: ${deps.team.getAgentIds().join(', ')}`,
+            };
+        }
+        // Validate coordinator is active
+        if (!deps.team.isActiveCoordinator()) {
+            return {
+                delegationId: '',
+                status: 'running',
+                error: 'Only the coordinator can use delegate_background.',
+            };
+        }
+        // Validate background delegation callback is available
+        if (!deps.runBackgroundDelegation) {
+            return {
+                delegationId: '',
+                status: 'running',
+                error: 'Background delegation not available. Ensure REPL is initialized.',
+            };
+        }
+        // Create delegation in tracker
+        const tracker = getDelegationTracker();
+        const delegation = tracker.create({
+            coordinatorId: 'default',
+            targetAgentId: input.agentId,
+            task: input.task,
+            expectedOutput: input.expectedOutput,
+            todoIndex: input.todoIndex,
+        });
+        // Build delegation preamble
+        const preambleLines = [
+            '[DELEGATION from coordinator]',
+            `Delegation ID: ${delegation.id}`,
+        ];
+        if (input.todoIndex !== undefined) {
+            preambleLines.push(`Associated todo: #${String(input.todoIndex)}`);
+        }
+        if (input.expectedOutput) {
+            preambleLines.push(`Expected output: ${input.expectedOutput}`);
+        }
+        preambleLines.push('', 'SCOPE: Focus ONLY on the task below. Do NOT pick up, start, or ask about', 'other tasks from the todo list, even if they appear unassigned. When your', 'task is complete, report your results and stop.', '', 'Task:', input.task, '', 'When done, save your key output as an artifact so the coordinator can reference it.');
+        if (input.todoIndex !== undefined) {
+            preambleLines.push(`When complete, mark todo #${String(input.todoIndex)} as done using the todo_update tool.`);
+        }
+        const message = preambleLines.join('\n');
+        // Run the specialist in background (or queue if busy)
+        const runResult = deps.runBackgroundDelegation(input.agentId, message);
+        if (runResult === null) {
+            tracker.fail(delegation.id, 'Failed to start background agent');
+            return {
+                delegationId: delegation.id,
+                status: 'running',
+                error: 'Failed to start background agent. Agent may not be available.',
+            };
+        }
+        // Update delegation status
+        if (runResult === 'running') {
+            tracker.updateStatus(delegation.id, 'running');
+        }
+        // 'queued' stays as 'pending' in the tracker
+        return {
+            delegationId: delegation.id,
+            status: runResult,
+        };
+    });
+    // Register handoff handler for specialist-to-specialist handoff
+    registerHandoffHandler(async (input) => {
+        // Wait for event loop to process any pending tool_end events
+        await new Promise((resolve) => setImmediate(resolve));
+        // Flush any accumulated text BEFORE showing the overlay
+        deps.flushTextBuffer?.();
+        // Validate team exists
+        if (!deps.team) {
+            return {
+                success: false,
+                declined: false,
+                error: 'Multi-agent team not initialized. Handoff requires an active team.',
+            };
+        }
+        // Validate target agent exists
+        const targetAgent = deps.team.get(input.agentId);
+        if (!targetAgent) {
+            return {
+                success: false,
+                declined: false,
+                error: `Agent '${input.agentId}' not found in team. Available agents: ${deps.team.getAgentIds().join(', ')}`,
+            };
+        }
+        // Determine source agent (the one performing the handoff)
+        const sourceAgentId = deps.team.activeAgentId;
+        // Cannot hand off to yourself
+        if (input.agentId === sourceAgentId) {
+            return {
+                success: false,
+                declined: false,
+                error: 'Cannot hand off to yourself.',
+            };
+        }
+        // One-hop rule: if this agent was itself handed a task, deny re-handoff
+        // Exception: handing back to coordinator (default) is always allowed
+        const isCoordinatorTarget = deps.team.isCoordinator(input.agentId);
+        if (deps.team.wasHandedTo(sourceAgentId) && !isCoordinatorTarget) {
+            const handoffSource = deps.team.getHandoffSource(sourceAgentId);
+            return {
+                success: false,
+                declined: false,
+                error: `You were handed this task by $${handoffSource ?? 'unknown'}. ` +
+                    'Complete it or hand it back to the coordinator ($default). ' +
+                    'You cannot re-hand off to another specialist.',
+            };
+        }
+        // Check auto-approve: if the source agent has autoApproveHandoff, skip overlay
+        const sourceTeamAgent = deps.team.get(sourceAgentId);
+        const autoApprove = sourceTeamAgent?.autoApproveHandoff === true;
+        if (!autoApprove) {
+            // Show approval overlay (reuse delegate overlay)
+            if (deps.showDelegateOverlayV2) {
+                const result = await deps.showDelegateOverlayV2({
+                    agentId: input.agentId,
+                    agentDisplayName: targetAgent.displayName,
+                    task: input.task,
+                    reason: input.reason,
+                });
+                if (!result.approved) {
+                    return {
+                        success: false,
+                        declined: true,
+                    };
+                }
+            }
+            else if (deps.showAskUserSimpleOverlayV2) {
+                // Fallback: use simple ask_user_simple handler
+                const question = input.reason
+                    ? `Hand off to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Reason: ${input.reason}`)}\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`
+                    : `Hand off to $${input.agentId} (${targetAgent.displayName})?\n${chalk.dim(`Task: ${truncate(input.task, 100)}`)}`;
+                const result = await deps.showAskUserSimpleOverlayV2({
+                    question,
+                    options: ['Yes', 'No'],
+                    allowCustom: false,
+                });
+                if (result.skipped || result.answer === 'No') {
+                    return {
+                        success: false,
+                        declined: true,
+                    };
+                }
+            }
+            else {
+                // No handler available
+                return {
+                    success: false,
+                    declined: false,
+                    error: 'Handoff UI not available. Ensure you are running in interactive mode.',
+                };
+            }
+        }
+        // Record the handoff for one-hop tracking
+        deps.team.recordHandoff(input.agentId, sourceAgentId);
+        // Set pending delegation - REPL will handle the switch after agent finishes
+        // Reuses the same pendingDelegation mechanism as delegate
+        deps.pendingDelegation = {
+            agentId: input.agentId,
+            task: input.task,
+        };
+        return {
+            success: true,
+            declined: false,
+        };
+    });
+}