@marcusrbrown/infra 0.6.0 → 0.8.0

package/src/commands/cliproxy/setup.ts

@@ -1,52 +1,62 @@
 /// <reference types="bun" />
 
-import type {SpinnerResult} from '@clack/prompts'
 import type {goke} from 'goke'
 
-import {cancel, confirm, intro, isCancel, log, note, outro, select, spinner, text} from '@clack/prompts'
+import type {ActionCtx} from '../../lib/action-ctx'
+
+import {cancel, confirm, intro, log, note, outro, select, text} from '@clack/prompts'
 import {z} from 'zod'
 
 import {resolveManagementKey} from './config'
-import {toStringArray} from './keys'
+import {
+  applyGhValue,
+  assertGhAuthenticated,
+  assertGhInstalled,
+  assertRepoAccess,
+  createManagementApiKey,
+  deleteManagementApiKey,
+  listExistingGhNames,
+  withGhRetry,
+  withSpinner,
+} from './setup/gh'
+import {formatDryRunPreview} from './setup/preview'
+import {buildApiKeyValue, cancelAndExit, ensureRepoFormat, promptGenericSecretNames, promptValue} from './setup/prompts'
+import {parseProviders, promptForModel, promptForProviders, PROVIDER_DEFAULTS, type ProviderId} from './setup/providers'
+import {runSmokeTest} from './setup/smoke-test'
+import {
+  collectCollisions,
+  formatTemplateSummary,
+  getHarnessTemplate,
+  harnessSchema,
+  stripTrailingSlash,
+  type Harness,
+  type HarnessTemplate,
+} from './setup/templates'
+import {
+  assertProxyKeyWorks,
+  assertProxyReachable,
+  MODEL_ID_RE,
+  validateSetupOptions,
+  verifyModelsAvailable,
+} from './setup/validation'
+import {checkFroBotWorkflow, formatWorkflowSnippet} from './setup/workflow-analyzer'
+
+export {formatDryRunPreview, type DryRunPreviewOptions} from './setup/preview'
+export {validateSetupOptions, verifyModelsAvailable} from './setup/validation'
 
 const DEFAULT_CLIPROXY_URL = 'https://cliproxy.fro.bot'
-const HTTP_TIMEOUT_MS = 10_000
-const DEFAULT_OMO_PROVIDERS = 'claude-max20'
-const DEFAULT_FRO_BOT_MODEL = 'anthropic/claude-sonnet-4-6'
-
-const harnessSchema = z.enum(['opencode', 'claude-code', 'generic'])
-const ghRepoViewSchema = z.object({
-  nameWithOwner: z.string(),
-  viewerPermission: z.string(),
-})
-const ghNameListSchema = z.array(z.object({name: z.string()}))
-
-export type Harness = z.infer<typeof harnessSchema>
 
 export interface SetupOptions {
   key?: string
   repo?: string
   harness?: Harness
-}
-
-export interface SecretAssignment {
-  name: string
-  value: string
-}
-
-export interface VariableAssignment {
-  name: string
-  value: string
-}
-
-export interface HarnessTemplate {
-  secrets: SecretAssignment[]
-  variables: VariableAssignment[]
-}
-
-interface GenericSecretNames {
-  apiKeySecretName: string
-  baseUrlSecretName: string
+  /** Raw comma-separated provider list string (e.g. "anthropic,openai"). Use parseProviders() to validate. */
+  providers?: string
+  model?: string
+  force?: boolean
+  dryRun?: boolean
+  verifySmoke?: boolean
+  ackKeyReuse?: boolean
 }
 
 interface SetupPlan {
@@ -58,611 +68,63 @@ interface SetupPlan {
   template: HarnessTemplate
 }
 
-interface CommandResult {
-  stdout: string
-  stderr: string
-  exitCode: number
-}
-
-function stripTrailingSlash(value: string): string {
-  return value.endsWith('/') ? value.slice(0, -1) : value
-}
-
-function resolveBaseUrl(input?: string): string {
-  return stripTrailingSlash(input ?? process.env.CLIPROXY_URL ?? DEFAULT_CLIPROXY_URL)
-}
-
-export function validateSetupOptions(options: SetupOptions, isInteractive: boolean): void {
-  if (isInteractive) {
-    return
+// Internal: test-only DI surface. Not part of the published API.
+export interface RunSetupDeps {
+  interactive?: boolean
+  baseUrl?: string
+  ctx?: ActionCtx
+  resolveManagementKey?: typeof resolveManagementKey
+  gh?: {
+    assertGhInstalled: typeof assertGhInstalled
+    assertGhAuthenticated: typeof assertGhAuthenticated
+    assertRepoAccess: typeof assertRepoAccess
+    listExistingGhNames: typeof listExistingGhNames
+    createManagementApiKey: typeof createManagementApiKey
+    deleteManagementApiKey: typeof deleteManagementApiKey
+    applyGhValue: typeof applyGhValue
+    withGhRetry: typeof withGhRetry
   }
-
-  if (!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.')
+  prompts?: {
+    promptValue: typeof promptValue
+    confirm: typeof confirm
+    intro: typeof intro
+    note: typeof note
+    outro: typeof outro
   }
-
-  if (!options.harness) {
-    throw new Error('--harness is required when stdin is not a TTY. Choose opencode or claude-code.')
+  smoke?: {
+    runSmokeTest: typeof runSmokeTest
   }
-
-  if (options.harness === 'generic') {
-    throw new Error('--harness generic is interactive-only because it requires custom secret names.')
+  validation?: {
+    assertProxyReachable: typeof assertProxyReachable
+    assertProxyKeyWorks: typeof assertProxyKeyWorks
+    verifyModelsAvailable: typeof verifyModelsAvailable
   }
 }
 
-export function getHarnessTemplate(
-  harness: Harness,
-  values: {
-    keyValue?: string
-    baseUrl?: string
-    genericSecretNames?: GenericSecretNames
-  } = {},
-): HarnessTemplate {
-  const keyValue = values.keyValue ?? 'sk-placeholder'
-  const baseUrl = stripTrailingSlash(values.baseUrl ?? DEFAULT_CLIPROXY_URL)
-
-  if (harness === 'opencode') {
-    return {
-      secrets: [
-        {
-          name: 'OPENCODE_AUTH_JSON',
-          value: JSON.stringify({anthropic: {type: 'api', key: keyValue}}),
-        },
-        {
-          name: 'OPENCODE_CONFIG',
-          value: JSON.stringify({provider: {anthropic: {options: {baseURL: `${baseUrl}/v1`}}}}),
-        },
-        {
-          name: 'OMO_PROVIDERS',
-          value: DEFAULT_OMO_PROVIDERS,
-        },
-      ],
-      variables: [
-        {
-          name: 'FRO_BOT_MODEL',
-          value: DEFAULT_FRO_BOT_MODEL,
-        },
-      ],
-    }
-  }
-
-  if (harness === 'claude-code') {
-    return {
-      secrets: [
-        {
-          name: 'ANTHROPIC_API_KEY',
-          value: keyValue,
-        },
-      ],
-      variables: [],
-    }
-  }
-
-  if (!values.genericSecretNames) {
-    throw new Error('Generic harness requires custom secret names.')
-  }
-
-  return {
-    secrets: [
-      {name: values.genericSecretNames.apiKeySecretName, value: keyValue},
-      {name: values.genericSecretNames.baseUrlSecretName, value: `${baseUrl}/v1`},
-    ],
-    variables: [],
-  }
+function resolveBaseUrl(input?: string): string {
+  return stripTrailingSlash(input ?? process.env.CLIPROXY_URL ?? DEFAULT_CLIPROXY_URL)
 }
 
 function extractErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
-function ensureRepoFormat(value: string): string {
-  const trimmed = value.trim()
-  if (!/^[^/\s]+\/[^/\s]+$/.test(trimmed)) {
-    throw new Error('Repository must be in owner/repo format.')
-  }
-  return trimmed
-}
-
-function ensureSecretName(value: string, label: string): string {
-  const trimmed = value.trim()
-  if (!/^[A-Z][A-Z0-9_]*$/.test(trimmed)) {
-    throw new Error(`${label} must be SCREAMING_SNAKE_CASE.`)
-  }
-  return trimmed
-}
-
-function cancelAndExit(message = 'Setup cancelled.'): never {
-  cancel(message)
-  process.exit(0)
-}
-
-async function promptValue<T extends string | boolean>(
-  promise: Promise<T | symbol>,
-  cancelMessage?: string,
-): Promise<T> {
-  const value = await promise
-  if (isCancel(value)) {
-    cancelAndExit(cancelMessage)
-  }
-  return value
-}
-
-async function withSpinner<T>(message: string, run: (spinnerInstance: SpinnerResult) => Promise<T>): Promise<T> {
-  const spinnerInstance = spinner()
-  spinnerInstance.start(message)
-
-  try {
-    const result = await run(spinnerInstance)
-    spinnerInstance.stop(message)
-    return result
-  } catch (error) {
-    spinnerInstance.error(`${message} failed`)
-    throw error
-  }
-}
-
-async function runCommand(command: string, args: string[]): Promise<CommandResult> {
-  const child = Bun.spawn([command, ...args], {
-    stdout: 'pipe',
-    stderr: 'pipe',
-    env: process.env,
-  })
-
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(child.stdout).text(),
-    new Response(child.stderr).text(),
-    child.exited,
-  ])
-
-  return {stdout, stderr, exitCode}
-}
-
-async function runGh(args: string[]): Promise<CommandResult> {
-  return runCommand('gh', args)
-}
-
-export function isGhRateLimitError(text: string): boolean {
-  return /rate limit/i.test(text)
-}
-
-/**
- * Query the GitHub API rate limit reset time. The `rate_limit` endpoint is
- * exempt from rate limiting itself, so this should succeed even when the
- * primary GraphQL limit is exhausted. Returns a formatted local time string
- * or a fallback phrase when the endpoint is unreachable.
- */
-async function queryRateLimitReset(): Promise<string> {
-  try {
-    const result = await runGh(['api', 'rate_limit'])
-    if (result.exitCode === 0) {
-      const parsed = JSON.parse(result.stdout) as {
-        resources?: {graphql?: {reset?: number}; core?: {reset?: number}}
-      }
-      const reset = parsed.resources?.graphql?.reset ?? parsed.resources?.core?.reset
-      if (reset) {
-        return new Date(reset * 1000).toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'})
-      }
-    }
-  } catch {
-    // Fall through to generic phrase
-  }
-  return 'an unknown time'
-}
-
-/**
- * Run a GitHub API operation wrapped in a spinner, retrying indefinitely on
- * rate-limit errors when in interactive mode. In non-interactive mode the
- * error is re-thrown with the reset time appended so the caller can surface
- * it without prompting.
- */
-export async function withGhRetry<T>(
-  label: string,
-  fn: (spinnerInstance: SpinnerResult) => Promise<T>,
-  interactive: boolean,
-  queryReset: () => Promise<string> = queryRateLimitReset,
-): Promise<T> {
-  for (;;) {
-    try {
-      return await withSpinner(label, fn)
-    } catch (error) {
-      const message = extractErrorMessage(error)
-      if (!isGhRateLimitError(message)) {
-        throw error
-      }
-      const reset = await queryReset()
-      if (!interactive) {
-        throw new Error(`${message} — GitHub API rate limit resets at ${reset}. Re-run when ready.`)
-      }
-      log.warn(`GitHub API rate limit exceeded. Resets at ${reset}.`)
-      const retry = await promptValue(
-        confirm({
-          message: 'Retry this step when ready?',
-          active: 'retry',
-          inactive: 'abort',
-          initialValue: true,
-        }),
-        'Setup aborted after rate limit.',
-      )
-      if (!retry) {
-        cancelAndExit('Setup aborted after GitHub API rate limit.')
-      }
-    }
-  }
-}
-
-async function assertGhInstalled(): Promise<void> {
-  if (!Bun.which('gh')) {
-    throw new Error('GitHub CLI is required for cliproxy setup. Install gh first: https://cli.github.com/')
-  }
-}
-
-async function assertGhAuthenticated(): Promise<void> {
-  const result = await runGh(['auth', 'status'])
-  if (result.exitCode !== 0) {
-    throw new Error(`GitHub CLI is not authenticated. Run "gh auth login" first. ${result.stderr.trim()}`.trim())
-  }
-}
-
-async function assertRepoAccess(repo: string): Promise<void> {
-  const result = await runGh(['repo', 'view', repo, '--json', 'nameWithOwner,viewerPermission'])
-  if (result.exitCode !== 0) {
-    throw new Error(`Unable to access ${repo}. ${result.stderr.trim()}`.trim())
-  }
-
-  const parsed = ghRepoViewSchema.parse(JSON.parse(result.stdout))
-  const writePermissions = new Set(['ADMIN', 'MAINTAIN', 'WRITE'])
-
-  if (!writePermissions.has(parsed.viewerPermission)) {
-    throw new Error(
-      `GitHub CLI does not have write access to ${parsed.nameWithOwner}. Current permission: ${parsed.viewerPermission}.`,
-    )
-  }
-}
-
-async function listExistingGhNames(repo: string, kind: 'secret' | 'variable'): Promise<string[]> {
-  const result = await runGh([kind, 'list', '--repo', repo, '--json', 'name'])
-  if (result.exitCode !== 0) {
-    throw new Error(`Unable to list existing GitHub ${kind}s for ${repo}. ${result.stderr.trim()}`.trim())
-  }
-
-  return ghNameListSchema.parse(JSON.parse(result.stdout)).map(entry => entry.name)
-}
-
-export type FroBotWorkflowCheck =
-  | {kind: 'missing'}
-  | {kind: 'unreachable'; reason: string}
-  | {kind: 'no-agent-step'}
-  | {
-      kind: 'analyzed'
-      stepsWithGaps: readonly {stepOrdinal: number; missingInputs: readonly string[]}[]
-    }
-
-// 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).
-const REQUIRED_OPENCODE_INPUTS = ['auth-json', 'opencode-config', 'omo-providers', 'model'] as const
-
-/**
- * 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.
- */
-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
-}
-
-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}`,
-  }
-}
-
-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: Record<string, string> = {
-    '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 }}',
-  }
-  /* eslint-enable no-template-curly-in-string */
-  return missingInputs.map(input => `          ${inputMap[input]}`).join('\n')
-}
-
-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)}`)
-  }
-}
-
-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)}`)
-  }
-}
-
-async function requestJson(endpoint: string, init: RequestInit): Promise<unknown> {
-  const response = await fetch(endpoint, {
-    ...init,
-    signal: AbortSignal.timeout(HTTP_TIMEOUT_MS),
-  })
-
-  if (!response.ok) {
-    const body = await response.text()
-    throw new Error(`${init.method ?? 'GET'} ${endpoint} failed with HTTP ${response.status}: ${body}`)
-  }
-
-  try {
-    return await response.json()
-  } catch {
-    return null
-  }
-}
-
-function managementHeaders(key: string): Headers {
-  const headers = new Headers()
-  headers.set('x-management-key', key)
-  headers.set('content-type', 'application/json')
-  return headers
-}
-
-function buildApiKeyValue(keyName: string): string {
-  const slug = (
-    keyName
-      .trim()
-      .toLowerCase()
-      .match(/[a-z0-9]+/g) ?? []
-  )
-    .join('-')
-    .slice(0, 24)
-  const random = crypto.randomUUID().split('-').join('')
-  return `sk-${slug || 'cliproxy'}-${random}`
-}
-
-async function createManagementApiKey(baseUrl: string, managementKey: string, keyValue: string): Promise<void> {
-  const endpoint = `${baseUrl}/v0/management/api-keys`
-  const currentPayload = await requestJson(endpoint, {
-    method: 'GET',
-    headers: managementHeaders(managementKey),
-  })
-  const currentKeys = toStringArray(currentPayload)
-
-  if (currentKeys.includes(keyValue)) {
-    return
-  }
-
-  await requestJson(endpoint, {
-    method: 'PUT',
-    headers: managementHeaders(managementKey),
-    body: JSON.stringify([...currentKeys, keyValue]),
-  })
-}
-
-async function deleteManagementApiKey(baseUrl: string, managementKey: string, keyValue: string): Promise<void> {
-  const endpoint = `${baseUrl}/v0/management/api-keys`
-  const currentPayload = await requestJson(endpoint, {
-    method: 'GET',
-    headers: managementHeaders(managementKey),
-  })
-  const currentKeys = toStringArray(currentPayload)
-  const filtered = currentKeys.filter(k => k !== keyValue)
-
-  if (filtered.length === currentKeys.length) {
-    return
-  }
-
-  await requestJson(endpoint, {
-    method: 'PUT',
-    headers: managementHeaders(managementKey),
-    body: JSON.stringify(filtered),
-  })
-}
-
-async function applyGhValue(kind: 'secret' | 'variable', name: string, repo: string, value: string): Promise<void> {
-  if (kind === 'secret') {
-    const child = Bun.spawn(['gh', 'secret', 'set', name, '--repo', repo], {
-      stdin: new Blob([value]).stream(),
-      stdout: 'pipe',
-      stderr: 'pipe',
-      env: process.env,
-    })
-
-    const [stderr, exitCode] = await Promise.all([new Response(child.stderr).text(), child.exited])
-
-    if (exitCode !== 0) {
-      throw new Error(`gh secret set ${name} failed: ${stderr.trim()}`.trim())
-    }
-    return
-  }
-
-  const result = await runGh([kind, 'set', name, '--repo', repo, '--body', value])
-  if (result.exitCode !== 0) {
-    throw new Error(`gh ${kind} set ${name} failed: ${result.stderr.trim()}`.trim())
-  }
-}
-
-function formatTemplateSummary(template: HarnessTemplate): string {
-  const secretLines = template.secrets.map(secret => `- secret ${secret.name}`)
-  const variableLines = template.variables.map(variable => `- variable ${variable.name}`)
-  return [...secretLines, ...variableLines].join('\n')
-}
-
-function collectCollisions(
-  template: HarnessTemplate,
-  existingSecrets: string[],
-  existingVariables: string[],
-): string[] {
-  const collisions: string[] = []
-
-  for (const secret of template.secrets) {
-    if (existingSecrets.includes(secret.name)) {
-      collisions.push(`secret ${secret.name}`)
-    }
-  }
-
-  for (const variable of template.variables) {
-    if (existingVariables.includes(variable.name)) {
-      collisions.push(`variable ${variable.name}`)
-    }
-  }
-
-  return collisions
-}
-
-async function promptGenericSecretNames(): Promise<GenericSecretNames> {
-  const apiKeySecretName = ensureSecretName(
-    await promptValue(
-      text({
-        message: 'Name for the API key secret',
-        placeholder: 'CLIPROXY_API_KEY',
-        validate: value => {
-          try {
-            ensureSecretName(value ?? '', 'API key secret name')
-            return undefined
-          } catch (error) {
-            return extractErrorMessage(error)
-          }
-        },
-      }),
-      'Setup cancelled before choosing the generic API key secret name.',
-    ),
-    'API key secret name',
-  )
-
-  const baseUrlSecretName = ensureSecretName(
-    await promptValue(
-      text({
-        message: 'Name for the proxy base URL secret',
-        placeholder: 'CLIPROXY_BASE_URL',
-        validate: value => {
-          try {
-            ensureSecretName(value ?? '', 'Base URL secret name')
-            return undefined
-          } catch (error) {
-            return extractErrorMessage(error)
-          }
-        },
-      }),
-      'Setup cancelled before choosing the generic base URL secret name.',
-    ),
-    'Base URL secret name',
-  )
-
-  return {apiKeySecretName, baseUrlSecretName}
+// Redact a bearer token for display in interactive prompts — never show raw key values.
+// Exported for direct unit testing of the redaction contract. The redacted form is
+// what gets shown in the interactive R8 prompt; the raw key must never reach the prompt UI.
+export function redactKey(key: string): string {
+  if (key.length < 12) return 'sk-***'
+  return `${key.slice(0, 3)}***${key.slice(-4)}`
 }
 
-async function buildInteractivePlan(options: SetupOptions, baseUrl: string): Promise<SetupPlan> {
+async function buildInteractivePlan(
+  options: SetupOptions,
+  baseUrl: string,
+  promptsImpl: Required<RunSetupDeps>['prompts'],
+): Promise<SetupPlan> {
   const createKey = !options.key
   const keyName = createKey
-    ? await promptValue(
+    ? await promptsImpl.promptValue(
         text({
           message: 'Name this new CLIProxyAPI key',
           placeholder: 'my-repo-ci',
@@ -674,7 +136,7 @@ async function buildInteractivePlan(options: SetupOptions, baseUrl: string): Pro
 
   const harness =
     options.harness ??
-    (await promptValue(
+    (await promptsImpl.promptValue(
       select<Harness>({
         message: 'Choose the harness to configure',
         options: [
@@ -689,7 +151,7 @@ async function buildInteractivePlan(options: SetupOptions, baseUrl: string): Pro
   const repo = options.repo
     ? ensureRepoFormat(options.repo)
     : ensureRepoFormat(
-        await promptValue(
+        await promptsImpl.promptValue(
           text({
             message: 'Target GitHub repository',
             placeholder: 'owner/repo',
@@ -706,6 +168,14 @@ async function buildInteractivePlan(options: SetupOptions, baseUrl: string): Pro
         ),
       )
 
+  let providers: ProviderId[] | undefined
+  let model: string | undefined
+
+  if (harness === 'opencode') {
+    providers = await promptForProviders()
+    model = await promptForModel(providers)
+  }
+
   const keyValue = options.key ?? buildApiKeyValue(keyName ?? 'cliproxy')
   const genericSecretNames = harness === 'generic' ? await promptGenericSecretNames() : undefined
 
@@ -715,258 +185,501 @@ async function buildInteractivePlan(options: SetupOptions, baseUrl: string): Pro
     keyValue,
     keyName,
     createKey,
-    template: getHarnessTemplate(harness, {keyValue, baseUrl, genericSecretNames}),
+    template: getHarnessTemplate(harness, {keyValue, baseUrl, genericSecretNames, providers, model}),
   }
 }
 
-function buildNonInteractivePlan(options: SetupOptions, baseUrl: string): SetupPlan {
+/**
+ * Returns true when the provider list includes anything beyond anthropic-only.
+ * Anthropic-only repos see no behavior change (G7 invariant).
+ */
+export function requiresDestructiveProviderChangeConfirmation(providers: ProviderId[]): boolean {
+  return !(providers.length === 1 && providers[0] === 'anthropic')
+}
+
+// Deprecated: use requiresDestructiveProviderChangeConfirmation. Will be removed in a future major.
+export const mustConfirmDestructive = requiresDestructiveProviderChangeConfirmation
+
+export async function buildNonInteractivePlan(
+  options: SetupOptions,
+  baseUrl: string,
+  deps?: Pick<RunSetupDeps, 'validation'>,
+): Promise<SetupPlan> {
   const harness = harnessSchema.parse(options.harness)
   const repo = ensureRepoFormat(options.repo ?? '')
   const keyValue = options.key ?? ''
 
+  const providers: ProviderId[] = options.providers ? parseProviders(options.providers) : ['anthropic']
+
+  let model: string
+  if (options.model) {
+    model = options.model
+  } else if (providers.length === 1) {
+    model = PROVIDER_DEFAULTS[providers[0] as ProviderId]
+  } else {
+    // Unreachable: validateSetupOptions enforces model when providers.length > 1
+    throw new Error('Pass --model <provider/model-id> when selecting multiple providers.')
+  }
+
+  // --dry-run: skip verifyModelsAvailable and force check; return plan for preview
+  if (options.dryRun) {
+    return {
+      repo,
+      harness,
+      keyValue,
+      createKey: false,
+      template: getHarnessTemplate(harness, {keyValue: keyValue || 'sk-placeholder', baseUrl, providers, model}),
+    }
+  }
+
+  const verifyModels = deps?.validation?.verifyModelsAvailable ?? verifyModelsAvailable
+
+  // Destructive overwrite gate: non-anthropic-only requires --force in non-interactive mode.
+  // Check BEFORE verifyModelsAvailable to avoid a network call when the gate will reject anyway.
+  if (requiresDestructiveProviderChangeConfirmation(providers) && !options.force) {
+    throw new Error(
+      `Refusing destructive provider change on ${options.repo ?? ''} without --force. Selected providers ${providers.join(', ')} would overwrite existing GitHub secret values (OPENCODE_AUTH_JSON, OPENCODE_CONFIG, OMO_PROVIDERS, FRO_BOT_MODEL). Note: --force authorizes overwriting these GitHub secret values; it does NOT rotate the underlying CLIProxyAPI proxy bearer token (which is preserved byte-for-byte when --key is supplied).`,
+    )
+  }
+
+  await verifyModels(baseUrl, keyValue, providers, model)
+
   return {
     repo,
     harness,
     keyValue,
     createKey: false,
-    template: getHarnessTemplate(harness, {keyValue, baseUrl}),
+    template: getHarnessTemplate(harness, {keyValue, baseUrl, providers, model}),
+  }
+}
+
+// Default real implementations for DI
+const realGh: Required<RunSetupDeps>['gh'] = {
+  assertGhInstalled,
+  assertGhAuthenticated,
+  assertRepoAccess,
+  listExistingGhNames,
+  createManagementApiKey,
+  deleteManagementApiKey,
+  applyGhValue,
+  withGhRetry,
+}
+
+const realPrompts: Required<RunSetupDeps>['prompts'] = {
+  promptValue,
+  confirm,
+  intro,
+  note,
+  outro,
+}
+
+const realSmoke: Required<RunSetupDeps>['smoke'] = {
+  runSmokeTest,
+}
+
+const realValidation: Required<RunSetupDeps>['validation'] = {
+  assertProxyReachable,
+  assertProxyKeyWorks,
+  verifyModelsAvailable,
+}
+
+const realCtx: ActionCtx = {
+  console: {
+    log: (...args: unknown[]) => {
+      console.log(...args)
+    },
+    error: (...args: unknown[]) => {
+      console.error(...args)
+    },
+  },
+  process: {
+    stdout: {write: (chunk: string) => process.stdout.write(chunk)},
+    stderr: {write: (chunk: string) => process.stderr.write(chunk)},
+    exit: (code: number) => process.exit(code),
+  },
+}
+
+// Internal: test-only DI surface. Not part of the published API.
+export async function runSetupCommand(options: SetupOptions, deps: RunSetupDeps = {}): Promise<void> {
+  const interactive = deps.interactive ?? Boolean(process.stdin.isTTY)
+  const baseUrl = deps.baseUrl ?? resolveBaseUrl()
+  // ctxInjected distinguishes MCP-mounted callers (which need ctx.console.error to surface errors
+  // through the MCP transport) from bare CLI callers (where cli.ts top-level catch already logs).
+  // Without this distinction, CLI users see the error twice.
+  const ctxInjected = deps.ctx !== undefined
+  const ctx = deps.ctx ?? realCtx
+  const gh = deps.gh ?? realGh
+  const prompts = deps.prompts ?? realPrompts
+  const smoke = deps.smoke ?? realSmoke
+  const validation = deps.validation ?? realValidation
+  const mgmtKeyResolver = deps.resolveManagementKey ?? resolveManagementKey
+
+  // --dry-run: short-circuit before validation so it works with no flags.
+  // Never blocks on stdin — safe to run anywhere.
+  if (options.dryRun) {
+    const providers: ProviderId[] = options.providers ? parseProviders(options.providers) : ['anthropic']
+    const model = options.model ?? PROVIDER_DEFAULTS[providers[0] as ProviderId]
+    const harness = options.harness ?? 'opencode'
+    const repo = options.repo ?? '<repo not specified>'
+    const keyValue = options.key ?? 'sk-placeholder'
+    ctx.console.log(
+      formatDryRunPreview({
+        repo,
+        harness,
+        providers,
+        model,
+        template: getHarnessTemplate(harness, {keyValue, baseUrl, providers, model}),
+      }),
+    )
+    return
   }
-}
 
-export function registerCliproxySetup(cli: ReturnType<typeof goke>): void {
-  cli
-    .command(
-      'cliproxy setup',
-      'Interactively onboard a GitHub repository to CLIProxyAPI by creating or reusing a key and wiring the required GitHub secrets and variables.',
-    )
-    .option(
-      '--key [key]',
-      z
-        .string()
-        .describe(
-          'Existing CLIProxyAPI API key value. When provided, setup skips key creation and reuses this key for GitHub secrets.',
-        ),
-    )
-    .option(
-      '--repo [repo]',
-      z.string().describe('Target GitHub repository in owner/repo format. Skips the repository prompt when provided.'),
-    )
-    .option(
-      '--harness [harness]',
-      harnessSchema.describe(
-        'Harness template to configure. Choose opencode, claude-code, or generic. Generic remains interactive-only.',
-      ),
-    )
-    .example('# Run the interactive onboarding wizard')
-    .example('infra cliproxy setup')
-    .example('# Run non-interactively with an existing key')
-    .example('infra cliproxy setup --key sk-test --repo owner/repo --harness opencode')
-    .action(async options => {
-      const interactive = Boolean(process.stdin.isTTY)
-      const baseUrl = resolveBaseUrl()
+  validateSetupOptions(options, interactive)
 
-      validateSetupOptions(options, interactive)
+  if (interactive) {
+    prompts.intro('CLIProxyAPI setup wizard')
+  }
 
-      if (interactive) {
-        intro('CLIProxyAPI setup wizard')
-      }
+  try {
+    await withSpinner('Checking GitHub CLI availability', async () => {
+      await gh.assertGhInstalled()
+      await gh.assertGhAuthenticated()
+    })
 
-      try {
-        await withSpinner('Checking GitHub CLI availability', async () => {
-          await assertGhInstalled()
-          await assertGhAuthenticated()
-        })
+    await withSpinner('Checking CLIProxyAPI reachability', async () => {
+      await validation.assertProxyReachable(baseUrl)
+    })
 
-        await withSpinner('Checking CLIProxyAPI reachability', async () => {
-          await assertProxyReachable(baseUrl)
-        })
+    const plan = interactive
+      ? await buildInteractivePlan(options, baseUrl, prompts)
+      : await buildNonInteractivePlan(options, baseUrl, {validation})
 
-        const plan = interactive
-          ? await buildInteractivePlan(options, baseUrl)
-          : buildNonInteractivePlan(options, baseUrl)
+    if (plan.createKey) {
+      mgmtKeyResolver()
+    }
 
-        if (plan.createKey) {
-          resolveManagementKey()
-        }
+    await gh.withGhRetry(
+      `Checking GitHub access for ${plan.repo}`,
+      async () => {
+        await gh.assertRepoAccess(plan.repo)
+      },
+      interactive,
+    )
 
-        await withGhRetry(
-          `Checking GitHub access for ${plan.repo}`,
-          async () => {
-            await assertRepoAccess(plan.repo)
-          },
-          interactive,
-        )
+    if (options.key) {
+      log.info('Using the provided API key value directly. No new CLIProxyAPI key will be created.')
+    }
 
-        if (options.key) {
-          log.info('Using the provided API key value directly. No new CLIProxyAPI key will be created.')
-        }
+    if (interactive) {
+      prompts.note(
+        [
+          `Proxy: ${baseUrl}`,
+          `Repository: ${plan.repo}`,
+          `Harness: ${plan.harness}`,
+          plan.createKey ? `New key name: ${plan.keyName}` : 'Using existing key value',
+          'GitHub values to write:',
+          formatTemplateSummary(plan.template),
+        ].join('\n'),
+        'Setup summary',
+      )
 
-        if (interactive) {
-          note(
-            [
-              `Proxy: ${baseUrl}`,
-              `Repository: ${plan.repo}`,
-              `Harness: ${plan.harness}`,
-              plan.createKey ? `New key name: ${plan.keyName}` : 'Using existing key value',
-              'GitHub values to write:',
-              formatTemplateSummary(plan.template),
-            ].join('\n'),
-            'Setup summary',
-          )
+      const shouldContinue = await prompts.promptValue(
+        prompts.confirm({
+          message: 'Proceed with GitHub secret and variable updates?',
+          active: 'yes',
+          inactive: 'no',
+          initialValue: true,
+        }),
+        'Setup cancelled before applying GitHub values.',
+      )
 
-          const shouldContinue = await promptValue(
-            confirm({
-              message: 'Proceed with GitHub secret and variable updates?',
-              active: 'yes',
-              inactive: 'no',
-              initialValue: true,
-            }),
-            'Setup cancelled before applying GitHub values.',
-          )
+      if (!shouldContinue) {
+        cancelAndExit('No changes applied.')
+      }
+    }
 
-          if (!shouldContinue) {
-            cancelAndExit('No changes applied.')
-          }
+    const [existingSecrets, existingVariables] = await gh.withGhRetry(
+      'Checking existing GitHub secrets and variables',
+      async () =>
+        Promise.all([gh.listExistingGhNames(plan.repo, 'secret'), gh.listExistingGhNames(plan.repo, 'variable')]),
+      interactive,
+    )
+
+    // Key-reuse acknowledgment guard: bearer token must not appear in prompt text
+    if (options.key && existingSecrets.includes('OPENCODE_AUTH_JSON')) {
+      if (interactive) {
+        const proceed = await prompts.promptValue(
+          prompts.confirm({
+            message: `You supplied --key ${redactKey(options.key)}. Verify it matches the bearer token inside the existing OPENCODE_AUTH_JSON on ${plan.repo}. Continue?`,
+            active: 'yes',
+            inactive: 'no',
+            initialValue: false,
+          }),
+          'Setup cancelled. Run with --ack-key-reuse to bypass interactive confirmation.',
+        )
+        if (!proceed) {
+          cancelAndExit('Setup cancelled. Run with --ack-key-reuse to bypass interactive confirmation.')
         }
+      } else if (!options.ackKeyReuse) {
+        throw new Error(
+          `Refusing key-reuse without explicit acknowledgment. Pass --ack-key-reuse to confirm that --key matches the bearer token inside the existing OPENCODE_AUTH_JSON on ${plan.repo}. (The CLI cannot verify this because GitHub secrets are write-only.)`,
+        )
+      }
+    }
 
-        const [existingSecrets, existingVariables] = await withGhRetry(
-          'Checking existing GitHub secrets and variables',
-          async () =>
-            Promise.all([listExistingGhNames(plan.repo, 'secret'), listExistingGhNames(plan.repo, 'variable')]),
-          interactive,
+    const collisions = collectCollisions(plan.template, existingSecrets, existingVariables)
+
+    if (collisions.length > 0) {
+      if (!interactive && !options.force) {
+        throw new Error(
+          `Refusing to overwrite existing GitHub values in ${plan.repo}: ${collisions.join(', ')}. Pass --force to confirm. Note: --force only authorizes overwriting these GitHub secret values; it does NOT rotate the underlying CLIProxyAPI proxy bearer token (which is preserved byte-for-byte when --key is supplied).`,
         )
-        const collisions = collectCollisions(plan.template, existingSecrets, existingVariables)
+      }
 
-        if (collisions.length > 0) {
-          if (!interactive) {
-            throw new Error(
-              `Refusing to overwrite existing GitHub values in non-interactive mode: ${collisions.join(', ')}`,
-            )
-          }
+      if (!interactive && options.force) {
+        log.warn(`Overwriting existing GitHub values: ${collisions.join(', ')}`)
+        // proceed
+      }
 
-          log.warn(`Existing GitHub values will be overwritten: ${collisions.join(', ')}`)
-          const overwrite = await promptValue(
-            confirm({
-              message: 'Overwrite the existing GitHub values?',
-              active: 'overwrite',
-              inactive: 'cancel',
-              initialValue: false,
-            }),
-            'Setup cancelled instead of overwriting existing values.',
-          )
+      if (interactive) {
+        log.warn(`Existing GitHub values will be overwritten: ${collisions.join(', ')}`)
+        const overwrite = await prompts.promptValue(
+          prompts.confirm({
+            message: 'Overwrite the existing GitHub values?',
+            active: 'overwrite',
+            inactive: 'cancel',
+            initialValue: false,
+          }),
+          'Setup cancelled instead of overwriting existing values.',
+        )
 
-          if (!overwrite) {
-            cancelAndExit('Existing GitHub values left unchanged.')
-          }
+        if (!overwrite) {
+          cancelAndExit('Existing GitHub values left unchanged.')
         }
+      }
+    }
 
-        let keyCreatedByThisRun = false
-        const managementKey = plan.createKey ? resolveManagementKey() : undefined
+    let keyCreatedByThisRun = false
+    const managementKey = plan.createKey ? mgmtKeyResolver() : undefined
 
-        if (plan.createKey && managementKey) {
-          await withSpinner('Creating a new CLIProxyAPI key', async () => {
-            await createManagementApiKey(baseUrl, managementKey, plan.keyValue)
-            keyCreatedByThisRun = true
-          })
-        }
+    if (plan.createKey && managementKey) {
+      await withSpinner('Creating a new CLIProxyAPI key', async () => {
+        await gh.createManagementApiKey(baseUrl, managementKey, plan.keyValue)
+        keyCreatedByThisRun = true
+      })
+    }
 
-        try {
-          await withGhRetry(
-            'Writing GitHub secrets and variables',
-            async spinnerInstance => {
-              for (const secret of plan.template.secrets) {
-                spinnerInstance.message(`Setting secret ${secret.name}`)
-                await applyGhValue('secret', secret.name, plan.repo, secret.value)
-              }
+    try {
+      await gh.withGhRetry(
+        'Writing GitHub secrets and variables',
+        async spinnerInstance => {
+          for (const secret of plan.template.secrets) {
+            spinnerInstance.message(`Setting secret ${secret.name}`)
+            await gh.applyGhValue('secret', secret.name, plan.repo, secret.value)
+          }
 
-              for (const variable of plan.template.variables) {
-                spinnerInstance.message(`Setting variable ${variable.name}`)
-                await applyGhValue('variable', variable.name, plan.repo, variable.value)
-              }
-            },
-            interactive,
-          )
+          for (const variable of plan.template.variables) {
+            spinnerInstance.message(`Setting variable ${variable.name}`)
+            await gh.applyGhValue('variable', variable.name, plan.repo, variable.value)
+          }
+        },
+        interactive,
+      )
 
-          await withSpinner('Verifying the new key through the proxy', async () => {
-            await assertProxyKeyWorks(baseUrl, plan.keyValue)
-          })
-
-          if (plan.harness === 'opencode') {
-            const workflow = await withGhRetry(
-              `Checking ${plan.repo} fro-bot.yaml wiring`,
-              async () => {
-                return checkFroBotWorkflow(plan.repo)
-              },
-              interactive,
-            )
+      await withSpinner('Verifying the new key through the proxy', async () => {
+        await validation.assertProxyKeyWorks(baseUrl, plan.keyValue)
+      })
 
-            switch (workflow.kind) {
-              case 'missing': {
-                log.warn(
-                  `No .github/workflows/fro-bot.yaml found in ${plan.repo}. The secrets and variables are set, but Fro Bot won't run until the workflow exists and passes them as inputs. See marcusrbrown/infra/.github/workflows/fro-bot.yaml for a reference.`,
-                )
-                break
-              }
-              case 'unreachable': {
-                log.warn(
-                  `Could not check .github/workflows/fro-bot.yaml in ${plan.repo}: ${workflow.reason}. The secrets and variables are set, but the workflow wiring was not verified. Re-run 'infra cliproxy setup' later to confirm, or inspect the file directly.`,
-                )
-                break
-              }
-              case 'no-agent-step': {
-                log.warn(
-                  `${plan.repo} .github/workflows/fro-bot.yaml exists but has no 'fro-bot/agent' step. Add one that passes the secrets and variables just written. See marcusrbrown/infra/.github/workflows/fro-bot.yaml for a reference.`,
-                )
-                break
-              }
-              case 'analyzed': {
-                for (const step of workflow.stepsWithGaps) {
-                  const missing = [...step.missingInputs]
-                  log.warn(
-                    [
-                      `${plan.repo} .github/workflows/fro-bot.yaml fro-bot/agent step #${step.stepOrdinal} is missing ${missing.length} required input${
-                        missing.length > 1 ? 's' : ''
-                      } (${missing.join(', ')}).`,
-                      `Without ${missing.includes('opencode-config') ? 'opencode-config, the baseURL override is ignored and Fro Bot hits api.anthropic.com with the proxy key, which fails with 401' : 'these, the secrets you just wrote will not reach OpenCode'}.`,
-                      '',
-                      `Add under the 'with:' block of the 'fro-bot/agent' step:`,
-                      formatWorkflowSnippet(missing),
-                    ].join('\n'),
-                  )
-                }
-                break
-              }
-              default: {
-                const _exhaustive: never = workflow
-                throw new Error(`Unhandled FroBotWorkflowCheck kind: ${JSON.stringify(_exhaustive)}`)
-              }
-            }
+      if (plan.harness === 'opencode') {
+        const workflow = await gh.withGhRetry(
+          `Checking ${plan.repo} fro-bot.yaml wiring`,
+          async () => {
+            return checkFroBotWorkflow(plan.repo)
+          },
+          interactive,
+        )
+
+        switch (workflow.kind) {
+          case 'missing': {
+            log.warn(
+              `No .github/workflows/fro-bot.yaml found in ${plan.repo}. The secrets and variables are set, but Fro Bot won't run until the workflow exists and passes them as inputs. See marcusrbrown/infra/.github/workflows/fro-bot.yaml for a reference.`,
+            )
+            break
+          }
+          case 'unreachable': {
+            log.warn(
+              `Could not check .github/workflows/fro-bot.yaml in ${plan.repo}: ${workflow.reason}. The secrets and variables are set, but the workflow wiring was not verified. Re-run 'infra cliproxy setup' later to confirm, or inspect the file directly.`,
+            )
+            break
+          }
+          case 'no-agent-step': {
+            log.warn(
+              `${plan.repo} .github/workflows/fro-bot.yaml exists but has no 'fro-bot/agent' step. Add one that passes the secrets and variables just written. See marcusrbrown/infra/.github/workflows/fro-bot.yaml for a reference.`,
+            )
+            break
           }
-        } catch (mutationError) {
-          if (keyCreatedByThisRun && managementKey) {
-            try {
-              await deleteManagementApiKey(baseUrl, managementKey, plan.keyValue)
-              log.warn('Rolled back the newly created CLIProxyAPI key after failure.')
-            } catch {
+          case 'analyzed': {
+            for (const step of workflow.stepsWithGaps) {
+              const missing = [...step.missingInputs]
               log.warn(
-                'Failed to roll back the newly created CLIProxyAPI key. Remove it manually via: infra cliproxy keys remove',
+                [
+                  `${plan.repo} .github/workflows/fro-bot.yaml fro-bot/agent step #${step.stepOrdinal} is missing ${missing.length} required input${
+                    missing.length > 1 ? 's' : ''
+                  } (${missing.join(', ')}).`,
+                  `Without ${missing.includes('opencode-config') ? 'opencode-config, the baseURL override is ignored and Fro Bot hits api.anthropic.com with the proxy key, which fails with 401' : 'these, the secrets you just wrote will not reach OpenCode'}.`,
+                  '',
+                  `Add under the 'with:' block of the 'fro-bot/agent' step:`,
+                  formatWorkflowSnippet(missing),
+                ].join('\n'),
               )
             }
+            break
           }
-          throw mutationError
+          default: {
+            const _exhaustive: never = workflow
+            throw new Error(`Unhandled FroBotWorkflowCheck kind: ${JSON.stringify(_exhaustive)}`)
+          }
+        }
+      }
+    } catch (mutationError) {
+      if (keyCreatedByThisRun && managementKey) {
+        try {
+          await gh.deleteManagementApiKey(baseUrl, managementKey, plan.keyValue)
+          log.warn('Rolled back the newly created CLIProxyAPI key after failure.')
+        } catch {
+          log.warn(
+            'Failed to roll back the newly created CLIProxyAPI key. Remove it manually via: infra cliproxy keys remove',
+          )
+        }
+      }
+      throw mutationError
+    }
+
+    if (interactive) {
+      prompts.outro(`Setup complete for ${plan.repo}. The ${plan.harness} harness can now use ${baseUrl}/v1.`)
+    } else {
+      log.success(`Setup complete for ${plan.repo}.`)
+    }
+
+    // ── Smoke test (opt-in, non-blocking) ──────────────────────────────
+    if (options.verifySmoke) {
+      const smokeResult = await withSpinner('Running smoke test', async () =>
+        smoke.runSmokeTest(plan.repo, plan.template.variables.find(v => v.name === 'FRO_BOT_MODEL')?.value ?? ''),
+      ).catch(async error => {
+        // withSpinner re-throws; catch here so smoke test never gates setup
+        return {
+          kind: 'unverified' as const,
+          message: `Smoke test error: ${extractErrorMessage(error)}`,
+          runUrl: undefined,
         }
+      })
+
+      // Machine-parseable hook for MCP/agent consumers
+      ctx.console.log(`[smoke-test] kind=${smokeResult.kind}`)
 
-        if (interactive) {
-          outro(`Setup complete for ${plan.repo}. The ${plan.harness} harness can now use ${baseUrl}/v1.`)
-        } else {
-          log.success(`Setup complete for ${plan.repo}.`)
+      switch (smokeResult.kind) {
+        case 'pass': {
+          log.success(`✓ ${smokeResult.message}${smokeResult.runUrl ? ` — ${smokeResult.runUrl}` : ''}`)
+          break
+        }
+        case 'fail': {
+          log.warn(`✗ ${smokeResult.message}${smokeResult.runUrl ? ` — ${smokeResult.runUrl}` : ''}`)
+          break
         }
-      } catch (error) {
-        const message = extractErrorMessage(error)
-        if (interactive) {
-          cancel(message)
+        case 'unverified': {
+          log.warn(`⚠ ${smokeResult.message}${smokeResult.runUrl ? ` — ${smokeResult.runUrl}` : ''}`)
+          break
+        }
+        default: {
+          const _exhaustive: never = smokeResult
+          throw new Error(`Unhandled SmokeResult kind: ${JSON.stringify(_exhaustive)}`)
         }
-        throw error
       }
+    }
+  } catch (error) {
+    const message = extractErrorMessage(error)
+    // MCP-mounted callers need ctx.console.error to surface the message through the MCP transport.
+    // Bare CLI callers leave it to cli.ts's top-level catch — emitting here too would double-log.
+    if (ctxInjected) {
+      ctx.console.error(message)
+    }
+    if (interactive) {
+      cancel(message)
+    }
+    throw error
+  }
+}
+
+export function registerCliproxySetup(cli: ReturnType<typeof goke>): void {
+  cli
+    .command(
+      'cliproxy setup',
+      'Interactively onboard a GitHub repository to CLIProxyAPI by creating or reusing a key and wiring the required GitHub secrets and variables.',
+    )
+    .option(
+      '--key [key]',
+      z
+        .string()
+        .describe(
+          'Existing CLIProxyAPI API key value. When provided, setup skips key creation and reuses this key for GitHub secrets.',
+        ),
+    )
+    .option(
+      '--repo [repo]',
+      z.string().describe('Target GitHub repository in owner/repo format. Skips the repository prompt when provided.'),
+    )
+    .option(
+      '--harness [harness]',
+      harnessSchema.describe(
+        'Harness template to configure. Choose opencode, claude-code, or generic. Generic remains interactive-only.',
+      ),
+    )
+    .option(
+      '--providers [providers]',
+      z
+        .string()
+        .describe(
+          'Comma-separated list of providers to enable. Default: anthropic. Supported values: anthropic, openai. Example: --providers anthropic,openai',
+        ),
+    )
+    .option(
+      '--model [model]',
+      z
+        .string()
+        .regex(MODEL_ID_RE)
+        .describe(
+          'Override the default model. Must be provider-prefixed and lowercase. Required when multiple providers selected. Examples: anthropic/claude-sonnet-4-6, openai/gpt-4o',
+        ),
+    )
+    .option(
+      '--force',
+      z.boolean().optional().describe('Overwrite existing GitHub secrets and variables without prompting.'),
+    )
+    .option('--dry-run', z.boolean().optional().describe('Print the plan without applying any changes.'))
+    .option(
+      '--verify-smoke',
+      z.boolean().optional().describe('Run a smoke test against the proxy after setup completes.'),
+    )
+    .option(
+      '--ack-key-reuse',
+      z
+        .boolean()
+        .default(false)
+        .describe(
+          'Acknowledge that --key matches the bearer token inside the existing OPENCODE_AUTH_JSON. Required in non-interactive mode when --key is supplied for a repo with existing OPENCODE_AUTH_JSON.',
+        ),
+    )
+    .example('# Preview planned actions without applying any changes (no flags required)')
+    .example('infra cliproxy setup --dry-run')
+    .example('# Run the interactive onboarding wizard')
+    .example('infra cliproxy setup')
+    .example('# Run non-interactively with an existing key (anthropic-only)')
+    .example('infra cliproxy setup --repo owner/repo --harness opencode --key sk-existing --force')
+    .example('# Enable both providers non-interactively (requires --force and --model)')
+    .example(
+      'infra cliproxy setup --repo owner/repo --harness opencode --providers anthropic,openai --model openai/gpt-5.4-mini --key sk-existing --ack-key-reuse --force',
+    )
+    .action(async (options, ctx) => {
+      await runSetupCommand(options, {ctx})
     })
 }