browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/cli/main.py

@@ -0,0 +1,298 @@
+"""CLI entrypoint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from browser_cli import __version__, exit_codes
+from browser_cli.actions import get_action_specs
+from browser_cli.cli.error_hints import next_hint_for_error
+from browser_cli.commands.action import run_action_command
+from browser_cli.commands.automation import run_automation_command
+from browser_cli.commands.doctor import run_doctor_command
+from browser_cli.commands.install_skills import run_install_skills_command
+from browser_cli.commands.paths import run_paths_command
+from browser_cli.commands.read import run_read_command
+from browser_cli.commands.reload import run_reload_command
+from browser_cli.commands.status import run_status_command
+from browser_cli.commands.task import run_task_command
+from browser_cli.errors import BrowserCliError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="browser-cli")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    read_parser = subparsers.add_parser(
+        "read",
+        help="Read a rendered page as HTML or snapshot text.",
+        description="Open a page, wait for render completion, and capture rendered output.",
+    )
+    read_parser.add_argument("url", help="Target page URL.")
+    read_parser.add_argument(
+        "--snapshot",
+        action="store_true",
+        help="Return snapshot tree output instead of rendered HTML.",
+    )
+    read_parser.add_argument(
+        "--scroll-bottom",
+        action="store_true",
+        help="Scroll to the bottom before capture to trigger lazy-loaded content.",
+    )
+    read_parser.set_defaults(handler=run_read_command)
+
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="Diagnose whether Browser CLI is ready on this machine.",
+        description="Diagnose install, browser, runtime, and service readiness with next-step guidance.",
+    )
+    doctor_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Return machine-readable diagnostic results.",
+    )
+    doctor_parser.set_defaults(handler=run_doctor_command)
+
+    paths_parser = subparsers.add_parser(
+        "paths",
+        help="Show Browser CLI runtime paths.",
+        description="Show the canonical Browser CLI runtime paths for home, tasks, automations, logs, and artifacts.",
+    )
+    paths_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Return machine-readable path data.",
+    )
+    paths_parser.set_defaults(handler=run_paths_command)
+
+    task_parser = subparsers.add_parser(
+        "task",
+        help="Run or validate a local task directory.",
+        description="`task` is local editable source. Run task.py + task.meta.json from a local task directory.",
+    )
+    task_subparsers = task_parser.add_subparsers(dest="task_subcommand", metavar="TASK_COMMAND")
+
+    task_run_parser = task_subparsers.add_parser(
+        "run",
+        help="Run a task directory.",
+        description="Load task.py from a local task directory and execute its run() entrypoint.",
+    )
+    task_run_parser.add_argument("path", help="Path to the task directory.")
+    task_run_parser.add_argument(
+        "--set",
+        dest="set_values",
+        action="append",
+        default=[],
+        help="Override one input as KEY=VALUE. Repeat as needed.",
+    )
+    task_run_parser.add_argument(
+        "--inputs-json",
+        help="JSON object with input overrides.",
+    )
+    task_run_parser.set_defaults(handler=run_task_command)
+
+    task_validate_parser = task_subparsers.add_parser(
+        "validate",
+        help="Validate a task directory.",
+        description="Validate task.py and task.meta.json in a local task directory.",
+    )
+    task_validate_parser.add_argument("path", help="Path to the task directory.")
+    task_validate_parser.set_defaults(handler=run_task_command)
+
+    task_examples_parser = task_subparsers.add_parser(
+        "examples",
+        help="List built-in task examples.",
+        description="Show canonical task examples available from the installed package.",
+    )
+    task_examples_parser.set_defaults(handler=run_task_command)
+
+    task_template_parser = task_subparsers.add_parser(
+        "template",
+        help="Print or write a minimal task template.",
+        description="Expose canonical task.py, task.meta.json, and automation.toml templates.",
+    )
+    task_template_parser.add_argument(
+        "--print",
+        dest="print_template",
+        action="store_true",
+        help="Print the template files to stdout.",
+    )
+    task_template_parser.add_argument(
+        "--output",
+        help="Write the template files into the given directory.",
+    )
+    task_template_parser.set_defaults(handler=run_task_command)
+
+    automation_parser = subparsers.add_parser(
+        "automation",
+        help="Publish and operate versioned automations.",
+        description="`automation` is a published immutable snapshot. Publish a task snapshot and manage automation service state.",
+    )
+    automation_subparsers = automation_parser.add_subparsers(
+        dest="automation_subcommand", metavar="AUTOMATION_COMMAND"
+    )
+
+    automation_publish_parser = automation_subparsers.add_parser(
+        "publish",
+        help="Publish one task directory into the automation service.",
+        description="Create a published automation from a task directory.",
+    )
+    automation_publish_parser.add_argument("path", help="Path to the task directory.")
+    automation_publish_parser.set_defaults(handler=run_automation_command)
+
+    automation_list_parser = automation_subparsers.add_parser(
+        "list",
+        help="List published automations.",
+        description="Show persisted automation ids, versions, and latest run summaries.",
+    )
+    automation_list_parser.set_defaults(handler=run_automation_command)
+
+    automation_versions_parser = automation_subparsers.add_parser(
+        "versions",
+        help="List published snapshot versions for one automation.",
+        description="Inspect the local snapshot history for a published automation.",
+    )
+    automation_versions_parser.add_argument("automation_id", help="Persisted automation id.")
+    automation_versions_parser.set_defaults(handler=run_automation_command)
+
+    automation_inspect_parser = automation_subparsers.add_parser(
+        "inspect",
+        help="Inspect one published automation.",
+        description="Combine service metadata, latest run status, and local snapshot version details.",
+    )
+    automation_inspect_parser.add_argument("automation_id", help="Persisted automation id.")
+    automation_inspect_parser.add_argument("--version", type=int, help="Specific snapshot version.")
+    automation_inspect_parser.set_defaults(handler=run_automation_command)
+
+    automation_ui_parser = automation_subparsers.add_parser(
+        "ui",
+        help="Start the local automation service if needed and print the UI URL.",
+        description="Ensure the automation service is running and print the local Web UI URL.",
+    )
+    automation_ui_parser.set_defaults(handler=run_automation_command)
+
+    automation_status_parser = automation_subparsers.add_parser(
+        "status",
+        help="Show local automation-service status.",
+        description="Inspect automation-service health without forcing a browser action.",
+    )
+    automation_status_parser.set_defaults(handler=run_automation_command)
+
+    automation_stop_parser = automation_subparsers.add_parser(
+        "stop",
+        help="Stop the local automation service.",
+        description="Request automation-service shutdown and clean stale runtime metadata.",
+    )
+    automation_stop_parser.set_defaults(handler=run_automation_command)
+
+    automation_import_parser = automation_subparsers.add_parser(
+        "import",
+        help="Import an automation manifest into the persistent automation service.",
+        description="Load automation.toml and publish it into the local automation-service database.",
+    )
+    automation_import_parser.add_argument("path", help="Path to automation.toml.")
+    automation_import_parser.add_argument(
+        "--enable",
+        action="store_true",
+        help="Enable the imported automation immediately.",
+    )
+    automation_import_parser.set_defaults(handler=run_automation_command)
+
+    automation_export_parser = automation_subparsers.add_parser(
+        "export",
+        help="Export one persisted automation to automation.toml.",
+        description="Write a persisted automation definition back out as automation.toml.",
+    )
+    automation_export_parser.add_argument("automation_id", help="Persisted automation id.")
+    automation_export_parser.add_argument(
+        "--output",
+        required=True,
+        help="Path to write automation.toml.",
+    )
+    automation_export_parser.set_defaults(handler=run_automation_command)
+
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show daemon, backend, and workspace runtime status.",
+        description="Inspect Browser CLI runtime state and print operational guidance.",
+    )
+    status_parser.set_defaults(handler=run_status_command)
+
+    reload_parser = subparsers.add_parser(
+        "reload",
+        help="Reset Browser CLI runtime and restart the daemon/browser backend.",
+        description="Clear Browser CLI runtime state, restart the daemon, and print the refreshed status.",
+    )
+    reload_parser.set_defaults(handler=run_reload_command)
+
+    skills_parser = subparsers.add_parser(
+        "install-skills",
+        help="Install packaged skills for Browser CLI to a skills directory.",
+        description="Copy packaged skills for Browser CLI from the installed package to the target skills directory.",
+    )
+    skills_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be installed without making changes.",
+    )
+    skills_parser.add_argument(
+        "--target",
+        help="Optional target directory. Defaults to ~/.agents/skills.",
+    )
+    skills_parser.set_defaults(handler=run_install_skills_command)
+
+    for spec in get_action_specs():
+        parser_name = spec.cli_name or spec.name
+        action_parser = subparsers.add_parser(
+            parser_name,
+            help=spec.help,
+            description=spec.description,
+        )
+        spec.add_arguments(action_parser)
+        action_parser.set_defaults(
+            handler=run_action_command,
+            action_name=spec.name,
+            action_request_builder=spec.build_request,
+            action_start_if_needed=spec.start_if_needed,
+        )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(list(argv) if argv is not None else None)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else exit_codes.USAGE_ERROR
+        return code
+
+    if not hasattr(args, "handler"):
+        parser.print_help()
+        return exit_codes.USAGE_ERROR
+
+    try:
+        result = args.handler(args)
+    except BrowserCliError as exc:
+        sys.stderr.write(f"Error: {exc}\n")
+        hint = next_hint_for_error(exc)
+        if hint:
+            sys.stderr.write(f"Next: {hint}\n")
+        return exc.exit_code
+    except KeyboardInterrupt:
+        sys.stderr.write("Error: interrupted.\n")
+        return exit_codes.TEMPORARY_FAILURE
+    except Exception as exc:  # pragma: no cover - last-resort guard
+        sys.stderr.write(f"Error: unexpected failure: {exc}\n")
+        return exit_codes.INTERNAL_ERROR
+
+    if result:
+        sys.stdout.write(result)
+    return exit_codes.SUCCESS
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

browser_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command handlers."""

browser_cli/commands/action.py

@@ -0,0 +1,25 @@
+"""Generic daemon-backed action command runner."""
+
+from __future__ import annotations
+
+from argparse import Namespace
+
+from browser_cli.daemon.client import send_command
+from browser_cli.errors import InvalidInputError
+from browser_cli.outputs.json import render_json_payload
+
+
+def run_action_command(args: Namespace) -> str:
+    builder = getattr(args, "action_request_builder", None)
+    if builder is None:
+        raise InvalidInputError("Internal CLI configuration error: missing action request builder.")
+    try:
+        request_payload = builder(args)
+    except ValueError as exc:
+        raise InvalidInputError(str(exc)) from exc
+    response = send_command(
+        args.action_name,
+        request_payload,
+        start_if_needed=bool(getattr(args, "action_start_if_needed", True)),
+    )
+    return render_json_payload(response)

browser_cli/commands/automation.py

@@ -0,0 +1,304 @@
+"""Automation CLI commands."""
+
+from __future__ import annotations
+
+import json
+from argparse import Namespace
+from pathlib import Path
+
+from browser_cli.automation import load_automation_manifest, publish_task_dir
+from browser_cli.automation.models import AutomationManifest
+from browser_cli.automation.projections import (
+    manifest_to_config_payload,
+    manifest_to_persisted_definition,
+    payload_to_persisted_definition,
+    persisted_definition_to_config_payload,
+)
+from browser_cli.automation.service.client import (
+    automation_service_ui_url,
+    ensure_automation_service_running,
+    read_automation_service_run_info,
+    request_automation_service,
+    stop_automation_service,
+)
+from browser_cli.constants import get_app_paths
+from browser_cli.errors import InvalidInputError
+from browser_cli.outputs.json import render_json_payload
+
+
+def run_automation_command(args: Namespace) -> str:
+    subcommand = args.automation_subcommand
+    if subcommand == "publish":
+        source_task_dir = Path(args.path).expanduser().resolve()
+        published = publish_task_dir(source_task_dir, app_paths=get_app_paths())
+        ensure_automation_service_running()
+        payload = request_automation_service(
+            "POST",
+            "/api/automations/import",
+            body={
+                "path": str(published.manifest_path),
+                "enabled": True,
+            },
+            start_if_needed=False,
+        )
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {
+                    "published": {
+                        "automation_id": published.automation_id,
+                        "automation_name": published.automation_name,
+                        "version": published.version,
+                        "manifest_source": published.manifest_source,
+                        "source_task_dir": str(source_task_dir),
+                        "snapshot_dir": str(published.snapshot_dir),
+                        "manifest_path": str(published.manifest_path),
+                    },
+                    "service": payload.get("data") or {},
+                    "next_commands": {
+                        "inspect": f"browser-cli automation inspect {published.automation_id}",
+                        "status": "browser-cli automation status",
+                        "ui": "browser-cli automation ui",
+                    },
+                    "model": {
+                        "task": "local editable source",
+                        "automation": "published immutable snapshot",
+                    },
+                },
+                "meta": {"action": "automation-publish"},
+            }
+        )
+    if subcommand == "list":
+        payload = request_automation_service("GET", "/api/automations", start_if_needed=True)
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {"automations": payload.get("data") or []},
+                "meta": {"action": "automation-list"},
+            }
+        )
+    if subcommand == "versions":
+        versions = _load_snapshot_versions(args.automation_id)
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {"automation_id": args.automation_id, "versions": versions},
+                "meta": {"action": "automation-versions"},
+            }
+        )
+    if subcommand == "inspect":
+        payload = request_automation_service(
+            "GET", f"/api/automations/{args.automation_id}", start_if_needed=True
+        )
+        versions = _load_snapshot_versions(args.automation_id)
+        live_automation_data = dict(payload.get("data") or {})
+        live_config = (
+            persisted_definition_to_config_payload(
+                payload_to_persisted_definition(live_automation_data)
+            )
+            if live_automation_data
+            else None
+        )
+        selected = (
+            _select_snapshot_version(
+                args.automation_id,
+                versions,
+                version=getattr(args, "version", None),
+            )
+            if getattr(args, "version", None) is not None
+            else None
+        )
+        snapshot_config = (
+            selected.get("snapshot_automation")
+            if isinstance(selected, dict) and isinstance(selected.get("snapshot_automation"), dict)
+            else None
+        )
+        snapshot_config_error = (
+            str(selected.get("snapshot_config_error") or "")
+            if isinstance(selected, dict) and selected.get("snapshot_config_error")
+            else None
+        )
+        latest_run = live_automation_data.get("latest_run")
+        latest_run_payload = latest_run if isinstance(latest_run, dict) else None
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {
+                    "snapshot_config": snapshot_config,
+                    "snapshot_config_error": snapshot_config_error,
+                    "live_config": live_config,
+                    "versions": versions,
+                    "selected_version": selected,
+                    "latest_run": latest_run_payload,
+                    "summary": _build_inspect_summary(
+                        args.automation_id,
+                        live_automation_data,
+                        versions,
+                        selected,
+                        latest_run_payload,
+                    ),
+                },
+                "meta": {"action": "automation-inspect"},
+            }
+        )
+    if subcommand == "import":
+        ensure_automation_service_running()
+        manifest = load_automation_manifest(args.path)
+        automation = manifest_to_persisted_definition(
+            manifest, enabled=bool(getattr(args, "enable", False))
+        )
+        body = persisted_definition_to_config_payload(automation)
+        body["enabled"] = automation.enabled
+        payload = request_automation_service(
+            "POST",
+            "/api/automations",
+            body=body,
+            start_if_needed=False,
+        )
+        payload["meta"] = {"action": "automation-import"}
+        return render_json_payload(payload)
+    if subcommand == "export":
+        payload = request_automation_service(
+            "GET",
+            f"/api/automations/{args.automation_id}/export",
+            start_if_needed=True,
+        )
+        output_path = Path(args.output).expanduser().resolve()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(str((payload.get("data") or {}).get("toml") or ""), encoding="utf-8")
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {"automation_id": args.automation_id, "output": str(output_path)},
+                "meta": {"action": "automation-export"},
+            }
+        )
+    if subcommand == "ui":
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": {
+                    "url": automation_service_ui_url(),
+                    "run_info": read_automation_service_run_info(),
+                },
+                "meta": {"action": "automation-ui"},
+            }
+        )
+    if subcommand == "status":
+        run_info = read_automation_service_run_info()
+        if not run_info:
+            return render_json_payload(
+                {
+                    "ok": True,
+                    "data": {"running": False},
+                    "meta": {"action": "automation-status"},
+                }
+            )
+        payload = request_automation_service("GET", "/api/service/status", start_if_needed=False)
+        payload["meta"] = {"action": "automation-status"}
+        return render_json_payload(payload)
+    if subcommand == "stop":
+        return render_json_payload(
+            {
+                "ok": True,
+                "data": stop_automation_service(),
+                "meta": {"action": "automation-stop"},
+            }
+        )
+    raise ValueError(f"Unsupported automation subcommand: {subcommand}")
+
+
+def _load_snapshot_versions(automation_id: str) -> list[dict[str, object]]:
+    versions_dir = get_app_paths().automations_dir / automation_id / "versions"
+    if not versions_dir.exists():
+        return []
+    versions: list[dict[str, object]] = []
+    for entry in sorted(versions_dir.iterdir(), key=_version_sort_key, reverse=True):
+        if not entry.is_dir() or not entry.name.isdigit():
+            continue
+        publish_path = entry / "publish.json"
+        publish_data = _read_json_file(publish_path)
+        snapshot_manifest, snapshot_config_error = _load_snapshot_manifest(
+            entry / "automation.toml"
+        )
+        versions.append(
+            {
+                "version": int(entry.name),
+                "snapshot_dir": str(entry),
+                "publish": publish_data,
+                "snapshot_automation": (
+                    _snapshot_manifest_to_automation_payload(snapshot_manifest)
+                    if snapshot_manifest is not None
+                    else None
+                ),
+                "snapshot_config_error": snapshot_config_error,
+                "snapshot_latest_run": publish_data.get("latest_run")
+                if isinstance(publish_data.get("latest_run"), dict)
+                else None,
+                "task_path": str(entry / "task.py"),
+                "task_meta_path": str(entry / "task.meta.json"),
+            }
+        )
+    return versions
+
+
+def _select_snapshot_version(
+    automation_id: str,
+    versions: list[dict[str, object]],
+    *,
+    version: int | None,
+) -> dict[str, object] | None:
+    if version is None:
+        return versions[0] if versions else None
+    for item in versions:
+        if item["version"] == version:
+            return item
+    raise InvalidInputError(f"Automation version not found for {automation_id}: {version}")
+
+
+def _version_sort_key(path: Path) -> int:
+    try:
+        return int(path.name)
+    except ValueError:
+        return -1
+
+
+def _read_json_file(path: Path) -> dict[str, object]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _build_inspect_summary(
+    automation_id: str,
+    automation_data: dict[str, object],
+    versions: list[dict[str, object]],
+    selected: dict[str, object] | None,
+    latest_run: dict[str, object] | None,
+) -> dict[str, object]:
+    latest_run_status = None
+    if isinstance(latest_run, dict):
+        latest_run_status = latest_run.get("status")
+    return {
+        "automation_id": automation_id,
+        "persisted_version": automation_data.get("version"),
+        "available_versions": [item["version"] for item in versions],
+        "selected_version": selected.get("version") if selected else None,
+        "selected_snapshot_dir": selected.get("snapshot_dir") if selected else None,
+        "selected_task_path": selected.get("task_path") if selected else None,
+        "schedule_mode": automation_data.get("schedule_kind"),
+        "latest_run_status": latest_run_status,
+    }
+
+
+def _load_snapshot_manifest(path: Path) -> tuple[AutomationManifest | None, str | None]:
+    if not path.exists():
+        return None, None
+    try:
+        return load_automation_manifest(path), None
+    except InvalidInputError as exc:
+        return None, str(exc)
+
+
+def _snapshot_manifest_to_automation_payload(manifest: AutomationManifest) -> dict[str, object]:
+    return manifest_to_config_payload(manifest)