AGENTS.md

Guidance for coding agents working on nk304 packages/contracts. This package is the generated contract boundary between FastAPI, web, mobile, SDK consumers, and socket payload handling.

Project Overview

packages/contracts stores openapi.json exported from the FastAPI app and generated TypeScript contract artifacts. It also generates WebSocket payload types with the local script. Generated contracts are not a place for hand-written business logic.

The package exists to keep route and socket shape changes visible. When API paths, schemas, event payloads, or envelope structures change, update the source API/schema first, export, generate, then verify consumers.

Project Map

openapi.json is exported from apps/api-py.
src/openapi.ts is generated by openapi-typescript.
src/ws.ts is generated by the local WebSocket type generator.
scripts/generate-ws.mjs builds socket payload types.
package.json defines generate, generate:openapi, and generate:ws.
README.md documents the OpenAPI export then generation sequence.

Setup Commands

From the monorepo root:

bashpnpm run contracts:export
pnpm --filter @nk304/contracts run generate
pnpm verify:web-next:contract

Manual package commands:

bashcd packages/contracts
pnpm run generate:openapi
pnpm run generate:ws

Change Rules For Agents

Do not hand edit generated TypeScript contract artifacts.
Change source schemas, endpoint responses, or socket declarations first.
Export OpenAPI from the API package before generating src/openapi.ts.
Run WebSocket generation after shared event or payload changes.
Commit generated artifacts only when the corresponding source change is in the same change set.
Review generated diffs for unexpected route, auth, or payload expansion.
If a generated diff is huge, summarize the source reason in the PR notes instead of hiding it.

Verification

bashpnpm run contracts:export
pnpm --filter @nk304/contracts run generate
pnpm verify:web-next:contract
pnpm --filter @nk304/web-next run typecheck

If mobile or SDK consumers rely on the changed path, run their closest tests too.

Security Notes

Generated contracts can expose accidental fields. Check that secret, internal, admin-only, worker-only, and protected transport fields are intentionally modeled before publishing or committing contract changes.

PR Checklist

Source API/schema/socket change explains the generated diff.
Generated files were produced by scripts.
Web and mobile consumers were checked for breakage.
Protected fields are not accidentally promoted into public response types.

nk304 Contracts Package Agent Guide