diff --git a/README.md b/README.md index 05a392778..136172c46 100644 --- a/README.md +++ b/README.md @@ -267,6 +267,7 @@ On Windows without Developer Mode (MSYS2 / Git Bash), `setup` falls back to file | [Privacy & Telemetry](docs/privacy.md) | What is sent, what never is, the update check, outside reviews, egress receipts | | [Uninstall](docs/uninstall.md) | The uninstall script and manual removal | | [Diagrams & Document Formats](docs/howto-diagrams-and-formats.md) | Mermaid/excalidraw fences in PDFs, image sizing and safety defaults, `--to html\|docx`, `/diagram` triplets | +| [Preview a frontend](docs/howto-preview-a-frontend.md) | The loopback preview with canned API answers that `/design-review --build` checks, its fixtures, the state inventory, and the `gstack-design-build` receipt | | [First Production Deploy](docs/howto-bring-up-a-first-deploy.md) | What to do when `/setup-deploy` says nothing is deployed yet: hosting, env and secrets, DNS, checking it works, then back to `/setup-deploy` | | [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge | | [GBrain quick tour](docs/gbrain-quick-tour.md) | The four setup paths, MCP registration, the per-repo trust policy, memory sync, Conductor env vars | diff --git a/bin/gstack-design-build b/bin/gstack-design-build new file mode 100755 index 000000000..c27b064e2 --- /dev/null +++ b/bin/gstack-design-build @@ -0,0 +1,97 @@ +#!/usr/bin/env -S bun --no-env-file --config=/dev/null +// gstack-design-build — the receipt behind /design-review --build. The loop +// edits and looks; this decides what it proved (lib/design-build.ts). +// +// Usage: gstack-design-build plan --inventory --run-dir [--waivers ] +// gstack-design-build preflight --inventory [--grant-remote ...] +// gstack-design-build admit +// gstack-design-build verify-start --inventory --run-dir +// gstack-design-build receipt --inventory --run-dir --rounds [--preview ] [--waivers ] [--out-root ] +// gstack-design-build check --inventory --receipt +// +// Prints exactly one "DESIGN_BUILD: code= …" line for every +// outcome (preflight and admit print it only when they stop the run). Exit 0 +// clean or waived (and ok), 1 open, 4 incomplete, unrendered or stale, 3 usage. + +import * as fs from 'node:fs'; +import * as path from 'node:path'; +import { execFileSync } from 'node:child_process'; +import { resolveStateRoot } from '../lib/state-root'; +import { runScriptSync } from '../lib/script-invocation'; +import { admit, BuildUsageError, check, parseInventory, plan, preflight, receipt, servedStates, verifyStart } from '../lib/design-build'; + +const USAGE = 'usage: gstack-design-build plan|preflight|admit|verify-start|receipt|check (see docs/howto-preview-a-frontend.md#build-receipt)'; + +function flags(argv: string[]): { pos: string[]; one: Map; many: Map } { + const pos: string[] = []; + const one = new Map(); + const many = new Map(); + for (let i = 0; i < argv.length; i++) { + const a = argv[i]!; + if (!a.startsWith('--')) { pos.push(a); continue; } + const v = argv[++i]; + if (v === undefined) throw new BuildUsageError('USAGE', `${a} needs a value`, USAGE); + one.set(a, v); + many.set(a, [...(many.get(a) ?? []), v]); + } + return { pos, one, many }; +} + +function repoRoot(): string { + return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', timeout: 30_000 }).trim(); +} + +function slug(): string { + const out = runScriptSync(path.join(import.meta.dir, 'gstack-slug'), [], { encoding: 'utf8', timeout: 30_000 }).stdout ?? ''; + return /^SLUG=(.+)$/m.exec(out)?.[1]?.trim() || 'unknown'; +} + +async function main(argv: string[]): Promise { + const [cmd, ...rest] = argv; + const f = flags(rest); + const need = (k: string): string => { + const v = f.one.get(k); + if (!v) throw new BuildUsageError('USAGE', `${cmd} needs ${k}`, USAGE); + return v; + }; + const inventory = () => parseInventory(fs.readFileSync(need('--inventory'), 'utf8')); + switch (cmd) { + case 'plan': + for (const l of plan(inventory(), path.resolve(need('--run-dir')), f.one.get('--waivers'))) console.log(l); + return 0; + case 'preflight': { + const r = await preflight(inventory(), f.many.get('--grant-remote') ?? []); + for (const l of r.lines) console.log(l); + return r.exit; + } + case 'admit': { + if (!f.pos[0]) throw new BuildUsageError('USAGE', 'admit needs the gstack-skill-start output file', USAGE); + const r = admit(fs.readFileSync(f.pos[0], 'utf8')); + for (const l of r.lines) console.log(l); + return r.exit; + } + case 'verify-start': + console.log(verifyStart(repoRoot(), inventory(), path.resolve(need('--run-dir')))); + return 0; + case 'receipt': { + const outRoot = f.one.get('--out-root') ?? path.join(resolveStateRoot(), 'projects', slug(), 'designs'); + const inv = inventory(); + const r = receipt({ repo: repoRoot(), inv, runDir: path.resolve(need('--run-dir')), rounds: Number(need('--rounds')), previewDir: f.one.get('--preview'), served: await servedStates(inv), waivers: f.one.get('--waivers'), outRoot }); + console.log(r.line); + return r.exit; + } + case 'check': { + const r = check(repoRoot(), inventory(), need('--receipt')); + console.log(r.line); + return r.exit; + } + default: + throw new BuildUsageError('USAGE', `unknown command ${cmd ?? '(none)'}`, USAGE); + } +} + +main(process.argv.slice(2)).then((code) => process.exit(code), (e) => { + if (e instanceof BuildUsageError) console.error(`gstack-design-build: ${e.code}: ${e.message} | fix: ${e.fix}`); + else console.error(`gstack-design-build: ${(e as Error).message}`); + process.exit(3); +}); diff --git a/bin/gstack-skill-start b/bin/gstack-skill-start index 83049c678..6d2a52bae 100755 --- a/bin/gstack-skill-start +++ b/bin/gstack-skill-start @@ -706,6 +706,7 @@ Key routing rules: - QA/testing site behavior → invoke /qa or /qa-only - Code review/diff check → invoke /review - Visual polish → invoke /design-review +- Building UI → once it renders, invoke /design-review --build (opt-in) - Ship/deploy/PR → invoke /ship (merge + deploy: the user types /land-and-deploy) - Save progress → invoke /context-save - Resume context → invoke /context-restore diff --git a/capy/skill/gstack/lane-card.md b/capy/skill/gstack/lane-card.md index d04632ea8..6131f60f7 100644 --- a/capy/skill/gstack/lane-card.md +++ b/capy/skill/gstack/lane-card.md @@ -18,6 +18,7 @@ For a crew lane (a thread working for a Captain). Read this once `gstack: ok head=` names that head, and a later push needs a new /ship. - After dispatching /ship, end your turn and hold no PR watch until it completes. Then subscribe to the PR, read its checks and comments once, stop the /ship subagent and run `gstack-ship-queue ready`. - Never merge. The controller merges on a recorded standing approval. +- UI work (recommended, never a READY prerequisite): once the change renders, run `install.sh --check --for design-review` and `gstack-browser-ensure`, launch with the printed `GSTACK_LAUNCH` line, then `/design-review --build `, and paste its one `DESIGN_BUILD:` line in READY. A start that prints `GSTACK_RESULT: skill=design-review status=refused` is `DESIGN_BUILD: unrendered code=INSTALL` (`gstack-design-build admit ` prints it). `incomplete` does not count as having run it. ## Under a Captain diff --git a/changelog.d/design-review-build-loop.md b/changelog.d/design-review-build-loop.md new file mode 100644 index 000000000..b332a5273 --- /dev/null +++ b/changelog.d/design-review-build-loop.md @@ -0,0 +1,7 @@ +--- +bump: minor +--- +- **`/design-review --build ` is a new opt-in loop for UI you are still building.** It skips the audit's clean-tree stop and never commits, stashes or asks. It lists the states your change can show, lints each one with `gstack-design-lint --scope app` at 1440 and 375 wide, takes a screenshot of each, checks seven spacing and hit-area items, and fixes what fails for up to three rounds. Then it runs one more pass that changes nothing and prints a single `DESIGN_BUILD:` line. The lane card, the CLAUDE.md routing block, docs/skills.md and /design-html's last step recommend it for UI work, but it is not required before a pull request is ready. +- **New `gstack-design-build` decides that line in code, not in skill prose.** The result is clean, waived, open, incomplete, unrendered or stale. It reads the lint's JSON verdict, never its exit status. A skipped render, a state measured at only some sizes, a state with no screenshot, an API call the preview could not answer, evidence older than the final pass, or a tree edited after the final pass can never print clean. Preflight checks the browser first. It refuses a target that is not on this machine unless someone granted that host, and it turns a refused design-review start into `code=INSTALL`. It lets the loop click through changes only when the preview itself answers at every local page; any other page, or a redirect, means the loop leaves changed actions alone. The receipt is a private JSON file tied to a hash of the exact files it measured, and `gstack-design-build check` reports it stale after any later edit. +- **New preview template (`design-review/templates/preview-fixtures.mjs`) serves an app on 127.0.0.1 with canned API answers, one scenario per state (`?as=`).** It uses the app's own Vite and config, or `--static` for plain files. It never installs Vite. A small script it adds to every page carries the scenario to the app's own API calls. Any API request without a matching fixture gets a 501 that names the route and the file to edit, and never reaches a real backend. The log is private and hides tokens, the port is never silently moved, and `stop` shuts it down cleanly. See docs/howto-preview-a-frontend.md. +- **Design lint URLs are now redacted even when they do not parse** (a port out of range, for example) **and when a token value holds punctuation such as `)`.** Before, such tokens could show up in text, JSON, stderr and trace files. diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 0eaaa3e97..57ee215e5 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -597,6 +597,8 @@ Use AskUserQuestion: > B) Iterate more — keep refining > C) Done — I'll use this as a reference +After A, recommend (opt-in, never required) `/design-review --build ` once the component renders in the app, with each state on a loopback preview (`docs/howto-preview-a-frontend.md`); run `install.sh --check --for design-review` and `gstack-browser-ensure` first. + --- ## Important Rules diff --git a/design-html/SKILL.md.tmpl b/design-html/SKILL.md.tmpl index 9764b6a11..f38a84a80 100644 --- a/design-html/SKILL.md.tmpl +++ b/design-html/SKILL.md.tmpl @@ -456,6 +456,8 @@ Use AskUserQuestion: > B) Iterate more — keep refining > C) Done — I'll use this as a reference +After A, recommend (opt-in, never required) `/design-review --build ` once the component renders in the app, with each state on a loopback preview (`docs/howto-preview-a-frontend.md`); run `install.sh --check --for design-review` and `gstack-browser-ensure` first. + --- ## Important Rules diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 784ec2f66..8c6e3537a 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -2,7 +2,7 @@ name: design-review preamble-tier: 4 version: 2.0.0 -description: "Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. (gstack)" +description: "Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them; --build checks UI while you build it. (gstack)" allowed-tools: - Bash - Read @@ -16,6 +16,7 @@ triggers: - visual design audit - design qa - fix design issues + - check the UI I am building --- @@ -161,6 +162,8 @@ bun --no-env-file --config=/dev/null run $HOME/.claude/skills/gstack/bin/gstack- `DESIGN_MD_FORMAT: spec`: the front matter is normative. Run `bun --no-env-file --config=/dev/null run $HOME/.claude/skills/gstack/bin/gstack-design-md.ts tokens DESIGN.md` and calibrate against the flat token map: a value present there is never a finding, and a finding that departs from a token names the token. `legacy` or `unknown`: read the file as prose. The `DESIGN_MD_MARKER` line is the user's persisted format choice; respect it and never offer a conversion here (that is /design-consultation's question). `missing`: calibrate against the code tokens captured above, or universal principles when there are none. +**`--build`:** skip the clean-tree check; run **Check the Aside browser**, then its STOP in Phases 1-6, not the audit. + **Check for clean working tree:** ```bash @@ -975,10 +978,14 @@ sections. Read a section in full before doing its step; do not work from memory. | When | Read this section | |------|-------------------| +| a --build run | `sections/build-loop.md` | | a craft, Persuade or redesign audit | `sections/craft-audit.md` | | the outside-voice pass that precedes Phase 7 triage (Codex availability, consent, both voices and synthesis) | `sections/outside-voices.md` | | writing a Phase 8e.5 regression test with no known test command (detect the framework, or offer to bootstrap one) | `sections/test-bootstrap.md` | +> **STOP.** Before a --build run, Read `~/.claude/skills/gstack/design-review/sections/build-loop.md` and execute it +> in full. Do not work from memory — that section is the source of truth for this step. + > **STOP.** Before a craft, Persuade or redesign audit, Read `~/.claude/skills/gstack/design-review/sections/craft-audit.md` and execute it > in full. Do not work from memory — that section is the source of truth for this step. @@ -990,18 +997,18 @@ Record baseline design score and AI slop score at end of Phase 6. ``` $GSTACK_STATE_ROOT/projects/$SLUG/designs/design-audit-{YYYYMMDD}/ -├── design-audit-{domain}.md # Structured report +├── design-audit-{domain}.md # Structured report ├── screenshots/ -│ ├── first-impression.jpg # Phase 1 -│ ├── {page}-annotated.png # Per-page annotated -│ ├── {page}-mobile.jpg # Responsive +│ ├── first-impression.jpg # Phase 1 +│ ├── {page}-annotated.png # Per-page annotated +│ ├── {page}-mobile.jpg # Responsive │ ├── {page}-tablet.jpg │ ├── {page}-desktop.jpg -│ ├── finding-001-before.png # Before fix -│ ├── finding-001-target.png # Target mockup (if generated) -│ ├── finding-001-after.png # After fix +│ ├── finding-001-before.png # Before fix +│ ├── finding-001-target.png # Target mockup (if generated) +│ ├── finding-001-after.png # After fix │ └── ... -└── design-baseline.json # For regression mode +└── design-baseline.json # For regression mode ``` --- diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index 41dc7620f..4a72d22bc 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -4,7 +4,7 @@ preamble-tier: 4 version: 2.0.0 description: | Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, - AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues + AI slop patterns, and slow interactions — then fixes them; --build checks UI while you build it. Iteratively fixes issues in source code, committing each fix atomically and re-verifying with before/after screenshots. For plan-mode design review (before implementation), use /plan-design-review. Use when asked to "audit the design", "visual QA", "check if it looks good", or "design polish". (gstack) @@ -21,6 +21,7 @@ triggers: - visual design audit - design qa - fix design issues + - check the UI I am building --- {{PREAMBLE}} @@ -52,6 +53,8 @@ Look for `DESIGN.md`, `design-system.md`, or similar in the repo root, then for {{DESIGN_MD_CHECK:calibrate}} +**`--build`:** skip the clean-tree check; run **Check the Aside browser**, then its STOP in Phases 1-6, not the audit. + **Check for clean working tree:** ```bash @@ -113,6 +116,8 @@ Remember `RUN_ID` and restate it literally in later blocks (each bash block is a {{SECTION_INDEX:design-review}} +{{SECTION:build-loop}} + {{SECTION:craft-audit}} Record baseline design score and AI slop score at end of Phase 6. @@ -123,18 +128,18 @@ Record baseline design score and AI slop score at end of Phase 6. ``` $GSTACK_STATE_ROOT/projects/$SLUG/designs/design-audit-{YYYYMMDD}/ -├── design-audit-{domain}.md # Structured report +├── design-audit-{domain}.md # Structured report ├── screenshots/ -│ ├── first-impression.jpg # Phase 1 -│ ├── {page}-annotated.png # Per-page annotated -│ ├── {page}-mobile.jpg # Responsive +│ ├── first-impression.jpg # Phase 1 +│ ├── {page}-annotated.png # Per-page annotated +│ ├── {page}-mobile.jpg # Responsive │ ├── {page}-tablet.jpg │ ├── {page}-desktop.jpg -│ ├── finding-001-before.png # Before fix -│ ├── finding-001-target.png # Target mockup (if generated) -│ ├── finding-001-after.png # After fix +│ ├── finding-001-before.png # Before fix +│ ├── finding-001-target.png # Target mockup (if generated) +│ ├── finding-001-after.png # After fix │ └── ... -└── design-baseline.json # For regression mode +└── design-baseline.json # For regression mode ``` --- diff --git a/design-review/sections/build-loop.md b/design-review/sections/build-loop.md new file mode 100644 index 000000000..5dcc8abb8 --- /dev/null +++ b/design-review/sections/build-loop.md @@ -0,0 +1,116 @@ + + +## Build loop: /design-review --build + +Opt-in, for UI being built: lint and screenshot each state on a local +preview, fix, and end with one receipt line. It replaces the audit phases, +never commits, stashes, checks out or resets (the lane's edits stay), and +never asks when unattended (record NEEDS INPUT instead). +`gstack-design-build` decides the outcome; this section gathers the evidence. + +**The seven items** (walk each screenshot): + +| # | Item | Rule | +|---|------|------| +| 1 | Row padding holds with one line and with two | `row-crowding` (edge) | +| 2 | Adjacent rows have breathing room | `row-crowding` (next row) | +| 3 | Help copy has space above it and the muted treatment sibling sections use | `copy-flush-under-list` | +| 4 | Status notes sit on their own line with a warning treatment | `note-in-row-weight` | +| 5 | Heading over name over hint, as the sibling sections do it | eye only | +| 6 | Comfortable hit areas | `small-hit-area` | +| 7 | Nothing overflows at 375 | `section-overflow` | + +For items 3 and 5 the repo's house style wins: judge against a sibling +section. + +### 1. Inventory + +```bash +SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null) +GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}" +RUN="$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-build-run-$(date -u +%Y%m%dT%H%M%SZ)" +mkdir -p "$RUN" && chmod 700 "$RUN" && echo "RUN: $RUN" +``` + +Each block is a fresh shell: `` is the printed `RUN:` path. Write `/inventory.json` from the spec and the diff: every +scenario × overlay × busy, success, error and empty that the change can show. + +```json +{"version":1,"within":"
","fixtures":"","touched":[""], + "states":[{"name":"owner","url":"http://127.0.0.1:5300/settings?as=owner","expect":""}, + {"name":"remove-confirm","mode":"screenshot","steps":"click Remove on the second row"}]} +``` + +A URL state gets `?as=` and an `expect` selector proving it +rendered with its data. A state that needs clicks is `"mode":"screenshot"` +and is never counted as linted. Preview and fixtures: +`docs/howto-preview-a-frontend.md`. + +### 2. Preflight (before any round) + +```bash +~/.claude/skills/gstack/bin/gstack-design-build preflight --inventory "/inventory.json" +``` + +Browser first, then targets (loopback only; another host needs a +`--grant-remote ` the person wrote; never add one yourself), then +reachability. A `DESIGN_BUILD:` line here is the run's final line: stop. On +`code=NO_PREVIEW`, start the preview and rerun preflight once. Under +`mutations=unknown` (no preview answered), never drive changed actions: +they may reach a live backend. + +### 3. Rounds (three at most) + +```bash +~/.claude/skills/gstack/bin/gstack-design-build plan --inventory "/inventory.json" --run-dir "/round-N" +``` + +1. Run the printed `LINT_CMD:` line exactly. Read `/round-N/lint.json`: + `app.verdict`, `app.codes`, `app.states[]` and the findings. Never + read the lint's exit status as the result. +2. Take a screenshot for every `SHOT:` line at its viewport (screenshot-only + states by their steps). Save it where the driver can write (Aside's + session directory; /tmp for $B), then cp it to the `SHOT:` path. +3. Walk the seven items on every screenshot. +4. Drive each changed action through busy, success, error and recovery, + and keyboard close back to its trigger. +5. Fix in source and fixtures. Leave the edits uncommitted. + +An incomplete state (a code in `app.states[]`) is a harness problem, not a +round: fix its named cause and rerun it. A preview 501 ends the run: add its +route, restart the preview, rerun from preflight. Stop +editing after round 3, or earlier once a round is clean. + +### 4. Final verification (read-only) and the receipt + +After the last permitted edit, one pass that changes nothing (to waive +findings, add `--waivers ` to `plan` and `receipt`): + +```bash +~/.claude/skills/gstack/bin/gstack-design-build plan --inventory "/inventory.json" --run-dir "/final" +~/.claude/skills/gstack/bin/gstack-design-build verify-start --inventory "/inventory.json" --run-dir "/final" +``` + +Run its `LINT_CMD:` line and every `SHOT:` line, then (`N`: rounds you edited +in; add `--preview ` if the preview served it): + +```bash +N= +~/.claude/skills/gstack/bin/gstack-design-build receipt --inventory "/inventory.json" --run-dir "/final" --rounds "${N:?}" +``` + +Its `DESIGN_BUILD:` line, unchanged, is the run's last and only one. There is no +fourth editing round without a written grant. + +### 5. Outcomes + +| Outcome | Means | Next | +|---------|-------|------| +| `clean` / `waived` | every URL state linted at every viewport, every state shot, nothing open | report it | +| `open` | complete coverage, open findings | each one gets a waiver with its reason, or a PR body line | +| `incomplete` | a state not linted everywhere, not shot, a preview 501, or stale evidence | its fix line; list the rest unverified in the PR body | +| `unrendered` | install, browser or preview missing | its fix line | +| `stale` | the tree changed after the receipt | rerun the final pass | + +Before READY quotes it, `~/.claude/skills/gstack/bin/gstack-design-build check --inventory "/inventory.json" --receipt ` +must reprint it. `incomplete` never satisfies the lane card's recommendation. diff --git a/design-review/sections/build-loop.md.tmpl b/design-review/sections/build-loop.md.tmpl new file mode 100644 index 000000000..6cbe0c36e --- /dev/null +++ b/design-review/sections/build-loop.md.tmpl @@ -0,0 +1,114 @@ +## Build loop: /design-review --build + +Opt-in, for UI being built: lint and screenshot each state on a local +preview, fix, and end with one receipt line. It replaces the audit phases, +never commits, stashes, checks out or resets (the lane's edits stay), and +never asks when unattended (record NEEDS INPUT instead). +`gstack-design-build` decides the outcome; this section gathers the evidence. + +**The seven items** (walk each screenshot): + +| # | Item | Rule | +|---|------|------| +| 1 | Row padding holds with one line and with two | `row-crowding` (edge) | +| 2 | Adjacent rows have breathing room | `row-crowding` (next row) | +| 3 | Help copy has space above it and the muted treatment sibling sections use | `copy-flush-under-list` | +| 4 | Status notes sit on their own line with a warning treatment | `note-in-row-weight` | +| 5 | Heading over name over hint, as the sibling sections do it | eye only | +| 6 | Comfortable hit areas | `small-hit-area` | +| 7 | Nothing overflows at 375 | `section-overflow` | + +For items 3 and 5 the repo's house style wins: judge against a sibling +section. + +### 1. Inventory + +```bash +SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null) +GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}" +RUN="$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-build-run-$(date -u +%Y%m%dT%H%M%SZ)" +mkdir -p "$RUN" && chmod 700 "$RUN" && echo "RUN: $RUN" +``` + +Each block is a fresh shell: `` is the printed `RUN:` path. Write `/inventory.json` from the spec and the diff: every +scenario × overlay × busy, success, error and empty that the change can show. + +```json +{"version":1,"within":"
","fixtures":"","touched":[""], + "states":[{"name":"owner","url":"http://127.0.0.1:5300/settings?as=owner","expect":""}, + {"name":"remove-confirm","mode":"screenshot","steps":"click Remove on the second row"}]} +``` + +A URL state gets `?as=` and an `expect` selector proving it +rendered with its data. A state that needs clicks is `"mode":"screenshot"` +and is never counted as linted. Preview and fixtures: +`docs/howto-preview-a-frontend.md`. + +### 2. Preflight (before any round) + +```bash +{{BIN_DIR}}/gstack-design-build preflight --inventory "/inventory.json" +``` + +Browser first, then targets (loopback only; another host needs a +`--grant-remote ` the person wrote; never add one yourself), then +reachability. A `DESIGN_BUILD:` line here is the run's final line: stop. On +`code=NO_PREVIEW`, start the preview and rerun preflight once. Under +`mutations=unknown` (no preview answered), never drive changed actions: +they may reach a live backend. + +### 3. Rounds (three at most) + +```bash +{{BIN_DIR}}/gstack-design-build plan --inventory "/inventory.json" --run-dir "/round-N" +``` + +1. Run the printed `LINT_CMD:` line exactly. Read `/round-N/lint.json`: + `app.verdict`, `app.codes`, `app.states[]` and the findings. Never + read the lint's exit status as the result. +2. Take a screenshot for every `SHOT:` line at its viewport (screenshot-only + states by their steps). Save it where the driver can write (Aside's + session directory; /tmp for $B), then cp it to the `SHOT:` path. +3. Walk the seven items on every screenshot. +4. Drive each changed action through busy, success, error and recovery, + and keyboard close back to its trigger. +5. Fix in source and fixtures. Leave the edits uncommitted. + +An incomplete state (a code in `app.states[]`) is a harness problem, not a +round: fix its named cause and rerun it. A preview 501 ends the run: add its +route, restart the preview, rerun from preflight. Stop +editing after round 3, or earlier once a round is clean. + +### 4. Final verification (read-only) and the receipt + +After the last permitted edit, one pass that changes nothing (to waive +findings, add `--waivers ` to `plan` and `receipt`): + +```bash +{{BIN_DIR}}/gstack-design-build plan --inventory "/inventory.json" --run-dir "/final" +{{BIN_DIR}}/gstack-design-build verify-start --inventory "/inventory.json" --run-dir "/final" +``` + +Run its `LINT_CMD:` line and every `SHOT:` line, then (`N`: rounds you edited +in; add `--preview ` if the preview served it): + +```bash +N= +{{BIN_DIR}}/gstack-design-build receipt --inventory "/inventory.json" --run-dir "/final" --rounds "${N:?}" +``` + +Its `DESIGN_BUILD:` line, unchanged, is the run's last and only one. There is no +fourth editing round without a written grant. + +### 5. Outcomes + +| Outcome | Means | Next | +|---------|-------|------| +| `clean` / `waived` | every URL state linted at every viewport, every state shot, nothing open | report it | +| `open` | complete coverage, open findings | each one gets a waiver with its reason, or a PR body line | +| `incomplete` | a state not linted everywhere, not shot, a preview 501, or stale evidence | its fix line; list the rest unverified in the PR body | +| `unrendered` | install, browser or preview missing | its fix line | +| `stale` | the tree changed after the receipt | rerun the final pass | + +Before READY quotes it, `{{BIN_DIR}}/gstack-design-build check --inventory "/inventory.json" --receipt ` +must reprint it. `incomplete` never satisfies the lane card's recommendation. diff --git a/design-review/sections/manifest.json b/design-review/sections/manifest.json index 6404a64c9..f93683afb 100644 --- a/design-review/sections/manifest.json +++ b/design-review/sections/manifest.json @@ -4,6 +4,12 @@ "version": 1, "note": "PASSIVE registry (v2 plan T9 / CM2). Fields are IDs, file paths, human titles, and human-readable trigger text ONLY. The skeleton's decision-tree prose is the ONLY place that decides WHEN to read a section. Carved on every host (CARVED_ON_EVERY_HOST in scripts/resolvers/sections.ts).", "sections": [ + { + "id": "build-loop", + "file": "build-loop.md", + "title": "Build loop: /design-review --build", + "trigger": "a --build run" + }, { "id": "craft-audit", "file": "craft-audit.md", diff --git a/design-review/templates/preview-fixtures.mjs b/design-review/templates/preview-fixtures.mjs new file mode 100644 index 000000000..adbe42872 --- /dev/null +++ b/design-review/templates/preview-fixtures.mjs @@ -0,0 +1,278 @@ +#!/usr/bin/env node +// gstack preview fixtures: serve a frontend on loopback with canned API +// answers, one scenario per state, so /design-review --build can lint and +// screenshot the states a spec names. docs/howto-preview-a-frontend.md is the +// contract. Two ways to run it: +// +// start --root --fixtures [--port 5300] [--api /api/] [--state ] [--static] +// Without --static: the repo's own Vite (resolved from --root, never +// installed by gstack) with its own config plus this file's plugin. +// With --static: a plain file server over --root (a built or hand-written +// page) with the same shim and fixture API. +// stop --state (or --port , which finds the default state dir) +// +// A request under the API prefix is answered only from +// /.json; anything else under the prefix is a 501 problem +// document naming the route and the file to edit, recorded in +// /unhandled.jsonl, never passed to a live backend; so is a path the +// app's own server.proxy would forward. Loopback only, a +// port this process owns (strict), a private redacted log, a clean stop. +// +// Plugin use inside a repo's vite.config: import { gstackPreviewFixtures } +// from this file and add gstackPreviewFixtures({ fixtures: '' }). + +import * as fs from 'node:fs'; +import * as http from 'node:http'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { createRequire } from 'node:module'; +import { pathToFileURL } from 'node:url'; + +const DOC = 'https://github.com/garrytan/gstack/blob/main/docs/howto-preview-a-frontend.md'; +const HOST = '127.0.0.1'; +const SCENARIO = /^[A-Za-z0-9._-]{1,64}$/; +const SECRET_PARAM = /token|key|secret|auth|session|sig|signature|password|pass|code|jwt|bearer/i; + +export const FIXES = { + PREVIEW_NO_VITE: 'install vite in the app (npm i -D vite), or pass --static to serve built files', + PREVIEW_CONFIG: "fix the app's vite config so 'vite' starts on its own, then rerun", + PREVIEW_PORT: 'stop whatever holds the port, or pass another --port', + PREVIEW_HOST: 'the preview listens on 127.0.0.1 only; drop --host', + PREVIEW_USAGE: 'see ' + DOC, + PREVIEW_NO_SCENARIO: 'open the page with ?as=; the shim carries it to API calls', + PREVIEW_UNKNOWN_SCENARIO: 'add /.json with {"version":1,"routes":{}}', + PREVIEW_UNHANDLED: 'add the route to the scenario file', + PREVIEW_LIVE_PROXY: 'serve the route under the API prefix from a fixture', + PREVIEW_STATE: 'pass --state ', +}; + +/** Userinfo dropped and secret-looking parameter values replaced, up to the next &, # or whitespace. */ +export function redact(s) { + return String(s) + .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/?#@]*@/gi, '$1') + .replace(/([?&#;])([^=&#?;\s]+)=([^&#\s]*)/g, (all, sep, key) => (SECRET_PARAM.test(key) ? `${sep}${key}=REDACTED` : all)); +} + +/** The script every HTML page gets first: ?as= persists for the tab and rides every same-origin fetch and XHR as x-gstack-scenario. */ +export const SHIM = `(function(){var K='gstack-scenario',q=null;try{q=new URLSearchParams(location.search).get('as');if(q!==null)sessionStorage.setItem(K,q);else q=sessionStorage.getItem(K);}catch(e){} +if(!q)return;window.__gstackScenario=q; +function same(u){try{return new URL(u,location.href).origin===location.origin}catch(e){return false}} +var f=window.fetch;if(f){window.fetch=function(input,init){var u=typeof input==='string'?input:(input&&input.url)||String(input);if(!same(u))return f.call(this,input,init);init=Object.assign({},init||{});var h=new Headers(init.headers||(typeof Request!=='undefined'&&input instanceof Request?input.headers:undefined));h.set('x-gstack-scenario',q);init.headers=h;return f.call(this,input,init)}} +var X=window.XMLHttpRequest&&XMLHttpRequest.prototype;if(X){var o=X.open,s=X.send;X.open=function(m,u){this.__gstackSame=same(u);return o.apply(this,arguments)};X.send=function(){if(this.__gstackSame)this.setRequestHeader('x-gstack-scenario',q);return s.apply(this,arguments)}}})();`; + +export function injectShim(html) { + const tag = ``; + return /]*>/i.test(html) ? html.replace(/]*>/i, (h) => h + tag) : tag + html; +} + +function scenarioOf(req, url) { + const header = req.headers['x-gstack-scenario']; + if (typeof header === 'string' && header) return header; + const q = url.searchParams.get('as'); + if (q) return q; + try { return new URL(req.headers.referer ?? '').searchParams.get('as') ?? ''; } catch { return ''; } +} + +function matchRoute(routes, method, pathname) { + if (routes[`${method} ${pathname}`]) return routes[`${method} ${pathname}`]; + const parts = pathname.split('/'); + for (const [key, value] of Object.entries(routes)) { + const [m, p] = key.split(' '); + if (m !== method || !p) continue; + const want = p.split('/'); + if (want.length === parts.length && want.every((w, i) => w.startsWith(':') || w === parts[i])) return value; + } + return null; +} + +/** Connect-style middleware answering the API prefix from fixtures; everything else goes to next(). */ +export function createFixtureMiddleware({ fixtures, api = '/api/', stateDir, log = () => {}, proxied = [] }) { + const record = (hit) => { if (stateDir) fs.appendFileSync(path.join(stateDir, 'unhandled.jsonl'), JSON.stringify(hit) + '\n', { mode: 0o600 }); }; + return (req, res, next) => { + const url = new URL(req.url ?? '/', 'http://' + HOST); + const method = (req.method ?? 'GET').toUpperCase(); + const scenario = scenarioOf(req, url); + const fail = (code, detail, fixLine) => { + record({ scenario, method, path: redact(url.pathname), code }); + log(`${method} ${redact(url.pathname + url.search)} 501 ${code} scenario=${scenario || '-'}`); + res.writeHead(501, { 'content-type': 'application/problem+json', 'x-gstack-preview': code, 'cache-control': 'no-store' }); + res.end(JSON.stringify({ type: `${DOC}#${code.toLowerCase().replace(/_/g, '-')}`, title: 'No fixture answers this request', status: 501, code, detail, fix: fixLine })); + }; + const live = url.pathname.startsWith(api) ? undefined : proxied.find((k) => (k.startsWith('^') ? new RegExp(k).test(req.url ?? '/') : (req.url ?? '/').startsWith(k))); + if (live !== undefined) return fail('PREVIEW_LIVE_PROXY', `${method} ${url.pathname} matches the app's dev proxy "${live}", a live backend`, `serve it under ${api} from a fixture`); + if (!url.pathname.startsWith(api)) return next(); + if (url.pathname === api + '__gstack-preview') { res.writeHead(204, { 'x-gstack-preview': 'ready', 'x-gstack-preview-state': stateDir ? encodeURIComponent(stateDir) : '', 'cache-control': 'no-store' }); return res.end(); } + if (!scenario) return fail('PREVIEW_NO_SCENARIO', `${method} ${url.pathname} arrived with no scenario (no x-gstack-scenario header, ?as= or Referer ?as=)`, FIXES.PREVIEW_NO_SCENARIO); + const file = path.join(fixtures, `${scenario}.json`); + if (!SCENARIO.test(scenario) || !fs.existsSync(file)) return fail('PREVIEW_UNKNOWN_SCENARIO', `scenario "${redact(scenario)}" has no fixture file`, `add ${path.join(fixtures, '.json')} with {"version":1,"routes":{}}`); + let doc; + try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return fail('PREVIEW_UNKNOWN_SCENARIO', `${file} is not JSON (${e.message})`, 'fix the JSON in ' + file); } + const route = matchRoute(doc.routes ?? {}, method, url.pathname); + if (!route) return fail('PREVIEW_UNHANDLED', `scenario "${scenario}" has no route "${method} ${url.pathname}"`, `add "${method} ${url.pathname}": {"status":200,"json":…} to ${file}`); + const status = Number(route.status ?? 200); + const finish = () => { + try { res.writeHead(status, { 'content-type': 'json' in route ? 'application/json' : 'text/plain', 'cache-control': 'no-store', ...(route.headers ?? {}) }); } + catch (e) { return fail('PREVIEW_UNKNOWN_SCENARIO', `route "${method} ${url.pathname}" in ${file} has a bad status or header (${e.message})`, 'fix that route in ' + file); } + log(`${method} ${redact(url.pathname + url.search)} ${status} scenario=${scenario}`); + res.end('json' in route ? JSON.stringify(route.json) : String(route.body ?? '')); + }; + req.resume(); + if (route.delay_ms) setTimeout(finish, Number(route.delay_ms)); else finish(); + }; +} + +/** The Vite plugin: the shim in every HTML page, the fixture API ahead of the app's own middleware. */ +export function gstackPreviewFixtures({ fixtures, api = '/api/', stateDir, log } = {}) { + return { + name: 'gstack-preview-fixtures', + apply: 'serve', + transformIndexHtml: () => [{ tag: 'script', attrs: { 'data-gstack-preview': '' }, children: SHIM, injectTo: 'head-prepend' }], + configureServer(server) { server.middlewares.use(createFixtureMiddleware({ fixtures: path.resolve(fixtures), api, stateDir, log, proxied: Object.keys(server.config?.server?.proxy ?? {}) })); }, + }; +} + +const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.woff2': 'font/woff2', '.ico': 'image/x-icon' }; + +function staticHandler(root, api) { + const base = path.resolve(root); + return (req, res) => { + const url = new URL(req.url ?? '/', 'http://' + HOST); + let file; + try { file = path.join(base, decodeURIComponent(url.pathname)); } catch { res.writeHead(400, { 'content-type': 'text/plain' }); return res.end('bad escape in the path'); } + if (file !== base && !file.startsWith(base + path.sep)) { res.writeHead(403); return res.end('outside the preview root'); } + if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html'); + if (!fs.existsSync(file) && !path.extname(url.pathname) && !url.pathname.startsWith(api)) file = path.join(base, 'index.html'); + if (!fs.existsSync(file)) { res.writeHead(404, { 'content-type': 'text/plain' }); return res.end('not found'); } + const ext = path.extname(file); + const body = fs.readFileSync(file); + res.writeHead(200, { 'content-type': TYPES[ext] ?? 'application/octet-stream', 'cache-control': 'no-store' }); + res.end(ext === '.html' ? injectShim(body.toString('utf8')) : body); + }; +} + +class PreviewError extends Error { + constructor(code, message) { super(message); this.code = code; } +} + +function parseArgs(argv) { + const out = { _: [] }; + for (let i = 0; i < argv.length; i++) { + const a = argv[i]; + if (a === '--static') out.static = true; + else if (a.startsWith('--')) { + if (argv[i + 1] === undefined) throw new PreviewError('PREVIEW_USAGE', `${a} needs a value`); + out[a.slice(2)] = argv[++i]; + } else out._.push(a); + } + return out; +} + +/** The app's own Vite: a node_modules/vite at or above the root. A runtime's global cache (Bun's auto-install) does not count. */ +function hasLocalVite(root) { + for (let dir = root; ; dir = path.dirname(dir)) { + if (fs.existsSync(path.join(dir, 'node_modules', 'vite', 'package.json'))) return true; + if (path.dirname(dir) === dir) return false; + } +} + +const defaultState = (port) => path.join(os.tmpdir(), `gstack-preview-${port}`); +const ownState = (dir) => { + const st = fs.lstatSync(dir); + if (st.isSymbolicLink() || !st.isDirectory() || (process.getuid && st.uid !== process.getuid())) throw new PreviewError('PREVIEW_STATE', `${dir} is a link or not a directory this user owns`); +}; + +async function start(o) { + if (o.host && o.host !== HOST && o.host !== 'localhost') throw new PreviewError('PREVIEW_HOST', `--host ${o.host} is not loopback`); + if (!o.root || !o.fixtures) throw new PreviewError('PREVIEW_USAGE', 'start needs --root and --fixtures '); + const port = Number(o.port ?? 5300); + if (!Number.isInteger(port) || port < 0 || port > 65535) throw new PreviewError('PREVIEW_USAGE', `--port ${o.port} is not a port number`); + const api = o.api ?? '/api/'; + const root = path.resolve(o.root); + const fixtures = path.resolve(o.fixtures); + const stateDir = path.resolve(o.state ?? defaultState(port || 'auto')); + fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 }); + ownState(stateDir); + fs.chmodSync(stateDir, 0o700); + const logFile = path.join(stateDir, 'preview.log'); + fs.writeFileSync(logFile, '', { mode: 0o600 }); + fs.chmodSync(logFile, 0o600); + fs.rmSync(path.join(stateDir, 'unhandled.jsonl'), { force: true }); + const log = (line) => fs.appendFileSync(logFile, `${new Date().toISOString()} ${redact(line)}\n`); + const fixtureMw = createFixtureMiddleware({ fixtures, api, stateDir, log }); + + let close; + let actualPort; + if (o.static) { + const serve = staticHandler(root, api); + const server = http.createServer((req, res) => fixtureMw(req, res, () => { log(`${req.method} ${redact(req.url)}`); serve(req, res); })); + await new Promise((resolve, reject) => { + server.once('error', (e) => reject(e.code === 'EADDRINUSE' ? new PreviewError('PREVIEW_PORT', `port ${port} on ${HOST} is taken`) : e)); + server.listen(port, HOST, resolve); + }); + actualPort = server.address().port; + close = () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r()); }); + } else { + let vitePath; + try { + if (!hasLocalVite(root)) throw new Error('no node_modules/vite'); + vitePath = createRequire(path.join(root, 'package.json')).resolve('vite'); + } catch { throw new PreviewError('PREVIEW_NO_VITE', `no vite package resolves from ${root}`); } + const vite = await import(pathToFileURL(vitePath).href); + let server; + try { + server = await vite.createServer({ root, logLevel: 'silent', server: { host: HOST, port, strictPort: true }, plugins: [gstackPreviewFixtures({ fixtures, api, stateDir, log })] }); + } catch (e) { throw new PreviewError('PREVIEW_CONFIG', `vite could not load the app's config: ${redact(e.message)}`); } + try { await server.listen(); } catch (e) { + await server.close(); + throw /EADDRINUSE|in use/.test(e.message) ? new PreviewError('PREVIEW_PORT', `port ${port} on ${HOST} is taken`) : new PreviewError('PREVIEW_CONFIG', redact(e.message)); + } + actualPort = server.httpServer.address().port; + close = () => server.close(); + } + const url = `http://${HOST}:${actualPort}/`; + fs.writeFileSync(path.join(stateDir, 'preview.json'), JSON.stringify({ pid: process.pid, port: actualPort, url, log: logFile }) + '\n', { mode: 0o600 }); + let stopping = false; + const stop = async () => { + if (stopping) return; + stopping = true; + await close(); + fs.rmSync(path.join(stateDir, 'preview.json'), { force: true }); + log('stopped'); + process.exit(0); + }; + process.on('SIGTERM', stop); + process.on('SIGINT', stop); + console.log(`PREVIEW: ready url=${url} mode=${o.static ? 'static' : 'vite'} state=${stateDir} log=${logFile}`); +} + +async function stopCmd(o) { + const stateDir = path.resolve(o.state ?? defaultState(o.port ?? 5300)); + const file = path.join(stateDir, 'preview.json'); + if (!fs.existsSync(file)) { console.log(`PREVIEW: stopped (nothing running for ${stateDir})`); return; } + ownState(stateDir); + const { pid, port } = JSON.parse(fs.readFileSync(file, 'utf8')); + const alive = () => { try { process.kill(pid, 0); return true; } catch { return false; } }; + if (alive()) process.kill(pid, 'SIGTERM'); + const running = () => fs.existsSync(file) && alive(); + for (let i = 0; i < 50 && running(); i++) await new Promise((r) => setTimeout(r, 100)); + if (running()) throw new PreviewError('PREVIEW_STOP', `process ${pid} did not stop within 5 s`); + fs.rmSync(file, { force: true }); + console.log(`PREVIEW: stopped port=${port}`); +} + +async function main(argv) { + const [cmd, ...rest] = argv; + const o = parseArgs(rest); + if (cmd === 'start') return start(o); + if (cmd === 'stop') return stopCmd(o); + throw new PreviewError('PREVIEW_USAGE', 'usage: preview-fixtures.mjs start --root --fixtures [--port 5300] [--api /api/] [--state ] [--static] | stop --state '); +} + +const invoked = process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname); +if (invoked) { + main(process.argv.slice(2)).catch((e) => { + const code = e.code && FIXES[e.code] !== undefined ? e.code : e.code === 'PREVIEW_STOP' ? e.code : 'PREVIEW_CONFIG'; + console.error(`PREVIEW: fail code=${code} ${redact(e.message)} | fix: ${FIXES[code] ?? 'kill the process named, then rerun'}`); + process.exit(code === 'PREVIEW_USAGE' || code === 'PREVIEW_HOST' ? 3 : 4); + }); +} diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md index ca59c24fc..6c5f35dd4 100644 --- a/docs/PROJECT_STRUCTURE.md +++ b/docs/PROJECT_STRUCTURE.md @@ -49,7 +49,7 @@ gstack/ │ └── skill-e2e-*.test.ts # Tier 2: E2E via claude -p (~$3.85/run, split by category) ├── qa/, qa-only/ # Surface-aware browser/functional QA; /qa-only reports and proposes tests without product edits ├── plan-design-review/ # /plan-design-review skill (report-only design audit) -├── design-review/ # /design-review skill (design audit + fix loop) +├── design-review/ # /design-review skill (design audit + fix loop; --build loop for UI in progress, templates/preview-fixtures.mjs = the loopback preview with canned API answers, docs/howto-preview-a-frontend.md) ├── ship/ # Ship workflow skill ├── review/ # PR review skill (checklist.md is hand-written; design-checklist.md is GENERATED from lib/design-catalog.ts) ├── deslop-shared-libs/ # Recommendations-only audit for worthwhile shared-code extractions @@ -75,7 +75,7 @@ gstack/ ├── freeze/ # /freeze skill; bin/check-freeze.sh (PreToolUse edit-boundary hook; sources careful/bin/hook-extract.sh, fails closed) ├── guard/, unfreeze/ # /guard (careful + freeze in one), /unfreeze ├── gstack-upgrade/ # /gstack-upgrade skill + migrations/ (run after ./setup during an upgrade) -├── bin/ # CLI utilities (gstack-render.ts = render a local HTML file through Aside or the engine, gstack-design-detect.ts = probe/scan through a user-installed impeccable engine; gstack-design-md.ts = open DESIGN.md check/convert/tokens/mark; gstack-design-lint = the free deterministic design lint over HTML/CSS/components, --render measures in the browser, --scope app measures one app section's spacing (docs/design-lint.md); gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, gstack-memorable, etc.) +├── bin/ # CLI utilities (gstack-render.ts = render a local HTML file through Aside or the engine, gstack-design-detect.ts = probe/scan through a user-installed impeccable engine; gstack-design-md.ts = open DESIGN.md check/convert/tokens/mark; gstack-design-lint = the free deterministic design lint over HTML/CSS/components, --render measures in the browser, --scope app measures one app section's spacing (docs/design-lint.md); gstack-design-build = the /design-review --build receipt (preflight, admit, plan, verify-start, receipt, check); gstack-repo-mode, gstack-slug, gstack-config, gstack-wtree, gstack-evidence, gstack-issue-guard, gstack-relink, gstack-memorable, etc.) ├── document-release/ # /document-release skill (every-ship pre-verification audit; standalone doc updates + Diataxis coverage map) ├── document-generate/ # /document-generate skill (Diataxis doc generator: tutorial/how-to/reference/explanation) ├── cso/ # /cso skill (OWASP Top 10 + STRIDE security audit) @@ -95,7 +95,7 @@ gstack/ ├── agents-digest/ # Committed 2KB instruction-tier rules digest (gstack-AGENTS.md) for rules-reading hosts ├── modules/ # loadouts.json (+ loadouts.schema.json): model rungs, the model map, pinned modules and named loadouts; read by scripts/modules.ts and lib/model-detect.ts, rendered by bin/gstack-modules (docs/loadouts.md) ├── extension/ # Chrome extension (side panel + activity feed + CSS inspector) -├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; design-catalog.ts = the typed design anti-pattern catalog every design skill renders from; design-lint/ = the static and render tiers behind bin/gstack-design-lint, ported from hallmark's sloplint; design-detect-contract.ts = detector sentinel vocabulary; design-md.ts = open DESIGN.md reader/writer; dom-dump-script.ts + generated dom-dump.js = rendered-DOM dump for the detector; review-evidence.ts = review-start receipt binding, computed freshness and shared-code snapshot eligibility; frontend-scope.ts; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/) +├── lib/ # Shared libraries (aside-render.ts = local-HTML rendering, Aside first, engine fallback; design-catalog.ts = the typed design anti-pattern catalog every design skill renders from; design-lint/ = the static and render tiers behind bin/gstack-design-lint, ported from hallmark's sloplint; design-build.ts = the outcome logic behind bin/gstack-design-build; design-detect-contract.ts = detector sentinel vocabulary; design-md.ts = open DESIGN.md reader/writer; dom-dump-script.ts + generated dom-dump.js = rendered-DOM dump for the detector; review-evidence.ts = review-start receipt binding, computed freshness and shared-code snapshot eligibility; frontend-scope.ts; claude-bin.ts, error-handling.ts, worktree.ts, egress-receipt.ts, context-bill.ts, redact-engine.ts, tracker-guard.ts, version-source.ts, code-intelligence/) │ └── diagram-render/ # Vendored mermaid + excalidraw runtimes, built into one offline bundle the renderer loads ├── patches/ # bun `patchedDependencies` patches (playwright-core windowsHide) ├── docs/designs/ # Design documents (incl. IMPECCABLE_INTEROP.md = the design detector / catalog / open DESIGN.md record, and fork-port-residual-2026-09/ evaluation evidence) diff --git a/docs/design-lint.md b/docs/design-lint.md index 7c76dbb9e..bd229081d 100644 --- a/docs/design-lint.md +++ b/docs/design-lint.md @@ -453,7 +453,9 @@ Every URL a person sees (text, JSON, stderr, traces, state names) has its userinfo dropped and the value of any query or `#fragment` parameter whose name contains token, key, secret, auth, session, sig, signature, password, pass, code, jwt or bearer replaced with `REDACTED`; the page is opened at the -real URL. +real URL. A URL that does not parse (a port out of range, say) and URLs +inside error text are redacted by pattern, and a value runs to the next `&`, +`#` or whitespace, so punctuation inside a token never lets its tail through. ## Token names the rules read diff --git a/docs/howto-preview-a-frontend.md b/docs/howto-preview-a-frontend.md new file mode 100644 index 000000000..d9f5546e1 --- /dev/null +++ b/docs/howto-preview-a-frontend.md @@ -0,0 +1,150 @@ +# Preview a frontend for /design-review --build + +Three commands, from the app's repo, with gstack installed at +`~/.claude/skills/gstack`: + +```bash +P=~/.claude/skills/gstack/design-review/templates/preview-fixtures.mjs +node $P start --root . --fixtures .gstack-preview/fixtures --port 5300 --state ~/.gstack/preview-5300 & +# PREVIEW: ready url=http://127.0.0.1:5300/ mode=vite state=/.gstack/preview-5300 log=/.gstack/preview-5300/preview.log + +curl -s -H 'x-gstack-scenario: owner' http://127.0.0.1:5300/api/members +# [{"name":"Dana Whitfield","role":"Owner"},{"name":"Omar Haddad","role":"Editor"}] + +node $P stop --state ~/.gstack/preview-5300 +# PREVIEW: stopped port=5300 +``` + +The template runs the app's own Vite (resolved from `--root`'s +`node_modules`, with the app's own config; gstack never installs Vite) plus a +fixture plugin. `--static` serves a directory of built or hand-written +files instead, with the same fixture API; gstack's own tests use that mode on +`test/fixtures/ui-spacing/preview/`. It runs under Node or Bun. + +## What it guarantees + +- **Loopback only.** It listens on 127.0.0.1; any other `--host` exits 3 + (`PREVIEW_HOST`). +- **An owned port.** The port is strict: if something holds it, it exits 4 + (`PREVIEW_PORT`) instead of moving. `--port 0` picks a free one and the + ready line names it. +- **A private, redacted log.** `/preview.log` (mode 0600, directory + 0700) has one line per API request (and, under `--static`, per page or + asset request); a URL's userinfo and the values of token-like + parameters are replaced with `REDACTED`. +- **No live backend.** Every request under the API prefix (`--api`, default + `/api/`) is answered from a fixture or with a 501. Anything outside the + prefix is the app's (SPA routes still serve), except a path the app's own + dev-server proxy forwards, which gets a 501 too (a WebSocket upgrade does + not). An app that calls an + absolute API URL on another origin still reaches that host, so point its + API base at the preview. `preflight` prints `mutations=fixtures-only` only + when the preview's own probe route, `/api/__gstack-preview`, answers at + every loopback state's origin without a redirect. A page that merely + carries the script, a redirect, or a custom `--api` prefix is + `mutations=unknown`, and the loop then drives no changed action. The Vite + plugin applies to the dev server only, so a build never carries the script. +- **A clean stop.** `stop` (or SIGTERM/SIGINT) closes the server, removes + `/preview.json` and exits 0. + +## Scenarios + +A state's URL names its scenario: `http://127.0.0.1:5300/settings?as=owner`. +A script injected first into every HTML page keeps `?as=` for the tab and +adds an `x-gstack-scenario` header to every same-origin `fetch` and +`XMLHttpRequest`, so the server's API calls see the scenario even though +their own URLs carry none. A request without the header falls back to its own +`?as=`, then to its Referer's `?as=`. + +## Fixtures + +One file per scenario, `/.json` (letters, digits, dot, +dash, underscore): + +```json +{ "version": 1, "routes": { + "GET /api/members": { "status": 200, "json": [{ "name": "Dana Whitfield", "role": "Owner" }] }, + "GET /api/members/:id": { "status": 200, "json": { "name": "Dana Whitfield" }, "delay_ms": 600 }, + "DELETE /api/members/:id": { "status": 409, "json": { "error": "The only owner cannot be removed." } } } } +``` + +A route key is a method and a path; `:name` matches one segment. `json` +sends JSON, `body` sends text, `headers` adds headers, `delay_ms` delays +the answer (for busy states). A declared error (the 409 above) is a fixture +like any other: it is how an error state is shown, and it never counts against +the run. + +### Failures + +Each failure is an RFC 9457 problem document (`application/problem+json`, +status 501, header `x-gstack-preview: `) with `code`, `detail` +naming the route and scenario, and `fix` naming the file to edit. Each is +also appended to `/unhandled.jsonl`, which the build receipt reads: +a state whose scenario hit one is `incomplete`, even when the page caught +the error and still rendered. + +| Code | Means | Fix | +|------|-------|-----| +| `PREVIEW_UNHANDLED` | the scenario file has no route for this method and path | add the route to that file, restart the preview and start a fresh run from preflight: every 501 the preview recorded during a run keeps its receipt incomplete | +| `PREVIEW_UNKNOWN_SCENARIO` | no `.json`, or it is not JSON | add or fix the file | +| `PREVIEW_NO_SCENARIO` | an API call with no scenario at all | open the page with `?as=` | +| `PREVIEW_LIVE_PROXY` | the path matches the app's `server.proxy`, a live backend | serve it under the API prefix from a fixture | + +Start failures print `PREVIEW: fail code= | fix: `: +`PREVIEW_NO_VITE` (no `node_modules/vite` at or above `--root`: install +it in the app, or use `--static`), `PREVIEW_CONFIG` (Vite could not load +the app's config), `PREVIEW_STATE` (the state directory is a symlink or +another user's), `PREVIEW_PORT`, `PREVIEW_HOST` and `PREVIEW_USAGE`. +Usage and host errors exit 3, the rest 4. + +To use the plugin from the app's own `vite.config`: +`import { gstackPreviewFixtures } from '/preview-fixtures.mjs'` and add +`gstackPreviewFixtures({ fixtures: '.gstack-preview/fixtures', stateDir: '' })` to +`plugins`. + +## Inventory + +`/design-review --build` lists the states it will check in an inventory +file, which `gstack-design-build` reads: + +```json +{ "version": 1, "within": "section.access", "fixtures": ".gstack-preview/fixtures", "touched": ["src/access.ts"], + "viewports": ["1440x900", "375x812"], + "states": [ + { "name": "owner", "url": "http://127.0.0.1:5300/settings?as=owner", "expect": ".rows .row" }, + { "name": "remove-confirm", "mode": "screenshot", "steps": "click Remove on the second row" } ] } +``` + +`within` is the section the lint measures. `expect` is a selector only +that state renders; the lint marks the state `STATE_MISMATCH` when it is +absent, and the receipt records whether it passed. `fixtures` and +`touched` (untracked files the loop created) are part of the tree identity +the receipt is bound to. `viewports` defaults to 1440x900 and 375x812. At +least one state must be a URL state; screenshot-only states are never counted +as linted. + +## Build receipt + +`gstack-design-build` (on gstack's `bin`) decides the run's outcome in +code: + +| Command | Does | +|---------|------| +| `preflight --inventory [--grant-remote ]` | browser first, then target authorization (loopback, or a host named in a grant), then that each URL answers; prints `PREFLIGHT: ok …` or the run's final `DESIGN_BUILD:` line (`NO_BROWSER`, `UNAUTHORIZED_TARGET`, `NO_PREVIEW`) | +| `admit ` | maps a refused design-review start to `DESIGN_BUILD: unrendered code=INSTALL` | +| `plan --inventory --run-dir [--waivers ]` | writes the lint's state file and prints the exact `LINT_CMD:` (carrying `--waivers` when given; a `waived` receipt needs it) and one `SHOT:` path per state and viewport | +| `verify-start --inventory --run-dir ` | records the tree identity right before the read-only final pass | +| `receipt --inventory --run-dir --rounds [--preview ] [--waivers ]` | writes `receipt.json` (0600) under `$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-build--/` and prints the one `DESIGN_BUILD:` line; it reads `--preview`, the state directory each running preview names, and the default per-port directory of any loopback origin where no preview answers; without `--preview`, a preview that keeps no record (the plugin without `stateDir`) makes the run `incomplete` (`PREVIEW_UNRECORDED`) | +| `check --inventory --receipt ` | reprints the line while the tree is unchanged, else `DESIGN_BUILD: stale code=TREE_CHANGED` | + +``` +DESIGN_BUILD: code= linted=/ shot=/ screenshot_only= open= waived= rounds= viewports= tree= receipt= [()] [| fix: ] +``` + +The verdict comes from the lint's JSON (`app.verdict`, `app.states[]`, +the findings), never its exit status. `clean` needs every URL state measured +at every planned viewport, every state screenshotted, no preview failure for +its scenario, evidence no older than `verify-start`, the same tree as then, +and nothing open. The tree identity hashes HEAD, every tracked change, the +`touched` files and the fixture directory. Exit 0 clean or waived, 1 open, +4 incomplete, unrendered or stale, 3 usage (including `--rounds` above 3). diff --git a/docs/skills.md b/docs/skills.md index 3d337ac9b..9fb9da8e7 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -365,6 +365,8 @@ This is my **designer who codes mode**. It runs an 80-item visual audit on your live site — in your Aside browser, so it sees exactly what a logged-in you sees — then enters a fix loop: for each design finding, it locates the source file, makes the minimal CSS/styling change, commits with `style(design): FINDING-NNN`, re-navigates to verify, and takes before/after screenshots. One commit per fix, fully bisectable. +**`--build` (opt-in, for UI you are building).** `/design-review --build ` skips the clean-tree check and never commits: it lists the states your change can show, serves them on a loopback preview with canned API answers ([preview recipe](howto-preview-a-frontend.md)), lints each one with `gstack-design-lint --scope app` at 1440 and 375, screenshots them, fixes what fails for up to three rounds, then runs one read-only final pass. `gstack-design-build` turns that evidence into one `DESIGN_BUILD:` line (clean, waived, open, incomplete or unrendered); a skipped render, a state it could not reach or an API call the preview could not answer is never clean. + The self-regulation heuristic is tuned for design work — CSS-only changes get a free pass (they are inherently safe and reversible), but changes to component JSX/TSX files count against the risk budget. Hard cap at 30 fixes. If the risk score exceeds 20%, it stops and asks. **Design detector.** When you have [impeccable](https://impeccable.style) installed, its engine runs first: on a URL the page's rendered DOM is dumped (linked styles inlined) and scanned; on a feature branch with no URL the changed frontend files are scanned (`.dart` files excepted: they count as frontend scope, but the engine reads web sources). Every mechanical finding arrives as a `FINDING-NNN` tagged with its rule id (`[nested-cards]`, `[low-contrast]`), and the report closes with `Detector: N → M`. gstack never runs impeccable's installer; when no engine is present it offers, once, to download the engine binary (checksum-pinned, logged in the egress ledger) and remembers the answer; without it the audit is unchanged. `gstack-config set design_detector off` disables the pre-pass. diff --git a/gstack/llms.txt b/gstack/llms.txt index a8b4671de..e714ae29c 100644 --- a/gstack/llms.txt +++ b/gstack/llms.txt @@ -24,7 +24,7 @@ Conventions: - [/design-consultation](design-consultation/SKILL.md): Design consultation: understands your product, researches the landscape, proposes a complete design system (aesthetic, typography, color, layout, spacing, motion), and generates font+color preview pages. - [/design-html](design-html/SKILL.md): Design finalization: generates production-quality Pretext-native HTML/CSS. - [/design-motion](design-motion/SKILL.md): Design motion: animate an approved design into a seamless MP4 and GIF loop. -- [/design-review](design-review/SKILL.md): Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. +- [/design-review](design-review/SKILL.md): Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them; --build checks UI while you build it. - [/design-shotgun](design-shotgun/SKILL.md): Design shotgun: generate multiple AI design variants, open a comparison board, collect structured feedback, and iterate. - [/deslop-shared-libs](deslop-shared-libs/SKILL.md): Find worthwhile shared-code extractions in recent work. - [/devex-review](devex-review/SKILL.md): Live developer experience audit. diff --git a/lib/design-build.ts b/lib/design-build.ts new file mode 100644 index 000000000..f1e107a00 --- /dev/null +++ b/lib/design-build.ts @@ -0,0 +1,357 @@ +/** + * The receipt behind `/design-review --build` (bin/gstack-design-build). The + * skill's loop edits and looks; this module decides what the run proved, so + * "never clean on skipped or partial coverage" lives in code, not prose: + * + * - `plan` turns the state inventory into the lint's --state-file, the exact + * lint command and one screenshot path per state and viewport. + * - `preflight` checks the browser first, then that every target is loopback + * (or granted by name), then that each URL answers, before any round. + * - `verify-start` records the measured tree identity right before the + * read-only final pass; `receipt` refuses evidence older than it or a tree + * that moved since, and reads the verdict from the lint's JSON, never its + * exit status. + * - `check` recomputes the tree identity so a later edit invalidates the + * receipt. + * + * Nothing here writes to the repository: no commit, stash, checkout or reset. + */ +import { createHash } from 'node:crypto'; +import { execFileSync } from 'node:child_process'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { pickEngine, type EngineChoice } from './aside-render'; +import { DEFAULT_VIEWPORTS, parseViewport, redactText, redactUrl, viewportLabel } from './design-lint/app-input'; + +export const MAX_ROUNDS = 3; +export const RECEIPT_VERSION = 1; +const DOC = 'docs/howto-preview-a-frontend.md'; +const PREVIEW_PROBE = '/api/__gstack-preview'; + +export class BuildUsageError extends Error { + constructor(readonly code: string, message: string, readonly fix: string) { + super(message); + } +} + +export interface InventoryState { name: string; url?: string; mode: 'url' | 'screenshot'; expect?: string; within?: string; scenario?: string; steps?: string } +export interface Inventory { version: 1; within: string; viewports: string[]; fixtures?: string; touched: string[]; states: InventoryState[] } + +export type Outcome = 'clean' | 'waived' | 'open' | 'incomplete' | 'unrendered' | 'stale'; + +/** Every code the build line can carry, with the one fix the loop is allowed to try. */ +export const BUILD_FIXES: Record = { + INSTALL: "run install.sh --for design-review from the lane's repo, then launch with its GSTACK_LAUNCH line", + NO_BROWSER: 'gstack-browser-ensure, then rerun /design-review --build', + NO_PREVIEW: `start the preview (${DOC}), then rerun`, + UNAUTHORIZED_TARGET: 'serve the app on 127.0.0.1 with the preview template, or rerun with --grant-remote written by the person who owns it', + TREE_CHANGED: 'the tree moved after the final pass began; rerun the final verification pass only', + STALE_EVIDENCE: 'a lint result or screenshot predates the final pass; rerun the final verification pass only', + LINT_MISSING: 'run the LINT_CMD line from plan, then rerun receipt', + VIEWPORTS: 'run the LINT_CMD line from plan unchanged; it measures every planned viewport', + NOT_LINTED: 'a URL state is missing from the lint result; run the LINT_CMD line from plan unchanged', + PREVIEW_UNHANDLED: `add the named route to the scenario's fixture file (${DOC}#fixtures), restart the preview, then start a fresh run from preflight`, + PREVIEW_UNKNOWN_SCENARIO: `add or fix the scenario's fixture file (${DOC}#fixtures), restart the preview, then start a fresh run from preflight`, + PREVIEW_NO_SCENARIO: 'give the state URL an ?as= query, restart the preview, then start a fresh run from preflight', + NOT_SHOT: 'take the SHOT lines from plan for the named states, then rerun receipt', + LINT_VERDICT: 'the lint result has no verdict; run the LINT_CMD line from plan unchanged', + INVENTORY_CHANGED: 'the inventory changed after verify-start; rerun the final verification pass from plan', + PREVIEW_UNRECORDED: 'start the preview template with --state (or give the plugin a stateDir), then start a fresh run from preflight', + PREVIEW_LIVE_PROXY: `serve the route under the API prefix from a fixture (${DOC}#fixtures), restart the preview, then start a fresh run from preflight`, +}; + +const NAME = /^[A-Za-z0-9._-]{1,64}$/; +const isLoopbackHost = (h: string): boolean => h === 'localhost' || h === '[::1]' || /^127\.\d+\.\d+\.\d+$/.test(h); +const relSafe = (p: unknown): boolean => typeof p === 'string' && p.length > 0 && !path.isAbsolute(p) && !p.split(/[\\/]/).includes('..'); + +export function parseInventory(text: string): Inventory { + const bad = (m: string): never => { throw new BuildUsageError('BAD_INVENTORY', m, `fix the inventory file; its format is in ${DOC}#inventory`); }; + let raw: Record; + try { raw = JSON.parse(text); } catch (e) { return bad(`the inventory is not JSON (${(e as Error).message})`); } + if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return bad('the inventory is not a JSON object'); + const unknown = Object.keys(raw).filter((k) => !['version', 'within', 'viewports', 'fixtures', 'touched', 'states'].includes(k)); + if (unknown.length) bad(`unknown inventory key ${unknown[0]}`); + if (raw.version !== 1) bad('inventory version must be 1'); + if (typeof raw.within !== 'string' || !raw.within.trim()) bad('the inventory needs within: the section selector'); + const viewports = raw.viewports === undefined ? DEFAULT_VIEWPORTS.map(viewportLabel) : raw.viewports; + if (!Array.isArray(viewports) || !viewports.length) return bad('viewports must be a non-empty list like ["1440x900","375x812"]'); + for (const v of viewports) parseViewport(String(v)); + const touched = raw.touched ?? []; + if (!Array.isArray(touched) || !touched.every(relSafe)) bad('touched must list repo-relative paths'); + if (raw.fixtures !== undefined && !relSafe(raw.fixtures)) bad('fixtures must be a repo-relative directory'); + if (!Array.isArray(raw.states) || !raw.states.length) return bad('the inventory lists no states'); + const seen = new Set(); + const states = (raw.states as Array>).map((s, i): InventoryState => { + if (!s || typeof s !== 'object') bad(`state ${i + 1} is not an object`); + const extra = Object.keys(s).filter((k) => !['name', 'url', 'mode', 'expect', 'within', 'scenario', 'steps'].includes(k)); + if (extra.length) bad(`state ${i + 1} has unknown key ${extra[0]}`); + for (const k of ['name', 'expect', 'within', 'scenario', 'url', 'steps', 'mode']) if (s[k] !== undefined && typeof s[k] !== 'string') bad(`state ${i + 1} ${k} must be a string`); + const name = s.name as string; + if (!name || !NAME.test(name)) bad(`state ${i + 1} needs a name of letters, digits, dot, dash or underscore`); + if (seen.has(name)) bad(`state ${name} is listed twice`); + seen.add(name); + const mode = (s.mode ?? 'url') as string; + if (mode !== 'url' && mode !== 'screenshot') bad(`state ${name} mode must be url or screenshot`); + if (mode === 'url' && !/^https?:\/\//.test((s.url as string) ?? '')) bad(`state ${name} needs an http(s) url`); + if (mode === 'screenshot' && !s.steps) bad(`screenshot-only state ${name} needs steps: how to reach it by hand`); + const out: InventoryState = { name, mode: mode as InventoryState['mode'] }; + for (const k of ['url', 'expect', 'within', 'scenario', 'steps'] as const) if (s[k] !== undefined) out[k] = s[k] as string; + return out; + }); + if (!states.some((s) => s.mode === 'url')) bad('the inventory needs at least one url state: screenshot-only states are never linted, so a run of only those proves nothing'); + return { version: 1, within: raw.within as string, viewports: viewports.map(String), ...(raw.fixtures ? { fixtures: raw.fixtures as string } : {}), touched: touched as string[], states }; +} + +/** The scenario a state's API calls carry: its own `scenario`, else its URL's ?as=, else none (''). */ +export function scenarioOf(s: InventoryState): string { + if (s.scenario !== undefined) return s.scenario; + try { return new URL(s.url ?? '').searchParams.get('as') ?? ''; } catch { return ''; } +} + +export const shotPath = (runDir: string, state: string, viewport: string): string => path.join(runDir, 'shots', `${state}-${viewport}.png`); + +const quote = (s: string): string => `'${s.replace(/'/g, "'\\''")}'`; + +/** The lint --state-file, the exact lint command and every screenshot path, written once per run. */ +export function plan(inv: Inventory, runDir: string, waivers?: string): string[] { + fs.mkdirSync(path.join(runDir, 'shots'), { recursive: true, mode: 0o700 }); + const urlStates = inv.states.filter((s) => s.mode === 'url'); + const stateFile = path.join(runDir, 'states.json'); + const lintStates = urlStates.map((s) => ({ name: s.name, url: s.url, ...(s.expect ? { expect: s.expect } : {}), ...(s.within ? { within: s.within } : {}) })); + fs.writeFileSync(stateFile, JSON.stringify({ version: 1, states: lintStates }, null, 2) + '\n', { mode: 0o600 }); + const lint = [quote(path.resolve(import.meta.dir, '..', 'bin', 'gstack-design-lint')), '--scope', 'app', '--state-file', quote(stateFile), '--within', quote(inv.within), ...inv.viewports.flatMap((v) => ['--viewport', v]), ...(waivers ? ['--waivers', quote(waivers)] : []), '--json', '>', quote(path.join(runDir, 'lint.json'))]; + return [ + `DESIGN_BUILD_PLAN: states=${inv.states.length} url=${urlStates.length} screenshot_only=${inv.states.length - urlStates.length} viewports=${inv.viewports.join(',')} run=${runDir}`, + ...(urlStates.length ? [`LINT_CMD: ${lint.join(' ')}`] : []), + ...inv.states.flatMap((s) => inv.viewports.map((v) => `SHOT: ${s.name} ${v} ${s.mode === 'url' ? redactUrl(s.url!) : 'screenshot-only: ' + s.steps} -> ${shotPath(runDir, s.name, v)}`)), + ]; +} + +const git = (repo: string, args: string[]): string => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, timeout: 60_000 }); + +function filesUnder(repo: string, rel: string): string[] { + const abs = path.join(repo, rel); + if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return [rel]; + return fs.readdirSync(abs, { recursive: true, withFileTypes: true }) + .filter((d) => d.isFile()) + .map((d) => path.relative(repo, path.join(d.parentPath, d.name)).split(path.sep).join('/')); +} + +/** The measured dirty-tree identity: HEAD, every tracked diff, the untracked files the loop touched and the fixture content. */ +export function treeIdentity(repo: string, inv: Pick): string { + const h = createHash('sha256'); + h.update('head\0' + git(repo, ['rev-parse', 'HEAD']).trim() + '\0'); + h.update('diff\0' + git(repo, ['diff', 'HEAD', '--binary', '--no-ext-diff', '--no-textconv']) + '\0'); + const files = [...new Set([...inv.touched.flatMap((t) => filesUnder(repo, t)), ...(inv.fixtures ? filesUnder(repo, inv.fixtures) : [])])].sort(); + for (const rel of files) { + const abs = path.join(repo, rel); + h.update('file\0' + rel + '\0'); + h.update(fs.existsSync(abs) && fs.statSync(abs).isFile() ? fs.readFileSync(abs) : Buffer.from('\0missing')); + h.update('\0'); + } + return h.digest('hex'); +} + +/** + * Right before the read-only final pass: record the tree it measures. The + * pass began at verify.json's own mtime, so evidence is compared on the + * filesystem's clock, not the process's. + */ +const inventoryHash = (inv: Inventory): string => createHash('sha256').update(JSON.stringify(inv)).digest('hex'); + +export function verifyStart(repo: string, inv: Inventory, runDir: string): string { + const tree = treeIdentity(repo, inv); + fs.mkdirSync(runDir, { recursive: true, mode: 0o700 }); + fs.writeFileSync(path.join(runDir, 'verify.json'), JSON.stringify({ tree, inventory: inventoryHash(inv) }) + '\n', { mode: 0o600 }); + return `VERIFY: tree=${tree.slice(0, 12)} run=${runDir}`; +} + +/** Each loopback state origin where a preview answered the probe, with the state directory it names; state is null when it keeps no record. */ +export async function servedStates(inv: Inventory): Promise> { + const origins = [...new Set(inv.states.filter((s) => s.url && isLoopbackHost(new URL(s.url).hostname)).map((s) => new URL(s.url!).origin))]; + const out: Array<{ origin: string; state: string | null }> = []; + for (const origin of origins) { + try { + const res = await fetch(new URL(PREVIEW_PROBE, origin), { signal: AbortSignal.timeout(10_000), redirect: 'manual' }); + if (res.status === 204 && res.headers.get('x-gstack-preview') === 'ready') out.push({ origin, state: decodeURIComponent(res.headers.get('x-gstack-preview-state') ?? '') || null }); + } catch {} + } + return out; +} + +export interface PreflightDeps { engine?: () => EngineChoice; reach?: (url: string) => Promise; preview?: (url: string) => Promise } + +/** The preview template answers its probe route with 204 and x-gstack-preview: ready; a redirect, a marker in the HTML or any other answer is not the preview. */ +async function previewAnswers(url: string): Promise { + try { + const res = await fetch(new URL(PREVIEW_PROBE, url), { signal: AbortSignal.timeout(10_000), redirect: 'manual' }); + return res.status === 204 && res.headers.get('x-gstack-preview') === 'ready'; + } catch { + return false; + } +} + +async function reachable(url: string): Promise { + try { + const res = await fetch(url, { signal: AbortSignal.timeout(10_000), redirect: 'manual' }); + return res.status >= 500 ? `answered ${res.status}` : null; + } catch (e) { + return (e as Error).message; + } +} + +/** + * Before any round: the browser engine first, then target authorization (a + * non-loopback target needs a grant naming its host, else the run stops + * incomplete before any page opens), then each URL state answers. + */ +export async function preflight(inv: Inventory, grants: string[], deps: PreflightDeps = {}): Promise<{ lines: string[]; exit: number }> { + const engine = (deps.engine ?? (() => pickEngine()))(); + if (!engine.engine) return { lines: [buildLine({ outcome: 'unrendered', code: 'NO_BROWSER', detail: redactText(engine.error) })], exit: 4 }; + const withUrl = inv.states.filter((s) => s.url); + const remote = withUrl.filter((s) => { const h = new URL(s.url!).hostname; return !isLoopbackHost(h) && !grants.includes(h); }); + if (remote.length) return { lines: [buildLine({ outcome: 'incomplete', code: 'UNAUTHORIZED_TARGET', detail: `${remote.map((s) => `${s.name} at ${redactUrl(s.url!)}`).join(', ')} is not on loopback and has no grant; no page was opened and no action ran` })], exit: 4 }; + const down: string[] = []; + for (const s of withUrl) { + const err = await (deps.reach ?? reachable)(s.url!); + if (err) down.push(`${s.name} (${redactUrl(s.url!)}: ${redactText(err)})`); + } + if (down.length) return { lines: [buildLine({ outcome: 'unrendered', code: 'NO_PREVIEW', detail: `no answer from ${down.join(', ')}` })], exit: 4 }; + const granted = withUrl.some((s) => !isLoopbackHost(new URL(s.url!).hostname)); + const local = withUrl.filter((s) => isLoopbackHost(new URL(s.url!).hostname)); + const previewed = (await Promise.all(local.map((s) => (deps.preview ?? previewAnswers)(s.url!)))).every(Boolean); + return { lines: [`PREFLIGHT: ok engine=${engine.engine} states=${inv.states.length} targets=${granted ? 'loopback+granted' : 'loopback'} mutations=${!previewed ? 'unknown' : granted ? 'fixtures+granted' : 'fixtures-only'}`], exit: 0 }; +} + +/** Map a gstack-skill-start transcript: a refused start is the build's INSTALL outcome. */ +export function admit(startOutput: string): { lines: string[]; exit: number } { + if (!/^GSTACK_RESULT: skill=design-review status=refused\b/m.test(startOutput)) return { lines: ['ADMIT: ok'], exit: 0 }; + const row = /^INSTALL: .*$/m.exec(startOutput)?.[0] ?? 'the preamble refused this workflow'; + return { lines: [buildLine({ outcome: 'unrendered', code: 'INSTALL', detail: redactText(row) })], exit: 4 }; +} + +export interface Counts { planned: number; url: number; linted: number; shot: number; screenshotOnly: number; open: number; waived: number } +export interface LineInput { outcome: Outcome; code: string; detail?: string; counts?: Counts; rounds?: number; viewports?: string[]; tree?: string; receipt?: string } + +/** The one DESIGN_BUILD line a READY pastes; every outcome and code prints through here. */ +export function buildLine(i: LineInput): string { + const c = i.counts; + const parts = [`DESIGN_BUILD: ${i.outcome}`, `code=${i.code}`]; + if (c) parts.push(`linted=${c.linted}/${c.url}`, `shot=${c.shot}/${c.planned}`, `screenshot_only=${c.screenshotOnly}`, `open=${c.open}`, `waived=${c.waived}`); + if (i.rounds !== undefined) parts.push(`rounds=${i.rounds}`); + if (i.viewports) parts.push(`viewports=${i.viewports.join(',')}`); + if (i.tree) parts.push(`tree=${i.tree.slice(0, 12)}`); + if (i.receipt) parts.push(`receipt=${i.receipt}`); + const fix = BUILD_FIXES[i.code]; + return parts.join(' ') + (i.detail ? ` (${i.detail.replace(/\s+/g, ' ').replace(/ \| fix: /g, ' / fix: ')})` : '') + (fix ? ` | fix: ${fix}` : ''); +} + +export interface UnhandledHit { scenario: string; method: string; path: string; code: string } + +/** The preview template's record of API calls it could not answer (unhandled.jsonl in its state directory). */ +export function readUnhandled(previewDir: string): UnhandledHit[] { + const file = path.join(previewDir, 'unhandled.jsonl'); + if (!fs.existsSync(file)) return []; + return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l) as UnhandledHit); +} + +interface LintFinding { rule: string; tier: string; grade: string; evidence?: string; waiver?: string; app?: { state: string; viewport: string; locator: string; measured: number; threshold: number } } +interface LintCoverage { name: string; viewport: string; status: string; code: string } +interface LintJson { findings?: LintFinding[]; app?: { verdict?: string; code?: string; codes?: string[]; viewports?: string[]; states?: LintCoverage[] } } + +export interface ReceiptInput { repo: string; inv: Inventory; runDir: string; rounds: number; previewDir?: string; served?: Array<{ origin: string; state: string | null }>; waivers?: string; outRoot: string; now?: () => Date } + +const mtime = (f: string): number => fs.statSync(f).mtimeMs; + +function readLint(runDir: string, verifyAt: number, add: (code: string, detail: string) => void): LintJson | null { + const file = path.join(runDir, 'lint.json'); + if (!fs.existsSync(file)) { add('LINT_MISSING', 'no lint.json'); return null; } + if (mtime(file) < verifyAt) add('STALE_EVIDENCE', 'lint.json predates the final pass'); + try { return JSON.parse(fs.readFileSync(file, 'utf8')) as LintJson; } catch { add('LINT_MISSING', 'lint.json is not JSON'); return null; } +} + +/** Decide the outcome from the evidence on disk, write the versioned receipt and return its one line. */ +export function receipt(r: ReceiptInput): { line: string; file: string; exit: number; receipt: Record & { states: Array>; open: unknown[]; waived: unknown[] } } { + if (!Number.isInteger(r.rounds) || r.rounds < 0 || r.rounds > MAX_ROUNDS) throw new BuildUsageError('ROUNDS', `--rounds ${r.rounds} is outside 0 to ${MAX_ROUNDS}`, `the loop stops editing after round ${MAX_ROUNDS}; report the open list instead of a fourth round`); + const verifyFile = path.join(r.runDir, 'verify.json'); + if (!fs.existsSync(verifyFile)) throw new BuildUsageError('NO_VERIFY', `${verifyFile} is missing`, 'run verify-start right before the final verification pass'); + const verify = { ...(JSON.parse(fs.readFileSync(verifyFile, 'utf8')) as { tree: string; inventory?: string }), at: mtime(verifyFile) }; + const tree = treeIdentity(r.repo, r.inv); + const codes: string[] = []; + const details: string[] = []; + const add = (code: string, detail: string): void => { if (!codes.includes(code)) codes.push(code); details.push(detail); }; + if (tree !== verify.tree) add('TREE_CHANGED', 'the tree changed after verify-start'); + if (verify.inventory !== inventoryHash(r.inv)) add('INVENTORY_CHANGED', 'the inventory is not the one verify-start recorded'); + + const urlStates = r.inv.states.filter((s) => s.mode === 'url'); + const lint = urlStates.length ? readLint(r.runDir, verify.at, add) : null; + const verdict = lint?.app?.verdict; + if (lint && !['clean', 'open', 'incomplete'].includes(verdict ?? '')) add('LINT_VERDICT', 'lint.json carries no app verdict'); + if (lint && (lint.app?.viewports ?? []).join(',') !== r.inv.viewports.join(',')) add('VIEWPORTS', `linted ${(lint.app?.viewports ?? []).join(',') || 'none'}, planned ${r.inv.viewports.join(',')}`); + + const served = r.served ?? []; + if (!r.previewDir && served.some((s) => s.state === null)) add('PREVIEW_UNRECORDED', 'a preview answered at a state origin but keeps no record of unanswered calls'); + const answered = new Set(served.map((s) => s.origin)); + const unanswered = urlStates.map((s) => new URL(s.url!)).filter((u) => isLoopbackHost(u.hostname) && !answered.has(u.origin)); + const previewDirs = [...new Set([...(r.previewDir ? [r.previewDir] : []), ...served.flatMap((s) => (s.state ? [s.state] : [])), ...unanswered.map((u) => path.join(os.tmpdir(), `gstack-preview-${u.port || 80}`))])]; + const hits = previewDirs.flatMap(readUnhandled); + const states = r.inv.states.map((s) => { + const cov = (lint?.app?.states ?? []).filter((c) => c.name === s.name); + const linted = s.mode === 'url' && r.inv.viewports.every((v) => cov.some((c) => c.viewport === v && c.status === 'measured')); + const shots = r.inv.viewports.map((v) => shotPath(r.runDir, s.name, v)).filter((f) => fs.existsSync(f)); + const scenario = scenarioOf(s); + const unhandled = s.mode === 'url' ? hits.filter((h) => h.scenario === scenario || !h.scenario) : []; + if (s.mode === 'url' && lint && !linted) { + const bad = cov.find((c) => c.status !== 'measured'); + add(bad?.code ?? 'NOT_LINTED', `${s.name} not linted at every viewport${bad ? ` (${bad.code})` : ''}`); + } + if (shots.length < r.inv.viewports.length) add('NOT_SHOT', `${s.name} has ${shots.length}/${r.inv.viewports.length} screenshots`); + if (shots.some((f) => mtime(f) < verify.at)) add('STALE_EVIDENCE', `a screenshot of ${s.name} predates the final pass`); + for (const h of unhandled) add(h.code, `${s.name}: ${h.method} ${redactText(h.path)} (scenario ${h.scenario || 'none'})`); + const expectPassed = s.mode === 'url' && lint ? cov.length > 0 && !cov.some((c) => c.code === 'STATE_MISMATCH') && cov.some((c) => c.status === 'measured') : null; + return { + name: s.name, mode: s.mode, ...(s.url ? { url: redactUrl(s.url) } : {}), ...(s.steps ? { steps: s.steps } : {}), scenario, linted, + viewports: cov.map((c) => ({ viewport: c.viewport, status: c.status, code: c.code })), + expect: s.expect ? { selector: s.expect, passed: expectPassed } : null, + shots: shots.map((f) => path.relative(r.runDir, f)), unhandled, + }; + }); + const appFindings = (lint?.findings ?? []).filter((f) => f.app); + const open = appFindings.filter((f) => f.grade !== 'waived'); + const waived = appFindings.filter((f) => f.grade === 'waived'); + const counts: Counts = { planned: states.length, url: urlStates.length, linted: states.filter((s) => s.linted).length, shot: states.filter((s) => s.shots.length === r.inv.viewports.length).length, screenshotOnly: states.length - urlStates.length, open: open.length, waived: waived.length }; + + let outcome: Outcome; + if (codes.length) outcome = 'incomplete'; + else if (urlStates.length && verdict === 'open') outcome = 'open'; + else if (urlStates.length && verdict !== 'clean') outcome = 'incomplete'; + else outcome = waived.length ? 'waived' : 'clean'; + const code = outcome === 'incomplete' ? (codes[0] ?? 'LINT_VERDICT') : outcome === 'open' ? 'OPEN' : 'OK'; + + const head = git(r.repo, ['rev-parse', 'HEAD']).trim(); + const dir = path.join(r.outRoot, `design-build-${head.slice(0, 12)}-${tree.slice(0, 12)}`); + fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); + const file = path.join(dir, 'receipt.json'); + const waivers = r.waivers ? { path: r.waivers, sha256: createHash('sha256').update(fs.readFileSync(r.waivers)).digest('hex') } : null; + const line = buildLine({ outcome, code, detail: outcome === 'incomplete' ? details.slice(0, 6).join('; ') : undefined, counts, rounds: r.rounds, viewports: r.inv.viewports, tree, receipt: file }); + const rec = { + version: RECEIPT_VERSION, outcome, code, codes, head, tree, measured_tree: verify.tree, inventory: inventoryHash(r.inv), rounds: r.rounds, viewports: r.inv.viewports, within: r.inv.within, + counts, states, lint: lint ? { verdict: verdict ?? null, code: lint.app?.code ?? null, codes: lint.app?.codes ?? [] } : null, + open: open.map((f) => ({ rule: f.rule, evidence: redactText(f.evidence ?? ''), ...f.app })), + waived: waived.map((f) => ({ rule: f.rule, reason: f.waiver ?? '', ...f.app })), + waivers, touched: r.inv.touched, fixtures: r.inv.fixtures ?? null, created_at: (r.now ?? (() => new Date()))().toISOString(), line, + }; + fs.writeFileSync(file, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600 }); + return { line, file, exit: outcome === 'clean' || outcome === 'waived' ? 0 : outcome === 'open' ? 1 : 4, receipt: rec }; +} + +/** A receipt stays good only while the tree it measured is the tree on disk. */ +export function check(repo: string, inv: Inventory, receiptFile: string): { line: string; exit: number } { + const rec = JSON.parse(fs.readFileSync(receiptFile, 'utf8')) as { tree: string; inventory: string; line: string; outcome: Outcome; version: number }; + if (rec.version !== RECEIPT_VERSION) return { line: buildLine({ outcome: 'stale', code: 'TREE_CHANGED', detail: `receipt version ${rec.version} is not ${RECEIPT_VERSION}` }), exit: 4 }; + const now = treeIdentity(repo, inv); + if (rec.inventory !== inventoryHash(inv)) return { line: buildLine({ outcome: 'stale', code: 'INVENTORY_CHANGED', detail: 'the inventory is not the one the receipt measured', receipt: receiptFile }), exit: 4 }; + if (now !== rec.tree) return { line: buildLine({ outcome: 'stale', code: 'TREE_CHANGED', detail: `measured ${rec.tree.slice(0, 12)}, tree is now ${now.slice(0, 12)}`, tree: now, receipt: receiptFile }), exit: 4 }; + return { line: rec.line, exit: rec.outcome === 'clean' || rec.outcome === 'waived' ? 0 : rec.outcome === 'open' ? 1 : 4 }; +} diff --git a/lib/design-lint/app-input.ts b/lib/design-lint/app-input.ts index 04c534029..c8822a66e 100644 --- a/lib/design-lint/app-input.ts +++ b/lib/design-lint/app-input.ts @@ -37,10 +37,25 @@ function redactParams(text: string): string | null { return new URLSearchParams([...params.entries()].map(([k, v]) => [k, SECRET_PARAM.test(k) ? 'REDACTED' : v])).toString(); } +const USERINFO = /([a-z][a-z0-9+.-]*:\/\/)[^\s/?#]*@/gi; +const PARAM = /([?&#;])([^=&#?;\s]+)=([^&#\s]*)/g; + +/** + * Redaction by pattern, for text that is not a parseable URL: userinfo after + * any scheme is dropped, and the value of every query or fragment parameter + * with a secret-looking name becomes REDACTED. A value ends only at &, # or + * whitespace, so punctuation inside it (a parenthesis, a colon) never lets its + * tail through. + */ +function redactPattern(s: string): string { + const name = (key: string): string => { try { return decodeURIComponent(key); } catch { return key; } }; + return s.replace(USERINFO, '$1').replace(PARAM, (all, sep: string, key: string) => (SECRET_PARAM.test(name(key)) ? `${sep}${key}=REDACTED` : all)); +} + /** A URL fit to print: userinfo dropped, secret-looking query and fragment parameter values replaced with REDACTED. Navigation always uses the real URL. */ export function redactUrl(raw: string): string { let u: URL; - try { u = new URL(raw); } catch { return raw.replace(/\/\/[^/@\s]*@/, '//'); } + try { u = new URL(raw); } catch { return redactPattern(raw); } u.username = ''; u.password = ''; const search = redactParams(u.search.slice(1)); @@ -50,8 +65,8 @@ export function redactUrl(raw: string): string { return u.toString(); } -/** Every http(s) URL inside free text (an error message, a stack) redacted. */ -export const redactText = (s: string): string => s.replace(/https?:\/\/[^\s"'<>)]+/g, (u) => redactUrl(u)); +/** Free text (an error message, a stack) with every URL's userinfo and secret-looking parameter values redacted. */ +export const redactText = redactPattern; /** A state's name when only its URL is given: its path and query, redacted. */ export function stateNameOf(url: string): string { diff --git a/test/design-build-e2e.test.ts b/test/design-build-e2e.test.ts new file mode 100644 index 000000000..144cf7423 --- /dev/null +++ b/test/design-build-e2e.test.ts @@ -0,0 +1,72 @@ +/** + * The build receipt end to end in a real browser (browser tier): the preview + * template serves a page whose rows come from the fixture API, the real + * gstack-design-lint measures two scenarios through the exact command + * gstack-design-build plan prints, and the receipt reads the lint's JSON and + * the preview's record. One scenario's page swallows a 501 and still renders + * its section clean; the receipt must still call that state incomplete. + * Runs whenever a browser is available, except in CI, where a missing browser + * fails. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import { execFileSync, spawnSync } from 'node:child_process'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import { browserAvailable, NO_BROWSER_REASON } from './helpers/browser-available'; +import { runPreview, startPreview, type Preview } from './helpers/preview-template'; + +const ROOT = path.resolve(import.meta.dir, '..'); +const hasBrowser = browserAvailable(); +if (!hasBrowser && process.env.CI) throw new Error('design-build-e2e: CI needs a browser for the build receipt tier: ' + NO_BROWSER_REASON); +const tmp: string[] = []; +const live: Preview[] = []; +afterAll(() => { for (const p of live) p.proc.kill(); for (const d of tmp) fs.rmSync(d, { recursive: true, force: true }); }); +const tmpDir = (p: string): string => { const d = fs.mkdtempSync(path.join(os.tmpdir(), p)); tmp.push(d); return d; }; +const env = { ...process.env, PATH: path.join(ROOT, 'bin') + path.delimiter + process.env.PATH }; + +describe.skipIf(!hasBrowser)('build receipt through the real lint (T26, T2, T3, T12, T36)', () => { + test('a caught 501 behind a clean, measured section is still incomplete; the other scenario is linted with its expect recorded', async () => { + const repo = tmpDir('design-build-e2e-'); + execFileSync('git', ['-C', repo, 'init', '-q'], { timeout: 30_000 }); + fs.cpSync(path.join(ROOT, 'test', 'fixtures', 'ui-spacing', 'preview'), path.join(repo, 'preview'), { recursive: true }); + execFileSync('git', ['-C', repo, 'add', '-A'], { timeout: 30_000 }); + execFileSync('git', ['-C', repo, '-c', 'user.name=gstack test', '-c', 'user.email=test@example.com', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'seed'], { timeout: 30_000 }); + const state = tmpDir('design-build-e2e-pv-'); + const p = await startPreview(['--static', '--root', path.join(repo, 'preview'), '--fixtures', path.join(repo, 'preview', 'fixtures'), '--port', '0', '--state', state]); + live.push(p); + const work = tmpDir('design-build-e2e-run-'); + const inv = path.join(work, 'inventory.json'); + fs.writeFileSync(inv, JSON.stringify({ version: 1, within: 'section.access', fixtures: 'preview/fixtures', states: [ + { name: 'owner', url: p.url + '?as=owner', expect: '.rows .row' }, + { name: 'lastowner', url: p.url + '?as=lastowner', expect: '.rows .row' }, + ] })); + const runDir = path.join(work, 'run'); + const sh = (args: string[]) => spawnSync(path.join(ROOT, 'bin', 'gstack-design-build'), args, { cwd: repo, encoding: 'utf8', env, timeout: 60_000 }); + expect(sh(['preflight', '--inventory', inv]).stdout).toMatch(/^PREFLIGHT: ok engine=\S+ states=2 targets=loopback mutations=fixtures-only$/m); + const planned = sh(['plan', '--inventory', inv, '--run-dir', runDir]).stdout; + expect(sh(['verify-start', '--inventory', inv, '--run-dir', runDir]).status).toBe(0); + const lintCmd = /^LINT_CMD: (.*)$/m.exec(planned)![1]!; + const lanePath = (process.env.PATH ?? '').split(path.delimiter).filter((d) => !fs.existsSync(path.join(d, 'gstack-design-lint'))).join(path.delimiter); + spawnSync('bash', ['-c', lintCmd], { cwd: repo, env: { ...process.env, PATH: lanePath }, timeout: 180_000 }); + const lint = JSON.parse(fs.readFileSync(path.join(runDir, 'lint.json'), 'utf8')); + expect(lint.app.verdict).toBe('clean'); + expect(lint.app.states.map((s: { name: string; viewport: string; status: string }) => [s.name, s.viewport, s.status])).toEqual([ + ['owner', '1440x900', 'measured'], ['owner', '375x812', 'measured'], ['lastowner', '1440x900', 'measured'], ['lastowner', '375x812', 'measured'], + ]); + const log = fs.readFileSync(path.join(state, 'preview.log'), 'utf8'); + expect(log).toContain('GET /api/members 200 scenario=lastowner'); + expect(log).toContain('GET /api/audit 501 PREVIEW_UNHANDLED scenario=lastowner'); + for (const m of planned.matchAll(/^SHOT: \S+ \S+ \S+ -> (\S+)$/gm)) fs.writeFileSync(m[1]!, 'png'); + const r = sh(['receipt', '--inventory', inv, '--run-dir', runDir, '--rounds', '1', '--preview', state, '--out-root', path.join(work, 'out')]); + expect(r.status).toBe(4); + expect(r.stdout).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED linted=2/2 shot=2/2'); + expect(r.stdout).toContain('lastowner: GET /api/audit (scenario lastowner)'); + const rec = JSON.parse(fs.readFileSync(/receipt=(\S+)/.exec(r.stdout)![1]!, 'utf8')); + expect(rec.states.map((s: { name: string; linted: boolean; expect: unknown; unhandled: unknown[] }) => [s.name, s.linted, s.expect, s.unhandled.length])).toEqual([ + ['owner', true, { selector: '.rows .row', passed: true }, 0], + ['lastowner', true, { selector: '.rows .row', passed: true }, 1], + ]); + expect(runPreview(['stop', '--state', state]).code).toBe(0); + }, 240_000); +}); diff --git a/test/design-build.test.ts b/test/design-build.test.ts new file mode 100644 index 000000000..9035c7124 --- /dev/null +++ b/test/design-build.test.ts @@ -0,0 +1,593 @@ +/** + * The /design-review --build receipt (bin/gstack-design-build, + * lib/design-build.ts) without a browser: the outcome is decided in code from + * the lint's JSON, the screenshots on disk, the preview's record of requests + * it could not answer and the measured tree identity. Skipped renders, + * partial coverage, screenshot-only states, a 501 the page swallowed, stale + * evidence and a later edit can never print clean. Also: preflight order and + * target authorization, the INSTALL mapping of a refused skill start, and a + * dirty tree left exactly as it was. + */ +import { afterAll, describe, expect, test } from 'bun:test'; +import { execFileSync, spawnSync } from 'node:child_process'; +import { createHash } from 'node:crypto'; +import * as fs from 'node:fs'; +import * as os from 'node:os'; +import * as path from 'node:path'; +import * as vm from 'node:vm'; +import { admit, buildLine, check, parseInventory, plan, preflight, receipt, servedStates, treeIdentity, verifyStart, type Inventory } from '../lib/design-build'; +import { redactText } from '../lib/design-lint/app-input'; +import { PREVIEW_TEMPLATE, runPreview, startPreview, type Preview } from './helpers/preview-template'; + +const ROOT = path.resolve(import.meta.dir, '..'); +const BIN = path.join(ROOT, 'bin', 'gstack-design-build'); +const VPS = ['1440x900', '375x812']; +const tmp: string[] = []; +const live: Preview[] = []; +afterAll(() => { for (const p of live) p.proc.kill(); for (const d of tmp) fs.rmSync(d, { recursive: true, force: true }); }); +const tmpDir = (p = 'design-build-'): string => { const d = fs.mkdtempSync(path.join(os.tmpdir(), p)); tmp.push(d); return d; }; + +const git = (repo: string, ...args: string[]): string => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8', timeout: 30_000 }); + +/** A standalone repo outside any checkout, with one commit, a dirty tracked file and an untracked component. */ +function fixtureRepo(): string { + const repo = tmpDir('design-build-repo-'); + git(repo, 'init', '-q'); + fs.mkdirSync(path.join(repo, 'src')); + fs.mkdirSync(path.join(repo, 'fixtures')); + fs.writeFileSync(path.join(repo, 'src', 'app.css'), '.row { padding: 4px; }\n'); + fs.writeFileSync(path.join(repo, 'fixtures', 'owner.json'), '{"version":1,"routes":{}}\n'); + git(repo, 'add', '-A'); + git(repo, '-c', 'user.name=gstack test', '-c', 'user.email=test@example.com', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'seed'); + fs.writeFileSync(path.join(repo, 'src', 'app.css'), '.row { padding: 12px; }\n'); + fs.writeFileSync(path.join(repo, 'src', 'access.ts'), 'export const rows = 3;\n'); + return repo; +} + +const URL_OWNER = 'http://127.0.0.1:5300/settings?as=owner'; +const URL_LAST = 'http://127.0.0.1:5300/settings?as=lastowner&token=RECEIPTSENTINEL'; +function inventory(over: Partial = {}): Inventory { + return parseInventory(JSON.stringify({ + version: 1, within: 'section.access', fixtures: 'fixtures', touched: ['src/access.ts'], + states: [{ name: 'owner', url: URL_OWNER, expect: '.rows .row' }, { name: 'lastowner', url: URL_LAST, expect: '.only-owner' }], + ...over, + })); +} + +type Cov = [name: string, viewport: string, status: 'measured' | 'incomplete', code: string]; +function lintJson(verdict: string, cov: Cov[], findings: unknown[] = []): string { + const states = cov.map(([name, viewport, status, code]) => ({ name, url: 'x', viewport, status, code, matched: 1 })); + return JSON.stringify({ summary: {}, files: 0, findings, app: { verdict, code: verdict === 'clean' ? 'OK' : verdict === 'open' ? 'OPEN' : cov.find((c) => c[2] !== 'measured')?.[3] ?? 'X', codes: [], within: 'section.access', matched: 1, viewports: VPS, states, open: 0, waived: 0, notes: [] } }); +} +const allMeasured = (names = ['owner', 'lastowner']): Cov[] => names.flatMap((n) => VPS.map((v): Cov => [n, v, 'measured', 'OK'])); +const finding = (rule: string, grade = 'ask', state = 'owner') => ({ rule, tier: grade === 'waived' ? 'ask' : grade, grade, file: 'x', line: 0, evidence: '[owner 1440px] a 2-line row leaves 4px', fix: 'f', source: 'render', ...(grade === 'waived' ? { waiver: 'house style here' } : {}), app: { state, viewport: '1440x900', locator: 'section.access > div.row', measured: 4, threshold: 8 } }); + +interface RunOpts { inv?: Inventory; lint?: string | null; shots?: string[] | 'all'; rounds?: number; unhandled?: object[]; beforeReceipt?: (repo: string, runDir: string) => void; repo?: string } +function run(o: RunOpts = {}) { + const repo = o.repo ?? fixtureRepo(); + const inv = o.inv ?? inventory(); + const runDir = tmpDir('design-build-run-'); + plan(inv, runDir); + verifyStart(repo, inv, runDir); + if (o.lint !== null) fs.writeFileSync(path.join(runDir, 'lint.json'), o.lint ?? lintJson('clean', allMeasured())); + const shots = o.shots ?? 'all'; + for (const s of inv.states) for (const v of VPS) if (shots === 'all' || shots.includes(`${s.name}-${v}`)) fs.writeFileSync(path.join(runDir, 'shots', `${s.name}-${v}.png`), 'png'); + const previewDir = tmpDir('design-build-preview-'); + if (o.unhandled) fs.writeFileSync(path.join(previewDir, 'unhandled.jsonl'), o.unhandled.map((u) => JSON.stringify(u)).join('\n') + '\n'); + o.beforeReceipt?.(repo, runDir); + const r = receipt({ repo, inv, runDir, rounds: o.rounds ?? 1, previewDir, outRoot: path.join(runDir, 'out') }); + return { ...r, repo, inv, runDir }; +} + +describe('the build receipt decides the outcome in code (T17, T18, T8, T12)', () => { + test('complete coverage with a clean lint verdict is clean; the line counts linted states, and the receipt is private and redacted', () => { + const r = run(); + expect(r.exit).toBe(0); + expect(r.line).toMatch(/^DESIGN_BUILD: clean code=OK linted=2\/2 shot=2\/2 screenshot_only=0 open=0 waived=0 rounds=1 viewports=1440x900,375x812 tree=[0-9a-f]{12} receipt=\S+receipt\.json$/); + expect(fs.statSync(r.file).mode & 0o777).toBe(0o600); + const text = fs.readFileSync(r.file, 'utf8'); + expect(text).not.toContain('RECEIPTSENTINEL'); + const rec = JSON.parse(text); + expect(rec).toMatchObject({ version: 1, outcome: 'clean', rounds: 1, viewports: VPS, counts: { planned: 2, url: 2, linted: 2 } }); + expect(rec.states.map((s: { name: string; expect: unknown }) => [s.name, s.expect])).toEqual([['owner', { selector: '.rows .row', passed: true }], ['lastowner', { selector: '.only-owner', passed: true }]]); + }); + + test('the verdict comes from the JSON: open findings make it open whatever the lint exited; waived findings alone make it waived', () => { + const open = run({ lint: lintJson('open', allMeasured(), [finding('row-crowding'), finding('small-hit-area', 'waived')]) }); + expect([open.exit, open.line.split(' ').slice(0, 3).join(' ')]).toEqual([1, 'DESIGN_BUILD: open code=OPEN']); + expect(open.line).toContain('open=1 waived=1'); + const waived = run({ lint: lintJson('clean', allMeasured(), [finding('small-hit-area', 'waived')]) }); + expect(waived.line).toStartWith('DESIGN_BUILD: waived code=OK'); + expect(waived.receipt.waived).toEqual([expect.objectContaining({ rule: 'small-hit-area', reason: 'house style here' })]); + }); + + test('a skipped render or partial coverage is never clean', () => { + const skipped = run({ lint: lintJson('incomplete', allMeasured().map(([n, v]): Cov => [n, v, 'incomplete', 'NO_BROWSER'])) }); + expect(skipped.line).toStartWith('DESIGN_BUILD: incomplete code=NO_BROWSER linted=0/2'); + const partial = run({ lint: lintJson('clean', allMeasured().filter(([n, v]) => !(n === 'lastowner' && v === '375x812'))) }); + expect(partial.line).toStartWith('DESIGN_BUILD: incomplete code=NOT_LINTED linted=1/2'); + const missing = run({ lint: null }); + expect(missing.line).toStartWith('DESIGN_BUILD: incomplete code=LINT_MISSING'); + const noShot = run({ shots: ['owner-1440x900', 'owner-375x812', 'lastowner-1440x900'] }); + expect(noShot.line).toStartWith('DESIGN_BUILD: incomplete code=NOT_SHOT linted=2/2 shot=1/2'); + const mismatch = run({ lint: lintJson('incomplete', [...allMeasured(['owner']), ['lastowner', '1440x900', 'incomplete', 'STATE_MISMATCH'], ['lastowner', '375x812', 'incomplete', 'STATE_MISMATCH']]) }); + expect(mismatch.line).toStartWith('DESIGN_BUILD: incomplete code=STATE_MISMATCH'); + expect(mismatch.receipt.states[1].expect).toEqual({ selector: '.only-owner', passed: false }); + for (const r of [skipped, partial, missing, noShot, mismatch]) expect(r.exit).toBe(4); + }); + + test('a screenshot-only state is never counted as linted, and an unreached one makes the run incomplete', () => { + const inv = inventory({ states: [{ name: 'owner', url: URL_OWNER, mode: 'url' }, { name: 'confirm', mode: 'screenshot', steps: 'click Remove on Dana' }] as Inventory['states'] }); + const shot = run({ inv, lint: lintJson('clean', allMeasured(['owner'])) }); + expect(shot.line).toStartWith('DESIGN_BUILD: clean code=OK linted=1/1 shot=2/2 screenshot_only=1'); + expect(shot.receipt.states[1]).toMatchObject({ name: 'confirm', mode: 'screenshot', linted: false }); + const unreached = run({ inv, lint: lintJson('clean', allMeasured(['owner'])), shots: ['owner-1440x900', 'owner-375x812'] }); + expect(unreached.line).toStartWith('DESIGN_BUILD: incomplete code=NOT_SHOT'); + expect(() => parseInventory(JSON.stringify({ version: 1, within: 'main', states: [{ name: 'confirm', mode: 'screenshot', steps: 'click' }] }))).toThrow('at least one url state'); + }); + + test('round 3 ends editing: open after round 3 is reported open, and a fourth round is refused', () => { + expect(run({ rounds: 3, lint: lintJson('open', allMeasured(), [finding('copy-flush-under-list')]) }).line).toContain('DESIGN_BUILD: open code=OPEN'); + expect(() => run({ rounds: 4 })).toThrow('--rounds 4 is outside 0 to 3'); + }); +}); + +describe('an unsupported fixture route never yields a complete receipt (T26)', () => { + test('a 501 the page caught still makes its state incomplete, while a declared error fixture does not', () => { + const r = run({ unhandled: [{ scenario: 'lastowner', method: 'GET', path: '/api/audit', code: 'PREVIEW_UNHANDLED' }] }); + expect(r.exit).toBe(4); + expect(r.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED linted=2/2'); + expect(r.line).toContain('lastowner: GET /api/audit (scenario lastowner)'); + expect(r.line).toContain('| fix: add the named route'); + expect(r.receipt.states[0].unhandled).toEqual([]); + const unknown = run({ unhandled: [{ scenario: 'owner', method: 'GET', path: '/api/members', code: 'PREVIEW_UNKNOWN_SCENARIO' }] }); + expect(unknown.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNKNOWN_SCENARIO'); + expect(run({ unhandled: [] }).line).toStartWith('DESIGN_BUILD: clean'); + }); + + test('a 501 recorded at any point in the run keeps the receipt incomplete, and a scenario-less one blocks every URL state', () => { + const early = run({ unhandled: [{ scenario: 'owner', method: 'DELETE', path: '/api/teams/7', code: 'PREVIEW_UNHANDLED', at: 1 }] }); + expect(early.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED'); + expect(early.line).toContain('restart the preview, then start a fresh run from preflight'); + const none = run({ unhandled: [{ scenario: '', method: 'GET', path: '/api/members', code: 'PREVIEW_NO_SCENARIO' }] }); + expect(none.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_NO_SCENARIO'); + expect(none.receipt.states.map((s) => (s.unhandled as unknown[]).length)).toEqual([1, 1]); + }); +}); + +describe('the receipt is bound to the measured tree (T7, T29, T37)', () => { + test('a regression the last round introduced is what the final pass reports', () => { + const repo = fixtureRepo(); + fs.writeFileSync(path.join(repo, 'src', 'app.css'), '.row { padding: 2px; }\n'); + const r = run({ repo, rounds: 3, lint: lintJson('open', allMeasured(), [finding('row-crowding', 'ask', 'lastowner')]) }); + expect(r.line).toStartWith('DESIGN_BUILD: open code=OPEN'); + expect(r.receipt.open).toEqual([expect.objectContaining({ rule: 'row-crowding', state: 'lastowner' })]); + }); + + test('evidence older than the final pass, or a tree that moved during it, is stale', () => { + const old = run({ beforeReceipt: (_repo, dir) => { const past = new Date(Date.now() - 60_000); fs.utimesSync(path.join(dir, 'lint.json'), past, past); } }); + expect(old.line).toStartWith('DESIGN_BUILD: incomplete code=STALE_EVIDENCE'); + for (const edit of ['src/app.css', 'src/access.ts', 'fixtures/owner.json']) { + const moved = run({ beforeReceipt: (repo) => fs.appendFileSync(path.join(repo, edit), '/* later */\n') }); + expect([edit, moved.line.split(' ').slice(0, 3).join(' ')]).toEqual([edit, 'DESIGN_BUILD: incomplete code=TREE_CHANGED']); + } + }); + + test('check keeps the line while the tree is unchanged and calls it stale after any later edit', () => { + const r = run(); + expect(check(r.repo, r.inv, r.file)).toEqual({ line: r.line, exit: 0 }); + fs.writeFileSync(path.join(r.repo, 'fixtures', 'lastowner.json'), '{}\n'); + const stale = check(r.repo, r.inv, r.file); + expect(stale.exit).toBe(4); + expect(stale.line).toStartWith('DESIGN_BUILD: stale code=TREE_CHANGED'); + }); + + test('the identity covers tracked diffs, the touched untracked files and fixture content, and nothing else', () => { + const repo = fixtureRepo(); + const inv = inventory(); + const a = treeIdentity(repo, inv); + fs.writeFileSync(path.join(repo, 'scratch.txt'), 'not touched by the loop\n'); + expect(treeIdentity(repo, inv)).toBe(a); + fs.writeFileSync(path.join(repo, 'src', 'access.ts'), 'export const rows = 4;\n'); + expect(treeIdentity(repo, inv)).not.toBe(a); + }); +}); + +describe('preflight, authorization and install (T14, T38, T31)', () => { + const engine = () => ({ engine: 'browse' as const, bin: '/x/browse' }); + test('the browser comes first: no engine is unrendered NO_BROWSER before any URL is touched', async () => { + const reached: string[] = []; + const r = await preflight(inventory(), [], { engine: () => ({ engine: null, probe: { ok: false, reason: 'NEEDS_ASIDE', detail: 't' }, error: 'no browser available: run ./setup' }) as never, reach: async (u) => { reached.push(u); return null; } }); + expect(r).toEqual({ lines: ['DESIGN_BUILD: unrendered code=NO_BROWSER (no browser available: run ./setup) | fix: gstack-browser-ensure, then rerun /design-review --build'], exit: 4 }); + expect(reached).toEqual([]); + }); + + test('a non-loopback target without a grant stops incomplete before any request; a named grant allows only that host', async () => { + const inv = inventory({ states: [{ name: 'prod', url: 'https://app.example.com/settings?as=owner', mode: 'url' }, { name: 'owner', url: URL_OWNER, mode: 'url' }] as Inventory['states'] }); + const reached: string[] = []; + const reach = async (u: string) => { reached.push(u); return null; }; + const refused = await preflight(inv, [], { engine, reach }); + expect(refused.exit).toBe(4); + expect(refused.lines[0]).toStartWith('DESIGN_BUILD: incomplete code=UNAUTHORIZED_TARGET (prod at https://app.example.com/settings?as=owner is not on loopback and has no grant; no page was opened and no action ran)'); + expect(reached).toEqual([]); + expect((await preflight(inv, ['other.example.com'], { engine, reach })).exit).toBe(4); + const probed: string[] = []; + const granted = await preflight(inv, ['app.example.com'], { engine, reach, preview: async (u) => { probed.push(u); return true; } }); + expect(granted.lines).toEqual(['PREFLIGHT: ok engine=browse states=2 targets=loopback+granted mutations=fixtures+granted']); + expect(probed).toEqual([URL_OWNER]); + expect((await preflight(inv, ['app.example.com'], { engine, reach, preview: async () => false })).lines).toEqual(['PREFLIGHT: ok engine=browse states=2 targets=loopback+granted mutations=unknown']); + expect((await preflight(inventory(), [], { engine, reach, preview: async () => true })).lines).toEqual(['PREFLIGHT: ok engine=browse states=2 targets=loopback mutations=fixtures-only']); + expect((await preflight(inventory(), [], { engine, reach, preview: async (u) => !u.includes('lastowner') })).lines).toEqual(['PREFLIGHT: ok engine=browse states=2 targets=loopback mutations=unknown']); + }); + + test('only the preview\'s own probe answer proves fixtures-only: a marker in the HTML or a redirect does not', async () => { + const page = 'app'; + const marked = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: () => new Response(page, { headers: { 'content-type': 'text/html' } }) }); + const preview = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: (req) => (new URL(req.url).pathname === '/api/__gstack-preview' ? new Response(null, { status: 204, headers: { 'x-gstack-preview': 'ready' } }) : new Response(page, { headers: { 'content-type': 'text/html' } })) }); + const bounce = Bun.serve({ hostname: '127.0.0.1', port: 0, fetch: (req) => Response.redirect(`http://127.0.0.1:${preview.port}${new URL(req.url).pathname}`, 302) }); + try { + const at = (port?: number) => inventory({ states: [{ name: 'owner', url: `http://127.0.0.1:${port}/settings?as=owner`, mode: 'url' }] as Inventory['states'] }); + for (const port of [marked.port, bounce.port]) expect((await preflight(at(port), [], { engine, reach: async () => null })).lines).toEqual(['PREFLIGHT: ok engine=browse states=1 targets=loopback mutations=unknown']); + expect((await preflight(at(preview.port), [], { engine, reach: async () => null })).lines).toEqual(['PREFLIGHT: ok engine=browse states=1 targets=loopback mutations=fixtures-only']); + } finally { for (const s of [marked, preview, bounce]) s.stop(true); } + }); + + test('a URL that does not answer is unrendered NO_PREVIEW, redacted', async () => { + const r = await preflight(inventory(), [], { engine, reach: async (u) => (u.includes('lastowner') ? 'connect ECONNREFUSED ' + u : null) }); + expect(r.lines[0]).toStartWith('DESIGN_BUILD: unrendered code=NO_PREVIEW (no answer from lastowner'); + expect(r.lines[0]).not.toContain('RECEIPTSENTINEL'); + }); + + test('a design-review start the install admission refused maps to unrendered code=INSTALL (real gstack-skill-start, mismatched verdict)', () => { + const gh = tmpDir('design-build-gh-'); + fs.writeFileSync(path.join(gh, 'config.yaml'), 'update_check: false\n'); + const real = fs.realpathSync(ROOT); + const verdict = path.join(gh, 'install-verdicts', `${createHash('sha256').update(real).digest('hex')}.json`); + fs.mkdirSync(path.dirname(verdict), { recursive: true }); + fs.writeFileSync(verdict, JSON.stringify({ schema_version: 1, checkout: real, head: '0'.repeat(40), for: 'design-review', required: ['runtime'], pins_planning_only: false, ok: true, trailer: 'gstack: ok 1.98.0.0 for=design-review', min_revision: '1.91.95.0', launch_path: '', time: '2026-11-07T00:00:00Z' })); + const home = tmpDir('design-build-home-'); + const start = spawnSync(path.join(ROOT, 'bin', 'gstack-skill-start'), ['--skill', 'design-review'], { cwd: home, encoding: 'utf8', timeout: 30_000, env: { PATH: process.env.PATH!, HOME: home, GSTACK_HOME: gh, GSTACK_LEASE_DIR: path.join(gh, 'leases'), GSTACK_SESSION_KIND: 'unattended', GSTACK_CAPY: '1' } }); + expect(start.status, start.stdout + start.stderr).toBe(3); + expect(start.stdout).toContain('GSTACK_RESULT: skill=design-review status=refused'); + const out = path.join(home, 'start.txt'); + fs.writeFileSync(out, start.stdout); + const r = spawnSync(BIN, ['admit', out], { encoding: 'utf8', timeout: 30_000 }); + expect(r.status).toBe(4); + expect(r.stdout).toMatch(/^DESIGN_BUILD: unrendered code=INSTALL \(INSTALL: fail verdict .*another HEAD.*\) \| fix: run install\.sh --for design-review/); + expect(admit('GSTACK_RESULT: skill=design-review status=complete run=x').lines).toEqual(['ADMIT: ok']); + }, 30_000); +}); + +describe('the bin: one line, exit codes, and a dirty tree left as it was (T17, T38)', () => { + test('plan prints the exact lint invocation, state file and every screenshot path; receipt and check print one DESIGN_BUILD line; git state is untouched', () => { + const repo = fixtureRepo(); + const before = { status: git(repo, 'status', '--porcelain'), css: fs.readFileSync(path.join(repo, 'src', 'app.css'), 'utf8'), stash: git(repo, 'stash', 'list'), log: git(repo, 'log', '--oneline') }; + const work = tmpDir('design-build-bin-'); + const inv = path.join(work, 'inventory.json'); + fs.writeFileSync(inv, JSON.stringify({ version: 1, within: 'section.access', fixtures: 'fixtures', touched: ['src/access.ts'], states: [{ name: 'owner', url: URL_OWNER, expect: '.rows .row' }] })); + const runDir = path.join(work, 'run'); + const sh = (args: string[]) => spawnSync(BIN, args, { cwd: repo, encoding: 'utf8', timeout: 30_000, env: { ...process.env, GSTACK_STATE_ROOT: path.join(work, 'state') } }); + const p = sh(['plan', '--inventory', inv, '--run-dir', runDir]); + expect(p.status, p.stderr).toBe(0); + expect(p.stdout).toContain(`LINT_CMD: '${path.join(ROOT, 'bin', 'gstack-design-lint')}' --scope app --state-file '${runDir}/states.json' --within 'section.access' --viewport 1440x900 --viewport 375x812 --json > '${runDir}/lint.json'`); + expect(p.stdout).toContain(`SHOT: owner 375x812 ${URL_OWNER} -> ${runDir}/shots/owner-375x812.png`); + expect(JSON.parse(fs.readFileSync(path.join(runDir, 'states.json'), 'utf8'))).toEqual({ version: 1, states: [{ name: 'owner', url: URL_OWNER, expect: '.rows .row' }] }); + expect(sh(['verify-start', '--inventory', inv, '--run-dir', runDir]).stdout).toMatch(/^VERIFY: tree=[0-9a-f]{12} /); + fs.writeFileSync(path.join(runDir, 'lint.json'), lintJson('clean', allMeasured(['owner']))); + for (const v of VPS) fs.writeFileSync(path.join(runDir, 'shots', `owner-${v}.png`), 'png'); + const rc = sh(['receipt', '--inventory', inv, '--run-dir', runDir, '--rounds', '2']); + expect(rc.status, rc.stderr).toBe(0); + expect(rc.stdout.trim().split('\n')).toHaveLength(1); + expect(rc.stdout).toMatch(new RegExp(`^DESIGN_BUILD: clean code=OK linted=1/1 .* receipt=${path.join(work, 'state', 'projects')}/[^/]+/designs/design-build-[0-9a-f]{12}-[0-9a-f]{12}/receipt\\.json\n$`)); + const file = /receipt=(\S+)/.exec(rc.stdout)![1]!; + expect(sh(['check', '--inventory', inv, '--receipt', file]).stdout).toBe(rc.stdout); + const fourth = sh(['receipt', '--inventory', inv, '--run-dir', runDir, '--rounds', '4']); + expect([fourth.status, fourth.stderr.trim()]).toEqual([3, 'gstack-design-build: ROUNDS: --rounds 4 is outside 0 to 3 | fix: the loop stops editing after round 3; report the open list instead of a fourth round']); + expect({ status: git(repo, 'status', '--porcelain'), css: fs.readFileSync(path.join(repo, 'src', 'app.css'), 'utf8'), stash: git(repo, 'stash', 'list'), log: git(repo, 'log', '--oneline') }).toEqual(before); + fs.appendFileSync(path.join(repo, 'src', 'access.ts'), '// edited after the receipt\n'); + const stale = sh(['check', '--inventory', inv, '--receipt', file]); + expect([stale.status, stale.stdout.split(' ').slice(0, 3).join(' ')]).toEqual([4, 'DESIGN_BUILD: stale code=TREE_CHANGED']); + }, 30_000); + + test('inventory errors are usage errors with a fix line', () => { + for (const [inv, msg] of [ + [{ version: 1, within: 'main', states: [{ name: 'a', url: URL_OWNER }], extra: 1 }, 'unknown inventory key extra'], + [{ version: 1, within: 'main', states: [{ name: 'a', url: URL_OWNER }, { name: 'a', url: URL_OWNER }] }, 'listed twice'], + [{ version: 1, within: 'main', states: [{ name: 'a', url: URL_OWNER }, { name: 'b', mode: 'screenshot' }] }, 'needs steps'], + [{ version: 1, within: 'main', touched: ['../x'], states: [{ name: 'a', url: URL_OWNER }] }, 'repo-relative'], + [{ version: 1, within: 'main', viewports: ['10x10'], states: [{ name: 'a', url: URL_OWNER }] }, 'width 320 to 3840'], + ] as const) expect(() => parseInventory(JSON.stringify(inv))).toThrow(msg); + expect(buildLine({ outcome: 'unrendered', code: 'NO_PREVIEW', detail: 'x | fix: y' })).toBe('DESIGN_BUILD: unrendered code=NO_PREVIEW (x / fix: y) | fix: start the preview (docs/howto-preview-a-frontend.md), then rerun'); + }); +}); + +/** + * design-review/templates/preview-fixtures.mjs without a browser: the shim in + * every page, scenarios by header, query or Referer, 501 problem documents + * that name the route and the file to edit (recorded for the build receipt), + * declared error fixtures passed through, SPA routes still served, loopback + * only, an owned port, a private redacted log and a clean stop. The shim + * itself runs in a VM with stand-in fetch and XHR. + */ +const PAGE = path.join(ROOT, 'test', 'fixtures', 'ui-spacing', 'preview'); +const FIXTURES = path.join(PAGE, 'fixtures'); + +async function begin(extra: string[] = []) { + const state = tmpDir('pv-'); + const p = await startPreview(['--static', '--root', PAGE, '--fixtures', FIXTURES, '--port', '0', '--state', state, ...extra]); + live.push(p); + return { ...p, state }; +} + +describe('preview template: scenarios and the fixture API (T3, T21, T22, T26, T36)', () => { + test('a malformed path escape gets a 400 and a fixture with a bad status gets a recorded 501, and the preview keeps serving', async () => { + const fixtures = tmpDir('pv-'); + fs.cpSync(FIXTURES, fixtures, { recursive: true }); + const owner = JSON.parse(fs.readFileSync(path.join(fixtures, 'owner.json'), 'utf8')); + owner.routes['GET /api/teams'] = { status: 'ok', json: [] }; + fs.writeFileSync(path.join(fixtures, 'owner.json'), JSON.stringify(owner)); + const state = tmpDir('pv-'); + const p = await startPreview(['--static', '--root', PAGE, '--fixtures', fixtures, '--port', '0', '--state', state]); + live.push(p); + expect((await fetch(p.url + '%E0%A4%A')).status).toBe(400); + const probe = await fetch(p.url + 'api/__gstack-preview', { redirect: 'manual' }); + expect([probe.status, probe.headers.get('x-gstack-preview')]).toEqual([204, 'ready']); + const bad = await fetch(p.url + 'api/teams?as=owner'); + expect([bad.status, bad.headers.get('x-gstack-preview')]).toEqual([501, 'PREVIEW_UNKNOWN_SCENARIO']); + expect((await bad.json()).detail).toContain('has a bad status or header'); + expect((await fetch(p.url + 'api/members?as=owner')).status).toBe(200); + expect(fs.readFileSync(path.join(state, 'unhandled.jsonl'), 'utf8')).toContain('"path":"/api/teams","code":"PREVIEW_UNKNOWN_SCENARIO"'); + expect(fs.readFileSync(path.join(state, 'unhandled.jsonl'), 'utf8')).not.toContain('__gstack-preview'); + }); + + test('pages get the shim; API calls are answered by header, ?as= or Referer; anything unsupported is a recorded 501', async () => { + const p = await begin(); + expect(p.ready).toMatch(/^PREVIEW: ready url=http:\/\/127\.0\.0\.1:\d+\/ mode=static state=\S+ log=\S+preview\.log$/); + const html = await (await fetch(p.url + '?as=owner')).text(); + expect(html.match(/data-gstack-preview/g)).toHaveLength(1); + expect(html.indexOf('data-gstack-preview')).toBeLessThan(html.indexOf('')); + const spa = await fetch(p.url + 'settings/team?as=owner'); + expect([spa.status, (await spa.text()).includes('Who has access')]).toEqual([200, true]); + + const byHeader = await fetch(p.url + 'api/members', { headers: { 'x-gstack-scenario': 'owner' } }); + expect((await byHeader.json()).map((m: { name: string }) => m.name)).toEqual(['Dana Whitfield', 'Omar Haddad', 'Lena Park']); + expect((await (await fetch(p.url + 'api/members?as=lastowner')).json())).toHaveLength(2); + expect((await (await fetch(p.url + 'api/members', { headers: { referer: p.url + 'settings?as=lastowner' } })).json())).toHaveLength(2); + const declared = await fetch(p.url + 'api/members/7', { method: 'DELETE', headers: { 'x-gstack-scenario': 'owner' } }); + expect([declared.status, (await declared.json()).error]).toEqual([409, 'The only owner cannot be removed.']); + + const problems = [ + [await fetch(p.url + 'api/members'), 'PREVIEW_NO_SCENARIO', 'arrived with no scenario'], + [await fetch(p.url + 'api/members', { headers: { 'x-gstack-scenario': 'nobody' } }), 'PREVIEW_UNKNOWN_SCENARIO', 'scenario "nobody" has no fixture file'], + [await fetch(p.url + 'api/audit?token=SEKRETSENTINEL', { headers: { referer: p.url + '?as=lastowner&session=REFSENTINEL' } }), 'PREVIEW_UNHANDLED', 'scenario "lastowner" has no route "GET /api/audit"'], + ] as const; + for (const [res, code, detail] of problems) { + expect([code, res.status, res.headers.get('content-type'), res.headers.get('x-gstack-preview')]).toEqual([code, 501, 'application/problem+json', code]); + const body = await res.json(); + expect(body).toMatchObject({ status: 501, code, type: expect.stringMatching(/howto-preview-a-frontend\.md#preview-/) }); + expect(body.detail).toContain(detail); + } + const unhandled = fs.readFileSync(path.join(p.state, 'unhandled.jsonl'), 'utf8').trim().split('\n').map((l) => JSON.parse(l)); + expect(unhandled).toEqual([ + { scenario: '', method: 'GET', path: '/api/members', code: 'PREVIEW_NO_SCENARIO' }, + { scenario: 'nobody', method: 'GET', path: '/api/members', code: 'PREVIEW_UNKNOWN_SCENARIO' }, + { scenario: 'lastowner', method: 'GET', path: '/api/audit', code: 'PREVIEW_UNHANDLED' }, + ]); + const fixLine = (await (await fetch(p.url + 'api/audit?as=lastowner')).json()).fix; + expect(fixLine).toBe(`add "GET /api/audit": {"status":200,"json":…} to ${path.join(FIXTURES, 'lastowner.json')}`); + + const log = path.join(p.state, 'preview.log'); + expect([fs.statSync(p.state).mode & 0o777, fs.statSync(log).mode & 0o777]).toEqual([0o700, 0o600]); + const text = fs.readFileSync(log, 'utf8'); + expect(text).toContain('GET /api/audit?token=REDACTED 501 PREVIEW_UNHANDLED scenario=lastowner'); + expect(text).not.toContain('SEKRETSENTINEL'); + + const stop = runPreview(['stop', '--state', p.state]); + expect(stop.out.trim()).toBe(`PREVIEW: stopped port=${p.port}`); + expect(await p.proc.exited).toBe(0); + expect(fs.existsSync(path.join(p.state, 'preview.json'))).toBe(false); + expect(await fetch(p.url).then(() => 'answered', () => 'closed')).toBe('closed'); + }, 30_000); + + test('loopback only, an owned port, and a named failure when the app has no Vite', async () => { + const p = await begin(); + const taken = runPreview(['start', '--static', '--root', PAGE, '--fixtures', FIXTURES, '--port', String(p.port), '--state', tmpDir('pv-')]); + expect([taken.code, taken.err.trim()]).toEqual([4, `PREVIEW: fail code=PREVIEW_PORT port ${p.port} on 127.0.0.1 is taken | fix: stop whatever holds the port, or pass another --port`]); + const host = runPreview(['start', '--static', '--root', PAGE, '--fixtures', FIXTURES, '--host', '0.0.0.0']); + expect([host.code, host.err]).toEqual([3, 'PREVIEW: fail code=PREVIEW_HOST --host 0.0.0.0 is not loopback | fix: the preview listens on 127.0.0.1 only; drop --host\n']); + const app = tmpDir('pv-'); + fs.writeFileSync(path.join(app, 'package.json'), '{"name":"no-vite","private":true}\n'); + const noVite = runPreview(['start', '--root', app, '--fixtures', FIXTURES, '--port', '0', '--state', tmpDir('pv-')]); + expect(noVite.code).toBe(4); + expect(noVite.err).toStartWith(`PREVIEW: fail code=PREVIEW_NO_VITE no vite package resolves from ${app} | fix: install vite`); + p.proc.kill('SIGTERM'); + expect(await p.proc.exited).toBe(0); + }, 30_000); +}); + +describe('preview template: the shim and the Vite plugin (T3, T21)', () => { + test('the shim adds x-gstack-scenario to same-origin fetch and XHR only, and keeps ?as= for the tab', async () => { + const mod = await import(PREVIEW_TEMPLATE); + const seen: Array<[string, string | null]> = []; + const store = new Map<string, string>(); + class FakeXHR { headers: Record<string, string> = {}; open(_m: string, _u: string) {} send() { seen.push(['xhr', this.headers['x-gstack-scenario'] ?? null]); } setRequestHeader(k: string, v: string) { this.headers[k] = v; } } + const ctx = (search: string) => { + const window: Record<string, unknown> = { + location: { search, href: 'http://127.0.0.1:5300/settings' + search, origin: 'http://127.0.0.1:5300' }, + sessionStorage: { getItem: (k: string) => store.get(k) ?? null, setItem: (k: string, v: string) => store.set(k, v) }, + fetch: async (u: string, init?: { headers?: Headers }) => { seen.push([u, init?.headers?.get('x-gstack-scenario') ?? null]); return 'ok'; }, + XMLHttpRequest: FakeXHR, URL, URLSearchParams, Headers, + }; + window.window = window; + vm.runInNewContext(mod.SHIM, { ...window, window }); + return window; + }; + const w = ctx('?as=lastowner'); + await (w.fetch as (u: string) => Promise<unknown>)('/api/members'); + await (w.fetch as (u: string) => Promise<unknown>)('https://api.example.com/x'); + const x = new (w.XMLHttpRequest as typeof FakeXHR)(); + x.open('GET', '/api/audit'); + x.send(); + const later = ctx(''); + await (later.fetch as (u: string) => Promise<unknown>)('/api/members'); + expect(seen).toEqual([['/api/members', 'lastowner'], ['https://api.example.com/x', null], ['xhr', 'lastowner'], ['/api/members', 'lastowner']]); + }); + + test('the plugin prepends the shim and mounts the fixture API on the dev server', async () => { + const mod = await import(PREVIEW_TEMPLATE); + const plugin = mod.gstackPreviewFixtures({ fixtures: FIXTURES }); + expect(plugin.name).toBe('gstack-preview-fixtures'); + expect(plugin.apply).toBe('serve'); + expect(plugin.transformIndexHtml()).toEqual([{ tag: 'script', attrs: { 'data-gstack-preview': '' }, children: mod.SHIM, injectTo: 'head-prepend' }]); + const used: Array<(req: unknown, res: unknown, next: () => void) => void> = []; + plugin.configureServer({ middlewares: { use: (fn: (typeof used)[number]) => used.push(fn) } }); + let status = 0; + let body = ''; + let passed = false; + used[0]!({ url: '/api/members', method: 'GET', headers: { 'x-gstack-scenario': 'owner' }, resume() {} }, { writeHead: (s: number) => { status = s; }, end: (b: string) => { body = b; } }, () => { passed = true; }); + expect([status, JSON.parse(body).length, passed]).toEqual([200, 3, false]); + used[0]!({ url: '/src/main.ts', method: 'GET', headers: {} }, {}, () => { passed = true; }); + expect(passed).toBe(true); + expect(mod.redact('http://' + ['u', 'p'].join(':') + '@h/x?api_key=a)b&ok=1#sig=c')).toBe('http://h/x?api_key=REDACTED&ok=1#sig=REDACTED'); + }); +}); + +describe('the receipt binds what it measured and reads the lint and preview as they are written', () => { + const PORT = 40000 + (process.pid % 20000); + const LOCAL = (as: string) => `http://127.0.0.1:${PORT}/settings?as=${as}`; + function measure(repo: string, inv: Inventory, recordedStates: string[]) { + const runDir = tmpDir('design-build-run-'); + plan(inv, runDir); + verifyStart(repo, inv, runDir); + fs.writeFileSync(path.join(runDir, 'lint.json'), lintJson('clean', allMeasured(recordedStates))); + for (const s of recordedStates) for (const v of VPS) fs.writeFileSync(path.join(runDir, 'shots', `${s}-${v}.png`), 'png'); + return runDir; + } + + test('an edit inside a touched directory changes the tree identity, so the receipt is TREE_CHANGED', () => { + const repo = fixtureRepo(); + fs.mkdirSync(path.join(repo, 'src', 'panel')); + fs.writeFileSync(path.join(repo, 'src', 'panel', 'a.tsx'), 'export const a = 1;\n'); + const r = run({ repo, inv: inventory({ touched: ['src/panel'] }), beforeReceipt: (rp) => fs.writeFileSync(path.join(rp, 'src', 'panel', 'a.tsx'), 'export const a = 2;\n') }); + expect(r.line).toStartWith('DESIGN_BUILD: incomplete code=TREE_CHANGED'); + }); + + test('an inventory edited after verify-start is never clean, and check refuses a receipt measured on another inventory', () => { + const repo = fixtureRepo(); + const inv = inventory(); + const fewer = inventory({ states: [{ name: 'owner', url: URL_OWNER, mode: 'url', expect: '.rows .row' }] }); + const runDir = measure(repo, inv, ['owner']); + const r = receipt({ repo, inv: fewer, runDir, rounds: 1, previewDir: tmpDir('design-build-preview-'), outRoot: path.join(runDir, 'out') }); + expect(r.line).toStartWith('DESIGN_BUILD: incomplete code=INVENTORY_CHANGED linted=1/1'); + const clean = run({ repo, inv }); + expect(clean.line).toStartWith('DESIGN_BUILD: clean'); + expect(check(repo, fewer, clean.file).line).toStartWith('DESIGN_BUILD: stale code=INVENTORY_CHANGED'); + expect(check(repo, inv, clean.file).line).toBe(clean.line); + }); + + test('without --preview the receipt reads the default preview state for each loopback port, so a recorded 501 is never clean', () => { + const repo = fixtureRepo(); + const inv = inventory({ states: [{ name: 'owner', url: LOCAL('owner'), mode: 'url' }, { name: 'lastowner', url: LOCAL('lastowner'), mode: 'url' }] }); + const state = path.join(os.tmpdir(), `gstack-preview-${PORT}`); + fs.mkdirSync(state, { recursive: true }); + tmp.push(state); + fs.writeFileSync(path.join(state, 'unhandled.jsonl'), JSON.stringify({ scenario: 'lastowner', method: 'GET', path: '/api/audit', code: 'PREVIEW_UNHANDLED' }) + '\n'); + const runDir = measure(repo, inv, ['owner', 'lastowner']); + const r = receipt({ repo, inv, runDir, rounds: 1, outRoot: path.join(runDir, 'out') }); + expect(r.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED linted=2/2'); + }); + + test("a path the app's own dev proxy forwards gets a recorded 501 instead of reaching the live backend", async () => { + const mod = await import(PREVIEW_TEMPLATE); + const state = tmpDir('pv-'); + const used: Array<(req: unknown, res: unknown, next: () => void) => void> = []; + mod.gstackPreviewFixtures({ fixtures: FIXTURES, stateDir: state }).configureServer({ config: { server: { proxy: { '/graphql': 'https://staging.example.com', '^/v1/.*': {} } } }, middlewares: { use: (fn: (typeof used)[number]) => used.push(fn) } }); + const hit = (url: string, method: string): [number, boolean] => { + let status = 0; + let passed = false; + used[0]!({ url, method, headers: { 'x-gstack-scenario': 'owner' }, resume() {} }, { writeHead: (s: number) => { status = s; }, end: () => {} }, () => { passed = true; }); + return [status, passed]; + }; + expect([hit('/graphql', 'POST'), hit('/v1/teams/7', 'DELETE'), hit('/src/main.ts', 'GET'), hit('/api/members', 'GET')]).toEqual([[501, false], [501, false], [0, true], [200, false]]); + expect(fs.readFileSync(path.join(state, 'unhandled.jsonl'), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l).code)).toEqual(['PREVIEW_LIVE_PROXY', 'PREVIEW_LIVE_PROXY']); + }); + + test('start refuses a state directory that is a symlink', () => { + const link = path.join(tmpDir('pv-'), 'state'); + fs.symlinkSync(tmpDir('pv-'), link); + const r = runPreview(['start', '--static', '--root', PAGE, '--fixtures', FIXTURES, '--port', '0', '--state', link]); + expect(r.code).toBe(4); + expect(r.err).toStartWith('PREVIEW: fail code=PREVIEW_STATE'); + }); +}); + +describe('round 3 (granted fix-check): the proxy catch-all, the preview record without --preview, and URL userinfo', () => { + test("an empty-string proxy key is a catch-all proxy and still gets the recorded 501", async () => { + const mod = await import(PREVIEW_TEMPLATE); + const state = tmpDir('pv-'); + const used: Array<(req: unknown, res: unknown, next: () => void) => void> = []; + mod.gstackPreviewFixtures({ fixtures: FIXTURES, stateDir: state }).configureServer({ config: { server: { proxy: { '': 'https://production.example' } } }, middlewares: { use: (fn: (typeof used)[number]) => used.push(fn) } }); + let status = 0; + let passed = false; + used[0]!({ url: '/graphql', method: 'POST', headers: { 'x-gstack-scenario': 'owner' }, resume() {} }, { writeHead: (s: number) => { status = s; }, end: () => {} }, () => { passed = true; }); + expect([status, passed]).toEqual([501, false]); + }); + + test('the probe names the state directory, so the receipt finds a --state or --port 0 preview without --preview; a preview with no record is never clean', async () => { + const state = tmpDir('pv-'); + const p = await startPreview(['--static', '--root', PAGE, '--fixtures', FIXTURES, '--port', '0', '--state', state]); + live.push(p); + const at = (as: string) => `${p.url}settings?as=${as}`; + const inv = inventory({ states: [{ name: 'owner', url: at('owner'), mode: 'url' }, { name: 'lastowner', url: at('lastowner'), mode: 'url' }] }); + expect(await servedStates(inv)).toEqual([{ origin: new URL(p.url).origin, state }]); + await fetch(p.url + 'api/audit?as=lastowner'); + const repo = fixtureRepo(); + const runDir = tmpDir('design-build-run-'); + plan(inv, runDir); + verifyStart(repo, inv, runDir); + fs.writeFileSync(path.join(runDir, 'lint.json'), lintJson('clean', allMeasured())); + for (const s of inv.states) for (const v of VPS) fs.writeFileSync(path.join(runDir, 'shots', `${s.name}-${v}.png`), 'png'); + const found = receipt({ repo, inv, runDir, rounds: 1, served: await servedStates(inv), outRoot: path.join(runDir, 'out') }); + expect(found.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED'); + const unrecorded = receipt({ repo, inv, runDir, rounds: 1, served: [{ origin: new URL(p.url).origin, state: null }], outRoot: path.join(runDir, 'out2') }); + expect(unrecorded.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNRECORDED'); + const mod = await import(PREVIEW_TEMPLATE); + const used: Array<(req: unknown, res: unknown, next: () => void) => void> = []; + mod.gstackPreviewFixtures({ fixtures: FIXTURES }).configureServer({ middlewares: { use: (fn: (typeof used)[number]) => used.push(fn) } }); + const headers: Record<string, string> = {}; + used[0]!({ url: '/api/__gstack-preview', method: 'GET', headers: {} }, { writeHead: (_s: number, h: Record<string, string>) => Object.assign(headers, h), end: () => {} }, () => {}); + expect([headers['x-gstack-preview'], headers['x-gstack-preview-state']]).toEqual(['ready', '']); + }); + + test('redactText drops userinfo up to the last @ before the host and redacts a percent-encoded secret key', () => { + expect(redactText('fetch http://' + ['user', 'p@ssw0rd'].join(':') + '@db.internal/x failed')).toBe('fetch http://db.internal/x failed'); + expect(redactText('GET http://h.test/p?%74oken=PCTSENTINEL&as=owner')).toBe('GET http://h.test/p?%74oken=REDACTED&as=owner'); + }); +}); + +describe('round 4 (granted fix-check): a stopped preview on another origin keeps its default record', () => { + test('when one origin answers the probe, a loopback origin that does not answer still has its default gstack-preview-<port> record read', async () => { + const state = tmpDir('pv-'); + const p = await startPreview(['--static', '--root', PAGE, '--fixtures', FIXTURES, '--port', '0', '--state', state]); + live.push(p); + const gone = Bun.serve({ port: 0, fetch: () => new Response('') }); + const stoppedPort = gone.port; + gone.stop(true); + const stoppedDir = path.join(os.tmpdir(), `gstack-preview-${stoppedPort}`); + fs.mkdirSync(stoppedDir, { recursive: true }); + fs.writeFileSync(path.join(stoppedDir, 'unhandled.jsonl'), JSON.stringify({ scenario: 'lastowner', method: 'GET', path: '/api/audit', code: 'PREVIEW_UNHANDLED' }) + '\n'); + try { + const inv = inventory({ states: [{ name: 'owner', url: `${p.url}settings?as=owner`, mode: 'url' }, { name: 'lastowner', url: `http://127.0.0.1:${stoppedPort}/settings?as=lastowner`, mode: 'url' }] }); + const repo = fixtureRepo(); + const runDir = tmpDir('design-build-run-'); + plan(inv, runDir); + verifyStart(repo, inv, runDir); + fs.writeFileSync(path.join(runDir, 'lint.json'), lintJson('clean', allMeasured())); + for (const s of inv.states) for (const v of VPS) fs.writeFileSync(path.join(runDir, 'shots', `${s.name}-${v}.png`), 'png'); + const r = receipt({ repo, inv, runDir, rounds: 1, served: await servedStates(inv), outRoot: path.join(runDir, 'out') }); + expect(r.line).toStartWith('DESIGN_BUILD: incomplete code=PREVIEW_UNHANDLED'); + } finally { + fs.rmSync(stoppedDir, { recursive: true, force: true }); + } + }); +}); diff --git a/test/design-lint-app-contract.test.ts b/test/design-lint-app-contract.test.ts index 64e060a44..27354b5cb 100644 --- a/test/design-lint-app-contract.test.ts +++ b/test/design-lint-app-contract.test.ts @@ -307,6 +307,32 @@ describe('app profile contract: findings, redaction and traces (T22, T29, T34, T expect(hashed.out + hashed.err).not.toContain('FRAGSENTINEL'); }); + test('a URL that does not parse and a token value holding ")" are redacted by pattern in text, JSON, stderr and traces', async () => { + expect(redactUrl('http://' + ['u', 'PW'].join(':') + '@localhost:99999/p?a=1&token=BADSENTINEL#sig=FRAGBAD')).toBe('http://localhost:99999/p?a=1&token=REDACTED#sig=REDACTED'); + expect(stateNameOf('http://localhost:99999/p?token=BADSENTINEL')).toBe('http://localhost:99999/p?token=REDACTED'); + expect(redactText('fetch failed at http://h.test/p?token=prefix)PARENSENTINEL_TAIL (x)')).toBe('fetch failed at http://h.test/p?token=REDACTED (x)'); + expect(redactText('GET /api?api_key=a:b)c&as=owner failed')).toBe('GET /api?api_key=REDACTED&as=owner failed'); + const bad = 'http://localhost:99999/p?token=SENTINEL_INVALID'; + for (const argv of [[], ['--json']]) { + const r = runBin(['--scope', 'app', '--url', bad, '--within', 'body', ...argv]); + expect(r.code).toBe(4); + expect(r.out + r.err).not.toContain('SENTINEL_INVALID'); + expect(r.out + r.err).toContain('token=REDACTED'); + } + const paren = 'http://127.0.0.1:5300/p?as=owner&token=prefix)PARENSENTINEL'; + const traceDir = tmpDir(); + const run = fakeRun({ measure: (w) => (w === 375 ? { error: 'Error: boom at ' + paren, stack: 'Error: boom\n at ' + paren + ':1:1' } : ok()) }); + for (const json of [false, true]) { + const out: string[] = []; + const err: string[] = []; + await appMain(args({ urls: [paren], json, verbose: true }), { out: (s) => out.push(s), err: (s) => err.push(s) }, { run, traceDir, reach: async () => 'connect ECONNREFUSED for ' + paren }); + await appMain(args({ urls: [paren], json, verbose: true }), { out: (s) => out.push(s), err: (s) => err.push(s) }, { run, traceDir, reach: async () => null }); + const traces = fs.readdirSync(traceDir).map((t) => fs.readFileSync(path.join(traceDir, t), 'utf8')).join(''); + expect(traces.length).toBeGreaterThan(0); + expect([json, (out.join('\n') + err.join('\n') + traces).includes('PARENSENTINEL')]).toEqual([json, false]); + } + }); + test('two --url states that share a redacted name stay two states; the same URL twice is DUPLICATE_STATE', async () => { const seen: string[] = []; const two = await app({ urls: ['http://127.0.0.1:5300/p?session=owner', 'http://127.0.0.1:5300/p?session=viewer'] }, { run: async (spec) => { seen.push(spec.file); return fakeRun({})(spec); } }); diff --git a/test/design-review-build-loop.test.ts b/test/design-review-build-loop.test.ts new file mode 100644 index 000000000..da3f0325a --- /dev/null +++ b/test/design-review-build-loop.test.ts @@ -0,0 +1,96 @@ +/** + * Source assertions for the opt-in /design-review --build loop: it routes + * before the audit's clean-tree stop but after nothing that the browser setup + * needs, never commits, stashes or asks, caps editing at three rounds, reads + * the lint verdict from JSON and leaves the one DESIGN_BUILD line to + * gstack-design-build. The seven items live in one place, and each adoption + * surface recommends the loop without making it a READY prerequisite. + */ +import { describe, expect, test } from 'bun:test'; +import * as fs from 'node:fs'; +import * as path from 'node:path'; + +const ROOT = path.resolve(import.meta.dir, '..'); +const read = (rel: string): string => fs.readFileSync(path.join(ROOT, rel), 'utf8'); +const TMPL = read('design-review/SKILL.md.tmpl'); +const SKILL = read('design-review/SKILL.md'); +const SECTION = read('design-review/sections/build-loop.md.tmpl'); + +describe('/design-review --build routing (T14, T38, T5)', () => { + test('the dispatch comes before the clean-tree check and its pointer after the hard rules', () => { + const dispatch = TMPL.indexOf('**`--build`:**'); + const clean = TMPL.indexOf('**Check for clean working tree:**'); + const browser = TMPL.indexOf('**Check the Aside browser:**'); + expect(dispatch).toBeGreaterThan(0); + expect(dispatch).toBeLessThan(clean); + expect(clean).toBeLessThan(browser); + expect(TMPL.slice(dispatch, clean)).toContain('skip the clean-tree check; run **Check the Aside browser**, then its STOP in Phases 1-6, not the audit.'); + const pointer = TMPL.indexOf('{{SECTION:build-loop}}'); + expect(TMPL.indexOf('{{DESIGN_HARD_RULES}}')).toBeLessThan(pointer); + expect(pointer).toBeLessThan(TMPL.indexOf('{{SECTION:craft-audit}}')); + expect(SKILL.indexOf('### Design Hard Rules')).toBeLessThan(SKILL.indexOf('> **STOP.**')); + expect(SKILL.indexOf('> **STOP.**')).toBe(SKILL.indexOf('> **STOP.** Before a --build run')); + }); + + test('the catalog description and triggers name the build mode', () => { + expect(/^description: .*--build checks UI while you build it/m.test(SKILL)).toBe(true); + expect(SKILL).toMatch(/^ - check the UI I am building$/m); + }); +}); + +describe('the build-loop section (T7, T8, T17, T18, T29, T37)', () => { + test('never commits, stashes, checks out, resets or asks', () => { + for (const bad of [/git (commit|stash|checkout|reset|add)\b/, /AskUserQuestion/]) expect(SECTION).not.toMatch(bad); + expect(SECTION).toContain('never asks'); + }); + + test('preflight before any round, at most three editing rounds, then a read-only final pass bound by verify-start', () => { + const at = (s: string) => { const i = SECTION.indexOf(s); expect([s, i >= 0]).toEqual([s, true]); return i; }; + expect(at('{{BIN_DIR}}/gstack-design-build preflight')).toBeLessThan(at('--run-dir "<run-dir>/round-N"')); + expect(at('### 3. Rounds (three at most)')).toBeLessThan(at('Stop\nediting after round 3')); + expect(at('{{BIN_DIR}}/gstack-design-build verify-start')).toBeLessThan(at('{{BIN_DIR}}/gstack-design-build receipt')); + expect(SECTION).toContain('There is no\nfourth editing round without a written grant.'); + }); + + test('the verdict is read from the lint JSON, never its exit status, and DESIGN_BUILD is printed by gstack-design-build only', () => { + expect(SECTION).toContain('`app.verdict`'); + expect(SECTION).toContain('Never\n read the lint\'s exit status as the result.'); + for (const bad of [/\$\?/, /exit code/i, /-eq 0/, /echo ["']?DESIGN_BUILD/]) expect(SECTION).not.toMatch(bad); + expect(SECTION).toContain('Run the printed `LINT_CMD:` line exactly.'); + }); + + test('each bash block stands alone: the first resolves the state root and slug, later ones name the helper and the run path literally', () => { + const blocks = [...SECTION.matchAll(/```bash\n([\s\S]*?)```/g)].map((m) => m[1]!); + expect(blocks[0]).toContain('SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)'); + expect(blocks[0]).toContain('GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?'); + for (const b of blocks.slice(1)) { + expect(b).not.toMatch(/\$(_DB|RUN|SLUG|GSTACK_STATE_ROOT)\b/); + expect(b).toContain('{{BIN_DIR}}/gstack-design-build'); + } + expect(SECTION).toContain("Save it where the driver can write (Aside's\n session directory; /tmp for $B), then cp it to the `SHOT:` path."); + }); + + test('the seven items are single-sourced in this section', () => { + const items = ['Row padding holds with one line and with two', 'Adjacent rows have breathing room', 'Comfortable hit areas', 'Nothing overflows at 375', 'Status notes sit on their own line with a warning treatment']; + for (const item of items) expect(SECTION).toContain(item); + const others = fs.readdirSync(ROOT, { recursive: true, withFileTypes: true }) + .filter((d) => d.isFile() && /\.(md|tmpl)$/.test(d.name) && !d.parentPath.includes('node_modules') && !d.parentPath.includes('.git')) + .map((d) => path.relative(ROOT, path.join(d.parentPath, d.name))) + .filter((f) => !/^design-review\/sections\/build-loop\.md(\.tmpl)?$/.test(f) && !/^\.[\w-]+\/skills\//.test(f) && !f.startsWith('test/')); + const carriers = others.filter((f) => items.some((i) => fs.readFileSync(path.join(ROOT, f), 'utf8').includes(i))); + expect(carriers).toEqual([]); + }); +}); + +describe('adoption surfaces recommend the loop, never require it (T5, T31)', () => { + test('lane card, routing block, docs/skills.md and /design-html', () => { + const lane = read('capy/skill/gstack/lane-card.md'); + expect(lane).toContain('UI work (recommended, never a READY prerequisite)'); + expect(lane).toContain('`install.sh --check --for design-review` and `gstack-browser-ensure`'); + expect(lane).toContain('A start that prints `GSTACK_RESULT: skill=design-review status=refused` is `DESIGN_BUILD: unrendered code=INSTALL`'); + expect(read('bin/gstack-skill-start')).toContain('- Building UI → once it renders, invoke /design-review --build <preview url> (opt-in)'); + expect(read('docs/skills.md')).toContain('**`--build` (opt-in, for UI you are building).**'); + expect(read('design-html/SKILL.md.tmpl')).toContain('recommend (opt-in, never required) `/design-review --build <preview url>`'); + expect(read('design-html/SKILL.md')).toContain('/design-review --build <preview url>'); + }); +}); diff --git a/test/fixtures/module-size-ratchet.json b/test/fixtures/module-size-ratchet.json index 97e68297a..80ef362d9 100644 --- a/test/fixtures/module-size-ratchet.json +++ b/test/fixtures/module-size-ratchet.json @@ -17,6 +17,7 @@ { "file": "lib/design-lint/render-probe-app.ts", "movedFrom": "(new: the design lint's app profile probes, GST-1741)" }, { "file": "lib/design-lint/app-input.ts", "movedFrom": "(new: the design lint's app profile inputs and URL redaction, GST-1741)" }, { "file": "lib/design-lint/app-cli.ts", "movedFrom": "(new: the design lint's --scope app CLI, GST-1741)" }, + { "file": "lib/design-build.ts", "movedFrom": "(new: the /design-review --build receipt behind gstack-design-build, GST-1741)" }, { "file": "lib/design-lint/render-png.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint-render.mjs)" }, { "file": "lib/design-lint/rules/assets.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint.mjs)" }, { "file": "lib/design-lint/rules/chrome-copy.ts", "movedFrom": "(new: the bundled design lint, GSTA-105; ported from hallmark sloplint.mjs)" }, diff --git a/test/fixtures/ui-spacing/preview/fixtures/lastowner.json b/test/fixtures/ui-spacing/preview/fixtures/lastowner.json new file mode 100644 index 000000000..63908a16c --- /dev/null +++ b/test/fixtures/ui-spacing/preview/fixtures/lastowner.json @@ -0,0 +1,19 @@ +{ + "version": 1, + "routes": { + "GET /api/members": { + "status": 200, + "delay_ms": 600, + "json": [ + { + "name": "Dana Whitfield", + "role": "Owner" + }, + { + "name": "Omar Haddad", + "role": "Reader" + } + ] + } + } +} diff --git a/test/fixtures/ui-spacing/preview/fixtures/owner.json b/test/fixtures/ui-spacing/preview/fixtures/owner.json new file mode 100644 index 000000000..33db730bf --- /dev/null +++ b/test/fixtures/ui-spacing/preview/fixtures/owner.json @@ -0,0 +1,32 @@ +{ + "version": 1, + "routes": { + "GET /api/members": { + "status": 200, + "json": [ + { + "name": "Dana Whitfield", + "role": "Owner" + }, + { + "name": "Omar Haddad", + "role": "Editor" + }, + { + "name": "Lena Park", + "role": "Reader" + } + ] + }, + "GET /api/audit": { + "status": 200, + "json": [] + }, + "DELETE /api/members/:id": { + "status": 409, + "json": { + "error": "The only owner cannot be removed." + } + } + } +} diff --git a/test/fixtures/ui-spacing/preview/index.html b/test/fixtures/ui-spacing/preview/index.html new file mode 100644 index 000000000..eeee3deeb --- /dev/null +++ b/test/fixtures/ui-spacing/preview/index.html @@ -0,0 +1,49 @@ +<!doctype html> +<html lang="en"> +<head> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>Project settings: access list from the fixture API + + + +
+
+

Who has access

+
+

Readers see deploys and logs; editors can change settings.

+
+
+ + + diff --git a/test/helpers/autoplan-preconfigured-fixture.ts b/test/helpers/autoplan-preconfigured-fixture.ts index ff958532b..758bd086c 100644 --- a/test/helpers/autoplan-preconfigured-fixture.ts +++ b/test/helpers/autoplan-preconfigured-fixture.ts @@ -16,6 +16,7 @@ Key routing rules: - QA/testing site behavior → invoke /qa or /qa-only - Code review/diff check → invoke /review - Visual polish → invoke /design-review +- Building UI → once it renders, invoke /design-review --build (opt-in) - Ship/deploy/PR → invoke /ship (merge + deploy: the user types /land-and-deploy) - Save progress → invoke /context-save - Resume context → invoke /context-restore diff --git a/test/helpers/carve-guards.ts b/test/helpers/carve-guards.ts index bc35176e1..40393984f 100644 --- a/test/helpers/carve-guards.ts +++ b/test/helpers/carve-guards.ts @@ -757,10 +757,10 @@ do not launch the downstream skill or open a browser.`, // No section-loading paid case yet: a new periodic case would push the // periodic census past its 38-slice cap (test/paid-retry-supervision.test.ts). behavioral: 'none', - maxSkeletonBytes: 84_869, // GSTA-134 skill diet (2026-10-28): lowered from 115_947 to the measured skeleton after the outside voices and test bootstrap moved to sections, 84,869. Before: GSTA-96 hoist merged with v1.91.274.0 (#3507, 2026-10-27): the hoisted skeleton plus main's headroom of 0 bytes; measured 115,947 on the merged tree. Before: measured 137735 on the merged tree with main f27a760 (2026-10-27, #3507); 137767 (2026-10-26; 137773 on 2026-10-25 before the shorter craft-audit trigger): the Section index the external-host carve test requires, its craft-audit row, and the STOP pointer (GSTA-92; Garry 2026-10-25 'Do it' (GSTA-92)). + maxSkeletonBytes: 85_182, // /design-review --build (GST-1741 PR 2, 2026-11-07, grant: GStack Minder, 2026-11-07): --build routing, stop pointer, index row, description clause and trigger: +443 B, trimmed 130; the build-loop section is mode-loaded; measured 85,182. Before: GSTA-134 skill diet (2026-10-28): lowered from 115_947 to the measured skeleton after the outside voices and test bootstrap moved to sections, 84,869. Before: GSTA-96 hoist merged with v1.91.274.0 (#3507, 2026-10-27): the hoisted skeleton plus main's headroom of 0 bytes; measured 115,947 on the merged tree. Before: measured 137735 on the merged tree with main f27a760 (2026-10-27, #3507); 137767 (2026-10-26; 137773 on 2026-10-25 before the shorter craft-audit trigger): the Section index the external-host carve test requires, its craft-audit row, and the STOP pointer (GSTA-92; Garry 2026-10-25 'Do it' (GSTA-92)). minUnionBytes: 136_100, // GSTA-134 skill diet (2026-10-28): measured union 137,602 (lowered from 143_300); before: measured union 144802 on the merged tree with main f27a760 (2026-10-27, #3507); 145037 (2026-10-26) mustContain: ['AI Slop Detection', 'Fix Loop', 'gstack-design-lint', 'Proof beside each claim', 'holds session data'], - maxSizeRatio: 1.3001, // GSTA-134 skill diet (2026-10-28): measured 137,602 / 105,842 = 1.30007, rounded up (lowered from 1.3739). Before: GSTA-96 hoist merged with v1.91.274.0 (#3507, 2026-10-27): the union now holds sections/preamble.md (the hoist's owner-approved raise, decision A) on top of main's 1.3681; measured 145,410 / 105,842 = 1.3739 on the merged tree. Before: first parity guard for design-review: measured 144802 / 105,842 = 1.3681 on the merged tree with main f27a760 (2026-10-27, #3507: the design lint swap); before that 145082 / 105,842 = 1.3708 (2026-10-25; 145077 after the /ship review fixes, 145068 = 1.3707 after the line-13 reword, 145049 = 1.3705 after the post-merge /ship review, 145037 = 1.3704 after its second pass, 2026-10-26), the skeleton's growth since v1.64.1.0 plus the craft audit (Garry 2026-10-25 'Do it' (GSTA-92)). + maxSizeRatio: 1.357, // /design-review --build (GST-1741 PR 2, 2026-11-07, grant: GStack Minder, 2026-11-07): --build routing, stop pointer, index row, description clause and trigger: +443 B, trimmed 130; the build-loop section is mode-loaded; measured 143,620 / 105,842 = 1.35693. Before: 1.3001, GSTA-134 skill diet (2026-10-28): measured 137,602 / 105,842 = 1.30007, rounded up (lowered from 1.3739). Before: GSTA-96 hoist merged with v1.91.274.0 (#3507, 2026-10-27): the union now holds sections/preamble.md (the hoist's owner-approved raise, decision A) on top of main's 1.3681; measured 145,410 / 105,842 = 1.3739 on the merged tree. Before: first parity guard for design-review: measured 144802 / 105,842 = 1.3681 on the merged tree with main f27a760 (2026-10-27, #3507: the design lint swap); before that 145082 / 105,842 = 1.3708 (2026-10-25; 145077 after the /ship review fixes, 145068 = 1.3707 after the line-13 reword, 145049 = 1.3705 after the post-merge /ship review, 145037 = 1.3704 after its second pass, 2026-10-26), the skeleton's growth since v1.64.1.0 plus the craft audit (Garry 2026-10-25 'Do it' (GSTA-92)). }, // ── Token-reduction Phase 4 wave 4 (v1.69.x branch): design doctrine carve ── diff --git a/test/helpers/free-fixtures-data.ts b/test/helpers/free-fixtures-data.ts index 4a6db25ff..d1f33b831 100644 --- a/test/helpers/free-fixtures-data.ts +++ b/test/helpers/free-fixtures-data.ts @@ -259,7 +259,7 @@ export const FREE_FIXTURES: Readonly> = { 'test/fixtures/trial-cause/replays.json': ['test/trial-cause.test.ts'], 'test/fixtures/trial-cause/thinking-captures-37198445662.json': ['test/trial-cause.test.ts'], 'test/fixtures/trial-record-v1-reader.ts': ['test/helpers/eval-store.test.ts'], - 'test/fixtures/ui-spacing/**': ['test/design-lint-app-contract.test.ts', 'test/design-lint-app-profile.test.ts', 'test/design-lint-scope-guard.test.ts'], + 'test/fixtures/ui-spacing/**': ['test/design-lint-app-contract.test.ts', 'test/design-lint-app-profile.test.ts', 'test/design-lint-scope-guard.test.ts', 'test/design-build-e2e.test.ts', 'test/design-build.test.ts'], 'test/fixtures/windows-bash-resolution.json': ['test/script-invocation.test.ts'], 'test/fixtures/workflow-required-steps.json': ['test/workflow-required-steps.test.ts'], }; diff --git a/test/helpers/preview-template.ts b/test/helpers/preview-template.ts new file mode 100644 index 000000000..ceef0d68a --- /dev/null +++ b/test/helpers/preview-template.ts @@ -0,0 +1,29 @@ +/** Start design-review/templates/preview-fixtures.mjs under isolated Bun and wait for its ready line. */ +import * as path from 'node:path'; +import { bunIsolationArgs } from '../../lib/bun-isolation'; + +export const PREVIEW_TEMPLATE = path.join(import.meta.dir, '..', '..', 'design-review', 'templates', 'preview-fixtures.mjs'); + +export interface Preview { url: string; port: number; proc: ReturnType; ready: string } + +export async function startPreview(args: string[], timeoutMs = 15_000): Promise { + const proc = Bun.spawn([process.execPath, ...bunIsolationArgs(), PREVIEW_TEMPLATE, 'start', ...args], { stdout: 'pipe', stderr: 'pipe' }); + const reader = proc.stdout.getReader(); + let text = ''; + const deadline = Date.now() + timeoutMs; + while (!/PREVIEW: ready .*\n/.test(text)) { + if (Date.now() > deadline) { proc.kill(); throw new Error('preview did not start: ' + text); } + const chunk = await Promise.race([reader.read(), Bun.sleep(200).then(() => null)]); + if (chunk && chunk.done) throw new Error('preview exited: ' + text + (await new Response(proc.stderr).text())); + if (chunk?.value) text += new TextDecoder().decode(chunk.value); + } + reader.releaseLock(); + const ready = /PREVIEW: ready .*/.exec(text)![0]; + const url = /url=(\S+)/.exec(ready)![1]!; + return { url, port: Number(new URL(url).port), proc, ready }; +} + +export function runPreview(args: string[]) { + const r = Bun.spawnSync([process.execPath, ...bunIsolationArgs(), PREVIEW_TEMPLATE, ...args], { stdout: 'pipe', stderr: 'pipe', timeout: 20_000 }); + return { code: r.exitCode, out: r.stdout.toString(), err: r.stderr.toString() }; +} diff --git a/test/test-pr-profile.test.ts b/test/test-pr-profile.test.ts index 79936ae0e..233173e47 100644 --- a/test/test-pr-profile.test.ts +++ b/test/test-pr-profile.test.ts @@ -256,6 +256,13 @@ describe('fast PR coverage policy', () => { expect(prLines).not.toContain('Full gate restored'); }); + test('the design lint app profile and build receipt fixtures are free fixtures, so editing them never restores the full gate', () => { + const changedFiles = ['test/fixtures/ui-spacing/replica.html', 'test/fixtures/ui-spacing/preview/index.html', 'test/fixtures/ui-spacing/preview/fixtures/lastowner.json']; + const result = selectPrProfile({ selectedE2E: [], selectedJudges: [], changedFiles, screenPolicy: 'narrow' }); + expect(result.unknownFiles).toEqual([]); + expect(result.mode).not.toBe('full-fallback'); + }); + test('DX-11: an edited paid test file selects its own name-addressable gate cases outside the profile', () => { const direct: PrProfileMaps = { ...maps, e2eTouchfiles: { ...maps.e2eTouchfiles, 'own-named': ['test/skill-e2e-own.test.ts'], 'own-prose': ['test/skill-e2e-own.test.ts'] },