@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/protocol/protocol-types.contract.js

@@ -0,0 +1,36 @@
+/* eslint-disable */
+// GENERATED by tools/generate-protocol from packages/plugin-sdk/schema/protocol.schema.json.
+// Do not edit it: change the Go types in packages/plugin-sdk/protocol, regenerate the schema
+// (`smith run schema -p plugin-sdk`), then run `smith run generate -p plugin-sdk-ts`.
+/** The protocol major version this SDK speaks. A breaking change to the protocol raises it. */
+export const PROTOCOL_VERSION = 1;
+/** The largest message the framing accepts, in bytes. */
+export const MAX_MESSAGE_BYTES = 67108864;
+/** The error codes of the protocol: the JSON-RPC 2.0 ones, and `PluginFailure` for a failure the user must act on. */
+export const ERROR_CODES = {
+    /** The message was not valid JSON. The response has a null id. */
+    ParseError: -32700,
+    /**
+     * The request is not valid, or arrived out of order: every request before initialize is refused
+     * with this code.
+     */
+    InvalidRequest: -32600,
+    /**
+     * The plugin does not implement the method, or did not advertise the capability. The message is
+     * "method not supported: <method>".
+     */
+    MethodNotFound: -32601,
+    /** The params do not have the shape the method expects. */
+    InvalidParams: -32602,
+    /**
+     * The plugin failed in a way that is not the user's to act on, for example a result that could
+     * not be encoded.
+     */
+    InternalError: -32603,
+    /**
+     * The method ran and failed for a reason the user must act on (a missing toolchain, a bad
+     * manifest). The message is shown to the user as it is, so it should say what to do. An error a
+     * method of the Go SDK returns becomes this code.
+     */
+    PluginFailure: -32000,
+};

package/protocol/rpc-error.error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A JSON-RPC 2.0 error object as an exception: what a host's call rejects
+ * with when the plugin answers an error, and what the serve loop turns an
+ * exception back into. `code` is one of {@link ERROR_CODES}.
+ */
+export declare class RpcError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}

package/protocol/rpc-error.error.js

@@ -0,0 +1,13 @@
+/**
+ * A JSON-RPC 2.0 error object as an exception: what a host's call rejects
+ * with when the plugin answers an error, and what the serve loop turns an
+ * exception back into. `code` is one of {@link ERROR_CODES}.
+ */
+export class RpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'RpcError';
+        this.code = code;
+    }
+}

package/protocol/schema-document.contract.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The shape of `packages/plugin-sdk/schema/protocol.schema.json`, the JSON
+ * Schema (draft 2020-12) of the plugin protocol, as far as the SDK reads it:
+ * the types, the wire codec and the host's capability check all follow it.
+ */
+export interface SchemaNode {
+    '$ref'?: string;
+    'type'?: string | string[];
+    'properties'?: Record<string, SchemaNode>;
+    'required'?: string[];
+    'items'?: SchemaNode;
+    'additionalProperties'?: SchemaNode | boolean;
+    'enum'?: string[];
+    'anyOf'?: SchemaNode[];
+    'description'?: string;
+    'x-enumDescriptions'?: Record<string, string>;
+}
+/** One row of the methods table: what a method takes, gives and needs. */
+export interface MethodRow {
+    description: string;
+    params: SchemaNode;
+    result: SchemaNode;
+    /** The capability a plugin advertises to be asked the method; `null` when it is always available. */
+    capability: string | null;
+}
+export interface ErrorCodeRow {
+    name: string;
+    code: number;
+    description: string;
+}
+export interface RoleRow {
+    name: string;
+    description?: string;
+    /** `exclusive` (one per project), `additive` (any number) or `perSlot` (one per task name provided). */
+    cardinality: 'exclusive' | 'additive' | 'perSlot';
+    /** The kinds of plugin that play the role when the plugin names none. */
+    defaultFor: string[];
+}
+export interface SchemaDocument {
+    '$schema': string;
+    '$id': string;
+    'title': string;
+    'description': string;
+    'x-protocolVersion': number;
+    'x-transport': {
+        framing: string;
+        encoding: string;
+        jsonrpc: string;
+        maxMessageBytes: number;
+    };
+    'x-methods': Record<string, MethodRow>;
+    'x-errorCodes': ErrorCodeRow[];
+    'x-roles': RoleRow[];
+    '$defs': Record<string, SchemaNode>;
+}

package/protocol/schema-document.contract.js

@@ -0,0 +1 @@
+export {};

package/scaffold/index.d.ts

@@ -0,0 +1,3 @@
+export { scaffoldProject } from './scaffold-project.use-case.ts';
+export type { ScaffoldOptions } from './scaffold-project.use-case.ts';
+export { scaffoldData } from './scaffold-data.mapper.ts';

package/scaffold/index.js

@@ -0,0 +1,2 @@
+export { scaffoldProject } from './scaffold-project.use-case.js';
+export { scaffoldData } from './scaffold-data.mapper.js';

package/scaffold/scaffold-data.mapper.d.ts

@@ -0,0 +1,15 @@
+import type { GenerateParams } from '../protocol/index.ts';
+/**
+ * What a project template can say, from the `generate` params:
+ *
+ * | Field | Value |
+ * |---|---|
+ * | `Dir` | the project's directory, workspace-relative |
+ * | `Name` | the project's name |
+ * | `Kind` | `app`, `lib` or `package` |
+ * | `Stack` | the stack to record in the manifest (may be empty) |
+ * | `Workspace` | the workspace's name |
+ * | `Scope` | the npm scope, with its `@` (may be empty) |
+ * | `ModulePrefix` | the Go module path prefix (may be empty) |
+ */
+export declare function scaffoldData(params: GenerateParams): Record<string, string>;

package/scaffold/scaffold-data.mapper.js

@@ -0,0 +1,24 @@
+/**
+ * What a project template can say, from the `generate` params:
+ *
+ * | Field | Value |
+ * |---|---|
+ * | `Dir` | the project's directory, workspace-relative |
+ * | `Name` | the project's name |
+ * | `Kind` | `app`, `lib` or `package` |
+ * | `Stack` | the stack to record in the manifest (may be empty) |
+ * | `Workspace` | the workspace's name |
+ * | `Scope` | the npm scope, with its `@` (may be empty) |
+ * | `ModulePrefix` | the Go module path prefix (may be empty) |
+ */
+export function scaffoldData(params) {
+    return {
+        Dir: params.directory,
+        Name: params.name,
+        Kind: params.kind,
+        Stack: params.stack ?? '',
+        Workspace: params.workspace.name,
+        Scope: params.workspace.scope ?? '',
+        ModulePrefix: params.workspace.modulePrefix ?? '',
+    };
+}

package/scaffold/scaffold-project.use-case.d.ts

@@ -0,0 +1,20 @@
+import type { GenerateParams, GenerateResult } from '../protocol/index.ts';
+export interface ScaffoldOptions {
+    /** The workspace root from `initialize`: the project's directory is relative to it. */
+    workspaceRoot: string;
+    /** The `generate` params. */
+    params: GenerateParams;
+    /** Target path to template text, with `[[ ]]` actions in both (`'[[.Dir]]/widget.json'`). */
+    files: Record<string, string>;
+    /** More fields for the templates, next to the ones {@link scaffoldData} lists. They win over them. */
+    data?: Record<string, unknown>;
+    /** Notes printed to the user after generation. */
+    notes?: string[];
+}
+/**
+ * The answer to `generate` for a scaffold: renders the templates into the new
+ * project, never overwriting a file, and reports what it wrote. A language
+ * plugin that scaffolds must record `params.stack` in the manifest it writes
+ * (`[[if .Stack]]` in a template), so discovery reports it back.
+ */
+export declare function scaffoldProject(options: ScaffoldOptions): Promise<GenerateResult>;

package/scaffold/scaffold-project.use-case.js

@@ -0,0 +1,13 @@
+import { writeTemplates } from '../templating/index.js';
+import { scaffoldData } from './scaffold-data.mapper.js';
+/**
+ * The answer to `generate` for a scaffold: renders the templates into the new
+ * project, never overwriting a file, and reports what it wrote. A language
+ * plugin that scaffolds must record `params.stack` in the manifest it writes
+ * (`[[if .Stack]]` in a template), so discovery reports it back.
+ */
+export async function scaffoldProject(options) {
+    const data = { ...scaffoldData(options.params), ...options.data };
+    const files = await writeTemplates(options.workspaceRoot, options.files, data);
+    return options.notes === undefined ? { files } : { files, notes: options.notes };
+}

package/serve/capabilities-of.algorithm.d.ts

@@ -0,0 +1,13 @@
+import type { Capabilities } from '../protocol/index.ts';
+import type { SmithPlugin } from './plugin.contract.ts';
+/** Whether the plugin implements a method of the protocol: it has every member the method needs, as functions. */
+export declare function implementsMethod(plugin: SmithPlugin, method: string): boolean;
+/**
+ * The capabilities a plugin advertises, derived from the methods it
+ * implements: a plugin cannot advertise a method it lacks, or implement one
+ * it does not advertise. The capability of each method is read from the
+ * schema's methods table.
+ */
+export declare function capabilitiesOf(plugin: SmithPlugin): Capabilities;
+/** Methods a plugin half-implements: a member of a pair (`install` without `uninstall`) that is not advertised for lack of the other. */
+export declare function halfImplemented(plugin: SmithPlugin): string[];

package/serve/capabilities-of.algorithm.js

@@ -0,0 +1,28 @@
+import { protocolSchema } from '../protocol/index.js';
+import { PLUGIN_MEMBERS } from './plugin-members.config.js';
+/** Whether the plugin implements a method of the protocol: it has every member the method needs, as functions. */
+export function implementsMethod(plugin, method) {
+    const entry = Object.hasOwn(PLUGIN_MEMBERS, method) ? PLUGIN_MEMBERS[method] : undefined;
+    return entry !== undefined && entry.requires.every(member => typeof plugin[member] === 'function');
+}
+/**
+ * The capabilities a plugin advertises, derived from the methods it
+ * implements: a plugin cannot advertise a method it lacks, or implement one
+ * it does not advertise. The capability of each method is read from the
+ * schema's methods table.
+ */
+export function capabilitiesOf(plugin) {
+    const capabilities = {};
+    const methods = Object.entries(protocolSchema['x-methods']);
+    for (const [method, row] of methods) {
+        if (row.capability !== null && implementsMethod(plugin, method))
+            capabilities[row.capability] = true;
+    }
+    return capabilities;
+}
+/** Methods a plugin half-implements: a member of a pair (`install` without `uninstall`) that is not advertised for lack of the other. */
+export function halfImplemented(plugin) {
+    return Object.entries(PLUGIN_MEMBERS)
+        .filter(([method, entry]) => typeof plugin[entry.member] === 'function' && !implementsMethod(plugin, method))
+        .map(([, entry]) => entry.member);
+}

package/serve/claim-stdout.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { FrameSink } from './protocol-streams.contract.ts';
+/**
+ * Takes the process's standard output for the protocol and nothing else. A
+ * `console.log`, a library's `process.stdout.write` or a child process's
+ * inherited output would corrupt the stream the host reads, so from here on
+ * everything written to `process.stdout` goes to standard error, where the
+ * host shows it to the user. The returned sink is the only way to the real
+ * standard output.
+ */
+export declare function claimStdout(): FrameSink;

package/serve/claim-stdout.use-case.js

@@ -0,0 +1,14 @@
+/**
+ * Takes the process's standard output for the protocol and nothing else. A
+ * `console.log`, a library's `process.stdout.write` or a child process's
+ * inherited output would corrupt the stream the host reads, so from here on
+ * everything written to `process.stdout` goes to standard error, where the
+ * host shows it to the user. The returned sink is the only way to the real
+ * standard output.
+ */
+export function claimStdout() {
+    const stdout = process.stdout;
+    const write = stdout.write.bind(stdout);
+    stdout.write = ((...args) => process.stderr.write(...args));
+    return { write };
+}

package/serve/dispatch-request.use-case.d.ts

@@ -0,0 +1,14 @@
+import type { ReceivedRequest } from '../codec/index.ts';
+import type { SmithPlugin } from './plugin.contract.ts';
+import type { RequestOutcome } from './request-outcome.contract.ts';
+/** The text of an exception: its message, or what was thrown. */
+export declare function messageOf(thrown: unknown): string;
+/**
+ * Answers one request: `initialize` and `shutdown` here, every other method
+ * by the member of the plugin that implements it. The codes are the Go SDK's:
+ * MethodNotFound for a method the plugin does not implement, InvalidParams
+ * for params of the wrong shape, PluginFailure for an exception the method
+ * threw (its message is shown to the user), InternalError for a result that
+ * cannot be written as the schema describes.
+ */
+export declare function dispatchRequest(plugin: SmithPlugin, request: ReceivedRequest): Promise<RequestOutcome>;

package/serve/dispatch-request.use-case.js

@@ -0,0 +1,56 @@
+import { EncodeError, ParamsError, decodeParams, encodeResult } from '../codec/index.js';
+import { ERROR_CODES } from '../protocol/index.js';
+import { implementsMethod } from './capabilities-of.algorithm.js';
+import { initializePlugin } from './initialize-plugin.use-case.js';
+import { PLUGIN_MEMBERS } from './plugin-members.config.js';
+/** The text of an exception: its message, or what was thrown. */
+export function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+ * Answers one request: `initialize` and `shutdown` here, every other method
+ * by the member of the plugin that implements it. The codes are the Go SDK's:
+ * MethodNotFound for a method the plugin does not implement, InvalidParams
+ * for params of the wrong shape, PluginFailure for an exception the method
+ * threw (its message is shown to the user), InternalError for a result that
+ * cannot be written as the schema describes.
+ */
+export async function dispatchRequest(plugin, request) {
+    if (request.method === 'shutdown')
+        return { ok: true, resultJson: '{}' };
+    let params;
+    if (request.method === 'initialize' || implementsMethod(plugin, request.method)) {
+        try {
+            params = decodeParams(request.method, request.params);
+        }
+        catch (error) {
+            if (error instanceof ParamsError)
+                return { ok: false, code: ERROR_CODES.InvalidParams, message: error.message };
+            throw error;
+        }
+    }
+    let result;
+    try {
+        if (request.method === 'initialize') {
+            result = await initializePlugin(plugin, params);
+        }
+        else if (implementsMethod(plugin, request.method)) {
+            const member = PLUGIN_MEMBERS[request.method].member;
+            result = await plugin[member].call(plugin, params);
+        }
+        else {
+            return { ok: false, code: ERROR_CODES.MethodNotFound, message: `method not supported: ${request.method}` };
+        }
+    }
+    catch (error) {
+        return { ok: false, code: ERROR_CODES.PluginFailure, message: messageOf(error) };
+    }
+    try {
+        return { ok: true, resultJson: encodeResult(request.method, result) };
+    }
+    catch (error) {
+        if (error instanceof EncodeError)
+            return { ok: false, code: ERROR_CODES.InternalError, message: `${request.method}: ${error.message}` };
+        throw error;
+    }
+}

package/serve/index.d.ts

@@ -0,0 +1,4 @@
+export { serve, serveStreams } from './serve.use-case.ts';
+export { capabilitiesOf, implementsMethod } from './capabilities-of.algorithm.ts';
+export type { Awaitable, CIContributor, Contributor, DeclarationEditor, DependencyManager, Discoverer, DoctorContributor, Generator, LatestReader, Plugin, PluginDescription, Publisher, RegistryReader, Remover, SmithPlugin, Versioner, } from './plugin.contract.ts';
+export type { FrameSink, ServeStreams } from './protocol-streams.contract.ts';

package/serve/index.js

@@ -0,0 +1,2 @@
+export { serve, serveStreams } from './serve.use-case.js';
+export { capabilitiesOf, implementsMethod } from './capabilities-of.algorithm.js';

package/serve/initialize-plugin.use-case.d.ts

@@ -0,0 +1,9 @@
+import type { InitializeParams, InitializeResult } from '../protocol/index.ts';
+import type { SmithPlugin } from './plugin.contract.ts';
+/**
+ * The handshake. It refuses a host that does not speak this SDK's protocol
+ * version (the message is the Go SDK's), asks the plugin to describe itself,
+ * and fills in the version it chose and the capabilities derived from the
+ * methods the plugin has, whatever `describe` returned for them.
+ */
+export declare function initializePlugin(plugin: SmithPlugin, params: InitializeParams): Promise<InitializeResult>;

package/serve/initialize-plugin.use-case.js

@@ -0,0 +1,16 @@
+import { PROTOCOL_VERSION } from '../protocol/index.js';
+import { capabilitiesOf } from './capabilities-of.algorithm.js';
+/**
+ * The handshake. It refuses a host that does not speak this SDK's protocol
+ * version (the message is the Go SDK's), asks the plugin to describe itself,
+ * and fills in the version it chose and the capabilities derived from the
+ * methods the plugin has, whatever `describe` returned for them.
+ */
+export async function initializePlugin(plugin, params) {
+    if (!params.protocolVersions.includes(PROTOCOL_VERSION)) {
+        // The Go SDK formats the host's list with %v: [1 2].
+        throw new Error(`no common protocol version: host speaks [${params.protocolVersions.join(' ')}], plugin speaks ${PROTOCOL_VERSION}`);
+    }
+    const description = await plugin.describe(params);
+    return { ...description, protocolVersion: PROTOCOL_VERSION, capabilities: capabilitiesOf(plugin) };
+}

package/serve/plugin-members.config.d.ts

@@ -0,0 +1,16 @@
+import type { SmithPlugin } from './plugin.contract.ts';
+type Member = Exclude<keyof SmithPlugin, 'describe'>;
+/**
+ * Which member of a plugin answers each method of the protocol (other than
+ * `initialize` and `shutdown`, which the serve loop answers), and which members
+ * the plugin must have for the method to count as implemented. A plugin with
+ * `install` and no `uninstall` does not implement the `dependencies`
+ * capability, as in the Go SDK, where the interface needs both methods. A spec
+ * checks the table against the methods of the schema, so a method added to the
+ * protocol cannot be left out.
+ */
+export declare const PLUGIN_MEMBERS: Readonly<Record<string, {
+    member: Member;
+    requires: readonly Member[];
+}>>;
+export {};

package/serve/plugin-members.config.js

@@ -0,0 +1,25 @@
+/**
+ * Which member of a plugin answers each method of the protocol (other than
+ * `initialize` and `shutdown`, which the serve loop answers), and which members
+ * the plugin must have for the method to count as implemented. A plugin with
+ * `install` and no `uninstall` does not implement the `dependencies`
+ * capability, as in the Go SDK, where the interface needs both methods. A spec
+ * checks the table against the methods of the schema, so a method added to the
+ * protocol cannot be left out.
+ */
+export const PLUGIN_MEMBERS = {
+    'discover': { member: 'discover', requires: ['discover'] },
+    'generate': { member: 'generate', requires: ['generate'] },
+    'version/write': { member: 'writeVersion', requires: ['writeVersion'] },
+    'publish': { member: 'publish', requires: ['publish'] },
+    'ci': { member: 'ci', requires: ['ci'] },
+    'doctor': { member: 'doctor', requires: ['doctor'] },
+    'contribute': { member: 'contribute', requires: ['contribute'] },
+    'remove': { member: 'remove', requires: ['remove'] },
+    'published': { member: 'published', requires: ['published'] },
+    'dependencies/install': { member: 'install', requires: ['install', 'uninstall'] },
+    'dependencies/uninstall': { member: 'uninstall', requires: ['install', 'uninstall'] },
+    'dependencies/declared': { member: 'declared', requires: ['declared', 'rewrite'] },
+    'dependencies/rewrite': { member: 'rewrite', requires: ['declared', 'rewrite'] },
+    'dependencies/latest': { member: 'latest', requires: ['latest'] },
+};

package/serve/plugin.contract.d.ts

@@ -0,0 +1,65 @@
+import type { CIParams, CIResult, ContributeParams, ContributeResult, DeclaredParams, DeclaredResult, DependencyResult, DiscoverParams, DiscoverResult, DoctorParams, DoctorResult, GenerateParams, GenerateResult, InitializeParams, InitializeResult, InstallParams, LatestParams, LatestResult, PublishedParams, PublishedResult, PublishParams, PublishResult, RemoveParams, RemoveResult, RewriteParams, UninstallParams, VersionParams, VersionResult } from '../protocol/index.ts';
+/** A result now or later: every method of a plugin may be `async`. */
+export type Awaitable<T> = T | Promise<T>;
+/** What a plugin says about itself. The serve loop fills in `protocolVersion` and `capabilities`. */
+export type PluginDescription = Omit<InitializeResult, 'protocolVersion' | 'capabilities'>;
+/** The one method every plugin has. */
+export interface Plugin {
+    /** Answers `initialize`: the plugin's identity, kind, languages, manifests and roles. */
+    describe: (params: InitializeParams) => Awaitable<PluginDescription>;
+}
+/** `discover`: describes the projects behind manifests. */
+export interface Discoverer {
+    discover: (params: DiscoverParams) => Awaitable<DiscoverResult>;
+}
+/** `generate`: scaffolds a project. */
+export interface Generator {
+    generate: (params: GenerateParams) => Awaitable<GenerateResult>;
+}
+/** `version/write`: records a release version in a manifest. */
+export interface Versioner {
+    writeVersion: (params: VersionParams) => Awaitable<VersionResult>;
+}
+/** `publish`: publishes a released project. */
+export interface Publisher {
+    publish: (params: PublishParams) => Awaitable<PublishResult>;
+}
+/** `published`: the newest version a registry has of a project. */
+export interface RegistryReader {
+    published: (params: PublishedParams) => Awaitable<PublishedResult>;
+}
+/** `ci`: what a pipeline needs for the plugin's projects. */
+export interface CIContributor {
+    ci: (params: CIParams) => Awaitable<CIResult>;
+}
+/** `doctor`: checks the plugin's projects. */
+export interface DoctorContributor {
+    doctor: (params: DoctorParams) => Awaitable<DoctorResult>;
+}
+/** `remove`: cleans up after a project is removed. */
+export interface Remover {
+    remove: (params: RemoveParams) => Awaitable<RemoveResult>;
+}
+/** `dependencies/install` and `dependencies/uninstall`: both, or the capability is not advertised. */
+export interface DependencyManager {
+    install: (params: InstallParams) => Awaitable<DependencyResult>;
+    uninstall: (params: UninstallParams) => Awaitable<DependencyResult>;
+}
+/** `dependencies/declared` and `dependencies/rewrite`: both, or the capability is not advertised. */
+export interface DeclarationEditor {
+    declared: (params: DeclaredParams) => Awaitable<DeclaredResult>;
+    rewrite: (params: RewriteParams) => Awaitable<DependencyResult>;
+}
+/** `dependencies/latest`: the newest releases of dependencies and pinned tools. */
+export interface LatestReader {
+    latest: (params: LatestParams) => Awaitable<LatestResult>;
+}
+/** `contribute`: a convention adds tasks to the projects it applies to. */
+export interface Contributor {
+    contribute: (params: ContributeParams) => Awaitable<ContributeResult>;
+}
+/**
+ * A plugin as {@link serve} takes it: `describe`, and the methods it implements.
+ * The capabilities it advertises are derived from which methods it has.
+ */
+export type SmithPlugin = Plugin & Partial<Discoverer & Generator & Versioner & Publisher & RegistryReader & CIContributor & DoctorContributor & Remover & DependencyManager & DeclarationEditor & LatestReader & Contributor>;

package/serve/plugin.contract.js

@@ -0,0 +1 @@
+export {};

package/serve/protocol-streams.contract.d.ts

@@ -0,0 +1,13 @@
+/** Where the serve loop writes its frames: a Node `Writable` fits. */
+export interface FrameSink {
+    write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
+}
+/** The streams {@link serveStreams} runs on. */
+export interface ServeStreams {
+    /** The host's requests, as bytes (a Node `Readable` fits). */
+    input: AsyncIterable<Uint8Array>;
+    /** The plugin's responses. */
+    output: FrameSink;
+    /** Where a warning about the plugin goes. Default: standard error. */
+    log?: (message: string) => void;
+}

package/serve/protocol-streams.contract.js

@@ -0,0 +1 @@
+export {};

package/serve/request-outcome.contract.d.ts

@@ -0,0 +1,9 @@
+/** What answering one request came to: the result, already written as JSON, or an error object. */
+export type RequestOutcome = {
+    ok: true;
+    resultJson: string;
+} | {
+    ok: false;
+    code: number;
+    message: string;
+};

package/serve/request-outcome.contract.js

@@ -0,0 +1 @@
+export {};

package/serve/serve.use-case.d.ts

@@ -0,0 +1,27 @@
+import type { SmithPlugin } from './plugin.contract.ts';
+import type { ServeStreams } from './protocol-streams.contract.ts';
+/**
+ * Runs a plugin on the process's standard input and output, and exits when the
+ * host sends `shutdown` or closes the stream. Use it as the whole body of the
+ * plugin's entry point:
+ *
+ * ```ts
+ * await serve({ describe: () => ({ ... }), discover: (params) => ({ ... }) })
+ * ```
+ *
+ * Standard output carries only the protocol's frames: whatever else the plugin
+ * or a library writes there goes to standard error instead. A failure of the
+ * stream exits with status 1 after the reason is printed.
+ */
+export declare function serve(plugin: SmithPlugin): Promise<never>;
+/**
+ * Answers requests from `input` on `output` until the host sends `shutdown`
+ * or the input ends, then resolves. This is the loop {@link serve} runs, on
+ * streams you choose: a test serves a plugin in-process over pipes with it.
+ *
+ * Semantics of the Go SDK's `serve.Serve`: requests are answered one at a time,
+ * in order; a request before `initialize` is refused (InvalidRequest);
+ * a notification (no `id`) gets no answer; an unreadable frame body is answered
+ * with ParseError and the loop goes on; an unreadable header ends it with an error.
+ */
+export declare function serveStreams(plugin: SmithPlugin, streams: ServeStreams): Promise<void>;