diff --git a/AGENTS.md b/AGENTS.md index edf0ff38..432c43d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,14 +14,14 @@ Default mode is `observe` (report only); `guard` is opt-in; `heal` is experiment | path | what | |---|---| -| `packages/runtime/` | the library: `src/` (incl. `auto.ts`, `cdn/`, `situation/`, `decide/`, `model/`, `devtools/`, `visual/` (measured visual checks: `start.ts` is the first-load stub, the rest is the lazy chunk), `analytics/` (interaction analytics, opt-in: `start.ts` stub, `index.ts` lazy chunk; `docs/runtime/ANALYTICS.md`), `agent/` (`@genclass/runtime/agent`, the coding-agent link: recording, delivery schedules, the bridge link; its own entry, never in the first load; `docs/runtime/AGENT.md`)), `test/` (vitest; `test/install/`, `test/browser/`, `test/browser/visual/` (Playwright, the CI `visual-browser` job)), `bin/` (CLI: `init`, `remove`, `login`, `connect`, `whoami`, `logout`, `dashboard`, `scan`/`audit`, `fetch-model`, `info`), `CHANGELOG.md`, `TELEMETRY.md`, `INTERCEPTION.md` | +| `packages/runtime/` | the library: `src/` (incl. `auto.ts`, `cdn/`, `situation/`, `decide/`, `model/`, `devtools/`, `visual/` (measured visual checks: `start.ts` is the first-load stub, the rest is the lazy chunk), `analytics/` (interaction analytics, opt-in: `start.ts` stub, `index.ts` lazy chunk; `docs/runtime/ANALYTICS.md`), `consent.ts` (the lazy chunk that applies `GenClass.consent(...)` under `consent: "pending"`; the gates themselves are in the first load), `agent/` (`@genclass/runtime/agent`, the coding-agent link: recording, delivery schedules, the bridge link; its own entry, never in the first load; `docs/runtime/AGENT.md`)), `test/` (vitest; `test/install/`, `test/browser/`, `test/browser/visual/` (Playwright, the CI `visual-browser` job)), `bin/` (CLI: `init`, `remove`, `login`, `connect`, `whoami`, `logout`, `dashboard`, `scan`/`audit`, `fetch-model`, `info`), `CHANGELOG.md`, `TELEMETRY.md`, `INTERCEPTION.md` | | `packages/runtime-model/` | the data-only model package (`files/` is gitignored, filled at release) and `MODEL_CARD.md` | | `sim/` | deterministic training-data simulator driving the real runtime (`SEPARABILITY.md`, `README.md`) | | `realapps/` | 128 real apps run in headless Chromium with the real runtime: training rows and the never-worse sweep | | `training/` | vocabulary pruning, curriculum (`curriculum/rt.py` mirrors the runtime's situation renderer), Azure training, ONNX export, `EVAL.md` | | `demos/` | six demo apps with a chaos backend and Playwright trials; `bench/heal/` runs them per mode | | `packages/mcp/` | `@genclass/mcp`: the MCP server for coding agents (bridge on 127.0.0.1:47357, store, explore verdicts, replays, regression-test generation, 9 tools incl. `genclass_scan`, which runs the runtime CLI's `scan`); no runtime deps; `test/e2e/race.e2e.mjs` is the real-browser check (not in CI's main job). `plugin/` is the Claude Code plugin (also an Agent Plugins package); `server.json`, the plugin, `.claude-plugin/`, `.cursor-plugin/`, `gemini-extension.json`, `llms-install.md` and the READMEs pin its version (`npm run sync -w @genclass/mcp` after a version bump; `test/manifests.test.ts` fails otherwise); `scripts/plugin-repo.mjs` assembles genclass-dev/genclass-plugin (the plugin at a repository root with its marketplace files and the released server vendored from npm under `server/`, which `.mcp.json` and the hook there run with `node` from `${CLAUDE_PLUGIN_ROOT}`, for the Claude directory's 50 MiB archive limit and its holds on `npx` launchers and lockfiles, Codex, Gemini CLI, `gh skill`; that repository re-syncs daily from main and is never edited by hand) | -| `packages/cli/` | `genclass` (`npx genclass`): the one way to set GenClass up, `genclass dashboard` (one app, whole, in the terminal) and `genclass suggest`. Plain ESM `.mjs` in `src/` (`main.mjs` names the command to the runtime CLI's modules, which it reuses from `packages/runtime/bin/lib`: sign-in, project detection, `init`; `state.mjs` reads the seven steps of a project from disk and from genclass.dev (account, runtime, dashboard, test workflow, GitHub App, coding agent, suggestions); `setup.mjs` and `actions.mjs` walk them, one Enter each, in a short view that `d` expands; `art.mjs` is the opening wordmark; `app.mjs` is `genclass dashboard`, which reads `GET /api/cli/app` (the dashboard's own numbers; a CLI session approved before the approval page said so is asked to sign in again); `views.mjs` is the rest of the dashboard from the same answer (`problems`, `analytics`, `events`, `health`, `agent`, `report`); `kinds.mjs` holds the dashboard page's own texts for each kind and its fix prompts (a test reads `telemetry-worker/src/pages.ts` and fails when a sentence differs); `fix.mjs` hands a problem to the person's coding agent with that prompt (it starts `claude`, `codex`, `cursor-agent` or `gemini` on a key press, or copies or prints; GenClass changes no code); `ask.mjs` is a question to genclass.dev's model; `manage.mjs` is the account's side (`apps`, `plan`, `team`, `connections`, `export`, `funnels`, `agent link`) over the routes a newer approval lists, with `session.mjs` saying why a call was refused and what to do next; `home.mjs` is the prompt the command stays open on after the walk (a command, or a sentence that is a question); `name.mjs` makes every screen say `genclass` once it is installed, `npx genclass` until then; `suggest/` measures the repository and the live site (`repo.mjs`, `site.mjs`), runs the catalog of checks (`checks.mjs`) and asks genclass.dev to order and explain what failed (`digest.mjs` is everything that is sent); `tui.mjs` is the look); `build.mjs` bundles it into one file with no dependencies (`dist/genclass.mjs`) with the runtime and MCP versions it installs; tests in `test/` (`server.test.ts` runs it against the collector in process). The server side is `telemetry-worker/src/cli.ts`, `suggest.ts` (rule 11) and `ask.ts` (rule 12). On npm as `genclass` since 2026-11-12, released by `release-cli.yml` on a `cli-v*` tag; it is the first install line the README names | +| `packages/cli/` | `genclass` (`npx genclass`): the one way to set GenClass up, `genclass dashboard` (one app, whole, in the terminal) and `genclass suggest`. Plain ESM `.mjs` in `src/` (`main.mjs` names the command to the runtime CLI's modules, which it reuses from `packages/runtime/bin/lib`: sign-in, project detection, `init`; `state.mjs` reads the seven steps of a project from disk and from genclass.dev (account, runtime, dashboard, test workflow, GitHub App, coding agent, suggestions); `setup.mjs` and `actions.mjs` walk them, one Enter each, in a short view that `d` expands; `art.mjs` is the opening wordmark; `app.mjs` is `genclass dashboard`, which reads `GET /api/cli/app` (the dashboard's own numbers; a CLI session approved before the approval page said so is asked to sign in again); `views.mjs` is the rest of the dashboard from the same answer (`problems`, `analytics`, `events`, `health`, `agent`, `report`); `kinds.mjs` holds the dashboard page's own texts for each kind and its fix prompts (a test reads `telemetry-worker/src/pages.ts` and fails when a sentence differs); `fix.mjs` hands a problem to the person's coding agent with that prompt (it starts `claude`, `codex`, `cursor-agent` or `gemini` on a key press, or copies or prints; GenClass changes no code); `ask.mjs` is a question to genclass.dev's model; `manage.mjs` is the account's side (`apps`, `plan`, `team`, `connections`, `export`, `funnels`, `agent link`) over the routes a newer approval lists, with `session.mjs` saying why a call was refused and what to do next; `home.mjs` is the prompt the command stays open on after the walk (a command, or a sentence that is a question); `name.mjs` makes every screen say `genclass` once it is installed, `npx genclass` until then; `privacy.mjs` is `genclass privacy` (what the project's setup sends and keeps, read from its files; free, no network), `doctor.mjs` is `genclass doctor` (every part's health, `--fix` for GenClass's own lines: the MCP pin, the skill, the dev-only agent link where `agentlink.mjs` plans it, which is every setup `init` writes but Angular, Nuxt, a plain script tag, another bundler or a setup by hand), `update.mjs` the once-a-day newer-release line; `agentlink.mjs` plans the dev-only `connectAgent` link the Coding agent step and `doctor --fix` write (in a `genclass:init` block `remove` takes out); `flake.mjs` is `genclass flake` (the project's Playwright suite through `@genclass/playwright` once in the natural order and once per seed: passed, racy, flaky or broken per test, from the race files; free, local); `suggest/` measures the repository and the live site (`repo.mjs`, `site.mjs`, including the shipped scripts' secret keys and the installed framework versions), runs the catalog of checks (`checks.mjs`) and asks genclass.dev to order and explain what failed (`digest.mjs` is everything that is sent); `tui.mjs` is the look); `build.mjs` bundles it into one file with no dependencies (`dist/genclass.mjs`) with the runtime and MCP versions it installs; tests in `test/` (`server.test.ts` runs it against the collector in process). The server side is `telemetry-worker/src/cli.ts`, `suggest.ts` (rule 11) and `ask.ts` (rule 12). On npm as `genclass` since 2026-11-12, released by `release-cli.yml` on a `cli-v*` tag; it is the first install line the README names | | `packages/sv/` | `@genclass/sv`: the Svelte CLI community add-on (`npx sv add @genclass`): adds the runtime, the `/auto` import first in `src/hooks.client`, the dev-only overlay and (default) the telemetry opt-out meta in `src/app.html`, all with the `genclass:init` marker so `remove` undoes it; bundles `@sveltejs/sv-utils`, `sv` is a peer; `test/e2e/` runs sv's add-on harness (pnpm, Chromium) | | `packages/playwright/` | `@genclass/playwright`: the fixture (`src/fixture.ts`, `install.ts`, `page.ts`, `chaos.ts`, `races.ts`: puts the runtime's script-tag build on every `page` in observe mode with telemetry off, seeded chaos that holds matched fetch/XHR requests with `page.route` and `route.fallback()`, witnesses through the agent entry with every hold off, one `genclass-races/1` file per test in `test-results/genclass/`, with where the test is declared (`location`), which the GitHub App's inline comments use) and the reporter + pure summariser that read those files and write `genclass-report.md` for the PR; peer deps only (`@playwright/test`, `@genclass/runtime`); zero-edit mode (`src/register.ts`, `wrap.ts`, `worker.ts`, `run.ts`: the command `genclass-playwright-run` gives an unmodified suite the same instrumentation by wrapping public Playwright objects in the worker process; `docs/github-app/workflows/genclass.yml` is the one file a repository adds); `test/e2e/run.mjs` is the real-browser check of both (its own workflow) | | `packages/nuxt/`, `packages/astro/` | `@genclass/nuxt` (a Nuxt module, `@nuxt/kit`, built with `@nuxt/module-builder`) and `@genclass/astro` (an Astro integration, `injectScript("page", ...)`): from options `{ mode, token?, telemetry?, devtools? }` they generate the runtime's own one line (`/auto` or `/auto/guard`) plus a `window.GENCLASS_CONFIG` module imported before it; browser only, nothing on the server; `@genclass/runtime` is a peer dependency. The generated code is pure (`src/source.ts`, `src/index.ts`) and the tests check it exactly, then build one fixture app. Workflow: `integrations.yml` (Node 24) | @@ -62,7 +62,9 @@ the e2e needs the runtime built too: `node packages/playwright/test/e2e/run.mjs` `packages/cli/` (`genclass`, the one command) has its own workflow, `cli.yml` (never blocks `ci.yml`): `npm run build -w genclass && (cd packages/cli && npx vitest run)`; the tests need no network (genclass.dev is the collector in process or a stand-in, the model and the sites are stand-ins). Its sources are plain `.mjs` and are not -type-checked. +type-checked. The real-browser check of `genclass flake` is not in `cli.yml` (it needs Chromium; about 40 s on the +development Mac): `npm run build -w @genclass/runtime && npm run build -w @genclass/playwright && npm run build -w genclass && node packages/cli/test/e2e/flake.e2e.mjs`; +its numbers are in RESULTS.md section 30. `packages/sv/` (`@genclass/sv`, the Svelte CLI add-on) has its own workflow, `sv-addon.yml` (never blocks `ci.yml`): `npm run typecheck -w @genclass/sv && npm run build -w @genclass/sv && (cd packages/sv && npx vitest run --project unit)`; diff --git a/docs/runtime/AGENT.md b/docs/runtime/AGENT.md index 0fa4206c..2781d544 100644 --- a/docs/runtime/AGENT.md +++ b/docs/runtime/AGENT.md @@ -78,6 +78,19 @@ production build drops it with the dead branch (the package's `sideEffects` list idempotent and returns that runtime here. `genclass_setup` prints this form, because the link alone needs no runtime in production, where `GenClass.init()` would run for every visitor and send anonymous diagnostics from public hosts by default. +In an app `init` set up, the `genclass` command writes the link itself (its setup's Coding agent step, in the same +preview and yes as `.mcp.json`, and `genclass doctor --fix`; `packages/cli/src/agentlink.mjs`): a file of its own +next to the entry, `genclass.agent.ts` (`.js` beside a JavaScript entry), one `genclass:init` block holding the two +imports and `if () connectAgent(GenClass.init());` with the check init uses there for the devtools line +(`import.meta.env.DEV` on Vite, `process.env.NODE_ENV === "development"` in Next.js and Create React App, plus +`typeof window !== "undefined"` where the entry also renders on the server), and one marked line in the entry, +`import "./genclass.agent"; // genclass:init` (`./genclass.agent.js` from a JavaScript entry; from Next.js's pages/_app, `../genclass.agent`, the file sits in the folder above pages/), right after init's `/auto` import (or after the block of a file init +created). The app's own code is never read or changed; imports stay first, and the link runs right after `/auto`, +before the app's code. In Next.js the file starts with `"use client"`, and where init bound `genclass` it holds +`import("@genclass/runtime/agent").then(({ connectAgent }) => connectAgent(GenClass.init()))` behind the check +instead of the static agent import; in Astro the link is a second marked ``); +} + +/** + * The development-build check for the link of entry `file` of `project` (detectProject's), as init writes it there + * for the devtools line; null for a framework where the link is not planned (see the header). + */ +export function devCondition(project, file = "") { + const f = posix(String(file)); + const both = (cond) => `${cond} && ${BROWSER}`; + switch (project?.framework) { + case "vite": + case "sveltekit": + case "astro": + return DEV.vite; + case "remix": + case "react-router": { + const cond = project.details?.vite ? DEV.vite : DEV.node; + // root runs on the server too (init's devtools line has the same check there) + return /(?:^|\/)entry\.client\.[cm]?[jt]sx?$/.test(f) ? cond : both(cond); + } + case "next": + // instrumentation-client runs in the browser only; genclass-init and pages/_app render on the server too + return /(?:^|\/)instrumentation-client\.[cm]?[jt]s$/.test(f) ? DEV.node : both(DEV.node); + case "cra": + return DEV.node; + case "webpack": + return NODE_ENV_BUNDLERS.includes(project.details?.bundler) ? DEV.node : null; + default: + return null; + } +} + +/** Nuxt: GenClass's plugin as init names it (/plugins/genclass.client.ts), relative to the project. */ +function nuxtPlugin(project, file) { + if (file) return posix(relative(project?.dir ?? ".", file)); + const src = project?.details?.srcDir && project?.dir ? posix(relative(project.dir, project.details.srcDir)) : ""; + return `${src ? `${src}/` : ""}plugins/genclass.client.ts`; +} + +/** + * The lines to add by hand where the link is not planned: { where, lines } (lines empty when there is nothing to + * add, as for the script tag, which has no agent entry yet). `file`: GenClass's own file for the link, where known + * (Nuxt's plugin). + */ +export function linkLines(project, file = null) { + const imports = ['import { GenClass } from "@genclass/runtime";', 'import { connectAgent } from "@genclass/runtime/agent";']; + switch (project?.framework) { + case "angular": + return { where: "src/main.ts: the imports right after GenClass's import, the if line right after the file's last import (before bootstrapApplication)", lines: ['import { isDevMode } from "@angular/core";', ...imports, "if (isDevMode()) connectAgent(GenClass.init());"] }; + case "nuxt": + // a block of its own after the plugin's: remove takes both out, and the file init created with them + return { + where: `the end of GenClass's plugin (${nuxtPlugin(project, file)}), after its "// genclass:init end" line, markers included`, + lines: [AGENT_START, ...imports, "if (import.meta.dev) connectAgent(GenClass.init());", AGENT_END], + }; + case "html": + return { where: "", lines: [] }; + default: { + // a bundler that may not define `process`: a check that is false there instead of a ReferenceError + const cond = devCondition(project, "entry.client.js") ?? 'typeof process !== "undefined" && process.env.NODE_ENV === "development"'; + return { where: "the app's browser entry: the imports right after GenClass's import, the if line right after the file's last import (imports stay first, and it runs before the app's code)", lines: [...imports, `if (${cond}) connectAgent(GenClass.init());`] }; + } + } +} + +/** Why the link is not planned for this project, in a few words. */ +function notPlannedWhy(project) { + switch (project?.framework) { + case "angular": + return "an Angular app tells development builds apart with isDevMode()"; + case "nuxt": + return "in Nuxt the link goes at the end of GenClass's plugin, by hand"; + case "html": + return "a page with GenClass's script tag has no development build, and the agent entry is a module (ESM) only"; + case "webpack": + return `${project.details?.bundler ?? "this bundler"} may not define process.env.NODE_ENV`; + default: + return "GenClass's import here is not one init marked"; + } +} + +/** Plug'n'Play's resolver (Yarn 2 wrote .pnp.js; Yarn 3 and later, and pnpm's node-linker=pnp, write .pnp.cjs). */ +const PNP_FILES = [".pnp.cjs", ".pnp.js"]; +const PNP_LOCKS = [ + ["yarn", "yarn.lock"], + ["pnpm", "pnpm-lock.yaml"], +]; +const parse = (text) => { + try { + return JSON.parse(text); + } catch { + return null; + } +}; +/** Whether `version` has the agent entry; null when it does not say (a workspace's own "0.0.0-use.local"). */ +const agentIn = (version) => (version === null || /-use\.local$/.test(version) ? null : (compareVersions(version, AGENT_SINCE) ?? -1) >= 0); + +/** + * A Plug'n'Play install rooted at `root` (no node_modules: .pnp.cjs resolves packages from the cache): the version + * of @genclass/runtime its lockfile gives the app in `cwd`, as { version, agent } (`agent` null when the lockfile + * holds it but not which version this app gets), or null when the lockfile does not hold it (not installed). + */ +function pnpRuntime(root, cwd, read) { + const pkg = parse(read(join(cwd, "package.json")) ?? ""); + const range = ["dependencies", "devDependencies", "optionalDependencies"].map((k) => pkg?.[k]?.["@genclass/runtime"]).find((r) => typeof r === "string"); + const importer = posix(relative(root, resolve(cwd))); + for (const [kind, file] of PNP_LOCKS) { + const text = read(join(root, file)); + if (typeof text !== "string") continue; + const version = lockVersion(kind, text, "@genclass/runtime", { importer, range, workspace: typeof pkg?.name === "string" ? pkg.name : undefined }); + if (version) return { version, agent: agentIn(version) }; + // there, but several versions and not one this app's range names + if (/(?:^|["'\s/,])@genclass\/runtime@/m.test(text)) return { version: null, agent: null }; + } + return null; +} + +/** + * The @genclass/runtime installed for the project in `cwd`, as Node finds it (its node_modules, else a parent's): + * { version, agent } (`agent`: it has the agent entry, exports["./agent"]; a package.json without `exports` goes by + * its version), or null when none is installed. A Plug'n'Play install (.pnp.cjs, no node_modules) goes by the + * version its lockfile gives; `agent` is null when that cannot be told. `read`: a file's text or null; `exists`: + * whether a file is there. + */ +export function installedRuntime(cwd, read = readText, exists = isFile) { + for (let d = resolve(cwd); ; d = dirname(d)) { + const text = read(join(d, "node_modules", "@genclass", "runtime", "package.json")); + if (typeof text === "string") { + const pkg = parse(text); + const version = typeof pkg?.version === "string" ? pkg.version : null; + const ex = pkg?.exports; + const agent = ex && typeof ex === "object" && !Array.isArray(ex) ? Object.prototype.hasOwnProperty.call(ex, "./agent") : ex === undefined && version !== null && (compareVersions(version, AGENT_SINCE) ?? -1) >= 0; + return { version, agent }; + } + if (PNP_FILES.some((f) => exists(join(d, f)))) return pnpRuntime(d, cwd, read); + if (dirname(d) === d) return null; + } +} + +/** The command that installs the newest runtime line (`npm install @genclass/runtime@beta` while it is a prerelease). */ +export function runtimeUpgrade(pm) { + const ch = channelOf(VERSION); + const spec = ch ? `@genclass/runtime@${ch}` : "@genclass/runtime"; + if (pm === "pnpm") return `pnpm add ${spec}`; + if (pm === "yarn") return `yarn add ${spec}`; + if (pm === "bun") return `bun add ${spec}`; + return `npm install ${spec}`; +} + +/** + * The link for a project, from the runtime CLI's inspectProject (`st`): `state` is + * - "linked": the app's code calls connectAgent already (`files`); the link's own file counts once a marked line + * imports it; + * - "planned": `changes` add it (the link's file, then the line in the entry that imports it; shown and asked before + * they are written, in that order); + * - "manual": it is not planned here (`why`), and `lines` are what to add by hand, `where`; `upgrade`, when the + * installed runtime has no agent entry (or none is installed), is the command to run first; + * - "none": there is no GenClass setup in this folder to link (not a web app, or GenClass not added yet). + * Only "planned" has changes; the others have `changes: null`. + */ +export function planAgentLink(st, deps = {}) { + const read = deps.read ?? readText; + const project = st?.project ?? null; + const cwd = st?.cwd ?? project?.dir ?? "."; + const rel = (f) => posix(relative(cwd, f)); + if (!project?.framework || project.refused) return { state: "none", changes: null, lines: null, why: "no web app in this folder" }; + const marked = st.marked ?? []; + const files = [...new Set([...marked, ...(st.files ?? [])])]; + // the link's files the marked lines import (an extensionless specifier names the .ts file) + const imported = new Set(marked.flatMap((m) => linkImportsIn(read(m)).map((s) => resolve(dirname(m), /\.[cm]?[jt]s$/.test(s) ? s : `${s}.ts`)))); + const linked = []; + for (const f of files) { + if (TEST_FILE.test(rel(f))) continue; + const t = read(f); + if (!t || !t.includes("connectAgent") || !LINKED(t)) continue; + // the link's own file whose import line was taken out by hand links nothing: planned again (the line alone) + if (isLinkFile(t) && !imported.has(resolve(f))) continue; + linked.push(rel(f)); + } + if (linked.length) return { state: "linked", changes: null, lines: null, files: linked }; + if (st.fresh) return { state: "none", changes: null, lines: null, why: "GenClass is not added to this app yet" }; + // the agent entry must be there to import: 0.2.x (npm's latest) has none, and a link to it stops the dev server + // and the build; the script tag needs no package + // (a Plug'n'Play install whose lockfile does not say which version this app gets: planned, as it cannot be told) + const rt = project.framework === "html" ? { agent: true } : installedRuntime(cwd, read, deps.exists ?? isFile); + const upgrade = rt && rt.agent !== false ? null : runtimeUpgrade(project.pm); + const needs = !upgrade ? null : rt ? `the installed @genclass/runtime${rt.version ? ` ${rt.version}` : ""} has no agent entry (it came in ${AGENT_SINCE}): first run ${upgrade}` : `@genclass/runtime is not installed: first run ${upgrade}`; + const manual = (why, file = null) => { + const by = linkLines(project, file); + return { state: "manual", changes: null, ...by, why: needs && by.lines.length ? `${why}; ${needs}` : why, ...(upgrade ? { upgrade } : {}) }; + }; + if (st.handWritten || !marked.length) return manual("GenClass was added by hand, so its lines are yours to change"); + const plugin = project.framework === "nuxt" ? (marked.find((f) => /(?:^|\/)plugins\/genclass\.client\.[cm]?[jt]s$/.test(posix(f))) ?? null) : null; + if (project.framework !== "astro" && devCondition(project, "entry.client.js") === null) return manual(notPlannedWhy(project), plugin); + if (upgrade) return { state: "manual", changes: null, ...linkLines(project), why: needs, upgrade }; + const made = []; + const edits = []; + let taken = null; + for (const f of marked) { + const before = read(f); + if (before === null) continue; + if (project.framework === "astro") { + const after = /\.astro$/.test(f) ? withAstroAgentLink(before) : null; + if (after !== null && after !== before) edits.push({ file: f, rel: rel(f), kind: "modify", before, after, what: `${rel(f)}: the coding-agent link, development builds only` }); + continue; + } + if (!/\.[cm]?[jt]sx?$/.test(f) || autoLine(linesOf(before)) < 0) continue; + const file = linkFileFor(project, f); + const own = read(file); + // a file of the person's own by that name (or one of GenClass's that was edited) is left alone + if (own !== null && !isLinkFile(own)) { + taken = rel(file); + continue; + } + const after = withAgentLink(before, { spec: linkSpecifier(f, file) }); + const edit = after !== null && after !== before; + // the link's file is written only when something imports it: the line planned here, or one the entry has already + // (an entry that only mentions connectAgent, in a comment or a function of its own, gets neither: no orphan file) + const importsIt = linkImportsIn(before).some((s) => resolve(dirname(f), /\.[cm]?[jt]s$/.test(s) ? s : `${s}.ts`) === resolve(file) || resolve(dirname(f), s) === resolve(file)); + if (own === null && (edit || importsIt) && !made.some((ch) => ch.file === file)) { + const { q, semi } = codeStyle(before); + const text = agentFileText(devCondition(project, f), { q, semi, eol: eolOf(before), client: project.framework === "next", bound: project.framework === "next" && BOUND.test(before) }); + made.push({ file, rel: rel(file), kind: "create", before: "", after: text, what: `${rel(file)}: the coding-agent link, development builds only` }); + } + if (edit) edits.push({ file: f, rel: rel(f), kind: "modify", before, after, what: `${rel(f)}: the line that imports ${rel(file)}, right after GenClass's import` }); + } + const changes = [...made, ...edits]; + if (!changes.length) { + if (taken) return manual(`${taken} is there already and is not GenClass's link, so it was left alone`); + return manual(project.framework === "astro" ? "GenClass's script shares its line with other code in " : notPlannedWhy(project)); + } + return { state: "planned", changes, lines: null }; +} + +/** The command that starts the project's dev server ("npm run dev"), from its package.json scripts; null if none. */ +export function devCommand(project) { + const scripts = project?.pkg?.scripts ?? {}; + const name = ["dev", "start", "serve", "develop"].find((s) => typeof scripts[s] === "string"); + if (!name) return null; + const pm = project.pm ?? "npm"; + if (pm === "npm") return name === "start" ? "npm start" : `npm run ${name}`; + if (pm === "bun") return `bun run ${name}`; + return `${pm} ${name}`; +} + +/** + * How to see GenClass work right now, before any deploy, in one sentence: the dev server, the page, its [GenClass] + * lines in the browser console, and the question for the coding agent (`agent`: its MCP server is configured here; + * else once it is, by the Coding agent step). + */ +export function seeItNow(project, { agent = true } = {}) { + const dev = devCommand(project); + const start = dev ? `start your dev server (${dev}) and open the page` : "start your dev server and open the page"; + const ask = '"is GenClass connected?" or to explore a flow for races'; + const tail = agent ? `, and ask your coding agent ${ask}` : `; once your coding agent is connected (the Coding agent step), ask it ${ask}`; + return `To see GenClass work now, before any deploy: ${start}; GenClass prints [GenClass] lines in the browser console${tail}.`; +} diff --git a/packages/cli/src/app.mjs b/packages/cli/src/app.mjs index a0a6870c..39f8fb40 100644 --- a/packages/cli/src/app.mjs +++ b/packages/cli/src/app.mjs @@ -120,9 +120,10 @@ export function render(app, state, o = {}) { for (const l of rest) out(` ${l}`); out(); } - // the dashboard page's own words: a page load is one page GenClass watched - out(` ${cell("Page loads", n(t.visits))} ${cell("Problems found", n(t.found))}`.trimEnd()); - out(` ${cell("Handled", n(t.handled))} ${cell("Visual checks", n(t.checks))}`.trimEnd()); + // the dashboard page's own words: a page load is one page GenClass watched; "Problems found" is the model's findings + // and the measured checks together, as on the page (pages.ts problemsOf) and in `genclass problems` and `report` + out(` ${cell("Page loads", n(t.visits))} ${cell("Problems found", n(t.found + t.checks))}`.trimEnd()); + out(` ${cell("Handled", n(t.handled))} ${cell("Of them checks", n(t.checks))}`.trimEnd()); if (line) out(` ${c.gray("Problems".padEnd(15))}${c.green(line)} ${c.gray("over the period")}`); if (!t.visits && !t.found && !t.checks) { diff --git a/packages/cli/src/cli.mjs b/packages/cli/src/cli.mjs index e10671db..18dd233b 100644 --- a/packages/cli/src/cli.mjs +++ b/packages/cli/src/cli.mjs @@ -9,6 +9,8 @@ // account without it, and offers to connect this folder's app once Pro is on. `remove` is the runtime CLI's, // followed by what this command's other steps wrote (remove.mjs). `dashboard` is this command's own view // (app.mjs); signed out, in a folder with an app's private link, it prints that link (the runtime CLI's own). +// `flake` takes Playwright's arguments, so it reads its own words (flake.mjs); it runs locally, sends nothing and +// is free, like `privacy` and `doctor`. // - The command is Pro's (the owner's call, 2026-11-13): every command but FREE_COMMANDS passes paywall.mjs // requirePro first (signed out: the sign-in, then Pro with its free trial), the home's commands (ctx.nested) // included. The walk (`genclass`, `setup`) has Pro as its own step right after the sign-in (state.mjs). @@ -21,6 +23,7 @@ import { hostConfig } from "../../runtime/bin/lib/host.mjs"; import { c, err, interactive, out } from "../../runtime/bin/lib/ui.mjs"; import { BUILD } from "./assets.mjs"; +import { isShort, shorten } from "./name.mjs"; import { width, wrap } from "./tui.mjs"; /** The help's sections: [heading, [command, what it does]...]; usage() lays them out for the terminal's width. */ @@ -44,6 +47,7 @@ const HELP = [ ['npx genclass ask "..."', "ask about your app in plain words; the model answers from its numbers"], ["npx genclass suggest [url]", "what your app is missing, most important first (--yes, --no-model, --all)"], ["npx genclass scan ", "23 visual checks on one page"], + ["npx genclass flake [tests]", "is a failing Playwright test flaky, or is your app racy? Runs your suite on seeded response orders and says which, with the seed that replays it (--runs N, --seed N, --json; free, local)"], ]], ["Connect", [ ["npx genclass connections", "where alerts go (Slack, Sentry, PostHog, Datadog, a webhook), GitHub, agent (connections add | test | on | off | remove )"], @@ -59,8 +63,23 @@ const HELP = [ ["npx genclass login", "sign in (logout, whoami)"], ["npx genclass remove", "take GenClass out of this app again"], ]], + ["Trust", [ + ["npx genclass privacy", "what GenClass sends from your visitors' browsers and keeps on their devices, and the lines that make it send nothing (--out file.md for a privacy policy; free, no sign-in)"], + ["npx genclass doctor", "check that everything GenClass added is in place and current, and what to run when it is not"], + ]], ]; +/** + * A help line with the command named as this run prints it: `genclass` once installed (name.mjs shortens it), or + * `npx genclass@alpha` for a prerelease run through npx (name.mjs useTaggedName): laid out with that name, so the + * columns line up after the output is rewritten. + */ +function named0(t) { + if (isShort()) return shorten(t); + const cmd = globalThis.__GENCLASS_CLI__?.cmd ?? "npx genclass"; + return cmd !== "npx genclass" && cmd.startsWith("npx genclass@") ? String(t).replace(/(^|[^\w-])npx genclass(?![@\w-])/g, `$1${cmd}`) : t; +} + /** * The help, laid out for `cols` columns (the terminal's): a command and its words side by side on a wide terminal, * the words under the command on a narrow one (58 columns and up), every line within `cols`. @@ -73,13 +92,20 @@ export function usage(cols = width()) { }; text("genclass: GenClass in your terminal. Set it up, see what it finds, have it fixed."); lines.push(""); - text("The genclass command comes with Pro: 3 days free, then $15 / developer / month, with a card on Stripe. Without Pro: login, logout, whoami, status, plan, upgrade, profile, remove, help. Free is on the website: https://genclass.dev", " "); + text("The genclass command comes with Pro: 3 days free, then $15 / developer / month, with a card on Stripe. Without Pro: login, logout, whoami, status, plan, upgrade, profile, privacy, doctor, flake, remove, help. Free is on the website: https://genclass.dev", " "); const side = w >= 78; - const col = 30; + // the command column fits the longest name as it is printed (npx genclass@alpha suggest [url] is 32 wide) + const longest = Math.max(...HELP.flatMap(([, rows]) => rows.map(([cmd]) => named0(cmd).length))); + const col = Math.max(30, Math.min(40, longest + 4)); + // laid out with the name as it is printed: once `genclass` is installed every `npx genclass` is shortened on its + // way out (name.mjs), so padding the long form would leave the first column four characters short + const named = named0; for (const [head, rows] of HELP) { lines.push(""); if (head) lines.push(` ${head}`); - for (const [cmd, what] of rows) { + for (const [cmd0, what0] of rows) { + const cmd = named(cmd0); + const what = named(what0); if (side) { const words = wrap(what, w - col); lines.push(` ${cmd.padEnd(col - 2)}${words[0] ?? ""}`); @@ -93,14 +119,16 @@ export function usage(cols = width()) { lines.push(""); text("Options: --app --range 24h|7d|30d|90d|1y --all --json --cwd --yes --no-browser --help --version", " "); lines.push(""); - text('Run it in your web app\'s folder. npx runs it without installing; "npm install -g genclass" makes it just "genclass". Every part GenClass sets up is listed by "npx genclass status --all". Docs: https://genclass.dev/docs/cli', " "); + // a prerelease is installed by its tag: plain "genclass" on npm is the stable line, which lacks this line's commands + const line = /^\d+\.\d+\.\d+-([0-9A-Za-z-]+)/.exec(BUILD.version)?.[1] ?? ""; + text(`Run it in your web app's folder. npx runs it without installing; "npm install -g genclass${line ? `@${line}` : ""}" makes it just "genclass". Every part GenClass sets up is listed by "npx genclass status --all". Docs: https://genclass.dev/docs/cli`, " "); return lines.join("\n"); } /** The help at the default width (80 columns), for tests and anything that wants it as one string. */ export const USAGE = usage(80); -const BOOL = { yes: "yes", y: "yes", json: "json", "no-browser": "noBrowser", "no-model": "noModel", all: "all", help: "help", h: "help", version: "version", v: "version", open: "open", print: "print", copy: "copy" }; +const BOOL = { md: "md", fix: "fix", offline: "offline", yes: "yes", y: "yes", json: "json", "no-browser": "noBrowser", "no-model": "noModel", all: "all", help: "help", h: "help", version: "version", v: "version", open: "open", print: "print", copy: "copy" }; const VALUE = { cwd: "cwd", url: "url", app: "app", range: "range", from: "from", to: "to", format: "format", out: "out", agent: "agent" }; /** The flags this file knows, and what is left ({ o, rest }); an unknown flag stays in `rest` for the command it is for. */ @@ -114,7 +142,8 @@ export function parseArgs(argv) { if (key && BOOL[key] && eq < 0) o[BOOL[key]] = true; else if (key && VALUE[key]) { const v = eq > 0 ? a.slice(eq + 1) : argv[++i]; - if (v === undefined || v === "") return { o, rest, error: `--${key} needs a value` }; + // a flag where the value should be (privacy --out --json) is a missing value, never a file named "--json" + if (v === undefined || v === "" || (eq < 0 && /^--?[A-Za-z]/.test(v))) return { o, rest, error: `--${key} needs a value` }; o[VALUE[key]] = v; } else rest.push(a); } @@ -159,7 +188,11 @@ export async function run(argv, ctx = {}) { await (await import("./actions.mjs")).planNow({ ...po, announce: true }).catch(() => "none"); return code; }; - if (["logout", "whoami"].includes(cmd)) return (await import("../../runtime/bin/lib/login.mjs")).run(cmd, args); + // --no-browser is one of this command's options for every command (the help lists it so): the runtime CLI's + // commands that do not take it (connect, init, scan, audit, logout, whoami, remove) get their words without it, + // and it is kept in `po` and in what paywall.mjs reads + const rargs = args.filter((a) => a !== "--no-browser"); + if (["logout", "whoami"].includes(cmd)) return (await import("../../runtime/bin/lib/login.mjs")).run(cmd, rargs); if (cmd === "login") { // the sign-in only; then Pro (paywall.mjs afterLogin) for an account without it; this folder's app is offered // to the account (the runtime login's own question) only once Pro is on, so nothing is written before Pro's card @@ -174,17 +207,19 @@ export async function run(argv, ctx = {}) { if (!(await (await import("./paywall.mjs")).afterLogin(po).catch(() => true))) return code; return thenPlan(noConnect ? code : await afterSignIn(po, args, login).catch(() => 1)); } - if (cmd === "remove") return (await import("./remove.mjs")).remove(args); + if (cmd === "remove") return (await import("./remove.mjs")).remove(rargs); + // free and local, and its words are Playwright's: it reads them itself (flake.mjs) + if (cmd === "flake") return (await import("./flake.mjs")).flake(args); if (["connect", "init", "scan", "audit"].includes(cmd)) { // words the command does not take: its own usage error, before anything is asked of genclass.dev - if (!asksHelp && !(await argsRight(cmd, args))) { - if (cmd === "connect") return (await import("../../runtime/bin/lib/login.mjs")).run(cmd, args); - if (cmd === "init") return (await import("../../runtime/bin/lib/init.mjs")).run(cmd, args); - return (await import("../../runtime/bin/lib/scan.mjs")).run(cmd, args); + if (!asksHelp && !(await argsRight(cmd, rargs))) { + if (cmd === "connect") return (await import("../../runtime/bin/lib/login.mjs")).run(cmd, rargs); + if (cmd === "init") return (await import("../../runtime/bin/lib/init.mjs")).run(cmd, rargs); + return (await import("../../runtime/bin/lib/scan.mjs")).run(cmd, rargs); } // the opt-out the setup prints works for everyone (AGENTS.md rule 8): on an app with GenClass in it, init // --no-telemetry (or --telemetry, to undo it) changes that one option, here on this machine - const optOut = cmd === "init" && telemetryOnly(args) && !(await import("../../runtime/bin/lib/init.mjs")).inspectProject({ cwd: po.cwd }).fresh; + const optOut = cmd === "init" && telemetryOnly(rargs) && !(await import("../../runtime/bin/lib/init.mjs")).inspectProject({ cwd: po.cwd }).fresh; const gate = optOut ? 0 : await paid(); if (gate !== 0) { if (cmd !== "scan" && cmd !== "audit") return gate; @@ -199,17 +234,17 @@ export async function run(argv, ctx = {}) { return 2; } } - if (cmd === "connect") return thenPlan(await (await import("../../runtime/bin/lib/login.mjs")).run(cmd, args)); - if (cmd === "init") return thenPlan(await (await import("../../runtime/bin/lib/init.mjs")).run(cmd, args)); + if (cmd === "connect") return thenPlan(await (await import("../../runtime/bin/lib/login.mjs")).run(cmd, rargs)); + if (cmd === "init") return thenPlan(await (await import("../../runtime/bin/lib/init.mjs")).run(cmd, rargs)); if (cmd === "scan" || cmd === "audit") { // this command carries no copy of the runtime's script-tag build, so the page check runs on genclass.dev unless asked otherwise - const withHost = args.includes("--local") || args.includes("--hosted") || args.includes("--help") ? args : [...args, "--hosted"]; + const withHost = rargs.includes("--local") || rargs.includes("--hosted") || rargs.includes("--help") ? rargs : [...rargs, "--hosted"]; return (await import("../../runtime/bin/lib/scan.mjs")).run(cmd, withHost); } const { o, rest, error } = parseArgs(args); if (error) { - err(`genclass: ${error}\n\n${usage()}`); + err(`genclass: ${error}\n Every command and option: ${c.cyan("npx genclass help")}`); return 2; } if (o.version || cmd === "version") { @@ -252,7 +287,8 @@ export async function run(argv, ctx = {}) { } if (cmd !== null && !COMMANDS.includes(cmd)) { const near = nearest(cmd); - err(`genclass: unknown command ${c.bold(cmd)}${near ? `. Did you mean ${c.cyan(`npx genclass ${near}`)}?` : ""}\n\n${usage()}`); + // one line and the way to the list: a typo is not worth 60 lines of help (the alpha walk, 2026-11-13) + err(`genclass: unknown command ${c.bold(cmd)}${near ? `. Did you mean ${c.cyan(`npx genclass ${near}`)}?` : ""}\n Every command: ${c.cyan("npx genclass help")}`); return 2; } // the commands that take words after their name: sections, picks, subcommands, a question @@ -261,7 +297,7 @@ export async function run(argv, ctx = {}) { const WORDY = ["analytics", "fix", "ask", "connections", "agent", "funnels", "apps", "team"]; if (flags.length || (words.length && !WORDY.includes(cmd))) { const bad = flags[0] ?? words[0]; - err(`genclass: unknown ${bad.startsWith("-") ? "option" : "command"} ${c.bold(bad)}\n\n${usage()}`); + err(`genclass: unknown ${bad.startsWith("-") ? "option" : "command"} ${c.bold(bad)}${cmd ? ` for ${cmd}` : ""}\n Every command and option: ${c.cyan("npx genclass help")}`); return 2; } // the words of the commands that take them, before anything is asked of genclass.dev @@ -278,6 +314,9 @@ export async function run(argv, ctx = {}) { // printed as before, with no sign-in and no Pro (it is on this machine already) const fallback = async () => (await import("../../runtime/bin/lib/login.mjs")).run("dashboard", [...(o.cwd ? ["--cwd", o.cwd] : []), ...(o.open ? ["--open"] : [])]); if (cmd === "dashboard" && !o.json && !o.app && (await privateLinkHere(o.cwd))) return fallback(); + // read only and local, for everyone: what is sent and kept (privacy.mjs), and whether the setup is whole (doctor.mjs) + if (cmd === "privacy") return (await import("./privacy.mjs")).privacy(o); + if (cmd === "doctor") return (await import("./doctor.mjs")).doctor(o); if (cmd !== null && !["setup", "status"].includes(cmd)) { const gate = await paid(); if (gate !== 0) return gate; @@ -300,6 +339,19 @@ export async function run(argv, ctx = {}) { const home = async (ho) => (await import("./home.mjs")).home(ho, { runCommand: (a) => run(a, { nested: true }), nearest, afterCommand: async () => (await import("./manage.mjs")).freeLine({ cwd: ho.cwd }) }); // `genclass` alone works from the first run on, and stays current (home.mjs installShortName) if (!ctx.nested && !o.yes && !o.json) await (await import("./home.mjs")).installShortName(); + // a newer genclass on npm: one line, from what yesterday's check found; today's runs alongside (update.mjs) + if (!ctx.nested) { + try { + const up = await import("./update.mjs"); + if (up.updateAllowed(o)) { + const line = up.updateLine(BUILD.version); + if (line) out(`\n ${c.yellow("▲")} ${line.text}`); + void up.refreshLatest(); + } + } catch { + /* the notice is never in the way */ + } + } // `genclass` alone opens the command's prompt straight away (the owner's call, 2026-11-13: "genclass by itself // directly takes you to the genclass cli"); `npx genclass` does too once this folder is set up, and walks the // setup only before that. The walk itself is `genclass setup`, to change something @@ -434,13 +486,13 @@ async function privateLinkHere(cwd) { } } -/** The commands that work without Pro: signing in and out, the plan itself, where things stand, help, the version, and taking GenClass out. */ -export const FREE_COMMANDS = ["login", "logout", "whoami", "plan", "upgrade", "profile", "status", "remove", "help", "version"]; +/** The commands that work without Pro: signing in and out, the plan itself, where things stand, help, the version, taking GenClass out, and the local checks that send nothing (privacy, doctor, flake). */ +export const FREE_COMMANDS = ["login", "logout", "whoami", "plan", "upgrade", "profile", "status", "remove", "help", "version", "privacy", "doctor", "flake"]; /** Every command, for the "did you mean" of a mistyped one. */ export const COMMANDS = [ "setup", "status", "suggest", "dashboard", "problems", "analytics", "events", "health", "report", "export", "fix", "ask", "scan", "connections", "agent", "funnels", - "apps", "plan", "upgrade", "profile", "team", "login", "logout", "whoami", "connect", "init", "remove", "help", "version", + "apps", "plan", "upgrade", "profile", "team", "login", "logout", "whoami", "connect", "init", "remove", "help", "version", "privacy", "doctor", "flake", ]; /** The command a mistyped one is closest to (at most two edits away), or null. */ diff --git a/packages/cli/src/doctor.mjs b/packages/cli/src/doctor.mjs new file mode 100644 index 00000000..bf789b1f --- /dev/null +++ b/packages/cli/src/doctor.mjs @@ -0,0 +1,1140 @@ +// `genclass doctor`: is everything GenClass added to this project in place and current, and what to run when it is +// not. One line per part (this command, Node, the sign-in, the runtime and where it is imported, the MCP server's +// pin, the skill, the coding-agent link, the bridge, the site's Content-Security-Policy, the test workflow), each +// with its fix. `--fix` does the fixes that are GenClass's own files and lines, after showing them. +// +// Invariants: +// - Read only unless --fix, and then only GenClass's own: the version pin in its MCP server entry, the skill file +// while it carries its marker, and the coding-agent link where agentlink.mjs plans it (its own file, imported right +// after init's import, in the frameworks whose development builds it can tell apart), marked genclass:init so +// `genclass remove` takes it out. Each change is shown (its diff; a new skill file by name and size) before it is +// written, with --yes too; a terminal is asked once, --yes is the yes, and without a terminal and without --yes +// nothing is written. With --json, stdout is one JSON object only (the report and the changes go to stderr) and +// nothing is asked: --fix writes with --yes only. +// - The project is found the way the tools that use it find it: the runtime where Node resolves it from the app's +// folder (its node_modules or a parent's, as workspaces hoist it), or the script tag's version on a plain HTML +// site; the MCP configuration in the same files `genclass status` reads (state.mjs agentConfigs), in the app's +// folder and at the repository's root. +// - Two requests at most, both to npm's public registry for dist-tags (this command's and the runtime's), each +// timed out after 2.5 s and sending nothing about the project; --offline skips them. This command is compared with +// the newer of `latest` and the dist-tag of the line it is on (`alpha` for 0.4.0-alpha.N). Locally: `git rev-parse` +// for the repository's root, and `genclass --version` with the PATH a shell has (npx's folders left out). Nothing +// else leaves the machine. +// - Never throws: a part that cannot be read says so ("not checked") and the others still run. +// - A Content-Security-Policy is "bad" only when it is set for routes that serve pages; one for a route that cannot +// be told to (`/admin/api/(.*)`, a source built at run time) is not checked, and the row names it. + +import { spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; +import { createConnection } from "node:net"; +import { delimiter, dirname, join, relative, resolve } from "node:path"; +import { c, interactive, out, printChange, sym } from "../../runtime/bin/lib/ui.mjs"; +import { channelOf, cmdFor, installedVersion } from "../../runtime/bin/lib/version.mjs"; +import { SKILL_MARK, SKILL_PATH, skillText } from "./actions.mjs"; +import { planAgentLink, withAgentLink } from "./agentlink.mjs"; +import { BUILD } from "./assets.mjs"; +import { runGit } from "./git.mjs"; +import { agentConfigs } from "./state.mjs"; +import { agree, clean, good, header, note, warn, width, wrap } from "./tui.mjs"; + +/** An import statement of the runtime's /auto entry (not a comment that names it, as the config file's does). */ +const AUTO_IMPORT = /^\s*import\s+(?:[\w*{}\s,]+\s+from\s+)?["']@genclass\/runtime\/auto(?:\/(?:observe|guard|heal))?["']/m; +const VERSION_RE = /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/; + +/** "1.2.3" or "1.2.3-beta.4" compared: negative when a is older. Prereleases sort before their release. */ +export function compareVersions(a, b) { + const p = (v) => { + const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(String(v ?? "")); + return m ? { n: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null; + }; + const x = p(a); + const y = p(b); + if (!x || !y) return 0; + for (let i = 0; i < 3; i++) if (x.n[i] !== y.n[i]) return x.n[i] - y.n[i]; + if (x.pre === y.pre) return 0; + if (x.pre === null) return 1; + if (y.pre === null) return -1; + const xs = x.pre.split("."); + const ys = y.pre.split("."); + for (let i = 0; i < Math.max(xs.length, ys.length); i++) { + if (xs[i] === undefined) return -1; + if (ys[i] === undefined) return 1; + const xn = /^\d+$/.test(xs[i]); + const yn = /^\d+$/.test(ys[i]); + if (xn && yn && Number(xs[i]) !== Number(ys[i])) return Number(xs[i]) - Number(ys[i]); + if (xs[i] !== ys[i]) return xs[i] < ys[i] ? -1 : 1; + } + return 0; +} + +/** + * The newest release for someone on `current`, from a package's dist-tags: the newer of `latest` and the tag named + * after current's prerelease line (`alpha` for 0.4.0-alpha.0, as the release workflows publish it), with the tag to + * install it by. { version: null } when the tags say nothing. Pure. + */ +export function newestFor(current, tags) { + const ok = (v) => (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v) ? v : null); + const latest = ok(tags?.latest); + const line = channelOf(current); + const pre = line && line !== "latest" ? ok(tags?.[line]) : null; + if (pre && (!latest || compareVersions(pre, latest) > 0)) return { version: pre, tag: line }; + return { version: latest, tag: "latest" }; +} + +/** npm's dist-tags for a package ({ latest, beta, ... }), or null: offline, slow (2.5 s), or not JSON. */ +async function distTags(name, fetchFn = globalThis.fetch) { + if (typeof fetchFn !== "function") return null; + const ctrl = new AbortController(); + const timer = setTimeout(() => ctrl.abort(), 2500); + try { + const r = await fetchFn(`https://registry.npmjs.org/-/package/${name.replace("/", "%2f")}/dist-tags`, { signal: ctrl.signal, headers: { accept: "application/json" } }); + if (!r.ok) return null; + const j = await r.json(); + return j && typeof j === "object" ? j : null; + } catch { + return null; + } finally { + clearTimeout(timer); + } +} + +const read = (file) => { + try { + return readFileSync(file, "utf8"); + } catch { + return null; + } +}; + +const real = (p) => { + try { + return realpathSync(p); + } catch { + return p; + } +}; + +/** Whether something listens on 127.0.0.1:port (GenClass's bridge, when an MCP server owns it). */ +function listening(port, timeoutMs = 400) { + return new Promise((done) => { + const s = createConnection({ host: "127.0.0.1", port }); + const end = (v) => { + s.destroy(); + done(v); + }; + s.setTimeout(timeoutMs, () => end(false)); + s.on("connect", () => end(true)); + s.on("error", () => end(false)); + }); +} + +// ------------------------------------------------------------------------------------- Content-Security-Policy + +/** The files hosts and frameworks read a Content-Security-Policy from, relative to the app's folder. */ +const CSP_FILES = [ + "index.html", + "public/index.html", + "src/app.html", + "vercel.json", + "firebase.json", + "staticwebapp.config.json", + "public/staticwebapp.config.json", + "netlify.toml", + "public/_headers", + "_headers", + "static/_headers", + "next.config.js", + "next.config.mjs", + "next.config.cjs", + "next.config.ts", + "src/middleware.ts", + "src/middleware.js", + "middleware.ts", + "middleware.js", + "src/proxy.ts", + "src/proxy.js", + "proxy.ts", + "proxy.js", + "src/hooks.server.ts", + "src/hooks.server.js", +]; + +const ESC = { n: "\n", t: "\t", r: "\r", b: "\b", f: "\f", v: "\v", 0: "\0", "\n": "" }; +const isQuote = (ch) => ch === '"' || ch === "'" || ch === "`"; +const skipWs = (t, i) => { + while (i < t.length && /\s/.test(t[i])) i++; + return i; +}; + +/** + * The string literal that opens at t[i] (JS, JSON or TOML: ", ' or `, and TOML's """ and '''): [value, end], or + * null when there is none or it does not close. A template literal's ${...} parts become their own text (without its + * quotes), so a source they add is still seen. + */ +function stringAt(t, i, toml = false) { + const q = t[i]; + if (!isQuote(q) || (toml && q === "`")) return null; + if (toml && t.startsWith(q.repeat(3), i)) { + const close = t.indexOf(q.repeat(3), i + 3); + if (close < 0) return null; + let v = t.slice(i + 3, close).replace(/^\r?\n/, ""); + if (q === '"') v = v.replace(/\\\r?\n\s*/g, "").replace(/\\(u[0-9a-fA-F]{4}|.)/g, (m, e) => (e[0] === "u" ? String.fromCharCode(parseInt(e.slice(1), 16)) : (ESC[e] ?? e))); + return [v, close + 3]; + } + let v = ""; + for (let j = i + 1; j < t.length; j++) { + const ch = t[j]; + if (ch === "\\" && !(toml && q === "'")) { + const e = t[j + 1] ?? ""; + if (e === "u" && /^[0-9a-fA-F]{4}$/.test(t.slice(j + 2, j + 6))) { + v += String.fromCharCode(parseInt(t.slice(j + 2, j + 6), 16)); + j += 5; + } else if (e === "\r" && t[j + 2] === "\n") j += 2; + else { + v += ESC[e] ?? e; + j++; + } + continue; + } + if (ch === q) return [v, j + 1]; + if (q === "`" && ch === "$" && t[j + 1] === "{") { + let depth = 0; + let k = j + 1; + for (; k < t.length; k++) { + if (t[k] === "{") depth++; + else if (t[k] === "}" && --depth === 0) break; + } + v += ` ${t.slice(j + 2, k).replace(/["`]/g, " ")} `; + j = k; + continue; + } + if (ch === "\n" && q !== "`") return null; + v += ch; + } + return null; +} + +/** Where the parenthesis that opens at t[i] closes (after it), skipping strings. */ +function closeParen(t, i) { + let depth = 0; + for (let j = i; j < t.length; j++) { + if (isQuote(t[j])) { + const s = stringAt(t, j); + if (s) { + j = s[1] - 1; + continue; + } + } + if (t[j] === "(") depth++; + else if (t[j] === ")" && --depth === 0) return j + 1; + } + return t.length; +} + +/** Past the calls and members after a value (`.replace(/\s{2,}/g, " ").trim()`, `as const`): they leave its sources. */ +function skipCalls(t, i) { + for (;;) { + const m = /^\s*\??\.\s*[A-Za-z_$][\w$]*\s*/.exec(t.slice(i, i + 200)); + if (m) { + i += m[0].length; + if (t[i] === "(") i = closeParen(t, i); + continue; + } + const a = /^\s+as\s+const\b/.exec(t.slice(i, i + 20)); + if (a) { + i += a[0].length; + continue; + } + return i; + } +} + +/** One operand of a JS string expression at t[i]: [value, end, known]; a name nothing here defines is its own text. */ +function jsAtom(t, i, depth) { + const s = stringAt(t, i); + if (s) return [s[0], s[1], true]; + if (t[i] === "(") { + const v = jsValue(t, i + 1, depth); + const j = v ? skipWs(t, v[1]) : -1; + return v && t[j] === ")" ? [v[0], j + 1, true] : null; + } + if (t[i] === "[") { + // an array of strings with .join(sep), the form `[ "default-src 'self'", ... ].join("; ")` + const parts = []; + let j = skipWs(t, i + 1); + while (t[j] !== "]") { + const v = jsValue(t, j, depth); + if (!v) return null; + parts.push(v[0]); + j = skipWs(t, v[1]); + if (t[j] === ",") j = skipWs(t, j + 1); + else if (t[j] !== "]") return null; + } + const join = /^\s*\.\s*join\s*\(\s*/.exec(t.slice(j + 1, j + 40)); + if (!join) return null; + const k = j + 1 + join[0].length; + const sep = t[k] === ")" ? [",", k] : stringAt(t, k); + if (!sep) return null; + const close = skipWs(t, sep[1]); + return [parts.join(sep[0]), t[close] === ")" ? close + 1 : close, true]; + } + const id = /^[A-Za-z_$][\w$]*/.exec(t.slice(i, i + 100))?.[0]; + if (!id || /^(?:true|false|null|undefined|new|await|function)$/.test(id)) return null; + if (depth < 4) { + const decl = new RegExp(`(?:^|[^\\w$.])(?:const|let|var)\\s+${id.replace(/\$/g, "\\$")}\\s*(?::[^=\\n]+)?=\\s*`).exec(t); + const v = decl ? jsValue(t, decl.index + decl[0].length, depth + 1) : null; + if (v) return [v[0], i + id.length, true]; + } + return [` ${id} `, i + id.length, false]; +} + +/** + * The string a JS or TS expression at t[i] comes to, as far as the file's text tells: string and template literals, + * joined with +, an array of strings with .join(sep), or a const that holds one of these. [value, end] or null + * (nothing in it could be read). + */ +function jsValue(t, i, depth = 0) { + const parts = []; + let known = false; + let at = skipWs(t, i); + for (;;) { + const one = jsAtom(t, at, depth); + if (!one) break; + parts.push(one[0]); + known ||= one[2]; + const j = skipWs(t, skipCalls(t, one[1])); + at = j; + if (t[j] !== "+") break; + at = skipWs(t, j + 1); + } + return known ? [parts.join(""), at] : null; +} + +const decodeHtml = (s) => + s.replace(/&(?:#(\d+)|#x([0-9a-f]+)|(quot|apos|amp|lt|gt));/gi, (m, d, x, n) => (d ? String.fromCharCode(Number(d)) : x ? String.fromCharCode(parseInt(x, 16)) : { quot: '"', apos: "'", amp: "&", lt: "<", gt: ">" }[n.toLowerCase()])); + +/** The policies a file sets, by its kind: [{ policy, route }] (`route`: the path pattern it is set for, if any). */ +function policiesIn(file, t) { + const found = []; + const NAME = /^content-security-policy$/i; + if (/\.html?$/i.test(file)) { + for (const tag of t.matchAll(/]*>/gi)) { + const attrs = {}; + for (const a of tag[0].matchAll(/([^\s=<>/"']+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+))/g)) attrs[a[1].toLowerCase()] = a[2] ?? a[3] ?? a[4]; + if (NAME.test(String(attrs["http-equiv"] ?? "").trim()) && attrs.content) found.push({ policy: decodeHtml(attrs.content), route: null }); + } + return found; + } + if (/_headers$/.test(file)) { + // Netlify's and Cloudflare Pages' file, read as their parsers read it: each line trimmed, so indenting is optional; + // a path line starts with `/` (or, on Cloudflare, an absolute URL: `https://example.com/*`), and the `Name: value` + // lines after it are its headers. A header before any path line is not applied, so it is not read. + let route; + for (const raw of t.split(/\r?\n/)) { + const line = raw.trim(); + if (!line || line.startsWith("#")) continue; + if (line.startsWith("/") || /^[a-z][a-z0-9+.-]*:\/\//i.test(line)) { + route = line; + continue; + } + const m = /^content-security-policy\s*:\s*(.+)$/i.exec(line); + if (m && route !== undefined) found.push({ policy: m[1].trim(), route }); + } + return found; + } + if (/\.toml$/.test(file)) { + for (const m of t.matchAll(/(?:^|[\s{,])(?:"content-security-policy"|'content-security-policy'|content-security-policy)\s*=\s*/gim)) { + const s = stringAt(t, m.index + m[0].length, true); + if (!s) continue; + const before = t.slice(0, m.index); + const table = before.lastIndexOf("[[headers]]"); + const route = table < 0 ? null : (/(?:^|\n)\s*for\s*=\s*["']([^"'\n]*)["']/.exec(before.slice(table))?.[1] ?? null); + found.push({ policy: s[0], route }); + } + return found; + } + if (/\.json$/.test(file)) { + let j; + try { + j = JSON.parse(t); + } catch { + j = undefined; + } + if (j !== undefined) { + // vercel.json and firebase.json: { source, headers: [{ key, value }] }; Azure's: globalHeaders, routes[].headers + const walk = (v, route) => { + if (Array.isArray(v)) return v.forEach((x) => walk(x, route)); + if (!v || typeof v !== "object") return; + const here = [v.source, v.src, v.route].find((x) => typeof x === "string") ?? route; + const name = v.key ?? v.name; + if (typeof name === "string" && NAME.test(name.trim()) && typeof v.value === "string") found.push({ policy: v.value, route: here }); + for (const [k, x] of Object.entries(v)) { + if (NAME.test(k.trim()) && typeof x === "string") found.push({ policy: x, route: here }); + else walk(x, here); + } + }; + walk(j, null); + return found; + } + } + // JS and TS: { key: "Content-Security-Policy", value: ... }, { "Content-Security-Policy": ... }, + // headers.set("Content-Security-Policy", ...), with the value read as far as the text tells (jsValue), and the + // route of the `{ source, headers }` entry it is in (jsRouteAt) + let code; + for (const m of t.matchAll(/(["'`])content-security-policy\1/gi)) { + let j = skipWs(t, m.index + m[0].length); + if (t[j] === ":") j++; + else if (t[j] === ",") { + j = skipWs(t, j + 1); + const v = /^["']?value["']?\s*:/.exec(t.slice(j, j + 20)); + if (v) j += v[0].length; + } else continue; + const r = jsValue(t, j); + if (!r || !r[0].trim()) continue; + code ??= codeOnly(t); + const src = jsRouteAt(t, code, m.index); + found.push({ policy: r[0], route: src?.route ?? null, ...(src?.text ? { text: src.text } : {}) }); + } + return found; +} + +const KEYWORD_BEFORE_REGEX = /^(?:return|typeof|instanceof|in|of|new|delete|void|throw|case|do|else|yield|await)$/; + +/** + * A JS or TS file's text with what is not code blanked (the inside of strings and template literals, comments, regular + * expressions), at the same length and with the same line breaks, so brackets and keys can be found in it. + */ +function codeOnly(t) { + const o = t.split(""); + const blank = (a, b) => { + for (let k = a; k < b; k++) if (o[k] !== "\n") o[k] = " "; + }; + let last = ""; // the last code character before i (spaces left out) + let word = ""; // the identifier that ends there, if one does + for (let i = 0; i < t.length; ) { + const ch = t[i]; + if (ch === "/" && (t[i + 1] === "/" || t[i + 1] === "*")) { + const close = t[i + 1] === "/" ? t.indexOf("\n", i) : t.indexOf("*/", i + 2); + const end = close < 0 ? t.length : t[i + 1] === "/" ? close : close + 2; + blank(i, end); + i = end; + continue; + } + if (isQuote(ch)) { + const s = stringAt(t, i); + if (s) { + blank(i + 1, s[1] - 1); + i = s[1]; + last = ch; + word = ""; + continue; + } + } + if (ch === "/" && (!/[\w$)\]'"`]/.test(last) || KEYWORD_BEFORE_REGEX.test(word))) { + // a regular expression, to its closing slash (past character classes) on the same line + let j = i + 1; + for (let cls = false; j < t.length && t[j] !== "\n"; j++) { + if (t[j] === "\\") j++; + else if (t[j] === "[") cls = true; + else if (t[j] === "]") cls = false; + else if (t[j] === "/" && !cls) break; + } + if (t[j] === "/") { + blank(i + 1, j); + i = j + 1; + last = ")"; + word = ""; + continue; + } + } + const id = /^[\w$]+/.exec(t.slice(i, i + 100))?.[0]; + if (id) { + last = id[id.length - 1]; + word = id; + i += id.length; + continue; + } + if (!/\s/.test(ch)) { + last = ch; + word = ""; + } + i++; + } + return o.join(""); +} + +/** + * The route a JS or TS header at t[at] is set for: the `source` of the innermost object around it that has one, as + * Next.js's headers() writes `{ source, headers: [...] }` (in either order), as { route, text? }; null when none + * does (a header a middleware sets, or one in a list kept in a constant). A source read only in part (a template's + * `${base}`, a name defined elsewhere) keeps what was not read as words between spaces in `route`, and `text` is + * the source as the file writes it. `code`: codeOnly(t). + */ +function jsRouteAt(t, code, at) { + const open = []; + for (let i = 0; i < at; i++) { + const ch = code[i]; + if (ch === "{" || ch === "[" || ch === "(") open.push(i); + else if ((ch === "}" || ch === "]" || ch === ")") && open.length) open.pop(); + } + for (let n = open.length - 1; n >= 0; n--) { + if (code[open[n]] !== "{") continue; + // the object's own keys: at its depth, each after its `{` or a `,` + let depth = 0; + let prev = "{"; + for (let i = open[n] + 1; i < code.length; i++) { + const ch = code[i]; + if (/\s/.test(ch)) continue; + if (depth === 0 && (prev === "{" || prev === ",")) { + const key = /^(?:source|"source"|'source')\s*:/.exec(t.slice(i, i + 20)); + if (key) { + const from = i + key[0].length; + const v = jsValue(t, from); + if (v && !/\s/.test(v[0])) return { route: v[0] }; + // the value's own text, to the `,` or bracket that ends it (strings are blank in `code`) + let end = from; + for (let d = 0; end < code.length; end++) { + const x = code[end]; + if (x === "{" || x === "[" || x === "(") d++; + else if (x === "}" || x === "]" || x === ")") { + if (d === 0) break; + d--; + } else if (x === "," && d === 0) break; + } + const text = clean(t.slice(from, end), 80); + return { route: v ? v[0] : ` ${text} `, text }; + } + } + if (ch === "{" || ch === "[" || ch === "(") depth++; + else if (ch === "}" || ch === "]" || ch === ")") { + if (depth === 0) break; + depth--; + } + prev = ch; + } + } + return null; +} + +/** The folders that serve no pages: API routes, and the folders frameworks and hosts serve files from. */ +const NOT_PAGES_DIRS = String.raw`api|trpc|graphql|_next|_nuxt|_astro|_app|assets|static|fonts|\.well-known`; +/** A path that starts with one of those folders. */ +const NOT_PAGES = new RegExp(String.raw`^\/(?:${NOT_PAGES_DIRS})(?:\/|$)`, "i"); +/** One of those folders as a whole segment further in (`/:locale/api/*`, `/admin/api/(.*)`): an API's, or a page's (`/docs/api/intro`). */ +const NOT_PAGES_SEGMENT = new RegExp(`^(?:${NOT_PAGES_DIRS})$`, "i"); +/** File extensions that are not pages (a pattern such as `**\/*.@(js|css)` or `/*.png` sets headers for files). */ +const FILE_EXT = /^(?:m?js|cjs|css|map|json|wasm|onnx|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|ttc|otf|eot|txt|xml|webmanifest|mp4|webm|mp3|pdf)$/i; +/** + * A pattern for files of some kinds, at the end of its last segment: `*.js`, `*.@(js|css)`, `*.(js|css)`, + * `*.{js,css}`, and Next.js's `/:all*(svg|jpg|png)` (the group right after a wildcard, without a dot). + */ +const FILE_PATTERN = /(?:\.@?\(([\w.|]+)\)|\.\{([\w.,]+)\}|\.(\w+)|[*+?)]\(([\w.|]+)\))$/; +/** A group of plain alternatives (`(api|trpc)`, `(?:api|trpc)`, `:lang(en|fr)?`): the pattern is each in turn. */ +const ALTERNATIVES = /(?::\w+)?\((?:\?:)?([\w./-]+(?:\|[\w./-]+)*)\)([?*+])?/; + +/** + * Whether a header's path pattern takes in any of the site's pages, where GenClass runs: true, false, or null when + * that cannot be told. False for API routes (`/api/*`, `/api/:path*`, `/(api|trpc)/(.*)`, `/(api|trpc)(.*)`) and + * static files (`/assets/(.*)`, `/_next/static/*`, `**\/*.@(js|css)`, `/:all*(svg|jpg|png)`). True for `/*`, `/(.*)`, + * `/:path*`, `/((?!api).*)`, `**` and a section such as `/app/*`; an absolute URL (Cloudflare's + * `https://example.com/*`) is read by its path. Null for a pattern with one of those folders further in + * (`/:locale/api/:path*`, `/admin/api/(.*)`: most are an API's, but `/docs/api/intro` may be a page) and one read only + * in part (a space in it: a JS template's `${base}/api/:path*` or a name defined elsewhere, which the reader leaves as + * words between spaces). A group of plain alternatives is each of them: true if any is, false if all are. + */ +export function routeHasPages(route) { + if (route == null) return true; + const partly = /\s/.test(String(route)); + let r = String(route).trim(); + const origin = /^[a-z][a-z0-9+.-]*:\/\/[^/]*/i.exec(r); + if (origin) r = r.slice(origin[0].length) || "/"; + if (!r || r === "*" || r === "**") return true; + const ext = FILE_PATTERN.exec(r.split("/").pop() ?? ""); + if (ext && (ext[1] ?? ext[2] ?? ext[3] ?? ext[4]).split(/[|,]/).every((e) => FILE_EXT.test(e.split(".").pop() ?? ""))) return false; + let variants = [r]; + for (let round = 0; round < 4; round++) { + const next = []; + let grew = false; + for (const v of variants) { + const g = ALTERNATIVES.exec(v); + if (!g) { + next.push(v); + continue; + } + grew = true; + const alts = g[1].split("|"); + if (g[2] === "?" || g[2] === "*") alts.push(""); + for (const a of alts) next.push(v.slice(0, g.index) + a + v.slice(g.index + g[0].length)); + } + if (!grew || next.length > 64) break; + variants = next; + } + const kinds = variants.map((v) => { + // the literal start, before the first wildcard, placeholder, group or part not read + const literal = /^[^*:(){}[\]?!+@\s]*/.exec(v)?.[0] ?? ""; + if (NOT_PAGES.test(literal)) return false; + if (partly || v.split("/").some((s) => NOT_PAGES_SEGMENT.test(s))) return null; + return true; + }); + return kinds.includes(true) ? true : kinds.every((k) => k === false) ? false : null; +} + +/** Whether a policy's text names a directive at all (else it was not read, as a value built at run time). */ +const readable = (policy) => + String(policy) + .split(/[;,]/) + .some((part) => /^(?:[a-z-]+-src|base-uri|sandbox|form-action|frame-ancestors|report-uri|report-to|require-trusted-types-for|trusted-types|upgrade-insecure-requests|block-all-mixed-content|navigate-to|plugin-types|webrtc)$/i.test(part.trim().split(/\s+/)[0] ?? "")); + +/** + * The Content-Security-Policy strings a project sets for its pages, in the files hosts and frameworks read them + * from (and `extra`, more files relative to `dir`, as a plain HTML site's pages): [{ file, policy, route, text?, + * unsure? }]. A policy for any of the pages counts, the home page's or a section's (`/app/*`); one set only for API + * routes or static files (`/api/*`, `/assets/*`) is left out (routeHasPages), and so is one whose text could not be + * read (built at run time); a report-only policy is not read (it blocks nothing). One for a route that may not serve + * pages (`/admin/api/(.*)`, a source built at run time) has `unsure: true`, so it is not checked as the pages' + * (`text`: the route as the file writes it, when it was read only in part). + */ +export function cspIn(dir, extra = []) { + const found = []; + for (const f of [...new Set([...CSP_FILES, ...extra])]) { + const t = read(join(dir, f)); + if (!t || !/content-security-policy/i.test(t)) continue; + for (const p of policiesIn(f, t)) { + if (!readable(p.policy)) continue; + const pages = routeHasPages(p.route); + if (pages) found.push({ file: f, ...p }); + else if (pages === null) found.push({ file: f, ...p, unsure: true }); + } + } + return found; +} + +/** A policy's directives: { name: [source, lower case] }; the first of a repeated directive is the one that counts. */ +function directives(policy) { + const dirs = {}; + for (const part of String(policy).split(";")) { + const [name, ...vals] = part.trim().split(/\s+/); + if (!name) continue; + const k = name.toLowerCase(); + if (!(k in dirs)) dirs[k] = vals.filter(Boolean).map((v) => v.toLowerCase()); + } + return dirs; +} + +/** The directive that governs `d` when it is not set: CSP's fallback lists. */ +const FALLBACK = { + "connect-src": ["connect-src", "default-src"], + "script-src": ["script-src", "default-src"], + "script-src-elem": ["script-src-elem", "script-src", "default-src"], + "worker-src": ["worker-src", "child-src", "script-src", "default-src"], +}; +const listFor = (dirs, d) => { + for (const n of FALLBACK[d]) if (dirs[n]) return dirs[n]; + return null; +}; + +/** The default model's folder on jsDelivr (the runtime's src/model/host.ts DEFAULT_MODEL_BASE_URL; a test keeps them equal). */ +const MODEL_BASE = "https://cdn.jsdelivr.net/npm/@genclass/runtime-model@0.2.0/files/"; +/** + * The onnxruntime-web version the runtime asks jsDelivr for: the one it bundles, which packages/runtime/package.json + * pins exactly (src/model/backend.ts ORT_FALLBACK_VERSION; a test keeps them equal). An app's installed runtime may + * pin another (ortPinnedFrom), and that is the one its pages load. + */ +const ORT_VERSION = "1.30.0"; +/** What the default model setup fetches from jsDelivr: the model, and ONNX Runtime's wasm (its WASM or WebGPU build's). */ +const cdnFiles = (ort) => [`${MODEL_BASE}model.onnx`, ...["ort-wasm-simd-threaded.wasm", "ort-wasm-simd-threaded.asyncify.wasm"].map((f) => `https://cdn.jsdelivr.net/npm/onnxruntime-web@${ort}/dist/${f}`)]; + +/** + * The onnxruntime-web version pinned by the runtime Node finds from `dir` (its node_modules or a parent's), as the + * runtime's own fetch-model reads it; null when the runtime is not installed or names a range. + */ +function ortPinnedFrom(dir) { + for (let d = resolve(dir); ; d = dirname(d)) { + const t = read(join(d, "node_modules", "@genclass", "runtime", "package.json")); + if (t !== null) { + try { + const v = String(JSON.parse(t)?.dependencies?.["onnxruntime-web"] ?? ""); + return /^\d+\.\d+\.\d+$/.test(v) ? v : null; + } catch { + return null; + } + } + if (dirname(d) === d) return null; + } +} + +const schemeMatches = (a, b) => a === b || (a === "http" && b === "https") || (a === "ws" && /^(?:wss|https?)$/.test(b)) || (a === "wss" && b === "https"); + +/** + * Whether a source list lets `url` load (CSP 3's matching, for a page on https): `*`, `'self'` (when `self`: the URL + * is the page's own origin), scheme sources (`https:`, `blob:`), host sources with or without a scheme, a `*.` + * wildcard, a port and a path; `'strict-dynamic'` lets in what a trusted script starts (`dynamic`). Null list: no + * policy for it, so allowed. Pure. + */ +export function sourceAllows(list, url, { self = false, dynamic = false } = {}) { + if (!list) return true; + if (dynamic && list.includes("'strict-dynamic'")) return true; + let u; + try { + u = new URL(url); + } catch { + return false; + } + const scheme = u.protocol.slice(0, -1); + const network = /^(?:https?|wss?)$/.test(scheme); + const port = u.port || (/^(?:https|wss)$/.test(scheme) ? "443" : "80"); + for (const s of list) { + if (s === "*") { + if (network) return true; + continue; + } + if (s === "'self'") { + if (self) return true; + continue; + } + if (s.startsWith("'")) continue; // 'none', a nonce, a hash, a keyword + const sm = /^([a-z][a-z0-9+.-]*):$/.exec(s); + if (sm) { + if (schemeMatches(sm[1], scheme)) return true; + continue; + } + const hm = /^(?:([a-z][a-z0-9+.-]*):\/\/)?(\*|\*\.[^:/]+|[^:/*]+)(?::(\d+|\*))?(\/[^?#]*)?$/.exec(s); + if (!hm || !network) continue; + if (hm[1] ? !schemeMatches(hm[1], scheme) : !/^(?:https|wss)$/.test(scheme)) continue; + const host = u.hostname.toLowerCase(); + if (hm[2] !== "*" && (hm[2].startsWith("*.") ? !host.endsWith(hm[2].slice(1)) : host !== hm[2])) continue; + if (hm[3] !== "*" && (hm[3] ?? (hm[1] === "http" || hm[1] === "ws" ? "80" : "443")) !== port && !(hm[3] === undefined && hm[1] === "http" && port === "443")) continue; + if (hm[4] && hm[4] !== "/" && !(hm[4].endsWith("/") ? u.pathname.startsWith(hm[4]) : u.pathname === hm[4])) continue; + return true; + } + return false; +} + +/** The folder a framework serves as-is, where a self-hosted model goes (init's publicDir). */ +export function publicDirOf(project) { + if (!project) return "public"; + if (project.framework === "sveltekit") return "static"; + if (project.framework === "angular" && existsSync(join(project.dir ?? ".", "src", "assets")) && !existsSync(join(project.dir ?? ".", "public"))) return "src/assets"; + if (project.framework === "html") return existsSync(join(project.dir ?? ".", "public", "index.html")) ? "public" : ""; + return "public"; +} + +/** + * What a policy blocks of what GenClass needs: [{ need, why }]. `policy` may hold several policies (a header's + * comma-separated list): each is enforced, so what any of them blocks is a gap. `o.script`: the script tag's src + * on a script-tag setup (its worker starts from a blob: URL; the tag needs script-src); `o.publicDir`: where a + * self-hosted model would go; `o.ort`: the onnxruntime-web version the app's runtime loads (ORT_VERSION when not + * given). Pure. + */ +export function cspGaps(policy, s, o = {}) { + const gaps = []; + const need = (g) => { + if (!gaps.some((x) => x.need === g.need)) gaps.push(g); + }; + const cdn = cdnFiles(typeof o.ort === "string" && /^\d+\.\d+\.\d+$/.test(o.ort) ? o.ort : ORT_VERSION); + const rt = cmdFor(BUILD.runtimeVersion); + const pub = o.publicDir ?? "public"; + const modelDir = pub ? `${pub}/genclass-model` : "genclass-model"; + const selfHost = `${rt} fetch-model ${modelDir}, then ${rt} init --model-url /genclass-model/`; + const tag = typeof o.script === "string" && o.script ? o.script : null; + const tagUrl = (() => { + try { + return tag ? new URL(/^\/\//.test(tag) ? `https:${tag}` : tag, "https://site.invalid/").href : null; + } catch { + return null; + } + })(); + for (const one of String(policy ?? "").split(",")) { + if (!one.trim()) continue; + const dirs = directives(one); + const lets = (d, url, opts) => sourceAllows(listFor(dirs, d), url, opts); + if (s.telemetry === "on" && !lets("connect-src", "https://genclass.dev/api/v1/events")) need({ need: "connect-src https://genclass.dev", why: "the diagnostics are blocked (or set telemetry: false)" }); + if (s.telemetry === "own" && s.endpoint && !lets("connect-src", `https://${s.endpoint}/`)) need({ need: `connect-src https://${s.endpoint}`, why: "the diagnostics cannot reach your collector" }); + if (s.model === "cdn" && !cdn.every((u) => lets("connect-src", u))) need({ need: "connect-src https://cdn.jsdelivr.net", why: `the model cannot download, so GenClass observes without a diagnosis (or self-host it: ${selfHost})` }); + if (s.model === "other" && s.modelHost && !lets("connect-src", `https://${s.modelHost}/`)) need({ need: `connect-src https://${s.modelHost}`, why: "the model cannot download, so GenClass observes without a diagnosis" }); + for (const h of s.sinks ?? []) if (typeof h === "string" && h && !lets("connect-src", `https://${h}/`)) need({ need: `connect-src https://${h}`, why: "the sink cannot send" }); + if (tagUrl) { + const elem = listFor(dirs, "script-src-elem"); + const own = tagUrl.startsWith("https://site.invalid/"); + if (!elem?.includes("'strict-dynamic'") && !sourceAllows(elem, tagUrl, { self: own })) need({ need: `script-src ${own ? "'self'" : new URL(tagUrl).origin}`, why: "the script tag cannot load, so GenClass does not run" }); + } + if (s.model !== "off") { + const script = listFor(dirs, "script-src"); + if (script && !script.includes("'wasm-unsafe-eval'") && !script.includes("'unsafe-eval'")) need({ need: "script-src 'wasm-unsafe-eval'", why: "the model's WebAssembly cannot start" }); + // the model's worker: the script tag starts it from a blob: URL, a bundled app from its own origin + const worker = tag ? "blob:https://site.invalid/0" : "https://site.invalid/assets/worker.js"; + if (!lets("worker-src", worker, { self: !tag, dynamic: true })) need({ need: tag ? "worker-src blob:" : "worker-src 'self'", why: "the model's worker cannot start, so the model runs on the main thread (about 180 ms per decision; model: { inlineFallback: false } skips it instead)" }); + } + } + return gaps; +} + +// ------------------------------------------------------------------------------------------------ the checks + +/** The entry file's text with the marked import of the coding-agent link's file right after GenClass's own import (agentlink.mjs). */ +export { withAgentLink }; + +/** Whether an entry file imports other code before GenClass's (GenClass must load first to see the app start). */ +export function importedFirst(text) { + const lines = String(text ?? "").split(/\r?\n/); + for (const l of lines) { + if (!/^\s*import\b/.test(l)) continue; + if (/@genclass\/runtime|genclass\.config|genclass:init/.test(l)) return true; + return false; + } + return true; +} + +/** GenClass's script tag in the marked files: { src, rel, version } (version null when the src names none), or null. */ +function scriptTagIn(st, cwd) { + for (const f of st?.marked ?? []) { + const t = read(f) ?? ""; + for (const m of t.matchAll(/]*?\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) { + const src = m[1] ?? m[2]; + if (!/genclass[^/]*\.global|@genclass\/runtime/i.test(src)) continue; + const version = new RegExp(`@genclass/runtime@(${VERSION_RE.source})(?:/|$)`).exec(src)?.[1] ?? null; + return { src, rel: relative(cwd, f), version }; + } + } + return null; +} + +/** The command that adds GenClass's MCP server and its skill to a project without an account. */ +const MCP_INIT = () => `npx -y @genclass/mcp@${BUILD.mcpVersion} init`; +/** The skill without its marker line (each command writes its own) and with \n line ends. */ +const skillBody = (t) => String(t).replace(/\r\n/g, "\n").replace(/^\n/m, ""); + +/** + * Every check: [{ id, label, state: "ok" | "warn" | "bad" | "info", detail, fix?: string, apply?: { what, file, + * after, writes: [{ file, rel, kind, before, after, mkdir? }] } }]. + * `deps` for tests: inspect (inspectProject), creds, fetchFn, pathVersion (the PATH genclass's), listening, offline, + * runGit (git, for the repository's root). + */ +export async function checks(o = {}, deps = {}) { + const r = []; + const add = (x) => r.push(x); + const offline = !!o.offline || !!deps.offline; + const [cliTags, rtTags] = offline ? [null, null] : await Promise.all([distTags("genclass", deps.fetchFn), distTags("@genclass/runtime", deps.fetchFn)]); + + // 1. this command, and the one `genclass` runs on this machine: against the newest of the line it is on + const { version: latest, tag: cliTag } = newestFor(BUILD.version, cliTags); + add( + latest && compareVersions(BUILD.version, latest) < 0 + ? { id: "cli", label: "This command", state: "warn", detail: `${BUILD.version}; ${latest} is out`, fix: `npm install -g genclass@${cliTag}` } + : { id: "cli", label: "This command", state: "ok", detail: `${BUILD.version}${latest ? " (the newest)" : offline ? "" : " (npm not checked)"}` }, + ); + const onPath = deps.pathVersion !== undefined ? deps.pathVersion : pathVersion(); + if (onPath && compareVersions(onPath, BUILD.version) !== 0) { + const older = compareVersions(onPath, latest ?? BUILD.version) < 0; + const tag = latest ? cliTag : (channelOf(BUILD.version) ?? "latest"); + add({ id: "cli-path", label: "genclass on PATH", state: older ? "warn" : "info", detail: `typing genclass runs ${onPath}, not ${BUILD.version}`, fix: older ? `npm install -g genclass@${tag}` : undefined }); + } + const major = Number(String(process.versions.node).split(".")[0]); + add(major >= 20 ? { id: "node", label: "Node", state: "ok", detail: process.versions.node } : { id: "node", label: "Node", state: "bad", detail: `${process.versions.node}: GenClass needs Node 20 or later`, fix: "install Node 20 or later (nodejs.org)" }); + + // 2. the sign-in: the runtime and the MCP server need none; this command's setup steps need a sign-in and Pro + const rtInit = `${cmdFor(BUILD.runtimeVersion)} init`; + try { + const { readCredentialsFor } = await import("../../runtime/bin/lib/account.mjs"); + const got = deps.creds !== undefined ? { creds: deps.creds } : readCredentialsFor(); + add(got.creds ? { id: "account", label: "Signed in", state: "ok", detail: clean(got.creds.account?.email ?? got.creds.account?.github_login ?? "yes", 50) } : { id: "account", label: "Signed in", state: "info", detail: "no: the runtime and the MCP server work without an account; npx genclass setup needs a sign-in and Pro", fix: "npx genclass login" }); + } catch { + add({ id: "account", label: "Signed in", state: "info", detail: "not checked" }); + } + + // 3. the runtime in the app + const inspect = deps.inspect ?? (await import("../../runtime/bin/lib/init.mjs")).inspectProject; + let st = null; + try { + st = inspect({ cwd: o.cwd }); + } catch { + /* not a project */ + } + const cwd = st?.cwd ?? o.cwd ?? process.cwd(); + const { readSetup } = await import("./privacy.mjs"); + const setup = await readSetup({ cwd }, { inspect: () => st ?? { cwd, files: [], marked: [] } }).catch(() => null); + const html = st?.project?.framework === "html"; + const tag = st?.project?.framework && !st.fresh ? scriptTagIn(st, cwd) : null; + if (!st?.project?.framework) { + add({ id: "runtime", label: "Runtime", state: "info", detail: "this folder is not a web app GenClass recognises", fix: "run it in your app's folder (or --cwd apps/web)" }); + } else if (st.fresh) { + add({ id: "runtime", label: "Runtime", state: "bad", detail: `not added to this ${st.project.label}`, fix: `npx genclass setup (with Pro), or without an account: ${rtInit}` }); + } else { + const newest = rtTags?.beta && rtTags?.latest ? (compareVersions(rtTags.beta, rtTags.latest) > 0 ? rtTags.beta : rtTags.latest) : (rtTags?.beta ?? rtTags?.latest ?? null); + const mode = setup?.mode ?? "observe"; + if (html) { + // a plain HTML site loads the runtime from its script tag: no package, no node_modules + if (tag?.version && newest && compareVersions(tag.version, newest) < 0) add({ id: "runtime", label: "Runtime", state: "warn", detail: `the script tag in ${tag.rel} loads @genclass/runtime ${tag.version}; ${newest} is out`, fix: `put ${newest} in the script tag's src in ${tag.rel}, and update its integrity attribute (or take it out)` }); + else add({ id: "runtime", label: "Runtime", state: "ok", detail: `script tag${tag?.version ? `, @genclass/runtime ${tag.version}` : ""}${tag ? ` in ${tag.rel}` : ""}, ${mode} mode` }); + } else { + // where Node finds it from the app's folder: its node_modules or a parent's (workspaces hoist it to the root) + const have = installedVersion(cwd); + if (!have) add({ id: "runtime", label: "Runtime", state: "warn", detail: "added, but @genclass/runtime is not installed (in node_modules here or in a parent folder)", fix: `${st.project.pm ?? "npm"} install` }); + else if (newest && compareVersions(have, newest) < 0) add({ id: "runtime", label: "Runtime", state: "warn", detail: `@genclass/runtime ${have}; ${newest} is out`, fix: `npm install @genclass/runtime@${newest}` }); + else add({ id: "runtime", label: "Runtime", state: "ok", detail: `@genclass/runtime ${have}, ${mode} mode` }); + } + // GenClass's import first in the entry + const entry = (st.marked ?? []).find((f) => AUTO_IMPORT.test(read(f) ?? "")); + if (entry && !importedFirst(read(entry))) add({ id: "order", label: "Import order", state: "warn", detail: `${relative(cwd, entry)} imports other code before GenClass, so it cannot see what that code does as it starts`, fix: `move the genclass:init lines to the top of ${relative(cwd, entry)}` }); + else if (entry) add({ id: "order", label: "Import order", state: "ok", detail: `first in ${relative(cwd, entry)}` }); + if (setup) add({ id: "privacy", label: "Diagnostics", state: "info", detail: setup.telemetry === "off" ? "off: nothing goes to genclass.dev" : setup.telemetry === "own" ? `to your own collector (${setup.endpoint})` : "on: anonymous counts to genclass.dev from public hosts", fix: "npx genclass privacy (what is sent and kept, and how to send nothing)" }); + } + + // 4. the coding agent: the MCP server's pin, the skill, the link from the dev page, the bridge. The configurations + // are the ones `genclass status` reads, here and at the repository's root (where a monorepo's agent starts). + const here = real(cwd); + const root = (() => { + try { + const top = (deps.runGit ?? runGit)(["rev-parse", "--show-toplevel"], cwd); + return top ? real(top) : null; + } catch { + return null; + } + })(); + const dirs = [here, ...(root && root !== here ? [root] : [])]; + const mcp = []; + for (const d of dirs) { + for (const f of agentConfigs(d)) { + const file = join(d, f); + const t = read(file); + if (t !== null && !mcp.some((x) => real(x.file) === real(file))) mcp.push({ file, rel: relative(here, file), t }); + } + } + const pinOf = (t) => new RegExp(`@genclass/mcp@(${VERSION_RE.source})`).exec(t)?.[1] ?? null; + if (!mcp.length) add({ id: "mcp", label: "MCP server", state: "warn", detail: "your coding agent has no GenClass tools in this project", fix: `npx genclass setup (the Coding agent step, with Pro), or without an account: ${MCP_INIT()}` }); + for (const { file, rel, t } of mcp) { + const pin = pinOf(t); + if (pin && compareVersions(pin, BUILD.mcpVersion) < 0) { + const after = t.split(`@genclass/mcp@${pin}`).join(`@genclass/mcp@${BUILD.mcpVersion}`); + const what = `${rel}: @genclass/mcp ${pin} to ${BUILD.mcpVersion}`; + add({ id: "mcp", label: "MCP server", state: "warn", detail: `${rel} pins @genclass/mcp ${pin}; this command installs ${BUILD.mcpVersion}`, fix: "npx genclass doctor --fix", apply: { what, file, after, writes: [{ file, rel, kind: "modify", before: t, after }] } }); + } else add({ id: "mcp", label: "MCP server", state: "ok", detail: `${rel}${pin ? ` (@genclass/mcp ${pin})` : " (unpinned)"}` }); + } + // the skill: here, else at the root; a missing one is written here, as the Coding agent step does + const skillFile = dirs.map((d) => join(d, SKILL_PATH)).find((f) => existsSync(f)) ?? join(here, SKILL_PATH); + const skillRel = relative(here, skillFile); + const skill = read(skillFile); + const mine = skillText(); + const crlf = /\r\n/.test(skill ?? ""); + const skillApply = (what) => ({ what, file: skillFile, after: crlf ? mine.replace(/\n/g, "\r\n") : mine, writes: [{ file: skillFile, rel: skillRel, kind: skill === null ? "create" : "modify", before: skill ?? "", after: crlf ? mine.replace(/\n/g, "\r\n") : mine, mkdir: true, skill: true }] }); + const markLine = skill === null ? null : (/^$/m.exec(skill.replace(/\r\n/g, "\n"))?.[0] ?? null); + const markedBy = markLine ? pinOf(markLine) : null; + const newerPin = mcp.map((x) => pinOf(x.t)).find((p) => p && compareVersions(p, BUILD.mcpVersion) > 0) ?? null; + if (skill === null) add({ id: "skill", label: "Skill", state: mcp.length ? "warn" : "info", detail: "no GenClass skill for Claude Code in this project", fix: "npx genclass doctor --fix", apply: skillApply(`${skillRel}: the skill`) }); + else if (!skill.includes(SKILL_MARK)) add({ id: "skill", label: "Skill", state: "ok", detail: `${skillRel} (yours: the marker was removed, so it is left alone)` }); + else if (skillBody(skill) === skillBody(mine)) add({ id: "skill", label: "Skill", state: "ok", detail: skillRel }); + else if (markedBy && compareVersions(markedBy, BUILD.mcpVersion) > 0) add({ id: "skill", label: "Skill", state: "ok", detail: `${skillRel} (from @genclass/mcp ${markedBy}, newer than this command's ${BUILD.mcpVersion}: left as it is)` }); + else if (newerPin) add({ id: "skill", label: "Skill", state: "info", detail: `${skillRel} differs from this command's (@genclass/mcp ${BUILD.mcpVersion}), and the project pins the newer ${newerPin}`, fix: `npx -y @genclass/mcp@${newerPin} init (writes that version's skill)` }); + else add({ id: "skill", label: "Skill", state: "warn", detail: `${skillRel} is from another version${markedBy ? ` (@genclass/mcp ${markedBy})` : ""}`, fix: "npx genclass doctor --fix", apply: skillApply(`${skillRel}: this version's skill`) }); + if (st?.project?.framework && !st.fresh) { + let link = null; + try { + link = planAgentLink(st); + } catch { + link = null; + } + // the planner's answer first: the link's own file without the line that imports it is not a link (privacy's text + // test would count it); privacy's reading only when the planner could not run + if (link ? link.state === "linked" : setup?.agentLink) add({ id: "link", label: "Agent link", state: "ok", detail: "the dev build connects to your coding agent (connectAgent)" }); + else if (link?.state === "manual" && !link.lines?.length) { + // nothing to add for this setup (the script tag): the agent's other tools still work + add({ id: "link", label: "Agent link", state: "info", detail: `not available here: ${link.why}; your coding agent's GenClass tools still audit any page you name (genclass_scan)` }); + } else { + const planned = link?.state === "planned" ? link.changes : null; + const by = `${link?.state === "manual" ? `not added here (${link.why}): ` : ""}ask your agent "is GenClass connected?": genclass_setup prints the dev-only lines for this app`; + add({ + id: "link", + label: "Agent link", + state: "warn", + detail: "the dev page does not connect to your coding agent, so genclass_status lists no page and explore and replay cannot run", + fix: planned ? "npx genclass doctor --fix" : by, + ...(planned ? { apply: { what: planned.map((ch) => ch.what).join("; "), file: planned[0].file, after: planned[0].after, writes: planned.map((ch) => ({ file: ch.file, rel: ch.rel, kind: ch.kind ?? "modify", before: ch.before, after: ch.after })) } } : {}), + }); + } + } + const port = Number(process.env.GENCLASS_AGENT_PORT) || 47357; + const up = await (deps.listening ?? listening)(port); + add(up ? { id: "bridge", label: "Bridge", state: "ok", detail: `a GenClass MCP server listens on 127.0.0.1:${port}` } : { id: "bridge", label: "Bridge", state: "info", detail: `nothing on 127.0.0.1:${port} yet: it starts with your coding agent`, fix: "start your coding agent in this folder" }); + + // 5. what the live site lets through: every policy each file sets for the pages + if (setup && st?.project?.framework && !st.fresh) { + const pages = html ? (st.marked ?? []).filter((f) => /\.html?$/i.test(f)).map((f) => relative(cwd, f).split("\\").join("/")) : []; + try { + const byFile = new Map(); + for (const p of cspIn(cwd, pages)) byFile.set(p.file, [...(byFile.get(p.file) ?? []), p]); + const o2 = { script: tag?.src ?? null, publicDir: publicDirOf(st.project), ort: html ? null : ortPinnedFrom(cwd) }; + const gapsOf = (list) => { + const gaps = []; + for (const p of list) for (const g of cspGaps(p.policy, setup, o2)) if (!gaps.some((x) => x.need === g.need)) gaps.push(g); + return gaps; + }; + for (const [file, list] of byFile) { + const sure = list.filter((p) => !p.unsure); + const gaps = gapsOf(sure); + // a policy for a route that may not serve pages (`/admin/api/(.*)`, a source built at run time) is not checked + // as the pages', and is named only when it would block GenClass: never "bad" for what may be an API's policy + const unsure = list.filter((p) => p.unsure && gapsOf([p]).length); + const routes = [...new Set(unsure.map((p) => clean(p.text ?? p.route, 80)))]; + const one = routes.length === 1; + const left = routes.length ? `the ${one ? "policy" : "policies"} for ${routes.join(", ")} ${one ? "is" : "are"} not checked: GenClass cannot tell whether pages are served there (if they are, ${one ? "it needs" : "they need"} ${gapsOf(unsure).map((g) => g.need).join(", ")})` : ""; + if (gaps.length) add({ id: "csp", label: "Content policy", state: "bad", detail: `${file}: ${gaps.map((g) => `without ${g.need}, ${g.why}`).join("; ")}${left ? `; ${left}` : ""}`, fix: `add ${gaps.map((g) => g.need).join(", ")} to the policy in ${file}` }); + else if (sure.length) add({ id: "csp", label: "Content policy", state: "ok", detail: `${file} allows what GenClass needs${left ? `; ${left}` : ""}` }); + else if (left) add({ id: "csp", label: "Content policy", state: "info", detail: `${file}: ${left}` }); + } + } catch { + add({ id: "csp", label: "Content policy", state: "info", detail: "not checked" }); + } + } + + // 6. the test workflow, for a project with Playwright + const pkgText = read(join(cwd, "package.json")) ?? ""; + if (/@playwright\/test/.test(pkgText)) { + add(existsSync(join(cwd, ".github", "workflows", "genclass.yml")) ? { id: "workflow", label: "Test workflow", state: "ok", detail: ".github/workflows/genclass.yml" } : { id: "workflow", label: "Test workflow", state: "info", detail: "your Playwright tests do not run with reordered responses on pull requests", fix: "npx genclass setup (the Test workflow step, with Pro)" }); + } + r.app = st?.project?.name ?? null; + r.framework = st?.project?.label || null; + // the header says who is signed in, as the Signed in row does (it read "not signed in" above a signed-in row) + const who = r.find((x) => x.id === "account"); + r.account = who?.state === "ok" ? who.detail : null; + return r; +} + +/** + * The PATH a shell has, for `genclass --version`: without npx's folders and node_modules/.bin, which `npx genclass` + * puts first (name.mjs shortNameWorks skips the same). { key, value }: the variable's name (PATH, or Path on + * Windows) and the list. + */ +export function userPath(env = process.env, platform = process.platform) { + const sep = platform === "win32" ? ";" : delimiter; + const key = Object.keys(env).find((k) => k.toUpperCase() === "PATH") ?? "PATH"; + const kept = String(env[key] ?? "") + .split(sep) + .filter((d) => d && !/[\\/]_npx[\\/]/.test(d) && !/node_modules[\\/]\.bin[\\/]?$/.test(d)); + return { key, value: kept.join(sep) }; +} + +/** The version of the `genclass` the shell runs, or null (not installed, or it did not answer in 4 s). */ +function pathVersion() { + try { + const p = userPath(); + const env = { ...process.env, GENCLASS_NO_INSTALL: "1" }; + for (const k of Object.keys(env)) if (k.toUpperCase() === "PATH") delete env[k]; + env[p.key] = p.value; + const r = spawnSync(process.platform === "win32" ? "genclass.cmd" : "genclass", ["--version"], { encoding: "utf8", timeout: 4000, shell: process.platform === "win32", env }); + return new RegExp(`genclass (${VERSION_RE.source})`).exec(r.stdout ?? "")?.[1] ?? null; + } catch { + return null; + } +} + +const MARK = { ok: () => c.green(sym.ok), warn: () => c.yellow(sym.warn), bad: () => c.red(sym.cross), info: () => c.gray(sym.dot) }; + +/** + * `genclass doctor [--fix] [--yes] [--json] [--offline]`. Exit 0 when nothing is wrong or warned about, else 1. + * --json prints one object: { ok, checks } and, with --fix, { fixed, failed, skipped } (what was written, what could + * not be, and what was not because --yes was not given); the report and the changes go to stderr then. + */ +export async function doctor(o = {}, deps = {}) { + const list = await checks(o, deps); + const wrong = list.filter((x) => x.state === "bad" || x.state === "warn"); + const shown = () => list.map(({ apply, ...x }) => ({ ...x, fixable: !!apply })); + if (o.json && !o.fix) { + out(JSON.stringify({ ok: wrong.length === 0, checks: shown() }, null, 2)); + return wrong.length ? 1 : 0; + } + if (!o.json) return (await report(list, o)).code; + // --json --fix: the report and each change on stderr, so stdout is the JSON alone and parses; nothing is asked + const write = process.stdout.write; + let r; + process.stdout.write = process.stderr.write.bind(process.stderr); + try { + r = await report(list, { ...o, ask: false }); + } finally { + process.stdout.write = write; + } + out(JSON.stringify({ ok: r.code === 0, checks: shown(), fixed: r.fixed, failed: r.failed, skipped: r.skipped }, null, 2)); + return r.code; +} + +/** Shows one planned write: its diff, or a new skill file by name and size. */ +function showWrite(w) { + if (w.kind === "create" && w.skill) { + out(` ${c.bold(w.rel)} ${c.gray("(")}${c.green("new file")}${c.gray(")")}`); + out(` ${c.gray(`${w.after.replace(/\r?\n$/, "").split("\n").length} lines: the procedure your coding agent follows with GenClass's tools (@genclass/mcp ${BUILD.mcpVersion}'s skill)`)}`); + out(); + return; + } + printChange({ file: w.rel ?? w.file, kind: w.kind ?? "modify", before: w.before ?? "", after: w.after }); +} + +/** The human report, and with --fix the writes: { code, fixed, failed, skipped } (each a list of `what`). */ +async function report(list, o) { + const wrong = list.filter((x) => x.state === "bad" || x.state === "warn"); + const fixable = list.filter((x) => x.apply); + const done = { fixed: [], failed: [], skipped: [] }; + header({ app: list.app, framework: list.framework, account: list.account }); + out(); + const wLabel = Math.max(...list.map((x) => x.label.length)); + for (const x of list) { + const lines = wrap(x.detail, width() - 9 - wLabel); + out(` ${MARK[x.state]()} ${x.label.padEnd(wLabel)} ${x.state === "ok" ? c.gray(lines[0] ?? "") : (lines[0] ?? "")}`); + for (const l of lines.slice(1)) out(` ${" ".repeat(wLabel)} ${x.state === "ok" ? c.gray(l) : l}`); + if (x.fix && x.state !== "ok") for (const l of wrap(`${sym.arrow ?? "->"} ${x.fix}`, width() - 9 - wLabel)) out(` ${" ".repeat(wLabel)} ${c.cyan(l)}`); + } + out(); + if (!o.fix) { + if (fixable.length) note(`${fixable.length === 1 ? "One of these is" : `${fixable.length} of these are`} GenClass's own files and lines: npx genclass doctor --fix does ${fixable.length === 1 ? "it" : "them"}, after showing ${fixable.length === 1 ? "it" : "them"}.`); + else if (!wrong.length) good("Everything GenClass added is in place."); + out(); + return { code: wrong.length ? 1 : 0, ...done }; + } + if (!fixable.length) { + note("Nothing here is GenClass's own to fix: the lines above say what to run."); + out(); + return { code: wrong.length ? 1 : 0, ...done }; + } + out(` ${c.bold("To fix")}`); + for (const x of fixable) { + // one item per fix, wrapped under its first word (a long file name used to run past the window) + const lines = wrap(x.apply.what, width() - 8); + out(` ${sym.dot} ${lines[0] ?? ""}`); + for (const l of lines.slice(1)) out(` ${l}`); + } + out(); + // each change itself, before anything is written (with --yes too, so an agent that ran it sees what changed) + for (const x of fixable) for (const w of x.apply.writes ?? [x.apply]) showWrite(w); + const ask = o.ask !== false && interactive(); + const yes = o.yes || (ask && (await agree("Write these?"))); + if (!yes) { + note(ask ? "Nothing was written." : o.ask === false ? "Nothing was written: run it with --yes." : "Nothing was written: run it with --yes, or on a terminal."); + out(); + done.skipped = fixable.map((x) => x.apply.what); + return { code: 1, ...done }; + } + for (const x of fixable) { + try { + for (const w of x.apply.writes ?? [x.apply]) { + if (w.mkdir) mkdirSync(dirname(w.file), { recursive: true }); + writeFileSync(w.file, w.after); + } + good(`Wrote ${x.apply.what}`); + done.fixed.push(x.apply.what); + } catch (e) { + done.failed.push(x.apply.what); + warn(`Could not write ${x.apply.what}: ${clean(e?.message ?? e, 100)}`); + } + } + const wrote = (id) => fixable.some((x) => x.id === id && done.fixed.includes(x.apply.what)); + // the agent can list the page only once its configuration names GenClass's server + const agentHasTools = list.some((x) => x.id === "mcp" && (x.state === "ok" || x.apply)); + if (wrote("link")) + note( + agentHasTools + ? 'Reload the dev page once, then ask your coding agent "is GenClass connected?": genclass_status lists the page.' + : `Reload the dev page once. Your coding agent has no GenClass tools in this project yet: ${MCP_INIT()} adds GenClass's server (or npx genclass setup, the Coding agent step, with Pro); restart the agent, then ask it "is GenClass connected?".`, + ); + if (wrote("mcp")) note("Restart your coding agent in this folder so it starts the new MCP server."); + out(); + // what is left is the person's to do (the lines above say what): still exit 1 then + return { code: done.failed.length || wrong.some((x) => !x.apply) ? 1 : 0, ...done }; +} diff --git a/packages/cli/src/flake.mjs b/packages/cli/src/flake.mjs new file mode 100644 index 00000000..1cadc470 --- /dev/null +++ b/packages/cli/src/flake.mjs @@ -0,0 +1,1178 @@ +// `genclass flake`: "is this Playwright test flaky, or is my app racy?" It runs the project's own Playwright suite +// through the project's own @genclass/playwright (its command, genclass-playwright-run): by default once with +// responses in their natural order, then once per seed (--runs, default 5) with the app's API responses held for a +// seeded time, so they can arrive in another order (--seed, --no-baseline and --no-chaos change that: parseFlakeArgs), +// and reads the race file that run writes for each test and seed. Per test it says one of four things, from what was +// measured only: +// - passed every time; +// - racy: it failed on some runs, and on a failing run GenClass recorded a race (a late response that wrote over +// newer data, a request sent again while the identical one was in flight, or a model diagnosis about order): +// which request, on which seeds (or in the natural order), and the command that runs it again: the replay of a +// failing seed, one with the race on it when there is one, else the natural order again (--no-chaos); +// - flaky: it failed on some runs and GenClass recorded no race on any failing run (or could not watch them): +// likely the test itself (a fixed wait, a timeout, state shared between tests); +// - broken: it failed on every run, in the natural order too. Without a natural-order run (--seed, --no-baseline) +// a test that failed on every seed with no race seen is listed apart, as failing on every seed with the order +// not checked, and the command that checks it is given; it is never said to fail "in the natural order too". +// When a test did not pass it ends with one command to run (finalReplay: the replay of a racy test's failing seed, +// else of a flaky test's, else the first failing test's own command) and the prompt for the coding agent: printed, or +// on a terminal offered to start the agent with, to copy or to print. +// +// Invariants: +// - Local and free: nothing is sent anywhere, no sign-in, no Pro (cli.mjs FREE_COMMANDS). It runs the person's tests +// with the Playwright and @genclass/playwright installed in their project; it never installs anything, and when +// either (or @genclass/runtime) is missing or unusable (too old, not built) it prints the exact install line and +// exits 2 without running anything. A runtime the app already lists in its dependencies (it ships GenClass) is +// installed without -D, so it stays there; everything else is a dev dependency. +// - A test is called racy only when the race file of one of its failing runs shows a race. A run GenClass saw +// nothing on is said as GenClass seeing no race there ("GenClass saw no race on the failing run"), never as "there +// is no race"; a run it could not watch (no race file, the agent entry not connected) is said as that. +// - It writes nothing in the project but what the run itself writes (Playwright's test-results, the race files in +// test-results/genclass). Its reporter and the results it collects live in a temporary folder removed at the end. +// - The person's own reporters stay on a Playwright that has --add-reporter: ours is added on top. An older one only +// has --reporter, which replaces the reporters in the playwright.config for that run: it gets ours and the ones +// given to this command with --reporter (Playwright then adds its own terminal output), and the run says so +// before it starts when none were given. The HTML report never opens a browser and waits +// (PLAYWRIGHT_HTML_OPEN=never). Retries are off unless --retries is passed: a retry would hide the failure this +// command is looking for. +// - Every screen fits the window (58 columns and up): the help, the results, the missing-package screen and the ones +// where nothing could be judged. Prose folds at its spaces; a word longer than a line (an address, a long path) +// stays whole, and so do an option with its value and a command named in a sentence (wrapKeeping, tui.mjs wrap): +// `--cwd apps/web`, `"npx playwright test"`, `npx genclass flake`. The results' title folds only between its +// phrases, so no word is left on a line of its own. A message on stderr that starts `genclass flake:` (an error, +// --print with nothing to fix) is one line, as wide as it is. +// - A command to copy is never folded (a paste of a folded one would run its first line alone): an install line, the +// replay under "Replay seed N of ...", and each test's own ("replay seed N:", "run it again:", "run it alone:", +// "with the natural order too:"), which follows its label when the two fit the window and stands on the line under +// it when they do not (commandLines). On a line of its own it starts further left to fit where it can and is +// printed whole, wider than the window when it is (copyLine), as the prompt for the coding agent is. +// - With --json every exit but --help's (the help is text) prints one JSON object on stdout, the ones where nothing +// could be judged included. +// - Text that came from the run (test titles, error messages, evidence lines) goes through clean() before it is +// printed or put into the prompt, and the prompt says it is data about the app, not instructions. +// - Exit code: 0 when every test passed every time (and after --help), 1 when one did not, 2 when nothing could be +// judged (a missing package or browser, a usage error, a run that could not start or ran no test), 128 plus the +// signal when the run was interrupted. + +import { spawn as spawnChild } from "node:child_process"; +import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import { constants, tmpdir } from "node:os"; +import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; +import { detectPackageManager, readJson } from "../../runtime/bin/lib/detect.mjs"; +import { c, err, interactive, out, sym } from "../../runtime/bin/lib/ui.mjs"; +import { clean, good, note, PROMPT, typed, warn, width, wrap } from "./tui.mjs"; + +/** Seeds per test unless --runs says otherwise. */ +export const DEFAULT_RUNS = 5; +/** The most seeds one command runs per test. */ +export const MAX_RUNS = 50; +/** The variable that tells our reporter where to write (one JSON line per test attempt). */ +export const RESULTS_ENV = "GENCLASS_FLAKE_RESULTS"; +/** The race files' format (@genclass/playwright src/types.ts). */ +export const RACES_SCHEMA = "genclass-races/1"; +/** A race file larger than this is not read (the format's own limit is 64 KB). */ +const MAX_RACE_FILE = 256 * 1024; +/** At most this many race files are read from one run. */ +const MAX_RACE_FILES = 20_000; +/** Model diagnoses that are about the order things happened in (a witness always is). */ +const ORDER_DIAGNOSES = new Set(["stale", "duplicate", "conflict"]); + +/** The help's parts; flakeUsage() lays them out for the window. */ +const HELP = { + // the usage line in the parts it may break between + head: ["usage: npx genclass flake", "[playwright test arguments ...]", "[--runs N]", "[--seed N]", "[--json]"], + intro: "Is a failing Playwright test flaky, or is your app racy? This runs your own suite with your own Playwright and @genclass/playwright: once with responses in their natural order, then once per seed with your app's API responses held for a seeded time, so they can arrive in another order. Then it says, for each test:", + verdicts: [ + ["passed", "it passed every time"], + ["racy", "it failed on some runs, and on a failing run GenClass saw a race: which request came late, the seed, and the command that replays exactly that seed"], + ["flaky", "it failed on some runs and GenClass saw no race there: likely the test itself"], + ["broken", "it failed every time, in the natural order too (with --seed or --no-baseline there is no natural-order run: it failed on every seed, and whether the order matters is not checked)"], + ], + options: [ + ["--runs N", `seeds per test (default ${DEFAULT_RUNS}, at most ${MAX_RUNS})`], + ["--seed N", "the first seed (default 1), without the natural-order run; alone it replays that one seed"], + ["--no-baseline", "no natural-order run first"], + ["--no-chaos", "every run in the natural order: plain repeats, nothing held"], + ["--json", "the same as data"], + ["--print", "only the prompt for your coding agent"], + ["--cwd ", "the folder with your playwright.config"], + ], + tail: 'Every other argument goes to "playwright test": a file, file:line, --grep, --project, -c ... Retries are off unless you pass --retries (a retry would hide the failure). Your reporters stay on a Playwright with --add-reporter; an older one runs only ours and the ones you pass with --reporter. Local and free: nothing is sent anywhere, no sign-in. It needs, in the project, Playwright and:', + install: "npm install -D @genclass/playwright @genclass/runtime@beta", + after: "(an app that lists @genclass/runtime in its dependencies installs it without -D, so it stays there)", +}; + +/** + * The command's help, laid out for `cols` columns (the window's): prose wrapped, the verdicts and the options as + * name and words with the words wrapped under themselves, every line within `cols` - 2; the install line is kept + * whole (it starts further left when it would not fit). + */ +export function flakeUsage(cols = width()) { + const w = Math.max(40, cols - 2); + const lines = []; + const prose = (t, first = "", next = first) => wrapKeeping(t, w - next.length, ['"playwright test"']).forEach((l, i) => lines.push(`${i ? next : first}${l}`)); + const table = (rows, pad) => { + for (const [name, what] of rows) wrap(what, w - 2 - pad).forEach((l, i) => lines.push(`${i ? " ".repeat(2 + pad) : ` ${name.padEnd(pad)}`}${l}`)); + }; + let head = ""; + for (const part of HELP.head) { + if (head && head.length + 1 + part.length > w) { + lines.push(head); + head = ` ${part}`; + } else head = head ? `${head} ${part}` : part; + } + lines.push(head, ""); + prose(HELP.intro); + table(HELP.verdicts, 9); + lines.push(""); + table(HELP.options, 16); + lines.push(""); + prose(HELP.tail); + lines.push(`${" ".repeat(Math.max(0, Math.min(2, w - HELP.install.length)))}${HELP.install}`); + prose(HELP.after, " "); + return `${lines.join("\n")}\n`; +} + +/** The command's help at the default width (80 columns), for tests and anything that wants it as one string. */ +export const FLAKE_USAGE = flakeUsage(80); + +// ------------------------------------------------------------------------------------------------- arguments + +/** + * The command's arguments: its own options, and every other argument for "playwright test" (`pw`), in order. A + * `--reporter` is taken out of `pw` (the run puts it back with ours); `--repeat-each` is the same as `--runs`. + * After a bare `--` everything goes to Playwright. + * @returns {{ runs: number, seed: number | null, baseline: boolean, chaos: boolean, json: boolean, print: boolean, help: boolean, cwd: string | null, pw: string[], config: string | null, retries: boolean, reporter: string | null, error: string | null }} + */ +export function parseFlakeArgs(argv) { + const o = { runs: DEFAULT_RUNS, seed: null, baseline: true, chaos: true, json: false, print: false, help: false, cwd: null, pw: [], config: null, retries: false, reporter: null, error: null }; + let runsGiven = false; + const whole = (name, v, min, max) => { + if (v === undefined || !/^\d+$/.test(String(v)) || Number(v) < min || Number(v) > max) { + o.error ??= `${name} needs a whole number from ${min} to ${max}${v === undefined ? "" : ` (got ${clean(v, 20)})`}`; + return null; + } + return Number(v); + }; + for (let i = 0; i < argv.length; i++) { + const a = String(argv[i]); + if (a === "--") { + o.pw.push(...argv.slice(i + 1).map(String)); + break; + } + const eq = a.startsWith("--") ? a.indexOf("=") : -1; + const key = eq > 0 ? a.slice(0, eq) : a; + const value = () => (eq > 0 ? a.slice(eq + 1) : argv[++i]); + if (key === "--help" || key === "-h") o.help = true; + else if (key === "--runs" || key === "--repeat-each") { + const n = whole("--runs", value(), 1, MAX_RUNS); + if (n !== null) { + o.runs = n; + runsGiven = true; + } + } else if (key === "--seed") { + const n = whole("--seed", value(), 0, 2 ** 31 - 1); + if (n !== null) o.seed = n; + } else if (key === "--no-baseline") o.baseline = false; + else if (key === "--no-chaos") o.chaos = false; + else if (key === "--json") o.json = true; + else if (key === "--print") o.print = true; + // one of the genclass command's options for every command (its help lists it); this one opens no browser, and + // "playwright test" would refuse the word + else if (key === "--no-browser") continue; + else if (key === "--cwd") { + const v = value(); + if (!v) o.error ??= "--cwd needs a folder"; + else o.cwd = String(v); + } else if (key === "--reporter") { + const v = value(); + if (!v) o.error ??= "--reporter needs a value"; + else o.reporter = String(v); + } else { + // Playwright's own, passed on in order; two are remembered: the config (the replay command names it) and + // whether retries were asked for (else the run turns them off) + if ((a === "--config" || a === "-c") && i + 1 < argv.length) { + o.config = String(argv[i + 1]); + o.pw.push(a, String(argv[++i])); + continue; + } + if (a.startsWith("--config=")) o.config = a.slice("--config=".length); + else if (/^-c./.test(a)) o.config = a.slice(2); + if (key === "--retries") o.retries = true; + o.pw.push(a); + } + } + // a seed given is a replay: no natural-order run, and one seed unless --runs says more + if (o.seed !== null) { + o.baseline = false; + if (!runsGiven) o.runs = 1; + } + if (!o.chaos) o.baseline = false; + return o; +} + +// ------------------------------------------------------------------------------------------------- the tools + +const resolveFrom = (dir, spec) => { + try { + return createRequire(join(dir, "noop.js")).resolve(spec); + } catch { + return null; + } +}; + +/** Whether the `playwright` package in `dir` has `playwright test --add-reporter` (read from its own command's file: newer versions have it, older ones only --reporter). */ +export function supportsAddReporter(dir) { + for (const f of ["lib/program.js", "lib/cli/program.js"]) { + try { + if (readFileSync(join(dir, f), "utf8").includes("--add-reporter")) return true; + } catch { + /* not this layout */ + } + } + return false; +} + +/** + * What this project has of what the run needs, resolved from `cwd` the way Node resolves the project's imports: + * Playwright (`@playwright/test`, else `playwright`), @genclass/playwright with its run command, and + * @genclass/runtime next to it or in the project (GENCLASS_RUNTIME_DIR names one by hand). + */ +export function findTools(cwd, env = process.env) { + const version = (file) => (file ? (readJson(file)?.version ?? null) : null); + const testPkg = resolveFrom(cwd, "@playwright/test/package.json"); + const pwPkg = (testPkg && resolveFrom(dirname(testPkg), "playwright/package.json")) ?? resolveFrom(cwd, "playwright/package.json"); + const playwright = testPkg || pwPkg ? { name: testPkg ? "@playwright/test" : "playwright", version: version(testPkg ?? pwPkg), addReporter: pwPkg ? supportsAddReporter(dirname(pwPkg)) : false } : null; + const gpPkg = resolveFrom(cwd, "@genclass/playwright/package.json"); + let genclassPlaywright = null; + if (gpPkg) { + const dir = dirname(gpPkg); + const bin = join(dir, "bin", "genclass-playwright-run.mjs"); + genclassPlaywright = { dir, version: version(gpPkg), bin: existsSync(bin) && existsSync(join(dir, "dist", "run.js")) ? bin : null }; + } + let runtime = null; + if (env.GENCLASS_RUNTIME_DIR?.trim()) { + const dir = resolve(cwd, env.GENCLASS_RUNTIME_DIR.trim()); + runtime = { version: null, dir, given: true, ok: existsSync(join(dir, "genclass.global.js")), why: "no-build" }; + } else { + const rtPkg = (gpPkg && resolveFrom(dirname(gpPkg), "@genclass/runtime/package.json")) ?? resolveFrom(cwd, "@genclass/runtime/package.json"); + if (rtPkg) { + const dist = join(dirname(rtPkg), "dist"); + const built = existsSync(join(dist, "genclass.global.js")); + runtime = { version: version(rtPkg), dir: dist, given: false, ok: built && existsSync(join(dist, "agent.js")), why: built ? "no-agent" : "no-build" }; + } + } + return { playwright, genclassPlaywright, runtime }; +} + +/** + * The add command of the project's package manager: for dev dependencies, or with `dev` false a plain add (which + * keeps a package the project lists in its dependencies there). + */ +export function addCommand(pm, pkgs, dev = true) { + const list = pkgs.join(" "); + if (pm === "pnpm") return `pnpm add ${dev ? "-D " : ""}${list}`; + if (pm === "yarn") return `yarn add ${dev ? "-D " : ""}${list}`; + if (pm === "bun") return `bun add ${dev ? "-d " : ""}${list}`; + return `npm install ${dev ? "-D " : ""}${list}`; +} + +/** Where a package.json lists @genclass/runtime: "dependencies" (an app that ships GenClass), "devDependencies", or null. */ +export function runtimeListed(pkg) { + const has = (k) => !!pkg && typeof pkg[k] === "object" && pkg[k] !== null && Object.hasOwn(pkg[k], "@genclass/runtime"); + return has("dependencies") ? "dependencies" : has("devDependencies") ? "devDependencies" : null; +} + +/** + * What is missing for a run, each with the exact line that installs it: [{ what, why, run }]. Empty when the run can + * start. `pm`: the project's package manager. `listed`: where the project's package.json lists @genclass/runtime + * (runtimeListed): in its dependencies, the runtime is installed without -D, so a production install keeps it. + */ +export function missingTools(tools, pm = "npm", listed = null) { + const miss = []; + const named = (pkg, v) => (v ? `${pkg} ${v}` : pkg); + if (!tools.playwright) miss.push({ what: "Playwright", why: "your tests run with your own Playwright, and this project has none", run: [addCommand(pm, ["@playwright/test"]), "npx playwright install chromium"] }); + const gp = tools.genclassPlaywright; + const rt = tools.runtime; + const needRuntime = !rt || !rt.ok; + const shipped = listed === "dependencies"; + if (!gp || !gp.bin) { + const why = gp ? `the installed ${named("@genclass/playwright", gp.version)} has no built genclass-playwright-run command` : "it runs your suite with GenClass on the pages your tests open"; + const run = needRuntime && shipped ? [addCommand(pm, ["@genclass/playwright"]), addCommand(pm, ["@genclass/runtime@beta"], false)] : [addCommand(pm, ["@genclass/playwright", ...(needRuntime ? ["@genclass/runtime@beta"] : [])])]; + miss.push({ what: "@genclass/playwright", why, run }); + } else if (needRuntime) { + const why = !rt ? "@genclass/playwright puts it on the pages your tests open" : rt.given ? `GENCLASS_RUNTIME_DIR names ${rt.dir}, which has no genclass.global.js` : rt.why === "no-build" ? `the installed ${named("@genclass/runtime", rt.version)} has no build (dist/genclass.global.js)` : `the installed ${named("@genclass/runtime", rt.version)} has no agent entry: 0.3.0-beta.1 or later is needed`; + miss.push({ what: "@genclass/runtime", why, run: [addCommand(pm, ["@genclass/runtime@beta"], !shipped)] }); + } + return miss; +} + +// ------------------------------------------------------------------------------------------------- the reporter + +/** + * The Playwright reporter the run adds: one JSON line per test attempt, appended to the file GENCLASS_FLAKE_RESULTS + * names, plus Playwright's own errors and how the run ended. CommonJS with no imports but node:fs, so every + * Playwright from 1.40 loads it; it prints nothing and never throws into the run. + */ +export const REPORTER_SOURCE = `"use strict"; +// Written by \`genclass flake\` for one run of your suite and removed when the run ends: what Playwright reported for +// each test attempt, one JSON line each, appended to the file ${RESULTS_ENV} names. It prints nothing. +const fs = require("node:fs"); +const file = process.env.${RESULTS_ENV}; +function put(o) { + if (!file) return; + try { fs.appendFileSync(file, JSON.stringify(o) + "\\n"); } catch (e) { /* the run goes on */ } +} +function text(e) { + const m = e && (e.message || e.value); + return typeof m === "string" ? m.slice(0, 2000) : null; +} +class GenClassFlakeReporter { + printsToStdio() { return false; } + onTestEnd(test, result) { + try { + let project = ""; + try { const p = test.parent && test.parent.project && test.parent.project(); project = (p && p.name) || ""; } catch (e) { /* none */ } + const loc = test.location || {}; + put({ t: "test", id: test.id, titlePath: test.titlePath(), project: project, file: loc.file || "", line: loc.line || 0, column: loc.column || 0, repeat: test.repeatEachIndex || 0, retry: result.retry || 0, status: result.status, expected: test.expectedStatus, error: text(result.error), ms: result.duration }); + } catch (e) { /* the run goes on */ } + } + onError(error) { put({ t: "error", error: text(error) }); } + onEnd(result) { put({ t: "end", status: result && result.status }); } +} +module.exports = GenClassFlakeReporter; +`; + +/** The lines our reporter wrote: { tests, errors, end }. Lines that are not ours are skipped. */ +export function readResults(text) { + const tests = []; + const errors = []; + let end = null; + for (const line of String(text ?? "").split("\n")) { + if (!line.trim()) continue; + let x; + try { + x = JSON.parse(line); + } catch { + continue; + } + if (!x || typeof x !== "object") continue; + if (x.t === "test" && typeof x.id === "string" && Array.isArray(x.titlePath)) tests.push(x); + else if (x.t === "error" && x.error) errors.push(String(x.error)); + else if (x.t === "end") end = typeof x.status === "string" ? x.status : null; + } + return { tests, errors, end }; +} + +// ------------------------------------------------------------------------------------------------- the race files + +const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : ""); + +/** + * The race files directly inside `dir` ("genclass-races/1", read as data and bounded): [{ name, test, seed, + * signatures, fixture, location }]. Anything else there is left alone. Never throws. + */ +export function readRaceDir(dir) { + let names = []; + try { + names = readdirSync(dir).filter((n) => n.toLowerCase().endsWith(".json")).sort().slice(0, MAX_RACE_FILES); + } catch { + return []; + } + const files = []; + for (const name of names) { + try { + const p = join(dir, name); + const st = statSync(p); + if (!st.isFile() || st.size > MAX_RACE_FILE) continue; + const f = JSON.parse(readFileSync(p, "utf8")); + if (!f || typeof f !== "object" || f.schema !== RACES_SCHEMA || typeof f.test !== "string" || !Number.isInteger(f.seed) || !Array.isArray(f.signatures)) continue; + const signatures = f.signatures + .filter((s) => s && typeof s === "object" && typeof s.sig === "string") + .slice(0, 200) + .map((s) => ({ sig: str(s.sig, 600), trigger: str(s.trigger, 100), diagnosis: str(s.diagnosis, 100), op: str(s.op, 300), confidence: typeof s.confidence === "number" && Number.isFinite(s.confidence) ? Math.min(1, Math.max(0, s.confidence)) : 0, evidence: str(s.evidence, 2000) })); + const fx = f.fixture && typeof f.fixture === "object" ? f.fixture : null; + files.push({ name, test: str(f.test, 1000), seed: f.seed, signatures, fixture: fx ? { model: str(fx.model, 20), agent: fx.agent === null ? null : str(fx.agent, 200) || "unknown", chaosApplied: Number.isInteger(fx.chaosApplied) ? fx.chaosApplied : null } : null }); + } catch { + /* not a race file we can read */ + } + } + return files; +} + +/** The race file of one test attempt: by the test's id, seed and retry in its name (the fixture's racesFileName). */ +export function raceFileFor(files, r, seed) { + const id = String(r.id).replace(/[^A-Za-z0-9_-]+/g, "") || "0"; + const suffix = `-${id}-s${seed}${r.retry > 0 ? `-r${r.retry}` : ""}.json`; + return files.find((f) => f.name.endsWith(suffix) && f.seed === seed) ?? null; +} + +/** Whether a signature is about the order things happened in: a witness (a fact), or the model's stale, duplicate or conflict. */ +export const isRace = (s) => s.trigger === "witness" || ORDER_DIAGNOSES.has(s.diagnosis); + +/** A race signature in words: "a late GET /api/search response wrote over newer data". */ +export function raceWords(s) { + if (s.trigger === "witness" && s.diagnosis === "overwrote-newer") return `a late ${s.op} response wrote over newer data`; + if (s.trigger === "witness" && s.diagnosis === "identical-in-flight") return `${s.op} was sent again while the identical request was in flight`; + if (s.trigger === "witness") return `${s.diagnosis} on ${s.op}`; + return `the model's diagnosis ${s.diagnosis} (${Math.round(s.confidence * 100)}%) on ${s.op}`; +} + +// ------------------------------------------------------------------------------------------------- the verdicts + +/** "2, 4 and 5". */ +export function listWords(xs) { + const a = xs.map(String); + return a.length <= 1 ? (a[0] ?? "") : `${a.slice(0, -1).join(", ")} and ${a[a.length - 1]}`; +} + +/** "seeds 1 to 5", "seed 3", "seeds 2, 4 and 9". */ +export function seedWords(seeds) { + const s = [...seeds].sort((a, b) => a - b); + if (s.length === 1) return `seed ${s[0]}`; + const contiguous = s.length > 2 && s.every((v, i) => i === 0 || v === s[i - 1] + 1); + return contiguous ? `seeds ${s[0]} to ${s[s.length - 1]}` : `seeds ${listWords(s)}`; +} + +const shell = (s) => (/^[\w./:@%+=,-]+$/.test(s) ? s : JSON.stringify(s)); + +/** The first line of an error message, without colours or control characters. */ +export const firstLine = (e) => clean(String(e ?? "").split("\n").find((l) => clean(l, 400)) ?? "", 160); + +/** An error in one line: its first line, and Playwright's Expected and Received lines when it has them. */ +export function errorLine(e) { + const lines = String(e ?? "").split("\n").map((l) => clean(l, 200)); + const head = lines.find(Boolean) ?? ""; + const said = lines.filter((l) => /^(Expected|Received)( string| pattern| substring| value)?:/.test(l)).slice(0, 2); + return clean([head, ...said].join("; "), 260); +} + +/** + * Every test's verdict from the runs: [{ order: "natural" | "seed", seedBase, results, races }] (the results our + * reporter wrote, the race files that run left), with `cwd` for display paths. Pure. + */ +export function judge(runs, o = {}) { + const cwd = o.cwd ?? process.cwd(); + const byKey = new Map(); + for (const run of runs) { + for (const r of run.results) { + if (r.status === "skipped" || r.status === "interrupted") continue; + const titles = r.titlePath.length > 3 ? r.titlePath.slice(3) : r.titlePath.slice(-1); + const key = [r.project, r.file, r.line, r.column, titles.join("\u0000")].join("\u0001"); + let t = byKey.get(key); + if (!t) { + const rel = r.file ? relative(cwd, r.file) : ""; + const file = (rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : r.file).split(sep).join("/"); + t = { key, project: String(r.project ?? ""), file, line: Number(r.line) || 0, title: titles.map((x) => clean(x, 200)).join(" › "), runs: [] }; + byKey.set(key, t); + } + const seed = run.order === "natural" ? 1 + (Number(r.repeat) || 0) : run.seedBase + (Number(r.repeat) || 0); + const file = raceFileFor(run.races, r, seed); + const watched = !!file && (!file.fixture || file.fixture.agent === null || file.fixture.model === "load"); + const why = !file ? "no race file: the test opened no page GenClass could watch" : watched ? null : `the page's GenClass agent was not connected (${clean(file.fixture.agent, 60)})`; + t.runs.push({ + order: run.order, + seed: run.order === "natural" ? null : seed, + repeat: Number(r.repeat) || 0, + retry: Number(r.retry) || 0, + ok: r.status === r.expected, + status: String(r.status), + error: r.status === r.expected ? null : errorLine(r.error), + // Playwright's own advice when its browsers are not installed (the whole message, not its first line) + noBrowser: r.status !== r.expected && /npx playwright install/i.test(String(r.error ?? "")), + watched, + why, + raceFile: file?.name ?? null, + races: file ? file.signatures.filter(isRace) : [], + other: file ? file.signatures.filter((s) => !isRace(s)) : [], + }); + } + } + const tests = [...byKey.values()].map((t) => verdictOf(t, o)); + const order = { racy: 0, flaky: 1, broken: 2, passed: 3 }; + tests.sort((a, b) => order[a.verdict] - order[b.verdict] || (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line || (a.project < b.project ? -1 : a.project > b.project ? 1 : 0))); + const totals = { tests: tests.length, passed: 0, racy: 0, flaky: 0, broken: 0 }; + for (const t of tests) totals[t.verdict]++; + return { tests, totals, config: o.config ?? null, cwdArg: o.cwdArg ?? null }; +} + +function verdictOf(t, o) { + const failing = t.runs.filter((r) => !r.ok); + const passing = t.runs.filter((r) => r.ok); + const natural = t.runs.filter((r) => r.order === "natural"); + const seeded = t.runs.filter((r) => r.order === "seed"); + // every race seen on a failing run, grouped by signature, with the seeds it was seen on, failing and passing + const races = new Map(); + for (const r of t.runs) { + for (const s of r.races) { + let g = races.get(s.sig); + if (!g) { + g = { ...s, words: clean(raceWords(s), 300), evidence: clean(s.evidence, 400), failing: [], passing: [], naturalFailing: false, naturalPassing: false }; + races.set(s.sig, g); + } + if (r.order === "natural") g[r.ok ? "naturalPassing" : "naturalFailing"] = true; + else g[r.ok ? "passing" : "failing"].push(r.seed); + } + } + const onFailing = [...races.values()].filter((g) => g.failing.length || g.naturalFailing); + // racy: a race on a failing run, and either a run that passed or no natural-order run to say the order does not + // matter (a replay of one seed); broken: every run failed, the natural order's too (or, without one, no race seen) + const verdict = failing.length === 0 ? "passed" : onFailing.length && (passing.length || !natural.length) ? "racy" : passing.length ? "flaky" : "broken"; + const failedSeeds = [...new Set(seeded.filter((r) => !r.ok).map((r) => r.seed))].sort((a, b) => a - b); + const passedSeeds = [...new Set(seeded.filter((r) => r.ok).map((r) => r.seed))].sort((a, b) => a - b); + const allSeeds = [...new Set(seeded.map((r) => r.seed))].sort((a, b) => a - b); + const naturalState = !natural.length ? null : natural.every((r) => r.ok) ? "passed" : natural.every((r) => !r.ok) ? "failed" : "both"; + const unwatched = failing.filter((r) => !r.watched); + // what else GenClass flagged on the failing runs (the model's other diagnoses): shown, never a verdict + const other = new Map(); + for (const r of failing) for (const s of r.other) if (!other.has(s.sig)) other.set(s.sig, { ...s, words: clean(`${s.trigger}:${s.diagnosis} ${s.op}`, 200) }); + // the run to replay: a failing seed where a race was seen, else a failing seed, else the natural order (a test that + // failed in the natural order too is broken whatever the seed: it is run plainly) + const raceRun = failing.find((r) => r.order === "seed" && r.races.length); + const seedRun = verdict === "broken" && natural.length ? undefined : (raceRun ?? failing.find((r) => r.order === "seed")); + const replay = verdict === "passed" ? null : replayCommand(t, seedRun ? seedRun.seed : null, { ...o, broken: verdict === "broken" }); + return { + ...t, + verdict, + failedSeeds, + passedSeeds, + seeds: allSeeds, + natural: naturalState, + naturalRuns: natural.length, + naturalFailed: natural.filter((r) => !r.ok).length, + failingRuns: failing.length, + races: onFailing, + alsoSeen: [...races.values()].filter((g) => !g.failing.length && !g.naturalFailing), + other: [...other.values()], + watchedFailing: failing.length - unwatched.length, + unwatchedWhy: unwatched.length ? (unwatched[0].why ?? "not watched") : null, + error: failing.find((r) => r.error)?.error ?? null, + replay, + replaySeed: seedRun ? seedRun.seed : null, + // failed on every seed with no natural-order run to compare with: the run that says whether the order matters + orderCheck: verdict === "broken" && !natural.length ? replayCommand(t, null, { ...o, whole: true }) : null, + }; +} + +/** + * The command that runs one test again: with `seed`, that seed's holds once (`genclass flake --seed N`); + * without one, in the natural order (`--no-chaos`), and for a broken test plain `playwright test`. `o.config`: the + * -c the run had; `o.cwdArg`: the --cwd it had; `o.whole`: the whole check of that test (the natural order, then the + * seeds), with no seed named. + */ +export function replayCommand(t, seed, o = {}) { + const loc = t.line ? `${t.file}:${t.line}` : t.file; + const extra = [...(t.project ? ["--project", t.project] : []), ...(o.config ? ["-c", o.config] : [])]; + if (o.broken && seed === null && !o.whole) return `${o.cwdArg ? `cd ${shell(o.cwdArg)} && ` : ""}${["npx", "playwright", "test", loc, ...extra].map(shell).join(" ")}`; + const tail = o.whole ? [] : seed === null ? ["--no-chaos"] : ["--seed", String(seed)]; + return ["npx", "genclass", "flake", loc, ...extra, ...(o.cwdArg ? ["--cwd", o.cwdArg] : []), ...tail].map(shell).join(" "); +} + +/** The command that runs these tests' files on every seed again (the proof after a fix). */ +export function rerunCommand(tests, o = {}) { + const files = [...new Set(tests.map((t) => t.file).filter(Boolean))]; + return ["npx", "genclass", "flake", ...files, ...(o.config ? ["-c", o.config] : []), ...(o.cwdArg ? ["--cwd", o.cwdArg] : [])].map(shell).join(" "); +} + +// ------------------------------------------------------------------------------------------------- what is said + +const VERDICT = { + racy: { mark: () => c.red(sym.cross), head: "Racy: your app" }, + flaky: { mark: () => c.yellow(sym.warn), head: "Flaky: likely the test" }, + broken: { mark: () => c.red(sym.cross), head: "Broken: fails every time" }, + // broken with no natural-order run (--seed, --no-baseline): what was measured, and no more + unordered: { mark: () => c.red(sym.cross), head: "Failed on every seed (no natural-order run)" }, + passed: { mark: () => c.green(sym.ok), head: "Passed every time" }, +}; + +/** The groups the verdicts are listed in, the worst first: broken tests with no natural-order run apart. */ +const GROUPS = [ + ["racy", (t) => t.verdict === "racy"], + ["flaky", (t) => t.verdict === "flaky"], + ["broken", (t) => t.verdict === "broken" && t.naturalRuns > 0], + ["unordered", (t) => t.verdict === "broken" && !t.naturalRuns], + ["passed", (t) => t.verdict === "passed"], +]; + +/** How each test ran, in words: "once in the natural order, then on seeds 1 to 5". */ +export function runsWords(plan) { + return runsParts(plan).join(" "); +} + +/** runsWords in the phrases a heading may break between: ["once in the natural order,", "then on seeds 1 to 5"]. */ +export function runsParts(plan) { + if (!plan.chaos) return [plan.runs === 1 ? "once in the natural order" : `${plan.runs} times in the natural order`]; + return plan.baseline ? ["once in the natural order,", `then on ${seedWords(plan.seeds)}`] : [`on ${seedWords(plan.seeds)}`]; +} + +/** + * One test's lines under its heading, each a [text, paint] pair; a command to copy is [text, paint, command], its + * text "