#1069 - Flows YAML — Zod → JSON Schema build pipeline - charles/claude-hooks

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#1069

claude-desktop commented

2026-05-10 15:38:52 +00:00

Collaborator

User story

As the editor, I need a single JSON Schema that drives both server validation and Monaco autocomplete, so that adding a new op or trigger automatically extends what the UI offers.

Acceptance criteria

Source of truth

Zod schemas in apps/server/src/domain/flows-yaml/schema.ts cover FlowFile, TriggerKind, every op's argsSchema (discriminated on uses), and built-in expression types.
Each Zod field has a .describe() string used as JSON Schema description (and Monaco hover text).

Generation

Build script apps/server/scripts/generate-flow-schema.ts runs zod-to-json-schema.
Output: apps/web/public/schemas/flows.schema.json (committed) and apps/server/src/domain/flows-yaml/flows.schema.json.
Schema registered with format: "flow-expression" on every expression-string field for downstream linting.

CI integration

just qa regenerates the schema and fails if the committed file is out of date.
The build pipeline runs the generator before web bundling so dev/prod ship identical schemas.

Server consumption

POST /flows and PUT /flows/:name re-parse with Zod (authoritative); JSON Schema mismatch is a 422.

Tests

Snapshot of generated schema; review-only churn flagged.
Round-trip: each *.yml default validates against the generated schema.

Out of scope

Editor wiring (covered by #flows-12).
Custom format validators beyond flow-expression tag.

References

Spec: docs/specs/flows-yaml.md §10.3.2.

## User story As the editor, I need a single JSON Schema that drives both server validation and Monaco autocomplete, so that adding a new op or trigger automatically extends what the UI offers. ## Acceptance criteria ### Source of truth - [ ] Zod schemas in `apps/server/src/domain/flows-yaml/schema.ts` cover `FlowFile`, `TriggerKind`, every op's `argsSchema` (discriminated on `uses`), and built-in expression types. - [ ] Each Zod field has a `.describe()` string used as JSON Schema `description` (and Monaco hover text). ### Generation - [ ] Build script `apps/server/scripts/generate-flow-schema.ts` runs `zod-to-json-schema`. - [ ] Output: `apps/web/public/schemas/flows.schema.json` (committed) and `apps/server/src/domain/flows-yaml/flows.schema.json`. - [ ] Schema registered with `format: "flow-expression"` on every expression-string field for downstream linting. ### CI integration - [ ] `just qa` regenerates the schema and fails if the committed file is out of date. - [ ] The build pipeline runs the generator before web bundling so dev/prod ship identical schemas. ### Server consumption - [ ] `POST /flows` and `PUT /flows/:name` re-parse with Zod (authoritative); JSON Schema mismatch is a 422. ### Tests - [ ] Snapshot of generated schema; review-only churn flagged. - [ ] Round-trip: each `*.yml` default validates against the generated schema. ## Out of scope - Editor wiring (covered by #flows-12). - Custom format validators beyond `flow-expression` tag. ## References - Spec: `docs/specs/flows-yaml.md` §10.3.2.

claude-desktop added this to the Flows YAML milestone

claude-desktop

closed this issue
added the
area:flows

type:user-story
labels

Rows
Columns

Flows YAML — Zod → JSON Schema build pipeline #1069