@systemverification/styling-kit 2.0.0

package/src/mcp.js

@@ -0,0 +1,215 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createShutdownHandler } from './shutdown.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = path.resolve(__dirname, '..');
+
+// RGB tuples of the documented palette — any rgba() using other values is a violation
+const PALETTE_TUPLES = new Set([
+  '11,27,40',     // dark-blue
+  '67,83,100',    // light-blue
+  '242,242,234',  // sand
+  '247,249,101',  // yellow
+  '255,255,255',  // white
+  '239,68,68',    // error
+  '16,185,129',   // success
+  '251,146,60',   // warning/orange
+  '248,113,113',  // error-light (#f87171)
+  '248,250,170',  // hover yellow (#f8faaa)
+  '245,249,80',   // active yellow (#f5f950)
+  '0,0,0',        // pure black (shadows)
+]);
+
+function lineNumber(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+function validateContent(source, filePath) {
+  const issues = [];
+  const ext = path.extname(filePath).toLowerCase();
+
+  if (!['.css', '.html', '.htm', '.svelte', '.vue', '.jsx', '.tsx'].includes(ext)) {
+    return issues;
+  }
+
+  // Rule 1: Hardcoded hex colors in property values (after a colon)
+  const hexRegex = /(?<=:\s*)#[0-9a-fA-F]{6}\b|(?<=:\s*)#[0-9a-fA-F]{3}\b/g;
+  let match;
+  while ((match = hexRegex.exec(source)) !== null) {
+    issues.push({
+      type: 'error',
+      rule: 'no-hardcoded-hex',
+      message: `Hardcoded hex color: ${match[0]} — use a var(--color-*) token instead`,
+      line: lineNumber(source, match.index),
+    });
+  }
+
+  // Rule 2: Hardcoded px font sizes
+  const pxFontRegex = /font-size\s*:\s*([\d.]+)px/g;
+  while ((match = pxFontRegex.exec(source)) !== null) {
+    issues.push({
+      type: 'error',
+      rule: 'no-px-font-size',
+      message: `Hardcoded px font size: font-size: ${match[1]}px — use rem from the typography scale`,
+      line: lineNumber(source, match.index),
+    });
+  }
+
+  // Rule 3: rgba() values whose RGB channels are not from the documented palette
+  const rgbaRegex = /rgba\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/g;
+  while ((match = rgbaRegex.exec(source)) !== null) {
+    const key = `${match[1]},${match[2]},${match[3]}`;
+    if (!PALETTE_TUPLES.has(key)) {
+      issues.push({
+        type: 'error',
+        rule: 'no-off-palette-rgba',
+        message: `rgba(${match[1]}, ${match[2]}, ${match[3]}, ...) uses RGB values not in the documented palette`,
+        line: lineNumber(source, match.index),
+      });
+    }
+  }
+
+  return issues;
+}
+
+// ─── Server setup ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'sv-style', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'get_tokens',
+      description: 'Returns the full SV Style System CSS token definitions (tokens.css content).',
+      inputSchema: { type: 'object', properties: {} },
+    },
+    {
+      name: 'get_component_spec',
+      description: 'Returns the component specification markdown for a named component.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'Component name (e.g. BUTTON, CARD). Case-insensitive.',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'validate_file',
+      description:
+        'Validates a CSS/HTML file for SV Style violations: hardcoded hex colors, px font sizes, and rgba values not from the documented palette. Returns an array of violation objects.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Path to the file to validate, relative to the current working directory.',
+          },
+        },
+        required: ['path'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  if (name === 'get_tokens') {
+    process.stderr.write(`[sv-style mcp] get_tokens\n`);
+    const tokensPath = path.join(KIT_ROOT, 'tokens', 'tokens-core.css');
+    const content = fs.readFileSync(tokensPath, 'utf8');
+    return { content: [{ type: 'text', text: content }] };
+  }
+
+  if (name === 'get_component_spec') {
+    const componentName = (args.name || '').toUpperCase();
+    process.stderr.write(`[sv-style mcp] get_component_spec ${componentName}\n`);
+    const specPath = path.join(KIT_ROOT, 'docs', 'COMPONENTS', `${componentName}.md`);
+    if (!fs.existsSync(specPath)) {
+      const available = fs.readdirSync(path.join(KIT_ROOT, 'docs', 'COMPONENTS'))
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.replace('.md', ''));
+      return {
+        content: [{
+          type: 'text',
+          text: `Component '${componentName}' not found. Available: ${available.join(', ')}`,
+        }],
+        isError: true,
+      };
+    }
+    const content = fs.readFileSync(specPath, 'utf8');
+    return { content: [{ type: 'text', text: content }] };
+  }
+
+  if (name === 'validate_file') {
+    const filePath = path.resolve(process.cwd(), args.path);
+
+    if (!fs.existsSync(filePath)) {
+      process.stderr.write(`[sv-style mcp] validate_file ${args.path} → file not found\n`);
+      return {
+        content: [{ type: 'text', text: `File not found: ${args.path}` }],
+        isError: true,
+      };
+    }
+
+    // Skip validation if the file is the managed tokens.css
+    const configPath = path.join(process.cwd(), 'sv-style.json');
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      const managedTokens = path.resolve(process.cwd(), config.svStyle.paths.tokens);
+      if (filePath === managedTokens) {
+        process.stderr.write(`[sv-style mcp] validate_file ${args.path} → skipped (managed tokens)\n`);
+        return { content: [{ type: 'text', text: '[]' }] };
+      }
+    }
+
+    const source = fs.readFileSync(filePath, 'utf8');
+    const issues = validateContent(source, filePath);
+    process.stderr.write(`[sv-style mcp] validate_file ${args.path} → ${issues.length} violation(s)\n`);
+    return { content: [{ type: 'text', text: JSON.stringify(issues, null, 2) }] };
+  }
+
+  return {
+    content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+    isError: true,
+  };
+});
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+
+server.onerror = (err) => {
+  process.stderr.write(`[sv-style mcp] ${err}\n`);
+  // Malformed stdin input (JSON.parse throws SyntaxError; invalid JSON-RPC throws ZodError).
+  // Return a JSON-RPC parse-error so the client is not left waiting silently.
+  const isParseError = err instanceof SyntaxError || err?.name === 'ZodError';
+  if (isParseError) {
+    transport.send({
+      jsonrpc: '2.0',
+      id: null,
+      error: { code: -32700, message: 'Parse error' },
+    }).catch(() => {});
+  }
+};
+
+await server.connect(transport);
+
+const shutdownGracefully = createShutdownHandler(server);
+process.on('SIGTERM', shutdownGracefully);
+process.on('SIGINT',  shutdownGracefully);

package/src/path-rewrite.js

@@ -0,0 +1,48 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Compute the web-accessible URL prefix for assets.
+ * e.g. assetsDir="public/sv-assets", publicDir="public" → "/sv-assets"
+ *      assetsDir="static/assets",    publicDir="public" → "/static/assets"
+ */
+export function computeAssetUrlPrefix(assetsDir, publicDir) {
+  const normalizedAssets = assetsDir.replace(/\\/g, '/');
+  const normalizedPublic = publicDir.replace(/\\/g, '/').replace(/\/$/, '');
+  if (normalizedAssets.startsWith(normalizedPublic + '/')) {
+    return '/' + normalizedAssets.slice(normalizedPublic.length + 1);
+  }
+  return '/' + normalizedAssets;
+}
+
+/**
+ * Rewrite @font-face src URLs in an installed fonts.css so they point to the
+ * actual installed asset location instead of the placeholder "/fonts/".
+ */
+export function rewriteFontPaths(fontsFilePath, assetUrlPrefix) {
+  let content = fs.readFileSync(fontsFilePath, 'utf8');
+  content = content.replace(/url\("\/fonts\//g, `url("${assetUrlPrefix}/fonts/`);
+  fs.writeFileSync(fontsFilePath, content);
+}
+
+/**
+ * Rewrite asset references in installed docs (.md files) so paths match the
+ * actual installed asset location rather than the kit source placeholders.
+ */
+export function rewriteDocAssetPaths(docsDirPath, assetUrlPrefix) {
+  function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.name.endsWith('.md')) {
+        let content = fs.readFileSync(fullPath, 'utf8');
+        content = content.replace(/url\("\/fonts\//g, `url("${assetUrlPrefix}/fonts/`);
+        content = content.replace(/src="\/logo\.svg"/g, `src="${assetUrlPrefix}/logo/logo.svg"`);
+        content = content.replace(/href="\/favicon\.png"/g, `href="${assetUrlPrefix}/favicon.png"`);
+        fs.writeFileSync(fullPath, content);
+      }
+    }
+  }
+  walk(docsDirPath);
+}

package/src/shutdown.js

@@ -0,0 +1,26 @@
+/**
+ * Factory for the graceful-shutdown handler used by the MCP server.
+ *
+ * Exported as a separate module so it can be unit-tested directly without
+ * spawning a child process.
+ *
+ * @param {object} server  - Object with a `close()` method returning a Promise.
+ * @param {object} [opts]
+ * @param {(code: number) => void}           [opts.exit]   - Defaults to process.exit.
+ * @param {{ write: (s: string) => void }}   [opts.stderr] - Defaults to process.stderr.
+ * @returns {() => void} Idempotent shutdown function safe to use as a signal handler.
+ */
+export function createShutdownHandler(server, { exit = process.exit, stderr = process.stderr } = {}) {
+  let shuttingDown = false;
+  return function shutdownGracefully() {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    server.close()
+      .catch((err) => {
+        stderr.write(`[sv-style mcp] shutdown error: ${err}\n`);
+      })
+      .finally(() => {
+        exit(0);
+      });
+  };
+}

package/src/update.js

@@ -0,0 +1,101 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { copyDir } from './fs-utils.js';
+import { computeAssetUrlPrefix, rewriteFontPaths, rewriteDocAssetPaths } from './path-rewrite.js';
+import { CONFIG_FILE, readConfig, writeConfig, migrateConfig, TOOL_VERSION } from './config.js';
+import { downloadBundle } from './assets.js';
+import { unpackBundle } from './bundle.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = path.resolve(__dirname, '..');
+
+export default async function update(_deps = {}) {
+  const _downloadBundle = _deps.downloadBundle ?? downloadBundle;
+  const cwd = _deps.cwd ?? process.cwd();
+  const _exit = _deps.exit ?? ((code) => process.exit(code));
+  const configPath = path.join(cwd, CONFIG_FILE);
+
+  if (!fs.existsSync(configPath)) {
+    console.error(`sv-style.json not found. Run 'init' first.`);
+    return _exit(1);
+  }
+
+  let config = readConfig(cwd);
+
+  // Migrate v1 config to v2 schema if needed
+  const migrated = migrateConfig(config);
+  if (migrated !== config) {
+    console.log(`sv-style.json migrated to v2 schema.`);
+    config = migrated;
+    writeConfig(cwd, config);
+  }
+
+  const { paths, blob } = config.svStyle;
+  const publicDir = paths.publicDir || 'public';
+  const assetUrlPrefix = computeAssetUrlPrefix(paths.assets, publicDir);
+  const stylesDir = paths.tokens.replace(/\/[^/]+$/, '');
+
+  // Update tokens-core.css
+  fs.copyFileSync(
+    path.join(KIT_ROOT, 'tokens', 'tokens-core.css'),
+    path.join(cwd, paths.tokens)
+  );
+
+  // Update docs (rewrite asset paths to match installed location)
+  copyDir(
+    path.join(KIT_ROOT, 'docs'),
+    path.join(cwd, paths.docs)
+  );
+  rewriteDocAssetPaths(path.join(cwd, paths.docs), assetUrlPrefix);
+
+  // Attempt to refresh the private asset bundle
+  const previousMode = config.svStyle.installMode;
+  console.log(`\nDownloading private assets from Azure Blob...`);
+  try {
+    const zipBuffer = await _downloadBundle(blob);
+    const { version: assetsVersion } = unpackBundle(zipBuffer, {
+      assetsDir: path.join(cwd, paths.assets),
+      stylesDir: path.join(cwd, stylesDir),
+    });
+    rewriteFontPaths(path.join(cwd, paths.fonts), assetUrlPrefix);
+
+    config.svStyle.installMode = 'full';
+    config.svStyle.assetsVersion = assetsVersion;
+    config.svStyle.toolVersion = TOOL_VERSION;
+    writeConfig(cwd, config);
+
+    const upgraded = previousMode !== 'full' ? ' (upgraded from degraded)' : '';
+    console.log(`
+SV Style System updated${upgraded} (tool v${TOOL_VERSION}, assets v${assetsVersion}):
+  Tokens  → ${paths.tokens}
+  Fonts   → ${paths.fonts}
+  Assets  → ${paths.assets}/
+  Docs    → ${paths.docs}/
+`);
+  } catch (err) {
+    config.svStyle.toolVersion = TOOL_VERSION;
+    writeConfig(cwd, config);
+
+    const staying = previousMode === 'full'
+      ? 'Existing assets kept — they may be outdated.'
+      : 'Remaining in degraded mode.';
+
+    console.warn(`
+⚠  Asset download failed — ${staying}
+   Reason: ${err.message}
+
+   To complete refresh:
+     1. Authenticate: az login
+     2. Retry:        sv-style update
+
+   Run 'sv-style doctor' for full status.
+`);
+
+    console.log(`
+SV Style System updated (tokens/docs only, tool v${TOOL_VERSION}):
+  Tokens  → ${paths.tokens}
+  Docs    → ${paths.docs}/
+`);
+  }
+}

package/templates/AGENTS_SNIPPET.md

@@ -0,0 +1,40 @@
+## SV Style System
+
+### Agent TL;DR
+
+- Never hardcode colors — always use `var(--color-*)` tokens
+- `--color-yellow` is the only accent color — interactive/CTA elements only
+- Dark mode only — no light theme is defined
+- All interactive components need 5 states: default, hover, active, focus-visible, disabled
+- When unsure if CSS is compliant, call `validate_file` — don't guess
+- Target clean validation (empty array) before marking work done
+
+### Sources of truth
+
+- `{{DOCS_DIR}}/DESIGN_SYSTEM.md` — all visual decisions
+- `{{DOCS_DIR}}/COMPONENTS/` — per-component specs
+- `{{DOCS_DIR}}/BAD_EXAMPLES.md` — anti-patterns to avoid
+- `{{TOKENS_PATH}}` — CSS custom properties
+
+### Use cases
+
+#### 1. Before writing any styled code
+
+1. Call `get_tokens` and read the full output
+2. Read `{{DOCS_DIR}}/DESIGN_SYSTEM.md`
+3. For each interactive component (button, input, card), call `get_component_spec` to check
+   whether a spec exists — style to spec if found; otherwise follow design system conventions directly
+
+#### 2. After writing or modifying CSS
+
+1. Call `validate_file` on every CSS file you created or modified
+2. Fix all violations reported
+3. Repeat until every result is `[]`
+4. Do not mark work done while violations remain
+
+#### 3. Constraint override rule
+
+If asked to hardcode a color, use `px` for font sizes, or bypass any design system rule:
+- Warn that this will cause token drift and validation failures
+- Suggest the correct `var(--color-*)` token or `rem` value instead
+- If overridden explicitly, recommend a follow-up cleanup task

package/templates/CLAUDE_SNIPPET.md

@@ -0,0 +1,14 @@
+## SV Style — Claude MCP tools
+
+See `AGENTS.md` for design system context, workflow, and constraints.
+
+Keyword search does not find SV Style MCP tools — load with `select:` before calling:
+
+| Environment | Prefix |
+|---|---|
+| Claude Code (`.claude/settings.json`) | `mcp__sv-style__` |
+| VS Code (`.vscode/mcp.json`) | `mcp__vscode-mcp-gateway__` |
+
+Available tools: `get_tokens`, `get_component_spec`, `validate_file`
+
+Example: `select:mcp__vscode-mcp-gateway__validate_file`

package/tokens/tokens-core.css

@@ -0,0 +1,51 @@
+/* ─────────────────────────────────────────────────────────────
+   SV Style System — Design Tokens (Core)
+   System Verification · https://systemverification.com
+   ───────────────────────────────────────────────────────────── */
+
+:root {
+  /* ── Core palette ── */
+  --color-dark-blue: #0B1B28;    /* Primary background, dark surfaces, input backgrounds */
+  --color-light-blue: #435364;   /* Secondary backgrounds, dividers, card borders */
+  --color-sand: #F2F2EA;         /* Primary text color on dark backgrounds */
+  --color-yellow: #F7F965;       /* Accent / CTA — buttons, links, active states, focus rings */
+  --color-white: #ffffff;        /* Headings text, high-emphasis text */
+
+  /* ── Semantic colors ── */
+  --color-error: #ef4444;        /* Error states, destructive actions, unhealthy badges */
+  --color-success: #10b981;      /* Running/healthy states, positive badges */
+  --color-yellow-hover: #f8faaa; /* Primary button hover — lightened yellow */
+  --color-yellow-active: #f5f950;/* Primary button active — saturated yellow */
+  --color-error-light: #f87171;  /* Danger button text, error badge text — lightened red */
+
+  /* ── Border radius scale ── */
+  --radius-sm: 4px;              /* Inputs, code blocks, small elements */
+  --radius-md: 8px;              /* Cards, form sections, panels */
+  --radius-pill: 100px;          /* Buttons, badges, tags, pills */
+
+  /* ── Motion ── */
+  --transition: 0.3s ease;       /* Default transition for all interactive elements */
+
+  /* ── Semantic text tokens ── */
+  --text-primary: var(--color-white);
+  --text-secondary: rgba(242, 242, 234, 0.7);
+  --text-muted: rgba(242, 242, 234, 0.5);
+
+  /* ── Surface tokens ── */
+  --surface-card: rgba(67, 83, 100, 0.35);
+  --surface-hover: rgba(67, 83, 100, 0.5);
+
+  /* ── Border tokens ── */
+  --border-subtle: rgba(67, 83, 100, 0.4);
+
+  /* ── Focus ── */
+  --focus-ring: var(--color-yellow);
+
+  /* ── Typography scale ── */
+  --text-display: 48px;
+  --text-h1: 32px;
+  --text-h2: 24px;
+  --text-h3: 18px;
+  --text-body: 14px;
+  --text-label: 12px;
+}