@springbrand/cli 0.1.4 → 0.1.5-alpha.2

package/dist/commands/connect.js

@@ -1,9 +1,9 @@
 /** 复刻自 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 { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, } 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 { connectApiKey, ensureCliAuthenticated } from '../lib/connect-auth.js';
 import { createStdinPrompt, runCliFallback } from '../lib/connect-fallback.js';
 import { installWebSkill, removeWebSkill } from '../lib/skill-install.js';
 import { ConnectInterruptedError, ConnectStepError, HoistedFailureReportedError, createConnectTelemetry, finishSetupCommand, requireCommandSupport, runGuarded, settle, SignInTimeoutError, spawnStepError, stageDurationOf, withStageDuration, spawnRemoval, } from '../lib/connect-runtime.js';
@@ -16,12 +16,14 @@ import { ALL_HARNESSES, AuthMode, HARNESS_DISPLAY_NAMES, RELOAD_ACTION, } from '
 import { detectHumanInitiated } from '../lib/harness.js';
 import { SPRINGBRAND_API_KEY_VAR } from '../lib/constants.js';
 import { emitNotice } from '../lib/notice.js';
-import { detectLegacyPlugin, legacyPluginHint, SIGN_IN_PROBES } from '../lib/registration-detect.js';
-import { errLine, warnLine } from '../lib/output.js';
+import { detectLegacyPlugin, detectRegistrations, legacyPluginHint, SIGN_IN_PROBES } from '../lib/registration-detect.js';
+import { errLine, out, warnLine } from '../lib/output.js';
 import { z } from 'zod';
-import { verifyMcpAuth } from '../lib/verify.js';
+import { verifyMcpAuth, verifyMcpHealth } from '../lib/verify.js';
 import { gateApiKey } from '../lib/connect-preflight.js';
-import { apiBaseFromMcpUrl, DEFAULT_MCP_URL, mcpServerName } from '../lib/mcp-endpoint.js';
+import { apiBaseFromMcpUrl, DEFAULT_MCP_URL, endpointOf, mcpServerName } from '../lib/mcp-endpoint.js';
+import { harnessOauthAction } from '../lib/harness-spec.js';
+import { buildConnectResult } from '../lib/connect-result.js';
 function removeExistingRegistration(client, removal, verbose) {
     const result = spawnRemoval(client.command, removal.args);
     if (result.status === 0)
@@ -42,9 +44,7 @@ function exportApiKey(apiKey, displayName, deferOutro) {
         persistApiKeyToEnvironment(apiKey);
     }
     catch (error) {
-        errLine(`Could not export SPRINGBRAND_API_KEY (${error instanceof Error ? error.message : String(error)}); ` +
-            'signing in instead.');
-        return false;
+        throw new ConnectStepError('Could not persist the API-key environment variable. OAuth was not started.', 'invalid_config');
     }
     process.env[SPRINGBRAND_API_KEY_VAR] = apiKey;
     if (deferOutro) {
@@ -165,7 +165,9 @@ async function runMissingHarnessFallback(displayName, connectClient, state, tele
 /** 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 storedKey = connectApiKey(options.apiKey);
+    if (storedKey && (!keyAuthSupported || !client.keyAuth))
+        throw new ConnectStepError('This Host version cannot install API-key authentication. Update the Host and retry with the same key.', 'key_auth_unsupported');
     const candidate = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.deferOutro);
     // Direct seeded clients need their own pre-write probe. Codex and other env-backed clients
     // have already passed the shared connect preflight before this function is reached.
@@ -183,7 +185,7 @@ async function prepareInstallAuth(client, options, keyAuthSupported) {
 /** 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 };
+        return { stdio: ['inherit', 2, 2], timeout: options.authTimeoutMs ?? 60_000 };
     if (!seeded)
         return captureStdio(options.verbose ?? false);
     return {
@@ -207,7 +209,7 @@ function performMcpAdd(client, options, plan, attemptId) {
     // 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);
+    const interactiveAdd = !(client.nonInteractiveAdd || keyedAdd || options.deferOAuth);
     // 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.
@@ -237,8 +239,8 @@ function performMcpAdd(client, options, plan, attemptId) {
 function performLoginStep(client, pendingLogin, options) {
     errLine('Signing in to SpringBrand...');
     const loginResult = spawn.sync(client.command, [...pendingLogin], {
-        stdio: 'inherit',
-        timeout: options.authTimeoutMs,
+        stdio: ['inherit', 2, 2],
+        timeout: options.authTimeoutMs ?? 60_000,
     });
     if (loginResult.error || loginResult.status !== 0) {
         throw signInStepError(`Could not authenticate SpringBrand in ${client.displayName}`, loginResult, options.authTimeoutMs !== undefined);
@@ -256,17 +258,20 @@ function announceAuthNotes(useKeyAuth, degradedNotes, seededNote) {
         errLine(degradedNotes.deferred);
     }
 }
+function loginArgsFor(client, mcpUrl) {
+    return client.loginArgs?.map((arg) => arg === 'springbrand' ? mcpServerName(mcpUrl) : arg);
+}
 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?.();
+    const addSignedIn = useKeyAuth ? undefined : 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;
+    const retryLogin = addSignedIn !== true;
+    const pendingLogin = !useKeyAuth && !options.deferOAuth && retryLogin ? loginArgs : undefined;
     let signInDeferred = !useKeyAuth && !addSignedIn && !pendingLogin;
     if (pendingLogin) {
         state.stage = 'client_oauth';
@@ -286,7 +291,8 @@ function completeAuthFlow(client, options, state, telemetry, ctx) {
 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];
+    const nativeProbe = SIGN_IN_PROBES[client.connectClient];
+    const probeAuthenticated = nativeProbe ? () => nativeProbe(options.mcpUrl) : undefined;
     await runGuarded(state, telemetry, async () => {
         telemetry.track('started');
         const support = await requireSupportOrRescue(client, client.connectClient, state, telemetry, options);
@@ -318,7 +324,7 @@ async function connectNativeMcpClient(client, options) {
             try {
                 client.pluginInstall({
                     mcpUrl: pluginUrl.toString(),
-                    apiKey: useKeyAuth ? validatedApiKey(options.apiKey) : undefined,
+                    apiKey: useKeyAuth ? connectApiKey(options.apiKey) : undefined,
                 });
             }
             catch (error) {
@@ -345,7 +351,7 @@ async function connectNativeMcpClient(client, options) {
                     useKeyAuth,
                     loginDegraded,
                     // The Plugin names its server after the endpoint's environment.
-                    loginArgs: loginDegraded ? undefined : ['mcp', 'login', mcpServerName(options.mcpUrl)],
+                    loginArgs: loginDegraded ? undefined : loginArgsFor(client, options.mcpUrl),
                     probeAuthenticated,
                     seededNote: undefined,
                 });
@@ -360,7 +366,7 @@ async function connectNativeMcpClient(client, options) {
             removeExistingRegistration(client, scopedRemoval(removal, options.mcpUrl), 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;
+        const loginArgs = loginDegraded ? undefined : loginArgsFor(client, options.mcpUrl);
         // A probed client authenticates inside `mcp add` too, so a failure there is either.
         state.stage =
             loginArgs && !probeAuthenticated ? 'registration' : 'registration_or_authentication';
@@ -380,15 +386,18 @@ async function connectNativeMcpClient(client, options) {
     });
     return state.authMode;
 }
-function connectedLine(client, signInDeferred) {
+function connectedLine(client, signInDeferred, mcpUrl) {
     // The CLI never observes deferred auth, so don't claim "connected".
     if (signInDeferred) {
+        const action = harnessOauthAction(client.connectClient, mcpUrl);
+        if (action)
+            return `SpringBrand is configured in ${client.displayName}, but authentication is pending. ${action}`;
         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, ` +
+    return (`SpringBrand configuration is installed. 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.
@@ -421,7 +430,7 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
         if (extraPostInstall) {
             await attempt('plugin_install', () => {
                 extraPostInstall({
-                    apiKey: validatedApiKey(options.apiKey),
+                    apiKey: connectApiKey(options.apiKey),
                     verbose: options.verbose ?? false,
                     seededHome,
                 });
@@ -432,7 +441,7 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
             });
         }
         // Before auth: a failed sign-in must not lose the harness record.
-        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
+        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode, options.mcpUrl);
         if (cliAuthRequired) {
             await attempt('authentication', () => {
                 // A set timeout means headless; never shell an interactive login.
@@ -448,13 +457,18 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
         if (!options.launch) {
             // Under --all the summary replaces this; sign-in hints still print.
             if (signInDeferred || !options.deferOutro)
-                errLine(connectedLine(client, signInDeferred));
+                errLine(connectedLine(client, signInDeferred, options.mcpUrl));
         }
         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);
+                if (signInDeferred) {
+                    const action = harnessOauthAction(client.connectClient, options.mcpUrl);
+                    if (action)
+                        errLine(action);
+                    else if (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.
@@ -470,7 +484,7 @@ async function runPostInstallSteps(client, options, state, telemetry, signInDefe
         failed = true;
     }
     if (failed) {
-        errLine(finishSetupHint(client.connectClient));
+        errLine(finishSetupHint(client.connectClient, options.mcpUrl));
         options.onPostInstallFailed?.();
     }
 }
@@ -502,8 +516,8 @@ function runCliInstallStep(options, telemetry) {
 function walkthroughPhase(outcome) {
     return outcome === 'printed' ? 'walkthrough_prompt_printed' : 'walkthrough_launched';
 }
-function finishSetupHint(connectClient) {
-    return `Finish setup with: ${finishSetupCommand(connectClient)}`;
+function finishSetupHint(connectClient, mcpUrl) {
+    return `Finish setup with: ${finishSetupCommand(connectClient, mcpUrl)}`;
 }
 /** Warn + report post_install_failed; interrupts are abandonment, not failure. */
 function trackPostInstallFailure(displayName, state, telemetry, error) {
@@ -530,11 +544,15 @@ export async function connectOpenClaw(options) {
         settled: false,
         harnessDegraded: false,
     };
+    let authMode;
     await runGuarded(state, telemetry, async () => {
         telemetry.track('started');
         const support = await requireSupportOrRescue(OPENCLAW, 'openclaw', state, telemetry, options);
         if (!support)
             return;
+        if (!connectApiKey(options.apiKey)) {
+            throw new ConnectStepError('OpenClaw requires a SpringBrand API key; keyless OAuth is not supported by this Host.', 'key_auth_unsupported');
+        }
         telemetry.setHarnessVersion(support.harnessVersion);
         telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
         if (options.cliInstall !== false) {
@@ -558,6 +576,7 @@ export async function connectOpenClaw(options) {
             interactiveLogin: options.authTimeoutMs === undefined,
             mcpUrl: options.mcpUrl,
         });
+        authMode = AuthMode.ApiKey;
         telemetry.track('checkpoint', { phase: 'authenticated' });
         saveConnectContext('openclaw', telemetry.attemptId);
         // For openclaw the skill install and auth ARE functional; only the walkthrough is cosmetic.
@@ -580,9 +599,10 @@ export async function connectOpenClaw(options) {
         }
         catch (error) {
             trackPostInstallFailure('OpenClaw', state, telemetry, error);
-            errLine(finishSetupHint('openclaw'));
+            errLine(finishSetupHint('openclaw', options.mcpUrl));
         }
     });
+    return authMode;
 }
 const PI_RELOAD_COPY = 'SpringBrand is configured in pi. Restart pi, then run `/mcp-auth springbrand` there if it asks you ' +
     'to sign in.';
@@ -620,11 +640,11 @@ const CONFIG_FILE_HARNESSES = {
         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.",
+            verified: "The API key was accepted; Host loading is still unverified. 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.',
+            reload: 'SpringBrand is configured. Reload the Cursor window, then approve/sign in under Settings → MCP.',
         },
     },
     omp: {
@@ -636,7 +656,7 @@ const CONFIG_FILE_HARNESSES = {
         // 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.",
+            verified: "The API key was accepted; Host loading is still unverified. 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,
@@ -652,7 +672,7 @@ const CONFIG_FILE_HARNESSES = {
         tryLaunch: () => false,
         postConnectNote: piPostConnectNotes,
         copy: {
-            verified: "SpringBrand is connected and verified (health+auth). Restart pi and it's live.",
+            verified: "The API key was accepted; Host loading is still unverified. 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,
@@ -666,7 +686,7 @@ const CONFIG_FILE_HARNESSES = {
         configPath: workbuddyMcpPath,
         tryLaunch: () => false,
         copy: {
-            verified: "SpringBrand is connected and verified (health+auth). Restart WorkBuddy and it's live.",
+            verified: "The API key was accepted; Host loading is still unverified. Restart WorkBuddy 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 workbuddy-ai',
             launched: 'SpringBrand is configured. Open WorkBuddy to load the MCP server.',
@@ -690,10 +710,10 @@ function installSkillPostSettle(spec, displayName, state, telemetry, options) {
     }
 }
 /** Prints last: the outro must own the final line. */
-function reportPostInstallFailure(harness, failed, onPostInstallFailed) {
+function reportPostInstallFailure(harness, failed, mcpUrl, onPostInstallFailed) {
     if (!failed)
         return;
-    errLine(finishSetupHint(harness));
+    errLine(finishSetupHint(harness, mcpUrl));
     onPostInstallFailed?.();
 }
 /** Writes the harness's MCP config file itself; no `mcp add` exists. */
@@ -737,12 +757,19 @@ async function connectConfigFileHarness(harness, options) {
         settled: false,
         harnessDegraded: false,
     };
+    let resolvedAuthMode;
     await runGuarded(state, telemetry, async () => {
         telemetry.track('started');
         telemetry.track('checkpoint', { phase: 'prerequisite_ok' });
         // A key lets the config carry an Authorization header. With no key, leave the
         // client on its own native MCP OAuth path; never open the CLI API-key page.
-        const resolvedKey = validatedApiKey(options.apiKey);
+        const rawKey = connectApiKey(options.apiKey);
+        if (rawKey && !validateKeyFormat(rawKey)) {
+            throw new ConnectStepError('The supplied SpringBrand API key is invalid; OAuth was not started.', 'invalid_config', {
+                failureDetail: 'key_rejected_before_oauth',
+            });
+        }
+        const resolvedKey = connectApiKey(options.apiKey);
         if (resolvedKey) {
             state.stage = 'authentication';
             ensureCliAuthenticated(harness, options.apiKey, {
@@ -751,10 +778,6 @@ async function connectConfigFileHarness(harness, options) {
             });
             telemetry.track('checkpoint', { phase: 'authenticated' });
         }
-        // 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);
@@ -774,8 +797,9 @@ async function connectConfigFileHarness(harness, options) {
             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' });
+        saveConnectContext(harness, telemetry.attemptId, resolvedKey ? AuthMode.ApiKey : 'oauth', options.mcpUrl);
+        resolvedAuthMode = resolvedKey ? AuthMode.ApiKey : 'deferred';
+        settle(state, telemetry, 'completed', { authMode: resolvedAuthMode });
         const postInstallFailed = installSkillPostSettle(spec, displayName, state, telemetry, options);
         if (resolvedKey) {
             // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
@@ -797,12 +821,13 @@ async function connectConfigFileHarness(harness, options) {
         const note = spec.postConnectNote?.();
         if (note)
             errLine(note);
-        reportPostInstallFailure(harness, postInstallFailed, options.onPostInstallFailed);
+        reportPostInstallFailure(harness, postInstallFailed, options.mcpUrl, options.onPostInstallFailed);
     });
+    return resolvedAuthMode;
 }
 /** Writes mcp.json directly — no `cursor mcp add` exists. */
 export async function connectCursor(options) {
-    await connectConfigFileHarness('cursor', options);
+    return connectConfigFileHarness('cursor', options);
 }
 /** Best-effort: false when no handler/open fails — caller falls back to reload copy. */
 function launchCursorDeeplink(mcpUrl) {
@@ -831,19 +856,18 @@ export async function launchAgent(client) {
 /** Total over the non-native harnesses; native harnesses use the descriptor engine. */
 const CONNECTOR_OVERRIDES = {
     openclaw: async (options) => {
-        await connectOpenClaw(options);
-        return undefined;
+        return connectOpenClaw(options);
     },
     cursor: async (options) => {
-        await connectCursor(options);
+        const authMode = 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;
+        return authMode;
     },
     omp: async (options) => {
-        await connectConfigFileHarness('omp', options);
+        const authMode = await connectConfigFileHarness('omp', options);
         if (options.launch) {
             try {
                 await launchOmpWalkthrough();
@@ -851,30 +875,30 @@ const CONNECTOR_OVERRIDES = {
             catch (error) {
                 // Post-settle, like the native walkthrough step: never fail the connect.
                 errLine(error instanceof Error ? error.message : String(error));
-                errLine(finishSetupHint('omp'));
+                errLine(finishSetupHint('omp', options.mcpUrl));
             }
         }
-        return undefined;
+        return authMode;
     },
     pi: async (options) => {
-        await connectConfigFileHarness('pi', options);
+        const authMode = await connectConfigFileHarness('pi', options);
         if (options.launch) {
             try {
                 await launchPiWalkthrough();
             }
             catch (error) {
                 errLine(error instanceof Error ? error.message : String(error));
-                errLine(finishSetupHint('pi'));
+                errLine(finishSetupHint('pi', options.mcpUrl));
             }
         }
-        return undefined;
+        return authMode;
     },
     'workbuddy-ai': async (options) => {
-        await connectConfigFileHarness('workbuddy-ai', options);
+        const authMode = await connectConfigFileHarness('workbuddy-ai', options);
         if (options.launch) {
             errLine('WorkBuddy has no launchable CLI walkthrough. Open WorkBuddy and start chatting.');
         }
-        return undefined;
+        return authMode;
     },
 };
 function requireNative(harness) {
@@ -930,6 +954,62 @@ async function connectManyPath(options, mcpUrl, attemptId) {
     if (!process.exitCode)
         process.exitCode = exitCode;
 }
+function safeConnectError(error) {
+    if (error instanceof ConnectStepError) {
+        if (error.message === 'unsupported')
+            return { code: 'unsupported', message: 'This Host is not supported by the CLI.', phase: 'input' };
+        const phase = error.failureReason === 'key_auth_unsupported' || error.failureReason === 'invalid_config'
+            ? 'authentication'
+            : error.failureReason === 'harness_command_unsupported' || error.failureReason === 'harness_too_old'
+                ? 'registration'
+                : 'registration';
+        return {
+            code: error.failureReason,
+            message: error.failureReason === 'key_auth_unsupported'
+                ? 'This Host does not support the requested authentication mode.'
+                : error.failureReason === 'invalid_config'
+                    ? 'The Host configuration could not be updated. Follow the CLI recovery message and retry.'
+                    : 'The Host could not be configured. Follow the CLI recovery message and retry.',
+            phase,
+        };
+    }
+    return { code: 'unexpected_error', message: 'The Host installation did not complete. Retry the connect command.', phase: 'registration' };
+}
+async function singleConnectResult(client, mcpUrl, authMode, installed, apiKey, error) {
+    const health = await verifyMcpHealth(mcpUrl);
+    const key = connectApiKey(apiKey);
+    // A preflight failure must never send the rejected or cross-environment key a
+    // second time merely to build a machine result.
+    const auth = !error && authMode === 'api-key' && key && validateKeyFormat(key)
+        ? await verifyMcpAuth(key, apiBaseFromMcpUrl(mcpUrl))
+        : undefined;
+    let registrationConnected;
+    let registrationMatches = false;
+    let keyMatchesRegistration = false;
+    try {
+        const status = ALL_HARNESSES.includes(client)
+            ? detectRegistrations([client], mcpUrl)[0] : undefined;
+        registrationConnected = status?.connected;
+        registrationMatches = status?.registered === 'yes' && !!status.registeredUrl &&
+            endpointOf(status.registeredUrl) === endpointOf(mcpUrl);
+        keyMatchesRegistration = status?.keyMatchesCliKey === true;
+    }
+    catch {
+        registrationConnected = undefined;
+    }
+    return buildConnectResult({
+        host: client,
+        mcpUrl,
+        authMode,
+        installed,
+        health,
+        auth,
+        registrationConnected,
+        registrationMatches,
+        keyMatchesRegistration,
+        ...(error ? { error: safeConnectError(error) } : {}),
+    });
+}
 async function connectSingleClient(client, options, mcpUrl, attemptId) {
     const connectOptions = {
         apiKey: options.apiKey,
@@ -937,12 +1017,21 @@ async function connectSingleClient(client, options, mcpUrl, attemptId) {
         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,
+        keyAuthOnly: !detectHumanInitiated() && !!connectApiKey(options.apiKey),
+        authTimeoutMs: 60_000,
+        // Machine mode is consumed by the landing agent: install the Host entry and
+        // return its native OAuth action instead of trying to drive an interactive login.
+        deferOAuth: options.json === true,
+        // A selected Host failure never switches clients or auth modes.
+        fallbackWhenMissing: false,
         verbose: options.verbose ?? false,
     };
     if (!ALL_HARNESSES.includes(client)) {
+        if (options.json) {
+            out(await singleConnectResult(String(client), mcpUrl, undefined, false, undefined, new ConnectStepError('unsupported', 'harness_command_unsupported')));
+            process.exitCode = 1;
+            return;
+        }
         throw new Error('Unsupported client: ' + client + '. Supported clients: ' + ALL_HARNESSES.join(', '));
     }
     const gate = await gateApiKey({
@@ -951,8 +1040,12 @@ async function connectSingleClient(client, options, mcpUrl, attemptId) {
         retryCommand: `sp connect ${client}`,
         mode: 'single',
         attemptId,
+        strict: options.json === true,
     });
     if (gate === 'blocked') {
+        if (options.json) {
+            out(await singleConnectResult(client, mcpUrl, connectApiKey(options.apiKey) !== undefined ? AuthMode.ApiKey : undefined, false, options.apiKey, new ConnectStepError('invalid key', 'invalid_config')));
+        }
         process.exitCode = 1;
         return;
     }
@@ -961,7 +1054,21 @@ async function connectSingleClient(client, options, mcpUrl, attemptId) {
     const hint = legacyPluginHint(client, legacy);
     if (hint)
         errLine(hint);
-    await connectHarness(client, connectOptions);
+    let authMode = connectApiKey(options.apiKey) !== undefined ? AuthMode.ApiKey : AuthMode.OAuth;
+    let error;
+    try {
+        authMode = await connectHarness(client, connectOptions) ?? authMode;
+    }
+    catch (caught) {
+        error = caught;
+        if (!options.json)
+            throw caught;
+    }
+    const result = await singleConnectResult(client, mcpUrl, authMode, !error, options.apiKey, error);
+    if (options.json)
+        out(result);
+    if (result.outcome !== 'verified' && process.exitCode !== 130)
+        process.exitCode = 1;
 }
 export function registerConnect(program) {
     program
@@ -975,9 +1082,16 @@ export function registerConnect(program) {
         .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('--json', 'Print one machine-readable bootstrap result')
         .option('--verbose', 'Print the full npm and skills output instead of only on failure')
         .action(async (client, options) => {
         if (options.apiKey && !validateKeyFormat(options.apiKey)) {
+            if (options.json && client && ALL_HARNESSES.includes(client)) {
+                const { mcpUrl } = parseMcpUrlOption(options);
+                out(await singleConnectResult(client, mcpUrl, AuthMode.ApiKey, false, options.apiKey, new ConnectStepError('invalid key', 'invalid_config')));
+                process.exitCode = 1;
+                return;
+            }
             throw new Error('Invalid --api-key value');
         }
         const { mcpUrl, attemptId } = parseMcpUrlOption(options);
@@ -985,9 +1099,15 @@ export function registerConnect(program) {
             if (client) {
                 throw new Error('Pass either a client or --all, not both.');
             }
+            if (options.json) {
+                throw new Error('--json requires a single client; --all has per-Host text output');
+            }
             await connectManyPath(options, mcpUrl, attemptId);
             return;
         }
+        if (options.json && !client) {
+            throw new Error('--json requires a single client; pass a client name');
+        }
         if (options.dryRun || options.uninstall || options.skipLaunch) {
             throw new Error('--dry-run, --uninstall and --skip-launch are only supported with --all.');
         }