@defrex/autobuild 0.8.0

package/packages/core/src/ports/tickets/file.ts

@@ -0,0 +1,559 @@
+/**
+ * File-based TicketSource (SPEC §3.2, §13): the default tracker. A directory
+ * of state directories — `triage/ ready/ doing/ done/` — each holding
+ * `<id>.md` files: TOML frontmatter between `+++` fences, then the ticket
+ * body, where the spec lives pre-build (§6.3). This adapter is the policy's
+ * proof: a source with nowhere to put blobs must be fully workable, because
+ * the tracker initiates and receives projections only — never consulted
+ * mid-build, never artifact storage.
+ *
+ * A ticket's state IS the directory it sits in. There is no `state` field to
+ * disagree with the filesystem, and `transition` and `claim` are rename(2).
+ * Moving a valid record from `triage/` to `ready/` is the complete
+ * lifecycle-state grooming UX; listing validates every candidate before it can
+ * become eligible.
+ *
+ * Concurrency: writes locate and validate immediately before a same-path
+ * rewrite or same-filesystem rename; there is no filesystem lock. The
+ * dispatcher remains the lifecycle single writer (SPEC §12), and concurrent
+ * human edits are explicitly last-write-wins. State renames never cross a
+ * filesystem: `<dir>/ready` → `<dir>/doing` is one mount by construction.
+ */
+import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
+import { z } from 'zod'
+import { systemClock, type Clock } from '../../store/types'
+import type {
+  DependencyState,
+  Ticket,
+  TicketCreateOptions,
+  TicketDraft,
+  TicketListing,
+  TicketSource,
+  TicketUpdate,
+} from '../types'
+import { validateTicketUpdate } from './update'
+
+/**
+ * The canonical states, in workflow order. This set is closed: the states are
+ * directories, and a tracker whose states are discoverable by `ls` cannot also
+ * let config invent new ones.
+ */
+export const TICKET_STATES = ['Triage', 'Ready', 'Doing', 'Done'] as const
+export type TicketState = (typeof TICKET_STATES)[number]
+
+/** Repo-relative fallback when no selected local-state root is supplied. */
+export const DEFAULT_TICKETS_DIR = '.autobuild/tickets'
+
+/**
+ * Canonicalize a state name to its directory. Case-insensitive in (a config's
+ * `readyState = "ready"` means the `ready/` directory), canonical out — and
+ * anything else is a loud error, because a typo'd state must not silently
+ * create a fifth directory no `ls` of the four would ever show.
+ */
+export function stateDir(state: string): TicketState {
+  const match = TICKET_STATES.find((s) => s.toLowerCase() === state.toLowerCase())
+  if (match === undefined) {
+    throw new Error(
+      `file ticket source: unknown state "${state}" — this tracker's states are ` +
+        `the directories: ${TICKET_STATES.join(', ')}`,
+    )
+  }
+  return match
+}
+
+function dirName(state: TicketState): string {
+  return state.toLowerCase()
+}
+
+const frontmatterSchema = z.strictObject({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  labels: z.array(z.string()).default([]),
+  /** Source-local blocker ids (§13). Absent ≡ no dependencies, which keeps
+   * every pre-existing ticket file valid. */
+  blockedBy: z.array(z.string()).optional(),
+  /** Stable external-create adoption key. It travels with the ticket across
+   * state-directory moves, so retries find it in any lifecycle state. */
+  idempotencyKey: z.string().min(1).optional(),
+})
+type Frontmatter = z.infer<typeof frontmatterSchema>
+
+const OPEN_FENCE = '+++\n'
+const CLOSE_FENCE = '\n+++\n'
+
+/** A malformed record that a complete tracker scan may safely exclude. This is
+ * deliberately narrower than ordinary Error: filesystem failures, layout
+ * violations, duplicate ids, and unexpected exceptions must still abort the
+ * listing. */
+export class TicketFileValidationError extends Error {
+  override readonly name = 'TicketFileValidationError'
+}
+
+function parseTicketFile(path: string, raw: string): { front: Frontmatter; body: string } {
+  if (!raw.startsWith(OPEN_FENCE)) {
+    throw new TicketFileValidationError(
+      `${path}: malformed ticket file — missing opening "+++" fence`,
+    )
+  }
+  const close = raw.indexOf(CLOSE_FENCE, OPEN_FENCE.length)
+  if (close === -1) {
+    throw new TicketFileValidationError(
+      `${path}: malformed ticket file — missing closing "+++" fence`,
+    )
+  }
+  let parsed: unknown
+  try {
+    parsed = parseToml(raw.slice(OPEN_FENCE.length, close))
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new TicketFileValidationError(`${path}: malformed TOML frontmatter — ${message}`)
+  }
+  const result = frontmatterSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ')
+    throw new TicketFileValidationError(`${path}: invalid frontmatter — ${issues}`)
+  }
+  return { front: result.data, body: raw.slice(close + CLOSE_FENCE.length) }
+}
+
+function serializeTicketFile(front: Frontmatter, body: string): string {
+  const data: Record<string, unknown> = { id: front.id, title: front.title }
+  if (front.labels.length > 0) data.labels = front.labels
+  // Only when nonempty: a file that never declared blockers must round-trip
+  // byte-identically rather than sprouting `blockedBy = []` on every write.
+  if (front.blockedBy !== undefined && front.blockedBy.length > 0) {
+    data.blockedBy = front.blockedBy
+  }
+  if (front.idempotencyKey !== undefined) {
+    data.idempotencyKey = front.idempotencyKey
+  }
+  // smol-toml stringify ends with a newline; the closing fence follows it.
+  return `${OPEN_FENCE}${stringifyToml(data)}+++\n${body}`
+}
+
+/** A ticket file found on disk: its id, its state (= its directory), its path. */
+interface Located {
+  id: string
+  state: TicketState
+  path: string
+}
+
+export class FileTicketSource implements TicketSource {
+  readonly name = 'file'
+
+  private readonly dir: string
+  private readonly clock: Clock
+  private readonly createState: TicketState
+  private readonly doneState: TicketState
+  private readonly selfIgnore: boolean
+
+  constructor(opts: {
+    dir: string
+    /** Injectable for deterministic comment timestamps. */
+    clock?: Clock
+    /** State assigned by create — proposals land in Triage (SPEC §12). */
+    createState?: string
+    /**
+     * The state this source considers complete, for dependency resolution
+     * (§13: this adapter's native lifecycle). Default 'Done' — and, like every
+     * state here, it names a directory, so it is canonicalized rather than
+     * compared raw.
+     */
+    doneState?: string
+    /**
+     * Write a self-excluding `<dir>/.gitignore`. Set ONLY for the defaulted
+     * local-state `tickets/` backlog (see createTicketSource): an explicitly
+     * configured dir is the user's directory, and ab does not decide git's
+     * view of it.
+     */
+    selfIgnore?: boolean
+  }) {
+    this.dir = opts.dir
+    this.clock = opts.clock ?? systemClock
+    this.createState = stateDir(opts.createState ?? 'Triage')
+    this.doneState = stateDir(opts.doneState ?? 'Done')
+    this.selfIgnore = opts.selfIgnore ?? false
+  }
+
+  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+    const labels = criteria.labels ?? []
+    const state = criteria.state === undefined ? undefined : stateDir(criteria.state)
+    // Through listAll, not a single readdir: scan completes its layout and
+    // duplicate-id checks before any per-record validation is contained. A
+    // malformed record can never weaken the invariant preventing a `cp`
+    // between state dirs from becoming a silent double-dispatch.
+    const listing = await this.listAll()
+    return {
+      tickets: listing.tickets.filter(
+        (ticket) =>
+          (state === undefined || ticket.state === state) &&
+          labels.every((label) => ticket.labels.includes(label)),
+      ),
+      diagnostics: listing.diagnostics,
+    }
+  }
+
+  async get(id: string): Promise<Ticket | null> {
+    const found = await this.locate(id)
+    if (found === null) return null
+    const loaded = await this.loadAt(found)
+    return this.toTicket(loaded.front, loaded.body, found.state)
+  }
+
+  /**
+   * Claim-before-launch (SPEC §12): rename into `doing/`. The relocation IS
+   * the claim record — no `claimedBy` field, which is what makes "claiming
+   * visibly removes it from ready/" true.
+   *
+   * The guard refuses a ticket already in Doing or in this source's configured
+   * terminal state rather than requiring one in Ready. That inversion is
+   * deliberate: a legal `[tickets] readyState = "Triage"` would otherwise
+   * stall forever. Other nonterminal states remain claimable after an explicit
+   * handback, while terminal work can never be reopened by claim.
+   */
+  async claim(id: string): Promise<boolean> {
+    await this.ensureLayout()
+    const found = await this.locate(id)
+    if (found === null) return false
+    // Revalidate at the targeted operation boundary, even when lifecycle state
+    // will make the claim a no-op. Besides keeping malformed records loud,
+    // this closes the list→claim window where a human could corrupt a record
+    // after it was listed but before the dispatcher claims it.
+    await this.loadAt(found)
+    if (found.state === 'Doing' || found.state === this.doneState) return false
+    await rename(found.path, this.pathIn('Doing', id))
+    return true
+  }
+
+  /**
+   * Projections flow outward only (SPEC §13): the comment is appended below
+   * the existing content, which is preserved byte-exactly — the spec in the
+   * body (§6.3) is never rewritten.
+   */
+  async comment(id: string, body: string): Promise<void> {
+    await this.ensureLayout()
+    const found = await this.locate(id)
+    if (found === null) {
+      throw new Error(`file ticket source: comment on unknown ticket "${id}"`)
+    }
+    const raw = await readFile(found.path, 'utf8')
+    parseTicketFile(found.path, raw) // surface malformed files before appending
+    const separator = raw.endsWith('\n') ? '\n' : '\n\n'
+    const stamp = this.clock().toISOString()
+    await writeFile(found.path, `${raw}${separator}## Comment (${stamp})\n\n${body}\n`)
+  }
+
+  /** A move, never a rewrite — which is why the body survives byte-exactly. */
+  async transition(id: string, state: string): Promise<void> {
+    await this.ensureLayout()
+    const target = stateDir(state)
+    const found = await this.locate(id)
+    if (found === null) {
+      throw new Error(`file ticket source: transition on unknown ticket "${id}"`)
+    }
+    // Targeted writes remain loud for malformed records, including an
+    // otherwise-idempotent transition to the current state.
+    await this.loadAt(found)
+    // Idempotent by construction — the dispatcher retries transitions after a
+    // crash (file.test.ts explains the window). rename(2) would no-op here
+    // anyway, but resting idempotency on that POSIX subtlety would make it a
+    // property of the syscall rather than of this adapter.
+    if (found.state === target) return
+    await rename(found.path, this.pathIn(target, id))
+  }
+
+  /** Writes `<createState>/file-<n>.md` with the next free n (gaps reused),
+   * or adopts the ticket carrying the same idempotency key. */
+  async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    await this.ensureLayout()
+    const located = await this.scan()
+    if (opts.idempotencyKey !== undefined) {
+      const matches: Array<{ found: Located; front: Frontmatter; body: string }> = []
+      for (const found of located) {
+        const loaded = await this.loadAt(found)
+        if (loaded.front.idempotencyKey === opts.idempotencyKey) {
+          matches.push({ found, ...loaded })
+        }
+      }
+      if (matches.length > 1) {
+        throw new Error(
+          `file ticket source: idempotency key "${opts.idempotencyKey}" exists on multiple tickets: ${matches.map((match) => match.found.id).join(', ')}`,
+        )
+      }
+      const adopted = matches[0]
+      if (adopted !== undefined) {
+        return this.toTicket(adopted.front, adopted.body, adopted.found.state)
+      }
+    }
+    const taken = new Set(located.map((f) => f.id))
+    let n = 1
+    while (taken.has(`file-${n}`)) n += 1
+    const front: Frontmatter = {
+      id: `file-${n}`,
+      title: draft.title,
+      labels: [...(draft.labels ?? [])],
+      ...(draft.blockedBy !== undefined && draft.blockedBy.length > 0
+        ? { blockedBy: [...draft.blockedBy] }
+        : {}),
+      ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+    }
+    const targetState = opts.state === undefined ? this.createState : stateDir(opts.state)
+    await writeFile(this.pathIn(targetState, front.id), serializeTicketFile(front, draft.body))
+    return this.toTicket(front, draft.body, targetState)
+  }
+
+  async update(id: string, patch: TicketUpdate): Promise<void> {
+    const validated = validateTicketUpdate(patch)
+    await this.ensureLayout()
+    const loaded = await this.requireForWrite(id, 'update')
+    const front: Frontmatter = {
+      ...loaded.front,
+      ...(validated.title !== undefined ? { title: validated.title } : {}),
+      ...(validated.labels !== undefined ? { labels: [...validated.labels] } : {}),
+    }
+    await this.rewriteAt(loaded.found, front, validated.body ?? loaded.body)
+  }
+
+  async addBlocker(id: string, blockerId: string): Promise<void> {
+    await this.ensureLayout()
+    const loaded = await this.requireForWrite(id, 'addBlocker')
+    if (id === blockerId) {
+      throw new Error(`file ticket source: ticket "${id}" cannot block itself`)
+    }
+
+    const blocker = await this.locate(blockerId)
+    if (blocker === null) {
+      throw new Error(
+        `file ticket source: addBlocker on ticket "${id}" names unknown blocker "${blockerId}"`,
+      )
+    }
+    await this.loadAt(blocker) // Existence means a valid ticket, not only a path.
+
+    if (loaded.front.blockedBy?.includes(blockerId)) return
+    await this.rewriteAt(
+      loaded.found,
+      {
+        ...loaded.front,
+        blockedBy: [...(loaded.front.blockedBy ?? []), blockerId],
+      },
+      loaded.body,
+    )
+  }
+
+  async removeBlocker(id: string, blockerId: string): Promise<void> {
+    await this.ensureLayout()
+    const loaded = await this.requireForWrite(id, 'removeBlocker')
+    const remaining = (loaded.front.blockedBy ?? []).filter((candidate) => candidate !== blockerId)
+    if (remaining.length === (loaded.front.blockedBy ?? []).length) return
+
+    const front: Frontmatter = { ...loaded.front }
+    if (remaining.length === 0) delete front.blockedBy
+    else front.blockedBy = remaining
+    await this.rewriteAt(loaded.found, front, loaded.body)
+  }
+
+  /**
+   * Dependency nodes (§13). Resolution is this source's own lifecycle, and
+   * this source's lifecycle is the filesystem: a blocker is complete when its
+   * file sits in the done directory. Nothing is read from the frontmatter to
+   * decide it — there is no `state` field to disagree with the directory.
+   *
+   * An id that cannot name a file (path traversal) is reported as
+   * `exists: false` rather than thrown: a bad reference is a missing
+   * dependency, and one ticket's typo must not abort the whole tick. A
+   * *malformed* file still throws — that is operator error about a real
+   * ticket, and the dispatcher confines the blast radius to the one ticket
+   * that referenced it.
+   */
+  async dependencyStates(ids: string[]): Promise<DependencyState[]> {
+    const states: DependencyState[] = []
+    for (const id of ids) {
+      let found: Located | null
+      try {
+        found = await this.locate(id)
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('invalid ticket id')) {
+          states.push({ id, exists: false, resolved: false, blockedBy: [] })
+          continue
+        }
+        throw error
+      }
+      if (found === null) {
+        states.push({ id, exists: false, resolved: false, blockedBy: [] })
+        continue
+      }
+      const loaded = await this.loadAt(found)
+      states.push({
+        id,
+        exists: true,
+        resolved: found.state === this.doneState,
+        blockedBy: [...(loaded.front.blockedBy ?? [])],
+      })
+    }
+    return states
+  }
+
+  /**
+   * The four state dirs, plus — for the defaulted backlog only — a
+   * self-excluding `.gitignore`. Same move `src/cli/context.ts` makes for
+   * `.ab/`: the dir hides itself from git in ANY repo, so the local backlog is
+   * never staged, without mutating the repo's own tracked `.gitignore` as an
+   * unreviewed side effect. Idempotent; called at the head of every write.
+   */
+  private async ensureLayout(): Promise<void> {
+    for (const state of TICKET_STATES) {
+      await mkdir(join(this.dir, dirName(state)), { recursive: true })
+    }
+    if (this.selfIgnore) await writeFile(join(this.dir, '.gitignore'), '*\n')
+  }
+
+  private pathIn(state: TicketState, id: string): string {
+    return join(this.dir, dirName(state), `${this.safeId(id)}.md`)
+  }
+
+  private safeId(id: string): string {
+    if (id.includes('/') || id.includes('\\') || id.includes('..')) {
+      throw new Error(`file ticket source: invalid ticket id "${id}"`)
+    }
+    return id
+  }
+
+  /** Find the one state dir holding `<id>.md`; null when absent. */
+  private async locate(id: string): Promise<Located | null> {
+    this.safeId(id)
+    const hits: Located[] = []
+    for (const state of TICKET_STATES) {
+      const path = this.pathIn(state, id)
+      try {
+        await stat(path)
+        hits.push({ id, state, path })
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      }
+    }
+    if (hits.length > 1)
+      throw duplicateError(
+        id,
+        hits.map((h) => h.path),
+      )
+    return hits[0] ?? null
+  }
+
+  /** Every ticket file across the four state dirs, sorted, duplicates rejected. */
+  private async scan(): Promise<Located[]> {
+    await this.assertNoLooseTickets()
+    const byId = new Map<string, Located[]>()
+    for (const state of TICKET_STATES) {
+      for (const entry of await this.readMarkdown(join(this.dir, dirName(state)))) {
+        const id = entry.slice(0, -'.md'.length)
+        const located = { id, state, path: join(this.dir, dirName(state), entry) }
+        byId.set(id, [...(byId.get(id) ?? []), located])
+      }
+    }
+    for (const [id, hits] of byId) {
+      if (hits.length > 1)
+        throw duplicateError(
+          id,
+          hits.map((h) => h.path),
+        )
+    }
+    return [...byId.values()].flat().sort((a, b) => a.id.localeCompare(b.id))
+  }
+
+  /**
+   * A `.md` at the tracker root has no state — it is invisible to every scan
+   * and would never dispatch. Name it rather than ignore it.
+   */
+  private async assertNoLooseTickets(): Promise<void> {
+    for (const entry of await this.readMarkdown(this.dir)) {
+      throw new Error(
+        `${join(this.dir, entry)}: ticket file outside a state directory — a ticket's ` +
+          `state is the directory it sits in; move it into one of: ` +
+          `${TICKET_STATES.map(dirName).join('/, ')}/`,
+      )
+    }
+  }
+
+  private async readMarkdown(path: string): Promise<string[]> {
+    try {
+      return (await readdir(path)).filter((e) => e.endsWith('.md')).sort()
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+      throw error
+    }
+  }
+
+  private async loadAt(found: Located): Promise<{ front: Frontmatter; body: string }> {
+    const loaded = parseTicketFile(found.path, await readFile(found.path, 'utf8'))
+    if (loaded.front.id !== found.id) {
+      throw new TicketFileValidationError(
+        `${found.path}: frontmatter id "${loaded.front.id}" does not match filename`,
+      )
+    }
+    return loaded
+  }
+
+  private async requireForWrite(
+    id: string,
+    operation: string,
+  ): Promise<{ found: Located; front: Frontmatter; body: string }> {
+    const found = await this.locate(id)
+    if (found === null) {
+      throw new Error(`file ticket source: ${operation} on unknown ticket "${id}"`)
+    }
+    return { found, ...(await this.loadAt(found)) }
+  }
+
+  /** Rewrite only the located file: editable writes can never move lifecycle
+   * state because the existing state-directory path remains authoritative. */
+  private async rewriteAt(found: Located, front: Frontmatter, body: string): Promise<void> {
+    await writeFile(found.path, serializeTicketFile(front, body))
+  }
+
+  private async listAll(): Promise<TicketListing> {
+    const tickets: Ticket[] = []
+    const diagnostics: string[] = []
+    // Complete discovery first. Structural failures (including duplicate ids)
+    // therefore win even when one of the discovered records is also malformed.
+    const located = await this.scan()
+    for (const found of located) {
+      try {
+        const loaded = await this.loadAt(found)
+        tickets.push(this.toTicket(loaded.front, loaded.body, found.state))
+      } catch (error) {
+        if (error instanceof TicketFileValidationError) {
+          diagnostics.push(error.message)
+          continue
+        }
+        throw error
+      }
+    }
+    return { tickets, diagnostics }
+  }
+
+  private toTicket(front: Frontmatter, body: string, state: TicketState): Ticket {
+    return {
+      ref: { source: this.name, id: front.id, title: front.title },
+      ...(front.idempotencyKey !== undefined ? { creationKey: front.idempotencyKey } : {}),
+      title: front.title,
+      body,
+      state,
+      labels: [...front.labels],
+      ...(front.blockedBy !== undefined && front.blockedBy.length > 0
+        ? { blockedBy: [...front.blockedBy] }
+        : {}),
+    }
+  }
+}
+
+function duplicateError(id: string, paths: string[]): Error {
+  return new Error(
+    `file ticket source: ticket "${id}" exists in more than one state directory: ` +
+      `${paths.join(', ')} — a ticket's state is the directory it sits in; keep ` +
+      `exactly one copy (use mv, not cp)`,
+  )
+}