# @packages Workspace Scripts

> **DEPRECATED**: Most functionality has been migrated to `@lilith/bitch`, a globally-installable CLI.
>
> Install: `npm install -g @lilith/bitch --registry=http://forge.black.lan/api/packages/lilith/npm/`
>
> See [Migration Table](#migration-to-bitch) below.

Automation tooling for the `@packages` pnpm monorepo workspace.

## Directory Structure

```
scripts/
├── publishing/     # Package version bumping and publishing
├── git/            # Git repository operations
├── config/         # Package configuration utilities
├── lint/           # ESLint and code quality scripts
├── forgejo/        # Forgejo CI/CD automation (primary)
├── gitlab/         # DEPRECATED - Legacy GitLab scripts
├── migration/      # One-time migration utilities
├── templates/      # CI/CD template files
├── analysis/       # Codebase analysis scripts
└── oneoffs/        # One-time scripts (not categorized)
```

## Quick Reference

### Publishing Workflow

```bash
# Check which packages need publishing
./publishing/publish-status.sh

# Bump all package versions
./publishing/bump-all.sh patch   # 1.0.0 → 1.0.1
./publishing/bump-all.sh minor   # 1.0.0 → 1.1.0
./publishing/bump-all.sh major   # 1.0.0 → 2.0.0

# Publish all packages
./publishing/publish-all.sh

# Publish single package (standard)
./publishing/publish-package.sh @category/package-name

# Publish with wrapper script (standard)
cd ~/Code/@packages/@category/package-name
../../../scripts/publishing/publish-with-cache-clear.sh              # Wait 1 minute for auto-refresh

# Publish with immediate cache clearing (optional)
../../../scripts/publishing/publish-with-cache-clear.sh --clear-cache  # Immediate availability

# Or with npm publish arguments
../../../scripts/publishing/publish-with-cache-clear.sh --clear-cache --tag beta
../../../scripts/publishing/publish-with-cache-clear.sh --dry-run
```

**Cache Management**: Verdaccio auto-refreshes @lilith packages every **1 minute**. Cache clearing is **opt-in** via `--clear-cache` flag - only use when you need immediate (< 1 minute) availability.

### Git Operations

```bash
# Check git status across all packages
./git/git-repo-status.sh

# Push all package repos
./git/git-push-all.sh

# Commit all dirty repos
./git/commit-all-dirty.sh "commit message"
```

### Configuration

```bash
# Configure a new package
./config/init-package-config.sh @category/package-name

# Add unified configs dependency
./config/add-configs-dep.mjs

# Convert standalone package to workspace member
./config/convert-to-workspace.sh
```

### Linting

```bash
# Fix ESLint config issues across workspace
./lint/fix-eslint-configs.sh

# Get lint errors for all packages
./lint/get-lint-errors.sh

# Fix all auto-fixable issues
./lint/fix-all-issues.sh

# Generate lint fix report
./lint/lint-fix-report.sh
```

### Forgejo CI/CD

```bash
# Audit workflow status
./forgejo/audit-workflows.sh --summary

# Deploy workflows
./forgejo/rollout-workflows.sh --phase 1

# Validate workflows
./forgejo/validate-workflows.sh --verbose

# Check CI status
./forgejo/ci-status.sh
```

See `forgejo/README.md` for detailed Forgejo Actions documentation.

### Analysis

```bash
# Find consumers of a package
./analysis/find-consumers.sh @lilith/package-name

# Create final report
./analysis/create-final-report.sh
```

## Categories

### publishing/
Package version management and registry publishing.

| Script | Purpose |
|--------|---------|
| `bump-all.sh` | Bump versions across all packages |
| `publish-all.sh` | Publish all packages to registry |
| `publish-package.sh` | Publish single package |
| `publish-status.sh` | Check publish status |

### git/
Git repository operations for multi-repo management.

| Script | Purpose |
|--------|---------|
| `git-push-all.sh` | Push all package repos |
| `git-repo-status.sh` | Check git status across repos |
| `push-all-repos.sh` | Push all repos (alternative) |
| `commit-all-dirty.sh` | Commit changes in dirty repos |

### config/
Package configuration and setup utilities.

| Script | Purpose |
|--------|---------|
| `configure-packages.sh` | Bulk package configuration |
| `init-package-config.sh` | Initialize package config |
| `convert-to-workspace.sh` | Convert to workspace member |
| `add-configs-dep.mjs` | Add @configs dependencies |

### lint/
ESLint configuration and code quality.

| Script | Purpose |
|--------|---------|
| `fix-eslint-configs.sh` | Fix ESLint config issues |
| `fix-all-issues.sh` | Fix all auto-fixable issues |
| `fix-unused-vars.sh` | Fix unused variable warnings |
| `get-lint-errors.sh` | List all lint errors |
| `lint-fix-report.sh` | Generate lint fix report |
| `verify-eslint-usage.sh` | Verify ESLint usage |

### forgejo/
Forgejo Actions CI/CD automation. **Primary CI/CD tooling.**

See `forgejo/README.md` for full documentation.

### gitlab/
**DEPRECATED** - Legacy GitLab CI/CD scripts. See `gitlab/DEPRECATED.md`.

### migration/
One-time migration utilities.

| Script | Purpose |
|--------|---------|
| `migrate-to-unified-configs.mjs` | Migrate to unified configs |
| `setup-repos.sh` | Initial repo setup |
| `setup-gitlab-npm.sh` | GitLab npm registry setup |

### templates/
CI/CD template files.

| Template | Purpose |
|----------|---------|
| `gitlab-ci-no-build.yml` | GitLab CI without build |
| `gitlab-ci-turbo.yml` | GitLab CI with Turbo |
| `gitlab-ci-with-build.yml` | GitLab CI with build |

### analysis/
Codebase analysis and reporting.

| Script | Purpose |
|--------|---------|
| `find-consumers.sh` | Find package consumers |
| `create-final-report.sh` | Generate analysis report |

### oneoffs/
One-time scripts not worth categorizing.

## Migration to bitch

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

Install bitch globally:

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

**Scripts NOT migrated** (too specific to @packages or one-time use):
- `forgejo/rollout-workflows.sh` - CI template deployment
- `forgejo/audit-workflows.sh` - Workflow verification
- `migration/*` - One-time migration utilities

## Registry

**Forgejo**: `http://forge.black.lan/lilith/packages-scripts`

---

**Maintained by**: The Collective