/sync-contracts

/sync-contracts

> Lightweight incremental update of workspace contracts without full re-analysis.

Purpose

Fast contract synchronization that:

• Checks only contract source files (not full workspace)
• Updates CONTRACTS.md with changes
• Validates consistency
• Takes ~15 seconds instead of ~2 minutes

When to Use

| Scenario | Command | |----------|---------| | After modifying API endpoints | `/sync-contracts` | | After changing shared types | `/sync-contracts` | | Session start shows stale contracts | `/sync-contracts` | | Post-commit hook (automatic) | `/sync-contracts --lightweight` | | Before pushing changes | `/sync-contracts --validate` | | See what changed without updating | `/sync-contracts --diff` |

Behavior

Step 1: Load Existing Topology

🔄 Loading workspace context...

Workspace: myapp (Monorepo)
Last full analysis: 2026-01-18T10:00:00Z
Last sync: 2026-01-20T14:32:00Z

Does NOT re-discover workspace structure - uses existing TOPOLOGY.md.

Step 2: Check Contract Sources

📋 Checking contract sources...

Monitored files (from .contract-sources):
  ✓ apps/api/openapi.json (modified 2h ago)
  ✓ packages/shared-types/src/index.ts (modified 2h ago)
  ○ packages/db/schema/campaigns.ts (unchanged)
  ○ packages/db/schema/users.ts (unchanged)
  ○ apps/api/app/schemas/campaign.py (unchanged)

Changes detected: 2 files

Step 3: Extract Changes

📝 Extracting contract changes...

apps/api/openapi.json:
  + POST /api/campaigns/bulk (new endpoint)
  ~ GET /api/campaigns (added 'status' query param)

packages/shared-types/src/index.ts:
  ~ Campaign interface (added 'tags: string[]' field)
  + CampaignBulkCreate interface (new)

Step 4: Update Artifacts

✏️  Updating workspace artifacts...

Updated: _project_specs/workspace/CONTRACTS.md
  - Added POST /api/campaigns/bulk to endpoints
  - Updated Campaign type definition
  - Added CampaignBulkCreate type

Updated: _project_specs/workspace/CROSS_REPO_INDEX.md
  - Added bulk create capability

Timestamps updated:
  Last sync: 2026-01-20T16:45:00Z

Step 5: Validate Consistency

✅ Validating contract consistency...

Checks:
  ✓ OpenAPI endpoint count matches routes (48/48)
  ✓ All Pydantic models have TypeScript equivalents
  ✓ No orphaned types in shared-types
  ⚠️  Frontend types may need regeneration

Validation: PASSED (1 warning)

Final Output

════════════════════════════════════════════════════════════════
  CONTRACT SYNC COMPLETE
════════════════════════════════════════════════════════════════

Sources checked: 5
Changes detected: 2
Files updated: 2

Changes Summary:
  + POST /api/campaigns/bulk (new endpoint)
  ~ Campaign interface (added 'tags' field)
  + CampaignBulkCreate interface (new)

Freshness: 🟢 Fresh
Last sync: 2026-01-20T16:45:00Z

⚠️  Note: Frontend types may need regeneration
   Run: cd apps/web && npm run generate:types

════════════════════════════════════════════════════════════════

Flags

| Flag | Description | |------|-------------| | `--lightweight` | Skip validation, minimal output (for hooks) | | `--diff` | Show changes without updating files | | `--validate` | Only validate, don't update | | `--force` | Update even if no changes detected | | `--verbose` | Show detailed extraction output |

Diff Mode

Preview changes without applying:

/sync-contracts --diff

Output:

📋 Contract Changes (not applied)

apps/api/openapi.json:
  + POST /api/campaigns/bulk
    Request: CampaignBulkCreate[]
    Response: Campaign[]

  ~ GET /api/campaigns
    + query param: status (string, optional)

packages/shared-types/src/index.ts:
  ~ interface Campaign {
      id: string;
      name: string;
  +   tags: string[];        // NEW
      status: CampaignStatus;
    }

  + interface CampaignBulkCreate {
      campaigns: CampaignCreate[];
    }

To apply these changes: /sync-contracts

Validate Mode

Check consistency without updating:

/sync-contracts --validate

Output:

🔍 Contract Validation

Endpoint Consistency:
  ✓ OpenAPI spec: 48 endpoints
  ✓ Route files: 48 handlers
  ✓ Match: YES

Type Consistency:
  ✓ Pydantic models: 23
  ✓ TypeScript types: 34
  ✓ Shared types exported: 34
  ⚠️  2 types only in backend (internal)

Cross-Module References:
  ✓ Frontend imports valid types: YES
  ✓ Backend codegen up to date: YES

Overall: ✅ VALID (2 warnings)

Lightweight Mode

For hooks - minimal output, fast execution:

/sync-contracts --lightweight

Output:

✓ Contracts synced (2 changes)

Or if no changes:

✓ Contracts up to date

Contract Sources File

The sync uses `.contract-sources` to know what to check:

# _project_specs/workspace/.contract-sources
# Auto-generated by /analyze-workspace
# Edit to add/remove monitored files

# OpenAPI specs
apps/api/openapi.json

# Type definitions
packages/shared-types/src/index.ts
packages/shared-types/src/api.ts
packages/shared-types/src/campaign.ts

# Pydantic schemas (Python)
apps/api/app/schemas/campaign.py
apps/api/app/schemas/user.py
apps/api/app/schemas/auth.py

# Database schema
packages/db/schema/campaigns.ts
packages/db/schema/users.ts

To add a new source:

echo "apps/api/app/schemas/new_model.py" >> _project_specs/workspace/.contract-sources

Error Handling

No Contract Sources

⚠️  No contract sources configured

Run /analyze-workspace first to set up contract monitoring.

Source File Missing

⚠️  Contract source not found: apps/api/openapi.json

Options:
  1. Generate it: cd apps/api && python -m app.generate_openapi
  2. Remove from monitoring: Edit .contract-sources
  3. Skip this file: /sync-contracts --skip apps/api/openapi.json

Validation Failed

❌ Contract validation failed

Issues found:
  1. OpenAPI has 48 endpoints, routes have 47
     Missing: DELETE /api/campaigns/:id (in spec, not in routes)

  2. Type mismatch: Campaign.status
     OpenAPI: "dra