@tiny-fish/cli 0.34.1-next.285 → 0.34.1-next.287

package/dist/commands/doctor.js

@@ -8,6 +8,8 @@ import { err, errLine, out, outLine } from '../lib/output.js';
 import { detectRegistrations } from '../lib/registration-detect.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 { connectClaudeCode, connectCodex, connectCursor, connectGrok, connectHermes, connectOpenClaw, connectOpencode, } from './connect.js';
 // A green auth mode with a red auth call proves nothing, so the call's verdict gates the claim.
@@ -197,6 +199,77 @@ function verifyHarnessKey(status, cliAuth, mcpUrl) {
     // The CLI never holds a harness's key, so only its own credential can be verified.
     return runsOnCliCredential(status) ? cliAuth : undefined;
 }
+// `ok` is backends && key; provider_available re-reads the key through the provider.
+function hermesPluginStatusVerdict(status) {
+    if (status.ok) {
+        return status.provider_available === false
+            ? { status: 'warn', detail: 'plugin configured, but its provider cannot see the key' }
+            : {
+                status: 'pass',
+                detail: `plugin ${status.plugin_version ?? 'installed'}; backends and key configured`,
+            };
+    }
+    if (!status.web_backend_configured) {
+        return {
+            status: 'warn',
+            detail: 'plugin installed but the web backends do not point at tinyfish',
+        };
+    }
+    return {
+        status: 'fail',
+        detail: 'web backends point at tinyfish but no key resolves from ' +
+            'TINYFISH_API_KEY or MCP_TINYFISH_API_KEY',
+    };
+}
+/** An unreadable config cannot prove the backends are ours, so doctor never fails on it. */
+function backendsOurs(home) {
+    try {
+        return hermesWebBackendsOurs(home);
+    }
+    catch {
+        return false;
+    }
+}
+function hermesPluginVerdict(home) {
+    const probe = readHermesPluginStatus(home);
+    if (probe.state === 'not_installed') {
+        // Backends naming an absent provider are broken; never-installed keeps exit 0.
+        return backendsOurs(home)
+            ? {
+                status: 'fail',
+                detail: 'web backends point at tinyfish but the plugin is not installed or not enabled',
+            }
+            : { status: 'warn', detail: 'the TinyFish web plugin is not installed or not enabled' };
+    }
+    if (probe.state === 'unreachable') {
+        return { status: 'warn', detail: '`hermes tinyfish status` did not respond in time' };
+    }
+    if (probe.state === 'unparseable') {
+        return {
+            status: 'warn',
+            detail: '`hermes tinyfish status --json` returned unparseable output',
+        };
+    }
+    return hermesPluginStatusVerdict(probe.status);
+}
+function checkHermesPlugin(status) {
+    const check = {
+        id: 'hermes-plugin',
+        title: 'Hermes web plugin',
+        harness: 'hermes',
+        scope: 'harness',
+    };
+    if (!status.detected)
+        return { ...check, status: 'skip', detail: 'harness not installed' };
+    if (status.registered !== Registered.Yes) {
+        return { ...check, status: 'skip', detail: 'TinyFish is not registered in Hermes' };
+    }
+    const home = resolveHermesHome();
+    if (!home) {
+        return { ...check, status: 'warn', detail: "could not determine Hermes' home directory" };
+    }
+    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) {
@@ -219,7 +292,7 @@ function repairsFor(checks, statuses) {
         // 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.status === 'fail');
+            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({
@@ -235,6 +308,17 @@ function repairsFor(checks, statuses) {
             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) {
@@ -246,10 +330,12 @@ export async function runDoctor(options) {
         cliAuth,
         Promise.all(statuses.map((status) => verifyHarnessKey(status, cliAuth, options.mcpUrl))),
     ]);
+    const hermesStatus = statuses.find((status) => status.harness === 'hermes');
     const checks = [
         checkCliVersion(),
         connectivity,
         ...statuses.map((status, i) => checkRegistration(status, options.mcpUrl, keyAuths[i], !credential.key)),
+        ...(hermesStatus ? [checkHermesPlugin(hermesStatus)] : []),
         credential.check,
         checkAuthCall(cliAuthResult),
     ];

package/dist/lib/connect-all-uninstall.js

@@ -3,6 +3,7 @@ import { NATIVE_BY_HARNESS, openclawSkillUninstall } from './connect-clients.js'
 import { ConnectInterruptedError, spawnRemoval } from './connect-runtime.js';
 import { removeCursorMcpServer, planCursorWrite } from './cursor-config.js';
 import { HERMES_KEY_VAR, hermesEnvPath, removeHermesKey, resolveHermesHome } from './hermes-env.js';
+import { clearHermesWebBackends, HERMES_PLUGIN_SHA } from './hermes-plugin.js';
 import { HARNESS_DISPLAY_NAMES as DISPLAY_NAMES } from './harness-detect.js';
 import { errLine } from './output.js';
 // OpenCode ships no `mcp remove`, so the only removal is editing the config it wrote.
@@ -12,7 +13,9 @@ export function planText(harness, mcpUrl, apiKey) {
         return planCursorWrite(mcpUrl, apiKey);
     // Only the keyed path seeds the .env; a keyless Hermes install writes nothing.
     if (harness === 'hermes' && apiKey) {
-        return `would run \`tinyfish connect hermes\` (harness-owned MCP write; the CLI writes ${HERMES_KEY_VAR} to Hermes' .env)`;
+        return (`would run \`tinyfish connect hermes\` (harness-owned MCP write; the CLI writes ` +
+            `${HERMES_KEY_VAR} to Hermes' .env, installs the tinyfish plugin at ` +
+            `${HERMES_PLUGIN_SHA.slice(0, 12)}, and points its web backends at tinyfish)`);
     }
     return `would run \`tinyfish connect ${harness}\` (harness-owned MCP write; no local file touched by the CLI)`;
 }
@@ -24,7 +27,9 @@ export function uninstallPlanText(harness) {
         return `would print \`${uninstallPointer(harness)}\` (no removal command exists)`;
     }
     // Hermes alone leaves a seeded key behind; `mcp remove` never clears it.
-    const envNote = harness === 'hermes' ? ` and clear ${HERMES_KEY_VAR} from Hermes' .env` : '';
+    const envNote = harness === 'hermes'
+        ? ` and clear ${HERMES_KEY_VAR} from Hermes' .env plus its tinyfish web backends`
+        : '';
     return `would run \`${uninstallPointer(harness)}\`${envNote}`;
 }
 /** Undefined: no harness-CLI removal exists (opencode). */
@@ -36,7 +41,8 @@ function uninstallRuns(harness) {
     const native = NATIVE_BY_HARNESS.get(harness);
     if (!native || native.removals.length === 0)
         return undefined;
-    return { command: native.command, runs: native.removals.map((r) => r.args) };
+    const extra = native.uninstallExtra ? [native.uninstallExtra.args] : [];
+    return { command: native.command, runs: [...native.removals.map((r) => r.args), ...extra] };
 }
 /** Derived from the same args the spawn runs, so the advice cannot drift. */
 function uninstallPointer(harness) {
@@ -48,9 +54,29 @@ function uninstallPointer(harness) {
     const joiner = process.platform === 'win32' ? ' && ' : ' ; ';
     return removal.runs.map((args) => `${removal.command} ${args.join(' ')}`).join(joiner);
 }
-/** `mcp remove` leaves this behind; a stale value gets silently reused. */
-function clearHermesEnvKey() {
+/** `mcp remove` clears neither the key nor the backends we wrote. */
+function clearHermesLocalState() {
     const home = resolveHermesHome();
+    const advisories = [clearHermesEnvKey(home), clearHermesBackends(home)].filter((advisory) => advisory !== undefined);
+    return advisories.length > 0 ? advisories.join(' ') : undefined;
+}
+/** Backends left naming an absent provider would break Hermes' web tools. */
+function clearHermesBackends(home) {
+    // The key clearer already reported the unresolved home.
+    if (!home)
+        return undefined;
+    try {
+        clearHermesWebBackends(home);
+        return undefined;
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        return (`could not unset Hermes' tinyfish web backends (${detail}). Run \`hermes config unset ` +
+            'web.search_backend`, `web.extract_backend` and `web.backend` by hand.');
+    }
+}
+/** `mcp remove` leaves this behind; a stale value gets silently reused. */
+function clearHermesEnvKey(home) {
     const retry = 're-run `tinyfish connect --all --uninstall`';
     if (!home) {
         return (`could not locate Hermes' home, so ${HERMES_KEY_VAR} may still be set in its .env. ` +
@@ -177,7 +203,7 @@ export function uninstallHarness(harness, configPath, verbose, binaryOnPath) {
     // Clearing a key the entry still references would break a working install.
     const removed = !result.removalFailed &&
         (result.outcome === 'uninstalled' || result.outcome === 'uninstall_noop');
-    const advisory = removed ? clearHermesEnvKey() : hermesKeyKeptAdvisory();
+    const advisory = removed ? clearHermesLocalState() : hermesKeyKeptAdvisory();
     if (!advisory)
         return result;
     // Appended, never replacing: an advisory must not hide the removal's message.

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

@@ -74,6 +74,11 @@ interface BaseMcpClient extends SupportedCommand {
         apiKey?: string;
         verbose: boolean;
     }) => void;
+    /** Extra --uninstall row beyond `removals`; never runs pre-add. */
+    uninstallExtra?: {
+        args: string[];
+        label: string;
+    };
 }
 /** Keyless installs use this argv; the harness signs itself in. */
 export interface OauthCapableMcpClient extends BaseMcpClient {

package/dist/lib/connect-clients.js

@@ -7,7 +7,7 @@ import { ConnectStepError, spawnStepError, } from './connect-runtime.js';
 import { TINYFISH_API_KEY_VAR } from './constants.js';
 import { HERMES_KEY_VAR, captureHermesKeyRestore, hermesEnvPath, resolveHermesHome, writeHermesKey, } from './hermes-env.js';
 import { hermesConfigPath, readHermesEntry } from './hermes-config.js';
-import { installHermesPlugin, setHermesWebBackends } from './hermes-plugin.js';
+import { HERMES_PLUGIN_NAME, installHermesPlugin, setHermesWebBackends } from './hermes-plugin.js';
 const HERMES_SEED_TIMEOUT_MS = 120_000;
 // An old install is only one reason a flag can go unseen, so no message asserts the cause.
 const SUPPORT_CHECK_DEBUG_HINT = ' Set TINYFISH_DEBUG=1 and retry to print the help output TinyFish read.';
@@ -332,6 +332,10 @@ export const HERMES = {
     },
     removals: [{ args: ['mcp', 'remove', 'tinyfish'], label: 'TinyFish registration from Hermes' }],
     extraPostInstall: installHermesWebPlugin,
+    uninstallExtra: {
+        args: ['plugins', 'uninstall', HERMES_PLUGIN_NAME],
+        label: 'TinyFish web plugin from Hermes',
+    },
     launchWalkthrough: launchHermesWalkthrough,
     postConnectNote: 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.',
 };

package/dist/lib/hermes-plugin.d.ts

@@ -1,6 +1,34 @@
+import { z } from 'zod';
 import { type InstallOptions } from './cli-install.js';
 export declare const HERMES_PLUGIN_SHA = "496cd63fefd982bbaa8a85ce78ef2270d700984f";
+export declare const HERMES_PLUGIN_NAME = "tinyfish";
 export declare const HERMES_PLUGIN_MANUAL_INSTALL = "hermes plugins install tinyfish-io/tinyfish-web-agent-integrations/hermes --ref 496cd63fefd982bbaa8a85ce78ef2270d700984f --enable";
 export declare function installHermesPlugin(home: string, apiKey: string, { verbose }: Pick<InstallOptions, 'verbose'>): void;
 /** After install only: backends must never name an absent provider. */
 export declare function setHermesWebBackends(home: string): void;
+/** Ours-only unsets: a user-chosen backend value survives the uninstall. */
+export declare function clearHermesWebBackends(home: string): void;
+declare const hermesPluginStatusSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    api_key_configured: z.ZodBoolean;
+    api_key_env_var: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    plugin_version: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    provider_available: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    web_backend_configured: z.ZodBoolean;
+}, z.core.$loose>;
+export type HermesPluginStatus = z.infer<typeof hermesPluginStatusSchema>;
+export type HermesPluginProbe = {
+    state: 'not_installed';
+} | {
+    state: 'unreachable';
+} | {
+    state: 'unparseable';
+} | {
+    state: 'ok';
+    status: HermesPluginStatus;
+};
+/** `status --json` always exits 0; a non-zero exit means the subcommand is absent. */
+export declare function readHermesPluginStatus(home: string): HermesPluginProbe;
+/** Fallback verdict input when the plugin CLI cannot answer. */
+export declare function hermesWebBackendsOurs(home: string): boolean;
+export {};

package/dist/lib/hermes-plugin.js

@@ -3,12 +3,15 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import spawn from 'cross-spawn';
+import { z } from 'zod';
 import { capturedOutput, replay, SKILL_INSTALL_TIMEOUT_MS, STEP_MAX_BUFFER, } from './cli-install.js';
-import { commandNotFound, ConnectStepError, spawnStepError } from './connect-runtime.js';
+import { commandNotFound, ConnectStepError, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
 import { errLine } from './output.js';
 // Bump per CLI release.
 export const HERMES_PLUGIN_SHA = '496cd63fefd982bbaa8a85ce78ef2270d700984f';
+// Manifest `name:`, not the repo subdir; `plugins uninstall` keys on it.
+export const HERMES_PLUGIN_NAME = 'tinyfish';
 const PLUGIN_SOURCE = 'tinyfish-io/tinyfish-web-agent-integrations/hermes';
 const PLUGIN_REPO_URL = 'https://github.com/tinyfish-io/tinyfish-web-agent-integrations.git';
 export const HERMES_PLUGIN_MANUAL_INSTALL = `hermes plugins install ${PLUGIN_SOURCE} --ref ${HERMES_PLUGIN_SHA} --enable`;
@@ -92,8 +95,63 @@ function configWrite(home, args) {
     throw error;
 }
 const HERMES_BACKEND_KEYS = ['web.search_backend', 'web.extract_backend'];
+// Dispatch falls back to web.backend, and the plugin's own setup can set it.
+const HERMES_OWNED_BACKEND_KEYS = [...HERMES_BACKEND_KEYS, 'web.backend'];
 /** After install only: backends must never name an absent provider. */
 export function setHermesWebBackends(home) {
     for (const key of HERMES_BACKEND_KEYS)
         configWrite(home, ['set', key, 'tinyfish']);
 }
+/** Unset prints empty and exits 0, so a failed read must not read as unset. */
+function configGet(home, key) {
+    const result = hermesConfig(['get', key], home);
+    throwIfInterrupted(result);
+    if (result.error || result.status !== 0) {
+        throw spawnStepError(`Could not read \`hermes config get ${key}\``, result);
+    }
+    return String(result.stdout ?? '').trim() || undefined;
+}
+/** Ours-only unsets: a user-chosen backend value survives the uninstall. */
+export function clearHermesWebBackends(home) {
+    for (const key of HERMES_OWNED_BACKEND_KEYS) {
+        if (configGet(home, key) === 'tinyfish')
+            configWrite(home, ['unset', key]);
+    }
+}
+const hermesPluginStatusSchema = z.looseObject({
+    ok: z.boolean(),
+    api_key_configured: z.boolean(),
+    api_key_env_var: z.string().nullish(),
+    plugin_version: z.string().nullish(),
+    provider_available: z.boolean().nullish(),
+    web_backend_configured: z.boolean(),
+});
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `status --json` always exits 0; a non-zero exit means the subcommand is absent. */
+export function readHermesPluginStatus(home) {
+    const result = spawn.sync('hermes', ['tinyfish', 'status', '--json'], {
+        encoding: 'utf8',
+        maxBuffer: STEP_MAX_BUFFER,
+        timeout: HARNESS_PROBE_TIMEOUT_MS,
+        env: { ...process.env, HERMES_HOME: home, FORCE_COLOR: '0', NO_COLOR: '1' },
+    });
+    // A timeout also lands in result.error, where "not installed" would be a lie.
+    if (result.error) {
+        return commandNotFound(result.error) ? { state: 'not_installed' } : { state: 'unreachable' };
+    }
+    if (result.status !== 0)
+        return { state: 'not_installed' };
+    const parsed = hermesPluginStatusSchema.safeParse(parseJson(String(result.stdout ?? '')));
+    return parsed.success ? { state: 'ok', status: parsed.data } : { state: 'unparseable' };
+}
+/** Fallback verdict input when the plugin CLI cannot answer. */
+export function hermesWebBackendsOurs(home) {
+    return HERMES_OWNED_BACKEND_KEYS.some((key) => configGet(home, key) === 'tinyfish');
+}

package/package.json

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