@khoaha/spek-cli 1.0.3 → 1.0.5

package/docs/WORKFLOW.md

@@ -1,479 +0,0 @@
-# Complete Workflow with CLI Tool
-
-## Overview
-
-This document illustrates how the CLI tool fits into the complete SpeX ecosystem workflow.
-
-## Architecture Diagram
-
-```mermaid
-graph TB
-    subgraph "Design Phase"
-        A[Figma Design] --> B[SpeX Plugin]
-    end
-    
-    subgraph "Export Options"
-        B --> C{Export Destination}
-        C -->|Local| D[Local File System]
-        C -->|Vault| E[Directus Vault]
-    end
-    
-    subgraph "Distribution"
-        E --> F[File ID Generated]
-        F --> G[Share File ID]
-        G --> H[Team Members]
-    end
-    
-    subgraph "Download & Access"
-        H --> I[CLI Tool]
-        I --> J[npx spek-cli -d file-id]
-        J --> K[Download from Directus]
-        K --> L[Extract to Local Directory]
-    end
-    
-    subgraph "Development"
-        D --> M[MCP Server]
-        L --> M
-        M --> N[Cursor AI]
-        N --> O[AI-Powered Code Generation]
-    end
-    
-    style B fill:#6A5AE0,stroke:#333,color:#fff
-    style E fill:#10B981,stroke:#333,color:#fff
-    style I fill:#F59E0B,stroke:#333,color:#fff
-    style N fill:#3B82F6,stroke:#333,color:#fff
-```
-
-## Detailed Workflow
-
-### Phase 1: Design & Export
-
-```mermaid
-sequenceDiagram
-    participant Designer
-    participant Figma
-    participant Plugin
-    participant Directus
-    
-    Designer->>Figma: Create component library
-    Designer->>Plugin: Open SpeX plugin
-    Designer->>Plugin: Configure export settings
-    Designer->>Plugin: Select "Export to Vault"
-    Plugin->>Directus: Upload ZIP file
-    Directus-->>Plugin: Return file ID
-    Plugin->>Designer: Show success dialog with file ID
-```
-
-**Actions:**
-1. Designer creates components in Figma
-2. Opens SpeX plugin
-3. Configures metadata (optional)
-4. Clicks "Export to Vault"
-5. Plugin uploads to Directus
-6. Designer receives file ID
-
-### Phase 2: Distribution
-
-```mermaid
-graph LR
-    A[Designer] --> B[Copy File ID]
-    B --> C[Share via Slack/Email]
-    C --> D[Developer 1]
-    C --> E[Developer 2]
-    C --> F[Developer N]
-    
-    style A fill:#6A5AE0,stroke:#333,color:#fff
-    style D fill:#10B981,stroke:#333,color:#fff
-    style E fill:#10B981,stroke:#333,color:#fff
-    style F fill:#10B981,stroke:#333,color:#fff
-```
-
-**Actions:**
-1. Designer copies file ID from plugin
-2. Shares via team communication channel
-3. Multiple developers can access same specs
-
-### Phase 3: Download with CLI
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant CLI as CLI Tool
-    participant Config as Config File
-    participant Directus
-    participant FS as File System
-    
-    Dev->>CLI: npx spek-cli -d abc123
-    
-    alt First Run
-        CLI->>Dev: Prompt: Directus URL?
-        Dev->>CLI: https://company.directus.app
-        CLI->>Dev: Prompt: Access Token?
-        Dev->>CLI: token_xyz...
-        CLI->>Config: Save config
-    end
-    
-    CLI->>Config: Load config
-    CLI->>Directus: Authenticate & download
-    Directus-->>CLI: ZIP file
-    CLI->>FS: Extract to current directory
-    CLI->>Dev: ✓ Success!
-```
-
-**Actions:**
-1. Developer runs CLI command with file ID
-2. First-time setup (if needed)
-3. CLI downloads from Directus
-4. Files extracted to current directory
-
-### Phase 4: AI-Powered Development
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant Cursor as Cursor AI
-    participant MCP as MCP Server
-    participant Specs as Spec Files
-    
-    Dev->>MCP: Start MCP server
-    MCP->>Specs: Load specifications
-    Dev->>Cursor: Open project
-    Cursor->>MCP: Connect via MCP protocol
-    
-    Dev->>Cursor: "Generate Button component"
-    Cursor->>MCP: Query button specs
-    MCP-->>Cursor: Return button specification
-    Cursor->>Cursor: Generate code from specs
-    Cursor-->>Dev: Show generated code
-    
-    Dev->>Cursor: Accept & apply
-```
-
-**Actions:**
-1. Developer starts MCP server
-2. Opens Cursor AI
-3. Asks AI to generate components
-4. AI queries specs via MCP
-5. AI generates code matching design system
-
-## Use Case Scenarios
-
-### Scenario 1: Solo Developer
-
-```
-Designer/Developer → Figma → Plugin → Export Local → MCP Server → Cursor AI
-```
-
-**Workflow:**
-- Same person designs and codes
-- Exports directly to local file system
-- No need for CLI tool
-- Direct MCP integration
-
-### Scenario 2: Small Team (2-5 people)
-
-```
-Designer → Figma → Plugin → Export to Vault → Share File ID
-                                                      ↓
-Developer 1 ← CLI Tool ← File ID                     |
-Developer 2 ← CLI Tool ← File ID ←-------------------+
-```
-
-**Workflow:**
-- Designer exports to Directus vault
-- Shares file ID via Slack
-- Each developer downloads with CLI
-- Developers use MCP for AI integration
-
-### Scenario 3: Large Team (5+ people)
-
-```
-Design Team → Figma → Plugin → Export to Vault → File ID in Wiki/Docs
-                                                         ↓
-Dev Team (many) ← CLI Tool ← File ID from Documentation
-                       ↓
-                  CI/CD Pipeline (automated download)
-```
-
-**Workflow:**
-- Design team maintains component library
-- Regular exports to vault
-- File IDs documented in team wiki
-- Developers download as needed
-- CI/CD automates spec downloads
-
-### Scenario 4: CI/CD Integration
-
-```
-GitHub Actions → CLI Tool → Download Specs → Commit to Repo → Deploy
-```
-
-**Workflow:**
-- Automated workflow triggered manually or on schedule
-- CLI downloads latest specs
-- Commits to repository
-- Triggers deployment pipeline
-
-## Comparison: Local vs. Vault Export
-
-### Local Export
-
-**Pros:**
-- ✅ Immediate access
-- ✅ No external dependencies
-- ✅ Works offline
-- ✅ No authentication needed
-
-**Cons:**
-- ❌ Manual file sharing
-- ❌ Version control challenges
-- ❌ No centralized storage
-- ❌ Difficult for teams
-
-**Best For:**
-- Solo developers
-- Quick prototypes
-- Offline work
-- Simple projects
-
-### Vault Export (with CLI)
-
-**Pros:**
-- ✅ Centralized storage
-- ✅ Easy sharing (just file ID)
-- ✅ Version history in Directus
-- ✅ Access control
-- ✅ Team collaboration
-
-**Cons:**
-- ❌ Requires Directus instance
-- ❌ Needs authentication
-- ❌ Requires internet connection
-- ❌ Extra step (CLI download)
-
-**Best For:**
-- Team projects
-- Enterprise environments
-- Version control needs
-- Distributed teams
-
-## Integration Points
-
-### 1. Figma Plugin ↔ Directus
-
-**Protocol:** Directus SDK (REST API)
-
-**Flow:**
-```
-Plugin → Directus SDK → POST /files → Upload ZIP → Return file ID
-```
-
-### 2. CLI Tool ↔ Directus
-
-**Protocol:** Directus SDK (REST API)
-
-**Flow:**
-```
-CLI → Directus SDK → GET /assets/:id → Download ZIP → Extract
-```
-
-### 3. MCP Server ↔ Cursor AI
-
-**Protocol:** Model Context Protocol (stdio)
-
-**Flow:**
-```
-Cursor → MCP Request → Read Spec Files → MCP Response → Cursor
-```
-
-### 4. Plugin ↔ MCP Server (Optional)
-
-**Protocol:** WebSocket
-
-**Flow:**
-```
-Plugin → WebSocket → Send Specs → MCP Server → Serve to Cursor
-```
-
-## Configuration Requirements
-
-### For Plugin (Vault Export)
-
-```json
-{
-  "directusUrl": "https://company.directus.app",
-  "accessToken": "plugin_token_xyz",
-  "collectionName": "figma_specs",
-  "folderName": "Design Specs"
-}
-```
-
-### For CLI Tool
-
-```json
-{
-  "directusUrl": "https://company.directus.app",
-  "accessToken": "cli_token_xyz",
-  "createdAt": "2026-02-13T..."
-}
-```
-
-**Note:** Plugin and CLI can use different tokens with different permissions.
-
-### For MCP Server
-
-```json
-{
-  "mcpServers": {
-    "spex-local": {
-      "command": "npx",
-      "args": ["-y", "spex-mcp", "--mode", "local", "--port", "8080"]
-    }
-  }
-}
-```
-
-## Security Considerations
-
-### Access Tokens
-
-**Plugin Token:**
-- Needs: `files:create`, `items:create`
-- Purpose: Upload specs to vault
-- Scope: Write access to specific collection
-
-**CLI Token:**
-- Needs: `files:read`
-- Purpose: Download specs from vault
-- Scope: Read access to files
-
-**Best Practice:**
-- Use separate tokens for plugin and CLI
-- Restrict permissions to minimum required
-- Rotate tokens regularly
-- Store in secure configuration files
-
-### File Sharing
-
-**File ID Sharing:**
-- File IDs are UUIDs (not sequential)
-- Difficult to guess
-- Still requires authentication to download
-- Can be shared via any channel
-
-**Access Control:**
-- Directus handles authentication
-- File permissions managed in Directus
-- Can restrict by user/role
-- Audit logs available
-
-## Performance Considerations
-
-### Download Speed
-
-**Factors:**
-- Network bandwidth
-- Directus server location
-- File size (typically 1-10MB)
-- Compression ratio
-
-**Typical Times:**
-- Small specs (<1MB): 1-3 seconds
-- Medium specs (1-5MB): 3-10 seconds
-- Large specs (5-10MB): 10-30 seconds
-
-### Extraction Speed
-
-**Factors:**
-- Disk I/O speed
-- Number of files in ZIP
-- Directory structure depth
-
-**Typical Times:**
-- Most specs: <1 second
-- Large specs: 1-3 seconds
-
-## Troubleshooting
-
-### Common Issues
-
-**1. Authentication Failed**
-```bash
-❌ Error: Authentication failed. Please check your access token.
-
-Solution:
-1. Check token is valid in Directus
-2. Verify token has files:read permission
-3. Reset config: rm ~/.spek-cli/config.json
-```
-
-**2. File Not Found**
-```bash
-❌ Error: File not found: abc123
-
-Solution:
-1. Verify file ID is correct
-2. Check file exists in Directus
-3. Ensure you have permission to access file
-```
-
-**3. Network Error**
-```bash
-❌ Error: Failed to download file: Network request failed
-
-Solution:
-1. Check internet connection
-2. Verify Directus URL is accessible
-3. Check firewall/proxy settings
-```
-
-**4. Overwrite Prompt Not Showing**
-```bash
-# Files extracted without prompt
-
-Reason:
-- No conflicting files in current directory
-- Only prompts if files would be overwritten
-```
-
-## Future Enhancements
-
-### Planned Features
-
-1. **Progress Bar**
-   - Show download progress
-   - Estimate time remaining
-
-2. **Multiple Instances**
-   - Support multiple Directus instances
-   - Switch between configs easily
-
-3. **Batch Download**
-   - Download multiple file IDs at once
-   - Parallel downloads
-
-4. **Custom Output**
-   - Specify extraction directory
-   - Organize by version/date
-
-5. **Integration Commands**
-   - `spek-cli list` - List available files
-   - `spek-cli search` - Search by metadata
-   - `spek-cli history` - Download history
-
-## Conclusion
-
-The CLI tool completes the SpeX ecosystem by providing:
-
-1. **Easy Distribution:** Share specs via simple file ID
-2. **Team Collaboration:** Multiple developers access same specs
-3. **Version Control:** Directus manages spec versions
-4. **Automation:** CI/CD integration possible
-5. **Security:** Access control via Directus
-
-**Complete Workflow:**
-```
-Design → Export → Share → Download → Develop
-  ↓        ↓       ↓        ↓          ↓
-Figma  Plugin  File ID   CLI Tool  Cursor AI
-```

package/scripts/publish.ps1

@@ -1,193 +0,0 @@
-##############################################################################
-# npm Publish Script (Windows PowerShell)
-# 
-# Usage:
-#   .\scripts\publish.ps1 [version]
-#
-# Arguments:
-#   version - One of: patch, minor, major, or specific version (e.g., 1.2.3)
-#             Default: patch
-#
-# Environment Variables:
-#   NPM_ACCESS_TOKEN - Required for authentication (set in .env)
-#
-# Examples:
-#   .\scripts\publish.ps1           # Bump patch version (1.0.0 -> 1.0.1)
-#   .\scripts\publish.ps1 minor     # Bump minor version (1.0.0 -> 1.1.0)
-#   .\scripts\publish.ps1 major     # Bump major version (1.0.0 -> 2.0.0)
-#   .\scripts\publish.ps1 2.5.3     # Set specific version
-##############################################################################
-
-param(
-    [string]$VersionType = "patch"
-)
-
-$ErrorActionPreference = "Stop"
-
-# Script directory
-$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
-$ProjectDir = Split-Path -Parent $ScriptDir
-
-# Load .env file if exists
-$EnvFile = Join-Path $ProjectDir ".env"
-if (Test-Path $EnvFile) {
-    Write-Host "Loading .env file..." -ForegroundColor Blue
-    Get-Content $EnvFile | ForEach-Object {
-        if ($_ -match '^([^#][^=]+)=(.+)$') {
-            $name = $matches[1].Trim()
-            $value = $matches[2].Trim()
-            [Environment]::SetEnvironmentVariable($name, $value, "Process")
-        }
-    }
-}
-
-# Check for NPM_ACCESS_TOKEN
-if (-not $env:NPM_ACCESS_TOKEN) {
-    Write-Host "❌ Error: NPM_ACCESS_TOKEN not found" -ForegroundColor Red
-    Write-Host "Please set NPM_ACCESS_TOKEN in .env file" -ForegroundColor Yellow
-    exit 1
-}
-
-# Validate version type
-if ($VersionType -notmatch '^(patch|minor|major|[0-9]+\.[0-9]+\.[0-9]+)$') {
-    Write-Host "❌ Invalid version type: $VersionType" -ForegroundColor Red
-    Write-Host "Use: patch, minor, major, or specific version (e.g., 1.2.3)" -ForegroundColor Yellow
-    exit 1
-}
-
-Write-Host ""
-Write-Host "╔══════════════════════════════════════╗" -ForegroundColor Blue
-Write-Host "║  📦 npm Publish Script              ║" -ForegroundColor Blue
-Write-Host "╚══════════════════════════════════════╝" -ForegroundColor Blue
-Write-Host ""
-
-# Step 1: Check git status
-Write-Host "1️⃣  Checking git status..." -ForegroundColor Blue
-$gitStatus = git status --porcelain
-if ($gitStatus) {
-    Write-Host "⚠️  Warning: You have uncommitted changes" -ForegroundColor Yellow
-    $response = Read-Host "Continue anyway? (y/N)"
-    if ($response -ne 'y' -and $response -ne 'Y') {
-        Write-Host "❌ Aborted" -ForegroundColor Red
-        exit 1
-    }
-}
-Write-Host "✓ Git status checked" -ForegroundColor Green
-Write-Host ""
-
-# Step 2: Clean install
-Write-Host "2️⃣  Clean install dependencies..." -ForegroundColor Blue
-if (Test-Path "node_modules") {
-    Remove-Item -Recurse -Force "node_modules"
-}
-if (Test-Path "package-lock.json") {
-    Remove-Item -Force "package-lock.json"
-}
-npm install
-Write-Host "✓ Dependencies installed" -ForegroundColor Green
-Write-Host ""
-
-# Step 3: Build
-Write-Host "3️⃣  Building TypeScript..." -ForegroundColor Blue
-npm run build
-if (-not (Test-Path "dist")) {
-    Write-Host "❌ Error: dist/ directory not found after build" -ForegroundColor Red
-    exit 1
-}
-Write-Host "✓ Build successful" -ForegroundColor Green
-Write-Host ""
-
-# Step 4: Test build output
-Write-Host "4️⃣  Testing build output..." -ForegroundColor Blue
-if (-not (Test-Path "dist\index.js")) {
-    Write-Host "❌ Error: dist\index.js not found" -ForegroundColor Red
-    exit 1
-}
-try {
-    node dist\index.js --version | Out-Null
-} catch {
-    Write-Host "⚠️  Warning: Version check failed (might be expected)" -ForegroundColor Yellow
-}
-Write-Host "✓ Build output verified" -ForegroundColor Green
-Write-Host ""
-
-# Step 5: Bump version
-Write-Host "5️⃣  Bumping version ($VersionType)..." -ForegroundColor Blue
-npm version $VersionType --no-git-tag-version
-$packageJson = Get-Content "package.json" | ConvertFrom-Json
-$newVersion = $packageJson.version
-Write-Host "✓ Version bumped to: $newVersion" -ForegroundColor Green
-Write-Host ""
-
-# Step 6: Create .npmrc with token
-Write-Host "6️⃣  Configuring npm authentication..." -ForegroundColor Blue
-$npmrcPath = Join-Path $ProjectDir ".npmrc"
-"//registry.npmjs.org/:_authToken=$env:NPM_ACCESS_TOKEN" | Out-File -FilePath $npmrcPath -Encoding ASCII
-Write-Host "✓ npm authentication configured" -ForegroundColor Green
-Write-Host ""
-
-# Step 7: Dry run publish
-Write-Host "7️⃣  Running dry-run publish..." -ForegroundColor Blue
-npm publish --dry-run
-Write-Host "✓ Dry-run successful" -ForegroundColor Green
-Write-Host ""
-
-# Step 8: Confirm publish
-Write-Host "┌────────────────────────────────────┐" -ForegroundColor Yellow
-Write-Host "│  Ready to publish v$newVersion" -ForegroundColor Yellow
-Write-Host "│  Package: spek-cli                │" -ForegroundColor Yellow
-Write-Host "└────────────────────────────────────┘" -ForegroundColor Yellow
-Write-Host ""
-$response = Read-Host "Proceed with publish? (y/N)"
-if ($response -ne 'y' -and $response -ne 'Y') {
-    Write-Host "❌ Publish cancelled" -ForegroundColor Red
-    Remove-Item -Force $npmrcPath
-    exit 1
-}
-
-# Step 9: Publish to npm
-Write-Host "9️⃣  Publishing to npm..." -ForegroundColor Blue
-npm publish --access public
-Write-Host "✓ Published successfully!" -ForegroundColor Green
-Write-Host ""
-
-# Step 10: Cleanup
-Write-Host "🧹 Cleaning up..." -ForegroundColor Blue
-Remove-Item -Force $npmrcPath
-Write-Host "✓ Cleanup complete" -ForegroundColor Green
-Write-Host ""
-
-# Step 11: Create git tag
-Write-Host "🏷️  Creating git tag..." -ForegroundColor Blue
-git add package.json
-try {
-    git commit -m "chore: bump version to v$newVersion"
-} catch {
-    Write-Host "No changes to commit" -ForegroundColor Gray
-}
-git tag "v$newVersion"
-Write-Host "✓ Git tag created: v$newVersion" -ForegroundColor Green
-Write-Host ""
-
-# Step 12: Test installation
-Write-Host "🧪 Testing installation..." -ForegroundColor Blue
-Write-Host "Run this command to test:" -ForegroundColor Yellow
-Write-Host "  npx spek-cli@$newVersion --version" -ForegroundColor Green
-Write-Host "Or:" -ForegroundColor Yellow
-Write-Host "  npx spek-cli --version" -ForegroundColor Green
-Write-Host ""
-
-# Success summary
-Write-Host "╔══════════════════════════════════════╗" -ForegroundColor Green
-Write-Host "║  ✅ Publish Complete!               ║" -ForegroundColor Green
-Write-Host "╚══════════════════════════════════════╝" -ForegroundColor Green
-Write-Host ""
-Write-Host "Package: spek-cli" -ForegroundColor Blue
-Write-Host "Version: $newVersion" -ForegroundColor Blue
-Write-Host "Registry: https://www.npmjs.com/package/spek-cli" -ForegroundColor Blue
-Write-Host ""
-Write-Host "Next steps:" -ForegroundColor Yellow
-Write-Host "  1. Push git tag: git push origin v$newVersion" -ForegroundColor Green
-Write-Host "  2. Test install: npx spek-cli@$newVersion" -ForegroundColor Green
-Write-Host "  3. Verify on npm: https://www.npmjs.com/package/spek-cli" -ForegroundColor Green
-Write-Host ""