unchainedsky-cli 0.1.0__tar.gz

unchainedsky_cli-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: unchainedsky-cli
+Version: 0.1.0
+Summary: Browser automation CLI over local Chrome CDP
+Requires-Python: >=3.10
+Requires-Dist: websockets>=12.0
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.49; extra == "agent"

unchainedsky_cli-0.1.0/README.md

@@ -0,0 +1,182 @@
+# unchainedsky-cli
+
+Browser automation CLI over local Chrome CDP — DDM-first methodology for LLM agents.
+
+## Install
+
+```bash
+# With uv (recommended)
+uv tool install unchainedsky-cli[agent]
+
+# Or pip
+pip install unchainedsky-cli[agent]
+
+# Or brew
+brew install --HEAD unchainedsky/tap/unchainedsky-cli
+```
+
+The `[agent]` extra includes the Anthropic SDK for the interactive Claude agent. Omit it if you only need the CLI tools.
+
+## Quick Start
+
+```bash
+# Launch Chrome and browse
+unchained launch https://news.ycombinator.com
+
+# Navigate returns page layout + intel probe automatically
+unchained navigate https://example.com
+
+# Search page text
+unchained ddm --text --find "price"
+
+# Element details at coordinates
+unchained ddm --at 694,584
+
+# Start the interactive Claude agent
+export ANTHROPIC_API_KEY=sk-ant-...
+unchained agent "find the cheapest flight to NYC"
+```
+
+## Launch Options
+
+```bash
+# Sandboxed profile (default — clean, isolated)
+unchained launch
+
+# Existing Chrome profile (with cookies, logins, extensions)
+unchained --port 9333 launch --use-profile --profile "Profile 3" https://x.com
+
+# Headless with stealth (auto-enables fingerprint evasion)
+unchained launch --headless https://example.com
+
+# Stealth mode (visible window, bot detection evasion)
+unchained launch --stealth https://example.com
+
+# Multiple profiles on different ports
+unchained --port 9222 launch --profile work
+unchained --port 9333 launch --use-profile --profile "Profile 3"
+unchained --port 9444 launch --use-profile --profile "Profile 8"
+```
+
+## Commands
+
+### Browser Lifecycle
+
+| Command | Description |
+|---------|-------------|
+| `launch [url]` | Launch Chrome with CDP (`--profile`, `--use-profile`, `--stealth`, `--headless`) |
+| `status` | Check if Chrome is alive |
+| `kill` | Kill Chrome on this port |
+
+### Navigation & Interaction
+
+| Command | Description |
+|---------|-------------|
+| `navigate <url>` | Navigate (returns inline DDM layout + Intel probe) |
+| `click --x X --y Y` | Click at pixel coordinates from DDM |
+| `click --selector CSS` | Click by CSS selector |
+| `type <text>` | Type into focused element |
+| `press_enter` | Press Enter key |
+| `key <key> [--modifiers N]` | Press any key (Escape, Tab, ArrowDown, etc.) |
+| `scroll [--direction DIR]` | Scroll page (up/down/left/right, default: 500px) |
+| `submit_form [--selector]` | Submit a form |
+| `set_file --selector CSS --files PATH...` | Set files on file input |
+
+### Page Intelligence
+
+| Command | Description |
+|---------|-------------|
+| `ddm` | DOM Density Map — text layout with interactive elements |
+| `ddm --text` | Extract page text (innerText) |
+| `ddm --text --find "keyword"` | Search page text, show nearby elements |
+| `ddm --at 694,584` | Element details at pixel coordinates |
+| `ddm --sparse` | RLE-compressed output (~100-400 tokens) |
+| `ddm --interactive` | Interactive elements only (smallest output) |
+| `ddm --llm-2pass` | LLM-optimized layout (default for navigate) |
+| `ddm --tabs` | List open tabs |
+| `ddm --forms` | Detect forms as callable contracts |
+| `intel --probe` | Fingerprint page + rank 8 extraction strategies |
+| `intel --extract` | Full extraction pipeline (auto-selects strategy) |
+| `intel --stores` | List JS data stores (YouTube, Next.js, Nuxt, etc.) |
+| `intel --shape <global>` | Map JS global variable structure |
+| `intel --find-paths <global> <pattern>` | Search paths in JS globals |
+
+### Data & Tabs
+
+| Command | Description |
+|---------|-------------|
+| `js <expression>` | Evaluate JavaScript |
+| `js_frame <frame> <expr>` | Evaluate JS in a specific iframe |
+| `screenshot [--output FILE]` | Save screenshot (last resort — use DDM first) |
+| `tabs` | List open tabs |
+| `create_tab [url]` | Open a new tab |
+| `close_tab <tab_id>` | Close a tab |
+| `cookies get [--urls URL...]` | Get cookies |
+| `cookies set <json>` | Inject cookies |
+| `frames` | List iframes |
+| `cdp <method> [params]` | Send raw CDP command |
+| `wait [--strategy dom\|network\|both]` | Wait for page load |
+| `alias set <name> <tab_id>` | Set a tab alias |
+| `alias list` | List tab aliases |
+
+### Agent
+
+| Command | Description |
+|---------|-------------|
+| `agent [task]` | Interactive Claude browser agent |
+| `agent --model opus "task"` | Use a specific model (sonnet/opus/haiku) |
+
+## DDM-First Methodology
+
+Every browsing task follows this pipeline:
+
+1. **ORIENT** — `navigate` and `click` return DDM layout inline. Read it. Don't call `ddm` separately.
+2. **IDENTIFY** — `ddm --at x,y` on elements you need details about.
+3. **CLASSIFY** — Check the Intel probe in navigate output. If `js_global > 50%`, use `intel --stores`. If `host_attrs > 50%`, use `intel --extract`.
+4. **ACT** — Click coordinates from DDM, type text, or run JS.
+5. **VERIFY** — Check the layout changed after actions.
+6. **EXTRACT** — Use `ddm --text`, `intel --extract`, or `js` based on page type.
+
+### Token Comparison
+
+| Method | Tokens | Info |
+|--------|--------|------|
+| Screenshot (base64 PNG) | ~2,100 | Visual only, no selectors |
+| `ddm --llm-2pass` | ~500 | Layout + interactive elements |
+| `ddm --sparse` | ~100-400 | RLE-compressed, varies by complexity |
+| `intel --probe` | ~50 | Fingerprint + strategy ranking |
+
+## Global Options
+
+```
+--port PORT    Chrome remote debugging port (default: 9222, env: UNCHAINED_PORT)
+--tab TAB_ID   Target tab ID, alias, or 'auto' (default: auto)
+--json         Output raw JSON
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `UNCHAINED_PORT` | `9222` | Chrome remote debugging port |
+| `UNCHAINED_DATA_DIR` | `~/.unchained` | Base directory for Chrome profiles |
+| `UNCHAINED_CHROME_BIN` | — | Chrome/Chromium binary override |
+| `UNCHAINED_DDM_BIN` | — | DDM binary path override |
+| `UNCHAINED_INTEL_BIN` | — | Intel binary path override |
+| `ANTHROPIC_API_KEY` | — | Required for `agent` command |
+
+## Build Binaries
+
+DDM and Intel can be compiled to native binaries (protects proprietary algorithms):
+
+```bash
+pip install nuitka ordered-set
+python build_binaries.py --install
+```
+
+Binaries are installed to `~/.unchained/bin/`. The CLI automatically uses them when available, falling back to the Python engine otherwise.
+
+## Requirements
+
+- Python 3.10+
+- Google Chrome, Chromium, or Microsoft Edge

unchainedsky_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=70"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unchainedsky-cli"
+version = "0.1.0"
+description = "Browser automation CLI over local Chrome CDP"
+requires-python = ">=3.10"
+dependencies = [
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+agent = ["anthropic>=0.49"]
+
+[project.scripts]
+unchained = "unchained_cli.cli:main"
+unchained-ddm = "unchained_cli.ddm_engine:main"
+unchained-intel = "unchained_cli.intel_engine:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["unchained_cli*"]

unchainedsky_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unchainedsky_cli-0.1.0/tests/test_bin.py

@@ -0,0 +1,53 @@
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+BIN = ROOT / "bin" / "unchained"
+
+
+class LauncherTests(unittest.TestCase):
+    def test_launcher_smoke_with_supported_python(self):
+        env = os.environ.copy()
+        env["UNCHAINED_PYTHON"] = sys.executable
+
+        result = subprocess.run(
+            [str(BIN), "--help"],
+            cwd=ROOT,
+            env=env,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("Browser automation over local Chrome CDP.", result.stdout)
+
+    def test_launcher_rejects_unsupported_python(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            fake_python = Path(tmpdir) / "python-old"
+            fake_python.write_text("#!/bin/sh\nexit 1\n", encoding="utf-8")
+            fake_python.chmod(0o755)
+
+            env = os.environ.copy()
+            env["UNCHAINED_PYTHON"] = str(fake_python)
+
+            result = subprocess.run(
+                [str(BIN), "--help"],
+                cwd=ROOT,
+                env=env,
+                text=True,
+                capture_output=True,
+                check=False,
+            )
+
+        self.assertEqual(result.returncode, 1)
+        self.assertIn("requires Python 3.10+", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

unchainedsky_cli-0.1.0/tests/test_chrome.py

@@ -0,0 +1,123 @@
+import asyncio
+import json
+import unittest
+from unittest import mock
+
+from unchained_cli.chrome import CDPError, ChromeClient
+
+
+class FakeWebSocket:
+    def __init__(self, messages):
+        self.messages = asyncio.Queue()
+        for message in messages:
+            self.messages.put_nowait(json.dumps(message))
+        self.sent = []
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        return False
+
+    async def send(self, raw):
+        self.sent.append(json.loads(raw))
+
+    async def recv(self):
+        return await self.messages.get()
+
+
+class FakeWebsocketsModule:
+    def __init__(self, websocket):
+        self.websocket = websocket
+
+    def connect(self, ws_url, ping_timeout=None):
+        self.ws_url = ws_url
+        self.ping_timeout = ping_timeout
+        return self.websocket
+
+
+class ChromeClientTests(unittest.TestCase):
+    def test_resolve_tab_auto_returns_first_page_tab(self):
+        client = ChromeClient()
+        with mock.patch.object(
+            client,
+            "list_tabs",
+            return_value=[{"id": "tab-1"}, {"id": "tab-2"}],
+        ):
+            self.assertEqual(client.resolve_tab("auto"), "tab-1")
+
+    def test_js_eval_frame_uses_isolated_world_context(self):
+        client = ChromeClient()
+        with mock.patch.object(
+            client,
+            "list_frames",
+            return_value=[{"index": 0, "frameId": "frame-1", "url": "", "name": ""}],
+        ), mock.patch.object(
+            client,
+            "send",
+            side_effect=[
+                {"executionContextId": 77},
+                {"result": {"type": "number", "value": 5}},
+            ],
+        ) as send:
+            result = client.js_eval_frame("tab-1", "0", "2 + 3")
+
+        self.assertEqual(result, 5)
+        self.assertEqual(send.call_args_list[0].args[1], "Page.createIsolatedWorld")
+        self.assertEqual(send.call_args_list[1].args[1], "Runtime.evaluate")
+        self.assertEqual(send.call_args_list[1].args[2]["contextId"], 77)
+
+    def test_wait_ready_dom_strategy_polls_document_ready_state(self):
+        websocket = FakeWebSocket([
+            {"id": 1, "result": {"result": {"type": "string", "value": "complete"}}},
+        ])
+        client = ChromeClient()
+
+        async def run_test():
+            with mock.patch.object(
+                client,
+                "_require_websockets",
+                return_value=FakeWebsocketsModule(websocket),
+            ):
+                return await client._async_wait_ready("ws://example", "dom", timeout=0.1)
+
+        result = asyncio.run(run_test())
+
+        self.assertEqual(result, "ready")
+        self.assertEqual(websocket.sent[0]["method"], "Runtime.enable")
+        self.assertEqual(websocket.sent[1]["method"], "Runtime.evaluate")
+
+    def test_wait_ready_network_strategy_waits_for_request_completion(self):
+        websocket = FakeWebSocket([
+            {"method": "Network.requestWillBeSent", "params": {"requestId": "req-1"}},
+            {"method": "Network.loadingFinished", "params": {"requestId": "req-1"}},
+        ])
+        client = ChromeClient()
+
+        async def run_test():
+            with mock.patch("unchained_cli.chrome._NETWORK_IDLE_WINDOW", 0.0), mock.patch.object(
+                client,
+                "_require_websockets",
+                return_value=FakeWebsocketsModule(websocket),
+            ):
+                return await client._async_wait_ready("ws://example", "network", timeout=0.1)
+
+        result = asyncio.run(run_test())
+
+        self.assertEqual(result, "ready")
+        self.assertEqual(websocket.sent[0]["method"], "Runtime.enable")
+        self.assertEqual(websocket.sent[1]["method"], "Network.enable")
+
+    def test_wait_ready_timeout_raises_cdp_error(self):
+        client = ChromeClient()
+        with mock.patch.object(client, "_ws_url_for", return_value="ws://example"), mock.patch.object(
+            client,
+            "_async_wait_ready",
+            new=mock.AsyncMock(side_effect=asyncio.TimeoutError),
+        ):
+            with self.assertRaisesRegex(CDPError, "strategy=dom"):
+                client.wait_ready("tab-1", "dom", timeout=0.1)
+
+
+if __name__ == "__main__":
+    unittest.main()

unchainedsky_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,195 @@
+import io
+import json
+import subprocess
+import sys
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+from types import SimpleNamespace
+from unittest import mock
+
+from unchained_cli import cli
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class FakeClient:
+    def __init__(self) -> None:
+        self.cookies_args = None
+
+    def list_tabs(self):
+        return [{"id": "tab-1", "title": "Example", "url": "https://example.com"}]
+
+    def resolve_tab(self, tab_id):
+        return "tab-1"
+
+    def navigate(self, tab_id, url):
+        return {"frameId": "frame-1"}
+
+    def js_eval(self, tab_id, expression):
+        return "https://example.com/final"
+
+    def get_cookies(self, tab_id, urls):
+        self.cookies_args = (tab_id, urls)
+        return [{"name": "session", "value": "abc", "domain": ".example.com"}]
+
+
+class CliCommandTests(unittest.TestCase):
+    def test_cmd_launch_reports_existing_chrome_with_unknown_profile_dir(self):
+        args = SimpleNamespace(
+            port=9222,
+            profile="alt",
+            headless=False,
+            url="https://example.com",
+            timeout=15.0,
+            chrome_args=[],
+            use_profile=False,
+            stealth=False,
+            json=False,
+        )
+
+        stdout = io.StringIO()
+        with mock.patch.object(
+            cli._launch,
+            "launch_chrome",
+            return_value={
+                "already_running": True,
+                "host": "127.0.0.1",
+                "port": 9222,
+                "profile_dir": None,
+                "startup_url": "https://example.com",
+            },
+        ), redirect_stdout(stdout):
+            cli.cmd_launch(args)
+
+        text = stdout.getvalue()
+        self.assertIn("Chrome ready → http://127.0.0.1:9222 (already running)", text)
+        self.assertIn("Profile dir → unknown (attached to existing Chrome on this port)", text)
+        self.assertIn("Startup URL → https://example.com", text)
+
+    def test_cmd_launch_reports_started_chrome(self):
+        args = SimpleNamespace(
+            port=9222,
+            profile="default",
+            headless=False,
+            url="https://example.com",
+            timeout=15.0,
+            chrome_args=[],
+            use_profile=False,
+            stealth=False,
+            json=False,
+        )
+
+        stdout = io.StringIO()
+        with mock.patch.object(
+            cli._launch,
+            "launch_chrome",
+            return_value={
+                "already_running": False,
+                "host": "127.0.0.1",
+                "port": 9222,
+                "pid": 1234,
+                "profile_dir": "/tmp/profile",
+                "startup_url": "https://example.com",
+            },
+        ), redirect_stdout(stdout):
+            cli.cmd_launch(args)
+
+        text = stdout.getvalue()
+        self.assertIn("Chrome started → http://127.0.0.1:9222 (PID 1234)", text)
+        self.assertIn("Profile dir → /tmp/profile", text)
+        self.assertIn("Startup URL → https://example.com", text)
+
+    def test_cmd_launch_omits_pid_when_unavailable(self):
+        args = SimpleNamespace(
+            port=9222,
+            profile="default",
+            headless=False,
+            url="https://example.com",
+            timeout=15.0,
+            chrome_args=[],
+            use_profile=False,
+            stealth=False,
+            json=False,
+        )
+
+        stdout = io.StringIO()
+        with mock.patch.object(
+            cli._launch,
+            "launch_chrome",
+            return_value={
+                "already_running": False,
+                "host": "127.0.0.1",
+                "port": 9222,
+                "profile_dir": "/tmp/profile",
+                "startup_url": "https://example.com",
+            },
+        ), redirect_stdout(stdout):
+            cli.cmd_launch(args)
+
+        text = stdout.getvalue()
+        self.assertIn("Chrome started → http://127.0.0.1:9222", text)
+        self.assertNotIn("(PID", text)
+        self.assertIn("Profile dir → /tmp/profile", text)
+
+    def test_cmd_tabs_outputs_json(self):
+        client = FakeClient()
+        args = SimpleNamespace(json=True)
+
+        stdout = io.StringIO()
+        with redirect_stdout(stdout):
+            cli.cmd_tabs(client, args)
+
+        self.assertEqual(
+            json.loads(stdout.getvalue()),
+            [{"id": "tab-1", "title": "Example", "url": "https://example.com"}],
+        )
+
+    def test_cmd_navigate_reports_final_url(self):
+        client = FakeClient()
+        args = SimpleNamespace(tab="auto", url="https://example.com", json=False)
+
+        stdout = io.StringIO()
+        with redirect_stdout(stdout):
+            cli.cmd_navigate(client, args)
+
+        self.assertIn("Navigated → https://example.com/final", stdout.getvalue())
+
+    def test_cmd_cookies_get_passes_multiple_urls(self):
+        client = FakeClient()
+        args = SimpleNamespace(
+            tab="auto",
+            urls=["https://example.com", "https://api.example.com"],
+            json=False,
+        )
+
+        stdout = io.StringIO()
+        with redirect_stdout(stdout):
+            cli.cmd_cookies_get(client, args)
+
+        self.assertEqual(
+            client.cookies_args,
+            ("tab-1", ["https://example.com", "https://api.example.com"]),
+        )
+        self.assertIn("(1 cookies)", stdout.getvalue())
+
+
+class CliSmokeTests(unittest.TestCase):
+    def test_module_help_smoke(self):
+        result = subprocess.run(
+            [sys.executable, "-m", "unchained_cli", "--help"],
+            cwd=ROOT,
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertIn("Browser automation over local Chrome CDP.", result.stdout)
+        self.assertIn("launch", result.stdout)
+        self.assertIn("navigate", result.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()

unchainedsky_cli-0.1.0/tests/test_ddm.py

@@ -0,0 +1,32 @@
+import io
+import unittest
+from contextlib import redirect_stderr
+from unittest import mock
+
+from unchained_cli import ddm
+
+
+class DdmTests(unittest.TestCase):
+    def test_run_ddm_falls_back_to_engine_when_no_binary(self):
+        """When no binary is found, DDM falls back to the Python engine."""
+        with mock.patch.object(ddm, "_find_binary", return_value=None), \
+             mock.patch("unchained_cli.ddm_engine.run", side_effect=SystemExit(0)) as engine_run:
+            code = ddm.run_ddm(9222, "auto", ["--help"])
+
+        self.assertEqual(code, 0)
+
+    def test_run_ddm_invokes_binary(self):
+        completed = mock.Mock(returncode=0)
+        with mock.patch.object(ddm, "_find_binary", return_value="/tmp/ddm"), mock.patch.object(
+            ddm.subprocess,
+            "run",
+            return_value=completed,
+        ) as run:
+            code = ddm.run_ddm(9222, "tab-1", ["--text"])
+
+        self.assertEqual(code, 0)
+        run.assert_called_once_with(["/tmp/ddm", "--port", "9222", "--tab", "tab-1", "--text"])
+
+
+if __name__ == "__main__":
+    unittest.main()