The agent that turns websites into APIs!
feat(cli): expand agent-friendly tests, --help epilogs and README
Kalil Bouziguesab5b57963716
diff --git a/README.md b/README.mdindex c65e249..e5dc7af 100644--- a/README.md+++ b/README.md@@ -358,7 +358,9 @@ Use these slash commands while in the CLI:### Scripted / Agent Usage-The CLI subcommands are scriptable. Pass `--no-interactive` (and/or `--json`) so they fail fast instead of opening prompts, and pipe the structured output into `jq` or another agent.+The CLI subcommands can be driven by another agent or a wrapper script. Pass `--no-interactive` (and/or `--json`) so they fail fast instead of opening questionary prompts, and pipe the structured output into `jq`.++When `--json` is set: stdout contains exactly one JSON document (the final result), Rich logs and progress are diverted to stderr, and the process exits with a stable code.```bash# Run an autonomous agent capture and get a single JSON result on stdout@@ -367,30 +369,41 @@ reverse-api-engineer agent \--url https://example.com/jobs \--json | jq-# Output (logs go to stderr; one JSON object on stdout):-# {-# "schema_version": 1,-# "status": "ok",-# "run_id": "deadbeef0001",-# "prompt": "capture the public jobs api",-# "url": "https://example.com/jobs",-# "mode": "auto",-# "har_path": "/.../recording.har",-# "script_path": "/.../api_client.py",-# "usage": { ... },-# "error": null-# }-# List runs / inspect a run as JSON (empty history -> [])reverse-api-engineer list --jsonreverse-api-engineer show <run_id> --json-# Run a generated script non-interactively (errors on multiple-script picker-# or missing-dep prompt instead of blocking)-reverse-api-engineer run <run_id> --no-interactive --auto-install -- --org acme+# Run a generated script non-interactively+# --no-interactive : never open the script-picker / install confirm+# --auto-install : install missing deps on retry without asking+reverse-api-engineer run <run_id> --file api_client.py \+ --no-interactive --auto-install -- --org acme```-Exit codes: `0` success, `1` runtime error, `2` misuse (missing required args).+#### `agent --json` output schema++| Field | Type | Notes |+|------------------|---------------------|------------------------------------------------------------------------|+| `schema_version` | `int` | Currently `1`. Bumped on breaking changes. |+| `status` | `"ok"` \| `"error"` | Top-level result. |+| `run_id` | `string` \| `null` | Stable id for follow-up `show` / `engineer` / `run` calls. |+| `prompt` | `string` | The prompt that was passed in. |+| `url` | `string` \| `null` | Optional starting URL. |+| `mode` | `string` \| `null` | Provider used (`"auto"` for Playwright MCP, `"chrome-mcp"`). |+| `har_path` | `string` \| `null` | Absolute path to the captured HAR (`recording.har`). |+| `script_path` | `string` \| `null` | Absolute path to the generated client when reverse engineering ran. |+| `usage` | `object` | Token + cost usage from the engineer SDK (`{input_tokens, output_tokens, total_cost}`).|+| `error` | `string` \| `null` | Human-readable error message when `status == "error"`. |++#### Exit codes++| Code | Meaning |+|------|---------------------------------------------------------------------------|+| `0` | Success. |+| `1` | Runtime error (capture or engineering failed; details in `error`). |+| `2` | Misuse β required arg missing under `--no-interactive` / `--json`. |++For `run`, the exit code is the underlying script's return code on success, or `1` if no script was found, or non-zero if `--no-interactive` would otherwise have to prompt.## π Claude Code Plugindiff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.pyindex 831515a..0038ba3 100644--- a/src/reverse_api/cli.py+++ b/src/reverse_api/cli.py@@ -1307,7 +1307,35 @@ def manual(prompt, url, reverse_engineer, model, output_dir):run_manual_capture(prompt, url, reverse_engineer, model, output_dir)+ epilog="""\b+Examples:+ reverse-api-engineer agent+ reverse-api-engineer agent -p "capture the jobs api" -u https://example.com --no-interactive+ reverse-api-engineer agent -p "capture the jobs api" --json | jq++\b+JSON output schema (--json):+ {+ "schema_version": 1,+ "status": "ok" | "error",+ "run_id": "<id>" | null,+ "prompt": "...",+ "url": "..." | null,+ "mode": "auto" | "chrome-mcp" | null,+ "har_path": "/abs/path/recording.har" | null,+ "script_path": "/abs/path/api_client.py" | null,+ "usage": { "input_tokens": ..., "output_tokens": ..., "total_cost": ... },+ "error": "<message>" | null+ }++\b+Exit codes:+ 0 success+ 1 runtime error (capture or engineering failed)+ 2 misuse (e.g. --prompt missing under --no-interactive / --json)+"""+)@click.option("--prompt", "-p", default=None, help="Instruction for the autonomous agent.")@click.option("--url", "-u", default=None, help="Optional starting URL.")@click.option(@@ -1995,7 +2023,16 @@ def _get_run_details(run: dict) -> dict:}[email protected]("list")+ "list",+ epilog="""\b+Examples:+ reverse-api-engineer list+ reverse-api-engineer list --mode auto --search jobs --json | jq++JSON output (--json) is always a flat array (possibly empty []).+""",+)@click.option("--json", "as_json", is_flag=True, help="Output as flat JSON array.")@click.option("--full", is_flag=True, help="Show all columns (default: compact view).")@click.option("--limit", "-n", type=int, default=None, help="Limit number of results.")@@ -2076,7 +2113,19 @@ def list_runs(as_json, full, limit, mode, model, search):console.print(table)[email protected]("show")+ "show",+ epilog="""\b+Examples:+ reverse-api-engineer show+ reverse-api-engineer show <run_id> --json | jq++\b+Exit codes (--json):+ 0 run found+ 1 run not found / no history+""",+)@click.argument("run_id", required=False)@click.option("--json", "as_json", is_flag=True, help="Output as JSON object.")def show_run(run_id, as_json):@@ -2188,7 +2237,22 @@ def show_run(run_id, as_json):console.print(table)[email protected]("run")+ "run",+ epilog="""\b+Examples:+ reverse-api-engineer run a450e520ca30+ reverse-api-engineer run ashby --ls+ reverse-api-engineer run ashby --file api_client.py -- --org acme --limit 10+ reverse-api-engineer run a450e520ca30 --file api_client.py --no-interactive --auto-install++\b+Exit codes:+ <script's exit code> the underlying script's return code (0 on success)+ 1 no script found for the run+ non-zero missing --file when multiple scripts exist under --no-interactive+""",+)@click.argument("identifier")@click.argument("script_args", nargs=-1, type=click.UNPROCESSED)@click.option("--file", "-f", "file_name", default=None, help="Script filename to run (e.g. api_client.py).")diff --git a/tests/test_cli_agent_json.py b/tests/test_cli_agent_json.pyindex f8dca12..72672d0 100644--- a/tests/test_cli_agent_json.py+++ b/tests/test_cli_agent_json.py@@ -1,8 +1,9 @@"""Tests for the agent-friendly CLI surface (--json, --no-interactive, payload shape)."""import json-from unittest.mock import patch+from unittest.mock import MagicMock, patch+import pytestfrom click.testing import CliRunnerfrom reverse_api.cli import (@@ -10,8 +11,10 @@ from reverse_api.cli import (_build_agent_payload,agent,list_runs,+ main,show_run,)+from reverse_api.session import SessionManagerclass TestBuildAgentPayload:@@ -136,3 +139,169 @@ class TestShowJsonNotFound:payload = json.loads(result.stdout.strip())assert "error" in payloadassert payload["run_id"] == "doesnotexist"+++# ---------------------------------------------------------------------------+# `run` command: --no-interactive and --auto-install behavior+# ---------------------------------------------------------------------------+++def multi_script_env(tmp_path):+ """Fake a run with multiple .py scripts on disk so the picker would normally fire."""+ history_path = tmp_path / "history.json"+ sm = SessionManager(history_path)+ sm.add_run(+ "abc123def456",+ "capture the ashby jobs api",+ mode="manual",+ paths={"script_path": "/scripts/abc123def456/api_client.py"},+ )+ scripts_dir = tmp_path / "scripts" / "abc123def456"+ scripts_dir.mkdir(parents=True)+ (scripts_dir / "api_client.py").write_text("print('client')")+ (scripts_dir / "example_usage.py").write_text("print('example')")++ patches = [+ patch("reverse_api.cli.session_manager", sm),+ patch("reverse_api.cli.config_manager", MagicMock(get=MagicMock(return_value=None))),+ patch("reverse_api.utils.get_base_output_dir", return_value=tmp_path),+ ]+ for p in patches:+ p.start()+ try:+ yield tmp_path, sm+ finally:+ for p in patches:+ p.stop()+++class TestRunCommandNonInteractive:+ """`run` should never block on questionary when --no-interactive or --auto-install is set."""++ def test_multiple_scripts_with_no_interactive_errors(self, multi_script_env):+ runner = CliRunner()+ with patch("questionary.select") as mock_select:+ result = runner.invoke(main, ["run", "abc123def456", "--no-interactive"])+ assert result.exit_code != 0+ # Picker must NOT have been opened+ mock_select.assert_not_called()+ assert "multiple scripts" in result.output.lower() or "available" in result.output.lower()++ def test_multiple_scripts_with_auto_install_errors_on_picker(self, multi_script_env):+ """--auto-install also implies non-interactive for the picker."""+ runner = CliRunner()+ with patch("questionary.select") as mock_select:+ result = runner.invoke(main, ["run", "abc123def456", "--auto-install"])+ assert result.exit_code != 0+ mock_select.assert_not_called()++ def test_no_interactive_with_file_flag_runs(self, multi_script_env):+ """--file disambiguates and the script runs without prompting."""+ runner = CliRunner()+ ok = MagicMock(returncode=0, stdout="", stderr="")+ with patch("subprocess.run", return_value=ok) as mock_sub, patch("questionary.select") as mock_select:+ result = runner.invoke(+ main, ["run", "abc123def456", "--file", "api_client.py", "--no-interactive"]+ )+ assert result.exit_code == 0+ mock_select.assert_not_called()+ assert mock_sub.called++ def test_auto_install_skips_questionary_confirm(self, multi_script_env):+ """When the script raises ModuleNotFoundError, --auto-install skips the confirm prompt."""+ runner = CliRunner()+ # First subprocess.run returns missing-module error; subsequent ones (venv setup, pip install, retry)+ # all succeed.+ first = MagicMock(returncode=1, stdout="", stderr="ModuleNotFoundError: No module named 'foo'")+ ok = MagicMock(returncode=0, stdout="", stderr="")++ def fake_subprocess(cmd, *args, **kwargs):+ # Detect the script execution call by looking for the .py path+ cmd_str = " ".join(str(c) for c in cmd)+ if cmd_str.endswith("api_client.py") or "api_client.py" in cmd_str:+ # First and second invocation of the script path+ fake_subprocess.script_calls += 1+ if fake_subprocess.script_calls == 1:+ return first+ return ok++ fake_subprocess.script_calls = 0++ with patch("subprocess.run", side_effect=fake_subprocess), patch("questionary.confirm") as mock_confirm:+ result = runner.invoke(+ main, ["run", "abc123def456", "--file", "api_client.py", "--auto-install"]+ )+ # questionary.confirm must never have been called+ mock_confirm.assert_not_called()+ # Final exit code should be from the retry (success)+ assert result.exit_code == 0++ def test_no_interactive_skips_confirm_and_does_not_install(self, multi_script_env):+ """--no-interactive (without --auto-install) must NOT install missing deps; it surfaces the failure."""+ runner = CliRunner()+ first = MagicMock(returncode=1, stdout="", stderr="ModuleNotFoundError: No module named 'foo'")+ ok = MagicMock(returncode=0, stdout="", stderr="")++ def fake_subprocess(cmd, *args, **kwargs):+ cmd_str = " ".join(str(c) for c in cmd)+ if "api_client.py" in cmd_str:+ fake_subprocess.script_calls += 1+ if fake_subprocess.script_calls == 1:+ return first+ # pip install must NOT happen β assert it+ if "pip" in cmd_str and "install" in cmd_str and "foo" in cmd_str:+ pytest.fail("pip should not have been called to install 'foo' under --no-interactive")+ return ok++ fake_subprocess.script_calls = 0++ with patch("subprocess.run", side_effect=fake_subprocess), patch("questionary.confirm") as mock_confirm:+ result = runner.invoke(+ main, ["run", "abc123def456", "--file", "api_client.py", "--no-interactive"]+ )+ mock_confirm.assert_not_called()+ # Exit propagates the original failure+ assert result.exit_code != 0+++# ---------------------------------------------------------------------------+# Agent --json: interruption + stdout-purity+# ---------------------------------------------------------------------------+++class TestAgentJsonInterruption:+ def test_keyboard_interrupt_emits_error_payload(self):+ runner = CliRunner()+ with patch("reverse_api.cli.run_agent_capture", side_effect=KeyboardInterrupt):+ result = runner.invoke(agent, ["--json", "-p", "x"])+ assert result.exit_code == 1+ payload = json.loads(result.stdout.strip().splitlines()[-1])+ assert payload["status"] == "error"+ assert payload["error"] == "interrupted"+++class TestAgentJsonStdoutPurity:+ """Stdout should contain exactly one JSON line; Rich noise must go to stderr."""++ def test_rich_console_output_does_not_contaminate_stdout(self):+ from reverse_api.cli import console as cli_console++ # Click 8.2+ separates stdout/stderr by default+ runner = CliRunner()++ def fake_capture(**kwargs):+ cli_console.print("noisy human-readable status")+ return {"run_id": "abc", "mode": "auto", "script_path": None, "usage": {}}++ with patch("reverse_api.cli.run_agent_capture", side_effect=fake_capture):+ result = runner.invoke(agent, ["--json", "-p", "x"])++ assert result.exit_code == 0+ # stdout is exactly one JSON object β nothing else+ stdout = result.stdout.strip()+ payload = json.loads(stdout)+ assert payload["status"] == "ok"+ assert "noisy" not in stdout+ # The noise landed on stderr instead+ assert "noisy" in result.stderr