@thinger-io/cli-core 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- `host` action `update_settings` says what the server does: it merges the
+  body into the host's custom settings (keys left out stay, `null` removes
+  one). Its confirmation plan no longer claims it removes the keys left
+  out of the body.
+- The browser login on a server that does not know the CLI's OAuth client
+  (older than Thinger 7.5.0, or the client was removed) says so and offers
+  username and password or a token instead of failing.
+
 ## [0.5.0] - 2026-10-21
 
 One grammar for every command, noun first:

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/auth.js

@@ -110,7 +110,22 @@ export async function authenticate(opts = {}) {
         if (method === 'userpass') {
             await authenticateWithUserPass(opts);
         } else if (method === 'oauth') {
-            await authenticateWithOAuth(opts, existing);
+            await authenticateWithOAuth(opts, existing).catch(async (error) => {
+                // A server older than the CLI's built-in OAuth client, or
+                // one whose admin removed it: sign in another way.
+                if (error.code !== 'oauth_client_unknown' || !process.stdin.isTTY) throw error;
+                console.log(warning(error.message));
+                const fallback = await ask(select, {
+                    message: 'Sign in another way:',
+                    choices: [
+                        { name: 'Username and password', value: 'userpass' },
+                        { name: 'Token', value: 'token' },
+                    ],
+                });
+                return fallback === 'userpass'
+                    ? authenticateWithUserPass(opts)
+                    : authenticateWithToken(opts);
+            });
         } else {
             await authenticateWithToken(opts);
         }
@@ -391,6 +406,15 @@ async function authenticateWithOAuth(opts, existing) {
         spinner.succeed('OAuth User Code received');
     } catch (error) {
         spinner.fail('OAuth device-code request failed');
+        const status = error.response?.status;
+        if (status === 401 || status === 404) {
+            throw Object.assign(
+                new Error(
+                    `The server does not know the OAuth client ${client_id} (Thinger 7.5.0 and later have it built in). Sign in with a token or username and password instead.`,
+                ),
+                { code: 'oauth_client_unknown' },
+            );
+        }
         throw error;
     }
 

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/catalog.js

@@ -665,7 +665,7 @@ export const CATALOG = {
                 method: 'put',
                 path: 'settings',
                 description:
-                    'Replace the host settings with `body`; read them first. Confirm with the user first.',
+                    'Patch the host settings with `body` (JSON merge: keys left out stay, null removes one); read them first. Confirm with the user first.',
             },
         },
     },

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/mcp/tools-resource.js

@@ -1493,11 +1493,13 @@ export function resourceTools({
                 .then((r) => r.data)
                 .catch(() => undefined);
             if (isRecord(now) && isRecord(body)) {
+                // The server merges the body (JSON merge-patch): keys left
+                // out stay, a null removes one.
+                const removed = Object.keys(body).filter((k) => body[k] === null && k in now);
                 const changed = Object.keys(body).filter(
-                    (k) => JSON.stringify(now[k]) !== JSON.stringify(body[k]),
+                    (k) => body[k] !== null && JSON.stringify(now[k]) !== JSON.stringify(body[k]),
                 );
-                const dropped = Object.keys(now).filter((k) => !(k in body));
-                return `It would replace the settings of ${target}: changes ${some(changed)}; removes ${some(dropped)} (left out of the body).`;
+                return `It would patch the settings of ${target}: changes ${some(changed)}; removes ${some(removed)}; the rest stays.`;
             }
         }
         if (action === 'test_notification') {

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.0",
+    "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": {