Repository navigation
Stability for 2.0.0: CLI-only scope, pinned JSON contracts, written promise #67
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
98fcb2b
e0c2a6e
c641786
78c700a
e797eaf
d2cffc9
725a84f
a782f2f
0dcd947
2a81f65
d4affc0
4daa7f8
4781252
942cc2b
af41037
f6f4cf0
a58334d
0a3e4f3
06f14c5
6b96345
95620db
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| # Sephera Stability Policy | ||
|
|
||
| **Version:** 2.0.0 | ||
| **Status:** The 2.0.0 stability promise. | ||
|
|
||
| This document states what Sephera 2.0.0 guarantees to its users. It is the | ||
| contract behind the version number. If a change would break something listed | ||
| here, it is a breaking change and needs a major version bump. | ||
|
|
||
| ## Scope | ||
|
|
||
| Sephera is a **CLI tool**. The stability promise covers: | ||
|
|
||
| 1. **The CLI** — 24 commands, their flags, their JSON output shapes, their exit codes. | ||
| 2. **The MCP server** — 21 tools, their input schemas, their wire protocol. | ||
|
|
||
| It does **not** cover: | ||
|
|
||
| - The Rust library API. All library crates are `publish = false`; they are | ||
| implementation detail. The `sephera` binary is distributed in GitHub | ||
| release archives, not published to crates.io. | ||
| - Human-readable output formats (tables, markdown reports). These are for | ||
| humans and may change cosmetically. The JSON output is the machine contract. | ||
|
|
||
| ## CLI contract | ||
|
|
||
| ### Commands and flags | ||
|
|
||
| The 24 commands and their flags are stable. Removing a command, removing a | ||
| flag, or changing a flag's meaning is a breaking change. Adding a new command | ||
| or a new optional flag is not. | ||
|
|
||
| ### JSON output | ||
|
|
||
| The JSON output of every command that supports `--format json` (20 of the | ||
| 24 commands) is a frozen contract from 2.0.0 onward. `guard`, `skill`, | ||
| `watch`, and `mcp` have no `--format` flag and are outside this contract. | ||
| Specifically: | ||
| - Top-level keys will not be removed or renamed. | ||
| - Field types will not change (a string stays a string, a number stays a number). | ||
| - New keys may be added (additive changes are not breaking). | ||
| - Key order is not guaranteed (JSON objects are unordered). | ||
|
|
||
| Every command's JSON output is pinned by an insta snapshot test in | ||
| `crates/sephera_cli/tests/`. If a snapshot changes, it is a breaking change | ||
| until proven otherwise. | ||
|
|
||
| ### Exit codes | ||
|
|
||
| - `0` — success. The analysis ran; any gate thresholds were not crossed. | ||
| - `1` — failure. The analysis could not run. An `error:` line is printed to stderr. | ||
| - `2` — gate violated. The analysis ran and a `--fail-on` threshold was crossed. | ||
| - `64` — usage error. The command line could not be parsed (unknown flag, | ||
| missing required argument). The run never started, so this cannot be | ||
| confused with a gate violation. | ||
| - `130` — interrupted. The user pressed Ctrl+C. Distinct from failure by design. | ||
|
|
||
| These codes are stable. A script that checks `== 2` for gate violations will | ||
| keep working. | ||
|
|
||
| ### Error format | ||
|
|
||
| Errors are printed to stderr as `error: <message>`. The message text may change; | ||
| the `error:` prefix and the stderr stream are stable. | ||
|
|
||
| One case is not an error report and carries no prefix: running `sephera` | ||
| with no arguments prints the help text to stderr and exits 64 (a missing | ||
| required argument), because the output is help, not an error message. | ||
|
|
||
| ## MCP contract | ||
|
|
||
| ### Tools | ||
|
|
||
| The 21 tools and their names are stable. Removing a tool or renaming it is a | ||
| breaking change. Adding a new tool is not. | ||
|
|
||
| ### Input schemas | ||
|
|
||
| Each tool's input parameters are stable. Removing a parameter or changing its | ||
| type is a breaking change. Adding a new optional parameter is not. | ||
|
|
||
| ### Wire protocol | ||
|
|
||
| The MCP server speaks JSON-RPC 2.0 over stdio with newline-delimited JSON | ||
| framing: one JSON message per line, each terminated by `\n`. This framing is | ||
| stable. The protocol version is negotiated at initialization: the server | ||
| supports `2024-11-05`, `2025-03-26`, and `2025-06-18` (rmcp 1.3.0) and | ||
| answers with the version the client requested when it supports it, | ||
| otherwise its latest (`2025-06-18`). `2024-11-05` is the oldest | ||
| supported version, not the negotiated one. | ||
|
|
||
| ### Output format | ||
|
|
||
| Tool outputs follow the same JSON contract as the CLI: top-level keys are | ||
| stable, new keys may be added, key order is not guaranteed. | ||
|
|
||
| ## What "breaking" means | ||
|
|
||
| A change is **breaking** if it would require a user to change their scripts, | ||
| their MCP client configuration, or their parsing code. Specifically: | ||
|
|
||
| - Removing/renaming a CLI command, flag, or MCP tool: **breaking** | ||
| - Removing/renaming a JSON key in any output: **breaking** | ||
| - Changing a JSON field's type: **breaking** | ||
| - Changing an exit code's meaning: **breaking** | ||
| - Adding a new command, flag (optional), tool, or JSON key: **not breaking** | ||
| - Changing human-readable table formatting: **not breaking** | ||
| - Changing an error message's wording (keeping the `error:` prefix): **not breaking** | ||
|
|
||
| ## Versioning | ||
|
|
||
| Sephera follows semantic versioning for the CLI and MCP contract: | ||
|
|
||
| - **Major** (3.0.0): breaking changes to the contract above. | ||
| - **Minor** (2.1.0): new commands, new tools, new optional flags, new JSON keys. | ||
| - **Patch** (2.0.1): bug fixes that do not change the contract. | ||
|
|
||
| The Rust library crates are `publish = false` and do not follow semver; they | ||
| change freely with the CLI. | ||
|
|
||
| ## Enforcement | ||
|
|
||
| - `cargo insta test --check --workspace` in CI fails on any snapshot mismatch. | ||
| - The `mcp_wire` CI job drives the MCP server over real stdio and verifies | ||
| the wire protocol. | ||
| - This document is the human-readable counterpart. When code and this document | ||
| disagree, the code's behavior (as pinned by snapshots) wins, and this | ||
| document must be updated. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -273,11 +273,22 @@ fn discover(anchor: &Path) -> Option<PathBuf> { | |
| } | ||
|
|
||
| /// The value after `flag`, if present. | ||
| /// | ||
| /// A following token that looks like a flag is not a value: clap would | ||
| /// report the flag as missing its value, and swallowing the next flag | ||
| /// here would both hide that error and misread the flag as a path | ||
| /// (`loc --config --format json` read `--format` as the config filename | ||
| /// and exited 1 for a missing file instead of 64 for a missing | ||
| /// argument). A lone `-` is a value, not a flag, and `--flag=value` | ||
| /// still supplies its value directly. | ||
| fn flag_value(argv: &[String], flag: &str) -> Option<String> { | ||
| let mut arguments = argv.iter(); | ||
| while let Some(argument) = arguments.next() { | ||
| if argument == flag { | ||
| return arguments.next().cloned(); | ||
| return match arguments.next() { | ||
| Some(value) if is_flag_like(value) => None, | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Preserve missing-value errors through the configuration pre-pass. With no discoverable configuration, Distinguish an absent option from an option with a missing value. Defer configuration checks for the latter so clap can report exit 64. Add this case beside the existing
|
||
| value => value.cloned(), | ||
| }; | ||
| } | ||
| // `--flag=value` is the other spelling of the same thing. | ||
| if let Some(value) = argument.strip_prefix(&format!("{flag}=")) { | ||
|
|
@@ -287,6 +298,12 @@ fn flag_value(argv: &[String], flag: &str) -> Option<String> { | |
| None | ||
| } | ||
|
|
||
| /// Whether a token reads as a flag rather than a value: it starts with | ||
| /// `-` and is more than the lone `-`, which clap treats as a value. | ||
| fn is_flag_like(token: &str) -> bool { | ||
| token.len() > 1 && token.starts_with('-') | ||
| } | ||
|
|
||
| /// The command name the user asked for, before `clap` sees it. | ||
| fn requested_command<'argv>( | ||
| argv: &'argv [String], | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.