phyll 0.4.1

package/skill/scripts/scan.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// Phyll static scan: finds AI tells in the source and maps routes, forms and modals.
+//
+//   node scan.mjs [dir] [--out scan.json] [--format json|text] [--config path]
+//
+// With --out the JSON goes to the file and a one-line summary to stdout.
+// Without it, JSON (default) or a text summary goes to stdout.
+import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { fail, isMain } from "./lib/cli.mjs";
+import { configPath, readConfigFile } from "./lib/config.mjs";
+import { runTells } from "./lib/detectors.mjs";
+import { walk } from "./lib/files.mjs";
+import { computeIndex, kindOf, staticEntries } from "./lib/score.mjs";
+import { analyzeStructure } from "./lib/structure.mjs";
+import { NAME, VERSION } from "./lib/version.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const TELLS_PATH = join(HERE, "..", "data", "tells.json");
+
+export function loadTells(path = TELLS_PATH) {
+  return JSON.parse(readFileSync(path, "utf8")).tells;
+}
+
+// The scanned folder relative to where the scan runs, so reports do not carry local paths
+// such as a home folder. Folders outside the working directory keep only their name.
+export function displayRoot(root, cwd = process.cwd()) {
+  const rel = relative(cwd, root).split(sep).join("/");
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || isAbsolute(rel)) return basename(root);
+  return rel;
+}
+
+export function scan(root, { ignore = [], tells = loadTells() } = {}) {
+  const { files, ignored } = walk(root, { ignore });
+  const cache = new Map();
+  const readText = (file) => {
+    if (!cache.has(file.abs)) cache.set(file.abs, readFileSync(file.abs, "utf8"));
+    return cache.get(file.abs);
+  };
+
+  const structure = analyzeStructure(root, files, readText);
+  const results = new Map(runTells(tells, files, readText, structure).map((r) => [r.id, r]));
+
+  const scanned = tells
+    .filter((t) => t.detection !== "dynamic")
+    .map((t) => ({
+      id: t.id,
+      name: t.name,
+      dimension: t.dimension,
+      kind: kindOf(t),
+      detection: t.detection,
+      weight: t.weight,
+      cap: t.cap,
+      hits: results.get(t.id)?.hits ?? 0,
+      locations: results.get(t.id)?.locations ?? [],
+    }));
+
+  const tellsById = new Map(tells.map((t) => [t.id, t]));
+  const entries = staticEntries(tells, scanned);
+  return {
+    tool: { name: NAME, version: VERSION },
+    root: displayRoot(root),
+    createdAt: new Date().toISOString(),
+    files: { scanned: files.length, ignored },
+    structure,
+    tells: scanned,
+    staticIndex: computeIndex(tellsById, entries, "function"),
+    styleIndex: computeIndex(tellsById, entries, "style"),
+  };
+}
+
+export function formatText(result) {
+  const lines = [];
+  lines.push(`Phyll scan of ${result.root}`);
+  lines.push(
+    `Files: ${result.files.scanned} scanned, ${result.files.ignored} ignored. Framework: ${result.structure.framework}. Theme: ${result.structure.theme ?? "unknown"}.`,
+  );
+  lines.push(`Static AI tell index: ${result.staticIndex ?? "n/a"}/100 (lower is better)`);
+  lines.push("");
+
+  const found = result.tells
+    .filter((t) => t.hits > 0)
+    .sort((a, b) => b.weight - a.weight || b.hits - a.hits);
+  const functionTells = found.filter((t) => (t.kind ?? "function") === "function");
+  const styleTells = found.filter((t) => t.kind === "style");
+  const width = Math.min(48, Math.max(10, ...found.map((t) => t.name.length)));
+  const row = (t) => {
+    const where = t.locations[0] ? `${t.locations[0].file}:${t.locations[0].line}` : "";
+    const name = t.name.length > width ? t.name.slice(0, width - 1) + "." : t.name.padEnd(width);
+    return `  ${t.id}  ${name}  ${String(t.hits).padStart(3)} hits  ${where}`;
+  };
+
+  if (functionTells.length === 0) lines.push("No tells that get in the way of use were found in the source.");
+  else lines.push("Tells that get in the way of use:", ...functionTells.map(row));
+  lines.push("");
+  if (styleTells.length) {
+    lines.push(
+      `Style notes, left as they are (style index ${result.styleIndex ?? "n/a"}/100):`,
+      ...styleTells.map(row),
+      "",
+    );
+  }
+
+  const { routes, forms, modals, notes } = result.structure;
+  lines.push(routes.length ? `Routes: ${routes.map((r) => r.path).join(", ")}` : "Routes: none found");
+  const longForms = forms.filter((f) => f.fields >= 7);
+  if (forms.length) {
+    const deferred = forms.reduce((sum, f) => sum + (f.deferred ?? 0), 0);
+    lines.push(
+      `Forms: ${forms.length}` +
+        (longForms.length ? `, longest ${Math.max(...forms.map((f) => f.fields))} fields` : "") +
+        (deferred ? `, plus ${deferred} optional behind a closed <details>` : ""),
+    );
+  }
+  if (modals.count) lines.push(`Modals: ${modals.count}`);
+  for (const note of notes) lines.push(`Note: ${note}`);
+  return lines.join("\n") + "\n";
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({
+      allowPositionals: true,
+      options: {
+        out: { type: "string" },
+        format: { type: "string", default: "json" },
+        config: { type: "string" },
+        help: { type: "boolean", short: "h" },
+      },
+    });
+  } catch (error) {
+    fail(error.message, 2);
+  }
+  const { values, positionals } = args;
+  if (values.help) {
+    process.stdout.write("Usage: node scan.mjs [dir] [--out scan.json] [--format json|text] [--config path]\n");
+    return;
+  }
+
+  const root = resolve(positionals[0] ?? ".");
+  let isDir = false;
+  try {
+    isDir = statSync(root).isDirectory();
+  } catch {
+    isDir = false;
+  }
+  if (!isDir) fail(`${root} is not a folder`, 2);
+
+  let config;
+  try {
+    config = readConfigFile(values.config ? resolve(values.config) : configPath(root));
+  } catch (error) {
+    fail(error.message, 2);
+  }
+
+  const result = scan(root, { ignore: Array.isArray(config.ignore) ? config.ignore : [] });
+  const json = JSON.stringify(result, null, 2) + "\n";
+
+  if (values.out) {
+    const out = resolve(values.out);
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, json);
+    const found = result.tells.filter((t) => t.hits > 0).length;
+    if (values.format === "text") process.stdout.write(formatText(result));
+    process.stdout.write(`Wrote ${out}: static index ${result.staticIndex ?? "n/a"}, ${found} tells found.\n`);
+    return;
+  }
+  process.stdout.write(values.format === "text" ? formatText(result) : json);
+}
+
+if (isMain(import.meta.url)) main();

package/src/browser.mjs

@@ -0,0 +1,317 @@
+// The browser the review agent walks the app with. It stays on the reviewed site, accepts
+// dialogs and reports what they said, saves screenshots and probe results in the report folder,
+// and keeps a log of every action in actions.json as part of the evidence.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SIZES = Object.freeze({
+  desktop: { viewport: { width: 1440, height: 900 } },
+  mobile: { viewport: { width: 390, height: 844 }, deviceScaleFactor: 1, isMobile: true, hasTouch: true },
+});
+
+const MAX_TREE = 12000;
+const MAX_SHOT_HEIGHT = 5000;
+const clip = (s, n = 300) => String(s ?? "").replace(/\s+/g, " ").trim().slice(0, n);
+
+export function sameSite(target, base) {
+  try {
+    return new URL(target, base).origin === new URL(base).origin;
+  } catch {
+    return false;
+  }
+}
+
+export function fileSlug(name) {
+  const slug = String(name ?? "")
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return slug || "screen";
+}
+
+// A few lines the agent can read at a glance; the full probe result is saved as JSON.
+export function summarizeProbe(p) {
+  const lines = [];
+  if (p?.page) lines.push(`Page height ${p.page.height}px${p.page.horizontalOverflow ? ", and it scrolls sideways" : ""}.`);
+  if (p?.contrast) {
+    const samples = (p.contrast.samples ?? [])
+      .slice(0, 3)
+      .map((s) => `"${clip(s.text, 40)}" at ${s.ratio}:1`)
+      .join("; ");
+    lines.push(`Contrast: ${p.contrast.failures} of ${p.contrast.checked} texts below the minimum${samples ? ` (${samples})` : ""}.`);
+  }
+  if (p?.actions) {
+    const a = p.actions;
+    lines.push(
+      `Actions: ${a.total} in total, ${a.primaryInFirstView} primary in the first view, ${a.iconOnlyUnnamed} icon-only without a name, ` +
+        `${a.smallTargets} smaller than 24px, ${a.deadLinks} dead links, ${a.hiddenUntilHover} shown only on hover.`,
+    );
+  }
+  if (p?.forms?.length) lines.push(`Forms: ${p.forms.map((f) => `${f.fields} fields, ${f.unlabeled} without a label`).join("; ")}.`);
+  if (p?.looseFields) lines.push(`${p.looseFields} fields sit outside any form.`);
+  if (p?.decor) lines.push(`Decoration: ${Object.entries(p.decor).map(([k, v]) => `${k} ${v}`).join(", ")}.`);
+  if (p?.errors?.length) lines.push(`The probe could not measure: ${p.errors.slice(0, 3).map((e) => clip(e, 80)).join("; ")}.`);
+  return lines.join("\n");
+}
+
+export class BrowserSession {
+  // allowRequest(url) decides every request the pages make. Phyll Cloud passes one that refuses
+  // private addresses; the command line tool, reviewing your own app, passes none.
+  constructor({ playwright, baseUrl, out, probeSource, headless = true, allowRequest = null }) {
+    this.playwright = playwright;
+    this.baseUrl = new URL(baseUrl).href;
+    this.out = out;
+    this.probeSource = probeSource;
+    this.headless = headless;
+    this.allowRequest = allowRequest;
+    this.size = "desktop";
+    this.log = [];
+    this.dialogs = [];
+    this.errors = [];
+    this.popups = [];
+    this.blocked = [];
+    this.lastStatus = null;
+  }
+
+  async start(size = "desktop") {
+    this.browser ??= await this.playwright.chromium.launch({ headless: this.headless });
+    await this.#newContext(size);
+    return this;
+  }
+
+  async #newContext(size) {
+    await this.context?.close().catch(() => {});
+    this.context = await this.browser.newContext({ ...SIZES[size], acceptDownloads: false });
+    if (this.allowRequest) {
+      await this.context.route("**/*", async (route) => {
+        const url = route.request().url();
+        if (await this.allowRequest(url)) return route.continue();
+        this.blocked.push(clip(url, 160));
+        return route.abort("blockedbyclient");
+      });
+      // WebSockets do not pass through route(), so they get the same check here.
+      await this.context.routeWebSocket(/.*/, async (ws) => {
+        if (await this.allowRequest(ws.url())) return ws.connectToServer();
+        this.blocked.push(clip(ws.url(), 160));
+        return ws.close({ code: 1008, reason: "Blocked by Phyll" });
+      });
+    }
+    this.size = size;
+    this.page = await this.context.newPage();
+    this.page.on("dialog", async (dialog) => {
+      this.dialogs.push(`${dialog.type()} "${clip(dialog.message(), 160)}"`);
+      await dialog.accept().catch(() => {});
+    });
+    this.page.on("console", (m) => {
+      if (m.type() === "error") this.errors.push(clip(m.text(), 200));
+    });
+    this.page.on("pageerror", (e) => this.errors.push(clip(e.message, 200)));
+    // New tabs, such as links with target=_blank, are closed and reported instead of followed.
+    this.context.on("page", (p) => {
+      this.popups.push(clip(p.url(), 160));
+      p.close().catch(() => {});
+    });
+  }
+
+  #path() {
+    try {
+      const u = new URL(this.page.url());
+      return u.pathname + u.search + u.hash;
+    } catch {
+      return this.page.url();
+    }
+  }
+
+  #record(action, detail = "") {
+    this.log.push({ at: new Date().toISOString(), action, detail, path: this.#path(), viewport: this.size });
+  }
+
+  #state(prefix) {
+    const parts = [prefix, `Now on ${this.#path()} at ${this.size} size.`];
+    if (this.dialogs.length) parts.push(`Dialogs shown and accepted: ${this.dialogs.splice(0).join(" | ")}.`);
+    if (this.popups.length) parts.push(`New tabs opened and closed: ${this.popups.splice(0).join(" | ")}.`);
+    if (this.blocked.length) parts.push(`Requests to private addresses were blocked: ${this.blocked.splice(0).slice(0, 3).join(" | ")}.`);
+    if (this.errors.length) parts.push(`JavaScript errors: ${this.errors.splice(0).join(" | ")}.`);
+    return parts.join(" ");
+  }
+
+  async #goto(url) {
+    let response = null;
+    try {
+      response = await this.page.goto(url, { waitUntil: "networkidle", timeout: 20000 });
+    } catch {
+      response = await this.page.goto(url, { waitUntil: "load", timeout: 20000 });
+    }
+    this.lastStatus = response?.status() ?? null;
+  }
+
+  async #settle() {
+    await this.page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+    await this.page.waitForTimeout(150);
+  }
+
+  async #after(label) {
+    await this.#settle();
+    let note = "";
+    if (!sameSite(this.page.url(), this.baseUrl)) {
+      const left = clip(this.page.url(), 160);
+      await this.page.goBack({ timeout: 10000 }).catch(() => {});
+      note = ` It led outside the app, to ${left}, so the browser went back.`;
+    }
+    return this.#state(`${label}.${note}`);
+  }
+
+  async open(target) {
+    const url = new URL(target, this.baseUrl).href;
+    if (!sameSite(url, this.baseUrl)) throw new Error(`only pages on ${new URL(this.baseUrl).origin} can be opened`);
+    if (this.allowRequest && !(await this.allowRequest(url))) throw new Error("that address is not public, so it cannot be opened");
+    await this.#goto(url);
+    this.#record("open", url);
+    const failed = this.lastStatus >= 400 ? ` and the server answered ${this.lastStatus}` : "";
+    return this.#state(`Opened ${this.#path()}${failed}`);
+  }
+
+  async snapshot() {
+    const title = await this.page.title().catch(() => "");
+    let tree = await this.page
+      .locator("body")
+      .ariaSnapshot({ timeout: 5000 })
+      .catch(() => "");
+    if (tree.length > MAX_TREE) tree = `${tree.slice(0, MAX_TREE)}\n[the rest of the page was cut]`;
+    this.#record("snapshot");
+    return `${this.#state(`Page titled "${clip(title, 120)}".`)}\n\n${tree}`;
+  }
+
+  async click({ role, name, text, exact = false, nth = 0 } = {}) {
+    let target = role ? this.page.getByRole(role, { name, exact }) : this.page.getByText(text ?? name ?? "", { exact });
+    let what = role ? `${role} "${name ?? ""}"` : `"${text ?? name}"`;
+    let count = await target.count();
+    if (!count && role && name) {
+      target = this.page.getByText(name, { exact });
+      what = `"${name}"`;
+      count = await target.count();
+    }
+    if (!count) throw new Error(`nothing on the page matches ${what}; take a snapshot to see what is there`);
+    await target.nth(Math.min(nth, count - 1)).click({ timeout: 5000 });
+    this.#record("click", what);
+    return this.#after(`Clicked ${what}${count > 1 ? `, the ${nth + 1}. of ${count} matches` : ""}`);
+  }
+
+  async fill({ label, placeholder, value } = {}) {
+    let target = label ? this.page.getByLabel(label, { exact: false }) : this.page.getByPlaceholder(placeholder ?? "");
+    if (label && !(await target.count())) target = this.page.getByPlaceholder(label);
+    if (!(await target.count())) throw new Error(`no field is labeled "${label ?? placeholder}"`);
+    await target.first().fill(String(value ?? ""), { timeout: 5000 });
+    this.#record("fill", label ?? placeholder);
+    return this.#after(`Typed into "${label ?? placeholder}"`);
+  }
+
+  async select({ label, option } = {}) {
+    const target = this.page.getByLabel(label, { exact: false });
+    if (!(await target.count())) throw new Error(`no list is labeled "${label}"`);
+    await target.first().selectOption({ label: option }, { timeout: 5000 });
+    this.#record("select", `${label}: ${option}`);
+    return this.#after(`Chose "${option}" in "${label}"`);
+  }
+
+  async check({ label, checked = true } = {}) {
+    const target = this.page.getByLabel(label, { exact: false }).first();
+    try {
+      if (checked) await target.check({ timeout: 3000 });
+      else await target.uncheck({ timeout: 3000 });
+    } catch {
+      // Choice chips often hide the real input; clicking the visible text works like a person would.
+      await this.page.getByText(label, { exact: true }).first().click({ timeout: 3000 });
+    }
+    this.#record(checked ? "check" : "uncheck", label);
+    return this.#after(`${checked ? "Checked" : "Unchecked"} "${label}"`);
+  }
+
+  async press({ key } = {}) {
+    await this.page.keyboard.press(key);
+    const focus = await this.page.evaluate(() => {
+      const el = document.activeElement;
+      if (!el || el === document.body) return "nothing";
+      const name = el.getAttribute("aria-label") || el.innerText || el.value || el.getAttribute("placeholder") || "";
+      return `${el.tagName.toLowerCase()} "${String(name).replace(/\s+/g, " ").trim().slice(0, 60)}"`;
+    });
+    this.#record("press", key);
+    return this.#after(`Pressed ${key}; focus is on ${focus}`);
+  }
+
+  async back() {
+    await this.page.goBack({ timeout: 10000 }).catch(() => {});
+    this.#record("back");
+    return this.#after("Went back");
+  }
+
+  async screenshot({ name, fullPage = false } = {}) {
+    const file = `screens/${this.size}-${fileSlug(name)}.png`;
+    mkdirSync(join(this.out, "screens"), { recursive: true });
+    const options = { path: join(this.out, file), fullPage };
+    if (fullPage) {
+      const height = await this.page.evaluate(() => document.documentElement.scrollHeight);
+      if (height > MAX_SHOT_HEIGHT) options.clip = { x: 0, y: 0, width: SIZES[this.size].viewport.width, height: MAX_SHOT_HEIGHT };
+    }
+    const saved = await this.page.screenshot(options);
+    // The agent looks at what is on screen; a full-page file can be too tall to read as one image.
+    const forAgent = fullPage ? await this.page.screenshot() : saved;
+    this.#record("screenshot", file);
+    return { path: file, data: forAgent.toString("base64") };
+  }
+
+  async probe({ name } = {}) {
+    const data = await this.page.evaluate(this.probeSource);
+    const file = `probe/${this.size}-${fileSlug(name)}.json`;
+    mkdirSync(join(this.out, "probe"), { recursive: true });
+    writeFileSync(join(this.out, file), JSON.stringify(data, null, 2) + "\n");
+    this.#record("probe", file);
+    return { path: file, summary: summarizeProbe(data) };
+  }
+
+  async resize({ size } = {}) {
+    if (!SIZES[size]) throw new Error(`the size must be desktop or mobile`);
+    const url = this.page?.url();
+    await this.#newContext(size);
+    if (url && url !== "about:blank") await this.#goto(url);
+    this.#record("resize", size);
+    return this.#state(`Switched to the ${size} size. The page loaded again, so anything kept only in memory was reset`);
+  }
+
+  async close() {
+    try {
+      writeFileSync(join(this.out, "actions.json"), JSON.stringify(this.log, null, 2) + "\n");
+    } finally {
+      await this.browser?.close().catch(() => {});
+    }
+  }
+}
+
+// The first capture of every route at both sizes, done by a session instead of capture.mjs, so
+// it goes through the session's request rules. Writes capture.json in the same shape.
+export async function captureWithSession({ session, routes, out, slugs }) {
+  const pages = [];
+  for (const size of ["desktop", "mobile"]) {
+    await session.resize({ size });
+    for (const [i, route] of routes.entries()) {
+      const entry = { route, viewport: size, url: new URL(route, session.baseUrl).href, status: null };
+      try {
+        await session.open(route);
+        entry.status = session.lastStatus;
+        entry.screenshot = (await session.screenshot({ name: slugs[i] })).path;
+        entry.probe = (await session.probe({ name: slugs[i] })).path;
+      } catch (error) {
+        entry.error = clip(error.message, 300);
+      }
+      entry.consoleErrors = session.errors.splice(0);
+      pages.push(entry);
+    }
+  }
+  await session.resize({ size: "desktop" });
+  const manifest = { tool: { name: "phyll" }, createdAt: new Date().toISOString(), baseUrl: session.baseUrl, viewports: ["desktop", "mobile"], pages };
+  writeFileSync(join(out, "capture.json"), JSON.stringify(manifest, null, 2) + "\n");
+  return manifest;
+}

package/src/cli.mjs

@@ -0,0 +1,165 @@
+// phyll: the commands a person types. The review itself happens inside their agent, through
+// the MCP server that `phyll mcp` runs and `phyll setup` registers.
+import { parseArgs } from "node:util";
+import { clearCredentials, credentialsPath, loadCredentials, saveCredentials } from "./credentials.mjs";
+import { engineClient } from "./engine.mjs";
+import { importSkill, VERSION } from "./paths.mjs";
+import { ensureBrowser, mcpCommand, registerClaude, writeCodexConfig } from "./setup.mjs";
+
+export const HELP = `Phyll ${VERSION}: UX review for apps built with AI, inside the agent you already use.
+
+Get started:
+  npx phyll signup you@example.com     Create a free account; the key is saved on this computer
+  npx phyll setup codex                Connect Phyll to Codex (or: npx phyll setup claude)
+  Then ask your agent: review my app at http://localhost:3000
+
+Commands:
+  signup <email>     Create a free account, with free full reviews
+  login <key>        Use an account you already have on this computer
+  setup <agent>      Connect Phyll to codex or claude, and install the browser it uses
+  status             Your plan and the reviews left
+  pro                Subscribe to Phyll Pro
+  billing            Change the card or cancel Phyll Pro
+  scan [folder]      Scan the source for AI tells. Free, with no account
+  mcp                Run the connector for your agent (setup registers it for you)
+  logout             Forget the key on this computer
+
+Options: --server <address> for signup and login, --lang <code> for signup, --format json for scan.
+
+The AI work runs in your agent, on your own plan. Phyll's engine sends the method and keeps the reports.
+`;
+
+const guessLanguage = () => ((Intl.DateTimeFormat().resolvedOptions().locale ?? "").toLowerCase().startsWith("pt") ? "pt-BR" : "en");
+
+function options(args, spec) {
+  return parseArgs({ args, allowPositionals: true, strict: true, options: spec });
+}
+
+export async function main(argv, io = {}) {
+  const out = io.stdout ?? process.stdout;
+  const err = io.stderr ?? process.stderr;
+  const env = io.env ?? process.env;
+  const cwd = io.cwd ?? process.cwd();
+  const fetchImpl = io.fetch ?? globalThis.fetch;
+  const write = (text) => out.write(text);
+  const fail = (text, code = 1) => {
+    err.write(`phyll: ${text}\n`);
+    return code;
+  };
+  const client = (server, key) => engineClient({ server, key, version: VERSION, fetchImpl });
+  const [command, ...rest] = argv;
+
+  try {
+    switch (command) {
+      case undefined:
+      case "help":
+      case "-h":
+      case "--help":
+        write(HELP);
+        return 0;
+      case "version":
+      case "-v":
+      case "--version":
+        write(`phyll ${VERSION}\n`);
+        return 0;
+
+      case "signup": {
+        const { values, positionals } = options(rest, { server: { type: "string" }, lang: { type: "string" } });
+        if (positionals.length !== 1) return fail("give your email, such as npx phyll signup you@example.com", 2);
+        const server = String(values.server ?? loadCredentials(env).server ?? "").replace(/\/+$/, "");
+        if (!server) return fail("give the address of the Phyll server with --server", 2);
+        const answer = await client(server, null).signup(positionals[0], values.lang ?? guessLanguage());
+        if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
+        const path = saveCredentials({ server, key: answer.json.key }, env);
+        write(`${answer.json.message}\nYour key, shown only now: ${answer.json.key}\nIt is saved in ${path}.\n\nNext, connect Phyll to your agent:\n  npx phyll setup codex\n  npx phyll setup claude\n`);
+        return 0;
+      }
+
+      case "login": {
+        const { values, positionals } = options(rest, { server: { type: "string" } });
+        if (positionals.length !== 1) return fail("give your key, such as npx phyll login phyll_...", 2);
+        const server = String(values.server ?? loadCredentials(env).server ?? "").replace(/\/+$/, "");
+        if (!server) return fail("give the address of the Phyll server with --server", 2);
+        const answer = await client(server, positionals[0]).me();
+        if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
+        saveCredentials({ server, key: positionals[0] }, env);
+        write(`Signed in as ${answer.json.email}, on the ${answer.json.plan === "pro" ? "Phyll Pro" : "free"} plan.\n`);
+        return 0;
+      }
+
+      case "logout":
+        clearCredentials(env);
+        write(`Removed ${credentialsPath(env)}.\n`);
+        return 0;
+
+      case "status": {
+        const { server, key } = loadCredentials(env);
+        if (!key) return fail("no account on this computer yet. Run npx phyll signup you@example.com");
+        const answer = await client(server, key).me();
+        if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
+        const me = answer.json;
+        const sessions = me.sessions ?? {};
+        const plan =
+          me.plan === "pro"
+            ? `Phyll Pro. Reviews this month: ${sessions.used ?? 0}.`
+            : `Free. ${Math.max(0, (sessions.limit ?? 0) - (sessions.used ?? 0))} of ${sessions.limit} free reviews left.`;
+        write(`${me.email} on ${server}\n${plan}\n`);
+        return 0;
+      }
+
+      case "pro":
+      case "billing": {
+        const { server, key } = loadCredentials(env);
+        if (!key) return fail("no account on this computer yet. Run npx phyll signup you@example.com");
+        const answer = command === "pro" ? await client(server, key).checkout() : await client(server, key).portal();
+        if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
+        write(`${command === "pro" ? "Subscribe to Phyll Pro here" : "Manage Phyll Pro here"}:\n${answer.json.url}\n`);
+        return 0;
+      }
+
+      case "setup": {
+        const agent = rest[0];
+        if (!["codex", "claude"].includes(agent)) return fail("say which agent to connect: npx phyll setup codex, or npx phyll setup claude", 2);
+        const command = io.mcpCommand ?? mcpCommand();
+        if (agent === "codex") {
+          const file = writeCodexConfig(command, env);
+          write(`Phyll is connected to Codex in ${file}. Restart Codex so it loads the connector.\n`);
+        } else {
+          const result = registerClaude(command, io.run);
+          write(
+            result.ok
+              ? "Phyll is connected to Claude Code. Start a new session so it loads the connector.\n"
+              : `Claude Code was not found on this computer. Run this where it is installed:\n  ${result.manual}\n`,
+          );
+        }
+        if (!(await (io.ensureBrowser ?? ensureBrowser)({ write }))) return fail("the browser could not be installed. Run: npx playwright install chromium");
+        write(
+          loadCredentials(env).key
+            ? "Next, ask your agent to review your app, for example: review my app at http://localhost:3000\n"
+            : "Next, create your account: npx phyll signup you@example.com\n",
+        );
+        return 0;
+      }
+
+      case "scan": {
+        const { values, positionals } = options(rest, { format: { type: "string" } });
+        const { scan, formatText } = await importSkill("scripts/scan.mjs");
+        const result = scan(positionals[0] ?? cwd);
+        write(values.format === "json" ? `${JSON.stringify(result, null, 2)}\n` : formatText(result));
+        return 0;
+      }
+
+      case "mcp": {
+        const { runMcpServer } = await import("./mcp.mjs");
+        await runMcpServer({ env, cwd, fetchImpl });
+        return null;
+      }
+
+      default:
+        return fail(`there is no command ${command}. Run npx phyll --help`, 2);
+    }
+  } catch (error) {
+    if (String(error?.code ?? "").startsWith("ERR_PARSE_ARGS")) return fail(`${error.message}. Run npx phyll --help`, 2);
+    throw error;
+  }
+}