@tiny-fish/cli 0.19.1-next.175 → 0.19.1-next.177

package/dist/commands/connect.d.ts

@@ -1,12 +1,9 @@
 import { Command } from "commander";
+import { type AgentClient } from "../lib/connect-runtime.js";
 export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
-export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw" | "opencode";
-/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
-export declare class ConnectInterruptedError extends Error {
-}
 interface NativeConnectOptions {
     apiKey?: string;
     mcpUrl: string;

package/dist/commands/connect.js

@@ -1,8 +1,8 @@
-import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
-import { CONNECT_ATTEMPT_ENV, CONNECT_SOURCE, isAttemptId, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, takePendingConnectAttempt, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
-import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
+import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
+import { commandNotFound, ConnectInterruptedError, createConnectTelemetry, requireCommandSupport, runGuarded, settle, throwIfInterrupted, NON_INTERACTIVE_TIMEOUT_MS, } from "../lib/connect-runtime.js";
+import { TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
 import { detectHumanInitiated } from "../lib/harness.js";
@@ -10,11 +10,8 @@ import { emitNotice } from "../lib/notice.js";
 import { errLine, sanitizeLine } from "../lib/output.js";
 import { codexOauthCompleted } from "../lib/registration-detect.js";
 import { z } from "zod";
-import { installSignalGuard } from "../lib/signals.js";
-import { postConnectEvent, telemetryDisabled } from "../lib/setup-telemetry.js";
 import { verifyMcpAuth } from "../lib/verify.js";
 export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
-const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 // An old install is only one reason a flag can go unseen, so no message asserts the cause.
@@ -74,72 +71,6 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
     "want to search and wait for my reply before using TinyFish Search. Show me the results, ask " +
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
     "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
-/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
-export class ConnectInterruptedError extends Error {
-}
-class PrerequisiteError extends Error {
-    failureReason;
-    harnessVersion;
-    constructor(message, failureReason, opts) {
-        super(message, { cause: opts?.cause });
-        this.failureReason = failureReason;
-        this.harnessVersion = opts?.harnessVersion;
-    }
-}
-function throwIfInterrupted(result) {
-    // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
-    // network as the user walking away. A timeout is a failure and must report as one.
-    if (result.error?.code === "ETIMEDOUT")
-        return;
-    if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
-        throw new ConnectInterruptedError("Setup interrupted");
-    }
-}
-/** Terminal events exactly once, whichever of flow or signal handler wins. */
-function settle(state, telemetry, stage, detail) {
-    if (state.settled)
-        return;
-    state.settled = true;
-    telemetry.track(stage, detail);
-}
-// Raw-mode children still surface via throwIfInterrupted; cooked-mode stages
-// (npm/npx/OAuth waits) land here.
-function installConnectSignalGuard(state, telemetry) {
-    return installSignalGuard(async () => {
-        if (!state.settled) {
-            settle(state, telemetry, "aborted", { failedStage: state.stage });
-            errLine("Setup interrupted — run the command again to finish.");
-        }
-        // Settled spans the whole post-install phase; the `completed` POST may still be in flight.
-        await telemetry.flush();
-    });
-}
-/** Shared terminal handling: interrupted → aborted, else failed. */
-async function runGuarded(state, telemetry, body) {
-    const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
-    try {
-        await body();
-    }
-    catch (error) {
-        if (error instanceof ConnectInterruptedError) {
-            settle(state, telemetry, "aborted", { failedStage: state.stage });
-            errLine("Setup interrupted — run the command again to finish.");
-            process.exitCode = 130;
-            return;
-        }
-        settle(state, telemetry, "failed", {
-            failedStage: state.stage,
-            ...(error instanceof PrerequisiteError
-                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
-                : {}),
-        });
-        throw error;
-    }
-    finally {
-        uninstallSignalGuard();
-        await telemetry.flush();
-    }
-}
 const CLAUDE_CODE = {
     command: "claude",
     connectClient: "claude-code",
@@ -291,109 +222,6 @@ const OPENCLAW = {
         unavailableMessage: OPENCLAW_SKILL_UNAVAILABLE_MESSAGE,
     },
 };
-/**
- * One page-minted id seeds one install attempt, so `tinyfish onboard` connecting three agents
- * does not report three installs under it. Later connects in the run fall back to a random id.
- */
-function takeSeedAttemptId() {
-    const fromEnv = process.env[CONNECT_ATTEMPT_ENV];
-    // Both sources are read-and-clear, and the delete lands before any subprocess inherits it.
-    delete process.env[CONNECT_ATTEMPT_ENV];
-    const parked = takePendingConnectAttempt();
-    return fromEnv && isAttemptId(fromEnv) ? fromEnv : parked;
-}
-function createConnectTelemetry(mcpUrl, client, opts) {
-    // Consumed even when --url already supplied an id: leaving it behind would let a stale
-    // seed reach the agent this connect launches, or the next connect on this machine.
-    const seeded = takeSeedAttemptId();
-    // A setup-page id (via --url, the env var, or one parked by login) joins "copied the
-    // command" to this install attempt.
-    const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
-    const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
-    const pending = [];
-    async function deliver(body) {
-        // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
-        if (telemetryDisabled())
-            return;
-        // Resolved per event: `tinyfish auth login` writes the config from a subprocess mid-connect.
-        await postConnectEvent({
-            endpoint,
-            body,
-            attempts: 2,
-            apiKey: resolvedApiKey(opts?.apiKey),
-            label: "connect",
-        });
-    }
-    return {
-        attemptId,
-        // Fire-and-forget; awaiting each event stalls setup when telemetry down.
-        track(stage, detail) {
-            pending.push(deliver(JSON.stringify({
-                attempt_id: attemptId,
-                client,
-                stage,
-                failed_stage: detail?.failedStage,
-                phase: detail?.phase,
-                failure_reason: detail?.failureReason,
-                harness_version: detail?.harnessVersion,
-                runtime_platform: process.platform,
-                node_version: process.version,
-                cli_version: CLI_VERSION,
-                // Same signal the usage events carry, so TTY and headless connects can be split.
-                is_human_initiated: detectHumanInitiated(),
-            })));
-        },
-        // Awaited in finally so in-flight events land before exit.
-        async flush() {
-            await Promise.all(pending);
-        },
-    };
-}
-function requireCommandSupport(client) {
-    const result = spawn.sync(client.command, client.supportCheck.args, {
-        encoding: "utf8",
-        // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
-        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
-    if (commandNotFound(result.error)) {
-        throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, "harness_not_installed", { cause: result.error });
-    }
-    if (result.error || result.status !== 0) {
-        throwIfInterrupted(result);
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
-    }
-    // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
-    const output = sanitizeLine(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
-    const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
-    const essential = listed(client.supportCheck.patterns);
-    const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
-    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
-        errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
-    }
-    if (!essential) {
-        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
-            harnessVersion: probeHarnessVersion(client.command),
-        });
-    }
-    return { optionalSupported };
-}
-/** Best-effort; the server rejects non-printable characters and >32 chars. */
-function probeHarnessVersion(command) {
-    const result = spawn.sync(command, ["--version"], {
-        encoding: "utf8",
-        timeout: NON_INTERACTIVE_TIMEOUT_MS,
-    });
-    if (result.error || result.status !== 0)
-        return undefined;
-    const version = sanitizeLine(result.stdout ?? "")
-        .replace(/[^\x20-\x7E]/g, "")
-        .trim();
-    return version ? version.slice(0, 32) : undefined;
-}
-function commandNotFound(error) {
-    return error?.code === "ENOENT";
-}
 export function installTinyFishCli() {
     errLine("Installing the TinyFish CLI...");
     const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_INSTALL_SPEC], {

package/dist/commands/upgrade.js

@@ -5,7 +5,8 @@ import { suppressNotice } from "../lib/notice.js";
 import { errLine } from "../lib/output.js";
 import { sendUpgradeCompleted, telemetryDisabled, } from "../lib/setup-telemetry.js";
 import { installSignalGuard, SIGNAL_EXIT_CODES } from "../lib/signals.js";
-import { ConnectInterruptedError, installTinyFishCli, updateWebSkill } from "./connect.js";
+import { ConnectInterruptedError } from "../lib/connect-runtime.js";
+import { installTinyFishCli, updateWebSkill } from "./connect.js";
 const VERSION_READ_TIMEOUT_MS = 2_000;
 const INTERRUPTED_MESSAGE = "Upgrade interrupted — run `tinyfish upgrade` again to finish.";
 function attempt(label, run) {

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

@@ -0,0 +1,53 @@
+export declare const NON_INTERACTIVE_TIMEOUT_MS = 10000;
+export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw" | "opencode";
+type ConnectStage = "started" | "checkpoint" | "completed" | "failed" | "aborted" | "post_install_failed";
+type ConnectFailureStage = "prerequisite_check" | "registration_cleanup" | "registration" | "registration_or_authentication" | "client_oauth" | "cli_install" | "skill_install" | "authentication" | "walkthrough_launch";
+type ConnectFailureReason = "harness_not_installed" | "harness_command_unsupported" | "harness_too_old";
+type ConnectCheckpoint = "prerequisite_ok" | "registered" | "oauth_done" | "cli_installed" | "skill_installed" | "authenticated";
+/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
+export declare class ConnectInterruptedError extends Error {
+}
+export declare function throwIfInterrupted(result: {
+    signal?: string | null;
+    error?: Error;
+}): void;
+export declare function commandNotFound(error: unknown): boolean;
+export interface ConnectRunState {
+    stage: ConnectFailureStage;
+    settled: boolean;
+}
+interface ConnectStageDetail {
+    failedStage?: ConnectFailureStage;
+    phase?: ConnectCheckpoint;
+    failureReason?: ConnectFailureReason;
+    harnessVersion?: string;
+}
+export interface ConnectTelemetry {
+    attemptId: string;
+    track(stage: ConnectStage, detail?: ConnectStageDetail): void;
+    flush(): Promise<void>;
+}
+/** Terminal events exactly once, whichever of flow or signal handler wins. */
+export declare function settle(state: ConnectRunState, telemetry: ConnectTelemetry, stage: ConnectStage, detail?: ConnectStageDetail): void;
+/** Shared terminal handling: interrupted → aborted, else failed. */
+export declare function runGuarded(state: ConnectRunState, telemetry: ConnectTelemetry, body: () => void | Promise<void>): Promise<void>;
+export interface SupportedCommand {
+    command: string;
+    displayName: string;
+    supportCheck: {
+        args: string[];
+        /** Missing → nothing can work; setup fails. */
+        patterns: RegExp[];
+        /** Missing → degrade to key or deferred auth, never refuse. */
+        optionalPatterns?: RegExp[];
+        unavailableMessage: string;
+    };
+}
+export declare function requireCommandSupport(client: SupportedCommand): {
+    optionalSupported: boolean;
+};
+export declare function createConnectTelemetry(mcpUrl: string, client: AgentClient, opts?: {
+    apiKey?: string;
+    attemptId?: string;
+}): ConnectTelemetry;
+export {};

package/dist/lib/connect-runtime.js

@@ -0,0 +1,186 @@
+import { randomUUID } from "node:crypto";
+import spawn from "cross-spawn";
+import { CONNECT_ATTEMPT_ENV, isAttemptId, resolvedApiKey, takePendingConnectAttempt, } from "./auth.js";
+import { CLI_VERSION } from "./constants.js";
+import { detectHumanInitiated } from "./harness.js";
+import { errLine, sanitizeLine } from "./output.js";
+import { postConnectEvent, telemetryDisabled } from "./setup-telemetry.js";
+import { installSignalGuard } from "./signals.js";
+export const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
+/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
+export class ConnectInterruptedError extends Error {
+}
+class PrerequisiteError extends Error {
+    failureReason;
+    harnessVersion;
+    constructor(message, failureReason, opts) {
+        super(message, { cause: opts?.cause });
+        this.failureReason = failureReason;
+        this.harnessVersion = opts?.harnessVersion;
+    }
+}
+export function throwIfInterrupted(result) {
+    // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
+    // network as the user walking away. A timeout is a failure and must report as one.
+    if (result.error?.code === "ETIMEDOUT")
+        return;
+    if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
+        throw new ConnectInterruptedError("Setup interrupted");
+    }
+}
+export function commandNotFound(error) {
+    return error?.code === "ENOENT";
+}
+/** Terminal events exactly once, whichever of flow or signal handler wins. */
+export function settle(state, telemetry, stage, detail) {
+    if (state.settled)
+        return;
+    state.settled = true;
+    telemetry.track(stage, detail);
+}
+// Raw-mode children still surface via throwIfInterrupted; cooked-mode stages
+// (npm/npx/OAuth waits) land here.
+function installConnectSignalGuard(state, telemetry) {
+    return installSignalGuard(async () => {
+        if (!state.settled) {
+            settle(state, telemetry, "aborted", { failedStage: state.stage });
+            errLine("Setup interrupted — run the command again to finish.");
+        }
+        // Settled spans the whole post-install phase; the `completed` POST may still be in flight.
+        await telemetry.flush();
+    });
+}
+/** Shared terminal handling: interrupted → aborted, else failed. */
+export async function runGuarded(state, telemetry, body) {
+    const uninstallSignalGuard = installConnectSignalGuard(state, telemetry);
+    try {
+        await body();
+    }
+    catch (error) {
+        if (error instanceof ConnectInterruptedError) {
+            settle(state, telemetry, "aborted", { failedStage: state.stage });
+            errLine("Setup interrupted — run the command again to finish.");
+            process.exitCode = 130;
+            return;
+        }
+        settle(state, telemetry, "failed", {
+            failedStage: state.stage,
+            ...(error instanceof PrerequisiteError
+                ? { failureReason: error.failureReason, harnessVersion: error.harnessVersion }
+                : {}),
+        });
+        throw error;
+    }
+    finally {
+        uninstallSignalGuard();
+        await telemetry.flush();
+    }
+}
+export function requireCommandSupport(client) {
+    const result = spawn.sync(client.command, client.supportCheck.args, {
+        encoding: "utf8",
+        // Agent harnesses export FORCE_COLOR, which makes clients colourise even a piped --help.
+        env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" },
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (commandNotFound(result.error)) {
+        throw new PrerequisiteError(`${client.displayName} is not installed or not available on PATH.`, "harness_not_installed", { cause: result.error });
+    }
+    if (result.error || result.status !== 0) {
+        throwIfInterrupted(result);
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
+    }
+    // Belt and braces with the colour env: a client that ignores NO_COLOR still has to match.
+    const output = sanitizeLine(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+    const listed = (patterns) => patterns.every((pattern) => pattern.test(output));
+    const essential = listed(client.supportCheck.patterns);
+    const optionalSupported = listed(client.supportCheck.optionalPatterns ?? []);
+    if ((!essential || !optionalSupported) && process.env["TINYFISH_DEBUG"]) {
+        errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
+    }
+    if (!essential) {
+        throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
+            harnessVersion: probeHarnessVersion(client.command),
+        });
+    }
+    return { optionalSupported };
+}
+/** Best-effort; the server rejects non-printable characters and >32 chars. */
+function probeHarnessVersion(command) {
+    const result = spawn.sync(command, ["--version"], {
+        encoding: "utf8",
+        timeout: NON_INTERACTIVE_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    const version = sanitizeLine(result.stdout ?? "")
+        .replace(/[^\x20-\x7E]/g, "")
+        .trim();
+    return version ? version.slice(0, 32) : undefined;
+}
+/**
+ * One page-minted id seeds one install attempt, so `tinyfish onboard` connecting three agents
+ * does not report three installs under it. Later connects in the run fall back to a random id.
+ */
+function takeSeedAttemptId() {
+    const fromEnv = process.env[CONNECT_ATTEMPT_ENV];
+    // Both sources are read-and-clear, and the delete lands before any subprocess inherits it.
+    delete process.env[CONNECT_ATTEMPT_ENV];
+    const parked = takePendingConnectAttempt();
+    return fromEnv && isAttemptId(fromEnv) ? fromEnv : parked;
+}
+export function createConnectTelemetry(mcpUrl, client, opts) {
+    // Consumed even when --url already supplied an id: leaving it behind would let a stale
+    // seed reach the agent this connect launches, or the next connect on this machine.
+    const seeded = takeSeedAttemptId();
+    // A setup-page id (via --url, the env var, or one parked by login) joins "copied the
+    // command" to this install attempt.
+    const attemptId = opts?.attemptId ?? seeded ?? randomUUID();
+    const endpoint = new URL("/api/cli/connect-event", mcpUrl).toString();
+    const pending = [];
+    async function deliver(body) {
+        // Ahead of the key read; postConnectEvent's own opt-out check is too late to skip it.
+        if (telemetryDisabled())
+            return;
+        // Resolved per event: `tinyfish auth login` writes the config from a subprocess mid-connect.
+        await postConnectEvent({
+            endpoint,
+            body,
+            attempts: 2,
+            apiKey: resolvedApiKey(opts?.apiKey),
+            label: "connect",
+        });
+    }
+    return {
+        attemptId,
+        // Fire-and-forget; awaiting each event stalls setup when telemetry down.
+        track(stage, detail) {
+            // Absorbed here, not in flush: flush runs in runGuarded's finally, so a rejection would
+            // replace the error the flow is already reporting.
+            pending.push(deliver(JSON.stringify({
+                attempt_id: attemptId,
+                client,
+                stage,
+                failed_stage: detail?.failedStage,
+                phase: detail?.phase,
+                failure_reason: detail?.failureReason,
+                harness_version: detail?.harnessVersion,
+                runtime_platform: process.platform,
+                node_version: process.version,
+                cli_version: CLI_VERSION,
+                // Same signal the usage events carry, so TTY and headless connects can be split.
+                is_human_initiated: detectHumanInitiated(),
+            })).catch((error) => {
+                // postConnectEvent is total, so this only fires if something inside deliver starts
+                // throwing. Same channel postConnectEvent uses for its own failures.
+                if (!process.env["TINYFISH_DEBUG"])
+                    return;
+                errLine(`connect telemetry failed: ${error instanceof Error ? error.message : String(error)}`);
+            }));
+        },
+        // Awaited in finally so in-flight events land before exit.
+        async flush() {
+            await Promise.all(pending);
+        },
+    };
+}

package/package.json

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