@tiny-fish/cli 0.11.1-next.132 → 0.12.1-next.135

package/README.md

@@ -64,6 +64,26 @@ npx -y @tiny-fish/cli@latest connect openclaw --launch
 OpenClaw must already be installed. The command installs the TinyFish skill for all local OpenClaw
 agents and guides you through Search, Fetch, and Agent one step at a time.
 
+## Upgrading
+
+```bash
+tinyfish upgrade
+```
+
+Brings both halves of an install current: the global `@tiny-fish/cli` package and the global
+`use-tinyfish` skill. Use this rather than remembering `npm i -g @tiny-fish/cli@latest` and
+`skills update -g` separately.
+
+The skill step refreshes only the TinyFish skill, and only for the agents you ran
+`tinyfish connect` against. Other global skills, and agents you never connected, are left alone.
+The refresh overwrites your copy of the skill, including any local edits to it. Restart your
+agent afterward to pick it up.
+
+If you never ran `tinyfish connect` on this machine, there is no record of which agent to
+refresh, so the command falls back to updating a tracked `use-tinyfish` skill if one exists. When
+it reports that the skill is missing or cannot be checked, run `tinyfish connect <client>` to
+reinstall it.
+
 ## Authentication
 
 Get your API key from [agent.tinyfish.ai](https://agent.tinyfish.ai).

package/dist/commands/connect.d.ts

@@ -1,7 +1,21 @@
 import { Command } from "commander";
+export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
 export type AgentClient = "claude-code" | "codex" | "hermes" | "openclaw";
+/** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
+export declare class ConnectInterruptedError extends Error {
+}
+export declare function installTinyFishCli(): void;
+/**
+ * Refresh the skill we installed, for the harnesses we installed it in.
+ *
+ * Reinstalling beats `skills update`: it reports failure through the exit code instead of
+ * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
+ * skill to agents the user never connected (`update` re-adds with no --agent, which targets
+ * every agent on the machine).
+ */
+export declare function updateWebSkill(): void;
 export declare function connectClaudeCode(options: {
     apiKey?: string;
     mcpUrl: string;

package/dist/commands/connect.js

@@ -20,11 +20,21 @@ const OPENCLAW_SKILL_UNAVAILABLE_MESSAGE = "This OpenClaw installation does not
     "retry.";
 const TINYFISH_CLI_NOT_FOUND_MESSAGE = "TinyFish CLI installed but is not available on PATH. Open a new terminal and retry.";
 const TINYFISH_CLI_PACKAGE = "@tiny-fish/cli@latest";
+export const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
 const SKILLS_CLI_PACKAGE = "skills@1.5.15";
 const TINYFISH_WEB_SKILL_SOURCE = "tinyfish-io/tinyfish-cookbook";
 const TINYFISH_WEB_SKILL = "use-tinyfish";
 const OPENCLAW_SKILL = "@tinyfish/tinyfish";
+// --force makes this an unconditional overwrite, so the same call installs and refreshes.
+const OPENCLAW_SKILL_INSTALL_ARGS = [
+    "skills",
+    "install",
+    OPENCLAW_SKILL,
+    "--global",
+    "--force",
+    "--acknowledge-clawhub-risk",
+];
 export const DEFAULT_ONBOARDING_PROMPT = "I just connected TinyFish. Call the guide_next_step tool now to begin. Then follow its " +
     "instructions one step at a time. Ask for my input and wait for my reply before each subsequent " +
     "TinyFish tool call.";
@@ -33,9 +43,13 @@ export const OPENCLAW_ONBOARDING_PROMPT = "I just installed the TinyFish skill.
     "which result I want to read, and wait before using TinyFish Fetch. Then ask what browser task " +
     "I want to complete and wait before using TinyFish Agent. Never skip ahead or choose for me.";
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
-class ConnectInterruptedError extends Error {
+export class ConnectInterruptedError extends Error {
 }
 function throwIfInterrupted(result) {
+    // spawn.sync kills a timed-out child with SIGTERM, so signal alone would misread a slow
+    // network as the user walking away. A timeout is a failure and must report as one.
+    if (result.error?.code === "ETIMEDOUT")
+        return;
     if (result.signal === "SIGINT" || result.signal === "SIGTERM") {
         throw new ConnectInterruptedError("Setup interrupted");
     }
@@ -314,7 +328,7 @@ function requireCommandSupport(client) {
 function commandNotFound(error) {
     return error?.code === "ENOENT";
 }
-function installTinyFishCli() {
+export function installTinyFishCli() {
     errLine("Installing the TinyFish CLI...");
     const result = spawn.sync("npm", ["install", "--global", TINYFISH_CLI_PACKAGE], {
         stdio: "inherit",
@@ -325,9 +339,9 @@ function installTinyFishCli() {
         throw new Error("Could not install the TinyFish CLI", { cause: result.error });
     }
 }
-function installWebSkill(client) {
-    errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
-    const result = spawn.sync("npx", [
+/** `skills add` is an unconditional overwrite, so it doubles as the refresh path. */
+function skillAddArgs(skillAgents) {
+    return [
         "-y",
         SKILLS_CLI_PACKAGE,
         "add",
@@ -336,13 +350,21 @@ function installWebSkill(client) {
         TINYFISH_WEB_SKILL,
         "--global",
         "--agent",
-        client.skillAgent,
+        ...skillAgents,
         "--yes",
-    ], {
-        env: {
-            ...process.env,
-            PATH: `${path.dirname(process.execPath)}${path.delimiter}${process.env.PATH ?? ""}`,
-        },
+    ];
+}
+// npx resolves from PATH, which a global npm install may not have exported yet.
+function skillSpawnEnv() {
+    return {
+        ...process.env,
+        PATH: `${path.dirname(process.execPath)}${path.delimiter}${process.env.PATH ?? ""}`,
+    };
+}
+function installWebSkill(client) {
+    errLine(`Installing the TinyFish web skill in ${client.displayName}...`);
+    const result = spawn.sync("npx", skillAddArgs([client.skillAgent]), {
+        env: skillSpawnEnv(),
         stdio: "inherit",
         timeout: SKILL_INSTALL_TIMEOUT_MS,
     });
@@ -353,6 +375,94 @@ function installWebSkill(client) {
         });
     }
 }
+// The `skills` update flow exits 0 even when it fails, so status alone proves nothing.
+// Safe to match on because SKILLS_CLI_PACKAGE is pinned.
+const SKILL_UPDATE_FAILURE_PATTERN = /Failed to (?:update|check|fetch)/;
+const SKILL_NOT_INSTALLED_PATTERN = /No installed skills found matching/;
+// A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
+// than failed. Left undetected that reads as "up to date" while nothing was refreshed.
+const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
+// `skills add` exits non-zero on a fatal error, but per-skill install failures only print.
+const SKILL_INSTALL_FAILURE_PATTERN = /Failed to install/;
+/**
+ * Refresh the skill we installed, for the harnesses we installed it in.
+ *
+ * Reinstalling beats `skills update`: it reports failure through the exit code instead of
+ * only in prose, it repairs a copy whose lock entry lost its hash, and it cannot spread the
+ * skill to agents the user never connected (`update` re-adds with no --agent, which targets
+ * every agent on the machine).
+ */
+export function updateWebSkill() {
+    // One entry per `tinyfish connect <client>`, persisted by PF-3169.
+    const connected = loadConfig().connect ?? {};
+    const skillAgents = [CLAUDE_CODE, CODEX, HERMES]
+        .filter((client) => connected[client.connectClient])
+        .map((client) => client.skillAgent);
+    const hasOpenClaw = Boolean(connected["openclaw"]);
+    // Installs predating PF-3169 recorded nothing; ask `skills` to refresh what it tracks.
+    if (skillAgents.length === 0 && !hasOpenClaw) {
+        refreshWebSkillByHash();
+        return;
+    }
+    if (skillAgents.length > 0)
+        reinstallWebSkill(skillAgents);
+    // OpenClaw keeps its skill under its own CLI, so it needs its own refresh.
+    if (hasOpenClaw)
+        reinstallOpenClawSkill();
+}
+function reinstallOpenClawSkill() {
+    errLine("Refreshing the TinyFish skill in OpenClaw...");
+    const result = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, { stdio: "inherit" });
+    // OpenClaw may have been removed since connect; a stale context entry must not fail an
+    // upgrade that otherwise succeeded.
+    if (commandNotFound(result.error)) {
+        errLine("OpenClaw is not on PATH, so its TinyFish skill was left unchanged.");
+        return;
+    }
+    if (result.error || result.status !== 0) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish skill in OpenClaw", { cause: result.error });
+    }
+}
+function reinstallWebSkill(skillAgents) {
+    errLine(`Refreshing the TinyFish web skill for ${skillAgents.join(", ")}...`);
+    const result = spawn.sync("npx", skillAddArgs(skillAgents), {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (output.trim())
+        errLine(output.trimEnd());
+    if (result.error || result.status !== 0 || SKILL_INSTALL_FAILURE_PATTERN.test(output)) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
+    }
+}
+/** Fallback when no harness is recorded: ask `skills` to refresh whatever it tracks. */
+function refreshWebSkillByHash() {
+    errLine("Refreshing the TinyFish web skill...");
+    const result = spawn.sync("npx", ["-y", SKILLS_CLI_PACKAGE, "update", TINYFISH_WEB_SKILL, "--global", "--yes"], {
+        encoding: "utf8",
+        env: skillSpawnEnv(),
+        timeout: SKILL_INSTALL_TIMEOUT_MS,
+    });
+    // Piped rather than inherited so the output can be inspected; echoed back for the user.
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    if (output.trim())
+        errLine(output.trimEnd());
+    if (result.error || result.status !== 0 || SKILL_UPDATE_FAILURE_PATTERN.test(output)) {
+        throwIfInterrupted(result);
+        throw new Error("Could not refresh the TinyFish web skill", { cause: result.error });
+    }
+    if (SKILL_UNCHECKABLE_PATTERN.test(output)) {
+        errLine("Run `tinyfish connect <client>` to reinstall the skill and restore update tracking.");
+        throw new Error("The TinyFish web skill cannot be checked for updates");
+    }
+    if (SKILL_NOT_INSTALLED_PATTERN.test(output)) {
+        errLine("No use-tinyfish skill installed. Run `tinyfish connect <client>` to add it.");
+    }
+}
 function ensureCliAuthenticated(source, apiKey) {
     const envKey = apiKey ?? process.env["TINYFISH_API_KEY"];
     if (envKey) {
@@ -487,6 +597,7 @@ async function connectNativeMcpClient(client, options) {
         // Persist once here (skill installed + authenticated) so both success paths, launch
         // or not, record the install; buildConnectHeaders reads it on subsequent requests.
         saveConnectContext(client.connectClient, telemetry.attemptId);
+        errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine(`TinyFish is connected. Open ${client.displayName} to start using it.`);
             settle(state, telemetry, "completed");
@@ -529,7 +640,9 @@ export async function connectOpenClaw(options) {
         }
         state.stage = "skill_install";
         errLine("Installing the TinyFish skill in OpenClaw...");
-        const skillInstallResult = spawn.sync("openclaw", ["skills", "install", OPENCLAW_SKILL, "--global", "--force", "--acknowledge-clawhub-risk"], { stdio: "inherit" });
+        const skillInstallResult = spawn.sync("openclaw", OPENCLAW_SKILL_INSTALL_ARGS, {
+            stdio: "inherit",
+        });
         if (skillInstallResult.error || skillInstallResult.status !== 0) {
             throwIfInterrupted(skillInstallResult);
             throw new Error("Could not install the TinyFish skill in OpenClaw", {
@@ -562,6 +675,7 @@ export async function connectOpenClaw(options) {
         }
         telemetry.track("checkpoint", { phase: "authenticated" });
         saveConnectContext("openclaw", telemetry.attemptId);
+        errLine(UPGRADE_HINT);
         if (!options.launch) {
             errLine("TinyFish is connected. Open OpenClaw to start using it.");
             settle(state, telemetry, "completed");

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function runUpgrade(): void;
+export declare function registerUpgrade(program: Command): void;

package/dist/commands/upgrade.js

@@ -0,0 +1,46 @@
+import { errLine } from "../lib/output.js";
+import { ConnectInterruptedError, installTinyFishCli, updateWebSkill } from "./connect.js";
+const INTERRUPTED_EXIT_CODE = 130;
+function attempt(label, run) {
+    try {
+        run();
+        errLine(`✓ ${label}: done`);
+        return undefined;
+    }
+    catch (error) {
+        // Ctrl+C is abandonment, not failure — neither step should be reported as broken.
+        if (error instanceof ConnectInterruptedError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        errLine(`✗ ${label}: ${message}`);
+        return message;
+    }
+}
+export function runUpgrade() {
+    errLine("Upgrading TinyFish...");
+    try {
+        // Both steps always run: neither artifact should stay stale because the other failed.
+        const failures = [
+            attempt("update the TinyFish CLI", installTinyFishCli),
+            attempt("refresh the TinyFish web skill", updateWebSkill),
+        ].filter((failure) => failure !== undefined);
+        if (failures.length > 0)
+            throw new Error(`tinyfish upgrade failed: ${failures.join("; ")}`);
+    }
+    catch (error) {
+        if (!(error instanceof ConnectInterruptedError))
+            throw error;
+        errLine("Upgrade interrupted — run `tinyfish upgrade` again to finish.");
+        process.exitCode = INTERRUPTED_EXIT_CODE;
+        return;
+    }
+    errLine("TinyFish is up to date. Restart your agent to pick up the refreshed skill.");
+}
+export function registerUpgrade(program) {
+    program
+        .command("upgrade")
+        .description("Update the TinyFish CLI and the use-tinyfish skill to the latest versions")
+        .action(() => {
+        runUpgrade();
+    });
+}

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 { registerUpgrade } from "./commands/upgrade.js";
 import { registerOnboard } from "./commands/onboard.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const program = new Command();
@@ -31,6 +32,7 @@ program
 registerAuth(program);
 registerOnboard(program);
 registerConnect(program);
+registerUpgrade(program);
 registerConfigureClaude(program);
 registerBrowser(program);
 registerProfile(program);

package/package.json

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