sublime_cli_tools 0.0.22

# Workspace Tools CLI

[![Pull Request](https://github.com/websublime/workspace-tools/workflows/Pull%20Request/badge.svg)](https://github.com/websublime/workspace-tools/actions)
[![Crates.io](https://img.shields.io/crates/v/sublime_cli_tools.svg)](https://crates.io/crates/sublime_cli_tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive command-line interface for managing Node.js workspaces and monorepos with changeset-based version management.

---

## Overview

`workspace` (Workspace Tools CLI) provides:

- **Configuration Management**: Initialize and validate workspace configurations
- **Changeset Workflow**: Create, update, list, show, edit, and remove changesets
- **Version Management**: Intelligent version bumping with preview mode and multiple strategies
- **Dependency Upgrades**: Detect, apply, and rollback dependency updates
- **Audit System**: Comprehensive health checks with actionable insights
- **Change Analysis**: Detect affected packages from Git changes
- **CI/CD Integration**: JSON output modes and silent operation for automation

---

## Installation & Quick Start

For installation instructions and quick start guide, see the [main README](../../README.md#-quick-start).

---

## Documentation

This README provides complete CLI documentation based on the actual source code.

### Available Commands

```bash
workspace init                        # Initialize project configuration
workspace config <subcommand>         # Manage configuration
workspace changeset <subcommand>      # Manage changesets
workspace bump [options]              # Bump package versions
workspace upgrade <subcommand>        # Manage dependency upgrades
workspace audit [options]             # Run project health audit
workspace changes [options]           # Analyze repository changes
workspace status                      # Display workspace status information
workspace execute [options]           # Execute commands across packages
workspace version [options]           # Display version information
workspace clone <url> [destination]   # Clone repository with workspace setup
```

---

## Commands Reference

### `init` - Initialize Project Configuration

Creates a new configuration file for changeset-based version management.

**Usage:**
```bash
workspace init [OPTIONS]
```

**Options:**
- `--changeset-path <PATH>` - Changeset directory path (default: `.changesets`)
- `--environments <LIST>` - Comma-separated list of environments (e.g., `dev,staging,prod`)
- `--default-env <LIST>` - Comma-separated list of default environments
- `--strategy <STRATEGY>` - Versioning strategy (`independent` or `unified`)
- `--registry <URL>` - NPM registry URL (default: `https://registry.npmjs.org`)
- `--config-format <FORMAT>` - Configuration file format (`json`, `toml`, or `yaml`)
- `--force` - Overwrite existing configuration
- `--non-interactive` - Use default values without prompting

**Examples:**
```bash
# Interactive initialization
workspace init

# Non-interactive with specific options
workspace init --non-interactive --strategy independent --config-format yaml

# Force overwrite existing config
workspace init --force --environments "dev,staging,prod"
```

---

### `config` - Manage Configuration

View and validate project configuration.

#### `config show` - Display Current Configuration

Shows all configuration values from the detected config file.

**Usage:**
```bash
workspace config show
```

**Examples:**
```bash
# Show configuration (human-readable)
workspace config show

# Show configuration as JSON
workspace --format json config show
```

#### `config validate` - Validate Configuration File

Checks that the configuration file is valid and all required fields are present.

**Usage:**
```bash
workspace config validate
```

**Examples:**
```bash
# Validate configuration
workspace config validate

# Validate with detailed logging
workspace --log-level debug config validate
```

---

### `changeset` - Manage Changesets

Create, update, list, and manage changesets for version control.

#### `changeset create` - Create New Changeset

Creates a changeset for the current branch.

**Usage:**
```bash
workspace changeset create [OPTIONS]
```

**Options:**
- `--bump <TYPE>` - Bump type (`major`, `minor`, or `patch`)
- `--env <LIST>` - Comma-separated list of environments
- `--branch <NAME>` - Branch name (defaults to current Git branch)
- `--message <TEXT>` - Optional description of changes
- `--packages <LIST>` - Comma-separated list of packages (auto-detected if not provided)
- `--non-interactive` - Use provided flags without prompting
- `--force` - Overwrite existing changeset if one exists for the branch

**Examples:**
```bash
# Interactive creation
workspace changeset create

# Non-interactive with specific options
workspace changeset create --bump minor --env "staging,prod" --non-interactive

# Create with message
workspace changeset create --bump patch --message "Fix critical bug"

# Overwrite existing changeset
workspace changeset create --bump major --force
```

#### `changeset update` - Update Existing Changeset

Adds commits or packages to an existing changeset.

**Usage:**
```bash
workspace changeset update [ID] [OPTIONS]
```

**Arguments:**
- `<ID>` - Changeset ID or branch name (defaults to current branch)

**Options:**
- `--commit <HASH>` - Add specific commit hash
- `--packages <LIST>` - Comma-separated list of packages to add
- `--bump <TYPE>` - Update bump type (`major`, `minor`, or `patch`)
- `--env <LIST>` - Comma-separated list of environments to add

**Examples:**
```bash
# Update changeset for current branch
workspace changeset update

# Update specific changeset
workspace changeset update feature/new-api --bump major

# Add specific commit
workspace changeset update --commit abc123def
```

#### `changeset list` - List All Changesets

Shows all active changesets with optional filtering and sorting.

**Usage:**
```bash
workspace changeset list [OPTIONS]
```

**Options:**
- `--filter-package <NAME>` - Filter by package name
- `--filter-bump <TYPE>` - Filter by bump type (`major`, `minor`, or `patch`)
- `--filter-env <ENV>` - Filter by environment
- `--sort <FIELD>` - Sort by field (`date`, `bump`, or `branch`; default: `date`)

**Examples:**
```bash
# List all changesets
workspace changeset list

# Filter by package
workspace changeset list --filter-package "@myorg/core"

# Filter and sort
workspace changeset list --filter-bump major --sort bump
```

#### `changeset show` - Show Changeset Details

Displays detailed information about a specific changeset.

**Usage:**
```bash
workspace changeset show <BRANCH>
```

**Arguments:**
- `<BRANCH>` - Branch name or changeset ID

**Examples:**
```bash
# Show changeset for branch
workspace changeset show feature/new-api

# Show as JSON
workspace --format json changeset show feature/new-api
```

#### `changeset edit` - Edit Changeset

Opens the changeset file in your editor ($EDITOR).

**Usage:**
```bash
workspace changeset edit [BRANCH]
```

**Arguments:**
- `<BRANCH>` - Branch name (defaults to current Git branch)

**Examples:**
```bash
# Edit changeset for current branch
workspace changeset edit

# Edit changeset for specific branch
workspace changeset edit feature/new-api
```

#### `changeset delete` - Delete Changeset

Removes a changeset from active changesets.

**Usage:**
```bash
workspace changeset delete <BRANCH> [OPTIONS]
```

**Arguments:**
- `<BRANCH>` - Branch name

**Options:**
- `--force` - Skip confirmation prompt

**Examples:**
```bash
# Delete with confirmation
workspace changeset delete feature/old-branch

# Delete without confirmation
workspace changeset delete feature/old-branch --force
```

#### `changeset history` - Query Changeset History

Searches archived changesets with filtering options.

**Usage:**
```bash
workspace changeset history [OPTIONS]
```

**Options:**
- `--filter-package <NAME>` - Filter by package name
- `--since <DATE>` - Since date (ISO 8601, e.g., `2024-01-01`)
- `--until <DATE>` - Until date (ISO 8601)
- `--filter-env <ENV>` - Filter by environment
- `--filter-bump <TYPE>` - Filter by bump type
- `--limit <N>` - Limit number of results

**Examples:**
```bash
# Show all history
workspace changeset history

# Filter by package and date range
workspace changeset history --filter-package "@myorg/core" --since "2024-01-01"

# Filter by environment and bump type
workspace changeset history --filter-env production --filter-bump major

# Limit results
workspace changeset history --limit 10
```

#### `changeset check` - Check if Changeset Exists

Checks if a changeset exists for the current or specified branch. Useful for Git hooks.

**Usage:**
```bash
workspace changeset check [OPTIONS]
```

**Options:**
- `--branch <NAME>` - Branch name (defaults to current Git branch)

**Examples:**
```bash
# Check current branch
workspace changeset check

# Check specific branch
workspace changeset check --branch feature/new-api
```

---

### `bump` - Bump Package Versions

Calculates and applies version bumps according to active changesets and the configured versioning strategy.

**Usage:**
```bash
workspace bump [OPTIONS]
```

**Options:**
- `--dry-run` - Preview changes without applying (safe, default behavior)
- `--execute` - Apply version changes (required for actual changes)
- `--snapshot` - Generate snapshot versions (mutually exclusive with `--prerelease`)
- `--snapshot-format <FORMAT>` - Snapshot format template (variables: `{version}`, `{branch}`, `{short_commit}`, `{commit}`)
- `--prerelease <TAG>` - Pre-release tag (`alpha`, `beta`, or `rc`) (mutually exclusive with `--snapshot`)
- `--packages <LIST>` - Comma-separated list of packages to bump (overrides changeset packages)
- `--git-tag` - Create Git tags for releases (format: `package@version`)
- `--git-push` - Push Git tags to remote (requires `--git-tag`)
- `--git-commit` - Commit version changes
- `--no-changelog` - Skip changelog generation/updates
- `--no-archive` - Keep changesets active after bump
- `--force` - Skip confirmations
- `--show-diff` - Show detailed version diffs (preview mode only)

**Note:** The `--snapshot` and `--prerelease` flags cannot be used together as they represent different versioning strategies.

**Examples:**
```bash
# Preview version bumps (safe, no changes)
workspace bump --dry-run

# Apply version bumps
workspace bump --execute

# Full release workflow
workspace bump --execute --git-commit --git-tag --git-push

# Snapshot version for testing
workspace bump --snapshot --execute

# Pre-release version
workspace bump --prerelease beta --execute

# Show detailed diffs in preview
workspace bump --dry-run --show-diff
```

#### Changeset Archive Policies

When bumping versions, the CLI can automatically archive processed changesets based on configurable policies. This prevents changesets from being reused in future bumps while maintaining a complete history.

**Available Policies:**

| Policy | Flags | Behavior | Use Case |
|--------|-------|----------|----------|
| **Auto** | *(none)* | Archives only stable versions | Default behavior - keeps prereleases active for iterative development |
| **Never** | `--no-archive` | Never archives changesets | Keep all changesets for review or manual cleanup |
| **Always** | `--always-archive` | Always archives changesets | Archive every bump, including prereleases |

**Policy Behavior:**

1. **Auto Policy** (Default)
   ```bash
   workspace bump --execute
   # Stable version: 1.2.3 → 1.3.0
   # Result: Changesets are ARCHIVED ✅
   
   workspace bump --execute --prerelease beta.create
   # Prerelease version: 1.2.3 → 1.3.0-beta.0
   # Result: Changesets are NOT archived ❌ (kept for next bump)
   ```

2. **Never Policy**
   ```bash
   workspace bump --execute --no-archive
   # Any version: 1.2.3 → 1.3.0
   # Result: Changesets are NOT archived ❌ (manual cleanup required)
   ```

3. **Always Policy**
   ```bash
   workspace bump --execute --always-archive
   # Stable version: 1.2.3 → 1.3.0
   # Result: Changesets are ARCHIVED ✅
   
   workspace bump --execute --prerelease beta.create --always-archive
   # Prerelease version: 1.2.3 → 1.3.0-beta.0
   # Result: Changesets are ARCHIVED ✅ (even for prereleases)
   ```

**Prerelease Workflow Example:**

The Auto policy enables clean prerelease workflows:

```bash
# Phase 1: Create initial beta (changesets NOT archived)
workspace bump --execute --prerelease beta.create
# 1.2.3 → 1.3.0-beta.0
# Changesets remain active ✓

# Phase 2: Increment beta (changesets NOT archived)
workspace bump --execute --prerelease beta.increment
# 1.3.0-beta.0 → 1.3.0-beta.1
# Changesets remain active ✓

# Phase 3: Create release candidate (changesets NOT archived)
workspace bump --execute --prerelease rc.create
# 1.3.0-beta.1 → 1.3.0-rc.0
# Changesets remain active ✓

# Phase 4: Promote to stable (changesets ARCHIVED)
workspace bump --execute --prerelease rc.promote
# 1.3.0-rc.0 → 1.3.0
# Changesets archived automatically ✓
```

**Conflict Protection:**

The `--no-archive` and `--always-archive` flags are mutually exclusive. The CLI prevents using both flags simultaneously:

```bash
workspace bump --execute --no-archive --always-archive
# Error: The argument '--no-archive' cannot be used with '--always-archive'
```

**When to Use Each Policy:**

- **Auto** (recommended): Standard workflow with prerelease support
- **Never**: Auditing, manual changeset management, or keeping full history active
- **Always**: Strict cleanup even for prereleases, or when changesets are single-use

---

### `upgrade` - Manage Dependency Upgrades

Check for available upgrades and apply them to workspace packages.

#### `upgrade check` - Check for Available Upgrades

Detects outdated dependencies in workspace packages.

**Usage:**
```bash
workspace upgrade check [OPTIONS]
```

**Options:**
- `--no-major` - Exclude major version upgrades from results (default: included)
- `--no-minor` - Exclude minor version upgrades from results (default: included)
- `--no-patch` - Exclude patch version upgrades from results (default: included)
- `--no-dev` - Exclude dev dependencies from results (default: included)
- `--peer` - Include peer dependencies in results (default: excluded)
- `--packages <LIST>` - Comma-separated list of packages to check
- `--registry <URL>` - Override registry URL (must be valid HTTP/HTTPS URL)

**Examples:**
```bash
# Check all upgrades
workspace upgrade check

# Check only non-breaking upgrades (exclude major)
workspace upgrade check --no-major

# Check only patch and minor upgrades
workspace upgrade check --no-major

# Exclude dev dependencies
workspace upgrade check --no-dev

# Check specific packages
workspace upgrade check --packages "@myorg/core,@myorg/utils"

# Include peer dependencies
workspace upgrade check --peer

# Use custom registry
workspace upgrade check --registry "https://npm.mycompany.com"
```

#### `upgrade apply` - Apply Dependency Upgrades

Updates dependencies to newer versions.

**Usage:**
```bash
workspace upgrade apply [OPTIONS]
```

**Options:**
- `--dry-run` - Preview without applying
- `--patch-only` - Only apply patch upgrades
- `--minor-and-patch` - Only apply minor and patch upgrades (non-breaking)
- `--packages <LIST>` - Comma-separated list of packages to upgrade
- `--auto-changeset` - Automatically create changeset for upgrades
- `--changeset-bump <TYPE>` - Changeset bump type (`major`, `minor`, or `patch`; default: `patch`)
- `--no-backup` - Skip backup creation (use with caution! recommended for CI/CD or when using Git for version control)
- `--force` - Skip confirmations

**Examples:**
```bash
# Preview upgrades
workspace upgrade apply --dry-run

# Apply safe upgrades with automatic changeset
workspace upgrade apply --minor-and-patch --auto-changeset

# Apply patch upgrades only
workspace upgrade apply --patch-only --force

# Apply upgrades for specific packages
workspace upgrade apply --packages "@myorg/core"

# Apply without backup (CI/CD scenario with Git version control)
git add . && git commit -m "Pre-upgrade commit"
workspace upgrade apply --no-backup --force
```

#### `upgrade backups` - Manage Upgrade Backups

List, restore, or clean upgrade backups.

**`upgrade backups list`** - List all backups:
```bash
workspace upgrade backups list
```

**`upgrade backups restore`** - Restore a backup:
```bash
workspace upgrade backups restore <ID> [OPTIONS]
```
Options:
- `--force` - Skip confirmation prompt

Example:
```bash
workspace upgrade backups restore backup_20240115_103045
```

**`upgrade backups clean`** - Clean old backups:
```bash
workspace upgrade backups clean [OPTIONS]
```
Options:
- `--keep <N>` - Number of recent backups to keep (default: 5)
- `--force` - Skip confirmation prompt

Example:
```bash
workspace upgrade backups clean --keep 3 --force
```

---

### `audit` - Run Project Health Audit

Analyzes project health including upgrades, dependencies, version consistency, and breaking changes.

**Usage:**
```bash
workspace audit [OPTIONS]
```

**Options:**
- `--sections <LIST>` - Comma-separated list of sections to audit (default: `all`)
  - Options: `all`, `upgrades`, `dependencies`, `version-consistency`, `breaking-changes`
- `--output <PATH>` - Write output to file
- `--min-severity <LEVEL>` - Minimum severity level (default: `info`)
  - Options: `critical`, `high`, `medium`, `low`, `info`
- `--verbosity <LEVEL>` - Detail level (default: `normal`)
  - Options: `minimal`, `normal`, `detailed`
- `--no-health-score` - Skip health score calculation
- `--export <FORMAT>` - Export format (`html` or `markdown`; requires `--export-file`)
- `--export-file <PATH>` - File path for exported report (requires `--export`)

**Examples:**
```bash
# Full audit
workspace audit

# Specific sections
workspace audit --sections upgrades,dependencies

# High severity issues only
workspace audit --min-severity high

# Export to markdown
workspace audit --export markdown --export-file audit-report.md

# JSON output for CI/CD
workspace --format json audit
```

---

### `changes` - Analyze Repository Changes

Detects which packages are affected by changes in the working directory or between commits.

**Usage:**
```bash
workspace changes [OPTIONS]
```

**Options:**
- `--since <REF>` - Since commit/branch/tag (analyzes changes since this Git reference)
- `--until <REF>` - Until commit/branch/tag (default: `HEAD`)
- `--branch <NAME>` - Compare against branch
- `--staged` - Only staged changes (cannot be used with `--unstaged`)
- `--unstaged` - Only unstaged changes (cannot be used with `--staged`)
- `--packages <LIST>` - Comma-separated list of packages to filter

**Examples:**
```bash
# Analyze working directory changes
workspace changes

# Changes since specific commit
workspace changes --since HEAD~5

# Changes between commits
workspace changes --since v1.0.0 --until v1.1.0

# Only staged changes
workspace changes --staged

# Compare against branch
workspace changes --branch main

# Filter specific packages
workspace changes --packages "@myorg/core"
```

---

### `status` - Display Workspace Status

Shows comprehensive workspace information including repository type, package manager, active branch, pending changesets, and all workspace packages.

**Usage:**
```bash
workspace status
```

**Output Includes:**
- **Repository Type**: `simple` (single package) or `monorepo` (with type: npm, yarn, pnpm, bun)
- **Package Manager**: Detected package manager (npm, yarn, pnpm, bun) and lock file
- **Git Branch**: Current branch name (if in a Git repository)
- **Pending Changesets**: List of active changeset IDs
- **Packages**: Table with name, version, and path for all workspace packages

**Examples:**
```bash
# Display workspace status (human-readable)
workspace status

# Display as JSON (for automation)
workspace --format json status

# Quiet mode (minimal output)
workspace --quiet status
```

**JSON Output Structure:**
```json
{
  "success": true,
  "data": {
    "repository": {
      "kind": "monorepo",
      "monorepoType": "npm"
    },
    "packageManager": {
      "name": "npm",
      "lockFile": "package-lock.json"
    },
    "branch": {
      "name": "feature/new-api"
    },
    "changesets": [
      { "id": "feature-new-api" }
    ],
    "packages": [
      { "name": "@myorg/core", "version": "1.2.0", "path": "packages/core" },
      { "name": "@myorg/utils", "version": "1.0.5", "path": "packages/utils" }
    ]
  }
}
```

---

### `execute` - Execute Commands Across Packages

Runs commands across workspace packages with optional filtering and parallel execution. Supports both npm scripts and system commands.

**Usage:**
```bash
workspace execute --cmd <COMMAND> [OPTIONS]
```

**Options:**
- `--cmd <COMMAND>` - Command to execute (required)
  - `npm:<script>` - Run npm script (e.g., `npm:lint`, `npm:build`, `npm:test`)
  - Plain command - Run system command (e.g., `echo hello`, `ls -la`)
- `--filter-package <PACKAGES>` - Comma-separated list of packages to run on (default: all)
- `--parallel` - Run commands in parallel across packages (default: sequential)
- `-- <ARGS>` - Additional arguments to pass to the command

**Command Formats:**

| Format | Description | Example |
|--------|-------------|---------|
| `npm:<script>` | Runs npm script via detected package manager | `npm:lint`, `npm:build` |
| Plain command | Runs system command directly | `echo hello`, `ls -la` |

**Examples:**
```bash
# Run npm lint script in all packages
workspace execute --cmd npm:lint

# Run npm test in specific packages
workspace execute --cmd npm:test --filter-package "@myorg/core,@myorg/utils"

# Run commands in parallel (faster for independent packages)
workspace execute --cmd npm:build --parallel

# Run system command in all packages
workspace execute --cmd "echo hello"

# Pass extra arguments to npm script
workspace execute --cmd npm:test -- --coverage --watch

# Run lint only in core package
workspace execute --cmd npm:lint --filter-package "@myorg/core"

# JSON output for CI/CD
workspace --format json execute --cmd npm:test
```

**Execution Behavior:**

- **Sequential (default)**: Commands run one package at a time, with streaming output
- **Parallel (`--parallel`)**: Commands run concurrently, output collected and displayed per package
- **npm Scripts**: Validates script exists in package.json before execution
- **Failure Handling**: Continues on failure, reports all failures at end with summary

**JSON Output Structure:**
```json
{
  "success": true,
  "data": {
    "command": "npm:test",
    "results": [
      {
        "package": "@myorg/core",
        "success": true,
        "duration_ms": 1234,
        "exit_code": 0
      },
      {
        "package": "@myorg/utils",
        "success": true,
        "duration_ms": 567,
        "exit_code": 0
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0,
      "duration_ms": 1801
    }
  }
}
```

**Use Cases:**

```bash
# CI/CD: Run tests across all packages
workspace execute --cmd npm:test --parallel

# Development: Lint before commit
workspace execute --cmd npm:lint

# Build specific packages
workspace execute --cmd npm:build --filter-package "@myorg/core"

# Run custom script with arguments
workspace execute --cmd npm:test -- --updateSnapshot
```

---

### `version` - Display Version Information

Shows the CLI version and optionally detailed build information.

**Usage:**
```bash
workspace version [OPTIONS]
```

**Options:**
- `--verbose` - Show detailed version information (includes Rust version, dependencies, and build info)

**Examples:**
```bash
# Show version
workspace version

# Show detailed information
workspace version --verbose
```

---

### `clone` - Clone Repository with Workspace Setup

Clones a Git repository and automatically initializes or validates workspace configuration for immediate development.

**Usage:**
```bash
workspace clone <URL> [DESTINATION] [OPTIONS]
```

**Arguments:**
- `<URL>` - Repository URL to clone from (HTTPS or SSH)
- `[DESTINATION]` - Optional destination path (defaults to repository name)

**Options:**

*Clone Options:*
- `--force` - Overwrite destination if it exists
- `--depth <N>` - Create shallow clone with specified depth
- `--skip-validation` - Skip configuration validation (even if config exists)
- `--non-interactive` - Skip interactive prompts

*Init Options (used if no config found):*
- `--changeset-path <PATH>` - Changeset directory path (default: `.changesets`)
- `--environments <LIST>` - Comma-separated list of environments
- `--default-env <LIST>` - Comma-separated list of default environments
- `--strategy <STRATEGY>` - Versioning strategy (`independent` or `unified`)
- `--registry <URL>` - NPM registry URL (default: `https://registry.npmjs.org`)
- `--config-format <FORMAT>` - Config file format (`json`, `toml`, or `yaml`)

**Behavior:**

The clone command follows this workflow:

1. **Clone repository** - Downloads the repository with progress indication
2. **Detect configuration** - Searches for existing workspace configuration
3. **Path A: Configuration exists** 
   - Validates configuration file structure
   - Checks required directories exist (.changesets/, .changesets/history/, .workspace-backups/)
   - Verifies .gitignore entries
   - Reports validation results
4. **Path B: No configuration**
   - Automatically runs `init` command
   - Creates workspace configuration
   - Sets up directory structure
   - Updates .gitignore

**Examples:**

```bash
# Clone to default location (repository name)
workspace clone https://github.com/org/repo.git

# Clone to specific directory
workspace clone https://github.com/org/repo.git ./my-project

# Clone with SSH
workspace clone git@github.com:org/repo.git

# Clone and force overwrite existing directory
workspace clone https://github.com/org/repo.git --force

# Shallow clone (faster, less disk space)
workspace clone https://github.com/org/repo.git --depth 1

# Clone with init configuration (non-interactive)
workspace clone https://github.com/org/repo.git \
  --non-interactive \
  --strategy independent \
  --environments "dev,staging,prod" \
  --default-env "prod"

# Clone and skip validation
workspace clone https://github.com/org/repo.git --skip-validation

# Clone for CI/CD with JSON output
workspace --format json clone https://github.com/org/repo.git ./workspace
```

**Error Scenarios:**

The clone command handles various error scenarios with helpful messages:

```bash
# Network/DNS failure
workspace clone https://github.com/org/invalid.git
# Error: Network error: Could not resolve host for URL
# Suggestions:
#   - Check your internet connection
#   - Verify the repository URL is correct

# Authentication failure (SSH)
workspace clone git@github.com:private/repo.git
# Error: Authentication error: Failed to authenticate
# Suggestions:
#   - Ensure your SSH key is added to your SSH agent
#   - Verify your SSH key is registered with GitHub
#   - Try: ssh -T git@github.com to test connection

# Authentication failure (HTTPS)
workspace clone https://github.com/private/repo.git
# Error: Authentication error: Failed to authenticate
# Suggestions:
#   - Verify you have access to this repository
#   - Ensure authentication is configured
#   - Check if your access token is valid

# Destination exists (without --force)
workspace clone https://github.com/org/repo.git ./existing-dir
# Error: Destination already exists: ./existing-dir
# Use --force to overwrite

# Repository not found
workspace clone https://github.com/org/nonexistent.git
# Error: Repository not found
# Suggestions:
#   - Verify the repository URL is correct
#   - Check if the repository exists
#   - Ensure you have access if repository is private

# Disk space error
workspace clone https://github.com/large/repository.git
# Error: Insufficient disk space to clone repository
# Suggestions:
#   - Free up disk space
#   - Choose a different destination with more space
#   - Consider using --depth 1 for a shallow clone

# Validation failure (existing config)
workspace clone https://github.com/org/broken-config.git
# Clone succeeds
# Validation detects:
#   ✗ Changeset directory
#     Error: Directory '.changesets' does not exist
#     Suggestion: Run 'workspace init --force' to create directory
#   ✗ .gitignore entries
#     Error: Missing .gitignore entries for workspace directories
#     Suggestion: Run 'workspace init --force' to update .gitignore
```

**Integration Examples:**

*CI/CD Pipeline (GitHub Actions):*

```yaml
name: Setup Development Environment

on:
  workflow_dispatch:
    inputs:
      repository:
        description: 'Repository to clone'
        required: true
      branch:
        description: 'Branch to checkout'
        default: 'main'

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - name: Clone and setup workspace
        run: |
          workspace clone ${{ github.event.inputs.repository }} \
            --non-interactive \
            --strategy independent \
            --config-format yaml

      - name: Checkout specific branch
        working-directory: ./repo-name
        run: git checkout ${{ github.event.inputs.branch }}

      - name: Verify setup
        working-directory: ./repo-name
        run: workspace config validate
```

*Developer Onboarding Script:*

```bash
#!/bin/bash
# onboard.sh - Quick setup for new developers

REPO_URL="https://github.com/myorg/monorepo.git"
DEST_DIR="$HOME/projects/monorepo"

echo "Setting up development environment..."

# Clone with workspace setup
workspace clone "$REPO_URL" "$DEST_DIR" \
  --non-interactive \
  --strategy independent \
  --environments "dev,staging,production" \
  --default-env "production" \
  --config-format toml

cd "$DEST_DIR" || exit 1

# Verify setup
echo "Verifying workspace configuration..."
workspace config validate

echo "Setup complete! You can now:"
echo "  cd $DEST_DIR"
echo "  workspace changeset create"
echo "  workspace bump --dry-run"
```

*Automated Testing Environment:*

```bash
#!/bin/bash
# test-setup.sh - Create isolated test environment

TEST_DIR=$(mktemp -d)
REPO="https://github.com/org/repo.git"

# Clone with shallow depth for faster setup
workspace clone "$REPO" "$TEST_DIR/workspace" \
  --depth 1 \
  --non-interactive \
  --skip-validation \
  --force

cd "$TEST_DIR/workspace" || exit 1

# Run tests
npm install
npm test

# Cleanup
rm -rf "$TEST_DIR"
```

*Mirror Repository Setup:*

```bash
#!/bin/bash
# mirror.sh - Setup repository mirror

SOURCE="https://github.com/upstream/original.git"
MIRROR_DIR="/var/repos/mirror"

# Clone original repository
workspace clone "$SOURCE" "$MIRROR_DIR" \
  --force \
  --config-format json

cd "$MIRROR_DIR" || exit 1

# Add mirror remote
git remote add mirror https://git.mycompany.com/mirror.git

# Validate workspace setup
workspace config validate && echo "Mirror setup complete"
```

---

## Global Options

All commands support these global options that control behavior across the entire application:

**Options:**
- `-r, --root <PATH>` - Project root directory (default: current directory)
  - Changes working directory before executing the command
  - All file operations will be relative to this path
  
- `-l, --log-level <LEVEL>` - Logging level (default: `info`)
  - Controls verbosity of operation logs written to **stderr**
  - Does NOT affect command output (stdout)
  - Levels: `silent`, `error`, `warn`, `info`, `debug`, `trace`, `verbose`
  - Note: `verbose` is an alias for `info` level
  
- `-q, --quiet` - Suppress all output
  - Shortcut that sets both `--log-level silent` and `--format quiet`
  - Useful for scripts that only care about exit codes
  
- `-v, --verbose` - Enable verbose output
  - Shortcut that sets `--log-level debug`
  - Useful for debugging and troubleshooting
  
- `-f, --format <FORMAT>` - Output format (default: `human`)
  - Controls format of command output written to **stdout**
  - Does NOT affect logging (stderr)
  - Formats: `human`, `json`, `json-compact`, `quiet`
  
- `--no-color` - Disable colored output
  - Removes ANSI color codes from both logs (stderr) and output (stdout)
  - Also respects the `NO_COLOR` environment variable
  - Useful for CI/CD environments and file redirection
  
- `-c, --config <PATH>` - Path to config file
  - Override default config file location
  - Path can be relative or absolute
  - Default: Auto-detect (`.changesets.{toml,json,yaml,yml}`)

**Stream Separation:**

The CLI maintains strict separation between:
- **stderr**: Logs only (controlled by `--log-level`)
- **stdout**: Command output only (controlled by `--format`)

This ensures JSON output is never contaminated with logs, enabling reliable piping and parsing in scripts.

**Examples:**
```bash
# Clean JSON output with no logs (perfect for automation)
workspace --format json --log-level silent bump --dry-run

# JSON output with debug logs (logs to stderr, JSON to stdout)
workspace --format json --log-level debug bump --dry-run > output.json 2> debug.log

# Change working directory
workspace --root /path/to/project changeset list

# Use custom config file
workspace --config custom-config.toml config show
```

---

## Configuration

The CLI uses a configuration file (`repo.config.toml`, `repo.config.json`, or `repo.config.yaml`) to control all aspects of workspace management. This file is typically created by running `workspace init`.

### Configuration File Location

The CLI automatically detects configuration files in this order:
1. Path specified via `--config` flag
2. `repo.config.toml` in project root
3. `repo.config.yaml` or `repo.config.yml` in project root
4. `repo.config.json` in project root

### Configuration Structure

The configuration is organized into logical sections under the `[package_tools]` namespace:

```toml
[package_tools.changeset]
# Changeset storage and management

[package_tools.version]
# Versioning strategy

[package_tools.dependency]
# Dependency propagation

[package_tools.upgrade]
# Dependency upgrade detection

[package_tools.changelog]
# Changelog generation

[package_tools.git]
# Git integration

[package_tools.audit]
# Health checks and audits

[package_tools.workspace]
# Monorepo workspace patterns (optional)
```

---

### Complete Example Configuration

```toml
[package_tools.changeset]
path = ".changesets"
history_path = ".changesets/history"
available_environments = ["development", "staging", "production"]
default_environments = ["production"]

[package_tools.version]
strategy = "independent"  # or "unified"
default_bump = "patch"
snapshot_format = "{version}-{branch}.{timestamp}"

[package_tools.dependency]
propagation_bump = "patch"
propagate_dependencies = true
propagate_dev_dependencies = false
propagate_peer_dependencies = true
max_depth = 10
fail_on_circular = true
skip_workspace_protocol = true
skip_file_protocol = true
skip_link_protocol = true
skip_portal_protocol = true

[package_tools.upgrade]
auto_changeset = true
changeset_bump = "patch"

[package_tools.upgrade.registry]
default_registry = "https://registry.npmjs.org"
scoped_registries = {}
auth_tokens = {}
timeout_secs = 30
retry_attempts = 3
retry_delay_ms = 1000
read_npmrc = true

[package_tools.upgrade.backup]
enabled = true
backup_dir = ".workspace-backups"
keep_after_success = false
max_backups = 5

[package_tools.changelog]
enabled = true
format = "keep-a-changelog"  # or "conventional" or "custom"
filename = "CHANGELOG.md"
include_commit_links = true
include_issue_links = true
include_authors = false
repository_url = "https://github.com/your-org/your-repo"
monorepo_mode = "per-package"  # or "root" or "both"
version_tag_format = "{name}@{version}"
root_tag_format = "v{version}"

[package_tools.changelog.conventional]
enabled = true
breaking_section = "Breaking Changes"

[package_tools.changelog.conventional.types]
feat = "Features"
fix = "Bug Fixes"
perf = "Performance Improvements"
refactor = "Code Refactoring"
docs = "Documentation"
build = "Build System"
ci = "Continuous Integration"
test = "Tests"
chore = "Chores"

[package_tools.changelog.exclude]
patterns = []
authors = []

[package_tools.changelog.template]
header = "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n"
version_header = "## [{version}] - {date}"
section_header = "### {section}"
entry_format = "- {description} ({hash})"

[package_tools.git]
merge_commit_template = "chore(release): {version}\n\nRelease version {version}\n\n{changelog_summary}"
monorepo_merge_commit_template = "chore(release): {package_name}@{version}\n\nRelease {package_name} version {version}\n\n{changelog_summary}"
include_breaking_warning = true
breaking_warning_template = "\n⚠️  BREAKING CHANGES: {breaking_changes_count}\n"

[package_tools.audit]
enabled = true
min_severity = "warning"  # "critical", "warning", or "info"

[package_tools.audit.sections]
upgrades = true
dependencies = true
breaking_changes = true
categorization = true
version_consistency = true

[package_tools.audit.upgrades]
include_patch = true
include_minor = true
include_major = true
deprecated_as_critical = true

[package_tools.audit.dependencies]
check_circular = true
check_missing = false
check_unused = false
check_version_conflicts = true

[package_tools.audit.breaking_changes]
check_conventional_commits = true
check_changelog = true

[package_tools.audit.version_consistency]
fail_on_inconsistency = false
warn_on_inconsistency = true

[package_tools.audit.health_score_weights]
critical_weight = 15.0
warning_weight = 5.0
info_weight = 1.0
security_multiplier = 1.5
breaking_changes_multiplier = 1.3
dependencies_multiplier = 1.2
version_consistency_multiplier = 1.0
upgrades_multiplier = 0.8
other_multiplier = 1.0

# Optional: Only for monorepo projects with workspace patterns
[package_tools.workspace]
patterns = ["packages/*", "apps/*"]
```

---

### Configuration Reference

#### `[package_tools.changeset]` - Changeset Management

Controls where changesets are stored and what environments are available.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `path` | String | `".changesets"` | Directory for active changesets |
| `history_path` | String | `".changesets/history"` | Directory for archived changesets |
| `available_environments` | Array | `["production"]` | Valid environment names for deployment targeting |
| `default_environments` | Array | `["production"]` | Environments used when none are specified |

**Example:**
```toml
[package_tools.changeset]
path = ".changesets"
history_path = ".changesets/history"
available_environments = ["dev", "staging", "prod"]
default_environments = ["prod"]
```

---

#### `[package_tools.version]` - Versioning Strategy

Defines how package versions are calculated and applied.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `strategy` | String | `"independent"` | Versioning strategy: `"independent"` (each package has own version) or `"unified"` (all packages share same version) |
| `default_bump` | String | `"patch"` | Default version bump when not specified in changeset: `"major"`, `"minor"`, `"patch"`, or `"none"` |
| `snapshot_format` | String | `"{version}-{branch}.{timestamp}"` | Format template for snapshot versions. Placeholders: `{version}`, `{branch}`, `{timestamp}`, `{short_hash}` |

**Example:**
```toml
[package_tools.version]
strategy = "unified"
default_bump = "minor"
snapshot_format = "{version}-snapshot.{short_hash}"
```

---

#### `[package_tools.dependency]` - Dependency Propagation

Controls how version changes propagate through the dependency graph.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `propagation_bump` | String | `"patch"` | Version bump type for propagated updates: `"major"`, `"minor"`, `"patch"`, or `"none"` |
| `propagate_dependencies` | Boolean | `true` | Propagate version updates to regular dependencies |
| `propagate_dev_dependencies` | Boolean | `false` | Propagate version updates to devDependencies |
| `propagate_peer_dependencies` | Boolean | `true` | Propagate version updates to peerDependencies |
| `max_depth` | Integer | `10` | Maximum depth for dependency propagation (0 = unlimited) |
| `fail_on_circular` | Boolean | `true` | Fail when circular dependencies are detected |
| `skip_workspace_protocol` | Boolean | `true` | Skip dependencies using workspace protocol (`workspace:*`) |
| `skip_file_protocol` | Boolean | `true` | Skip dependencies using file protocol (`file:../path`) |
| `skip_link_protocol` | Boolean | `true` | Skip dependencies using link protocol (`link:../path`) |
| `skip_portal_protocol` | Boolean | `true` | Skip dependencies using portal protocol (`portal:../path`) |

**Example:**
```toml
[package_tools.dependency]
propagation_bump = "minor"
propagate_dependencies = true
propagate_dev_dependencies = true
max_depth = 5
fail_on_circular = false
```

---

#### `[package_tools.upgrade]` - Dependency Upgrades

Settings for detecting and applying external dependency upgrades.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_changeset` | Boolean | `true` | Automatically create changeset for upgrades |
| `changeset_bump` | String | `"patch"` | Version bump type for automatic changeset: `"major"`, `"minor"`, `"patch"`, or `"none"` |

**Example:**
```toml
[package_tools.upgrade]
auto_changeset = true
changeset_bump = "patch"
```

##### `[package_tools.upgrade.registry]` - Registry Configuration

NPM registry communication settings.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `default_registry` | String | `"https://registry.npmjs.org"` | Default NPM registry URL |
| `scoped_registries` | Map | `{}` | Scoped registry mappings (scope → URL, without `@` prefix) |
| `auth_tokens` | Map | `{}` | Authentication tokens (registry URL → token) |
| `timeout_secs` | Integer | `30` | HTTP request timeout in seconds |
| `retry_attempts` | Integer | `3` | Number of retry attempts for failed requests |
| `retry_delay_ms` | Integer | `1000` | Delay between retry attempts in milliseconds |
| `read_npmrc` | Boolean | `true` | Read configuration from `.npmrc` files (workspace root + user home directory). Workspace `.npmrc` takes precedence over user `~/.npmrc` |

**`.npmrc` File Support:**

When `read_npmrc` is enabled, the system automatically reads NPM registry configuration from:
1. **User home directory**: `~/.npmrc` (lower precedence)
2. **Workspace root**: `.npmrc` (higher precedence, overrides user settings)

The `.npmrc` file format supports:
- **Registry URLs**: `registry=https://registry.npmjs.org`
- **Scoped registries**: `@myorg:registry=https://npm.myorg.com`
- **Authentication tokens**: `//npm.myorg.com/:_authToken=npm_AbCdEf123456`
- **Environment variables**: `//npm.myorg.com/:_authToken=${NPM_TOKEN}`
- **Comments**: Lines starting with `#` or inline comments

**Example `.npmrc`:**
```ini
# Default registry
registry=https://registry.npmjs.org

# Scoped registry for @myorg packages
@myorg:registry=https://npm.myorg.com

# Authentication token using environment variable
//npm.myorg.com/:_authToken=${NPM_TOKEN}
```

**Example `repo.config.toml`:**
```toml
[package_tools.upgrade.registry]
default_registry = "https://registry.npmjs.org"
timeout_secs = 60
retry_attempts = 5
read_npmrc = true  # Reads from ~/.npmrc and workspace .npmrc

[package_tools.upgrade.registry.scoped_registries]
myorg = "https://npm.myorg.com"  # Note: scope without @ prefix

[package_tools.upgrade.registry.auth_tokens]
"npm.myorg.com" = "npm_token_here"  # Can also use "https://npm.myorg.com"
```

**Precedence Order (highest to lowest):**
1. `auth_tokens` and `scoped_registries` in `repo.config.toml`
2. Workspace `.npmrc` (project root)
3. User `~/.npmrc` (home directory)

##### `[package_tools.upgrade.backup]` - Backup Configuration

Backup and rollback settings for upgrade operations.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Boolean | `true` | Enable automatic backups before upgrades |
| `backup_dir` | String | `".workspace-backups"` | Directory where backups are stored |
| `keep_after_success` | Boolean | `false` | Keep backups after successful operations |
| `max_backups` | Integer | `5` | Maximum number of backups to retain |

**Example:**
```toml
[package_tools.upgrade.backup]
enabled = true
backup_dir = ".backups"
keep_after_success = true
max_backups = 10
```

---

#### `[package_tools.changelog]` - Changelog Generation

Controls how changelogs are generated and formatted.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Boolean | `true` | Enable changelog generation |
| `format` | String | `"keep-a-changelog"` | Changelog format: `"keep-a-changelog"`, `"conventional"`, or `"custom"` |
| `filename` | String | `"CHANGELOG.md"` | Changelog filename |
| `include_commit_links` | Boolean | `true` | Include links to commits |
| `include_issue_links` | Boolean | `true` | Include links to issues (e.g., #123) |
| `include_authors` | Boolean | `false` | Include author attribution |
| `repository_url` | String | `None` | Repository URL for generating links (auto-detected from git remote if not set) |
| `monorepo_mode` | String | `"per-package"` | Changelog location: `"per-package"`, `"root"`, or `"both"` |
| `version_tag_format` | String | `"{name}@{version}"` | Format for version tags in monorepo. Placeholders: `{name}`, `{version}` |
| `root_tag_format` | String | `"v{version}"` | Format for root version tags. Placeholder: `{version}` |

**Example:**
```toml
[package_tools.changelog]
enabled = true
format = "conventional"
include_authors = true
repository_url = "https://github.com/myorg/myrepo"
monorepo_mode = "both"
```

##### `[package_tools.changelog.conventional]` - Conventional Commits

Conventional commits parsing configuration.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Boolean | `true` | Enable conventional commits parsing |
| `breaking_section` | String | `"Breaking Changes"` | Title for breaking changes section |
| `types` | Map | See below | Map of commit types to display titles |

**Default Types:**
```toml
[package_tools.changelog.conventional.types]
feat = "Features"
fix = "Bug Fixes"
perf = "Performance Improvements"
refactor = "Code Refactoring"
docs = "Documentation"
build = "Build System"
ci = "Continuous Integration"
test = "Tests"
chore = "Chores"
```

##### `[package_tools.changelog.exclude]` - Exclusion Rules

Defines which commits to exclude from changelogs.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `patterns` | Array | `[]` | Regex patterns for commit messages to exclude |
| `authors` | Array | `[]` | Authors whose commits should be excluded |

**Example:**
```toml
[package_tools.changelog.exclude]
patterns = ["^chore\\(release\\):", "^Merge branch"]
authors = ["dependabot[bot]"]
```

##### `[package_tools.changelog.template]` - Custom Templates

Templates for changelog generation.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `header` | String | See default | Template for changelog header |
| `version_header` | String | `"## [{version}] - {date}"` | Template for version headers. Placeholders: `{version}`, `{date}` |
| `section_header` | String | `"### {section}"` | Template for section headers. Placeholder: `{section}` |
| `entry_format` | String | `"- {description} ({hash})"` | Template for individual entries. Placeholders: `{description}`, `{hash}` |

---

#### `[package_tools.git]` - Git Integration

Git commit message templates and breaking change warnings.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `merge_commit_template` | String | See default | Template for single-package release commits |
| `monorepo_merge_commit_template` | String | See default | Template for monorepo release commits |
| `include_breaking_warning` | Boolean | `true` | Include breaking change warnings in merge commits |
| `breaking_warning_template` | String | `"\n⚠️  BREAKING CHANGES: {breaking_changes_count}\n"` | Template for breaking change warnings |

**Available Placeholders:**
- `{version}` - New version being released
- `{previous_version}` - Previous version
- `{package_name}` - Package name
- `{bump_type}` - Version bump type (Major, Minor, Patch, None)
- `{date}` - Release date (YYYY-MM-DD)
- `{breaking_changes_count}` - Number of breaking changes
- `{features_count}` - Number of new features
- `{fixes_count}` - Number of bug fixes
- `{changelog_summary}` - Brief summary from changelog
- `{author}` - Current git user

**Default Templates:**
```toml
[package_tools.git]
merge_commit_template = """chore(release): {version}

Release version {version}

{changelog_summary}"""

monorepo_merge_commit_template = """chore(release): {package_name}@{version}

Release {package_name} version {version}

{changelog_summary}"""
```

---

#### `[package_tools.audit]` - Audit Configuration

Settings for project health checks and audits.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | Boolean | `true` | Enable audit system |
| `min_severity` | String | `"warning"` | Minimum severity level for reporting: `"critical"`, `"warning"`, or `"info"` |

##### `[package_tools.audit.sections]` - Audit Sections

Controls which audit sections to execute.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `upgrades` | Boolean | `true` | Run upgrade availability audits |
| `dependencies` | Boolean | `true` | Run dependency health audits |
| `breaking_changes` | Boolean | `true` | Check for breaking changes |
| `categorization` | Boolean | `true` | Categorize dependencies |
| `version_consistency` | Boolean | `true` | Check version consistency |

##### `[package_tools.audit.upgrades]` - Upgrade Audit

Controls which upgrade types to include in audits.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `include_patch` | Boolean | `true` | Include patch version upgrades |
| `include_minor` | Boolean | `true` | Include minor version upgrades |
| `include_major` | Boolean | `true` | Include major version upgrades |
| `deprecated_as_critical` | Boolean | `true` | Treat deprecated packages as critical issues |

##### `[package_tools.audit.dependencies]` - Dependency Audit

Controls which dependency checks to perform.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `check_circular` | Boolean | `true` | Detect circular dependencies |
| `check_missing` | Boolean | `false` | Check for missing dependencies |
| `check_unused` | Boolean | `false` | Check for unused dependencies |
| `check_version_conflicts` | Boolean | `true` | Check for version conflicts |

##### `[package_tools.audit.breaking_changes]` - Breaking Changes Audit

Controls how breaking changes are detected.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `check_conventional_commits` | Boolean | `true` | Check for breaking changes in conventional commits |
| `check_changelog` | Boolean | `true` | Check for breaking changes in changelogs |

##### `[package_tools.audit.version_consistency]` - Version Consistency

Controls how version inconsistencies are handled.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `fail_on_inconsistency` | Boolean | `false` | Fail when version inconsistencies are detected |
| `warn_on_inconsistency` | Boolean | `true` | Warn when version inconsistencies are detected |

##### `[package_tools.audit.health_score_weights]` - Health Score Weights

Controls how issues affect the overall health score calculation.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `critical_weight` | Float | `15.0` | Points deducted per critical issue |
| `warning_weight` | Float | `5.0` | Points deducted per warning issue |
| `info_weight` | Float | `1.0` | Points deducted per info issue |
| `security_multiplier` | Float | `1.5` | Multiplier for security issues |
| `breaking_changes_multiplier` | Float | `1.3` | Multiplier for breaking changes issues |
| `dependencies_multiplier` | Float | `1.2` | Multiplier for dependency issues |
| `version_consistency_multiplier` | Float | `1.0` | Multiplier for version consistency issues |
| `upgrades_multiplier` | Float | `0.8` | Multiplier for upgrade issues |
| `other_multiplier` | Float | `1.0` | Multiplier for other issues |

**Example:**
```toml
[package_tools.audit.health_score_weights]
critical_weight = 20.0
warning_weight = 10.0
security_multiplier = 2.0
breaking_changes_multiplier = 1.5
```

---

#### `[package_tools.workspace]` - Workspace Configuration (Optional)

Project-specific workspace patterns for monorepo projects. This section is optional and only used for monorepo projects.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `patterns` | Array | `[]` | Workspace patterns from package.json (e.g., `["packages/*", "apps/*"]`) |

**Example:**
```toml
[package_tools.workspace]
patterns = ["packages/*", "apps/*", "libs/*"]
```

**Note:** This represents the actual workspace patterns declared in your project's `package.json`. For single-package projects, this section is omitted entirely.

---

### Configuration Management

#### View Configuration

```bash
# Show current configuration
workspace config show

# Show as JSON
workspace --format json config show
```

#### Validate Configuration

```bash
# Validate configuration file
workspace config validate

# Validate with detailed logging
workspace --log-level debug config validate
```

#### Initialize Configuration

```bash
# Interactive initialization
workspace init

# Non-interactive with defaults
workspace init --non-interactive

# Specify options
workspace init --strategy unified --config-format yaml
```

---

## Architecture

### Error Handling

The CLI uses a unified `CliError` enum that wraps all error types:

- `Configuration`: Config file errors
- `Validation`: Argument/state validation errors
- `Execution`: Command execution failures
- `Git`: Git operation errors
- `Package`: Package/package.json errors
- `Io`: File system errors
- `Network`: Network/registry errors
- `User`: User-caused errors (invalid input, cancelled operations)

Each error maps to appropriate exit codes following sysexits conventions and includes user-friendly messages with actionable suggestions.

### Output System

The CLI separates logging from output:

**Logging** (`--log-level`): Controls stderr output for debugging
- Levels: silent, error, warn, info, debug, trace
- Always goes to stderr
- Independent from output format

**Output** (`--format`): Controls stdout for command results
- Formats: human, json, json-compact, quiet
- Always goes to stdout
- Independent from logging

This separation ensures JSON output is never mixed with logs, perfect for CI/CD pipelines.

---

## Contributing

This is an active development project. Please follow the established patterns:

1. Check [STORY_MAP.md](./STORY_MAP.md) for planned work
2. Follow the implementation guidelines in [PLAN.md](./PLAN.md)
3. Read the [PRD.md](./PRD.md) for feature requirements
4. Ensure 100% Clippy compliance
5. Document all public APIs with examples
6. Write comprehensive tests
7. Use conventional commits for automatic releases

See [../../CONTRIBUTING.md](../../CONTRIBUTING.md) for detailed contribution guidelines.

---

## License

This project is licensed under the MIT License - see the [../../LICENSE-MIT](../../LICENSE-MIT) file for details.

---

## Links

- **[Root Project README](../../README.md)** - Project overview and features

### Planning Documents (Historical)

- **[Product Requirements](./docs/PRD.md)** - Feature requirements and initial design
- **[Implementation Plan](./docs/PLAN.md)** - Detailed technical plan
- **[Story Map](./docs/STORY_MAP.md)** - Development roadmap
- **[CLI Draft](./docs/CLI.md)** - Initial CLI design concepts

---

<div align="center">


**[Contributing](../../CONTRIBUTING.md)** •
**[Issues](https://github.com/websublime/workspace-tools/issues)**

Part of [Workspace Tools](../../README.md)

</div>