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

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.0.0-alpha.2",
+  "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.2",
-    "@superdoc-dev/sdk-darwin-x64": "1.0.0-alpha.2",
-    "@superdoc-dev/sdk-linux-arm64": "1.0.0-alpha.2",
-    "@superdoc-dev/sdk-linux-x64": "1.0.0-alpha.2",
-    "@superdoc-dev/sdk-windows-x64": "1.0.0-alpha.2"
+    "@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",

package/skills/editing-docx.md

@@ -1,5 +1,5 @@
 ---
-name: editing-docx
+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).
 ---
 
@@ -130,6 +130,10 @@ For stateless mutate commands, provide `--out <path>`.
 - `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)
 

package/src/__tests__/skills.test.ts

@@ -1,6 +1,9 @@
 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, listSkills } from '../skills';
+import { getSkill, installSkill, listSkills } from '../skills';
 
 describe('listSkills', () => {
   test('returns an array of skill names', () => {
@@ -91,3 +94,73 @@ describe('getSkill', () => {
     }
   });
 });
+
+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,
+    });
+  });
+});
+