@reqvire-org/ads 0.3.9 → 0.3.11

package/dist/mcp/build-status.mjs

@@ -2,7 +2,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { isInside, projectPath } from "../config.mjs";
+import { isInside, projectPath, loadConfig } from "../config.mjs";
+import { previewSourceRevision } from "../preview-inputs.mjs";
 import { readPreviewManifest } from "../preview-resources.mjs";
 import { previewArtifactPath, withPreviewSession } from "../preview-scope.mjs";
 
@@ -10,7 +11,7 @@ export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
 const maxBytes = 256 * 1024;
 const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
-const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
+const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), sourceRevision:z.string().regex(/^[a-f0-9]{64}$/).optional(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
 const progressSchema = z.object({ phase: z.enum(["queued", "validation", "compilation", "validation-and-compilation", "publication", "idle"]), startedAt: z.string().datetime(), updatedAt: z.string().datetime() }).strict();
 const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), progress: progressSchema.optional(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
@@ -93,8 +94,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
       apps = next;
       save();
     },
-    begin(id) {
+    begin(id,{sourceRevision = previewSourceRevision(loadConfig(root),apps)} = {}) {
       const value = entry(id);
+      value.sourceRevision = sourceRevision;
       value.state = "building";
       value.revision++;
       value.diagnostics = [];
@@ -137,6 +139,11 @@ export function inspectBuildStatus(root, config, { session, previewSession, proc
     }
   } catch (error) { reportError = `Invalid preview build status: ${error.message.slice(0, 500)}`; }
   let graphError;
+  let sourceRevision, sourceError;
+  if (report?.previews.some(entry=>entry.state==="ready")) {
+    try { sourceRevision = previewSourceRevision(loadConfig(root),config.apps); }
+    catch (error) { sourceError = `Cannot verify preview inputs: ${error.message}`; }
+  }
   if (config.previewManifest && report?.previews.some(entry => entry.state === "ready")) {
     try {
       if (!readPreviewManifest(options, { verify: true })) throw new Error("Preview resource manifest is missing.");
@@ -154,13 +161,16 @@ export function inspectBuildStatus(root, config, { session, previewSession, proc
     if (state === "ready") {
       try {
         if (value.lastSuccessfulRevision !== value.revision || artifactDigest(artifact) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
+        if (sourceError) throw new Error(sourceError);
+        if (!value.sourceRevision) throw new Error("Preview builder did not record its source revision. Rebuild using the current ADS build reporter.");
+        if (value.sourceRevision !== sourceRevision) { state = "idle"; diagnostics = [{code:"ADS_PREVIEW_STALE_SOURCE",message:"Project inputs changed after this preview was built. Waiting for a build of the current source."}]; }
       } catch (error) { state = "error"; diagnostics = [{ message: error.message }]; }
     }
     if (processState?.state === "failed") { state = "error"; diagnostics = [{ message: processState.error ?? "Preview watcher exited." }, ...diagnostics].slice(0, 20); }
     if (["stopped", "stopping", "idle"].includes(processState?.state)) state = "unreported";
     const current = state === "ready";
     return { id: app.id, state, session: report?.session ?? null, revision: value?.revision ?? null, lastSuccessfulRevision: value?.lastSuccessfulRevision ?? null,
-      current, stale: state === "unreported" ? null : !current, available, diagnostics };
+      current, stale: state === "unreported" ? null : !current, available, ...(value?.sourceRevision ? {sourceRevision:value.sourceRevision} : {}), diagnostics };
   });
   const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
   return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, ...(report?.progress ? { progress: report.progress } : {}), previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };

package/dist/mcp/preview-watch.mjs

@@ -31,16 +31,17 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   const ready = new Set();
   const requests = new Set();
   let active;
+  let invalidation;
   let requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
   let reportFile = path.join(root, ".ds", `build-status-${session}.json`);
-  function request(file) {
-    if (!command || requests.has(file) && active === file) return;
+  function request(file,force = false) {
+    if (!command || !force && requests.has(file) && active === file) return;
     requests.add(file);
     active = file;
     mkdirSync(path.dirname(requestFile), { recursive: true });
     if (realpathSync(path.dirname(requestFile)) !== path.dirname(requestFile)) throw new Error("Preview requests cannot resolve through a symlink.");
     const temporary = `${requestFile}.tmp`;
-    writeFileSync(temporary, JSON.stringify({ session, active: path.relative(root, active).replaceAll("\\", "/"), files: [...requests].map((file) => path.relative(root, file).replaceAll("\\", "/")) }));
+    writeFileSync(temporary, JSON.stringify({ session, active: path.relative(root, active).replaceAll("\\", "/"), files: [...requests].map((file) => path.relative(root, file).replaceAll("\\", "/")), ...(invalidation ? {invalidation} : {}) }));
     renameSync(temporary, requestFile);
   }
 
@@ -135,7 +136,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     if (state === "failed" || restarting || stalled) await restart();
     if (disposed) throw new Error("Preview watcher is stopped.");
     start();
-    request(file);
+    request(file,buildStatus().previews.some(entry=>entry.diagnostics.some(item=>item.code==="ADS_PREVIEW_STALE_SOURCE")));
     if (signal?.aborted) throw new Error("Preview request cancelled.");
     const app = config.apps.find((entry) => path.resolve(root, entry.file) === file);
     let baseline = baselines.get(file) ?? null;
@@ -181,7 +182,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     })();
     return stopping;
   }
-  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, resourceSession, buildStatus, setApps(apps) {
+  return { start, ensure, invalidate() { invalidation = randomUUID(); if (active) request(active,true); }, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, resourceSession, buildStatus, setApps(apps) {
     for (const app of apps) {
       const file = path.resolve(root, app.file);
       if (!baselines.has(file)) baselines.set(file, stamp(file));
@@ -202,6 +203,7 @@ export function createReconfigurablePreviewWatch(root, config, options) {
     status() { return replacing ? { state: "reconfiguring" } : current.status(); },
     resourceSession() { return current.resourceSession(); },
     buildStatus() { return current.buildStatus(); },
+    async invalidate() { await pending; if (!stopped) current.invalidate(); },
     setApps(next) { apps = next; current.setApps(next); },
     kill() { current.kill(); },
     reconfigure(next, force = false) {

package/dist/mcp/server.mjs

@@ -46,6 +46,14 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     cache.registry = cache.catalog = cache.documents = undefined;
   }
   const getShowcaseUrl = () => showcaseUrl?.() ?? options.config.mcp.showcaseUrl;
+  function scenarioUrl(id) {
+    const base = getShowcaseUrl();
+    if (!base) return null;
+    const url = new URL(base);
+    url.searchParams.delete("category");
+    url.searchParams.set("scenario", id);
+    return url.href;
+  }
   const project = () => { const context = projectContext(options); context.showcase.url = getShowcaseUrl(); return context; };
   const subscribed = new Set();
   const server = new Server({ name: "reqvire-ads", version: pkg.version }, {
@@ -171,6 +179,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     if (result.applied) {
       try {
         if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration" || result.units?.includes("configuration")) await previewWatch?.reconfigure?.(loadConfig(root).config.mcp,true);
+        await previewWatch?.invalidate?.();
         await refresh(true);
       } catch (error) {result.warnings=[...(result.warnings ?? []),{rule:"mutation-notification",message:`Changes were applied, but preview refresh failed: ${error.message.slice(0,2000)}. Recheck ads_status and reopen the scenario.`}];}
     }
@@ -197,10 +206,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const build = await previewBuild(app, signal);
         const graph = graphSelection(id);
         if (!options.config.mcp.previewManifest) projectApp(options, app, build);
-        const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
-        url?.searchParams.delete("category");
-        url?.searchParams.set("scenario", id);
-        return json({ widget: { resourceUri: scenarioWidget() }, scenario: { ...entry, resourceUri: appUri(id) }, ...graph, build, showcaseUrl: url?.href ?? null });
+        return json({ widget: { resourceUri: scenarioWidget() }, scenario: { ...entry, resourceUri: appUri(id) }, ...graph, build, showcaseUrl: scenarioUrl(id) });
       } },
       { name: "ads_tokens", description: "Use before styling, theme, brand or motion-token changes to inspect existing semantic definitions/values. Query specific token names with a small limit. ads_show_tokens renders project token scenarios; definition inspection does not validate component layout.", schema: query, call: ({ query: search = "", limit }) => {
         const inventory = inspectTokens(root);
@@ -233,10 +239,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
           const build = await previewBuild(app, signal);
           const graph = graphSelection(category);
           if (!options.config.mcp.previewManifest) projectApp(options, app, build);
-          const url = getShowcaseUrl() ? new URL(getShowcaseUrl()) : null;
-          url?.searchParams.delete("scenario");
-          url?.searchParams.set("category", category);
-          return json({ widget: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI }, category, scenario: { ...entry, resourceUri: appUri(category) }, ...graph, build, showcaseUrl: url?.href ?? null });
+          return json({ widget: { resourceUri: options.config.mcp.previewManifest ? PREVIEW_APP_URI : TOKENS_APP_URI }, category, scenario: { ...entry, resourceUri: appUri(category) }, ...graph, build, showcaseUrl: scenarioUrl(category) });
         }
         return json({ widget: { resourceUri: TOKENS_APP_URI }, category: null, tokenCount: inspectTokens(root).tokens.length, dataUri: `${PROJECT_URI}/tokens`, showcaseUrl: getShowcaseUrl() });
       } },

package/dist/preview-inputs.mjs

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { isInside } from "./config.mjs";
+
+/** Shared source evidence for compilation, watch recovery and status reads. */
+export function previewSourceRevision({root,config}, apps = config.mcp.apps ?? []) {
+  const rows = [], generated = config.assets.generatedPaths.map(file => path.resolve(root,file));
+  const outputs = new Set(apps.map(app => path.resolve(root,app.file)));
+  function digest(file) { return createHash("sha256").update(readFileSync(file)).digest("hex"); }
+  function visit(directory) {
+    for (const entry of readdirSync(directory,{withFileTypes:true})) {
+      if (entry.isSymbolicLink() || ["node_modules",".git",".ds",".vite","coverage"].includes(entry.name)) continue;
+      const file = path.join(directory,entry.name);
+      if (outputs.has(file) || generated.some(base => isInside(base,file))) continue;
+      if (entry.isDirectory()) visit(file);
+      else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) rows.push([path.relative(root,file),digest(file)]);
+    }
+  }
+  visit(root);
+  const installed = path.join(root,"node_modules/.package-lock.json");
+  rows.push(["installed-packages",existsSync(installed) ? digest(installed) : null]);
+  return createHash("sha256").update(JSON.stringify(rows.sort((a,b)=>a[0].localeCompare(b[0])))).digest("hex");
+}

package/dist/preview-resources.mjs

@@ -28,7 +28,8 @@ export function previewEntriesPlugin(entries, mountEntry) {
     load(id) {
       const entry = ids.get(id.slice(1));
       if (!entry) return;
-      return `import { mountScenario } from ${JSON.stringify(mountEntry)};import Scenario from ${JSON.stringify(path.resolve(entry.root, entry.file))};export const mount = container => mountScenario(Scenario,container);`;
+      const styles = (entry.stylesheets ?? []).map(file => `import ${JSON.stringify(path.resolve(entry.root, file))};`).join("");
+      return `import { mountScenario } from ${JSON.stringify(mountEntry)};${styles}import Scenario from ${JSON.stringify(path.resolve(entry.root, entry.file))};export const mount = container => mountScenario(Scenario,container);`;
     },
   };
 }

package/dist/scenarios-compiler.mjs

@@ -6,6 +6,7 @@ import { inspectScenarios } from "./scenarios.mjs";
 import { artifactDigest, createBuildReporter } from "./mcp/build-status.mjs";
 import { cachedPreviewPublication, previewArtifactHtml, readPreviewManifest } from "./preview-resources.mjs";
 import { previewArtifactPath, withPreviewSession } from "./preview-scope.mjs";
+import { previewSourceRevision } from "./preview-inputs.mjs";
 
 const digest = value => createHash("sha256").update(value).digest("hex");
 const fileDigest = file => { try { return digest(readFileSync(file)); } catch { return null; } };
@@ -13,8 +14,8 @@ const fileDigest = file => { try { return digest(readFileSync(file)); } catch {
 /** Cache only successful validation + matching source/dependency/output content.
  * Cache state is development output, never proof that a failed build is current. */
 export function createPreviewCache(options, compilerFiles = []) {
-  const { root, config } = options;
-  const adapterFiles = [import.meta.filename, ...["preview-resources.mjs", "preview-scope.mjs", "scenarios-vite.mjs", "linaria.mjs", "linaria/atomic-css.cjs", "linaria/atomic-styled.cjs", "linaria/preserve-values.cjs"].map(file => path.join(import.meta.dirname, file)), ...compilerFiles,
+  const { root } = options;
+  const adapterFiles = [import.meta.filename, ...["preview-inputs.mjs", "preview-resources.mjs", "preview-scope.mjs", "scenarios-vite.mjs", "linaria.mjs", "linaria/atomic-css.cjs", "linaria/atomic-styled.cjs", "linaria/preserve-values.cjs"].map(file => path.join(import.meta.dirname, file)), ...compilerFiles,
     ...["package.json", "package-lock.json", "bun.lock", "bun.lockb", "node_modules/.package-lock.json"].map(file => path.join(root, file))];
   const adapterDigest = () => digest(JSON.stringify(adapterFiles.map(file => [file, fileDigest(file)])));
   const loadedAdapter = adapterDigest();
@@ -27,20 +28,7 @@ export function createPreviewCache(options, compilerFiles = []) {
     }
   } catch { /* Missing or corrupt cache means validate and rebuild. */ }
   function inputs() {
-    const rows = [];
-    const generated = config.assets.generatedPaths.map(file => path.resolve(root, file));
-    function visit(directory) {
-      for (const entry of readdirSync(directory, { withFileTypes: true })) {
-        if (entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)) continue;
-        const file = path.join(directory, entry.name);
-        if (generated.some(base => isInside(base, file))) continue;
-        if (entry.isDirectory()) visit(file);
-        else if (entry.isFile() && /\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) rows.push([path.relative(root, file), fileDigest(file)]);
-      }
-    }
-    visit(root);
-    rows.push(["installed-packages", fileDigest(path.join(root, "node_modules/.package-lock.json"))]);
-    rows.push(["node-runtime", `${process.version}/${process.platform}/${process.arch}`]);
+    const rows = [["project-inputs",previewSourceRevision(options)],["node-runtime",`${process.version}/${process.platform}/${process.arch}`]];
     for (const file of compilerFiles) rows.push([file, fileDigest(file)]);
     // Tool upgrades invalidate validation even when the project's lockfile is unchanged.
     for (const name of readdirSync(import.meta.dirname).filter(name => name.endsWith(".mjs"))) {
@@ -119,6 +107,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   let generation = 0;
   let publishedStamp;
   let validation;
+  let observedSourceRevision = previewSourceRevision(options);
+  let invalidation;
   function failure(error) {
     try { reporter.failure(error); } catch (reportError) { console.error(reportError); }
     console.error(error);
@@ -144,7 +134,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   }
   async function compile(entry) {
     if (buildGraph) return compileGraph();
-    const revision = reporter.begin(entry.id);
+    const revision = reporter.begin(entry.id,{sourceRevision:previewSourceRevision(options)});
     const started = generation;
     try {
       const stamp = cache.inputs();
@@ -187,7 +177,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     }
   }
   async function compileGraph() {
-    const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id)]));
+    const sourceRevision = previewSourceRevision(options);
+    const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id,{sourceRevision})]));
     const started = generation;
     try {
       const stamp = cache.inputs();
@@ -257,6 +248,10 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     try {
       const value = JSON.parse(readFileSync(file, "utf8"));
       if (value.session !== process.env.ADS_MCP_BUILD_SESSION) return;
+      if (value.invalidation !== invalidation) {
+        invalidation = value.invalidation;
+        if (requested.size) sourceChanged("invalidate",options.config.dsDir,true);
+      }
       active = entries.find(entry => entry.artifact === value.active)?.id;
       for (const file of value.files) {
         const entry = entries.find(entry => entry.artifact === file);
@@ -288,6 +283,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const changes = [...changed]; changed.clear();
       try {
         entries = registry();
+        observedSourceRevision = previewSourceRevision(options);
         registryFailure = undefined;
         reporter.setApps(buildApps());
         reporter.clearFailure();
@@ -297,7 +293,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         // compilation. Check active first, then rebuild only changed dependencies.
         for (const id of requested) {
           const entry = entries.find(entry => entry.id === id);
-          if (entry) { reporter.begin(id); pending.add(id); }
+          if (entry) { reporter.begin(id,{sourceRevision:observedSourceRevision}); pending.add(id); }
         }
         if (changes.length) void drain();
       } catch (error) {
@@ -344,7 +340,17 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     } catch (error) { failure(error); }
   }
   reconcileWatches(true);
-  const reconcileTimer = setInterval(reconcileWatches, 1000);
+  const reconcileTimer = setInterval(() => {
+    reconcileWatches();
+    try {
+      const current = previewSourceRevision(options);
+      if (current !== observedSourceRevision) {
+        observedSourceRevision = current;
+        sourceChanged("reconcile",options.config.dsDir,true);
+      }
+      request();
+    } catch (error) { failure(error); }
+  }, 1000);
   request();
   console.log(`Scenario compiler ready: ${entries.length} entries; builds are requested on demand.`);
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {

package/dist/scenarios.mjs

@@ -110,7 +110,8 @@ export function inspectScenarios(options, suppliedProgram) {
       const owner = scoped.inventory.owner(relative);
       for (const name of tokens) if (tokenInventory.tokens.find(token => token.name === name)?.owner !== owner) report(file, `Token ${name} needs a preview beside its defining owner. Shared tokens belong under the configured token directory; local tokens stay with their component/pattern.`);
     }
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    const stylesheets = kind === "tokens" ? scoped.definitions.filter(entry => entry.unit === scoped.inventory.owner(relative)).map(entry => entry.file) : [];
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(Object.hasOwn(metadata, "exercises") ? { exercises: [...new Set(exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), ...(stylesheets.length ? { stylesheets } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }