nurosys-agents 2.0.0

package/scripts/setup.js

@@ -0,0 +1,518 @@
+#!/usr/bin/env node
+
+const fs   = require('fs');
+const path = require('path');
+const { spawnSync, execSync } = require('child_process');
+const readline = require('readline');
+
+const { runSetupRules } = require('./setup-rules.js');
+
+const projectRoot = process.cwd();
+
+function resolvePackagePath() {
+  try { return path.dirname(require.resolve('nurosys-agents/package.json')); }
+  catch { return path.resolve(__dirname, '..'); }
+}
+
+const packagePath = resolvePackagePath();
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function ask(q) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(res => rl.question(q, a => { rl.close(); res(a.trim().toLowerCase()); }));
+}
+
+// Interactive checkbox multiselect — arrow keys to move, space to toggle, enter to confirm
+function multiselect(title, options) {
+  return new Promise((resolve) => {
+    let cursor   = 0;
+    const selected = new Set();
+
+    function render() {
+      if (render.drawn) process.stdout.write(`\x1B[${options.length + 2}A`);
+      render.drawn = true;
+
+      process.stdout.write(`\n  ${title}\n`);
+      options.forEach((opt, i) => {
+        const check  = selected.has(i) ? '◉' : '○';
+        const active = i === cursor    ? '\x1B[36m›\x1B[0m' : ' ';
+        const label  = i === cursor    ? `\x1B[36m${opt.label}\x1B[0m` : opt.label;
+        process.stdout.write(`  ${active} ${check}  ${label}\n`);
+      });
+    }
+
+    render.drawn = false;
+    render();
+
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.isTTY) process.stdin.setRawMode(true);
+
+    process.stdin.on('keypress', function handler(_, key) {
+      if (!key) return;
+
+      if (key.name === 'up')    cursor = (cursor - 1 + options.length) % options.length;
+      if (key.name === 'down')  cursor = (cursor + 1) % options.length;
+      if (key.name === 'space') selected.has(cursor) ? selected.delete(cursor) : selected.add(cursor);
+
+      if (key.name === 'return' || key.name === 'enter') {
+        process.stdin.removeListener('keypress', handler);
+        if (process.stdin.isTTY) process.stdin.setRawMode(false);
+        process.stdout.write('\n');
+        resolve(options.filter((_, i) => selected.has(i)).map(o => o.value));
+        return;
+      }
+
+      if (key.ctrl && key.name === 'c') process.exit(0);
+
+      render();
+    });
+  });
+}
+
+function commandExists(cmd) {
+  return spawnSync(cmd, ['--version'], { stdio: 'pipe', shell: true }).status === 0;
+}
+
+function run(cmd, opts = {}) {
+  execSync(cmd, { stdio: 'inherit', ...opts });
+}
+
+function isSymlink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+function symlink(source, target, label, type = 'dir') {
+  const exists = fs.existsSync(target) || isSymlink(target);
+  if (exists) {
+    if (isSymlink(target)) { console.log(`  ✅ ${label} (already set)`); return; }
+    console.warn(`  ⚠️  ${label} — exists as real ${type}, skipping`);
+    return;
+  }
+  const parent = path.dirname(target);
+  if (!fs.existsSync(parent)) fs.mkdirSync(parent, { recursive: true });
+  fs.symlinkSync(source, target, type);
+  console.log(`  ✅ ${label}`);
+}
+
+function writeJSON(filePath, data, label) {
+  const content = JSON.stringify(data, null, 2);
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
+    console.log(`  ✅ ${label} (already up to date)`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  console.log(`  ✅ ${label}`);
+}
+
+function writeFile(filePath, content, label) {
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) {
+    console.log(`  ✅ ${label} (already up to date)`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  console.log(`  ✅ ${label}`);
+}
+
+// ─── Stack detection ──────────────────────────────────────────────────────────
+
+const FRONTEND_DEPS = ['react', 'react-dom', 'next', 'vite', 'vue', 'nuxt', 'svelte', '@angular/core', 'gatsby', '@remix-run/react'];
+const BACKEND_DEPS  = ['@nestjs/core', 'express', 'fastify', 'koa', '@hapi/hapi', 'restify'];
+
+function detectStack() {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(pkgPath)) return 'unknown';
+  const pkg  = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const deps = Object.keys({ ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) });
+  const fe   = FRONTEND_DEPS.some(d => deps.includes(d));
+  const be   = BACKEND_DEPS.some(d => deps.includes(d));
+  if (fe && be) return 'monolith';
+  if (fe) return 'frontend';
+  if (be) return 'backend';
+  return 'unknown';
+}
+
+const STACK_LABEL = { backend: 'Backend (Node/NestJS)', frontend: 'Frontend (React/Vue/Vite)', monolith: 'Monolith (full-stack)', unknown: 'Unknown' };
+
+// ─── Source paths (in package) ────────────────────────────────────────────────
+
+const pkgAgent        = path.join(packagePath, '.agent');
+const pkgInstructions = path.join(pkgAgent, 'INSTRUCTIONS.md');
+
+function pkgSkills(stack)    { return path.join(pkgAgent, stack, 'skills'); }
+function pkgWorkflows(stack) { return path.join(pkgAgent, stack, 'workflows'); }
+
+// Relative path helper — avoids absolute paths in symlinks so they survive moves
+function rel(from, to) { return path.relative(path.dirname(from), to); }
+
+// Pick the IDE-specific module-runner variant
+function moduleRunnerSource(stack, ide) {
+  const variant = { claude: 'module-runner.claude.md', cursor: 'module-runner.cursor.md', codex: 'module-runner.codex.md' }[ide];
+  if (!variant) return null;
+  const candidate = path.join(pkgWorkflows(stack), variant);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+// ─── Serena MCP config ────────────────────────────────────────────────────────
+// Serena replaces code-review-graph as the symbolic code intelligence MCP.
+// Install: uvx --from git+https://github.com/oraios/serena serena start-mcp-server --project=.
+
+const SERENA_MCP = {
+  command: 'uvx',
+  args: ['--from', 'git+https://github.com/oraios/serena', 'serena', 'start-mcp-server', '--project=.'],
+};
+
+// ─── IDE setup ────────────────────────────────────────────────────────────────
+
+function setupClaudeCode(stack) {
+  console.log('\n── Claude Code ───────────────────────────────────────────────');
+  // Symlink each skill DIRECTORY so supporting files come along.
+  const skillsDir = pkgSkills(stack);
+  const claudeSkillsDir = path.join(projectRoot, '.claude/skills');
+  if (fs.existsSync(skillsDir)) {
+    fs.mkdirSync(claudeSkillsDir, { recursive: true });
+    for (const skillName of fs.readdirSync(skillsDir).sort()) {
+      const skillSrc = path.join(skillsDir, skillName);
+      const skillMd = path.join(skillSrc, 'SKILL.md');
+      if (fs.existsSync(skillMd) && fs.statSync(skillSrc).isDirectory()) {
+        const target = path.join(claudeSkillsDir, skillName);
+        symlink(rel(target, skillSrc), target, `.claude/skills/${skillName}/`, 'dir');
+      }
+    }
+  }
+
+  // Symlink only the Claude Code variant of module-runner as the canonical module-runner.md
+  const runnerSrc = moduleRunnerSource(stack, 'claude');
+  const claudeAgentsDir = path.join(projectRoot, '.claude/agents');
+  if (runnerSrc) {
+    fs.mkdirSync(claudeAgentsDir, { recursive: true });
+    const target = path.join(claudeAgentsDir, 'module-runner.md');
+    symlink(rel(target, runnerSrc), target, '.claude/agents/module-runner.md (Claude variant)', 'file');
+  }
+
+  symlink(rel(path.join(projectRoot, 'CLAUDE.md'), pkgInstructions), path.join(projectRoot, 'CLAUDE.md'), 'CLAUDE.md         → INSTRUCTIONS.md', 'file');
+  symlink(rel(path.join(projectRoot, 'AGENTS.md'), pkgInstructions), path.join(projectRoot, 'AGENTS.md'), 'AGENTS.md         → INSTRUCTIONS.md', 'file');
+}
+
+// Parse a single field from YAML frontmatter (--- ... ---)
+function parseFrontmatterField(content, field) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return null;
+  const line = m[1].split('\n').find(l => l.startsWith(`${field}:`));
+  if (!line) return null;
+  return line.slice(field.length + 1).trim().replace(/^["']|["']$/g, '');
+}
+
+// Write a .mdc file; skips if already up to date (safe to re-run after package update)
+function writeMdc(rulesDir, filename, { description, alwaysApply, body }) {
+  const content = [
+    '---',
+    `description: "${description}"`,
+    `alwaysApply: ${alwaysApply}`,
+    '---',
+    '',
+    body,
+  ].join('\n');
+  const dest = path.join(rulesDir, filename);
+  if (fs.existsSync(dest) && fs.readFileSync(dest, 'utf8') === content) {
+    console.log(`  ✅ .cursor/rules/${filename} (already up to date)`);
+  } else {
+    fs.writeFileSync(dest, content);
+    console.log(`  ✅ .cursor/rules/${filename}`);
+  }
+}
+
+function setupCursor(stack) {
+  console.log('\n── Cursor ────────────────────────────────────────────────────');
+
+  // Project-level MCP config for Serena
+  writeJSON(
+    path.join(projectRoot, '.cursor/mcp.json'),
+    { mcpServers: { serena: SERENA_MCP } },
+    '.cursor/mcp.json  → Serena MCP'
+  );
+
+  const rulesDir = path.join(projectRoot, '.cursor', 'rules');
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  // MDC rule — Serena (always apply: prefer symbol-level analysis over grep/read)
+  writeMdc(rulesDir, 'serena.mdc', {
+    description: 'Symbolic code analysis via Serena — prefer get_symbols_overview / find_symbol / find_referencing_symbols over grep/read',
+    alwaysApply: true,
+    body: fs.readFileSync(pkgInstructions, 'utf8'),
+  });
+
+  // MDC rules — one per skill (description-triggered, not always-on)
+  const skillsDir = pkgSkills(stack);
+  if (fs.existsSync(skillsDir)) {
+    for (const skillName of fs.readdirSync(skillsDir).sort()) {
+      const skillFile = path.join(skillsDir, skillName, 'SKILL.md');
+      if (!fs.existsSync(skillFile)) continue;
+      const skillContent = fs.readFileSync(skillFile, 'utf8');
+      const description = parseFrontmatterField(skillContent, 'description') || `${skillName} skill`;
+      writeMdc(rulesDir, `${skillName}.mdc`, { description, alwaysApply: false, body: skillContent });
+    }
+  }
+
+  // Module-runner — Cursor variant. Also wire Cursor subagents the runner depends on.
+  setupCursorSubagents(stack);
+}
+
+// Cursor subagents (.cursor/subagents/*.md) used by /module-runner (Cursor variant).
+// Each is a thin wrapper that delegates to a SKILL.md in this package.
+function setupCursorSubagents(stack) {
+  const subagentsDir = path.join(projectRoot, '.cursor', 'subagents');
+  fs.mkdirSync(subagentsDir, { recursive: true });
+
+  const SUBAGENTS = [
+    { name: 'implementer',      delegateTo: null,                   purpose: 'Implement a single module from its prompt file. Read documentation/features/<feature>/<MODULE>.md and produce code per its specification. Return JSON { files_changed, summary, blockers }.' },
+    { name: 'code-reviewer',    delegateTo: 'code-reviewer',        purpose: 'Run /code-reviewer in sub-agent mode on the diff. Return findings JSON per the skill\'s sub-agent contract.' },
+    { name: 'code-fixer',       delegateTo: null,                   purpose: 'Apply BLOCKER/HIGH/required-MED findings from a /code-reviewer JSON. Return JSON { fixed, skipped, summary }.' },
+    { name: 'security-auditor', delegateTo: 'security-assessment',  purpose: 'Run /security-assessment in sub-agent mode on the diff. Return findings JSON.' },
+    { name: 'security-fixer',   delegateTo: null,                   purpose: 'Apply CRITICAL/HIGH findings from a /security-assessment JSON. Return JSON { fixed, skipped, summary }.' },
+    { name: 'build-test-fixer', delegateTo: null,                   purpose: 'Fix build or test failures given failure output and the recently changed files. Return JSON { fixed, summary }.' },
+  ];
+
+  for (const sa of SUBAGENTS) {
+    const file = path.join(subagentsDir, `${sa.name}.md`);
+    const delegateNote = sa.delegateTo
+      ? `\nDelegate to the \`${sa.delegateTo}\` skill (.cursor/rules/${sa.delegateTo}.mdc). Follow its sub-agent mode contract.\n`
+      : '';
+    const content = [
+      '---',
+      `name: ${sa.name}`,
+      `description: "${sa.purpose}"`,
+      '---',
+      '',
+      `# Subagent: ${sa.name}`,
+      '',
+      sa.purpose,
+      delegateNote,
+      '## Constraints',
+      '- Independent context — the parent agent has provided everything you need in the prompt.',
+      '- Return structured JSON output when the parent requests it.',
+      '- Do not commit, push, or change branches.',
+      '- Use Serena for symbol-level edits where possible (`rename_symbol`, `replace_symbol_body`, `safe_delete_symbol`).',
+      '',
+    ].join('\n');
+    writeFile(file, content, `.cursor/subagents/${sa.name}.md`);
+  }
+}
+
+function setupAntigravity(stack) {
+  console.log('\n── Antigravity ───────────────────────────────────────────────');
+  symlink(rel(path.join(projectRoot, 'GEMINI.md'), pkgInstructions), path.join(projectRoot, 'GEMINI.md'), 'GEMINI.md         → INSTRUCTIONS.md', 'file');
+}
+
+function setupCodexDefaultRules() {
+  const rulesDir  = path.join(projectRoot, '.codex', 'rules');
+  const rulesFile = path.join(rulesDir, 'default.rules');
+
+  const content = [
+    '# Codex execution policy — generated by nurosys-agent-setup',
+    '# Docs: https://developers.openai.com/codex/rules',
+    '',
+    'prefix_rule(',
+    '  pattern = "npm",',
+    '  decision = "allow",',
+    '  justification = "Allow npm package management",',
+    ')',
+    '',
+    'prefix_rule(',
+    '  pattern = "git",',
+    '  decision = "allow",',
+    '  justification = "Allow git version control",',
+    ')',
+    '',
+    'prefix_rule(',
+    '  pattern = "uvx",',
+    '  decision = "allow",',
+    '  justification = "Allow uvx (for Serena MCP server)",',
+    ')',
+    '',
+    'prefix_rule(',
+    '  pattern = "node",',
+    '  decision = "allow",',
+    '  justification = "Allow node script execution",',
+    ')',
+  ].join('\n') + '\n';
+
+  writeFile(rulesFile, content, '.codex/rules/default.rules');
+}
+
+function setupCodex(stack) {
+  console.log('\n── Codex ─────────────────────────────────────────────────');
+  symlink(rel(path.join(projectRoot, 'AGENTS.md'), pkgInstructions), path.join(projectRoot, 'AGENTS.md'), 'AGENTS.md         → INSTRUCTIONS.md', 'file');
+  setupCodexDefaultRules();
+
+  // Symlink Codex variant of module-runner into a Codex-discoverable location.
+  // Codex reads AGENTS.md for project-level instructions; we also drop the runner doc
+  // alongside so users can reference it explicitly.
+  const runnerSrc = moduleRunnerSource(stack, 'codex');
+  if (runnerSrc) {
+    const target = path.join(projectRoot, '.codex', 'workflows', 'module-runner.md');
+    symlink(rel(target, runnerSrc), target, '.codex/workflows/module-runner.md (Codex variant)', 'file');
+  }
+}
+
+// ─── Serena ──────────────────────────────────────────────────────────────────
+
+function checkUvx() {
+  return commandExists('uvx');
+}
+
+async function setupSerena(ides) {
+  console.log('\n── Serena (MCP for symbolic code analysis) ───────────────────');
+  console.log('  ℹ️  Skills use Serena for symbol-level navigation and edits.');
+  console.log('     https://github.com/oraios/serena\n');
+
+  if (!checkUvx()) {
+    console.log('  ⚠️  `uvx` not found. Serena runs via uvx (part of the `uv` Python toolchain).');
+    console.log('     Install: https://docs.astral.sh/uv/getting-started/installation/');
+    const ans = await ask('  ❓ Continue setup without verifying Serena? [y/N] ');
+    if (ans !== 'y' && ans !== 'yes') return;
+  } else {
+    console.log('  ✅ uvx available — Serena will run on demand via the configured MCP entry');
+  }
+
+  // Cursor MCP already written by setupCursor()
+  if (ides.includes('cursor')) {
+    console.log('  ✅ Cursor MCP configured via .cursor/mcp.json');
+  }
+
+  // Claude Code — write or merge into project-level .mcp.json
+  if (ides.includes('claude')) {
+    const claudeMcp = path.join(projectRoot, '.mcp.json');
+    let existing = {};
+    if (fs.existsSync(claudeMcp)) {
+      try { existing = JSON.parse(fs.readFileSync(claudeMcp, 'utf8')); } catch {}
+    }
+    existing.mcpServers = existing.mcpServers || {};
+    if (!existing.mcpServers.serena) {
+      existing.mcpServers.serena = SERENA_MCP;
+      fs.writeFileSync(claudeMcp, JSON.stringify(existing, null, 2));
+      console.log('  ✅ Claude Code MCP configured (.mcp.json)');
+    } else {
+      console.log('  ✅ Claude Code MCP already configured (.mcp.json)');
+    }
+  }
+
+  // Codex — write to ~/.codex/config.toml
+  if (ides.includes('codex')) {
+    const configDir  = path.join(process.env.HOME || '', '.codex');
+    const configFile = path.join(configDir, 'config.toml');
+    const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf8') : '';
+    if (existing.includes('[mcp_servers.serena]')) {
+      console.log('  ✅ Codex MCP already configured (~/.codex/config.toml)');
+    } else {
+      const ans = await ask('  ❓ Add Serena MCP to ~/.codex/config.toml? [y/N] ');
+      if (ans === 'y' || ans === 'yes') {
+        const entry = `\n[mcp_servers.serena]\ncommand = "${SERENA_MCP.command}"\nargs = ${JSON.stringify(SERENA_MCP.args)}\n`;
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(configFile, existing + entry);
+        console.log('  ✅ Codex MCP configured (~/.codex/config.toml)');
+      }
+    }
+  }
+}
+
+// ─── .gitignore ───────────────────────────────────────────────────────────────
+
+function setupGitignore(ides) {
+  console.log('\n── .gitignore ────────────────────────────────────────────────');
+
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const entries = ['# nurosys-agents (generated — do not commit)'];
+
+  entries.push('.agents/rules');
+
+  if (ides.includes('claude')) {
+    entries.push('.claude/skills', '.claude/agents', '.mcp.json', 'CLAUDE.md', 'AGENTS.md');
+  }
+  if (ides.includes('cursor')) {
+    entries.push('.cursor/rules', '.cursor/subagents', '.cursor/mcp.json');
+  }
+  if (ides.includes('antigravity')) {
+    entries.push('GEMINI.md');
+  }
+  if (ides.includes('codex')) {
+    entries.push('.codex/rules', '.codex/workflows');
+    if (!ides.includes('claude')) entries.push('AGENTS.md');
+  }
+
+  const existing = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, 'utf8')
+    : '';
+
+  const toAdd = entries.filter(e => e.startsWith('#') || !existing.split('\n').includes(e));
+
+  if (toAdd.length <= 1) {
+    console.log('  ✅ .gitignore already up to date');
+    return;
+  }
+
+  const block = '\n' + toAdd.join('\n') + '\n';
+  fs.writeFileSync(gitignorePath, existing + block);
+  console.log(`  ✅ Added ${toAdd.length - 1} entries to .gitignore`);
+  toAdd.filter(e => !e.startsWith('#')).forEach(e => console.log(`     ${e}`));
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('🚀  nurosys-agents — setup\n');
+
+  // 1. Stack
+  let stack = detectStack();
+  console.log(`🔍  Detected stack: ${STACK_LABEL[stack]}`);
+  if (stack === 'unknown') {
+    const ans = await ask('    Choose: (b)ackend  (f)rontend  (m)onolith: ');
+    stack = ans.startsWith('f') ? 'frontend' : ans.startsWith('m') ? 'monolith' : 'backend';
+    console.log(`    Using: ${STACK_LABEL[stack]}`);
+  }
+
+  // 2. IDEs — interactive multiselect
+  const ideChoices = await multiselect('Which IDE(s) do you use?  ↑↓ move  space toggle  enter confirm', [
+    { label: 'Claude Code',  value: 'claude'      },
+    { label: 'Cursor',       value: 'cursor'       },
+    { label: 'Antigravity',  value: 'antigravity'  },
+    { label: 'Codex',        value: 'codex'        },
+  ]);
+
+  const ides = ideChoices.length > 0 ? ideChoices : ['claude'];
+  console.log(`  Setting up: ${ides.join(', ')}`);
+
+  // 3. IDE-specific wiring (includes per-IDE module-runner variant)
+  if (ides.includes('claude'))      setupClaudeCode(stack);
+  if (ides.includes('cursor'))      setupCursor(stack);
+  if (ides.includes('antigravity')) setupAntigravity(stack);
+  if (ides.includes('codex'))       setupCodex(stack);
+
+  // 4. Serena MCP
+  await setupSerena(ides);
+
+  // 5. Gitignore
+  setupGitignore(ides);
+
+  // 6. Project-memory rules (if project-memory/ exists)
+  runSetupRules();
+
+  // 7. Summary
+  console.log('\n' + '─'.repeat(60));
+  console.log('✨  Setup complete!\n');
+  console.log(`    Stack : ${STACK_LABEL[stack]}`);
+  console.log(`    IDEs  : ${ides.join(', ')}`);
+  console.log('\n    Skills available:');
+  const skillsDir = pkgSkills(stack);
+  if (fs.existsSync(skillsDir)) fs.readdirSync(skillsDir).forEach(s => console.log(`      /${s}`));
+  console.log('\n    Next steps:');
+  console.log('      1. Bootstrap project-memory  →  /create-blueprint all');
+  console.log('      2. Brainstorm a feature      →  /brainstorm <problem>');
+  console.log('      3. Plan it                   →  /architect <feature>');
+  console.log('      4. Build it autonomously     →  /module-runner documentation/features/<feature>/');
+  console.log('─'.repeat(60) + '\n');
+}
+
+main().catch(err => { console.error('\n❌ Setup failed:', err.message); process.exit(1); });