@expressivecss/mcp-server 0.3.1 → 0.4.0

package/contract.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "generatedBy": "scripts/gen-expressivecss-skill.mjs",
-  "frameworkVersion": "0.13.1",
-  "skillVersion": "0.9.0",
-  "matchingTag": "v0.13.1",
+  "frameworkVersion": "0.14.1",
+  "skillVersion": "0.10.0",
+  "matchingTag": "v0.14.1",
   "releaseTags": [
     "v0.10.0",
     "v0.10.1",
@@ -11,6 +11,8 @@
     "v0.12.0",
     "v0.13.0",
     "v0.13.1",
+    "v0.14.0",
+    "v0.14.1",
     "v0.5.0",
     "v0.6.0",
     "v0.7.0",
@@ -27,5 +29,5 @@
     "package.json",
     "CHANGELOG.md"
   ],
-  "sourceHash": "18ec4146d300280bbcb74eb3b23f16d1015a0a3db86a8c59fc8348dbdf9d96c2"
+  "sourceHash": "80d854b3978953f2491c292c4c9c0fe32f72842a9d9a03e4e0b8aff409314463"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "ExpressiveCSS MCP server with Design→QA workflow tools.",
   "homepage": "https://www.expressivecss.com",
   "repository": {

package/scripts/resolve-version.mjs

@@ -33,14 +33,15 @@ async function readBounded(filePath) {
     if (!before.isFile() || !sameFile(before, pathBefore)) return { error: 'identity-changed' };
     const limit = readLimit(filePath);
     if (before.size > BigInt(limit)) return { error: 'oversized' };
-    const buffer = Buffer.alloc(limit + 1);
+    // Size the buffer to the file, not the limit. The spare byte exposes growth.
+    const buffer = Buffer.allocUnsafe(Number(before.size) + 1);
     let offset = 0;
     while (offset < buffer.length) {
       const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
       if (bytesRead === 0) break;
       offset += bytesRead;
     }
-    if (offset > limit) return { error: 'oversized' };
+    if (offset > before.size) return { error: 'identity-changed' };
     const after = await handle.stat({ bigint: true });
     const pathAfter = await lstat(filePath, { bigint: true });
     const currentResolved = await realpath(filePath);

package/semantics-data.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "generatedBy": "mcp/expressivecss/scripts/sync-guides.mjs",
-  "frameworkVersion": "0.13.1",
+  "frameworkVersion": "0.14.1",
   "semantics": {
     "about": "Normative HTML semantics for ExpressiveCSS. This data file is the single source of truth: SEMANTICS.md is generated from it by scripts/gen-semantics.mjs, and tests/semantics.test.js enforces it. One row per roster entry, each stating its kind - component, foundation or behavior, as CONTEXT.md defines them. CONTEXT.md defines the rest of the vocabulary.",
     "scope": "Element choice, landmark structure, and the ARIA that element choice implies. Keyboard interaction, focus management and colour contrast are deliberately out of scope.",
@@ -977,6 +977,26 @@
           }
         ]
       },
+      "map": {
+        "status": "enforced",
+        "note": "Added with the map component. MapLibre draws the map on a canvas, so the frame needs a name for the region it is, and a marker that opens a popup has to be a button to be reached and activated from the keyboard. Icon-only controls are covered by icon-only-control-is-named.",
+        "rules": [
+          {
+            "id": "map-is-named",
+            "kind": "forbid",
+            "selector": ".map:not([aria-label], [aria-labelledby])",
+            "fragmentSafe": true,
+            "message": "Name the map with aria-label or aria-labelledby, and give it role=\"region\". MapLibre's canvas has no useful name of its own."
+          },
+          {
+            "id": "map-popup-marker-is-button",
+            "kind": "forbid",
+            "selector": ".map-marker[aria-controls]:not(button)",
+            "fragmentSafe": true,
+            "message": "A marker that opens a popup is a <button type=\"button\"> with aria-label, so the keyboard can reach and open it."
+          }
+        ]
+      },
       "accordion": {
         "status": "enforced",
         "note": "Added with the accordion component. Each item is a native <details>, so the browser exposes <summary> as a button with its expanded state and handles the keyboard. The rules keep authors from re-stating that state or nesting controls in the toggle.",
@@ -1216,6 +1236,34 @@
           }
         ]
       },
+      "confetti": {
+        "status": "enforced",
+        "note": "Added with the confetti component. The pieces are decoration drawn on a canvas, so an authored confetti canvas is hidden from assistive technology. The page-wide canvas the script creates hides itself.",
+        "rules": [
+          {
+            "id": "confetti-canvas-is-hidden",
+            "kind": "require-attr",
+            "selector": "canvas.confetti",
+            "attr": "aria-hidden",
+            "equals": "true",
+            "message": "Confetti is decoration. Mark the canvas aria-hidden=\"true\" and say what happened in text, for example in a snackbar."
+          }
+        ]
+      },
+      "particles": {
+        "status": "enforced",
+        "note": "Added with the particles component. The dots are decoration drawn on a canvas, so the canvas is hidden from assistive technology.",
+        "rules": [
+          {
+            "id": "particles-canvas-is-hidden",
+            "kind": "require-attr",
+            "selector": "canvas.particles",
+            "attr": "aria-hidden",
+            "equals": "true",
+            "message": "Particles are decoration. Mark the canvas aria-hidden=\"true\"."
+          }
+        ]
+      },
       "tree": {
         "status": "enforced",
         "note": "Added with the tree component. Nested lists of native disclosures and links: every row is a Tab stop and the browser opens a branch, so no tree role is promised.",

package/server.js

@@ -62,6 +62,7 @@ function configuredCommandRoots(value) {
   return trimmed.split(path.delimiter).map((entry) => entry.trim()).filter(Boolean);
 }
 
+const PROJECT_ROOTS_SETTING = 'EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS';
 const QUALITY_SCRIPTS = ['typecheck', 'test', 'verify:expressivecss'];
 // Trusted server configuration can only narrow the built-in list. Invalid input denies all.
 function configuredScripts(value) {
@@ -82,6 +83,8 @@ const SETTINGS = {
   commandTimeoutMs: Number(process.env.EXPRESSIVECSS_MCP_COMMAND_TIMEOUT_MS || DEFAULT_COMMAND_TIMEOUT_MS),
   allowedScripts: configuredScripts(process.env.EXPRESSIVECSS_MCP_ALLOWED_SCRIPTS),
   allowedCommandRoots: configuredCommandRoots(process.env.EXPRESSIVECSS_MCP_ALLOWED_COMMAND_ROOTS),
+  // Unset keeps every root open. A set but empty or invalid list denies every client-supplied root.
+  allowedProjectRoots: process.env[PROJECT_ROOTS_SETTING] === undefined ? null : configuredCommandRoots(process.env[PROJECT_ROOTS_SETTING]),
 };
 
 const SKIP_FLAGS = {
@@ -316,7 +319,29 @@ function parseCliProjectRoot() {
 }
 
 function resolveProjectRoot(projectRoot) {
-  return projectRoot ? path.resolve(projectRoot) : parseCliProjectRoot();
+  return projectRoot ? authorizedProjectRoot(projectRoot) : parseCliProjectRoot();
+}
+
+// The operator's default root is trusted. When configured, a client-supplied root must sit inside an allowed root.
+function authorizedProjectRoot(projectRoot) {
+  const resolved = path.resolve(projectRoot);
+  if (!SETTINGS.allowedProjectRoots) return resolved;
+  let canonical = null;
+  try { canonical = realpathSync(resolved); } catch {}
+  if (!canonical || !matchingRoot(SETTINGS.allowedProjectRoots, canonical)) {
+    throw new Error(`projectRoot is not inside a root allowed by ${PROJECT_ROOTS_SETTING}.`);
+  }
+  return resolved;
+}
+
+function matchingRoot(configuredRoots, candidate) {
+  return configuredRoots.flatMap((configuredRoot) => {
+    try {
+      return [realpathSync(path.resolve(configuredRoot))];
+    } catch {
+      return [];
+    }
+  }).find((allowedRoot) => isPathInside(allowedRoot, candidate)) ?? null;
 }
 
 function resolveRepoRoot(startDir) {
@@ -407,7 +432,7 @@ function serializeToolResult(payload) {
   return {
     content: [{
       type: 'text',
-      text: JSON.stringify(payload, null, GUIDANCE_TOOLS.has(payload.stage) ? undefined : 2),
+      text: JSON.stringify(payload),
     }],
     structuredContent: payload,
     ...(payload.responseBudget?.delivery === 'error' ? { isError: true } : {}),
@@ -833,6 +858,8 @@ async function loadGuideCatalog(projectRoot) {
     guideSource: 'bundled',
     count: bundledGuideCache.count,
     components: bundledGuideCache.components,
+    // Handlers reuse this resolution instead of reading the lockfiles again.
+    version: projectResolution,
   };
 }
 
@@ -965,9 +992,9 @@ async function projectSummary(projectRoot) {
   return summary;
 }
 
-async function resolveAgainstContract(projectRoot, contractVersion) {
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
-  if (contractVersion) return version;
+function resolveAgainstContract(catalog) {
+  const version = catalog.version;
+  if (catalog.frameworkVersion) return version;
   return {
     ...version,
     status: 'unresolved',
@@ -1534,14 +1561,7 @@ function isPathInside(root, candidate) {
 
 function commandExecutionPolicy(projectRoot) {
   const resolvedProjectRoot = realpathSync(path.resolve(projectRoot));
-  const allowedRoots = SETTINGS.allowedCommandRoots.flatMap((configuredRoot) => {
-    try {
-      return [realpathSync(path.resolve(configuredRoot))];
-    } catch {
-      return [];
-    }
-  });
-  const matchedRoot = allowedRoots.find((allowedRoot) => isPathInside(allowedRoot, resolvedProjectRoot)) ?? null;
+  const matchedRoot = matchingRoot(SETTINGS.allowedCommandRoots, resolvedProjectRoot);
   return {
     configured: SETTINGS.allowedCommandRoots.length > 0,
     allowed: Boolean(matchedRoot),
@@ -1591,7 +1611,7 @@ function stopProcessTree(proc, signal) {
   }
 }
 
-function redactSensitiveText(value) {
+export function redactSensitiveText(value) {
   return String(value)
     .replace(/(Authorization\s*:\s*Bearer\s+)[^\s,;]+/giu, '$1[REDACTED]')
     .replace(/\b(Bearer\s+)[A-Za-z0-9._~+\/-]{16,}/giu, '$1[REDACTED]')
@@ -1602,11 +1622,12 @@ function redactSensitiveText(value) {
     .replace(/\bxox[baprs]-[A-Za-z0-9-]{20,}\b/gu, '[REDACTED]')
     .replace(/\bsk-[A-Za-z0-9_-]{20,}\b/gu, '[REDACTED]')
     .replace(/\bAKIA[0-9A-Z]{16}\b/gu, '[REDACTED]')
-    .replace(/\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, '[REDACTED]')
+    // Start only where a token run starts; a bare `\b` retries inside `a-b-c` runs in quadratic time.
+    .replace(/(?<![A-Za-z0-9_-])[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, '[REDACTED]')
     .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, '[REDACTED]')
     .replace(/(["'])(API[_-]?KEY|TOKEN|PASSWORD|PASSWD|SECRET|CLIENT[_-]?SECRET|CLIENTSECRET|CONNECTION[_-]?STRING|ACCESS_TOKEN|REFRESH_TOKEN|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY)\1\s*:\s*(["'])[^"'\r\n]*\3/giu, '$1$2$1:$3[REDACTED]$3')
     .replace(/\b(API[_-]?KEY|TOKEN|PASSWORD|PASSWD|SECRET|CLIENT[_-]?SECRET|CLIENTSECRET|CONNECTION[_-]?STRING|ACCESS_TOKEN|REFRESH_TOKEN|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY)\s*[:=]\s*[^\s,;]+/giu, '$1=[REDACTED]')
-    .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/giu, '$1[REDACTED]@')
+    .replace(/([a-z][a-z0-9+.-]{0,31}:\/\/)[^\s/@:]+:[^\s/@]+@/giu, '$1[REDACTED]@') // Bounded scheme keeps long runs linear.
     .replace(/\/(?:home|Users)\/[^/\s"'<>]+(?:\/[^\s"'<>),;\]}]*)?/gu, '[LOCAL_PATH]')
     .replace(/\/(?:private\/)?tmp\/[^\s"'<>),;\]}]+/gu, '[LOCAL_PATH]')
     .replace(/[A-Z]:\\+Users\\+[^\\\s]+(?:\\+[^\s]*)?/giu, '[LOCAL_PATH]');
@@ -1630,18 +1651,17 @@ export async function readInspectionFile(filePath, projectRoot, byteLimit) {
       throw error;
     }
 
-    const bytes = Buffer.allocUnsafe(byteLimit + 1);
+    // Size the buffer to the file, not the limit. The spare byte exposes growth
+    // and files such as /proc entries that report a smaller size than they hold.
+    const capacity = Number(before.size) + 1;
+    const bytes = Buffer.allocUnsafe(capacity);
     let total = 0;
-    while (total <= byteLimit) {
-      const chunk = await handle.read(bytes, total, byteLimit + 1 - total, total);
+    while (total < capacity) {
+      const chunk = await handle.read(bytes, total, capacity - total, total);
       if (chunk.bytesRead === 0) break;
       total += chunk.bytesRead;
     }
-    if (total > byteLimit) {
-      const error = new Error(`file exceeds ${byteLimit} byte read limit`);
-      error.code = 'INSPECTION_FILE_TOO_LARGE';
-      throw error;
-    }
+    if (total > before.size) throw new Error('file changed while reading');
 
     const after = await handle.stat({ bigint: true });
     const pathAfter = await lstat(filePath, { bigint: true });
@@ -1897,7 +1917,7 @@ async function setupExpertHandler(args) {
   const snapshot = await projectSummary(projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
   const contractVersion = catalog.frameworkVersion;
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
+  const version = catalog.version;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
   const checks = [
     {
@@ -2015,7 +2035,7 @@ async function rulesEnforcerHandler(args) {
   const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   const hasSnippet = parsed.snippet.trim().length > 0;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
 
@@ -2137,7 +2157,7 @@ async function creativeDirectorHandler(args) {
   const parsed = creativeSchemaParsed.parse(args);
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   return toToolResult(buildCreativePayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
 }
 
@@ -2201,7 +2221,7 @@ async function pageArchitectHandler(args, stage = 'page_architect') {
   const workflowId = parsed.workflowId || randomUUID();
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
   const contractSafe = version.status === 'match' && !provenanceBlock;
 
@@ -2274,7 +2294,7 @@ async function componentSyntaxExpertHandler(args) {
   const parsed = syntaxSchemaParsed.parse(args);
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = resolveAgainstContract(catalog);
   return toToolResult(buildSyntaxPayload(catalog, version, parsed), { ...parsed, projectRoot }, { catalog, version });
 }
 
@@ -2348,9 +2368,9 @@ function buildSyntaxPayload(catalog, version, parsed) {
 
 async function componentCatalogHandler(args) {
   const parsed = catalogSchemaParsed.parse(args);
-  const projectRoot = parsed.projectRoot === undefined ? undefined : path.resolve(parsed.projectRoot);
+  const projectRoot = parsed.projectRoot === undefined ? undefined : authorizedProjectRoot(parsed.projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const version = projectRoot === undefined ? null : await resolveAgainstContract(projectRoot, catalog.frameworkVersion);
+  const version = projectRoot === undefined ? null : resolveAgainstContract(catalog);
   return toToolResult(buildCatalogPayload(catalog, version, parsed), parsed, { catalog, version });
 }
 
@@ -2424,8 +2444,7 @@ async function qualityInspectorHandler(args) {
   const projectRoot = resolveProjectRoot(parsed.projectRoot);
   const fileSummary = summarizeProjectFiles(parsed.files, projectRoot);
   const catalog = await loadGuideCatalog(projectRoot);
-  const contractVersion = catalog.frameworkVersion;
-  const version = await resolveExpressiveVersion({ projectRoot, contractVersion });
+  const version = catalog.version;
   const provenanceBlock = provenanceBlockReason(catalog.provenance.status);
 
   const fileInspection = await findFileViolations(fileSummary.existing, projectRoot);

package/smoke.mjs

@@ -996,6 +996,21 @@ const transport = new StdioClientTransport({
   assert.equal(execFileSync(process.execPath, ['--input-type=module', '-e', "import('./server.js').then(() => console.log('imported'))"], { cwd: packageDir, encoding: 'utf8', timeout: 30_000 }).trim(), 'imported');
 }
 
+{
+  const { redactSensitiveText, readInspectionFile } = await import('./server.js');
+  // Command output is captured up to 160K characters. Redaction must stay linear on long token runs.
+  const startedAt = Date.now();
+  for (const output of ['ab12'.repeat(40_000), 'a-'.repeat(80_000), 'a'.repeat(160_000)]) redactSensitiveText(output);
+  assert.ok(Date.now() - startedAt < 2_000, `redaction took ${Date.now() - startedAt} ms`);
+  const redacted = redactSensitiveText('token eyJhbGciOiJIUzI1.eyJzdWIiOiIxMjM0.SflKxwRJSMeKKF2QT git+https://user:pass@example.com/x');
+  assert.doesNotMatch(redacted, /eyJhbGci|user:pass/u);
+  assert.match(redacted, /git\+https:\/\/\[REDACTED\]@example\.com/u);
+  if (process.platform === 'linux') {
+    // procfs reports size 0 for files with content. A size-bound read must fail, not return a truncated file.
+    await assert.rejects(readInspectionFile('/proc/self/status', '/proc', 1024 * 1024), /changed while reading/u);
+  }
+}
+
 const client = new Client({ name: 'expressivecss-mcp-smoke', version: '0.1.0' });
 
 try {
@@ -1304,6 +1319,7 @@ try {
     },
   });
   assert.ok(boundedRules.structuredContent.issueCount <= 200);
+  assert.equal(boundedRules.content[0].text.includes('\n  '), false, 'tool results are compact JSON');
   assert.ok(boundedRules.structuredContent.blockedChecks.includes('static inspection limit reached'));
 
   const nestedMarkupStartedAt = Date.now();
@@ -2290,6 +2306,52 @@ try {
     await timeoutClient.close();
   }
 
+  const rootsClient = new Client({ name: 'expressivecss-mcp-project-roots-smoke', version: '0.1.0' });
+  try {
+    await rootsClient.connect(new StdioClientTransport({
+      command: process.execPath,
+      args: [path.join(packageDir, 'server.js')],
+      cwd: packageDir,
+      stderr: 'pipe',
+      env: { ...process.env, EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS: outsideDir },
+    }));
+    // A root outside the allowlist must not become a file-existence or hash oracle.
+    for (const [name, args] of [
+      ['quality_inspector', { projectRoot: os.tmpdir(), files: [outsideFile] }],
+      ['component_catalog', { projectRoot: os.tmpdir() }],
+      ['setup_expert', { projectRoot: path.join(outsideDir, 'missing') }],
+    ]) {
+      const denied = await rootsClient.callTool({ name, arguments: args });
+      assert.equal(denied.isError, true, `${name} accepted a root outside the allowlist`);
+      assert.match(denied.content[0].text, /EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS/u);
+    }
+    const allowed = await rootsClient.callTool({ name: 'quality_inspector', arguments: { projectRoot: outsideDir, files: [] } });
+    assert.notEqual(allowed.isError, true, allowed.content[0].text);
+    const defaultRoot = await rootsClient.callTool({ name: 'component_catalog', arguments: {} });
+    assert.notEqual(defaultRoot.isError, true, 'the operator default root needs no allowlist entry');
+  } finally {
+    await rootsClient.close();
+  }
+
+  // Set but empty or invalid allowlists fail closed instead of allowing every root.
+  for (const setting of ['', '[]', '[broken', '[42]']) {
+    const closedClient = new Client({ name: 'expressivecss-mcp-closed-roots-smoke', version: '0.1.0' });
+    try {
+      await closedClient.connect(new StdioClientTransport({
+        command: process.execPath,
+        args: [path.join(packageDir, 'server.js')],
+        cwd: packageDir,
+        stderr: 'pipe',
+        env: { ...process.env, EXPRESSIVECSS_MCP_ALLOWED_PROJECT_ROOTS: setting },
+      }));
+      const denied = await closedClient.callTool({ name: 'quality_inspector', arguments: { projectRoot: outsideDir, files: [outsideFile] } });
+      assert.equal(denied.isError, true, `allowlist ${JSON.stringify(setting)} allowed a client root`);
+      assert.equal(JSON.stringify(denied).includes('sha256'), false);
+    } finally {
+      await closedClient.close();
+    }
+  }
+
   const trapTransport = new StdioClientTransport({
     command: process.execPath,
     args: [path.join(packageDir, 'server.js')],