@defrex/autobuild 0.8.0

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

@@ -0,0 +1,135 @@
+/**
+ * TicketSource factory (SPEC §3.2, §13): construct the builtin or plugin source
+ * named by [tickets]. Plugin credentials, like LINEAR_API_KEY, come only from
+ * the environment. This remains the single boundary for file-directory
+ * defaulting and for registry-aware source selection.
+ */
+import { resolve } from 'node:path'
+import type { TicketsConfig } from '../../config/schema'
+import { createPluginRegistry, type PluginRegistry } from '../../plugins/registry'
+import type { PluginFactoryContext } from '../../plugins/manifest'
+import type { TicketSource } from '../types'
+import { DEFAULT_TICKETS_DIR, FileTicketSource } from './file'
+import { LinearTicketSource } from './linear'
+import { HostedTicketSource } from './remote'
+
+function reason(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export async function createTicketSource(
+  config: TicketsConfig,
+  env: Record<string, string | undefined>,
+  /** A relative [tickets].dir is relative to the repo, not this process's cwd. */
+  targetRepo: string,
+  /** Selected local state root. Remote stores pass the repo-local default. */
+  localStateRoot?: string,
+  /** Registry loaded from this repository's configured plugins. */
+  plugins: PluginRegistry = createPluginRegistry(),
+): Promise<TicketSource> {
+  if (config.source === 'hosted') {
+    const rawUrl = env.AB_STORE?.trim()
+    if (!rawUrl) {
+      throw new Error(
+        'AB_STORE is not set — required when [tickets].source = "hosted"; set it to the hosted service HTTP(S) URL',
+      )
+    }
+    let serviceUrl: URL
+    try {
+      serviceUrl = new URL(rawUrl)
+    } catch {
+      throw new Error('AB_STORE must be a valid HTTP(S) URL when [tickets].source = "hosted"')
+    }
+    if (serviceUrl.protocol !== 'http:' && serviceUrl.protocol !== 'https:') {
+      throw new Error('AB_STORE must be an HTTP(S) URL when [tickets].source = "hosted"')
+    }
+    const token = env.AB_TOKEN?.trim()
+    if (!token) {
+      throw new Error(
+        'AB_TOKEN is not set — an operator-scope token is required when [tickets].source = "hosted"',
+      )
+    }
+    if (config.teamKey === undefined) {
+      throw new Error('[tickets].source = "hosted" requires teamKey')
+    }
+    return new HostedTicketSource({
+      url: serviceUrl.toString(),
+      token,
+      teamKey: config.teamKey,
+      ...(config.claimedState !== undefined ? { claimedState: config.claimedState } : {}),
+      ...(config.createState !== undefined ? { createState: config.createState } : {}),
+    })
+  }
+
+  if (config.source === 'linear') {
+    const apiKey = env.LINEAR_API_KEY
+    if (apiKey === undefined || apiKey === '') {
+      throw new Error(
+        'LINEAR_API_KEY is not set — expected a Linear personal API key; ' +
+          'required when [tickets].source = "linear". Set it in the ' +
+          'environment or a local .env file.',
+      )
+    }
+    // teamKey presence is cross-validated at config parse; re-checked here
+    // because plugin configurations can carry the same optional field.
+    if (config.teamKey === undefined) {
+      throw new Error(
+        '[tickets].source = "linear" requires teamKey — the Linear team key (e.g. "ENG")',
+      )
+    }
+    return new LinearTicketSource({
+      apiKey,
+      teamKey: config.teamKey,
+      ...(config.claimedState !== undefined ? { claimedState: config.claimedState } : {}),
+      ...(config.createState !== undefined ? { createState: config.createState } : {}),
+    })
+  }
+
+  if (config.source === 'file') {
+    return new FileTicketSource({
+      dir:
+        config.dir === undefined && localStateRoot !== undefined
+          ? resolve(localStateRoot, 'tickets')
+          : resolve(targetRepo, config.dir ?? DEFAULT_TICKETS_DIR),
+      // Only the DEFAULTED backlog hides itself from git. An explicit dir is
+      // user-owned and may intentionally be tracked.
+      selfIgnore: config.dir === undefined,
+      ...(config.createState !== undefined ? { createState: config.createState } : {}),
+    })
+  }
+
+  const registration = plugins.ticketSources.get(config.source)
+  if (registration === undefined || registration.factory === undefined) {
+    const available = [...plugins.ticketSources.keys()].sort().join(', ')
+    throw new Error(
+      `unknown ticket source "${config.source}"; available ticket sources: ${available}`,
+    )
+  }
+
+  const missing = (registration.requiredEnv ?? []).filter((name) => {
+    const value = env[name]
+    return value === undefined || value === ''
+  })
+  if (missing.length > 0) {
+    throw new Error(
+      `ticket source "${config.source}" from plugin "${registration.owner.name}" ` +
+        `requires environment ${missing.map((name) => `variable "${name}"`).join(', ')}; ` +
+        'set the missing credentials in the environment or a local .env file',
+    )
+  }
+
+  const context: PluginFactoryContext = {
+    config: config as unknown as Record<string, unknown>,
+    env,
+    repoRoot: resolve(targetRepo),
+  }
+  try {
+    return await registration.factory(context)
+  } catch (error) {
+    throw new Error(
+      `ticket source "${config.source}" from plugin "${registration.owner.name}" ` +
+        `failed during construction: ${reason(error)}`,
+      { cause: error },
+    )
+  }
+}

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

@@ -0,0 +1,215 @@
+/**
+ * In-memory TicketSource for seam tests (SPEC §3.2, §13). Mirrors the policy
+ * shape of the real adapters: initiation (listReady/get/claim/create),
+ * pre-build grooming writes (update/blockers), and outward projections
+ * (comment/transition), all journaled where seam tests need exact evidence.
+ */
+import type {
+  DependencyState,
+  Ticket,
+  TicketCreateOptions,
+  TicketDraft,
+  TicketListing,
+  TicketSource,
+  TicketUpdate,
+} from '../types'
+import { validateTicketUpdate } from './update'
+
+function cloneTicket(ticket: Ticket): Ticket {
+  return {
+    ref: { ...ticket.ref },
+    ...(ticket.creationKey !== undefined ? { creationKey: ticket.creationKey } : {}),
+    title: ticket.title,
+    body: ticket.body,
+    state: ticket.state,
+    labels: [...ticket.labels],
+    ...(ticket.blockedBy !== undefined ? { blockedBy: [...ticket.blockedBy] } : {}),
+  }
+}
+
+export class FakeTicketSource implements TicketSource {
+  readonly name = 'fake'
+
+  /** Journal of every projection sent outward (§13), in call order. */
+  readonly comments: Array<{ id: string; body: string }> = []
+  readonly transitions: Array<{ id: string; state: string }> = []
+  /** Every accepted grooming write, including idempotent blocker retries. */
+  readonly updates: Array<{ id: string; patch: TicketUpdate }> = []
+  readonly blockerAdds: Array<{ id: string; blockerId: string }> = []
+  readonly blockerRemovals: Array<{ id: string; blockerId: string }> = []
+  /** Ids claimed, in call order — lets tests assert a blocked ticket was
+   * never claimed (§12: gating precedes claim-before-launch). */
+  readonly claims: string[] = []
+  /** Every `dependencyStates` request, in call order — lets tests assert a
+   * dependency-free ticket costs zero port calls. */
+  readonly dependencyQueries: string[][] = []
+
+  private readonly tickets = new Map<string, Ticket>()
+  private readonly claimed = new Set<string>()
+  private readonly idempotency = new Map<string, string>()
+  private readonly createState: string
+  private readonly doneState: string
+  private nextId = 1
+
+  constructor(
+    seed: Ticket[] = [],
+    opts: {
+      /** State assigned by create — proposals land in Triage (SPEC §12). */
+      createState?: string
+      /** State this fake treats as resolved for dependencies (§13: the
+       * adapter owns what "complete" means). */
+      doneState?: string
+    } = {},
+  ) {
+    for (const ticket of seed) {
+      this.tickets.set(ticket.ref.id, cloneTicket(ticket))
+      if (ticket.creationKey !== undefined) {
+        this.idempotency.set(ticket.creationKey, ticket.ref.id)
+      }
+    }
+    this.createState = opts.createState ?? 'Triage'
+    this.doneState = opts.doneState ?? 'Done'
+  }
+
+  /** Seed a ticket after construction — lets a test make one become Ready
+   * mid-run, which is how "a single pass does not claim tickets that arrive
+   * after its initial selection" (§12) gets a real oracle rather than a
+   * vacuous one. */
+  add(ticket: Ticket): void {
+    this.tickets.set(ticket.ref.id, cloneTicket(ticket))
+  }
+
+  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+    const labels = criteria.labels ?? []
+    return {
+      tickets: [...this.tickets.values()]
+        .filter(
+          (ticket) =>
+            (criteria.state === undefined || ticket.state === criteria.state) &&
+            labels.every((label) => ticket.labels.includes(label)),
+        )
+        .map(cloneTicket),
+      diagnostics: [],
+    }
+  }
+
+  async get(id: string): Promise<Ticket | null> {
+    const ticket = this.tickets.get(id)
+    return ticket ? cloneTicket(ticket) : null
+  }
+
+  /** Claim-before-launch: true once per nonterminal lifecycle stay. A later
+   * explicit transition releases the fake claim, but the configured terminal
+   * state remains unclaimable and cannot be used as an implicit reopen. */
+  async claim(id: string): Promise<boolean> {
+    this.claims.push(id)
+    const ticket = this.tickets.get(id)
+    if (!ticket || ticket.state === this.doneState || this.claimed.has(id)) return false
+    this.claimed.add(id)
+    return true
+  }
+
+  async comment(id: string, body: string): Promise<void> {
+    this.require(id, 'comment')
+    this.comments.push({ id, body })
+  }
+
+  async transition(id: string, state: string): Promise<void> {
+    const ticket = this.require(id, 'transition')
+    ticket.state = state
+    this.claimed.delete(id)
+    this.transitions.push({ id, state })
+  }
+
+  async create(draft: TicketDraft, opts: TicketCreateOptions = {}): Promise<Ticket> {
+    if (opts.idempotencyKey !== undefined) {
+      const adopted = this.idempotency.get(opts.idempotencyKey)
+      if (adopted !== undefined) return cloneTicket(this.require(adopted, 'create'))
+    }
+    const id = `fake-${this.nextId++}`
+    const ticket: Ticket = {
+      ref: { source: this.name, id, title: draft.title },
+      ...(opts.idempotencyKey !== undefined ? { creationKey: opts.idempotencyKey } : {}),
+      title: draft.title,
+      body: draft.body,
+      state: opts.state ?? this.createState,
+      labels: [...(draft.labels ?? [])],
+      // Recorded verbatim, never discarded — the same contract the real
+      // adapters owe (§13).
+      ...(draft.blockedBy !== undefined && draft.blockedBy.length > 0
+        ? { blockedBy: [...draft.blockedBy] }
+        : {}),
+    }
+    this.tickets.set(id, ticket)
+    if (opts.idempotencyKey !== undefined) {
+      this.idempotency.set(opts.idempotencyKey, id)
+    }
+    return cloneTicket(ticket)
+  }
+
+  async update(id: string, patch: TicketUpdate): Promise<void> {
+    const validated = validateTicketUpdate(patch)
+    const ticket = this.require(id, 'update')
+
+    if (validated.title !== undefined) {
+      ticket.title = validated.title
+      ticket.ref.title = validated.title
+    }
+    if (validated.body !== undefined) ticket.body = validated.body
+    if (validated.labels !== undefined) ticket.labels = [...validated.labels]
+
+    this.updates.push({ id, patch: cloneUpdate(validated) })
+  }
+
+  async addBlocker(id: string, blockerId: string): Promise<void> {
+    const ticket = this.require(id, 'addBlocker')
+    if (id === blockerId) {
+      throw new Error(`fake ticket source: ticket "${id}" cannot block itself`)
+    }
+    this.require(blockerId, 'addBlocker')
+
+    this.blockerAdds.push({ id, blockerId })
+    if (ticket.blockedBy?.includes(blockerId)) return
+    ticket.blockedBy = [...(ticket.blockedBy ?? []), blockerId]
+  }
+
+  async removeBlocker(id: string, blockerId: string): Promise<void> {
+    const ticket = this.require(id, 'removeBlocker')
+    this.blockerRemovals.push({ id, blockerId })
+
+    const remaining = (ticket.blockedBy ?? []).filter((candidate) => candidate !== blockerId)
+    if (remaining.length === 0) delete ticket.blockedBy
+    else ticket.blockedBy = remaining
+  }
+
+  /** Resolution is this fake's own lifecycle: `doneState` and nothing else. */
+  async dependencyStates(ids: string[]): Promise<DependencyState[]> {
+    this.dependencyQueries.push([...ids])
+    return ids.map((id) => {
+      const ticket = this.tickets.get(id)
+      if (!ticket) return { id, exists: false, resolved: false, blockedBy: [] }
+      return {
+        id,
+        exists: true,
+        resolved: ticket.state === this.doneState,
+        blockedBy: [...(ticket.blockedBy ?? [])],
+      }
+    })
+  }
+
+  private require(id: string, operation: string): Ticket {
+    const ticket = this.tickets.get(id)
+    if (!ticket) {
+      throw new Error(`fake ticket source: ${operation} on unknown ticket "${id}"`)
+    }
+    return ticket
+  }
+}
+
+function cloneUpdate(patch: TicketUpdate): TicketUpdate {
+  return {
+    ...(patch.title !== undefined ? { title: patch.title } : {}),
+    ...(patch.body !== undefined ? { body: patch.body } : {}),
+    ...(patch.labels !== undefined ? { labels: [...patch.labels] } : {}),
+  }
+}