@fringetools/cli 0.1.0 → 0.1.2

package/README.md

@@ -17,8 +17,6 @@ That is the whole setup. `init` adds a `PostToolUse` hook to `.claude/settings.j
 
 Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe check`. Existing messy repo? Run `npx @fringetools/cli check --update-baseline` once so only *new* problems gate (see [Baseline](#baseline)).
 
-> **Until the first npm release:** build from source — `pnpm install && pnpm --filter @fringetools/cli build`, then use `node packages/cli/dist/bin.js` in place of `npx @fringetools/cli`.
-
 ## Commands
 
 | Command | What it does |
@@ -29,7 +27,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | `fringe check --hook` | One-line `fringe/hook.v1` JSON for CI / pre-commit. Exits `1` on errors. Claude Code does **not** feed this back — use `--claude-hook` for agents. Wins over `--json`. |
 | `fringe check --update-baseline` | Accept today's findings into `fringe.baseline.json` (commit it). Exit `0`. |
 | `fringe check --record [--manifest <path>]` | Also append this run to `.fringe/ledger.jsonl`, optionally merging an agent flow manifest. |
-| `fringe init [path]` | Add the Claude Code hook and install the skill. Safe to re-run; refuses to touch an invalid `settings.json`. |
+| `fringe init [path]` | Add the Claude Code hook and install the five skills. Safe to re-run; refuses to touch an invalid `settings.json`. |
 | `fringe open [path] [--port <n>]` | Serve the ledger as a plain HTML page on `127.0.0.1:4173` (loopback only). Ctrl+C to stop. |
 | `fringe --help` · `--version` | Usage / version. |
 
@@ -103,7 +101,9 @@ After each edit the hook runs; with errors it returns, for example:
 
 This was verified end to end with real agent runs: the agent receives the findings and fixes them (see [docs/architecture.md](../../docs/architecture.md)). Why `--claude-hook` and not `--hook`: Claude Code only passes a hook's output to the agent as `decision`/`reason` JSON on exit 0 (or stderr on exit 2); the CI contract `--hook` exits 1 and is ignored.
 
-**The skill** (`.claude/skills/fringe/SKILL.md`, source: [skill/SKILL.md](skill/SKILL.md)) teaches the agent the ladder: *Flow* (cut what users don't need, with evidence in `.fringe/manifest.json`) → *Edges* (fix every hook finding, never silence a rule to get green) → *Polish* (tokens, scales, no AI look), then record the run. It is plain Markdown, so any agent platform that reads `AGENTS.md`/skill files can use it as-is.
+**Skills** — `fringe init` installs five into `.claude/skills/` (sources in [skill/](skill/), one folder each); the Claude Code plugin ships the same folders, namespaced `/fringe:…`: `fringe` (below), `fringe-review` ("review this page": ranked, plain-English findings with fixes), `fringe-audit` (whole-repo plan: top rules and files, a fix order, offers `--update-baseline`), `fringe-debt` (lists `fringe-ignore` suppressions and the baseline) and `fringe-help` (quick reference). Invoke as `/fringe-review` etc. Reviews run `fringe check`, so Claude Code will ask you to approve that command once (or allow `Bash(fringe:*)` / `Bash(npx:*)`).
+
+**The main skill** (`.claude/skills/fringe/SKILL.md`) teaches the agent the ladder: *Flow* (cut what users don't need, with evidence in `.fringe/manifest.json`) → *Edges* (fix every hook finding, never silence a rule to get green) → *Polish* (tokens, scales, no AI look), then record the run. It is plain Markdown, so any agent platform that reads `AGENTS.md`/skill files can use it as-is.
 
 For CI or pre-commit use `fringe check --hook` (or just the exit code):
 

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-AOUZJDQL.js";
+} from "./chunk-E3SJZ4OQ.js";
 
 // src/bin.ts
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-AOUZJDQL.js → chunk-E3SJZ4OQ.js}

@@ -4,7 +4,7 @@ import { readFileSync as readFileSync8 } from "fs";
 import { resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1166,7 +1166,7 @@ import { createServer } from "http";
 var esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 function renderBoard(records, corrupt = 0) {
   const rows = [...records].reverse().map((r) => {
-    const flows = (r.manifest?.flows ?? []).map((f) => `<li>${esc(f.action)}: ${esc(f.what)} <small>(${esc(f.evidence)}) \u2014 judged</small></li>`).join("");
+    const flows = (r.manifest?.flows ?? []).map((f) => `<li>${esc(f.action)}: ${esc(f.what)} <small>(${esc(f.evidence)}) \u2014 judged${f.unsupported ? ", <b>no evidence</b>" : ""}</small></li>`).join("");
     return `<tr><td>${esc(r.ts)}</td><td>${r.score}</td><td>${r.counts.error}</td><td>${r.counts.review}</td><td>${r.counts.signal}</td><td>${r.files}</td><td>${r.suppressed ?? 0}</td><td>${flows ? `<ul>${flows}</ul>` : ""}</td></tr>`;
   }).join("");
   const body = records.length === 0 ? "<p>No runs yet. Run <code>fringe check --record</code> and reload.</p>" : `<table><tr><th>When</th><th>Health</th><th>Errors</th><th>Review</th><th>Signals</th><th>Files</th><th>Suppressed</th><th>Flow cuts</th></tr>${rows}</table>`;
@@ -1186,11 +1186,11 @@ function startBoard(root, port) {
 }
 
 // src/init.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync7, writeFileSync as writeFileSync2, copyFileSync } from "fs";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync7, readdirSync as readdirSync3, writeFileSync as writeFileSync2, copyFileSync } from "fs";
 import { dirname, join as join7 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
-var SKILL = fileURLToPath(new URL("../skill/SKILL.md", import.meta.url));
+var SKILL_DIR = fileURLToPath(new URL("../skill/", import.meta.url));
 function initProject(root) {
   const done = [];
   const settingsPath = join7(root, ".claude", "settings.json");
@@ -1210,12 +1210,14 @@ function initProject(root) {
     writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     done.push(`hook added to ${settingsPath}`);
   }
-  const skillPath = join7(root, ".claude", "skills", "fringe", "SKILL.md");
-  if (existsSync2(skillPath)) done.push("skill already present");
-  else {
-    mkdirSync2(dirname(skillPath), { recursive: true });
-    copyFileSync(SKILL, skillPath);
-    done.push(`skill installed at ${skillPath}`);
+  for (const name of readdirSync3(SKILL_DIR)) {
+    const skillPath = join7(root, ".claude", "skills", name, "SKILL.md");
+    if (existsSync2(skillPath)) done.push(`skill ${name} already present`);
+    else {
+      mkdirSync2(dirname(skillPath), { recursive: true });
+      copyFileSync(join7(SKILL_DIR, name, "SKILL.md"), skillPath);
+      done.push(`skill ${name} installed`);
+    }
   }
   return done;
 }
@@ -1235,6 +1237,13 @@ function readManifest(path2, warn) {
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || !Array.isArray(parsed.flows)) throw new Error("missing flows");
+    for (const f of parsed.flows) {
+      if (f.action === "cut" && weakEvidence(f.evidence)) {
+        f.unsupported = true;
+        warn(`fringe: warning: cut '${f.what}' has no real evidence \u2014 recorded as unsupported
+`);
+      }
+    }
     return parsed;
   } catch {
     warn(`fringe: warning: manifest at ${path2} is not valid '{ flows: [...] }' JSON \u2014 continuing without
@@ -1242,6 +1251,7 @@ function readManifest(path2, warn) {
     return void 0;
   }
 }
+var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\/?a|none|tbd|obvious|unnecessary|clutter|unused)\.?$/i.test(e.trim());
 var HELP = `fringe check [--json] [--hook] [--record] [--manifest <path>] [path]
 fringe check --claude-hook [path]       for Claude Code hooks (feeds errors back to the agent)
 fringe check --update-baseline [path]   accept today's findings; only new ones gate

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-AOUZJDQL.js";
+} from "./chunk-E3SJZ4OQ.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skill/{SKILL.md → fringe/SKILL.md}

@@ -5,6 +5,8 @@ description: Use when writing or changing frontend code (JSX/TSX, HTML, CSS, Vue
 
 # Fringe
 
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
 Ponytail trims your code. Fringe handles your edges. Work the ladder in order.
 
 1. **Flow (judged).** Before building, ask what the user can skip. Cut steps, screens or options nobody needs. Write each decision with its evidence to `.fringe/manifest.json`: `{"flows":[{"action":"cut"|"kept","what":"...","evidence":"..."}]}`. No evidence, no cut.

package/skill/fringe-audit/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: fringe-audit
+description: Use when the user wants a whole-repo UX/accessibility audit, a plan for an existing frontend with many problems, or to adopt Fringe on a messy repo ("audit this codebase", "where do we start", "adopt fringe"). Produces a prioritized plan and sets a baseline.
+---
+
+# Fringe audit
+
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
+1. Run `fringe check --json .` and note the totals. Do not print every finding.
+2. Summarize as a plan:
+   - Totals by severity and the health score, plus files scanned and skipped.
+   - **Top rules** by count, and **top files** by error count (the 5 worst of each).
+   - For each top rule: what it means in one sentence, a typical fix, and whether it is likely mechanical (add `aria-label`, add `alt`) or needs design judgment.
+   - A suggested order: mechanical `error` fixes first, then `error`s needing judgment, then `review`, then `signal`.
+3. Offer the baseline: "`fringe check --update-baseline` records today's findings so only new problems gate; commit `fringe.baseline.json`." Run it only if the user agrees.
+4. Ask before changing code. If the user says go, fix one rule at a time, re-run `fringe check` after each, and re-baseline at the end so the file shrinks.
+
+Spot-check a few reported findings by reading the code before presenting them as certain; Fringe is static and can be wrong. Say which you checked.

package/skill/fringe-debt/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: fringe-debt
+description: Use when the user asks what Fringe findings have been silenced or deferred ("fringe debt", "what did we suppress", "what's in the baseline", /fringe-debt). One-shot report of suppressions and the baseline; changes nothing.
+---
+
+# Fringe debt
+
+Fringe has two ways to defer a finding: an inline `fringe-ignore` comment and the `fringe.baseline.json` file. This lists both so a deferral can't quietly become permanent.
+
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place.
+
+1. **Inline suppressions.** `git grep --no-index --exclude-standard -nE 'fringe-ignore +FR-[0-9]+'`. One row per hit: `<file>:<line>, <rule> — <why, if the comment or nearby code says>`. Skip hits that are only prose mentioning the convention.
+2. **Baseline.** If `fringe.baseline.json` exists, count entries per rule (each entry is `rule|file|message`) and list the files with the most. If it is missing, say there is no baseline.
+3. **Today's picture.** Run `fringe check --json .` and report the current counts by severity next to the baseline total, so the user sees whether the debt is shrinking.
+4. Close with the single most valuable thing to pay down first (usually the rule with the most baselined entries that has a mechanical fix) and the command to shrink the baseline afterwards: `fringe check --update-baseline`.
+
+Change nothing. Do not run `--update-baseline` unless the user asks.

package/skill/fringe-help/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: fringe-help
+description: Use when the user asks what Fringe can do or how to use it ("fringe help", "what commands does fringe have", /fringe-help). Quick reference; changes nothing.
+---
+
+# Fringe help
+
+Fringe checks agent-written frontends for accessibility, state, dark-pattern and "AI look" problems, gates the hard failures, and keeps a local history.
+
+**Skills**
+
+| Skill | Use it to |
+|---|---|
+| `fringe` | The working rules: cut what users don't need, fix every hook finding, polish, record |
+| `/fringe-review` | Review a page or component: ranked findings with plain-English fixes |
+| `/fringe-audit` | Audit the whole repo: top rules and files, a fix order, offer a baseline |
+| `/fringe-debt` | List silenced findings (`fringe-ignore`, baseline) |
+| `/fringe-help` | This reference |
+
+**Commands** (`fringe`, or `npx -y @fringetools/cli`)
+
+| Command | What it does |
+|---|---|
+| `check [dir]` | Scan and print findings and the health score; exit 1 on any error |
+| `check --json` / `--hook` / `--claude-hook` | Machine output; CI gate; agent feedback form |
+| `check --update-baseline` | Accept today's findings; only new ones gate |
+| `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |
+| `init` | Add the hook and install the skills |
+| `open` | View the ledger at 127.0.0.1:4173 |
+
+**Escape hatch:** `// fringe-ignore FR-203` on or above the line, for a real false positive only; every run reports `N suppressed`.
+
+Full reference: https://github.com/skc-learn/fringe/blob/main/packages/cli/README.md

package/skill/fringe-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: fringe-review
+description: Use when the user asks to review, check or critique a UI, page or component for accessibility and UX edges ("review this page", "what's wrong with this form", "is this accessible"). Runs Fringe and reports ranked findings with fixes, in plain English.
+---
+
+# Fringe review
+
+Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
+
+1. Run `fringe check --json .` from the project root. Fringe takes directories, not single files, so if the user named one file or page, run on the folder and keep only the findings whose `loc.file` matches it.
+2. Report in plain English, no jargon left unexplained:
+   - **Must fix** — `error` findings. Group by rule. For each: where (`file:line`), what is wrong in one sentence, the exact fix, and who is hurt (for example "a screen reader says only 'button'"). Cite the `wcag` criterion when present.
+   - **Worth a look** — `review` findings. These are heuristics: say they need your judgment, and give your call on each.
+   - **Polish** — `signal` findings, only the top few. Never present them as bugs.
+3. End with the health score as measured, the count by severity, and one line on what was not checked (Fringe is static: it cannot judge contrast on images, real focus order, or whether copy is good).
+4. Change no code unless asked. If asked to fix, fix `error` items first and re-run to confirm.
+
+Do not invent findings the tool did not report, and do not call the score an estimate: it is measured.