codebyplan 1.0.0 → 1.2.0

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.0.0";
+    VERSION = "1.2.0";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -127,7 +127,7 @@ var init_api = __esm({
     init_version();
     API_KEY = process.env.CODEBYPLAN_API_KEY ?? "";
     BASE_URL = (process.env.CODEBYPLAN_API_URL ?? "https://codebyplan.com").replace(/\/$/, "");
-    REQUEST_TIMEOUT_MS = 3e4;
+    REQUEST_TIMEOUT_MS = 12e4;
     MAX_RETRIES = 3;
     BASE_DELAY_MS = 1e3;
     ApiError = class extends Error {
@@ -197,11 +197,7 @@ var TEMPLATE_MANAGED_KEYS, TEMPLATE_MANAGED_PERMISSION_KEYS, ARRAY_PERMISSION_KE
 var init_settings_merge = __esm({
   "src/lib/settings-merge.ts"() {
     "use strict";
-    TEMPLATE_MANAGED_KEYS = [
-      "attribution",
-      "hooks",
-      "statusLine"
-    ];
+    TEMPLATE_MANAGED_KEYS = ["attribution", "hooks", "statusLine"];
     TEMPLATE_MANAGED_PERMISSION_KEYS = [
       "deny",
       "ask",
@@ -255,12 +251,13 @@ function mergeDiscoveredHooks(existing, discovered, hooksRelPath = ".claude/hook
       merged[meta.event] = [];
     }
     const eventEntries = merged[meta.event];
+    const alreadyRegistered = eventEntries.some(
+      (m) => m.hooks.some((h) => h.command === command)
+    );
+    if (alreadyRegistered) continue;
     const matcherEntry = eventEntries.find((m) => m.matcher === meta.matcher);
     if (matcherEntry) {
-      const exists = matcherEntry.hooks.some((h) => h.command === command);
-      if (!exists) {
-        matcherEntry.hooks.push({ type: "command", command });
-      }
+      matcherEntry.hooks.push({ type: "command", command });
     } else {
       eventEntries.push({
         matcher: meta.matcher,
@@ -280,7 +277,10 @@ function stripDiscoveredHooks(config, hooksRelPath = ".claude/hooks") {
         (h) => !(h.command && h.command.startsWith(prefix) && h.command.endsWith(".sh"))
       );
       if (filteredHooks.length > 0) {
-        filteredMatchers.push({ matcher: matcher.matcher, hooks: filteredHooks });
+        filteredMatchers.push({
+          matcher: matcher.matcher,
+          hooks: filteredHooks
+        });
       }
     }
     if (filteredMatchers.length > 0) {
@@ -307,17 +307,25 @@ function substituteVariables(content, repoData) {
   }
   return result;
 }
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function reverseSubstituteVariables(content, repoData) {
   const entries = [];
   for (const [name, resolver] of Object.entries(TEMPLATE_VARIABLES)) {
     const value = resolver(repoData);
-    if (value.length < 3) continue;
+    if (value.length === 0) continue;
     entries.push([value, `{{${name}}}`]);
   }
   entries.sort((a, b) => b[0].length - a[0].length);
   let result = content;
   for (const [value, placeholder] of entries) {
-    result = result.replaceAll(value, placeholder);
+    if (value.length < 8) {
+      const pattern = new RegExp(`\\b${escapeRegex(value)}\\b`, "g");
+      result = result.replace(pattern, placeholder);
+    } else {
+      result = result.replaceAll(value, placeholder);
+    }
   }
   return result;
 }
@@ -341,7 +349,16 @@ var sync_engine_exports = {};
 __export(sync_engine_exports, {
   executeSyncToLocal: () => executeSyncToLocal
 });
-import { readdir as readdir2, readFile as readFile2, writeFile, unlink, mkdir, rmdir, chmod, stat } from "node:fs/promises";
+import {
+  readdir as readdir2,
+  readFile as readFile2,
+  writeFile,
+  unlink,
+  mkdir,
+  rmdir,
+  chmod,
+  stat
+} from "node:fs/promises";
 import { join as join2, dirname } from "node:path";
 function getTypeDir(claudeDir, dir) {
   if (dir === "commands") return join2(claudeDir, dir, "cbp");
@@ -416,13 +433,23 @@ async function executeSyncToLocal(options) {
   const dbOnlyFiles = [];
   for (const [syncKey, typeName] of Object.entries(syncKeyToType)) {
     if (worktree && typeName === "command") {
-      byType["commands"] = { created: [], updated: [], deleted: [], unchanged: [] };
+      byType["commands"] = {
+        created: [],
+        updated: [],
+        deleted: [],
+        unchanged: []
+      };
       continue;
     }
     const cfg = typeConfig[typeName];
     const targetDir = getTypeDir(claudeDir, cfg.dir);
     const remoteFiles = syncData[syncKey] ?? [];
-    const result = { created: [], updated: [], deleted: [], unchanged: [] };
+    const result = {
+      created: [],
+      updated: [],
+      deleted: [],
+      unchanged: []
+    };
     if (!dryRun) {
       await mkdir(targetDir, { recursive: true });
     }
@@ -483,7 +510,12 @@ async function executeSyncToLocal(options) {
     const syncKey = "docs_stack";
     const targetDir = join2(projectPath, "docs", "stack");
     const remoteFiles = syncData[syncKey] ?? [];
-    const result = { created: [], updated: [], deleted: [], unchanged: [] };
+    const result = {
+      created: [],
+      updated: [],
+      deleted: [],
+      unchanged: []
+    };
     if (remoteFiles.length > 0 && !dryRun) {
       await mkdir(targetDir, { recursive: true });
     }
@@ -492,7 +524,10 @@ async function executeSyncToLocal(options) {
     for (const remote of remoteFiles) {
       const relPath = remote.category ? join2(remote.category, remote.name) : remote.name;
       const substituted = substituteVariables(remote.content, repoData);
-      remotePathMap.set(relPath, { content: substituted, name: `${remote.category ?? ""}/${remote.name}` });
+      remotePathMap.set(relPath, {
+        content: substituted,
+        name: `${remote.category ?? ""}/${remote.name}`
+      });
     }
     for (const [relPath, { content, name }] of remotePathMap) {
       const fullPath = join2(targetDir, relPath);
@@ -531,7 +566,9 @@ async function executeSyncToLocal(options) {
   const globalSettingsFiles = syncData.global_settings ?? [];
   let globalSettings = {};
   for (const gf of globalSettingsFiles) {
-    const parsed = JSON.parse(substituteVariables(gf.content, repoData));
+    const parsed = JSON.parse(
+      substituteVariables(gf.content, repoData)
+    );
     globalSettings = { ...globalSettings, ...parsed };
   }
   const specialTypes = {
@@ -540,7 +577,12 @@ async function executeSyncToLocal(options) {
   };
   for (const [typeName, getPath] of Object.entries(specialTypes)) {
     const remoteFiles = syncData[typeName] ?? [];
-    const result = { created: [], updated: [], deleted: [], unchanged: [] };
+    const result = {
+      created: [],
+      updated: [],
+      deleted: [],
+      unchanged: []
+    };
     for (const remote of remoteFiles) {
       const targetPath = getPath(remote.name);
       const remoteContent = substituteVariables(remote.content, repoData);
@@ -551,11 +593,14 @@ async function executeSyncToLocal(options) {
       }
       if (typeName === "settings") {
         const repoSettings = JSON.parse(remoteContent);
-        const combinedTemplate = mergeGlobalAndRepoSettings(globalSettings, repoSettings);
+        const combinedTemplate = mergeGlobalAndRepoSettings(
+          globalSettings,
+          repoSettings
+        );
         const hooksDir = join2(projectPath, ".claude", "hooks");
         const discovered = await discoverHooks(hooksDir);
         if (localContent === void 0) {
-          let finalSettings = stripPermissionsAllow(combinedTemplate);
+          const finalSettings = stripPermissionsAllow(combinedTemplate);
           if (discovered.size > 0) {
             finalSettings.hooks = mergeDiscoveredHooks(
               finalSettings.hooks ?? {},
@@ -564,7 +609,11 @@ async function executeSyncToLocal(options) {
           }
           if (!dryRun) {
             await mkdir(dirname(targetPath), { recursive: true });
-            await writeFile(targetPath, JSON.stringify(finalSettings, null, 2) + "\n", "utf-8");
+            await writeFile(
+              targetPath,
+              JSON.stringify(finalSettings, null, 2) + "\n",
+              "utf-8"
+            );
           }
           result.created.push(remote.name);
           totals.created++;
@@ -625,28 +674,32 @@ async function executeSyncToLocal(options) {
     });
     const fileRepoUpdates = [];
     const syncTimestamp = (/* @__PURE__ */ new Date()).toISOString();
-    for (const [syncKey] of Object.entries(syncKeyToType)) {
+    for (const [syncKey, typeName] of Object.entries(syncKeyToType)) {
       const remoteFiles = syncData[syncKey] ?? [];
       for (const file of remoteFiles) {
-        if (file.id) {
-          fileRepoUpdates.push({
-            claude_file_id: file.id,
-            last_synced_at: syncTimestamp,
-            sync_status: "synced"
-          });
-        }
+        fileRepoUpdates.push({
+          claude_file_id: file.id ?? void 0,
+          file_type: typeName,
+          file_name: file.name,
+          file_category: file.category ?? null,
+          file_scope: file.scope ?? "shared",
+          last_synced_at: syncTimestamp,
+          sync_status: "synced"
+        });
       }
     }
     for (const typeName of ["claude_md", "settings"]) {
       const remoteFiles = syncData[typeName] ?? [];
       for (const file of remoteFiles) {
-        if (file.id) {
-          fileRepoUpdates.push({
-            claude_file_id: file.id,
-            last_synced_at: syncTimestamp,
-            sync_status: "synced"
-          });
-        }
+        fileRepoUpdates.push({
+          claude_file_id: file.id ?? void 0,
+          file_type: typeName,
+          file_name: file.name,
+          file_category: file.category ?? null,
+          file_scope: file.scope ?? `local:${repoId}`,
+          last_synced_at: syncTimestamp,
+          sync_status: "synced"
+        });
       }
     }
     if (fileRepoUpdates.length > 0) {
@@ -748,7 +801,9 @@ async function runSetup() {
   console.log("\n  CodeByPlan Setup\n");
   console.log("  This will configure Claude Code to use CodeByPlan.\n");
   console.log("  1. Sign up at https://codebyplan.com");
-  console.log("  2. Create an API key at https://codebyplan.com/settings/api-keys/\n");
+  console.log(
+    "  2. Create an API key at https://codebyplan.com/settings/api-keys/\n"
+  );
   try {
     const apiKey = (await rl.question("  Enter your API key: ")).trim();
     if (!apiKey) {
@@ -780,8 +835,10 @@ async function runSetup() {
         console.log("  API key is valid!\n");
       }
     } else {
-      console.log(`  Warning: API returned status ${res.status}, but continuing.
-`);
+      console.log(
+        `  Warning: API returned status ${res.status}, but continuing.
+`
+      );
     }
     console.log("  Where should the MCP server be configured?\n");
     console.log("    1. Global \u2014 available in all projects (~/.claude.json)");
@@ -795,14 +852,20 @@ async function runSetup() {
       console.log(`  Done! Config written to ${configPath}
 `);
       if (scope === "project") {
-        console.log("  Note: .mcp.json contains your API key \u2014 add it to .gitignore.\n");
+        console.log(
+          "  Note: .mcp.json contains your API key \u2014 add it to .gitignore.\n"
+        );
       }
     } else {
       console.log("  Warning: Could not verify the saved configuration.\n");
-      console.log(`  Manually add to ~/.claude.json under mcpServers.codebyplan:
-`);
-      console.log(`    { "url": "https://codebyplan.com/mcp", "headers": { "x-api-key": "${apiKey}" } }
-`);
+      console.log(
+        `  Manually add to ~/.claude.json under mcpServers.codebyplan:
+`
+      );
+      console.log(
+        `    { "url": "https://codebyplan.com/mcp", "headers": { "x-api-key": "${apiKey}" } }
+`
+      );
     }
     if (repos.length > 0) {
       console.log("  Initialize this project?\n");
@@ -827,14 +890,22 @@ async function runSetup() {
           const projectPath = process.cwd();
           try {
             const worktreesRes = await apiGet(`/worktrees?repo_id=${selectedRepo.id}`);
-            const match = worktreesRes.data.find((wt) => projectPath === wt.path || projectPath.startsWith(wt.path + "/"));
+            const match = worktreesRes.data.find(
+              (wt) => projectPath === wt.path || projectPath.startsWith(wt.path + "/")
+            );
             if (match) worktreeId = match.id;
           } catch {
           }
           const codebyplanPath = join3(projectPath, ".codebyplan.json");
-          const codebyplanConfig = { repo_id: selectedRepo.id };
+          const codebyplanConfig = {
+            repo_id: selectedRepo.id
+          };
           if (worktreeId) codebyplanConfig.worktree_id = worktreeId;
-          await writeFile2(codebyplanPath, JSON.stringify(codebyplanConfig, null, 2) + "\n", "utf-8");
+          await writeFile2(
+            codebyplanPath,
+            JSON.stringify(codebyplanConfig, null, 2) + "\n",
+            "utf-8"
+          );
           console.log(`  Created ${codebyplanPath}`);
           console.log("\n  Running initial sync...\n");
           try {
@@ -845,8 +916,10 @@ async function runSetup() {
             });
             const totalChanges = syncResult.totals.created + syncResult.totals.updated + syncResult.totals.deleted;
             if (totalChanges > 0) {
-              console.log(`  Synced: ${syncResult.totals.created} created, ${syncResult.totals.updated} updated, ${syncResult.totals.deleted} deleted
-`);
+              console.log(
+                `  Synced: ${syncResult.totals.created} created, ${syncResult.totals.updated} updated, ${syncResult.totals.deleted} deleted
+`
+              );
             } else {
               console.log("  All files already up to date.\n");
             }
@@ -858,7 +931,9 @@ async function runSetup() {
         }
       }
     }
-    console.log("  Setup complete! Start a new Claude Code session to begin.\n");
+    console.log(
+      "  Setup complete! Start a new Claude Code session to begin.\n"
+    );
   } finally {
     rl.close();
   }
@@ -918,17 +993,58 @@ var init_config = __esm({
 // src/cli/fileMapper.ts
 import { readdir as readdir3, readFile as readFile5 } from "node:fs/promises";
 import { join as join5, extname } from "node:path";
+function extractScope(content, type) {
+  if (type === "hook") {
+    const match = content.match(/^#\s*@scope:\s*(\S+)/m);
+    if (match) {
+      const raw = match[1];
+      return raw === "shared" ? "shared" : `local:${raw}`;
+    }
+    return "shared";
+  }
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const scopeLine = fmMatch[1].match(/^scope:\s*(\S+)/m);
+    if (scopeLine) {
+      const raw = scopeLine[1];
+      return raw === "shared" ? "shared" : `local:${raw}`;
+    }
+    if (/^scope\b/m.test(fmMatch[1])) {
+      console.error(
+        `  Warning: frontmatter contains "scope" but could not parse it. Expected format: "scope: shared" or "scope: <repo-name>". Defaulting to "shared".`
+      );
+    }
+  }
+  return "shared";
+}
 function compositeKey(type, name, category) {
   return category ? `${type}:${category}/${name}` : `${type}:${name}`;
 }
 async function scanLocalFiles(claudeDir, projectPath) {
   const result = /* @__PURE__ */ new Map();
   await scanCommands(join5(claudeDir, "commands", "cbp"), result);
-  await scanSubfolderType(join5(claudeDir, "agents"), "agent", "AGENT.md", result);
-  await scanSubfolderType(join5(claudeDir, "skills"), "skill", "SKILL.md", result);
+  await scanSubfolderType(
+    join5(claudeDir, "agents"),
+    "agent",
+    "AGENT.md",
+    result
+  );
+  await scanSubfolderType(
+    join5(claudeDir, "skills"),
+    "skill",
+    "SKILL.md",
+    result
+  );
   await scanFlatType(join5(claudeDir, "rules"), "rule", ".md", result);
   await scanFlatType(join5(claudeDir, "hooks"), "hook", ".sh", result);
   await scanTemplates(join5(claudeDir, "templates"), result);
+  await scanCategorizedType(
+    join5(claudeDir, "context"),
+    "context",
+    ".md",
+    result
+  );
+  await scanDocsRecursive(join5(claudeDir, "docs"), result);
   await scanSettings(claudeDir, projectPath, result);
   return result;
 }
@@ -944,14 +1060,19 @@ async function scanCommandsRecursive(baseDir, currentDir, result) {
   }
   for (const entry of entries) {
     if (entry.isDirectory()) {
-      await scanCommandsRecursive(baseDir, join5(currentDir, entry.name), result);
+      await scanCommandsRecursive(
+        baseDir,
+        join5(currentDir, entry.name),
+        result
+      );
     } else if (entry.isFile() && entry.name.endsWith(".md")) {
       const name = entry.name.slice(0, -3);
       const content = await readFile5(join5(currentDir, entry.name), "utf-8");
       const relDir = currentDir.slice(baseDir.length + 1);
       const category = relDir || null;
+      const scope = extractScope(content, "command");
       const key = compositeKey("command", name, category);
-      result.set(key, { type: "command", name, category, content });
+      result.set(key, { type: "command", name, category, content, scope });
     }
   }
 }
@@ -967,8 +1088,15 @@ async function scanSubfolderType(dir, type, fileName, result) {
       const filePath = join5(dir, entry.name, fileName);
       try {
         const content = await readFile5(filePath, "utf-8");
+        const scope = extractScope(content, type);
         const key = compositeKey(type, entry.name, null);
-        result.set(key, { type, name: entry.name, category: null, content });
+        result.set(key, {
+          type,
+          name: entry.name,
+          category: null,
+          content,
+          scope
+        });
       } catch {
       }
     }
@@ -985,8 +1113,72 @@ async function scanFlatType(dir, type, ext, result) {
     if (entry.isFile() && entry.name.endsWith(ext)) {
       const name = entry.name.slice(0, -ext.length);
       const content = await readFile5(join5(dir, entry.name), "utf-8");
+      const scope = extractScope(content, type);
       const key = compositeKey(type, name, null);
-      result.set(key, { type, name, category: null, content });
+      result.set(key, { type, name, category: null, content, scope });
+    }
+  }
+}
+async function scanCategorizedType(dir, type, ext, result) {
+  let entries;
+  try {
+    entries = await readdir3(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      const category = entry.name;
+      let subEntries;
+      try {
+        subEntries = await readdir3(join5(dir, category), {
+          withFileTypes: true
+        });
+      } catch {
+        continue;
+      }
+      for (const sub of subEntries) {
+        if (sub.isFile() && sub.name.endsWith(ext)) {
+          const name = sub.name.slice(0, -ext.length);
+          const content = await readFile5(
+            join5(dir, category, sub.name),
+            "utf-8"
+          );
+          const scope = extractScope(content, type);
+          const key = compositeKey(type, name, category);
+          result.set(key, { type, name, category, content, scope });
+        }
+      }
+    } else if (entry.isFile() && entry.name.endsWith(ext)) {
+      const name = entry.name.slice(0, -ext.length);
+      const content = await readFile5(join5(dir, entry.name), "utf-8");
+      const scope = extractScope(content, type);
+      const key = compositeKey(type, name, null);
+      result.set(key, { type, name, category: null, content, scope });
+    }
+  }
+}
+async function scanDocsRecursive(docsDir, result) {
+  await scanDocsDir(docsDir, docsDir, result);
+}
+async function scanDocsDir(baseDir, currentDir, result) {
+  let entries;
+  try {
+    entries = await readdir3(currentDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      await scanDocsDir(baseDir, join5(currentDir, entry.name), result);
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      const name = entry.name.slice(0, -3);
+      const content = await readFile5(join5(currentDir, entry.name), "utf-8");
+      const scope = extractScope(content, "docs");
+      const relDir = currentDir.slice(baseDir.length + 1);
+      const category = relDir || null;
+      const key = compositeKey("docs", name, category);
+      result.set(key, { type: "docs", name, category, content, scope });
     }
   }
 }
@@ -1000,8 +1192,15 @@ async function scanTemplates(dir, result) {
   for (const entry of entries) {
     if (entry.isFile() && extname(entry.name)) {
       const content = await readFile5(join5(dir, entry.name), "utf-8");
+      const scope = extractScope(content, "template");
       const key = compositeKey("template", entry.name, null);
-      result.set(key, { type: "template", name: entry.name, category: null, content });
+      result.set(key, {
+        type: "template",
+        name: entry.name,
+        category: null,
+        content,
+        scope
+      });
     }
   }
 }
@@ -1035,7 +1234,13 @@ async function scanSettings(claudeDir, projectPath, result) {
   }
   const content = JSON.stringify(parsed, null, 2) + "\n";
   const key = compositeKey("settings", "settings", null);
-  result.set(key, { type: "settings", name: "settings", category: null, content });
+  result.set(key, {
+    type: "settings",
+    name: "settings",
+    category: null,
+    content,
+    scope: "shared"
+  });
 }
 var init_fileMapper = __esm({
   "src/cli/fileMapper.ts"() {
@@ -1069,7 +1274,9 @@ async function confirmProceed(message) {
       const a = answer.trim().toLowerCase();
       if (a === "" || a === "y" || a === "yes") return true;
       if (a === "n" || a === "no") return false;
-      console.log(`    Unknown option "${answer.trim()}". Valid: y/yes, n/no, or Enter for yes.`);
+      console.log(
+        `    Unknown option "${answer.trim()}". Valid: y/yes, n/no, or Enter for yes.`
+      );
     }
   } catch (err) {
     if (isAbortError(err)) throw new SyncCancelledError();
@@ -1202,11 +1409,16 @@ async function promptReviewMode() {
   const rl = createInterface2({ input: stdin2, output: stdout2 });
   try {
     while (true) {
-      const answer = await rl.question("  Review [o]ne-by-one or [f]older-by-folder? ");
+      const answer = await rl.question(
+        "  Review [o]ne-by-one or [f]older-by-folder? "
+      );
       const a = answer.trim().toLowerCase();
-      if (a === "o" || a === "one-by-one" || a === "one" || a === "file") return "file";
+      if (a === "o" || a === "one-by-one" || a === "one" || a === "file")
+        return "file";
       if (a === "f" || a === "folder") return "folder";
-      console.log(`    Unknown option "${answer.trim()}". Valid: o/one-by-one, f/folder`);
+      console.log(
+        `    Unknown option "${answer.trim()}". Valid: o/one-by-one, f/folder`
+      );
     }
   } catch (err) {
     if (isAbortError(err)) throw new SyncCancelledError();
@@ -1245,7 +1457,9 @@ async function reviewFilesOneByOne(items, label, plannedAction, recommendedActio
           break;
         }
         if (result.action === null) {
-          console.log(`    Unknown option "${answer.trim()}". Valid: ${formatActionPrompt(rec, hasContent, false)}`);
+          console.log(
+            `    Unknown option "${answer.trim()}". Valid: ${formatActionPrompt(rec, hasContent, false)}`
+          );
           continue;
         }
         results.push(result.action);
@@ -1282,7 +1496,13 @@ async function reviewFolder(folderName, items, label, plannedAction, recommended
       const a = answer.trim().toLowerCase();
       if (a === "o" || a === "one-by-one") {
         rl.close();
-        return reviewFilesOneByOne(items, label, plannedAction, recommendedAction, content);
+        return reviewFilesOneByOne(
+          items,
+          label,
+          plannedAction,
+          recommendedAction,
+          content
+        );
       }
       if (a === "r" || a === "recommended") {
         return items.map(
@@ -1303,11 +1523,13 @@ async function reviewFolder(folderName, items, label, plannedAction, recommended
       if (result.action !== null) {
         return items.map(() => result.action);
       }
-      console.log(`    Unknown option "${answer.trim()}". Valid: ${formatActionPrompt(
-        recommendedAction ? recommendedAction(items[0]) : plannedAction(items[0]),
-        false,
-        true
-      )} [o]ne-by-one`);
+      console.log(
+        `    Unknown option "${answer.trim()}". Valid: ${formatActionPrompt(
+          recommendedAction ? recommendedAction(items[0]) : plannedAction(items[0]),
+          false,
+          true
+        )} [o]ne-by-one`
+      );
     }
   } catch (err) {
     if (isAbortError(err)) throw new SyncCancelledError();
@@ -1893,7 +2115,10 @@ async function runSync() {
     if (!dryRun) {
       try {
         await apiDelete("/sync/lock", { repo_id: repoId });
-      } catch {
+      } catch (err) {
+        console.error(
+          `  Warning: failed to release sync lock: ${err instanceof Error ? err.message : String(err)}`
+        );
       }
     }
   }
@@ -1906,37 +2131,42 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
     localFiles = await scanLocalFiles(claudeDir, projectPath);
   } catch {
   }
-  const [defaultsRes, repoSyncRes, repoRes, syncStateRes, fileReposRes] = await Promise.all([
-    apiGet("/sync/defaults"),
-    apiGet("/sync/files", { repo_id: repoId }),
-    apiGet(`/repos/${repoId}`),
-    apiGet("/sync/state", {
-      repo_id: repoId
-    }),
-    apiGet("/sync/file-repos", {
-      repo_id: repoId
-    })
-  ]);
+  const [defaultsRes, repoSyncRes, repoRes, , fileReposRes] = await Promise.all(
+    [
+      apiGet("/sync/defaults"),
+      apiGet("/sync/files", { repo_id: repoId }),
+      apiGet(`/repos/${repoId}`),
+      apiGet("/sync/state", {
+        repo_id: repoId
+      }),
+      apiGet("/sync/file-repos", {
+        repo_id: repoId
+      })
+    ]
+  );
   const syncStartTime = Date.now();
   const repoData = repoRes.data;
   const remoteDefaults = flattenSyncData(defaultsRes.data);
   const remoteRepoFiles = flattenSyncData(repoSyncRes.data);
-  const syncState = syncStateRes.data;
   const fileRepoHashes = /* @__PURE__ */ new Map();
   const fileRepoByClaudeFileId = /* @__PURE__ */ new Map();
   for (const entry of fileReposRes.data ?? []) {
-    if (entry.claude_files) {
-      const key = compositeKey(
-        entry.claude_files.type,
-        entry.claude_files.name,
-        entry.claude_files.category
+    const baseKey = compositeKey(
+      entry.file_type,
+      entry.file_name,
+      entry.file_category
+    );
+    const scopedKey = `${baseKey}:${entry.file_scope}`;
+    fileRepoHashes.set(scopedKey, entry.last_synced_content_hash);
+    if (!fileRepoHashes.has(baseKey)) {
+      fileRepoHashes.set(baseKey, entry.last_synced_content_hash);
+    }
+    if (entry.claude_file_id) {
+      fileRepoByClaudeFileId.set(
+        entry.claude_file_id,
+        entry.last_synced_content_hash
       );
-      fileRepoHashes.set(key, entry.last_synced_content_hash);
     }
-    fileRepoByClaudeFileId.set(
-      entry.claude_file_id,
-      entry.last_synced_content_hash
-    );
   }
   const remoteFiles = new Map([...remoteDefaults, ...remoteRepoFiles]);
   console.log(
@@ -1965,6 +2195,7 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         type: local.type,
         name: local.name,
         category: local.category,
+        scope: local.scope,
         isHook: local.type === "hook",
         claudeFileId: null
       });
@@ -1984,6 +2215,7 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         type: remote.type,
         name: remote.name,
         category: remote.category ?? null,
+        scope: remote.scope ?? "shared",
         isHook: remote.type === "hook",
         claudeFileId: remote.id ?? null
       });
@@ -1993,7 +2225,8 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         continue;
       }
       const localHash = contentHash(local.content);
-      const lastSyncedHash = fileRepoHashes.get(key) ?? null;
+      const scopedKey = `${key}:${local.scope}`;
+      const lastSyncedHash = fileRepoHashes.get(scopedKey) ?? fileRepoHashes.get(key) ?? null;
       const localChanged = lastSyncedHash ? localHash !== lastSyncedHash : true;
       let action;
       if (force) {
@@ -2003,8 +2236,8 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
       } else if (lastSyncedHash === null) {
         action = "conflict";
       } else {
-        const remoteDbHash = remote.content_hash ?? null;
-        const remoteChanged = remoteDbHash ? remoteDbHash !== lastSyncedHash : true;
+        const remoteResolvedHash = contentHash(resolvedRemote);
+        const remoteChanged = remoteResolvedHash !== lastSyncedHash;
         if (remoteChanged) {
           action = "conflict";
         } else {
@@ -2023,6 +2256,7 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         type: local.type,
         name: local.name,
         category: local.category,
+        scope: local.scope,
         isHook: local.type === "hook",
         claudeFileId: remote.id ?? null
       });
@@ -2123,7 +2357,8 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         type: p.type,
         name: p.name,
         category: p.category,
-        content: p.pushContent
+        content: p.pushContent,
+        scope: p.scope
       }));
       if (toUpsert.length > 0) {
         await apiPost("/sync/files", {
@@ -2146,38 +2381,16 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
           if (p.filePath) {
             try {
               await unlink2(p.filePath);
-            } catch {
+            } catch (err) {
+              if (err instanceof Error && "code" in err && err.code !== "ENOENT") {
+                console.error(
+                  `  Warning: failed to delete ${p.filePath}: ${err.message}`
+                );
+              }
             }
           }
         }
       }
-      const unresolvedConflicts = plan.filter(
-        (p) => p.action === "conflict" || p.action === "skip" && p.localContent !== null && p.remoteContent !== null
-      );
-      if (unresolvedConflicts.length > 0) {
-        let stored = 0;
-        for (const p of unresolvedConflicts) {
-          if (p.claudeFileId) {
-            try {
-              await apiPost("/sync/conflicts", {
-                repo_id: repoId,
-                claude_file_id: p.claudeFileId,
-                conflict_type: "both_modified",
-                local_content: p.localContent,
-                remote_content: p.remoteContent
-              });
-              stored++;
-            } catch {
-            }
-          }
-        }
-        if (stored > 0) {
-          console.log(
-            `
-  ${stored} conflict(s) stored in DB for later resolution.`
-          );
-        }
-      }
       const syncDurationMs = Date.now() - syncStartTime;
       await apiPost("/sync/state", {
         repo_id: repoId,
@@ -2194,9 +2407,13 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
       const syncTimestamp = (/* @__PURE__ */ new Date()).toISOString();
       const fileRepoUpdates = [];
       for (const p of toPull) {
-        if (p.claudeFileId && p.remoteContent !== null) {
+        if (p.remoteContent !== null) {
           fileRepoUpdates.push({
-            claude_file_id: p.claudeFileId,
+            claude_file_id: p.claudeFileId ?? void 0,
+            file_type: p.type,
+            file_name: p.name,
+            file_category: p.category,
+            file_scope: p.scope,
             last_synced_at: syncTimestamp,
             last_synced_content_hash: contentHash(p.remoteContent),
             sync_status: "synced"
@@ -2204,9 +2421,13 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
         }
       }
       for (const p of toPush) {
-        if (p.claudeFileId && p.localContent !== null) {
+        if (p.localContent !== null) {
           fileRepoUpdates.push({
-            claude_file_id: p.claudeFileId,
+            claude_file_id: p.claudeFileId ?? void 0,
+            file_type: p.type,
+            file_name: p.name,
+            file_category: p.category,
+            file_scope: p.scope,
             last_synced_at: syncTimestamp,
             last_synced_content_hash: contentHash(p.localContent),
             sync_status: "synced"
@@ -2227,6 +2448,36 @@ async function runSyncInner(repoId, projectPath, dryRun, force, fix = false) {
   Applied: ${toPull.length} pulled, ${toPush.length} pushed, ${toDelete.length} deleted` + (skipped.length > 0 ? `, ${skipped.length} skipped` : "")
       );
     }
+    const unresolvedConflicts = plan.filter(
+      (p) => p.action === "conflict" || p.action === "skip" && p.localContent !== null && p.remoteContent !== null
+    );
+    if (unresolvedConflicts.length > 0) {
+      let stored = 0;
+      for (const p of unresolvedConflicts) {
+        try {
+          await apiPost("/sync/conflicts", {
+            repo_id: repoId,
+            claude_file_id: p.claudeFileId ?? void 0,
+            file_type: p.type,
+            file_name: p.name,
+            file_category: p.category,
+            file_scope: p.scope,
+            conflict_type: "both_modified",
+            local_content: p.localContent,
+            remote_content: p.remoteContent
+          });
+          stored++;
+        } catch (err) {
+          console.error(`Failed to store conflict for ${p.displayPath}:`, err);
+        }
+      }
+      if (stored > 0) {
+        console.log(
+          `
+  ${stored} conflict(s) stored in DB for later resolution.`
+        );
+      }
+    }
   } else if (dryRun) {
     console.log("\n  (dry-run \u2014 no changes)");
   }
@@ -2486,7 +2737,10 @@ function groupByType(items) {
     rule: "Rules",
     hook: "Hooks",
     template: "Templates",
-    settings: "Settings"
+    settings: "Settings",
+    context: "Context",
+    docs_stack: "Stack Docs",
+    docs: "Docs"
   };
   for (const item of items) {
     const label = typeLabels[item.type] ?? item.type;
@@ -2504,6 +2758,9 @@ function getLocalFilePath(claudeDir, projectPath, remote) {
     rule: { dir: "rules", ext: ".md" },
     hook: { dir: "hooks", ext: ".sh" },
     template: { dir: "templates", ext: "" },
+    context: { dir: "context", ext: ".md" },
+    docs_stack: { dir: join7("docs", "stack"), ext: ".md" },
+    docs: { dir: "docs", ext: ".md" },
     claude_md: { dir: "", ext: "" },
     settings: { dir: "", ext: "" }
   };
@@ -2517,11 +2774,13 @@ function getLocalFilePath(claudeDir, projectPath, remote) {
   if (remote.type === "command" && remote.category)
     return join7(typeDir, remote.category, `${remote.name}${cfg.ext}`);
   if (remote.type === "template") return join7(typeDir, remote.name);
+  if (remote.category && (remote.type === "context" || remote.type === "docs_stack" || remote.type === "docs"))
+    return join7(typeDir, remote.category, `${remote.name}${cfg.ext}`);
   return join7(typeDir, `${remote.name}${cfg.ext}`);
 }
 function getSyncVersion() {
   try {
-    return "1.0.0";
+    return "1.2.0";
   } catch {
     return "unknown";
   }
@@ -2535,7 +2794,10 @@ function flattenSyncData(data) {
     rules: "rule",
     hooks: "hook",
     templates: "template",
-    settings: "settings"
+    settings: "settings",
+    contexts: "context",
+    docs_stack: "docs_stack",
+    docs: "docs"
   };
   for (const [syncKey, typeName] of Object.entries(typeMap)) {
     const files = data[syncKey] ?? [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {
@@ -14,6 +14,10 @@
     "build": "tsc",
     "build:npm": "node esbuild.npm.mjs",
     "prepublishOnly": "npm run build:npm",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
@@ -40,9 +44,18 @@
     "node": ">=18"
   },
   "devDependencies": {
+    "@eslint/js": "^9.18.0",
     "@types/node": "^20",
+    "@vitest/eslint-plugin": "^1.1.44",
     "esbuild": "^0.25",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-no-secrets": "^2.2.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "eslint-plugin-security": "^3.0.1",
+    "globals": "^17.0.0",
     "typescript": "^5",
+    "typescript-eslint": "^8.20.0",
     "vitest": "^4.0.18"
   }
 }