gencode-ai 0.1.2 → 0.2.0

package/docs/operating-modes.md

@@ -0,0 +1,96 @@
+# Operating Modes
+
+> Reference: [Claude Code](https://claude.ai/code) operating modes
+
+GenCode has **3 operating modes** that can be cycled with `Shift+Tab`:
+
+```
+Normal (default)
+    ↓ Shift+Tab
+Plan (⏸ plan mode on)
+    ↓ Shift+Tab
+Accept (⏵⏵ accept edits on)
+    ↓ Shift+Tab
+Normal
+    ...
+```
+
+## Mode Comparison
+
+| Mode | Status Indicator | Edit Confirmation | Available Tools |
+|------|------------------|-------------------|-----------------|
+| **Normal** | _(none)_ | Required | All |
+| **Plan** | `⏸ plan mode on (shift+tab to cycle)` | N/A (edits blocked) | Read-only |
+| **Accept** | `⏵⏵ accept edits on (shift+tab to cycle)` | Auto-approved | All |
+
+## Mode Details
+
+### 1. Normal Mode (Default)
+
+- Normal execution mode
+- Every Write/Edit operation requires user confirmation
+- All tools available
+- Default mode when GenCode starts
+
+### 2. Plan Mode
+
+- Read-only exploration mode for designing implementation approaches
+- Write, Edit, and Bash tools are blocked
+- Used for understanding codebase and creating implementation plans
+
+**Allowed Tools:** Read, Glob, Grep, WebFetch, WebSearch, TodoWrite, AskUserQuestion
+
+**Blocked Tools:** Write, Edit, Bash
+
+### 3. Auto-accept Mode
+
+- Automatic edit acceptance mode
+- Write/Edit operations are automatically approved without confirmation
+- Useful when trusting the agent or after approving a plan
+- **Caution**: May cause unintended file changes
+
+## Plan Mode Workflow
+
+When in Plan mode, the agent goes through 5 phases:
+
+```
+EnterPlanMode
+     ↓
+┌─────────────┐
+│Understanding│ ← Explore codebase
+└──────┬──────┘
+       ↓
+┌─────────────┐
+│   Design    │ ← Design approach
+└──────┬──────┘
+       ↓
+┌─────────────┐
+│   Review    │ ← (Optional) Clarify requirements
+└──────┬──────┘
+       ↓
+┌─────────────┐
+│   Final     │ ← Write plan to file
+└──────┬──────┘
+       ↓
+ExitPlanMode
+       ↓
+┌─────────────┐
+│  Approval   │ ← User approves/modifies/cancels
+└─────────────┘
+```
+
+## Plan Approval Options
+
+When exiting Plan mode:
+
+| Option | Description | Next Mode |
+|--------|-------------|-----------|
+| **approve** | Accept plan, auto-accept edits | Accept |
+| **approve_manual** | Accept plan, manually approve each edit | Normal |
+| **modify** | Return to modify the plan | Plan |
+| **cancel** | Cancel plan entirely | Normal |
+
+## References
+
+- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+- [Plan Mode Proposal](./proposals/0004-plan-mode.md)

package/docs/proposals/0012-ask-user-question.md

@@ -2,9 +2,10 @@
 
 - **Proposal ID**: 0012
 - **Author**: gencode team
-- **Status**: Draft
+- **Status**: Implemented
 - **Created**: 2025-01-15
 - **Updated**: 2025-01-16
+- **Implemented**: 2025-01-16
 
 ## Summary
 
@@ -1014,6 +1015,70 @@ describe('AskUserQuestion Integration', () => {
 
 No breaking changes to existing functionality.
 
+## Implementation Notes
+
+### Files Created/Modified
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/tools/builtin/ask-user.ts` | Created | Tool implementation with Zod schemas |
+| `src/tools/types.ts` | Modified | Added Question/QuestionAnswer interfaces to ToolContext |
+| `src/tools/index.ts` | Modified | Registered and exported askUserQuestionTool |
+| `src/agent/types.ts` | Modified | Added AgentEventAskUser type |
+| `src/agent/agent.ts` | Modified | Added askUserCallback and toolContext integration |
+| `src/agent/index.ts` | Modified | Exported AskUserCallback type |
+| `src/cli/components/QuestionPrompt.tsx` | Created | Question UI component with Claude Code style |
+| `src/cli/components/App.tsx` | Modified | Integrated QuestionPrompt and state management |
+| `src/cli/components/theme.ts` | Modified | Added new icons for checkboxes and chips |
+| `src/cli/components/index.ts` | Modified | Exported QuestionPrompt and AnswerDisplay |
+| `src/prompts/tools/ask-user.txt` | Created | Tool description for LLM |
+
+### Key Implementation Details
+
+1. **Callback-based architecture**: The tool uses a callback (`askUser`) injected via `ToolContext` to communicate with the CLI layer
+2. **Promise-based async flow**: Questions block agent execution until user responds
+3. **Claude Code UI alignment**: Uses radio buttons (○/●), checkboxes (☐/☑), chip headers, and matching color scheme
+4. **Auto-added "Other" option**: Every question automatically includes an "Other" option for custom input
+5. **Multi-select support**: Full support for both single-select and multi-select modes
+
+### Prompt Guidance (Critical for LLM Tool Usage)
+
+The system prompt in `src/prompts/system/base.txt` includes explicit guidance with bad examples to ensure the LLM uses the tool instead of plain text:
+
+```
+CRITICAL: You MUST use the AskUserQuestion tool for ALL questions with choices.
+NEVER write numbered lists, bullet points, or "which do you prefer" questions as plain text.
+
+## Wrong - Plain Text Questions (DO NOT DO THIS)
+
+<bad-example>
+user: Set up a new database
+assistant: I can set up a database for you. Which one would you prefer?
+1. PostgreSQL - relational database
+2. MongoDB - document database
+3. SQLite - embedded database
+</bad-example>
+
+## Correct - Use AskUserQuestion Tool
+
+<example>
+user: Set up a new database
+assistant: [uses AskUserQuestion tool with structured options]
+</example>
+```
+
+The tool description in `src/prompts/tools/ask-user.txt` reinforces this with explicit "WRONG" examples:
+
+```
+CRITICAL: You MUST use this tool for ANY question with 2+ choices.
+NEVER present options as plain text, numbered lists, or bullet points.
+
+WRONG (never do this):
+- "Which do you prefer? 1. Option A 2. Option B"
+- "What type? - Web - CLI - API"
+- Writing any numbered or bulleted choices in your response
+```
+
 ## Theme Extensions
 
 Add the following icons to `src/cli/components/theme.ts`:

package/docs/proposals/0025-cost-tracking.md

@@ -2,9 +2,10 @@
 
 - **Proposal ID**: 0025
 - **Author**: mycode team
-- **Status**: Draft
+- **Status**: Implemented
 - **Created**: 2025-01-15
-- **Updated**: 2025-01-15
+- **Updated**: 2026-01-16
+- **Implemented**: 2026-01-16
 
 ## Summary
 
@@ -439,6 +440,63 @@ Only show costs after session ends.
 
 No breaking changes.
 
+## Implementation Notes
+
+### Phase 1 Complete (2026-01-16)
+
+Implemented core cost tracking functionality with real-time display in CLI.
+
+### Files Created
+
+| File | Description |
+|------|-------------|
+| `src/pricing/types.ts` | Type definitions for pricing and costs |
+| `src/pricing/models.ts` | Model pricing database (updated Jan 2025) |
+| `src/pricing/calculator.ts` | Cost calculation and formatting utilities |
+| `src/pricing/index.ts` | Module exports |
+| `examples/test-cost-tracking.ts` | Test script for cost tracking |
+| `docs/cost-tracking-comparison.md` | Detailed comparison with OpenCode |
+
+### Files Modified
+
+| File | Changes |
+|------|---------|
+| `src/providers/types.ts` | Added `cost?: CostEstimate` to `CompletionResponse` |
+| `src/providers/anthropic.ts` | Calculate and return cost in responses |
+| `src/providers/openai.ts` | Calculate and return cost in responses |
+| `src/providers/gemini.ts` | Calculate and return cost in responses |
+| `src/providers/vertex-ai.ts` | Calculate and return cost in responses |
+| `src/agent/types.ts` | Added `usage` and `cost` to `AgentEventDone` |
+| `src/agent/agent.ts` | Pass usage and cost to done event |
+| `src/cli/components/App.tsx` | Pass cost data to CompletionMessage |
+| `src/cli/components/Messages.tsx` | Display cost and token usage |
+
+### Key Implementation Details
+
+1. **Pricing Database**: Comprehensive pricing for all major models (Anthropic, OpenAI, Google Gemini/Vertex AI) as of January 2025
+
+2. **Cost Calculation**: Simple formula `(tokens / 1M) * pricePerMillion` for each token type
+
+3. **CLI Display Format**: `✻ Done for 2.3s • Tokens: 1.2K in / 567 out • (~$0.02)`
+
+4. **Provider Integration**: All 4 providers (Anthropic, OpenAI, Gemini, Vertex AI) calculate cost when usage data is available
+
+5. **Graceful Degradation**: Cost displays only when provider returns usage data (some stream modes may not include it)
+
+### Testing
+
+- Tested cost calculation with sample data
+- Verified correct pricing for all providers
+- Confirmed CLI display formatting
+
+### Future Enhancements (Phase 2+)
+
+- Session cost aggregation
+- Budget system with alerts
+- Cost reporting (`/costs` command)
+- Multi-provider cost comparison
+- Advanced token types (reasoning, cache)
+
 ## References
 
 - [Anthropic Pricing](https://www.anthropic.com/pricing)

package/docs/proposals/README.md

@@ -27,7 +27,7 @@ This directory contains enhancement proposals for the gencode project. Each prop
 | [0009](./0009-hooks-system.md) | Hooks System | Draft |
 | [0010](./0010-mcp-integration.md) | MCP Integration | Draft |
 | [0011](./0011-custom-commands.md) | Custom Commands | Draft |
-| [0012](./0012-ask-user-question.md) | AskUserQuestion Tool | Draft |
+| [0012](./0012-ask-user-question.md) | AskUserQuestion Tool | Implemented |
 | [0041](./0041-configuration-system.md) | Configuration System | Implemented |
 | [0042](./0042-prompt-optimization.md) | Prompt System Optimization | Implemented |
 
@@ -47,7 +47,7 @@ This directory contains enhancement proposals for the gencode project. Each prop
 | [0022](./0022-plugin-system.md) | Plugin System | Draft |
 | [0023](./0023-permission-enhancements.md) | Permission Enhancements | Draft |
 | [0024](./0024-keyboard-shortcuts.md) | Keyboard Shortcuts | Draft |
-| [0025](./0025-cost-tracking.md) | Cost Tracking | Draft |
+| [0025](./0025-cost-tracking.md) | Cost Tracking | Implemented |
 | [0026](./0026-git-integration.md) | Git Integration | Draft |
 | [0027](./0027-enhanced-read-tool.md) | Enhanced Read Tool | Draft |
 | [0028](./0028-enhanced-bash-tool.md) | Enhanced Bash Tool | Draft |

package/examples/test-ask-user.ts

@@ -0,0 +1,167 @@
+/**
+ * Test script for AskUserQuestion tool
+ *
+ * Run with: npx tsx examples/test-ask-user.ts [mode]
+ *
+ * Modes:
+ *   single   - Single question, single select (default)
+ *   multi    - Single question, multi-select
+ *   multiple - Multiple questions with review screen
+ */
+
+import { render } from 'ink';
+import React from 'react';
+import { QuestionPrompt } from '../src/cli/components/QuestionPrompt.js';
+import type { Question, QuestionAnswer } from '../src/tools/types.js';
+
+// Test questions - matching Claude Code style
+const testQuestions: Question[] = [
+  {
+    question: 'What type of database would you like to create?',
+    header: 'DB Type',
+    options: [
+      {
+        label: 'PostgreSQL',
+        description: 'Powerful open-source relational database with advanced features like JSON support and full-text search',
+      },
+      {
+        label: 'MySQL',
+        description: 'Popular relational database, great for web applications and general-purpose use',
+      },
+      {
+        label: 'SQLite',
+        description: 'Lightweight file-based database, perfect for local development or embedded applications',
+      },
+      {
+        label: 'MongoDB',
+        description: 'NoSQL document database for flexible schema and JSON-like documents',
+      },
+    ],
+    multiSelect: false,
+  },
+];
+
+const testMultiSelectQuestions: Question[] = [
+  {
+    question: 'Which features should we enable for your project?',
+    header: 'Features',
+    options: [
+      {
+        label: 'TypeScript',
+        description: 'Type safety and better IDE support with static type checking',
+      },
+      {
+        label: 'ESLint + Prettier',
+        description: 'Code linting and automatic formatting for consistent code style',
+      },
+      {
+        label: 'Testing (Vitest)',
+        description: 'Fast unit testing framework with native ESM support',
+      },
+      {
+        label: 'Tailwind CSS',
+        description: 'Utility-first CSS framework for rapid UI development',
+      },
+    ],
+    multiSelect: true,
+  },
+];
+
+const testMultipleQuestions: Question[] = [
+  {
+    question: 'What type of database would you like to create?',
+    header: 'DB Type',
+    options: [
+      {
+        label: 'PostgreSQL',
+        description: 'Powerful open-source relational database with advanced features like JSON support and full-text search',
+      },
+      {
+        label: 'MySQL',
+        description: 'Popular relational database, great for web applications and general-purpose use',
+      },
+      {
+        label: 'SQLite',
+        description: 'Lightweight file-based database, perfect for local development or embedded applications',
+      },
+      {
+        label: 'MongoDB',
+        description: 'NoSQL document database for flexible schema and JSON-like documents',
+      },
+    ],
+    multiSelect: false,
+  },
+  {
+    question: 'What is the primary purpose of this database?',
+    header: 'Purpose',
+    options: [
+      {
+        label: 'GenCode project',
+        description: 'Add database functionality to the GenCode AI assistant project',
+      },
+      {
+        label: 'New project',
+        description: 'Create a database for a separate new project',
+      },
+      {
+        label: 'Learning/Testing',
+        description: 'Set up a database for experimentation and learning',
+      },
+    ],
+    multiSelect: false,
+  },
+];
+
+// Choose which test to run
+const testMode = process.argv[2] || 'single';
+
+let questions: Question[];
+switch (testMode) {
+  case 'multi':
+    questions = testMultiSelectQuestions;
+    console.log('\n=== Testing Multi-Select Mode ===\n');
+    break;
+  case 'multiple':
+    questions = testMultipleQuestions;
+    console.log('\n=== Testing Multiple Questions with Review ===\n');
+    break;
+  default:
+    questions = testQuestions;
+    console.log('\n=== Testing Single-Select Mode ===\n');
+}
+
+function TestApp() {
+  const handleComplete = (answers: QuestionAnswer[]) => {
+    console.log('\n\n=== Answers Received ===');
+    answers.forEach((answer, i) => {
+      console.log(`\n${i + 1}. ${answer.header}`);
+      console.log(`   Question: ${answer.question}`);
+      console.log(`   Selected: ${answer.selectedOptions.join(', ') || '(none)'}`);
+      if (answer.customInput) {
+        console.log(`   Custom: ${answer.customInput}`);
+      }
+    });
+    console.log('\n');
+    process.exit(0);
+  };
+
+  const handleCancel = () => {
+    console.log('\n\nCancelled by user\n');
+    process.exit(0);
+  };
+
+  return React.createElement(QuestionPrompt, {
+    questions,
+    onComplete: handleComplete,
+    onCancel: handleCancel,
+  });
+}
+
+// Render the test app
+const { unmount } = render(React.createElement(TestApp));
+
+// Handle Ctrl+C
+process.on('SIGINT', () => {
+  unmount();
+  process.exit(0);
+});

package/examples/test-checkpointing.ts

@@ -0,0 +1,121 @@
+/**
+ * Test Checkpointing System
+ *
+ * This example demonstrates the automatic file change tracking and rewind capabilities.
+ */
+
+import { CheckpointManager } from '../src/checkpointing/index.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+async function testCheckpointing() {
+  console.log('🧪 Testing Checkpointing System\n');
+
+  const manager = new CheckpointManager('test-session');
+  const testDir = path.join(__dirname, '../.test-checkpoints');
+  const testFile = path.join(testDir, 'example.txt');
+
+  try {
+    // Create test directory
+    await fs.mkdir(testDir, { recursive: true });
+
+    console.log('1️⃣  Recording file creation...');
+    const originalContent = 'Hello, World!';
+    await fs.writeFile(testFile, originalContent, 'utf-8');
+
+    manager.recordChange({
+      path: testFile,
+      changeType: 'create',
+      previousContent: null,
+      newContent: originalContent,
+      toolName: 'Write',
+    });
+
+    console.log('   ✓ File created:', testFile);
+    console.log('   ✓ Checkpoint recorded\n');
+
+    console.log('2️⃣  Recording file modification...');
+    const modifiedContent = 'Hello, Checkpointing!';
+    await fs.writeFile(testFile, modifiedContent, 'utf-8');
+
+    manager.recordChange({
+      path: testFile,
+      changeType: 'modify',
+      previousContent: originalContent,
+      newContent: modifiedContent,
+      toolName: 'Edit',
+    });
+
+    console.log('   ✓ File modified');
+    console.log('   ✓ Checkpoint recorded\n');
+
+    console.log('3️⃣  Listing checkpoints...');
+    console.log(manager.formatCheckpointList(true));
+    console.log();
+
+    console.log('4️⃣  Getting summary...');
+    const summary = manager.getSummary();
+    console.log(`   Created: ${summary.created}`);
+    console.log(`   Modified: ${summary.modified}`);
+    console.log(`   Deleted: ${summary.deleted}`);
+    console.log(`   Total: ${summary.total}\n`);
+
+    console.log('5️⃣  Rewinding last change...');
+    const result = await manager.rewind({ count: 1 });
+
+    if (result.success) {
+      console.log('   ✓ Rewind successful');
+      result.revertedFiles.forEach((f) => {
+        console.log(`     • ${path.basename(f.path)} (${f.action})`);
+      });
+
+      // Verify content was restored
+      const restoredContent = await fs.readFile(testFile, 'utf-8');
+      if (restoredContent === originalContent) {
+        console.log('   ✓ Content restored correctly\n');
+      } else {
+        console.log('   ✗ Content mismatch!\n');
+      }
+    } else {
+      console.log('   ✗ Rewind failed');
+      result.errors.forEach((e) => console.log(`     ${e.error}`));
+    }
+
+    console.log('6️⃣  Rewinding all changes...');
+    const finalResult = await manager.rewind({ all: true });
+
+    if (finalResult.success) {
+      console.log('   ✓ All changes reverted');
+      finalResult.revertedFiles.forEach((f) => {
+        console.log(`     • ${path.basename(f.path)} (${f.action})`);
+      });
+
+      // Verify file was deleted
+      try {
+        await fs.access(testFile);
+        console.log('   ✗ File still exists!\n');
+      } catch {
+        console.log('   ✓ File was deleted as expected\n');
+      }
+    }
+
+    console.log('✅ All tests passed!\n');
+  } catch (error) {
+    console.error('❌ Test failed:', error);
+  } finally {
+    // Cleanup
+    try {
+      await fs.rm(testDir, { recursive: true, force: true });
+      console.log('🧹 Cleaned up test directory');
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+// Run the test
+testCheckpointing();

package/examples/test-cost-tracking.ts

@@ -0,0 +1,77 @@
+/**
+ * Test cost tracking functionality
+ */
+
+import { createProvider } from '../src/providers/index.js';
+import { calculateCost, formatCost, formatTokens } from '../src/pricing/calculator.js';
+
+async function testCostTracking() {
+  console.log('='.repeat(60));
+  console.log('Testing Cost Tracking Feature');
+  console.log('='.repeat(60));
+  console.log();
+
+  // Test 1: Cost Calculation
+  console.log('Test 1: Cost Calculation');
+  console.log('-'.repeat(60));
+
+  const testCases = [
+    { provider: 'anthropic', model: 'claude-sonnet-4', input: 1000, output: 500 },
+    { provider: 'openai', model: 'gpt-4o', input: 1000, output: 500 },
+    { provider: 'gemini', model: 'gemini-2.0-flash', input: 1000, output: 500 },
+  ];
+
+  for (const test of testCases) {
+    const cost = calculateCost(test.provider, test.model, {
+      inputTokens: test.input,
+      outputTokens: test.output,
+    });
+
+    console.log(`\n${test.provider}/${test.model}:`);
+    console.log(`  Input: ${formatTokens(test.input)} tokens`);
+    console.log(`  Output: ${formatTokens(test.output)} tokens`);
+    console.log(`  Cost: ${formatCost(cost.totalCost)}`);
+    console.log(`  Breakdown: ${formatCost(cost.inputCost)} (input) + ${formatCost(cost.outputCost)} (output)`);
+  }
+
+  console.log();
+  console.log('='.repeat(60));
+  console.log();
+
+  // Test 2: Real API Call (if env var is set)
+  if (process.env.ANTHROPIC_API_KEY) {
+    console.log('Test 2: Real API Call with Anthropic');
+    console.log('-'.repeat(60));
+
+    const provider = createProvider({ provider: 'anthropic', model: 'claude-haiku-3-5' });
+
+    const response = await provider.complete({
+      model: 'claude-haiku-3-5',
+      messages: [{ role: 'user', content: 'Say hello in one word' }],
+      maxTokens: 10,
+    });
+
+    console.log('\nResponse:', response.content[0]?.type === 'text' ? response.content[0].text : '');
+
+    if (response.usage) {
+      console.log(`\nToken Usage:`);
+      console.log(`  Input: ${formatTokens(response.usage.inputTokens)}`);
+      console.log(`  Output: ${formatTokens(response.usage.outputTokens)}`);
+    }
+
+    if (response.cost) {
+      console.log(`\nCost Estimate:`);
+      console.log(`  Total: ${formatCost(response.cost.totalCost)}`);
+      console.log(`  Input: ${formatCost(response.cost.inputCost)}`);
+      console.log(`  Output: ${formatCost(response.cost.outputCost)}`);
+    }
+
+    console.log();
+    console.log('='.repeat(60));
+  } else {
+    console.log('Skipping API test (no ANTHROPIC_API_KEY)');
+    console.log('='.repeat(60));
+  }
+}
+
+testCostTracking().catch(console.error);