@kya-os/cli 1.7.0 → 1.8.3

package/dist/commands/init-stages.js

@@ -0,0 +1,684 @@
+import chalk from "chalk";
+import ora from "ora";
+import { existsSync } from "fs";
+import { join } from "path";
+import { openUrlInBrowser, pollForClaimStatus, } from "../utils/cli-kit/index.js";
+import { EnvManager } from "../utils/env-manager.js";
+import { writeAgentMetadata } from "../utils/dco/agent-metadata.js";
+import { patchIdentityDidInPlace } from "../utils/identity-heal.js";
+import { isValidSlug } from "../utils/dco/paths.js";
+import { installDependency } from "../utils/dependency-installer.js";
+import { shouldInstallDependency } from "../utils/should-install-dependency.js";
+import { runToolReadinessGate, } from "../utils/tool-readiness.js";
+import { detectPlatform } from "../utils/platform-detector.js";
+import { AGENT_DETECTION_TABLE } from "../utils/agent-detector.js";
+import { runAgentProfileStage, } from "../utils/agent-profile-stage.js";
+import { createRegisterAgentIdentity, } from "../utils/register-agent-identity.js";
+import { mergeReviewRegistry } from "../utils/review-registry-writer.js";
+import { isGhAuthenticated, isGhInstalled, getGhUser } from "../utils/dco/github.js";
+import { cliEffects, EffectTrigger } from "../effects/cli-integration.js";
+import { moduleExists, StageFatalError, } from "../utils/init/pipeline.js";
+import { readHubConfig } from "../utils/hub-config.js";
+import { readStoredCredential } from "../utils/github-credential.js";
+import { readPendingAnchor } from "../orchestrator/github-credential-anchor-sender.js";
+import { runGithubCredentialStage, } from "../utils/github-credential-stage.js";
+// Only "github" and "hub" actually have "already configured, skip unless
+// forced" branches for --reconfigure to bypass (githubStage/hubStage below,
+// via reconfiguring()). readiness/identity/claim run unconditionally on
+// every invocation already (nothing for --reconfigure to force), and
+// profiles' own idempotency lives inside runAgentProfileStage with no
+// force/reconfigure parameter of its own -- listing them here would accept
+// `--reconfigure profiles` (etc.) as a "known stage" that silently does
+// nothing, worse than the "not a known stage" warning it'd otherwise get.
+export const RECONFIGURABLE_STAGES = ["github", "hub"];
+export function isReconfigurableStage(value) {
+    return RECONFIGURABLE_STAGES.includes(value);
+}
+const AGENT_KIND_VALUES = AGENT_DETECTION_TABLE.map((row) => row.kind);
+function isAgentKind(value) {
+    return AGENT_KIND_VALUES.includes(value);
+}
+/** Parses --profiles into valid AgentKinds; unknown tokens are dropped. */
+export function parseProfilesFlag(raw) {
+    if (!raw)
+        return undefined;
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(isAgentKind);
+}
+export function printToolReadinessSummary(checks) {
+    console.log(chalk.bold("🔧 Tool Readiness"));
+    for (const check of checks) {
+        if (check.found && (check.tool !== "gh" || check.authenticated)) {
+            console.log(`   ${chalk.green("✓")} ${check.tool}${check.version ? ` (${check.version})` : ""}`);
+        }
+        else if (check.found) {
+            console.log(`   ${chalk.yellow("⚠")} ${check.tool}: ${check.installHint}`);
+        }
+        else {
+            console.log(`   ${chalk.yellow("⚠")} ${check.tool} not found: ${check.installHint}`);
+        }
+    }
+}
+function printMcpModuleMissingError() {
+    console.error(chalk.red("Error: MCP-I module not available. Please ensure @kya-os/mcp-i is installed."));
+    console.error(chalk.yellow("Run: npm install @kya-os/mcp-i"));
+}
+// Cached across calls within the same process, exactly as init.ts did
+// before this refactor -- CI validation may run before @kya-os/mcp-i is
+// built, so the dynamic import can fail on the first `init()` call in a
+// process and succeed on a later one once the workspace is built; once it
+// succeeds, later calls in the SAME process reuse the resolved module
+// instead of importing it again.
+let cachedEnableMCPIdentityCLI = null;
+/**
+ * Loads @kya-os/mcp-i's enableMCPIdentityCLI, offering to install it on
+ * failure (P14 commit 1).
+ */
+async function loadMcpIdentityModule(options, isTTY) {
+    try {
+        const mcpModule = await import("@kya-os/mcp-i");
+        return mcpModule.enableMCPIdentityCLI;
+    }
+    catch {
+        const confirmInstall = async (message) => {
+            const inquirer = (await import("inquirer")).default;
+            const { answer } = await inquirer.prompt([
+                { type: "confirm", name: "answer", message, default: true },
+            ]);
+            return answer;
+        };
+        const wantsInstall = await shouldInstallDependency({ install: options.install, yes: options.yes }, isTTY, confirmInstall);
+        if (wantsInstall) {
+            const install = await installDependency({
+                packageManager: detectPlatform().packageManager,
+                packageName: "@kya-os/mcp-i",
+            });
+            if (install.success) {
+                try {
+                    const mcpModule = await import("@kya-os/mcp-i");
+                    return mcpModule.enableMCPIdentityCLI;
+                }
+                catch {
+                    // Retry failed: fall through to the terminal error below.
+                }
+            }
+        }
+        printMcpModuleMissingError();
+        throw new StageFatalError(1, "MCP-I module not available");
+    }
+}
+/** Whether `--reconfigure <stage>` targets exactly this stage. */
+function reconfiguring(ctx, stage) {
+    return ctx.options.reconfigure === stage;
+}
+/**
+ * Reads a value a prior stage MUST have already set on `ctx`, given the
+ * fixed order `INIT_STAGES` below runs in. `InitStageContext`'s later
+ * fields are typed optional because the pipeline populates them
+ * progressively; before this refactor they were plain local variables in
+ * one function body, sequentially assigned and narrowed by TypeScript's
+ * own control-flow analysis, which a shared mutable context loses. A bare
+ * `!` assertion would silently turn a future stage-ordering mistake (e.g.
+ * `claimStage` moved before `identityStage` in `INIT_STAGES`) into an
+ * opaque "Cannot read properties of undefined" deep inside whichever
+ * stage read the missing field; this throws a message that names the
+ * actual invariant that broke instead.
+ */
+function requireStageValue(value, fieldName, stageName) {
+    if (value === undefined) {
+        throw new Error(`Internal error: the "${stageName}" stage requires ctx.${fieldName} to already be set by an earlier stage. Check INIT_STAGES's order in init-stages.ts.`);
+    }
+    return value;
+}
+/** Stage 1: readiness checks (git/gh/claude) and the @kya-os/mcp-i self-install. */
+export const readinessStage = {
+    name: "readiness",
+    when: () => true,
+    run: async (ctx) => {
+        const readiness = await runToolReadinessGate({ interactive: ctx.isTTY });
+        printToolReadinessSummary(readiness.checks);
+        if (readiness.fatalMissing.length > 0) {
+            console.log(chalk.red(`\n❌ Required tool missing: ${readiness.fatalMissing.join(", ")}. Install it and re-run.`));
+            throw new StageFatalError(1, `Required tool missing: ${readiness.fatalMissing.join(", ")}`);
+        }
+        ctx.readiness = readiness;
+        console.log(chalk.bold("\n📋 Agent Configuration"));
+        console.log(`   Name: ${ctx.options.name || "Auto-generated"}`);
+        console.log(`   Platform: ${ctx.platform}`);
+        if (ctx.options.description) {
+            console.log(`   Description: ${ctx.options.description}`);
+        }
+        if (ctx.options.repository) {
+            console.log(`   Repository: ${ctx.options.repository}`);
+        }
+        const enableMCPIdentity = cachedEnableMCPIdentityCLI ??
+            (await loadMcpIdentityModule(ctx.options, ctx.isTTY));
+        cachedEnableMCPIdentityCLI = enableMCPIdentity;
+        ctx.enableMCPIdentity = enableMCPIdentity;
+        const warnings = readiness.checks
+            .filter((c) => !c.found || (c.tool === "gh" && !c.authenticated))
+            .map((c) => `${c.tool}: ${c.installHint}`);
+        return {
+            ok: true,
+            summaryLine: `Tool readiness: ${readiness.checks.filter((c) => c.found).length}/${readiness.checks.length} found.`,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    },
+};
+/** Stage 2: project identity and registration (existing behavior, unchanged). */
+/** The registration call's progress reporter: spinner text plus the CLI effects. */
+function buildOnProgressHandler(spinner) {
+    return async (event) => {
+        switch (event.stage) {
+            case "checking_existing":
+                spinner.text = "Checking for existing identity...";
+                break;
+            case "generating_keys":
+                spinner.text = "Generating cryptographic keys...";
+                await cliEffects.showEffect(EffectTrigger.AGENT_IDENTITY_CREATE, `🤖 Generating Agent Identity\nCreating cryptographic keys...`, { skipExitPrompt: true });
+                break;
+            case "registering":
+                spinner.text = "Registering with Know-That-AI...";
+                await cliEffects.showEffect(EffectTrigger.DID_GENERATION, `🔐 Registering Agent\nConnecting to Know-That-AI...`, { skipExitPrompt: true });
+                break;
+            case "saving":
+                spinner.text = "Saving identity...";
+                break;
+            case "complete":
+                spinner.succeed("Identity created successfully!");
+                break;
+        }
+    };
+}
+/**
+ * The identity adapter mints a local PLACEHOLDER did (shape
+ * did:web:localhost:3000:agents:<8hex>) before registration even happens;
+ * only a claim URL + server-assigned slug mean registration actually
+ * completed and the registry has a real did:web record to resolve. Heals
+ * `.mcpi/identity.json` in place (when present) so the placeholder never
+ * outlives registration, and returns the DID every later stage/write must
+ * treat as authoritative from here on.
+ */
+function healPlaceholderDid(result, options) {
+    const registrationSucceeded = Boolean(result.metadata.claimUrl && result.metadata.agentSlug);
+    let canonicalDid = null;
+    if (registrationSucceeded &&
+        !options.local &&
+        isValidSlug(result.metadata.agentSlug ?? "")) {
+        try {
+            const registryBaseUrl = options.endpoint || "https://knowthat.ai";
+            const parsedRegistryUrl = new URL(registryBaseUrl);
+            if (parsedRegistryUrl.protocol === "https:") {
+                canonicalDid = `did:web:${parsedRegistryUrl.hostname}:agents:${result.metadata.agentSlug}`;
+            }
+        }
+        catch {
+            // Malformed --endpoint: fall back to the placeholder did rather than
+            // guess at a host.
+        }
+    }
+    let effectiveDid = result.identity.did;
+    if (canonicalDid) {
+        const identityFilePath = join(process.cwd(), ".mcpi", "identity.json");
+        if (existsSync(identityFilePath)) {
+            try {
+                patchIdentityDidInPlace(identityFilePath, canonicalDid);
+                effectiveDid = canonicalDid;
+            }
+            catch (error) {
+                if (options.verbose) {
+                    console.warn(chalk.yellow(`\n⚠️  Could not heal .mcpi/identity.json did: ${error.message}`));
+                }
+            }
+        }
+    }
+    return effectiveDid;
+}
+/** Persists the new identity's secrets to `.env.local`, new identities only. */
+async function saveEnvVariables(result, effectiveDid, options) {
+    if (!(result.metadata.isNewIdentity && !options.skipRegistration))
+        return;
+    try {
+        const envManager = new EnvManager();
+        await envManager.updateEnvFile(".env.local", {
+            AGENT_PRIVATE_KEY: result.identity.privateKey,
+            AGENT_DID: effectiveDid,
+            AGENT_PUBLIC_KEY: result.identity.publicKey,
+            AGENT_KEY_ID: result.identity.kid,
+            KYA_VOUCHED_API_KEY: "", // Will be set when agent is claimed
+            ...(result.metadata.agentId && {
+                AGENT_ID: result.metadata.agentId,
+            }),
+            ...(result.metadata.agentSlug && {
+                AGENT_SLUG: result.metadata.agentSlug,
+            }),
+        });
+        if (options.verbose) {
+            console.log(chalk.gray("\n✅ Environment variables saved to .env.local"));
+        }
+    }
+    catch (error) {
+        if (options.verbose) {
+            console.warn(chalk.yellow("\n⚠️  Could not save environment variables:", error.message));
+        }
+    }
+}
+/** Persists public agent metadata (no secrets) to `.mcpi/agent.json`. */
+function persistAgentMetadata(result, effectiveDid, agentName, options) {
+    const slug = result.metadata.agentSlug;
+    if (!(!options.skipRegistration && slug))
+        return;
+    try {
+        const registryBase = options.local
+            ? "http://localhost:3000"
+            : options.endpoint || "https://knowthat.ai";
+        writeAgentMetadata(process.cwd(), {
+            id: result.metadata.agentId,
+            slug,
+            name: agentName,
+            url: `${registryBase}/agents/${slug}`,
+            did: effectiveDid,
+            claimUrl: result.metadata.claimUrl,
+            registeredAt: new Date().toISOString(),
+        });
+    }
+    catch (error) {
+        console.warn(chalk.yellow(`\n⚠️  Could not write .mcpi/agent.json: ${error.message}`));
+    }
+}
+export const identityStage = {
+    name: "identity",
+    when: () => true,
+    run: async (ctx) => {
+        const options = ctx.options;
+        const enableMCPIdentity = requireStageValue(ctx.enableMCPIdentity, "enableMCPIdentity", "identity");
+        const spinner = ora("Setting up agent identity...").start();
+        // Default the agent name once and use it for BOTH registration and the
+        // persisted agent.json, so the display name always matches what was
+        // registered (never the slug). Uses || (not ??) so an empty --name also
+        // falls back, matching register.ts's default.
+        const agentName = options.name || "MCP-I Agent";
+        ctx.agentName = agentName;
+        try {
+            const result = await enableMCPIdentity({
+                name: agentName,
+                description: options.description,
+                repository: options.repository,
+                endpoint: options.local ? "http://localhost:3000" : options.endpoint,
+                logLevel: options.verbose ? "info" : "silent",
+                skipRegistration: options.skipRegistration,
+                onProgress: buildOnProgressHandler(spinner),
+            });
+            if (result.metadata.isNewIdentity) {
+                await cliEffects.showEffect(EffectTrigger.OPERATION_SUCCESS, `✅ Agent Identity Created\n\nDID: ${result.identity.did}`, { skipExitPrompt: true });
+            }
+            const effectiveDid = healPlaceholderDid(result, options);
+            await saveEnvVariables(result, effectiveDid, options);
+            persistAgentMetadata(result, effectiveDid, agentName, options);
+            ctx.registrationResult = result;
+            ctx.effectiveDid = effectiveDid;
+            return {
+                ok: true,
+                summaryLine: result.metadata.isNewIdentity
+                    ? `Identity created (did: ${effectiveDid}).`
+                    : `Identity already set up (did: ${effectiveDid}).`,
+            };
+        }
+        catch (error) {
+            spinner.fail("Failed to set up identity");
+            throw error;
+        }
+    },
+};
+/** Stage 3: claim flow (existing, unchanged). */
+export const claimStage = {
+    name: "claim",
+    when: () => true,
+    run: async (ctx) => {
+        const options = ctx.options;
+        const result = requireStageValue(ctx.registrationResult, "registrationResult", "claim");
+        if (options.skipRegistration) {
+            return { ok: true, summaryLine: "Claim flow: skipped (--skip-registration)." };
+        }
+        if (!result.metadata.claimUrl) {
+            return { ok: true, summaryLine: "Claim flow: no claim needed." };
+        }
+        console.log(`\n${chalk.bold("🎫 Claim Your Agent:")}`);
+        console.log(`   ${chalk.cyan(result.metadata.claimUrl)}`);
+        const { opened, reason } = await openUrlInBrowser(result.metadata.claimUrl);
+        if (opened) {
+            console.log(chalk.green("\n✅ Browser opened!"));
+        }
+        else if (reason === "non-tty") {
+            console.log(chalk.gray("\n   Non-interactive environment detected — visit the link above."));
+        }
+        else {
+            console.log(chalk.yellow("\n⚠️  Could not open browser automatically"));
+            console.log(chalk.cyan(`   Please visit: ${result.metadata.claimUrl}`));
+        }
+        if (options.skipClaimCheck) {
+            console.log(chalk.gray("\n   Skipping claim check..."));
+            console.log(chalk.gray("   You can claim your agent anytime at the URL above."));
+            return { ok: true, summaryLine: "Claim flow: claim check skipped." };
+        }
+        console.log("\n");
+        const agentSlug = result.metadata.agentSlug || result.metadata.agentId || options.name || "unknown";
+        const apiEndpoint = options.local
+            ? "http://localhost:3000"
+            : options.endpoint || "https://knowthat.ai";
+        const claimed = await pollForClaimStatus(new URL(`/api/agents/${encodeURIComponent(agentSlug)}`, apiEndpoint).toString(), (body) => {
+            if (!body || typeof body !== "object")
+                return false;
+            const data = body;
+            return Boolean(data.userId ||
+                data.status === "active" ||
+                data.owner ||
+                data.claimedAt ||
+                data.isDraft === false);
+        }, { verbose: options.verbose });
+        if (claimed) {
+            console.clear();
+            console.log(chalk.green("🎉 Your agent is now claimed and ready to use!\n"));
+            return { ok: true, summaryLine: "Claim flow: claimed." };
+        }
+        return { ok: true, summaryLine: "Claim flow: pending claim." };
+    },
+};
+/**
+ * Runs a DCO setup for one newly-created agent profile (review-loop P18:
+ * the DCO prompt moves inside the per-agent profile step, asked once per
+ * agent rather than once globally -- init.ts's own end-of-run prompt below
+ * still covers the MAIN identity, which is not itself an agent profile).
+ * Interactive + TTY only, same guard shape as the main prompt.
+ */
+async function offerPerAgentDco(slug) {
+    const inquirer = (await import("inquirer")).default;
+    const { setupDco } = await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "setupDco",
+            message: `Set up commit signing and PR attribution for ${slug} now?`,
+            default: true,
+        },
+    ]);
+    if (!setupDco)
+        return;
+    const { runDcoSetup } = await import("../utils/dco/setup.js");
+    const { renderSetupResult } = await import("../utils/dco/render.js");
+    const dcoResult = await runDcoSetup({ interactive: true, agent: slug });
+    renderSetupResult(dcoResult);
+}
+/**
+ * Runs the agent-profile stage (P15 commit 6) and, for any profile it
+ * creates, merges an entry into the review registry (P15 commit 7) and
+ * offers per-agent DCO setup (P18).
+ */
+async function runProfileStageAndUpdateRegistry(ctx) {
+    const options = ctx.options;
+    let githubLogin;
+    try {
+        if ((await isGhInstalled()) && (await isGhAuthenticated())) {
+            githubLogin = (await getGhUser()).login;
+        }
+    }
+    catch {
+        // Best-effort: profile slugs fall back to "agent-<kind>" below.
+    }
+    ctx.githubLogin = githubLogin;
+    const registerIdentity = createRegisterAgentIdentity({
+        endpoint: options.local ? "http://localhost:3000" : options.endpoint,
+        enableMCPIdentityCLIImpl: requireStageValue(ctx.enableMCPIdentity, "enableMCPIdentity", "profiles"),
+    });
+    const profileStageResult = await runAgentProfileStage({
+        interactive: ctx.isTTY,
+        profilesFlag: parseProfilesFlag(options.profiles),
+        skipProfiles: options.skipProfiles,
+        githubLogin,
+        registerIdentity,
+    });
+    if (profileStageResult.createdProfiles.length > 0) {
+        console.log(`\n${chalk.bold("🧩 Agent Profiles:")}`);
+        for (const profile of profileStageResult.createdProfiles) {
+            console.log(`   ${chalk.green("✓")} ${profile.kind} (${profile.slug})`);
+        }
+    }
+    for (const error of profileStageResult.errors) {
+        console.log(chalk.yellow(`   ⚠ Could not set up a profile for ${error.kind}: ${error.message}`));
+    }
+    if (profileStageResult.createdProfiles.length > 0 && githubLogin) {
+        const entries = profileStageResult.createdProfiles.map((profile) => ({
+            person: githubLogin,
+            githubLogin: githubLogin,
+            slug: profile.slug,
+            agentDid: profile.did,
+            reviews: true,
+            fixes: false,
+        }));
+        const registryResult = mergeReviewRegistry(entries, {
+            designateFixerCandidates: [profileStageResult.createdProfiles[0].did],
+        });
+        if (registryResult.status === "written") {
+            console.log(chalk.gray(`   Updated review registry at ${registryResult.path}`));
+        }
+        else if (registryResult.status === "invalid-existing" ||
+            registryResult.status === "invalid-result") {
+            console.log(chalk.yellow(`   ⚠ Review registry not updated: ${registryResult.error}`));
+        }
+    }
+    // Per-agent DCO prompt (P18): interactive + TTY only, one ask per newly
+    // created profile, never for a profile that already existed. Caught
+    // per-profile, not left to propagate: a signing-setup failure for one
+    // agent must not also skip the OTHER newly-created profiles' own DCO
+    // offer, and -- since profilesStage runs before github/hub in
+    // INIT_STAGES -- an uncaught throw here stops runStages entirely
+    // (StageFatalError is the only modeled way to do that on purpose),
+    // silently skipping GitHub credential onboarding and hub context too.
+    if (ctx.isTTY && !ctx.isTestEnv && options.dco !== false) {
+        for (const profile of profileStageResult.createdProfiles) {
+            try {
+                await offerPerAgentDco(profile.slug);
+            }
+            catch (error) {
+                console.log(chalk.yellow(`   ⚠ Commit-signing setup for ${profile.slug} failed: ${error.message}`));
+            }
+        }
+    }
+    return profileStageResult;
+}
+/** Stage 4: agent detection and profiles (P15), absorbing the per-agent DCO prompt. */
+export const profilesStage = {
+    name: "profiles",
+    when: () => true,
+    run: async (ctx) => {
+        if (ctx.options.skipRegistration) {
+            ctx.profileStageResult = null;
+            return { ok: true, summaryLine: "Agent profiles: skipped (--skip-registration)." };
+        }
+        const result = await runProfileStageAndUpdateRegistry(ctx);
+        ctx.profileStageResult = result;
+        if (result.errors.length > 0) {
+            return {
+                ok: false,
+                summaryLine: `Agent profiles: ${result.createdProfiles.length} created, ${result.errors.length} failed.`,
+                warnings: result.errors.map((e) => `${e.kind}: ${e.message}`),
+            };
+        }
+        if (result.createdProfiles.length > 0) {
+            return {
+                ok: true,
+                summaryLine: `Agent profiles: created ${result.createdProfiles.length} (${result.createdProfiles.map((p) => p.slug).join(", ")}).`,
+            };
+        }
+        if (result.skippedKinds.length > 0) {
+            return {
+                ok: true,
+                summaryLine: `Agent profiles already set up (${result.skippedKinds.length}).`,
+            };
+        }
+        if (result.detected.length === 0) {
+            return { ok: true, summaryLine: "Agent profiles: no agent harnesses detected." };
+        }
+        return { ok: true, summaryLine: "Agent profiles: none set up this run." };
+    },
+};
+/**
+ * Stage 5: GitHub credential onboarding. P16 landed (#704) with a real
+ * `runGithubCredentialStage` (utils/github-credential-stage.ts); this
+ * wraps it the same way the profiles stage above wraps
+ * `runAgentProfileStage`. `--skip-github` omits the stage entirely
+ * (`when`) rather than being threaded into the call, so `run` never
+ * executes when it's set -- matching the hub stage's own pattern below.
+ *
+ * The "already configured, skip unless forced" gate runs BEFORE calling
+ * `runGithubCredentialStage` at all: that function has no such short-
+ * circuit of its own (an interactive run with an existing credential
+ * re-prompts to rotate it every time, which is correct for a standalone
+ * `dco setup`-adjacent flow but not for this PR's own re-run design -- a
+ * second `kya-os init` on a configured machine should feel like opening
+ * the front door, not re-onboarding). Three DISTINCT reasons can force
+ * the call through, and they must not be conflated (each mix-up here was
+ * a real /get finding on an earlier version of this exact stage):
+ *
+ * - `--reconfigure github` / an explicit `--github-token-env`: a STATED
+ *   intent to redo credential setup, so the call gets the normal
+ *   `ctx.isTTY` interactivity (rotate-confirmation prompt and all,
+ *   exactly as if nothing were configured yet).
+ * - A queued anchor with neither of those AND a credential that's still
+ *   there (`retryPendingAnchorOnly`): ONLY a delivery retry, not a
+ *   change to the credential itself, so it forces the call through but
+ *   with `interactive: false` regardless of the real TTY --
+ *   `runGithubCredentialStage` attempts the pending-anchor flush
+ *   unconditionally before it ever looks at `interactive`, and
+ *   `interactive: false` with no token-env makes it skip out via
+ *   `resolveGithubTokenSource`'s non-interactive branch instead of
+ *   falling through into acquire-and-rotate if the flush still can't
+ *   reach the hub -- so a second `kya-os init` never re-opens "rotate
+ *   your GitHub credential?" over a hub that just hasn't come back up
+ *   yet.
+ * - A missing/corrupt credential (`!alreadyConfigured`), pending anchor
+ *   or not: `readStoredCredential` (not a bare `existsSync`) means this
+ *   reads as NOT configured, so it must get the FULL normal-interactivity
+ *   flow to actually self-heal -- `retryPendingAnchorOnly` is false in
+ *   this case specifically (it requires `alreadyConfigured`), so a
+ *   leftover `pending-anchor.json` next to an absent/corrupt
+ *   `credentials.json` doesn't also force `interactive: false` and wedge
+ *   the self-heal behind a silent non-interactive skip.
+ */
+export const githubStage = {
+    name: "github",
+    when: (ctx) => !ctx.options.skipGithub,
+    run: async (ctx) => {
+        const alreadyConfigured = Boolean(readStoredCredential());
+        const explicitlyForced = reconfiguring(ctx, "github") || Boolean(ctx.options.githubTokenEnv);
+        const hasPendingAnchor = Boolean(readPendingAnchor());
+        if (alreadyConfigured && !explicitlyForced && !hasPendingAnchor) {
+            return { ok: true, summaryLine: "GitHub credentials already set up." };
+        }
+        // Retry-only: the credential itself is fine (alreadyConfigured) and
+        // nothing explicit was asked for, but a queued anchor still needs
+        // its delivery retried -- this must NOT also fire when the
+        // credential is missing/corrupt (a real /get finding on the
+        // previous round's own fix): a leftover pending-anchor.json next to
+        // an absent or corrupt credentials.json must still get the normal
+        // interactive acquisition flow (readStoredCredential's own self-
+        // heal promise), not be forced non-interactive just because
+        // something is also queued for delivery.
+        const retryPendingAnchorOnly = alreadyConfigured && !explicitlyForced && hasPendingAnchor;
+        try {
+            const result = await runGithubCredentialStage({
+                interactive: ctx.isTTY && !retryPendingAnchorOnly,
+                githubTokenEnv: ctx.options.githubTokenEnv,
+                // --hub is this PR's own explicit, non-interactive override;
+                // DIDCOMM_HUB_ENDPOINT is the ambient fallback every hub-aware
+                // command in this codebase already reads. --hub naming a
+                // DIFFERENT endpoint than the env var must win, since it is the
+                // more specific, just-typed intent.
+                hubEndpoint: ctx.options.hub || process.env["DIDCOMM_HUB_ENDPOINT"],
+            });
+            switch (result.status) {
+                case "completed":
+                    return {
+                        ok: true,
+                        summaryLine: `GitHub credential: ${result.githubLogin} (${result.anchorDelivery === "delivered" ? "anchored" : "anchor pending"}).`,
+                    };
+                case "declined-rotation":
+                    return {
+                        ok: true,
+                        summaryLine: "GitHub credential: kept existing (rotation declined).",
+                    };
+                case "anchor-build-failed":
+                    return {
+                        ok: false,
+                        summaryLine: `GitHub credential: ${result.githubLogin} saved locally, not yet anchored.`,
+                        warnings: [result.reason],
+                    };
+                case "skipped":
+                    return {
+                        ok: true,
+                        summaryLine: `GitHub credential onboarding: skipped (${result.reason}).`,
+                    };
+            }
+        }
+        catch (error) {
+            return {
+                ok: false,
+                summaryLine: "GitHub credential onboarding failed.",
+                warnings: [error.message],
+            };
+        }
+    },
+};
+/**
+ * Stage 6: hub context (review-loop P17). Same runtime-optional shape as
+ * the GitHub stage above; "already configured" reads `~/.mcpi/hub.json`
+ * through the existing read-only `readHubConfig()` helper (utils/
+ * hub-config.ts), so this stage's state-detection needs no dependency on
+ * P17's module either.
+ */
+export const hubStage = {
+    name: "hub",
+    when: async (ctx) => {
+        if (ctx.options.skipHub)
+            return false;
+        return moduleExists("../utils/hub-context.js", import.meta.url);
+    },
+    run: async (ctx) => {
+        const existing = readHubConfig();
+        if (existing && !reconfiguring(ctx, "hub")) {
+            return { ok: true, summaryLine: `Hub context already set up (${existing.endpoint}).` };
+        }
+        /* v8 ignore start -- unreachable until P17's resolution module exists; see `when` above. */
+        return {
+            ok: true,
+            summaryLine: "Hub context: module found but resolution not yet wired (P17 lands separately).",
+        };
+        /* v8 ignore stop */
+    },
+};
+export const INIT_STAGES = [
+    readinessStage,
+    identityStage,
+    claimStage,
+    profilesStage,
+    githubStage,
+    hubStage,
+];
+/** Human-readable reason an omitted stage produced no StageResult. */
+export function omittedStageSummary(name, ctx) {
+    switch (name) {
+        case "github":
+            // githubStage.when is now a plain `!skipGithub` check (P16 landed,
+            // #704) -- --skip-github is the only reason this stage is ever
+            // omitted, unlike hub below (still gated on P17 not landing yet).
+            return "GitHub credential onboarding: skipped (--skip-github).";
+        case "hub":
+            return ctx.options.skipHub
+                ? "Hub context: skipped (--skip-hub)."
+                : "Hub context: skipped (not available yet).";
+        default:
+            return `${name}: skipped.`;
+    }
+}
+//# sourceMappingURL=init-stages.js.map