refactor: add json schema and improve JSON output

Author: soywod

CHANGELOG.md

@@ -6,8 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- Added `imap.alpn`, `jmap.alpn`, `caldav.alpn` and `carddav.alpn`, the ALPN identifiers offered during the TLS handshake.
+
+  Unset takes the protocol default the backend already used, `["imap"]` over IMAP and `["http/1.1"]` over JMAP and WebDAV, so nothing moves for a configuration that does not name it. An empty list skips ALPN negotiation, for a server whose TLS terminator rejects the handshake carrying one, and a non-empty list replaces the default. Only rustls reads it, native-tls having no ALPN.
+
+- Added `carillon json-schema`, generating the JSON Schema of a command's `--json` output.
+
+  It writes one schema to stdout, or one file per command into `--dir`. `check` and `configure` are the two commands that print data.
+
 ### Changed
 
+- Expanded the leading tilde and the shell variables in `imap.tls.cert`, `jmap.tls.cert`, `caldav.tls.cert` and `carddav.tls.cert`.
+
+  `cert = "~/certs/example.pem"` used to be read as the literal relative path `./~/certs/example.pem`, so the certificate was never found. It is now expanded when the file is read, as every other path in the configuration already was.
+
+
 - **BREAKING**: renamed `completions` and `manuals` to `completion` and `manual`, the plural staying as a hidden alias.
 - Spawned a credential command once per checked account, rather than once per backend naming it.
 

Cargo.lock

@@ -52,8 +52,10 @@ notify-rust = { version = "4", default-features = false, features = ["d"] }
 pimalaya-cli = { version = "0.2", default-features = false, features = ["terminal", "prompt", "spinner", "wizard"] }
 pimalaya-config = { version = "0.2", default-features = false, features = ["toml", "secret"] }
 pimalaya-stream = { version = "0.3", default-features = false, features = ["std"] }
+schemars = "1"
 secrecy = { version = "0.10", features = ["serde"] }
 serde = { version = "1", features = ["derive"] }
+serde_json = "1"
 shellexpand = "3.1"
 subst = "0.3"
 url = { version = "2.2", features = ["serde"] }

Cargo.toml

@@ -131,7 +131,7 @@ Force a backend on an account declaring several:
 carillon -b jmap watch
 ```
 
-Every command and every flag is documented behind `--help`. Man pages and shell completions are generated by `carillon manual --dir <DIR>` and `carillon completion --dir <DIR>`.
+Every command and every flag is documented behind `--help`. Man pages, shell completions and the JSON Schemas of the `--json` output are generated by `carillon manual --dir <DIR>`, `carillon completion --dir <DIR>` and `carillon json-schema --dir <DIR>`.
 
 Logs go to stderr, so they can be redirected to a file while the command output stays on stdout:
 

README.md

@@ -0,0 +1,28 @@
+---
+cairn: delta
+change: alpn-under-each-backend
+---
+
+## ADDED Requirements
+
+### Requirement: The TLS handshake is configured under its backend
+Every backend speaking TLS SHALL carry a `tls` table and an `alpn` key of its own, and the runtime TLS handle SHALL be built through one conversion taking that list, so a connection cannot be opened without saying what it negotiates. `alpn` SHALL be a list of ALPN identifiers: unset SHALL take the default the backend's client crate owns (`["imap"]` over IMAP, `["http/1.1"]` over JMAP and WebDAV), an empty list SHALL skip ALPN negotiation, and a non-empty list SHALL replace the default. Only rustls SHALL read it, native-tls having no ALPN. Every path in a `tls` table SHALL be expanded when the file is read, so a leading tilde or a shell variable names the same thing there as everywhere else.
+
+#### Scenario: A server that refuses the handshake carrying an ALPN
+- **GIVEN** a CalDAV server whose TLS terminator rejects a `ClientHello` offering `http/1.1`
+- **WHEN** the account sets `caldav.alpn = []`
+- **THEN** the connection is opened with no ALPN extension at all
+
+#### Scenario: A configuration naming no ALPN
+- **GIVEN** an account carrying no `alpn` key
+- **WHEN** it is watched
+- **THEN** the backend offers the default its client crate owns, unchanged from before the key existed, and nothing is written back into a generated document
+
+#### Scenario: A certificate under the home directory
+- **GIVEN** `imap.tls.cert = "~/certs/example.pem"`
+- **WHEN** the configuration is read
+- **THEN** the path is expanded against the home directory rather than read as a relative `./~/certs/example.pem`
+
+## MODIFIED Requirements
+
+## REMOVED Requirements

cairn/changes/alpn-under-each-backend/delta.md

@@ -0,0 +1,23 @@
+---
+cairn: change
+id: alpn-under-each-backend
+status: landed
+created: 2026-08-29
+---
+
+# Give every TLS backend its own ALPN key
+
+## Why
+
+Three call sites built a `Tls` out of a `TlsConfig` and then patched the ALPN list back into it, because `From<TlsConfig> for Tls` hardcoded an empty one. Nothing forced a fourth call site to do the same, so the next connection added would have negotiated no ALPN and nobody would have noticed until a server that needs one refused it.
+
+The three lists were also literals in the source, which is the wrong place: `vec!["imap"]` and `vec!["http/1.1"]` are exactly what a configuration key should be able to override. A server whose TLS terminator rejects a handshake carrying `http/1.1` has no way to say so, and the rest of the family (himalaya, himalaya-tui, cardamum, neverest) already exposes that key.
+
+While reading the same table, `tls.cert` turned out to be the one path in the configuration that is not expanded when the file is read, so `cert = "~/certs/example.pem"` names a relative `./~/certs` directory that does not exist.
+
+## What
+
+- `From<TlsConfig> for Tls` becomes `TlsConfig::into_tls(self, alpn)`, the signature himalaya, himalaya-tui, cardamum and neverest already carry. A call site now has to say what it negotiates.
+- `imap`, `jmap`, `caldav` and `carddav` each gain an `alpn: Option<Vec<String>>` key. Unset takes the default its client crate owns, `[]` skips ALPN, and a non-empty list replaces the default. Maildir gains none: it opens no socket.
+- `tls.cert` is expanded at deserialize, through a private `opt_shell_expanded_path` carrying a TODO for the shared helper pimalaya-config has not shipped yet.
+- The DAV wizard's test connection opens with the same profile a watch does, rather than with its own literal.

cairn/changes/alpn-under-each-backend/proposal.md

@@ -0,0 +1,11 @@
+---
+cairn: tasks
+change: alpn-under-each-backend
+---
+
+- [x] Replace `From<TlsConfig> for Tls` with `TlsConfig::into_tls`
+- [x] Add `alpn` to the IMAP, JMAP, CalDAV and CardDAV blocks
+- [x] Feed it through `into_tls` at every call site, the wizard included
+- [x] Expand `tls.cert` at deserialize
+- [x] Document the keys in the sample and cover them with round-trip tests
+- [x] Fold the delta into the spec and log the change

cairn/changes/alpn-under-each-backend/tasks.md

@@ -0,0 +1,23 @@
+---
+cairn: delta
+change: camel-case-json-output
+---
+
+## ADDED Requirements
+
+## MODIFIED Requirements
+
+### Requirement: Every printed output has a published schema
+Every command handing data to the printer SHALL return a named `*Output` type deriving `Display`, `Serialize` and `JsonSchema`, and `carillon json-schema` SHALL publish the schema of each, keyed by the command path joined with hyphens and prefixed `carillon-`. Every type reaching the printer SHALL spell its keys in camelCase, declared as `rename_all` on the type, which is the convention of the `--json` output alone and not of the TOML configuration, whose keys stay kebab-case. A command that writes files rather than data SHALL stay out of the registry, and `watch` SHALL print nothing, reporting through its hooks alone.
+
+#### Scenario: A consumer reading the check payload
+- **GIVEN** `carillon json-schema carillon-check`
+- **WHEN** it runs
+- **THEN** the JSON Schema of the `--json` payload of `carillon check` is printed on stdout
+
+#### Scenario: Every schema at once
+- **GIVEN** `carillon json-schema --dir <DIR>`
+- **WHEN** it runs
+- **THEN** one file per command is written there, the directory being created if it is not already
+
+## REMOVED Requirements

cairn/changes/camel-case-json-output/delta.md

@@ -0,0 +1,18 @@
+---
+cairn: change
+id: camel-case-json-output
+status: landed
+created: 2026-08-29
+---
+
+# Print JSON keys in camelCase
+
+## Why
+
+The `--json` output of every Pimalaya CLI is moving to camelCase keys, matching the wire formats these tools wrap (JMAP, the Google and Microsoft APIs, JSCalendar and JSContact) and sparing a consumer the `."key-name"` quoting jq needs for a hyphenated key. carillon is pre-1.0 and its output types carry no `rename_all` at all, so they emit serde's default snake_case and the convention is unstated in the source.
+
+## What
+
+- `CheckOutput`, `BackendCheck` and `ConfigureOutput`, which is every type reaching `printer.out`, carry `#[serde(rename_all = "camelCase")]`, so the convention is declared where the payload is defined rather than inferred from field names that happen to be single words.
+- No compatibility alias: carillon switches now rather than carrying two spellings.
+- The TOML configuration is untouched. The `rename_all = "kebab-case"` throughout `src/config.rs` is the config vocabulary, which is a different surface with a different convention.

cairn/changes/camel-case-json-output/proposal.md

@@ -0,0 +1,9 @@
+---
+cairn: tasks
+change: camel-case-json-output
+---
+
+- [x] Add `rename_all = "camelCase"` to `CheckOutput`, `BackendCheck` and `ConfigureOutput`
+- [x] Leave the `src/config.rs` kebab-case attributes alone
+- [x] Regenerate the schemas and read the `carillon-check` and `carillon-configure` properties
+- [x] Fold the delta into the spec and log the change