@displaydev/cli 0.19.0 → 0.21.0

package/dist/api-client.js

@@ -1,7 +1,4 @@
-/**
- * HTTP client for the display.dev API.
- * Used by the stdio MCP server to proxy tool calls to the REST API.
- */ function _assert_this_initialized(self) {
+function _assert_this_initialized(self) {
     if (self === void 0) {
         throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
     }
@@ -284,6 +281,10 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
+/**
+ * HTTP client for the display.dev API.
+ * Used by the stdio MCP server to proxy tool calls to the REST API.
+ */ import { readLatestVersionFromResponse } from './update-notice.js';
 export var ApiError = /*#__PURE__*/ function(Error1) {
     "use strict";
     _inherits(ApiError, Error1);
@@ -311,15 +312,50 @@ export var ApiClient = /*#__PURE__*/ function() {
     "use strict";
     function ApiClient(config) {
         _class_call_check(this, ApiClient);
-        var _config_clientType;
+        var _config_clientType, _config_version, _config_clientSource;
         _define_property(this, "baseUrl", void 0);
         _define_property(this, "apiKey", void 0);
         _define_property(this, "clientType", void 0);
+        _define_property(this, "version", void 0);
+        _define_property(this, "clientSource", void 0);
         this.baseUrl = config.baseUrl.replace(/\/$/, '');
         this.apiKey = config.apiKey;
         this.clientType = (_config_clientType = config.clientType) !== null && _config_clientType !== void 0 ? _config_clientType : 'mcp-stdio';
+        this.version = (_config_version = config.version) !== null && _config_version !== void 0 ? _config_version : '';
+        this.clientSource = (_config_clientSource = config.clientSource) !== null && _config_clientSource !== void 0 ? _config_clientSource : '';
     }
     _create_class(ApiClient, [
+        {
+            key: "clientHeaders",
+            value: /**
+   * Build the request-side header set. Always carries `X-Client-Type`;
+   * adds `X-Client-Version` when the client was constructed with one;
+   * adds `X-Client-Source` when a distribution-channel attribution was
+   * configured.
+   */ function clientHeaders(extra) {
+                var headers = _object_spread({
+                    'X-Client-Type': this.clientType
+                }, this.version ? {
+                    'X-Client-Version': this.version
+                } : {}, this.clientSource ? {
+                    'X-Client-Source': this.clientSource
+                } : {}, extra);
+                return headers;
+            }
+        },
+        {
+            key: "observeResponse",
+            value: /**
+   * Read the registry-derived `X-Client-Latest-Version` response header
+   * and feed it to the update-notice comparator. Called from every
+   * fetch site. No-op when no version is configured (older constructions
+   * that didn't pass `version` should not trigger an update prompt).
+   */ function observeResponse(res) {
+                if (this.version) {
+                    readLatestVersionFromResponse(res, this.version);
+                }
+            }
+        },
         {
             key: "publish",
             value: function publish(params) {
@@ -355,9 +391,7 @@ export var ApiClient = /*#__PURE__*/ function() {
                         }
                         return [
                             2,
-                            this.doFetch('POST', '/v1/public/artifacts', form, {
-                                'X-Client-Type': this.clientType
-                            })
+                            this.doFetch('POST', '/v1/public/artifacts', form, this.clientHeaders())
                         ];
                     });
                 }).call(this);
@@ -804,14 +838,14 @@ export var ApiClient = /*#__PURE__*/ function() {
                                     4,
                                     fetch(url, {
                                         method: 'GET',
-                                        headers: {
-                                            'Authorization': "Bearer ".concat(this.apiKey),
-                                            'X-Client-Type': this.clientType
-                                        }
+                                        headers: this.clientHeaders({
+                                            Authorization: "Bearer ".concat(this.apiKey)
+                                        })
                                     })
                                 ];
                             case 1:
                                 res = _state.sent();
+                                this.observeResponse(res);
                                 if (!!res.ok) return [
                                     3,
                                     3
@@ -961,10 +995,9 @@ export var ApiClient = /*#__PURE__*/ function() {
                                 return [
                                     4,
                                     fetch("".concat(this.baseUrl, "/v1/artifacts?limit=1"), {
-                                        headers: {
-                                            'Authorization': "Bearer ".concat(apiKey),
-                                            'X-Client-Type': this.clientType
-                                        }
+                                        headers: this.clientHeaders({
+                                            Authorization: "Bearer ".concat(apiKey)
+                                        })
                                     })
                                 ];
                             case 1:
@@ -980,6 +1013,7 @@ export var ApiClient = /*#__PURE__*/ function() {
                                     'network_error'
                                 ];
                             case 3:
+                                this.observeResponse(res);
                                 if (res.ok) {
                                     return [
                                         2,
@@ -1008,10 +1042,9 @@ export var ApiClient = /*#__PURE__*/ function() {
                     return _ts_generator(this, function(_state) {
                         return [
                             2,
-                            this.doFetch(method, path, body, {
-                                'Authorization': "Bearer ".concat(this.apiKey),
-                                'X-Client-Type': this.clientType
-                            })
+                            this.doFetch(method, path, body, this.clientHeaders({
+                                Authorization: "Bearer ".concat(this.apiKey)
+                            }))
                         ];
                     });
                 }).call(this);
@@ -1024,9 +1057,7 @@ export var ApiClient = /*#__PURE__*/ function() {
                     return _ts_generator(this, function(_state) {
                         return [
                             2,
-                            this.doFetch(method, path, body, {
-                                'X-Client-Type': this.clientType
-                            })
+                            this.doFetch(method, path, body, this.clientHeaders())
                         ];
                     });
                 }).call(this);
@@ -1045,15 +1076,15 @@ export var ApiClient = /*#__PURE__*/ function() {
                                     4,
                                     fetch(url, {
                                         method: method,
-                                        headers: {
-                                            'Content-Type': 'application/json',
-                                            'X-Client-Type': this.clientType
-                                        },
+                                        headers: this.clientHeaders({
+                                            'Content-Type': 'application/json'
+                                        }),
                                         body: body ? JSON.stringify(body) : undefined
                                     })
                                 ];
                             case 1:
                                 res = _state.sent();
+                                this.observeResponse(res);
                                 return [
                                     2,
                                     res.json()
@@ -1088,6 +1119,7 @@ export var ApiClient = /*#__PURE__*/ function() {
                                 ];
                             case 1:
                                 res = _state.sent();
+                                this.observeResponse(res);
                                 if (!!res.ok) return [
                                     3,
                                     3

package/dist/main.js

@@ -198,9 +198,26 @@ import { Command } from 'commander';
 import { ApiClient, ApiError } from './api-client.js';
 import { loadConfig, saveConfig } from './config.js';
 import { startMcpServer } from './mcp-server.js';
+import { emitOnExit, setCurrentVersion, setMcpMode } from './update-notice.js';
 import { DEFAULT_API_URL, DeviceCodeDeniedError, DeviceCodeExpiredError, DeviceCodeFailedError, InvalidFlagError, PublishArgsError, classifyBrandingError, parseShortIdAndVersion, parseShowBrandingFlag, pollDeviceToken, readApiKeyFromTty, readStreamToString, resolveAuth as resolveAuthFromEnvAndConfig, validatePublishArgs } from './main-helpers.js';
 var require = createRequire(import.meta.url);
 var version = require('../package.json').version;
+// Update-notice scaffolding (spec/feat-cli-update-notification.md). The
+// `'exit'` hook fires on every termination path — natural completion,
+// `process.exit(N)`, uncaught throws — so the notice lands regardless of
+// which exit path the command took. `'beforeExit'` would not work; it
+// does not fire when `process.exit()` is called explicitly.
+//
+// Process-level idempotency: keyed on a Symbol.for so `vi.resetModules()`
+// + dynamic re-import in tests does not stack a second listener (each
+// re-import would otherwise re-run this top-level statement).
+setCurrentVersion(version);
+var EXIT_HOOK_FLAG = Symbol.for('@displaydev/cli.exit-hook-registered');
+var flagged = process;
+if (!flagged[EXIT_HOOK_FLAG]) {
+    flagged[EXIT_HOOK_FLAG] = true;
+    process.on('exit', emitOnExit);
+}
 function resolveAuthOrConfig() {
     return _async_to_generator(function() {
         var auth;
@@ -256,11 +273,50 @@ function resolvePublicApiUrl() {
     var _process_env_DISPLAYDEV_API_URL;
     return (_process_env_DISPLAYDEV_API_URL = process.env.DISPLAYDEV_API_URL) !== null && _process_env_DISPLAYDEV_API_URL !== void 0 ? _process_env_DISPLAYDEV_API_URL : DEFAULT_API_URL;
 }
+/**
+ * Distribution-channel attribution stash. `--client-source <name>` is
+ * registered on `program` and on every subcommand in the tree (see
+ * `addClientSourceOptionRecursive` at the bottom of this file) and a
+ * `preAction` hook stashes the parsed value before any action runs.
+ * `createClient` and the two unauthenticated `new ApiClient(...)` sites
+ * then read the stash via `resolveClientSource()`.
+ *
+ * Why a global stash instead of threading through every action: there
+ * are ~20 direct-HTTP subcommands and a single resolution path; passing
+ * the value down through each action's opts type would touch every
+ * action handler for a flag that is structurally cross-cutting.
+ *
+ * The flag is also registered on `mcp` so `dsp mcp --client-source foo`
+ * is silently accepted (per spec §1 out-of-scope). The stash gets
+ * populated, but the mcp action builds its `ApiClient` without reading
+ * the stash, so the value never reaches the spawned MCP server's
+ * outgoing requests.
+ *
+ * Precedence: flag > `DISPLAYDEV_CLIENT_SOURCE` env > omitted. An
+ * explicitly empty flag (`--client-source=`) is treated as the user
+ * suppressing attribution: the env fallback is skipped and the header
+ * is omitted. The header is analytics-only; it does not affect audit /
+ * share-notification source normalization (which keys off
+ * `X-Client-Type`).
+ */ var clientSourceFromFlag;
+var clientSourceFlagPassed = false;
+function resolveClientSource() {
+    if (clientSourceFlagPassed) {
+        return clientSourceFromFlag;
+    }
+    var env = process.env.DISPLAYDEV_CLIENT_SOURCE;
+    if (typeof env === 'string' && env.length > 0) {
+        return env;
+    }
+    return undefined;
+}
 function createClient(auth) {
     return new ApiClient({
         baseUrl: auth.apiUrl,
         apiKey: auth.apiKey,
-        clientType: 'cli'
+        clientType: 'cli',
+        version: version,
+        clientSource: resolveClientSource()
     });
 }
 var program = new Command().name('dsp').description('display.dev CLI — publish artifacts behind company auth').version(version);
@@ -407,7 +463,9 @@ program.command('publish <path>').description('Publish an HTML or Markdown file.
                     publicClient = new ApiClient({
                         baseUrl: resolvePublicApiUrl(),
                         apiKey: '',
-                        clientType: 'cli'
+                        clientType: 'cli',
+                        version: version,
+                        clientSource: resolveClientSource()
                     });
                     _state.label = 10;
                 case 10:
@@ -1074,7 +1132,9 @@ program.command('login').description('Authenticate with display.dev').option('--
                     client = new ApiClient({
                         baseUrl: apiUrl,
                         apiKey: '',
-                        clientType: 'cli'
+                        clientType: 'cli',
+                        version: version,
+                        clientSource: resolveClientSource()
                     });
                     if (!(opts.apiKey !== undefined)) return [
                         3,
@@ -2247,6 +2307,7 @@ program.command('mcp').description('Start MCP server over stdin/stdout').action(
                     ];
                 case 1:
                     auth = _state.sent();
+                    setMcpMode();
                     if (!auth) return [
                         3,
                         3
@@ -2254,7 +2315,8 @@ program.command('mcp').description('Start MCP server over stdin/stdout').action(
                     client = new ApiClient({
                         baseUrl: auth.apiUrl,
                         apiKey: auth.apiKey,
-                        clientType: 'mcp-stdio'
+                        clientType: 'mcp-stdio',
+                        version: version
                     });
                     return [
                         4,
@@ -2274,7 +2336,8 @@ program.command('mcp').description('Start MCP server over stdin/stdout').action(
                     publicClient = new ApiClient({
                         baseUrl: resolvePublicApiUrl(),
                         apiKey: '',
-                        clientType: 'mcp-stdio'
+                        clientType: 'mcp-stdio',
+                        version: version
                     });
                     return [
                         4,
@@ -2291,4 +2354,61 @@ program.command('mcp').description('Start MCP server over stdin/stdout').action(
         });
     })();
 });
+/**
+ * Register `--client-source <name>` on `program` AND every command in
+ * the tree (top-level + nested under `comment` / `thread` + `mcp`).
+ * This makes the flag parseable at any level — `dsp --client-source
+ * foo publish ...`, `dsp publish --client-source foo ...`,
+ * `dsp comment --client-source foo add ...`, etc. — so the skill
+ * helpers (per spec §4.2 / §4.3 / §4.4) which exec `dsp publish
+ * --client-source … "$@"` work without per-command duplication of
+ * the action signature.
+ *
+ * `mcp` is included so the flag is silently accepted there too. The
+ * mcp action does not call `resolveClientSource()`, so the stashed
+ * value never reaches the spawned MCP server's `ApiClient` (spec §1
+ * out-of-scope).
+ */ function addClientSourceOptionRecursive(cmd) {
+    cmd.option('--client-source <name>', 'Distribution channel attribution (sent as X-Client-Source header for funnel analytics)');
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+    try {
+        for(var _iterator = cmd.commands[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var child = _step.value;
+            addClientSourceOptionRecursive(child);
+        }
+    } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+    } finally{
+        try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
+        } finally{
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
+        }
+    }
+}
+addClientSourceOptionRecursive(program);
+/**
+ * Resolve the parsed flag value before each action. Program-level
+ * `preAction` hooks fire ahead of every subcommand action, so a single
+ * registration is enough — the callback walks the active command up
+ * through its parents and stops at the first command whose `opts()`
+ * has a string-typed `clientSource` (distinguishing "not passed"
+ * `undefined` from "explicit blank" `''`).
+ */ program.hook('preAction', function(_thisCommand, actionCommand) {
+    var cursor = actionCommand;
+    while(cursor){
+        var val = cursor.opts().clientSource;
+        if (typeof val === 'string') {
+            clientSourceFlagPassed = true;
+            clientSourceFromFlag = val.length > 0 ? val : undefined;
+            return;
+        }
+        cursor = cursor.parent;
+    }
+});
 program.parse();

package/dist/mcp-server.js

@@ -192,6 +192,7 @@ import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ApiError } from './api-client.js';
+import { withUpdateNotice } from './update-notice.js';
 var FILE_ERROR_CODES = new Set([
     'ENOENT',
     'EACCES',
@@ -313,7 +314,7 @@ export function registerPublicTools(server, api) {
             'html',
             'md'
         ]).default('html').describe('Content format')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var hasContent, hasFilePath, content, _tmp, result, err;
             return _ts_generator(this, function(_state) {
@@ -409,7 +410,7 @@ export function registerPublicTools(server, api) {
                 }
             });
         })();
-    });
+    }));
 }
 export function registerTools(server, api) {
     server.tool('publish', 'Publish an HTML or Markdown artifact behind company auth', {
@@ -433,7 +434,7 @@ export function registerTools(server, api) {
             'hide',
             'inherit'
         ]).optional().describe('display.dev attribution bar override. Paid tier only; defaults to org setting when omitted.')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var _args_name, hasContent, hasFilePath, _args_name1, content, _tmp, result, _tmp1, err;
             return _ts_generator(this, function(_state) {
@@ -611,7 +612,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('find', 'List or search artifacts in the caller\'s organization. Omit `query` to list every artifact (paginated). Filter by name, one-or-more authors, one-or-more visibilities, or update time. Sort by `updated_at` (default), `view_count`, or `name`. Paginate via `cursor` — if the result includes a non-null `nextCursor`, pass it back to fetch the next page; if filters change between calls, drop the cursor. The response also carries `totalCount` (`-1` means the count query exceeded its budget — treat as "many"). `visibility: ["private"]` returns only your own private artifacts, not org-wide.', {
         query: z.string().optional().describe('Search by artifact name (case-insensitive substring). Omit to list all artifacts.'),
         author: z.array(z.string()).optional().describe('Filter by one or more authors. Each value: email, userId, or the literal "me". Multiple values are ORed. "me" requires a user-scoped credential — with an org API key the wire drops it.'),
@@ -632,7 +633,7 @@ export function registerTools(server, api) {
         ]).optional().describe('Sort direction. Defaults: desc for updated_at and view_count, asc for name.'),
         cursor: z.string().optional().describe('Opaque pagination token from a prior response. Pass it back to fetch the next page. WARNING: only valid for the same `sort`/`dir`/filter set that issued it — change a filter and drop the cursor, or results will be skewed without an error.'),
         limit: z.number().int().min(1).max(100).optional().describe('Max results per page (1–100, default 50).')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -667,11 +668,11 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('get', 'Get full details of a specific artifact', {
         short_id: z.string().describe('Artifact shortId'),
         include: z.array(z.string()).optional().describe('Include additional data (e.g. "versions")')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -706,11 +707,11 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('delete', 'Delete an artifact permanently', {
         short_id: z.string().describe('Artifact shortId to delete'),
         confirm: z.boolean().describe('Must be true to confirm deletion')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -764,7 +765,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('share', 'Change an artifact\'s visibility and/or add/remove individual shared-with emails without republishing.', {
         short_id: z.string().describe('Short ID of the artifact (8 chars).'),
         visibility: z.enum([
@@ -774,7 +775,7 @@ export function registerTools(server, api) {
         ]).optional().describe('Change the visibility level. Omit to keep current. "private" requires the Pro plan.'),
         add_users: z.array(z.string()).optional().describe('Emails to add to sharedWith (idempotent).'),
         remove_users: z.array(z.string()).optional().describe('Emails to remove from sharedWith (idempotent).')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -832,11 +833,11 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('rename', 'Rename a published artifact. The URL slug updates to match; existing URLs still resolve because routing uses the shortId.', {
         short_id: z.string().describe('The 8-character shortId returned at publish.'),
         name: z.string().describe('New display name. 1–200 characters.')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -875,7 +876,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('export', 'Retrieve the source bytes of a published artifact. `format: "original"` returns the publisher\'s upload (markdown for .md, HTML for .html). `format: "markdown"` always returns markdown — `.md` is unchanged, `.html` is converted via Workers AI (cached).', {
         short_id: z.string().describe('Short ID of the artifact (8 chars).'),
         version: z.number().int().min(1).optional().describe('Pinned version number. Omit for current.'),
@@ -883,7 +884,7 @@ export function registerTools(server, api) {
             'original',
             'markdown'
         ]).default('original').describe('Representation requested. Default "original".')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -931,7 +932,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     // Metadata-only: does NOT bump the artifact version. Use the `publish`
     // tool (with `show_branding`) when you're changing content at the same
     // time so both writes happen in one transaction.
@@ -942,7 +943,7 @@ export function registerTools(server, api) {
             'hide',
             'inherit'
         ]).describe('show = force branding on; hide = force off; inherit = follow org default')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -977,14 +978,14 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('set_logo', 'Upload or replace the org logo (paid tiers only). Used as the favicon on every artifact the org publishes. Stdio variant reads bytes from a local file path.', {
         file_path: z.string().describe('Path to a local PNG or WebP file. Square, 32×32 to 1024×1024, ≤256 KB.'),
         content_type: z.enum([
             'image/png',
             'image/webp'
         ]).optional().describe('Optional declared MIME type; inferred from the file extension when omitted.')
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var bytes, err, contentType, lower, result, err1;
             return _ts_generator(this, function(_state) {
@@ -1073,8 +1074,8 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
-    server.tool('clear_logo', 'Remove the org logo. Idempotent — succeeds even when no logo is currently set.', {}, function() {
+    }));
+    server.tool('clear_logo', 'Remove the org logo. Idempotent — succeeds even when no logo is currently set.', {}, withUpdateNotice(function() {
         return _async_to_generator(function() {
             var err;
             return _ts_generator(this, function(_state) {
@@ -1111,7 +1112,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     registerCommentTools(server, api);
 }
 /**
@@ -1179,7 +1180,7 @@ export function registerTools(server, api) {
         body: z.string().min(1).max(10000).describe('Comment body (≤10k chars)'),
         parent_id: z.string().optional().describe('Root comment id when posting a reply'),
         anchor: anchorSchema
-    }), function(args) {
+    }), withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var shortIdOrErr, result, err;
             return _ts_generator(this, function(_state) {
@@ -1233,7 +1234,7 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('list_comments', 'List comment threads on a subject. Reads from Postgres (not the KV widget cache).', _object_spread_props(_object_spread({}, subjectArgs), {
         status: z.enum([
             'open',
@@ -1241,7 +1242,7 @@ export function registerTools(server, api) {
             'all'
         ]).optional().describe('Defaults to "open"'),
         since: z.string().optional().describe('ISO-8601 — return only threads with activity at or after this timestamp')
-    }), function(args) {
+    }), withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var shortIdOrErr, result, err;
             return _ts_generator(this, function(_state) {
@@ -1294,11 +1295,11 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('edit_comment', 'Edit your own comment within the 5-minute author window. After 5 minutes the body is locked.', {
         comment_id: z.string(),
         body: z.string().min(1).max(10000)
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -1333,10 +1334,10 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('delete_comment', 'Soft-delete a comment. Author / artifact creator / org admin. Replies remain visible; body becomes "[deleted]".', {
         comment_id: z.string()
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var err;
             return _ts_generator(this, function(_state) {
@@ -1373,10 +1374,10 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('resolve_thread', 'Mark a thread resolved (root comment id). Thread participant / artifact creator / org admin.', {
         comment_id: z.string()
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -1411,10 +1412,10 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
     server.tool('reopen_thread', 'Reopen a resolved thread. Any authenticated user with view access on the artifact.', {
         comment_id: z.string()
-    }, function(args) {
+    }, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var result, err;
             return _ts_generator(this, function(_state) {
@@ -1449,8 +1450,8 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
-    server.tool('watch', 'Watch the subject for comment notifications. Per-user; service-account API keys cannot subscribe.', subjectArgs, function(args) {
+    }));
+    server.tool('watch', 'Watch the subject for comment notifications. Per-user; service-account API keys cannot subscribe.', subjectArgs, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var shortIdOrErr, result, err;
             return _ts_generator(this, function(_state) {
@@ -1500,8 +1501,8 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
-    server.tool('unwatch', 'Unwatch the subject. Per-user; service-account API keys cannot subscribe.', subjectArgs, function(args) {
+    }));
+    server.tool('unwatch', 'Unwatch the subject. Per-user; service-account API keys cannot subscribe.', subjectArgs, withUpdateNotice(function(args) {
         return _async_to_generator(function() {
             var shortIdOrErr, err;
             return _ts_generator(this, function(_state) {
@@ -1553,5 +1554,5 @@ export function registerTools(server, api) {
                 }
             });
         })();
-    });
+    }));
 }

package/dist/update-notice.js

@@ -0,0 +1,488 @@
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Update-notification surface for `@displaydev/cli`. Two paths consume it:
+ * plain CLI (stderr block printed from a `process.on('exit', ...)` hook)
+ * and MCP stdio (content block appended to the next `tools/call` result).
+ *
+ * Module-level state (`latestVersion`, `injectedThisProcess`,
+ * `currentVersion`) is intentional. Tests reset between cases via
+ * `vi.resetModules()` + dynamic re-import — there is no exported
+ * test-only reset.
+ */ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export var PACKAGE_NAME = '@displaydev/cli';
+var NOTICE_PREFIX = '[displaydev]';
+var THROTTLE_MS = 24 * 60 * 60 * 1000;
+var latestVersion = null;
+var injectedThisProcess = false;
+var currentVersion = null;
+var mcpMode = false;
+/**
+ * Stamp the running CLI's version. main.ts calls this once at module
+ * scope; the value is read by `emitOnExit` and `injectIntoToolResult`
+ * when they format the notice text.
+ */ export function setCurrentVersion(version) {
+    currentVersion = version;
+}
+/**
+ * Mark this process as a long-running MCP-stdio server. main.ts calls
+ * this from the `mcp` subcommand handler. Once set, `emitOnExit` skips —
+ * MCP mode surfaces the notice via `injectIntoToolResult`, and the
+ * stderr fallback would (a) write the wrong text variant ("npm i -g"
+ * vs. "bump the host config") and (b) reach nowhere useful since stdio
+ * MCP hosts do not surface stderr to the agent.
+ */ export function setMcpMode() {
+    mcpMode = true;
+}
+/** Mark the CLI outdated, capturing the registry's `latest` value. */ export function markOutdated(version) {
+    latestVersion = version;
+}
+/** Read the most recently observed `latest`, or null. */ export function getLatestVersion() {
+    return latestVersion;
+}
+function statePath() {
+    return join(homedir(), '.displaydev', 'update-state.json');
+}
+/** Read the per-machine throttle state. Missing or corrupt → empty. */ export function loadUpdateState() {
+    try {
+        var raw = readFileSync(statePath(), 'utf-8');
+        var parsed = JSON.parse(raw);
+        if (parsed && (typeof parsed === "undefined" ? "undefined" : _type_of(parsed)) === 'object') {
+            return parsed;
+        }
+        return {};
+    } catch (unused) {
+        return {};
+    }
+}
+/** Persist the throttle state. Best-effort; failures swallow. */ export function saveUpdateState(state) {
+    try {
+        var path = statePath();
+        mkdirSync(dirname(path), {
+            recursive: true
+        });
+        writeFileSync(path, "".concat(JSON.stringify(state), "\n"));
+    } catch (unused) {
+    // Best-effort per spec failure-modes table — a write that fails
+    // means we re-fire next invocation, which is preferable to a
+    // crash on read-only home or a full disk.
+    }
+}
+/**
+ * Compare two semver strings; returns true when `a > b`. Implements the
+ * pre-release ranking rules from semver.org §11:
+ *   - Numeric identifiers compare numerically.
+ *   - Alphanumeric identifiers compare lexically (ASCII).
+ *   - Numeric identifiers always rank below alphanumeric.
+ *   - A longer pre-release identifier list outranks a prefix-equal shorter
+ *     one (e.g. `0.20.0-alpha.1` > `0.20.0-alpha`).
+ *   - A stable release outranks any pre-release with the same `x.y.z`.
+ *
+ * Returns false for anything that fails to parse.
+ */ export function semverGt(a, b) {
+    // Strict semver (semver.org §9): numeric identifiers MUST NOT have
+    // leading zeros, identifiers MUST NOT be empty.
+    var NUMERIC_RE = /^(?:0|[1-9]\d*)$/;
+    var ALPHANUM_RE = /^[0-9A-Za-z-]+$/;
+    var SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+    var isValidPreId = function isValidPreId(id) {
+        if (id.length === 0) {
+            return false;
+        }
+        // Numeric identifier with leading zeros is invalid (`-01`, `-007`).
+        if (/^\d+$/.test(id) && id.length > 1 && id.startsWith('0')) {
+            return false;
+        }
+        return ALPHANUM_RE.test(id);
+    };
+    var parsed = function parsed(v) {
+        var match = SEMVER_RE.exec(v);
+        if (!match) {
+            return null;
+        }
+        // Reject leading zeros on the numeric main triple too (`01.0.0`).
+        if (![
+            match[1],
+            match[2],
+            match[3]
+        ].every(function(p) {
+            return NUMERIC_RE.test(p);
+        })) {
+            return null;
+        }
+        var preIds = match[4] ? match[4].split('.') : [];
+        if (!preIds.every(isValidPreId)) {
+            return null;
+        }
+        return {
+            parts: [
+                Number(match[1]),
+                Number(match[2]),
+                Number(match[3])
+            ],
+            preIds: preIds
+        };
+    };
+    var A = parsed(a);
+    var B = parsed(b);
+    if (!A || !B) {
+        return false;
+    }
+    for(var i = 0; i < 3; i++){
+        if (A.parts[i] !== B.parts[i]) {
+            return A.parts[i] > B.parts[i];
+        }
+    }
+    // Equal main parts: stable release outranks any pre-release.
+    if (A.preIds.length === 0 && B.preIds.length > 0) {
+        return true;
+    }
+    if (A.preIds.length > 0 && B.preIds.length === 0) {
+        return false;
+    }
+    var len = Math.min(A.preIds.length, B.preIds.length);
+    for(var i1 = 0; i1 < len; i1++){
+        var cmp = comparePreId(A.preIds[i1], B.preIds[i1]);
+        if (cmp !== 0) {
+            return cmp > 0;
+        }
+    }
+    // All shared identifiers equal: longer list ranks higher.
+    return A.preIds.length > B.preIds.length;
+}
+/**
+ * Compare two pre-release identifiers per semver §11.4. Numeric < alphanumeric;
+ * pure-numeric identifiers compare numerically; alphanumerics compare lexically.
+ * Returns positive when `a > b`, negative when `a < b`, 0 when equal.
+ */ function comparePreId(a, b) {
+    var numA = /^\d+$/.test(a);
+    var numB = /^\d+$/.test(b);
+    if (numA && numB) {
+        var na = Number(a);
+        var nb = Number(b);
+        return na === nb ? 0 : na > nb ? 1 : -1;
+    }
+    if (numA) {
+        return -1;
+    }
+    if (numB) {
+        return 1;
+    }
+    return a === b ? 0 : a > b ? 1 : -1;
+}
+/**
+ * Read `X-Client-Latest-Version` from a Response and, when greater than
+ * the local CLI version, mark the comparator outdated. Silently skips
+ * missing / blank / malformed values.
+ */ export function readLatestVersionFromResponse(res, current) {
+    var header = res.headers.get('x-client-latest-version');
+    if (!header) {
+        return;
+    }
+    var trimmed = header.trim();
+    if (!trimmed) {
+        return;
+    }
+    if (semverGt(trimmed, current)) {
+        markOutdated(trimmed);
+    }
+}
+export function formatNotice(opts) {
+    // Single-line dimmed banner for humans in a terminal — mode === 'cli'
+    // is the only path that ever sees `tty === true` (MCP is always stdio).
+    if (opts.mode === 'cli' && opts.tty) {
+        var dim = '\x1b[2m';
+        var reset = '\x1b[0m';
+        return "".concat(dim).concat(NOTICE_PREFIX, " update available: ").concat(opts.latest, " (you have ").concat(opts.current, "). Run `npm i -g ").concat(PACKAGE_NAME, "@latest` to update.").concat(reset);
+    }
+    if (opts.mode === 'cli') {
+        return [
+            "".concat(NOTICE_PREFIX, " Update available: ").concat(PACKAGE_NAME, " ").concat(opts.latest, " (you have ").concat(opts.current, ")."),
+            'Ask the user if they want to update.',
+            "If yes: run `npm i -g ".concat(PACKAGE_NAME, "@latest` (or the equivalent for their package manager — bun, pnpm, yarn — based on how they installed it) and retry the original command.")
+        ].join('\n');
+    }
+    // MCP variant: npm i -g does not update an already-running stdio
+    // process; the host has to bump its config and restart.
+    return [
+        "".concat(NOTICE_PREFIX, " Update available: ").concat(PACKAGE_NAME, " ").concat(opts.latest, " (you have ").concat(opts.current, ")."),
+        'Ask the user if they want to update.',
+        "If yes: bump the version pin for ".concat(PACKAGE_NAME, " in their MCP host config, or if the config uses @latest, ask them to restart their MCP host.")
+    ].join('\n');
+}
+function passesThrottle(now, state) {
+    if (!state.lastNoticeAt) {
+        return true;
+    }
+    var last = Date.parse(state.lastNoticeAt);
+    if (Number.isNaN(last)) {
+        return true;
+    }
+    return now - last >= THROTTLE_MS;
+}
+/**
+ * Synchronous `'exit'` handler for plain CLI mode. Fires after every
+ * termination path (natural completion, `process.exit(N)`, uncaught
+ * exception). Must remain synchronous — the event loop is winding
+ * down by the time it runs, so `await` would silently no-op.
+ *
+ * Skips when the process is running as a stdio MCP server (notice text
+ * differs and stderr is not surfaced to the host) or when injection has
+ * already fired in this process (MCP mode already prompted via the
+ * tool-result content block).
+ */ export function emitOnExit() {
+    if (mcpMode) {
+        return;
+    }
+    if (injectedThisProcess) {
+        return;
+    }
+    if (latestVersion === null || currentVersion === null) {
+        return;
+    }
+    var state = loadUpdateState();
+    var now = Date.now();
+    if (!passesThrottle(now, state)) {
+        return;
+    }
+    var text = formatNotice({
+        current: currentVersion,
+        latest: latestVersion,
+        mode: 'cli',
+        tty: Boolean(process.stderr.isTTY)
+    });
+    process.stderr.write("".concat(text, "\n"));
+    saveUpdateState({
+        lastNoticeAt: new Date(now).toISOString(),
+        lastNoticeVersion: latestVersion
+    });
+}
+/**
+ * Append a notice content block to a tool-call result when:
+ *   1. The comparator has marked the CLI outdated.
+ *   2. We have not already injected once in this process.
+ *   3. The cross-process 24 h throttle allows.
+ *
+ * Preserves `_meta`, `isError`, and any other top-level fields. Only
+ * `content` changes shape (a new entry appended).
+ */ export function injectIntoToolResult(result) {
+    if (latestVersion === null || currentVersion === null) {
+        return result;
+    }
+    if (injectedThisProcess) {
+        return result;
+    }
+    var now = Date.now();
+    var state = loadUpdateState();
+    if (!passesThrottle(now, state)) {
+        return result;
+    }
+    var text = formatNotice({
+        current: currentVersion,
+        latest: latestVersion,
+        mode: 'mcp',
+        tty: false
+    });
+    result.content = _to_consumable_array(result.content).concat([
+        {
+            type: 'text',
+            text: text
+        }
+    ]);
+    injectedThisProcess = true;
+    saveUpdateState({
+        lastNoticeAt: new Date(now).toISOString(),
+        lastNoticeVersion: latestVersion
+    });
+    return result;
+}
+/**
+ * Higher-order wrapper around an MCP tool handler. Awaits the inner
+ * handler then runs the result through `injectIntoToolResult`.
+ *
+ * Mounted in `mcp-server.ts` at every `server.tool(...)` registration
+ * site so injection runs uniformly regardless of which return shape
+ * (`okResponse` / `errorResponse` / direct literal / `_meta`-bearing)
+ * the inner handler returned.
+ */ export function withUpdateNotice(handler) {
+    return function() {
+        for(var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++){
+            args[_key] = arguments[_key];
+        }
+        return _async_to_generator(function() {
+            var result;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            handler.apply(void 0, _to_consumable_array(args))
+                        ];
+                    case 1:
+                        result = _state.sent();
+                        return [
+                            2,
+                            injectIntoToolResult(result)
+                        ];
+                }
+            });
+        })();
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displaydev/cli",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "bin": {
     "dsp": "dist/main.js"