@superdoc-dev/sdk 1.0.0-alpha.1 → 1.0.0-alpha.3

package/package.json

@@ -1,22 +1,24 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.3",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "files": [
     "src",
-    "skills"
+    "skills",
+    "tools"
   ],
   "optionalDependencies": {
-    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.1",
-    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.1",
-    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.1",
-    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.1",
-    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.1"
+    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-alpha.3",
+    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.3",
+    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.3",
+    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.3",
+    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.3"
   },
   "devDependencies": {
+    "@types/bun": "^1.3.8",
     "@types/node": "22.19.2",
     "typescript": "^5.9.2"
   },

package/skills/editing-docx.md

@@ -1,6 +1,6 @@
 ---
-name: editing-docx
-description: Session-first SuperDoc CLI workflows for querying and editing DOCX files (find, inspect, comment, replace, format, and close safely).
+name: superdoc
+description: Session-first SuperDoc CLI workflows for querying and editing DOCX files (find/inspect, comments lifecycle, text mutations, tracked-changes review, and close safely).
 ---
 
 # SuperDoc Playground Skill
@@ -14,9 +14,9 @@ Use this skill for manual DOCX exploration/editing in Codex CLI or Claude CLI.
 3. Treat CLI envelopes as truth (`ok`, `data`, `error`).
 4. Re-query before mutating if target addresses might be stale.
 5. If matches are ambiguous, ask user which match(es) to modify.
-6. End every workflow with an explicit close decision:
-   - `close --save --out ...`
-   - `close --save --in-place`
+6. End every workflow with an explicit persistence + close decision:
+   - `save --out ...` then `close`
+   - `save --in-place` then `close`
    - `close --discard`
 
 ## CLI Invocation
@@ -34,6 +34,8 @@ superdoc open ./contract.docx --output json
 ```
 2. Query and inspect:
 ```bash
+superdoc describe --output json
+superdoc describe command doc.find --output json
 superdoc info --output json
 superdoc find --type text --pattern "termination" --output json
 superdoc get-node --address-json '{"kind":"block","nodeType":"paragraph","nodeId":"p1"}' --output json
@@ -48,25 +50,28 @@ superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":1
 ```bash
 superdoc find --type text --pattern "Updated clause text" --output json
 ```
-5. Close:
+5. Save and close:
 ```bash
-superdoc close --save --out ./contract.reviewed.docx --output json
+superdoc save --out ./contract.reviewed.docx --output json
+superdoc close --output json
 ```
 
 ## Command Patterns (Session Mode)
 
 ### Session lifecycle
-- `superdoc open <doc> [--session <id>] [--replace] --output json`
+- `superdoc open <doc> [--session <id>] --output json`
 - `superdoc status [--session <id>] --output json`
+- `superdoc save [--in-place] [--out <path>] [--force] --output json`
+- `superdoc close [--discard] --output json`
 - `superdoc session list --output json`
+- `superdoc session save <id> [--in-place] [--out <path>] [--force] --output json`
 - `superdoc session use <id> --output json`
 - `superdoc session set-default <id> --output json`
 - `superdoc session close <id> --discard --output json`
-- `superdoc close --save --in-place --output json`
-- `superdoc close --save --out <path> --output json`
-- `superdoc close --discard --output json`
 
 ### Query
+- `superdoc describe --output json`
+- `superdoc describe command <operationId> --output json`
 - `superdoc info --output json`
 - `superdoc find --type text --pattern "<text>" --output json`
 - `superdoc find --query-json '{...}' --output json`
@@ -74,9 +79,33 @@ superdoc close --save --out ./contract.reviewed.docx --output json
 - `superdoc get-node-by-id --id <nodeId> [--node-type <type>] --output json`
 
 ### Mutate
+- `superdoc create paragraph [--input-json '{...}'] [--text "..."] [--at document-start|document-end] [--before-address-json '{...}'] [--after-address-json '{...}'] [--dry-run] [--change-mode direct|tracked] --output json`
 - `superdoc comments add --target-json '{...}' --text "..." --output json`
-- `superdoc replace --target-json '{...}' --text "..." [--dry-run] --output json`
-- `superdoc format bold --target-json '{...}' [--dry-run] --output json`
+- `superdoc comments edit --id <commentId> --text "..." [--expected-revision <n>] [--force] --output json`
+- `superdoc comments reply --parent-id <commentId> --text "..." [--expected-revision <n>] [--force] --output json`
+- `superdoc comments move --id <commentId> --target-json '{...}' [--expected-revision <n>] [--force] --output json`
+- `superdoc comments resolve --id <commentId> [--expected-revision <n>] [--force] --output json`
+- `superdoc comments remove --id <commentId> [--expected-revision <n>] [--force] --output json`
+- `superdoc comments set-internal --id <commentId> --is-internal <true|false> [--expected-revision <n>] [--force] --output json`
+- `superdoc insert [--target-json '{...}'] --text "..." [--dry-run] [--change-mode direct|tracked] --output json`
+- `superdoc replace --target-json '{...}' --text "..." [--dry-run] [--change-mode direct|tracked] --output json`
+- `superdoc delete --target-json '{...}' [--dry-run] [--change-mode direct|tracked] --output json`
+- `superdoc format bold --target-json '{...}' [--dry-run] [--change-mode direct|tracked] --output json`
+
+### Comments read/navigation
+- `superdoc comments get --id <commentId> --output json`
+- `superdoc comments list [--include-resolved <true|false>] --output json`
+- `superdoc comments set-active --id <commentId> --output json`
+- `superdoc comments set-active --clear --output json`
+- `superdoc comments go-to --id <commentId> --output json`
+
+### Track changes
+- `superdoc track-changes list [--type insert|delete|format] [--limit <n>] [--offset <n>] --output json`
+- `superdoc track-changes get --id <trackedChangeId> --output json`
+- `superdoc track-changes accept --id <trackedChangeId> [--expected-revision <n>] [--force] --output json`
+- `superdoc track-changes reject --id <trackedChangeId> [--expected-revision <n>] [--force] --output json`
+- `superdoc track-changes accept-all [--expected-revision <n>] [--force] --output json`
+- `superdoc track-changes reject-all [--expected-revision <n>] [--force] --output json`
 
 ### Stateless fallback
 If a command includes `<doc>` (or `--doc`), it runs statelessly for that call.
@@ -84,21 +113,36 @@ For stateless mutate commands, provide `--out <path>`.
 
 ## Target Selection Guidance
 
+- Prefer structural creation for new block insertion:
+  - `create paragraph` creates a new paragraph block and returns structural handles (`paragraph`, `insertionPoint`).
 - Prefer `find --type text --pattern ...` first.
 - Use `data.result.context[*].textRanges[*]` as `--target-json` for text edits/comments.
+- `insert` may omit `--target-json`; it defaults to the first editable insertion point (first paragraph start when available).
 - When multiple matches exist, apply a deterministic policy:
   - first match only, or
   - first N matches, or
   - user-selected match indexes.
 - For uncertain targets, run `get-node` before mutate.
 
+## Mutation Mode Guidance
+
+- Use `--change-mode direct|tracked` to control whether edits create tracked changes.
+- `create paragraph` supports `--change-mode tracked` for tracked structural creation.
+- `replace`, `insert`, `delete`, and `format bold` support `--change-mode tracked`.
+- `track-changes *` commands are for review lifecycle (list/get/accept/reject), not content insertion.
+- Deterministic tracked-change outcomes:
+  - unknown/stale ids -> `TRACK_CHANGE_NOT_FOUND`
+  - no applicable `accept-all`/`reject-all` change -> `NO_OP` receipt
+  - missing tracking capability -> `TRACK_CHANGE_COMMAND_UNAVAILABLE`
+
 ## Scenario Prompts (Copy/Paste)
 
 1. Open `./contracts/msa.docx`, find `termination`, add comments to the first 2 matches asking for clearer notice period, then save to `./contracts/msa.reviewed.docx`.
 2. Use the active session to find `governing law`, inspect the top match node, then add a concise legal-risk comment.
 3. Open two sessions (`vendor-a`, `vendor-b`) on different docs, switch between them, and add one comment in each.
 4. Run a redline pass replacing `shall` with `must` for the first 3 matches: dry-run first, then apply.
-5. Open from stdin (`open -`), run `find`, add one comment, then close and save to a chosen output path.
+5. Run `track-changes list`, inspect one change with `track-changes get`, then accept it by id.
+6. Open from stdin (`open -`), run `find`, add one comment, then `save --out` and `close`.
 
 ## Collaboration (Node-Only, Optional)
 

package/src/__tests__/skills.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { SuperDocCliError } from '../runtime/errors';
+import { getSkill, installSkill, listSkills } from '../skills';
+
+describe('listSkills', () => {
+  test('returns an array of skill names', () => {
+    const skills = listSkills();
+    expect(Array.isArray(skills)).toBe(true);
+    expect(skills.length).toBeGreaterThan(0);
+  });
+
+  test('includes the editing-docx skill', () => {
+    const skills = listSkills();
+    expect(skills).toContain('editing-docx');
+  });
+
+  test('returns sorted results', () => {
+    const skills = listSkills();
+    const sorted = [...skills].sort();
+    expect(skills).toEqual(sorted);
+  });
+
+  test('does not include file extensions', () => {
+    const skills = listSkills();
+    for (const name of skills) {
+      expect(name).not.toContain('.md');
+    }
+  });
+});
+
+describe('getSkill', () => {
+  test('returns content for a valid skill name', () => {
+    const content = getSkill('editing-docx');
+    expect(typeof content).toBe('string');
+    expect(content.length).toBeGreaterThan(0);
+  });
+
+  test('throws INVALID_ARGUMENT for empty name', () => {
+    expect(() => getSkill('')).toThrow(SuperDocCliError);
+    try {
+      getSkill('');
+    } catch (error) {
+      expect((error as SuperDocCliError).code).toBe('INVALID_ARGUMENT');
+    }
+  });
+
+  test('throws INVALID_ARGUMENT for whitespace-only name', () => {
+    expect(() => getSkill('   ')).toThrow(SuperDocCliError);
+    try {
+      getSkill('   ');
+    } catch (error) {
+      expect((error as SuperDocCliError).code).toBe('INVALID_ARGUMENT');
+    }
+  });
+
+  test('throws INVALID_ARGUMENT for names with path traversal characters', () => {
+    const maliciousNames = ['../etc/passwd', './local', 'foo/bar', 'a b c', 'skill.md'];
+
+    for (const name of maliciousNames) {
+      expect(() => getSkill(name)).toThrow(SuperDocCliError);
+      try {
+        getSkill(name);
+      } catch (error) {
+        expect((error as SuperDocCliError).code).toBe('INVALID_ARGUMENT');
+      }
+    }
+  });
+
+  test('throws SKILL_NOT_FOUND for nonexistent skill', () => {
+    expect(() => getSkill('nonexistent-skill-name-xyz')).toThrow(SuperDocCliError);
+    try {
+      getSkill('nonexistent-skill-name-xyz');
+    } catch (error) {
+      const sdError = error as SuperDocCliError;
+      expect(sdError.code).toBe('SKILL_NOT_FOUND');
+      expect((sdError.details as { available: string[] }).available).toContain('editing-docx');
+    }
+  });
+
+  test('accepts valid skill names with hyphens and underscores', () => {
+    // These should not throw INVALID_ARGUMENT (they may throw SKILL_NOT_FOUND)
+    const validNames = ['a', 'my-skill', 'my_skill', 'Skill1', '1skill'];
+
+    for (const name of validNames) {
+      try {
+        getSkill(name);
+      } catch (error) {
+        // SKILL_NOT_FOUND is expected; INVALID_ARGUMENT means the regex is wrong
+        expect((error as SuperDocCliError).code).not.toBe('INVALID_ARGUMENT');
+      }
+    }
+  });
+});
+
+describe('installSkill', () => {
+  test('installs bundled skill to Claude project skills directory', async () => {
+    const workdir = await mkdtemp(path.join(tmpdir(), 'superdoc-sdk-skills-project-'));
+    try {
+      const result = installSkill('editing-docx', { cwd: workdir });
+      const expectedPath = path.join(workdir, '.claude', 'skills', 'editing-docx', 'SKILL.md');
+      const content = await readFile(expectedPath, 'utf8');
+
+      expect(result.path).toBe(expectedPath);
+      expect(result.scope).toBe('project');
+      expect(result.written).toBe(true);
+      expect(result.overwritten).toBe(false);
+      expect(content).toContain('superdoc open');
+    } finally {
+      await rm(workdir, { recursive: true, force: true });
+    }
+  });
+
+  test('installs bundled skill to Claude user skills directory', async () => {
+    const homeDir = await mkdtemp(path.join(tmpdir(), 'superdoc-sdk-skills-user-'));
+    try {
+      const result = installSkill('editing-docx', { scope: 'user', homeDir });
+      const expectedPath = path.join(homeDir, '.claude', 'skills', 'editing-docx', 'SKILL.md');
+      const content = await readFile(expectedPath, 'utf8');
+
+      expect(result.path).toBe(expectedPath);
+      expect(result.scope).toBe('user');
+      expect(result.written).toBe(true);
+      expect(result.overwritten).toBe(false);
+      expect(content).toContain('superdoc open');
+    } finally {
+      await rm(homeDir, { recursive: true, force: true });
+    }
+  });
+
+  test('returns without writing when overwrite is false and target exists', async () => {
+    const workdir = await mkdtemp(path.join(tmpdir(), 'superdoc-sdk-skills-no-overwrite-'));
+    const skillFile = path.join(workdir, '.claude', 'skills', 'editing-docx', 'SKILL.md');
+    try {
+      await mkdir(path.dirname(skillFile), { recursive: true });
+      await writeFile(skillFile, 'custom-content', 'utf8');
+      const result = installSkill('editing-docx', { cwd: workdir, overwrite: false });
+      const content = await readFile(skillFile, 'utf8');
+
+      expect(result.written).toBe(false);
+      expect(result.overwritten).toBe(false);
+      expect(content).toBe('custom-content');
+    } finally {
+      await rm(workdir, { recursive: true, force: true });
+    }
+  });
+
+  test('overwrites existing target by default', async () => {
+    const workdir = await mkdtemp(path.join(tmpdir(), 'superdoc-sdk-skills-overwrite-'));
+    const skillFile = path.join(workdir, '.claude', 'skills', 'editing-docx', 'SKILL.md');
+    try {
+      await mkdir(path.dirname(skillFile), { recursive: true });
+      await writeFile(skillFile, 'old-content', 'utf8');
+      const result = installSkill('editing-docx', { cwd: workdir });
+      const content = await readFile(skillFile, 'utf8');
+
+      expect(result.written).toBe(true);
+      expect(result.overwritten).toBe(true);
+      expect(content).toContain('superdoc open');
+    } finally {
+      await rm(workdir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/tools.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from 'bun:test';
+import { dispatchSuperDocTool, resolveToolOperation } from '../tools';
+import { SuperDocCliError } from '../runtime/errors';
+
+describe('tools dispatch constraints', () => {
+  test('intent tool name resolves to doc.find operation', async () => {
+    const operationId = await resolveToolOperation('find_content');
+    expect(operationId).toBe('doc.find');
+  });
+
+  test('enforces requiresOneOf for doc.find (type | query)', async () => {
+    const client = {
+      doc: {
+        find: async () => ({ ok: true }),
+      },
+    };
+
+    try {
+      await dispatchSuperDocTool(client, 'find_content', {});
+      throw new Error('Expected dispatch to fail.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SuperDocCliError);
+      const cliError = error as SuperDocCliError;
+      expect(cliError.code).toBe('INVALID_ARGUMENT');
+      expect(cliError.message).toContain('One of the following arguments is required');
+    }
+  });
+
+  test('enforces mutuallyExclusive constraints for doc.find query + flat flags', async () => {
+    let called = false;
+    const client = {
+      doc: {
+        find: async () => {
+          called = true;
+          return { ok: true };
+        },
+      },
+    };
+
+    try {
+      await dispatchSuperDocTool(client, 'find_content', {
+        query: { select: { type: 'text', pattern: 'Wilde' } },
+        type: 'text',
+      });
+      throw new Error('Expected dispatch to fail.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SuperDocCliError);
+      const cliError = error as SuperDocCliError;
+      expect(cliError.code).toBe('INVALID_ARGUMENT');
+      expect(cliError.message).toContain('mutually exclusive');
+      expect(called).toBe(false);
+    }
+  });
+
+  test('enforces requiredWhen for doc.find text selectors', async () => {
+    const client = {
+      doc: {
+        find: async () => ({ ok: true }),
+      },
+    };
+
+    try {
+      await dispatchSuperDocTool(client, 'find_content', {
+        type: 'text',
+      });
+      throw new Error('Expected dispatch to fail.');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SuperDocCliError);
+      const cliError = error as SuperDocCliError;
+      expect(cliError.code).toBe('INVALID_ARGUMENT');
+      expect(cliError.message).toContain('required by constraints');
+    }
+  });
+
+  test('dispatches when constraints are satisfied', async () => {
+    const client = {
+      doc: {
+        find: async (args: Record<string, unknown>) => ({
+          ok: true,
+          query: args,
+        }),
+      },
+    };
+
+    const result = await dispatchSuperDocTool(client, 'find_content', {
+      query: {
+        select: { type: 'text', pattern: 'Wilde' },
+      },
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+    });
+  });
+});
+