git.zone/cli
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(cli): split commit and release into target-based workflows

Browse Source
This commit is contained in:
Jürgen Kunz
2026-05-10 10:01:09 +00:00
parent 738fbaa64f
commit 0e27d54ad2
22 changed files with 1938 additions and 1057 deletions
Download Patch File Download Diff File Expand all files Collapse all files
readme.md
+269 -451
View File
@@ -1,101 +1,264 @@
# @git.zone/cli 🚀
**The ultimate CLI toolbelt for modern TypeScript development workflows**
`@git.zone/cli` is the development workflow CLI behind the `gitzone` and `gzone` commands. It helps TypeScript-heavy teams keep projects tidy, create semantic source commits, manage local Docker-backed services, scaffold new modules, and release software through explicit, target-based release configuration.
[![npm version](https://img.shields.io/npm/v/@git.zone/cli.svg)](https://www.npmjs.com/package/@git.zone/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
## 🎯 What is gitzone?
gitzone is a powerful command-line interface that supercharges your development workflow with automated project management, intelligent code formatting, seamless version control, and development service orchestration. Whether you're bootstrapping a new TypeScript project, maintaining code quality, managing complex multi-repository setups, or spinning up local development databases, gitzone has got you covered.
It is opinionated where that saves time: source commits and releases are separate, changelog entries flow through a standard `Pending` section, project config lives in `.smartconfig.json`, and release targets make side effects visible before they happen.
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## 🏃‍♂️ Quick Start
### Installation
## Install
```bash
# 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.
### Your First Commands
After installation, both binaries point to the same CLI:
```bash
# Create a new TypeScript npm package
gitzone template npm
gitzone --help
gzone --help
```
# Format your entire codebase (dry-run by default)
## The Big Idea
`gitzone commit` handles source history.
`gitzone release` handles release transactions.
That split is intentional. A commit should not unexpectedly publish npm packages, push Docker images, or trigger remote release pipelines. A release should clearly show which targets it will publish to.
## Quick Start
```bash
# Preview project standardization work
gitzone format
# Apply formatting changes
gitzone format --write
# Start local MongoDB and MinIO services
gitzone services start
# Create a semantic commit with AI-powered suggestions
# Create a semantic source commit
gitzone commit
# Preview the configured release transaction
gitzone release --plan
# Release pending changelog entries to configured targets
gitzone release
```
## 🛠️ Core Features
## Commands
### 🔀 Semantic Commits & Versioning
| Command | Purpose |
| --- | --- |
| `commit` | Analyze changes and create one semantic source commit |
| `release` | Turn pending changelog entries into a versioned release and publish targets |
| `format` | Plan or apply project formatting and standardization |
| `config` | Inspect, update, and migrate `.smartconfig.json` |
| `services` | Manage local MongoDB, MinIO, and Elasticsearch containers |
| `template` | Scaffold projects from built-in templates |
| `meta` | Manage multi-repository workspaces |
| `open` | Open repository assets like CI pages |
| `docker` | Run Docker maintenance tasks |
| `deprecate` | Deprecate npm packages across registries |
| `start` | Prepare an existing project for local work |
| `helpers` | Run small helper utilities |
Create standardized commits with AI-powered suggestions that automatically handle versioning:
Global flags include `--help`, `--json`, `--plain`, `--agent`, `--no-interactive`, and `--no-check-updates`.
## Commit Workflow
`gitzone commit` creates one semantic source commit. It does not bump versions, create tags, publish packages, or push Docker images.
```bash
# Interactive commit with AI recommendations
# Interactive semantic commit
gitzone commit
# Read-only recommendation for agents and scripts
# Read-only AI recommendation
gitzone commit recommend --json
# Auto-accept AI recommendations (skipped for BREAKING CHANGEs)
# Auto-accept safe recommendations
gitzone commit -y
# Auto-accept, push, build, and release
gitzone commit -ypbr
# Auto-accept, test, build, and push
gitzone commit -ytbp
# Show the resolved workflow without mutating anything
gitzone commit --plan
```
**Flags:**
The commit flow:
| 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 |
| | `--json` | Emit JSON for `gitzone commit recommend` |
1. Analyze the working tree.
2. Suggest commit type, scope, and message.
3. Write a human-readable entry into `changelog.md` under `## Pending`.
4. Stage and create one semantic source commit.
5. Optionally run formatting, tests, build, and push based on flags or config.
**Workflow steps:**
Commit flags:
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
| Flag | Meaning |
| --- | --- |
| `-y`, `--yes` | Auto-accept safe recommendations |
| `-t`, `--test` | Add test step |
| `-b`, `--build` | Add build step |
| `-p`, `--push` | Push after the source commit |
| `-f`, `--format` | Run `gitzone format --write` before commit |
| `--plan` | Show resolved workflow only |
Supports both npm (`package.json`) and Deno (`deno.json`) projects, including dual-type projects.
`-r` is intentionally not part of commit anymore. Use `gitzone release`.
### 🎨 Intelligent Code Formatting
## Release Workflow
Automatically format and standardize your entire codebase. **Dry-run by default** — nothing changes until you explicitly use `--write`:
`gitzone release` performs the release core once, then publishes to configured targets.
The release core is not configurable plumbing. It always follows the same professional release transaction:
1. Run configured preflight checks.
2. Read `changelog.md` `## Pending` entries.
3. Infer or accept a semver bump.
4. Update version files and baked commit info.
5. Move pending changelog entries into the new version section.
6. Create the local release commit.
7. Create the local release tag.
Targets decide what happens after that:
| Target | What it does |
| --- | --- |
| `git` | Pushes the release commit and tags, often triggering remote CI release builds |
| `npm` | Publishes the package to configured npm registries |
| `docker` | Builds and pushes configured Docker images |
```bash
# Preview what would change (default behavior)
# Preview the resolved release plan
gitzone release --plan
# Release to configured targets
gitzone release
# Release only to npm
gitzone release --target npm
# Release only to git and Docker
gitzone release --target git,docker
# Skip package/container publishing and keep only git target
gitzone release --no-publish
# Override inferred semver level
gitzone release --minor
```
Release flags:
| Flag | Meaning |
| --- | --- |
| `-y`, `--yes` | Run without interactive confirmation |
| `-t`, `--test` | Enable preflight tests |
| `-b`, `--build` | Enable preflight build |
| `-p`, `--push` | Enable the `git` target |
| `--target <csv>` | Use only selected targets, e.g. `git,npm` |
| `--npm` | Enable the `npm` target |
| `--docker` | Enable the `docker` target |
| `--no-publish` | Keep release core and `git` target only |
| `--no-build` | Disable preflight build for this run |
| `--major`, `--minor`, `--patch` | Override inferred semver level |
| `--plan` | Show resolved workflow only |
## Standard Changelog
The changelog is convention-based and intentionally not configured.
`gitzone commit` appends entries to:
```markdown
## Pending
```
`gitzone release` moves those pending entries into a dated version section:
```markdown
## 2026-05-10 - 2.15.0
```
The standard buckets are `Breaking Changes`, `Features`, `Fixes`, `Documentation`, and `Maintenance`.
## Configuration
All CLI config lives under `@git.zone/cli` in `.smartconfig.json`.
```json
{
"@git.zone/cli": {
"schemaVersion": 2,
"projectType": "npm",
"commit": {
"confirmation": "prompt",
"steps": ["analyze", "test", "build", "changelog", "commit", "push"]
},
"release": {
"confirmation": "prompt",
"preflight": {
"requireCleanTree": true,
"test": false,
"build": true
},
"targets": {
"git": {
"enabled": true,
"remote": "origin",
"pushBranch": true,
"pushTags": true
},
"npm": {
"enabled": true,
"registries": ["https://registry.npmjs.org"],
"accessLevel": "public",
"alreadyPublished": "success"
},
"docker": {
"enabled": false,
"images": []
}
}
}
}
}
```
NPM registries belong only here:
```text
@git.zone/cli.release.targets.npm.registries
```
Useful config commands:
```bash
# Show current @git.zone/cli config
gitzone config show --json
# Read the npm release target registries
gitzone config get release.targets.npm.registries
# Add an npm release target registry
gitzone config add https://registry.npmjs.org
# Set npm target access level
gitzone config access public
# Run schema migration to v2
gitzone config migrate 2
```
## Formatting
`gitzone format` is dry-run by default. That makes it safe to run in any repo.
```bash
# Preview changes
gitzone format
# Emit a machine-readable plan
@@ -104,471 +267,126 @@ gitzone format plan --json
# Apply changes
gitzone format --write
# Auto-approve without prompts
gitzone format --yes --write
# Show detailed diffs
gitzone format --diff
# Enable verbose logging
gitzone format --verbose
# Apply without prompt
gitzone format --write --yes
```
**Flags:**
Formatters include cleanup, smartconfig normalization, dependency license checks, package metadata normalization, template updates, `.gitignore`, TypeScript config, Prettier, README existence checks, and configured copy operations.
| 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 |
| `--verbose` | Enable verbose logging |
| `--diff` | Show file diffs |
| `--json` | Emit a read-only format plan as JSON |
## Development Services
**Formatters (executed in order):**
`gitzone services` manages local Docker-backed services for development projects.
1. 🧹 **Cleanup** — removes obsolete files (yarn.lock, package-lock.json, tslint.json, etc.)
2. ⚙️ **Smartconfig** — formats and standardizes `.smartconfig.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
Supported services:
### 🐳 Development Services Management
Effortlessly manage local development services (MongoDB, MinIO S3, Elasticsearch) with Docker:
| Service | Aliases |
| --- | --- |
| MongoDB | `mongo`, `mongodb` |
| MinIO | `minio`, `s3` |
| Elasticsearch | `elasticsearch`, `es` |
```bash
gitzone services [command]
```
**Commands:**
| 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 |
| `set <csv>` | Set enabled services without prompts |
| `enable <service...>` | Enable one or more services |
| `disable <service...>` | Disable one or more services |
| `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) |
**Service aliases:**
- `mongo` / `mongodb` — MongoDB
- `minio` / `s3` — MinIO (S3-compatible storage)
- `elasticsearch` / `es` — Elasticsearch
- `all` — All services (default)
**Key features:**
- 🎲 **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
**Global operations (`-g` flag):**
```bash
# List all registered projects
gitzone services list -g
# Show status across all projects
gitzone services status -g
# Stop all containers across all projects
gitzone services stop -g
# Remove stale registry entries
gitzone services cleanup -g
```
**Example workflow:**
```bash
# Start all services for your project
# Start configured services
gitzone services start
# Configure enabled services without prompts
# Enable specific services non-interactively
gitzone services set mongodb,minio
# Check what's running
# Check status
gitzone services status
# Get MongoDB Compass connection string
# Print MongoDB Compass connection string
gitzone services compass
# Output: mongodb://defaultadmin:defaultpass@192.168.1.100:27018/myproject?authSource=admin
# View MongoDB logs
# Show logs
gitzone services logs mongo 50
# Stop services when done
# Stop containers but keep data
gitzone services stop
# Remove containers and data
gitzone services clean
```
### ⚙️ Release & Commit Configuration
Service config is stored in `.nogit/env.json`. Data is stored below `.nogit/`, so it stays out of Git.
Manage release registries and commit settings:
## Templates
Start new projects with built-in scaffolds:
```bash
gitzone config [subcommand]
gitzone template npm
gitzone template service
gitzone template website
gitzone template wcc
```
| Command | Description |
| ---------------------------------- | ---------------------------------------------------------- |
| `show` | Display current release config (registries, access level) |
| `get <path>` | Read a single value from `@git.zone/cli` |
| `set <path> <value>` | Write a single value to `@git.zone/cli` |
| `unset <path>` | Remove a single value from `@git.zone/cli` |
| `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 |
Templates are rendered through SmartScaf and then can be normalized with `gitzone format`.
Configuration is stored in `.smartconfig.json` under the `@git.zone/cli` key.
## Meta Repositories
### 📦 Project Templates
Instantly scaffold production-ready projects with best practices built-in:
Use `gitzone meta` when one workspace coordinates multiple repositories.
```bash
gitzone template [template-name]
```
**Interactive templates:**
- **`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
Each template comes pre-configured with:
- ✅ 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
Manage multiple related repositories as a cohesive unit:
```bash
# Initialize a meta repository
gitzone meta init
# Add a sub-project
gitzone meta add [name] [git-url]
# Update all sub-projects (clone missing, clean superfluous)
gitzone meta add frontend https://example.com/org/frontend.git
gitzone meta update
# Remove a sub-project
gitzone meta remove [name]
gitzone meta remove frontend
```
### 🐳 Docker Management
Streamline your Docker workflow:
## Other Utilities
```bash
# Clean up all Docker resources (containers, images, volumes, networks)
# Docker cleanup
gitzone docker prune
```
### 🔗 Quick CI/CD Access
Jump directly to your CI/CD configurations:
```bash
# Open CI/CD settings
# Open GitLab CI settings or pipelines for the current repo
gitzone open ci
# Open pipelines view
gitzone open pipelines
```
Works with GitLab repositories to provide instant access to your deployment configurations.
### 📝 Package Deprecation
Smoothly transition users from old to new packages:
```bash
# Deprecate an old npm package interactively
gitzone deprecate
```
Interactive wizard that prompts for registry URLs, old package name, and new package name — then runs `npm deprecate` across all specified registries.
### 🚦 Project Initialization
Prepare existing projects for development:
```bash
# Prepare a project for local work
gitzone start
```
Automatically checks out master, pulls latest changes, and installs dependencies.
### 🔧 Helper Utilities
```bash
# Generate a unique short ID
# Generate a short unique ID
gitzone helpers shortid
```
## 📋 Configuration
## Troubleshooting
### .smartconfig.json
Customize gitzone behavior through `.smartconfig.json`:
```json
{
"@git.zone/cli": {
"projectType": "npm",
"cli": {
"interactive": true,
"output": "human",
"checkUpdates": true
},
"release": {
"registries": ["https://registry.npmjs.org"],
"accessLevel": "public"
},
"commit": {
"alwaysTest": false,
"alwaysBuild": false
},
"format": {
"interactive": true,
"showStats": true,
"modules": {
"skip": ["prettier"],
"only": []
}
}
}
}
```
### Environment Variables
- `CI` — Detect CI environment for automated workflows
- `DEBUG` — Enable debug output
- `GITZONE_FORMAT_PARALLEL` — Control parallel formatting
## 🎯 Common Workflows
### Full-Stack Development Cycle
Format only previews changes:
```bash
# 1. Start fresh
gitzone start
# 2. Spin up databases and services
gitzone services start
# 3. Make changes
# ... your development work ...
# 4. Check service logs if needed
gitzone services logs mongo
# 5. Preview format changes, then apply
gitzone format
gitzone format --write
```
# 6. Commit with semantic versioning
Release says there is nothing to release:
```bash
# Make sure commits have populated the Pending changelog section
gitzone commit
# 7. Stop services when done
gitzone services stop
```
### Automated CI/CD Commit
```bash
# Auto-accept, test, build, push, and release in one command
gitzone commit -ytbpr
```
### Agent-Friendly Inspection
```bash
# Top-level machine-readable help
gitzone help config --json
# Read-only commit recommendation
gitzone commit recommend --json
# Read-only format plan
gitzone format plan --json
# Read or change config without prompts
gitzone config get release.accessLevel
gitzone config set cli.interactive false
```
### Multi-Repository Management
```bash
# 1. Set up meta repository
gitzone meta init
# 2. Add all related projects
gitzone meta add frontend https://github.com/org/frontend.git
gitzone meta add backend https://github.com/org/backend.git
gitzone meta add shared https://github.com/org/shared.git
# 3. Synchronize updates
gitzone meta update
```
### Safe Formatting with Plan Review
```bash
# 1. Preview changes (default)
gitzone format
# 2. Save plan for review
gitzone format --save-plan format-changes.json
# 3. Apply from saved plan
gitzone format --from-plan format-changes.json --write
```
### Database-Driven Development
```bash
# 1. Start MongoDB, MinIO, and Elasticsearch
gitzone services start
# 2. Get connection details
gitzone services config
# 3. Connect with MongoDB Compass
gitzone services compass
# 4. Monitor services
gitzone services status
# 5. Clean everything when done
gitzone services clean # ⚠️ Warning: deletes data
```
## 🔌 Integrations
### CI/CD Platforms
- **GitLab CI** — full pipeline support with templates
- **GitHub Actions** — automated workflows
- **Docker** — container-based deployments
### Development Tools
- **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
- **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 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
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"
- Check your `npmextra.json` configuration
- Try with `--yes --write` flags
- Use `--verbose` for detailed output
### Docker Commands Fail
Ensure Docker daemon is running:
Docker services fail to start:
```bash
docker info
```
### Services Won't Start
```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 status
gitzone services reconfigure
```
### Template Creation Issues
Verify pnpm/npm is properly configured:
Config looks outdated:
```bash
npm config get registry
gitzone config migrate 2
gitzone config show --json
```
### MongoDB Connection Issues
- Ensure services are running: `gitzone services status`
- Check firewall settings for the assigned ports
- Use `gitzone services compass` for the correct connection string
## 📈 Performance
gitzone is optimized for speed:
- ⚡ **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
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.