@khoaha/spek-cli 1.0.3

package/docs/USAGE_EXAMPLES.md

@@ -0,0 +1,520 @@
+# Usage Examples
+
+Complete guide with real-world examples for using `spek-cli` CLI tool.
+
+## Installation
+
+```bash
+# Run directly with npx (no installation needed)
+npx spek-cli
+
+# Or install globally
+npm install -g spek-cli
+```
+
+## Basic Usage
+
+### First Time Setup
+
+When you run the CLI for the first time, you'll be prompted to configure your Directus connection:
+
+```bash
+$ npx spek-cli
+
+📦 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: ********************************
+
+✓ Configuration saved to /Users/username/.spek-cli/config.json
+
+? Enter the file ID to download: abc123-def456-ghi789
+
+📥 Downloading file: abc123-def456-ghi789...
+✓ Download complete
+🔍 Validating ZIP file...
+✓ ZIP file is valid
+📦 Extracting files...
+✓ Files extracted successfully
+
+✓ Success! Files extracted to current directory
+```
+
+### Direct Download (With File ID)
+
+Once configured, you can download files directly:
+
+```bash
+# Using -d flag
+npx spek-cli -d abc123-def456-ghi789
+
+# Using --download flag
+npx spek-cli --download abc123-def456-ghi789
+```
+
+**Output:**
+```
+📦 spek-cli
+
+📥 Downloading file: abc123-def456-ghi789...
+✓ Download complete
+🔍 Validating ZIP file...
+✓ ZIP file is valid
+📦 Extracting files...
+✓ Files extracted successfully
+
+✓ Success! Files extracted to current directory
+```
+
+### Interactive Mode
+
+Run without arguments to be prompted for the file ID:
+
+```bash
+$ npx spek-cli
+
+📦 spek-cli
+
+? Enter the file ID to download: abc123-def456-ghi789
+
+📥 Downloading file: abc123-def456-ghi789...
+✓ Download complete
+🔍 Validating ZIP file...
+✓ ZIP file is valid
+📦 Extracting files...
+✓ Files extracted successfully
+
+✓ Success! Files extracted to current directory
+```
+
+## Real-World Workflows
+
+### Workflow 1: Designer → Developer Handoff
+
+**Scenario:** Designer exports specs from Figma, developer downloads them.
+
+**Designer (in Figma Plugin):**
+1. Open SpeX plugin in Figma
+2. Go to "Vault Export" tab
+3. Click "Export to Vault"
+4. Copy the file ID from success dialog
+5. Share file ID with developer (via Slack, email, etc.)
+
+**Developer:**
+```bash
+# Create project directory
+mkdir my-design-specs
+cd my-design-specs
+
+# Download specs
+npx spek-cli -d abc123-def456-ghi789
+
+# Files are now in current directory
+ls
+# Output: README.md  manifest.json  components/  icons/  images/
+```
+
+### Workflow 2: CI/CD Pipeline
+
+**Scenario:** Automatically download latest specs in CI pipeline.
+
+**GitHub Actions Example:**
+```yaml
+name: Download Design Specs
+
+on:
+  workflow_dispatch:
+    inputs:
+      file_id:
+        description: 'Directus file ID'
+        required: true
+
+jobs:
+  download-specs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Setup spek-cli config
+        run: |
+          mkdir -p ~/.spek-cli
+          echo '{
+            "directusUrl": "${{ secrets.DIRECTUS_URL }}",
+            "accessToken": "${{ secrets.DIRECTUS_TOKEN }}",
+            "createdAt": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'"
+          }' > ~/.spek-cli/config.json
+
+      - name: Download specs
+        run: npx spek-cli -d ${{ github.event.inputs.file_id }}
+
+      - name: Commit specs
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+          git add .
+          git commit -m "Update design specs"
+          git push
+```
+
+### Workflow 3: Multiple Projects
+
+**Scenario:** Working with multiple Directus instances.
+
+**Setup:**
+```bash
+# Project A
+cd ~/projects/project-a
+npx spek-cli -d file-id-a
+
+# Project B (different Directus instance)
+cd ~/projects/project-b
+# Need to reconfigure for different instance
+rm ~/.spek-cli/config.json
+npx spek-cli -d file-id-b
+```
+
+**Better Approach (Future Enhancement):**
+```bash
+# Use environment variables (future feature)
+DIRECTUS_URL=https://project-a.directus.app \
+DIRECTUS_TOKEN=token-a \
+npx spek-cli -d file-id-a
+```
+
+### Workflow 4: Overwriting Existing Specs
+
+**Scenario:** Update specs with newer version.
+
+```bash
+$ cd my-design-specs
+$ npx spek-cli -d new-file-id
+
+📦 spek-cli
+
+📥 Downloading file: new-file-id...
+✓ Download complete
+🔍 Validating ZIP file...
+✓ ZIP file is valid
+
+⚠️  Warning: Some files already exist in the current directory
+? Files already exist in current directory. Overwrite? (y/N) › y
+
+📦 Extracting files...
+✓ Files extracted successfully
+
+✓ Success! Files extracted to current directory
+```
+
+## Common Scenarios
+
+### Scenario: Getting File ID from Plugin
+
+1. In Figma, open SpeX plugin
+2. Navigate to "Vault Export" tab
+3. Click "Export to Vault"
+4. Success dialog shows:
+   ```
+   ✓ Export Successful!
+   
+   File ID: abc123-def456-ghi789
+   
+   Download Link: https://your-instance.directus.app/assets/abc123-def456-ghi789?download
+   
+   [Copy File ID] [Copy Download Link]
+   ```
+5. Click "Copy File ID"
+6. Use in CLI: `npx spek-cli -d abc123-def456-ghi789`
+
+### Scenario: Organizing Downloaded Specs
+
+```bash
+# Create organized directory structure
+mkdir -p ~/design-specs/project-name/v1.0
+cd ~/design-specs/project-name/v1.0
+
+# Download specs
+npx spek-cli -d abc123-def456-ghi789
+
+# Result:
+# ~/design-specs/
+#   └── project-name/
+#       └── v1.0/
+#           ├── README.md
+#           ├── manifest.json
+#           ├── components/
+#           ├── icons/
+#           └── images/
+```
+
+### Scenario: Checking What Will Be Downloaded
+
+```bash
+# Download to temporary directory first
+mkdir /tmp/specs-preview
+cd /tmp/specs-preview
+npx spek-cli -d abc123-def456-ghi789
+
+# Review contents
+ls -la
+
+# If satisfied, download to actual location
+cd ~/my-project
+npx spek-cli -d abc123-def456-ghi789
+
+# Cleanup preview
+rm -rf /tmp/specs-preview
+```
+
+### Scenario: Handling Errors
+
+**Invalid File ID:**
+```bash
+$ npx spek-cli -d invalid-id
+
+📦 spek-cli
+
+📥 Downloading file: invalid-id...
+
+❌ Error: File not found: invalid-id
+```
+
+**Authentication Failed:**
+```bash
+$ npx spek-cli -d abc123-def456-ghi789
+
+📦 spek-cli
+
+📥 Downloading file: abc123-def456-ghi789...
+
+❌ Error: Authentication failed. Please check your access token.
+
+# Fix: Update config
+$ rm ~/.spek-cli/config.json
+$ npx spek-cli -d abc123-def456-ghi789
+# Will prompt for new credentials
+```
+
+**Network Error:**
+```bash
+$ npx spek-cli -d abc123-def456-ghi789
+
+📦 spek-cli
+
+📥 Downloading file: abc123-def456-ghi789...
+
+❌ Error: Failed to download file: Network request failed
+```
+
+## Command Reference
+
+### Download Commands
+
+```bash
+# Interactive mode (prompts for file ID)
+npx spek-cli
+
+# Direct download with short flag
+npx spek-cli -d <file-id>
+
+# Direct download with long flag
+npx spek-cli --download <file-id>
+```
+
+### Help Commands
+
+```bash
+# Show help
+npx spek-cli --help
+npx spek-cli -h
+
+# Show version
+npx spek-cli --version
+npx spek-cli -v
+```
+
+### Configuration Management
+
+```bash
+# View current config
+cat ~/.spek-cli/config.json
+
+# Reset config (will prompt for new setup)
+rm ~/.spek-cli/config.json
+npx spek-cli
+
+# Backup config
+cp ~/.spek-cli/config.json ~/.spek-cli/config.backup.json
+
+# Restore config
+cp ~/.spek-cli/config.backup.json ~/.spek-cli/config.json
+```
+
+## Tips & Best Practices
+
+### 1. Organize by Version
+
+```bash
+# Create version-specific directories
+mkdir -p specs/v1.0 specs/v1.1 specs/v2.0
+
+# Download each version
+cd specs/v1.0 && npx spek-cli -d file-id-v1.0
+cd ../v1.1 && npx spek-cli -d file-id-v1.1
+cd ../v2.0 && npx spek-cli -d file-id-v2.0
+```
+
+### 2. Use with Git
+
+```bash
+# Add specs directory to git
+cd my-project
+mkdir design-specs
+cd design-specs
+npx spek-cli -d abc123-def456-ghi789
+
+# Commit to version control
+git add .
+git commit -m "Add design specs v1.0"
+```
+
+### 3. Automate with Scripts
+
+**download-specs.sh:**
+```bash
+#!/bin/bash
+
+FILE_ID=$1
+
+if [ -z "$FILE_ID" ]; then
+  echo "Usage: ./download-specs.sh <file-id>"
+  exit 1
+fi
+
+# Create timestamped directory
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+SPEC_DIR="specs_${TIMESTAMP}"
+
+mkdir -p "$SPEC_DIR"
+cd "$SPEC_DIR"
+
+# Download specs
+npx spek-cli -d "$FILE_ID"
+
+echo "Specs downloaded to: $SPEC_DIR"
+```
+
+**Usage:**
+```bash
+chmod +x download-specs.sh
+./download-specs.sh abc123-def456-ghi789
+```
+
+### 4. Team Configuration
+
+**Share config template (without token):**
+
+**config.template.json:**
+```json
+{
+  "directusUrl": "https://your-company.directus.app",
+  "accessToken": "YOUR_TOKEN_HERE",
+  "createdAt": "2026-02-13T00:00:00.000Z"
+}
+```
+
+**Setup instructions for team:**
+```bash
+# Copy template
+cp config.template.json ~/.spek-cli/config.json
+
+# Edit with your personal token
+nano ~/.spek-cli/config.json
+```
+
+## Troubleshooting
+
+### Problem: "Command not found"
+
+**Solution:**
+```bash
+# Use npx instead of global install
+npx spek-cli -d <file-id>
+
+# Or install globally
+npm install -g spek-cli
+```
+
+### Problem: "Permission denied"
+
+**Solution:**
+```bash
+# Check directory permissions
+ls -la
+
+# Ensure you have write access
+chmod u+w .
+
+# Or run in a directory you own
+cd ~/my-project
+npx spek-cli -d <file-id>
+```
+
+### Problem: "Config file corrupted"
+
+**Solution:**
+```bash
+# Delete and recreate
+rm ~/.spek-cli/config.json
+npx spek-cli
+# Follow setup prompts
+```
+
+### Problem: "Download hangs"
+
+**Solution:**
+```bash
+# Check network connection
+ping your-directus-instance.com
+
+# Check Directus instance is accessible
+curl https://your-directus-instance.com
+
+# Try again with timeout (future feature)
+# For now, Ctrl+C and retry
+```
+
+## Getting Help
+
+```bash
+# Show help
+npx spek-cli --help
+
+# Check version
+npx spek-cli --version
+
+# View config location
+echo ~/.spek-cli/config.json
+```
+
+## Next Steps
+
+After downloading specs:
+
+1. **Review README.md:** Contains overview and structure
+2. **Check manifest.json:** Lists all components and assets
+3. **Explore components/:** Component specifications
+4. **Review icons/:** Icon assets and metadata
+5. **Check images/:** Image assets
+
+For more information, see:
+- [Architecture Documentation](./ARCHITECTURE.md)
+- [Testing Guide](./TESTING.md)
+- [Main README](../README.md)