@khoaha/spek-cli 1.0.4 → 1.0.6

package/docs/USAGE_EXAMPLES.md

@@ -1,520 +0,0 @@
-# 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)