agent-toolkit-cli 1.11.0__py3-none-win_amd64.whl

agent_toolkit/data/skills/tooling/playwright-cli/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: playwright-cli
+description: Drive a real browser from the terminal using the Playwright CLI (snapshot, click, fill, screenshots,
+  traces). Use when the task is CLI-first browser automation (data extraction, UI debugging, form fills,
+  multi-tab work). For Playwright **test specs**, use `e2e-runner` instead.
+origin:
+  type: first-party
+---
+# Playwright CLI
+
+Drive a real browser from the terminal using `playwright-cli`. The bundled
+wrapper script runs the CLI through `npx`, so a global install is not required.
+
+> Treat this skill as **CLI-first automation**. Do NOT pivot to
+> `@playwright/test` test files unless the user explicitly asks for them — for
+> Playwright tests use [`e2e-runner`](../../../agents/e2e-runner/AGENT.md).
+
+## When to use
+
+- Quick, one-off browser automation from the shell (snapshot → interact →
+  screenshot/trace).
+- Reproducing a UI bug step-by-step with persistent sessions.
+- Extracting data from a page that requires JS rendering.
+- Smoke-checking a deployment without authoring a test suite.
+
+## Prerequisites
+
+- `npx` on `PATH` (provided by Node.js / `volta` from `bootstrap`).
+- Optional but recommended: a global install for faster startup —
+  `npm install -g @playwright/cli@latest`.
+- Outbound HTTPS access to npm and to the target sites.
+
+`skills check playwright-cli` validates `npx` is present.
+
+## Wrapper script (set once per shell)
+
+```bash
+export PWCLI="$HOME/.local/share/agent-toolkit/skills/playwright-cli/scripts/playwright_cli.sh"
+alias pwcli="$PWCLI"
+pwcli --help
+```
+
+The wrapper uses `npx --yes --package @playwright/cli playwright-cli`, so even
+without a global install the first call will fetch the package and cache it.
+
+If `PLAYWRIGHT_CLI_SESSION` is set, the wrapper passes it as `--session`
+automatically — handy to keep separate browser contexts per project.
+
+## Quick start
+
+```bash
+pwcli open https://playwright.dev --headed
+pwcli snapshot
+pwcli click e15
+pwcli type "Playwright"
+pwcli press Enter
+pwcli screenshot
+```
+
+## Core workflow
+
+1. `open` the page.
+2. `snapshot` to get stable element refs (e.g. `e3`).
+3. Interact using refs from the **latest** snapshot.
+4. Re-snapshot after navigation or significant DOM changes.
+5. Capture artifacts (`screenshot`, `pdf`, `tracing-start`/`tracing-stop`)
+   when useful.
+
+Minimal loop:
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli click e3
+pwcli snapshot
+```
+
+## When to snapshot again
+
+After:
+
+- navigation
+- clicking elements that change the UI substantially
+- opening/closing modals or menus
+- tab switches
+
+Refs go stale silently. When a command fails due to a missing ref, snapshot
+again — do not bypass with `run-code`/`eval` unless explicitly justified.
+
+## Recommended patterns
+
+### Form fill and submit
+
+```bash
+pwcli open https://example.com/form
+pwcli snapshot
+pwcli fill e1 "user@example.com"
+pwcli fill e2 "password123"
+pwcli click e3
+pwcli snapshot
+```
+
+### Debug a UI flow with traces
+
+```bash
+pwcli open https://example.com --headed
+pwcli tracing-start
+# ...interactions...
+pwcli tracing-stop
+```
+
+### Multi-tab work
+
+```bash
+pwcli tab-new https://example.com
+pwcli tab-list
+pwcli tab-select 0
+pwcli snapshot
+```
+
+## Sessions
+
+```bash
+pwcli --session todo open https://demo.playwright.dev/todomvc
+pwcli --session todo snapshot
+```
+
+Or set the env var once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=todo
+pwcli open https://demo.playwright.dev/todomvc
+```
+
+## Boundaries
+
+- This skill is **read/interact** on real browsers. No test framework, no test
+  files. For test suites, hand off to `e2e-runner`.
+- When this skill captures artifacts inside a project, write them under
+  `output/playwright/` (or whatever the repo defines) — never introduce new
+  top-level artifact folders.
+- For sandboxed AI tools that block `npx`/network, ask the user to authorize
+  outbound network for this skill rather than disabling sandboxing globally.
+
+## References
+
+- [`references/cli.md`](references/cli.md) — CLI command reference.
+- [`references/workflows.md`](references/workflows.md) — practical workflows
+  and troubleshooting.
+
+## See also
+
+- [`e2e-runner`](../../../agents/e2e-runner/AGENT.md) — Playwright **test**
+  authoring & execution (different mental model than this skill).

agent_toolkit/data/skills/tooling/playwright-cli/references/cli.md

@@ -0,0 +1,116 @@
+# Playwright CLI Reference
+
+Use the wrapper script unless `playwright-cli` is already installed globally:
+
+```bash
+export PWCLI="$HOME/.local/share/agent-toolkit/skills/playwright-cli/scripts/playwright_cli.sh"
+"$PWCLI" --help
+```
+
+Optional convenience alias:
+
+```bash
+alias pwcli="$PWCLI"
+```
+
+The wrapper uses `npx --yes --package @playwright/cli playwright-cli`, so the
+first invocation will fetch the package on demand and cache it.
+
+## Core
+
+```bash
+pwcli open https://example.com
+pwcli close
+pwcli snapshot
+pwcli click e3
+pwcli dblclick e7
+pwcli type "search terms"
+pwcli press Enter
+pwcli fill e5 "user@example.com"
+pwcli drag e2 e8
+pwcli hover e4
+pwcli select e9 "option-value"
+pwcli upload ./document.pdf
+pwcli check e12
+pwcli uncheck e12
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e5
+pwcli dialog-accept
+pwcli dialog-accept "confirmation text"
+pwcli dialog-dismiss
+pwcli resize 1920 1080
+```
+
+## Navigation
+
+```bash
+pwcli go-back
+pwcli go-forward
+pwcli reload
+```
+
+## Keyboard
+
+```bash
+pwcli press Enter
+pwcli press ArrowDown
+pwcli keydown Shift
+pwcli keyup Shift
+```
+
+## Mouse
+
+```bash
+pwcli mousemove 150 300
+pwcli mousedown
+pwcli mousedown right
+pwcli mouseup
+pwcli mouseup right
+pwcli mousewheel 0 100
+```
+
+## Save as
+
+```bash
+pwcli screenshot
+pwcli screenshot e5
+pwcli pdf
+```
+
+## Tabs
+
+```bash
+pwcli tab-list
+pwcli tab-new
+pwcli tab-new https://example.com/page
+pwcli tab-close
+pwcli tab-close 2
+pwcli tab-select 0
+```
+
+## DevTools
+
+```bash
+pwcli console
+pwcli console warning
+pwcli network
+pwcli run-code "await page.waitForTimeout(1000)"
+pwcli tracing-start
+pwcli tracing-stop
+```
+
+## Sessions
+
+Use a named session to isolate work:
+
+```bash
+pwcli --session todo open https://demo.playwright.dev/todomvc
+pwcli --session todo snapshot
+```
+
+Or set an environment variable once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=todo
+pwcli open https://demo.playwright.dev/todomvc
+```

agent_toolkit/data/skills/tooling/playwright-cli/references/workflows.md

@@ -0,0 +1,98 @@
+# Playwright CLI Workflows
+
+Use the wrapper script and snapshot often.
+Assume `PWCLI` is set and `pwcli` is an alias for `"$PWCLI"`.
+When running inside a project, contain artifacts under `output/playwright/<label>/`.
+
+## Standard interaction loop
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli click e3
+pwcli snapshot
+```
+
+## Form submission
+
+```bash
+pwcli open https://example.com/form --headed
+pwcli snapshot
+pwcli fill e1 "user@example.com"
+pwcli fill e2 "password123"
+pwcli click e3
+pwcli snapshot
+pwcli screenshot
+```
+
+## Data extraction
+
+```bash
+pwcli open https://example.com
+pwcli snapshot
+pwcli eval "document.title"
+pwcli eval "el => el.textContent" e12
+```
+
+## Debugging and inspection
+
+Capture console messages and network activity after reproducing an issue:
+
+```bash
+pwcli console warning
+pwcli network
+```
+
+Record a trace around a suspicious flow:
+
+```bash
+pwcli tracing-start
+# reproduce the issue
+pwcli tracing-stop
+pwcli screenshot
+```
+
+## Sessions
+
+Use sessions to isolate work across projects:
+
+```bash
+pwcli --session marketing open https://example.com
+pwcli --session marketing snapshot
+pwcli --session checkout open https://example.com/checkout
+```
+
+Or set the session once:
+
+```bash
+export PLAYWRIGHT_CLI_SESSION=checkout
+pwcli open https://example.com/checkout
+```
+
+## Configuration file
+
+By default the CLI reads `playwright-cli.json` from the current directory. Use
+`--config` to point at a specific file.
+
+Minimal example:
+
+```json
+{
+  "browser": {
+    "launchOptions": {
+      "headless": false
+    },
+    "contextOptions": {
+      "viewport": { "width": 1280, "height": 720 }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+- If an element ref fails, run `pwcli snapshot` again and retry.
+- If the page looks wrong, re-open with `--headed` and resize the window.
+- If a flow depends on prior state, use a named `--session`.
+- If `npx` is blocked by your AI tool's sandbox, authorize outbound network
+  for this skill rather than disabling sandboxing globally.

agent_toolkit/data/skills/tooling/playwright-cli/scripts/executable_playwright_cli.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "Error: npx is required but not found on PATH." >&2
+  exit 1
+fi
+
+has_session_flag="false"
+for arg in "$@"; do
+  case "$arg" in
+    --session | --session=*)
+      has_session_flag="true"
+      break
+      ;;
+  esac
+done
+
+cmd=(npx --yes --package @playwright/cli playwright-cli)
+if [[ ${has_session_flag} != "true" && -n ${PLAYWRIGHT_CLI_SESSION:-} ]]; then
+  cmd+=(--session "${PLAYWRIGHT_CLI_SESSION}")
+fi
+cmd+=("$@")
+
+exec "${cmd[@]}"

agent_toolkit/data_cache.py

@@ -0,0 +1,79 @@
+"""GitHub Release data cache for lighter wheel installs."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.request
+from pathlib import Path
+
+from agent_toolkit import __version__
+
+
+def _xdg_cache_home() -> Path:
+    return Path(os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache")))
+
+
+def cache_dir() -> Path:
+    return _xdg_cache_home() / "agent-toolkit"
+
+
+CACHE_DIR = cache_dir()  # default at import; tests should patch cache_dir()
+CACHE_VERSION_FILE = cache_dir() / "cached_version.json"
+GITHUB_RELEASES_API = "https://api.github.com/repos/ulises-jeremias/agent-toolkit/releases/latest"
+
+
+def cached_version() -> str | None:
+    version_file = cache_dir() / "cached_version.json"
+    if not version_file.is_file():
+        return None
+    try:
+        data = json.loads(version_file.read_text())
+        return str(data.get("version", "")) or None
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def is_cache_current() -> bool:
+    cached = cached_version()
+    return cached is not None and cached == __version__
+
+
+def ensure_cached_data(*, offline: bool = False, force: bool = False) -> Path | None:
+    """Ensure toolkit data exists in XDG cache. Returns cache path or None."""
+    dest = cache_dir()
+    dest.mkdir(parents=True, exist_ok=True)
+
+    if not force and is_cache_current() and (dest / "profiles").is_dir():
+        return dest
+
+    if offline:
+        if (dest / "profiles").is_dir():
+            return dest
+        return None
+
+    try:
+        req = urllib.request.Request(
+            GITHUB_RELEASES_API,
+            headers={"User-Agent": "agent-toolkit-data-cache/1"},
+        )
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            release = json.loads(resp.read())
+        tag = str(release.get("tag_name", __version__)).lstrip("v")
+        tarball_url = release.get("tarball_url")
+        if not tarball_url:
+            return None
+        version_file = dest / "cached_version.json"
+        version_file.write_text(
+            json.dumps({"version": tag, "source": "github-release", "url": tarball_url}, indent=2)
+            + "\n"
+        )
+        return dest
+    except Exception:
+        return dest if (dest / "profiles").is_dir() else None
+
+
+def refresh_cache() -> bool:
+    """Force refresh cache metadata from GitHub Releases."""
+    result = ensure_cached_data(force=True)
+    return result is not None

agent_toolkit/data_sync.py

@@ -0,0 +1,144 @@
+"""Download and cache agent-toolkit capability data from GitHub Releases."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from agent_toolkit import __version__
+
+GITHUB_REPO = "ulises-jeremias/agent-toolkit"
+DATA_SUBDIRS = ("skills", "agents", "loops", "profiles", "mcp", "catalogs")
+VERSION_FILE = ".version"
+
+
+def data_cache_dir() -> Path:
+    """XDG data directory for downloaded capability trees."""
+    xdg = os.environ.get("XDG_DATA_HOME", "").strip()
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".local" / "share"
+    return base / "agent-toolkit" / "data"
+
+
+def is_valid_data_root(path: Path) -> bool:
+    return (
+        path.is_dir()
+        and (path / "profiles").is_dir()
+        and ((path / "skills").is_dir() or (path / "loops").is_dir())
+    )
+
+
+def cached_version() -> str | None:
+    vf = data_cache_dir() / VERSION_FILE
+    if vf.is_file():
+        return vf.read_text(encoding="utf-8").strip() or None
+    return None
+
+
+def _release_tag(version: str) -> str:
+    return version if version.startswith("v") else f"v{version}"
+
+
+def _fetch_latest_release_tag() -> str:
+    url = f"https://api.github.com/repos/{GITHUB_REPO}/releases/latest"
+    req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json"})
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+    tag = payload.get("tag_name", "")
+    if not tag:
+        raise RuntimeError("GitHub Releases API returned no tag_name")
+    return tag
+
+
+def _copy_data_tree(src_root: Path, dest: Path) -> None:
+    dest.mkdir(parents=True, exist_ok=True)
+    for name in DATA_SUBDIRS:
+        src = src_root / name
+        if not src.is_dir():
+            continue
+        dst = dest / name
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+
+
+def download_data(
+    version: str | None = None,
+    *,
+    force: bool = False,
+    quiet: bool = False,
+) -> Path:
+    """Download capability data from a GitHub Release source tarball into the cache."""
+    cache = data_cache_dir()
+    target_version = version or cached_version() or _release_tag(__version__)
+
+    if not force and is_valid_data_root(cache):
+        current = cached_version()
+        if current and current.lstrip("v") == target_version.lstrip("v"):
+            return cache
+
+    tag = _release_tag(target_version)
+    url = f"https://github.com/{GITHUB_REPO}/archive/refs/tags/{tag}.tar.gz"
+    if not quiet:
+        print(f"[agent-toolkit] Downloading capability data ({tag})…", flush=True)
+
+    with tempfile.TemporaryDirectory(prefix="agent-toolkit-data-") as tmp:
+        tarball = Path(tmp) / "source.tar.gz"
+        try:
+            urllib.request.urlretrieve(url, tarball)
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(
+                f"Failed to download {url} (HTTP {exc.code}). "
+                "Set AGENT_TOOLKIT_ROOT to a checkout or run with bundled wheel data."
+            ) from exc
+        except OSError as exc:
+            raise RuntimeError(
+                f"Failed to download {url} ({exc}). "
+                "Set AGENT_TOOLKIT_ROOT to a checkout or run with bundled wheel data."
+            ) from exc
+
+        extract_dir = Path(tmp) / "extract"
+        extract_dir.mkdir()
+        with tarfile.open(tarball, "r:gz") as tar:
+            tar.extractall(extract_dir, filter="data")
+
+        roots = [p for p in extract_dir.iterdir() if p.is_dir()]
+        if not roots:
+            raise RuntimeError(f"No top-level directory in release tarball for {tag}")
+        src_root = roots[0]
+        if not is_valid_data_root(src_root):
+            raise RuntimeError(f"Release {tag} tarball does not contain capability data")
+
+        if cache.exists():
+            shutil.rmtree(cache)
+        _copy_data_tree(src_root, cache)
+        (cache / VERSION_FILE).write_text(tag.lstrip("v"), encoding="utf-8")
+
+    if not quiet:
+        print(f"[agent-toolkit] Cached data at {cache}", flush=True)
+    return cache
+
+
+def ensure_data(
+    *,
+    offline: bool = False,
+    force: bool = False,
+    version: str | None = None,
+) -> Path | None:
+    """Return cached/downloaded data root, or None when offline and cache is missing."""
+    cache = data_cache_dir()
+    if is_valid_data_root(cache) and not force:
+        cv = cached_version()
+        pin = version or __version__
+        if cv is None or cv.lstrip("v") == pin.lstrip("v"):
+            return cache
+
+    if offline:
+        return cache if is_valid_data_root(cache) else None
+
+    return download_data(version, force=force)

agent_toolkit/installer/merge.py

@@ -0,0 +1,59 @@
+"""Non-destructive JSON config merge for profile installs."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def merge_json_objects(
+    base: dict[str, Any],
+    overlay: dict[str, Any],
+    *,
+    prefix: str = "",
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Merge overlay into base without overwriting existing keys.
+
+    Returns the merged dict and a list of ownership patches (JSON-pointer-like paths).
+    """
+    merged = dict(base)
+    patches: list[dict[str, Any]] = []
+
+    for key, value in overlay.items():
+        path = f"{prefix}/{key}" if prefix else f"/{key}"
+        if key not in merged:
+            merged[key] = value
+            patches.append({"op": "add", "path": path, "value": value})
+            continue
+        if isinstance(merged[key], dict) and isinstance(value, dict):
+            nested, nested_patches = merge_json_objects(merged[key], value, prefix=path)
+            if nested != merged[key]:
+                merged[key] = nested
+                patches.extend(nested_patches)
+
+    return merged, patches
+
+
+def merge_json_file(
+    src: Path,
+    dst: Path,
+    *,
+    force: bool = False,
+) -> tuple[dict[str, Any] | None, list[dict[str, Any]], str]:
+    """Merge src JSON into dst when dst exists; otherwise return src content.
+
+    Returns (result_dict, patches, ownership) where ownership is ``created`` or ``merged``.
+    """
+    overlay = json.loads(src.read_text(encoding="utf-8"))
+    if not dst.is_file() or force:
+        return overlay, [], "created"
+
+    base = json.loads(dst.read_text(encoding="utf-8"))
+    if not isinstance(base, dict) or not isinstance(overlay, dict):
+        return None, [], "skipped"
+
+    merged, patches = merge_json_objects(base, overlay)
+    if merged == base:
+        return merged, [], "unchanged"
+    return merged, patches, "merged"