@erclx/aitk 3.43.1 → 3.44.0

package/src/targets/registry.ts

@@ -0,0 +1,161 @@
+import { 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 {
+  const override = 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, 'aitk')
+}
+
+export function registryPath(): string {
+  return join(stateDir(), 'targets.json')
+}
+
+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. `aitk 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 `aitk 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),
+  }
+}

package/src/targets/sweep.ts

@@ -0,0 +1,246 @@
+import { readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git-env'
+import { isLegacyStamped, legacyStampPath, stampPath } from '@/sync/stamp'
+import { isDirectory } from '@/target'
+
+/**
+ * Folders a walk never descends into.
+ *
+ * Most hold vendored trees or the repository's own object store, where a target
+ * cannot live and walking costs the sweep most of its time. `.claude` is here
+ * for a different reason: a stamped folder is found by testing the folder
+ * itself rather than by walking into its `.claude`, so descending finds nothing
+ * new, and `.claude/worktrees/` holds a full checkout per linked worktree that
+ * carries a copy of its own target's stamp. One target on this machine had five
+ * of them, each of which would have reported as a target of its own.
+ */
+const SKIP = new Set([
+  'node_modules',
+  '.git',
+  '.claude',
+  'dist',
+  'build',
+  'vendor',
+  'target',
+  '.next',
+  '.venv',
+])
+
+/** How deep below a root the walk goes before it stops and says so. */
+export const DEFAULT_DEPTH = 4
+
+/**
+ * One project, with every path on this machine that holds a stamp for it.
+ *
+ * The paths are plural because a project can be cloned more than once, which
+ * is not a hypothetical: the census taken on 2026-08-28 counted `caret` at the
+ * clone it walked while the repair had run in a second clone it never saw, and
+ * that gap is what left a task carrying a ticked outcome its own finding
+ * contradicted.
+ */
+export interface SweptTarget {
+  readonly paths: readonly string[]
+  /** The origin every path agrees on, or null when git resolved none. */
+  readonly origin: string | null
+  /** True while every path still carries its stamp at the retired location. */
+  readonly legacy: boolean
+}
+
+/**
+ * What the answer is bounded by, reported alongside it.
+ *
+ * A sweep cannot see another machine, a clone under a path nobody named, or a
+ * tree it lacked permission to read. Stating the bound is what makes an
+ * incomplete answer legible as incomplete, which the two undercounts this
+ * exists to replace were not.
+ */
+export interface SweepBound {
+  readonly roots: readonly string[]
+  readonly depth: number
+  /** Folders the walk stopped at on reaching the depth cap, so a target below one is unseen. */
+  readonly truncated: readonly string[]
+  /** Roots that could not be listed at all, as opposed to holding nothing. */
+  readonly unreadable: readonly string[]
+  /**
+   * Symlinks to directories, which the walk does not follow.
+   *
+   * `readdirSync` with `withFileTypes` answers `isDirectory()` false for one, so
+   * without this field a target reached only through a symlink is dropped
+   * before the walk and named nowhere, which is a third silent undercount
+   * beside the two this module replaces.
+   */
+  readonly symlinks: readonly string[]
+}
+
+export interface SweepReport {
+  readonly targets: readonly SweptTarget[]
+  readonly bound: SweepBound
+}
+
+export interface SweepOptions {
+  readonly depth?: number
+  /** Resolves a checkout's origin. Injected so a test needs no remote. */
+  readonly originOf?: (path: string) => Promise<string | null>
+}
+
+/** Whether a folder carries an install stamp at either the current or the retired path. */
+function isStamped(path: string): boolean {
+  return (
+    Bun.file(stampPath(path)).size > 0 ||
+    Bun.file(legacyStampPath(path)).size > 0
+  )
+}
+
+/**
+ * Reads the origin a checkout pushes to, trimmed to a form two clones of one
+ * project agree on.
+ *
+ * The scheme and the `.git` suffix are dropped because one project is commonly
+ * cloned over ssh in one place and https in another, and a comparison keeping
+ * either reports those as two projects, which is the count this exists to fix.
+ *
+ * Userinfo goes with them, and it is the component that has to. A checkout
+ * cloned as `https://x-access-token:<token>@github.com/owner/repo.git` puts the
+ * token in the key, and the key is returned on `SweptTarget.origin` and printed
+ * by `aitk targets list --json`. Dropping it also fixes the count, since
+ * `https://someuser@github.com/owner/repo.git` keyed on the user and so failed
+ * to group with the same project's ssh clone.
+ */
+export async function originOf(path: string): Promise<string | null> {
+  const result = await $`git -C ${path} remote get-url origin`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+
+  if (result.exitCode !== 0) return null
+
+  const raw = result.stdout.toString().trim()
+  if (raw.length === 0) return null
+
+  return raw
+    .replace(/^[a-z+]+:\/\//, '')
+    .replace(/^[^/@]*@/, '')
+    .replace(/:/, '/')
+    .replace(/\.git$/, '')
+    .replace(/\/$/, '')
+    .toLowerCase()
+}
+
+/**
+ * Walks the given roots for installed targets and reports what bounds the walk.
+ *
+ * A stamped folder is descended into like any other, because a stamp is written
+ * by an install someone ran in that folder and a target can hold others. The
+ * machine this was measured on has exactly that shape: one stamped repository
+ * holds the eight the hand census walked, so stopping at the outer one would
+ * have hidden every target the sweep exists to find.
+ */
+export async function sweepTargets(
+  roots: readonly string[],
+  opts: SweepOptions = {},
+): Promise<SweepReport> {
+  const depth = opts.depth ?? DEFAULT_DEPTH
+  const resolveOrigin = opts.originOf ?? originOf
+
+  const found: string[] = []
+  const truncated: string[] = []
+  const unreadable: string[] = []
+  const symlinks: string[] = []
+  const seen = new Set<string>()
+
+  const walk = (dir: string, level: number): void => {
+    if (seen.has(dir)) return
+    seen.add(dir)
+
+    if (isStamped(dir)) found.push(dir)
+
+    if (level >= depth) {
+      truncated.push(dir)
+      return
+    }
+
+    let entries: string[]
+    try {
+      const listed = readdirSync(dir, { withFileTypes: true }).filter(
+        (entry) => !SKIP.has(entry.name),
+      )
+
+      // A symlink is reported as neither a directory nor walked, so a directory
+      // symlink is named here rather than dropped. Following one is available,
+      // since `seen` already closes the cycle, and naming it is the answer the
+      // bound asks for: what the walk did not reach, stated rather than
+      // omitted. `isDirectory` follows the link, so a symlink to a file or a
+      // broken one is excluded rather than read as an unfollowed directory.
+      for (const entry of listed) {
+        if (!entry.isSymbolicLink()) continue
+        const full = join(dir, entry.name)
+        if (isDirectory(full)) symlinks.push(full)
+      }
+
+      entries = listed
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+    } catch {
+      unreadable.push(dir)
+      return
+    }
+
+    for (const name of entries) walk(join(dir, name), level + 1)
+  }
+
+  const resolved = roots.map((root) => resolve(root))
+
+  for (const root of resolved) {
+    if (!isDirectory(root)) {
+      unreadable.push(root)
+      continue
+    }
+    walk(root, 0)
+  }
+
+  return {
+    targets: await group(found.sort(), resolveOrigin),
+    bound: { roots: resolved, depth, truncated, unreadable, symlinks },
+  }
+}
+
+/**
+ * Collapses the paths sharing one origin into a single target.
+ *
+ * A path whose origin does not resolve stays on its own, since two checkouts
+ * with no remote cannot be shown to be the same project and merging them on
+ * that absence would undercount in the other direction.
+ */
+async function group(
+  paths: readonly string[],
+  resolveOrigin: (path: string) => Promise<string | null>,
+): Promise<readonly SweptTarget[]> {
+  const origins = await Promise.all(paths.map(resolveOrigin))
+  const byOrigin = new Map<string, string[]>()
+  const alone: SweptTarget[] = []
+
+  paths.forEach((path, index) => {
+    const origin = origins[index]
+
+    if (origin === null || origin === undefined) {
+      alone.push({ paths: [path], origin: null, legacy: isLegacyStamped(path) })
+      return
+    }
+
+    const group = byOrigin.get(origin)
+    if (group === undefined) byOrigin.set(origin, [path])
+    else group.push(path)
+  })
+
+  const merged = [...byOrigin.entries()].map(([origin, group]) => ({
+    paths: group,
+    origin,
+    legacy: group.every((path) => isLegacyStamped(path)),
+  }))
+
+  return [...merged, ...alone].sort((a, b) =>
+    (a.paths[0] ?? '').localeCompare(b.paths[0] ?? ''),
+  )
+}

package/standards/issue.md

@@ -58,7 +58,7 @@ Fix the feedback CLI so it applies the `feedback` label.
 
 ## Details
 
-`aitk feedback --github` opens an issue with no label, so `toolkit-triage` never lists it.
+`aitk feedback --github` opens an issue with no label, so `aitk-feedback-triage` never lists it.
 
 ## Context