@tiny-fish/cli 0.45.1 → 0.45.2-next.356

package/dist/commands/connect.js

@@ -1,855 +1,13 @@
-import spawn from 'cross-spawn';
-import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, } from '../lib/auth.js';
-import { CURSOR_SKILL_TARGET, KEYLESS_ONBOARDING_PROMPT, OPENCLAW, openclawSkillInstallArgs, NATIVE_BY_HARNESS, launchNativeMcpClient, launchOmpWalkthrough, launchPiWalkthrough, launchOpenClawWalkthrough, openExternalUrl, } from '../lib/connect-clients.js';
-import { captureStdio, capturedOutput, installTinyFishCli, 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, readCursorTinyfishEntry, writeCursorMcpConfig, } from '../lib/cursor-config.js';
+import { validateKeyFormat, validatedApiKey } from '../lib/auth.js';
 import { runConnectAll } from '../lib/connect-all.js';
-import { ompMcpPath, readOmpTinyfishEntry, writeOmpMcpConfig } from '../lib/omp-config.js';
-import { PI_ADAPTER_INSTALL_COMMAND, piMcpAdapterState, piSkillDirMismatch, piMcpPath, readPiTinyfishEntry, writePiMcpConfig, } from '../lib/pi-config.js';
-import { ALL_HARNESSES, AuthMode, HARNESS_DISPLAY_NAMES, RELOAD_ACTION, } from '../lib/harness-detect.js';
+import { ALL_HARNESSES } from '../lib/harness-detect.js';
 import { detectHumanInitiated } from '../lib/harness.js';
-import { TINYFISH_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 { errLine } from '../lib/output.js';
 import { z } from 'zod';
-import { verifyMcpAuth, verifyMcpHealth } 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) {
-        // Cause only: headless refuses below, so this must not promise a sign-in (PF-3803).
-        errLine(`Could not export TINYFISH_API_KEY (${error instanceof Error ? error.message : String(error)}).`);
-        return false;
-    }
-    process.env[TINYFISH_API_KEY_VAR] = apiKey;
-    if (deferOutro) {
-        deferOutro('Exported TINYFISH_API_KEY to your shell profile — restart your agents (or open a new ' +
-            'terminal) before use.');
-    }
-    else {
-        errLine(`Exported TINYFISH_API_KEY to your shell profile — ${displayName} reads the key from there, ` +
-            'so restart it (or open a new terminal) before use.');
-    }
-    return true;
-}
-function resolveKeyedAdd(client, storedKey, keyAuthSupported, keyAuthOnly, 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)) {
-        if (keyAuthOnly)
-            refuseFailedKeyExport(client);
-        errLine(`Signing in to ${client.displayName} instead.`);
-        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'
-        : `TinyFish does not sign in to ${client.displayName} any other way`;
-    const rerun = `re-run: tinyfish connect ${client.connectClient}`;
-    if (!client.keyAuth) {
-        throw new ConnectStepError(`${client.displayName} cannot take a TinyFish API key, and ${noSignIn}. ` +
-            `Run: tinyfish connect ${client.connectClient}`, 'key_auth_unsupported');
-    }
-    if (!keyAuthSupported || headless) {
-        throw new ConnectStepError(`This ${client.displayName} install cannot take a TinyFish API key, and ${noSignIn}. ` +
-            `Update it, then ${rerun}`, 'harness_too_old');
-    }
-    throw new ConnectStepError(`Connecting ${client.displayName} needs a TinyFish API key, and ${noSignIn}. ` +
-        `Run: tinyfish auth login, then ${rerun}`, 'invalid_config', { failureDetail: 'keyless_install_refused' });
-}
-/** Headless has no sign-in to degrade to, and the harness version is not the fault (PF-3803). */
-function refuseFailedKeyExport(client) {
-    // Never names a file: on Windows the write is `setx`, not a shell profile.
-    throw new ConnectStepError(`Could not save ${TINYFISH_API_KEY_VAR} to your environment, so ${client.displayName} has no ` +
-        `way to read your key. Fix that, then re-run: tinyfish connect ${client.connectClient}`, 'invalid_config', { failureDetail: 'key_export_failed' });
-}
-/** 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;
-    // No status means the network failed, not the key.
-    if (verified.status === undefined) {
-        throw new ConnectStepError(`Could not reach TinyFish 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 TinyFish API key was rejected (${verified.code ?? 'unknown'}), so it was not ` +
-        `written to ${displayName}. Run: tinyfish auth login`, 'invalid_config', { failureDetail: `key_rejected status=${verified.status}` });
-}
-async function requireKeylessMcp(mcpUrl) {
-    if ((await verifyMcpHealth(mcpUrl, true)).ok)
-        return;
-    throw new ConnectStepError('TinyFish keyless Search is unavailable', 'invalid_config');
-}
-/** 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 TinyFish CLI instead.`);
-    const outcome = await runCliFallback({
-        apiKey: options.apiKey,
-        verbose: options.verbose ?? false,
-        prompt: detectHumanInitiated() ? createStdinPrompt() : undefined,
-        retryCommand: `npx @tiny-fish/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 TinyFish CLI is installed and working.');
-    errLine('Using a different agent? Run: tinyfish connect --all');
-}
-/** Resolved before the removals, so a refusal strands no registration. */
-async function prepareInstallAuth(client, options, keyAuthSupported) {
-    // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
-    const storedKey = validatedApiKey(options.apiKey);
-    const keyedAdd = resolveKeyedAdd(client, storedKey, keyAuthSupported, options.keyAuthOnly === true, options.deferOutro);
-    const keylessArgs = !storedKey ? client.keylessAddArgs : undefined;
-    const directInstall = !storedKey ? client.prepareKeylessInstall?.() : undefined;
-    let keyless = !!directInstall;
-    let buildAddArgs;
-    if (keyedAdd) {
-        buildAddArgs = (mcpUrl) => keyedAdd.spec.addArgs(mcpUrl, keyedAdd.key);
-    }
-    else if (keylessArgs && keyAuthSupported) {
-        buildAddArgs = keylessArgs;
-        keyless = true;
-    }
-    else if (keylessArgs && options.authTimeoutMs !== undefined) {
-        refuseKeylessInstall(client, false, true);
-    }
-    else if (!directInstall) {
-        buildAddArgs = 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, keyless, buildAddArgs, directInstall };
-}
-/** 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,
-    };
-}
-function performDirectInstall(client, install, mcpUrl) {
-    const registered = install.register(mcpUrl.toString());
-    if (registered.ok)
-        return { seededHome: install.home };
-    const detail = registered.detail ? `: ${registered.detail}` : '';
-    throw new ConnectStepError(`${client.displayName} reported success but TinyFish is not enabled there${detail}.`, 'invalid_config', { failureDetail: registered.tag });
-}
-/** Returns the seeded-credential note when a key was written into a user-owned file. */
-function performMcpAdd(client, options, plan, attemptId) {
-    const { keyedAdd, buildAddArgs, directInstall } = 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 TinyFish to ${client.displayName}...`);
-    if (directInstall)
-        return performDirectInstall(client, directInstall, mcpUrl);
-    if (!buildAddArgs)
-        throw new Error(`No MCP add arguments exist for ${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 TinyFish to ${client.displayName}`, addResult, interactiveAdd && options.authTimeoutMs !== undefined));
-    }
-    const registration = seeded?.confirmRegistered();
-    if (registration && !registration.ok) {
-        failAdd(() => new ConnectStepError(`${client.displayName} reported success but TinyFish 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 TinyFish...');
-    const loginResult = spawn.sync(client.command, [...pendingLogin], {
-        stdio: 'inherit',
-        timeout: options.authTimeoutMs,
-    });
-    if (loginResult.error || loginResult.status !== 0) {
-        throw signInStepError(`Could not authenticate TinyFish in ${client.displayName}`, loginResult, options.authTimeoutMs !== undefined);
-    }
-}
-function announceAuthNotes(useKeyAuth, degradedNotes, seededNote) {
-    if (useKeyAuth) {
-        errLine(degradedNotes?.keyed ?? 'Using your stored TinyFish 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, useKeyless, loginDegraded, loginArgs, probeAuthenticated } = ctx;
-    if (useKeyless) {
-        errLine('Using keyless TinyFish Search — no account or browser sign-in needed.');
-        return { authMode: AuthMode.Keyless, signInDeferred: false };
-    }
-    // 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;
-        const useKeyless = plan.keyless;
-        if (useKeyless)
-            await requireKeylessMcp(options.mcpUrl);
-        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,
-            useKeyless,
-            loginDegraded,
-            loginArgs,
-            probeAuthenticated,
-            seededNote,
-        });
-        state.authMode = authMode;
-        // Registration/OAuth make MCP work; the steps below 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 (`TinyFish is configured in ${client.displayName}. ${client.displayName} will ask you ` +
-            'to sign in to TinyFish the first time you use it.');
-    }
-    return (`TinyFish 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 {
-        // Above every step: a Ctrl+C below must not lose a registration already reported (PF-3803).
-        saveConnectContext(client.connectClient, telemetry.attemptId, state.authMode);
-        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' });
-            });
-        }
-        if (client.extraPostInstall && state.authMode !== AuthMode.Keyless) {
-            await attempt('plugin_install', () => {
-                const pluginVersion = client.extraPostInstall?.({
-                    apiKey: validatedApiKey(options.apiKey),
-                    verbose: options.verbose ?? false,
-                    seededHome,
-                });
-                telemetry.track('checkpoint', { phase: 'plugin_installed', pluginVersion });
-            });
-        }
-        if (state.authMode !== AuthMode.Keyless) {
-            await attempt('authentication', () => {
-                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();
-                }, state.authMode === AuthMode.Keyless ? KEYLESS_ONBOARDING_PROMPT : undefined);
-            });
-        }
-    }
-    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;
-    }
-    installTinyFishCli({ 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 TinyFish 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 TinyFish 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('TinyFish 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 = 'TinyFish is configured in pi. Restart pi, then run `/mcp-auth tinyfish` 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 TinyFish 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 TinyFish 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 TinyFish 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 = 'TinyFish is configured in omp. Open omp and sign in to TinyFish when prompted, or run ' +
-    '`/mcp reauth tinyfish` there.';
-const CONFIG_FILE_HARNESSES = {
-    cursor: {
-        skillTarget: CURSOR_SKILL_TARGET,
-        registeredUrl: () => readCursorTinyfishEntry().url,
-        write: writeCursorMcpConfig,
-        configPath: cursorMcpPath,
-        tryLaunch: launchCursorDeeplink,
-        copy: {
-            verified: "TinyFish is connected and verified (health+auth). Reload the Cursor window (or restart cursor-agent) and it's live.",
-            authFailed: (reason) => `TinyFish is configured, but the authenticated check failed (${reason}). ` +
-                'Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish connect cursor',
-            launched: 'Cursor should pop a TinyFish install confirmation — approve it, then sign in when prompted.',
-            reload: 'TinyFish 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: () => readOmpTinyfishEntry()?.url,
-        write: writeOmpMcpConfig,
-        configPath: ompMcpPath,
-        // No install deeplink exists; the keyless copy carries the sign-in.
-        tryLaunch: () => false,
-        copy: {
-            verified: "TinyFish is connected and verified (health+auth). Restart omp and it's live.",
-            authFailed: (reason) => `TinyFish is configured, but the authenticated check failed (${reason}). ` +
-                'Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish connect omp',
-            launched: OMP_KEYLESS_COPY,
-            reload: OMP_KEYLESS_COPY,
-        },
-    },
-    pi: {
-        skillTarget: { skillAgent: 'pi', displayName: HARNESS_DISPLAY_NAMES.pi },
-        registeredUrl: () => readPiTinyfishEntry().url,
-        write: writePiMcpConfig,
-        configPath: piMcpPath,
-        // No install deeplink exists; the copy carries the restart instead.
-        tryLaunch: () => false,
-        postConnectNote: piPostConnectNotes,
-        copy: {
-            verified: "TinyFish is connected and verified (health+auth). Restart pi and it's live.",
-            authFailed: (reason) => `TinyFish is configured, but the authenticated check failed (${reason}). ` +
-                'Fix: rotate/re-enter your key with `tinyfish auth login`, then re-run: tinyfish 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' });
-        const resolveAuth = async () => {
-            let resolvedKey = validatedApiKey(options.apiKey);
-            const keyless = !resolvedKey && harness === 'omp';
-            if (keyless) {
-                await requireKeylessMcp(options.mcpUrl);
-            }
-            else {
-                state.stage = 'authentication';
-                ensureCliAuthenticated(harness, options.apiKey, {
-                    interactiveLogin: options.authTimeoutMs === undefined,
-                });
-                resolvedKey = validatedApiKey(options.apiKey);
-                telemetry.track('checkpoint', { phase: 'authenticated' });
-                if (!resolvedKey) {
-                    errLine('Ignoring the stored API key: invalid format. Run: tinyfish auth login');
-                }
-            }
-            return { resolvedKey, keyless };
-        };
-        const { resolvedKey, keyless } = await resolveAuth();
-        state.stage = 'registration';
-        errLine(`Adding TinyFish 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: tinyfish 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 TinyFish entry (updated auth/config to current).');
-        }
-        telemetry.track('checkpoint', { phase: 'registered' });
-        let authMode = keyless ? AuthMode.Keyless : 'deferred';
-        if (resolvedKey)
-            authMode = AuthMode.ApiKey;
-        state.authMode = authMode;
-        if (keyless)
-            saveConnectContext(harness, telemetry.attemptId, AuthMode.Keyless);
-        else
-            saveConnectContext(harness, telemetry.attemptId);
-        settle(state, telemetry, 'completed', { authMode });
-        const postInstallFailed = installSkillPostSettle(spec, displayName, state, telemetry, options);
-        if (keyless) {
-            errLine(`TinyFish keyless Search is connected in ${displayName}.`);
-        }
-        else if (resolvedKey) {
-            // Deeplink would embed the key in a URL (process args, LaunchServices logs) — reload instead.
-            const verify = await verifyMcpAuth(resolvedKey, apiBaseFromMcpUrl(options.mcpUrl));
-            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);
-    });
-    return state.authMode;
-}
-/** 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) => {
-        const authMode = await connectConfigFileHarness('omp', options);
-        if (options.launch) {
-            try {
-                await launchOmpWalkthrough(undefined, authMode === AuthMode.Keyless ? KEYLESS_ONBOARDING_PROMPT : undefined);
-            }
-            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 authMode;
-    },
-    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);
-}
+import { DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
+import { connectHarness } from '../lib/connect-harness.js';
 function parseMcpUrlOption(options) {
     let mcpUrl = options.url ?? DEFAULT_MCP_URL;
     const parsedUrl = URL.parse(mcpUrl);