gencode-ai 0.1.0

package/docs/proposals/0008-checkpointing.md

@@ -0,0 +1,327 @@
+# Proposal: Checkpointing (Edit Undo/Rewind)
+
+- **Proposal ID**: 0008
+- **Author**: mycode team
+- **Status**: Draft
+- **Created**: 2025-01-15
+- **Updated**: 2025-01-15
+
+## Summary
+
+Implement a checkpointing system that tracks all file changes made by the agent and enables users to rewind/undo unwanted modifications. This provides a safety net for experimentation and quick recovery from undesired changes.
+
+## Motivation
+
+Currently, mycode makes irreversible file changes. This leads to:
+
+1. **Fear of damage**: Users hesitant to let agent modify files
+2. **Manual recovery**: Must use git or backups to undo changes
+3. **Lost work**: Accidental overwrites can't be recovered
+4. **No visibility**: Can't see what files were changed
+5. **No experimentation**: Can't easily try approaches and revert
+
+A checkpointing system enables safe experimentation with easy rollback.
+
+## Claude Code Reference
+
+Claude Code provides automatic checkpointing:
+
+### Key Features
+- Automatic tracking of all file edits
+- `/rewind` command to undo changes
+- Change history visible in session
+- Per-file and bulk rollback options
+- Integration with git (commits as checkpoints)
+
+### Example Usage
+```
+Agent: [Makes several file changes]
+- Modified src/auth.ts
+- Created src/middleware.ts
+- Modified package.json
+
+User: Actually, I don't like that approach. Undo those changes.
+
+Agent: I'll rewind the file changes.
+[Reverting 3 file changes...]
+- Reverted src/auth.ts
+- Deleted src/middleware.ts
+- Reverted package.json
+
+Changes have been undone.
+```
+
+### Change Tracking Display
+```
+Session Changes:
+  [1] src/auth.ts (modified) - 10 minutes ago
+  [2] src/middleware.ts (created) - 8 minutes ago
+  [3] package.json (modified) - 5 minutes ago
+
+Use /rewind [number] to undo specific changes
+Use /rewind all to undo all changes
+```
+
+## Detailed Design
+
+### API Design
+
+```typescript
+// src/checkpointing/types.ts
+type ChangeType = 'create' | 'modify' | 'delete';
+
+interface FileCheckpoint {
+  id: string;
+  path: string;
+  changeType: ChangeType;
+  timestamp: Date;
+  previousContent: string | null;  // null for create
+  newContent: string | null;       // null for delete
+  toolName: string;                // Which tool made the change
+}
+
+interface CheckpointSession {
+  id: string;
+  sessionId: string;
+  checkpoints: FileCheckpoint[];
+  createdAt: Date;
+}
+
+interface RewindOptions {
+  checkpointId?: string;    // Specific checkpoint
+  path?: string;            // Specific file
+  all?: boolean;            // All changes
+  count?: number;           // Last N changes
+}
+
+interface RewindResult {
+  success: boolean;
+  revertedFiles: string[];
+  errors: Array<{ path: string; error: string }>;
+}
+```
+
+```typescript
+// src/checkpointing/checkpoint-manager.ts
+class CheckpointManager {
+  private session: CheckpointSession;
+
+  constructor(sessionId: string);
+
+  // Record a file change
+  recordChange(change: Omit<FileCheckpoint, 'id' | 'timestamp'>): void;
+
+  // Get all checkpoints
+  getCheckpoints(): FileCheckpoint[];
+
+  // Get changes for a specific file
+  getFileHistory(path: string): FileCheckpoint[];
+
+  // Rewind changes
+  async rewind(options: RewindOptions): Promise<RewindResult>;
+
+  // Get summary of changes
+  getSummary(): { created: number; modified: number; deleted: number };
+
+  // Clear checkpoints (e.g., after git commit)
+  clearCheckpoints(): void;
+}
+```
+
+### Implementation Approach
+
+1. **Tool Hooking**: Intercept Write and Edit tool executions
+2. **Pre-Change Capture**: Store file content before modification
+3. **Change Recording**: Log all changes with metadata
+4. **Rewind Logic**: Apply inverse operations to restore state
+5. **Persistence**: Store checkpoints in session data
+6. **Git Integration**: Option to use git for versioning
+
+```typescript
+// Wrapping tools with checkpoint tracking
+function withCheckpointing(tool: Tool, checkpointManager: CheckpointManager): Tool {
+  return {
+    ...tool,
+    execute: async (input, context) => {
+      // Capture pre-change state
+      let previousContent: string | null = null;
+      if (tool.name === 'Write' || tool.name === 'Edit') {
+        previousContent = await safeReadFile(input.file_path);
+      }
+
+      // Execute original tool
+      const result = await tool.execute(input, context);
+
+      // Record checkpoint on success
+      if (result.success) {
+        const newContent = await safeReadFile(input.file_path);
+        checkpointManager.recordChange({
+          path: input.file_path,
+          changeType: previousContent === null ? 'create' : 'modify',
+          previousContent,
+          newContent,
+          toolName: tool.name
+        });
+      }
+
+      return result;
+    }
+  };
+}
+```
+
+### Rewind Command
+
+```typescript
+// src/commands/rewind-command.ts
+async function rewindCommand(args: string[], context: CommandContext): Promise<void> {
+  const { checkpointManager, ui } = context;
+
+  if (args[0] === 'all') {
+    const result = await checkpointManager.rewind({ all: true });
+    ui.showMessage(`Reverted ${result.revertedFiles.length} files`);
+  } else if (args[0]) {
+    const checkpointId = args[0];
+    const result = await checkpointManager.rewind({ checkpointId });
+    ui.showMessage(`Reverted: ${result.revertedFiles.join(', ')}`);
+  } else {
+    // Show change list
+    const checkpoints = checkpointManager.getCheckpoints();
+    ui.showChangeList(checkpoints);
+  }
+}
+```
+
+### File Changes
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/checkpointing/types.ts` | Create | Checkpoint type definitions |
+| `src/checkpointing/checkpoint-manager.ts` | Create | Core checkpoint management |
+| `src/checkpointing/tool-wrapper.ts` | Create | Tool wrapping for tracking |
+| `src/checkpointing/index.ts` | Create | Module exports |
+| `src/commands/rewind-command.ts` | Create | /rewind command |
+| `src/tools/write.ts` | Modify | Add checkpoint integration |
+| `src/tools/edit.ts` | Modify | Add checkpoint integration |
+| `src/session/types.ts` | Modify | Add checkpoint data |
+
+## User Experience
+
+### Change Tracking Display
+```
+┌─ File Changes This Session ───────────────────┐
+│                                               │
+│ [1] 5 min ago  src/auth.ts         (modified) │
+│ [2] 4 min ago  src/middleware.ts   (created)  │
+│ [3] 2 min ago  package.json        (modified) │
+│                                               │
+│ Total: 2 modified, 1 created, 0 deleted       │
+└───────────────────────────────────────────────┘
+```
+
+### Rewind Command
+```
+> /rewind
+
+Session has 3 file changes:
+  [1] src/auth.ts (modified) - 5 min ago
+  [2] src/middleware.ts (created) - 4 min ago
+  [3] package.json (modified) - 2 min ago
+
+Usage:
+  /rewind 1        - Revert specific change
+  /rewind all      - Revert all changes
+  /rewind last 2   - Revert last 2 changes
+```
+
+### Rewind Confirmation
+```
+> /rewind all
+
+Are you sure you want to revert 3 file changes?
+  - src/auth.ts (restore previous)
+  - src/middleware.ts (delete)
+  - package.json (restore previous)
+
+[Confirm] [Cancel]
+```
+
+### Rewind Success
+```
+✓ Reverted 3 files:
+  • src/auth.ts - restored
+  • src/middleware.ts - deleted
+  • package.json - restored
+
+Checkpoints cleared.
+```
+
+### Inline Change Indicator
+After each file modification:
+```
+Agent: [Edit] Modified src/auth.ts
+       (checkpoint saved - use /rewind to undo)
+```
+
+## Alternatives Considered
+
+### Alternative 1: Git-Only Versioning
+Rely solely on git for undo.
+
+**Pros**: No extra storage, standard workflow
+**Cons**: Requires git, must commit to checkpoint
+**Decision**: Rejected as primary - git integration as optional enhancement
+
+### Alternative 2: Full File Backups
+Store complete file copies.
+
+**Pros**: Simple, reliable
+**Cons**: Storage intensive for large files
+**Decision**: Partially adopted - store content for reasonable sizes
+
+### Alternative 3: Diff-Based Storage
+Store only diffs between versions.
+
+**Pros**: Space efficient
+**Cons**: Complex, harder to apply reverts
+**Decision**: Deferred - start simple, optimize later
+
+## Security Considerations
+
+1. **Sensitive Data**: Checkpoints may contain sensitive content
+2. **Storage Limits**: Limit total checkpoint size
+3. **Cleanup**: Clear checkpoints on session end
+4. **File Permissions**: Respect file permissions when reverting
+5. **Concurrent Access**: Handle external file modifications
+
+## Testing Strategy
+
+1. **Unit Tests**:
+   - Change recording
+   - Rewind logic for each change type
+   - Multiple file reverts
+
+2. **Integration Tests**:
+   - Tool wrapping
+   - Session persistence
+   - Command handling
+
+3. **Manual Testing**:
+   - Various file operations
+   - Partial reverts
+   - Edge cases (binary files, permissions)
+
+## Migration Path
+
+1. **Phase 1**: Basic Write/Edit tracking and rewind
+2. **Phase 2**: /rewind command with UI
+3. **Phase 3**: Git integration (optional)
+4. **Phase 4**: Selective rewind (by file, by time range)
+5. **Phase 5**: Checkpoint browsing and diff viewing
+
+No breaking changes to existing functionality.
+
+## References
+
+- [Claude Code Checkpointing](https://code.claude.com/docs/en/checkpointing)
+- [Git Reset and Revert](https://git-scm.com/docs/git-reset)

package/docs/proposals/0009-hooks-system.md

@@ -0,0 +1,343 @@
+# Proposal: Hooks System
+
+- **Proposal ID**: 0009
+- **Author**: mycode team
+- **Status**: Draft
+- **Created**: 2025-01-15
+- **Updated**: 2025-01-15
+
+## Summary
+
+Implement an event-driven hooks system that allows users to register shell commands or scripts to run automatically in response to specific events (tool execution, prompt submission, session events). This enables automated workflows, quality gates, and custom integrations.
+
+## Motivation
+
+Currently, mycode has no extensibility for automated actions. This limits:
+
+1. **Quality enforcement**: Can't auto-run linters after edits
+2. **Notifications**: Can't alert users on completion
+3. **Integration**: Can't trigger external systems
+4. **Automation**: Can't enforce coding standards automatically
+5. **Customization**: No way to extend agent behavior
+
+A hooks system enables powerful automation and customization.
+
+## Claude Code Reference
+
+Claude Code provides a comprehensive hooks system:
+
+### Configuration
+```json
+// .claude/settings.json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "type": "command",
+        "command": ".claude/hooks/run-linter.sh $FILE_PATH"
+      }
+    ],
+    "Notification": [
+      {
+        "type": "command",
+        "command": "afplay ~/.claude/sounds/notify.mp3"
+      }
+    ]
+  }
+}
+```
+
+### Available Events
+| Event | Description | Context |
+|-------|-------------|---------|
+| `PreToolUse` | Before tool execution | Tool name, inputs |
+| `PostToolUse` | After tool execution | Tool name, inputs, result |
+| `UserPromptSubmit` | User sends message | Prompt text |
+| `Notification` | Agent needs attention | Message |
+| `Stop` | Agent stops working | Reason |
+| `SessionStart` | Session begins | Session info |
+
+### Hook Types
+1. **Command Mode**: Run shell command directly
+2. **Prompt Mode**: Let LLM decide actions (advanced)
+
+### Matcher Patterns
+- Simple string: `"Edit"` - matches Edit tool
+- Regex: `"Edit|Write"` - matches Edit or Write
+- Wildcard: `"*"` - matches all
+
+### Environment Variables
+Hooks receive context via environment:
+- `$TOOL_NAME` - Name of the tool
+- `$FILE_PATH` - Path of affected file
+- `$EXIT_CODE` - Tool exit code
+- `$SESSION_ID` - Current session
+
+## Detailed Design
+
+### API Design
+
+```typescript
+// src/hooks/types.ts
+type HookEvent =
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'UserPromptSubmit'
+  | 'Notification'
+  | 'Stop'
+  | 'SessionStart'
+  | 'SubagentStop';
+
+type HookType = 'command' | 'prompt';
+
+interface HookDefinition {
+  matcher?: string | RegExp;  // For tool events
+  type: HookType;
+  command?: string;           // For command type
+  prompt?: string;            // For prompt type
+  timeout?: number;           // Max execution time
+  blocking?: boolean;         // Wait for completion
+}
+
+interface HooksConfig {
+  [event: string]: HookDefinition[];
+}
+
+interface HookContext {
+  event: HookEvent;
+  toolName?: string;
+  toolInput?: Record<string, any>;
+  toolResult?: any;
+  prompt?: string;
+  sessionId: string;
+  cwd: string;
+}
+
+interface HookResult {
+  success: boolean;
+  output?: string;
+  error?: string;
+  blocked?: boolean;   // Hook blocked the action
+  message?: string;    // Message to show user
+}
+```
+
+```typescript
+// src/hooks/hooks-manager.ts
+class HooksManager {
+  private config: HooksConfig;
+
+  constructor(config: HooksConfig);
+
+  // Register hooks from settings
+  loadFromSettings(settings: Settings): void;
+
+  // Trigger hooks for an event
+  async trigger(event: HookEvent, context: HookContext): Promise<HookResult[]>;
+
+  // Check if event has hooks
+  hasHooks(event: HookEvent): boolean;
+
+  // Get hooks for event
+  getHooks(event: HookEvent): HookDefinition[];
+
+  // Add hook programmatically
+  addHook(event: HookEvent, hook: HookDefinition): void;
+
+  // Remove hook
+  removeHook(event: HookEvent, index: number): void;
+}
+```
+
+### Implementation Approach
+
+1. **Configuration Loading**: Parse hooks from settings.json
+2. **Event Integration**: Hook into tool execution, prompts, etc.
+3. **Matcher Evaluation**: Match hooks to relevant events
+4. **Command Execution**: Run shell commands with context
+5. **Environment Setup**: Pass context via environment variables
+6. **Result Handling**: Process hook output and blocking
+
+```typescript
+// Hook execution
+async function executeHook(hook: HookDefinition, context: HookContext): Promise<HookResult> {
+  if (hook.type === 'command') {
+    // Build environment
+    const env = {
+      ...process.env,
+      TOOL_NAME: context.toolName || '',
+      FILE_PATH: context.toolInput?.file_path || '',
+      SESSION_ID: context.sessionId,
+      CWD: context.cwd,
+    };
+
+    // Expand variables in command
+    const command = expandVariables(hook.command, context);
+
+    // Execute with timeout
+    const result = await execWithTimeout(command, {
+      env,
+      cwd: context.cwd,
+      timeout: hook.timeout || 30000
+    });
+
+    return {
+      success: result.exitCode === 0,
+      output: result.stdout,
+      error: result.stderr,
+      blocked: result.exitCode !== 0 && hook.blocking
+    };
+  }
+
+  // Prompt mode - more complex, uses LLM
+  // ...
+}
+```
+
+### File Changes
+
+| File | Action | Description |
+|------|--------|-------------|
+| `src/hooks/types.ts` | Create | Hook type definitions |
+| `src/hooks/hooks-manager.ts` | Create | Core hooks management |
+| `src/hooks/executor.ts` | Create | Hook execution logic |
+| `src/hooks/index.ts` | Create | Module exports |
+| `src/agent/agent.ts` | Modify | Integrate hook triggers |
+| `src/tools/registry.ts` | Modify | Tool execution hooks |
+| `src/config/settings-manager.ts` | Modify | Load hooks config |
+
+## User Experience
+
+### Configuration
+Users configure hooks in `.mycode/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "type": "command",
+        "command": "npm run lint:fix $FILE_PATH",
+        "blocking": false
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "afplay ~/.mycode/sounds/done.mp3"
+      }
+    ]
+  }
+}
+```
+
+### Hook Execution Display
+```
+Agent: [Write] Created src/component.tsx
+
+Running hooks...
+  ▶ PostToolUse: npm run lint:fix src/component.tsx
+  ✓ Lint completed (2 issues fixed)
+```
+
+### Blocking Hook
+```
+Agent: [Edit] Modified src/auth.ts
+
+Running hooks...
+  ▶ PostToolUse: npm test -- --related src/auth.ts
+  ✗ Tests failed (2 failures)
+
+Hook blocked further execution. Please fix the failing tests.
+```
+
+### Hook Status
+```
+> /hooks
+
+Active Hooks:
+┌────────────────────┬─────────────────────────────────────┐
+│ Event              │ Action                              │
+├────────────────────┼─────────────────────────────────────┤
+│ PostToolUse        │ npm run lint:fix (Edit|Write)       │
+│ Stop               │ afplay done.mp3                     │
+│ SessionStart       │ echo "Welcome!"                     │
+└────────────────────┴─────────────────────────────────────┘
+```
+
+## Alternatives Considered
+
+### Alternative 1: Plugin-Based Hooks
+Hooks as JavaScript/TypeScript modules.
+
+**Pros**: More powerful, type-safe
+**Cons**: Requires JS knowledge, security concerns
+**Decision**: Deferred - start with shell commands
+
+### Alternative 2: Built-in Actions Only
+Predefined hook actions (lint, test, notify).
+
+**Pros**: Simpler, safer
+**Cons**: Limited flexibility
+**Decision**: Rejected - custom commands are essential
+
+### Alternative 3: Webhook-Based
+HTTP webhooks instead of shell commands.
+
+**Pros**: Remote integration
+**Cons**: Complexity, security, network dependency
+**Decision**: Deferred - can add alongside shell hooks
+
+## Security Considerations
+
+1. **Command Injection**: Sanitize context values in commands
+2. **Timeout Enforcement**: Prevent runaway hooks
+3. **Resource Limits**: Limit concurrent hook executions
+4. **Path Restrictions**: Consider limiting executable paths
+5. **Output Limits**: Truncate large hook outputs
+6. **Privilege Escalation**: Hooks run with user's permissions
+
+```typescript
+// Safe variable expansion
+function expandVariables(command: string, context: HookContext): string {
+  return command
+    .replace(/\$FILE_PATH/g, shellescape([context.toolInput?.file_path || '']))
+    .replace(/\$TOOL_NAME/g, shellescape([context.toolName || '']))
+    // ... etc
+}
+```
+
+## Testing Strategy
+
+1. **Unit Tests**:
+   - Matcher evaluation
+   - Environment building
+   - Variable expansion
+
+2. **Integration Tests**:
+   - Hook triggering from tools
+   - Blocking behavior
+   - Multiple hooks
+
+3. **Manual Testing**:
+   - Various hook configurations
+   - Error handling
+   - Timeout behavior
+
+## Migration Path
+
+1. **Phase 1**: Basic PostToolUse and Stop hooks
+2. **Phase 2**: All event types
+3. **Phase 3**: Blocking hooks
+4. **Phase 4**: /hooks command and UI
+5. **Phase 5**: Prompt-mode hooks
+
+No breaking changes to existing functionality.
+
+## References
+
+- [Claude Code Hooks Documentation](https://code.claude.com/docs/en/hooks)
+- [Understanding Claude Code Full Stack](https://alexop.dev/posts/understanding-claude-code-full-stack/)
+- [Git Hooks](https://git-scm.com/docs/githooks) (similar concept)