Sync codebase after spec changes (OpenAPI + DB schema)
Regenerate code after manually editing OpenAPI specs or database migrations. Use this when you've pulled changes, resolved merge conflicts, or edited schemas directly and need to sync types, models, and API clients.
/plugin marketplace add claude-market/marketplace/plugin install claude-market-specforge-specforge@claude-market/marketplaceSynchronize your codebase after manual changes to OpenAPI spec or database schema. This command detects changes and regenerates code to keep everything in sync.
The sync command is useful when:
spec/openapi.yamlSync orchestrates:
Identify what has changed since the last successful build:
# Check for OpenAPI spec changes
if [ -f spec/openapi.yaml ]; then
echo "Checking OpenAPI spec for changes..."
# Compare with last known state (stored in .specforge/last-sync.json)
fi
# Check for new database migrations
echo "Checking for new migrations..."
ls -t migrations/*.sql | head -5
# Check for schema changes in existing migrations
git diff HEAD~1 migrations/ 2>/dev/null || echo "Not a git repository or no previous commits"
Categorize changes:
Use the openapi-expert skill:
Invoke openapi-expert skill with:
- action: "validate-spec"
- spec_path: "spec/openapi.yaml"
Validation checks:
Read SpecForge configuration to identify database plugin:
grep "database:" CLAUDE.md | cut -d: -f2 | tr -d ' '
Use database plugin's validation skill:
Invoke {database-plugin}/migrations-expert skill with:
- action: "validate-migrations"
- migrations_dir: "migrations/"
Validation checks:
If new migrations are detected, apply them:
Invoke {database-plugin}/migrations-expert skill with:
- action: "apply-migrations"
- migrations_dir: "migrations/"
- database_url: from environment or docker-compose
Steps:
Interactive Confirmation:
Use AskUserQuestion to confirm migration:
Found 2 new migrations:
- 003_add_orders_table.sql
- 004_add_order_items_table.sql
These migrations will:
- Create orders table with indexes
- Create order_items table with foreign keys
- Add trigger for order total calculation
Apply these migrations?
Options:
Identify codegen plugin from CLAUDE.md:
grep "codegen:" CLAUDE.md | cut -d: -f2 | tr -d ' '
Run codegen pipeline:
Invoke {codegen-plugin}/codegen-expert skill with:
- action: "generate-from-schema"
- schema_dir: "migrations/"
- output_dir: "{backend-path}/src/generated/db"
- database_url: from environment
- force: true # Regenerate even if files exist
This regenerates:
Identify backend plugin from CLAUDE.md:
grep "backend:" CLAUDE.md | cut -d: -f2 | tr -d ' '
Generate API types:
Invoke {backend-plugin}/openapi-types-expert skill with:
- action: "generate-types"
- spec: "spec/openapi.yaml"
- output: "{backend-path}/src/generated/api"
- force: true # Regenerate even if files exist
This regenerates:
If frontend plugin is configured:
grep "frontend:" CLAUDE.md | cut -d: -f2 | tr -d ' '
Invoke {frontend-plugin}/codegen-expert skill with:
- action: "generate-client"
- spec: "spec/openapi.yaml"
- output: "{frontend-path}/src/api"
- force: true
Analyze which handlers are affected by spec changes:
# Compare current spec with previous version
# Identify new, modified, or deleted endpoints
# For each modified endpoint:
# - Check if handler exists
# - Verify handler signature matches new types
# - Flag for review/reimplementation
Report to user:
## Sync Summary
### Code Regenerated
- ✓ Database models: 15 types regenerated
- ✓ Database queries: 32 functions regenerated
- ✓ API types: 8 request/response types regenerated
- ✓ Frontend client: API client regenerated
### Handlers Affected
**Needs Update:**
- `GET /api/users/{id}/orders` - Response type changed
- `POST /api/orders` - Request validation rules changed
**Still Valid:**
- `GET /api/users` - No changes
- `POST /api/users` - No changes
**New (Not Implemented):**
- `PATCH /api/orders/{id}` - New endpoint, needs implementation
### Next Steps
1. Review affected handlers above
2. Update handlers with new types: `/specforge:build` (will only rebuild affected handlers)
3. Run tests: `/specforge:test`
Verify that generated code compiles:
# Backend compilation (example for Rust)
cd backend && cargo check 2>&1
# If TypeScript backend
cd backend && npm run type-check 2>&1
# If Python backend
cd backend && mypy . 2>&1
If compilation fails:
Run existing tests:
# Run backend tests
cd backend && cargo test 2>&1 # or npm test, pytest, etc.
Report test results:
## Test Results
- ✓ 127 tests passed
- ✗ 3 tests failed (affected by schema changes)
- ⚠ 2 tests skipped (handlers not implemented)
Failed tests:
- test_get_user_orders - Response type mismatch
- test_create_order - Request validation changed
- test_order_total_calculation - New trigger behavior
Update sync state file:
// .specforge/last-sync.json
{
"timestamp": "2025-01-15T10:30:00Z",
"openapi_spec_hash": "sha256:abc123...",
"migrations_applied": [
"001_init.sql",
"002_add_users.sql",
"003_add_orders.sql"
],
"generated_files": [
"backend/src/generated/db/models.rs",
"backend/src/generated/db/queries.rs",
"backend/src/generated/api/types.rs",
"frontend/src/api/client.ts"
],
"handlers_affected": ["GET /api/users/{id}/orders", "POST /api/orders"],
"tests_status": {
"passed": 127,
"failed": 3,
"skipped": 2
}
}
Show user what was synced and what needs attention:
## SpecForge Sync Complete
**Changes Detected:**
- 1 new database migration applied
- OpenAPI spec updated (3 endpoints modified)
**Code Regenerated:**
- ✓ Database models and queries
- ✓ API request/response types
- ✓ Frontend API client
**Action Required:**
1. **Update Handlers** (3 affected):
- GET /api/users/{id}/orders - Response type changed
- POST /api/orders - Request validation changed
- PATCH /api/orders/{id} - New endpoint
Run: `/specforge:build` to update/implement handlers
2. **Fix Failing Tests** (3 tests):
Run: `/specforge:test` after handler updates
**Next Command:**
`/specforge:build` - Implement/update affected handlers
Use AskUserQuestion to get next action:
/specforge:build)/specforge:validate)# Teammate added new endpoints to OpenAPI spec
git pull origin main
# Sync to regenerate code
/specforge:sync
# You manually edited spec/openapi.yaml
# Added new endpoint: GET /api/products
paths:
/api/products:
get:
summary: List products
# ... endpoint definition
# Sync to generate types and scaffold handler
/specforge:sync
# You created a new migration file
cat > migrations/005_add_products.sql <<EOF
CREATE TABLE products (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
price_cents INTEGER NOT NULL
);
EOF
# Sync to apply migration and generate types
/specforge:sync
# Resolved conflicts in spec/openapi.yaml and migrations/
git merge feature-branch
# ... resolved conflicts ...
git add spec/openapi.yaml migrations/
git commit -m "Merge feature-branch"
# Sync to regenerate everything
/specforge:sync
When to use /specforge:sync:
When to use /specforge:build:
/specforge:planRelationship:
/specforge:plan → Propose spec changes
↓
/specforge:build → Apply specs + implement handlers + test
↓
/specforge:sync → Regenerate after external spec changes
Sync behavior can be customized in CLAUDE.md:
## SpecForge Configuration
- backend: rust-axum
- database: sqlite
- codegen: rust-sql
- frontend: react-tanstack
### Sync Options
- auto_apply_migrations: false # Require confirmation
- regenerate_on_conflict: true # Auto-regenerate on file conflicts
- run_tests_after_sync: true # Run tests automatically
- backup_before_migration: true # Backup DB before applying migrations
Always backup database before applying migrations (unless in development mode):
# Production/staging: backup first
if [ "$ENV" != "development" ]; then
echo "Backing up database..."
# Use database plugin backup skill
fi
Show what would happen without making changes:
/specforge:sync --dry-run
Would apply:
- migrations/003_add_orders.sql
- migrations/004_add_order_items.sql
Would regenerate:
- backend/src/generated/db/*
- backend/src/generated/api/*
- frontend/src/api/*
No changes made (dry run).
If migration or code generation fails, rollback changes:
Error applying migration 003_add_orders.sql:
- Foreign key constraint failed
Rolling back migration...
Database restored to previous state.
Sync failed. Please fix migration and try again.
Error: Migration 005_xxx.sql has timestamp before 004_xxx.sql
Solution: Rename migration file with correct sequential number.
Warning: backend/src/generated/db/models.rs has been manually modified
Solution:
generated/ directoryError: Invalid $ref in spec/openapi.yaml:
- #/components/schemas/Order not found
Solution: Fix OpenAPI spec, then re-run sync.
Error: Type mismatch in handler
- Expected: OrderResponse
- Found: Order
Solution: Run /specforge:build to update handlers with new types.
/specforge:plan - Generate implementation plan for new features/specforge:build - Full build pipeline (specs + handlers + tests)/specforge:validate - Validate specs and code without regenerating/specforge:test - Run test suite