luk/GODSPEED_SYNC.md

# 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.