@ansonlai/docx-redline-js 0.6.0 → 0.6.2

package/AGENTS.md

@@ -9,7 +9,7 @@ or an installed plugin bundle to infer public behavior.
 | Task | Start here |
 |---|---|
 | Edit or review a complete `.docx` | [Agent Fast Start](docs/AGENT_FAST_START.md) and the `docx-redline` CLI |
-| Build an agent/tool wrapper | [README wrapper example](README.md#example-agent-session-wrapper-development-only), then [knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#designing-a-thin-agent-wrapper) |
+| Build or update an agent skill/tool wrapper | [Skill Authoring Contract](docs/SKILL_AUTHORING.md), then [README wrapper example](README.md#example-agent-session-wrapper-development-only) |
 | Change paragraph/range reconciliation | `index.js` → `engine/oxml-engine.js` → selected `engine/*-mode.js` |
 | Change complete-document operations | `services/standalone-operation-runner.js` → `services/document-operation-*.js` |
 | Change DOCX ZIP or CLI behavior | `node/index.js`, `node/docx-document.js`, `node/cli.js` |
@@ -22,12 +22,13 @@ specific advanced operation, API, or recovery topic you need.
 ## Ordinary document edits
 
 Use one focused extraction and one apply call. With a structured wrapper, use
-its revision-bound target handles. For shell-only work, serialize operations to
-stdin and use the explicit agent profile:
+its revision-bound target handles. Follow `selection.hint` when a search for
+restorable text yields 0 matches in accepted view. For shell-only work, use a
+UTF-8 operations file or serializer-backed stdin and the explicit agent profile:
 
 ```bash
-docx-redline extract contract.docx --range 10:30
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --output reviewed.docx
+docx-redline extract contract.docx --search "termination" --around 3
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
 For every ordinary text operation, `modified` is the complete desired
@@ -43,6 +44,10 @@ unchanged failed arguments. Do not accept/reject another reviewer's work or
 remove comments without explicit user authorization. The source is never
 overwritten unless `--in-place` is explicit.
 
+The agent profile preserves progressive execution and the ordinary revision
+policy. Add `--atomic` or `--existing-revisions slice-cross-author` only when
+that policy is intended, and confirm the resolved `effectiveOptions`.
+
 Advanced restore, rejected-view insertion, list, table, formatting, comments,
 revision policies, and failure examples live in the
 [knowledge base](docs/AGENT_KNOWLEDGE_BASE.md#agent-document-workflow-cli) and

package/CHANGELOG.md

@@ -13,6 +13,9 @@
 
 ### New Features
 
+- **Self-describing and bounded agent discovery (WP-00–WP-02)**: CLI contract version 6 adds command-specific JSON help, canonical redline/comment/restore examples, case-insensitive contextual search with `--around`/`--context`/`-C`, direct-hit pagination through `--limit` and `--after`, and deliberate `--all` opt-out. Unscoped inspection is capped at 20 direct records and a 48 KiB soft budget without truncating any returned `exactText`; extraction now distinguishes matches from context and prioritizes human-facing provision/heading references over machine paragraph ordinals.
+- **Composable agent safety and compact output (WP-03–WP-04)**: CLI contract version 7 replaces the atomic-coupled agent profile capability with `agent-safety-profile-v2`. `--profile agent` now enforces complete-success exits while preserving progressive execution and the ordinary revision policy; `--atomic` and `--existing-revisions` compose explicitly. Compact CLI JSON keeps receipts only in the authoritative top-level array, omits exact-match diagnostics, summarizes successful equivalent-whitespace matches, and supports one-line `--compact` output without changing Node or standalone-runner results.
+- **Packaged skill-authoring contract (WP-05)**: `docs/SKILL_AUTHORING.md` separates automation invariants from transaction/revision policy, file-versus-stdin transport, reviewer preferences, recovery-envelope behavior, and human-facing presentation. It requires contract/capability negotiation, focused contextual extraction, and library delegation while retaining the visible `AI Redliner` fallback without a new author guard.
 - **Batch-start source binding (WP-04)**: Strong document-operation targets are compiled once against the immutable source DOM and carried through structural index/fingerprint drift with rollback-aware session identities. Independent edits no longer need manual bottom-up sorting; same-source writes, incompatible revision/format combinations, and unsafe capture fan-out fail before mutation with causal conflict codes. Unique references to paragraph text created elsewhere in the same batch become explicit internal capture dependencies.
 - **Machine-actionable recovery (WP-05)**: Operation, package-facade, example-session, and compact CLI failures now carry recovery envelope version 1 with stable stage/category/action metadata, bounded corrective context, and authorization flags. Failed and partial mutation results include an explicit original-vs-output retry plan and operation indexes. `apply --require-complete` exits with code 3 for partial work while preserving legacy behavior without the flag.
 - **Compact shell-agent protocol (WP-06)**: CLI contract version 5 adds `operations-stdin` and `agent-profile-v1`. `--operations -` accepts UTF-8 operation arrays/envelopes without a temporary operations file, while explicit `--profile agent` combines atomic rollback and complete-success exit behavior and reports its effective settings. `AGENTS.md` is now a 527-word routing card, and the 349-word `docs/AGENT_FAST_START.md` carries the ordinary edit contract. Ambient project configuration was deliberately deferred because it would save only the profile flag while adding hidden state.

package/README.md

@@ -144,10 +144,16 @@ import { inspectDocumentParts } from '@ansonlai/docx-redline-js';
 const inventory = inspectDocumentParts({ documentXml, commentsXml, numberingXml });
 ```
 
-Inspection returns exact paragraph text, target IDs/fingerprints, headings,
-table/list context, revision authors, and joined comment anchors. Filters such
-as `search`, `indexes`, `range`, `revisedOnly`, `inTable`, and `skipEmpty`
-limit output. `revisionView` accepts `accepted`, `rejected`, or `current`.
+Inspection returns exact paragraph text, target IDs/fingerprints, headings,
+table/list context, revision authors, and joined comment anchors. Filters such
+as `search`, `indexes`, `range`, `revisedOnly`, `inTable`, and `skipEmpty`
+limit output. Search is a case-insensitive substring match; `around` adds nearby drafting
+context, while `limit` and `after` page direct hits. When a search yields 0
+matches in the active view, `selection.hint` provides guidance if matches exist
+in the alternate revision view (such as searching for deleted text to restore).
+`revisionView` accepts `accepted`, `rejected`, or `current`. Returned
+paragraphs identify matches versus context and include `humanReference` for
+user-facing summaries.
 
 For complete `.docx` buffers in Node:
 
@@ -211,11 +217,11 @@ latency. Checked comparative results are in the
 
 ### Agent CLI
 
-```bash
-docx-redline extract contract.docx --range 10:30
-docx-redline preflight contract.docx --operations operations.json --author "Editor"
-docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
-docx-redline validate reviewed.docx
+```bash
+docx-redline extract contract.docx --search "termination" --around 3
+docx-redline preflight contract.docx --operations operations.json --author "Editor"
+docx-redline apply contract.docx --operations operations.json --author "Editor" --output reviewed.docx
+docx-redline validate reviewed.docx
 ```
 
 ```bash
@@ -232,7 +238,7 @@ docx-redline apply contract.docx --target "Another author's clause" --modified "
 docx-redline apply contract.docx --operations operations.json --atomic --require-complete --output reviewed.docx
 
 # Agent shell path: JSON is emitted by a serializer, not interpolated by the shell
-node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --output reviewed.docx
+node emit-operations.mjs | docx-redline apply contract.docx --operations - --profile agent --compact --output reviewed.docx
 ```
 
 All commands emit JSON on stdout. `apply` defaults:
@@ -241,18 +247,36 @@ All commands emit JSON on stdout. `apply` defaults:
 - **Existing revisions**: Defaults to `'merge-same-author'`. Pass `--existing-revisions slice-cross-author` to edit inside another reviewer's pending insertions with native carrier slicing.
 - **Transactionality**: Defaults to `atomic: false` (applies valid operations and reports any failures). Pass `--atomic` for all-or-nothing rollback on any operation error.
 - **Complete-success exit**: Pass `--require-complete` when a progressive `partial` result must exit with code `3`; errors exit with code `2`. Without the flag, partial results retain the legacy zero exit code, so always inspect `completion`.
-- **Agent profile**: `--profile agent` explicitly enables atomic rollback and complete-success exit behavior while retaining strict targeting, validation, tracked changes, and `merge-same-author`. It reports the resolved `effectiveOptions`; explicit flags take precedence.
+- **Agent profile**: `--profile agent` enables complete-success exit behavior while retaining the ordinary progressive transaction and existing-revision defaults. Compose it with `--atomic` or an explicit `--existing-revisions` policy when intended, and verify the resolved `effectiveOptions`.
 - **Operations from stdin**: `--operations -` reads the same array or `{ operations, expectedRevision }` envelope accepted from a file. Feed it from a JSON serializer or structured process API, not shell-interpolated legal text.
+- **Compact stdout**: `--compact` emits one-line mutation JSON. It changes serialization only, not operation semantics.
 - **Tracked changes**: Defaults to `generateRedlines: true`. Pass `--no-redlines` when clean direct text edits are desired.
 - **Inline edits**: Use `--target <text>` with `--modified <text>` or `--comment <text>` for quick one-liners without creating a JSON file.
-- **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. They report `written`, `outputPath`, per-operation results and receipts, compact validation counts, and a derived `completion` boolean. Use `validate` when full issue arrays are needed.
+- **Compact mutation results**: `apply`, `accept`, `reject`, and `delete-comments` omit full OOXML/package payloads and inspection text from stdout. CLI operation results omit duplicate nested receipt bodies; the ordered top-level `receipts` array is authoritative. Successful exact target-match diagnostics are omitted and equivalent-whitespace matches retain only mode/count. Node and standalone-runner results remain unchanged. Use `validate` when full issue arrays are needed.
 
-`docx-redline version` reports contract version 5 and the additive
-`batch-start-source-binding`, `recovery-envelope-v1`, and
-`require-complete-exit`, `operations-stdin`, and `agent-profile-v1`
-capabilities. Wrappers should negotiate only the capabilities they use.
-
-See the [compact agent fast start](./docs/AGENT_FAST_START.md) and the
+Inspection commands default to 20 direct matches and a 48 KiB soft response
+budget when no explicit positional scope is supplied. When a search returns 0
+matches in the requested view, `selection.hint` provides immediate guidance if
+matches exist in the alternate view (such as searching for a deleted clause to
+restore). Use `--limit` with `--after <paragraph-index>` to continue, `--around N`
+(aliases `--context` and `-C`) to include nearby paragraphs, and `--all` only
+for deliberate unbounded inspection. Every retained target is complete; an
+individually oversized paragraph is returned whole with an `oversizeItem`
+marker. Machine `index` and `ref` fields are for targeting and pagination, not
+user-facing Word locations; use `humanReference`, `provision`, or
+`nearestHeading` in reports.
+
+`docx-redline version` reports contract version 7 and the additive
+`command-help-v1`, `inspection-context-v1`, `bounded-inspection-v1`,
+`human-document-references-v1`, `batch-start-source-binding`,
+`recovery-envelope-v1`, `require-complete-exit`, `operations-stdin`,
+`agent-safety-profile-v2`, `deduplicated-cli-receipts`, and
+`compact-cli-json-v1` capabilities. Wrappers should negotiate only the
+capabilities they use. Run `docx-redline <command> --help` for that command's
+machine-readable options, behavior, exit codes, canonical GitHub documentation links, and compact examples.
+
+See the [compact agent fast start](./docs/AGENT_FAST_START.md), the
+[skill/harness authoring contract](./docs/SKILL_AUTHORING.md), and the
 [operation JSON Schema](docs/schemas/document-operations.schema.json).
 
 ### Configuration (call once at startup)
@@ -554,10 +578,14 @@ guidance. Callers should pass `{ strictTargets: true }` and use strict descripto
 
 ### Mutation Receipts
 
-Both single-operation (`applyOperationToDocumentXml`) and batch
-(`applyOperationsToDocumentXml`) results expose commit-aware **Mutation Receipts**
-(`result.receipt` on single results and per-item `results[i].receipt`, plus `result.receipts`
-for the full batch).
+Both single-operation (`applyOperationToDocumentXml`) and batch
+(`applyOperationsToDocumentXml`) results expose commit-aware **Mutation Receipts**
+(`result.receipt` on single results and per-item `results[i].receipt`, plus `result.receipts`
+for the full batch).
+
+This full receipt shape is retained by the Node facade and standalone runner.
+Only compact CLI JSON removes duplicate `results[i].receipt` bodies and keeps
+the ordered top-level `receipts` array.
 
 ```js
 const result = await applyOperationsToDocumentXml(documentXml, operations, 'Agent');

package/dist/docx-redline-js.esm.js

@@ -1,4 +1,4 @@
-// @ansonlai/docx-redline-js v0.6.0 — https://github.com/AnsonLai/docx-redline-js
+// @ansonlai/docx-redline-js v0.6.2 — https://github.com/AnsonLai/docx-redline-js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -11466,6 +11466,70 @@ function collectDocumentCommentAnchors(paragraphNodes, revisionView) {
   });
   return anchors;
 }
+function selectInspectionParagraphs(allParagraphs, options) {
+  let matches = allParagraphs;
+  if (options.revisedOnly) matches = matches.filter((item) => item.hasRevisions);
+  if (options.inTable != null) matches = matches.filter((item) => item.inTable === !!options.inTable);
+  if (options.skipEmpty) matches = matches.filter((item) => item.text.length > 0);
+  if (options.search) {
+    const needle = String(options.search).toLowerCase();
+    matches = matches.filter((item) => item.text.toLowerCase().includes(needle));
+  }
+  if (Array.isArray(options.indexes)) {
+    const indexes = new Set(options.indexes);
+    matches = matches.filter((item) => indexes.has(item.index));
+  }
+  let rangeStart = 1;
+  let rangeEnd = allParagraphs.length;
+  if (options.range) {
+    rangeStart = Number(options.range.start ?? options.range[0]);
+    rangeEnd = Number(options.range.end ?? options.range[1]);
+    matches = matches.filter((item) => item.index >= rangeStart && item.index <= rangeEnd);
+  }
+  const totalMatches = matches.length;
+  const after = Number.isInteger(options.after) && options.after > 0 ? options.after : null;
+  const remaining = after == null ? matches : matches.filter((item) => item.index > after);
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : null;
+  const selectedMatches = limit == null ? remaining : remaining.slice(0, limit);
+  const truncated = selectedMatches.length < remaining.length;
+  const around = Number.isInteger(options.around) && options.around > 0 ? options.around : 0;
+  const exposeSelection = !!options.search || around > 0 || limit != null || after != null;
+  let paragraphs = selectedMatches;
+  if (around > 0 && options.search) {
+    const directIndexes = new Set(selectedMatches.map((item) => item.index));
+    const contextFor = /* @__PURE__ */ new Map();
+    for (const match of selectedMatches) {
+      const start = Math.max(rangeStart, match.index - around);
+      const end = Math.min(rangeEnd, match.index + around);
+      for (let index = start; index <= end; index++) {
+        if (directIndexes.has(index)) continue;
+        const owners = contextFor.get(index) || [];
+        owners.push(match.index);
+        contextFor.set(index, owners);
+      }
+    }
+    const returnedIndexes = /* @__PURE__ */ new Set([...directIndexes, ...contextFor.keys()]);
+    paragraphs = allParagraphs.filter((item) => returnedIndexes.has(item.index)).map((item) => directIndexes.has(item.index) ? { ...item, selectionRole: "match" } : { ...item, selectionRole: "context", contextFor: contextFor.get(item.index) || [] });
+  } else if (exposeSelection) {
+    paragraphs = selectedMatches.map((item) => ({ ...item, selectionRole: "match" }));
+  }
+  return {
+    paragraphs,
+    ...exposeSelection ? {
+      selection: {
+        ...options.search ? { search: String(options.search), caseSensitive: false } : {},
+        totalMatches,
+        returnedMatches: selectedMatches.length,
+        returnedParagraphs: paragraphs.length,
+        truncated,
+        nextAfter: truncated && selectedMatches.length > 0 ? selectedMatches[selectedMatches.length - 1].index : null,
+        ...limit != null ? { limit } : {},
+        ...after != null ? { after } : {},
+        ...around > 0 ? { around } : {}
+      }
+    } : {}
+  };
+}
 function inspectDocumentParts(parts, options = {}) {
   const documentPart = parseXml2(parts?.documentXml, "word/document.xml", true);
   if (documentPart.error) return { status: "error", error: documentPart.error, paragraphs: [], comments: [], warnings: [] };
@@ -11495,7 +11559,8 @@ function inspectDocumentParts(parts, options = {}) {
     const index = zeroIndex + 1;
     const provision = list?.label && list.format !== "bullet" ? list.label : null;
     const headingText = nearestHeading?.text || null;
-    const humanReference = [provision, headingText, text.slice(0, options.excerptLength || 120)].filter(Boolean).join(" \u2014 ");
+    const excerpt = text.slice(0, options.excerptLength || 120);
+    const humanReference = level ? text : provision ? [provision, headingText].filter(Boolean).join(" \u2014 ") : headingText ? [headingText, excerpt].filter(Boolean).join(" \u2014 ") : excerpt;
     const segments = extractParagraphRevisionSegments(paragraph);
     return {
       index,
@@ -11505,8 +11570,9 @@ function inspectDocumentParts(parts, options = {}) {
       revisionView,
       text,
       exactText: text,
-      excerpt: text.slice(0, options.excerptLength || 120),
+      excerpt,
       humanReference,
+      provision,
       inTable: hasAncestor(paragraph, "tc"),
       table: structure.table,
       styleId,
@@ -11527,22 +11593,36 @@ function inspectDocumentParts(parts, options = {}) {
     definition.anchoredText ?? (definition.anchoredText = commentAnchors.get(id) || paragraph.text);
     comments.set(id, definition);
   }
-  if (options.revisedOnly) paragraphs = paragraphs.filter((item) => item.hasRevisions);
-  if (options.inTable != null) paragraphs = paragraphs.filter((item) => item.inTable === !!options.inTable);
-  if (options.skipEmpty) paragraphs = paragraphs.filter((item) => item.text.length > 0);
-  if (options.search) {
+  const selected = selectInspectionParagraphs(paragraphs, options);
+  if (options.search && selected.selection && selected.selection.totalMatches === 0) {
     const needle = String(options.search).toLowerCase();
-    paragraphs = paragraphs.filter((item) => item.text.toLowerCase().includes(needle));
-  }
-  if (Array.isArray(options.indexes)) {
-    const indexes = new Set(options.indexes);
-    paragraphs = paragraphs.filter((item) => indexes.has(item.index));
-  }
-  if (options.range) {
-    const start = Number(options.range.start ?? options.range[0]);
-    const end = Number(options.range.end ?? options.range[1]);
-    paragraphs = paragraphs.filter((item) => item.index >= start && item.index <= end);
-  }
+    const alternateView = revisionView === "accepted" ? "rejected" : "accepted";
+    let rangeStart = 1;
+    let rangeEnd = paragraphNodes.length;
+    if (options.range) {
+      rangeStart = Number(options.range.start ?? options.range[0]);
+      rangeEnd = Number(options.range.end ?? options.range[1]);
+    }
+    let alternateMatches = 0;
+    for (let i = 0; i < paragraphNodes.length; i++) {
+      const index = i + 1;
+      if (options.range && (index < rangeStart || index > rangeEnd)) continue;
+      if (Array.isArray(options.indexes) && !options.indexes.includes(index)) continue;
+      const pNode = paragraphNodes[i];
+      if (options.table && !hasAncestor(pNode, "tc")) continue;
+      if (options.body && hasAncestor(pNode, "tc")) continue;
+      if (options.revised && revisionAuthors(pNode).length === 0) continue;
+      const altText = extractCanonicalParagraphText(pNode, { revisionView: alternateView });
+      if (options.skipEmpty && altText.length === 0) continue;
+      if (altText.toLowerCase().includes(needle)) {
+        alternateMatches++;
+      }
+    }
+    if (alternateMatches > 0) {
+      selected.selection.hint = revisionView === "accepted" ? `0 matches in accepted view, but ${alternateMatches} match${alternateMatches === 1 ? "" : "es"} found in --view rejected. If searching for deleted text to restore, re-run with --view rejected.` : `0 matches in rejected view, but ${alternateMatches} match${alternateMatches === 1 ? "" : "es"} found in --view accepted. Re-run with --view accepted.`;
+    }
+  }
+  paragraphs = selected.paragraphs;
   const allRevisionAuthors = [...new Set(paragraphs.flatMap((item) => item.revisionAuthors))].sort();
   const coveredEntries = extractDocumentPartsEntries(parts);
   const coveredParts = coveredEntries.map((e) => e.name).sort();
@@ -11559,6 +11639,7 @@ function inspectDocumentParts(parts, options = {}) {
     revisionToken,
     coveredParts,
     paragraphs,
+    ...selected.selection ? { selection: selected.selection } : {},
     comments: [...comments.values()],
     revisionAuthors: allRevisionAuthors,
     commentAuthors: [...new Set([...comments.values()].map((item) => item.author).filter(Boolean))].sort(),