The agent that turns websites into APIs!
from __future__ import annotations
import asyncio
import json
import logging
import os
import random
import sys
import traceback
from collections.abc import Callable, Iterable, Iterator
from contextlib import contextmanager
from pathlib import Path
from typing import IO, Any, Protocol, TextIO, TypedDict
import click
import questionary
import setproctitle
from prompt_toolkit import PromptSession
from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
from prompt_toolkit.completion import CompleteEvent, Completer, Completion
from prompt_toolkit.document import Document
from prompt_toolkit.formatted_text import HTML
from prompt_toolkit.key_binding import KeyBindings, KeyPressEvent
from prompt_toolkit.styles import Style as PtStyle
from questionary import Choice
from rich.console import Console
from rich.markup import escape
from . import __version__
from .config import DEFAULT_OPENCODE_MODEL, DEFAULT_OPENCODE_PROVIDER, ConfigManager
from .engineer import run_reverse_engineering
from .messages import MessageStore
from .session import SessionManager
from .tui import (
ERROR_CTA,
MODE_COLORS,
THEME_DIM,
THEME_PRIMARY,
THEME_SECONDARY,
display_banner,
display_footer,
get_model_choices,
)
from .utils import (
check_for_updates,
discover_scripts,
generate_folder_name,
generate_run_id,
get_base_output_dir,
get_config_path,
get_har_dir,
get_history_path,
get_messages_path,
get_timestamp,
resolve_run,
)
class CliEventEmitter(Protocol):
def __call__(self, event: str, **fields: Any) -> None: ...
class PromptModeState(TypedDict):
mode: str
mode_index: int
setproctitle.setproctitle("reverse-api-engineer")
setproctitle.setthreadtitle("reverse-api-engineer")
console = Console()
config_manager = ConfigManager(get_config_path())
session_manager = SessionManager(get_history_path())
def _format_ollama_size(size: int) -> str:
if size < 1024:
return "cloud"
return f"{size / (1024**3):.1f} GB"
def _select_ollama_model_for_settings() -> str | None:
"""Discover installed agent-capable Ollama models and let the user choose."""
from .ollama_runtime import OllamaSetupError, ensure_ollama_models
try:
status = asyncio.run(ensure_ollama_models())
except OllamaSetupError as e:
console.print(f" [yellow]error:[/yellow] {escape(str(e))}\n")
return None
models = status.compatible_models
if not models:
console.print(" [yellow]error:[/yellow] no installed Ollama model supports tools with at least 64k context")
console.print(" [dim]Pull a compatible model explicitly, then retry. RAE will not download multi-GB models silently.[/dim]\n")
return None
if len(models) == 1:
console.print(f" [dim]using the only compatible Ollama model: {models[0].name}[/dim]")
return models[0].name
choices = [
Choice(
title=(
f"{model.name} ({model.parameter_size or 'unknown'}, {_format_ollama_size(model.size)}, "
f"{model.context_length // 1024}k context)"
),
value=model.name,
)
for model in models
]
choices.append(Choice(title="back", value="back"))
selected = questionary.select(
" > ollama model",
choices=choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{THEME_SECONDARY} bold"),
("highlighted", f"fg:{THEME_SECONDARY} bold"),
]
),
).ask()
return None if selected in {None, "back"} else str(selected)
def default_model_for_configured_sdk(sdk: str | None = None) -> str:
"""Return the configured default model id for the given SDK (or current config SDK)."""
s = (sdk or config_manager.get("sdk", "claude") or "claude").lower()
if s == "opencode":
return str(config_manager.get("opencode_model") or DEFAULT_OPENCODE_MODEL)
if s == "copilot":
return str(config_manager.get("copilot_model") or "gpt-5")
if s == "cursor":
return str(config_manager.get("cursor_model") or "composer-2.5")
return str(config_manager.get("claude_code_model") or "claude-sonnet-4-6")
async def _load_opencode_catalog_for_settings() -> dict:
"""Start or reuse OpenCode and load its live provider/model catalog."""
import httpx2 as httpx
from .opencode_runtime import (
ensure_opencode_server,
get_opencode_model_catalog,
opencode_base_url,
)
base_url = opencode_base_url()
password = os.environ.get("OPENCODE_SERVER_PASSWORD")
username = os.environ.get("OPENCODE_SERVER_USERNAME", "opencode")
auth = httpx.BasicAuth(username, password) if password else None
async with httpx.AsyncClient(base_url=base_url, timeout=120.0, auth=auth) as client:
await ensure_opencode_server(client, base_url=base_url)
return await get_opencode_model_catalog(client)
def _select_opencode_pair_for_settings(mode_color: str = THEME_PRIMARY) -> tuple[str, str] | None:
"""Select a valid tool-capable provider/model pair from the live OpenCode catalog."""
from .opencode_runtime import opencode_model_is_free, opencode_model_is_selectable
try:
with console.status(" Loading OpenCode providers and models...", spinner="dots"):
catalog = asyncio.run(_load_opencode_catalog_for_settings())
except Exception as e:
response = getattr(e, "response", None)
if getattr(response, "status_code", None) == 401:
console.print(
" [yellow]error:[/yellow] OpenCode authentication failed. "
"Set OPENCODE_SERVER_PASSWORD (and OPENCODE_SERVER_USERNAME when customized).\n"
)
else:
console.print(f" [yellow]error:[/yellow] could not load OpenCode providers and models: {escape(str(e))}\n")
return None
providers = [provider for provider in catalog.get("providers", []) if isinstance(provider, dict)]
raw_defaults = catalog.get("default")
defaults = raw_defaults if isinstance(raw_defaults, dict) else {}
selectable = []
for provider in providers:
models = provider.get("models")
if provider.get("id") and isinstance(models, dict) and any(opencode_model_is_selectable(model) for model in models.values()):
selectable.append(provider)
style = questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
)
current_provider = config_manager.get("opencode_provider", "")
provider_choices = []
for provider in selectable:
provider_id = str(provider["id"])
provider_name = str(provider.get("name") or "")
title = (
f"{provider_id} — {provider_name}"
if provider_name and provider_name != provider_id
else provider_id
)
provider_choices.append(Choice(title=title, value=provider_id))
provider_ids = {str(provider["id"]) for provider in selectable}
if "ollama" not in provider_ids:
provider_choices.append(Choice(title="ollama — installed local models", value="ollama"))
provider_ids.add("ollama")
provider_choices.append(Choice(title="back", value="back"))
provider_id = questionary.select(
" > opencode provider",
choices=provider_choices,
default=current_provider if current_provider in provider_ids else None,
pointer=">",
qmark="",
style=style,
use_search_filter=True,
use_jk_keys=False,
).ask()
if provider_id is None or provider_id == "back":
return None
if provider_id == "ollama":
model_id = _select_ollama_model_for_settings()
return ("ollama", model_id) if model_id else None
provider = next(item for item in selectable if item.get("id") == provider_id)
models = provider["models"]
current_model = config_manager.get("opencode_model", "") if provider_id == current_provider else ""
default_model = str(defaults.get(provider_id) or "")
model_ids = [str(model_id) for model_id, model in models.items() if opencode_model_is_selectable(model)]
model_ids.sort(key=lambda model_id: (model_id not in {current_model, default_model}, model_id))
model_choices = []
for model_id in model_ids:
model = models[model_id]
model_name = str(model.get("name") or "")
title = f"{model_id} — {model_name}" if model_name and model_name != model_id else model_id
markers = []
if opencode_model_is_free(provider_id, model_id, model):
markers.append("free")
if model_id == default_model:
markers.append("default")
if markers:
title += f" ({', '.join(markers)})"
model_choices.append(Choice(title=title, value=model_id))
model_choices.append(Choice(title="back", value="back"))
selected_default = None
if current_model in model_ids:
selected_default = current_model
elif default_model in model_ids:
selected_default = default_model
model_id = questionary.select(
" > opencode model",
choices=model_choices,
default=selected_default,
pointer=">",
qmark="",
style=style,
use_search_filter=True,
use_jk_keys=False,
).ask()
if model_id is None or model_id == "back":
return None
return str(provider_id), str(model_id)
# Schema version for --json outputs. Wrappers can query it via
# `reverse-api-engineer --json-schema-version`.
AGENT_JSON_SCHEMA_VERSION = 1
# Map of stable usage keys → SDK-specific candidates (first match wins).
# Lets `agent --json` and `engineer --json` emit a stable cost/token shape
# regardless of which SDK (Claude / OpenCode / Copilot) ran underneath.
_STABLE_USAGE_KEYS: dict[str, tuple[str, ...]] = {
"input_tokens": ("input_tokens",),
"output_tokens": ("output_tokens",),
"cache_read_tokens": ("cache_read_input_tokens", "cache_read_tokens"),
"cache_write_tokens": ("cache_creation_input_tokens", "cache_write_tokens"),
"total_cost_usd": ("estimated_cost_usd", "total_cost_usd", "total_cost"),
}
def _normalize_usage(raw: dict | None) -> dict:
"""Return a stable subset of usage fields, keeping the SDK-native dict under .raw.
Wrappers can rely on the top-level keys; per-SDK extras stay under raw.
"""
if not raw or not isinstance(raw, dict):
return {}
out: dict = {}
for stable_key, candidates in _STABLE_USAGE_KEYS.items():
for c in candidates:
if c in raw:
out[stable_key] = raw[c]
break
out["raw"] = raw
return out
# Machine-readable error categories. Wrappers can react differently to each
# without pattern-matching on the human-readable `error` string.
ERROR_KINDS = (
"misuse", # user input invalid / missing required arg
"config_invalid", # config file or env var malformed
"permission_denied", # filesystem / API perm denied
"network", # DNS / TCP / TLS / timeout
"engine_failure", # SDK or capture engine crashed mid-run
"interrupted", # KeyboardInterrupt / SIGINT
"unknown", # default fallback
)
def _format_error_message(error: str | BaseException | None) -> str | None:
"""Render an exception or string into a human-readable error message.
KeyboardInterrupt has no useful str() — we return the conventional
"interrupted" so downstream wrappers can match on a stable message.
Empty exception messages fall back to the class name.
"""
if error is None:
return None
if isinstance(error, KeyboardInterrupt):
return "interrupted"
if isinstance(error, BaseException):
return str(error) or type(error).__name__
return error
def _classify_error(error: str | BaseException | None, *, default: str = "unknown") -> str | None:
"""Map an Exception or human error message to one of the ERROR_KINDS.
Callers may pass a stronger hint by setting `default` (e.g. `misuse` from
a CLI argument check, before any exception).
"""
if error is None:
return None
if isinstance(error, BaseException):
if isinstance(error, KeyboardInterrupt):
return "interrupted"
if isinstance(error, PermissionError):
return "permission_denied"
if isinstance(error, (ConnectionError, TimeoutError)):
return "network"
msg = str(error)
else:
msg = error
low = msg.lower()
if "permission denied" in low or "errno 13" in low:
return "permission_denied"
if "interrupted" in low:
return "interrupted"
if "is required" in low or "missing required" in low or "no such option" in low or "in non-interactive" in low:
return "misuse"
if any(kw in low for kw in ("connection refused", "timeout", "timed out", "dns", "network", "unreachable", "ssl")):
return "network"
if "not found" in low or "no run" in low or "produced no run" in low or "produced no result" in low:
return "engine_failure"
return default
@contextmanager
def _quiet_consoles_for_json() -> Iterator[TextIO]:
"""Reserve stdout for the final JSON payload; route Rich output to stderr.
Yields the original stdout file object so the caller can write JSON to it
after the wrapped block exits cleanly. Rich Console.file is a property that
lazily resolves to sys.stdout, so we save/restore the underlying _file slot
rather than the resolved file object.
"""
real_stdout = sys.stdout
redirected_consoles: list[tuple[Console, IO[str] | None]] = []
sys.stdout = sys.stderr
for mod_name, mod in list(sys.modules.items()):
if not mod_name.startswith("reverse_api") or mod is None:
continue
candidate = getattr(mod, "console", None)
if isinstance(candidate, Console):
redirected_consoles.append((candidate, candidate._file))
candidate.file = sys.stderr
try:
yield real_stdout
finally:
sys.stdout = real_stdout
for c, original_inner in redirected_consoles:
c._file = original_inner
def _write_json_line(stream: TextIO, line: str) -> None:
stream.write(line + "\n")
stream.flush()
def _write_json_stdout(real_stdout: TextIO, payload: dict, *, json_stream: bool) -> None:
"""Write final CLI JSON payload (single doc or NDJSON terminal event)."""
out = {"event": "result", **payload} if json_stream else payload
real_stdout.write(json.dumps(out) + "\n")
real_stdout.flush()
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
from .agent_browser import check_agent_browser_runtime
checks: list[dict] = []
agent_provider = config_manager.get("agent_provider", "auto")
global_agent_browser = shutil.which("agent-browser")
# 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
if agent_provider in ("auto", "chrome-mcp", "agent-browser"):
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', 'chrome-mcp', or 'agent-browser'",
})
# 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",
"cursor": "CURSOR_API_KEY",
}.get(sdk)
if sdk_env_var is None:
checks.append({
"name": "sdk",
"status": "error",
"message": f"unknown sdk {sdk!r}; expected 'claude', 'opencode', 'copilot', or 'cursor'",
})
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 + npx — MCP providers need both; agent-browser with a global binary does not.
node = shutil.which("node")
needs_node_for_browser = agent_provider != "agent-browser" or global_agent_browser is None
if node is None:
if needs_node_for_browser:
checks.append({
"name": "node",
"status": "error",
"message": "node not found in PATH; required for agent-mode browser tooling "
"(MCP browser servers plus Vercel agent-browser install/bootstrap)",
})
else:
checks.append({
"name": "node",
"status": "ok",
"message": "not on PATH (optional while global `agent-browser` is installed)",
})
else:
try:
ver = subprocess.run(
[node, "--version"], capture_output=True, text=True, errors="replace", 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}"})
npx = shutil.which("npx")
needs_npx_for_browser = agent_provider in ("auto", "chrome-mcp") or (
agent_provider == "agent-browser" and global_agent_browser is None
)
if npx is None:
if needs_npx_for_browser:
checks.append({
"name": "npx",
"status": "error",
"message": "npx not found in PATH; required so npm can spawn MCP helpers and "
"fetch/run the pinned agent-browser CLI when no global binary is present",
})
else:
checks.append({
"name": "npx",
"status": "ok",
"message": "not on PATH (optional while global `agent-browser` is installed)",
})
else:
checks.append({"name": "npx", "status": "ok", "message": npx})
# 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. agent-browser CLI: read-only validation (no npm install during dry-run).
if agent_provider == "agent-browser":
ab_setup = check_agent_browser_runtime()
parts: list[str] = []
if ab_setup.error:
parts.append(ab_setup.error)
elif ab_setup.ok:
parts.append("`agent-browser` CLI reachable (`--help` OK)")
if ab_setup.notices:
parts.extend(ab_setup.notices)
checks.append({
"name": "agent-browser:cli",
"status": "error" if not ab_setup.ok else "ok",
"message": " | ".join(parts) if parts else "configured",
})
# 8. Output dir writability — probe with a unique filename so we never
# clobber a real user file (a fixed name like `.dry_run_write_probe`
# could legitimately exist in someone's output dir).
import secrets
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 / f".rae_dry_run_probe_{os.getpid()}_{secrets.token_hex(4)}"
# If somehow this exact filename already exists, refuse to touch it.
if probe.exists():
raise FileExistsError(f"unique probe path collision: {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"
# `would_run.model` resolution mirrors the live capture path: each SDK
# has its own model config key, so picking `claude_code_model` for an
# opencode/copilot session would misreport what would actually run.
sdk_model_key = {
"claude": "claude_code_model",
"opencode": "opencode_model",
"copilot": "copilot_model",
"cursor": "cursor_model",
}.get(sdk, "claude_code_model")
sdk_default_model = {
"claude": "claude-sonnet-4-6",
"opencode": "claude-opus-4-6",
"copilot": "gpt-5",
"cursor": "composer-2.5",
}.get(sdk, "claude-sonnet-4-6")
resolved_model = model or config_manager.get(sdk_model_key, sdk_default_model)
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": resolved_model,
"output_dir": str(base),
"headless": headless,
},
"checks": checks,
}
def _build_agent_payload(
result: dict | None,
*,
prompt: str | None,
url: str | None,
output_dir: str | None = None,
error: str | BaseException | None = None,
error_kind_hint: str = "unknown",
) -> dict:
"""Normalize an agent capture result into a stable JSON shape.
`output_dir` must match the value passed to the underlying capture so the
HAR path is resolved against the user's chosen run root, not the default.
"""
result = result or {}
run_id = result.get("run_id")
inner_error = result.get("error")
final_error_obj = error if error is not None else inner_error
if final_error_obj is None and not run_id:
final_error_obj = "agent capture produced no run"
error_str = _format_error_message(final_error_obj)
error_kind = _classify_error(final_error_obj, default=error_kind_hint) if final_error_obj else None
har_path = None
if run_id:
candidate = get_har_dir(run_id, output_dir) / "recording.har"
har_path = str(candidate) if candidate.exists() else None
return {
"schema_version": AGENT_JSON_SCHEMA_VERSION,
"status": "error" if error_str else "ok",
"run_id": run_id,
"prompt": prompt,
"url": url,
"mode": result.get("mode"),
"har_path": har_path,
"script_path": result.get("script_path"),
"usage": _normalize_usage(result.get("usage")),
"error": error_str,
"error_kind": error_kind,
}
def _build_engineer_payload(
result: dict | None,
*,
run_id: str,
prompt: str | None,
fresh: bool,
error: str | BaseException | None = None,
error_kind_hint: str = "unknown",
) -> dict:
"""Normalize an engineer-mode result into a stable JSON shape.
Mirrors `_build_agent_payload`'s contract minus the agent-specific fields
(no `url`, no `mode`, no `har_path`). `prompt` is the value the user passed
to --prompt (which may have been used as either a full replacement or as
additional instructions depending on --fresh).
"""
result = result if isinstance(result, dict) else {}
inner_error = result.get("error")
final_error_obj = error if error is not None else inner_error
if final_error_obj is None and not result:
final_error_obj = "engineering produced no result"
error_str = _format_error_message(final_error_obj)
error_kind = _classify_error(final_error_obj, default=error_kind_hint) if final_error_obj else None
return {
"schema_version": AGENT_JSON_SCHEMA_VERSION,
"status": "error" if error_str else "ok",
"run_id": run_id,
"prompt": prompt,
"fresh": fresh,
"script_path": result.get("script_path"),
"usage": _normalize_usage(result.get("usage")),
"error": error_str,
"error_kind": error_kind,
}
def _build_run_payload(
*,
identifier: str,
run_id: str | None = None,
script_path: str | None = None,
script_args: tuple[str, ...] | list[str] = (),
returncode: int | None = None,
stdout: str | None = None,
stderr: str | None = None,
scripts: list[Path] | None = None,
error: str | BaseException | None = None,
error_kind_hint: str = "unknown",
) -> dict:
"""Normalize `run --json` output into a stable machine-readable shape."""
error_str = _format_error_message(error)
if error_str is None and returncode not in (None, 0):
error_str = f"script exited with code {returncode}"
error_kind = _classify_error(error, default=error_kind_hint) if error_str else None
if error_str and error is None:
error_kind = error_kind_hint
return {
"schema_version": AGENT_JSON_SCHEMA_VERSION,
"status": "error" if error_str else "ok",
"identifier": identifier,
"run_id": run_id,
"script_path": script_path,
"script_args": list(script_args),
"returncode": returncode,
"stdout": stdout,
"stderr": stderr,
"scripts": [
{
"name": p.name,
"path": str(p),
"size": p.stat().st_size if p.exists() else None,
"modified": p.stat().st_mtime if p.exists() else None,
}
for p in (scripts or [])
],
"error": error_str,
"error_kind": error_kind,
}
def _write_json_event(real_stdout: TextIO, payload: dict) -> None:
real_stdout.write(json.dumps(payload) + "\n")
real_stdout.flush()
# Mode definitions
MODES = ["agent", "manual", "engineer", "collector"]
MODE_DESCRIPTIONS = {
"manual": "full pipeline",
"engineer": "reverse engineer only",
"agent": "autonomous agent + capture",
"collector": "ai-powered data collection",
}
AGENT_TASK_SUGGESTIONS = [
"Go to github.com/trending and capture the top 10 trending repos' API calls",
"Navigate to news.ycombinator.com, browse the front page and capture API interactions",
"Go to weather.com, search for New York weather and capture the forecast API",
"Visit reddit.com/r/programming, browse posts and capture the Reddit API calls",
"Go to maps.google.com, search for restaurants near Times Square and capture API calls",
"Navigate to twitter.com/explore and capture trending topics API interactions",
"Go to amazon.com, search for 'mechanical keyboard' and capture product search API",
"Visit spotify.com/search, search for an artist and capture the search API",
"Navigate to stackoverflow.com, search for 'python async' and capture the search API",
"Go to npmjs.com, search for 'express' and capture the package registry API",
"Visit producthunt.com and capture the feed/listing API calls",
"Go to crunchbase.com and browse company profiles to capture their API",
"Navigate to linkedin.com/jobs, search for 'software engineer' and capture job search API",
"Go to airbnb.com, search for stays in Paris and capture the listing search API",
"Visit imdb.com, search for a movie and capture the title/search API calls",
"Go to wolframalpha.com, run a query and capture the computation API",
"Navigate to booking.com, search for hotels in Tokyo and capture the search API",
"Go to zillow.com, search for homes in San Francisco and capture the listing API",
"Visit translate.google.com, translate a paragraph and capture the translation API",
"Go to unsplash.com, search for 'mountains' and capture the photo search API",
]
def prompt_interactive_options( # noqa: C901 — long questionary flow; split when it is next touched
prompt: str | None = None,
url: str | None = None,
reverse_engineer: bool | None = None,
model: str | None = None,
current_mode: str = "agent",
) -> dict:
"""Prompt user for essential options interactively (Browgents style).
Shift+Tab cycles through modes: manual ↔ engineer ↔ agent
"""
# Slash command completer
commands = [
"/settings",
"/history",
"/messages",
"/help",
"/exit",
"/quit",
"/commands",
]
class EnhancedCompleter(Completer):
"""Autocomplete for slash commands and run IDs."""
def get_completions(self, document: Document, complete_event: CompleteEvent) -> Iterable[Completion]:
text = document.text_before_cursor
# Slash command completion
if text.startswith("/"):
# Check if we're after /messages command
if text.startswith("/messages "):
# Run ID completion for /messages
run_id_prefix = text[10:] # Everything after "/messages "
for run_id in self._get_run_ids():
if run_id.startswith(run_id_prefix):
yield Completion(
run_id,
start_position=-len(run_id_prefix),
display_meta=self._get_run_meta(run_id),
)
elif " " not in text:
# Regular slash command completion (no space yet)
for cmd in commands:
if cmd.startswith(text):
yield Completion(cmd, start_position=-len(text))
# Run-id completion in engineer mode
elif mode_state["mode"] == "engineer" and text:
for run_id in self._get_run_ids():
if run_id.startswith(text):
yield Completion(
run_id,
start_position=-len(text),
display_meta=self._get_run_meta(run_id),
)
def _get_run_ids(self) -> list[str]:
"""Get all run IDs from history (newest first)."""
try:
history = session_manager.get_history(limit=50)
return [run["run_id"] for run in history]
except Exception:
return []
def _get_run_meta(self, run_id: str) -> str:
"""Get metadata for a run ID (timestamp + prompt snippet)."""
try:
run = session_manager.get_run(run_id)
if run:
timestamp = run.get("timestamp", "")[:16] # YYYY-MM-DD HH:MM
prompt = run.get("prompt", "")[:30]
return f"[{timestamp}] {prompt}"
except Exception:
pass
return ""
command_completer = EnhancedCompleter()
# Track mode state (mutable container for closure)
mode_state: PromptModeState = {"mode": current_mode, "mode_index": MODES.index(current_mode)}
# Create key bindings for mode cycling and autocomplete
kb = KeyBindings()
@kb.add("s-tab") # Shift+Tab
def cycle_mode(event: KeyPressEvent) -> None:
"""Cycle to next mode."""
mode_state["mode_index"] = (mode_state["mode_index"] + 1) % len(MODES)
mode_state["mode"] = MODES[mode_state["mode_index"]]
# Force prompt refresh by invalidating the app
event.app.invalidate()
@kb.add("right") # Right arrow
def accept_completion(event: KeyPressEvent) -> None:
"""Accept the current autocomplete suggestion with right arrow."""
buff = event.app.current_buffer
if buff.complete_state:
# Save the current completion before closing
completion = buff.complete_state.current_completion
if completion:
buff.apply_completion(completion)
else:
# No completion selected, just move cursor right
buff.cursor_right()
else:
# If no completion, just move cursor right
buff.cursor_right()
@kb.add("c-r") # Ctrl+R: random task suggestion (agent mode)
def random_suggestion(event: KeyPressEvent) -> None:
"""Fill prompt with a random task suggestion for agent mode."""
if mode_state["mode"] == "agent":
suggestion = random.choice(AGENT_TASK_SUGGESTIONS)
buff = event.app.current_buffer
buff.text = suggestion
buff.cursor_position = len(suggestion)
def get_prompt() -> HTML:
"""Generate prompt with current mode indicator."""
mode = mode_state["mode"]
mode_color = MODE_COLORS.get(mode, THEME_PRIMARY)
return HTML(f'<style fg="{mode_color}">[{mode}]</style> <style fg="{mode_color}" bold="true">></style> ')
if prompt is None:
pt_style = PtStyle.from_dict(
{
"prompt": f"{THEME_PRIMARY} bold",
"": THEME_SECONDARY,
}
)
session: PromptSession[str] = PromptSession(
message=get_prompt, # Dynamic prompt function
completer=command_completer,
auto_suggest=AutoSuggestFromHistory(),
complete_while_typing=True,
style=pt_style,
key_bindings=kb,
)
prompt = session.prompt()
if prompt is None: # Handle Ctrl+D or Ctrl+C if not caught
raise click.Abort()
prompt = prompt.strip()
if not prompt:
return {"command": "/empty", "mode": mode_state["mode"]}
if prompt.startswith("/"):
return {"command": prompt.lower(), "mode": mode_state["mode"]}
# Return mode in all cases
result_mode = mode_state["mode"]
# Engineer mode: prompt is the run_id
if result_mode == "engineer":
_sdk = config_manager.get("sdk", "claude")
resolved = model or default_model_for_configured_sdk(_sdk)
return {
"mode": result_mode,
"run_id": prompt,
"model": resolved,
}
# Agent mode: autonomous browser, no URL needed (agent navigates on its own)
if result_mode == "agent":
if model is None:
_sdk = config_manager.get("sdk", "claude")
model = default_model_for_configured_sdk(_sdk)
mode_color = MODE_COLORS.get("agent", THEME_PRIMARY)
console = Console()
console.print(f" [{mode_color}]autonomous[/{mode_color}] [dim]agent will navigate on its own[/dim]")
return {
"mode": result_mode,
"prompt": prompt,
"url": url if url else None,
"reverse_engineer": False, # Agent mode doesn't auto-reverse engineer
"model": model,
}
# Collector mode: just needs prompt
if result_mode == "collector":
if model is None:
model = config_manager.get("collector_model", "claude-sonnet-4-6")
return {
"mode": result_mode,
"prompt": prompt,
"model": model,
}
# Manual mode: need URL
if url is None:
try:
url = questionary.text(
" > url",
instruction="(Enter for none)",
qmark="",
style=questionary.Style(
[
("question", f"fg:{THEME_SECONDARY}"),
("instruction", f"fg:{THEME_DIM} italic"),
]
),
).ask()
if url is None: # questionary returns None on Ctrl+C
raise click.Abort()
except KeyboardInterrupt:
raise click.Abort() from None
# Use settings defaults for the rest
if reverse_engineer is None:
reverse_engineer = True
if model is None:
_sdk = config_manager.get("sdk", "claude")
model = default_model_for_configured_sdk(_sdk)
return {
"mode": result_mode,
"prompt": prompt,
"url": url if url else None,
"reverse_engineer": reverse_engineer,
"model": model,
}
CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
@click.group(invoke_without_command=True, context_settings=CONTEXT_SETTINGS)
@click.pass_context
@click.version_option(version=__version__)
@click.option(
"--json-schema-version",
"show_schema_version",
is_flag=True,
help="Print the agent/engineer JSON schema_version this binary emits and exit.",
)
def main(ctx: click.Context, show_schema_version: bool) -> None:
"""reverse-api-engineer: reverse engineer apis.
Run without a subcommand to start the interactive REPL; use agent, manual,
engineer, or collector mode interactively.
Scripted flags are subcommand-specific: agent, engineer, and run support
--json, --json-stream, and --no-interactive; list/show support --json.
Set RAE_DEBUG=1 to include unexpected agent failure tracebacks on stderr.
See `<cmd> --help` for details. Wrappers that need to gate on the payload
schema can call `reverse-api-engineer
--json-schema-version`.
"""
if show_schema_version:
click.echo(str(AGENT_JSON_SCHEMA_VERSION))
ctx.exit(0)
if ctx.invoked_subcommand is None:
# Refuse to drop into the prompt_toolkit REPL when stdin is not a TTY:
# without an interactive terminal the REPL would block on stdin
# forever (e.g. CI invocations, agent wrappers that forgot the
# subcommand). Print --help to stderr and exit 2 (misuse).
if not sys.stdin.isatty():
click.echo(ctx.get_help(), err=True)
click.echo(
"\nerror: no subcommand given and stdin is not a TTY; "
"the interactive REPL requires a terminal.",
err=True,
)
sys.exit(2)
repl_loop()
def repl_loop() -> None:
"""Main interactive loop for the CLI."""
from concurrent.futures import ThreadPoolExecutor
# Start update check in background to avoid blocking startup
update_executor = ThreadPoolExecutor(max_workers=1)
update_future = update_executor.submit(check_for_updates)
# Get current SDK and model from config
sdk = config_manager.get("sdk", "claude")
model = default_model_for_configured_sdk(sdk)
display_banner(console, sdk=sdk, model=model)
console.print(" [dim]shift+tab to cycle modes | ctrl+r for random task (agent)[/dim]")
display_footer(console)
# Show update message if background check has completed
try:
update_msg = update_future.result(timeout=0.5)
if update_msg:
console.print(f" [yellow]{update_msg}[/yellow]")
console.print()
except Exception:
pass # Timed out or failed — don't block startup
finally:
update_executor.shutdown(wait=False)
current_mode = "agent"
while True:
try:
options = prompt_interactive_options(current_mode=current_mode)
# Update current mode for next iteration
current_mode = options.get("mode", "agent")
if "command" in options:
cmd = options["command"]
mode_color = MODE_COLORS.get(current_mode, THEME_PRIMARY)
if cmd == "/empty":
continue
if cmd == "/exit" or cmd == "/quit":
return # Exit the loop and return to main
elif cmd == "/settings":
handle_settings(mode_color)
elif cmd == "/history":
handle_history(mode_color)
elif cmd == "/help" or cmd == "/commands":
handle_help(mode_color)
elif cmd.startswith("/messages"):
parts = cmd.split(maxsplit=1)
if len(parts) > 1:
handle_messages(parts[1].strip(), mode_color)
else:
console.print(" [red]usage:[/red] /messages <run_id>")
else:
# Unknown command - show error and available commands
console.print(f" [red]Unknown command:[/red] {cmd}")
console.print(" [dim]Available commands: /settings, /history, /messages, /help, /commands, /exit[/dim]")
continue
mode = options.get("mode", "agent")
# Handle different modes
if mode == "engineer":
raw_input = options.get("run_id")
if not raw_input:
console.print(" [dim]Usage:[/dim] <run_id> (switch context)")
console.print(" [dim] [/dim] <prompt> (re-engineer the latest run)")
continue
# Two cases: input matches a known run_id (switch context) or
# it's free text (additive instructions on the latest run).
if session_manager.get_run(raw_input):
target_run_id = raw_input
add_instr = None
else:
latest = session_manager.get_history(limit=1)
if not latest:
console.print(" [red]error:[/red] no runs found in history")
continue
target_run_id = latest[0]["run_id"]
add_instr = raw_input
run_engineer(
target_run_id,
model=options.get("model"),
additional_instructions=add_instr,
)
continue
if mode == "agent":
# Agent mode: run autonomous browser agent
run_agent_capture(
prompt=options["prompt"],
url=options.get("url"),
model=options.get("model"),
)
continue
if mode == "collector":
# Collector mode: AI-powered data collection
run_collector(
prompt=options["prompt"],
model=options.get("model"),
)
continue
# Manual mode: run browser capture
run_manual_capture(
prompt=options["prompt"],
url=options["url"],
reverse_engineer=options["reverse_engineer"],
model=options["model"],
)
except (click.Abort, KeyboardInterrupt):
console.print("\n [dim]terminated[/dim]")
return
except Exception as e:
console.print(f" [red]error:[/red] {escape(str(e))}")
console.print(f" [dim]{ERROR_CTA}[/dim]")
def handle_settings(mode_color: str = THEME_PRIMARY) -> None:
"""Keep the settings menu open until the user explicitly goes back."""
while _handle_settings_action(mode_color):
pass
def _handle_settings_action(mode_color: str = THEME_PRIMARY) -> bool: # noqa: C901 — one branch per settings menu entry; split when next touched
"""Display and manage settings with improved layout and descriptions."""
from rich.table import Table
console.print()
# Create a table for current configuration
config_table = Table(show_header=False, box=None, padding=(0, 1))
config_table.add_column(style="dim", justify="left")
config_table.add_column(style=mode_color, justify="left")
# Sort config items alphabetically by key
for k, v in sorted(config_manager.config.items()):
display_val = str(v) if v is not None else "default"
# Make the key more readable
key_display = k.replace("_", " ").title()
config_table.add_row(key_display, display_val)
# Display in a clean format
console.print(" [bold white]Settings[/bold white] [dim]Current Configuration[/dim]")
console.print(config_table)
console.print()
# Settings menu (sorted alphabetically)
choices = [
Choice(title="Agent Provider", value="agent_provider"),
Choice(title="Claude Code Model", value="claude_code_model"),
Choice(title="Copilot Model", value="copilot_model"),
Choice(title="Cursor Model", value="cursor_model"),
Choice(title="Cursor Web Search", value="cursor_web_search"),
Choice(title="OpenCode Provider / Model", value="opencode_pair"),
Choice(title="Output Directory", value="output_dir"),
Choice(title="Output Language", value="output_language"),
Choice(title="Real-time Sync", value="real_time_sync"),
Choice(title="SDK", value="sdk"),
Choice(title="Back", value="back"),
]
action = questionary.select(
" ", # Add padding via the question prompt
choices=choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
("selected", "fg:white"),
("question", ""), # Hide the question text styling
]
),
).ask()
if action is None or action == "back":
return False # Exit settings to main prompt
if action == "claude_code_model":
model_choices = [Choice(title=c["name"].lower(), value=c["value"]) for c in get_model_choices()]
model_choices.append(Choice(title="back", value="back"))
model = questionary.select(
"",
choices=model_choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if model and model != "back":
config_manager.set("claude_code_model", model)
console.print(f" [dim]updated[/dim] {model}\n")
elif action == "sdk":
sdk_choices = [
Choice(title="claude", value="claude"),
Choice(title="copilot", value="copilot"),
Choice(title="cursor", value="cursor"),
Choice(title="opencode", value="opencode"),
Choice(title="back", value="back"),
]
sdk = questionary.select(
"",
choices=sdk_choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if sdk and sdk != "back":
config_manager.set("sdk", sdk)
console.print(f" [dim]updated[/dim] sdk: {sdk}\n")
elif action == "output_language":
lang_choices = [
Choice(title="python", value="python"),
Choice(title="javascript", value="javascript"),
Choice(title="typescript", value="typescript"),
Choice(title="go", value="go"),
Choice(title="java", value="java"),
Choice(title="csharp", value="csharp"),
Choice(title="php", value="php"),
Choice(title="ruby", value="ruby"),
Choice(title="c", value="c"),
Choice(title="powershell", value="powershell"),
Choice(title="back", value="back"),
]
lang = questionary.select(
"",
choices=lang_choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if lang and lang != "back":
config_manager.set("output_language", lang)
console.print(f" [dim]updated[/dim] output language: {lang}\n")
elif action == "agent_provider":
provider_choices = [
Choice(title="auto (Playwright MCP)", value="auto"),
Choice(title="chrome-mcp (Chrome DevTools MCP)", value="chrome-mcp"),
Choice(title="agent-browser (Vercel CLI via shell/Bash)", value="agent-browser"),
Choice(title="back", value="back"),
]
provider = questionary.select(
"",
choices=provider_choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if provider and provider != "back":
config_manager.set("agent_provider", provider)
console.print(f" [dim]updated[/dim] agent provider: {provider}")
if provider == "agent-browser":
console.print()
console.print(
" [dim]Browsing runs through Vercel's agent-browser CLI (not an MCP shim).[/dim]"
)
console.print(
" [dim]On first agent run RAE installs the CLI with `npm install -g <pin>` when "
"`agent-browser` is missing (you’ll see a banner), then reuses the global shim.[/dim]"
)
console.print(
" [dim]Pin via `agent_browser_npx_package` in config or `RAE_AGENT_BROWSER_PACKAGE` env.[/dim]"
)
console.print(
" [dim]Extra operator hints (cloud backends, corp proxy…): "
"`agent_browser_notes` or `RAE_AGENT_BROWSER_NOTES`.[/dim]"
)
console.print(
" [dim]Chrome download: `agent-browser install` once (add `--with-deps` on Linux).[/dim]"
)
console.print()
elif provider == "chrome-mcp":
console.print()
console.print(" [dim]chrome devtools mcp setup:[/dim]")
console.print(" [dim] 1. open chrome (version 146 or newer)[/dim]")
console.print(" [dim] 2. go to chrome://inspect/#remote-debugging[/dim]")
console.print(' [dim] 3. click "Enable auto-connect"[/dim]')
console.print(" [dim] 4. node.js v20.19+ required[/dim]")
console.print()
console.print(" [dim]the agent will connect to your real chrome browser.[/dim]")
console.print(" [dim]existing sessions, cookies, and auth will be available.[/dim]")
console.print(" [dim]avoid browsing sensitive sites while the agent is active.[/dim]")
console.print()
elif action == "opencode_pair":
pair = _select_opencode_pair_for_settings(mode_color)
if pair is not None:
provider_id, model_id = pair
config_manager.update({"opencode_provider": provider_id, "opencode_model": model_id})
console.print(f" [dim]updated[/dim] opencode: {provider_id}/{model_id}\n")
elif action == "copilot_model":
current = config_manager.get("copilot_model", "gpt-5")
new_model = questionary.text(
" > copilot model",
default=current or "gpt-5",
instruction="(e.g., 'gpt-5', 'gpt-4.1')",
qmark="",
style=questionary.Style(
[
("question", f"fg:{THEME_SECONDARY}"),
("instruction", f"fg:{THEME_DIM} italic"),
]
),
).ask()
if new_model is not None:
new_model = new_model.strip()
if not new_model:
console.print(" [yellow]error:[/yellow] copilot model cannot be empty\n")
else:
config_manager.set("copilot_model", new_model)
console.print(f" [dim]updated[/dim] copilot model: {new_model}\n")
elif action == "cursor_model":
current = config_manager.get("cursor_model", "composer-2.5")
new_model = questionary.text(
" > cursor model",
default=current or "composer-2.5",
instruction="(e.g., 'composer-2.5', 'composer-2' — see Cursor SDK docs)",
qmark="",
style=questionary.Style(
[
("question", f"fg:{THEME_SECONDARY}"),
("instruction", f"fg:{THEME_DIM} italic"),
]
),
).ask()
if new_model is not None:
new_model = new_model.strip()
if not new_model:
console.print(" [yellow]error:[/yellow] cursor model cannot be empty\n")
else:
config_manager.set("cursor_model", new_model)
console.print(f" [dim]updated[/dim] cursor model: {new_model}\n")
elif action == "cursor_web_search":
pick = questionary.select(
"",
choices=[
Choice(title="On — WebFetch/WebSearch + plugins/team settings", value=True),
Choice(title="Off — project + user Cursor settings only", value=False),
Choice(title="back", value="back"),
],
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if pick is not None and pick != "back":
config_manager.set("cursor_web_search", pick)
console.print(f" [dim]updated[/dim] cursor web search: {'on' if pick else 'off'}\n")
elif action == "real_time_sync":
current = config_manager.get("real_time_sync", True)
sync_choices = [
Choice(title="Enabled", value=True),
Choice(title="Disabled", value=False),
Choice(title="Back", value="back"),
]
sync = questionary.select(
"",
choices=sync_choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
]
),
).ask()
if sync is not None and sync != "back":
config_manager.set("real_time_sync", sync)
status = "enabled" if sync else "disabled"
console.print(f" [dim]updated[/dim] real-time sync: {status}\n")
elif action == "output_dir":
current = config_manager.get("output_dir")
new_dir = questionary.text(
" > output directory",
default=current or "",
instruction="(Enter for default ~/.reverse-api/runs)",
qmark="",
style=questionary.Style(
[
("question", f"fg:{THEME_SECONDARY}"),
("instruction", f"fg:{THEME_DIM} italic"),
]
),
).ask()
if new_dir is not None:
config_manager.set("output_dir", new_dir if new_dir.strip() else None)
console.print(" [dim]updated[/dim] output directory\n")
return True
def handle_history(mode_color: str = THEME_PRIMARY) -> None:
"""Display history of runs."""
history = session_manager.get_history(limit=15)
if not history:
console.print(" [dim]> no logs found[/dim]")
return
choices = []
for run in history:
cost = run.get("usage", {}).get("estimated_cost_usd", 0)
cost_str = f"${cost:.3f}" if cost > 0 else "-"
title = f"{run['run_id']:12} {run['prompt'][:40]:40} {cost_str:>8}"
choices.append(Choice(title=title, value=run["run_id"]))
choices.append(Choice(title="back", value="back"))
run_id = questionary.select(
"",
choices=choices,
pointer=">",
qmark="",
style=questionary.Style(
[
("pointer", f"fg:{mode_color} bold"),
("highlighted", f"fg:{mode_color} bold"),
("selected", "fg:white"),
]
),
).ask()
if not run_id or run_id == "back":
return
selected_run = session_manager.get_run(run_id)
if selected_run:
run = selected_run
from rich.table import Table
# Create a formatted display of the run details
details_table = Table(show_header=False, box=None, padding=(0, 1))
details_table.add_column(style="dim", justify="left", width=20)
details_table.add_column(style="white", justify="left")
details_table.add_row("Run ID", run.get("run_id", "-"))
details_table.add_row("Timestamp", run.get("timestamp", "-"))
details_table.add_row("Prompt", run.get("prompt", "-"))
details_table.add_row("Model", run.get("model", "-"))
details_table.add_row("Mode", run.get("mode", "-"))
usage = run.get("usage", {})
if usage:
cost = usage.get("estimated_cost_usd", 0)
details_table.add_row("Cost", f"${cost:.4f}" if cost > 0 else "-")
input_tokens = usage.get("input_tokens", 0)
output_tokens = usage.get("output_tokens", 0)
if input_tokens or output_tokens:
details_table.add_row("Tokens", f"{input_tokens:,} in / {output_tokens:,} out")
console.print()
console.print(" [bold white]Run Details[/bold white]")
console.print(details_table)
console.print()
if questionary.confirm(" > recode?", qmark="").ask():
model = run.get("model") or config_manager.get("claude_code_model", "claude-sonnet-4-6")
run_engineer(run_id, model=model)
else:
console.print(" [dim]> not found[/dim]")
def handle_help(mode_color: str = THEME_PRIMARY) -> None:
"""Show enhanced help with command details and examples."""
from rich.table import Table
console.print()
# Commands table
commands_table = Table(show_header=False, box=None, padding=(0, 1))
commands_table.add_column(style=f"{mode_color} bold", justify="left", width=20)
commands_table.add_column(style="white", justify="left")
commands_table.add_row(
"/settings",
"Configure model, SDK, agent provider, and sync settings\n[dim]Usage: /settings[/dim]",
)
commands_table.add_row("", "") # Spacing
commands_table.add_row(
"/history",
"View past runs with timestamps, costs, and status\n[dim]Usage: /history[/dim]",
)
commands_table.add_row("", "")
commands_table.add_row(
"/messages <run_id>",
"View detailed message logs from a specific run\n[dim]Usage: /messages abc123[/dim]",
)
commands_table.add_row("", "")
commands_table.add_row(
"/help or /commands",
"Show this help message\n[dim]Usage: /help[/dim]",
)
commands_table.add_row("", "")
commands_table.add_row("/exit or /quit", "Exit the application\n[dim]Usage: /exit[/dim]")
console.print(" [bold white]Available Commands[/bold white]")
console.print(commands_table)
# Modes table
console.print()
modes_table = Table(show_header=False, box=None, padding=(0, 1))
modes_table.add_column(style=f"{mode_color} bold", justify="left", width=15)
modes_table.add_column(style="dim", justify="left")
modes_table.add_row("agent", "Autonomous agent + capture")
modes_table.add_row("manual", "Full pipeline: browser + reverse engineering")
modes_table.add_row("engineer", "Reverse engineer only (enter run_id)")
modes_table.add_row("collector", "AI-powered data collection")
console.print(" [bold white]Modes[/bold white] [dim]Shift+Tab to cycle[/dim]")
console.print(modes_table)
console.print()
def handle_messages(run_id: str, mode_color: str = THEME_PRIMARY) -> None:
"""Display messages from a previous run."""
from rich.table import Table
store = MessageStore(run_id)
messages = store.load()
if not messages:
console.print(f" [dim]>[/dim] [red]no messages found for run:[/red] {run_id}")
return
# Create header panel
header_table = Table(show_header=False, box=None, padding=(0, 0))
header_table.add_column(style="white", justify="left")
header_table.add_row(f"Run ID: {run_id}")
header_table.add_row(f"Total Messages: {len(messages)}")
console.print()
console.print(" [bold white]Message Log[/bold white]")
console.print(header_table)
console.print()
for msg in messages:
msg_type = msg.get("type", "unknown")
content = msg.get("content", "")
timestamp = msg.get("timestamp", "")[:19] # Truncate to datetime
if msg_type == "prompt":
console.print(f" [dim]{timestamp}[/dim] [white]prompt[/white]")
# Show first 200 chars of prompt
display = str(content)[:200]
if len(str(content)) > 200:
display += "..."
console.print(f" [dim]{display}[/dim]")
elif msg_type == "tool_start":
name = content.get("name", "tool")
console.print(f" [dim]{timestamp}[/dim] [white]{name.lower()}[/white]")
elif msg_type == "tool_result":
name = content.get("name", "tool")
is_error = content.get("is_error", False)
status = "[red]error[/red]" if is_error else "[dim]ok[/dim]"
console.print(f" [dim]{timestamp}[/dim] {status}")
elif msg_type == "thinking":
display = str(content)[:100].replace("\\n", " ")
if len(str(content)) > 100:
display += "..."
console.print(f" [dim]{timestamp} .. {display}[/dim]")
elif msg_type == "error":
console.print(f" [dim]{timestamp}[/dim] [red]error: {escape(str(content))}[/red]")
elif msg_type == "result":
console.print(f" [dim]{timestamp}[/dim] [white]complete[/white]")
if isinstance(content, dict):
script_path = content.get("script_path", "")
if script_path:
console.print(f" [dim]{script_path}[/dim]")
console.print()
@main.command(
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" | "agent-browser" | null,
"har_path": "/abs/path/recording.har" | null,
"script_path": "/abs/path/api_client.py" | null,
"usage": {
"input_tokens": ...,
"output_tokens": ...,
"cache_read_tokens": ...,
"cache_write_tokens": ...,
"total_cost_usd": ...,
"raw": { ... }
},
"error": "<message>" | null,
"error_kind": "misuse" | "config_invalid" | "permission_denied" | "network" | "engine_failure" | "interrupted" | "unknown" | 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(
"--model",
"-m",
type=click.Choice(["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"]),
default=None,
)
@click.option("--output-dir", "-o", default=None, help="Custom output directory.")
@click.option(
"--no-interactive",
is_flag=True,
help="Fail fast instead of prompting for missing inputs (intended for scripted/agent usage).",
)
@click.option(
"--json",
"as_json",
is_flag=True,
help="Emit a single JSON result on stdout (logs go to stderr). Implies --no-interactive.",
)
@click.option(
"--json-stream",
"json_stream",
is_flag=True,
help="Emit NDJSON progress events on stdout during the run, then a final {\"event\":\"result\",...} line. Implies --no-interactive.",
)
@click.option(
"--headless",
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."
),
)
@click.option(
"--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: str | None,
url: str | None,
model: str | None,
output_dir: str | None,
no_interactive: bool,
as_json: bool,
json_stream: bool,
headless: bool,
dry_run: bool,
) -> None:
"""Run autonomous agent browser session.
Agent mode runs an integrated capture + reverse-engineering pipeline.
"""
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 or json_stream
machine_output = as_json or json_stream
if no_interactive and not (prompt and prompt.strip()):
if machine_output:
misuse = _build_agent_payload(
{},
prompt=prompt,
url=url,
output_dir=output_dir,
error="--prompt is required in non-interactive/--json mode",
error_kind_hint="misuse",
)
if json_stream:
misuse = {"event": "result", **misuse}
click.echo(json.dumps(misuse))
else:
click.echo("error: --prompt is required when --no-interactive is set", err=True)
sys.exit(2)
# Either flag must suppress the post-generation follow-up prompt that would
# otherwise block on stdin (`input(" > ")`) inside ClaudeAutoEngineer.
interactive = not no_interactive
if not machine_output:
result = run_agent_capture(
prompt=prompt,
url=url,
model=model,
output_dir=output_dir,
interactive=interactive,
headless=headless,
)
if isinstance(result, dict) and "error" in result:
if interactive and result["error"] == "interrupted":
return
if not result.get("error_reported"):
click.echo(f"error: {result['error'] or 'Agent analysis failed.'}", err=True)
sys.exit(1)
return
from .json_stream import make_json_stream_sink
with _quiet_consoles_for_json() as real_stdout:
sink = (
make_json_stream_sink(lambda line: _write_json_line(real_stdout, line))
if json_stream
else None
)
try:
result = run_agent_capture(
prompt=prompt,
url=url,
model=model,
output_dir=output_dir,
interactive=interactive,
headless=headless,
json_event_sink=sink,
)
payload = _build_agent_payload(result, prompt=prompt, url=url, output_dir=output_dir)
except KeyboardInterrupt as e:
payload = _build_agent_payload(
{}, prompt=prompt, url=url, output_dir=output_dir, error=e
)
except Exception as e:
# Pass the exception object so _classify_error can use isinstance
# (PermissionError → permission_denied, ConnectionError → network, ...)
payload = _build_agent_payload(
{}, prompt=prompt, url=url, output_dir=output_dir, error=e
)
_write_json_stdout(real_stdout, payload, json_stream=json_stream)
sys.exit(0 if payload["status"] == "ok" else 1)
@main.command(
epilog="""\b
Examples:
reverse-api-engineer collector -p "collect companies hiring browser automation engineers"
reverse-api-engineer collector
"""
)
@click.option("--prompt", "-p", default=None, help="Collection instructions.")
@click.option(
"--model",
"-m",
type=click.Choice(["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"]),
default=None,
)
@click.option("--output-dir", "-o", default=None, help="Custom output directory for run metadata and messages.")
def collector(prompt: str | None, model: str | None, output_dir: str | None) -> None:
"""Run AI-powered data collection."""
if prompt is None:
if not sys.stdin.isatty():
click.echo("error: --prompt is required when stdin is not a TTY", err=True)
sys.exit(2)
options = prompt_interactive_options(
prompt=None,
model=model,
current_mode="collector",
)
if "command" in options:
return
prompt = options["prompt"]
model = options.get("model") or model
result = run_collector(prompt=prompt, model=model, output_dir=output_dir)
if result is None or (isinstance(result, dict) and result.get("error")):
sys.exit(1)
def run_manual_capture(
prompt: str | None = None,
url: str | None = None,
reverse_engineer: bool = True,
model: str | None = None,
output_dir: str | None = None,
) -> None:
"""Shared logic for manual capture."""
output_dir = output_dir or config_manager.get("output_dir")
# Manual mode drives a local Playwright browser, which ships in the optional
# [manual] extra. Fail fast — before prompting the user or recording a run —
# so a base-only install never leaves a phantom "manual" run in history.
try:
from .browser import ManualBrowser
except ImportError as exc:
raise click.ClickException(
"Manual capture mode requires the Playwright browser stack, which is "
"not installed by default. Install it with:\n\n"
" pip install 'reverse-api-engineer[manual]'\n"
" playwright install chromium\n\n"
"(Agent mode does not need this.)"
) from exc
if prompt is None:
options = prompt_interactive_options(
prompt=prompt,
url=url,
reverse_engineer=reverse_engineer,
model=model,
)
if "command" in options:
return # Should not happen from here
prompt = options["prompt"]
url = options["url"]
reverse_engineer = options["reverse_engineer"]
model = options["model"]
run_id = generate_run_id()
timestamp = get_timestamp()
sdk = config_manager.get("sdk", "claude")
# Record initial session
session_manager.add_run(
run_id=run_id,
prompt=prompt,
timestamp=timestamp,
url=url,
model=model,
mode="manual", # Track mode in history
sdk=sdk,
paths={"har_dir": str(get_har_dir(run_id, output_dir))},
)
browser = ManualBrowser(run_id=run_id, prompt=prompt, output_dir=output_dir)
har_path = browser.start(start_url=url)
if reverse_engineer:
result = run_engineer(
run_id=run_id,
har_path=har_path,
prompt=prompt,
model=model,
output_dir=output_dir,
)
if result:
sdk = config_manager.get("sdk", "claude")
session_manager.update_run(
run_id=run_id,
sdk=sdk,
usage=result.get("usage", {}),
paths={"script_path": result.get("script_path")},
)
else:
console.print(" [dim]>[/dim] [white]recording complete[/white]")
console.print(f" [dim]>[/dim] [white]run_id: {run_id}[/white]")
console.print(f" [dim]>[/dim] [dim]use 'reverse-api-engineer engineer {run_id}' to engineer later[/dim]\n")
def run_agent_capture(
prompt: str | None = None,
url: str | None = None,
model: str | None = None,
output_dir: str | None = None,
interactive: bool = True,
headless: bool = False,
json_event_sink: Callable[[dict[str, Any]], None] | None = None,
) -> dict[str, Any] | None:
"""Shared logic for agent capture mode."""
output_dir = output_dir or config_manager.get("output_dir")
if prompt is None:
options = prompt_interactive_options(
prompt=prompt,
url=url,
reverse_engineer=False,
model=model,
)
if "command" in options:
return None
prompt = options["prompt"]
url = options["url"]
model = options["model"]
agent_provider = config_manager.get("agent_provider", "auto")
return run_auto_capture(
prompt=prompt,
url=url,
model=model,
output_dir=output_dir,
agent_provider=agent_provider,
interactive=interactive,
headless=headless,
json_event_sink=json_event_sink,
)
def run_collector(prompt: str | None = None, model: str | None = None, output_dir: str | None = None) -> dict[str, Any] | None:
"""Run AI-powered data collection with Collector class."""
from .collector import Collector
# Generate run ID
run_id = generate_run_id()
output_dir = output_dir or config_manager.get("output_dir")
# Use collector model from config if not specified
if model is None:
model = config_manager.get("collector_model", "claude-sonnet-4-6")
# Initialize session
session_manager.add_run(
run_id=run_id,
prompt=prompt or "",
mode="collector",
timestamp=get_timestamp(),
)
try:
# Run collector
collector = Collector(
run_id=run_id,
prompt=prompt or "",
model=model,
output_dir=output_dir,
)
result = asyncio.run(collector.run())
if result and not result.get("error"):
# Update session with results
session_manager.update_run(
run_id=run_id,
sdk="claude",
usage=result.get("usage", {}),
paths={"output_path": result.get("output_path")},
)
return result
except Exception as e:
console.print(f" [red]collector error: {escape(str(e))}[/red]")
console.print(f" [dim]{ERROR_CTA}[/dim]")
import traceback
traceback.print_exc()
return {
"run_id": run_id,
"error": str(e) or type(e).__name__,
}
def run_auto_capture(
prompt: str | None = None,
url: str | None = None,
model: str | None = None,
output_dir: str | None = None,
agent_provider: str = "auto",
interactive: bool = True,
headless: bool = False,
json_event_sink: Callable[[dict[str, Any]], None] | None = None,
) -> dict[str, Any] | None:
"""Auto mode: LLM-driven browser automation + real-time reverse engineering."""
output_dir = output_dir or config_manager.get("output_dir")
if prompt is None:
options = prompt_interactive_options(
prompt=prompt,
url=url,
reverse_engineer=False,
model=model,
)
if "command" in options:
return None
prompt = options["prompt"]
url = options.get("url")
model = options["model"]
if agent_provider == "chrome-mcp" and not headless:
console.print()
console.print(" [dim]chrome devtools mcp (auto-connect)[/dim]")
console.print(" [dim]controlling your real chrome browser[/dim]")
console.print(" [dim]existing sessions, cookies, and auth available[/dim]")
console.print()
console.print(" [dim]auto-connect setup:[/dim]")
console.print(" [dim] 1. chrome 146+ required[/dim]")
console.print(" [dim] 2. go to chrome://inspect/#remote-debugging[/dim]")
console.print(' [dim] 3. click "Enable auto-connect"[/dim]')
console.print(" [dim] 4. node.js v20.19+[/dim]")
console.print()
console.print(" [dim]warning: the agent will execute actions on your browser[/dim]")
console.print(" [dim]avoid browsing sensitive sites during the session[/dim]")
console.print()
elif agent_provider == "chrome-mcp" and headless:
console.print()
console.print(" [dim]chrome devtools mcp (headless)[/dim]")
console.print(" [dim]auto-connect disabled — mcp will spawn its own headless chrome[/dim]")
console.print()
elif agent_provider == "agent-browser":
console.print()
console.print(
" [dim]agent-browser: Vercel CLI via shell (Reverse API Engineer does not attach "
"Playwright/Chrome browser MCP for this provider).[/dim]"
)
console.print(
" [dim]Startup prefers PATH `agent-browser`, otherwise installs via "
"`npm install -g <pin>` so Chromium pairs with a stable shim (with a banner); "
"only falls back to `npx -y` if npm cannot run.[/dim]"
)
console.print(
" [dim]First-time Chrome download: `agent-browser install` (add `--with-deps` on Linux).[/dim]"
)
console.print()
sdk = config_manager.get("sdk", "claude")
if model is None:
model = default_model_for_configured_sdk(sdk)
run_id = generate_run_id()
timestamp = get_timestamp()
if agent_provider == "chrome-mcp":
mode_label = "chrome-mcp"
elif agent_provider == "agent-browser":
mode_label = "agent-browser"
else:
mode_label = "auto"
session_manager.add_run(
run_id=run_id,
prompt=prompt,
timestamp=timestamp,
url=url,
model=model,
mode=mode_label,
paths={"har_dir": str(get_har_dir(run_id, output_dir))},
)
try:
output_language = config_manager.get("output_language", "python")
from .auto_engineer import ClaudeAutoEngineer, CopilotAutoEngineer, OpenCodeAutoEngineer
from .cursor_engineer import CursorAutoEngineer
engineer: ClaudeAutoEngineer | CopilotAutoEngineer | OpenCodeAutoEngineer | CursorAutoEngineer
if sdk == "opencode":
from .auto_engineer import OpenCodeAutoEngineer
engineer = OpenCodeAutoEngineer(
run_id=run_id,
prompt=prompt,
output_dir=output_dir,
agent_provider=agent_provider,
opencode_provider=config_manager.get("opencode_provider", DEFAULT_OPENCODE_PROVIDER),
opencode_model=model or config_manager.get("opencode_model", DEFAULT_OPENCODE_MODEL),
enable_sync=config_manager.get("real_time_sync", False),
sdk=sdk,
output_language=output_language,
interactive=interactive,
headless=headless,
)
elif sdk == "copilot":
from .auto_engineer import CopilotAutoEngineer
engineer = CopilotAutoEngineer(
run_id=run_id,
prompt=prompt,
copilot_model=model or config_manager.get("copilot_model", "gpt-5"),
output_dir=output_dir,
agent_provider=agent_provider,
enable_sync=config_manager.get("real_time_sync", False),
sdk=sdk,
output_language=output_language,
interactive=interactive,
headless=headless,
)
elif sdk == "cursor":
from .cursor_engineer import CursorAutoEngineer
_cs = config_manager.get("cursor_setting_sources")
_cursor_src = _cs if isinstance(_cs, list) and all(isinstance(x, str) for x in _cs) else None
engineer = CursorAutoEngineer(
run_id=run_id,
prompt=prompt,
output_dir=output_dir,
agent_provider=agent_provider,
enable_sync=config_manager.get("real_time_sync", False),
sdk=sdk,
output_language=output_language,
interactive=interactive,
headless=headless,
cursor_model=model or config_manager.get("cursor_model", "composer-2.5"),
cursor_web_search=bool(config_manager.get("cursor_web_search", True)),
cursor_setting_sources=_cursor_src,
)
else:
from .auto_engineer import ClaudeAutoEngineer
engineer = ClaudeAutoEngineer(
run_id=run_id,
prompt=prompt,
model=model or config_manager.get("claude_code_model", "claude-sonnet-4-6"),
output_dir=output_dir,
agent_provider=agent_provider,
enable_sync=config_manager.get("real_time_sync", False),
sdk=sdk,
output_language=output_language,
interactive=interactive,
headless=headless,
)
if json_event_sink is not None:
from .json_stream import attach_json_stream_to_engineer
attach_json_stream_to_engineer(
engineer,
json_event_sink,
mode=mode_label,
url=url,
command="agent",
)
# Start sync before analysis
engineer.start_sync()
interrupted = False
cancelled = False
try:
result = asyncio.run(engineer.analyze_and_generate())
interrupted = isinstance(result, dict) and result.get("error") == "interrupted"
except KeyboardInterrupt as exc:
result = getattr(exc, "partial_result", None)
# Python 3.11+ Runner translates SIGINT cancellation to
# KeyboardInterrupt, with the tagged CancelledError as context.
if result is None and isinstance(exc.__context__, asyncio.CancelledError):
result = getattr(exc.__context__, "partial_result", None)
interrupted = True
console.print("\n [dim]run aborted[/dim]")
except asyncio.CancelledError as exc:
result = getattr(exc, "partial_result", None)
cancelled = True
finally:
# Always stop sync when done
engineer.stop_sync()
# Update session with results
if result:
session_manager.update_run(
run_id=run_id,
usage=result.get("usage", {}),
paths={"script_path": result.get("script_path")},
)
return {
"run_id": run_id,
"mode": mode_label,
"script_path": (result or {}).get("script_path"),
"usage": (result or {}).get("usage", {}),
**(
{"error": "interrupted"}
if interrupted
else {"error": "Agent analysis cancelled."}
if cancelled
else {"error": "Agent analysis produced no result."}
if result is None
else {}
),
}
except Exception as e:
message = str(e) or type(e).__name__
click.echo(f"error: {message}", err=True)
click.echo(ERROR_CTA, err=True)
if os.environ.get("RAE_DEBUG") == "1":
traceback.print_exc(file=sys.stderr)
else:
logging.getLogger(__name__).debug("Auto mode failed", exc_info=True)
return {
"run_id": run_id,
"mode": mode_label,
"script_path": None,
"usage": {},
"error": message,
"error_reported": True,
}
@main.command(
epilog="""\b
Examples:
reverse-api-engineer engineer abc123def456
reverse-api-engineer engineer abc123def456 -p "add pagination support"
reverse-api-engineer engineer abc123def456 --fresh -p "extract auth flow only"
reverse-api-engineer engineer abc123def456 --json | jq
\b
JSON output schema (--json):
{
"schema_version": 1,
"status": "ok" | "error",
"run_id": "<id>",
"prompt": "..." | null,
"fresh": false,
"script_path": "/abs/path/api_client.py" | null,
"usage": {
"input_tokens": ...,
"output_tokens": ...,
"cache_read_tokens": ...,
"cache_write_tokens": ...,
"total_cost_usd": ...,
"raw": { ... }
},
"error": "<message>" | null,
"error_kind": "misuse" | "config_invalid" | "permission_denied" | "network" | "engine_failure" | "interrupted" | "unknown" | null
}
\b
Exit codes:
0 success
1 runtime error (engineering failed, run not found)
2 misuse
"""
)
@click.argument("run_id", required=False)
@click.option(
"--prompt",
"-p",
default=None,
help=(
"With --fresh: replace the captured run's original goal. "
"Without --fresh: layered as additional instructions on top of the original prompt."
),
)
@click.option(
"--fresh",
is_flag=True,
help="Ignore previously generated scripts and re-engineer from scratch.",
)
@click.option(
"--model",
"-m",
type=click.Choice(["claude-sonnet-4-6", "claude-opus-4-6", "claude-haiku-4-5"]),
default=None,
)
@click.option("--output-dir", "-o", default=None, help="Custom output directory.")
@click.option(
"--no-interactive",
is_flag=True,
help="Reserved for symmetry with `agent`/`run`; engineer mode is non-interactive by design.",
)
@click.option(
"--json",
"as_json",
is_flag=True,
help="Emit a single JSON result on stdout (logs go to stderr). Implies --no-interactive.",
)
@click.option(
"--json-stream",
"json_stream",
is_flag=True,
help="Emit NDJSON progress events on stdout during the run, then a final {\"event\":\"result\",...} line. Implies --no-interactive.",
)
def engineer(
run_id: str | None,
prompt: str | None,
fresh: bool,
model: str | None,
output_dir: str | None,
no_interactive: bool,
as_json: bool,
json_stream: bool,
) -> None:
"""Run reverse engineering on a previous run."""
# `run_id` is declared optional at the click level so that wrappers using
# --json get a JSON misuse payload instead of Click's plain-text "missing
# argument" error. We re-validate inline to preserve the same exit-2 UX
# for non-JSON invocations.
if not run_id:
machine_output = as_json or json_stream
if machine_output:
misuse = _build_engineer_payload(
None,
run_id="",
prompt=prompt,
fresh=fresh,
error="RUN_ID is required",
error_kind_hint="misuse",
)
if json_stream:
with _quiet_consoles_for_json() as real_stdout:
_write_json_stdout(real_stdout, misuse, json_stream=True)
else:
click.echo(json.dumps(misuse))
else:
click.echo("Usage: reverse-api-engineer engineer [OPTIONS] RUN_ID", err=True)
click.echo("\nError: Missing argument 'RUN_ID'.", err=True)
sys.exit(2)
# --fresh treats --prompt as a full replacement of the original goal;
# without --fresh, --prompt is additive so the captured run's context is preserved.
main_prompt = prompt if fresh else None
additional = prompt if (prompt and not fresh) else None
# Either flag must suppress the post-generation follow-up prompt that
# would otherwise block on stdin (`input(" > ")`) inside ClaudeEngineer.
no_interactive = no_interactive or as_json or json_stream
interactive = not no_interactive
machine_output = as_json or json_stream
if not machine_output:
run_engineer(
run_id,
prompt=main_prompt,
additional_instructions=additional,
model=model,
output_dir=output_dir,
is_fresh=fresh,
interactive=interactive,
)
return
from .json_stream import make_json_stream_sink
with _quiet_consoles_for_json() as real_stdout:
sink = (
make_json_stream_sink(lambda line: _write_json_line(real_stdout, line))
if json_stream
else None
)
try:
result = run_engineer(
run_id,
prompt=main_prompt,
additional_instructions=additional,
model=model,
output_dir=output_dir,
is_fresh=fresh,
interactive=interactive,
json_event_sink=sink,
)
payload = _build_engineer_payload(result, run_id=run_id, prompt=prompt, fresh=fresh)
except KeyboardInterrupt as e:
payload = _build_engineer_payload(
None, run_id=run_id, prompt=prompt, fresh=fresh, error=e
)
except Exception as e:
# Pass the exception object so _classify_error can use isinstance.
payload = _build_engineer_payload(
None, run_id=run_id, prompt=prompt, fresh=fresh, error=e
)
_write_json_stdout(real_stdout, payload, json_stream=json_stream)
sys.exit(0 if payload["status"] == "ok" else 1)
def run_engineer(
run_id: str,
har_path: Path | None = None,
prompt: str | None = None,
model: str | None = None,
output_dir: str | None = None,
additional_instructions: str | None = None,
is_fresh: bool = False,
output_mode: str = "client",
interactive: bool = True,
json_event_sink: Callable[[dict[str, Any]], None] | None = None,
) -> dict[str, Any] | None:
"""Shared logic for reverse engineering."""
if not har_path or not prompt:
# Load from history if possible
run_data = session_manager.get_run(run_id)
if not run_data:
# Fallback to file search if not in history
har_dir = get_har_dir(run_id, output_dir)
har_path = har_dir / "recording.har"
if not har_path.exists():
console.print(f" [red]not found:[/red] {run_id}")
return None
if not prompt:
prompt = "Reverse engineer captured APIs" if output_mode == "client" else "Generate OpenAPI documentation"
else:
if not prompt:
prompt = run_data["prompt"]
# Detect where it was saved
paths = run_data.get("paths", {})
har_dir = Path(paths.get("har_dir", get_har_dir(run_id, None)))
har_path = har_dir / "recording.har"
sdk = config_manager.get("sdk", "claude")
enable_sync = config_manager.get("real_time_sync", True)
output_language = config_manager.get("output_language", "python")
if sdk == "opencode":
result = run_reverse_engineering(
run_id=run_id,
har_path=har_path,
prompt=prompt,
model=model,
output_dir=output_dir,
sdk=sdk,
opencode_provider=config_manager.get("opencode_provider", DEFAULT_OPENCODE_PROVIDER),
opencode_model=config_manager.get("opencode_model", DEFAULT_OPENCODE_MODEL),
enable_sync=enable_sync,
additional_instructions=additional_instructions,
is_fresh=is_fresh,
output_language=output_language,
output_mode=output_mode,
interactive=interactive,
json_event_sink=json_event_sink,
)
elif sdk == "copilot":
result = run_reverse_engineering(
run_id=run_id,
har_path=har_path,
prompt=prompt,
model=model,
output_dir=output_dir,
sdk=sdk,
copilot_model=config_manager.get("copilot_model", "gpt-5"),
enable_sync=enable_sync,
additional_instructions=additional_instructions,
is_fresh=is_fresh,
output_language=output_language,
output_mode=output_mode,
interactive=interactive,
json_event_sink=json_event_sink,
)
elif sdk == "cursor":
_cs = config_manager.get("cursor_setting_sources")
_cursor_src = _cs if isinstance(_cs, list) and all(isinstance(x, str) for x in _cs) else None
_cm = model or config_manager.get("cursor_model", "composer-2.5")
result = run_reverse_engineering(
run_id=run_id,
har_path=har_path,
prompt=prompt,
model=_cm,
output_dir=output_dir,
sdk=sdk,
cursor_model=_cm,
cursor_web_search=bool(config_manager.get("cursor_web_search", True)),
cursor_setting_sources=_cursor_src,
enable_sync=enable_sync,
additional_instructions=additional_instructions,
is_fresh=is_fresh,
output_language=output_language,
output_mode=output_mode,
interactive=interactive,
json_event_sink=json_event_sink,
)
else:
result = run_reverse_engineering(
run_id=run_id,
har_path=har_path,
prompt=prompt,
model=model or config_manager.get("claude_code_model", "claude-sonnet-4-6"),
output_dir=output_dir,
sdk=sdk,
enable_sync=enable_sync,
additional_instructions=additional_instructions,
is_fresh=is_fresh,
output_language=output_language,
output_mode=output_mode,
interactive=interactive,
json_event_sink=json_event_sink,
)
if result:
# Skip manual copy if real-time sync is enabled (files already synced)
if not enable_sync:
# Automatically copy to current directory with a readable name
output_dir_path = Path(result["script_path"]).parent
base_name = generate_folder_name(prompt, sdk=sdk)
# Choose base path based on output mode
if output_mode == "docs":
base_path = Path.cwd() / "docs"
else:
base_path = Path.cwd() / "scripts"
from .sync import get_available_directory
# Get available directory (won't overwrite existing non-empty dirs)
local_dir = get_available_directory(base_path, base_name)
local_dir.mkdir(parents=True, exist_ok=True)
import shutil
for item in output_dir_path.iterdir():
if item.is_file():
shutil.copy2(item, local_dir / item.name)
# Different messages for docs vs client mode
if output_mode == "docs":
console.print(" [dim]>[/dim] [white]documentation complete[/white]")
console.print(f" [dim]>[/dim] [white]{result['script_path']}[/white]")
console.print(f" [dim]>[/dim] [white]copied to ./docs/{local_dir.name}[/white]\n")
else:
console.print(" [dim]>[/dim] [white]decoding complete[/white]")
console.print(f" [dim]>[/dim] [white]{result['script_path']}[/white]")
console.print(f" [dim]>[/dim] [white]copied to ./scripts/{local_dir.name}[/white]\n")
else:
# With sync enabled, just show completion
if output_mode == "docs":
console.print(" [dim]>[/dim] [white]documentation complete[/white]")
else:
console.print(" [dim]>[/dim] [white]decoding complete[/white]")
console.print(f" [dim]>[/dim] [white]{result['script_path']}[/white]\n")
session_manager.update_run(
run_id=run_id,
sdk=sdk,
output_mode=output_mode,
usage=result.get("usage", {}),
paths={"script_path": result.get("script_path")},
)
return result
def _get_run_details(run: dict) -> dict:
"""Enrich a history entry with filesystem info."""
run_id = run.get("run_id", "")
output_dir = config_manager.get("output_dir")
base_dir = get_base_output_dir(output_dir)
script_dir = base_dir / "scripts" / run_id
files = []
if script_dir.exists():
files = sorted(f.name for f in script_dir.iterdir() if f.is_file())
# Scan ./scripts/ subdirectories to find local copy
local_path = None
local_scripts = Path.cwd() / "scripts"
if local_scripts.exists() and files:
files_set = set(files)
for subdir in local_scripts.iterdir():
if subdir.is_dir():
local_files = {f.name for f in subdir.iterdir() if f.is_file()}
if local_files and local_files == files_set:
local_path = f"./scripts/{subdir.name}/"
break
usage = run.get("usage", {})
cost = usage.get("total_cost", usage.get("cost"))
return {
"run_id": run_id,
"prompt": run.get("prompt", ""),
"timestamp": run.get("timestamp", ""),
"model": run.get("model", ""),
"mode": run.get("mode", ""),
"sdk": run.get("sdk", ""),
"cost": cost,
"script_dir": str(script_dir),
"files": files,
"file_count": len(files),
"local_path": local_path,
}
@main.command(
"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.")
@click.option("--mode", "-m", type=str, default=None, help="Filter by mode (auto/manual/agent/engineer/collector).")
@click.option("--model", type=str, default=None, help="Filter by model name.")
@click.option("--search", "-s", type=str, default=None, help="Case-insensitive substring match on prompt.")
def list_runs(as_json: bool, full: bool, limit: int | None, mode: str | None, model: str | None, search: str | None) -> None:
"""List generated scripts and runs with optional filters."""
from rich.table import Table
runs = list(session_manager.history)
if mode:
runs = [r for r in runs if r.get("mode", "") == mode]
if model:
runs = [r for r in runs if model.lower() in (r.get("model") or "").lower()]
if search:
runs = [r for r in runs if search.lower() in (r.get("prompt") or "").lower()]
if not runs:
if as_json:
click.echo(json.dumps([]))
elif not session_manager.history:
console.print("No runs found.", style="dim")
else:
console.print("No matching runs found.")
return
if limit is not None:
runs = runs[:limit]
results = [_get_run_details(r) for r in runs]
if as_json:
click.echo(json.dumps(results, indent=2))
return
if full:
table = Table(show_lines=False)
table.add_column("run_id", style="cyan")
table.add_column("prompt", max_width=40)
table.add_column("timestamp")
table.add_column("model")
table.add_column("mode")
table.add_column("sdk")
table.add_column("cost", justify="right")
table.add_column("script_dir")
table.add_column("files", justify="right")
for r in results:
prompt = r["prompt"][:40] + ("..." if len(r["prompt"]) > 40 else "")
cost_str = f"${r['cost']:.2f}" if r["cost"] is not None else ""
table.add_row(
r["run_id"],
prompt,
r["timestamp"],
r["model"] or "",
r["mode"] or "",
r["sdk"] or "",
cost_str,
r["script_dir"],
str(r["file_count"]),
)
else:
table = Table(show_lines=False)
table.add_column("run_id", style="cyan")
table.add_column("prompt", max_width=40)
table.add_column("timestamp")
table.add_column("script_dir")
for r in results:
prompt = r["prompt"][:40] + ("..." if len(r["prompt"]) > 40 else "")
table.add_row(
r["run_id"],
prompt,
r["timestamp"],
r["script_dir"],
)
console.print(table)
@main.command(
"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: str | None, as_json: bool) -> None:
"""Show detailed info for a specific run."""
from rich.table import Table
from rich.text import Text
def _show_error_payload(message: str, rid: str | None = None) -> dict:
return {
"schema_version": AGENT_JSON_SCHEMA_VERSION,
"status": "error",
"run_id": rid,
"error": message,
"error_kind": _classify_error(message, default="engine_failure"),
}
if run_id:
run = session_manager.get_run(run_id)
elif session_manager.history:
run = session_manager.history[0]
else:
if as_json:
click.echo(json.dumps(_show_error_payload("no runs found")))
sys.exit(1)
console.print("No runs found.", style="dim")
return
if run is None:
if as_json:
click.echo(json.dumps(_show_error_payload("run not found", run_id)))
sys.exit(1)
console.print(f"Run not found: {run_id}")
return
details = _get_run_details(run)
rid = details["run_id"]
output_dir = config_manager.get("output_dir")
base_dir = get_base_output_dir(output_dir)
# Extra fields
details["url"] = run.get("url")
details["output_mode"] = run.get("output_mode", "client")
usage = run.get("usage", {})
details["input_tokens"] = usage.get("input_tokens", 0)
details["output_tokens"] = usage.get("output_tokens", 0)
details["cache_creation_input_tokens"] = usage.get("cache_creation_input_tokens", 0)
details["cache_read_input_tokens"] = usage.get("cache_read_input_tokens", 0)
# Artifact paths with existence
har_dir = base_dir / "har" / rid
messages_path = get_messages_path(rid, output_dir)
script_dir = Path(details["script_dir"])
details["har_dir"] = str(har_dir)
details["har_dir_exists"] = har_dir.exists()
details["messages_path"] = str(messages_path)
details["messages_path_exists"] = messages_path.exists()
details["script_dir_exists"] = script_dir.exists()
# HAR entry count
har_entries = None
if har_dir.exists():
recording = har_dir / "recording.har"
if recording.exists():
try:
har_data = json.loads(recording.read_text(encoding="utf-8-sig"))
har_entries = len(har_data.get("log", {}).get("entries", []))
except Exception:
pass
details["har_entries"] = har_entries
if as_json:
details["schema_version"] = AGENT_JSON_SCHEMA_VERSION
details["status"] = "ok"
details["error"] = None
details["error_kind"] = None
click.echo(json.dumps(details, indent=2))
return
# Rich table output
table = Table(show_header=False, show_lines=True)
table.add_column(style="bold cyan")
table.add_column()
def _path_val(path_str: str, exists: bool) -> Text:
t = Text(path_str + " ")
t.append("✓" if exists else "✗", style="green" if exists else "red")
return t
rows: list[tuple[str, Text | str | None]] = [
("prompt", details["prompt"]),
("timestamp", details["timestamp"]),
("model", details["model"]),
("mode", details["mode"]),
("sdk", details["sdk"]),
("output_mode", details["output_mode"]),
("url", details.get("url")),
("cost", f"${details['cost']:.2f}" if details["cost"] is not None else None),
("input_tokens", str(details["input_tokens"])),
("output_tokens", str(details["output_tokens"])),
("cache_creation", str(details["cache_creation_input_tokens"])),
("cache_read", str(details["cache_read_input_tokens"])),
("har_dir", _path_val(details["har_dir"], details["har_dir_exists"])),
("har_entries", str(har_entries) if har_entries is not None else None),
("script_dir", _path_val(details["script_dir"], details["script_dir_exists"])),
]
files = details["files"]
if files:
rows.append(("files", ", ".join(files) + f" ({len(files)})"))
rows.append(("local_path", details.get("local_path")))
rows.append(("messages", _path_val(details["messages_path"], details["messages_path_exists"])))
for key, val in rows:
if val is None or val == "":
continue
table.add_row(key, val if isinstance(val, Text) else str(val))
console.print(f"\nRun {rid}")
console.print(table)
def _extract_missing_module(stderr: str) -> str | None:
"""Extract a missing top-level module name from a ModuleNotFoundError message.
Returns None if no module name is found or the name is not a plain Python
identifier — a genuine ModuleNotFoundError always names one, and rejecting
anything else prevents a crafted error message from smuggling pip options
or arbitrary install targets.
"""
import re as _re
match = _re.search(r"No module named ['\"]([^'\"]+)['\"]", stderr)
if not match:
return None
missing = match.group(1).split(".")[0]
# fullmatch, since $ in re.match would accept a trailing newline
if not _re.fullmatch(r"[a-zA-Z0-9_]+", missing) or len(missing) > 64:
return None
return missing
def _run_non_python_script(script: Path, script_args: tuple[str, ...]) -> None:
"""Run a non-Python generated client with its language's toolchain and exit."""
import shutil
import subprocess
from .runtime_commands import resolve_windows_command
from .utils import build_script_commands
try:
steps, tool = build_script_commands(script, script_args)
except ValueError as e:
raise click.ClickException(str(e)) from e
executable = shutil.which(tool)
if executable is None:
raise click.ClickException(f"cannot run {script.name}: '{tool}' is missing from PATH — install it and retry")
if sys.platform == "win32":
try:
steps[0] = resolve_windows_command([executable, *steps[0][1:]])
except ValueError as e:
raise click.ClickException(str(e)) from e
returncode = 0
for cmd in steps:
returncode = subprocess.run(cmd, cwd=str(script.parent)).returncode
if returncode != 0:
break
raise SystemExit(returncode)
def _run_script_machine_payload(
*,
identifier: str,
script_args: tuple[str, ...],
file_name: str | None,
list_scripts: bool,
auto_install: bool,
emit_event: CliEventEmitter,
) -> dict:
"""Run or list generated scripts without prompts and with JSON-safe stdout."""
import subprocess
from .runtime_commands import decode_process_output
run_id: str | None = None
script: Path | None = None
scripts: list[Path] = []
try:
run = resolve_run(identifier, session_manager, interactive=False)
run_id = run["run_id"]
output_dir = config_manager.get("output_dir")
scripts = discover_scripts(run_id, output_dir, run_metadata=run)
emit_event("run_resolved", run_id=run_id, script_count=len(scripts))
if not scripts:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
scripts=scripts,
error=f"No runnable scripts found for run {run_id}",
error_kind_hint="engine_failure",
)
if list_scripts:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
scripts=scripts,
returncode=0,
)
if file_name:
matching = [s for s in scripts if s.name == file_name]
if not matching:
available = ", ".join(s.name for s in scripts)
return _build_run_payload(
identifier=identifier,
run_id=run_id,
scripts=scripts,
error=f"'{file_name}' not found. Available: {available}",
error_kind_hint="misuse",
)
script = matching[0]
elif len(scripts) == 1:
script = scripts[0]
else:
available = ", ".join(s.name for s in scripts)
return _build_run_payload(
identifier=identifier,
run_id=run_id,
scripts=scripts,
error=(f"multiple scripts found for run {run_id}; pass --file <name> to choose. Available: {available}"),
error_kind_hint="misuse",
)
emit_event("script_selected", run_id=run_id, script_path=str(script))
if script.suffix != ".py":
import shutil
from .utils import build_script_commands
try:
steps, tool = build_script_commands(script, script_args)
except ValueError as e:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
scripts=scripts,
error=str(e),
error_kind_hint="misuse",
)
executable = shutil.which(tool)
if executable is None:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
scripts=scripts,
error=f"cannot run {script.name}: '{tool}' is missing from PATH — install it and retry",
error_kind_hint="config_invalid",
)
if sys.platform == "win32":
from .runtime_commands import resolve_windows_command
try:
steps[0] = resolve_windows_command([executable, *steps[0][1:]])
except ValueError as e:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
scripts=scripts,
error=str(e),
error_kind_hint="config_invalid",
)
binary_result = None
for cmd in steps:
emit_event("process_started", run_id=run_id, script_path=str(script))
binary_result = subprocess.run(cmd, cwd=str(script.parent), capture_output=True)
if binary_result.returncode != 0:
break
assert binary_result is not None, "build_script_commands returned no execution steps"
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
returncode=binary_result.returncode,
stdout=decode_process_output(binary_result.stdout),
stderr=decode_process_output(binary_result.stderr),
scripts=scripts,
)
from .utils import get_base_output_dir as _get_base
venv_dir = _get_base(output_dir) / ".venv"
venv_bin = "Scripts" if sys.platform == "win32" else "bin"
venv_python = venv_dir / venv_bin / ("python.exe" if sys.platform == "win32" else "python")
venv_pip = venv_dir / venv_bin / ("pip.exe" if sys.platform == "win32" else "pip")
if not venv_dir.exists():
emit_event("venv_setup_started", run_id=run_id, path=str(venv_dir))
subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True, capture_output=True, text=True, errors="replace")
subprocess.run([str(venv_pip), "install", "-q", "requests"], check=True, capture_output=True, text=True, errors="replace")
emit_event("venv_setup_completed", run_id=run_id, path=str(venv_dir))
requirements = script.parent / "requirements.txt"
if requirements.exists():
emit_event("requirements_install_started", run_id=run_id, path=str(requirements))
subprocess.run([str(venv_pip), "install", "-q", "-r", str(requirements)], check=True, capture_output=True, text=True, errors="replace")
emit_event("requirements_install_completed", run_id=run_id, path=str(requirements))
cmd = [str(venv_python), str(script), *script_args]
emit_event("process_started", run_id=run_id, script_path=str(script))
def run_client() -> subprocess.CompletedProcess[str]:
captured = subprocess.run(
cmd, capture_output=True,
env={**os.environ, "PYTHONIOENCODING": "utf-8"},
)
return subprocess.CompletedProcess(
captured.args, captured.returncode,
decode_process_output(captured.stdout, utf8_stream=True),
decode_process_output(captured.stderr, utf8_stream=True),
)
result = run_client()
stderr = result.stderr or ""
if result.returncode != 0 and "ModuleNotFoundError: No module named" in stderr:
missing = _extract_missing_module(stderr)
if missing:
emit_event("dependency_missing", run_id=run_id, package=missing)
if auto_install:
emit_event("dependency_install_started", run_id=run_id, package=missing)
subprocess.run([str(venv_pip), "install", "-q", missing], check=True, capture_output=True, text=True, errors="replace")
emit_event("dependency_install_completed", run_id=run_id, package=missing)
emit_event("process_retried", run_id=run_id, script_path=str(script))
result = run_client()
else:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
returncode=result.returncode,
stdout=result.stdout or "",
stderr=stderr,
scripts=scripts,
error=f"missing dependency: {missing}",
error_kind_hint="engine_failure",
)
elif auto_install:
# Keep the refusal observable instead of falling through to a
# generic script-exit error
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
returncode=result.returncode,
stdout=result.stdout or "",
stderr=stderr,
scripts=scripts,
error="refusing to auto-install: no safe package name could be extracted from the ModuleNotFoundError output",
error_kind_hint="engine_failure",
)
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script),
script_args=script_args,
returncode=result.returncode,
stdout=result.stdout or "",
stderr=result.stderr or "",
scripts=scripts,
)
except click.ClickException as e:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script) if script else None,
script_args=script_args,
scripts=scripts,
error=e.message,
error_kind_hint="misuse",
)
except Exception as e:
return _build_run_payload(
identifier=identifier,
run_id=run_id,
script_path=str(script) if script else None,
script_args=script_args,
scripts=scripts,
error=e,
error_kind_hint="engine_failure",
)
@main.command(
"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
reverse-api-engineer run a450e520ca30 --file api_client.py --json | jq
reverse-api-engineer run a450e520ca30 --file api_client.py --json-stream
\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).")
@click.option("--ls", "list_scripts", is_flag=True, help="List available scripts without executing.")
@click.option(
"--no-interactive",
is_flag=True,
help="Fail fast on script-picker / missing-dependency prompts (intended for scripted/agent usage).",
)
@click.option(
"--auto-install",
is_flag=True,
help="Auto-install missing dependencies on retry without prompting (implies --no-interactive for the picker).",
)
@click.option(
"--json",
"as_json",
is_flag=True,
help="Emit one JSON result on stdout with captured script stdout/stderr. Implies --no-interactive.",
)
@click.option(
"--json-stream",
"json_stream",
is_flag=True,
help='Emit NDJSON progress events on stdout, then a final {"event":"result",...} line. Implies --no-interactive.',
)
@click.pass_context
def run_script(
ctx: click.Context,
identifier: str,
script_args: tuple[str, ...],
file_name: str | None,
list_scripts: bool,
no_interactive: bool,
auto_install: bool,
as_json: bool,
json_stream: bool,
) -> None:
"""Run a generated script from a previous run.
IDENTIFIER is a run ID or search term to match against prompts.
Any extra arguments after the identifier are passed to the script.
Examples:
reverse-api-engineer run a450e520ca30
reverse-api-engineer run ashby --ls
reverse-api-engineer run ashby --file api_client.py
reverse-api-engineer run ashby -- --org acme --limit 10
"""
import subprocess
import sys
from rich.table import Table
machine_output = as_json or json_stream
no_interactive = no_interactive or machine_output
if machine_output:
with _quiet_consoles_for_json() as real_stdout:
def emit_event(event: str, **fields: Any) -> None:
if json_stream:
_write_json_event(real_stdout, {"event": event, **fields})
payload = _run_script_machine_payload(
identifier=identifier,
script_args=script_args,
file_name=file_name,
list_scripts=list_scripts,
auto_install=auto_install,
emit_event=emit_event,
)
_write_json_stdout(real_stdout, payload, json_stream=json_stream)
if payload["returncode"] not in (None, 0):
raise SystemExit(payload["returncode"])
raise SystemExit(0 if payload["status"] == "ok" else 1)
# Resolve which run
run = resolve_run(identifier, session_manager, interactive=not no_interactive)
run_id = run["run_id"]
output_dir = config_manager.get("output_dir")
# Discover scripts (prefer stored path from run metadata, fall back to output_dir)
scripts = discover_scripts(run_id, output_dir, run_metadata=run)
prompt_preview = (run.get("prompt") or "")[:80]
ts = (run.get("timestamp") or "")[:19]
console.print(f"{run_id} {ts} {prompt_preview}", style="dim")
if scripts:
console.print(f"{scripts[0].parent}", style="dim")
if not scripts:
console.print(f"[red]No runnable scripts found for run {run_id}[/red]")
raise SystemExit(1)
# --ls: just list and exit
if list_scripts:
table = Table(title=f"Scripts in run {run_id}")
table.add_column("File", style="cyan")
table.add_column("Size", justify="right")
table.add_column("Modified")
for s in scripts:
stat = s.stat()
size = f"{stat.st_size:,} B"
from datetime import datetime
modified = datetime.fromtimestamp(stat.st_mtime).strftime("%Y-%m-%d %H:%M")
table.add_row(s.name, size, modified)
console.print(table)
return
# Select script
if file_name:
# Exact filename match
matching = [s for s in scripts if s.name == file_name]
if not matching:
available = ", ".join(s.name for s in scripts)
raise click.ClickException(f"'{file_name}' not found. Available: {available}")
script = matching[0]
elif len(scripts) == 1:
script = scripts[0]
elif no_interactive or auto_install:
available = ", ".join(s.name for s in scripts)
raise click.ClickException(
f"multiple scripts found for run {run_id}; pass --file <name> to choose. Available: {available}"
)
else:
# Interactive picker
choices = [questionary.Choice(title=s.name, value=s) for s in scripts]
script = questionary.select(
"Select script to run:",
choices=choices,
).ask()
if script is None:
raise click.Abort()
# Non-Python clients: dispatch on extension, no venv involved
if script.suffix != ".py":
_run_non_python_script(script, script_args)
# Shared venv at ~/.reverse-api/runs/.venv (with requests pre-installed)
from .utils import get_base_output_dir as _get_base
venv_dir = _get_base(output_dir) / ".venv"
venv_bin = "Scripts" if sys.platform == "win32" else "bin"
venv_python = venv_dir / venv_bin / ("python.exe" if sys.platform == "win32" else "python")
venv_pip = venv_dir / venv_bin / ("pip.exe" if sys.platform == "win32" else "pip")
if not venv_dir.exists():
console.print("Setting up shared venv...", style="dim")
subprocess.run([sys.executable, "-m", "venv", str(venv_dir)], check=True)
subprocess.run([str(venv_pip), "install", "-q", "requests"], check=True)
console.print("Shared venv ready.", style="dim")
# Install per-run requirements.txt if present
scripts_dir = script.parent
requirements = scripts_dir / "requirements.txt"
if requirements.exists():
subprocess.run([str(venv_pip), "install", "-q", "-r", str(requirements)], check=True)
python_path = str(venv_python)
# Execute with real-time stdout, capture stderr for import error detection
cmd = [python_path, str(script), *script_args]
launch_env = {**os.environ, "PYTHONIOENCODING": "utf-8"}
result = subprocess.run(
cmd, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace",
env=launch_env,
)
# Print stderr so the user sees it, then check for missing imports
if result.stderr:
sys.stderr.write(result.stderr)
if result.returncode != 0:
if "ModuleNotFoundError: No module named" in (result.stderr or ""):
missing = _extract_missing_module(result.stderr)
if missing:
console.print(f"[yellow]Missing dependency: {missing}[/yellow]")
if auto_install:
install = True
elif no_interactive:
install = False
else:
install = questionary.confirm(
f"Install '{missing}' and retry?", default=True
).ask()
if install:
subprocess.run([str(venv_pip), "install", "-q", missing], check=True)
console.print(f"Installed [green]{missing}[/green]. Retrying...")
retry_result = subprocess.run(cmd, env=launch_env)
raise SystemExit(retry_result.returncode)
raise SystemExit(result.returncode)
if __name__ == "__main__":
main()