@compilr-dev/cli 0.4.0 → 0.5.0

package/README.md

@@ -1,7 +1,20 @@
 # @compilr-dev/cli
 
+```
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| CLI
+```
+
 > AI-powered CLI assistant using @compilr-dev/agents
 
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/cli.svg)](https://www.npmjs.com/package/@compilr-dev/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 ## Overview
 
 An AI coding assistant for the terminal, built with the `@compilr-dev/agents` library. Supports multiple LLM providers (Claude, OpenAI, Gemini, Ollama) with streaming output, tool execution, and context management.
@@ -63,8 +76,8 @@ compilr --verbose
 
 ```bash
 # Clone the repository
-git clone https://github.com/scozzola/compilr-dev-cli.git
-cd compilr-dev-cli
+git clone https://github.com/compilr-dev/cli.git
+cd cli
 
 # Install dependencies
 npm install
@@ -86,13 +99,15 @@ npm run build
 
 ## Documentation
 
-Specs in `/workspace/project-docs/00-requirements/compilr-dev-cli/`:
-- `poc-objectives.md` - Original validation objectives
-- `poc-scope.md` - Feature scope
-- `poc-architecture.md` - Technical design
-- `streaming-output-plan.md` - Streaming implementation
-- `theme-system-spec.md` - Theme configuration
-- `config-overlay-spec.md` - Settings system
+Full documentation and tutorials available at [compilr.dev](https://compilr.dev):
+- Getting Started Guide
+- Configuration Reference
+- Tool Documentation
+- Best Practices
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
@@ -100,11 +115,14 @@ MIT
 
 ## Links
 
-- [compilr.dev](https://compilr.dev) - Main website
+- [compilr.dev](https://compilr.dev) - Main website & documentation
 - [@compilr-dev/agents](https://www.npmjs.com/package/@compilr-dev/agents) - Agent library
 - [@compilr-dev/agents-coding](https://www.npmjs.com/package/@compilr-dev/agents-coding) - Coding tools
-- [GitHub](https://github.com/scozzola/compilr-dev-cli) - Source code
+- [GitHub](https://github.com/compilr-dev/cli) - Source code
+- [Examples](https://github.com/compilr-dev/examples) - Example projects
 
 ---
 
-**Built with @compilr-dev/agents**
+```
+[^_^] Built with @compilr-dev/agents
+```

package/dist/agent.d.ts

@@ -6,7 +6,7 @@
  * and available tools.
  */
 import { Agent } from '@compilr-dev/agents';
-import type { AgentEvent, PermissionHandler } from '@compilr-dev/agents';
+import type { AgentEvent, PermissionHandler, GuardrailTriggeredHandler } from '@compilr-dev/agents';
 /**
  * Supported providers
  */
@@ -47,6 +47,68 @@ export interface AgentOptions {
      * This is appended to the system prompt to give the agent project-specific knowledge.
      */
     projectContext?: string;
+    /**
+     * Guided workflow context.
+     * Appended to the system prompt when in guided mode.
+     * Generated by the workflow module based on project/item state.
+     */
+    guidedModeContext?: string;
+    /**
+     * Enable anchors (critical info that survives compaction).
+     * When true, agent is configured with AnchorManager.
+     */
+    enableAnchors?: boolean;
+    /**
+     * Pre-loaded anchors to add to the agent at startup.
+     * These are loaded from persisted files (global + project).
+     */
+    persistedAnchors?: Array<{
+        id?: string;
+        content: string;
+        priority: 'critical' | 'safety' | 'info';
+        scope: 'session' | 'persistent' | 'temporary';
+        tags?: string[];
+        projectId?: string;
+    }>;
+    /**
+     * Enable guardrails (safety checks for risky operations).
+     * When true, 15 built-in patterns are enabled for git, filesystem, database, etc.
+     * Warnings are emitted as 'guardrail_warning' events on the agent.
+     */
+    enableGuardrails?: boolean;
+    /**
+     * Callback for guardrail confirmation prompts.
+     * Called when a guardrail with action='confirm' is triggered.
+     * Return true to proceed, false to block.
+     */
+    onGuardrailTriggered?: GuardrailTriggeredHandler;
+    /**
+     * Callback when a subagent starts (task tool spawns agent).
+     * @param toolUseId - Tool use ID for correlation (from task tool's tool_start event)
+     * @param agentType - Type of agent being spawned
+     * @param description - Task description
+     */
+    onSubagentStart?: (toolUseId: string, agentType: string, description: string) => void;
+    /**
+     * Callback when a subagent completes.
+     * @param toolUseId - Tool use ID for correlation
+     * @param success - Whether the subagent completed successfully
+     * @param tokenCount - Total tokens used by the subagent
+     * @param error - Error message if failed
+     */
+    onSubagentEnd?: (toolUseId: string, success: boolean, tokenCount: number, error?: string) => void;
+    /**
+     * Callback when a subagent uses a tool (for live updates).
+     * @param toolUseId - Tool use ID for correlation
+     * @param toolName - Name of the tool being used
+     * @param summary - Optional summary of what the tool is doing
+     */
+    onSubagentToolUse?: (toolUseId: string, toolName: string, summary?: string) => void;
+    /**
+     * Callback invoked when subagent tracking should be cleared (e.g., new run starting).
+     * Returns a function to clear the tracking state.
+     */
+    onSubagentTrackingReady?: (clearTracking: () => void) => void;
 }
 /**
  * Get permission info for a tool by name.
@@ -56,6 +118,17 @@ export declare function getToolPermissionInfo(toolName: string): {
     level: 'once' | 'always' | 'session';
     description: string;
 } | undefined;
+/**
+ * Get information about built-in guardrails.
+ * Used for displaying guardrail info in /help or status overlays.
+ */
+export declare function getBuiltinGuardrailInfo(): Array<{
+    id: string;
+    name: string;
+    description: string;
+    action: 'warn' | 'confirm' | 'block';
+    category: string;
+}>;
 /**
  * Creates an Agent instance configured with all tools.
  */

package/dist/agent.js

@@ -5,94 +5,176 @@
  * ClaudeProvider, OllamaProvider, OpenAIProvider, or GeminiProvider
  * and available tools.
  */
-import { Agent, ClaudeProvider, OllamaProvider, OpenAIProvider, GeminiProvider, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, } from '@compilr-dev/agents';
+import { Agent, ClaudeProvider, OllamaProvider, OpenAIProvider, GeminiProvider, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, } from '@compilr-dev/agents';
 import { isAutoCompactEnabled } from './settings/index.js';
 import { getApiKey } from './utils/credentials.js';
 import { createToolRegistry, createMinimalToolRegistry } from './tools.js';
 import { getAgentRegistry } from './agents/registry.js';
-const SYSTEM_PROMPT = `You are a helpful coding assistant running in a terminal.
+const SYSTEM_PROMPT = `You are a coding assistant running in a terminal CLI.
 
-AVAILABLE TOOLS (use these exact names - lowercase with underscores):
+You help users with software engineering tasks: writing code, debugging, refactoring, explaining concepts, managing projects, and more.
 
-File Operations:
-- read_file: Read contents of a file (parameter: path)
+## Tone and Style
+
+- Your output displays in a terminal. Keep responses short and concise.
+- Use GitHub-flavored markdown for formatting.
+- Only use emojis if the user explicitly requests them.
+- Output text to communicate. Never use tools (like bash echo) to communicate.
+- NEVER create files unless absolutely necessary. Always prefer editing existing files.
+- When referencing code, include file path and line number: src/utils.ts:42
+
+## Professional Objectivity
+
+Prioritize technical accuracy over validating the user's beliefs. Provide direct, objective technical info without unnecessary praise or emotional validation. Disagree when necessary - objective guidance is more valuable than false agreement.
+
+Avoid phrases like "You're absolutely right!" or "Great question!" - just answer directly.
+
+## No Time Estimates
+
+Never predict how long tasks will take. Avoid phrases like "this will take a few minutes" or "quick fix". Focus on what needs to be done, not duration.
+
+---
+
+## Doing Tasks
+
+When the user requests software engineering work:
+
+1. **Read before modifying**: NEVER propose changes to code you haven't read. Always read files first.
+2. **Use todo_write for complex tasks**: Track progress on multi-step work (3+ steps).
+3. **Avoid over-engineering**:
+   - Only make changes that are directly requested
+   - Don't add features beyond what was asked
+   - Don't add error handling for scenarios that can't happen
+   - Don't create abstractions for one-time operations
+   - Three similar lines is better than a premature abstraction
+4. **Security awareness**: Don't introduce vulnerabilities (injection, XSS, SQL injection). If you notice insecure code, fix it immediately.
+5. **Clean up completely**: If something is unused, delete it. No backwards-compatibility hacks.
+
+## Task Management (todo_write)
+
+Use todo_write to track progress on multi-step tasks.
+
+When to use:
+- Tasks with 3+ distinct steps
+- User provides multiple tasks
+- Complex work requiring planning
+
+When NOT to use:
+- Single, trivial tasks
+- Purely informational questions
+- Tasks completable in 1-2 steps
+
+### Example: When to use todo_write
+
+User: Fix the type errors and run the tests
+Assistant: I'll track this multi-step task:
+[Uses todo_write: "Fix type errors", "Run tests"]
+[Marks "Fix type errors" as in_progress]
+[Reads files, fixes errors]
+[Marks "Fix type errors" complete, "Run tests" in_progress]
+[Runs tests]
+[Marks "Run tests" complete]
+
+### Example: When NOT to use todo_write
+
+User: What does this function do?
+Assistant: [Reads the file and explains directly - no todo needed for a simple question]
+
+---
+
+## Tool Usage
+
+IMPORTANT: Tool names are lowercase with underscores. Use them exactly as shown.
+
+### File Operations
+- read_file: Read file contents (parameter: path)
 - write_file: Create or overwrite a file (parameters: path, content)
 - edit: Replace text in a file (parameters: path, old_text, new_text)
 - glob: Find files matching a pattern (parameters: pattern, path)
 - grep: Search file contents with regex (parameters: pattern, path)
 
-Shell:
+### Shell
 - bash: Run shell commands (parameter: command)
-  For long-running commands (dev servers, watch modes), use run_in_background=true
-- bash_output: Get output from a background shell (parameter: shell_id)
-- kill_shell: Terminate a background shell (parameter: shell_id)
-
-BACKGROUND PROCESSES:
-When running commands that don't exit (like npm run dev, npm start, watch commands):
-1. Use bash with run_in_background=true to start the process
-2. The tool returns a shell_id you can use to monitor or kill the process
-3. Use bash_output with the shell_id to check output/status
-4. Use kill_shell with the shell_id to stop the process when done
-
-Example: Starting a dev server
-  bash(command="npm run dev", run_in_background=true) → returns shell_id
-  bash_output(shell_id="...") → check if server started
-  kill_shell(shell_id="...") → stop when done
-
-Git:
+  For long-running commands (dev servers), use run_in_background=true
+- bash_output: Get output from background shell (parameter: shell_id)
+- kill_shell: Terminate background shell (parameter: shell_id)
+
+### Git
 - git_status: Show working tree status
 - git_diff: Show file differences
-- git_log: Show commit history (parameter: limit)
+- git_log: Show commit history
 - git_commit: Create a commit (parameters: message, files)
 - git_branch: List or manage branches
 
-Project Analysis:
+### Project Analysis
 - detect_project: Detect project type and framework
-- find_project_root: Find the root directory of the project
-- run_tests: Run project test suite
-- run_lint: Run project linter
+- find_project_root: Find project root directory
+- run_tests: Run test suite
+- run_lint: Run linter
 
-Task Management:
-- todo_write: Add/update todo items (parameters: todos array)
+### Task Management
+- todo_write: Add/update todo items
 - todo_read: View current todo list
 
-Next Action Suggestions:
-- suggest: Suggest a next action to the user (parameters: action, reason)
-  The suggestion appears as ghost text in the input prompt (user presses Tab to accept).
-
-  IMPORTANT: Always use 'suggest' after completing a task or answering a question.
-  This is a mandatory part of your response workflow, not optional.
-
-  When to suggest:
-    - After ANY tool-based task → suggest verifying, testing, or next logical step
-    - After answering a question → suggest a follow-up to explore
-    - After explaining something → suggest trying it out or diving deeper
-    - When your reply ends with a question → suggest an answer option
-
-  Good suggestions are short commands or actions: "run npm test", "commit the changes",
-  "show me the API endpoints", "explain the error in more detail"
-
-Sub-agents (via task tool):
-- task: Spawn a specialized sub-agent for complex, multi-step tasks
-  Parameters: description (3-5 words), prompt (detailed task), subagent_type
-  Built-in types:
-    - explore: Fast codebase search and navigation
-    - code-review: Review code for bugs and best practices
-    - plan: Break down complex tasks into steps
-    - debug: Investigate and fix issues
-    - test-runner: Run and analyze tests
-    - refactor: Safe code refactoring
-    - security-audit: Scan for vulnerabilities
-    - doc-lookup: Search documentation
-    - general: General-purpose multi-step tasks
-  Custom agents may also be available (check /agents command).
-
-IMPORTANT RULES:
-1. Tool names are lowercase with underscores - use them exactly as shown
-2. If unsure which tool to use, pick the closest match from the list
-3. For simple questions (math, facts), answer directly without tools
-4. After calling a tool, you MUST respond with the result to the user - never end silently
-5. Use the task tool to delegate complex tasks to specialized sub-agents
+### User Interaction
+- ask_user: Ask question with multiple choice options
+- ask_user_simple: Ask simple yes/no or text input question
+- suggest: Suggest next action (appears as ghost text - user presses Tab to accept)
+
+### Sub-agents
+- task: Spawn specialized sub-agent for complex tasks
+  Types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general
+
+---
+
+## Git Safety Protocol
+
+When working with git:
+
+1. **Never update git config** without explicit user request
+2. **Never force push** to main/master - warn if requested
+3. **Never use --amend** unless:
+   - User explicitly requested it, AND
+   - Commit was created by you in this session, AND
+   - Commit has NOT been pushed to remote
+4. **Check before destructive operations**:
+   - git reset --hard (loses uncommitted changes)
+   - git checkout -- file (discards local changes)
+   - git clean (deletes untracked files)
+5. **Only commit when asked** - don't commit proactively
+
+### Commit Workflow
+1. Run git_status to see changes
+2. Run git_diff to review what will be committed
+3. Check recent git_log for commit message style
+4. Create focused commit with clear message
+5. Never commit files with secrets (.env, credentials.json)
+
+---
+
+## Next Action Suggestions
+
+After completing a task, call the suggest tool to recommend the next action.
+
+Good suggestions are short commands or actions:
+- "run npm test"
+- "commit the changes"
+- "check the error log"
+
+CALL the suggest tool - never write "suggest: ..." as text.
+
+---
+
+## IMPORTANT RULES (read carefully)
+
+1. Tool names are lowercase with underscores - use exactly as shown
+2. ALWAYS read files before proposing changes to them
+3. After calling a tool, respond with the result - never end silently
+4. Use todo_write for multi-step tasks (3+ steps)
+5. Don't over-engineer - implement exactly what was asked
+6. Check for security issues - fix insecure code immediately
+7. Use the task tool to delegate complex work to sub-agents
+8. Call suggest tool after completing tasks (don't write "suggest:" as text)
 
 Current working directory: ${process.cwd()}`;
 /**
@@ -111,8 +193,7 @@ const DEFAULT_PERMISSION_RULES = [
     // Project runners (can have side effects)
     { toolName: 'run_tests', level: 'once', description: 'Run test suite' },
     { toolName: 'run_lint', level: 'once', description: 'Run linter (may auto-fix)' },
-    // Local file modifications
-    { toolName: 'backlog_write', level: 'once', description: 'Modify backlog file' },
+    // Note: backlog_write removed - use workitem_* tools which modify database
 ];
 /**
  * Get permission info for a tool by name.
@@ -128,6 +209,19 @@ export function getToolPermissionInfo(toolName) {
     }
     return undefined;
 }
+/**
+ * Get information about built-in guardrails.
+ * Used for displaying guardrail info in /help or status overlays.
+ */
+export function getBuiltinGuardrailInfo() {
+    return BUILTIN_GUARDRAILS.map((g) => ({
+        id: g.id,
+        name: g.name,
+        description: g.description,
+        action: g.action,
+        category: g.tags?.[0] ?? 'general',
+    }));
+}
 /**
  * Merges built-in agent types with custom agents from registry.
  * Custom agents get safe read-only tools by default.
@@ -254,10 +348,16 @@ export function createAgent(options = {}) {
             }
         }
         : undefined;
-    // Build system prompt with optional project context
-    const systemPrompt = options.projectContext
-        ? `${SYSTEM_PROMPT}\n\n---\n\n## Project Context\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${options.projectContext}`
-        : SYSTEM_PROMPT;
+    // Build system prompt with optional project context and guided mode context
+    // Note: Anchors are NOT added here - they're handled by library's AnchorManager
+    // which re-injects them on every LLM call (survives compaction)
+    let systemPrompt = SYSTEM_PROMPT;
+    if (options.projectContext) {
+        systemPrompt += `\n\n---\n\n## Project Context\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${options.projectContext}`;
+    }
+    if (options.guidedModeContext) {
+        systemPrompt += `\n\n---\n\n${options.guidedModeContext}`;
+    }
     const agent = new Agent({
         provider,
         systemPrompt,
@@ -280,7 +380,40 @@ export function createAgent(options = {}) {
             : undefined,
         // Iteration limit handler - asks user if they want to continue
         onIterationLimitReached: options.onIterationLimitReached,
+        // Anchors - critical info that survives context compaction
+        // Library re-injects anchors on every LLM call
+        anchors: options.enableAnchors
+            ? {
+                maxAnchors: 50,
+                maxTokens: 4000,
+                includeDefaults: true,
+                // Note: We manage persistence ourselves via project-anchors.ts
+                // Don't set persistPath - we load anchors manually below
+            }
+            : undefined,
+        // Guardrails - pattern-based safety checks for risky operations
+        // 15 built-in patterns: git destructive ops, rm -rf, DROP TABLE, secrets, etc.
+        guardrails: options.enableGuardrails
+            ? {
+                enabled: true,
+                includeDefaults: true,
+                onTriggered: options.onGuardrailTriggered,
+            }
+            : undefined,
     });
+    // Load persisted anchors into the agent's AnchorManager
+    if (options.enableAnchors && options.persistedAnchors) {
+        for (const anchor of options.persistedAnchors) {
+            agent.addAnchor({
+                id: anchor.id,
+                content: anchor.content,
+                priority: anchor.priority,
+                scope: anchor.scope,
+                tags: anchor.tags,
+                // Note: projectId is for our tracking, not needed by library
+            });
+        }
+    }
     // Register tools using registerTools method
     const tools = options.minimal
         ? createMinimalToolRegistry()
@@ -289,20 +422,70 @@ export function createAgent(options = {}) {
     agent.registerTools(tools);
     // Register Task tool for sub-agent spawning (only in full mode)
     if (!options.minimal) {
+        // Track active subagents to correlate spawn/complete/events
+        // Track active subagents by toolUseId for token counting
+        const activeSubagents = new Map();
+        // Provide a way for caller to clear tracking state between runs
+        if (options.onSubagentTrackingReady) {
+            options.onSubagentTrackingReady(() => {
+                activeSubagents.clear();
+            });
+        }
         const taskTool = createTaskTool({
             parentAgent: agent,
             agentTypes: getMergedAgentTypes(),
             enableEventStreaming: true,
             defaultTimeout: 120000, // 2 minutes for subagent operations
-            onSpawn: (agentType, description) => {
+            // Now uses toolUseId for direct correlation (no more FIFO matching!)
+            onSpawn: (agentType, description, toolUseId) => {
                 if (options.verbose) {
-                    console.log(`\n[Sub-agent] Spawning ${agentType}: ${description}`);
+                    console.log(`\n[Sub-agent] Spawning ${agentType}: ${description} (${toolUseId ?? 'no-id'})`);
+                }
+                // Immediately notify with toolUseId - no more queuing/matching!
+                if (toolUseId) {
+                    activeSubagents.set(toolUseId, { agentType, tokenCount: 0 });
+                    if (options.onSubagentStart) {
+                        options.onSubagentStart(toolUseId, agentType, description);
+                    }
                 }
             },
-            onComplete: (agentType, result) => {
+            onComplete: (agentType, result, toolUseId) => {
                 if (options.verbose) {
                     console.log(`[Sub-agent] ${agentType} completed (${String(result.iterations)} iterations)`);
                 }
+                // Direct notification with toolUseId - no more searching!
+                if (toolUseId && options.onSubagentEnd) {
+                    options.onSubagentEnd(toolUseId, true, result.toolCalls);
+                    activeSubagents.delete(toolUseId);
+                }
+            },
+            // Stream subagent events for live updates
+            onSubAgentEvent: (eventInfo) => {
+                const { toolUseId, event } = eventInfo;
+                // Handle tool events for live updates
+                if (event.type === 'tool_start' && toolUseId && event.name && options.onSubagentToolUse) {
+                    // Extract tool name and input summary
+                    const toolName = event.name;
+                    let summary;
+                    // Try to get a meaningful summary from input
+                    const input = event.input;
+                    if (input) {
+                        // Common patterns for tool input summaries
+                        const path = input.path;
+                        const pattern = input.pattern;
+                        const command = input.command;
+                        const filePath = input.file_path;
+                        if (typeof path === 'string')
+                            summary = path;
+                        else if (typeof pattern === 'string')
+                            summary = pattern;
+                        else if (typeof command === 'string')
+                            summary = command.slice(0, 40);
+                        else if (typeof filePath === 'string')
+                            summary = filePath;
+                    }
+                    options.onSubagentToolUse(toolUseId, toolName, summary);
+                }
             },
         });
         // Type assertion needed for task tool compatibility

package/dist/anchors/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Anchors Module
+ *
+ * Re-exports the project-anchors API for managing persistent
+ * critical information that survives context compaction.
+ */
+export { getAnchorManager, getGlobalAnchorManager, clearProjectAnchors, getFormattedAnchors, addAnchor, getAllAnchors, getProjectsWithAnchors, getAnchorStats, clearManagerCache, } from './project-anchors.js';
+export type { Anchor, AnchorInput, AnchorQueryOptions } from './project-anchors.js';
+export { AnchorManager } from '@compilr-dev/agents';

package/dist/anchors/index.js

@@ -0,0 +1,9 @@
+/**
+ * Anchors Module
+ *
+ * Re-exports the project-anchors API for managing persistent
+ * critical information that survives context compaction.
+ */
+export { getAnchorManager, getGlobalAnchorManager, clearProjectAnchors, getFormattedAnchors, addAnchor, getAllAnchors, getProjectsWithAnchors, getAnchorStats, clearManagerCache, } from './project-anchors.js';
+// Re-export the AnchorManager type from agents for consumers
+export { AnchorManager } from '@compilr-dev/agents';