feat: Typed Responses Pipeline, Auth Hardening, and Upload Validation

[davideast]

This PR integrates a complete Typed Responses Pipeline into the SDK codegen, hardens authentication documentation, adds runtime verification tests, and increments the pre-release distribution track to 0.1.2-next.5.

What Changed

1. Typed Responses Pipeline (responses.generated.ts)

We updated the code generation engine (scripts/generate-sdk.ts) to output dedicated response schemas and typescript interfaces for every MCP tool binding.

• responses.generated.ts: Emits complete structural mappings for all tool method responses (e.g., CreateProjectResponse, BatchCreateScreensResponse, ListScreensResponse).
• types.generated.ts: Contains complete underlying property schemas parsed out from tool contracts.
• Passthrough Mapping: Replaces broad any/unknown return constraints in generated domain methods (like Stitch.createProject()) with exact, high-fidelity type definitions.

2. Authentication Documentation & Verification

• upload-handler.ts: Added comprehensive trace documentation regarding direct REST interactions, body transcoder behaviors, and validation paths.
• client.ts: Hardened documentation around httpPost authentication priority logic (API Key vs OAuth token selection).
• live.test.ts: Aligned active integration verification routines to accurately consume the environment-injected STITCH_API_KEY.

3. Architectural Tests & Utilities

• parse-resource-name.test.ts: Adds exhaustive unit coverage for splitting cloud asset URIs into standalone numeric IDs (parseResourceName).
• screen-factory.test.ts: Introduces robust verification boundaries for domain instance object creation.
• utils.ts: Houses the structural resource parsing logic.

4. Pre-Release Version Stamp

• Incremented package parameters to 0.1.2-next.5.
• Executed npm run build to synchronize the compiled output and ensure the new version constant is embedded into src/version.ts.

---

Files Changed

Generator & Pipeline Engine

• scripts/generate-sdk.ts — Implemented Stage 2 Response Schema type mapping emissions
• scripts/test/generate-sdk.test.ts — Added contract assertions for response payload generation
• scripts/tool-schema.ts — Integrated schema mapping arrays

Codegen Output

• packages/sdk/generated/src/responses.generated.ts — New (Typed response interfaces)
• packages/sdk/generated/src/types.generated.ts — New (Underlying field types)
• packages/sdk/generated/src/*.ts — Regenerated with exact return signatures mapped to tool response types

SDK Codebase & Infrastructure

• packages/sdk/package.json — Incremented version to 0.1.2-next.5
• packages/sdk/src/version.ts — Hardcoded compilation stamp updated
• packages/sdk/src/utils.ts — New (Resource name parser)
• packages/sdk/src/upload-handler.ts — Enhanced trace logging documentation
• packages/sdk/src/client.ts — Added priority resolution comments to httpPost

Test Suites

• packages/sdk/test/integration/live.test.ts — Corrected integration credential resolution
• packages/sdk/test/unit/parse-resource-name.test.ts — New (Resource name utility tests)
• packages/sdk/test/unit/screen-factory.test.ts — New (Domain projection factory tests)

Documentation

• .agents/skills/stitch-sdk-usage/SKILL.md — Updated usage patterns
• packages/sdk/README.md — Documented return models