@marcomigozzi/trailhead 0.15.0 → 0.16.0

package/plugins/trailhead/hooks/mod/auto-run.ts

@@ -0,0 +1,165 @@
+// The autonomous run seen from the main checkout (#296): which slots are in flight and the scope counts.
+// Read-only: the mod only watches, it never writes a work state or the tracker. Pure parts are in
+// auto-run-view.ts; here the engine part that scans the checkouts and reads the counts.
+import type { EngineInterface } from 'claude-code'
+
+import type { AutoRun, RepoPin, RunCounts, WorkState } from '../../types'
+import { GH_TIMEOUT_MS, MIN_REFRESH_MS } from './map-pane'
+import { aggregateRun, isRunMember, nextRunAfterFailure, parseRunCounts, parseRunScope, runCountsArgs, slotTicket } from './auto-run-view'
+import type { Where } from './auto-run-view'
+import { pinKey } from './repo-pin'
+import { listSiblings, listWorktreeBranches, readAt, trim } from './work-state-locate'
+import { isMissing, parseWorkState } from './work-state-view'
+
+const RECORD_PATH = '.trailhead/auto-run.json'
+const GIT_TIMEOUT_MS = 5_000
+
+// L'ultimo run noto e i fallimenti di fila (con l'istante dell'ultimo contato): sono macchinario del modulo, non stato disegnato.
+let lastRun: AutoRun | null = null
+let failures = 0
+let lastFailureAt: number | null = null
+let counts: { key: string; at: number; value: RunCounts | null } | null = null
+
+export const resetAutoRun = (): void => {
+  lastRun = null
+  failures = 0
+  lastFailureAt = null
+  counts = null
+}
+
+// Il run sparisce: anche i conteggi e il loro pavimento.
+export const clearRunCounts = (): void => {
+  counts = null
+}
+
+type Gate = { kind: 'closed' } | { kind: 'open'; scope: string | null } | { kind: 'failed' }
+
+// Il run può esistere solo se c'è il record o lo stato proprio è auto: altrimenti nessun processo parte.
+async function gate($: EngineInterface, main: string, own: WorkState | null): Promise<Gate> {
+  try {
+    const text = (await $.fs.read(`${trim(main)}/${RECORD_PATH}`)) as string
+    return { kind: 'open', scope: parseRunScope(text) }
+  } catch (err) {
+    if (!isMissing(err)) return own?.auto === true ? { kind: 'open', scope: null } : { kind: 'failed' }
+    return own?.auto === true ? { kind: 'open', scope: null } : { kind: 'closed' }
+  }
+}
+
+// La regola di cloneOnBranch (trailhead-auto-slot.js): git dir dentro la cartella e HEAD sul branch dello slot.
+// undefined: git non è riuscito a girare.
+async function cloneOnBranch($: EngineInterface, dir: string, ticket: number): Promise<boolean | undefined> {
+  const git = (args: string[]) => $.process.run(['git', '-C', dir, ...args], { cwd: dir, timeoutMs: GIT_TIMEOUT_MS })
+  try {
+    const g = await git(['rev-parse', '--absolute-git-dir'])
+    if (g.exitCode !== 0) return false
+    const gitDir = trim(g.stdout.trim())
+    if (gitDir !== dir && !gitDir.startsWith(`${dir}/`)) return false
+    const b = await git(['symbolic-ref', '--quiet', 'HEAD'])
+    return b.exitCode === 0 && b.stdout.trim() === `refs/heads/trailhead/t${ticket}`
+  } catch {
+    return undefined
+  }
+}
+
+type Candidate = { path: string; where: Where | { kind: 'sibling'; ticket: number } }
+
+// Un checkout alla volta, senza doppioni: vince la grafia di git, il main e il pin contano come main.
+const candidatesOf = (main: string, pinned: string, listed: readonly { path: string; branch: string | null }[], siblings: readonly string[]): Candidate[] => {
+  const all: Candidate[] = [{ path: trim(main), where: { kind: 'main' } }]
+  if (trim(pinned) !== trim(main)) all.push({ path: trim(pinned), where: { kind: 'main' } })
+  for (const w of listed) {
+    const ticket = slotTicket(w.branch)
+    if (ticket !== null) all.push({ path: trim(w.path), where: { kind: 'worktree', ticket } })
+  }
+  for (const path of siblings) {
+    const ticket = Number(/-t(\d+)$/.exec(path)?.[1])
+    if (ticket > 0) all.push({ path: trim(path), where: { kind: 'sibling', ticket } })
+  }
+  return all.filter((c, i) => all.findIndex(o => o.path === c.path) === i)
+}
+
+type Scan = { ok: true; run: AutoRun | null } | { ok: false }
+
+async function scan($: EngineInterface, main: string, pinned: string): Promise<Scan> {
+  const listed = await listWorktreeBranches($, main)
+  const siblings = await listSiblings($, main)
+  if (listed === null || siblings === null) return { ok: false }
+  const candidates = candidatesOf(main, pinned, listed, siblings)
+  const texts = await Promise.all(candidates.map(c => readAt($, c.path)))
+  if (texts.includes(undefined)) return { ok: false }
+  const members: WorkState[] = []
+  for (const [i, c] of candidates.entries()) {
+    const text = texts[i]
+    const state = typeof text === 'string' ? parseWorkState(text) : null
+    if (state === null || !state.auto) continue
+    let where: Where
+    if (c.where.kind === 'sibling') {
+      // Il controllo git costa due processi: solo per un fratello il cui stato è già auto del suo ticket.
+      if (state.ticket !== c.where.ticket) continue
+      const onBranch = await cloneOnBranch($, c.path, c.where.ticket)
+      if (onBranch === undefined) return { ok: false }
+      where = { kind: 'clone', ticket: c.where.ticket, onBranch }
+    } else where = c.where
+    if (isRunMember(where, state)) members.push(state)
+  }
+  return { ok: true, run: aggregateRun(members) }
+}
+
+// Un turno fa più refresh: un fallimento conta solo se dall'ultimo contato è passato MIN_REFRESH_MS,
+// così un singhiozzo breve di git non azzera un run vivo. Senza orologio ogni fallimento conta.
+async function isNewFailure($: EngineInterface): Promise<boolean> {
+  const now = await nowOf($)
+  if (now === null) return true
+  if (lastFailureAt !== null && now - lastFailureAt < MIN_REFRESH_MS) return false
+  lastFailureAt = now
+  return true
+}
+
+// Il run attuale e lo scope del record. Una scansione fallita tiene l'ultimo risultato per al massimo
+// MAX_FAILURES volte di fila; un miss pulito o il gate chiuso lo azzerano subito.
+export async function scanRun($: EngineInterface, input: { main: string; pinned: string; ownState: WorkState | null }): Promise<{ run: AutoRun | null; scope: string | null }> {
+  const g = await gate($, input.main, input.ownState)
+  if (g.kind === 'closed') {
+    lastRun = null
+    failures = 0
+    lastFailureAt = null
+    return { run: null, scope: null }
+  }
+  const result = g.kind === 'open' ? await scan($, trim(input.main), input.pinned) : ({ ok: false } as const)
+  if (result.ok) {
+    failures = 0
+    lastFailureAt = null
+    lastRun = result.run
+  } else if (await isNewFailure($)) {
+    failures += 1
+    lastRun = nextRunAfterFailure(lastRun, failures)
+  }
+  return { run: lastRun, scope: g.kind === 'open' ? g.scope : null }
+}
+
+async function nowOf($: EngineInterface): Promise<number | null> {
+  try {
+    return await $.clock.now()
+  } catch {
+    return null
+  }
+}
+
+// I conteggi dello scope, mai più spesso di MIN_REFRESH_MS; una lettura fallita tiene gli ultimi.
+export async function readRunCounts($: EngineInterface, pin: RepoPin, scope: string | null): Promise<RunCounts | null> {
+  const key = `${pinKey(pin)}|${scope ?? ''}`
+  const now = await nowOf($)
+  const cached = counts !== null && counts.key === key ? counts : null
+  // Senza orologio non c'è pavimento: niente gh a ruota libera, vale il valore in cache (o nulla).
+  if (now === null) return cached?.value ?? null
+  if (cached !== null && now - cached.at < MIN_REFRESH_MS) return cached.value
+  let value = cached?.value ?? null
+  try {
+    const out = await $.process.run(['gh', ...runCountsArgs(pin.host, pin.slug, scope)], { cwd: pin.root, timeoutMs: GH_TIMEOUT_MS })
+    if (out.exitCode === 0) value = parseRunCounts(out.stdout) ?? value
+  } catch {
+    // Lettura fallita: restano gli ultimi conteggi.
+  }
+  counts = { key, at: now, value }
+  return value
+}

package/plugins/trailhead/hooks/mod/map-pane-view.ts

@@ -1,13 +1,14 @@
 // Pure view logic of the map pane: parse what `gh` printed, group the rows, word a
 // failure and an age, decide when a refresh may run. No engine calls here, so it is easy to test.
 import { fit } from './work-state-view'
-import type { BurndownHistory, BurndownIssue, DashboardRef, MapCounts, MapInfo, MapsRead, MapSummary, PaneTicket, TicketState, TicketType, UatParent } from '../../types'
+import type { BurndownHistory, BurndownIssue, DashboardRef, MapCounts, MapInfo, MapsRead, MapSummary, OpenTotal, PaneTicket, TicketState, TicketType, UatParent } from '../../types'
 
 export const TICKET_TYPES: readonly TicketType[] = ['decision', 'research', 'prototype', 'build', 'bug', 'task']
 
 // `isCapped`: gh returned as many rows as it was asked for, so the list may be cut.
 export type ParsedTickets = { tickets: readonly PaneTicket[]; unverifiedCount: number; isCapped: boolean }
 export type TicketGroups = {
+  needsYou: readonly PaneTicket[]
   frontier: readonly PaneTicket[]
   inProgress: readonly PaneTicket[]
   uat: readonly PaneTicket[]
@@ -68,17 +69,10 @@ const stateOf = (names: readonly string[], assignees: readonly string[]): Ticket
 // Only an https link is kept; anything else would be drawn as plain text.
 const safeUrl = (raw: unknown): string => (typeof raw === 'string' && /^https:\/\//.test(raw) ? raw : '')
 
-// `gh issue list --json number,title,labels,assignees,url`. Unverified rows are
-// quarantined (counted, never listed); whiteboard rows do not belong to a map, and on the
-// whiteboard (`isWhiteboard`) only they are kept.
-export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } = {}): ParsedTickets | null => {
-  let raw: unknown
-  try {
-    raw = JSON.parse(stdout)
-  } catch {
-    return null
-  }
-  if (!Array.isArray(raw)) return null
+// The rows of an open-ticket list (the `gh issue list --json number,title,labels,assignees,url` shape).
+// Unverified rows are quarantined (counted, never listed); whiteboard rows do not belong to a map, and on the
+// whiteboard (`isWhiteboard`) only they are kept. A list that reached LIST_LIMIT rows is capped.
+export const ticketsFromRows = (raw: readonly unknown[], opts: { isWhiteboard?: boolean } = {}): ParsedTickets => {
   const rows = raw.filter(isRecord).filter(r => isPosInt(r.number))
   const named = rows.map(r => ({ r, names: labelNames(r.labels) }))
   const unverifiedCount = named.filter(({ names }) => names.includes(`${LABEL_PREFIX}unverified`)).length
@@ -95,13 +89,61 @@ export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } =
         assignees,
         url: safeUrl(r.url),
         isUat: names.includes(`${LABEL_PREFIX}uat`),
+        isNeedsYou: names.includes(`${LABEL_PREFIX}needs-you`),
         uatOf: null,
       }
     })
   return { tickets, unverifiedCount, isCapped: raw.length >= LIST_LIMIT }
 }
 
-// `gh issue list --label trailhead:uat ... --json number,body`: ticket number -> the parent its first
+// `gh issue list --json ...` output as a ticket list; not a list is unreadable (null).
+export const parseTickets = (stdout: string, opts: { isWhiteboard?: boolean } = {}): ParsedTickets | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  return Array.isArray(raw) ? ticketsFromRows(raw, opts) : null
+}
+
+// The rows that carry `name`: a GraphQL `labels:` filter is any-of, so an AND of two labels is done here.
+export const withLabel = (rows: readonly unknown[], name: string): unknown[] =>
+  rows.filter(r => isRecord(r) && labelNames(r.labels).includes(name))
+
+export type IssuesPage = { rows: unknown[]; hasNextPage: boolean; endCursor: string | null }
+
+// One page of the GraphQL open-ticket read (`repository.issues(...){nodes{...}pageInfo{...}}`), its nodes
+// flattened to the rows `gh issue list --json` prints so one parser serves both (`body` rides along only when
+// the node has a string one, so the ticket rows keep their shape). Any `errors` (even beside
+// partial `data`), a missing page info or a next page without a cursor is unreadable: the caller decides (`readOpen` falls back to
+// `gh issue list`, `readUat` fails closed to null).
+export const parseIssuesPage = (stdout: string): IssuesPage | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  if (!isRecord(raw) || 'errors' in raw || !isRecord(raw.data) || !isRecord(raw.data.repository)) return null
+  const issues = raw.data.repository.issues
+  if (!isRecord(issues) || !Array.isArray(issues.nodes) || !isRecord(issues.pageInfo)) return null
+  const { hasNextPage, endCursor } = issues.pageInfo
+  if (typeof hasNextPage !== 'boolean') return null
+  if (hasNextPage && (typeof endCursor !== 'string' || endCursor === '')) return null
+  const inner = (v: unknown) => (isRecord(v) && Array.isArray(v.nodes) ? v.nodes : [])
+  const rows = issues.nodes.filter(isRecord).map(n => ({
+    number: n.number,
+    title: n.title,
+    url: n.url,
+    labels: inner(n.labels),
+    assignees: inner(n.assignees),
+    ...(typeof n.body === 'string' ? { body: n.body } : {}),
+  }))
+  return { rows, hasNextPage, endCursor: hasNextPage ? (endCursor as string) : null }
+}
+
+// The open `trailhead:uat` rows of the GraphQL read, as JSON (`number` and `body`): ticket number -> the parent its first
 // `UAT of:` line names, `[<name>](<url>/issues/<n>)` (or a bare `#<n>`, with an empty title). A row with
 // no such line, or an unreadable one, is skipped; not a list is unreadable (null).
 export const parseUatParents = (stdout: string): ReadonlyMap<number, UatParent> | null => {
@@ -237,7 +279,55 @@ export const parseMapsRead = (stdout: string): MapsRead | null => {
       }),
     )
     .sort((a, b) => a.number - b.number)
-  return { maps, whiteboard: whiteboardOf(repo) }
+  return { maps, whiteboard: whiteboardOf(repo), isMapsCapped: isCappedBy(issues, nodes.length) }
+}
+
+// More open maps exist than the read returned (`totalCount` above the nodes read); without a usable
+// `totalCount` a read that filled MAPS_READ_LIMIT is taken as cut.
+const isCappedBy = (issues: Record<string, unknown>, read: number): boolean => {
+  const count = totalOf(issues)
+  return count === null ? read >= MAPS_READ_LIMIT : count > read
+}
+
+// The most open maps one maps read asks for.
+export const MAPS_READ_LIMIT = 100
+
+// One query counting the open tickets of every open map and of the whiteboard: the dashboard's own scopes
+// (a ticket carries one map label or the whiteboard label, never both, so nothing counts twice).
+export const openTotalQuery = (maps: readonly number[]): string => {
+  const scope = (alias: string, label: string) => `${alias}:issues(states:OPEN,labels:["${label}"]){totalCount}`
+  const fields = [...maps.map(n => scope(`m${n}`, `${LABEL_PREFIX}map-${n}`)), scope('wb', `${LABEL_PREFIX}whiteboard`)]
+  return `query($owner:String!,$repo:String!){repository(owner:$owner,name:$repo){${fields.join('')}}}`
+}
+
+// The sum of every alias of `openTotalQuery`; any `errors`, a missing alias or an unusable count is
+// unreadable (null), never a partial sum shown as exact.
+export const parseOpenTotal = (stdout: string, maps: readonly number[]): number | null => {
+  let raw: unknown
+  try {
+    raw = JSON.parse(stdout)
+  } catch {
+    return null
+  }
+  if (!isRecord(raw) || 'errors' in raw || !isRecord(raw.data) || !isRecord(raw.data.repository)) return null
+  const repo = raw.data.repository
+  const counts = [...maps.map(n => totalOf(repo[`m${n}`])), totalOf(repo.wb)]
+  return counts.some(c => c === null) ? null : counts.reduce((sum: number, c) => sum + (c as number), 0)
+}
+
+// The last good total, kept through a failed count read only while it was computed over exactly these open
+// maps (and the same cut of the maps read); a changed map set hides it rather than show it stale.
+export const keepOpenTotal = (kept: OpenTotal | null, maps: readonly number[], isMapsCapped: boolean): OpenTotal | null =>
+  kept !== null && kept.isMapsCapped === isMapsCapped && kept.maps.length === maps.length && kept.maps.every((n, i) => n === maps[i]) ? kept : null
+
+// The line of the total, long form first, the short one when that does not fit, null when unknown or when
+// not even the short one fits. A truncated maps read is a lower bound, worded as one.
+export const openTotalLabel = (total: number | null, isCapped: boolean, columns: number): string | null => {
+  if (total === null) return null
+  const long = `${isCapped ? 'at least ' : ''}${total} open across all maps + whiteboard`
+  if (long.length <= columns) return long
+  const short = `${isCapped ? '≥' : ''}${total} open in total`
+  return short.length <= columns ? short : null
 }
 
 // `gh issue list --label trailhead:dashboard --json number,url`: the pinned index, the lowest number
@@ -322,13 +412,13 @@ export const whiteboardHeading = (tickets: readonly PaneTicket[] | null, isCappe
 
 const byNumber = (a: PaneTicket, b: PaneTicket) => a.number - b.number
 
-// Paused wins, then a UAT ticket (whatever its state), then the state: each ticket shows once.
-type Place = TicketState | 'uat'
-const placeOf = (t: PaneTicket): Place => (t.state === 'paused' ? 'paused' : t.isUat ? 'uat' : t.state)
+// Needs-you wins, then paused, then a UAT ticket (whatever its state), then the state: each ticket shows once.
+type Place = TicketState | 'uat' | 'needs-you'
+const placeOf = (t: PaneTicket): Place => (t.isNeedsYou ? 'needs-you' : t.state === 'paused' ? 'paused' : t.isUat ? 'uat' : t.state)
 
 export const groupTickets = (tickets: readonly PaneTicket[]): TicketGroups => {
   const of = (place: Place) => tickets.filter(t => placeOf(t) === place).sort(byNumber)
-  return { frontier: of('frontier'), inProgress: of('in-progress'), uat: of('uat'), paused: of('paused'), blocked: of('blocked') }
+  return { needsYou: of('needs-you'), frontier: of('frontier'), inProgress: of('in-progress'), uat: of('uat'), paused: of('paused'), blocked: of('blocked') }
 }
 
 const errorText = (err: unknown): string => {
@@ -358,6 +448,10 @@ export const refreshDecision = (now: number, lastStartedAt: number | null, minMs
   return waitMs <= 0 ? { run: true } : { run: false, waitMs }
 }
 
+// A host timer dies silently (a refused `clock.after` never fires, a refused `every` period ends the
+// interval): one whose due time is past by more than the grace is held dead and started again.
+export const isTimerLate = (now: number, dueAt: number, graceMs: number): boolean => now - dueAt > graceMs
+
 export const ageLabel = (ms: number): string => {
   if (ms < 5_000) return 'just now'
   if (ms < 60_000) return `${Math.floor(ms / 1_000)}s ago`
@@ -365,7 +459,7 @@ export const ageLabel = (ms: number): string => {
   return `${Math.floor(ms / 3_600_000)}h ago`
 }
 
-export type RowAside = { kind: 'work' | 'queued' | 'holder' | 'self'; text: string }
+export type RowAside = { kind: 'work' | 'resume' | 'queued' | 'starting' | 'holder' | 'self'; text: string }
 export type RowLayout = {
   mark: string | null
   label: string
@@ -379,6 +473,8 @@ export type RowContext = {
   // True when the group holds the ticket in play: its rows share a two-cell mark column.
   hasMarkColumn: boolean
   pendingWork: number | null
+  // Whether the pending press waits for the turn to end (`queued`) or has been sent (`starting`).
+  pendingPhase: 'queued' | 'starting' | null
   columns: number
 }
 
@@ -408,20 +504,49 @@ export const footerStatus = (status: string, columns: number): FooterStatus => {
 
 const SELF_ASIDE: RowAside = { kind: 'self', text: 'this session' }
 
-// The ticket in play says `this session`; otherwise a frontier row has its button and the rest their holder.
-const asideOf = (t: PaneTicket, pendingWork: number | null, isInPlay: boolean): RowAside | null => {
+type Pending = { number: number | null; phase: 'queued' | 'starting' | null }
+// Only a press known to wait for the turn to end is offered a cancel; one sent, or not yet classed, is not.
+const pendingAside = (phase: Pending['phase']): RowAside =>
+  phase === 'queued' ? { kind: 'queued', text: 'queued' } : { kind: 'starting', text: 'starting' }
+
+const holderOf = (t: PaneTicket): RowAside => ({ kind: 'holder', text: t.assignees.map(a => `@${a}`).join(' ') })
+
+// A needs-you row: any holder first (a `work` press would steal the claim), then nothing when blocked,
+// else `work` (never `resume`: the claim clears the mark, resume would not).
+const needsYouAside = (t: PaneTicket, pending: Pending): RowAside | null => {
+  if (t.assignees.length > 0) return holderOf(t)
+  if (t.state === 'blocked') return null
+  return pending.number === t.number ? pendingAside(pending.phase) : { kind: 'work', text: 'work' }
+}
+
+// The ticket in play says `this session`; a needs-you row follows its own rule; otherwise a frontier row has
+// a `work` button, a paused one a `resume` button (the verb checks the claim), and the rest their holder.
+const asideOf = (t: PaneTicket, pending: Pending, isInPlay: boolean): RowAside | null => {
   if (isInPlay) return SELF_ASIDE
-  if (t.state === 'frontier') return pendingWork === t.number ? { kind: 'queued', text: 'queued' } : { kind: 'work', text: 'work' }
-  return t.assignees.length === 0 ? null : { kind: 'holder', text: t.assignees.map(a => `@${a}`).join(' ') }
+  if (t.isNeedsYou) return needsYouAside(t, pending)
+  if (t.state === 'frontier' || t.state === 'paused') {
+    if (pending.number === t.number) return pendingAside(pending.phase)
+    return t.state === 'frontier' ? { kind: 'work', text: 'work' } : { kind: 'resume', text: 'resume' }
+  }
+  return t.assignees.length === 0 ? null : holderOf(t)
 }
 
+// The button that takes a queued ticket back out of the queue.
+export const CANCEL_LABEL = 'cancel'
+const CANCEL_WIDTH = CANCEL_LABEL.length + BUTTON_CHROME + 1
+
 const asideWidth = (a: RowAside | null): number =>
-  a === null ? 0 : a.text.length + (a.kind === 'work' ? BUTTON_CHROME : 0) + 1
+  a === null
+    ? 0
+    : a.text.length + (a.kind === 'work' || a.kind === 'resume' ? BUTTON_CHROME : 0) + 1 + (a.kind === 'queued' ? CANCEL_WIDTH : 0)
+
+// The press the panel holds back while a turn runs, and releases when it ends.
+export type HeldPress = { id: number; verb: 'work' | 'resume'; number: number }
 
 // What one row draws, cut to the pane width: mark column, `#n title`, type, right-hand part.
 export const rowLayout = (t: PaneTicket, ctx: RowContext): RowLayout => {
   const mark = ctx.isInPlay ? MARK : ctx.hasMarkColumn ? MARK_PAD : null
-  const aside = asideOf(t, ctx.pendingWork, ctx.isInPlay)
+  const aside = asideOf(t, { number: ctx.pendingWork, phase: ctx.pendingPhase }, ctx.isInPlay)
   const type = t.type === null ? null : ` ${t.type}`
   const prefix = `#${t.number}`
   const room = ctx.columns - (mark?.length ?? 0) - asideWidth(aside) - (type?.length ?? 0) - prefix.length - 1