Adding a feature

A feature is done when it works end to end and every layer has its proof. The order is fixed:

1. Engine API.
2. Automation tool with an end-to-end test.
3. UI.
4. Parity entry with evidence.
5. Documentation page update.

1. Engine API

• Put the behaviour in the engine, or in the crate below it that owns the concern (http, grpc, ws, interop, script, store, and so on).
• Return errors through the crate's error type and ?.
• The UI and the automation tool must share this one implementation.

2. Automation tool

Every user-facing feature must be callable without the GUI. Tools live in crates/automation/src/tools.rs.

• Add a ToolDef to the table returned by tools(). It has name (snake_case), title, description, input_schema and the read_only and destructive flags. Declare required and optional arguments with the req(...) and opt(...) helpers in the schema! macro.
• Add the matching arm to dispatch(...). Unknown tools and unknown arguments are refused before any state changes.
• Errors must say what was wrong and what is allowed.
• Send every path argument through the session, so --root confines it. A path outside the root gets the same refusal whether or not it exists, including paths reached by nested dispatch.
• Write atomically. Never discard unsaved work silently. Cap anything echoed to an agent (bodies are capped at 1 MiB).
• Add an end-to-end test in crates/automation/tests/ (see tools.rs and engine_tools.rs there). The CLI side is exercised in apps/postguy-cli/tests/.
• Check it yourself with postguy-cli:

cargo run -p postguy-cli -- tools
cargo run -p postguy-cli -- run --script steps.json --root DIR

3. UI

Implement the interface in crates/ui-egui. These rules apply to every UI change:

• Never add a repaint loop.
• Never run I/O, parsing, formatting, searching or scripts on the UI thread.
• Use Lucide icons from assets/icons/ and Poppins only (see Assets and clean-room).
• Check undo/redo and dirty tracking, save fidelity and session restore.
• Look at the result:
  • Launch postguy --control FILE. Use postguy-cli ui --control FILE screenshot --out x.png (plus inspect, command and set).
  • Or take a headless shot with cargo run -p postguy-ui-egui --example shot.
  
  The control channel refuses click, key and type today. See UI control channel and Known gaps.

4. Parity entry

Every user-facing feature has a [[feature]] entry in parity/postman-features.toml.

• shipped requires cited tests whose paths and names exist.
• planned and na entries must not cite evidence.

Run the check:

cargo xtask parity            # validate and report
cargo xtask parity --partial  # list partial entries

"Shipped" means it exists and is tested, not that it is "as good as another tool". Say in notes what is still missing. Also make sure no other entry just became untrue.

The same facts show to users on Feature status.

5. Documentation

Update the matching page under docs/content/ in the same pull request as any user-facing change. See Writing the documentation.

Testing

Review every change at four zooms. Do it while you make the change, not at the end.

Tests mirror the zooms: property, unit, crate integration, end to end. Scale the zoom to the change.

Hermetic tests

Tests never touch the internet. Use the loopback servers in crates/testkit (a dev-dependency, never shipped): HTTP, TLS, an OAuth token endpoint, gRPC with our own echo.proto, WebSocket and a proxy.

Fuzzing

cargo xtask fuzz --time 300

fuzz mutates committed seed files under fuzz/seeds/. It runs these targets in child processes through postguy-cli fuzz-target: url, vars, curl, data, openapi, har and script.

• A panic, a fatal signal or a hang is a finding.
• Findings are saved under fuzz-out/findings/, which is git-ignored.

Optional flags: --time SECONDS, and --seed N for a reproducible run. CI runs it nightly with --time 900.

To turn a finding into a regression test:

1. Read the saved input and the why in the finding's info file.
2. Reduce the input to a small synthetic sample. Never commit corpus-derived files.
3. Write a test that feeds it to the failing function and asserts a clean Err or a handled result.
4. Run the test and watch it fail (panic) before the fix.
5. Fix, run it again, then commit the fix and the test together.

Never-crash rules

A malformed file, a hostile response, a bad tool argument, a corrupt settings file or a full disk must produce an error the user can act on. It must never crash and never lose work. This outranks feature work.

• Non-test code uses Result. No unwrap(), expect(), panic!, unreachable!, todo! or unimplemented! unless provably infallible, with a comment saying why.
• No unsafe. The workspace sets unsafe_code = "forbid".
• Treat every input-derived number as hostile. Use get(), checked or saturating arithmetic, and cap allocations sized by the input.
• Bound recursion with seen-sets or depth limits (JSON, $ref, proto messages, variable references, redirects).
• Entry points that run untrusted input (scripts, importers, commands, file import and export) keep a last-resort catch_unwind guard. Keep panic = "unwind". Never set panic = "abort".
• A clean crate carries #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]. New crates start with it.
• Every crash fix comes with a small synthetic regression test that panicked before the fix.