@git.zone/cli 2.13.7 → 2.13.10

package/readme.md

@@ -18,11 +18,11 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 ### Installation
 
 ```bash
-# Install globally via npm
-npm install -g @git.zone/cli
-
-# Or with pnpm (recommended)
+# Install globally via pnpm (recommended)
 pnpm add -g @git.zone/cli
+
+# Or with npm
+npm install -g @git.zone/cli
 ```
 
 Once installed, you can use either `gitzone` or the shorter `gzone` command from anywhere in your terminal.
@@ -33,9 +33,12 @@ Once installed, you can use either `gitzone` or the shorter `gzone` command from
 # Create a new TypeScript npm package
 gitzone template npm
 
-# Format your entire codebase
+# Format your entire codebase (dry-run by default)
 gitzone format
 
+# Apply formatting changes
+gitzone format --write
+
 # Start local MongoDB and MinIO services
 gitzone services start
 
@@ -45,167 +48,210 @@ gitzone commit
 
 ## 🛠️ Core Features
 
-### 🐳 Development Services Management
+### 🔀 Semantic Commits & Versioning
 
-Effortlessly manage local MongoDB and MinIO (S3-compatible) services for your development environment:
+Create standardized commits with AI-powered suggestions that automatically handle versioning:
 
 ```bash
-gitzone services [command]
+# Interactive commit with AI recommendations
+gitzone commit
+
+# Auto-accept AI recommendations (skipped for BREAKING CHANGEs)
+gitzone commit -y
+
+# Auto-accept, push, build, and release
+gitzone commit -ypbr
 ```
 
-**Available commands:**
+**Flags:**
 
-- **`start [service]`** - Start services (mongo|s3|all)
-- **`stop [service]`** - Stop services (mongo|s3|all)
-- **`restart [service]`** - Restart services
-- **`status`** - Show current service status
-- **`config`** - Display configuration details
-- **`compass`** - Get MongoDB Compass connection string with network IP
-- **`logs [service] [lines]`** - View service logs
-- **`remove`** - Remove containers (preserves data)
-- **`clean`** - Remove containers AND data (⚠️ destructive)
+| Flag | Long Form | Description |
+|------|-----------|-------------|
+| `-y` | `--yes` | Auto-accept AI recommendations |
+| `-p` | `--push` | Push to remote after commit |
+| `-t` | `--test` | Run tests before committing |
+| `-b` | `--build` | Build after commit, verify clean tree |
+| `-r` | `--release` | Publish to configured npm registries |
+| | `--format` | Run format before committing |
 
-**Key features:**
+**Workflow steps:**
 
-- 🎲 **Smart port assignment** - Automatically assigns random ports (20000-30000) to avoid conflicts
-- 📦 **Project isolation** - Each project gets its own containers with unique names
-- 💾 **Data persistence** - Data stored in `.nogit/` directories survives container restarts
-- 🔗 **MongoDB Compass support** - Instantly get connection strings for GUI access
-- 🌐 **Network IP detection** - Automatically detects your local network IP for remote connections
-- ⚙️ **Auto-configuration** - Creates `.nogit/env.json` with smart defaults
+1. 🤖 **AI-powered analysis** — analyzes your changes and suggests commit type, scope, and message
+2. 📝 Interactive commit message builder (type: `fix`/`feat`/`BREAKING CHANGE`, scope, description)
+3. 📜 Automatic changelog generation
+4. 🏷️ Automatic version bumping (major/minor/patch) with git tag creation
+5. 🔨 Optional build & verification
+6. 🚀 Optional push to origin
+7. 📦 Optional publish to npm registries
 
-**Example workflow:**
+Supports both npm (`package.json`) and Deno (`deno.json`) projects, including dual-type projects.
+
+### 🎨 Intelligent Code Formatting
+
+Automatically format and standardize your entire codebase. **Dry-run by default** — nothing changes until you explicitly use `--write`:
 
 ```bash
-# Start all services for your project
-gitzone services start
+# Preview what would change (default behavior)
+gitzone format
 
-# Check what's running
-gitzone services status
+# Apply changes
+gitzone format --write
 
-# Get MongoDB Compass connection string
-gitzone services compass
-# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin
+# Auto-approve without prompts
+gitzone format --yes --write
 
-# View MongoDB logs
-gitzone services logs mongo 50
+# Show detailed diffs
+gitzone format --diff
 
-# Stop services when done
-gitzone services stop
+# Enable verbose logging
+gitzone format --verbose
 ```
 
-The services are configured via `.nogit/env.json` which is automatically created with secure defaults and random ports for each project.
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--write` / `-w` | Apply changes (default is dry-run) |
+| `--yes` | Auto-approve without interactive confirmation |
+| `--plan-only` | Only show what would be done |
+| `--save-plan <file>` | Save the format plan to a file |
+| `--from-plan <file>` | Load and execute a saved plan |
+| `--detailed` | Show detailed stats and save report |
+| `--parallel` / `--no-parallel` | Toggle parallel execution |
+| `--verbose` | Enable verbose logging |
+| `--diff` | Show file diffs |
+
+**Formatters (executed in order):**
+
+1. 🧹 **Cleanup** — removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
+2. ⚙️ **Npmextra** — formats and standardizes `npmextra.json`
+3. 📜 **License** — ensures proper licensing and checks dependency licenses
+4. 📦 **Package.json** — standardizes package configuration
+5. 📋 **Templates** — applies project template updates
+6. 🙈 **Gitignore** — updates repository ignore rules
+7. 🔧 **Tsconfig** — optimizes TypeScript configuration
+8. ✨ **Prettier** — applies code formatting
+9. 📖 **Readme** — ensures readme files exist
+10. 📂 **Copy** — copies configured files
 
-### 📦 Project Templates
+### 🐳 Development Services Management
 
-Instantly scaffold production-ready projects with best practices built-in:
+Effortlessly manage local development services (MongoDB, MinIO S3, Elasticsearch) with Docker:
 
 ```bash
-gitzone template [template-name]
+gitzone services [command]
 ```
 
-**Available templates:**
+**Commands:**
 
-- **`npm`** - TypeScript npm package with testing, CI/CD, and full tooling
-- **`service`** - Microservice architecture with Docker support
-- **`website`** - Modern web application with LitElement and service workers
-- **`wcc`** - Web Component Collection for reusable UI components
+| Command | Description |
+|---------|-------------|
+| `start [service]` | Start services (`mongo`\|`s3`\|`elasticsearch`\|`all`) |
+| `stop [service]` | Stop services |
+| `restart [service]` | Restart services |
+| `status` | Show current service status |
+| `config` | Display configuration details |
+| `compass` | Get MongoDB Compass connection string with network IP |
+| `logs [service] [lines]` | View service logs (default: 20 lines) |
+| `reconfigure` | Reassign ports and restart all services |
+| `remove` | Remove containers (preserves data) |
+| `clean` | Remove containers AND data (⚠️ destructive) |
 
-Each template comes pre-configured with:
+**Service aliases:**
 
-- ✅ TypeScript with modern configurations
-- ✅ Automated testing setup with `@git.zone/tstest`
-- ✅ CI/CD pipelines (GitLab/GitHub)
-- ✅ Code formatting and linting
-- ✅ Documentation structure
+- `mongo` / `mongodb` — MongoDB
+- `minio` / `s3` — MinIO (S3-compatible storage)
+- `elasticsearch` / `es` — Elasticsearch
+- `all` — All services (default)
 
-### 🎨 Intelligent Code Formatting
+**Key features:**
 
-The most powerful feature of gitzone - automatically format and standardize your entire codebase:
+- 🎲 **Smart port assignment** — automatically assigns random ports (20000–30000) to avoid conflicts
+- 📦 **Project isolation** — each project gets its own containers with unique names
+- 💾 **Data persistence** — data stored in `.nogit/` survives container restarts
+- 🔗 **MongoDB Compass support** — instantly get connection strings for GUI access
+- 🌐 **Network IP detection** — detects your local network IP for remote connections
+- ⚙️ **Auto-configuration** — creates `.nogit/env.json` with smart defaults
 
-```bash
-# Preview changes without applying them
-gitzone format --dry-run
+**Global operations (`-g` flag):**
 
-# Format with automatic approval
-gitzone format --yes
+```bash
+# List all registered projects
+gitzone services list -g
 
-# Save formatting plan for later execution
-gitzone format --save-plan format-plan.json
+# Show status across all projects
+gitzone services status -g
 
-# Execute a saved plan
-gitzone format --from-plan format-plan.json
+# Stop all containers across all projects
+gitzone services stop -g
 
-# Enable verbose output for debugging
-gitzone format --verbose
+# Remove stale registry entries
+gitzone services cleanup -g
 ```
 
-**Format features:**
-
-- 🔄 **Smart caching** - Only processes changed files
-- 🛡️ **Rollback support** - Undo formatting changes if needed
-- 📊 **Detailed reporting** - See exactly what changed
-- ⚡ **Parallel execution** - Format multiple files simultaneously
-- 🎯 **Module-specific formatting** - Target specific formatters
-
-**Rollback capabilities:**
+**Example workflow:**
 
 ```bash
-# List all available backups
-gitzone format --list-backups
+# Start all services for your project
+gitzone services start
 
-# Rollback to the last operation
-gitzone format --rollback
+# Check what's running
+gitzone services status
 
-# Rollback to a specific operation
-gitzone format --rollback [operation-id]
+# Get MongoDB Compass connection string
+gitzone services compass
+# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin
 
-# Clean old backups
-gitzone format --clean-backups
+# View MongoDB logs
+gitzone services logs mongo 50
+
+# Stop services when done
+gitzone services stop
 ```
 
-**Formatters included:**
+### ⚙️ Release & Commit Configuration
 
-- **Prettier** - JavaScript/TypeScript code formatting
-- **License** - Ensure proper licensing
-- **Package.json** - Standardize package configurations
-- **Tsconfig** - TypeScript configuration optimization
-- **Readme** - Documentation formatting
-- **Gitignore** - Repository ignore rules
-- **Templates** - Project template updates
-- **Npmextra** - Extended npm configurations
-- **Cleanup** - Removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
+Manage release registries and commit settings:
 
-### 🔀 Semantic Commits & Versioning
+```bash
+gitzone config [subcommand]
+```
 
-Create standardized commits with AI-powered suggestions that automatically handle versioning:
+| Command | Description |
+|---------|-------------|
+| `show` | Display current release config (registries, access level) |
+| `add [url]` | Add a registry URL (default: `https://registry.npmjs.org`) |
+| `remove [url]` | Remove a registry URL (interactive selection if no URL) |
+| `clear` | Clear all registries (with confirmation) |
+| `access [public\|private]` | Set npm access level for publishing |
+| `commit alwaysTest [true\|false]` | Always run tests before commit |
+| `commit alwaysBuild [true\|false]` | Always build after commit |
+| `services` | Configure which services are enabled |
 
-```bash
-# Interactive commit with AI recommendations
-gitzone commit
+Configuration is stored in `npmextra.json` under the `@git.zone/cli` key.
 
-# Auto-accept AI recommendations
-gitzone commit -y
+### 📦 Project Templates
+
+Instantly scaffold production-ready projects with best practices built-in:
 
-# Auto-accept and push
-gitzone commit -y -p
+```bash
+gitzone template [template-name]
 ```
 
-Features:
+**Interactive templates:**
 
-- 🤖 **AI-powered analysis** - Analyzes your changes and suggests commit type, scope, and message
-- 📝 Interactive commit message builder with smart defaults
-- 🏷️ Automatic version bumping (major/minor/patch)
-- 📜 Changelog generation
-- 🚀 Optional auto-push to origin
-- 🎯 Conventional commit compliance
+- **`npm`** — TypeScript npm package with testing, CI/CD, and full tooling
+- **`service`** — Microservice architecture with Docker support
+- **`website`** — Modern web application with LitElement and service workers
+- **`wcc`** — Web Component Collection for reusable UI components
 
-The commit wizard guides you through:
+Each template comes pre-configured with:
 
-1. **Type selection** (fix/feat/BREAKING CHANGE) with AI recommendation
-2. **Scope definition** (component/module affected)
-3. **Description crafting**
-4. **Version bump determination**
+- ✅ TypeScript with modern configurations
+- ✅ Automated testing setup with `@git.zone/tstest`
+- ✅ CI/CD pipelines (GitLab/GitHub)
+- ✅ Code formatting and linting
+- ✅ Documentation structure
 
 ### 🏗️ Meta Repository Management
 
@@ -218,36 +264,22 @@ gitzone meta init
 # Add a sub-project
 gitzone meta add [name] [git-url]
 
-# Update all sub-projects
+# Update all sub-projects (clone missing, clean superfluous)
 gitzone meta update
 
 # Remove a sub-project
 gitzone meta remove [name]
 ```
 
-Perfect for:
-
-- Monorepo management
-- Multi-package projects
-- Coordinated deployments
-- Synchronized versioning
-
 ### 🐳 Docker Management
 
 Streamline your Docker workflow:
 
 ```bash
-# Clean up all Docker resources
+# Clean up all Docker resources (containers, images, volumes, networks)
 gitzone docker prune
 ```
 
-This command removes:
-
-- Stopped containers
-- Unused images
-- Dangling volumes
-- Unused networks
-
 ### 🔗 Quick CI/CD Access
 
 Jump directly to your CI/CD configurations:
@@ -270,12 +302,7 @@ Smoothly transition users from old to new packages:
 gitzone deprecate
 ```
 
-Interactive wizard for:
-
-- Setting deprecation notices
-- Guiding users to replacements
-- Updating registry metadata
-- Coordinating migration paths
+Interactive wizard that prompts for registry URLs, old package name, and new package name — then runs `npm deprecate` across all specified registries.
 
 ### 🚦 Project Initialization
 
@@ -285,17 +312,10 @@ Prepare existing projects for development:
 gitzone start
 ```
 
-Automatically:
-
-- Checks out master branch
-- Pulls latest changes
-- Installs dependencies
-- Sets up development environment
+Automatically checks out master, pulls latest changes, and installs dependencies.
 
 ### 🔧 Helper Utilities
 
-Quick utilities for common tasks:
-
 ```bash
 # Generate a unique short ID
 gitzone helpers shortid
@@ -303,31 +323,44 @@ gitzone helpers shortid
 
 ## 📋 Configuration
 
-### npmextra.json Configuration
+### npmextra.json
 
 Customize gitzone behavior through `npmextra.json`:
 
 ```json
 {
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "release": {
+      "registries": [
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
+    },
+    "commit": {
+      "alwaysTest": false,
+      "alwaysBuild": false
+    }
+  },
   "gitzone": {
     "format": {
       "interactive": true,
-      "showDiffs": false,
-      "autoApprove": false,
       "parallel": true,
-      "rollback": {
+      "showStats": true,
+      "cache": {
         "enabled": true,
-        "autoRollbackOnError": true,
-        "backupRetentionDays": 7
+        "clean": true
       },
       "modules": {
         "skip": ["prettier"],
         "only": [],
         "order": []
       },
-      "cache": {
-        "enabled": true,
-        "clean": true
+      "licenses": {
+        "allowed": ["MIT", "Apache-2.0"],
+        "exceptions": {
+          "some-package": "GPL-3.0"
+        }
       }
     }
   }
@@ -336,35 +369,9 @@ Customize gitzone behavior through `npmextra.json`:
 
 ### Environment Variables
 
-- `CI` - Detect CI environment for automated workflows
-- `DEBUG` - Enable debug output
-- `GITZONE_FORMAT_PARALLEL` - Control parallel formatting
-
-## 🏆 Best Practices
-
-### For New Projects
-
-1. Start with a template: `gitzone template npm`
-2. Set up local services: `gitzone services start`
-3. Customize the generated structure
-4. Run initial format: `gitzone format`
-5. Set up CI/CD: `gitzone open ci`
-
-### For Existing Projects
-
-1. Initialize: `gitzone start`
-2. Format codebase: `gitzone format --dry-run` (preview first!)
-3. Apply formatting: `gitzone format --yes`
-4. Set up services: `gitzone services start`
-5. Commit changes: `gitzone commit`
-
-### For Teams
-
-1. Document format preferences in `npmextra.json`
-2. Share `.nogit/env.json` template for consistent service setup
-3. Use `--save-plan` for reviewable format changes
-4. Enable rollback for safety
-5. Standardize commit conventions
+- `CI` — Detect CI environment for automated workflows
+- `DEBUG` — Enable debug output
+- `GITZONE_FORMAT_PARALLEL` — Control parallel formatting
 
 ## 🎯 Common Workflows
 
@@ -383,8 +390,9 @@ gitzone services start
 # 4. Check service logs if needed
 gitzone services logs mongo
 
-# 5. Format code
+# 5. Preview format changes, then apply
 gitzone format
+gitzone format --write
 
 # 6. Commit with semantic versioning
 gitzone commit
@@ -393,6 +401,13 @@ gitzone commit
 gitzone services stop
 ```
 
+### Automated CI/CD Commit
+
+```bash
+# Auto-accept, test, build, push, and release in one command
+gitzone commit -ytbpr
+```
+
 ### Multi-Repository Management
 
 ```bash
@@ -408,29 +423,26 @@ gitzone meta add shared https://github.com/org/shared.git
 gitzone meta update
 ```
 
-### Safe Formatting with Rollback
+### Safe Formatting with Plan Review
 
 ```bash
-# 1. Preview changes
-gitzone format --dry-run
+# 1. Preview changes (default)
+gitzone format
 
 # 2. Save plan for review
 gitzone format --save-plan format-changes.json
 
-# 3. Apply formatting
-gitzone format --from-plan format-changes.json
-
-# 4. If something goes wrong, rollback
-gitzone format --rollback
+# 3. Apply from saved plan
+gitzone format --from-plan format-changes.json --write
 ```
 
 ### Database-Driven Development
 
 ```bash
-# 1. Start MongoDB and MinIO
+# 1. Start MongoDB, MinIO, and Elasticsearch
 gitzone services start
 
-# 2. Get connection string for your app
+# 2. Get connection details
 gitzone services config
 
 # 3. Connect with MongoDB Compass
@@ -447,43 +459,44 @@ gitzone services clean  # ⚠️ Warning: deletes data
 
 ### CI/CD Platforms
 
-- **GitLab CI** - Full pipeline support with templates
-- **GitHub Actions** - Automated workflows
-- **Docker** - Container-based deployments
+- **GitLab CI** — full pipeline support with templates
+- **GitHub Actions** — automated workflows
+- **Docker** — container-based deployments
 
 ### Development Tools
 
-- **TypeScript** - First-class support
-- **Prettier** - Code formatting
-- **npm/pnpm** - Package management
-- **MongoDB** - Local database service
-- **MinIO** - S3-compatible object storage
-- **MongoDB Compass** - Database GUI integration
+- **TypeScript** — first-class support
+- **Prettier** — code formatting
+- **pnpm** — package management
+- **MongoDB** — local database service
+- **MinIO** — S3-compatible object storage
+- **Elasticsearch** — search and analytics
+- **MongoDB Compass** — database GUI integration
 
 ### Version Control
 
-- **Git** - Deep integration
-- **Semantic Versioning** - Automatic version bumping
-- **Conventional Commits** - Standardized commit messages
+- **Git** — deep integration
+- **Semantic Versioning** — automatic version bumping
+- **Conventional Commits** — standardized commit messages
+- **AI-Powered Analysis** — intelligent commit suggestions via `@git.zone/tsdoc`
 
 ## 💡 Pro Tips
 
 1. **Use aliases**: Add `alias gz='gitzone'` to your shell profile
-2. **Combine commands**: `gitzone format --yes && gitzone commit`
+2. **Combine flags**: `gitzone commit -ypbr` for the full auto workflow
 3. **Leverage templates**: Start projects right with proven structures
 4. **Enable caching**: Dramatically speeds up formatting operations
-5. **Save format plans**: Review changes before applying in production
+5. **Save format plans**: Review changes before applying
 6. **Port management**: Let services auto-assign ports to avoid conflicts
 7. **Use MongoDB Compass**: `gitzone services compass` for visual DB management
+8. **Global service management**: `gitzone services status -g` to see all projects' services at once
 
 ## 🐛 Troubleshooting
 
 ### Format Command Shows "Cancelled"
 
-If the format command shows cancelled even after confirming:
-
 - Check your `npmextra.json` configuration
-- Try with `--yes` flag to skip confirmation
+- Try with `--yes --write` flags
 - Use `--verbose` for detailed output
 
 ### Docker Commands Fail
@@ -496,19 +509,20 @@ docker info
 
 ### Services Won't Start
 
-Check for port conflicts:
-
 ```bash
 # Services auto-assign ports, but you can check the config
 cat .nogit/env.json
 
 # Verify Docker is running
 docker ps
+
+# Reassign ports if there are conflicts
+gitzone services reconfigure
 ```
 
 ### Template Creation Issues
 
-Verify npm/pnpm is properly configured:
+Verify pnpm/npm is properly configured:
 
 ```bash
 npm config get registry
@@ -524,12 +538,11 @@ npm config get registry
 
 gitzone is optimized for speed:
 
-- **Parallel processing** for format operations
-- **Smart caching** to avoid redundant work
-- **Incremental updates** for meta repositories
-- **Minimal dependencies** for fast installation
-- **Isolated services** prevent resource conflicts
-- **Auto port assignment** eliminates manual configuration
+- ⚡ **Parallel processing** for format operations
+- 🧠 **Smart caching** to avoid redundant work
+- 📊 **Incremental updates** for meta repositories
+- 🐳 **Isolated services** prevent resource conflicts
+- 🎲 **Auto port assignment** eliminates manual configuration
 
 ## License and Legal Information