@defrex/autobuild 0.8.0

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

@@ -0,0 +1,48 @@
+/**
+ * Minimal local .env loader for the `ab` binary: `KEY=VALUE` lines, `#`
+ * comments, optional matching quotes around the value, optional `export `
+ * prefix. Values never override variables already present in the environment
+ * — the real environment wins, so a checked-in .env cannot shadow runner-set
+ * ambient auth (D8). Bun auto-loads .env when running bin/ab.ts directly;
+ * this loader makes the behavior explicit and Node-portable.
+ */
+import { readFileSync } from 'node:fs'
+
+const KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+/** Parse .env text into key/value pairs; malformed lines are skipped. */
+export function parseDotEnv(raw: string): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const line of raw.split('\n')) {
+    let trimmed = line.trim()
+    if (trimmed === '' || trimmed.startsWith('#')) continue
+    if (trimmed.startsWith('export ')) trimmed = trimmed.slice('export '.length)
+    const eq = trimmed.indexOf('=')
+    if (eq === -1) continue
+    const key = trimmed.slice(0, eq).trim()
+    if (!KEY_PATTERN.test(key)) continue
+    let value = trimmed.slice(eq + 1).trim()
+    const quote = value[0]
+    if ((quote === '"' || quote === "'") && value.length >= 2 && value.endsWith(quote)) {
+      value = value.slice(1, -1)
+    }
+    result[key] = value
+  }
+  return result
+}
+
+/**
+ * Load `path` into `env` if the file exists (silently a no-op otherwise).
+ * Only keys not already set in `env` are written.
+ */
+export function loadDotEnv(path: string, env: Record<string, string | undefined>): void {
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return
+  }
+  for (const [key, value] of Object.entries(parseDotEnv(raw))) {
+    if (env[key] === undefined) env[key] = value
+  }
+}

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

@@ -0,0 +1,206 @@
+/**
+ * Ambient auth resolution (SPEC §8.1, D8): the runner launches every session
+ * with `AB_STORE`, `AB_BUILD`, `AB_PHASE`, `AB_SESSION` (and `AB_TOKEN` for a
+ * remote store) set, and the CLI resolves everything from the environment —
+ * the skill only ever passes the build slug. Least privilege comes from the
+ * runner, not from prompt instructions.
+ *
+ * Errors here are agent feedback (D6): each names the missing or malformed
+ * variable and the format that would be accepted.
+ */
+import { CORE_PHASES, isPhase, type Phase } from '../ontology'
+
+export interface HarvestCliEnv {
+  store: string
+  repo: string
+  run: string
+  phase: 'synthesize' | 'review'
+  round: number
+  session: string
+  token?: string
+}
+
+export interface CliEnv {
+  /** Store URL or local path (`AB_STORE`). */
+  store: string
+  /** Build slug (`AB_BUILD`). */
+  build: string
+  /** Current phase, parsed from `AB_PHASE` (`<phase>[@<round>]`). */
+  phase: Phase
+  /** Round (loop phases) or attempt (verify/reconcile); defaults to 1. */
+  round: number
+  /** Session id (`AB_SESSION`). */
+  session: string
+  /** Scoped token for a remote store (`AB_TOKEN`) — optional locally. */
+  token?: string
+}
+
+export type AmbientReadSession = CliEnv | HarvestCliEnv
+
+const PHASE_FORMAT = "'<phase>[@<round>]' (e.g. 'implement@2', 'verify:e2e@1')"
+const BUILD_AMBIENT_TUPLE = 'AB_STORE/AB_BUILD/AB_PHASE/AB_SESSION'
+const HARVEST_AMBIENT_TUPLE = 'AB_STORE/AB_REPO/AB_HARVEST/AB_PHASE/AB_SESSION'
+
+/** Optional ambient identity is present but cannot safely select one scope. */
+export class InvalidAmbientContextError extends Error {
+  override readonly name = 'InvalidAmbientContextError'
+
+  constructor(detail: string) {
+    super(
+      `invalid ambient context: ${detail}. Expected no agent identity markers, ` +
+        `a complete build tuple (${BUILD_AMBIENT_TUPLE}), or a complete Harvest tuple ` +
+        `(${HARVEST_AMBIENT_TUPLE})`,
+    )
+  }
+}
+
+/** A required runner-provided session value is absent or empty. Callers that
+ * resolve ambient auth directly still receive the variable-specific message;
+ * the process wiring uses the type to defer missing-session feedback to the
+ * command-aware router guard. */
+export class MissingAmbientContextError extends Error {
+  override readonly name = 'MissingAmbientContextError'
+
+  constructor(
+    readonly variable: string,
+    expected: string,
+  ) {
+    super(
+      `${variable} is not set — expected ${expected}. ` +
+        'The runner sets ambient auth for every session (D8, SPEC §8.1).',
+    )
+  }
+}
+
+function requireVar(
+  env: Record<string, string | undefined>,
+  name: string,
+  expected: string,
+): string {
+  const value = env[name]
+  if (value === undefined || value === '') {
+    throw new MissingAmbientContextError(name, expected)
+  }
+  return value
+}
+
+/** `implement@2` → `{ phase: 'implement', round: 2 }`; round defaults to 1. */
+export function parseAbPhase(raw: string): { phase: Phase; round: number } {
+  // Split on the LAST '@' so a malformed 'implement@2@3' reports the phase
+  // part as unknown rather than silently taking the first segment.
+  const at = raw.lastIndexOf('@')
+  const phasePart = at === -1 ? raw : raw.slice(0, at)
+  const roundPart = at === -1 ? undefined : raw.slice(at + 1)
+
+  if (!isPhase(phasePart)) {
+    throw new Error(
+      `AB_PHASE "${raw}" names an unknown phase "${phasePart}" — expected one of ` +
+        `${CORE_PHASES.join(', ')}, or 'verify:<step>'; format ${PHASE_FORMAT}`,
+    )
+  }
+
+  let round = 1
+  if (roundPart !== undefined) {
+    if (!/^[1-9]\d*$/.test(roundPart)) {
+      throw new Error(
+        `AB_PHASE "${raw}" has a malformed round "${roundPart}" — the round must ` +
+          `be a positive integer; format ${PHASE_FORMAT}`,
+      )
+    }
+    round = Number(roundPart)
+  }
+  return { phase: phasePart, round }
+}
+
+/**
+ * Resolve the CLI's ambient environment (D8). Throws with the exact variable
+ * and expected format on the first problem found.
+ */
+export function parseHarvestPhase(raw: string): {
+  phase: 'synthesize' | 'review'
+  round: number
+} {
+  const match = /^(synthesize|review)@([1-9]\d*)$/.exec(raw)
+  if (!match) {
+    throw new Error(
+      `AB_PHASE "${raw}" is not a harvest session phase — expected ` +
+        `'synthesize@<round>' or 'review@<round>'`,
+    )
+  }
+  return {
+    phase: match[1] as 'synthesize' | 'review',
+    round: Number(match[2]),
+  }
+}
+
+export function resolveHarvestCliEnv(env: Record<string, string | undefined>): HarvestCliEnv {
+  const store = requireVar(env, 'AB_STORE', 'the store URL or local path')
+  const repo = requireVar(env, 'AB_REPO', 'the repository identity')
+  const run = requireVar(env, 'AB_HARVEST', 'the harvest run id')
+  const rawPhase = requireVar(env, 'AB_PHASE', `'synthesize@<round>' or 'review@<round>'`)
+  const session = requireVar(env, 'AB_SESSION', 'the session id')
+  const { phase, round } = parseHarvestPhase(rawPhase)
+  const token = env.AB_TOKEN
+  return {
+    store,
+    repo,
+    run,
+    phase,
+    round,
+    session,
+    ...(token !== undefined && token !== '' ? { token } : {}),
+  }
+}
+
+export function resolveCliEnv(env: Record<string, string | undefined>): CliEnv {
+  const store = requireVar(env, 'AB_STORE', 'the store URL or local path')
+  const build = requireVar(env, 'AB_BUILD', 'the build slug')
+  const rawPhase = requireVar(env, 'AB_PHASE', `the current phase in the format ${PHASE_FORMAT}`)
+  const session = requireVar(env, 'AB_SESSION', 'the session id')
+  const { phase, round } = parseAbPhase(rawPhase)
+  const token = env.AB_TOKEN
+  return {
+    store,
+    build,
+    phase,
+    round,
+    session,
+    ...(token !== undefined && token !== '' ? { token } : {}),
+  }
+}
+
+/**
+ * Classify the optional ambient authority used by the finite read-only query
+ * commands. AB_STORE and AB_TOKEN remain ordinary operator selection and
+ * credentials when no identity marker is present. Once any build/Harvest
+ * identity marker appears, however, the context must be complete and
+ * unambiguous; a partial agent environment must never fall back to operator
+ * authority.
+ */
+export function resolveAmbientReadSession(
+  env: Record<string, string | undefined>,
+): AmbientReadSession | undefined {
+  const present = (name: string): boolean => env[name] !== undefined
+  const hasBuildMarker = present('AB_BUILD')
+  const hasHarvestMarker = present('AB_REPO') || present('AB_HARVEST')
+  const hasSharedMarker = present('AB_PHASE') || present('AB_SESSION')
+
+  if (!hasBuildMarker && !hasHarvestMarker && !hasSharedMarker) return undefined
+  if (hasBuildMarker && hasHarvestMarker) {
+    throw new InvalidAmbientContextError(
+      'build and Harvest identity markers are mixed, so resource authority is ambiguous',
+    )
+  }
+  if (!hasBuildMarker && !hasHarvestMarker) {
+    throw new InvalidAmbientContextError(
+      'AB_PHASE or AB_SESSION is present without AB_BUILD or AB_REPO/AB_HARVEST',
+    )
+  }
+
+  try {
+    return hasBuildMarker ? resolveCliEnv(env) : resolveHarvestCliEnv(env)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new InvalidAmbientContextError(detail)
+  }
+}