@codebyplan/cli 2.0.2 → 2.1.0

package/README.md

@@ -71,6 +71,17 @@ claude mcp add codebyplan -e CODEBYPLAN_API_KEY=your_key_here -- npx -y @codebyp
 |------|-------------|
 | `health_check` | Check server version, API connectivity, and latency |
 
+### Settings File Model
+
+The `sync_claude_files` tool writes a `settings.json` file to the project's `.claude/` directory. This file contains shared settings (hooks, statusLine, attribution, permissions.deny/ask/additionalDirectories) merged from global and repo-specific scopes in the database.
+
+A separate `settings.local.json` file (not managed by sync) holds local-only configuration: `permissions.allow` and MCP server definitions. Claude Code merges both files at runtime, with `settings.local.json` taking precedence.
+
+| File | Managed By | Contains |
+|------|------------|----------|
+| `settings.json` | `sync_claude_files` (synced from DB) | Shared settings: hooks, statusLine, attribution, permissions.deny/ask/additionalDirectories |
+| `settings.local.json` | User (local-only) | Machine-specific: permissions.allow, MCP server config |
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/cli.js

@@ -37,7 +37,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "2.0.2";
+    VERSION = "2.1.0";
     PACKAGE_NAME = "@codebyplan/cli";
   }
 });
@@ -384,7 +384,36 @@ function mergeSettings(template, local) {
   }
   return merged;
 }
-var TEMPLATE_MANAGED_KEYS, TEMPLATE_MANAGED_PERMISSION_KEYS;
+function mergeGlobalAndRepoSettings(global, repo) {
+  const merged = { ...global, ...repo };
+  const globalPerms = global.permissions && typeof global.permissions === "object" ? global.permissions : {};
+  const repoPerms = repo.permissions && typeof repo.permissions === "object" ? repo.permissions : {};
+  if (Object.keys(globalPerms).length > 0 || Object.keys(repoPerms).length > 0) {
+    const mergedPerms = { ...globalPerms, ...repoPerms };
+    for (const key of ARRAY_PERMISSION_KEYS) {
+      const globalArr = Array.isArray(globalPerms[key]) ? globalPerms[key] : [];
+      const repoArr = Array.isArray(repoPerms[key]) ? repoPerms[key] : [];
+      if (globalArr.length > 0 || repoArr.length > 0) {
+        mergedPerms[key] = [.../* @__PURE__ */ new Set([...globalArr, ...repoArr])];
+      }
+    }
+    merged.permissions = mergedPerms;
+  }
+  return merged;
+}
+function stripPermissionsAllow(settings) {
+  if (!settings.permissions || typeof settings.permissions !== "object") {
+    return settings;
+  }
+  const perms = { ...settings.permissions };
+  delete perms.allow;
+  if (Object.keys(perms).length === 0) {
+    const { permissions: _, ...rest } = settings;
+    return rest;
+  }
+  return { ...settings, permissions: perms };
+}
+var TEMPLATE_MANAGED_KEYS, TEMPLATE_MANAGED_PERMISSION_KEYS, ARRAY_PERMISSION_KEYS;
 var init_settings_merge = __esm({
   "src/lib/settings-merge.ts"() {
     "use strict";
@@ -398,6 +427,7 @@ var init_settings_merge = __esm({
       "ask",
       "additionalDirectories"
     ];
+    ARRAY_PERMISSION_KEYS = ["deny", "ask"];
   }
 });
 
@@ -460,6 +490,25 @@ function mergeDiscoveredHooks(existing, discovered, hooksRelPath = ".claude/hook
   }
   return merged;
 }
+function stripDiscoveredHooks(config2, hooksRelPath = ".claude/hooks") {
+  const prefix = `bash ${hooksRelPath}/`;
+  const stripped = {};
+  for (const [event, matchers] of Object.entries(config2)) {
+    const filteredMatchers = [];
+    for (const matcher of matchers) {
+      const filteredHooks = matcher.hooks.filter(
+        (h) => !(h.command && h.command.startsWith(prefix) && h.command.endsWith(".sh"))
+      );
+      if (filteredHooks.length > 0) {
+        filteredMatchers.push({ matcher: matcher.matcher, hooks: filteredHooks });
+      }
+    }
+    if (filteredMatchers.length > 0) {
+      stripped[event] = filteredMatchers;
+    }
+  }
+  return stripped;
+}
 var init_hook_registry = __esm({
   "src/lib/hook-registry.ts"() {
     "use strict";
@@ -687,9 +736,15 @@ async function executeSyncToLocal(options) {
     }
     byType[typeName] = result;
   }
+  const globalSettingsFiles = syncData.global_settings ?? [];
+  let globalSettings = {};
+  for (const gf of globalSettingsFiles) {
+    const parsed = JSON.parse(substituteVariables(gf.content, repoData));
+    globalSettings = { ...globalSettings, ...parsed };
+  }
   const specialTypes = {
     claude_md: () => join4(projectPath, "CLAUDE.md"),
-    settings: () => join4(projectPath, ".claude", "settings.local.json")
+    settings: () => join4(projectPath, ".claude", "settings.json")
   };
   for (const [typeName, getPath] of Object.entries(specialTypes)) {
     const remoteFiles = syncData[typeName] ?? [];
@@ -703,25 +758,28 @@ async function executeSyncToLocal(options) {
       } catch {
       }
       if (typeName === "settings") {
-        const templateSettings = JSON.parse(remoteContent);
+        const repoSettings = JSON.parse(remoteContent);
+        const combinedTemplate = mergeGlobalAndRepoSettings(globalSettings, repoSettings);
         const hooksDir = join4(projectPath, ".claude", "hooks");
         const discovered = await discoverHooks(hooksDir);
         if (localContent === void 0) {
+          let finalSettings = stripPermissionsAllow(combinedTemplate);
           if (discovered.size > 0) {
-            templateSettings.hooks = mergeDiscoveredHooks(
-              templateSettings.hooks ?? {},
+            finalSettings.hooks = mergeDiscoveredHooks(
+              finalSettings.hooks ?? {},
               discovered
             );
           }
           if (!dryRun) {
             await mkdir(dirname(targetPath), { recursive: true });
-            await writeFile2(targetPath, JSON.stringify(templateSettings, null, 2) + "\n", "utf-8");
+            await writeFile2(targetPath, JSON.stringify(finalSettings, null, 2) + "\n", "utf-8");
           }
           result.created.push(remote.name);
           totals.created++;
         } else {
           const localSettings = JSON.parse(localContent);
-          const merged = mergeSettings(templateSettings, localSettings);
+          let merged = mergeSettings(combinedTemplate, localSettings);
+          merged = stripPermissionsAllow(merged);
           if (discovered.size > 0) {
             merged.hooks = mergeDiscoveredHooks(
               merged.hooks ?? {},
@@ -1107,7 +1165,7 @@ import { join as join6, extname } from "node:path";
 function compositeKey(type, name, category) {
   return category ? `${type}:${category}/${name}` : `${type}:${name}`;
 }
-async function scanLocalFiles(claudeDir) {
+async function scanLocalFiles(claudeDir, projectPath) {
   const result = /* @__PURE__ */ new Map();
   await scanCommands(join6(claudeDir, "commands", "cbp"), result);
   await scanSubfolderType(join6(claudeDir, "agents"), "agent", "AGENT.md", result);
@@ -1115,6 +1173,7 @@ async function scanLocalFiles(claudeDir) {
   await scanFlatType(join6(claudeDir, "rules"), "rule", ".md", result);
   await scanFlatType(join6(claudeDir, "hooks"), "hook", ".sh", result);
   await scanTemplates(join6(claudeDir, "templates"), result);
+  await scanSettings(claudeDir, projectPath, result);
   return result;
 }
 async function scanCommands(dir, result) {
@@ -1190,9 +1249,43 @@ async function scanTemplates(dir, result) {
     }
   }
 }
+async function scanSettings(claudeDir, projectPath, result) {
+  const settingsPath = join6(claudeDir, "settings.json");
+  let raw;
+  try {
+    raw = await readFile6(settingsPath, "utf-8");
+  } catch {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  parsed = stripPermissionsAllow(parsed);
+  if (parsed.hooks && typeof parsed.hooks === "object") {
+    const hooksDir = projectPath ? join6(projectPath, ".claude", "hooks") : join6(claudeDir, "hooks");
+    const discovered = await discoverHooks(hooksDir);
+    if (discovered.size > 0) {
+      parsed.hooks = stripDiscoveredHooks(
+        parsed.hooks,
+        ".claude/hooks"
+      );
+      if (Object.keys(parsed.hooks).length === 0) {
+        delete parsed.hooks;
+      }
+    }
+  }
+  const content = JSON.stringify(parsed, null, 2) + "\n";
+  const key = compositeKey("settings", "settings", null);
+  result.set(key, { type: "settings", name: "settings", category: null, content });
+}
 var init_fileMapper = __esm({
   "src/cli/fileMapper.ts"() {
     "use strict";
+    init_settings_merge();
+    init_hook_registry();
   }
 });
 
@@ -1275,6 +1368,7 @@ async function runPush() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
   const force = hasFlag("force", 3);
+  const isGlobal = hasFlag("global", 3);
   validateApiKey();
   const config2 = await resolveConfig(flags);
   const { repoId, projectPath } = config2;
@@ -1293,7 +1387,7 @@ async function runPush() {
     return;
   }
   console.log("  Scanning local files...");
-  const localFiles = await scanLocalFiles(claudeDir);
+  const localFiles = await scanLocalFiles(claudeDir, projectPath);
   console.log(`  Found ${localFiles.size} local files.`);
   console.log("  Fetching remote state...");
   const [syncRes, repoRes] = await Promise.all([
@@ -1382,7 +1476,8 @@ async function runPush() {
       type: f.type,
       name: f.name,
       category: f.category,
-      content: f.content
+      content: f.content,
+      ...f.type === "settings" ? { scope: isGlobal ? "global" : "repo" } : {}
     })),
     delete_keys: toDelete
   });
@@ -1416,7 +1511,8 @@ function flattenSyncData(data) {
     skills: "skill",
     rules: "rule",
     hooks: "hook",
-    templates: "template"
+    templates: "template",
+    settings: "settings"
   };
   for (const [syncKey, typeName] of Object.entries(typeMap)) {
     const files = data[syncKey] ?? [];
@@ -1596,7 +1692,7 @@ async function runInit() {
           allFiles.push({ type: "claude_md", name: file.name, content: file.content });
         }
         for (const file of settingsFiles) {
-          allFiles.push({ type: "settings", name: file.name, content: file.content });
+          allFiles.push({ type: "settings", name: file.name, content: file.content, scope: file.scope ?? "repo" });
         }
         if (allFiles.length > 0) {
           await apiPost("/sync/files", {
@@ -23380,21 +23476,6 @@ function registerReadTools(server) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
   });
-  server.registerTool("get_handoff", {
-    description: "Get handoff state for a repo (status, summary, resume command/context).",
-    inputSchema: {
-      repo_id: external_exports.string().uuid().describe("The repo UUID")
-    }
-  }, async ({ repo_id }) => {
-    try {
-      const res = await apiGet(`/repos/${repo_id}`);
-      const { id, name, handoff_status, handoff_summary, handoff_resume_command, handoff_resume_context, handoff_updated_at } = res.data;
-      const data = { id, name, handoff_status, handoff_summary, handoff_resume_command, handoff_resume_context, handoff_updated_at };
-      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-    } catch (err) {
-      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-    }
-  });
   server.registerTool("get_sync_status", {
     description: "Get cross-repo sync status. Shows which repos need a claude files sync based on latest updates.",
     inputSchema: {}
@@ -23406,6 +23487,22 @@ function registerReadTools(server) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
   });
+  server.registerTool("get_next_action", {
+    description: "Compute the next action for a repo based on current workflow state. Returns command, instructions, state, and context.",
+    inputSchema: {
+      repo_id: external_exports.string().uuid().describe("The repo UUID"),
+      worktree_id: external_exports.string().uuid().optional().describe("Optional worktree UUID to filter by assignment")
+    }
+  }, async ({ repo_id, worktree_id }) => {
+    try {
+      const params = {};
+      if (worktree_id) params.worktree_id = worktree_id;
+      const res = await apiGet(`/repos/${repo_id}/next-action`, params);
+      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
   server.registerTool("get_worktrees", {
     description: "List worktrees for a repo. Optionally filter by status.",
     inputSchema: {
@@ -23514,27 +23611,33 @@ function registerWriteTools(server) {
     description: "Create a new checkpoint for a repo. Optionally connect it to a launch via launch_id.",
     inputSchema: {
       repo_id: external_exports.string().uuid().describe("The repo UUID"),
-      title: external_exports.string().describe("Checkpoint title"),
+      title: external_exports.string().optional().describe("Checkpoint title (optional \u2014 Claude can generate if missing)"),
       number: external_exports.number().int().describe("Checkpoint number (e.g. 1 for CHK-001)"),
-      goal: external_exports.string().optional().describe("Checkpoint goal description"),
+      goal: external_exports.string().optional().describe("Checkpoint goal description (max 300 chars, brief overview)"),
       deadline: external_exports.string().optional().describe("Deadline date (ISO format)"),
       status: external_exports.string().optional().describe("Initial status (default: pending). Use 'draft' for checkpoints not ready for development."),
       launch_id: external_exports.string().uuid().optional().describe("Optional launch UUID to connect this checkpoint to"),
+      ideas: external_exports.array(external_exports.object({
+        description: external_exports.string().describe("Idea description"),
+        requirements: external_exports.array(external_exports.string()).optional().describe("List of requirements for this idea"),
+        images: external_exports.array(external_exports.string()).optional().describe("Image URLs for this idea")
+      })).optional().describe("Ideas array \u2014 each idea has description, requirements[], images[]"),
       context: external_exports.any().optional().describe("Context JSONB (decisions, discoveries, dependencies, constraints, qa_answers)"),
       research: external_exports.any().optional().describe("Research JSONB (topics with findings and sources)"),
       qa: external_exports.any().optional().describe("QA JSONB (checklist items with type, check, status)")
     }
-  }, async ({ repo_id, title, number: number3, goal, deadline, status, launch_id, context, research, qa }) => {
+  }, async ({ repo_id, title, number: number3, goal, deadline, status, launch_id, ideas, context, research, qa }) => {
     try {
       const body = {
         repo_id,
-        title,
+        title: title ?? null,
         number: number3,
         goal: goal ?? null,
         deadline: deadline ?? null,
         status: status ?? "pending",
         launch_id: launch_id ?? null
       };
+      if (ideas !== void 0) body.ideas = ideas;
       if (context !== void 0) body.context = context;
       if (research !== void 0) body.research = research;
       if (qa !== void 0) body.qa = qa;
@@ -23548,19 +23651,24 @@ function registerWriteTools(server) {
     description: "Update an existing checkpoint. Can connect or disconnect a launch via launch_id.",
     inputSchema: {
       checkpoint_id: external_exports.string().uuid().describe("The checkpoint UUID"),
-      title: external_exports.string().optional().describe("New title"),
-      goal: external_exports.string().optional().describe("New goal"),
+      title: external_exports.string().nullable().optional().describe("New title (or null to clear)"),
+      goal: external_exports.string().optional().describe("New goal (max 300 chars, brief overview)"),
       status: external_exports.string().optional().describe("New status (draft, pending, active, completed)"),
       deadline: external_exports.string().optional().describe("New deadline (ISO format)"),
       completed_at: external_exports.string().optional().describe("Completion timestamp (ISO format)"),
       launch_id: external_exports.string().uuid().nullable().optional().describe("Launch UUID to connect (or null to disconnect)"),
       worktree_id: external_exports.string().uuid().nullable().optional().describe("Worktree UUID to assign (or null to unassign)"),
       assigned_to: external_exports.string().nullable().optional().describe("Who/what claimed this checkpoint"),
+      ideas: external_exports.array(external_exports.object({
+        description: external_exports.string().describe("Idea description"),
+        requirements: external_exports.array(external_exports.string()).optional().describe("List of requirements for this idea"),
+        images: external_exports.array(external_exports.string()).optional().describe("Image URLs for this idea")
+      })).optional().describe("Ideas array \u2014 each idea has description, requirements[], images[]"),
       context: external_exports.any().optional().describe("Context JSONB (decisions, discoveries, dependencies, constraints, qa_answers)"),
       research: external_exports.any().optional().describe("Research JSONB (topics with findings and sources)"),
       qa: external_exports.any().optional().describe("QA JSONB (checklist items with type, check, status)")
     }
-  }, async ({ checkpoint_id, title, goal, status, deadline, completed_at, launch_id, worktree_id, assigned_to, context, research, qa }) => {
+  }, async ({ checkpoint_id, title, goal, status, deadline, completed_at, launch_id, worktree_id, assigned_to, ideas, context, research, qa }) => {
     const update = {};
     if (title !== void 0) update.title = title;
     if (goal !== void 0) update.goal = goal;
@@ -23570,6 +23678,7 @@ function registerWriteTools(server) {
     if (launch_id !== void 0) update.launch_id = launch_id;
     if (worktree_id !== void 0) update.worktree_id = worktree_id;
     if (assigned_to !== void 0) update.assigned_to = assigned_to;
+    if (ideas !== void 0) update.ideas = ideas;
     if (context !== void 0) update.context = context;
     if (research !== void 0) update.research = research;
     if (qa !== void 0) update.qa = qa;
@@ -23958,31 +24067,6 @@ function registerWriteTools(server) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
   });
-  server.registerTool("update_handoff", {
-    description: "Update handoff state for a repo (status, summary, resume command/context). Automatically sets handoff_updated_at.",
-    inputSchema: {
-      repo_id: external_exports.string().uuid().describe("The repo UUID"),
-      status: external_exports.string().optional().describe("Handoff status"),
-      summary: external_exports.string().optional().describe("Handoff summary"),
-      resume_command: external_exports.string().optional().describe("Resume command"),
-      resume_context: external_exports.string().optional().describe("Resume context")
-    }
-  }, async ({ repo_id, status, summary, resume_command, resume_context }) => {
-    const body = {};
-    if (status !== void 0) body.status = status;
-    if (summary !== void 0) body.summary = summary;
-    if (resume_command !== void 0) body.resume_command = resume_command;
-    if (resume_context !== void 0) body.resume_context = resume_context;
-    if (Object.keys(body).length === 0) {
-      return { content: [{ type: "text", text: "Error: No fields to update" }], isError: true };
-    }
-    try {
-      const res = await apiPatch(`/repos/${repo_id}/handoff`, body);
-      return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
-    } catch (err) {
-      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
-    }
-  });
   server.registerTool("create_worktree", {
     description: "Create a new worktree for a repo.",
     inputSchema: {

package/package.json

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