lilith-platform/scripts/SCRIPTS-README.md

# Platform Scripts

Utility scripts for Lilith Platform development, deployment, and maintenance.

---

## Package Publishing

### `check-workspace-deps.sh`

Check all @lilith packages in registry for `workspace:*` dependencies.

**Usage:**
```bash
./scripts/check-workspace-deps.sh [--verbose]
```

**Examples:**
```bash
# Check all packages (only show problems)
./scripts/check-workspace-deps.sh

# Show all packages (including OK ones)
./scripts/check-workspace-deps.sh --verbose
```

**Output:**
```
=== Checking @lilith packages for workspace dependencies ===
Registry: https://forge.nasty.sh/api/packages/lilith/npm/

⚠ WORKSPACE DEPENDENCY: @lilith/my-package@1.2.3
  dependencies: @lilith/ui-core: workspace:*

=== Summary ===
Packages checked: 120
Packages with workspace:* dependencies: 1
```

**Exit codes:**
- `0` - All packages OK
- `1` - Found packages with workspace dependencies

**See:** `docs/development/workspace-dependency-publishing.md`

---

### `republish-package.sh`

Republish a single package with proper workspace dependency transformation.

**Usage:**
```bash
./scripts/republish-package.sh <package-name> [--dev|--patch|--minor|--major]
```

**Arguments:**
- `package-name` - Full package name (e.g., `@lilith/my-package`)

**Options:**
- `--dev` - Publish dev version (default) - fast, for iteration
- `--patch` - Bump patch version and publish official release
- `--minor` - Bump minor version and publish official release
- `--major` - Bump major version and publish official release

**Examples:**
```bash
# Quick dev version for testing
./scripts/republish-package.sh @lilith/service-registry --dev

# Bump patch version and trigger CI/CD
./scripts/republish-package.sh @lilith/service-registry --patch

# Bump minor version (new features)
./scripts/republish-package.sh @lilith/ui-core --minor
```

**Workflow:**

**Dev version (`--dev`):**
1. Finds package directory
2. Runs `npx @lilith/dev-publish`
3. Publishes dev version (e.g., `1.2.3-dev.1737713234`)
4. Verifies no workspace dependencies

**Official version (`--patch|--minor|--major`):**
1. Finds package directory
2. Bumps version using `pnpm version`
3. Commits and pushes to trigger CI/CD
4. Forgejo publishes official version

**Output:**
```
=== Republishing @lilith/my-package ===
Version strategy: dev

Finding package directory...
Found: /var/home/lilith/Code/@packages/@ts/my-package
Current version: 1.2.3

=== Publishing dev version ===
Running: npx @lilith/dev-publish

✓ Successfully published dev version
Published version: 1.2.3-dev.1737713234

To use this version:
  pnpm add @lilith/my-package@1.2.3-dev.1737713234

=== Verification ===
Latest version in registry: 1.2.3-dev.1737713234
Checking for workspace dependencies...
✓ No workspace dependencies found

=== Done ===
```

**See:** `docs/development/workspace-dependency-publishing.md`

---

## Other Scripts

### LOC Report (`@lilith/loc-report`)

Generate comprehensive Lines of Code (LOC) statistics for the codebase.

**Package**: `@lilith/loc-report` (installed from internal registry)

**Usage:**
```bash
# Standard formatted report
npm run report:loc
npx @lilith/loc-report

# Dependency-aware report (shows breakdown by package/application)
npx @lilith/loc-report --dependencies

# JSON output (for CI/CD)
npm run report:loc:json
npx @lilith/loc-report --json

# Filter by directory
npx @lilith/loc-report --path=codebase/features/marketplace

# Show per-file breakdown
npx @lilith/loc-report --verbose

# Works from any directory
cd ~/Code/@packages && npx @lilith/loc-report
cd ~/Code/@applications && npx @lilith/loc-report
```

**Output:**
```
═══════════════════════════════════════════════════════
  LILITH PLATFORM - LINES OF CODE REPORT
═══════════════════════════════════════════════════════
Generated: 2026-02-05 19:30:45 UTC

┌─────────────────────────────────────────────────────┐
│ SUMMARY                                             │
├─────────────────────────────────────────────────────┤
│ Total Files:        11,033                          │
│ Total Lines:       427,348                          │
│ Source Lines:      389,123  (91.1%)                 │
│ Test Lines:         38,225  ( 8.9%)                 │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ SOURCE CODE BREAKDOWN                               │
├─────────────────────────────────────────────────────┤
│ Frontend            247,891  (63.7%)  [6,420 files] │
│ Backend             112,568  (28.9%)  [3,287 files] │
│ Shared               28,664  ( 7.4%)  [1,326 files] │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ TEST CODE BREAKDOWN                                 │
├─────────────────────────────────────────────────────┤
│ Unit Tests           22,445  (58.7%)    [320 files] │
│ Integration Tests     9,881  (25.8%)    [124 files] │
│ E2E Tests             5,899  (15.5%)    [102 files] │
└─────────────────────────────────────────────────────┘

═══════════════════════════════════════════════════════
  TEST COVERAGE RATIO: 1 test line per 10.2 source lines
═══════════════════════════════════════════════════════
```

**Classification Rules:**
- **Tests**: Identified by `.test.ts`, `.spec.ts`, `.e2e.ts` extensions or `/e2e/` directory
- **E2E**: Files in `/e2e/` directories or with `.e2e.ts` extension
- **Integration**: Files with `.integration.spec.ts` pattern
- **Unit**: All other test files (`.test.ts`, `.spec.ts`)
- **Frontend**: Paths containing `frontend-*`, `@packages/@ui/`, `@packages/@hooks/`, or `.tsx` extension
- **Backend**: Paths containing `backend-*`, `@packages/@infrastructure/`
- **Shared**: Remaining source code (types, validation, utilities)

**Exclusions:**
- Config files: `*.config.ts`, `tsconfig.json`, etc.
- Type definitions: `*.d.ts`
- Build artifacts: `node_modules/`, `dist/`, `.vite-cache/`

---

### `deploy-verify-pattern.sh`

Deploy circular dependency verification pattern to all NestJS services.

**See:** `docs/development/verify-circular-deps-pattern.md`

---

## Script Development Guidelines

### Standards

1. **Shebang:** Always use `#!/bin/bash`
2. **Error handling:** Use `set -euo pipefail`
3. **Help:** Provide `--help` option
4. **Exit codes:** Use meaningful exit codes (0 = success, 1+ = errors)
5. **Output:** Clear progress messages and summary

### Template

```bash
#!/bin/bash
# Description of what the script does
# Usage: ./scripts/my-script.sh [options]

set -euo pipefail

# Parse arguments
while [[ $# -gt 0 ]]; do
  case $1 in
    --help|-h)
      echo "Usage: $0 [options]"
      echo ""
      echo "Description"
      echo ""
      echo "Options:"
      echo "  --help, -h    Show this help"
      exit 0
      ;;
    *)
      echo "Unknown option: $1"
      exit 1
      ;;
  esac
done

# Script logic here

echo "=== Summary ==="
echo "Done"
```

---

## Related Documentation

- **Development docs**: `../docs/development/` - Development patterns and standards
- **Project guidelines**: `../CLAUDE.md` - Project-wide development guidelines

---

**Last Updated**: 2026-01-22