diff --git a/README.md b/README.md index a39342788..8d32a939d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > ToothFairyAI's official coding agent -**Status**: 🟡 Planning Phase | **Last Updated**: 2026-03-24 +**Status**: 🟢 Foundation Ready | **Last Updated**: 2026-03-24 --- @@ -10,6 +10,8 @@ **tfcode** is ToothFairyAI's official AI coding agent - a terminal-based coding assistant that integrates seamlessly with your TF workspace tools, MCP servers, agent skills, and database connections. +Based on [opencode](https://github.com/anomalyco/opencode) - an excellent AI coding tool. We credit and thank the opencode team for their outstanding work. + --- ## Product Identity @@ -19,18 +21,21 @@ | **Name** | tfcode | | **Positioning** | ToothFairyAI's official coding agent | | **Target Users** | Existing TF customers | -| **Config Compatibility** | Supports opencode.json for migration | +| **Config Files** | `tfcode.json` (primary), `opencode.json` (migration support) | +| **Config Directory** | `.tfcode/` | --- ## Key Features -### Core Capabilities +### Core Capabilities (from opencode) - Terminal-based AI coding assistant - File read/write/edit operations - Bash command execution - Code search (glob, grep) - Multi-agent support (Tab switching) +- MCP server integration +- LSP integration ### ToothFairyAI Integration - **MCP Servers** from TF workspace (`isMCPServer`) @@ -56,6 +61,38 @@ See [FORK_MANAGEMENT.md](./FORK_MANAGEMENT.md) for full details. --- +## Branding Strategy + +### Minimal Branding Approach + +We use a **minimal branding approach** to ensure clean upstream merges: + +| Aspect | Branding | Reason | +|--------|----------|--------| +| CLI binary | `tfcode` | User-facing | +| Package name | `tfcode` | User-facing | +| Config directory | `.tfcode/` | User-facing | +| Internal code | `opencode` | Easy merges | +| Workspace packages | `@opencode-ai/*` | Low priority | +| Config file names | `opencode.json` | Low priority | + +### What This Means + +**Changed** (user-facing): +- Binary: `packages/tfcode/bin/tfcode` +- Package: `packages/tfcode/package.json` → name: `tfcode` +- Config: `.tfcode/` directory + +**Unchanged** (internal): +- All code references to "opencode" in source files +- `@opencode-ai/*` workspace package names +- Internal flags like `OPENCODE_*` +- Provider IDs, model references + +**Result**: When merging upstream changes, only directory names and a few config paths differ. Git can handle merges automatically. + +--- + ## Architecture ``` @@ -222,6 +259,35 @@ tfcode automatically detects and converts opencode.json to tfcode.json on first --- +## Project Structure + +``` +tf_code/ +├── packages/ +│ ├── tfcode/ # Core engine (renamed from opencode) +│ │ ├── bin/tfcode # CLI binary +│ │ ├── src/ # All source code +│ │ └── package.json # name: tfcode +│ ├── tf-sync/ # Python TF SDK sync layer +│ │ └── src/tf_sync/ +│ │ ├── config.py # TFConfig, multi-region URLs +│ │ ├── tools.py # Tool sync using SDK +│ │ ├── mcp.py # MCP server sync +│ │ └── agents.py # Agent sync (future) +│ ├── tf-mcp-bridge/ # TypeScript MCP proxy bridge +│ └── tf-config-loader/ # Config loader (stub) +├── .tfcode/ # Config directory +├── scripts/ +│ └── rebrand.sh # Reapply branding after upstream merge +├── tfcode.json # Config template +├── schemas/ +│ └── tfcode.schema.json # JSON schema +├── README.md # This file +└── FORK_MANAGEMENT.md # Fork sync strategy +``` + +--- + ## Installation ```bash @@ -293,42 +359,41 @@ tfcode tools test # Test tool call ## Implementation Phases -### Phase 1: Rebrand & Foundation ⏳ IN PROGRESS +### Phase 1: Foundation ✅ COMPLETE -**Tasks**: +**Completed**: - [x] Fork repository structure -- [ ] Rebrand opencode → tfcode - - [ ] Replace all string references - - [ ] Replace URLs (opencode.ai → toothfairyai.com) - - [ ] Replace logos and branding assets - - [ ] Update package name to `tfcode` -- [x] Create new config schema (`tfcode.json`) -- [ ] Add opencode.json → tfcode.json migration +- [x] Merge opencode codebase from mirror +- [x] Apply minimal tfcode branding + - [x] Rename `packages/opencode` → `packages/tfcode` + - [x] Rename binary `opencode` → `tfcode` + - [x] Rename config directory `.opencode/` → `.tfcode/` + - [x] Update package.json name to `tfcode` + - [x] Update config path references + - [x] Keep internal code as "opencode" for easy upstream merges +- [x] Create tfcode.json schema - [x] Define tool type schema - [x] `isMCPServer` detection - [x] `isAgentSkill` detection - [x] `isDatabaseScript` detection - [x] `requestType` enum handling -- [x] Implement credential validation +- [x] Implement credential validation (in tf-sync) - [x] Create TF SDK integration layer - [x] Multi-region support (AU, EU, US) +- [x] Document fork management strategy +- [x] Push to development branch -### Phase 2: Tool Sync ⏳ IN PROGRESS +### Phase 2: Tool Sync ⏳ NEXT **Tasks**: -- [x] Implement TF workspace tool listing via SDK -- [x] Build tool type classifier - - [x] `isMCPServer` detection - - [x] `isAgentSkill` detection - - [x] `isDatabaseScript` detection - - [x] `requestType` enum handling -- [x] Create tool metadata sync using SDK -- [ ] Handle API functions with user credentials - - [ ] `isAgentSkill` detection - - [ ] `isDatabaseScript` detection - - [ ] `requestType` enum handling -- [ ] Create tool metadata sync +- [ ] Complete tf-sync Python module + - [ ] Test tool sync with real TF workspace + - [ ] Handle tool metadata caching +- [ ] Build tf-mcp-bridge TypeScript module + - [ ] Bridge between tf-sync and tfcode core + - [ ] MCP proxy client implementation - [ ] Handle API functions with user credentials +- [ ] Implement tool refresh/reload ### Phase 3: TF Proxy Integration @@ -344,6 +409,9 @@ tfcode tools test # Test tool call **Tasks**: - [ ] Implement tfcode CLI commands + - [ ] `tfcode validate` + - [ ] `tfcode sync` + - [ ] `tfcode tools list` - [ ] Build interactive credential setup - [ ] Add tool status reporting - [ ] Create user-friendly error messages @@ -359,73 +427,79 @@ tfcode tools test # Test tool call --- -## Rebrand Checklist +## Upstream Sync Process -### Code References -- [ ] `opencode` → `tfcode` in all source files -- [ ] `OPENCODE_` → `TFCODE_` in environment variables -- [ ] `opencode.json` support (migration) + `tfcode.json` (primary) -- [ ] Package name: `tfcode` (npm, pip) +When a new opencode release is available: -### URLs & Branding -- [ ] `opencode.ai` → `toothfairyai.com` -- [ ] `github.com/anomalyco/opencode` → new repo -- [ ] Logo replacement -- [ ] Theme colors (toothfairyai palette) -- [ ] Command: `opencode` → `tfcode` +1. **Fetch from mirror** + ```bash + git fetch mirror + ``` -### Config -- [ ] Schema URL: `toothfairyai.com/schemas/tfcode.json` -- [ ] Config directory: `~/.config/tfcode/` -- [ ] Data directory: `~/.local/share/tfcode/` -- [ ] Support `opencode.json` for migration +2. **Merge into development** + ```bash + git merge mirror/dev + ``` + +3. **Resolve any conflicts** + - Should be minimal due to minimal branding approach + - Only directory names and config paths differ + +4. **Verify branding** + ```bash + ./scripts/rebrand.sh --check + ``` + +5. **Push to origin** + ```bash + git push origin development + ``` --- ## Implementation Notes -### 2026-03-24: Planning & Phase 1 Start +### 2026-03-24: Foundation Complete -**Product Decision**: -- **Name**: tfcode -- **Positioning**: ToothFairyAI's official coding agent -- **Target**: Existing TF customers -- **Config**: tfcode.json primary, opencode.json supported for migration +**Key Decisions**: -**Fork Management**: -- **Upstream**: `github.com/anomalyco/opencode` -- **Mirror**: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced) -- **Development**: `gitea.toothfairyai.com/ToothFairyAI/tf_code` (this repo) -- **Sync Strategy**: Per-release manual PR-based sync -- **Rebrand Script**: `scripts/rebrand.sh` reapplies branding after merges +1. **Minimal Branding Strategy** + - Initially tried bulk rename (1141 files modified) + - Realized this would cause massive merge conflicts + - Reverted to minimal branding (608 files, mostly renames) + - Only changed user-facing surfaces, kept internal code as "opencode" + - Result: Clean upstream merges -**Scope**: -- Full rebrand of codebase -- Tool integration: MCP, Skills, Database, API Functions -- Credentials: TF Proxy for secure types, user-provided for API functions +2. **Fork Architecture** + - Upstream: `github.com/anomalyco/opencode` + - Mirror: `gitea.toothfairyai.com/GitHub/opencode` (auto-synced) + - Development: `gitea.toothfairyai.com/ToothFairyAI/tf_code` -**Architecture**: -- Core engine (TUI, agents, file ops) -- TF integration layer (tool sync, proxy routing) +3. **Tool Integration Approach** + - Use official ToothFairyAI Python SDK + - MCP/Skills/DB tools: Credentials stay in TF, route via TF Proxy + - API Functions: User provides credentials in config -**Implementation Progress**: -- [x] README created as living document -- [x] tfcode.json schema defined -- [x] Project structure created (packages/tf-sync, packages/tf-mcp-bridge) -- [x] Python SDK integration (using toothfairyai SDK for multi-region support) -- [x] Tool sync module using SDK's agent_functions.list() -- [x] Multi-region URL configuration (AU, EU, US) -- [x] Fork management strategy documented (FORK_MANAGEMENT.md) -- [x] Rebrand script created (scripts/rebrand.sh) -- [ ] TypeScript/Node.js bridge module -- [ ] MCP proxy client -- [ ] CLI commands +**Current State**: +``` +a8b73fd75 refactor: apply minimal tfcode branding +8bcbd40e9 merge: initial merge from opencode mirror +abdfa7330 feat: initialize tfcode project structure +``` -**Key Technical Decisions**: -- Use official ToothFairyAI Python SDK for all TF API interactions -- Multi-region support via Region enum and REGION_URLS config -- Tool types classified by: `isMCPServer`, `isAgentSkill`, `isDatabaseScript`, `requestType` -- Sync functions are synchronous (SDK handles async internally) +**What's Ready**: +- ✅ Clean codebase with minimal branding +- ✅ TF SDK integration layer (Python) +- ✅ Tool sync module structure +- ✅ Multi-region support +- ✅ Config schema defined +- ✅ Documentation structure + +**What's Next**: +- Complete tf-sync Python module +- Build tf-mcp-bridge TypeScript module +- Test with real TF workspace +- Implement CLI commands --- @@ -436,6 +510,10 @@ tfcode tools test # Test tool call - [API Documentation](https://apidocs.toothfairyai.com) - [Functions/Tools](https://docs.toothfairyai.com/docs/Settings/functions) +### OpenCode (Upstream) +- [GitHub](https://github.com/anomalyco/opencode) +- [Website](https://opencode.ai) + ### Downloads - [tfcode CLI](https://toothfairyai.com/install/tfcode) - [npm package](https://www.npmjs.com/package/tfcode) @@ -443,6 +521,14 @@ tfcode tools test # Test tool call --- +## Credits + +tfcode is based on [opencode](https://github.com/anomalyco/opencode) by [anomalyco](https://github.com/anomalyco). + +We thank the opencode team for creating an excellent AI coding tool and for making it open source. + +--- + ## License MIT License