@defrex/autobuild 0.8.0

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

@@ -0,0 +1,74 @@
+/**
+ * Dependency-free argv parsing for one exact `ab` command form.
+ *
+ * Callers supply the complete flag vocabulary for the receiving command. The
+ * parser deliberately owns only syntax: command-specific positional arity,
+ * numeric conversion, and mutually exclusive flags remain with the route.
+ */
+/** `'multi'` is a value flag that may repeat: values accumulate in order. */
+export type FlagKind = 'value' | 'boolean' | 'multi'
+
+export type FlagSpec = Readonly<Record<string, FlagKind>>
+
+export interface ParsedArgs {
+  positionals: string[]
+  flags: Map<string, string | true | string[]>
+}
+
+export function parseArgs(
+  args: readonly string[],
+  allowedFlags: FlagSpec,
+  usage: string,
+): ParsedArgs {
+  const positionals: string[] = []
+  const flags = new Map<string, string | true | string[]>()
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!
+    if (!arg.startsWith('--')) {
+      positionals.push(arg)
+      continue
+    }
+
+    const name = arg.slice(2)
+    const kind = Object.hasOwn(allowedFlags, name) ? allowedFlags[name] : undefined
+    if (kind === undefined) {
+      throw new Error(`unknown flag --${name} — ${usage}`)
+    }
+    if (kind !== 'multi' && flags.has(name)) {
+      throw new Error(`--${name} may be supplied only once — ${usage}`)
+    }
+    if (kind === 'boolean') {
+      flags.set(name, true)
+      continue
+    }
+
+    const value = args[index + 1]
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(
+        `--${name} requires a value${value !== undefined ? `, got "${value}"` : ''} — ${usage}`,
+      )
+    }
+    if (kind === 'multi') {
+      const collected = flags.get(name)
+      const previous: string[] = Array.isArray(collected) ? collected : []
+      flags.set(name, [...previous, value])
+    } else {
+      flags.set(name, value)
+    }
+    index += 1
+  }
+
+  return { positionals, flags }
+}
+
+export function stringFlag(parsed: ParsedArgs, name: string): string | undefined {
+  const value = parsed.flags.get(name)
+  return typeof value === 'string' ? value : undefined
+}
+
+/** Collected values of a repeatable flag, in supply order; `[]` when absent. */
+export function multiFlag(parsed: ParsedArgs, name: string): string[] {
+  const value = parsed.flags.get(name)
+  return Array.isArray(value) ? value : []
+}

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

@@ -0,0 +1,182 @@
+/**
+ * Artifact command core (SPEC §8.2). In-session `put|get` are own-build by
+ * construction: their store handle and remote token come from the phase tuple.
+ * `download` is the read-only operator form; when invoked with complete
+ * ambient phase identity it keeps that identity's Store authority.
+ */
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import { agentActor } from '../events/envelope'
+import { prAttachmentSchema } from '../ontology'
+import type { Exec } from '../ports/workspace/git-worktree'
+import type { Artifact, ArtifactMeta, BuildStore } from '../store/types'
+import type { CliEnv } from './env'
+import { buildInRepository } from './repo-state'
+import { withAmbientReadStore, type StoreOpener } from './store-opening'
+
+export interface ArtifactDeps {
+  store: BuildStore
+  env: CliEnv
+}
+
+/** `plan@1` → `{kind: 'plan', rev: 1}`; no `@` → latest (rev omitted). */
+export function parseArtifactSpec(spec: string): { kind: string; rev?: number } {
+  const at = spec.lastIndexOf('@')
+  if (at === -1) return { kind: spec }
+  const kind = spec.slice(0, at)
+  const revPart = spec.slice(at + 1)
+  if (kind === '' || !/^\d+$/.test(revPart)) {
+    throw new Error(
+      `invalid artifact ref "${spec}" — expected '<kind>' or '<kind>@<rev>' ` +
+        '(rev is a nonnegative integer; revisions are 0-based, §6.3)',
+    )
+  }
+  return { kind, rev: Number(revPart) }
+}
+
+export interface ArtifactPutOpts {
+  /** Atomically designate this exact deposited revision for PR projection. */
+  attach?: boolean
+}
+
+function normalizedMediaType(file: ReturnType<typeof Bun.file>): string {
+  const type = file.type.split(';', 1)[0]?.trim().toLowerCase()
+  return type === undefined || type === '' ? 'application/octet-stream' : type
+}
+
+/** Deposit a revision of `kind` from `filePath`; the caller prints the rev. */
+export async function artifactPut(
+  deps: ArtifactDeps,
+  kind: string,
+  filePath: string,
+  opts: ArtifactPutOpts = {},
+): Promise<ArtifactMeta> {
+  if (kind.trim() === '') {
+    throw new Error("'ab artifact put' requires a non-empty <kind> (§8.2)")
+  }
+  // §6.3 immutability: the spec cannot change during a build. It enters via
+  // dispatch (spec.imported / spec.authored — dispatcher plumbing, never this
+  // CLI) and changes only through a human-answered escalation (spec.revised).
+  // Without this gate, any phase's agent could silently swap the contract
+  // every later reviewer approves conformance to.
+  if (kind === 'spec') {
+    throw new Error(
+      "'ab artifact put spec' is rejected: the spec is immutable during a build " +
+        '(§6.3) — a phase that finds the spec itself wrong should raise ' +
+        "'ab escalate' so a human can revise it (spec.revised restarts from plan).",
+    )
+  }
+  const file = Bun.file(filePath)
+  if (!(await file.exists())) {
+    throw new Error(`'ab artifact put ${kind}': file not found: ${filePath}`)
+  }
+  // Artifacts are byte streams. Text deposits remain byte-for-byte compatible,
+  // while PNG and other binary evidence must never pass through UTF-8 decode.
+  const content = await file.bytes()
+  if (opts.attach !== true) {
+    return deps.store.putArtifact(deps.env.build, { kind, content })
+  }
+
+  // Validate every display/provider field before entering the atomic store
+  // operation. `basename` ensures callers cannot publish an output path.
+  const attachment = prAttachmentSchema.parse({
+    artifact: { kind, rev: 0 }, // replaced with the store-assigned rev below
+    filename: basename(filePath),
+    mediaType: normalizedMediaType(file),
+  })
+  const { artifacts } = await deps.store.appendWithArtifacts(
+    deps.env.build,
+    [{ kind, content }],
+    (deposited) => ({
+      actor: agentActor(deps.env.phase, deps.env.session),
+      type: 'pr-attachment.designated',
+      payload: {
+        ...attachment,
+        artifact: {
+          kind: deposited[0]!.kind,
+          rev: deposited[0]!.revision,
+        },
+      },
+    }),
+  )
+  const meta = artifacts[0]
+  if (meta === undefined) {
+    throw new Error('attachment deposit produced no artifact meta — this is a store bug')
+  }
+  return meta
+}
+
+/** Fetch `<kind>[@rev]` within the own build; latest when rev is omitted. */
+export async function artifactGet(deps: ArtifactDeps, spec: string): Promise<Artifact> {
+  const { kind, rev } = parseArtifactSpec(spec)
+  const artifact = await deps.store.getArtifact(deps.env.build, kind, rev)
+  if (artifact === null) {
+    const metas = await deps.store.listArtifacts(deps.env.build)
+    const kinds = [...new Set(metas.map((meta) => meta.kind))]
+    throw new Error(
+      `no "${kind}" artifact${rev !== undefined ? ` at rev ${rev}` : ''} in ` +
+        `build "${deps.env.build}" — deposited kinds: ${kinds.join(', ') || '(none)'}`,
+    )
+  }
+  return artifact
+}
+
+export interface ArtifactDownloadOpts {
+  /** Current checkout; repository identity resolves to its main worktree. */
+  targetRepo: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  build: string
+  spec: string
+  outputPath: string
+  /** Explicit --store; precedence remains flag > AB_STORE > local default. */
+  storeRef?: string
+  /** Adapter seam for local/remote selection tests. */
+  openStore?: StoreOpener
+}
+
+export interface ArtifactDownloadResult {
+  artifact: Artifact
+  outputPath: string
+}
+
+/** Read-only binary retrieval whose invocation requires no session. It
+ * deliberately accepts terminal builds: artifacts are evidence, not control. */
+export async function artifactDownload(
+  opts: ArtifactDownloadOpts,
+): Promise<ArtifactDownloadResult> {
+  if (opts.build.trim() === '') {
+    throw new Error("'ab artifact download' requires a non-empty <build>")
+  }
+  const { kind, rev } = parseArtifactSpec(opts.spec)
+  if (kind.trim() === '') {
+    throw new Error("'ab artifact download' requires a non-empty <kind>[@rev]")
+  }
+  return withAmbientReadStore(opts, async (context) => {
+    const record = await context.store.getBuild(opts.build)
+    if (record === null) {
+      throw new Error(
+        `no build "${opts.build}" in this store — run 'ab builds --all' or pass --store <ref>`,
+      )
+    }
+    if (!(await buildInRepository(record, context.checkout, opts.exec))) {
+      throw new Error(
+        `build "${opts.build}" belongs to repository "${record.repo}", not "${context.repo}"`,
+      )
+    }
+    const artifact = await context.store.getArtifact(opts.build, kind, rev)
+    if (artifact === null) {
+      const available = await context.store.listArtifacts(opts.build)
+      const refs = available.map((meta) => `${meta.kind}@${meta.revision}`)
+      throw new Error(
+        `no "${kind}" artifact${rev !== undefined ? ` at rev ${rev}` : ''} in ` +
+          `build "${opts.build}" — available refs: ${refs.join(', ') || '(none)'}`,
+      )
+    }
+
+    const outputPath = resolve(opts.targetRepo, opts.outputPath)
+    await mkdir(dirname(outputPath), { recursive: true })
+    await writeFile(outputPath, artifact.content)
+    return { artifact, outputPath }
+  })
+}

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

@@ -0,0 +1,198 @@
+/**
+ * Shared wiring for the `ab` process entry points. Production calls this with
+ * argv only; the repo-local hot entry may additionally supply a per-paint
+ * dashboard renderer resolver. All command routing and resource cleanup stay
+ * identical between the two entries.
+ */
+import { join } from 'node:path'
+import { isSessionlessInvocation, runCli } from './main'
+import { createUpgradeAgentResolver } from './upgrade-agent'
+import { loadDotEnv } from './dotenv'
+import { MissingAmbientContextError, resolveCliEnv, resolveHarvestCliEnv } from './env'
+import { openProductionSessionStore } from './store-opening'
+import { processTerminal, processTerminalInput, type TerminalOut } from './terminal'
+import { installTerminalRestoreHook, type TerminalRestoreProcess } from './terminal-restore'
+import type { DashboardRendererResolver } from './dashboard/render'
+import { loadConfig } from '../config/load'
+import { loadPlugins } from '../plugins/load'
+import { createForge } from '../ports/forge/create'
+import { spawnExec } from '../ports/workspace/git-worktree'
+import { randomIds } from '../ids'
+import { systemClock } from '../store/types'
+import { resolveMainRepo } from './repo-state'
+
+/** Upgrade (including its `update` alias) owns Ctrl-C only while raw per-file
+ * progress is active. Everywhere else its process must retain Node's ordinary
+ * immediate SIGINT termination. */
+export function usesGenericSessionlessSigintHandler(command: string | undefined): boolean {
+  return command !== 'upgrade' && command !== 'update'
+}
+
+export interface SessionlessSigintBoundary {
+  on(event: 'SIGINT', listener: () => void): unknown
+  once(event: 'SIGINT', listener: () => void): unknown
+  removeListener(event: 'SIGINT', listener: () => void): unknown
+}
+
+/** Dispatch keeps its listener through the complete child drain; ordinary
+ * sessionless commands preserve the historical one-shot cancellation. */
+export function installSessionlessSigintHandler(
+  command: string | undefined,
+  onSigint: () => void,
+  boundary: SessionlessSigintBoundary = process,
+): () => void {
+  if (!usesGenericSessionlessSigintHandler(command)) return () => {}
+  if (command === 'dispatch') boundary.on('SIGINT', onSigint)
+  else boundary.once('SIGINT', onSigint)
+  return () => boundary.removeListener('SIGINT', onSigint)
+}
+
+/** Install the dispatch-only process fallback around the exact CLI lifetime. */
+export async function withDispatchTerminalRestore<T>(
+  command: string | undefined,
+  terminal: TerminalOut,
+  run: () => Promise<T>,
+  boundary: TerminalRestoreProcess = process as unknown as TerminalRestoreProcess,
+  requestStop: () => void = () => {},
+): Promise<T> {
+  const hook =
+    command === 'dispatch'
+      ? installTerminalRestoreHook(terminal.modes, boundary, requestStop)
+      : undefined
+  try {
+    return await run()
+  } finally {
+    hook?.close()
+  }
+}
+
+export async function runBinary(
+  argv: string[],
+  resolveDashboardRenderer?: DashboardRendererResolver,
+): Promise<number> {
+  const command = argv[0]
+  // Version identity is installation-local and offline; do not inspect even a
+  // repository-local .env before routing it.
+  if (command !== '--version') {
+    // Local .env supplies developer-set secrets (e.g. LINEAR_API_KEY); real
+    // environment variables always win over .env values.
+    loadDotEnv(join(process.cwd(), '.env'), process.env)
+  }
+
+  const unscopedDeps = {
+    workspacePath: process.cwd(),
+    processEnv: process.env,
+    exec: spawnExec,
+    stdout: (line: string) => console.log(line),
+    stderr: (line: string) => console.error(line),
+  }
+
+  // Sessionless commands resolve their own repository/store and do not require
+  // a phase tuple; durable controls also take a target slug and inspect raw
+  // AB_SESSION/AB_BUILD only to reject self-control. The flat-name set and
+  // mixed nested-command classifier live beside the switch in main.ts.
+  if (isSessionlessInvocation(argv)) {
+    // The dispatch watch loop runs until SIGINT; abort the signal so it exits
+    // cleanly at the next tick boundary (§15.6-C: in-flight leases expire and
+    // a future dispatch re-attaches).
+    const controller = new AbortController()
+    const onSigint = (): void => controller.abort()
+    const ownsSigint = usesGenericSessionlessSigintHandler(command)
+    const terminal = processTerminal(process.stdout)
+    const removeSigint = installSessionlessSigintHandler(command, onSigint)
+    try {
+      return await withDispatchTerminalRestore(
+        command,
+        terminal,
+        () =>
+          runCli(argv, {
+            ...unscopedDeps,
+            ...(ownsSigint ? { signal: controller.signal } : {}),
+            // `ab dispatch`'s dashboard seam: interactive iff stdout is a real
+            // TTY, so a pipe or redirect silently gets plain output.
+            terminal,
+            input: processTerminalInput(process.stdin),
+            ...(command === 'init'
+              ? { initInteractive: process.stdin.isTTY === true && process.stdout.isTTY === true }
+              : {}),
+            upgradeResolverFactory: createUpgradeAgentResolver,
+            ...(resolveDashboardRenderer !== undefined ? { resolveDashboardRenderer } : {}),
+          }),
+        process as unknown as TerminalRestoreProcess,
+        onSigint,
+      )
+    } finally {
+      removeSigint()
+    }
+  }
+
+  if (command === 'harvest') {
+    let harvestEnv: ReturnType<typeof resolveHarvestCliEnv>
+    try {
+      harvestEnv = resolveHarvestCliEnv(process.env)
+    } catch (error) {
+      if (error instanceof MissingAmbientContextError) {
+        return runCli(argv, unscopedDeps)
+      }
+      console.error(error instanceof Error ? error.message : String(error))
+      return 1
+    }
+    const store = openProductionSessionStore(harvestEnv)
+    try {
+      return await runCli(argv, {
+        ...unscopedDeps,
+        store,
+        harvestEnv,
+        ids: randomIds(),
+        clock: systemClock,
+      })
+    } finally {
+      await store.close()
+    }
+  }
+
+  let cliEnv: ReturnType<typeof resolveCliEnv>
+  try {
+    cliEnv = resolveCliEnv(process.env)
+  } catch (error) {
+    if (error instanceof MissingAmbientContextError) {
+      return runCli(argv, unscopedDeps)
+    }
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+
+  // A scoped phase process is composed from the build worktree's immutable
+  // configuration just like dispatch. Load and select the forge before opening
+  // the store so plugin failures cannot partially execute terminal plumbing.
+  let forge: Awaited<ReturnType<typeof createForge>>
+  try {
+    const repoRoot = process.cwd()
+    const packageRoot = await resolveMainRepo(repoRoot, spawnExec)
+    const config = await loadConfig(join(repoRoot, 'autobuild.toml'))
+    const plugins = await loadPlugins(config.plugins, repoRoot, { packageRoot })
+    forge = await createForge({
+      name: config.forge,
+      registry: plugins,
+      env: process.env,
+      repoRoot,
+    })
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+
+  const store = openProductionSessionStore(cliEnv)
+  try {
+    return await runCli(argv, {
+      ...unscopedDeps,
+      store,
+      env: cliEnv,
+      forge,
+      ids: randomIds(),
+      clock: systemClock,
+    })
+  } finally {
+    await store.close()
+  }
+}