@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/codec/schema-lookup.algorithm.js

@@ -0,0 +1,56 @@
+/** Follows `$ref` to the definition it names. */
+export function resolveNode(schema, node) {
+    let current = node;
+    for (let hops = 0; current.$ref !== undefined; hops++) {
+        const name = current.$ref.slice('#/$defs/'.length);
+        const target = schema.$defs[name];
+        if (target === undefined || hops > 16)
+            throw new Error(`the schema has no definition ${current.$ref}`);
+        current = target;
+    }
+    return current;
+}
+/** Whether `null` is a value of the node: `["integer", "null"]`, or an `anyOf` with null. */
+export function isNullable(node) {
+    return Array.isArray(node.type) ? node.type.includes('null') : node.anyOf?.some(branch => branch.type === 'null') ?? false;
+}
+/** The node without its `null` alternative. */
+export function withoutNull(schema, node) {
+    if (Array.isArray(node.type)) {
+        const types = node.type.filter(t => t !== 'null');
+        return { ...node, type: types.length === 1 ? types[0] : types };
+    }
+    const branches = node.anyOf?.filter(branch => branch.type !== 'null');
+    return branches !== undefined && branches.length === 1 ? resolveNode(schema, branches[0]) : node;
+}
+/** The kind of value a node describes, after `$ref` and null are set aside. */
+export function kindOf(schema, node) {
+    const base = resolveNode(schema, withoutNull(schema, node));
+    switch (base.type) {
+        case 'string': {
+            return 'string';
+        }
+        case 'integer': {
+            return 'integer';
+        }
+        case 'number': {
+            return 'number';
+        }
+        case 'boolean': {
+            return 'boolean';
+        }
+        case 'array': {
+            return 'array';
+        }
+        case 'object': {
+            return base.properties === undefined ? 'map' : 'struct';
+        }
+        default: {
+            return 'any';
+        }
+    }
+}
+/** The node as the codec walks it: nullability removed, references followed. */
+export function baseNode(schema, node) {
+    return resolveNode(schema, withoutNull(schema, node));
+}

package/codec/wire-message.mapper.d.ts

@@ -0,0 +1,25 @@
+/** A request or notification as it was received. `id` is `null` for a notification. */
+export interface ReceivedRequest {
+    id: number | null;
+    method: string;
+    params: unknown;
+}
+/** A response as it was received. */
+export interface ReceivedResponse {
+    id: number | null;
+    result: unknown;
+    error: {
+        code: number;
+        message: string;
+    } | null;
+}
+/** A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params`, the params left out when there are none. */
+export declare function writeRequest(id: number, method: string, paramsJson: string | undefined): string;
+/** A successful response: `id` is `null` only when the request could not be read. */
+export declare function writeResult(id: number | null, resultJson: string): string;
+/** An error response. */
+export declare function writeFailure(id: number | null, code: number, message: string): string;
+/** Reads a request frame. A `null` or missing id makes it a notification. */
+export declare function parseRequest(body: string): ReceivedRequest;
+/** Reads a response frame. */
+export declare function parseResponse(body: string): ReceivedResponse;

package/codec/wire-message.mapper.js

@@ -0,0 +1,58 @@
+import { encodeJsonString } from './encode-json-value.algorithm.js';
+import { MessageParseError } from './message-parse.error.js';
+/** A request as the Go SDK writes it: `jsonrpc`, `id`, `method`, `params`, the params left out when there are none. */
+export function writeRequest(id, method, paramsJson) {
+    const params = paramsJson === undefined ? '' : `,"params":${paramsJson}`;
+    return `{"jsonrpc":"2.0","id":${id},"method":${encodeJsonString(method)}${params}}`;
+}
+/** A successful response: `id` is `null` only when the request could not be read. */
+export function writeResult(id, resultJson) {
+    return `{"jsonrpc":"2.0","id":${id === null ? 'null' : id},"result":${resultJson}}`;
+}
+/** An error response. */
+export function writeFailure(id, code, message) {
+    return `{"jsonrpc":"2.0","id":${id === null ? 'null' : id},"error":{"code":${code},"message":${encodeJsonString(message)}}}`;
+}
+function parseObject(body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (error) {
+        throw new MessageParseError(error instanceof Error ? error.message : String(error));
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new MessageParseError('a message is a JSON object');
+    return value;
+}
+function readId(message) {
+    const id = message.id;
+    if (id === undefined || id === null)
+        return null;
+    if (typeof id !== 'number' || !Number.isSafeInteger(id))
+        throw new MessageParseError('id must be an integer');
+    return id;
+}
+/** Reads a request frame. A `null` or missing id makes it a notification. */
+export function parseRequest(body) {
+    const message = parseObject(body);
+    const id = readId(message);
+    const method = message.method ?? '';
+    if (typeof method !== 'string')
+        throw new MessageParseError('method must be a string');
+    return { id, method, params: message.params };
+}
+/** Reads a response frame. */
+export function parseResponse(body) {
+    const message = parseObject(body);
+    const id = readId(message);
+    const error = message.error;
+    if (error === undefined || error === null)
+        return { id, result: message.result, error: null };
+    if (typeof error !== 'object' || Array.isArray(error))
+        throw new MessageParseError('error must be an object');
+    const { code, message: text } = error;
+    if (typeof code !== 'number' || typeof text !== 'string')
+        throw new MessageParseError('error needs a numeric code and a message');
+    return { id, result: undefined, error: { code, message: text } };
+}

package/conformance/check-generation.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { PluginClient } from '../host/index.ts';
+import type { ConformanceReport } from './conformance-report.model.ts';
+/** The stack name generated projects are asked to record. */
+export declare const CONFORMANCE_STACK = "conformance";
+/**
+ * Asks the plugin for one project of each kind, checks the files it reports
+ * exist, and, for a language plugin, that its own `discover` returns what it
+ * made, with the kind and the stack it was asked for, tasks with commands, and
+ * that the dry runs of `version/write`, `remove`, `publish` and `published`
+ * answer.
+ */
+export declare function checkGeneration(client: PluginClient, workspace: string, report: ConformanceReport): Promise<void>;

package/conformance/check-generation.use-case.js

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { effectiveRoles } from '../plugin-roles/index.js';
+import { projectKindDirectory } from '../projects/index.js';
+import { findManifests } from './find-manifests.algorithm.js';
+import { goList, goQuote } from './go-list.mapper.js';
+/** The stack name generated projects are asked to record. */
+export const CONFORMANCE_STACK = 'conformance';
+const LONG_MS = 20 * 60 * 1000;
+function article(kind) {
+    return kind === 'app' ? 'an app' : `a ${kind}`;
+}
+/**
+ * Asks the plugin for one project of each kind, checks the files it reports
+ * exist, and, for a language plugin, that its own `discover` returns what it
+ * made, with the kind and the stack it was asked for, tasks with commands, and
+ * that the dry runs of `version/write`, `remove`, `publish` and `published`
+ * answer.
+ */
+export async function checkGeneration(client, workspace, report) {
+    const language = effectiveRoles(client.info).includes('language');
+    const made = [];
+    for (const kind of ['app', 'lib', 'package']) {
+        const name = `c${kind}`;
+        const params = {
+            kind,
+            name,
+            directory: `${projectKindDirectory(kind)}/${name}`,
+            stack: CONFORMANCE_STACK,
+            workspace: { name: 'conformance', scope: '@conformance', modulePrefix: 'example.com/conformance' },
+        };
+        let files;
+        try {
+            const generated = await client.call('generate', params, { timeoutMs: LONG_MS });
+            files = generated.files;
+        }
+        catch (error) {
+            report.add(`generates ${article(kind)}`, false, messageOf(error));
+            continue;
+        }
+        const missing = files.filter(file => !existsSync(join(workspace, ...file.split('/'))));
+        report.add(`generates ${article(kind)}`, files.length > 0 && missing.length === 0, `files reported but not written: ${goList(missing)} (of ${goList(files)})`);
+        made.push(params);
+    }
+    if (!language || made.length === 0)
+        return;
+    let projects;
+    try {
+        const discovered = await client.call('discover', { manifests: findManifests(workspace, client.info.manifests ?? []) }, { timeoutMs: LONG_MS });
+        projects = discovered.projects;
+    }
+    catch (error) {
+        report.add('discovers what it generated', false, messageOf(error));
+        return;
+    }
+    const found = new Map(projects.map(project => [project.root, project]));
+    for (const params of made) {
+        const project = found.get(params.directory);
+        report.add(`discovers the generated ${params.kind}`, project !== undefined, `no project at ${params.directory} among ${projects.length} discovered`);
+        if (project === undefined)
+            continue;
+        report.add(`the generated ${params.kind} keeps its kind`, project.kind === params.kind, `discovered as ${goQuote(project.kind)}`);
+        report.add(`the generated ${params.kind} records its stack`, project.stack === CONFORMANCE_STACK, `discovered with stack ${goQuote(project.stack ?? '')}; generate must record params.stack in the manifest`);
+        const empty = Object.entries(project.tasks ?? {}).filter(([, task]) => task.command.length === 0).map(([name]) => name).sort((a, b) => a.localeCompare(b));
+        report.add(`the generated ${params.kind}'s tasks have commands`, empty.length === 0, `tasks without a command: ${goList(empty)}`);
+        if (client.supports('version/write')) {
+            await attempt(report, `writes the ${params.kind}'s version (dry run)`, () => client.call('version/write', { project, version: '1.2.3', dryRun: true }, { timeoutMs: 60_000 }));
+        }
+        if (client.supports('remove')) {
+            await attempt(report, `would remove the ${params.kind} (dry run)`, () => client.call('remove', { project, dryRun: true }, { timeoutMs: 60_000 }));
+        }
+        if (params.kind === 'package' && client.supports('publish')) {
+            await attempt(report, 'publishes the package (dry run)', () => client.call('publish', { project, version: '1.2.3', dryRun: true }, { timeoutMs: 5 * 60_000 }));
+        }
+        if (params.kind === 'package' && client.supports('published')) {
+            await attempt(report, 'says what the registry has of the package', () => client.call('published', { project }, { timeoutMs: 60_000 }), ' (an unreachable registry is a result, not an error)');
+        }
+    }
+}
+async function attempt(report, check, call, hint = '') {
+    try {
+        await call();
+        report.add(check, true, '');
+    }
+    catch (error) {
+        report.add(check, false, `${messageOf(error)}${hint}`);
+    }
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}

package/conformance/check-plugin.use-case.d.ts

@@ -0,0 +1,24 @@
+import type { PluginClient } from '../host/index.ts';
+import { ConformanceReport } from './conformance-report.model.ts';
+/** Options of {@link checkPlugin}. */
+export interface CheckOptions {
+    /**
+     * An empty directory the plugin was started in (its `workspaceRoot`). When
+     * set, a plugin that generates projects is asked to generate an app, a lib
+     * and a package there, which a language plugin must then discover as
+     * generated. Generation may install dependencies, so it is opt-in.
+     */
+    workspace?: string;
+}
+/**
+ * Runs the checks of `smith plugin check` against a connected plugin: it names
+ * itself, has a known kind and known roles, its roles match what it
+ * implements, it names the slots it fills, its references and stacks are
+ * well-formed, every advertised method answers a request with nothing in it,
+ * and, with `workspace`, the projects it generates are found again by its own
+ * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
+ * under the same names. (`smith plugin check` adds one more, "shuts down when
+ * asked", after closing the plugin: call {@link PluginClient.close} and add it
+ * to the report if you want it.)
+ */
+export declare function checkPlugin(client: PluginClient, options?: CheckOptions): Promise<ConformanceReport>;

package/conformance/check-plugin.use-case.js

@@ -0,0 +1,78 @@
+import { describeRef, isEmptyRef } from '../plugin-refs/index.js';
+import { ROLES, effectiveRoles, isKnownRole } from '../plugin-roles/index.js';
+import { checkGeneration } from './check-generation.use-case.js';
+import { ConformanceReport } from './conformance-report.model.js';
+import { goList, goQuote } from './go-list.mapper.js';
+const CALL_TIMEOUT_MS = 20 * 60 * 1000;
+/**
+ * Runs the checks of `smith plugin check` against a connected plugin: it names
+ * itself, has a known kind and known roles, its roles match what it
+ * implements, it names the slots it fills, its references and stacks are
+ * well-formed, every advertised method answers a request with nothing in it,
+ * and, with `workspace`, the projects it generates are found again by its own
+ * `discover`. A port of the Go SDK's `conformance.Check`, with the same checks
+ * under the same names. (`smith plugin check` adds one more, "shuts down when
+ * asked", after closing the plugin: call {@link PluginClient.close} and add it
+ * to the report if you want it.)
+ */
+export async function checkPlugin(client, options = {}) {
+    const info = client.info;
+    const report = new ConformanceReport(info.plugin);
+    report.add('names itself', info.plugin.name !== '' && info.plugin.version !== '', `initialize returned name ${goQuote(info.plugin.name)}, version ${goQuote(info.plugin.version)}; both are required`);
+    report.add('has a known kind', info.kind === 'language' || info.kind === 'convention', `kind ${goQuote(info.kind)} is neither language nor convention`);
+    const roles = effectiveRoles(info);
+    for (const role of roles)
+        report.add(`plays a known role: ${role}`, isKnownRole(role), `roles are ${goList(ROLES)}`);
+    const caps = info.capabilities;
+    if (roles.includes('language')) {
+        report.add('a language plugin discovers projects', caps.discover === true && (info.manifests ?? []).length > 0, 'it must implement discover and name its manifest files');
+    }
+    if (roles.includes('scaffold'))
+        report.add('a scaffold generates projects', caps.generate === true, 'it must implement generate');
+    for (const role of ['toolchain', 'structure', 'deploy']) {
+        if (roles.includes(role) && !roles.includes('language')) {
+            report.add(`a ${role} plugin does something`, caps.contribute === true || caps.generate === true || caps.ci === true || caps.doctor === true, 'it implements none of contribute, generate, ci and doctor');
+        }
+    }
+    const provides = info.provides ?? [];
+    if (provides.length > 0)
+        report.add('only a toolchain provides tasks', roles.includes('toolchain'), `it provides ${goList(provides)} without the toolchain role`);
+    if (info.kind === 'convention' && roles.includes('toolchain'))
+        report.add('a toolchain names the slots it fills', provides.length > 0, 'a toolchain plugin must list the tasks it provides');
+    const requires = info.requires ?? [];
+    const conflicts = info.conflicts ?? [];
+    const stacks = info.stacks ?? [];
+    for (const ref of requires)
+        report.add(`requires ${describeRef(ref)}: a known reference`, isValidRef(ref), 'a reference sets a known level, a name or a slot');
+    for (const ref of conflicts) {
+        report.add(`conflicts with ${describeRef(ref)}: a known reference`, isValidRef(ref) && ref.name !== info.plugin.name, 'a reference sets a known level, a name or a slot, and is not the plugin itself');
+    }
+    const names = new Set();
+    for (const stack of stacks) {
+        report.add(`stack ${stack.name} is complete`, stack.name !== '' && stack.language !== '' && !names.has(stack.name), 'a stack needs a unique name and a language plugin');
+        names.add(stack.name);
+    }
+    const answers = async (check, method, params) => {
+        if (!client.supports(method))
+            return;
+        try {
+            await client.call(method, params, { timeoutMs: CALL_TIMEOUT_MS });
+            report.add(check, true, '');
+        }
+        catch (error) {
+            report.add(check, false, error instanceof Error ? error.message : String(error));
+        }
+    };
+    await answers('discover answers with no manifests', 'discover', { manifests: [] });
+    await answers('contribute answers with no projects', 'contribute', { projects: [] });
+    await answers('ci answers with no projects', 'ci', { projects: [] });
+    await answers('doctor answers with no projects', 'doctor', { projects: [] });
+    if (options.workspace !== undefined && caps.generate === true)
+        await checkGeneration(client, options.workspace, report);
+    return report;
+}
+/** Whether a reference names something: a known level, a name or a slot. */
+function isValidRef(ref) {
+    const level = ref.level ?? '';
+    return !isEmptyRef(ref) && (level === '' || isKnownRole(level));
+}

package/conformance/conformance-report.model.d.ts

@@ -0,0 +1,22 @@
+import type { Peer } from '../protocol/index.ts';
+/** One check: its name, whether it held, and, when it did not, what is wrong. */
+export interface CheckResult {
+    check: string;
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * Every check run against one plugin. `JSON.stringify(report)` gives the shape
+ * `smith plugin check --json` prints: `{ plugin, results }`.
+ */
+export declare class ConformanceReport {
+    readonly plugin: Peer;
+    readonly results: CheckResult[];
+    constructor(plugin: Peer);
+    /** Whether every check passed. */
+    get ok(): boolean;
+    /** The failed checks, one per line: `check: detail`. */
+    failures(): string;
+    /** Records a check. The detail is kept only for a check that failed. */
+    add(check: string, ok: boolean, detail: string): void;
+}

package/conformance/conformance-report.model.js

@@ -0,0 +1,23 @@
+/**
+ * Every check run against one plugin. `JSON.stringify(report)` gives the shape
+ * `smith plugin check --json` prints: `{ plugin, results }`.
+ */
+export class ConformanceReport {
+    plugin;
+    results = [];
+    constructor(plugin) {
+        this.plugin = plugin;
+    }
+    /** Whether every check passed. */
+    get ok() {
+        return this.results.every(result => result.ok);
+    }
+    /** The failed checks, one per line: `check: detail`. */
+    failures() {
+        return this.results.filter(result => !result.ok).map(result => `${result.check}: ${result.detail ?? ''}`).join('\n');
+    }
+    /** Records a check. The detail is kept only for a check that failed. */
+    add(check, ok, detail) {
+        this.results.push(ok ? { check, ok } : { check, ok, detail });
+    }
+}

package/conformance/find-manifests.algorithm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The manifests of a plugin below a workspace, workspace-relative with forward
+ * slashes: files named like `names` (see isManifest), skipping dot-folders and
+ * dependency folders, and files at the root itself, as the Go conformance
+ * suite does.
+ */
+export declare function findManifests(workspace: string, names: readonly string[]): string[];

package/conformance/find-manifests.algorithm.js

@@ -0,0 +1,34 @@
+import { readdirSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { isManifest } from '../projects/index.js';
+const SKIPPED_FOLDERS = new Set(['node_modules', '__pycache__']);
+/**
+ * The manifests of a plugin below a workspace, workspace-relative with forward
+ * slashes: files named like `names` (see isManifest), skipping dot-folders and
+ * dependency folders, and files at the root itself, as the Go conformance
+ * suite does.
+ */
+export function findManifests(workspace, names) {
+    const found = [];
+    const walk = (relative) => {
+        const folder = join(workspace, ...relative.split('/').filter(part => part !== ''));
+        const entries = readdirSync(folder, { withFileTypes: true });
+        for (const entry of entries) {
+            const path = relative === '' ? entry.name : `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (!entry.name.startsWith('.') && !SKIPPED_FOLDERS.has(entry.name))
+                    walk(path);
+            }
+            else if (isManifest(names, entry.name) && posix.dirname(path) !== '.') {
+                found.push(path);
+            }
+        }
+    };
+    try {
+        walk('');
+    }
+    catch {
+        // An unreadable folder ends the walk; what was found stays.
+    }
+    return found;
+}

package/conformance/go-list.mapper.d.ts

@@ -0,0 +1,4 @@
+/** A list as Go's `%v` writes it, `[a b]`, which the details of the Go checks use; the TypeScript checks keep their text the same. */
+export declare function goList(items: readonly unknown[]): string;
+/** A string as Go's `%q` writes it. */
+export declare function goQuote(text: string): string;

package/conformance/go-list.mapper.js

@@ -0,0 +1,8 @@
+/** A list as Go's `%v` writes it, `[a b]`, which the details of the Go checks use; the TypeScript checks keep their text the same. */
+export function goList(items) {
+    return `[${items.map(String).join(' ')}]`;
+}
+/** A string as Go's `%q` writes it. */
+export function goQuote(text) {
+    return JSON.stringify(text);
+}

package/conformance/index.d.ts

@@ -0,0 +1,5 @@
+export { checkPlugin } from './check-plugin.use-case.ts';
+export type { CheckOptions } from './check-plugin.use-case.ts';
+export { CONFORMANCE_STACK } from './check-generation.use-case.ts';
+export { ConformanceReport } from './conformance-report.model.ts';
+export type { CheckResult } from './conformance-report.model.ts';

package/conformance/index.js

@@ -0,0 +1,3 @@
+export { checkPlugin } from './check-plugin.use-case.js';
+export { CONFORMANCE_STACK } from './check-generation.use-case.js';
+export { ConformanceReport } from './conformance-report.model.js';

package/framing/frame-message.algorithm.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One message as the protocol frames it: `Content-Length: <bytes>`, a blank
+ * line (CRLF CRLF), then the body. The length counts bytes of UTF-8, not characters.
+ */
+export declare function frameMessage(body: string): Buffer;

package/framing/frame-message.algorithm.js

@@ -0,0 +1,8 @@
+/**
+ * One message as the protocol frames it: `Content-Length: <bytes>`, a blank
+ * line (CRLF CRLF), then the body. The length counts bytes of UTF-8, not characters.
+ */
+export function frameMessage(body) {
+    const bytes = Buffer.from(body, 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${bytes.length}\r\n\r\n`, 'ascii'), bytes]);
+}

package/framing/frame-reader.store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cuts a byte stream into the bodies of its frames. Bytes arrive in chunks of
+ * any size; {@link FrameReader.push} returns every body a chunk completed.
+ * Headers end at a blank line (CRLF or LF alone, as the Go SDK reads them),
+ * `Content-Length` is matched without regard to case, and a header that is not
+ * `Name: value`, a length that is not a number from 0 to 64 MiB, or a header
+ * block without a length is a {@link FramingError}.
+ */
+export declare class FrameReader {
+    #private;
+    /** Bytes received that are not part of a complete frame yet. */
+    get pending(): number;
+    /** Adds the bytes that arrived and returns the body of every frame they completed, in order. */
+    push(chunk: Uint8Array): string[];
+}

package/framing/frame-reader.store.js

@@ -0,0 +1,59 @@
+import { MAX_MESSAGE_BYTES } from '../protocol/index.js';
+import { FramingError } from './framing.error.js';
+/**
+ * Cuts a byte stream into the bodies of its frames. Bytes arrive in chunks of
+ * any size; {@link FrameReader.push} returns every body a chunk completed.
+ * Headers end at a blank line (CRLF or LF alone, as the Go SDK reads them),
+ * `Content-Length` is matched without regard to case, and a header that is not
+ * `Name: value`, a length that is not a number from 0 to 64 MiB, or a header
+ * block without a length is a {@link FramingError}.
+ */
+export class FrameReader {
+    #buffer = Buffer.alloc(0);
+    /** The length and where the body starts, or null while the header is incomplete. */
+    #readHeader() {
+        let length = -1;
+        let position = 0;
+        for (;;) {
+            const newline = this.#buffer.indexOf(0x0A, position);
+            if (newline === -1)
+                return null;
+            const line = this.#buffer.subarray(position, newline).toString('ascii').replace(/[\r\n]+$/, '');
+            position = newline + 1;
+            if (line === '')
+                break;
+            const colon = line.indexOf(':');
+            if (colon === -1)
+                throw new FramingError(`malformed header "${line}"`);
+            if (line.slice(0, colon).trim().toLowerCase() !== 'content-length')
+                continue;
+            const text = line.slice(colon + 1).trim();
+            const parsed = /^\d+$/.test(text) ? Number(text) : NaN;
+            if (!Number.isSafeInteger(parsed) || parsed > MAX_MESSAGE_BYTES)
+                throw new FramingError(`invalid Content-Length "${line.slice(colon + 1)}"`);
+            length = parsed;
+        }
+        if (length < 0)
+            throw new FramingError('message without Content-Length');
+        return { length, bodyStart: position };
+    }
+    /** Bytes received that are not part of a complete frame yet. */
+    get pending() {
+        return this.#buffer.length;
+    }
+    /** Adds the bytes that arrived and returns the body of every frame they completed, in order. */
+    push(chunk) {
+        this.#buffer = this.#buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.#buffer, chunk]);
+        const bodies = [];
+        for (;;) {
+            const header = this.#readHeader();
+            if (header === null)
+                return bodies;
+            const end = header.bodyStart + header.length;
+            if (this.#buffer.length < end)
+                return bodies;
+            bodies.push(this.#buffer.subarray(header.bodyStart, end).toString('utf8'));
+            this.#buffer = this.#buffer.subarray(end);
+        }
+    }
+}

package/framing/framing.error.d.ts

@@ -0,0 +1,4 @@
+/** The bytes on the stream are not a sequence of frames: a malformed header, a missing or invalid Content-Length. The stream cannot be trusted after it. */
+export declare class FramingError extends Error {
+    constructor(message: string);
+}

package/framing/framing.error.js

@@ -0,0 +1,7 @@
+/** The bytes on the stream are not a sequence of frames: a malformed header, a missing or invalid Content-Length. The stream cannot be trusted after it. */
+export class FramingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FramingError';
+    }
+}

package/framing/index.d.ts

@@ -0,0 +1,3 @@
+export { frameMessage } from './frame-message.algorithm.ts';
+export { FrameReader } from './frame-reader.store.ts';
+export { FramingError } from './framing.error.ts';

package/framing/index.js

@@ -0,0 +1,3 @@
+export { frameMessage } from './frame-message.algorithm.js';
+export { FrameReader } from './frame-reader.store.js';
+export { FramingError } from './framing.error.js';

package/host/connect-plugin.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { SmithPlugin } from '../serve/index.ts';
+import type { HostOptions } from './host-options.contract.ts';
+import { PluginClient } from './plugin-client.client.ts';
+/** The streams of a plugin that is somewhere else: its responses to read, its requests to write. */
+export interface PluginStreams {
+    /** What the plugin writes (its standard output). */
+    input: AsyncIterable<Uint8Array>;
+    /** What the plugin reads (its standard input). */
+    output: {
+        write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
+        end: () => unknown;
+    };
+}
+/**
+ * Performs the handshake with a plugin reachable through a pair of streams.
+ * Closing the client shuts the plugin down and ends the streams; there is no
+ * process to kill.
+ */
+export declare function connectPlugin(streams: PluginStreams, options: HostOptions): Promise<PluginClient>;
+/**
+ * Serves a plugin object in this process over pipes and connects to it, the way
+ * the Go SDK's tests serve a plugin with `serve.Serve` over `io.Pipe`: the
+ * real framing, handshake and dispatch, no process. Closing the client waits
+ * for the serve loop to end.
+ */
+export declare function connectInProcess(plugin: SmithPlugin, options: HostOptions): Promise<PluginClient>;