@thinger-io/cli-core 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.5.2] - 2026-10-31
+
+### Added
+
+- The CLI says when a newer release of it is on npm: once a day it asks the
+  registry for the latest version of the identity's `npmPackage` (cached in
+  the cache folder) and, after a command run in a terminal, prints one line
+  with the update command. The MCP server tells the agent instead, in its
+  instructions when the cache already knows and otherwise with the first
+  answer of the session, so the agent can suggest the update to the user.
+  Off in CI, with JSON output, and with `<PREFIX>_NO_UPDATE_CHECK=1` or
+  `NO_UPDATE_NOTIFIER=1`.
+
 ## [0.5.1] - 2026-10-31
 
 ### Fixed

package/README.md

@@ -48,6 +48,12 @@ It holds everything that is not specific to a product:
   reads.
 - **OpenAPI** (`openapi`) — the server's own API description, cached per
   server and version, with a bundled copy as fallback.
+- **Update check** (`update-check`) — once a day, the latest release of the
+  CLI's npm package (`npmPackage` in the identity). After a command run in
+  a terminal, one line says when a newer one is out; the MCP server tells
+  the agent, in its instructions or with the first answer of the session,
+  so it can suggest the update. Off in CI and with `<PREFIX>_NO_UPDATE_CHECK=1`
+  (or `NO_UPDATE_NOTIFIER=1`).
 
 ## Identity
 

package/lib/cli.js

@@ -3,7 +3,9 @@ import { Command } from 'commander';
 import { setActiveProfile } from './config.js';
 import { env, identity } from './identity.js';
 
-import { classifyError, detectJsonModeFromArgv } from './output.js';
+import { classifyError, detectJsonModeFromArgv, isJsonMode } from './output.js';
+import { warning } from './format.js';
+import { latestVersion, updateNotice } from './update-check.js';
 import { startMCPServer } from './mcp/server.js';
 import { registerAuthCommands } from './commands/auth.js';
 import { registerProfileCommands } from './commands/profile.js';
@@ -171,4 +173,19 @@ export async function runCli({ argv = process.argv, onNoCommand, ...opts }) {
         return;
     }
     await program.parseAsync(argv);
+    await notifyUpdate(opts.version, argv);
+}
+
+/**
+ * After a command run in a terminal, one line on stderr when a newer
+ * release is on npm. Not for JSON output, nor for `mcp`, whose server is
+ * still running (it tells the agent instead).
+ *
+ * @param {string} version
+ * @param {string[]} argv
+ */
+async function notifyUpdate(version, argv) {
+    if (!process.stderr.isTTY || isJsonMode() || argv.slice(2).includes('mcp')) return;
+    const notice = updateNotice(version, await latestVersion());
+    if (notice) console.error(warning(notice));
 }

package/lib/mcp/server.js

@@ -12,6 +12,7 @@ import { identity } from '../identity.js';
 import { buildTools, listResources, readResource } from './registry.js';
 import { withProfile } from './helpers.js';
 import { defineCliDocs } from '../docs.js';
+import { cachedLatest, latestVersion, updateNotice } from '../update-check.js';
 
 /** What a tool declares that the protocol lists. */
 const LISTED = ['name', 'title', 'description', 'inputSchema', 'annotations'];
@@ -59,6 +60,18 @@ export async function startMCPServer({
         readOnly,
     });
 
+    // A newer release of the CLI: the agent hears it in the instructions
+    // when the cache already knows, otherwise with the first answer of the
+    // session (the registry is asked from now, in the background).
+    const latest = latestVersion();
+    const forAgent = (notice) =>
+        `${notice}. Tell the user and suggest the update; the MCP server runs the new version once the client restarts it.`;
+    const known = updateNotice(version, cachedLatest().latest);
+    let told = !!known;
+    const serverInstructions = [instructions, known && forAgent(known)]
+        .filter(Boolean)
+        .join('\n\n');
+
     const server = new Server(
         {
             name: mcp.serverName,
@@ -66,10 +79,22 @@ export async function startMCPServer({
         },
         {
             capabilities: { tools: {}, resources: {} },
-            ...(instructions ? { instructions } : {}),
+            ...(serverInstructions ? { instructions: serverInstructions } : {}),
         },
     );
 
+    /** @param {any} result */
+    const withUpdateNote = async (result) => {
+        if (told) return result;
+        told = true;
+        const notice = updateNotice(version, await latest);
+        if (!notice || !Array.isArray(result?.content)) return result;
+        return {
+            ...result,
+            content: [...result.content, { type: 'text', text: forAgent(notice) }],
+        };
+    };
+
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: tools.map((t) =>
             Object.fromEntries(LISTED.filter((k) => t[k] !== undefined).map((k) => [k, t[k]])),
@@ -136,7 +161,9 @@ export async function startMCPServer({
         }
         const extra = server.getClientCapabilities()?.elicitation ? { elicit } : {};
         try {
-            return await withProfile(args.profile, () => tool.handler(args, extra));
+            return await withUpdateNote(
+                await withProfile(args.profile, () => tool.handler(args, extra)),
+            );
         } catch (error) {
             // Surface the same {message, code} pair the CLI emits in JSON
             // mode so MCP clients can pattern-match on `[code]` instead of

package/lib/update-check.js

@@ -0,0 +1,87 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { cacheDir } from './config.js';
+import { compareVersions } from './dashboard-sdk.js';
+import { env, identity } from './identity.js';
+
+/**
+ * Whether a newer release of the CLI is on npm, so the CLI and its MCP
+ * server can tell the user (and the agent) to update. The answer of the
+ * registry is kept for a day in the cache folder; everything here is
+ * advice: what cannot be read gives no notice.
+ */
+
+const REGISTRY = 'https://registry.npmjs.org';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const TIMEOUT_MS = 1500;
+const CACHE_FILE = 'latest-version.json';
+
+/**
+ * Off without an npm package to ask about, in CI and tests, and when the
+ * user turns it off (`<PREFIX>_NO_UPDATE_CHECK=1` or the common
+ * `NO_UPDATE_NOTIFIER`).
+ */
+export function updateCheckEnabled() {
+    if (!identity().npmPackage) return false;
+    const off = (v) => v !== undefined && v !== '' && !/^(0|false|no)$/i.test(v);
+    return !(
+        off(env('NO_UPDATE_CHECK')) ||
+        off(process.env.NO_UPDATE_NOTIFIER) ||
+        off(process.env.CI) ||
+        process.env.NODE_TEST_CONTEXT
+    );
+}
+
+function cachePath() {
+    return path.join(cacheDir(), CACHE_FILE);
+}
+
+/** The latest version the cache knows, and whether it is less than a day old. */
+export function cachedLatest() {
+    try {
+        const { latest, checkedAt } = JSON.parse(fs.readFileSync(cachePath(), 'utf8'));
+        if (typeof latest !== 'string') return {};
+        return { latest, fresh: Date.now() - Number(checkedAt) < DAY_MS };
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The latest version on npm: from the cache when it is fresh, otherwise
+ * asked to the registry (and cached). Undefined when it cannot be known.
+ *
+ * @returns {Promise<string | undefined>}
+ */
+export async function latestVersion() {
+    if (!updateCheckEnabled()) return undefined;
+    const cached = cachedLatest();
+    if (cached.fresh) return cached.latest;
+    try {
+        const res = await fetch(`${REGISTRY}/${identity().npmPackage}/latest`, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        if (!res.ok) return cached.latest;
+        const { version } = /** @type {{ version?: unknown }} */ (await res.json());
+        if (typeof version !== 'string') return cached.latest;
+        fs.writeFileSync(cachePath(), JSON.stringify({ latest: version, checkedAt: Date.now() }));
+        return version;
+    } catch {
+        return cached.latest;
+    }
+}
+
+/**
+ * The line that tells the user a newer release is out, or undefined when
+ * `version` is the latest (or newer: a development build).
+ *
+ * @param {string} version  The running CLI's.
+ * @param {string | undefined} latest
+ */
+export function updateNotice(version, latest) {
+    if (!latest || !version || version === 'unknown') return undefined;
+    if (compareVersions(latest, version) <= 0) return undefined;
+    const { name, npmPackage } = identity();
+    return `${name} ${latest} is available (this is ${version}). Update with: npm i -g ${npmPackage}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinger-io/cli-core",
-    "version": "0.5.1",
+    "version": "0.5.2",
     "description": "Shared core of the Thinger.io CLIs and their MCP servers: API client, auth, profiles, generic commands and MCP tools",
     "type": "module",
     "exports": {