feat(list): publish a JSON Schema for the schema-2 envelope

[max-sixty]

wt list --format=json schema 2 now has a published, machine-readable contract at worktrunk.dev/schema/list-v2.json.

The schema was already derived — test_schema_generates built one, asserted it compiled, and threw it away, with a comment saying "until the schema export ships." This ships it: wt list --print-schema prints the document (a developer entry point alongside --help-page, intercepted before clap), and a new step in test_docs_are_in_sync commits it to docs/static/schema/list-v2.json, the same generate-and-commit pattern as llms.txt. It shells out rather than calling schema_for! because JsonEnvelope lives in the bin-only crate::commands tree.

Two things had to be fixed for the document to be usable.

The contract. schema_for! generates under schemars' deserialize contract, which marks a skip_serializing_if field required — nothing supplies it on the way in. The first document I generated therefore required default_branch, upstream, pr, checks, summary and vars on every item, all of which the absence rule routinely omits, so it rejected the output it documents. Generating under for_serialize() fixes it.

The vocabularies. Four fields — checks.status, display.state, default_branch.integration.reason and worktree.operation — were &'static str, so the schema described them as bare strings. They are now JsonCheckStatus, JsonMainState, JsonIntegrationReason and JsonOperation, each converted from its domain enum by an exhaustive match, so a new CiStatus, MainState, IntegrationReason or InProgressOperation variant is a compile error rather than a value silently missing from the published vocabulary. The emitted JSON is unchanged; the existing envelope snapshot passes untouched.

Before and after, for one item

// before — rejects its own output, and loses the vocabulary
"required": ["default_branch", "upstream", "pr", "checks", "summary", "vars", "display"],
"status": { "type": "string" }

// after
"required": ["branch", "head", "display"],
"status": { "enum": ["passed", "running", "failed"] }

Testing

test_schema_accepts_envelopes validates a battery — every CiStatus over both sources, every MainState, a populated worktree row, an integrated row with an upstream and a dev server, plus the absent and null arms of the absence rule — against the same document --print-schema emits.

Validating proves nothing about a type the battery never instantiates, so the test also pins every non-Nullable_ type in the document to a path that must carry a non-null value. A new Json* type fails until the battery reaches it, and a row that stops populating one fails too — the check reports the type names rather than leaving the gap to a reader. This needed a jsonschema dev-dependency: schemars only generates, and derives the document from the types without ever seeing an envelope, so nothing otherwise tied the two together.

The test was confirmed to fail on the bug it exists for. Reverting to for_deserialize() makes it report pr, checks, summary, vars and display.columns as wrongly required.

The dependency is dev-only: reqwest, rustls and async-trait stay unselected so no HTTP stack comes along, and cargo tree --package worktrunk --edges normal -i jsonschema finds no path to it.

One direction it deliberately does not cover: a loosening. If a field reverted to &'static str the schema would say type: string and anything would validate. That direction is held by the compiler instead, via the exhaustive matches.

Notes for review

• schema_document() lives in json_v2.rs beside the types, not in help.rs, so --print-schema and the test compile the same document rather than two constructions that could drift on the contract setting.
• The lychee exclusion for worktrunk.dev/schema/ follows the entry directly above it: a generated link that 404s until the site deploys.

This was written by Claude Code on behalf of max-sixty

[worktrunk-bot]

worktree.operation is a fourth field of the shape this PR converts, and it stays &'static str. JsonWorktreeV2's pub operation: Tri<&'static str> — doc comment In-progress operation: "rebase", "merge", "cherry_pick", "revert", or "bisect" — lands in the published document as {"$ref": "#/$defs/Nullable_string"}, i.e. {"type": ["string", "null"]}, so the schema drops that vocabulary exactly the way checks.status did before this change. The value comes from operation.into() on InProgressOperation's strum::IntoStaticStr, so a sixth variant would appear in published output with nothing failing to compile — the drift the new exhaustive From impls exist to prevent. A JsonOperation mirroring JsonIntegrationReason would close it, and test_operation_arms already pins the five wire names to assert against.

Two smaller ones inline.

[worktrunk-bot]

The added worktree row only sets git_operation, so the rest of the subtree the fix is named for stays absent-or-null: locked/prunable are None and carry skip_serializing_if, so both fields are omitted, and working_tree_status is None so changes serializes as null. JsonReason, JsonChanges and JsonDiff ship in the published document and still never meet a real object, which makes the guard's message ("battery no longer covers the worktree subtree") claim more than the assertion checks — it pins operation alone. Suggestion inline.

Same class outside the worktree subtree, if it's worth closing in one pass: no battery item sets an integration signal, so check_integration returns None for every row and default_branch.integration lands as Tri::Unknown throughout (the same null test_absence_rule_unresolved_vs_determined asserts for a fresh item). JsonIntegration and JsonIntegrationReason are therefore never validated against output — and JsonIntegrationReason is one of the three enums this PR adds precisely to stop that vocabulary drifting. upstream (item.upstream unset → null) and dev_server (item.url unset → absent) leave JsonUpstream and JsonDevServer in the same position.