@tiny-fish/cli 0.36.1-next.293 → 0.37.0

package/dist/commands/doctor.js

@@ -6,7 +6,7 @@ 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 { sendDoctorCompleted } from '../lib/setup-telemetry.js';
+import { doctorErrorClass, 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';
@@ -423,11 +423,15 @@ export async function applyRepairs(repairs, options) {
 }
 /** 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,
@@ -441,7 +445,7 @@ function telemetryPayload(report, offered, outcomes, options, durationMs) {
         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: !options.fix ? 'none' : options.yes ? 'fix_yes' : 'fix',
+        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.
@@ -454,6 +458,25 @@ function telemetryPayload(report, offered, outcomes, options, durationMs) {
         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')
@@ -500,6 +523,8 @@ export function registerDoctor(program) {
             }
             err({ error: 'doctor could not complete; re-run with --debug for the raw error' });
             process.exitCode = DOCTOR_COULD_NOT_RUN;
+            // After the exit code is set: telemetry never decides how doctor exits.
+            await sendDoctorCompleted(doctorOptions.mcpUrl, couldNotRunPayload(e, doctorOptions, Math.round(performance.now() - startedAt)), telemetryKey());
             return;
         }
         if (options.pretty)
@@ -508,7 +533,6 @@ export function registerDoctor(program) {
             out(report);
         process.exitCode = exitCodeFor(report.checks);
         // After the exit code is set: telemetry never decides how doctor exits.
-        const resolved = apiKeyStatus();
-        await sendDoctorCompleted(doctorOptions.mcpUrl, telemetryPayload(report, offered, outcomes, doctorOptions, Math.round(performance.now() - startedAt)), 'key' in resolved ? resolved.key : undefined);
+        await sendDoctorCompleted(doctorOptions.mcpUrl, telemetryPayload(report, offered, outcomes, doctorOptions, Math.round(performance.now() - startedAt)), telemetryKey());
     });
 }

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

@@ -80,7 +80,12 @@ export type UpgradeScope = 'both' | 'cli' | 'skill';
 export declare function sendUpgradeCompleted(fromVersion: string, toVersion: string | null, outcome: UpgradeOutcome, scope: UpgradeScope, apiKey?: string): Promise<void>;
 export declare function sendSetupCompleted(mcpUrl: string, harnesses: HarnessResult[], apiKey?: string, mode?: SetupMode, attemptId?: string): Promise<void>;
 export declare const DOCTOR_HARNESS_SCOPES: readonly ["all", ...("openclaw" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "claude-code")[]];
+export declare const DOCTOR_ERROR_CLASSES: readonly ["command_not_found", "timeout", "spawn_error", "nonzero_exit", "unexpected_error"];
+export type DoctorErrorClass = (typeof DOCTOR_ERROR_CLASSES)[number];
+/** Derived, not read: the catch is generic, so only the code is trustworthy. */
+export declare function doctorErrorClass(error: unknown): DoctorErrorClass;
 export declare const doctorCompletedPayloadSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"completed">;
     schema_version: z.ZodInt;
     cli_version: z.ZodString;
     ok_harnesses: z.ZodBoolean;
@@ -139,6 +144,125 @@ export declare const doctorCompletedPayloadSchema: z.ZodObject<{
     }, z.core.$strip>>;
     duration_ms: z.ZodInt;
 }, z.core.$strip>;
+export declare const doctorCouldNotRunPayloadSchema: z.ZodObject<{
+    outcome: z.ZodLiteral<"could_not_run">;
+    error_class: z.ZodEnum<{
+        timeout: "timeout";
+        command_not_found: "command_not_found";
+        spawn_error: "spawn_error";
+        nonzero_exit: "nonzero_exit";
+        unexpected_error: "unexpected_error";
+    }>;
+    schema_version: z.ZodInt;
+    cli_version: z.ZodString;
+    fix_mode: z.ZodEnum<{
+        none: "none";
+        fix: "fix";
+        fix_yes: "fix_yes";
+    }>;
+    harness_scope: z.ZodEnum<{
+        openclaw: "openclaw";
+        grok: "grok";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        opencode: "opencode";
+        "claude-code": "claude-code";
+        all: "all";
+    }>;
+    is_human_initiated: z.ZodBoolean;
+    duration_ms: z.ZodInt;
+}, z.core.$strip>;
+declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"completed">;
+    schema_version: z.ZodInt;
+    cli_version: z.ZodString;
+    ok_harnesses: z.ZodBoolean;
+    ok_cli: z.ZodBoolean;
+    checks_pass: z.ZodInt;
+    checks_fail: z.ZodInt;
+    checks_warn: z.ZodInt;
+    checks_skip: z.ZodInt;
+    repairs_offered: z.ZodInt;
+    repair_actions: z.ZodArray<z.ZodEnum<{
+        connect: "connect";
+        "auth-login": "auth-login";
+    }>>;
+    repairs_attempted: z.ZodInt;
+    repairs_succeeded: z.ZodInt;
+    fix_mode: z.ZodEnum<{
+        none: "none";
+        fix: "fix";
+        fix_yes: "fix_yes";
+    }>;
+    harness_scope: z.ZodEnum<{
+        openclaw: "openclaw";
+        grok: "grok";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        opencode: "opencode";
+        "claude-code": "claude-code";
+        all: "all";
+    }>;
+    is_human_initiated: z.ZodBoolean;
+    failed_check_ids: z.ZodArray<z.ZodString>;
+    failed_harnesses: z.ZodArray<z.ZodEnum<{
+        openclaw: "openclaw";
+        grok: "grok";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        opencode: "opencode";
+        "claude-code": "claude-code";
+    }>>;
+    harnesses: z.ZodArray<z.ZodObject<{
+        harness: z.ZodEnum<{
+            openclaw: "openclaw";
+            grok: "grok";
+            cursor: "cursor";
+            codex: "codex";
+            hermes: "hermes";
+            opencode: "opencode";
+            "claude-code": "claude-code";
+        }>;
+        detected: z.ZodBoolean;
+        registered: z.ZodEnum<typeof Registered>;
+        auth_mode: z.ZodEnum<typeof AuthMode>;
+        proves_harness_reach: z.ZodBoolean;
+    }, z.core.$strip>>;
+    duration_ms: z.ZodInt;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"could_not_run">;
+    error_class: z.ZodEnum<{
+        timeout: "timeout";
+        command_not_found: "command_not_found";
+        spawn_error: "spawn_error";
+        nonzero_exit: "nonzero_exit";
+        unexpected_error: "unexpected_error";
+    }>;
+    schema_version: z.ZodInt;
+    cli_version: z.ZodString;
+    fix_mode: z.ZodEnum<{
+        none: "none";
+        fix: "fix";
+        fix_yes: "fix_yes";
+    }>;
+    harness_scope: z.ZodEnum<{
+        openclaw: "openclaw";
+        grok: "grok";
+        cursor: "cursor";
+        codex: "codex";
+        hermes: "hermes";
+        opencode: "opencode";
+        "claude-code": "claude-code";
+        all: "all";
+    }>;
+    is_human_initiated: z.ZodBoolean;
+    duration_ms: z.ZodInt;
+}, z.core.$strip>], "outcome">;
 export type DoctorCompletedPayload = z.infer<typeof doctorCompletedPayloadSchema>;
-export declare function sendDoctorCompleted(mcpUrl: string, payload: DoctorCompletedPayload, apiKey?: string): Promise<void>;
+export type DoctorCouldNotRunPayload = z.infer<typeof doctorCouldNotRunPayloadSchema>;
+export type DoctorPayload = z.infer<typeof doctorPayloadSchema>;
+export declare function sendDoctorCompleted(mcpUrl: string, payload: DoctorPayload, apiKey?: string): Promise<void>;
 export {};

package/dist/lib/setup-telemetry.js

@@ -191,7 +191,25 @@ export const DOCTOR_HARNESS_SCOPES = ['all', ...ALL_HARNESSES];
 // user-authored or credential-shaped can ride a doctor run to PostHog. `detail` never leaves.
 // Caps mirror the route's schema: a payload the server would 400 is dropped here instead,
 // because postConnectEvent never retries a 4xx and the event would vanish silently.
+// Same spellings as cli_connect_stage.failure_reason; the type pins them.
+export const DOCTOR_ERROR_CLASSES = [
+    'command_not_found',
+    'timeout',
+    'spawn_error',
+    'nonzero_exit',
+    'unexpected_error',
+];
+/** Derived, not read: the catch is generic, so only the code is trustworthy. */
+export function doctorErrorClass(error) {
+    const code = error?.code;
+    if (code === 'ENOENT')
+        return 'command_not_found';
+    if (code === 'ETIMEDOUT')
+        return 'timeout';
+    return code ? 'spawn_error' : 'unexpected_error';
+}
 export const doctorCompletedPayloadSchema = z.object({
+    outcome: z.literal('completed'),
     schema_version: z.int().positive(),
     cli_version: z.string().max(32),
     ok_harnesses: z.boolean(),
@@ -223,6 +241,21 @@ export const doctorCompletedPayloadSchema = z.object({
         .max(16),
     duration_ms: z.int().nonnegative().max(3_600_000),
 });
+// Detection threw, so there is no report to aggregate: enumerated outcome and timing only.
+export const doctorCouldNotRunPayloadSchema = z.object({
+    outcome: z.literal('could_not_run'),
+    error_class: z.enum(DOCTOR_ERROR_CLASSES),
+    schema_version: z.int().positive(),
+    cli_version: z.string().max(32),
+    fix_mode: z.enum(['none', 'fix', 'fix_yes']),
+    harness_scope: z.enum(DOCTOR_HARNESS_SCOPES),
+    is_human_initiated: z.boolean(),
+    duration_ms: z.int().nonnegative().max(3_600_000),
+});
+const doctorPayloadSchema = z.discriminatedUnion('outcome', [
+    doctorCompletedPayloadSchema,
+    doctorCouldNotRunPayloadSchema,
+]);
 export async function sendDoctorCompleted(mcpUrl, payload, apiKey) {
     if (telemetryDisabled())
         return;
@@ -230,7 +263,7 @@ export async function sendDoctorCompleted(mcpUrl, payload, apiKey) {
     let body;
     try {
         // Parse inside try — a schema violation must not fail a diagnosis that already ran.
-        const parsed = doctorCompletedPayloadSchema.parse(payload);
+        const parsed = doctorPayloadSchema.parse(payload);
         endpoint = new URL('/api/cli/connect-event', mcpUrl).toString();
         // Stamped after the parse: process-derived and bounded, cannot trip route caps.
         body = JSON.stringify({

package/package.json

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