@defrex/autobuild 0.9.0 → 0.10.0

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

@@ -1,6 +1,7 @@
 /**
  * File-based TicketSource (SPEC §3.2, §13): the default tracker. A directory
- * of state directories — `triage/ ready/ doing/ done/` — each holding
+ * of state directories — the lifecycle four `triage/ ready/ doing/ done/`
+ * plus any the repository adds, such as `icebox/` — 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
@@ -19,6 +20,7 @@
  * human edits are explicitly last-write-wins. State renames never cross a
  * filesystem: `<dir>/ready` → `<dir>/doing` is one mount by construction.
  */
+import { readdirSync, statSync } from 'node:fs'
 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'
@@ -31,40 +33,64 @@ import type {
   TicketDraft,
   TicketListing,
   TicketSource,
+  TicketStateInfo,
   TicketUpdate,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
+/** Repo-relative fallback when no selected local-state root is supplied. */
+export const DEFAULT_TICKETS_DIR = '.autobuild/tickets'
+
 /**
- * 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.
+ * The directories the dispatcher's roles (create, ready, claim, triage, done)
+ * are played by. Always valid state names, because `ensureLayout` creates them.
  */
-export const TICKET_STATES = ['Triage', 'Ready', 'Doing', 'Done'] as const
-export type TicketState = (typeof TICKET_STATES)[number]
+const LIFECYCLE_DIRS = ['triage', 'ready', 'doing', 'done'] as const
 
-/** Repo-relative fallback when no selected local-state root is supplied. */
-export const DEFAULT_TICKETS_DIR = '.autobuild/tickets'
+/** Dotfile inside a state directory holding its one-line purpose. Dot entries
+ * and non-`.md` files are never tickets, so it can never be mistaken for one. */
+const ABOUT_FILE = '.about'
+
+const STATE_NAME_RULE =
+  'a state name is one to forty characters of lowercase letters, digits, and hyphens, starting with a letter'
+const STATE_NAME_RE = /^[a-z][a-z0-9-]{0,39}$/
+
+/** Throws, stating the rule, unless `name` may be used to create a state. */
+export function validateStateName(name: string): void {
+  if (!STATE_NAME_RE.test(name)) {
+    throw new Error(`file ticket source: invalid state name "${name}" — ${STATE_NAME_RULE}`)
+  }
+}
+
+/** The state names a root listing yields: the lifecycle four, then every other
+ * non-dot directory alphabetically. Dot entries and files are never states. */
+function statesIn(directories: string[]): string[] {
+  const lifecycle: string[] = [...LIFECYCLE_DIRS]
+  const extra = directories
+    .filter((name) => !name.startsWith('.') && !lifecycle.includes(name))
+    .sort()
+  return [...lifecycle, ...extra]
+}
 
 /**
- * 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.
+ * Resolve a state name to its directory. Case-insensitive in (a config's
+ * `readyState = "ready"` means the `ready/` directory), the directory's real
+ * name out — and a name matching no directory is a loud error, because a
+ * typo'd state must not silently create a directory no `ls` would show.
  */
-export function stateDir(state: string): TicketState {
-  const match = TICKET_STATES.find((s) => s.toLowerCase() === state.toLowerCase())
-  if (match === undefined) {
+function resolveState(name: string, existing: string[]): string {
+  if (existing.includes(name)) return name
+  const matches = existing.filter((s) => s.toLowerCase() === name.toLowerCase())
+  if (matches.length === 1) return matches[0] as string
+  if (matches.length > 1) {
     throw new Error(
-      `file ticket source: unknown state "${state}" — this tracker's states are ` +
-        `the directories: ${TICKET_STATES.join(', ')}`,
+      `file ticket source: ambiguous state "${name}" — it matches the directories ${matches.join(', ')}`,
     )
   }
-  return match
-}
-
-function dirName(state: TicketState): string {
-  return state.toLowerCase()
+  throw new Error(
+    `file ticket source: unknown state "${name}" — this tracker's states are ` +
+      `the directories: ${existing.join(', ')}`,
+  )
 }
 
 const frontmatterSchema = z.strictObject({
@@ -138,7 +164,7 @@ function serializeTicketFile(front: Frontmatter, body: string): string {
 /** A ticket file found on disk: its id, its state (= its directory), its path. */
 interface Located {
   id: string
-  state: TicketState
+  state: string
   path: string
 }
 
@@ -147,8 +173,8 @@ export class FileTicketSource implements TicketSource {
 
   private readonly dir: string
   private readonly clock: Clock
-  private readonly createState: TicketState
-  private readonly doneState: TicketState
+  private readonly createState: string
+  private readonly doneState: string
   private readonly selfIgnore: boolean
 
   constructor(opts: {
@@ -174,14 +200,20 @@ export class FileTicketSource implements TicketSource {
   }) {
     this.dir = opts.dir
     this.clock = opts.clock ?? systemClock
-    this.createState = stateDir(opts.createState ?? 'Triage')
-    this.doneState = stateDir(opts.doneState ?? 'Done')
+    const existing = this.statesSync()
+    this.createState = resolveState(opts.createState ?? 'Triage', existing)
+    this.doneState = resolveState(opts.doneState ?? 'Done', existing)
     this.selfIgnore = opts.selfIgnore ?? false
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
     const labels = criteria.labels ?? []
-    const state = criteria.state === undefined ? undefined : stateDir(criteria.state)
+    const state =
+      criteria.state === undefined ? undefined : resolveState(criteria.state, await this.states())
     // 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`
@@ -209,8 +241,8 @@ export class FileTicketSource implements TicketSource {
    * 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
+   * 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.
@@ -224,8 +256,8 @@ export class FileTicketSource implements TicketSource {
     // 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))
+    if (found.state === 'doing' || found.state === this.doneState) return false
+    await rename(found.path, this.pathIn('doing', id))
     return true
   }
 
@@ -250,7 +282,7 @@ export class FileTicketSource implements TicketSource {
   /** 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 target = resolveState(state, await this.states())
     const found = await this.locate(id)
     if (found === null) {
       throw new Error(`file ticket source: transition on unknown ticket "${id}"`)
@@ -270,9 +302,16 @@ export class FileTicketSource implements TicketSource {
    * or adopts the ticket carrying the same idempotency key. */
   async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
     await this.ensureLayout()
+    // Resolve before anything is read or written: an unknown state touches no file.
+    const targetState =
+      opts.state === undefined ? this.createState : resolveState(opts.state, await this.states())
     const located = await this.scan()
     if (opts.idempotencyKey !== undefined) {
-      const matches: Array<{ found: Located; front: Frontmatter; body: string }> = []
+      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) {
@@ -301,7 +340,6 @@ export class FileTicketSource implements TicketSource {
         : {}),
       ...(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)
   }
@@ -397,22 +435,105 @@ export class FileTicketSource implements TicketSource {
     return states
   }
 
+  /** Every state with its ticket count and purpose. Reads directories only —
+   * never parses a ticket — so a malformed record cannot hide the states. */
+  async listStates(): Promise<TicketStateInfo[]> {
+    const infos: TicketStateInfo[] = []
+    for (const name of await this.states()) infos.push(await this.stateInfo(name))
+    return infos
+  }
+
+  async addState(
+    name: string,
+    opts: { about?: string } = {},
+  ): Promise<{ state: TicketStateInfo; created: boolean }> {
+    validateStateName(name)
+    const about = opts.about === undefined ? undefined : opts.about.trim()
+    if (about !== undefined && (about === '' || /[\r\n]/.test(about))) {
+      throw new Error('file ticket source: a state purpose must be one nonblank line')
+    }
+    const existing = await this.states()
+    const clash = existing.find((s) => s !== name && s.toLowerCase() === name.toLowerCase())
+    if (clash !== undefined) {
+      throw new Error(
+        `file ticket source: state "${name}" collides with the existing state "${clash}" — ${STATE_NAME_RULE}, ` +
+          'and state names are compared case-insensitively',
+      )
+    }
+    const created = !existing.includes(name)
+    await this.ensureLayout()
+    if (created) await mkdir(join(this.dir, name))
+    if (about !== undefined) await writeFile(join(this.dir, name, ABOUT_FILE), `${about}\n`)
+    return { state: await this.stateInfo(name), created }
+  }
+
+  private async stateInfo(name: string): Promise<TicketStateInfo> {
+    const tickets = (await this.readMarkdown(join(this.dir, name))).length
+    let about: string | undefined
+    try {
+      about = (await readFile(join(this.dir, name, ABOUT_FILE), 'utf8')).trim()
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    return { name, tickets, ...(about ? { about } : {}) }
+  }
+
   /**
-   * The four state dirs, plus — for the defaulted backlog only — a
+   * The four lifecycle dirs (never a custom state: `addState` is the
+   * explicit act), 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 })
+    for (const state of LIFECYCLE_DIRS) {
+      await mkdir(join(this.dir, 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`)
+  /** The state names that exist now. Re-read per operation so a directory
+   * created while a long-running dispatcher is up is seen. */
+  private async states(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.dir, { withFileTypes: true })
+      const directories: string[] = []
+      for (const entry of entries) {
+        if (entry.isDirectory()) directories.push(entry.name)
+        else if (entry.isSymbolicLink()) {
+          const target = await stat(join(this.dir, entry.name)).catch(() => null)
+          if (target?.isDirectory()) directories.push(entry.name)
+        }
+      }
+      return statesIn(directories)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return statesIn([])
+      throw error
+    }
+  }
+
+  /** Constructor-time twin of `states()`: the only sync IO in this adapter. */
+  private statesSync(): string[] {
+    try {
+      const entries = readdirSync(this.dir, { withFileTypes: true })
+      const directories = entries
+        .filter(
+          (e) =>
+            e.isDirectory() ||
+            (e.isSymbolicLink() &&
+              statSync(join(this.dir, e.name), { throwIfNoEntry: false })?.isDirectory()),
+        )
+        .map((e) => e.name)
+      return statesIn(directories)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return statesIn([])
+      throw error
+    }
+  }
+
+  private pathIn(state: string, id: string): string {
+    return join(this.dir, state, `${this.safeId(id)}.md`)
   }
 
   private safeId(id: string): string {
@@ -426,7 +547,7 @@ export class FileTicketSource implements TicketSource {
   private async locate(id: string): Promise<Located | null> {
     this.safeId(id)
     const hits: Located[] = []
-    for (const state of TICKET_STATES) {
+    for (const state of await this.states()) {
       const path = this.pathIn(state, id)
       try {
         await stat(path)
@@ -443,14 +564,14 @@ export class FileTicketSource implements TicketSource {
     return hits[0] ?? null
   }
 
-  /** Every ticket file across the four state dirs, sorted, duplicates rejected. */
+  /** Every ticket file across every state dir, 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)))) {
+    for (const state of await this.states()) {
+      for (const entry of await this.readMarkdown(join(this.dir, state))) {
         const id = entry.slice(0, -'.md'.length)
-        const located = { id, state, path: join(this.dir, dirName(state), entry) }
+        const located = { id, state, path: join(this.dir, state, entry) }
         byId.set(id, [...(byId.get(id) ?? []), located])
       }
     }
@@ -473,7 +594,7 @@ export class FileTicketSource implements TicketSource {
       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('/, ')}/`,
+          `${(await this.states()).join('/, ')}/`,
       )
     }
   }
@@ -535,7 +656,7 @@ export class FileTicketSource implements TicketSource {
     return { tickets, diagnostics }
   }
 
-  private toTicket(front: Frontmatter, body: string, state: TicketState): Ticket {
+  private toTicket(front: Frontmatter, body: string, state: string): Ticket {
     return {
       ref: { source: this.name, id: front.id, title: front.title },
       ...(front.idempotencyKey !== undefined ? { creationKey: front.idempotencyKey } : {}),

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

@@ -238,10 +238,42 @@ export class LinearTicketSource implements TicketSource {
     return [...(await this.getTeamInfo('workflow states')).stateIds.keys()]
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  /** The Linear user a `readyAssignee` value names: `me` is the API key's
+   * owner, anything else is an email. Null when no user matches. */
+  async resolveAssignee(
+    assignee: string,
+  ): Promise<{ id: string; name: string; email: string } | null> {
+    if (assignee === 'me') {
+      const data = await this.gql<{ viewer: { id: string; name: string; email: string } | null }>(
+        'resolveAssignee',
+        'query Viewer { viewer { id name email } }',
+        {},
+      )
+      return data.viewer ?? null
+    }
+    const data = await this.gql<{
+      users: { nodes: { id: string; name: string; email: string }[] }
+    }>(
+      'resolveAssignee',
+      'query UserByEmail($email: String!) { users(filter: { email: { eq: $email } }) { nodes { id name email } } }',
+      { email: assignee },
+    )
+    return data.users.nodes[0] ?? null
+  }
+
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
     const filter: Record<string, unknown> = {
       team: { key: { eq: this.teamKey } },
     }
+    if (criteria.assignee !== undefined) {
+      // An unassigned issue matches neither predicate, so it is never ready.
+      filter.assignee =
+        criteria.assignee === 'me' ? { isMe: { eq: true } } : { email: { eq: criteria.assignee } }
+    }
     if (criteria.state !== undefined) {
       filter.state = { name: { eq: criteria.state } }
     }

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

@@ -44,7 +44,7 @@ export async function requirePostMutationTicket(
 export function ticketListCriteria(
   config: Config,
   filters: { state?: string; labels?: string[] },
-): { state?: string; labels?: string[] } {
+): { state?: string; labels?: string[]; assignee?: string } {
   return filters.state === undefined && filters.labels === undefined
     ? readyCriteria(config)
     : filters

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

@@ -86,7 +86,14 @@ export class HostedTicketSource implements TicketSource {
     return schema.parse(await response.json())
   }
 
-  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+  async listReady(criteria: {
+    labels?: string[]
+    state?: string
+    assignee?: string
+  }): Promise<TicketListing> {
+    if (criteria.assignee !== undefined) {
+      throw new Error('the hosted ticket source does not support an assignee gate')
+    }
     const listing = await this.request('list-ready', criteria, ticketListingWireSchema)
     return { ...listing, tickets: listing.tickets.map((ticket) => this.project(ticket)) }
   }

package/packages/core/src/ports/types.ts

@@ -122,12 +122,27 @@ export interface TicketUpdate {
   labels?: string[]
 }
 
+/** One workflow state of a source that can enumerate them. */
+export interface TicketStateInfo {
+  name: string
+  /** Tickets currently in the state. */
+  tickets: number
+  /** One-line purpose recorded when the state was created, if any. */
+  about?: string
+}
+
 export interface TicketSource {
   readonly name: string
   /** Ready tickets matching the dispatch criteria (label/state — §3.3), plus
    * actionable diagnostics for individual source records excluded as invalid.
    * Fatal source failures and invariants still reject the call. */
-  listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing>
+  listReady(criteria: {
+    labels?: string[]
+    state?: string
+    /** `me` (the API key's owner) or a user's email; only sources that can honour it
+     * accept it — others reject `[tickets].readyAssignee` at config parse. */
+    assignee?: string
+  }): Promise<TicketListing>
   get(id: string): Promise<Ticket | null>
   /** Claim-before-launch (§12): acquires nonterminal work and returns true.
    * Returns false for an unknown, already-claimed/contested, or terminal ticket.
@@ -154,6 +169,22 @@ export interface TicketSource {
    * are initiation, so §13's "never consulted mid-build" is untouched.
    */
   dependencyStates(ids: string[]): Promise<DependencyState[]>
+  /**
+   * Optional state discovery (`ab ticket states`): every state the source has,
+   * lifecycle states first in workflow order, then the rest alphabetically.
+   * Sources that cannot enumerate their states omit it.
+   */
+  listStates?(): Promise<TicketStateInfo[]>
+  /**
+   * Optional state creation (`ab ticket state create`). Idempotent: an existing
+   * state is reported with `created: false`, and a supplied `about` replaces its
+   * purpose. Rejects a malformed or case-colliding name without creating anything.
+   * Named `addState` because adapters already hold a `createState` option field.
+   */
+  addState?(
+    name: string,
+    opts?: { about?: string },
+  ): Promise<{ state: TicketStateInfo; created: boolean }>
 }
 
 // ── Workspace (SPEC §3.2, §7) ────────────────────────────────────────────────

package/packages/core/src/processes/build-execution-state.ts

@@ -3,6 +3,7 @@ import { configSchema } from '../config/schema'
 import { BUILD_OWNED_CONFIG_PATHS } from '../config/live'
 import { isPipelineSourceRef, type PipelineSourceMeta } from '../config/pipeline-source'
 import type { AbEvent } from '../events/catalog'
+import { defineReducer } from '../kernel/incremental'
 import type { Artifact, ArtifactInput } from '../store/types'
 
 export const BUILD_EFFECTIVE_CONFIG_ARTIFACT = 'build-runner-effective-config'
@@ -83,26 +84,41 @@ export function buildOwnedSectionsDiffer(a: Config, b: Config): boolean {
   )
 }
 
-/** Latest workspace location not followed by release. Historical events use
- * the provider ref as the path compatibility fallback. */
-export function selectOpenWorkspace(events: readonly AbEvent[]): {
+export interface OpenWorkspaceLocation {
   ref: string
   path: string
   branch: string
-} | null {
-  let open: { ref: string; path: string; branch: string } | null = null
-  for (const event of events) {
-    if (event.type === 'workspace.provisioned') {
-      open = {
-        ref: event.payload.ref,
-        path: event.payload.path ?? event.payload.ref,
-        branch: event.payload.branch,
+}
+
+export const OPEN_WORKSPACE_REDUCER_VERSION = 1
+
+/** Latest workspace location not followed by release. Historical events use
+ * the provider ref as the path compatibility fallback. */
+export const openWorkspaceReducer = defineReducer<
+  { open: OpenWorkspaceLocation | null },
+  AbEvent,
+  OpenWorkspaceLocation | null
+>({
+  version: OPEN_WORKSPACE_REDUCER_VERSION,
+  initial: () => ({ open: null }),
+  fold(acc, events) {
+    for (const event of events) {
+      if (event.type === 'workspace.provisioned') {
+        acc.open = {
+          ref: event.payload.ref,
+          path: event.payload.path ?? event.payload.ref,
+          branch: event.payload.branch,
+        }
+      } else if (event.type === 'workspace.released') {
+        acc.open = null
       }
-    } else if (event.type === 'workspace.released') {
-      open = null
     }
-  }
-  return open
+  },
+  finish: (acc) => (acc.open === null ? null : { ...acc.open }),
+})
+
+export function selectOpenWorkspace(events: readonly AbEvent[]): OpenWorkspaceLocation | null {
+  return openWorkspaceReducer.reduce(events)
 }
 
 export function diagnosticArtifact(diagnostic: BuildRunnerDiagnostic): ArtifactInput {