@attentionform/astra-mcp-server 0.4.0 → 0.4.2

package/dist/index.js

@@ -6082,6 +6082,9 @@ var RSIDS_EMPTY_RE = /<w:rsids>\s*<\/w:rsids>/g;
 var RSIDS_SELF_CLOSING_RE = /<w:rsids\s*\/>/g;
 var AUTHOR_ATTR_RE = /\s+(w|w15):author="[^"]*"/g;
 var INITIALS_ATTR_RE = /\s+w:initials="[^"]*"/g;
+var PRESENCE_INFO_TAG_RE = /<w15:presenceInfo\b(?:[^>"']|"[^"]*"|'[^']*')*>/g;
+var PRESENCE_PROVIDER_NONE_RE = /\sw15:providerId=(["'])None\1/;
+var PRESENCE_USERID_RE = /(\sw15:userId=)(?:"[^"]*"|'[^']*')/;
 var EMAIL_RE = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
 var PHONE_RE = /(\+\d[\d\s\-().]{6,}\d|\(\d{3}\)\s*\d{3}[\s\-.]\d{4}|\b\d{3}[\s\-.]\d{3}[\s\-.]\d{4}\b)/g;
 var CLAUSE_ACRONYM_RE = /\b(dfars|far|cfr|nist)\b/gi;
@@ -6853,6 +6856,15 @@ function sanitizeDocumentXml(xml, opts, partName = "word XML part", hooks) {
       o.replacementAuthor.split(/[\s._-]+/).filter(Boolean).map((s) => s[0]).join("").slice(0, 4).toUpperCase() || "A"
     );
     out = out.replace(INITIALS_ATTR_RE, ` w:initials="${initials}"`);
+    if (partName === "word/people.xml") {
+      out = out.replace(PRESENCE_INFO_TAG_RE, (tag) => {
+        if (!PRESENCE_PROVIDER_NONE_RE.test(tag)) return tag;
+        return tag.replace(PRESENCE_USERID_RE, (_m, open) => {
+          purgedAuthors += 1;
+          return `${open}"${replacement === "" ? "Anonymous" : replacement}"`;
+        });
+      });
+    }
   }
   let acceptedRevisions = 0;
   let unresolvedRevisions = [];
@@ -10480,9 +10492,10 @@ var DocxParser = class _DocxParser {
   /**
    * Restores the package to a previously captured snapshot: every entry is
    * restored (entries added after the snapshot are removed), then documentDom
-   * and stylesDom are reloaded and stable IDs re-assigned.
+   * and stylesDom are reloaded and stable IDs re-assigned. The restored package is exactly the snapshot;
+   * only a restore that mixes a pre-0.4.2 commit with live parts passes `registerCoreProperties`.
    */
-  restorePackageSnapshot(snapshot3) {
+  restorePackageSnapshot(snapshot3, options) {
     for (const entry of [...this.zip.getEntries()]) {
       if (!snapshot3.has(entry.entryName)) {
         this.zip.deleteFile(entry);
@@ -10501,8 +10514,15 @@ var DocxParser = class _DocxParser {
         continue;
       }
       const buffer = Buffer.from(data);
-      if (this.zip.getEntry(entryName)) {
-        this.zip.updateFile(entryName, buffer);
+      const liveEntry = this.zip.getEntry(entryName);
+      if (liveEntry) {
+        let unchanged = false;
+        try {
+          unchanged = !liveEntry.isDirectory && liveEntry.header.size === buffer.length && readPartData(liveEntry, entryName).equals(buffer);
+        } catch {
+          unchanged = false;
+        }
+        if (!unchanged) this.zip.updateFile(entryName, buffer);
       } else {
         this.zip.addFile(entryName, buffer);
       }
@@ -10527,7 +10547,7 @@ var DocxParser = class _DocxParser {
     } else {
       this.stylesDom = null;
     }
-    registerExistingCorePropertiesPart(this.getZipAdapter());
+    if (options?.registerCoreProperties) registerExistingCorePropertiesPart(this.getZipAdapter());
     this.invalidateMediaCache();
     this.assignStableIds();
     this._bumpNodePagesRevision();
@@ -13818,7 +13838,55 @@ function getRepoDir(docPath) {
   if (root !== null) return import_path3.default.join(root, historyKey(import_path3.default.dirname(docPath)), import_path3.default.basename(docPath));
   return import_path3.default.join(import_path3.default.dirname(docPath), ".astra", import_path3.default.basename(docPath));
 }
+var SNAPSHOT_FORMAT_MARKER = ".astra-snapshot-format";
+var SNAPSHOT_FORMAT_VERSION = "2";
+function isCompleteSnapshotMarker(content) {
+  if (content === void 0) return false;
+  return Buffer.from(content).toString("utf8").trim() === SNAPSHOT_FORMAT_VERSION;
+}
+var ESCAPED_DIR = "__astra_escaped__";
+var ESCAPED_NAME_MAX = 255;
+function needsHistoryEscape(entryName) {
+  const name2 = entryName.replace(/\\/g, "/");
+  if (name2 === SNAPSHOT_FORMAT_MARKER || name2 === "document.xml") return true;
+  if (name2 === ESCAPED_DIR || name2.startsWith(`${ESCAPED_DIR}/`)) return true;
+  return name2.split("/").some((segment) => segment.toLowerCase().startsWith(".git"));
+}
+function isUnrecordableName(entryName) {
+  const name2 = entryName.replace(/\\/g, "/");
+  if (name2 === "" || name2.endsWith("/") || name2.startsWith("/") || /^[a-zA-Z]:/.test(name2)) return true;
+  return name2.split("/").some((segment) => segment === "" || segment === "." || segment === "..");
+}
 function isTrackedPackageFile(entryName) {
+  const name2 = entryName.replace(/\\/g, "/");
+  if (name2 === "word/document.xml") return false;
+  return !isUnrecordableName(name2);
+}
+function historyPathFor(entryName) {
+  const name2 = entryName.replace(/\\/g, "/");
+  if (!needsHistoryEscape(name2)) return name2;
+  const encoded = Buffer.from(name2, "utf8").toString("base64url");
+  if (encoded.length > ESCAPED_NAME_MAX) {
+    throw Object.assign(
+      new Error(`E_VALIDATION: the package entry name is too long to record in history (${name2.length} characters).`),
+      {
+        code: "E_VALIDATION",
+        remedy: "Rename or remove that package part (for example with sanitize_document), then save again."
+      }
+    );
+  }
+  return `${ESCAPED_DIR}/${encoded}`;
+}
+function entryNameFor(repoPath) {
+  const rel = repoPath.replace(/\\/g, "/");
+  if (!rel.startsWith(`${ESCAPED_DIR}/`)) return rel;
+  return Buffer.from(rel.slice(ESCAPED_DIR.length + 1), "base64url").toString("utf8");
+}
+function isRepoPartPath(repoPath) {
+  const rel = repoPath.replace(/\\/g, "/");
+  return rel !== "document.xml" && rel !== SNAPSHOT_FORMAT_MARKER && rel !== "" && !rel.startsWith(".git/");
+}
+function isLegacyTrackedPackageFile(entryName) {
   const name2 = entryName.replace(/\\/g, "/");
   if (name2 === "word/document.xml") return false;
   if (name2 === "word/styles.xml") return true;
@@ -13842,7 +13910,7 @@ function toRepoRelative(entryName) {
 }
 async function writeAndAdd(repoDir, relPath, content) {
   const safeRel = toRepoRelative(relPath);
-  if (safeRel.includes("..") || import_path3.default.isAbsolute(safeRel) || /^[a-zA-Z]:/.test(safeRel)) {
+  if (isTraversalName(safeRel)) {
     throw new Error(`Security Violation: refusing to track package path '${relPath}'`);
   }
   const fullPath = import_path3.default.join(repoDir, safeRel);
@@ -13854,6 +13922,59 @@ async function writeAndAdd(repoDir, relPath, content) {
   await writeFileNoFollow(fullPath, content);
   await import_isomorphic_git.default.add({ fs: import_fs4.default, dir: repoDir, filepath: safeRel });
 }
+function isTraversalName(entryName) {
+  const name2 = toRepoRelative(entryName);
+  return name2.split("/").includes("..") || import_path3.default.isAbsolute(name2) || /^[a-zA-Z]:/.test(name2);
+}
+async function writeSnapshotParts(repoDir, extraFiles) {
+  const written = /* @__PURE__ */ new Set();
+  if (!extraFiles) return written;
+  for (const [name2, content] of Object.entries(extraFiles)) {
+    if (isTraversalName(name2)) {
+      await writeAndAdd(repoDir, name2, content);
+      continue;
+    }
+    if (!isTrackedPackageFile(name2)) continue;
+    const repoPath = historyPathFor(name2);
+    await writeAndAdd(repoDir, repoPath, content);
+    written.add(repoPath);
+  }
+  return written;
+}
+async function indexedPartPaths(repoDir) {
+  const tracked = await import_isomorphic_git.default.listFiles({ fs: import_fs4.default, dir: repoDir });
+  return new Set(tracked.map((t) => toRepoRelative(t)).filter(isRepoPartPath));
+}
+async function snapshotIsProvenComplete(repoDir, extraFiles, written) {
+  if (!extraFiles) return false;
+  try {
+    const indexed = await indexedPartPaths(repoDir);
+    if (indexed.size !== written.size) return false;
+    for (const p of written) if (!indexed.has(p)) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function applySnapshotMarker(repoDir, complete) {
+  if (complete) {
+    await writeAndAdd(repoDir, SNAPSHOT_FORMAT_MARKER, `${SNAPSHOT_FORMAT_VERSION}
+`);
+    return;
+  }
+  try {
+    await import_promises2.default.unlink(import_path3.default.join(repoDir, SNAPSHOT_FORMAT_MARKER));
+  } catch {
+  }
+  try {
+    await import_isomorphic_git.default.remove({ fs: import_fs4.default, dir: repoDir, filepath: SNAPSHOT_FORMAT_MARKER });
+  } catch {
+  }
+  const stillIndexed = (await import_isomorphic_git.default.listFiles({ fs: import_fs4.default, dir: repoDir })).some((t) => toRepoRelative(t) === SNAPSHOT_FORMAT_MARKER);
+  if (stillIndexed) {
+    throw new Error("History commit refused: could not clear the snapshot marker of an earlier commit.");
+  }
+}
 async function chmod0700BestEffort(dir) {
   if (process.platform === "win32") return;
   try {
@@ -14229,11 +14350,8 @@ async function initAstraRepo(docPath, initialXml, extraFiles) {
   const repoDir = await ensureAstraGitRepo(docPath);
   await import_isomorphic_git.default.init({ fs: import_fs4.default, dir: repoDir });
   await writeAndAdd(repoDir, "document.xml", initialXml);
-  if (extraFiles) {
-    for (const [name2, content] of Object.entries(extraFiles)) {
-      await writeAndAdd(repoDir, name2, content);
-    }
-  }
+  const writtenParts = await writeSnapshotParts(repoDir, extraFiles);
+  await applySnapshotMarker(repoDir, await snapshotIsProvenComplete(repoDir, extraFiles, writtenParts));
   await import_isomorphic_git.default.commit({
     fs: import_fs4.default,
     dir: repoDir,
@@ -14289,41 +14407,35 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
   } catch (err) {
     if (err?.code === HISTORY_QUOTA_CODE) throw err;
   }
-  await writeAndAdd(repoDir, "document.xml", xmlContent);
   if (extraFiles) {
-    for (const [name2, content] of Object.entries(extraFiles)) {
-      await writeAndAdd(repoDir, name2, content);
-    }
+    for (const name2 of Object.keys(extraFiles)) if (!isTraversalName(name2) && isTrackedPackageFile(name2)) historyPathFor(name2);
   }
+  await writeAndAdd(repoDir, "document.xml", xmlContent);
+  const writtenParts = await writeSnapshotParts(repoDir, extraFiles);
   try {
     const toDelete = /* @__PURE__ */ new Set();
     if (deletedFiles) {
       for (const name2 of deletedFiles) {
-        const rel = toRepoRelative(name2);
-        if (rel === "document.xml") continue;
-        toDelete.add(rel);
+        if (!isTrackedPackageFile(name2) || isTraversalName(name2)) continue;
+        toDelete.add(historyPathFor(name2));
       }
     }
     if (extraFiles) {
-      const newTracked = new Set(
-        Object.keys(extraFiles).map((k) => toRepoRelative(k))
-      );
+      const newTracked = writtenParts;
       try {
         const tracked = await import_isomorphic_git.default.listFiles({ fs: import_fs4.default, dir: repoDir });
         for (const t of tracked) {
           const rel = toRepoRelative(t);
-          if (rel === "document.xml") continue;
-          if (isTrackedPackageFile(rel) && !newTracked.has(rel)) {
+          if (isRepoPartPath(rel) && !newTracked.has(rel)) {
             toDelete.add(rel);
           }
         }
       } catch {
       }
       try {
-        const onDisk = await collectRepoFiles(repoDir);
-        for (const rel of onDisk.keys()) {
-          if (rel === "document.xml") continue;
-          if (isTrackedPackageFile(rel) && !newTracked.has(rel)) {
+        const onDisk = await listRepoPaths(repoDir);
+        for (const rel of onDisk) {
+          if (isRepoPartPath(rel) && !newTracked.has(rel)) {
             toDelete.add(rel);
           }
         }
@@ -14331,7 +14443,7 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
       }
     }
     for (const rel of toDelete) {
-      if (rel.includes("..") || import_path3.default.isAbsolute(rel) || /^[a-zA-Z]:/.test(rel)) continue;
+      if (isTraversalName(rel)) continue;
       const fullPath = import_path3.default.join(repoDir, rel);
       try {
         await import_promises2.default.unlink(fullPath);
@@ -14344,6 +14456,7 @@ async function commitChange(docPath, xmlContent, message, extraFiles, deletedFil
     }
   } catch {
   }
+  await applySnapshotMarker(repoDir, await snapshotIsProvenComplete(repoDir, extraFiles, writtenParts));
   const sha = await import_isomorphic_git.default.commit({
     fs: import_fs4.default,
     dir: repoDir,
@@ -14395,8 +14508,8 @@ async function getHistory(docPath) {
   });
   return entries;
 }
-async function collectRepoFiles(repoDir) {
-  const out = /* @__PURE__ */ new Map();
+async function listRepoPaths(repoDir) {
+  const out = [];
   async function walk(dir, relBase) {
     let entries = [];
     try {
@@ -14406,21 +14519,18 @@ async function collectRepoFiles(repoDir) {
     }
     for (const entry of entries) {
       if (entry.name === ".git") continue;
-      const full = import_path3.default.join(dir, entry.name);
       const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) {
-        await walk(full, rel);
-      } else if (entry.isFile()) {
-        try {
-          out.set(rel, await import_promises2.default.readFile(full));
-        } catch {
-        }
-      }
+      if (entry.isDirectory()) await walk(import_path3.default.join(dir, entry.name), rel);
+      else if (entry.isFile()) out.push(rel);
     }
   }
   await walk(repoDir, "");
   return out;
 }
+function trackedPredicateFor(target) {
+  return target.complete ? isTrackedPackageFile : isLegacyTrackedPackageFile;
+}
+var INCOMPLETE_SNAPSHOT_WARNING = "This commit was recorded by an older ASTra version and predates complete snapshots: parts it never recorded (for example comment metadata, document properties, custom XML) keep their current content in the file, so the restore is not exact: those parts can be left without the content-type or relationship entries they had before. Restores to versions saved from now on are exact.";
 async function checkoutCommit(docPath, commitOid) {
   if (typeof commitOid !== "string" || commitOid.length === 0) {
     throw new Error(`Cannot checkout: commit ${commitOid} not found in history.`);
@@ -14484,8 +14594,18 @@ async function checkoutCommit(docPath, commitOid) {
     );
   }
   const xml = Buffer.from(docBlob.blob).toString("utf8");
+  let complete = false;
+  const markerOid = blobs.get(SNAPSHOT_FORMAT_MARKER);
+  if (markerOid) {
+    try {
+      const marker = await import_isomorphic_git.default.readBlob({ fs: import_fs4.default, dir: repoDir, oid: markerOid });
+      complete = isCompleteSnapshotMarker(marker.blob);
+    } catch {
+      complete = false;
+    }
+  }
   const trackedEntries = [...blobs.entries()].filter(
-    ([rel]) => rel !== "document.xml" && isTrackedPackageFile(rel)
+    ([rel]) => isRepoPartPath(rel) && (complete || isLegacyTrackedPackageFile(entryNameFor(rel)))
   );
   const extraBlobs = await Promise.all(
     trackedEntries.map(async ([rel, blobOid]) => {
@@ -14498,11 +14618,11 @@ async function checkoutCommit(docPath, commitOid) {
           `Checkout failed: cannot read blob '${rel}' (${blobOid}) at commit ${commitOid}: ${cause}`
         );
       }
-      return [rel, Buffer.from(blobResult.blob)];
+      return [entryNameFor(rel), Buffer.from(blobResult.blob)];
     })
   );
   const extra = new Map(extraBlobs);
-  return { xml, extra };
+  return { xml, extra, complete };
 }
 async function commitStateIfDiffersFromHead(docPath, xmlContent, message, extraFiles = {}, author) {
   try {
@@ -43908,15 +44028,16 @@ async function handleRevertDocument(store, input) {
         });
       }
       const merged = new Map(preRevertSnap);
+      const isTrackedForTarget = trackedPredicateFor(target);
       for (const key of [...merged.keys()]) {
-        if (key !== "word/document.xml" && isTrackedPackageFile(key)) merged.delete(key);
+        if (key !== "word/document.xml" && isTrackedForTarget(key)) merged.delete(key);
       }
       for (const [k, v] of target.extra) merged.set(k, v);
       merged.set("word/document.xml", Buffer.from(target.xml, "utf8"));
       let writeAttempted = false;
       let commitPhase = false;
       try {
-        handle.parser.restorePackageSnapshot(merged);
+        handle.parser.restorePackageSnapshot(merged, { registerCoreProperties: !target.complete });
         await refreshHandleAstInPlace(handle);
         const buf = handle.parser.rezip();
         const candidate = await validateForBaseline(buf);
@@ -43964,7 +44085,9 @@ async function handleRevertDocument(store, input) {
           dirty: false,
           discardedUnsaved,
           commitOid,
-          commitMessage
+          commitMessage,
+          snapshotComplete: target.complete,
+          ...target.complete ? {} : { restoreWarning: INCOMPLETE_SNAPSHOT_WARNING }
         };
       } catch (stageErr) {
         const preserved = getEngineErrorCode(stageErr);
@@ -44266,7 +44389,8 @@ async function handlePreviewRevert(store, input) {
         const targetXmlBytes = Buffer.from(target.xml, "utf8");
         if (!liveXml || Buffer.compare(liveXml, targetXmlBytes) !== 0) affectedFiles.push("word/document.xml");
         const names = /* @__PURE__ */ new Set();
-        for (const k of liveSnap.keys()) if (k !== "word/document.xml" && isTrackedPackageFile(k)) names.add(k);
+        const isTrackedForTarget = trackedPredicateFor(target);
+        for (const k of liveSnap.keys()) if (k !== "word/document.xml" && isTrackedForTarget(k)) names.add(k);
         for (const k of target.extra.keys()) names.add(k);
         for (const name2 of [...names].sort()) {
           if (affectedFiles.length >= AUDIT_FILES_MAX) break;
@@ -44314,6 +44438,8 @@ async function handlePreviewRevert(store, input) {
         changedValuesTruncated,
         changedValuesPositional,
         ...changedValuesReason ? { changedValuesReason } : {},
+        snapshotComplete: target.complete,
+        ...target.complete ? {} : { restoreWarning: INCOMPLETE_SNAPSHOT_WARNING },
         dirty,
         dirtyHandling: dirty ? `Session holds ${unsavedOps} revision(s) of unsaved edits: a bare real revert would fail closed with E_CONFLICT; a real revert with discardUnsaved:true WOULD discard them (echoed back bounded). Net-zero edits still count as dirty (revisions pending, not a content diff). This preview discarded nothing.` : "Session is clean: a real revert would discard nothing.",
         currentHeadOid: full[0].oid,
@@ -45658,7 +45784,8 @@ var import_zod9 = require("zod");
 // package.json
 var package_default = {
   name: "@attentionform/astra-mcp-server",
-  version: "0.4.0",
+  mcpName: "com.attentionform/astra-mcp-server",
+  version: "0.4.2",
   description: "Official Model Context Protocol (MCP) server for ASTra document IDE",
   main: "dist/index.js",
   types: "dist/index.d.ts",
@@ -45699,8 +45826,8 @@ var package_default = {
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   dependencies: {
-    "@attentionform/astra-engine": "^0.4.0",
-    "@attentionform/ooxml-validator": "^0.4.0",
+    "@attentionform/astra-engine": "^0.4.2",
+    "@attentionform/ooxml-validator": "^0.4.2",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",

package/dist/lib/mcp/handlers/history.d.ts

@@ -36,6 +36,10 @@ export declare function handleRevertDocument(store: McpSessionStore, input: unkn
     discardedUnsaved: DiscardedUnsavedSummary;
     commitOid: string;
     commitMessage: string;
+    /** True when the target commit recorded every package part, so the restore is exact. */
+    snapshotComplete: boolean;
+    /** Present when the target commit predates complete snapshots: the restore is not exact. */
+    restoreWarning?: string;
 } | (McpErrorShape & {
     dirtyReason?: string;
 })>;
@@ -79,6 +83,10 @@ export declare function handlePreviewRevert(store: McpSessionStore, input: unkno
     changedValuesPositional: boolean;
     /** Present when the target range is not computable (empty changedValues). */
     changedValuesReason?: string;
+    /** True when the target commit recorded every package part, so a real revert is exact. */
+    snapshotComplete: boolean;
+    /** Present when the target commit predates complete snapshots: a real revert is not exact. */
+    restoreWarning?: string;
     dirty: boolean;
     dirtyHandling: string;
     currentHeadOid: string;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@attentionform/astra-mcp-server",
-  "version": "0.4.0",
+  "mcpName": "com.attentionform/astra-mcp-server",
+  "version": "0.4.2",
   "description": "Official Model Context Protocol (MCP) server for ASTra document IDE",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,8 +42,8 @@
     "adm-zip-gate": "node ../../scripts/check-adm-zip-imports.mjs"
   },
   "dependencies": {
-    "@attentionform/astra-engine": "^0.4.0",
-    "@attentionform/ooxml-validator": "^0.4.0",
+    "@attentionform/astra-engine": "^0.4.2",
+    "@attentionform/ooxml-validator": "^0.4.2",
     "@modelcontextprotocol/sdk": "^1.32.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",