@systemdox/mcp-server 0.1.57 → 0.1.58

package/dist/index.js

@@ -1311,8 +1311,8 @@ function registerGetPlanBoard(server, apiClient2) {
             ]
           };
         }
-        const open = boards.filter((b) => !b.closed);
-        if (open.length === 0) {
+        const open2 = boards.filter((b) => !b.closed);
+        if (open2.length === 0) {
           return {
             content: [
               {
@@ -1322,16 +1322,16 @@ function registerGetPlanBoard(server, apiClient2) {
             ]
           };
         }
-        const closedNote = boards.length > open.length ? `
+        const closedNote = boards.length > open2.length ? `
 
-_${boards.length - open.length} closed board(s) not listed._` : "";
+_${boards.length - open2.length} closed board(s) not listed._` : "";
         return {
           content: [
             {
               type: "text",
-              text: `${open.length} open project board(s):
+              text: `${open2.length} open project board(s):
 
-${formatBoards(open)}` + closedNote + `
+${formatBoards(open2)}` + closedNote + `
 
 Call get_plan_board with project_number to list a board's issues.`
             }
@@ -3094,7 +3094,7 @@ var PERSON_ID_RE = new RegExp(`^${PERSON_ID}$`);
 
 // src/sync-memory.ts
 import { existsSync as existsSync3 } from "fs";
-import { mkdir as mkdir3, readdir as readdir2, readFile as readFile4, rm as rm3, writeFile as writeFile3 } from "fs/promises";
+import { appendFile, mkdir as mkdir3, open, readdir as readdir2, readFile as readFile4, rename as rename2, rm as rm3, stat, writeFile as writeFile3 } from "fs/promises";
 import { dirname as dirname3, join as join4, resolve as resolve3 } from "path";
 
 // src/lib/memory-sync.ts
@@ -3118,15 +3118,41 @@ function readFrontmatter(text3) {
   const m = BLOCK_RE.exec(text3);
   if (!m) return void 0;
   const front = { shareFalse: false };
-  for (const line of m[1].split(/\r?\n/)) {
-    const kv = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
+  const lines = m[1].split(/\r?\n/);
+  if (lines.some((l) => /^[ \t]*\t/.test(l) && l.trim())) return front;
+  let topType;
+  let topShare;
+  let nestedType;
+  let nestedShare;
+  let inMetadata = false;
+  let nestedIndent;
+  for (const line of lines) {
+    if (!line.trim() || /^[ \t]*#/.test(line)) continue;
+    const indent = /^ */.exec(line)[0].length;
+    if (indent === 0) {
+      inMetadata = /^metadata[ \t]*:[ \t]*(#.*)?$/.test(line);
+      nestedIndent = void 0;
+    }
+    const kv = /^ *([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
     if (!kv) continue;
     const raw = kv[2].replace(/[ \t]+#.*$/, "");
     const quoted = /^(["'])(.*)\1$/.exec(raw);
     const value = quoted ? quoted[2] : raw;
-    if (kv[1] === "type") front.type = value.trim().toLowerCase();
-    if (kv[1] === "share") front.shareFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
-  }
+    const isFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
+    if (indent === 0) {
+      if (kv[1] === "type") topType = value.trim().toLowerCase();
+      if (kv[1] === "share") topShare = isFalse;
+      continue;
+    }
+    if (!inMetadata) continue;
+    nestedIndent ??= indent;
+    if (indent !== nestedIndent) continue;
+    if (kv[1] === "type") nestedType = value.trim().toLowerCase();
+    if (kv[1] === "share") nestedShare = isFalse;
+  }
+  const type = topType ?? nestedType;
+  if (type !== void 0) front.type = type;
+  front.shareFalse = (topShare ?? nestedShare) === true;
   return front;
 }
 function isShareable(path, text3) {
@@ -3367,18 +3393,50 @@ function lineDiff(before, after) {
 }
 
 // src/sync-memory.ts
+var HOOK_LOG_MAX_BYTES = 1024 * 1024;
 var SYNC_MEMORY_COMMAND = "npx -y @systemdox/mcp-server sync-memory";
 var SyncFailed = class extends Error {
 };
+var SyncStopped = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+  }
+  reason;
+};
+function failureReason(e) {
+  if (e instanceof SyncStopped) return e.reason;
+  const { status, code } = refusal(e);
+  if (status !== void 0) return code ? `SystemDox refused it, ${code}` : "SystemDox refused it";
+  const err = e;
+  const net = err?.cause?.code ?? err?.code ?? "";
+  if (e instanceof TypeError || /^(ECONN|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|UND_ERR)/.test(net)) {
+    return "SystemDox could not be reached";
+  }
+  return "it could not finish";
+}
+async function writeWhole(path, text3) {
+  await mkdir3(dirname3(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile3(tmp, text3, "utf8");
+    await rename2(tmp, path);
+  } catch (e) {
+    await rm3(tmp, { force: true });
+    throw e;
+  }
+}
 function refusal(e) {
   if (!(e instanceof Error)) return {};
   const { status, code } = e;
   return { status: typeof status === "number" ? status : void 0, code: typeof code === "string" ? code : void 0 };
 }
 var toPath = (root, rel) => join4(root, ...rel.split("/"));
+var LEFT_TEMP_RE = /\.\d+\.[a-z0-9]+\.tmp$/;
 async function readFolder(root) {
   const files = {};
   const names = /* @__PURE__ */ new Set();
+  const temps = [];
   async function walk2(dir, prefix) {
     for (const e of await readdir2(dir, { withFileTypes: true })) {
       if (e.name.startsWith(".")) continue;
@@ -3386,12 +3444,13 @@ async function readFolder(root) {
       if (e.isDirectory()) await walk2(join4(dir, e.name), rel);
       else if (e.isFile()) {
         names.add(rel.toLowerCase());
+        if (LEFT_TEMP_RE.test(e.name)) temps.push(rel);
         if (e.name.endsWith(".md")) files[rel] = await readFile4(join4(dir, e.name), "utf8");
       }
     }
   }
   if (existsSync3(root)) await walk2(root, "");
-  return { files, names };
+  return { files, names, temps };
 }
 async function pullTeam(client, ws, project) {
   try {
@@ -3440,7 +3499,11 @@ var Report = class {
   deletedHere = /* @__PURE__ */ new Set();
   deletedFromTeam = /* @__PURE__ */ new Set();
   conflicts = [];
+  /** The conflict copies written this run, by name. */
+  copies = /* @__PURE__ */ new Set();
   skipped = /* @__PURE__ */ new Map();
+  /** Skipped files a sync in the member's terminal can send: held for a value, or for the vault. */
+  waiting = /* @__PURE__ */ new Set();
   people = [];
   toAnswer = /* @__PURE__ */ new Map();
   add(plan) {
@@ -3448,12 +3511,32 @@ var Report = class {
     plan.pushed.forEach((p) => this.pushed.add(p));
     plan.deletedHere.forEach((p) => this.deletedHere.add(p));
     plan.deletedFromTeam.forEach((p) => this.deletedFromTeam.add(p));
-    for (const c of plan.conflicts) this.conflicts.push(`${c.path}: the team's text; yours is beside it as ${c.copy}`);
+    for (const c of plan.conflicts) {
+      this.conflicts.push(`${c.path}: the team's text; yours is beside it as ${c.copy}`);
+      this.copies.add(c.copy);
+    }
     for (const line of plan.indexTeamLines) this.conflicts.push(`${INDEX_FILE}: your line was kept; the team's was: ${line}`);
   }
   skip(path, reason) {
     if (!this.skipped.has(path)) this.skipped.set(path, reason);
   }
+  /** Skipped, and waiting for the member at a terminal. */
+  wait(path, reason) {
+    this.skip(path, reason);
+    this.waiting.add(path);
+  }
+  summary(outcome, version, reason) {
+    return {
+      outcome,
+      ...reason ? { reason } : {},
+      version,
+      pulled: this.pulled.size,
+      pushed: this.pushed.size,
+      deleted: this.deletedHere.size + this.deletedFromTeam.size,
+      conflictCopies: [...this.copies].sort(),
+      waiting: [...this.waiting].sort()
+    };
+  }
   lines(summary, dryRun) {
     const out = [summary];
     const section = (title, items) => {
@@ -3556,7 +3639,7 @@ async function people(opts, ws, files, report, hint) {
           for (const path of g.files) {
             if (leftOut.has(path)) continue;
             current[path] = addShareFalse(current[path]);
-            await writeFile3(toPath(opts.dir, path), current[path], "utf8");
+            await writeWhole(toPath(opts.dir, path), current[path]);
             leftOut.add(path);
           }
           report.people.push({ kind: g.kind, answer: "left out (share: false)", files: g.files.length });
@@ -3659,7 +3742,7 @@ async function people(opts, ws, files, report, hint) {
     const yes = /^y(es)?$/i.test((await ask(`Rewrite ${paths.length} file${paths.length === 1 ? "" : "s"} as shown? [y/N] `)).trim());
     if (yes) {
       for (const path of paths) {
-        await writeFile3(toPath(opts.dir, path), rewritten[path], "utf8");
+        await writeWhole(toPath(opts.dir, path), rewritten[path]);
         current[path] = rewritten[path];
       }
     }
@@ -3674,11 +3757,11 @@ async function people(opts, ws, files, report, hint) {
     held.add(path);
     const keys = pending.filter((f) => f.kind !== HOME_PATH).map((f) => groupKey(f.kind, f.normalised));
     if (keys.some((k) => vaultDown.has(k))) {
-      report.skip(path, "the vault did not answer (SYD-K019) for a value in it; it syncs once the value is filed");
+      report.wait(path, "the vault did not answer (SYD-K019) for a value in it; it syncs once the value is filed");
     } else if (keys.some((k) => !answers.has(k))) {
-      report.skip(path, `it holds a value nobody has answered for: run \`${hint}\` in a terminal`);
+      report.wait(path, `it holds a value nobody has answered for: run \`${hint}\` in a terminal`);
     } else {
-      report.skip(path, `it holds a value to rewrite as its identifier or ~: run \`${hint}\` in a terminal`);
+      report.wait(path, `it holds a value to rewrite as its identifier or ~: run \`${hint}\` in a terminal`);
     }
   }
   for (const g of groups) {
@@ -3689,12 +3772,11 @@ async function people(opts, ws, files, report, hint) {
   }
   return { files: current, held, leftOut };
 }
+async function removeLeftTemps(dir, temps) {
+  for (const rel of temps) await rm3(toPath(dir, rel), { force: true });
+}
 async function applyPlan(dir, plan) {
-  for (const [path, text3] of Object.entries(plan.writes)) {
-    const full = toPath(dir, path);
-    await mkdir3(dirname3(full), { recursive: true });
-    await writeFile3(full, text3, "utf8");
-  }
+  for (const [path, text3] of Object.entries(plan.writes)) await writeWhole(toPath(dir, path), text3);
   for (const path of plan.deletes) await rm3(toPath(dir, path), { force: true });
 }
 var sameManifest = (a, b) => Object.keys(a).length === Object.keys(b).length && Object.entries(a).every(([p, h]) => b[p] === h);
@@ -3739,8 +3821,19 @@ async function syncMemory(opts) {
   const { client, out } = opts;
   const now = opts.now?.() ?? /* @__PURE__ */ new Date();
   try {
+    const checkDeadline = () => {
+      if (opts.deadline !== void 0 && Date.now() > opts.deadline) {
+        throw new SyncStopped("took too long", "Stopped: the sync's time ran out before anything more was written or sent.");
+      }
+    };
     const own = await client.getOwnTeamSetup();
     const ws = own.workspace;
+    if (opts.workspace && ws !== opts.workspace) {
+      throw new SyncStopped(
+        "the key is for another workspace",
+        `The key is for ${ws}, not ${opts.workspace}: nothing was synced. Set SYSTEMDOX_API_KEY to a key of ${opts.workspace}, or unset it.`
+      );
+    }
     const project = opts.project ?? (own.memory.length === 1 ? own.memory[0].project : void 0);
     if (!project) {
       throw new SyncFailed(
@@ -3754,6 +3847,12 @@ async function syncMemory(opts) {
     const date = localDate(now);
     const stored = (await readState(ws)).memory?.[project];
     let team = await pullTeam(client, ws, project);
+    if (opts.unattended && stored && !team.exists) {
+      throw new SyncStopped(
+        "the team memory could not be read",
+        `${ws}/${project} could not be read from SystemDox: nothing was changed. Run sync-memory in your terminal to see why.`
+      );
+    }
     let base = stored ? { version: stored.version, manifest: stored.manifest, exists: true } : { version: 0, manifest: {}, exists: false };
     const folder = await readFolder(dir);
     const shared = {};
@@ -3766,14 +3865,16 @@ async function syncMemory(opts) {
       } else shared[path] = text3;
     }
     const importWrites = {};
-    if (opts.importDir) {
-      const other = await readFolder(resolve3(opts.importDir));
-      const taken = new Set(folder.names);
+    const current = { ...folder.files };
+    const taken = new Set(folder.names);
+    for (const importDir of opts.importDirs ?? []) {
+      const other = await readFolder(resolve3(importDir));
       for (const [path, text3] of Object.entries(other.files).sort(([a], [b]) => a.localeCompare(b))) {
         if (!isShareable(path, text3) || !isFilePath(path)) continue;
-        const here = folder.files[path];
+        const here = current[path];
         if (here === void 0) {
           shared[path] = text3;
+          current[path] = text3;
           importWrites[path] = text3;
           taken.add(path.toLowerCase());
         } else if (here !== text3) {
@@ -3781,16 +3882,14 @@ async function syncMemory(opts) {
           taken.add(copy.toLowerCase());
           importWrites[copy] = text3;
           report.conflicts.push(`${path}: this folder's text; the imported one is beside it as ${copy}`);
+          report.copies.add(copy);
         }
       }
-      folder.names = taken;
-      if (!opts.dryRun) {
-        for (const [path, text3] of Object.entries(importWrites)) {
-          const full = toPath(dir, path);
-          await mkdir3(dirname3(full), { recursive: true });
-          await writeFile3(full, text3, "utf8");
-        }
-      }
+    }
+    folder.names = taken;
+    if (!opts.dryRun) {
+      checkDeadline();
+      for (const [path, text3] of Object.entries(importWrites)) await writeWhole(toPath(dir, path), text3);
     }
     const found = await people(run2, ws, shared, report, hint);
     for (const path of found.leftOut) {
@@ -3815,12 +3914,16 @@ async function syncMemory(opts) {
         );
         return 0;
       }
+      checkDeadline();
+      if (attempt === 1) await removeLeftTemps(dir, folder.temps);
       await applyPlan(dir, plan);
       let version = team.version;
       if (!sameManifest(plan.manifest, team.manifest)) {
+        checkDeadline();
         await upload(client, ws, project, plan, team.manifest, report);
       }
       if (!sameManifest(plan.manifest, team.manifest)) {
+        checkDeadline();
         try {
           version = (await client.pushMemoryVersion(ws, project, { baseVersion: team.version, manifest: plan.manifest })).version;
         } catch (e) {
@@ -3832,6 +3935,7 @@ async function syncMemory(opts) {
                 false
               )
             );
+            opts.summary?.(report.summary("moved-on", team.version, "moved on twice"));
             return 2;
           }
           base = team;
@@ -3856,10 +3960,21 @@ async function syncMemory(opts) {
           false
         )
       );
+      opts.summary?.(report.summary("synced", version));
       return 0;
     }
   } catch (e) {
     out(e.message);
+    opts.summary?.({
+      outcome: "failed",
+      reason: failureReason(e),
+      version: 0,
+      pulled: 0,
+      pushed: 0,
+      deleted: 0,
+      conflictCopies: [],
+      waiting: []
+    });
     return 1;
   }
 }
@@ -4031,7 +4146,9 @@ function registerTeamSetupTools(server, apiClient2, { localFiles }) {
         project: args.project,
         dryRun: !!args.dryRun,
         client: apiClient2,
-        out: (...l) => lines.push(...l)
+        out: (...l) => lines.push(...l),
+        // Nobody is at a terminal: a project the team no longer serves is left as it is.
+        unattended: true
       });
       return { ...text2(lines.join("\n")), ...code ? { isError: true } : {} };
     }
@@ -4039,7 +4156,7 @@ function registerTeamSetupTools(server, apiClient2, { localFiles }) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.57" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.58" : "0.0.0-dev";
 var READ_TOOLS = [
   "get_context",
   "get_checks",

package/dist/lib/memory-sync.d.ts

@@ -4,8 +4,9 @@
  * `src/sync-memory.ts` reads the folders and calls the API around it.
  *
  * - **What is shared** (`isShareable`): a `*.md` file whose frontmatter `type`
- *   is `feedback`, `project` or `reference`, and `MEMORY.md`; never a file
- *   with `share: false` or a `<name>.local-<date>.md` conflict copy.
+ *   (at the top level or under `metadata:`, Amendment 3) is `feedback`,
+ *   `project` or `reference`, and `MEMORY.md`; never a file with
+ *   `share: false` or a `<name>.local-<date>.md` conflict copy.
  * - **The merge** (`decide`, `planMerge`): three-way per path, with the base
  *   (the manifest of the last sync), the team's latest version and the local
  *   folder, row by row as the contract's table says.
@@ -29,7 +30,13 @@ export interface Frontmatter {
     shareFalse: boolean;
 }
 /** The frontmatter's `type` and `share`, or undefined when the file has no
- * leading block. Only top-level `key: value` lines are read. */
+ * leading block. They are read at the top level, or one level under
+ * `metadata:`, the form Claude Code writes (`metadata:` on one line,
+ * `  type: project` under it); a top-level key wins over the nested one
+ * (ADR-217 Amendment 3). Read as the server's YAML reads them:
+ * - a block with a tab in a line's indentation is not YAML, so the server sees
+ *   no front matter: nothing is read here either (no type, so not shared);
+ * - only keys at the first indent under `metadata:` count, never deeper ones. */
 export declare function readFrontmatter(text: string): Frontmatter | undefined;
 /**
  * Shared with the team: `MEMORY.md` at the folder's root, or a `*.md` file

package/dist/lib/memory-sync.js

@@ -93,15 +93,41 @@ function readFrontmatter(text) {
   const m = BLOCK_RE.exec(text);
   if (!m) return void 0;
   const front = { shareFalse: false };
-  for (const line of m[1].split(/\r?\n/)) {
-    const kv = /^([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
+  const lines = m[1].split(/\r?\n/);
+  if (lines.some((l) => /^[ \t]*\t/.test(l) && l.trim())) return front;
+  let topType;
+  let topShare;
+  let nestedType;
+  let nestedShare;
+  let inMetadata = false;
+  let nestedIndent;
+  for (const line of lines) {
+    if (!line.trim() || /^[ \t]*#/.test(line)) continue;
+    const indent = /^ */.exec(line)[0].length;
+    if (indent === 0) {
+      inMetadata = /^metadata[ \t]*:[ \t]*(#.*)?$/.test(line);
+      nestedIndent = void 0;
+    }
+    const kv = /^ *([A-Za-z_][\w-]*)[ \t]*:[ \t]*(.*?)[ \t]*$/.exec(line);
     if (!kv) continue;
     const raw = kv[2].replace(/[ \t]+#.*$/, "");
     const quoted = /^(["'])(.*)\1$/.exec(raw);
     const value = quoted ? quoted[2] : raw;
-    if (kv[1] === "type") front.type = value.trim().toLowerCase();
-    if (kv[1] === "share") front.shareFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
+    const isFalse = quoted ? value.trim().toLowerCase() === "false" : YAML_FALSE.has(value);
+    if (indent === 0) {
+      if (kv[1] === "type") topType = value.trim().toLowerCase();
+      if (kv[1] === "share") topShare = isFalse;
+      continue;
+    }
+    if (!inMetadata) continue;
+    nestedIndent ??= indent;
+    if (indent !== nestedIndent) continue;
+    if (kv[1] === "type") nestedType = value.trim().toLowerCase();
+    if (kv[1] === "share") nestedShare = isFalse;
   }
+  const type = topType ?? nestedType;
+  if (type !== void 0) front.type = type;
+  front.shareFalse = (topShare ?? nestedShare) === true;
   return front;
 }
 function isShareable(path, text) {

package/dist/lib/team-setup-files.d.ts

@@ -8,7 +8,9 @@
  * - `~/.claude/systemdox/<workspace>/state.json`: the installed versions and
  *   hashes, each memory project's base manifest and version, the accepted
  *   SHA-256s. Never a value and never an answer about a person;
- * - `~/.claude/systemdox/<workspace>/plugin/<n>/`: plugin version n, unpacked.
+ * - `~/.claude/systemdox/<workspace>/plugin/<n>/`: plugin version n, unpacked;
+ * - `~/.claude/systemdox/<workspace>/sync-memory.log` and `sync.lock`: the hook
+ *   run's full report and its lock (ADR-217 Amendment 3).
  *
  * Every path starts at `homeDir()`, the one place the home folder is read, so
  * a test points HOME (USERPROFILE on Windows) at a temporary folder.
@@ -29,6 +31,11 @@ export declare function systemdoxDir(): string;
 export declare function credentialsPath(): string;
 export declare function workspaceDir(workspace: string): string;
 export declare function statePath(workspace: string): string;
+/** `~/.claude/systemdox/<workspace>/sync-memory.log`: the full report of every
+ * `sync-memory --hook` run, newest last (ADR-217 Amendment 3). */
+export declare function syncLogPath(workspace: string): string;
+/** `~/.claude/systemdox/<workspace>/sync.lock`: held while a hook run syncs. */
+export declare function syncLockPath(workspace: string): string;
 export declare function pluginRoot(workspace: string): string;
 export declare function pluginDir(workspace: string, version: number): string;
 export type Credentials = Record<string, {

package/dist/lib/team-setup-files.js

@@ -63,6 +63,12 @@ function workspaceDir(workspace) {
 function statePath(workspace) {
   return join(workspaceDir(workspace), "state.json");
 }
+function syncLogPath(workspace) {
+  return join(workspaceDir(workspace), "sync-memory.log");
+}
+function syncLockPath(workspace) {
+  return join(workspaceDir(workspace), "sync.lock");
+}
 function pluginRoot(workspace) {
   return join(workspaceDir(workspace), "plugin");
 }
@@ -226,6 +232,8 @@ export {
   restrictToMember,
   runMarketplaceAuth,
   statePath,
+  syncLockPath,
+  syncLogPath,
   systemdoxDir,
   updateState,
   workspaceDir,

package/dist/lib/team-setup-types.d.ts

@@ -56,6 +56,8 @@ export interface PluginVersion {
         args?: string[];
         url?: string;
     }[];
+    /** This version carries SystemDox's memory sync hooks (ADR-217 Amendment 3); absent before it. */
+    memoryHooks?: boolean;
     command: string;
 }
 export interface Marketplace {