feat: sync

docs/sync-implementation.md

@@ -0,0 +1,115 @@
+# tfcode Sync Implementation Summary
+
+## What's Implemented
+
+### 1. Postinstall Script (`packages/tfcode/scripts/postinstall.cjs`)
+- Checks for Python 3.10+ installation
+- Auto-installs ToothFairyAI Python SDK on `npm install tfcode`
+- Handles externally-managed environments (Homebrew, etc.)
+- Shows clear error messages if Python is missing
+
+### 2. Python Sync Module (`packages/tf-sync/src/tf_sync/`)
+- `config.py` - Configuration management, credential validation, multi-region support
+- `tools.py` - Sync API functions from TF workspace
+- `mcp.py` - Reserved for future MCP support (not in SDK yet)
+
+### 3. CLI Commands (`packages/tfcode/src/cli/cmd/tools.ts`)
+- `tfcode validate` - Validate TF credentials
+- `tfcode sync` - Sync tools from workspace
+- `tfcode tools list [--type]` - List synced tools
+- `tfcode tools credentials <name> --set/--show` - Manage API keys
+- `tfcode tools debug <name>` - Debug tool configuration
+
+### 4. Region Support
+| Region | Base URL | Use Case |
+|--------|----------|----------|
+| `dev` | api.toothfairylab.link | Development |
+| `au` | api.toothfairyai.com | Australia (Default) |
+| `eu` | api.eu.toothfairyai.com | Europe |
+| `us` | api.us.toothfairyai.com | United States |
+
+## Test Results
+
+```bash
+$ python3 scripts/test-sync.py
+
+============================================================
+tfcode Sync Test
+============================================================
+
+Test 1: Load Configuration
+----------------------------------------
+✓ Workspace ID: 6586b7e6-683e-4ee6-a6cf-24c19729b5ff
+✓ Region: dev
+✓ API URL: https://api.toothfairylab.link
+
+Test 2: Validate Credentials
+----------------------------------------
+✓ Credentials valid
+  Workspace: Connected
+  ID: 6586b7e6-683e-4ee6-a6cf-24c19729b5ff
+
+Test 3: Sync Tools
+----------------------------------------
+✓ Synced 100 tools
+
+By type:
+  api_function: 100
+
+Sample tools:
+  🌐 get_kanban_projects (api_function)
+  🌐 azure_costs_test_official (api_function)
+  ... and 95 more
+```
+
+## SDK Capabilities (Current)
+
+The ToothFairyAI Python SDK currently exposes:
+- `agent_functions` - API Functions with `request_type` (get/post/put/delete/etc.)
+- `connections` - Provider connections (openai, anthropic, groq, etc.)
+- `agents` - TF workspace agents
+
+**Not yet exposed:**
+- MCP servers (`isMCPServer`)
+- Agent skills (`isAgentSkill`)
+- Database scripts (`isDatabaseScript`)
+
+These will be added to the SDK in the future. For now, MCP servers must be configured manually in `tfcode.json`.
+
+## Environment Setup
+
+```bash
+export TF_WORKSPACE_ID="your-workspace-id"
+export TF_API_KEY="your-api-key"
+export TF_REGION="dev"  # or au, eu, us
+```
+
+## Usage
+
+```bash
+# Install
+npm install -g tfcode
+
+# Or with bun
+cd packages/tf-sync && python3 -m pip install -e . --break-system-packages
+cd packages/tfcode && bun install
+
+# Validate
+tfcode validate
+
+# Sync
+tfcode sync
+
+# List tools
+tfcode tools list
+```
+
+## Files Created/Modified
+
+- `packages/tfcode/scripts/postinstall.cjs` - Postinstall script
+- `packages/tfcode/src/cli/cmd/tools.ts` - CLI commands
+- `packages/tf-sync/src/tf_sync/config.py` - Config + regions
+- `packages/tf-sync/src/tf_sync/tools.py` - Tool sync
+- `packages/tf-sync/src/tf_sync/mcp.py` - MCP placeholder
+- `scripts/test-sync.py` - Test script
+- `scripts/setup-tf-dev.sh` - Dev environment setup