portable-agent-layer 0.45.2 → 0.46.0

package/assets/skills/playwright/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: playwright
+description: Capture a screenshot of a URL or local page and load it into context for a visual check. Use when asked to check visually, use playwright, screenshot a page, see or look at the design yourself, or verify a layout on desktop and mobile widths.
+argument-hint: <url> [--viewport WxH] [--full-page] [--selector <css>]
+---
+
+## Overview
+
+Take a screenshot of a running page and `Read` it into context so you can see the rendered result yourself — for design review, responsive checks (desktop + mobile widths), and confirming a layout fix actually looks right. This skill returns an **image**, not page data.
+
+## Engine selection (handled by the tool)
+
+The bundled tool picks the best available local engine automatically:
+
+1. **System `playwright-cli`** (Microsoft's stateful agent CLI) — used when it is on `PATH` and no exact viewport/full-page is requested (its `screenshot` command can't set those).
+2. **PAL-installed Playwright, launched via Node** — the cross-platform-safe path (Playwright's Chromium hangs under Bun on Windows). Honors `--viewport`, `--full-page`, and `--selector` precisely.
+
+If neither engine is usable, the tool prints `NO_PLAYWRIGHT_CLI` and exits non-zero — only then use the **Playwright MCP** (tier 3) in step 4.
+
+## Workflow
+
+1. Resolve the URL. If it's a local app, make sure the dev server is already running first.
+2. Run the tool (it prints the absolute PNG path as its last stdout line):
+
+   ```bash
+   node --experimental-strip-types ~/.pal/skills/playwright/tools/shot.ts <url> \
+     [--viewport 1440x900] [--full-page] [--selector "<css>"] [-o <out.png>]
+   ```
+
+3. `Read` the printed path so the screenshot enters your context. For a responsive check, run once per width (e.g. `--viewport 1440x900` then `--viewport 390x844`) and Read each.
+4. If the tool exits with `NO_PLAYWRIGHT_CLI`:
+   - If Playwright MCP tools (`mcp__playwright__browser_*`) are available: `browser_navigate` to the URL, `browser_take_screenshot` to a file, then `Read` it.
+   - Otherwise, tell the user Playwright isn't installed and suggest running `pal cli install`.
+
+## Output format
+
+The screenshot image (via `Read`) plus one line stating the URL and viewport captured. Add a review only if the caller asked you to assess the design.
+
+## When to use
+
+- "check visually", "use playwright", "screenshot this", "see/look at the design yourself", "does this look right", desktop/mobile layout verification.
+
+## Do NOT use
+
+- To scrape page text or DOM data — fetch the page directly instead; this returns an image.
+- To measure computed styles, element sizes, or horizontal overflow — use the Playwright MCP `browser_evaluate` for metrics; this skill does not return numbers.

package/assets/skills/playwright/tools/shot-lib.ts

@@ -0,0 +1,61 @@
+// Pure, side-effect-free helpers for the playwright skill tool.
+// Kept separate from shot.ts so they can be unit-tested without launching a browser.
+
+export type ShotOptions = {
+  url: string;
+  out: string;
+  viewport?: { width: number; height: number };
+  fullPage: boolean;
+  selector?: string;
+  waitMs?: number;
+};
+
+const USAGE =
+  "usage: shot.ts <url> [-o <file>] [--viewport WxH] [--full-page] [--selector <css>] [--wait <ms>]";
+
+export function parseArgs(argv: string[]): ShotOptions {
+  let url = "";
+  let out = "";
+  let viewport: ShotOptions["viewport"];
+  let fullPage = false;
+  let selector: string | undefined;
+  let waitMs: number | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-o" || a === "--out") out = argv[++i] ?? "";
+    else if (a === "--viewport") {
+      const m = /^(\d+)[x,](\d+)$/.exec(argv[++i] ?? "");
+      if (!m) throw new Error("--viewport expects WxH, e.g. 1440x900");
+      viewport = { width: Number(m[1]), height: Number(m[2]) };
+    } else if (a === "--full-page") fullPage = true;
+    else if (a === "--selector") selector = argv[++i];
+    else if (a === "--wait") {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n)) throw new Error("--wait expects a number of milliseconds");
+      waitMs = n;
+    } else if (!a.startsWith("-") && !url) url = a;
+    else throw new Error(`unknown argument: ${a}\n${USAGE}`);
+  }
+
+  if (!url) throw new Error(`a URL is required\n${USAGE}`);
+  return { url, out, viewport, fullPage, selector, waitMs };
+}
+
+export type Tier = "cli" | "node";
+
+/**
+ * Decide which local engine to use. `playwright-cli` (Microsoft's stateful agent CLI)
+ * is preferred when present, but its `screenshot` command cannot set a viewport or
+ * capture full-page — so any request that needs exact size/full-page falls to the
+ * Node-launched PAL Playwright, which honors them precisely.
+ */
+export function chooseTier(opts: {
+  cliAvailable: boolean;
+  viewport?: unknown;
+  fullPage?: boolean;
+}): Tier {
+  if (!opts.cliAvailable) return "node";
+  if (opts.viewport || opts.fullPage) return "node";
+  return "cli";
+}

package/assets/skills/playwright/tools/shot.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// playwright skill tool: capture a screenshot of a URL and print its absolute path.
+//
+// Engine selection (see chooseTier):
+//   Tier 1 — system `playwright-cli` binary (Microsoft's stateful agent CLI), when on
+//            PATH and no exact viewport/full-page is requested.
+//   Tier 2 — PAL-installed Playwright, launched via Node. (Playwright's chromium.launch
+//            hangs under Bun on Windows — the same Node exception create-pdf relies on.)
+// If neither engine works, prints NO_PLAYWRIGHT_CLI on stderr and exits non-zero so the
+// caller (SKILL.md) can fall back to the Playwright MCP.
+//
+// Run with Node:
+//   node --experimental-strip-types ~/.pal/skills/playwright/tools/shot.ts <url> [opts]
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { chooseTier, parseArgs, type ShotOptions } from "./shot-lib.ts";
+
+function playwrightCliAvailable(): boolean {
+  try {
+    return spawnSync("playwright-cli", ["--version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function runViaCli(opts: ShotOptions, out: string): boolean {
+  const open = spawnSync("playwright-cli", ["open", opts.url], { stdio: "inherit" });
+  if (open.status !== 0) return false;
+  const args = ["screenshot", `--filename=${out}`];
+  if (opts.selector) args.push(opts.selector);
+  const shot = spawnSync("playwright-cli", args, { stdio: "inherit" });
+  spawnSync("playwright-cli", ["close"], { stdio: "ignore" });
+  return shot.status === 0 && existsSync(out);
+}
+
+// "unavailable" = the engine itself can't run (package or Chromium missing) → MCP fallback.
+// "error" = the engine ran but the page/screenshot failed → a real error, not an MCP case.
+type NodeResult = "ok" | "unavailable" | "error";
+
+async function runViaNode(opts: ShotOptions, out: string): Promise<NodeResult> {
+  let chromium: typeof import("playwright").chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    return "unavailable"; // package not resolvable
+  }
+
+  let browser: Awaited<ReturnType<typeof chromium.launch>>;
+  try {
+    browser = await chromium.launch();
+  } catch (e) {
+    console.error(`chromium launch failed: ${(e as Error).message}`);
+    return "unavailable"; // browser not installed / can't launch
+  }
+
+  try {
+    const page = await browser.newPage(opts.viewport ? { viewport: opts.viewport } : {});
+    await page.goto(opts.url, { waitUntil: "networkidle" });
+    if (opts.waitMs) await page.waitForTimeout(opts.waitMs);
+    if (opts.selector) await page.locator(opts.selector).screenshot({ path: out });
+    else await page.screenshot({ path: out, fullPage: opts.fullPage });
+    return existsSync(out) ? "ok" : "error";
+  } catch (e) {
+    console.error(`screenshot failed: ${(e as Error).message}`);
+    return "error";
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main(): Promise<void> {
+  let opts: ShotOptions;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(2);
+  }
+
+  const out = opts.out ? resolve(opts.out) : join(tmpdir(), `pal-shot-${Date.now()}.png`);
+  const tier = chooseTier({
+    cliAvailable: playwrightCliAvailable(),
+    viewport: opts.viewport,
+    fullPage: opts.fullPage,
+  });
+
+  if (tier === "cli" && runViaCli(opts, out)) {
+    console.log(out);
+    return;
+  }
+
+  const result = await runViaNode(opts, out);
+  if (result === "ok") {
+    console.log(out);
+    return;
+  }
+  if (result === "unavailable") {
+    console.error("NO_PLAYWRIGHT_CLI");
+    process.exit(3); // no local engine → caller falls back to Playwright MCP
+  }
+  process.exit(1); // engine ran but the capture failed — a real error, not an MCP case
+}
+
+await main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.45.2",
+  "version": "0.46.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {