bookedsolidtech · himerus · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
@@ -0,0 +1,52 @@
+name: Publish VS Code Extension
+
+on:
+  push:
+    tags:
+      - 'vscode-v*'
+
+jobs:
+  publish-vscode:
+    name: Publish to Marketplaces
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install gitleaks
+        run: |
+          GITLEAKS_VERSION="8.18.4"
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
+            | tar -xz -C /usr/local/bin gitleaks
+
+      - name: Scan for secrets
+        run: gitleaks detect --config .gitleaks.toml --log-opts="HEAD~1..HEAD" --verbose --redact
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: '9'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build helixir
+        run: pnpm run build
+
+      - name: Bundle extension
+        run: pnpm --filter helixir-vscode run vscode:prepublish
+
+      - name: Publish to VS Code Marketplace
+        run: npx @vscode/vsce publish --no-dependencies
+        env:
+          VSCE_PAT: ${{ secrets.VSCE_PAT }}
+
+      - name: Publish to Open VSX
+        run: npx ovsx publish --no-dependencies -p ${{ secrets.OVSX_PAT }}
diff --git a/README.md b/README.md
diff --git a/assets/social-card.png b/assets/social-card.png
diff --git a/assets/social-card.webp b/assets/social-card.webp
@@ -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 .",
@@ -107,7 +108,8 @@
       "@hono/node-server": ">=1.19.10",
       "express-rate-limit": ">=8.2.2",
       "undici": ">=7.24.0",
-      "flatted": ">=3.4.0"
+      "flatted": ">=3.4.2",
+      "picomatch": ">=4.0.4"
     }
   },
   "engines": {

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

diff --git a/packages/core/src/config.ts b/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

diff --git a/packages/core/src/handlers/cem.ts b/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[] = [];

diff --git a/packages/core/src/handlers/dependencies.ts b/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);

diff --git a/packages/core/src/handlers/extend.ts b/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);

diff --git a/packages/core/src/handlers/theme.ts b/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})`;
   }
 }
 

@@ -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": {

diff --git a/packages/vscode/.vscodeignore b/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/
diff --git a/packages/vscode/README.md b/packages/vscode/README.md
@@ -0,0 +1,87 @@
+# 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)