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:

./scripts/check-workspace-deps.sh [--verbose]

Examples:

# 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:

./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:

# 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:

# 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

#!/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