recurspec

RecurSpec is an early-stage, MIT-licensed Node.js package that tests recovery paths in command-line tools. Where a conventional test might only assert that an error message is printed, RecurSpec verifies that the command the message suggests actually fixes the problem, so that users really get unstuck. How it works A test case is described declaratively in a recurspec.yml file. Each case declares the command to run, the expected failure (for example a nonzero exit code and a stderr substring), where the recovery instruction comes from, and a verification step. Verification can rerun the original command and require a zero exit code, so the tool confirms the recovery loop closes rather than just that the advice is present. Getting started The project requires Node.js 22 or later and pnpm. It is installed as a development dependency, then used through three core commands: an init step that writes a starter configuration containing a runnable Node.js example, a validate step, and a test step. The bundled demo deliberately mixes passing and broken recovery paths. Command-line surface The CLI exposes test, validate, init, explain and discover commands. The test command supports options for selecting a case or tag, choosing a report format (human, json, junit or markdown), verbose output, fail-fast behaviour, a seed, and a dry run. Exit codes are defined as 0 for all passing, 1 for a failed contract, and 2 for configuration or usage errors. JSON, JUnit and Markdown reporters are intended for CI pipelines and pull-request comments. A programmatic API is also available through runRecurSpec. What it catches The tool targets mismatches between an error message and its instructions: suggested commands that no longer exist, incomplete recovery steps, commands that succeed without resolving the original problem, advice that leads into a further error, instruction loops, and instructions that are ambiguous or unsafe. Retry and goal recovery Two recovery shapes are supported. In retry-style recovery, removing a blocker lets the original command succeed on a second attempt. In goal recovery, the suggested command replaces the failed operation entirely, so the user's goal is met even though rerunning the original command would still fail. The README notes that work on Cargo cases surfaced this distinction and led to goal-based verification. Real-world compatibility The compatibility suite includes cases drawn from Git, Cargo and npm, covering situations such as a missing Git identity, branch deletion, divergent pull advice, an existing Cargo project directory, and an npm script that is missing. Results include ambiguous advice (multiple exclusive or required commands), goal recovery, and informational-only messages that are correctly ignored. Missing tools are skipped when the suite runs. Safety model Recovery commands are parsed and checked before execution. Shell chaining, redirection, command substitution and known destructive commands are blocked by default, and each case runs in an isolated temporary workspace. The README is explicit that the local backend does not enforce OS-level network sandboxing, so a deny-network setting remains advisory until a container backend exists. Limitations and status The documentation lists three limitations: no OS-level network isolation in the local backend, a need for scripted standard input when testing interactive TTY programs (full PTY support is future work), and a dependence on tools printing greppable advice, with ambiguous or missing advice reported rather than guessed. RecurSpec is described as early-stage, and both the configuration and public API may change before a 1.0 release. Separate documentation covers configuration, extraction, safety, reporters and discovery.