Skip to content

The agent that turns websites into APIs!

feat: codegen for manual mode

kalil03217141e618034a
diff --git a/.gitignore b/.gitignore
index fc6a11e..22da872 100644
--- a/.gitignore
+++ b/.gitignore
@@ -91,3 +91,4 @@ prompt*.md
test*
FEATURES.md
+docs/
\ No newline at end of file
diff --git a/src/reverse_api/action_recorder.py b/src/reverse_api/action_recorder.py
new file mode 100644
index 0000000..490e2e1
--- /dev/null
+++ b/src/reverse_api/action_recorder.py
@@ -0,0 +1,51 @@
+"""Action recording infrastructure for manual browser sessions."""
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import List, Optional
+
+
+@dataclass
+class RecordedAction:
+ """A single recorded browser action."""
+
+ type: str # "click", "fill", "navigate", "press"
+ selector: Optional[str] = None
+ value: Optional[str] = None
+ url: Optional[str] = None
+ timestamp: float = 0.0
+ metadata: Optional[dict] = None
+
+
+class ActionRecorder:
+ """Records browser actions during manual sessions."""
+
+ def __init__(self):
+ self.actions: List[RecordedAction] = []
+
+ def add_action(self, action: RecordedAction) -> None:
+ """Add an action to the recording."""
+ self.actions.append(action)
+
+ def get_actions(self) -> List[RecordedAction]:
+ """Get all recorded actions."""
+ return self.actions
+
+ def save(self, path: Path) -> None:
+ """Save actions to a JSON file."""
+ data = [asdict(action) for action in self.actions]
+ with open(path, "w") as f:
+ json.dump(data, f, indent=2)
+
+ @classmethod
+ def load(cls, path: Path) -> "ActionRecorder":
+ """Load actions from a JSON file."""
+ recorder = cls()
+ if path.exists():
+ with open(path) as f:
+ data = json.load(f)
+ for item in data:
+ recorder.add_action(RecordedAction(**item))
+ return recorder
+
diff --git a/src/reverse_api/browser.py b/src/reverse_api/browser.py
index b729c75..b5adce8 100644
--- a/src/reverse_api/browser.py
+++ b/src/reverse_api/browser.py
@@ -17,6 +17,7 @@ from rich.console import Console
from rich.status import Status
from . import __version__
+from .action_recorder import ActionRecorder, RecordedAction
from .tui import ERROR_CTA
from .utils import get_har_dir, get_timestamp
@@ -202,14 +203,18 @@ class ManualBrowser:
prompt: str,
output_dir: str | None = None,
use_real_chrome: bool = True, # New option to use real Chrome
+ enable_action_recording: bool = False,
):
self.run_id = run_id
self.prompt = prompt
self.output_dir = output_dir
self.use_real_chrome = use_real_chrome
+ self.enable_action_recording = enable_action_recording
+
self.har_dir = get_har_dir(run_id, output_dir)
self.har_path = self.har_dir / "recording.har"
self.metadata_path = self.har_dir / "metadata.json"
+
self._playwright = None
self._browser: Browser | None = None
self._context: BrowserContext | None = None
@@ -217,6 +222,192 @@ class ManualBrowser:
self._user_agent = random.choice(USER_AGENTS)
self._using_persistent = False # Track if using persistent context
+ self.action_recorder = ActionRecorder() if enable_action_recording else None
+
+ def _inject_action_recorder(self, page: Page) -> None:
+ """Inject action recording script into page.
+
+ Uses console.log + page.on('console') for reliable capture.
+ Works best with stealth Chromium mode (not real Chrome).
+ """
+ if not self.enable_action_recording:
+ return
+
+ # Simple JS that logs actions to console with a special prefix
+ recorder_js = '''
+ window.__recordedActions = [];
+ window.__lastUrl = null;
+
+ document.addEventListener('click', (e) => {
+ const el = e.target;
+
+ // Build a robust selector by traversing up to find parent with ID
+ function buildSelector(element) {
+ // Priority 1: data-testid on element or close parent
+ let current = element;
+ for (let i = 0; i < 3 && current; i++) {
+ if (current.dataset && current.dataset.testid) {
+ const path = i === 0 ? '' : ' ' + getPathFromAncestor(current, element);
+ return '[data-testid="' + current.dataset.testid + '"]' + path;
+ }
+ current = current.parentElement;
+ }
+
+ // Priority 2: element has short ID
+ if (element.id && element.id.length < 20) {
+ return '#' + element.id;
+ }
+
+ // Priority 3: find parent with ID and build path
+ current = element.parentElement;
+ let depth = 1;
+ while (current && depth < 5) {
+ if (current.id && current.id.length < 20) {
+ const path = getPathFromAncestor(current, element);
+ const selector = '#' + current.id + ' > ' + path;
+ // Verify it's unique
+ if (document.querySelectorAll(selector).length === 1) {
+ return selector;
+ }
+ }
+ current = current.parentElement;
+ depth++;
+ }
+
+ // Priority 4: name attribute
+ if (element.name) {
+ return '[name="' + element.name + '"]';
+ }
+
+ // Priority 5: aria-label
+ if (element.getAttribute && element.getAttribute('aria-label')) {
+ return '[aria-label="' + element.getAttribute('aria-label') + '"]';
+ }
+
+ // Priority 6: role + text for buttons
+ if ((element.tagName === 'BUTTON' || element.role === 'button') && element.innerText) {
+ const text = element.innerText.trim().substring(0, 30);
+ if (text && !text.includes('\\n')) {
+ return 'button:has-text("' + text.replace(/"/g, '\\\\"') + '")';
+ }
+ }
+
+ // Priority 7: link text
+ if (element.tagName === 'A' && element.innerText) {
+ const text = element.innerText.trim().substring(0, 30);
+ if (text && !text.includes('\\n')) {
+ return 'a:has-text("' + text.replace(/"/g, '\\\\"') + '")';
+ }
+ }
+
+ // Priority 8: tag + class
+ if (element.className && typeof element.className === 'string') {
+ const cls = element.className.split(' ').filter(c => c && c.length < 30 && !c.includes('hover') && !c.includes('active'))[0];
+ if (cls) {
+ const baseSelector = element.tagName.toLowerCase() + '.' + cls;
+ const matches = document.querySelectorAll(baseSelector);
+ if (matches.length === 1) return baseSelector;
+ const idx = Array.from(matches).indexOf(element);
+ if (idx >= 0) return baseSelector + ' >> nth=' + idx;
+ }
+ }
+
+ // Fallback: tag name
+ return element.tagName.toLowerCase();
+ }
+
+ // Get path from ancestor to descendant
+ function getPathFromAncestor(ancestor, descendant) {
+ if (ancestor === descendant) return descendant.tagName.toLowerCase();
+
+ let path = [];
+ let current = descendant;
+ while (current && current !== ancestor) {
+ path.unshift(current.tagName.toLowerCase());
+ current = current.parentElement;
+ }
+ return path.join(' > ');
+ }
+
+ const selector = buildSelector(el);
+ const action = {type: 'click', selector: selector, timestamp: Date.now()};
+ window.__recordedActions.push(action);
+ console.log('__ACTION__' + JSON.stringify(action));
+ }, true);
+
+ document.addEventListener('input', (e) => {
+ if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') {
+ const el = e.target;
+ let selector = '';
+ if (el.id && el.id.length < 20) selector = '#' + el.id;
+ else if (el.name) selector = '[name="' + el.name + '"]';
+ else if (el.placeholder) selector = '[placeholder="' + el.placeholder + '"]';
+ else selector = el.tagName.toLowerCase();
+
+ const action = {type: 'fill', selector: selector, value: el.value, timestamp: Date.now()};
+ window.__recordedActions.push(action);
+ console.log('__ACTION__' + JSON.stringify(action));
+ }
+ }, true);
+
+ document.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter') {
+ const el = e.target;
+ let selector = '';
+ if (el.id && el.id.length < 20) selector = '#' + el.id;
+ else if (el.name) selector = '[name="' + el.name + '"]';
+ else selector = el.tagName.toLowerCase();
+
+ const action = {type: 'press', selector: selector, value: 'Enter', timestamp: Date.now()};
+ window.__recordedActions.push(action);
+ console.log('__ACTION__' + JSON.stringify(action));
+ }
+ }, true);
+
+ // Only log navigation for top-level main frame, not iframes
+ if (window === window.top) {
+ const url = window.location.href;
+ // Skip about:blank, blob:, data:, service workers, embeds
+ if (url && !url.startsWith('about:') && !url.startsWith('blob:') &&
+ !url.startsWith('data:') && !url.includes('/embed') &&
+ !url.includes('service_worker') && !url.includes('googletagmanager')) {
+ // Only log if URL changed
+ if (url !== window.__lastUrl) {
+ window.__lastUrl = url;
+ console.log('__ACTION__' + JSON.stringify({type: 'navigate', url: url, timestamp: Date.now()}));
+ }
+ }
+ }
+ '''
+
+ # Listen to console for actions
+ import json
+ last_url = [None] # Mutable to track last URL
+
+ def on_console(msg):
+ text = msg.text
+ if text.startswith('__ACTION__'):
+ try:
+ action_json = text[10:] # Remove '__ACTION__' prefix
+ action_data = json.loads(action_json)
+
+ # Filter duplicate navigations
+ if action_data.get('type') == 'navigate':
+ url = action_data.get('url', '')
+ if url == last_url[0]:
+ return # Skip duplicate
+ last_url[0] = url
+
+ if self.action_recorder:
+ self.action_recorder.add_action(RecordedAction(**action_data))
+ except Exception as e:
+ console.print(f" [dim]action parse error: {e}[/dim]")
+
+ page.on("console", on_console)
+ page.add_init_script(recorder_js)
+
+ console.print(" [dim]action recording enabled[/dim]")
+
def _save_metadata(self, end_time: str) -> None:
"""Save run metadata to JSON file."""
metadata = {
@@ -283,6 +474,9 @@ class ManualBrowser:
# For HAR recording & context
page = self._context.new_page()
+ if self.enable_action_recording:
+ self._inject_action_recorder(page)
+
if start_url:
page.goto(start_url, wait_until="domcontentloaded")
else:
@@ -375,6 +569,9 @@ class ManualBrowser:
# Open initial page
page = self._context.new_page()
+ if self.enable_action_recording:
+ self._inject_action_recorder(page)
+
if start_url:
page.goto(start_url, wait_until="domcontentloaded")
else:
@@ -408,7 +605,8 @@ class ManualBrowser:
self._playwright = sync_playwright().start()
- # Try real Chrome first, fall back to stealth Chromium
+ # Try real Chrome first (better for avoiding detection)
+ # Fall back to stealth Chromium if Chrome not available
if self.use_real_chrome:
return self._start_with_real_chrome(start_url)
else:
@@ -468,6 +666,11 @@ class ManualBrowser:
console.print(" [dim]capture saved[/dim]")
console.print(" [dim]metadata synced[/dim]")
+ if self.action_recorder:
+ actions_path = self.har_dir / "actions.json"
+ self.action_recorder.save(actions_path)
+ console.print(" [dim]actions saved[/dim]")
+
return self.har_path
diff --git a/src/reverse_api/cli.py b/src/reverse_api/cli.py
index 5844d82..8da6210 100644
--- a/src/reverse_api/cli.py
+++ b/src/reverse_api/cli.py
@@ -32,13 +32,17 @@ from .tui import (
from .utils import (
generate_folder_name,
generate_run_id,
+ get_actions_path,
get_config_path,
get_har_dir,
get_history_path,
+ get_scripts_dir,
get_timestamp,
parse_engineer_prompt,
parse_record_only_tag,
+ parse_codegen_tag,
)
+from .playwright_codegen import PlaywrightCodeGenerator
console = Console()
config_manager = ConfigManager(get_config_path())
@@ -105,6 +109,7 @@ def prompt_interactive_options(
# Tags for manual/agent modes with descriptions
tags = [
("@record-only", "record HAR only, skip reverse engineering"),
+ ("@codegen", "record actions and generate Playwright script"),
("@help", "show mode-specific help"),
]
for tag, meta in tags:
@@ -885,6 +890,9 @@ def handle_manual_help(mode_color=THEME_PRIMARY):
table.add_row("@record-only [prompt]", "Record HAR only, skip reverse engineering.\n[dim]Example: @record-only[/dim]")
table.add_row("", "")
+ table.add_row("@codegen [prompt]", "Record actions and generate Playwright script.\n[dim]Example: @codegen navigate to google[/dim]")
+ table.add_row("", "")
+
table.add_row("Shift+Tab", "Cycle to other modes (Engineer, Agent).")
console.print(table)
@@ -1109,8 +1117,12 @@ def run_manual_capture(prompt=None, url=None, reverse_engineer=True, model=None,
# Parse @record-only tag - if present, skip reverse engineering
prompt, is_record_only = parse_record_only_tag(prompt)
+ prompt, is_codegen = parse_codegen_tag(prompt)
+
if is_record_only:
reverse_engineer = False
+ if is_codegen:
+ reverse_engineer = False
run_id = generate_run_id()
timestamp = get_timestamp()
@@ -1128,7 +1140,12 @@ def run_manual_capture(prompt=None, url=None, reverse_engineer=True, model=None,
paths={"har_dir": str(get_har_dir(run_id, output_dir))},
)
- browser = ManualBrowser(run_id=run_id, prompt=prompt, output_dir=output_dir)
+ browser = ManualBrowser(
+ run_id=run_id,
+ prompt=prompt,
+ output_dir=output_dir,
+ enable_action_recording=is_codegen
+ )
har_path = browser.start(start_url=url)
if reverse_engineer:
@@ -1147,6 +1164,9 @@ def run_manual_capture(prompt=None, url=None, reverse_engineer=True, model=None,
usage=result.get("usage", {}),
paths={"script_path": result.get("script_path")},
)
+ elif is_codegen:
+ # Generate Playwright script from recorded actions
+ run_playwright_codegen(run_id, prompt, output_dir, start_url=url)
elif is_record_only:
# Show helpful message for record-only mode
console.print(" [dim]>[/dim] [white]recording complete[/white]")
@@ -1384,6 +1404,51 @@ def run_auto_capture(prompt=None, url=None, model=None, output_dir=None):
return None
+def run_playwright_codegen(
+ run_id: str,
+ prompt: str,
+ output_dir: str | None = None,
+ start_url: str | None = None
+):
+ """Generate Playwright script from recorded actions."""
+ actions_path = get_actions_path(run_id, output_dir)
+ if not actions_path.exists():
+ console.print(" [red]error:[/red] no actions recorded")
+ return
+
+ from .action_recorder import ActionRecorder
+
+ actions = ActionRecorder.load(actions_path)
+ action_list = actions.get_actions()
+
+ # If no explicit start_url, extract from first navigate action
+ if not start_url and action_list:
+ if action_list[0].type == "navigate" and action_list[0].url:
+ start_url = action_list[0].url
+
+ generator = PlaywrightCodeGenerator(action_list, start_url=start_url)
+ script = generator.generate()
+
+ scripts_dir = get_scripts_dir(run_id, output_dir)
+
+ # Handle duplicate file paths
+ script_path = scripts_dir / "automation.py"
+ if script_path.exists():
+ i = 1
+ while (scripts_dir / f"automation_{i}.py").exists():
+ i += 1
+ script_path = scripts_dir / f"automation_{i}.py"
+
+ script_path.write_text(script)
+
+ # Also write requirements.txt
+ (scripts_dir / "requirements.txt").write_text("playwright\n")
+
+ console.print(" [dim]>[/dim] [white]codegen complete[/white]")
+ console.print(f" [dim]>[/dim] [white]{script_path}[/white]")
+ console.print(f" [dim]>[/dim] [dim]run with: uv run python {script_path}[/dim]\n")
+
+
@main.command()
@click.argument("run_id")
@click.option(
diff --git a/src/reverse_api/playwright_codegen.py b/src/reverse_api/playwright_codegen.py
new file mode 100644
index 0000000..bf001b9
--- /dev/null
+++ b/src/reverse_api/playwright_codegen.py
@@ -0,0 +1,131 @@
+"""Generates Playwright automation scripts from recorded actions."""
+
+from typing import List
+
+from .action_recorder import RecordedAction
+
+
+class PlaywrightCodeGenerator:
+ """Generates Playwright automation scripts from recorded actions."""
+
+ def __init__(self, actions: List[RecordedAction], start_url: str | None = None):
+ self.actions = self._clean_actions(actions)
+ self.start_url = start_url
+
+ def _clean_actions(self, actions: List[RecordedAction]) -> List[RecordedAction]:
+ """Clean up actions (deduplicate fills, remove redundant events)."""
+ cleaned = []
+ last_fill_selector = None
+
+ for i, action in enumerate(actions):
+ # For 'fill' actions on the same selector, only keep the last one
+ if action.type == "fill":
+ # Look ahead to see if there's another fill for this selector
+ is_last_fill = True
+ for next_action in actions[i + 1:]:
+ if next_action.type == "fill" and next_action.selector == action.selector:
+ is_last_fill = False
+ break
+ if next_action.type != "fill":
+ # If interaction changes (e.g. click), we must keep the current fill
+ break
+
+ if is_last_fill:
+ cleaned.append(action)
+ else:
+ cleaned.append(action)
+
+ return cleaned
+
+ def _get_base_url(self, url: str | None) -> str | None:
+ """Extract base URL (without query params) for comparison."""
+ if not url:
+ return None
+ from urllib.parse import urlparse
+ parsed = urlparse(url)
+ return f"{parsed.scheme}://{parsed.netloc}{parsed.path}"
+
+ def generate(self) -> str:
+ """Generate complete Playwright script."""
+ lines = [
+ '"""',
+ "Playwright automation script",
+ "Generated by reverse-api-engineer",
+ '"""',
+ "",
+ "from playwright.sync_api import sync_playwright",
+ "",
+ "",
+ "# Stealth Chrome arguments to avoid bot detection",
+ "STEALTH_ARGS = [",
+ ' "--disable-blink-features=AutomationControlled",',
+ ' "--disable-infobars",',
+ ' "--disable-dev-shm-usage",',
+ ' "--disable-extensions",',
+ ' "--no-first-run",',
+ ' "--no-default-browser-check",',
+ ']',
+ "",
+ "",
+ "def main():",
+ " with sync_playwright() as p:",
+ " # Launch browser with stealth settings",
+ " browser = p.chromium.launch(",
+ " headless=False,",
+ " args=STEALTH_ARGS,",
+ ' ignore_default_args=["--enable-automation"],',
+ " )",
+ " context = browser.new_context(",
+ ' user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",',
+ " )",
+ " page = context.new_page()",
+ "",
+ ]
+
+ if self.start_url:
+ lines.append(f' # Start URL')
+ lines.append(f' page.goto("{self.start_url}")')
+ lines.append("")
+
+ current_url = self.start_url
+ last_nav_base = self._get_base_url(self.start_url) if self.start_url else None
+
+ for action in self.actions:
+ if action.type == "click":
+ lines.append(f" page.click('{action.selector}')")
+
+ elif action.type == "fill" and action.value:
+ # Escape quotes in value
+ value = action.value.replace('\"', '\\\"')
+ lines.append(f" page.fill('{action.selector}', \"{value}\")")
+
+ elif action.type == "press":
+ lines.append(f" page.press('{action.selector}', '{action.value}')")
+
+ elif action.type == "navigate":
+ # Skip if same as start URL or very similar (just different query params)
+ nav_base = self._get_base_url(action.url)
+ if nav_base != last_nav_base:
+ lines.append(f" page.goto('{action.url}')")
+ last_nav_base = nav_base
+ else:
+ continue # Skip duplicate navigation, don't add delay
+
+ # Add a small delay between actions as requested
+ lines.append(" page.wait_for_timeout(1000)")
+
+ lines.extend([
+ "",
+ " # Keep browser open for a moment",
+ " page.wait_for_timeout(2000)",
+ "",
+ " context.close()",
+ " browser.close()",
+ "",
+ "",
+ "if __name__ == '__main__':",
+ " main()",
+ ""
+ ])
+
+ return "\n".join(lines)
diff --git a/src/reverse_api/utils.py b/src/reverse_api/utils.py
index f2cd154..9683f59 100644
--- a/src/reverse_api/utils.py
+++ b/src/reverse_api/utils.py
@@ -327,6 +327,24 @@ def parse_record_only_tag(prompt: str) -> tuple[str, bool]:
return prompt, False
+def parse_codegen_tag(prompt: str) -> tuple[str, bool]:
+ """Parse @codegen tag from prompt.
+
+ When present, records actions and generates Playwright script instead of API client.
+
+ Returns:
+ tuple: (cleaned_prompt, is_codegen)
+ """
+ if not prompt:
+ return "", False
+
+ pattern = r"@codegen\s*"
+ if re.search(pattern, prompt, re.IGNORECASE):
+ cleaned = re.sub(pattern, "", prompt, flags=re.IGNORECASE).strip()
+ return cleaned, True
+ return prompt, False
+
+
def generate_run_id() -> str:
"""Generate a unique run ID using a short UUID format."""
return uuid.uuid4().hex[:12]
@@ -369,6 +387,12 @@ def get_har_dir(run_id: str, output_dir: str | None = None) -> Path:
return har_dir
+def get_actions_path(run_id: str, output_dir: str | None = None) -> Path:
+ """Get the actions JSON file path for a specific run."""
+ har_dir = get_har_dir(run_id, output_dir)
+ return har_dir / "actions.json"
+
+
def get_scripts_dir(run_id: str, output_dir: str | None = None) -> Path:
"""Get the scripts directory for a specific run."""
base_dir = get_base_output_dir(output_dir)