@defrex/autobuild 0.12.0 → 0.13.0

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

@@ -16,6 +16,8 @@ import type { TicketSource } from '../types'
 import { DEFAULT_TICKETS_DIR, FileTicketSource } from './file'
 import { LinearTicketSource } from './linear'
 import { HostedTicketSource } from './remote'
+import { ticketLifecycle } from './lifecycle'
+import { normalizeServiceURL } from '../../connection'
 
 function reason(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
@@ -32,26 +34,41 @@ export async function createTicketSource(
   plugins: PluginRegistry = createPluginRegistry(),
 ): Promise<TicketSource> {
   if (config.source === 'hosted') {
-    const rawUrl = env.AB_STORE?.trim() || configuredStore(targetRepo)
+    const buildUrl = env.AB_STORE?.trim() || configuredStore(targetRepo)
+    const rawUrl = config.url ?? buildUrl
     if (!rawUrl) {
       throw new Error(
-        'AB_STORE is not set — required when [tickets].source = "hosted"; set it to the hosted service HTTP(S) URL',
+        'Hosted tickets require [tickets] url when builds are local; alternatively set [store] url or AB_STORE to a service',
       )
     }
     let serviceUrl: URL
     try {
-      serviceUrl = new URL(rawUrl)
+      serviceUrl = new URL(normalizeServiceURL(rawUrl, 'tickets.url'))
     } 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"')
+      throw new Error(
+        'Hosted tickets require [tickets] url when [store] url / AB_STORE selects local builds',
+      )
     }
-    const token = projectToken(
-      rawUrl,
-      (await resolveRepoOrigin(targetRepo, spawnExec)) ?? targetRepo,
-      env,
+    const ticketSession = env.AB_TICKET_TOKEN !== undefined || env.AB_TICKET_URL !== undefined
+    if (
+      ticketSession &&
+      (!env.AB_TICKET_TOKEN ||
+        !env.AB_TICKET_URL ||
+        normalizeServiceURL(env.AB_TICKET_URL) !== normalizeServiceURL(rawUrl))
     )
+      throw new Error('Ticket session credential does not match the selected ticket service')
+    const token = ticketSession
+      ? env.AB_TICKET_TOKEN
+      : projectToken(
+          rawUrl,
+          (await resolveRepoOrigin(targetRepo, spawnExec)) ?? targetRepo,
+          config.url &&
+            (!buildUrl ||
+              !/^https?:/.test(buildUrl) ||
+              normalizeServiceURL(config.url) !== normalizeServiceURL(buildUrl))
+            ? { ...env, AB_TOKEN: undefined }
+            : env,
+        )
     if (!token) {
       throw new Error(
         'No project credential; run ab connect (or set AB_TOKEN) — a project credential is required when [tickets].source = "hosted"',
@@ -60,13 +77,32 @@ export async function createTicketSource(
     if (config.teamKey === undefined) {
       throw new Error('[tickets].source = "hosted" requires teamKey')
     }
-    return new HostedTicketSource({
+    const source = new HostedTicketSource({
       url: serviceUrl.toString(),
       token,
       teamKey: config.teamKey,
       ...(config.claimedState !== undefined ? { claimedState: config.claimedState } : {}),
       ...(config.createState !== undefined ? { createState: config.createState } : {}),
     })
+    // Delegated sessions may read policy, but never redefine project authority.
+    if (!ticketSession && !env.AB_HARVEST && !env.AB_PHASE) {
+      const lifecycle = ticketLifecycle(config)
+      await source.synchronizePolicy({
+        version: 1,
+        tickets: {
+          source: 'hosted',
+          teamKey: config.teamKey,
+          readyState: lifecycle.ready,
+          triageState: lifecycle.triage,
+          claimedState: lifecycle.doing,
+          doneState: lifecycle.done,
+          createState: lifecycle.create,
+          proposalState: lifecycle.proposal,
+          ...(config.readyLabels !== undefined ? { readyLabels: config.readyLabels } : {}),
+        },
+      })
+    }
+    return source
   }
 
   if (config.source === 'linear') {

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

@@ -1,3 +1,5 @@
+import { fileRequestedIds } from './requested-id'
+import { ticketRevision, checkTicketRevision } from './revision'
 /**
  * In-memory TicketSource for seam tests (SPEC §3.2, §13). Mirrors the policy
  * shape of the real adapters: initiation (listReady/get/claim/create),
@@ -12,11 +14,13 @@ import type {
   TicketListing,
   TicketSource,
   TicketUpdate,
+  TicketMutation,
 } from '../types'
 import { validateTicketUpdate } from './update'
 
 function cloneTicket(ticket: Ticket, doneState: string): Ticket {
   return {
+    revision: ticketRevision(ticket),
     ref: { ...ticket.ref },
     ...(ticket.creationKey !== undefined ? { creationKey: ticket.creationKey } : {}),
     title: ticket.title,
@@ -29,6 +33,7 @@ function cloneTicket(ticket: Ticket, doneState: string): Ticket {
 }
 
 export class FakeTicketSource implements TicketSource {
+  readonly requestedIds = fileRequestedIds
   readonly name = 'fake'
 
   /** Journal of every projection sent outward (§13), in call order. */
@@ -111,6 +116,7 @@ export class FakeTicketSource implements TicketSource {
     const ticket = this.tickets.get(id)
     if (!ticket || ticket.state === this.doneState || this.claimed.has(id)) return false
     this.claimed.add(id)
+    ticket.state = 'Doing'
     return true
   }
 
@@ -131,8 +137,10 @@ export class FakeTicketSource implements TicketSource {
       const adopted = this.idempotency.get(opts.idempotencyKey)
       if (adopted !== undefined) return cloneTicket(this.require(adopted, 'create'), this.doneState)
     }
-    const id = `fake-${this.nextId++}`
+    const id = opts.requestedId ?? `fake-${this.nextId++}`
+    if (this.tickets.has(id)) throw new Error(`requested ticket id already occupied: ${id}`)
     const ticket: Ticket = {
+      revision: 'pending',
       ref: { source: this.name, id, title: draft.title },
       ...(opts.idempotencyKey !== undefined ? { creationKey: opts.idempotencyKey } : {}),
       title: draft.title,
@@ -153,6 +161,27 @@ export class FakeTicketSource implements TicketSource {
     return cloneTicket(ticket, this.doneState)
   }
 
+  async mutateIfRevision(id: string, expected: string, mutation: TicketMutation): Promise<void> {
+    const ticket = this.require(id, 'revision-checked write')
+    checkTicketRevision(cloneTicket(ticket, this.doneState), expected)
+    if (mutation.kind === 'update') await this.update(id, mutation.patch)
+    else if (mutation.kind === 'transition') await this.transition(id, mutation.state)
+    else {
+      for (const blocker of mutation.ids) {
+        this.require(blocker, 'blocker')
+        if (mutation.operation === 'block' && blocker === id)
+          throw new Error(`ticket "${id}" cannot block itself`)
+      }
+      // No await between validation and in-memory batch application.
+      const blockers = new Set(ticket.blockedBy ?? [])
+      for (const blocker of mutation.ids) {
+        if (mutation.operation === 'block') blockers.add(blocker)
+        else blockers.delete(blocker)
+      }
+      ticket.blockedBy = [...blockers]
+    }
+  }
+
   async update(id: string, patch: TicketUpdate): Promise<void> {
     const validated = validateTicketUpdate(patch)
     const ticket = this.require(id, 'update')

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

@@ -0,0 +1,159 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TicketAssetStore } from '../types'
+import type { Frontmatter } from './file-codec'
+import { decodePortableAsset, encodePortableAsset, type PortableAsset } from './portable-assets'
+import { contentHash } from '../../store/types'
+import {
+  DEFAULT_TICKET_ASSET_LIMITS,
+  summarizeTicketAsset,
+  validateTicketAssetInput,
+  type TicketAsset,
+  type TicketAssetInput,
+} from '../../store/ticket-assets'
+
+type History = Record<string, Array<{ asset: PortableAsset | null; createdAt: string }>>
+// Native revisions occupy a separate range so legacy recorded pins remain unambiguous.
+const FIRST_REVISION = 1_000_000_000
+export class FileTicketAssets implements TicketAssetStore {
+  constructor(
+    private dir: string,
+    private load: (
+      id: string,
+    ) => Promise<{ front: Frontmatter; exists?: boolean; save(front: Frontmatter): Promise<void> }>,
+  ) {}
+  async ticketAssetLimits() {
+    return { ...DEFAULT_TICKET_ASSET_LIMITS }
+  }
+  private key(kind: string, name: string) {
+    return `${kind}/${name}`
+  }
+  private path(id: string) {
+    return join(this.dir, '.ab-assets', `${Buffer.from(id).toString('hex')}.json`)
+  }
+  private async history(id: string, front: Frontmatter): Promise<History> {
+    try {
+      return JSON.parse(await readFile(this.path(id), 'utf8')) as History
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    }
+    return Object.fromEntries(
+      (front.attachments ?? []).map((asset) => [
+        this.key(asset.kind, asset.name),
+        [{ asset, createdAt: '1970-01-01T00:00:00.000Z' }],
+      ]),
+    )
+  }
+  async hasTicketAssetHistory(_repo: string, id: string, kind: string, name: string) {
+    const { front } = await this.load(id)
+    return this.key(kind, name) in (await this.history(id, front))
+  }
+  private materialize(
+    repo: string,
+    id: string,
+    asset: PortableAsset,
+    revision: number,
+    createdAt: string,
+  ): TicketAsset {
+    const input = decodePortableAsset(asset)
+    const size = validateTicketAssetInput(input)
+    return {
+      meta: {
+        repo,
+        ticketId: id,
+        kind: asset.kind,
+        name: asset.name,
+        layout: asset.layout,
+        revision,
+        createdAt,
+        size,
+        entries: input.entries.map((e) =>
+          e.type === 'dir'
+            ? e
+            : {
+                type: 'file',
+                path: e.path,
+                size: e.content.byteLength,
+                blobRef: contentHash(e.content),
+              },
+        ),
+      },
+      entries: input.entries,
+    }
+  }
+  async getTicketAsset(repo: string, id: string, kind: string, name: string, revision?: number) {
+    const { front } = await this.load(id)
+    const history = (await this.history(id, front))[this.key(kind, name)]
+    if (!history) return null
+    const index = revision === undefined ? history.length - 1 : revision - FIRST_REVISION
+    const item = history[index]
+    return item?.asset
+      ? this.materialize(repo, id, item.asset, FIRST_REVISION + index, item.createdAt)
+      : null
+  }
+  async listTicketAssets(repo: string, id: string) {
+    const { front } = await this.load(id)
+    const history = await this.history(id, front)
+    return Object.values(history).flatMap((items) => {
+      const item = items.at(-1)!
+      return item.asset
+        ? [
+            summarizeTicketAsset(
+              this.materialize(
+                repo,
+                id,
+                item.asset,
+                FIRST_REVISION + items.length - 1,
+                item.createdAt,
+              ).meta,
+            ),
+          ]
+        : []
+    })
+  }
+  private async persist(
+    id: string,
+    history: History,
+    loaded: Awaited<ReturnType<FileTicketAssets['load']>>,
+  ) {
+    const path = this.path(id)
+    await mkdir(join(this.dir, '.ab-assets'), { recursive: true })
+    const temp = `${path}.${crypto.randomUUID()}.tmp`
+    await writeFile(temp, JSON.stringify(history))
+    await rename(temp, path)
+    // The journal is authoritative after interruption; repair the portable projection on retry.
+    loaded.front.attachments = Object.values(history).flatMap((items) =>
+      items.at(-1)!.asset ? [items.at(-1)!.asset!] : [],
+    )
+    await loaded.save(loaded.front)
+  }
+  async putTicketAsset(repo: string, id: string, input: TicketAssetInput) {
+    validateTicketAssetInput(input)
+    const loaded = await this.load(id)
+    if (loaded.exists === false)
+      throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+    const history = await this.history(id, loaded.front)
+    const key = this.key(input.kind, input.name)
+    const items = history[key] ?? []
+    history[key] = items
+    const asset = encodePortableAsset(input)
+    const createdAt = new Date().toISOString()
+    items.push({ asset, createdAt })
+    await this.persist(id, history, loaded)
+    return this.materialize(repo, id, asset, FIRST_REVISION + items.length - 1, createdAt).meta
+  }
+  async removeTicketAsset(repo: string, id: string, kind: string, name: string) {
+    const current = await this.getTicketAsset(repo, id, kind, name)
+    const loaded = await this.load(id)
+    if (loaded.exists === false)
+      throw new Error(`file ticket source: asset on unknown ticket "${id}"`)
+    const history = await this.history(id, loaded.front)
+    const key = this.key(kind, name)
+    if (history[key]?.at(-1)?.asset === null) return null
+    const items = history[key] ?? []
+    history[key] = items
+    items.push({ asset: null, createdAt: new Date().toISOString() })
+    await this.persist(id, history, loaded)
+    return current?.meta ?? null
+  }
+}

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

@@ -0,0 +1,90 @@
+import { portableAssetSchema } from './portable-assets'
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
+import { z } from 'zod'
+
+const frontmatterSchema = z.strictObject({
+  comments: z
+    .array(
+      z.strictObject({ body: z.string(), createdAt: z.string(), author: z.string().optional() }),
+    )
+    .optional(),
+  attachments: z
+    .array(portableAssetSchema)
+    .superRefine((assets, ctx) => {
+      const names = new Set<string>()
+      for (const asset of assets) {
+        const key = `${asset.kind}/${asset.name}`
+        if (names.has(key))
+          ctx.addIssue({ code: 'custom', message: `duplicate attachment: ${key}` })
+        names.add(key)
+      }
+    })
+    .optional(),
+  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(),
+})
+export 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'
+}
+
+export 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) }
+}
+
+export 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
+  }
+  if (front.comments !== undefined) data.comments = front.comments
+  if (front.attachments !== undefined) data.attachments = front.attachments
+  // smol-toml stringify ends with a newline; the closing fence follows it.
+  return `${OPEN_FENCE}${stringifyToml(data)}+++\n${body}`
+}