@superdoc-dev/sdk 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/helpers/format.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Format helper methods for the Node SDK.
+ *
+ * These are hand-written convenience wrappers that call the canonical
+ * `format.apply` operation with pre-filled inline directives. They are NOT generated
+ * from the contract and will not be overwritten by `pnpm run generate:all`.
+ *
+ * Usage:
+ * ```ts
+ * import { createSuperDocClient } from 'superdoc';
+ * import { formatBold, unformatBold, clearBold } from 'superdoc/helpers/format';
+ *
+ * const client = createSuperDocClient();
+ * await client.connect();
+ *
+ * // Apply bold ON:
+ * await formatBold(client.doc, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
+ *
+ * // Apply explicit bold OFF (override style inheritance):
+ * await unformatBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ *
+ * // Clear direct bold formatting (inherit from style cascade):
+ * await clearBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * ```
+ */
+import type { InvokeOptions, OperationSpec } from '../runtime/transport-common.js';
+export interface FormatHelperParams {
+    doc?: string;
+    sessionId?: string;
+    target?: {
+        kind: 'text';
+        blockId: string;
+        range: {
+            start: number;
+            end: number;
+        };
+    };
+    /** Flat-flag shorthand for target.blockId (normalized before dispatch). */
+    blockId?: string;
+    /** Flat-flag shorthand for target.range.start (normalized before dispatch). */
+    start?: number;
+    /** Flat-flag shorthand for target.range.end (normalized before dispatch). */
+    end?: number;
+    dryRun?: boolean;
+    changeMode?: 'direct' | 'tracked';
+    expectedRevision?: string;
+}
+/**
+ * Generic invoke function that works with the SuperDocRuntime.
+ * The doc API proxy created by `createDocApi(runtime)` exposes generated methods,
+ * but helpers call the runtime directly for forward-compatibility.
+ */
+type RuntimeInvokeFn = <T = unknown>(operation: OperationSpec, params?: Record<string, unknown>, options?: InvokeOptions) => Promise<T>;
+/** Apply bold ON. Equivalent to `format.apply` with `inline: { bold: 'on' }`. */
+export declare function formatBold(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply italic ON. Equivalent to `format.apply` with `inline: { italic: 'on' }`. */
+export declare function formatItalic(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply underline ON. Equivalent to `format.apply` with `inline: { underline: 'on' }`. */
+export declare function formatUnderline(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply strikethrough ON. Equivalent to `format.apply` with `inline: { strike: 'on' }`. */
+export declare function formatStrikethrough(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply bold OFF. Equivalent to `format.apply` with `inline: { bold: 'off' }`. */
+export declare function unformatBold(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply italic OFF. Equivalent to `format.apply` with `inline: { italic: 'off' }`. */
+export declare function unformatItalic(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply underline OFF. Equivalent to `format.apply` with `inline: { underline: 'off' }`. */
+export declare function unformatUnderline(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Apply strikethrough OFF. Equivalent to `format.apply` with `inline: { strike: 'off' }`. */
+export declare function unformatStrikethrough(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Clear bold formatting. Equivalent to `format.apply` with `inline: { bold: 'clear' }`. */
+export declare function clearBold(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Clear italic formatting. Equivalent to `format.apply` with `inline: { italic: 'clear' }`. */
+export declare function clearItalic(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Clear underline formatting. Equivalent to `format.apply` with `inline: { underline: 'clear' }`. */
+export declare function clearUnderline(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+/** Clear strikethrough formatting. Equivalent to `format.apply` with `inline: { strike: 'clear' }`. */
+export declare function clearStrikethrough(invoke: RuntimeInvokeFn, params?: FormatHelperParams, options?: InvokeOptions): Promise<unknown>;
+export {};
+//# sourceMappingURL=format.d.ts.map

package/dist/helpers/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/helpers/format.ts"],"names":[],"mappings":"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"}

package/dist/helpers/format.js

@@ -0,0 +1,121 @@
+/**
+ * Format helper methods for the Node SDK.
+ *
+ * These are hand-written convenience wrappers that call the canonical
+ * `format.apply` operation with pre-filled inline directives. They are NOT generated
+ * from the contract and will not be overwritten by `pnpm run generate:all`.
+ *
+ * Usage:
+ * ```ts
+ * import { createSuperDocClient } from 'superdoc';
+ * import { formatBold, unformatBold, clearBold } from 'superdoc/helpers/format';
+ *
+ * const client = createSuperDocClient();
+ * await client.connect();
+ *
+ * // Apply bold ON:
+ * await formatBold(client.doc, { target: { kind: 'text', blockId: 'p1', range: { start: 0, end: 5 } } });
+ *
+ * // Apply explicit bold OFF (override style inheritance):
+ * await unformatBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ *
+ * // Clear direct bold formatting (inherit from style cascade):
+ * await clearBold(client.doc, { blockId: 'p1', start: 0, end: 5 });
+ * ```
+ */
+/**
+ * Minimal operation spec for `format.apply`. Used to invoke the canonical
+ * operation through the runtime without depending on generated code.
+ *
+ * Only canonical params are listed here. Flat-flag shortcuts (blockId,
+ * start, end) are accepted via FormatHelperParams and normalized into
+ * a `target` object before invoke.
+ */
+const FORMAT_APPLY_SPEC = {
+    operationId: 'doc.format.apply',
+    commandTokens: ['format', 'apply'],
+    params: [
+        { name: 'doc', kind: 'doc', type: 'string' },
+        { name: 'sessionId', kind: 'doc', flag: 'session', type: 'string' },
+        { name: 'target', kind: 'jsonFlag', type: 'json' },
+        { name: 'inline', kind: 'jsonFlag', type: 'json' },
+        { name: 'dryRun', kind: 'flag', type: 'boolean' },
+        { name: 'changeMode', kind: 'flag', type: 'string' },
+        { name: 'expectedRevision', kind: 'flag', type: 'string' },
+    ],
+};
+/**
+ * Normalizes flat-flag shorthand params (blockId, start, end) into a
+ * canonical `target` object. If `target` is already provided, flat flags
+ * are left untouched (the caller provided the canonical form directly).
+ */
+function normalizeFormatParams(params) {
+    const { blockId, start, end, target, ...rest } = params;
+    if (blockId !== undefined && target === undefined) {
+        return {
+            ...rest,
+            target: { kind: 'text', blockId, range: { start: start ?? 0, end: end ?? 0 } },
+        };
+    }
+    return params;
+}
+function mergeInlineStyles(params, inline) {
+    return { ...normalizeFormatParams(params), inline };
+}
+// ---------------------------------------------------------------------------
+// format* helpers — apply ON directive
+// ---------------------------------------------------------------------------
+/** Apply bold ON. Equivalent to `format.apply` with `inline: { bold: 'on' }`. */
+export function formatBold(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { bold: 'on' }), options);
+}
+/** Apply italic ON. Equivalent to `format.apply` with `inline: { italic: 'on' }`. */
+export function formatItalic(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { italic: 'on' }), options);
+}
+/** Apply underline ON. Equivalent to `format.apply` with `inline: { underline: 'on' }`. */
+export function formatUnderline(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { underline: 'on' }), options);
+}
+/** Apply strikethrough ON. Equivalent to `format.apply` with `inline: { strike: 'on' }`. */
+export function formatStrikethrough(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { strike: 'on' }), options);
+}
+// ---------------------------------------------------------------------------
+// unformat* helpers — apply explicit OFF directive (style override)
+// ---------------------------------------------------------------------------
+/** Apply bold OFF. Equivalent to `format.apply` with `inline: { bold: 'off' }`. */
+export function unformatBold(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { bold: 'off' }), options);
+}
+/** Apply italic OFF. Equivalent to `format.apply` with `inline: { italic: 'off' }`. */
+export function unformatItalic(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { italic: 'off' }), options);
+}
+/** Apply underline OFF. Equivalent to `format.apply` with `inline: { underline: 'off' }`. */
+export function unformatUnderline(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { underline: 'off' }), options);
+}
+/** Apply strikethrough OFF. Equivalent to `format.apply` with `inline: { strike: 'off' }`. */
+export function unformatStrikethrough(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { strike: 'off' }), options);
+}
+// ---------------------------------------------------------------------------
+// clear* helpers — remove direct formatting (inherit from style cascade)
+// ---------------------------------------------------------------------------
+/** Clear bold formatting. Equivalent to `format.apply` with `inline: { bold: 'clear' }`. */
+export function clearBold(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { bold: 'clear' }), options);
+}
+/** Clear italic formatting. Equivalent to `format.apply` with `inline: { italic: 'clear' }`. */
+export function clearItalic(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { italic: 'clear' }), options);
+}
+/** Clear underline formatting. Equivalent to `format.apply` with `inline: { underline: 'clear' }`. */
+export function clearUnderline(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { underline: 'clear' }), options);
+}
+/** Clear strikethrough formatting. Equivalent to `format.apply` with `inline: { strike: 'clear' }`. */
+export function clearStrikethrough(invoke, params = {}, options) {
+    return invoke(FORMAT_APPLY_SPEC, mergeInlineStyles(params, { strike: 'clear' }), options);
+}

package/dist/index.cjs

@@ -0,0 +1,45 @@
+'use strict';
+
+var client = require('./generated/client.cjs');
+var process = require('./runtime/process.cjs');
+var skills = require('./skills.cjs');
+var tools = require('./tools.cjs');
+var errors = require('./runtime/errors.cjs');
+
+/**
+ * High-level client for interacting with SuperDoc documents via the CLI.
+ *
+ * Provides a typed `doc` API for opening, querying, and mutating documents.
+ * Call {@link connect} before operations and {@link dispose} when finished
+ * to manage the host process lifecycle.
+ */
+class SuperDocClient {
+    runtime;
+    doc;
+    constructor(options = {}) {
+        this.runtime = new process.SuperDocRuntime(options);
+        this.doc = client.createDocApi(this.runtime);
+    }
+    async connect() {
+        await this.runtime.connect();
+    }
+    async dispose() {
+        await this.runtime.dispose();
+    }
+}
+function createSuperDocClient(options = {}) {
+    return new SuperDocClient(options);
+}
+
+exports.getSkill = skills.getSkill;
+exports.installSkill = skills.installSkill;
+exports.listSkills = skills.listSkills;
+exports.chooseTools = tools.chooseTools;
+exports.dispatchSuperDocTool = tools.dispatchSuperDocTool;
+exports.getAvailableGroups = tools.getAvailableGroups;
+exports.getToolCatalog = tools.getToolCatalog;
+exports.listTools = tools.listTools;
+exports.resolveToolOperation = tools.resolveToolOperation;
+exports.SuperDocCliError = errors.SuperDocCliError;
+exports.SuperDocClient = SuperDocClient;
+exports.createSuperDocClient = createSuperDocClient;

package/dist/index.d.ts

@@ -16,8 +16,8 @@ export declare class SuperDocClient {
 }
 export declare function createSuperDocClient(options?: SuperDocClientOptions): SuperDocClient;
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getToolCatalog, inferDocumentFeatures, listTools, resolveToolOperation, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getAvailableGroups, getToolCatalog, listTools, resolveToolOperation, } from './tools.js';
 export { SuperDocCliError } from './runtime/errors.js';
-export type { InvokeOptions, OperationSpec, OperationParamSpec, SuperDocClientOptions, } from './runtime/process.js';
-export type { DocumentFeatures, ToolChooserInput, ToolPhase, ToolProfile, ToolProvider, } from './tools.js';
+export type { InvokeOptions, OperationSpec, OperationParamSpec, SuperDocClientOptions } from './runtime/process.js';
+export type { ToolChooserInput, ToolChooserMode, ToolGroup, ToolProvider } from './tools.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEnF;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;gBAElC,OAAO,GAAE,qBAA0B;IAKzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAExF;AAED,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,SAAS,EACT,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EACV,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAmB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAEnF;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;gBAElC,OAAO,GAAE,qBAA0B;IAKzC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAExF;AAED,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACpH,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -25,5 +25,5 @@ export function createSuperDocClient(options = {}) {
     return new SuperDocClient(options);
 }
 export { getSkill, installSkill, listSkills } from './skills.js';
-export { chooseTools, dispatchSuperDocTool, getToolCatalog, inferDocumentFeatures, listTools, resolveToolOperation, } from './tools.js';
+export { chooseTools, dispatchSuperDocTool, getAvailableGroups, getToolCatalog, listTools, resolveToolOperation, } from './tools.js';
 export { SuperDocCliError } from './runtime/errors.js';

package/dist/runtime/embedded-cli.cjs

@@ -0,0 +1,100 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var node_module = require('node:module');
+var path = require('node:path');
+var node_url = require('node:url');
+var errors = require('./errors.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)));
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc-dev/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc-dev/sdk-darwin-x64',
+    'linux-x64': '@superdoc-dev/sdk-linux-x64',
+    'linux-arm64': '@superdoc-dev/sdk-linux-arm64',
+    'windows-x64': '@superdoc-dev/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+function resolveTarget() {
+    const platform = process.platform;
+    const arch = process.arch;
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
+}
+function ensureExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        node_fs.chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
+    }
+}
+function resolveFromPlatformPackage(target) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    const binaryName = binaryNameForTarget(target);
+    try {
+        return require$1.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveFromWorkspaceFallback(target) {
+    const binaryName = binaryNameForTarget(target);
+    const dirName = TARGET_TO_DIR[target];
+    const filePath = path.resolve(node_url.fileURLToPath(new URL('../../platforms', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)))), dirName, 'bin', binaryName);
+    if (!node_fs.existsSync(filePath))
+        return null;
+    return filePath;
+}
+/**
+ * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
+ */
+function resolveEmbeddedCliBinary() {
+    const target = resolveTarget();
+    if (!target) {
+        throw new errors.SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: {
+                platform: process.platform,
+                arch: process.arch,
+            },
+        });
+    }
+    const platformPackagePath = resolveFromPlatformPackage(target);
+    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    if (!resolvedPath) {
+        throw new errors.SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
+            code: 'CLI_BINARY_MISSING',
+            details: {
+                target,
+                packageName: TARGET_TO_PACKAGE[target],
+            },
+        });
+    }
+    ensureExecutable(resolvedPath);
+    return resolvedPath;
+}
+
+exports.resolveEmbeddedCliBinary = resolveEmbeddedCliBinary;

package/dist/runtime/errors.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * Error thrown by the SuperDoc SDK when a CLI operation fails.
+ *
+ * Includes a machine-readable `code` for programmatic error handling
+ * and optional `details` with structured diagnostic context.
+ */
+class SuperDocCliError extends Error {
+    code;
+    details;
+    exitCode;
+    constructor(message, options) {
+        super(message);
+        this.name = 'SuperDocCliError';
+        this.code = options.code;
+        this.details = options.details;
+        this.exitCode = options.exitCode;
+    }
+}
+
+exports.SuperDocCliError = SuperDocCliError;