Merge branch 'main' into stable

# Conflicts:
#	packages/superdoc/scripts/ensure-types.cjs

Author: harbournick

apps/cli/README.md

@@ -311,10 +311,11 @@ superdoc info ./contract.docx --pretty
 
 ## Input payload flags
 
-- `--query-json`, `--query-file`
-- `--address-json`, `--address-file`
-- `--target-json`, `--target-file`
-- `--at-json`, `--at-file` (for `create paragraph`)
+- `--query-json`, `--query-file` (`find`, `lists list`)
+- `--address-json`, `--address-file` (`get-node`, `lists get`)
+- `--target-json` (mutation commands — no `--target-file` counterpart; use flat flags `--block-id`/`--start`/`--end` as alternative)
+- `--input-json`, `--input-file` (`call`, `create paragraph`)
+- `--at-json`, `--at-file` (`create paragraph`)
 
 ## Stdin support
 

apps/cli/package.json

@@ -10,8 +10,11 @@
     "skill"
   ],
   "scripts": {
+    "predev": "node scripts/ensure-superdoc-build.js",
     "dev": "bun run src/index.ts",
+    "prebuild": "node scripts/ensure-superdoc-build.js",
     "build": "bun build src/index.ts --outdir dist --target node --format esm",
+    "prebuild:native": "node scripts/ensure-superdoc-build.js",
     "build:native": "bun build src/index.ts --compile --outfile dist/superdoc",
     "build:native:all": "node scripts/build-native-cli.js --all",
     "build:native:host": "node scripts/build-native-cli.js",
@@ -20,10 +23,12 @@
     "build:prepublish": "node scripts/build-and-stage.js",
     "publish:platforms": "node scripts/publish.js --tag latest",
     "publish:platforms:dry": "node scripts/publish.js --tag latest --dry-run",
+    "pretest": "node scripts/ensure-superdoc-build.js",
     "test": "NODE_ENV=test bun test",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "format": "prettier --write .",
+    "pretypecheck": "node scripts/ensure-superdoc-build.js --types",
     "typecheck": "tsc --noEmit -p tsconfig.check.json",
     "prepublishOnly": "pnpm run build",
     "release": "pnpx semantic-release",

apps/cli/scripts/build-native-cli.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { cliRoot, ensureNoUnknownFlags, getOptionalFlagValue, isDirectExecution, repoRoot } from './utils.js';
+import { ensureSuperdocBuild } from './ensure-superdoc-build.js';
 
 const cliEntry = path.join(cliRoot, 'src/index.ts');
 const cliPackagePath = path.join(cliRoot, 'package.json');
@@ -155,6 +156,7 @@ async function writeManifest(entries) {
  */
 export async function main(argv = process.argv.slice(2)) {
   ensureNoUnknownFlags(argv, allowedFlags);
+  ensureSuperdocBuild();
   const targets = resolveRequestedTargets(argv);
   const hostTarget = resolveHostTargetId();
 

apps/cli/scripts/ensure-superdoc-build.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import { ensureNoUnknownFlags, isDirectExecution, repoRoot, runCommand } from './utils.js';
+
+const allowedFlags = new Set(['--types']);
+const superdocRoot = path.join(repoRoot, 'packages/superdoc');
+
+/**
+ * Ensures the packaged `superdoc` runtime exists for CLI entrypoints that now
+ * consume `superdoc/super-editor` instead of raw `@superdoc/super-editor/*` source.
+ *
+ * `--types` performs the full published build so package type exports exist.
+ * Without it, a faster runtime-only build is sufficient for Bun execution.
+ *
+ * @param {{ includeTypes?: boolean }} [options]
+ * @returns {void}
+ */
+export function ensureSuperdocBuild(options = {}) {
+  const includeTypes = options.includeTypes === true;
+  const scriptName = includeTypes ? 'build:es' : 'build:dev';
+  const label = includeTypes ? 'Build packaged SuperDoc runtime and types' : 'Build packaged SuperDoc runtime';
+
+  runCommand('pnpm', ['--prefix', superdocRoot, 'run', scriptName], label);
+}
+
+/**
+ * CLI wrapper around {@link ensureSuperdocBuild}.
+ *
+ * @param {string[]} [argv=process.argv.slice(2)]
+ * @returns {void}
+ */
+export function main(argv = process.argv.slice(2)) {
+  ensureNoUnknownFlags(argv, allowedFlags);
+  ensureSuperdocBuild({ includeTypes: argv.includes('--types') });
+}
+
+if (isDirectExecution(import.meta.url)) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  }
+}

apps/cli/skill/SKILL.md

@@ -5,7 +5,7 @@ description: Edit, query, and transform Word documents with the SuperDoc CLI v1
 
 # SuperDoc CLI (v1)
 
-Use SuperDoc CLI for DOCX work. Prefer canonical v1 commands.
+Use SuperDoc CLI for DOCX work. Use v1 commands (canonical operations and their helper wrappers).
 Do not default to legacy commands unless explicitly needed for v0-style bulk workflows.
 
 Use `superdoc` if installed, or `npx @superdoc-dev/cli@latest` as a fallback.
@@ -28,12 +28,13 @@ Use `describe command` for per-command args and constraints.
 
 ```bash
 superdoc open ./contract.docx
-superdoc find --type text --pattern "termination"
+superdoc query match --select-json '{"type":"text","pattern":"termination"}' --require exactlyOne
 superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":11}}' --text "expiration"
 superdoc save --in-place
 superdoc close
 ```
 
+- Always use `query match` (not `find`) to discover mutation targets — it returns exact addresses with cardinality guarantees.
 - After `open`, commands run against the active/default session when `<doc>` is omitted.
 - Use `superdoc session list|set-default|save|close` for explicit session control.
 - `close` on dirty state requires `--discard` or a prior `save`.
@@ -57,28 +58,80 @@ superdoc replace ./proposal.docx \
 
 - In stateless mode (`<doc>` provided), mutating commands require `--out` unless using `--dry-run`.
 
+### Safety: preview before apply
+
+- Use `--dry-run` to preview any mutation without applying it.
+- Use `--expected-revision <n>` with stateful mutations for optimistic concurrency checks.
+
 ## Common v1 Commands
 
-- Search text/nodes: `find --type text --pattern "..."` or `find --query-json '{...}'`
-- Replace text: `replace --target-json '{...}' --text "..."`
-- Add/edit comments: `comments add|reply|edit|resolve|remove`
-- Review tracked changes: `track-changes list|accept|reject|accept-all|reject-all`
+### Query & inspect
+
+- Search/browse content: `find --type text --pattern "..."` or `find --query-json '{...}'`
+- Find mutation target: `query match --select-json '{...}' --require exactlyOne`
+- Inspect blocks: `blocks list`, `get-node`, `get-node-by-id`
 - Extract content: `get-text`, `get-markdown`, `get-html`
-- Low-level direct invoke: `call <operationId> --input-json '{...}'`
+
+### Mutate
+
+- Replace text: `replace --target-json '{...}' --text "..."`
+- Insert inline text: `insert --block-id <id> --offset <n> --value "..."`
+- Delete text/node: `delete --target-json '{...}'`
+- Delete blocks: `blocks delete`, `blocks delete-range`
+- Batch mutations: `mutations apply --steps-json '[...]' --atomic true --change-mode direct`
+- Create paragraph: `create paragraph --text "..."` (with optional `--at-json`)
+- Create heading: `create heading --input-json '{"level":<n>,"text":"..."}'`
+
+### Format
+
+- Apply formatting: `format apply --block-id <id> --start <n> --end <n> --inline-json '{"bold":true}'`
+- Shortcuts: `format bold`, `format italic`, `format underline`, `format strikethrough`
+
+### Lists
+
+- List items: `lists list`, `lists get`
+- Insert list item: `lists insert --node-id <id> --position after --text "..."`
+- Modify: `lists indent`, `lists outdent`, `lists set-level`, `lists set-type`, `lists convert-to-text`
+
+### Comments
+
+- Add/reply: `comments add`, `comments reply`
+- Read: `comments get`, `comments list`
+- Edit/resolve/move: `comments edit`, `comments resolve`, `comments move`, `comments set-internal`
+- Delete: `comments delete` (canonical) or `comments remove` (alias)
+
+### Track changes
+
+- List: `track-changes list`, `track-changes get`
+- Decide: `track-changes accept`, `track-changes reject`, `track-changes accept-all`, `track-changes reject-all`
+
+### History
+
+- `history get`, `history undo`, `history redo`
+
+### Low-level
+
+- Direct invoke: `call <operationId> --input-json '{...}'` (JSON output only — `--pretty` is not supported)
 
 ## JSON/File Payload Flags
 
-Use one of each pair (not both):
+Not all `--*-file` variants are available on every command. Use `describe command <name>` to check.
+
+Always supported alongside their `-json` counterpart (use one, not both):
+
+| Flag pair | Available on |
+|-----------|-------------|
+| `--query-json` / `--query-file` | `find`, `lists list` |
+| `--address-json` / `--address-file` | `get-node`, `lists get` |
+| `--input-json` / `--input-file` | `call`, `create paragraph` |
+| `--at-json` / `--at-file` | `create paragraph` |
 
-- `--query-json` or `--query-file`
-- `--target-json` or `--target-file`
-- `--address-json` or `--address-file`
-- `--input-json` or `--input-file` (for `call`)
+`--target-json` is widely available on mutation commands but has **no** `--target-file` counterpart. Use flat flags (`--block-id`, `--start`, `--end`) as an alternative to `--target-json`.
 
 ## Output and Global Flags
 
 - Default output is JSON envelope.
-- Use `--pretty` for human-readable output.
+- Use `--pretty` for human-readable output (not supported by `call`).
 - Global flags: `--output <json|pretty>`, `--session <id>`, `--timeout-ms <n>`.
 - `<doc>` can be `-` to read DOCX bytes from stdin.
 

apps/cli/src/__tests__/cli.test.ts

@@ -3,6 +3,7 @@ import { access, copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promis
 import { join } from 'node:path';
 import { run } from '../index';
 import { resolveListDocFixture, resolveSourceDocFixture } from './fixtures';
+import { writeListDocWithoutParaIds } from './unstable-list-fixture';
 
 type RunResult = {
   code: number;
@@ -1218,6 +1219,55 @@ describe('superdoc CLI', () => {
     expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);
   });
 
+  test('lists list/get keep list item addresses stable for docs without paraIds in stateless mode', async () => {
+    const source = join(TEST_DIR, 'lists-no-paraids-stateless.docx');
+    await writeListDocWithoutParaIds(source);
+
+    const address = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);
+
+    const getResult = await runCli(['lists', 'get', source, '--address-json', JSON.stringify(address)]);
+    expect(getResult.code).toBe(0);
+
+    const getEnvelope = parseJsonOutput<
+      SuccessEnvelope<{
+        address: ListItemAddress;
+        item: { address: ListItemAddress };
+      }>
+    >(getResult);
+    expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);
+
+    const secondAddress = await firstListItemAddress(['lists', 'list', source, '--limit', '1']);
+    expect(secondAddress.nodeId).toBe(address.nodeId);
+  });
+
+  test('lists list/get keep list item addresses stable for docs without paraIds in stateful mode', async () => {
+    const source = join(TEST_DIR, 'lists-no-paraids-stateful.docx');
+    await writeListDocWithoutParaIds(source);
+
+    try {
+      const openResult = await runCli(['open', source]);
+      expect(openResult.code).toBe(0);
+
+      const address = await firstListItemAddress(['lists', 'list', '--limit', '1']);
+
+      const getResult = await runCli(['lists', 'get', '--address-json', JSON.stringify(address)]);
+      expect(getResult.code).toBe(0);
+
+      const getEnvelope = parseJsonOutput<
+        SuccessEnvelope<{
+          address: ListItemAddress;
+          item: { address: ListItemAddress };
+        }>
+      >(getResult);
+      expect(getEnvelope.data.item.address.nodeId).toBe(address.nodeId);
+
+      const secondAddress = await firstListItemAddress(['lists', 'list', '--limit', '1']);
+      expect(secondAddress.nodeId).toBe(address.nodeId);
+    } finally {
+      await runCli(['close', '--discard']);
+    }
+  });
+
   test('lists list pretty prints list rows', async () => {
     const result = await runCli(['lists', 'list', LIST_SAMPLE_DOC, '--limit', '2', '--output', 'pretty']);
     expect(result.code).toBe(0);