@iceinvein/agent-skills 0.1.24 → 0.1.26

package/README.md

@@ -104,6 +104,7 @@ Skills that compose the other audit skills into higher-level workflows.
 | Skill | What it does |
 |-------|--------------|
 | **improve-my-codebase** | Runs every applicable audit skill in parallel against your codebase, ranks findings by convergence (multiple audits agreeing) and per-file rollup, and writes a prioritized improvement report. Default sweeps everything; positional args switch modes (`quick`, `diff`, `interactive`) or narrow scope (`focus <area>`, `module <path>`). |
+| **magpie** | Interactive PR review pipeline. Runs five parallel specialist subagents (security, bugs, performance, code-smells, architecture), dedupes findings, applies a critic rubric, peer-reviews via `codex exec`, and serves an interactive HTML report for selecting findings to post via `gh`. |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iceinvein/agent-skills",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "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/diff.patch

@@ -0,0 +1,86 @@
+diff --git a/src/api/session.ts b/src/api/session.ts
+index abc1234..def5678 100644
+--- a/src/api/session.ts
++++ b/src/api/session.ts
+@@ -80,20 +80,35 @@ function validateToken(token: string): boolean {
+   return token.length > 16
+ }
+
+-export async function createSession(userId: string, token: string) {
+-  // Session key uses tenant id for isolation
+-  const key = `session:${userId}`
+-  await redis.set(key, token)
+-  return {
+-    userId,
+-    createdAt: new Date(),
+-  }
++const SESSION_TTL_SECONDS = 60 * 60 * 8 // 8h
++const sessionKey = (tenantId: string, userId: string) => `t:${tenantId}:session:${userId}`
++
++export async function createSession(tenantId: string, userId: string, token: string) {
++  const key = sessionKey(tenantId, userId)
++  await redis.set(key, token, 'EX', SESSION_TTL_SECONDS)
++  const sessionToken = await redis.get(key)
++  return {
++    tenantId,
++    userId,
++    token: sessionToken,
++    createdAt: new Date(),
++    expiresAt: new Date(Date.now() + SESSION_TTL_SECONDS * 1000),
++  }
+ }
+
+diff --git a/src/cache/invalidation.ts b/src/cache/invalidation.ts
+index 1111111..2222222 100644
+--- a/src/cache/invalidation.ts
++++ b/src/cache/invalidation.ts
+@@ -138,10 +138,8 @@ export async function getCacheVersion(): Promise<number> {
+   return parseInt(version, 10)
+ }
+
+-export async function invalidate() {
+-  const version = await redis.get(versionKey)
+-  const newVersion = parseInt(version, 10) + 1
+-  await redis.set(versionKey, String(newVersion))
++export async function invalidate(): Promise<number> {
++  const newVersion = await redis.incr(versionKey)
+   return newVersion
+ }
+
+diff --git a/src/dashboard/recent-activity.tsx b/src/dashboard/recent-activity.tsx
+index 3333333..4444444 100644
+--- a/src/dashboard/recent-activity.tsx
++++ b/src/dashboard/recent-activity.tsx
+@@ -55,10 +55,13 @@ export interface RecentActivityProps {
+   onEventSelect?: (event: Event) => void
+ }
+
+-export function RecentActivity({ events, onEventSelect }: RecentActivityProps) {
+-  const timeline = events
+-    .map(toTimelineEntry)
+-    .sort(byRecency)
++import { useMemo } from 'react'
++
++export function RecentActivity({ events, onEventSelect }: RecentActivityProps) {
++  const timeline = useMemo(
++    () => events.map(toTimelineEntry).sort(byRecency),
++    [events]
++  )
+
+   return (
+     <div className="timeline-container">
+
+diff --git a/src/services/auth/index.ts b/src/services/auth/index.ts
+index 5555555..6666666 100644
+--- a/src/services/auth/index.ts
++++ b/src/services/auth/index.ts
+@@ -20,7 +20,8 @@ export class AuthService {
+   }
+
+   async signIn(email: string, password: string) {
+-    const user = await userDb.getUserById(email)
++    const user = await this.userRepo.findById(email)
++    const lastLoginAt = await this.userRepo.findLastLoginAt(email)
+     if (!user || !this.verifyPassword(password, user.passwordHash)) {
+       throw new Error('Invalid credentials')
+     }

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,21 @@
+{
+  "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",
+  "files": [
+    { "path": "src/api/session.ts", "additions": 42, "deletions": 18 },
+    { "path": "src/cache/invalidation.ts", "additions": 28, "deletions": 12 },
+    { "path": "src/dashboard/recent-activity.tsx", "additions": 35, "deletions": 8 },
+    { "path": "src/lib/parser.ts", "additions": 64, "deletions": 45 },
+    { "path": "src/services/auth/index.ts", "additions": 31, "deletions": 15 },
+    { "path": "src/utils/format-currency.ts", "additions": 16, "deletions": 9 },
+    { "path": "src/components/Button.tsx", "additions": 22, "deletions": 11 },
+    { "path": "vendor/legacy/heavy-parser.js", "additions": 8, "deletions": 3 },
+    { "path": "README.md", "additions": 5, "deletions": 2 },
+    { "path": "package.json", "additions": 1, "deletions": 1 }
+  ]
+}

package/skills/magpie/fixtures/fake-gh.sh

@@ -10,7 +10,16 @@ case "$1 $2" in
   "headRefOid": "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
   "baseRefOid": "cafebabecafebabecafebabecafebabecafebabe",
   "author": { "login": "octocat" },
-  "body": "Fake body"
+  "body": "Fake body",
+  "url": "https://github.com/octocat/Hello-World/pull/1234",
+  "files": [
+    {
+      "path": "src/a.ts",
+      "additions": 1,
+      "deletions": 0,
+      "changeType": "modified"
+    }
+  ]
 }
 JSON
     ;;

package/skills/magpie/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magpie",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "type": "module",
   "scripts": {

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__/diff-utils.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test'
+import { filePathMatches, parseUnifiedDiffToHunks, splitDiffByFile } from '../diff-utils.ts'
+
+const SAMPLE = `diff --git a/src/a.ts b/src/a.ts
+index abc..def 100644
+--- a/src/a.ts
++++ b/src/a.ts
+@@ -1,3 +1,4 @@
+ line1
+-old
++new
++added
+ line3
+diff --git a/src/b.ts b/src/b.ts
+new file mode 100644
+--- /dev/null
++++ b/src/b.ts
+@@ -0,0 +1,2 @@
++first
++second
+`
+
+describe('parseUnifiedDiffToHunks', () => {
+  test('parses a single-file two-hunk diff', () => {
+    const single = SAMPLE.split('diff --git a/src/b.ts')[0] ?? ''
+    const hunks = parseUnifiedDiffToHunks(single)
+    expect(hunks).toHaveLength(1)
+    const hunk = hunks[0]
+    if (!hunk) throw new Error('expected one hunk')
+    expect(hunk.oldStart).toBe(1)
+    expect(hunk.newStart).toBe(1)
+    expect(hunk.lines).toHaveLength(5)
+    const types = hunk.lines.map((l) => l.type)
+    expect(types).toEqual(['context', 'removed', 'added', 'added', 'context'])
+  })
+
+  test('assigns new line numbers only to added and context lines', () => {
+    const single = SAMPLE.split('diff --git a/src/b.ts')[0] ?? ''
+    const hunks = parseUnifiedDiffToHunks(single)
+    const hunk = hunks[0]
+    if (!hunk) throw new Error('expected one hunk')
+    const lines = hunk.lines
+    expect(lines[0]?.newLineNo).toBe(1)
+    expect(lines[1]?.newLineNo).toBeNull()
+    expect(lines[2]?.newLineNo).toBe(2)
+    expect(lines[3]?.newLineNo).toBe(3)
+    expect(lines[4]?.newLineNo).toBe(4)
+  })
+
+  test('assigns old line numbers only to removed and context lines', () => {
+    const single = SAMPLE.split('diff --git a/src/b.ts')[0] ?? ''
+    const hunks = parseUnifiedDiffToHunks(single)
+    const hunk = hunks[0]
+    if (!hunk) throw new Error('expected one hunk')
+    const lines = hunk.lines
+    expect(lines[0]?.oldLineNo).toBe(1)
+    expect(lines[1]?.oldLineNo).toBe(2)
+    expect(lines[2]?.oldLineNo).toBeNull()
+    expect(lines[3]?.oldLineNo).toBeNull()
+    expect(lines[4]?.oldLineNo).toBe(3)
+  })
+
+  test('returns empty array for empty input', () => {
+    expect(parseUnifiedDiffToHunks('')).toEqual([])
+  })
+
+  test('handles "no newline at end of file" marker by ignoring it', () => {
+    const diff = `--- a/x
++++ b/x
+@@ -1 +1 @@
+-old
+\
++new
+\
+`
+    const hunks = parseUnifiedDiffToHunks(diff)
+    const hunk = hunks[0]
+    if (!hunk) throw new Error('expected one hunk')
+    expect(hunk.lines.map((l) => l.type)).toEqual(['removed', 'added'])
+  })
+})
+
+describe('splitDiffByFile', () => {
+  test('returns one entry per file using the "b/" path', () => {
+    const m = splitDiffByFile(SAMPLE)
+    expect(m.size).toBe(2)
+    expect(m.get('src/a.ts')).toContain('@@ -1,3 +1,4 @@')
+    expect(m.get('src/b.ts')).toContain('@@ -0,0 +1,2 @@')
+  })
+
+  test('returns empty map for empty input', () => {
+    expect(splitDiffByFile('').size).toBe(0)
+  })
+})
+
+describe('filePathMatches', () => {
+  test('exact match', () => {
+    expect(filePathMatches('src/a.ts', 'src/a.ts')).toBe(true)
+  })
+  test('tolerates "b/" prefix on one side', () => {
+    expect(filePathMatches('b/src/a.ts', 'src/a.ts')).toBe(true)
+  })
+  test('non-match returns false', () => {
+    expect(filePathMatches('src/a.ts', 'src/b.ts')).toBe(false)
+  })
+})