@defrex/autobuild 0.11.0 → 0.13.0

package/packages/core/src/cli/ticket-editor.ts

@@ -0,0 +1,82 @@
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { TicketSource, TicketUpdate } from '../ports/types'
+import { parseTicketFile, serializeTicketFile } from '../ports/tickets/file-codec'
+import { TicketRevisionUnsupported } from '../ports/tickets/revision'
+import { requireTicket, updateTicket } from '../ports/tickets/operations'
+
+export type TicketEditorRunner = (command: string, path: string) => Promise<number>
+
+/** The configured editor is a shell command; only our generated path is quoted. */
+export const runTicketEditor: TicketEditorRunner = async (command, path) => {
+  const quoted = `'${path.replaceAll("'", "'\\''")}'`
+  return Bun.spawn(['sh', '-c', `${command} ${quoted}`], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  }).exited
+}
+
+export async function editTicket(
+  source: TicketSource,
+  id: string,
+  env: Record<string, string | undefined>,
+  stdout: (line: string) => void,
+  runner: TicketEditorRunner = runTicketEditor,
+): Promise<void> {
+  if (!source.mutateIfRevision) throw new TicketRevisionUnsupported(source.name)
+  const command = env.VISUAL?.trim() || env.EDITOR?.trim()
+  if (!command) throw new Error('set VISUAL or EDITOR to edit a ticket')
+  const ticket = await requireTicket(source, id)
+  const front = {
+    id,
+    title: ticket.title,
+    labels: [...ticket.labels],
+    blockedBy: [...(ticket.blockedBy ?? [])],
+    ...(ticket.creationKey !== undefined ? { idempotencyKey: ticket.creationKey } : {}),
+  }
+  // Reference comments remain part of the frontmatter, outside the editable keys.
+  const reference = `# Read-only reference\n# state = ${JSON.stringify(ticket.state ?? null)}\n# revision = ${JSON.stringify(ticket.revision)}\n`
+  const serialized = serializeTicketFile(front, ticket.body)
+  const original = serialized.replace('+++\n', `+++\n${reference}`)
+  const directory = await mkdtemp(join(tmpdir(), 'ab-ticket-edit-'))
+  const path = join(directory, 'ticket.md')
+  await writeFile(path, original, { mode: 0o600 })
+  try {
+    const code = await runner(command, path)
+    if (code !== 0) throw new Error(`editor exited with status ${code}`)
+    const edited = await readFile(path, 'utf8')
+    if (edited !== original) {
+      const parsed = parseTicketFile(path, edited)
+      const close = edited.indexOf('\n+++\n', 4)
+      const comments = edited
+        .slice(4, close)
+        .split('\n')
+        .filter((line) => line.trimStart().startsWith('#'))
+        .join('\n')
+      if (comments !== reference.trimEnd())
+        throw new Error('read-only reference comments cannot change')
+      if (
+        parsed.front.id !== id ||
+        parsed.front.idempotencyKey !== front.idempotencyKey ||
+        JSON.stringify(parsed.front.blockedBy ?? []) !== JSON.stringify(front.blockedBy)
+      )
+        throw new Error('id, idempotencyKey and blockedBy are read-only')
+      const patch: TicketUpdate = {}
+      if (parsed.front.title !== ticket.title) patch.title = parsed.front.title
+      if (parsed.body !== ticket.body) patch.body = parsed.body
+      if (JSON.stringify(parsed.front.labels) !== JSON.stringify(ticket.labels))
+        patch.labels = parsed.front.labels
+      if (Object.keys(patch).length > 0)
+        await updateTicket(source, id, patch, false, ticket.revision)
+    }
+    await rm(directory, { recursive: true })
+    stdout(`ticket edit complete: ${source.name}:${id}`)
+  } catch (error) {
+    throw new Error(
+      `${error instanceof Error ? error.message : String(error)}; edited text kept at ${path}`,
+      { cause: error },
+    )
+  }
+}

package/packages/core/src/cli/ticket.ts

@@ -1,3 +1,6 @@
+import { exportTickets, importTickets } from '../ports/tickets/migration'
+import { composeTicketAssets } from '../store/ticket-assets'
+import { editTicket, type TicketEditorRunner } from './ticket-editor'
 /**
  * Source-agnostic pre-build ticket operations (SPEC §8.8). These commands run
  * outside build sessions and resolve the repository's configured TicketSource,
@@ -19,7 +22,13 @@ import {
   ticketListCriteria,
   updateTicket,
 } from '../ports/tickets/operations'
-import type { Ticket, TicketSource, TicketStateInfo, TicketUpdate } from '../ports/types'
+import type {
+  TicketAssetStore,
+  Ticket,
+  TicketSource,
+  TicketStateInfo,
+  TicketUpdate,
+} from '../ports/types'
 import { reduceBuild } from '../kernel/reducer'
 import type { BuildStore } from '../store/types'
 import { spawnExec, type Exec } from '../ports/workspace/git-worktree'
@@ -45,6 +54,8 @@ export type TicketSourceFactory = (
 
 export interface TicketCommandOpts {
   targetRepo: string
+  expectedRevision?: string
+  editorRunner?: TicketEditorRunner
   /** Process environment — store selection and adapter secrets. */
   env: Record<string, string | undefined>
   /** Git seam supplied by the CLI; omitted direct callers use targetRepo. */
@@ -152,10 +163,13 @@ export interface TicketStateCreateOpts extends TicketCommandOpts {
 }
 
 type TicketCommandName =
+  | 'export'
+  | 'import'
   | 'states'
   | 'state create'
   | 'create'
   | 'update'
+  | 'edit'
   | 'block'
   | 'unblock'
   | 'list'
@@ -170,12 +184,11 @@ export interface ResolvedTicketCommand {
   source: TicketSource
 }
 
-/** Resolve linked-worktree identity, config, selected local state, and adapter
- * exactly once for one ticket command or another sessionless caller. */
-export async function openTicketSource(
-  opts: TicketCommandOpts & { storeRef?: string },
+/** Resolve the main checkout and config without requiring provider credentials. */
+async function resolveTicketConfig(
+  opts: TicketCommandOpts,
   label: string,
-): Promise<ResolvedTicketCommand> {
+): Promise<{ targetRepo: string; config: Config }> {
   const targetRepo =
     opts.exec === undefined
       ? resolve(opts.targetRepo)
@@ -194,18 +207,40 @@ export async function openTicketSource(
     throw error
   }
 
+  return { targetRepo, config }
+}
+
+/** Resolve configuration and construct the configured ticket adapter. */
+export async function openTicketSource(
+  opts: TicketCommandOpts & { storeRef?: string },
+  label: string,
+): Promise<ResolvedTicketCommand> {
+  return createTicketCommandSource(opts, await resolveTicketConfig(opts, label))
+}
+
+async function createTicketCommandSource(
+  opts: TicketCommandOpts,
+  { targetRepo, config }: { targetRepo: string; config: Config },
+): Promise<ResolvedTicketCommand> {
   // Ticket commands use the same trusted plugin catalog as dispatch. Loading
   // and registration finish before any adapter is constructed or called.
   const plugins = await loadPlugins(config.plugins, targetRepo)
   const repoState = resolveRepoStatePaths({
     repo: targetRepo,
+    configStore: config.store?.url,
     ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
     ...(opts.env.AB_STORE !== undefined ? { envStore: opts.env.AB_STORE } : {}),
   })
   const factory = opts.sourceFactory ?? createTicketSource
   return {
     config,
-    source: await factory(config.tickets, opts.env, targetRepo, repoState.localStateRoot, plugins),
+    source: await factory(
+      config.tickets,
+      config.tickets.source === 'hosted' ? { ...opts.env, AB_STORE: repoState.storeRef } : opts.env,
+      targetRepo,
+      repoState.localStateRoot,
+      plugins,
+    ),
   }
 }
 
@@ -306,18 +341,18 @@ export async function abTicketUpdate(opts: TicketUpdateOpts): Promise<void> {
     ...(opts.labels !== undefined ? { labels: [...opts.labels] } : {}),
   }
   if (opts.json === true) {
-    const updated = await updateTicket(source, opts.id, patch)
+    const updated = await updateTicket(source, opts.id, patch, true, opts.expectedRevision)
     if (updated !== null) emitTicketJson(opts, updated)
     return
   }
-  await updateTicket(source, opts.id, patch, false)
+  await updateTicket(source, opts.id, patch, false, opts.expectedRevision)
   opts.stdout(`ticket updated: ${source.name}:${opts.id}`)
 }
 
 export async function abTicketBlock(opts: TicketBlockerOpts): Promise<void> {
   const { source } = await resolveTicketCommand(opts, 'block')
   const blockerIds = [...new Set(opts.blockerIds)]
-  const updated = await changeBlockers(source, opts.id, blockerIds, 'block')
+  const updated = await changeBlockers(source, opts.id, blockerIds, 'block', opts.expectedRevision)
   if (opts.json === true) {
     emitTicketJson(opts, updated)
     return
@@ -330,7 +365,13 @@ export async function abTicketBlock(opts: TicketBlockerOpts): Promise<void> {
 export async function abTicketUnblock(opts: TicketBlockerOpts): Promise<void> {
   const { source } = await resolveTicketCommand(opts, 'unblock')
   const blockerIds = [...new Set(opts.blockerIds)]
-  const updated = await changeBlockers(source, opts.id, blockerIds, 'unblock')
+  const updated = await changeBlockers(
+    source,
+    opts.id,
+    blockerIds,
+    'unblock',
+    opts.expectedRevision,
+  )
   if (opts.json === true) {
     emitTicketJson(opts, updated)
     return
@@ -365,7 +406,7 @@ export async function abTicketShow(opts: TicketShowOpts): Promise<void> {
   const { source } = await resolveTicketCommand(opts, 'show')
   const ticket = await requireTicket(source, opts.id)
   // An asset-listing failure fails the command rather than hiding the assets.
-  const assets = await withTicketStore(opts, ({ store, repo }) =>
+  const assets = await withTicketAssets(opts, source, ({ store, repo }) =>
     store.listTicketAssets(repo, opts.id),
   )
   if (opts.json === true) {
@@ -392,6 +433,12 @@ export async function abTicketShow(opts: TicketShowOpts): Promise<void> {
   // Keep the adapter-provided body untouched. It may itself be multiline and
   // may intentionally end (or not end) with a newline.
   opts.stdout(ticket.body)
+  for (const comment of ticket.comments ?? []) {
+    opts.stdout(
+      `Comment ${comment.createdAt}${comment.author !== undefined ? ` — ${comment.author}` : ''}`,
+    )
+    opts.stdout(comment.body)
+  }
 }
 
 function withTicketStore<T>(
@@ -410,6 +457,19 @@ function withTicketStore<T>(
   )
 }
 
+function withTicketAssets<T>(
+  opts: TicketCommandOpts,
+  source: TicketSource,
+  use: (context: { store: TicketAssetStore; buildStore: BuildStore; repo: string }) => Promise<T>,
+): Promise<T> {
+  if (source.name === 'hosted' && !source.assets) {
+    throw new Error('hosted ticket source has no asset capability')
+  }
+  return withTicketStore(opts, ({ store, repo }) =>
+    use({ store: composeTicketAssets(source, store), buildStore: store, repo }),
+  )
+}
+
 /** Slugs of this repo's non-terminal builds for the ticket. A build freezes its
  * ticket assets at the claim (SPEC §6.3), so a change to them does not reach
  * it. The notice is advisory: a failed lookup yields none and never blocks. */
@@ -448,18 +508,26 @@ export async function abTicketAttach(opts: TicketAttachOpts): Promise<void> {
   await requireTicket(source, opts.id)
   const walk = await walkAssetPath(opts.path)
   const name = opts.name ?? walk.basename
-  const stored = await withTicketStore(opts, async ({ store, repo }) => {
+  const stored = await withTicketAssets(opts, source, async ({ store, buildStore, repo }) => {
     const limits = await store.ticketAssetLimits(repo)
     const input = await buildAssetInput(walk, { kind: opts.kind, name }, limits)
     const live = await store.listTicketAssets(repo, opts.id)
     const replacing = live.some((asset) => asset.kind === opts.kind && asset.name === name)
     const meta = await store.putTicketAsset(repo, opts.id, input)
-    return { meta, replacing, active: await activeBuildsFor(store, repo, opts.id) }
+    return { meta, replacing, active: await activeBuildsFor(buildStore, repo, opts.id) }
   })
   const { meta } = stored
   warnActiveBuilds(opts, stored.active)
   try {
-    await source.comment(opts.id, ticketAssetNote(stored.replacing ? 'replaced' : 'attached', meta))
+    await source.comment(
+      opts.id,
+      ticketAssetNote(
+        stored.replacing ? 'replaced' : 'attached',
+        meta,
+        'ab',
+        source.name === 'hosted',
+      ),
+    )
   } catch (error) {
     throw new Error(
       `ticket asset ${meta.kind}/${meta.name} was stored as revision ${meta.revision}, but the note on ` +
@@ -480,9 +548,17 @@ export async function abTicketAttach(opts: TicketAttachOpts): Promise<void> {
 /** `ab ticket asset get <id> <kind> <name> <dest>` — exact bytes at the
  * latest or a named revision. */
 export async function abTicketAssetGet(opts: TicketAssetGetOpts): Promise<void> {
-  const asset = await withTicketStore(opts, ({ store, repo }) =>
-    store.getTicketAsset(repo, opts.id, opts.kind, opts.name, opts.rev),
-  )
+  const resolved = await resolveTicketConfig(opts, 'ab ticket asset get')
+  const readAsset = ({ store, repo }: { store: TicketAssetStore; repo: string }) =>
+    store.getTicketAsset(repo, opts.id, opts.kind, opts.name, opts.rev)
+  const asset =
+    resolved.config.tickets.source === 'linear'
+      ? await withTicketStore(opts, readAsset)
+      : await withTicketAssets(
+          opts,
+          (await createTicketCommandSource(opts, resolved)).source,
+          readAsset,
+        )
   if (asset === null) {
     const revision = opts.rev === undefined ? '' : ` revision ${opts.rev}`
     throw new Error(
@@ -504,16 +580,23 @@ export async function abTicketAssetGet(opts: TicketAssetGetOpts): Promise<void>
  * (earlier revisions stay retrievable) and note the removal on the ticket. */
 export async function abTicketAssetRm(opts: TicketAssetRmOpts): Promise<void> {
   const { source } = await resolveTicketCommand(opts, 'asset rm')
-  const { removed, active } = await withTicketStore(opts, async ({ store, repo }) => ({
-    removed: await store.removeTicketAsset(repo, opts.id, opts.kind, opts.name),
-    active: await activeBuildsFor(store, repo, opts.id),
-  }))
+  const { removed, active } = await withTicketAssets(
+    opts,
+    source,
+    async ({ store, buildStore, repo }) => ({
+      removed: await store.removeTicketAsset(repo, opts.id, opts.kind, opts.name),
+      active: await activeBuildsFor(buildStore, repo, opts.id),
+    }),
+  )
   if (removed === null) {
     throw new Error(`ticket ${opts.id} has no current asset ${opts.kind}/${opts.name} to remove`)
   }
   warnActiveBuilds(opts, active)
   try {
-    await source.comment(opts.id, ticketAssetNote('removed', removed))
+    await source.comment(
+      opts.id,
+      ticketAssetNote('removed', removed, 'ab', source.name === 'hosted'),
+    )
   } catch (error) {
     throw new Error(
       `ticket asset ${opts.kind}/${opts.name} was removed, but the note on ${source.name}:${opts.id} ` +
@@ -530,7 +613,7 @@ export async function abTicketAssetRm(opts: TicketAssetRmOpts): Promise<void> {
 /** `ab ticket move <id> <state>` — adapter-owned state validation and move. */
 export async function abTicketMove(opts: TicketMoveOpts): Promise<void> {
   const { source } = await resolveTicketCommand(opts, 'move')
-  const moved = await moveTicket(source, opts.id, opts.state)
+  const moved = await moveTicket(source, opts.id, opts.state, opts.expectedRevision)
   if (opts.json === true) {
     opts.stdout(JSON.stringify(moved, null, 2))
     return
@@ -559,10 +642,10 @@ export function stateRoles(
   const named: Array<[TicketStateRole, string]> = [
     ['create', tickets.createState ?? 'triage'],
     ['ready', tickets.readyState],
-    ['claimed', 'doing'],
+    ['claimed', tickets.source === 'hosted' ? (tickets.claimedState ?? 'doing') : 'doing'],
     ['triage', triage],
     ['proposal', tickets.proposalState ?? triage],
-    ['done', 'done'],
+    ['done', tickets.source === 'hosted' ? (tickets.doneState ?? 'done') : 'done'],
   ]
   const roles = new Map<string, TicketStateRole[]>(names.map((name) => [name, []]))
   for (const [role, target] of named) {
@@ -613,7 +696,7 @@ export async function abTicketStates(opts: TicketStatesOpts): Promise<void> {
   })
 }
 
-/** `ab ticket state create <name> [--about <text>]` — idempotent. */
+/** `ab ticket state create <name> [--about <text>]` — duplicate policy belongs to the source. */
 export async function abTicketStateCreate(opts: TicketStateCreateOpts): Promise<void> {
   const { config, source } = await resolveTicketCommand(opts, 'state create')
   if (typeof source.addState !== 'function') {
@@ -643,9 +726,11 @@ export async function abTicketStateCreate(opts: TicketStateCreateOpts): Promise<
 const CREATE_USAGE =
   'usage: ab ticket create <title> --body <file> [--state <state>] [--labels a,b] [--blocked-by id,id] [--json] (§8.8)'
 const UPDATE_USAGE =
-  'usage: ab ticket update <id> [--title <title>] [--body <file>] [--labels a,b] [--json] (§8.8)'
-const BLOCK_USAGE = 'usage: ab ticket block <id> <blocker-id[,blocker-id...]> [--json] (§8.8)'
-const UNBLOCK_USAGE = 'usage: ab ticket unblock <id> <blocker-id[,blocker-id...]> [--json] (§8.8)'
+  'usage: ab ticket update <id> [--title <title>] [--body <file>] [--labels a,b] [--expected-revision <opaque>] [--json] (§8.8)'
+const BLOCK_USAGE =
+  'usage: ab ticket block <id> <blocker-id[,blocker-id...]> [--expected-revision <opaque>] [--json] (§8.8)'
+const UNBLOCK_USAGE =
+  'usage: ab ticket unblock <id> <blocker-id[,blocker-id...]> [--expected-revision <opaque>] [--json] (§8.8)'
 const LIST_USAGE = 'usage: ab ticket list [--state <state>] [--labels a,b] [--json] (§8.8)'
 const SHOW_USAGE = 'usage: ab ticket show <id> [--store <ref>] [--json] (§8.8)'
 const ATTACH_USAGE =
@@ -654,11 +739,15 @@ const ASSET_GET_USAGE =
   'usage: ab ticket asset get <id> <kind> <name> <dest> [--rev <n>] [--store <ref>] [--json] (§8.8)'
 const ASSET_RM_USAGE =
   'usage: ab ticket asset rm <id> <kind> <name> [--store <ref>] [--json] (§8.8)'
-const MOVE_USAGE = 'usage: ab ticket move <id> <state> [--json] (§8.8)'
+const MOVE_USAGE =
+  'usage: ab ticket move <id> <state> [--expected-revision <opaque>] [--json] (§8.8)'
 const STATES_USAGE = 'usage: ab ticket states [--json] (§8.8)'
 const STATE_CREATE_USAGE = 'usage: ab ticket state create <name> [--about <text>] [--json] (§8.8)'
 export const TICKET_USAGE = [
+  'usage: ab ticket export <dir> [--store <ref>]',
+  'usage: ab ticket import <dir> [--store <ref>]',
   CREATE_USAGE,
+  'usage: ab ticket edit <id> (§8.8)',
   UPDATE_USAGE,
   BLOCK_USAGE,
   UNBLOCK_USAGE,
@@ -689,6 +778,25 @@ interface TicketCliOpts extends TicketCommandOpts {
 export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<void> {
   const [command, ...args] = argv
   switch (command) {
+    case 'export':
+    case 'import': {
+      const parsed = parseArgs(args, { store: 'value' }, TICKET_USAGE)
+      const [dir, ...extra] = parsed.positionals
+      if (!dir?.trim() || extra.length) throw new Error(TICKET_USAGE)
+      const migrationOpts = { ...opts, storeRef: stringFlag(parsed, 'store') ?? opts.storeRef }
+      const { source } = await resolveTicketCommand(migrationOpts, command)
+      await withTicketAssets(migrationOpts, source, ({ store, repo }) =>
+        (command === 'export' ? exportTickets : importTickets)({
+          source,
+          assets: store,
+          repo,
+          dir,
+          print: opts.stdout,
+        }),
+      )
+      return
+    }
+
     case 'create': {
       const parsed = parseArgs(
         args,
@@ -716,10 +824,23 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
       return
     }
 
+    case 'edit': {
+      if (args.length !== 1 || !args[0]?.trim()) throw new Error('usage: ab ticket edit <id>')
+      const { source } = await resolveTicketCommand(opts, 'edit')
+      await editTicket(source, args[0], opts.env, opts.stdout, opts.editorRunner)
+      return
+    }
+
     case 'update': {
       const parsed = parseArgs(
         args,
-        { title: 'value', body: 'value', labels: 'value', json: 'boolean' },
+        {
+          title: 'value',
+          body: 'value',
+          labels: 'value',
+          'expected-revision': 'value',
+          json: 'boolean',
+        },
         TICKET_USAGE,
       )
       const [id, ...extra] = parsed.positionals
@@ -736,6 +857,7 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
       await abTicketUpdate({
         ...opts,
         id,
+        expectedRevision: stringFlag(parsed, 'expected-revision'),
         ...(title !== undefined ? { title } : {}),
         ...(bodyFile !== undefined ? { bodyFile } : {}),
         ...(labels !== undefined ? { labels: commaList(labels) } : {}),
@@ -746,7 +868,11 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
 
     case 'block':
     case 'unblock': {
-      const parsed = parseArgs(args, { json: 'boolean' }, TICKET_USAGE)
+      const parsed = parseArgs(
+        args,
+        { json: 'boolean', 'expected-revision': 'value' },
+        TICKET_USAGE,
+      )
       const [id, blockerList, ...extra] = parsed.positionals
       if (
         id === undefined ||
@@ -759,7 +885,13 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
       }
       const blockerIds = commaList(blockerList)
       if (blockerIds.length === 0) throw new Error(TICKET_USAGE)
-      const blockerOpts = { ...opts, id, blockerIds, json: parsed.flags.has('json') }
+      const blockerOpts = {
+        ...opts,
+        id,
+        blockerIds,
+        expectedRevision: stringFlag(parsed, 'expected-revision'),
+        json: parsed.flags.has('json'),
+      }
       if (command === 'block') await abTicketBlock(blockerOpts)
       else await abTicketUnblock(blockerOpts)
       return
@@ -903,7 +1035,11 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
     }
 
     case 'move': {
-      const parsed = parseArgs(args, { json: 'boolean' }, TICKET_USAGE)
+      const parsed = parseArgs(
+        args,
+        { json: 'boolean', 'expected-revision': 'value' },
+        TICKET_USAGE,
+      )
       const [id, state, ...extra] = parsed.positionals
       if (
         id === undefined ||
@@ -918,6 +1054,7 @@ export async function abTicket(argv: string[], opts: TicketCliOpts): Promise<voi
         ...opts,
         id,
         state,
+        expectedRevision: stringFlag(parsed, 'expected-revision'),
         json: parsed.flags.has('json'),
       })
       return

package/packages/core/src/cli/upgrade-compatibility.ts

@@ -0,0 +1,80 @@
+import { spawnExec } from '../ports/workspace/git-worktree'
+import { readDistributionIdentity } from './installation'
+import { isRemoteStoreRef, resolveRepoState } from './repo-state'
+import {
+  classifyClient,
+  compatibilityAdvice,
+  stableVersion,
+  supportedClientRangeSchema,
+} from '../store/remote/compatibility'
+
+export type CompatibilityFetch = (url: string, init: RequestInit) => Promise<Response>
+
+/** Read-only, advisory, and deliberately credential-free. Never expose a store URL. */
+export async function checkUpgradeCompatibility(options: {
+  targetRepo: string
+  version?: string
+  distRoot?: string
+  env?: Record<string, string | undefined>
+  stderr: (line: string) => void
+  fetch?: CompatibilityFetch
+  timeoutMs?: number
+}): Promise<void> {
+  const paths = await resolveRepoState({
+    targetRepo: options.targetRepo,
+    exec: spawnExec,
+    envStore: (options.env ?? process.env).AB_STORE,
+  })
+  if (!isRemoteStoreRef(paths.storeRef)) return
+  const unknown = () =>
+    options.stderr(
+      'warning: hosted service compatibility could not be verified; the upgraded project may fail to connect',
+    )
+  try {
+    const targetVersion =
+      options.version ?? (await readDistributionIdentity(options.distRoot)).version
+    const url = new URL(paths.storeRef)
+    url.username = ''
+    url.password = ''
+    url.search = ''
+    url.hash = ''
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/health`
+    const controller = new AbortController()
+    let timeout: ReturnType<typeof setTimeout> | undefined
+    const expired = new Promise<never>((_, reject) => {
+      timeout = setTimeout(() => {
+        controller.abort()
+        reject(new Error('timeout'))
+      }, options.timeoutMs ?? 3000)
+    })
+    const response = await Promise.race([
+      (async () => {
+        const response = await (options.fetch ?? fetch)(url.toString(), {
+          signal: controller.signal,
+          redirect: 'error',
+        })
+        if (response.status !== 200) throw new Error('health failed')
+        return (await response.json()) as Record<string, unknown>
+      })(),
+      expired,
+    ]).finally(() => clearTimeout(timeout))
+    if (!response || !stableVersion(response.autobuildVersion)) return unknown()
+    const serviceVersion = response.autobuildVersion as string
+    if (!Object.hasOwn(response, 'supportedClientRange')) {
+      if (targetVersion !== serviceVersion)
+        options.stderr(
+          `warning: service Autobuild ${serviceVersion} requires an exact client version; target ${targetVersion} differs. Upgrade the service to the compatibility-window release first to publish a supported client range; the upgraded project may fail to connect`,
+        )
+      return
+    }
+    const range = supportedClientRangeSchema.safeParse(response.supportedClientRange)
+    if (!range.success || classifyClient(targetVersion, range.data) === 'invalid') return unknown()
+    const advice = compatibilityAdvice(targetVersion, serviceVersion, range.data)
+    if (advice)
+      options.stderr(
+        `warning: target Autobuild ${targetVersion}: ${advice}; the upgraded project may fail to connect`,
+      )
+  } catch {
+    unknown()
+  }
+}