@cparkerwebm/webmonterey 1.0.0

package/src/cli/design-extract.ts

@@ -0,0 +1,229 @@
+/*
+ * `webm design:extract` - turn a hand-edited tokens.css into design.json.
+ *
+ * Run once per site during a rebuild. Reads the stylesheet, diffs every declaration against the
+ * default token set, and writes only what differs - mapped to a structured field where one
+ * exists, and to `overrides` where none does.
+ *
+ * It REPORTS what it could not map rather than dropping it. A token silently lost here becomes a
+ * color that quietly reverts on a site someone already signed off, which is the failure this
+ * command exists to prevent.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { DEFAULTS } from '../design/defaults.ts';
+import { MAPPING } from '../design/compile.ts';
+import type { DesignSystem } from '../design/types.ts';
+
+const DEFAULT_VALUES = new Map(DEFAULTS.flatMap((g) => g.tokens.map((t) => [t.name, t.value])));
+const REVERSE = new Map(MAPPING.map(([path, token]) => [token, path]));
+
+export interface ParsedTokens {
+  /** Declarations at the top level, outside every at-rule. The site's actual token values. */
+  base: Map<string, string>;
+  /**
+   * Declarations nested inside an at-rule, keyed by token, with the at-rule preludes they came
+   * from. These CANNOT be represented in design.json - it compiles a flat :root block - so they
+   * are reported and left in the stylesheet rather than folded into the base values.
+   */
+  conditional: Map<string, string[]>;
+}
+
+/**
+ * Pull `--webm-x: value;` pairs out of a stylesheet, SEPARATING at-rule-scoped ones.
+ *
+ * THE BUG THIS REPLACES was a flat regex over the whole file, last-write-wins. tokens.css sets
+ * a token in :root and then overrides it inside `@media (prefers-reduced-motion: reduce)`, so
+ * the media value overwrote the real one and became the site's base. Converting webmonterey.com
+ * that way wrote `--webm-duration-fast: 0ms` as its base: every animation on the site disabled
+ * for every visitor, from a migration that reported success.
+ *
+ * Worse, it was invisible to the obvious check. Comparing parseTokens(original) against
+ * parseTokens(compiled) matched 238 of 238 - both sides ran the same broken parser, so the
+ * comparison only proved it was consistently wrong.
+ *
+ * Brace counting rather than a CSS parser: this reads one hand-written file with a known shape,
+ * and a dependency for it would be the larger risk.
+ */
+export function parseTokens(css: string): ParsedTokens {
+  const source = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const base = new Map<string, string>();
+  const conditional = new Map<string, string[]>();
+
+  /*
+   * ONLY CONDITIONAL AT-RULES COUNT. `@layer webm.tokens { :root { ... } }` is how every one of
+   * these stylesheets is written, and a layer does not make a declaration conditional - it only
+   * places it in the cascade. Treating every at-rule as conditional put the entire file inside
+   * one, so nothing was a base value and the whole extraction came back empty.
+   *
+   * @media, @supports and @container apply their contents only when the condition holds. Those
+   * are the ones design.json cannot express.
+   */
+  const CONDITIONAL = /^@(media|supports|container)\b/;
+
+  /* The conditional at-rule preludes currently open. */
+  const atRules: string[] = [];
+  /* Brace depth at which each open at-rule started, so it can be popped on the matching close. */
+  const atRuleDepth: number[] = [];
+  let depth = 0;
+  let buffer = '';
+
+  for (let i = 0; i < source.length; i++) {
+    const char = source[i]!;
+
+    if (char === '{') {
+      const prelude = buffer.trim();
+      if (CONDITIONAL.test(prelude)) {
+        atRules.push(prelude);
+        atRuleDepth.push(depth);
+      }
+      depth++;
+      buffer = '';
+      continue;
+    }
+
+    if (char === '}') {
+      depth--;
+      if (atRuleDepth.length && atRuleDepth.at(-1) === depth) {
+        atRules.pop();
+        atRuleDepth.pop();
+      }
+      buffer = '';
+      continue;
+    }
+
+    if (char === ';') {
+      const declaration = buffer.trim();
+      const match = /^(--webm-[\w-]+)\s*:\s*([\s\S]+)$/.exec(declaration);
+      if (match) {
+        const [, name, value] = match as unknown as [string, string, string];
+        if (atRules.length === 0) {
+          base.set(name, value.trim());
+        } else {
+          conditional.set(name, [...(conditional.get(name) ?? []), atRules.join(' / ')]);
+        }
+      }
+      buffer = '';
+      continue;
+    }
+
+    buffer += char;
+  }
+
+  return { base, conditional };
+}
+
+function setPath(target: Record<string, unknown>, path: readonly string[], value: string): void {
+  let node = target;
+  for (const key of path.slice(0, -1)) {
+    node[key] ??= {};
+    node = node[key] as Record<string, unknown>;
+  }
+  node[path.at(-1)!] = value;
+}
+
+export interface ExtractResult {
+  design: DesignSystem;
+  mapped: string[];
+  overridden: string[];
+  added: string[];
+  unchanged: number;
+  /**
+   * Tokens the stylesheet also sets inside an at-rule, with the preludes. design.json compiles a
+   * flat :root block and cannot express these, so they stay in the site's own CSS - and the
+   * command has to SAY so, because a silently dropped media override is a site that stops
+   * responding to reduced-motion or to a breakpoint with nothing to show for it.
+   */
+  conditional: Map<string, string[]>;
+}
+
+export function extract(css: string): ExtractResult {
+  const { base: found, conditional } = parseTokens(css);
+  const design: DesignSystem = { version: 1 };
+  const mapped: string[] = [];
+  const overridden: string[] = [];
+  const added: string[] = [];
+  let unchanged = 0;
+
+  for (const [name, value] of found) {
+    const isKnown = DEFAULT_VALUES.has(name);
+    if (isKnown && DEFAULT_VALUES.get(name) === value) {
+      unchanged++;
+      continue;
+    }
+    const path = REVERSE.get(name);
+    if (path) {
+      setPath(design as Record<string, unknown>, path, value);
+      mapped.push(name);
+    } else {
+      design.overrides ??= {};
+      design.overrides[name] = value;
+      (isKnown ? overridden : added).push(name);
+    }
+  }
+
+  return { design, mapped, overridden, added, unchanged, conditional };
+}
+
+export function run(argv: string[]): number {
+  const input = argv[0] ?? 'src/styles/tokens.css';
+  const output = argv[1] ?? 'design.json';
+
+  if (!existsSync(input)) {
+    console.error(`webm design:extract: no such file: ${input}`);
+    console.error(`  usage: webm design:extract [tokens.css] [design.json]`);
+    return 1;
+  }
+  if (existsSync(output)) {
+    console.error(`webm design:extract: ${output} already exists. Move it aside first.`);
+    return 1;
+  }
+
+  const result = extract(readFileSync(input, 'utf8'));
+  const json = JSON.stringify(
+    { $schema: './node_modules/@cparkerwebm/webmonterey/schema/design.json', ...result.design },
+    null,
+    2,
+  );
+  writeFileSync(output, json + '\n');
+
+  console.log(`Read ${input}`);
+  console.log(`  ${result.unchanged} tokens match the defaults and were omitted`);
+  if (result.mapped.length) {
+    console.log(`  ${result.mapped.length} mapped to structured fields:`);
+    for (const n of result.mapped) console.log(`      ${n}`);
+  }
+  if (result.overridden.length) {
+    console.log(`  ${result.overridden.length} kept as overrides (no structured field exists):`);
+    for (const n of result.overridden) console.log(`      ${n}`);
+  }
+  if (result.added.length) {
+    console.log(`  ${result.added.length} are site tokens, not part of the default set:`);
+    for (const n of result.added) console.log(`      ${n}`);
+  }
+  console.log(`\nWrote ${output}`);
+
+  /*
+   * THE PART THAT MUST NOT BE QUIET. design.json compiles one flat :root block, so a token the
+   * stylesheet also sets inside @media cannot be carried across. Folding those values into the
+   * base is what the old parser did, and it wrote a reduced-motion 0ms as webmonterey.com's real
+   * animation duration - every animation off, for every visitor, reported as a success.
+   */
+  if (result.conditional.size) {
+    console.log(
+      `\n${result.conditional.size} tokens are ALSO set inside an at-rule. design.json holds one\n` +
+        `flat :root block, so those conditional values are NOT in it and must stay in CSS:\n`,
+    );
+    for (const [name, rules] of result.conditional) {
+      console.log(`      ${name}   ${[...new Set(rules)].join(', ')}`);
+    }
+    console.log(
+      `\n  Move those blocks to src/styles/custom/_index.css. Leaving them behind silently\n` +
+        `  drops reduced-motion handling and every responsive token override.`,
+    );
+  }
+
+  console.log(
+    `\nNext: delete ${input}, and check the compiled output matches what the site rendered before.`,
+  );
+  return 0;
+}

package/src/cli/doctor.ts

@@ -0,0 +1,187 @@
+/*
+ * `webm doctor` - the consolidated check for everything that fails silently.
+ *
+ * Generation 2 specified these across a dozen places in CLAUDE.md, as prose a reader had to
+ * remember. Prose is a convention; this is a mechanism. Each check maps to a trap that produced a
+ * real client incident, and each failure is invisible in normal use - which is precisely why a
+ * command has to go looking.
+ *
+ * Exit code is 1 on any failure, so it can gate a build or a go-live.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { CHECKS, type CheckContext } from './checks.ts';
+import { loadSiteFiles } from '../integration/config.ts';
+
+import { PACKAGE_ROOT, packageVersion } from './package-root.ts';
+
+/** Strip // and /* comments so JSON.parse can read a .jsonc file. */
+function parseJsonc<T>(source: string): T {
+  const stripped = source
+    .replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (m, comment) => (comment ? '' : m))
+    .replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(stripped) as T;
+}
+
+function readTree(root: string, dir: string, exts: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string) => {
+    if (!existsSync(d)) return;
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const full = join(d, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (exts.some((e) => entry.name.endsWith(e))) {
+        out.set(relative(root, full), readFileSync(full, 'utf8'));
+      }
+    }
+  };
+  walk(join(root, dir));
+  return out;
+}
+
+/**
+ * The custom Worker entrypoint named by wrangler `main`, if there is one.
+ *
+ * `main` is normally absent - the adapter generates the entrypoint. A site sets it only to add
+ * handlers the generated one has no room for, which in practice means `scheduled()`.
+ */
+/**
+ * public/ files still byte-identical to the package's seeded placeholder.
+ *
+ * Compared by bytes rather than by hash of a known list, so replacing the artwork clears it
+ * however the client's file was produced.
+ */
+function placeholderFiles(siteRoot: string): string[] {
+  const seeded = join(PACKAGE_ROOT, 'template', 'public');
+  if (!existsSync(seeded)) return [];
+  return readdirSync(seeded)
+    .filter((file) => {
+      const theirs = join(siteRoot, 'public', file);
+      if (!existsSync(theirs)) return false;
+      try {
+        /* Compare as base64 rather than Buffer.equals: this file typechecks without Node's
+         * Buffer typings, and the files involved are a few dozen kilobytes at most. */
+        return readFileSync(theirs, 'base64') === readFileSync(join(seeded, file), 'base64');
+      } catch {
+        return false;
+      }
+    })
+    .map((file) => `public/${file}`);
+}
+
+function readWorkerEntry(siteRoot: string, wranglerPath: string | undefined | null): string | null {
+  if (!wranglerPath) return null;
+  const config = parseJsonc(readFileSync(wranglerPath, 'utf8')) as { main?: string };
+  if (!config.main) return null;
+  const entry = join(siteRoot, config.main);
+  return existsSync(entry) ? readFileSync(entry, 'utf8') : null;
+}
+
+function contentPageNames(root: string): string[] {
+  const dir = join(root, 'src/content/pages');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''));
+}
+
+/**
+ * .mcp.json and the pre-approval list out of .claude/settings.json.
+ *
+ * Both are read leniently: a repo with malformed JSON in either is a repo whose MCP setup is
+ * broken, and the check reports that as a missing server rather than the doctor throwing on a
+ * file it was only inspecting.
+ */
+function readMcp(siteRoot: string): CheckContext['mcp'] {
+  const read = <T>(rel: string, pick: (parsed: Record<string, unknown>) => T): T | null => {
+    const path = join(siteRoot, rel);
+    if (!existsSync(path)) return null;
+    try {
+      return pick(JSON.parse(readFileSync(path, 'utf8')));
+    } catch {
+      return null;
+    }
+  };
+  return {
+    declared: read('.mcp.json', (p) => (p.mcpServers ?? null) as Record<string, { url?: string }>),
+    enabled: read('.claude/settings.json', (p) => (p.enabledMcpjsonServers ?? null) as string[]),
+  };
+}
+
+export function buildContext(siteRoot: string): CheckContext {
+  const { site } = loadSiteFiles(siteRoot);
+  const wranglerPath = ['wrangler.jsonc', 'wrangler.json']
+    .map((f) => join(siteRoot, f))
+    .find(existsSync);
+  const syncPath = join(siteRoot, '.claude/skills/webm/.webm-sync.json');
+
+  return {
+    site,
+    wrangler: wranglerPath ? parseJsonc(readFileSync(wranglerPath, 'utf8')) : null,
+    pages: readTree(siteRoot, 'src/pages', ['.astro', '.ts']),
+    components: readTree(siteRoot, 'src/components', ['.astro', '.ts']),
+    today: new Date().toISOString().slice(0, 10),
+    workerEntry: readWorkerEntry(siteRoot, wranglerPath),
+    placeholders: placeholderFiles(siteRoot),
+    contentPages: contentPageNames(siteRoot),
+    content: readTree(siteRoot, 'src/content/pages', ['.json']),
+    /*
+     * Everything else in the repo that can hold a call the compiler will not resolve for you:
+     * actions, the site's own includes and email templates, and the SQL that has to have a
+     * migration behind it. Read here rather than in each check so a check stays a pure function
+     * of its context and the tests can hand it a literal.
+     */
+    actions: readTree(siteRoot, 'src/actions', ['.ts']),
+    includes: readTree(siteRoot, 'src/includes', ['.ts', '.astro']),
+    emails: readTree(siteRoot, 'src/emails', ['.ts']),
+    migrations: readTree(siteRoot, 'migrations', ['.sql']),
+    registry: existsSync(join(siteRoot, 'src/components/registry.ts'))
+      ? readFileSync(join(siteRoot, 'src/components/registry.ts'), 'utf8')
+      : null,
+    present: Object.fromEntries(
+      [
+        'public/_headers',
+        'public/favicon.ico',
+        'public/site.webmanifest',
+        'scripts/check-node.mjs',
+      ].map((f) => [f, existsSync(join(siteRoot, f))]),
+    ),
+    sync: existsSync(syncPath) ? JSON.parse(readFileSync(syncPath, 'utf8')) : null,
+    mcp: readMcp(siteRoot),
+    version: packageVersion(),
+  };
+}
+
+export function run(argv: string[]): number {
+  const siteRoot = argv[0] ?? process.cwd();
+  if (!existsSync(join(siteRoot, 'webmonterey.json'))) {
+    console.error(`webm doctor: no webmonterey.json in ${siteRoot}. Not a WebMonterey site.`);
+    return 1;
+  }
+
+  const ctx = buildContext(siteRoot);
+  let failed = 0;
+  let warned = 0;
+
+  for (const check of CHECKS) {
+    const result = check.run(ctx);
+    const mark = result.status === 'pass' ? '  ok ' : result.status === 'warn' ? 'warn ' : 'FAIL ';
+    console.log(`${mark} ${check.title}`);
+    if (result.detail) {
+      console.log(`       ${result.detail}`);
+      /*
+       * The failure mode is printed with the failure. A check that only says what is wrong makes
+       * the reader guess whether it matters; saying what it looks like from outside is what turns
+       * "not listed in run_worker_first" into something worth fixing before a client sees it.
+       */
+      if (result.status === 'fail') console.log(`       fails as: ${check.silentAs}`);
+    }
+    if (result.status === 'fail') failed++;
+    if (result.status === 'warn') warned++;
+  }
+
+  console.log(
+    `\n${CHECKS.length - failed - warned} passed, ${warned} warning${warned === 1 ? '' : 's'}, ${failed} failed`,
+  );
+  return failed > 0 ? 1 : 0;
+}

package/src/cli/mcp.test.ts

@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { MCP_NAMES, MCP_SERVERS, mcpConfig, mcpGaps } from './mcp.ts';
+
+const repo = new URL('../../', import.meta.url);
+const readJson = (rel: string) => JSON.parse(readFileSync(new URL(rel, repo), 'utf8'));
+
+test('every server is http and has an absolute https url', () => {
+  for (const [name, s] of Object.entries(MCP_SERVERS)) {
+    assert.equal(s.type, 'http', name);
+    assert.ok(s.url.startsWith('https://'), `${name} is not https`);
+    assert.ok(s.purpose.length > 0, `${name} has no stated purpose`);
+  }
+});
+
+test('mcpConfig drops purpose - it documents our file, not the protocol', () => {
+  const entry = mcpConfig().mcpServers['astro-docs'];
+  assert.deepEqual(Object.keys(entry).sort(), ['type', 'url']);
+});
+
+/*
+ * THE POINT OF THE MODULE. Four places have to agree about these servers, and two of them are
+ * checked-in files in this repo rather than code, so nothing but a test can notice them drifting.
+ * Adding a server to mcp.ts and forgetting the repo's own .mcp.json is the exact mistake that
+ * leaves the framework being written from recall while every client site reads current docs.
+ */
+test("the package's own .mcp.json is what mcp.ts says it should be", () => {
+  assert.deepEqual(readJson('.mcp.json'), mcpConfig());
+});
+
+test("the package's own settings pre-approve every server, in order", () => {
+  assert.deepEqual(readJson('.claude/settings.json').enabledMcpjsonServers, MCP_NAMES);
+});
+
+test('a fully wired repo has no gaps', () => {
+  assert.deepEqual(mcpGaps(mcpConfig().mcpServers, MCP_NAMES), {
+    undeclared: [],
+    unapproved: [],
+    wrongUrl: [],
+  });
+});
+
+test('gaps separate not-declared from declared-but-inert, because the fixes differ', () => {
+  const gaps = mcpGaps({ 'astro-docs': { url: MCP_SERVERS['astro-docs'].url } }, []);
+  assert.deepEqual(gaps.undeclared, ['mdn', 'website-spec', 'email-spec']);
+  assert.deepEqual(gaps.unapproved, ['astro-docs']);
+});
+
+test('a server pointed somewhere else is a gap even when declared and approved', () => {
+  const gaps = mcpGaps({ ...mcpConfig().mcpServers, mdn: { url: 'https://evil.test' } }, MCP_NAMES);
+  assert.deepEqual(gaps.wrongUrl, ['mdn']);
+});
+
+test('nothing at all is reported as everything undeclared rather than throwing', () => {
+  assert.deepEqual(mcpGaps(null, null).undeclared, MCP_NAMES);
+});

package/src/cli/mcp.ts

@@ -0,0 +1,110 @@
+/*
+ * The documentation servers every WebMonterey repo talks to, and the one list that says so.
+ *
+ * WHY THIS IS A MODULE AND NOT A LITERAL IN THE SCAFFOLD. Four places have to agree about these
+ * servers: the scaffold writes them into a new site, the codemod adds them to an existing one,
+ * `webm doctor` checks a site still has them, and the package's own .mcp.json declares them for
+ * this repo. Four literals is four chances to add a server in three places and spend an afternoon
+ * on why one repo answers from training data.
+ *
+ * WHAT THEY ARE FOR. Astro ships majors faster than any model's corpus turns over, and the web
+ * platform ships behavior continuously - baseline support, a new API, a deprecation. Both
+ * servers exist so a session can read what is true today rather than recalling what was true at
+ * a training cutoff. Neither of them enforces anything on their own: they are a reference. What
+ * makes a session USE them is the rule in CLAUDE.md, and what makes a repo keep them wired is
+ * the `mcp-docs` check in doctor.
+ */
+
+export interface McpServer {
+  type: 'http';
+  url: string;
+  /** Said in the file, so the next person reading .mcp.json knows what it is for. */
+  purpose: string;
+}
+
+export const MCP_SERVERS: Record<string, McpServer> = {
+  /*
+   * Astro's own, from docs.astro.build/en/guides/build-with-ai. Free, open source, and the
+   * documented way to give a tool current Astro knowledge.
+   */
+  'astro-docs': {
+    type: 'http',
+    url: 'https://mcp.docs.astro.build/mcp',
+    purpose: 'Current Astro documentation. Consult before using any Astro API.',
+  },
+  /*
+   * Mozilla's, from developer.mozilla.org/en-US/mcp. Search, reference and - the part no model
+   * has current - browser compatibility data.
+   *
+   * EXPERIMENTAL, AND MOZILLA SAYS SO: it may be withdrawn at any time, and queries are logged
+   * while the experiment runs. It is a docs lookup, so nothing confidential should reach it in
+   * the first place; the rule in CLAUDE.md is what keeps it that way. If it disappears, the
+   * failure is a session that cannot reach it, not a build that breaks.
+   */
+  mdn: {
+    type: 'http',
+    url: 'https://mcp.mdn.mozilla.net/',
+    purpose: 'MDN reference and browser-compat data. Consult before using a web platform API.',
+  },
+  /*
+   * The Website Specification and The Email Specification - Joost de Valk and contributors,
+   * MIT/CC BY. Search, per-topic pages and, the useful part here, generated checklists across
+   * SEO, accessibility, performance, privacy, security and i18n.
+   *
+   * GUIDANCE, NOT A STANDARD, WHATEVER THE NAME SAYS. These are opinionated best-practice
+   * documents, not normative specs, and they are at 0.2.0 and 0.1.0. They must never outrank MDN
+   * or the Astro docs on what an API does; they answer a different question - what a good site or
+   * a good email does. CLAUDE.md states that precedence, because a server called
+   * "specification" invites exactly the wrong assumption.
+   */
+  'website-spec': {
+    type: 'http',
+    url: 'https://mcp.specification.website/mcp',
+    purpose: 'Site-quality guidance: SEO, accessibility, performance, privacy, security, i18n.',
+  },
+  /*
+   * Email is a SEPARATE server from the website one - the Website Specification excludes it by
+   * design. It earns its place because src/emails/ is where recall is worst: client rendering
+   * quirks and deliverability rules move, and a template that looks right in a browser is not
+   * evidence of anything.
+   */
+  'email-spec': {
+    type: 'http',
+    url: 'https://mcp.specification.email/mcp',
+    purpose: 'Email guidance: rendering, deliverability, accessibility. For src/emails/ work.',
+  },
+};
+
+/** The server names, in the order they should appear everywhere. */
+export const MCP_NAMES: string[] = Object.keys(MCP_SERVERS);
+
+/** The `.mcp.json` body. `purpose` is dropped - it documents this file, not the protocol. */
+export function mcpConfig(): { mcpServers: Record<string, { type: string; url: string }> } {
+  return {
+    mcpServers: Object.fromEntries(
+      Object.entries(MCP_SERVERS).map(([name, s]) => [name, { type: s.type, url: s.url }]),
+    ),
+  };
+}
+
+/**
+ * What a repo is missing, given what it declares and what it pre-approves.
+ *
+ * TWO LISTS, BECAUSE A SERVER CAN BE WIRED AND STILL INERT. A server in .mcp.json that is not in
+ * `enabledMcpjsonServers` prompts for approval on every machine, and a rule that depends on
+ * whoever cloned the repo happening to hit Approve is not a rule. That is the failure this
+ * separates out rather than folding into one boolean.
+ */
+export function mcpGaps(
+  declared: Record<string, { url?: string }> | null | undefined,
+  enabled: string[] | null | undefined,
+): { undeclared: string[]; unapproved: string[]; wrongUrl: string[] } {
+  const d = declared ?? {};
+  const e = new Set(enabled ?? []);
+  const undeclared = MCP_NAMES.filter((n) => !(n in d));
+  return {
+    undeclared,
+    unapproved: MCP_NAMES.filter((n) => n in d && !e.has(n)),
+    wrongUrl: MCP_NAMES.filter((n) => n in d && d[n]?.url !== MCP_SERVERS[n].url),
+  };
+}