Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

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

Maximilian Roos7f8ac8e5d757
diff --git a/.config/lychee.toml b/.config/lychee.toml
index 70b980501..394c5daa6 100644
--- a/.config/lychee.toml
+++ b/.config/lychee.toml
@@ -24,12 +24,14 @@ exclude = [
# Zola internal links use @/ syntax (validated by `zola check`, not lychee)
"/@/",
- # Self-referential `.md` links in docs/static/llms.txt. These are generated
- # (and their existence guaranteed) by `test_docs_are_in_sync`, and they
- # point at the live site — so a newly added page's link always 404s until
- # the site is deployed. Prose/template links use the trailing-slash form
- # (worktrunk.dev/faq/), so this only excludes the llms.txt index entries.
+ # Links to files under docs/static/ that `test_docs_are_in_sync` generates.
+ # It guarantees their existence, and they point at the live site — so a
+ # newly added one always 404s until the site is deployed. The first pattern
+ # covers llms.txt's self-referential index entries; prose and template
+ # links use the trailing-slash form (worktrunk.dev/faq/), so it doesn't
+ # reach them. The second covers the published JSON Schema.
"worktrunk\\.dev/[a-z0-9-]+\\.md",
+ "worktrunk\\.dev/schema/",
# Private or authenticated GitHub resources
"github\\.com/anthropics/claude-code/issues",
diff --git a/Cargo.lock b/Cargo.lock
index 33f5f2908..4f8e1a28b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,6 +2,20 @@
# It is not intended for manual editing.
version = 4
+[[package]]
+name = "ahash"
+version = "0.8.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
+dependencies = [
+ "cfg-if",
+ "getrandom 0.3.4",
+ "once_cell",
+ "serde",
+ "version_check",
+ "zerocopy",
+]
+
[[package]]
name = "aho-corasick"
version = "1.1.4"
@@ -261,7 +275,16 @@ version = "0.5.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0700ddab506f33b20a03b13996eccd309a48e5ff77d0d95926aa0210fb4e95f1"
dependencies = [
- "bit-vec",
+ "bit-vec 0.6.3",
+]
+
+[[package]]
+name = "bit-set"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
+dependencies = [
+ "bit-vec 0.8.0",
]
[[package]]
@@ -270,6 +293,12 @@ version = "0.6.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
+[[package]]
+name = "bit-vec"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e764a1d40d510daf35e07be9eb06e75770908c27d411ee6c92109c9840eaaf7"
+
[[package]]
name = "bitflags"
version = "1.3.2"
@@ -325,6 +354,12 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "borrow-or-share"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c"
+
[[package]]
name = "bstr"
version = "1.12.1"
@@ -348,6 +383,12 @@ version = "1.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "64fa3c856b712db6612c019f14756e64e4bcea13337a6b33b696333a9eaa2d06"
+[[package]]
+name = "bytecount"
+version = "0.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e"
+
[[package]]
name = "bytemuck"
version = "1.25.0"
@@ -884,6 +925,12 @@ dependencies = [
"parking_lot_core",
]
+[[package]]
+name = "data-encoding"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06"
+
[[package]]
name = "deltae"
version = "0.3.2"
@@ -1002,6 +1049,17 @@ dependencies = [
"objc2",
]
+[[package]]
+name = "displaydoc"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.1",
+]
+
[[package]]
name = "document-features"
version = "0.2.12"
@@ -1041,6 +1099,15 @@ version = "1.15.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+[[package]]
+name = "email_address"
+version = "0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e079f19b08ca6239f47f8ba8509c11cf3ea30095831f7fed61441475edd8c449"
+dependencies = [
+ "serde",
+]
+
[[package]]
name = "encode_unicode"
version = "1.0.0"
@@ -1104,10 +1171,21 @@ version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b95f7c0680e4142284cf8b22c14a476e87d61b004a3a0861872b32ef7ead40a2"
dependencies = [
- "bit-set",
+ "bit-set 0.5.3",
"regex",
]
+[[package]]
+name = "fancy-regex"
+version = "0.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "476de73bddf2ef8490aa4ee8f1cf40b430bf1d56c48c22080e5186952cd580e6"
+dependencies = [
+ "bit-set 0.8.0",
+ "regex-automata",
+ "regex-syntax",
+]
+
[[package]]
name = "fast-srgb8"
version = "1.0.0"
@@ -1155,6 +1233,17 @@ version = "0.5.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
+[[package]]
+name = "fluent-uri"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc74ac4d8359ae70623506d512209619e5cf8f347124910440dbc221714b328e"
+dependencies = [
+ "borrow-or-share",
+ "ref-cast",
+ "serde",
+]
+
[[package]]
name = "fnv"
version = "1.0.7"
@@ -1173,6 +1262,16 @@ version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+[[package]]
+name = "fraction"
+version = "0.15.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e076045bb43dac435333ed5f04caf35c7463631d0dae2deb2638d94dd0a5b872"
+dependencies = [
+ "lazy_static",
+ "num",
+]
+
[[package]]
name = "frizbee"
version = "0.11.0"
@@ -1321,9 +1420,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
dependencies = [
"cfg-if",
+ "js-sys",
"libc",
"r-efi 5.3.0",
"wasip2",
+ "wasm-bindgen",
]
[[package]]
@@ -1464,12 +1565,115 @@ dependencies = [
"cc",
]
+[[package]]
+name = "icu_collections"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "utf8_iter",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
+
+[[package]]
+name = "icu_properties"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
+
+[[package]]
+name = "icu_provider"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
[[package]]
name = "ident_case"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
[[package]]
name = "if_chain"
version = "1.0.3"
@@ -1628,6 +1832,58 @@ dependencies = [
"wasm-bindgen",
]
+[[package]]
+name = "jsonschema"
+version = "0.49.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8da60094fc1968bbd091e2cfa004415cb7b19e25e592376e66a64aa832bb6039"
+dependencies = [
+ "ahash",
+ "bytecount",
+ "data-encoding",
+ "email_address",
+ "fancy-regex 0.19.0",
+ "fraction",
+ "getrandom 0.3.4",
+ "idna",
+ "itoa",
+ "jsonschema-regex",
+ "jsonschema-value",
+ "num-cmp",
+ "num-traits",
+ "percent-encoding",
+ "referencing",
+ "regex",
+ "serde",
+ "serde_json",
+ "strum",
+ "unicode-general-category",
+ "uuid-simd",
+]
+
+[[package]]
+name = "jsonschema-regex"
+version = "0.49.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36539f34ef9e5da418433fbbf7294522d8f930ecf6a540ccd1ec6481c9ff9056"
+dependencies = [
+ "regex-syntax",
+]
+
+[[package]]
+name = "jsonschema-value"
+version = "0.49.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8bc513dfee68c6fe29498451df95a32951ea227801b476f4a1f236433986c891"
+dependencies = [
+ "ahash",
+ "bytecount",
+ "fraction",
+ "num-cmp",
+ "num-traits",
+ "serde_json",
+]
+
[[package]]
name = "kanal"
version = "0.1.1"
@@ -1731,6 +1987,12 @@ version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+[[package]]
+name = "litemap"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
+
[[package]]
name = "litrs"
version = "1.0.0"
@@ -1807,6 +2069,12 @@ dependencies = [
"autocfg",
]
+[[package]]
+name = "micromap"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a86d3146ed3995b5913c414f6664344b9617457320782e64f0bb44afd49d74"
+
[[package]]
name = "mimalloc"
version = "0.1.48"
@@ -1930,6 +2198,45 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "num"
+version = "0.4.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "35bd024e8b2ff75562e5f34e7f4905839deb4b22955ef5e73d2fea1b9813cb23"
+dependencies = [
+ "num-bigint",
+ "num-complex",
+ "num-integer",
+ "num-iter",
+ "num-rational",
+ "num-traits",
+]
+
+[[package]]
+name = "num-bigint"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-cmp"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63335b2e2c34fae2fb0aa2cecfd9f0832a1e24b3b32ecec612c3426d46dc8aaa"
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
[[package]]
name = "num-conv"
version = "0.2.2"
@@ -1947,6 +2254,36 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-iter"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
+[[package]]
+name = "num-rational"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f83d14da390562dca69fc84082e73e548e1ad308d24accdedd2720017cb37824"
+dependencies = [
+ "num-bigint",
+ "num-integer",
+ "num-traits",
+]
+
[[package]]
name = "num-traits"
version = "0.2.19"
@@ -2097,6 +2434,12 @@ version = "0.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8b2d2086a3a477709f0208181e65857a9c062064ab2b3bb9abaf64f17d148bf3"
+[[package]]
+name = "outref"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a80800c0488c3a21695ea981a54918fbb37abf04f4d0720c453632255e2ff0e"
+
[[package]]
name = "page_size"
version = "0.6.0"
@@ -2366,6 +2709,15 @@ dependencies = [
"winreg",
]
+[[package]]
+name = "potential_utf"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
+dependencies = [
+ "zerovec",
+]
+
[[package]]
name = "powerfmt"
version = "0.2.0"
@@ -2632,6 +2984,23 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "referencing"
+version = "0.49.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05915176d843da9ec5c925e5e2631be9aa61b27430acfdd562e79cae8f559725"
+dependencies = [
+ "ahash",
+ "fluent-uri",
+ "getrandom 0.3.4",
+ "hashbrown 0.17.0",
+ "itoa",
+ "micromap",
+ "parking_lot",
+ "percent-encoding",
+ "serde_json",
+]
+
[[package]]
name = "reflink-copy"
version = "0.1.30"
@@ -3103,6 +3472,12 @@ dependencies = [
"windows-sys 0.61.2",
]
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
[[package]]
name = "static_assertions"
version = "1.1.0"
@@ -3221,6 +3596,17 @@ dependencies = [
"unicode-width 0.2.2",
]
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
[[package]]
name = "tempfile"
version = "3.27.0"
@@ -3303,7 +3689,7 @@ dependencies = [
"anyhow",
"base64",
"bitflags 2.13.0",
- "fancy-regex",
+ "fancy-regex 0.11.0",
"filedescriptor",
"finl_unicode",
"fixedbitset 0.4.2",
@@ -3417,6 +3803,16 @@ dependencies = [
"time-core",
]
+[[package]]
+name = "tinystr"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
[[package]]
name = "tinytemplate"
version = "1.2.1"
@@ -3705,6 +4101,12 @@ dependencies = [
"unicode-segmentation",
]
+[[package]]
+name = "unicode-general-category"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b993bddc193ae5bd0d623b49ec06ac3e9312875fdae725a975c51db1cc1677f"
+
[[package]]
name = "unicode-ident"
version = "1.0.22"
@@ -3761,6 +4163,12 @@ version = "2.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "daf8dba3b7eb870caf1ddeed7bc9d2a049f3cfdfae7cb521b087cc33ae4c49da"
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
[[package]]
name = "utf8parse"
version = "0.2.2"
@@ -3779,6 +4187,16 @@ dependencies = [
"wasm-bindgen",
]
+[[package]]
+name = "uuid-simd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23b082222b4f6619906941c17eb2297fff4c2fb96cb60164170522942a200bd8"
+dependencies = [
+ "outref",
+ "vsimd",
+]
+
[[package]]
name = "valuable"
version = "0.1.1"
@@ -3829,6 +4247,12 @@ version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+[[package]]
+name = "vsimd"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c3082ca00d5a5ef149bb8b555a72ae84c9c59f7250f013ac822ac2e49b19c64"
+
[[package]]
name = "vt100"
version = "0.16.2"
@@ -4414,6 +4838,7 @@ dependencies = [
"indexmap",
"insta",
"insta-cmd",
+ "jsonschema",
"log",
"minijinja",
"nix 0.31.3",
@@ -4479,6 +4904,12 @@ dependencies = [
"thiserror 2.0.18",
]
+[[package]]
+name = "writeable"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ffae5123b2d3fc086436f8834ae3ab053a283cfac8fe0a0b8eaae044768a4c4"
+
[[package]]
name = "wt-perf"
version = "0.1.0"
@@ -4509,6 +4940,29 @@ version = "0.13.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd"
+[[package]]
+name = "yoke"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "synstructure",
+]
+
[[package]]
name = "zerocopy"
version = "0.8.33"
@@ -4529,6 +4983,60 @@ dependencies = [
"syn 2.0.117",
]
+[[package]]
+name = "zerofrom"
+version = "0.1.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+ "synstructure",
+]
+
+[[package]]
+name = "zerotrie"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.117",
+]
+
[[package]]
name = "zmij"
version = "1.0.16"
diff --git a/Cargo.toml b/Cargo.toml
index a4ed23f73..33e8bf095 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -324,6 +324,7 @@ vt100 = "0.16.2"
ansi-to-html = "0.2.3"
wt-perf = { path = "tests/helpers/wt-perf" }
similar = "3.1.1"
+jsonschema = { version = "0.49", default-features = false }
[[bench]]
name = "alias"
diff --git a/docs/content/list.md b/docs/content/list.md
index 7598d1fb2..e89abb534 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -294,6 +294,11 @@ and the per-item `repo` moves to the envelope's `repo.forge`.
{{ terminal(cmd="# Current worktree path (for scripts)|||wt list --format=json | jq -r '.items[] | select(.worktree.current) | .worktree.path'||||||# Branches with uncommitted changes|||wt list --format=json | jq '.items[] | select(.worktree.changes.modified)'||||||# Integrated branches (safe to remove)|||wt list --format=json | jq '.items[] | select(.display.state == __WT_QUOT__integrated__WT_QUOT__ or .display.state == __WT_QUOT__empty__WT_QUOT__) | .branch'||||||# Worktrees ahead of upstream (needs pushing)|||wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'") }}
+A JSON Schema for the envelope is published at
+[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).
+It describes what `wt` writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
### Schema 1
The original bare-array format, and the default while unset:
diff --git a/docs/static/schema/list-v2.json b/docs/static/schema/list-v2.json
new file mode 100644
index 000000000..4003140b6
--- /dev/null
+++ b/docs/static/schema/list-v2.json
@@ -0,0 +1,830 @@
+{
+ "$defs": {
+ "CiSource": {
+ "description": "Source of CI status (PR/MR vs branch workflow)\n\nSerialized to JSON as \"pr\" or \"branch\" for programmatic consumers.",
+ "oneOf": [
+ {
+ "const": "pr",
+ "description": "Pull request or merge request",
+ "type": "string"
+ },
+ {
+ "const": "branch",
+ "description": "Branch workflow/pipeline (no PR/MR)",
+ "type": "string"
+ }
+ ]
+ },
+ "Collected": {
+ "description": "Fact families whose collection is gated (`--full`, `[list] summary`,\na listed `ci`/`summary` column). Ungated families (working tree, counts,\ndiffs) are always requested. Serialized as-is into the schema-2 JSON\nenvelope's `collected` field, disambiguating \"absent because not\nrequested\".",
+ "properties": {
+ "ci": {
+ "description": "Forge CI/PR data was fetched.",
+ "type": "boolean"
+ },
+ "summary": {
+ "description": "LLM branch summaries were generated.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "ci",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "GitRepoInfo": {
+ "description": "Parsed, provider-neutral repository metadata.\n\nThis is the single shape behind the `repo` / `ci.repo` JSON objects of\n`wt list`; serde controls the field rename/skip rules so there is no\nparallel output-only struct.",
+ "properties": {
+ "host": {
+ "description": "Web host for the repository URL.",
+ "type": "string"
+ },
+ "name": {
+ "description": "Repository name.",
+ "type": "string"
+ },
+ "owner": {
+ "description": "Repository owner, organization, or namespace path.",
+ "type": "string"
+ },
+ "project": {
+ "description": "Azure DevOps project name.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "provider": {
+ "$ref": "#/$defs/GitRepoProvider",
+ "description": "Forge provider, or [`GitRepoProvider::Unknown`] for parseable URLs whose\nhost and config do not identify a supported provider."
+ },
+ "remote": {
+ "description": "Local git remote this metadata was derived from. Set only for the\ntop-level `repo` of `wt list`; absent for PR/MR-URL-derived metadata\nsuch as `ci.repo`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "url": {
+ "description": "Repository web URL.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "url",
+ "provider",
+ "host",
+ "owner",
+ "name"
+ ],
+ "type": "object"
+ },
+ "GitRepoProvider": {
+ "description": "Supported forge providers for repository metadata.",
+ "enum": [
+ "github",
+ "gitlab",
+ "gitea",
+ "azure-devops",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "JsonChanges": {
+ "description": "Working-tree change facts.",
+ "properties": {
+ "conflicted": {
+ "description": "Tracked files carry merge conflicts; null while unresolved.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "deleted": {
+ "description": "Has deleted files.",
+ "type": "boolean"
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonDiff"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Lines added/deleted vs HEAD; null while unresolved."
+ },
+ "modified": {
+ "description": "Has modified (unstaged) files.",
+ "type": "boolean"
+ },
+ "renamed": {
+ "description": "Has renamed files.",
+ "type": "boolean"
+ },
+ "staged": {
+ "description": "Has staged files.",
+ "type": "boolean"
+ },
+ "untracked": {
+ "description": "Has untracked files.",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "staged",
+ "modified",
+ "untracked",
+ "renamed",
+ "deleted",
+ "conflicted",
+ "diff"
+ ],
+ "type": "object"
+ },
+ "JsonCheckStatus": {
+ "description": "The pipeline outcomes that reach JSON. [`CiStatus`] carries three more\nthat never appear here, because each is reported by the shape of `checks`\nrather than by a value inside it: `Error` makes both `pr` and `checks`\nunknown, `NoCI` makes `checks` absent, and `Conflicts` leaves `status`\nnull (the conflict itself surfaces as `pr.mergeable`). See\n[`pr_and_checks`].",
+ "enum": [
+ "passed",
+ "running",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "JsonChecks": {
+ "description": "CI pipeline facts.",
+ "properties": {
+ "source": {
+ "$ref": "#/$defs/CiSource",
+ "description": "`\"pr\"` or `\"branch\"` (branch workflow)."
+ },
+ "stale": {
+ "description": "Local HEAD is not what CI ran against.",
+ "type": "boolean"
+ },
+ "status": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonCheckStatus"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Pipeline outcome; null when a conflicts report masked it."
+ }
+ },
+ "required": [
+ "status",
+ "source",
+ "stale"
+ ],
+ "type": "object"
+ },
+ "JsonDefaultBranch": {
+ "description": "Relation to the default branch — independent facts, not the table's\npriority-collapsed symbol (that lives in `display.state`).",
+ "properties": {
+ "ahead": {
+ "description": "Commits ahead; null while unresolved (and for orphans).",
+ "format": "uint",
+ "minimum": 0,
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "behind": {
+ "description": "Commits behind; null while unresolved (and for orphans).",
+ "format": "uint",
+ "minimum": 0,
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "diff": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonDiff"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Lines added/deleted vs the default branch; null while unresolved."
+ },
+ "integration": {
+ "$ref": "#/$defs/Nullable_JsonIntegration",
+ "description": "How committed content is integrated; absent when determined\nnot-integrated, null when undetermined (dirty trees skip the\nexpensive checks)."
+ },
+ "merge_conflicts": {
+ "description": "A merge into the default branch would conflict (local `merge-tree`\nsimulation); null while unresolved.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "orphan": {
+ "description": "No merge-base with the default branch; null while unresolved.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "ahead",
+ "behind",
+ "diff",
+ "orphan",
+ "merge_conflicts"
+ ],
+ "type": "object"
+ },
+ "JsonDevServer": {
+ "description": "Dev server facts.",
+ "properties": {
+ "listening": {
+ "description": "The URL's port is listening; null while unresolved.",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "url": {
+ "description": "URL from the project's `list.url` template.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "url",
+ "listening"
+ ],
+ "type": "object"
+ },
+ "JsonDiff": {
+ "description": "Line diff statistics",
+ "properties": {
+ "added": {
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "deleted": {
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "added",
+ "deleted"
+ ],
+ "type": "object"
+ },
+ "JsonDisplay": {
+ "description": "Presentation strings. Everything here is a rendering of facts that\nappear elsewhere in the item.",
+ "properties": {
+ "columns": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Rendered `[list.custom-columns]` cells keyed by header; empty cells\nomitted.",
+ "type": "object"
+ },
+ "state": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonMainState"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The table's collapsed default-branch state (one value per row,\nhighest priority wins); absent when none applies or unresolved."
+ },
+ "statusline": {
+ "description": "Pre-formatted one-line status with ANSI colors, for prompt tools.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "symbols": {
+ "description": "Raw status glyphs without ANSI (e.g. `\"+!⊂\"`).",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "type": "object"
+ },
+ "JsonHead": {
+ "description": "HEAD commit facts.",
+ "properties": {
+ "committed_at": {
+ "description": "Committer time, RFC 3339 UTC; null when not loaded.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "sha": {
+ "description": "Full commit SHA.",
+ "type": "string"
+ },
+ "short_sha": {
+ "description": "Abbreviated per `core.abbrev`, auto-extended for ambiguous prefixes.",
+ "type": "string"
+ },
+ "subject": {
+ "description": "Commit subject (first line); null when not loaded (e.g. prunable\nworktrees).",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "sha",
+ "short_sha",
+ "subject",
+ "committed_at"
+ ],
+ "type": "object"
+ },
+ "JsonIntegration": {
+ "description": "Why committed content counts as integrated.",
+ "properties": {
+ "reason": {
+ "$ref": "#/$defs/JsonIntegrationReason",
+ "description": "Which check matched."
+ }
+ },
+ "required": [
+ "reason"
+ ],
+ "type": "object"
+ },
+ "JsonIntegrationReason": {
+ "description": "`IntegrationReason` wire values. Schema 2 uses snake_case throughout; the\nenum's own serde rename (kebab-case) is shared with other surfaces, so the\nmapping lives here instead of on the enum.",
+ "enum": [
+ "same_commit",
+ "ancestor",
+ "no_added_changes",
+ "trees_match",
+ "merge_adds_nothing",
+ "patch_id_match"
+ ],
+ "type": "string"
+ },
+ "JsonItemV2": {
+ "description": "One list row: a worktree, a local branch, or a remote-only branch.",
+ "properties": {
+ "branch": {
+ "description": "Branch name; null for a detached-HEAD worktree. Remote rows carry\nthe bare branch name, with the remote in `remote`.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "checks": {
+ "$ref": "#/$defs/Nullable_JsonChecks",
+ "description": "CI pipeline state; absent when no CI exists (or CI wasn't\ncollected), null when the forge fetch failed."
+ },
+ "default_branch": {
+ "$ref": "#/$defs/Nullable_JsonDefaultBranch",
+ "description": "Relation to the default branch; absent on the default branch itself."
+ },
+ "dev_server": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonDevServer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Dev server from the project's `list.url` template; absent when not\nconfigured."
+ },
+ "display": {
+ "$ref": "#/$defs/JsonDisplay",
+ "description": "Presentation: rendered strings for humans and prompt tools."
+ },
+ "head": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonHead"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "HEAD commit; null for unborn branches."
+ },
+ "pr": {
+ "$ref": "#/$defs/Nullable_JsonPr",
+ "description": "Open PR/MR; absent when none exists (or CI wasn't collected), null\nwhen the forge fetch failed."
+ },
+ "remote": {
+ "description": "Remote name for remote-only branch rows; absent on local rows.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "summary": {
+ "$ref": "#/$defs/Nullable_string",
+ "description": "LLM-generated branch summary; absent when summaries are off or none\nwas produced, null while pending."
+ },
+ "upstream": {
+ "$ref": "#/$defs/Nullable_JsonUpstream",
+ "description": "Tracking-branch relation; absent when no upstream is configured,\nnull while unresolved."
+ },
+ "vars": {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Custom variables stored via `wt config state vars`.",
+ "type": "object"
+ },
+ "worktree": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonWorktreeV2"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Worktree facts; absent on branch-only rows."
+ }
+ },
+ "required": [
+ "branch",
+ "head",
+ "display"
+ ],
+ "type": "object"
+ },
+ "JsonMainState": {
+ "description": "[`MainState`] wire values. `MainState::None` renders as no value at all,\nso it has no variant here — `display.state` is absent instead. The\n`Integrated` payload is dropped: the reason it carries is already reported\nas `default_branch.integration.reason`.",
+ "enum": [
+ "is_main",
+ "would_conflict",
+ "empty",
+ "same_commit",
+ "integrated",
+ "orphan",
+ "diverged",
+ "ahead",
+ "behind"
+ ],
+ "type": "string"
+ },
+ "JsonOperation": {
+ "description": "[`InProgressOperation`] wire values. The domain enum's `strum` names are\nthe same strings, but going through an exhaustive match is what makes a\nsixth variant a compile error here instead of a value that appears in\npublished output with nothing to catch it.",
+ "enum": [
+ "merge",
+ "rebase",
+ "cherry_pick",
+ "revert",
+ "bisect"
+ ],
+ "type": "string"
+ },
+ "JsonPr": {
+ "description": "Open PR/MR facts.",
+ "properties": {
+ "mergeable": {
+ "description": "Whether the PR merges cleanly into its target: false when the forge\nreports conflicts, null otherwise (the fetch records only the\nconflicted case).",
+ "type": [
+ "boolean",
+ "null"
+ ]
+ },
+ "number": {
+ "description": "Forge number; null when the forge reported none.",
+ "format": "uint64",
+ "minimum": 0,
+ "type": [
+ "integer",
+ "null"
+ ]
+ },
+ "repo": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/GitRepoInfo"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "The repository the PR/MR targets (the upstream for fork PRs);\nabsent when the URL doesn't parse."
+ },
+ "review": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ReviewState"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Review state; absent when the forge reports no review signal."
+ },
+ "url": {
+ "description": "URL to the PR/MR page; null when the forge reported none.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "number",
+ "url",
+ "mergeable"
+ ],
+ "type": "object"
+ },
+ "JsonReason": {
+ "description": "Reason payload for `locked` / `prunable`.",
+ "properties": {
+ "reason": {
+ "description": "Reason git records; null when none was given.",
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "reason"
+ ],
+ "type": "object"
+ },
+ "JsonRepo": {
+ "description": "Repo-wide facts.",
+ "properties": {
+ "default_branch": {
+ "description": "The branch every `default_branch` object measures against; absent\nwhen detection failed.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "forge": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/GitRepoInfo"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Forge metadata derived from the primary remote; absent when no\nremote URL parses."
+ }
+ },
+ "type": "object"
+ },
+ "JsonUpstream": {
+ "description": "Tracking-branch relation.",
+ "properties": {
+ "ahead": {
+ "description": "Commits ahead of the upstream.",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "behind": {
+ "description": "Commits behind the upstream.",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+ },
+ "branch": {
+ "description": "Branch name on the remote; null when only the remote is known.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "remote": {
+ "description": "Remote name.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "remote",
+ "branch",
+ "ahead",
+ "behind"
+ ],
+ "type": "object"
+ },
+ "JsonWorktreeV2": {
+ "description": "Worktree facts. Location attributes (`locked`, `prunable`,\n`branch_mismatch`, `duplicate_branch`) are independent fields — unlike\nschema 1's single `state`, they can co-occur.",
+ "properties": {
+ "branch_mismatch": {
+ "description": "The checked-out branch doesn't match the branch this worktree was\ncreated for.",
+ "type": "boolean"
+ },
+ "changes": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonChanges"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Working-tree state; null while unresolved."
+ },
+ "current": {
+ "description": "This is the worktree the command ran from.",
+ "type": "boolean"
+ },
+ "detached": {
+ "description": "HEAD is detached.",
+ "type": "boolean"
+ },
+ "duplicate_branch": {
+ "description": "Another worktree has the same branch checked out.",
+ "type": "boolean"
+ },
+ "locked": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonReason"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Present when the worktree is locked."
+ },
+ "main": {
+ "description": "This is the main worktree.",
+ "type": "boolean"
+ },
+ "operation": {
+ "$ref": "#/$defs/Nullable_JsonOperation",
+ "description": "In-progress operation; absent when none, null while unresolved."
+ },
+ "path": {
+ "description": "Filesystem path.",
+ "type": "string"
+ },
+ "previous": {
+ "description": "This was the previous worktree (`wt switch -`).",
+ "type": "boolean"
+ },
+ "prunable": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonReason"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Present when git considers the worktree prunable."
+ }
+ },
+ "required": [
+ "path",
+ "main",
+ "current",
+ "previous",
+ "detached",
+ "branch_mismatch",
+ "duplicate_branch",
+ "changes"
+ ],
+ "type": "object"
+ },
+ "Nullable_JsonChecks": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonChecks"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_JsonDefaultBranch": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonDefaultBranch"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_JsonIntegration": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonIntegration"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_JsonOperation": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonOperation"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_JsonPr": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonPr"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_JsonUpstream": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/JsonUpstream"
+ },
+ {
+ "type": "null"
+ }
+ ]
+ },
+ "Nullable_string": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "ReviewState": {
+ "description": "Review state of a PR/MR.\n\nThe vocabulary matches Claude Code's statusline `pr.review_state` field so\nthe two surfaces never disagree on names. A PR with no review signal at all\n(e.g. GitHub's `reviewDecision` is empty on repos without required\nreviewers and no reviews) carries `None` on [`PrStatus`], not `Pending`,\nso unreviewed branches keep their plain CI colors.",
+ "oneOf": [
+ {
+ "enum": [
+ "approved",
+ "changes_requested",
+ "draft"
+ ],
+ "type": "string"
+ },
+ {
+ "const": "pending",
+ "description": "Review is required before merge (e.g. branch protection) but not given yet",
+ "type": "string"
+ }
+ ]
+ }
+ },
+ "$id": "https://worktrunk.dev/schema/list-v2.json",
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "description": "Root envelope.",
+ "properties": {
+ "collected": {
+ "$ref": "#/$defs/Collected",
+ "description": "Which gated fact families this run requested."
+ },
+ "items": {
+ "description": "One entry per row, in table order.",
+ "items": {
+ "$ref": "#/$defs/JsonItemV2"
+ },
+ "type": "array"
+ },
+ "repo": {
+ "$ref": "#/$defs/JsonRepo",
+ "description": "Repo-wide facts, hoisted out of the items."
+ },
+ "schema": {
+ "description": "Output schema version. The unversioned bare-array format is 1.",
+ "format": "uint32",
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "schema",
+ "repo",
+ "collected",
+ "items"
+ ],
+ "title": "wt list --format=json (schema 2)",
+ "type": "object"
+}
diff --git a/plugins/worktrunk/skills/worktrunk/reference/list.md b/plugins/worktrunk/skills/worktrunk/reference/list.md
index e0815a172..a9fb36ce1 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/list.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/list.md
@@ -291,6 +291,11 @@ $ wt list --format=json | jq '.items[] | select(.display.state == "integrated" o
$ wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'
```
+A JSON Schema for the envelope is published at
+[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).
+It describes what `wt` writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
### Schema 1
The original bare-array format, and the default while unset:
diff --git a/skills/worktrunk/reference/list.md b/skills/worktrunk/reference/list.md
index e0815a172..a9fb36ce1 100644
--- a/skills/worktrunk/reference/list.md
+++ b/skills/worktrunk/reference/list.md
@@ -291,6 +291,11 @@ $ wt list --format=json | jq '.items[] | select(.display.state == "integrated" o
$ wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'
```
+A JSON Schema for the envelope is published at
+[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).
+It describes what `wt` writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
### Schema 1
The original bare-array format, and the default while unset:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index c27d0effb..c4e91f75c 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1053,6 +1053,11 @@ $ wt list --format=json | jq '.items[] | select(.display.state == "integrated" o
$ wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'
```
+A JSON Schema for the envelope is published at
+[worktrunk.dev/schema/list-v2.json](https://worktrunk.dev/schema/list-v2.json).
+It describes what `wt` writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
### Schema 1
The original bare-array format, and the default while unset:
diff --git a/src/commands/list/json_v2.rs b/src/commands/list/json_v2.rs
index f3a727d17..54e626957 100644
--- a/src/commands/list/json_v2.rs
+++ b/src/commands/list/json_v2.rs
@@ -5,6 +5,13 @@
//! quarantined under `display`. Selected by `[list] json-schema = 2`;
//! schema 1 is the bare-array format in [`super::json_output`].
//!
+//! A JSON Schema derived from these types is published at
+//! `https://worktrunk.dev/schema/list-v2.json`, regenerated from
+//! `wt list --print-schema` by `test_docs_are_in_sync`. It is generated under
+//! schemars' *serialize* contract, so `skip_serializing_if` fields are
+//! optional there — adding a field whose absence the schema should allow
+//! needs that attribute, not just an `Option`.
+//!
//! ## The absence rule
//!
//! - **Absent** — nothing to report: not applicable to this row, not
@@ -25,13 +32,14 @@ use std::path::PathBuf;
use schemars::JsonSchema;
use serde::Serialize;
use worktrunk::git::{
- GitRepoInfo, IntegrationReason, IntegrationSignals, Repository, check_integration,
+ GitRepoInfo, InProgressOperation, IntegrationReason, IntegrationSignals, Repository,
+ check_integration,
};
use super::ci_status::{CiSource, CiStatus, PrStatus, ReviewState};
use super::custom_columns::ResolvedCustomColumn;
use super::json_output::{JsonDiff, format_raw_symbols};
-use super::model::{BranchScope, Collected, ItemKind, ListItem, WorktreeData};
+use super::model::{BranchScope, Collected, ItemKind, ListItem, MainState, WorktreeData};
/// Tri-state field encoding the absence rule (see module docs).
#[derive(Debug, Clone, PartialEq)]
@@ -92,6 +100,35 @@ pub struct JsonEnvelope {
pub items: Vec<JsonItemV2>,
}
+/// The published JSON Schema for [`JsonEnvelope`], as a JSON value.
+///
+/// `wt list --print-schema` prints this and `test_docs_are_in_sync` commits it
+/// to `docs/static/schema/list-v2.json`; it lives here so the document and the
+/// types it describes stay in one place, and so `test_schema_accepts_envelopes`
+/// checks the same document that ships.
+///
+/// Generated under schemars' *serialize* contract. The default deserialize
+/// contract marks a `skip_serializing_if` field required — nothing supplies it
+/// on the way in — which would make the schema reject the output it documents.
+pub fn schema_document() -> serde_json::Value {
+ let settings = schemars::generate::SchemaSettings::default().for_serialize();
+ let schema = schemars::SchemaGenerator::new(settings).into_root_schema_for::<JsonEnvelope>();
+
+ let mut value = serde_json::to_value(&schema).expect("schema serializes");
+ let object = value.as_object_mut().expect("schema is an object");
+ // Zola serves docs/static/ at the site root, so this is where the
+ // committed docs/static/schema/list-v2.json is reachable.
+ object.insert(
+ "$id".to_string(),
+ "https://worktrunk.dev/schema/list-v2.json".into(),
+ );
+ object.insert(
+ "title".to_string(),
+ "wt list --format=json (schema 2)".into(),
+ );
+ value
+}
+
/// Repo-wide facts.
#[derive(Debug, Serialize, JsonSchema)]
pub struct JsonRepo {
@@ -213,15 +250,40 @@ pub struct JsonWorktreeV2 {
/// Another worktree has the same branch checked out.
pub duplicate_branch: bool,
- /// In-progress operation: `"rebase"`, `"merge"`, `"cherry_pick"`,
- /// `"revert"`, or `"bisect"`; absent when none, null while unresolved.
+ /// In-progress operation; absent when none, null while unresolved.
#[serde(skip_serializing_if = "Tri::is_absent")]
- pub operation: Tri<&'static str>,
+ pub operation: Tri<JsonOperation>,
/// Working-tree state; null while unresolved.
pub changes: Option<JsonChanges>,
}
+/// [`InProgressOperation`] wire values. The domain enum's `strum` names are
+/// the same strings, but going through an exhaustive match is what makes a
+/// sixth variant a compile error here instead of a value that appears in
+/// published output with nothing to catch it.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum JsonOperation {
+ Merge,
+ Rebase,
+ CherryPick,
+ Revert,
+ Bisect,
+}
+
+impl From<InProgressOperation> for JsonOperation {
+ fn from(operation: InProgressOperation) -> Self {
+ match operation {
+ InProgressOperation::Merge => Self::Merge,
+ InProgressOperation::Rebase => Self::Rebase,
+ InProgressOperation::CherryPick => Self::CherryPick,
+ InProgressOperation::Revert => Self::Revert,
+ InProgressOperation::Bisect => Self::Bisect,
+ }
+ }
+}
+
/// Reason payload for `locked` / `prunable`.
#[derive(Debug, Serialize, JsonSchema)]
pub struct JsonReason {
@@ -278,10 +340,35 @@ pub struct JsonDefaultBranch {
/// Why committed content counts as integrated.
#[derive(Debug, Serialize, JsonSchema)]
pub struct JsonIntegration {
- /// Which check matched: `"same_commit"`, `"ancestor"`,
- /// `"no_added_changes"`, `"trees_match"`, `"merge_adds_nothing"`, or
- /// `"patch_id_match"`.
- pub reason: &'static str,
+ /// Which check matched.
+ pub reason: JsonIntegrationReason,
+}
+
+/// `IntegrationReason` wire values. Schema 2 uses snake_case throughout; the
+/// enum's own serde rename (kebab-case) is shared with other surfaces, so the
+/// mapping lives here instead of on the enum.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum JsonIntegrationReason {
+ SameCommit,
+ Ancestor,
+ NoAddedChanges,
+ TreesMatch,
+ MergeAddsNothing,
+ PatchIdMatch,
+}
+
+impl From<IntegrationReason> for JsonIntegrationReason {
+ fn from(reason: IntegrationReason) -> Self {
+ match reason {
+ IntegrationReason::SameCommit => Self::SameCommit,
+ IntegrationReason::Ancestor => Self::Ancestor,
+ IntegrationReason::NoAddedChanges => Self::NoAddedChanges,
+ IntegrationReason::TreesMatch => Self::TreesMatch,
+ IntegrationReason::MergeAddsNothing => Self::MergeAddsNothing,
+ IntegrationReason::PatchIdMatch => Self::PatchIdMatch,
+ }
+ }
}
/// Tracking-branch relation.
@@ -327,9 +414,8 @@ pub struct JsonPr {
/// CI pipeline facts.
#[derive(Debug, PartialEq, Serialize, JsonSchema)]
pub struct JsonChecks {
- /// `"passed"`, `"running"`, or `"failed"`; null when a conflicts report
- /// masked the pipeline outcome.
- pub status: Option<&'static str>,
+ /// Pipeline outcome; null when a conflicts report masked it.
+ pub status: Option<JsonCheckStatus>,
/// `"pr"` or `"branch"` (branch workflow).
pub source: CiSource,
@@ -338,6 +424,33 @@ pub struct JsonChecks {
pub stale: bool,
}
+/// The pipeline outcomes that reach JSON. [`CiStatus`] carries three more
+/// that never appear here, because each is reported by the shape of `checks`
+/// rather than by a value inside it: `Error` makes both `pr` and `checks`
+/// unknown, `NoCI` makes `checks` absent, and `Conflicts` leaves `status`
+/// null (the conflict itself surfaces as `pr.mergeable`). See
+/// [`pr_and_checks`].
+#[derive(Debug, PartialEq, Serialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum JsonCheckStatus {
+ Passed,
+ Running,
+ Failed,
+}
+
+impl JsonCheckStatus {
+ /// `None` for the statuses the shape of `checks` reports instead (see the
+ /// type docs). `Error` and `NoCI` never reach a constructed `JsonChecks`.
+ fn from_ci_status(status: CiStatus) -> Option<Self> {
+ match status {
+ CiStatus::Passed => Some(Self::Passed),
+ CiStatus::Running => Some(Self::Running),
+ CiStatus::Failed => Some(Self::Failed),
+ CiStatus::Conflicts | CiStatus::NoCI | CiStatus::Error => None,
+ }
+ }
+}
+
/// Dev server facts.
#[derive(Debug, Serialize, JsonSchema)]
pub struct JsonDevServer {
@@ -355,7 +468,7 @@ pub struct JsonDisplay {
/// The table's collapsed default-branch state (one value per row,
/// highest priority wins); absent when none applies or unresolved.
#[serde(skip_serializing_if = "Option::is_none")]
- pub state: Option<&'static str>,
+ pub state: Option<JsonMainState>,
/// Raw status glyphs without ANSI (e.g. `"+!⊂"`).
#[serde(skip_serializing_if = "Option::is_none")]
@@ -371,17 +484,39 @@ pub struct JsonDisplay {
pub columns: BTreeMap<String, String>,
}
-/// `IntegrationReason` wire values. Schema 2 uses snake_case throughout;
-/// the enum's own serde rename (kebab-case) is shared with other surfaces,
-/// so the mapping lives here instead of on the enum.
-fn integration_reason_str(reason: IntegrationReason) -> &'static str {
- match reason {
- IntegrationReason::SameCommit => "same_commit",
- IntegrationReason::Ancestor => "ancestor",
- IntegrationReason::NoAddedChanges => "no_added_changes",
- IntegrationReason::TreesMatch => "trees_match",
- IntegrationReason::MergeAddsNothing => "merge_adds_nothing",
- IntegrationReason::PatchIdMatch => "patch_id_match",
+/// [`MainState`] wire values. `MainState::None` renders as no value at all,
+/// so it has no variant here — `display.state` is absent instead. The
+/// `Integrated` payload is dropped: the reason it carries is already reported
+/// as `default_branch.integration.reason`.
+#[derive(Debug, Serialize, JsonSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum JsonMainState {
+ IsMain,
+ WouldConflict,
+ Empty,
+ SameCommit,
+ Integrated,
+ Orphan,
+ Diverged,
+ Ahead,
+ Behind,
+}
+
+impl JsonMainState {
+ /// `None` for [`MainState::None`], which the table renders as no symbol.
+ fn from_main_state(state: MainState) -> Option<Self> {
+ match state {
+ MainState::None => None,
+ MainState::IsMain => Some(Self::IsMain),
+ MainState::WouldConflict => Some(Self::WouldConflict),
+ MainState::Empty => Some(Self::Empty),
+ MainState::SameCommit => Some(Self::SameCommit),
+ MainState::Integrated(_) => Some(Self::Integrated),
+ MainState::Orphan => Some(Self::Orphan),
+ MainState::Diverged => Some(Self::Diverged),
+ MainState::Ahead => Some(Self::Ahead),
+ MainState::Behind => Some(Self::Behind),
+ }
}
}
@@ -542,7 +677,10 @@ impl JsonItemV2 {
let columns = columns_map(custom_columns, &item.custom_values);
let display = JsonDisplay {
- state: item.status_symbols.main_state.and_then(|s| s.as_json_str()),
+ state: item
+ .status_symbols
+ .main_state
+ .and_then(JsonMainState::from_main_state),
symbols: Some(format_raw_symbols(&item.status_symbols)).filter(|s| !s.is_empty()),
statusline: item.statusline.clone(),
columns,
@@ -655,7 +793,7 @@ fn json_default_branch(item: &ListItem, worktree_data: Option<&WorktreeData>) ->
// seeded: every seed points the negative direction, so a match can
// only come from a computed signal.
Some(reason) => Tri::Known(JsonIntegration {
- reason: integration_reason_str(reason),
+ reason: reason.into(),
}),
// "Not integrated" is a determination only when every signal was
// genuinely computed — a seeded signal means a probe never ran.
@@ -695,18 +833,16 @@ fn pr_and_checks(
// the pipeline did.
CiStatus::Error => return (Tri::Unknown, Tri::Unknown),
CiStatus::NoCI => Tri::Absent,
- CiStatus::Conflicts => Tri::Known(JsonChecks {
- // The fetch discards the pipeline outcome when the forge
- // reports conflicts (see `pr.mergeable`).
- status: None,
- source: status.source,
- stale: status.is_stale,
- }),
- CiStatus::Passed | CiStatus::Running | CiStatus::Failed => Tri::Known(JsonChecks {
- status: Some(status.ci_status.into()),
- source: status.source,
- stale: status.is_stale,
- }),
+ // Conflicts lands here with a null `status`: the fetch discards the
+ // pipeline outcome when the forge reports conflicts, which surfaces
+ // as `pr.mergeable` instead.
+ CiStatus::Conflicts | CiStatus::Passed | CiStatus::Running | CiStatus::Failed => {
+ Tri::Known(JsonChecks {
+ status: JsonCheckStatus::from_ci_status(status.ci_status),
+ source: status.source,
+ stale: status.is_stale,
+ })
+ }
};
let pr = if status.source == CiSource::PullRequest {
@@ -876,7 +1012,7 @@ mod tests {
assert_eq!(
checks,
Tri::Known(JsonChecks {
- status: Some("passed"),
+ status: Some(JsonCheckStatus::Passed),
source: CiSource::PullRequest,
stale: true,
})
@@ -927,7 +1063,7 @@ mod tests {
assert_eq!(
checks,
Tri::Known(JsonChecks {
- status: Some("failed"),
+ status: Some(JsonCheckStatus::Failed),
source: CiSource::Branch,
stale: false,
})
@@ -1125,18 +1261,10 @@ mod tests {
item
}
- /// The derived schema must generate cleanly — `Tri<T>`'s JsonSchema
- /// delegation to `Option<T>` is only exercised here until the schema
- /// export ships.
- #[test]
- fn test_schema_generates() {
- let schema = schemars::schema_for!(JsonEnvelope);
- let json = serde_json::to_value(&schema).unwrap();
- assert!(json["properties"]["items"].is_object());
- }
-
+ /// `JsonIntegrationReason` covers every `IntegrationReason`, under the
+ /// snake_case wire names schema 2 publishes.
#[test]
- fn test_integration_reason_str_covers_every_reason() {
+ fn test_integration_reason_wire_names() {
let cases = [
(IntegrationReason::SameCommit, "same_commit"),
(IntegrationReason::Ancestor, "ancestor"),
@@ -1146,7 +1274,39 @@ mod tests {
(IntegrationReason::PatchIdMatch, "patch_id_match"),
];
for (reason, expected) in cases {
- assert_eq!(integration_reason_str(reason), expected);
+ let wire = serde_json::to_value(JsonIntegrationReason::from(reason)).unwrap();
+ assert_eq!(wire, expected);
+ }
+ }
+
+ /// Every [`MainState`] the table can show reaches `display.state` with a
+ /// wire name, and `None` reaches it as absent.
+ #[test]
+ fn test_main_state_wire_names() {
+ let cases = [
+ (MainState::None, None),
+ (MainState::IsMain, Some("is_main")),
+ (MainState::WouldConflict, Some("would_conflict")),
+ (MainState::Empty, Some("empty")),
+ (MainState::SameCommit, Some("same_commit")),
+ (
+ MainState::Integrated(IntegrationReason::Ancestor),
+ Some("integrated"),
+ ),
+ (MainState::Orphan, Some("orphan")),
+ (MainState::Diverged, Some("diverged")),
+ (MainState::Ahead, Some("ahead")),
+ (MainState::Behind, Some("behind")),
+ ];
+ for (state, expected) in cases {
+ let wire = JsonMainState::from_main_state(state).map(|s| {
+ serde_json::to_value(s)
+ .unwrap()
+ .as_str()
+ .unwrap()
+ .to_string()
+ });
+ assert_eq!(wire.as_deref(), expected, "for {state:?}");
}
}
@@ -1265,6 +1425,256 @@ mod tests {
);
}
+ /// Every path in `value` holding a non-null value, with array indices
+ /// collapsed to `*` so a path matches whichever battery row supplies it.
+ fn non_null_paths(value: &serde_json::Value) -> std::collections::BTreeSet<String> {
+ fn walk(
+ value: &serde_json::Value,
+ path: &str,
+ out: &mut std::collections::BTreeSet<String>,
+ ) {
+ if value.is_null() {
+ return;
+ }
+ out.insert(path.to_string());
+ match value {
+ serde_json::Value::Object(map) => {
+ for (key, child) in map {
+ walk(child, &format!("{path}/{key}"), out);
+ }
+ }
+ serde_json::Value::Array(entries) => {
+ for child in entries {
+ walk(child, &format!("{path}/*"), out);
+ }
+ }
+ _ => {}
+ }
+ }
+ let mut out = std::collections::BTreeSet::new();
+ walk(value, "", &mut out);
+ out
+ }
+
+ /// The published schema must accept what `wt list --format=json`
+ /// actually writes.
+ ///
+ /// schemars derives the document from the types without ever seeing
+ /// output, so nothing else pins the two together. This caught the schema
+ /// being generated under the deserialize contract, where every
+ /// `skip_serializing_if` field is required and the document rejects its
+ /// own output.
+ ///
+ /// The battery walks the axes the schema is most likely to get wrong:
+ /// every `CiStatus` (which drives the `pr`/`checks` tri-state arms and
+ /// `JsonCheckStatus`) and every `MainState` (which drives
+ /// `JsonMainState`).
+ #[test]
+ fn test_schema_accepts_envelopes() {
+ let collected = Collected {
+ ci: true,
+ summary: true,
+ };
+
+ let mut items = Vec::new();
+
+ // Bare row: every gated family absent.
+ items.push(convert(
+ &item_with("bare"),
+ Collected {
+ ci: false,
+ summary: false,
+ },
+ ));
+
+ // A fully-populated worktree row. `worktree` and everything under it
+ // appear nowhere else in the battery, and each field left at its
+ // default takes one more type out of the validator's reach: git
+ // records a lock with or without a message, so both `JsonReason` arms
+ // need a row.
+ items.push(convert(
+ &worktree_item(
+ "worktree",
+ WorktreeData {
+ git_operation: Some(Some(InProgressOperation::Rebase)),
+ locked: Some("manual lock".to_string()),
+ prunable: Some(String::new()),
+ working_tree_status: Some(Default::default()),
+ has_conflicts: Some(true),
+ working_tree_diff: Some(worktrunk::git::LineDiff {
+ added: 3,
+ deleted: 1,
+ }),
+ ..Default::default()
+ },
+ ),
+ collected,
+ ));
+
+ // An integrated row with an upstream and a dev server. Without the
+ // signals `check_integration` returns `None` and `integration` is
+ // null throughout, so `JsonIntegration` and `JsonIntegrationReason`
+ // would never meet a real object.
+ let mut integrated = item_with("integrated");
+ integrated.is_ancestor = Some(true);
+ integrated.is_orphan = Some(false);
+ integrated.has_file_changes = Some(false);
+ integrated.committed_trees_match = Some(true);
+ integrated.would_merge_add = Some(false);
+ integrated.is_patch_id_match = Some(true);
+ integrated.upstream = Some(UpstreamStatus {
+ remote: Some("origin".to_string()),
+ upstream_short: Some("origin/integrated".to_string()),
+ ahead: 2,
+ behind: 1,
+ });
+ integrated.url = Some("http://127.0.0.1:3000".to_string());
+ integrated.url_active = Some(true);
+ items.push(convert(&integrated, collected));
+
+ // Every CI status, over both sources.
+ for source in [CiSource::PullRequest, CiSource::Branch] {
+ for ci in [
+ CiStatus::Passed,
+ CiStatus::Running,
+ CiStatus::Failed,
+ CiStatus::Conflicts,
+ CiStatus::NoCI,
+ CiStatus::Error,
+ ] {
+ let mut item = item_with("ci");
+ item.pr_status = Some(Some(PrStatus {
+ url: Some("https://github.com/org/repo/pull/7".to_string()),
+ number: Some(PrRef::pr(7)),
+ review_state: Some(ReviewState::Approved),
+ ..pr_status(ci, source)
+ }));
+ items.push(convert(&item, collected));
+ }
+ }
+
+ // Every collapsed default-branch state.
+ for state in [
+ MainState::None,
+ MainState::IsMain,
+ MainState::WouldConflict,
+ MainState::Empty,
+ MainState::SameCommit,
+ MainState::Integrated(IntegrationReason::PatchIdMatch),
+ MainState::Orphan,
+ MainState::Diverged,
+ MainState::Ahead,
+ MainState::Behind,
+ ] {
+ let mut item = item_with("state");
+ item.status_symbols.main_state = Some(state);
+ items.push(convert(&item, collected));
+ }
+
+ // Requested-but-undetermined: the null arm of the absence rule.
+ let mut seeded = item_with("seeded");
+ seeded.summary = Some(None);
+ seeded.pr_status = Some(None);
+ items.push(convert(&seeded, collected));
+
+ let envelope = JsonEnvelope {
+ schema: 2,
+ repo: JsonRepo {
+ default_branch: Some("main".to_string()),
+ // `forge` is the only place `GitRepoInfo` and
+ // `GitRepoProvider` appear in the document.
+ forge: Some(GitRepoInfo {
+ url: "https://github.com/org/repo".to_string(),
+ provider: worktrunk::git::GitRepoProvider::GitHub,
+ host: "github.com".to_string(),
+ owner: "org".to_string(),
+ name: "repo".to_string(),
+ project: None,
+ remote: Some("origin".to_string()),
+ }),
+ },
+ collected,
+ items,
+ };
+
+ let schema = schema_document();
+ let validator = jsonschema::validator_for(&schema).expect("schema compiles");
+ let instance = serde_json::to_value(&envelope).unwrap();
+
+ // Validating proves nothing about a type the battery never
+ // instantiates: a document can accept an envelope while whole
+ // subtrees of it go unexercised. Pin every type the document defines
+ // to a path that must carry a real value, so a new `Json*` type fails
+ // here until the battery reaches it, and a row that stops populating
+ // one fails too.
+ let reached = non_null_paths(&instance);
+ let pinned: &[(&str, &str)] = &[
+ ("CiSource", "/items/*/checks/source"),
+ ("Collected", "/collected"),
+ ("GitRepoInfo", "/repo/forge"),
+ ("GitRepoProvider", "/repo/forge/provider"),
+ ("JsonChanges", "/items/*/worktree/changes"),
+ ("JsonCheckStatus", "/items/*/checks/status"),
+ ("JsonChecks", "/items/*/checks"),
+ ("JsonDefaultBranch", "/items/*/default_branch"),
+ ("JsonDevServer", "/items/*/dev_server"),
+ ("JsonDiff", "/items/*/worktree/changes/diff"),
+ ("JsonDisplay", "/items/*/display"),
+ ("JsonHead", "/items/*/head"),
+ ("JsonIntegration", "/items/*/default_branch/integration"),
+ (
+ "JsonIntegrationReason",
+ "/items/*/default_branch/integration/reason",
+ ),
+ ("JsonItemV2", "/items/*"),
+ ("JsonMainState", "/items/*/display/state"),
+ ("JsonOperation", "/items/*/worktree/operation"),
+ ("JsonPr", "/items/*/pr"),
+ ("JsonReason", "/items/*/worktree/locked"),
+ ("JsonRepo", "/repo"),
+ ("JsonUpstream", "/items/*/upstream"),
+ ("JsonWorktreeV2", "/items/*/worktree"),
+ ("ReviewState", "/items/*/pr/review"),
+ ];
+
+ // `Nullable_X` is a schemars wrapper over `X`, which carries its own
+ // row, so it needs no path of its own.
+ let defined: Vec<&str> = schema["$defs"]
+ .as_object()
+ .unwrap()
+ .keys()
+ .map(String::as_str)
+ .filter(|name| !name.starts_with("Nullable_"))
+ .collect();
+ let unpinned: Vec<&str> = defined
+ .iter()
+ .copied()
+ .filter(|name| !pinned.iter().any(|(pinned_name, _)| pinned_name == name))
+ .collect();
+ assert!(
+ unpinned.is_empty(),
+ "published types with no path pinned here: {unpinned:?}"
+ );
+
+ let unreached: Vec<&str> = pinned
+ .iter()
+ .filter(|(_, path)| !reached.contains(*path))
+ .map(|(name, _)| *name)
+ .collect();
+ assert!(
+ unreached.is_empty(),
+ "published types the battery never instantiates: {unreached:?}"
+ );
+ let errors: Vec<String> = validator
+ .iter_errors(&instance)
+ .map(|e| format!("{}: {e}", e.instance_path()))
+ .collect();
+ assert!(
+ errors.is_empty(),
+ "schema rejected its own output:\n{errors:#?}"
+ );
+ }
+
#[test]
fn test_envelope_snapshot_shape() {
// Serialize a minimal envelope to pin the top-level shape.
diff --git a/src/help.rs b/src/help.rs
index 910fc0c1a..69a9c1e7b 100644
--- a/src/help.rs
+++ b/src/help.rs
@@ -180,6 +180,13 @@ pub fn maybe_handle_help_with_pager(alias_help_context: Option<crate::commands::
process::exit(0);
}
+ // Check for --print-schema flag (output the JSON Schema for a command's
+ // --format=json payload)
+ if args.iter().any(|a| a == "--print-schema") {
+ handle_print_schema(&args);
+ process::exit(0);
+ }
+
// Check for --help-description flag (output meta description for docs)
if args.iter().any(|a| a == "--help-description") {
handle_help_description(&args);
@@ -431,6 +438,41 @@ fn handle_help_description(args: &[String]) {
print!("{description}");
}
+/// Print the JSON Schema for a command's `--format=json` payload.
+///
+/// A developer entry point in the same family as `--help-page`: it exists so
+/// the docs sync (`test_docs_are_in_sync`) can regenerate a committed schema
+/// file by running the binary, which is the only way a `tests/` integration
+/// test can reach a type in the bin-only `crate::commands` tree.
+///
+/// One command has a schema today, because one payload is versioned. The
+/// subcommand is the axis a second would arrive on.
+fn handle_print_schema(args: &[String]) {
+ let subcommand = args
+ .iter()
+ .filter(|a| !a.starts_with('-') && !a.ends_with("/wt"))
+ .find(|a| !a.contains("target/") && *a != "wt");
+
+ let Some(subcommand) = subcommand else {
+ eprintln!(
+ "Usage: wt <command> --print-schema
+Commands with schemas: list"
+ );
+ process::exit(2);
+ };
+
+ if subcommand != "list" {
+ eprintln!("No JSON schema for '{subcommand}'; commands with schemas: list");
+ process::exit(2);
+ }
+
+ let schema = crate::commands::list::json_v2::schema_document();
+ println!(
+ "{}",
+ serde_json::to_string_pretty(&schema).expect("schema serializes")
+ );
+}
+
/// Generate a full documentation page for a command.
///
/// Output format:
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 964af2ecf..27196fc28 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -358,3 +358,30 @@ fn test_nested_subcommand_suggestion(
assert_cmd_snapshot!(test_name, cmd);
});
}
+
+/// `--print-schema` names one command's `--format=json` payload, so an
+/// unrecognized or missing command is a usage error rather than a silent
+/// empty document. `test_docs_are_in_sync` treats a non-zero exit as a sync
+/// failure, which is what keeps a renamed command from quietly publishing
+/// nothing.
+#[test]
+fn test_print_schema_rejects_unknown_command() {
+ for args in [&["--print-schema"][..], &["merge", "--print-schema"][..]] {
+ let output = wt_command()
+ .args(args)
+ .output()
+ .unwrap_or_else(|e| panic!("failed to run wt {args:?}: {e}"));
+
+ assert_eq!(
+ output.status.code(),
+ Some(2),
+ "wt {args:?} should exit 2; stderr: {:?}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ assert!(
+ output.stdout.is_empty(),
+ "wt {args:?} should print no schema, but stdout was: {:?}",
+ String::from_utf8_lossy(&output.stdout)
+ );
+ }
+}
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index eecbf4ccb..e44afed3c 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -2578,6 +2578,52 @@ fn sync_cli_mod_example_bodies(project_root: &Path) -> (Vec<String>, Vec<String>
(errors, updated_files)
}
+/// Generate `docs/static/schema/list-v2.json` from `wt list --print-schema`,
+/// publishing it at the `$id` the document carries
+/// (`https://worktrunk.dev/schema/list-v2.json`).
+///
+/// Shells out rather than calling `schema_for!` directly: the `JsonEnvelope`
+/// it derives from lives in the bin-only `crate::commands` tree, which an
+/// integration test can't import. Same reason `sync_command_pages` runs
+/// `--help-page`.
+///
+/// A schemars upgrade rewrites this file. That shows up here as an ordinary
+/// out-of-sync failure, which is the intent — a consumer's schema changing
+/// under a dependency bump should be a reviewed diff.
+fn sync_json_schema(project_root: &Path) -> (Vec<String>, Vec<String>) {
+ let mut errors = Vec::new();
+ let mut updated_files = Vec::new();
+
+ let output = wt_command()
+ .args(["list", "--print-schema"])
+ .current_dir(project_root)
+ .output()
+ .expect("Failed to run wt list --print-schema");
+
+ if !output.status.success() {
+ errors.push(format!(
+ "'wt list --print-schema' failed (exit {}): {}",
+ output.status.code().unwrap_or(-1),
+ String::from_utf8_lossy(&output.stderr)
+ ));
+ return (errors, updated_files);
+ }
+
+ let generated = String::from_utf8_lossy(&output.stdout).to_string();
+ if generated.trim().is_empty() {
+ errors.push("Empty output from 'wt list --print-schema'".to_string());
+ return (errors, updated_files);
+ }
+
+ let rel_path = "docs/static/schema/list-v2.json";
+ let dst = project_root.join(rel_path);
+ if fs::read_to_string(&dst).unwrap_or_default() != generated {
+ write_tracked(&dst, &generated, rel_path, &mut updated_files);
+ }
+
+ (errors, updated_files)
+}
+
/// Generate `docs/static/llms.txt` from `docs/content/*.md` front-matter,
/// following the llms.txt spec (https://llmstxt.org/): H1, blockquote summary,
/// optional intro prose, H2 section headings with bulleted link lists.
@@ -2817,6 +2863,13 @@ fn test_docs_are_in_sync() {
let (llms_errors, llms_files) = sync_llms_txt(project_root);
tag("llms.txt", llms_errors, llms_files);
+ // Step 5b: Generate docs/static/schema/list-v2.json from the derived
+ // schema. Grouped here because it also writes docs/static/, but it reads
+ // the binary rather than the markdown pipeline, so it has no ordering
+ // dependency on the steps above.
+ let (schema_errors, schema_files) = sync_json_schema(project_root);
+ tag("json schema", schema_errors, schema_files);
+
// Step 6: Sync README from the now-fresh docs files. Runs last because
// section extraction depends on docs/content/*.md being current.
let readme_path = project_root.join("README.md");
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index ede4c27ad..c136ef943 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -365,6 +365,11 @@ and the per-item repo moves to the envelope's repo.forge.
  # Worktrees ahead of upstream (needs pushing)
  wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'
+A JSON Schema for the envelope is published at
+worktrunk.dev/schema/list-v2.json.
+It describes what wt writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
Schema 1
The original bare-array format, and the default while unset:
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index 49b8bb009..7499e2ad4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -461,6 +461,11 @@ and the per-item repo moves to the envelope's repo.forge.
  # Worktrees ahead of upstream (needs pushing)
  wt list --format=json | jq '.items[] | select(.upstream.ahead > 0) | .branch'
+A JSON Schema for the envelope is published at
+worktrunk.dev/schema/list-v2.json.
+It describes what wt writes, so a field the absence rule can omit is
+optional there rather than required-and-null.
+
Schema 1
The original bare-array format, and the default while unset: