HTTP API: shell

The repository's shell automation measured against the tracked migration inventory: new shell is refused unless an exemption declares why it has to be shell and when it stops being, and an exemption whose file is gone is refused too, so the list only shrinks as units move into typed and scripted capabilities (ADR 0069).

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

shell

GET /api/v1/shell/check shell.check

Refuse undeclared shell

Every shell unit under bin/, lib/, scripts/, share/, .githooks/ and .claude/hooks/ — by interpreter line or by a .sh name, as git would commit it, links not followed — against .ai/repo/automation/inventory.jsonl: an undeclared unit, a record whose unit is gone, an exemption missing its reason or its removal condition, a disposition outside A-F, a duplicate and a record out of canonical order are each a finding that names the file and the remedy. Reads the tree and git's index only; no build and no network.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_shell_check
$ shell check

No parameters.

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/shell/check"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	ShellReport	Refuse undeclared shell: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

ShellFinding

object

One thing the check refuses, with what to do about it.

property	type	required	description
code	string	yes	The finding's code: `shell.undeclared`, `shell.stale`, `shell.missing_field`, `shell.invalid_disposition`, `shell.invalid_unit`, `shell.exemption_not_shell`, `shell.duplicate`, `shell.out_of_order` or `shell.malformed`.
path	string	yes	The file the finding is about: the shell unit, or the inventory itself.
line	integer \| null	no	The line of the inventory the finding is about, when it is about one.
message	string	yes	What is wrong, in a sentence.
remedy	string	yes	What to do about it.

Used by ShellReport

ShellReport

object

The verdict of one check of the tree.

property	type	required	description
measured	boolean	yes	Whether the tree could be measured at all. `false` is not a pass: the reason says what stopped the measurement, and a caller that gates on this report must refuse.
reason	string \| null	no	Why the tree could not be measured, when it could not.
inventory	string	yes	The inventory read, relative to the repository root.
governed	array of string	yes	The directories whose shell units must be declared.
units	array of ShellUnit → ShellUnit	yes	Every shell unit under the governed directories, in canonical order.
records	integer (uint)	yes	How many records the inventory holds, shell or not.
exemptions	map of integer (uint)	yes	How many exemptions the inventory declares, by disposition.
findings	array of ShellFinding → ShellFinding	yes	Every finding, in canonical order. Empty is the passing answer.
passes	boolean	yes	`true` when the tree was measured and nothing was found.

Used by shell.check

ShellUnit

object

One shell unit the tree carries.

property	type	required	description
path	string	yes	The path, relative to the repository root.
dialect	string	yes	The shell the unit is written for: the interpreter its first line names, or `sourced` for a `*.sh` file with no interpreter line.
disposition	string \| null	no	The disposition its inventory record carries, when it has one.

Used by ShellReport