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

package/dist/lib/connect-native.js

@@ -0,0 +1,389 @@
+import spawn from 'cross-spawn';
+import { CONNECT_SOURCE, persistApiKeyToEnvironment, saveConnectContext, validatedApiKey, } from './auth.js';
+import { KEYLESS_ONBOARDING_PROMPT, launchNativeMcpClient, } from './connect-clients.js';
+import { captureStdio, capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
+import { ensureCliAuthenticated } from './connect-auth.js';
+import { installWebSkill } from './skill-install.js';
+import { ConnectInterruptedError, ConnectStepError, createConnectTelemetry, runGuarded, settle, SignInTimeoutError, spawnRemoval, spawnStepError, } from './connect-runtime.js';
+import { TINYFISH_API_KEY_VAR } from './constants.js';
+import { AuthMode, RELOAD_ACTION } from './harness-detect.js';
+import { SIGN_IN_PROBES } from './registration-detect.js';
+import { errLine, warnLine } from './output.js';
+import { verifyMcpAuth } from './verify.js';
+import { apiBaseFromMcpUrl } from './mcp-endpoint.js';
+import { finishSetupHint, requireKeylessMcp, requireSupportOrRescue, runCliInstallStep, trackPostInstallFailure, walkthroughPhase, } from './connect-steps.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}` });
+}
+/** 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;
+}
+/** 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 };
+}
+export 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?.();
+    }
+}

package/dist/lib/connect-openclaw.d.ts

@@ -0,0 +1,3 @@
+import { type NativeConnectOptions } from './connect-steps.js';
+/** Skill install only: no key handoff or post-install callback to honour. */
+export declare function connectOpenClaw(options: Omit<NativeConnectOptions, 'keyAuthOnly' | 'onPostInstallFailed'>): Promise<void>;

package/dist/lib/connect-openclaw.js

@@ -0,0 +1,71 @@
+import spawn from 'cross-spawn';
+import { saveConnectContext } from './auth.js';
+import { OPENCLAW, openclawSkillInstallArgs, launchOpenClawWalkthrough, } from './connect-clients.js';
+import { captureStdio, capturedOutput, replay } from './cli-install.js';
+import { ensureCliAuthenticated } from './connect-auth.js';
+import { createConnectTelemetry, runGuarded, settle, spawnStepError, } from './connect-runtime.js';
+import { RELOAD_ACTION } from './harness-detect.js';
+import { errLine } from './output.js';
+import { finishSetupHint, requireSupportOrRescue, runCliInstallStep, trackPostInstallFailure, walkthroughPhase, } from './connect-steps.js';
+/** 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'));
+        }
+    });
+}

package/dist/lib/connect-steps.d.ts

@@ -0,0 +1,38 @@
+import { type TakeHoistedCliInstall } from './cli-install.js';
+import { type ConnectCheckpoint, requireCommandSupport, type AgentClient, type ConnectRunState, type ConnectTelemetry, type SupportedCommand } from './connect-runtime.js';
+import type { WalkthroughOutcome } from './connect-clients.js';
+export interface NativeConnectOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    launch: boolean;
+    attemptId?: string;
+    /** Headless: refuse rather than fall back to an unfinishable browser sign-in. */
+    keyAuthOnly?: boolean;
+    /** Headless --all: bounds sign-in spawns and bars interactive CLI login. */
+    authTimeoutMs?: number;
+    /** Internal only: false leaves the global npm tree untouched. */
+    cliInstall?: boolean;
+    /** Set by `--all`: the CLI install already ran once, upfront. */
+    hoistedCliInstall?: TakeHoistedCliInstall;
+    /** Lets `--all` warn in its summary instead of all-green. */
+    onPostInstallFailed?: () => void;
+    /** Inherit subprocess stdio instead of replaying it only on failure. */
+    verbose?: boolean;
+    /** Set by `--all`: repeated outro lines print once, after the summary. */
+    deferOutro?: (line: string) => void;
+    /** Targeted connects only: --all keeps its per-harness failed row. */
+    fallbackWhenMissing?: boolean;
+}
+export declare function requireKeylessMcp(mcpUrl: string): Promise<void>;
+/** Undefined means the rescue ran; the caller returns immediately. */
+export declare function requireSupportOrRescue(client: SupportedCommand, connectClient: AgentClient, state: ConnectRunState, telemetry: ConnectTelemetry, options: {
+    apiKey?: string;
+    verbose?: boolean;
+    fallbackWhenMissing?: boolean;
+}): Promise<ReturnType<typeof requireCommandSupport> | undefined>;
+/** Consumes the `--all` hoist when present; installs inline otherwise. */
+export declare function runCliInstallStep(options: NativeConnectOptions, telemetry: ConnectTelemetry): void;
+export declare function walkthroughPhase(outcome: WalkthroughOutcome): ConnectCheckpoint;
+export declare function finishSetupHint(connectClient: AgentClient): string;
+/** Warn + report post_install_failed; interrupts are abandonment, not failure. */
+export declare function trackPostInstallFailure(displayName: string, state: ConnectRunState, telemetry: ConnectTelemetry, error: unknown): void;

package/dist/lib/connect-steps.js

@@ -0,0 +1,104 @@
+import { verifyMcpHealth } from './verify.js';
+import { installTinyFishCli } from './cli-install.js';
+import { createStdinPrompt, runCliFallback } from './connect-fallback.js';
+import { detectHumanInitiated } from './harness.js';
+import { errLine } from './output.js';
+import { ConnectInterruptedError, ConnectStepError, HoistedFailureReportedError, finishSetupCommand, requireCommandSupport, settle, stageDurationOf, withStageDuration, } from './connect-runtime.js';
+export async function requireKeylessMcp(mcpUrl) {
+    if ((await verifyMcpHealth(mcpUrl, true)).ok)
+        return;
+    throw new ConnectStepError('TinyFish keyless Search is unavailable', 'invalid_config');
+}
+function isMissingHarness(error) {
+    return error instanceof ConnectStepError && error.failureReason === 'harness_not_installed';
+}
+/** Undefined means the rescue ran; the caller returns immediately. */
+export 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');
+}
+/** 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. */
+export 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' });
+}
+export function walkthroughPhase(outcome) {
+    return outcome === 'printed' ? 'walkthrough_prompt_printed' : 'walkthrough_launched';
+}
+export function finishSetupHint(connectClient) {
+    return `Finish setup with: ${finishSetupCommand(connectClient)}`;
+}
+/** Warn + report post_install_failed; interrupts are abandonment, not failure. */
+export 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)}`);
+}

package/dist/lib/doctor-repairs.js

@@ -1,5 +1,5 @@
 import spawn from 'cross-spawn';
-import { connectHarness } from '../commands/connect.js';
+import { connectHarness } from './connect-harness.js';
 import { OAUTH_SIGN_IN_TIMEOUT_MS } from './connect-all-auth.js';
 import { Registered } from './harness-detect.js';
 import { detectHumanInitiated } from './harness.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.45.2-next.354",
+  "version": "0.45.2-next.356",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {