# I'll explore this codebase to understand the SpecStory CLI, focusing on the sync command. Let me sta
**Session ID:** `68102df9-70a5-43a4-95d6-4b6fb042fe01` **Project:** /Users/rdmtv/Documents/claydev-local/macos-apps-v2/vscode-specstory **Date:** 2025-12-13T19:55:35.470Z **Slug:** rustling-shimmying-wave

---

## Conversation I'll explore this codebase to understand the SpecStory CLI, focusing on the sync command. Let me start by examining the structure and finding the main entry points. Let me look at the main directory structure and find the CLI entry points: Perfect! I found the CLI entry points. Let me read the main CLI files: Great! Now let me check the sync repository and understand how it handles history files and data: Now let me check how the API routes handle sync and look at additional configuration files: Let me check the config and see how paths are handled: Let me check the database connections to understand path handling better: Perfect! Let me check what's in the CLI output utilities and verify one more important file: Excellent! Let me check one more important file - the API validator for sync to understand the parameters better, and also see what sanitizeProjectPath does: Let me search for sanitizeProjectPath in the entire codebase: Now let me read the claude.ts file where sanitizeProjectPath is defined: Perfect! Now I have all the information I need. Let me compile a comprehensive summary of my findings. ## Summary: SpecStory CLI and Sync Command Based on my exploration of the codebase, here's a detailed analysis of how the SpecStory CLI works and specifically how the sync command functions: ### 1. CLI Entry Point and Architecture **Main Entry Point:** - **File:** `/Users/rdmtv/Documents/claydev-local/macos-apps-v2/vscode-specstory/app/cli/index.ts` - **Framework:** Uses Commander.js for CLI argument parsing - **Command Name:** `specstory-cli` (v0.1.0) - **Execution:** `bun app/cli/index.ts` (uses Bun runtime) ### 2. Available Commands The CLI supports these commands: 1. **import** - Import JSONL session data into SpecStory database - Options: `--global`, `--project `, `--all`, `--force` 2. **export** - Export sessions to markdown or JSON - Options: `--session `, `--project `, `--format `, `--output ` 3. **search** - Search sessions and messages - Options: `--project `, `--limit `, `--json` 4. **sync** - Manage cloud sync status and operations (our focus) 5. **migrate** - Run database migrations - Options: `--dry-run` 6. **stats** - Show database statistics - Options: `--project `, `--json` ### 3. The Sync Command in Detail **Command Definition:** ```typescript program .command('sync') .description('Manage cloud sync status and operations') .option('--status', 'Show sync status') .option('--start ', 'Start sync with provider (icloud|dropbox|google-drive)') .option('--stop ', 'Stop sync by ID') ``` **Usage Examples:** ```bash # Show current sync status bun app/cli/index.ts sync --status # Start syncing with a cloud provider bun app/cli/index.ts sync --start icloud bun app/cli/index.ts sync --start dropbox bun app/cli/index.ts sync --start google-drive # Stop syncing bun app/cli/index.ts sync --stop ``` **Parameters & Options:** | Parameter | Type | Description | |-----------|------|-------------| | `--status` | flag | Display current sync state and configuration | | `--start ` | string | Initiate sync with: `icloud`, `dropbox`, or `google-drive` | | `--stop ` | string | Stop an active sync by its unique ID | ### 4. Sync Command Implementation **Location:** `/Users/rdmtv/Documents/claydev-local/macos-apps-v2/vscode-specstory/app/cli/commands/sync.ts` **How it Works:** 1. **Status Display** (`--status`): - Retrieves sync state from database via `getSyncState()` - Shows: Sync ID, Provider, Status, Last Sync timestamp, Next Sync scheduled, Error messages - If no sync configured, suggests using `--start ` 2. **Start Sync** (`--start `): - Validates provider is one of: `icloud`, `dropbox`, `google-drive` - Creates unique sync ID using `crypto.randomUUID()` - Sets sync status to `'syncing'` - Schedules next sync for 1 hour in the future - Stores state in database - Prints confirmation with Sync ID 3. **Stop Sync** (`--stop `): - Takes sync ID as parameter - Changes status to `'paused'` - Persists to database ### 5. History File Handling & Database **Database Location:** - **Path:** `.specstory/specstory.db` (relative to project root or current working directory) - **Format:** SQLite with Drizzle ORM - **Key Tables:** - `projects` - Project metadata - `history_files` - Tracks .md files in `.specstory/history/` - `cloud_sync_state` - Cloud sync metadata - `ai_rules_backups` - GOOD feature backups - `sessions` - Imported JSONL session data - `session_messages` - Individual messages from sessions **History Files Table Structure:** ```typescript { id: integer (primary key) sessionId: text (links to sessions) filePath: text (relative to .specstory/history/) fileName: text fileSize: integer lastModified: timestamp checksum: text (SHA-256 hash for change detection) projectId: integer (foreign key to projects) createdAt: timestamp } ``` ### 6. Cloud Sync State Management **Sync State Fields:** ```typescript { id: string (UUID) provider: 'icloud' | 'dropbox' | 'google-drive' status: 'idle' | 'syncing' | 'error' | 'paused' lastSyncAt: timestamp | null nextSyncAt: timestamp | null pendingChanges: number cloudWorkspaceId: string (remote workspace identifier) error: string | null } ``` **Sync Status Lifecycle:** 1. `idle` - Ready to sync or no active sync 2. `syncing` - Currently synchronizing 3. `paused` - User paused the sync 4. `error` - Sync failed with error message ### 7. Path Handling **Project Path Sanitization:** The CLI uses `sanitizeProjectPath()` to convert absolute paths to Claude Code's internal format: - Function: Replaces all `/` with `-` and removes leading `-` - Example: `/Users/user/my-project` → `Users-user-my-project` - Location: `/Users/rdmtv/Documents/claydev-local/macos-apps-v2/vscode-specstory/app/db/connections/claude.ts` **Key Paths:** - **Global history:** `~/.claude/history.jsonl` - **Project history:** `~/.claude/projects//*.jsonl` - **SpecStory DB:** `./.specstory/specstory.db` - **Project metadata:** `./.specstory/.project.json` ### 8. API Routes for Sync The sync command interfaces with these REST API endpoints (when running as server): - `GET /api/sync/status` - Get all sync states - `GET /api/sync/status/:projectId` - Get sync for specific project - `POST /api/sync/start/:projectId` - Start sync - `POST /api/sync/complete/:projectId` - Mark complete - `POST /api/sync/fail/:projectId` - Mark failed - `POST /api/sync/pause/:projectId` - Pause sync - `POST /api/sync/resume/:projectId` - Resume sync - `GET /api/sync/stats` - Get sync statistics - `GET /api/sync/errors` - List projects with errors - `GET /api/sync/pending` - List projects with pending changes ### 9. Example Project Configuration The current project has sync enabled: ```json { "workspace_id": "fa73-8d4b-48c3-7919", "workspace_id_at": "2025-12-10T01:51:39.760Z", "project_name": "vscode-specstory", "cloud_sync": true, "user_id": "woojin@superdisco.co" } ``` This file is stored at `.specstory/.project.json`