@tiny-fish/cli 0.14.1-next.154 → 0.15.1-next.159

package/dist/commands/config-claude.js

@@ -1,5 +1,5 @@
 import { err, errLine, out } from "../lib/output.js";
-import { loadConfig, validateKeyFormat } from "../lib/auth.js";
+import { validatedApiKey } from "../lib/auth.js";
 import { readSettingsJson, writeSettingsJson, readClaudeMd, writeClaudeMd, mergeSettings, removeFromSettings, mergeClaudeMd, removeFromClaudeMd, claudeSettingsPath, claudeMdPath, isTinyfishConfiguredInSettings, isTinyfishConfiguredInClaudeMd, } from "../lib/claude-config.js";
 function loadExistingConfig() {
     let settings;
@@ -25,11 +25,7 @@ function loadExistingConfig() {
     return { settings, claudeMd };
 }
 function isSignedIn() {
-    const envKey = process.env.TINYFISH_API_KEY;
-    if (envKey && validateKeyFormat(envKey))
-        return true;
-    const config = loadConfig();
-    return !!config.api_key && validateKeyFormat(config.api_key);
+    return !!validatedApiKey();
 }
 function install(settings, claudeMd) {
     errLine("Configuring Claude Code to use TinyFish...\n");

package/dist/commands/connect.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import spawn from "cross-spawn";
-import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
+import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, resolvedApiKey, saveConnectContext, validateKeyFormat, validatedApiKey, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION, TINYFISH_CLI_PACKAGE } from "../lib/constants.js";
 import { cursorInstallDeeplink, cursorMcpPath, writeCursorMcpConfig, } from "../lib/cursor-config.js";
 import { runConnectAll } from "../lib/connect-all.js";
@@ -16,17 +16,29 @@ 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;
-const MCP_LOGIN_UNAVAILABLE_MESSAGE = "This Claude Code installation does not expose `claude mcp login`, which is required for " +
-    "one-command MCP authentication. Update Claude Code and retry, or authenticate TinyFish " +
-    "manually from /mcp.";
-const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "This Codex installation does not support one-command MCP authentication. Update Codex and " +
-    "retry, or add TinyFish manually with `codex mcp add`.";
-const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "This Hermes installation does not support one-command MCP authentication. Update Hermes and " +
-    "retry, or add TinyFish manually with `hermes mcp add`.";
-const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "This OpenClaw installation does not support global skill installation. Update OpenClaw and " +
-    "retry.";
-const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "This OpenCode installation does not support one-command MCP setup (`opencode mcp add --url`). " +
-    "Update OpenCode and retry, or add TinyFish manually with `opencode mcp add`.";
+// An old install is only one reason a flag can go unseen, so no message asserts the cause.
+const SUPPORT_CHECK_DEBUG_HINT = " Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.";
+const MCP_LOGIN_UNAVAILABLE_MESSAGE = "Could not confirm this Claude Code installation exposes `claude mcp login`: `claude mcp " +
+    "--help` did not list it. Update Claude Code and retry, or authenticate TinyFish manually " +
+    "from /mcp." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const CODEX_OAUTH_RESOURCE_UNAVAILABLE_MESSAGE = "Could not confirm this Codex installation supports one-command MCP authentication: `codex " +
+    "mcp add --help` did not list `--oauth-resource`. Update Codex and retry, or add TinyFish " +
+    "manually with `codex mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const HERMES_OAUTH_UNAVAILABLE_MESSAGE = "Could not confirm this Hermes installation supports one-command MCP authentication: `hermes " +
+    "mcp add --help` did not list `--auth oauth`. Update Hermes and retry, or add TinyFish " +
+    "manually with `hermes mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "Could not confirm this OpenClaw installation supports global skill installation: `openclaw " +
+    "skills install --help` did not list `--global` and `--acknowledge-clawhub-risk`. Update " +
+    "OpenClaw and retry, or install manually with `openclaw skills install @tinyfish/tinyfish " +
+    "--global --acknowledge-clawhub-risk`." +
+    SUPPORT_CHECK_DEBUG_HINT;
+const OPENCODE_MCP_ADD_UNAVAILABLE_MESSAGE = "Could not confirm this OpenCode installation supports one-command MCP setup: `opencode mcp " +
+    "add --help` did not list `--url`. Update OpenCode and retry, or add TinyFish manually with " +
+    "`opencode mcp add`." +
+    SUPPORT_CHECK_DEBUG_HINT;
 // OpenCode is model-agnostic (unlike Claude Code / Codex), so a fresh install can default to a
 // model with no tool support — TinyFish runs entirely on tool calls, so it would fail there.
 const OPENCODE_MODEL_NOTE = "Note: TinyFish runs on tool calls, so OpenCode needs a model that supports tool use. Image-only " +
@@ -192,7 +204,8 @@ function launchHermesWalkthrough() {
             cause: seedResult.error,
         });
     }
-    const sessionId = seedResult.stderr?.match(/session_id:\s*([^\s]+)/i)?.[1];
+    // A colourised id would carry its trailing escape sequence into `--resume` (PF-3452).
+    const sessionId = sanitizeLine(seedResult.stderr ?? "").match(/session_id:\s*([^\s]+)/i)?.[1];
     if (!sessionId) {
         throw new Error("Hermes did not return a walkthrough session ID");
     }
@@ -297,6 +310,8 @@ function createConnectTelemetry(mcpUrl, client, opts) {
                 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.
@@ -308,6 +323,8 @@ function createConnectTelemetry(mcpUrl, client, opts) {
 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)) {
@@ -317,8 +334,12 @@ function requireCommandSupport(client) {
         throwIfInterrupted(result);
         throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_command_unsupported", { cause: result.error });
     }
-    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+    // 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 ?? ""}`);
     if (!client.supportCheck.patterns.every((pattern) => pattern.test(output))) {
+        if (process.env["TINYFISH_DEBUG"]) {
+            errLine(`${client.command} ${client.supportCheck.args.join(" ")} printed:\n${output.trim()}`);
+        }
         throw new PrerequisiteError(client.supportCheck.unavailableMessage, "harness_too_old", {
             harnessVersion: probeHarnessVersion(client.command),
         });
@@ -572,8 +593,8 @@ async function connectNativeMcpClient(client, options) {
         mcpUrl.searchParams.set("client", client.connectClient);
         mcpUrl.searchParams.set("connect_attempt_id", telemetry.attemptId);
         // Prod MCP accepts X-API-Key, so a stored key replaces the browser OAuth hop.
-        const storedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
-        const useKeyAuth = client.headerAuthSupported === true && !!storedKey && validateKeyFormat(storedKey);
+        const storedKey = validatedApiKey(options.apiKey);
+        const useKeyAuth = client.headerAuthSupported === true && !!storedKey;
         state.stage = client.loginArgs ? "registration" : "registration_or_authentication";
         errLine(`Adding TinyFish to ${client.displayName}...`);
         const addResult = spawn.sync(client.command, [
@@ -747,9 +768,11 @@ export async function connectCursor(options) {
         state.stage = "authentication";
         ensureCliAuthenticated("cursor", options.apiKey);
         telemetry.track("checkpoint", { phase: "authenticated" });
-        // loadConfig() is unvalidated on read — a hand-edited key must not reach mcp.json.
-        const storedKey = options.apiKey ?? process.env["TINYFISH_API_KEY"] ?? loadConfig().api_key;
-        const resolvedKey = storedKey && validateKeyFormat(storedKey) ? storedKey : undefined;
+        const resolvedKey = validatedApiKey(options.apiKey);
+        // ensureCliAuthenticated leaves a key stored, and `auth status` exits 0 on a malformed one.
+        if (!resolvedKey) {
+            errLine("Ignoring the stored API key: invalid format. Run: tinyfish auth login");
+        }
         state.stage = "registration";
         errLine("Adding TinyFish to Cursor...");
         const mcpUrl = new URL(options.mcpUrl);

package/dist/lib/auth.d.ts

@@ -20,8 +20,26 @@ interface EnvironmentOptions {
 }
 export declare function persistApiKeyToEnvironment(apiKey: string, options?: EnvironmentOptions): void;
 export declare function clearConfig(): boolean;
+/** The one rule that is ours to enforce: the key becomes an HTTP header, so CR/LF cannot pass. */
+export declare function isHeaderSafe(key: string): boolean;
 export declare function validateKeyFormat(key: string): boolean;
 export declare function maskKey(key: string): string;
+export type KeySource = "explicit" | "env" | "config" | "none";
+export interface ResolvedKey {
+    key: string;
+    source: Exclude<KeySource, "none">;
+}
+export interface UnresolvedKey {
+    error: string;
+    source: KeySource;
+}
 /** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
 export declare function resolvedApiKey(explicitApiKey?: string): string | undefined;
+/** resolvedApiKey for keys that reach a config file or the wire — loadConfig() is unvalidated on read. */
+export declare function validatedApiKey(explicitApiKey?: string): string | undefined;
+/**
+ * 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 getApiKey(): string;

package/dist/lib/auth.js

@@ -132,52 +132,62 @@ export function clearConfig() {
         return false;
     }
 }
-export function validateKeyFormat(key) {
-    // Reject control characters (covers CR, LF, and others) — guards against header injection
+/** The one rule that is ours to enforce: the key becomes an HTTP header, so CR/LF cannot pass. */
+export function isHeaderSafe(key) {
     for (let i = 0; i < key.length; i += 1) {
         if (key.charCodeAt(i) < 0x20)
             return false;
     }
-    return KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
+    return true;
+}
+export function validateKeyFormat(key) {
+    return isHeaderSafe(key) && KEY_PREFIXES.some((p) => key.startsWith(p)) && key.length > MIN_KEY_LENGTH;
 }
 export function maskKey(key) {
     if (key.length <= 8)
         return "***";
     return key.slice(0, 12) + "..." + key.slice(-4);
 }
-/** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
-export function resolvedApiKey(explicitApiKey) {
+// The one flag/env/config precedence chain; `source` says which place a caller must name.
+function lookupApiKey(explicitApiKey) {
     if (explicitApiKey)
-        return explicitApiKey;
+        return { value: explicitApiKey, source: "explicit" };
     const envKey = process.env["TINYFISH_API_KEY"];
     if (envKey)
-        return envKey;
-    try {
-        return loadConfig().api_key;
+        return { value: envKey, source: "env" };
+    // No try/catch: loadConfig swallows its own errors and returns {}.
+    const stored = loadConfig().api_key;
+    return stored ? { value: stored, source: "config" } : { source: "none" };
+}
+/** Key for optional paths (telemetry, auth probes) — absent is a valid answer, so never exits. */
+export function resolvedApiKey(explicitApiKey) {
+    return lookupApiKey(explicitApiKey).value;
+}
+/** resolvedApiKey for keys that reach a config file or the wire — loadConfig() is unvalidated on read. */
+export function validatedApiKey(explicitApiKey) {
+    const key = resolvedApiKey(explicitApiKey);
+    return key && validateKeyFormat(key) ? key : undefined;
+}
+/**
+ * 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();
+    if (!value || source === "none") {
+        return { error: "No API key found. Run: tinyfish auth login", source: "none" };
     }
-    catch {
-        return undefined;
+    // Shape is the server's call. A local prefix rule turns a key format we have not shipped
+    // support for yet into a hard failure the user cannot work around, and the 401 says more.
+    if (!isHeaderSafe(value)) {
+        return { error: "The API key contains control characters and cannot be sent", source };
     }
+    return { key: value, source };
 }
 export function getApiKey() {
-    const envKey = process.env.TINYFISH_API_KEY;
-    if (envKey) {
-        if (!validateKeyFormat(envKey)) {
-            err({
-                error: "TINYFISH_API_KEY has invalid format. Expected sk-tinyfish-... or sk-mino-...",
-            });
-            process.exit(1);
-        }
-        return envKey;
-    }
-    const config = loadConfig();
-    if (config.api_key) {
-        if (!validateKeyFormat(config.api_key)) {
-            err({ error: "Stored API key has invalid format. Run: tinyfish auth login" });
-            process.exit(1);
-        }
-        return config.api_key;
-    }
-    err({ error: "No API key found. Run: tinyfish auth login" });
+    const resolved = apiKeyStatus();
+    if ("key" in resolved)
+        return resolved.key;
+    err({ error: resolved.error });
     process.exit(1);
 }

package/dist/lib/connect-all.js

@@ -1,7 +1,7 @@
 import * as readline from "node:readline/promises";
 import spawn from "cross-spawn";
 import { connectClaudeCode, connectCodex, connectCursor, connectHermes, connectOpenClaw, } from "../commands/connect.js";
-import { resolvedApiKey, validateKeyFormat } from "./auth.js";
+import { validatedApiKey } from "./auth.js";
 import { detectInstalledHarnesses, FIVE_HARNESSES, } from "./harness-detect.js";
 import { detectHumanInitiated } from "./harness.js";
 import { emitNotice } from "./notice.js";
@@ -29,10 +29,6 @@ const UNINSTALL_POINTERS = {
     hermes: "hermes mcp remove tinyfish",
     openclaw: "openclaw skills uninstall @tinyfish/tinyfish --global",
 };
-function hasStoredAuth(explicitApiKey) {
-    const key = resolvedApiKey(explicitApiKey);
-    return !!key && validateKeyFormat(key);
-}
 async function runHarnessConnect(harness, opts) {
     const base = { apiKey: opts.apiKey, mcpUrl: opts.mcpUrl, launch: false };
     if (harness === "claude-code")
@@ -102,7 +98,7 @@ async function processHarness(detection, opts, prompt) {
     if (opts.dryRun) {
         const plan = opts.uninstall
             ? uninstallPlanText(harness)
-            : planText(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+            : planText(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
         return { ...base, outcome: "dry_run", fixCommand: plan };
     }
     if (opts.uninstall)
@@ -110,7 +106,7 @@ async function processHarness(detection, opts, prompt) {
     const isTTY = detectHumanInitiated();
     // claude-code leaves the own-OAuth set when a key is stored: `mcp add --header
     // X-API-Key` replaces its login. codex/hermes have no header path, so they keep the skip.
-    const keyed = hasStoredAuth(opts.apiKey);
+    const keyed = !!validatedApiKey(opts.apiKey);
     const ownAuthHarness = HARNESS_OWN_AUTH.has(harness) && !(harness === "claude-code" && keyed);
     const alreadyAuthed = !ownAuthHarness && keyed;
     if (!isTTY && !alreadyAuthed) {
@@ -142,7 +138,7 @@ async function processHarness(detection, opts, prompt) {
     if (!interruptedBefore && process.exitCode === 130) {
         return { ...base, outcome: "interrupted", fixCommand: `tinyfish connect ${harness}` };
     }
-    const verify = await verifyHarness(harness, opts.mcpUrl, resolvedApiKey(opts.apiKey));
+    const verify = await verifyHarness(harness, opts.mcpUrl, validatedApiKey(opts.apiKey));
     return {
         ...base,
         installed: true,
@@ -279,7 +275,7 @@ export async function runConnectAll(opts) {
             verify_depth: r.verifyDepth ?? null,
             verify_ok: r.verifyOk ?? null,
         }));
-        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, resolvedApiKey(opts.apiKey));
+        await sendSetupCompleted(opts.mcpUrl, harnessTelemetry, validatedApiKey(opts.apiKey));
         // After the summary and before the launch, which is where the user is reading.
         emitNotice();
     }

package/dist/lib/cursor-config.d.ts

@@ -9,6 +9,15 @@ export interface CursorMcpWriteResult {
 }
 /** Dry-run description of the pending write; touches nothing. */
 export declare function planCursorWrite(mcpUrl: string, apiKey?: string): string;
+export interface CursorTinyfishEntry {
+    present: boolean;
+    hasApiKeyHeader: boolean;
+    /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
+    url?: string;
+    error?: string;
+}
+/** Read-only probe for doctor — reports shape, never the header value. */
+export declare function readCursorTinyfishEntry(): CursorTinyfishEntry;
 /** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
 export declare function writeCursorMcpConfig(mcpUrl: string, apiKey?: string): CursorMcpWriteResult;
 /** Cursor deeplink format: cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64 */

package/dist/lib/cursor-config.js

@@ -65,6 +65,25 @@ export function planCursorWrite(mcpUrl, apiKey) {
         ? `${filePath}: would create with a "tinyfish" MCP server entry${authNote}`
         : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry${authNote}`;
 }
+/** Read-only probe for doctor — reports shape, never the header value. */
+export function readCursorTinyfishEntry() {
+    const existing = readExisting();
+    if ("error" in existing)
+        return { present: false, hasApiKeyHeader: false, error: existing.error };
+    const servers = existing.parsed.mcpServers;
+    const entry = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
+    if (!isPlainRecord(entry))
+        return { present: false, hasApiKeyHeader: false };
+    const headers = entry.headers;
+    // Header names are case-insensitive, and this file is hand-editable — matching only the
+    // casing we write would understate auth mode for a user who typed it differently.
+    return {
+        present: true,
+        hasApiKeyHeader: isPlainRecord(headers) &&
+            Object.entries(headers).some(([name, value]) => name.toLowerCase() === "x-api-key" && typeof value === "string"),
+        ...(typeof entry.url === "string" ? { url: entry.url } : {}),
+    };
+}
 // Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
 function commitServers(filePath, existing, servers) {
     fs.mkdirSync(cursorConfigDir(), { recursive: true, mode: 0o700 });

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

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
+export declare const DOCTOR_SCHEMA_VERSION = 1;
+declare const checkStatusSchema: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+    warn: "warn";
+    skip: "skip";
+}>;
+declare const doctorCheckSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        pass: "pass";
+        fail: "fail";
+        warn: "warn";
+        skip: "skip";
+    }>;
+    detail: z.ZodString;
+    harness: z.ZodNullable<z.ZodEnum<{
+        openclaw: "openclaw";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        "claude-code": "claude-code";
+    }>>;
+}, z.core.$strip>;
+declare const doctorHarnessSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        openclaw: "openclaw";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        "claude-code": "claude-code";
+    }>;
+    detected: z.ZodBoolean;
+    registered: z.ZodEnum<{
+        unknown: "unknown";
+        yes: "yes";
+        no: "no";
+    }>;
+    auth_mode: z.ZodEnum<{
+        unknown: "unknown";
+        oauth: "oauth";
+        "api-key": "api-key";
+    }>;
+    proves_harness_reach: z.ZodBoolean;
+}, z.core.$strip>;
+declare const doctorRepairSchema: z.ZodObject<{
+    for: z.ZodString;
+    action: z.ZodEnum<{
+        connect: "connect";
+        "auth-login": "auth-login";
+    }>;
+    harness: z.ZodNullable<z.ZodEnum<{
+        openclaw: "openclaw";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        "claude-code": "claude-code";
+    }>>;
+    command: z.ZodString;
+    unattended_safe: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const doctorReportSchema: z.ZodObject<{
+    schema_version: z.ZodInt;
+    cli_version: z.ZodString;
+    ok: z.ZodBoolean;
+    checks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        status: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+            warn: "warn";
+            skip: "skip";
+        }>;
+        detail: z.ZodString;
+        harness: z.ZodNullable<z.ZodEnum<{
+            openclaw: "openclaw";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            "claude-code": "claude-code";
+        }>>;
+    }, z.core.$strip>>;
+    harnesses: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            openclaw: "openclaw";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            "claude-code": "claude-code";
+        }>;
+        detected: z.ZodBoolean;
+        registered: z.ZodEnum<{
+            unknown: "unknown";
+            yes: "yes";
+            no: "no";
+        }>;
+        auth_mode: z.ZodEnum<{
+            unknown: "unknown";
+            oauth: "oauth";
+            "api-key": "api-key";
+        }>;
+        proves_harness_reach: z.ZodBoolean;
+    }, z.core.$strip>>;
+    repairs: z.ZodArray<z.ZodObject<{
+        for: z.ZodString;
+        action: z.ZodEnum<{
+            connect: "connect";
+            "auth-login": "auth-login";
+        }>;
+        harness: z.ZodNullable<z.ZodEnum<{
+            openclaw: "openclaw";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            "claude-code": "claude-code";
+        }>>;
+        command: z.ZodString;
+        unattended_safe: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type CheckStatus = z.infer<typeof checkStatusSchema>;
+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>;
+/** Doctor itself broke, which is a different claim from "your setup is broken". */
+export declare const DOCTOR_COULD_NOT_RUN = 2;
+/** Skips never fail the run; a skip means not applicable, not broken. */
+export declare function exitCodeFor(checks: DoctorCheck[]): 0 | 1;
+export declare function renderPretty(report: DoctorReport): string;
+export {};

package/dist/lib/doctor-report.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { FIVE_HARNESSES } from "./harness-detect.js";
+/** Bumped whenever a consumer could misread the payload; the cookbook skill releases separately. */
+export const DOCTOR_SCHEMA_VERSION = 1;
+const checkStatusSchema = z.enum(["pass", "fail", "warn", "skip"]);
+const harnessSchema = z.enum(FIVE_HARNESSES);
+const doctorCheckSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: checkStatusSchema,
+    detail: z.string(),
+    harness: harnessSchema.nullable(),
+});
+const doctorHarnessSchema = z.object({
+    harness: harnessSchema,
+    detected: z.boolean(),
+    registered: z.enum(["yes", "no", "unknown"]),
+    auth_mode: z.enum(["api-key", "oauth", "unknown"]),
+    proves_harness_reach: z.boolean(),
+});
+// `action` is what `--fix` dispatches on, not the harness field: keying off a null harness
+// conflated "run auth login" with a non-executable repair and the credential fix never ran.
+const doctorRepairSchema = z.object({
+    for: z.string(),
+    action: z.enum(["connect", "auth-login"]),
+    harness: harnessSchema.nullable(),
+    command: z.string(),
+    unattended_safe: z.boolean(),
+});
+export const doctorReportSchema = z
+    .object({
+    // Not `z.literal`: a consumer must be able to read a future version and say so.
+    schema_version: z.int().positive(),
+    cli_version: z.string(),
+    ok: z.boolean(),
+    checks: z.array(doctorCheckSchema),
+    harnesses: z.array(doctorHarnessSchema),
+    repairs: z.array(doctorRepairSchema),
+})
+    // A report that says ok while a check failed is worse than no report.
+    .refine((report) => !report.ok || report.checks.every((check) => check.status !== "fail"), {
+    message: "ok cannot be true while a check has failed",
+    path: ["ok"],
+});
+const GLYPHS = { pass: "✓", fail: "✗", warn: "⚠", skip: "…" };
+/** Doctor itself broke, which is a different claim from "your setup is broken". */
+export const DOCTOR_COULD_NOT_RUN = 2;
+/** Skips never fail the run; a skip means not applicable, not broken. */
+export function exitCodeFor(checks) {
+    return checks.some((check) => check.status === "fail") ? 1 : 0;
+}
+export function renderPretty(report) {
+    const lines = report.checks.map((c) => `${GLYPHS[c.status]} ${c.title}${c.detail ? ` — ${c.detail}` : ""}`);
+    if (report.repairs.length > 0) {
+        lines.push("", "Repairs:");
+        for (const repair of report.repairs)
+            lines.push(`  ${repair.command}`);
+    }
+    return lines.join("\n");
+}

package/dist/lib/harness-detect.d.ts

@@ -1,6 +1,8 @@
 export declare const FIVE_HARNESSES: readonly ["claude-code", "codex", "cursor", "hermes", "openclaw"];
 export type FiveHarness = (typeof FIVE_HARNESSES)[number];
 export declare function harnessConfigPath(harness: FiveHarness): string;
+/** For reason strings that name a location; keeps them in sync with the table above. */
+export declare function harnessDisplayPath(harness: FiveHarness): string;
 export interface HarnessDetection {
     harness: FiveHarness;
     detected: boolean;

package/dist/lib/harness-detect.js

@@ -13,6 +13,10 @@ const CONFIG_DIRS = {
 export function harnessConfigPath(harness) {
     return path.join(os.homedir(), CONFIG_DIRS[harness]); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
 }
+/** For reason strings that name a location; keeps them in sync with the table above. */
+export function harnessDisplayPath(harness) {
+    return `~/${CONFIG_DIRS[harness]}`;
+}
 export function detectInstalledHarnesses() {
     return FIVE_HARNESSES.map((harness) => {
         const configPath = harnessConfigPath(harness);

package/dist/lib/registration-detect.d.ts

@@ -0,0 +1,15 @@
+import { type FiveHarness } from "./harness-detect.js";
+export type Registered = "yes" | "no" | "unknown";
+export type AuthMode = "api-key" | "oauth" | "unknown";
+export interface RegistrationStatus {
+    harness: FiveHarness;
+    detected: boolean;
+    registered: Registered;
+    authMode: AuthMode;
+    connectedBefore: boolean;
+    /** The endpoint the harness is actually pointed at, when the probe exposes it. */
+    registeredUrl?: string;
+    reason?: string;
+}
+/** Never throws; a failed probe is `unknown` with a reason, so no caller can read it as healthy. */
+export declare function detectRegistrations(harnesses?: FiveHarness[]): RegistrationStatus[];

package/dist/lib/registration-detect.js

@@ -0,0 +1,239 @@
+import * as fs from "fs";
+import * as path from "path";
+import spawn from "cross-spawn";
+import { z } from "zod";
+import { loadConfig } from "./auth.js";
+import { errLine } from "./output.js";
+import { readCursorTinyfishEntry } from "./cursor-config.js";
+import { detectInstalledHarnesses, harnessConfigPath, harnessDisplayPath, } from "./harness-detect.js";
+// 2s tripped on a cold `hermes mcp list` (0.3s warm), reporting `unknown` on a healthy install.
+const PROBE_TIMEOUT_MS = 6_000;
+// A list, verified against codex 0.146. A name-keyed map was accepted here too, but every
+// field is optional, so that arm parsed *any* object-of-objects: a wrapper like
+// `{"servers": {...}}` decoded as one entry named `servers` and reported TinyFish absent.
+const codexEntrySchema = z.looseObject({
+    name: z.string().optional(),
+    auth_status: z.string().optional(),
+    transport: z
+        .looseObject({ url: z.string().optional(), bearer_token_env_var: z.string().nullish() })
+        .optional(),
+});
+const codexListSchema = z.array(codexEntrySchema);
+// An old harness CLI without the subcommand exits non-zero too; that is unknown, not absent.
+const UNSUPPORTED_SUBCOMMAND = /unknown command|unrecognized subcommand|invalid subcommand/i;
+// `claude mcp get` exits 1 for a usage error too, so only this message is evidence of absence.
+const NO_SUCH_SERVER = /no (?:mcp )?server named/i;
+const API_KEY_HEADER = /x-api-key/i;
+// The report is pasted in public, so every reason is authored here. A spawn error's own
+// message quotes absolute paths, which is how a home directory reaches the payload.
+function spawnFailureReason(command, code) {
+    if (code === "ENOENT")
+        return `\`${command}\` is not on PATH`;
+    if (code === "EACCES")
+        return `\`${command}\` is not executable`;
+    return `could not run \`${command}\``;
+}
+function runProbe(command, args) {
+    const result = spawn.sync(command, args, { encoding: "utf8", timeout: PROBE_TIMEOUT_MS });
+    if (result.error) {
+        const code = result.error.code;
+        // A timeout arrives as ETIMEDOUT here, not only as a signal, so it must be named before
+        // the generic spawn failure; otherwise a timeout reports "could not run".
+        if (code === "ETIMEDOUT") {
+            return { outcome: "unavailable", reason: `\`${command} ${args.join(" ")}\` timed out` };
+        }
+        return { outcome: "unavailable", reason: spawnFailureReason(command, code) };
+    }
+    // Reached only when something else killed the child, so this is a crash, not the timeout.
+    if (result.signal) {
+        return { outcome: "unavailable", reason: `\`${command}\` was killed by ${result.signal}` };
+    }
+    const stdout = result.stdout ?? "";
+    return {
+        outcome: "ran",
+        exitCode: result.status ?? 1,
+        stdout,
+        output: `${stdout}${result.stderr ?? ""}`,
+    };
+}
+// claude-code only. Codex cannot use this: its `mcp get` exits 0 on a missing server.
+function fromMcpGet(command, keyAuthPattern) {
+    const probe = runProbe(command, ["mcp", "get", "tinyfish"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    if (probe.exitCode !== 0) {
+        if (UNSUPPORTED_SUBCOMMAND.test(probe.output)) {
+            return {
+                registered: "unknown",
+                authMode: "unknown",
+                reason: `\`${command} mcp get\` is unsupported by this version`,
+            };
+        }
+        // A broken CLI also exits nonzero, and reading that as absence earns a spurious repair.
+        if (!NO_SUCH_SERVER.test(probe.output)) {
+            return {
+                registered: "unknown",
+                authMode: "unknown",
+                reason: `\`${command} mcp get\` failed without reporting the server as absent`,
+            };
+        }
+        return { registered: "no", authMode: "unknown" };
+    }
+    // Positive evidence only: whether `mcp get` echoes headers at all is unverified, so absence
+    // of the pattern is `unknown`, never proof of OAuth.
+    const url = /^\s*URL:\s*(\S+)/m.exec(probe.output)?.[1];
+    return {
+        registered: "yes",
+        authMode: keyAuthPattern.test(probe.output) ? "api-key" : "unknown",
+        ...(url ? { registeredUrl: url } : {}),
+    };
+}
+// `codex mcp get <missing>` prints an error and exits 0, so presence must never be read from
+// its exit code; `mcp list --json` is the only trustworthy read-back.
+function probeCodex() {
+    const probe = runProbe("codex", ["mcp", "list", "--json"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    // Presence is never inferred from exit code 0, but a nonzero exit means the output cannot
+    // be trusted either — that is `unknown`, not "no server".
+    if (probe.exitCode !== 0) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `\`codex mcp list --json\` exited ${probe.exitCode}`,
+        };
+    }
+    let servers;
+    try {
+        // stdout only: an update banner on stderr would otherwise break the parse and report a
+        // healthy install as `unknown`.
+        servers = JSON.parse(probe.stdout);
+    }
+    catch {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "`codex mcp list --json` returned unparseable output",
+        };
+    }
+    // A scalar or a wrapper object decodes fine and then silently reports "no server", which
+    // would suggest a spurious repair. Anything but a list is unknown.
+    const shape = codexListSchema.safeParse(servers);
+    if (!shape.success) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "`codex mcp list --json` returned an unexpected shape",
+        };
+    }
+    const entry = shape.data.find((s) => s.name === "tinyfish");
+    if (!entry)
+        return { registered: "no", authMode: "unknown" };
+    // auth_status is the configured auth type, not whether a login succeeded — exactly auth_mode.
+    const codexUrl = entry.transport?.url;
+    return {
+        registered: "yes",
+        // Read from this entry: codex emits `bearer_token_env_var` on every HTTP server, so testing
+        // the whole payload reports api-key for TinyFish because some other server carries a key.
+        authMode: entry.auth_status === "o_auth"
+            ? "oauth"
+            : entry.transport?.bearer_token_env_var
+                ? "api-key"
+                : "unknown",
+        ...(codexUrl ? { registeredUrl: codexUrl } : {}),
+    };
+}
+function probeCursor() {
+    const entry = readCursorTinyfishEntry();
+    if (entry.error) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: "mcp.json exists but could not be read or parsed",
+        };
+    }
+    if (!entry.present)
+        return { registered: "no", authMode: "unknown" };
+    return {
+        registered: "yes",
+        authMode: entry.hasApiKeyHeader ? "api-key" : "unknown",
+        ...(entry.url ? { registeredUrl: entry.url } : {}),
+    };
+}
+// Hermes registers with `--auth oauth` and has no key path today, so mode is fixed.
+function probeHermes() {
+    const probe = runProbe("hermes", ["mcp", "list"]);
+    if (probe.outcome === "unavailable") {
+        return { registered: "unknown", authMode: "unknown", reason: probe.reason };
+    }
+    if (probe.exitCode !== 0) {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `\`hermes mcp list\` exited ${probe.exitCode}`,
+        };
+    }
+    return probe.output.includes("tinyfish")
+        ? { registered: "yes", authMode: "oauth" }
+        : { registered: "no", authMode: "unknown" };
+}
+// OpenClaw installs a skill, not an MCP server; the skill shells the CLI, so auth is the CLI key.
+function probeOpenClaw() {
+    const skillsDir = path.join(harnessConfigPath("openclaw"), "skills");
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir);
+    }
+    catch {
+        return {
+            registered: "unknown",
+            authMode: "unknown",
+            reason: `no global skills directory at ${harnessDisplayPath("openclaw")}/skills; OpenClaw layout is unverified`,
+        };
+    }
+    return entries.some((name) => /tinyfish/i.test(name))
+        ? { registered: "yes", authMode: "api-key" }
+        : { registered: "no", authMode: "unknown" };
+}
+const PROBES = {
+    "claude-code": () => fromMcpGet("claude", API_KEY_HEADER),
+    codex: probeCodex,
+    cursor: probeCursor,
+    hermes: probeHermes,
+    openclaw: probeOpenClaw,
+};
+/** Never throws; a failed probe is `unknown` with a reason, so no caller can read it as healthy. */
+export function detectRegistrations(harnesses) {
+    const connect = loadConfig().connect ?? {};
+    return detectInstalledHarnesses()
+        .filter((detection) => !harnesses || harnesses.includes(detection.harness))
+        .map((detection) => {
+        const base = {
+            harness: detection.harness,
+            detected: detection.detected,
+            connectedBefore: detection.harness in connect,
+        };
+        // Undetected means nothing to probe: no spawn cost, and no misleading "unknown".
+        if (!detection.detected) {
+            return { ...base, registered: "no", authMode: "unknown" };
+        }
+        try {
+            return { ...base, ...PROBES[detection.harness]() };
+        }
+        catch (e) {
+            // An arbitrary throw is the one message we cannot author, so it never ships. Full
+            // fidelity stays on stderr behind --debug, which is not the pasted artifact.
+            if (process.env["TINYFISH_DEBUG"]) {
+                errLine(`probe ${detection.harness} threw: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            return {
+                ...base,
+                registered: "unknown",
+                authMode: "unknown",
+                reason: "the probe failed unexpectedly",
+            };
+        }
+    });
+}

package/package.json

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