@codebyplan/cli 2.0.2 → 2.2.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.2.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: {
@@ -23429,63 +23526,232 @@ var init_read = __esm({
   }
 });
 
-// src/lib/auto-push.ts
+// src/lib/git-pr.ts
 import { exec as execCb } from "node:child_process";
 import { promisify } from "node:util";
-async function autoPushToMain(repoId) {
-  let repo;
+async function createPR(options) {
+  const { repoPath, head, base, title, body } = options;
   try {
-    const res = await apiGet(`/repos/${repoId}`);
-    repo = res.data;
-  } catch {
+    try {
+      const { stdout: existing } = await exec(
+        `gh pr list --head "${head}" --base "${base}" --json number,url --jq '.[0]'`,
+        { cwd: repoPath }
+      );
+      if (existing.trim()) {
+        const pr = JSON.parse(existing.trim());
+        return { pr_url: pr.url, pr_number: pr.number };
+      }
+    } catch {
+    }
+    const { stdout: stdout5 } = await exec(
+      `gh pr create --head "${head}" --base "${base}" --title "${title.replace(/"/g, '\\"')}" --body "${body.replace(/"/g, '\\"')}"`,
+      { cwd: repoPath }
+    );
+    const prUrl = stdout5.trim();
+    const prNumber = parseInt(prUrl.split("/").pop() ?? "0", 10);
+    return { pr_url: prUrl, pr_number: prNumber || null };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
+    return { pr_url: null, pr_number: null, error: errorMessage };
+  }
+}
+async function getPRStatus(repoPath, prNumber) {
+  try {
+    const { stdout: stdout5 } = await exec(
+      `gh pr view ${prNumber} --json state,mergeable,title,url,number`,
+      { cwd: repoPath }
+    );
+    const pr = JSON.parse(stdout5.trim());
     return {
-      pushed: false,
-      message: "Repo not found",
-      error: "Repo not found"
+      state: pr.state,
+      mergeable: pr.mergeable,
+      title: pr.title,
+      url: pr.url,
+      number: pr.number
     };
-  }
-  if (!repo.auto_push_enabled) {
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
     return {
-      pushed: false,
-      message: "Auto-push is not enabled for this repo"
+      state: "UNKNOWN",
+      mergeable: "UNKNOWN",
+      title: "",
+      url: "",
+      number: prNumber,
+      error: errorMessage
     };
   }
-  if (!repo.path) {
+}
+var exec;
+var init_git_pr = __esm({
+  "src/lib/git-pr.ts"() {
+    "use strict";
+    exec = promisify(execCb);
+  }
+});
+
+// src/lib/promotion.ts
+async function promoteCheckpoint(checkpointId) {
+  try {
+    const checkpointRes = await apiGet(`/checkpoints/${checkpointId}`);
+    const checkpoint = checkpointRes.data;
+    if (!checkpoint.branch_name) {
+      return {
+        promoted: false,
+        pr_url: null,
+        pr_number: null,
+        checklist_id: null,
+        message: "Checkpoint has no branch_name set",
+        error: "No branch_name on checkpoint"
+      };
+    }
+    const repoRes = await apiGet(`/repos/${checkpoint.repo_id}`);
+    const repo = repoRes.data;
+    if (!repo.path) {
+      return {
+        promoted: false,
+        pr_url: null,
+        pr_number: null,
+        checklist_id: null,
+        message: "Repo path not configured",
+        error: "Repo path not configured"
+      };
+    }
+    const baseBranch = repo.git_branch ?? "development";
+    const chkNumber = checkpoint.number.toString().padStart(3, "0");
+    const checklist = await createChecklistFromTemplates(
+      checkpoint.repo_id,
+      checkpointId,
+      "feat_to_development",
+      `CHK-${chkNumber}: ${checkpoint.title ?? "Untitled"} \u2192 ${baseBranch}`
+    );
+    const prResult = await createPR({
+      repoPath: repo.path,
+      head: checkpoint.branch_name,
+      base: baseBranch,
+      title: `CHK-${chkNumber}: ${checkpoint.title ?? "Checkpoint completion"}`,
+      body: `## Checkpoint CHK-${chkNumber}
+
+**Goal**: ${checkpoint.goal ?? "N/A"}
+
+Automatically created by CodeByPlan promotion engine.`
+    });
+    if (checklist && prResult.pr_url) {
+      await apiPut(`/merge-checklists/${checklist.id}`, {
+        pr_url: prResult.pr_url,
+        pr_number: prResult.pr_number,
+        status: "in_progress"
+      });
+    }
+    return {
+      promoted: true,
+      pr_url: prResult.pr_url,
+      pr_number: prResult.pr_number,
+      checklist_id: checklist?.id ?? null,
+      message: prResult.error ? `PR creation issue: ${prResult.error}` : `PR created: ${prResult.pr_url}`
+    };
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : String(err);
     return {
-      pushed: false,
-      message: "Repo path is not configured",
-      error: "Repo path is not configured"
+      promoted: false,
+      pr_url: null,
+      pr_number: null,
+      checklist_id: null,
+      message: "Promotion failed",
+      error: errorMessage
     };
   }
-  const sourceBranch = repo.git_branch ?? "development";
+}
+async function promoteToMain(repoId) {
   try {
-    await exec("git checkout main", { cwd: repo.path });
-    await exec(`git merge ${sourceBranch} --ff-only`, { cwd: repo.path });
-    await exec("git push origin main", { cwd: repo.path });
-    await exec(`git checkout ${sourceBranch}`, { cwd: repo.path });
+    const repoRes = await apiGet(`/repos/${repoId}`);
+    const repo = repoRes.data;
+    if (!repo.path) {
+      return {
+        promoted: false,
+        pr_url: null,
+        pr_number: null,
+        checklist_id: null,
+        message: "Repo path not configured",
+        error: "Repo path not configured"
+      };
+    }
+    const sourceBranch = repo.git_branch ?? "development";
+    const prResult = await createPR({
+      repoPath: repo.path,
+      head: sourceBranch,
+      base: "main",
+      title: `Promote ${sourceBranch} \u2192 main`,
+      body: `Promotion from ${sourceBranch} to main.
+
+Automatically created by CodeByPlan promotion engine.`
+    });
     return {
-      pushed: true,
-      message: `Merged ${sourceBranch} -> main and pushed to origin`
+      promoted: true,
+      pr_url: prResult.pr_url,
+      pr_number: prResult.pr_number,
+      checklist_id: null,
+      message: prResult.error ? `PR creation issue: ${prResult.error}` : `PR created: ${prResult.pr_url}`
     };
   } catch (err) {
-    try {
-      await exec(`git checkout ${sourceBranch}`, { cwd: repo.path });
-    } catch {
-    }
     const errorMessage = err instanceof Error ? err.message : String(err);
     return {
-      pushed: false,
-      message: "Auto-push failed",
+      promoted: false,
+      pr_url: null,
+      pr_number: null,
+      checklist_id: null,
+      message: "Promotion to main failed",
       error: errorMessage
     };
   }
 }
-var exec;
-var init_auto_push = __esm({
-  "src/lib/auto-push.ts"() {
+async function createChecklistFromTemplates(repoId, checkpointId, branchLevel, title) {
+  try {
+    const templatesRes = await apiGet(
+      `/repos/${repoId}/checklist-templates`,
+      { branch_level: branchLevel }
+    );
+    const templates = templatesRes.data ?? [];
+    const items = templates.map((t) => ({
+      title: t.title,
+      description: t.description,
+      is_required: t.is_required,
+      checked: false,
+      checked_at: null
+    }));
+    const checklistRes = await apiPost(
+      "/merge-checklists",
+      {
+        checkpoint_id: checkpointId,
+        branch_level: branchLevel,
+        title,
+        status: "pending",
+        items
+      }
+    );
+    return checklistRes.data;
+  } catch {
+    try {
+      const checklistRes = await apiPost(
+        "/merge-checklists",
+        {
+          checkpoint_id: checkpointId,
+          branch_level: branchLevel,
+          title,
+          status: "pending",
+          items: []
+        }
+      );
+      return checklistRes.data;
+    } catch {
+      return null;
+    }
+  }
+}
+var init_promotion = __esm({
+  "src/lib/promotion.ts"() {
     "use strict";
     init_api();
-    exec = promisify(execCb);
+    init_git_pr();
   }
 });
 
@@ -23514,27 +23780,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 +23820,25 @@ 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"),
+      branch_name: external_exports.string().nullable().optional().describe("Git branch name for this checkpoint (e.g. feat/CHK-061-git-overhaul)"),
+      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, branch_name, ideas, context, research, qa }) => {
     const update = {};
     if (title !== void 0) update.title = title;
     if (goal !== void 0) update.goal = goal;
@@ -23570,6 +23848,8 @@ 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 (branch_name !== void 0) update.branch_name = branch_name;
+    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;
@@ -23584,7 +23864,7 @@ function registerWriteTools(server) {
     }
   });
   server.registerTool("complete_checkpoint", {
-    description: "Mark a checkpoint as completed. Sets status to 'completed', completed_at to now, and triggers auto-push to main if enabled for the repo.",
+    description: "Mark a checkpoint as completed. Sets status to 'completed', completed_at to now, and triggers promotion (creates PR from feat branch to development).",
     inputSchema: {
       checkpoint_id: external_exports.string().uuid().describe("The checkpoint UUID")
     }
@@ -23595,8 +23875,13 @@ function registerWriteTools(server) {
         completed_at: (/* @__PURE__ */ new Date()).toISOString()
       });
       const checkpoint = res.data;
-      const pushResult = await autoPushToMain(checkpoint.repo_id);
-      return { content: [{ type: "text", text: JSON.stringify({ checkpoint, autoPush: pushResult }, null, 2) }] };
+      const featToDevResult = await promoteCheckpoint(checkpoint_id);
+      let devToMainResult = null;
+      const repoRes = await apiGet(`/repos/${checkpoint.repo_id}`);
+      if (repoRes.data.auto_push_enabled) {
+        devToMainResult = await promoteToMain(checkpoint.repo_id);
+      }
+      return { content: [{ type: "text", text: JSON.stringify({ checkpoint, promotion: { feat_to_development: featToDevResult, development_to_main: devToMainResult } }, null, 2) }] };
     } catch (err) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
@@ -23958,31 +24243,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: {
@@ -24017,13 +24277,74 @@ function registerWriteTools(server) {
       return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
   });
+  server.registerTool("create_pr", {
+    description: "Create a GitHub PR for a repo. Uses gh CLI.",
+    inputSchema: {
+      repo_id: external_exports.string().uuid().describe("The repo UUID"),
+      head: external_exports.string().describe("Source branch name"),
+      base: external_exports.string().describe("Target branch name"),
+      title: external_exports.string().describe("PR title"),
+      body: external_exports.string().optional().describe("PR description body")
+    }
+  }, async ({ repo_id, head, base, title, body }) => {
+    try {
+      const repoRes = await apiGet(`/repos/${repo_id}`);
+      const repo = repoRes.data;
+      if (!repo.path) {
+        return { content: [{ type: "text", text: "Error: Repo path is not configured." }], isError: true };
+      }
+      const result = await createPR({
+        repoPath: repo.path,
+        head,
+        base,
+        title,
+        body: body ?? ""
+      });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool("get_pr_status", {
+    description: "Get the status of a GitHub PR by number.",
+    inputSchema: {
+      repo_id: external_exports.string().uuid().describe("The repo UUID"),
+      pr_number: external_exports.number().int().describe("The PR number")
+    }
+  }, async ({ repo_id, pr_number }) => {
+    try {
+      const repoRes = await apiGet(`/repos/${repo_id}`);
+      const repo = repoRes.data;
+      if (!repo.path) {
+        return { content: [{ type: "text", text: "Error: Repo path is not configured." }], isError: true };
+      }
+      const status = await getPRStatus(repo.path, pr_number);
+      return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
+  server.registerTool("promote_checkpoint", {
+    description: "Trigger full promotion flow for a checkpoint. Creates merge checklist from templates and GitHub PR (feat branch \u2192 development).",
+    inputSchema: {
+      checkpoint_id: external_exports.string().uuid().describe("The checkpoint UUID")
+    }
+  }, async ({ checkpoint_id }) => {
+    try {
+      const result = await promoteCheckpoint(checkpoint_id);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+  });
 }
 var init_write = __esm({
   "src/tools/write.ts"() {
     "use strict";
     init_zod();
     init_api();
-    init_auto_push();
+    init_promotion();
+    init_git_pr();
     init_sync_engine();
   }
 });
@@ -24033,30 +24354,45 @@ import { exec as execCb2 } from "node:child_process";
 import { promisify as promisify2 } from "node:util";
 function registerFileGenTools(server) {
   server.registerTool("git_commit", {
-    description: "Stage files and create a git commit in a repo. If files are specified, stages only those files. Otherwise stages all changes.",
+    description: "Stage files and create a git commit in a repo. If files are specified, stages only those files. Otherwise stages all changes. Optionally verifies the current branch matches branch_name.",
     inputSchema: {
       repo_id: external_exports.string().uuid().describe("The repo UUID"),
       message: external_exports.string().describe("Commit message"),
-      files: external_exports.array(external_exports.string()).optional().describe("Specific file paths to stage (relative to repo root). If omitted, stages all changes.")
+      files: external_exports.array(external_exports.string()).optional().describe("Specific file paths to stage (relative to repo root). If omitted, stages all changes."),
+      branch_name: external_exports.string().optional().describe("Expected branch name. If provided, verifies the repo is on this branch before committing.")
     }
-  }, async ({ repo_id, message, files }) => {
+  }, async ({ repo_id, message, files, branch_name }) => {
     try {
       const repoRes = await apiGet(`/repos/${repo_id}`);
       const repo = repoRes.data;
       if (!repo.path) {
         return { content: [{ type: "text", text: "Error: Repo path is not configured." }], isError: true };
       }
+      if (branch_name) {
+        const { stdout: currentBranch } = await exec2("git rev-parse --abbrev-ref HEAD", { cwd: repo.path });
+        if (currentBranch.trim() !== branch_name) {
+          return {
+            content: [{
+              type: "text",
+              text: `Error: Expected branch "${branch_name}" but currently on "${currentBranch.trim()}".`
+            }],
+            isError: true
+          };
+        }
+      }
       const addCmd = files && files.length > 0 ? `git add ${files.map((f) => `"${f}"`).join(" ")}` : "git add .";
       await exec2(addCmd, { cwd: repo.path });
       const { stdout: stdout5, stderr } = await exec2(
         `git commit -m "${message.replace(/"/g, '\\"')}"`,
         { cwd: repo.path }
       );
+      const { stdout: branch } = await exec2("git rev-parse --abbrev-ref HEAD", { cwd: repo.path });
       return {
         content: [{
           type: "text",
           text: JSON.stringify({
             status: "committed",
+            branch: branch.trim(),
             output: stdout5.trim(),
             warnings: stderr.trim() || void 0
           }, null, 2)

package/package.json

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