@vintasoftware/pr-review-canvas 0.1.0

package/src/server/routes/pages.ts

@@ -0,0 +1,64 @@
+import { Hono } from 'hono'
+import { type Appearance, type AppearanceQuery, appearanceForRequest } from '../../contract/settings.js'
+import type { AppContext } from '../context.js'
+import type { AppEnv } from '../env.js'
+import { AppError } from '../errors.js'
+import { homePage, reviewPage } from '../html.js'
+import { parsePrNumber } from './api.js'
+
+/** How the page is painted, rendered onto the tag so nothing flashes before the app module runs. */
+export async function appearanceFor(ctx: AppContext, query: AppearanceQuery): Promise<Appearance> {
+  return appearanceForRequest(await ctx.settings.read(), query)
+}
+
+/** The `?skin` and `?theme` of one request, which pick an appearance for that load alone. */
+export function appearanceQuery(c: { req: { query: (name: string) => string | undefined } }): AppearanceQuery {
+  return { skin: c.req.query('skin'), theme: c.req.query('theme') }
+}
+
+export function pageRoutes(ctx: AppContext): Hono<AppEnv> {
+  const app = new Hono<AppEnv>()
+
+  app.get('/', async c => {
+    const recentPrs = await ctx.prs.listRecent(10)
+    return c.html(
+      homePage(
+        {
+          recentPrs,
+          owner: ctx.config.repo.owner,
+          repo: ctx.config.repo.name,
+          version: ctx.version,
+          port: ctx.config.port,
+        },
+        c.get('cspNonce'),
+        await appearanceFor(ctx, appearanceQuery(c))
+      )
+    )
+  })
+
+  // Where the home page's form lands. It is a plain GET form, so the page needs no script of its
+  // own and the number arrives as a query parameter.
+  app.get('/review', c => {
+    const raw = c.req.query('n') ?? ''
+    return c.redirect(`/review/${encodeURIComponent(raw)}`, 303)
+  })
+
+  app.get('/review/:n', async c => {
+    const raw = c.req.param('n')
+    let prNumber: number
+    try {
+      prNumber = parsePrNumber(raw)
+    } catch {
+      throw new AppError('BAD_REQUEST', `"${raw}" is not a pull request number`, 400, 'use /review/<number>')
+    }
+    return c.html(
+      reviewPage(
+        { prNumber, owner: ctx.config.repo.owner, repo: ctx.config.repo.name, version: ctx.version },
+        c.get('cspNonce'),
+        await appearanceFor(ctx, appearanceQuery(c))
+      )
+    )
+  })
+
+  return app
+}

package/src/server/routes/review-routes.ts

@@ -0,0 +1,245 @@
+// The routes that write: local review state, and the three things the tool posts to GitHub.
+import { Hono } from 'hono'
+import { z } from 'zod'
+import type { ReviewBodyResponse, StateResponse } from '../../contract/api.js'
+import { PostCommentInputSchema, type PostCommentResult } from '../../contract/comments.js'
+import type { Pr, ReviewArtifact } from '../../contract/review-artifact.js'
+import { checkInlineTarget, postComment } from '../../github/post-comment.js'
+import { PostReviewInputSchema, postReview } from '../../github/post-review.js'
+import { buildReviewBody, stateForHead, unreviewedLayers } from '../../github/review-body.js'
+import { isReviewedId } from '../../store/state-store.js'
+import type { PrLoader } from '../bundle.js'
+import type { AppContext } from '../context.js'
+import { AppError } from '../errors.js'
+import { parsePrNumber } from './api.js'
+
+const ReviewedBodySchema = z.object({
+  reviewed: z.boolean(),
+  /** The commit the page was showing; a mark made on another commit is refused. */
+  headSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
+})
+const DismissedBodySchema = z.object({ dismissed: z.boolean(), reason: z.string().max(500).optional() })
+const HiddenBodySchema = z.object({ hidden: z.boolean() })
+
+/**
+ * The page says which commit it was showing. When the pull request has moved on, the post is
+ * refused instead of landing on code the reader never saw.
+ */
+function requireSameHead(expected: string | undefined, current: string): void {
+  if (expected !== undefined && expected !== current) {
+    throw new AppError(
+      'CANVAS_STALE',
+      'the pull request has a new head commit since this page was drawn',
+      409,
+      'reload the page and try again'
+    )
+  }
+}
+
+/** A JSON body the route can read, or a 400 that says what shape it expected. */
+async function readBody<T>(request: Request, schema: z.ZodType<T>, expected: string): Promise<T> {
+  let raw: unknown
+  try {
+    raw = await request.json()
+  } catch {
+    throw new AppError('BAD_REQUEST', `send a JSON body: ${expected}`, 400)
+  }
+  const parsed = schema.safeParse(raw)
+  if (!parsed.success) {
+    throw new AppError('BAD_REQUEST', `send a JSON body: ${expected}`, 400, parsed.error.issues[0]?.message)
+  }
+  return parsed.data
+}
+
+/** The canvas the reviewer is signing off on: the one written for the pull request's head. */
+async function artifactForHead(ctx: AppContext, number: number, pr: Pr): Promise<ReviewArtifact> {
+  if (ctx.fixtureArtifact !== null) {
+    return { ...ctx.fixtureArtifact, pr }
+  }
+  const found = await ctx.canvases.findForPr(number, pr.headSha)
+  if (found.status !== 'ready') {
+    throw new AppError(
+      'SIGNOFF_INCOMPLETE',
+      'the canvas on screen was generated for another commit',
+      409,
+      'regenerate the canvas for the current head, then review its layers'
+    )
+  }
+  const artifact = await ctx.canvases.readArtifact(found.headSha)
+  if (artifact === null) {
+    throw new AppError('CANVAS_NOT_FOUND', `no canvas for pull request ${number}`, 404, 'generate one first')
+  }
+  return artifact
+}
+
+export function reviewRoutes(ctx: AppContext, loader: PrLoader): Hono {
+  const api = new Hono()
+
+  /** Posting is refused here as well as in the UI, so a stale page cannot post either. */
+  const requirePosting = async (): Promise<void> => {
+    const caps = await ctx.capabilities.get()
+    if (caps.canComment === false) {
+      throw new AppError(
+        'COMMENT_FORBIDDEN',
+        caps.reason ?? 'this GitHub login cannot post on this repository',
+        403,
+        caps.hint
+      )
+    }
+  }
+
+  const stateBody = (number: number, state: StateResponse['state']): StateResponse => ({ prNumber: number, state })
+
+  api.get('/prs/:n/state', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    return c.json(stateBody(number, await ctx.state.read(number)))
+  })
+
+  api.put('/prs/:n/reviewed/:id{.+}', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const id = c.req.param('id')
+    if (!isReviewedId(id)) {
+      throw new AppError('BAD_REQUEST', `not a reviewed id: ${id}`, 400, 'use layer:<id> or layer:<id>/file:<key>')
+    }
+    const body = await readBody(c.req.raw, ReviewedBodySchema, '{ "reviewed": true }')
+    const pr = await loader.currentPr(number)
+    requireSameHead(body.headSha, pr.headSha)
+    return c.json(stateBody(number, await ctx.state.setReviewed(number, id, body.reviewed, pr.headSha)))
+  })
+
+  api.put('/prs/:n/points/:fingerprint/dismissed', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const fingerprint = c.req.param('fingerprint')
+    const body = await readBody(c.req.raw, DismissedBodySchema, '{ "dismissed": true, "reason": "…" }')
+    const next = await ctx.state.setDismissed(number, fingerprint, body.dismissed, body.reason)
+    return c.json(stateBody(number, next))
+  })
+
+  api.put('/prs/:n/threads/:rootCommentId/hidden', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const rootId = z.coerce.number().int().positive().safeParse(c.req.param('rootCommentId'))
+    if (!rootId.success) {
+      throw new AppError('BAD_REQUEST', 'the thread id is the numeric id of its first comment', 400)
+    }
+    const { hidden } = await readBody(c.req.raw, HiddenBodySchema, '{ "hidden": true }')
+    return c.json(stateBody(number, await ctx.state.setThreadHidden(number, rootId.data, hidden)))
+  })
+
+  api.get('/prs/:n/capabilities', async c => {
+    parsePrNumber(c.req.param('n'))
+    return c.json(await ctx.capabilities.get({ refresh: c.req.query('refresh') === '1' }))
+  })
+
+  api.post('/prs/:n/comments', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const input = await readBody(c.req.raw, PostCommentInputSchema, 'an inline, reply, or issue comment')
+    await requirePosting()
+    const pr = await loader.currentPr(number)
+    requireSameHead(input.headSha, pr.headSha)
+    if (input.kind === 'inline') {
+      const derived = await ctx.derived.read(pr.headSha)
+      if (derived === null) {
+        throw new AppError(
+          'NOT_FOUND',
+          'the diff of this head is not available locally, so the line cannot be checked',
+          404,
+          'fetch the PR head and reload'
+        )
+      }
+      const problem = checkInlineTarget(derived.files, input)
+      if (problem !== null) {
+        throw new AppError('COMMENT_LINE_NOT_IN_DIFF', problem, 422, 'comment on a line the diff shows')
+      }
+    }
+    const posted = await postComment(ctx.gh, ctx.config.repo, number, pr.headSha, input)
+    await appendComment(ctx, number, posted)
+    const entry =
+      input.kind === 'inline' && input.pointFingerprint !== undefined
+        ? { commentId: posted.comment.id, pointFingerprint: input.pointFingerprint }
+        : { commentId: posted.comment.id }
+    const state = await ctx.state.addPosted(number, entry)
+    return c.json({ ...posted, state }, 201)
+  })
+
+  api.get('/prs/:n/review/body', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const pr = await loader.currentPr(number)
+    const artifact = await artifactForHead(ctx, number, pr)
+    const state = stateForHead(await ctx.state.read(number), pr.headSha)
+    const comments = (await ctx.prs.readComments(number)) ?? (await loader.refreshComments(number)).comments
+    const body: ReviewBodyResponse = {
+      headSha: pr.headSha,
+      body: buildReviewBody({ artifact, state, comments, headSha: pr.headSha }),
+      unreviewed: unreviewedLayers(artifact, state).map(l => l.title),
+    }
+    return c.json(body)
+  })
+
+  api.post('/prs/:n/review', async c => {
+    const number = parsePrNumber(c.req.param('n'))
+    const input = await readBody(c.req.raw, PostReviewInputSchema, '{ "event": "APPROVE" }')
+    await requirePosting()
+    const pr = await loader.currentPr(number)
+    requireSameHead(input.headSha, pr.headSha)
+    const artifact = await artifactForHead(ctx, number, pr)
+    const state = stateForHead(await ctx.state.read(number), pr.headSha)
+    if (input.event === 'APPROVE') {
+      const missing = unreviewedLayers(artifact, state)
+      if (missing.length > 0) {
+        throw new AppError(
+          'SIGNOFF_INCOMPLETE',
+          `${missing.length} ${missing.length === 1 ? 'layer is' : 'layers are'} not reviewed yet`,
+          409,
+          missing.map(l => l.title).join(', ')
+        )
+      }
+    }
+    const comments = (await ctx.prs.readComments(number)) ?? (await loader.refreshComments(number)).comments
+    const body = input.body ?? buildReviewBody({ artifact, state, comments, headSha: pr.headSha })
+    const review = await postReview(ctx.gh, ctx.config.repo, number, pr.headSha, { event: input.event, body })
+    return c.json({ review }, 201)
+  })
+
+  return api
+}
+
+/** One append at a time per PR, so two posts that land together do not overwrite each other. */
+const appendChains = new Map<number, Promise<unknown>>()
+
+function appendComment(ctx: AppContext, number: number, posted: PostCommentResult): Promise<void> {
+  const run = () => writeAppendedComment(ctx, number, posted)
+  const chained = (appendChains.get(number) ?? Promise.resolve()).then(run, run)
+  appendChains.set(
+    number,
+    chained.catch(() => undefined)
+  )
+  return chained
+}
+
+/**
+ * Keeps the cached comments in step with what was just posted, so a reload shows it once. With
+ * nothing cached there is nothing to keep in step: the next read fetches the list from GitHub.
+ */
+async function writeAppendedComment(ctx: AppContext, number: number, posted: PostCommentResult): Promise<void> {
+  const comments = await ctx.prs.readComments(number)
+  if (comments === null) {
+    return
+  }
+  if (posted.kind === 'review') {
+    if (comments.reviewComments.some(c => c.id === posted.comment.id)) {
+      return
+    }
+    await ctx.prs.writeComments(number, {
+      ...comments,
+      reviewComments: [...comments.reviewComments, posted.comment],
+    })
+    return
+  }
+  if (comments.issueComments.some(c => c.id === posted.comment.id)) {
+    return
+  }
+  await ctx.prs.writeComments(number, { ...comments, issueComments: [...comments.issueComments, posted.comment] })
+}

package/src/server/routes/static.ts

@@ -0,0 +1,114 @@
+import { readFile, realpath, stat } from 'node:fs/promises'
+import path from 'node:path'
+import { Hono } from 'hono'
+import type { AppContext, VendorRoots } from '../context.js'
+import { AppError } from '../errors.js'
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.ico': 'image/x-icon',
+  '.txt': 'text/plain; charset=utf-8',
+}
+
+export function contentTypeFor(file: string): string {
+  return CONTENT_TYPES[path.extname(file).toLowerCase()] ?? 'application/octet-stream'
+}
+
+function under(root: string, full: string): boolean {
+  return full === root || full.startsWith(root + path.sep)
+}
+
+/**
+ * Resolves `rel` under `root`, or null when it escapes the root or is not a plain file. The
+ * real path is checked as well as the written one, so a symlink inside the root that points
+ * outside it names no file either.
+ */
+export async function resolveUnder(root: string, rel: string): Promise<string | null> {
+  let decoded: string
+  try {
+    decoded = decodeURIComponent(rel)
+  } catch {
+    // A malformed percent escape names no file.
+    return null
+  }
+  if (decoded.includes('\0')) {
+    return null
+  }
+  const full = path.resolve(root, decoded)
+  if (!under(root, full)) {
+    return null
+  }
+  try {
+    const s = await stat(full)
+    if (!s.isFile()) {
+      return null
+    }
+    const real = await realpath(full)
+    const realRoot = await realpath(root)
+    return under(realRoot, real) ? full : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The browser-side libraries, served from node_modules. Single-file libraries map to one exact
+ * file; `diff` and `mermaid` ship many ES modules with relative imports, so their directories are
+ * served as a whole (JavaScript files only). Mermaid loads the chunk of a diagram type at render
+ * time, which is why its whole `dist/` has to be reachable.
+ */
+export async function resolveVendor(roots: VendorRoots, rel: string): Promise<string | null> {
+  const exact: Record<string, string> = {
+    'marked.js': roots.marked,
+    'purify.js': roots.dompurify,
+    'highlight.js': roots.hljs,
+  }
+  const hit = exact[rel]
+  if (hit !== undefined) {
+    return resolveUnder(path.dirname(hit), path.basename(hit))
+  }
+  if (rel.startsWith('diff/') && rel.endsWith('.js')) {
+    return resolveUnder(roots.diff, rel.slice('diff/'.length))
+  }
+  if (rel.startsWith('mermaid/') && rel.endsWith('.mjs')) {
+    return resolveUnder(roots.mermaid, rel.slice('mermaid/'.length))
+  }
+  return null
+}
+
+export function staticRoutes(ctx: AppContext): Hono {
+  const app = new Hono()
+
+  async function send(file: string, cache: string): Promise<Response> {
+    const body = await readFile(file)
+    return new Response(new Uint8Array(body), {
+      headers: { 'content-type': contentTypeFor(file), 'cache-control': cache },
+    })
+  }
+
+  app.get('/static/*', async c => {
+    const rel = c.req.path.slice('/static/'.length)
+    const file = await resolveUnder(ctx.staticDir, rel)
+    if (file === null) {
+      throw new AppError('NOT_FOUND', `no static file ${rel}`, 404)
+    }
+    return send(file, 'no-cache')
+  })
+
+  app.get('/vendor/*', async c => {
+    const rel = c.req.path.slice('/vendor/'.length)
+    const file = await resolveVendor(ctx.vendorRoots, rel)
+    if (file === null) {
+      throw new AppError('NOT_FOUND', `no vendored file ${rel}`, 404)
+    }
+    return send(file, 'public, max-age=86400')
+  })
+
+  return app
+}

package/src/server/security.ts

@@ -0,0 +1,104 @@
+import { randomBytes } from 'node:crypto'
+import type { MiddlewareHandler } from 'hono'
+import type { AppEnv } from './env.js'
+import { AppError } from './errors.js'
+
+const ALLOWED_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+/** The hostname part of a Host header (`localhost:3010` → `localhost`, `[::1]:3010` → `[::1]`). */
+export function hostnameOf(host: string): string {
+  const m = /^(\[[^\]]+\]|[^:]+)(?::\d+)?$/.exec(host.trim())
+  return m?.[1]?.toLowerCase() ?? ''
+}
+
+export function isAllowedHost(host: string | undefined): host is string {
+  return host !== undefined && ALLOWED_HOSTNAMES.has(hostnameOf(host))
+}
+
+/** Origin must name this very server. `null` (opaque origin) is rejected too. */
+export function isSameOrigin(origin: string | undefined, host: string): boolean {
+  if (origin === undefined) {
+    return true
+  }
+  let url: URL
+  try {
+    url = new URL(origin)
+  } catch {
+    return false
+  }
+  return url.host.toLowerCase() === host.toLowerCase() && isAllowedHost(url.host)
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS'])
+
+/**
+ * Two checks. The Host allowlist stops DNS rebinding: a page on an attacker's domain that
+ * resolves to 127.0.0.1 sends its own hostname. The same-origin check on state-changing methods
+ * stops cross-site requests, because this server can post to GitHub as the user.
+ */
+export const securityMiddleware: MiddlewareHandler<AppEnv> = async (c, next) => {
+  const host = c.req.header('host')
+  if (!isAllowedHost(host)) {
+    throw new AppError('FORBIDDEN_HOST', 'this server only answers to localhost', 403)
+  }
+  if (!SAFE_METHODS.has(c.req.method)) {
+    const site = c.req.header('sec-fetch-site')
+    if (site !== undefined && site !== 'same-origin' && site !== 'none') {
+      throw new AppError('CROSS_ORIGIN', 'cross-site request rejected', 403)
+    }
+    if (!isSameOrigin(c.req.header('origin'), host)) {
+      throw new AppError('CROSS_ORIGIN', 'cross-origin request rejected', 403)
+    }
+  }
+  await next()
+}
+
+/**
+ * The page's own scripts and styles, nothing else. Inline styles are allowed because the page
+ * sets dynamic values that way (progress width, layer stripe colors) and mermaid injects a style
+ * element per drawing; inline scripts are not, except the two the shell carries under its nonce.
+ */
+export function contentSecurityPolicy(nonce: string): string {
+  return [
+    "default-src 'none'",
+    `script-src 'self' 'nonce-${nonce}'`,
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: https:",
+    "font-src 'self'",
+    "connect-src 'self'",
+    "form-action 'self'",
+    "base-uri 'none'",
+    "frame-ancestors 'none'",
+    "object-src 'none'",
+  ].join('; ')
+}
+
+/** A fresh nonce per HTML response, so the shell's inline scripts run and nothing else does. */
+export function createNonce(): string {
+  return randomBytes(16).toString('base64')
+}
+
+/**
+ * Headers every answer carries. `no-store` on the API keeps PR text, comments, and canvases out
+ * of any cache; HTML pages carry the policy above.
+ */
+export function applyResponseHeaders(res: Response, path: string, nonce: string): void {
+  res.headers.set('x-content-type-options', 'nosniff')
+  res.headers.set('referrer-policy', 'no-referrer')
+  if (path.startsWith('/api/')) {
+    res.headers.set('cache-control', 'no-store')
+  }
+  if ((res.headers.get('content-type') ?? '').startsWith('text/html')) {
+    res.headers.set('content-security-policy', contentSecurityPolicy(nonce))
+  }
+}
+
+/**
+ * Puts the headers on every answer of the normal path. Errors never reach the code after
+ * `next()`, so `createApp` applies the same headers to what its error handlers build.
+ */
+export const responseHeaders: MiddlewareHandler<AppEnv> = async (c, next) => {
+  c.set('cspNonce', createNonce())
+  await next()
+  applyResponseHeaders(c.res, c.req.path, c.get('cspNonce'))
+}

package/src/server/sse.ts

@@ -0,0 +1,67 @@
+// Server-sent events, written by hand: one named event per frame, JSON in the data line.
+import type { ChatEvent } from '../contract/chat.js'
+
+export const SSE_HEADERS = {
+  'content-type': 'text/event-stream; charset=utf-8',
+  'cache-control': 'no-store',
+  connection: 'keep-alive',
+  /** Nothing between the browser and this server should buffer a stream on localhost. */
+  'x-accel-buffering': 'no',
+} as const
+
+/**
+ * One frame. A data line cannot hold a newline, so the JSON is written as one line, which
+ * `JSON.stringify` already gives.
+ */
+export function sseFrame(event: ChatEvent): string {
+  const { event: name, ...rest } = event
+  return `event: ${name}\ndata: ${JSON.stringify(rest)}\n\n`
+}
+
+/**
+ * The event stream of one chat turn as a response body.
+ *
+ * `onCancel` runs the moment the reader goes away. Asking the iterator to return is not enough on
+ * its own: an async generator queues `return()` behind a `next()` that is still waiting, so a
+ * silent agent would keep running until it spoke again.
+ */
+export function sseStream(
+  events: AsyncIterable<ChatEvent>,
+  onClose?: () => void,
+  onCancel?: () => void
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder()
+  const iterator = events[Symbol.asyncIterator]()
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      let next: IteratorResult<ChatEvent>
+      try {
+        next = await iterator.next()
+      } catch (err) {
+        controller.enqueue(
+          encoder.encode(
+            sseFrame({
+              event: 'error',
+              code: 'INTERNAL',
+              message: err instanceof Error ? err.message : String(err),
+            })
+          )
+        )
+        controller.close()
+        onClose?.()
+        return
+      }
+      if (next.done === true) {
+        controller.close()
+        onClose?.()
+        return
+      }
+      controller.enqueue(encoder.encode(sseFrame(next.value)))
+    },
+    cancel() {
+      onCancel?.()
+      void iterator.return?.(undefined)
+      onClose?.()
+    },
+  })
+}

package/src/store/atomic-json.ts

@@ -0,0 +1,68 @@
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import type { z } from 'zod'
+
+/** Writes JSON through a temp file and a rename, so a reader never sees a half-written file. */
+export async function writeJsonAtomic(file: string, value: unknown): Promise<void> {
+  return writeTextAtomic(file, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+export async function writeTextAtomic(file: string, text: string): Promise<void> {
+  await mkdir(path.dirname(file), { recursive: true })
+  const temporaryDir = await mkdtemp(`${file}.`)
+  try {
+    const tmp = path.join(temporaryDir, 'content')
+    await writeFile(tmp, text, 'utf8')
+    await rename(tmp, file)
+  } finally {
+    await rm(temporaryDir, { recursive: true, force: true })
+  }
+}
+
+/** Parsed and validated JSON, or null when the file does not exist. Invalid content throws. */
+export async function readJson<T>(file: string, schema: z.ZodType<T>): Promise<T | null> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (err) {
+    if (isNotFound(err)) {
+      return null
+    }
+    throw err
+  }
+  return schema.parse(JSON.parse(text))
+}
+
+/**
+ * Like readJson, but a missing file, invalid JSON, or a shape the schema rejects all return
+ * `fallback()`. Other read errors still throw.
+ */
+export async function readJsonOrDefault<T, D>(file: string, schema: z.ZodType<T>, fallback: () => D): Promise<T | D> {
+  const text = await readText(file)
+  if (text === null) {
+    return fallback()
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return fallback()
+  }
+  const parsed = schema.safeParse(raw)
+  return parsed.success ? parsed.data : fallback()
+}
+
+export async function readText(file: string): Promise<string | null> {
+  try {
+    return await readFile(file, 'utf8')
+  } catch (err) {
+    if (isNotFound(err)) {
+      return null
+    }
+    throw err
+  }
+}
+
+export function isNotFound(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT'
+}