getclaros 0.1.1 → 0.3.0

package/dist/hooks.js

@@ -0,0 +1,348 @@
+// Coding-agent hooks: `getclaros hook <agent>` runs once per tool call, reads the agent's hook payload on stdin, maps a
+// shell command or a file edit to a Claros action, asks POST /v1/check and answers in the agent's own protocol.
+// MCP tool calls are left to the MCP guard (cli.ts), so nothing is checked twice.
+// Protocols (official docs, read 2026-10-24):
+// - Claude Code  https://code.claude.com/docs/en/hooks  settings.json {hooks: {PreToolUse: [{matcher, hooks: [{type:
+//     "command", command, timeout}]}]}}; stdin {cwd, tool_name, tool_input}; stdout hookSpecificOutput {permissionDecision
+//     allow|deny|ask, permissionDecisionReason (deny: to Claude, ask: to the user), additionalContext}, systemMessage.
+// - Codex  https://developers.openai.com/codex/hooks  hooks.json, same shape; shell = Bash, edits = apply_patch (the
+//     patch in tool_input.command). "ask" is not supported on PreToolUse (the call would run): ask blocks instead.
+//     Hooks run only after the user trusts them in /hooks; project hooks only in a trusted project.
+// - Cursor  https://cursor.com/docs/hooks  hooks.json {version: 1, hooks: {beforeShellExecution: [{command}],
+//     preToolUse: [{command, matcher}]}}; stdout {permission allow|deny|ask, user_message, agent_message}. There is no
+//     before-edit event: preToolUse on Write/Delete gates edits; its "ask" isn't enforced yet, so ask blocks there.
+// Kept light: node builtins, config.js and verdict.js at run time; jsonc-parser only when installing.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig, relocate, resolve, saveConfig } from "./config.js";
+import { nudgesOf, nudgeText, stopText } from "./verdict.js";
+export const AGENTS = ["claude-code", "codex", "cursor"];
+const MAX = 20_000; // ponytail: a huge write is checked on its first 20k chars; send a summary if rules need the rest
+const cut = (s) => { const t = String(s ?? ""); return t.length > MAX ? t.slice(0, MAX) + "\n…(truncated)" : t; };
+/** The project root: the agent's own variable, else the nearest git root above cwd, else cwd. */
+export function rootOf(p, cwd, env = process.env) {
+    const set = env.CLAUDE_PROJECT_DIR || env.CURSOR_PROJECT_DIR || p.workspace_roots?.[0];
+    if (set)
+        return set;
+    for (let d = cwd;; d = dirname(d)) {
+        if (existsSync(join(d, ".git")))
+            return d;
+        if (dirname(d) === d)
+            return cwd;
+    }
+}
+const rel = (f, root) => {
+    const r = isAbsolute(f) ? relative(root, f) : f;
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r.split(sep).join("/") : f;
+};
+const diffOf = (edits) => edits.map((e) => [...String(e.old_string ?? "").split("\n").map((l) => `-${l}`), ...String(e.new_string ?? "").split("\n").map((l) => `+${l}`)].join("\n"))
+    .join("\n");
+/** Files an apply_patch envelope touches (*** Add / Update / Delete File: …, *** Move to: …). */
+export const patchFiles = (patch) => [...patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm)].map((m) => m[1].trim());
+/** A hook payload → the action Claros checks, or null (not a shell command or an edit: let it run unchecked). */
+export function actionOf(agent, p, env = process.env) {
+    const cwd = String(p.cwd ?? p.tool_input?.working_directory ?? process.cwd()), root = rootOf(p, cwd, env);
+    const base = { project: basename(root), cwd: cwd === root ? "." : rel(cwd, root) };
+    const t = p.tool_name, i = p.tool_input ?? {};
+    const shell = (command) => ({ tool: "shell", state: { command: cut(command), ...base }, arguments: { command } });
+    const file = (tool, f, more) => ({ tool, state: { file_path: rel(f, root), ...more, project: base.project }, arguments: i });
+    if (agent === "cursor") {
+        if (p.hook_event_name === "beforeShellExecution")
+            return shell(String(p.command ?? ""));
+        if (t === "Shell")
+            return shell(String(i.command ?? ""));
+        // ponytail: Cursor documents no tool_input for Write / Delete; these are the field names its other events use
+        if (t === "Write") {
+            const f = String(i.file_path ?? i.path ?? "");
+            return file("write_file", f, i.edits ? { diff: cut(diffOf(i.edits)) } : { content: cut(i.content ?? i.contents ?? "") });
+        }
+        if (t === "Delete")
+            return file("delete_file", String(i.file_path ?? i.path ?? ""), {});
+        return null;
+    }
+    if (t === "Bash" || t === "PowerShell")
+        return shell(String(i.command ?? ""));
+    if (agent === "codex") {
+        if (t !== "apply_patch")
+            return null;
+        const patch = String(i.command ?? i.patch ?? ""), files = patchFiles(patch);
+        return file("edit_file", files[0] ?? "", { diff: cut(patch), ...(files.length > 1 ? { files: files.map((f) => rel(f, root)).join(", ") } : {}) });
+    }
+    if (t === "Write")
+        return file("write_file", String(i.file_path ?? ""), { content: cut(i.content) });
+    if (t === "Edit")
+        return file("edit_file", String(i.file_path ?? ""), { diff: cut(diffOf([i])) });
+    if (t === "MultiEdit")
+        return file("edit_file", String(i.file_path ?? ""), { diff: cut(diffOf(i.edits ?? [])) });
+    if (t === "NotebookEdit")
+        return file("edit_file", String(i.notebook_path ?? ""), { content: cut(i.new_source) });
+    return null;
+}
+const who = (r) => {
+    const v = (r.violations ?? []).find((x) => x.action === "ask" || x.action === "stop") ?? {};
+    return v.who_to_ask || v.owner || v.expert || "the rule's owner";
+};
+const firstRule = (r) => (r.violations ?? []).find((x) => x.action === "ask" || x.action === "stop")?.rule ?? "a team rule";
+/** A /v1/check answer (or why the check failed) → the agent's hook output. `cursorPre`: Cursor's preToolUse (no ask). */
+export function outputOf(agent, r, err, o = {}) {
+    const what = o.tool ?? "this action";
+    let kind, text = "", short = "";
+    if (err) {
+        if (o.failClosed) {
+            kind = "stop";
+            text = `Claros couldn't check this action (${err}), so it was not run. Ask a person to confirm it is allowed before trying again.`;
+            short = `Claros couldn't check ${what} (${err}); blocked (fail-closed).`;
+        }
+        else {
+            kind = "warn";
+            short = `Claros couldn't check ${what} (${err}); it ran unchecked. Run: npx getclaros doctor`;
+        }
+    }
+    else if (r.allowed) {
+        kind = nudgesOf(r).length ? "nudge" : "silent";
+        text = kind === "nudge" ? nudgeText(r) : "";
+    }
+    else {
+        kind = r.result === "ask" ? "ask" : "stop";
+        text = stopText(r) + (kind === "ask" && r.check_id && !r.question ? `\nCheck: ${r.check_id} (give it to ${who(r)} with the question)` : "");
+        short = kind === "ask" ? `Claros: ask ${who(r)} before ${what}: ${firstRule(r)}${r.check_id ? ` (check ${r.check_id})` : ""}`
+            : `Claros stopped ${what}: ${firstRule(r)}`;
+    }
+    const json = (x) => ({ stdout: JSON.stringify(x), stderr: "", code: 0 });
+    if (agent === "cursor") {
+        const noAsk = o.event === "preToolUse"; // Cursor: ask accepted but not enforced on preToolUse
+        if (kind === "silent")
+            return json({ permission: "allow" });
+        if (kind === "warn")
+            return json({ permission: "allow", user_message: short });
+        if (kind === "nudge")
+            return json({ permission: "allow", agent_message: text });
+        if (kind === "ask" && !noAsk)
+            return json({ permission: "ask", user_message: short, agent_message: text });
+        return json({ permission: "deny", user_message: short, agent_message: text });
+    }
+    const hso = (x) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", ...x } });
+    if (kind === "silent")
+        return { stdout: "", stderr: "", code: 0 };
+    if (kind === "warn")
+        return json({ systemMessage: short });
+    if (kind === "nudge")
+        return json(hso({ additionalContext: text.slice(0, 10_000) }));
+    if (kind === "ask" && agent === "claude-code") { // native ask: the person at the keyboard decides, with the reason
+        return json({ ...hso({ permissionDecision: "ask", permissionDecisionReason: short, additionalContext: text.slice(0, 10_000) }) });
+    }
+    return json({ ...hso({ permissionDecision: "deny", permissionDecisionReason: text }), systemMessage: short });
+}
+/** The key: flag → CLAROS_KEY → saved config → the project's .env. */
+function keyFor(flag, root) {
+    if (flag || process.env.CLAROS_KEY)
+        return (flag || process.env.CLAROS_KEY);
+    const saved = loadConfig().key;
+    if (saved)
+        return saved;
+    try {
+        return /^(?:export\s+)?CLAROS_KEY=["']?([^"'\r\n]*)/m.exec(readFileSync(join(root, ".env"), "utf8"))?.[1].trim() ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+async function check(at, a, actor, timeout) {
+    const go = async () => {
+        const res = await fetch(at.url + "/v1/check", { method: "POST", signal: AbortSignal.timeout(timeout),
+            headers: { "content-type": "application/json", ...(at.key ? { authorization: `Bearer ${at.key}` } : {}) },
+            body: JSON.stringify({ tool: a.tool, action: a.tool, actor, state: a.state, arguments: a.arguments }) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return res.json();
+    };
+    try {
+        return await go();
+    }
+    catch (e) {
+        if (e.name === "TimeoutError" || !(await relocate(at)))
+            throw e;
+        return go(); // the server moved: the saved address is updated for the next call
+    }
+}
+/** `getclaros hook <agent> [--fail-closed] [--timeout ms] [--url …] [--web …] [--key …]` → exit code. */
+export async function main(argv) {
+    let v, agent;
+    try {
+        const p = parseArgs({ args: argv, allowPositionals: true, options: { "fail-closed": { type: "boolean" },
+                timeout: { type: "string" }, url: { type: "string" }, web: { type: "string" }, key: { type: "string" } } });
+        v = p.values;
+        agent = p.positionals[0];
+        if (!AGENTS.includes(agent))
+            throw new Error(`usage: getclaros hook <${AGENTS.join("|")}> [--fail-closed] [--timeout ms]`);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return 2;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(readFileSync(0, "utf8"));
+    }
+    catch {
+        payload = null;
+    }
+    const emit = (o) => {
+        if (o.stdout)
+            process.stdout.write(o.stdout + "\n");
+        if (o.stderr)
+            process.stderr.write(o.stderr + "\n");
+        return o.code;
+    };
+    // Cursor also runs Claude Code's hooks (.claude/settings.json); its own hooks.json entry checks those calls
+    if (agent !== "cursor" && payload?.cursor_version)
+        return 0;
+    const a = payload && actionOf(agent, payload);
+    if (!payload)
+        return emit(outputOf(agent, null, "unreadable hook payload", { failClosed: v["fail-closed"] }));
+    if (!a)
+        return emit(outputOf(agent, { allowed: true }, null, { event: payload.hook_event_name }));
+    const o = { failClosed: !!v["fail-closed"], tool: a.tool === "shell" ? `\`${String(a.state.command).slice(0, 80)}\``
+            : `${a.tool} ${a.state.file_path}`, event: payload.hook_event_name };
+    let r = null, err = null;
+    try {
+        const root = rootOf(payload, String(payload.cwd ?? process.cwd()));
+        const at = await resolve({ url: v.url, web: v.web, key: keyFor(v.key, root) });
+        const s = loadConfig();
+        if (at.source === "discovered" && !s.url)
+            saveConfig({ ...s, url: at.url, web: at.web }); // cache discovery
+        if (!at.key)
+            throw new Error("no Claros key: run npx getclaros init");
+        r = await check(at, a, agent, Number(v.timeout ?? 5000));
+        if (r?.need?.length)
+            throw new Error("the check needs records from an app the hook can't read");
+    }
+    catch (e) {
+        err = e.name === "TimeoutError" ? `timed out after ${v.timeout ?? 5000}ms` : e.message;
+    }
+    return emit(outputOf(agent, r, err, o));
+}
+const isOurs = (cmd) => /(getclaros|[\\/]dist[\\/]cli\.js)\s+hook\s/.test(String(cmd ?? "") + " ");
+/** Where each agent keeps its hooks, project and user scope. */
+export function hookFiles(project) {
+    const h = homedir(), codex = process.env.CODEX_HOME || join(h, ".codex");
+    return [
+        { agent: "claude-code", client: "Claude Code", path: join(project, ".claude", "settings.json"), user: false },
+        { agent: "claude-code", client: "Claude Code", path: join(h, ".claude", "settings.json"), user: true },
+        { agent: "codex", client: "Codex", path: join(project, ".codex", "hooks.json"), user: false },
+        { agent: "codex", client: "Codex", path: join(codex, "hooks.json"), user: true },
+        { agent: "cursor", client: "Cursor", path: join(project, ".cursor", "hooks.json"), user: false },
+        { agent: "cursor", client: "Cursor", path: join(h, ".cursor", "hooks.json"), user: true },
+    ].filter((f, i, all) => all.findIndex((x) => x.path === f.path) === i);
+}
+/** Agents installed on this machine (their home directory exists) or configured in this project. */
+export function hookAgents(project) {
+    const h = homedir(), codex = process.env.CODEX_HOME || join(h, ".codex");
+    const dirs = { "claude-code": [join(h, ".claude"), join(project, ".claude")],
+        codex: [codex, join(project, ".codex")], cursor: [join(h, ".cursor"), join(project, ".cursor")] };
+    return AGENTS.filter((a) => dirs[a].some((d) => existsSync(d)));
+}
+/** [event, entry] pairs init adds for an agent. */
+export function entriesFor(agent, command) {
+    if (agent === "claude-code")
+        return [["PreToolUse", { matcher: "Bash|PowerShell|Edit|Write|NotebookEdit",
+                    hooks: [{ type: "command", command, timeout: 30 }] }]];
+    if (agent === "codex")
+        return [["PreToolUse", { matcher: "^Bash$|^apply_patch$",
+                    hooks: [{ type: "command", command, timeout: 30, statusMessage: "Checking with Claros" }] }]];
+    return [["beforeShellExecution", { command, timeout: 30 }], ["preToolUse", { command, matcher: "Write|Delete", timeout: 30 }]];
+}
+const entryOurs = (e) => isOurs(e?.command) || (Array.isArray(e?.hooks) && e.hooks.some((h) => isOurs(h?.command)));
+async function jsonc() {
+    const j = await import("jsonc-parser");
+    const fmt = (text) => {
+        const ind = text.match(/^([ \t]+)\S/m)?.[1] ?? "  ";
+        return { insertSpaces: !ind.startsWith("\t"), tabSize: ind.startsWith("\t") ? 1 : ind.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+    };
+    const set = (t, path, value) => j.applyEdits(t, j.modify(t, path, value, { formattingOptions: fmt(t) }));
+    const items = (t, path) => j.findNodeAtLocation(j.parseTree(t), path)?.children ?? [];
+    const cut = (t, a, b, r = "") => t.slice(0, a) + r + t.slice(b);
+    // by hand, like clients.ts addClaros / removeEntry: jsonc's modify would reformat the neighbouring entries
+    /** value appended to the array at path, or as `key` to the object at path */
+    const put = (t, path, value, key) => {
+        const last = items(t, path).at(-1);
+        if (!last)
+            return set(t, key === undefined ? path : [...path, key], key === undefined ? [value] : value);
+        const at = last.offset + last.length, indent = /^[ \t]*/.exec(t.slice(t.lastIndexOf("\n", last.offset) + 1))[0];
+        return cut(t, at, at, `,${fmt(t).eol}${indent}${key === undefined ? "" : `${JSON.stringify(key)}: `}${JSON.stringify(value)}`);
+    };
+    /** the k-th element (array) or property (object) at path out, with its comma */
+    const drop = (t, path, k) => {
+        const xs = items(t, path), p = xs[k];
+        if (k > 0)
+            return cut(t, xs[k - 1].offset + xs[k - 1].length, p.offset + p.length);
+        if (xs.length > 1)
+            return cut(t, p.offset, xs[1].offset);
+        return set(t, [...path, p.type === "property" ? p.children[0].value : k], undefined);
+    };
+    const read = (t) => {
+        const errors = [], doc = j.parse(t, errors, { allowTrailingComma: true });
+        if (errors.length || (doc !== undefined && (typeof doc !== "object" || Array.isArray(doc))))
+            throw new Error("not valid JSON");
+        return doc ?? {};
+    };
+    return { set, read, put, drop };
+}
+/** The file's text with our hooks in it (added once; a changed launcher is updated in place). Throws on bad JSON. */
+export async function addHooks(text, agent, command) {
+    const { set, read, put } = await jsonc();
+    let t = text.trim() ? text : "{}\n";
+    if (agent === "cursor" && read(t).version === undefined)
+        t = put(t, [], 1, "version");
+    for (const [event, entry] of entriesFor(agent, command)) {
+        const hooks = read(t).hooks, list = hooks?.[event];
+        if (!hooks || typeof hooks !== "object") {
+            t = put(t, [], { [event]: [entry] }, "hooks");
+            continue;
+        }
+        if (!Array.isArray(list)) {
+            t = list === undefined ? put(t, ["hooks"], [entry], event) : set(t, ["hooks", event], [entry]);
+            continue;
+        }
+        const at = list.findIndex(entryOurs);
+        if (at < 0)
+            t = put(t, ["hooks", event], entry);
+        else if (JSON.stringify(list[at]) !== JSON.stringify(entry))
+            t = set(t, ["hooks", event, at], entry);
+    }
+    return t;
+}
+/** The inverse: our entries out; an event list or `hooks` object left empty by that goes too. */
+export async function removeHooks(text) {
+    const { read, drop } = await jsonc();
+    let t = text;
+    for (const [event, list] of Object.entries(read(t).hooks ?? {})) {
+        if (!Array.isArray(list) || !list.some(entryOurs))
+            continue;
+        if (list.every(entryOurs))
+            t = drop(t, ["hooks"], Object.keys(read(t).hooks).indexOf(event));
+        else
+            for (let i = list.length - 1; i >= 0; i--)
+                if (entryOurs(list[i]))
+                    t = drop(t, ["hooks", event], i);
+    }
+    const doc = read(t);
+    if (doc.hooks && typeof doc.hooks === "object" && !Object.keys(doc.hooks).length && text !== t) {
+        t = drop(t, [], Object.keys(doc).indexOf("hooks"));
+    }
+    return t;
+}
+/** Does this file hold our hooks? (false when absent or unreadable) */
+export async function hasHooks(path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        const { read } = await jsonc();
+        return Object.values(read(readFileSync(path, "utf8")).hooks ?? {}).some((l) => Array.isArray(l) && l.some(entryOurs));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/projects.js

@@ -0,0 +1,179 @@
+// Browser agents in a project directory: Playwright (package.json) and browser-use (pyproject / requirements / locks).
+// For each: the install command in the project's own package manager (never global), where the hook goes, whether
+// it's there, and where CLAROS_KEY can be written safely (an existing .env that git ignores and doesn't track).
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+const SKIP = new Set(["node_modules", "dist", "build", "out", "venv", "__pycache__", "site-packages", "coverage"]);
+/** source files under dir (not dot dirs, deps or builds), at most `cap` of them */
+function sources(dir, ext, cap = 2000) {
+    const out = [];
+    const walk = (d, depth) => {
+        let names;
+        try {
+            names = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (out.length >= cap)
+                return;
+            const p = join(d, n);
+            if (n.startsWith(".") || SKIP.has(n))
+                continue;
+            let s;
+            try {
+                s = statSync(p);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                if (depth < 8)
+                    walk(p, depth + 1);
+            }
+            else if (ext.test(n) && s.size < 512_000) {
+                out.push({ path: p, text: readFileSync(p, "utf8") });
+            }
+        }
+    };
+    walk(dir, 0);
+    return out;
+}
+const read = (p) => { try {
+    return readFileSync(p, "utf8");
+}
+catch {
+    return "";
+} };
+export function nodePm(dir, dev, pkg) {
+    const has = (f) => existsSync(join(dir, f));
+    if (has("pnpm-lock.yaml"))
+        return { name: "pnpm", argv: ["pnpm", "add", ...(dev ? ["-D"] : []), pkg] };
+    if (has("yarn.lock"))
+        return { name: "yarn", argv: ["yarn", "add", ...(dev ? ["-D"] : []), pkg] };
+    if (has("bun.lockb") || has("bun.lock"))
+        return { name: "bun", argv: ["bun", "add", ...(dev ? ["-d"] : []), pkg] };
+    return { name: "npm", argv: ["npm", "install", ...(dev ? ["-D"] : []), pkg] };
+}
+export function pyPm(dir, pkg) {
+    if (existsSync(join(dir, "uv.lock")))
+        return { name: "uv", argv: ["uv", "add", pkg] };
+    if (existsSync(join(dir, "poetry.lock")) || /^\[tool\.poetry\]/m.test(read(join(dir, "pyproject.toml")))) {
+        return { name: "poetry", argv: ["poetry", "add", pkg] };
+    }
+    // pip only into a virtualenv: the active one if it lives in this project, else ./.venv or ./venv
+    const venvs = [process.env.VIRTUAL_ENV && !relative(dir, process.env.VIRTUAL_ENV).startsWith("..") ? process.env.VIRTUAL_ENV : "",
+        join(dir, ".venv"), join(dir, "venv")].filter(Boolean);
+    for (const v of venvs) {
+        const py = [join(v, "bin", "python"), join(v, "Scripts", "python.exe")].find(existsSync);
+        if (py)
+            return { name: "pip", argv: [py, "-m", "pip", "install", pkg] };
+    }
+    return { name: "pip", argv: null, note: `no virtualenv in this project: activate yours, then pip install ${pkg} (init never installs globally)` };
+}
+const FIXTURE = (ext) => `// Written by \`npx getclaros init\`: every test's \`page\` goes through the Claros guard (consequential clicks and
+// submits are checked against your team's rules first). Import { test, expect } from here instead of
+// "@playwright/test". \`npx getclaros undo\` removes this file.
+import { existsSync, readFileSync } from "node:fs";
+import * as util from "node:util";
+import { test as base } from "@playwright/test";
+import { guard } from "getclaros-browser";
+
+// Playwright doesn't read .env: take CLAROS_KEY (and CLAROS_URL / CLAROS_WEB_URL) from it when the shell doesn't set them
+const env${ext === "ts" || ext === "mts" ? ": Record<string, string | undefined>" : ""} = existsSync(".env") && util.parseEnv ? util.parseEnv(readFileSync(".env", "utf8")) : {};
+for (const [k, v] of Object.entries(env)) if (k.startsWith("CLAROS_")) process.env[k] ??= v;
+
+export * from "@playwright/test";
+export const test = base.extend({
+  page: async ({ page }, use) => {
+    await guard(page);
+    await use(page);
+  },
+});
+`;
+export const fixtureText = (path) => FIXTURE(path.split(".").pop());
+// ponytail: only `dir` itself is a project (no monorepo workspace walk); run init in the package, or use --project
+export function detectBrowser(dir) {
+    const out = [];
+    let pkg; // eslint-disable-line @typescript-eslint/no-explicit-any
+    try {
+        pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+    }
+    catch { /* not a Node project */ }
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    if (deps["@playwright/test"] || deps.playwright) {
+        const runner = !!deps["@playwright/test"], pm = nodePm(dir, runner, "getclaros-browser");
+        const src = sources(dir, /\.(c|m)?[jt]sx?$/);
+        const p = { kind: "Playwright", dir, via: `${runner ? "@playwright/test" : "playwright"}, ${pm.name}`,
+            install: pm.argv, installed: !!deps["getclaros-browser"] || existsSync(join(dir, "node_modules", "getclaros-browser")),
+            more: 0, hooked: false };
+        if (runner) {
+            const config = ["ts", "mts", "js", "mjs", "cjs", "cts"].map((e) => join(dir, `playwright.config.${e}`)).find(existsSync);
+            const ext = config?.split(".").pop()?.replace(/^c/, "m") ?? "ts";
+            p.fixture = join(config ? dirname(config) : dir, `claros.fixture.${ext}`);
+            const specs = src.filter((f) => f.path !== config && f.path !== p.fixture && /from\s+["']@playwright\/test["']/.test(f.text));
+            p.hookFile = specs[0]?.path;
+            p.more = Math.max(0, specs.length - 1);
+            p.hooked = existsSync(p.fixture) && src.some((f) => f.path !== p.fixture && /claros\.fixture/.test(f.text));
+        }
+        else {
+            p.hookFile = src.find((f) => /["']playwright["']/.test(f.text))?.path;
+            p.hooked = src.some((f) => /["']getclaros-browser["']/.test(f.text));
+        }
+        out.push(p);
+    }
+    const manifests = ["pyproject.toml", "uv.lock", "poetry.lock",
+        ...(existsSync(dir) ? readdirSync(dir).filter((n) => /^requirements.*\.txt$/.test(n)) : [])].map((n) => read(join(dir, n))).join("\n");
+    if (/browser[-_]use/i.test(manifests)) {
+        const pm = pyPm(dir, "claros-browser"), src = sources(dir, /\.py$/);
+        const venvLib = join(dir, ".venv", "lib");
+        const inVenv = existsSync(venvLib) && readdirSync(venvLib).some((v) => existsSync(join(venvLib, v, "site-packages", "claros_browser")));
+        out.push({ kind: "browser-use", dir, via: `browser-use, ${pm.name}`, install: pm.argv, installNote: pm.note,
+            installed: /claros[-_]browser/i.test(manifests) || inVenv,
+            hookFile: (src.find((f) => /browser_use/.test(f.text) && /\bAgent\(/.test(f.text)) ?? src.find((f) => /browser_use/.test(f.text)))?.path,
+            more: 0, hooked: src.some((f) => /\bguard_tools\(/.test(f.text)) });
+    }
+    return out;
+}
+/** The import line a Playwright spec needs to use the fixture. */
+export function fixtureImport(p) {
+    const from = p.hookFile ? dirname(p.hookFile) : p.dir;
+    let rel = relative(from, p.fixture).split("\\").join("/");
+    if (/\.ts$/.test(rel))
+        rel = rel.slice(0, -3);
+    return `import { test, expect } from "${rel.startsWith(".") ? rel : "./" + rel}";`;
+}
+/** Where CLAROS_* may be written: an existing .env that git ignores and doesn't track. ok=false says why not. */
+export function envTarget(dir) {
+    const path = join(dir, ".env");
+    if (!existsSync(path))
+        return { path, ok: false, why: "no .env in this project" };
+    const git = (...a) => spawnSync("git", ["-C", dir, ...a], { stdio: "ignore" }).status;
+    if (git("ls-files", "--error-unmatch", "--", ".env") === 0)
+        return { path, ok: false, why: ".env is tracked by git" };
+    const ignored = git("check-ignore", "-q", "--", ".env");
+    if (ignored === 0)
+        return { path, ok: true };
+    if (ignored === 1)
+        return { path, ok: false, why: ".env isn't in .gitignore" };
+    // not a git repo (or no git): the .gitignore next to it decides
+    const lines = read(join(dir, ".gitignore")).split(/\r?\n/).map((l) => l.trim());
+    return lines.some((l) => /^\/?(\.env|\.env\*|\.env\.?\*|\*\.env|\.env\/?)$/.test(l))
+        ? { path, ok: true } : { path, ok: false, why: ".env isn't in .gitignore" };
+}
+/** The .env text with each var set (an existing line replaced in place, else appended). */
+export function setEnv(text, vars) {
+    for (const [k, v] of Object.entries(vars)) {
+        const line = `${k}=${v}`, re = new RegExp(`^(export\\s+)?${k}=.*$`, "m");
+        text = re.test(text) ? text.replace(re, line) : text + (text && !text.endsWith("\n") ? "\n" : "") + line + "\n";
+    }
+    return text;
+}
+/** The value of a var in a .env file ("" when absent). */
+export const envValue = (path, k) => {
+    const m = new RegExp(`^(?:export\\s+)?${k}=["']?([^"'\\r\\n]*)`, "m").exec(read(path));
+    return m ? m[1].trim() : "";
+};
+export const short = (p, dir) => relative(dir, p) || basename(p);