@marcusrbrown/infra 0.6.0 → 0.8.0

package/src/commands/cliproxy/setup/validation.ts

@@ -0,0 +1,182 @@
+import type {SetupOptions} from '../setup'
+
+import {z} from 'zod'
+
+import {parseProviders, type ProviderId} from './providers'
+
+// Permissive schema: unknown fields preserved via passthrough()
+const modelEntrySchema = z
+  .object({
+    id: z.string(),
+    owned_by: z.string(),
+  })
+  .passthrough()
+
+const modelsResponseSchema = z
+  .object({
+    data: z.array(modelEntrySchema),
+  })
+  .passthrough()
+
+export const MODEL_ID_RE = /^(?:anthropic|openai)\/[a-z\d](?:[a-z\d.\-]*[a-z\d])?$/
+
+const HTTP_TIMEOUT_MS = 10_000
+
+/** Local copy — avoids a circular import with setup.ts (validation → setup → validation). */
+function extractErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function validateSetupOptions(options: SetupOptions, isInteractive: boolean): void {
+  if (isInteractive) {
+    return
+  }
+
+  // Validate providers/model first (independent of key/repo/harness)
+  if (options.providers) {
+    const providers = parseProviders(options.providers)
+
+    if (providers.length > 1 && !options.model) {
+      throw new Error('Pass --model <provider/model-id> when selecting multiple providers.')
+    }
+
+    if (options.model) {
+      const slashIndex = options.model.indexOf('/')
+      const prefix = slashIndex === -1 ? options.model : options.model.slice(0, slashIndex)
+      if (!providers.includes(prefix as ProviderId)) {
+        throw new Error(
+          `Model prefix ${prefix} does not match selected providers (${providers.join(', ')}). Valid prefixes: ${providers.join(', ')}/`,
+        )
+      }
+    }
+  }
+
+  if (!options.dryRun && !options.key) {
+    throw new Error('--key is required when stdin is not a TTY. Provide an existing CLIProxyAPI key value.')
+  }
+
+  if (!options.repo) {
+    throw new Error('--repo is required when stdin is not a TTY. Provide the target GitHub repository as owner/repo.')
+  }
+
+  if (!options.harness) {
+    throw new Error('--harness is required when stdin is not a TTY. Choose opencode or claude-code.')
+  }
+
+  if (options.harness === 'generic') {
+    throw new Error('--harness generic is interactive-only because it requires custom secret names.')
+  }
+}
+
+/**
+ * Verifies that the required models are available on the proxy.
+ *
+ * Short-circuits immediately for anthropic-only setups — no fetch is made.
+ * Never echoes the Authorization header in any error message.
+ */
+export async function verifyModelsAvailable(
+  baseUrl: string,
+  key: string,
+  providers: ProviderId[],
+  model: string,
+): Promise<void> {
+  // Anthropic-only: no fetch needed
+  if (providers.length === 1 && providers[0] === 'anthropic') {
+    return
+  }
+
+  const endpoint = `${baseUrl}/v1/models`
+  const response = await fetch(endpoint, {
+    headers: {Authorization: `Bearer ${key}`},
+    signal: AbortSignal.timeout(10_000),
+  })
+
+  if (response.status === 401 || response.status === 403) {
+    throw new Error('Proxy key rejected. Verify with `cliproxy keys list` or rerun setup to create a new one.')
+  }
+
+  if (!response.ok) {
+    const rawBody = await response.text()
+    // Redact any Authorization headers or sk-* token-shaped strings that the server might echo
+    const redacted = rawBody
+      .replaceAll(/Bearer\s+[^\s"]+/g, 'Bearer <redacted>')
+      .replaceAll(/sk-[\w.-]{8,}/g, 'sk-<redacted>')
+    const excerpt = redacted.slice(0, 200)
+    throw new Error(`/v1/models returned HTTP ${response.status}: ${excerpt}`)
+  }
+
+  const json = (await response.json()) as unknown
+
+  let parsed: z.infer<typeof modelsResponseSchema>
+  try {
+    parsed = modelsResponseSchema.parse(json)
+  } catch (error) {
+    const message =
+      error instanceof z.ZodError
+        ? error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ')
+        : extractErrorMessage(error)
+    throw new Error(`Malformed /v1/models response: ${message}`)
+  }
+
+  const entries = parsed.data
+
+  // OpenAI presence check
+  if (providers.includes('openai')) {
+    const hasOpenAi = entries.some(e => e.owned_by === 'openai')
+    if (!hasOpenAi) {
+      throw new Error('No OpenAI models on proxy — is the Codex token loaded? Try `cliproxy login codex`.')
+    }
+  }
+
+  // Model presence check: strip provider prefix to get bare id
+  const slashIndex = model.indexOf('/')
+  const bareId = slashIndex === -1 ? model : model.slice(slashIndex + 1)
+  const providerPrefix = slashIndex >= 0 ? model.slice(0, slashIndex) : undefined
+
+  const modelPresent = entries.some(e => e.id === bareId)
+  if (!modelPresent) {
+    // List available ids for the matching provider only
+    const matchingIds = providerPrefix
+      ? entries.filter(e => e.owned_by === providerPrefix).map(e => e.id)
+      : entries.map(e => e.id)
+    const available = matchingIds.length > 0 ? matchingIds.join(', ') : '(none)'
+    throw new Error(`Model "${bareId}" not found on proxy. Available ${providerPrefix ?? 'models'}: ${available}`)
+  }
+}
+
+export async function assertProxyReachable(baseUrl: string): Promise<void> {
+  try {
+    const response = await fetch(baseUrl, {
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Proxy check failed for ${baseUrl}: HTTP ${response.status}. Is the proxy running and reachable?`)
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('Proxy check failed')) {
+      throw error
+    }
+    throw new Error(`Unable to reach proxy at ${baseUrl}: ${extractErrorMessage(error)}`)
+  }
+}
+
+export async function assertProxyKeyWorks(baseUrl: string, keyValue: string): Promise<void> {
+  try {
+    const response = await fetch(`${baseUrl}/v1/models`, {
+      headers: {
+        authorization: `Bearer ${keyValue}`,
+      },
+      signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Proxy key verification failed with HTTP ${response.status}`)
+    }
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('Proxy key verification')) {
+      throw error
+    }
+    throw new Error(`Unable to verify proxy key at ${baseUrl}: ${extractErrorMessage(error)}`)
+  }
+}

package/src/commands/cliproxy/setup/workflow-analyzer.test.ts

@@ -0,0 +1,341 @@
+/// <reference types="bun" />
+
+import {describe, expect, it} from 'bun:test'
+
+import {
+  analyzeFroBotWorkflow,
+  findFroBotAgentStepBodies,
+  formatWorkflowSnippet,
+  interpretGhContentResult,
+} from './workflow-analyzer'
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────────
+
+const COMPLETE_WORKFLOW = `      - uses: fro-bot/agent@abc123
+        with:
+          github-token: \${{ secrets.FRO_BOT_PAT }}
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          model: \${{ vars.FRO_BOT_MODEL }}
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+          opencode-config: \${{ secrets.OPENCODE_CONFIG }}
+          prompt: \${{ env.PROMPT }}
+`
+
+const MISSING_OPENCODE_CONFIG_WORKFLOW = `      - uses: fro-bot/agent@abc123
+        with:
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          github-token: \${{ secrets.FRO_BOT_PAT }}
+          model: \${{ vars.FRO_BOT_MODEL }}
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+          prompt: \${{ env.PROMPT }}
+`
+
+// Regression fixture for PR #125 review: a sibling step has `model:` as an input,
+// but the fro-bot/agent step is missing it. The step-scoped scan must still flag
+// `model` as missing, otherwise the diagnostic is silently suppressed.
+const SIBLING_STEP_SHADOWS_MODEL_INPUT = `name: ci
+on: [push]
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        model: [opus, sonnet]
+    steps:
+      - uses: actions/some-ai-step@abc
+        with:
+          model: \${{ matrix.model }}
+      - name: Run Fro Bot
+        uses: fro-bot/agent@def
+        with:
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          opencode-config: \${{ secrets.OPENCODE_CONFIG }}
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+`
+
+const WORKFLOW_WITHOUT_FRO_BOT_AGENT = `name: ci
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo hello
+`
+
+// Follow-up from PR #125 second review: the matchAll refactor must report gaps
+// in any fro-bot/agent step, not just the first. Step #1 is complete, step #2 is
+// missing opencode-config and model — the analyzer should flag only step #2.
+const TWO_AGENT_STEPS_SECOND_BROKEN = `name: fro-bot
+on: [pull_request, schedule]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run Fro Bot review
+        uses: fro-bot/agent@abc123
+        with:
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          opencode-config: \${{ secrets.OPENCODE_CONFIG }}
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+          model: \${{ vars.FRO_BOT_MODEL }}
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run Fro Bot dispatch
+        uses: fro-bot/agent@abc123
+        with:
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+`
+
+// openai model prefix regression fixtures
+const WORKFLOW_WITH_OPENAI_MODEL = `      - uses: fro-bot/agent@abc123
+        with:
+          github-token: \${{ secrets.FRO_BOT_PAT }}
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          model: openai/gpt-5.4-mini
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+          opencode-config: \${{ secrets.OPENCODE_CONFIG }}
+          prompt: \${{ env.PROMPT }}
+`
+
+// Dual-provider hints: omo-providers value contains "openai", model is openai/...
+const WORKFLOW_WITH_DUAL_PROVIDER_HINTS = `name: fro-bot
+on: [pull_request]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run Fro Bot
+        uses: fro-bot/agent@abc123
+        with:
+          github-token: \${{ secrets.FRO_BOT_PAT }}
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          model: openai/gpt-5.4-mini
+          omo-providers: anthropic,openai
+          opencode-config: \${{ secrets.OPENCODE_CONFIG }}
+          prompt: \${{ env.PROMPT }}
+`
+
+// Missing opencode-config but with openai model prefix — gap detection must still fire
+const MISSING_OPENCODE_CONFIG_OPENAI_MODEL_WORKFLOW = `      - uses: fro-bot/agent@abc123
+        with:
+          auth-json: \${{ secrets.OPENCODE_AUTH_JSON }}
+          github-token: \${{ secrets.FRO_BOT_PAT }}
+          model: openai/gpt-5.4-mini
+          omo-providers: \${{ secrets.OMO_PROVIDERS }}
+          prompt: \${{ env.PROMPT }}
+`
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('cliproxy setup helpers', () => {
+  describe('analyzeFroBotWorkflow', () => {
+    it('returns empty stepsWithGaps when all four inputs are wired', () => {
+      const result = analyzeFroBotWorkflow(COMPLETE_WORKFLOW)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toEqual([])
+    })
+
+    it('detects a missing opencode-config input on step #1', () => {
+      const result = analyzeFroBotWorkflow(MISSING_OPENCODE_CONFIG_WORKFLOW)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toHaveLength(1)
+      expect(result.stepsWithGaps[0]?.stepOrdinal).toBe(1)
+      expect([...(result.stepsWithGaps[0]?.missingInputs ?? [])]).toEqual(['opencode-config'])
+    })
+
+    it('flags model as missing even when a sibling step uses model: as an input', () => {
+      const result = analyzeFroBotWorkflow(SIBLING_STEP_SHADOWS_MODEL_INPUT)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toHaveLength(1)
+      expect(result.stepsWithGaps[0]?.stepOrdinal).toBe(1)
+      expect([...(result.stepsWithGaps[0]?.missingInputs ?? [])]).toEqual(['model'])
+    })
+
+    it('returns kind no-agent-step when the workflow has no fro-bot/agent step', () => {
+      const result = analyzeFroBotWorkflow(WORKFLOW_WITHOUT_FRO_BOT_AGENT)
+
+      expect(result.kind).toBe('no-agent-step')
+    })
+
+    it('returns kind no-agent-step for empty content', () => {
+      const result = analyzeFroBotWorkflow('')
+
+      expect(result.kind).toBe('no-agent-step')
+    })
+
+    it('reports only the broken step when a workflow has two fro-bot/agent steps and one is complete', () => {
+      const result = analyzeFroBotWorkflow(TWO_AGENT_STEPS_SECOND_BROKEN)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toHaveLength(1)
+      expect(result.stepsWithGaps[0]?.stepOrdinal).toBe(2)
+      expect([...(result.stepsWithGaps[0]?.missingInputs ?? [])]).toEqual(['opencode-config', 'model'])
+    })
+  })
+
+  describe('analyzer regression for openai model prefix', () => {
+    it('returns empty stepsWithGaps for a workflow with openai/... model and all four inputs', () => {
+      const result = analyzeFroBotWorkflow(WORKFLOW_WITH_OPENAI_MODEL)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toEqual([])
+    })
+
+    it('returns empty stepsWithGaps for a dual-provider workflow with openai/... model', () => {
+      const result = analyzeFroBotWorkflow(WORKFLOW_WITH_DUAL_PROVIDER_HINTS)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toEqual([])
+    })
+
+    it('detects missing opencode-config even when model is openai/...', () => {
+      const result = analyzeFroBotWorkflow(MISSING_OPENCODE_CONFIG_OPENAI_MODEL_WORKFLOW)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toHaveLength(1)
+      expect(result.stepsWithGaps[0]?.stepOrdinal).toBe(1)
+      expect([...(result.stepsWithGaps[0]?.missingInputs ?? [])]).toEqual(['opencode-config'])
+    })
+
+    it('detects missing opencode-config when model is anthropic/... (sanity regression)', () => {
+      const result = analyzeFroBotWorkflow(MISSING_OPENCODE_CONFIG_WORKFLOW)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toHaveLength(1)
+      expect(result.stepsWithGaps[0]?.stepOrdinal).toBe(1)
+      expect([...(result.stepsWithGaps[0]?.missingInputs ?? [])]).toEqual(['opencode-config'])
+    })
+
+    it('does not emit any enable-omo warning for openai model workflows', () => {
+      const openaiResult = analyzeFroBotWorkflow(WORKFLOW_WITH_OPENAI_MODEL)
+      const dualResult = analyzeFroBotWorkflow(WORKFLOW_WITH_DUAL_PROVIDER_HINTS)
+
+      // The analyzer result shape has no warning category — only stepsWithGaps.
+      // Verify the result object has exactly the expected keys (kind + stepsWithGaps).
+      expect(Object.keys(openaiResult)).toEqual(['kind', 'stepsWithGaps'])
+      expect(Object.keys(dualResult)).toEqual(['kind', 'stepsWithGaps'])
+    })
+
+    it('REQUIRED_OPENCODE_INPUTS covers exactly auth-json, opencode-config, omo-providers, model (no enable-omo)', () => {
+      // Infer the required inputs from fixture-based testing: a workflow with exactly
+      // these four inputs and no others (besides github-token and prompt) passes with zero gaps.
+      const result = analyzeFroBotWorkflow(WORKFLOW_WITH_OPENAI_MODEL)
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      // Zero gaps confirms the four inputs in the fixture are sufficient — enable-omo is NOT required.
+      expect(result.stepsWithGaps).toEqual([])
+    })
+  })
+
+  describe('interpretGhContentResult', () => {
+    it('returns kind missing when stderr contains HTTP 404', () => {
+      const result = interpretGhContentResult({
+        exitCode: 1,
+        stdout: '',
+        stderr: 'gh: Not Found (HTTP 404)',
+      })
+
+      expect(result.kind).toBe('missing')
+    })
+
+    it('returns kind unreachable with the stderr reason on non-404 failures', () => {
+      const result = interpretGhContentResult({
+        exitCode: 1,
+        stdout: '',
+        stderr: 'gh: API rate limit exceeded',
+      })
+
+      expect(result.kind).toBe('unreachable')
+      if (result.kind !== 'unreachable') throw new Error('unreachable')
+      expect(result.reason).toBe('gh: API rate limit exceeded')
+    })
+
+    it('falls back to the exit code when stderr is empty on a non-404 failure', () => {
+      const result = interpretGhContentResult({exitCode: 2, stdout: '', stderr: ''})
+
+      expect(result.kind).toBe('unreachable')
+      if (result.kind !== 'unreachable') throw new Error('unreachable')
+      expect(result.reason).toBe('gh api exited with code 2')
+    })
+
+    it('delegates to analyzeFroBotWorkflow on a successful response', () => {
+      const result = interpretGhContentResult({
+        exitCode: 0,
+        stdout: COMPLETE_WORKFLOW,
+        stderr: '',
+      })
+
+      expect(result.kind).toBe('analyzed')
+      if (result.kind !== 'analyzed') throw new Error('unreachable')
+      expect(result.stepsWithGaps).toEqual([])
+    })
+  })
+
+  describe('formatWorkflowSnippet', () => {
+    it('renders snippet lines at 10-space indent so they can be pasted directly under with:', () => {
+      const snippet = formatWorkflowSnippet(['opencode-config', 'model'])
+
+      /* eslint-disable no-template-curly-in-string -- GitHub Actions expression syntax, not JS template literals */
+      const expected = [
+        '          opencode-config: ${{ secrets.OPENCODE_CONFIG }}',
+        '          model: ${{ vars.FRO_BOT_MODEL }}',
+      ].join('\n')
+      /* eslint-enable no-template-curly-in-string */
+      expect(snippet).toBe(expected)
+    })
+  })
+})
+
+describe('findFroBotAgentStepBodies', () => {
+  it('returns empty array for content with no fro-bot/agent step', () => {
+    const bodies = findFroBotAgentStepBodies(WORKFLOW_WITHOUT_FRO_BOT_AGENT)
+
+    expect(bodies).toEqual([])
+  })
+
+  it('returns empty array for empty content', () => {
+    const bodies = findFroBotAgentStepBodies('')
+
+    expect(bodies).toEqual([])
+  })
+
+  it('returns one entry for a single fro-bot/agent step', () => {
+    const bodies = findFroBotAgentStepBodies(COMPLETE_WORKFLOW)
+
+    expect(bodies).toHaveLength(1)
+    expect(bodies[0]?.stepOrdinal).toBe(1)
+    expect(bodies[0]?.body).toContain('fro-bot/agent@')
+  })
+
+  it('returns two entries for a workflow with two fro-bot/agent steps', () => {
+    const bodies = findFroBotAgentStepBodies(TWO_AGENT_STEPS_SECOND_BROKEN)
+
+    expect(bodies).toHaveLength(2)
+    expect(bodies[0]?.stepOrdinal).toBe(1)
+    expect(bodies[1]?.stepOrdinal).toBe(2)
+  })
+
+  it('scopes each body to only its own step — sibling step with: block is excluded', () => {
+    const bodies = findFroBotAgentStepBodies(SIBLING_STEP_SHADOWS_MODEL_INPUT)
+
+    // Only one fro-bot/agent step in this fixture
+    expect(bodies).toHaveLength(1)
+    // The sibling step's `model:` key must NOT appear in the fro-bot/agent step body
+    expect(bodies[0]?.body).not.toContain('matrix.model')
+  })
+})

package/src/commands/cliproxy/setup/workflow-analyzer.ts

@@ -0,0 +1,137 @@
+import type {CommandResult} from './gh'
+
+import {runGh} from './gh'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type FroBotWorkflowCheck =
+  | {kind: 'missing'}
+  | {kind: 'unreachable'; reason: string}
+  | {kind: 'no-agent-step'}
+  | {
+      kind: 'analyzed'
+      stepsWithGaps: readonly {stepOrdinal: number; missingInputs: readonly string[]}[]
+    }
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+// github-token and prompt are intentionally excluded from this check:
+// github-token is harness-agnostic (PAT wiring, not secret-routing) and prompt is
+// workflow-defined (the user's prompt body, not a harness default).
+//
+// NOTE: `enable-omo: true` is NOT a required input.
+// For proxy-routed providers configured via OPENCODE_CONFIG.provider.<name>.options.baseURL,
+// the fro-bot/agent action honors auth.json directly (regardless of oMo state).
+// Source: fro-bot/agent@v0.44.3+ action.yaml lines 99-104; verified by librarian 2026-05-25.
+const REQUIRED_OPENCODE_INPUTS = ['auth-json', 'opencode-config', 'omo-providers', 'model'] as const
+type RequiredOpencodeInput = (typeof REQUIRED_OPENCODE_INPUTS)[number]
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Slice the workflow content into one entry per `fro-bot/agent` step. Handles
+ * both the `- name:\n  uses: ...` and `- uses: ...` step shapes. Returns an
+ * empty array if no fro-bot/agent step is present.
+ *
+ * Step-scoped slicing prevents false-passes where a same-named input key in a
+ * sibling step (strategy.matrix, custom actions, reusable workflow with:
+ * blocks) could mask a genuine gap in fro-bot/agent's wiring.
+ */
+export function findFroBotAgentStepBodies(content: string): {stepOrdinal: number; body: string}[] {
+  const bodies: {stepOrdinal: number; body: string}[] = []
+  const pattern = /^(\s*(?:-\s+)?)uses:\s*fro-bot\/agent@/gm
+
+  for (const match of content.matchAll(pattern)) {
+    if (match.index === undefined || match[1] === undefined) continue
+
+    const stepBodyIndent = match[1].length
+    const dashIndent = Math.max(0, stepBodyIndent - 2)
+    const lines = content.slice(match.index).split('\n')
+    const stepLines: string[] = [lines[0] ?? '']
+
+    for (let index = 1; index < lines.length; index += 1) {
+      const line = lines[index] ?? ''
+      if (!line.trim()) {
+        stepLines.push(line)
+        continue
+      }
+      const firstNonSpace = line.search(/\S/)
+      if (firstNonSpace === dashIndent && line.trimStart().startsWith('-')) break
+      if (firstNonSpace < dashIndent) break
+      stepLines.push(line)
+    }
+
+    bodies.push({stepOrdinal: bodies.length + 1, body: stepLines.join('\n')})
+  }
+
+  return bodies
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export function analyzeFroBotWorkflow(workflowContent: string): FroBotWorkflowCheck {
+  const steps = findFroBotAgentStepBodies(workflowContent)
+
+  if (steps.length === 0) {
+    return {kind: 'no-agent-step'}
+  }
+
+  const stepsWithGaps = steps
+    .map(step => ({
+      stepOrdinal: step.stepOrdinal,
+      missingInputs: REQUIRED_OPENCODE_INPUTS.filter(input => {
+        const inputPattern = new RegExp(String.raw`^\s+${input}:`, 'm')
+        return !inputPattern.test(step.body)
+      }),
+    }))
+    .filter(step => step.missingInputs.length > 0)
+
+  return {kind: 'analyzed', stepsWithGaps}
+}
+
+/**
+ * Extracted pure helper: turn a `gh api /repos/.../contents/<file>` result into
+ * a FroBotWorkflowCheck. Separated from checkFroBotWorkflow so tests can exercise
+ * the 404-vs-transport-error logic without mocking Bun.spawn.
+ */
+export function interpretGhContentResult(result: CommandResult): FroBotWorkflowCheck {
+  if (result.exitCode === 0) {
+    return analyzeFroBotWorkflow(result.stdout)
+  }
+
+  // gh prints `gh: Not Found (HTTP 404)` on 404; anything else is auth/network/5xx.
+  if (/HTTP 404/.test(result.stderr)) {
+    return {kind: 'missing'}
+  }
+
+  return {
+    kind: 'unreachable',
+    reason: result.stderr.trim() || `gh api exited with code ${result.exitCode}`,
+  }
+}
+
+export async function checkFroBotWorkflow(repo: string): Promise<FroBotWorkflowCheck> {
+  const result = await runGh([
+    'api',
+    '--header',
+    'Accept: application/vnd.github.raw',
+    `/repos/${repo}/contents/.github/workflows/fro-bot.yaml`,
+  ])
+
+  return interpretGhContentResult(result)
+}
+
+// Snippet uses 10-space indent to match the canonical `with:` block depth
+// in marcusrbrown/infra/.github/workflows/fro-bot.yaml, so users can paste
+// directly under their step's `with:` key without re-indenting.
+export function formatWorkflowSnippet(missingInputs: readonly string[]): string {
+  /* eslint-disable no-template-curly-in-string -- GitHub Actions expression syntax, not JS template literals */
+  const inputMap = {
+    'auth-json': 'auth-json: ${{ secrets.OPENCODE_AUTH_JSON }}',
+    'opencode-config': 'opencode-config: ${{ secrets.OPENCODE_CONFIG }}',
+    'omo-providers': 'omo-providers: ${{ secrets.OMO_PROVIDERS }}',
+    model: 'model: ${{ vars.FRO_BOT_MODEL }}',
+  } satisfies Record<RequiredOpencodeInput, string>
+  /* eslint-enable no-template-curly-in-string */
+  return missingInputs.map(input => `          ${(inputMap as Record<string, string>)[input]}`).join('\n')
+}