@ansonlai/docx-redline-js 0.8.0 → 0.8.1

package/docs/AGENT_KNOWLEDGE_BASE.md

@@ -399,7 +399,7 @@ algorithms:
 - Shell/file wrappers invoke the `docx-redline` CLI and preserve its JSON stdout
   and exit code.
 - Node byte-oriented wrappers use `openDocx`, `inspect`, `applyOperations`,
-  `resolveRevisions`, `deleteComments`, and `toBuffer`.
+  `resolveRevisions`, `deleteComments`, `resolveComment`, and `toBuffer`.
 - XML-only hosts use the standalone runner and remain responsible for package
   artifacts returned beside `documentXml`.
 - Paragraph/range hosts use root exports and remain responsible for deciding how
@@ -609,7 +609,9 @@ normalize or reconstruct `exactText`. Operation files follow
 - `preflight` checks targets, anchors, revisions, conflicts, authors, and needed artifacts without mutation (read-only).
 - `apply` applies an operation file transactionally with automatic rollback and internal markup validation.
 - `accept` and `reject` resolve revisions selected by `--author` or `--all-authors`.
-- `delete-comments` removes matching definitions and document anchors together.
+- `delete-comments` removes matching definitions and document anchors together, selected by `--author`,
+  `--all-authors`, or `--comment-id <id[,id]>` (ids from `inspect`). Deleting a thread root also deletes its
+  replies; unknown ids fail with `COMMENT_NOT_FOUND`.
 - A whole-paragraph delete stops with `COMMENTED_CONTENT_DELETE` when the
   paragraph has an existing comment. Surface the returned reviewer and comment
   text for human follow-up; do not silently convert this into comment removal.
@@ -656,8 +658,57 @@ To reply inside an existing Word comment thread, use the comment ID returned by
 { "type": "comment_reply", "parentCommentId": "8", "commentContent": "Agreed; updated.", "author": "Editor" }
 ```
 
-Replies are represented in `word/commentsExtended.xml` and deliberately add no
-new `commentRangeStart`, `commentRangeEnd`, or `commentReference` to the body.
+A reply is defined in `word/comments.xml` and linked to its thread in `word/commentsExtended.xml`
+(`w15:paraIdParent`, keyed on the last paragraph of each comment, as Word does). Word only displays a
+reply that also has its own `commentRangeStart`, `commentRangeEnd` and `commentReference` around the same
+range as its thread, so the operation adds those markers next to the thread's existing ones. A reply to a
+reply joins the root thread. If the parent has no anchor in the body the operation fails with
+`PARENT_ANCHOR_NOT_FOUND`.
+
+#### Headers and footers
+
+`inspect().headersFooters` lists every header/footer part the document uses, with its paragraph text:
+`path`, `kind`, `type` (`default`/`first`/`even`), `appliesToSections`, `active`, `hasFields`. Add `part` to an
+operation to edit one instead of the body; everything else in the operation is unchanged:
+
+```json
+{ "type": "replace", "part": { "kind": "footer", "type": "default", "section": 0 },
+  "target": { "exactText": "Draft v1" }, "modified": "Draft v2" }
+```
+
+`part` is a selector (`kind`, optional `type` defaulting to `default`, optional zero-based `section`) or a part path such as
+`word/footer2.xml`. Omitting `part` always targets the body; headers and footers are opt-in. Rules:
+
+- A footer or header shared by several sections is one part; the result lists `partSections`. A section with no reference of its
+  own inherits the previous section's part (Word's "link to previous"), and `section` finds it.
+- Several distinct parts matching a selector fail with `PART_AMBIGUOUS` (add `section` or use the path); none fail with
+  `PART_NOT_FOUND`. A bad selector rejects the whole request before anything is written.
+- Fields are atomic. An edit that would change a `PAGE`/`NUMPAGES`/`DATE` field's text fails with `FIELD_EDIT_REFUSED`; edit the
+  text around the field instead.
+- `comment`, `comment_reply` and `comment_resolve` with `part` fail with `COMMENT_IN_HEADER_FOOTER` (Word has no comments in headers or footers).
+- Body and part operations can share a batch; results keep the original operation indexes and carry `part`. Atomic batches roll
+  back across body and parts. Revision ids stay unique across the whole package.
+- `accept` / `reject` (API and CLI) also resolve tracked changes inside headers and footers.
+- Creating a header/footer that does not exist is not supported.
+- `exactText` in a header or footer is the whole paragraph text as `headersFooters[].paragraphs` shows it, including the
+  current result of any field (for example `Page 1`).
+
+#### Resolving comment threads
+
+Resolve (or reopen with `"resolved": false`) the thread containing a comment id from `inspect`:
+
+```json
+{ "type": "comment_resolve", "commentId": "8" }
+```
+
+The API form is `await doc.resolveComment(commentId, { resolved })`. Word resolves whole threads, so any id in
+the thread updates the root and every reply together; a reply added to a resolved thread is written resolved,
+as Word does. Only `word/commentsExtended.xml` changes. Resolving an already-resolved thread is `no_change`.
+Unknown ids fail with `COMMENT_NOT_FOUND`, in `preflight` as well as `apply`. Operations run in batch order, so
+`comment_reply` followed by `comment_resolve` closes the thread including the new reply. Like any comment
+operation it is refused with `part`.
+
+Resolving and deleting other reviewers' comments are review decisions: do them only when the user asked.
 
 #### Legacy skill wrapper migration
 
@@ -724,6 +775,11 @@ When the CLI or runner returns an error code, follow these specific recovery act
 | `REJECTED_INSERTION_STATE_REQUIRED` / `UNSAFE_REVISION_BOUNDARY` | An explicit rejected-view insertion did not resolve to supported plain run text inside a wholly foreign-deleted paragraph. | Do not fall back to a generic edit. Narrow the exact anchor/offset, or handle comments, bookmarks, fields, hyperlinks, moves, or other structural boundaries manually. |
 | `GENERATED_OOXML_INVALID` | The operation introduced a new validation error relative to its baseline. | Treat the operation as unapplied and inspect `generatedIssues`; correct the generating operation or builder rather than repairing or accepting the source document's unrelated baseline defects. |
 | `UNSAFE_DELETED_TABLE_ROW` / `UNSUPPORTED_MOVE_REVISION` / `SECTION_BREAK_PARAGRAPH` / `UNSAFE_PARAGRAPH_PLACEMENT` | Paragraph restoration cannot preserve the source structural boundary safely. | Do not retry as an ordinary redline. Resolve the row/move/section/placement condition manually or narrow the restoration to a safe paragraph. |
+| `PART_NOT_FOUND` / `PART_AMBIGUOUS` | The `part` selector matched no header/footer, or several. | Re-run `inspect` and use `headersFooters[].path`, or add `section`. |
+| `FIELD_EDIT_REFUSED` | The edit would change a field (PAGE, NUMPAGES, DATE) in a header or footer. | Edit the text around the field. |
+| `COMMENT_IN_HEADER_FOOTER` | A comment operation carried `part`. | Comment on body text instead. |
+| `COMMENT_NOT_FOUND` | `comment_resolve` or `delete-comments --comment-id` named an id that is not in the document. | Re-run `inspect` and use `comments[].id`. |
+| `PARENT_COMMENT_NOT_FOUND` / `PARENT_ANCHOR_NOT_FOUND` | A reply's parent id is unknown, or the parent has no anchor in the body. | Re-run `inspect`; reply to a comment that is anchored in the body. |
 | `COMMENTED_CONTENT_MERGE` / `COMMENTED_CONTENT_DELETE` | Operation would overwrite, revert, or delete content with comments. | Fails closed to prevent orphaned comment threads. Report the comment author and text to the user; resolve the comment before re-editing. |
 | `INVALID_OPERATION` | Operation object violates schema or has incompatible fields. | Validate the JSON structure against [`document-operations.schema.json`](schemas/document-operations.schema.json) before targeting is attempted. |
 | `STRUCTURED_CONTENT_INVALID` | Malformed Markdown table or structure in replacement text. | Ensure tables include a separator row (`\| --- \| --- \|`) and consistent column counts; do not downgrade to raw text. |
@@ -732,11 +788,16 @@ When the CLI or runner returns an error code, follow these specific recovery act
 
 #### Document Scope & Boundary Invariants
 
-The `docx-redline` engine and CLI operate specifically on the **main document body**:
+The `docx-redline` engine and CLI operate on the **main document body** and, when an operation sets `part`, on
+**existing header and footer parts**:
 
-- **Supported Content**: Body paragraphs, numbered/bulleted lists, tables and table cells, comments, and comment replies.
-- **Unsupported Content**: Headers, footers, footnotes, endnotes, floating text boxes, shape drawings, watermarks, and embedded macros.
-- Do not attempt to target, edit, or comment on header/footer text or footnote citations using `docx-redline`. Use specialized document manipulation tools or manual editing for layout frames outside the body text.
+- **Supported Content**: Body paragraphs, numbered/bulleted lists, tables and table cells, comments, comment replies,
+  resolving/reopening comment threads, and text in existing headers and footers (see *Headers and footers*).
+- **Unsupported Content**: Footnotes, endnotes, floating text boxes, shape drawings, images, watermarks, embedded macros,
+  creating a header or footer that does not exist, editing field codes or results (`PAGE`, `NUMPAGES`, `DATE`), and
+  comments in headers or footers (Word has none).
+- Do not attempt to target footnote citations or text boxes with `docx-redline`. Header/footer text is edited only with
+  an explicit `part`; body searches never match it.
 
 ### Convert paragraph text into a Word list
 

package/docs/schemas/document-operations.schema.json

@@ -71,6 +71,22 @@
         }
       ]
     },
+    "headerFooterPart": {
+      "description": "Targets a header or footer instead of the body. Use a part path from inspect().headersFooters, or a selector. Comments are not supported in headers or footers.",
+      "oneOf": [
+        { "type": "string", "minLength": 1, "examples": ["word/footer2.xml"] },
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "enum": ["header", "footer"] },
+            "type": { "enum": ["default", "first", "even"], "description": "Defaults to default." },
+            "section": { "type": "integer", "minimum": 0, "description": "Zero-based section; required when several sections have their own part." }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "base": {
       "type": "object",
       "required": ["type", "target"],
@@ -78,6 +94,7 @@
         "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
         "captureKey": { "type": "string", "minLength": 1, "maxLength": 256 },
         "target": { "$ref": "#/$defs/target" }, "targetRef": { "type": ["integer", "string", "null"] },
+        "part": { "$ref": "#/$defs/headerFooterPart" },
         "author": { "type": "string", "minLength": 1 }, "generateRedlines": { "type": "boolean" },
         "existingRevisions": { "enum": ["merge-same-author", "slice-cross-author", "reject-input", "accept-all-first", "accept-all-first-keep-normalized"] },
         "pairReplacements": { "type": "boolean" },
@@ -109,6 +126,18 @@
           },
           "additionalProperties": false
         },
+        {
+          "type": "object",
+          "description": "Resolve or reopen the comment thread containing commentId. Resolved is thread-level in Word, so the root and every reply change together. Body-only; not allowed with part.",
+          "required": ["type", "commentId"],
+          "properties": {
+            "type": { "const": "comment_resolve" },
+            "operationId": { "type": "string", "minLength": 1, "maxLength": 256 },
+            "commentId": { "type": ["integer", "string"] },
+            "resolved": { "type": "boolean", "default": true }
+          },
+          "additionalProperties": false
+        },
         {
           "allOf": [ { "$ref": "#/$defs/base" }, { "type": "object", "required": ["replacements"], "properties": { "type": { "enum": ["redline", "replace"] }, "replacements": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/localizedReplacement" } } } } ]
         },