@erclx/canon 4.0.0

package/src/targets/pulls.ts

@@ -0,0 +1,250 @@
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+import { isDirectory } from '@/target'
+
+const GH_TIMEOUT_MS = 30_000
+
+/**
+ * The two headings a review pass posts under.
+ *
+ * Owned by `claude-pr-review`, which states the full set once, and pinned here
+ * the way `claude-orchestrate/scripts/poll.sh` pins them. All three surfaces
+ * ship separately, so a heading added in that skill goes stale here with
+ * nothing comparing the copies.
+ */
+const REVIEW_OPEN = '## Review'
+const REVIEW_CLOSED = '## Review closed'
+
+/** Why a target produced no reading, so an unreachable one never reads as having no work. */
+export type TargetRefusal = 'not-a-directory' | 'gh-unavailable' | 'list-failed'
+
+export type ChecksState = 'passing' | 'failing' | 'pending'
+
+/** Whether the newest review pass left work owed. */
+export type ReviewState = 'open' | 'closed'
+
+export interface PullState {
+  readonly number: number
+  readonly title: string
+  readonly url: string
+  readonly head: string
+  /** Null when GitHub reported no check at all, which is not the same answer as passing. */
+  readonly checks: ChecksState | null
+  /** Null when no pass carrying a review heading has landed on the thread. */
+  readonly review: ReviewState | null
+  /** False when the review read failed, leaving `review` covering nothing. */
+  readonly reviewReadable: boolean
+}
+
+export type TargetPulls =
+  | {
+      readonly kind: 'refused'
+      readonly path: string
+      readonly reason: TargetRefusal
+    }
+  | {
+      readonly kind: 'read'
+      readonly path: string
+      readonly pulls: readonly PullState[]
+    }
+
+/** Runs one `gh` invocation in a target and hands back its stdout, or null when it failed. */
+export type GhRunner = (
+  cwd: string,
+  args: readonly string[],
+) => Promise<string | null>
+
+export interface PullsOptions {
+  readonly run?: GhRunner
+}
+
+/**
+ * `gh` resolves its repository through the same environment variables git does
+ * and they beat `cwd`, so a run from inside a hook would read whichever
+ * repository that hook's environment names rather than the target handed here.
+ */
+const runGh: GhRunner = async (cwd, args) => {
+  if (Bun.which('gh') === null) return null
+
+  try {
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return null
+  }
+}
+
+interface RawPull {
+  readonly number?: number
+  readonly title?: string
+  readonly url?: string
+  readonly headRefOid?: string
+  readonly statusCheckRollup?: readonly RawCheck[]
+}
+
+interface RawCheck {
+  readonly status?: string
+  readonly conclusion?: string
+  readonly state?: string
+}
+
+interface RawReview {
+  readonly body?: string
+  readonly submittedAt?: string
+}
+
+const FAILED = new Set([
+  'FAILURE',
+  'TIMED_OUT',
+  'CANCELLED',
+  'ACTION_REQUIRED',
+  'STARTUP_FAILURE',
+  'ERROR',
+])
+
+/**
+ * Collapses every check on a head into one word.
+ *
+ * A failure outranks a pending one, because a run still going cannot clear a
+ * job that already failed and reporting the head as pending would invite a
+ * wait for an answer that has arrived.
+ */
+export function rollup(checks: readonly RawCheck[]): ChecksState | null {
+  if (checks.length === 0) return null
+
+  const verdicts = checks.map((check) => check.conclusion ?? check.state ?? '')
+
+  if (verdicts.some((verdict) => FAILED.has(verdict))) return 'failing'
+
+  const running = checks.some(
+    (check) =>
+      (check.status !== undefined && check.status !== 'COMPLETED') ||
+      check.state === 'PENDING' ||
+      (check.conclusion === undefined && check.state === undefined),
+  )
+
+  return running ? 'pending' : 'passing'
+}
+
+/**
+ * Reads the heading of the newest pass carrying one, matching on the first line
+ * alone the way `poll.sh` does.
+ *
+ * The reviews arrive oldest first, so the last match is the current state of
+ * the thread. A pass carrying neither heading is somebody reviewing by hand and
+ * says nothing about whether the loop owes work.
+ */
+export function latestReview(
+  reviews: readonly RawReview[],
+): ReviewState | null {
+  let state: ReviewState | null = null
+
+  for (const review of reviews) {
+    const first = (review.body ?? '').split('\n')[0]?.replace(/\r$/, '')
+    if (first === REVIEW_OPEN) state = 'open'
+    else if (first === REVIEW_CLOSED) state = 'closed'
+  }
+
+  return state
+}
+
+function parse<T>(text: string | null): T | null {
+  if (text === null) return null
+  try {
+    return JSON.parse(text) as T
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Reports the open pull requests in one target with their checks and the
+ * heading their newest review pass carries.
+ *
+ * A list that failed and a target with no open pull request are separated
+ * rather than collapsed, since reading the first as the second reports a target
+ * as done when nothing was read at all. That is the failure mode the shell loop
+ * this replaces had no way to surface.
+ */
+export async function readTargetPulls(
+  path: string,
+  opts: PullsOptions = {},
+): Promise<TargetPulls> {
+  const run = opts.run ?? runGh
+
+  if (!isDirectory(path))
+    return { kind: 'refused', path, reason: 'not-a-directory' }
+
+  if (opts.run === undefined && Bun.which('gh') === null) {
+    return { kind: 'refused', path, reason: 'gh-unavailable' }
+  }
+
+  const listed = parse<readonly RawPull[]>(
+    await run(path, [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--json',
+      'number,title,url,headRefOid,statusCheckRollup',
+    ]),
+  )
+
+  if (listed === null) return { kind: 'refused', path, reason: 'list-failed' }
+
+  const pulls = await Promise.all(
+    listed
+      .filter(
+        (raw): raw is RawPull & { number: number } =>
+          typeof raw.number === 'number',
+      )
+      .map(async (raw) => {
+        // One query per pull request, so a review read that failed surfaces on
+        // the thread it failed for rather than emptying the whole target.
+        const reviews = parse<{ reviews?: readonly RawReview[] }>(
+          await run(path, [
+            'pr',
+            'view',
+            String(raw.number),
+            '--json',
+            'reviews',
+          ]),
+        )
+
+        return {
+          number: raw.number,
+          title: raw.title ?? '',
+          url: raw.url ?? '',
+          head: raw.headRefOid ?? '',
+          checks: rollup(raw.statusCheckRollup ?? []),
+          review: reviews === null ? null : latestReview(reviews.reviews ?? []),
+          reviewReadable: reviews !== null,
+        }
+      }),
+  )
+
+  return { kind: 'read', path, pulls }
+}
+
+/**
+ * Reads every target, one at a time.
+ *
+ * The reads are serial rather than batched because each one spends a GitHub API
+ * quota shared across all of them, and a wave running over a dozen targets that
+ * fired them together would meet the secondary rate limit rather than an answer.
+ */
+export async function readPullsAcross(
+  paths: readonly string[],
+  opts: PullsOptions = {},
+): Promise<readonly TargetPulls[]> {
+  const reports: TargetPulls[] = []
+
+  for (const path of paths) reports.push(await readTargetPulls(path, opts))
+
+  return reports
+}

package/src/targets/registry.ts

@@ -0,0 +1,203 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+/**
+ * One project the toolkit has installed into, as the install recorded it.
+ *
+ * The path is the target root rather than its git directory, because the
+ * record is written by a sync that knows where it wrote and not by anything
+ * that resolved a repository. Whether two entries are one project is a
+ * question about their origins, which `src/targets/sweep.ts` answers.
+ */
+export interface TargetRecord {
+  readonly path: string
+  /** ISO stamp of the most recent sync that recorded this target. */
+  readonly stampedAt: string
+}
+
+/**
+ * An absent file and an empty one are separate answers, the same split
+ * `src/sessions/registry.ts` draws.
+ *
+ * The first means no sync has ever recorded a target on this machine, so the
+ * population is unknown and the sweep is the only reading available. The
+ * second means the file was read and holds no usable row, which a caller
+ * should be able to tell apart from a lookup that never ran.
+ */
+export type TargetRegistry =
+  | { readonly kind: 'absent'; readonly path: string }
+  | {
+      readonly kind: 'read'
+      readonly path: string
+      readonly targets: readonly TargetRecord[]
+    }
+
+interface StoredRegistry {
+  readonly version: number
+  readonly targets: readonly TargetRecord[]
+}
+
+const VERSION = 1
+
+/**
+ * Resolves the folder holding this machine's toolkit state.
+ *
+ * Twin of `sandboxTree` in `src/commands/sandbox.ts`, which resolves the same
+ * three sources in the same order. The override exists so a test never writes
+ * into the home directory of whoever runs it.
+ */
+export function stateDir(): string {
+  return stateDirNamed('canon')
+}
+
+/**
+ * Where this machine's state sat before the rename. Read below when the
+ * current folder holds no registry, and never written to by anything here.
+ */
+export function retiredStateDir(): string {
+  // canon-keep-retired
+  return stateDirNamed('aitk')
+}
+
+/**
+ * The override honors the retired variable too, since an operator who exported
+ * it is the same operator whose registry sits under the retired folder.
+ */
+function stateDirNamed(folder: string): string {
+  // canon-keep-retired
+  const override = process.env.CANON_STATE_DIR ?? process.env.AITK_STATE_DIR
+  if (override !== undefined && override !== '') return override
+
+  const state = process.env.XDG_STATE_HOME
+  const base =
+    state !== undefined && state !== ''
+      ? state
+      : join(homedir(), '.local', 'state')
+
+  return join(base, folder)
+}
+
+/**
+ * The registry this machine uses, current path first and the retired one
+ * behind it.
+ *
+ * The rename moved the folder and nothing migrates it, so a machine that has
+ * been recording targets for months would otherwise answer with an empty
+ * registry the first time it ran the renamed binary. Empty is
+ * indistinguishable from a machine that never installed anything, which is
+ * exactly the confident wrong answer this record exists to prevent.
+ *
+ * Resolving one path for both the read and the write is deliberate. A machine
+ * already holding the retired file keeps using it rather than being migrated
+ * underneath, which mirrors how `readStamp` treats a target's retired config.
+ */
+export function registryPath(): string {
+  const current = join(stateDir(), 'targets.json')
+  if (existsSync(current)) return current
+
+  const retired = join(retiredStateDir(), 'targets.json')
+  return existsSync(retired) ? retired : current
+}
+
+function isRecord(value: Partial<TargetRecord>): value is TargetRecord {
+  return (
+    typeof value.path === 'string' &&
+    value.path.length > 0 &&
+    typeof value.stampedAt === 'string' &&
+    value.stampedAt.length > 0
+  )
+}
+
+/**
+ * Reads every recorded target, sorted by path.
+ *
+ * A row missing either field is dropped rather than reported. This module is
+ * the file's only writer, so a malformed row is a hand edit or a truncated
+ * write and neither is a finding the caller can act on. What a caller can act
+ * on is the file being absent, which is its own kind above.
+ */
+export function readTargetRegistry(
+  path: string = registryPath(),
+): TargetRegistry {
+  let text: string
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch {
+    return { kind: 'absent', path }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return { kind: 'read', path, targets: [] }
+  }
+
+  if (typeof parsed !== 'object' || parsed === null) {
+    return { kind: 'read', path, targets: [] }
+  }
+
+  const stored = parsed as Partial<StoredRegistry>
+  const rows = Array.isArray(stored.targets) ? stored.targets : []
+  const targets = rows
+    .filter((row): row is TargetRecord =>
+      isRecord(row as Partial<TargetRecord>),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path))
+
+  return { kind: 'read', path, targets }
+}
+
+/** Why a record attempt did not land, so a caller can say so rather than assume it did. */
+export type RecordOutcome = 'recorded' | 'unwritten'
+
+/**
+ * Records one target, keyed by its resolved path and replacing any row already
+ * held for it.
+ *
+ * The write is a temp file plus a rename, so a reader never meets a half
+ * written file. Two syncs finishing together still resolve last-writer-wins on
+ * the merged set, which can drop the row the loser added. That is left rather
+ * than locked: the authoritative record of an install is the stamp inside the
+ * target, this index is a cache over those, and the next sync of the dropped
+ * target restores its row.
+ *
+ * Nothing removes a row either, so a target that was deleted or that dropped
+ * the toolkit stays here and the count drifts upward. `canon targets pulls`
+ * meets that on use, since it refuses a path it cannot open rather than
+ * reading it as a target with no work, but `canon targets list` does not: it
+ * never opens a recorded path, and the count is its whole output.
+ */
+export function recordTarget(
+  target: string,
+  now: Date,
+  path: string = registryPath(),
+): RecordOutcome {
+  const resolved = resolve(target)
+  const current = readTargetRegistry(path)
+  const existing = current.kind === 'read' ? current.targets : []
+
+  const targets = [
+    ...existing.filter((row) => row.path !== resolved),
+    { path: resolved, stampedAt: now.toISOString() },
+  ].sort((a, b) => a.path.localeCompare(b.path))
+
+  const payload: StoredRegistry = { version: VERSION, targets }
+  const temp = `${path}.${process.pid}.tmp`
+
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(temp, `${JSON.stringify(payload, null, 2)}\n`)
+    renameSync(temp, path)
+    return 'recorded'
+  } catch {
+    return 'unwritten'
+  }
+}

package/src/targets/resolve.ts

@@ -0,0 +1,145 @@
+import { resolve } from 'node:path'
+import { isLegacyStamped } from '@/sync/stamp'
+import {
+  readTargetRegistry,
+  type TargetRegistry,
+  registryPath,
+} from '@/targets/registry'
+import {
+  type SweepBound,
+  type SweepOptions,
+  sweepTargets,
+} from '@/targets/sweep'
+
+/**
+ * Where a target came from, carried on the row rather than inferred.
+ *
+ * A caller deciding whether an answer is trustworthy needs to know which rows
+ * the machine recorded for itself and which a walk guessed at, and the two
+ * carry different bounds.
+ */
+export type TargetSource = 'given' | 'record' | 'sweep'
+
+export interface KnownTarget {
+  /** Every checkout of this project on this machine, one for the ordinary case. */
+  readonly paths: readonly string[]
+  readonly origin: string | null
+  readonly source: TargetSource
+  /** When a sync last recorded this target, or null for a row only a sweep found. */
+  readonly stampedAt: string | null
+  /** True while the install stamp still sits at the retired path. */
+  readonly legacy: boolean
+}
+
+export interface ResolvedTargets {
+  readonly targets: readonly KnownTarget[]
+  /** Null when the caller named its targets, so no registry read was attempted. */
+  readonly registry: TargetRegistry | null
+  /** Null when no sweep ran, which is the ordinary case. */
+  readonly bound: SweepBound | null
+}
+
+export interface ResolveTargetsOptions extends SweepOptions {
+  /** Paths the caller named. These win outright and suppress both other sources. */
+  readonly paths?: readonly string[]
+  /** Roots to walk, supplementing the record rather than replacing it. */
+  readonly sweep?: readonly string[]
+  readonly registryFile?: string
+}
+
+/**
+ * Answers which projects the toolkit has installed into.
+ *
+ * The record written at install time is the primary source and a walk is the
+ * fallback, which is the shape the population needs: a sweep alone cannot see
+ * another machine or a clone under a path nobody named, and that is exactly how
+ * the count moved from four to seven inside one pass and was then wrong in both
+ * directions at once.
+ *
+ * A caller naming paths gets those and no lookup at all, since it has already
+ * answered the question this resolves.
+ */
+export async function resolveTargets(
+  opts: ResolveTargetsOptions = {},
+): Promise<ResolvedTargets> {
+  if (opts.paths !== undefined && opts.paths.length > 0) {
+    return {
+      targets: opts.paths.map((path) => given(resolve(path))),
+      registry: null,
+      bound: null,
+    }
+  }
+
+  const file = opts.registryFile ?? registryPath()
+  const registry = readTargetRegistry(file)
+
+  const recorded: KnownTarget[] =
+    registry.kind === 'read'
+      ? registry.targets.map((row) => ({
+          paths: [row.path],
+          origin: null,
+          source: 'record' as const,
+          stampedAt: row.stampedAt,
+          legacy: isLegacyStamped(row.path),
+        }))
+      : []
+
+  if (opts.sweep === undefined || opts.sweep.length === 0) {
+    return { targets: recorded, registry, bound: null }
+  }
+
+  const swept = await sweepTargets(opts.sweep, opts)
+  const known = new Set(recorded.flatMap((target) => target.paths))
+
+  // A sweep row whose paths the record already holds is the same project read
+  // twice, so it adds nothing. A row holding one known path and one unknown one
+  // is the second-clone case, and it replaces the record's row rather than
+  // sitting beside it, since the sweep is the only source that can see both.
+  const added: KnownTarget[] = []
+  const superseded = new Set<string>()
+
+  for (const target of swept.targets) {
+    const overlap = target.paths.filter((path) => known.has(path))
+
+    if (overlap.length === target.paths.length) continue
+
+    for (const path of overlap) superseded.add(path)
+
+    // The recorded clone leads, because the record only names one a sync
+    // actually ran in, where the rest are checkouts a walk happened to find.
+    // Every caller reading a single path takes the first, and picking that by
+    // sort order is how a repair ran in one clone while the count was taken
+    // against another and the target read as untouched.
+    added.push({
+      paths: [...overlap, ...target.paths.filter((path) => !known.has(path))],
+      origin: target.origin,
+      source: overlap.length > 0 ? 'record' : 'sweep',
+      stampedAt:
+        recorded.find((row) => overlap.includes(row.paths[0] ?? ''))
+          ?.stampedAt ?? null,
+      legacy: target.legacy,
+    })
+  }
+
+  const kept = recorded.filter(
+    (row) => !row.paths.some((path) => superseded.has(path)),
+  )
+
+  return {
+    targets: [...kept, ...added].sort((a, b) =>
+      (a.paths[0] ?? '').localeCompare(b.paths[0] ?? ''),
+    ),
+    registry,
+    bound: swept.bound,
+  }
+}
+
+function given(path: string): KnownTarget {
+  return {
+    paths: [path],
+    origin: null,
+    source: 'given',
+    stampedAt: null,
+    legacy: isLegacyStamped(path),
+  }
+}