Piu Frontend Sync

PIU Frontend Sync

Scans a frontend repository for HTTP API calls and cross-references them against a PIU project to find mismatches, missing endpoints, and type contract violations.

CLI Scripts

This skill bundles scripts/piu.ts (relative to this SKILL.md):

bun scripts/piu.ts <command> [args...]     # MCP client (46 tools)

For full tool reference, see the piu-mcp skill.

Prerequisites

A PIU project must exist with backend routes synced (via backend-sync or manual creation).

Step 0: Re-Sync Detection

For previously audited projects, check if the frontend repo changed:

# The PIU project description stores the last audited commit:
# "Frontend audit: <commit_sha> @ <timestamp> from <repo_url>"
bun scripts/piu.ts get-project PROJECT_ID

cd /path/to/frontend/repo
OLD_COMMIT="<from PIU description>"
NEW_COMMIT=$(git rev-parse HEAD)

if [ "$OLD_COMMIT" = "$NEW_COMMIT" ]; then
  echo "No frontend changes since last audit"
  exit 0
fi

# Get changed API-related files
git diff --name-only "$OLD_COMMIT" "$NEW_COMMIT" | grep -E '(api|service|hook|store|lib|utils)/'

Step 1: Clone & Identify Frontend Framework

TMPDIR=$(mktemp -d /tmp/piu-frontend-sync-XXXXX)
git clone --depth 1 <url> "$TMPDIR/repo"
cd "$TMPDIR/repo"
COMMIT=$(git rev-parse HEAD)

Detect from package.json:

Step 2: API Call Discovery

Scan directories in priority order:

1. **/api/** — Dedicated API layer
2. **/services/** — Service layer
3. **/hooks/** — Custom hooks
4. **/lib/** — Library utilities
5. **/store/** or **/stores/** — State management

Search for HTTP call patterns:

For each API call, extract:

• HTTP method (GET, POST, PUT, DELETE, PATCH)
• URL path (resolve relative paths, strip baseURL prefixes)
• Request body TypeScript interface (if typed)
• Response TypeScript interface (if typed)
• File and line number

Skip: **/*.test.*, **/*.spec.*, **/__tests__/**, **/__mocks__/**

Step 3: Cross-Reference Against PIU

# Full project tree with all requests
bun scripts/piu.ts tree PROJECT_ID

# Search for specific endpoints
bun scripts/piu.ts search PROJECT_ID "/users" POST

# Or use the knowledge graph for semantic search
bun scripts/piu.ts search-entities '{"query":"user authentication","project_id":"PROJECT_ID","entity_type":"request"}'

# API surface summary
bun scripts/piu.ts api-surface PROJECT_ID

Match each frontend call against PIU requests by:

1. Method match — HTTP method must be identical
2. Path match — Normalize paths (strip /api prefix, resolve :param ↔ {{param}})

Categorize:

• MATCHED — Frontend call has a PIU request
• MISSING_IN_PIU — Frontend calls it but PIU doesn't have it
• MISSING_IN_FRONTEND — PIU has it but frontend doesn't call it

Step 4: Contract Validation (MATCHED endpoints)

For matched endpoints with TypeScript interfaces, compare types:

Frontend types (from codebase): request body interfaces, response interfaces, path param types.

PIU Data Models (from MCP):

bun scripts/piu.ts request-models REQUEST_ID
bun scripts/piu.ts resolve-fields MODEL_ID

Compare field-by-field:

• Missing fields — PIU model has a field the frontend doesn't expect
• Extra fields — Frontend expects a field PIU model doesn't have
• Type mismatches — Field type differs (string vs number)
• Required/optional — Disagree on whether a field is required

Step 4.5: Response Validation (optional)

If the backend is running, validate actual responses:

# Execute a request
bun scripts/piu.ts execute REQUEST_ID

# Validate response against linked model
bun scripts/piu.ts validate '{"model_id":"RESPONSE_MODEL_ID","response_body":"{...}"}'

# Batch verify all GET endpoints
bun scripts/piu.ts verify PROJECT_ID

Step 5: Report

rm -rf "$TMPDIR"

## Frontend API Sync Report

**Frontend Repository:** <url>
**Frontend Commit:** <short_sha>
**Framework:** <detected>
**API Client:** <detected>
**PIU Project:** <name> (ID: <id>)

### Summary
- Total frontend API calls: <N>
- Matched: <count>
- Missing in PIU: <count>
- Missing in Frontend: <count>

### Missing in PIU
| Method | Path | File | Line |
|--------|------|------|------|
| POST | /api/users/bulk | src/api/users.ts | 45 |

### Missing in Frontend
| Method | Path | Collection |
|--------|------|------------|
| DELETE | /users/:id | Users |

### Contract Mismatches
| Endpoint | Field | Frontend Type | PIU Model Type | Issue |
|----------|-------|---------------|----------------|-------|
| POST /users | age | number \| undefined | number (required) | Required in PIU, optional in frontend |

### Recommendations
1. Add missing endpoints to PIU: [list]
2. Review dead endpoints: [list]
3. Fix type mismatches: [list]

Step 5.5: Auto-Fix Mode (optional)

When the user requests auto-fix, create missing PIU entities:

# Create missing requests
bun scripts/piu.ts create-request '{"collection_id":"...","name":"Bulk Create Users","config":{"method":"POST","url":"/bulk","headers":[],"params":[],"body":{"type":"json","content":""},"auth":{"type":"none"},"description":"..."}}'

# Create models from TypeScript interfaces
bun scripts/piu.ts create-model '{"project_id":"...","name":"BulkCreateRequest","fields":[{"name":"users","field_type":"array","required":true}]}'

# Link model to request
bun scripts/piu.ts link-model '{"request_id":"...","model_type":"request","model_id":"..."}'

# Use entity relations to find what's connected
bun scripts/piu.ts find-related request REQUEST_ID

Update Audit Marker

After audit, store the frontend commit in PIU project description:

bun scripts/piu.ts update-project '{"project_id":"PROJECT_ID","description":"...\nFrontend audit: <COMMIT> @ <TIMESTAMP> from <REPO_URL>"}'

Notes

• Normalize paths before comparison: strip /api prefix, convert :param to {{param}}
• Resolve base URL configuration before matching
• For monorepo frontends, ask which app to analyze
• Use api-surface for a quick view of all PIU endpoints to compare against
• Use search-entities for semantic search when path matching is ambiguous
• Use find-related to trace entity relationships after auto-fix
• Use model-mermaid to visualize the API contract between frontend and backend