@springbrand/cli 0.1.0

package/dist/commands/connect.js

@@ -0,0 +1,901 @@
+/** 复刻自 tiny-fish CLI 编译产物：connect.d.ts + connect.impl.js */
+import spawn from 'cross-spawn';
+import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from '../lib/auth.js';
+import { CURSOR_SKILL_TARGET, OPENCLAW, openclawSkillInstallArgs, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchPiWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
+import { captureStdio, capturedOutput, installSpringBrandCli, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from '../lib/cli-install.js';
+import { ensureCliAuthenticated } from '../lib/connect-auth.js';
+import { createStdinPrompt, runCliFallback } from '../lib/connect-fallback.js';
+import { installWebSkill } from '../lib/skill-install.js';
+import { ConnectInterruptedError, ConnectStepError, HoistedFailureReportedError, createConnectTelemetry, finishSetupCommand, requireCommandSupport, runGuarded, settle, SignInTimeoutError, spawnStepError, stageDurationOf, withStageDuration, spawnRemoval, } from '../lib/connect-runtime.js';
+import { cursorInstallDeeplink, cursorMcpPath, readCursorSpringbrandEntry, writeCursorMcpConfig, } from '../lib/cursor-config.js';
+import { runConnectAll } from '../lib/connect-all.js';
+import { ompMcpPath, readOmpSpringbrandEntry, writeOmpMcpConfig } from '../lib/omp-config.js';
+import { PI_ADAPTER_INSTALL_COMMAND, piMcpAdapterState, piSkillDirMismatch, piMcpPath, readPiSpringbrandEntry, writePiMcpConfig, } from '../lib/pi-config.js';
+import { ALL_HARNESSES, AuthMode, HARNESS_DISPLAY_NAMES, RELOAD_ACTION, } from '../lib/harness-detect.js';
+import { detectHumanInitiated } from '../lib/harness.js';
+import { SPRINGBRAND_API_KEY_VAR } from '../lib/constants.js';
+import { emitNotice } from '../lib/notice.js';
+import { SIGN_IN_PROBES } from '../lib/registration-detect.js';
+import { errLine, warnLine } from '../lib/output.js';
+import { z } from 'zod';
+import { verifyMcpAuth } from '../lib/verify.js';
+import { gateApiKey } from '../lib/connect-preflight.js';
+import { apiBaseFromMcpUrl, DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
+function removeExistingRegistration(client, removal, verbose) {
+    const result = spawnRemoval(client.command, removal.args);
+    if (result.status === 0)
+        return;
+    // Best-effort: a stale entry makes `mcp add` error or upsert, with a truer message.
+    if (!verbose)
+        return;
+    const details = result.stderr?.trim() || result.error?.message || 'unknown error';
+    warnLine(`Could not remove existing ${removal.label}: ${details}`);
+}
+/** false: fall back to OAuth — a config naming an unset variable authenticates nothing. */
+function exportApiKey(apiKey, displayName, deferOutro) {
+    try {
+        persistApiKeyToEnvironment(apiKey);
+    }
+    catch (error) {
+        errLine(`Could not export SPRINGBRAND_API_KEY (${error instanceof Error ? error.message : String(error)}); ` +
+            'signing in instead.');
+        return false;
+    }
+    process.env[SPRINGBRAND_API_KEY_VAR] = apiKey;
+    if (deferOutro) {
+        deferOutro('Exported SPRINGBRAND_API_KEY to your shell profile — restart your agents (or open a new ' +
+            'terminal) before use.');
+    }
+    else {
+        errLine(`Exported SPRINGBRAND_API_KEY to your shell profile — ${displayName} reads the key from there, ` +
+            'so restart it (or open a new terminal) before use.');
+    }
+    return true;
+}
+/** Undefined leaves the client on its keyless path, if any. */
+function resolveKeyedAdd(client, storedKey, keyAuthSupported, deferOutro) {
+    if (!storedKey || !keyAuthSupported || !client.keyAuth)
+        return undefined;
+    const keyed = { key: storedKey, spec: client.keyAuth };
+    // Before the removals: a failed export must not strand the old registration.
+    if (keyed.spec.envVar && !exportApiKey(keyed.key, client.displayName, deferOutro)) {
+        return undefined;
+    }
+    return keyed;
+}
+/** No sign-in to degrade to, so the install stops. */
+function refuseKeylessInstall(client, keyAuthSupported, headless = false) {
+    const noSignIn = headless
+        ? 'signing in needs a terminal'
+        : `SpringBrand does not sign in to ${client.displayName} any other way`;
+    const rerun = `re-run: sp connect ${client.connectClient}`;
+    if (!client.keyAuth) {
+        throw new ConnectStepError(`${client.displayName} cannot take a SpringBrand API key, and ${noSignIn}. ` +
+            `Run: sp connect ${client.connectClient}`, 'key_auth_unsupported');
+    }
+    if (!keyAuthSupported || headless) {
+        throw new ConnectStepError(`This ${client.displayName} install cannot take a SpringBrand API key, and ${noSignIn}. ` +
+            `Update it, then ${rerun}`, 'harness_too_old');
+    }
+    throw new ConnectStepError(`Connecting ${client.displayName} needs a SpringBrand API key, and ${noSignIn}. ` +
+        `Run: sp auth login, then ${rerun}`, 'invalid_config', { failureDetail: 'keyless_install_refused' });
+}
+/** Resolved before the removals, so a refusal strands no registration. */
+function keylessAddArgs(client, keyAuthSupported) {
+    if (!client.addArgs)
+        refuseKeylessInstall(client, keyAuthSupported);
+    return client.addArgs;
+}
+/** Runs before any write: a refused key strands nothing. */
+async function verifyKeyBeforeSeeding(apiKey, displayName, mcpUrl) {
+    // One host serves `/mcp` and `/v1`, so `--url` decides where the key is checked.
+    const verified = await verifyMcpAuth(apiKey, apiBaseFromMcpUrl(mcpUrl));
+    if (verified.ok)
+        return;
+    // Anything but a refusal leaves the key usable, so it is reported as an outage, not a bad key.
+    if (verified.kind !== 'credential_rejected') {
+        throw new ConnectStepError(`Could not reach SpringBrand to check your API key (${verified.code ?? 'unknown'}), so ` +
+            `nothing was written to ${displayName}. Check your connection and retry.`, 'timeout');
+    }
+    // The tag carries the HTTP status; `verified.code` is authored prose.
+    throw new ConnectStepError(`Your SpringBrand API key was rejected (${verified.code ?? 'unknown'}), so it was not ` +
+        `written to ${displayName}. Run: sp auth login`, 'invalid_config', { failureDetail: `key_rejected status=${verified.status}` });
+}
+/** A bounded spawn's timeout means the sign-in never finished. */
+function signInStepError(message, result, bounded) {
+    const error = spawnStepError(message, result);
+    return bounded && error.failureReason === 'timeout'
+        ? new SignInTimeoutError(error.message, error.cause)
+        : error;
+}
+function isMissingHarness(error) {
+    return error instanceof ConnectStepError && error.failureReason === 'harness_not_installed';
+}
+/** Undefined means the rescue ran; the caller returns immediately. */
+async function requireSupportOrRescue(client, connectClient, state, telemetry, options) {
+    try {
+        return requireCommandSupport(client);
+    }
+    catch (error) {
+        if (!options.fallbackWhenMissing || !isMissingHarness(error))
+            throw error;
+        await runMissingHarnessFallback(client.displayName, connectClient, state, telemetry, options);
+        return undefined;
+    }
+}
+// The harness attempt stays failed; the rescue rides fallback_outcome (PF-3707).
+async function runMissingHarnessFallback(displayName, connectClient, state, telemetry, options) {
+    // Stamped before any step: Ctrl+C settles before an outcome exists.
+    telemetry.setFallbackOutcome('abandoned');
+    errLine(`${displayName} was not found on PATH. Setting up the SpringBrand CLI instead.`);
+    const outcome = await runCliFallback({
+        apiKey: options.apiKey,
+        verbose: options.verbose ?? false,
+        prompt: detectHumanInitiated() ? createStdinPrompt() : undefined,
+        retryCommand: `npx @springbrand/cli connect ${connectClient}`,
+        hooks: {
+            // Terminal detail is explicit below; abort rows still name the step.
+            onStepStart: (stage) => {
+                state.stage = stage;
+            },
+            onStepDone: (phase) => telemetry.track('checkpoint', { phase }),
+        },
+    });
+    telemetry.setFallbackOutcome(outcome);
+    // Never `completed`: dashboards read that as "the harness install worked".
+    settle(state, telemetry, 'failed', {
+        failedStage: 'prerequisite_check',
+        failureReason: 'harness_not_installed',
+    });
+    if (outcome !== 'cli_verified') {
+        process.exitCode = 1;
+        return;
+    }
+    errLine('The SpringBrand CLI is installed and working.');
+    errLine('Using a different agent? Run: sp connect --all');
+}
+/** Resolved before the removals, so a refusal strands no registration. */
+async function prepareInstallAuth(client, options, keyAuthSupported) {
+    // `/mcp` accepts the key as `Authorization: Bearer`, so a stored key replaces the browser OAuth hop.
+    const storedKey = validatedApiKey(options.apiKey);
+    const keyedAdd = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.deferOutro);
+    // Refuses here when key-required; others keep their OAuth argv.
+    const buildAddArgs = keyedAdd
+        ? (mcpUrl) => keyedAdd.spec.addArgs(mcpUrl, keyedAdd.key)
+        : keylessAddArgs(client, keyAuthSupported);
+    if (options.keyAuthOnly && !keyedAdd)
+        refuseKeylessInstall(client, keyAuthSupported, true);
+    // Verify first: a revoked key in a foreign .env is unrecoverable.
+    if (keyedAdd?.spec.seedKey) {
+        await verifyKeyBeforeSeeding(keyedAdd.key, client.displayName, options.mcpUrl);
+    }
+    return { keyedAdd, buildAddArgs };
+}
+/** Inherit for an inline-OAuth add; capture otherwise, piping prompts when seeded. */
+function addSpawnOptions(options, interactiveAdd, seeded) {
+    if (interactiveAdd)
+        return { stdio: 'inherit', timeout: options.authTimeoutMs };
+    if (!seeded)
+        return captureStdio(options.verbose ?? false);
+    return {
+        encoding: 'utf8',
+        // Without it, the 1 MiB default overflows into a misread Ctrl+C.
+        maxBuffer: STEP_MAX_BUFFER,
+        // The unattended path had no bound at all before; captureStdio's is the floor.
+        timeout: options.authTimeoutMs ?? SKILL_INSTALL_TIMEOUT_MS,
+        input: seeded.stdinInput,
+        env: seeded.env,
+    };
+}
+/** Returns the seeded-credential note when a key was written into a user-owned file. */
+function performMcpAdd(client, options, plan, attemptId) {
+    const { keyedAdd, buildAddArgs } = plan;
+    const mcpUrl = new URL(options.mcpUrl);
+    mcpUrl.searchParams.set('source', CONNECT_SOURCE);
+    mcpUrl.searchParams.set('client', client.connectClient);
+    mcpUrl.searchParams.set('connect_attempt_id', attemptId);
+    errLine(`Adding SpringBrand to ${client.displayName}...`);
+    // Header keys ride argv (/proc/<pid>/cmdline); these CLIs take headers no other way.
+    const addArgs = buildAddArgs(mcpUrl.toString());
+    // Capturing an inline-OAuth add hides the sign-in URL and hangs.
+    const interactiveAdd = !(client.nonInteractiveAdd || keyedAdd);
+    // After the removals: an interrupt there leaves no key behind.
+    const seeded = keyedAdd?.spec.seedKey?.(keyedAdd.key);
+    // Writing the entry ourselves skips the harness probe that saves it disabled.
+    if (seeded?.register(mcpUrl.toString())) {
+        return { note: seeded.note, seededHome: seeded.home };
+    }
+    const addResult = spawn.sync(client.command, addArgs, addSpawnOptions(options, interactiveAdd, seeded));
+    // Rolls back first: signInStepError throws on a Ctrl+C.
+    const failAdd = (build) => {
+        seeded?.rollback();
+        const error = build();
+        replay(capturedOutput(addResult));
+        throw error;
+    };
+    if (addResult.error || addResult.status !== 0) {
+        failAdd(() => signInStepError(`Could not add SpringBrand to ${client.displayName}`, addResult, interactiveAdd && options.authTimeoutMs !== undefined));
+    }
+    const registration = seeded?.confirmRegistered();
+    if (registration && !registration.ok) {
+        failAdd(() => new ConnectStepError(`${client.displayName} reported success but SpringBrand is not enabled there` +
+            `${registration.detail ? `: ${registration.detail}` : ''}.`, 'invalid_config', 
+        // The tag keeps the path-bearing prose out of telemetry.
+        { failureDetail: registration.tag }));
+    }
+    return { note: seeded?.note, seededHome: seeded?.home };
+}
+function performLoginStep(client, pendingLogin, options) {
+    errLine('Signing in to SpringBrand...');
+    const loginResult = spawn.sync(client.command, [...pendingLogin], {
+        stdio: 'inherit',
+        timeout: options.authTimeoutMs,
+    });
+    if (loginResult.error || loginResult.status !== 0) {
+        throw signInStepError(`Could not authenticate SpringBrand in ${client.displayName}`, loginResult, options.authTimeoutMs !== undefined);
+    }
+}
+function announceAuthNotes(useKeyAuth, degradedNotes, seededNote) {
+    if (useKeyAuth) {
+        errLine(degradedNotes?.keyed ?? 'Using your stored SpringBrand API key — no browser sign-in needed.');
+        // Every other credential the CLI writes into a user-owned file says so too.
+        if (seededNote)
+            errLine(seededNote);
+    }
+    else if (degradedNotes) {
+        // Printed here, not with the closing line, so a `--launch` run sees it before the handover.
+        errLine(degradedNotes.deferred);
+    }
+}
+function completeAuthFlow(client, options, state, telemetry, ctx) {
+    const { useKeyAuth, loginDegraded, loginArgs, probeAuthenticated } = ctx;
+    // Codex runs OAuth inside `mcp add` and exits 0 either way, so the recorded state decides
+    // whether the login step below still runs. Unknown keeps the pre-probe behaviour.
+    const addSignedIn = probeAuthenticated?.();
+    if (addSignedIn)
+        telemetry.track('checkpoint', { phase: 'oauth_done' });
+    announceAuthNotes(useKeyAuth, loginDegraded ? client.degradedAuthNotes : undefined, ctx.seededNote);
+    // A probed client signs in again only when its inline OAuth is known to have been abandoned.
+    const retryLogin = probeAuthenticated ? addSignedIn === false : true;
+    const pendingLogin = !useKeyAuth && retryLogin ? loginArgs : undefined;
+    let signInDeferred = !useKeyAuth && !addSignedIn && !pendingLogin;
+    if (pendingLogin) {
+        state.stage = 'client_oauth';
+        performLoginStep(client, pendingLogin, options);
+        if (probeAuthenticated?.() === false)
+            signInDeferred = true;
+        else
+            telemetry.track('checkpoint', { phase: 'oauth_done' });
+    }
+    const authMode = useKeyAuth
+        ? AuthMode.ApiKey
+        : signInDeferred
+            ? 'deferred'
+            : AuthMode.OAuth;
+    return { authMode, signInDeferred };
+}
+async function connectNativeMcpClient(client, options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, client.connectClient, options);
+    const state = { stage: 'prerequisite_check', settled: false };
+    const probeAuthenticated = SIGN_IN_PROBES[client.connectClient];
+    await runGuarded(state, telemetry, async () => {
+        telemetry.track('started');
+        const support = await requireSupportOrRescue(client, client.connectClient, state, telemetry, options);
+        if (!support)
+            return;
+        const { optionalSupported, keyAuthSupported, harnessVersion } = support;
+        telemetry.setHarnessVersion(harnessVersion);
+        state.harnessDegraded = !!client.loginArgs && !optionalSupported;
+        const plan = await prepareInstallAuth(client, options, keyAuthSupported);
+        const useKeyAuth = !!plan.keyedAdd;
+        telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
+        state.stage = 'registration_cleanup';
+        for (const removal of client.removals)
+            removeExistingRegistration(client, removal, options.verbose ?? false);
+        // Undefining `loginArgs` reuses the deferred-auth path codex/hermes already take.
+        const loginDegraded = state.harnessDegraded === true;
+        const loginArgs = loginDegraded ? undefined : client.loginArgs;
+        // A probed client authenticates inside `mcp add` too, so a failure there is either.
+        state.stage =
+            loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
+        const { note: seededNote, seededHome } = performMcpAdd(client, options, plan, telemetry.attemptId);
+        telemetry.track('checkpoint', { phase: 'registered' });
+        const { authMode, signInDeferred } = completeAuthFlow(client, options, state, telemetry, {
+            useKeyAuth,
+            loginDegraded,
+            loginArgs,
+            probeAuthenticated,
+            seededNote,
+        });
+        state.authMode = authMode;
+        // Registration/OAuth make MCP work; later steps are cosmetic and must not fail the attempt.
+        settle(state, telemetry, 'completed', { authMode });
+        await runPostInstallSteps(client, options, state, telemetry, signInDeferred, seededHome);
+    });
+    return state.authMode;
+}
+function connectedLine(client, signInDeferred) {
+    // The CLI never observes deferred auth, so don't claim "connected".
+    if (signInDeferred) {
+        if (client.signInHint)
+            return client.signInHint;
+        return (`SpringBrand is configured in ${client.displayName}. ${client.displayName} will ask you ` +
+            'to sign in to SpringBrand the first time you use it.');
+    }
+    return (`SpringBrand is connected. Open ${client.displayName}; if it is already running, ` +
+        `${RELOAD_ACTION[client.connectClient]} to pick up the tools.`);
+}
+// Runs after `completed` settled: steps fail alone, the rest still run.
+async function runPostInstallSteps(client, options, state, telemetry, signInDeferred, seededHome) {
+    let failed = false;
+    // Modelled on upgrade's attempt(); interrupts rethrow and abandon remaining steps.
+    const attempt = async (stage, run) => {
+        state.stage = stage;
+        try {
+            await run();
+        }
+        catch (error) {
+            if (error instanceof ConnectInterruptedError)
+                throw error;
+            failed = true;
+            trackPostInstallFailure(client.displayName, state, telemetry, error);
+        }
+    };
+    try {
+        if (options.cliInstall !== false) {
+            await attempt('cli_install', () => runCliInstallStep(options, telemetry));
+        }
+        if (client.skillAgent) {
+            await attempt('skill_install', () => {
+                installWebSkill(client, { verbose: options.verbose ?? false });
+                telemetry.track('checkpoint', { phase: 'skill_installed' });
+            });
+        }
+        const extraPostInstall = client.extraPostInstall;
+        if (extraPostInstall) {
+            await attempt('plugin_install', () => {
+                extraPostInstall({
+                    apiKey: validatedApiKey(options.apiKey),
+                    verbose: options.verbose ?? false,
+                    seededHome,
+                });
+                telemetry.track('checkpoint', {
+                    phase: 'plugin_installed',
+                    pluginVersion: client.pluginVersion,
+                });
+            });
+        }
+        // Before auth: a failed sign-in must not lose the harness record.
+        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
+        await attempt('authentication', () => {
+            // A set timeout means headless; never shell an interactive login.
+            ensureCliAuthenticated(client.connectClient, options.apiKey, {
+                interactiveLogin: options.authTimeoutMs === undefined,
+            });
+            telemetry.track('checkpoint', { phase: 'authenticated' });
+        });
+        if (client.postConnectNote)
+            errLine(client.postConnectNote);
+        if (!options.launch) {
+            // Under --all the summary replaces this; sign-in hints still print.
+            if (signInDeferred || !options.deferOutro)
+                errLine(connectedLine(client, signInDeferred));
+        }
+        else {
+            await attempt('walkthrough_launch', async () => {
+                // Before the handover, or the only sign-in instructions scroll past under the agent.
+                if (signInDeferred && client.signInHint)
+                    errLine(client.signInHint);
+                await launchNativeMcpClient(client, async (outcome) => {
+                    telemetry.track('checkpoint', { phase: walkthroughPhase(outcome) });
+                    // Flushed pre-block; the session-long handover would strand the delivery.
+                    await telemetry.flush();
+                });
+            });
+        }
+    }
+    catch (error) {
+        // Interrupts stop quietly; anything else escapes to runGuarded.
+        if (!(error instanceof ConnectInterruptedError))
+            throw error;
+        failed = true;
+    }
+    if (failed) {
+        errLine(finishSetupHint(client.connectClient));
+        options.onPostInstallFailed?.();
+    }
+}
+/** Fails on a carried failure; only the first take reports anything. */
+function takeHoistedCliInstall(take, telemetry) {
+    const { outcome, firstTake } = take();
+    if (!outcome.ok) {
+        // Late takers fail too; only the first reports the install.
+        if (!firstTake)
+            throw new HoistedFailureReportedError(outcome.error.message);
+        throw withStageDuration(outcome.error, outcome.durationMs);
+    }
+    if (firstTake) {
+        telemetry.track('checkpoint', {
+            phase: 'cli_installed',
+            stageDurationMs: outcome.durationMs,
+        });
+    }
+}
+/** Consumes the `--all` hoist when present; installs inline otherwise. */
+function runCliInstallStep(options, telemetry) {
+    if (options.hoistedCliInstall) {
+        takeHoistedCliInstall(options.hoistedCliInstall, telemetry);
+        return;
+    }
+    installSpringBrandCli({ verbose: options.verbose ?? false, announce: true });
+    telemetry.track('checkpoint', { phase: 'cli_installed' });
+}
+function walkthroughPhase(outcome) {
+    return outcome === 'printed' ? 'walkthrough_prompt_printed' : 'walkthrough_launched';
+}
+function finishSetupHint(connectClient) {
+    return `Finish setup with: ${finishSetupCommand(connectClient)}`;
+}
+/** Warn + report post_install_failed; interrupts are abandonment, not failure. */
+function trackPostInstallFailure(displayName, state, telemetry, error) {
+    if (error instanceof ConnectInterruptedError)
+        return;
+    // An earlier harness already owns the shared install's failure record.
+    if (!(error instanceof HoistedFailureReportedError)) {
+        telemetry.track('post_install_failed', {
+            failedStage: state.stage,
+            failureReason: error instanceof ConnectStepError ? error.failureReason : 'unexpected_error',
+            failureDetail: error instanceof ConnectStepError ? (error.failureDetail ?? error.message) : undefined,
+            stageDurationMs: stageDurationOf(error),
+        });
+    }
+    errLine(`The ${displayName} MCP connection succeeded, but a finishing step ` +
+        `(${state.stage}) failed: ${error instanceof Error ? error.message : String(error)}`);
+}
+/** Skill install only: no key handoff or post-install callback to honour. */
+export async function connectOpenClaw(options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, 'openclaw', options);
+    // Skill install, no MCP server — never degraded, and false keeps it inside a `= false` filter.
+    const state = {
+        stage: 'prerequisite_check',
+        settled: false,
+        harnessDegraded: false,
+    };
+    await runGuarded(state, telemetry, async () => {
+        telemetry.track('started');
+        const support = await requireSupportOrRescue(OPENCLAW, 'openclaw', state, telemetry, options);
+        if (!support)
+            return;
+        telemetry.setHarnessVersion(support.harnessVersion);
+        telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
+        if (options.cliInstall !== false) {
+            state.stage = 'cli_install';
+            runCliInstallStep(options, telemetry);
+        }
+        state.stage = 'skill_install';
+        errLine('Installing the SpringBrand skill in OpenClaw...');
+        const skillInstallResult = spawn.sync('openclaw', openclawSkillInstallArgs(support.matchedVariant), captureStdio(options.verbose ?? false));
+        if (skillInstallResult.error || skillInstallResult.status !== 0) {
+            // Built first: its interrupt check must run before any replay.
+            const error = spawnStepError('Could not install the SpringBrand skill in OpenClaw', skillInstallResult);
+            replay(capturedOutput(skillInstallResult));
+            throw error;
+        }
+        telemetry.track('checkpoint', { phase: 'skill_installed' });
+        // Stores the key before probing, so a passed --api-key never reaches an interactive login.
+        state.stage = 'authentication';
+        // A set timeout means headless; never shell an interactive login.
+        ensureCliAuthenticated('openclaw', options.apiKey, {
+            interactiveLogin: options.authTimeoutMs === undefined,
+        });
+        telemetry.track('checkpoint', { phase: 'authenticated' });
+        saveConnectContext('openclaw', telemetry.attemptId);
+        // For openclaw the skill install and auth ARE functional; only the walkthrough is cosmetic.
+        settle(state, telemetry, 'completed');
+        if (!options.launch) {
+            // Under --all the summary already lists OpenClaw.
+            if (!options.deferOutro) {
+                errLine('SpringBrand is connected. Open OpenClaw; if it is already running, ' +
+                    `${RELOAD_ACTION.openclaw} to pick up the skill.`);
+            }
+            return;
+        }
+        state.stage = 'walkthrough_launch';
+        try {
+            await launchOpenClawWalkthrough(async (outcome) => {
+                telemetry.track('checkpoint', { phase: walkthroughPhase(outcome) });
+                // Flushed pre-block; the session-long handover would strand the delivery.
+                await telemetry.flush();
+            });
+        }
+        catch (error) {
+            trackPostInstallFailure('OpenClaw', state, telemetry, error);
+            errLine(finishSetupHint('openclaw'));
+        }
+    });
+}
+const PI_RELOAD_COPY = 'SpringBrand is configured in pi. Restart pi, then run `/mcp-auth springbrand` there if it asks you ' +
+    'to sign in.';
+// The skill is the working path either way, so the note must not read as a failure.
+const PI_ADAPTER_DORMANT_NOTE = 'Note: pi has no built-in MCP support, so the entry in its mcp.json stays dormant until you ' +
+    `run \`${PI_ADAPTER_INSTALL_COMMAND}\`. The SpringBrand skill works without it.`;
+// Only the dormant case was spoken for, leaving a working MCP install silent.
+const PI_ADAPTER_LIVE_NOTE = 'pi-mcp-adapter is installed, so pi loads the SpringBrand MCP tools as well as the skill once ' +
+    'you restart it.';
+function piAdapterNote() {
+    const state = piMcpAdapterState();
+    if (state === 'installed')
+        return PI_ADAPTER_LIVE_NOTE;
+    return state === 'absent' ? PI_ADAPTER_DORMANT_NOTE : undefined;
+}
+// The `skills` CLI writes to the default dir even when pi reads another one.
+function piPostConnectNotes() {
+    const notes = [piAdapterNote()];
+    const skills = piSkillDirMismatch();
+    if (skills) {
+        notes.push(`Note: PI_CODING_AGENT_DIR points pi at ${skills.readFrom}, but the SpringBrand skill ` +
+            `installed to ${skills.installedTo}. Copy or symlink it across for pi to load it.`);
+    }
+    const printable = notes.filter(Boolean);
+    return printable.length > 0 ? printable.join('\n') : undefined;
+}
+// Only interactive omp wires the OAuth handler; headless cannot sign in.
+const OMP_KEYLESS_COPY = 'SpringBrand is configured in omp. Open omp and sign in to SpringBrand when prompted, or run ' +
+    '`/mcp reauth springbrand` there.';
+const CONFIG_FILE_HARNESSES = {
+    cursor: {
+        skillTarget: CURSOR_SKILL_TARGET,
+        registeredUrl: () => readCursorSpringbrandEntry().url,
+        write: writeCursorMcpConfig,
+        configPath: cursorMcpPath,
+        tryLaunch: launchCursorDeeplink,
+        copy: {
+            verified: "SpringBrand is connected and verified (health+auth). Reload the Cursor window (or restart cursor-agent) and it's live.",
+            authFailed: (reason) => `SpringBrand is configured, but the authenticated check failed (${reason}). ` +
+                'Fix: rotate/re-enter your key with `sp auth login`, then re-run: sp connect cursor',
+            launched: 'Cursor should pop a SpringBrand install confirmation — approve it, then sign in when prompted.',
+            reload: 'SpringBrand is connected. Reload the Cursor window, then approve/sign in under Settings → MCP.',
+        },
+    },
+    omp: {
+        // No skill exists for omp; installWebSkill returns without one.
+        skillTarget: { displayName: HARNESS_DISPLAY_NAMES.omp },
+        registeredUrl: () => readOmpSpringbrandEntry()?.url,
+        write: writeOmpMcpConfig,
+        configPath: ompMcpPath,
+        // No install deeplink exists; the keyless copy carries the sign-in.
+        tryLaunch: () => false,
+        copy: {
+            verified: "SpringBrand is connected and verified (health+auth). Restart omp and it's live.",
+            authFailed: (reason) => `SpringBrand is configured, but the authenticated check failed (${reason}). ` +
+                'Fix: rotate/re-enter your key with `sp auth login`, then re-run: sp connect omp',
+            launched: OMP_KEYLESS_COPY,
+            reload: OMP_KEYLESS_COPY,
+        },
+    },
+    pi: {
+        skillTarget: { skillAgent: 'pi', displayName: HARNESS_DISPLAY_NAMES.pi },
+        registeredUrl: () => readPiSpringbrandEntry().url,
+        write: writePiMcpConfig,
+        configPath: piMcpPath,
+        // No install deeplink exists; the copy carries the restart instead.
+        tryLaunch: () => false,
+        postConnectNote: piPostConnectNotes,
+        copy: {
+            verified: "SpringBrand is connected and verified (health+auth). Restart pi and it's live.",
+            authFailed: (reason) => `SpringBrand is configured, but the authenticated check failed (${reason}). ` +
+                'Fix: rotate/re-enter your key with `sp auth login`, then re-run: sp connect pi',
+            launched: PI_RELOAD_COPY,
+            reload: PI_RELOAD_COPY,
+        },
+    },
+};
+/** Cosmetic and post-settle: a skill failure must not fail the connection. */
+function installSkillPostSettle(spec, displayName, state, telemetry, options) {
+    if (!spec.skillTarget.skillAgent)
+        return false;
+    state.stage = 'skill_install';
+    try {
+        installWebSkill(spec.skillTarget, { verbose: options.verbose ?? false });
+        telemetry.track('checkpoint', { phase: 'skill_installed' });
+        return false;
+    }
+    catch (error) {
+        trackPostInstallFailure(displayName, state, telemetry, error);
+        return true;
+    }
+}
+/** Prints last: the outro must own the final line. */
+function reportPostInstallFailure(harness, failed, onPostInstallFailed) {
+    if (!failed)
+        return;
+    errLine(finishSetupHint(harness));
+    onPostInstallFailed?.();
+}
+/** Writes the harness's MCP config file itself; no `mcp add` exists. */
+async function connectConfigFileHarness(harness, options) {
+    const spec = CONFIG_FILE_HARNESSES[harness];
+    const displayName = HARNESS_DISPLAY_NAMES[harness];
+    let fallbackAttemptId;
+    const registeredUrl = spec.registeredUrl();
+    if (registeredUrl) {
+        try {
+            const registered = new URL(registeredUrl);
+            const requested = new URL(options.mcpUrl);
+            const registeredId = registered.searchParams.get('connect_attempt_id');
+            const registeredSource = registered.searchParams.get('source');
+            const registeredClient = registered.searchParams.get('client');
+            for (const key of ['source', 'client', 'connect_attempt_id']) {
+                registered.searchParams.delete(key);
+                requested.searchParams.delete(key);
+            }
+            registered.searchParams.sort();
+            requested.searchParams.sort();
+            if (registered.toString() === requested.toString() &&
+                registeredSource === CONNECT_SOURCE &&
+                registeredClient === harness &&
+                z.uuid().safeParse(registeredId).success) {
+                fallbackAttemptId = registeredId ?? undefined;
+            }
+        }
+        catch {
+            // A hand-edited invalid URL is repaired below with a fresh attempt id.
+        }
+    }
+    const telemetry = createConnectTelemetry(options.mcpUrl, harness, {
+        ...options,
+        fallbackAttemptId,
+    });
+    // Never degraded: no sign-in command to be missing. False, not absent, so a `= false`
+    // filter still catches these harnesses.
+    const state = {
+        stage: 'prerequisite_check',
+        settled: false,
+        harnessDegraded: false,
+    };
+    await runGuarded(state, telemetry, async () => {
+        telemetry.track('started');
+        telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
+        // Auth first: a key lets the config carry an Authorization header, removing the sign-in hand-back.
+        state.stage = 'authentication';
+        // A set timeout means headless; never shell an interactive login.
+        ensureCliAuthenticated(harness, options.apiKey, {
+            interactiveLogin: options.authTimeoutMs === undefined,
+        });
+        telemetry.track('checkpoint', { phase: 'authenticated' });
+        const resolvedKey = validatedApiKey(options.apiKey);
+        // ensureCliAuthenticated leaves a key stored, and `auth status` exits 0 on a malformed one.
+        if (!resolvedKey) {
+            errLine('Ignoring the stored API key: invalid format. Run: sp auth login');
+        }
+        state.stage = 'registration';
+        errLine(`Adding SpringBrand to ${displayName}...`);
+        const mcpUrl = new URL(options.mcpUrl);
+        mcpUrl.searchParams.set('source', CONNECT_SOURCE);
+        mcpUrl.searchParams.set('client', harness);
+        mcpUrl.searchParams.set('connect_attempt_id', telemetry.attemptId);
+        const result = spec.write(mcpUrl.toString(), resolvedKey);
+        if (result.status === 'corrupt_skip') {
+            // The message fallback would leak the config path; tag instead.
+            throw new ConnectStepError(`Could not update ${spec.configPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
+                `Fix the file, then re-run: sp connect ${harness}`, 'invalid_config', { failureDetail: `${harness}_mcp_json_corrupt` });
+        }
+        if (result.backupPath) {
+            errLine(`Backed up existing ${displayName} MCP config to ${result.backupPath}`);
+        }
+        if (result.repaired) {
+            errLine('Repaired the existing SpringBrand entry (updated auth/config to current).');
+        }
+        telemetry.track('checkpoint', { phase: 'registered' });
+        saveConnectContext(harness, telemetry.attemptId);
+        settle(state, telemetry, 'completed', { authMode: resolvedKey ? AuthMode.ApiKey : 'deferred' });
+        const postInstallFailed = installSkillPostSettle(spec, displayName, state, telemetry, options);
+        if (resolvedKey) {
+            // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
+            // `/mcp` is the gateway's only endpoint, so `--url` also decides where the key is checked.
+            const verify = await verifyMcpAuth(resolvedKey, apiBaseFromMcpUrl(mcpUrl.toString()));
+            if (verify.ok) {
+                errLine(spec.copy.verified);
+            }
+            else {
+                errLine(spec.copy.authFailed(verify.reason ?? 'unknown'));
+            }
+        }
+        else if (detectHumanInitiated() && spec.tryLaunch(mcpUrl.toString())) {
+            errLine(spec.copy.launched);
+        }
+        else {
+            errLine(spec.copy.reload);
+        }
+        const note = spec.postConnectNote?.();
+        if (note)
+            errLine(note);
+        reportPostInstallFailure(harness, postInstallFailed, options.onPostInstallFailed);
+    });
+}
+/** Writes mcp.json directly — no `cursor mcp add` exists. */
+export async function connectCursor(options) {
+    await connectConfigFileHarness('cursor', options);
+}
+/** Best-effort: false when no handler/open fails — caller falls back to reload copy. */
+function launchCursorDeeplink(mcpUrl) {
+    const result = openExternalUrl(cursorInstallDeeplink(mcpUrl));
+    return !result.error && result.status === 0;
+}
+/** Total over the non-native harnesses: a new one fails to compile until wired here. */
+const LAUNCH_OVERRIDES = {
+    omp: launchOmpWalkthrough,
+    pi: launchPiWalkthrough,
+    openclaw: launchOpenClawWalkthrough,
+    // Cursor has no chat CLI to launch.
+    cursor: () => {
+        throw new Error('Cursor has no launchable walkthrough. Open Cursor and start chatting.');
+    },
+};
+const isNonNative = (harness) => harness in LAUNCH_OVERRIDES;
+export async function launchAgent(client) {
+    if (isNonNative(client))
+        return void (await LAUNCH_OVERRIDES[client]());
+    await launchNativeMcpClient(requireNative(client));
+}
+/** Total over the non-native harnesses; native harnesses use the descriptor engine. */
+const CONNECTOR_OVERRIDES = {
+    openclaw: async (options) => {
+        await connectOpenClaw(options);
+        return undefined;
+    },
+    cursor: async (options) => {
+        await connectCursor(options);
+        // `connect cursor --launch` still connects; it just cannot launch after.
+        if (options.launch) {
+            errLine('Cursor has no launchable walkthrough. Open Cursor and start chatting.');
+        }
+        return undefined;
+    },
+    omp: async (options) => {
+        await connectConfigFileHarness('omp', options);
+        if (options.launch) {
+            try {
+                await launchOmpWalkthrough();
+            }
+            catch (error) {
+                // Post-settle, like the native walkthrough step: never fail the connect.
+                errLine(error instanceof Error ? error.message : String(error));
+                errLine(finishSetupHint('omp'));
+            }
+        }
+        return undefined;
+    },
+    pi: async (options) => {
+        await connectConfigFileHarness('pi', options);
+        if (options.launch) {
+            try {
+                await launchPiWalkthrough();
+            }
+            catch (error) {
+                errLine(error instanceof Error ? error.message : String(error));
+                errLine(finishSetupHint('pi'));
+            }
+        }
+        return undefined;
+    },
+};
+function requireNative(harness) {
+    const client = NATIVE_BY_HARNESS.get(harness);
+    if (!client)
+        throw new Error(`No native MCP descriptor for ${harness}`);
+    return client;
+}
+export async function connectHarness(harness, options) {
+    if (isNonNative(harness))
+        return CONNECTOR_OVERRIDES[harness](options);
+    return connectNativeMcpClient(requireNative(harness), options);
+}
+function parseMcpUrlOption(options) {
+    let mcpUrl = options.url ?? DEFAULT_MCP_URL;
+    const parsedUrl = URL.parse(mcpUrl);
+    if (mcpUrl.startsWith('-') || !parsedUrl || !['http:', 'https:'].includes(parsedUrl.protocol)) {
+        throw new Error(`Invalid --url value: ${mcpUrl}`);
+    }
+    // Page-minted attempt id rides in on --url. Strip before the URL becomes the MCP
+    // base — registration re-stamps it, and nothing else may carry it.
+    const pageAttemptId = parsedUrl.searchParams.get('connect_attempt_id');
+    let attemptId;
+    if (pageAttemptId !== null) {
+        parsedUrl.searchParams.delete('connect_attempt_id');
+        mcpUrl = parsedUrl.toString();
+        if (z.uuid().safeParse(pageAttemptId).success)
+            attemptId = pageAttemptId;
+    }
+    return { mcpUrl, attemptId };
+}
+/** Bare `connect` offers the picker; `--all` takes the dry-run/uninstall/skip-launch flags. */
+async function connectManyPath(options, mcpUrl, attemptId) {
+    if (options.launch) {
+        throw new Error('--launch is not supported with --all. Connect a single client to launch it.');
+    }
+    const pick = !options.all;
+    const humanInitiated = pick && detectHumanInitiated();
+    if (pick && !humanInitiated) {
+        errLine('No terminal detected: connecting every detected harness (same as sp connect --all).');
+    }
+    const exitCode = await runConnectAll({
+        apiKey: options.apiKey,
+        mcpUrl,
+        attemptId,
+        dryRun: options.dryRun ?? false,
+        uninstall: options.uninstall ?? false,
+        noLaunch: options.skipLaunch === true,
+        pick: humanInitiated,
+        verbose: options.verbose ?? false,
+    });
+    // Preserve the 130 runGuarded set on Ctrl+C.
+    if (!process.exitCode)
+        process.exitCode = exitCode;
+}
+async function connectSingleClient(client, options, mcpUrl, attemptId) {
+    const connectOptions = {
+        apiKey: options.apiKey,
+        mcpUrl,
+        launch: options.launch ?? false,
+        attemptId,
+        // A key that the install cannot use leaves only a browser hop no agent can finish.
+        keyAuthOnly: !detectHumanInitiated() && !!validatedApiKey(options.apiKey),
+        // Only here: a missing harness rescues via the CLI (PF-3707).
+        fallbackWhenMissing: true,
+        verbose: options.verbose ?? false,
+    };
+    if (!ALL_HARNESSES.includes(client)) {
+        throw new Error('Unsupported client: ' + client + '. Supported clients: ' + ALL_HARNESSES.join(', '));
+    }
+    const gate = await gateApiKey({
+        apiKey: options.apiKey,
+        mcpUrl,
+        retryCommand: `sp connect ${client}`,
+        mode: 'single',
+        attemptId,
+    });
+    if (gate === 'blocked') {
+        process.exitCode = 1;
+        return;
+    }
+    await connectHarness(client, connectOptions);
+}
+export function registerConnect(program) {
+    program
+        .command('connect')
+        .description('Connect SpringBrand to an AI agent')
+        .argument('[client]', `Agent client to connect (${ALL_HARNESSES.join(', ')}); omit to pick from the agents detected on this machine`)
+        .option('--all', 'Detect and connect every supported harness found on this machine')
+        .option('--dry-run', 'Print planned writes per harness without touching anything (--all only)')
+        .option('--uninstall', 'Remove SpringBrand entries written by connect --all')
+        .option('--skip-launch', 'Skip the end-of-install agent launch (--all only)')
+        .option('--api-key <apiKey>', 'SpringBrand API key to persist for the installed skill')
+        .option('--launch', 'Launch the agent and start the SpringBrand walkthrough')
+        .option('--url <mcpUrl>', 'MCP endpoint override')
+        .option('--verbose', 'Print the full npm and skills output instead of only on failure')
+        .action(async (client, options) => {
+        if (options.apiKey && !validateKeyFormat(options.apiKey)) {
+            throw new Error('Invalid --api-key value');
+        }
+        const { mcpUrl, attemptId } = parseMcpUrlOption(options);
+        if (options.all) {
+            if (client) {
+                throw new Error('Pass either a client or --all, not both.');
+            }
+            await connectManyPath(options, mcpUrl, attemptId);
+            return;
+        }
+        if (options.dryRun || options.uninstall || options.skipLaunch) {
+            throw new Error('--dry-run, --uninstall and --skip-launch are only supported with --all.');
+        }
+        if (!client) {
+            await connectManyPath(options, mcpUrl, attemptId);
+            return;
+        }
+        await connectSingleClient(client, options, mcpUrl, attemptId);
+        // Deferred to here so the notice lands after install output, not interleaved with it.
+        emitNotice();
+    });
+}
+//# sourceMappingURL=connect.js.map