# Declarative CLI contract

Reckon's command grammar is defined once in `src/cli-model.ts` with Commander
15.0.0. The model owns root and nested commands, positionals, global and local
options, numeric parsing, unknown-option rejection, and root or command help.
`bin/cli.ts` dispatches the validated invocation to the existing product
handlers so JSON output contracts and established commands remain compatible.

Run `reckon --help` for the root command inventory or append `--help` to any
declared command path, for example:

```bash
reckon repos search --help
reckon update --help
```

Help uses the active terminal width. Non-TTY output uses a deterministic
100-column layout so snapshots, documentation, and automation do not depend on
the caller's environment. Narrow and wide formatting are covered by pure tests;
the Unix acceptance fixture also exercises a real pseudo-terminal when the
host provides one. Windows uses the same deterministic formatter and Commander
model without depending on a Unix `script` executable.

Commander is an exact production dependency rather than a floating range. Its
resolved integrity is pinned by both npm and Bun lockfiles and flows through
the normal SBOM, provenance, package-install, vulnerability, and signed-release
gates. It adds no transitive runtime dependencies. Updating it requires the
same lockfile review and full CLI compatibility suite as any parser change.

Command-specific semantic checks remain close to their product handlers (for
example repository existence, mutually exclusive configuration modes, and
graph-query target rules), but syntax cannot reach a handler unless the shared
declarative model accepts it first.

`reckon pack grep` evaluates user patterns with exact-pinned RE2 WebAssembly,
not Node's backtracking regular-expression engine. Backreferences and lookaround
are rejected because they cannot retain RE2's linear-time guarantee. Route
matching treats application path text literally and recognizes only complete
Express/NestJS-style `:name` or `{name}` path segments as parameters.