@axiomatic-labs/claudeflow 2.49.24 → 2.49.26

package/lib/install.js

@@ -27,7 +27,7 @@ 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 = ['__pycache__/', '*.pyc', '.claudeflow/test-context.json', '.claudeflow/.auth/', '.claudeflow/telemetry/', '.claudeflow/certification/', '.claudeflow/tools/'];
+const GITIGNORE_LINES = ['__pycache__/', '*.pyc', '.claudeflow/test-context.json', '.claudeflow/.auth/', '.claudeflow/telemetry/', '.claudeflow/certification/', '.claudeflow/tools/', '.claudeflow/backups/'];
 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'];
 
@@ -272,6 +272,110 @@ function copyPath(src, dst) {
   }
 }
 
+function safeRelative(base, target) {
+  const rel = path.relative(base, target);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return path.basename(target);
+  return rel;
+}
+
+function uniqueBackupPath(backupRoot, rel) {
+  const parsed = path.parse(rel);
+  let candidate = path.join(backupRoot, rel);
+  let i = 1;
+  while (fs.existsSync(candidate)) {
+    candidate = path.join(backupRoot, parsed.dir, `${parsed.name}.${i}${parsed.ext}`);
+    i++;
+  }
+  return candidate;
+}
+
+function moveAsideManagedPath(target, backupRoot, relBase) {
+  const rel = safeRelative(relBase, target);
+  const backup = uniqueBackupPath(backupRoot, rel);
+  fs.mkdirSync(path.dirname(backup), { recursive: true });
+  fs.renameSync(target, backup);
+  return backup;
+}
+
+function makeWritableTree(target) {
+  if (!fs.existsSync(target)) return;
+  const st = fs.lstatSync(target);
+  if (st.isDirectory()) {
+    try { fs.chmodSync(target, 0o755); } catch {}
+    for (const name of fs.readdirSync(target)) makeWritableTree(path.join(target, name));
+    try { fs.chmodSync(target, 0o755); } catch {}
+    return;
+  }
+  if (st.isFile()) {
+    try { fs.chmodSync(target, 0o644); } catch {}
+  }
+}
+
+function replaceManagedPath(src, dst, backupRoot, relBase) {
+  let movedAside = null;
+  if (fs.existsSync(dst)) {
+    try {
+      rmrf(dst);
+    } catch {
+      // Recover user-owned managed paths that lost write bits. Root-owned paths still require
+      // a one-time chown; the caller reports that explicitly instead of hiding the failure.
+      try { makeWritableTree(dst); rmrf(dst); }
+      catch { movedAside = moveAsideManagedPath(dst, backupRoot, relBase || path.dirname(dst)); }
+    }
+  }
+  copyPath(src, dst);
+  return { movedAside };
+}
+
+function chownTree(target, uid, gid) {
+  if (!fs.existsSync(target)) return 0;
+  let count = 0;
+  const st = fs.lstatSync(target);
+  if (st.isDirectory() && !st.isSymbolicLink()) {
+    for (const name of fs.readdirSync(target)) count += chownTree(path.join(target, name), uid, gid);
+  }
+  try { fs.chownSync(target, uid, gid); count++; } catch {}
+  return count;
+}
+
+function addExisting(paths, p) {
+  if (fs.existsSync(p)) paths.push(p);
+}
+
+function addExistingChildren(paths, dir, predicate) {
+  if (!fs.existsSync(dir)) return;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (predicate(e)) paths.push(path.join(dir, e.name));
+  }
+}
+
+function repairSudoOwnership(cwd, options = {}) {
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+  if (!isRoot && options.forceSudoOwnershipRepair !== true) return 0;
+  const uid = parseInt(options.sudoUid || process.env.SUDO_UID || '', 10);
+  const gid = parseInt(options.sudoGid || process.env.SUDO_GID || '', 10);
+  if (!Number.isInteger(uid) || uid <= 0 || !Number.isInteger(gid) || gid < 0) return 0;
+
+  const paths = [];
+  addExisting(paths, path.join(cwd, '.claudeflow'));
+  addExisting(paths, path.join(cwd, 'scripts', 'claudeflow'));
+  addExisting(paths, path.join(cwd, '.claude', 'settings.json'));
+  addExistingChildren(paths, path.join(cwd, '.claude', 'skills'), e => e.isDirectory() && e.name.startsWith('claudeflow-'));
+  addExistingChildren(paths, path.join(cwd, '.claude', 'agents'), e => e.isFile() && e.name.startsWith('claudeflow-') && e.name.endsWith('.md'));
+  addExistingChildren(paths, path.join(cwd, '.agents', 'skills'), e => e.isDirectory() && e.name.startsWith('claudeflow-'));
+  addExisting(paths, path.join(cwd, '.agents', 'plugins', 'marketplace.json'));
+  addExisting(paths, path.join(cwd, '.codex', 'hooks.json'));
+  addExisting(paths, path.join(cwd, '.codex', 'config.toml'));
+  addExistingChildren(paths, path.join(cwd, '.codex', 'agents'), e => e.isFile() && e.name.startsWith('claudeflow-') && e.name.endsWith('.toml'));
+  addExisting(paths, path.join(cwd, 'plugins', 'codexflow'));
+  for (const doc of CODEX_DOCS) addExisting(paths, path.join(cwd, 'docs', doc));
+  for (const f of ['CLAUDE.md', 'AGENTS.md', '.mcp.json', '.gitignore']) addExisting(paths, path.join(cwd, f));
+
+  let count = 0;
+  for (const p of [...new Set(paths)]) count += chownTree(p, uid, gid);
+  return count;
+}
+
 function pathHash(p) {
   if (!fs.existsSync(p)) return null;
   const h = crypto.createHash('sha256');
@@ -306,8 +410,8 @@ function syncManagedGlobalDir(srcDir, dstDir, backupRoot, filter) {
         copyPath(d, path.join(backupRoot, path.basename(dstDir), e.name));
         out.backups++;
       }
-      rmrf(d);
-      copyPath(s, d);
+      const r = replaceManagedPath(s, d, backupRoot, dstDir);
+      if (r.movedAside) out.backups++;
       out.changed++;
     } catch {
       out.failed++;
@@ -606,6 +710,8 @@ function installFromPayload(src, cwd, options = {}) {
     globalAgents: 0,
     globalChanged: 0,
     globalBackups: 0,
+    localBackups: 0,
+    ownershipRepaired: 0,
     codexSkills: 0,
     codexAgents: 0,
     codexHooks: false,
@@ -627,15 +733,26 @@ function installFromPayload(src, cwd, options = {}) {
   // two steps a user most needs (the env block wires agent-teams + the autocompact window, etc.). Before this,
   // any throw in steps 1–4 silently left settings/CLAUDE.md unconfigured. Each step records its name on failure
   // so `run()` can warn instead of reporting a clean success over a partial install.
-  const step = (name, fn) => { try { fn(); } catch { out.failed.push(name); } };
+  const step = (name, fn) => { try { fn(); } catch (err) { out.failed.push(`${name}${err && err.code ? ':' + err.code : ''}`); } };
+  const stamp = new Date().toISOString().replace(/\D/g, '').slice(0, 14) + '-' + process.pid;
+  const backupRoot = path.join(cwd, '.claudeflow', 'backups', `install-${stamp}`);
+  const replace = (s, d, relBase, label) => {
+    try {
+      const r = replaceManagedPath(s, d, backupRoot, relBase || cwd);
+      if (r.movedAside) out.localBackups++;
+      return true;
+    } catch (err) {
+      out.failed.push(`${label || path.relative(cwd, d)}${err && err.code ? ':' + err.code : ''}`);
+      return false;
+    }
+  };
 
   // 1) Playbooks — always refreshed (shared system).
   step('playbooks', () => {
     const srcPlaybooks = path.join(src, '.claudeflow', 'playbooks');
     if (fs.existsSync(srcPlaybooks)) {
       const dst = path.join(cwd, '.claudeflow', 'playbooks');
-      rmrf(dst); copyDir(srcPlaybooks, dst);
-      out.playbooks = countFiles(dst);
+      if (replace(srcPlaybooks, dst, cwd, 'playbooks')) out.playbooks = countFiles(dst);
     }
   });
 
@@ -648,7 +765,7 @@ function installFromPayload(src, cwd, options = {}) {
     }
     for (const c of SHARED_CONFIGS) {
       const s = path.join(src, '.claudeflow', c);
-      if (fs.existsSync(s)) fs.copyFileSync(s, path.join(cwd, '.claudeflow', c));
+      if (fs.existsSync(s)) replace(s, path.join(cwd, '.claudeflow', c), cwd, `configs:${c}`);
     }
   });
 
@@ -671,7 +788,7 @@ function installFromPayload(src, cwd, options = {}) {
       const dst = path.join(cwd, 'scripts', 'claudeflow');
       fs.mkdirSync(dst, { recursive: true });
       for (const e of fs.readdirSync(srcScripts)) {
-        try { fs.copyFileSync(path.join(srcScripts, e), path.join(dst, e)); out.scripts++; } catch {}
+        if (replace(path.join(srcScripts, e), path.join(dst, e), cwd, `scripts:${e}`)) out.scripts++;
       }
     }
   });
@@ -685,7 +802,7 @@ function installFromPayload(src, cwd, options = {}) {
       for (const e of fs.readdirSync(srcSkills, { withFileTypes: true })) {
         if (!e.isDirectory() || !e.name.startsWith('claudeflow-')) continue;
         const d = path.join(dst, e.name);
-        try { rmrf(d); copyDir(path.join(srcSkills, e.name), d); out.skills++; } catch {}
+        if (replace(path.join(srcSkills, e.name), d, cwd, `skills:${e.name}`)) out.skills++;
       }
     }
   });
@@ -698,7 +815,7 @@ function installFromPayload(src, cwd, options = {}) {
       fs.mkdirSync(dst, { recursive: true });
       for (const e of fs.readdirSync(srcAgents, { withFileTypes: true })) {
         if (!e.isFile() || !e.name.startsWith('claudeflow-') || !e.name.endsWith('.md')) continue;
-        try { fs.copyFileSync(path.join(srcAgents, e.name), path.join(dst, e.name)); out.agents++; } catch {}
+        if (replace(path.join(srcAgents, e.name), path.join(dst, e.name), cwd, `agents:${e.name}`)) out.agents++;
       }
     }
   });
@@ -725,7 +842,7 @@ function installFromPayload(src, cwd, options = {}) {
       for (const e of fs.readdirSync(srcSkills, { withFileTypes: true })) {
         if (!e.isDirectory() || !e.name.startsWith('claudeflow-')) continue;
         const d = path.join(dst, e.name);
-        try { rmrf(d); copyDir(path.join(srcSkills, e.name), d); out.codexSkills++; } catch {}
+        if (replace(path.join(srcSkills, e.name), d, cwd, `codex-skills:${e.name}`)) out.codexSkills++;
       }
     }
   });
@@ -738,7 +855,7 @@ function installFromPayload(src, cwd, options = {}) {
       fs.mkdirSync(dst, { recursive: true });
       for (const e of fs.readdirSync(srcAgents, { withFileTypes: true })) {
         if (!e.isFile() || !e.name.startsWith('claudeflow-') || !e.name.endsWith('.toml')) continue;
-        try { fs.copyFileSync(path.join(srcAgents, e.name), path.join(dst, e.name)); out.codexAgents++; } catch {}
+        if (replace(path.join(srcAgents, e.name), path.join(dst, e.name), cwd, `codex-agents:${e.name}`)) out.codexAgents++;
       }
     }
   });
@@ -803,8 +920,7 @@ function installFromPayload(src, cwd, options = {}) {
     const srcPlugin = path.join(src, 'plugins', 'codexflow');
     if (fs.existsSync(srcPlugin)) {
       const dst = path.join(cwd, 'plugins', 'codexflow');
-      rmrf(dst); copyDir(srcPlugin, dst);
-      out.codexPlugin = countFiles(dst);
+      if (replace(srcPlugin, dst, cwd, 'codex-plugin')) out.codexPlugin = countFiles(dst);
     }
   });
 
@@ -817,7 +933,7 @@ function installFromPayload(src, cwd, options = {}) {
       for (const doc of CODEX_DOCS) {
         const s = path.join(srcDocs, doc);
         if (!fs.existsSync(s)) continue;
-        try { fs.copyFileSync(s, path.join(dstDocs, doc)); out.docs++; } catch {}
+        if (replace(s, path.join(dstDocs, doc), cwd, `docs:${doc}`)) out.docs++;
       }
     }
   });
@@ -825,6 +941,11 @@ function installFromPayload(src, cwd, options = {}) {
   // 12) .gitignore — ensure runtime and credential paths are ignored (add-if-absent; never commit creds).
   step('gitignore', () => { out.gitignore = mergeGitignore(cwd, GITIGNORE_LINES); });
 
+  // 13) If the user ran `sudo npx ... install`, avoid leaving the managed framework owned by root.
+  step('sudo-ownership', () => {
+    if (options.repairSudoOwnership === true) out.ownershipRepaired = repairSudoOwnership(cwd, options);
+  });
+
   return out;
 }
 
@@ -884,6 +1005,7 @@ async function run() {
     syncGlobalClaude: process.env.CLAUDEFLOW_NO_GLOBAL_SYNC !== '1',
     configureTools: true,
     configureSerena: true,
+    repairSudoOwnership: true,
   });
   writeLocalVersion(`v${version}`);
 
@@ -892,10 +1014,12 @@ async function run() {
   ui.success(`claudeflow v${version} installed`);
   ui.info(`  ${summary.playbooks} playbooks · ${summary.scripts} scripts · ${summary.skills} skills`
     + (summary.globalSkills || summary.globalAgents
-      ? ` · global Claude repaired (${summary.globalSkills} skills, ${summary.globalAgents} agents`
+        ? ` · global Claude repaired (${summary.globalSkills} skills, ${summary.globalAgents} agents`
         + (summary.globalBackups ? `, ${summary.globalBackups} backups` : '')
         + ')'
       : '')
+    + (summary.localBackups ? ` · ${summary.localBackups} local stale path${summary.localBackups > 1 ? 's' : ''} moved to backup` : '')
+    + (summary.ownershipRepaired ? ` · ownership restored on ${summary.ownershipRepaired} path${summary.ownershipRepaired > 1 ? 's' : ''}` : '')
     + (summary.codexSkills ? ` · ${summary.codexSkills} Codex skills` : '')
     + (summary.codexAgents ? ` · ${summary.codexAgents} Codex agents` : '')
     + (summary.codexHooks ? ' · Codex hooks merged' : '')
@@ -909,6 +1033,12 @@ async function run() {
     + (summary.agentsMd ? ' · AGENTS.md guidance synced' : ''));
   if (summary.failed && summary.failed.length) {
     ui.warn(`  some steps did not complete: ${summary.failed.join(', ')}. Re-run \`npx @axiomatic-labs/claudeflow@latest install\` (the @latest avoids a stale npx cache).`);
+    if (summary.failed.some(f => /:EACCES|:EPERM/.test(f))) {
+      ui.warn('  Permission repair: one or more managed claudeflow paths are not writable by your user.');
+      ui.warn('  From the project root, run once:');
+      ui.warn('    sudo chown -R "$(whoami):$(id -gn)" .claudeflow scripts/claudeflow .claude/skills/claudeflow-* .claude/agents/claudeflow-* .agents/skills/claudeflow-* .codex/agents/claudeflow-* plugins/codexflow');
+      ui.warn('  Then re-run: npx @axiomatic-labs/claudeflow@latest install');
+    }
   }
   ui.done(`Describe a change and the ${ui.BOLD}claudeflow-implementer${ui.RESET} agent will build it.`);
 }
@@ -928,5 +1058,6 @@ module.exports.optionalSerenaCommand = optionalSerenaCommand;
 module.exports.serenaMcpServer = serenaMcpServer;
 module.exports.serenaCodexToml = serenaCodexToml;
 module.exports.ensureManagedTools = ensureManagedTools;
+module.exports.repairSudoOwnership = repairSudoOwnership;
 module.exports.ensureSerenaTool = ensureSerenaTool;
 module.exports.ensureAstGrepTool = ensureAstGrepTool;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.49.24",
+  "version": "2.49.26",
   "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"