@axiomatic-labs/claudeflow 2.49.18 → 2.49.20

package/lib/install.js

@@ -2,7 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
-const { execSync } = require('child_process');
+const { execFileSync, execSync } = require('child_process');
 const { requireAuth } = require('./auth.js');
 const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
 const { writeLocalVersion, readLocalVersion } = require('./version.js');
@@ -27,12 +27,233 @@ const PER_PROJECT_CONFIGS = ['brand.json', 'risk-signals.json', 'test-context.js
 // Paths appended to the project's .gitignore (add-if-absent). These hold TEST credentials / Playwright
 // storage state — they must NEVER be committed. test-context.json is per-project runtime state; .auth/
 // holds storageState files the orchestrator seeds for auth-gated functional verification.
-const GITIGNORE_LINES = ['.claudeflow/test-context.json', '.claudeflow/.auth/', '.claudeflow/telemetry/', '.claudeflow/certification/'];
+const GITIGNORE_LINES = ['.claudeflow/test-context.json', '.claudeflow/.auth/', '.claudeflow/telemetry/', '.claudeflow/certification/', '.claudeflow/tools/'];
 const SHARED_CONFIGS = ['playbook-map.json', 'agent-map.json'];   // always refreshed (shared system)
 const CODEX_DOCS = ['claudeflow-codex-migration.md', 'codexflow-codex-native-workflow.md', 'codexflow-local-actions.md'];
 
 function rmrf(p) { fs.rmSync(p, { recursive: true, force: true }); }
 
+function findExecutable(name) {
+  const envPath = process.env.PATH || '';
+  const exts = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+  for (const dir of envPath.split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const p = path.join(dir, process.platform === 'win32' ? name + ext : name);
+      try {
+        fs.accessSync(p, fs.constants.X_OK);
+        return p;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+function optionalSerenaCommand(options = {}) {
+  if (options.configureSerena !== true && options.configureTools !== true) return null;
+  if (options.noSerena === true || process.env.CLAUDEFLOW_NO_SERENA === '1') return null;
+  if (options.serenaCommand) return String(options.serenaCommand);
+  if (process.env.CLAUDEFLOW_SERENA_COMMAND) return process.env.CLAUDEFLOW_SERENA_COMMAND;
+  return findExecutable('serena');
+}
+
+function serenaMcpServer(command, context) {
+  return {
+    command,
+    args: ['start-mcp-server', '--project-from-cwd', `--context=${context}`, '--open-web-dashboard', 'false'],
+  };
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function serenaCodexToml(command) {
+  return [
+    '[mcp_servers.serena]',
+    `command = ${tomlString(command)}`,
+    'args = ["start-mcp-server", "--project-from-cwd", "--context=codex", "--open-web-dashboard", "false"]',
+    'startup_timeout_sec = 30',
+    'tool_timeout_sec = 120',
+    '',
+  ].join('\n');
+}
+
+function exeName(name) {
+  return process.platform === 'win32' ? `${name}.cmd` : name;
+}
+
+function managedToolsHome(options = {}) {
+  return options.toolsHome || path.join(options.homeDir || os.homedir(), '.claudeflow', 'tools');
+}
+
+function projectToolsBin(cwd) {
+  return path.join(cwd, '.claudeflow', 'tools', 'bin');
+}
+
+function runQuiet(command, args, options = {}) {
+  execFileSync(command, args, {
+    cwd: options.cwd || process.cwd(),
+    env: { ...process.env, ...(options.env || {}) },
+    stdio: 'ignore',
+    timeout: options.timeout || 120000,
+  });
+}
+
+function executableOk(command, args = ['--help']) {
+  if (!command) return false;
+  try {
+    runQuiet(command, args, { timeout: 20000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writeToolWrapper(cwd, name, target) {
+  const bin = projectToolsBin(cwd);
+  fs.mkdirSync(bin, { recursive: true });
+  if (process.platform === 'win32') {
+    const wrapper = path.join(bin, `${name}.cmd`);
+    fs.writeFileSync(wrapper, `@echo off\r\n"${target}" %*\r\n`);
+    return wrapper;
+  }
+  const wrapper = path.join(bin, name);
+  fs.writeFileSync(wrapper, `#!/usr/bin/env sh\nexec "${target}" "$@"\n`);
+  fs.chmodSync(wrapper, 0o755);
+  return wrapper;
+}
+
+function uvToolBinDir(uvCommand) {
+  try {
+    return String(execFileSync(uvCommand, ['tool', 'dir', '--bin'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20000 })).trim();
+  } catch {
+    return null;
+  }
+}
+
+function pythonVersionOk(command) {
+  if (!command) return false;
+  try {
+    const out = String(execFileSync(command, ['-c', 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 20000,
+    })).trim();
+    const [maj, min] = out.split('.').map(n => parseInt(n, 10) || 0);
+    return maj > 3 || (maj === 3 && min >= 11);
+  } catch {
+    return false;
+  }
+}
+
+function findPython311(options = {}) {
+  const candidates = [
+    options.pythonCommand,
+    process.env.CLAUDEFLOW_PYTHON_COMMAND,
+    findExecutable('python3.13'),
+    findExecutable('python3.12'),
+    findExecutable('python3.11'),
+    findExecutable('python3'),
+  ].filter(Boolean);
+  return candidates.find(pythonVersionOk) || null;
+}
+
+function venvBinPath(venv, name) {
+  return process.platform === 'win32'
+    ? path.join(venv, 'Scripts', `${name}.exe`)
+    : path.join(venv, 'bin', name);
+}
+
+function installSerenaWithPip(options = {}) {
+  const python = findPython311(options);
+  if (!python) return null;
+  const venv = path.join(managedToolsHome(options), 'serena-venv');
+  try {
+    if (!fs.existsSync(venvBinPath(venv, 'python'))) {
+      runQuiet(python, ['-m', 'venv', venv], { timeout: 180000 });
+    }
+    const venvPython = venvBinPath(venv, 'python');
+    runQuiet(venvPython, ['-m', 'pip', 'install', '-U', 'serena-agent'], { timeout: 300000 });
+    const command = venvBinPath(venv, 'serena');
+    return executableOk(command, ['--help']) ? command : null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureSerenaTool(cwd, options = {}) {
+  if (options.noSerena === true || process.env.CLAUDEFLOW_NO_SERENA === '1') {
+    return { status: 'skipped', reason: 'CLAUDEFLOW_NO_SERENA=1' };
+  }
+
+  let command = options.serenaCommand || process.env.CLAUDEFLOW_SERENA_COMMAND || findExecutable('serena');
+  if (!executableOk(command, ['--help'])) {
+    const uv = options.uvCommand || findExecutable('uv');
+    if (uv) {
+      try {
+        runQuiet(uv, ['tool', 'install', '-p', '3.13', 'serena-agent'], { timeout: 300000 });
+      } catch {}
+      const binDir = uvToolBinDir(uv);
+      const installed = binDir ? path.join(binDir, exeName('serena')) : null;
+      command = executableOk(installed, ['--help']) ? installed : findExecutable('serena');
+    }
+    if (!executableOk(command, ['--help'])) command = installSerenaWithPip(options);
+  }
+
+  if (!executableOk(command, ['--help'])) {
+    return { status: 'failed', reason: 'serena install failed; need uv or Python 3.11+ with pip' };
+  }
+  const wrapper = writeToolWrapper(cwd, 'serena', command);
+  return { status: 'ready', command: wrapper, target: command };
+}
+
+function ensureAstGrepTool(cwd, options = {}) {
+  if (options.noAstGrep === true || process.env.CLAUDEFLOW_NO_AST_GREP === '1') {
+    return { status: 'skipped', reason: 'CLAUDEFLOW_NO_AST_GREP=1' };
+  }
+
+  const home = managedToolsHome(options);
+  const prefix = path.join(home, 'ast-grep');
+  const managed = path.join(prefix, 'node_modules', '.bin', exeName('ast-grep'));
+  let command = options.astGrepCommand || process.env.CLAUDEFLOW_AST_GREP_COMMAND || null;
+  if (!executableOk(command, ['--version'])) {
+    command = executableOk(managed, ['--version'])
+      ? managed
+      : (findExecutable('ast-grep') || findExecutable('sg'));
+  }
+  if (!executableOk(command, ['--version'])) {
+    const npm = options.npmCommand || findExecutable('npm');
+    if (!npm) return { status: 'failed', reason: 'npm not found; ast-grep managed install requires npm' };
+    try {
+      fs.mkdirSync(prefix, { recursive: true });
+      runQuiet(npm, ['install', '--prefix', prefix, '@ast-grep/cli@latest'], { timeout: 300000 });
+    } catch {
+      return { status: 'failed', reason: 'npm install @ast-grep/cli failed' };
+    }
+    command = managed;
+  }
+  if (!executableOk(command, ['--version'])) {
+    return { status: 'failed', reason: 'ast-grep command did not validate after install' };
+  }
+  const wrapper = writeToolWrapper(cwd, 'ast-grep', command);
+  // `sg` is convenient on macOS, but Linux reserves `sg`; still provide the wrapper because it is project-local.
+  const sgWrapper = writeToolWrapper(cwd, 'sg', command);
+  return { status: 'ready', command: wrapper, sgCommand: sgWrapper, target: command };
+}
+
+function ensureManagedTools(cwd, options = {}) {
+  if (options.configureTools !== true || process.env.CLAUDEFLOW_NO_TOOLS === '1') {
+    return { serena: { status: 'skipped', reason: 'tool bootstrap disabled' }, astGrep: { status: 'skipped', reason: 'tool bootstrap disabled' } };
+  }
+  return {
+    serena: ensureSerenaTool(cwd, options),
+    astGrep: ensureAstGrepTool(cwd, options),
+  };
+}
+
 function copyDir(src, dst) {
   fs.mkdirSync(dst, { recursive: true });
   for (const e of fs.readdirSync(src, { withFileTypes: true })) {
@@ -393,6 +614,9 @@ function installFromPayload(src, cwd, options = {}) {
     codexPlugin: 0,
     docs: 0,
     mcp: 0,
+    serenaMcp: 0,
+    serenaCodexConfig: false,
+    tooling: {},
     gitignore: 0,
     claudeMd: false,
     agentsMd: false,
@@ -428,6 +652,17 @@ function installFromPayload(src, cwd, options = {}) {
     }
   });
 
+  // 2b) Managed tool bootstrap — installs/validates semantic-code accelerators once per machine and writes
+  // small project-local wrappers under .claudeflow/tools/bin. Deps stay outside the repo; the wrappers give
+  // agents stable commands even when their shell PATH differs from the user's interactive shell.
+  step('managed-tools', () => {
+    out.tooling = ensureManagedTools(cwd, options);
+    for (const name of ['serena', 'astGrep']) {
+      const tool = out.tooling[name];
+      if (tool && tool.status === 'failed') out.failed.push(`tools:${name}:${tool.reason}`);
+    }
+  });
+
   // 3) Scripts (hooks + scans + servers) — always refreshed. Per-file isolation so ONE bad file (a socket, a
   //    permission denial) can't abort the whole copy — let alone the later settings/CLAUDE.md steps.
   step('scripts', () => {
@@ -532,6 +767,14 @@ function installFromPayload(src, cwd, options = {}) {
     }
   });
 
+  // 7b) Optional semantic-code MCP. Serena is useful for fresh implementers, but it must not become a hidden
+  // dependency. The real install auto-registers it only when a `serena` executable already exists (or the caller
+  // passes an explicit command); tests/direct installFromPayload stay deterministic unless configureSerena=true.
+  step('serena-mcp', () => {
+    const serena = (out.tooling.serena && out.tooling.serena.command) || optionalSerenaCommand(options);
+    if (serena) out.serenaMcp = mergeMcp(cwd, { serena: serenaMcpServer(serena, 'claude-code') });
+  });
+
   // 8) AGENTS.md — upsert the Codex guidance block between markers, preserving project guidance.
   step('agents-md', () => {
     out.agentsMd = syncAgentsMd(cwd, path.join(src, 'assets', 'AGENTS.snippet.md'));
@@ -546,6 +789,10 @@ function installFromPayload(src, cwd, options = {}) {
     const srcConfig = path.join(src, '.codex', 'config.toml');
     if (fs.existsSync(srcConfig)) out.codexConfig = mergeCodexConfig(cwd, fs.readFileSync(srcConfig, 'utf8'));
   });
+  step('serena-codex-config', () => {
+    const serena = (out.tooling.serena && out.tooling.serena.command) || optionalSerenaCommand(options);
+    if (serena) out.serenaCodexConfig = mergeCodexConfig(cwd, serenaCodexToml(serena));
+  });
 
   // 10) Codex marketplace + local plugin — managed codexflow entry only; user plugins are preserved.
   step('codex-marketplace', () => {
@@ -633,7 +880,11 @@ async function run() {
   execSync(`unzip -qq -o "${tmpZip}" -d "${tmp}"`, { stdio: 'ignore' });
 
   ui.step('Installing framework...');
-  const summary = installFromPayload(tmp, cwd, { syncGlobalClaude: process.env.CLAUDEFLOW_NO_GLOBAL_SYNC !== '1' });
+  const summary = installFromPayload(tmp, cwd, {
+    syncGlobalClaude: process.env.CLAUDEFLOW_NO_GLOBAL_SYNC !== '1',
+    configureTools: true,
+    configureSerena: true,
+  });
   writeLocalVersion(`v${version}`);
 
   try { rmrf(tmp); fs.rmSync(tmpZip, { force: true }); } catch {}
@@ -649,6 +900,9 @@ async function run() {
     + (summary.codexAgents ? ` · ${summary.codexAgents} Codex agents` : '')
     + (summary.codexHooks ? ' · Codex hooks merged' : '')
     + (summary.codexConfig ? ' · Codex config synced' : '')
+    + (summary.tooling && summary.tooling.serena && summary.tooling.serena.status === 'ready' ? ' · Serena ready' : '')
+    + (summary.tooling && summary.tooling.astGrep && summary.tooling.astGrep.status === 'ready' ? ' · ast-grep ready' : '')
+    + (summary.serenaMcp || summary.serenaCodexConfig ? ' · Serena MCP configured' : '')
     + (summary.codexMarketplace ? ' · Codex plugin registered' : '')
     + (summary.mcp ? ` · ${summary.mcp} MCP server${summary.mcp > 1 ? 's' : ''} added to .mcp.json` : '')
     + (summary.claudeMd ? ' · CLAUDE.md guidance synced' : '')
@@ -670,3 +924,9 @@ module.exports.mergeGitignore = mergeGitignore;
 module.exports.mergeCodexHooks = mergeCodexHooks;
 module.exports.mergeCodexConfig = mergeCodexConfig;
 module.exports.mergeCodexMarketplace = mergeCodexMarketplace;
+module.exports.optionalSerenaCommand = optionalSerenaCommand;
+module.exports.serenaMcpServer = serenaMcpServer;
+module.exports.serenaCodexToml = serenaCodexToml;
+module.exports.ensureManagedTools = ensureManagedTools;
+module.exports.ensureSerenaTool = ensureSerenaTool;
+module.exports.ensureAstGrepTool = ensureAstGrepTool;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.49.18",
+  "version": "2.49.20",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code and Codex. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"