@defrex/autobuild 0.8.0

package/packages/core/src/kernel/origin.ts

@@ -0,0 +1,69 @@
+/**
+ * Dependency-free repository-origin helpers.
+ *
+ * Repository identity in the BuildStore, dispatcher, `ab builds`,
+ * `ab repository status`, and the web app is the repository's normalized
+ * origin URL, not a checkout path — a path-based identity makes two hosts
+ * disagree about which repository they operate. These helpers live in the
+ * kernel layer so ports code (the GitHub REST forge) and the hosted store
+ * service can share them without importing the CLI layer.
+ */
+
+/**
+ * Location-independent form of a git remote URL, for comparing a recorded
+ * repository origin with the origin of the current checkout. Trims; maps
+ * scp-like `git@host:path` (and bare `host:path`) remotes and explicit
+ * `ssh://`/`git://` URLs to their `https://` spelling; drops credentials;
+ * lowercases the host; strips a trailing `.git` and trailing slashes.
+ * Anything unparseable — notably a local-path remote — is returned trimmed
+ * as-is, so such remotes only ever compare equal to themselves.
+ */
+export function normalizeGitRemoteUrl(raw: string): string {
+  const trimmed = raw.trim()
+  // scp-like syntax: `[user@]host:relative/path`. A colon followed by an
+  // absolute path (or a Windows drive letter) is not scp-like — leave it for
+  // URL parsing, which fails and falls through to the trimmed passthrough.
+  const scp =
+    trimmed.includes('://') || /^[A-Za-z]:/.test(trimmed)
+      ? null
+      : /^(?:[^@/]+@)?([^/:]+):([^/].*)$/.exec(trimmed)
+  const candidate = scp !== null ? `https://${scp[1]}/${scp[2]}` : trimmed
+  try {
+    const url = new URL(candidate)
+    // Only network URLs carry a host; a Windows drive or relative path parses
+    // as a scheme-only URL and passes through untouched.
+    if (url.hostname === '') return trimmed
+    const path = url.pathname.replace(/\.git\/?$/i, '').replace(/\/+$/, '')
+    // ssh and git URLs name the same repository as their https spelling, so
+    // an ssh-origin host checkout and the sandbox guest's pinned https origin
+    // must normalize to one form (the scp-like branch already does).
+    const protocol =
+      url.protocol === 'ssh:' || url.protocol === 'git:' || url.protocol === 'git+ssh:'
+        ? 'https:'
+        : url.protocol
+    return `${protocol}//${url.host.toLowerCase()}${path}`
+  } catch {
+    return trimmed
+  }
+}
+
+/**
+ * Whether `ref` is a valid exact Git branch name, by git-check-ref-format(1)'s
+ * rules: no leading `-`, no `..`, none of `~^:?*[\` anywhere, no ASCII
+ * control characters or space, no `@{`, not bare `@`, no trailing `.lock`
+ * or `.`, and no empty slash-delimited components. The REST forge uses this
+ * to reject a branch name before interpolating it into a ref endpoint,
+ * replacing the host `git check-ref-format` subprocess.
+ */
+export function isValidGitBranchName(branch: string): boolean {
+  if (branch === '' || branch.startsWith('-')) return false
+  if (branch.endsWith('.lock') || branch.endsWith('.')) return false
+  if (branch.includes('..') || branch.includes('@{') || branch === '@') return false
+  for (const char of branch) {
+    const code = char.codePointAt(0)!
+    if (code < 0x20 || code === 0x7f) return false
+    if ('~^:?*[\\ '.includes(char)) return false
+  }
+  // No empty slash-delimited component (`a//b`, leading/trailing slash).
+  return branch.split('/').every((component) => component !== '')
+}

package/packages/core/src/kernel/phases.ts

@@ -0,0 +1,196 @@
+/**
+ * The phase table (SPEC §4): a phase's name derives its skill, its events,
+ * and its artifact kind — mechanically. This table also encodes each phase's
+ * terminal discipline (D5), required deposits, context inputs (§8.3), and
+ * plumbing (D7), so the CLI, the context builder, and the engine all validate
+ * against the same data.
+ */
+import { isVerifyPhase, type CorePhase, type Phase } from '../ontology'
+import type { EventType } from '../events/payloads'
+import { installedSkillName } from '../skills'
+
+export type PhaseKind = 'producer' | 'review' | 'agent-verify'
+export type TerminalCommand = 'done' | 'verdict' | 'escalate'
+
+/**
+ * Kernel-side plumbing triggered by the phase's terminal (D7, §8.6):
+ * agents only ever commit locally; push/PR happen at the boundary.
+ */
+export type PhasePlumbing = 'push-branch' | 'open-pr' | 'push-merge-commit'
+
+/**
+ * What `ab context` materializes for the phase (§8.3). Scoping is
+ * deliberate: what a phase *can't* see is part of its design.
+ */
+export interface ContextInputs {
+  ticket?: boolean
+  spec?: boolean
+  plan?: 'latest' | 'approved'
+  /**
+   * `current`: this round's feedback only (producers).
+   * `all-rounds`: every prior round's findings, for `persists` marking
+   * (reviewers — §15.4).
+   */
+  findings?: 'current' | 'all-rounds'
+  /** Feedback cited by this exact phase occurrence's started event. Agent
+   * verify uses this for answered guidance without widening findings input. */
+  currentFeedback?: boolean
+  /** Producer's own prior-round artifacts (plan revs / implement notes). */
+  priorOwnArtifacts?: boolean
+  commitRange?: boolean
+  implementNotes?: boolean
+  verifyReports?: boolean
+  /** Reconcile: the fresh `{baseSha}` from this attempt's `reconcile.started` (§15.7). */
+  conflict?: boolean
+  prTemplate?: boolean
+  /** Agent-verify: the step's config from autobuild.toml (§16.1). */
+  stepConfig?: boolean
+  /**
+   * Answered guidance escalations addressed to THIS phase (§15.6-B, §11).
+   * Finalize and reconcile have no producer round for the engine to feed the
+   * answer into, so `ab context` is their delivery channel — the engine's
+   * loop routing (loopOfPhase → 'other') relies on this input existing.
+   */
+  answeredGuidance?: boolean
+}
+
+export interface PhaseSpec {
+  name: CorePhase | 'verify'
+  kind: PhaseKind
+  /** Installed, namespaced skill name. For verify steps the actual skill
+   * comes from step config (§16.1). */
+  skill: string
+  startedEvent: EventType
+  terminal: 'done' | 'verdict'
+  terminalEvent: EventType
+  /**
+   * Artifact kind the terminal requires deposited (D5). For agent-verify
+   * steps the report kind is per-step (`verify-report:<step>`) and required
+   * only on `fail` — enforced by the CLI, not listed here.
+   */
+  requiredArtifact?: string
+  /** Verdict vocabulary the CLI enforces (§8.2). */
+  verdictVocabulary?: readonly string[]
+  /** `implement` only: no `done` on a dirty worktree (D5). */
+  requiresCleanWorktree?: boolean
+  plumbing?: PhasePlumbing
+  inputs: ContextInputs
+}
+
+export const PHASE_SPECS: Record<CorePhase | 'verify', PhaseSpec> = {
+  plan: {
+    name: 'plan',
+    kind: 'producer',
+    skill: installedSkillName('plan'),
+    startedEvent: 'plan.started',
+    terminal: 'done',
+    terminalEvent: 'plan.completed',
+    requiredArtifact: 'plan',
+    inputs: {
+      ticket: true,
+      spec: true,
+      priorOwnArtifacts: true,
+      findings: 'current',
+    },
+  },
+  'plan-review': {
+    name: 'plan-review',
+    kind: 'review',
+    skill: installedSkillName('plan-review'),
+    startedEvent: 'plan-review.started',
+    terminal: 'verdict',
+    terminalEvent: 'plan-review.verdict',
+    requiredArtifact: 'plan-review',
+    verdictVocabulary: ['approve', 'revise', 'escalate'],
+    inputs: { spec: true, plan: 'latest', findings: 'all-rounds' },
+  },
+  implement: {
+    name: 'implement',
+    kind: 'producer',
+    skill: installedSkillName('implement'),
+    startedEvent: 'implement.started',
+    terminal: 'done',
+    terminalEvent: 'implement.completed',
+    requiredArtifact: 'implement-notes',
+    requiresCleanWorktree: true,
+    plumbing: 'push-branch',
+    inputs: {
+      spec: true,
+      plan: 'approved',
+      findings: 'current',
+      verifyReports: true,
+      priorOwnArtifacts: true,
+    },
+  },
+  'code-review': {
+    name: 'code-review',
+    kind: 'review',
+    skill: installedSkillName('code-review'),
+    startedEvent: 'code-review.started',
+    terminal: 'verdict',
+    terminalEvent: 'code-review.verdict',
+    requiredArtifact: 'code-review',
+    verdictVocabulary: ['approve', 'revise', 'escalate'],
+    inputs: {
+      spec: true,
+      plan: 'approved',
+      commitRange: true,
+      findings: 'all-rounds',
+      implementNotes: true,
+    },
+  },
+  verify: {
+    name: 'verify',
+    kind: 'agent-verify',
+    skill: installedSkillName('verify'),
+    startedEvent: 'verify.started',
+    terminal: 'verdict',
+    terminalEvent: 'verify.completed',
+    verdictVocabulary: ['pass', 'fail', 'skip'],
+    inputs: { spec: true, stepConfig: true, commitRange: true, currentFeedback: true },
+  },
+  finalize: {
+    name: 'finalize',
+    kind: 'producer',
+    skill: installedSkillName('finalize'),
+    startedEvent: 'finalize.started',
+    terminal: 'done',
+    terminalEvent: 'finalize.completed',
+    requiredArtifact: 'pr-description',
+    plumbing: 'open-pr',
+    inputs: {
+      spec: true,
+      plan: 'approved',
+      verifyReports: true,
+      prTemplate: true,
+      answeredGuidance: true,
+    },
+  },
+  reconcile: {
+    name: 'reconcile',
+    kind: 'producer',
+    skill: installedSkillName('reconcile'),
+    startedEvent: 'reconcile.started',
+    terminal: 'done',
+    terminalEvent: 'reconcile.completed',
+    requiredArtifact: 'reconcile-notes',
+    plumbing: 'push-merge-commit',
+    inputs: {
+      spec: true,
+      plan: 'approved',
+      implementNotes: true,
+      conflict: true,
+      answeredGuidance: true,
+    },
+  },
+}
+
+export function phaseSpecFor(phase: Phase): PhaseSpec {
+  return isVerifyPhase(phase) ? PHASE_SPECS.verify : PHASE_SPECS[phase]
+}
+
+/** Every phase ends with exactly one terminal command (D5); `escalate` is
+ * always available in addition to the phase's own terminal. */
+export function allowedTerminals(phase: Phase): TerminalCommand[] {
+  return [phaseSpecFor(phase).terminal, 'escalate']
+}

package/packages/core/src/kernel/plan-verify-selection.ts

@@ -0,0 +1,105 @@
+import { parse as parseToml } from 'smol-toml'
+import { z } from 'zod'
+import type { Config } from '../config/schema'
+
+const planMetadataSchema = z.strictObject({
+  verifySteps: z.array(
+    z
+      .string()
+      .min(1, 'verify step names must be nonempty')
+      .refine((step) => step.trim() === step, 'verify step names must not be blank or padded'),
+  ),
+})
+
+/**
+ * Read an opening TOML `+++` front-matter block. A document without an
+ * opening fence has no metadata; once an opening fence is attempted, malformed
+ * fences are errors rather than silently becoming Markdown body text.
+ */
+function parsePlanMetadata(plan: string): z.infer<typeof planMetadataSchema> | undefined {
+  if (!plan.startsWith('+++')) return undefined
+
+  const firstBreak = plan.indexOf('\n')
+  const opening = (firstBreak === -1 ? plan : plan.slice(0, firstBreak)).replace(/\r$/, '')
+  if (opening !== '+++') {
+    throw new Error(
+      'plan front matter has a malformed opening fence — expected a line containing only "+++"',
+    )
+  }
+  if (firstBreak === -1) {
+    throw new Error('plan front matter is missing its closing "+++" fence')
+  }
+
+  const metadataStart = firstBreak + 1
+  let cursor = metadataStart
+  let metadataEnd: number | undefined
+  while (cursor <= plan.length) {
+    const nextBreak = plan.indexOf('\n', cursor)
+    const lineEnd = nextBreak === -1 ? plan.length : nextBreak
+    const line = plan.slice(cursor, lineEnd).replace(/\r$/, '')
+    if (line === '+++') {
+      metadataEnd = cursor
+      break
+    }
+    if (nextBreak === -1) break
+    cursor = nextBreak + 1
+  }
+  if (metadataEnd === undefined) {
+    throw new Error('plan front matter is missing its closing "+++" fence')
+  }
+
+  let parsed: unknown
+  try {
+    parsed = parseToml(plan.slice(metadataStart, metadataEnd))
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`plan front matter is not valid TOML: ${message}`)
+  }
+
+  const result = planMetadataSchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `  ${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('\n')
+    throw new Error(`plan front matter is invalid:\n${issues}`)
+  }
+  return result.data
+}
+
+/**
+ * Resolve a plan's requested verification set against repository config.
+ *
+ * Missing front matter preserves the historical default (all configured
+ * steps). An explicit list is a set, while returned order always comes from
+ * `[verify].steps`. `always = true` is the mandatory/non-deselectable marker.
+ */
+export function resolvePlanVerifySteps(plan: string, config: Config): string[] {
+  const metadata = parsePlanMetadata(plan)
+  if (metadata === undefined) return [...config.verify.steps]
+
+  const selected = new Set<string>()
+  for (const step of metadata.verifySteps) {
+    if (selected.has(step)) {
+      throw new Error(`plan verifySteps contains duplicate step ${JSON.stringify(step)}`)
+    }
+    selected.add(step)
+
+    if (!config.verify.steps.includes(step) || !Object.hasOwn(config.verify.stepConfigs, step)) {
+      throw new Error(
+        `plan verifySteps names unknown step ${JSON.stringify(step)} — ` +
+          `no [verify.${step}] table is configured`,
+      )
+    }
+  }
+
+  for (const step of config.verify.steps) {
+    if (config.verify.stepConfigs[step]?.always === true && !selected.has(step)) {
+      throw new Error(
+        `plan verifySteps omits mandatory step ${JSON.stringify(step)} — ` +
+          `[verify.${step}].always = true steps cannot be deselected`,
+      )
+    }
+  }
+
+  return config.verify.steps.filter((step) => selected.has(step))
+}

package/packages/core/src/kernel/pr-attachments.ts

@@ -0,0 +1,82 @@
+import type { AbEvent } from '../events/catalog'
+import type { PrImageHostTarget } from '../ontology'
+
+export type PrAttachmentDesignationEvent = Extract<AbEvent, { type: 'pr-attachment.designated' }>
+export type PrAttachmentHostedEvent = Extract<AbEvent, { type: 'pr-attachment.hosted' }>
+
+/** The host consent frozen into the build at claim time. */
+export function frozenPrImageHost(events: readonly AbEvent[]): PrImageHostTarget | undefined {
+  let created: Extract<AbEvent, { type: 'build.created' }> | undefined
+  for (const event of events) {
+    if (event.type === 'build.created' && (created === undefined || event.seq < created.seq)) {
+      created = event
+    }
+  }
+  return created?.payload.pr?.imageHost
+}
+
+/**
+ * Current PR attachments are explicit designations after the latest spec
+ * restart, with the newest exact revision replacing earlier designations of
+ * the same artifact kind. Distinct kinds remain distinct attachments.
+ */
+export function currentPrAttachments(events: readonly AbEvent[]): PrAttachmentDesignationEvent[] {
+  let restartSeq = 0
+  for (const event of events) {
+    if (event.type === 'spec.revised') restartSeq = Math.max(restartSeq, event.seq)
+  }
+
+  const byKind = new Map<string, PrAttachmentDesignationEvent>()
+  for (const event of events) {
+    if (event.type !== 'pr-attachment.designated' || event.seq <= restartSeq) {
+      continue
+    }
+    const previous = byKind.get(event.payload.artifact.kind)
+    if (previous === undefined || event.seq > previous.seq) {
+      byKind.set(event.payload.artifact.kind, event)
+    }
+  }
+  return [...byKind.values()].sort((left, right) => left.seq - right.seq)
+}
+
+/**
+ * Correlate one durable hosted copy to each current designation. Unknown,
+ * backwards, and stale correlations are ignored rather than throwing so the
+ * selector remains total over any structurally valid event ordering.
+ */
+export function hostedPrAttachments(
+  events: readonly AbEvent[],
+  designations = currentPrAttachments(events),
+): Map<number, PrAttachmentHostedEvent> {
+  const designationBySeq = new Map(designations.map((event) => [event.seq, event]))
+  const hosted = new Map<number, PrAttachmentHostedEvent>()
+  for (const event of events) {
+    if (event.type !== 'pr-attachment.hosted') continue
+    const designation = designationBySeq.get(event.payload.designationSeq)
+    if (designation === undefined || event.seq <= designation.seq) continue
+    const previous = hosted.get(designation.seq)
+    if (previous === undefined || event.seq > previous.seq) {
+      hosted.set(designation.seq, event)
+    }
+  }
+  return hosted
+}
+
+/** Every durable hosted copy that has not yet received a later reclaim fact. */
+export function pendingPrAttachmentReclaims(events: readonly AbEvent[]): PrAttachmentHostedEvent[] {
+  const hosted = events
+    .filter((event): event is PrAttachmentHostedEvent => event.type === 'pr-attachment.hosted')
+    .sort((left, right) => left.seq - right.seq)
+  const hostedSeqs = new Set(hosted.map((event) => event.seq))
+  const reclaimed = new Set<number>()
+  for (const event of events) {
+    if (
+      event.type === 'pr-attachment.reclaimed' &&
+      hostedSeqs.has(event.payload.hostedSeq) &&
+      event.seq > event.payload.hostedSeq
+    ) {
+      reclaimed.add(event.payload.hostedSeq)
+    }
+  }
+  return hosted.filter((event) => !reclaimed.has(event.seq))
+}