@iceinvein/agent-skills 0.1.24 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Install agent skills into AI coding tools",
   "author": "iceinvein",
   "license": "MIT",

package/skills/magpie/README.md

@@ -33,11 +33,26 @@ Inside Claude Code, ask: "Review PR 1234" (or paste a PR URL). The agent reads S
 
 ```
 bun install           # Installs @types/bun
-bun test              # Run all tests (145 tests, 24 files)
+bun test              # Run all tests
 bun run lint          # Biome check
 bun run typecheck     # tsc --noEmit
 ```
 
+### Previewing the UI
+
+Use the bundled example PR fixture to render either page without a real review. Useful for design iteration.
+
+```
+magpie preview                                  # render both pages, open findings.html
+magpie preview --page progress --stage fresh    # progress page at "everything pending"
+magpie preview --page progress --stage specialists-running
+magpie preview --page progress --stage peer-review-error
+magpie preview --no-open --out /tmp/magpie-ui   # write files only
+magpie preview --list-stages                    # see all stage presets
+```
+
+The fixture lives at `fixtures/example-pr/` (pr.json + findings.final.json + post-status.json) and covers all four severities, all five focus domains, every section combination (with/without suggestion code block, with/without verification, raw-prose fallback), and a mix of posted / failed / fresh badges.
+
 ## Layout
 
 - `SKILL.md` is the agent-facing prompt; installed by the agent-skills CLI.

package/skills/magpie/bin/magpie.ts

@@ -15,11 +15,32 @@ Subcommands:
   status <run-dir>           Print highest completed stage
   open [id]                  Open findings.html in your browser (defaults to latest run)
   post <run-dir> --ids a,b   Post the given finding ids via gh (rich body + optional summary)
+  preview [opts]             Render the UI from a bundled fixture (no PR needed). See --help-preview.
   --list-runs                List archived runs
   --cleanup-run <id>         Delete an archived run
   --version                  Print the magpie version
   --help                     Show this message`
 
+const USAGE_PREVIEW = `Usage: magpie preview [options]
+
+Render the findings and/or progress pages from a bundled example PR fixture so
+you can iterate on the UI without running a real review.
+
+Options:
+  --page <findings|progress|both>   Which page to render (default: both)
+  --stage <preset>                  Pipeline state preset for the progress page
+                                    (default: report-done)
+  --fixture <dir>                   Override the fixture directory
+  --out <dir>                       Where to write the HTML (default: ~/.magpie/preview-<ts>)
+  --no-open                         Don't open the page in your browser
+  --dry-run                         Print the paths that would be written, write nothing
+  --list-stages                     List the known --stage presets and exit
+  --help                            Show this message
+
+Stage presets: fresh, setup-running, setup-done, context-skipped,
+specialists-running, specialists-done, dedupe-done, critic-done,
+peer-review-error, report-done, post-done.`
+
 type Handler = (args: string[]) => Promise<number> | number
 
 const HANDLERS: Record<string, Handler> = {
@@ -178,6 +199,45 @@ const HANDLERS: Record<string, Handler> = {
     process.stdout.write(`${JSON.stringify(outcome)}\n`)
     return outcome.ok ? 0 : 1
   },
+  preview: async (args) => {
+    if (args.includes('--help') || args.includes('-h')) {
+      process.stdout.write(`${USAGE_PREVIEW}\n`)
+      return 0
+    }
+    const { KNOWN_STAGE_PRESETS, DEFAULT_STAGE, runPreview } = await import(
+      '../scripts/preview-cmd.ts'
+    )
+    if (args.includes('--list-stages')) {
+      for (const s of KNOWN_STAGE_PRESETS) process.stdout.write(`${s}\n`)
+      return 0
+    }
+    const pageFlag = args.indexOf('--page')
+    const pageRaw = pageFlag !== -1 ? args[pageFlag + 1] : 'both'
+    if (pageRaw !== 'findings' && pageRaw !== 'progress' && pageRaw !== 'both') {
+      process.stderr.write(`preview: invalid --page ${pageRaw} (want findings|progress|both)\n`)
+      return 2
+    }
+    const stageFlag = args.indexOf('--stage')
+    const stageRaw = stageFlag !== -1 ? args[stageFlag + 1] : DEFAULT_STAGE
+    if (!stageRaw || !KNOWN_STAGE_PRESETS.includes(stageRaw as never)) {
+      process.stderr.write(
+        `preview: invalid --stage ${stageRaw}. Use --list-stages to see available presets.\n`,
+      )
+      return 2
+    }
+    const fixtureFlag = args.indexOf('--fixture')
+    const outFlag = args.indexOf('--out')
+    const result = await runPreview({
+      page: pageRaw,
+      stage: stageRaw as never,
+      ...(fixtureFlag !== -1 && args[fixtureFlag + 1] ? { fixtureDir: args[fixtureFlag + 1] } : {}),
+      ...(outFlag !== -1 && args[outFlag + 1] ? { outDir: args[outFlag + 1] } : {}),
+      openInBrowser: !args.includes('--no-open') && !args.includes('--dry-run'),
+      dryRun: args.includes('--dry-run'),
+    })
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+    return 0
+  },
   '--list-runs': async () => {
     const { listRuns } = await import('../scripts/housekeeping-cmd.ts')
     const runs = await listRuns()
@@ -221,5 +281,3 @@ async function main(argv: string[]): Promise<number> {
 
 const code = await main(process.argv.slice(2))
 process.exit(code)
-
-export {}

package/skills/magpie/fixtures/example-pr/findings.final.json

@@ -0,0 +1,137 @@
+[
+  {
+    "id": "security-1",
+    "file": "src/api/session.ts",
+    "line": 87,
+    "severity": "blocker",
+    "risk": {
+      "impact": "critical",
+      "likelihood": "likely",
+      "confidence": "high",
+      "action": "must-fix"
+    },
+    "title": "Session token written to Redis with no TTL and no namespace, every tenant shares the same keyspace",
+    "description": "Observation: createSession() (src/api/session.ts:87) writes `session:${userId}` straight into the shared Redis instance with redis.set(key, token) and no SET EX argument. The same connection pool is shared with the marketing job runner introduced in #1102.\n\nWhy it matters: sessions never expire so a stolen token is valid forever, and the marketing runner can read every active session via SCAN. Two tenants on the same cluster will overwrite each other's sessions because user ids are not globally unique across tenants in this codebase (verified in `getUserById`).\n\nSuggested direction: namespace the key with tenant id (`t:${tenantId}:session:${userId}`), use SET ... EX <ttl>, and move sessions to a dedicated logical DB or a separate Redis with auth. Add an integration test that two tenants with the same numeric user id do not collide.\n\nNeeds verification: confirm whether the marketing job runner has SCAN access; if so, this is exploitable today.",
+    "suggestion": {
+      "body": "// src/api/session.ts\nconst SESSION_TTL_SECONDS = 60 * 60 * 8 // 8h\nconst sessionKey = (tenantId: string, userId: string) => `t:${tenantId}:session:${userId}`\n\nexport async function createSession(tenantId: string, userId: string, token: string) {\n  await redis.set(sessionKey(tenantId, userId), token, 'EX', SESSION_TTL_SECONDS)\n}",
+      "startLine": 80,
+      "endLine": 95
+    },
+    "domain": "security"
+  },
+  {
+    "id": "bugs-1",
+    "file": "src/cache/invalidation.ts",
+    "line": 142,
+    "severity": "high",
+    "risk": {
+      "impact": "high",
+      "likelihood": "likely",
+      "confidence": "high",
+      "action": "must-fix"
+    },
+    "title": "invalidate() reads the cache version then writes it back without atomicity, two concurrent invalidations drop the second one",
+    "description": "Observation: invalidate() reads cache.version (src/cache/invalidation.ts:142), increments it locally, then writes it back with cache.setVersion(v + 1). Two concurrent invalidations triggered by webhooks both read v=4, both write v=5, and the second invalidation is silently lost.\n\nWhy it matters: stale entries continue serving for the next read window (up to 30s), which the team has previously flagged as the root cause of two billing incidents this quarter. The pattern is easy to miss because it only fails under burst load.\n\nSuggested direction: replace the read-then-write with redis.incr on the version key (atomic at the Redis level), or wrap the read/write in WATCH/MULTI. Add a load test that fires 50 parallel invalidations and asserts the final version is exactly initial + 50.",
+    "suggestion": {
+      "body": "// src/cache/invalidation.ts\nconst newVersion = await redis.incr(versionKey)\nreturn newVersion",
+      "startLine": 140,
+      "endLine": 150
+    },
+    "domain": "bugs"
+  },
+  {
+    "id": "perf-1",
+    "file": "src/dashboard/recent-activity.tsx",
+    "line": 58,
+    "severity": "high",
+    "risk": {
+      "impact": "high",
+      "likelihood": "possible",
+      "confidence": "medium",
+      "action": "should-fix"
+    },
+    "title": "RecentActivity rebuilds the entire timeline on every keystroke in the unrelated search box",
+    "description": "Observation: RecentActivity (src/dashboard/recent-activity.tsx:58) recomputes `timeline = events.map(toTimelineEntry).sort(byRecency)` inline in the render, with `events` coming from the parent Dashboard component whose state includes the search box value.\n\nWhy it matters: with the production median of ~3200 events per workspace, every keystroke in the search box rebuilds the whole timeline and re-renders 200+ TimelineRow components. Lighthouse traces show 380ms of scripting per keystroke on a mid-tier laptop.\n\nSuggested direction: move the search input into its own component, memoize `timeline` with useMemo keyed on events, or hoist the timeline into a selector. The fix is small but the impact is felt on every dashboard interaction.",
+    "domain": "performance"
+  },
+  {
+    "id": "code-smells-1",
+    "file": "src/lib/parser.ts",
+    "line": 156,
+    "severity": "medium",
+    "risk": {
+      "impact": "medium",
+      "likelihood": "possible",
+      "confidence": "high",
+      "action": "should-fix"
+    },
+    "title": "Three near-identical parseX functions diverge in their error handling for the same edge case",
+    "description": "Observation: parseHeader (src/lib/parser.ts:156), parseFooter (line 198), and parseBody (line 240) all handle the empty-line case differently: parseHeader returns null, parseFooter throws, parseBody returns an empty object. All three are called from the same dispatch loop in normalize().\n\nWhy it matters: the dispatch loop swallows the parseFooter throw inside a try/catch added in this PR (line 88), so currently parseFooter silently becomes \"no result\". Future authors adding a fourth parser will have no obvious convention to follow and the loop's catch will hide whatever they pick.\n\nSuggested direction: extract a shared parseSection(label, lines) helper that returns Result<Section, ParseError>, replace the three functions with thin wrappers, and remove the swallowing catch from normalize(). This is one of those refactors that gets harder every release.",
+    "domain": "code-smells"
+  },
+  {
+    "id": "arch-1",
+    "file": "src/services/auth/index.ts",
+    "line": 24,
+    "severity": "medium",
+    "risk": {
+      "impact": "medium",
+      "likelihood": "likely",
+      "confidence": "high",
+      "action": "should-fix"
+    },
+    "title": "AuthService now imports from src/db/users directly, breaking the layered architecture set up last quarter",
+    "description": "Observation: AuthService.signIn (src/services/auth/index.ts:24) now imports `userRepo` from `src/db/users` directly to read the last-login column. Every other service goes through the `UserRepository` interface in `src/domain/user.ts` so that the storage layer can be swapped during tests.\n\nWhy it matters: this is the first service to skip the interface. Once one does it the others will follow within a few sprints, and the layering set up to make in-memory tests cheap erodes. Tests that depend on real Postgres are 20x slower than the in-memory ones.\n\nSuggested direction: route the last-login read through UserRepository.findById and add the column to the User domain type, or add a UserRepository.findLastLoginAt method to keep the projection narrow. Keep the storage import inside `src/db/`.",
+    "suggestion": {
+      "body": "// src/domain/user.ts\nexport interface UserRepository {\n  findById(id: UserId): Promise<User | null>\n  findLastLoginAt(id: UserId): Promise<Date | null>\n}\n\n// src/services/auth/index.ts\nconst lastLoginAt = await this.userRepo.findLastLoginAt(userId)",
+      "startLine": 20,
+      "endLine": 40
+    },
+    "domain": "architecture"
+  },
+  {
+    "id": "bugs-2",
+    "file": "src/utils/format-currency.ts",
+    "line": 8,
+    "severity": "medium",
+    "risk": {
+      "impact": "medium",
+      "likelihood": "edge-case",
+      "confidence": "medium",
+      "action": "should-fix"
+    },
+    "title": "formatCurrency uses toFixed(2) which loses precision on JPY, KRW, and other zero-decimal currencies",
+    "description": "formatCurrency in src/utils/format-currency.ts:8 hardcodes value.toFixed(2) and tacks on a currency symbol from a map. For JPY a payment of 1500 yen renders as ¥1500.00, which is technically wrong but harmless visually. For KRW the localization team flagged this as a translation bug in their style guide and asked us to use Intl.NumberFormat instead. The change is small and worth doing while the formatter is being touched anyway.",
+    "domain": "bugs"
+  },
+  {
+    "id": "code-smells-2",
+    "file": "src/components/Button.tsx",
+    "line": 12,
+    "severity": "low",
+    "risk": {
+      "impact": "low",
+      "likelihood": "possible",
+      "confidence": "high",
+      "action": "consider"
+    },
+    "title": "Button accepts a boolean `primary` and a boolean `danger` and a boolean `ghost`, three flags that should be one variant prop",
+    "description": "Observation: Button (src/components/Button.tsx:12) now accepts `primary`, `danger`, `ghost`, and the new `secondary` flag added in this PR. The render branches on them with a chain of ternaries and the four-flag combinatorics are not all valid (primary && danger renders as danger but consumers don't know).\n\nWhy it matters: the next variant added will make the ternary unreadable and the type system isn't preventing nonsense combinations. The fix is small now and gets worse with each addition.\n\nSuggested direction: collapse to `variant: 'primary' | 'danger' | 'ghost' | 'secondary'` (default 'primary'). Migrate callers in one sweep; the four flags only have ~40 call sites across the repo.",
+    "domain": "code-smells"
+  },
+  {
+    "id": "perf-2",
+    "file": "vendor/legacy/heavy-parser.js",
+    "line": 412,
+    "severity": "low",
+    "risk": {
+      "impact": "low",
+      "likelihood": "edge-case",
+      "confidence": "low",
+      "action": "optional"
+    },
+    "title": "Synchronous regex compilation in a hot loop, but only matters if the input crosses ~50k chars",
+    "description": "Observation: heavy-parser.js:412 compiles a regex inside the tokenize loop instead of hoisting it to module scope.\n\nWhy it matters: at the input sizes this repo actually parses today (<5k chars) the overhead is negligible (<1ms). It would matter if the parser were ever pointed at the new bulk-import payloads the team has been discussing.\n\nNeeds verification: confirm whether the bulk-import payloads actually flow through this parser; if not, this can be left alone.",
+    "domain": "performance"
+  }
+]

package/skills/magpie/fixtures/example-pr/post-status.json

@@ -0,0 +1,5 @@
+{
+  "security-1": "posted",
+  "arch-1": "posted",
+  "perf-1": { "status": "failed", "message": "HTTP 422: pull_request_review_thread: line out of diff" }
+}

package/skills/magpie/fixtures/example-pr/pr.json

@@ -0,0 +1,9 @@
+{
+  "number": 1337,
+  "title": "Migrate session store to Redis and introduce TextOnlyPrompt abstraction",
+  "author": { "login": "asha-platform" },
+  "headRefName": "feat/session-redis-and-prompts",
+  "baseRefName": "main",
+  "headRefOid": "9f3a8c0211dbb5fe7a82a2c1b08e0a45c2d1ee01",
+  "url": "https://github.com/example/repo/pull/1337"
+}

package/skills/magpie/scripts/__tests__/cli.test.ts

@@ -155,3 +155,122 @@ test('post rejects missing --ids', async () => {
   expect(exit).toBe(2)
   expect(stderr).toContain('post: missing --ids')
 })
+
+test('preview surfaces its own --help block with the stage preset list', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'preview', '--help'], { stdout: 'pipe' })
+  const stdout = await new Response(proc.stdout).text()
+  const exit = await proc.exited
+  expect(exit).toBe(0)
+  expect(stdout).toContain('Usage: magpie preview')
+  expect(stdout).toContain('--stage')
+  // Sanity-check that the preset list mentions both endpoints of the pipeline.
+  expect(stdout).toContain('fresh')
+  expect(stdout).toContain('post-done')
+})
+
+test('preview --list-stages prints every known preset, one per line', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'preview', '--list-stages'], { stdout: 'pipe' })
+  const stdout = await new Response(proc.stdout).text()
+  const exit = await proc.exited
+  expect(exit).toBe(0)
+  const presets = stdout.trim().split('\n')
+  expect(presets).toContain('fresh')
+  expect(presets).toContain('specialists-running')
+  expect(presets).toContain('peer-review-error')
+  expect(presets).toContain('report-done')
+  expect(presets).toContain('post-done')
+})
+
+test('preview --dry-run --no-open writes nothing and prints the planned paths', async () => {
+  const out = await mkdtemp(join(tmpdir(), 'magpie-cli-preview-'))
+  try {
+    // mkdtemp creates the directory; remove it so we can confirm the dry-run
+    // truly writes nothing on its own. The handler should still report it
+    // would have written here.
+    await rm(out, { recursive: true, force: true })
+    const proc = Bun.spawn(
+      ['bun', CLI, 'preview', '--dry-run', '--no-open', '--out', out, '--stage', 'critic-done'],
+      { stdout: 'pipe', stderr: 'pipe' },
+    )
+    const stdout = await new Response(proc.stdout).text()
+    const exit = await proc.exited
+    expect(exit).toBe(0)
+    const result = JSON.parse(stdout.trim())
+    expect(result.dryRun).toBe(true)
+    expect(result.outDir).toBe(out)
+    expect(result.findingsHtml).toBe(join(out, 'findings.html'))
+    expect(result.progressHtml).toBe(join(out, 'progress.html'))
+    // Dry run must not create the directory or any files inside it.
+    const findingsFile = Bun.file(join(out, 'findings.html'))
+    expect(await findingsFile.exists()).toBe(false)
+  } finally {
+    await rm(out, { recursive: true, force: true })
+  }
+})
+
+test('preview --no-open renders the requested page to disk and returns its path', async () => {
+  const out = await mkdtemp(join(tmpdir(), 'magpie-cli-preview-render-'))
+  try {
+    const proc = Bun.spawn(
+      [
+        'bun',
+        CLI,
+        'preview',
+        '--no-open',
+        '--page',
+        'progress',
+        '--stage',
+        'specialists-running',
+        '--out',
+        out,
+      ],
+      { stdout: 'pipe', stderr: 'pipe' },
+    )
+    const stdout = await new Response(proc.stdout).text()
+    const exit = await proc.exited
+    expect(exit).toBe(0)
+    const result = JSON.parse(stdout.trim())
+    expect(result.progressHtml).toBe(join(out, 'progress.html'))
+    expect(result.findingsHtml).toBeUndefined()
+    const html = await Bun.file(join(out, 'progress.html')).text()
+    // The preset has setup + context done (2/7 segments filled) and
+    // specialists running.
+    expect(html).toContain('--done-count: 2')
+    expect(html).toContain('class="step running"')
+    expect(html).toContain('data-stage="specialists"')
+  } finally {
+    await rm(out, { recursive: true, force: true })
+  }
+})
+
+test('preview rejects an unknown --stage with exit 2 and a hint', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'preview', '--no-open', '--stage', 'bogus'], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stderr = await new Response(proc.stderr).text()
+  const exit = await proc.exited
+  expect(exit).toBe(2)
+  expect(stderr).toContain('preview: invalid --stage bogus')
+  expect(stderr).toContain('--list-stages')
+})
+
+test('preview rejects an unknown --page with exit 2', async () => {
+  const proc = Bun.spawn(['bun', CLI, 'preview', '--no-open', '--page', 'sidebar'], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  const stderr = await new Response(proc.stderr).text()
+  const exit = await proc.exited
+  expect(exit).toBe(2)
+  expect(stderr).toContain('preview: invalid --page sidebar')
+})
+
+test('top-level --help surfaces the preview subcommand', async () => {
+  const proc = Bun.spawn(['bun', CLI, '--help'], { stdout: 'pipe' })
+  const stdout = await new Response(proc.stdout).text()
+  const exit = await proc.exited
+  expect(exit).toBe(0)
+  expect(stdout).toContain('preview')
+  expect(stdout).toContain('--help-preview')
+})

package/skills/magpie/scripts/__tests__/preview-cmd.test.ts

@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  DEFAULT_STAGE,
+  KNOWN_STAGE_PRESETS,
+  type PreviewResult,
+  runPreview,
+  type STAGE_PRESETS,
+} from '../preview-cmd.ts'
+
+let workDir: string
+
+beforeEach(async () => {
+  workDir = await mkdtemp(join(tmpdir(), 'magpie-preview-test-'))
+})
+
+afterEach(async () => {
+  await rm(workDir, { recursive: true, force: true })
+})
+
+// Captures any opener invocations so we can assert without spawning a real OS
+// open command in tests.
+function withCapturedOpener(): { calls: string[]; factory: () => (path: string) => Promise<void> } {
+  const calls: string[] = []
+  return {
+    calls,
+    factory: () => async (path: string) => {
+      calls.push(path)
+    },
+  }
+}
+
+test('renders both pages by default from the bundled fixture', async () => {
+  const opener = withCapturedOpener()
+  const result = await runPreview({
+    page: 'both',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openerFactory: opener.factory,
+  })
+  expect(result.findingsHtml).toBe(join(workDir, 'findings.html'))
+  expect(result.progressHtml).toBe(join(workDir, 'progress.html'))
+  const findings = await readFile(result.findingsHtml as string, 'utf8')
+  const progress = await readFile(result.progressHtml as string, 'utf8')
+  expect(findings).toContain('PR #1337')
+  expect(findings).toContain('feat/session-redis-and-prompts')
+  // The fixture covers all four severities so the breakdown line should
+  // include each one.
+  expect(findings).toContain('blocker')
+  expect(findings).toContain('high')
+  expect(findings).toContain('medium')
+  expect(findings).toContain('low')
+  expect(progress).toContain('PR #1337')
+  // Default stage is report-done so the connector should fill 7/7 segments
+  // before the final post stage.
+  expect(progress).toContain('--done-count: 7')
+})
+
+test('honors --page findings: progress is not rendered', async () => {
+  const opener = withCapturedOpener()
+  const result = await runPreview({
+    page: 'findings',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openerFactory: opener.factory,
+  })
+  expect(result.findingsHtml).toBeDefined()
+  expect(result.progressHtml).toBeUndefined()
+})
+
+test('honors --page progress: findings is not rendered', async () => {
+  const opener = withCapturedOpener()
+  const result = await runPreview({
+    page: 'progress',
+    stage: 'specialists-running',
+    outDir: workDir,
+    openerFactory: opener.factory,
+  })
+  expect(result.progressHtml).toBeDefined()
+  expect(result.findingsHtml).toBeUndefined()
+  const html = await readFile(result.progressHtml as string, 'utf8')
+  expect(html).toContain('class="step running"')
+})
+
+test('--no-open suppresses the browser opener', async () => {
+  const opener = withCapturedOpener()
+  await runPreview({
+    page: 'both',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openInBrowser: false,
+    openerFactory: opener.factory,
+  })
+  expect(opener.calls).toEqual([])
+})
+
+test('opener is called with the findings path when both pages are rendered', async () => {
+  const opener = withCapturedOpener()
+  const result = await runPreview({
+    page: 'both',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openInBrowser: true,
+    openerFactory: opener.factory,
+  })
+  expect(opener.calls).toEqual([result.findingsHtml as string])
+  expect(result.opened).toBe(result.findingsHtml)
+})
+
+test('dry-run returns the planned paths without writing files', async () => {
+  const opener = withCapturedOpener()
+  const result = await runPreview({
+    page: 'both',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    dryRun: true,
+    openerFactory: opener.factory,
+  })
+  expect(result.dryRun).toBe(true)
+  expect(result.findingsHtml).toBe(join(workDir, 'findings.html'))
+  expect(opener.calls).toEqual([])
+  // Nothing should have been created in workDir.
+  let createdAnyway = false
+  try {
+    await readFile(join(workDir, 'findings.html'), 'utf8')
+    createdAnyway = true
+  } catch {
+    // expected
+  }
+  expect(createdAnyway).toBe(false)
+})
+
+test('every stage preset is renderable end-to-end', async () => {
+  for (const stage of KNOWN_STAGE_PRESETS) {
+    const stageDir = join(workDir, stage)
+    const opener = withCapturedOpener()
+    const result: PreviewResult = await runPreview({
+      page: 'progress',
+      stage,
+      outDir: stageDir,
+      openInBrowser: false,
+      openerFactory: opener.factory,
+    })
+    const html = await readFile(result.progressHtml as string, 'utf8')
+    expect(html).toContain('class="pipeline"')
+  }
+})
+
+test('--done-count in the progress page reflects the chosen preset', async () => {
+  const cases: Array<{ stage: keyof typeof STAGE_PRESETS; expectedDone: number }> = [
+    { stage: 'fresh', expectedDone: 0 },
+    { stage: 'setup-done', expectedDone: 1 },
+    { stage: 'specialists-done', expectedDone: 3 },
+    { stage: 'critic-done', expectedDone: 5 },
+    { stage: 'report-done', expectedDone: 7 },
+    { stage: 'post-done', expectedDone: 8 },
+  ]
+  for (const { stage, expectedDone } of cases) {
+    const stageDir = join(workDir, stage)
+    await runPreview({
+      page: 'progress',
+      stage,
+      outDir: stageDir,
+      openInBrowser: false,
+    })
+    const html = await readFile(join(stageDir, 'progress.html'), 'utf8')
+    expect(html).toContain(`--done-count: ${expectedDone}`)
+  }
+})
+
+test('peer-review-error preset surfaces the error step in the rendered HTML', async () => {
+  await runPreview({
+    page: 'progress',
+    stage: 'peer-review-error',
+    outDir: workDir,
+    openInBrowser: false,
+  })
+  const html = await readFile(join(workDir, 'progress.html'), 'utf8')
+  expect(html).toContain('class="step error"')
+  expect(html).toContain('data-stage="peer-review"')
+})
+
+test('mixed post-status in the fixture surfaces both posted and failed badges', async () => {
+  await runPreview({
+    page: 'findings',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openInBrowser: false,
+  })
+  const html = await readFile(join(workDir, 'findings.html'), 'utf8')
+  expect(html).toContain('class="badge posted"')
+  expect(html).toContain('class="badge failed"')
+  // The fixture's failed entry includes a 422 message; make sure it survives.
+  expect(html).toContain('422')
+})
+
+test('bundled fixture covers all five focus domains', async () => {
+  await runPreview({
+    page: 'findings',
+    stage: DEFAULT_STAGE,
+    outDir: workDir,
+    openInBrowser: false,
+  })
+  const html = await readFile(join(workDir, 'findings.html'), 'utf8')
+  for (const domain of ['security', 'bugs', 'performance', 'code-smells', 'architecture']) {
+    expect(html).toContain(`data-filter-value="${domain}"`)
+  }
+})