@defrex/autobuild 0.12.0 → 0.13.0

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

@@ -1,3 +1,5 @@
+import { hostedRequestedIds } from './requested-id'
+import { TicketRevisionConflict } from './revision'
 import type {
   DependencyState,
   Ticket,
@@ -6,16 +8,25 @@ import type {
   TicketListing,
   TicketSource,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
-import { AuthError } from '../../store/remote/client'
+import { RemoteBuildStore, AuthError } from '../../store/remote/client'
 import { errorBodySchema } from '../../store/remote/protocol'
 import {
   claimWireSchema,
+  TICKET_REVISIONS_HEADER,
+  TICKET_REVISIONS_CAPABILITY,
+  hostedTicketPolicySchema,
+  type HostedTicketPolicy,
+  TICKET_COMMENTS_HEADER,
+  TICKET_COMMENTS_CAPABILITY,
   dependencyStatesWireSchema,
   type HostedTicketContext,
   successWireSchema,
   ticketListingWireSchema,
   ticketWireSchema,
+  ticketStatesWireSchema,
+  ticketStateCreateWireSchema,
 } from './remote-protocol'
 import {
   AUTOBUILD_VERSION,
@@ -38,12 +49,27 @@ export interface HostedTicketSourceOptions extends HostedTicketContext {
 /** Full TicketSource client for a hosted Autobuild service. */
 export class HostedTicketSource implements TicketSource {
   readonly name = 'hosted'
+  readonly requestedIds: ReturnType<typeof hostedRequestedIds>
+  readonly assets: import('../types').TicketAssetStore
   private readonly base: string
   private readonly token: string
   private readonly fetchFn: HostedTicketFetch
   private readonly context: HostedTicketContext
 
   constructor(options: HostedTicketSourceOptions) {
+    this.requestedIds = hostedRequestedIds(options.teamKey)
+    const client = new RemoteBuildStore({
+      url: options.url,
+      token: options.token,
+      ...(options.fetchFn ? { fetchFn: options.fetchFn as typeof fetch } : {}),
+    })
+    this.assets = {
+      ticketAssetLimits: client.ticketAssetLimits.bind(client),
+      putTicketAsset: client.putTicketAsset.bind(client),
+      getTicketAsset: client.getTicketAsset.bind(client),
+      listTicketAssets: client.listTicketAssets.bind(client),
+      removeTicketAsset: client.removeTicketAsset.bind(client),
+    }
     this.base = options.url.replace(/\/+$/, '')
     this.token = options.token
     this.fetchFn = options.fetchFn ?? fetch
@@ -55,6 +81,10 @@ export class HostedTicketSource implements TicketSource {
     }
   }
 
+  async synchronizePolicy(policy: HostedTicketPolicy): Promise<void> {
+    await this.request('policy', hostedTicketPolicySchema.parse(policy), successWireSchema)
+  }
+
   private project(ticket: Ticket): Ticket {
     return { ...ticket, ref: { ...ticket.ref, source: this.name } }
   }
@@ -68,7 +98,9 @@ export class HostedTicketSource implements TicketSource {
       method: 'POST',
       headers: {
         'content-type': 'application/json',
+        [TICKET_COMMENTS_HEADER]: TICKET_COMMENTS_CAPABILITY,
         authorization: `Bearer ${this.token}`,
+        [TICKET_REVISIONS_HEADER]: TICKET_REVISIONS_CAPABILITY,
         [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
         [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
       },
@@ -77,8 +109,17 @@ export class HostedTicketSource implements TicketSource {
     if (!response.ok) {
       let message = `ticket service responded ${response.status}`
       try {
-        message = errorBodySchema.parse(await response.json()).error
-      } catch {
+        const body = (await response.json()) as Record<string, unknown>
+        if (
+          response.status === 409 &&
+          typeof body.currentRevision === 'string' &&
+          typeof body.expectedRevision === 'string' &&
+          typeof body.id === 'string'
+        )
+          throw new TicketRevisionConflict(body.id, body.expectedRevision, body.currentRevision)
+        message = errorBodySchema.parse(body).error
+      } catch (error) {
+        if (error instanceof TicketRevisionConflict) throw error
         // Keep the status-only safe fallback for non-protocol responses.
       }
       if (response.status === 401 || response.status === 403) throw new AuthError(message)
@@ -99,6 +140,14 @@ export class HostedTicketSource implements TicketSource {
     return { ...listing, tickets: listing.tickets.map((ticket) => this.project(ticket)) }
   }
 
+  async listStates() {
+    return this.request('states', {}, ticketStatesWireSchema)
+  }
+
+  async addState(name: string, opts: { about?: string } = {}) {
+    return this.request('add-state', { name, ...opts }, ticketStateCreateWireSchema)
+  }
+
   async get(id: string): Promise<Ticket | null> {
     const ticket = await this.request('get', { id }, ticketWireSchema.nullable())
     return ticket === null ? null : this.project(ticket)
@@ -120,6 +169,14 @@ export class HostedTicketSource implements TicketSource {
     return this.project(await this.request('create', { draft, options }, ticketWireSchema))
   }
 
+  async mutateIfRevision(
+    id: string,
+    expectedRevision: string,
+    mutation: TicketMutation,
+  ): Promise<void> {
+    await this.request('mutate-if-revision', { id, expectedRevision, mutation }, successWireSchema)
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     await this.request('update', { id, patch }, successWireSchema)
   }

package/packages/core/src/ports/tickets/requested-id.ts

@@ -0,0 +1,46 @@
+/** Requested-id policies shared by adapter writes and migration preflight. */
+export interface RequestedIdPolicy {
+  preserve(id: string): string | undefined
+  allocate(occupied: string[]): string
+}
+
+export function validateFileTicketId(id: string): string {
+  if (!id || id === '.' || /[/\\\0]/.test(id) || id.includes('..'))
+    throw new Error(`file ticket source: invalid ticket id "${id}"`)
+  return id
+}
+
+export const fileRequestedIds: RequestedIdPolicy = {
+  preserve: validateFileTicketId,
+  allocate(occupied) {
+    let n = 1
+    while (occupied.includes(`file-${n}`)) n++
+    return `file-${n}`
+  },
+}
+
+export const MAX_TICKET_NUMBER = 9223372036854775807n
+export function hostedRequestedIds(teamKey: string): RequestedIdPolicy {
+  const numberOf = (id: string): bigint | undefined => {
+    if (!id.startsWith(`${teamKey}-`)) return undefined
+    const suffix = id.slice(teamKey.length + 1)
+    if (!/^[1-9][0-9]*$/.test(suffix)) return undefined
+    const n = BigInt(suffix)
+    if (n > MAX_TICKET_NUMBER) throw new Error(`ticket number exceeds PostgreSQL bigint: ${id}`)
+    return n
+  }
+  return {
+    preserve(id) {
+      return numberOf(id) === undefined ? undefined : id
+    },
+    allocate(occupied) {
+      let max = 0n
+      for (const id of occupied) {
+        const n = numberOf(id)
+        if (n !== undefined && n > max) max = n
+      }
+      if (max === MAX_TICKET_NUMBER) throw new Error('ticket numbers exhausted')
+      return `${teamKey}-${max + 1n}`
+    },
+  }
+}

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

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto'
+import type { Ticket, TicketMutation, TicketSource } from '../types'
+
+/** Content versions intentionally return to the same value after an exact revert. */
+export function ticketRevision(
+  ticket: Pick<Ticket, 'title' | 'body' | 'labels' | 'state' | 'blockedBy'> & {
+    comments?: Ticket['comments']
+    attachments?: unknown
+  },
+): string {
+  return createHash('sha256')
+    .update(
+      JSON.stringify([
+        ticket.title,
+        ticket.body,
+        [...new Set(ticket.labels)].sort(),
+        ticket.state ?? null,
+        [...new Set(ticket.blockedBy ?? [])].sort(),
+        ...(ticket.comments !== undefined || ticket.attachments !== undefined
+          ? [ticket.comments ?? null, ticket.attachments ?? null]
+          : []),
+      ]),
+    )
+    .digest('hex')
+}
+
+export class TicketRevisionConflict extends Error {
+  constructor(
+    readonly id: string,
+    readonly expectedRevision: string,
+    readonly currentRevision: string,
+  ) {
+    super(
+      `ticket "${id}" changed: expected revision ${expectedRevision}, current revision ${currentRevision}`,
+    )
+    this.name = 'TicketRevisionConflict'
+  }
+}
+
+export class TicketRevisionUnsupported extends Error {
+  constructor(source: string) {
+    super(`${source} ticket source does not support revision-checked writes`)
+    this.name = 'TicketRevisionUnsupported'
+  }
+}
+
+export function checkTicketRevision(ticket: Ticket, expected: string): void {
+  if (!expected.trim()) throw new Error('expected revision must be nonblank')
+  if (ticket.revision !== expected)
+    throw new TicketRevisionConflict(ticket.ref.id, expected, ticket.revision)
+}
+
+export async function mutateTicketIfRevision(
+  source: TicketSource,
+  id: string,
+  expected: string,
+  mutation: TicketMutation,
+): Promise<void> {
+  if (!expected.trim()) throw new Error('expected revision must be nonblank')
+  if (!source.mutateIfRevision) throw new TicketRevisionUnsupported(source.name)
+  await source.mutateIfRevision(id, expected, mutation)
+}

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

@@ -0,0 +1,61 @@
+/** Shared state rules; configured names are deliberately not create-validated. */
+export const STATE_NAME_RULE =
+  'a state name is one to forty characters of lowercase letters, digits, and hyphens, starting with a letter'
+
+export function validateStateName(name: string, source = 'file ticket source'): void {
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(name)) {
+    throw new Error(`${source}: invalid state name "${name}" — ${STATE_NAME_RULE}`)
+  }
+}
+
+export function validateStatePurpose(
+  value: string | undefined,
+  source = 'file ticket source',
+): string | undefined {
+  const about = value?.trim()
+  if (about !== undefined && (about === '' || /[\r\n]/.test(about))) {
+    throw new Error(`${source}: a state purpose must be one nonblank line`)
+  }
+  return about
+}
+
+export function orderStates(names: string[], lifecycle: readonly string[]): string[] {
+  const first = [...new Set(lifecycle)].filter((name) => names.includes(name))
+  return [...first, ...names.filter((name) => !first.includes(name)).sort()]
+}
+
+export function resolveState(
+  name: string,
+  existing: string[],
+  source = 'file ticket source',
+): 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
+  const directories = source === 'file ticket source'
+  if (matches.length > 1) {
+    throw new Error(
+      `${source}: ambiguous state "${name}" — it matches the ${directories ? 'directories' : 'states'} ${matches.join(', ')}`,
+    )
+  }
+  throw new Error(
+    `${source}: unknown state "${name}" — this tracker's states are ${directories ? 'the directories: ' : ''}${existing.join(', ')}`,
+  )
+}
+
+/** Portable directory vocabulary, without guessing lifecycle roles. */
+export function normalizeStateName(name: string): string {
+  if (/^[a-z][a-z0-9-]{0,39}$/.test(name)) return name
+  const candidate = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+  try {
+    validateStateName(candidate)
+  } catch {
+    throw new Error(`invalid state "${name}" (normalized: "${candidate}")`)
+  }
+  return candidate
+}

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

@@ -1,3 +1,4 @@
+import type { BuildStore } from '../store/types'
 /**
  * Ports (SPEC §3.2): interfaces to the world, each with swappable adapters.
  * The kernel and processes depend only on these types; adapters live in
@@ -49,7 +50,19 @@ export interface SessionStreamSink extends SessionStreamEmitter {
 // never consulted mid-build and never used as artifact storage. A file-based
 // adapter with nowhere to put blobs must be fully workable.
 
+/** A recorded comment, with its exact body and source timestamp. */
+export interface TicketComment {
+  body: string
+  createdAt: string
+  author?: string
+}
+
 export interface Ticket {
+  /** Opaque source version of title, body, labels, state and blockers. */
+  revision: string
+  /** Complete history oldest first when exposed by this read. Absent means
+   * unsupported; an empty array means no comments. Bodies are unchanged. */
+  comments?: TicketComment[]
   ref: TicketRef
   /** Stable source-native key used to correlate an externally created ticket
    * with Autobuild's durable creation reservation. It is separate from the
@@ -106,6 +119,8 @@ export interface DependencyState {
 }
 
 export interface TicketCreateOptions {
+  /** Requested source id. Unsupported adapters must reject it. */
+  requestedId?: string
   /** Explicit workflow state for this create (harvest always targets Triage). */
   state?: string
   /** Source-level adoption key for crash-safe external creation. File and fake
@@ -148,7 +163,29 @@ export class TicketSourceRateLimitError extends Error {
   }
 }
 
+export type TicketAssetStore = {
+  /** Native ownership, including tombstones, prevents resurrection from legacy stores. */
+  hasTicketAssetHistory?(repo: string, id: string, kind: string, name: string): Promise<boolean>
+} & Pick<
+  BuildStore,
+  | 'ticketAssetLimits'
+  | 'putTicketAsset'
+  | 'getTicketAsset'
+  | 'listTicketAssets'
+  | 'removeTicketAsset'
+>
+
+export type TicketMutation =
+  | { kind: 'update'; patch: TicketUpdate }
+  | { kind: 'transition'; state: string }
+  | { kind: 'blockers'; operation: 'block' | 'unblock'; ids: string[] }
+
 export interface TicketSource {
+  /** Import support: the same pure id policy used by create, for mutation-free preflight. */
+  readonly requestedIds?: import('./tickets/requested-id').RequestedIdPolicy
+  readonly assets?: TicketAssetStore
+  /** Check and mutate at the source boundary; absent means checks are unsupported. */
+  mutateIfRevision?(id: string, expectedRevision: string, mutation: TicketMutation): Promise<void>
   readonly name: string
   /** Ready tickets matching the dispatch criteria (label/state — §3.3), plus
    * actionable diagnostics for individual source records excluded as invalid.
@@ -193,9 +230,9 @@ export interface TicketSource {
    */
   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.
+   * Optional state creation (`ab ticket state create`). Duplicate policy is
+   * adapter-specific: file creation is idempotent and can replace purpose;
+   * hosted creation refuses existing names in any case. Rejects malformed names.
    * Named `addState` because adapters already hold a `createState` option field.
    */
   addState?(

package/packages/core/src/ports/workspace/build-execution.ts

@@ -116,6 +116,7 @@ export type ExecutionObservation =
  * teardown of the environment and descendants it starts before completion. */
 export interface ExecutionLaunchAuth {
   token: string
+  tickets?: { url: string; token: string }
 }
 
 export interface BuildExecution {

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

@@ -132,7 +132,11 @@ export async function createWorkspaceProvider(
     // receives through `opts` reach the plugin factory through the context.
     return await factory({
       config: config.config,
-      env: Object.fromEntries(Object.entries(opts.env).filter(([key]) => key !== 'AB_TOKEN')),
+      env: Object.fromEntries(
+        Object.entries(opts.env).filter(
+          ([key]) => !['AB_TOKEN', 'AB_TICKET_TOKEN', 'AB_TICKET_URL'].includes(key),
+        ),
+      ),
       repoRoot: resolve(opts.repoRoot),
       ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
       ...(opts.storeRef !== undefined && opts.storeToken !== undefined

package/packages/core/src/ports/workspace/operator-sandbox.ts

@@ -27,6 +27,8 @@
 export const SANDBOX_FORBIDDEN_ENV: readonly string[] = [
   'AB_STORE',
   'AB_TOKEN',
+  'AB_TICKET_TOKEN',
+  'AB_TICKET_URL',
   'GITHUB_TOKEN',
   'GH_TOKEN',
   'LINEAR_API_KEY',

package/packages/core/src/ports/workspace/vercel-sandbox.ts

@@ -641,7 +641,7 @@ function runtimeEnvironment(
 ): Record<string, string> {
   return Object.fromEntries(
     config.environmentVariables
-      .filter((name) => name !== 'AB_TOKEN')
+      .filter((name) => !['AB_TOKEN', 'AB_TICKET_URL', 'AB_TICKET_TOKEN'].includes(name))
       .map((name) => [name, requireVercelEnvironmentValue(env, name)]),
   )
 }
@@ -947,7 +947,7 @@ export async function validateVercelSandbox(
           ['AB_STORE', options.storeRef],
           ['AB_TOKEN', options.storeToken],
           ...config.environmentVariables
-            .filter((name) => name !== 'AB_TOKEN')
+            .filter((name) => !['AB_TOKEN', 'AB_TICKET_URL', 'AB_TICKET_TOKEN'].includes(name))
             .map((name) => [name, requireVercelEnvironmentValue(options.env, name)]),
         ]),
       }),
@@ -1602,7 +1602,8 @@ export class VercelSandboxProvider implements WorkspaceProvider {
       }),
     }
     for (const name of this.options.config.environmentVariables)
-      if (name !== 'AB_TOKEN') env[name] = requireVercelEnvironmentValue(this.options.env, name)
+      if (!['AB_TOKEN', 'AB_TICKET_URL', 'AB_TICKET_TOKEN'].includes(name))
+        env[name] = requireVercelEnvironmentValue(this.options.env, name)
     const command = (await sandbox.runCommand({
       cmd: 'sh',
       args: [
@@ -1906,10 +1907,13 @@ export class VercelSandboxProvider implements WorkspaceProvider {
     const env: Record<string, string> = {
       AB_STORE: this.options.storeRef,
       AB_TOKEN: scopedToken,
+      ...(auth?.tickets
+        ? { AB_TICKET_URL: auth.tickets.url, AB_TICKET_TOKEN: auth.tickets.token }
+        : {}),
       [HARVEST_RUNNER_OPTIONS_ENV]: JSON.stringify(envelope),
     }
     for (const envName of this.options.config.environmentVariables)
-      if (envName !== 'AB_TOKEN')
+      if (!['AB_TOKEN', 'AB_TICKET_URL', 'AB_TICKET_TOKEN'].includes(envName))
         env[envName] = requireVercelEnvironmentValue(this.options.env, envName)
     const command = (await sandbox.runCommand({
       cmd: 'sh',