phyll 0.4.1

package/src/credentials.mjs

@@ -0,0 +1,40 @@
+// The Phyll key and server on this computer, in ~/.phyll/credentials.json. PHYLL_API_URL and
+// PHYLL_API_KEY win over the file, and PHYLL_HOME moves the folder.
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The address of Phyll's own server. --server or PHYLL_API_URL point the connector elsewhere.
+export const DEFAULT_SERVER = "https://agentphyll.com";
+
+export const phyllHome = (env = process.env) => env.PHYLL_HOME || join(homedir(), ".phyll");
+export const credentialsPath = (env = process.env) => join(phyllHome(env), "credentials.json");
+
+export function loadCredentials(env = process.env) {
+  let file = {};
+  try {
+    file = JSON.parse(readFileSync(credentialsPath(env), "utf8"));
+  } catch {
+    file = {};
+  }
+  return {
+    server: String(env.PHYLL_API_URL || file.server || DEFAULT_SERVER || "").replace(/\/+$/, "") || null,
+    key: env.PHYLL_API_KEY || file.key || null,
+  };
+}
+
+export function saveCredentials({ server, key }, env = process.env) {
+  mkdirSync(phyllHome(env), { recursive: true, mode: 0o700 });
+  const path = credentialsPath(env);
+  writeFileSync(path, JSON.stringify({ server, key }, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // Windows keeps its own permissions on the user folder.
+  }
+  return path;
+}
+
+export function clearCredentials(env = process.env) {
+  rmSync(credentialsPath(env), { force: true });
+}

package/src/engine.mjs

@@ -0,0 +1,40 @@
+// Calls to the Phyll engine. Every call answers { ok, status, json } and never throws, so the
+// agent always gets a message it can pass on.
+const LOCAL = /^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+
+export function engineClient({ server, key = null, version = "0", fetchImpl = globalThis.fetch }) {
+  const base = String(server ?? "").replace(/\/+$/, "");
+  async function call(method, path, body) {
+    if (!base) return { ok: false, status: 0, json: { message: "No Phyll server is set. Sign up with npx phyll signup you@example.com --server <address>." } };
+    if (key && !/^https:\/\//i.test(base) && !LOCAL.test(base)) {
+      return { ok: false, status: 0, json: { message: `Phyll sends your key only over https, and ${base} is not.` } };
+    }
+    let response;
+    try {
+      response = await fetchImpl(`${base}${path}`, {
+        method,
+        headers: {
+          ...(key ? { authorization: `Bearer ${key}` } : {}),
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+          "user-agent": `phyll/${version}`,
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+      });
+    } catch (error) {
+      return { ok: false, status: 0, json: { message: `Could not reach Phyll at ${base} (${error?.cause?.code ?? error?.message ?? error}).` } };
+    }
+    const json = await response.json().catch(() => ({}));
+    return { ok: response.ok, status: response.status, json: json ?? {} };
+  }
+  return {
+    base,
+    signup: (email, language) => call("POST", "/v1/signup", { email, language }),
+    me: () => call("GET", "/v1/me"),
+    startSession: (body) => call("POST", "/v1/sessions", body),
+    guide: (id, name, tells = []) =>
+      call("GET", `/v1/sessions/${encodeURIComponent(id)}/guides/${encodeURIComponent(name)}${tells.length ? `?tells=${encodeURIComponent(tells.join(","))}` : ""}`),
+    submitReport: (id, report) => call("POST", `/v1/sessions/${encodeURIComponent(id)}/report`, { report }),
+    checkout: () => call("POST", "/v1/billing/checkout"),
+    portal: () => call("POST", "/v1/billing/portal"),
+  };
+}

package/src/mcp.mjs

@@ -0,0 +1,145 @@
+// The connector as an MCP server on stdio, for Codex, Claude Code or any agent that speaks MCP.
+// Nothing here writes to stdout: that stream belongs to the protocol.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { VERSION } from "./paths.mjs";
+import { Connector } from "./review.mjs";
+
+const INSTRUCTIONS =
+  "Phyll reviews the UX of apps built with AI, the way a first-time user meets them, and keeps their design. When the person asks to review, audit or improve the UX, flows or onboarding of the app in this project, call start_review with the address where the app runs and follow the method it returns, step by step. The scan tool reads the source for AI tells and needs no account.";
+
+export function createServer(connector) {
+  const server = new McpServer({ name: "phyll", version: VERSION }, { instructions: INSTRUCTIONS });
+  const reply = (result) => {
+    if (result.image) {
+      return { content: [{ type: "image", data: result.image, mimeType: "image/png" }, { type: "text", text: result.text }] };
+    }
+    return { content: [{ type: "text", text: result.text }], ...(result.isError ? { isError: true } : {}) };
+  };
+  const safely = (fn) => async (args) => {
+    try {
+      return reply(await fn(args ?? {}));
+    } catch (error) {
+      return reply({ text: `That did not work: ${error?.message ?? error}`, isError: true });
+    }
+  };
+  const tool = (name, description, inputSchema, fn) => server.registerTool(name, { description, inputSchema }, safely(fn));
+  const browser = (fn) => async (args) => ({ text: await fn(await connector.browser(), args) });
+
+  tool(
+    "start_review",
+    "Start a Phyll review of a running app. Scans the project's source, creates the report folder and returns the method to follow. Uses one of the account's reviews.",
+    {
+      url: z.string().describe("Where the app runs, such as http://localhost:3000"),
+      language: z.string().optional().describe("Language of the report, such as en or pt-BR. Use the language the person writes in."),
+      user: z.string().optional().describe("Who uses the app, when the person said it"),
+      jobs: z.array(z.string()).optional().describe("The core jobs of the app, when the person named them"),
+      name: z.string().optional().describe("Name of the product, for the report's project"),
+      project_dir: z.string().optional().describe("The project folder, when it is not the folder the agent runs in"),
+    },
+    (args) => connector.startReview(args),
+  );
+  tool(
+    "capture",
+    "Save a screenshot and the probe of each route at laptop and phone size, in the report folder. Without routes, captures the routes the scan found.",
+    { routes: z.array(z.string()).optional().describe("Routes such as / and /pricing") },
+    (args) => connector.capture(args),
+  );
+  tool(
+    "open",
+    "Open a page of the app by path, such as /pricing, or by a full URL on the same site. Pages on other sites are refused.",
+    { path: z.string() },
+    browser((session, { path }) => session.open(path)),
+  );
+  tool(
+    "snapshot",
+    "Read the current page as an accessibility tree: headings, text, links, buttons and fields with their names. Take one before clicking.",
+    {},
+    browser((session) => session.snapshot()),
+  );
+  tool(
+    "click",
+    "Click something the way a person would: by role and accessible name, such as role button and name Save, or by visible text. Reports dialogs, new tabs and JavaScript errors that followed.",
+    {
+      role: z.string().optional(),
+      name: z.string().optional(),
+      text: z.string().optional(),
+      exact: z.boolean().optional(),
+      nth: z.number().int().min(0).optional(),
+    },
+    browser((session, args) => session.click(args)),
+  );
+  tool(
+    "fill",
+    "Type into a field found by its label, or by its placeholder when it has no label. Use obvious test data, never real personal data.",
+    { label: z.string().optional(), placeholder: z.string().optional(), value: z.string() },
+    browser((session, args) => session.fill(args)),
+  );
+  tool("select", "Choose an option in a list found by its label.", { label: z.string(), option: z.string() }, browser((session, args) => session.select(args)));
+  tool(
+    "check",
+    "Check or uncheck a checkbox or a radio button found by its label.",
+    { label: z.string(), checked: z.boolean().optional() },
+    browser((session, args) => session.check(args)),
+  );
+  tool("press", "Press a key, such as Tab, Enter or Escape, and report where the focus went.", { key: z.string() }, browser((session, args) => session.press(args)));
+  tool("back", "Go back to the previous page.", {}, browser((session) => session.back()));
+  tool(
+    "screenshot",
+    "Save a screenshot of the current page in the report folder as evidence, and look at it. Name it after the moment, such as signup-empty.",
+    { name: z.string(), fullPage: z.boolean().optional() },
+    async (args) => {
+      const shot = await (await connector.browser()).screenshot(args);
+      return { image: shot.data, text: `Saved ${shot.path}.` };
+    },
+  );
+  tool(
+    "probe",
+    "Measure the current page: text contrast, button sizes, unnamed icon buttons, dead links, form fields and decoration.",
+    { name: z.string() },
+    async (args) => {
+      const result = await (await connector.browser()).probe(args);
+      return { text: `Saved ${result.path}.\n${result.summary}` };
+    },
+  );
+  tool(
+    "resize",
+    "Switch between laptop size (desktop, 1440 by 900) and phone size (mobile, 390 by 844). The page loads again.",
+    { size: z.enum(["desktop", "mobile"]) },
+    browser((session, args) => session.resize(args)),
+  );
+  tool(
+    "guide",
+    "Get one of Phyll's guides for this review: walkthrough, heuristics, report-format, fixing, or tells with the ids you need.",
+    {
+      name: z.enum(["walkthrough", "heuristics", "report-format", "fixing", "tells"]),
+      tells: z.array(z.string()).optional().describe("Tell ids such as F05 and L01, for the tells guide"),
+    },
+    (args) => connector.guide(args),
+  );
+  tool(
+    "finish_review",
+    "Send report.json to Phyll, which checks it, scores it, keeps it with a link and writes report.md. If it lists problems, fix the file and call it again.",
+    {},
+    () => connector.finishReview(),
+  );
+  tool("scan", "Scan a project's source for AI tells, with no account and no AI. Returns the static index and the tells found.", { dir: z.string().optional() }, (args) => connector.scan(args));
+  tool("account", "Show the Phyll plan and how many free reviews are left.", {}, () => connector.account());
+  tool("upgrade", "Get the link for the person to subscribe to Phyll Pro.", {}, () => connector.upgrade());
+  return server;
+}
+
+export async function runMcpServer(options = {}) {
+  const connector = new Connector(options);
+  const server = createServer(connector);
+  await server.connect(new StdioServerTransport());
+  const stop = async () => {
+    await connector.close();
+    // Let the process end on its own: exiting inside the stdin close callback trips a libuv
+    // assertion on Windows. The timer only fires if something still holds the event loop.
+    setTimeout(() => process.exit(0), 1000).unref();
+  };
+  process.stdin.on("close", stop);
+  process.on("SIGTERM", stop);
+}

package/src/paths.mjs

@@ -0,0 +1,19 @@
+// Where the connector finds the scanner and the probe: skills/phyll when it runs from the
+// repository, or the copy packed next to it on npm. The copy holds only the open parts.
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PACKAGE_DIR = join(HERE, "..");
+const REPO = join(PACKAGE_DIR, "..", "..");
+const IN_REPO = existsSync(join(REPO, "skills", "phyll", "scripts", "scan.mjs")) && existsSync(join(REPO, "packages", "connector", "package.json"));
+
+export const SKILL_DIR = IN_REPO ? join(REPO, "skills", "phyll") : join(PACKAGE_DIR, "skill");
+export const BIN = join(PACKAGE_DIR, "bin", "phyll.mjs");
+export const VERSION = JSON.parse(readFileSync(join(PACKAGE_DIR, "package.json"), "utf8")).version;
+// Installed from npm, the package sits inside a node_modules folder; from the repository it does not.
+export const PUBLISHED = PACKAGE_DIR.split(/[\\/]/).includes("node_modules");
+
+export const importSkill = (relative) => import(pathToFileURL(join(SKILL_DIR, relative)).href);
+export const probeSource = () => readFileSync(join(SKILL_DIR, "scripts", "probe.js"), "utf8");

package/src/review.mjs

@@ -0,0 +1,226 @@
+// What each connector tool does. The agent that calls them does the thinking on its owner's
+// plan; the connector keeps the browser, the files and the key on this machine and asks the
+// engine for the method, the guides and the finished report.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { BrowserSession, captureWithSession } from "./browser.mjs";
+import { loadCredentials } from "./credentials.mjs";
+import { engineClient } from "./engine.mjs";
+import { importSkill, probeSource, VERSION } from "./paths.mjs";
+
+export const timestamp = (date = new Date()) => date.toISOString().replace(/[:.]/g, "-").slice(0, 19);
+
+export function normalizeUrl(input) {
+  const text = String(input ?? "").trim();
+  if (!text) throw new Error("give the address of the running app, such as http://localhost:3000");
+  const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `http://${text}`);
+  if (!/^https?:$/.test(url.protocol)) throw new Error("the address must start with http:// or https://");
+  return url.href;
+}
+
+function localeLanguage() {
+  const locale = Intl.DateTimeFormat().resolvedOptions().locale ?? "";
+  return locale.toLowerCase().startsWith("pt") ? "pt-BR" : "en";
+}
+
+export function describeCapture(manifest) {
+  const pages = manifest?.pages ?? [];
+  if (!pages.length) return "No screen could be captured, so capture what you need with the browser tools.";
+  const lines = pages.map((p) => {
+    const files = [p.screenshot, p.probe].filter(Boolean).join(", ");
+    const trouble = p.error ? ` Could not capture: ${p.error}.` : "";
+    const errors = p.consoleErrors?.length ? ` JavaScript errors: ${p.consoleErrors.slice(0, 2).join(" | ")}.` : "";
+    return `- ${p.route} at ${p.viewport} size${p.status ? `, HTTP ${p.status}` : ""}: ${files || "no files"}.${trouble}${errors}`;
+  });
+  return ["Captured screens, with the probe result for each, saved in capture.json:", ...lines].join("\n");
+}
+
+function finishText(result, reportRel) {
+  const report = result.report ?? {};
+  const summary = report.summary ?? {};
+  const byId = new Map((report.findings ?? []).map((f) => [f.id, f]));
+  const top = (report.topThree ?? []).map((id) => byId.get(id)).filter(Boolean);
+  const previous = typeof report.history?.previousIndex === "number" ? `, previous ${report.history.previousIndex}` : "";
+  return [
+    result.message,
+    `AI tell index: ${summary.aiTellIndex ?? "n/a"}/100${previous}. Lower is better.`,
+    summary.inputs ? `Inputs asked / needed on the core jobs: ${summary.inputs.asked} / ${summary.inputs.needed}.` : null,
+    top.length ? "What blocks people most:" : null,
+    ...top.map((f, i) => `${i + 1}. ${f.title} (${f.severity})`),
+    `Report on this machine: ${reportRel}/report.md`,
+    `Link: ${result.url}`,
+    "Tell the person the index, these findings and where the report is, and offer to fix them.",
+  ]
+    .filter((line) => line !== null && line !== undefined)
+    .join("\n");
+}
+
+const NOT_CONNECTED =
+  "Phyll is not connected on this computer yet. Ask the person to run npx phyll signup their@email.com in a terminal (or npx phyll login <key> if they already have an account), then try again.";
+
+export class Connector {
+  constructor({ env = process.env, cwd = process.cwd(), fetchImpl = globalThis.fetch, loadPlaywright = () => import("playwright"), now = () => new Date() } = {}) {
+    this.env = env;
+    this.cwd = cwd;
+    this.fetchImpl = fetchImpl;
+    this.loadPlaywright = loadPlaywright;
+    this.now = now;
+    this.review = null;
+  }
+
+  engine() {
+    const { server, key } = loadCredentials(this.env);
+    return key && server ? engineClient({ server, key, version: VERSION, fetchImpl: this.fetchImpl }) : null;
+  }
+
+  // The review of this session, or the newest one in the project, so fixes can happen in a new
+  // conversation after the review ended.
+  current() {
+    if (this.review) return this.review;
+    const reports = join(this.cwd, ".phyll", "reports");
+    const newest = existsSync(reports)
+      ? readdirSync(reports)
+          .filter((name) => existsSync(join(reports, name, "session.json")))
+          .sort()
+          .at(-1)
+      : null;
+    if (!newest) throw new Error("no review has started. Call start_review with the address of the app first.");
+    const saved = JSON.parse(readFileSync(join(reports, newest, "session.json"), "utf8"));
+    this.review = { ...saved, project: this.cwd, reportDir: join(reports, newest), reportRel: `.phyll/reports/${newest}`, browser: null };
+    return this.review;
+  }
+
+  async browser() {
+    const review = this.current();
+    if (!review.browser) {
+      const mod = await this.loadPlaywright();
+      const playwright = mod.chromium ? mod : mod.default;
+      const session = new BrowserSession({ playwright, baseUrl: review.url, out: review.reportDir, probeSource: probeSource() });
+      try {
+        await session.start();
+      } catch (error) {
+        const missing = /Executable doesn't exist|playwright install/i.test(error?.message ?? "");
+        throw new Error(missing ? "the browser is not installed. Ask the person to run npx phyll setup codex (or claude) once." : `the browser did not start: ${error.message}`);
+      }
+      review.browser = session;
+    }
+    return review.browser;
+  }
+
+  async scan({ dir } = {}) {
+    const { scan, formatText } = await importSkill("scripts/scan.mjs");
+    return { text: formatText(scan(resolve(this.cwd, dir ?? "."))) };
+  }
+
+  async startReview({ url, name, language, user, jobs, project_dir: projectDir } = {}) {
+    const engine = this.engine();
+    if (!engine) return { text: NOT_CONNECTED, isError: true };
+    const target = normalizeUrl(url);
+    const project = resolve(this.cwd, projectDir ?? ".");
+    if (!existsSync(project)) throw new Error(`the project folder ${project} does not exist`);
+    const { configPath, readConfigFile } = await importSkill("scripts/lib/config.mjs");
+    const config = readConfigFile(configPath(project));
+    const reportRel = `.phyll/reports/${timestamp(this.now())}`;
+    const reportDir = join(project, ...reportRel.split("/"));
+    mkdirSync(reportDir, { recursive: true });
+
+    const { scan } = await importSkill("scripts/scan.mjs");
+    const result = scan(project, { ignore: config.ignore ?? [] });
+    writeFileSync(join(reportDir, "scan.json"), JSON.stringify(result, null, 2) + "\n");
+    const routes = (result.structure?.routes ?? []).map((r) => r.path);
+    const summary = {
+      staticIndex: result.staticIndex,
+      tells: result.tells.filter((t) => t.hits > 0).map((t) => ({ id: t.id, hits: t.hits })),
+      structure: {
+        routes: routes.map((path) => ({ path })),
+        forms: (result.structure?.forms ?? []).map((f) => ({ file: f.file, line: f.line, fields: f.fields })),
+      },
+    };
+
+    const lang = language || config.language || localeLanguage();
+    const answer = await engine.startSession({
+      url: target,
+      name: name || config.name || basename(project),
+      language: lang,
+      user: user || config.endUser || undefined,
+      jobs: jobs?.length ? jobs : Array.isArray(config.coreJobs) ? config.coreJobs : [],
+      reportFolder: reportRel,
+      scan: summary,
+    });
+    if (!answer.ok) {
+      rmSync(reportDir, { recursive: true, force: true });
+      const link = answer.json.checkoutUrl ? `\nCheckout: ${answer.json.checkoutUrl}` : "";
+      return { text: `${answer.json.message ?? `Phyll answered ${answer.status}.`}${link}`, isError: answer.status !== 402 };
+    }
+    await this.review?.browser?.close();
+    const { staticRoutes } = await importSkill("scripts/capture.mjs");
+    this.review = { id: answer.json.id, url: target, project, reportDir, reportRel, routes: staticRoutes(routes), browser: null };
+    writeFileSync(join(reportDir, "session.json"), JSON.stringify({ id: answer.json.id, url: target, routes: this.review.routes }, null, 2) + "\n");
+    return { text: [answer.json.message, `Report folder: ${reportRel}`, "", answer.json.instructions].join("\n") };
+  }
+
+  async capture({ routes } = {}) {
+    const review = this.current();
+    const { staticRoutes, uniqueSlugs } = await importSkill("scripts/capture.mjs");
+    let list = staticRoutes(routes?.length ? routes : review.routes).slice(0, 12);
+    if (!list.length) list = ["/"];
+    const session = await this.browser();
+    return { text: describeCapture(await captureWithSession({ session, routes: list, out: review.reportDir, slugs: uniqueSlugs(list) })) };
+  }
+
+  async guide({ name, tells = [] } = {}) {
+    const review = this.current();
+    const engine = this.engine();
+    if (!engine) return { text: NOT_CONNECTED, isError: true };
+    const answer = await engine.guide(review.id, name, tells);
+    return answer.ok ? { text: answer.json.text } : { text: answer.json.message ?? `Phyll answered ${answer.status}.`, isError: true };
+  }
+
+  async finishReview() {
+    const review = this.current();
+    const engine = this.engine();
+    if (!engine) return { text: NOT_CONNECTED, isError: true };
+    const path = join(review.reportDir, "report.json");
+    if (!existsSync(path)) return { text: `report.json is missing in ${review.reportRel}. Write it there first.`, isError: true };
+    let report;
+    try {
+      report = JSON.parse(readFileSync(path, "utf8"));
+    } catch (error) {
+      return { text: `report.json is not valid JSON: ${error.message}`, isError: true };
+    }
+    const answer = await engine.submitReport(review.id, report);
+    if (!answer.ok) {
+      const problems = (answer.json.errors ?? []).map((e) => `- ${e}`);
+      return { text: [answer.json.message ?? `Phyll answered ${answer.status}.`, ...problems].join("\n"), isError: true };
+    }
+    writeFileSync(path, JSON.stringify(answer.json.report, null, 2) + "\n");
+    writeFileSync(join(review.reportDir, "report.md"), answer.json.markdown);
+    await review.browser?.close();
+    review.browser = null;
+    return { text: finishText(answer.json, review.reportRel) };
+  }
+
+  async account() {
+    const engine = this.engine();
+    if (!engine) return { text: NOT_CONNECTED, isError: true };
+    const answer = await engine.me();
+    if (!answer.ok) return { text: answer.json.message ?? `Phyll answered ${answer.status}.`, isError: true };
+    const me = answer.json;
+    const sessions = me.sessions ?? {};
+    const left = me.plan === "pro" ? "Phyll Pro, unlimited reviews" : `${Math.max(0, (sessions.limit ?? 0) - (sessions.used ?? 0))} of ${sessions.limit} free reviews left`;
+    return { text: `${me.email}: ${left}.` };
+  }
+
+  async upgrade() {
+    const engine = this.engine();
+    if (!engine) return { text: NOT_CONNECTED, isError: true };
+    const answer = await engine.checkout();
+    return answer.ok
+      ? { text: `Ask the person to open this link to subscribe to Phyll Pro: ${answer.json.url}` }
+      : { text: answer.json.message ?? `Phyll answered ${answer.status}.`, isError: true };
+  }
+
+  async close() {
+    await this.review?.browser?.close();
+  }
+}

package/src/setup.mjs

@@ -0,0 +1,69 @@
+// Connects Phyll to the person's agent: an MCP server entry in Codex's config.toml, or a
+// `claude mcp add` for Claude Code, and the Chromium build Playwright needs.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BIN, PUBLISHED } from "./paths.mjs";
+
+// How the agent starts the connector: through npx when installed from npm, or straight from
+// this folder when it runs from the repository.
+export function mcpCommand({ published = PUBLISHED, platform = process.platform, node = process.execPath, bin = BIN } = {}) {
+  if (!published) return [node, bin, "mcp"];
+  const npx = ["npx", "-y", "phyll@latest", "mcp"];
+  return platform === "win32" ? ["cmd", "/c", ...npx] : npx;
+}
+
+const tomlString = (value) => JSON.stringify(String(value));
+
+export function codexBlock(command) {
+  return `[mcp_servers.phyll]\ncommand = ${tomlString(command[0])}\nargs = [${command.slice(1).map(tomlString).join(", ")}]\n`;
+}
+
+// Removes [mcp_servers.phyll] and its sub-tables, keeping everything else in the file as it was.
+export function withoutTable(text, name) {
+  const kept = [];
+  let skipping = false;
+  for (const line of text.split("\n")) {
+    const header = line.trim().match(/^\[\[?\s*([^\]]+?)\s*\]\]?$/);
+    if (header) skipping = header[1] === name || header[1].startsWith(`${name}.`);
+    if (!skipping) kept.push(line);
+  }
+  return kept.join("\n");
+}
+
+export function writeCodexConfig(command, env = process.env) {
+  const dir = env.CODEX_HOME || join(homedir(), ".codex");
+  const file = join(dir, "config.toml");
+  const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const rest = withoutTable(before, "mcp_servers.phyll").replace(/\s+$/, "");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, `${rest ? `${rest}\n\n` : ""}${codexBlock(command)}`);
+  return file;
+}
+
+const quote = (arg) => (/[\s"]/.test(arg) ? `"${arg.replaceAll('"', '\\"')}"` : arg);
+
+export function registerClaude(command, run = spawnSync) {
+  const args = ["mcp", "add", "--scope", "user", "phyll", "--", ...command];
+  const call = (list) => run("claude", list.map(quote), { shell: true, encoding: "utf8" });
+  call(["mcp", "remove", "phyll", "--scope", "user"]);
+  const added = call(args);
+  if (added.error || added.status !== 0) return { ok: false, manual: `claude ${args.map(quote).join(" ")}` };
+  return { ok: true };
+}
+
+// Opens Chromium once; when Playwright says it is missing, installs it.
+export async function ensureBrowser({ write = () => {}, run = spawnSync } = {}) {
+  const { chromium } = await import("playwright");
+  try {
+    await (await chromium.launch()).close();
+    return true;
+  } catch (error) {
+    if (!/Executable doesn't exist|playwright install/i.test(error?.message ?? "")) throw error;
+  }
+  write("Installing the browser Phyll uses, Chromium (about 150 MB)...\n");
+  const cli = createRequire(import.meta.url).resolve("playwright/cli");
+  return run(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" }).status === 0;
+}