@superdoc/sdk 2.4.1 → 2.6.0

package/dist/generated/client.d.ts

@@ -3065,6 +3065,7 @@ export interface DocBlocksListParams {
     limit?: number;
     nodeTypes?: Array<"paragraph" | "heading" | "listItem" | "table" | "tableRow" | "tableCell" | "tableOfContents" | "image" | "sdt">;
     includeText?: boolean;
+    reviewMode?: string;
 }
 export interface DocBlocksDeleteParams {
     doc?: string;
@@ -17345,6 +17346,7 @@ export interface DocListsSetLevelNumberingParams {
     numFmt?: string;
     lvlText?: string;
     start?: number;
+    isLgl?: boolean;
     input?: Record<string, unknown> | unknown[];
 }
 export interface DocListsSetLevelBulletParams {
@@ -37454,6 +37456,7 @@ export type DocBlocksListResult = {
         ref?: string;
     }>;
     revision: string;
+    reviewMode: "final" | "original" | "redline";
 };
 export type DocBlocksDeleteResult = {
     success: true;
@@ -117209,6 +117212,7 @@ export interface DocBlocksListBoundParams {
     limit?: number;
     nodeTypes?: Array<"paragraph" | "heading" | "listItem" | "table" | "tableRow" | "tableCell" | "tableOfContents" | "image" | "sdt">;
     includeText?: boolean;
+    reviewMode?: string;
 }
 export interface DocBlocksDeleteBoundParams {
     out?: string;
@@ -131245,6 +131249,7 @@ export interface DocListsSetLevelNumberingBoundParams {
     numFmt?: string;
     lvlText?: string;
     start?: number;
+    isLgl?: boolean;
     input?: Record<string, unknown> | unknown[];
 }
 export interface DocListsSetLevelBulletBoundParams {

package/dist/generated/contract.cjs

@@ -24279,7 +24279,7 @@ const CONTRACT = {
                 "list"
             ],
             "category": "core",
-            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.",
+            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, single-story scoping via `in: <StoryLocator>`, and final/original/redline projection of numbering metadata without changing block membership.",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -24539,6 +24539,25 @@ const CONTRACT = {
                     "type": "boolean",
                     "flag": "include-text",
                     "description": "When true, includes the full flattened block text in each block entry."
+                },
+                {
+                    "name": "reviewMode",
+                    "kind": "flag",
+                    "type": "string",
+                    "flag": "review-mode",
+                    "schema": {
+                        "oneOf": [
+                            {
+                                "const": "final"
+                            },
+                            {
+                                "const": "original"
+                            },
+                            {
+                                "const": "redline"
+                            }
+                        ]
+                    }
                 }
             ],
             "constraints": null,
@@ -24582,6 +24601,9 @@ const CONTRACT = {
                     "includeText": {
                         "type": "boolean",
                         "description": "When true, includes the full flattened block text in each block entry."
+                    },
+                    "reviewMode": {
+                        "$ref": "#/$defs/SDProjectionReviewMode"
                     }
                 },
                 "additionalProperties": false
@@ -24730,13 +24752,17 @@ const CONTRACT = {
                     },
                     "revision": {
                         "type": "string"
+                    },
+                    "reviewMode": {
+                        "$ref": "#/$defs/SDProjectionReviewMode"
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "total",
                     "blocks",
-                    "revision"
+                    "revision",
+                    "reviewMode"
                 ]
             },
             "intentGroup": "get_content",
@@ -138369,7 +138395,7 @@ const CONTRACT = {
                 "set-level-numbering"
             ],
             "category": "lists",
-            "description": "Advanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, and start in one call (abstract-scoped, no clone-on-write).",
+            "description": "Advanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, start, and legal numbering in one call (abstract-scoped, no clone-on-write).",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -138645,6 +138671,12 @@ const CONTRACT = {
                     "kind": "flag",
                     "type": "number"
                 },
+                {
+                    "name": "isLgl",
+                    "kind": "flag",
+                    "type": "boolean",
+                    "flag": "is-lgl"
+                },
                 {
                     "name": "input",
                     "kind": "jsonFlag",
@@ -138677,6 +138709,9 @@ const CONTRACT = {
                     },
                     "start": {
                         "type": "integer"
+                    },
+                    "isLgl": {
+                        "type": "boolean"
                     }
                 },
                 "additionalProperties": false,

package/dist/generated/contract.js

@@ -2901,6 +2901,10 @@ export const CONTRACT = {
         "transport": "stdio",
         "features": [
             "cli.invoke",
+            "document.open",
+            "document.invoke",
+            "document.save",
+            "document.close",
             "host.shutdown",
             "host.describe",
             "host.describe.command"
@@ -27186,7 +27190,7 @@ export const CONTRACT = {
                 "list"
             ],
             "category": "core",
-            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, and single-story scoping via `in: <StoryLocator>`.",
+            "description": "List top-level blocks in document order with IDs, types, text previews, and optional full text when includeText:true. Supports pagination via offset/limit, optional nodeType filtering, single-story scoping via `in: <StoryLocator>`, and final/original/redline projection of numbering metadata without changing block membership.",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -27446,6 +27450,25 @@ export const CONTRACT = {
                     "type": "boolean",
                     "flag": "include-text",
                     "description": "When true, includes the full flattened block text in each block entry."
+                },
+                {
+                    "name": "reviewMode",
+                    "kind": "flag",
+                    "type": "string",
+                    "flag": "review-mode",
+                    "schema": {
+                        "oneOf": [
+                            {
+                                "const": "final"
+                            },
+                            {
+                                "const": "original"
+                            },
+                            {
+                                "const": "redline"
+                            }
+                        ]
+                    }
                 }
             ],
             "constraints": null,
@@ -27489,6 +27512,9 @@ export const CONTRACT = {
                     "includeText": {
                         "type": "boolean",
                         "description": "When true, includes the full flattened block text in each block entry."
+                    },
+                    "reviewMode": {
+                        "$ref": "#/$defs/SDProjectionReviewMode"
                     }
                 },
                 "additionalProperties": false
@@ -27637,13 +27663,17 @@ export const CONTRACT = {
                     },
                     "revision": {
                         "type": "string"
+                    },
+                    "reviewMode": {
+                        "$ref": "#/$defs/SDProjectionReviewMode"
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "total",
                     "blocks",
-                    "revision"
+                    "revision",
+                    "reviewMode"
                 ]
             },
             "intentGroup": "get_content",
@@ -141276,7 +141306,7 @@ export const CONTRACT = {
                 "set-level-numbering"
             ],
             "category": "lists",
-            "description": "Advanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, and start in one call (abstract-scoped, no clone-on-write).",
+            "description": "Advanced alias for lists.setLevelNumberStyle/setLevelText/setLevelStart. Set format, pattern, start, and legal numbering in one call (abstract-scoped, no clone-on-write).",
             "requiresDocumentContext": true,
             "docRequirement": "optional",
             "responseEnvelopeKey": "result",
@@ -141552,6 +141582,12 @@ export const CONTRACT = {
                     "kind": "flag",
                     "type": "number"
                 },
+                {
+                    "name": "isLgl",
+                    "kind": "flag",
+                    "type": "boolean",
+                    "flag": "is-lgl"
+                },
                 {
                     "name": "input",
                     "kind": "jsonFlag",
@@ -141584,6 +141620,9 @@ export const CONTRACT = {
                     },
                     "start": {
                         "type": "integer"
+                    },
+                    "isLgl": {
+                        "type": "boolean"
                     }
                 },
                 "additionalProperties": false,

package/dist/runtime/document-rpc.cjs

@@ -0,0 +1,189 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+var errors = require('./errors.cjs');
+
+const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+const DOCUMENT_RPC_V0_OPERATIONS = new Set(['doc.getText', 'doc.insert', 'doc.save', 'doc.close']);
+const DOCUMENT_RPC_OPEN_FIELDS = new Set(['doc', 'sessionId', 'runtime']);
+const DOCUMENT_RPC_INSERT_FIELDS = new Set([
+    'value',
+    'type',
+    'target',
+    'ref',
+    'in',
+    'placement',
+    'content',
+    'nestingPolicy',
+]);
+function unsupported(message, operationId) {
+    return new errors.SuperDocCliError(message, {
+        code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+        ...(operationId === undefined ? {} : { details: { operationId } }),
+    });
+}
+function documentRpcEnabled(env) {
+    return (env?.SUPERDOC_SDK_DOCUMENT_RPC ?? process.env.SUPERDOC_SDK_DOCUMENT_RPC) === '1';
+}
+function supportsDocumentRpc(features) {
+    return DOCUMENT_RPC_FEATURES.every((feature) => features.has(feature));
+}
+function hasUnsupportedInvokeOptions(options) {
+    return (options.stdinBytes !== undefined ||
+        options.dryRun !== undefined ||
+        options.expectedRevision !== undefined ||
+        options.changeMode !== undefined);
+}
+function canOpenWithDocumentRpc(params, options) {
+    if (hasUnsupportedInvokeOptions(options))
+        return false;
+    if (typeof params.doc !== 'string' || params.doc.trim().length === 0 || params.doc === '-')
+        return false;
+    if (params.runtime !== undefined && params.runtime !== 'v2')
+        return false;
+    if (params.sessionId !== undefined && (typeof params.sessionId !== 'string' || params.sessionId.length === 0)) {
+        return false;
+    }
+    return Object.entries(params).every(([key, value]) => value === undefined || DOCUMENT_RPC_OPEN_FIELDS.has(key));
+}
+function buildDocumentOpenParams(params) {
+    const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : node_crypto.randomUUID();
+    return {
+        sessionId,
+        params: { sessionId, path: params.doc },
+    };
+}
+function mapDocumentOpenResult(response, sessionId, path) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new errors.SuperDocCliError('Host returned invalid document.open result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId || typeof record.byteLength !== 'number') {
+        throw new errors.SuperDocCliError('Host returned invalid document.open session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        active: true,
+        contextId: sessionId,
+        runtime: 'v2',
+        sessionType: 'local',
+        document: { path, source: 'path', byteLength: record.byteLength, revision: 0 },
+        dirty: false,
+    };
+}
+function documentInvokeInput(operationId, params) {
+    const allowedFields = operationId === 'doc.getText' ? new Set(['in']) : DOCUMENT_RPC_INSERT_FIELDS;
+    const input = Object.fromEntries(Object.entries(params).filter(([key, value]) => value !== undefined && key !== 'doc' && key !== 'sessionId'));
+    const unsupportedField = Object.keys(input).find((key) => !allowedFields.has(key));
+    if (unsupportedField) {
+        throw unsupported(`Structured document RPC v0 does not support ${operationId} field ${unsupportedField}.`, operationId);
+    }
+    return input;
+}
+function buildDocumentInvokeParams(sessionId, operation, params, options) {
+    if (!DOCUMENT_RPC_V0_OPERATIONS.has(operation.operationId)) {
+        throw unsupported(`Structured document RPC does not support ${operation.operationId} in v0.`, operation.operationId);
+    }
+    if (hasUnsupportedInvokeOptions(options)) {
+        throw unsupported('Structured document RPC v0 does not support document mutation options.', operation.operationId);
+    }
+    if (operation.operationId === 'doc.save') {
+        if (params.inPlace === true || typeof params.out !== 'string' || params.out.length === 0) {
+            throw unsupported('Structured document RPC v0 requires doc.save({ out }) and does not support inPlace.', operation.operationId);
+        }
+        return {
+            method: 'document.save',
+            params: {
+                sessionId,
+                path: params.out,
+                overwrite: params.force === true,
+                ...(params.mode === undefined ? {} : { mode: params.mode }),
+            },
+        };
+    }
+    if (operation.operationId === 'doc.close') {
+        return {
+            method: 'document.close',
+            params: {
+                sessionId,
+                ...(params.discard === undefined ? {} : { discard: params.discard }),
+            },
+        };
+    }
+    return {
+        method: 'document.invoke',
+        params: {
+            sessionId,
+            operationId: operation.operationId.slice('doc.'.length),
+            input: documentInvokeInput(operation.operationId, params),
+        },
+    };
+}
+function mapDocumentLifecycleResult(operationId, response, sessionId) {
+    if (operationId !== 'doc.save' && operationId !== 'doc.close')
+        return response;
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new errors.SuperDocCliError(`Host returned invalid ${operationId.slice('doc.'.length)} result.`, {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId) {
+        throw new errors.SuperDocCliError('Host returned a result for the wrong document session.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    if (operationId === 'doc.close') {
+        if (record.closed !== true || typeof record.discarded !== 'boolean') {
+            throw new errors.SuperDocCliError('Host returned invalid document.close result.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { result: response },
+            });
+        }
+        return {
+            contextId: sessionId,
+            runtime: 'v2',
+            closed: true,
+            saved: false,
+            discarded: record.discarded,
+            defaultSessionCleared: false,
+        };
+    }
+    const output = record.output;
+    if (record.saved !== true ||
+        typeof output !== 'object' ||
+        output == null ||
+        Array.isArray(output) ||
+        typeof output.path !== 'string' ||
+        typeof output.byteLength !== 'number') {
+        throw new errors.SuperDocCliError('Host returned invalid document.save result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        saved: true,
+        inPlace: false,
+        mode: record.mode,
+        output,
+        report: record.report,
+    };
+}
+
+exports.DOCUMENT_RPC_FEATURES = DOCUMENT_RPC_FEATURES;
+exports.buildDocumentInvokeParams = buildDocumentInvokeParams;
+exports.buildDocumentOpenParams = buildDocumentOpenParams;
+exports.canOpenWithDocumentRpc = canOpenWithDocumentRpc;
+exports.documentRpcEnabled = documentRpcEnabled;
+exports.mapDocumentLifecycleResult = mapDocumentLifecycleResult;
+exports.mapDocumentOpenResult = mapDocumentOpenResult;
+exports.supportsDocumentRpc = supportsDocumentRpc;

package/dist/runtime/document-rpc.d.ts

@@ -0,0 +1,15 @@
+import type { InvokeOptions, OperationSpec } from './transport-common.js';
+export declare const DOCUMENT_RPC_FEATURES: readonly ["document.open", "document.invoke", "document.save", "document.close"];
+export declare function documentRpcEnabled(env: Record<string, string | undefined> | undefined): boolean;
+export declare function supportsDocumentRpc(features: ReadonlySet<string>): boolean;
+export declare function canOpenWithDocumentRpc(params: Record<string, unknown>, options: InvokeOptions): boolean;
+export declare function buildDocumentOpenParams(params: Record<string, unknown>): {
+    readonly sessionId: string;
+    readonly params: Record<string, unknown>;
+};
+export declare function mapDocumentOpenResult(response: unknown, sessionId: string, path: string): Record<string, unknown>;
+export declare function buildDocumentInvokeParams(sessionId: string, operation: OperationSpec, params: Record<string, unknown>, options: InvokeOptions): {
+    readonly method: string;
+    readonly params: Record<string, unknown>;
+};
+export declare function mapDocumentLifecycleResult(operationId: string, response: unknown, sessionId: string): unknown;

package/dist/runtime/document-rpc.js

@@ -0,0 +1,177 @@
+import { randomUUID } from 'node:crypto';
+import { SuperDocCliError } from './errors.js';
+export const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+const DOCUMENT_RPC_V0_OPERATIONS = new Set(['doc.getText', 'doc.insert', 'doc.save', 'doc.close']);
+const DOCUMENT_RPC_OPEN_FIELDS = new Set(['doc', 'sessionId', 'runtime']);
+const DOCUMENT_RPC_INSERT_FIELDS = new Set([
+    'value',
+    'type',
+    'target',
+    'ref',
+    'in',
+    'placement',
+    'content',
+    'nestingPolicy',
+]);
+function unsupported(message, operationId) {
+    return new SuperDocCliError(message, {
+        code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+        ...(operationId === undefined ? {} : { details: { operationId } }),
+    });
+}
+export function documentRpcEnabled(env) {
+    return (env?.SUPERDOC_SDK_DOCUMENT_RPC ?? process.env.SUPERDOC_SDK_DOCUMENT_RPC) === '1';
+}
+export function supportsDocumentRpc(features) {
+    return DOCUMENT_RPC_FEATURES.every((feature) => features.has(feature));
+}
+function hasUnsupportedInvokeOptions(options) {
+    return (options.stdinBytes !== undefined ||
+        options.dryRun !== undefined ||
+        options.expectedRevision !== undefined ||
+        options.changeMode !== undefined);
+}
+export function canOpenWithDocumentRpc(params, options) {
+    if (hasUnsupportedInvokeOptions(options))
+        return false;
+    if (typeof params.doc !== 'string' || params.doc.trim().length === 0 || params.doc === '-')
+        return false;
+    if (params.runtime !== undefined && params.runtime !== 'v2')
+        return false;
+    if (params.sessionId !== undefined && (typeof params.sessionId !== 'string' || params.sessionId.length === 0)) {
+        return false;
+    }
+    return Object.entries(params).every(([key, value]) => value === undefined || DOCUMENT_RPC_OPEN_FIELDS.has(key));
+}
+export function buildDocumentOpenParams(params) {
+    const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : randomUUID();
+    return {
+        sessionId,
+        params: { sessionId, path: params.doc },
+    };
+}
+export function mapDocumentOpenResult(response, sessionId, path) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError('Host returned invalid document.open result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId || typeof record.byteLength !== 'number') {
+        throw new SuperDocCliError('Host returned invalid document.open session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        active: true,
+        contextId: sessionId,
+        runtime: 'v2',
+        sessionType: 'local',
+        document: { path, source: 'path', byteLength: record.byteLength, revision: 0 },
+        dirty: false,
+    };
+}
+function documentInvokeInput(operationId, params) {
+    const allowedFields = operationId === 'doc.getText' ? new Set(['in']) : DOCUMENT_RPC_INSERT_FIELDS;
+    const input = Object.fromEntries(Object.entries(params).filter(([key, value]) => value !== undefined && key !== 'doc' && key !== 'sessionId'));
+    const unsupportedField = Object.keys(input).find((key) => !allowedFields.has(key));
+    if (unsupportedField) {
+        throw unsupported(`Structured document RPC v0 does not support ${operationId} field ${unsupportedField}.`, operationId);
+    }
+    return input;
+}
+export function buildDocumentInvokeParams(sessionId, operation, params, options) {
+    if (!DOCUMENT_RPC_V0_OPERATIONS.has(operation.operationId)) {
+        throw unsupported(`Structured document RPC does not support ${operation.operationId} in v0.`, operation.operationId);
+    }
+    if (hasUnsupportedInvokeOptions(options)) {
+        throw unsupported('Structured document RPC v0 does not support document mutation options.', operation.operationId);
+    }
+    if (operation.operationId === 'doc.save') {
+        if (params.inPlace === true || typeof params.out !== 'string' || params.out.length === 0) {
+            throw unsupported('Structured document RPC v0 requires doc.save({ out }) and does not support inPlace.', operation.operationId);
+        }
+        return {
+            method: 'document.save',
+            params: {
+                sessionId,
+                path: params.out,
+                overwrite: params.force === true,
+                ...(params.mode === undefined ? {} : { mode: params.mode }),
+            },
+        };
+    }
+    if (operation.operationId === 'doc.close') {
+        return {
+            method: 'document.close',
+            params: {
+                sessionId,
+                ...(params.discard === undefined ? {} : { discard: params.discard }),
+            },
+        };
+    }
+    return {
+        method: 'document.invoke',
+        params: {
+            sessionId,
+            operationId: operation.operationId.slice('doc.'.length),
+            input: documentInvokeInput(operation.operationId, params),
+        },
+    };
+}
+export function mapDocumentLifecycleResult(operationId, response, sessionId) {
+    if (operationId !== 'doc.save' && operationId !== 'doc.close')
+        return response;
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError(`Host returned invalid ${operationId.slice('doc.'.length)} result.`, {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId) {
+        throw new SuperDocCliError('Host returned a result for the wrong document session.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    if (operationId === 'doc.close') {
+        if (record.closed !== true || typeof record.discarded !== 'boolean') {
+            throw new SuperDocCliError('Host returned invalid document.close result.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { result: response },
+            });
+        }
+        return {
+            contextId: sessionId,
+            runtime: 'v2',
+            closed: true,
+            saved: false,
+            discarded: record.discarded,
+            defaultSessionCleared: false,
+        };
+    }
+    const output = record.output;
+    if (record.saved !== true ||
+        typeof output !== 'object' ||
+        output == null ||
+        Array.isArray(output) ||
+        typeof output.path !== 'string' ||
+        typeof output.byteLength !== 'number') {
+        throw new SuperDocCliError('Host returned invalid document.save result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        saved: true,
+        inPlace: false,
+        mode: record.mode,
+        output,
+        report: record.report,
+    };
+}