@superdoc-dev/sdk 1.0.0-alpha.9 → 1.0.0-next.67

package/dist/skills.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var os = require('node:os');
+var path = require('node:path');
+var node_url = require('node:url');
+var errors = require('./runtime/errors.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// Resolve skills directory relative to package root (works from both src/ and dist/)
+const skillsDir = path.resolve(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('skills.cjs', document.baseURI).href)))), '..', 'skills');
+const SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+const SUPPORTED_SKILL_RUNTIMES = ['claude'];
+const SUPPORTED_INSTALL_SCOPES = ['project', 'user'];
+function resolveSkillFilePath(skillName) {
+    const filePath = path.resolve(skillsDir, `${skillName}.md`);
+    const root = `${skillsDir}${path.sep}`;
+    if (!filePath.startsWith(root)) {
+        throw new errors.SuperDocCliError('Skill name resolved outside SDK skill directory.', {
+            code: 'INVALID_ARGUMENT',
+            details: { skillName },
+        });
+    }
+    return filePath;
+}
+function normalizeSkillName(name) {
+    const normalized = name.trim();
+    if (!normalized || !SKILL_NAME_RE.test(normalized)) {
+        throw new errors.SuperDocCliError('Skill name is required.', {
+            code: 'INVALID_ARGUMENT',
+            details: { name },
+        });
+    }
+    return normalized;
+}
+function listSkills() {
+    try {
+        return node_fs.readdirSync(skillsDir)
+            .filter((entry) => path.extname(entry) === '.md')
+            .map((entry) => path.basename(entry, '.md'))
+            .sort();
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Unable to enumerate SDK skills.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                skillsDir,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function getSkill(name) {
+    const normalized = normalizeSkillName(name);
+    const filePath = resolveSkillFilePath(normalized);
+    try {
+        return node_fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError?.code === 'ENOENT') {
+            let available = [];
+            try {
+                available = listSkills();
+            }
+            catch {
+                // Keep available empty
+            }
+            throw new errors.SuperDocCliError('Requested SDK skill was not found.', {
+                code: 'SKILL_NOT_FOUND',
+                details: { name: normalized, available },
+            });
+        }
+        throw new errors.SuperDocCliError('Unable to read SDK skill file.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalized,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+function installSkill(name, options = {}) {
+    const normalizedName = normalizeSkillName(name);
+    const runtime = options.runtime ?? 'claude';
+    if (!SUPPORTED_SKILL_RUNTIMES.includes(runtime)) {
+        throw new errors.SuperDocCliError('Unsupported skill runtime.', {
+            code: 'INVALID_ARGUMENT',
+            details: { runtime, supportedRuntimes: [...SUPPORTED_SKILL_RUNTIMES] },
+        });
+    }
+    const scope = options.scope ?? 'project';
+    if (!SUPPORTED_INSTALL_SCOPES.includes(scope)) {
+        throw new errors.SuperDocCliError('Unsupported skill install scope.', {
+            code: 'INVALID_ARGUMENT',
+            details: { scope, supportedScopes: [...SUPPORTED_INSTALL_SCOPES] },
+        });
+    }
+    const skillsRoot = options.targetDir !== undefined
+        ? path.resolve(options.targetDir)
+        : scope === 'user'
+            ? path.resolve(options.homeDir ?? os.homedir(), '.claude', 'skills')
+            : path.resolve(options.cwd ?? process.cwd(), '.claude', 'skills');
+    const skillFile = path.join(skillsRoot, normalizedName, 'SKILL.md');
+    const overwrite = options.overwrite ?? true;
+    const alreadyExists = node_fs.existsSync(skillFile);
+    if (!overwrite && alreadyExists) {
+        return {
+            name: normalizedName,
+            runtime,
+            scope: options.targetDir !== undefined ? 'custom' : scope,
+            path: skillFile,
+            written: false,
+            overwritten: false,
+        };
+    }
+    try {
+        const content = getSkill(name);
+        node_fs.mkdirSync(path.dirname(skillFile), { recursive: true });
+        node_fs.writeFileSync(skillFile, content, 'utf8');
+    }
+    catch (error) {
+        if (error instanceof errors.SuperDocCliError)
+            throw error;
+        throw new errors.SuperDocCliError('Unable to install SDK skill.', {
+            code: 'SKILL_IO_ERROR',
+            details: {
+                name: normalizedName,
+                runtime,
+                scope: options.targetDir !== undefined ? 'custom' : scope,
+                path: skillFile,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    return {
+        name: normalizedName,
+        runtime,
+        scope: options.targetDir !== undefined ? 'custom' : scope,
+        path: skillFile,
+        written: true,
+        overwritten: alreadyExists,
+    };
+}
+
+exports.getSkill = getSkill;
+exports.installSkill = installSkill;
+exports.listSkills = listSkills;

package/dist/tools.cjs

@@ -0,0 +1,371 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_fs = require('node:fs');
+var path = require('node:path');
+var node_url = require('node:url');
+var contract = require('./generated/contract.cjs');
+var errors = require('./runtime/errors.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// Resolve tools directory relative to package root (works from both src/ and dist/)
+const toolsDir = path.resolve(path.dirname(node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('tools.cjs', document.baseURI).href)))), '..', 'tools');
+const providerFileByName = {
+    openai: 'tools.openai.json',
+    anthropic: 'tools.anthropic.json',
+    vercel: 'tools.vercel.json',
+    generic: 'tools.generic.json',
+};
+let _policyCache = null;
+function loadPolicy() {
+    if (_policyCache)
+        return _policyCache;
+    const raw = node_fs.readFileSync(path.join(toolsDir, 'tools-policy.json'), 'utf8');
+    _policyCache = JSON.parse(raw);
+    return _policyCache;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+function isPresent(value) {
+    if (value == null)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return true;
+}
+function extractProviderToolName(tool) {
+    // Anthropic / Generic: top-level name
+    if (typeof tool.name === 'string')
+        return tool.name;
+    // OpenAI / Vercel: nested under function.name
+    if (isRecord(tool.function) && typeof tool.function.name === 'string') {
+        return tool.function.name;
+    }
+    return null;
+}
+function invalidArgument(message, details) {
+    throw new errors.SuperDocCliError(message, { code: 'INVALID_ARGUMENT', details });
+}
+async function readJson(fileName) {
+    const filePath = path.join(toolsDir, fileName);
+    let raw = '';
+    try {
+        raw = await promises.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Unable to load packaged tool artifact.', {
+            code: 'TOOLS_ASSET_NOT_FOUND',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new errors.SuperDocCliError('Packaged tool artifact is invalid JSON.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: {
+                filePath,
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function loadProviderBundle(provider) {
+    return readJson(providerFileByName[provider]);
+}
+async function loadToolNameMap() {
+    return readJson('tool-name-map.json');
+}
+async function loadCatalog() {
+    return readJson('catalog.json');
+}
+function normalizeFeatures(features) {
+    return {
+        hasTables: Boolean(features?.hasTables),
+        hasLists: Boolean(features?.hasLists),
+        hasComments: Boolean(features?.hasComments),
+        hasTrackedChanges: Boolean(features?.hasTrackedChanges),
+        isEmptyDocument: Boolean(features?.isEmptyDocument),
+    };
+}
+function stableSortByPhasePriority(entries, priorityOrder) {
+    const priority = new Map(priorityOrder.map((category, index) => [category, index]));
+    return [...entries].sort((a, b) => {
+        const aPriority = priority.get(a.category) ?? Number.MAX_SAFE_INTEGER;
+        const bPriority = priority.get(b.category) ?? Number.MAX_SAFE_INTEGER;
+        if (aPriority !== bPriority)
+            return aPriority - bPriority;
+        return a.toolName.localeCompare(b.toolName);
+    });
+}
+const OPERATION_INDEX = Object.fromEntries(Object.entries(contract.CONTRACT.operations).map(([id, op]) => [id, op]));
+function validateDispatchArgs(operationId, args) {
+    const operation = OPERATION_INDEX[operationId];
+    if (!operation) {
+        invalidArgument(`Unknown operation id ${operationId}.`);
+    }
+    // Unknown-param rejection
+    const allowedParams = new Set(operation.params.map((param) => String(param.name)));
+    for (const key of Object.keys(args)) {
+        if (!allowedParams.has(key)) {
+            invalidArgument(`Unexpected parameter ${key} for ${operationId}.`);
+        }
+    }
+    // Required-param enforcement
+    for (const param of operation.params) {
+        if ('required' in param && Boolean(param.required) && args[param.name] == null) {
+            invalidArgument(`Missing required parameter ${param.name} for ${operationId}.`);
+        }
+    }
+    // Constraint validation (CLI handles schema-level type validation authoritatively)
+    const constraints = 'constraints' in operation ? operation.constraints : undefined;
+    if (!constraints || !isRecord(constraints))
+        return;
+    const mutuallyExclusive = Array.isArray(constraints.mutuallyExclusive) ? constraints.mutuallyExclusive : [];
+    const requiresOneOf = Array.isArray(constraints.requiresOneOf) ? constraints.requiresOneOf : [];
+    const requiredWhen = Array.isArray(constraints.requiredWhen) ? constraints.requiredWhen : [];
+    for (const group of mutuallyExclusive) {
+        if (!Array.isArray(group))
+            continue;
+        const present = group.filter((name) => isPresent(args[name]));
+        if (present.length > 1) {
+            invalidArgument(`Arguments are mutually exclusive for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const group of requiresOneOf) {
+        if (!Array.isArray(group))
+            continue;
+        const hasAny = group.some((name) => isPresent(args[name]));
+        if (!hasAny) {
+            invalidArgument(`One of the following arguments is required for ${operationId}: ${group.join(', ')}`, {
+                operationId,
+                group,
+            });
+        }
+    }
+    for (const rule of requiredWhen) {
+        if (!isRecord(rule))
+            continue;
+        const whenValue = args[rule.whenParam];
+        let shouldRequire = false;
+        if (Object.prototype.hasOwnProperty.call(rule, 'equals')) {
+            shouldRequire = whenValue === rule.equals;
+        }
+        else if (Object.prototype.hasOwnProperty.call(rule, 'present')) {
+            const present = rule.present === true;
+            shouldRequire = present ? isPresent(whenValue) : !isPresent(whenValue);
+        }
+        else {
+            shouldRequire = isPresent(whenValue);
+        }
+        if (shouldRequire && !isPresent(args[rule.param])) {
+            invalidArgument(`Argument ${rule.param} is required by constraints for ${operationId}.`, {
+                operationId,
+                rule,
+            });
+        }
+    }
+}
+function resolveDocApiMethod(client, operationId) {
+    const tokens = operationId.split('.').slice(1);
+    let cursor = client.doc;
+    for (const token of tokens) {
+        if (!isRecord(cursor) || !(token in cursor)) {
+            throw new errors.SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
+                code: 'TOOL_DISPATCH_NOT_FOUND',
+                details: { operationId, token },
+            });
+        }
+        cursor = cursor[token];
+    }
+    if (typeof cursor !== 'function') {
+        throw new errors.SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
+            code: 'TOOL_DISPATCH_NOT_FOUND',
+            details: { operationId },
+        });
+    }
+    return cursor;
+}
+async function getToolCatalog(options = {}) {
+    const catalog = await loadCatalog();
+    if (!options.profile)
+        return catalog;
+    return {
+        ...catalog,
+        profiles: {
+            intent: options.profile === 'intent' ? catalog.profiles.intent : { name: 'intent', tools: [] },
+            operation: options.profile === 'operation' ? catalog.profiles.operation : { name: 'operation', tools: [] },
+        },
+    };
+}
+async function listTools(provider, options = {}) {
+    const profile = options.profile ?? 'intent';
+    const bundle = await loadProviderBundle(provider);
+    const tools = bundle.profiles[profile];
+    if (!Array.isArray(tools)) {
+        throw new errors.SuperDocCliError('Tool provider bundle is missing profile tools.', {
+            code: 'TOOLS_ASSET_INVALID',
+            details: { provider, profile },
+        });
+    }
+    return tools;
+}
+async function resolveToolOperation(toolName) {
+    const map = await loadToolNameMap();
+    return typeof map[toolName] === 'string' ? map[toolName] : null;
+}
+function inferDocumentFeatures(infoResult) {
+    if (!isRecord(infoResult)) {
+        return {
+            hasTables: false,
+            hasLists: false,
+            hasComments: false,
+            hasTrackedChanges: false,
+            isEmptyDocument: false,
+        };
+    }
+    const counts = isRecord(infoResult.counts) ? infoResult.counts : {};
+    const words = typeof counts.words === 'number' ? counts.words : 0;
+    const paragraphs = typeof counts.paragraphs === 'number' ? counts.paragraphs : 0;
+    const tables = typeof counts.tables === 'number' ? counts.tables : 0;
+    const comments = typeof counts.comments === 'number' ? counts.comments : 0;
+    const lists = typeof counts.lists === 'number' ? counts.lists : typeof counts.listItems === 'number' ? counts.listItems : 0;
+    const trackedChanges = typeof counts.trackedChanges === 'number'
+        ? counts.trackedChanges
+        : typeof counts.tracked_changes === 'number'
+            ? counts.tracked_changes
+            : 0;
+    return {
+        hasTables: tables > 0,
+        hasLists: lists > 0,
+        hasComments: comments > 0,
+        hasTrackedChanges: trackedChanges > 0,
+        isEmptyDocument: words === 0 && paragraphs <= 1,
+    };
+}
+async function chooseTools(input) {
+    const catalog = await loadCatalog();
+    const policy = loadPolicy();
+    const profile = input.profile ?? 'intent';
+    const phase = input.taskContext?.phase ?? 'read';
+    const phasePolicy = policy.phases[phase];
+    const featureMap = normalizeFeatures(input.documentFeatures);
+    const maxTools = Math.max(1, input.budget?.maxTools ?? policy.defaults.maxToolsByProfile[profile]);
+    const minReadTools = Math.max(0, input.budget?.minReadTools ?? policy.defaults.minReadTools);
+    const includeCategories = new Set(input.policy?.includeCategories ?? phasePolicy.include);
+    const excludeCategories = new Set([...(input.policy?.excludeCategories ?? []), ...phasePolicy.exclude]);
+    const allowMutatingTools = input.policy?.allowMutatingTools ?? phase === 'mutate';
+    const excluded = [];
+    const profileTools = catalog.profiles[profile].tools;
+    const indexByToolName = new Map(profileTools.map((tool) => [tool.toolName, tool]));
+    let candidates = profileTools.filter((tool) => {
+        if (tool.requiredCapabilities.some((capability) => !featureMap[capability])) {
+            excluded.push({ toolName: tool.toolName, reason: 'missing-required-capability' });
+            return false;
+        }
+        if (!allowMutatingTools && tool.mutates) {
+            excluded.push({ toolName: tool.toolName, reason: 'mutations-disabled' });
+            return false;
+        }
+        if (includeCategories.size > 0 && !includeCategories.has(tool.category)) {
+            excluded.push({ toolName: tool.toolName, reason: 'category-not-included' });
+            return false;
+        }
+        if (excludeCategories.has(tool.category)) {
+            excluded.push({ toolName: tool.toolName, reason: 'phase-category-excluded' });
+            return false;
+        }
+        return true;
+    });
+    const forceExclude = new Set(input.policy?.forceExclude ?? []);
+    candidates = candidates.filter((tool) => {
+        if (!forceExclude.has(tool.toolName))
+            return true;
+        excluded.push({ toolName: tool.toolName, reason: 'force-excluded' });
+        return false;
+    });
+    for (const forcedToolName of input.policy?.forceInclude ?? []) {
+        const forced = indexByToolName.get(forcedToolName);
+        if (!forced) {
+            excluded.push({ toolName: forcedToolName, reason: 'not-in-profile' });
+            continue;
+        }
+        candidates.push(forced);
+    }
+    candidates = [...new Map(candidates.map((tool) => [tool.toolName, tool])).values()];
+    const selected = [];
+    const foundationalIds = new Set(policy.defaults.foundationalOperationIds);
+    const foundational = candidates.filter((tool) => foundationalIds.has(tool.operationId));
+    for (const tool of foundational) {
+        if (selected.length >= minReadTools || selected.length >= maxTools)
+            break;
+        selected.push(tool);
+    }
+    const remaining = stableSortByPhasePriority(candidates.filter((tool) => !selected.some((entry) => entry.toolName === tool.toolName)), phasePolicy.priority);
+    for (const tool of remaining) {
+        if (selected.length >= maxTools) {
+            excluded.push({ toolName: tool.toolName, reason: 'budget-trim' });
+            continue;
+        }
+        selected.push(tool);
+    }
+    const bundle = await loadProviderBundle(input.provider);
+    const providerTools = Array.isArray(bundle.profiles[profile]) ? bundle.profiles[profile] : [];
+    const providerIndex = new Map(providerTools
+        .filter((tool) => isRecord(tool))
+        .map((tool) => [extractProviderToolName(tool), tool])
+        .filter((entry) => entry[0] !== null));
+    const selectedProviderTools = selected
+        .map((tool) => providerIndex.get(tool.toolName))
+        .filter((tool) => Boolean(tool));
+    return {
+        tools: selectedProviderTools,
+        selected: selected.map((tool) => ({
+            operationId: tool.operationId,
+            toolName: tool.toolName,
+            category: tool.category,
+            mutates: tool.mutates,
+            profile: tool.profile,
+        })),
+        excluded,
+        selectionMeta: {
+            profile,
+            phase,
+            maxTools,
+            minReadTools,
+            selectedCount: selected.length,
+            decisionVersion: policy.defaults.chooserDecisionVersion,
+            provider: input.provider,
+        },
+    };
+}
+async function dispatchSuperDocTool(client, toolName, args = {}, invokeOptions) {
+    const operationId = await resolveToolOperation(toolName);
+    if (!operationId) {
+        throw new errors.SuperDocCliError(`Unknown SuperDoc tool: ${toolName}`, {
+            code: 'TOOL_NOT_FOUND',
+            details: { toolName },
+        });
+    }
+    if (!isRecord(args)) {
+        invalidArgument(`Tool arguments for ${toolName} must be an object.`);
+    }
+    validateDispatchArgs(operationId, args);
+    const method = resolveDocApiMethod(client, operationId);
+    return method(args, invokeOptions);
+}
+
+exports.chooseTools = chooseTools;
+exports.dispatchSuperDocTool = dispatchSuperDocTool;
+exports.getToolCatalog = getToolCatalog;
+exports.inferDocumentFeatures = inferDocumentFeatures;
+exports.listTools = listTools;
+exports.resolveToolOperation = resolveToolOperation;

package/package.json

@@ -1,35 +1,41 @@
 {
   "name": "@superdoc-dev/sdk",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-next.67",
   "private": false,
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      }
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
     "dist",
+    "skills",
     "tools"
   ],
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "prepack": "rm -rf tools && cp -r ../../tools ./tools && rm -f ./tools/__init__.py",
-    "postpack": "rm -rf tools && ln -s ../../tools tools"
-  },
   "devDependencies": {
-    "@types/bun": "catalog:",
-    "@types/node": "catalog:",
-    "typescript": "catalog:"
+    "@types/bun": "^1.3.8",
+    "@types/node": "22.19.2",
+    "rollup": "^4.31.0",
+    "typescript": "^5.9.2"
+  },
+  "optionalDependencies": {
+    "@superdoc-dev/sdk-darwin-x64": "1.0.0-next.67",
+    "@superdoc-dev/sdk-darwin-arm64": "1.0.0-next.67",
+    "@superdoc-dev/sdk-linux-x64": "1.0.0-next.67",
+    "@superdoc-dev/sdk-windows-x64": "1.0.0-next.67",
+    "@superdoc-dev/sdk-linux-arm64": "1.0.0-next.67"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && rollup -c rollup.cjs.config.mjs",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/skills/editing-docx.md

@@ -0,0 +1,31 @@
+# Editing DOCX Documents with SuperDoc SDK
+
+You are a document editing assistant using the SuperDoc SDK. You have access to tools
+that let you open, read, search, and modify `.docx` files programmatically.
+
+## Workflow
+
+1. **Open** the document with `doc.open`
+2. **Inspect** it with `doc.info` to understand structure
+3. **Find** content with `doc.find` using text search or node type queries
+4. **Modify** content using `doc.insert`, `doc.replace`, `doc.delete`, or formatting operations
+5. **Save** changes with `doc.save`
+6. **Close** when done with `doc.close`
+
+## Key Operations
+
+- `doc.find` — Search by text pattern, node type, or structured query
+- `doc.getNode` — Get a specific node by address
+- `doc.insert` — Insert text at a position
+- `doc.replace` — Replace content at a position
+- `doc.delete` — Delete content at a position
+- `doc.format.*` — Apply bold, italic, underline, strikethrough
+- `doc.comments.*` — Add, edit, resolve, remove comments
+- `doc.trackChanges.*` — Accept/reject tracked changes
+
+## Best Practices
+
+- Always open before operating, save when done
+- Use `doc.find` to locate content before modifying
+- Use `doc.info` to check document capabilities
+- Handle errors gracefully — operations may fail if targets are invalid