opencastle 0.7.0 → 0.8.1

package/src/cli/detect.ts

@@ -221,15 +221,17 @@ export async function detectRepoInfo(projectRoot: string): Promise<RepoInfo> {
     }
   }
 
-  // ── 3. Detect by config files ───────────────────────────────
-  await detectCategory(projectRoot, FRAMEWORKS, info, 'frameworks');
-  await detectCategory(projectRoot, DATABASES, info, 'databases');
-  await detectCategory(projectRoot, CMS_PLATFORMS, info, 'cms');
-  await detectCategory(projectRoot, DEPLOYMENT, info, 'deployment');
-  await detectCategory(projectRoot, TESTING, info, 'testing');
-  await detectCategory(projectRoot, CICD, info, 'cicd');
-  await detectCategory(projectRoot, STYLING, info, 'styling');
-  await detectCategory(projectRoot, AUTH, info, 'auth');
+  // ── 3. Detect by config files (parallel) ─────────────────────
+  await Promise.all([
+    detectCategory(projectRoot, FRAMEWORKS, info, 'frameworks'),
+    detectCategory(projectRoot, DATABASES, info, 'databases'),
+    detectCategory(projectRoot, CMS_PLATFORMS, info, 'cms'),
+    detectCategory(projectRoot, DEPLOYMENT, info, 'deployment'),
+    detectCategory(projectRoot, TESTING, info, 'testing'),
+    detectCategory(projectRoot, CICD, info, 'cicd'),
+    detectCategory(projectRoot, STYLING, info, 'styling'),
+    detectCategory(projectRoot, AUTH, info, 'auth'),
+  ]);
 
   // ── 4. Detect from package.json deps ────────────────────────
   await detectFromPackageJson(projectRoot, info);
@@ -241,12 +243,14 @@ export async function detectRepoInfo(projectRoot: string): Promise<RepoInfo> {
     '.claude/mcp.json',
     'mcp.json',
   ];
-  for (const p of mcpPaths) {
-    if (await fileExists(resolve(projectRoot, p))) {
-      info.mcpConfig = true;
-      info.configFiles.push(p);
-    }
-  }
+  await Promise.all(
+    mcpPaths.map(async (p) => {
+      if (await fileExists(resolve(projectRoot, p))) {
+        info.mcpConfig = true;
+        info.configFiles.push(p);
+      }
+    })
+  );
 
   // ── 6. Check for TypeScript ─────────────────────────────────
   const tsConfigPath = resolve(projectRoot, 'tsconfig.json');

package/src/cli/doctor.ts

@@ -0,0 +1,235 @@
+import { resolve } from 'node:path';
+import { readFile, access, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { readManifest } from './manifest.js';
+import { getRequiredMcpEnvVars } from './stack-config.js';
+import type { CliContext, Manifest, IdeChoice } from './types.js';
+
+// ── Styled output helpers ─────────────────────────────────────
+
+const PASS = '\x1b[32m✓\x1b[0m';
+const FAIL = '\x1b[31m✗\x1b[0m';
+const WARN = '\x1b[33m!\x1b[0m';
+const DIM = (s: string) => `\x1b[2m${s}\x1b[0m`;
+const BOLD = (s: string) => `\x1b[1m${s}\x1b[0m`;
+
+interface CheckResult {
+  ok: boolean;
+  label: string;
+  detail?: string;
+  warning?: boolean;
+}
+
+// ── Individual checks ─────────────────────────────────────────
+
+function checkManifest(manifest: Manifest | null): CheckResult {
+  if (!manifest) {
+    return { ok: false, label: 'OpenCastle manifest (.opencastle.json)', detail: 'Not found. Run "npx opencastle init" first.' };
+  }
+  return { ok: true, label: 'OpenCastle manifest (.opencastle.json)', detail: `v${manifest.version}, IDE: ${manifest.ides?.join(', ') ?? manifest.ide}` };
+}
+
+async function checkCustomizations(projectRoot: string): Promise<CheckResult> {
+  const dir = resolve(projectRoot, '.github', 'customizations');
+  if (!existsSync(dir)) {
+    return { ok: false, label: 'Customizations directory', detail: '.github/customizations/ not found' };
+  }
+  const files = await readdir(dir).catch(() => []);
+  return { ok: true, label: 'Customizations directory', detail: `${files.length} entries` };
+}
+
+async function checkSkillMatrix(projectRoot: string): Promise<CheckResult> {
+  const path = resolve(projectRoot, '.github', 'customizations', 'agents', 'skill-matrix.md');
+  if (!existsSync(path)) {
+    return { ok: false, label: 'Skill matrix', detail: 'File not found at .github/customizations/agents/skill-matrix.md' };
+  }
+  const content = await readFile(path, 'utf8');
+  // Look for empty capability slots (pattern: | `domain` | | |)
+  const emptySlots = content.match(/\| `\w+`\s*\|\s*\|\s*\|/g);
+  if (emptySlots && emptySlots.length > 0) {
+    return { ok: true, label: 'Skill matrix', detail: `${emptySlots.length} unresolved capability slot(s)`, warning: true };
+  }
+  return { ok: true, label: 'Skill matrix', detail: 'All capability slots populated' };
+}
+
+async function checkInstructions(projectRoot: string): Promise<CheckResult> {
+  const dir = resolve(projectRoot, '.github', 'instructions');
+  if (!existsSync(dir)) {
+    return { ok: false, label: 'Instruction files', detail: '.github/instructions/ not found' };
+  }
+  const files = await readdir(dir).catch(() => []);
+  const mdFiles = files.filter((f) => f.endsWith('.md'));
+  if (mdFiles.length === 0) {
+    return { ok: false, label: 'Instruction files', detail: 'No .md files in .github/instructions/' };
+  }
+  return { ok: true, label: 'Instruction files', detail: `${mdFiles.length} instruction files` };
+}
+
+async function checkAgents(projectRoot: string): Promise<CheckResult> {
+  const dir = resolve(projectRoot, '.github', 'customizations', 'agents');
+  if (!existsSync(dir)) {
+    return { ok: false, label: 'Agent definitions', detail: 'agents/ directory not found in customizations' };
+  }
+  const files = await readdir(dir).catch(() => []);
+  const agentFiles = files.filter((f) => f.endsWith('.agent.md'));
+  if (agentFiles.length === 0) {
+    return { ok: false, label: 'Agent definitions', detail: 'No .agent.md files found' };
+  }
+  return { ok: true, label: 'Agent definitions', detail: `${agentFiles.length} agents` };
+}
+
+async function checkSkills(projectRoot: string): Promise<CheckResult> {
+  const dir = resolve(projectRoot, '.github', 'skills');
+  if (!existsSync(dir)) {
+    return { ok: false, label: 'Skills directory', detail: '.github/skills/ not found' };
+  }
+  const entries = await readdir(dir).catch(() => []);
+  return { ok: true, label: 'Skills directory', detail: `${entries.length} skills` };
+}
+
+async function checkLogs(projectRoot: string): Promise<CheckResult> {
+  const dir = resolve(projectRoot, '.github', 'customizations', 'logs');
+  if (!existsSync(dir)) {
+    return { ok: false, label: 'Observability logs', detail: 'logs/ directory not found — dashboard will be empty' };
+  }
+  const required = ['sessions.ndjson', 'delegations.ndjson', 'reviews.ndjson', 'panels.ndjson', 'disputes.ndjson'];
+  const missing = required.filter((f) => !existsSync(resolve(dir, f)));
+  if (missing.length > 0) {
+    return { ok: true, label: 'Observability logs', detail: `Missing: ${missing.join(', ')}`, warning: true };
+  }
+  return { ok: true, label: 'Observability logs', detail: 'All log files present' };
+}
+
+function checkMcpEnvVars(manifest: Manifest | null): CheckResult {
+  if (!manifest?.stack) {
+    return { ok: true, label: 'MCP environment variables', detail: 'No stack config (skipped)' };
+  }
+  const required = getRequiredMcpEnvVars(manifest.stack, manifest.repoInfo);
+  if (required.length === 0) {
+    return { ok: true, label: 'MCP environment variables', detail: 'No env vars required' };
+  }
+  const missing = required.filter((r) => !process.env[r.envVar]);
+  if (missing.length > 0) {
+    const names = missing.map((m) => m.envVar).join(', ');
+    return { ok: false, label: 'MCP environment variables', detail: `Missing: ${names}` };
+  }
+  return { ok: true, label: 'MCP environment variables', detail: `${required.length} var(s) set` };
+}
+
+async function checkDotEnv(projectRoot: string, manifest: Manifest | null): Promise<CheckResult> {
+  const envPath = resolve(projectRoot, '.env');
+  if (!existsSync(envPath)) {
+    if (manifest?.stack) {
+      const required = getRequiredMcpEnvVars(manifest.stack, manifest.repoInfo);
+      if (required.length > 0) {
+        return { ok: true, label: '.env file', detail: 'Not found — consider creating one for MCP secrets', warning: true };
+      }
+    }
+    return { ok: true, label: '.env file', detail: 'Not found (not required)' };
+  }
+  return { ok: true, label: '.env file', detail: 'Present' };
+}
+
+async function checkIdeConfigs(projectRoot: string, manifest: Manifest | null): Promise<CheckResult> {
+  if (!manifest) {
+    return { ok: false, label: 'IDE configuration files', detail: 'No manifest — cannot check' };
+  }
+  const ides = manifest.ides ?? [manifest.ide];
+  const checks: Array<{ ide: string; file: string; found: boolean }> = [];
+
+  for (const ide of ides) {
+    let configFile: string;
+    switch (ide as IdeChoice) {
+      case 'vscode':
+        configFile = '.github/copilot-instructions.md';
+        break;
+      case 'cursor':
+        configFile = '.cursor/rules/opencastle.mdc';
+        break;
+      case 'claude-code':
+        configFile = '.claude/settings.json';
+        break;
+      case 'opencode':
+        configFile = '.opencode/agents.md';
+        break;
+      default:
+        continue;
+    }
+    checks.push({ ide: ide as string, file: configFile, found: existsSync(resolve(projectRoot, configFile)) });
+  }
+
+  const missing = checks.filter((c) => !c.found);
+  if (missing.length > 0) {
+    return { ok: false, label: 'IDE configuration files', detail: `Missing: ${missing.map((m) => `${m.ide} (${m.file})`).join(', ')}` };
+  }
+  return { ok: true, label: 'IDE configuration files', detail: `${checks.length} IDE(s) configured` };
+}
+
+async function checkMcpConfig(projectRoot: string, manifest: Manifest | null): Promise<CheckResult> {
+  if (!manifest) {
+    return { ok: false, label: 'MCP configuration', detail: 'No manifest — cannot check' };
+  }
+  const ides = manifest.ides ?? [manifest.ide];
+  const mcpPaths: Record<string, string> = {
+    vscode: '.vscode/mcp.json',
+    cursor: '.cursor/mcp.json',
+    'claude-code': '.claude/mcp.json',
+    opencode: 'mcp.json',
+  };
+
+  const found: string[] = [];
+  for (const ide of ides) {
+    const path = mcpPaths[ide as string];
+    if (path && existsSync(resolve(projectRoot, path))) {
+      found.push(ide as string);
+    }
+  }
+  if (found.length === 0 && ides.length > 0) {
+    return { ok: true, label: 'MCP configuration', detail: 'No MCP config files found (MCP tools will not be available)', warning: true };
+  }
+  return { ok: true, label: 'MCP configuration', detail: `${found.length} MCP config(s)` };
+}
+
+// ── Main doctor command ───────────────────────────────────────
+
+export default async function doctor({ args: _args }: CliContext): Promise<void> {
+  const projectRoot = process.cwd();
+
+  console.log(`\n  🏰 ${BOLD('OpenCastle Doctor')}\n`);
+  console.log(`  ${DIM('Checking your setup...')}\n`);
+
+  const manifest = await readManifest(projectRoot);
+
+  const results: CheckResult[] = [
+    checkManifest(manifest),
+    await checkCustomizations(projectRoot),
+    await checkInstructions(projectRoot),
+    await checkAgents(projectRoot),
+    await checkSkills(projectRoot),
+    await checkSkillMatrix(projectRoot),
+    await checkLogs(projectRoot),
+    await checkIdeConfigs(projectRoot, manifest),
+    await checkMcpConfig(projectRoot, manifest),
+    checkMcpEnvVars(manifest),
+    await checkDotEnv(projectRoot, manifest),
+  ];
+
+  for (const r of results) {
+    const icon = r.ok ? (r.warning ? WARN : PASS) : FAIL;
+    const detail = r.detail ? `  ${DIM(r.detail)}` : '';
+    console.log(`  ${icon} ${r.label}${detail}`);
+  }
+
+  const failures = results.filter((r) => !r.ok);
+  const warnings = results.filter((r) => r.ok && r.warning);
+
+  console.log();
+  if (failures.length > 0) {
+    console.log(`  ${BOLD(`${failures.length} issue(s) found.`)} Run "npx opencastle init" to fix.\n`);
+    process.exit(1);
+  } else if (warnings.length > 0) {
+    console.log(`  ${BOLD('All checks passed')} with ${warnings.length} warning(s).\n`);
+  } else {
+    console.log(`  ${BOLD('All checks passed.')} Your setup is healthy.\n`);
+  }
+}

package/src/cli/init.ts

@@ -8,24 +8,9 @@ import { updateGitignore } from './gitignore.js'
 import { getRequiredMcpEnvVars } from './stack-config.js'
 import { TECH_PLUGINS, TEAM_PLUGINS } from '../orchestrator/plugins/index.js'
 import { detectRepoInfo, mergeStackIntoRepoInfo, formatRepoInfo } from './detect.js'
-import type { CliContext, IdeAdapter, IdeChoice, TechTool, TeamTool, StackConfig } from './types.js'
-
-const ADAPTERS: Record<string, () => Promise<IdeAdapter>> = {
-  vscode: () => import('./adapters/vscode.js') as Promise<IdeAdapter>,
-  cursor: () => import('./adapters/cursor.js') as Promise<IdeAdapter>,
-  'claude-code': () =>
-    import('./adapters/claude-code.js') as Promise<IdeAdapter>,
-  opencode: () =>
-    import('./adapters/opencode.js') as Promise<IdeAdapter>,
-}
-
-/** IDE display labels */
-const IDE_DISPLAY: Record<IdeChoice, string> = {
-  vscode: 'VS Code',
-  cursor: 'Cursor',
-  'claude-code': 'Claude Code',
-  opencode: 'OpenCode',
-}
+import { IDE_ADAPTERS } from './adapters/index.js'
+import { IDE_LABELS } from './types.js'
+import type { CliContext, IdeChoice, TechTool, TeamTool, StackConfig } from './types.js'
 
 export default async function init({ pkgRoot, args }: CliContext): Promise<void> {
   const projectRoot = process.cwd()
@@ -135,7 +120,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   // ── Merge user choices into detected info ────────────────────
   const combinedRepoInfo = mergeStackIntoRepoInfo(repoInfo, stack)
 
-  const ideNames = ides.map((id) => IDE_DISPLAY[id as IdeChoice]).join(', ')
+  const ideNames = ides.map((id) => IDE_LABELS[id as IdeChoice]).join(', ')
   console.log(`\n  Installing for ${c.cyan(ideNames)}...`)
   if (techTools.length > 0) {
     console.log(`  Tech: ${c.green(techTools.join(', '))}`)
@@ -148,9 +133,9 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   // ── Dry run ─────────────────────────────────────────────────────
   if (dryRun) {
     for (const ide of ides) {
-      const adapter = await ADAPTERS[ide]()
+      const adapter = await IDE_ADAPTERS[ide]()
       const managed = adapter.getManagedPaths()
-      console.log(`  ${c.dim(`[dry-run] ${IDE_DISPLAY[ide as IdeChoice]} files:`)}\n`)
+      console.log(`  ${c.dim(`[dry-run] ${IDE_LABELS[ide as IdeChoice]} files:`)}\n`)
       for (const p of managed.framework) {
         console.log(`    ${c.green('+')} ${p}`)
       }
@@ -197,7 +182,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   const allManagedPaths = { framework: [] as string[], customizable: [] as string[] }
 
   for (const ide of ides) {
-    const adapter = await ADAPTERS[ide]()
+    const adapter = await IDE_ADAPTERS[ide]()
     const results = await adapter.install(pkgRoot, projectRoot, stack, combinedRepoInfo)
     totalCreated += results.created.length
     totalSkipped += results.skipped.length
@@ -228,7 +213,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
     console.log(`  ${c.dim('→')} Skipped ${totalSkipped} existing files`)
   }
 
-  // ── Env var notice ──────────────────────────────────────────────
+  // ── 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`)
@@ -236,6 +221,28 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
       console.log(`     ${c.bold(envVar)}`)
       console.log(`     ${c.dim('└')} ${c.dim(hint)}\n`)
     }
+
+    // Offer to create .env if it doesn't exist
+    const envPath = resolve(projectRoot, '.env')
+    if (!dryRun && !existsSync(envPath)) {
+      const createEnv = await confirm('Create a .env file with placeholders for these variables?', true)
+      if (createEnv) {
+        const { writeFile: writeEnvFile } = await import('node:fs/promises')
+        const lines = envVars.map(({ envVar, hint }) => `# ${hint}\n${envVar}=\n`)
+        await writeEnvFile(envPath, lines.join('\n') + '\n')
+        console.log(`  ${c.green('✓')} Created .env with ${envVars.length} placeholder(s)`)
+        console.log(`  ${c.dim('→')} Fill in the values, then reload your IDE\n`)
+      }
+    } else if (!dryRun && existsSync(envPath)) {
+      // Check which vars are already in .env
+      const envContent = await readFile(envPath, 'utf8')
+      const missing = envVars.filter(({ envVar }) => !envContent.includes(envVar))
+      if (missing.length > 0) {
+        console.log(`  ${c.dim('→')} Your .env is missing: ${missing.map((m) => m.envVar).join(', ')}`)
+      } else {
+        console.log(`  ${c.green('✓')} All required variables found in .env`)
+      }
+    }
   }
 
   // ── OAuth setup guides ────────────────────────────────────────
@@ -266,7 +273,7 @@ export default async function init({ pkgRoot, args }: CliContext): Promise<void>
   if (envVars.length > 0) {
     step++
     console.log(
-      `  ${step}. Set the environment variable${envVars.length > 1 ? 's' : ''} listed above`
+      `  ${step}. Set the environment variable${envVars.length > 1 ? 's' : ''} listed above (in .env or your shell)`
     )
   }
   step++