@khoaha/spek-cli 1.0.3

package/docs/PUBLISH_QUICK_REFERENCE.md

@@ -0,0 +1,135 @@
+# 🚀 Quick Publish Reference
+
+## Pre-Publish Checklist
+
+```bash
+# 1. Verify token is configured
+cat .env | grep NPM_ACCESS_TOKEN
+
+# 2. Clean build
+npm run build
+
+# 3. Test locally
+node dist/index.js --help
+node dist/index.js --version
+
+# 4. Dry run
+npm publish --dry-run
+```
+
+## Publish Commands
+
+### Linux/macOS
+```bash
+# Make executable (first time only)
+chmod +x scripts/publish.sh
+
+# Publish (choose one)
+./scripts/publish.sh              # Patch: 1.0.0 → 1.0.1
+./scripts/publish.sh minor        # Minor: 1.0.0 → 1.1.0
+./scripts/publish.sh major        # Major: 1.0.0 → 2.0.0
+./scripts/publish.sh 2.5.3        # Specific version
+```
+
+### Windows (PowerShell)
+```powershell
+# Publish (choose one)
+.\scripts\publish.ps1              # Patch: 1.0.0 → 1.0.1
+.\scripts\publish.ps1 minor        # Minor: 1.0.0 → 1.1.0
+.\scripts\publish.ps1 major        # Major: 1.0.0 → 2.0.0
+.\scripts\publish.ps1 2.5.3        # Specific version
+```
+
+### Or Use npm Scripts
+```bash
+npm run publish:patch    # 1.0.0 → 1.0.1
+npm run publish:minor    # 1.0.0 → 1.1.0
+npm run publish:major    # 1.0.0 → 2.0.0
+```
+
+## Post-Publish
+
+```bash
+# 1. Verify on npm
+https://www.npmjs.com/package/spek-cli
+
+# 2. Test installation
+npx spek-cli@latest --version
+
+# 3. Push git tag
+git push origin v1.0.0
+
+# 4. Test full workflow
+npx spek-cli -d <test-file-id>
+```
+
+## Quick Test
+
+```bash
+# Test without publishing
+npm link
+spek-cli --help
+spek-cli --version
+npm unlink -g spek-cli
+```
+
+## Environment
+
+Required in `.env`:
+```bash
+NPM_ACCESS_TOKEN=npm_xxxxxxxxxxxxxxxxxxxxxx
+```
+
+## What the Script Does
+
+1. ✓ Checks git status
+2. ✓ Clean installs dependencies  
+3. ✓ Builds TypeScript
+4. ✓ Verifies build output
+5. ✓ Bumps version
+6. ✓ Creates .npmrc with token
+7. ✓ Runs dry-run
+8. ✓ Asks for confirmation
+9. ✓ Publishes to npm
+10. ✓ Cleans up .npmrc
+11. ✓ Creates git tag
+12. ✓ Shows success message
+
+## Troubleshooting
+
+### "NPM_ACCESS_TOKEN not found"
+```bash
+# Check .env file exists
+ls -la .env
+
+# Create if missing
+echo "NPM_ACCESS_TOKEN=your-token-here" > .env
+```
+
+### "401 Unauthorized"
+- Generate new token at https://www.npmjs.com/settings/~/tokens
+- Update `.env` with new token
+
+### "403 Forbidden"  
+- Package name already exists
+- Or insufficient token permissions
+
+### Build fails
+```bash
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+## Quick Links
+
+- **Publishing Guide**: `docs/PUBLISHING.md`
+- **npm Registry**: https://www.npmjs.com/package/spek-cli
+- **Token Settings**: https://www.npmjs.com/settings/~/tokens
+- **Rename Summary**: `RENAME_COMPLETE.md`
+
+---
+
+**Current Version**: 1.0.0 (unpublished)
+**Ready**: ✅ Yes - All files updated and tested
+**Next**: Run publish script

package/docs/SVG_TO_VECTOR_DRAWABLE.md

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