@khoaha/spek-cli 1.0.3

package/QUICKSTART.md

@@ -0,0 +1,253 @@
+# Quick Start Guide
+
+Get started with `spek-cli` CLI tool in 5 minutes.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- Access to a Directus instance with Vault Export
+- A file ID from the Figma SpeX plugin
+
+## Step 1: Get Your File ID
+
+### From Figma Plugin
+
+1. Open your Figma file
+2. Launch the **SpeX** plugin
+3. Navigate to **"Vault Export"** tab
+4. Click **"Export to Vault"**
+5. Wait for export to complete
+6. Copy the **File ID** from the success dialog
+
+**Example File ID:**
+```
+abc123-def456-ghi789-jkl012
+```
+
+## Step 2: Run the CLI Tool
+
+Open your terminal and navigate to where you want the specs:
+
+```bash
+# Create a directory for your specs
+mkdir my-design-specs
+cd my-design-specs
+
+# Run the CLI tool
+npx spek-cli -d abc123-def456-ghi789-jkl012
+```
+
+## Step 3: First-Time Setup
+
+If this is your first time running the tool, you'll be prompted for configuration:
+
+```bash
+📦 spek-cli
+
+🔧 Configuration not found. Let's set it up!
+
+? Enter your Directus instance URL: https://my-company.directus.app
+? Enter your Directus access token: ********************************
+```
+
+### Getting Your Access Token
+
+1. Log in to your Directus instance
+2. Go to **User Settings** → **Access Tokens**
+3. Click **"Create New Token"**
+4. Give it a name (e.g., "CLI Tool")
+5. Set permissions: **Read** access to **Files**
+6. Copy the generated token
+7. Paste it into the CLI prompt
+
+## Step 4: Download Complete!
+
+Once configured, the download will proceed automatically:
+
+```bash
+✓ Configuration saved to ~/.spek-cli/config.json
+
+📥 Downloading file: abc123-def456-ghi789-jkl012...
+✓ Download complete
+🔍 Validating ZIP file...
+✓ ZIP file is valid
+📦 Extracting files...
+✓ Files extracted successfully
+
+✓ Success! Files extracted to current directory
+```
+
+## Step 5: Explore Your Specs
+
+Check what was downloaded:
+
+```bash
+ls
+```
+
+**Typical Structure:**
+```
+my-design-specs/
+├── README.md              # Overview and usage guide
+├── manifest.json          # Component manifest
+├── components/            # Component specifications
+│   ├── Button.yaml
+│   ├── Card.yaml
+│   └── ...
+├── icons/                 # Icon assets
+│   ├── icon-home.svg
+│   ├── icon-user.svg
+│   └── ...
+└── images/                # Image assets
+    └── ...
+```
+
+## Next Steps
+
+### Use with Cursor AI
+
+1. Start the MCP server:
+   ```bash
+   npx spex-mcp --mode local --port 8080
+   ```
+
+2. Open your project in Cursor
+
+3. Ask Cursor to generate components:
+   ```
+   "Generate a Button component based on the design specs"
+   ```
+
+### Download More Specs
+
+For subsequent downloads, just provide the file ID:
+
+```bash
+# No setup prompts - uses saved config
+npx spek-cli -d new-file-id-xyz
+```
+
+### Interactive Mode
+
+Run without arguments to be prompted for the file ID:
+
+```bash
+npx spek-cli
+
+? Enter the file ID to download: abc123-def456-ghi789
+```
+
+## Common Commands
+
+```bash
+# Direct download
+npx spek-cli -d <file-id>
+
+# Interactive mode
+npx spek-cli
+
+# Show help
+npx spek-cli --help
+
+# Show version
+npx spek-cli --version
+```
+
+## Troubleshooting
+
+### "Authentication failed"
+
+**Problem:** Your access token is invalid or expired.
+
+**Solution:**
+```bash
+# Delete config and re-setup
+rm ~/.spek-cli/config.json
+npx spek-cli -d <file-id>
+```
+
+### "File not found"
+
+**Problem:** The file ID doesn't exist or you don't have access.
+
+**Solution:**
+1. Verify the file ID is correct
+2. Check the file exists in Directus
+3. Ensure your token has read access
+
+### "Files already exist"
+
+**Problem:** You're downloading to a directory with existing files.
+
+**Solution:**
+The CLI will prompt you:
+```
+? Files already exist in current directory. Overwrite? (y/N)
+```
+- Choose **Yes** to overwrite
+- Choose **No** to cancel
+
+### Config Location
+
+Your configuration is stored at:
+- **Windows:** `C:\Users\<username>\.spek-cli\config.json`
+- **macOS:** `/Users/<username>/.spek-cli/config.json`
+- **Linux:** `/home/<username>/.spek-cli/config.json`
+
+## Tips
+
+### 1. Organize by Version
+
+```bash
+mkdir -p specs/v1.0 specs/v1.1
+cd specs/v1.0 && npx spek-cli -d file-id-v1
+cd ../v1.1 && npx spek-cli -d file-id-v2
+```
+
+### 2. Use with Git
+
+```bash
+cd my-project
+mkdir design-specs
+cd design-specs
+npx spek-cli -d <file-id>
+git add .
+git commit -m "Add design specs"
+```
+
+### 3. Create a Script
+
+**download-specs.sh:**
+```bash
+#!/bin/bash
+mkdir -p specs/$(date +%Y%m%d)
+cd specs/$(date +%Y%m%d)
+npx spek-cli -d $1
+```
+
+**Usage:**
+```bash
+chmod +x download-specs.sh
+./download-specs.sh abc123-def456-ghi789
+```
+
+## Need Help?
+
+- **Documentation:** [Full README](./README.md)
+- **Architecture:** [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+- **Examples:** [docs/USAGE_EXAMPLES.md](./docs/USAGE_EXAMPLES.md)
+- **Testing:** [docs/TESTING.md](./docs/TESTING.md)
+- **Workflow:** [docs/WORKFLOW.md](./docs/WORKFLOW.md)
+
+## Summary
+
+That's it! You're now ready to use `spek-cli` to download design specs from Directus.
+
+**Quick Recap:**
+1. ✅ Get file ID from Figma plugin
+2. ✅ Run `npx spek-cli -d <file-id>`
+3. ✅ Configure on first run (Directus URL + token)
+4. ✅ Specs downloaded and extracted
+5. ✅ Use with Cursor AI for code generation
+
+**Happy coding! 🚀**

package/README.md

@@ -0,0 +1,154 @@
+# spek-cli
+
+CLI tool to download and extract Figma design specs from Directus.
+
+## Installation
+
+```bash
+npx spek-cli
+```
+
+## Usage
+
+### Interactive Mode
+
+Simply run without arguments to be prompted for the file ID:
+
+```bash
+npx spek-cli
+```
+
+### Direct Download
+
+Download a specific file by ID:
+
+```bash
+npx spek-cli -d <file-id>
+# or
+npx spek-cli --download <file-id>
+```
+
+### First Run Setup
+
+On first run, you'll be prompted to configure:
+
+1. **Directus Instance URL**: Your Directus instance (e.g., `https://my-instance.directus.app`)
+2. **Access Token**: Your Directus access token for authentication
+
+Configuration is saved to `~/.spek-cli/config.json`
+
+## Features
+
+- ✅ Download files from Directus using official SDK
+- ✅ Automatic authentication with access token
+- ✅ Extract ZIP files to named folder (based on filename)
+- ✅ Prompt before overwriting existing folders
+- ✅ Auto-setup configuration on first run
+- ✅ Interactive and direct command modes
+
+## Configuration
+
+Configuration file location: `~/.spek-cli/config.json`
+
+```json
+{
+  "directusUrl": "https://my-instance.directus.app",
+  "accessToken": "your-access-token",
+  "createdAt": "2026-02-13T..."
+}
+```
+
+## Examples
+
+```bash
+# First time - interactive setup
+npx spek-cli
+# Prompts for: Directus URL, Access Token, File ID
+
+# Subsequent runs - direct download
+npx spek-cli -d abc123-def456-ghi789
+
+# Interactive mode (prompts for file ID only)
+npx spek-cli
+```
+
+### Output Structure
+
+When you download a file, it will be extracted into a folder named after the file:
+
+```bash
+# If the file in Directus is named "design-specs-v1.zip"
+npx spek-cli -d abc123
+
+# Creates structure:
+./design-specs-v1/
+├── README.md
+├── manifest.json
+├── components/
+├── icons/
+└── images/
+```
+
+## Error Handling
+
+The CLI handles common errors gracefully:
+
+- **Invalid authentication**: Check your access token
+- **File not found**: Verify the file ID exists in Directus
+- **Network errors**: Check your internet connection
+- **Corrupted ZIP**: The downloaded file is invalid
+- **Permission errors**: Ensure write access to current directory
+
+## Help
+
+```bash
+npx spek-cli --help
+```
+
+## Version
+
+```bash
+npx spek-cli --version
+```
+
+## Development
+
+This CLI tool is part of the specs-figma monorepo.
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+### Local Testing
+
+**Linux/macOS:**
+```bash
+# Build first
+npm run build
+
+# Run locally
+node dist/index.js -d <file-id>
+```
+
+**Windows:**
+```powershell
+# Build first
+npm run build
+
+# Run locally
+node dist/index.js -d <file-id>
+```
+
+**Note for Windows users:** See [WINDOWS_DEVELOPMENT.md](./WINDOWS_DEVELOPMENT.md) for detailed Windows-specific development guide.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// Windows-compatible CLI wrapper
+import('../dist/index.js').catch((error) => {
+  console.error('Failed to load CLI:', error);
+  process.exit(1);
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,286 @@
+# CLI Tool Architecture
+
+## Overview
+
+`spek-cli` is a standalone CLI tool for downloading and extracting Figma design specs from Directus vault storage. It's built with TypeScript and uses the official Directus SDK for authentication and file downloads.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         User                                │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    CLI Entry Point                          │
+│                    (src/index.ts)                           │
+│  • Parse arguments (-d, --download, --help, --version)      │
+│  • Orchestrate workflow                                     │
+└────────────┬────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Configuration Manager                          │
+│              (src/config/manager.ts)                        │
+│  • Check if config exists                                   │
+│  • Load from ~/.spek-cli/config.json                     │
+│  • Save new configuration                                   │
+└────────────┬────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  Prompts Module                             │
+│                (src/prompts/index.ts)                       │
+│  • Prompt for Directus URL (first run)                      │
+│  • Prompt for access token (first run)                      │
+│  • Prompt for file ID (interactive mode)                    │
+│  • Prompt for overwrite confirmation                        │
+└────────────┬────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Directus Client                               │
+│              (src/directus/client.ts)                       │
+│  • Create authenticated Directus SDK client                 │
+│  • Download file using readAssetRaw()                       │
+│  • Handle authentication and errors                         │
+└────────────┬────────────────────────────────────────────────┘
+             │
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Download Handler                               │
+│            (src/download/handler.ts)                        │
+│  • Download file to temp location                           │
+│  • Validate ZIP file                                        │
+│  • Check for existing files                                 │
+│  • Extract to current working directory                     │
+│  • Cleanup temp files                                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Module Breakdown
+
+### 1. Entry Point (`src/index.ts`)
+
+**Responsibilities:**
+- Parse command-line arguments
+- Check/initialize configuration
+- Orchestrate the download workflow
+- Handle errors and display results
+
+**Key Functions:**
+- `parseArgs()` - Parse CLI arguments
+- `showHelp()` - Display help message
+- `showVersion()` - Display version
+- `main()` - Main entry point
+
+**Flow:**
+```
+1. Parse arguments
+2. Load or initialize config
+3. Get file ID (from args or prompt)
+4. Call download handler
+5. Display result
+```
+
+### 2. Configuration Manager (`src/config/manager.ts`)
+
+**Responsibilities:**
+- Manage configuration file at `~/.spek-cli/config.json`
+- Load, save, and validate configuration
+- Ensure config directory exists
+
+**Key Functions:**
+- `configExists()` - Check if config file exists
+- `loadConfig()` - Load configuration from disk
+- `saveConfig()` - Save configuration to disk
+- `getConfigPath()` - Get config file path
+
+**Configuration Structure:**
+```typescript
+interface VaultConfig {
+  directusUrl: string;      // e.g., https://my.directus.app
+  accessToken: string;      // Directus access token
+  createdAt: string;        // ISO timestamp
+}
+```
+
+### 3. Prompts Module (`src/prompts/index.ts`)
+
+**Responsibilities:**
+- Interactive user input collection
+- Validation of user inputs
+- Confirmation dialogs
+
+**Key Functions:**
+- `promptForConfig()` - First-run configuration setup
+- `promptForFileId()` - Get file ID in interactive mode
+- `promptOverwrite()` - Confirm overwrite of existing files
+
+**Uses:** `prompts` package (v2.4.2) for user-friendly CLI prompts
+
+### 4. Directus Client (`src/directus/client.ts`)
+
+**Responsibilities:**
+- Create authenticated Directus SDK client
+- Download files from Directus assets
+- Handle authentication and API errors
+
+**Key Functions:**
+- `createAuthenticatedClient()` - Initialize Directus client
+- `downloadFile()` - Download file by ID
+
+**Error Handling:**
+- 401: Authentication failed
+- 404: File not found
+- Network errors: Connection issues
+
+**Implementation Details:**
+- Uses `@directus/sdk` with `authentication()` and `rest()` modules
+- Converts `ReadableStream` to `Buffer` for file processing
+- Sets access token before making requests
+
+### 5. Download Handler (`src/download/handler.ts`)
+
+**Responsibilities:**
+- Orchestrate download and extraction process
+- Validate ZIP files
+- Check for file conflicts
+- Extract to current working directory
+- Cleanup temporary files
+
+**Key Functions:**
+- `checkExistingFiles()` - Check if extraction would overwrite files
+- `handleDownload()` - Main download and extract workflow
+
+**Flow:**
+```
+1. Download file from Directus
+2. Save to temp file
+3. Validate ZIP structure
+4. Check for existing files
+5. Prompt for overwrite if needed
+6. Extract to CWD
+7. Cleanup temp files
+8. Return result
+```
+
+**Uses:** `adm-zip` for ZIP file operations
+
+## Data Flow
+
+```
+User Input
+    ↓
+CLI Arguments / Prompts
+    ↓
+Configuration (from file or new setup)
+    ↓
+Directus SDK Client
+    ↓
+Download File (via Directus API)
+    ↓
+Temp File Storage
+    ↓
+ZIP Validation
+    ↓
+Overwrite Check
+    ↓
+Extract to CWD
+    ↓
+Cleanup & Result
+```
+
+## Error Handling Strategy
+
+### Configuration Errors
+- Missing config → Auto-trigger setup wizard
+- Invalid config → Show error, suggest re-setup
+
+### Authentication Errors
+- 401 Unauthorized → Check access token message
+- Invalid URL → Validation during setup
+
+### Download Errors
+- 404 Not Found → File ID doesn't exist
+- Network errors → Connection issues
+- Timeout → Retry suggestion
+
+### Extraction Errors
+- Invalid ZIP → Corrupted file message
+- Permission errors → Write access issues
+- Disk space → Insufficient space
+
+### User Cancellation
+- Ctrl+C during prompts → Graceful exit
+- Overwrite declined → Cancel operation
+
+## Dependencies
+
+### Production Dependencies
+- `@directus/sdk` (^17.0.0) - Official Directus SDK
+- `prompts` (^2.4.2) - Interactive CLI prompts
+- `adm-zip` (^0.5.10) - ZIP file operations
+- `chalk` (^5.3.0) - Terminal colors
+
+### Development Dependencies
+- `typescript` (^5.3.3) - TypeScript compiler
+- `@types/node` (^20.11.0) - Node.js type definitions
+- `@types/adm-zip` (^0.5.5) - adm-zip type definitions
+- `@types/prompts` (^2.4.9) - prompts type definitions
+
+## Build System
+
+**Compiler:** TypeScript 5.3.3
+
+**Target:** ES2022 with Node.js modules
+
+**Output:** `dist/` directory with compiled JavaScript + source maps
+
+**Entry Point:** `dist/index.js` (with shebang for CLI execution)
+
+## Configuration File Location
+
+**Path:** `~/.spek-cli/config.json`
+
+**Platform-specific:**
+- Windows: `C:\Users\<username>\.spek-cli\config.json`
+- macOS: `/Users/<username>/.spek-cli/config.json`
+- Linux: `/home/<username>/.spek-cli/config.json`
+
+## Security Considerations
+
+1. **Access Token Storage**
+   - Stored in user's home directory
+   - File permissions should be restricted (user-only)
+   - Never logged or displayed in output
+
+2. **HTTPS Enforcement**
+   - Directus URL validated to be valid URL
+   - SDK handles HTTPS connections
+
+3. **Input Validation**
+   - URL validation during setup
+   - File ID passed through without modification
+   - No shell command injection risks
+
+## Performance Characteristics
+
+- **Download Speed:** Limited by network and Directus server
+- **Memory Usage:** Streams file to temp, then loads ZIP into memory
+- **Disk Usage:** Temporary file during download (auto-cleaned)
+- **Startup Time:** ~100ms for config load + argument parsing
+
+## Future Enhancements
+
+Potential features for future versions:
+
+1. **Progress Bar:** Show download progress for large files
+2. **Resume Downloads:** Support partial download resume
+3. **Batch Downloads:** Download multiple files at once
+4. **Config Management:** Commands to view/edit/reset config
+5. **Dry Run:** Preview what would be extracted without extracting
+6. **Custom Output:** Specify extraction directory
+7. **Compression:** Support other archive formats
+8. **Logging:** Verbose mode with detailed logs