jackherd 1.8.1 → 1.9.0

package/src/plans/texts.ts

@@ -3,13 +3,13 @@ import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from '.
 import { shownWithMore } from './shown-with-more'
 import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
-/** The words of an open lane: its section labels, the age of a running phase, the wave, the finished phases not merged yet, and the pointer of a phase with only its review gate open. */
+/** The words of an open lane: the age of a running phase, the word before the open phases that wait, the finished phases not merged yet, and the pointer of a phase with only its review gate open. */
 export type HerdTexts = {
-  sections: { session: string; chips: string; now: string; next: string; later: string; done: string }
   minutesAgo: (minutes: number) => string
-  wave: (wave: number) => string
+  next: string
   notMerged: string
   reviewGate: string
+  gate: string
 }
 
 /**
@@ -24,6 +24,8 @@ export type PlanTexts = {
   noWorktree: string
   noRow: string
   notInPlan: string
+  /** Before a task an agent reports that no task of the plan names. */
+  now: string
   /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
   allButDocs: string
   tickedSummary: (count: number) => string
@@ -64,6 +66,7 @@ export const boardTexts = (term: string) => ({
   pageNotWritten: (reason: string) => `${term} page not written: ${reason}`,
   pageNotOpenedReason: (reason: string) => `${term} page: ${reason}`,
   notReadable: (reason: string) => `${term} not readable: ${reason}`,
+  notOpened: (reason: string) => `could not open: ${reason}`,
 })
 
 const ALL_BUT_DOCS = 'docs open'
@@ -76,17 +79,18 @@ export const TEXTS: PlanTexts = {
   noWorktree: 'no worktree',
   noRow: 'no row in lanes',
   notInPlan: 'not in the plan',
+  now: 'now:',
   allButDocs: ALL_BUT_DOCS,
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
   draft: 'draft · ',
   privateLink: 'private',
   phaseTally: (done, total) => (total > 0 ? `${done}/${total} ph` : ''),
   herd: {
-    sections: { session: 'SESSION', chips: '📎', now: 'NOW', next: 'NEXT', later: 'LATER', done: 'DONE' },
     minutesAgo: (minutes) => (minutes === 0 ? '· just now' : `· ${minutes} min ago`),
-    wave: (wave) => `wave ${wave}:`,
+    next: 'next',
     notMerged: 'not merged',
     reviewGate: 'Review gate',
+    gate: '· gate',
   },
   planned: (phases, plans) =>
     `planned (${phases} ${phases === 1 ? 'phase' : 'phases'} in ${plans} ${plans === 1 ? 'plan' : 'plans'})`,
@@ -98,12 +102,13 @@ export const TEXTS: PlanTexts = {
   },
   hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
   legend: [
-    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
-    `▸ ▾ open and close · NOW ▶ the phases whose boxes or task lines moved in the last ${STALE_ACTIVITY_MINUTES} min, the one moved last first, · n min ago since then, → the task each is on (Review gate = only its review gate is open) · NEXT the next wave · LATER the other open phases · DONE ✓ the finished ones, not merged = ticked in the worktree, not on the base branch yet · ${ALL_BUT_DOCS} = only the documentation box is open · the lane line names the phase moved last · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
-    `◐ progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
-    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status under 📎, 📡 <n> in amber on a folded lane when tickets are new',
-    "SESSION: the agent's title · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main",
+    'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a link chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
+    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · • state unknown · only blocked wears its word in the lane line, the symbol says the rest · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · a working or blocked lane opens by itself only when it first appears, after that → ← and clicks are yours alone',
+    `▸ ▾ open and close · an open lane's branches, top down: the agent's title and ⎇ its branch, ↗ its pull requests, its link chips, the phases it works on, next, ✓ · a lane shows only the phases its board rows name · a phase row = some of its tasks are ticked, one of its boxes was ticked in the last ${STALE_ACTIVITY_MINUTES} min, or an agent reports working on it, by number · n min ago since the last tick or report, · gate = only the review gate is open · ▶ teal = a task an agent reported (its task list or jh task; its name dim at the right edge when several agents work in the lane), ▷ dim = only guessed from the words of its log · now: <text> = a reported task no plan task names · next = the other open phases, as ranges · ✓ the finished ones, not merged = ticked in the worktree, not on the base branch yet · ${ALL_BUT_DOCS} = only the documentation box is open · a folded lane line names the phase moved last, +n more active ones, and its count · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
+    `the bar = progress over the lane's plans · n/m = m checkboxes, n ticked · n/m ph = n of m phases finished · n/n in green = all ticked · 🥣 share of the context window used, on a folded lane only once it warns · Sonnet ${MODEL_MARK.differs} Opus in amber = the phase's subagent ran on another model than the plan's`,
+    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status among the link chips, 📡 <n> in amber on a folded lane when tickets are new',
+    '▌ on top = waits for your answer: 📎 a file or an Artifact that was sent (click: a cut-off row expands, then it opens), ? a question of the board · it goes when the board row is closed or `jh waiting close <id>` · woof closes the block',
+    '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
   ],
 }
 

package/src/plans/unlisted-lanes.ts

@@ -2,8 +2,8 @@ import { isAbsolute, relative, sep } from 'node:path'
 import type { SprintLane } from '../plan-format'
 import type { LaneAgent } from '../terminal'
 
-/** A worktree with an agent that has no row in the sprint table; `name` is its directory below the worktree directory. */
-export type UnlistedLane = { name: string; agent: LaneAgent }
+/** A worktree with an agent, or only a subagent of the coordinator, that has no row in the sprint table; `name` is its directory below the worktree directory. */
+export type UnlistedLane = { name: string; agent: LaneAgent | null }
 
 type PlacedAgent = { lane: string; agent: LaneAgent }
 
@@ -25,21 +25,26 @@ const placed = (agents: readonly LaneAgent[], worktreeDirectory: string): Placed
 
 /**
  * The lanes that run but are missing from the sprint table: one per worktree below `worktreeDirectory` with an
- * agent in it. A worktree counts as listed when the table names it, or names any agent running in it. The first
- * agent of a worktree stands for it; the lanes come in name order.
+ * agent in it, or a subagent of the coordinator at work in it (`subagentLanes`, no agent then). A worktree counts as
+ * listed when the table names it, or names any agent running in it. The first agent of a worktree stands for it; the
+ * lanes come in name order.
  */
 export const unlistedLanes = (
   agents: readonly LaneAgent[],
   listed: ReadonlySet<string>,
   worktreeDirectory: string,
+  subagentLanes: ReadonlySet<string> = new Set(),
 ): UnlistedLane[] => {
   const inWorktrees = placed(agents, worktreeDirectory)
   const listedWorktrees = new Set(
     inWorktrees.filter(({ lane, agent }) => listed.has(lane) || listed.has(agent.name)).map(({ lane }) => lane),
   )
-  const byLane = new Map<string, LaneAgent>()
+  const byLane = new Map<string, LaneAgent | null>()
   for (const { lane, agent } of inWorktrees) {
     if (!listedWorktrees.has(lane) && !byLane.has(lane)) byLane.set(lane, agent)
   }
+  for (const lane of subagentLanes) {
+    if (!listed.has(lane) && !byLane.has(lane)) byLane.set(lane, null)
+  }
   return [...byLane].sort(([left], [right]) => left.localeCompare(right)).map(([name, agent]) => ({ name, agent }))
 }

package/src/plans/view.ts

@@ -37,6 +37,8 @@ export const renderSnapshot = (
       planned: snapshot.planned,
       watch: snapshot.watch,
       watchesTickets: snapshot.watchesTickets,
+      awaiting: snapshot.waiting,
+      unplaced: snapshot.unplaced,
     },
     selection,
     width,
@@ -45,9 +47,7 @@ export const renderSnapshot = (
 }
 
 export const startSelection = (snapshot: Snapshot, options: Options): Selection =>
-  options.lane
-    ? laneSelection(snapshot.views[0]?.progress, snapshot.views[0]?.status.agent ?? null)
-    : overviewSelection()
+  options.lane ? laneSelection(snapshot.views[0]?.progress) : overviewSelection()
 
 /** Header and footer stay put; the body shows `bodyRows` lines from `top`, padded so the footer sits at the bottom. */
 export const draw = (screen: Screen, top: number): void => {

package/src/plans/waiting-click.ts

@@ -0,0 +1,76 @@
+import type { WaitingItem } from '../plan-format/waiting'
+import { fit, wrap } from '../terminal/text'
+import { textWidth } from '../terminal/width'
+import { plain } from './layout-phase'
+import { MOUSE_BUTTON, type MouseEvent } from './selection'
+
+/** How many for-you rows the herd draws; the rest is one `+<n>` line. */
+export const SHOWN_WAITING = 5
+/** The bar and the blank that start every line of a for-you row. */
+export const WAITING_MARK = '▌'
+
+const FILE_MARK = '📎'
+const QUESTION_MARK = '?'
+const OPENABLE = /^(https?|file):\/\//
+
+/**
+ * One for-you row as drawn: its plain text lines (more than one while it is expanded), whether its text is wider than
+ * the pane (`cut`), whether it is expanded, and the address a click opens.
+ */
+export type WaitingRow = { key: string; lines: string[]; cut: boolean; expanded: boolean; url: string | null }
+
+/** What a click does: expand or fold the row (its key), open an address, or nothing (null). */
+export type WaitingClick = { toggle: string } | { open: string }
+
+/** The key of a row in the herd's expanded set: the record's id, else its text. */
+export const waitingKey = ({ id, item }: WaitingItem): string => `waiting>${id ?? item}`
+
+const roomOf = (width: number): number => Math.max(width - textWidth(`${WAITING_MARK} `), 1)
+
+const rowOf = (item: WaitingItem, expandedKeys: ReadonlySet<string>, width: number): WaitingRow => {
+  const text = `${item.kind === 'file' ? FILE_MARK : QUESTION_MARK} ${plain(item.item)}`
+  const room = roomOf(width)
+  const cut = textWidth(text) > room
+  const key = waitingKey(item)
+  const expanded = cut && expandedKeys.has(key)
+  const url = item.kind === 'file' && item.url && OPENABLE.test(item.url) ? item.url : null
+  return { key, lines: expanded ? wrap(text, room) : [fit(text, room)], cut, expanded, url }
+}
+
+/** The rows the herd draws for what waits on the user: the first five, each folded to one line unless expanded. */
+export const waitingRows = (
+  items: readonly WaitingItem[],
+  expandedKeys: ReadonlySet<string>,
+  width: number,
+): WaitingRow[] => items.slice(0, SHOWN_WAITING).map((item) => rowOf(item, expandedKeys, width))
+
+const rowAt = (rows: readonly WaitingRow[], firstLine: number, line: number): WaitingRow | null => {
+  let first = firstLine
+  for (const row of rows) {
+    if (line < first + row.lines.length) return line >= first ? row : null
+    first += row.lines.length
+  }
+  return null
+}
+
+const clickOn = ({ key, cut, expanded, url }: WaitingRow): WaitingClick | null => {
+  if (url) return cut && !expanded ? { toggle: key } : { open: url }
+  return cut ? { toggle: key } : null
+}
+
+/**
+ * What a plain left click on the for-you block does. A row that is cut off expands on the first click; then a
+ * question folds on the next click and a file or Artifact opens. A row that fits opens its file on the first click, a
+ * question does nothing. The `+<n>` line, other lines, a click with a modifier (ctrl is left to the terminal's own link
+ * opening), a release and the wheel do nothing. `firstLine` is the screen line (0-based) of the first row, as
+ * `renderScreen` returns it.
+ */
+export const waitingClick = (
+  rows: readonly WaitingRow[],
+  firstLine: number,
+  { button, row, pressed }: Pick<MouseEvent, 'button' | 'row' | 'pressed'>,
+): WaitingClick | null => {
+  if (!pressed || button !== MOUSE_BUTTON.left) return null
+  const target = rowAt(rows, firstLine, row - 1)
+  return target ? clickOn(target) : null
+}

package/src/preview/command.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { openInBrowser } from '../terminal/open'
+import { runGh } from '../watch/gh'
+import { embedExternalImages, fetchImage } from './embed'
+import { rewriteImages } from './images'
+import { mediaTypeOf } from './open'
+import { asksForHelp, PREVIEW_USAGE, parsePreviewOptions } from './options'
+import { previewPage } from './page'
+import { renderMarkdown, repositorySlugOf } from './render'
+
+type PackageFacts = { root: string; name: string }
+
+const packageOf = (file: string): PackageFacts | null => {
+  for (let directory = dirname(file); ; directory = dirname(directory)) {
+    const manifest = join(directory, 'package.json')
+    if (existsSync(manifest)) {
+      const name = (JSON.parse(readFileSync(manifest, 'utf8')) as { name?: unknown }).name
+      if (typeof name === 'string') return { root: directory, name }
+    }
+    if (dirname(directory) === directory) return null
+  }
+}
+
+const remoteSlugOf = (directory: string): string | null => {
+  const result = Bun.spawnSync(['git', '-C', directory, 'remote', 'get-url', 'origin'], {
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  return result.exitCode === 0 ? repositorySlugOf(result.stdout.toString()) : null
+}
+
+/** Whether `file` is a regular file whose real path, links followed, lies under the real path of `root`. */
+const isRegularFileUnder = (root: string, file: string): boolean => {
+  if (!existsSync(file)) return false
+  return realpathSync(file).startsWith(`${realpathSync(root)}/`) && statSync(file).isFile()
+}
+
+/**
+ * The image at `path` under `root` as a data address; null when it is missing, no image, no regular file, or outside
+ * `root` once links are followed, so a link in the working tree cannot put a file from elsewhere into the page.
+ */
+export const inlineImage = (root: string, path: string): string | null => {
+  const file = resolve(root, path)
+  const type = mediaTypeOf(file)
+  if (type === null || !file.startsWith(`${root}/`) || !isRegularFileUnder(root, file)) return null
+  return `data:${type};base64,${readFileSync(file).toString('base64')}`
+}
+
+/**
+ * `jh preview <markdown-file> [--out <path>] [--open]`: renders the file through GitHub's markdown API and writes a
+ * page that shows it in GitHub and in npm style, light and dark, and at phone width. The package's own images come
+ * from the working tree, so the preview shows what is not published yet. External images (badges) are embedded as data addresses, so the page is complete where it may load nothing from outside; one that cannot be fetched stays linked, with one warning. Prints the path of the page; `--open`
+ * opens it. `--help` prints the usage. Exit 0 written, 1 failed (`gh` missing or not signed in, file unreadable).
+ */
+export const run = async (args: string[]): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(PREVIEW_USAGE)
+    return 0
+  }
+  try {
+    const options = parsePreviewOptions(args)
+    const file = resolve(options.file)
+    if (!existsSync(file)) throw new Error(`${options.file} does not exist`)
+    const facts = packageOf(file)
+    const html = await renderMarkdown(readFileSync(file, 'utf8'), remoteSlugOf(dirname(file)), dirname(file), runGh)
+    const own = facts ?? { root: dirname(file), name: '' }
+    const local = rewriteImages(html, own.name, (path) => inlineImage(own.root, path))
+    const { html: rewritten, failed } = await embedExternalImages(local, fetchImage)
+    if (failed > 0)
+      console.error(`${failed} external ${failed === 1 ? 'image' : 'images'} could not be embedded and stay linked`)
+    const out = resolve(options.out ?? join(tmpdir(), `jh-preview-${basename(file, '.md')}.html`))
+    writeFileSync(out, previewPage({ title: basename(file), html: rewritten }))
+    console.log(out)
+    const reason = options.open ? openInBrowser(out) : null
+    if (reason) console.error(`could not open the page: ${reason}`)
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/preview/embed.ts

@@ -0,0 +1,209 @@
+import { lookup } from 'node:dns/promises'
+import { isIPv4, isIPv6 } from 'node:net'
+import { decodedAttribute } from './images'
+
+/** An image as fetched: its media type and bytes; null when it cannot be had. */
+type FetchedImage = { type: string; bytes: Uint8Array }
+
+/** The seam the page's external images are fetched through; a test replaces it. */
+export type ImageFetch = (url: string) => Promise<FetchedImage | null>
+
+/** What fetching an image needs from the network: the addresses of a host, and one request. Tests pass their own. */
+export type ImageSeams = {
+  resolve: (host: string) => Promise<string[]>
+  request: (url: string, init: RequestInit) => Promise<Response>
+}
+
+const MAX_BYTES = 5 * 1024 * 1024
+const TIMEOUT_MS = 10_000
+const MAX_REDIRECTS = 3
+const EXTERNAL_IMAGE = /<img\b[^>]*?\ssrc="(https:\/\/[^"]+)"/g
+const REDIRECT = new Set([301, 302, 303, 307, 308])
+/** A plain image media type; anything else would be written into the page's `src` attribute unchecked. */
+const IMAGE_TYPE = /^image\/[a-z0-9.+-]+$/i
+
+/**
+ * IPv4 ranges no public image lives in: this network, private, shared (carrier NAT), loopback, link-local (cloud
+ * metadata), IETF protocol assignments, benchmarking, multicast and reserved. As [first octets, prefix length].
+ */
+const NON_PUBLIC_V4: [number, number, number][] = [
+  [0, 0, 8],
+  [10, 0, 8],
+  [100, 64, 10],
+  [127, 0, 8],
+  [169, 254, 16],
+  [172, 16, 12],
+  [192, 0, 24],
+  [192, 168, 16],
+  [198, 18, 15],
+  [224, 0, 3],
+]
+
+const v4Number = (address: string): number => address.split('.').reduce((value, part) => value * 256 + Number(part), 0)
+
+const isPublicV4 = (address: string): boolean => {
+  const value = v4Number(address)
+  return NON_PUBLIC_V4.every(([first, second, prefix]) => {
+    const network = (first * 256 + second) * 65_536
+    const size = 2 ** (32 - prefix)
+    return value < network || value >= network + size
+  })
+}
+
+/** An IPv4 address as the last two groups of an IPv6 address: `127.0.0.1` → `7f00:1`. */
+const v4AsGroups = (address: string): string => {
+  const value = v4Number(address)
+  return `${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`
+}
+
+const groupsOf = (part: string | undefined): number[] =>
+  part ? part.split(':').map((group) => Number.parseInt(group, 16)) : []
+
+/** The eight 16-bit groups of an IPv6 address, an embedded IPv4 tail included. */
+const v6Groups = (address: string): number[] => {
+  const tail = /\d+\.\d+\.\d+\.\d+$/.exec(address)?.[0]
+  const text = tail ? `${address.slice(0, -tail.length)}${v4AsGroups(tail)}` : address
+  const [head, rest] = text.split('::')
+  const left = groupsOf(head)
+  const right = groupsOf(rest)
+  return rest === undefined ? left : [...left, ...Array(8 - left.length - right.length).fill(0), ...right]
+}
+
+const v4Of = (high: number, low: number): string => [high >>> 8, high & 0xff, low >>> 8, low & 0xff].join('.')
+
+const isPublicV6 = (address: string): boolean => {
+  const groups = v6Groups(address)
+  const [first] = groups
+  const zeroPrefix = groups.slice(0, 5).every((group) => group === 0)
+  if (zeroPrefix && (groups[5] === 0xffff || groups[5] === 0)) {
+    return groups[5] === 0xffff || groups[6] !== 0 ? isPublicV4(v4Of(groups[6], groups[7])) : false
+  }
+  // Unique local fc00::/7, link-local fe80::/10, site-local fec0::/10, multicast ff00::/8.
+  return (first & 0xfe00) !== 0xfc00 && (first & 0xffc0) !== 0xfe80 && (first & 0xffc0) !== 0xfec0 && first < 0xff00
+}
+
+/** Whether an IP address is one a public host answers on; loopback, private, link-local and the like are not. */
+export const isPublicAddress = (address: string): boolean => {
+  if (isIPv4(address)) return isPublicV4(address)
+  if (isIPv6(address)) return isPublicV6(address)
+  return false
+}
+
+/** Whether the address is https and every address its host resolves to is public; none resolved is no. */
+const isFetchable = async (url: URL, resolve: ImageSeams['resolve']): Promise<boolean> => {
+  if (url.protocol !== 'https:') return false
+  const host = url.hostname.replace(/^\[(.*)\]$/, '$1')
+  const addresses = isIPv4(host) || isIPv6(host) ? [host] : await resolve(host)
+  return addresses.length > 0 && addresses.every(isPublicAddress)
+}
+
+/** The body up to `limit` bytes, read as a stream; null once it grows past it. */
+const readCapped = async (body: ReadableStream<Uint8Array> | null, limit: number): Promise<Uint8Array | null> => {
+  if (!body) return new Uint8Array()
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (let read = await reader.read(); !read.done; read = await reader.read()) {
+    size += read.value.length
+    if (size > limit) {
+      await reader.cancel()
+      return null
+    }
+    chunks.push(read.value)
+  }
+  const bytes = new Uint8Array(size)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.length
+  }
+  return bytes
+}
+
+/**
+ * The image an answer carries: a successful answer with a plain `image/<subtype>` type within the size limit, refused by its
+ * announced length before anything is read, else while it streams; null otherwise.
+ */
+export const imageFromResponse = async (response: Response): Promise<FetchedImage | null> => {
+  const type = response.headers.get('content-type')?.split(';')[0].trim().toLowerCase()
+  if (!response.ok || type === undefined || !IMAGE_TYPE.test(type)) return null
+  if (Number(response.headers.get('content-length') ?? 0) > MAX_BYTES) return null
+  const bytes = await readCapped(response.body, MAX_BYTES)
+  return bytes ? { type, bytes } : null
+}
+
+/**
+ * Fetches an image from a public https host: the host is resolved first and refused when any of its addresses is
+ * loopback, private or link-local, redirects are followed by hand (at most three), each target checked the same way.
+ * Null for any refusal or failure. Resolving and requesting are two lookups, so a host that changes its answer between
+ * them (DNS rebinding) is not caught; the page is a local preview, which bounds what such a host could read.
+ */
+export const fetchImageWith = async (
+  address: string,
+  { resolve, request }: ImageSeams,
+): Promise<FetchedImage | null> => {
+  let url = new URL(address)
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop += 1) {
+    if (!(await isFetchable(url, resolve))) return null
+    const response = await request(url.href, { redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS) })
+    const location = response.headers.get('location')
+    if (!REDIRECT.has(response.status)) return imageFromResponse(response)
+    if (!location) return null
+    url = new URL(location, url)
+  }
+  return null
+}
+
+const systemSeams: ImageSeams = {
+  resolve: async (host) => (await lookup(host, { all: true, verbatim: true })).map(({ address }) => address),
+  request: (url, init) => fetch(url, init),
+}
+
+/** Fetches an image over the network with a time limit; null for any failure. */
+export const fetchImage: ImageFetch = async (url) => {
+  try {
+    return await fetchImageWith(url, systemSeams)
+  } catch {
+    return null
+  }
+}
+
+const dataAddressOf = ({ type, bytes }: FetchedImage): string =>
+  `data:${type};base64,${Buffer.from(bytes).toString('base64')}`
+
+const safely = async (fetchOne: ImageFetch, url: string): Promise<FetchedImage | null> => {
+  try {
+    return await fetchOne(url)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The page with every external image (`https://…` in an `<img src>`) shown from a data address, so it is complete where
+ * a page may load nothing from outside (an Artifact's content security policy). Each address is fetched once, as the
+ * address its attribute text stands for (`&amp;` read as `&`), and replaced by its text as written. One that
+ * cannot be fetched, or answers with no plain image type, keeps its address; `failed` counts those addresses. Plain
+ * http images are left as they are.
+ */
+export const embedExternalImages = async (
+  html: string,
+  fetchOne: ImageFetch,
+): Promise<{ html: string; failed: number }> => {
+  const addresses = [...new Set([...html.matchAll(EXTERNAL_IMAGE)].map(([, address]) => address))]
+  const fetched = await Promise.all(
+    addresses.map(async (address) => [address, await safely(fetchOne, decodedAttribute(address))] as const),
+  )
+  const embedded = new Map(
+    fetched.flatMap(([address, image]) =>
+      image && IMAGE_TYPE.test(image.type) ? [[address, dataAddressOf(image)] as const] : [],
+    ),
+  )
+  return {
+    html: html.replace(EXTERNAL_IMAGE, (tag, address: string) => {
+      const data = embedded.get(address)
+      return data ? tag.replace(`src="${address}"`, `src="${data}"`) : tag
+    }),
+    failed: addresses.length - embedded.size,
+  }
+}

package/src/preview/images.ts

@@ -0,0 +1,89 @@
+import { posix } from 'node:path'
+
+/** Reads the file at a path relative to the package root as an address the page can show; null when it cannot. */
+export type LocalImage = (relativePath: string) => string | null
+
+const CAMO = /^https:\/\/camo\.githubusercontent\.com\/[0-9a-f]+\/([0-9a-f]+)$/
+const SCHEME = /^[a-z][a-z0-9+.-]*:|^\/\//i
+
+/** The address GitHub's image proxy stands for; any other address as it is. */
+const canonicalOf = (src: string): string => {
+  const hex = CAMO.exec(src)?.[1]
+  return hex ? Buffer.from(hex, 'hex').toString('utf8') : src
+}
+
+/** The path below `<package>[@version]/` of an unpkg address of the package; null for any other address. */
+const unpkgPathOf = (address: string, packageName: string): string | null => {
+  if (!URL.canParse(address)) return null
+  const { host, pathname } = new URL(address)
+  const [, name, ...rest] = pathname.split('/')
+  if (host !== 'unpkg.com' || name?.split('@')[0] !== packageName || rest.length === 0) return null
+  return posix.normalize(rest.join('/'))
+}
+
+/**
+ * The path inside the package an image address means: a relative path, or an `unpkg.com/<package>/…` address of the
+ * package itself (any version, `?` part cut off). Null for every other address.
+ */
+export const packagePathOf = (address: string, packageName: string): string | null => {
+  const clean = address.split(/[?#]/)[0]
+  const unpkg = unpkgPathOf(clean, packageName)
+  if (unpkg !== null) return unpkg
+  if (SCHEME.test(clean) || clean.startsWith('/') || clean === '') return null
+  const normalized = posix.normalize(clean)
+  return normalized.startsWith('..') ? null : normalized
+}
+
+const ENTITIES: Record<string, string> = { '&amp;': '&', '&quot;': '"', '&lt;': '<', '&gt;': '>', '&#39;': "'" }
+
+/** An attribute's text as the address it stands for, the entities GitHub's renderer writes undone. */
+export const decodedAttribute = (text: string): string =>
+  text.replace(/&(amp|quot|lt|gt|#39);/g, (entity) => ENTITIES[entity])
+
+/** An address as attribute text: nothing in it can close the attribute or open a tag. */
+const escapedAttribute = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+const attributeOf = (tag: string, name: string): string | null => {
+  const text = new RegExp(`\\s${name}="([^"]*)"`).exec(tag)?.[1]
+  return text === undefined ? null : decodedAttribute(text)
+}
+
+const withoutAttributes = (tag: string, names: readonly string[]): string =>
+  names.reduce((rest, name) => rest.replace(new RegExp(`\\s${name}="[^"]*"`, 'g'), ''), tag)
+
+/** The tag with `source` as its only address; `source` is the address itself, not attribute text, and is escaped here. */
+const withSource = (tag: string, source: string): string =>
+  withoutAttributes(tag, ['src', 'data-canonical-src']).replace(/^<img/, () => `<img src="${escapedAttribute(source)}"`)
+
+const localOrKept = (address: string, packageName: string, read: LocalImage): string => {
+  const path = packagePathOf(address, packageName)
+  return (path === null ? null : read(path)) ?? address
+}
+
+/** One `<img>` tag with its address resolved: the working tree's file for the package's own images, the original address otherwise. */
+const resolveImage = (tag: string, packageName: string, read: LocalImage): string => {
+  const address = canonicalOf(attributeOf(tag, 'data-canonical-src') ?? attributeOf(tag, 'src') ?? '')
+  return address === '' ? tag : withSource(tag, localOrKept(address, packageName, read))
+}
+
+const withClass = (tag: string, className: string): string => tag.replace(/^<img/, `<img class="${className}"`)
+
+/** `<picture>` with a dark source as two images, one shown per theme; the page switches themes itself, the browser's media query would not follow it. */
+const themedPicture = (picture: string): string => {
+  const dark = /<source[^>]*\bsrcset="([^"]+)"/.exec(picture)?.[1]
+  const image = /<img[^>]*>/.exec(picture)?.[0]
+  if (dark === undefined || image === undefined) return picture
+  const darkImage = withSource(image, decodedAttribute(dark))
+  return `${withClass(image, 'only-light')}${withClass(darkImage, 'only-dark')}`
+}
+
+/**
+ * The rendered HTML with every image shown from the working tree where it is the package's own (relative paths and
+ * `unpkg.com/<package>/…`, so an unpublished README shows its unpublished pictures) and every `<picture>` split
+ * into a light and a dark image. Other addresses stay as they are.
+ */
+export const rewriteImages = (html: string, packageName: string, read: LocalImage): string =>
+  html
+    .replace(/<picture>[\s\S]*?<\/picture>/g, themedPicture)
+    .replace(/<img\b[^>]*>/g, (tag) => resolveImage(tag, packageName, read))

package/src/preview/open.ts

@@ -0,0 +1,12 @@
+const MEDIA_TYPES: Record<string, string> = {
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+}
+
+/** The media type of an image file by its extension; null when the preview does not inline that kind of file. */
+export const mediaTypeOf = (path: string): string | null =>
+  MEDIA_TYPES[path.split('.').pop()?.toLowerCase() ?? ''] ?? null

package/src/preview/options.ts

@@ -0,0 +1,32 @@
+import { CLI_NAME } from '../version/release'
+
+/** What `jh preview` was asked for: the Markdown file, where to write the page (null: the temporary directory) and whether to open it. */
+export type PreviewOptions = { file: string; out: string | null; open: boolean }
+
+export const PREVIEW_USAGE = `usage: ${CLI_NAME} preview <markdown-file> [--out <path>] [--open]`
+
+/** Whether the command line asks for the usage: `--help` or `-h` anywhere, as the top level of `jh` reads it. */
+export const asksForHelp = (args: readonly string[]): boolean => args.includes('--help') || args.includes('-h')
+
+const usageError = (message: string): Error => new Error(`${message}\n${PREVIEW_USAGE}`)
+
+/** Reads `<file> [--out <path>] [--open]` in any order; throws on an unknown option, a missing value or a missing or second file. */
+export const parsePreviewOptions = (args: readonly string[]): PreviewOptions => {
+  const words: string[] = []
+  let out: string | null = null
+  let open = false
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--open') open = true
+    else if (arg === '--out') {
+      const value = args[i + 1]
+      if (value === undefined || value.startsWith('--')) throw usageError('--out needs a path')
+      out = value
+      i += 1
+    } else if (arg.startsWith('--')) throw usageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  if (words.length === 0) throw usageError('the Markdown file is required')
+  if (words.length > 1) throw usageError(`one file at most, got ${words.join(' ')}`)
+  return { file: words[0], out, open }
+}