godspeed app sync

2025-08-20 08:30:54 -04:00
parent ca6e4cdf5d
commit c46d53b261
17 changed files with 3170 additions and 45 deletions
--- a/GODSPEED_SYNC.md
+++ b/GODSPEED_SYNC.md
@@ -0,0 +1,250 @@
+# Godspeed Sync
+
+A two-way synchronization tool between the Godspeed task management API and local markdown files.
+
+## Features
+
+- **Bidirectional Sync**: Download tasks from Godspeed to markdown files, edit locally, and upload changes back
+- **Directory Structure**: Creates a clean directory structure matching your Godspeed lists
+- **ID Tracking**: Uses hidden HTML comments to track task IDs even when you rearrange tasks
+- **Markdown Format**: Simple `- [ ] Task name <!-- id:abc123 -->` format for easy editing
+- **Completion Status**: Supports incomplete `[ ]`, completed `[x]`, and cancelled `[-]` checkboxes
+- **Notes Support**: Task notes are preserved and synced
+- **CLI Interface**: Easy-to-use command line interface with shortcuts
+
+## Installation
+
+The Godspeed sync is part of the GTD Terminal Tools project. Make sure you have the required dependencies:
+
+```bash
+# Install dependencies
+uv sync
+
+# Or with pip
+pip install requests click
+```
+
+## Configuration
+
+### Option 1: Environment Variables
+```bash
+export GODSPEED_EMAIL="your@email.com"
+export GODSPEED_PASSWORD="your-password"
+
+# OR use an API token directly
+export GODSPEED_TOKEN="your-api-token"
+
+# Optional: Custom sync directory
+export GODSPEED_SYNC_DIR="~/Documents/MyTasks"
+
+# Optional: Disable SSL verification for corporate networks
+export GODSPEED_DISABLE_SSL_VERIFY="true"
+```
+
+### Option 2: Interactive Setup
+The tool will prompt for credentials if not provided via environment variables.
+
+### Getting an API Token
+You can get your API token from the Godspeed desktop app:
+1. Open the Command Palette (Cmd/Ctrl + Shift + P)
+2. Run "Copy API access token"
+3. Use this token with `GODSPEED_TOKEN` environment variable
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Download all tasks from Godspeed to local markdown files
+python -m src.cli.godspeed download
+# OR use the short alias
+python -m src.cli.godspeed download  # 'gs' will be available when integrated
+
+# Upload local changes back to Godspeed
+python -m src.cli.godspeed upload
+
+# Bidirectional sync (download then upload)
+python -m src.cli.godspeed sync
+
+# Check sync status
+python -m src.cli.godspeed status
+
+# Open sync directory in file manager
+python -m src.cli.godspeed open
+
+# Test connection and SSL (helpful for corporate networks)
+python -m src.cli.godspeed test-connection
+```
+
+### Workflow Example
+
+1. **Initial sync**:
+   ```bash
+   python -m src.cli.godspeed download
+   ```
+
+2. **Edit tasks locally**:
+   Open the generated markdown files in your favorite editor:
+   ```
+   ~/Documents/Godspeed/
+   ├── Personal.md
+   ├── Work_Projects.md
+   └── Shopping.md
+   ```
+
+3. **Make changes**:
+   ```markdown
+   # Personal.md
+   - [ ] Call dentist <!-- id:abc123 -->
+   - [x] Buy groceries <!-- id:def456 -->
+     Don't forget milk and eggs
+   - [-] Old project <!-- id:ghi789 -->
+   - [ ] New task I just added <!-- id:jkl012 -->
+
+   # Work_Projects.md  
+   - [ ] Finish quarterly report <!-- id:xyz890 -->
+     Due Friday
+   - [-] Cancelled meeting <!-- id:uvw567 -->
+   ```
+
+4. **Sync changes back**:
+   ```bash
+   python -m src.cli.godspeed upload
+   ```
+
+## File Format
+
+Each list becomes a markdown file with tasks in this format:
+
+```markdown
+- [ ] Incomplete task <!-- id:abc123 -->
+- [x] Completed task <!-- id:def456 -->
+- [X] Also completed (capital X works too) <!-- id:ghi789 -->
+- [-] Cancelled/cleared task <!-- id:jkl012 -->
+- [ ] Task with notes <!-- id:mno345 -->
+  Notes go on the next line, indented
+```
+
+### Important Notes:
+- **Don't remove the `<!-- id:xxx -->` comments** - they're used to track tasks
+- **Don't worry about the IDs** - they're auto-generated for new tasks
+- **Checkbox format matters**: 
+  - Use `[ ]` for incomplete tasks
+  - Use `[x]` or `[X]` for completed tasks
+  - Use `[-]` for cancelled/cleared tasks
+- **Completion status syncs both ways**: 
+  - Check/uncheck boxes in markdown → syncs to Godspeed
+  - Mark complete/incomplete/cleared in Godspeed → syncs to markdown
+- **Completed/cancelled tasks are hidden**: When downloading from Godspeed, only incomplete tasks appear in local files (keeps them clean)
+- **Notes are optional** - indent them under the task line
+- **File names** correspond to list names (special characters replaced with underscores)
+
+## Directory Structure
+
+By default, files are synced to:
+- `~/Documents/Godspeed/` (if Documents folder exists)
+- `~/.local/share/gtd-terminal-tools/godspeed/` (fallback)
+
+Each Godspeed list becomes a `.md` file:
+- "Personal" → `Personal.md`
+- "Work Projects" → `Work_Projects.md`
+- "Shopping List" → `Shopping_List.md`
+
+## Sync Metadata
+
+The tool stores sync metadata in `.godspeed_metadata.json`:
+```json
+{
+  "task_mapping": {
+    "local-id-1": "godspeed-task-id-1",
+    "local-id-2": "godspeed-task-id-2"
+  },
+  "list_mapping": {
+    "Personal": "godspeed-list-id-1",
+    "Work Projects": "godspeed-list-id-2"
+  },
+  "last_sync": "2024-01-15T10:30:00"
+}
+```
+
+## API Rate Limits
+
+Godspeed has rate limits:
+- **Listing**: 10 requests/minute, 200/hour
+- **Creating/Updating**: 60 requests/minute, 1,000/hour
+
+The sync tool respects these limits and handles errors gracefully.
+
+## Troubleshooting
+
+### SSL/Corporate Network Issues
+If you're getting SSL certificate errors on a corporate network:
+
+```bash
+# Test the connection first
+python -m src.cli.godspeed test-connection
+
+# If SSL errors occur, bypass SSL verification
+export GODSPEED_DISABLE_SSL_VERIFY=true
+python -m src.cli.godspeed test-connection
+```
+
+### Authentication Issues
+```bash
+# Clear stored credentials
+rm ~/.local/share/gtd-terminal-tools/godspeed_config.json
+
+# Use token instead of password
+export GODSPEED_TOKEN="your-token-here"
+```
+
+### Sync Issues
+```bash
+# Check current status
+python -m src.cli.godspeed status
+
+# Verify sync directory
+ls ~/Documents/Godspeed/
+
+# Check metadata
+cat ~/.local/share/gtd-terminal-tools/godspeed/.godspeed_metadata.json
+```
+
+### Common Problems
+
+1. **"List ID not found"**: New lists created locally will put tasks in your Inbox
+2. **"Task not found"**: Tasks deleted in Godspeed won't sync back
+3. **Duplicate tasks**: Don't manually copy task lines between files (IDs must be unique)
+
+## Development
+
+### Testing
+Run the test suite:
+```bash
+python test_godspeed_sync.py
+```
+
+### File Structure
+```
+src/services/godspeed/
+├── __init__.py          # Package init
+├── client.py            # Godspeed API client
+├── sync.py              # Sync engine
+└── config.py            # Configuration management
+
+src/cli/
+└── godspeed.py          # CLI interface
+```
+
+## Contributing
+
+This is part of the larger GTD Terminal Tools project. When contributing:
+
+1. Follow the existing code style
+2. Add tests for new functionality
+3. Update this README for user-facing changes
+4. Test with the mock data before real API calls
+
+## License
+
+Same as the parent GTD Terminal Tools project.