@tiny-fish/cli 0.37.1-next.300 → 0.37.1-next.301

package/dist/commands/auth.js

@@ -128,7 +128,10 @@ export function registerAuth(program) {
         // Read from stdin pipe (CI/CD) or hidden TTY prompt (interactive)
         const key = await readKeyFromStdinOrPrompt();
         if (!key) {
-            err('API key cannot be empty');
+            // `echo $KEY | tinyfish auth set` with KEY unset pipes a blank line, not a key.
+            err(process.stdin.isTTY
+                ? 'API key cannot be empty'
+                : "No key received on stdin. Example: echo 'sk-tinyfish-...' | tinyfish auth set");
             process.exit(1);
         }
         if (!validateKeyFormat(key)) {

package/dist/commands/connect.js

@@ -16,6 +16,7 @@ import { SIGN_IN_PROBES } from '../lib/registration-detect.js';
 import { errLine, warnLine } from '../lib/output.js';
 import { z } from 'zod';
 import { verifyMcpAuth } from '../lib/verify.js';
+import { gateApiKey } from '../lib/connect-preflight.js';
 import { apiBaseFromMcpUrl, DEFAULT_MCP_URL } from '../lib/mcp-endpoint.js';
 function removeExistingRegistration(client, removal, verbose) {
     const result = spawnRemoval(client.command, removal.args);
@@ -746,6 +747,17 @@ async function connectSingleClient(client, options, mcpUrl, attemptId) {
     if (!ALL_HARNESSES.includes(client)) {
         throw new Error('Unsupported client: ' + client + '. Supported clients: ' + ALL_HARNESSES.join(', '));
     }
+    const gate = await gateApiKey({
+        apiKey: options.apiKey,
+        mcpUrl,
+        retryCommand: `tinyfish connect ${client}`,
+        mode: 'single',
+        attemptId,
+    });
+    if (gate === 'blocked') {
+        process.exitCode = 1;
+        return;
+    }
     await connectHarness(client, connectOptions);
 }
 export function registerConnect(program) {

package/dist/commands/doctor.d.ts

@@ -1,17 +1,4 @@
 import type { Command } from 'commander';
-import { type DoctorRepair, type DoctorReport } from '../lib/doctor-report.js';
-import { type Harness } from '../lib/harness-detect.js';
-export interface DoctorOptions {
-    mcpUrl: string;
-    harness?: Harness;
-    fix?: boolean;
-    yes?: boolean;
-}
+import { type DoctorOptions, type DoctorReport } from '../lib/doctor-report.js';
 export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
-export interface RepairOutcome {
-    repair: DoctorRepair;
-    status: 'repaired' | 'skipped' | 'failed';
-    reason?: string;
-}
-export declare function applyRepairs(repairs: DoctorRepair[], options: DoctorOptions): Promise<RepairOutcome[]>;
 export declare function registerDoctor(program: Command): void;

package/dist/commands/doctor.js

@@ -1,17 +1,16 @@
-import spawn from 'cross-spawn';
 import { apiKeyStatus } from '../lib/auth.js';
 import { CLI_VERSION } from '../lib/constants.js';
 import { DOCTOR_COULD_NOT_RUN, DOCTOR_INVALID_INPUT, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, verdictFor, } from '../lib/doctor-report.js';
+import { applyRepairs, repairsFor } from '../lib/doctor-repairs.js';
+import { couldNotRunPayload, telemetryKey, telemetryPayload } from '../lib/doctor-telemetry.js';
 import { ALL_HARNESSES, AuthMode, Registered } from '../lib/harness-detect.js';
-import { detectHumanInitiated } from '../lib/harness.js';
 import { err, errLine, out, outLine } from '../lib/output.js';
 import { detectRegistrations } from '../lib/registration-detect.js';
-import { doctorErrorClass, sendDoctorCompleted, } from '../lib/setup-telemetry.js';
+import { sendDoctorCompleted } from '../lib/setup-telemetry.js';
 import { verifyMcpAuth, verifyMcpHealth } from '../lib/verify.js';
 import { resolveHermesHome } from '../lib/hermes-env.js';
 import { hermesWebBackendsOurs, readHermesPluginStatus, } from '../lib/hermes-plugin.js';
 import { DEFAULT_MCP_URL, endpointOf, isDefaultEndpoint } from '../lib/mcp-endpoint.js';
-import { connectHarness } from './connect.js';
 // A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
 function provesHarnessReach(status, keyAuth, healthOk, mcpUrl) {
     // An endpoint doctor could not reach proves nothing about a harness pointed at it.
@@ -270,57 +269,6 @@ function checkHermesPlugin(status) {
     }
     return { ...check, ...hermesPluginVerdict(home) };
 }
-// Only Cursor's repair is a pure local file write; every other one needs a browser sign-in.
-const UNATTENDED_SAFE = new Set(['cursor']);
-function repairsFor(checks, statuses) {
-    const repairs = [];
-    // A revoked-but-well-formed key passes the credential check and fails the call; both need login.
-    const credentialBroken = checks.some((c) => (c.id === 'cli-credential' || c.id === 'cli-auth-call') && c.status === 'fail');
-    // connect writes the stored key, so replace a dead one first.
-    if (credentialBroken) {
-        repairs.push({
-            for: 'cli-credential-invalid',
-            action: 'auth-login',
-            harness: null,
-            command: 'tinyfish auth login',
-            unattended_safe: false,
-        });
-    }
-    const authCallPassed = checks.some((c) => c.id === 'cli-auth-call' && c.status === 'pass');
-    for (const status of statuses) {
-        // `unknown` earns nothing: connect would contradict the check's detail.
-        // A registered entry that still fails earns one too.
-        // `connected: false` is the harness's own no; it only warns, so it earns a repair here.
-        const brokenRegistration = status.connected === false ||
-            checks.some((c) => c.harness === status.harness && c.id !== 'hermes-plugin' && c.status === 'fail');
-        if (!status.detected || (status.registered !== Registered.No && !brokenRegistration))
-            continue;
-        repairs.push({
-            for: status.registered === Registered.Yes
-                ? `${status.harness}-registration-broken`
-                : status.connectedBefore
-                    ? `${status.harness}-registration-lost`
-                    : `${status.harness}-not-connected`,
-            action: 'connect',
-            harness: status.harness,
-            command: `tinyfish connect ${status.harness}`,
-            // A dead well-formed key passes the format check.
-            unattended_safe: UNATTENDED_SAFE.has(status.harness) && authCallPassed,
-        });
-    }
-    // connect hermes reinstalls the plugin; a second row would double it.
-    const pluginBroken = checks.some((c) => c.id === 'hermes-plugin' && c.status === 'fail');
-    if (pluginBroken && !repairs.some((repair) => repair.harness === 'hermes')) {
-        repairs.push({
-            for: 'hermes-plugin-broken',
-            action: 'connect',
-            harness: 'hermes',
-            command: 'tinyfish connect hermes',
-            unattended_safe: false,
-        });
-    }
-    return repairs;
-}
 export async function runDoctor(options) {
     const statuses = detectRegistrations(options.harness ? [options.harness] : undefined);
     const credential = checkCredential();
@@ -359,124 +307,6 @@ export async function runDoctor(options) {
     // Nothing to scrub: every string above is authored here or enumerated at its source.
     return doctorReportSchema.parse(body);
 }
-// Shell out rather than import the login flow: `auth login` owns its own browser and prompts.
-// Re-invoke this same entry script, never a global `tinyfish` — under `npx` there is no such
-// binary on PATH, and npx is the install-nothing path doctor exists to serve.
-function runAuthLogin() {
-    const entry = process.argv[1];
-    if (!entry)
-        throw new Error('Could not locate the TinyFish CLI entry point to re-invoke');
-    const result = spawn.sync(process.execPath, [entry, 'auth', 'login', '--source', 'doctor'], {
-        stdio: 'inherit',
-    });
-    if (result.error)
-        throw new Error('Could not run `tinyfish auth login`', { cause: result.error });
-    if (result.status !== 0) {
-        throw new Error(`\`tinyfish auth login\` exited ${result.status ?? 'unknown'}`);
-    }
-}
-/** Dispatches on `action`, never on a null harness: that conflation made the credential fix a no-op. */
-async function runRepair(repair, mcpUrl) {
-    if (repair.action === 'auth-login')
-        return runAuthLogin();
-    if (repair.harness)
-        await connectHarness(repair.harness, { mcpUrl, launch: false });
-}
-export async function applyRepairs(repairs, options) {
-    const interactive = detectHumanInitiated();
-    const outcomes = [];
-    for (const repair of repairs) {
-        if (!interactive && !options.yes) {
-            outcomes.push({
-                repair,
-                status: 'skipped',
-                reason: 'no terminal; re-run with --yes to repair unattended',
-            });
-            continue;
-        }
-        if (!interactive && !repair.unattended_safe) {
-            outcomes.push({
-                repair,
-                status: 'skipped',
-                reason: 'needs a browser sign-in, which has no unattended path',
-            });
-            continue;
-        }
-        try {
-            await runRepair(repair, options.mcpUrl);
-            outcomes.push({ repair, status: 'repaired' });
-        }
-        catch (e) {
-            // Connect quotes absolute config paths in its errors, so the raw text stays behind
-            // --debug and the user is told where to find it rather than handed a generic dead end.
-            if (process.env['TINYFISH_DEBUG']) {
-                errLine(e instanceof Error ? (e.stack ?? e.message) : String(e));
-            }
-            outcomes.push({
-                repair,
-                status: 'failed',
-                reason: `\`${repair.command}\` failed; re-run it directly, or --debug for the raw error`,
-            });
-        }
-    }
-    return outcomes;
-}
-/** Mirrors the route's cap; over it the payload would 400 and never be retried. */
-const MAX_DURATION_MS = 3_600_000;
-function fixModeOf(options) {
-    return !options.fix ? 'none' : options.yes ? 'fix_yes' : 'fix';
-}
-/** Enumerated fields only; check `detail` text never leaves the machine. */
-function telemetryPayload(report, offered, outcomes, options, durationMs) {
-    const count = (status) => report.checks.filter((check) => check.status === status).length;
-    const failed = report.checks.filter((check) => check.status === 'fail');
-    return {
-        outcome: 'completed',
-        schema_version: report.schema_version,
-        cli_version: report.cli_version,
-        ok_harnesses: report.ok_harnesses,
-        ok_cli: report.ok_cli,
-        checks_pass: count('pass'),
-        checks_fail: count('fail'),
-        checks_warn: count('warn'),
-        checks_skip: count('skip'),
-        // From the pre-repair report; the verdicts above describe the machine after it.
-        repairs_offered: offered.length,
-        repair_actions: [...new Set(offered.map((repair) => repair.action))],
-        repairs_attempted: outcomes.filter((outcome) => outcome.status !== 'skipped').length,
-        repairs_succeeded: outcomes.filter((outcome) => outcome.status === 'repaired').length,
-        fix_mode: fixModeOf(options),
-        // --harness scopes detection, so the counts above cover that harness alone.
-        harness_scope: options.harness ?? 'all',
-        // Same signal cli_connect_stage carries, so agent and human doctor runs split.
-        is_human_initiated: detectHumanInitiated(),
-        // Two flat arrays rather than one of pairs: PostHog groups by element, not by field.
-        failed_check_ids: [...new Set(failed.map((check) => check.id))],
-        failed_harnesses: [...new Set(failed.map((check) => check.harness).filter((h) => h !== null))],
-        harnesses: report.harnesses,
-        // Clamped, not validated: a --fix parked at a prompt must not fail the parse and drop the run.
-        duration_ms: Math.min(durationMs, MAX_DURATION_MS),
-    };
-}
-/** Both paths send keyless when there is no key; the route records those anonymously. */
-function telemetryKey() {
-    const resolved = apiKeyStatus();
-    return 'key' in resolved ? resolved.key : undefined;
-}
-/** Enumerated outcome and timing only; the raw error stays behind --debug. */
-function couldNotRunPayload(error, options, durationMs) {
-    return {
-        outcome: 'could_not_run',
-        error_class: doctorErrorClass(error),
-        schema_version: DOCTOR_SCHEMA_VERSION,
-        cli_version: CLI_VERSION,
-        fix_mode: fixModeOf(options),
-        harness_scope: options.harness ?? 'all',
-        is_human_initiated: detectHumanInitiated(),
-        // Clamped like the completed row: over the cap the payload would 400 un-retried.
-        duration_ms: Math.min(durationMs, MAX_DURATION_MS),
-    };
-}
 export function registerDoctor(program) {
     program
         .command('doctor')

package/dist/lib/auth.d.ts

@@ -1,5 +1,6 @@
 export { DASHBOARD_URL, getDashboardUrl } from './constants.js';
 export declare function configDir(): string;
+export declare function configFile(): string;
 /** Install channel baked onto connect context; the connect flow is always CLI-driven. */
 export declare const CONNECT_SOURCE = "tinyfish_cli";
 export declare const CONNECT_ATTEMPT_ENV = "TINYFISH_CONNECT_ATTEMPT_ID";
@@ -65,5 +66,5 @@ export declare function validatedApiKey(explicitApiKey?: string): string | undef
  * The diagnosis, not the key: doctor must report a bad credential and say where it came from
  * rather than exit like getApiKey does.
  */
-export declare function apiKeyStatus(): ResolvedKey | UnresolvedKey;
+export declare function apiKeyStatus(explicitApiKey?: string): ResolvedKey | UnresolvedKey;
 export declare function getApiKey(): string;

package/dist/lib/auth.js

@@ -11,7 +11,7 @@ export function configDir() {
     // os.homedir() is cross-platform; process.env.HOME is undefined on Windows
     return path.join(os.homedir(), '.tinyfish');
 }
-function configFile() {
+export function configFile() {
     return path.join(configDir(), 'config.json');
 }
 /** Install channel baked onto connect context; the connect flow is always CLI-driven. */
@@ -283,8 +283,8 @@ export function validatedApiKey(explicitApiKey) {
  * The diagnosis, not the key: doctor must report a bad credential and say where it came from
  * rather than exit like getApiKey does.
  */
-export function apiKeyStatus() {
-    const { value, source } = lookupApiKey();
+export function apiKeyStatus(explicitApiKey) {
+    const { value, source } = lookupApiKey(explicitApiKey);
     if (!value || source === 'none') {
         return { error: 'No API key found. Run: tinyfish auth login', source: 'none' };
     }

package/dist/lib/connect-all.js

@@ -9,6 +9,7 @@ import { actionable, computeExitCode, reloadHint, renderSummary } from './connec
 import { planText, uninstallHarness, uninstallPlanText } from './connect-all-uninstall.js';
 import { NATIVE_BY_HARNESS } from './connect-clients.js';
 import { createStdinPrompt, runCliFallback } from './connect-fallback.js';
+import { gateApiKey } from './connect-preflight.js';
 import { ConnectInterruptedError } from './connect-runtime.js';
 import { pickHarnesses } from './connect-picker.js';
 import { commandOnPath, detectInstalledHarnesses, HARNESS_COMMANDS, HARNESS_DISPLAY_NAMES as DISPLAY_NAMES, ALL_HARNESSES, } from './harness-detect.js';
@@ -212,8 +213,13 @@ async function connectLoop(detections, opts, deselected, io) {
         try {
             setErrIndent(STEP_INDENT);
             result = await processHarness(detection, opts, io.prompt, oauthBudget, io.takeHoistedCli, (line) => io.outro.add(line));
+            // A failed harness prints nothing of its own, so its step reads as skipped.
+            if (result.outcome === 'failed' && result.errorMessage)
+                errLine(result.errorMessage);
         }
         catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            errLine(errorMessage);
             // Isolation: one harness throwing never stops the others.
             result = {
                 harness,
@@ -221,7 +227,7 @@ async function connectLoop(detections, opts, deselected, io) {
                 configPath: detection.configPath,
                 installed: false,
                 outcome: 'failed',
-                errorMessage: e instanceof Error ? e.message : String(e),
+                errorMessage,
                 fixCommand: `tinyfish connect ${harness}`,
             };
         }
@@ -295,11 +301,32 @@ async function finishRun(results, opts, isTTY) {
     }
     return exitCode;
 }
+/** Neither path needs a live key, and neither writes a registration. */
+function keyGateApplies(opts) {
+    return !opts.uninstall && !opts.dryRun;
+}
+async function blockedByKeyGate(opts) {
+    if (!keyGateApplies(opts))
+        return false;
+    const pick = opts.pick === true;
+    const gate = await gateApiKey({
+        apiKey: opts.apiKey,
+        mcpUrl: opts.mcpUrl,
+        // The picker path is reached by a bare `tinyfish connect`.
+        retryCommand: pick ? 'tinyfish connect' : 'tinyfish connect --all',
+        mode: pick ? 'pick' : 'all',
+        attemptId: opts.attemptId,
+    });
+    return gate === 'blocked';
+}
 export async function runConnectAll(opts) {
     const isTTY = detectHumanInitiated();
+    // Above the setup event and every write: a blocked run is not a setup attempt.
+    if (await blockedByKeyGate(opts))
+        return 1;
     // Ahead of detection and the hoisted install; either can end the process silently.
     // Not on the picker path: an explicit cancel is not a setup.
-    if (!opts.uninstall && !opts.dryRun && !opts.pick) {
+    if (keyGateApplies(opts) && !opts.pick) {
         // validatedApiKey falls back to env/config; opts.apiKey alone splits the run's two ends.
         await sendSetupStarted(opts.mcpUrl, opts.attemptId, validatedApiKey(opts.apiKey));
     }

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

@@ -0,0 +1,15 @@
+import { type SetupBlockedMode } from './setup-telemetry.js';
+export type PreflightOutcome = 'ok' | 'blocked';
+interface PreflightOptions {
+    apiKey?: string;
+    mcpUrl: string;
+    retryCommand: string;
+    mode: SetupBlockedMode;
+    attemptId?: string;
+}
+/**
+ * Checks the key every harness would install with, once, before anything is written.
+ * A bad key otherwise fails all seven installs the slow way, and Hermes refuses outright.
+ */
+export declare function gateApiKey(options: PreflightOptions): Promise<PreflightOutcome>;
+export {};

package/dist/lib/connect-preflight.js

@@ -0,0 +1,67 @@
+import { apiKeyStatus, configFile, validateKeyFormat } from './auth.js';
+import { TINYFISH_API_KEY_VAR } from './constants.js';
+import { apiBaseFromMcpUrl } from './mcp-endpoint.js';
+import { errLine, warnLine } from './output.js';
+import { sendSetupBlocked, } from './setup-telemetry.js';
+import { verifyMcpAuth } from './verify.js';
+function sourceAdvice(source) {
+    switch (source) {
+        case 'env':
+            return `The key came from ${TINYFISH_API_KEY_VAR}, which overrides a saved key — fix or unset that export.`;
+        case 'explicit':
+            return 'The key came from --api-key.';
+        default:
+            return `The key came from ${configFile()}. Save a working one: tinyfish auth login, or pipe a key to tinyfish auth set.`;
+    }
+}
+async function block(detail, options) {
+    errLine(`${detail.message} Nothing was installed.`);
+    errLine(sourceAdvice(detail.source));
+    errLine(`Then re-run: ${options.retryCommand}`);
+    await sendSetupBlocked(options.mcpUrl, {
+        blockReason: detail.reason,
+        keySource: detail.source,
+        ...(detail.status === undefined ? {} : { status: detail.status }),
+        mode: options.mode,
+        attemptId: options.attemptId,
+    }, detail.key);
+    return 'blocked';
+}
+/**
+ * Checks the key every harness would install with, once, before anything is written.
+ * A bad key otherwise fails all seven installs the slow way, and Hermes refuses outright.
+ */
+export async function gateApiKey(options) {
+    const status = apiKeyStatus(options.apiKey);
+    // No key at all is a valid answer: the OAuth harnesses still connect without one.
+    if (status.source === 'none')
+        return 'ok';
+    const source = status.source;
+    if (!('key' in status)) {
+        return block({ reason: 'key_unreadable', source, message: `${status.error}.` }, options);
+    }
+    // Downstream this key is dropped as unusable, which reads as "no key" and silently
+    // downgrades every install to a browser sign-in Hermes cannot take.
+    if (!validateKeyFormat(status.key)) {
+        return block({
+            reason: 'key_malformed',
+            source,
+            message: 'Your TinyFish API key is not shaped like one (expected sk-tinyfish-... or sk-mino-...).',
+        }, options);
+    }
+    const verified = await verifyMcpAuth(status.key, apiBaseFromMcpUrl(options.mcpUrl));
+    if (verified.ok)
+        return 'ok';
+    // No status means the network failed, and an outage must not block a whole setup.
+    if (verified.status === undefined) {
+        warnLine(`Could not check your TinyFish API key (${verified.code ?? 'unknown'}); continuing.`);
+        return 'ok';
+    }
+    return block({
+        reason: 'key_rejected',
+        source,
+        message: `Your TinyFish API key was rejected (${verified.code ?? 'unknown'}).`,
+        key: status.key,
+        status: verified.status,
+    }, options);
+}

package/dist/lib/doctor-repairs.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorCheck, DoctorOptions, DoctorRepair } from './doctor-report.js';
+import type { RegistrationStatus } from './registration-detect.js';
+export declare function repairsFor(checks: DoctorCheck[], statuses: RegistrationStatus[]): DoctorRepair[];
+export interface RepairOutcome {
+    repair: DoctorRepair;
+    status: 'repaired' | 'skipped' | 'failed';
+    reason?: string;
+}
+export declare function applyRepairs(repairs: DoctorRepair[], options: DoctorOptions): Promise<RepairOutcome[]>;

package/dist/lib/doctor-repairs.js

@@ -0,0 +1,118 @@
+import spawn from 'cross-spawn';
+import { connectHarness } from '../commands/connect.js';
+import { Registered } from './harness-detect.js';
+import { detectHumanInitiated } from './harness.js';
+import { errLine } from './output.js';
+// Only Cursor's repair is a pure local file write; every other one needs a browser sign-in.
+const UNATTENDED_SAFE = new Set(['cursor']);
+export function repairsFor(checks, statuses) {
+    const repairs = [];
+    // A revoked-but-well-formed key passes the credential check and fails the call; both need login.
+    const credentialBroken = checks.some((c) => (c.id === 'cli-credential' || c.id === 'cli-auth-call') && c.status === 'fail');
+    // connect writes the stored key, so replace a dead one first.
+    if (credentialBroken) {
+        repairs.push({
+            for: 'cli-credential-invalid',
+            action: 'auth-login',
+            harness: null,
+            command: 'tinyfish auth login',
+            unattended_safe: false,
+        });
+    }
+    const authCallPassed = checks.some((c) => c.id === 'cli-auth-call' && c.status === 'pass');
+    for (const status of statuses) {
+        // `unknown` earns nothing: connect would contradict the check's detail.
+        // A registered entry that still fails earns one too.
+        // `connected: false` is the harness's own no; it only warns, so it earns a repair here.
+        const brokenRegistration = status.connected === false ||
+            checks.some((c) => c.harness === status.harness && c.id !== 'hermes-plugin' && c.status === 'fail');
+        if (!status.detected || (status.registered !== Registered.No && !brokenRegistration))
+            continue;
+        repairs.push({
+            for: status.registered === Registered.Yes
+                ? `${status.harness}-registration-broken`
+                : status.connectedBefore
+                    ? `${status.harness}-registration-lost`
+                    : `${status.harness}-not-connected`,
+            action: 'connect',
+            harness: status.harness,
+            command: `tinyfish connect ${status.harness}`,
+            // A dead well-formed key passes the format check.
+            unattended_safe: UNATTENDED_SAFE.has(status.harness) && authCallPassed,
+        });
+    }
+    // connect hermes reinstalls the plugin; a second row would double it.
+    const pluginBroken = checks.some((c) => c.id === 'hermes-plugin' && c.status === 'fail');
+    if (pluginBroken && !repairs.some((repair) => repair.harness === 'hermes')) {
+        repairs.push({
+            for: 'hermes-plugin-broken',
+            action: 'connect',
+            harness: 'hermes',
+            command: 'tinyfish connect hermes',
+            unattended_safe: false,
+        });
+    }
+    return repairs;
+}
+// Shell out rather than import the login flow: `auth login` owns its own browser and prompts.
+// Re-invoke this same entry script, never a global `tinyfish` — under `npx` there is no such
+// binary on PATH, and npx is the install-nothing path doctor exists to serve.
+function runAuthLogin() {
+    const entry = process.argv[1];
+    if (!entry)
+        throw new Error('Could not locate the TinyFish CLI entry point to re-invoke');
+    const result = spawn.sync(process.execPath, [entry, 'auth', 'login', '--source', 'doctor'], {
+        stdio: 'inherit',
+    });
+    if (result.error)
+        throw new Error('Could not run `tinyfish auth login`', { cause: result.error });
+    if (result.status !== 0) {
+        throw new Error(`\`tinyfish auth login\` exited ${result.status ?? 'unknown'}`);
+    }
+}
+/** Dispatches on `action`, never on a null harness: that conflation made the credential fix a no-op. */
+async function runRepair(repair, mcpUrl) {
+    if (repair.action === 'auth-login')
+        return runAuthLogin();
+    if (repair.harness)
+        await connectHarness(repair.harness, { mcpUrl, launch: false });
+}
+export async function applyRepairs(repairs, options) {
+    const interactive = detectHumanInitiated();
+    const outcomes = [];
+    for (const repair of repairs) {
+        if (!interactive && !options.yes) {
+            outcomes.push({
+                repair,
+                status: 'skipped',
+                reason: 'no terminal; re-run with --yes to repair unattended',
+            });
+            continue;
+        }
+        if (!interactive && !repair.unattended_safe) {
+            outcomes.push({
+                repair,
+                status: 'skipped',
+                reason: 'needs a browser sign-in, which has no unattended path',
+            });
+            continue;
+        }
+        try {
+            await runRepair(repair, options.mcpUrl);
+            outcomes.push({ repair, status: 'repaired' });
+        }
+        catch (e) {
+            // Connect quotes absolute config paths in its errors, so the raw text stays behind
+            // --debug and the user is told where to find it rather than handed a generic dead end.
+            if (process.env['TINYFISH_DEBUG']) {
+                errLine(e instanceof Error ? (e.stack ?? e.message) : String(e));
+            }
+            outcomes.push({
+                repair,
+                status: 'failed',
+                reason: `\`${repair.command}\` failed; re-run it directly, or --debug for the raw error`,
+            });
+        }
+    }
+    return outcomes;
+}

package/dist/lib/doctor-report.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AuthMode, Registered } from './harness-detect.js';
+import { AuthMode, type Harness, Registered } from './harness-detect.js';
 /** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
 export declare const DOCTOR_SCHEMA_VERSION = 3;
 declare const checkStatusSchema: z.ZodEnum<{
@@ -151,6 +151,12 @@ export type DoctorCheck = z.infer<typeof doctorCheckSchema>;
 export type DoctorHarness = z.infer<typeof doctorHarnessSchema>;
 export type DoctorRepair = z.infer<typeof doctorRepairSchema>;
 export type DoctorReport = z.infer<typeof doctorReportSchema>;
+export interface DoctorOptions {
+    mcpUrl: string;
+    harness?: Harness;
+    fix?: boolean;
+    yes?: boolean;
+}
 /** Doctor itself broke, which is a different claim from "your setup is broken". */
 export declare const DOCTOR_COULD_NOT_RUN = 2;
 /** The invocation was wrong, not the machine; exit 2 stays "doctor broke". */

package/dist/lib/doctor-telemetry.d.ts

@@ -0,0 +1,9 @@
+import { type DoctorOptions, type DoctorRepair, type DoctorReport } from './doctor-report.js';
+import type { RepairOutcome } from './doctor-repairs.js';
+import { type DoctorCompletedPayload, type DoctorCouldNotRunPayload } from './setup-telemetry.js';
+/** Enumerated fields only; check `detail` text never leaves the machine. */
+export declare function telemetryPayload(report: DoctorReport, offered: DoctorRepair[], outcomes: RepairOutcome[], options: DoctorOptions, durationMs: number): DoctorCompletedPayload;
+/** Both paths send keyless when there is no key; the route records those anonymously. */
+export declare function telemetryKey(): string | undefined;
+/** Enumerated outcome and timing only; the raw error stays behind --debug. */
+export declare function couldNotRunPayload(error: unknown, options: DoctorOptions, durationMs: number): DoctorCouldNotRunPayload;

package/dist/lib/doctor-telemetry.js

@@ -0,0 +1,61 @@
+import { apiKeyStatus } from './auth.js';
+import { CLI_VERSION } from './constants.js';
+import { DOCTOR_SCHEMA_VERSION, } from './doctor-report.js';
+import { detectHumanInitiated } from './harness.js';
+import { doctorErrorClass, } from './setup-telemetry.js';
+/** Mirrors the route's cap; over it the payload would 400 and never be retried. */
+const MAX_DURATION_MS = 3_600_000;
+function fixModeOf(options) {
+    return !options.fix ? 'none' : options.yes ? 'fix_yes' : 'fix';
+}
+/** Enumerated fields only; check `detail` text never leaves the machine. */
+export function telemetryPayload(report, offered, outcomes, options, durationMs) {
+    const count = (status) => report.checks.filter((check) => check.status === status).length;
+    const failed = report.checks.filter((check) => check.status === 'fail');
+    return {
+        outcome: 'completed',
+        schema_version: report.schema_version,
+        cli_version: report.cli_version,
+        ok_harnesses: report.ok_harnesses,
+        ok_cli: report.ok_cli,
+        checks_pass: count('pass'),
+        checks_fail: count('fail'),
+        checks_warn: count('warn'),
+        checks_skip: count('skip'),
+        // From the pre-repair report; the verdicts above describe the machine after it.
+        repairs_offered: offered.length,
+        repair_actions: [...new Set(offered.map((repair) => repair.action))],
+        repairs_attempted: outcomes.filter((outcome) => outcome.status !== 'skipped').length,
+        repairs_succeeded: outcomes.filter((outcome) => outcome.status === 'repaired').length,
+        fix_mode: fixModeOf(options),
+        // --harness scopes detection, so the counts above cover that harness alone.
+        harness_scope: options.harness ?? 'all',
+        // Same signal cli_connect_stage carries, so agent and human doctor runs split.
+        is_human_initiated: detectHumanInitiated(),
+        // Two flat arrays rather than one of pairs: PostHog groups by element, not by field.
+        failed_check_ids: [...new Set(failed.map((check) => check.id))],
+        failed_harnesses: [...new Set(failed.map((check) => check.harness).filter((h) => h !== null))],
+        harnesses: report.harnesses,
+        // Clamped, not validated: a --fix parked at a prompt must not fail the parse and drop the run.
+        duration_ms: Math.min(durationMs, MAX_DURATION_MS),
+    };
+}
+/** Both paths send keyless when there is no key; the route records those anonymously. */
+export function telemetryKey() {
+    const resolved = apiKeyStatus();
+    return 'key' in resolved ? resolved.key : undefined;
+}
+/** Enumerated outcome and timing only; the raw error stays behind --debug. */
+export function couldNotRunPayload(error, options, durationMs) {
+    return {
+        outcome: 'could_not_run',
+        error_class: doctorErrorClass(error),
+        schema_version: DOCTOR_SCHEMA_VERSION,
+        cli_version: CLI_VERSION,
+        fix_mode: fixModeOf(options),
+        harness_scope: options.harness ?? 'all',
+        is_human_initiated: detectHumanInitiated(),
+        // Clamped like the completed row: over the cap the payload would 400 un-retried.
+        duration_ms: Math.min(durationMs, MAX_DURATION_MS),
+    };
+}

package/dist/lib/setup-telemetry.d.ts

@@ -43,6 +43,18 @@ declare const harnessResultSchema: z.ZodObject<{
 }, z.core.$strip>;
 /** First act of a `--all` run; everything upstream of it stays invisible. */
 export declare function sendSetupStarted(mcpUrl: string, attemptId?: string, apiKey?: string): Promise<void>;
+export type SetupBlockReason = 'key_rejected' | 'key_malformed' | 'key_unreadable';
+export type SetupBlockedMode = 'all' | 'pick' | 'single';
+export interface SetupBlockedDetail {
+    blockReason: SetupBlockReason;
+    keySource: 'env' | 'config' | 'explicit';
+    /** Only a server answer has one; a malformed key never reaches the API. */
+    status?: number;
+    mode: SetupBlockedMode;
+    attemptId?: string;
+}
+/** Terminal state for a run the key gate stopped; fires instead of setup_started. */
+export declare function sendSetupBlocked(mcpUrl: string, detail: SetupBlockedDetail, apiKey?: string): Promise<void>;
 export declare const setupCompletedPayloadSchema: z.ZodObject<{
     harnesses: z.ZodArray<z.ZodObject<{
         harness: z.ZodEnum<{

package/dist/lib/setup-telemetry.js

@@ -123,6 +123,30 @@ export async function sendSetupStarted(mcpUrl, attemptId, apiKey) {
         apiKey,
     });
 }
+/** Terminal state for a run the key gate stopped; fires instead of setup_started. */
+export async function sendSetupBlocked(mcpUrl, detail, apiKey) {
+    if (telemetryDisabled())
+        return;
+    const stamped = detail.attemptId && z.uuid().safeParse(detail.attemptId).success ? detail.attemptId : undefined;
+    await postConnectEvent({
+        endpoint: new URL('/api/cli/connect-event', mcpUrl).toString(),
+        body: JSON.stringify({
+            event: 'setup_blocked',
+            cli_version: CLI_VERSION,
+            block_reason: detail.blockReason,
+            key_source: detail.keySource,
+            ...(detail.status !== undefined ? { status: detail.status } : {}),
+            mode: detail.mode,
+            runtime_platform: process.platform,
+            ...(stamped ? { connect_attempt_id: stamped } : {}),
+            cli_invocation_id: CLI_INVOCATION_ID,
+            runtime_env: detectRuntimeEnv(),
+        }),
+        attempts: 1,
+        label: 'setup',
+        apiKey,
+    });
+}
 export const setupCompletedPayloadSchema = z.object({
     harnesses: z
         .array(harnessResultSchema)

package/package.json

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