@nolto/cli 0.8.1 → 0.10.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { createRequire as createRequire3 } from "module";
 import { fileURLToPath as fileURLToPath4 } from "url";
-import path15 from "path";
+import path19 from "path";
 import { CommanderError } from "commander";
 
 // src/config.ts
@@ -56,7 +56,7 @@ function mapHttpStatusToCliError(status, opts = {}) {
     return new CliError(
       opts.serverMessage ?? "This project is bound to a different repository.",
       2,
-      "Owner: run `nolto link --rebind` inside the repository that should own this project.",
+      "Check that nolto.json points to the project for this repository (nolto link --show). Owner: run `nolto link --rebind` inside the repository that should own this project.",
       status
     );
   }
@@ -314,11 +314,11 @@ function maskToken(token) {
 function createHttpClient(opts) {
   const { baseUrl, version, token } = opts;
   const base = baseUrl.replace(/\/+$/, "");
-  async function request(method, path16, body) {
-    if (!path16.startsWith("/api/")) {
-      throw new CliError(`HTTP client path must start with /api/, got: ${path16}`, 2);
+  async function request(method, path20, body) {
+    if (!path20.startsWith("/api/")) {
+      throw new CliError(`HTTP client path must start with /api/, got: ${path20}`, 2);
     }
-    const url = `${base}${path16}`;
+    const url = `${base}${path20}`;
     const headers = {
       "Content-Type": "application/json",
       "User-Agent": `${CLI_USER_AGENT_NAME}/${version}`
@@ -374,14 +374,15 @@ function createHttpClient(opts) {
 import { Command } from "commander";
 
 // src/commands/init.ts
-import readline from "readline/promises";
+import readline2 from "readline/promises";
 import { createRequire } from "module";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import os3 from "os";
-import path8 from "path";
+import path9 from "path";
 import fs from "fs";
 
 // src/commands/link.ts
+import readline from "readline/promises";
 import os2 from "os";
 import path5 from "path";
 import { statSync as statSync2 } from "fs";
@@ -519,12 +520,12 @@ function normalizeRemote(raw) {
   const firstSlash = s.indexOf("/");
   if (firstSlash <= 0) return null;
   let host = s.slice(0, firstSlash).toLowerCase();
-  let path16 = s.slice(firstSlash + 1);
+  let path20 = s.slice(firstSlash + 1);
   if (hadScheme) host = host.replace(/:\d+$/, "");
-  path16 = path16.replace(/\/+/g, "/").replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
-  if (path16.length === 0) return null;
-  if (HOSTED_LOWERCASE_PATH.has(host)) path16 = path16.toLowerCase();
-  return `${host}/${path16}`;
+  path20 = path20.replace(/\/+/g, "/").replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+  if (path20.length === 0) return null;
+  if (HOSTED_LOWERCASE_PATH.has(host)) path20 = path20.toLowerCase();
+  return `${host}/${path20}`;
 }
 
 // ../roadmap-schema/src/index.ts
@@ -819,14 +820,51 @@ async function handleShow(deps, projectBindingPath, mode2) {
     }
   }
 }
-async function handleRebind(deps, projectId, root, mode2) {
+async function handleRebind(deps, projectId, root, mode2, yes) {
   if (!UUID_RE.test(projectId)) {
     throw new CliError(
       `Invalid project ID: "${projectId}". Must be a UUID (e.g. 00000000-0000-0000-0000-000000000001).`,
       2
     );
   }
+  const result = await deps.http.get("/api/projects");
+  const projects = Array.isArray(result.projects) ? result.projects : [];
+  const project = projects.find((candidate) => candidate.id === projectId);
+  if (project == null) {
+    throw new CliError(
+      `Project ${projectId} is not in your accessible projects. Check nolto.json (nolto link --show) before rebinding.`,
+      2
+    );
+  }
   const repoIdentity = await makeRepoIdentityResolver(deps)(root);
+  if (mode2 !== "json") {
+    process.stdout.write(`Project   : ${project.name} (${project.id})
+`);
+    process.stdout.write(`Bound to  : ${project.repoIdentity ?? "not bound"}
+`);
+    process.stdout.write(`Rebind to : ${repoIdentity.kind}:${repoIdentity.value}
+`);
+  }
+  if (!yes) {
+    if (mode2 === "json") {
+      throw new CliError(
+        "--rebind requires confirmation. Pass --yes to skip the prompt in --json mode.",
+        2
+      );
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let confirmed = false;
+    try {
+      const answer = await rl.question(`Rebind "${project.name}" to this repository? [y/N] `);
+      confirmed = answer.trim().toLowerCase() === "y";
+    } finally {
+      rl.close();
+    }
+    if (!confirmed) {
+      process.stdout.write("Aborted.\n");
+      return;
+    }
+  }
   await deps.http.post(`/api/projects/${projectId}/repo-binding`, { repoIdentity });
   if (mode2 === "json") {
     printResult({ rebound: true, projectId, repoIdentity }, mode2);
@@ -836,10 +874,10 @@ async function handleRebind(deps, projectId, root, mode2) {
   }
 }
 async function handleUnlink(projectBindingPath, mode2) {
-  const { readFile: readFile8, writeFile: writeFile7, chmod: chmod2 } = await import("fs/promises");
+  const { readFile: readFile12, writeFile: writeFile10, chmod: chmod2 } = await import("fs/promises");
   let existing = {};
   try {
-    const raw = await readFile8(projectBindingPath, "utf8");
+    const raw = await readFile12(projectBindingPath, "utf8");
     const parsed = JSON.parse(raw);
     if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
       throw new CliError(
@@ -854,7 +892,7 @@ async function handleUnlink(projectBindingPath, mode2) {
   }
   const { projectId: _removed, ...rest } = existing;
   void _removed;
-  await writeFile7(projectBindingPath, JSON.stringify(rest, null, 2) + "\n", { mode: 420 });
+  await writeFile10(projectBindingPath, JSON.stringify(rest, null, 2) + "\n", { mode: 420 });
   await chmod2(projectBindingPath, 420);
   if (mode2 === "json") {
     printResult({ unlinked: true, projectBindingPath }, mode2);
@@ -945,7 +983,7 @@ Commit nolto.json to share the binding with your team.
 function register(program, deps) {
   const cmd = program.command("link [projectId]").description(
     "Bind this repository to a Nolto project.\nWrites nolto.json at the repo root. Commit it to share the binding with your team.\n\nExamples:\n  nolto link <uuid>      Write / update nolto.json\n  nolto link --show      Show the current binding\n  nolto link --rebind    Rebind the project to this repository\n  nolto link --unlink    Remove the projectId from nolto.json"
-  ).option("--show", "Show the current repo binding (path + projectId + source)").option("--rebind", "Rebind the project to this repository (owner only, once per 7 days)").option("--unlink", "Remove the projectId key from nolto.json");
+  ).option("--show", "Show the current repo binding (path + projectId + source)").option("--rebind", "Rebind the project to this repository (owner only, once per 7 days)").option("-y, --yes", "Skip the rebind confirmation prompt").option("--unlink", "Remove the projectId key from nolto.json");
   cmd.action(async (projectId) => {
     const { output } = deps;
     const projectBindingPath = deps.repoBinding?.path ?? deps.projectBindingPath ?? null;
@@ -973,7 +1011,7 @@ function register(program, deps) {
       }
       const startDir = resolveStartDir(process.env, process.cwd());
       const root = findRepoRoot(startDir).root;
-      await handleRebind(deps, effectiveProjectId, root, mode2);
+      await handleRebind(deps, effectiveProjectId, root, mode2, cmd.opts()["yes"] === true);
       return;
     }
     if (projectId == null || projectId.trim().length === 0) {
@@ -1103,14 +1141,55 @@ async function scaffoldRoadmap(args) {
   return { created: true, path: filePath };
 }
 
+// src/git-merge-driver.ts
+import { execFile as execFile2 } from "child_process";
+import { readFile as readFile5, writeFile as writeFile6 } from "fs/promises";
+import path8 from "path";
+import { promisify } from "util";
+var ATTRIBUTE_LINE = ".nolto/roadmaps/*.json merge=nolto-roadmap";
+var DRIVER_COMMAND = "nolto merge-file %A %B --base %O";
+async function ensureGitAttributes(root) {
+  const filePath = path8.join(root, ".gitattributes");
+  let content = "";
+  try {
+    content = await readFile5(filePath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  if (content.split(/\r?\n/).includes(ATTRIBUTE_LINE)) return "exists";
+  const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
+  await writeFile6(filePath, content + separator + ATTRIBUTE_LINE + "\n", "utf8");
+  return "added";
+}
+async function configureMergeDriver(root, exec = async (file, args, options) => {
+  const execFileAsync = promisify(execFile2);
+  await execFileAsync(file, args, options);
+}) {
+  try {
+    await exec(
+      "git",
+      ["config", "--local", "merge.nolto-roadmap.name", "Nolto roadmap merge"],
+      { cwd: root }
+    );
+    await exec(
+      "git",
+      ["config", "--local", "merge.nolto-roadmap.driver", DRIVER_COMMAND],
+      { cwd: root }
+    );
+    return "configured";
+  } catch {
+    return "skipped";
+  }
+}
+
 // src/commands/init.ts
-var __dirname2 = path8.dirname(fileURLToPath2(import.meta.url));
+var __dirname2 = path9.dirname(fileURLToPath2(import.meta.url));
 var _require = createRequire(import.meta.url);
 function getCliVersion() {
   const candidates = [
-    path8.resolve(__dirname2, "../package.json"),
+    path9.resolve(__dirname2, "../package.json"),
     // bundled: dist/../package.json
-    path8.resolve(__dirname2, "../../package.json")
+    path9.resolve(__dirname2, "../../package.json")
     // source:  src/commands/../../package.json
   ];
   for (const pkgPath of candidates) {
@@ -1162,10 +1241,27 @@ async function pickProject(rl, http, projects, promptText) {
   }
   return void 0;
 }
+async function selectRepoProject(rl, http, projects, defaultProjectId) {
+  const defaultProject = defaultProjectId == null ? void 0 : projects.find((project) => project.id === defaultProjectId);
+  if (defaultProject != null) {
+    const useDefault = await rl.question(
+      `Use "${defaultProject.name}" (${defaultProject.id}) for this repository? [Y/n] `
+    );
+    if (useDefault.trim().toLowerCase() !== "n") {
+      return defaultProject;
+    }
+  }
+  return pickProject(
+    rl,
+    http,
+    projects,
+    "Project number for this repository, 'c' to create new (or Enter to skip): "
+  );
+}
 function register2(program, deps) {
   program.command("init").description("Interactive setup: configure token, base URL, and default project.").option("--force", "Overwrite existing config without prompting").action(async (opts) => {
     const configPath = deps.configPath;
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const rl = readline2.createInterface({ input: process.stdin, output: process.stdout });
     try {
       let configureGlobal = opts.force === true;
       if (!configureGlobal) {
@@ -1221,6 +1317,9 @@ function register2(program, deps) {
         );
         defaultProjectId = selected?.id;
         defaultProjectName = selected?.name;
+        if (selected != null && !projects.some((project) => project.id === selected.id)) {
+          projects = [...projects, selected];
+        }
         await saveConfigFile(configPath, {
           token,
           baseUrl: baseUrl !== DEFAULT_BASE_URL ? baseUrl : void 0,
@@ -1251,25 +1350,41 @@ Saved ${configPath}
       }
       if (isHomeDirectory(root)) {
         process.stderr.write(
-          `Refusing to set up your home directory as a repository root (found ${path8.join(os3.homedir(), ".git")}). Run nolto init inside a project repository.
+          `Refusing to set up your home directory as a repository root (found ${path9.join(os3.homedir(), ".git")}). Run nolto init inside a project repository.
 `
         );
         return;
       }
       const existingBinding = deps.repoBinding?.error == null ? deps.repoBinding?.binding ?? null : null;
-      let repoProject = existingBinding != null ? { id: existingBinding.projectId, name: path8.basename(root) } : defaultProjectId != null ? { id: defaultProjectId, name: defaultProjectName ?? path8.basename(root) } : void 0;
-      if (repoProject == null) {
-        http ??= createHttpClient({ baseUrl, token, version: getCliVersion() });
-        if (projects == null) {
-          const result = await http.get("/api/projects");
-          projects = Array.isArray(result.projects) ? result.projects : [];
+      const repoHttp = http ?? deps.http;
+      if (projects == null) {
+        const result = await repoHttp.get("/api/projects");
+        projects = Array.isArray(result.projects) ? result.projects : [];
+      }
+      let keepExistingBinding = false;
+      let repoProject;
+      if (existingBinding != null) {
+        const boundProject = projects.find(
+          (project) => project.id === existingBinding.projectId
+        );
+        if (boundProject != null) {
+          process.stdout.write(
+            `Existing binding: nolto.json \u2192 "${boundProject.name}" (${boundProject.id})
+`
+          );
+        } else {
+          process.stderr.write(
+            `Warning: nolto.json points to project ${existingBinding.projectId}, which is not in your accessible projects.
+`
+          );
         }
-        repoProject = await pickProject(
-          rl,
-          http,
-          projects,
-          "Project number for this repository, 'c' to create new (or Enter to skip): "
+        const keep = await rl.question(
+          boundProject != null ? "Keep this binding? [Y/n] " : "Keep this binding? [y/N] "
         );
+        keepExistingBinding = boundProject != null ? keep.trim().toLowerCase() !== "n" : keep.trim().toLowerCase() === "y";
+        repoProject = keepExistingBinding ? boundProject ?? { id: existingBinding.projectId, name: path9.basename(root) } : await selectRepoProject(rl, repoHttp, projects, defaultProjectId);
+      } else {
+        repoProject = await selectRepoProject(rl, repoHttp, projects, defaultProjectId);
       }
       if (repoProject == null) {
         process.stdout.write("Skipped repo setup (no project selected).\n");
@@ -1281,9 +1396,9 @@ Set up this repository (${root}) for roadmap sync? [Y/n] `);
         process.stdout.write("Skipped repo setup.\n");
         return;
       }
-      const bindingPath = deps.repoBinding?.path ?? path8.join(root, "nolto.json");
-      if (existingBinding != null) {
-        process.stdout.write(`binding:        kept ${bindingPath} (${existingBinding.projectId})
+      const bindingPath = deps.repoBinding?.path ?? path9.join(root, "nolto.json");
+      if (keepExistingBinding) {
+        process.stdout.write(`binding:        kept ${bindingPath} (${repoProject.id})
 `);
       } else {
         if (deps.repoBinding?.error != null) {
@@ -1293,22 +1408,22 @@ Set up this repository (${root}) for roadmap sync? [Y/n] `);
           );
         }
         await writeRepoBinding(root, repoProject.id);
-        process.stdout.write(`binding:        wrote ${path8.join(root, "nolto.json")}
+        process.stdout.write(`binding:        wrote ${path9.join(root, "nolto.json")}
 `);
       }
       const sourceDir = resolveSkillSourceDir();
       const version = getCliVersion();
       const claudeInstall = await installSkill({
-        skillsParentDir: path8.join(root, ".claude", "skills"),
+        skillsParentDir: path9.join(root, ".claude", "skills"),
         sourceDir,
         version
       });
       process.stdout.write(`skill (claude): ${claudeInstall.action} ${claudeInstall.targetDir}
 `);
-      const usesAgentsTooling = fs.existsSync(path8.join(root, ".agents")) || fs.existsSync(path8.join(root, ".codex")) || fs.existsSync(path8.join(root, "AGENTS.md"));
+      const usesAgentsTooling = fs.existsSync(path9.join(root, ".agents")) || fs.existsSync(path9.join(root, ".codex")) || fs.existsSync(path9.join(root, "AGENTS.md"));
       if (usesAgentsTooling) {
         const agentsInstall = await installSkill({
-          skillsParentDir: path8.join(root, ".agents", "skills"),
+          skillsParentDir: path9.join(root, ".agents", "skills"),
           sourceDir,
           version
         });
@@ -1330,6 +1445,13 @@ Set up this repository (${root}) for roadmap sync? [Y/n] `);
 ` : `watch registry: already registered
 `
       );
+      const attributesResult = await ensureGitAttributes(root);
+      process.stdout.write(`gitattributes:  ${attributesResult} .gitattributes
+`);
+      const mergeDriverResult = await configureMergeDriver(root, deps.gitMergeExec);
+      process.stdout.write(
+        mergeDriverResult === "configured" ? "merge driver:   configured\n" : "merge driver:   skipped (git unavailable)\n"
+      );
     } finally {
       rl.close();
     }
@@ -1359,7 +1481,7 @@ async function promptHidden(rl, prompt) {
 }
 
 // src/commands/login.ts
-import readline2 from "readline/promises";
+import readline3 from "readline/promises";
 
 // src/login-poll.ts
 async function pollUntilToken(opts) {
@@ -1425,7 +1547,7 @@ function register3(program, deps) {
         } catch {
         }
         if (existing?.token) {
-          const rl = readline2.createInterface({
+          const rl = readline3.createInterface({
             input: process.stdin,
             output: process.stdout
           });
@@ -1549,15 +1671,15 @@ function register4(program, deps) {
 }
 
 // src/commands/sync.ts
-import { copyFile, mkdir as mkdir6, readFile as readFile5, readdir as readdir2, rename as rename2, rmdir, unlink as unlink2 } from "fs/promises";
+import { copyFile, mkdir as mkdir6, readFile as readFile6, readdir as readdir2, rename as rename2, rmdir, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 
 // src/sync-repo.ts
-import path10 from "path";
+import path11 from "path";
 
 // src/sync-core.ts
 import { createHash } from "crypto";
-import path9 from "path";
+import path10 from "path";
 function sha256Hex(content) {
   return "sha256:" + createHash("sha256").update(content, "utf8").digest("hex");
 }
@@ -1578,10 +1700,10 @@ function collectPlanRefs(roadmap) {
   }
   return refs;
 }
-async function loadValidRoadmap(filePath, readFile8) {
+async function loadValidRoadmap(filePath, readFile12) {
   let raw;
   try {
-    raw = await readFile8(filePath);
+    raw = await readFile12(filePath);
   } catch {
     throw new CliError(`No roadmap found at ${filePath}. Run \`nolto init\` first.`, 2);
   }
@@ -1604,7 +1726,7 @@ async function loadValidRoadmap(filePath, readFile8) {
 async function buildSyncBody(args) {
   const planDocuments = [];
   for (const ref of collectPlanRefs(args.roadmap)) {
-    const absolute = path9.join(args.repoRoot, ref.path);
+    const absolute = path10.join(args.repoRoot, ref.path);
     if (!args.deps.fileExists(absolute)) {
       args.deps.warn(`plan file not found, skipping: ${ref.path}`);
       continue;
@@ -1651,7 +1773,7 @@ async function listRoadmapFiles(roadmapsDir, io) {
   }
 }
 async function migrateLegacyRoadmap(args) {
-  const targetPath = path10.join(args.roadmapsDir, `${args.slug}.json`);
+  const targetPath = path11.join(args.roadmapsDir, `${args.slug}.json`);
   await args.io.mkdir(args.roadmapsDir);
   try {
     await args.io.rename(args.legacyPath, targetPath);
@@ -1660,7 +1782,7 @@ async function migrateLegacyRoadmap(args) {
     await args.io.unlink(args.legacyPath);
   }
   try {
-    await args.io.rmdir(path10.dirname(args.legacyPath));
+    await args.io.rmdir(path11.dirname(args.legacyPath));
   } catch {
   }
   args.io.log(
@@ -1669,14 +1791,14 @@ async function migrateLegacyRoadmap(args) {
   return `${args.slug}.json`;
 }
 async function syncRepo(args, io) {
-  const bindingPath = path10.join(args.root, "nolto.json");
+  const bindingPath = path11.join(args.root, "nolto.json");
   const binding = await loadRepoBinding(bindingPath);
   const projectId = binding?.projectId ?? args.defaultProjectId;
   if (projectId == null) {
     throw new CliError("No project binding. Run `nolto init` or `nolto link <projectId>`.", 2);
   }
-  const roadmapsDir = path10.join(args.root, ".nolto", "roadmaps");
-  const legacyPath = path10.join(args.root, ".roadmap", "roadmap.json");
+  const roadmapsDir = path11.join(args.root, ".nolto", "roadmaps");
+  const legacyPath = path11.join(args.root, ".roadmap", "roadmap.json");
   let roadmapFiles = await listRoadmapFiles(roadmapsDir, io);
   if (roadmapFiles.length > 0) {
     if (io.fileExists(legacyPath)) {
@@ -1691,7 +1813,7 @@ async function syncRepo(args, io) {
       );
       return { results: [], planAbsPaths: [] };
     }
-    const migrationSlug = binding?.roadmapSlug ?? slugifyProjectId(path10.basename(args.root));
+    const migrationSlug = binding?.roadmapSlug ?? slugifyProjectId(path11.basename(args.root));
     roadmapFiles = [
       await migrateLegacyRoadmap({
         slug: migrationSlug,
@@ -1715,14 +1837,14 @@ async function syncRepo(args, io) {
           2
         );
       }
-      const filePath = path10.join(roadmapsDir, fileName);
+      const filePath = path11.join(roadmapsDir, fileName);
       return { slug, roadmap: await loadValidRoadmap(filePath, io.readFile) };
     })
   );
   const planAbsPaths = /* @__PURE__ */ new Set();
   for (const { roadmap } of roadmaps) {
     for (const ref of collectPlanRefs(roadmap)) {
-      planAbsPaths.add(path10.join(args.root, ref.path));
+      planAbsPaths.add(path11.join(args.root, ref.path));
     }
   }
   const results = [];
@@ -1756,7 +1878,7 @@ function register5(program, deps) {
     const response = await syncRepo(
       { root, defaultProjectId: deps.settings.defaultProjectId, migrateLegacy: true },
       {
-        readFile: (p) => readFile5(p, "utf8"),
+        readFile: (p) => readFile6(p, "utf8"),
         fileExists: (p) => existsSync3(p),
         listDir: (p) => readdir2(p),
         rename: rename2,
@@ -1800,10 +1922,531 @@ function register5(program, deps) {
   });
 }
 
+// src/commands/diff.ts
+import { readFile as readFile7 } from "fs/promises";
+import path13 from "path";
+
+// src/roadmap-diff.ts
+function diffRoadmaps(local, server) {
+  if (local === null && server === null) return [];
+  if (local === null) return [{ kind: "meta", field: "roadmap", side: "server" }];
+  if (server === null) return [{ kind: "meta", field: "roadmap", side: "local" }];
+  const entries = [];
+  const serverPhases = new Map(server.phases.map((phase) => [phase.id, phase]));
+  for (const localPhase of local.phases) {
+    const serverPhase = serverPhases.get(localPhase.id);
+    if (!serverPhase) {
+      entries.push({
+        kind: "phase-removed",
+        id: localPhase.id,
+        title: localPhase.title,
+        side: "local"
+      });
+      continue;
+    }
+    const serverTasks = new Map(serverPhase.tasks.map((task) => [task.id, task]));
+    for (const localTask of localPhase.tasks) {
+      const serverTask = serverTasks.get(localTask.id);
+      if (!serverTask) {
+        entries.push({
+          kind: "task-removed",
+          id: localTask.id,
+          title: localTask.title,
+          side: "local"
+        });
+      } else if (localTask.status !== serverTask.status) {
+        entries.push({
+          kind: "task-status",
+          id: localTask.id,
+          title: localTask.title,
+          local: localTask.status,
+          server: serverTask.status
+        });
+      }
+    }
+    const localTaskIds = new Set(localPhase.tasks.map((task) => task.id));
+    for (const serverTask of serverPhase.tasks) {
+      if (!localTaskIds.has(serverTask.id)) {
+        entries.push({
+          kind: "task-added",
+          id: serverTask.id,
+          title: serverTask.title,
+          side: "server"
+        });
+      }
+    }
+  }
+  const localPhaseIds = new Set(local.phases.map((phase) => phase.id));
+  for (const serverPhase of server.phases) {
+    if (!localPhaseIds.has(serverPhase.id)) {
+      entries.push({
+        kind: "phase-added",
+        id: serverPhase.id,
+        title: serverPhase.title,
+        side: "server"
+      });
+    }
+  }
+  const meta = [
+    { field: "updatedAt", local: local.updatedAt, server: server.updatedAt },
+    {
+      field: "currentTaskId",
+      local: local.currentTaskId ?? null,
+      server: server.currentTaskId ?? null
+    },
+    { field: "summary", local: local.summary, server: server.summary }
+  ];
+  for (const item of meta) {
+    if (item.local !== item.server) entries.push({ kind: "meta", ...item });
+  }
+  return entries;
+}
+function truncate(value) {
+  if (value == null) return "none";
+  const singleLine = value.replace(/\s+/g, " ");
+  return singleLine.length <= 60 ? singleLine : singleLine.slice(0, 57) + "...";
+}
+function formatRoadmapDiff(slug, entries) {
+  if (entries.length === 0) return [];
+  const lines = [`${slug}:`];
+  for (const entry of entries) {
+    if (entry.kind === "task-status") {
+      lines.push(`  ${entry.id}: ${entry.local} (local) != ${entry.server} (server)`);
+    } else if (entry.kind === "task-added" || entry.kind === "task-removed") {
+      lines.push(`  ${entry.side} only task ${entry.id} "${truncate(entry.title)}"`);
+    } else if (entry.kind === "phase-added" || entry.kind === "phase-removed") {
+      lines.push(`  ${entry.side} only phase ${entry.id} "${truncate(entry.title)}"`);
+    } else if (entry.field === "roadmap") {
+      lines.push(`  ${entry.side} only roadmap`);
+    } else {
+      lines.push(
+        `  ${entry.field}: ${truncate(entry.local)} (local) != ${truncate(entry.server)} (server)`
+      );
+    }
+  }
+  return lines;
+}
+
+// src/roadmap-read.ts
+import { readdir as readdir3 } from "fs/promises";
+import path12 from "path";
+async function resolveRoadmapReadContext(deps) {
+  if (deps.settings.token == null) {
+    throw new CliError("Not authenticated. Run `nolto login` or set NOLTO_TOKEN.", 3);
+  }
+  const startDir = resolveStartDir(process.env, process.cwd());
+  const { root, foundGit } = findRepoRoot(startDir);
+  if (!foundGit) {
+    throw new CliError("No git repository found. Run inside a repo set up with `nolto init`.", 2);
+  }
+  const binding = await loadRepoBinding(path12.join(root, "nolto.json"));
+  const projectId = binding?.projectId ?? deps.settings.defaultProjectId;
+  if (projectId == null) {
+    throw new CliError("No project binding. Run `nolto init` or `nolto link <projectId>`.", 2);
+  }
+  return { root, projectId };
+}
+async function listLocalRoadmapSlugs(root) {
+  try {
+    const entries = await readdir3(path12.join(root, ".nolto", "roadmaps"));
+    return entries.filter((entry) => entry.endsWith(".json")).map((entry) => entry.slice(0, -".json".length)).sort();
+  } catch (err) {
+    if (err != null && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+// src/commands/diff.ts
+function register6(program, deps) {
+  program.command("diff [slug]").description("Compare local roadmaps with the server without changing either side.").action(async (requestedSlug) => {
+    const { root, projectId } = await resolveRoadmapReadContext(deps);
+    const list = await deps.http.get(
+      `/api/projects/${projectId}/roadmaps`
+    );
+    const serverBySlug = new Map(list.roadmaps.map((roadmap) => [roadmap.slug, roadmap]));
+    const localSlugs = await listLocalRoadmapSlugs(root);
+    const localSlugSet = new Set(localSlugs);
+    const allSlugs = [.../* @__PURE__ */ new Set([...localSlugs, ...serverBySlug.keys()])].sort();
+    if (requestedSlug != null && !allSlugs.includes(requestedSlug)) {
+      throw new CliError(
+        `Roadmap "${requestedSlug}" was not found locally or on the server.`,
+        2
+      );
+    }
+    const targetSlugs = requestedSlug == null ? allSlugs : [requestedSlug];
+    let differing = 0;
+    for (const slug of targetSlugs) {
+      let local = null;
+      if (localSlugSet.has(slug)) {
+        const localPath = path13.join(root, ".nolto", "roadmaps", `${slug}.json`);
+        try {
+          local = await loadValidRoadmap(localPath, (filePath) => readFile7(filePath, "utf8"));
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(`Warning: could not diff ${slug}.json: ${message}
+`);
+          process.stdout.write(`${slug}:
+  local roadmap is present but invalid
+`);
+          differing += 1;
+          continue;
+        }
+      }
+      let server = null;
+      if (serverBySlug.has(slug) && local !== null) {
+        const response = await deps.http.get(
+          `/api/projects/${projectId}/roadmaps/${encodeURIComponent(slug)}`
+        );
+        const validation = validateRoadmap(response.roadmap);
+        if (validation.errors.length > 0) {
+          throw new CliError(
+            `Server roadmap "${slug}" failed validation: ${validation.errors.join("; ")}`,
+            5
+          );
+        }
+        server = response.roadmap;
+      }
+      const entries = local === null && serverBySlug.has(slug) ? [{ kind: "meta", field: "roadmap", side: "server" }] : diffRoadmaps(local, server);
+      if (entries.length === 0) continue;
+      differing += 1;
+      process.stdout.write(formatRoadmapDiff(slug, entries).join("\n") + "\n");
+    }
+    if (differing === 0) {
+      process.stdout.write("Up to date with the server.\n");
+      process.exitCode = 0;
+    } else {
+      process.stdout.write(`${differing} roadmap(s) differ
+`);
+      process.exitCode = 1;
+    }
+  });
+}
+
+// src/commands/pull.ts
+import { mkdir as mkdir7, readFile as readFile8, writeFile as writeFile7 } from "fs/promises";
+import path14 from "path";
+
+// src/roadmap-merge.ts
+import { isDeepStrictEqual } from "util";
+function taskLocations(roadmap) {
+  const result = /* @__PURE__ */ new Map();
+  for (const phase of roadmap?.phases ?? []) {
+    for (const task of phase.tasks) result.set(task.id, { task, phaseId: phase.id });
+  }
+  return result;
+}
+function chooseField(args) {
+  if (args.baseExists && isDeepStrictEqual(args.ours, args.base)) return args.theirs;
+  if (args.baseExists && isDeepStrictEqual(args.theirs, args.base)) return args.ours;
+  if (isDeepStrictEqual(args.ours, args.theirs)) return args.ours;
+  return args.newer === "ours" ? args.ours : args.theirs;
+}
+function chooseStatus(base, ours, theirs) {
+  if (base !== void 0) {
+    const oursChanged = ours.status !== base.status;
+    const theirsChanged = theirs.status !== base.status;
+    if (!oursChanged) return theirs.status;
+    if (!theirsChanged) return ours.status;
+  }
+  const candidates = [ours, theirs];
+  if (candidates.some((task) => task.status === "done" && task.completedAt != null)) {
+    return "done";
+  }
+  for (const status of ["blocked", "in-progress", "todo"]) {
+    if (candidates.some((task) => task.status === status)) return status;
+  }
+  return base?.status !== "done" ? base?.status ?? "todo" : "todo";
+}
+function earliest(values) {
+  return values.filter((value) => value != null).sort((a, b) => Date.parse(a) - Date.parse(b))[0];
+}
+function latest(values) {
+  return values.filter((value) => value != null).sort((a, b) => Date.parse(b) - Date.parse(a))[0];
+}
+function assignOptional(target, key, value) {
+  if (value !== void 0) Object.assign(target, { [key]: value });
+}
+function cloneSingleTask(task) {
+  const cloned = { ...task };
+  if (task.dependsOn !== void 0) cloned.dependsOn = [...task.dependsOn];
+  if (cloned.status !== "done") delete cloned.completedAt;
+  return cloned;
+}
+function mergeTask(args) {
+  const baseExists = args.base !== void 0;
+  const status = chooseStatus(args.base, args.ours, args.theirs);
+  const merged = {
+    id: args.ours.id,
+    title: chooseField({
+      baseExists,
+      base: args.base?.title,
+      ours: args.ours.title,
+      theirs: args.theirs.title,
+      newer: args.newer
+    }),
+    status
+  };
+  assignOptional(
+    merged,
+    "startedAt",
+    earliest([args.base?.startedAt, args.ours.startedAt, args.theirs.startedAt])
+  );
+  if (status === "done") {
+    assignOptional(
+      merged,
+      "completedAt",
+      latest([args.base?.completedAt, args.ours.completedAt, args.theirs.completedAt])
+    );
+  }
+  assignOptional(merged, "note", chooseField({
+    baseExists,
+    base: args.base?.note,
+    ours: args.ours.note,
+    theirs: args.theirs.note,
+    newer: args.newer
+  }));
+  assignOptional(merged, "plan", chooseField({
+    baseExists,
+    base: args.base?.plan,
+    ours: args.ours.plan,
+    theirs: args.theirs.plan,
+    newer: args.newer
+  }));
+  const dependsOn = [
+    ...args.ours.dependsOn ?? [],
+    ...args.theirs.dependsOn ?? []
+  ].filter((id, index, values) => values.indexOf(id) === index);
+  if (dependsOn.length > 0) merged.dependsOn = dependsOn;
+  return merged;
+}
+function shouldKeep(base, ours, theirs) {
+  if (base === void 0) return ours !== void 0 || theirs !== void 0;
+  if (ours === void 0 && theirs === void 0) return false;
+  if (ours === void 0) return !isDeepStrictEqual(theirs, base);
+  if (theirs === void 0) return !isDeepStrictEqual(ours, base);
+  return true;
+}
+function orderTasks(args) {
+  const oursPhase = args.ours.phases.find((phase) => phase.id === args.phaseId);
+  const theirsPhase = args.theirs.phases.find((phase) => phase.id === args.phaseId);
+  const ordered = (oursPhase?.tasks ?? []).map((task) => task.id).filter((id) => args.taskIds.has(id));
+  let nearestCommon = null;
+  let insertAfter = null;
+  for (const task of theirsPhase?.tasks ?? []) {
+    if (!args.taskIds.has(task.id)) continue;
+    if (args.oursLocations.has(task.id)) {
+      if (ordered.includes(task.id)) {
+        nearestCommon = task.id;
+        insertAfter = task.id;
+      }
+      continue;
+    }
+    if (nearestCommon === null || insertAfter === null) {
+      ordered.push(task.id);
+      continue;
+    }
+    const index = ordered.indexOf(insertAfter);
+    ordered.splice(index + 1, 0, task.id);
+    insertAfter = task.id;
+  }
+  return ordered;
+}
+function mergeRoadmaps(args) {
+  const newer = Date.parse(args.theirs.updatedAt) > Date.parse(args.ours.updatedAt) ? "theirs" : "ours";
+  const newerRoadmap = newer === "ours" ? args.ours : args.theirs;
+  const olderRoadmap = newer === "ours" ? args.theirs : args.ours;
+  const basePhases = new Map((args.base?.phases ?? []).map((phase) => [phase.id, phase]));
+  const oursPhases = new Map(args.ours.phases.map((phase) => [phase.id, phase]));
+  const theirsPhases = new Map(args.theirs.phases.map((phase) => [phase.id, phase]));
+  const baseLocations = taskLocations(args.base);
+  const oursLocations = taskLocations(args.ours);
+  const theirsLocations = taskLocations(args.theirs);
+  const keptTasks = /* @__PURE__ */ new Map();
+  const targetPhaseByTask = /* @__PURE__ */ new Map();
+  const taskIds = /* @__PURE__ */ new Set([
+    ...baseLocations.keys(),
+    ...oursLocations.keys(),
+    ...theirsLocations.keys()
+  ]);
+  for (const taskId of taskIds) {
+    const baseLocation = baseLocations.get(taskId);
+    const oursLocation = oursLocations.get(taskId);
+    const theirsLocation = theirsLocations.get(taskId);
+    if (!shouldKeep(baseLocation, oursLocation, theirsLocation)) continue;
+    const task = oursLocation !== void 0 && theirsLocation !== void 0 ? mergeTask({
+      base: baseLocation?.task,
+      ours: oursLocation.task,
+      theirs: theirsLocation.task,
+      newer
+    }) : cloneSingleTask((oursLocation ?? theirsLocation).task);
+    keptTasks.set(taskId, task);
+    targetPhaseByTask.set(taskId, (oursLocation ?? theirsLocation).phaseId);
+  }
+  const keptPhaseIds = /* @__PURE__ */ new Set();
+  const allPhaseIds = /* @__PURE__ */ new Set([
+    ...basePhases.keys(),
+    ...oursPhases.keys(),
+    ...theirsPhases.keys()
+  ]);
+  for (const phaseId of allPhaseIds) {
+    if (shouldKeep(basePhases.get(phaseId), oursPhases.get(phaseId), theirsPhases.get(phaseId))) {
+      keptPhaseIds.add(phaseId);
+    }
+  }
+  const phaseOrder = [
+    ...args.ours.phases.map((phase) => phase.id).filter((id) => keptPhaseIds.has(id)),
+    ...args.theirs.phases.map((phase) => phase.id).filter((id) => keptPhaseIds.has(id) && !oursPhases.has(id))
+  ];
+  const phases = phaseOrder.map((phaseId) => {
+    const base = basePhases.get(phaseId);
+    const ours = oursPhases.get(phaseId);
+    const theirs = theirsPhases.get(phaseId);
+    const source = ours ?? theirs;
+    const title = ours !== void 0 && theirs !== void 0 ? chooseField({
+      baseExists: base !== void 0,
+      base: base?.title,
+      ours: ours.title,
+      theirs: theirs.title,
+      newer
+    }) : source.title;
+    const plan = ours !== void 0 && theirs !== void 0 ? chooseField({
+      baseExists: base !== void 0,
+      base: base?.plan,
+      ours: ours.plan,
+      theirs: theirs.plan,
+      newer
+    }) : source.plan;
+    const phaseTaskIds = new Set(
+      [...keptTasks.keys()].filter((taskId) => targetPhaseByTask.get(taskId) === phaseId)
+    );
+    const tasks = orderTasks({
+      phaseId,
+      taskIds: phaseTaskIds,
+      ours: args.ours,
+      theirs: args.theirs,
+      oursLocations
+    }).map((taskId) => keptTasks.get(taskId));
+    const phase = { id: phaseId, title, status: "todo", tasks };
+    if (plan !== void 0) phase.plan = plan;
+    phase.status = derivePhaseStatus(phase);
+    return phase;
+  });
+  const mergedTasks = new Map(
+    phases.flatMap((phase) => phase.tasks.map((task) => [task.id, task]))
+  );
+  const validCurrentTask = (roadmap) => {
+    const id = roadmap.currentTaskId ?? null;
+    return id != null && mergedTasks.get(id)?.status === "in-progress" ? id : null;
+  };
+  const merged = {
+    schemaVersion: 2,
+    project: { ...newerRoadmap.project },
+    updatedAt: newerRoadmap.updatedAt,
+    currentTaskId: validCurrentTask(newerRoadmap) ?? validCurrentTask(olderRoadmap),
+    summary: newerRoadmap.summary,
+    phases
+  };
+  const validation = validateRoadmap(merged);
+  if (validation.errors.length > 0) {
+    throw new CliError(
+      `Merged roadmap failed validation:
+  ${validation.errors.join("\n  ")}`,
+      1
+    );
+  }
+  return merged;
+}
+
+// src/commands/pull.ts
+async function readExisting(filePath) {
+  try {
+    return await readFile8(filePath, "utf8");
+  } catch (err) {
+    if (err != null && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+function register7(program, deps) {
+  program.command("pull [slug]").description(
+    "Pull server roadmaps, optionally merging them with valid local copies."
+  ).option("--merge", "Structurally merge server and local roadmap changes").action(async (requestedSlug, opts) => {
+    const { root, projectId } = await resolveRoadmapReadContext(deps);
+    const list = await deps.http.get(
+      `/api/projects/${projectId}/roadmaps`
+    );
+    const serverBySlug = new Map(list.roadmaps.map((roadmap) => [roadmap.slug, roadmap]));
+    if (requestedSlug != null && !serverBySlug.has(requestedSlug)) {
+      throw new CliError(`Roadmap "${requestedSlug}" was not found on the server.`, 2);
+    }
+    const targets = requestedSlug == null ? [...serverBySlug.values()] : [serverBySlug.get(requestedSlug)];
+    const roadmapsDir = path14.join(root, ".nolto", "roadmaps");
+    for (const summary of targets) {
+      const response = await deps.http.get(
+        `/api/projects/${projectId}/roadmaps/${encodeURIComponent(summary.slug)}`
+      );
+      const validation = validateRoadmap(response.roadmap);
+      if (validation.errors.length > 0) {
+        throw new CliError(
+          `Server roadmap "${summary.slug}" failed validation: ${validation.errors.join("; ")}`,
+          5
+        );
+      }
+      const filePath = path14.join(roadmapsDir, `${summary.slug}.json`);
+      const existing = await readExisting(filePath);
+      let roadmap = response.roadmap;
+      let outputVerb = "pulled";
+      if (opts.merge === true && existing !== null) {
+        let local;
+        try {
+          local = JSON.parse(existing);
+        } catch {
+          process.stderr.write(
+            `Warning: skipped ${summary.slug}.json because the local roadmap contains malformed JSON.
+`
+          );
+          continue;
+        }
+        const localValidation = validateRoadmap(local);
+        if (localValidation.errors.length > 0) {
+          process.stderr.write(
+            `Warning: skipped ${summary.slug}.json because the local roadmap is invalid: ${localValidation.errors.join("; ")}
+`
+          );
+          continue;
+        }
+        roadmap = mergeRoadmaps({
+          base: null,
+          ours: local,
+          theirs: response.roadmap
+        });
+        outputVerb = "merged";
+      }
+      const serialized = JSON.stringify(roadmap, null, 2) + "\n";
+      if (existing === serialized) {
+        process.stdout.write(`unchanged ${summary.slug}.json
+`);
+        continue;
+      }
+      await mkdir7(roadmapsDir, { recursive: true });
+      await writeFile7(filePath, serialized, "utf8");
+      process.stdout.write(
+        outputVerb === "merged" ? `merged ${summary.slug}.json
+` : `pulled ${summary.slug}.json (${summary.taskDone}/${summary.taskTotal} done)
+`
+      );
+    }
+    process.stdout.write("Review with git diff before committing.\n");
+  });
+}
+
 // src/commands/watch.ts
-import { copyFile as copyFile2, mkdir as mkdir7, readFile as readFile6, readdir as readdir3, rename as rename3, rmdir as rmdir2, unlink as unlink3 } from "fs/promises";
+import { copyFile as copyFile2, mkdir as mkdir8, readFile as readFile9, readdir as readdir4, rename as rename3, rmdir as rmdir2, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
-import path12 from "path";
+import path16 from "path";
 import chokidar from "chokidar";
 
 // src/watch-core.ts
@@ -1909,7 +2552,7 @@ var RepoWatch = class {
 };
 
 // src/service-install.ts
-import path11 from "path";
+import path15 from "path";
 import os4 from "os";
 function buildUnitFile(args) {
   return [
@@ -1929,8 +2572,8 @@ function buildUnitFile(args) {
 }
 function getUnitPath(env) {
   const xdg = env["XDG_CONFIG_HOME"];
-  const base = xdg != null && xdg.length > 0 ? xdg : path11.join(os4.homedir(), ".config");
-  return path11.join(base, "systemd", "user", "nolto-watch.service");
+  const base = xdg != null && xdg.length > 0 ? xdg : path15.join(os4.homedir(), ".config");
+  return path15.join(base, "systemd", "user", "nolto-watch.service");
 }
 async function installServiceWith(deps) {
   if (deps.platform !== "linux") {
@@ -1941,7 +2584,7 @@ async function installServiceWith(deps) {
     );
   }
   const unitPath = getUnitPath(deps.env);
-  await deps.mkdir(path11.dirname(unitPath));
+  await deps.mkdir(path15.dirname(unitPath));
   await deps.writeFile(unitPath, buildUnitFile({ nodePath: deps.nodePath, scriptPath: deps.scriptPath }));
   deps.log(`Wrote ${unitPath}`);
   const reload = await deps.exec(["systemctl", "--user", "daemon-reload"]);
@@ -1955,18 +2598,18 @@ async function installServiceWith(deps) {
   deps.log("Service nolto-watch enabled and started. Logs: journalctl --user -u nolto-watch -f");
 }
 async function installService() {
-  const { writeFile: writeFile7, mkdir: mkdir9 } = await import("fs/promises");
-  const { execFile: execFile3 } = await import("child_process");
-  const { promisify: promisify2 } = await import("util");
-  const execFileAsync = promisify2(execFile3);
+  const { writeFile: writeFile10, mkdir: mkdir10 } = await import("fs/promises");
+  const { execFile: execFile4 } = await import("child_process");
+  const { promisify: promisify3 } = await import("util");
+  const execFileAsync = promisify3(execFile4);
   await installServiceWith({
     platform: process.platform,
     env: process.env,
     nodePath: process.execPath,
-    scriptPath: path11.resolve(process.argv[1] ?? ""),
-    writeFile: (p, content) => writeFile7(p, content, "utf8"),
+    scriptPath: path15.resolve(process.argv[1] ?? ""),
+    writeFile: (p, content) => writeFile10(p, content, "utf8"),
     mkdir: async (p) => {
-      await mkdir9(p, { recursive: true });
+      await mkdir10(p, { recursive: true });
     },
     exec: async (cmd) => {
       try {
@@ -2021,9 +2664,9 @@ async function uninstallServiceWith(deps) {
 }
 async function uninstallService() {
   const { unlink: unlink4 } = await import("fs/promises");
-  const { execFile: execFile3 } = await import("child_process");
-  const { promisify: promisify2 } = await import("util");
-  const execFileAsync = promisify2(execFile3);
+  const { execFile: execFile4 } = await import("child_process");
+  const { promisify: promisify3 } = await import("util");
+  const execFileAsync = promisify3(execFile4);
   await uninstallServiceWith({
     platform: process.platform,
     env: process.env,
@@ -2043,7 +2686,7 @@ async function uninstallService() {
 }
 
 // src/commands/watch.ts
-function register6(program, deps) {
+function register8(program, deps) {
   program.command("watch").description("Watch every registered repository's roadmap + plan files and sync on change.").option("--debounce <ms>", "Debounce window in milliseconds", "2000").option("--install-service", "Install and enable a systemd user unit (nolto-watch) instead of watching").option("--uninstall-service", "Stop and remove the systemd user unit (nolto-watch) instead of watching").action(async (opts) => {
     if (opts.installService && opts.uninstallService) {
       throw new CliError("--install-service and --uninstall-service cannot be used together.", 2);
@@ -2080,10 +2723,10 @@ function register6(program, deps) {
       token: deps.settings.token
     });
     const startRepo = (root) => {
-      const roadmapsPath = path12.join(root, ".nolto", "roadmaps");
-      const legacyRoadmapPath = path12.join(root, ".roadmap", "roadmap.json");
+      const roadmapsPath = path16.join(root, ".nolto", "roadmaps");
+      const legacyRoadmapPath = path16.join(root, ".roadmap", "roadmap.json");
       const warn = (line) => {
-        process.stderr.write(`Warning: [${path12.basename(root)}] ${line}
+        process.stderr.write(`Warning: [${path16.basename(root)}] ${line}
 `);
       };
       const watcher = chokidar.watch([roadmapsPath, legacyRoadmapPath], { ignoreInitial: true });
@@ -2092,17 +2735,17 @@ function register6(program, deps) {
           // #316: watch must warn about legacy roadmaps without migrating them.
           { root, defaultProjectId: deps.settings.defaultProjectId, migrateLegacy: false },
           {
-            readFile: (p) => readFile6(p, "utf8"),
+            readFile: (p) => readFile9(p, "utf8"),
             fileExists: (p) => existsSync4(p),
-            listDir: (p) => readdir3(p),
+            listDir: (p) => readdir4(p),
             rename: rename3,
             copyFile: copyFile2,
-            mkdir: (p) => mkdir7(p, { recursive: true }).then(() => void 0),
+            mkdir: (p) => mkdir8(p, { recursive: true }).then(() => void 0),
             unlink: unlink3,
             rmdir: rmdir2,
             repoIdentity: makeRepoIdentityResolver(deps),
             http,
-            log: (line) => process.stdout.write(`[${path12.basename(root)}] ${line}
+            log: (line) => process.stdout.write(`[${path16.basename(root)}] ${line}
 `),
             warn
           }
@@ -2165,25 +2808,25 @@ function register6(program, deps) {
 }
 
 // src/update-cli.ts
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import { existsSync as existsSync5 } from "fs";
 import { realpath } from "fs/promises";
 import { createRequire as createRequire2 } from "module";
-import path14 from "path";
+import path18 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
-import { promisify } from "util";
+import { promisify as promisify2 } from "util";
 
 // src/update-notifier.ts
-import { readFile as readFile7, writeFile as writeFile6, mkdir as mkdir8 } from "fs/promises";
+import { readFile as readFile10, writeFile as writeFile8, mkdir as mkdir9 } from "fs/promises";
 import https from "https";
-import path13 from "path";
+import path17 from "path";
 var PACKAGE = "@nolto/cli";
 var CACHE_FILE = "update-check.json";
 var CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var REQUEST_TIMEOUT_MS = 2e3;
-function isNewerVersion(latest, current) {
+function isNewerVersion(latest2, current) {
   const parts = (v) => v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10) || 0);
-  const a = parts(latest);
+  const a = parts(latest2);
   const b = parts(current);
   for (let i = 0; i < 3; i++) {
     const x = a[i] ?? 0;
@@ -2192,9 +2835,9 @@ function isNewerVersion(latest, current) {
   }
   return false;
 }
-function formatUpdateNotice(latest, current) {
+function formatUpdateNotice(latest2, current) {
   return `
-Update available: ${current} \u2192 ${latest}  \xB7  run \`nolto update\`
+Update available: ${current} \u2192 ${latest2}  \xB7  run \`nolto update\`
 `;
 }
 function isDisabled(env) {
@@ -2233,22 +2876,22 @@ function fetchLatestFromRegistry(timeoutMs = REQUEST_TIMEOUT_MS, opts = {}) {
     req.on("error", () => resolve(null));
   });
 }
-async function writeUpdateCache(cachePath, now, latest) {
-  await mkdir8(path13.dirname(cachePath), { recursive: true });
-  const payload = { checkedAt: now, latest };
-  await writeFile6(cachePath, JSON.stringify(payload), { mode: 384 });
+async function writeUpdateCache(cachePath, now, latest2) {
+  await mkdir9(path17.dirname(cachePath), { recursive: true });
+  const payload = { checkedAt: now, latest: latest2 };
+  await writeFile8(cachePath, JSON.stringify(payload), { mode: 384 });
 }
 async function refreshCache(cachePath, now, fetchLatest) {
-  const latest = await fetchLatest();
-  if (!latest) return;
-  await writeUpdateCache(cachePath, now, latest).catch(() => void 0);
+  const latest2 = await fetchLatest();
+  if (!latest2) return;
+  await writeUpdateCache(cachePath, now, latest2).catch(() => void 0);
 }
 async function checkForUpdate(opts) {
   if (isDisabled(opts.env)) return null;
-  const cachePath = path13.join(opts.configDir, CACHE_FILE);
+  const cachePath = path17.join(opts.configDir, CACHE_FILE);
   let cache = {};
   try {
-    cache = JSON.parse(await readFile7(cachePath, "utf8"));
+    cache = JSON.parse(await readFile10(cachePath, "utf8"));
   } catch {
   }
   if (typeof cache.checkedAt !== "number" || opts.now - cache.checkedAt > CACHE_TTL_MS) {
@@ -2264,13 +2907,13 @@ async function checkForUpdate(opts) {
 async function notifyUpdate(opts) {
   try {
     if (opts.isJson || !process.stderr.isTTY) return;
-    const latest = await checkForUpdate({
+    const latest2 = await checkForUpdate({
       current: opts.current,
       configDir: getConfigDir(opts.env),
       env: opts.env,
       now: opts.now
     });
-    if (latest) process.stderr.write(formatUpdateNotice(latest, opts.current));
+    if (latest2) process.stderr.write(formatUpdateNotice(latest2, opts.current));
   } catch {
   }
 }
@@ -2321,14 +2964,14 @@ async function updateCliWith(deps) {
   if (!isInsideGlobalPackage(deps.scriptPath, globalRoot, deps.platform)) {
     throw notGlobalError(deps.scriptPath);
   }
-  const latest = await deps.fetchLatest();
-  if (latest == null) {
+  const latest2 = await deps.fetchLatest();
+  if (latest2 == null) {
     throw new CliError(
       "Could not reach the npm registry to check for the latest @nolto/cli version.",
       5
     );
   }
-  if (!isNewerVersion(latest, deps.currentVersion)) {
+  if (!isNewerVersion(latest2, deps.currentVersion)) {
     deps.log(`Already up to date (${PACKAGE2} ${deps.currentVersion}).`);
     return {
       status: "up-to-date",
@@ -2341,7 +2984,7 @@ async function updateCliWith(deps) {
     "npm",
     "install",
     "-g",
-    `${PACKAGE2}@${latest}`
+    `${PACKAGE2}@${latest2}`
   ]);
   if (installResult.code !== 0) {
     const detail = stderrTail(installResult.stderr);
@@ -2351,11 +2994,11 @@ async function updateCliWith(deps) {
       /EACCES|permission denied/i.test(installResult.stderr) ? "Permission denied \u2014 check your npm global prefix (npm config get prefix) or re-run with elevated permissions." : void 0
     );
   }
-  deps.log(`Updated ${PACKAGE2} ${deps.currentVersion} \u2192 ${latest}.`);
+  deps.log(`Updated ${PACKAGE2} ${deps.currentVersion} \u2192 ${latest2}.`);
   await deps.writeCache(
-    path14.join(deps.configDir, UPDATE_CACHE_FILE),
+    path18.join(deps.configDir, UPDATE_CACHE_FILE),
     deps.now,
-    latest
+    latest2
   ).catch(() => void 0);
   let watchService = "not-installed";
   const unitPath = getUnitPath(deps.env);
@@ -2379,22 +3022,22 @@ async function updateCliWith(deps) {
   return {
     status: "updated",
     from: deps.currentVersion,
-    to: latest,
+    to: latest2,
     watchService
   };
 }
 function getCurrentVersion() {
-  const dirname = path14.dirname(fileURLToPath3(import.meta.url));
+  const dirname = path18.dirname(fileURLToPath3(import.meta.url));
   const require3 = createRequire2(import.meta.url);
   try {
-    const pkg = require3(path14.resolve(dirname, "../package.json"));
+    const pkg = require3(path18.resolve(dirname, "../package.json"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
   }
 }
 async function updateCli(opts = {}) {
-  const execFileAsync = promisify(execFile2);
+  const execFileAsync = promisify2(execFile3);
   const scriptPath = await realpath(process.argv[1] ?? "");
   return updateCliWith({
     currentVersion: getCurrentVersion(),
@@ -2426,7 +3069,7 @@ async function updateCli(opts = {}) {
 }
 
 // src/commands/update.ts
-function register7(program, deps) {
+function register9(program, deps) {
   program.command("update").description("Update @nolto/cli to the latest version and restart the watch service if installed").action(async () => {
     const mode2 = deps.output.mode;
     const result = await updateCli({ quiet: mode2 === "json" });
@@ -2436,6 +3079,46 @@ function register7(program, deps) {
   });
 }
 
+// src/commands/merge-file.ts
+import { readFile as readFile11, writeFile as writeFile9 } from "fs/promises";
+async function readRoadmap(filePath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile11(filePath, "utf8"));
+  } catch (err) {
+    const message = err instanceof SyntaxError ? "malformed JSON" : String(err);
+    throw new CliError(`${filePath}: ${message}`, 1);
+  }
+  const validation = validateRoadmap(parsed);
+  if (validation.errors.length > 0) {
+    throw new CliError(
+      `${filePath} failed validation:
+  ${validation.errors.join("\n  ")}`,
+      1
+    );
+  }
+  return parsed;
+}
+function register10(program) {
+  program.command("merge-file <ours> <theirs>").description(
+    'Structurally merge roadmap files for Git.\ngit config merge.nolto-roadmap.driver "nolto merge-file %A %B --base %O"'
+  ).option("--base <path>", "Common ancestor roadmap file").option("--output <path>", "Write the result here (defaults to <ours>)").action(async (oursPath, theirsPath, opts) => {
+    const ours = await readRoadmap(oursPath);
+    const theirs = await readRoadmap(theirsPath);
+    const base = opts.base == null ? null : await readRoadmap(opts.base);
+    const merged = mergeRoadmaps({ base, ours, theirs });
+    await writeFile9(
+      opts.output ?? oursPath,
+      JSON.stringify(merged, null, 2) + "\n",
+      "utf8"
+    );
+    const taskCount = merged.phases.reduce((total, phase) => total + phase.tasks.length, 0);
+    process.stderr.write(`merged roadmap (${taskCount} tasks)
+`);
+    process.exitCode = 0;
+  });
+}
+
 // src/program.ts
 function stripCommanderErrorPrefix(msg) {
   return msg.startsWith("error: ") ? msg.slice("error: ".length) : msg;
@@ -2451,9 +3134,12 @@ function buildProgram(deps) {
   register5(program, deps);
   register6(program, deps);
   register7(program, deps);
+  register8(program, deps);
+  register9(program, deps);
+  register10(program);
   program.hook("preAction", (_thisCommand, actionCommand) => {
     const bindingError = deps.repoBinding?.error;
-    const bindingExemptCommands = ["init", "link", "update"];
+    const bindingExemptCommands = ["init", "link", "update", "merge-file"];
     if (bindingError != null && !bindingExemptCommands.includes(actionCommand.name())) {
       throw bindingError;
     }
@@ -2462,11 +3148,11 @@ function buildProgram(deps) {
 }
 
 // src/index.ts
-var __dirname3 = path15.dirname(fileURLToPath4(import.meta.url));
+var __dirname3 = path19.dirname(fileURLToPath4(import.meta.url));
 var require2 = createRequire3(import.meta.url);
 function getVersion() {
   try {
-    const pkgPath = path15.resolve(__dirname3, "../package.json");
+    const pkgPath = path19.resolve(__dirname3, "../package.json");
     const pkg = require2(pkgPath);
     return pkg.version ?? "0.0.0";
   } catch {