@nolto/cli 0.8.1 → 0.9.0

package/README.md

@@ -63,6 +63,9 @@ CLI versions older than 0.8.0 do not send a repository identity and receive
 
 ```bash
 nolto sync                         # Push roadmap JSON files and linked plan Markdown
+nolto diff [slug]                  # Compare local and server roadmaps without changing them
+nolto pull [slug]                  # Overwrite local roadmap files from the server
+nolto pull --merge [slug]          # Structurally merge server and local roadmaps
 nolto watch [--debounce <ms>]      # Watch registered repositories and auto-sync
 nolto watch --install-service      # Install the Linux systemd user service
 ```
@@ -78,6 +81,35 @@ repositories are skipped with a warning.
 The CLI warns when an installed `roadmap-progress` skill version differs from the
 CLI version; run `nolto init` in that repository to refresh it.
 
+Use `nolto diff [slug]` before pushing to review structural task, phase, and
+metadata differences. It exits with code 1 when differences are found and does
+not change either side. `nolto pull [slug]` downloads all server roadmaps, or one
+named roadmap, and intentionally overwrites the corresponding local files after
+validation. It never deletes local-only roadmaps. Add `--merge` to preserve valid
+local changes using a deterministic structural merge, and review the result with
+`git diff` before committing.
+
+## Merging roadmap conflicts
+
+Roadmap files use Nolto's structural Git merge driver. The repository attribute
+and local Git configuration are:
+
+```text
+.nolto/roadmaps/*.json merge=nolto-roadmap
+git config --local merge.nolto-roadmap.driver "nolto merge-file %A %B --base %O"
+```
+
+`nolto init` sets up both entries for the current repository and is safe to run
+again for an existing repository. Git invokes the underlying command as:
+
+```bash
+nolto merge-file <ours> <theirs> --base <ancestor>
+```
+
+The result is written to `<ours>` as required by Git. Use
+`nolto pull --merge [slug]` when the server has changes that should be combined
+with a valid local roadmap before syncing.
+
 ## Configuration
 
 The config file is `~/.config/nolto/config.json` (or
@@ -139,7 +171,7 @@ Errors are written to stderr:
 | Code | Meaning |
 |---|---|
 | 0 | Success |
-| 1 | Unexpected command failure |
+| 1 | Roadmap differences found (`nolto diff`) or unexpected command failure |
 | 2 | Local input or file validation error |
 | 3 | Authentication or authorization error |
 | 4 | Rate limit response |

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
@@ -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}`
@@ -378,7 +378,7 @@ import readline 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
@@ -519,12 +519,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
@@ -836,10 +836,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 +854,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);
@@ -1103,14 +1103,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) {
@@ -1251,13 +1292,13 @@ 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;
+      let repoProject = existingBinding != null ? { id: existingBinding.projectId, name: path9.basename(root) } : defaultProjectId != null ? { id: defaultProjectId, name: defaultProjectName ?? path9.basename(root) } : void 0;
       if (repoProject == null) {
         http ??= createHttpClient({ baseUrl, token, version: getCliVersion() });
         if (projects == null) {
@@ -1281,7 +1322,7 @@ 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");
+      const bindingPath = deps.repoBinding?.path ?? path9.join(root, "nolto.json");
       if (existingBinding != null) {
         process.stdout.write(`binding:        kept ${bindingPath} (${existingBinding.projectId})
 `);
@@ -1293,22 +1334,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 +1371,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();
     }
@@ -1549,15 +1597,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 +1626,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 +1652,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 +1699,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 +1708,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 +1717,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 +1739,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 +1763,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 +1804,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 +1848,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 +2478,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 +2498,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 +2510,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 +2524,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 +2590,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 +2612,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 +2649,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 +2661,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 +2734,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 +2761,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 +2802,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 +2833,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 +2890,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 +2910,7 @@ async function updateCliWith(deps) {
     "npm",
     "install",
     "-g",
-    `${PACKAGE2}@${latest}`
+    `${PACKAGE2}@${latest2}`
   ]);
   if (installResult.code !== 0) {
     const detail = stderrTail(installResult.stderr);
@@ -2351,11 +2920,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 +2948,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 +2995,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 +3005,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 +3060,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 +3074,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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolto/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "CLI for syncing repository roadmaps with Nolto.",
   "license": "MIT",
   "type": "module",