Skip to content

The agent that turns websites into APIs!

feat(cli): agent --dry-run for safe pre-flight validation (issue #62 item 5)

Kalil Bouzigues43a3d9704260
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.py
index 5b59910..65bc3d9 100644
--- a/src/reverse_api/cli.py
+++ b/src/reverse_api/cli.py
@@ -1,5 +1,6 @@
import asyncio
import json
+import os
import random
import sys
from contextlib import contextmanager
@@ -175,6 +176,153 @@ def _quiet_consoles_for_json():
c._file = original_inner
+def _build_dry_run_payload(
+ *,
+ prompt: str | None,
+ url: str | None,
+ model: str | None,
+ output_dir: str | None,
+ headless: bool,
+) -> dict:
+ """Validate config / env / deps without launching a browser.
+
+ Returns a payload with the same top-level shape as `_build_agent_payload`
+ plus a `checks` array (each item: name, status: ok|warn|error, message)
+ and a `would_run` sub-object showing what an actual `agent` invocation
+ would do with these inputs. Status is `error` if any check is `error`,
+ otherwise `ok`. Misuse errors (missing prompt) get `error_kind=misuse`;
+ runtime issues (missing API key, missing node) get `config_invalid`.
+ """
+ import shutil
+ import subprocess
+
+ checks: list[dict] = []
+
+ # 1. Prompt
+ if not prompt or not prompt.strip():
+ checks.append({"name": "prompt", "status": "error", "message": "--prompt is required"})
+ else:
+ checks.append({"name": "prompt", "status": "ok", "message": f"{len(prompt)} chars"})
+
+ # 2. URL (optional, but if given it must look reasonable)
+ if url:
+ if url.startswith("http://") or url.startswith("https://"):
+ checks.append({"name": "url", "status": "ok", "message": url})
+ else:
+ checks.append({
+ "name": "url",
+ "status": "error",
+ "message": f"url must start with http:// or https://, got {url!r}",
+ })
+ else:
+ checks.append({"name": "url", "status": "ok", "message": "(none — agent will pick a start)"})
+
+ # 3. Agent provider
+ agent_provider = config_manager.get("agent_provider", "auto")
+ if agent_provider in ("auto", "chrome-mcp"):
+ checks.append({"name": "agent_provider", "status": "ok", "message": agent_provider})
+ else:
+ checks.append({
+ "name": "agent_provider",
+ "status": "error",
+ "message": f"unknown agent_provider {agent_provider!r}; expected 'auto' or 'chrome-mcp'",
+ })
+
+ # 4. SDK + API key presence (we only check env var existence, not validity)
+ sdk = config_manager.get("sdk", "claude")
+ sdk_env_var = {
+ "claude": "ANTHROPIC_API_KEY",
+ "opencode": "OPENCODE_API_KEY",
+ "copilot": "GITHUB_COPILOT_TOKEN",
+ }.get(sdk)
+ if sdk_env_var is None:
+ checks.append({
+ "name": "sdk",
+ "status": "error",
+ "message": f"unknown sdk {sdk!r}; expected 'claude', 'opencode', or 'copilot'",
+ })
+ elif not os.environ.get(sdk_env_var):
+ checks.append({
+ "name": f"sdk:{sdk}",
+ "status": "warn",
+ "message": f"{sdk_env_var} not set in env (the SDK may still resolve auth via a config file)",
+ })
+ else:
+ checks.append({"name": f"sdk:{sdk}", "status": "ok", "message": f"{sdk_env_var} present"})
+
+ # 5. Node.js for MCP servers (both auto and chrome-mcp use npx)
+ node = shutil.which("node")
+ if node is None:
+ checks.append({
+ "name": "node",
+ "status": "error",
+ "message": "node not found in PATH; required by both auto (rae-playwright-mcp) and chrome-mcp",
+ })
+ else:
+ try:
+ ver = subprocess.run(
+ [node, "--version"], capture_output=True, text=True, timeout=5
+ ).stdout.strip()
+ checks.append({"name": "node", "status": "ok", "message": ver})
+ except Exception as e:
+ checks.append({"name": "node", "status": "warn", "message": f"could not query version: {e}"})
+
+ # 6. Headed chrome-mcp requires the user has a real Chrome with auto-connect
+ if agent_provider == "chrome-mcp" and not headless:
+ checks.append({
+ "name": "chrome-mcp:auto-connect",
+ "status": "warn",
+ "message": "chrome-mcp without --headless requires Chrome 146+ with auto-connect enabled at chrome://inspect/#remote-debugging — this is not auto-checkable",
+ })
+
+ # 7. Output dir writability
+ base = Path(output_dir or config_manager.get("output_dir") or "~/.reverse-api/runs").expanduser()
+ try:
+ base.mkdir(parents=True, exist_ok=True)
+ probe = base / ".dry_run_write_probe"
+ probe.write_text("")
+ probe.unlink()
+ checks.append({"name": "output_dir", "status": "ok", "message": str(base)})
+ except Exception as e:
+ checks.append({
+ "name": "output_dir",
+ "status": "error",
+ "message": f"{base}: {e}",
+ })
+
+ # Aggregate
+ has_error = any(c["status"] == "error" for c in checks)
+ final_error = None
+ error_kind = None
+ if has_error:
+ first_err = next(c for c in checks if c["status"] == "error")
+ final_error = f"{first_err['name']}: {first_err['message']}"
+ # Misuse for prompt/url; config_invalid otherwise
+ error_kind = "misuse" if first_err["name"] in ("prompt", "url") else "config_invalid"
+
+ return {
+ "schema_version": AGENT_JSON_SCHEMA_VERSION,
+ "status": "error" if has_error else "ok",
+ "run_id": None,
+ "prompt": prompt,
+ "url": url,
+ "mode": "dry-run",
+ "har_path": None,
+ "script_path": None,
+ "usage": {},
+ "error": final_error,
+ "error_kind": error_kind,
+ "would_run": {
+ "agent_provider": agent_provider,
+ "sdk": sdk,
+ "model": model or config_manager.get("claude_code_model", "claude-sonnet-4-6"),
+ "output_dir": str(base),
+ "headless": headless,
+ },
+ "checks": checks,
+ }
+
+
def _build_agent_payload(
result: dict | None,
*,
@@ -1218,12 +1366,28 @@ Exit codes:
is_flag=True,
help="Launch the MCP-controlled browser in headless mode (required on machines without an X server). For chrome-mcp this drops --autoConnect since auto-connect requires a headed Chrome instance.",
)
-def agent(prompt, url, model, output_dir, no_interactive, as_json, headless):
+ "--dry-run",
+ is_flag=True,
+ help="Validate prompt/url/config/env without launching the browser. Emits a manifest of what would run + check results. Implies --json. Exits 0 if all checks pass, 1 if any error.",
+)
+def agent(prompt, url, model, output_dir, no_interactive, as_json, headless, dry_run):
"""Run autonomous agent browser session.
Agent mode runs an integrated capture + reverse-engineering pipeline; if you
only want a HAR recording, use `manual --no-engineer` instead.
"""
+ if dry_run:
+ # --dry-run is fundamentally about emitting machine-parseable validation
+ # results, so it implies --json (and therefore --no-interactive).
+ with _quiet_consoles_for_json() as real_stdout:
+ payload = _build_dry_run_payload(
+ prompt=prompt, url=url, model=model, output_dir=output_dir, headless=headless
+ )
+ real_stdout.write(json.dumps(payload) + "\n")
+ real_stdout.flush()
+ sys.exit(0 if payload["status"] == "ok" else 1)
+
no_interactive = no_interactive or as_json
if no_interactive and not (prompt and prompt.strip()):
diff --git a/tests/test_cli_followups.py b/tests/test_cli_followups.py
index e359da5..46ed07c 100644
--- a/tests/test_cli_followups.py
+++ b/tests/test_cli_followups.py
@@ -308,6 +308,126 @@ class TestJsonSchemaVersionFlag:
assert "--json-schema-version" in result.output
+class TestAgentDryRun:
+ """`agent --dry-run` validates without launching the browser."""
+
+ def test_dry_run_ok_path(self, tmp_path):
+ """All checks pass → status=ok, exit 0, full payload + checks array."""
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ # Patch config_manager so we don't depend on the user's real config
+ with patch("reverse_api.cli.config_manager") as cm, \
+ patch.dict("os.environ", {"ANTHROPIC_API_KEY": "fake"}, clear=False):
+ cm.get.side_effect = lambda key, default=None: {
+ "agent_provider": "auto",
+ "sdk": "claude",
+ "claude_code_model": "claude-sonnet-4-6",
+ "output_dir": str(tmp_path),
+ }.get(key, default)
+ result = runner.invoke(
+ agent_cmd, ["--dry-run", "-p", "fetch jobs", "-u", "https://example.com"]
+ )
+
+ assert result.exit_code == 0, result.output
+ payload = json.loads(result.stdout.strip())
+ assert payload["status"] == "ok"
+ assert payload["mode"] == "dry-run"
+ assert payload["run_id"] is None
+ assert payload["error"] is None
+ assert payload["would_run"]["agent_provider"] == "auto"
+ assert payload["would_run"]["sdk"] == "claude"
+ assert payload["would_run"]["headless"] is False
+ # Checks include prompt, url, agent_provider, sdk, node, output_dir
+ check_names = {c["name"] for c in payload["checks"]}
+ assert "prompt" in check_names
+ assert "url" in check_names
+ assert "agent_provider" in check_names
+ assert "node" in check_names
+ assert "output_dir" in check_names
+
+ def test_dry_run_missing_prompt_is_misuse(self, tmp_path):
+ """Missing --prompt → error_kind=misuse, exit 1, no browser launched."""
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ with patch("reverse_api.cli.config_manager") as cm:
+ cm.get.side_effect = lambda key, default=None: {
+ "agent_provider": "auto",
+ "sdk": "claude",
+ "output_dir": str(tmp_path),
+ }.get(key, default)
+ result = runner.invoke(agent_cmd, ["--dry-run"])
+
+ assert result.exit_code == 1
+ payload = json.loads(result.stdout.strip())
+ assert payload["status"] == "error"
+ assert payload["error_kind"] == "misuse"
+ assert any(c["name"] == "prompt" and c["status"] == "error" for c in payload["checks"])
+
+ def test_dry_run_bad_url_is_misuse(self, tmp_path):
+ """A url that doesn't start with http(s):// is flagged."""
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ with patch("reverse_api.cli.config_manager") as cm:
+ cm.get.side_effect = lambda key, default=None: {
+ "agent_provider": "auto",
+ "sdk": "claude",
+ "output_dir": str(tmp_path),
+ }.get(key, default)
+ result = runner.invoke(agent_cmd, ["--dry-run", "-p", "x", "-u", "ftp://nope"])
+
+ assert result.exit_code == 1
+ payload = json.loads(result.stdout.strip())
+ assert payload["error_kind"] == "misuse"
+ assert any(c["name"] == "url" and c["status"] == "error" for c in payload["checks"])
+
+ def test_dry_run_unwritable_output_dir_is_config_invalid(self):
+ """Unwritable output_dir → error_kind=config_invalid, not misuse."""
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ with patch("reverse_api.cli.config_manager") as cm:
+ cm.get.side_effect = lambda key, default=None: {
+ "agent_provider": "auto",
+ "sdk": "claude",
+ "output_dir": "/sys/forbidden",
+ }.get(key, default)
+ result = runner.invoke(
+ agent_cmd, ["--dry-run", "-p", "x", "--output-dir", "/sys/forbidden"]
+ )
+
+ assert result.exit_code == 1
+ payload = json.loads(result.stdout.strip())
+ assert payload["error_kind"] == "config_invalid"
+ assert any(c["name"] == "output_dir" and c["status"] == "error" for c in payload["checks"])
+
+ def test_dry_run_does_not_launch_browser(self, tmp_path):
+ """--dry-run must NOT call run_agent_capture (no browser, no LLM, no cost)."""
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ with patch("reverse_api.cli.config_manager") as cm, \
+ patch("reverse_api.cli.run_agent_capture") as mock_run:
+ cm.get.side_effect = lambda key, default=None: {
+ "agent_provider": "auto",
+ "sdk": "claude",
+ "output_dir": str(tmp_path),
+ }.get(key, default)
+ runner.invoke(agent_cmd, ["--dry-run", "-p", "x", "-u", "https://example.com"])
+ mock_run.assert_not_called()
+
+ def test_dry_run_help_mentions_implies_json(self):
+ from reverse_api.cli import agent as agent_cmd
+
+ runner = CliRunner()
+ result = runner.invoke(agent_cmd, ["--help"])
+ assert "--dry-run" in result.output
+ # Click reflows whitespace, so "Implies\n--json" or "Implies --json"
+ assert "Implies" in result.output and "--json" in result.output
+
+
class TestRootHelpMentionsScripted:
"""Item #6 partial: root --help should advertise scripted features."""