@erclx/canon 4.0.0

package/src/sessions/resolve.ts

@@ -0,0 +1,333 @@
+import { basename } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+import {
+  type Confidence,
+  liveness,
+  type LivenessProbes,
+  SYSTEM_PROBES,
+} from '@/sessions/live'
+import { readRegistry, type SessionRecord } from '@/sessions/registry'
+
+/** Why a row carries no branch, stated rather than left as an absent key. */
+export type Unresolved =
+  | 'not-a-repository'
+  | 'detached-head'
+  | 'git-unavailable'
+
+export interface ResolvedSession {
+  readonly name: string
+  readonly pid: number
+  readonly sessionId: string | null
+  readonly cwd: string
+  readonly kind: string
+  readonly status: string
+  readonly startedAt: string | null
+  /**
+   * The stamp the record carries beside `status`, kept alongside the dwell it
+   * computes below for a caller comparing two sessions rather than reading the
+   * age of one.
+   */
+  readonly statusUpdatedAt: string | null
+  /**
+   * Elapsed milliseconds since `statusUpdatedAt`, falling back to the coarser
+   * `updatedAt` when the record predates the narrower field, computed once at
+   * read time so three callers do not each convert the raw stamp and each get
+   * the clock-skew case wrong. The one record ever measured carrying
+   * `status: "waiting"` has exactly this shape: no `statusUpdatedAt`, an
+   * `updatedAt` beside it, so a caller reading this field alone would report
+   * the single real instance as unmeasured rather than as stalled.
+   * Clamped at zero rather than reported negative: a record stamped
+   * by a clock running ahead of this one is a skew to absorb, not a session
+   * that has not started waiting yet.
+   */
+  readonly statusDwellMs: number | null
+  /**
+   * The shared git directory every worktree of one repository resolves to,
+   * which is what identifies the repository a row belongs to. A branch name is
+   * unique inside one and says nothing across a machine.
+   */
+  readonly repository: string | null
+  readonly worktree: string | null
+  readonly branch: string | null
+  /** Null exactly when `branch` is set. The two are written together. */
+  readonly unresolved: Unresolved | null
+}
+
+export type SessionReport =
+  | { readonly kind: 'absent'; readonly dir: string }
+  | {
+      readonly kind: 'resolved'
+      readonly dir: string
+      /**
+       * The weakest confidence any surviving row was decided at, so one read
+       * tells a caller whether the roster can be trusted as an identity.
+       */
+      readonly confidence: Confidence
+      readonly sessions: readonly ResolvedSession[]
+    }
+
+export interface ResolveOptions {
+  readonly dir?: string
+  readonly probes?: LivenessProbes
+  readonly locate?: (cwd: string) => Promise<Located>
+  /** The instant the dwell is computed against. Defaults to `Date.now`. */
+  readonly now?: () => number
+}
+
+export interface Located {
+  readonly repository: string | null
+  readonly worktree: string | null
+  readonly branch: string | null
+  readonly unresolved: Unresolved | null
+}
+
+/**
+ * Asks git what a directory is checked out to.
+ *
+ * A detached HEAD and a directory outside any repository are separated here
+ * rather than collapsed into one empty answer, because the first is a session
+ * that has a worktree and no branch and the second has neither.
+ */
+async function locate(cwd: string): Promise<Located> {
+  const top = await $`git -C ${cwd} rev-parse --show-toplevel`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+
+  if (top.exitCode !== 0) {
+    // git absent and git refusing the directory are both non-zero here. The
+    // first is the platform report the plan asked for and the second is an
+    // ordinary answer, so the distinguishing read is whether git ran at all.
+    const version = await $`git --version`.quiet().nothrow()
+    return {
+      repository: null,
+      worktree: null,
+      branch: null,
+      unresolved:
+        version.exitCode === 0 ? 'not-a-repository' : 'git-unavailable',
+    }
+  }
+
+  const worktree = top.stdout.toString().trim()
+  const repository = await repositoryOf(cwd)
+  const head = await $`git -C ${cwd} branch --show-current`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+  const branch = head.stdout.toString().trim()
+
+  if (head.exitCode !== 0 || branch.length === 0) {
+    return { repository, worktree, branch: null, unresolved: 'detached-head' }
+  }
+
+  return { repository, worktree, branch, unresolved: null }
+}
+
+/**
+ * Resolves the shared git directory a working directory belongs to.
+ *
+ * The common directory is what a linked worktree and its main checkout agree
+ * on, so two rows in one repository match here while the toplevel would place
+ * every worktree in a repository of its own.
+ */
+export async function repositoryOf(cwd: string): Promise<string | null> {
+  const dir =
+    await $`git -C ${cwd} rev-parse --path-format=absolute --git-common-dir`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+
+  if (dir.exitCode !== 0) return null
+
+  const resolved = dir.stdout.toString().trim()
+  return resolved.length > 0 ? resolved : null
+}
+
+/**
+ * Falls back to `updatedAt` when `statusUpdatedAt` is absent, since the
+ * narrower field is the newer of the two and a record predating it still
+ * carries the coarser one. The one record measured with `status: "waiting"`
+ * takes exactly this path: no `statusUpdatedAt`, an `updatedAt` beside it.
+ */
+function dwellMs(record: SessionRecord, now: number): number | null {
+  const stamp = record.statusUpdatedAt ?? record.updatedAt
+  return stamp === undefined ? null : Math.max(0, now - stamp)
+}
+
+/**
+ * An absent field is rendered as an absence rather than as a value.
+ *
+ * A missing start time formatted from zero reads as a session launched in 1970
+ * and a missing identifier as an empty one, both of which a caller would take
+ * for data. Null says the record did not carry it, which is the same
+ * distinction the registry draws between an absent folder and an empty one.
+ */
+function present(
+  record: SessionRecord,
+  located: Located,
+  now: number,
+): ResolvedSession {
+  return {
+    name: record.name,
+    pid: record.pid,
+    sessionId: record.sessionId ?? null,
+    cwd: record.cwd,
+    kind: record.kind ?? 'unknown',
+    status: record.status ?? 'unknown',
+    startedAt:
+      record.startedAt === undefined
+        ? null
+        : new Date(record.startedAt).toISOString(),
+    statusUpdatedAt:
+      record.statusUpdatedAt === undefined
+        ? null
+        : new Date(record.statusUpdatedAt).toISOString(),
+    statusDwellMs: dwellMs(record, now),
+    repository: located.repository,
+    worktree: located.worktree,
+    branch: located.branch,
+    unresolved: located.unresolved,
+  }
+}
+
+/**
+ * Resolves every live session to the worktree and branch it holds.
+ *
+ * The registry is the whole source. Each session writes its own working
+ * directory beside its own name, so a caller matching a listing row to a branch
+ * reads both from one record instead of ordering the roster by start time and
+ * hoping the order holds.
+ *
+ * A row whose branch cannot be read is kept and marked. Dropping it would leave
+ * a caller unable to tell a session that holds no branch from one the resolver
+ * never saw, and the second is the failure this replaces.
+ */
+export async function resolveSessions(
+  opts: ResolveOptions = {},
+): Promise<SessionReport> {
+  const probes = opts.probes ?? SYSTEM_PROBES
+  const find = opts.locate ?? locate
+  const now = opts.now?.() ?? Date.now()
+  const registry = readRegistry(opts.dir)
+
+  if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
+
+  const live: SessionRecord[] = []
+  let confidence: Confidence = 'confirmed'
+
+  for (const record of registry.records) {
+    const state = liveness(record, probes)
+    if (!state.alive) continue
+    if (state.confidence === 'unverified') confidence = 'unverified'
+    live.push(record)
+  }
+
+  const sessions = await Promise.all(
+    live.map(async (record) => present(record, await find(record.cwd), now)),
+  )
+
+  return { kind: 'resolved', dir: registry.dir, confidence, sessions }
+}
+
+/** The environment slice the caller's own identity is read from. */
+export type Env = Record<string, string | undefined>
+
+/** Why the caller's own row could not be named, rather than an empty result. */
+export type SelfUnresolved = 'no-identity' | 'no-row'
+
+/**
+ * What the environment offers about the session making the call.
+ *
+ * Both fields are candidates rather than a pair, since a client sets them
+ * independently and a caller can arrive carrying either one alone.
+ */
+export interface SelfIdentity {
+  readonly sessionId: string | null
+  readonly pid: number | null
+}
+
+export type SelfReport =
+  | { readonly kind: 'self'; readonly session: ResolvedSession }
+  | {
+      readonly kind: 'unresolved'
+      readonly reason: SelfUnresolved
+      readonly identity: SelfIdentity
+    }
+
+/**
+ * A positive integer, which is what separates a pid from a socket named for
+ * something else. Signal zero addresses the caller's own process group, so a
+ * zero would match a row rather than failing to.
+ */
+function pidOf(value: string | undefined): number | null {
+  if (value === undefined) return null
+  const pid = Number(value.trim())
+  return Number.isInteger(pid) && pid > 0 ? pid : null
+}
+
+/**
+ * Reads whatever the environment states about the calling session.
+ *
+ * Three identifier namespaces are in play and only two of them join to a
+ * roster row. `CLAUDE_CODE_SESSION_ID` is the roster's own `sessionId` and is
+ * read first because it survives a rename, where the name a session carries is
+ * derived from what it turned out to be doing and rotates while a build runs.
+ * `CLAUDE_CODE_HOST_SESSION_ID` is deliberately never read: it holds a
+ * `local_`-prefixed value from the harness namespace that matches no row, and
+ * it is the variable a reader searching the environment for a session id finds
+ * first.
+ *
+ * The socket path is the last rung because its basename is the caller's pid by
+ * a client convention rather than a published interface, so a client that
+ * moves it drops this rung while leaving the two above it standing.
+ */
+export function callerIdentity(env: Env = process.env): SelfIdentity {
+  const stated = env.CLAUDE_CODE_SESSION_ID?.trim()
+  const socket = env.CLAUDE_CODE_MESSAGING_SOCKET
+
+  return {
+    sessionId: stated !== undefined && stated.length > 0 ? stated : null,
+    pid:
+      pidOf(env.CLAUDE_PID) ??
+      pidOf(
+        socket === undefined
+          ? undefined
+          : basename(socket).replace(/\.sock$/, ''),
+      ),
+  }
+}
+
+/**
+ * Names which row of a roster belongs to the caller.
+ *
+ * The read that already returns every field marks none of them as the caller,
+ * so this performs the join rather than adding a source. An identity the
+ * environment does not carry and an identity no row matches are separated,
+ * because the first is a client that states nothing and the second is a
+ * session the roster cannot see. A session driving from Remote Control is the
+ * measured instance of the second: it is addressable on the message channel
+ * and holds no local process record for the roster to report.
+ */
+export function selfOf(
+  sessions: readonly ResolvedSession[],
+  identity: SelfIdentity,
+): SelfReport {
+  if (identity.sessionId === null && identity.pid === null) {
+    return { kind: 'unresolved', reason: 'no-identity', identity }
+  }
+
+  const byId =
+    identity.sessionId === null
+      ? undefined
+      : sessions.find((session) => session.sessionId === identity.sessionId)
+  const byPid =
+    identity.pid === null
+      ? undefined
+      : sessions.find((session) => session.pid === identity.pid)
+  const match = byId ?? byPid
+
+  return match === undefined
+    ? { kind: 'unresolved', reason: 'no-row', identity }
+    : { kind: 'self', session: match }
+}

package/src/slides/layouts.ts

@@ -0,0 +1,391 @@
+import type PptxGenJS from 'pptxgenjs'
+import type { Slide } from '@/slides/parse'
+import { FONTS, type Theme, TYPE } from '@/slides/styles'
+
+type Deck = InstanceType<typeof PptxGenJS>
+type PptxSlide = ReturnType<Deck['addSlide']>
+
+export interface LayoutInfo {
+  name: string
+  description: string
+}
+
+export interface NavEntry {
+  title: string
+  slideNumber: number
+}
+
+export interface DeckNav {
+  deckTitle: string
+  tocSlide?: number
+  sections: NavEntry[]
+}
+
+export const LAYOUTS: LayoutInfo[] = [
+  { name: 'title', description: 'Cover slide with deck title and subtitle' },
+  { name: 'toc', description: 'Contents slide linking to each section' },
+  { name: 'section', description: 'Section divider with one large heading' },
+  { name: 'bullets', description: 'Title above a bullet list' },
+  { name: 'two-column', description: 'Two labeled columns of bullets' },
+  { name: 'stat-callout', description: 'Row of large stats with captions' },
+  { name: 'grid', description: 'Two-by-two cards, each a term and detail' },
+  { name: 'quote', description: 'Large pull quote with attribution' },
+]
+
+const W = 13.333
+const H = 7.5
+const MX = 0.7
+const CW = W - MX * 2
+const BODY_Y = 1.7
+
+const RENDERERS: Record<
+  string,
+  (s: PptxSlide, slide: Slide, theme: Theme) => void
+> = {
+  title: renderTitle,
+  section: renderSection,
+  bullets: renderBullets,
+  'two-column': renderTwoColumn,
+  'stat-callout': renderStatCallout,
+  grid: renderGrid,
+  quote: renderQuote,
+}
+
+export function renderDeckSlide(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+): void {
+  const renderer = RENDERERS[slide.layout] ?? renderBullets
+  renderer(s, slide, theme)
+}
+
+export function renderToc(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+  nav: DeckNav,
+): void {
+  addTitle(s, slide.title || 'Contents', theme)
+  if (nav.sections.length === 0) return
+  s.addText(
+    nav.sections.map((entry) => ({
+      text: entry.title,
+      options: { breakLine: true, hyperlink: { slide: entry.slideNumber } },
+    })),
+    {
+      x: MX,
+      y: BODY_Y,
+      w: CW,
+      h: 5,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body + 2,
+      color: theme.accent,
+      valign: 'top',
+      lineSpacingMultiple: 1.6,
+    },
+  )
+}
+
+export function addFooter(
+  s: PptxSlide,
+  slide: Slide,
+  theme: Theme,
+  nav: DeckNav,
+): void {
+  if (slide.layout === 'title' || slide.layout === 'toc') return
+  if (nav.deckTitle) {
+    s.addText(nav.deckTitle, {
+      x: MX,
+      y: H - 0.5,
+      w: CW / 2,
+      h: 0.3,
+      fontFace: FONTS.body,
+      fontSize: TYPE.caption,
+      color: theme.muted,
+      valign: 'middle',
+    })
+  }
+  if (nav.tocSlide) {
+    s.addText('Contents', {
+      x: MX + CW / 2,
+      y: H - 0.5,
+      w: CW / 2,
+      h: 0.3,
+      fontFace: FONTS.body,
+      fontSize: TYPE.caption,
+      color: theme.muted,
+      align: 'right',
+      valign: 'middle',
+      hyperlink: { slide: nav.tocSlide },
+    })
+  }
+}
+
+function renderTitle(s: PptxSlide, slide: Slide, theme: Theme): void {
+  s.addText(clean(slide.title), {
+    x: MX,
+    y: 2.6,
+    w: CW,
+    h: 1.4,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.cover,
+    bold: true,
+    color: theme.ink,
+    valign: 'top',
+  })
+  const subtitle = slide.content.join(' ').trim()
+  if (subtitle) {
+    s.addText(clean(subtitle), {
+      x: MX,
+      y: 4.1,
+      w: CW,
+      h: 1,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body + 4,
+      color: theme.muted,
+      valign: 'top',
+    })
+  }
+}
+
+function renderSection(s: PptxSlide, slide: Slide, theme: Theme): void {
+  s.addText(clean(slide.title), {
+    x: MX,
+    y: 2.9,
+    w: CW,
+    h: 1.6,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.section,
+    bold: true,
+    color: theme.accent,
+    valign: 'middle',
+  })
+}
+
+function renderBullets(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const items = bullets(slide.content)
+  if (items.length === 0) return
+  s.addText(
+    items.map((text) => ({
+      text,
+      options: { bullet: { code: '2022' }, breakLine: true },
+    })),
+    {
+      x: MX,
+      y: BODY_Y,
+      w: CW,
+      h: 5,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      color: theme.ink,
+      valign: 'top',
+      lineSpacingMultiple: 1.3,
+      paraSpaceAfter: 10,
+    },
+  )
+}
+
+function renderTwoColumn(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const cols = columns(slide.content)
+  const gap = 0.6
+  const colWidth = (CW - gap) / 2
+  cols.slice(0, 2).forEach((col, index) => {
+    const x = MX + index * (colWidth + gap)
+    s.addText(col.heading, {
+      x,
+      y: BODY_Y,
+      w: colWidth,
+      h: 0.6,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.body + 4,
+      bold: true,
+      color: theme.accent,
+      valign: 'top',
+    })
+    if (col.items.length === 0) return
+    s.addText(
+      col.items.map((text) => ({
+        text,
+        options: { bullet: { code: '2022' }, breakLine: true },
+      })),
+      {
+        x,
+        y: BODY_Y + 0.7,
+        w: colWidth,
+        h: 4.3,
+        fontFace: FONTS.body,
+        fontSize: TYPE.body,
+        color: theme.ink,
+        valign: 'top',
+        lineSpacingMultiple: 1.3,
+        paraSpaceAfter: 8,
+      },
+    )
+  })
+}
+
+function renderStatCallout(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const stats = pairs(slide.content).slice(0, 4)
+  if (stats.length === 0) return
+  const gap = 0.5
+  const cellWidth = (CW - gap * (stats.length - 1)) / stats.length
+  stats.forEach((stat, index) => {
+    const x = MX + index * (cellWidth + gap)
+    s.addText(stat.left, {
+      x,
+      y: 2.6,
+      w: cellWidth,
+      h: 1.3,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.stat,
+      bold: true,
+      color: theme.accent,
+      align: 'left',
+      valign: 'top',
+    })
+    s.addText(stat.right, {
+      x,
+      y: 3.9,
+      w: cellWidth,
+      h: 1.4,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      color: theme.muted,
+      align: 'left',
+      valign: 'top',
+    })
+  })
+}
+
+function renderGrid(s: PptxSlide, slide: Slide, theme: Theme): void {
+  addTitle(s, slide.title, theme)
+  const cards = pairs(slide.content).slice(0, 4)
+  const gap = 0.5
+  const cardWidth = (CW - gap) / 2
+  const cardHeight = 2.1
+  cards.forEach((card, index) => {
+    const col = index % 2
+    const row = Math.floor(index / 2)
+    const x = MX + col * (cardWidth + gap)
+    const y = BODY_Y + row * (cardHeight + gap)
+    s.addShape('roundRect', {
+      x,
+      y,
+      w: cardWidth,
+      h: cardHeight,
+      fill: { color: theme.surface },
+      line: { type: 'none' },
+      rectRadius: 0.08,
+    })
+    s.addText(card.left, {
+      x: x + 0.3,
+      y: y + 0.25,
+      w: cardWidth - 0.6,
+      h: 0.6,
+      fontFace: FONTS.heading,
+      fontSize: TYPE.body + 4,
+      bold: true,
+      color: theme.ink,
+      valign: 'top',
+    })
+    s.addText(card.right, {
+      x: x + 0.3,
+      y: y + 0.95,
+      w: cardWidth - 0.6,
+      h: cardHeight - 1.2,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body - 2,
+      color: theme.ink,
+      valign: 'top',
+      lineSpacingMultiple: 1.2,
+    })
+  })
+}
+
+function renderQuote(s: PptxSlide, slide: Slide, theme: Theme): void {
+  const lines = slide.content
+  const attribution = lines.find((line) => /^(—|-)\s/.test(line.trim()))
+  const quote = lines
+    .filter((line) => line !== attribution)
+    .join(' ')
+    .trim()
+  s.addText(clean(quote), {
+    x: MX,
+    y: 2.2,
+    w: CW,
+    h: 2.6,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.quote,
+    italic: true,
+    color: theme.ink,
+    valign: 'top',
+    lineSpacingMultiple: 1.25,
+  })
+  if (attribution) {
+    s.addText(clean(attribution.replace(/^(—|-)\s+/, '')), {
+      x: MX,
+      y: 5,
+      w: CW,
+      h: 0.6,
+      fontFace: FONTS.body,
+      fontSize: TYPE.body,
+      bold: true,
+      color: theme.accent,
+      valign: 'top',
+    })
+  }
+}
+
+function addTitle(s: PptxSlide, title: string, theme: Theme): void {
+  if (!title) return
+  s.addText(clean(title), {
+    x: MX,
+    y: 0.5,
+    w: CW,
+    h: 0.9,
+    fontFace: FONTS.heading,
+    fontSize: TYPE.title,
+    bold: true,
+    color: theme.ink,
+    valign: 'top',
+  })
+}
+
+function clean(text: string): string {
+  return text.replace(/\*\*/g, '').replace(/`/g, '').trim()
+}
+
+function bullets(content: string[]): string[] {
+  return content
+    .filter((line) => line.trim().startsWith('-'))
+    .map((line) => clean(line.replace(/^\s*-\s+/, '')))
+}
+
+function pairs(content: string[]): { left: string; right: string }[] {
+  return content
+    .filter((line) => line.trim().startsWith('-'))
+    .map((line) => line.replace(/^\s*-\s+/, ''))
+    .map((line) => {
+      const [left, ...rest] = line.split(/\s*:\s*/)
+      return { left: clean(left), right: clean(rest.join(': ')) }
+    })
+}
+
+function columns(content: string[]): { heading: string; items: string[] }[] {
+  const cols: { heading: string; items: string[] }[] = []
+  for (const line of content) {
+    const heading = line.match(/^##\s+(.+)/)
+    if (heading) {
+      cols.push({ heading: clean(heading[1]), items: [] })
+      continue
+    }
+    if (line.trim().startsWith('-') && cols.length > 0) {
+      cols[cols.length - 1].items.push(clean(line.replace(/^\s*-\s+/, '')))
+    }
+  }
+  return cols
+}