@superdoc-dev/sdk 1.0.0-alpha.1

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@superdoc-dev/sdk",
+  "version": "1.0.0-alpha.1",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "files": [
+    "src",
+    "skills"
+  ],
+  "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"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.2",
+    "typescript": "^5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/skills/editing-docx.md

@@ -0,0 +1,113 @@
+---
+name: editing-docx
+description: Session-first SuperDoc CLI workflows for querying and editing DOCX files (find, inspect, comment, replace, format, and close safely).
+---
+
+# SuperDoc Playground Skill
+
+Use this skill for manual DOCX exploration/editing in Codex CLI or Claude CLI.
+
+## Interaction Rules (Must Follow)
+
+1. Always run CLI commands in JSON mode: `--output json`.
+2. Prefer session mode: `open` once, then run commands without `<doc>`.
+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`
+   - `close --discard`
+
+## CLI Invocation
+
+Use `superdoc ...` commands.
+
+If `superdoc` is not installed in this repo environment, use:
+`bun apps/cli-alpha/src/index.ts ...`
+
+## Canonical Session Workflow
+
+1. Open a session:
+```bash
+superdoc open ./contract.docx --output json
+```
+2. Query and inspect:
+```bash
+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
+```
+3. Mutate (using target JSON from `find` results):
+```bash
+superdoc comments add --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Please clarify this clause." --output json
+superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Updated clause text" --dry-run --output json
+superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":10,"end":20}}' --text "Updated clause text" --output json
+```
+4. Verify:
+```bash
+superdoc find --type text --pattern "Updated clause text" --output json
+```
+5. Close:
+```bash
+superdoc close --save --out ./contract.reviewed.docx --output json
+```
+
+## Command Patterns (Session Mode)
+
+### Session lifecycle
+- `superdoc open <doc> [--session <id>] [--replace] --output json`
+- `superdoc status [--session <id>] --output json`
+- `superdoc session list --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 info --output json`
+- `superdoc find --type text --pattern "<text>" --output json`
+- `superdoc find --query-json '{...}' --output json`
+- `superdoc get-node --address-json '{...}' --output json`
+- `superdoc get-node-by-id --id <nodeId> [--node-type <type>] --output json`
+
+### Mutate
+- `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`
+
+### Stateless fallback
+If a command includes `<doc>` (or `--doc`), it runs statelessly for that call.
+For stateless mutate commands, provide `--out <path>`.
+
+## Target Selection Guidance
+
+- Prefer `find --type text --pattern ...` first.
+- Use `data.result.context[*].textRanges[*]` as `--target-json` for text edits/comments.
+- 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.
+
+## 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.
+
+## Collaboration (Node-Only, Optional)
+
+Use only when collaboration runtime is available in your environment.
+
+```bash
+superdoc open ./contract.docx --collaboration-json '{"providerType":"hocuspocus","url":"ws://localhost:1234","documentId":"contract-1","tokenEnv":"SUPERDOC_COLLAB_TOKEN"}' --output json
+```
+
+Notes:
+- Collaboration commands are command-scoped (connect -> sync -> operate -> disconnect).
+- Python collaboration is not supported; expect `NOT_SUPPORTED`.