functionalscript 0.43.1 → 0.44.0

package/fjs/protocol/mcp/proof.f.mjs

@@ -0,0 +1,312 @@
+/**
+ * @import { Unknown } from '../../media/json/types.ts'
+ * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { MemOperationMap } from '../../effects/mock/types.ts'
+ * @import { Key, MemOp } from '../../effects/memory/types.ts'
+ * @import {
+ *   ToolsListParams, ToolsListResult, ToolsCallParams, ToolsCallResult,
+ *   McpHandlers, McpConfig, McpSessionState,
+ * } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { pure, step } from '../../effects/module.f.mjs'
+import { eff } from '../../effects/eff/module.f.mjs'
+import { run } from '../../effects/mock/module.f.mjs'
+import { asBase, asNominal, create, read } from '../../effects/memory/module.f.mjs'
+import {
+    uninitializedState, mcpStep, notInitialized,
+} from './module.f.mjs'
+
+// ── Memory mock ────────────────────────────────────────────────────────────────
+
+/** @typedef {{
+ *   readonly next: number
+ *   readonly values: { readonly [key: string]: unknown }
+ * }} _MemoryState */
+
+/** @type {_MemoryState} */
+const initial = { next: 0, values: {} }
+
+/** @type {MemOperationMap<MemOp, _MemoryState>} */
+const mock = {
+    memCreate: value => state => {
+        const id = `k${state.next}`
+        /** @type {Key<unknown>} */
+        const key = asNominal(id)
+        return [{ next: state.next + 1, values: { ...state.values, [id]: value } }, key]
+    },
+    memRead: key => state => [state, state.values[asBase(key)]],
+    memWrite: (key, value) => state => {
+        const id = asBase(key)
+        return [{ ...state, values: { ...state.values, [id]: value } }, undefined]
+    },
+}
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+/** @type {McpConfig} */
+const config = {
+    serverInfo: { name: 'test-server', version: '0.1.0' },
+    capabilities: { tools: {} },
+    protocolVersion: '2024-11-05',
+}
+
+const configNoTools = { ...config, capabilities: {} }
+
+/** @typedef {never} _Op */
+/** @type {McpHandlers<_Op>} */
+const handlers = {
+    // Echoes a received cursor as `nextCursor` so tests can observe pagination params.
+    toolsList: (/** @type {ToolsListParams} */ p) =>
+        /** @type {Effect<_Op, ToolsListResult>} */
+        (pure(p.cursor === undefined
+            ? { tools: [{ name: 'greet', inputSchema: {} }] }
+            : { tools: [], nextCursor: p.cursor })),
+    toolsCall: (/** @type {ToolsCallParams} */ _p) =>
+        /** @type {Effect<_Op, ToolsCallResult>} */
+        (pure({ content: [{ type: 'text', text: 'hello' }] })),
+}
+
+/** @typedef {readonly [unknown, McpSessionState]} _StepResult */
+
+// Run a memory effect against the mock, return the result.
+/** @type {<T>(effect: Effect<MemOp, T>) => T} */
+const runMem = effect =>
+    run(mock)(initial)(effect)[1]
+
+// TypeScript infers O = Operation (the upper bound) rather than O = never when
+// O flows through McpHandlers<never>, so we cast the widened type down to MemOp.
+/** @type {<T>(e: Effect<Operation, T>) => Effect<MemOp, T>} */
+const asMemEffect = e => /** @type {Effect<MemOp, any>} */ (/** @type {unknown} */ (e))
+
+// Run one step from uninitializedState, return [response, newState].
+/** @type {(cfg: McpConfig) => (msg: unknown) => _StepResult} */
+const step1 = cfg => msg =>
+    runMem(asMemEffect(step(
+        create(/** @type {McpSessionState} */ (uninitializedState)),
+        key => step(
+            mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg)),
+            resp => step(
+                read(key),
+                state => pure(/** @type {const} */ ([resp, state])),
+            ),
+        ),
+    )))
+
+// Run initialize then a second step, return [response, newState] of the second.
+/** @type {(cfg: McpConfig) => (msg1: unknown) => (msg2: unknown) => _StepResult} */
+const step2 = cfg => msg1 => msg2 =>
+    runMem(asMemEffect(eff(create(/** @type {McpSessionState} */ (uninitializedState))).step(key =>
+        eff(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg1))).step(() =>
+            eff(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg2))).step(resp =>
+                step(
+                    read(key),
+                    state => pure(/** @type {const} */ ([resp, state])),
+                )
+            ).value).value).value))
+
+// Run initialize, notifications/initialized, then a third step; return [response, newState] of the third.
+/** @type {(cfg: McpConfig) => (msg1: unknown) => (msg2: unknown) => (msg3: unknown) => _StepResult} */
+const step3 = cfg => msg1 => msg2 => msg3 =>
+    runMem(asMemEffect(eff(create(/** @type {McpSessionState} */ (uninitializedState))).step(key =>
+        eff(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg1))).step(() =>
+            eff(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg2))).step(() =>
+                eff(mcpStep(cfg)(handlers)(key)(/** @type {Unknown} */ (msg3))).step(resp =>
+                    eff(read(key)).step(state => pure(/** @type {const} */ ([/** @type {unknown} */ (resp), state]))).value).value).value).value).value))
+
+// ── Test messages ─────────────────────────────────────────────────────────────
+
+const initMsg = { jsonrpc: '2.0', method: 'initialize', id: 1,
+    params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'client', version: '0.0.1' } } }
+
+const initNotif = { jsonrpc: '2.0', method: 'notifications/initialized' }
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+export const proof = {
+    lifecycle: {
+        initialStateIsUninitialized: () => {
+            assert(uninitializedState[0] === 'uninitialized')
+        },
+
+        initializeTransitionsToInitializing: () => {
+            const [, newState] = step1(config)(initMsg)
+            assert(newState[0] === 'initializing')
+        },
+
+        initializedNotificationTransitionsToInitialized: () => {
+            const [resp, newState] = step2(config)(initMsg)(initNotif)
+            assertEq(resp, null)
+            assert(newState[0] === 'initialized')
+        },
+
+        initializeReturnsResult: () => {
+            const [resp] = step1(config)(initMsg)
+            assert(resp !== null && typeof resp === 'object' && 'result' in /** @type {object} */ (resp))
+            const r = /** @type {{ result: { protocolVersion: string } }} */ (resp).result
+            assertEq(r.protocolVersion, '2024-11-05')
+        },
+
+        initializeWithBadParamsReturnsInvalidParams: () => {
+            const bad = { jsonrpc: '2.0', method: 'initialize', id: 2, params: { wrong: true } }
+            const [resp, newState] = step1(config)(bad)
+            assert(newState[0] === 'uninitialized')
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+        },
+
+        notificationBeforeInitReturnNull: () => {
+            const [resp, newState] = step1(config)(initNotif)
+            assert(newState[0] === 'uninitialized')
+            assertEq(resp, null)
+        },
+
+        unknownNotificationReturnNull: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/unknown' }
+            const [resp] = step2(config)(initMsg)(notif)
+            assertEq(resp, null)
+        },
+
+        doubleInitializeReturnsInvalidRequest: () => {
+            const [resp, newState] = step2(config)(initMsg)(initMsg)
+            assert(newState[0] === 'initializing')
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32600)
+        },
+
+        pingBeforeInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 11 }
+            const [resp, newState] = step1(config)(msg)
+            assert(newState[0] === 'uninitialized')
+            assert(!('error' in /** @type {object} */ (resp)))
+        },
+
+        pingDuringInitializingSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 12 }
+            const [resp, newState] = step2(config)(initMsg)(msg)
+            assert(newState[0] === 'initializing')
+            assert(!('error' in /** @type {object} */ (resp)))
+        },
+
+        pingAfterInitSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 15 }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assert(!('error' in /** @type {object} */ (resp)))
+        },
+
+        pingWithObjectParamsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 19, params: {} }
+            const [resp] = step1(config)(msg)
+            assert(!('error' in /** @type {object} */ (resp)))
+        },
+
+        pingInvalidParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'ping', id: 20, params: 1 }
+            const [resp] = step1(config)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+        },
+
+        initializedNotificationObjectParamsTransitions: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: {} }
+            const [resp, newState] = step2(config)(initMsg)(notif)
+            assertEq(resp, null)
+            assert(newState[0] === 'initialized')
+        },
+
+        initializedNotificationBadParamsIgnored: () => {
+            const notif = { jsonrpc: '2.0', method: 'notifications/initialized', params: 1 }
+            const [resp, newState] = step2(config)(initMsg)(notif)
+            assertEq(resp, null)
+            assert(newState[0] === 'initializing')
+        },
+
+        methodBeforeInitReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 3 }
+            const [resp, newState] = step1(config)(msg)
+            assert(newState[0] === 'uninitialized')
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, notInitialized.code)
+        },
+
+        methodDuringInitializingReturnsNotInitialized: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 16 }
+            const [resp, newState] = step2(config)(initMsg)(msg)
+            assert(newState[0] === 'initializing')
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, notInitialized.code)
+        },
+
+        invalidEnvelopeReturnsInvalidRequest: () => {
+            const bad = { jsonrpc: '1.0', method: 'ping', id: 4 }
+            const [resp] = step1(config)(bad)
+            assertEq(/** @type {{ error: { code: number }; id: unknown }} */ (resp).error.code, -32600)
+            assertEq(/** @type {{ error: { code: number }; id: unknown }} */ (resp).id, null)
+        },
+    },
+
+    tools: {
+        toolsListSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 5 }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.tools.length, 1)
+            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.tools[0].name, 'greet')
+        },
+
+        toolsListPassesCursorToHandler: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 17,
+                params: { cursor: 'page-2' } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ result: ToolsListResult }} */ (resp).result.nextCursor, 'page-2')
+        },
+
+        toolsListInvalidCursorReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 18,
+                params: { cursor: 42 } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+        },
+
+        toolsCallSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 6,
+                params: { name: 'greet', arguments: {} } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ text: string }} */ (/** @type {{ result: ToolsCallResult }} */ (resp).result.content[0]).text, 'hello')
+        },
+
+        toolsCallBadParamsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 7, params: { missing: true } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+        },
+
+        toolsCallAbsentArgumentsSucceeds: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 13,
+                params: { name: 'greet' } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ text: string }} */ (/** @type {{ result: ToolsCallResult }} */ (resp).result.content[0]).text, 'hello')
+        },
+
+        toolsCallNullArgumentsReturnsInvalidParams: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 14,
+                params: { name: 'greet', arguments: null } }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32602)
+        },
+
+        toolsListWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/list', id: 8 }
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+        },
+
+        toolsCallWithoutCapabilityReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'tools/call', id: 9,
+                params: { name: 'greet', arguments: {} } }
+            const [resp] = step3(configNoTools)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+        },
+
+        unknownMethodReturnsMethodNotFound: () => {
+            const msg = { jsonrpc: '2.0', method: 'resources/list', id: 10 }
+            const [resp] = step3(config)(initMsg)(initNotif)(msg)
+            assertEq(/** @type {{ error: { code: number } }} */ (resp).error.code, -32601)
+        },
+    },
+}

package/fjs/protocol/mcp/stdio/module.f.d.mts

@@ -0,0 +1,52 @@
+/**
+ * stdio transport for JSON-RPC / MCP servers.
+ *
+ * `stdioTransport` wraps a step function — the `mcpStep`-shaped
+ * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.mjs` — in the
+ * canonical read → parse → dispatch → write loop, expressed as a recursive
+ * effect so it stays in the pure effect model and is fully testable against a
+ * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
+ *
+ * The loop only consumes `Read` (stdin, one byte at a time, via the pure
+ * `readLine` combinator) and emits `Write` (stdout) on top of whatever `O` the
+ * step needs (e.g. `MemOp`); it is transport-agnostic and carries no filesystem
+ * dependency.
+ *
+ * Edge cases, matching the issue's spec:
+ * - `readLine` yields `null` (EOF) → the loop returns, a clean shutdown.
+ * - a malformed JSON line → a JSON-RPC parse-error response (`-32700`, `id`
+ *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
+ * - the step yields `null` (a notification needing no reply) → nothing is
+ *   written and the loop continues.
+ * - a response that doesn't fit in one encoded line (`tryUtf8` overflow —
+ *   `maxLength`, 128 KiB) never throws. `writeResponse` retries with a fixed,
+ *   small `-32603` internal-error body carrying the original `id`; if even
+ *   that overflows (a pathological caller-controlled `id`, e.g. a very large
+ *   string), it retries once more with `id: null` — a fully constant response
+ *   shape that is always small enough to encode. Every request that reaches
+ *   `step` therefore gets *some* response line, never silence and never a
+ *   crashed process.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../../../media/json/types.ts'
+ * @import { Effect, Operation } from '../../../effects/types.ts'
+ * @import { IoResult, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Response } from '../../json_rpc/types.ts'
+ */
+import type { Unknown } from '../../../media/json/types.ts';
+import type { Effect, Operation } from '../../../effects/types.ts';
+import type { Read, Write } from '../../../effects/node/types.ts';
+import type { Response } from '../../json_rpc/types.ts';
+export type Step<O extends Operation> = (value: Unknown) => Effect<O, Response | null>;
+/**
+ * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
+ *
+ * Recurses after each handled line; terminates (resolving to `void`) when
+ * `readLine` reports EOF.
+ *
+ * @template {Operation} O
+ * @param {Step<O>} handler
+ * @returns {Effect<Read | Write | O, void>}
+ */
+export declare const stdioTransport: <O extends Operation>(handler: Step<O>) => Effect<Read | Write | O, void>;

package/fjs/protocol/mcp/stdio/module.f.mjs

@@ -0,0 +1,132 @@
+/**
+ * stdio transport for JSON-RPC / MCP servers.
+ *
+ * `stdioTransport` wraps a step function — the `mcpStep`-shaped
+ * `(value) => Effect<O, Response | null>` from `fjs/protocol/mcp/module.f.mjs` — in the
+ * canonical read → parse → dispatch → write loop, expressed as a recursive
+ * effect so it stays in the pure effect model and is fully testable against a
+ * mock stdin / stdout (see `fjs/effects/node/virtual`) with no real process.
+ *
+ * The loop only consumes `Read` (stdin, one byte at a time, via the pure
+ * `readLine` combinator) and emits `Write` (stdout) on top of whatever `O` the
+ * step needs (e.g. `MemOp`); it is transport-agnostic and carries no filesystem
+ * dependency.
+ *
+ * Edge cases, matching the issue's spec:
+ * - `readLine` yields `null` (EOF) → the loop returns, a clean shutdown.
+ * - a malformed JSON line → a JSON-RPC parse-error response (`-32700`, `id`
+ *   `null`) is written rather than silently discarded, per JSON-RPC 2.0 §5.
+ * - the step yields `null` (a notification needing no reply) → nothing is
+ *   written and the loop continues.
+ * - a response that doesn't fit in one encoded line (`tryUtf8` overflow —
+ *   `maxLength`, 128 KiB) never throws. `writeResponse` retries with a fixed,
+ *   small `-32603` internal-error body carrying the original `id`; if even
+ *   that overflows (a pathological caller-controlled `id`, e.g. a very large
+ *   string), it retries once more with `id: null` — a fully constant response
+ *   shape that is always small enough to encode. Every request that reaches
+ *   `step` therefore gets *some* response line, never silence and never a
+ *   crashed process.
+ *
+ * @module
+ *
+ * @import { Unknown } from '../../../media/json/types.ts'
+ * @import { Effect, Operation } from '../../../effects/types.ts'
+ * @import { IoResult, Read, Write } from '../../../effects/node/types.ts'
+ * @import { Response } from '../../json_rpc/types.ts'
+ */
+
+import { pure, step } from '../../../effects/module.f.mjs'
+import { readLine, write } from '../../../effects/node/module.f.mjs'
+import { tryUtf8 } from '../../../text/module.f.mjs'
+import { parse, stringify } from '../../../media/json/module.f.mjs'
+import { sort } from '../../../types/object/module.f.mjs'
+import { internalError, jsonrpc, parseError } from '../../json_rpc/module.f.mjs'
+import { error, ok } from '../../../types/result/module.f.mjs'
+
+/**
+ * A transport step: maps one parsed JSON-RPC message to a response, or `null`
+ * for a notification that needs no reply. The shape of `mcpStep(config)(handlers)(key)`.
+ * @template {Operation} O
+ * @typedef {(value: Unknown) => Effect<O, Response | null>} Step
+ */
+
+const stringifyJson = stringify(sort)
+
+/** The parse-error response (`-32700`, `id: null`) for a malformed input line. */
+/** @type {Response} */
+const parseErrorResponse = { jsonrpc, error: parseError, id: null }
+
+/** An internal-error response (`-32603`) carrying `id`.
+ * @type {(id: Response['id']) => Response}
+ */
+const internalErrorResponse = id => ({ jsonrpc, error: internalError, id })
+
+/** Encodes a response as a newline-terminated UTF-8 line and writes it to `stdout`.
+ * @type {(resp: Response) => Effect<Write, IoResult<void>>}
+ */
+const writeResponse = resp => {
+    const v = tryUtf8(stringifyJson(resp) + '\n')
+    return v === null
+        ? pure(error(undefined))
+        : step(
+            write('stdout', v),
+            () => pure(ok(undefined)),
+        )
+}
+
+/**
+ * Drives the read-parse-dispatch-write loop for `handler` over stdin/stdout.
+ *
+ * Recurses after each handled line; terminates (resolving to `void`) when
+ * `readLine` reports EOF.
+ *
+ * @template {Operation} O
+ * @param {Step<O>} handler
+ * @returns {Effect<Read | Write | O, void>}
+ */
+export const stdioTransport = handler =>
+    step(
+        readLine('stdin'),
+        line => line === null
+            ? pure(undefined)
+            : handleLine(handler)(line),
+    )
+
+/**
+ * @template {Operation} O
+ * @param {Step<O>} handler
+ * @returns {(line: string) => Effect<Read | Write | O, void>}
+ */
+const handleLine = handler => line => {
+    const [t, value] = parse(line)
+    return step(
+        t === 'error'
+            ? writeResponse(parseErrorResponse)
+            : step(
+                handler(value),
+                resp => resp === null
+                    ? pure(undefined)
+                    : step(
+                        writeResponse(resp),
+                        ([t2]) => t2 === 'error'
+                            // The real response didn't fit. Retry with a fixed, small
+                            // internal-error body carrying `resp.id` — but a
+                            // caller-controlled `id` (e.g. a very large string) can
+                            // itself push even this fallback over `maxLength`, so
+                            // that retry is bounded by one more: an `id: null`
+                            // internal-error, whose fully-constant shape is the only
+                            // line in this transport guaranteed to always encode.
+                            ? step(
+                                writeResponse(internalErrorResponse(resp.id)),
+                                ([t3]) => t3 === 'error'
+                                    ? step(
+                                        writeResponse(internalErrorResponse(null)),
+                                        () => pure(undefined),
+                                    )
+                                    : pure(undefined)
+                            )
+                            : pure(undefined)),
+            ),
+        () => stdioTransport(handler),
+    )
+}

package/fjs/protocol/mcp/stdio/proof.f.d.mts

@@ -0,0 +1,20 @@
+/**
+ * @import { Unknown } from '../../../media/json/types.ts'
+ * @import { Effect } from '../../../effects/types.ts'
+ * @import { State } from '../../../effects/node/virtual/types.ts'
+ * @import { Id, Response } from '../../json_rpc/types.ts'
+ * @import { Step } from './module.f.mjs'
+ */
+export declare const proof: {
+    eofImmediately: () => void;
+    requestWritesResponse: () => void;
+    requestWithoutTrailingNewline: () => void;
+    notificationWritesNothing: () => void;
+    malformedJsonWritesParseError: () => void;
+    trailingCommaWritesParseError: () => void;
+    undefinedFieldOmitted: () => void;
+    oversizedResponseWritesInternalError: () => void;
+    loopContinuesAfterOversizedResponse: () => void;
+    oversizedIdFallsBackToNullId: () => void;
+    multipleLines: () => void;
+};