@tiny-fish/cli 0.15.1-next.158 → 0.15.1-next.160

package/dist/commands/doctor.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import { type DoctorReport } from "../lib/doctor-report.js";
+import { type FiveHarness } from "../lib/harness-detect.js";
+export interface DoctorOptions {
+    mcpUrl: string;
+    harness?: FiveHarness;
+}
+export declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+export declare function registerDoctor(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,217 @@
+import { apiKeyStatus } from "../lib/auth.js";
+import { CLI_VERSION } from "../lib/constants.js";
+import { DOCTOR_COULD_NOT_RUN, DOCTOR_SCHEMA_VERSION, doctorReportSchema, exitCodeFor, renderPretty, } from "../lib/doctor-report.js";
+import { FIVE_HARNESSES } from "../lib/harness-detect.js";
+import { err, errLine, out, outLine } from "../lib/output.js";
+import { detectRegistrations } from "../lib/registration-detect.js";
+import { verifyMcpAuth, verifyMcpHealth } from "../lib/verify.js";
+import { DEFAULT_MCP_URL } 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, authCallPassed, healthOk, mcpUrl) {
+    // An endpoint doctor could not reach proves nothing about a harness pointed at it.
+    if (!healthOk)
+        return false;
+    if (pointsElsewhere(status.registeredUrl, mcpUrl))
+        return false;
+    return status.registered === "yes" && status.authMode === "api-key" && authCallPassed;
+}
+// Reports the version, never judges it: staleness is the server's call via X-TF-Notice.
+function checkCliVersion() {
+    return {
+        id: "cli-version",
+        title: `CLI ${CLI_VERSION}`,
+        status: "pass",
+        detail: `${CLI_VERSION}; the server reports staleness via X-TF-Notice`,
+        harness: null,
+    };
+}
+async function checkConnectivity(mcpUrl) {
+    const health = await verifyMcpHealth(mcpUrl);
+    return {
+        id: "mcp-connectivity",
+        title: "MCP endpoint reachable",
+        status: health.ok ? "pass" : "fail",
+        detail: health.ok ? mcpUrl : (health.code ?? "the endpoint is unreachable"),
+        harness: null,
+    };
+}
+// Query strings carry the connect attempt id, so they differ on every healthy install.
+function endpointOf(url) {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname.replace(/\/$/, "")}`;
+}
+/** Host alone let `/wrong-path` and plain `http://` through and claim the harness reaches us. */
+function pointsElsewhere(registeredUrl, mcpUrl) {
+    if (!registeredUrl)
+        return undefined;
+    try {
+        const registered = endpointOf(registeredUrl);
+        return registered === endpointOf(mcpUrl) ? undefined : registered;
+    }
+    catch {
+        // An endpoint that will not parse cannot be shown to match, so it does not.
+        return "an unparseable endpoint";
+    }
+}
+function registrationVerdict(status, mcpUrl) {
+    if (!status.detected)
+        return { status: "skip", detail: "harness not installed" };
+    if (status.registered === "unknown") {
+        return { status: "warn", detail: status.reason ?? "could not determine registration" };
+    }
+    if (status.registered === "yes") {
+        // A `tinyfish` entry aimed at a dev server is registered and still cannot reach TinyFish.
+        const elsewhere = pointsElsewhere(status.registeredUrl, mcpUrl);
+        if (elsewhere) {
+            return {
+                status: "fail",
+                detail: `registered, but points at ${elsewhere} rather than ${endpointOf(mcpUrl)}`,
+            };
+        }
+        return { status: "pass", detail: `registered, auth mode ${status.authMode}` };
+    }
+    // Connected once and now absent is a broken install; never connected is just not set up.
+    return status.connectedBefore
+        ? { status: "fail", detail: "connected previously but TinyFish is no longer registered" }
+        : { status: "warn", detail: "installed but TinyFish was never connected" };
+}
+function checkRegistration(status, mcpUrl) {
+    return {
+        id: "harness-registration",
+        title: `${status.harness} registration`,
+        harness: status.harness,
+        ...registrationVerdict(status, mcpUrl),
+    };
+}
+function checkCredential() {
+    const resolved = apiKeyStatus();
+    const check = {
+        id: "cli-credential",
+        title: "CLI credential",
+        status: "key" in resolved ? "pass" : "fail",
+        detail: "key" in resolved ? `valid key from ${resolved.source}` : resolved.error,
+        harness: null,
+    };
+    return "key" in resolved ? { check, key: resolved.key } : { check };
+}
+async function checkAuthCall(key) {
+    if (!key) {
+        return {
+            id: "cli-auth-call",
+            title: "Authenticated call",
+            status: "skip",
+            detail: "no credential to test",
+            harness: null,
+        };
+    }
+    const auth = await verifyMcpAuth(key);
+    return {
+        id: "cli-auth-call",
+        title: "Authenticated call",
+        status: auth.ok ? "pass" : "fail",
+        detail: auth.ok ? "listRuns succeeded" : (auth.code ?? "the authenticated call failed"),
+        harness: null,
+    };
+}
+// 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 = [];
+    for (const status of statuses) {
+        // `unknown` earns nothing: running connect off a failed probe contradicts the check's detail.
+        // A registered-but-misaimed entry does earn one, since connect rewrites the URL.
+        const misaimed = checks.some((c) => c.harness === status.harness && c.status === "fail");
+        if (!status.detected || (status.registered !== "no" && !misaimed))
+            continue;
+        repairs.push({
+            for: status.registered === "yes"
+                ? `${status.harness}-points-elsewhere`
+                : status.connectedBefore
+                    ? `${status.harness}-registration-lost`
+                    : `${status.harness}-not-connected`,
+            action: "connect",
+            harness: status.harness,
+            command: `tinyfish connect ${status.harness}`,
+            unattended_safe: UNATTENDED_SAFE.has(status.harness),
+        });
+    }
+    // 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");
+    if (credentialBroken) {
+        repairs.push({
+            for: "cli-credential-invalid",
+            action: "auth-login",
+            harness: null,
+            command: "tinyfish auth login",
+            unattended_safe: false,
+        });
+    }
+    return repairs;
+}
+export async function runDoctor(options) {
+    const statuses = detectRegistrations(options.harness ? [options.harness] : undefined);
+    const credential = checkCredential();
+    const checks = [
+        checkCliVersion(),
+        await checkConnectivity(options.mcpUrl),
+        ...statuses.map((status) => checkRegistration(status, options.mcpUrl)),
+        credential.check,
+        await checkAuthCall(credential.key),
+    ];
+    const authCallPassed = checks.some((c) => c.id === "cli-auth-call" && c.status === "pass");
+    const healthOk = checks.some((c) => c.id === "mcp-connectivity" && c.status === "pass");
+    const harnesses = statuses.map((status) => ({
+        harness: status.harness,
+        detected: status.detected,
+        registered: status.registered,
+        auth_mode: status.authMode,
+        proves_harness_reach: provesHarnessReach(status, authCallPassed, healthOk, options.mcpUrl),
+    }));
+    const body = {
+        schema_version: DOCTOR_SCHEMA_VERSION,
+        cli_version: CLI_VERSION,
+        ok: exitCodeFor(checks) === 0,
+        checks,
+        harnesses,
+        repairs: repairsFor(checks, statuses),
+    };
+    // Nothing to scrub: every string above is authored here or enumerated at its source.
+    return doctorReportSchema.parse(body);
+}
+export function registerDoctor(program) {
+    program
+        .command("doctor")
+        .description("Diagnose your TinyFish setup")
+        .option("--pretty", "Human-readable check list instead of JSON")
+        .option("--harness <name>", `Restrict to one harness (${FIVE_HARNESSES.join(", ")})`)
+        .option("--url <mcpUrl>", "MCP endpoint override")
+        .action(async (options) => {
+        if (options.harness && !FIVE_HARNESSES.includes(options.harness)) {
+            err({ error: `Unknown --harness value: ${options.harness}` });
+            process.exitCode = DOCTOR_COULD_NOT_RUN;
+            return;
+        }
+        let report;
+        try {
+            report = await runDoctor({
+                mcpUrl: options.url ?? DEFAULT_MCP_URL,
+                ...(options.harness ? { harness: options.harness } : {}),
+            });
+        }
+        catch (e) {
+            // Exit 2 means doctor itself broke, a different claim from "your setup is broken".
+            // Authored, like every other string a user might paste; raw text is behind --debug.
+            if (process.env["TINYFISH_DEBUG"]) {
+                errLine(e instanceof Error ? (e.stack ?? e.message) : String(e));
+            }
+            err({ error: "doctor could not complete; re-run with --debug for the raw error" });
+            process.exitCode = DOCTOR_COULD_NOT_RUN;
+            return;
+        }
+        if (options.pretty)
+            outLine(renderPretty(report));
+        else
+            out(report);
+        process.exitCode = exitCodeFor(report.checks);
+    });
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import { registerRuns } from "./commands/runs.js";
 import { registerConfigureClaude } from "./commands/config-claude.js";
 import { registerSearch } from "./commands/search.js";
 import { registerConnect } from "./commands/connect.js";
+import { registerDoctor } from "./commands/doctor.js";
 import { registerUpgrade } from "./commands/upgrade.js";
 import { registerOnboard } from "./commands/onboard.js";
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -32,6 +33,7 @@ program
 registerAuth(program);
 registerOnboard(program);
 registerConnect(program);
+registerDoctor(program);
 registerUpgrade(program);
 registerConfigureClaude(program);
 registerBrowser(program);

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/verify.d.ts

@@ -3,6 +3,8 @@ export interface VerifyResult {
     depth: VerifyDepth;
     ok: boolean;
     reason?: string;
+    /** Authored summary of `reason`, safe to publish. Additive: `connect` still prints `reason`. */
+    code?: string;
 }
 /** Reachability check. Verify failure is a warning, never install failure. */
 export declare function verifyMcpHealth(mcpUrl: string): Promise<VerifyResult>;

package/dist/lib/verify.js

@@ -1,5 +1,37 @@
 import { listRuns } from "./client.js";
+import { ApiError } from "./output.js";
 const VERIFY_TIMEOUT_MS = 5_000;
+// `fetch` collapses every network fault to "fetch failed" and hides the cause on `e.cause`.
+function networkCode(e) {
+    const cause = e?.cause;
+    switch (cause?.code) {
+        case "ECONNREFUSED":
+            return "connection refused";
+        case "ENOTFOUND":
+            return "host not found";
+        case "ETIMEDOUT":
+            return "connection timed out";
+        case "CERT_HAS_EXPIRED":
+        case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+        case "DEPTH_ZERO_SELF_SIGNED_CERT":
+            return "TLS verification failed";
+        default:
+            return e instanceof Error && e.name === "TimeoutError"
+                ? "request timed out"
+                : "could not reach the endpoint";
+    }
+}
+function authCode(e) {
+    if (!(e instanceof ApiError))
+        return "the authenticated call failed";
+    if (e.status === 401)
+        return "the API key is invalid or expired";
+    if (e.status === 403)
+        return "the API key is not allowed to do this";
+    if (e.status === 429)
+        return "rate limited";
+    return e.status >= 500 ? "TinyFish returned a server error" : `the API returned HTTP ${e.status}`;
+}
 /** Reachability check. Verify failure is a warning, never install failure. */
 export async function verifyMcpHealth(mcpUrl) {
     try {
@@ -11,7 +43,12 @@ export async function verifyMcpHealth(mcpUrl) {
         });
         // MCP rejects bare GET with 4xx — still proves endpoint routed.
         if (response.status >= 500) {
-            return { depth: "health", ok: false, reason: `endpoint returned HTTP ${response.status}` };
+            return {
+                depth: "health",
+                ok: false,
+                reason: `endpoint returned HTTP ${response.status}`,
+                code: `the endpoint returned HTTP ${response.status}`,
+            };
         }
         return { depth: "health", ok: true };
     }
@@ -20,6 +57,7 @@ export async function verifyMcpHealth(mcpUrl) {
             depth: "health",
             ok: false,
             reason: e instanceof Error ? e.message : "network error reaching MCP endpoint",
+            code: networkCode(e),
         };
     }
 }
@@ -31,6 +69,11 @@ export async function verifyMcpAuth(apiKey) {
         return { depth: "health+auth", ok: true };
     }
     catch (e) {
-        return { depth: "health+auth", ok: false, reason: e instanceof Error ? e.message : String(e) };
+        return {
+            depth: "health+auth",
+            ok: false,
+            reason: e instanceof Error ? e.message : String(e),
+            code: authCode(e),
+        };
     }
 }

package/package.json

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