mandrel 1.57.0

package/.agents/scripts/agents-bootstrap-github.js

@@ -0,0 +1,634 @@
+/* node:coverage ignore file */
+/**
+ * agents-bootstrap-github — Idempotent Label & Field Setup
+ *
+ * Creates the required label taxonomy and project board custom fields
+ * for the v5 Epic-centric flow on a target GitHub repo. Idempotent —
+ * skips resources that already exist.
+ *
+ * Usage:
+ *   node .agents/scripts/agents-bootstrap-github.js
+ *
+ * Reads the canonical config from .agentrc.json via the config resolver,
+ * then uses the provider factory to instantiate the correct provider.
+ *
+ * @see docs/v5-implementation-plan.md Sprint 1C
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { applyBranchProtection } from './lib/bootstrap/branch-protection.js';
+import {
+  CI_WORKFLOW_RELATIVE_PATH,
+  renderCiWorkflow,
+} from './lib/bootstrap/ci-workflow-template.js';
+import {
+  compareSemver,
+  MIN_GH_VERSION,
+  parseGhVersion,
+  preflightGh,
+  preflightRuntimeDeps,
+} from './lib/bootstrap/gh-preflight.js';
+import { confirm as defaultHitlConfirm } from './lib/bootstrap/hitl-confirm.js';
+import { applyMergeMethods } from './lib/bootstrap/merge-methods.js';
+import { printSummary } from './lib/bootstrap/summary.js';
+import {
+  auditProjectWorkflows,
+  formatAuditSummary,
+  reapConflictingWorkflows,
+  resolveProjectIdByNumber,
+} from './lib/bootstrap/workflow-audit.js';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  GhAuthError,
+  GhNotInstalledError,
+  GhVersionError,
+  MissingRuntimeDepsError,
+} from './lib/errors/index.js';
+import { Logger } from './lib/Logger.js';
+import {
+  LABEL_TAXONOMY,
+  PROJECT_FIELD_DEFS,
+  PROJECT_VIEW_DEFS,
+  STATUS_FIELD_OPTIONS,
+} from './lib/label-taxonomy.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const PROJECTS_DOC_POINTER =
+  'See docs/project-board.md for the manual Projects V2 setup checklist.';
+
+/**
+ * Detect that an error is a not-found / 404 signal across the surfaces
+ * the provider can emit. The `gh-exec` classifier wraps the CLI's
+ * "could not resolve to a" / "HTTP 404" / "not found" stderr in a
+ * `GhNotFoundError` whose message is the literal string
+ * `gh-exec: resource not found` — the `'404'` substring is absent. The
+ * legacy bespoke-client path produced `failed (404):` messages. Match
+ * both so a legitimate fresh-repo run (issue #1 doesn't exist yet)
+ * doesn't fatal-fail the preflight.
+ */
+function isApiAccessNotFoundError(err) {
+  if (!err) return false;
+  if (err.name === 'GhNotFoundError') return true;
+  const message = err.message ?? '';
+  const stderr = err.stderr ?? '';
+  return (
+    /\b404\b/.test(message) ||
+    /\b404\b/.test(stderr) ||
+    /resource not found/i.test(message) ||
+    /resource not found/i.test(stderr) ||
+    /\bnot found\b/i.test(stderr) ||
+    /could not resolve to a/i.test(stderr)
+  );
+}
+
+async function verifyApiAccess(provider) {
+  try {
+    await provider.getTicket(1);
+  } catch (err) {
+    // Not-found is fine — API reachable, issue #1 doesn't exist on the
+    // target repo. Anything else (auth, scope, transport) is fatal.
+    if (!isApiAccessNotFoundError(err)) {
+      throw new Error(
+        `[bootstrap] API access verification failed: ${err.message}`,
+      );
+    }
+  }
+}
+
+async function ensureLabels(provider, log) {
+  log(`[bootstrap] Ensuring ${LABEL_TAXONOMY.length} labels...`);
+  const labels = await provider.ensureLabels(LABEL_TAXONOMY);
+  const missing = Array.isArray(labels.missing) ? labels.missing : [];
+  log(
+    `[bootstrap] Labels — created: ${labels.created.length}, skipped: ${labels.skipped.length}, missing: ${missing.length}`,
+  );
+  if (labels.created.length > 0) {
+    log(`[bootstrap]   Created: ${labels.created.join(', ')}`);
+  }
+  if (missing.length > 0) {
+    log(
+      `[bootstrap] ⚠️  ${missing.length} label(s) were reported as created/skipped but are NOT present on the remote: ${missing.join(', ')}. Re-run bootstrap or create them manually with \`gh label create\`.`,
+    );
+  }
+  return labels;
+}
+
+async function resolveProject(provider, providerConfig, log) {
+  const fallback = (scopesMissing) => ({
+    projectNumber: providerConfig?.projectNumber ?? null,
+    created: false,
+    skipped: true,
+    scopesMissing,
+  });
+  try {
+    const result = await provider.resolveOrCreateProject();
+    if (result.scopesMissing) {
+      log(
+        `[bootstrap] Projects V2: token lacks the "project" scope — skipping board provisioning. ${PROJECTS_DOC_POINTER}`,
+      );
+      return fallback(true);
+    }
+    const projectNumber = result.projectNumber ?? null;
+    const created = !!result.created;
+    log(
+      `[bootstrap] ${created ? 'Created' : 'Using'} Project V2 #${projectNumber}.`,
+    );
+    return { projectNumber, created, skipped: false, scopesMissing: false };
+  } catch (err) {
+    log(
+      `[bootstrap] Projects V2 resolution failed: ${err.message}. ${PROJECTS_DOC_POINTER}`,
+    );
+    return fallback(false);
+  }
+}
+
+async function ensureStatusField(provider, log) {
+  try {
+    const statusField = await provider.ensureStatusField(STATUS_FIELD_OPTIONS);
+    if (statusField.status === 'scopes-missing') {
+      log(
+        `[bootstrap] Projects V2 Status field: insufficient scopes. ${PROJECTS_DOC_POINTER}`,
+      );
+    } else {
+      const addedSuffix = statusField.added.length
+        ? ` (added: ${statusField.added.join(', ')})`
+        : '';
+      log(`[bootstrap] Status field — ${statusField.status}${addedSuffix}`);
+    }
+    return statusField;
+  } catch (err) {
+    log(`[bootstrap] Status field provisioning failed: ${err.message}`);
+    return { status: 'skipped', added: [] };
+  }
+}
+
+async function ensureViews(provider, log) {
+  try {
+    const views = await provider.ensureProjectViews(PROJECT_VIEW_DEFS);
+    if (views.unavailable) {
+      log(
+        `[bootstrap] Projects V2 Views unavailable — skipped ${views.skipped.join(', ')}.${views.error ? ` (${views.error})` : ''} ${PROJECTS_DOC_POINTER}`,
+      );
+    } else {
+      log(
+        `[bootstrap] Views — created: ${views.created.length}, skipped: ${views.skipped.length}`,
+      );
+    }
+    return views;
+  } catch (err) {
+    log(`[bootstrap] Views provisioning failed: ${err.message}`);
+    return { created: [], skipped: [], unavailable: false };
+  }
+}
+
+/**
+ * Audit the project's built-in workflows and, when explicitly opted-in
+ * via `--reap-conflicting-workflows`, delete the ones that race against
+ * the orchestrator's `ColumnSync` writes. Default behaviour is
+ * advisory: warn loudly with the operator-driven remediation hint, do
+ * not mutate. Story #2845.
+ *
+ * Returns a structured envelope the bootstrap summary renders, even
+ * when the audit was skipped (no projectId) so callers don't need a
+ * separate "did this run" guard.
+ *
+ * @param {object} provider
+ * @param {number} projectNumber
+ * @param {boolean} reap
+ * @param {(line: string) => void} log
+ */
+async function auditAndOptionallyReapWorkflows(
+  provider,
+  projectNumber,
+  reap,
+  log,
+) {
+  let projectId = null;
+  try {
+    projectId = await resolveProjectIdByNumber({ provider, projectNumber });
+  } catch (err) {
+    log(
+      `[bootstrap] Workflow audit: could not resolve project id — ${err.message}.`,
+    );
+    return { skipped: true, reason: 'project-id-unresolved' };
+  }
+  if (!projectId) {
+    log(
+      `[bootstrap] Workflow audit: project #${projectNumber} not visible to viewer — skipping.`,
+    );
+    return { skipped: true, reason: 'project-not-visible' };
+  }
+  let audit;
+  try {
+    audit = await auditProjectWorkflows({ provider, projectId });
+  } catch (err) {
+    log(`[bootstrap] Workflow audit failed: ${err.message} — skipping.`);
+    return { skipped: true, reason: 'audit-failed', error: err.message };
+  }
+  log(`[bootstrap] Workflow audit — ${formatAuditSummary(audit)}.`);
+  if (audit.conflicting.length === 0) {
+    return { audit, reaped: [], action: 'no-conflicts' };
+  }
+  const names = audit.conflicting.map((w) => w.name).join(', ');
+  if (!reap) {
+    log(
+      `[bootstrap] ⚠️ Conflicting workflows enabled: ${names}. ` +
+        `These race against the orchestrator's ColumnSync writes and ` +
+        `typically leave closed Stories stuck at "In Progress" on the ` +
+        `board (see Story #2813 for the reproduction). Remediation: ` +
+        `(a) re-run with --reap-conflicting-workflows to delete them, ` +
+        `or (b) toggle them off in the GitHub UI under ` +
+        `Project → Workflows. The orchestrator's post-merge ` +
+        `resync-status-column.js CLI defends against both unless you ` +
+        `also disable that step.`,
+    );
+    return { audit, reaped: [], action: 'warn-only' };
+  }
+  log(
+    `[bootstrap] Reaping ${audit.conflicting.length} conflicting workflow(s): ${names}...`,
+  );
+  const { reaped } = await reapConflictingWorkflows({ provider, audit });
+  log(
+    `[bootstrap] ✅ Deleted ${reaped.length} workflow(s): ${reaped.map((r) => r.name).join(', ')}.`,
+  );
+  return { audit, reaped, action: 'reaped' };
+}
+
+async function ensureProjectFields(provider, project, log) {
+  log(
+    `[bootstrap] Ensuring ${PROJECT_FIELD_DEFS.length} project fields on project #${project.projectNumber}...`,
+  );
+  const fields = await provider.ensureProjectFields(PROJECT_FIELD_DEFS);
+  log(
+    `[bootstrap] Fields — created: ${fields.created.length}, skipped: ${fields.skipped.length}`,
+  );
+  return fields;
+}
+
+/**
+ * Create or additively-merge branch protection on `baseBranch` (typically
+ * `main`) so the `delivery.quality.prGate.checks` suite is required
+ * before merge. Behaviour rules:
+ *
+ *   - `enforceBranchProtection: false` → skip, log the opt-out, return a
+ *     `{ status: 'skipped' }` summary.
+ *   - `prGate.checks` empty or absent → skip with a clear log, since there
+ *     is nothing to enforce.
+ *   - Existing protection rule → preserve every existing required-check
+ *     context and append only the missing prGate names.
+ *   - No existing rule → create a fresh one carrying just the prGate
+ *     contexts plus minimal sensible defaults (strict status checks).
+ *
+ * Errors (insufficient scopes, repo permission denied, etc.) are logged
+ * and return a `{ status: 'failed' }` summary so the bootstrap CLI
+ * surfaces a non-fatal warning rather than aborting the entire run —
+ * matching how the project-board provisioning steps degrade.
+ */
+async function ensureMainBranchProtection(
+  provider,
+  { baseBranch, prGate },
+  log,
+) {
+  if (prGate?.enforceBranchProtection === false) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': skipped (delivery.quality.prGate.enforceBranchProtection=false).`,
+    );
+    return { status: 'skipped', reason: 'opt-out' };
+  }
+
+  const checkNames = (prGate?.checks ?? [])
+    .map((c) => c?.name)
+    .filter((n) => typeof n === 'string' && n.length > 0);
+  if (checkNames.length === 0) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': skipped (no prGate.checks configured).`,
+    );
+    return { status: 'skipped', reason: 'no-checks' };
+  }
+
+  try {
+    const result = await provider.setBranchProtection(baseBranch, {
+      contexts: checkNames,
+    });
+    const verb = result.created ? 'Created' : 'Updated';
+    const addedSuffix = result.added.length
+      ? ` (added: ${result.added.join(', ')})`
+      : ' (all required checks already present)';
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': ${verb} rule${addedSuffix}.`,
+    );
+    return { status: result.created ? 'created' : 'merged', ...result };
+  } catch (err) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': failed — ${err.message}. Proceeding without it.`,
+    );
+    return { status: 'failed', reason: err.message };
+  }
+}
+
+/**
+ * Render the stabilized-quality-gates CI workflow template into a project
+ * checkout. Idempotent on the byte level: when `.github/workflows/ci.yml`
+ * already matches the rendered template, no write occurs and the action is
+ * `unchanged`. When the file is absent the action is `created`. When the
+ * file exists with operator-authored differences the helper preserves it
+ * and returns `custom-workflow-skip` along with the rendered body so the
+ * bootstrap caller (or `/agents-update`) can offer a side-by-side diff.
+ *
+ * Network-free; safe to invoke under tests with a tmp `projectRoot`.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot - Repo root (must contain or accept
+ *   `.github/workflows/`).
+ * @param {object} [args.template] - Forwarded to `renderCiWorkflow`.
+ * @param {boolean} [args.write=true] - When `false`, the helper computes
+ *   the would-be action without touching disk. Used by the
+ *   bootstrap CLI's dry-run mode.
+ * @returns {{ action: 'created'|'unchanged'|'custom-workflow-skip',
+ *             path: string, rendered: string }}
+ */
+export function ensureCiWorkflow(args) {
+  const projectRoot = args.projectRoot;
+  const rendered = renderCiWorkflow(args.template);
+  const target = path.join(projectRoot, CI_WORKFLOW_RELATIVE_PATH);
+  if (!fs.existsSync(target)) {
+    if (args.write !== false) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, rendered, 'utf8');
+    }
+    return { action: 'created', path: target, rendered };
+  }
+  const existing = fs.readFileSync(target, 'utf8');
+  if (existing === rendered) {
+    return { action: 'unchanged', path: target, rendered };
+  }
+  return { action: 'custom-workflow-skip', path: target, rendered };
+}
+
+/**
+ * Run the idempotent bootstrap sequence.
+ *
+ * Accepts the canonical resolved config (output of `resolveConfig()` —
+ * `config.github` holds the GitHub provider block). Epic #2880 removed the
+ * legacy shim parameters; see `.agents/rules/git-conventions.md#contract-cutovers-—-no-shim-layer`.
+ *
+ * Consent-first install (Story #3526, Feature #3515, Epic #3438): every
+ * mutation this function performs — labels, Projects V2, branch protection,
+ * merge methods — is the irreversible `github-admin` phase group from the
+ * mutation manifest. The whole sequence is now **explicit opt-in**: unless
+ * `opts.githubAdminApproved === true`, `runBootstrap` short-circuits before
+ * touching the provider and issues **zero** GitHub mutations. This is the
+ * boundary-level enforcement of the consent signal the `bootstrap.js`
+ * orchestrator threads from `parseAndValidate` (interactive operator
+ * confirmation, `--assume-yes`, or `--approve-github-admin`) down through
+ * `executeGithubBootstrap`: a direct caller cannot silently reconfigure a
+ * repo by skipping that consent. Even additive branch-protection /
+ * merge-method changes that
+ * previously applied without a prompt are gated — they are enumerated in the
+ * manifest's `github-admin` group and only land once that group is approved.
+ *
+ * @param {object} config - Resolved config wrapper with a `github` block.
+ * @param {{
+ *   token?: string,
+ *   quiet?: boolean,
+ *   providerOverride?: object,
+ *   project?: object,
+ *   github?: object,
+ *   baseBranch?: string,
+ *   githubAdminApproved?: boolean,
+ * }} [opts] - `githubAdminApproved` MUST be `true` for any GitHub mutation to
+ *   occur; any other value (absent / `false`) is treated as "not approved"
+ *   and the run is a verified no-op.
+ */
+export async function runBootstrap(config, opts = {}) {
+  // Explicit opt-in gate (Story #3526). Default-deny: absent or non-`true`
+  // approval issues zero GitHub mutations and returns a no-op envelope the
+  // CLI summary renders as a skip. The provider is never instantiated, so a
+  // non-approved run performs no network I/O at all.
+  if (opts.githubAdminApproved !== true) {
+    const skipLog = opts.quiet ? () => {} : Logger.info;
+    skipLog(
+      '[bootstrap] GitHub-admin mutations skipped: github-admin phase group not approved (explicit opt-in required).',
+    );
+    return { skipped: true, reason: 'github-admin-not-approved' };
+  }
+
+  const provider =
+    opts.providerOverride ?? createProvider(config, { token: opts.token });
+  const log = opts.quiet ? () => {} : Logger.info;
+  const providerName = config.provider ?? (config.github ? 'github' : null);
+  const providerConfig = providerName ? config[providerName] : null;
+
+  log('[bootstrap] Starting idempotent setup...');
+  log(`[bootstrap] Provider: ${providerName}`);
+  log(`[bootstrap] Target: ${providerConfig?.owner}/${providerConfig?.repo}`);
+
+  log('[bootstrap] Verifying API access...');
+  await verifyApiAccess(provider);
+  log('[bootstrap] API access verified.');
+
+  const labels = await ensureLabels(provider, log);
+  const project = await resolveProject(provider, providerConfig, log);
+
+  const projectReady = !project.skipped && project.projectNumber;
+  let statusField = { status: 'skipped', added: [] };
+  let views = { created: [], skipped: [], unavailable: false };
+  let fields = { created: [], skipped: [] };
+
+  if (projectReady) {
+    statusField = await ensureStatusField(provider, log);
+    views = await ensureViews(provider, log);
+    fields = await ensureProjectFields(provider, project, log);
+  } else {
+    log('[bootstrap] No active project — skipping legacy project-field setup.');
+  }
+
+  // Story #2845 — audit project workflows for the ones that race against
+  // the orchestrator's ColumnSync writes (notably `Pull request merged`
+  // and `Pull request linked to issue`, which both rewrite Status as a
+  // side-effect of auto-merge). When `--reap-conflicting-workflows` is
+  // set, also delete the offenders via `deleteProjectV2Workflow` (the
+  // only programmatic action GraphQL exposes today — `enabled` is
+  // read-only).
+  const workflowAudit = projectReady
+    ? await auditAndOptionallyReapWorkflows(
+        provider,
+        project.projectNumber,
+        opts.reapConflictingWorkflows === true,
+        log,
+      )
+    : { skipped: true, reason: 'no-project' };
+
+  // Consumer-facing bootstrap promotes the framework's CI-gates-only
+  // stance: branch protection with enforce_admins + 0-approval-count and
+  // the squash-only merge-method allowlist. Behavior-shifting drift on
+  // either step routes through the HITL confirm gate — non-TTY runs abort
+  // with a clear stderr message rather than silently apply.
+  //
+  // The legacy `ensureMainBranchProtection` helper is preserved (re-
+  // exported below) so the Epic #1142 Story #1157 contract tests stay
+  // green; `applyBranchProtection` is its consumer-parity successor.
+  // Post-reshape: bootstrap reads from the new `project` + `github` blocks
+  // exclusively. The legacy "agent settings" opt was removed in Epic #2880.
+  const projectCfg = opts.project ?? config.project ?? {};
+  const githubCfg = opts.github ?? {};
+  const settings = {
+    ...projectCfg,
+    baseBranch: opts.baseBranch ?? projectCfg.baseBranch ?? 'main',
+    github: githubCfg,
+    // Preserve the legacy `quality` shape pointer when callers still pass it.
+    quality: projectCfg.quality,
+  };
+  const hitlConfirm =
+    opts.hitlConfirm ??
+    ((args) =>
+      defaultHitlConfirm(args, {
+        assume: opts.assumeYes ? 'yes' : opts.assumeNo ? 'no' : undefined,
+      }));
+
+  const branchProtection = await applyBranchProtection({
+    provider,
+    settings,
+    hitlConfirm,
+    log,
+  });
+  const mergeMethods = await applyMergeMethods({
+    provider,
+    settings,
+    hitlConfirm,
+    log,
+  });
+
+  log('[bootstrap] Done.');
+  return {
+    labels,
+    fields,
+    project,
+    statusField,
+    views,
+    workflowAudit,
+    branchProtection,
+    mergeMethods,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // Preflight `gh` before touching config or the provider — surfaces the
+  // most common new-adopter failure (missing/stale `gh`) as the first
+  // diagnostic instead of an ENOENT later in the provider stack.
+  // Tech Spec #1350 → "Bootstrap surface": gh auth status must exit 0
+  // before bootstrap proceeds.
+  try {
+    const { version } = await preflightGh();
+    Logger.info(`[bootstrap] gh CLI ${version} ready (auth verified).`);
+  } catch (err) {
+    if (
+      err instanceof GhNotInstalledError ||
+      err instanceof GhAuthError ||
+      err instanceof GhVersionError
+    ) {
+      Logger.error(`[bootstrap] ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Preflight runtime deps before the dynamic config-resolver import so
+  // a green-field consumer who skipped `/agents-bootstrap-project` gets
+  // a workflow hint instead of a raw `ERR_MODULE_NOT_FOUND`.
+  try {
+    await preflightRuntimeDeps();
+  } catch (err) {
+    if (err instanceof MissingRuntimeDepsError) {
+      Logger.error(`[bootstrap] ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  // Dynamic import to avoid circular dependency issues at module level.
+  const { resolveConfig, validateOrchestrationConfig } = await import(
+    './lib/config-resolver.js'
+  );
+
+  const config = resolveConfig();
+
+  if (!config.github) {
+    throw new Error('[bootstrap] No "github" block found in .agentrc.json.');
+  }
+
+  try {
+    validateOrchestrationConfig(config);
+  } catch (err) {
+    Logger.error(`[bootstrap] ERROR: ${err.message}`);
+    process.exit(1);
+  }
+
+  const installWorkflows = process.argv.includes('--install-workflows');
+  // Epic #1235 Story 5 — flags let CI / non-interactive callers pin the
+  // HITL gate's answer deterministically. The bootstrap is non-interactive
+  // by default in non-TTY contexts (the gate returns false and aborts);
+  // these flags are the documented escape hatches.
+  const assumeYes = process.argv.includes('--assume-yes');
+  const assumeNo = process.argv.includes('--assume-no');
+  // Story #2845 — opt-in destructive flag. When set, the workflow-audit
+  // step calls `deleteProjectV2Workflow` for every conflicting built-in
+  // (e.g. "Pull request merged", "Pull request linked to issue"). Default
+  // is warn-only because the GraphQL mutation is irreversible.
+  const reapConflictingWorkflows = process.argv.includes(
+    '--reap-conflicting-workflows',
+  );
+  // Story #3526 — GitHub-admin mutations are explicit opt-in. The standalone
+  // CLI must carry an unambiguous approval signal before any remote mutation
+  // lands: either `--approve-github-admin` (the dedicated consent flag) or
+  // `--assume-yes` (the existing "accept everything" escape hatch). Without
+  // one of these, `runBootstrap` short-circuits to a verified no-op so a bare
+  // invocation never silently reconfigures branch protection or merge methods.
+  const githubAdminApproved =
+    assumeYes || process.argv.includes('--approve-github-admin');
+
+  try {
+    const result = await runBootstrap(config, {
+      installWorkflows,
+      project: config.project,
+      github: config.github,
+      assumeYes,
+      assumeNo,
+      reapConflictingWorkflows,
+      githubAdminApproved,
+    });
+    // A non-approved run returns the skip envelope (no full result shape);
+    // the skip line is already logged inside runBootstrap, so render the
+    // detailed summary only when mutations were actually attempted.
+    if (result.skipped) {
+      Logger.info(
+        `[bootstrap] GitHub-admin step skipped (${result.reason}). Re-run with --approve-github-admin (or --assume-yes) to apply.`,
+      );
+    } else {
+      printSummary(result);
+    }
+  } catch (err) {
+    throw new Error(`[bootstrap] runBootstrap failed: ${err.message}`);
+  }
+}
+
+// Re-export internal helpers for test consumers (no production caller imports them).
+// Re-export the gh-preflight surface so existing test consumers can keep
+// importing it from this module after the Story #3349 split.
+export {
+  compareSemver,
+  ensureMainBranchProtection,
+  isApiAccessNotFoundError,
+  MIN_GH_VERSION,
+  parseGhVersion,
+  preflightGh,
+  preflightRuntimeDeps,
+  verifyApiAccess,
+};
+
+runAsCli(import.meta.url, main, { source: 'Bootstrap' });