opencastle 0.10.0 → 0.10.2

package/src/cli/init.ts

@@ -88,6 +88,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
     ...(repoInfo.databases ?? []),
     ...(repoInfo.deployment ?? []),
     ...(repoInfo.monorepo ? [repoInfo.monorepo] : []),
+    ...((repoInfo.frameworks ?? []).map(f => f === 'next' ? 'nextjs' : f)),
   ])
 
   console.log(`  ${c.bold('── Tech Tools ────────────────────────────────')}`)
@@ -199,6 +200,12 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   manifest.repoInfo = combinedRepoInfo
   await writeManifest(projectRoot, manifest)
 
+  // ── Ensure .env is gitignored when MCP env vars are needed ────
+  const envVars = getRequiredMcpEnvVars(stack, combinedRepoInfo)
+  if (envVars.length > 0 && !allManagedPaths.framework.includes('.env')) {
+    allManagedPaths.framework.push('.env')
+  }
+
   // ── Update .gitignore ───────────────────────────────────────────
   const gitignoreResult = await updateGitignore(projectRoot, allManagedPaths)
 
@@ -214,7 +221,6 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   }
 
   // ── Env var notice + .env file generation ────────────────────
-  const envVars = getRequiredMcpEnvVars(stack, combinedRepoInfo)
   if (envVars.length > 0) {
     console.log(`\n  ${c.yellow('⚠')}  Required environment variables for MCP servers:\n`)
     for (const { envVar, hint } of envVars) {
@@ -248,7 +254,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   // ── OAuth setup guides ────────────────────────────────────────
   if (teamTools.includes('slack')) {
     console.log(`  ${c.cyan('📖')} Slack MCP requires a Slack App with a bot token.`)
-    console.log(`     Setup guide: ${c.cyan('https://www.opencastle.dev/guides/plugins#slack')}\n`)
+    console.log(`     Setup guide: ${c.cyan('https://www.opencastle.dev/docs/plugins#slack')}\n`)
   }
 
   console.log(`\n  ${c.bold('Next steps:')}`)

package/src/cli/mcp.ts

@@ -111,7 +111,7 @@ export async function scaffoldMcpConfig(
 
     for (const plugin of Object.values(PLUGINS)) {
       if (plugin.mcpServerKey && included.has(plugin.mcpServerKey)) {
-        servers[plugin.mcpServerKey] = plugin.mcpConfig as VsCodeServer;
+        servers[plugin.mcpServerKey] = plugin.mcpConfig! as VsCodeServer;
         if (plugin.mcpInputs) {
           inputs.push(...plugin.mcpInputs);
         }
@@ -181,3 +181,79 @@ export async function scaffoldMcpConfig(
 
   return { path: destPath, action: 'created' };
 }
+
+// ── MCP config rebuild for reconfigure ────────────────────────
+
+/**
+ * Returns the relative path to the MCP config file for a given IDE.
+ */
+function getMcpConfigRelPath(ide: IdeChoice): string {
+  switch (ide) {
+    case 'vscode':
+      return '.vscode/mcp.json';
+    case 'cursor':
+      return '.cursor/mcp.json';
+    case 'claude-code':
+      return '.claude/mcp.json';
+    case 'opencode':
+      return 'opencode.json';
+  }
+}
+
+/**
+ * Rebuild the MCP config for a specific IDE after a stack reconfigure.
+ *
+ * 1. Reads the existing MCP config
+ * 2. Removes all plugin-managed server entries
+ * 3. Preserves manually-added server entries
+ * 4. Re-scaffolds with the new stack selection
+ */
+export async function rebuildMcpConfig(
+  projectRoot: string,
+  ide: IdeChoice,
+  stack: StackConfig,
+  repoInfo?: RepoInfo
+): Promise<void> {
+  const destRelPath = getMcpConfigRelPath(ide);
+  const destPath = resolve(projectRoot, destRelPath);
+
+  if (!existsSync(destPath)) {
+    // No existing config — scaffold fresh
+    await scaffoldMcpConfig(projectRoot, destRelPath, stack, repoInfo, ide);
+    return;
+  }
+
+  // Read existing config and strip all plugin-managed servers
+  const existing = JSON.parse(await readFile(destPath, 'utf8')) as Record<string, unknown>;
+  const containerKey =
+    ide === 'opencode' ? 'mcp' : ide === 'vscode' ? 'servers' : 'mcpServers';
+
+  const existingServers = (existing[containerKey] ?? {}) as Record<string, unknown>;
+
+  // Get all known plugin server keys
+  const allPluginServerKeys = new Set(
+    Object.values(PLUGINS)
+      .filter((p) => p.mcpServerKey)
+      .map((p) => p.mcpServerKey!)
+  );
+
+  // Remove all plugin-managed servers (they'll be re-added by scaffoldMcpConfig)
+  for (const key of Object.keys(existingServers)) {
+    if (allPluginServerKeys.has(key)) {
+      delete existingServers[key];
+    }
+  }
+
+  // Remove plugin-managed inputs (VS Code only)
+  if (ide === 'vscode') {
+    delete existing.inputs;
+  }
+
+  existing[containerKey] = existingServers;
+
+  // Write the cleaned config (preserving manually-added servers)
+  await writeFile(destPath, JSON.stringify(existing, null, 2) + '\n');
+
+  // Re-scaffold: merges new plugin servers into the cleaned config
+  await scaffoldMcpConfig(projectRoot, destRelPath, stack, repoInfo, ide);
+}

package/src/cli/stack-config-update.test.ts

@@ -0,0 +1,210 @@
+import { describe, it, expect } from 'vitest';
+import { updateSkillMatrixContent } from './stack-config.js';
+import type { StackConfig } from './types.js';
+import type { SkillMatrixData } from './stack-config.js';
+
+function makeTemplate(): SkillMatrixData {
+  return {
+    bindings: {
+      framework: {
+        entries: [],
+        description: 'SSR/SSG, routing, layouts, Server/Client Components',
+      },
+      database: { entries: [], description: 'Schema, migrations, auth flow, roles' },
+      cms: { entries: [], description: 'Document types, queries, schema management' },
+      deployment: {
+        entries: [],
+        description: 'Hosting, cron jobs, env vars, caching, headers',
+      },
+      'codebase-tool': {
+        entries: [],
+        description: 'Task running, building, linting, testing, code generation',
+      },
+      testing: {
+        entries: [],
+        description: 'Unit testing frameworks, coverage, test planning',
+      },
+      'e2e-testing': {
+        entries: [],
+        description: 'Browser automation, E2E testing, viewport testing, visual validation',
+      },
+      'task-management': {
+        entries: [],
+        description: 'Issue tracking, naming, priorities, workflow states',
+      },
+    },
+    agents: {},
+  };
+}
+
+function templateJson(): string {
+  return JSON.stringify(makeTemplate(), null, 2) + '\n';
+}
+
+function parse(result: string): SkillMatrixData {
+  return JSON.parse(result);
+}
+
+describe('updateSkillMatrixContent', () => {
+  it('fills database slot when a database tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['supabase'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.database.entries).toEqual([
+      { name: 'Supabase', skill: 'supabase-database' },
+    ]);
+  });
+
+  it('fills cms slot when a CMS tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['sanity'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.cms.entries).toEqual([{ name: 'Sanity', skill: 'sanity-cms' }]);
+  });
+
+  it('fills framework slot when a framework tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['nextjs'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.framework.entries).toEqual([
+      { name: 'Next.js', skill: 'nextjs-framework' },
+    ]);
+  });
+
+  it('fills deployment slot when a deployment tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['vercel'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.deployment.entries).toEqual([
+      { name: 'Vercel', skill: 'vercel-deployment' },
+    ]);
+  });
+
+  it('fills codebase-tool slot when a monorepo tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['nx'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings['codebase-tool'].entries).toEqual([
+      { name: 'NX', skill: 'nx-workspace' },
+    ]);
+  });
+
+  it('fills task-management slot when a tracker tool is selected', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: [], teamTools: ['linear'] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings['task-management'].entries).toEqual([
+      { name: 'Linear', skill: 'linear-task-management' },
+    ]);
+  });
+
+  it('clears database slot when no database tool is selected', () => {
+    const template = makeTemplate();
+    template.bindings.database.entries = [
+      { name: 'Supabase', skill: 'supabase-database' },
+    ];
+    const stack: StackConfig = { ides: ['vscode'], techTools: [], teamTools: [] };
+    const data = parse(
+      updateSkillMatrixContent(JSON.stringify(template, null, 2) + '\n', stack)
+    );
+    expect(data.bindings.database.entries).toEqual([]);
+  });
+
+  it('switches from one database to another', () => {
+    const template = makeTemplate();
+    template.bindings.database.entries = [
+      { name: 'Supabase', skill: 'supabase-database' },
+    ];
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['convex'], teamTools: [] };
+    const data = parse(
+      updateSkillMatrixContent(JSON.stringify(template, null, 2) + '\n', stack)
+    );
+    expect(data.bindings.database.entries).toEqual([
+      { name: 'Convex', skill: 'convex-database' },
+    ]);
+  });
+
+  it('fills multiple slots at once', () => {
+    const stack: StackConfig = {
+      ides: ['vscode'],
+      techTools: ['supabase', 'sanity', 'vercel', 'nextjs'],
+      teamTools: ['linear'],
+    };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.database.entries).toEqual([
+      { name: 'Supabase', skill: 'supabase-database' },
+    ]);
+    expect(data.bindings.cms.entries).toEqual([{ name: 'Sanity', skill: 'sanity-cms' }]);
+    expect(data.bindings.deployment.entries).toEqual([
+      { name: 'Vercel', skill: 'vercel-deployment' },
+    ]);
+    expect(data.bindings.framework.entries).toEqual([
+      { name: 'Next.js', skill: 'nextjs-framework' },
+    ]);
+    expect(data.bindings['task-management'].entries).toEqual([
+      { name: 'Linear', skill: 'linear-task-management' },
+    ]);
+  });
+
+  it('does not modify unrelated slots', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['supabase'], teamTools: [] };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.framework.entries).toEqual([]);
+    expect(data.bindings.cms.entries).toEqual([]);
+  });
+
+  it('supports multiple plugins in the same slot', () => {
+    const stack: StackConfig = {
+      ides: ['vscode'],
+      techTools: ['supabase', 'convex'],
+      teamTools: [],
+    };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.database.entries).toEqual([
+      { name: 'Supabase', skill: 'supabase-database' },
+      { name: 'Convex', skill: 'convex-database' },
+    ]);
+  });
+
+  it('supports multiple frameworks in the same slot', () => {
+    const stack: StackConfig = {
+      ides: ['vscode'],
+      techTools: ['nextjs', 'astro'],
+      teamTools: [],
+    };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.framework.entries).toEqual([
+      { name: 'Next.js', skill: 'nextjs-framework' },
+      { name: 'Astro', skill: 'astro-framework' },
+    ]);
+  });
+
+  it('supports multiple CMS tools in the same slot', () => {
+    const stack: StackConfig = {
+      ides: ['vscode'],
+      techTools: ['sanity', 'contentful'],
+      teamTools: [],
+    };
+    const data = parse(updateSkillMatrixContent(templateJson(), stack));
+    expect(data.bindings.cms.entries).toEqual([
+      { name: 'Sanity', skill: 'sanity-cms' },
+      { name: 'Contentful', skill: 'contentful-cms' },
+    ]);
+  });
+
+  it('preserves agents section', () => {
+    const template = makeTemplate();
+    template.agents = {
+      Developer: { slots: ['framework'], directSkills: ['validation-gates'] },
+    };
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['supabase'], teamTools: [] };
+    const data = parse(
+      updateSkillMatrixContent(JSON.stringify(template, null, 2) + '\n', stack)
+    );
+    expect(data.agents.Developer).toEqual({
+      slots: ['framework'],
+      directSkills: ['validation-gates'],
+    });
+  });
+
+  it('outputs valid JSON with trailing newline', () => {
+    const stack: StackConfig = { ides: ['vscode'], techTools: ['supabase'], teamTools: [] };
+    const result = updateSkillMatrixContent(templateJson(), stack);
+    expect(result.endsWith('\n')).toBe(true);
+    expect(() => JSON.parse(result)).not.toThrow();
+  });
+});

package/src/cli/stack-config.ts

@@ -1,3 +1,6 @@
+import { resolve } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import type { TechTool, TeamTool, StackConfig, CopyDirOptions, RepoInfo } from './types.js';
 import {
   PLUGINS,
@@ -15,7 +18,7 @@ import type { PluginConfig } from '../orchestrator/plugins/types.js';
 interface ToolInfo {
   tech: string;
   skill: string | null;
-  mcpServer: string | null;
+  mcpServer?: string;
 }
 
 /** All tech-tool metadata — derived from plugin configs. */
@@ -135,6 +138,23 @@ export function getRequiredMcpEnvVars(stack: StackConfig, repoInfo?: RepoInfo):
 
 // ── Customization file transforms ─────────────────────────────
 
+// ── Skill matrix JSON types ────────────────────────────────────
+
+export interface SkillMatrixEntry {
+  name: string;
+  skill: string;
+}
+
+export interface SkillMatrixSlot {
+  entries: SkillMatrixEntry[];
+  description: string;
+}
+
+export interface SkillMatrixData {
+  bindings: Record<string, SkillMatrixSlot>;
+  agents: Record<string, { slots: string[]; directSkills: string[] }>;
+}
+
 /**
  * Return a transform callback that pre-populates customization files
  * based on the user's stack selection.
@@ -145,47 +165,13 @@ export function getCustomizationsTransform(
   stack: StackConfig
 ): NonNullable<CopyDirOptions['transform']> {
   return (content: string, srcPath: string) => {
-    if (srcPath.endsWith('skill-matrix.md')) {
-      return transformSkillMatrix(content, stack);
+    if (srcPath.endsWith('skill-matrix.json')) {
+      return updateSkillMatrixContent(content, stack);
     }
     return content;
   };
 }
 
-/**
- * Fill in the `database` and `cms` rows in the skill matrix
- * based on the user's stack selection.
- */
-function transformSkillMatrix(content: string, stack: StackConfig): string {
-  let result = content;
-
-  // Find first selected DB tool
-  const db = stack.techTools.find((t) => (DB_TOOLS as readonly string[]).includes(t));
-  if (db) {
-    const info = TECH_TOOL_INFO[db as TechTool];
-    if (info?.skill) {
-      result = result.replace(
-        /(\| `database`\s*\|)\s*\|(\s*\|)/,
-        `$1 ${info.tech} | \`${info.skill}\` $2`
-      );
-    }
-  }
-
-  // Find first selected CMS tool
-  const cms = stack.techTools.find((t) => (CMS_TOOLS as readonly string[]).includes(t));
-  if (cms) {
-    const info = TECH_TOOL_INFO[cms as TechTool];
-    if (info?.skill) {
-      result = result.replace(
-        /(\| `cms`\s*\|)\s*\|(\s*\|)/,
-        `$1 ${info.tech} | \`${info.skill}\` $2`
-      );
-    }
-  }
-
-  return result;
-}
-
 // ── Agent tool injection ──────────────────────────────────────
 
 /**
@@ -253,3 +239,90 @@ export function getAgentTransform(
     return `---\n${newFrontmatter}\n---\n${body}`;
   };
 }
+
+// ── Skill matrix update ─────────────────────────────────────────
+
+/** Mapping from plugin subCategory to skill matrix slot name. */
+const SUBCATEGORY_TO_SLOT: Record<string, string> = {
+  database: 'database',
+  cms: 'cms',
+  deployment: 'deployment',
+  framework: 'framework',
+  'codebase-tool': 'codebase-tool',
+  'task-management': 'task-management',
+  testing: 'testing',
+  'e2e-testing': 'e2e-testing',
+};
+
+/**
+ * Get the filesystem path to the skill matrix file for a given IDE.
+ */
+function getSkillMatrixPath(projectRoot: string, ide: string): string {
+  const relativePath = 'customizations/agents/skill-matrix.json';
+  switch (ide) {
+    case 'vscode':
+      return resolve(projectRoot, '.github', relativePath);
+    case 'cursor':
+      return resolve(projectRoot, '.cursor', 'rules', relativePath);
+    case 'claude-code':
+      return resolve(projectRoot, '.claude', relativePath);
+    case 'opencode':
+      return resolve(projectRoot, '.opencode', relativePath);
+    default:
+      return '';
+  }
+}
+
+/**
+ * Update the skill matrix file in-place for a specific IDE.
+ * Updates slot entries based on the user's current stack selections.
+ * Returns true if the file was updated, false if unchanged or missing.
+ */
+export async function updateSkillMatrixFile(
+  projectRoot: string,
+  ide: string,
+  stack: StackConfig
+): Promise<boolean> {
+  const matrixPath = getSkillMatrixPath(projectRoot, ide);
+  if (!matrixPath || !existsSync(matrixPath)) return false;
+
+  const content = await readFile(matrixPath, 'utf8');
+  const updated = updateSkillMatrixContent(content, stack);
+  if (updated !== content) {
+    await writeFile(matrixPath, updated);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Update skill matrix JSON content based on stack selections.
+ * Pure function — sets slot entries for all plugin-mapped subcategories.
+ * Supports multiple plugins per slot (e.g. multiple databases).
+ */
+export function updateSkillMatrixContent(content: string, stack: StackConfig): string {
+  const data: SkillMatrixData = JSON.parse(content);
+  const allTools = [...stack.techTools, ...stack.teamTools] as string[];
+
+  for (const [subCategory, slotName] of Object.entries(SUBCATEGORY_TO_SLOT)) {
+    // Find ALL selected tools matching this subcategory (not just the first)
+    const matchingTools = allTools.filter((toolId) => {
+      const plugin = PLUGINS[toolId];
+      return plugin?.subCategory === subCategory;
+    });
+
+    const entries: SkillMatrixEntry[] = matchingTools
+      .map((toolId) => {
+        const plugin = PLUGINS[toolId];
+        if (!plugin?.skillName) return null;
+        return { name: plugin.name, skill: plugin.skillName };
+      })
+      .filter((e): e is SkillMatrixEntry => e !== null);
+
+    if (data.bindings[slotName]) {
+      data.bindings[slotName].entries = entries;
+    }
+  }
+
+  return JSON.stringify(data, null, 2) + '\n';
+}

package/src/cli/types.ts

@@ -3,7 +3,7 @@ import type { ChildProcess } from 'node:child_process';
 // ── Stack selection types ──────────────────────────────────────
 
 export type IdeChoice = 'vscode' | 'cursor' | 'claude-code' | 'opencode';
-export type TechTool = 'sanity' | 'contentful' | 'strapi' | 'supabase' | 'convex' | 'vercel' | 'nx' | 'chrome-devtools';
+export type TechTool = 'sanity' | 'contentful' | 'strapi' | 'supabase' | 'convex' | 'vercel' | 'nx' | 'chrome-devtools' | 'nextjs' | 'astro';
 export type TeamTool = 'linear' | 'jira' | 'slack' | 'teams';
 
 export interface StackConfig {