toolcraft 0.0.104 → 0.0.106

package/dist/testing/harness.js

@@ -11,6 +11,7 @@ import { fakeFetch } from "./fakes.js";
 import { createMemoryFs } from "./memory-fs.js";
 import { runParity } from "./parity.js";
 import { createRenderCapture } from "./render-capture.js";
+import { createManagedStream } from "../stream.js";
 function isHandlerFs(value) {
     return typeof value.readFile === "function";
 }
@@ -185,6 +186,75 @@ export function createCommandTestHarness(root, options = {}) {
     return {
         fs: memoryFs,
         timeline: cumulativeTimeline,
+        async stream(requestedPath, inputParams = {}, streamOptions = {}) {
+            const events = [];
+            const statuses = [];
+            try {
+                const resolved = resolveCommand(root, requestedPath);
+                const command = resolved.command;
+                if (command.stream === undefined) {
+                    throw new UserError(`Command "${resolved.path.join(".")}" is not a stream.`);
+                }
+                const sealedEnv = createSealedEnv(command.secrets, options.env, options.secrets);
+                const commandSecrets = resolveCommandSecrets(command, sealedEnv);
+                const diagnostics = createRuntimeLogger({
+                    level: options.logLevel ?? "debug",
+                    logger: () => undefined
+                });
+                const baseContext = {
+                    ...(options.services ?? {}),
+                    secrets: commandSecrets,
+                    fetch: runtimeFetch,
+                    fs: memoryFs,
+                    env: createEnv(sealedEnv),
+                    diagnostics,
+                    progress() { }
+                };
+                await assertCommandRequirements(command, { ...baseContext, params: undefined }, {
+                    apiVersion: options.apiVersion,
+                    env: sealedEnv
+                });
+                const schema = filterSchemaForScope(command.params, "sdk");
+                if (schema === undefined || schema.kind !== "object") {
+                    throw new ToolcraftBugError(`command "${command.name}" must define an object params schema for SDK.`);
+                }
+                const errors = [];
+                const params = validateObjectSchema(schema, inputParams, "", errors);
+                throwValidationErrors(errors);
+                const stream = createManagedStream({
+                    eventSchema: command.stream.event,
+                    signal: streamOptions.signal,
+                    onStatus: (event) => statuses.push(event),
+                    async create(signal, status) {
+                        return await command.handler({
+                            ...baseContext,
+                            params,
+                            signal,
+                            status,
+                            async refreshSecrets() {
+                                return resolveCommandSecrets(command, sealedEnv);
+                            }
+                        });
+                    }
+                });
+                const limit = streamOptions.limit ?? Number.POSITIVE_INFINITY;
+                try {
+                    for await (const event of stream) {
+                        events.push(event);
+                        if (events.length >= limit) {
+                            break;
+                        }
+                    }
+                }
+                finally {
+                    await stream.cancel();
+                }
+                return { ok: true, events, statuses };
+            }
+            catch (error) {
+                return { ok: false, events, statuses, error };
+            }
+        },
         async parity(requestedPath, inputParams = {}) {
             const resolved = resolveCommand(root, requestedPath);
             const sealedEnv = createSealedEnv(resolved.command.secrets, options.env, options.secrets);

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { createCommandTestHarness, type CommandTestHarness, type ConfirmationRequest, type EffectEvent, type HarnessOptions, type PipelineStage, type RunResult } from "./harness.js";
+export { createCommandTestHarness, type CommandTestHarness, type ConfirmationRequest, type EffectEvent, type HarnessOptions, type PipelineStage, type RunResult, type StreamRunResult } from "./harness.js";
 export { fakeFetch, fakeService, type FetchRoute, type ServiceCall } from "./fakes.js";
 export { createMemoryFs, type FsChange, type MemoryFs } from "./memory-fs.js";
 export type { ParityResult, SurfaceOutcome } from "./parity.js";

package/node_modules/tiny-stdio-mcp-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Poe Platform
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/tiny-stdio-mcp-server/README.md

@@ -0,0 +1,231 @@
+# tiny-stdio-mcp-server
+
+Minimal [Model Context Protocol](https://modelcontextprotocol.io) server for Node.js. Zero runtime dependencies, type-safe tool definitions, rich content helpers for images/audio/files.
+
+## Install
+
+```sh
+npm install tiny-stdio-mcp-server
+```
+
+## Quick start
+
+```ts
+import { createServer, defineSchema } from "tiny-stdio-mcp-server";
+
+const schema = defineSchema({
+  text: { type: "string", description: "Text to reverse" }
+});
+
+createServer({ name: "my-server", version: "1.0.0" })
+  .tool("reverse", "Reverse a string", schema, ({ text }) => {
+    return text.split("").reverse().join("");
+  })
+  .listen();
+```
+
+Run it:
+
+```sh
+node my-server.js
+```
+
+Any MCP client (Claude Code, Codex, etc.) can connect to it over stdio.
+
+## API
+
+### `createServer(options)`
+
+Creates a new MCP server.
+
+```ts
+const server = createServer({ name: "my-server", version: "1.0.0" });
+```
+
+### `.tool(name, description, schema, handler, outputSchema?)`
+
+Register a tool. The handler receives typed args matching the schema and returns a string, content helper, array of content, or a typed object when `outputSchema` is supplied.
+
+```ts
+const schema = defineSchema({
+  query: { type: "string", description: "Search query" },
+  limit: { type: "number", description: "Max results", optional: true }
+});
+
+server.tool("search", "Search for things", schema, async ({ query, limit }) => {
+  // `query` is string, `limit` is number | undefined
+  return `Found results for: ${query}`;
+});
+```
+
+For structured-data tools, pass a root-object output schema. The server advertises it as MCP `Tool.outputSchema`, validates successful handler results, and returns them as `CallToolResult.structuredContent`. Plain object returns receive a JSON text backstop in `content[]` for older clients. Explicit `CallToolResult` values keep their handler-supplied content blocks; the JSON text backstop is added only when `content` is empty.
+
+```ts
+const input = defineSchema({
+  query: { type: "string" }
+});
+const output = defineSchema({
+  items: {
+    type: "array",
+    items: {
+      type: "object",
+      properties: {
+        title: { type: "string" },
+        score: { type: "number" }
+      },
+      required: ["title", "score"]
+    }
+  }
+});
+
+server.tool(
+  "search",
+  "Search",
+  input,
+  async ({ query }) => ({
+    items: [{ title: query, score: 1 }]
+  }),
+  output
+);
+```
+
+Output schemas must have `type: "object"` at the root because MCP structured content is an object. Otherwise, any schema accepted by Ajv is supported, including composition keywords, nullable type unions, and local `$defs`/`$ref` references. Input and output schemas compile synchronously during `.tool()` or `.registerTool()` registration, so malformed schemas throw immediately instead of failing on the first tool call.
+
+Successful structured results must satisfy `outputSchema`. Validation failures use JSON-RPC `-32602` for inputs and `-32603` for outputs, with Ajv's formatted error text in the message and the raw Ajv error array in `error.data`. Explicit handler results with `isError: true` are passed through unchanged and are exempt from structured-content and output-schema validation.
+
+Tools whose natural result is prose, images, audio, files, or other content blocks should omit `outputSchema` and keep returning content.
+
+### `.listen()`
+
+Start listening on stdin/stdout (standard MCP stdio transport).
+
+```ts
+await server.listen();
+```
+
+### `.connect(transport)`
+
+Connect to a custom readable/writable stream pair.
+
+```ts
+await server.connect({ readable: process.stdin, writable: process.stdout });
+```
+
+### `.connectSDK(transport)`
+
+Connect using an SDK-compatible in-memory transport (for testing).
+
+```ts
+await server.connectSDK(sdkTransport);
+```
+
+### `.removeTool(name)` / `.notifyToolsChanged()`
+
+Dynamically add/remove tools at runtime and notify connected clients.
+
+## Configuration Options
+
+- `createServer({ name, version, toolCallTimeoutMs? })`: server identity plus an optional positive-integer tool timeout in milliseconds. Timed-out calls return JSON-RPC error `-32603`; handlers continue running in the background.
+- `.tool(name, description, schema, handler, outputSchema?)`: tool metadata, input schema, handler, and optional structured output schema.
+- `.connect({ readable, writable })`: custom stream transport for tests or embedded hosts.
+
+## `defineSchema(definition)`
+
+Type-safe schema builder. Returns a JSON Schema object with inferred TypeScript types.
+
+```ts
+const schema = defineSchema({
+  name: { type: "string", description: "User name" },
+  age: { type: "number", description: "User age", optional: true }
+});
+// Handler receives: { name: string; age?: number }
+```
+
+## Environment Variables
+
+This package does not read public environment variables.
+
+Supported types: `string`, `number`, `boolean`, `object`, `array`.
+
+## Content helpers
+
+Tool handlers can return rich content beyond plain text.
+
+### Images
+
+```ts
+import { Image } from "tiny-stdio-mcp-server";
+
+server.tool("screenshot", "Take a screenshot", schema, async () => {
+  return Image.fromBase64(base64Data, "image/png");
+  // or: await Image.fromUrl("https://example.com/image.png")
+  // or: Image.fromBytes(uint8Array)
+});
+```
+
+Supported formats: PNG, JPEG, GIF, WebP.
+
+### Audio
+
+```ts
+import { Audio } from "tiny-stdio-mcp-server";
+
+server.tool("speak", "Text to speech", schema, async () => {
+  return Audio.fromBase64(base64Data, "audio/mpeg");
+  // or: await Audio.fromUrl("https://example.com/audio.mp3")
+  // or: Audio.fromBytes(uint8Array, "mp3")
+});
+```
+
+Supported formats: MP3, WAV, OGG, M4A.
+
+### Files
+
+```ts
+import { File } from "tiny-stdio-mcp-server";
+
+server.tool("export", "Export data", schema, async () => {
+  return File.fromText(csvContent, "text/csv");
+  // or: File.fromBytes(uint8Array, "application/pdf")
+  // or: await File.fromUrl("https://example.com/report.pdf")
+});
+```
+
+### Mixed content
+
+Return arrays to send multiple content blocks:
+
+```ts
+server.tool("analyze", "Analyze image", schema, async () => {
+  const image = await Image.fromUrl(url);
+  return [image, "Analysis complete: found 3 objects"];
+});
+```
+
+## Testing
+
+Use `createTestPair` with the official MCP SDK for in-memory testing:
+
+```ts
+import { createTestPair } from "tiny-stdio-mcp-server/testing";
+
+const server = createServer({ name: "test", version: "1.0.0" }).tool(
+  "ping",
+  "Ping",
+  defineSchema({}),
+  () => "pong"
+);
+
+const { client, cleanup } = await createTestPair(server);
+
+const result = await client.callTool({ name: "ping", arguments: {} });
+// result.content === [{ type: "text", text: "pong" }]
+
+await cleanup();
+```
+
+Requires `@modelcontextprotocol/sdk` as a dev dependency.
+
+## License
+
+MIT

package/node_modules/tiny-stdio-mcp-server/dist/content/audio.d.ts

@@ -0,0 +1,15 @@
+import { type FromUrlOptions } from "./remote.js";
+export interface AudioContent {
+    type: "audio";
+    data: string;
+    mimeType: string;
+}
+export declare class Audio {
+    private readonly base64Data;
+    private readonly mimeType;
+    private constructor();
+    static fromUrl(url: string, options?: FromUrlOptions): Promise<Audio>;
+    static fromBytes(data: Uint8Array, format?: string): Audio;
+    static fromBase64(base64: string, mimeType: string): Audio;
+    toContentBlock(): AudioContent;
+}

package/node_modules/tiny-stdio-mcp-server/dist/content/audio.js

@@ -0,0 +1,84 @@
+import { assertBase64, fileTypeFromBuffer, parseContentType, safeRemoteLabel } from "./mime.js";
+import { readRemoteBytes } from "./remote.js";
+const SUPPORTED_AUDIO_MIMES = new Set([
+    "audio/mpeg",
+    "audio/wav",
+    "audio/ogg",
+    "audio/mp4",
+]);
+const AUDIO_FORMAT_MAP = {
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    mpeg: "audio/mpeg",
+};
+export class Audio {
+    base64Data;
+    mimeType;
+    constructor(base64Data, mimeType) {
+        this.base64Data = base64Data;
+        this.mimeType = mimeType;
+    }
+    static async fromUrl(url, options) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch audio from ${safeRemoteLabel(url)}: ${response.status} ${response.statusText}`);
+        }
+        const data = await readRemoteBytes(response, "audio", url, options);
+        const detected = fileTypeFromBuffer(data);
+        let mimeType;
+        if (detected && SUPPORTED_AUDIO_MIMES.has(detected.mime)) {
+            mimeType = detected.mime;
+        }
+        else {
+            const contentType = parseContentType(response.headers.get("content-type")).mimeType;
+            if (contentType && SUPPORTED_AUDIO_MIMES.has(contentType)) {
+                mimeType = contentType;
+            }
+            else {
+                throw new Error(`Unable to detect audio MIME type from ${safeRemoteLabel(url)}`);
+            }
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Audio(base64, mimeType);
+    }
+    static fromBytes(data, format) {
+        let mimeType;
+        if (format) {
+            if (format.includes("/")) {
+                mimeType = format.toLowerCase();
+            }
+            else {
+                mimeType = AUDIO_FORMAT_MAP[format.toLowerCase()] || `audio/${format}`;
+            }
+            if (!SUPPORTED_AUDIO_MIMES.has(mimeType)) {
+                throw new Error(`Unsupported audio MIME type: ${mimeType}`);
+            }
+        }
+        else {
+            const detected = fileTypeFromBuffer(data);
+            if (!detected || !SUPPORTED_AUDIO_MIMES.has(detected.mime)) {
+                throw new Error("Unable to detect audio MIME type from bytes");
+            }
+            mimeType = detected.mime;
+        }
+        const base64 = Buffer.from(data).toString("base64");
+        return new Audio(base64, mimeType);
+    }
+    static fromBase64(base64, mimeType) {
+        assertBase64(base64);
+        const normalizedMimeType = mimeType.toLowerCase();
+        if (!SUPPORTED_AUDIO_MIMES.has(normalizedMimeType)) {
+            throw new Error(`Unsupported audio MIME type: ${normalizedMimeType}`);
+        }
+        return new Audio(base64, normalizedMimeType);
+    }
+    toContentBlock() {
+        return {
+            type: "audio",
+            data: this.base64Data,
+            mimeType: this.mimeType,
+        };
+    }
+}

package/node_modules/tiny-stdio-mcp-server/dist/content/convert.d.ts

@@ -0,0 +1,16 @@
+import { Image, type ImageContent } from "./image.js";
+import { Audio, type AudioContent } from "./audio.js";
+import { File, type EmbeddedResource } from "./file.js";
+export interface TextContent {
+    type: "text";
+    text: string;
+}
+export type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource;
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ToolReturn = undefined | JsonPrimitive | JsonObject | Image | Audio | File | ContentBlock | Array<undefined | JsonPrimitive | JsonObject | Image | Audio | File | ContentBlock>;
+export declare function toContentBlocks(result: ToolReturn): ContentBlock[];
+export {};

package/node_modules/tiny-stdio-mcp-server/dist/content/convert.js

@@ -0,0 +1,61 @@
+import { Image } from "./image.js";
+import { Audio } from "./audio.js";
+import { File } from "./file.js";
+function convertSingleValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return { type: "text", text: String(value) };
+    }
+    if (value === null) {
+        return { type: "text", text: "null" };
+    }
+    if (value instanceof Image) {
+        return value.toContentBlock();
+    }
+    if (value instanceof Audio) {
+        return value.toContentBlock();
+    }
+    if (value instanceof File) {
+        return value.toContentBlock();
+    }
+    if (isContentBlock(value)) {
+        return value;
+    }
+    return { type: "text", text: JSON.stringify(value) };
+}
+export function toContentBlocks(result) {
+    if (result === undefined) {
+        return [];
+    }
+    if (Array.isArray(result)) {
+        return result.flatMap((item) => toContentBlocks(item));
+    }
+    return [convertSingleValue(result)];
+}
+function isContentBlock(value) {
+    if (!hasOwnProperty(value, "type") || typeof value.type !== "string") {
+        return false;
+    }
+    if (value.type === "text") {
+        return hasOwnProperty(value, "text") && typeof value.text === "string";
+    }
+    if (value.type === "image" || value.type === "audio") {
+        return hasOwnProperty(value, "data")
+            && typeof value.data === "string"
+            && hasOwnProperty(value, "mimeType")
+            && typeof value.mimeType === "string";
+    }
+    if (value.type !== "resource" || !hasOwnProperty(value, "resource")) {
+        return false;
+    }
+    const resource = value.resource;
+    return typeof resource === "object"
+        && resource !== null
+        && hasOwnProperty(resource, "uri")
+        && typeof resource.uri === "string"
+        && (!hasOwnProperty(resource, "mimeType") || typeof resource.mimeType === "string")
+        && ((hasOwnProperty(resource, "text") && typeof resource.text === "string")
+            || (hasOwnProperty(resource, "blob") && typeof resource.blob === "string"));
+}
+function hasOwnProperty(value, name) {
+    return Object.prototype.hasOwnProperty.call(value, name);
+}

package/node_modules/tiny-stdio-mcp-server/dist/content/file-type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal magic bytes detection for common media types.
+ * This can be replaced with `file-type` package (https://npm.im/file-type)
+ * if more comprehensive detection is needed. The API is designed to be
+ * compatible: fileTypeFromBuffer(data) returns { mime: string, ext: string } | undefined
+ */
+export interface FileTypeResult {
+    mime: string;
+    ext: string;
+}
+export declare function fileTypeFromBuffer(data: Uint8Array): FileTypeResult | undefined;

package/node_modules/tiny-stdio-mcp-server/dist/content/file-type.js

@@ -0,0 +1,93 @@
+/**
+ * Minimal magic bytes detection for common media types.
+ * This can be replaced with `file-type` package (https://npm.im/file-type)
+ * if more comprehensive detection is needed. The API is designed to be
+ * compatible: fileTypeFromBuffer(data) returns { mime: string, ext: string } | undefined
+ */
+export function fileTypeFromBuffer(data) {
+    if (data.length < 12) {
+        return undefined;
+    }
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (data[0] === 0x89 &&
+        data[1] === 0x50 &&
+        data[2] === 0x4e &&
+        data[3] === 0x47 &&
+        data[4] === 0x0d &&
+        data[5] === 0x0a &&
+        data[6] === 0x1a &&
+        data[7] === 0x0a) {
+        return { mime: "image/png", ext: "png" };
+    }
+    // JPEG: FF D8 FF
+    if (data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+        return { mime: "image/jpeg", ext: "jpg" };
+    }
+    // GIF: 47 49 46 38 (GIF8)
+    if (data[0] === 0x47 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x38) {
+        return { mime: "image/gif", ext: "gif" };
+    }
+    // WEBP: 52 49 46 46 ... 57 45 42 50 (RIFF...WEBP)
+    if (data[0] === 0x52 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x46 &&
+        data[8] === 0x57 &&
+        data[9] === 0x45 &&
+        data[10] === 0x42 &&
+        data[11] === 0x50) {
+        return { mime: "image/webp", ext: "webp" };
+    }
+    // MP3: FF FB or FF FA (MPEG audio) or 49 44 33 (ID3 tag)
+    if ((data[0] === 0xff && (data[1] === 0xfb || data[1] === 0xfa)) ||
+        (data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33)) {
+        return { mime: "audio/mpeg", ext: "mp3" };
+    }
+    // WAV: 52 49 46 46 ... 57 41 56 45 (RIFF...WAVE)
+    if (data[0] === 0x52 &&
+        data[1] === 0x49 &&
+        data[2] === 0x46 &&
+        data[3] === 0x46 &&
+        data[8] === 0x57 &&
+        data[9] === 0x41 &&
+        data[10] === 0x56 &&
+        data[11] === 0x45) {
+        return { mime: "audio/wav", ext: "wav" };
+    }
+    // OGG: 4F 67 67 53 (OggS)
+    if (data[0] === 0x4f &&
+        data[1] === 0x67 &&
+        data[2] === 0x67 &&
+        data[3] === 0x53) {
+        return { mime: "audio/ogg", ext: "ogg" };
+    }
+    // M4A: MP4 container with audio - check for M4A brand at offset 8
+    // ftyp followed by M4A brand
+    if (data[4] === 0x66 &&
+        data[5] === 0x74 &&
+        data[6] === 0x79 &&
+        data[7] === 0x70 &&
+        data[8] === 0x4d &&
+        data[9] === 0x34 &&
+        data[10] === 0x41) {
+        return { mime: "audio/mp4", ext: "m4a" };
+    }
+    // MP4: ... 66 74 79 70 (ftyp box, offset 4)
+    if (data[4] === 0x66 &&
+        data[5] === 0x74 &&
+        data[6] === 0x79 &&
+        data[7] === 0x70) {
+        return { mime: "video/mp4", ext: "mp4" };
+    }
+    // WEBM: 1A 45 DF A3 (EBML header)
+    if (data[0] === 0x1a &&
+        data[1] === 0x45 &&
+        data[2] === 0xdf &&
+        data[3] === 0xa3) {
+        return { mime: "video/webm", ext: "webm" };
+    }
+    return undefined;
+}

package/node_modules/tiny-stdio-mcp-server/dist/content/file.d.ts

@@ -0,0 +1,28 @@
+import { type FromUrlOptions } from "./remote.js";
+export interface TextResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export interface BlobResourceContents {
+    uri: string;
+    mimeType: string;
+    blob: string;
+}
+export interface EmbeddedResource {
+    type: "resource";
+    resource: TextResourceContents | BlobResourceContents;
+}
+export declare class File {
+    private readonly data;
+    private readonly mimeType;
+    private readonly isText;
+    private readonly name?;
+    private readonly charset;
+    private constructor();
+    static fromUrl(url: string, options?: FromUrlOptions): Promise<File>;
+    static fromBytes(data: Uint8Array, mimeType: string): File;
+    static fromText(text: string, mimeType?: string): File;
+    static fromBase64(base64: string, mimeType: string): File;
+    toContentBlock(): EmbeddedResource;
+}