gencode-ai 0.1.3 → 0.3.0

package/src/planning/state.ts

@@ -0,0 +1,305 @@
+/**
+ * Plan Mode State Management
+ *
+ * Singleton state manager for plan mode. Tracks whether plan mode
+ * is active, current phase, and manages tool filtering.
+ */
+
+import type {
+  PlanModeState,
+  PlanPhase,
+  AllowedPrompt,
+  ModeType,
+  PlanModeEvent,
+} from './types.js';
+import { PLAN_MODE_ALLOWED_TOOLS, PLAN_MODE_BLOCKED_TOOLS } from './types.js';
+
+// ============================================================================
+// State Manager
+// ============================================================================
+
+/**
+ * Plan Mode State Manager
+ *
+ * Manages the plan mode state and provides methods for:
+ * - Entering/exiting plan mode
+ * - Phase transitions
+ * - Tool filtering
+ * - Event notifications
+ */
+export class PlanModeManager {
+  private state: PlanModeState;
+  private eventListeners: Set<(event: PlanModeEvent) => void>;
+
+  constructor() {
+    this.state = this.getInitialState();
+    this.eventListeners = new Set();
+  }
+
+  /**
+   * Get initial state
+   */
+  private getInitialState(): PlanModeState {
+    return {
+      active: false,
+      phase: 'understanding',
+      planFilePath: null,
+      originalRequest: null,
+      requestedPermissions: [],
+      enteredAt: null,
+    };
+  }
+
+  /**
+   * Get current state (readonly)
+   */
+  getState(): Readonly<PlanModeState> {
+    return { ...this.state };
+  }
+
+  /**
+   * Check if plan mode is active
+   */
+  isActive(): boolean {
+    return this.state.active;
+  }
+
+  /**
+   * Get current mode type for UI
+   * Note: Returns 'plan' or 'normal'. 'accept' mode is managed at the App level.
+   */
+  getCurrentMode(): ModeType {
+    return this.state.active ? 'plan' : 'normal';
+  }
+
+  /**
+   * Enter plan mode
+   */
+  enter(planFilePath: string, originalRequest?: string): void {
+    this.state = {
+      active: true,
+      phase: 'understanding',
+      planFilePath,
+      originalRequest: originalRequest ?? null,
+      requestedPermissions: [],
+      enteredAt: new Date(),
+    };
+
+    this.emit({ type: 'enter', planFilePath });
+  }
+
+  /**
+   * Exit plan mode
+   */
+  exit(approved: boolean = false): void {
+    const wasActive = this.state.active;
+    this.state = this.getInitialState();
+
+    if (wasActive) {
+      this.emit({ type: 'exit', approved });
+    }
+  }
+
+  /**
+   * Toggle plan mode (for Shift+Tab)
+   */
+  toggle(planFilePath?: string): void {
+    if (this.state.active) {
+      this.exit(false);
+    } else if (planFilePath) {
+      this.enter(planFilePath);
+    }
+    this.emit({ type: 'toggle' });
+  }
+
+  /**
+   * Update phase
+   */
+  setPhase(phase: PlanPhase): void {
+    if (this.state.active) {
+      this.state.phase = phase;
+      this.emit({ type: 'phase_change', phase });
+    }
+  }
+
+  /**
+   * Get current phase
+   */
+  getPhase(): PlanPhase {
+    return this.state.phase;
+  }
+
+  /**
+   * Set requested permissions (from ExitPlanMode)
+   */
+  setRequestedPermissions(permissions: AllowedPrompt[]): void {
+    this.state.requestedPermissions = permissions;
+  }
+
+  /**
+   * Get requested permissions
+   */
+  getRequestedPermissions(): AllowedPrompt[] {
+    return [...this.state.requestedPermissions];
+  }
+
+  /**
+   * Get plan file path
+   */
+  getPlanFilePath(): string | null {
+    return this.state.planFilePath;
+  }
+
+  // ============================================================================
+  // Tool Filtering
+  // ============================================================================
+
+  /**
+   * Check if a tool is allowed in the current mode
+   */
+  isToolAllowed(toolName: string): boolean {
+    if (!this.state.active) {
+      return true; // All tools allowed in build mode
+    }
+
+    // In plan mode, only allow read-only tools
+    return (PLAN_MODE_ALLOWED_TOOLS as readonly string[]).includes(toolName);
+  }
+
+  /**
+   * Check if a tool is blocked in the current mode
+   */
+  isToolBlocked(toolName: string): boolean {
+    if (!this.state.active) {
+      return false; // No tools blocked in build mode
+    }
+
+    return (PLAN_MODE_BLOCKED_TOOLS as readonly string[]).includes(toolName);
+  }
+
+  /**
+   * Get list of allowed tools for current mode
+   */
+  getAllowedTools(): string[] {
+    if (!this.state.active) {
+      return []; // Empty means all allowed
+    }
+    return [...PLAN_MODE_ALLOWED_TOOLS];
+  }
+
+  /**
+   * Get list of blocked tools for current mode
+   */
+  getBlockedTools(): string[] {
+    if (!this.state.active) {
+      return [];
+    }
+    return [...PLAN_MODE_BLOCKED_TOOLS];
+  }
+
+  /**
+   * Filter tool list based on current mode
+   */
+  filterTools(toolNames: string[]): string[] {
+    if (!this.state.active) {
+      return toolNames;
+    }
+
+    return toolNames.filter((name) => this.isToolAllowed(name));
+  }
+
+  // ============================================================================
+  // Event System
+  // ============================================================================
+
+  /**
+   * Subscribe to plan mode events
+   */
+  subscribe(listener: (event: PlanModeEvent) => void): () => void {
+    this.eventListeners.add(listener);
+    return () => {
+      this.eventListeners.delete(listener);
+    };
+  }
+
+  /**
+   * Emit an event to all listeners
+   */
+  private emit(event: PlanModeEvent): void {
+    for (const listener of this.eventListeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error('Error in plan mode event listener:', error);
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Singleton Instance
+// ============================================================================
+
+/**
+ * Global plan mode manager instance
+ */
+let globalPlanModeManager: PlanModeManager | null = null;
+
+/**
+ * Get the global plan mode manager
+ */
+export function getPlanModeManager(): PlanModeManager {
+  if (!globalPlanModeManager) {
+    globalPlanModeManager = new PlanModeManager();
+  }
+  return globalPlanModeManager;
+}
+
+/**
+ * Reset the global plan mode manager (for testing)
+ */
+export function resetPlanModeManager(): void {
+  if (globalPlanModeManager) {
+    globalPlanModeManager.exit(false);
+  }
+  globalPlanModeManager = null;
+}
+
+// ============================================================================
+// Convenience Functions
+// ============================================================================
+
+/**
+ * Check if plan mode is currently active
+ */
+export function isPlanModeActive(): boolean {
+  return getPlanModeManager().isActive();
+}
+
+/**
+ * Get the current mode type
+ */
+export function getCurrentMode(): ModeType {
+  return getPlanModeManager().getCurrentMode();
+}
+
+/**
+ * Enter plan mode
+ */
+export function enterPlanMode(planFilePath: string, originalRequest?: string): void {
+  getPlanModeManager().enter(planFilePath, originalRequest);
+}
+
+/**
+ * Exit plan mode
+ */
+export function exitPlanMode(approved: boolean = false): void {
+  getPlanModeManager().exit(approved);
+}
+
+/**
+ * Toggle plan mode
+ */
+export function togglePlanMode(planFilePath?: string): void {
+  getPlanModeManager().toggle(planFilePath);
+}

package/src/planning/tools/enter-plan-mode.ts

@@ -0,0 +1,111 @@
+/**
+ * EnterPlanMode Tool
+ *
+ * Transitions the agent into plan mode for designing implementation
+ * approaches before writing code. In plan mode, only read-only tools
+ * are available.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../../tools/types.js';
+import { getPlanModeManager } from '../state.js';
+import { createPlanFile, getDisplayPath } from '../plan-file.js';
+import { PLAN_MODE_ALLOWED_TOOLS, PLAN_MODE_BLOCKED_TOOLS } from '../types.js';
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+const EnterPlanModeInputSchema = z.object({});
+
+export type EnterPlanModeInput = z.infer<typeof EnterPlanModeInputSchema>;
+
+/**
+ * EnterPlanMode Tool
+ *
+ * Use this tool when you need to plan an implementation before writing code.
+ * This is recommended for:
+ * - New feature implementations
+ * - Tasks with multiple valid approaches
+ * - Architectural decisions
+ * - Multi-file changes
+ * - Unclear requirements
+ */
+export const enterPlanModeTool: Tool<EnterPlanModeInput> = {
+  name: 'EnterPlanMode',
+
+  description: `Transition into plan mode to design an implementation approach before writing code.
+
+Use this tool when:
+- Implementing new features that require design decisions
+- Tasks with multiple valid approaches
+- Changes that affect existing behavior or structure
+- Architectural decisions between patterns or technologies
+- Multi-file changes (more than 2-3 files)
+- Unclear requirements that need exploration
+
+In plan mode:
+- Only read-only tools are available (Read, Glob, Grep, WebFetch, WebSearch, TodoWrite, AskUserQuestion)
+- Write, Edit, and Bash tools are blocked
+- You can explore the codebase and design an approach
+- Use ExitPlanMode when ready to request user approval
+
+This tool REQUIRES user approval before entering plan mode.`,
+
+  parameters: EnterPlanModeInputSchema,
+
+  async execute(_input: EnterPlanModeInput, context: ToolContext): Promise<ToolResult> {
+    const manager = getPlanModeManager();
+
+    // Check if already in plan mode
+    if (manager.isActive()) {
+      return {
+        success: false,
+        output: '',
+        error: 'Already in plan mode. Use ExitPlanMode to exit first.',
+      };
+    }
+
+    try {
+      // Create plan file
+      const planFile = await createPlanFile(context.cwd);
+      const displayPath = getDisplayPath(planFile.path, context.cwd);
+
+      // Enter plan mode
+      manager.enter(planFile.path);
+
+      // Build response
+      const output = `
+Entered PLAN mode.
+
+Plan file: ${displayPath}
+
+In plan mode, you have access to read-only tools for exploration:
+${PLAN_MODE_ALLOWED_TOOLS.map((t) => `  - ${t}`).join('\n')}
+
+Blocked tools (write/execute operations):
+${PLAN_MODE_BLOCKED_TOOLS.map((t) => `  - ${t}`).join('\n')}
+
+Instructions:
+1. Explore the codebase using Read, Glob, Grep tools
+2. Research if needed using WebFetch, WebSearch
+3. Design your implementation approach
+4. Write your plan to the plan file using Write (plan file only)
+5. Call ExitPlanMode when ready for user approval
+
+Use Shift+Tab to toggle between Plan and Build modes.
+`.trim();
+
+      return {
+        success: true,
+        output,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to enter plan mode: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};

package/src/planning/tools/exit-plan-mode.ts

@@ -0,0 +1,170 @@
+/**
+ * ExitPlanMode Tool
+ *
+ * Exits plan mode and requests user approval for the implementation plan.
+ * Supports pre-approving permissions for bash commands needed during execution.
+ */
+
+import { z } from 'zod';
+import type { Tool, ToolResult, ToolContext } from '../../tools/types.js';
+import { getPlanModeManager } from '../state.js';
+import { readPlanFile, parseFilesToChange, parsePreApprovedPermissions, getDisplayPath } from '../plan-file.js';
+import type { AllowedPrompt } from '../types.js';
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+const AllowedPromptSchema = z.object({
+  tool: z.literal('Bash').describe('The tool this permission applies to'),
+  prompt: z.string().describe('Semantic description of the action, e.g., "run tests", "install dependencies"'),
+});
+
+const ExitPlanModeInputSchema = z.object({
+  allowedPrompts: z
+    .array(AllowedPromptSchema)
+    .optional()
+    .describe('Prompt-based permissions needed to implement the plan'),
+});
+
+export type ExitPlanModeInput = z.infer<typeof ExitPlanModeInputSchema>;
+
+/**
+ * ExitPlanMode Tool
+ *
+ * Call this when you have finished writing your plan and are ready
+ * for user approval. The plan file should already be written.
+ */
+export const exitPlanModeTool: Tool<ExitPlanModeInput> = {
+  name: 'ExitPlanMode',
+
+  description: `Exit plan mode and request user approval for the implementation plan.
+
+## How This Tool Works
+- You should have already written your plan to the plan file
+- This tool reads the plan from the file you wrote
+- The user will see the plan contents and approve/modify/cancel
+
+## Requesting Permissions (allowedPrompts)
+Request prompt-based permissions for bash commands your plan will need:
+
+\`\`\`json
+{
+  "allowedPrompts": [
+    { "tool": "Bash", "prompt": "run tests" },
+    { "tool": "Bash", "prompt": "install dependencies" },
+    { "tool": "Bash", "prompt": "build the project" }
+  ]
+}
+\`\`\`
+
+Guidelines for prompts:
+- Use semantic descriptions that capture the action's purpose
+- "run tests" matches: npm test, pytest, go test, etc.
+- "install dependencies" matches: npm install, pip install, etc.
+- Keep descriptions concise but descriptive
+- Only request permissions you actually need
+- Scope permissions narrowly
+
+## When to Use This Tool
+Only use this tool when you have finished planning and are ready for approval.
+Do NOT use this tool for research tasks - only for implementation planning.`,
+
+  parameters: ExitPlanModeInputSchema,
+
+  async execute(input: ExitPlanModeInput, context: ToolContext): Promise<ToolResult> {
+    const manager = getPlanModeManager();
+
+    // Check if in plan mode
+    if (!manager.isActive()) {
+      return {
+        success: false,
+        output: '',
+        error: 'Not in plan mode. Use EnterPlanMode first.',
+      };
+    }
+
+    const planFilePath = manager.getPlanFilePath();
+    if (!planFilePath) {
+      return {
+        success: false,
+        output: '',
+        error: 'No plan file found. This should not happen.',
+      };
+    }
+
+    try {
+      // Read plan file
+      const planFile = await readPlanFile(planFilePath);
+      if (!planFile) {
+        return {
+          success: false,
+          output: '',
+          error: `Could not read plan file: ${planFilePath}`,
+        };
+      }
+
+      // Parse plan content
+      const filesToChange = parseFilesToChange(planFile.content);
+      const planPermissions = parsePreApprovedPermissions(planFile.content);
+
+      // Combine with input permissions
+      const requestedPermissions: AllowedPrompt[] = [
+        ...planPermissions,
+        ...(input.allowedPrompts || []),
+      ];
+
+      // Store permissions for approval UI
+      manager.setRequestedPermissions(requestedPermissions);
+      manager.setPhase('approval');
+
+      // Build response for the LLM
+      const displayPath = getDisplayPath(planFilePath, context.cwd);
+      let output = `
+Plan ready for approval.
+
+Plan file: ${displayPath}
+
+`;
+
+      // Summary of files to change
+      if (filesToChange.length > 0) {
+        output += 'Files to change:\n';
+        for (const file of filesToChange) {
+          const icon = file.action === 'create' ? '+' : file.action === 'modify' ? '~' : '-';
+          output += `  ${icon} ${file.path} (${file.action})\n`;
+        }
+        output += '\n';
+      }
+
+      // Requested permissions
+      if (requestedPermissions.length > 0) {
+        output += 'Requested permissions:\n';
+        for (const perm of requestedPermissions) {
+          output += `  - ${perm.tool}(prompt: ${perm.prompt})\n`;
+        }
+        output += '\n';
+      }
+
+      output += `
+The user will now be prompted to:
+1. Approve - Accept plan and proceed with execution
+2. Modify - Go back and modify the plan
+3. Cancel - Exit plan mode without executing
+
+Waiting for user decision...
+`.trim();
+
+      return {
+        success: true,
+        output,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        output: '',
+        error: `Failed to exit plan mode: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  },
+};