jackherd 0.0.1 → 1.0.0

package/src/plans/snapshot.ts

@@ -0,0 +1,300 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { ContextReading } from '../context'
+import { type AgentLogReader, contextOfAgent } from '../context/report'
+import { agentLog } from '../context/session-log'
+import {
+  type LaneProgress,
+  laneProgress,
+  readSprintDocument,
+  resolvePlanPath,
+  type SprintLane,
+  shortTitle,
+  sprintTitleOf,
+} from '../plan-format'
+import type { LaneAgent, LaneStatusSource } from '../terminal'
+import type { PlanLanguage } from '../vocabulary'
+import type { WatchBadges, WatchHealth } from '../watch/plan-badges'
+import { readWatchReading } from '../watch/plan-badges-read'
+import { boardRowsOf } from './board-rows'
+import { errorText } from './error-text'
+import { type BaseReader, baseReaderOf, gitStatusOf, refExists } from './git'
+import type { PullRequestState } from './github'
+import { type Fallbacks, laneWorkOf, readAtBase, readFallback, readPlans, textAtBase } from './lane-plans'
+import { type LaneView, sortByUrgency } from './layout'
+import { extractLinkChips } from './link-chips'
+import type { Options } from './options'
+import { currentPlanFirst, followingPlans, type PlannedPlan, plannedPlans } from './planned'
+import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from './settings'
+import { boardTexts } from './texts'
+import { type UnlistedLane, unlistedLanes, unlistedSprintLane } from './unlisted-lanes'
+import { withWorkedPhases } from './worked-phases'
+
+/** Where the view reads from: the main checkout, the sprint document, the command line and the project settings. */
+export type Source = {
+  root: string
+  sprintFile: string
+  options: Options
+  settings: PlansSettings
+  terminal: LaneStatusSource
+  /** The log lines of an agent's chat, null without one; defaults to reading them from `~/.claude/projects`. */
+  readAgentLog?: AgentLogReader
+  /** Why this board was chosen over others, shown with the errors; null or absent when there was no choice. */
+  boardNotice?: string | null
+}
+
+/**
+ * The documents a snapshot was read from, for views that draw more than the lane lines: the sprint text, the
+ * plan texts by link as the sprint writes it, and the lanes in the order of the sprint table.
+ */
+export type SnapshotDocuments = {
+  sprint: string
+  plans: Record<string, string>
+  laneOrder: string[]
+  /** The board's lanes as the view draws them: the base ref's rows plus the rows only the checkout has. */
+  lanes: SprintLane[]
+}
+
+/**
+ * What one read of the sprint, the plans, git and the terminal produced; keys redraw from it without
+ * reading again. `errors` are shown in the footer.
+ */
+export type Snapshot = {
+  title: string
+  views: LaneView[]
+  documents: SnapshotDocuments
+  /** The open phases no lane with an agent leads; empty while the view shows one lane. */
+  planned: PlannedPlan[]
+  files: string[]
+  titles: Map<string, string | null>
+  errors: string[]
+  /** The watcher's health; absent when no lane has an open pull request, so the watcher was not looked at. */
+  watch?: WatchHealth
+  /** The project's response language, for the words of the watcher's badges. */
+  language?: PlanLanguage
+}
+
+type LaneSources = {
+  source: Source
+  base: BaseReader
+  sprintDirectory: string
+  agents: LaneAgent[]
+  pullRequests: PullRequestState
+}
+
+type BoardLanes = { markdown: string; lanes: SprintLane[] }
+
+const SHOWN_NAMES = 2
+
+type LaneResult = { view: LaneView; files: string[]; texts: Record<string, string>; pane: string | null }
+
+/** How full the agent's context is, null when the terminal gave no session or the session has no log. */
+const contextOf = (agent: LaneAgent | undefined, source: Source): ContextReading | null => {
+  const report = contextOfAgent(agent, source.readAgentLog ?? agentLog, source.settings.context)
+  return report && { share: report.share, level: report.level }
+}
+
+/** The repository path of the plan the lane's current phase belongs to; null when every phase is done. */
+const currentPlanPath = ({ current, steps }: LaneProgress, sprintDirectory: string): string | null => {
+  const href = current ? steps[current.stepIndex].step.planHref : null
+  return href ? resolvePlanPath(sprintDirectory, href) : null
+}
+
+/** What a lane's worktree and agent say, listed in the sprint or not: git state, pull requests, context. */
+const runningState = async (sources: LaneSources, name: string, agent: LaneAgent | undefined) => {
+  const { source, pullRequests } = sources
+  const gitStatus = await gitStatusOf(worktreeOf(source.root, source.settings, name), baseRefOf(source.settings))
+  return {
+    gitStatus,
+    view: {
+      status: { agent: agent?.status ?? null, ...gitStatus },
+      pullRequests: gitStatus.branch ? (pullRequests.byBranch.get(gitStatus.branch) ?? []) : [],
+      context: contextOf(agent, source),
+    },
+  }
+}
+
+const laneView = async (sources: LaneSources, lane: SprintLane, fallbacks: Fallbacks): Promise<LaneResult> => {
+  const { source, agents } = sources
+  const { root, settings } = source
+  const worktree = worktreeOf(root, settings, lane.name)
+  const agent = agents.find((candidate) => candidate.name === lane.name)
+  const { gitStatus, view: running } = await runningState(sources, lane.name, agent)
+  const { plans, files, texts } = await readPlans(
+    lane,
+    { root, settings, base: sources.base, sprintDirectory: sources.sprintDirectory },
+    laneWorkOf(worktree, gitStatus),
+    fallbacks,
+  )
+  const shown = withWorkedPhases(lane, plans)
+  const progress = laneProgress(shown, plans)
+  const view: LaneView = {
+    progress,
+    ...running,
+    chips: Object.fromEntries(
+      Object.entries(texts).map(([href, text]) => [href, extractLinkChips(text, settings.linkKinds)]),
+    ),
+    following: currentPlanFirst(
+      followingPlans(
+        { lane: shown, agent: agent?.status ?? null },
+        { plans: texts, sprintDirectory: sources.sprintDirectory, language: settings.planLanguage },
+      ),
+      currentPlanPath(progress, sources.sprintDirectory),
+    ),
+  }
+  return { view, files, texts, pane: agent?.pane ?? null }
+}
+
+/**
+ * A running lane the sprint table does not list: its worktree's git state, pull requests and context, without plan
+ * and without phases, marked as unlisted.
+ */
+const unlistedView = async (sources: LaneSources, { name, agent }: UnlistedLane): Promise<LaneResult> => {
+  const { view: running } = await runningState(sources, name, agent)
+  const view: LaneView = {
+    progress: laneProgress(unlistedSprintLane(name), {}),
+    ...running,
+    chips: {},
+    unlisted: true,
+  }
+  return { view, files: [], texts: {}, pane: agent.pane }
+}
+
+/** The view with the watcher's badges of its own pull requests, only when there are any, so it otherwise stays as it was. */
+const withBadges = (view: LaneView, badges: WatchBadges): LaneView => {
+  const own = Object.fromEntries(
+    view.pullRequests.flatMap(({ number }) => {
+      const found = badges[String(number)]
+      return found ? [[String(number), found]] : []
+    }),
+  )
+  return Object.keys(own).length > 0 ? { ...view, badges: own } : view
+}
+
+/** The terminal's agents, or none with the reason when it cannot be asked, so the screen says why lanes show "no agent". */
+const readAgents = (terminal: LaneStatusSource): { agents: LaneAgent[]; errors: string[] } => {
+  try {
+    return { agents: terminal.listAgents(), errors: [] }
+  } catch (error) {
+    return { agents: [], errors: [errorText(error)] }
+  }
+}
+
+/** Up to two names, then how many more: `a, b and 3 more`. */
+const namedWithMore = (names: readonly string[]): string => {
+  const more = names.length - SHOWN_NAMES
+  return `${names.slice(0, SHOWN_NAMES).join(', ')}${more > 0 ? ` and ${more} more` : ''}`
+}
+
+/** The footer line for files read from a checkout because the base ref lacks them or does not exist. */
+export const fallbackNotice = (fallbacks: readonly string[], baseRef: string, baseRefKnown: boolean): string | null => {
+  if (fallbacks.length === 0) return null
+  if (!baseRefKnown) return `${baseRef} not found, reading plans from the checkout`
+  return `not on ${baseRef}, read from the checkout: ${namedWithMore([...new Set(fallbacks)])}`
+}
+
+/**
+ * The board and its lanes. The text is the base ref's; rows the checkout's board file has beyond it are added
+ * (the watcher reminds the coordinator of them, the view does not mark them). A board the base ref lacks is read from the checkout alone, and a
+ * checkout with the same text adds nothing.
+ */
+const readBoardLanes = async (
+  source: Source,
+  base: BaseReader,
+  boardPath: string,
+  fallbacks: Fallbacks,
+): Promise<BoardLanes> => {
+  const { sprintFile, settings } = source
+  const atBase = textAtBase(base, boardPath)
+  const markdown = atBase ?? (await readFallback(boardPath, sprintFile, fallbacks)) ?? ''
+  const checkoutText = atBase !== null && existsSync(sprintFile) ? await Bun.file(sprintFile).text() : markdown
+  return { markdown, lanes: boardRowsOf(markdown, checkoutText, settings.planLanguage).lanes }
+}
+
+/** The plans the sprint's plans tables name, read at the base ref, by link; lanes read theirs themselves. */
+const readListedPlans = async (
+  source: Source,
+  base: BaseReader,
+  sprintDirectory: string,
+  markdown: string,
+  fallbacks: Fallbacks,
+): Promise<Record<string, string>> => {
+  const hrefs = new Set(
+    readSprintDocument(markdown, source.settings.planLanguage).planTables.flatMap(({ rows }) =>
+      rows.flatMap((row) => (row.href ? [row.href] : [])),
+    ),
+  )
+  const entries = await Promise.all(
+    [...hrefs].map(async (href) => {
+      const path = resolvePlanPath(sprintDirectory, href)
+      const text = await readAtBase(base, path, join(source.root, path), fallbacks)
+      return text === null ? [] : [[href, text] as const]
+    }),
+  )
+  return Object.fromEntries(entries.flat())
+}
+
+export const loadSnapshot = async (source: Source, pullRequests: PullRequestState): Promise<Snapshot> => {
+  const { root, sprintFile, options, settings, terminal } = source
+  const fallbacks: Fallbacks = []
+  const base = baseReaderOf(root, baseRefOf(settings))
+  const boardPath = boardRepoPathOf(root, settings, sprintFile)
+  const board = await readBoardLanes(source, base, boardPath, fallbacks)
+  const { markdown } = board
+  const sprintDirectory = dirname(boardPath)
+  const { agents, errors } = readAgents(terminal)
+  const isWanted = ({ name }: { name: string }) => !options.lane || name === options.lane
+  const lanes = board.lanes.filter(isWanted)
+  const unlisted = unlistedLanes(
+    agents,
+    new Set(board.lanes.map((lane) => lane.name)),
+    join(root, settings.worktreeDirectory),
+  ).filter(isWanted)
+  const sources = {
+    source,
+    base,
+    sprintDirectory,
+    agents,
+    pullRequests,
+  }
+  const results = [
+    ...(await Promise.all(lanes.map((lane) => laneView(sources, lane, fallbacks)))),
+    ...(await Promise.all(unlisted.map((lane) => unlistedView(sources, lane)))),
+  ]
+  const listedPlans = await readListedPlans(source, base, sprintDirectory, markdown, fallbacks)
+  const documentsPlans = Object.assign({}, listedPlans, ...results.map((result) => result.texts))
+  const planned = options.lane
+    ? []
+    : plannedPlans({
+        plans: documentsPlans,
+        lanes: results.map(({ view }) => ({ lane: view.progress.lane, agent: view.status.agent })),
+        sprintDirectory,
+        language: settings.planLanguage,
+      })
+  const reading = results.some(({ view }) => view.pullRequests.length > 0) ? readWatchReading(root, Date.now()) : null
+  const baseRef = baseRefOf(settings)
+  const notice = fallbacks.length > 0 ? fallbackNotice(fallbacks, baseRef, refExists(root, baseRef)) : null
+  const unknownLaneTitle =
+    options.lane && results.length === 0 ? boardTexts(settings.board.term).laneNotListed(options.lane) : null
+  return {
+    title: unknownLaneTitle ?? sprintTitleOf(markdown, sprintDirectory),
+    views: sortByUrgency(results.map((result) => withBadges(result.view, reading?.badges ?? {}))),
+    documents: {
+      sprint: markdown,
+      plans: documentsPlans,
+      laneOrder: [...lanes, ...unlisted].map((lane) => lane.name),
+      lanes: board.lanes,
+    },
+    planned,
+    files: [sprintFile, ...results.flatMap((result) => result.files)],
+    titles: new Map(results.flatMap(({ view, pane }) => (pane ? [[pane, shortTitle(view.progress)]] : []))),
+    errors: [
+      ...errors,
+      ...pullRequests.errors,
+      ...(notice ? [notice] : []),
+      ...(source.boardNotice ? [source.boardNotice] : []),
+    ],
+    watch: reading?.health,
+    language: settings.responseLanguage,
+  }
+}

package/src/plans/sprint-export.ts

@@ -0,0 +1,103 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { openInBrowser } from '../terminal/open'
+import { errorText } from './error-text'
+import { baseRefInfo, remoteBlobBase } from './git'
+import { baseRefOf, boardRepoPathOf } from './settings'
+import type { Snapshot, Source } from './snapshot'
+import { renderPlanBody, renderSprintHtml } from './sprint-html'
+import { buildSprintPage, type SprintPage, sprintPagePath } from './sprint-page'
+import { boardTexts } from './texts'
+
+const DIRECTORY_MODE = 0o700
+const FILE_MODE = 0o600
+
+/** What writing and opening the page needs from outside; the defaults are the real ones. */
+export type ExportEnvironment = {
+  now: () => Date
+  temporaryDirectory: string
+  open: (target: string) => string | null
+}
+
+const systemEnvironment = (): ExportEnvironment => ({
+  now: () => new Date(),
+  temporaryDirectory: tmpdir(),
+  open: (target) => openInBrowser(target),
+})
+
+/** A page on disk: where it is, and the section id of each plan it carries by the plan's repository path. */
+export type WrittenPage = { path: string; anchors: ReadonlyMap<string, string> }
+
+const pageOf = ({ root, sprintFile, settings }: Source, snapshot: Snapshot, environment: ExportEnvironment) =>
+  buildSprintPage(snapshot, {
+    root,
+    generatedAt: environment.now(),
+    baseRef: baseRefInfo(root, baseRefOf(settings)),
+    repoBlobBase: remoteBlobBase(root, settings.baseBranch),
+    sprintDirectory: dirname(boardRepoPathOf(root, settings, sprintFile)),
+    language: settings.planLanguage,
+    linkKinds: settings.linkKinds,
+  })
+
+const writePage = (
+  page: SprintPage,
+  { sprintFile, root, settings }: Source,
+  environment: ExportEnvironment,
+): WrittenPage | { error: string } => {
+  const path = sprintPagePath(environment.temporaryDirectory, dirname(boardRepoPathOf(root, settings, sprintFile)))
+  try {
+    mkdirSync(dirname(path), { recursive: true, mode: DIRECTORY_MODE })
+    writeFileSync(path, renderSprintHtml(page), { mode: FILE_MODE })
+  } catch (error) {
+    return { error: errorText(error) }
+  }
+  return { path, anchors: page.links.anchors }
+}
+
+/** The page as a file, without opening it; the reason when it could not be written. */
+export const writeSprintPageFile = (
+  source: Source,
+  snapshot: Snapshot,
+  environment: ExportEnvironment = systemEnvironment(),
+): WrittenPage | { error: string } => writePage(pageOf(source, snapshot, environment), source, environment)
+
+const yieldToEventLoop = (): Promise<void> => new Promise((resolve) => setTimeout(resolve, 0))
+
+/**
+ * The same as `writeSprintPageFile`, but the plans are rendered one at a time with the event loop given back in
+ * between, so a key pressed while the page is built waits for one plan (a few hundred milliseconds at most), not
+ * for all of them (seconds). The final write then finds every plan already rendered.
+ */
+export const writeSprintPageInSteps = async (
+  source: Source,
+  snapshot: Snapshot,
+  environment: ExportEnvironment = systemEnvironment(),
+): Promise<WrittenPage | { error: string }> => {
+  const page = pageOf(source, snapshot, environment)
+  for (const document of page.planDocuments) {
+    renderPlanBody(document, page)
+    await yieldToEventLoop()
+  }
+  return writePage(page, source, environment)
+}
+
+/**
+ * Writes the whole board as one HTML file and opens it in the default browser, at `anchor` when given. Returns
+ * the footer line: the path when it was opened, the path and the reason when it could not be (no display is no
+ * error), the reason when nothing could be written.
+ */
+export const exportSprintPage = (
+  source: Source,
+  snapshot: Snapshot,
+  environment: ExportEnvironment = systemEnvironment(),
+  anchor: string | null = null,
+): string => {
+  const texts = boardTexts(source.settings.board.term)
+  const written = writeSprintPageFile(source, snapshot, environment)
+  if ('error' in written) return texts.pageNotWritten(written.error)
+  const { path } = written
+  const reason = environment.open(anchor ? `${pathToFileURL(path).href}#${anchor}` : path)
+  return reason === null ? texts.pageOpened(path) : texts.pageNotOpened(path, reason)
+}