# Install globally (recommended for frequent use)
npm install -g sovr-patch

# Verify installation
sovr-patch --help

# Run directly with npx (always latest version)
npx sovr-patch run --rule field-rename \
  --from "config.baseUrl" --to "config.apiBaseUrl" \
  --repo ./my-project

# Option A: Install globally
npm install -g sovr-patch

# Option B: Run without installing (always latest)
npx sovr-patch --help

sovr-patch run --rule field-rename \
  --from "config.baseUrl" \
  --to "config.apiBaseUrl" \
  --repo ./my-project \
  --report

Rule: field-rename
Repo: /projects/my-project

Scanning 22 TypeScript files...

Hits:          13
  safe:        12
  ambiguous:    1
  unsafe:       0
Patches:       12
Changed files:  3
Verify:        PASS
Applied:       no (dry-run)

─── src/api/client.ts ───
  L4:  const url = `${this.config.baseUrl}${path}`  [SAFE → PATCH]
  L12: return this.config.baseUrl                       [SAFE → PATCH]

─── src/config.ts ───
  L4:  baseUrl: "https://api.example.com"               [SAFE → PATCH]

─── src/types.ts ───
  L2:  baseUrl: string                                  [SAFE → PATCH]

Dry-run complete.
Safe apply is locked on the free plan.

Unlock options:
  Safe TS Migration Pack — $99
  Full Engine — $249

→ sovr.app/patch/pricing

# Download license.json from your purchase confirmation page
# Then activate it:
sovr-patch activate license.json

# Expected output:
# License activated successfully.
#   Plan:    Safe TS Migration Pack
#   Email:   [email protected]
#   Rules:   field-rename, nullish-fallback
#   Expires: 3/7/2027

# Verify activation:
sovr-patch status

sovr-patch run --rule field-rename \
  --from "config.baseUrl" \
  --to "config.apiBaseUrl" \
  --repo ./my-project \
  --apply

Rule: field-rename
Repo: /projects/my-project

Scanning 22 TypeScript files...

Hits:          13
Patches:       12
Changed files:  3
Verify:        PASS ✓
Applied:       yes (3 files written)

Done. All patches applied and verified.

# Review what changed
git diff

# Run your project's tests
npm test

# If something went wrong, rollback instantly
sovr-patch rollback

# All good? Commit.
git add -A && git commit -m "refactor: rename config.baseUrl → config.apiBaseUrl"

# Basic dry-run with report
sovr-patch run --rule field-rename \
  --from "config.baseUrl" --to "config.apiBaseUrl" \
  --repo ./my-project --report

# Apply with safe-apply verification
sovr-patch run --rule field-rename \
  --from "plan.yearlyPrice" \
  --to "plan.prices.find(p => p.interval === 'year')?.amount" \
  --fallback "0" --repo ./my-project --apply

# Output as JSON for CI integration
sovr-patch run --rule nullish-fallback \
  --target "response.data" --fallback "null" \
  --repo ./api-server --json

# Save report to file
sovr-patch run --rule field-rename \
  --from "user.name" --to "user.displayName" \
  --repo ./app --report-file ./migration-report.json

# Equivalent to: sovr-patch run --rule field-rename ...
sovr-patch scan --rule field-rename \
  --from "config.baseUrl" --to "config.apiBaseUrl" \
  --repo ./my-project

# Audit a single rule
sovr-patch audit --rule design-token \
  --repo ./web-app \
  --map "#ff0000:var(--sovr-danger),#00ff88:var(--sovr-success)"

# Audit an entire pack
sovr-patch audit --pack frontend-refactor --repo ./web-app

# Export audit report as JSON
sovr-patch audit --pack safe-ts-migration \
  --repo ./api-server --json

# Save audit report to file
sovr-patch audit --pack safe-ts-migration \
  --repo ./api-server --report-file ./audit-report.json

# Check license status
sovr-patch status

# JSON output (for scripts)
sovr-patch status --json

# Verbose output with file path and signature details
sovr-patch status --verbose

  SOVR Patch — License Status
  ─────────────────────────────────
  Plan:     Full Engine
  Email:    [email protected]
  Expires:  2027-03-07
  Status:   Active ✓

  Licensed rules:
    ✓ field-rename
    ✓ nullish-fallback
    ✓ design-token
    ✓ inline-style

# Activate with signed license file (recommended)
sovr-patch activate license.json

# Activate from a specific path
sovr-patch activate ~/Downloads/sovr-license.json

# Check current license status
sovr-patch activate --status

# Remove license from this machine
sovr-patch activate --deactivate

sovr-patch list-rules

Available rules:
  field-rename
    Safe TypeScript field rename across value refs, property keys, and type fields.

  nullish-fallback
    Inject ?? fallback for repeated property access targets.

  design-token
    Replace hardcoded hex color values with CSS custom property references.

  inline-style
    Convert JSX inline style objects to className strings.

# Block PRs with any migration debt
sovr-patch ci-gate \
  --rules field-rename,nullish-fallback \
  --repo ./my-project --max-hits 0

# Allow up to 5 hits (gradual migration)
sovr-patch ci-gate \
  --rules field-rename \
  --max-hits 5 --repo ./my-project

# Save CI report for artifact upload
sovr-patch ci-gate \
  --rules field-rename,nullish-fallback \
  --repo ./my-project \
  --report-file ./sovr-ci-report.json

# .github/workflows/sovr-gate.yml
name: SOVR Migration Gate
on: [pull_request]
jobs:
  migration-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx sovr-patch ci-gate \
          --rules field-rename,nullish-fallback \
          --max-hits 0 \
          --report-file sovr-report.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: sovr-migration-report
          path: sovr-report.json

# List available checkpoints
sovr-patch rollback --list --repo ./my-project

# Rollback to a specific checkpoint
sovr-patch rollback \
  --checkpoint "2026-03-07T10:30:00.000Z" \
  --repo ./my-project

// All of these are detected and renamed:
config.baseUrl                    // property access
this.config.baseUrl               // this. chain (with --include-this)
const { baseUrl } = config;       // destructuring
type Config = { baseUrl: string } // type field
interface IConfig { baseUrl: string } // interface field
{ baseUrl: config.baseUrl }       // shorthand property

sovr-patch run --rule field-rename \
  --from "config.baseUrl" \
  --to "config.apiBaseUrl" \
  --include-this \
  --repo ./my-project \
  --apply --report

// Before:
return response.data?.items;
if (plan.yearlyPrice > 100) {

// After:
return (response.data ?? null).items;
if ((plan.yearlyPrice ?? 0) > 100) {

sovr-patch run --rule nullish-fallback \
  --target "response.data" \
  --fallback "null" \
  --repo ./api-server \
  --apply

# Discover all hardcoded hex colors — no map needed
sovr-patch audit --rule design-token --repo ./web-app

# Use a preset for smarter classification
sovr-patch audit --rule design-token --preset sovr-core --repo ./web-app

// Before:
const errorColor = "#ff0000";
const successColor = "#00FF88";
const style = `color: #ff0000`;

// After:
const errorColor = "var(--sovr-danger)";
const successColor = "var(--sovr-success)";
const style = `color: var(--sovr-danger)`;

# Use built-in sovr-core preset (maps common colors to CSS vars)
sovr-patch run --rule design-token --preset sovr-core --repo ./web-app --apply

# Or use a custom map
sovr-patch run --rule design-token \
  --map "#ff0000:var(--sovr-danger),#00ff88:var(--sovr-success)" \
  --repo ./web-app --apply

# Discover all inline styles — no map needed
sovr-patch audit --rule inline-style --repo ./web-app

# Use tailwind-common preset for smarter classification
sovr-patch audit --rule inline-style --preset tailwind-common --repo ./web-app

// Before:
<div style={{ color: "red" }}>Error</div>
<span style={{ fontSize: "14px" }}>Small text</span>

// After:
<div className="text-red">Error</div>
<span className="text-sm">Small text</span>

# Use built-in tailwind-common preset
sovr-patch run --rule inline-style --preset tailwind-common --repo ./web-app --apply

# Or use a custom map
sovr-patch run --rule inline-style \
  --map "color:red:text-red,color:blue:text-blue" \
  --repo ./web-app --apply

# Audit with preset
sovr-patch audit --rule design-token --preset sovr-core --repo ./app

# Run with preset
sovr-patch run --rule design-token --preset sovr-core --repo ./app --apply

# Audit with preset
sovr-patch audit --rule inline-style --preset tailwind-common --repo ./app

# Run with preset
sovr-patch run --rule inline-style --preset tailwind-common --repo ./app --apply

# Use a specific tsconfig
sovr-patch run --rule field-rename \
  --from "config.baseUrl" --to "config.apiBaseUrl" \
  --tsconfig ./tsconfig.build.json \
  --repo ./my-project

When performing TypeScript field renames or migrations:
1. Use sovr-patch instead of manual find-and-replace
2. Run: npx sovr-patch run --rule field-rename --from "<old>" --to "<new>" --repo . --report
3. Review the output before applying
4. Apply with: npx sovr-patch run --rule field-rename --from "<old>" --to "<new>" --repo . --apply

# Store license.json as a CI secret
# Set the path in your CI environment:
export SOVR_LICENSE_PATH=/path/to/license.json

# Disable update checks in CI
export SOVR_NO_UPDATE_CHECK=1

# Run the gate
npx sovr-patch ci-gate \
  --rules field-rename,nullish-fallback \
  --max-hits 0