trawl-devices-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 legostin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# trawl-devices-agent
+
+Local sidecar for the Trawl **devices** plugin: records browser actions into a
+declarative JS DSL and replays them with Playwright.
+
+## Run
+
+```sh
+npx trawl-devices-agent@latest --workspace=/path/to/repo --port=8787
+```
+
+It prints the port and the bearer token; paste the token into the plugin once.
+The token also lives in `~/.trawl-devices/agent.json` (mode 0600).
+
+Install a browser once: `npx playwright install chromium`.
+
+Flags: `--workspace` (default: cwd), `--port` (8787, next free port if taken),
+`--proxy-port` (8080, Trawl's proxy), `--keep-runs` (50).
+
+## Workspace layout
+
+```
+<workspace>/
+  devices.json     # device registry, commit it
+  scripts/*.js     # scenarios, commit them
+  runs/<runId>/    # report.json, trace.zip, *.png — gitignore this
+```
+
+## Writing scripts
+
+See `skills/writing-device-scripts/SKILL.md` — the same text the agent serves at
+`GET /guide` and that can be symlinked into `~/.claude/skills/`.
+
+## Security model
+
+The agent listens on `127.0.0.1` only and refuses any request that lacks the
+bearer token, carries an `Origin` header, or arrives with an unexpected `Host`
+header. `GET /health` answers without a token so the plugin can detect a running
+agent, and returns only the agent version in that case.
+
+**Scripts are not sandboxed against malice.** `node:vm` keeps `require`,
+`process` and `fetch` out of scope so accidents stay contained, but a script runs
+with your privileges. Run only scripts you wrote or reviewed — the same trust
+model as Trawl plugins.
+
+Secrets passed by the plugin are masked in reports, logs and API responses.
+Playwright traces cannot be masked, so a device that uses `secret()` should keep
+`trace` at `on-failure` (the default) rather than `always`.
+
+## API
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/health` | version, DSL version, known steps |
+| GET/POST | `/devices` | list / upsert devices |
+| POST/GET/DELETE | `/sessions` | start, list, stop browser sessions |
+| GET/POST | `/scripts…` | list, read, write, validate scripts |
+| POST/GET/DELETE | `/runs…` | start, poll, cancel runs |
+| POST/GET | `/record…` | start, inspect, stop a recording |
+| POST | `/control/snapshot`, `/control/do` | live browser control |
+| GET | `/guide` | the DSL reference |

package/dist/auth.js

@@ -0,0 +1,23 @@
+import { promises as fs } from "node:fs";
+import { randomBytes } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+export const configDir = () => path.join(os.homedir(), ".trawl-devices");
+/** Read the bearer token, creating a 0600 file with a fresh one if absent. */
+export async function loadOrCreateToken(dir = configDir()) {
+    const file = path.join(dir, "agent.json");
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        if (typeof parsed?.token === "string" && parsed.token.length >= 32)
+            return parsed.token;
+    }
+    catch {
+        // missing or corrupt — fall through and mint a new one
+    }
+    const token = randomBytes(24).toString("base64url"); // 32 chars
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    await fs.writeFile(file, JSON.stringify({ token }, null, 2) + "\n", { mode: 0o600 });
+    await fs.chmod(file, 0o600);
+    return token;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,CAAC,MAAM,SAAS,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,gBAAgB,CAAC,CAAC;AAEjF,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAc,SAAS,EAAE;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC3D,IAAI,OAAO,MAAM,EAAE,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IAC1F,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;IAChE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrF,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/codegen.js

@@ -0,0 +1,41 @@
+import { isRegExp, isRegexSpec } from "./targets.js";
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const quote = (s) => `'${s.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n")}'`;
+export function formatArg(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (typeof value === "string")
+        return quote(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (isRegExp(value))
+        return String(value);
+    if (isRegexSpec(value))
+        return `/${value.__regex.source}/${value.__regex.flags}`;
+    if (Array.isArray(value))
+        return `[${value.map(formatArg).join(", ")}]`;
+    if (typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .map(([k, v]) => `${IDENT.test(k) ? k : quote(k)}: ${formatArg(v)}`);
+        return entries.length ? `{ ${entries.join(", ")} }` : "{}";
+    }
+    return "null";
+}
+const SETUP = new Set(["device", "use"]);
+/** Steps → a runnable DSL script. Setup calls are grouped and separated by a blank line. */
+export function generate(steps, options = {}) {
+    const line = (s) => `${s.action}(${s.args.map(formatArg).join(", ")})`;
+    const setup = steps.filter((s) => SETUP.has(s.action)).map(line);
+    const body = steps.filter((s) => !SETUP.has(s.action)).map(line);
+    const chunks = [];
+    if (options.header)
+        chunks.push(`// ${options.header}`);
+    if (setup.length)
+        chunks.push(setup.join("\n"), "");
+    chunks.push(body.join("\n"));
+    return chunks.join("\n").replace(/\n+$/, "") + "\n";
+}
+//# sourceMappingURL=codegen.js.map

package/dist/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"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"}

package/dist/control.js

@@ -0,0 +1,106 @@
+import { AgentError } from "./types.js";
+import { toLocator } from "./targets.js";
+const REF_ATTR = "data-trawl-ref";
+/** Interactive/labelled nodes, each tagged with a stable ref for the next action. */
+export async function snapshot(page) {
+    return page.evaluate((refAttr) => {
+        const SELECTOR = "a[href],button,input,select,textarea,[role],[tabindex]:not([tabindex='-1']),h1,h2,h3,label";
+        const implicitRole = (el) => {
+            const explicit = el.getAttribute("role");
+            if (explicit)
+                return explicit;
+            const tag = el.tagName.toLowerCase();
+            if (tag === "button")
+                return "button";
+            if (tag === "a")
+                return "link";
+            if (tag === "select")
+                return "combobox";
+            if (tag === "textarea")
+                return "textbox";
+            if (tag === "label")
+                return "label";
+            if (/^h[1-6]$/.test(tag))
+                return "heading";
+            if (tag === "input") {
+                const type = (el.getAttribute("type") ?? "text").toLowerCase();
+                if (type === "checkbox")
+                    return "checkbox";
+                if (type === "radio")
+                    return "radio";
+                if (type === "submit" || type === "button")
+                    return "button";
+                return "textbox";
+            }
+            return tag;
+        };
+        let counter = 0;
+        const out = [];
+        for (const el of Array.from(document.querySelectorAll(SELECTOR))) {
+            const ref = `e${++counter}`;
+            el.setAttribute(refAttr, ref);
+            const input = el;
+            const labelled = input.labels?.[0]?.textContent?.trim();
+            const rect = el.getBoundingClientRect();
+            out.push({
+                ref,
+                role: implicitRole(el),
+                name: (el.getAttribute("aria-label") ?? labelled ?? el.textContent ?? "").trim().slice(0, 80),
+                ...(labelled ? { label: labelled } : {}),
+                tag: el.tagName.toLowerCase(),
+                ...(input.value !== undefined ? { value: String(input.value).slice(0, 80) } : {}),
+                visible: rect.width > 0 && rect.height > 0,
+            });
+        }
+        return out;
+    }, REF_ATTR);
+}
+/** Perform one action by ref or by declarative target, and report what changed. */
+export async function performAction(page, input) {
+    const consoleErrors = [];
+    const onConsole = (msg) => {
+        if (msg.type() === "error")
+            consoleErrors.push(msg.text());
+    };
+    page.on("console", onConsole);
+    try {
+        if (input.action === "goto") {
+            await page.goto(input.value ?? "about:blank");
+        }
+        else if (input.action !== "screenshot") {
+            const locator = input.ref ? page.locator(`[${REF_ATTR}="${input.ref}"]`) : toLocator(page, input.target ?? {});
+            if (input.ref && (await locator.count()) === 0) {
+                throw new AgentError("script", `unknown ref: ${input.ref}`);
+            }
+            switch (input.action) {
+                case "click":
+                    await locator.click({ timeout: 10_000 });
+                    break;
+                case "fill":
+                    await locator.fill(input.value ?? "", { timeout: 10_000 });
+                    break;
+                case "check":
+                    await locator.check({ timeout: 10_000 });
+                    break;
+                case "uncheck":
+                    await locator.uncheck({ timeout: 10_000 });
+                    break;
+                case "select":
+                    await locator.selectOption(input.value ?? "", { timeout: 10_000 });
+                    break;
+                case "hover":
+                    await locator.hover({ timeout: 10_000 });
+                    break;
+                case "press":
+                    await locator.press(input.value ?? "Enter", { timeout: 10_000 });
+                    break;
+            }
+        }
+        await page.waitForTimeout(150);
+        return { url: page.url(), title: await page.title(), consoleErrors };
+    }
+    finally {
+        page.off("console", onConsole);
+    }
+}
+//# sourceMappingURL=control.js.map

package/dist/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"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"}

package/dist/devices.js

@@ -0,0 +1,69 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { AgentError } from "./types.js";
+import { resolveInWorkspace } from "./workspace.js";
+export const DEVICE_DEFAULTS = {
+    type: "browser",
+    browser: "chromium",
+    headless: false,
+    viewport: { width: 1280, height: 800 },
+    proxy: { mode: "trawl" },
+    ignoreHTTPSErrors: true,
+    trace: "on-failure",
+    video: false,
+    capabilities: ["record", "run", "live", "traffic"],
+};
+const BROWSERS = ["chromium", "firefox", "webkit"];
+const TRACES = ["off", "on-failure", "always"];
+const PROXY_MODES = ["trawl", "none", "custom"];
+/** Fill defaults and reject malformed input. Throws AgentError("script"). */
+export function validateDevice(input) {
+    const raw = (input ?? {});
+    const fail = (msg) => {
+        throw new AgentError("script", `invalid device: ${msg}`);
+    };
+    if (typeof raw.id !== "string" || !/^[a-zA-Z0-9._-]+$/.test(raw.id))
+        fail("id must match [a-zA-Z0-9._-]+");
+    if (typeof raw.name !== "string" || !raw.name.trim())
+        fail("name is required");
+    const merged = { ...DEVICE_DEFAULTS, ...raw };
+    if (!BROWSERS.includes(merged.browser))
+        fail(`browser must be one of ${BROWSERS.join(", ")}`);
+    if (!TRACES.includes(merged.trace))
+        fail(`trace must be one of ${TRACES.join(", ")}`);
+    if (!PROXY_MODES.includes(merged.proxy?.mode))
+        fail(`proxy.mode must be one of ${PROXY_MODES.join(", ")}`);
+    if (merged.proxy.mode === "custom" && !merged.proxy.url)
+        fail("proxy.url is required when proxy.mode is custom");
+    merged.type = "browser";
+    return merged;
+}
+const registryPath = (root) => resolveInWorkspace(root, "devices.json");
+export async function loadDevices(root) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(registryPath(root), "utf8"));
+        return Array.isArray(parsed?.devices) ? parsed.devices.map(validateDevice) : [];
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+export async function saveDevice(root, patch) {
+    const device = validateDevice(patch);
+    const devices = await loadDevices(root);
+    const next = devices.filter((d) => d.id !== device.id).concat(device);
+    next.sort((a, b) => a.id.localeCompare(b.id));
+    const file = registryPath(root);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify({ devices: next }, null, 2) + "\n", "utf8");
+    return device;
+}
+export async function getDevice(root, id) {
+    const found = (await loadDevices(root)).find((d) => d.id === id);
+    if (!found)
+        throw new AgentError("device", `unknown device: ${id}`);
+    return found;
+}
+//# sourceMappingURL=devices.js.map

package/dist/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.js","sourceRoot":"","sources":["../src/devices.ts"],"names":[],"mappings":"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"}

package/dist/guide.js

@@ -0,0 +1,14 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolved relative to this module, so it works from src/ under vitest and from
+ * dist/ in the published package — `skills/` sits at the package root in both.
+ */
+const GUIDE_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "skills/writing-device-scripts/SKILL.md");
+/** The DSL reference, frontmatter stripped. Single source shared with the Claude Code skill. */
+export async function readGuide() {
+    const raw = await fs.readFile(GUIDE_PATH, "utf8");
+    return raw.replace(/^---\n[\s\S]*?\n---\n/, "").trim() + "\n";
+}
+//# sourceMappingURL=guide.js.map

package/dist/guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide.js","sourceRoot":"","sources":["../src/guide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAC1B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,IAAI,EACJ,wCAAwC,CACzC,CAAC;AAEF,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,SAAS;IAC7B,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,GAAG,CAAC,OAAO,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC;AAChE,CAAC"}

package/dist/index.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { createServer } from "./server.js";
+import { loadOrCreateToken } from "./auth.js";
+import { ensureWorkspace } from "./workspace.js";
+import { pruneRuns } from "./retention.js";
+import { AGENT_VERSION, DSL_VERSION } from "./version.js";
+import { STEP_NAMES } from "./steps.js";
+import { buildRoutes } from "./routes.js";
+const arg = (name, fallback) => {
+    const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : fallback;
+};
+const workspace = arg("workspace", process.cwd());
+const wanted = Number(arg("port", "8787"));
+const trawlProxyPort = Number(arg("proxy-port", "8080"));
+const listen = (server, candidate) => new Promise((resolve, reject) => {
+    server.once("error", (err) => (err.code === "EADDRINUSE" ? resolve(-1) : reject(err)));
+    server.listen(candidate, "127.0.0.1", () => resolve(candidate));
+});
+const token = await loadOrCreateToken();
+await ensureWorkspace(workspace);
+const pruned = await pruneRuns(workspace, Number(arg("keep-runs", "50")));
+if (pruned.length)
+    console.log(`pruned ${pruned.length} old run(s)`);
+let port = -1;
+for (let candidate = wanted; candidate < wanted + 20 && port < 0; candidate++) {
+    const server = createServer({
+        token,
+        getPort: () => port,
+        routes: buildRoutes({ workspace, trawlProxyPort }),
+        health: () => ({ dsl: DSL_VERSION, steps: [...STEP_NAMES], workspace }),
+    });
+    port = await listen(server, candidate);
+}
+if (port < 0)
+    throw new Error(`no free port in ${wanted}..${wanted + 20}`);
+console.log(`trawl-devices-agent ${AGENT_VERSION} listening on http://127.0.0.1:${port}`);
+console.log(`workspace: ${workspace}`);
+console.log(`token: ${token}`);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/interpolate.js

@@ -0,0 +1,20 @@
+import { AgentError } from "./types.js";
+const PATTERN = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+/** Replace {{VAR}} from `env`, deeply. Unknown variables are a script error. */
+export function interpolate(value, env) {
+    if (typeof value === "string") {
+        return value.replace(PATTERN, (_match, name) => {
+            const replacement = env[name];
+            if (replacement === undefined)
+                throw new AgentError("script", `unknown variable: ${name}`);
+            return replacement;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map((v) => interpolate(v, env));
+    if (value && typeof value === "object" && Object.prototype.toString.call(value) !== "[object RegExp]") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, env)]));
+    }
+    return value;
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../src/interpolate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,OAAO,GAAG,yCAAyC,CAAC;AAE1D,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,GAA2B;IACrE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;YACrD,MAAM,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,WAAW,KAAK,SAAS;gBAAE,MAAM,IAAI,UAAU,CAAC,QAAQ,EAAE,qBAAqB,IAAI,EAAE,CAAC,CAAC;YAC3F,OAAO,WAAW,CAAC;QACrB,CAAC,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACvE,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAAE,CAAC;QACtG,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/mask.js

@@ -0,0 +1,19 @@
+/** Replaces every secret value with *** in any string reachable from `value`. */
+export function makeMasker(secrets) {
+    const values = Object.values(secrets)
+        .filter((v) => typeof v === "string" && v.length >= 4)
+        .sort((a, b) => b.length - a.length);
+    const maskString = (input) => values.reduce((acc, secret) => acc.split(secret).join("***"), input);
+    const walk = (value) => {
+        if (typeof value === "string")
+            return maskString(value);
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value && typeof value === "object" && Object.prototype.toString.call(value) !== "[object RegExp]") {
+            return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, walk(v)]));
+        }
+        return value;
+    };
+    return values.length ? walk : (value) => value;
+}
+//# sourceMappingURL=mask.js.map

package/dist/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../src/mask.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,OAA+B;IACxD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;SACrD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAU,EAAE,CAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IAEvE,MAAM,IAAI,GAAG,CAAC,KAAc,EAAW,EAAE;QACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;QACxD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,EAAE,CAAC;YACtG,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5G,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,CAAC;AAC1D,CAAC"}

package/dist/recorder.js

@@ -0,0 +1,99 @@
+import { randomBytes } from "node:crypto";
+import { AgentError } from "./types.js";
+import { toLocator } from "./targets.js";
+import { generate } from "./codegen.js";
+import { writeScript } from "./workspace.js";
+import { RECORDER_SOURCE } from "./recorderInject.js";
+const MARK = "data-trawl-rec-el";
+export class RecorderStore {
+    deps;
+    recordings = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get(id) {
+        const found = this.recordings.get(id);
+        if (!found)
+            throw new AgentError("agent", `unknown recording: ${id}`);
+        return found;
+    }
+    async start(sessionId, url) {
+        const session = this.deps.sessions.get(sessionId);
+        const recording = {
+            id: `rec_${randomBytes(4).toString("hex")}`,
+            sessionId,
+            steps: [],
+            warnings: [],
+            startedAt: Date.now(),
+        };
+        await session.context.exposeBinding("__trawlRec", async ({ page }, raw) => {
+            try {
+                const target = await this.pickTarget(page, raw.candidates, recording);
+                recording.steps.push({
+                    index: recording.steps.length,
+                    action: raw.action,
+                    args: [target, ...raw.args],
+                });
+            }
+            catch (err) {
+                recording.warnings.push(`dropped ${raw.action}: ${err.message}`);
+            }
+        });
+        await session.context.addInitScript(RECORDER_SOURCE);
+        this.deps.sessions.setState(sessionId, "recording");
+        if (url)
+            await session.page.goto(url);
+        else
+            await session.page.reload();
+        this.recordings.set(recording.id, recording);
+        return recording;
+    }
+    /**
+     * Playwright's own locator engine is the arbiter: the first candidate that
+     * resolves to exactly one element, and to *the* marked element, wins.
+     */
+    async pickTarget(page, candidates, recording) {
+        for (const candidate of candidates) {
+            try {
+                const locator = toLocator(page, candidate);
+                if ((await locator.count()) !== 1)
+                    continue;
+                const handle = (await locator.elementHandle({ timeout: 1000 }));
+                if (!handle)
+                    continue;
+                const isMarked = await handle.evaluate((el, mark) => el.hasAttribute(mark), MARK);
+                await handle.dispose();
+                if (isMarked)
+                    return candidate;
+            }
+            catch {
+                // try the next candidate
+            }
+        }
+        const fallback = candidates.at(-1);
+        if (!fallback)
+            throw new AgentError("script", "no candidate target");
+        recording.warnings.push(`no verified target; fell back to ${JSON.stringify(fallback)}`);
+        return fallback;
+    }
+    async stop(id, options) {
+        const recording = this.get(id);
+        const session = this.deps.sessions.get(recording.sessionId);
+        await session.page
+            .evaluate(() => window.__trawlRecorderControl?.("flush"))
+            .catch(() => { });
+        await session.page.waitForTimeout(150);
+        this.recordings.delete(id);
+        this.deps.sessions.setState(recording.sessionId, "idle");
+        const code = generate(recording.steps, { header: "recorded by trawl-devices-agent" });
+        if (options.saveAs)
+            await writeScript(this.deps.workspace, options.saveAs, code);
+        return {
+            steps: recording.steps,
+            code,
+            warnings: recording.warnings,
+            ...(options.saveAs ? { scriptPath: options.saveAs } : {}),
+        };
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"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"}