@khoaha/spek-cli 1.0.3 → 1.0.5

package/docs/SVG_TO_VECTOR_DRAWABLE.md

@@ -1,186 +0,0 @@
-# SVG to Vector Drawable Conversion Feature
-
-## Overview
-Added SVG to Android Vector Drawable XML conversion feature to the `spek-cli` CLI tool using `vd-tool` library.
-
-## Command Usage
-
-### Basic Conversion
-```bash
-npx spek-cli svg-to-vd -i <input> -o <output>
-```
-
-### With Tint Color
-```bash
-npx spek-cli svg-to-vd -i icon.svg -o icon.xml --tint "#FF5722"
-```
-
-### Examples
-```bash
-# Convert SVG file
-npx spek-cli svg-to-vd -i ./icons/heart.svg -o ./drawables/heart.xml
-
-# With tint color
-npx spek-cli svg-to-vd -i icon.svg -o icon.xml --tint "#FF5722"
-
-# Using raw SVG content
-npx spek-cli svg-to-vd -i "<svg>...</svg>" -o output.xml
-
-# Output to nested directory (auto-creates directories)
-npx spek-cli svg-to-vd -i icon.svg -o res/drawable/icon.xml
-```
-
-## Options
-
-### Required
-- `-i, --input <input>` - SVG file path or raw SVG content (auto-detected)
-- `-o, --output <output>` - Output Vector Drawable XML file path
-
-### Optional
-- `--tint <color>` - Tint color to apply (e.g., "#FF5722")
-- `-h, --help` - Show help message
-
-## Features
-
-### Auto-detection
-The tool automatically detects whether the input is:
-1. **SVG content** - If starts with `<svg`
-2. **File path** - If file exists at the path
-3. **Fallback** - Treats as SVG content
-
-### Error Handling
-Comprehensive error messages with suggestions:
-- Missing required parameters
-- Invalid SVG format
-- File read errors
-- Conversion failures
-- Write permission issues
-
-### Smart Output
-- **Directory creation** - Automatically creates output directories if they don't exist
-- **Overwrite** - Silently overwrites existing files
-- **Validation** - Validates SVG content before conversion
-- **Progress feedback** - Shows step-by-step progress with emojis
-
-## Architecture
-
-### File Structure
-```
-cli-tool/src/
-├── commands/
-│   └── svg-to-vd/
-│       └── handler.ts              # Command handler with error handling
-├── utils/
-│   ├── svg-converter.ts            # Core conversion logic using vd-tool
-│   └── file-utils.ts               # File I/O utilities
-├── types/
-│   └── index.ts                    # TypeScript interfaces
-└── index.ts                        # Main CLI entry point
-```
-
-### Key Components
-
-#### 1. SVG Converter (`utils/svg-converter.ts`)
-- `convertSvgToVectorDrawable()` - Main conversion function
-- `validateSvgContent()` - SVG format validation
-- Uses temporary files for vd-tool processing
-- Applies customizations (tint)
-- Automatic cleanup
-
-#### 2. File Utilities (`utils/file-utils.ts`)
-- `detectInputType()` - Auto-detect file vs content
-- `fileExists()` - Check file existence
-- `readFileContent()` - Read SVG file
-- `writeFileContent()` - Write XML with directory creation
-
-#### 3. Command Handler (`commands/svg-to-vd/handler.ts`)
-- Validates required options
-- Orchestrates conversion flow
-- Provides user-friendly error messages
-- Shows progress feedback
-
-#### 4. Type Definitions (`types/index.ts`)
-- `SvgToVdOptions` - Command options
-- `SvgConversionResult` - Conversion result
-- Extended `CliOptions` for command routing
-
-## Implementation Details
-
-### Technology Stack
-- **TypeScript 5.x** - Type-safe implementation
-- **vd-tool 4.0.2** - SVG to Vector Drawable conversion
-- **Node.js 18+** - ES Modules support
-- **chalk 5.x** - Colored terminal output
-
-### Detection Priority
-```typescript
-1. Check if input starts with '<svg' → Treat as SVG content
-2. Check if file exists at path → Read file
-3. Fallback → Treat as SVG content
-```
-
-### Error Messages
-All errors include:
-- Clear description of the problem
-- Helpful tip or suggestion
-- Example usage when relevant
-
-### Conversion Process
-```
-1. Parse command arguments
-2. Auto-detect input type (file vs content)
-3. Read SVG content
-4. Validate SVG format
-5. Convert using vd-tool
-6. Apply customizations (tint if specified)
-7. Create output directory if needed
-8. Write Vector Drawable XML
-9. Show success message
-```
-
-## Testing Results
-
-### ✅ Tested Scenarios
-1. **File conversion** - Successfully converts SVG files
-2. **Tint application** - Correctly applies tint color
-3. **Nested directories** - Auto-creates output directories
-4. **Missing output** - Shows error with suggestion
-5. **Invalid input** - Validates and shows helpful error
-6. **Help text** - Both main and command-specific help work
-
-### Sample Output
-```xml
-<vector xmlns:android="http://schemas.android.com/apk/res/android"
-    android:width="24dp"
-    android:height="24dp"
-    android:viewportWidth="24"
-    android:viewportHeight="24">
-  <path
-      android:pathData="M20.84,4.61a5.5,5.5..."
-      android:strokeLineJoin="round"
-      android:strokeWidth="2"
-      android:fillColor="#00000000"
-      android:strokeColor="currentColor"
-      android:strokeLineCap="round"/>
-</vector>
-```
-
-## Dependencies Added
-```json
-{
-  "vd-tool": "^4.0.2"
-}
-```
-
-## Notes
-- Complex SVG features may not be fully supported by vd-tool
-- Output files are overwritten without confirmation
-- Temporary files are automatically cleaned up after conversion
-- Works on Windows, macOS, and Linux
-
-## Future Enhancements (Potential)
-- Batch conversion support (multiple files)
-- Custom naming patterns
-- SVG optimization before conversion
-- Preview mode (show output without writing)
-- Configuration file support

package/docs/TESTING.md

@@ -1,429 +0,0 @@
-# Testing Guide
-
-## Prerequisites
-
-1. **Directus Instance:** You need access to a Directus instance with the Vault Export feature
-2. **Access Token:** Generate an access token from your Directus instance
-3. **Test File:** Have a file ID from a Vault Export ready for testing
-
-## Getting Test Data
-
-### From Figma Plugin
-
-1. Open the SpeX Figma plugin
-2. Go to "Vault Export" tab
-3. Configure your Directus connection
-4. Export specs to vault
-5. Copy the file ID from the success dialog
-
-### File ID Format
-
-File IDs are UUIDs, typically in this format:
-```
-abc123-def456-ghi789-jkl012
-```
-
-## Local Testing
-
-### 1. Build the CLI Tool
-
-```bash
-# From monorepo root
-npm run cli:build
-
-# Or from cli-tool directory
-cd cli-tool
-npm run build
-```
-
-### 2. Test Locally (Without Publishing)
-
-```bash
-# From cli-tool directory
-node dist/index.js --help
-node dist/index.js -d <your-file-id>
-```
-
-### 3. Test with npx (Local Link)
-
-```bash
-# From cli-tool directory
-npm link
-
-# Now you can use it globally
-spek-cli -d <your-file-id>
-
-# Unlink when done
-npm unlink -g spek-cli
-```
-
-## Test Scenarios
-
-### Scenario 1: First Run (No Config)
-
-**Expected Behavior:**
-1. CLI prompts for Directus URL
-2. CLI prompts for access token
-3. Config is saved to `~/.spek-cli/config.json`
-4. CLI prompts for file ID (if not provided)
-5. Download and extraction proceeds
-
-**Test Commands:**
-```bash
-# Interactive mode (prompts for everything)
-spek-cli
-
-# Direct mode (prompts for config only)
-spek-cli -d <file-id>
-```
-
-**Validation:**
-- [ ] Config file created at `~/.spek-cli/config.json`
-- [ ] Config contains correct URL and token
-- [ ] Success message displayed
-- [ ] Files extracted to current directory
-
-### Scenario 2: Subsequent Runs (Config Exists)
-
-**Expected Behavior:**
-1. Config loaded from file
-2. No prompts for URL/token
-3. Prompts for file ID if not provided
-4. Download and extraction proceeds
-
-**Test Commands:**
-```bash
-# Interactive mode
-spek-cli
-
-# Direct mode
-spek-cli -d <file-id>
-```
-
-**Validation:**
-- [ ] No config prompts shown
-- [ ] Download proceeds immediately
-- [ ] Files extracted successfully
-
-### Scenario 3: Overwrite Existing Files
-
-**Setup:**
-```bash
-# First download
-spek-cli -d <file-id>
-
-# Second download (same file)
-spek-cli -d <file-id>
-```
-
-**Expected Behavior:**
-1. CLI detects existing files
-2. Prompts: "Files already exist. Overwrite?"
-3. If Yes → Overwrites files
-4. If No → Cancels operation
-
-**Validation:**
-- [ ] Warning message shown
-- [ ] Overwrite prompt appears
-- [ ] Choosing "Yes" overwrites files
-- [ ] Choosing "No" cancels without changes
-
-### Scenario 4: Invalid Authentication
-
-**Setup:**
-```bash
-# Edit config file with invalid token
-# ~/.spek-cli/config.json
-```
-
-**Expected Behavior:**
-1. Download attempt fails
-2. Error message: "Authentication failed. Please check your access token."
-3. Suggests checking config
-
-**Test Commands:**
-```bash
-spek-cli -d <file-id>
-```
-
-**Validation:**
-- [ ] Clear error message
-- [ ] No partial downloads
-- [ ] Temp files cleaned up
-
-### Scenario 5: File Not Found
-
-**Test Commands:**
-```bash
-spek-cli -d invalid-file-id-12345
-```
-
-**Expected Behavior:**
-1. Download attempt fails
-2. Error message: "File not found: invalid-file-id-12345"
-
-**Validation:**
-- [ ] Clear error message
-- [ ] No partial extraction
-- [ ] Temp files cleaned up
-
-### Scenario 6: Network Errors
-
-**Setup:**
-- Disconnect internet or use invalid Directus URL
-
-**Expected Behavior:**
-1. Connection fails
-2. Error message with network details
-
-**Validation:**
-- [ ] Graceful error handling
-- [ ] No hanging processes
-- [ ] Temp files cleaned up
-
-### Scenario 7: Corrupted ZIP File
-
-**Note:** This is difficult to test without modifying the Directus server response.
-
-**Expected Behavior:**
-1. Download completes
-2. ZIP validation fails
-3. Error message: "Invalid or corrupted ZIP file"
-
-**Validation:**
-- [ ] No extraction attempted
-- [ ] Temp files cleaned up
-
-### Scenario 8: User Cancellation
-
-**Test Commands:**
-```bash
-spek-cli
-# Press Ctrl+C during any prompt
-```
-
-**Expected Behavior:**
-1. Graceful exit
-2. No partial operations
-3. No temp files left behind
-
-**Validation:**
-- [ ] Clean exit
-- [ ] No error messages
-- [ ] No temp files
-
-### Scenario 9: Help and Version
-
-**Test Commands:**
-```bash
-spek-cli --help
-spek-cli -h
-spek-cli --version
-spek-cli -v
-```
-
-**Expected Behavior:**
-- Help shows usage, options, examples
-- Version shows current version number
-
-**Validation:**
-- [ ] Help is clear and comprehensive
-- [ ] Version matches package.json
-
-### Scenario 10: Empty Directory vs. Non-Empty
-
-**Test A: Empty Directory**
-```bash
-mkdir test-empty
-cd test-empty
-spek-cli -d <file-id>
-```
-
-**Expected:** Direct extraction, no overwrite prompt
-
-**Test B: Non-Empty Directory**
-```bash
-mkdir test-non-empty
-cd test-non-empty
-echo "test" > README.md
-spek-cli -d <file-id>
-```
-
-**Expected:** Overwrite prompt only if ZIP contains README.md
-
-**Validation:**
-- [ ] Empty dir: No prompt
-- [ ] Non-empty dir with conflicts: Prompt shown
-- [ ] Non-empty dir without conflicts: No prompt
-
-## Manual Testing Checklist
-
-### Setup Phase
-- [ ] Build succeeds without errors
-- [ ] TypeScript compilation clean
-- [ ] All dependencies installed
-
-### Configuration
-- [ ] First run prompts for config
-- [ ] Config saved correctly
-- [ ] Config loaded on subsequent runs
-- [ ] Invalid URL rejected during setup
-- [ ] Empty token rejected during setup
-
-### Download
-- [ ] Valid file ID downloads successfully
-- [ ] Invalid file ID shows error
-- [ ] Network errors handled gracefully
-- [ ] Authentication errors clear
-
-### Extraction
-- [ ] Files extracted to CWD
-- [ ] Directory structure preserved
-- [ ] Overwrite prompt works
-- [ ] Cancellation works
-- [ ] Temp files cleaned up
-
-### User Experience
-- [ ] Help message clear
-- [ ] Version displayed correctly
-- [ ] Error messages helpful
-- [ ] Success messages clear
-- [ ] Colors enhance readability
-
-### Edge Cases
-- [ ] Very large files (>100MB)
-- [ ] Files with special characters
-- [ ] Deeply nested directory structures
-- [ ] Empty ZIP files
-- [ ] ZIP with single file
-- [ ] ZIP with many files (>1000)
-
-## Automated Testing (Future)
-
-### Unit Tests
-
-```typescript
-// Example test structure
-describe('Config Manager', () => {
-  it('should create config directory if not exists', () => {});
-  it('should save config with timestamp', () => {});
-  it('should load existing config', () => {});
-});
-
-describe('Download Handler', () => {
-  it('should detect existing files', () => {});
-  it('should validate ZIP files', () => {});
-  it('should cleanup temp files on error', () => {});
-});
-```
-
-### Integration Tests
-
-```typescript
-describe('Full Download Flow', () => {
-  it('should download and extract valid file', async () => {});
-  it('should handle authentication errors', async () => {});
-  it('should handle file not found', async () => {});
-});
-```
-
-## Performance Testing
-
-### Metrics to Track
-
-1. **Startup Time:** Time from command to first prompt
-2. **Download Speed:** MB/s for various file sizes
-3. **Extraction Time:** Time to extract various ZIP sizes
-4. **Memory Usage:** Peak memory during download/extraction
-
-### Test Files
-
-- Small: <1MB
-- Medium: 1-10MB
-- Large: 10-100MB
-- Very Large: >100MB
-
-## Troubleshooting
-
-### Build Fails
-
-```bash
-# Clean and rebuild
-rm -rf dist node_modules
-npm install
-npm run build
-```
-
-### Config Issues
-
-```bash
-# View config
-cat ~/.spek-cli/config.json
-
-# Delete config (forces re-setup)
-rm ~/.spek-cli/config.json
-```
-
-### Temp Files Not Cleaned
-
-```bash
-# Check temp directory
-ls /tmp/spek-cli-*
-
-# Manual cleanup
-rm /tmp/spek-cli-*
-```
-
-### Permission Errors
-
-```bash
-# Check config directory permissions
-ls -la ~/.spek-cli
-
-# Fix permissions
-chmod 700 ~/.spek-cli
-chmod 600 ~/.spek-cli/config.json
-```
-
-## Reporting Issues
-
-When reporting issues, include:
-
-1. **Command used:** Full command with arguments
-2. **Error message:** Complete error output
-3. **Environment:**
-   - OS and version
-   - Node.js version
-   - npm version
-4. **Config:** Directus URL (redact token)
-5. **File ID:** If applicable (redact if sensitive)
-6. **Steps to reproduce:** Detailed steps
-
-## Test Results Template
-
-```markdown
-## Test Results - [Date]
-
-**Environment:**
-- OS: Windows 10 / macOS 14 / Ubuntu 22.04
-- Node.js: v20.11.0
-- npm: v10.2.4
-
-**Test Scenarios:**
-- [ ] First run setup
-- [ ] Subsequent runs
-- [ ] Overwrite prompt
-- [ ] Invalid auth
-- [ ] File not found
-- [ ] Network errors
-- [ ] User cancellation
-- [ ] Help/Version
-- [ ] Empty directory
-- [ ] Non-empty directory
-
-**Issues Found:**
-1. [Issue description]
-2. [Issue description]
-
-**Overall Status:** ✅ Pass / ❌ Fail
-```