design-spine 0.1.0 → 0.2.1

package/src/lib/docker.ts

@@ -0,0 +1,196 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Matches package.json engines.bun and the pin in action.yml; a test keeps them in step.
+export const DOCKER_BUN_VERSION = '1.3.13'
+// GitHub's ubuntu-latest is x64, so captures must be too, even on Apple silicon.
+export const DOCKER_PLATFORM = 'linux/amd64'
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+export const imageTag = (playwrightVersion: string, bunVersion = DOCKER_BUN_VERSION): string =>
+  `design-spine-capture:${playwrightVersion}-bun${bunVersion}`
+
+export const dockerfileText = (
+  playwrightVersion: string,
+  bunVersion = DOCKER_BUN_VERSION,
+): string =>
+  `FROM mcr.microsoft.com/playwright:v${playwrightVersion}-noble
+COPY --from=oven/bun:${bunVersion} /usr/local/bin/bun /usr/local/bin/bun
+`
+
+/** Loopback hosts mean the host machine, which a container reaches as host.docker.internal. */
+export function rewriteBaseForDocker(base: string): string {
+  const url = new URL(base)
+  if (!LOOPBACK.has(url.hostname)) return base
+  url.hostname = 'host.docker.internal'
+  const out = url.href
+  const bare = url.pathname === '/' && !url.search && !url.hash
+  return bare && !base.endsWith('/') ? out.slice(0, -1) : out
+}
+
+export function installedPlaywrightVersion(): string {
+  const pkg = createRequire(import.meta.url)('playwright/package.json') as { version: string }
+  return pkg.version
+}
+
+export interface CliLocation {
+  /** Extra `-v` mount for a CLI that lives outside the project root. */
+  mounts: string[]
+  /** CLI path as seen inside the container. */
+  path: string
+}
+
+export function locateCli(root: string, cliFile: string, packageDir: string): CliLocation {
+  const rel = relative(root, cliFile)
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel))
+    return { mounts: [], path: `/work/${rel.split(sep).join('/')}` }
+  return {
+    mounts: ['-v', `${packageDir}:/spine:ro`],
+    path: `/spine/${relative(packageDir, cliFile).split(sep).join('/')}`,
+  }
+}
+
+export interface InnerCapture {
+  manifest: string
+  base: string
+  routes?: string
+  concurrency: string
+}
+
+export function innerCaptureArgs(o: InnerCapture): string[] {
+  return [
+    'capture',
+    '--manifest',
+    o.manifest,
+    '--base',
+    o.base,
+    ...(o.routes ? ['--routes', o.routes] : []),
+    '--concurrency',
+    o.concurrency,
+  ]
+}
+
+export interface RunArgvInput {
+  image: string
+  root: string
+  cli: CliLocation
+  recordedBase: string
+  inner: string[]
+  /** Set on Linux hosts so files written into the project stay owned by the caller. */
+  user?: { uid: number; gid: number }
+  /**
+   * Linux hosts share the host network, so an app bound only to localhost (the usual CI
+   * setup) is reachable without rewriting the URL. Docker Desktop and OrbStack use
+   * host.docker.internal instead.
+   */
+  hostNetwork?: boolean
+}
+
+export function dockerRunArgv(i: RunArgvInput): string[] {
+  return [
+    'run',
+    '--rm',
+    '--platform',
+    DOCKER_PLATFORM,
+    '--init',
+    '--ipc=host',
+    ...(i.user ? ['--user', `${i.user.uid}:${i.user.gid}`, '-e', 'HOME=/tmp'] : []),
+    '-v',
+    `${i.root}:/work`,
+    ...i.cli.mounts,
+    '-w',
+    '/work',
+    ...(i.hostNetwork ? ['--network', 'host'] : ['--add-host=host.docker.internal:host-gateway']),
+    '-e',
+    'PLAYWRIGHT_BROWSERS_PATH=/ms-playwright',
+    '-e',
+    'SPINE_CWD=/work',
+    // The run keeps the URL the host used, so review and reports read the same as a host capture.
+    '-e',
+    `SPINE_RECORDED_BASE_URL=${i.recordedBase}`,
+    '-e',
+    `SPINE_HOST_ROOT=${i.root}`,
+    i.image,
+    'bun',
+    i.cli.path,
+    ...i.inner,
+  ]
+}
+
+function docker(args: string[], opts: { input?: string; quiet?: boolean } = {}) {
+  return spawnSync('docker', args, {
+    input: opts.input,
+    stdio: [
+      opts.input === undefined ? 'ignore' : 'pipe',
+      opts.quiet ? 'ignore' : 'inherit',
+      'inherit',
+    ],
+  })
+}
+
+export function assertDockerReady(): void {
+  const info = spawnSync('docker', ['info'], { stdio: 'ignore' })
+  if ((info.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT')
+    throw new Error('--docker needs the docker CLI, but `docker` is not on PATH.')
+  if (info.status !== 0)
+    throw new Error(
+      '--docker needs a running Docker daemon, but `docker info` failed. Start Docker or OrbStack.',
+    )
+}
+
+export function ensureImage(playwrightVersion: string, log: (s: string) => void): string {
+  const tag = imageTag(playwrightVersion)
+  if (docker(['image', 'inspect', tag], { quiet: true }).status === 0) return tag
+  log(`Building ${tag} (${DOCKER_PLATFORM}), first run only...`)
+  const built = docker(['build', '--platform', DOCKER_PLATFORM, '-t', tag, '-'], {
+    input: dockerfileText(playwrightVersion),
+  })
+  if (built.status !== 0) throw new Error(`docker build failed for ${tag}.`)
+  return tag
+}
+
+export interface DockerCapture extends InnerCapture {
+  root: string
+  /** Base URL as the host sees it, before the loopback rewrite. */
+  hostBase: string
+  log: (s: string) => void
+}
+
+/** Runs `spine capture` inside the pinned Playwright image and resolves to its exit code. */
+export async function captureInDocker(o: DockerCapture): Promise<number> {
+  assertDockerReady()
+  const image = ensureImage(installedPlaywrightVersion(), o.log)
+  const cliFile = realpathSync(fileURLToPath(new URL('../cli.ts', import.meta.url)))
+  const root = realpathSync(o.root)
+  const cli = locateCli(root, cliFile, dirname(dirname(cliFile)))
+  const getuid = process.getuid?.()
+  const linux = process.platform === 'linux'
+  const argv = dockerRunArgv({
+    image,
+    root,
+    cli,
+    recordedBase: o.hostBase,
+    inner: innerCaptureArgs({ ...o, base: linux ? o.base : rewriteBaseForDocker(o.base) }),
+    hostNetwork: linux,
+    user:
+      linux && getuid !== undefined
+        ? { uid: getuid, gid: process.getgid?.() ?? getuid }
+        : undefined,
+  })
+  return await new Promise<number>((done, fail) => {
+    const child = spawn('docker', argv, { stdio: 'inherit' })
+    child.on('error', fail)
+    child.on('close', (code) => done(code ?? 1))
+  })
+}
+
+/** Manifest path relative to the project root, since the container sees the root as /work. */
+export function manifestInRoot(root: string, manifest: string): string {
+  const rel = relative(root, resolve(root, manifest))
+  if (!rel || rel.startsWith('..') || isAbsolute(rel))
+    throw new Error('--docker needs the manifest inside the project root.')
+  return rel.split(sep).join('/')
+}

package/src/lib/redact.ts

@@ -0,0 +1,26 @@
+// Captured text lands in run.json, the HTML report and CI artifacts, so app-generated URLs keep
+// only origin and path: query strings, fragments and userinfo often carry tokens or signatures.
+
+/** One URL reduced to origin + path; schemes other than HTTP and WebSocket keep only the scheme. */
+export function safeUrl(raw: string): string {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    return '[unparseable url]'
+  }
+  return ['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol)
+    ? url.origin + url.pathname
+    : `${url.protocol}[redacted]`
+}
+
+const URL_IN_TEXT = /\b(?:https?|wss?):\/\/[^\s"'<>`]+/g
+const TRAILING = /[.,;:!?)\]]+$/
+
+/** Every http(s) and ws(s) URL inside free text (console messages, error strings) passed through safeUrl. */
+export function redactUrls(text: string): string {
+  return text.replace(URL_IN_TEXT, (match) => {
+    const tail = match.match(TRAILING)?.[0] ?? ''
+    return safeUrl(match.slice(0, match.length - tail.length)) + tail
+  })
+}

package/src/lib/report.ts

@@ -30,6 +30,10 @@ export function buildReport(dir: string, run: RunRecord, review: ReviewFile): st
         ...(tile.warnings ?? []),
         ...(tile.consoleErrors ?? []).map((message) => `Console: ${message}`),
         ...(tile.pageErrors ?? []).map((message) => `Page error: ${message}`),
+        ...(tile.requestErrors ?? []).map(
+          (error) =>
+            `Request: ${error.status !== undefined ? `HTTP ${error.status}` : error.failure} · ${error.resourceType} · +${error.elapsedMs} ms · ${error.url}`,
+        ),
         ...(tile.brokenImages ?? []).map((source) => `Broken image: ${source}`),
         ...(tile.textClipped ?? []).map((item) => `Possible clipped text: ${item.selector}`),
         ...(tile.overflowX ? ['Horizontal overflow'] : []),

package/src/lib/routes.ts

@@ -170,6 +170,8 @@ export function draftManifest(
     baseUrl,
     viewports: [390, 1280],
     themes: { light: 'light', dark: 'dark', method: 'localStorage', key: 'theme' },
+    // Motion and unsettled pages are the main source of false diffs; start stable.
+    capture: { animations: 'disabled', stabilityAttempts: 3 },
     initScripts: [],
     routes,
   }

package/src/lib/runs.ts

@@ -105,9 +105,14 @@ export function setLatest(root: string, runId: string): void {
 }
 
 export const loadRun = (dir: string): RunRecord => {
-  const r = readJson<RunRecord>(join(dir, 'run.json'))
-  if (!r) throw new Error(`Missing run.json in ${dir}`)
-  for (const tile of r.tiles ?? []) {
+  const path = join(dir, 'run.json')
+  const r = readStateJson<RunRecord>(path)
+  if (r === null && !existsSync(path)) throw new Error(`Missing run.json in ${dir}`)
+  // Callers index r.tiles directly, so a parseable file with the wrong shape is corruption too.
+  if (!isPlainObject(r) || (r.tiles !== undefined && !Array.isArray(r.tiles)))
+    throw new Error(`Invalid ${path}. Preserve the file and repair or remove it, then retry.`)
+  r.tiles ??= []
+  for (const tile of r.tiles) {
     // Tile files are joined onto run and baseline dirs; only plain capture names are allowed.
     if (typeof tile.file !== 'string' || !/^[A-Za-z0-9[\]._-]+\.png$/.test(tile.file))
       throw new Error(`Invalid tile file in ${join(dir, 'run.json')}: ${String(tile.file)}`)
@@ -160,4 +165,5 @@ export const isFlagged = (t: Tile): boolean =>
   t.brokenImages.length > 0 ||
   t.consoleErrors.length > 0 ||
   t.pageErrors.length > 0 ||
+  !!t.requestErrors?.length ||
   !!t.redirectedTo

package/src/lib/server.ts

@@ -3,6 +3,8 @@ import { readFileSync, realpathSync } from 'node:fs'
 import { basename, join, resolve, sep } from 'node:path'
 import { PNG } from 'pngjs'
 import UI_PATH from '../ui/index.html' with { type: 'file' }
+import UI_CSS from '../ui/review.css' with { type: 'file' }
+import UI_JS from '../ui/review.js' with { type: 'file' }
 import { buildComparisonAsync } from './comparison.ts'
 import { listRuns, selectRun } from './history.ts'
 import { buildReport } from './report.ts'
@@ -30,6 +32,18 @@ export function startReviewServer(initialRunDir: string, port: number) {
         headers: { 'content-type': 'text/html; charset=utf-8' },
       })
     }
+    if (
+      req.method === 'GET' &&
+      ['/assets/review.css', '/assets/review.js'].includes(url.pathname)
+    ) {
+      const css = url.pathname.endsWith('.css')
+      return new Response(Bun.file(String(css ? UI_CSS : UI_JS)), {
+        headers: {
+          'content-type': css ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        },
+      })
+    }
     if (req.method === 'GET' && url.pathname === '/api/report') {
       try {
         return new Response(buildReport(runDir, loadRun(runDir), loadReview(runDir)), {

package/src/lib/summary.ts

@@ -0,0 +1,70 @@
+export const SUMMARY_MARKER = '<!-- design-spine -->'
+export const SUMMARY_ROW_CAP = 50
+
+export interface SummaryInput {
+  rows: { id: string; result: string; ratio: string }[]
+  threshold: number
+  policy: string
+  gateReasons: string[]
+  /** Number of failures the CLI counted; it decides pass or fail. */
+  failed: number
+  /** Where reviewers find the full report. */
+  reportArtifact?: string
+}
+
+const RESULTS = [
+  'ok',
+  'CHANGED',
+  'new',
+  'size-changed',
+  'no-capture',
+  'modified-capture',
+  'modified-baseline',
+  'unreadable',
+]
+
+/** Ids and reasons come from user manifests, so neutralise Markdown and HTML. */
+export function escapeMarkdown(text: string): string {
+  return text
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[&\\|<>`]/g, (c) =>
+      c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : `\\${c}`,
+    )
+}
+
+export function buildSummary(input: SummaryInput): string {
+  const { rows, failed } = input
+  const counts = new Map<string, number>()
+  for (const r of rows) counts.set(r.result, (counts.get(r.result) ?? 0) + 1)
+  const kinds = [...RESULTS, ...[...counts.keys()].filter((k) => !RESULTS.includes(k))]
+  const parts = kinds
+    .filter((k) => (counts.get(k) ?? 0) > 0 || k === 'ok')
+    .map((k) => `${counts.get(k) ?? 0} ${escapeMarkdown(k)}`)
+  const lines = [
+    SUMMARY_MARKER,
+    `## Design Spine: ${failed ? 'failed' : 'passed'}`,
+    '',
+    `${rows.length} tiles (${parts.join(', ')}). Policy: ${escapeMarkdown(input.policy)}, threshold ${input.threshold}.`,
+    '',
+  ]
+  const shown = rows.filter((r) => r.result !== 'ok')
+  if (shown.length) {
+    lines.push('| Tile | Result | Ratio |', '| --- | --- | --- |')
+    for (const r of shown.slice(0, SUMMARY_ROW_CAP))
+      lines.push(
+        `| ${escapeMarkdown(r.id)} | ${escapeMarkdown(r.result)} | ${escapeMarkdown(r.ratio)} |`,
+      )
+    if (shown.length > SUMMARY_ROW_CAP) lines.push('', `and ${shown.length - SUMMARY_ROW_CAP} more`)
+    lines.push('')
+  }
+  if (input.gateReasons.length) {
+    lines.push('Strict gate reasons:', '')
+    for (const reason of input.gateReasons) lines.push(`- ${escapeMarkdown(reason)}`)
+    lines.push('')
+  }
+  lines.push(
+    `Full report with screenshots: download the \`${input.reportArtifact ?? 'design-spine-report'}\` artifact from this run.`,
+    '',
+  )
+  return lines.join('\n')
+}

package/src/lib/types.ts

@@ -66,6 +66,15 @@ export interface Tile {
   status: number
   consoleErrors: string[]
   pageErrors: string[]
+  /** First 20 failed requests observed during capture; URL credentials/query/fragment removed. */
+  requestErrors?: {
+    url: string
+    resourceType: string
+    status?: number
+    failure?: string
+    /** Milliseconds from the start of navigation until the error was observed. */
+    elapsedMs: number
+  }[]
   overflowX: boolean
   blankRegions: { count: number; boxes: Box[] }
   brokenImages: string[]

package/src/mcp.ts

@@ -0,0 +1,117 @@
+import { join } from 'node:path'
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { isFlagged, loadReview, loadRun, resolveRunDir, runIdOf } from './lib/runs.ts'
+import type { ReviewFile, RunRecord } from './lib/types.ts'
+
+/**
+ * Read-only MCP server. It only calls loaders that read (resolveRunDir, loadRun,
+ * loadReview) and registers no tool that writes, so the process cannot change a
+ * review decision. Do not import writeJson, mergeReview or setLatest here.
+ */
+
+const STATUSES = ['approved', 'rejected', 'pending'] as const
+type TileStatus = (typeof STATUSES)[number]
+
+const statusOf = (review: ReviewFile, id: string): TileStatus => {
+  const d = review.tiles[id]?.decision
+  return d === 'approve' ? 'approved' : d === 'reject' ? 'rejected' : 'pending'
+}
+
+function latest(root: string): { dir: string; run: RunRecord; review: ReviewFile } {
+  const dir = resolveRunDir(root)
+  return { dir, run: loadRun(dir), review: loadReview(dir) }
+}
+
+export function spineStatus(root: string) {
+  const { dir, run, review } = latest(root)
+  const counts = { approved: 0, rejected: 0, pending: 0 }
+  for (const t of run.tiles) counts[statusOf(review, t.id)]++
+  return {
+    runId: run.id,
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    tiles: run.tiles.length,
+    ...counts,
+    flagged: run.tiles.filter(isFlagged).length,
+    runDir: dir,
+    reviewCommand: `spine review --run ${runIdOf(dir)}`,
+  }
+}
+
+export function spineListTiles(root: string, status?: TileStatus) {
+  const { dir, run, review } = latest(root)
+  return run.tiles
+    .map((t) => ({
+      id: t.id,
+      route: t.route,
+      state: t.state,
+      viewport: t.viewport,
+      theme: t.theme,
+      imagePath: join(dir, t.file),
+      imageHash: t.imageHash ?? null,
+      status: statusOf(review, t.id),
+    }))
+    .filter((row) => !status || row.status === status)
+}
+
+const TOOLS = [
+  {
+    name: 'spine_status',
+    description:
+      'Summary of the latest design-spine run: run id and times, tile count, approved/rejected/pending counts, flagged count, run directory and the command that opens the contact sheet. Read-only.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+  {
+    name: 'spine_list_tiles',
+    description:
+      'List tiles of the latest run with route, state, viewport, theme, image path, image hash (null if not recorded) and review status. Optional status filter. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: { status: { type: 'string', enum: [...STATUSES] } },
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  },
+]
+
+const ok = (data: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(data) }] })
+const err = (message: string) => ({
+  isError: true,
+  content: [{ type: 'text' as const, text: message }],
+})
+
+export function createSpineMcpServer(root: string): Server {
+  const server = new Server(
+    { name: 'design-spine', version: '0.2.1' },
+    { capabilities: { tools: {} } },
+  )
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    try {
+      const args = (req.params.arguments ?? {}) as Record<string, unknown>
+      switch (req.params.name) {
+        case 'spine_status':
+          return ok(spineStatus(root))
+        case 'spine_list_tiles': {
+          const status = args.status
+          if (status !== undefined && !STATUSES.includes(status as TileStatus))
+            return err(`status must be one of: ${STATUSES.join(', ')}`)
+          return ok(spineListTiles(root, status as TileStatus | undefined))
+        }
+        default:
+          return err(`Unknown tool: ${req.params.name}`)
+      }
+    } catch (e) {
+      return err((e as Error).message)
+    }
+  })
+  return server
+}
+
+/** Serve over stdio. stdout carries the protocol, so nothing else may print to it. */
+export async function runMcp(root: string): Promise<void> {
+  await createSpineMcpServer(root).connect(new StdioServerTransport())
+}