From 118207f0f762ac8aa9bfbd2b93417f34d8f199e6 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 7 Nov 2026 18:18:23 -0800 Subject: [PATCH] Add /design-review --build, an opt-in loop that checks and fixes new UI while you build it (#4142) * Hide tokens in URLs that do not parse or that hold punctuation Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Add a build receipt and a fixture preview server so a design state whose API call went unanswered is never reported finished Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Register the preview fixtures as free so editing them does not rerun every paid test Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Add /design-review --build, an opt-in loop that lints, screenshots and fixes UI while you build it Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Recommend the design build loop for UI work in the lane card, routing rules, skills guide and design-html Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Let the design review skill grow by the opt-in build mode's routing line and pointer Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Make the design build loop work when an agent follows it step by step A real run of /design-review --build turned up four problems: - Each bash block runs in a fresh shell, so later blocks lost $RUN and the helper path, and the first block never set the project slug or state root. Blocks now stand alone and later ones use the printed run path. - The lint command it printed was a bare name that is not on PATH; it now prints the full path to the bundled lint. - gstack's own browser can only save screenshots under /tmp, so the section says to save where the browser can write and copy the file into place. - The --build pointer sat before the design hard rules, which every section must follow; it now comes right after them. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Hold the design-review size ratio to the granted 1.357 Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Let the free checks find the preview server's test when the server file changes Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Keep the design build loop honest about stale API misses and pages that are not the preview A missing fixture route that was fixed before the final pass no longer blocks the receipt, an API call that arrived with no scenario now does, preflight only promises fixtures-only mutations when every page carries the preview script, and a bad path escape or a fixture with a bad status no longer stops the preview. Review-Finding: p1/specialist-batched#1 reader=state-machines Review-Finding: p1/specialist-batched#2 reader=security Review-Finding: p1/red-team#1 reader=red-team Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/red-team#4 reader=red-team Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Make the design build loop fail closed on any missed API call and only trust a page the preview actually serves Any API call the preview could not answer during a run now keeps the receipt incomplete, and its fix line says to add the route, restart the preview and start again from preflight. Preflight checks every local page whatever hosts were granted, asks the preview's own probe route instead of looking for a marker in the HTML, and treats a redirect as not the preview. The Vite plugin now applies to the dev server only, so built pages never carry the preview script. Review-Finding: p2v/outside-voice#3 reader=outside-voice Review-Finding: p2/red-team#1 reader=red-team Review-Finding: p2v/outside-voice#1 reader=outside-voice Review-Finding: p2v/outside-voice#2 reader=outside-voice Review-Loop-Exception: a-0aec1d2672bd Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Link the frontend preview guide from the README and note the preview check in the changelog Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Fix a test type error the CI type check caught in the preview probe test Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Fix the five free-suite failures in the design build loop Run the slug helper through the shared script launcher, move the preview server tests into the design build test that imports the product code, let the single-source check skip generated host copies, write the build-loop commands without free-text placeholders (trimmed so the skill stays under its size cap), and add the build routing line to the onboarding fixture. Review-Loop-Exception: a-b2e2abe1c646 Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Document how to waive findings in the design build loop and say which requests the preview log records Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Keep the design build receipt from calling waived, edited or proxied runs clean The receipt now reads waivers from the lint's grade, hashes every file in a touched folder, refuses an inventory that changed after verify-start, and finds the preview's record of unanswered calls in its default state folder. The preview answers a path the app's own dev proxy would forward with a recorded 501, and refuses a state folder that is a symlink or another user's. Review-Finding: p1/red-team#1 reader=red-team Review-Finding: p1/red-team#2 reader=red-team Review-Finding: p1/red-team#3 reader=red-team Review-Finding: p1/red-team#4 reader=red-team Review-Finding: p1/specialist-batched#1 reader=testing Review-Finding: p1/specialist-batched#2 reader=security Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Give the new receipt tests the state mode the inventory type requires, and say the preview does not stop proxied WebSocket upgrades Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Stop a catch-all dev proxy, an unrecorded preview and passwords with @ from slipping past the design build checks An empty server.proxy key now gets the recorded 501 too. The preview's probe names its state directory, so the receipt reads a --state or --port 0 preview's record without --preview, and a preview that keeps no record makes the run incomplete. Text redaction drops userinfo up to the last @ and redacts percent-encoded secret parameter names. Review-Finding: s11/outside-voice#1 reader=outside-voice Review-Finding: s11/targeted#1 reader=targeted Review-Finding: s11/adversarial-native#3 reader=adversarial-native Review-Finding: s11/targeted#2 reader=targeted Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Build the userinfo redaction test's URL from parts so the credential scan does not read it as a real login Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * Keep reading a stopped preview's default record when another origin's preview still answers The receipt now reads the union of --preview, the state directory each answering preview names, and the default gstack-preview- directory for every loopback state origin that did not answer the probe. servedStates reports which origin each answer came from. Review-Finding: fc3/fix-check#1 reader=fix-check Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> * List the design build receipt, its library and the preview template in the project structure guide Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --------- Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com> --- README.md | 1 + bin/gstack-design-build | 97 +++ bin/gstack-skill-start | 1 + capy/skill/gstack/lane-card.md | 1 + changelog.d/design-review-build-loop.md | 7 + design-html/SKILL.md | 2 + design-html/SKILL.md.tmpl | 2 + design-review/SKILL.md | 25 +- design-review/SKILL.md.tmpl | 23 +- design-review/sections/build-loop.md | 116 ++++ design-review/sections/build-loop.md.tmpl | 114 ++++ design-review/sections/manifest.json | 6 + design-review/templates/preview-fixtures.mjs | 278 ++++++++ docs/PROJECT_STRUCTURE.md | 6 +- docs/design-lint.md | 4 +- docs/howto-preview-a-frontend.md | 150 +++++ docs/skills.md | 2 + gstack/llms.txt | 2 +- lib/design-build.ts | 357 +++++++++++ lib/design-lint/app-input.ts | 21 +- test/design-build-e2e.test.ts | 72 +++ test/design-build.test.ts | 593 ++++++++++++++++++ test/design-lint-app-contract.test.ts | 26 + test/design-review-build-loop.test.ts | 96 +++ test/fixtures/module-size-ratchet.json | 1 + .../preview/fixtures/lastowner.json | 19 + .../ui-spacing/preview/fixtures/owner.json | 32 + test/fixtures/ui-spacing/preview/index.html | 49 ++ .../helpers/autoplan-preconfigured-fixture.ts | 1 + test/helpers/carve-guards.ts | 4 +- test/helpers/free-fixtures-data.ts | 2 +- test/helpers/preview-template.ts | 29 + test/test-pr-profile.test.ts | 7 + 33 files changed, 2117 insertions(+), 29 deletions(-) create mode 100755 bin/gstack-design-build create mode 100644 changelog.d/design-review-build-loop.md create mode 100644 design-review/sections/build-loop.md create mode 100644 design-review/sections/build-loop.md.tmpl create mode 100644 design-review/templates/preview-fixtures.mjs create mode 100644 docs/howto-preview-a-frontend.md create mode 100644 lib/design-build.ts create mode 100644 test/design-build-e2e.test.ts create mode 100644 test/design-build.test.ts create mode 100644 test/design-review-build-loop.test.ts create mode 100644 test/fixtures/ui-spacing/preview/fixtures/lastowner.json create mode 100644 test/fixtures/ui-spacing/preview/fixtures/owner.json create mode 100644 test/fixtures/ui-spacing/preview/index.html create mode 100644 test/helpers/preview-template.ts 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'] },