screenforge 0.4.0__py3-none-any.whl

cli/modes/dry_run.py

@@ -0,0 +1,237 @@
+"""Dry-run execution modes."""
+
+import cli.shared as _shared
+from cli.reporter import (
+    _apply_resume_summary,
+    _build_action_summary,
+    _build_inline_action_data,
+    _build_reporter,
+    _emit_run_started,
+)
+from cli.shared import (
+    _capture_ui_state,
+    _connect_adapter,
+    _ensure_executor_runtime,
+    _ensure_runtime_classes,
+    log,
+)
+from common.runtime_modes import MODE_DRY_RUN
+
+
+def _preview_action_resolution(device, platform: str, action_data: dict) -> dict:
+    _ensure_executor_runtime()
+    l_type = action_data.get("locator_type", "")
+    l_value = action_data.get("locator_value", "")
+    if not l_type or str(l_type).lower() == "global" or str(l_value).lower() == "global":
+        return {"resolvable": True, "resolution_error": ""}
+
+    u2_locator_map = {
+        "resourceId": "resourceId",
+        "text": "text",
+        "description": "description",
+        "id": "resourceId",
+    }
+    u2_key = u2_locator_map.get(l_type, l_type)
+    try:
+        element = _shared.get_actual_element(device, platform, u2_key, l_value)
+        return {"resolvable": element is not None, "resolution_error": ""}
+    except Exception as e:
+        return {"resolvable": False, "resolution_error": str(e)}
+
+
+def _build_resolution_hint(args, action_data: dict, resolution: dict) -> str:
+    if resolution.get("resolvable", False):
+        return ""
+
+    locator_type = action_data.get("locator_type", "")
+    if not args.vision and str(locator_type).lower() != "global":
+        return "Locator resolution failed. Verify current page state; consider enabling --vision."
+    return "Locator resolution failed. Verify page structure and whether the target element exists."
+
+
+def run_dry_run_mode(
+    args,
+    output_script_path: str,
+    context_content: str,
+    resume_context: dict,
+) -> int:
+    reporter = _build_reporter(args, output_script_path, MODE_DRY_RUN)
+    final_status = "failed"
+    exit_code = 1
+    final_error = ""
+    adapter = None
+    _emit_run_started(reporter, args, output_script_path, MODE_DRY_RUN)
+    _apply_resume_summary(reporter, resume_context)
+
+    try:
+        adapter = _connect_adapter(args, reporter)
+        ui_json, screenshot_base64 = _capture_ui_state(args, adapter, reporter, 1)
+        _ensure_runtime_classes()
+        brain = _shared.AutonomousBrain()
+        decision_data = brain.get_next_autonomous_action(
+            goal=args.goal,
+            context=context_content,
+            ui_json=ui_json,
+            history=[],
+            platform=args.platform,
+            last_error="",
+            screenshot_base64=screenshot_base64,
+        )
+
+        status = decision_data.get("status", "failed")
+        action_data = decision_data.get("result", {})
+        resolution = _preview_action_resolution(
+            adapter.driver, args.platform, action_data
+        )
+        resolution_hint = _build_resolution_hint(args, action_data, resolution)
+        reporter.emit_event(
+            "dry_run_preview",
+            status=status,
+            action=action_data.get("action", ""),
+            locator_type=action_data.get("locator_type", ""),
+            locator_value=action_data.get("locator_value", ""),
+            extra_value=action_data.get("extra_value", ""),
+            resolvable=resolution.get("resolvable", False),
+            resolution_error=resolution.get("resolution_error", ""),
+            resolution_hint=resolution_hint,
+        )
+        reporter.update_summary(
+            dry_run_preview={
+                "status": status,
+                "action": action_data.get("action", ""),
+                "locator_type": action_data.get("locator_type", ""),
+                "locator_value": action_data.get("locator_value", ""),
+                "extra_value": action_data.get("extra_value", ""),
+                "resolvable": resolution.get("resolvable", False),
+                "resolution_error": resolution.get("resolution_error", ""),
+                "resolution_hint": resolution_hint,
+            }
+        )
+
+        if status == "failed":
+            final_error = "Task cannot continue — AI determined failure"
+            log.warning("⚠️ [Dry Run] AI determined task cannot continue.")
+            exit_code = 1
+        else:
+            log.info(
+                f"🧪 [Dry Run] would_execute: {action_data.get('action', '')} "
+                f"{action_data.get('locator_type', '')}={action_data.get('locator_value', '')}"
+            )
+            final_status = "success"
+            exit_code = 0
+    except Exception as e:
+        final_error = str(e)
+        reporter.emit_event("dry_run_failed", error=str(e))
+        log.error(f"❌ [Dry Run] Simulation failed: {e}")
+    finally:
+        reporter.finalize(
+            status=final_status,
+            exit_code=exit_code,
+            steps_executed=1 if not final_error else 0,
+            last_error=final_error,
+        )
+        if adapter:
+            try:
+                adapter.teardown()
+            except Exception as e:
+                log.warning(f"⚠️ [Warning] Cleanup failed: {e}")
+    return exit_code
+
+
+def run_action_dry_run_mode(
+    args,
+    output_script_path: str,
+    resume_context: dict,
+) -> int:
+    reporter = _build_reporter(args, output_script_path, MODE_DRY_RUN)
+    final_status = "failed"
+    exit_code = 1
+    final_error = ""
+    adapter = None
+    preview_steps = []
+    _emit_run_started(reporter, args, output_script_path, MODE_DRY_RUN)
+    _apply_resume_summary(reporter, resume_context)
+
+    try:
+        action_data = _build_inline_action_data(args)
+        action_summary = _build_action_summary(args, action_data)
+        reporter.update_control_summary(
+            control_kind="action",
+            control_label=action_summary["action_name"],
+            source_ref="inline://action",
+            action=action_summary["action"],
+            locator_type=action_summary["locator_type"],
+            locator_value=action_summary["locator_value"],
+            extra_value=action_summary["extra_value"],
+        )
+        reporter.emit_event(
+            "action_loaded",
+            action_name=action_summary["action_name"],
+            action=action_summary["action"],
+            locator_type=action_summary["locator_type"],
+            locator_value=action_summary["locator_value"],
+        )
+
+        adapter = _connect_adapter(args, reporter)
+        resolution = _preview_action_resolution(
+            adapter.driver, args.platform, action_data
+        )
+        resolution_hint = _build_resolution_hint(args, action_data, resolution)
+        preview = {
+            "step": 1,
+            "name": action_data["name"],
+            "action": action_data["action"],
+            "locator_type": action_data["locator_type"],
+            "locator_value": action_data["locator_value"],
+            "extra_value": action_data["extra_value"],
+            "resolvable": resolution.get("resolvable", False),
+            "resolution_error": resolution.get("resolution_error", ""),
+            "resolution_hint": resolution_hint,
+        }
+        preview_steps.append(preview)
+        reporter.emit_event("action_step_preview", **preview)
+
+        reporter.update_summary(
+            action_summary=_build_action_summary(
+                args,
+                action_data,
+                resolvable=preview["resolvable"],
+                resolution_error=preview["resolution_error"],
+                resolution_hint=preview["resolution_hint"],
+            ),
+            dry_run_preview={
+                "workflow": False,
+                "step_count": 1,
+                "unresolved_steps": 0 if preview["resolvable"] else 1,
+                "preview_steps": preview_steps,
+            },
+        )
+        reporter.update_control_summary(
+            resolvable=preview["resolvable"],
+            resolution_error=preview["resolution_error"],
+            resolution_hint=preview["resolution_hint"],
+        )
+
+        if preview["resolvable"]:
+            final_status = "success"
+            exit_code = 0
+        else:
+            final_error = "Action locator cannot be resolved"
+            exit_code = 1
+    except Exception as e:
+        final_error = str(e)
+        reporter.emit_event("action_dry_run_failed", error=str(e))
+        log.error(f"❌ [Action] Dry-run failed: {e}")
+    finally:
+        reporter.finalize(
+            status=final_status,
+            exit_code=exit_code,
+            steps_executed=len(preview_steps),
+            last_error=final_error,
+        )
+        if adapter:
+            try:
+                adapter.teardown()
+            except Exception as e:
+                log.warning(f"⚠️ [Warning] Cleanup failed: {e}")
+    return exit_code

cli/modes/init.py

@@ -0,0 +1,133 @@
+"""Interactive init wizard: guides new users through first-time setup."""
+
+from pathlib import Path
+
+
+def _prompt_choice(question: str, options: list[str], default: int = 0) -> int:
+    print(f"\n  {question}")
+    for i, opt in enumerate(options):
+        marker = ">" if i == default else " "
+        print(f"  {marker} [{i + 1}] {opt}")
+    while True:
+        raw = input(f"  Choice [{default + 1}]: ").strip()
+        if not raw:
+            return default
+        try:
+            choice = int(raw) - 1
+            if 0 <= choice < len(options):
+                return choice
+        except ValueError:
+            pass
+        print(f"  Please enter 1-{len(options)}")
+
+
+def _prompt_input(question: str, default: str = "") -> str:
+    suffix = f" [{default}]" if default else ""
+    raw = input(f"  {question}{suffix}: ").strip()
+    return raw or default
+
+
+def run_init_mode() -> int:
+    print("\n  screenforge init — First-time setup wizard")
+    print("  " + "=" * 44)
+
+    # Step 1: Platform
+    platform_idx = _prompt_choice(
+        "Which platform will you test?",
+        ["Web (Chrome/Playwright)", "Android (uiautomator2)", "iOS (WebDriverAgent)"],
+        default=0,
+    )
+    platform = ["web", "android", "ios"][platform_idx]
+
+    # Step 2: LLM config
+    print("\n  ScreenForge needs an LLM API key for AI-driven testing.")
+    print("  (Skip this for --demo mode which requires no key)")
+
+    api_key = _prompt_input("OPENAI_API_KEY (or compatible)", "sk-...")
+    base_url = _prompt_input("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    model = _prompt_input("MODEL_NAME", "gpt-4o")
+
+    # Step 3: Write .env
+    env_path = Path(".env")
+    if env_path.exists():
+        overwrite = _prompt_choice(
+            ".env already exists. Overwrite?",
+            ["No, keep existing", "Yes, overwrite"],
+            default=0,
+        )
+        if overwrite == 0:
+            print("  Keeping existing .env")
+        else:
+            _write_env(env_path, api_key, base_url, model)
+    else:
+        _write_env(env_path, api_key, base_url, model)
+
+    # Step 4: Platform-specific checks
+    print(f"\n  Platform: {platform}")
+    if platform == "web":
+        _check_web_deps()
+    elif platform == "android":
+        _check_android_deps()
+    elif platform == "ios":
+        _check_ios_deps()
+
+    # Step 5: Suggest next steps
+    print("\n  Setup complete! Next steps:")
+    print("  " + "-" * 30)
+    print("  1. screenforge --demo                    # See it work (no API key needed)")
+    print(f"  2. screenforge --doctor --platform {platform}  # Verify environment")
+    print(f"  3. screenforge --action goto --platform {platform} --extra-value \"https://example.com\"")
+    print()
+
+    return 0
+
+
+def _write_env(path: Path, api_key: str, base_url: str, model: str) -> None:
+    content = f"""OPENAI_API_KEY = "{api_key}"
+OPENAI_BASE_URL = "{base_url}"
+MODEL_NAME = "{model}"
+"""
+    path.write_text(content)
+    print(f"  Written: {path}")
+
+
+def _check_web_deps() -> None:
+    try:
+        import playwright  # noqa: F401
+        print("  [ok] playwright installed")
+    except ImportError:
+        print("  [!!] playwright not installed")
+        print("       Fix: pip install playwright && playwright install chromium")
+        return
+
+    from shutil import which
+    if which("chromium") or which("google-chrome") or which("chrome"):
+        print("  [ok] Chrome/Chromium found")
+    else:
+        print("  [ok] Will use Playwright's bundled Chromium")
+
+
+def _check_android_deps() -> None:
+    from shutil import which
+
+    if which("adb"):
+        print("  [ok] adb found")
+    else:
+        print("  [!!] adb not found in PATH")
+        print("       Fix: install Android SDK platform-tools")
+
+    try:
+        import uiautomator2  # noqa: F401
+        print("  [ok] uiautomator2 installed")
+    except ImportError:
+        print("  [!!] uiautomator2 not installed")
+        print("       Fix: pip install screenforge[android]")
+
+
+def _check_ios_deps() -> None:
+    try:
+        import wda  # noqa: F401
+        print("  [ok] facebook-wda installed")
+    except ImportError:
+        print("  [!!] facebook-wda not installed")
+        print("       Fix: pip install screenforge[ios]")

cli/modes/plan.py

@@ -0,0 +1,148 @@
+"""Plan-only execution modes."""
+
+import cli.shared as _shared
+from cli.reporter import (
+    _apply_resume_summary,
+    _build_action_summary,
+    _build_inline_action_data,
+    _build_reporter,
+    _emit_run_started,
+)
+from cli.shared import (
+    _capture_ui_state,
+    _connect_adapter,
+    _ensure_runtime_classes,
+    log,
+)
+from common.runtime_modes import MODE_PLAN_ONLY
+
+
+def run_plan_only_mode(
+    args,
+    output_script_path: str,
+    context_content: str,
+    resume_context: dict,
+) -> int:
+    reporter = _build_reporter(args, output_script_path, MODE_PLAN_ONLY)
+    final_status = "failed"
+    exit_code = 1
+    final_error = ""
+    adapter = None
+    steps_executed = 0
+    _emit_run_started(reporter, args, output_script_path, MODE_PLAN_ONLY)
+    _apply_resume_summary(reporter, resume_context)
+
+    try:
+        adapter = _connect_adapter(args, reporter)
+        ui_json, screenshot_base64 = _capture_ui_state(args, adapter, reporter, 1)
+        _ensure_runtime_classes()
+        brain = _shared.AutonomousBrain()
+        plan = brain.get_execution_plan(
+            goal=args.goal,
+            context=context_content,
+            ui_json=ui_json,
+            history=[],
+            platform=args.platform,
+            screenshot_base64=screenshot_base64,
+        )
+
+        planned_steps = plan.get("planned_steps", [])
+        steps_executed = len(planned_steps) or 1
+        reporter.emit_event(
+            "plan_generated",
+            current_state_summary=plan.get("current_state_summary", ""),
+            planned_steps=planned_steps,
+            suggested_assertion=plan.get("suggested_assertion", ""),
+            risks=plan.get("risks", []),
+        )
+        reporter.update_summary(plan_preview=plan)
+        log.info(f"🧭 [Plan] Current page summary: {plan.get('current_state_summary', '')}")
+        for index, step in enumerate(planned_steps, start=1):
+            log.info(f"🧭 [Plan] Step {index}: {step}")
+        if plan.get("suggested_assertion"):
+            log.info(f"🧭 [Plan] Suggested assertion: {plan.get('suggested_assertion', '')}")
+
+        final_status = "success"
+        exit_code = 0
+    except Exception as e:
+        final_error = str(e)
+        reporter.emit_event("plan_failed", error=str(e))
+        log.error(f"❌ [Plan] Plan generation failed: {e}")
+    finally:
+        reporter.finalize(
+            status=final_status,
+            exit_code=exit_code,
+            steps_executed=steps_executed,
+            last_error=final_error,
+        )
+        if adapter:
+            try:
+                adapter.teardown()
+            except Exception as e:
+                log.warning(f"⚠️ [Warning] Cleanup failed: {e}")
+    return exit_code
+
+
+def run_action_plan_only_mode(
+    args,
+    output_script_path: str,
+    resume_context: dict,
+) -> int:
+    reporter = _build_reporter(args, output_script_path, MODE_PLAN_ONLY)
+    final_status = "failed"
+    exit_code = 1
+    final_error = ""
+    _emit_run_started(reporter, args, output_script_path, MODE_PLAN_ONLY)
+    _apply_resume_summary(reporter, resume_context)
+
+    try:
+        action_data = _build_inline_action_data(args)
+        plan = {
+            "current_state_summary": f"Inline action [{action_data['name']}] preview",
+            "planned_steps": [action_data["name"]],
+            "suggested_assertion": "",
+            "risks": [],
+        }
+        action_summary = _build_action_summary(args, action_data)
+        reporter.update_control_summary(
+            control_kind="action",
+            control_label=action_summary["action_name"],
+            source_ref="inline://action",
+            action=action_summary["action"],
+            locator_type=action_summary["locator_type"],
+            locator_value=action_summary["locator_value"],
+            extra_value=action_summary["extra_value"],
+        )
+        reporter.emit_event(
+            "action_loaded",
+            action_name=action_summary["action_name"],
+            action=action_summary["action"],
+            locator_type=action_summary["locator_type"],
+            locator_value=action_summary["locator_value"],
+        )
+        reporter.emit_event(
+            "plan_generated",
+            current_state_summary=plan["current_state_summary"],
+            planned_steps=plan["planned_steps"],
+            suggested_assertion="",
+            risks=[],
+        )
+        reporter.update_summary(plan_preview=plan, action_summary=action_summary)
+
+        log.info(f"🧭 [Action] Action name: {action_summary['action_name']}")
+        log.info(f"🧭 [Action] Preview step: {action_summary['action_name']}")
+
+        final_status = "success"
+        exit_code = 0
+    except Exception as e:
+        final_error = str(e)
+        reporter.emit_event("action_plan_failed", error=str(e))
+        log.error(f"❌ [Action] Plan generation failed: {e}")
+    finally:
+        reporter.finalize(
+            status=final_status,
+            exit_code=exit_code,
+            steps_executed=1 if final_status == "success" else 0,
+            last_error=final_error,
+        )
+    return exit_code