@compilr-dev/agents 0.2.1 → 0.3.1

package/dist/tools/builtin/ask-user-simple.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Ask User Simple Tool - Single question with simple string options
+ *
+ * A simplified version of ask_user for single questions with string options.
+ * Preferred over ask_user when you only need to ask one simple question.
+ *
+ * Features:
+ * - Single question
+ * - Simple string options (no value/label distinction)
+ * - Default value support
+ * - Factory function for custom implementations
+ */
+import type { Tool } from '../types.js';
+/**
+ * Input parameters for ask_user_simple tool
+ */
+export interface AskUserSimpleInput {
+    /** The question to ask */
+    question: string;
+    /** Simple string options to choose from */
+    options: string[];
+    /** Default value if user skips (optional) */
+    default?: string;
+}
+/**
+ * Result from ask_user_simple tool
+ */
+export interface AskUserSimpleResult {
+    /** The selected answer */
+    answer: string;
+    /** Whether the default was used */
+    usedDefault?: boolean;
+}
+/**
+ * Options for creating custom ask_user_simple tool
+ */
+export interface AskUserSimpleToolOptions {
+    /**
+     * Custom handler for asking the question.
+     * If not provided, uses readline-based implementation.
+     */
+    onAsk?: (question: string, options: string[], defaultValue?: string) => Promise<AskUserSimpleResult>;
+}
+/**
+ * Default ask_user_simple tool using readline for basic CLI interaction.
+ * Use createAskUserSimpleTool() for custom implementations.
+ */
+export declare const askUserSimpleTool: Tool<AskUserSimpleInput>;
+/**
+ * Create a custom ask_user_simple tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskSimple = createAskUserSimpleTool({
+ *   onAsk: async (question, options, defaultValue) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserSimpleOverlay({ question, options, defaultValue });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskSimple);
+ * ```
+ */
+export declare function createAskUserSimpleTool(options?: AskUserSimpleToolOptions): Tool<AskUserSimpleInput>;

package/dist/tools/builtin/ask-user-simple.js

@@ -0,0 +1,149 @@
+/**
+ * Ask User Simple Tool - Single question with simple string options
+ *
+ * A simplified version of ask_user for single questions with string options.
+ * Preferred over ask_user when you only need to ask one simple question.
+ *
+ * Features:
+ * - Single question
+ * - Simple string options (no value/label distinction)
+ * - Default value support
+ * - Factory function for custom implementations
+ */
+/* eslint-disable no-console -- Intentional console output for fallback CLI prompts */
+import * as readline from 'readline';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+// =============================================================================
+// Default Implementation (readline-based)
+// =============================================================================
+async function askSimpleWithReadline(question, options, defaultValue) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        // Print question and options
+        console.log(`\n${question}`);
+        options.forEach((opt, i) => {
+            console.log(`  ${String(i + 1)}. ${opt}`);
+        });
+        if (defaultValue) {
+            console.log(`  (Press Enter for default: ${defaultValue})`);
+        }
+        rl.question('Choice: ', (answer) => {
+            rl.close();
+            const trimmed = answer.trim();
+            // Empty input - use default or first option
+            if (!trimmed) {
+                if (defaultValue) {
+                    resolve({ answer: defaultValue, usedDefault: true });
+                }
+                else {
+                    resolve({ answer: options[0], usedDefault: true });
+                }
+                return;
+            }
+            // Try to parse as number
+            const idx = parseInt(trimmed, 10) - 1;
+            if (idx >= 0 && idx < options.length) {
+                resolve({ answer: options[idx] });
+                return;
+            }
+            // Try to match option text (case-insensitive)
+            const lowerInput = trimmed.toLowerCase();
+            const matched = options.find((opt) => opt.toLowerCase() === lowerInput);
+            if (matched) {
+                resolve({ answer: matched });
+                return;
+            }
+            // No match - use default or first option
+            if (defaultValue) {
+                resolve({ answer: defaultValue, usedDefault: true });
+            }
+            else {
+                resolve({ answer: options[0], usedDefault: true });
+            }
+        });
+    });
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+/**
+ * Default ask_user_simple tool using readline for basic CLI interaction.
+ * Use createAskUserSimpleTool() for custom implementations.
+ */
+export const askUserSimpleTool = defineTool({
+    name: 'ask_user_simple',
+    description: 'Ask a single simple question with string options. ' +
+        'Use this instead of ask_user when you only need one question. ' +
+        'Provide 2-4 clear, concise options. ' +
+        'The user can select by number or by typing the option text.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            question: {
+                type: 'string',
+                description: 'The question to ask the user',
+            },
+            options: {
+                type: 'array',
+                description: 'Available options (2-4 options)',
+                minItems: 2,
+                maxItems: 4,
+                items: {
+                    type: 'string',
+                },
+            },
+            default: {
+                type: 'string',
+                description: 'Default value if user skips',
+            },
+        },
+        required: ['question', 'options'],
+    },
+    execute: async (input) => {
+        try {
+            const result = await askSimpleWithReadline(input.question, input.options, input.default);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a custom ask_user_simple tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskSimple = createAskUserSimpleTool({
+ *   onAsk: async (question, options, defaultValue) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserSimpleOverlay({ question, options, defaultValue });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskSimple);
+ * ```
+ */
+export function createAskUserSimpleTool(options = {}) {
+    const handler = options.onAsk ?? askSimpleWithReadline;
+    return defineTool({
+        name: 'ask_user_simple',
+        description: askUserSimpleTool.definition.description,
+        inputSchema: askUserSimpleTool.definition.inputSchema,
+        execute: async (input) => {
+            try {
+                const result = await handler(input.question, input.options, input.default);
+                return createSuccessResult(result);
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}

package/dist/tools/builtin/ask-user.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Ask User Tool - Gather input from user via questions with options
+ *
+ * This tool allows the agent to ask the user questions with predefined options.
+ * The default implementation uses Node.js readline for basic CLI interaction.
+ * Consumers (like CLI apps) can override with custom UI implementations.
+ *
+ * Features:
+ * - Multiple questions in a single call
+ * - Options with labels, values, and descriptions
+ * - Multi-select support
+ * - Factory function for custom implementations
+ */
+import type { Tool } from '../types.js';
+/**
+ * A single option for a question
+ */
+export interface AskUserOption {
+    /** Display text for the option */
+    label: string;
+    /** Value returned when this option is selected */
+    value: string;
+    /** Optional description/explanation */
+    description?: string;
+}
+/**
+ * A question to ask the user
+ */
+export interface AskUserQuestion {
+    /** Unique identifier for this question */
+    id: string;
+    /** The question text */
+    question: string;
+    /** Available options to choose from */
+    options: AskUserOption[];
+    /** Allow multiple selections (default: false) */
+    multiSelect?: boolean;
+}
+/**
+ * Input parameters for ask_user tool
+ */
+export interface AskUserInput {
+    /** Questions to ask the user (1-4 questions) */
+    questions: AskUserQuestion[];
+}
+/**
+ * Result from ask_user tool
+ */
+export interface AskUserResult {
+    /** Answers keyed by question ID */
+    answers: Record<string, string | string[]>;
+    /** Question IDs that were skipped */
+    skipped: string[];
+}
+/**
+ * Options for creating custom ask_user tool
+ */
+export interface AskUserToolOptions {
+    /**
+     * Custom handler for asking questions.
+     * If not provided, uses readline-based implementation.
+     */
+    onAsk?: (questions: AskUserQuestion[]) => Promise<AskUserResult>;
+}
+/**
+ * Default ask_user tool using readline for basic CLI interaction.
+ * Use createAskUserTool() for custom implementations.
+ */
+export declare const askUserTool: Tool<AskUserInput>;
+/**
+ * Create a custom ask_user tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskUser = createAskUserTool({
+ *   onAsk: async (questions) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserOverlay({ questions });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskUser);
+ * ```
+ */
+export declare function createAskUserTool(options?: AskUserToolOptions): Tool<AskUserInput>;

package/dist/tools/builtin/ask-user.js

@@ -0,0 +1,195 @@
+/**
+ * Ask User Tool - Gather input from user via questions with options
+ *
+ * This tool allows the agent to ask the user questions with predefined options.
+ * The default implementation uses Node.js readline for basic CLI interaction.
+ * Consumers (like CLI apps) can override with custom UI implementations.
+ *
+ * Features:
+ * - Multiple questions in a single call
+ * - Options with labels, values, and descriptions
+ * - Multi-select support
+ * - Factory function for custom implementations
+ */
+/* eslint-disable no-console -- Intentional console output for fallback CLI prompts */
+import * as readline from 'readline';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+// =============================================================================
+// Default Implementation (readline-based)
+// =============================================================================
+async function askWithReadline(questions) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const askQuestion = (prompt) => {
+        return new Promise((resolve) => {
+            rl.question(prompt, (answer) => {
+                resolve(answer);
+            });
+        });
+    };
+    const answers = {};
+    const skipped = [];
+    try {
+        for (const q of questions) {
+            // Print question
+            console.log(`\n${q.question}`);
+            // Print options
+            q.options.forEach((opt, i) => {
+                const desc = opt.description ? ` - ${opt.description}` : '';
+                console.log(`  ${String(i + 1)}. ${opt.label}${desc}`);
+            });
+            if (q.multiSelect) {
+                console.log('  (Enter numbers separated by commas, or press Enter to skip)');
+            }
+            // Get answer
+            const prompt = q.multiSelect ? 'Choices: ' : 'Choice: ';
+            const answer = await askQuestion(prompt);
+            if (!answer.trim()) {
+                skipped.push(q.id);
+                continue;
+            }
+            if (q.multiSelect) {
+                // Parse comma-separated numbers
+                const indices = answer
+                    .split(',')
+                    .map((s) => parseInt(s.trim(), 10) - 1)
+                    .filter((i) => i >= 0 && i < q.options.length);
+                if (indices.length > 0) {
+                    answers[q.id] = indices.map((i) => q.options[i].value);
+                }
+                else {
+                    skipped.push(q.id);
+                }
+            }
+            else {
+                // Single selection
+                const idx = parseInt(answer.trim(), 10) - 1;
+                if (idx >= 0 && idx < q.options.length) {
+                    answers[q.id] = q.options[idx].value;
+                }
+                else {
+                    // Invalid input - try to use as raw value or skip
+                    skipped.push(q.id);
+                }
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+    return { answers, skipped };
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+/**
+ * Default ask_user tool using readline for basic CLI interaction.
+ * Use createAskUserTool() for custom implementations.
+ */
+export const askUserTool = defineTool({
+    name: 'ask_user',
+    description: 'Ask the user one or more questions with predefined options. ' +
+        'Use this to gather preferences, make decisions, or get user input during workflows. ' +
+        'Each question should have 2-4 clear options. ' +
+        'Prefer ask_user_simple for single simple questions.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            questions: {
+                type: 'array',
+                description: 'Questions to ask (1-4 questions)',
+                minItems: 1,
+                maxItems: 4,
+                items: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'string',
+                            description: 'Unique identifier for this question',
+                        },
+                        question: {
+                            type: 'string',
+                            description: 'The question text to display',
+                        },
+                        options: {
+                            type: 'array',
+                            description: 'Available options (2-4 options)',
+                            minItems: 2,
+                            maxItems: 4,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    label: {
+                                        type: 'string',
+                                        description: 'Display text for this option',
+                                    },
+                                    value: {
+                                        type: 'string',
+                                        description: 'Value returned when selected',
+                                    },
+                                    description: {
+                                        type: 'string',
+                                        description: 'Optional explanation of this option',
+                                    },
+                                },
+                                required: ['label', 'value'],
+                            },
+                        },
+                        multiSelect: {
+                            type: 'boolean',
+                            description: 'Allow selecting multiple options',
+                        },
+                    },
+                    required: ['id', 'question', 'options'],
+                },
+            },
+        },
+        required: ['questions'],
+    },
+    execute: async (input) => {
+        try {
+            const result = await askWithReadline(input.questions);
+            return createSuccessResult(result);
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a custom ask_user tool with your own UI implementation.
+ *
+ * @example
+ * ```typescript
+ * const customAskUser = createAskUserTool({
+ *   onAsk: async (questions) => {
+ *     // Show fancy UI overlay
+ *     const overlay = new AskUserOverlay({ questions });
+ *     return await ui.showOverlay(overlay);
+ *   }
+ * });
+ * agent.registerTool(customAskUser);
+ * ```
+ */
+export function createAskUserTool(options = {}) {
+    const handler = options.onAsk ?? askWithReadline;
+    return defineTool({
+        name: 'ask_user',
+        description: askUserTool.definition.description,
+        inputSchema: askUserTool.definition.inputSchema,
+        execute: async (input) => {
+            try {
+                const result = await handler(input.questions);
+                return createSuccessResult(result);
+            }
+            catch (error) {
+                return createErrorResult(error instanceof Error ? error.message : String(error));
+            }
+        },
+    });
+}

package/dist/tools/builtin/backlog.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Backlog Tools - File-based project backlog management
+ *
+ * Provides backlog_read and backlog_write tools for managing project backlogs.
+ * Uses a JSON file stored in .compilr/backlog.json (or backlog.json in project root).
+ *
+ * Features:
+ * - Read with filters (status, type, search, limit)
+ * - Write/update individual items or full backlog
+ * - Support for common item types (feature, bug, chore, spike)
+ * - Priority levels (critical, high, medium, low)
+ */
+import type { Tool } from '../types.js';
+/**
+ * Status of a backlog item
+ */
+export type BacklogStatus = 'backlog' | 'in-progress' | 'done' | 'blocked';
+/**
+ * Type of backlog item
+ */
+export type BacklogItemType = 'feature' | 'bug' | 'chore' | 'spike';
+/**
+ * Priority level
+ */
+export type BacklogPriority = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * A backlog item
+ */
+export interface BacklogItem {
+    /** Unique identifier (e.g., "FEAT-001", "BUG-002") */
+    id: string;
+    /** Type of item */
+    type: BacklogItemType;
+    /** Short title */
+    title: string;
+    /** Detailed description (optional) */
+    description?: string;
+    /** Current status */
+    status: BacklogStatus;
+    /** Priority level (optional, defaults to medium) */
+    priority?: BacklogPriority;
+    /** Acceptance criteria (optional) */
+    acceptanceCriteria?: string[];
+    /** Dependencies on other items (optional) */
+    dependencies?: string[];
+    /** Labels/tags (optional) */
+    labels?: string[];
+    /** Created timestamp */
+    createdAt?: string;
+    /** Last updated timestamp */
+    updatedAt?: string;
+}
+/**
+ * Input parameters for backlog_read tool
+ */
+export interface BacklogReadInput {
+    /** Get a specific item by ID */
+    id?: string;
+    /** Filter by status */
+    status?: BacklogStatus;
+    /** Filter by type */
+    type?: BacklogItemType;
+    /** Search in title and description */
+    search?: string;
+    /** Filter by priority */
+    priority?: BacklogPriority;
+    /** Maximum items to return (default: 20) */
+    limit?: number;
+}
+/**
+ * Result from backlog_read
+ */
+export interface BacklogReadResult {
+    items: BacklogItem[];
+    total: number;
+    filtered: number;
+}
+/**
+ * Input parameters for backlog_write tool
+ */
+export interface BacklogWriteInput {
+    /** Action to perform */
+    action: 'add' | 'update' | 'delete' | 'replace';
+    /** Item to add or update (required for add/update) */
+    item?: Partial<BacklogItem>;
+    /** Item ID to delete (required for delete) */
+    deleteId?: string;
+    /** Full list of items (required for replace action) */
+    items?: BacklogItem[];
+}
+/**
+ * Result from backlog_write
+ */
+export interface BacklogWriteResult {
+    success: boolean;
+    action: string;
+    itemId?: string;
+    itemCount?: number;
+}
+/**
+ * Read backlog items with optional filters
+ */
+export declare const backlogReadTool: Tool<BacklogReadInput>;
+/**
+ * Write/update backlog items
+ */
+export declare const backlogWriteTool: Tool<BacklogWriteInput>;
+/**
+ * Options for creating custom backlog tools
+ */
+export interface BacklogToolOptions {
+    /** Custom base path for backlog file */
+    basePath?: string;
+}
+/**
+ * Create backlog tools with custom options
+ */
+export declare function createBacklogTools(_options?: BacklogToolOptions): {
+    backlogRead: Tool<BacklogReadInput>;
+    backlogWrite: Tool<BacklogWriteInput>;
+};