@superdoc/sdk 2.5.0 → 2.7.0

package/dist/index.cjs

@@ -4,6 +4,7 @@ var client = require('./generated/client.cjs');
 var contract = require('./generated/contract.cjs');
 var process = require('./runtime/process.cjs');
 var errors = require('./runtime/errors.cjs');
+var introspection = require('./introspection.cjs');
 var skills = require('./skills.cjs');
 var tools = require('./tools.cjs');
 var intentDispatch_generated = require('./generated/intent-dispatch.generated.cjs');
@@ -145,11 +146,11 @@ class SuperDocClient {
         this.handles.set(contextId, handle);
         return handle;
     }
-    async describe(params = {}, options) {
-        return this.rawApi.describe(params, options);
+    async describe(_params = {}, _options) {
+        return introspection.describeContract();
     }
-    async describeCommand(params, options) {
-        return this.rawApi.describeCommand(params, options);
+    async describeCommand(params, _options) {
+        return introspection.describeContractOperation(params);
     }
     async dispose() {
         for (const handle of this.handles.values()) {

package/dist/index.d.ts

@@ -74,8 +74,8 @@ export declare class SuperDocClient {
      * different session ids (useful for diff workflows).
      */
     open(params: DocOpenParams, options?: InvokeOptions): Promise<SuperDocDocument>;
-    describe(params?: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
-    describeCommand(params: DocDescribeCommandParams, options?: InvokeOptions): Promise<unknown>;
+    describe(_params?: Record<string, unknown>, _options?: InvokeOptions): Promise<unknown>;
+    describeCommand(params: DocDescribeCommandParams, _options?: InvokeOptions): Promise<unknown>;
     dispose(): Promise<void>;
     /** @internal */
     removeHandle(sessionId: string): void;

package/dist/index.js

@@ -2,6 +2,7 @@ import { createDocApi, createBoundDocApi, } from './generated/client.js';
 import { CONTRACT } from './generated/contract.js';
 import { SuperDocRuntime, } from './runtime/process.js';
 import { SuperDocCliError } from './runtime/errors.js';
+import { describeContract, describeContractOperation } from './introspection.js';
 // ---------------------------------------------------------------------------
 // Session-bound runtime wrapper
 // ---------------------------------------------------------------------------
@@ -137,11 +138,11 @@ export class SuperDocClient {
         this.handles.set(contextId, handle);
         return handle;
     }
-    async describe(params = {}, options) {
-        return this.rawApi.describe(params, options);
+    async describe(_params = {}, _options) {
+        return describeContract();
     }
-    async describeCommand(params, options) {
-        return this.rawApi.describeCommand(params, options);
+    async describeCommand(params, _options) {
+        return describeContractOperation(params);
     }
     async dispose() {
         for (const handle of this.handles.values()) {

package/dist/introspection.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var contract = require('./generated/contract.cjs');
+var errors = require('./runtime/errors.cjs');
+
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function detailParam(param) {
+    return {
+        name: param.name,
+        kind: param.kind,
+        ...(Object.prototype.hasOwnProperty.call(param, 'flag') ? { flag: param.flag } : {}),
+        type: param.type,
+        ...(Object.prototype.hasOwnProperty.call(param, 'required') ? { required: param.required } : {}),
+        ...(Object.prototype.hasOwnProperty.call(param, 'schema') ? { schema: param.schema } : {}),
+    };
+}
+function describeContract() {
+    return cloneJson(contract.CONTRACT.introspection.overview);
+}
+function describeContractOperation(params) {
+    const rawQuery = params?.operationId;
+    if (rawQuery == null || String(rawQuery).length === 0) {
+        throw new errors.SuperDocCliError('describe command: missing required input.operationId.', {
+            code: 'MISSING_REQUIRED',
+            exitCode: 1,
+        });
+    }
+    const query = String(rawQuery);
+    const normalizedQuery = query.trim().toLowerCase();
+    const index = Object.prototype.hasOwnProperty.call(contract.CONTRACT.introspection.lookup, normalizedQuery)
+        ? contract.CONTRACT.introspection.lookup[normalizedQuery]
+        : undefined;
+    if (typeof index !== 'number' ||
+        !Number.isInteger(index) ||
+        index < 0 ||
+        index >= contract.CONTRACT.introspection.overview.operations.length) {
+        throw new errors.SuperDocCliError(`Unknown operation: ${query}`, {
+            code: 'TARGET_NOT_FOUND',
+            details: { query },
+            exitCode: 1,
+        });
+    }
+    const summary = contract.CONTRACT.introspection.overview.operations[index];
+    const operation = contract.CONTRACT.operations[summary.id];
+    return cloneJson({
+        contractVersion: contract.CONTRACT.contractVersion,
+        query,
+        operation: {
+            ...summary,
+            params: operation.params.map(detailParam),
+            constraints: operation.constraints ?? null,
+        },
+    });
+}
+
+exports.describeContract = describeContract;
+exports.describeContractOperation = describeContractOperation;

package/dist/introspection.d.ts

@@ -0,0 +1,3 @@
+import { type ContractOverview } from './generated/contract.js';
+export declare function describeContract(): ContractOverview;
+export declare function describeContractOperation(params?: Record<string, unknown> | null): unknown;

package/dist/introspection.js

@@ -0,0 +1,53 @@
+import { CONTRACT } from './generated/contract.js';
+import { SuperDocCliError } from './runtime/errors.js';
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function detailParam(param) {
+    return {
+        name: param.name,
+        kind: param.kind,
+        ...(Object.prototype.hasOwnProperty.call(param, 'flag') ? { flag: param.flag } : {}),
+        type: param.type,
+        ...(Object.prototype.hasOwnProperty.call(param, 'required') ? { required: param.required } : {}),
+        ...(Object.prototype.hasOwnProperty.call(param, 'schema') ? { schema: param.schema } : {}),
+    };
+}
+export function describeContract() {
+    return cloneJson(CONTRACT.introspection.overview);
+}
+export function describeContractOperation(params) {
+    const rawQuery = params?.operationId;
+    if (rawQuery == null || String(rawQuery).length === 0) {
+        throw new SuperDocCliError('describe command: missing required input.operationId.', {
+            code: 'MISSING_REQUIRED',
+            exitCode: 1,
+        });
+    }
+    const query = String(rawQuery);
+    const normalizedQuery = query.trim().toLowerCase();
+    const index = Object.prototype.hasOwnProperty.call(CONTRACT.introspection.lookup, normalizedQuery)
+        ? CONTRACT.introspection.lookup[normalizedQuery]
+        : undefined;
+    if (typeof index !== 'number' ||
+        !Number.isInteger(index) ||
+        index < 0 ||
+        index >= CONTRACT.introspection.overview.operations.length) {
+        throw new SuperDocCliError(`Unknown operation: ${query}`, {
+            code: 'TARGET_NOT_FOUND',
+            details: { query },
+            exitCode: 1,
+        });
+    }
+    const summary = CONTRACT.introspection.overview.operations[index];
+    const operation = CONTRACT.operations[summary.id];
+    return cloneJson({
+        contractVersion: CONTRACT.contractVersion,
+        query,
+        operation: {
+            ...summary,
+            params: operation.params.map(detailParam),
+            constraints: operation.constraints ?? null,
+        },
+    });
+}

package/dist/runtime/document-rpc.cjs

@@ -0,0 +1,328 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+var errors = require('./errors.cjs');
+var transportCommon = require('./transport-common.cjs');
+
+const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
+const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
+const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
+const DOCUMENT_RPC_OPEN_FIELDS = new Set(['doc', 'sessionId', 'runtime']);
+const DOCUMENT_RPC_SAVE_FIELDS = new Set(['sessionId', 'out', 'force', 'mode', 'inPlace']);
+const DOCUMENT_API_OPTION_FIELDS = new Set(['expectedRevision', 'changeMode', 'dryRun', 'supportCheck']);
+const DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS = new Set([
+    'doc.history.redo',
+    'doc.history.undo',
+    'doc.plan.execute',
+]);
+function unsupported(message, operationId) {
+    return new errors.SuperDocCliError(message, {
+        code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+        ...(operationId === undefined ? {} : { details: { operationId } }),
+    });
+}
+function buildDocumentAuthor(user) {
+    if (user === undefined)
+        return undefined;
+    if (typeof user !== 'object' || user === null || Array.isArray(user)) {
+        throw new errors.SuperDocCliError('user must be an object with a non-empty name.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const record = user;
+    if (typeof record.name !== 'string' || record.name.trim().length === 0) {
+        throw new errors.SuperDocCliError('user.name must be a non-empty string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (record.email !== undefined && typeof record.email !== 'string') {
+        throw new errors.SuperDocCliError('user.email must be a string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return {
+        name: record.name,
+        ...(record.email === undefined ? {} : { email: record.email }),
+    };
+}
+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 canOpenWithDocumentRpc(params, options) {
+    if (options.stdinBytes !== undefined)
+        return false;
+    if (options.dryRun !== undefined || options.expectedRevision !== undefined || options.changeMode !== undefined) {
+        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, user, defaultChangeMode) {
+    const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : node_crypto.randomUUID();
+    const author = buildDocumentAuthor(user);
+    return {
+        sessionId,
+        params: {
+            sessionId,
+            path: params.doc,
+            ...(author === undefined ? {} : { author }),
+            ...(defaultChangeMode == null ? {} : { defaultChangeMode }),
+        },
+    };
+}
+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 supportsTrackedMode(operation) {
+    return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
+}
+function documentInvokePayload(operation, params, invokeOptions) {
+    const normalizedParams = transportCommon.applyOperationParamAliases(operation, params);
+    if (invokeOptions.stdinBytes !== undefined) {
+        throw unsupported('Structured document RPC does not support stdinBytes.', operation.operationId);
+    }
+    if (typeof normalizedParams.out === 'string' && normalizedParams.out.length > 0) {
+        throw unsupported('Structured document RPC does not support per-operation output paths.', operation.operationId);
+    }
+    if (normalizedParams.force === true) {
+        throw unsupported('Structured document RPC does not support per-operation force.', operation.operationId);
+    }
+    const input = {};
+    const options = {};
+    const paramsByName = new Map(operation.params.map((param) => [param.name, param]));
+    for (const [name, value] of Object.entries(normalizedParams)) {
+        if (value === undefined || name === 'doc' || name === 'sessionId' || name === 'out' || name === 'force')
+            continue;
+        const param = paramsByName.get(name);
+        if (!param) {
+            throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
+        }
+        if (typeof param.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = value;
+            continue;
+        }
+        if (DOCUMENT_API_OPTION_FIELDS.has(name)) {
+            options[name] = value;
+            continue;
+        }
+        throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
+    }
+    for (const name of ['expectedRevision', 'changeMode', 'dryRun']) {
+        const value = invokeOptions[name];
+        if (value === undefined || normalizedParams[name] !== undefined)
+            continue;
+        const projectedValue = name === 'expectedRevision' ? String(value) : value;
+        const param = paramsByName.get(name);
+        if (typeof param?.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = projectedValue;
+        }
+        else {
+            options[name] = projectedValue;
+        }
+    }
+    if (options.changeMode !== undefined && !supportsTrackedMode(operation)) {
+        if (options.changeMode === 'tracked') {
+            throw unsupported(`Structured document RPC does not support tracked mode for ${operation.operationId}.`, operation.operationId);
+        }
+        if (options.changeMode !== 'direct') {
+            throw unsupported(`Structured document RPC received an invalid change mode for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.changeMode;
+    }
+    if (options.dryRun !== undefined && operation.supportsDryRun !== true) {
+        if (options.dryRun === true) {
+            throw unsupported(`Structured document RPC does not support dry run for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.dryRun;
+    }
+    if (options.expectedRevision !== undefined && DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS.has(operation.operationId)) {
+        throw unsupported(`Structured document RPC does not yet support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    if (options.expectedRevision !== undefined && operation.mutates !== true) {
+        throw unsupported(`Structured document RPC does not support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    return {
+        input,
+        ...(Object.keys(options).length === 0 ? {} : { options }),
+    };
+}
+function buildDocumentInvokeParams(sessionId, operation, params, options, hostFeatures) {
+    if (operation.operationId === 'doc.save') {
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.save invoke options.', operation.operationId);
+        }
+        const unknownField = Object.entries(params).find(([name, value]) => value !== undefined && !DOCUMENT_RPC_SAVE_FIELDS.has(name))?.[0];
+        if (unknownField !== undefined) {
+            throw unsupported(`Structured document RPC does not support doc.save field ${unknownField}.`, operation.operationId);
+        }
+        if (params.inPlace !== undefined && typeof params.inPlace !== 'boolean') {
+            throw unsupported('Structured document RPC requires inPlace to be a boolean.', operation.operationId);
+        }
+        if (params.inPlace === true && params.out !== undefined) {
+            throw unsupported('Structured document RPC requires either inPlace or out, not both.', operation.operationId);
+        }
+        if (params.out !== undefined && (typeof params.out !== 'string' || params.out.length === 0)) {
+            throw unsupported('Structured document RPC requires out to be a non-empty path.', operation.operationId);
+        }
+        if (params.out === undefined && hostFeatures?.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE) !== true) {
+            throw unsupported('Structured document RPC host does not support source saves.', operation.operationId);
+        }
+        return {
+            method: 'document.save',
+            params: {
+                sessionId,
+                ...(params.out === undefined ? {} : { path: params.out }),
+                ...(params.force === true ? { overwrite: true } : {}),
+                ...(params.mode === undefined ? {} : { mode: params.mode }),
+            },
+        };
+    }
+    if (operation.operationId === 'doc.close') {
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.close invoke options.', operation.operationId);
+        }
+        return {
+            method: 'document.close',
+            params: {
+                sessionId,
+                ...(params.discard === undefined ? {} : { discard: params.discard }),
+            },
+        };
+    }
+    const documentOperation = operation;
+    if (typeof documentOperation.documentApiOperationId !== 'string' ||
+        documentOperation.documentApiOperationId.length === 0) {
+        throw unsupported(`Structured document RPC does not support ${operation.operationId}.`, operation.operationId);
+    }
+    const payload = documentInvokePayload(documentOperation, params, options);
+    return {
+        method: 'document.invoke',
+        params: {
+            sessionId,
+            operationId: documentOperation.documentApiOperationId,
+            input: payload.input,
+            ...(payload.options === undefined ? {} : { options: payload.options }),
+        },
+    };
+}
+function documentRpcRequestSupportsResponseTimeout(operation, request) {
+    if (request.method === 'document.save')
+        return false;
+    if (request.method !== 'document.invoke')
+        return true;
+    const documentOperation = operation;
+    const requestOptions = typeof request.params.options === 'object' &&
+        request.params.options !== null &&
+        !Array.isArray(request.params.options)
+        ? request.params.options
+        : undefined;
+    if (requestOptions?.dryRun === true)
+        return true;
+    if (documentOperation.mutates === false)
+        return true;
+    return documentOperation.idempotency === 'idempotent';
+}
+function mapDocumentLifecycleResult(operationId, response, sessionId, expectedInPlace) {
+    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 record.inPlace !== 'boolean' && !(record.inPlace === undefined && expectedInPlace === false)) ||
+        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: record.inPlace ?? false,
+        mode: record.mode,
+        output,
+        report: record.report,
+    };
+}
+
+exports.DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE;
+exports.DOCUMENT_RPC_FEATURES = DOCUMENT_RPC_FEATURES;
+exports.DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE;
+exports.DOCUMENT_RPC_SOURCE_SAVE_FEATURE = DOCUMENT_RPC_SOURCE_SAVE_FEATURE;
+exports.buildDocumentInvokeParams = buildDocumentInvokeParams;
+exports.buildDocumentOpenParams = buildDocumentOpenParams;
+exports.canOpenWithDocumentRpc = canOpenWithDocumentRpc;
+exports.documentRpcEnabled = documentRpcEnabled;
+exports.documentRpcRequestSupportsResponseTimeout = documentRpcRequestSupportsResponseTimeout;
+exports.mapDocumentLifecycleResult = mapDocumentLifecycleResult;
+exports.mapDocumentOpenResult = mapDocumentOpenResult;
+exports.supportsDocumentRpc = supportsDocumentRpc;

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

@@ -0,0 +1,24 @@
+import { type ChangeMode, type InvokeOptions, type OperationSpec, type UserIdentity } from './transport-common.js';
+export declare const DOCUMENT_RPC_FEATURES: readonly ["document.open", "document.invoke", "document.save", "document.close"];
+export declare const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = "document.open.defaultChangeMode";
+export declare const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = "document.save.source";
+export declare const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = "host.request.timeoutMs";
+type DocumentRpcRequest = {
+    readonly method: string;
+    readonly params: Record<string, unknown>;
+};
+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>, user?: UserIdentity, defaultChangeMode?: ChangeMode): {
+    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, hostFeatures?: ReadonlySet<string>): {
+    readonly method: string;
+    readonly params: Record<string, unknown>;
+};
+export declare function documentRpcRequestSupportsResponseTimeout(operation: OperationSpec, request: DocumentRpcRequest): boolean;
+export declare function mapDocumentLifecycleResult(operationId: string, response: unknown, sessionId: string, expectedInPlace?: boolean): unknown;
+export {};