jackherd 0.0.0-stage → 1.0.0

package/src/plans/link-chips.ts

@@ -0,0 +1,74 @@
+import type { LinkKind } from '../config/link-kinds'
+
+/** A link of a plan that matches a link kind, as the sprint page shows it. */
+export type LinkChip = { url: string; label: string; icon: string; private: boolean }
+
+type Found = { url: string; text: string | null; before: string; line: string }
+
+const MARKDOWN_LINK = /\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g
+const AUTOLINK = /<(https?:\/\/[^>\s]+)>/g
+const BARE_LINK = /(?<![(<\w"])(https?:\/\/[^\s)>\]]+)/g
+const LABEL_BEFORE = /\*\*([^*]+?):?\*\*:?\s*(?:[-–>]\s*)?$/
+const PRIVATE = /\bprivat/i
+const MARKS = /\*\*|`/g
+const CONTROL = /\p{Cc}/gu
+
+const linksOf = (line: string): Found[] => {
+  const found: Found[] = []
+  const take = (url: string, text: string | null, index: number) =>
+    found.push({ url, text, before: line.slice(0, index), line })
+  for (const match of line.matchAll(MARKDOWN_LINK)) take(match[2], match[1], match.index)
+  for (const match of line.matchAll(AUTOLINK)) take(match[1], null, match.index)
+  const rest = line
+    .replace(MARKDOWN_LINK, (whole) => ' '.repeat(whole.length))
+    .replace(AUTOLINK, (whole) => ' '.repeat(whole.length))
+  for (const match of rest.matchAll(BARE_LINK)) take(match[1].replace(/[.,;]+$/, ''), null, match.index)
+  return found.sort((left, right) => line.indexOf(left.url) - line.indexOf(right.url))
+}
+
+const labelOf = ({ text, before }: Found, kind: LinkKind): string => {
+  const written = text ?? LABEL_BEFORE.exec(before)?.[1]
+  return written ? written.replace(MARKS, '').replace(CONTROL, '').trim() || kind.label : kind.label
+}
+
+/**
+ * The links of a plan's text that match one of the kinds, once each and in the order they appear. The chip's
+ * text is the link text, else the bold label written before the link (`**Mockup:** <url>`), else the kind's
+ * label; a link on a line that says it is private carries that. Nothing is fetched.
+ */
+export const extractLinkChips = (markdown: string, kinds: readonly LinkKind[]): LinkChip[] => {
+  const compiled = kinds.map((kind) => ({ kind, pattern: new RegExp(kind.pattern) }))
+  const chips = new Map<string, LinkChip>()
+  for (const line of markdown.split('\n')) {
+    for (const link of linksOf(line)) {
+      const match = compiled.find(({ pattern }) => pattern.test(link.url))
+      if (!match || chips.has(link.url)) continue
+      chips.set(link.url, {
+        url: link.url,
+        label: labelOf(link, match.kind),
+        icon: match.kind.icon,
+        private: PRIVATE.test(link.line),
+      })
+    }
+  }
+  return [...chips.values()]
+}
+
+const CHIP_KEY = /^chip>(https?:\/\/.+)$/
+const PLAN_KEY = /^plan>(file:\/\/\/.+)$/
+
+/**
+ * The click target of a chip. A `file:` address is the sprint page's own (the plan chip) and gets a key of its
+ * own, so no link of a plan's text can ever be taken for it; the keys cannot collide with a lane key (`@`), a
+ * phase key or a pull request key.
+ */
+export const chipKey = (url: string): string => (url.startsWith('file:') ? `plan>${url}` : `chip>${url}`)
+
+/** The address behind the click target of a link of a plan's text: http(s) only, null for any other key. */
+export const chipUrlOf = (key: string): string | null => CHIP_KEY.exec(key)?.[1] ?? null
+
+/** The `file:` address behind the plan chip's click target; the caller opens it only when it is the page. */
+export const planUrlOf = (key: string): string | null => PLAN_KEY.exec(key)?.[1] ?? null
+
+/** Whether a click target belongs to a chip, of either kind. */
+export const isChipKey = (key: string): boolean => chipUrlOf(key) !== null || planUrlOf(key) !== null

package/src/plans/live.ts

@@ -0,0 +1,336 @@
+import { existsSync, type FSWatcher, watch } from 'node:fs'
+import { dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { openInBrowser } from '../terminal/open'
+import { errorText } from './error-text'
+import {
+  type FetchState,
+  fetchBase,
+  fetchNotice,
+  goneLanePullRequests,
+  initialFetchState,
+  shouldFetch,
+  watchedFiles,
+} from './fetch'
+import { fetchHeadPath } from './git'
+import { fetchPullRequests, noPullRequests, type PullRequestState } from './github'
+import type { Screen } from './layout'
+import { type KnownPage, pageAfterWrite, pageKey, pageNeedsWriting, planAnchorOn, withPlanChips } from './plan-chips'
+import { pullRequestUrl } from './pull-requests'
+import {
+  inputOutcome,
+  isSprintPageKey,
+  overviewSelection,
+  splitKeys,
+  syncLaneFolds,
+  targetKeys,
+  type View,
+  windowTop,
+} from './selection'
+import { BASE_REMOTE, baseRefOf, boardRepoPathOf, clockLocaleOf } from './settings'
+import { singleFlight } from './single-flight'
+import { loadSnapshot, type Snapshot, type Source } from './snapshot'
+import { exportSprintPage, writeSprintPageInSteps } from './sprint-export'
+import { boardTexts } from './texts'
+import { bodyRows, clockOf, draw, paneWidth, renderSnapshot, startSelection, TERMINAL_OFF, TERMINAL_ON } from './view'
+
+/** The state of the running view; only the functions below `runLive` change it. */
+type Live = {
+  source: Source
+  snapshot: Snapshot | null
+  screen: Screen | null
+  view: View
+  errors: string[]
+  pullRequests: PullRequestState
+  fetch: FetchState
+  /** One footer line about the last action of the person, such as where the sprint page was written; cleared by the next key. */
+  notice: string | null
+  watchers: Map<string, FSWatcher>
+  /** This clone's `FETCH_HEAD`, watched beside the plan files; null when git names none. */
+  fetchHead: string | null
+  reported: Map<string, string | null>
+  pending: Timer | null
+  /** The snapshot as read, without the plan chips; `snapshot` is this plus the chips of `page`. */
+  read: Snapshot | null
+  /** The sprint page last written, and the key of the plans it was built from; a click on a plan chip opens it. */
+  page: KnownPage | null
+  pageWriting: boolean
+  flight: (() => Promise<void>) | null
+  pageError: string | null
+}
+
+const REFRESH_MS = 5_000
+const PULL_REQUEST_REFRESH_MS = 60_000
+const DEBOUNCE_MS = 150
+const QUIT_KEYS = new Set(['\x03', 'q'])
+
+/** The sidebar titles that differ from the ones last reported, in the order of `titles`; null clears one. */
+export const changedTitles = (
+  titles: ReadonlyMap<string, string | null>,
+  reported: ReadonlyMap<string, string | null>,
+): [string, string | null][] => [...titles].filter(([pane, title]) => reported.get(pane) !== title)
+
+/** Reports the titles that changed since the last frame; a failed report is retried on the next one. */
+const reportTitles = (source: Source, titles: Map<string, string | null>, reported: Map<string, string | null>) => {
+  const errors: string[] = []
+  for (const [pane, title] of changedTitles(titles, reported)) {
+    const error = source.terminal.setTitle(pane, title)
+    if (error) errors.push(`sidebar title not set: ${terminalSafe(error)}`)
+    else reported.set(pane, title)
+  }
+  return errors
+}
+
+const clearTitles = (source: Source, reported: Map<string, string | null>) => {
+  for (const [pane, title] of reported) {
+    if (title) source.terminal.setTitle(pane, null)
+  }
+}
+
+const syncWatchers = (watchers: Map<string, FSWatcher>, files: string[], onChange: () => void) => {
+  for (const [file, watcher] of watchers) {
+    if (files.includes(file)) continue
+    watcher.close()
+    watchers.delete(file)
+  }
+  for (const file of files.filter((candidate) => !watchers.has(candidate))) {
+    try {
+      const watcher = watch(file, (event) => {
+        if (event === 'rename') {
+          watcher.close()
+          watchers.delete(file)
+        }
+        onChange()
+      })
+      watchers.set(file, watcher)
+    } catch {
+      // A file that cannot be watched right now is retried on the next refresh; the 5 s refresh covers it meanwhile.
+    }
+  }
+}
+
+/** Alternate screen, hidden cursor, mouse reports and raw keys; `quit` restores the terminal. */
+const enterTerminal = (onInput: (input: string) => void, quit: () => void, onResize: () => void) => {
+  process.stdout.write(TERMINAL_ON)
+  process.on('SIGINT', quit)
+  process.on('SIGTERM', quit)
+  process.stdout.on('resize', onResize)
+  if (!process.stdin.isTTY) return
+  process.stdin.setRawMode(true)
+  process.stdin.on('data', (chunk) => {
+    for (const input of splitKeys(chunk.toString())) onInput(input)
+  })
+}
+
+const redraw = (live: Live) => {
+  if (!live.snapshot) return
+  const screen = renderSnapshot(
+    live.snapshot,
+    live.view.selection,
+    [...live.errors, ...(live.pageError ? [live.pageError] : []), ...(live.notice ? [live.notice] : [])],
+    paneWidth(),
+    clockLocaleOf(live.source.settings),
+  )
+  const top = windowTop(live.view, screen.body.cursorLine, screen.body.lines.length, bodyRows(screen))
+  live.screen = screen
+  live.view = { ...live.view, top }
+  draw(screen, top)
+}
+
+/** The whole sprint, also while the view shows one lane: the snapshot is read again without the lane filter. */
+const wholeSprint = async (live: Live, snapshot: Snapshot): Promise<Snapshot> =>
+  live.source.options.lane
+    ? loadSnapshot({ ...live.source, options: { ...live.source.options, lane: null } }, live.pullRequests)
+    : snapshot
+
+const boardTextsOf = (live: Live) => boardTexts(live.source.settings.board.term)
+
+const sprintDirectoryOf = ({ root, sprintFile, settings }: Source): string =>
+  dirname(boardRepoPathOf(root, settings, sprintFile))
+
+/** The snapshot as read with the plan chips of the page written so far, none before the first one. */
+const withKnownPage = (live: Live, read: Snapshot): Snapshot =>
+  live.page ? withPlanChips(read, live.page, sprintDirectoryOf(live.source)) : read
+
+const isCurrent = (live: Live, read: Snapshot): boolean =>
+  live.page !== null && !pageNeedsWriting(live.page, pageKey(read), existsSync(live.page.path))
+
+/**
+ * Writes the sprint page, so a plan chip's link points at a file that exists. Only when the plans it is built
+ * from changed or the file is gone: building it takes seconds, with the event loop blocked for all of them.
+ */
+const syncSprintPage = async (live: Live, read: Snapshot) => {
+  const key = pageKey(read)
+  if (live.pageWriting || !pageNeedsWriting(live.page, key, live.page !== null && existsSync(live.page.path))) return
+  live.pageWriting = true
+  try {
+    const written = await writeSprintPageInSteps(live.source, await wholeSprint(live, read))
+    live.pageError = 'error' in written ? boardTextsOf(live).pageNotWritten(written.error) : null
+    live.page = pageAfterWrite(live.page, written, key)
+  } catch (error) {
+    live.pageError = boardTextsOf(live).pageNotWritten(errorText(error))
+  } finally {
+    live.pageWriting = false
+  }
+  if (live.read) live.snapshot = withKnownPage(live, live.read)
+  redraw(live)
+}
+
+/** A re-read never overlaps another: one asked for meanwhile runs once after the running one, so the screen cannot go back to an older read. */
+const refresh = (live: Live, onChange: () => void): Promise<void> => {
+  live.flight ??= singleFlight(() => readOnce(live, onChange))
+  return live.flight()
+}
+
+const readOnce = async (live: Live, onChange: () => void) => {
+  try {
+    const read = await loadSnapshot(live.source, live.pullRequests)
+    const next = withKnownPage(live, read)
+    live.read = read
+    if (!live.snapshot) live.view = { ...live.view, selection: startSelection(next, live.source.options) }
+    const folded = syncLaneFolds(
+      live.view.selection,
+      next.views.map(({ progress, status }) => ({ lane: progress.lane.name, status: status.agent })),
+    )
+    live.view = { ...live.view, selection: folded }
+    live.snapshot = next
+    const fetchLine = fetchNotice(live.fetch, baseRefOf(live.source.settings), clockLocaleOf(live.source.settings))
+    live.errors = [
+      ...next.errors,
+      ...(fetchLine ? [fetchLine] : []),
+      ...reportTitles(live.source, next.titles, live.reported),
+    ]
+    syncWatchers(live.watchers, watchedFiles(next.files, live.fetchHead), onChange)
+  } catch (error) {
+    const at = clockOf(clockLocaleOf(live.source.settings))
+    live.errors = [`refresh failed at ${at}, showing the last good state: ${errorText(error)}`]
+  }
+  redraw(live)
+  const { read } = live
+  if (read) setTimeout(() => void syncSprintPage(live, read), 0)
+}
+
+const writeSprintPage = async (live: Live, snapshot: Snapshot, anchor: string | null = null) => {
+  const { source } = live
+  try {
+    live.notice = exportSprintPage(source, await wholeSprint(live, snapshot), undefined, anchor)
+  } catch (error) {
+    live.notice = boardTextsOf(live).pageNotWritten(errorText(error))
+  }
+  redraw(live)
+}
+
+/**
+ * A click on a plan chip. A page built from the current plans is opened at once; otherwise it is written again
+ * first. Any other `file:` address is refused.
+ */
+const openPlan = (live: Live, snapshot: Snapshot, address: string) => {
+  const anchor = planAnchorOn(live.page?.path ?? null, address)
+  if (!anchor || !live.page) return
+  if (!live.read || !isCurrent(live, live.read)) {
+    void writeSprintPage(live, snapshot, anchor)
+    return
+  }
+  const reason = openInBrowser(`${pathToFileURL(live.page.path).href}#${anchor}`)
+  const texts = boardTextsOf(live)
+  live.notice = reason === null ? texts.pageOpened(live.page.path) : texts.pageNotOpenedReason(reason)
+}
+
+const handleInput = (live: Live, input: string) => {
+  const { snapshot, screen } = live
+  if (!snapshot || !screen) return
+  live.notice = null
+  if (isSprintPageKey(input)) {
+    void writeSprintPage(live, snapshot)
+    return
+  }
+  const context = {
+    keys: targetKeys(screen.body.targets),
+    targets: screen.body.targets,
+    headerRows: screen.header.length,
+    bodyRows: bodyRows(screen),
+  }
+  const pullRequests = snapshot.views.flatMap((view) => view.pullRequests)
+  const outcome = inputOutcome(live.view, input, context, (key) => pullRequestUrl(pullRequests, key))
+  live.view = outcome.view
+  if (outcome.open?.startsWith('file:')) {
+    openPlan(live, snapshot, outcome.open)
+    redraw(live)
+    return
+  }
+  const error = outcome.open ? openInBrowser(outcome.open) : null
+  if (error) live.errors = [...live.errors, error]
+  redraw(live)
+}
+
+export const runLive = (source: Source): void => {
+  const live: Live = {
+    source,
+    snapshot: null,
+    screen: null,
+    view: { selection: overviewSelection(), top: 0, follow: true },
+    errors: [],
+    pullRequests: noPullRequests(),
+    fetch: initialFetchState(),
+    notice: null,
+    watchers: new Map(),
+    fetchHead: fetchHeadPath(source.root),
+    reported: new Map(),
+    pending: null,
+    read: null,
+    page: null,
+    pageWriting: false,
+    flight: null,
+    pageError: null,
+  }
+  const schedule = () => {
+    if (live.pending) clearTimeout(live.pending)
+    live.pending = setTimeout(() => refresh(live, schedule), DEBOUNCE_MS)
+  }
+  const fetchBaseBranch = async () => {
+    live.fetch = { ...live.fetch, lastAttempt: Date.now(), running: true }
+    const failure = await fetchBase(source.root, BASE_REMOTE, source.settings.baseBranch)
+    live.fetch = {
+      ...live.fetch,
+      running: false,
+      failure,
+      lastSuccess: failure === null ? new Date() : live.fetch.lastSuccess,
+    }
+    schedule()
+  }
+  const fetchWhenDue = (pullRequestGone: boolean) => {
+    const due = shouldFetch({
+      now: Date.now(),
+      state: live.fetch,
+      intervalMinutes: source.settings.fetchIntervalMinutes,
+      pullRequestGone,
+    })
+    if (due) void fetchBaseBranch()
+  }
+  const refreshPullRequests = async () => {
+    const previous = live.pullRequests
+    live.pullRequests = await fetchPullRequests(source.root)
+    const readable = previous.errors.length === 0 && live.pullRequests.errors.length === 0
+    const laneBranches = new Set(live.snapshot?.views.flatMap(({ status }) => (status.branch ? [status.branch] : [])))
+    const gone = goneLanePullRequests(previous.byBranch, live.pullRequests.byBranch, laneBranches)
+    fetchWhenDue(readable && gone.length > 0)
+    schedule()
+  }
+  const quit = () => {
+    clearTitles(source, live.reported)
+    for (const watcher of live.watchers.values()) watcher.close()
+    process.stdout.write(TERMINAL_OFF)
+    process.exit(0)
+  }
+  const onInput = (input: string) => (QUIT_KEYS.has(input) ? quit() : handleInput(live, input))
+
+  enterTerminal(onInput, quit, () => redraw(live))
+  setInterval(() => {
+    fetchWhenDue(false)
+    void refresh(live, schedule)
+  }, REFRESH_MS)
+  setInterval(refreshPullRequests, PULL_REQUEST_REFRESH_MS)
+  void refresh(live, schedule)
+  void refreshPullRequests()
+}

package/src/plans/markdown-html.ts

@@ -0,0 +1,140 @@
+import { dirname, join, posix } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Marked, type Tokens } from 'marked'
+
+/** Where a plan's links can go: the other plans on the page, the repository, the local checkout. */
+export type LinkContext = {
+  /** The repository path of the plan the markdown comes from. */
+  fromPath: string
+  /** Repository path of a plan on the page → the id of its section. */
+  anchors: ReadonlyMap<string, string>
+  /** `https://host/owner/repo/blob/<branch>/` or null when the remote is unknown. */
+  blobBase: string | null
+  /** The main checkout, for `file:` links when there is no remote. */
+  root: string
+}
+
+const escapeHtml = (text: string): string =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+/** The id of a heading as GitHub makes it: lower case, punctuation gone, spaces to hyphens. */
+export const headingSlug = (text: string): string =>
+  text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\p{L}\p{N}\s-]/gu, '')
+    .replace(/\s/g, '-')
+
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i
+const WEB = /^https?:\/\//i
+const MAX_HEADING = 6
+const HEADING_SHIFT = 2
+
+/** The id of the section of a plan, from its repository path. */
+export const planAnchorOf = (repoPath: string): string =>
+  `plan-${headingSlug(posix.basename(repoPath, '.md')).replace(/-+/g, '-')}`
+
+/**
+ * Where a link of a plan goes on the page: another plan of the page becomes its anchor, a link inside the
+ * plan becomes the id of that heading, any other file of the repository goes to GitHub (or to the checkout),
+ * a web link stays. Anything else, a script or a path out of the repository, has no target.
+ */
+export const resolveLink = (href: string, context: LinkContext, ownAnchor: string): string | null => {
+  if (href === '') return null
+  if (href.startsWith('#')) return `#${ownAnchor}--${href.slice(1)}`
+  if (WEB.test(href)) return href
+  if (SCHEME.test(href)) return null
+  const [path, fragment] = href.split('#')
+  const target = posix.normalize(posix.join(dirname(context.fromPath), path))
+  if (target.startsWith('..')) return null
+  const anchor = context.anchors.get(target)
+  if (anchor) return `#${anchor}${fragment ? `--${fragment}` : ''}`
+  const base = context.blobBase ? `${context.blobBase}${target}` : pathToFileURL(join(context.root, target)).href
+  return fragment ? `${base}#${fragment}` : base
+}
+
+/** Every table in its own container that scrolls sideways, so a wide one is not cut off. */
+export const scrollable = (html: string): string =>
+  html.replace(/<table/g, '<div class="table-scroll"><table').replace(/<\/table>/g, '</table></div>')
+
+// The header fields (`**Date:**`, `**Status:**`, `**Scope:**`) sit on consecutive lines, which markdown folds
+// into one paragraph; a trailing double space keeps each on its own line.
+const hardBreakFields = (markdown: string): string =>
+  markdown.replace(/^(\*\*\w+:\*\*[^\n]*)\n(?=\*\*\w+:\*\*)/gm, '$1  \n')
+
+const renderUncached = (
+  markdown: string,
+  context: LinkContext,
+  ownAnchor: string,
+  /** The title the section already shows; a first level 1 heading with that text is left out. */
+  shownTitle: string | null = null,
+): string => {
+  const seen = new Map<string, number>()
+  const marked = new Marked({
+    gfm: true,
+    renderer: {
+      html: ({ text }: Tokens.HTML | Tokens.Tag) => escapeHtml(text),
+      image: ({ text }: Tokens.Image) => escapeHtml(text),
+      checkbox: ({ checked }: Tokens.Checkbox) => (checked ? '☑' : '☐'),
+      link(this: { parser: { parseInline: (tokens: Tokens.Generic[]) => string } }, { href, tokens }: Tokens.Link) {
+        const label = this.parser.parseInline(tokens)
+        const target = resolveLink(href, context, ownAnchor)
+        return target === null ? label : `<a href="${escapeHtml(target)}">${label}</a>`
+      },
+      heading(
+        this: { parser: { parseInline: (tokens: Tokens.Generic[]) => string } },
+        { tokens, depth, text }: Tokens.Heading,
+      ) {
+        if (depth === 1 && shownTitle !== null && text.trim() === shownTitle.trim()) return ''
+        const slug = headingSlug(text)
+        const count = seen.get(slug) ?? 0
+        seen.set(slug, count + 1)
+        const id = `${ownAnchor}--${count === 0 ? slug : `${slug}-${count}`}`
+        const level = Math.min(depth + HEADING_SHIFT, MAX_HEADING)
+        return `<h${level} id="${escapeHtml(id)}">${this.parser.parseInline(tokens)}</h${level}>\n`
+      },
+    },
+  })
+  return scrollable(marked.parse(hardBreakFields(markdown), { async: false }))
+}
+
+const rendered = new Map<string, string>()
+const RENDERED_MAX = 64
+
+const renderKey = (markdown: string, context: LinkContext, ownAnchor: string, shownTitle: string | null): string =>
+  JSON.stringify([
+    Bun.hash(markdown).toString(36),
+    markdown.length,
+    context.fromPath,
+    [...context.anchors],
+    context.blobBase,
+    context.root,
+    ownAnchor,
+    shownTitle,
+  ])
+
+/**
+ * A plan's markdown as HTML for the page. Raw HTML in the text is shown as text and images as their alt text;
+ * headings get ids under the plan's anchor and move two levels down; task items are ☐ and ☑. Rendering takes
+ * about two milliseconds per kilobyte, so what was rendered is kept: the same text under the same links yields
+ * the same HTML, and a page built again after one plan changed renders that plan only.
+ */
+export const renderPlanMarkdown = (
+  markdown: string,
+  context: LinkContext,
+  ownAnchor: string,
+  /** The title the section already shows; a first level 1 heading with that text is left out. */
+  shownTitle: string | null = null,
+): string => {
+  const key = renderKey(markdown, context, ownAnchor, shownTitle)
+  const kept = rendered.get(key)
+  if (kept !== undefined) {
+    rendered.delete(key)
+    rendered.set(key, kept)
+    return kept
+  }
+  const html = renderUncached(markdown, context, ownAnchor, shownTitle)
+  if (rendered.size >= RENDERED_MAX) rendered.delete(rendered.keys().next().value as string)
+  rendered.set(key, html)
+  return html
+}

package/src/plans/options.ts

@@ -0,0 +1,15 @@
+export type Options = { boardPath: string | null; lane: string | null; once: boolean; ensure: boolean }
+
+const KNOWN_OPTIONS = ['--lane', '--once', '--ensure']
+
+export const parseOptions = (args: string[]): Options => {
+  const unknown = args.find((arg) => arg.startsWith('--') && !KNOWN_OPTIONS.includes(arg))
+  if (unknown) throw new Error(`unknown option ${unknown} (known: ${KNOWN_OPTIONS.join(', ')})`)
+  const laneIndex = args.indexOf('--lane')
+  const lane = laneIndex === -1 ? null : args[laneIndex + 1]
+  if (lane === undefined || lane?.startsWith('--')) throw new Error('--lane needs a lane name')
+  const positional = args.filter((arg, index) => !arg.startsWith('--') && (laneIndex === -1 || index !== laneIndex + 1))
+  const ensure = args.includes('--ensure')
+  if (ensure && (lane !== null || args.includes('--once'))) throw new Error('--ensure takes no --lane or --once')
+  return { boardPath: positional[0] ?? null, lane, once: args.includes('--once'), ensure }
+}

package/src/plans/phase-source.ts

@@ -0,0 +1,71 @@
+import type { PlanPhase } from '../plan-format'
+
+/** What a lane has done in its own worktree: commits ahead of the base ref (null when unknown) and changed files. */
+export type OwnWork = { ahead: number | null; dirty: number }
+
+export const PHASE_SOURCE = { base: 'base', worktree: 'worktree' } as const
+
+export type PhaseSource = (typeof PHASE_SOURCE)[keyof typeof PHASE_SOURCE]
+
+export const hasOwnWork = ({ ahead, dirty }: OwnWork): boolean => (ahead ?? 0) > 0 || dirty > 0
+
+/**
+ * Where a phase that a row of the lane names is read from: its worktree while the lane has unmerged work of
+ * its own there, where the lane ticks it, else the base ref. `mergePlanPhases` adds the phases no row names.
+ */
+export const phaseSource = (work: OwnWork, ownedByLane: boolean): PhaseSource =>
+  ownedByLane && hasOwnWork(work) ? PHASE_SOURCE.worktree : PHASE_SOURCE.base
+
+const LETTER_SUFFIX = /[a-z]$/
+
+/** A sprint phase `4b` belongs to the plan phase `4` as well as to `4b`. */
+export const belongsToLane = (planPhaseId: string, laneIds: readonly string[]): boolean =>
+  laneIds.some((id) => id === planPhaseId || id.replace(LETTER_SUFFIX, '') === planPhaseId)
+
+const doneStates = (phase: PlanPhase): boolean[] => phase.items.map((item) => item.done)
+
+const sameTicks = (left: PlanPhase, right: PlanPhase): boolean => {
+  const [leftStates, rightStates] = [doneStates(left), doneStates(right)]
+  return leftStates.length === rightStates.length && leftStates.every((done, index) => done === rightStates[index])
+}
+
+const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => item.done).length
+
+/** The lane ticked further than the base: the worktree's copy is newer, not an old copy of another lane's work. */
+const tickedFurther = (worktreePhase: PlanPhase, basePhase: PlanPhase): boolean =>
+  tickCount(worktreePhase) > tickCount(basePhase)
+
+/** A phase read from the worktree is touched when its ticks differ from the base's, or the base lacks it. */
+const markTouched = (phase: PlanPhase, basePhase: PlanPhase | undefined): PlanPhase =>
+  basePhase && sameTicks(phase, basePhase) ? phase : { ...phase, touched: true }
+
+/**
+ * The phases of a plan as the lane sees them: the base ref's phases in their order, each replaced by the
+ * worktree's version when `phaseSource` says so, or, for a phase no row of the lane names, when the lane has
+ * work of its own and ticked it further than the base; a phase only the worktree has follows. A phase the
+ * worktree ticked less stays at the base: the lane holds an old copy of what another lane finished. Only the
+ * count is compared, so a tick of the lane's own stays hidden while the base has more ticks in that phase.
+ */
+export const mergePlanPhases = (
+  base: readonly PlanPhase[],
+  worktree: readonly PlanPhase[] | null,
+  laneIds: readonly string[],
+  work: OwnWork,
+): PlanPhase[] => {
+  const laneHasWork = hasOwnWork(work)
+  const worktreeById = new Map((worktree ?? []).map((phase) => [phase.id, phase]))
+  const baseIds = new Set(base.map((phase) => phase.id))
+  const readsWorktree = (id: string) => phaseSource(work, belongsToLane(id, laneIds)) === PHASE_SOURCE.worktree
+  const readsWorktreeCopy = (worktreePhase: PlanPhase, basePhase: PlanPhase) =>
+    readsWorktree(basePhase.id) || (laneHasWork && tickedFurther(worktreePhase, basePhase))
+  const inBaseOrder = base.map((basePhase) => {
+    const worktreePhase = worktreeById.get(basePhase.id)
+    return worktreePhase && readsWorktreeCopy(worktreePhase, basePhase)
+      ? markTouched(worktreePhase, basePhase)
+      : basePhase
+  })
+  const added = laneHasWork
+    ? [...worktreeById.values()].filter((phase) => !baseIds.has(phase.id)).map((phase) => markTouched(phase, undefined))
+    : []
+  return [...inBaseOrder, ...added]
+}