@adobe/design-data-agent-mcp 1.9.5 → 1.9.7

package/README.md

@@ -38,7 +38,11 @@ package version — there's no separate data update to run. Pin `@latest` (as ab
 fetches the newest published version rather than reusing whatever it last cached; `-y` alone
 only skips the install confirmation, it doesn't force a re-fetch. Already on `/plugin`? Run
 `/plugin update design-data-agent@spectrum-design-data`. Call the primer tool and check
-`provenance.designDataVersion` to see which dataset version is embedded.
+`provenance.designDataVersion` to see which dataset version is embedded. The primer tool
+also does a best-effort check against the latest published `@adobe/spectrum-design-data`
+version — if the embedded dataset is behind, it adds a `provenance.datasetStatus` field and
+logs a one-line warning to stderr. This is silent on any network failure (offline/air-gapped
+use is unaffected); set `DESIGN_DATA_SKIP_VERSION_CHECK=1` to disable the check entirely.
 
 ## MCP server
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/design-data-agent-mcp",
-  "version": "1.9.5",
+  "version": "1.9.7",
   "description": "MCP server and Claude Code skill for the design-data agent surface — read tools run in-process via wasm",
   "type": "module",
   "main": "./src/index.js",
@@ -32,7 +32,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@adobe/design-data": "3.0.7",
     "@adobe/design-data-wasm": "0.7.0",
-    "@adobe/spectrum-design-data": "2.7.0"
+    "@adobe/spectrum-design-data": "3.0.0"
   },
   "devDependencies": {
     "ava": "^6.0.1"

package/skills/design-data/SKILL.md

@@ -6,7 +6,7 @@ description: >
   system, token lookup, spec-conformance, drift detection, or token authoring on custom data.
 metadata:
   author: adobe
-  version: "1.9.5"
+  version: "1.9.7"
 when_to_use: >
   Trigger on: design system, design tokens, spec-conformant, drift, validate tokens, token
   authoring, custom dataset, DESIGN_DATA_PATH, design-data validate, design-data diff,

package/src/dataset-freshness.js

@@ -0,0 +1,95 @@
+// Copyright 2026 Adobe. All rights reserved.
+// This file is licensed to you under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may obtain a copy
+// of the License at http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software distributed under
+// the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+// OF ANY KIND, either express or implied. See the License for the specific language
+// governing permissions and limitations under the License.
+
+/**
+ * Best-effort runtime check that the embedded dataset (provenance.designDataVersion,
+ * baked into @adobe/design-data-wasm at build time) isn't behind the latest published
+ * @adobe/spectrum-design-data. See spectrum-design-data-9fe.5 — a plain `npx -y <pkg>`
+ * (no @latest tag) can silently reuse a cached older wasm build.
+ *
+ * Deliberately silent on any failure (offline, registry down, timeout): this is a
+ * courtesy signal, never a reason to break the primer response.
+ */
+
+const REGISTRY_URL =
+  "https://registry.npmjs.org/@adobe/spectrum-design-data/latest";
+const TIMEOUT_MS = 1500;
+
+/**
+ * Numeric major.minor.patch compare. ponytail: ignores prerelease/build tags;
+ * add real semver only if a data prerelease ships.
+ */
+export function isBehind(embedded, latest) {
+  const a = String(embedded).split(".").map(Number);
+  const b = String(latest).split(".").map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+let warned = false;
+let cached; // Promise<status|null>, memoized per process — cleared on failure so a
+// transient network blip doesn't permanently disable the check (see fetchLatest).
+
+/**
+ * @param {string} embeddedVersion - provenance.designDataVersion from ds.primer()
+ * @returns {Promise<{latestVersion: string, isStale: boolean, message?: string}|null>}
+ */
+export function checkDatasetFreshness(embeddedVersion) {
+  if (!embeddedVersion || process.env.DESIGN_DATA_SKIP_VERSION_CHECK) {
+    return Promise.resolve(null);
+  }
+  if (!cached) {
+    cached = fetchLatest(embeddedVersion).then((status) => {
+      // A null result means the check failed (offline/timeout/registry error) —
+      // don't memoize failure, so the next primer call retries instead of being
+      // stuck with no freshness signal for the rest of the process.
+      if (status === null) cached = undefined;
+      return status;
+    });
+  }
+  return cached;
+}
+
+async function fetchLatest(embeddedVersion) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const { version: latestVersion } = await res.json();
+    const isStale = isBehind(embeddedVersion, latestVersion);
+    const status = { latestVersion, isStale };
+    if (isStale) {
+      status.message =
+        `Embedded dataset (${embeddedVersion}) is behind the latest published ` +
+        `@adobe/spectrum-design-data (${latestVersion}). Reinstall with ` +
+        `npx -y @adobe/design-data-agent-mcp@latest to pick up the newer snapshot.`;
+      if (!warned) {
+        warned = true;
+        console.error(`[design-data] ${status.message}`);
+      }
+    }
+    return status;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Test-only: clear the memoized check + warn-once flag between cases. */
+export function __resetFreshnessCache() {
+  warned = false;
+  cached = undefined;
+}

package/src/tools/read.js

@@ -32,6 +32,7 @@ import { readFileSync, existsSync, readdirSync } from "fs";
 import { join } from "path";
 import { loadDataset } from "@adobe/design-data/load";
 import { config } from "../config.js";
+import { checkDatasetFreshness } from "../dataset-freshness.js";
 
 // Note: this module intentionally never spawns the native binary — primer and
 // describe_component must keep working with no CLI on PATH at all (see the
@@ -107,6 +108,11 @@ export function createReadTools() {
         const wasm = await getWasm();
         const ds = await getDataset();
         const { provenance } = ds.primer();
+        // Best-effort staleness check (spectrum-design-data-9fe.5) — silent on
+        // failure, never blocks the primer response.
+        const datasetStatus = await checkDatasetFreshness(
+          provenance.designDataVersion,
+        );
         return {
           // top-level source is the legacy skill-contract field; provenance.source
           // duplicates it intentionally — provenance is the richer metrics object
@@ -124,7 +130,9 @@ export function createReadTools() {
           },
           components: wasm.getFieldValues("component") ?? [],
           properties: wasm.getFieldValues("property") ?? [],
-          provenance,
+          provenance: datasetStatus
+            ? { ...provenance, datasetStatus }
+            : provenance,
         };
       },
     },