feat(spec): command forms, views and lens endpoints (0.65.0) #19

Merged

peterswimm merged 1 commit from feat/spec-command-form into main

2026-10-09 15:45:37 +00:00

peterswimm commented

2026-10-09 15:32:25 +00:00

Owner

The spec side of command forms (toilville-design#177). It pairs with spel#1085, which is live, and ritual-engine#903.

Scope

openapi.yaml 0.65.0 and the CHANGELOG:

form on available commands: a new CommandForm {type, variant}, on AvailableCommand (wishes) and AvailableParlayCommand.
GET /api/v1/views (getView, which returns a ResolvedView), plus GET, PUT and DELETE /api/v1/lens (Lens). These have been live since #1041 and #870 but were never in the spec. A form points at /api/v1/views, so leaving them out would point at an undocumented endpoint.
The header and input blocks are added to the OpenAPI ForgeBlock mirror, generated from schemas/forge_block.json 1.2 rather than hand-copied: HeaderBlock, HeadingLevel, InputBlock, InputElement and its six element types, ChoiceOption, ChoiceStyle.
- Without them, every generated command form failed validation against the OpenAPI union: 38 errors.
- The mirror still omits image, fact_set, video, column_set and carousel. That is unchanged and noted in the CHANGELOG.

Testing

openapi-spec-validator: valid (OpenAPI 3.1.0).
Live responses, taken read-only from the forge, against the new schemas:
- all 14 command_form views as ResolvedView;
- the 7 commands of an in-progress wish as AvailableCommand;
- the 2 decisions on a pending parlay as AvailableParlayCommand.
0 errors, against 38 before the block mirror.
Controls, all rejected:
- a form with a malformed type and the wrong variant;
- a form whose submit button has no action_id;
- an input with an unknown element type.
tools/check_schema_registry.py: consistent. pytest: 18 passed, 1 xfailed, the same as main.

Impact Statement

Existing features: None. This is additive documentation.
Public APIs / contracts:
- documents form and four live operations;
- the OpenAPI ForgeBlock union gains two variants that the canonical schema already had.
Schemas: openapi.yaml 0.64.0 → 0.65.0. No JSON Schema file changes.
Data / artifacts: None.
Integrations: clients generated from the OpenAPI file gain the views and lens operations and the header and input block types.
Mappings: a form's action_id maps to its inputs key, and command:<command> maps to POST …/commands {command}.
Backward compatibility: additive.

Docs

The CHANGELOG entry under Unreleased.

The spec side of command forms (toilville-design#177). It pairs with spel#1085, which is live, and ritual-engine#903. ## Scope `openapi.yaml` 0.65.0 and the CHANGELOG: - **`form` on available commands:** a new `CommandForm {type, variant}`, on `AvailableCommand` (wishes) and `AvailableParlayCommand`. - **`GET /api/v1/views`** (`getView`, which returns a `ResolvedView`), plus **`GET`, `PUT` and `DELETE /api/v1/lens`** (`Lens`). These have been live since #1041 and #870 but were never in the spec. A `form` points at `/api/v1/views`, so leaving them out would point at an undocumented endpoint. - **The `header` and `input` blocks** are added to the OpenAPI `ForgeBlock` mirror, generated from `schemas/forge_block.json` 1.2 rather than hand-copied: `HeaderBlock`, `HeadingLevel`, `InputBlock`, `InputElement` and its six element types, `ChoiceOption`, `ChoiceStyle`. - Without them, every generated command form failed validation against the OpenAPI union: 38 errors. - The mirror still omits `image`, `fact_set`, `video`, `column_set` and `carousel`. That is unchanged and noted in the CHANGELOG. ## Testing - `openapi-spec-validator`: valid (OpenAPI 3.1.0). - **Live responses, taken read-only from the forge, against the new schemas:** - all 14 `command_form` views as `ResolvedView`; - the 7 commands of an in-progress wish as `AvailableCommand`; - the 2 decisions on a pending parlay as `AvailableParlayCommand`. **0 errors**, against 38 before the block mirror. - **Controls, all rejected:** - a `form` with a malformed type and the wrong variant; - a form whose submit button has no `action_id`; - an input with an unknown element type. - `tools/check_schema_registry.py`: consistent. `pytest`: 18 passed, 1 xfailed, the same as `main`. ## Impact Statement - **Existing features:** None. This is additive documentation. - **Public APIs / contracts:** - documents `form` and four live operations; - the OpenAPI `ForgeBlock` union gains two variants that the canonical schema already had. - **Schemas:** `openapi.yaml` 0.64.0 → 0.65.0. No JSON Schema file changes. - **Data / artifacts:** None. - **Integrations:** clients generated from the OpenAPI file gain the views and lens operations and the header and input block types. - **Mappings:** a form's `action_id` maps to its `inputs` key, and `command:<command>` maps to `POST …/commands {command}`. - **Backward compatibility:** additive. ## Docs The CHANGELOG entry under Unreleased.

peterswimm added 1 commit

2026-10-09 15:32:25 +00:00

feat(spec): command forms, views and lens endpoints (0.65.0)

PR policy check / policy-gate (pull_request) Successful in 0s

Details

CI / schema-registry (pull_request) Successful in 5s

Details

d6a562b2ef

form {type, variant} on available wish and parlay commands; GET /api/v1/views
and /api/v1/lens documented; header and input blocks mirrored from
forge_block.json 1.2 into the OpenAPI ForgeBlock union.

peterswimm merged commit 1817787fda into main

2026-10-09 15:45:37 +00:00

peterswimm deleted branch feat/spec-command-form

2026-10-09 15:45:37 +00:00

peterswimm referenced this pull request from a commit

2026-10-09 15:45:39 +00:00

Merge pull request 'feat(spec): command forms, views and lens endpoints (0.65.0)' (#19) from feat/spec-command-form into main

peterswimm referenced this pull request

2026-10-10 20:25:12 +00:00

Events → commands → views contract: available_commands, command submit, view/lens registry, events stream #15