@sudobility/music_types 0.1.0

package/CLAUDE.md

@@ -0,0 +1,46 @@
+# @sudobility/music_types
+
+TypeScript types and Zod schemas for the ScoreSmith music family (music_api, music_client, music_lib, music_app).
+
+## Tech Stack
+
+- TypeScript (strict), ESM only, built with `tsc -p tsconfig.esm.json`
+- Zod v4 schemas (runtime dependency — schemas are exported values)
+- Bun for scripts, vitest for tests
+- Published to npm as `@sudobility/music_types` (public access) via CI on push to main
+
+## Commands
+
+- `bun install` — install dependencies
+- `bun run verify` — typecheck + lint + test + build (run before any push)
+- `bun run test` — vitest (tests co-located in `src/*.test.ts`)
+- `bun run build` — emit `dist/`
+
+## Structure
+
+Everything exports from a single sectioned `src/index.ts`:
+
+1. Score model types (Score/Track/Measure/Voice/NoteEvent/RestEvent, DurationName, Clef, …)
+2. Type guards (`isNoteEvent`, `isRestEvent`)
+3. Selection/fragment types (`ScoreRange`, `ScoreSelection`, `ScoreFragment`)
+4. Zod schemas for the score tree (`scoreSchema`, `parseScore`, …)
+5. AI generation contracts (`GenerateScoreRequest` → `GenerateScoreResult`, `RegenerateRegionRequest` → `RegenerateRegionResult`, `MusicGenerationProvider`)
+6. Zod schemas for the generation contracts (`parseGenerateScoreRequest`, …)
+7. Project API types (`ProjectRecord`, `ProjectSummary`, `ProjectCreateRequest`, `ProjectUpdateRequest`, `ProjectListQuery`)
+8. Zod schemas for the project API
+9. Response envelope (`ApiResponse<T>`, `successResponse`, `errorResponse`, `API_ERROR_CODES`)
+
+`src/test-helpers.ts` is a test-only factory stand-in (excluded from the published build); the real factories live in `@sudobility/music_lib`.
+
+## Gotchas
+
+- No domain logic here: tick math, factories, commands, validation logic all live in `@sudobility/music_lib`. This package must never depend on music_lib (music_api depends on this package and must not pull in UI/audio code).
+- `noteEventSchema`/`restEventSchema` are `.strict()` on purpose (a stray `pitch` key must not pass as a rest); other schemas strip unknown keys for forward compatibility.
+- Ticks are integers at 480 PPQ by convention; `startTick` is absolute.
+
+## Related Projects
+
+- `music_api` — backend (Hono/Drizzle/OpenAI proxy), consumes schemas for validation
+- `music_client` — typed network client + React Query hooks
+- `music_lib` — domain logic, adapters, store
+- `music_app` — web app (UI/routing only)

package/README.md

@@ -0,0 +1,42 @@
+# @sudobility/music_types
+
+Shared TypeScript types and Zod schemas for the ScoreSmith music platform: the score data model, AI generation contracts, project API payloads, and the standard API response envelope.
+
+## Installation
+
+```bash
+bun add @sudobility/music_types
+```
+
+## Usage
+
+```ts
+import {
+  type Score,
+  parseScore,
+  type GenerateScoreRequest,
+  successResponse,
+} from '@sudobility/music_types';
+
+const score: Score = parseScore(untrustedJson); // throws ZodError on invalid input
+```
+
+## API Summary
+
+- **Score model** — `Score`, `Track`, `Measure`, `Voice`, `NoteEvent`, `RestEvent`, guards `isNoteEvent`/`isRestEvent`
+- **Selection/fragments** — `ScoreRange`, `ScoreSelection`, `ScoreFragment`
+- **Zod schemas** — `scoreSchema` tree + `parseScore`
+- **Generation contracts** — `GenerateScoreRequest`/`GenerateScoreResult`, `RegenerateRegionRequest`/`RegenerateRegionResult`, `MusicGenerationProvider`, with schemas and `parse*` helpers
+- **Project API** — `ProjectRecord`, `ProjectSummary`, create/update/list-query types + schemas
+- **Envelope** — `ApiResponse<T>`, `successResponse`, `errorResponse`, `API_ERROR_CODES`
+
+## Development
+
+```bash
+bun install
+bun run verify   # typecheck + lint + test + build
+```
+
+## License
+
+BUSL-1.1