@rsconcept/rstool 0.10.3 → 1.0.1

package/src/wrapper/client.ts

@@ -2,6 +2,7 @@ import { spawn, type ChildProcessByStdio } from 'node:child_process';
 import readline from 'node:readline';
 import { type Readable, type Writable } from 'node:stream';
 
+/** One JSON line emitted by the stdio wrapper (request response or ready event). */
 export interface WrapperResponse<T = unknown> {
   id: string | number | null;
   ok: boolean;
@@ -13,19 +14,32 @@ export interface WrapperResponse<T = unknown> {
   };
 }
 
+/** Options for spawning the `rstool-wrapper` child process. */
 export interface RSToolWrapperClientOptions {
+  /** Executable to spawn. Default: `npm`. */
   command?: string;
+  /** Arguments passed to `command`. Default: `['run', 'wrapper']`. */
   args?: string[];
+  /** Working directory for the child process. Default: `process.cwd()`. */
   cwd?: string;
+  /** Whether to run the command in a shell. Default: `true`. */
   shell?: boolean;
 }
 
+/**
+ * JSON-RPC client for the `rstool-wrapper` stdio process.
+ *
+ * Sends one JSON request per line on stdin and reads one JSON response per line from stdout.
+ */
 export class RSToolWrapperClient {
   private process: ChildProcessByStdio<Writable, Readable, null>;
   private input: readline.Interface;
   private pending = new Map<string, (value: WrapperResponse) => void>();
   private requestCounter = 1;
 
+  /**
+   * @param options - Spawn configuration; defaults run `npm run wrapper` in the current directory.
+   */
   public constructor(options: RSToolWrapperClientOptions = {}) {
     this.process = spawn(options.command ?? 'npm', options.args ?? ['run', 'wrapper'], {
       cwd: options.cwd ?? process.cwd(),
@@ -39,6 +53,7 @@ export class RSToolWrapperClient {
     this.input.on('line', line => this.handleLine(line));
   }
 
+  /** Block until the wrapper emits its initial `{ ready: true }` event. */
   public async waitUntilReady(): Promise<void> {
     for (;;) {
       const line = await this.readOneEvent();
@@ -54,6 +69,13 @@ export class RSToolWrapperClient {
     }
   }
 
+  /**
+   * Invoke a wrapper method and return its `result` field.
+   *
+   * @param method - Stdio method name (matches {@link RSToolAgentContract} operations).
+   * @param params - Method parameters object.
+   * @throws When the wrapper responds with `ok: false`.
+   */
   public async call<T>(method: string, params: unknown = {}): Promise<T> {
     const id = String(this.requestCounter++);
     const payload = JSON.stringify({ id, method, params });
@@ -68,6 +90,7 @@ export class RSToolWrapperClient {
     return response.result as T;
   }
 
+  /** Close stdin and terminate the wrapper process. */
   public async close(): Promise<void> {
     this.input.close();
     this.process.stdin.end();

package/src/wrapper/stdio-handler.test.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { describe, expect, it } from 'vitest';
+
+import { CstType, CONTRACT_VERSION, RSToolAgent } from '../models';
+import { handleStdioRequest, STDIO_METHODS } from './stdio-handler';
+
+describe('handleStdioRequest', () => {
+  const tool = new RSToolAgent();
+
+  it('responds to ping with contract version', async () => {
+    const response = await handleStdioRequest(tool, { id: 1, method: 'ping' });
+    expect(response).toEqual({
+      id: 1,
+      ok: true,
+      result: { pong: true, contractVersion: CONTRACT_VERSION }
+    });
+  });
+
+  it('lists contract methods', async () => {
+    const response = await handleStdioRequest(tool, { id: 2, method: 'methods' });
+    expect(response.ok).toBe(true);
+    expect(response.result).toEqual(STDIO_METHODS);
+  });
+
+  it('applies schema patch through the wrapper', async () => {
+    const response = await handleStdioRequest(tool, {
+      id: 3,
+      method: 'applySchemaPatch',
+      params: { items: [{ alias: 'X1' }] }
+    });
+    expect(response.ok).toBe(true);
+    expect((response.result as { success: boolean }).success).toBe(true);
+  });
+
+  it('evaluates a constituent', async () => {
+    const sessionTool = new RSToolAgent();
+    await handleStdioRequest(sessionTool, {
+      id: 10,
+      method: 'applySchemaPatch',
+      params: {
+        items: [{ alias: 'X1' }, { alias: 'D1', definitionFormal: '1+2' }]
+      }
+    });
+    const response = await handleStdioRequest(sessionTool, {
+      id: 11,
+      method: 'evaluate',
+      params: { constituentId: 2 }
+    });
+    expect(response.ok).toBe(true);
+    expect((response.result as { value: number }).value).toBe(3);
+  });
+
+  it('returns METHOD_NOT_FOUND for unknown methods', async () => {
+    const response = await handleStdioRequest(tool, { id: 4, method: 'notReal' });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('METHOD_NOT_FOUND');
+  });
+
+  it('returns INTERNAL_ERROR when setCurrentSession lacks sessionId', async () => {
+    const response = await handleStdioRequest(tool, { id: 5, method: 'setCurrentSession', params: {} });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('INTERNAL_ERROR');
+    expect(response.error?.message).toMatch(/sessionId/);
+  });
+
+  it('returns INTERNAL_ERROR for unknown session id', async () => {
+    const sessionTool = new RSToolAgent();
+    const response = await handleStdioRequest(sessionTool, {
+      id: 6,
+      method: 'setCurrentSession',
+      params: { sessionId: randomUUID() }
+    });
+    expect(response.ok).toBe(false);
+    expect(response.error?.code).toBe('INTERNAL_ERROR');
+    expect(response.error?.message).toMatch(/Unknown session/);
+  });
+
+  it('filters diagnostics by constituentId param', async () => {
+    const sessionTool = new RSToolAgent();
+    const created = await handleStdioRequest(sessionTool, { id: 20, method: 'createSession' });
+    const sessionId = (created.result as { sessionId: string }).sessionId;
+    await handleStdioRequest(sessionTool, {
+      id: 21,
+      method: 'applySchemaPatch',
+      params: {
+        sessionId,
+        mode: 'best_effort',
+        items: [{ alias: 'X1', cstType: CstType.BASE, definitionFormal: 'Z' }]
+      }
+    });
+
+    const all = await handleStdioRequest(sessionTool, { id: 22, method: 'listDiagnostics', params: { sessionId } });
+    const filtered = await handleStdioRequest(sessionTool, {
+      id: 23,
+      method: 'listDiagnostics',
+      params: { sessionId, constituentId: 1 }
+    });
+    expect((all.result as unknown[]).length).toBeGreaterThan(0);
+    expect(filtered.result).toEqual(all.result);
+  });
+});

package/src/wrapper/stdio-handler.ts

@@ -0,0 +1,195 @@
+import type { RSToolAgent } from '../models/rstool-agent';
+
+export interface StdioRequest {
+  id: string | number;
+  method: string;
+  params?: unknown;
+}
+
+export interface StdioResponse {
+  id: string | number | null;
+  ok: boolean;
+  result?: unknown;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+}
+
+export const STDIO_METHODS = [
+  'ensureSession',
+  'createSession',
+  'getCurrentSession',
+  'setCurrentSession',
+  'applySchemaPatch',
+  'getSessionState',
+  'listDiagnostics',
+  'analyzeExpression',
+  'commitStep',
+  'exportSession',
+  'exportPortal',
+  'importData',
+  'setModelValues',
+  'getModelState',
+  'evaluate',
+  'recalculateModel'
+] as const;
+
+function asObject(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  return value as Record<string, unknown>;
+}
+
+function requiredString(input: Record<string, unknown>, key: string): string {
+  const value = input[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing or invalid "${key}"`);
+  }
+  return value;
+}
+
+function optionalSessionId(input: Record<string, unknown>): string | undefined {
+  const value = input.sessionId;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function omitSessionId(input: Record<string, unknown>): Record<string, unknown> {
+  const { sessionId: _sessionId, ...rest } = input;
+  return rest;
+}
+
+export async function handleStdioRequest(tool: RSToolAgent, request: StdioRequest): Promise<StdioResponse> {
+  try {
+    const params = asObject(request.params);
+    switch (request.method) {
+      case 'ping':
+        return { id: request.id, ok: true, result: { pong: true, contractVersion: tool.contractVersion } };
+      case 'methods':
+        return { id: request.id, ok: true, result: STDIO_METHODS };
+      case 'ensureSession':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.ensureSession(params.initial as never)
+        };
+      case 'createSession':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.createSession(params.initial as never)
+        };
+      case 'getCurrentSession':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.getCurrentSession()
+        };
+      case 'setCurrentSession':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.setCurrentSession(requiredString(params, 'sessionId'))
+        };
+      case 'applySchemaPatch':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.applySchemaPatch(omitSessionId(params) as never, optionalSessionId(params))
+        };
+      case 'getSessionState':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.getSessionState(
+            (params.detail as 'summary' | 'full' | undefined) ?? 'summary',
+            optionalSessionId(params)
+          )
+        };
+      case 'listDiagnostics': {
+        const constituentId = params.constituentId;
+        const filters = typeof constituentId === 'number' ? { constituentId } : (params.filters as never);
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.listDiagnostics(filters, optionalSessionId(params))
+        };
+      }
+      case 'analyzeExpression':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.analyzeExpression(omitSessionId(params) as never, optionalSessionId(params))
+        };
+      case 'commitStep':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.commitStep(params.message as string | undefined, optionalSessionId(params))
+        };
+      case 'exportSession':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.exportSession(optionalSessionId(params))
+        };
+      case 'exportPortal':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.exportPortal(omitSessionId(params) as never, optionalSessionId(params))
+        };
+      case 'importData':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.importData(params.payload as string | object, params.kind as never)
+        };
+      case 'setModelValues':
+        return {
+          id: request.id,
+          ok: true,
+          result: await tool.setModelValues(omitSessionId(params) as never, optionalSessionId(params))
+        };
+      case 'getModelState':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.getModelState(optionalSessionId(params))
+        };
+      case 'evaluate':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.evaluate(omitSessionId(params) as never, optionalSessionId(params))
+        };
+      case 'recalculateModel':
+        return {
+          id: request.id,
+          ok: true,
+          result: tool.recalculateModel(optionalSessionId(params))
+        };
+      default:
+        return {
+          id: request.id ?? null,
+          ok: false,
+          error: {
+            code: 'METHOD_NOT_FOUND',
+            message: `Unknown method: ${request.method}`
+          }
+        };
+    }
+  } catch (error) {
+    return {
+      id: request.id ?? null,
+      ok: false,
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: error instanceof Error ? error.message : 'Unknown error',
+        details: error
+      }
+    };
+  }
+}

package/src/wrapper/stdio-wrapper.ts

@@ -2,45 +2,10 @@
 import readline from 'node:readline';
 
 import { RSToolAgent } from '../models/rstool-agent';
+import { handleStdioRequest, type StdioRequest, type StdioResponse } from './stdio-handler';
 
-interface StdioRequest {
-  id: string | number;
-  method: string;
-  params?: unknown;
-}
-
-interface StdioResponse {
-  id: string | number | null;
-  ok: boolean;
-  result?: unknown;
-  error?: {
-    code: string;
-    message: string;
-    details?: unknown;
-  };
-}
-
-const tool = new RSToolAgent();
-
-const METHODS = [
-  'createSession',
-  'addOrUpdateConstituenta',
-  'analyzeExpression',
-  'getFormState',
-  'listDiagnostics',
-  'commitStep',
-  'exportSession',
-  'exportPortalSchema',
-  'exportPortalModel',
-  'importSession',
-  'setConstituentaValue',
-  'setConstituentaValues',
-  'clearConstituentaValues',
-  'getModelState',
-  'evaluateExpression',
-  'evaluateConstituenta',
-  'recalculateModel'
-] as const;
+const persistenceDir = process.env.RSTOOL_PERSISTENCE_DIR;
+const tool = new RSToolAgent(persistenceDir ? { persistenceDir } : {});
 
 function writeResponse(response: StdioResponse): void {
   if (!process.stdout.writable || process.stdout.destroyed || process.stdout.writableEnded) {
@@ -53,154 +18,6 @@ function writeResponse(response: StdioResponse): void {
   }
 }
 
-function asObject(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    return {};
-  }
-  return value as Record<string, unknown>;
-}
-
-function requiredString(input: Record<string, unknown>, key: string): string {
-  const value = input[key];
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`Missing or invalid "${key}"`);
-  }
-  return value;
-}
-
-async function handleRequest(request: StdioRequest): Promise<StdioResponse> {
-  try {
-    const params = asObject(request.params);
-    switch (request.method) {
-      case 'ping':
-        return { id: request.id, ok: true, result: { pong: true } };
-      case 'methods':
-        return { id: request.id, ok: true, result: METHODS };
-      case 'createSession':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.createSession(params.initial as never)
-        };
-      case 'addOrUpdateConstituenta':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.addOrUpdateConstituenta(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'analyzeExpression':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.analyzeExpression(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'getFormState':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.getFormState(requiredString(params, 'sessionId'))
-        };
-      case 'listDiagnostics':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.listDiagnostics(requiredString(params, 'sessionId'), params.filters as never)
-        };
-      case 'commitStep':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.commitStep(requiredString(params, 'sessionId'), params.message as string | undefined)
-        };
-      case 'exportSession':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.exportSession(requiredString(params, 'sessionId'))
-        };
-      case 'exportPortalSchema':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.exportPortalSchema(requiredString(params, 'sessionId'))
-        };
-      case 'exportPortalModel':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.exportPortalModel(requiredString(params, 'sessionId'))
-        };
-      case 'importSession':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.importSession(requiredString(params, 'payload'))
-        };
-      case 'setConstituentaValue':
-        return {
-          id: request.id,
-          ok: true,
-          result: await tool.setConstituentaValue(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'setConstituentaValues':
-        return {
-          id: request.id,
-          ok: true,
-          result: await tool.setConstituentaValues(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'clearConstituentaValues':
-        return {
-          id: request.id,
-          ok: true,
-          result: await tool.clearConstituentaValues(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'getModelState':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.getModelState(requiredString(params, 'sessionId'))
-        };
-      case 'evaluateExpression':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.evaluateExpression(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'evaluateConstituenta':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.evaluateConstituenta(requiredString(params, 'sessionId'), params.input as never)
-        };
-      case 'recalculateModel':
-        return {
-          id: request.id,
-          ok: true,
-          result: tool.recalculateModel(requiredString(params, 'sessionId'))
-        };
-      default:
-        return {
-          id: request.id ?? null,
-          ok: false,
-          error: {
-            code: 'METHOD_NOT_FOUND',
-            message: `Unknown method: ${request.method}`
-          }
-        };
-    }
-  } catch (error) {
-    return {
-      id: request.id ?? null,
-      ok: false,
-      error: {
-        code: 'INTERNAL_ERROR',
-        message: error instanceof Error ? error.message : 'Unknown error',
-        details: error
-      }
-    };
-  }
-}
-
 const input = readline.createInterface({
   input: process.stdin,
   crlfDelay: Infinity
@@ -225,7 +42,7 @@ input.on('line', line => {
     if (!('id' in request) || !('method' in request)) {
       throw new Error('Request must include "id" and "method"');
     }
-    void handleRequest(request).then(writeResponse);
+    void handleStdioRequest(tool, request).then(writeResponse);
   } catch (error) {
     writeResponse({
       id: null,

package/dist/analysis-JiwOYDKx.d.ts

@@ -1,16 +0,0 @@
-import { a as RSToolErrorDescription, n as CstType, s as ValueClass } from "./common-DxLg3eXX.js";
-
-//#region src/models/analysis.d.ts
-interface AnalyzeExpressionInput {
-  expression: string;
-  cstType: CstType;
-}
-interface AnalysisResult {
-  success: boolean;
-  type: Record<string, unknown> | null;
-  valueClass: ValueClass | null;
-  diagnostics: RSToolErrorDescription[];
-}
-//#endregion
-export { AnalyzeExpressionInput as n, AnalysisResult as t };
-//# sourceMappingURL=analysis-JiwOYDKx.d.ts.map

package/dist/constituenta-Dnd6iToB.d.ts

@@ -1,36 +0,0 @@
-import { n as CstType } from "./common-DxLg3eXX.js";
-import { t as AnalysisResult } from "./analysis-JiwOYDKx.js";
-import { t as DiagnosticRecord } from "./diagnostic-BMYvciz8.js";
-
-//#region src/models/constituenta.d.ts
-interface ConstituentaDraft {
-  id: number;
-  /** Alias */
-  alias: string;
-  /** CST type */
-  cstType: CstType;
-  /** Formal definition */
-  definitionFormal: string;
-  /** Natural-language term */
-  term?: string;
-  /** Natural-language definition */
-  definitionText?: string;
-  /** Convention or comment */
-  convention?: string;
-}
-interface ConstituentaState extends Omit<ConstituentaDraft, 'term' | 'definitionText' | 'convention'> {
-  term: string;
-  definitionText: string;
-  convention: string;
-  analysis: AnalysisResult;
-}
-interface AddOrUpdateConstituentaInput {
-  draft: ConstituentaDraft;
-}
-interface AddOrUpdateConstituentaResult {
-  state: ConstituentaState;
-  diagnostics: DiagnosticRecord[];
-}
-//#endregion
-export { ConstituentaState as i, AddOrUpdateConstituentaResult as n, ConstituentaDraft as r, AddOrUpdateConstituentaInput as t };
-//# sourceMappingURL=constituenta-Dnd6iToB.d.ts.map

package/dist/diagnostic-BMYvciz8.d.ts

@@ -1,15 +0,0 @@
-import { a as RSToolErrorDescription } from "./common-DxLg3eXX.js";
-
-//#region src/models/diagnostic.d.ts
-interface DiagnosticRecord {
-  sessionId: string;
-  constituentId?: number;
-  expression: string;
-  error: RSToolErrorDescription;
-}
-interface ListDiagnosticsFilters {
-  constituentId?: number;
-}
-//#endregion
-export { ListDiagnosticsFilters as n, DiagnosticRecord as t };
-//# sourceMappingURL=diagnostic-BMYvciz8.d.ts.map

package/dist/evaluation-CCVYH0wA.d.ts

@@ -1,21 +0,0 @@
-import { a as RSToolErrorDescription, n as CstType, o as RSToolValue, r as EvalStatus, t as BasicBinding } from "./common-DxLg3eXX.js";
-
-//#region src/models/evaluation.d.ts
-interface EvaluateExpressionInput {
-  expression: string;
-  cstType: CstType;
-}
-interface EvaluateConstituentaInput {
-  constituentId: number;
-}
-interface EvaluationResult {
-  success: boolean;
-  value: RSToolValue | BasicBinding | null;
-  status: EvalStatus;
-  iterations: number;
-  cacheHits: number;
-  diagnostics: RSToolErrorDescription[];
-}
-//#endregion
-export { EvaluateExpressionInput as n, EvaluationResult as r, EvaluateConstituentaInput as t };
-//# sourceMappingURL=evaluation-CCVYH0wA.d.ts.map