ranni-cli 0.0.0-stage → 0.2.3

package/src/init.ts

@@ -0,0 +1,184 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { basename, join, posix, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isMap, parseDocument } from 'yaml'
+import { RanniError } from './errors'
+import { findProjectRoot } from './project'
+
+export const WORK_KIND = 'work'
+const DEFAULT_ROOT = '.relic/records/work'
+
+const norm = (p: string) => posix.normalize(p).replace(/\/+$/, '')
+
+export interface WorkRoot {
+  path: string
+  /** Why this path, for the user. */
+  why: string
+}
+
+/** Picks the root for the work kind from the roots already declared. Pure. */
+export function chooseWorkRoot(topology: { specs?: unknown; shared?: unknown; records?: Record<string, unknown> }): WorkRoot {
+  const records = Object.values(topology.records ?? {}).filter((v): v is string => typeof v === 'string').map(norm)
+  const taken = new Set(
+    [topology.specs, topology.shared, ...records].filter((v): v is string => typeof v === 'string').map(norm),
+  )
+  let candidate: string
+  let why: string
+  if (records.length === 0 || records.every(r => r.startsWith('.relic/records/'))) {
+    candidate = DEFAULT_ROOT
+    why = records.length === 0 ? 'no record roots declared yet' : 'the other records live under .relic/records'
+  } else {
+    // Sibling of the existing roots: the most common parent directory, first seen wins ties.
+    const counts = new Map<string, number>()
+    for (const r of records) counts.set(posix.dirname(r), (counts.get(posix.dirname(r)) ?? 0) + 1)
+    let parent = posix.dirname(records[0])
+    let best = 0
+    for (const [p, c] of counts) if (c > best) { best = c; parent = p }
+    candidate = parent === '.' ? WORK_KIND : `${parent}/${WORK_KIND}`
+    why = `a sibling of the existing record roots (${parent === '.' ? 'project root' : parent})`
+  }
+  if (taken.has(candidate)) {
+    candidate = `${candidate}-items`
+    why += `; ${norm(candidate.replace(/-items$/, ''))} is already a Relic root`
+  }
+  return { path: candidate, why }
+}
+
+export interface YamlEdit {
+  text: string
+  changed: boolean
+  /** The declared or added root of the work kind. */
+  workRoot: string
+  why?: string
+}
+
+/**
+ * Declares the work record kind when none exists, with the yaml Document API so comments
+ * and formatting survive. Pure.
+ */
+export function addWorkKind(source: string): YamlEdit {
+  const doc = parseDocument(source)
+  if (doc.errors.length) throw new RanniError(`relic.yaml is not valid YAML: ${doc.errors[0].message}`)
+  const topology = doc.get('topology', true)
+  if (!isMap(topology)) throw new RanniError('relic.yaml has no topology map. Run `relic verify` to see what Relic expects.')
+  const records = topology.get('records', true)
+  if (isMap(records) && records.has(WORK_KIND)) {
+    const existing = records.get(WORK_KIND)
+    return { text: source, changed: false, workRoot: String(existing) }
+  }
+  const plain = doc.toJS() as { topology: { specs?: unknown; shared?: unknown; records?: Record<string, unknown> } }
+  const { path, why } = chooseWorkRoot(plain.topology)
+  if (isMap(records)) records.set(WORK_KIND, path)
+  else topology.set('records', doc.createNode({ [WORK_KIND]: path }))
+  return { text: doc.toString({ lineWidth: 0 }), changed: true, workRoot: path, why }
+}
+
+export interface SkillChange {
+  dir: string
+  action: 'installed' | 'updated' | 'unchanged'
+  detail: string[]
+}
+
+function readTree(dir: string): Map<string, string> {
+  const out = new Map<string, string>()
+  const walk = (d: string) => {
+    for (const name of readdirSync(d).sort()) {
+      const p = join(d, name)
+      if (statSync(p).isDirectory()) walk(p)
+      else out.set(relative(dir, p).split('\\').join('/'), readFileSync(p, 'utf8'))
+    }
+  }
+  if (existsSync(dir)) walk(dir)
+  return out
+}
+
+/** Every `<dot-dir>/skills/relic/` of the project that holds a SKILL.md. */
+export function findRelicSkillDirs(projectRoot: string): string[] {
+  const found: string[] = []
+  for (const name of readdirSync(projectRoot).sort()) {
+    if (!name.startsWith('.') || name === '.git') continue
+    const base = join(projectRoot, name)
+    try {
+      if (!statSync(base).isDirectory()) continue
+    } catch {
+      continue
+    }
+    if (existsSync(join(base, 'skills', 'relic', 'SKILL.md'))) found.push(base)
+  }
+  return found
+}
+
+export function templateDir(): string {
+  return fileURLToPath(new URL('../templates/ranni', import.meta.url))
+}
+
+/** Copies the template over `<engine>/skills/ranni`, replacing the previous copy. */
+export function syncSkill(engineDir: string, template: string): SkillChange {
+  const dest = join(engineDir, 'skills', 'ranni')
+  const next = readTree(template)
+  const prev = readTree(dest)
+  const detail: string[] = []
+  for (const [f, c] of next) {
+    if (!prev.has(f)) detail.push(`+ ${f}`)
+    else if (prev.get(f) !== c) detail.push(`~ ${f}`)
+  }
+  for (const f of prev.keys()) if (!next.has(f)) detail.push(`- ${f}`)
+  const dir = join(basename(engineDir), 'skills', 'ranni')
+  if (!existsSync(dest)) {
+    cpSync(template, dest, { recursive: true })
+    return { dir, action: 'installed', detail: [`${next.size} files`] }
+  }
+  if (detail.length === 0) return { dir, action: 'unchanged', detail }
+  rmSync(dest, { recursive: true, force: true })
+  cpSync(template, dest, { recursive: true })
+  return { dir, action: 'updated', detail }
+}
+
+export interface Io {
+  out: (s: string) => void
+  err: (s: string) => void
+}
+
+export function runInit(cwd: string, io: Io, template = templateDir()): number {
+  const root = findProjectRoot(cwd)
+  if (!root) {
+    io.err('ranni: no relic.yaml found in this directory or above. Run `relic init` first; ranni never creates one.\n')
+    return 1
+  }
+  // Check every precondition before changing anything.
+  const engines = findRelicSkillDirs(root)
+  if (engines.length === 0) {
+    io.err('ranni: no Relic skill is installed (looked for <dot-dir>/skills/relic/SKILL.md). Run `relic install` first.\n')
+    return 1
+  }
+  const yamlPath = join(root, 'relic.yaml')
+  const edit = addWorkKind(readFileSync(yamlPath, 'utf8'))
+
+  const lines: string[] = []
+  if (edit.changed) {
+    writeFileSync(yamlPath, edit.text)
+    lines.push(`relic.yaml: declared the "${WORK_KIND}" record kind at ${edit.workRoot} (${edit.why})`)
+    const dir = join(root, edit.workRoot)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+      lines.push(`created ${edit.workRoot}/`)
+    }
+  } else {
+    lines.push(`relic.yaml: already declares the "${WORK_KIND}" record kind at ${edit.workRoot}`)
+  }
+  for (const eng of engines) {
+    const ch = syncSkill(eng, template)
+    lines.push(`${ch.dir}: ${ch.action}${ch.detail.length ? ' (' + ch.detail.join(', ') + ')' : ''}`)
+  }
+  io.out(lines.join('\n') + '\n')
+  return 0
+}

package/src/project.ts

@@ -0,0 +1,32 @@
+import { lstatSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { parse } from 'yaml'
+
+/** Nearest ancestor (or self) directory holding a regular, non-symlinked relic.yaml. */
+export function findProjectRoot(from: string): string | undefined {
+  let dir = from
+  for (;;) {
+    try {
+      if (lstatSync(join(dir, 'relic.yaml')).isFile()) return dir
+    } catch {
+      // not here, keep walking
+    }
+    const up = dirname(dir)
+    if (up === dir) return undefined
+    dir = up
+  }
+}
+
+/**
+ * Whether relic.yaml at the root declares the record kind. Undefined when the file cannot
+ * be read or parsed: the caller then says nothing rather than guess.
+ */
+export function declaresRecordKind(root: string, kind: string): boolean | undefined {
+  try {
+    const doc = parse(readFileSync(join(root, 'relic.yaml'), 'utf8')) as { topology?: { records?: unknown } } | null
+    const records = doc?.topology?.records
+    return !!records && typeof records === 'object' && Object.hasOwn(records, kind)
+  } catch {
+    return undefined
+  }
+}

package/src/relic.ts

@@ -0,0 +1,89 @@
+import { RanniError } from './errors'
+import type { Runner } from './runner'
+import type { LinkRef, WorkItem } from './types'
+
+export const SUPPORTED_FORMAT_VERSION = 1
+
+const MIN_RELIC =
+  'Ranni needs a relic with structured search: `relic search --kind <kind> --json` reporting formatVersion 1 with document metadata.'
+
+/** Validates and converts the JSON of `relic search --json`. Pure. */
+export function parseSearch(stdout: string): { items: WorkItem[]; federated: boolean } {
+  let json: unknown
+  try {
+    json = JSON.parse(stdout)
+  } catch {
+    throw new RanniError(`relic search did not return JSON. ${MIN_RELIC}`)
+  }
+  const root = json as { formatVersion?: unknown; results?: unknown }
+  if (root === null || typeof root !== 'object' || root.formatVersion === undefined) {
+    throw new RanniError(`relic search output has no formatVersion. ${MIN_RELIC}`)
+  }
+  if (root.formatVersion !== SUPPORTED_FORMAT_VERSION) {
+    throw new RanniError(
+      `relic search reports formatVersion ${String(root.formatVersion)}; this Ranni supports ${SUPPORTED_FORMAT_VERSION}. Update Ranni or Relic so they agree.`,
+    )
+  }
+  if (!Array.isArray(root.results)) throw new RanniError('relic search output has no results array.')
+
+  const items: WorkItem[] = []
+  let federated = false
+  for (const r of root.results as Record<string, unknown>[]) {
+    if (r.type !== undefined && r.type !== 'document') continue
+    if (typeof r.id !== 'string' || typeof r.path !== 'string') continue
+    const project = Array.isArray(r.project) ? (r.project as unknown[]).map(String) : undefined
+    if (project && project.length > 1) federated = true
+    if (r.metadata === null || typeof r.metadata !== 'object' || Array.isArray(r.metadata)) {
+      throw new RanniError(`relic search results carry no metadata. ${MIN_RELIC}`)
+    }
+    const meta = r.metadata as Record<string, unknown>
+    items.push({
+      id: r.id,
+      path: r.path,
+      title: typeof r.label === 'string' ? r.label : r.id,
+      project,
+      waiting: 'waiting' in meta ? waitingText(meta.waiting) : undefined,
+      links: parseLinks(r.links),
+    })
+  }
+  return { items, federated }
+}
+
+function parseLinks(v: unknown): LinkRef[] {
+  if (!Array.isArray(v)) return []
+  const out: LinkRef[] = []
+  for (const l of v as Record<string, unknown>[]) {
+    const target = (l.targetPath ?? l.resolvedPath) as unknown
+    out.push({
+      href: String(l.href ?? ''),
+      text: String(l.text ?? ''),
+      targetPath: typeof target === 'string' ? target : undefined,
+    })
+  }
+  return out
+}
+
+/** The waiting key is set: show its text. A bare key still escalates, with a placeholder. */
+export function waitingText(v: unknown): string {
+  if (v === null || v === undefined || v === '') return ''
+  return String(v).replace(/\s+/g, ' ').trim()
+}
+
+export async function searchWork(
+  run: Runner,
+  cwd: string,
+  kind: string,
+): Promise<{ items: WorkItem[]; federated: boolean }> {
+  const res = await run('relic', ['search', '--kind', kind, '--json'], { cwd })
+  if (res.missing) {
+    throw new RanniError(`relic was not found on PATH. Install Relic. ${MIN_RELIC}`)
+  }
+  if (res.code !== 0) {
+    const err = (res.stderr || res.stdout).trim()
+    if (/unknown option/i.test(err)) {
+      throw new RanniError(`The installed relic has no structured search (${err.split('\n')[0]}). ${MIN_RELIC}`)
+    }
+    throw new RanniError(`relic search failed (exit ${res.code}): ${err || 'no output'}`)
+  }
+  return parseSearch(res.stdout)
+}

package/src/render.ts

@@ -0,0 +1,81 @@
+import { isMergedPr } from './derive'
+import type { ItemStatus, StatusModel } from './status'
+import { LABEL_ORDER, LABEL_TEXT } from './types'
+
+export function formatAge(seconds: number): string {
+  const m = Math.floor(seconds / 60)
+  if (m < 1) return 'now'
+  if (m < 60) return `${m}m`
+  const h = Math.floor(m / 60)
+  if (h < 24) return `${h}h`
+  const d = Math.floor(h / 24)
+  if (d < 14) return `${d}d`
+  const w = Math.floor(d / 7)
+  if (d < 90) return `${w}w`
+  const mo = Math.floor(d / 30)
+  if (d < 365) return `${mo}mo`
+  return `${Math.floor(d / 365)}y`
+}
+
+const plural = (n: number, w: string) => `${n} ${w}${n === 1 ? '' : 's'}`
+
+function prLine(p: ItemStatus['pullRequests'][number]): string {
+  const bits: string[] = []
+  if (p.reviewDecision === 'CHANGES_REQUESTED') bits.push('changes requested')
+  else if (p.reviewDecision === 'APPROVED') bits.push('approved')
+  if (p.unresolvedThreads) bits.push(plural(p.unresolvedThreads, 'unresolved thread'))
+  if (p.failingChecks) bits.push(plural(p.failingChecks, 'failing check'))
+  const draft = p.isDraft ? ' (draft)' : ''
+  return `PR #${p.number}${draft}${bits.length ? ' ' + bits.join(' · ') : ''}`
+}
+
+/** Evidence lines shown under an item, depending on its label. Pure. */
+export function detailLines(it: ItemStatus, defaultBranch?: string): string[] {
+  const lines: string[] = []
+  if (it.label === 'waiting') lines.push(`? ${it.waiting || '(no question written)'}`)
+  const merged = it.pullRequests.filter(p => isMergedPr(p, defaultBranch))
+  const open = it.pullRequests.filter(p => p.state === 'OPEN')
+  if (it.label === 'ready-to-close') {
+    for (const p of merged) lines.push(`PR #${p.number} merged`)
+    const mb = it.branches.filter(b => b.merged)
+    if (merged.length === 0 && mb.length) lines.push(`branch ${mb[0].name} merged into ${defaultBranch ?? 'the default branch'}`)
+    else if (merged.length === 0 && it.mergedTrailerCommits) {
+      lines.push(`${plural(it.mergedTrailerCommits, 'trailer commit')} on ${defaultBranch ?? 'the default branch'}`)
+    }
+  }
+  if (it.label === 'in-review' || it.label === 'waiting') {
+    for (const p of open) lines.push(prLine(p))
+  }
+  if (it.label === 'in-flight') {
+    const parts: string[] = []
+    if (it.branches.length) parts.push(plural(it.branches.length, 'branch'))
+    if (it.trailerCommits) parts.push(plural(it.trailerCommits, 'trailer commit'))
+    lines.push(parts.join(' · '))
+  }
+  for (const l of it.links) lines.push(`→ ${l.id} ${LABEL_TEXT[l.label].toLowerCase()}`)
+  return lines
+}
+
+export function renderHuman(m: StatusModel): string {
+  const out: string[] = []
+  const n = m.items.length
+  out.push(`${m.kind} · ${plural(n, 'item')}${m.defaultBranch ? ` · default branch ${m.defaultBranch}` : ''}`)
+  for (const note of m.notes) out.push(`! ${note}`)
+  if (n === 0) {
+    out.push('', `No work items of kind "${m.kind}".`)
+    return out.join('\n') + '\n'
+  }
+  const idW = Math.max(...m.items.map(i => i.id.length))
+  for (const label of LABEL_ORDER) {
+    const group = m.items.filter(i => i.label === label)
+    if (group.length === 0) continue
+    out.push('', `${LABEL_TEXT[label]} (${group.length})`)
+    for (const it of group) {
+      const age = it.ageSeconds !== undefined ? formatAge(it.ageSeconds) : '-'
+      const where = it.project && it.project.length > 1 ? `[${it.project.slice(1).join('/')}] ` : ''
+      out.push(`  ${it.id.padEnd(idW)}  ${where}${it.title}  ·  ${age}`)
+      for (const l of detailLines(it, m.defaultBranch)) out.push(`  ${' '.repeat(idW)}  ${l}`)
+    }
+  }
+  return out.join('\n') + '\n'
+}

package/src/runner.ts

@@ -0,0 +1,39 @@
+import { execFile } from 'node:child_process'
+
+export interface RunResult {
+  /** Exit code; 127 when the executable could not be started. */
+  code: number
+  stdout: string
+  stderr: string
+  /** True when the executable does not exist or cannot be started. */
+  missing: boolean
+}
+
+export interface RunOptions {
+  cwd?: string
+}
+
+/** The only way Ranni talks to `relic`, `git` and `gh`. Tests inject a fake. */
+export type Runner = (cmd: string, args: string[], opts?: RunOptions) => Promise<RunResult>
+
+export const run: Runner = (cmd, args, opts = {}) =>
+  new Promise(resolve => {
+    execFile(
+      cmd,
+      args,
+      { cwd: opts.cwd, maxBuffer: 256 * 1024 * 1024, encoding: 'utf8' },
+      (err, stdout, stderr) => {
+        if (!err) return resolve({ code: 0, stdout, stderr, missing: false })
+        const e = err as NodeJS.ErrnoException & { code?: number | string }
+        if (e.code === 'ENOENT' || e.code === 'EACCES') {
+          return resolve({ code: 127, stdout: '', stderr: e.message, missing: true })
+        }
+        resolve({
+          code: typeof e.code === 'number' ? e.code : 1,
+          stdout: stdout ?? '',
+          stderr: stderr ?? '',
+          missing: false,
+        })
+      },
+    )
+  })

package/src/status.ts

@@ -0,0 +1,182 @@
+import { derive } from './derive'
+import { RanniError } from './errors'
+import { gitEvidenceFor, markMerged, readMerged, readRepoGit } from './git'
+import { prsFor, readHost, readThreads } from './host'
+import { declaresRecordKind, findProjectRoot } from './project'
+import { searchWork } from './relic'
+import type { Runner } from './runner'
+import { LABEL_ORDER } from './types'
+import type { Evidence, Label, PullRequestEvidence, WorkItem } from './types'
+
+export interface Deps {
+  run: Runner
+  now: Date
+  cwd: string
+  /** Defaults to the nearest relic.yaml ancestor of cwd. Tests may set it. */
+  projectRoot?: string
+}
+
+export interface StatusOptions {
+  kind: string
+  ids: string[]
+}
+
+export interface ItemStatus {
+  id: string
+  title: string
+  path: string
+  project?: string[]
+  label: Label
+  waiting?: string
+  lastActivity?: string
+  ageSeconds?: number
+  branches: { name: string; remote: boolean; date: string; merged?: boolean }[]
+  trailerCommits: number
+  /** Trailer commits on the default branch. Only present in Git-only mode. */
+  mergedTrailerCommits?: number
+  pullRequests: PullRequestEvidence[]
+  links: { id: string; title: string; label: Label }[]
+}
+
+export interface SourceState {
+  available: boolean
+  reason?: string
+}
+
+export interface StatusModel {
+  formatVersion: 1
+  kind: string
+  generatedAt: string
+  root: string
+  defaultBranch?: string
+  sources: { relic: SourceState; git: SourceState; host: SourceState }
+  /** Limitations the reader should know about, in plain language. */
+  notes: string[]
+  items: ItemStatus[]
+}
+
+const sameProject = (a?: string[], b?: string[]) => (a ?? []).join('/') === (b ?? []).join('/')
+
+export async function buildStatus(deps: Deps, opts: StatusOptions): Promise<StatusModel> {
+  const { run, cwd, now } = deps
+  const root = deps.projectRoot ?? findProjectRoot(cwd)
+  if (!root) throw new RanniError('No relic.yaml found above this directory. Run `relic init`, then `ranni init`.')
+
+  const notes: string[] = []
+  const { items: all, federated } = await searchWork(run, root, opts.kind)
+
+  const wanted = opts.ids.map(i => i.toUpperCase())
+  for (const w of wanted) {
+    if (!all.some(i => i.id.toUpperCase() === w)) {
+      throw new RanniError(`No work item ${w} of kind "${opts.kind}"${all.length ? '' : ' (the kind has no items; has `ranni init` run?)'}.`)
+    }
+  }
+
+  if (all.length === 0 && !federated && declaresRecordKind(root, opts.kind) === false) {
+    notes.push(
+      `relic.yaml declares no "${opts.kind}" record kind. Run \`ranni init\` to declare the work kind, or pass --kind with a declared one.`,
+    )
+  }
+
+  if (federated) {
+    notes.push(
+      'Federation: Relic reports member project addresses but not their filesystem roots, so Git evidence comes from the root repository only. Work items of members may show less activity than they have.',
+    )
+  }
+
+  // Git: one for-each-ref and one log for the whole repository.
+  const repoGit = await readRepoGit(run, root)
+  const git = { available: repoGit.available, reason: repoGit.reason }
+  if (!repoGit.available) notes.push(`Git evidence unavailable: ${repoGit.reason}.`)
+
+  // Git host: one PR listing, plus one bounded GraphQL call for open matching PRs.
+  const host = await readHost(run, root)
+  let defaultBranch = host.defaultBranch ?? repoGit.defaultBranch
+  if (!host.available) {
+    notes.push(
+      `Git host evidence unavailable: ${host.reason}. Showing Git evidence only; pull request state, review decisions, threads and checks are missing.`,
+    )
+    if (repoGit.available) {
+      markMerged(repoGit, await readMerged(run, root, repoGit))
+      if (!defaultBranch) notes.push('Default branch unknown: merged branches could not be detected.')
+    }
+  } else {
+    const matchedOpen = new Map<number, PullRequestEvidence>()
+    for (const it of all) {
+      for (const p of prsFor(host.pullRequests, it.id)) if (p.state === 'OPEN') matchedOpen.set(p.number, p)
+    }
+    const th = await readThreads(run, root, host, [...matchedOpen.keys()])
+    for (const [n, c] of th.counts) matchedOpen.get(n)!.unresolvedThreads = c
+    if (th.error) notes.push(`Unresolved review threads unavailable: ${th.error}.`)
+    if (th.skipped > 0) notes.push(`Review threads were read for ${matchedOpen.size - th.skipped} of ${matchedOpen.size} open pull requests (bounded).`)
+    if (host.truncated) notes.push('The pull request listing hit its limit; older pull requests may be missing.')
+  }
+
+  const derived = new Map<WorkItem, { ev: Evidence; label: Label; last?: string }>()
+  for (const it of all) {
+    const gitEv = repoGit.available ? gitEvidenceFor(repoGit, it.id) : { branches: [], commits: [] }
+    const prs: PullRequestEvidence[] = host.available ? prsFor(host.pullRequests, it.id) : []
+    const ev: Evidence = {
+      git: gitEv,
+      pullRequests: prs,
+      mergedByGit: !host.available && (gitEv.branches.some(b => b.merged === true) || gitEv.commits.some(c => c.merged === true)),
+    }
+    const d = derive(it, ev, defaultBranch)
+    derived.set(it, { ev, label: d.label, last: d.lastActivity })
+  }
+
+  const byPath = (it: WorkItem, path: string) =>
+    all.find(o => o !== it && o.path === path && sameProject(o.project, it.project))
+
+  const statuses: ItemStatus[] = all
+    .filter(it => wanted.length === 0 || wanted.includes(it.id.toUpperCase()))
+    .map(it => {
+      const { ev, label, last } = derived.get(it)!
+      const seen = new Set<string>()
+      const links: ItemStatus['links'] = []
+      for (const l of it.links) {
+        if (!l.targetPath) continue
+        const t = byPath(it, l.targetPath)
+        if (!t || seen.has(t.id)) continue
+        seen.add(t.id)
+        links.push({ id: t.id, title: t.title, label: derived.get(t)!.label })
+      }
+      return {
+        id: it.id,
+        title: it.title,
+        path: it.path,
+        ...(it.project ? { project: it.project } : {}),
+        label,
+        ...(it.waiting !== undefined ? { waiting: it.waiting } : {}),
+        ...(last ? { lastActivity: last, ageSeconds: Math.max(0, Math.round((now.getTime() - Date.parse(last)) / 1000)) } : {}),
+        branches: ev.git.branches.map(b => ({ name: b.name, remote: b.remote, date: b.date, ...(b.merged !== undefined ? { merged: b.merged } : {}) })),
+        trailerCommits: ev.git.commits.length,
+        ...(ev.git.commits.some(c => c.merged !== undefined)
+          ? { mergedTrailerCommits: ev.git.commits.filter(c => c.merged).length }
+          : {}),
+        pullRequests: ev.pullRequests,
+        links,
+      }
+    })
+
+  statuses.sort((a, b) => {
+    const la = LABEL_ORDER.indexOf(a.label)
+    const lb = LABEL_ORDER.indexOf(b.label)
+    if (la !== lb) return la - lb
+    const ta = a.lastActivity ? Date.parse(a.lastActivity) : -Infinity
+    const tb = b.lastActivity ? Date.parse(b.lastActivity) : -Infinity
+    if (ta !== tb) return tb - ta
+    return a.id.localeCompare(b.id)
+  })
+
+  return {
+    formatVersion: 1,
+    kind: opts.kind,
+    generatedAt: now.toISOString(),
+    root,
+    ...(defaultBranch ? { defaultBranch } : {}),
+    sources: { relic: { available: true }, git, host: { available: host.available, ...(host.reason ? { reason: host.reason } : {}) } },
+    notes,
+    items: statuses,
+  }
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+export type Label = 'waiting' | 'ready-to-close' | 'in-review' | 'in-flight' | 'not-started'
+
+export const LABEL_ORDER: Label[] = ['waiting', 'ready-to-close', 'in-review', 'in-flight', 'not-started']
+
+export const LABEL_TEXT: Record<Label, string> = {
+  waiting: 'Waiting on you',
+  'ready-to-close': 'Ready to close',
+  'in-review': 'In review',
+  'in-flight': 'In flight',
+  'not-started': 'Not started',
+}
+
+/** A work item as Relic's search read model describes it. */
+export interface WorkItem {
+  id: string
+  /** Path relative to the owning Relic project. */
+  path: string
+  title: string
+  /** Project address in a federated view, root first. Undefined without federation. */
+  project?: string[]
+  /** Set when the waiting key is present; empty string when it carries no question. */
+  waiting?: string
+  /** Outgoing links as resolved by Relic. */
+  links: LinkRef[]
+}
+
+export interface LinkRef {
+  href: string
+  text: string
+  targetPath?: string
+}
+
+export interface BranchEvidence {
+  /** Short name, for example work/WORK-042-push or origin/work/WORK-042-push. */
+  name: string
+  remote: boolean
+  tip: string
+  /** ISO date of the tip commit. */
+  date: string
+  /** Fully merged into the default branch. Only computed in Git-only mode. */
+  merged?: boolean
+}
+
+export interface CommitEvidence {
+  sha: string
+  date: string
+  /** On the default branch. Only computed in Git-only mode. */
+  merged?: boolean
+}
+
+export interface GitEvidence {
+  branches: BranchEvidence[]
+  /** Commits carrying a Work: trailer for the identity. */
+  commits: CommitEvidence[]
+}
+
+export type ReviewDecision = 'CHANGES_REQUESTED' | 'APPROVED' | 'REVIEW_REQUIRED' | ''
+
+export interface PullRequestEvidence {
+  number: number
+  title: string
+  url: string
+  state: 'OPEN' | 'MERGED' | 'CLOSED'
+  isDraft: boolean
+  baseRef: string
+  reviewDecision: ReviewDecision
+  failingChecks: number
+  /** Undefined when threads were not fetched or the fetch failed. */
+  unresolvedThreads?: number
+}
+
+export interface Evidence {
+  git: GitEvidence
+  pullRequests: PullRequestEvidence[]
+  /** Branch fully merged into the default branch counts as merged. */
+  mergedByGit: boolean
+}
+
+export interface Derived {
+  label: Label
+  /** Newest commit or branch tip tied to the identity, ISO. */
+  lastActivity?: string
+}