laurigates/cli-smoke-recipes

CLI Smoke Recipes

Every pure-function module that transforms data should be reachable from the shell plus a bulk-smoke recipe that iterates every shipped input. Applies to decoders, codecs, parsers, validators, formatters, compilers, transpilers, linters.

When to Use This Skill

| Use this skill when… | Skip when… | |---------------------|------------| | Designing a new module with a clear input → output contract | Internal helper with no stable interface | | Adding CLI exposure to an existing library | Code whose only consumer is another in-process module | | Authoring justfile recipes for bulk verification | One-off scripts | | Deciding if a feature is complete | Implementation is purely experimental |

The Pattern

1. CLI exposure

Each transforming module is callable via <bin> <module> <subcmd>:

| Operation | Pattern | Required? | |-----------|---------|-----------| | info | Pure reader; prints headers / metadata | Yes | | decode / parse | Source → output format | Yes if the module consumes | | encode / render | Output → source format | Yes if the module produces | | identify / validate | Classify / verify without full parse | Optional but cheap |

The subcommand is a shell entry point, not a new abstraction. It uses the module's existing functions — never a re-implementation.

2. Stdout-first

Reader subcommands default to streaming to stdout when the destination argument is omitted. This makes them pipe-friendly:

mytool codec info foo.bin | head -20
mytool codec decode foo.bin | jq .header
mytool codec decode foo.bin | cmp - expected.raw

Errors go to stderr, so stdout stays a clean data stream. Exit codes follow standard conventions (0 success, non-zero failure). Do not print decorative banners to stdout in reader commands.

3. Module purity

CLI paths keep module dependencies minimal. In practice: a codec module's CLI entrypoint should not import the application's UI / framework layer. The test:

Can the CLI run in a headless, framework-free environment (CI sandbox, bare container, a naked shell)?

If yes, the module is pure enough. If no, the module has a UI dependency that belongs somewhere else. Prune the import.

4. Justfile wrapper per subcommand

One recipe per subcommand, names: <module>-<subcmd>:

codec-info path:
    @just build
    ./build/mytool codec info {{path}}

codec-decode path:
    @just build
    ./build/mytool codec decode {{path}}

The recipe declares build as a prerequisite so stale binaries never hide bugs. Paths resolve against a workspace variable like GAME_ROOT / DATA_DIR / FIXTURE_DIR so they work across machines and in CI.

5. Bulk smoke recipe

Per module, one <module>-smoke recipe that iterates every shipped instance of the input format and prints a one-line summary per input:

codec-smoke:
    @just build
    for f in $(fd -e bin . "$DATA_DIR/codec"); do \
        printf "%-40s " "$(basename $f)"; \
        ./build/mytool codec info "$f" | head -1; \
    done

The bulk recipe catches correctness properties that per-file runs miss:

• "All N shipped inputs identify as the expected format" — catches format drift.
• "Round-trip against input X is byte-identical" — catches encode-vs-decode asymmetry.
• "Parser never crashes on any shipped input" — catches the most embarrassing class of bug.

6. Same-commit landing

CLI, justfile recipe, and module code ship in one commit. If the CLI or recipe is deferred to a follow-up, the feature tracker does not advance past "in progress." This is the same discipline as .claude/rules/docs-currency.md applied to the manual-verification surface instead of the docs.

Detection Heuristic

Before applying the pattern, confirm the module qualifies:

| Signal | Indicates | |--------|-----------| | Module has a pure transformation function | Pattern applies | | Input / output are serialisable (bytes, text, JSON) | Pattern applies | | Module needs UI / framework context to run | Pattern does not apply — refactor first | | Module is a one-off migration script | Pattern does not apply |

Quick Reference

Checklist for new transforming module

• [ ] info subcommand exposed
• [ ] decode / parse streams to stdout by default
• [ ] Errors go to stderr
• [ ] Module import graph excludes UI / framework layer
• [ ] One justfile recipe per subcommand, build prerequisite declared
• [ ] <module>-smoke iterates every shipped input
• [ ] CLI + recipes + module land in the same commit

Common Mistakes

| Mistake | Correct Approach | |---------|-----------------| | Decorative banners on stdout | Stderr only; stdout is data | | Running bulk smoke on "representative" inputs | Bulk smoke iterates every shipped input | | CLI imports the UI layer | Refactor; keep CLI path headless | | Deferring the smoke recipe to a follow-up | Same-commit or tracker does not advance | | Hard-coded absolute paths in recipes | Resolve against a workspace variable |

Related

• tools-plugin:justfile-expert — recipe-authoring mechanics
• .claude/rules/docs-currency.md — the same-commit principle this skill mirrors
• blueprint-plugin:blueprint-docs-currency — the docs-side counterpart
• agent-patterns-plugin:parallel-agent-dispatch — smoke recipes are the gate between waves in multi-wave dispatches

Evidence: the manual-verification surface is the last line of defence before gameplay / real traffic / integration tests exist. Smoke recipes shipped in the same commit as a decoder module caught encoding consistency and round-trip byte-identity on first run — manual exercise had never caught either.