@fringetools/cli 0.5.0 → 0.6.0

package/README.md

@@ -23,6 +23,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 |---|---|
 | `fringe check [dir\|file]` | Scan a directory (default `.`) or judge one file (the project root is found by climbing to the nearest `package.json`). Prints findings and the health score. Exit `1` on any `error`. |
 | `fringe scan <url> [--states file] [--stress] [--storage-state auth.json] [--screenshots dir] [--update-baseline] [--json]` | **Runtime check of a live page** (needs `npm i -D playwright-core axe-core`; uses your installed Chrome). Runs axe-core for real contrast, computed names and ARIA relations (`FR-400`; critical/serious = `error`, the rest `review`), then walks the page with Tab and reports keyboard traps (`FR-401`, error) and controls Tab never reaches (review). Accepts `http(s)://` and `file://` URLs. Exit `1` on errors. |
+| `fringe login <url> [--out file]` | **Log in once, by hand, in a real browser window** and save the session (default `.fringe/auth.json`) for `scan --storage-state`. Works with MFA and SSO. The file holds live cookies: keep it out of git. |
 | `fringe rules [dir] [--json]` | **Per-rule health for this repo**: findings still open, accepted into the baseline, and silenced with `fringe-ignore`, plus the ledger trend when `--record` has been used. A rule that is mostly overridden here is flagged: it may not suit the repo, so retune, disable or report it. `fringe/rules.v1`. |
 | `fringe handoff [dir\|file] [--scan url]` | **Work order for another agent or CI.** Prints a self-contained prompt (rules, definition of done, the ordered plan) and saves `.fringe/handoff.json` (`fringe/handoff.v1`). `--json` prints the file; `--out` chooses where. |
 | `fringe verify [--handoff file] [--json]` | **Proof it was done.** Re-checks everything the hand-off covered and reports `complete` / `partial` / `regressed`: errors fixed, remaining, introduced, and how many findings were silenced with `fringe-ignore` since. Exit `0` only when `complete` (`fringe/verify.v1`). |
@@ -108,9 +109,54 @@ npx @fringetools/cli scan http://localhost:3000 --modes dark,reflow      # a sub
 
 Each mode runs on a fresh page so one mode's emulation never leaks into the next, and only findings the plain page did not already have are kept. Findings are labelled `[dark mode]`, `[reduced motion]`, `[reflow]`. Modes apply to the initial page, not to named states.
 
-### Pages behind a login, screenshots, and a baseline for scan findings
+### Pages behind a login
+
+Most apps hide the interesting pages behind a sign-in, and a scan that gets bounced to the login screen audits the wrong page. Three ways to be logged in; pick the one that fits.
+
+**1. Log in once by hand (works with MFA, SSO, captchas).**
+
+```sh
+npx @fringetools/cli login http://localhost:3000/login      # a Chrome window opens
+# sign in as you normally would, then press Enter in the terminal (close the window afterwards)
+npx @fringetools/cli scan http://localhost:3000/dashboard --storage-state .fringe/auth.json
+```
+
+The session (cookies and local storage) is saved to `.fringe/auth.json`. It is a live login: **keep it out of git** (the command warns if `.gitignore` does not list `.fringe/`) and expect it to expire.
+
+**2. A scripted login (for CI and agents).** Describe the steps in `fringe.scan.json`; credentials come from environment variables, so none are stored in the file:
+
+```json
+{
+  "login": {
+    "url": "/login",
+    "steps": [
+      { "fill": "#email", "value": "${env:FRINGE_EMAIL}" },
+      { "fill": "#password", "value": "${env:FRINGE_PASSWORD}" },
+      { "click": "button:has-text(\"Sign in\")" },
+      { "waitFor": "[data-test=dashboard]" }
+    ]
+  },
+  "states": [ { "name": "settings", "steps": [ { "goto": "/settings" } ] } ]
+}
+```
+
+Use a **test account**, not a real user. A missing variable stops the scan before any browser opens, naming the variable and never its value; messages show the step with the `${env:...}` placeholder, not the secret. Prefer specific selectors: `text=Sign in` can match the page heading instead of the button.
+
+**3. Several roles in one scan.** List sessions; each runs the whole scan (initial page, states, stress modes) and findings are labelled `[as admin]`, `[as member]`:
+
+```json
+{ "sessions": [
+  { "name": "member", "login": { "url": "/login", "steps": [ ... ] } },
+  { "name": "admin",  "storageState": "admin-auth.json" }
+] }
+```
+
+**What you will see when something is off**
+- `FR-405` "the scan was sent to /login, which looks like a login page": the session is missing or expired. Everything else in that run describes the login screen, not your app, so refresh the session first.
+- `FR-402` "login failed at step N": a selector did not match or the page did not reach the expected state. The step is shown; fix it in `fringe.scan.json`.
+
+### Screenshots and a baseline for scan findings
 
-- **Login:** save a browser session once, then point the scan at it: `npx playwright-core codegen --save-storage=auth.json http://localhost:3000` (log in by hand in the window that opens, then close it). Use it with `--storage-state auth.json`, or put `"storageState": "auth.json"` at the top of `fringe.scan.json` (relative to that file). Keep the file out of git: it contains session cookies.
 - **Screenshots:** `--screenshots shots/` saves a full-page PNG of the initial page, each named state and each stress mode, so a reviewer can see what was audited.
 - **Baseline:** `scan --update-baseline` writes `fringe.scan.baseline.json` (commit it); later scans hide those known findings and report `N baselined`. Matching is by rule, page/state and element, not axe's wording, so a contrast ratio that shifts slightly stays known.
 

package/dist/bin.js

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

package/dist/{chunk-ZTIMW7ON.js → chunk-JJI65ERU.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
 import { existsSync as existsSync5, readFileSync as readFileSync11, statSync } from "fs";
-import { dirname as dirname2, join as join11, resolve } from "path";
+import { dirname as dirname3, join as join12, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.5.0";
+var VERSION = "0.6.0";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1641,31 +1641,61 @@ function tabWalkFindings(url, focusables, visits) {
   return out;
 }
 var STEP_KEYS = ["click", "fill", "press", "hover", "waitFor", "goto"];
+var bad = (m) => {
+  throw new Error(`fringe.scan.json: ${m}`);
+};
+function checkSteps(steps, where2) {
+  if (!Array.isArray(steps) || steps.length === 0) return bad(`${where2} needs a non-empty "steps" list`);
+  for (const [k, step] of steps.entries()) {
+    const keys = STEP_KEYS.filter((x) => step && typeof step === "object" && x in step);
+    if (keys.length !== 1 || typeof step[keys[0]] !== "string") bad(`${where2} step ${k + 1} must be exactly one of ${STEP_KEYS.join(", ")} with a string value`);
+    if (keys[0] === "fill" && typeof step.value !== "string") bad(`${where2} step ${k + 1}: fill needs a "value"`);
+  }
+  return steps;
+}
 function parseStates(json) {
-  const bad = (m) => {
-    throw new Error(`fringe.scan.json: ${m}`);
-  };
-  const states = json?.states;
-  if (!Array.isArray(states)) return bad('expected { "states": [ ... ] }');
-  return states.map((s, i) => {
+  const o = json;
+  if (o?.states === void 0 && (o?.login !== void 0 || o?.sessions !== void 0 || o?.storageState !== void 0)) return [];
+  if (!Array.isArray(o?.states)) return bad('expected { "states": [ ... ] }');
+  return o.states.map((s, i) => {
     if (typeof s?.name !== "string" || !s.name.trim()) bad(`states[${i}] needs a "name"`);
-    if (!Array.isArray(s.steps) || s.steps.length === 0) bad(`state "${s.name}" needs a non-empty "steps" list`);
-    for (const [k, step] of s.steps.entries()) {
-      const keys = STEP_KEYS.filter((x) => step && typeof step === "object" && x in step);
-      if (keys.length !== 1 || typeof step[keys[0]] !== "string") bad(`state "${s.name}" step ${k + 1} must be exactly one of ${STEP_KEYS.join(", ")} with a string value`);
-      if (keys[0] === "fill" && typeof step.value !== "string") bad(`state "${s.name}" step ${k + 1}: fill needs a "value"`);
-    }
-    return { name: s.name.trim(), steps: s.steps };
+    return { name: s.name.trim(), steps: checkSteps(s.steps, `state "${s.name}"`) };
   });
 }
+function parseSessions(json, baseDir) {
+  const o = json ?? {};
+  const one = (x, where2, name) => {
+    if (x?.storageState !== void 0 && typeof x.storageState !== "string") bad(`${where2}: storageState must be a file path`);
+    if (x?.login !== void 0 && typeof x.login?.url !== "undefined" && typeof x.login.url !== "string") bad(`${where2}: login.url must be a string`);
+    return { ...name ? { name } : {}, ...x?.storageState ? { storageState: join8(baseDir, x.storageState) } : {}, ...x?.login ? { login: { ...x.login.url ? { url: x.login.url } : {}, steps: checkSteps(x.login.steps, `${where2} login`) } } : {} };
+  };
+  const out = [];
+  if (o.login !== void 0 || o.storageState !== void 0) out.push(one(o, "top level"));
+  if (o.sessions !== void 0) {
+    if (!Array.isArray(o.sessions) || o.sessions.length === 0) bad('"sessions" must be a non-empty list');
+    for (const [i, s] of o.sessions.entries()) {
+      if (typeof s?.name !== "string" || !s.name.trim()) bad(`sessions[${i}] needs a "name"`);
+      if (!s.storageState && !s.login) bad(`session "${s.name}" needs a "storageState" or a "login"`);
+      out.push(one(s, `session "${s.name}"`, s.name.trim()));
+    }
+  }
+  return out;
+}
+var ENV_REF = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
+var expandEnv = (s) => s.replace(ENV_REF, (_m, n) => {
+  const v = process.env[n];
+  if (v === void 0) throw new Error(`environment variable ${n} is not set (named in fringe.scan.json)`);
+  return v;
+});
+var envNames = (steps) => steps.flatMap((st) => ("fill" in st ? [st.value] : "goto" in st ? [st.goto] : []).flatMap((v) => [...v.matchAll(ENV_REF)].map((m) => m[1])));
 async function runStep(page, step, base) {
   const t = { timeout: 1e4 };
   if ("click" in step) await page.click(step.click, t);
-  else if ("fill" in step) await page.fill(step.fill, step.value, t);
+  else if ("fill" in step) await page.fill(step.fill, expandEnv(step.value), t);
   else if ("press" in step) await page.keyboard.press(step.press);
   else if ("hover" in step) await page.hover(step.hover, t);
   else if ("waitFor" in step) await page.waitForSelector(step.waitFor, t);
-  else await page.goto(new URL(step.goto, base).href, { waitUntil: "load", timeout: 3e4 });
+  else await page.goto(new URL(expandEnv(step.goto), base).href, { waitUntil: "load", timeout: 3e4 });
   await page.waitForTimeout(150);
 }
 async function audit(page, axePath, url) {
@@ -1683,12 +1713,12 @@ async function audit(page, axePath, url) {
   }
   return [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)];
 }
-var inState = (name, url, f) => ({ ...f, message: `[${name}] ${f.message}`, loc: { ...f.loc, file: `${url} [${name}]` }, ...f.cluster ? { cluster: `${f.cluster} [${name}]` } : {} });
+var inState = (name, url, f) => ({ ...f, message: `[${name}] ${f.message}`, loc: { ...f.loc, file: `${f.loc.file === url ? url : f.loc.file} [${name}]` }, ...f.cluster ? { cluster: `${f.cluster} [${name}]` } : {} });
 var MODES = ["dark", "reduced", "reflow"];
 function parseModes(list) {
   const out = list.split(",").map((m) => m.trim()).filter(Boolean);
-  const bad = out.find((m) => !MODES.includes(m));
-  if (bad || out.length === 0) throw new Error(`unknown scan mode '${bad ?? ""}': use ${MODES.join(", ")}`);
+  const bad2 = out.find((m) => !MODES.includes(m));
+  if (bad2 || out.length === 0) throw new Error(`unknown scan mode '${bad2 ?? ""}': use ${MODES.join(", ")}`);
   return out;
 }
 function onlyNew(base, extra) {
@@ -1751,14 +1781,51 @@ function applyScanBaseline(cwd, findings) {
   return { fresh, known: findings.length - fresh.length };
 }
 var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "page";
+var LOGINISH = /log-?in|sign-?in|sso|auth/i;
+var firstLine = (e) => String(e.message).split("\n")[0].slice(0, 120);
+async function loginRedirect(page, requested, who) {
+  let now, want;
+  try {
+    now = new URL(page.url());
+    want = new URL(requested);
+  } catch {
+    return [];
+  }
+  if (now.pathname === want.pathname) return [];
+  const hasPassword = await page.evaluate(() => !!document.querySelector("input[type=password]"));
+  if (!LOGINISH.test(now.pathname) && !hasPassword) return [];
+  return [{ rule: "FR-405", severity: "review", message: `the scan was sent to ${now.pathname}, which looks like a login page: ${who ? `the "${who}" session may have expired or the login failed` : "this page needs a login"}`, hint: 'save a session with `fringe login <url>` or add a "login" block to fringe.scan.json; findings for this page describe the login screen, not your app', loc: { file: requested, line: 1, col: 0 } }];
+}
+async function auditContext(context, axePath, url, opts, who, shot) {
+  const { states = [], modes = [] } = opts;
+  const page = await context.newPage();
+  await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+  await shot(page, "initial");
+  const all = [...await loginRedirect(page, url, who), ...await audit(page, axePath, url)];
+  const plain = [...all];
+  for (const st of states) {
+    await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+    let step = 0;
+    try {
+      for (; step < st.steps.length; step++) await runStep(page, st.steps[step], url);
+    } catch (e) {
+      all.push({ rule: "FR-402", severity: "review", message: `[${st.name}] state could not be reached: step ${step + 1} ${JSON.stringify(st.steps[step])} failed (${firstLine(e)})`, hint: "fix the step in fringe.scan.json or the page; nothing in this state was audited", loc: { file: `${url} [${st.name}]`, line: 1, col: 0 } });
+      continue;
+    }
+    await shot(page, `state-${st.name}`);
+    all.push(...(await audit(page, axePath, url)).map((f) => inState(st.name, url, f)));
+  }
+  for (const m of modes) all.push(...await stress(context, axePath, url, m, plain, shot));
+  return all;
+}
 async function scan(url, cwd = process.cwd(), opts = {}) {
   const { states = [], modes = [] } = opts;
-  const shot = async (page, name) => {
-    if (!opts.screenshots) return;
-    mkdirSync3(opts.screenshots, { recursive: true });
-    await page.screenshot({ path: join8(opts.screenshots, `${slug(name)}.png`), fullPage: true });
-  };
   if (!/^(https?|file):\/\//i.test(url)) throw new Error(`fringe scan takes an http(s):// or file:// URL, got '${url}'`);
+  const sessions = opts.sessions?.length ? opts.sessions : [opts.storageState ? { storageState: opts.storageState } : {}];
+  for (const n of /* @__PURE__ */ new Set([...sessions.flatMap((s) => envNames(s.login?.steps ?? [])), ...states.flatMap((s) => envNames(s.steps))])) {
+    if (process.env[n] === void 0) throw new Error(`environment variable ${n} is not set (named in fringe.scan.json)`);
+  }
+  for (const s of sessions) if (s.storageState && !existsSync2(s.storageState)) throw new Error(`storage state file not found: ${s.storageState} (create one with: fringe login ${url})`);
   const req = createRequire(join8(cwd, "noop.js"));
   let playwright, axePath;
   try {
@@ -1778,35 +1845,46 @@ async function scan(url, cwd = process.cwd(), opts = {}) {
     }
   }
   try {
-    if (opts.storageState && !existsSync2(opts.storageState)) throw new Error(`storage state file not found: ${opts.storageState} (create one with: npx playwright-core codegen --save-storage=auth.json ${url})`);
-    const context = await browser.newContext(opts.storageState ? { storageState: opts.storageState } : {});
-    const page = await context.newPage();
-    await page.goto(url, { waitUntil: "load", timeout: 3e4 });
-    await shot(page, "initial");
-    const all = await audit(page, axePath, url);
-    const plain = [...all];
-    for (const st of states) {
-      await page.goto(url, { waitUntil: "load", timeout: 3e4 });
-      let step = 0;
+    const all = [];
+    for (const s of sessions) {
+      const who = s.name, label = who ? `as ${who}` : void 0;
+      const shot = async (page, name) => {
+        if (!opts.screenshots) return;
+        mkdirSync3(opts.screenshots, { recursive: true });
+        await page.screenshot({ path: join8(opts.screenshots, `${slug(who ? `${who}-${name}` : name)}.png`), fullPage: true });
+      };
+      const context = await browser.newContext(s.storageState ? { storageState: s.storageState } : {});
       try {
-        for (; step < st.steps.length; step++) await runStep(page, st.steps[step], url);
-      } catch (e) {
-        all.push({ rule: "FR-402", severity: "review", message: `[${st.name}] state could not be reached: step ${step + 1} ${JSON.stringify(st.steps[step])} failed (${String(e.message).split("\n")[0].slice(0, 120)})`, hint: "fix the step in fringe.scan.json or the page; nothing in this state was audited", loc: { file: `${url} [${st.name}]`, line: 1, col: 0 } });
-        continue;
+        let found;
+        if (s.login) {
+          const lp = await context.newPage();
+          let step = 0;
+          try {
+            await lp.goto(new URL(s.login.url ?? url, url).href, { waitUntil: "load", timeout: 3e4 });
+            for (; step < s.login.steps.length; step++) await runStep(lp, s.login.steps[step], url);
+            found = await auditContext(context, axePath, url, opts, who, shot);
+          } catch (e) {
+            found = [{ rule: "FR-402", severity: "review", message: `login${who ? ` as ${who}` : ""} failed at step ${step + 1} ${JSON.stringify(s.login.steps[step] ?? {})} (${firstLine(e)})`, hint: "check the login steps and selectors in fringe.scan.json; nothing was scanned for this session", loc: { file: url, line: 1, col: 0 } }];
+          } finally {
+            await lp.close().catch(() => {
+            });
+          }
+        } else found = await auditContext(context, axePath, url, opts, who, shot);
+        all.push(...label ? found.map((f) => inState(label, url, f)) : found);
+      } finally {
+        await context.close();
       }
-      await shot(page, `state-${st.name}`);
-      all.push(...(await audit(page, axePath, url)).map((f) => inState(st.name, url, f)));
     }
-    for (const m of modes) all.push(...await stress(context, axePath, url, m, plain, shot));
+    const files = sessions.length * (1 + states.length + modes.length);
     if (opts.updateBaseline) {
       writeFileSync3(baselinePath(cwd), JSON.stringify(all.map(scanKey).sort(), null, 2) + "\n");
-      return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files: 1 + states.length + modes.length, skipped: [], findings: [], clusters: [], counts: { error: 0, review: 0, signal: 0 }, score: 100, baselined: all.length };
+      return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files, skipped: [], findings: [], clusters: [], counts: { error: 0, review: 0, signal: 0 }, score: 100, baselined: all.length };
     }
     const { fresh, known } = applyScanBaseline(cwd, all);
     const { findings, clusters } = rankScan(url, fresh);
     const counts = { error: 0, review: 0, signal: 0 };
     for (const f of findings) counts[f.severity]++;
-    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files: 1 + states.length + modes.length, skipped: [], findings, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1), ...known ? { baselined: known } : {} };
+    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files, skipped: [], findings, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1), ...known ? { baselined: known } : {} };
   } finally {
     await browser.close();
   }
@@ -1830,19 +1908,71 @@ function mergeScan(base, scanned, weights) {
   return { ...base, findings: [...base.findings, ...scanned.findings], clusters: [...base.clusters ?? [], ...scanned.clusters ?? []].sort((a, b) => b.priority - a.priority), counts, score: score(counts, weights, base.files), ...(base.baselined ?? 0) + (scanned.baselined ?? 0) ? { baselined: (base.baselined ?? 0) + (scanned.baselined ?? 0) } : {} };
 }
 
-// src/init.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync9, readdirSync as readdirSync3, writeFileSync as writeFileSync4, copyFileSync } from "fs";
+// src/login.ts
+import { createRequire as createRequire2 } from "module";
+import { mkdirSync as mkdirSync4 } from "fs";
 import { dirname, join as join9 } from "path";
+import { createInterface } from "readline";
+async function saveSession(url, cwd, out, o = {}) {
+  if (!/^https?:\/\//i.test(url)) throw new Error(`fringe login takes an http(s):// URL, got '${url}'`);
+  const req = createRequire2(join9(cwd, "noop.js"));
+  let playwright;
+  try {
+    playwright = req("playwright-core");
+  } catch {
+    throw new Error(SCAN_HELP);
+  }
+  let browser;
+  const headless = o.headless ?? false;
+  try {
+    browser = await playwright.chromium.launch({ channel: "chrome", headless });
+  } catch {
+    try {
+      browser = await playwright.chromium.launch({ headless });
+    } catch {
+      throw new Error(SCAN_HELP);
+    }
+  }
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 6e4 });
+    if (o.wait) await o.wait();
+    else {
+      process.stderr.write("fringe: log in in the browser window, then come back here and press Enter. Close the window afterwards, not before.\n");
+      await new Promise((ok, fail) => {
+        const rl = createInterface({ input: process.stdin });
+        rl.once("line", () => {
+          rl.close();
+          ok();
+        });
+        browser.once("disconnected", () => {
+          rl.close();
+          fail(new Error("the browser was closed before the session was saved: press Enter in this terminal first, then close the window"));
+        });
+      });
+    }
+    mkdirSync4(dirname(out), { recursive: true });
+    await context.storageState({ path: out });
+  } finally {
+    await browser.close().catch(() => {
+    });
+  }
+}
+
+// src/init.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readFileSync as readFileSync9, readdirSync as readdirSync3, writeFileSync as writeFileSync4, copyFileSync } from "fs";
+import { dirname as dirname2, join as join10 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
 var SKILL_DIR = fileURLToPath(new URL("../skill/", import.meta.url));
 function hookCommand(root) {
-  return existsSync3(join9(root, "node_modules", "@fringetools", "cli", "package.json")) ? "npx --no-install fringe check --claude-hook" : HOOK;
+  return existsSync3(join10(root, "node_modules", "@fringetools", "cli", "package.json")) ? "npx --no-install fringe check --claude-hook" : HOOK;
 }
 function isWired(root, home) {
   for (const dir of [root, home]) {
     try {
-      if (/claude-hook|fringe(tool)?@/.test(readFileSync9(join9(dir, ".claude", "settings.json"), "utf8"))) return true;
+      if (/claude-hook|fringe(tool)?@/.test(readFileSync9(join10(dir, ".claude", "settings.json"), "utf8"))) return true;
     } catch {
     }
   }
@@ -1850,7 +1980,7 @@ function isWired(root, home) {
 }
 function initProject(root) {
   const done = [];
-  const settingsPath = join9(root, ".claude", "settings.json");
+  const settingsPath = join10(root, ".claude", "settings.json");
   let settings = {};
   if (existsSync3(settingsPath)) {
     try {
@@ -1863,16 +1993,16 @@ function initProject(root) {
   if (/(fringe|@fringetools\/cli) check/.test(JSON.stringify(post))) done.push("hook already present");
   else {
     post.push({ matcher: "Edit|Write", hooks: [{ type: "command", command: hookCommand(root) }] });
-    mkdirSync4(dirname(settingsPath), { recursive: true });
+    mkdirSync5(dirname2(settingsPath), { recursive: true });
     writeFileSync4(settingsPath, JSON.stringify(settings, null, 2) + "\n");
     done.push(`hook added to ${settingsPath}`);
   }
   for (const name of readdirSync3(SKILL_DIR)) {
-    const skillPath = join9(root, ".claude", "skills", name, "SKILL.md");
+    const skillPath = join10(root, ".claude", "skills", name, "SKILL.md");
     if (existsSync3(skillPath)) done.push(`skill ${name} already present`);
     else {
-      mkdirSync4(dirname(skillPath), { recursive: true });
-      copyFileSync(join9(SKILL_DIR, name, "SKILL.md"), skillPath);
+      mkdirSync5(dirname2(skillPath), { recursive: true });
+      copyFileSync(join10(SKILL_DIR, name, "SKILL.md"), skillPath);
       done.push(`skill ${name} installed`);
     }
   }
@@ -1905,7 +2035,7 @@ function initFor(root, agents) {
   for (const a of agents) {
     const spec = AGENT_FILES[a];
     if (!spec) throw new Error(`unknown agent '${a}': use ${AGENTS.join(", ")} (or 'claude' for the hook + skills)`);
-    const file2 = join9(root, spec.path);
+    const file2 = join10(root, spec.path);
     const text = spec.wrap ? spec.wrap(body) : body;
     if (existsSync3(file2)) {
       const cur = readFileSync9(file2, "utf8");
@@ -1918,7 +2048,7 @@ ${MARK2}
 ${spec.wrap ? body : text}`);
       done.push(`rules appended to ${spec.path}`);
     } else {
-      mkdirSync4(dirname(file2), { recursive: true });
+      mkdirSync5(dirname2(file2), { recursive: true });
       writeFileSync4(file2, text.replace("# Fringe: handle your edges", `${MARK2}
 # Fringe: handle your edges`));
       done.push(`${spec.path} created`);
@@ -1927,10 +2057,10 @@ ${spec.wrap ? body : text}`);
   return done;
 }
 function initGit(root) {
-  const dir = join9(root, ".git", "hooks");
-  if (!existsSync3(join9(root, ".git"))) throw new Error("not a git repository (no .git here)");
-  const file2 = join9(dir, "pre-commit");
-  const local = existsSync3(join9(root, "node_modules", "@fringetools", "cli", "package.json"));
+  const dir = join10(root, ".git", "hooks");
+  if (!existsSync3(join10(root, ".git"))) throw new Error("not a git repository (no .git here)");
+  const file2 = join10(dir, "pre-commit");
+  const local = existsSync3(join10(root, "node_modules", "@fringetools", "cli", "package.json"));
   const cmd = local ? "npx --no-install fringe check" : "npx -y @fringetools/cli check";
   const script = `#!/bin/sh
 # fringe pre-commit: blocks the commit while error-level UX/accessibility problems remain
@@ -1946,7 +2076,7 @@ exit 0
     if (readFileSync9(file2, "utf8").includes("# fringe pre-commit")) return ["pre-commit hook already present"];
     throw new Error(`${file2} already exists and is not Fringe's: add 'npx -y @fringetools/cli check || exit 1' to it yourself`);
   }
-  mkdirSync4(dir, { recursive: true });
+  mkdirSync5(dir, { recursive: true });
   writeFileSync4(file2, script, { mode: 493 });
   return [`pre-commit hook installed at ${file2}`];
 }
@@ -2079,12 +2209,12 @@ After each batch, verify: \`fringe check ${target}\``);
 
 // src/rulereport.ts
 import { existsSync as existsSync4, readFileSync as readFileSync10 } from "fs";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 async function ruleReport(root) {
   const cfg = loadConfig(root);
   const result = await runCheck(root, cfg, false);
   const baselinedBy = /* @__PURE__ */ new Map();
-  const bl = join10(root, "fringe.baseline.json");
+  const bl = join11(root, "fringe.baseline.json");
   if (existsSync4(bl)) {
     try {
       for (const k of JSON.parse(readFileSync10(bl, "utf8"))) baselinedBy.set(k.split("|")[0], (baselinedBy.get(k.split("|")[0]) ?? 0) + 1);
@@ -2207,7 +2337,7 @@ function verifyToMarkdown(v) {
 }
 
 // src/index.ts
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync5 } from "fs";
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync5 } from "fs";
 var log = (o) => o.log ?? ((s) => console.log(s));
 var err = (o) => o.err ?? ((s) => process.stderr.write(s));
 function readManifest(path2, warn) {
@@ -2238,13 +2368,13 @@ function readManifest(path2, warn) {
 }
 function resolveTarget(arg) {
   if (!statSync(arg).isFile()) return { root: arg };
-  let dir = dirname2(arg);
-  for (let d = dir, i = 0; i < 12; i++, d = dirname2(d)) {
-    if (existsSync5(join11(d, "package.json")) || existsSync5(join11(d, "fringe.config.json"))) {
+  let dir = dirname3(arg);
+  for (let d = dir, i = 0; i < 12; i++, d = dirname3(d)) {
+    if (existsSync5(join12(d, "package.json")) || existsSync5(join12(d, "fringe.config.json"))) {
       dir = d;
       break;
     }
-    if (dirname2(d) === d) break;
+    if (dirname3(d) === d) break;
   }
   return { root: dir, only: /* @__PURE__ */ new Set([arg]) };
 }
@@ -2254,9 +2384,10 @@ function loadScanOptions(cwd, rest) {
     return i === -1 ? void 0 : rest[i + 1];
   };
   const si = rest.indexOf("--states");
-  const file2 = si !== -1 ? resolve(cwd, rest[si + 1] ?? "") : join11(cwd, "fringe.scan.json");
+  const file2 = si !== -1 ? resolve(cwd, rest[si + 1] ?? "") : join12(cwd, "fringe.scan.json");
   let states = [];
-  let storageState = flag("--storage-state") ? resolve(cwd, flag("--storage-state")) : void 0;
+  let sessions;
+  const storageFlag = flag("--storage-state") ? resolve(cwd, flag("--storage-state")) : void 0;
   if (si !== -1 || existsSync5(file2)) {
     let raw;
     try {
@@ -2265,10 +2396,11 @@ function loadScanOptions(cwd, rest) {
       throw new Error(`${file2}: ${e.message}`);
     }
     states = parseStates(raw);
-    if (!storageState && typeof raw.storageState === "string") storageState = resolve(dirname2(file2), raw.storageState);
+    const parsed = parseSessions(raw, dirname3(file2));
+    if (parsed.length) sessions = parsed;
   }
   const shots = flag("--screenshots");
-  return { states, modes: loadModes(rest), ...storageState ? { storageState } : {}, ...shots ? { screenshots: resolve(cwd, shots) } : {}, ...rest.includes("--update-baseline") ? { updateBaseline: true } : {} };
+  return { states, modes: loadModes(rest), ...storageFlag ? { storageState: storageFlag } : sessions ? { sessions } : {}, ...shots ? { screenshots: resolve(cwd, shots) } : {}, ...rest.includes("--update-baseline") ? { updateBaseline: true } : {} };
 }
 function loadModes(rest) {
   const i = rest.indexOf("--modes");
@@ -2278,6 +2410,7 @@ var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\
 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
+fringe login <url> [--out auth.json]     log in once in a browser window and save the session for scans
 fringe scan <url> [--states f] [--stress | --modes ...] [--storage-state auth.json] [--screenshots dir] [--update-baseline] [--json]               runtime check in a real browser (axe-core + keyboard walk); needs playwright-core and axe-core
 fringe rules [dir] [--json]               per rule: open / baselined / silenced, to spot rules that don't suit this repo
 fringe handoff [dir|file] [--scan url]    a work order for another agent or CI (saved to .fringe/handoff.json)
@@ -2405,6 +2538,27 @@ async function runCli(argv, opts = {}) {
       return result.counts.error > 0 ? 1 : 0;
     } catch (e) {
       err(opts)(`fringe: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "login") {
+    try {
+      const url = rest.find((a, i) => !a.startsWith("--") && rest[i - 1] !== "--out");
+      if (!url) {
+        err(opts)("fringe: login needs a URL, e.g. fringe login http://localhost:3000/login\n");
+        return 2;
+      }
+      const cwd = opts.cwd ?? process.cwd();
+      const oi = rest.indexOf("--out");
+      const out = resolve(cwd, oi !== -1 ? rest[oi + 1] ?? "" : ".fringe/auth.json");
+      await saveSession(url, cwd, out, { headless: rest.includes("--headless"), wait: opts.waitForUser });
+      log(opts)(`fringe: session saved to ${out}
+It holds your logged-in cookies: keep it out of git. Use it with: fringe scan <url> --storage-state ${oi !== -1 ? rest[oi + 1] : ".fringe/auth.json"}`);
+      if (oi === -1 && existsSync5(join12(cwd, ".gitignore")) && !/\.fringe/.test(readFileSync11(join12(cwd, ".gitignore"), "utf8"))) log(opts)("fringe: your .gitignore does not list .fringe/: add it, or the session file could be committed.");
+      return 0;
+    } catch (e) {
+      err(opts)(`fringe: ${e.message}
 `);
       return 2;
     }
@@ -2431,7 +2585,7 @@ async function runCli(argv, opts = {}) {
       const h = buildHandoff(g.result, { root: g.root, target: g.target, ...g.only ? { only: g.only } : {}, ...g.scan ? { scan: g.scan } : {} }, g.limit);
       const oi = rest.indexOf("--out");
       const outFile = resolve(g.root, oi !== -1 ? rest[oi + 1] ?? "" : ".fringe/handoff.json");
-      mkdirSync5(dirname2(outFile), { recursive: true });
+      mkdirSync6(dirname3(outFile), { recursive: true });
       writeFileSync5(outFile, JSON.stringify(h, null, 2) + "\n");
       log(opts)(rest.includes("--json") ? JSON.stringify(h, null, 2) : h.prompt);
       err(opts)(`fringe: hand-off saved to ${outFile}; the receiving agent proves it is done with: fringe verify${oi !== -1 ? ` --handoff ${outFile}` : ""}

package/dist/index.d.ts

@@ -2,7 +2,8 @@ interface CliOpts {
     log?: (s: string) => void;
     cwd?: string;
     err?: (s: string) => void; /** Home directory for `init --global` (tests override it). */
-    home?: string;
+    home?: string; /** `fringe login` waits for this instead of Enter on the terminal (tests). */
+    waitForUser?: () => Promise<void>;
 }
 declare function runCli(argv: string[], opts?: CliOpts): Promise<number>;
 

package/dist/index.js

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

package/package.json

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

package/skill/fringe-help/SKILL.md

@@ -27,6 +27,7 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `check --update-baseline` | Accept today's findings; only new ones gate |
 | `scan <url>` | Runtime check of a live page: real contrast, keyboard walk, and named states from `fringe.scan.json` (needs `playwright-core` + `axe-core`) |
 | `plan [dir\|file] [--scan url]` | Ordered fix batches (shared components first) with recipes; `--scan` adds the live page |
+| `login <url>` | Log in once in a browser window and save the session, so `scan` can reach pages behind a sign-in |
 | `handoff` / `verify` | Work order for another agent or CI, and proof it was done (complete / partial / regressed) |
 | `rules` | Per rule: open / baselined / silenced, to spot rules that do not suit this repo |
 | `init --for <agents>` / `--git` | Rules file for Codex, Cursor, Copilot, Gemini…; commit gate for any agent |