@attentionform/astra 0.4.1 → 0.4.2

package/README.md

@@ -110,7 +110,7 @@ Renders one saved-file page to PNG/JPEG via headless LibreOffice (same renderer
 Lists recorded sidecar commits newest first; read-only; `--init` (alias `--track`) records the current file as the baseline when no sidecar exists yet.
 
 ### 13. Revert to Recorded State (`astra revert`)
-Restores the tracked package state `--steps <n>` commits back and records the restore as a new commit (append-only); `preview-revert` previews the same change read-only.
+Restores the package state `--steps <n>` commits back (every package part, comment metadata and document properties included) and records the restore as a new commit (append-only). Commits recorded before 0.4.2 hold fewer parts, so restoring from one prints a warning; `preview-revert` previews the same change read-only.
 
 ### 14. Redo Reverted State (`astra redo`)
 Re-applies the state replaced by the most recent revert (one redo per revert head).

package/dist/cli.js

@@ -6175,6 +6175,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;
@@ -6946,6 +6949,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 = [];
@@ -10579,9 +10591,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);
@@ -10600,8 +10613,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);
       }
@@ -10626,7 +10646,7 @@ var DocxParser = class _DocxParser {
     } else {
       this.stylesDom = null;
     }
-    registerExistingCorePropertiesPart(this.getZipAdapter());
+    if (options?.registerCoreProperties) registerExistingCorePropertiesPart(this.getZipAdapter());
     this.invalidateMediaCache();
     this.assignStableIds();
     this._bumpNodePagesRevision();
@@ -13886,7 +13906,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;
@@ -13910,7 +13978,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);
@@ -13922,6 +13990,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 {
@@ -14297,11 +14418,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,
@@ -14357,41 +14475,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);
           }
         }
@@ -14399,7 +14511,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);
@@ -14412,6 +14524,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,
@@ -14463,8 +14576,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 {
@@ -14474,21 +14587,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.`);
@@ -14552,8 +14662,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]) => {
@@ -14566,11 +14686,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 {
@@ -40718,7 +40838,7 @@ function summarizeStyleGuide(guide) {
 // package.json
 var package_default = {
   name: "@attentionform/astra",
-  version: "0.4.1",
+  version: "0.4.2",
   description: "Command-line tool for OOXML (.docx) document engineering",
   main: "dist/cli.js",
   types: "dist/packages/cli/src/cli.d.ts",
@@ -40762,7 +40882,7 @@ var package_default = {
   },
   dependencies: {
     "@attentionform/astra-engine": "^0.4.0",
-    "@attentionform/ooxml-validator": "^0.4.1",
+    "@attentionform/ooxml-validator": "^0.4.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",
     "isomorphic-git": "^1.25.0",
@@ -41538,10 +41658,13 @@ function commandHelpText(cmd) {
       "  working file was modified since the last recorded commit (E_CONFLICT: a revert would",
       "  overwrite changes that were never recorded). The restored package is written only after",
       "  it passes the OOXML validation gate; a commit failure restores the pre-command bytes.",
-      "Tracked package files only: document.xml, [Content_Types].xml,",
-      "  word/{styles,numbering,settings,comments,footnotes,endnotes}.xml, header/footer parts and",
-      "  their rels, the document rels, and word/{media,charts,embeddings,theme}/; parts outside",
-      "  that set (e.g. docProps/) keep the working-file bytes.",
+      "Every package part is recorded and restored (document.xml, [Content_Types].xml, styles, comments",
+      "  and their metadata, word/{media,charts,embeddings,theme}/, docProps/, custom XML, ...); a part",
+      "  the commit does not have is removed. Commits recorded by ASTra versions before 0.4.2 hold only",
+      "  document.xml, [Content_Types].xml, word/{styles,numbering,settings,comments,footnotes,endnotes}.xml,",
+      "  header/footer parts and their rels, the document rels, and word/{media,charts,embeddings,theme}/;",
+      "  restoring from one prints a warning, and parts outside that set (e.g. docProps/) keep the",
+      "  working-file bytes.",
       "Exit 0 ok \xB7 1 conflict/validation/IO failure (nothing written) \xB7 2 bad args/absent sidecar."
     ].join("\n"),
     redo: [
@@ -41601,10 +41724,10 @@ function sidecarGitState(file) {
 function hasHistorySidecar(file) {
   return sidecarGitState(file) === "repo";
 }
-function trackedExtras(snapshot3) {
+function trackedExtras(snapshot3, isTracked = isTrackedPackageFile) {
   const out = /* @__PURE__ */ new Map();
   for (const [name2, buf] of snapshot3) {
-    if (name2 !== "word/document.xml" && isTrackedPackageFile(name2)) out.set(name2, buf);
+    if (name2 !== "word/document.xml" && isTracked(name2)) out.set(name2, buf);
   }
   return out;
 }
@@ -45363,7 +45486,7 @@ async function divergedFiles(file, parser2, commitOid) {
   const recorded = await checkoutCommit(file, commitOid);
   const snapshot3 = parser2.capturePackageSnapshot();
   const liveXml = snapshot3.get("word/document.xml")?.toString("utf8") ?? "";
-  return packageDiff(liveXml, trackedExtras(snapshot3), recorded.xml, recorded.extra);
+  return packageDiff(liveXml, trackedExtras(snapshot3, trackedPredicateFor(recorded)), recorded.xml, recorded.extra);
 }
 function sidecarWarning(commits) {
   const carried = commits.warning;
@@ -45458,12 +45581,13 @@ function parseDocStepsArgs(out, cmd, args) {
 async function restoreAndCommit(opts) {
   const { cmd, file, parser: parser2, prevBytes, target, targetOid, commitMessage } = opts;
   const snapshot3 = parser2.capturePackageSnapshot();
+  const isTrackedForTarget = trackedPredicateFor(target);
   for (const key of [...snapshot3.keys()]) {
-    if (key !== "word/document.xml" && isTrackedPackageFile(key)) snapshot3.delete(key);
+    if (key !== "word/document.xml" && isTrackedForTarget(key)) snapshot3.delete(key);
   }
   for (const [name2, data] of target.extra) snapshot3.set(name2, data);
   snapshot3.set("word/document.xml", Buffer.from(target.xml, "utf8"));
-  parser2.restorePackageSnapshot(snapshot3);
+  parser2.restorePackageSnapshot(snapshot3, { registerCoreProperties: !target.complete });
   const buf = parser2.rezip();
   const candidate = await validateDocxBuffer(buf, { maxErrors: BASELINE_MAX_ERRORS });
   if (!candidate.ok && judgeAgainstBaseline(candidate, buildBaseline(candidate)).kind !== "tolerated") {
@@ -45635,7 +45759,7 @@ async function cmdPreviewRevert(out, args) {
     const target = await checkoutCommit(file, targetOid);
     const snapshot3 = parser2.capturePackageSnapshot();
     const liveXml = snapshot3.get("word/document.xml")?.toString("utf8") ?? "";
-    const affectedFiles = packageDiff(liveXml, trackedExtras(snapshot3), target.xml, target.extra);
+    const affectedFiles = packageDiff(liveXml, trackedExtras(snapshot3, trackedPredicateFor(target)), target.xml, target.extra);
     const changed = await divergedFiles(file, parser2, commits[0].oid);
     const warning = sidecarWarning(commits);
     const head = commits[0].oid;
@@ -45653,6 +45777,7 @@ async function cmdPreviewRevert(out, args) {
       changed.length > 0 ? `  working file: DIVERGED from head ${shortOid(head)} \u2014 a real revert would refuse E_CONFLICT (changed: ${shownList(changed)})` : `  working file: clean at head ${shortOid(head)} \u2014 a real revert would proceed`
     );
     if (warning) printStderr(`${CLI_NAME}: warning: ${warning}`);
+    if (!target.complete) printStderr(`${CLI_NAME}: warning: ${INCOMPLETE_SNAPSHOT_WARNING}`);
     printJson(out, {
       ok: true,
       command: "preview-revert",
@@ -45666,7 +45791,9 @@ async function cmdPreviewRevert(out, args) {
       totalCommits: commits.length,
       diverged: changed.length > 0,
       divergedFiles: changed,
-      warning
+      warning,
+      snapshotComplete: target.complete,
+      ...target.complete ? {} : { restoreWarning: INCOMPLETE_SNAPSHOT_WARNING }
     });
     return EXIT_OK;
   } catch (err) {
@@ -45699,6 +45826,7 @@ async function cmdRevert(out, args) {
       out,
       `REVERT OK ${file}: restored ${shortOid(targetOid)} "${subject}" (steps=${steps}); new commit ${shortOid(result.commitOid)}`
     );
+    if (!target.complete) printStderr(`${CLI_NAME}: warning: ${INCOMPLETE_SNAPSHOT_WARNING}`);
     printJson(out, {
       ok: true,
       command: "revert",
@@ -45706,7 +45834,9 @@ async function cmdRevert(out, args) {
       steps,
       revertedToCommit: targetOid,
       commitOid: result.commitOid,
-      commitMessage: result.commitMessage
+      commitMessage: result.commitMessage,
+      snapshotComplete: target.complete,
+      ...target.complete ? {} : { restoreWarning: INCOMPLETE_SNAPSHOT_WARNING }
     });
     return EXIT_OK;
   } catch (err) {
@@ -45752,13 +45882,16 @@ async function cmdRedo(out, args) {
       out,
       `REDO OK ${file}: re-applied the state replaced by revert ${shortOid(headOid)}; new commit ${shortOid(result.commitOid)}`
     );
+    if (!target.complete) printStderr(`${CLI_NAME}: warning: ${INCOMPLETE_SNAPSHOT_WARNING}`);
     printJson(out, {
       ok: true,
       command: "redo",
       file,
       restoredCommit: targetOid,
       commitOid: result.commitOid,
-      commitMessage: result.commitMessage
+      commitMessage: result.commitMessage,
+      snapshotComplete: target.complete,
+      ...target.complete ? {} : { restoreWarning: INCOMPLETE_SNAPSHOT_WARNING }
     });
     return EXIT_OK;
   } catch (err) {

package/dist/packages/cli/src/cli/history-support.d.ts

@@ -13,8 +13,12 @@ export type SidecarGitState = 'repo' | 'stray' | 'absent';
 export declare function sidecarGitState(file: string): SidecarGitState;
 /** Is a valid sidecar chain present for this document? */
 export declare function hasHistorySidecar(file: string): boolean;
-/** Tracked package files (everything but document.xml) from a live snapshot. */
-export declare function trackedExtras(snapshot: Map<string, Buffer>): Map<string, Buffer>;
+/**
+ * Tracked package files (everything but document.xml) from a live snapshot. `isTracked` selects the
+ * rule: the default is the complete-snapshot rule; pass trackedPredicateFor(commit) to compare with a
+ * commit recorded by an older ASTra version.
+ */
+export declare function trackedExtras(snapshot: Map<string, Buffer>, isTracked?: (name: string) => boolean): Map<string, Buffer>;
 export declare function extrasRecord(extras: Map<string, Buffer>): Record<string, Buffer>;
 export type BatchRevisionResult = {
     recorded: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@attentionform/astra",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Command-line tool for OOXML (.docx) document engineering",
   "main": "dist/cli.js",
   "types": "dist/packages/cli/src/cli.d.ts",
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@attentionform/astra-engine": "^0.4.0",
-    "@attentionform/ooxml-validator": "^0.4.1",
+    "@attentionform/ooxml-validator": "^0.4.2",
     "@xmldom/xmldom": "0.8.15",
     "adm-zip": "0.6.1",
     "isomorphic-git": "^1.25.0",