@pure-ds/core 0.7.4 → 0.7.5

package/.cursorrules

@@ -49,6 +49,27 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 2. Otherwise use workspace root paths (pure-ds development)
 3. Prefer reading actual files over guessing - the data is authoritative
 
+## 🔌 MCP-First Lookup Protocol (Preferred)
+
+If an MCP server named `pure-ds` is available, **use MCP tools first** before generating PDS code.
+
+### Required lookup order
+
+1. **Tokens** → call `get_tokens`
+2. **Primitives / utilities / selectors** → call `find_utility_class`
+3. **Web component API** → call `get_component_api`
+4. **Enhancer metadata + demoHtml** → call `get_enhancer_metadata`
+5. **Design config deterministic mapping** → call `get_config_relations`
+6. **Final snippet sanity check** → call `validate_pds_snippet`
+
+### Non-negotiable rules
+
+- Do not invent class names, tokens, attributes, events, or selectors.
+- If a value is not found in MCP results, state it is unavailable and suggest nearest matches.
+- Prefer MCP results over memory, including examples in this file.
+- If MCP is unavailable, fall back to direct SSoT file reads using the paths above.
+- If neither MCP nor file reads are available, provide only conservative guidance and clearly mark uncertainty.
+
 ---
 
 ## 📋 pds-form Best Practices

package/.github/copilot-instructions.md

@@ -49,6 +49,27 @@ PDS follows the [Pure Web Manifesto](https://pureweb.dev/manifesto): "The browse
 2. Otherwise use workspace root paths (pure-ds development)
 3. Prefer reading actual files over guessing - the data is authoritative
 
+## 🔌 MCP-First Lookup Protocol (Preferred)
+
+If an MCP server named `pure-ds` is available, **use MCP tools first** before generating PDS code.
+
+### Required lookup order
+
+1. **Tokens** → call `get_tokens`
+2. **Primitives / utilities / selectors** → call `find_utility_class`
+3. **Web component API** → call `get_component_api`
+4. **Enhancer metadata + demoHtml** → call `get_enhancer_metadata`
+5. **Design config deterministic mapping** → call `get_config_relations`
+6. **Final snippet sanity check** → call `validate_pds_snippet`
+
+### Non-negotiable rules
+
+- Do not invent class names, tokens, attributes, events, or selectors.
+- If a value is not found in MCP results, state it is unavailable and suggest nearest matches.
+- Prefer MCP results over memory, including examples in this file.
+- If MCP is unavailable, fall back to direct SSoT file reads using the paths above.
+- If neither MCP nor file reads are available, provide only conservative guidance and clearly mark uncertainty.
+
 ---
 
 ## 📋 pds-form Best Practices

package/dist/types/src/js/pds-core/pds-start-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pds-start-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/js/pds-core/pds-start-helpers.js"],"names":[],"mappings":"AAqBA,sEAgCC;AAiBD,mDASC;AA6BD,8CAsBC;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkJC;AAGD;;;;;;;;EAmCC;AAED;;QASC;AAGD;;;;;GA+KC;AA1eM,qDAGI"}
+{"version":3,"file":"pds-start-helpers.d.ts","sourceRoot":"","sources":["../../../../../src/js/pds-core/pds-start-helpers.js"],"names":[],"mappings":"AAqBA,sEAgCC;AAiBD,mDASC;AA6BD,8CAsBC;AAGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkJC;AAGD;;;;;;;;EAmCC;AAED;;QASC;AAGD;;;;;GA2JC;AAtdM,qDAGI"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pure-ds/core",
   "shortname": "pds",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Why develop a Design System when you can generate one?",
   "repository": {
     "type": "git",
@@ -31,8 +31,12 @@
     "pds-build-icons": "packages/pds-cli/bin/pds-build-icons.js",
     "pds-import": "packages/pds-cli/bin/pds-import.js",
     "pds-setup-copilot": "packages/pds-cli/bin/pds-setup-copilot.js",
+    "pds-setup-mcp": "packages/pds-cli/bin/pds-setup-mcp.js",
     "pds-init-config": "packages/pds-cli/bin/pds-init-config.js",
-    "pds-bootstrap": "packages/pds-cli/bin/pds-bootstrap.js"
+    "pds-bootstrap": "packages/pds-cli/bin/pds-bootstrap.js",
+    "pds-mcp-server": "packages/pds-cli/bin/pds-mcp-server.js",
+    "pds-mcp-health": "packages/pds-cli/bin/pds-mcp-health.js",
+    "pds-mcp-eval": "packages/pds-cli/bin/pds-mcp-eval.js"
   },
   "exports": {
     ".": {
@@ -88,6 +92,8 @@
     "pds:css-data": "node packages/pds-cli/bin/generate-css-data.js",
     "pds:import": "node packages/pds-cli/bin/pds-import.js",
     "pds:dx": "node packages/pds-cli/bin/pds-dx.js",
+    "pds:mcp:health": "node packages/pds-cli/bin/pds-mcp-health.js",
+    "pds:mcp:eval": "node packages/pds-cli/bin/pds-mcp-eval.js",
     "storybook:generate": "cd packages/pds-storybook && npm run generate-stories",
     "storybook:dev": "cd packages/pds-storybook && npm run storybook:dev",
     "storybook:build": "cd packages/pds-storybook && npm run storybook:build"

package/packages/pds-cli/bin/pds-bootstrap.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { readFile, writeFile, mkdir, access, rename, rm, copyFile, readdir } from 'fs/promises';
 import { existsSync } from 'fs';

package/packages/pds-cli/bin/pds-import.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { mkdir, readFile, writeFile } from 'fs/promises';
 import path from 'path';

package/packages/pds-cli/bin/pds-mcp-eval.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createPdsMcpContext, runPdsMcpTool } from '../lib/pds-mcp-core.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+async function loadCases(filePath) {
+  const raw = await readFile(filePath, 'utf8');
+  const json = JSON.parse(raw);
+  return Array.isArray(json) ? json : [];
+}
+
+function hasPath(objectValue, dotPath) {
+  if (!dotPath) return true;
+  const parts = dotPath.split('.');
+  let current = objectValue;
+  for (const part of parts) {
+    if (!current || typeof current !== 'object' || !(part in current)) return false;
+    current = current[part];
+  }
+  return true;
+}
+
+async function runCase(ctx, testCase) {
+  const result = await runPdsMcpTool(ctx, testCase.tool, testCase.args || {});
+  const checks = testCase.expect?.paths || [];
+  const failures = checks.filter((checkPath) => !hasPath(result, checkPath));
+  return {
+    id: testCase.id,
+    tool: testCase.tool,
+    pass: failures.length === 0,
+    failures,
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const caseFileArgIndex = args.findIndex((arg) => arg === '--cases');
+  const caseFilePath = caseFileArgIndex > -1
+    ? path.resolve(process.cwd(), args[caseFileArgIndex + 1])
+    : path.resolve(__dirname, '../lib/pds-mcp-eval-cases.json');
+
+  const ctx = createPdsMcpContext({ projectRoot: process.cwd() });
+  const cases = await loadCases(caseFilePath);
+  if (cases.length === 0) {
+    console.error('No evaluation cases found.');
+    process.exit(1);
+  }
+
+  const results = [];
+  for (const testCase of cases) {
+    // eslint-disable-next-line no-await-in-loop
+    const outcome = await runCase(ctx, testCase);
+    results.push(outcome);
+  }
+
+  const passed = results.filter((r) => r.pass).length;
+  const failed = results.length - passed;
+
+  console.log(`PDS MCP Eval (${results.length} cases)`);
+  console.log(`Passed: ${passed}`);
+  console.log(`Failed: ${failed}`);
+
+  if (failed > 0) {
+    console.log('');
+    for (const result of results.filter((r) => !r.pass)) {
+      console.log(`- ${result.id} (${result.tool}) failed checks: ${result.failures.join(', ')}`);
+    }
+    process.exit(2);
+  }
+}
+
+main().catch((error) => {
+  console.error('MCP eval failed:', error?.message || error);
+  process.exit(1);
+});

package/packages/pds-cli/bin/pds-mcp-health.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+
+const requiredTools = [
+  'get_tokens',
+  'find_utility_class',
+  'get_component_api',
+  'get_enhancer_metadata',
+  'get_config_relations',
+  'validate_pds_snippet',
+];
+
+function frame(message) {
+  const body = Buffer.from(JSON.stringify(message), 'utf8');
+  return Buffer.concat([
+    Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8'),
+    body,
+  ]);
+}
+
+function parseFrames(state, chunk, onMessage) {
+  state.buffer = Buffer.concat([state.buffer, chunk]);
+  while (true) {
+    const separator = Buffer.from('\r\n\r\n', 'utf8');
+    const headerEnd = state.buffer.indexOf(separator);
+    if (headerEnd === -1) return;
+
+    const header = state.buffer.slice(0, headerEnd).toString('utf8');
+    const contentLengthMatch = header.match(/Content-Length:\s*(\d+)/i);
+    if (!contentLengthMatch) {
+      state.buffer = Buffer.alloc(0);
+      return;
+    }
+
+    const contentLength = Number(contentLengthMatch[1]);
+    const bodyStart = headerEnd + separator.length;
+    const bodyEnd = bodyStart + contentLength;
+    if (state.buffer.length < bodyEnd) return;
+
+    const body = state.buffer.slice(bodyStart, bodyEnd).toString('utf8');
+    state.buffer = state.buffer.slice(bodyEnd);
+
+    try {
+      onMessage(JSON.parse(body));
+    } catch {
+      // Ignore malformed JSON frame and continue.
+    }
+  }
+}
+
+async function runHealthCheck() {
+  const child = spawn(process.execPath, ['./packages/pds-cli/bin/pds-mcp-server.js'], {
+    cwd: process.cwd(),
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  const state = { buffer: Buffer.alloc(0) };
+  let initialized = false;
+
+  const timer = setTimeout(() => {
+    console.error('❌ MCP health check timed out while waiting for server responses.');
+    child.kill();
+    process.exit(2);
+  }, 8000);
+
+  child.stderr.on('data', (data) => {
+    const text = String(data || '').trim();
+    if (text) {
+      console.error(`MCP server stderr: ${text}`);
+    }
+  });
+
+  child.stdout.on('data', (chunk) => {
+    parseFrames(state, chunk, (message) => {
+      if (message.id === 1 && message.result?.serverInfo?.name) {
+        initialized = true;
+        child.stdin.write(frame({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }));
+        return;
+      }
+
+      if (message.id === 2 && Array.isArray(message.result?.tools)) {
+        const toolNames = message.result.tools.map((tool) => tool.name).filter(Boolean);
+        const missingTools = requiredTools.filter((toolName) => !toolNames.includes(toolName));
+
+        if (missingTools.length > 0) {
+          console.error('❌ MCP server is reachable but missing required tools:');
+          missingTools.forEach((toolName) => console.error(`   - ${toolName}`));
+          clearTimeout(timer);
+          child.kill();
+          process.exit(3);
+        }
+
+        console.log('✅ PDS MCP health check passed');
+        console.log(`   Server: ${message.result?.serverInfo?.name || 'pds-ssoT'}`);
+        console.log(`   Tools: ${toolNames.sort().join(', ')}`);
+        clearTimeout(timer);
+        child.kill();
+        process.exit(0);
+      }
+    });
+  });
+
+  child.on('exit', (code) => {
+    if (!initialized) {
+      clearTimeout(timer);
+      process.exit(code || 1);
+    }
+  });
+
+  child.stdin.write(
+    frame({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'pds-mcp-health', version: '1.0.0' },
+      },
+    })
+  );
+}
+
+runHealthCheck().catch((error) => {
+  console.error('❌ MCP health check failed:', error?.message || error);
+  process.exit(1);
+});

package/packages/pds-cli/bin/pds-mcp-server.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+import { createPdsMcpContext, getPdsMcpTools, runPdsMcpTool } from '../lib/pds-mcp-core.js';
+
+const SERVER_NAME = 'pds-ssoT';
+const SERVER_VERSION = '0.1.0';
+const PROTOCOL_VERSION = '2024-11-05';
+
+const ctx = createPdsMcpContext({ projectRoot: process.cwd() });
+const tools = getPdsMcpTools();
+
+let inputBuffer = Buffer.alloc(0);
+
+function writeMessage(payload) {
+  const body = Buffer.from(JSON.stringify(payload), 'utf8');
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8');
+  process.stdout.write(Buffer.concat([header, body]));
+}
+
+function sendResponse(id, result) {
+  writeMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id, code, message, data) {
+  writeMessage({
+    jsonrpc: '2.0',
+    id,
+    error: { code, message, data },
+  });
+}
+
+async function handleMessage(message) {
+  const { id, method, params } = message || {};
+
+  try {
+    if (method === 'initialize') {
+      return sendResponse(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: SERVER_NAME,
+          version: SERVER_VERSION,
+        },
+      });
+    }
+
+    if (method === 'notifications/initialized' || method === 'initialized') {
+      return;
+    }
+
+    if (method === 'ping') {
+      return sendResponse(id, {});
+    }
+
+    if (method === 'tools/list') {
+      return sendResponse(id, { tools });
+    }
+
+    if (method === 'tools/call') {
+      const toolName = params?.name;
+      const args = params?.arguments || {};
+      const data = await runPdsMcpTool(ctx, toolName, args);
+      return sendResponse(id, {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(data, null, 2),
+          },
+        ],
+      });
+    }
+
+    if (method === 'prompts/list') {
+      return sendResponse(id, { prompts: [] });
+    }
+
+    if (method === 'resources/list') {
+      return sendResponse(id, { resources: [] });
+    }
+
+    if (typeof id !== 'undefined') {
+      return sendError(id, -32601, `Method not found: ${method}`);
+    }
+  } catch (error) {
+    if (typeof id !== 'undefined') {
+      return sendError(id, -32000, error?.message || 'Unhandled server error', {
+        stack: error?.stack || '',
+      });
+    }
+  }
+}
+
+function tryReadFrame() {
+  const separator = Buffer.from('\r\n\r\n', 'utf8');
+  const headerEnd = inputBuffer.indexOf(separator);
+  if (headerEnd === -1) return false;
+
+  const header = inputBuffer.slice(0, headerEnd).toString('utf8');
+  const contentLengthMatch = header.match(/Content-Length:\s*(\d+)/i);
+  if (!contentLengthMatch) {
+    inputBuffer = Buffer.alloc(0);
+    return false;
+  }
+
+  const contentLength = Number(contentLengthMatch[1]);
+  const bodyStart = headerEnd + separator.length;
+  const bodyEnd = bodyStart + contentLength;
+  if (inputBuffer.length < bodyEnd) return false;
+
+  const body = inputBuffer.slice(bodyStart, bodyEnd).toString('utf8');
+  inputBuffer = inputBuffer.slice(bodyEnd);
+
+  let message;
+  try {
+    message = JSON.parse(body);
+  } catch {
+    return true;
+  }
+
+  handleMessage(message);
+  return true;
+}
+
+process.stdin.on('data', (chunk) => {
+  inputBuffer = Buffer.concat([inputBuffer, chunk]);
+  while (tryReadFrame()) {
+    // Parse all complete frames currently in the input buffer.
+  }
+});
+
+process.stdin.on('error', () => {
+  process.exit(1);
+});
+
+process.on('uncaughtException', (error) => {
+  const text = error?.stack || error?.message || String(error);
+  process.stderr.write(`[pds-mcp-server] uncaughtException: ${text}\n`);
+});

package/packages/pds-cli/bin/pds-setup-mcp.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { mkdir, readFile, writeFile, access } from 'fs/promises';
+import path from 'path';
+
+const projectRoot = process.cwd();
+const serverCommand = 'node';
+const serverArgs = ['./node_modules/@pure-ds/core/packages/pds-cli/bin/pds-mcp-server.js'];
+
+async function readJsonIfExists(filePath) {
+  try {
+    await access(filePath);
+    const text = await readFile(filePath, 'utf8');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+async function setupVSCodeConfig() {
+  const configPath = path.join(projectRoot, '.vscode', 'mcp.json');
+  const current = (await readJsonIfExists(configPath)) || {};
+
+  const servers = current.servers && typeof current.servers === 'object' ? current.servers : {};
+  servers['pure-ds'] = {
+    type: 'stdio',
+    command: serverCommand,
+    args: serverArgs,
+  };
+
+  await writeJson(configPath, { ...current, servers });
+  return configPath;
+}
+
+async function setupCursorConfig() {
+  const configPath = path.join(projectRoot, '.cursor', 'mcp.json');
+  const current = (await readJsonIfExists(configPath)) || {};
+
+  const mcpServers = current.mcpServers && typeof current.mcpServers === 'object' ? current.mcpServers : {};
+  mcpServers['pure-ds'] = {
+    command: serverCommand,
+    args: serverArgs,
+  };
+
+  await writeJson(configPath, { ...current, mcpServers });
+  return configPath;
+}
+
+async function main() {
+  console.log('🔌 Setting up local PDS MCP server configuration...');
+
+  const [vscodePath, cursorPath] = await Promise.all([
+    setupVSCodeConfig(),
+    setupCursorConfig(),
+  ]);
+
+  console.log('✅ MCP configuration updated');
+  console.log(`   • VS Code: ${path.relative(projectRoot, vscodePath)}`);
+  console.log(`   • Cursor: ${path.relative(projectRoot, cursorPath)}`);
+  console.log('');
+  console.log('ℹ️  Restart your AI extension/IDE so it re-reads MCP server config.');
+}
+
+main().catch((error) => {
+  console.error('❌ Failed to set up MCP:', error?.message || error);
+  process.exit(1);
+});