fix(deploy): validate deployment id as 8-hex app_id, not UUID

[mastermanas805]

Symptom

A live dogfood found the deployment wedge is broken end-to-end through MCP. Six deployment-by-id tools — get_deployment, get_deployment_events, redeploy, delete_deployment, update_deploy_env, wake_deployment — applied uuidSchema (canonical 8-4-4-4-12 UUID) to their id/app_id argument. But a deployment app_id is 8-char lowercase hex, not a UUID. So zod rejected every real call client-side with -32602 before it reached the api. An agent could create_deploy (receives deploy_id like a3f91c0e) and then could NOT poll status, read failure events, redeploy, delete, update env, or wake it. The whole manage-the-deploy loop was dead through MCP.

Root cause / why it shipped green

Two compounding masks let 161 tests pass while every real call was broken:

1. The mock was made to lie. A prior change (BUG-MCP-025) edited test/mock-api.ts to EMIT UUID-shaped app_ids ("now the mock returns a UUID-shaped app_id like prod") — but prod does not emit UUID app_ids. The mock was made to match the wrong schema, so fixtures never tripped it.
2. The unit tests bypass the schema. The handler tests call server._registeredTools[name].handler(...) directly, bypassing the zod inputSchema the real MCP SDK dispatch applies at the wire boundary. The validation that breaks in prod was never exercised in test.

Ground truth (verified)

• api generateAppID() (api/internal/handlers/deploy.go): hex.EncodeToString of 4 random bytes ⇒ exactly 8 lowercase hex chars. Comment: "generateAppID produces an 8-char lowercase hex string via crypto/rand."
• Live openapi DeployItem: app_id = "8-char public identifier used in the URL"; token = "Public-facing alias for app_id (same 8-char value)". (id is the DB row PK, format: uuid — but the URL identifier is app_id/token.)
• openapi route params for /deploy/{id}, /deploy/{id}/events, /deploy/{id}/wake, /api/v1/deployments/{id} are all bare {type: string}.
• Resource tokens ARE real UUIDs — uuidSchema stays correct for delete_resource, presign_storage, pause_resource, resume_resource, rotate_credentials. Those are untouched.

Fix

1. Introduce deployIdSchema = z.string().regex(/^[0-9a-f]{8}$/, ...) (named const APP_ID_REGEX), matching the api's real format with a precise agent-facing error message.
2. Apply deployIdSchema to exactly the 6 deployment-id tools. uuidSchema left on the 5 resource-token tools.
3. Revert the mock lie: test/mock-api.ts now emits 8-hex app_ids (via a generateAppId() helper mirroring the api's generateAppID()), so create_deploy → the manage tools round-trips in tests the way it does in prod. The DB row id stays a UUID (matches openapi).
4. Regression test (test/deploy-id-schema-unit.test.ts) that drives the registered inputSchema (the SDK dispatch path, NOT handlerFor), iterating the six tools as a registry: asserts each ACCEPTS a3f91c0e and REJECTS a UUID + an obviously-bad value, plus deployIdSchema.parse unit contracts. Also corrected the stale input-hardening-unit.test.ts block that codified the lie, and the two integration.test.ts 404 tests (which DO go through real client.callTool dispatch — they passed a UUID that would now be rejected before reaching the api).
5. Pin zod in dependencies (4.3.6, the lockfile-resolved version) — src/index.ts imports zod but it was only resolving as an SDK peer.

Coverage block (rule 17)

Symptom:        deployment-id tools reject the real 8-hex app_id client-side (-32602)
Enumeration:    grep -n "uuidSchema\.describe|id: uuidSchema" src/index.ts  (mapped each to its server.tool name)
Sites found:    11 uuidSchema usages total
Sites touched:  6  (the deployment-id tools); 5 resource-token tools left on uuidSchema (correct — their tokens ARE UUIDs)
Coverage test:  test/deploy-id-schema-unit.test.ts — iterates the registered inputSchema for all 6 tools (registry-style, rule 18); reds if any tool reverts to uuidSchema OR if app_id format changes
Local verified: npm test → 477 pass / 0 fail. New test reds (12 failures) when the tools are reverted to uuidSchema (sanity-checked). The full create→get→redeploy→delete lifecycle now round-trips through real client.callTool dispatch with a real 8-hex id.

Notes

• Library/server change — no platform deploy. Published to npm on release, but this PR does NOT cut a release tag (just merge).

Follow-ups (NOT in this PR — MCP-vs-API tool gaps the dogfood flagged)

• get_deploy_logs — api exposes GET /deploy/{id}/logs; no MCP tool wraps it.
• stacks redeploy — single-app redeploy exists; no equivalent for multi-service stacks.
• resource credentials re-fetch — no MCP tool to re-retrieve a resource's connection string after the initial provision response.

🤖 Generated with Claude Code