phyll 0.4.4 → 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.4",
-  "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.4",
+  "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.4";
+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,25 +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 { hostname } from "node:os";
+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              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 or claude, and install the browser it uses
+  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
@@ -28,7 +32,7 @@ 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
@@ -53,6 +57,23 @@ 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;
@@ -111,7 +132,7 @@ 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;
       }
 
@@ -169,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(
@@ -193,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/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,5 +1,6 @@
-// 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";
@@ -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) {