Open source CLI • @specferret/cli@0.9.12

The contract firewall for AI-generated code.

Coding agents change API shapes, types, and event payloads without telling you. SpecFerret generates contracts from your TypeScript, maps every consumer, and blocks the commit when a change breaks something downstream.

Install CLI Quickstart Read the code

bun install -g @specferret/cli   # Bun today; standalone binary next

cd your-repo
ferret extract --link   # contracts + import graph from your exported types — nothing to hand-write
ferret lint      # ✓ ferret  24 contracts  0 drift  11ms

Why SpecFerret

Nothing to hand-write

ferret extract builds contracts from your exported TypeScript — resolving type aliases and z.infer schemas. One command on an existing repo. No annotations, no YAML authoring.

Blast radius, not a diff

Every change is classified breaking or non-breaking, with the direct and transitive consumers listed, in under 500ms. You get stopped only for changes that actually break someone.

Built for agents, not just against them

A Claude Code hook blocks the agent mid-edit with the impact report, and an MCP server lets it ask what a change would break before it makes it.

In the agent's loop, not after it

The edit firewall

Every other drift tool writes a report for a human. ferret init installs a PostToolUse hook, so when the agent edits a type it is stopped and handed the contract, the downstream impact, and the fix — before its next move.

Ask before you break it

The MCP server exposes ferret_impact: the agent checks what a shape change would break before touching it. Prevention instead of cleanup.

Deterministic by design

No model sits in the decision path — same input, same verdict, every run, for zero tokens. You cannot trust an LLM to be the stop signal for another LLM.

"Doesn't tsc catch this?"

Inside one compile boundary, yes. Across the boundaries agents actually break — API responses parsed at runtime, DB rows, event payloads — it sees nothing. SpecFerret does.

How It Works

1. Run ferret extract on your repo — contracts are generated from your exported TypeScript, and config is created on first run.
2. Run ferret lint — drift is classified in both directions: contract changes that break consumers, and code that drifted from its declared contract.
3. Run ferret review to resolve, and ferret init --hook to block bad commits at the door.

Deterministic checks

Run ferret lint locally and in CI with reproducible drift detection and clear failure output.

Contract-aware impact

Review mode reports direct and transitive affected contracts so teams know exactly what to update.

Guarded publishing

Trusted publishing with OIDC from GitHub Actions, lockstep version guards, and a clean-room install smoke test after every release.