AgentBlock/docs/superpowers/plans/2026-06-23-visa-api-and-migration.md

VISA API And Migration Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add a real backend API surface and a database schema migration for the VISA backend foundation.

Architecture: Add an Express app factory with seeded in-memory VISA data so the API can run without introducing a database driver yet. Add a PostgreSQL migration file that creates the normalized VISA schema described in docs/visa-backend-database-design.md.

Tech Stack: TypeScript, Express, Node assert tests, PostgreSQL SQL migration.

---

Task 1: API Tests

Files:

• Create: src/server/visaApi.test.ts

• Step 1: Write failing API tests

Test GET /api/model-versions/:id/visa, GET /api/model-versions/:id/view-model, POST /api/model-versions/:id/actions/run-check, and a missing model version response.

• Step 2: Run the test to verify red

Run: npx.cmd tsx src/server/visaApi.test.ts. Expected: FAIL because the server app module does not exist.

Task 2: API Implementation

Files:

• Create: src/server/visaRepository.ts

• Create: src/server/visaApi.ts

• Create: src/server/index.ts

• Modify: package.json

• Step 1: Add in-memory repository

Seed the repository with createDefaultVisaSpec() and expose getVisaSpec, getWorkflowViewModel, and runConsistencyCheck.

• Step 2: Add Express app factory

Expose the VISA JSON endpoint, view-model endpoint, and run-check action.

• Step 3: Add server entry and npm script

Add src/server/index.ts and a server script using tsx.

• Step 4: Run API tests

Run: npx.cmd tsx src/server/visaApi.test.ts. Expected: PASS.

Task 3: Migration Tests

Files:

• Create: db/migrations/202606230001_create_visa_schema.test.ts

• Step 1: Write failing migration test

Assert the migration includes the system tables, VISA semantic tables, consistency check table, foreign keys, and indexes.

• Step 2: Run the test to verify red

Run: npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts. Expected: FAIL because the SQL migration does not exist.

Task 4: Migration SQL

Files:

• Create: db/migrations/202606230001_create_visa_schema.sql

• Step 1: Add PostgreSQL schema migration

Create model/version tables, VISA T1-T8 normalized tables, consistency check table, foreign keys, uniqueness constraints, and basic indexes.

• Step 2: Run migration test

Run: npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts. Expected: PASS.

Task 5: Verification

Files:

• Modify as needed based on test results.

• Step 1: Run model and API tests

Run:

• npx.cmd tsx src/workflowModel.test.ts

• npx.cmd tsx src/visaModel.test.ts

• npx.cmd tsx src/server/visaApi.test.ts

• npx.cmd tsx db/migrations/202606230001_create_visa_schema.test.ts

• Step 2: Run TypeScript check

Run: npm.cmd run lint.