phyll 0.4.3 → 0.4.5

package/README.md

@@ -10,12 +10,12 @@ The AI work runs in your agent, on your own plan. This package adds the browser,
 
 ```bash
 npx phyll signup you@example.com
-npx phyll setup codex        # or: npx phyll setup claude
+npx phyll setup codex        # or claude, cursor, windsurf, gemini
 ```
 
 Then ask your agent: "review my app at http://localhost:3000".
 
-`setup` registers the connector in Codex's `config.toml` or with `claude mcp add`, and installs the Chromium build it uses. You need Node 20 or newer.
+`setup` registers the connector in Codex's `config.toml`, with `claude mcp add`, or in the `mcpServers` of Cursor's `~/.cursor/mcp.json`, Windsurf's `~/.codeium/windsurf/mcp_config.json` or Gemini CLI's `~/.gemini/settings.json`, keeping everything else in the file. It also installs the Chromium build the connector uses. For any other agent that takes MCP servers, `npx phyll setup other` prints the entry to paste. You need Node 20 or newer.
 
 Your reports, keys and plan are also on the site: `npx phyll account` opens your account there, already signed in. If you lose the key, sign in at [agentphyll.com/login](https://agentphyll.com/login) with your email and create a new one.
 
@@ -25,12 +25,12 @@ Your reports, keys and plan are also on the site: `npx phyll account` opens your
 | --- | --- |
 | `signup <email>` | Create a free account, with 5 full reviews. The key is saved in `~/.phyll` |
 | `login <key>` | Use an account you already have on this computer |
-| `setup codex` or `setup claude` | Connect Phyll to your agent and install the browser |
+| `setup <agent>` | Connect Phyll to `codex`, `claude`, `cursor`, `windsurf` or `gemini` and install the browser; `setup other` prints the settings for any other agent |
 | `status` | Your plan and the reviews left |
 | `account` | Open your account on agentphyll.com, already signed in: reports, usage, keys and plan |
 | `pro` | Subscribe to Phyll Pro, R$ 9 a month, with unlimited reviews |
 | `billing` | Change the card or cancel Phyll Pro |
-| `scan [folder]` | Scan the source for AI tells, with no account and no AI |
+| `scan [folder]` | Scan the source for AI tells, with no account and no AI. `--format json` for scripts, `--format badge` for a README badge |
 | `mcp` | Run the connector for your agent; `setup` registers it for you |
 | `logout` | Forget the key on this computer |
 

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "phyll",
-  "version": "0.4.3",
-  "description": "UX review for apps built with AI, inside the agent you already use. Connects Codex or Claude Code to the Phyll engine; the AI work stays on your own plan.",
+  "version": "0.4.5",
+  "description": "UX review for apps built with AI, inside the agent you already use. Connects Codex, Claude Code, Cursor, Windsurf or Gemini CLI to the Phyll engine; the AI work stays on your own plan.",
+  "mcpName": "io.github.carlosphyll/phyll",
   "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/carlosphyll/phyll",
@@ -14,8 +15,12 @@
     "ux",
     "ux-review",
     "mcp",
+    "mcp-server",
     "codex",
     "claude-code",
+    "cursor",
+    "windsurf",
+    "gemini-cli",
     "ai",
     "vibe-coding"
   ],

package/skill/data/tells.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.3",
+  "version": "0.4.5",
   "tells": [
     {
       "id": "P01",
@@ -1636,6 +1636,17 @@
           "<input className=\"focus:outline-none focus:ring-2\" />"
         ]
       }
+    },
+    {
+      "id": "S07",
+      "name": "No results that look like an empty list",
+      "dimension": "states",
+      "kind": "function",
+      "severity": "major",
+      "weight": 2,
+      "cap": 1,
+      "detection": "dynamic",
+      "summary": "A search or filter that matches nothing shows the same screen as a list with nothing in it, or gives no way to clear it, so people think their data is gone or get stuck."
     }
   ]
 }

package/skill/scripts/lib/version.mjs

@@ -1,3 +1,3 @@
 // Single source for the tool name and version used in scan output and reports.
 export const NAME = "phyll";
-export const VERSION = "0.4.3";
+export const VERSION = "0.4.5";

package/skill/scripts/scan.mjs

@@ -90,7 +90,7 @@ export function formatText(result) {
   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}`;
+    return `  ${t.id}  ${name}  ${String(t.hits).padStart(3)} ${t.hits === 1 ? "hit " : "hits"}  ${where}`;
   };
 
   if (functionTells.length === 0) lines.push("No tells that get in the way of use were found in the source.");

package/src/cli.mjs

@@ -1,22 +1,29 @@
 // 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 { spawn } from "node:child_process";
+import { homedir, hostname } from "node:os";
+import { join } from "node:path";
 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";
+import { ensureBrowser, JSON_AGENTS, mcpCommand, mcpJson, registerClaude, writeCodexConfig, writeJsonConfig } from "./setup.mjs";
+
+const AGENTS = ["codex", "claude", ...Object.keys(JSON_AGENTS)];
 
 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)
+  npx phyll setup codex                Connect Phyll to Codex (or claude, cursor, windsurf, gemini)
   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
+  login              Use your account on this computer: allow it in the browser
+  login <key>        Or use it with a key
+  setup <agent>      Connect Phyll to codex, claude, cursor, windsurf or gemini, and install the
+                     browser it uses. setup other prints the settings for any agent with MCP
   status             Your plan and the reviews left
   account            Open your account on the site, signed in: reports, keys and plan
   pro                Subscribe to Phyll Pro
@@ -25,17 +32,48 @@ Commands:
   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.
+Options: --server <address> for signup and login, --lang <code> for signup, --format json or badge for scan.
 
 The AI work runs in your agent, on your own plan. Phyll's engine sends the method and keeps the reports.
+Every command, with examples: https://agentphyll.com/commands
 `;
 
+// Opens a page in the person's browser, best effort, since the address is printed too. Only the
+// server's own connect page opens, so an odd answer never reaches the shell.
+function openBrowser(url, server) {
+  if (!url.startsWith(`${server}/connect/`) || !/^[\w:/.-]+$/.test(url)) return;
+  const [command, args] =
+    process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => {}).unref();
+  } catch {
+    // No browser here; the address above is enough.
+  }
+}
+
 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 });
 }
 
+// After a scan: the full review, which sees what the source cannot show, and the badge once the
+// index is low enough to show off.
+export function scanNext(index) {
+  const lines = [
+    "",
+    "Next: a full review opens the app as a first-time user, checks these hints along with what",
+    "only the running app shows, and can fix what it finds without changing your design.",
+    "  npx phyll setup codex      (or claude, cursor, windsurf, gemini)",
+    "  then ask your agent: review my app at http://localhost:3000",
+  ];
+  if (index !== null && index !== undefined && index <= 25) lines.push("Show the index in your README: npx phyll scan --format badge");
+  return `${lines.join("\n")}\n`;
+}
+
+// A README badge with the static index. The engine draws it, and it links to Phyll.
+export const badgeMarkdown = (index, server) => `[![Phyll AI tell index: ${index}/100](${server}/badge/index/${index}.svg)](${server})`;
+
 export async function main(argv, io = {}) {
   const out = io.stdout ?? process.stdout;
   const err = io.stderr ?? process.stderr;
@@ -48,6 +86,28 @@ export async function main(argv, io = {}) {
     return code;
   };
   const client = (server, key) => engineClient({ server, key, version: VERSION, fetchImpl });
+  const sleep = io.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+
+  // Without a key, the terminal asks the site for a code, the person allows this computer in the
+  // browser, signed in, and the terminal's next check brings a key of its own.
+  async function loginInBrowser(server) {
+    const started = await client(server).deviceStart((io.hostname ?? hostname)());
+    if (!started.ok) return fail(started.json.message ?? `Phyll answered ${started.status}.`);
+    const { deviceCode, userCode, url, interval = 2, expiresIn = 600 } = started.json;
+    write(`To use your account on this computer, allow it in the browser:\n${url}\nCheck that the page shows the code ${userCode}. Waiting...\n`);
+    await (io.openBrowser ?? openBrowser)(url, server);
+    const deadline = Date.now() + Math.min(Number(expiresIn) || 600, 900) * 1000;
+    while (Date.now() < deadline) {
+      await sleep(Math.max(1, Number(interval) || 2) * 1000);
+      const answer = await client(server).deviceCheck(deviceCode);
+      if (answer.status === 202) continue;
+      if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
+      saveCredentials({ server, key: answer.json.key }, env);
+      write(`Signed in as ${answer.json.email}, on the ${answer.json.plan === "pro" ? "Phyll Pro" : "free"} plan. The key is saved in ${credentialsPath(env)}.\n`);
+      return 0;
+    }
+    return fail("the code expired before it was allowed. Run npx phyll login again.");
+  }
   const [command, ...rest] = argv;
 
   try {
@@ -72,15 +132,16 @@ export async function main(argv, io = {}) {
         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`);
+        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      (or claude, cursor, windsurf, gemini)\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);
+        if (positionals.length > 1) return fail("give one key, such as npx phyll login phyll_..., or none to sign in with the browser", 2);
         const server = String(values.server ?? loadCredentials(env).server ?? "").replace(/\/+$/, "");
         if (!server) return fail("give the address of the Phyll server with --server", 2);
+        if (!positionals.length) return await loginInBrowser(server);
         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);
@@ -95,7 +156,7 @@ export async function main(argv, io = {}) {
 
       case "status": {
         const { server, key } = loadCredentials(env);
-        if (!key) return fail("no account on this computer yet. Run npx phyll signup you@example.com");
+        if (!key) return fail("no account on this computer yet. Run npx phyll login, or 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;
@@ -110,7 +171,7 @@ export async function main(argv, io = {}) {
 
       case "account": {
         const { server, key } = loadCredentials(env);
-        if (!key) return fail(`no account on this computer yet. Run npx phyll signup you@example.com, or sign in at ${server}/login`);
+        if (!key) return fail("no account on this computer yet. Run npx phyll login, or npx phyll signup you@example.com");
         const answer = await client(server, key).loginLink();
         if (!answer.ok) return fail(answer.json.message ?? `Phyll answered ${answer.status}.`);
         write(`Open your account, already signed in. The link works once, for 15 minutes:\n${answer.json.url}\n`);
@@ -120,7 +181,7 @@ export async function main(argv, io = {}) {
       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");
+        if (!key) return fail("no account on this computer yet. Run npx phyll login, or 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`);
@@ -129,18 +190,30 @@ export async function main(argv, io = {}) {
 
       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);
+        if (![...AGENTS, "other"].includes(agent)) {
+          return fail("say which agent to connect: npx phyll setup codex, claude, cursor, windsurf or gemini. For any other agent with MCP: npx phyll setup other", 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 {
+        } else if (agent === "claude") {
           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`,
           );
+        } else if (agent === "other") {
+          write(`Add Phyll to your agent's MCP servers, then restart the agent:\n${mcpJson(command)}\n`);
+        } else {
+          const { name, path } = JSON_AGENTS[agent];
+          const file = join(io.home ?? homedir(), ...path);
+          write(
+            writeJsonConfig(file, command)
+              ? `Phyll is connected to ${name} in ${file}. Restart ${name} so it loads the connector.\n`
+              : `${file} is not plain JSON, so Phyll left it as it was. Add this to its mcpServers, then restart ${name}:\n${mcpJson(command)}\n`,
+          );
         }
         if (!(await (io.ensureBrowser ?? ensureBrowser)({ write }))) return fail("the browser could not be installed. Run: npx playwright install chromium");
         write(
@@ -153,9 +226,14 @@ export async function main(argv, io = {}) {
 
       case "scan": {
         const { values, positionals } = options(rest, { format: { type: "string" } });
+        const format = values.format ?? "text";
+        if (!["text", "json", "badge"].includes(format)) return fail("the format is text, json or badge", 2);
         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));
+        if (format === "json") write(`${JSON.stringify(result, null, 2)}\n`);
+        else if (format === "text") write(`${formatText(result)}${scanNext(result.staticIndex)}`);
+        else if (result.staticIndex === null) return fail("there is no index to show: the scan found no files it reads");
+        else write(`${badgeMarkdown(result.staticIndex, loadCredentials(env).server)}\n`);
         return 0;
       }
 

package/src/engine.mjs

@@ -37,5 +37,9 @@ export function engineClient({ server, key = null, version = "0", fetchImpl = gl
     checkout: () => call("POST", "/v1/billing/checkout"),
     portal: () => call("POST", "/v1/billing/portal"),
     loginLink: () => call("POST", "/v1/login-link"),
+    // Signing in from the browser: the terminal asks for a code, then checks until the person
+    // allows it on the site.
+    deviceStart: (name) => call("POST", "/v1/device", { name }),
+    deviceCheck: (deviceCode) => call("POST", "/v1/device/token", { deviceCode }),
   };
 }

package/src/review.mjs

@@ -100,7 +100,7 @@ export class Connector {
         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}`);
+        throw new Error(missing ? "the browser is not installed. Ask the person to run npx phyll setup once, with the name of their agent, such as npx phyll setup codex." : `the browser did not start: ${error.message}`);
       }
       review.browser = session;
     }

package/src/setup.mjs

@@ -1,10 +1,11 @@
-// 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.
+// Connects Phyll to the person's agent: an MCP server entry in Codex's config.toml, a
+// `claude mcp add` for Claude Code, or an entry in the JSON file Cursor, Windsurf or Gemini CLI
+// read, 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 { dirname, 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
@@ -43,6 +44,38 @@ export function writeCodexConfig(command, env = process.env) {
   return file;
 }
 
+// Agents that keep their MCP servers under "mcpServers" in a JSON file in the home folder.
+export const JSON_AGENTS = {
+  cursor: { name: "Cursor", path: [".cursor", "mcp.json"] },
+  windsurf: { name: "Windsurf", path: [".codeium", "windsurf", "mcp_config.json"] },
+  gemini: { name: "Gemini CLI", path: [".gemini", "settings.json"] },
+};
+
+const serverEntry = (command) => ({ command: command[0], args: command.slice(1) });
+
+// The entry to paste into the MCP settings of any other agent.
+export const mcpJson = (command) => JSON.stringify({ mcpServers: { phyll: serverEntry(command) } }, null, 2);
+
+// Adds phyll to mcpServers and keeps the rest of the file as it was. A file that is not plain
+// JSON, such as one with comments, is left alone and the caller shows the entry to paste.
+export function writeJsonConfig(file, command) {
+  let config = {};
+  if (existsSync(file)) {
+    const text = readFileSync(file, "utf8").replace(String.fromCharCode(0xfeff), "").trim();
+    try {
+      config = text ? JSON.parse(text) : {};
+    } catch {
+      return false;
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) return false;
+  }
+  const servers = config.mcpServers && typeof config.mcpServers === "object" && !Array.isArray(config.mcpServers) ? config.mcpServers : {};
+  config.mcpServers = { ...servers, phyll: serverEntry(command) };
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+  return true;
+}
+
 const quote = (arg) => (/[\s"]/.test(arg) ? `"${arg.replaceAll('"', '\\"')}"` : arg);
 
 export function registerClaude(command, run = spawnSync) {
@@ -54,16 +87,23 @@ export function registerClaude(command, run = spawnSync) {
   return { ok: true };
 }
 
+// Playwright's own command line. The package does not export "./cli", so it is found through
+// the package.json, which it does export, and the file its "bin" names.
+export function playwrightCli(require = createRequire(import.meta.url)) {
+  const manifest = require.resolve("playwright/package.json");
+  const { bin } = JSON.parse(readFileSync(manifest, "utf8"));
+  return join(dirname(manifest), typeof bin === "string" ? bin : bin.playwright);
+}
+
 // Opens Chromium once; when Playwright says it is missing, installs it.
-export async function ensureBrowser({ write = () => {}, run = spawnSync } = {}) {
-  const { chromium } = await import("playwright");
+export async function ensureBrowser({ write = () => {}, run = spawnSync, chromium = null } = {}) {
+  const browser = chromium ?? (await import("playwright")).chromium;
   try {
-    await (await chromium.launch()).close();
+    await (await browser.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;
+  return run(process.execPath, [playwrightCli(), "install", "chromium"], { stdio: "inherit" }).status === 0;
 }