release: staging → main (16 features, 4 epics)

build

@@ -0,0 +1 @@
+/Volumes/Development/booked/helixir/build

node_modules

@@ -0,0 +1 @@
+/Volumes/Development/booked/helixir/node_modules

package.json

@@ -36,6 +36,7 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "type-check": "tsc --noEmit",
+    "typecheck": "pnpm run type-check",
     "lint": "eslint src packages/core/src",
     "lint:fix": "eslint src packages/core/src --fix",
     "format": "prettier --write .",

packages/core/package.json

@@ -16,7 +16,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^3.22.0"
   },
   "peerDependencies": {

packages/core/src/config.ts

@@ -32,7 +32,6 @@ const defaults: McpWcConfig = {
 };
 
 function readConfigFile(projectRoot: string): Partial<McpWcConfig> {
-  // Primary config file name
   const primaryPath = resolve(projectRoot, 'helixir.mcp.json');
   if (existsSync(primaryPath)) {
     try {
@@ -44,21 +43,6 @@ function readConfigFile(projectRoot: string): Partial<McpWcConfig> {
     }
   }
 
-  // Backward-compatible fallback to legacy config file name
-  const legacyPath = resolve(projectRoot, 'mcpwc.config.json');
-  if (existsSync(legacyPath)) {
-    process.stderr.write(
-      `[helixir] Warning: mcpwc.config.json is deprecated. Rename to helixir.mcp.json.\n`,
-    );
-    try {
-      const raw = readFileSync(legacyPath, 'utf-8');
-      return JSON.parse(raw) as Partial<McpWcConfig>;
-    } catch {
-      process.stderr.write(`[helixir] Warning: mcpwc.config.json is malformed. Using defaults.\n`);
-      return {};
-    }
-  }
-
   return {};
 }
 
@@ -92,36 +76,32 @@ export function loadConfig(): Readonly<McpWcConfig> {
   }
 
   // Apply env vars (highest priority)
-  if (process.env['MCP_WC_CEM_PATH'] !== undefined) {
-    config.cemPath = process.env['MCP_WC_CEM_PATH'];
-  }
-  if (process.env['MCP_WC_PROJECT_ROOT'] !== undefined) {
-    config.projectRoot = process.env['MCP_WC_PROJECT_ROOT'];
-  }
-  if (process.env['MCP_WC_COMPONENT_PREFIX'] !== undefined) {
-    config.componentPrefix = process.env['MCP_WC_COMPONENT_PREFIX'];
-  }
-  if (process.env['MCP_WC_HEALTH_HISTORY_DIR'] !== undefined) {
-    config.healthHistoryDir = process.env['MCP_WC_HEALTH_HISTORY_DIR'];
-  }
-  if (process.env['MCP_WC_TSCONFIG_PATH'] !== undefined) {
-    config.tsconfigPath = process.env['MCP_WC_TSCONFIG_PATH'];
-  }
-  if (process.env['MCP_WC_TOKENS_PATH'] !== undefined) {
-    const val = process.env['MCP_WC_TOKENS_PATH'];
-    config.tokensPath = val === 'null' ? null : val;
-  }
-  if (process.env['MCP_WC_CDN_BASE'] !== undefined) {
-    const val = process.env['MCP_WC_CDN_BASE'];
-    config.cdnBase = val === 'null' ? null : val;
-  }
-  if (process.env['MCP_WC_CDN_AUTOLOADER'] !== undefined) {
-    const val = process.env['MCP_WC_CDN_AUTOLOADER'];
-    config.cdnAutoloader = val === 'null' ? null : val;
+  // String keys map directly; nullable keys treat the literal string 'null' as null.
+  const ENV_MAP_STRING: Readonly<Record<string, keyof McpWcConfigMutable>> = {
+    MCP_WC_CEM_PATH: 'cemPath',
+    MCP_WC_PROJECT_ROOT: 'projectRoot',
+    MCP_WC_COMPONENT_PREFIX: 'componentPrefix',
+    MCP_WC_HEALTH_HISTORY_DIR: 'healthHistoryDir',
+    MCP_WC_TSCONFIG_PATH: 'tsconfigPath',
+  };
+  const ENV_MAP_NULLABLE: Readonly<Record<string, keyof McpWcConfigMutable>> = {
+    MCP_WC_TOKENS_PATH: 'tokensPath',
+    MCP_WC_CDN_BASE: 'cdnBase',
+    MCP_WC_CDN_AUTOLOADER: 'cdnAutoloader',
+    MCP_WC_CDN_STYLESHEET: 'cdnStylesheet',
+  };
+
+  for (const [envKey, configKey] of Object.entries(ENV_MAP_STRING)) {
+    const val = process.env[envKey];
+    if (val !== undefined) {
+      (config as Record<string, unknown>)[configKey] = val;
+    }
   }
-  if (process.env['MCP_WC_CDN_STYLESHEET'] !== undefined) {
-    const val = process.env['MCP_WC_CDN_STYLESHEET'];
-    config.cdnStylesheet = val === 'null' ? null : val;
+  for (const [envKey, configKey] of Object.entries(ENV_MAP_NULLABLE)) {
+    const val = process.env[envKey];
+    if (val !== undefined) {
+      (config as Record<string, unknown>)[configKey] = val === 'null' ? null : val;
+    }
   }
 
   // --watch CLI flag overrides config file value

packages/core/src/handlers/cem.ts

@@ -725,7 +725,10 @@ export function findComponentsByToken(
   cem: Cem,
 ): FindComponentsByTokenResult {
   if (!token.startsWith('--')) {
-    throw new Error(`CSS custom property name must start with "--": "${token}"`);
+    throw new MCPError(
+      `CSS custom property name must start with "--": "${token}"`,
+      ErrorCategory.VALIDATION,
+    );
   }
 
   const components: TokenComponentMatch[] = [];

packages/core/src/handlers/dependencies.ts

@@ -1,4 +1,5 @@
 import type { Cem } from './cem.js';
+import { MCPError, ErrorCategory } from '../shared/error-handling.js';
 
 export interface ComponentDependencyResult {
   tagName: string;
@@ -105,7 +106,7 @@ export function getComponentDependencies(
   }
 
   if (!found) {
-    throw new Error(`Component "${tagName}" not found in CEM.`);
+    throw new MCPError(`Component "${tagName}" not found in CEM.`, ErrorCategory.NOT_FOUND);
   }
 
   const depMap = buildDependencyMap(cem);

packages/core/src/handlers/extend.ts

@@ -1,4 +1,5 @@
 import type { Cem, CemDeclaration } from './cem.js';
+import { MCPError, ErrorCategory } from '../shared/error-handling.js';
 
 // --- Helpers ---
 
@@ -66,7 +67,7 @@ export function extendComponent(
 ): ExtendComponentResult {
   const parentDecl = findDeclaration(cem, parentTagName);
   if (!parentDecl) {
-    throw new Error(`Component "${parentTagName}" not found in CEM.`);
+    throw new MCPError(`Component "${parentTagName}" not found in CEM.`, ErrorCategory.NOT_FOUND);
   }
 
   const parentClassName = tagNameToClassName(parentTagName);

packages/core/src/handlers/theme.ts

@@ -145,7 +145,7 @@ function lightPlaceholder(tokenName: string, category: string): string {
       return '200ms';
 
     default:
-      return '/* TODO: set value */';
+      return `var(${tokenName})`;
   }
 }
 

packages/mcp/package.json

@@ -46,7 +46,7 @@
   "homepage": "https://github.com/bookedsolidtech/helixir/tree/main/packages/mcp#readme",
   "peerDependencies": {
     "helixir": ">=0.5.0",
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^3.22.0"
   },
   "devDependencies": {

packages/vscode/.vscodeignore

@@ -0,0 +1,30 @@
+# Source files — not needed in the packaged extension
+src/
+tsconfig.json
+esbuild.config.mjs
+
+# Development dependencies and lock files
+node_modules/
+.pnpm-store/
+pnpm-lock.yaml
+package-lock.json
+
+# Test artefacts
+coverage/
+*.test.ts
+*.spec.ts
+
+# Build intermediates (keep dist/)
+*.map
+
+# Editor and OS artefacts
+.vscode/
+.DS_Store
+*.log
+
+# Root-level workspace files that should not be bundled
+../../node_modules/
+../../src/
+../../build/
+../../packages/
+../../.github/

packages/vscode/README.md

@@ -0,0 +1,84 @@
+# Helixir — VS Code Extension
+
+**AI-powered web component intelligence for VS Code.**
+
+Helixir gives AI assistants full situational awareness of any web component library by wiring the [helixir MCP server](https://github.com/bookedsolidtech/helixir) directly into VS Code's MCP layer.
+
+## Features
+
+- **MCP server auto-registration** — the helixir MCP server starts automatically with VS Code, no manual configuration required
+- **30+ MCP tools** — component discovery, health scoring, breaking-change detection, TypeScript diagnostics, design token lookup, and more
+- **Zero hallucinations** — every AI component suggestion is grounded in your actual `custom-elements.json`
+- **Framework-agnostic** — works with Lit, Stencil, FAST, Spectrum, Shoelace, or any library that produces a Custom Elements Manifest
+
+## Requirements
+
+- VS Code **≥ 1.99.0**
+- A component library with a `custom-elements.json` (Custom Elements Manifest)
+- Node.js **≥ 20** on `PATH`
+
+## Getting Started
+
+1. Install the extension from the VS Code Marketplace
+2. Open your component library folder in VS Code
+3. The Helixir MCP server will register automatically with AI assistants that support MCP (e.g., GitHub Copilot, Claude)
+
+### Optional: Configure the Config Path
+
+If your `mcpwc.config.json` is not at the workspace root, set the path via VS Code settings:
+
+```json
+// .vscode/settings.json
+{
+  "helixir.configPath": "packages/web-components/mcpwc.config.json"
+}
+```
+
+The path can be relative to the workspace root or absolute.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `Helixir: Run Health Check` | Guides you to run a health check via your AI assistant |
+
+## Extension Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `helixir.configPath` | `string` | `""` | Path to `mcpwc.config.json`. Empty = workspace root. |
+
+## How It Works
+
+When the extension activates, it registers a **MCP server definition provider** (`helixir`) with VS Code's language model API (`vscode.lm`). VS Code spawns the bundled helixir MCP server (`dist/mcp-server.js`) as a child process over stdio.
+
+The server reads your `custom-elements.json` and exposes 30+ tools that AI models can call to look up component APIs, run health scans, generate type declarations, and more.
+
+## Configuration Reference
+
+The helixir server is configured via environment variables passed by the extension:
+
+| Variable | Description |
+|----------|-------------|
+| `MCP_WC_PROJECT_ROOT` | Set to your workspace folder automatically |
+| `MCP_WC_CONFIG_PATH` | Set when `helixir.configPath` is configured |
+
+Additional configuration (token path, component prefix, health history dir) belongs in `mcpwc.config.json`. See the [helixir documentation](https://github.com/bookedsolidtech/helixir) for the full config reference.
+
+## Troubleshooting
+
+**MCP server not appearing in AI assistant tools**
+- Verify VS Code ≥ 1.99.0 is installed
+- Confirm your workspace contains a `custom-elements.json`
+- Check the Output panel → Helixir for error messages
+
+**"No workspace folder" error from Run Health Check**
+- Open a folder (not just a file) in VS Code — the extension uses the workspace folder as the project root
+
+**Server starts but returns no components**
+- Ensure `custom-elements.json` exists at the workspace root or configure `helixir.configPath`
+- Regenerate the manifest: `npm run analyze:cem` (or your CEM generation script)
+
+## License
+
+MIT — see [LICENSE](../../LICENSE)

packages/vscode/esbuild.config.mjs

@@ -0,0 +1,69 @@
+/**
+ * esbuild configuration for the Helixir VS Code extension.
+ *
+ * Produces two bundles:
+ *   dist/extension.js   — VS Code extension host entry (CJS, externalizes 'vscode')
+ *   dist/mcp-server.js  — Helixir MCP server entry (ESM, bundles helixir)
+ */
+
+import * as esbuild from 'esbuild';
+
+const isProduction = process.argv.includes('--production');
+const isWatch = process.argv.includes('--watch');
+
+const sharedOptions = {
+  bundle: true,
+  sourcemap: !isProduction,
+  minify: isProduction,
+  logLevel: 'info',
+  platform: 'node',
+  target: 'node20',
+};
+
+/**
+ * Bundle 1: VS Code extension host entry
+ *   - CommonJS (VS Code extension host requires CJS)
+ *   - 'vscode' is externalized — provided by the VS Code runtime
+ */
+const extensionConfig = {
+  ...sharedOptions,
+  entryPoints: ['src/extension.ts'],
+  outfile: 'dist/extension.js',
+  format: 'cjs',
+  external: ['vscode'],
+};
+
+/**
+ * Bundle 2: Helixir MCP server
+ *   - ESM format (helixir is an ES module)
+ *   - Bundles helixir and its dependencies so the extension is self-contained
+ *   - Spawned as a child process via stdio by the VS Code extension
+ */
+const mcpServerConfig = {
+  ...sharedOptions,
+  entryPoints: ['src/mcp-server-entry.ts'],
+  outfile: 'dist/mcp-server.js',
+  format: 'esm',
+  banner: {
+    js: '#!/usr/bin/env node\n// Helixir MCP Server — bundled by esbuild',
+  },
+};
+
+async function build() {
+  const extensionCtx = await esbuild.context(extensionConfig);
+  const mcpServerCtx = await esbuild.context(mcpServerConfig);
+
+  if (isWatch) {
+    await Promise.all([extensionCtx.watch(), mcpServerCtx.watch()]);
+    console.log('[helixir-vscode] Watching for changes...');
+  } else {
+    await Promise.all([extensionCtx.rebuild(), mcpServerCtx.rebuild()]);
+    await Promise.all([extensionCtx.dispose(), mcpServerCtx.dispose()]);
+    console.log('[helixir-vscode] Build complete.');
+  }
+}
+
+build().catch((err) => {
+  console.error('[helixir-vscode] Build failed:', err);
+  process.exit(1);
+});