phyll 0.4.1

package/skill/schema/config.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/carlosphyll/phyll/blob/main/skills/phyll/schema/config.schema.json",
+  "title": "Phyll project configuration",
+  "description": "Optional settings in .phyll/config.json at the root of the reviewed project. Every field is optional.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "language": {
+      "description": "Language for the report. Defaults to the language of the product's interface.",
+      "type": "string"
+    },
+    "entryUrl": {
+      "description": "Where the running app can be opened, such as http://localhost:3000.",
+      "type": "string"
+    },
+    "startCommand": {
+      "description": "Command that starts the app, such as npm run dev.",
+      "type": "string"
+    },
+    "endUser": {
+      "description": "Who uses the product, in one sentence.",
+      "type": "string"
+    },
+    "coreJobs": {
+      "description": "The two or three things the end user comes to do.",
+      "type": "array",
+      "items": { "type": "string" },
+      "maxItems": 5
+    },
+    "ignore": {
+      "description": "Globs, relative to the project root, that the static scan skips.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "telemetry": {
+      "description": "Opt in to sending anonymous numbers (tool version, mode, index, counts) to cloud.apiUrl. Off by default, and nothing is sent without a URL.",
+      "type": "boolean"
+    },
+    "cloud": {
+      "description": "Phyll Cloud settings. The service does not exist yet; with both fields empty nothing leaves the machine. PHYLL_API_URL and PHYLL_API_KEY override these values.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "apiUrl": { "type": "string" },
+        "apiKey": { "type": "string" }
+      }
+    }
+  }
+}

package/skill/schema/tells.schema.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/carlosphyll/phyll/blob/main/skills/phyll/schema/tells.schema.json",
+  "title": "Phyll tell catalog",
+  "description": "Tells are recurring signs that an interface or flow was produced by default choices of a code generator. Each tell has metadata for scoring and optional static detectors.",
+  "type": "object",
+  "required": ["version", "tells"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "tells": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/tell" }
+    }
+  },
+  "$defs": {
+    "category": {
+      "description": "File categories a detector reads. markup: html, jsx, tsx, vue, svelte, astro, mdx. script: js, ts, mjs, cjs. style: css, scss, sass, less.",
+      "enum": ["markup", "script", "style"]
+    },
+    "categories": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/category" }
+    },
+    "tell": {
+      "type": "object",
+      "required": ["id", "name", "dimension", "severity", "weight", "cap", "detection", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[PFALCS]\\d{2}$" },
+        "name": { "type": "string", "minLength": 3, "maxLength": 80 },
+        "dimension": { "enum": ["purpose", "flow", "actions", "look", "copy", "states"] },
+        "kind": {
+          "description": "function: the tell gets in the way of using the product, counts in the AI tell index and fix mode fixes it. style: the tell is about the generated look; it is reported as a style note, counts only in the style index, and fix mode leaves it alone unless the owner asks. Defaults to function.",
+          "enum": ["function", "style"]
+        },
+        "severity": {
+          "description": "Typical severity when the tell shows up on a core job. A finding can raise or lower it.",
+          "enum": ["blocker", "major", "minor", "polish"]
+        },
+        "weight": {
+          "description": "How much the tell counts in the AI tell index: 1 cosmetic, 2 noticeable, 3 gets in the way of the job.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3
+        },
+        "cap": {
+          "description": "Number of hits at which the tell counts in full.",
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 20
+        },
+        "detection": {
+          "description": "static: source patterns are enough. dynamic: needs the running app. both: source gives a hint the reviewer confirms in the app.",
+          "enum": ["static", "dynamic", "both"]
+        },
+        "summary": { "type": "string", "minLength": 10, "maxLength": 240 },
+        "detectors": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/detector" }
+        },
+        "examples": {
+          "description": "Snippets the detectors must match (hit) and must not match (miss). The test suite runs them.",
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["hit", "miss"],
+          "properties": {
+            "hit": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/example" } },
+            "miss": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/example" } }
+          }
+        }
+      }
+    },
+    "example": {
+      "description": "Source code, read as a .jsx file unless a file name with another extension is given.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "required": ["code", "file"],
+          "additionalProperties": false,
+          "properties": {
+            "code": { "type": "string", "minLength": 1 },
+            "file": { "type": "string", "pattern": "\\.[a-z]+$" }
+          }
+        }
+      ]
+    },
+    "detector": {
+      "oneOf": [
+        { "$ref": "#/$defs/regexDetector" },
+        { "$ref": "#/$defs/classComboDetector" },
+        { "$ref": "#/$defs/phraseDetector" },
+        { "$ref": "#/$defs/metricDetector" }
+      ]
+    },
+    "skipIf": {
+      "description": "Project traits that switch the detector off. darkTheme: most backgrounds in the source are dark, so light text classes are expected.",
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["darkTheme"] }
+    },
+    "regexDetector": {
+      "type": "object",
+      "required": ["kind", "pattern"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "regex" },
+        "pattern": { "type": "string", "minLength": 1 },
+        "flags": { "type": "string", "pattern": "^[imsu]*$" },
+        "in": { "$ref": "#/$defs/categories" },
+        "skipIf": { "$ref": "#/$defs/skipIf" },
+        "note": { "type": "string" }
+      }
+    },
+    "classComboDetector": {
+      "type": "object",
+      "required": ["kind", "all"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "classCombo" },
+        "all": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "none": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "in": { "$ref": "#/$defs/categories" },
+        "note": { "type": "string" }
+      }
+    },
+    "phraseDetector": {
+      "type": "object",
+      "required": ["kind", "phrases"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "phrase" },
+        "phrases": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 2 } },
+        "in": { "$ref": "#/$defs/categories" },
+        "note": { "type": "string" }
+      }
+    },
+    "metricDetector": {
+      "type": "object",
+      "required": ["kind", "metric"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "const": "metric" },
+        "metric": { "enum": ["longForms", "modals"] },
+        "min": { "type": "integer", "minimum": 1 },
+        "note": { "type": "string" }
+      }
+    }
+  }
+}

package/skill/scripts/capture.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+// Phyll capture: screenshots and probe measurements for each route, at desktop and phone sizes.
+// Optional. Use it when the host agent has no browser tool, or to capture many screens at once.
+// Needs Playwright in the reviewed project (npm i -D playwright && npx playwright install chromium).
+//
+//   node capture.mjs --url http://localhost:5173 [--routes "/,/flows"] [--scan scan.json]
+//                    [--out dir] [--viewports desktop,mobile] [--no-probe] [--wait 800]
+//                    [--max-height 5000] [--no-full-page]
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { fail, isMain } from "./lib/cli.mjs";
+import { NAME, VERSION } from "./lib/version.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const VIEWPORTS = Object.freeze({
+  desktop: { viewport: { width: 1440, height: 900 }, deviceScaleFactor: 1 },
+  mobile: { viewport: { width: 390, height: 844 }, deviceScaleFactor: 1, isMobile: true, hasTouch: true },
+});
+
+// File name for a route. The query string stays in, so /new and /new?template=link do not collide.
+export function routeSlug(route) {
+  const [pathAndQuery] = String(route ?? "").split("#");
+  const [path, query = ""] = pathAndQuery.split("?");
+  const base = path.replace(/^\/+|\/+$/g, "").replace(/\.html?$/i, "");
+  const slug = [base, query].filter(Boolean).join("-").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+  return slug || "home";
+}
+
+// Gives each route a unique slug, numbering repeats: flows, flows-2.
+export function uniqueSlugs(routes) {
+  const seen = new Map();
+  return routes.map((route) => {
+    const slug = routeSlug(route);
+    const count = (seen.get(slug) ?? 0) + 1;
+    seen.set(slug, count);
+    return count === 1 ? slug : `${slug}-${count}`;
+  });
+}
+
+// Routes the browser can open as they are: no :params, [params], wildcards or (groups).
+export function staticRoutes(routes) {
+  return [...new Set(routes.filter((r) => typeof r === "string" && r.startsWith("/") && !/[:*[\]()]/.test(r)))];
+}
+
+export function parseCaptureArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    allowPositionals: false,
+    options: {
+      url: { type: "string" },
+      routes: { type: "string" },
+      scan: { type: "string" },
+      out: { type: "string" },
+      viewports: { type: "string", default: "desktop,mobile" },
+      "no-probe": { type: "boolean", default: false },
+      "no-full-page": { type: "boolean", default: false },
+      wait: { type: "string", default: "800" },
+      "max-height": { type: "string", default: "5000" },
+    },
+  });
+  if (!values.url) throw new Error("--url is required, for example --url http://localhost:5173");
+  const viewports = values.viewports.split(",").map((v) => v.trim()).filter(Boolean);
+  for (const v of viewports) {
+    if (!VIEWPORTS[v]) throw new Error(`unknown viewport ${v}; use ${Object.keys(VIEWPORTS).join(" or ")}`);
+  }
+  let routes = null;
+  if (values.routes) {
+    routes = [];
+    for (const raw of values.routes.split(",").map((r) => r.trim()).filter(Boolean)) {
+      // Git Bash on Windows rewrites arguments that start with "/" into Windows paths.
+      if (/^[A-Za-z]:[\\/]/.test(raw)) {
+        process.stderr.write(
+          `phyll: skipped route "${raw}", which looks like a path rewritten by Git Bash. ` +
+            "Run with MSYS_NO_PATHCONV=1, or write routes without the leading slash (dashboard instead of /dashboard).\n",
+        );
+        continue;
+      }
+      routes.push(raw.startsWith("/") ? raw : `/${raw}`);
+    }
+  }
+  return {
+    url: values.url,
+    routes,
+    scan: values.scan ?? null,
+    out: values.out ?? null,
+    viewports,
+    probe: !values["no-probe"],
+    fullPage: !values["no-full-page"],
+    wait: Number(values.wait) || 0,
+    maxHeight: Number(values["max-height"]) || 5000,
+  };
+}
+
+// Looks for Playwright in the reviewed project first, then next to this script.
+export async function loadPlaywright(cwd = process.cwd()) {
+  const requires = [createRequire(join(cwd, "package.json")), createRequire(import.meta.url)];
+  for (const req of requires) {
+    for (const name of ["playwright", "@playwright/test", "playwright-core"]) {
+      try {
+        const mod = await import(pathToFileURL(req.resolve(name)).href);
+        const api = mod.chromium ? mod : mod.default;
+        if (api?.chromium) return api;
+      } catch {
+        // try the next candidate
+      }
+    }
+  }
+  return null;
+}
+
+const timestamp = () => new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+const clip = (s) => String(s ?? "").replace(/\s+/g, " ").trim().slice(0, 300);
+
+async function main() {
+  let args;
+  try {
+    args = parseCaptureArgs(process.argv.slice(2));
+  } catch (error) {
+    fail(error.message, 2);
+  }
+
+  const pw = await loadPlaywright();
+  if (!pw) {
+    process.stderr.write(
+      [
+        "phyll: Playwright is not installed in this project.",
+        "Install it with:",
+        "  npm i -D playwright",
+        "  npx playwright install chromium",
+        "Or use your agent's browser tool and run probe.js in the page (see references/walkthrough.md).",
+        "",
+      ].join("\n"),
+    );
+    process.exit(3);
+  }
+
+  let routes = args.routes;
+  if (!routes && args.scan) {
+    const scan = JSON.parse(readFileSync(resolve(args.scan), "utf8"));
+    routes = staticRoutes((scan.structure?.routes ?? []).map((r) => r.path));
+  }
+  routes = staticRoutes(routes?.length ? routes : ["/"]);
+
+  const out = resolve(args.out ?? join(".phyll", "reports", timestamp()));
+  mkdirSync(join(out, "screens"), { recursive: true });
+  if (args.probe) mkdirSync(join(out, "probe"), { recursive: true });
+  const probeSource = readFileSync(join(HERE, "probe.js"), "utf8");
+
+  const slugs = uniqueSlugs(routes);
+  const pages = [];
+  const browser = await pw.chromium.launch();
+  try {
+    for (const name of args.viewports) {
+      const context = await browser.newContext(VIEWPORTS[name]);
+      const page = await context.newPage();
+      const consoleErrors = [];
+      page.on("console", (m) => {
+        if (m.type() === "error") consoleErrors.push(clip(m.text()));
+      });
+      page.on("pageerror", (e) => consoleErrors.push(clip(e.message)));
+
+      for (const [i, route] of routes.entries()) {
+        const url = new URL(route, args.url).href;
+        const slug = slugs[i];
+        const entry = { route, viewport: name, url, status: null };
+        try {
+          let response;
+          try {
+            response = await page.goto(url, { waitUntil: "networkidle", timeout: 20000 });
+          } catch {
+            response = await page.goto(url, { waitUntil: "load", timeout: 20000 });
+          }
+          entry.status = response?.status() ?? null;
+          if (args.wait) await page.waitForTimeout(args.wait);
+
+          const shot = `screens/${name}-${slug}.png`;
+          const height = await page.evaluate(() => document.documentElement.scrollHeight);
+          const options = { path: join(out, shot), fullPage: args.fullPage };
+          if (args.fullPage && height > args.maxHeight) {
+            options.clip = { x: 0, y: 0, width: VIEWPORTS[name].viewport.width, height: args.maxHeight };
+          }
+          await page.screenshot(options);
+          entry.screenshot = shot;
+
+          if (args.probe) {
+            const data = await page.evaluate(probeSource);
+            const probePath = `probe/${name}-${slug}.json`;
+            writeFileSync(join(out, probePath), JSON.stringify(data, null, 2) + "\n");
+            entry.probe = probePath;
+          }
+        } catch (error) {
+          entry.error = clip(error.message);
+        }
+        entry.consoleErrors = consoleErrors.splice(0);
+        pages.push(entry);
+      }
+      await context.close();
+    }
+  } finally {
+    await browser.close();
+  }
+
+  const manifest = {
+    tool: { name: NAME, version: VERSION },
+    createdAt: new Date().toISOString(),
+    baseUrl: args.url,
+    viewports: args.viewports,
+    pages,
+  };
+  writeFileSync(join(out, "capture.json"), JSON.stringify(manifest, null, 2) + "\n");
+
+  const failed = pages.filter((p) => p.error);
+  const noisy = pages.filter((p) => p.consoleErrors?.length);
+  process.stdout.write(`Captured ${pages.length - failed.length} of ${pages.length} screens into ${out}\n`);
+  for (const p of failed) process.stdout.write(`  could not capture ${p.viewport} ${p.route}: ${p.error}\n`);
+  if (noisy.length) process.stdout.write(`  ${noisy.length} screens logged JavaScript errors; see capture.json\n`);
+  if (!existsSync(join(out, "capture.json"))) process.exit(1);
+}
+
+if (isMain(import.meta.url)) main();

package/skill/scripts/lib/cli.mjs

@@ -0,0 +1,16 @@
+// Small helpers shared by the command-line scripts.
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// True when the module at metaUrl is the script Node was asked to run.
+export function isMain(metaUrl) {
+  if (!process.argv[1]) return false;
+  const self = fileURLToPath(metaUrl);
+  const entry = resolve(process.argv[1]);
+  return process.platform === "win32" ? self.toLowerCase() === entry.toLowerCase() : self === entry;
+}
+
+export function fail(message, code = 1) {
+  process.stderr.write(`phyll: ${message}\n`);
+  process.exit(code);
+}

package/skill/scripts/lib/config.mjs

@@ -0,0 +1,19 @@
+// Reads .phyll/config.json from the reviewed project. Every field is optional.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CONFIG_DIR = ".phyll";
+export const CONFIG_FILE = "config.json";
+
+export function configPath(projectDir) {
+  return join(projectDir, CONFIG_DIR, CONFIG_FILE);
+}
+
+export function readConfigFile(path) {
+  if (!path || !existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`Could not read ${path}: ${error.message}`);
+  }
+}