@erclx/aitk 3.43.2 → 3.45.0

package/src/commands/targets.ts

@@ -0,0 +1,319 @@
+import type { Command } from 'commander'
+import { readPullsAcross, type TargetPulls } from '@/targets/pulls'
+import {
+  type KnownTarget,
+  type ResolvedTargets,
+  resolveTargets,
+} from '@/targets/resolve'
+import { DEFAULT_DEPTH, type SweepBound } from '@/targets/sweep'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface ListOptions {
+  readonly json?: boolean
+  readonly sweep?: string[]
+  readonly depth?: string
+}
+
+interface PullsOptions extends ListOptions {}
+
+/**
+ * Reads the depth a sweep is bounded by, or null when the value is not one.
+ *
+ * `Number('abc')` is `NaN` and every `level >= NaN` test is false, so an
+ * unchecked value walks to the bottom of whatever root it was given while
+ * the bound reports a depth of `NaN`. Both halves of the guarantee go at once,
+ * which is why this refuses rather than falling back to the default.
+ */
+function readDepth(value: string | undefined): number | null {
+  const depth = Number(value ?? DEFAULT_DEPTH)
+
+  return Number.isInteger(depth) && depth >= 0 ? depth : null
+}
+
+const REFUSALS: Record<string, string> = {
+  'not-a-directory': 'the path is not a directory, so nothing was read there',
+  'gh-unavailable': 'gh is not on the path, so no pull request could be read',
+  'list-failed':
+    'the open pull request list could not be read, so this is not a target with no work',
+}
+
+export function register(program: Command): void {
+  const targets = program
+    .command('targets')
+    .description('Report the projects this toolkit has installed into')
+    .helpOption('-h, --help', 'Show this help message')
+
+  targets
+    .command('list')
+    .description('Report every known target with where the answer came from')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option(
+      '--sweep <path...>',
+      'Also walk these roots for targets the record never held',
+    )
+    .option(
+      '--depth <n>',
+      'How deep below each swept root to walk',
+      String(DEFAULT_DEPTH),
+    )
+    .addHelpText('after', LIST_HELP)
+    .action(async (opts: ListOptions) => {
+      process.exitCode = await runList(opts)
+    })
+
+  targets
+    .command('pulls')
+    .description(
+      'Report the open pull request, checks, and review heading per target',
+    )
+    .argument('[path...]', 'Targets to read, defaulting to every known one')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--sweep <path...>', 'Also walk these roots when no path is given')
+    .option(
+      '--depth <n>',
+      'How deep below each swept root to walk',
+      String(DEFAULT_DEPTH),
+    )
+    .addHelpText('after', PULLS_HELP)
+    .action(async (paths: string[], opts: PullsOptions) => {
+      process.exitCode = await runPulls(paths, opts)
+    })
+}
+
+const LIST_HELP = [
+  '',
+  'Sources:',
+  '  Every sync that stamps a target records it in a machine-level index, so',
+  '  a project installed since that shipped is known without being named.',
+  '  --sweep walks the roots given for anything installed before it, and a',
+  '  target found in two clones is reported once with both paths.',
+  '',
+  'Exit codes:',
+  '  0  the population was read',
+  '  1  refused, with the reason on stderr',
+  '',
+  'An absent index is reported as unknown rather than as no targets. Nothing',
+  'was read in that case, so a count of zero would be a confident wrong answer.',
+  '',
+  'The JSON carries a "bound" object whenever a sweep ran, naming the roots',
+  'walked, the depth, the folders the walk stopped at, the roots it could not',
+  'read, and the directory symlinks the walk did not follow. A sweep cannot',
+  'see another machine or a clone under a path nobody named, so read the bound',
+  'before treating the count as the population.',
+  '',
+  'An exit code says nothing about a call made from a session, since a shell',
+  'profile may wrap the binary in a function taking its status from a later',
+  'command. Read the record rather than the exit when a skill consumes this.',
+  '',
+  'Examples:',
+  '  aitk targets list',
+  '  aitk targets list --json',
+  '  aitk targets list --sweep ~/repos --json',
+  '',
+].join('\n')
+
+const PULLS_HELP = [
+  '',
+  'Reads, per target, every open pull request with its checks and the heading',
+  'its newest review pass carries. Naming paths reads those and looks up',
+  'nothing; naming none reads every target `aitk targets list` reports.',
+  '',
+  'Exit codes:',
+  '  0  at least one target was read',
+  '  1  refused, or every target refused',
+  '',
+  'A target that could not be read carries a "reason" rather than an empty',
+  'pull list, since reading a failed query as no open work is what reports a',
+  'target as done having read nothing.',
+  '',
+  '"checks" is null when GitHub reported no check at all, which is not the',
+  'same answer as passing. "review" is "open" while the newest pass carries',
+  '## Review, "closed" once one carries ## Review closed, and null when no',
+  'pass has landed. "reviewReadable" is false when that query failed, which',
+  'leaves "review" covering nothing.',
+  '',
+  'Examples:',
+  '  aitk targets pulls',
+  '  aitk targets pulls ../caret ../stackr --json',
+  '',
+].join('\n')
+
+async function runList(opts: ListOptions): Promise<number> {
+  intro('aitk targets list')
+
+  const depth = readDepth(opts.depth)
+
+  if (depth === null) return refuseDepth(opts)
+
+  const resolved = await resolveTargets({ sweep: opts.sweep, depth })
+
+  const unknown = reportTargets(resolved)
+  if (resolved.bound) reportBound(resolved.bound)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        registry: resolved.registry?.path ?? null,
+        known: resolved.registry?.kind !== 'absent',
+        targets: resolved.targets,
+        bound: resolved.bound,
+      })}\n`,
+    )
+  }
+
+  return unknown ? 1 : 0
+}
+
+async function runPulls(paths: string[], opts: PullsOptions): Promise<number> {
+  intro('aitk targets pulls')
+
+  const depth = readDepth(opts.depth)
+
+  if (depth === null) return refuseDepth(opts)
+
+  const resolved = await resolveTargets({ paths, sweep: opts.sweep, depth })
+
+  if (resolved.targets.length === 0) {
+    logStep('Refused')
+    logWarn(
+      resolved.registry?.kind === 'absent'
+        ? `No target index at ${resolved.registry.path}, and no path was given. Name the targets, or sweep for them with --sweep.`
+        : 'No target resolved, so nothing was read.',
+    )
+    outro()
+
+    if (opts.json) {
+      process.stdout.write(
+        `${JSON.stringify({ reason: 'no-targets', targets: [] })}\n`,
+      )
+    }
+
+    return 1
+  }
+
+  // One clone per project. Two checkouts sharing an origin answer the same
+  // query, so reading both spends the rate limit to print one answer twice.
+  const reports = await readPullsAcross(
+    resolved.targets.map((target) => target.paths[0] ?? ''),
+  )
+
+  reportPulls(reports)
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ targets: reports })}\n`)
+  }
+
+  return reports.every((report) => report.kind === 'refused') ? 1 : 0
+}
+
+function refuseDepth(opts: ListOptions): number {
+  logStep('Refused')
+  logWarn(
+    `--depth takes a whole number of levels and was given ${opts.depth}. A value that is not one leaves the walk with no cap at all.`,
+  )
+  outro()
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({ reason: 'bad-depth', depth: opts.depth, targets: [] })}\n`,
+    )
+  }
+
+  return 1
+}
+
+/** Returns whether the population is unknown, which is the one refusal this read has. */
+function reportTargets(resolved: ResolvedTargets): boolean {
+  logStep('Targets')
+
+  if (resolved.registry?.kind === 'absent' && resolved.bound === null) {
+    logWarn(
+      `No target index at ${resolved.registry.path}. Nothing was read, so this is not a machine with no targets. Sweep for them with --sweep, or run a sync in a target to record it.`,
+    )
+    return true
+  }
+
+  if (resolved.targets.length === 0) {
+    logInfo('No target found.')
+    return false
+  }
+
+  logInfo(plural(resolved.targets.length, 'target'))
+  pipeOutput(resolved.targets.map(describe).join('\n'))
+  return false
+}
+
+function describe(target: KnownTarget): string {
+  const flags = [target.source, ...(target.legacy ? ['legacy stamp'] : [])]
+  const clones =
+    target.paths.length > 1 ? `\n  ${target.paths.slice(1).join('\n  ')}` : ''
+
+  return `${target.paths[0]}  ${flags.join(', ')}${clones}`
+}
+
+function reportBound(bound: SweepBound): void {
+  logStep('Bound')
+  logInfo(
+    `Walked ${plural(bound.roots.length, 'root')} to depth ${bound.depth} on this machine alone.`,
+  )
+
+  if (bound.truncated.length > 0) {
+    logWarn(
+      `${plural(bound.truncated.length, 'folder')} hit the depth cap, so a target below one is unseen.`,
+    )
+  }
+
+  if (bound.unreadable.length > 0) {
+    logWarn(
+      `${plural(bound.unreadable.length, 'root')} could not be read: ${bound.unreadable.join(', ')}`,
+    )
+  }
+
+  if (bound.symlinks.length > 0) {
+    const verb = bound.symlinks.length === 1 ? 'was' : 'were'
+    logWarn(
+      `${plural(bound.symlinks.length, 'symlink')} to a directory ${verb} not followed: ${bound.symlinks.join(', ')}`,
+    )
+  }
+}
+
+function reportPulls(reports: readonly TargetPulls[]): void {
+  logStep('Pull requests')
+
+  for (const report of reports) {
+    if (report.kind === 'refused') {
+      logWarn(`${report.path}: ${REFUSALS[report.reason] ?? report.reason}`)
+      continue
+    }
+
+    if (report.pulls.length === 0) {
+      logInfo(`${report.path}: nothing open.`)
+      continue
+    }
+
+    logInfo(`${report.path}`)
+    pipeOutput(
+      report.pulls
+        .map((pull) => {
+          const checks = pull.checks ?? 'no checks'
+          const review = pull.reviewReadable
+            ? (pull.review ?? 'no pass')
+            : 'review unreadable'
+          return `  #${pull.number}  ${checks}  ${review}  ${pull.url}`
+        })
+        .join('\n'),
+    )
+  }
+}

package/src/demo/beats.ts

@@ -1,5 +1,5 @@
 /**
- * Reads the human-facing draft `claude-screencast` writes. Nothing here knows
+ * Reads the human-facing draft `aitk-screencast` writes. Nothing here knows
  * about a browser: the draft is prose aimed at a person, and turning it into
  * something executable is `@/demo/compile`'s job.
  */

package/src/sessions/claim.ts

@@ -24,6 +24,13 @@ export interface ClaimReport {
 }
 
 export interface ClaimOptions {
+  /**
+   * The repository the claim is answered about, not merely where the caller
+   * stands. Every reading below is taken against it, so handing another
+   * project's path asks about that project, which is what lets a dispatcher in
+   * one repository see a branch held in another. Defaults to the caller's own
+   * directory, so a call omitting it answers exactly as it always has.
+   */
   readonly cwd?: string
   readonly resolve?: () => Promise<SessionReport>
   readonly listWorktrees?: (cwd: string) => Promise<readonly WorktreeEntry[]>

package/src/sync/stamp.ts

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { dirname, join, sep } from 'node:path'
 import { execa } from 'execa'
+import { recordTarget } from '@/targets/registry'
 
 /**
  * Domains the stamp can record. Governance attributes file by file through the
@@ -209,6 +210,14 @@ async function putDomain(
   const path = stampPath(target)
   await mkdir(dirname(path), { recursive: true })
   await writeFile(path, `${JSON.stringify(stamp, null, 2)}\n`)
+
+  // Every install and sync that stamps a target passes through here, which is
+  // what makes this the one place the machine-level index can be kept without
+  // each command remembering to. Its outcome is dropped rather than reported:
+  // the stamp just written is the authoritative record of this install, the
+  // index is a cache over every such stamp, and a state folder nobody can
+  // write is not a reason to fail a sync that already landed its files.
+  recordTarget(target, now)
 }
 
 const commitCache = new Map<string, Promise<string | undefined>>()

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
+}