@khoaha/spek-cli 1.0.4 → 1.0.5

package/docs/WINDOWS_DEVELOPMENT.md

@@ -1,487 +0,0 @@
-# Windows Development Guide
-
-## The Problem
-
-Windows PowerShell cannot directly execute Node.js files with shebang (`#!/usr/bin/env node`). This causes the error:
-
-```
-Error: Invalid character
-Code: 800A03F6
-Source: Microsoft JScript compilation error
-```
-
-## The Solution
-
-We've created a **Windows-compatible wrapper** at `bin/cli.js` that properly loads the compiled code.
-
----
-
-## 🚀 Development Workflow for Windows
-
-### Option 1: Using Node.js Directly (Recommended for Testing)
-
-This is the **simplest and most reliable** method for local testing:
-
-```powershell
-# 1. Build the project
-cd F:\specs-figma\cli-tool
-npm run build
-
-# 2. Run with Node.js directly
-node dist/index.js --help
-node dist/index.js -d <file-id>
-
-# Example with real file ID
-node dist/index.js -d 0880c1fa-7dd9-4b28-a39d-32a5ef83cc58
-```
-
-**Pros:**
-- ✅ Works on all Windows versions
-- ✅ No PATH configuration needed
-- ✅ Simple and straightforward
-- ✅ Best for development and testing
-
-**Cons:**
-- ❌ Longer command (need to type `node dist/index.js`)
-
----
-
-### Option 2: Using npm link (For Global Testing)
-
-Link the package globally to test as if it were installed:
-
-```powershell
-# 1. Build the project
-cd F:\specs-figma\cli-tool
-npm run build
-
-# 2. Link globally
-npm link
-
-# 3. Now you can use it anywhere
-cd C:\Users\Khoa\Downloads\spex-export
-spek-cli -d <file-id>
-
-# 4. When done testing, unlink
-npm unlink -g spek-cli
-```
-
-**Pros:**
-- ✅ Test the actual user experience
-- ✅ Works from any directory
-- ✅ Tests the bin wrapper
-
-**Cons:**
-- ❌ Requires admin privileges sometimes
-- ❌ Can conflict with published versions
-- ❌ Need to rebuild and relink after changes
-
----
-
-### Option 3: Using npx Locally (For Package Testing)
-
-Test the package as users would with npx:
-
-```powershell
-# 1. Build the project
-cd F:\specs-figma\cli-tool
-npm run build
-
-# 2. Pack the package (creates .tgz file)
-npm pack
-
-# 3. Install globally from the .tgz
-npm install -g .\spek-cli-1.0.0.tgz
-
-# 4. Test it
-cd C:\Users\Khoa\Downloads\spex-export
-spek-cli -d <file-id>
-
-# 5. Uninstall when done
-npm uninstall -g spek-cli
-```
-
-**Pros:**
-- ✅ Tests the complete package
-- ✅ Most realistic user experience
-- ✅ Tests packaging and distribution
-
-**Cons:**
-- ❌ Most complex workflow
-- ❌ Need to repack after every change
-- ❌ Creates .tgz files to clean up
-
----
-
-## 📝 Recommended Development Flow
-
-### For Active Development (Making Changes)
-
-```powershell
-# Terminal 1: Watch mode (auto-rebuild on changes)
-cd F:\specs-figma\cli-tool
-npm run dev
-
-# Terminal 2: Test your changes
-cd F:\specs-figma\cli-tool
-node dist/index.js -d <file-id>
-```
-
-### For Testing Complete Workflow
-
-```powershell
-# 1. Build
-cd F:\specs-figma\cli-tool
-npm run build
-
-# 2. Link globally
-npm link
-
-# 3. Test from different directory
-cd C:\Users\Khoa\Downloads\test-directory
-spek-cli -d <file-id>
-
-# 4. Unlink when done
-npm unlink -g spek-cli
-```
-
----
-
-## 🔧 Quick Commands Reference
-
-### Build Commands
-
-```powershell
-# Build once
-npm run build
-
-# Watch mode (rebuild on changes)
-npm run dev
-
-# Clean and rebuild
-Remove-Item -Recurse -Force dist
-npm run build
-```
-
-### Testing Commands
-
-```powershell
-# Test with Node.js directly
-node dist/index.js --help
-node dist/index.js --version
-node dist/index.js -d <file-id>
-node dist/index.js  # Interactive mode
-
-# Test with npm link
-npm link
-spek-cli --help
-spek-cli -d <file-id>
-npm unlink -g spek-cli
-```
-
-### Debugging Commands
-
-```powershell
-# Check if build output exists
-Get-ChildItem dist
-
-# View compiled JavaScript
-Get-Content dist/index.js | Select-Object -First 20
-
-# Check Node.js version
-node --version
-
-# Check npm version
-npm --version
-```
-
----
-
-## 🐛 Troubleshooting
-
-### Error: "Invalid character" (800A03F6)
-
-**Cause:** Trying to run the file directly in PowerShell
-
-**Solution:** Use `node dist/index.js` instead
-
-```powershell
-# ❌ DON'T DO THIS
-.\dist\index.js
-
-# ✅ DO THIS
-node dist/index.js
-```
-
----
-
-### Error: "Cannot find module"
-
-**Cause:** Project not built or dependencies not installed
-
-**Solution:**
-```powershell
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-```
-
----
-
-### Error: "spek-cli: command not found"
-
-**Cause:** Package not linked globally
-
-**Solution:**
-```powershell
-# Link the package
-cd F:\specs-figma\cli-tool
-npm link
-
-# Or use Node.js directly
-node dist/index.js -d <file-id>
-```
-
----
-
-### Error: "Permission denied"
-
-**Cause:** Need admin privileges for npm link
-
-**Solution:**
-```powershell
-# Run PowerShell as Administrator
-# Right-click PowerShell → "Run as Administrator"
-
-# Then run npm link
-npm link
-```
-
----
-
-### Build Errors
-
-**Cause:** TypeScript compilation errors
-
-**Solution:**
-```powershell
-# Check for errors
-npm run build
-
-# If errors, check the TypeScript files
-# Fix any type errors shown in the output
-```
-
----
-
-## 📦 Testing with Real Directus Instance
-
-### Step 1: Prepare Test Environment
-
-```powershell
-# Create test directory
-New-Item -ItemType Directory -Path C:\Users\Khoa\Downloads\specs-test
-cd C:\Users\Khoa\Downloads\specs-test
-```
-
-### Step 2: Get Test Data
-
-1. Open Figma with SpeX plugin
-2. Export to Directus Vault
-3. Copy the File ID from success dialog
-
-### Step 3: Run CLI Tool
-
-```powershell
-# Option A: Using Node.js directly
-node F:\specs-figma\cli-tool\dist\index.js -d <file-id>
-
-# Option B: Using npm link
-cd F:\specs-figma\cli-tool
-npm link
-cd C:\Users\Khoa\Downloads\specs-test
-spek-cli -d <file-id>
-```
-
-### Step 4: Verify Results
-
-```powershell
-# Check extracted files
-Get-ChildItem
-
-# Should see:
-# - README.md
-# - manifest.json
-# - components/
-# - icons/
-# - images/
-```
-
----
-
-## 🔄 Complete Development Cycle
-
-### 1. Make Changes
-
-Edit source files in `src/`:
-- `src/index.ts`
-- `src/config/manager.ts`
-- `src/prompts/index.ts`
-- etc.
-
-### 2. Build
-
-```powershell
-cd F:\specs-figma\cli-tool
-npm run build
-```
-
-### 3. Test
-
-```powershell
-# Quick test
-node dist/index.js --help
-
-# Full test with file ID
-node dist/index.js -d <file-id>
-```
-
-### 4. Verify
-
-```powershell
-# Check if files extracted
-Get-ChildItem
-
-# Check config created
-Get-Content ~\.spek-cli\config.json
-```
-
-### 5. Iterate
-
-Repeat steps 1-4 until satisfied.
-
----
-
-## 🎯 Best Practices for Windows Development
-
-### 1. Use PowerShell or Windows Terminal
-
-**Recommended:**
-- Windows Terminal (modern, better experience)
-- PowerShell 7+ (cross-platform)
-
-**Avoid:**
-- Command Prompt (cmd.exe) - limited features
-- Git Bash - may have path issues
-
-### 2. Use Full Paths When Testing
-
-```powershell
-# ✅ GOOD: Full path
-node F:\specs-figma\cli-tool\dist\index.js -d <file-id>
-
-# ❌ RISKY: Relative path (depends on current directory)
-node dist\index.js -d <file-id>
-```
-
-### 3. Use npm Scripts
-
-```powershell
-# ✅ GOOD: Use npm scripts
-npm run build
-npm run dev
-
-# ❌ AVOID: Direct tsc commands
-tsc
-tsc --watch
-```
-
-### 4. Clean Build When in Doubt
-
-```powershell
-# Remove old build
-Remove-Item -Recurse -Force dist
-
-# Fresh build
-npm run build
-```
-
-### 5. Check Node.js Version
-
-```powershell
-# Ensure Node.js 18+
-node --version
-# Should show: v18.x.x or higher
-```
-
----
-
-## 📋 Pre-Testing Checklist
-
-Before testing with real Directus instance:
-
-- [ ] Node.js 18+ installed
-- [ ] Dependencies installed (`npm install`)
-- [ ] Project built (`npm run build`)
-- [ ] Directus instance URL ready
-- [ ] Access token generated
-- [ ] File ID from Vault Export ready
-- [ ] Test directory created
-
----
-
-## 🚀 Quick Start for Testing
-
-**The fastest way to test right now:**
-
-```powershell
-# 1. Navigate to project
-cd F:\specs-figma\cli-tool
-
-# 2. Build (if not already built)
-npm run build
-
-# 3. Create test directory
-New-Item -ItemType Directory -Path C:\Users\Khoa\Downloads\specs-test -Force
-cd C:\Users\Khoa\Downloads\specs-test
-
-# 4. Run CLI with your file ID
-node F:\specs-figma\cli-tool\dist\index.js -d 0880c1fa-7dd9-4b28-a39d-32a5ef83cc58
-
-# 5. Follow the prompts for first-time setup
-```
-
----
-
-## 📞 Need Help?
-
-### Common Issues
-
-1. **"Invalid character" error** → Use `node dist/index.js` instead of running directly
-2. **"Cannot find module" error** → Run `npm install` and `npm run build`
-3. **"Command not found" error** → Use full path or run `npm link`
-4. **Permission errors** → Run PowerShell as Administrator
-
-### Documentation
-
-- [Main README](./README.md)
-- [Quick Start](./QUICKSTART.md)
-- [Testing Guide](./docs/TESTING.md)
-- [Architecture](./docs/ARCHITECTURE.md)
-
----
-
-## ✅ Summary
-
-**For Development & Testing on Windows:**
-
-```powershell
-# The simplest and most reliable method:
-cd F:\specs-figma\cli-tool
-npm run build
-node dist/index.js -d <file-id>
-```
-
-**That's it!** This works on all Windows versions and doesn't require any special setup.