@codebyplan/cli 3.0.3 → 3.2.0

package/dist/cli.js

@@ -37,7 +37,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "3.0.3";
+    VERSION = "3.2.0";
     PACKAGE_NAME = "@codebyplan/cli";
   }
 });
@@ -465,6 +465,7 @@ async function executeSyncToLocal(options) {
   const worktree = await isGitWorktree(projectPath);
   const byType = {};
   const totals = { created: 0, updated: 0, deleted: 0, unchanged: 0 };
+  const dbOnlyFiles = [];
   for (const [syncKey, typeName] of Object.entries(syncKeyToType)) {
     if (worktree && typeName === "command") {
       byType["commands"] = { created: [], updated: [], deleted: [], unchanged: [] };
@@ -489,6 +490,13 @@ async function executeSyncToLocal(options) {
       const fullPath = join2(targetDir, relPath);
       const localContent = localFiles.get(relPath);
       if (localContent === void 0) {
+        const remoteFile = remoteFiles.find((f) => f.name === name);
+        dbOnlyFiles.push({
+          type: typeName,
+          name,
+          category: remoteFile?.category ?? null,
+          localPath: fullPath
+        });
         if (!dryRun) {
           await mkdir(dirname(fullPath), { recursive: true });
           await writeFile(fullPath, content, "utf-8");
@@ -659,7 +667,7 @@ async function executeSyncToLocal(options) {
   if (!dryRun) {
     await apiPut(`/repos/${repoId}`, { claude_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
   }
-  return { byType, totals };
+  return { byType, totals, dbOnlyFiles };
 }
 var typeConfig, syncKeyToType;
 var init_sync_engine = __esm({
@@ -1055,6 +1063,90 @@ async function confirmProceed(message) {
     rl.close();
   }
 }
+function parseReviewAction(input, fallback) {
+  const a = input.trim().toLowerCase();
+  switch (a) {
+    case "d":
+    case "delete":
+      return { action: "delete", all: false };
+    case "p":
+    case "pull":
+      return { action: "pull", all: false };
+    case "s":
+    case "push":
+      return { action: "push", all: false };
+    case "k":
+    case "skip":
+      return { action: "skip", all: false };
+    case "da":
+      return { action: "delete", all: true };
+    case "pa":
+      return { action: "pull", all: true };
+    case "sa":
+      return { action: "push", all: true };
+    case "ka":
+      return { action: "skip", all: true };
+    case "":
+      return { action: fallback, all: false };
+    default:
+      return { action: fallback, all: false };
+  }
+}
+async function promptReviewMode() {
+  const rl = createInterface2({ input: stdin2, output: stdout2 });
+  try {
+    const answer = await rl.question("  Review [o]ne-by-one or [f]older-by-folder? ");
+    const a = answer.trim().toLowerCase();
+    return a === "f" || a === "folder" ? "folder" : "file";
+  } finally {
+    rl.close();
+  }
+}
+async function reviewFilesOneByOne(items, label, plannedAction) {
+  const rl = createInterface2({ input: stdin2, output: stdout2 });
+  const results = [];
+  try {
+    let applyAll = null;
+    for (const item of items) {
+      if (applyAll) {
+        results.push(applyAll);
+        continue;
+      }
+      const planned = plannedAction(item);
+      const answer = await rl.question(
+        `    ${label(item)} (${planned}) \u2014 [d]elete [p]ull pu[s]h s[k]ip: `
+      );
+      const { action, all } = parseReviewAction(answer, planned);
+      results.push(action);
+      if (all) applyAll = action;
+    }
+  } finally {
+    rl.close();
+  }
+  return results;
+}
+async function reviewFolder(folderName, items, label, plannedAction) {
+  console.log(`
+  ${folderName} (${items.length} files):`);
+  for (const item of items) {
+    console.log(`    ${label(item)} (${plannedAction(item)})`);
+  }
+  const rl = createInterface2({ input: stdin2, output: stdout2 });
+  let answer;
+  try {
+    answer = await rl.question(
+      `  Action for all: [d]elete [p]ull pu[s]h s[k]ip [o]ne-by-one: `
+    );
+  } finally {
+    rl.close();
+  }
+  const a = answer.trim().toLowerCase();
+  if (a === "o" || a === "one-by-one") {
+    return reviewFilesOneByOne(items, label, plannedAction);
+  }
+  const { action } = parseReviewAction(a, "skip");
+  return items.map(() => action);
+}
 var init_confirm = __esm({
   "src/cli/confirm.ts"() {
     "use strict";
@@ -1062,7 +1154,7 @@ var init_confirm = __esm({
 });
 
 // src/lib/tech-detect.ts
-import { readFile as readFile6, access } from "node:fs/promises";
+import { readFile as readFile6, access, readdir as readdir4 } from "node:fs/promises";
 import { join as join6 } from "node:path";
 async function fileExists(filePath) {
   try {
@@ -1072,15 +1164,56 @@ async function fileExists(filePath) {
     return false;
   }
 }
-async function detectTechStack(projectPath) {
+async function discoverMonorepoApps(projectPath) {
+  const apps = [];
+  const patterns = [];
+  try {
+    const raw = await readFile6(join6(projectPath, "pnpm-workspace.yaml"), "utf-8");
+    const matches = raw.match(/^\s*-\s*['"]?([^'"#\n]+)['"]?/gm);
+    if (matches) {
+      for (const m of matches) {
+        const pattern = m.replace(/^\s*-\s*['"]?/, "").replace(/['"]?\s*$/, "").trim();
+        if (pattern) patterns.push(pattern);
+      }
+    }
+  } catch {
+  }
+  if (patterns.length === 0) {
+    try {
+      const raw = await readFile6(join6(projectPath, "package.json"), "utf-8");
+      const pkg = JSON.parse(raw);
+      const ws = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces?.packages;
+      if (ws) patterns.push(...ws);
+    } catch {
+    }
+  }
+  for (const pattern of patterns) {
+    if (pattern.endsWith("/*")) {
+      const dir = pattern.slice(0, -2);
+      const absDir = join6(projectPath, dir);
+      try {
+        const entries = await readdir4(absDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const relPath = join6(dir, entry.name);
+            const absPath = join6(absDir, entry.name);
+            if (await fileExists(join6(absPath, "package.json"))) {
+              apps.push({ name: entry.name, path: relPath, absPath });
+            }
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return apps;
+}
+async function detectFromDirectory(dirPath) {
   const seen = /* @__PURE__ */ new Map();
   try {
-    const raw = await readFile6(join6(projectPath, "package.json"), "utf-8");
+    const raw = await readFile6(join6(dirPath, "package.json"), "utf-8");
     const pkg = JSON.parse(raw);
-    const allDeps = {
-      ...pkg.dependencies,
-      ...pkg.devDependencies
-    };
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     for (const depName of Object.keys(allDeps)) {
       const rule = PACKAGE_MAP[depName];
       if (rule) {
@@ -1088,13 +1221,23 @@ async function detectTechStack(projectPath) {
         if (!seen.has(key)) {
           seen.set(key, { name: rule.name, category: rule.category });
         }
+        continue;
+      }
+      for (const { prefix, rule: prefixRule } of PACKAGE_PREFIX_MAP) {
+        if (depName.startsWith(prefix)) {
+          const key = prefixRule.name.toLowerCase();
+          if (!seen.has(key)) {
+            seen.set(key, { name: prefixRule.name, category: prefixRule.category });
+          }
+          break;
+        }
       }
     }
   } catch {
   }
   for (const { file, rule } of CONFIG_FILE_MAP) {
     const key = rule.name.toLowerCase();
-    if (!seen.has(key) && await fileExists(join6(projectPath, file))) {
+    if (!seen.has(key) && await fileExists(join6(dirPath, file))) {
       seen.set(key, { name: rule.name, category: rule.category });
     }
   }
@@ -1104,33 +1247,95 @@ async function detectTechStack(projectPath) {
     return a.name.localeCompare(b.name);
   });
 }
+async function detectTechStack(projectPath) {
+  const repo = await detectFromDirectory(projectPath);
+  const discoveredApps = await discoverMonorepoApps(projectPath);
+  const apps = [];
+  for (const app of discoveredApps) {
+    const stack = await detectFromDirectory(app.absPath);
+    if (stack.length > 0) {
+      apps.push({ name: app.name, path: app.path, stack });
+    }
+  }
+  const flatMap = /* @__PURE__ */ new Map();
+  for (const entry of repo) {
+    flatMap.set(entry.name.toLowerCase(), entry);
+  }
+  for (const app of apps) {
+    for (const entry of app.stack) {
+      const key = entry.name.toLowerCase();
+      if (!flatMap.has(key)) {
+        flatMap.set(key, entry);
+      }
+    }
+  }
+  const flat = Array.from(flatMap.values()).sort((a, b) => {
+    const catCmp = a.category.localeCompare(b.category);
+    if (catCmp !== 0) return catCmp;
+    return a.name.localeCompare(b.name);
+  });
+  return { repo, apps, flat };
+}
 function mergeTechStack(remote, detected) {
+  const remoteResult = Array.isArray(remote) ? { repo: remote, apps: [], flat: remote } : remote;
   const seen = /* @__PURE__ */ new Map();
-  for (const entry of remote) {
+  for (const entry of remoteResult.flat) {
     seen.set(entry.name.toLowerCase(), entry);
   }
   const added = [];
-  for (const entry of detected) {
+  for (const entry of detected.flat) {
     const key = entry.name.toLowerCase();
     if (!seen.has(key)) {
       seen.set(key, entry);
       added.push(entry);
     }
   }
-  const merged = Array.from(seen.values()).sort((a, b) => {
+  const flat = Array.from(seen.values()).sort((a, b) => {
     const catCmp = a.category.localeCompare(b.category);
     if (catCmp !== 0) return catCmp;
     return a.name.localeCompare(b.name);
   });
+  const merged = {
+    repo: detected.repo,
+    apps: detected.apps,
+    flat
+  };
   return { merged, added };
 }
 function parseTechStack(raw) {
+  if (Array.isArray(raw)) {
+    return raw.filter(
+      (item) => typeof item === "object" && item !== null && typeof item.name === "string" && typeof item.category === "string"
+    );
+  }
+  if (typeof raw === "object" && raw !== null && "flat" in raw) {
+    return parseTechStack(raw.flat);
+  }
+  return [];
+}
+function parseAppTechStacks(raw) {
   if (!Array.isArray(raw)) return [];
   return raw.filter(
-    (item) => typeof item === "object" && item !== null && typeof item.name === "string" && typeof item.category === "string"
-  );
+    (item) => typeof item === "object" && item !== null && typeof item.name === "string" && typeof item.path === "string" && Array.isArray(item.stack)
+  ).map((item) => ({
+    name: item.name,
+    path: item.path,
+    stack: parseTechStack(item.stack)
+  }));
+}
+function parseTechStackResult(raw) {
+  if (typeof raw === "object" && raw !== null && !Array.isArray(raw) && "flat" in raw) {
+    const obj = raw;
+    return {
+      repo: parseTechStack(obj.repo),
+      apps: parseAppTechStacks(obj.apps),
+      flat: parseTechStack(obj.flat)
+    };
+  }
+  const flat = parseTechStack(raw);
+  return { repo: flat, apps: [], flat };
 }
-var PACKAGE_MAP, CONFIG_FILE_MAP;
+var PACKAGE_MAP, PACKAGE_PREFIX_MAP, CONFIG_FILE_MAP;
 var init_tech_detect = __esm({
   "src/lib/tech-detect.ts"() {
     "use strict";
@@ -1173,17 +1378,50 @@ var init_tech_detect = __esm({
       playwright: { name: "Playwright", category: "testing" },
       "@playwright/test": { name: "Playwright", category: "testing" },
       cypress: { name: "Cypress", category: "testing" },
+      supertest: { name: "Supertest", category: "testing" },
       // Build tools
       turbo: { name: "Turborepo", category: "build" },
       vite: { name: "Vite", category: "build" },
       webpack: { name: "Webpack", category: "build" },
       esbuild: { name: "esbuild", category: "build" },
       rollup: { name: "Rollup", category: "build" },
+      nx: { name: "Nx", category: "build" },
+      lerna: { name: "Lerna", category: "build" },
+      tsup: { name: "tsup", category: "build" },
+      "@swc/core": { name: "SWC", category: "build" },
+      parcel: { name: "Parcel", category: "build" },
       // Tools
       eslint: { name: "ESLint", category: "tool" },
       prettier: { name: "Prettier", category: "tool" },
-      "@biomejs/biome": { name: "Biome", category: "tool" }
-    };
+      "@biomejs/biome": { name: "Biome", category: "tool" },
+      storybook: { name: "Storybook", category: "tool" },
+      // Component libs
+      "@mui/material": { name: "MUI", category: "component-lib" },
+      "@chakra-ui/react": { name: "Chakra UI", category: "component-lib" },
+      "@mantine/core": { name: "Mantine", category: "component-lib" },
+      // GraphQL
+      graphql: { name: "GraphQL", category: "graphql" },
+      "@apollo/client": { name: "Apollo Client", category: "graphql" },
+      urql: { name: "urql", category: "graphql" },
+      "graphql-request": { name: "graphql-request", category: "graphql" },
+      // Documentation
+      typedoc: { name: "TypeDoc", category: "documentation" },
+      "@docusaurus/core": { name: "Docusaurus", category: "documentation" },
+      vitepress: { name: "VitePress", category: "documentation" },
+      // Code quality
+      husky: { name: "Husky", category: "quality" },
+      "lint-staged": { name: "lint-staged", category: "quality" },
+      commitlint: { name: "commitlint", category: "quality" },
+      "@commitlint/cli": { name: "commitlint", category: "quality" },
+      // Mobile
+      "react-native": { name: "React Native", category: "mobile" },
+      expo: { name: "Expo", category: "mobile" }
+    };
+    PACKAGE_PREFIX_MAP = [
+      { prefix: "@radix-ui/", rule: { name: "Radix UI", category: "component-lib" } },
+      { prefix: "@storybook/", rule: { name: "Storybook", category: "tool" } },
+      { prefix: "@testing-library/", rule: { name: "Testing Library", category: "testing" } }
+    ];
     CONFIG_FILE_MAP = [
       { file: "tsconfig.json", rule: { name: "TypeScript", category: "language" } },
       { file: "next.config.js", rule: { name: "Next.js", category: "framework" } },
@@ -1195,7 +1433,13 @@ var init_tech_detect = __esm({
       { file: "docker-compose.yml", rule: { name: "Docker", category: "deployment" } },
       { file: "docker-compose.yaml", rule: { name: "Docker", category: "deployment" } },
       { file: "Dockerfile", rule: { name: "Docker", category: "deployment" } },
-      { file: "vercel.json", rule: { name: "Vercel", category: "deployment" } }
+      { file: "vercel.json", rule: { name: "Vercel", category: "deployment" } },
+      { file: ".storybook/main.js", rule: { name: "Storybook", category: "tool" } },
+      { file: ".storybook/main.ts", rule: { name: "Storybook", category: "tool" } },
+      { file: ".storybook/main.mjs", rule: { name: "Storybook", category: "tool" } },
+      { file: "components.json", rule: { name: "shadcn/ui", category: "component-lib" } },
+      { file: "nx.json", rule: { name: "Nx", category: "build" } },
+      { file: "lerna.json", rule: { name: "Lerna", category: "build" } }
     ];
   }
 });
@@ -1205,7 +1449,7 @@ var sync_exports = {};
 __export(sync_exports, {
   runSync: () => runSync
 });
-import { readFile as readFile7, writeFile as writeFile3, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
+import { readFile as readFile7, writeFile as writeFile3, mkdir as mkdir2, chmod as chmod2, unlink as unlink2 } from "node:fs/promises";
 import { join as join7, dirname as dirname2 } from "node:path";
 async function runSync() {
   const flags = parseFlags(3);
@@ -1252,7 +1496,7 @@ async function runSync() {
         localContent: local.content,
         remoteContent: null,
         pushContent: reverseSubstituteVariables(local.content, repoData),
-        filePath: null,
+        filePath: getLocalFilePath(claudeDir, projectPath, { type: local.type, name: local.name, category: local.category }),
         type: local.type,
         name: local.name,
         category: local.category,
@@ -1295,7 +1539,7 @@ async function runSync() {
         action,
         localContent: local.content,
         remoteContent: resolvedRemote,
-        pushContent: action === "push" ? reverseSubstituteVariables(local.content, repoData) : null,
+        pushContent: reverseSubstituteVariables(local.content, repoData),
         filePath: getLocalFilePath(claudeDir, projectPath, remote),
         type: local.type,
         name: local.name,
@@ -1306,48 +1550,106 @@ async function runSync() {
   }
   const pulls = plan.filter((p) => p.action === "pull");
   const pushes = plan.filter((p) => p.action === "push");
-  if (pulls.length > 0) {
-    console.log(`  Pull (DB \u2192 local): ${pulls.length}`);
-    for (const p of pulls) console.log(`    \u2193 ${p.displayPath}`);
+  const remoteOnly = plan.filter((p) => p.action === "pull" && p.localContent === null);
+  const contentPulls = pulls.filter((p) => p.localContent !== null);
+  if (contentPulls.length > 0) {
+    console.log(`  Pull (DB \u2192 local): ${contentPulls.length}`);
+    for (const p of contentPulls) console.log(`    \u2193 ${p.displayPath}`);
   }
   if (pushes.length > 0) {
     console.log(`  Push (local \u2192 DB): ${pushes.length}`);
     for (const p of pushes) console.log(`    \u2191 ${p.displayPath}`);
   }
-  if (pulls.length === 0 && pushes.length === 0) {
+  if (remoteOnly.length > 0) {
+    console.log(`
+  DB-only (not on disk): ${remoteOnly.length}`);
+    for (const p of remoteOnly) console.log(`    \u2715 ${p.displayPath}`);
+  }
+  if (contentPulls.length === 0 && pushes.length === 0 && remoteOnly.length === 0) {
     console.log("  All .claude/ files in sync.");
   }
   if (plan.length > 0 && !dryRun) {
-    if (!force && pulls.length + pushes.length > 0) {
-      console.log();
-      const confirmed = await confirmProceed();
-      if (!confirmed) {
-        console.log("  Cancelled.\n");
-        return;
+    if (!force) {
+      const agreed = await confirmProceed(`
+  Agree with sync? [Y/n] `);
+      if (!agreed) {
+        const mode = await promptReviewMode();
+        if (mode === "file") {
+          const actions = await reviewFilesOneByOne(
+            plan,
+            (p) => p.displayPath,
+            (p) => p.action
+          );
+          for (let i = 0; i < plan.length; i++) {
+            plan[i].action = actions[i];
+          }
+        } else {
+          const groups = groupByType(plan);
+          for (const [typeName, items] of groups) {
+            const actions = await reviewFolder(
+              typeName,
+              items,
+              (p) => p.displayPath,
+              (p) => p.action
+            );
+            for (let i = 0; i < items.length; i++) {
+              items[i].action = actions[i];
+            }
+          }
+        }
       }
     }
-    for (const p of pulls) {
-      if (p.filePath && p.remoteContent !== null) {
-        await mkdir2(dirname2(p.filePath), { recursive: true });
-        await writeFile3(p.filePath, p.remoteContent, "utf-8");
-        if (p.isHook) await chmod2(p.filePath, 493);
+    const toPull = plan.filter((p) => p.action === "pull");
+    const toPush = plan.filter((p) => p.action === "push");
+    const toDelete = plan.filter((p) => p.action === "delete");
+    const skipped = plan.filter((p) => p.action === "skip");
+    if (toPull.length + toPush.length + toDelete.length === 0) {
+      console.log("\n  All items skipped \u2014 no changes applied.");
+    } else {
+      for (const p of toPull) {
+        if (p.filePath && p.remoteContent !== null) {
+          await mkdir2(dirname2(p.filePath), { recursive: true });
+          await writeFile3(p.filePath, p.remoteContent, "utf-8");
+          if (p.isHook) await chmod2(p.filePath, 493);
+        }
+      }
+      const toUpsert = toPush.filter((p) => p.pushContent !== null).map((p) => ({
+        type: p.type,
+        name: p.name,
+        category: p.category,
+        content: p.pushContent
+      }));
+      if (toUpsert.length > 0) {
+        await apiPost("/sync/files", {
+          repo_id: repoId,
+          files: toUpsert
+        });
       }
+      if (toDelete.length > 0) {
+        const deleteKeys = toDelete.map((p) => ({
+          type: p.type,
+          name: p.name,
+          category: p.category
+        }));
+        await apiPost("/sync/files", {
+          repo_id: repoId,
+          delete_keys: deleteKeys
+        });
+        for (const p of toDelete) {
+          if (p.filePath) {
+            try {
+              await unlink2(p.filePath);
+            } catch {
+            }
+          }
+        }
+      }
+      await apiPut(`/repos/${repoId}`, { claude_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
+      console.log(
+        `
+  Applied: ${toPull.length} pulled, ${toPush.length} pushed, ${toDelete.length} deleted` + (skipped.length > 0 ? `, ${skipped.length} skipped` : "")
+      );
     }
-    const toUpsert = pushes.filter((p) => p.pushContent !== null).map((p) => ({
-      type: p.type,
-      name: p.name,
-      category: p.category,
-      content: p.pushContent
-    }));
-    if (toUpsert.length > 0) {
-      await apiPost("/sync/files", {
-        repo_id: repoId,
-        files: toUpsert
-      });
-    }
-    await apiPut(`/repos/${repoId}`, { claude_sync_at: (/* @__PURE__ */ new Date()).toISOString() });
-    console.log(`
-  Applied: ${pulls.length} pulled, ${pushes.length} pushed`);
   } else if (dryRun) {
     console.log("\n  (dry-run \u2014 no changes)");
   }
@@ -1449,14 +1751,17 @@ async function syncConfig(repoId, projectPath, dryRun) {
 async function syncTechStack(repoId, projectPath, dryRun) {
   try {
     const detected = await detectTechStack(projectPath);
-    if (detected.length === 0) {
+    if (detected.flat.length === 0) {
       console.log("    No tech stack detected.");
       return;
     }
     const repoRes = await apiGet(`/repos/${repoId}`);
-    const remote = parseTechStack(repoRes.data.tech_stack);
+    const remote = parseTechStackResult(repoRes.data.tech_stack);
     const { merged, added } = mergeTechStack(remote, detected);
-    console.log(`    ${detected.length} detected${added.length > 0 ? ` (${added.length} new)` : ""}`);
+    console.log(`    ${detected.flat.length} detected${added.length > 0 ? ` (${added.length} new)` : ""}`);
+    if (detected.apps.length > 0) {
+      console.log(`    Apps: ${detected.apps.map((a) => a.name).join(", ")}`);
+    }
     for (const entry of added) {
       console.log(`      + ${entry.name} (${entry.category})`);
     }
@@ -1467,6 +1772,25 @@ async function syncTechStack(repoId, projectPath, dryRun) {
     console.log("    Tech stack detection skipped.");
   }
 }
+function groupByType(items) {
+  const groups = /* @__PURE__ */ new Map();
+  const typeLabels = {
+    command: "Commands",
+    agent: "Agents",
+    skill: "Skills",
+    rule: "Rules",
+    hook: "Hooks",
+    template: "Templates",
+    settings: "Settings"
+  };
+  for (const item of items) {
+    const label = typeLabels[item.type] ?? item.type;
+    const group = groups.get(label) ?? [];
+    group.push(item);
+    groups.set(label, group);
+  }
+  return groups;
+}
 function getLocalFilePath(claudeDir, projectPath, remote) {
   const typeConfig2 = {
     command: { dir: "commands", ext: ".md" },
@@ -24031,17 +24355,52 @@ function registerWriteTools(server) {
   }, async ({ repo_id, project_path }) => {
     try {
       const syncResult = await executeSyncToLocal({ repoId: repo_id, projectPath: project_path });
-      const { byType, totals } = syncResult;
+      const { byType, totals, dbOnlyFiles } = syncResult;
       const summary = {
         ...byType,
         totals: { created: totals.created, updated: totals.updated, deleted: totals.deleted },
         message: totals.created + totals.updated + totals.deleted === 0 ? "All files up to date" : `Synced: ${totals.created} created, ${totals.updated} updated, ${totals.deleted} deleted`
       };
+      if (dbOnlyFiles.length > 0) {
+        summary.db_only_files = dbOnlyFiles;
+        summary.message += `
+
+${dbOnlyFiles.length} file(s) exist in DB but were missing locally (recreated). Use delete_claude_files to remove them from DB if they were intentionally deleted.`;
+      }
       return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
   });
+  server.registerTool("delete_claude_files", {
+    description: "Soft-delete claude files from the CodeByPlan DB. Use after sync_claude_files reports db_only_files that should be removed. Each file is identified by type, name, and optional category.",
+    inputSchema: {
+      repo_id: external_exports.string().uuid().describe("Repository ID"),
+      files: external_exports.array(external_exports.object({
+        type: external_exports.string().describe("File type: command, agent, skill, rule, hook, template, docs_stack"),
+        name: external_exports.string().describe("File name"),
+        category: external_exports.string().nullable().optional().describe("Category (for commands: e.g. 'development/checkpoint')")
+      })).describe("Files to soft-delete from DB")
+    }
+  }, async ({ repo_id, files }) => {
+    try {
+      const res = await apiPost("/sync/files", {
+        repo_id,
+        delete_keys: files
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            deleted: res.data.deleted,
+            message: `Soft-deleted ${res.data.deleted} file(s) from DB. Run sync_claude_files to clean up local copies.`
+          }, null, 2)
+        }]
+      };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
   server.registerTool("update_session_state", {
     description: "Update session state for a repo. Actions: activate (deactivates other repos), deactivate, pause, refresh, clear_refresh.",
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codebyplan/cli",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "MCP server for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {