@defrex/autobuild 0.8.0

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

@@ -0,0 +1,161 @@
+import type { Config } from '../../config/schema'
+import { readyCriteria } from '../../processes/dispatcher'
+import type { Ticket, TicketDraft, TicketSource, TicketUpdate } from '../types'
+
+/** Expected ticket-operation failures which operator transports may expose verbatim. */
+export class TicketOperationError extends Error {
+  constructor(
+    readonly code: 'not-found' | 'refusal',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'TicketOperationError'
+  }
+}
+
+export function missingTicket(source: TicketSource, id: string): TicketOperationError {
+  return new TicketOperationError(
+    'not-found',
+    `no ticket "${id}" in the configured ${source.name} ticket source — ticket ids are source-local`,
+  )
+}
+
+export async function requireTicket(source: TicketSource, id: string): Promise<Ticket> {
+  const ticket = await source.get(id)
+  if (ticket === null) throw missingTicket(source, id)
+  return ticket
+}
+
+export async function requirePostMutationTicket(
+  source: TicketSource,
+  id: string,
+  operation: string,
+): Promise<Ticket> {
+  const ticket = await source.get(id)
+  if (ticket === null) {
+    throw new TicketOperationError(
+      'refusal',
+      `ticket "${id}" disappeared from the configured ${source.name} ticket source after ${operation}`,
+    )
+  }
+  return ticket
+}
+
+export function ticketListCriteria(
+  config: Config,
+  filters: { state?: string; labels?: string[] },
+): { state?: string; labels?: string[] } {
+  return filters.state === undefined && filters.labels === undefined
+    ? readyCriteria(config)
+    : filters
+}
+
+async function knownBlockers(
+  source: TicketSource,
+  blockerIds: string[],
+  prefix: string,
+  suffix = '',
+): Promise<string[]> {
+  const ids = [...new Set(blockerIds)]
+  if (ids.length === 0) return ids
+  const states = await source.dependencyStates(ids)
+  const unknown = states.filter((state) => !state.exists).map((state) => state.id)
+  if (unknown.length > 0) {
+    throw new TicketOperationError(
+      'not-found',
+      `${prefix}no ticket ${unknown.map((id) => `"${id}"`).join(', ')} in the configured ${source.name} ticket source — blocker ids are source-local${suffix}`,
+    )
+  }
+  return ids
+}
+
+export async function createTicket(
+  source: TicketSource,
+  input: TicketDraft & { state?: string },
+  options: { blockerErrorPrefix?: string; blockerErrorSuffix?: string } = {},
+): Promise<Ticket> {
+  const blockedBy = await knownBlockers(
+    source,
+    input.blockedBy ?? [],
+    options.blockerErrorPrefix ?? '',
+    options.blockerErrorSuffix ?? '',
+  )
+  const draft: TicketDraft = {
+    title: input.title,
+    body: input.body,
+    ...(input.labels !== undefined ? { labels: [...input.labels] } : {}),
+    ...(blockedBy.length > 0 ? { blockedBy } : {}),
+  }
+  try {
+    return input.state === undefined
+      ? await source.create(draft)
+      : await source.create(draft, { state: input.state })
+  } catch (error) {
+    throw new TicketOperationError(
+      'refusal',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+}
+
+export async function updateTicket(
+  source: TicketSource,
+  id: string,
+  patch: TicketUpdate,
+  readAfter = true,
+): Promise<Ticket | null> {
+  try {
+    await source.update(id, patch)
+  } catch (error) {
+    throw new TicketOperationError(
+      'refusal',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+  return readAfter ? requirePostMutationTicket(source, id, 'the update') : null
+}
+
+export async function moveTicket(source: TicketSource, id: string, state: string): Promise<Ticket> {
+  await requireTicket(source, id)
+  try {
+    await source.transition(id, state)
+  } catch (error) {
+    throw new TicketOperationError(
+      'refusal',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+  return requirePostMutationTicket(source, id, 'the move')
+}
+
+export async function changeBlockers(
+  source: TicketSource,
+  id: string,
+  blockerIds: string[],
+  operation: 'block' | 'unblock',
+): Promise<Ticket> {
+  await requireTicket(source, id)
+  const ids = await knownBlockers(source, blockerIds, '')
+  if (operation === 'block' && ids.includes(id)) {
+    throw new TicketOperationError(
+      'refusal',
+      `ticket "${id}" in the configured ${source.name} ticket source cannot block itself`,
+    )
+  }
+  try {
+    for (const blockerId of ids) {
+      if (operation === 'block') await source.addBlocker(id, blockerId)
+      else await source.removeBlocker(id, blockerId)
+    }
+  } catch (error) {
+    throw new TicketOperationError(
+      'refusal',
+      error instanceof Error ? error.message : String(error),
+    )
+  }
+  return requirePostMutationTicket(
+    source,
+    id,
+    operation === 'block' ? 'adding blockers' : 'removing blockers',
+  )
+}

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

@@ -0,0 +1,13 @@
+export { HostedTicketSource } from './remote'
+export type { HostedTicketFetch, HostedTicketSourceOptions } from './remote'
+export { createTicketServer } from './remote-server'
+export type { TicketServerOptions } from './remote-server'
+export {
+  HOSTED_TICKET_OPERATIONS,
+  hostedTicketContextSchema,
+  hostedTicketRequestSchemas,
+} from './remote-protocol'
+export type { HostedTicketContext, HostedTicketOperation } from './remote-protocol'
+// The hosted service composes the already live-proven Linear adapter; provider
+// credentials remain server-side.
+export { LinearTicketSource } from './linear'

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

@@ -0,0 +1,80 @@
+import { z } from 'zod'
+import { ticketRefSchema } from '../../ontology'
+
+/** Repository-owned policy sent with every hosted ticket operation. */
+export const hostedTicketContextSchema = z.strictObject({
+  teamKey: z.string().min(1),
+  claimedState: z.string().min(1).optional(),
+  createState: z.string().min(1).optional(),
+})
+export type HostedTicketContext = z.infer<typeof hostedTicketContextSchema>
+
+export const ticketWireSchema = z.strictObject({
+  ref: ticketRefSchema,
+  creationKey: z.string().optional(),
+  title: z.string(),
+  body: z.string(),
+  state: z.string().optional(),
+  labels: z.array(z.string()),
+  blockedBy: z.array(z.string()).optional(),
+})
+export const ticketListingWireSchema = z.strictObject({
+  tickets: z.array(ticketWireSchema),
+  diagnostics: z.array(z.string()),
+})
+export const dependencyStateWireSchema = z.strictObject({
+  id: z.string(),
+  exists: z.boolean(),
+  resolved: z.boolean(),
+  blockedBy: z.array(z.string()),
+})
+export const dependencyStatesWireSchema = z.array(dependencyStateWireSchema)
+export const successWireSchema = z.strictObject({ ok: z.literal(true) })
+export const claimWireSchema = z.strictObject({ claimed: z.boolean() })
+
+const criteriaSchema = z.strictObject({
+  labels: z.array(z.string()).optional(),
+  state: z.string().optional(),
+})
+const idSchema = z.strictObject({ id: z.string().min(1) })
+const draftSchema = z.strictObject({
+  title: z.string(),
+  body: z.string(),
+  labels: z.array(z.string()).optional(),
+  blockedBy: z.array(z.string()).optional(),
+})
+const createOptionsSchema = z.strictObject({
+  state: z.string().optional(),
+  idempotencyKey: z.string().optional(),
+})
+const updateSchema = z
+  .strictObject({
+    title: z.string().optional(),
+    body: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+  })
+  .refine((value) => Object.keys(value).length > 0, 'update must name at least one field')
+
+function envelope<T extends z.ZodType>(input: T) {
+  return z.strictObject({ context: hostedTicketContextSchema, input })
+}
+
+export const hostedTicketRequestSchemas = {
+  'list-ready': envelope(criteriaSchema),
+  get: envelope(idSchema),
+  claim: envelope(idSchema),
+  comment: envelope(z.strictObject({ id: z.string().min(1), body: z.string() })),
+  transition: envelope(z.strictObject({ id: z.string().min(1), state: z.string().min(1) })),
+  create: envelope(z.strictObject({ draft: draftSchema, options: createOptionsSchema.optional() })),
+  update: envelope(z.strictObject({ id: z.string().min(1), patch: updateSchema })),
+  'add-blocker': envelope(z.strictObject({ id: z.string().min(1), blockerId: z.string().min(1) })),
+  'remove-blocker': envelope(
+    z.strictObject({ id: z.string().min(1), blockerId: z.string().min(1) }),
+  ),
+  'dependency-states': envelope(z.strictObject({ ids: z.array(z.string().min(1)) })),
+} as const
+
+export type HostedTicketOperation = keyof typeof hostedTicketRequestSchemas
+export const HOSTED_TICKET_OPERATIONS = Object.keys(
+  hostedTicketRequestSchemas,
+) as HostedTicketOperation[]

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

@@ -0,0 +1,185 @@
+import type { TicketSource } from '../types'
+import { systemClock, type Clock } from '../../store/types'
+import type { ErrorBody, ErrorKind } from '../../store/remote/protocol'
+import { tokenResource, verifyToken } from '../../store/remote/token'
+import {
+  AUTOBUILD_VERSION,
+  AUTOBUILD_VERSION_HEADER,
+  REMOTE_STORE_PROTOCOL_VERSION,
+  REMOTE_STORE_PROTOCOL_VERSION_HEADER,
+} from '../../store/remote/version'
+import {
+  hostedTicketRequestSchemas,
+  type HostedTicketContext,
+  type HostedTicketOperation,
+} from './remote-protocol'
+
+export interface TicketServerOptions {
+  secret: string
+  sourceFor(context: HostedTicketContext): TicketSource | Promise<TicketSource>
+  clock?: Clock
+  /** Observes unexpected source failures without changing their wire response. */
+  onInternalError?: (error: unknown, request: Request) => unknown | Promise<unknown>
+}
+
+class TicketRequestError extends Error {
+  constructor(
+    readonly status: number,
+    readonly kind: ErrorKind,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+function json(status: number, body: unknown): Response {
+  return Response.json(body, { status })
+}
+
+function failure(status: number, kind: ErrorKind, error: string): Response {
+  return json(status, { error, kind } satisfies ErrorBody)
+}
+
+/** HTTP face of the TicketSource port. Authentication deliberately runs before
+ * JSON parsing and source construction, so denied callers cannot probe either. */
+export function createTicketServer(options: TicketServerOptions): {
+  fetch(req: Request): Promise<Response>
+} {
+  const clock = options.clock ?? systemClock
+
+  function identify(req: Request): void {
+    const autobuild = req.headers.get(AUTOBUILD_VERSION_HEADER)
+    const protocol = req.headers.get(REMOTE_STORE_PROTOCOL_VERSION_HEADER)
+    if (autobuild !== AUTOBUILD_VERSION || protocol !== REMOTE_STORE_PROTOCOL_VERSION) {
+      throw new TicketRequestError(
+        409,
+        'conflict',
+        `remote store version mismatch: client Autobuild ${autobuild ?? '(missing)'} protocol ${protocol ?? '(missing)'}; server Autobuild ${AUTOBUILD_VERSION} protocol ${REMOTE_STORE_PROTOCOL_VERSION}`,
+      )
+    }
+  }
+
+  function authorize(req: Request): void {
+    const match = /^Bearer\s+(.+)$/i.exec(req.headers.get('authorization') ?? '')
+    if (!match) throw new TicketRequestError(401, 'auth', 'missing bearer token')
+    const scope = verifyToken(options.secret, match[1]!, clock())
+    if (scope === null) throw new TicketRequestError(401, 'auth', 'invalid or expired token')
+    const resource = tokenResource(scope)
+    if (resource.kind !== 'deployment') {
+      throw new TicketRequestError(
+        403,
+        'auth',
+        `token scoped to ${resource.kind} "${resource.id}" may not access ticket operations`,
+      )
+    }
+  }
+
+  async function body(req: Request): Promise<unknown> {
+    try {
+      return await req.json()
+    } catch {
+      throw new TicketRequestError(400, 'validation', 'request body is not valid JSON')
+    }
+  }
+
+  async function route(req: Request, operation: HostedTicketOperation): Promise<Response> {
+    const raw = await body(req)
+    const parsed = hostedTicketRequestSchemas[operation].safeParse(raw)
+    if (!parsed.success) {
+      throw new TicketRequestError(
+        400,
+        'validation',
+        `invalid request body: ${parsed.error.message}`,
+      )
+    }
+    const context = parsed.data.context
+    const source = await options.sourceFor(context)
+
+    // Parse again through the operation-specific schema to preserve precise
+    // inference in each branch while keeping the shared pre-source validation.
+    switch (operation) {
+      case 'list-ready': {
+        const request = hostedTicketRequestSchemas['list-ready'].parse(raw)
+        return json(200, await source.listReady(request.input))
+      }
+      case 'get': {
+        const request = hostedTicketRequestSchemas.get.parse(raw)
+        return json(200, await source.get(request.input.id))
+      }
+      case 'claim': {
+        const request = hostedTicketRequestSchemas.claim.parse(raw)
+        return json(200, { claimed: await source.claim(request.input.id) })
+      }
+      case 'comment': {
+        const request = hostedTicketRequestSchemas.comment.parse(raw)
+        await source.comment(request.input.id, request.input.body)
+        return json(200, { ok: true })
+      }
+      case 'transition': {
+        const request = hostedTicketRequestSchemas.transition.parse(raw)
+        await source.transition(request.input.id, request.input.state)
+        return json(200, { ok: true })
+      }
+      case 'create': {
+        const request = hostedTicketRequestSchemas.create.parse(raw)
+        return json(201, await source.create(request.input.draft, request.input.options))
+      }
+      case 'update': {
+        const request = hostedTicketRequestSchemas.update.parse(raw)
+        await source.update(request.input.id, request.input.patch)
+        return json(200, { ok: true })
+      }
+      case 'add-blocker': {
+        const request = hostedTicketRequestSchemas['add-blocker'].parse(raw)
+        await source.addBlocker(request.input.id, request.input.blockerId)
+        return json(200, { ok: true })
+      }
+      case 'remove-blocker': {
+        const request = hostedTicketRequestSchemas['remove-blocker'].parse(raw)
+        await source.removeBlocker(request.input.id, request.input.blockerId)
+        return json(200, { ok: true })
+      }
+      case 'dependency-states': {
+        const request = hostedTicketRequestSchemas['dependency-states'].parse(raw)
+        return json(200, await source.dependencyStates(request.input.ids))
+      }
+    }
+  }
+
+  return {
+    async fetch(req: Request): Promise<Response> {
+      try {
+        const url = new URL(req.url)
+        if (req.method !== 'POST' || !url.pathname.startsWith('/tickets/')) {
+          return failure(404, 'not-found', `no route: ${req.method} ${url.pathname}`)
+        }
+        identify(req)
+        authorize(req)
+        const operation = url.pathname.slice('/tickets/'.length) as HostedTicketOperation
+        if (!Object.hasOwn(hostedTicketRequestSchemas, operation)) {
+          return failure(404, 'not-found', `no route: ${req.method} ${url.pathname}`)
+        }
+        return await route(req, operation)
+      } catch (error) {
+        if (error instanceof TicketRequestError) {
+          return failure(error.status, error.kind, error.message)
+        }
+        // Only the message crosses the trust boundary; causes and stacks never do.
+        const message = error instanceof Error ? error.message : 'ticket backend failed'
+        const notFound = /unknown (?:ticket|issue)|not found/i.test(message)
+        // These are intentional domain feedback from TicketSource implementations.
+        // Their historical standalone mapping remains unchanged.
+        const expectedDomainFailure =
+          message.startsWith('invalid ticket update') || message.includes('cannot block itself')
+        if (!notFound && !expectedDomainFailure && options.onInternalError !== undefined) {
+          try {
+            await options.onInternalError(error, req)
+          } catch {
+            // Diagnostics must never replace the protocol response.
+          }
+        }
+        return failure(notFound ? 404 : 500, notFound ? 'not-found' : 'internal', message)
+      }
+    },
+  }
+}

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

@@ -0,0 +1,130 @@
+import type {
+  DependencyState,
+  Ticket,
+  TicketCreateOptions,
+  TicketDraft,
+  TicketListing,
+  TicketSource,
+  TicketUpdate,
+} from '../types'
+import { AuthError } from '../../store/remote/client'
+import { errorBodySchema } from '../../store/remote/protocol'
+import {
+  claimWireSchema,
+  dependencyStatesWireSchema,
+  type HostedTicketContext,
+  successWireSchema,
+  ticketListingWireSchema,
+  ticketWireSchema,
+} from './remote-protocol'
+import {
+  AUTOBUILD_VERSION,
+  AUTOBUILD_VERSION_HEADER,
+  REMOTE_STORE_PROTOCOL_VERSION,
+  REMOTE_STORE_PROTOCOL_VERSION_HEADER,
+} from '../../store/remote/version'
+
+export type HostedTicketFetch = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>
+
+export interface HostedTicketSourceOptions extends HostedTicketContext {
+  url: string
+  token: string
+  fetchFn?: HostedTicketFetch
+}
+
+/** Full TicketSource client for a hosted Autobuild service. */
+export class HostedTicketSource implements TicketSource {
+  readonly name = 'hosted'
+  private readonly base: string
+  private readonly token: string
+  private readonly fetchFn: HostedTicketFetch
+  private readonly context: HostedTicketContext
+
+  constructor(options: HostedTicketSourceOptions) {
+    this.base = options.url.replace(/\/+$/, '')
+    this.token = options.token
+    this.fetchFn = options.fetchFn ?? fetch
+    this.context = {
+      teamKey: options.teamKey,
+      ...(options.claimedState !== undefined ? { claimedState: options.claimedState } : {}),
+      ...(options.createState !== undefined ? { createState: options.createState } : {}),
+    }
+  }
+
+  private project(ticket: Ticket): Ticket {
+    return { ...ticket, ref: { ...ticket.ref, source: this.name } }
+  }
+
+  private async request<T>(
+    operation: string,
+    input: unknown,
+    schema: { parse(value: unknown): T },
+  ): Promise<T> {
+    const response = await this.fetchFn(`${this.base}/tickets/${operation}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${this.token}`,
+        [AUTOBUILD_VERSION_HEADER]: AUTOBUILD_VERSION,
+        [REMOTE_STORE_PROTOCOL_VERSION_HEADER]: REMOTE_STORE_PROTOCOL_VERSION,
+      },
+      body: JSON.stringify({ context: this.context, input }),
+    })
+    if (!response.ok) {
+      let message = `ticket service responded ${response.status}`
+      try {
+        message = errorBodySchema.parse(await response.json()).error
+      } catch {
+        // Keep the status-only safe fallback for non-protocol responses.
+      }
+      if (response.status === 401 || response.status === 403) throw new AuthError(message)
+      throw new Error(message)
+    }
+    return schema.parse(await response.json())
+  }
+
+  async listReady(criteria: { labels?: string[]; state?: string }): Promise<TicketListing> {
+    const listing = await this.request('list-ready', criteria, ticketListingWireSchema)
+    return { ...listing, tickets: listing.tickets.map((ticket) => this.project(ticket)) }
+  }
+
+  async get(id: string): Promise<Ticket | null> {
+    const ticket = await this.request('get', { id }, ticketWireSchema.nullable())
+    return ticket === null ? null : this.project(ticket)
+  }
+
+  async claim(id: string): Promise<boolean> {
+    return (await this.request('claim', { id }, claimWireSchema)).claimed
+  }
+
+  async comment(id: string, body: string): Promise<void> {
+    await this.request('comment', { id, body }, successWireSchema)
+  }
+
+  async transition(id: string, state: string): Promise<void> {
+    await this.request('transition', { id, state }, successWireSchema)
+  }
+
+  async create(draft: TicketDraft, options: TicketCreateOptions = {}): Promise<Ticket> {
+    return this.project(await this.request('create', { draft, options }, ticketWireSchema))
+  }
+
+  async update(id: string, patch: TicketUpdate): Promise<void> {
+    await this.request('update', { id, patch }, successWireSchema)
+  }
+
+  async addBlocker(id: string, blockerId: string): Promise<void> {
+    await this.request('add-blocker', { id, blockerId }, successWireSchema)
+  }
+
+  async removeBlocker(id: string, blockerId: string): Promise<void> {
+    await this.request('remove-blocker', { id, blockerId }, successWireSchema)
+  }
+
+  dependencyStates(ids: string[]): Promise<DependencyState[]> {
+    return this.request('dependency-states', { ids }, dependencyStatesWireSchema)
+  }
+}

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

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+import { expandIssues } from '../../zod-issues'
+import type { TicketUpdate } from '../types'
+
+const ticketUpdateSchema = z
+  .strictObject({
+    title: z
+      .string()
+      .refine((value) => value.trim().length > 0, 'title must not be blank')
+      .optional(),
+    body: z
+      .string()
+      .refine((value) => value.trim().length > 0, 'body must not be blank')
+      .optional(),
+    labels: z.array(z.string()).optional(),
+  })
+  .refine(
+    (patch) => patch.title !== undefined || patch.body !== undefined || patch.labels !== undefined,
+    'update must name at least one of title, body, or labels',
+  )
+
+/** Render ticket-update issues while retaining nested union branch detail. */
+export function renderTicketUpdateIssues(issues: readonly z.core.$ZodIssue[]): string {
+  return expandIssues(issues)
+    .map((issue) => {
+      const path = issue.path.join('.')
+      return path === '' ? issue.message : `${path}: ${issue.message}`
+    })
+    .join('; ')
+}
+
+/**
+ * Validate the common partial-update contract before an adapter performs any
+ * write. Keeping this at the port boundary (rather than only in the CLI)
+ * gives direct callers and every provider identical required-field and strict
+ * key semantics.
+ */
+export function validateTicketUpdate(patch: TicketUpdate): TicketUpdate {
+  const result = ticketUpdateSchema.safeParse(patch)
+  if (!result.success) {
+    throw new Error(`invalid ticket update — ${renderTicketUpdateIssues(result.error.issues)}`)
+  }
+
+  // Reconstruct the patch so arrays cannot be mutated behind an adapter's
+  // back and explicit `undefined` never masquerades as a named field.
+  return {
+    ...(result.data.title !== undefined ? { title: result.data.title } : {}),
+    ...(result.data.body !== undefined ? { body: result.data.body } : {}),
+    ...(result.data.labels !== undefined ? { labels: [...result.data.labels] } : {}),
+  }
+}