@axiomatic-labs/claudeflow 2.10.71 → 2.10.73

package/lib/install.js

@@ -9,11 +9,17 @@ const ui = require('./ui.js');
 // Template skills are shipped inside the ZIP. Copy every claudeflow-* skill
 // from the release so template subskills stay in sync, while preserving any
 // user-generated skills that are not part of the shipped asset.
+const TEMPLATE_AGENTS = new Set(['claudeflow-explorer', 'claudeflow-planner', 'example-agent']);
+const TEMPLATE_MANAGED_MANIFEST = path.join('.claude', 'config', 'template-managed-manifest.json');
+const CLAUDE_BACKUP_ROOT = '.claudeflow-backups';
 
 async function run() {
   const current = readLocalVersion();
   const isUpdate = !!current;
   let copiedTemplateSkillCount = 0;
+  let staleRemovedCount = 0;
+  let managedPathCount = 0;
+  let backupPath = null;
 
   ui.banner(current || undefined);
 
@@ -41,11 +47,27 @@ async function run() {
   fs.mkdirSync(tmpExtract, { recursive: true });
 
   const cwd = process.cwd();
+  backupPath = createPreInstallBackup(cwd, {
+    isUpdate,
+    currentVersion: current,
+  });
 
   try {
     ui.step('Extracting template files...');
     execSync(`unzip -o "${tmpZip}" -d "${tmpExtract}"`, { stdio: 'pipe' });
     const srcClaude = path.join(tmpExtract, '.claude');
+    const nextManagedPaths = collectManagedPathsFromRelease(tmpExtract);
+    const previousManifest = readTemplateManagedManifest(cwd);
+    const previousManagedPaths = previousManifest
+      ? previousManifest.managedPaths
+      : collectLegacyManagedPathsFromDisk(cwd);
+
+    if (isUpdate && !previousManifest) {
+      ui.info('No template-managed manifest found. Running aggressive legacy prune for managed paths.');
+    }
+
+    const staleManagedPaths = [...previousManagedPaths].filter((relPath) => !nextManagedPaths.has(relPath));
+    staleRemovedCount = pruneStaleManagedPaths(cwd, staleManagedPaths);
 
     // Copy settings.json
     const srcSettings = path.join(srcClaude, 'settings.json');
@@ -91,7 +113,6 @@ async function run() {
     }
 
     // Copy template agents (only template-managed, preserve user agents)
-    const TEMPLATE_AGENTS = new Set(['claudeflow-explorer', 'claudeflow-planner', 'example-agent']);
     const srcAgents = path.join(srcClaude, 'agents');
     const dstAgents = path.join(cwd, '.claude', 'agents');
     if (fs.existsSync(srcAgents)) {
@@ -128,6 +149,11 @@ async function run() {
 
     // Write version file
     writeLocalVersion(version);
+    nextManagedPaths.add(normalizeRelativePath(path.join('.claude', '.claudeflow-version')));
+
+    // Persist managed path manifest for deterministic stale-file pruning on update
+    writeTemplateManagedManifest(cwd, version, nextManagedPaths);
+    managedPathCount = nextManagedPaths.size;
 
   } finally {
     fs.unlinkSync(tmpZip);
@@ -161,6 +187,11 @@ async function run() {
     ui.success(`${skillCount} skills (${copiedTemplateSkillCount} template skills updated, user skills preserved)`);
     ui.success(`${hookCount} hooks updated`);
     ui.success(`${docCount} docs updated`);
+    ui.success(`${staleRemovedCount} stale template-managed files removed`);
+    ui.success(`Template-managed manifest updated (${managedPathCount} paths)`);
+    if (backupPath) {
+      ui.success(`Backup created: ${path.relative(cwd, backupPath)}`);
+    }
 
     if (current === version) {
       ui.done(`Claudeflow ${version} reinstalled.`);
@@ -171,6 +202,10 @@ async function run() {
     ui.success(`${skillCount} skills installed`);
     ui.success(`${hookCount} hooks installed`);
     ui.success(`${docCount} docs installed`);
+    ui.success(`Template-managed manifest written (${managedPathCount} paths)`);
+    if (backupPath) {
+      ui.success(`Backup created: ${path.relative(cwd, backupPath)}`);
+    }
 
     ui.done(`Claudeflow ${version} installed.`);
 
@@ -387,6 +422,243 @@ function homedir() {
   return require('os').homedir();
 }
 
+function createPreInstallBackup(projectRoot, options = {}) {
+  const sourceClaudeDir = path.join(projectRoot, '.claude');
+  if (!fs.existsSync(sourceClaudeDir) || !fs.statSync(sourceClaudeDir).isDirectory()) {
+    return null;
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const modeLabel = options.isUpdate ? 'update' : 'install';
+  const fromVersion = sanitizeForPath(options.currentVersion || 'none');
+  const backupDir = path.join(
+    projectRoot,
+    CLAUDE_BACKUP_ROOT,
+    `${timestamp}-${modeLabel}-from-${fromVersion}`,
+    '.claude',
+  );
+
+  ui.step('Creating safety backup of .claude...');
+  fs.mkdirSync(path.dirname(backupDir), { recursive: true });
+  copyDirSync(sourceClaudeDir, backupDir);
+  return path.dirname(backupDir);
+}
+
+function sanitizeForPath(value) {
+  return String(value || 'none').replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/-+/g, '-');
+}
+
+function normalizeRelativePath(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function isPathInside(candidatePath, parentPath) {
+  const relative = path.relative(parentPath, candidatePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function collectFilesRecursive(rootDir) {
+  if (!fs.existsSync(rootDir)) return [];
+  const files = [];
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+      } else if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  }
+  return files;
+}
+
+function addFilesFromDir(set, rootBase, targetDir) {
+  for (const filePath of collectFilesRecursive(targetDir)) {
+    const relPath = normalizeRelativePath(path.relative(rootBase, filePath));
+    if (relPath.startsWith('.claude/')) {
+      set.add(relPath);
+    }
+  }
+}
+
+function collectManagedPathsFromRelease(extractRoot) {
+  const srcClaude = path.join(extractRoot, '.claude');
+  const managed = new Set();
+
+  const settingsPath = path.join(srcClaude, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    managed.add('.claude/settings.json');
+  }
+
+  ['runtime', 'hooks', 'templates', 'docs'].forEach((folder) => {
+    addFilesFromDir(managed, extractRoot, path.join(srcClaude, folder));
+  });
+
+  const skillsDir = path.join(srcClaude, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith('claudeflow-')) {
+        addFilesFromDir(managed, extractRoot, path.join(skillsDir, entry.name));
+      }
+    }
+  }
+
+  const agentsDir = path.join(srcClaude, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const agentName of TEMPLATE_AGENTS) {
+      const filePath = path.join(agentsDir, `${agentName}.md`);
+      if (fs.existsSync(filePath)) {
+        managed.add(normalizeRelativePath(path.join('.claude', 'agents', `${agentName}.md`)));
+      }
+    }
+  }
+
+  const tmpDir = path.join(srcClaude, 'tmp');
+  if (fs.existsSync(tmpDir)) {
+    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        managed.add(normalizeRelativePath(path.join('.claude', 'tmp', entry.name)));
+      }
+    }
+  }
+
+  const versionFile = path.join(srcClaude, '.claudeflow-version');
+  if (fs.existsSync(versionFile)) {
+    managed.add('.claude/.claudeflow-version');
+  }
+
+  return managed;
+}
+
+function collectLegacyManagedPathsFromDisk(projectRoot) {
+  const claudeflowRoot = path.join(projectRoot, '.claude');
+  const managed = new Set();
+
+  const settingsPath = path.join(claudeflowRoot, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    managed.add('.claude/settings.json');
+  }
+
+  ['runtime', 'hooks', 'templates', 'docs'].forEach((folder) => {
+    addFilesFromDir(managed, projectRoot, path.join(claudeflowRoot, folder));
+  });
+
+  const skillsDir = path.join(claudeflowRoot, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name.startsWith('claudeflow-')) {
+        addFilesFromDir(managed, projectRoot, path.join(skillsDir, entry.name));
+      }
+    }
+  }
+
+  const agentsDir = path.join(claudeflowRoot, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const agentName of TEMPLATE_AGENTS) {
+      const filePath = path.join(agentsDir, `${agentName}.md`);
+      if (fs.existsSync(filePath)) {
+        managed.add(normalizeRelativePath(path.join('.claude', 'agents', `${agentName}.md`)));
+      }
+    }
+  }
+
+  const tmpDir = path.join(claudeflowRoot, 'tmp');
+  if (fs.existsSync(tmpDir)) {
+    const entries = fs.readdirSync(tmpDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.py')) {
+        managed.add(normalizeRelativePath(path.join('.claude', 'tmp', entry.name)));
+      }
+    }
+  }
+
+  const versionFile = path.join(claudeflowRoot, '.claudeflow-version');
+  if (fs.existsSync(versionFile)) {
+    managed.add('.claude/.claudeflow-version');
+  }
+
+  return managed;
+}
+
+function readTemplateManagedManifest(projectRoot) {
+  const manifestPath = path.join(projectRoot, TEMPLATE_MANAGED_MANIFEST);
+  if (!fs.existsSync(manifestPath)) return null;
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (!Array.isArray(parsed.managed_paths)) return null;
+    const managedPaths = new Set(
+      parsed.managed_paths
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => normalizeRelativePath(entry))
+        .filter((entry) => entry.startsWith('.claude/')),
+    );
+    return {
+      version: typeof parsed.version === 'string' ? parsed.version : null,
+      managedPaths,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function writeTemplateManagedManifest(projectRoot, version, managedPaths) {
+  const manifestPath = path.join(projectRoot, TEMPLATE_MANAGED_MANIFEST);
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+  const payload = {
+    schema_version: 1,
+    version,
+    updated_at: new Date().toISOString(),
+    managed_paths: [...managedPaths].sort(),
+  };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function pruneStaleManagedPaths(projectRoot, staleRelativePaths) {
+  if (!Array.isArray(staleRelativePaths) || staleRelativePaths.length === 0) {
+    return 0;
+  }
+
+  const claudeflowRoot = path.resolve(projectRoot, '.claude');
+  let removedCount = 0;
+  const uniquePaths = [...new Set(staleRelativePaths.map((entry) => normalizeRelativePath(entry)))]
+    .filter((entry) => entry.startsWith('.claude/'))
+    .sort((a, b) => b.length - a.length);
+
+  for (const relPath of uniquePaths) {
+    const absolutePath = path.resolve(projectRoot, relPath);
+    if (!isPathInside(absolutePath, claudeflowRoot)) continue;
+    if (!fs.existsSync(absolutePath)) continue;
+
+    fs.rmSync(absolutePath, { recursive: true, force: true });
+    removedCount += 1;
+    pruneEmptyAncestors(path.dirname(absolutePath), claudeflowRoot);
+  }
+
+  return removedCount;
+}
+
+function pruneEmptyAncestors(startDir, stopDir) {
+  let current = startDir;
+  while (isPathInside(current, stopDir) && current !== stopDir) {
+    if (!fs.existsSync(current)) {
+      current = path.dirname(current);
+      continue;
+    }
+    const entries = fs.readdirSync(current);
+    if (entries.length > 0) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
 // Recursively copy a directory, creating parents as needed
 function copyDirSync(src, dst) {
   fs.mkdirSync(dst, { recursive: true });

package/package.json

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