From ad514a920c41da61214629a16b4e1e08b0ad7065 Mon Sep 17 00:00:00 2001 From: Carlos Gutierrez Date: Wed, 4 Feb 2026 23:14:35 -0500 Subject: [PATCH] docs: update documentation for v0.3.0 - CHANGELOG.md: Add version sections for 0.2.x and 0.3.0, add known issues and planned features linking to GitHub issues #111-#115 - CONTRIBUTING.md: Update prerequisites to Bun, fix file structure to reflect tui-solid migration, update commands to use bun - README.md: Add version badges, roadmap section with v0.4.0 plans, known issues section, and recent changes summary --- README.md | 36 ++++++ docs/CHANGELOG.md | 264 ++++++++++++++++++++++++++++++------------- docs/CONTRIBUTING.md | 82 ++++++++------ 3 files changed, 269 insertions(+), 113 deletions(-) diff --git a/README.md b/README.md index 2720428..d6577bf 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ CodeTyper Logo

+

+ Version + License + Bun +

+ An AI-powered terminal coding agent with an interactive TUI. CodeTyper autonomously executes coding tasks using tool calls with granular permission controls and intelligent provider routing. ## How It Works @@ -392,6 +398,28 @@ Branch and rewind session history for experimentation. Sessions are stored in `.codetyper/sessions/` with automatic commit message suggestions. +## Roadmap + +### v0.4.0 - Agent Completion + +The next major release focuses on production-ready autonomous agent execution: + +| Feature | Issue | Status | +|---------|-------|--------| +| Plan Approval Gate | [#111](https://github.com/CarGDev/codetyper.cli/issues/111) | Planned | +| Diff Preview Before Write | [#112](https://github.com/CarGDev/codetyper.cli/issues/112) | Planned | +| Execution Control (Pause/Resume/Abort) | [#113](https://github.com/CarGDev/codetyper.cli/issues/113) | Planned | +| Consistent Model Behavior | [#114](https://github.com/CarGDev/codetyper.cli/issues/114) | Planned | +| Quality Gates (TypeScript, Lint, Tests) | [#115](https://github.com/CarGDev/codetyper.cli/issues/115) | Planned | + +### Known Issues + +- Agent mode executes without waiting for user plan approval +- Different LLM models may behave inconsistently during agent execution +- No diff preview before file modifications + +See [CHANGELOG](docs/CHANGELOG.md) for full version history. + ## Development ```bash @@ -411,6 +439,14 @@ bun test bun run lint ``` +## Recent Changes (v0.3.0) + +- **System Prompt Builder**: New modular prompt system with modes, tiers, and providers +- **Module Restructure**: Consistent internal organization with improved imports +- **Solid.js TUI**: Fully migrated to Solid.js + OpenTUI (removed legacy React/Ink) + +See [CHANGELOG](docs/CHANGELOG.md) for complete version history. + ## Documentation - [Changelog](docs/CHANGELOG.md) - Version history and changes diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 61dc467..7274b38 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Planned + +- **Plan Approval Gate**: Require user confirmation before agent executes plans ([#111](https://github.com/CarGDev/codetyper.cli/issues/111)) +- **Diff Preview**: Show file changes before writing ([#112](https://github.com/CarGDev/codetyper.cli/issues/112)) +- **Execution Control**: Pause, resume, and abort agent execution ([#113](https://github.com/CarGDev/codetyper.cli/issues/113)) +- **Model Consistency**: Ensure consistent behavior across LLM providers ([#114](https://github.com/CarGDev/codetyper.cli/issues/114)) +- **Quality Gates**: Run TypeScript, lint, and tests before task completion ([#115](https://github.com/CarGDev/codetyper.cli/issues/115)) + +### Known Issues + +- Agent mode executes without waiting for user plan approval +- Different LLM models behave inconsistently during agent execution +- No diff preview before file modifications + +--- + +## [0.3.0] - 2025-02-04 + +### Added + +- **System Prompt Builder**: New modular prompt system with modes, tiers, and providers + - Separate prompt templates for different agent modes + - Provider-specific prompt optimizations + - Tier-based prompt complexity (basic, standard, advanced) + +### Changed + +- **Restructured `src/` Modules**: Consistent internal organization across all modules + - Deleted legacy `index.ts` barrel exports + - Improved import paths with path aliases + - Better separation of concerns + +### Removed + +- **Legacy React/Ink TUI**: Removed old TUI implementation + - Migrated fully to Solid.js + OpenTUI + - Fixed TypeScript errors from removal + +### Fixed + +- Import paths in utils folder +- MCP initialization issues + +--- + +## [0.2.4] - 2025-02-01 + +### Fixed + +- MCP server connection stability improvements +- Various MCP-related bug fixes + +--- + +## [0.2.3] - 2025-01-31 + +### Fixed + +- MCP form input handling for server configuration +- Reactive MCP server state updates +- MCP server issues and stability + +### Added + +- `BRAIN_DISABLED` flag for disabling Brain API integration +- Ollama tool call formatting improvements + +--- + +## [0.2.2] - 2025-01-30 + +### Fixed + +- App store initialization issue +- General stability improvements + +--- + +## [0.2.1] - 2025-01-29 + +### Added + +- **MCP Server Searcher**: Browse and discover MCP servers + - Interactive browser with `/mcp browse` + - Search servers with `/mcp search ` + - Filter by category (database, web, AI, dev-tools, etc.) + - View server details and required environment variables + - One-click install with `/mcp install ` + - 15+ curated verified servers from Anthropic + - Popular servers list with `/mcp popular` + - Category listing with `/mcp categories` + +--- + +## [0.2.0] - 2025-01-28 + ### Added - **Hooks System**: Lifecycle hooks for extensibility @@ -41,81 +137,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Mode indicator in status line - Configurable via settings.json -- **Home Screen**: New welcome screen with centered gradient logo - - Displays version, provider, and model info - - Transitions to session view on first message - - Clean, centered layout +--- -- **MCP Integration**: Model Context Protocol server support - - Connect to external MCP servers - - Use tools from connected servers - - `/mcp` command for server management - - Status display in UI - - **MCP Server Browser**: Search and discover MCP servers - - Interactive browser with `/mcp browse` - - Search servers with `/mcp search ` - - Filter by category (database, web, AI, dev-tools, etc.) - - View server details and required environment variables - - One-click install with `/mcp install ` - - 15+ curated verified servers from Anthropic - - Registry integration with Smithery +## [0.1.80] - 2025-01-27 -- **Reasoning System**: Advanced agent orchestration - - Memory selection for context optimization - - Quality evaluation of responses - - Termination detection for agent loops - - Context compression for long conversations - - Retry policies with exponential backoff +### Fixed -- **Todo Panel**: Task tracking during sessions - - Toggle visibility with `Ctrl+T` - - `todo-read` and `todo-write` tools - - Zustand-based state management +- Prompt template issues +- Agent response formatting -- **Theme System**: Customizable color themes - - `/theme` command to switch themes - - Dark, Light, Tokyo Night, Dracula themes - - Persistent theme preference +--- -- **Agent Selection**: Switch between agent modes - - `/agent` command for selection - - Coder, Architect, Reviewer agents - -- **Learning System**: Knowledge persistence - - Vector store for embeddings - - Semantic search capabilities - - Project learnings storage - -- **Streaming Responses**: Real-time message display - - Faster feedback from LLM - - Progress indicators - -- **Enhanced Navigation**: - - `PageUp/PageDown` for fast scrolling - - `Shift+Up/Down` for line-by-line scroll - - `Ctrl+Home/End` to jump to top/bottom - -- **Optimized Permissions**: Performance improvements - - Pattern caching - - Indexed pattern matching - - Faster permission checks - -- **Auto-Compaction**: Context management - - Automatic conversation compression - - Maintains context within limits +## [0.1.79] - 2025-01-26 ### Changed -- Improved session header with token count and context percentage -- Enhanced status bar with MCP connection info -- Better command menu with more commands +- Version bump with minor fixes + +--- + +## [0.1.78] - 2025-01-25 + +### Changed + +- **Improved Agent Autonomy**: Better task execution flow +- **Enhanced Diff View**: Improved readability for file changes + - Better color contrast + - Clearer line indicators + +--- + +## [0.1.77] - 2025-01-24 + +### Added + +- **Debug Log Panel**: View internal logs for troubleshooting +- **Centered Modals**: Improved modal positioning and appearance + +### Fixed + +- Multiple UX issues +- Modal positioning on different terminal sizes +- Input focus handling + +--- + +## [0.1.76] - 2025-01-23 + +### Fixed + +- Installation issues with npm link +- Package distribution problems + +--- + +## [0.1.75] - 2025-01-22 + +### Fixed + +- Repository URL in package.json +- Package metadata corrections + +--- ## [0.1.0] - 2025-01-16 ### Added -- **Interactive TUI**: Full terminal UI using Ink (React for CLIs) - - Message-based input (Enter to send, Alt+Enter for newlines) +- **Interactive TUI**: Full terminal UI using Solid.js + OpenTUI + - Message-based input (Enter to send, Shift+Enter for newlines) - Log panel showing conversation history - Status bar with session info - ASCII banner header @@ -136,10 +226,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `read` - Read file contents - `write` - Create or overwrite files - `edit` - Find and replace in files + - `glob` - Find files by pattern + - `grep` - Search file contents - **Provider Support**: - - GitHub Copilot (default) - OAuth device flow authentication, access to GPT-4o, GPT-5, Claude, Gemini via Copilot API - - Ollama - Local server (no auth), run any local model + - GitHub Copilot (default) - OAuth device flow authentication + - Ollama - Local server (no auth) + +- **Cascading Provider System**: Intelligent routing between providers + - Quality scoring per task type + - Automatic provider selection based on performance - **Session Management**: - Persistent session storage @@ -151,22 +247,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `codetyper ` - Start with initial prompt - `codetyper login ` - Authenticate with provider - `codetyper status` - Show provider status - - `codetyper config` - Manage configuration -### Changed - -- Migrated from readline-based input to Ink TUI -- Removed classic mode in favor of TUI-only interface -- Tool output now captured and displayed in log panel (not streamed to stdout) - -### Fixed - -- Permission modal not showing in TUI mode -- Input area blocking during command execution -- Rate limit handling for Copilot provider (429 errors) +- **Theme System**: 14+ built-in color themes +- **Todo Panel**: Task tracking with `Ctrl+T` +- **Home Screen**: Welcome screen with version info --- -## Version History +## Version History Summary -- **0.1.0** - Initial release with TUI, agent system, and multi-provider support +| Version | Date | Highlights | +|---------|------|------------| +| 0.3.0 | 2025-02-04 | System prompt builder, module restructure, legacy TUI removal | +| 0.2.x | 2025-01-28 - 02-01 | Hooks, plugins, session forks, vim motions, MCP browser | +| 0.1.x | 2025-01-16 - 01-27 | Initial release, TUI, agent system, providers, permissions | + +--- + +[Unreleased]: https://github.com/CarGDev/codetyper.cli/compare/v0.3.0...HEAD +[0.3.0]: https://github.com/CarGDev/codetyper.cli/compare/v0.2.4...v0.3.0 +[0.2.4]: https://github.com/CarGDev/codetyper.cli/compare/v0.2.3...v0.2.4 +[0.2.3]: https://github.com/CarGDev/codetyper.cli/compare/v0.2.2...v0.2.3 +[0.2.2]: https://github.com/CarGDev/codetyper.cli/compare/v0.2.1...v0.2.2 +[0.2.1]: https://github.com/CarGDev/codetyper.cli/compare/v0.2.0...v0.2.1 +[0.2.0]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.80...v0.2.0 +[0.1.80]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.79...v0.1.80 +[0.1.79]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.78...v0.1.79 +[0.1.78]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.77...v0.1.78 +[0.1.77]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.76...v0.1.77 +[0.1.76]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.75...v0.1.76 +[0.1.75]: https://github.com/CarGDev/codetyper.cli/compare/v0.1.0...v0.1.75 +[0.1.0]: https://github.com/CarGDev/codetyper.cli/releases/tag/v0.1.0 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9a26f4b..0a03cdc 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -10,8 +10,7 @@ Please be respectful and constructive in all interactions. We welcome contributo ### Prerequisites -- Node.js >= 18.0.0 -- npm or yarn +- [Bun](https://bun.sh) >= 1.0.0 - Git ### Setup @@ -19,36 +18,42 @@ Please be respectful and constructive in all interactions. We welcome contributo 1. Fork the repository 2. Clone your fork: ```bash - git clone https://github.com/YOUR_USERNAME/codetyper-cli.git - cd codetyper-cli + git clone https://github.com/YOUR_USERNAME/codetyper.cli.git + cd codetyper.cli ``` 3. Install dependencies: ```bash - npm install + bun install ``` 4. Build the project: ```bash - npm run build + bun run build ``` 5. Link for local testing: ```bash - npm link + bun link ``` ### Development Workflow ```bash -# Start TypeScript watch mode -npm run dev +# Start development mode +bun run dev + +# Watch mode with auto-rebuild +bun run dev:watch # Run tests -npm test +bun test + +# Type check +bun run typecheck # Lint code -npm run lint +bun run lint # Format code -npm run format +bun run prettier ``` ## How to Contribute @@ -84,7 +89,7 @@ npm run format 4. Ensure all tests pass: ```bash - npm test + bun test ``` 5. Commit with clear messages: @@ -134,30 +139,37 @@ docs: update README with new CLI options ``` src/ ├── index.ts # Entry point only +├── api/ # API clients (Copilot, Ollama, Brain) ├── commands/ # CLI command implementations ├── constants/ # Centralized constants ├── interfaces/ # Interface definitions +├── prompts/ # System prompts and prompt templates ├── providers/ # LLM provider integrations ├── services/ # Business logic services -│ ├── hooks-service.ts # Lifecycle hooks -│ ├── plugin-service.ts # Plugin management -│ ├── plugin-loader.ts # Plugin discovery -│ └── session-fork-service.ts # Session forking +│ ├── core/ # Core agent and orchestration +│ ├── hooks/ # Lifecycle hooks +│ ├── plugin/ # Plugin management +│ └── session/ # Session management and forking +├── skills/ # Agent skill definitions ├── stores/ # Zustand state stores -│ └── vim-store.ts # Vim mode state -├── tools/ # Agent tools (bash, read, write, edit) -├── tui/ # Terminal UI components +├── tools/ # Agent tools (bash, read, write, edit, etc.) +├── tui-solid/ # Terminal UI (Solid.js + OpenTUI) │ ├── components/ # Reusable UI components -│ └── hooks/ # React hooks (useVimMode, etc.) -└── types/ # Type definitions +│ ├── context/ # Solid.js context providers +│ ├── routes/ # TUI route components +│ └── ui/ # Base UI primitives +├── types/ # Type definitions +├── ui/ # Print-mode UI components +└── utils/ # Utility functions ``` ### Testing - Write tests for non-UI logic -- Place tests in `tests/` directory +- Place tests in `tests/` directory or colocate with source files - Name test files `*.test.ts` - Use descriptive test names +- Tests run with Vitest via `bun test` ```typescript describe('PermissionManager', () => { @@ -180,16 +192,16 @@ describe('PermissionManager', () => { | File | Purpose | |------|---------| | `src/index.ts` | CLI entry point, command registration | -| `src/services/agent.ts` | Agent loop, tool orchestration | -| `src/services/permissions.ts` | Permission system | -| `src/services/hooks-service.ts` | Lifecycle hooks | -| `src/services/plugin-service.ts` | Plugin management | -| `src/services/session-fork-service.ts` | Session forking | -| `src/commands/chat-tui.tsx` | Main TUI command | -| `src/tui/App.tsx` | Root TUI component | -| `src/tui/store.ts` | Zustand state management | -| `src/stores/vim-store.ts` | Vim mode state | -| `src/tui/hooks/useVimMode.ts` | Vim keyboard handling | +| `src/services/core/agent.ts` | Agent loop, tool orchestration | +| `src/services/permissions/` | Permission system | +| `src/services/hooks/` | Lifecycle hooks | +| `src/services/plugin/` | Plugin management | +| `src/services/session/` | Session forking | +| `src/tui-solid/app.tsx` | Root TUI component (Solid.js) | +| `src/tui-solid/components/` | UI components | +| `src/stores/` | Zustand state management | +| `src/prompts/` | System prompt templates | +| `src/tools/` | Tool implementations | ### Adding a New Provider @@ -225,8 +237,8 @@ describe('PermissionManager', () => { ### Adding Vim Bindings -1. Add binding to `VIM_DEFAULT_BINDINGS` in `src/constants/vim.ts` -2. Add action handler in `src/tui/hooks/useVimMode.ts` +1. Add binding to vim constants in `src/constants/` +2. Add action handler in the vim store (`src/stores/`) 3. Update documentation ## Questions?