@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @monosmith/plugin-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript SDK for writing [smith](https://github.com/monosmith-app/monosmith) plugins: the
+protocol's types, the serve loop, a host to test a plugin with, the conformance checks of
+`smith plugin check`, `[[ ]]` templating and JSON editing that keeps key order. No runtime
+dependencies; Node.js 22 or later (24 to run a plugin written in TypeScript as it is).
+
+```sh
+npm install @monosmith/plugin-sdk
+```
+
+A plugin is an object with `describe` and one method for each thing it does. The SDK frames the
+JSON-RPC messages, answers `initialize`, derives the capabilities from the methods the object has and
+keeps standard output for the protocol:
+
+```ts
+#!/usr/bin/env node
+import { serve, task, contributeTo } from '@monosmith/plugin-sdk'
+
+await serve({
+  describe: () => ({ plugin: { name: 'widget-lint', version: '0.1.0' }, kind: 'convention', roles: ['structure'], languages: ['widget'] }),
+  contribute: ({ projects }) => contributeTo(projects, () => ({
+    tasks: { 'layout-check': task(['node', 'check.js'], { cache: true }) },
+    dependsOn: { lint: ['layout-check'] },
+  })),
+})
+```
+
+Test it in-process, with the real handshake and framing, and run the same checks as
+`smith plugin check`:
+
+```ts
+import { checkPlugin, connectInProcess } from '@monosmith/plugin-sdk'
+
+const client = await connectInProcess(plugin, { workspaceRoot: dir })
+const report = await checkPlugin(client)
+if (!report.ok) throw new Error(report.failures())
+await client.close()
+```
+
+The full guide and API reference: [The TypeScript SDK](../../docs/plugins/creating/typescript-sdk.md).
+Examples that use it: [`structure-layout-node`](../../docs/examples/plugins/structure-layout-node) and
+[`language-widget-ts`](../../docs/examples/plugins/language-widget-ts).
+
+## The protocol schema is the source of truth
+
+The types in `src/protocol` are not written by hand. The Go types of the protocol
+(`packages/plugin-sdk/protocol`) are the source of truth; their JSON Schema is committed as
+[`packages/plugin-sdk/schema/protocol.schema.json`](../plugin-sdk/schema/protocol.schema.json), and
+`tools/generate-protocol` turns that into `protocol-types.contract.ts` (the interfaces, the methods
+table, the error codes) and `protocol-schema.contract.ts` (the schema itself, which the wire codec and the
+host's capability check read at run time). After a change to the protocol:
+
+```sh
+smith run schema -p plugin-sdk          # the Go side writes the schema
+smith run generate -p plugin-sdk-ts     # this side writes the types
+```
+
+Two tests fail when either file is stale: the Go test `TestCommittedSchemaIsCurrent` and
+`tools/generate-protocol/generate-protocol.use-case.spec.ts` (`smith run generate-check -p plugin-sdk-ts`
+checks without writing). A test also fails when the schema has a method this SDK does not know how to
+serve (`PLUGIN_MEMBERS`), so a new method has to be given its place in the plugin object.
+
+## What is where
+
+| Folder of `src` | What it holds |
+|---|---|
+| `protocol` | the generated types, the schema as data, `RpcError` |
+| `codec` | the wire form of the messages: key order, `omitempty`, sorted maps and escaping as the Go SDK writes them, so the bytes are equal; params shaped as the types promise |
+| `framing` | `Content-Length` framing over a byte stream |
+| `serve` | `serve`, `serveStreams`, the plugin interfaces, capability derivation |
+| `host` | `startPlugin`, `connectPlugin`, `connectInProcess`, `PluginClient`: the host side, for tests |
+| `conformance` | `checkPlugin`: the checks of `smith plugin check` |
+| `templating`, `jsondoc` | ports of the Go SDK's `templating` and `jsondoc` |
+| `tasks`, `scaffold`, `ci` | helpers to build the answers of contribute, generate and ci |
+| `build-dir`, `plugin-roles`, `plugin-refs`, `projects` | the protocol package's small functions: build directories, roles, plugin references, project kinds, manifests |
+
+The source is organised by vertical slices (`smith` lints it); `integration` holds the tests that start
+real processes: the examples under `smith plugin check` and in a throwaway workspace, and the
+compatibility test that a TypeScript plugin and a Go plugin with the same logic answer with the same
+bytes.
+
+## Develop
+
+```sh
+smith run lint typecheck test build -p plugin-sdk-ts
+```
+
+The integration tests need `smith` and `go` on the path and skip themselves without them. The package
+is released by smith from conventional commits, like the other packages of this repository.

package/build-dir/build-dir.algorithm.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The directory at the workspace root every build writes into: smith's opinion,
+ * so all output is in one place, outside every source tree, and cleaning is
+ * deleting one folder. A plugin builds a project into {@link projectBuildDir};
+ * `smith doctor` fails a task whose outputs fall outside it.
+ */
+export declare const BUILD_DIR = "dist";
+/** Where a project's build goes, workspace-relative: `dist/<project dir>`, mirroring the workspace (`dist/apps/web`). */
+export declare function projectBuildDir(root: string): string;
+/**
+ * The same directory relative to the project (`../../dist/apps/web`): what a
+ * tool configured from inside the project, or a task's `outputs`, name.
+ */
+export declare function buildDirFromProject(root: string): string;
+/** Whether a workspace-relative path is inside the build directory. */
+export declare function inBuildDir(path: string): boolean;

package/build-dir/build-dir.algorithm.js

@@ -0,0 +1,26 @@
+/**
+ * The directory at the workspace root every build writes into: smith's opinion,
+ * so all output is in one place, outside every source tree, and cleaning is
+ * deleting one folder. A plugin builds a project into {@link projectBuildDir};
+ * `smith doctor` fails a task whose outputs fall outside it.
+ */
+export const BUILD_DIR = 'dist';
+function trimSlashes(root) {
+    return root.replaceAll(/^\/+|\/+$/g, '');
+}
+/** Where a project's build goes, workspace-relative: `dist/<project dir>`, mirroring the workspace (`dist/apps/web`). */
+export function projectBuildDir(root) {
+    return `${BUILD_DIR}/${trimSlashes(root)}`;
+}
+/**
+ * The same directory relative to the project (`../../dist/apps/web`): what a
+ * tool configured from inside the project, or a task's `outputs`, name.
+ */
+export function buildDirFromProject(root) {
+    const trimmed = trimSlashes(root);
+    return '../'.repeat(trimmed.split('/').length) + projectBuildDir(trimmed);
+}
+/** Whether a workspace-relative path is inside the build directory. */
+export function inBuildDir(path) {
+    return path === BUILD_DIR || path.startsWith(`${BUILD_DIR}/`);
+}

package/build-dir/index.d.ts

@@ -0,0 +1 @@
+export { BUILD_DIR, buildDirFromProject, inBuildDir, projectBuildDir } from './build-dir.algorithm.ts';

package/build-dir/index.js

@@ -0,0 +1 @@
+export { BUILD_DIR, buildDirFromProject, inBuildDir, projectBuildDir } from './build-dir.algorithm.js';

package/ci/ci-contribution.algorithm.d.ts

@@ -0,0 +1,28 @@
+import type { ActionStep, Credential, Step } from '../protocol/index.ts';
+/**
+ * A provider-native step: a GitHub action (`'actions/setup-node@v6'`) or an
+ * Azure task (`'NodeTool@0'`) with its inputs, written in the order given. The
+ * values of a pipeline are written as quoted YAML strings, except `true` and
+ * `false`, so pass strings.
+ */
+export declare function actionStep(uses: string, inputs?: Record<string, string> | Array<[string, string]>): ActionStep;
+export interface StepOptions {
+    /** The workspace-relative directory to run in. Default: the workspace root. */
+    dir?: string;
+    /** Whether a failure fails the phase (the default) or only warns. */
+    blocking?: boolean;
+    /** Workspace-relative files whose content decides what an audit step finds (a lockfile): smith skips a passing step while they are unchanged. */
+    cacheFiles?: string[];
+}
+/** One command a CI phase (`setup`, `audit`, `postRelease`) runs. It blocks unless `blocking: false`. */
+export declare function ciStep(name: string, command: string[], options?: StepOptions): Step;
+export interface CredentialOptions {
+    /** Release works without it. Default: it is required. */
+    required?: boolean;
+    /** Also give it to `smith ci setup`: installs from a private registry need it. */
+    setup?: boolean;
+    /** Also give it to every step that runs tasks. */
+    tasks?: boolean;
+}
+/** A secret the release phase needs, read from the environment variable `env`. */
+export declare function credential(env: string, description: string, options?: CredentialOptions): Credential;

package/ci/ci-contribution.algorithm.js

@@ -0,0 +1,19 @@
+/**
+ * A provider-native step: a GitHub action (`'actions/setup-node@v6'`) or an
+ * Azure task (`'NodeTool@0'`) with its inputs, written in the order given. The
+ * values of a pipeline are written as quoted YAML strings, except `true` and
+ * `false`, so pass strings.
+ */
+export function actionStep(uses, inputs = {}) {
+    const pairs = Array.isArray(inputs) ? inputs : Object.entries(inputs);
+    return pairs.length === 0 ? { uses } : { uses, inputs: pairs.map(([name, value]) => ({ name, value })) };
+}
+/** One command a CI phase (`setup`, `audit`, `postRelease`) runs. It blocks unless `blocking: false`. */
+export function ciStep(name, command, options = {}) {
+    const { dir, cacheFiles } = options;
+    return { name, command, blocking: options.blocking ?? true, ...(dir !== undefined && { dir }), ...(cacheFiles !== undefined && { cacheFiles }) };
+}
+/** A secret the release phase needs, read from the environment variable `env`. */
+export function credential(env, description, options = {}) {
+    return { env, description, required: options.required ?? true, ...((options.setup === true) && { setup: true }), ...((options.tasks === true) && { tasks: true }) };
+}

package/ci/index.d.ts

@@ -0,0 +1,2 @@
+export { actionStep, ciStep, credential } from './ci-contribution.algorithm.ts';
+export type { CredentialOptions, StepOptions } from './ci-contribution.algorithm.ts';

package/ci/index.js

@@ -0,0 +1 @@
+export { actionStep, ciStep, credential } from './ci-contribution.algorithm.js';

package/codec/encode-by-schema.algorithm.d.ts

@@ -0,0 +1,12 @@
+import type { SchemaDocument, SchemaNode } from '../protocol/index.ts';
+/**
+ * Writes a value as the JSON the Go SDK would write for the same message:
+ * the members of a message in the order the schema lists them (the order of the
+ * Go fields), an optional member left out when it is absent or holds the
+ * zero value Go's `omitempty` drops (`""`, `0`, `false`, an empty array or
+ * map), the keys of a map sorted, HTML characters escaped. So the bytes a TypeScript
+ * plugin writes equal the bytes a Go plugin writes for the same answer.
+ *
+ * It throws {@link EncodeError} for a required member that is missing or a value of the wrong type.
+ */
+export declare function encodeBySchema(schema: SchemaDocument, node: SchemaNode, value: unknown, path: string): string;

package/codec/encode-by-schema.algorithm.js

@@ -0,0 +1,105 @@
+import { EncodeError } from './encode-error.error.js';
+import { compareKeys, encodeJsonString, encodeJsonValue } from './encode-json-value.algorithm.js';
+import { baseNode, isNullable, kindOf } from './schema-lookup.algorithm.js';
+/**
+ * Writes a value as the JSON the Go SDK would write for the same message:
+ * the members of a message in the order the schema lists them (the order of the
+ * Go fields), an optional member left out when it is absent or holds the
+ * zero value Go's `omitempty` drops (`""`, `0`, `false`, an empty array or
+ * map), the keys of a map sorted, HTML characters escaped. So the bytes a TypeScript
+ * plugin writes equal the bytes a Go plugin writes for the same answer.
+ *
+ * It throws {@link EncodeError} for a required member that is missing or a value of the wrong type.
+ */
+export function encodeBySchema(schema, node, value, path) {
+    const kind = kindOf(schema, node);
+    if (value === null || value === undefined) {
+        if (isNullable(node) || (kind === 'any' && value === null))
+            return 'null';
+        throw new EncodeError(`${path} is required${value === null ? ' and cannot be null' : ''}`);
+    }
+    const base = baseNode(schema, node);
+    switch (kind) {
+        case 'string': {
+            if (typeof value !== 'string')
+                throw wrongType(path, 'a string', value);
+            return encodeJsonString(value);
+        }
+        case 'integer': {
+            if (typeof value !== 'number' || !Number.isSafeInteger(value))
+                throw wrongType(path, 'an integer', value);
+            return String(value);
+        }
+        case 'number': {
+            if (typeof value !== 'number' || !Number.isFinite(value))
+                throw wrongType(path, 'a number', value);
+            return String(value);
+        }
+        case 'boolean': {
+            if (typeof value !== 'boolean')
+                throw wrongType(path, 'a boolean', value);
+            return value ? 'true' : 'false';
+        }
+        case 'array': {
+            if (!Array.isArray(value))
+                throw wrongType(path, 'an array', value);
+            const items = base.items ?? {};
+            return `[${value.map((item, i) => encodeBySchema(schema, items, item, `${path}[${i}]`)).join(',')}]`;
+        }
+        case 'map': {
+            if (!isPlainObject(value))
+                throw wrongType(path, 'an object', value);
+            const values = typeof base.additionalProperties === 'object' ? base.additionalProperties : {};
+            const members = Object.entries(value)
+                .filter(([, member]) => member !== undefined)
+                .sort(([a], [b]) => compareKeys(a, b))
+                .map(([name, member]) => `${encodeJsonString(name)}:${encodeBySchema(schema, values, member, `${path}.${name}`)}`);
+            return `{${members.join(',')}}`;
+        }
+        case 'struct': {
+            if (!isPlainObject(value))
+                throw wrongType(path, 'an object', value);
+            return encodeStruct(schema, base, value, path);
+        }
+        default: {
+            return encodeJsonValue(value, path);
+        }
+    }
+}
+function encodeStruct(schema, base, value, path) {
+    const properties = base.properties ?? {};
+    const required = new Set(base.required);
+    const members = [];
+    for (const [name, property] of Object.entries(properties)) {
+        const member = value[name];
+        if (!required.has(name) && isOmitted(schema, property, member))
+            continue;
+        members.push(`${encodeJsonString(name)}:${encodeBySchema(schema, property, member, `${path}.${name}`)}`);
+    }
+    // Members the schema does not know (a protocol that grew past this SDK) are kept, after the known ones.
+    const known = new Set(Object.keys(properties));
+    const unknown = Object.keys(value).filter(name => !known.has(name) && value[name] !== undefined).sort(compareKeys);
+    for (const name of unknown)
+        members.push(`${encodeJsonString(name)}:${encodeJsonValue(value[name], `${path}.${name}`)}`);
+    return `{${members.join(',')}}`;
+}
+/** Go's `omitempty`: absent, null, or the zero value of a scalar, array or map. A struct is never empty. */
+function isOmitted(schema, property, member) {
+    if (member === undefined || member === null)
+        return true;
+    const kind = kindOf(schema, property);
+    if (kind === 'string')
+        return member === '';
+    if (kind === 'integer' || kind === 'number')
+        return member === 0;
+    if (kind === 'boolean')
+        return member === false;
+    return kind === 'array' ? Array.isArray(member) && member.length === 0 : kind === 'map' && isPlainObject(member) && Object.values(member).every(v => v === undefined);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function wrongType(path, expected, value) {
+    const got = Array.isArray(value) ? 'an array' : (typeof value === 'object' ? 'an object' : `a ${typeof value}`);
+    return new EncodeError(`${path} must be ${expected}, not ${got}`);
+}

package/codec/encode-error.error.d.ts

@@ -0,0 +1,4 @@
+/** A value that cannot be written as the message the schema describes: a required member is missing, or a member has the wrong type. */
+export declare class EncodeError extends Error {
+    constructor(message: string);
+}

package/codec/encode-error.error.js

@@ -0,0 +1,7 @@
+/** A value that cannot be written as the message the schema describes: a required member is missing, or a member has the wrong type. */
+export class EncodeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EncodeError';
+    }
+}

package/codec/encode-json-value.algorithm.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A string as the Go SDK writes it: JSON escaping, and `<`, `>`, `&`, U+2028
+ * and U+2029 as `\u` escapes (Go's `json.Marshal` escapes HTML by default). Both
+ * forms decode to the same text; writing Go's makes the two SDKs' bytes equal.
+ */
+export declare function encodeJsonString(text: string): string;
+/** Go sorts the keys of a map by their UTF-8 bytes. */
+export declare function compareKeys(a: string, b: string): number;
+/**
+ * Any JSON value as the Go SDK writes a `map[string]any`: object keys sorted,
+ * members whose value is `undefined` left out.
+ */
+export declare function encodeJsonValue(value: unknown, path: string): string;

package/codec/encode-json-value.algorithm.js

@@ -0,0 +1,51 @@
+import { EncodeError } from './encode-error.error.js';
+/**
+ * A string as the Go SDK writes it: JSON escaping, and `<`, `>`, `&`, U+2028
+ * and U+2029 as `\u` escapes (Go's `json.Marshal` escapes HTML by default). Both
+ * forms decode to the same text; writing Go's makes the two SDKs' bytes equal.
+ */
+export function encodeJsonString(text) {
+    return JSON.stringify(text)
+        .replaceAll('<', String.raw `\u003c`)
+        .replaceAll('>', String.raw `\u003e`)
+        .replaceAll('&', String.raw `\u0026`)
+        .replaceAll('\u{2028}', String.raw `\u2028`)
+        .replaceAll('\u{2029}', String.raw `\u2029`);
+}
+/** Go sorts the keys of a map by their UTF-8 bytes. */
+export function compareKeys(a, b) {
+    return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+/**
+ * Any JSON value as the Go SDK writes a `map[string]any`: object keys sorted,
+ * members whose value is `undefined` left out.
+ */
+export function encodeJsonValue(value, path) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'string': {
+            return encodeJsonString(value);
+        }
+        case 'boolean': {
+            return value ? 'true' : 'false';
+        }
+        case 'number': {
+            if (!Number.isFinite(value))
+                throw new EncodeError(`${path}: ${value} cannot be written as JSON`);
+            return String(value);
+        }
+        case 'object': {
+            if (Array.isArray(value))
+                return `[${value.map((item, i) => encodeJsonValue(item === undefined ? null : item, `${path}[${i}]`)).join(',')}]`;
+            const members = Object.entries(value)
+                .filter(([, member]) => member !== undefined)
+                .sort(([a], [b]) => compareKeys(a, b))
+                .map(([name, member]) => `${encodeJsonString(name)}:${encodeJsonValue(member, `${path}.${name}`)}`);
+            return `{${members.join(',')}}`;
+        }
+        default: {
+            throw new EncodeError(`${path}: a ${typeof value} cannot be written as JSON`);
+        }
+    }
+}

package/codec/index.d.ts

@@ -0,0 +1,6 @@
+export { decodeParams, decodeResult, encodeParams, encodeResult } from './method-codec.algorithm.ts';
+export { EncodeError } from './encode-error.error.ts';
+export { ParamsError } from './params-error.error.ts';
+export { MessageParseError } from './message-parse.error.ts';
+export { parseRequest, parseResponse, writeFailure, writeRequest, writeResult } from './wire-message.mapper.ts';
+export type { ReceivedRequest, ReceivedResponse } from './wire-message.mapper.ts';

package/codec/index.js

@@ -0,0 +1,5 @@
+export { decodeParams, decodeResult, encodeParams, encodeResult } from './method-codec.algorithm.js';
+export { EncodeError } from './encode-error.error.js';
+export { ParamsError } from './params-error.error.js';
+export { MessageParseError } from './message-parse.error.js';
+export { parseRequest, parseResponse, writeFailure, writeRequest, writeResult } from './wire-message.mapper.js';

package/codec/message-parse.error.d.ts

@@ -0,0 +1,4 @@
+/** A frame whose body is not a JSON-RPC 2.0 message of the shape the protocol uses. The serve loop answers it with the code ParseError. */
+export declare class MessageParseError extends Error {
+    constructor(message: string);
+}

package/codec/message-parse.error.js

@@ -0,0 +1,7 @@
+/** A frame whose body is not a JSON-RPC 2.0 message of the shape the protocol uses. The serve loop answers it with the code ParseError. */
+export class MessageParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MessageParseError';
+    }
+}

package/codec/method-codec.algorithm.d.ts

@@ -0,0 +1,8 @@
+/** The params of a request, written as the Go SDK writes them; a method the protocol does not know is written as plain JSON. */
+export declare function encodeParams(method: string, params: unknown): string;
+/** The result of a method, written as the Go SDK writes it. */
+export declare function encodeResult(method: string, result: unknown): string;
+/** The params of a received request, shaped as the generated types promise (see normalizeBySchema). Absent params are an empty object. */
+export declare function decodeParams(method: string, params: unknown): unknown;
+/** The result of a received response, shaped as the generated types promise. */
+export declare function decodeResult(method: string, result: unknown): unknown;

package/codec/method-codec.algorithm.js

@@ -0,0 +1,31 @@
+import { protocolSchema } from '../protocol/index.js';
+import { encodeBySchema } from './encode-by-schema.algorithm.js';
+import { encodeJsonValue } from './encode-json-value.algorithm.js';
+import { normalizeBySchema } from './normalize-by-schema.algorithm.js';
+function rowOf(method) {
+    return Object.hasOwn(protocolSchema['x-methods'], method) ? protocolSchema['x-methods'][method] : undefined;
+}
+/** The params of a request, written as the Go SDK writes them; a method the protocol does not know is written as plain JSON. */
+export function encodeParams(method, params) {
+    return encode(method, 'params', params);
+}
+/** The result of a method, written as the Go SDK writes it. */
+export function encodeResult(method, result) {
+    return encode(method, 'result', result);
+}
+/** The params of a received request, shaped as the generated types promise (see normalizeBySchema). Absent params are an empty object. */
+export function decodeParams(method, params) {
+    return decode(method, 'params', params ?? {});
+}
+/** The result of a received response, shaped as the generated types promise. */
+export function decodeResult(method, result) {
+    return decode(method, 'result', result ?? {});
+}
+function encode(method, side, value) {
+    const row = rowOf(method);
+    return row === undefined ? encodeJsonValue(value, side) : encodeBySchema(protocolSchema, row[side], value, side);
+}
+function decode(method, side, value) {
+    const row = rowOf(method);
+    return row === undefined ? value : normalizeBySchema(protocolSchema, row[side], value, side);
+}

package/codec/normalize-by-schema.algorithm.d.ts

@@ -0,0 +1,14 @@
+import type { SchemaDocument, SchemaNode } from '../protocol/index.ts';
+/**
+ * Shapes a received value the way the Go SDK's decoder does, so the types the
+ * generated interfaces promise hold:
+ *
+ * - a required member that is absent or `null` is its zero value (`[]`, `{}`,
+ *   `''`, `0`, `false`): the Go host writes a nil slice as `null`;
+ * - an optional member that is `null` is removed;
+ * - members the schema does not know stay as they are.
+ *
+ * It throws {@link ParamsError} where a value has the wrong JSON type. The
+ * value is edited in place and returned.
+ */
+export declare function normalizeBySchema(schema: SchemaDocument, node: SchemaNode, value: unknown, path: string, depth?: number): unknown;

package/codec/normalize-by-schema.algorithm.js

@@ -0,0 +1,103 @@
+import { ParamsError } from './params-error.error.js';
+import { baseNode, isNullable, kindOf } from './schema-lookup.algorithm.js';
+const MAX_DEPTH = 64;
+/** The JSON test and the words for the error of each scalar kind. */
+const SCALARS = {
+    string: { is: value => typeof value === 'string', article: 'a string' },
+    integer: { is: value => typeof value === 'number' && Number.isSafeInteger(value), article: 'an integer' },
+    number: { is: value => typeof value === 'number', article: 'a number' },
+    boolean: { is: value => typeof value === 'boolean', article: 'a boolean' },
+};
+/**
+ * Shapes a received value the way the Go SDK's decoder does, so the types the
+ * generated interfaces promise hold:
+ *
+ * - a required member that is absent or `null` is its zero value (`[]`, `{}`,
+ *   `''`, `0`, `false`): the Go host writes a nil slice as `null`;
+ * - an optional member that is `null` is removed;
+ * - members the schema does not know stay as they are.
+ *
+ * It throws {@link ParamsError} where a value has the wrong JSON type. The
+ * value is edited in place and returned.
+ */
+export function normalizeBySchema(schema, node, value, path, depth = 0) {
+    if (depth > MAX_DEPTH)
+        throw new ParamsError(`${path} is nested too deeply`);
+    if (value === null || value === undefined)
+        return isNullable(node) ? null : zeroOf(schema, node, path, depth);
+    const kind = kindOf(schema, node);
+    const base = baseNode(schema, node);
+    const scalar = SCALARS[kind];
+    if (scalar !== undefined) {
+        if (!scalar.is(value))
+            throw wrongType(path, scalar.article, value);
+        return value;
+    }
+    if (kind === 'array') {
+        if (!Array.isArray(value))
+            throw wrongType(path, 'an array', value);
+        return value.map((item, i) => normalizeBySchema(schema, base.items ?? {}, item, `${path}[${i}]`, depth + 1));
+    }
+    if (kind === 'map')
+        return normalizeMap(schema, base, value, path, depth);
+    return kind === 'struct' ? normalizeStruct(schema, base, value, path, depth) : value;
+}
+function normalizeMap(schema, base, value, path, depth) {
+    if (!isObject(value))
+        throw wrongType(path, 'an object', value);
+    const values = typeof base.additionalProperties === 'object' ? base.additionalProperties : {};
+    const keepsNull = kindOf(schema, values) === 'any';
+    for (const [name, member] of Object.entries(value)) {
+        if (member !== null)
+            value[name] = normalizeBySchema(schema, values, member, `${path}.${name}`, depth + 1);
+        else if (!keepsNull)
+            delete value[name];
+    }
+    return value;
+}
+function normalizeStruct(schema, base, value, path, depth) {
+    if (!isObject(value))
+        throw wrongType(path, 'an object', value);
+    const required = new Set(base.required);
+    const properties = Object.entries(base.properties ?? {});
+    for (const [name, property] of properties) {
+        const member = value[name];
+        const at = `${path}.${name}`;
+        if (member !== undefined && member !== null) {
+            value[name] = normalizeBySchema(schema, property, member, at, depth + 1);
+        }
+        else if (required.has(name)) {
+            const zero = zeroOf(schema, property, at, depth + 1);
+            if (zero !== undefined)
+                value[name] = zero;
+        }
+        else {
+            delete value[name];
+        }
+    }
+    return value;
+}
+/** The value Go's decoder leaves in a member the message did not carry. */
+function zeroOf(schema, node, path, depth) {
+    if (isNullable(node))
+        return null;
+    const kind = kindOf(schema, node);
+    if (kind === 'string')
+        return '';
+    if (kind === 'integer' || kind === 'number')
+        return 0;
+    if (kind === 'boolean')
+        return false;
+    if (kind === 'array')
+        return [];
+    if (kind === 'map')
+        return {};
+    return kind === 'struct' ? normalizeBySchema(schema, node, {}, path, depth + 1) : undefined;
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function wrongType(path, expected, value) {
+    const got = Array.isArray(value) ? 'an array' : (typeof value === 'object' ? 'an object' : `a ${typeof value}`);
+    return new ParamsError(`${path} must be ${expected}, not ${got}`);
+}

package/codec/params-error.error.d.ts

@@ -0,0 +1,4 @@
+/** A received message whose params (or result) do not have the shape the schema describes. The serve loop answers it with the code InvalidParams. */
+export declare class ParamsError extends Error {
+    constructor(message: string);
+}

package/codec/params-error.error.js

@@ -0,0 +1,7 @@
+/** A received message whose params (or result) do not have the shape the schema describes. The serve loop answers it with the code InvalidParams. */
+export class ParamsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParamsError';
+    }
+}

package/codec/schema-lookup.algorithm.d.ts

@@ -0,0 +1,13 @@
+import type { SchemaDocument, SchemaNode } from '../protocol/index.ts';
+/** What a schema node holds, as far as the codec cares. */
+export type NodeKind = 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'struct' | 'map' | 'any';
+/** Follows `$ref` to the definition it names. */
+export declare function resolveNode(schema: SchemaDocument, node: SchemaNode): SchemaNode;
+/** Whether `null` is a value of the node: `["integer", "null"]`, or an `anyOf` with null. */
+export declare function isNullable(node: SchemaNode): boolean;
+/** The node without its `null` alternative. */
+export declare function withoutNull(schema: SchemaDocument, node: SchemaNode): SchemaNode;
+/** The kind of value a node describes, after `$ref` and null are set aside. */
+export declare function kindOf(schema: SchemaDocument, node: SchemaNode): NodeKind;
+/** The node as the codec walks it: nullability removed, references followed. */
+export declare function baseNode(schema: SchemaDocument, node: SchemaNode): SchemaNode;