revise 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## 3.1.0
+
+### Added
+
+- **`--blocks` on `changes`, `accept`, and `reject`.** Select tracked
+  changes by block: ids (`--blocks a1B2c3,d4E5f6`) or a range in document
+  order (`--blocks a1B2c3..d4E5f6`). Ids of list items, table cells, and
+  paragraphs inside them work. In the library: `{ blocks: [...] }`, with
+  ranges as `{ from, to }`.
+- **`--view tracked|accepted|original`** on `read`, `grep`, `search`,
+  `export`, and `convert`. `read` now shows pending changes inline as
+  `<del>` and `<ins>` with their change ids and authors; `grep` and `search`
+  find text on both sides of a change and say which side it's on. `export`
+  and `convert` with `--view original` write the document as it was before
+  every pending change. `--final` still means `--view accepted`.
+- **`replace-all --ignore-case` and `--exact`.**
+
+### Changed
+
+- **`replace-text` is now `replace-all`** (`replaceAll` in the library). It
+  replaces in page headers and footers and in footnotes and endnotes as well
+  as the body, and says where. Curly and straight quotes, no-break and plain
+  spaces, and no-break and plain hyphens match each other unless `--exact`,
+  and the replacement keeps the document's characters: `"net 30"` →
+  `"net 45"` keeps its no-break space. Matches it leaves alone, like other
+  capitalization, are reported as `nearMisses`. `replace-text` and
+  `replaceText` still work, and JSON output run under `replace-text` still
+  names it.
+- **`--section` is a heading and everything under it.** `--section 8`
+  includes 8.1 and 8.2. Numbers match whether typed or Word's automatic
+  numbering. A title matches in full, or by text in only one heading; text in
+  several headings is an error (`section_ambiguous`), and a section that
+  doesn't exist is `section_not_found` instead of an empty result.
+- **Clearer flag names:** `new --content` (was `--from`), `new --page-size`
+  (was `--page`), `search --results-page` (was `--page`), and `--blocks` for
+  block ids on `read` and `replace-all` (was `--ids`). The old names still
+  work.
+- **`changes` lists header, footer, and note changes as such** ("Header",
+  "Footnote 1"), with their text.
+
+### Fixed
+
+- **Word-numbered headings.** Headings numbered by Word's heading styles, how
+  most contracts number clauses, are headings again: `outline` lists them
+  with their numbers ("8.1 Cap on liability") and `--section 8` finds them.
+- **Comparing numbered documents.** Two copies of the same numbered document
+  compare as unchanged, instead of every numbered clause deleted and
+  reinserted.
+- **Comparing against a file revise edited.** A one-word edit compares as a
+  one-word change, not a whole paragraph replaced: editing a paragraph no
+  longer adds fonts and sizes to it or its neighbors.
+- **Tracked changes in headers and footers** are saved as Word revisions, and
+  ones made in Word open as pending changes.
+- **Markdown export** numbers nested list items per level (8.1 was written
+  as "9."), and writes numbered headings as headings: `## 8.1 Cap on
+liability`.
+
 ## 3.0.1
 
 ### Fixed

package/README.md

@@ -1,119 +1,104 @@
 # revise
 
-The swiss army knife for documents. Read, edit, and redline Word documents
-from the command line or from TypeScript. Edits land as tracked changes, with
-comments, review, and undo, and untouched content is written back to the
-.docx byte for byte. Built for AI agents and the programs that run them.
+Read, edit, and redline Word documents from the command line or TypeScript.
 
-**Using a coding agent?** Paste this into it:
+```bash
+npm i -g revise  # or: npx revise <command>
+```
+
+AI agents using `revise` can edit documents several times faster. Paste this into your agent:
 
 ```text
 Read https://revise.io/skills/cli.md and follow it.
 ```
 
-## Install
+## CLI
 
 ```bash
-npm i -g revise        # or: npx revise <command>
+revise outline contract.docx                              # headings with block ranges
+revise read contract.docx 0                               # blocks as HTML, with ids
+revise replace-all contract.docx "Provider" "Northstar"  # a tracked change, saved in place
+revise replace-all contract.docx "net 30" "net 45" --author "Legal bot" --out v2.docx
+revise changes contract.docx                              # what's pending
+revise accept contract.docx --all
+revise reject contract.docx --section 8
+revise undo contract.docx
+revise compare v1.docx v2.docx --out redline.docx
+revise export contract.docx contract.pdf                  # .docx .pdf .md .html .txt
+cat notes.md | revise convert - notes.docx
 ```
 
-Node 20 or newer. No account, API key, or telemetry, and documents never
-leave your machine. Two things fetch over the network: PDF export downloads
-its fonts from revise.io, and an image you insert by URL is downloaded.
-
-## The CLI
-
-Every command names its file. Edits save the file in place.
-
 ```bash
-revise outline contract.docx                     # headings with block ranges
-revise read contract.docx 0                       # blocks as HTML, with ids
-revise replace-text contract.docx "Provider" "Northstar"   # tracked change
-revise changes contract.docx                      # what's pending
-revise reject contract.docx --section 8           # review by section
-revise export contract.docx contract.pdf          # .docx .pdf .md .html .txt
-revise compare v1.docx v2.docx --out redline.docx # redline two versions
-revise undo contract.docx
+revise tools                        # every editing tool
+revise call contract.docx set_header_footer '{"side":"footer","center":"Page {PAGE} of {PAGES}"}'
+revise status contract.docx --json  # one versioned JSON object
+revise examples                     # more
 ```
 
-`revise tools` lists the editing tools (insert, replace, move, tables,
-comments, footnotes, styles, headers and footers…) and `revise call` runs
-one with JSON input. `--author "Legal bot"` signs tracked changes, `--out
-copy.docx` saves an edit as a new file, and `-` reads or writes a pipe
-(`cat notes.md | revise convert - notes.docx`). `--json` on any command prints
-one versioned object ([contract](https://revise.io/developer/docs/revise/json)).
-`revise examples` shows more.
+[JSON output contract](https://revise.io/developer/docs/revise/json)
 
 ## Agent skills
 
-The skill teaches a coding agent the CLI: reading by block id, tracked edits,
-review, creating documents, and the `xml` escape hatch.
-
-| Agent                             | Install                                                                                           |
-| --------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Claude Code                       | `claude plugin marketplace add reviseio/skills`, then `claude plugin install revise@revise`       |
-| Codex, ChatGPT desktop            | `codex plugin marketplace add reviseio/skills`, then `codex plugin add revise@revise`             |
-| Cursor, Copilot, Windsurf, Cline… | `npx skills add reviseio/skills --skill revise`                                                   |
-| Anything else                     | `revise skill install` (into `.agents/skills` or `.claude/skills`), or `revise skill` to print it |
-
-Building a browser editor instead? The `revise-editor` skill covers
-[`@reviseio/editor`](https://www.npmjs.com/package/@reviseio/editor):
-`npx skills add reviseio/skills --skill revise-editor`.
+```bash
+claude plugin marketplace add reviseio/skills && claude plugin install revise@revise  # Claude Code
+codex plugin marketplace add reviseio/skills && codex plugin add revise@revise        # Codex
+npx skills add reviseio/skills --skill revise                                         # Cursor, Copilot, Windsurf…
+revise skill install                                                                  # anything else
+```
 
-## The library
+## Library
 
 ```ts
 import { ReviseDocument } from "revise";
 
 const doc = await ReviseDocument.open("contract.docx", { author: "Legal bot" });
-await doc.replaceText("Provider", "Northstar"); // tracked changes
+await doc.replaceAll("Provider", "Northstar");
 await doc.reject({ section: "8" });
-const { bytes, fidelity } = await doc.export({ format: "docx" });
+const { bytes } = await doc.export({ format: "docx" });
 doc.dispose();
 ```
 
-Run the editing tools with typed input, or hand them to a model:
+Give the editing tools to a model:
 
 ```ts
 import Anthropic from "@anthropic-ai/sdk";
 import { ReviseDocument, agentTools } from "revise";
 
 const doc = await ReviseDocument.open("brief.docx");
-const { tools, handle } = agentTools(doc, { provider: "anthropic" });
-const client = new Anthropic();
-// Pass `tools` to client.messages.create(); answer each tool_use block in
-// the response with `await handle(block)`, which returns its tool_result.
+const agent = agentTools(doc, { provider: "anthropic" }); // or "openai"
+const reply = await new Anthropic().messages.create({
+  model,
+  max_tokens,
+  messages,
+  tools: agent.tools,
+});
+const results = await Promise.all(
+  reply.content.filter((b) => b.type === "tool_use").map(agent.handle),
+);
+messages.push(
+  { role: "assistant", content: reply.content },
+  { role: "user", content: results },
+);
 ```
 
-### Collaboration servers
-
-Seed a sync server's room from a file, and edit or export the live room:
+Edit a live collaboration room (Y.js):
 
 ```ts
 import { ReviseDocument, seedYDoc } from "revise";
 
-// e.g. Hocuspocus onLoadDocument: safe on every connection
-await seedYDoc(room, "contract.docx");
-
+await seedYDoc(room, "contract.docx"); // safe on every connection
 const doc = await ReviseDocument.fromYDoc(room, { author: "Review bot" });
-await doc.tools.call("replace", {
-  /* ... */
-});
+await doc.replaceAll("draft", "final");
 const { bytes } = await doc.export({ format: "docx" });
 ```
 
-The browser editor for the same documents is
-[`@reviseio/editor`](https://www.npmjs.com/package/@reviseio/editor).
-
-## Docs
+## Links
 
-- [revise.io/developer/docs](https://revise.io/developer/docs)
-- [Build with AI](https://revise.io/developer/docs/build-with-ai): skills,
-  plugins, and Markdown versions of every page
-- [Changelog](https://revise.io/developer/docs/revise/changelog)
+[Docs](https://revise.io/developer/docs/revise/introduction) ·
+[Changelog](https://revise.io/developer/docs/revise/changelog) ·
+[Browser editor (`@reviseio/editor`)](https://www.npmjs.com/package/@reviseio/editor)
 
 ## License
 
-MIT. `revise` runs on [`@reviseio/engine`](https://www.npmjs.com/package/@reviseio/engine),
-Revise's document engine, which is installed with it and is free for any use,
-including commercial, under its own license.
+MIT. Runs on [`@reviseio/engine`](https://www.npmjs.com/package/@reviseio/engine),
+free for any use under its own license.