gitnexushub 0.4.4 → 0.6.0

package/dist/install-ci-command.js

@@ -0,0 +1,680 @@
+/**
+ * `gnx install-ci` (v2) — opens a PR on the user's GitHub repo that
+ * adds the single Claude-led GitNexus CI workflow, using the user's
+ * local `gh` CLI rather than a Hub-side OAuth-write grant.
+ *
+ * v1 shipped three workflow files (gitnexus.yml + claude.yml +
+ * claude-code-review.yml) and a `--no-claude` opt-out. v2 collapses
+ * to one file and makes Claude mandatory: the workflow's only review
+ * mechanism is the `anthropics/claude-code-action@v1` step, primed
+ * with a pre-computed Context Pack from `Akon-Labs/gitnexus-check@v2`.
+ *
+ * Pivot rationale (unchanged from v1): we don't want the Hub to keep
+ * a write-capable GitHub token per user. Doing the GitHub write from
+ * the user's machine via `gh` keeps the Hub free of `workflow` /
+ * `repo` OAuth scopes.
+ *
+ * Flow:
+ *   1. Detect git repo + GitHub remote.
+ *   2. Resolve fullName → repoId via `GET /api/repos`.
+ *   3. POST install-ci-bundle (mints CI token, renders workflow YAML).
+ *   4. `gh` preflight (installed, authed, has `repo` scope).
+ *   5. Push branch + PUT workflow file + open PR.
+ *   6. Set GITNEXUS_TOKEN + CLAUDE_CODE_OAUTH_TOKEN secrets via stdin.
+ *
+ * The exported `runInstallCi` is the commander entry point; the
+ * GitHub-write helpers (`pushWorkflowAndOpenPr`, `setRepoSecret`)
+ * accept an injected `runGh` for unit-testability.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import pc from 'picocolors';
+import { isGitRepo, getGitRemoteUrl, parseGitRemote, matchRepo } from './project.js';
+import { warn, resolveAuth } from './cli-helpers.js';
+const WORKFLOW_PATH = '.github/workflows/gitnexus.yml';
+const COMMIT_MESSAGE = 'Install GitNexus PR review workflow';
+const PR_TITLE = 'Install GitNexus PR review workflow';
+const PR_BODY = 'Adds the GitNexus PR review workflow.\n\n' +
+    'On every PR, this workflow:\n' +
+    '\n' +
+    '1. Runs `Akon-Labs/gitnexus-check@v2` to pre-compute a Context Pack from the GitNexus knowledge graph.\n' +
+    '2. Hands that pack to `anthropics/claude-code-action@v1`, which posts a single review comment grounded in the graph.\n' +
+    '\n' +
+    'Merge to enable on every PR. Two repository secrets are required:\n' +
+    '\n' +
+    '- `GITNEXUS_TOKEN` — set by `gnx install-ci`\n' +
+    '- `CLAUDE_CODE_OAUTH_TOKEN` — set by `gnx install-ci` if a local Claude Code login is detected\n';
+// ─── Entry point ─────────────────────────────────────────────────────
+/**
+ * Entry point for `gnx install-ci`. Imported by index.ts so commander
+ * has a stable handle.
+ *
+ * Output is structured as 6 numbered steps with a final boxed summary.
+ * The styling matches the v1 install-ci output that the user explicitly
+ * called out as "polished" — we keep the visual contract.
+ */
+export async function runInstallCi(opts) {
+    const t0 = Date.now();
+    const { api } = await resolveAuth(undefined, opts.hub);
+    // ── Step 1: Detect the local repo ──────────────────────────────────
+    const step1 = beginStep(1, 6, 'Detecting repository');
+    if (!isGitRepo()) {
+        step1.failExit('Not in a git repository. cd into your project root and try again.');
+    }
+    const remoteUrl = getGitRemoteUrl();
+    if (!remoteUrl) {
+        step1.failExit('No git remote named "origin". Add a GitHub remote and try again.');
+    }
+    const fullName = parseGitRemote(remoteUrl);
+    if (!fullName) {
+        step1.failExit(`Could not parse a GitHub repo from origin: ${pc.dim(remoteUrl)}`, 'Only github.com URLs are supported (HTTPS or SSH).');
+    }
+    const [owner, repoName] = fullName.split('/');
+    step1.done(pc.bold(fullName));
+    // ── Step 2: Find the repo on the Hub ───────────────────────────────
+    const step2 = beginStep(2, 6, 'Looking up repo on Hub');
+    let hubRepoId;
+    try {
+        const hubRepos = await api.listRepos();
+        const hubRepo = matchRepo(fullName, hubRepos);
+        if (!hubRepo) {
+            step2.failExit(`Repo ${pc.bold(fullName)} is not indexed by your Hub.`, `Index it first via the Hub UI, then re-run ${pc.cyan('gnx install-ci')}.`);
+        }
+        hubRepoId = hubRepo.id;
+        step2.done(`indexed (id ${pc.dim(hubRepoId.slice(0, 8))})`);
+    }
+    catch (err) {
+        if (err instanceof StepExited)
+            throw err;
+        step2.failExit(`Hub lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // ── Step 3: gh CLI preflight ───────────────────────────────────────
+    const step3 = beginStep(3, 6, 'Checking gh CLI');
+    if (!hasGh()) {
+        step3.fail('`gh` not found in PATH.');
+        console.error('');
+        console.error(`    ${pc.bold('Install:')}`);
+        console.error(`      macOS:    ${pc.cyan('brew install gh')}`);
+        console.error(`      Linux:    ${pc.cyan('https://github.com/cli/cli/blob/trunk/docs/install_linux.md')}`);
+        console.error(`      Windows:  ${pc.cyan('winget install --id GitHub.cli')}`);
+        console.error('');
+        console.error(`    Then authenticate: ${pc.cyan('gh auth login')}`);
+        console.error('');
+        console.error(`    ${pc.dim('GitNexus uses your gh CLI to push the workflow PR + set secrets,')}`);
+        console.error(`    ${pc.dim('so the Hub never needs OAuth-write access to your GitHub repos.')}`);
+        console.error('');
+        return process.exit(1);
+    }
+    if (!ghIsAuthed()) {
+        step3.failExit('`gh` is installed but not authenticated.', `Run: ${pc.cyan('gh auth login')}`);
+    }
+    const missingScope = ghMissingScope();
+    if (missingScope) {
+        step3.failExit(`\`gh\` missing the ${pc.bold(missingScope)} scope.`, `Add it with: ${pc.cyan(`gh auth refresh -h github.com -s ${missingScope}`)}`);
+    }
+    step3.done('authenticated, scope ok');
+    // ── Step 4: Mint CI token + render workflow YAML ───────────────────
+    const step4 = beginStep(4, 6, 'Minting CI token');
+    let bundle;
+    try {
+        bundle = await api.installCiBundle(hubRepoId);
+    }
+    catch (err) {
+        step4.failExit(`Hub rejected install-ci: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // Hub emits both token and ciToken as the same value for back-compat;
+    // prefer ciToken (named for intent). Fall back to token for any future
+    // Hub build that drops the alias.
+    const ciToken = bundle.ciToken || bundle.token;
+    if (!ciToken) {
+        step4.failExit('Hub returned an install-ci-bundle with no token. Contact support.');
+        return;
+    }
+    if (!bundle.workflowYaml) {
+        step4.failExit('Hub returned an install-ci-bundle with no workflow YAML. Contact support.');
+        return;
+    }
+    step4.done(`token ${pc.dim(ciToken.slice(0, 12) + '...')}`);
+    // ── Step 5: Push branch + workflow file + open PR ──────────────────
+    const branchName = `gitnexus/install-ci-${Date.now()}`;
+    const step5 = beginStep(5, 6, 'Pushing workflow PR');
+    let pushResult;
+    try {
+        step5.progress(`branch ${pc.dim(branchName)}, file ${pc.dim(WORKFLOW_PATH)}`);
+        pushResult = await pushWorkflowAndOpenPr({
+            owner,
+            repo: repoName,
+            branchName,
+            workflowYaml: bundle.workflowYaml,
+            runGh: defaultGhRunner,
+        });
+    }
+    catch (err) {
+        step5.fail(`failed to push workflow: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`    ${pc.dim('You can rerun safely — the Hub mints fresh tokens each run.')}`);
+        console.error('');
+        return process.exit(1);
+    }
+    if (pushResult.alreadyInstalled) {
+        step5.done(`already installed — ${pc.cyan(pushResult.prUrl)}`);
+    }
+    else {
+        step5.done(pc.cyan(pushResult.prUrl));
+    }
+    // ── Step 6: Set GitHub Actions secrets ─────────────────────────────
+    const step6 = beginStep(6, 6, 'Setting Actions secrets');
+    let gnxSecretSet = false;
+    try {
+        step6.progress(`writing ${pc.bold('GITNEXUS_TOKEN')}...`);
+        await setRepoSecret(defaultGhRunner, fullName, 'GITNEXUS_TOKEN', ciToken);
+        gnxSecretSet = true;
+    }
+    catch (err) {
+        step6.subFail(`GITNEXUS_TOKEN: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let claudeSecretSet = false;
+    let claudeSkipReason = null;
+    const claudeToken = readClaudeOAuthToken({
+        claudeToken: opts.claudeToken,
+        claudeTokenFile: opts.claudeTokenFile,
+    });
+    if (!claudeToken) {
+        claudeSkipReason = 'no-token-provided';
+    }
+    else {
+        try {
+            step6.progress('writing CLAUDE_CODE_OAUTH_TOKEN...');
+            await setRepoSecret(defaultGhRunner, fullName, 'CLAUDE_CODE_OAUTH_TOKEN', claudeToken);
+            claudeSecretSet = true;
+        }
+        catch (err) {
+            claudeSkipReason = 'gh-failed';
+            step6.subFail(`CLAUDE_CODE_OAUTH_TOKEN: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    step6.done(`GITNEXUS_TOKEN ${gnxSecretSet ? '✓' : '✗'}, CLAUDE_CODE_OAUTH_TOKEN ${claudeSecretSet ? '✓' : '⚠'}`);
+    // Hard-fail when we couldn't set the Claude secret at all (no token
+    // provided AND no gh failure to recover from). v2 mandates a Claude
+    // review; shipping an install where the workflow can't authenticate
+    // is worse than asking the user to come back with a token.
+    if (!claudeSecretSet && claudeSkipReason === 'no-token-provided') {
+        console.error('');
+        console.error(`  ${pc.red('✗')}  ${pc.bold('Claude OAuth token required')}`);
+        console.error('');
+        console.error(`     ${pc.dim('GitNexus CI uses Claude to post the PR review. Set up once:')}`);
+        console.error('');
+        console.error(`       ${pc.bold('1.')} Run: ${pc.cyan('claude setup-token')}`);
+        console.error(`       ${pc.bold('2.')} Copy the printed token`);
+        console.error(`       ${pc.bold('3.')} Re-run ${pc.cyan('gnx install-ci')} with one of:`);
+        console.error('');
+        console.error(`            ${pc.dim('# preferred — set once in your shell rc')}`);
+        console.error(`            ${pc.cyan('export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...')}`);
+        console.error(`            ${pc.cyan('gnx install-ci')}`);
+        console.error('');
+        console.error(`            ${pc.dim('# or one-shot via flag (leaks to shell history)')}`);
+        console.error(`            ${pc.cyan('gnx install-ci --claude-token=sk-ant-oat01-...')}`);
+        console.error('');
+        console.error(`            ${pc.dim('# or via file (e.g. for ops scripts)')}`);
+        console.error(`            ${pc.cyan('gnx install-ci --claude-token-file=~/.config/claude-ci-token')}`);
+        console.error('');
+        console.error(`     ${pc.dim('The CI gnx_ token is already minted on the Hub; re-running is safe.')}`);
+        console.error('');
+        process.exit(1);
+    }
+    // ── Final summary box ─────────────────────────────────────────────
+    const elapsedSec = ((Date.now() - t0) / 1000).toFixed(1);
+    printSummaryBox({
+        repo: fullName,
+        branch: branchName,
+        prUrl: pushResult.prUrl,
+        gnxSecretSet,
+        claudeSecretSet,
+        claudeSkipReason,
+        rawCiToken: ciToken,
+        alreadyInstalled: pushResult.alreadyInstalled,
+        elapsedSec,
+    });
+}
+// ─── Output helpers ──────────────────────────────────────────────────
+/**
+ * Sentinel thrown by `failExit` so callers can distinguish a "we
+ * intentionally exited" signal from real surprises. We never actually
+ * see the throw because `process.exit(1)` runs first — but typescript
+ * needs `never` and we want a real `Error` instance for any test that
+ * stubs `process.exit`.
+ */
+class StepExited extends Error {
+    constructor() {
+        super('Step exited');
+        this.name = 'StepExited';
+    }
+}
+function beginStep(n, total, title) {
+    const tag = pc.dim(`[${n}/${total}]`);
+    console.log('');
+    console.log(`${tag} ${pc.bold(title)}...`);
+    const t0 = Date.now();
+    return {
+        progress(msg) {
+            console.log(`        ${pc.dim('↳')} ${pc.dim(msg)}`);
+        },
+        done(suffix) {
+            const elapsed = `${((Date.now() - t0) / 1000).toFixed(1)}s`;
+            console.log(`${tag} ${pc.green('✓')} ${pc.bold(title)} ${pc.dim('— ' + suffix)} ${pc.dim(`(${elapsed})`)}`);
+        },
+        fail(msg) {
+            console.log(`${tag} ${pc.red('✗')} ${pc.bold(title)} ${pc.red('— ' + msg)}`);
+        },
+        failExit(msg, hint) {
+            console.log(`${tag} ${pc.red('✗')} ${pc.bold(title)} ${pc.red('— ' + msg)}`);
+            if (hint) {
+                console.error('');
+                console.error(`        ${hint}`);
+            }
+            console.error('');
+            process.exit(1);
+            // unreachable in production; needed for `never` in tests that stub exit.
+            throw new StepExited();
+        },
+        subFail(msg) {
+            console.log(`        ${pc.red('✗')} ${msg}`);
+        },
+    };
+}
+/**
+ * Final recap. Plain horizontal-rule layout + aligned key/value pairs;
+ * avoids ANSI-aware column math (which is fragile across picocolors
+ * versions). The "table" is rendered for the secrets list so the
+ * status column lines up; everything else is plain indented text that
+ * still reads cleanly when ANSI colour is stripped.
+ */
+function printSummaryBox(s) {
+    const hr = pc.dim('─'.repeat(60));
+    console.log('');
+    console.log(hr);
+    if (s.alreadyInstalled) {
+        console.log(`  ${pc.cyan('●')}  ${pc.bold(`Already installed (verified in ${s.elapsedSec}s)`)}`);
+    }
+    else {
+        console.log(`  ${pc.green('✔')}  ${pc.bold(`Setup complete in ${s.elapsedSec}s`)}`);
+    }
+    console.log(hr);
+    console.log('');
+    const kv = (k, v) => `  ${pc.dim(k.padEnd(10))}${v}`;
+    console.log(kv('Repo', pc.bold(s.repo)));
+    console.log(kv('Branch', pc.dim(s.branch)));
+    console.log(kv('PR', pc.cyan(s.prUrl)));
+    console.log('');
+    printTable([pc.bold('Secret'), pc.bold('Status')], [
+        ['GITNEXUS_TOKEN', s.gnxSecretSet ? pc.green('✓ set') : pc.red('✗ failed')],
+        [
+            'CLAUDE_CODE_OAUTH_TOKEN',
+            s.claudeSecretSet
+                ? pc.green('✓ set')
+                : s.claudeSkipReason === 'no-token-provided'
+                    ? pc.yellow('⚠ creds not found')
+                    : pc.red('✗ failed'),
+        ],
+    ]);
+    console.log('');
+    console.log(`  ${pc.bold('Next:')} review and merge ${pc.cyan(s.prUrl)}.`);
+    console.log(`         The workflow will run automatically on every PR — Claude posts a review comment grounded in your GitNexus graph.`);
+    console.log('');
+    if (!s.gnxSecretSet) {
+        warn('GITNEXUS_TOKEN secret not set. Run manually:');
+        console.error(`    ${pc.cyan('gh secret set')} GITNEXUS_TOKEN ${pc.cyan('--repo')} ${s.repo}`);
+        console.error(`    ${pc.dim(`# paste: ${s.rawCiToken}`)}`);
+        console.error('');
+        warn('Token will not be shown again — re-run `gnx install-ci` to mint a fresh one.');
+        console.log('');
+    }
+    if (!s.claudeSecretSet) {
+        if (s.claudeSkipReason === 'no-token-provided') {
+            console.log(`  ${pc.yellow('!')} ${pc.bold('Claude review:')} ${pc.dim('no Claude Code credentials found locally.')}`);
+            console.log(`     1. Run ${pc.cyan('claude setup-token')} (one-time, requires Claude Pro/Max)`);
+            console.log(`     2. Re-run ${pc.cyan('gnx install-ci')} — token picked up automatically`);
+            console.log(`     ${pc.dim('Or set CLAUDE_CODE_OAUTH_TOKEN manually:')} ${pc.cyan(`gh secret set CLAUDE_CODE_OAUTH_TOKEN --repo ${s.repo}`)}`);
+        }
+        else if (s.claudeSkipReason === 'gh-failed') {
+            console.log(`  ${pc.yellow('!')} ${pc.bold('Claude review:')} ${pc.dim('CLAUDE_CODE_OAUTH_TOKEN not set. Run manually:')}`);
+            console.log(`    ${pc.cyan('gh secret set')} CLAUDE_CODE_OAUTH_TOKEN ${pc.cyan('--repo')} ${s.repo}`);
+        }
+        console.log('');
+    }
+}
+/** Strip ANSI CSI (`\x1b[<...>m`) so column widths line up under colour. */
+function visibleWidth(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+function printTable(header, rows) {
+    const cols = header.length;
+    const widths = new Array(cols).fill(0);
+    for (let c = 0; c < cols; c++)
+        widths[c] = visibleWidth(header[c]);
+    for (const row of rows) {
+        for (let c = 0; c < cols; c++) {
+            widths[c] = Math.max(widths[c], visibleWidth(row[c] ?? ''));
+        }
+    }
+    const pad = (s, w) => s + ' '.repeat(Math.max(0, w - visibleWidth(s)));
+    const top = '  ' + pc.dim('┌─' + widths.map((w) => '─'.repeat(w)).join('─┬─') + '─┐');
+    const mid = '  ' + pc.dim('├─' + widths.map((w) => '─'.repeat(w)).join('─┼─') + '─┤');
+    const bot = '  ' + pc.dim('└─' + widths.map((w) => '─'.repeat(w)).join('─┴─') + '─┘');
+    const line = (cells) => '  ' +
+        pc.dim('│ ') +
+        cells.map((cell, i) => pad(cell, widths[i])).join(pc.dim(' │ ')) +
+        pc.dim(' │');
+    console.log(top);
+    console.log(line(header));
+    console.log(mid);
+    for (const row of rows)
+        console.log(line(row));
+    console.log(bot);
+}
+// ─── gh CLI helpers ──────────────────────────────────────────────────
+function hasGh() {
+    try {
+        execFileSync('gh', ['--version'], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ghIsAuthed() {
+    try {
+        execFileSync('gh', ['auth', 'status'], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the missing scope name (e.g. "repo") if the active gh auth
+ * session lacks one we need, else null. We check `repo` only — that
+ * scope covers everything install-ci does:
+ *   - push branches & file content (Contents API)
+ *   - open PRs (Pulls API)
+ *   - read+write Actions secrets (`repo` is sufficient for repo-level
+ *     secrets; only org-level secrets need `admin:org`)
+ *
+ * Falls back to "no missing scope" if we can't parse `gh auth status`
+ * — better to let the real call surface the real error than block on
+ * a parser misfire across gh versions.
+ */
+export function ghMissingScope() {
+    let stderr = '';
+    try {
+        execFileSync('gh', ['auth', 'status'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        const e = err;
+        stderr = String(e.stderr ?? '') + String(e.stdout ?? '');
+    }
+    if (!stderr) {
+        try {
+            stderr = execFileSync('gh', ['auth', 'status'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+    const m = stderr.match(/Token scopes:\s*([^\n]+)/i);
+    if (!m)
+        return null;
+    const scopes = m[1]
+        .split(/[,\s]+/)
+        .map((s) => s.replace(/['"]/g, '').trim())
+        .filter(Boolean);
+    if (!scopes.some((s) => s === 'repo'))
+        return 'repo';
+    return null;
+}
+/**
+ * Read the user's Claude Code OAuth token from local credentials so
+ * we can auto-set CLAUDE_CODE_OAUTH_TOKEN as a GitHub Actions secret
+ * — the same source Claude Code's own `/install-github-app` reads.
+ *
+ * Lookup order (descending preference — first hit wins):
+ *
+ *   1. `opts.claudeToken` from `--claude-token=<value>` (lowest priority,
+ *      flagged for completeness — leaks to argv / `ps` / shell history).
+ *   2. `opts.claudeTokenFile` from `--claude-token-file=<path>` — reads
+ *      the file's trimmed contents. Keeps the token off argv.
+ *   3. `process.env.CLAUDE_CODE_OAUTH_TOKEN` — the documented happy path.
+ *      User runs `claude setup-token` once, exports the result via shell
+ *      rc, then `gnx install-ci` picks it up automatically on every run.
+ *
+ * Why we no longer auto-detect from `~/.claude/.credentials.json`: that
+ * file's `claudeAiOauth.accessToken` is the user's *interactive session*
+ * token (~1h expiry, refreshed in-band). It is NOT a valid CI OAuth
+ * token — those are minted explicitly by `claude setup-token` and have
+ * the longer-lived headless scope set the GHA expects. Live testing on
+ * deer-flow PR #11 confirmed: shipping the session token to the GHA
+ * causes "Could not resolve auth credentials" inside the bundled
+ * Anthropic SDK. Better to fail loud with a clear instruction than to
+ * silently set the wrong token.
+ *
+ * Returns the trimmed token if any source yields one; null otherwise.
+ * The caller prints a clear "run `claude setup-token` first" instruction
+ * on null and exits non-zero rather than shipping a half-installed CI.
+ */
+export function readClaudeOAuthToken(opts) {
+    if (opts.claudeToken && opts.claudeToken.trim().length > 0) {
+        return opts.claudeToken.trim();
+    }
+    if (opts.claudeTokenFile) {
+        try {
+            const raw = fs.readFileSync(opts.claudeTokenFile, 'utf-8').trim();
+            if (raw.length > 0)
+                return raw;
+        }
+        catch {
+            // File unreadable / missing — fall through to env var.
+        }
+    }
+    const envToken = process.env.CLAUDE_CODE_OAUTH_TOKEN;
+    if (envToken && envToken.trim().length > 0) {
+        return envToken.trim();
+    }
+    return null;
+}
+/**
+ * Default `gh` runner — shells out via execFileSync. Captures stdout
+ * + stderr separately so callers can inspect each. When `input` is set,
+ * pipes it to stdin (used for `gh secret set` so secret material never
+ * lands in argv or process listings). Translates non-zero exit into a
+ * thrown Error whose message is the stderr text, matching the contract
+ * tests expect.
+ */
+export const defaultGhRunner = async (args, opts = {}) => {
+    try {
+        const stdout = execFileSync('gh', args, {
+            encoding: 'utf-8',
+            stdio: opts.input !== undefined ? ['pipe', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+            input: opts.input,
+        });
+        return { stdout, stderr: '', code: 0 };
+    }
+    catch (err) {
+        const e = err;
+        const stderr = typeof e.stderr === 'string'
+            ? e.stderr
+            : e.stderr instanceof Buffer
+                ? e.stderr.toString()
+                : '';
+        throw new Error(stderr.trim() || e.message || 'gh command failed');
+    }
+};
+/**
+ * Set a repository-level Actions secret without ever putting the value
+ * in argv. `gh secret set NAME --repo OWNER/REPO` reads the secret
+ * value from stdin when neither `--body` nor `--body-file` is set —
+ * documented behavior across all supported gh versions.
+ *
+ * (We deliberately avoid `--body-file -`. That flag was added later
+ * than our minimum supported gh version; older installs reject it as
+ * "unknown flag" and crash the install-ci flow even though the
+ * underlying API supports stdin natively.)
+ */
+export async function setRepoSecret(runGh, fullName, name, value) {
+    await runGh(['secret', 'set', name, '--repo', fullName], { input: value });
+}
+/**
+ * Push the workflow file to `branchName` and open a PR.
+ *
+ * Idempotency:
+ *   - If `branchName` already exists we keep using it (gh's create-branch
+ *     fails with "Reference already exists" — caught and ignored).
+ *   - If the workflow file is already present with byte-identical
+ *     content AND a matching PR is already open from this head, we
+ *     mark `alreadyInstalled = true` and skip the PUT + create-PR
+ *     calls. The branch name embeds a timestamp so practical retries
+ *     never collide, but tests inject a fixed branch name to drive
+ *     this code path.
+ *   - If the file exists with different content, we PUT with the
+ *     existing sha so it's an update.
+ *   - If a PR creation returns 422 (duplicate), we fall back to the
+ *     `pulls?head=...&state=all` lookup and surface that URL.
+ *
+ * `runGh` is injected so tests can drive the full idempotency matrix
+ * without spawning a real `gh`.
+ */
+export async function pushWorkflowAndOpenPr(args) {
+    const { owner, repo, branchName, workflowYaml, runGh } = args;
+    const ownerRepo = `${owner}/${repo}`;
+    // 1. Default branch + base sha.
+    const repoInfoRaw = await runGh(['api', `repos/${ownerRepo}`]);
+    const repoInfo = JSON.parse(repoInfoRaw.stdout);
+    const defaultBranch = repoInfo.default_branch;
+    const baseRefRaw = await runGh(['api', `repos/${ownerRepo}/git/ref/heads/${defaultBranch}`]);
+    const baseRef = JSON.parse(baseRefRaw.stdout);
+    const baseSha = baseRef.object.sha;
+    // 2. Create the branch (idempotent).
+    let branchAlreadyExists = false;
+    try {
+        await runGh([
+            'api',
+            `repos/${ownerRepo}/git/refs`,
+            '--method',
+            'POST',
+            '-f',
+            `ref=refs/heads/${branchName}`,
+            '-f',
+            `sha=${baseSha}`,
+        ]);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : '';
+        if (!/already exists|Reference.+exists/i.test(msg))
+            throw err;
+        branchAlreadyExists = true;
+    }
+    // 3. Check existing file content. If it's byte-identical AND the branch
+    //    pre-existed, we're in the no-op path. Otherwise we PUT (update or
+    //    create).
+    let existingSha;
+    let existingContentMatches = false;
+    try {
+        const existingRaw = await runGh([
+            'api',
+            `repos/${ownerRepo}/contents/${WORKFLOW_PATH}?ref=${branchName}`,
+        ]);
+        const existing = JSON.parse(existingRaw.stdout);
+        existingSha = existing.sha;
+        if (existing.encoding === 'base64' && existing.content) {
+            const decoded = Buffer.from(existing.content, 'base64').toString('utf-8');
+            if (decoded === workflowYaml)
+                existingContentMatches = true;
+        }
+    }
+    catch (err) {
+        // 404 — file doesn't exist on this branch yet, leave existingSha undefined.
+        const msg = err instanceof Error ? err.message : '';
+        if (!/Not Found|404/i.test(msg))
+            throw err;
+    }
+    // 4. PUT the file unless content matches and we're idempotent-no-oping.
+    let skipWrite = false;
+    if (branchAlreadyExists && existingContentMatches) {
+        skipWrite = true;
+    }
+    if (!skipWrite) {
+        const writeArgs = [
+            'api',
+            `repos/${ownerRepo}/contents/${WORKFLOW_PATH}`,
+            '--method',
+            'PUT',
+            '-f',
+            `branch=${branchName}`,
+            '-f',
+            `message=${COMMIT_MESSAGE}`,
+            '-f',
+            `content=${Buffer.from(workflowYaml).toString('base64')}`,
+        ];
+        if (existingSha) {
+            writeArgs.push('-f', `sha=${existingSha}`);
+        }
+        await runGh(writeArgs);
+    }
+    // 5. Open PR (or surface existing). Always look up state=all on 422 so
+    //    a closed-but-not-merged PR doesn't trigger an unhelpful crash.
+    const createPrArgs = [
+        'api',
+        `repos/${ownerRepo}/pulls`,
+        '--method',
+        'POST',
+        '-f',
+        `title=${PR_TITLE}`,
+        '-f',
+        `head=${branchName}`,
+        '-f',
+        `base=${defaultBranch}`,
+        '-f',
+        `body=${PR_BODY}`,
+    ];
+    let prUrl;
+    let prAlreadyExisted = false;
+    try {
+        const createdRaw = await runGh(createPrArgs);
+        prUrl = JSON.parse(createdRaw.stdout).html_url;
+    }
+    catch (err) {
+        // Always try the fallback list query — gh's stderr formatting
+        // varies across versions for 422 / "duplicate", so we don't
+        // regex-match the message; we just look up state=all and trust
+        // GitHub. If no existing PR is found we re-throw the original.
+        try {
+            const listRaw = await runGh([
+                'api',
+                `repos/${ownerRepo}/pulls?head=${owner}:${branchName}&state=all`,
+            ]);
+            const list = JSON.parse(listRaw.stdout);
+            if (list[0]) {
+                prUrl = list[0].html_url;
+                prAlreadyExisted = true;
+            }
+            else {
+                throw err;
+            }
+        }
+        catch (fallbackErr) {
+            // Surface the original error rather than the fallback's parse error.
+            throw err;
+        }
+    }
+    return {
+        prUrl,
+        alreadyInstalled: skipWrite && prAlreadyExisted,
+    };
+}