@defrex/autobuild 0.8.0

package/packages/core/src/cli/store-opening.contract.ts

@@ -0,0 +1,289 @@
+/**
+ * Shared behavioral contract for finite sessionless commands that own a
+ * BuildStore. Register this against distinct command shells so selection,
+ * credentials, production composition, and cleanup cannot drift per command.
+ */
+import { describe, expect, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Exec } from '../ports/workspace/git-worktree'
+import { MemoryBuildStore } from '../store/memory'
+import { startStoreServer } from '../store/remote/server'
+import { mintToken } from '../store/remote/token'
+import type { BuildStore } from '../store/types'
+import type { StoreOpener } from './store-opening'
+
+const MAIN_REPO = '/main/repo'
+const LINKED_REPO = '/linked/worktree'
+
+const mainRepoExec: Exec = async (cmd) =>
+  cmd[1] === 'remote'
+    ? // No origin remote: identity falls back to the resolved checkout path.
+      { stdout: '', stderr: "error: No such remote 'origin'\n", exitCode: 2 }
+    : {
+        stdout: `${MAIN_REPO}/.git\n${MAIN_REPO}/.git\n${MAIN_REPO}\n`,
+        stderr: '',
+        exitCode: 0,
+      }
+
+const noGit: Exec = async () => ({
+  stdout: '',
+  stderr: 'not a git repository',
+  exitCode: 128,
+})
+
+export interface StoreOpeningCommandOpts {
+  targetRepo: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  stdout: (line: string) => void
+  storeRef?: string
+  openStore?: StoreOpener
+}
+
+export interface StoreOpeningCommandAdapter {
+  run: (opts: StoreOpeningCommandOpts) => Promise<void>
+  /** Extract a command-specific marker proving it used canonical main-repo
+   * identity (for example a filtered build slug or a projected repo path). */
+  canonicalMarker: (stdout: string[]) => string | undefined
+  expectedCanonicalMarker: string
+}
+
+function trackedStore(
+  store: MemoryBuildStore,
+  opts: { failOperations?: boolean; onClose: () => void },
+): BuildStore {
+  return new Proxy(store, {
+    get(target, prop) {
+      if (prop === 'close') {
+        return async () => opts.onClose()
+      }
+      const value = Reflect.get(target, prop, target) as unknown
+      if (typeof value !== 'function') return value
+      if (opts.failOperations === true) {
+        return async () => {
+          throw new Error('store operation failed')
+        }
+      }
+      return value.bind(target) as unknown
+    },
+  }) as unknown as BuildStore
+}
+
+async function capture(
+  adapter: StoreOpeningCommandAdapter,
+  opts: Omit<StoreOpeningCommandOpts, 'stdout'>,
+): Promise<string[]> {
+  const stdout: string[] = []
+  await adapter.run({ ...opts, stdout: (line) => stdout.push(line) })
+  return stdout
+}
+
+export function describeStoreOpeningContract(
+  name: string,
+  adapter: StoreOpeningCommandAdapter,
+): void {
+  describe(`sessionless store-opening contract: ${name}`, () => {
+    test('shares reference precedence, normalization, URL preservation, and opaque token forwarding', async () => {
+      const store = new MemoryBuildStore()
+      const opened: Array<{ ref: string; token?: string }> = []
+      const openStore: StoreOpener = (ref, token) => {
+        opened.push({ ref, ...(token !== undefined ? { token } : {}) })
+        return store
+      }
+      const base = {
+        targetRepo: LINKED_REPO,
+        exec: mainRepoExec,
+        openStore,
+      }
+
+      await capture(adapter, {
+        ...base,
+        env: { AB_STORE: 'environment' },
+        storeRef: 'flag/../selected',
+      })
+      await capture(adapter, {
+        ...base,
+        env: { AB_STORE: 'environment/../selected-env' },
+      })
+      await capture(adapter, {
+        ...base,
+        env: { AB_STORE: '/absolute/state' },
+        storeRef: '  ',
+      })
+      await capture(adapter, {
+        ...base,
+        env: { AB_STORE: ' \t' },
+        storeRef: '',
+      })
+      await capture(adapter, {
+        ...base,
+        env: {},
+        storeRef: 'http://store.example.test/api',
+      })
+      await capture(adapter, {
+        ...base,
+        env: {},
+        storeRef: 'https://store.example.test/api?x=1',
+      })
+      await capture(adapter, {
+        ...base,
+        env: { AB_TOKEN: '' },
+        storeRef: 'https://store.example.test/empty-token',
+      })
+      await capture(adapter, {
+        ...base,
+        env: { AB_TOKEN: ' opaque token ' },
+        storeRef: 'https://store.example.test/opaque-token',
+      })
+
+      expect(opened).toEqual([
+        { ref: `${MAIN_REPO}/selected` },
+        { ref: `${MAIN_REPO}/selected-env` },
+        { ref: '/absolute/state' },
+        { ref: `${MAIN_REPO}/.autobuild` },
+        { ref: 'http://store.example.test/api' },
+        { ref: 'https://store.example.test/api?x=1' },
+        { ref: 'https://store.example.test/empty-token' },
+        {
+          ref: 'https://store.example.test/opaque-token',
+          token: ' opaque token ',
+        },
+      ])
+    })
+
+    test('uses canonical main-repository identity', async () => {
+      const store = new MemoryBuildStore()
+      await store.createBuild({ slug: 'main-build', repo: MAIN_REPO })
+      await store.createBuild({ slug: 'other-build', repo: '/other/repo' })
+      await store.ensureRepo(MAIN_REPO)
+      const stdout = await capture(adapter, {
+        targetRepo: LINKED_REPO,
+        env: {},
+        exec: mainRepoExec,
+        openStore: () => store,
+      })
+      expect(adapter.canonicalMarker(stdout)).toBe(adapter.expectedCanonicalMarker)
+    })
+
+    test('closes exactly once on success, store failure, and output failure', async () => {
+      const run = async (mode: 'success' | 'store' | 'output'): Promise<number> => {
+        const store = new MemoryBuildStore()
+        let closes = 0
+        const tracked = trackedStore(store, {
+          failOperations: mode === 'store',
+          onClose: () => {
+            closes += 1
+          },
+        })
+        const command = adapter.run({
+          targetRepo: LINKED_REPO,
+          env: {},
+          exec: mainRepoExec,
+          openStore: () => tracked,
+          stdout:
+            mode === 'output'
+              ? () => {
+                  throw new Error('output failed')
+                }
+              : () => {},
+        })
+        if (mode === 'success') await command
+        else {
+          await expect(command).rejects.toThrow(
+            mode === 'store' ? 'store operation failed' : 'output failed',
+          )
+        }
+        return closes
+      }
+
+      expect(await run('success')).toBe(1)
+      expect(await run('store')).toBe(1)
+      expect(await run('output')).toBe(1)
+    })
+
+    test('propagates opener failure without phantom cleanup', async () => {
+      let closes = 0
+      const unopened = new MemoryBuildStore()
+      unopened.close = async () => {
+        closes += 1
+      }
+      await expect(
+        adapter.run({
+          targetRepo: LINKED_REPO,
+          env: {},
+          exec: mainRepoExec,
+          stdout: () => {},
+          openStore: () => {
+            throw new Error('open failed')
+          },
+        }),
+      ).rejects.toThrow('open failed')
+      expect(closes).toBe(0)
+    })
+
+    test('production composition opens a local SQLite root', async () => {
+      const repo = await mkdtemp(join(tmpdir(), 'ab-store-opening-local-'))
+      try {
+        await adapter.run({
+          targetRepo: repo,
+          env: {},
+          exec: noGit,
+          stdout: () => {},
+          storeRef: 'state',
+        })
+        expect(existsSync(join(repo, 'state', 'autobuild.sqlite'))).toBe(true)
+      } finally {
+        await rm(repo, { recursive: true, force: true })
+      }
+    })
+
+    test('production composition forwards a token to remote HTTP and rejects missing or invalid credentials', async () => {
+      const secret = 'store-opening-secret'
+      const now = new Date('2026-07-15T12:00:00.000Z')
+      const backing = new MemoryBuildStore({ clock: () => now })
+      const server = startStoreServer({
+        store: backing,
+        secret,
+        clock: () => now,
+      })
+      const token = mintToken(secret, {
+        build: '*',
+        session: '*',
+        exp: now.getTime() + 60_000,
+      })
+      try {
+        await adapter.run({
+          targetRepo: LINKED_REPO,
+          env: { AB_TOKEN: token },
+          exec: mainRepoExec,
+          stdout: () => {},
+          storeRef: server.url,
+        })
+        await expect(
+          adapter.run({
+            targetRepo: LINKED_REPO,
+            env: {},
+            exec: mainRepoExec,
+            stdout: () => {},
+            storeRef: server.url,
+          }),
+        ).rejects.toThrow(/missing bearer token/)
+        await expect(
+          adapter.run({
+            targetRepo: LINKED_REPO,
+            env: { AB_TOKEN: 'invalid-token' },
+            exec: mainRepoExec,
+            stdout: () => {},
+            storeRef: server.url,
+          }),
+        ).rejects.toThrow(/invalid or expired token/)
+      } finally {
+        await server.stop()
+        await backing.close()
+      }
+    })
+  })
+}

package/packages/core/src/cli/store-opening.ts

@@ -0,0 +1,167 @@
+/**
+ * Production BuildStore composition for CLI commands.
+ *
+ * `repo-state.ts` owns repository identity and reference precedence, while
+ * `store-ref.ts` remains the adapter-free local-vs-remote parser. This module
+ * joins those seams to the production remote adapter and owns finite-command
+ * store lifecycle.
+ */
+import type { Exec } from '../ports/workspace/git-worktree'
+import { RemoteBuildStore } from '../store/remote/client'
+import { scopeLocalStoreToPhaseSession } from '../store/phase-session'
+import type { BuildStore } from '../store/types'
+import {
+  resolveAmbientReadSession,
+  type AmbientReadSession,
+  type CliEnv,
+  type HarvestCliEnv,
+} from './env'
+import { isRemoteStoreRef, resolveRepoState, type RepoStatePaths } from './repo-state'
+import { resolveStore } from './store-ref'
+
+/** Shared injection seam used by every command that opens a BuildStore. */
+export type StoreOpener = (ref: string, token?: string) => BuildStore
+
+function optionalToken(value: string | undefined): string | undefined {
+  // Bearer credentials are opaque. Only absence and the exact empty value mean
+  // "no token"; nonempty values are forwarded byte-for-byte.
+  return value !== undefined && value !== '' ? value : undefined
+}
+
+/** Production local/remote composition. The low-level parser stays injectable
+ * and does not import the HTTP adapter. */
+export const openProductionStore: StoreOpener = (ref, token) => {
+  const forwardedToken = optionalToken(token)
+  return resolveStore(ref, {
+    remoteFactory: (url, remoteToken) => new RemoteBuildStore({ url, token: remoteToken }),
+    ...(forwardedToken !== undefined ? { token: forwardedToken } : {}),
+  })
+}
+
+/** Apply validated ambient authority to a selected Store handle. Remote
+ * handles retain token-backed server authorization; filesystem handles receive
+ * the equivalent in-process scope. Keeping this primitive shared prevents
+ * phase commands and ambient-aware query commands from drifting. */
+function scopeSelectedStoreToPhaseSession(
+  store: BuildStore,
+  ref: string,
+  env: AmbientReadSession,
+): BuildStore {
+  if (isRemoteStoreRef(ref)) return store
+  return scopeLocalStoreToPhaseSession(
+    store,
+    'build' in env
+      ? { kind: 'build', id: env.build, session: env.session }
+      : { kind: 'repo', id: env.repo, session: env.session },
+  )
+}
+
+/** Open the Store for a validated phase/Harvest ambient identity. */
+export function openProductionSessionStore(env: CliEnv | HarvestCliEnv): BuildStore {
+  return scopeSelectedStoreToPhaseSession(openProductionStore(env.store, env.token), env.store, env)
+}
+
+export interface OpenedStoreContext extends RepoStatePaths {
+  store: BuildStore
+  token?: string
+  /** The validated ambient phase/Harvest identity this invocation carries, if
+   * any — the same value that scoped `store` on the local path. Exposed so a
+   * command core can extend own-resource authority to remote handles too,
+   * where no session wrapper exists. */
+  ambient?: AmbientReadSession
+}
+
+export interface OpenStoreForRepoStateOpts {
+  env: Record<string, string | undefined>
+  openStore?: StoreOpener
+}
+
+/** Open from an already canonicalized state selection. Dispatch uses this form
+ * so repository topology and relative overrides are decided exactly once. */
+export function openStoreForRepoState(
+  state: RepoStatePaths,
+  opts: OpenStoreForRepoStateOpts,
+): OpenedStoreContext {
+  const token = optionalToken(opts.env.AB_TOKEN)
+  const store = (opts.openStore ?? openProductionStore)(state.storeRef, token)
+  return {
+    ...state,
+    store,
+    ...(token !== undefined ? { token } : {}),
+  }
+}
+
+export interface SessionlessStoreOpts extends OpenStoreForRepoStateOpts {
+  targetRepo: string
+  exec: Exec
+  /** Explicit --store; precedence is applied by repo-state.ts. */
+  storeRef?: string
+}
+
+/** Resolve the main checkout and sessionless reference precedence, then open
+ * the selected production or injected store. The caller owns the handle. */
+export async function openSessionlessStore(
+  opts: SessionlessStoreOpts,
+): Promise<OpenedStoreContext> {
+  const state = await resolveRepoState({
+    targetRepo: opts.targetRepo,
+    exec: opts.exec,
+    ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+    ...(opts.env.AB_STORE !== undefined ? { envStore: opts.env.AB_STORE } : {}),
+  })
+  return openStoreForRepoState(state, opts)
+}
+
+/** Finite command ownership boundary. Opening failures occur before the
+ * try/finally, so only a successfully returned handle is ever closed.
+ *
+ * Remote store handles do not session-scope (bearer authorization is the
+ * server's concern), so a command core that needs own-build authority must
+ * consume `ambient` from the context directly rather than rely on the handle
+ * enforcing a scope. */
+export async function withSessionlessStore<T>(
+  opts: SessionlessStoreOpts,
+  use: (context: OpenedStoreContext) => Promise<T> | T,
+): Promise<T> {
+  const context = await openSessionlessStore(opts)
+  try {
+    return await use(context)
+  } finally {
+    await context.store.close()
+  }
+}
+
+/** Dedicated opener for the finite query commands whose operator-sessionless
+ * syntax is also useful inside a phase. Invalid ambient identity fails before
+ * repository canonicalization or Store opening; absent identity preserves the
+ * ordinary unscoped operator path. */
+export async function openAmbientReadStore(
+  opts: SessionlessStoreOpts,
+): Promise<OpenedStoreContext> {
+  const ambient = resolveAmbientReadSession(opts.env)
+  const state = await resolveRepoState({
+    targetRepo: opts.targetRepo,
+    exec: opts.exec,
+    ...(opts.storeRef !== undefined ? { storeRef: opts.storeRef } : {}),
+    ...(opts.env.AB_STORE !== undefined ? { envStore: opts.env.AB_STORE } : {}),
+  })
+  const context = openStoreForRepoState(state, opts)
+  if (ambient === undefined) return context
+  return {
+    ...context,
+    ambient,
+    store: scopeSelectedStoreToPhaseSession(context.store, state.storeRef, ambient),
+  }
+}
+
+export async function withAmbientReadStore<T>(
+  opts: SessionlessStoreOpts,
+  use: (context: OpenedStoreContext) => Promise<T> | T,
+): Promise<T> {
+  const context = await openAmbientReadStore(opts)
+  try {
+    return await use(context)
+  } finally {
+    await context.store.close()
+  }
+}

package/packages/core/src/cli/store-ref.ts

@@ -0,0 +1,33 @@
+/**
+ * `AB_STORE` reference resolution (SPEC §7.2, §8.1): a local filesystem path
+ * opens the SQLite+blob-dir store; an http(s) URL is the remote HTTP adapter.
+ *
+ * The production remote adapter is composed in `src/cli/store-opening.ts` via
+ * `remoteFactory`. This low-level parser stays decoupled from that adapter, so
+ * it remains independently testable and an unwired entry point fails clearly.
+ */
+import { openLocalStore } from '../store/local/store'
+import type { BuildStore } from '../store/types'
+import { isRemoteStoreRef } from './repo-state'
+
+export interface ResolveStoreOpts {
+  /** Constructs the remote HTTP store (§7.2.2); production wiring is external. */
+  remoteFactory?: (url: string, token?: string) => BuildStore
+  /** Scoped token (D8, `AB_TOKEN`) — passed through to the remote factory. */
+  token?: string
+}
+
+export function resolveStore(ref: string, opts: ResolveStoreOpts = {}): BuildStore {
+  if (isRemoteStoreRef(ref)) {
+    if (opts.remoteFactory === undefined) {
+      throw new Error(
+        `remote store support not wired: cannot open "${ref}" from this entry ` +
+          'point — supply the remote HTTP adapter (SPEC §7.2.2) as ' +
+          "resolveStore's remoteFactory; production composition lives in " +
+          'src/cli/store-opening.ts',
+      )
+    }
+    return opts.remoteFactory(ref, opts.token)
+  }
+  return openLocalStore(ref)
+}

package/packages/core/src/cli/terminal-restore.ts

@@ -0,0 +1,174 @@
+/**
+ * Terminal modes owned by the interactive dispatch dashboard. A declaration is
+ * the single source for both its ordinary enter/leave writes and the
+ * process-boundary emergency restore.
+ */
+export interface TerminalMode {
+  readonly name: string
+  readonly enter: string
+  readonly restore: string
+  /** Lower values restore first when the process boundary unwinds all modes. */
+  readonly restoreOrder: number
+}
+
+export const ALTERNATE_SCREEN_MODE = {
+  name: 'alternate-screen',
+  enter: '\x1b[?1049h',
+  restore: '\x1b[?1049l',
+  restoreOrder: 30,
+} as const satisfies TerminalMode
+
+export const HIDDEN_CURSOR_MODE = {
+  name: 'hidden-cursor',
+  enter: '\x1b[?25l',
+  restore: '\x1b[?25h',
+  restoreOrder: 40,
+} as const satisfies TerminalMode
+
+export const BRACKETED_PASTE_MODE = {
+  name: 'bracketed-paste',
+  enter: '\x1b[?2004h',
+  restore: '\x1b[?2004l',
+  restoreOrder: 20,
+} as const satisfies TerminalMode
+
+export const KITTY_KEYBOARD_FLAGS = 0b1_1101
+
+export const KITTY_KEYBOARD_MODE = {
+  name: 'kitty-keyboard-flags',
+  enter: `\x1b[>${KITTY_KEYBOARD_FLAGS}u`,
+  restore: '\x1b[<1u',
+  restoreOrder: 10,
+} as const satisfies TerminalMode
+
+export interface TerminalModeController {
+  /** Arm before writing the enter sequence. Re-entering an active mode is inert. */
+  enter(mode: TerminalMode): void
+  /** Write the ordinary restore sequence, then disarm. */
+  leave(mode: TerminalMode): void
+  /** Synchronously and best-effort restore every active mode. */
+  restoreAll(): void
+  isActive(mode: TerminalMode): boolean
+  readonly activeModes: readonly TerminalMode[]
+}
+
+/**
+ * Keep the currently active terminal modes at the output seam.
+ *
+ * Enter arms before its write and leave disarms only after a successful write.
+ * A failed normal write therefore remains visible to the synchronous emergency
+ * path. Emergency restoration attempts every mode even if one write fails.
+ */
+export function createTerminalModeController(
+  write: (chunk: string) => void,
+  emergencyWrite: (chunk: string) => void = write,
+): TerminalModeController {
+  const active = new Map<TerminalMode, number>()
+  let activation = 0
+
+  return {
+    enter(mode): void {
+      if (active.has(mode)) return
+      active.set(mode, activation++)
+      write(mode.enter)
+    },
+    leave(mode): void {
+      if (!active.has(mode)) return
+      write(mode.restore)
+      active.delete(mode)
+    },
+    restoreAll(): void {
+      const modes = [...active.entries()].sort(
+        ([left, leftActivation], [right, rightActivation]) =>
+          left.restoreOrder - right.restoreOrder || leftActivation - rightActivation,
+      )
+      for (const [mode] of modes) {
+        try {
+          emergencyWrite(mode.restore)
+          active.delete(mode)
+        } catch {
+          // Best effort means one broken write cannot prevent the remaining
+          // independent modes from being restored. The failed mode stays armed
+          // so a later exit boundary may retry it.
+        }
+      }
+    },
+    isActive: (mode): boolean => active.has(mode),
+    get activeModes(): readonly TerminalMode[] {
+      return [...active.keys()]
+    },
+  }
+}
+
+export const TERMINATING_SIGNALS = [
+  'SIGHUP',
+  'SIGQUIT',
+  'SIGTERM',
+] as const satisfies readonly NodeJS.Signals[]
+
+export interface TerminalRestoreProcess {
+  readonly pid: number
+  on(event: string, listener: (...args: unknown[]) => void): unknown
+  removeListener(event: string, listener: (...args: unknown[]) => void): unknown
+  kill(pid: number, signal: NodeJS.Signals): unknown
+}
+
+export interface TerminalRestoreHook {
+  /** Restore active modes, remove this hook's listeners, then replay a captured signal. */
+  close(): void
+}
+
+/**
+ * Install the synchronous process-boundary fallback used only by `ab dispatch`.
+ * SIGINT is deliberately absent: raw Ctrl-C and the binary's AbortController
+ * retain the dashboard's normal final-frame teardown. Other terminating signals
+ * restore immediately but are replayed only after the async dispatch drain.
+ */
+export function installTerminalRestoreHook(
+  modes: TerminalModeController,
+  boundary: TerminalRestoreProcess = process as unknown as TerminalRestoreProcess,
+  requestStop: (signal: (typeof TERMINATING_SIGNALS)[number]) => void = () => {},
+): TerminalRestoreHook {
+  let closed = false
+  let pendingSignal: (typeof TERMINATING_SIGNALS)[number] | undefined
+  const registrations: Array<[string, (...args: unknown[]) => void]> = []
+
+  const restore = (): void => {
+    modes.restoreAll()
+  }
+  const remove = (): void => {
+    if (closed) return
+    closed = true
+    for (const [event, listener] of registrations) boundary.removeListener(event, listener)
+  }
+  const add = (event: string, listener: (...args: unknown[]) => void): void => {
+    registrations.push([event, listener])
+    boundary.on(event, listener)
+  }
+
+  // `uncaughtExceptionMonitor` observes an uncaught fault without changing
+  // Node's default crash behavior. `exit` is the final synchronous fallback.
+  add('uncaughtExceptionMonitor', restore)
+  add('exit', restore)
+  for (const signal of TERMINATING_SIGNALS) {
+    add(signal, () => {
+      restore()
+      if (pendingSignal !== undefined) return
+      pendingSignal = signal
+      requestStop(signal)
+    })
+  }
+
+  return {
+    close(): void {
+      if (closed) return
+      // Closing after runCli returns also catches an unexpectedly active ledger
+      // without depending on another promise turn or stream drain.
+      restore()
+      remove()
+      // Replay only after the supervised child has drained and the handlers are
+      // gone, preserving the operating system's terminating-signal semantics.
+      if (pendingSignal !== undefined) boundary.kill(boundary.pid, pendingSignal)
+    },
+  }
+}