@michelabboud/visual-forge-mcp 0.6.0 → 0.7.0

package/scripts/README.md

@@ -0,0 +1,460 @@
+# NPM Manager Script
+
+Production-ready bash script for managing npm package lifecycle with comprehensive safety checks and verbose logging.
+
+## Features
+
+### ✅ Safety Features
+- **Validates package.json** before any operation
+- **Checks npm authentication** before publish
+- **Verifies git status** (warns about uncommitted changes)
+- **Runs tests** before publish (with --skip-tests option)
+- **Runs build** before publish (with --skip-build option)
+- **Security audit** checks for vulnerabilities
+- **Confirms before destructive actions** (deprecate, unpublish)
+- **Creates git tags** automatically after publish
+- **Dry-run mode** for safe testing (`--dry-run`)
+- **Checks if version already published** before attempting publish
+
+### 📦 Package Management
+- **Publish** to npm with comprehensive pre-publish checks
+- **Version bumping** (patch, minor, major, or specific version)
+- **Package info** from npm registry
+- **Package stats** (quality, popularity, downloads)
+- **Distribution tags** management
+- **Access control** management
+- **Token management** for authentication
+
+### 🔒 Authentication
+- Supports **NPM_TOKEN** environment variable
+- Supports **recovery codes** via `npm login --auth-type=legacy`
+- Validates authentication before operations
+
+### 📝 Logging
+- **Color-coded output** for easy reading
+- **Comprehensive logging** to `npm-manager.log`
+- **Verbose mode** for detailed output
+
+## Installation
+
+```bash
+# Make script executable
+chmod +x scripts/npm-manager.sh
+
+# Optional: Create alias in your shell profile
+alias npm-mgr='./scripts/npm-manager.sh'
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Show help
+./scripts/npm-manager.sh --help
+
+# Show package info
+./scripts/npm-manager.sh info
+
+# Show package statistics
+./scripts/npm-manager.sh stats
+
+# Show distribution tags
+./scripts/npm-manager.sh tags
+```
+
+### Version Management
+
+```bash
+# Bump patch version (0.6.0 → 0.6.1)
+./scripts/npm-manager.sh bump patch
+
+# Bump minor version (0.6.0 → 0.7.0)
+./scripts/npm-manager.sh bump minor
+
+# Bump major version (0.6.0 → 1.0.0)
+./scripts/npm-manager.sh bump major
+
+# Set specific version
+./scripts/npm-manager.sh bump 2.0.0
+
+# Dry run (see what would happen)
+./scripts/npm-manager.sh bump patch --dry-run
+```
+
+### Publishing
+
+```bash
+# Publish to npm (runs all checks)
+./scripts/npm-manager.sh publish
+
+# Publish with specific tag
+./scripts/npm-manager.sh publish beta
+
+# Dry run publish (safe testing)
+./scripts/npm-manager.sh publish --dry-run
+
+# Skip tests (use with caution)
+./scripts/npm-manager.sh publish --skip-tests
+
+# Skip build
+./scripts/npm-manager.sh publish --skip-build
+
+# Force (skip confirmations - dangerous!)
+./scripts/npm-manager.sh publish --force
+```
+
+### Testing & Building
+
+```bash
+# Run tests only
+./scripts/npm-manager.sh test
+
+# Run build only
+./scripts/npm-manager.sh build
+
+# Run security audit
+./scripts/npm-manager.sh audit
+
+# Check for outdated dependencies
+./scripts/npm-manager.sh outdated
+```
+
+### Access & Tokens
+
+```bash
+# Manage package access
+./scripts/npm-manager.sh access
+
+# Manage npm tokens
+./scripts/npm-manager.sh tokens
+```
+
+### Deprecation & Unpublish
+
+```bash
+# Deprecate a version
+./scripts/npm-manager.sh deprecate 1.0.0 "Please upgrade to 2.0.0"
+
+# Unpublish a version (DANGEROUS - requires multiple confirmations)
+./scripts/npm-manager.sh unpublish 1.0.0
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Simulate actions without making changes |
+| `--skip-tests` | Skip running tests before publish |
+| `--skip-build` | Skip running build before publish |
+| `--force` | Skip confirmations (use with extreme caution) |
+| `--verbose` | Enable verbose output |
+| `-h, --help` | Show help message |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `NPM_TOKEN` | npm authentication token (alternative to npm login) |
+
+## Recommended Workflow
+
+### 1. Development
+```bash
+# Make your changes
+git add .
+git commit -m "feat: Add new feature"
+```
+
+### 2. Testing
+```bash
+# Run tests
+./scripts/npm-manager.sh test
+
+# Run build
+./scripts/npm-manager.sh build
+
+# Run audit
+./scripts/npm-manager.sh audit
+```
+
+### 3. Version Bump
+```bash
+# Bump version (patch for bug fixes, minor for features, major for breaking changes)
+./scripts/npm-manager.sh bump patch
+
+# Update CHANGELOG.md with changes
+vim CHANGELOG.md
+
+# Commit version bump
+git commit -am "chore: Bump version to $(node -pe "require('./package.json').version")"
+```
+
+### 4. Publish
+```bash
+# Dry run first (recommended)
+./scripts/npm-manager.sh publish --dry-run
+
+# Actually publish
+./scripts/npm-manager.sh publish
+
+# Push changes and tags
+git push && git push --tags
+```
+
+## Pre-Publish Checks
+
+The script automatically performs these checks before publishing:
+
+1. ✅ **package.json validation** - Ensures valid JSON and required fields
+2. ✅ **npm authentication** - Verifies you're logged in
+3. ✅ **Git status check** - Warns about uncommitted changes
+4. ✅ **Version check** - Ensures version isn't already published
+5. ✅ **Tests** - Runs `npm test` (can skip with --skip-tests)
+6. ✅ **Build** - Runs `npm run build` (can skip with --skip-build)
+7. ✅ **Security audit** - Checks for vulnerabilities
+8. ✅ **Outdated dependencies** - Warns about outdated packages
+9. ✅ **File list** - Shows what will be published
+10. ✅ **Final confirmation** - Asks "Are you absolutely sure?"
+
+## Authentication
+
+### Method 1: NPM Token (Recommended for CI/CD)
+
+```bash
+# Set environment variable
+export NPM_TOKEN=npm_your_token_here
+
+# Or create .env file
+echo "NPM_TOKEN=npm_your_token_here" > .env
+
+# Script will use token automatically
+./scripts/npm-manager.sh publish
+```
+
+### Method 2: npm login
+
+```bash
+# Standard login
+npm login
+
+# With 2FA/recovery codes
+npm login --auth-type=legacy
+
+# Then use script
+./scripts/npm-manager.sh publish
+```
+
+## Examples
+
+### Complete Release Workflow
+
+```bash
+# 1. Make sure everything is committed
+git status
+
+# 2. Run full test suite
+./scripts/npm-manager.sh test
+
+# 3. Bump version
+./scripts/npm-manager.sh bump minor
+
+# 4. Update CHANGELOG.md
+echo "## [$(node -pe "require('./package.json').version")] - $(date +%Y-%m-%d)" >> CHANGELOG.md
+vim CHANGELOG.md
+
+# 5. Commit version bump
+git commit -am "chore: Release v$(node -pe "require('./package.json').version")"
+
+# 6. Dry run publish (check everything)
+./scripts/npm-manager.sh publish --dry-run
+
+# 7. Actually publish
+./scripts/npm-manager.sh publish
+
+# 8. Push to GitHub
+git push && git push --tags
+```
+
+### Beta Release
+
+```bash
+# Bump to beta version
+./scripts/npm-manager.sh bump 1.0.0-beta.1
+
+# Publish with beta tag
+./scripts/npm-manager.sh publish beta
+```
+
+### Deprecate Old Version
+
+```bash
+# Deprecate specific version
+./scripts/npm-manager.sh deprecate 0.5.0 "Security vulnerability fixed in 0.6.0. Please upgrade."
+```
+
+### Emergency Unpublish (within 72 hours)
+
+```bash
+# Only works if published less than 72 hours ago
+# Requires multiple confirmations
+./scripts/npm-manager.sh unpublish 1.0.0
+```
+
+## Safety Features in Detail
+
+### Dry Run Mode
+Test any operation without making actual changes:
+```bash
+./scripts/npm-manager.sh publish --dry-run
+./scripts/npm-manager.sh bump patch --dry-run
+```
+
+### Git Tag Creation
+Automatically creates and pushes git tags:
+- Tag format: `v{version}` (e.g., `v0.6.0`)
+- Asks for confirmation before pushing
+- Includes version in tag message
+
+### Multiple Confirmations for Dangerous Operations
+- **Unpublish**: Requires typing package name + 2 confirmations
+- **Deprecate**: Requires confirmation with preview
+- **Publish**: Shows complete summary and asks for confirmation
+
+### Logging
+All operations are logged to `npm-manager.log`:
+```bash
+# View recent activity
+tail -f npm-manager.log
+
+# Search logs
+grep "publish" npm-manager.log
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Check if authenticated
+npm whoami
+
+# Login with recovery codes
+npm login --auth-type=legacy
+
+# Or use token
+export NPM_TOKEN=your_token_here
+```
+
+### Build/Test Failures
+
+```bash
+# Skip tests if they're failing but you need to publish
+./scripts/npm-manager.sh publish --skip-tests
+
+# Skip build
+./scripts/npm-manager.sh publish --skip-build
+
+# Skip both (not recommended)
+./scripts/npm-manager.sh publish --skip-tests --skip-build
+```
+
+### Version Already Published
+
+```bash
+# Error: "Version X.Y.Z is already published"
+# Solution: Bump to new version
+./scripts/npm-manager.sh bump patch
+```
+
+### Git Uncommitted Changes
+
+```bash
+# Warning: "You have uncommitted changes"
+# Option 1: Commit them
+git add .
+git commit -m "Your changes"
+
+# Option 2: Continue anyway (script will ask)
+# Option 3: Stash them
+git stash
+```
+
+## Integration with CI/CD
+
+### GitHub Actions Example
+
+```yaml
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Publish to npm
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: ./scripts/npm-manager.sh publish --skip-tests --force
+```
+
+### GitLab CI Example
+
+```yaml
+publish:
+  stage: deploy
+  only:
+    - tags
+  script:
+    - export NPM_TOKEN=$NPM_TOKEN
+    - ./scripts/npm-manager.sh publish --skip-tests --force
+```
+
+## Best Practices
+
+1. **Always test before publishing**
+   ```bash
+   ./scripts/npm-manager.sh test
+   ```
+
+2. **Use dry-run first**
+   ```bash
+   ./scripts/npm-manager.sh publish --dry-run
+   ```
+
+3. **Update CHANGELOG.md**
+   - Document all changes
+   - Follow semantic versioning
+
+4. **Never use --force in production**
+   - Only use in CI/CD after thorough testing
+   - Dangerous to skip confirmations
+
+5. **Keep git in sync**
+   ```bash
+   git push && git push --tags
+   ```
+
+6. **Monitor after publish**
+   - Check npm registry: https://www.npmjs.com/package/your-package
+   - Monitor for issues
+   - Check download stats
+
+## Support
+
+- **Script Issues**: Check `npm-manager.log` for detailed logs
+- **npm Issues**: Visit https://docs.npmjs.com/
+- **Package Issues**: Check your package.json and npm registry
+
+## License
+
+Part of Visual Forge MCP project.