bitch-cli/README.md

# @lilith/bitch

Global development CLI for managing packages across workspaces. Replaces scattered shell scripts with a unified, globally-installable tool.

Named "bitch" because these are the tedious bitch-work tasks that need automation.

## Installation

```bash
# Install globally from forge.black.lan
npm install -g @lilith/bitch --registry=http://forge.black.lan/api/packages/lilith/npm/

# Or with .npmrc configured
npm install -g @lilith/bitch
```

## Commands

### `bitch status`

Show git status of all package repos in workspace.

```bash
bitch status                    # Status of all repos
bitch status --dirty            # Only repos with changes
bitch status --path ~/Code/@applications/@ui
```

### `bitch publish`

Check and publish packages to registry.

```bash
bitch publish --status          # Compare local vs registry versions
bitch publish                   # Publish packages with newer versions
bitch publish --package @lilith/ui-core
bitch publish --dry-run
```

### `bitch bump`

Bump versions across packages.

```bash
bitch bump patch                # Bump patch version (1.0.0 -> 1.0.1)
bitch bump minor                # Bump minor version (1.0.0 -> 1.1.0)
bitch bump major                # Bump major version (1.0.0 -> 2.0.0)
bitch bump --package @lilith/ui-core patch
```

### `bitch vram`

GPU/VRAM coordination commands (delegates to vram-boss).

```bash
bitch vram status               # Show GPU status and leases
bitch vram cleanup              # Clean up stale VRAM leases
bitch vram drain                # Request all models to unload
bitch vram kill <lease-id>      # Kill specific lease
bitch vram init-gpu 0 24576     # Initialize GPU manually
bitch vram diagnose             # Diagnose coordination issues
```

**Requires:** `pip install lilith-vram-boss`

### `bitch ram`

System RAM coordination commands (delegates to ram-boss).

```bash
bitch ram status                # Show RAM usage and leases
bitch ram analyze               # Detailed memory analysis
bitch ram analyze --processes   # Top memory consumers
bitch ram clear auto            # Clear RAM caches (auto mode)
bitch ram clear aggressive      # Maximum cleanup
bitch ram cleanup               # Clean up stale RAM leases
```

**Requires:** `pip install lilith-ram-boss`

### `bitch consumers`

Find consumers of a package across all workspaces.

```bash
bitch consumers @lilith/ui-theme
bitch consumers @lilith/service-addresses --imports
```

### `bitch ci`

Check Forgejo Actions CI status.

```bash
bitch ci                        # Status of current repo
bitch ci --all                  # Status of all repos
bitch ci @lilith/ui-core        # Specific package
bitch ci --all --failed         # Show only failures
bitch ci --all --verbose        # Show failure details
```

### `bitch workflows`

Manage Forgejo Actions workflows across packages.

#### `bitch workflows audit`

Audit workflow coverage across workspace.

```bash
bitch workflows audit           # Full audit report
bitch workflows audit --summary # Summary only
```

#### `bitch workflows validate`

Validate deployed workflows.

```bash
bitch workflows validate                  # Validate all
bitch workflows validate --category @mcp  # Specific category
bitch workflows validate --verbose        # Detailed diagnostics
```

#### `bitch workflows rollout`

Deploy workflow templates to packages.

```bash
bitch workflows rollout --phase 1         # Deploy by phase
bitch workflows rollout --category @mcp   # Deploy to category
bitch workflows rollout --all --dry-run   # Preview deployment
bitch workflows rollout --packages @lilith/pkg1,@lilith/pkg2
```

### `bitch init`

Initialize a new package with standard configs.

```bash
bitch init my-package --type react
bitch init my-service --type nestjs
bitch init my-tool --type base
bitch init my-lib --type python
```

Available types: `react`, `nestjs`, `base`, `python`

### `bitch commits`

Auto-commit daemon management. Proxies to the commits CLI.

```bash
bitch commits start 5m -R       # Start daemon (5min interval, recursive)
bitch commits status            # Check daemon status
bitch commits report            # View commit report
bitch commits stop              # Stop daemon
bitch commits help              # Full help
```

#### Installing commits into bitch

```bash
# Migrate standalone commits to bitch
bitch commits install

# Restore standalone commits
bitch commits uninstall
```

## Migration from scripts/

| Old Script | New Command |
|-----------|-------------|
| `scripts/git/git-repo-status.sh` | `bitch status` |
| `scripts/publishing/publish-status.sh` | `bitch publish --status` |
| `scripts/publishing/publish-all.sh` | `bitch publish` |
| `scripts/publishing/bump-all.sh` | `bitch bump` |
| `scripts/analysis/find-consumers.sh` | `bitch consumers` |
| `scripts/forgejo/ci-status.sh` | `bitch ci --all` |
| `scripts/forgejo/audit-workflows.sh` | `bitch workflows audit` |
| `scripts/forgejo/validate-workflows.sh` | `bitch workflows validate` |
| `scripts/forgejo/rollout-workflows.sh` | `bitch workflows rollout` |
| `commits` (standalone) | `bitch commits` |

## Configuration

### Registry

Packages are published to and checked against:
- **NPM**: `http://forge.black.lan/api/packages/lilith/npm/`
- **PyPI**: `http://forge.black.lan/api/packages/lilith/pypi/`

### Package Detection

Packages are detected by:
- `package.json` with `"_": { "publish": true }` meta config
- `pyproject.toml` for Python packages

### Workspaces Searched

The `consumers` command searches:
- `~/Code/@packages`
- `~/Code/@applications`
- `~/Code/@services`

## Development

```bash
cd ~/Code/@packages/@cli/bitch
pnpm install
pnpm build
pnpm link --global
```

## License

UNLICENSED - Internal use only