toolcraft 0.0.1

package/dist/mcp.js

@@ -0,0 +1,354 @@
+import { access, readFile, writeFile } from "node:fs/promises";
+import { createServer, JSON_RPC_ERROR_CODES, ToolError, } from "tiny-stdio-mcp-server";
+import { toJsonSchema } from "agent-kit-schema";
+import { UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
+import { filterSchemaForScope } from "./schema-scope.js";
+const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
+function normalizeRoots(roots) {
+    if (!Array.isArray(roots)) {
+        return roots;
+    }
+    return {
+        kind: "group",
+        name: "",
+        aliases: [],
+        secrets: {},
+        children: roots,
+    };
+}
+function splitWords(value) {
+    const words = [];
+    let current = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index] ?? "";
+        const lower = char.toLowerCase();
+        const upper = char.toUpperCase();
+        const isSeparator = char === "-" || char === "_" || char === " " || char === ".";
+        if (isSeparator) {
+            if (current.length > 0) {
+                words.push(current.toLowerCase());
+                current = "";
+            }
+            continue;
+        }
+        const isUppercase = char !== lower && char === upper;
+        const previous = value[index - 1];
+        const next = value[index + 1];
+        const previousIsLowercase = previous !== undefined && previous === previous.toLowerCase() && previous !== previous.toUpperCase();
+        const nextIsLowercase = next !== undefined && next === next.toLowerCase() && next !== next.toUpperCase();
+        if (isUppercase && current.length > 0 && (previousIsLowercase || nextIsLowercase)) {
+            words.push(current.toLowerCase());
+            current = char;
+            continue;
+        }
+        current += char;
+    }
+    if (current.length > 0) {
+        words.push(current.toLowerCase());
+    }
+    return words;
+}
+function formatSegment(segment, casing) {
+    const words = splitWords(segment);
+    if (casing === "snake") {
+        return words.join("_");
+    }
+    return words
+        .map((word, index) => index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+        .join("");
+}
+function unwrapOptional(schema) {
+    if (schema.kind === "optional") {
+        return unwrapOptional(schema.inner);
+    }
+    return schema;
+}
+function isOptional(schema) {
+    return schema.kind === "optional";
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function createFs() {
+    return {
+        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
+        writeFile: async (path, contents) => {
+            await writeFile(path, contents);
+        },
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function createEnv(values = process.env) {
+    return {
+        get(key) {
+            return values[key];
+        },
+    };
+}
+function validateServices(services) {
+    for (const name of Object.keys(services)) {
+        if (RESERVED_SERVICE_NAMES.has(name)) {
+            throw new Error(`Service name "${name}" is reserved. Choose a different name.`);
+        }
+    }
+}
+function applySchemaCasing(schema, casing) {
+    if (schema.type !== "object" || schema.properties === undefined) {
+        if (schema.type === "array" && schema.items !== undefined) {
+            return {
+                ...schema,
+                items: applySchemaCasing(schema.items, casing),
+            };
+        }
+        return schema;
+    }
+    const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [
+        formatSegment(key, casing),
+        applySchemaCasing(value, casing),
+    ]));
+    const required = schema.required?.map((key) => formatSegment(key, casing));
+    return {
+        ...schema,
+        properties,
+        ...(required === undefined ? {} : { required }),
+    };
+}
+function collectParamSummaries(schema, casing, path = [], inheritedOptional = false) {
+    const summaries = [];
+    for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
+        const childSchema = unwrapOptional(rawChildSchema);
+        const nextPath = [...path, formatSegment(key, casing)];
+        const optional = inheritedOptional || isOptional(rawChildSchema);
+        if (childSchema.kind === "object") {
+            summaries.push(...collectParamSummaries(childSchema, casing, nextPath, optional));
+            continue;
+        }
+        summaries.push(`${nextPath.join(".")}${optional ? "" : " (required)"}`);
+    }
+    return summaries;
+}
+function buildToolDescription(description, params, casing) {
+    const summary = collectParamSummaries(params, casing);
+    const parameterSummary = summary.length === 0 ? "" : `Parameters: ${summary.join(", ")}.`;
+    if (description === undefined) {
+        return parameterSummary;
+    }
+    if (parameterSummary.length === 0) {
+        return description;
+    }
+    return `${description} ${parameterSummary}`;
+}
+function matchesAllowlist(toolName, allowlist) {
+    if (allowlist === undefined) {
+        return true;
+    }
+    const segments = toolName.split("__");
+    const candidates = segments.map((_segment, index) => segments.slice(0, index + 1).join("__"));
+    return candidates.some((candidate) => allowlist.includes(candidate));
+}
+function formatToolName(path) {
+    return path.map((segment) => formatSegment(segment, "snake")).join("__");
+}
+function enumerateTools(root, casing, allowlist) {
+    const tools = [];
+    function visit(node, path) {
+        if (node.kind === "command") {
+            if (!node.scope.includes("mcp")) {
+                return;
+            }
+            const name = formatToolName([...path, node.name]);
+            const params = filterSchemaForScope(node.params, "mcp");
+            if (!matchesAllowlist(name, allowlist)) {
+                return;
+            }
+            if (params === undefined || params.kind !== "object") {
+                throw new Error(`Bug: command "${name}" must define an object params schema for MCP.`);
+            }
+            tools.push({
+                command: node,
+                name,
+                description: buildToolDescription(node.description, params, casing),
+                inputSchema: applySchemaCasing(toJsonSchema(params), casing),
+            });
+            return;
+        }
+        const nextPath = [...path, node.name];
+        for (const child of node.children) {
+            visit(child, nextPath);
+        }
+    }
+    const rootPath = root.name.length === 0 ? [] : [root.name];
+    for (const child of root.children) {
+        visit(child, rootPath);
+    }
+    return tools;
+}
+function validateEnum(value, schema, label) {
+    if (!schema.values.includes(value)) {
+        throw new UserError(`Invalid value for "${label}". Expected one of: ${schema.values.map((candidate) => String(candidate)).join(", ")}.`);
+    }
+    return value;
+}
+function validateSchemaValue(schema, value, casing, label) {
+    const unwrappedSchema = unwrapOptional(schema);
+    if (value === null && unwrappedSchema.nullable === true) {
+        return null;
+    }
+    switch (unwrappedSchema.kind) {
+        case "string":
+            if (typeof value !== "string") {
+                throw new UserError(`Invalid value for "${label}". Expected a string.`);
+            }
+            return value;
+        case "number":
+            if (!isValidNumberSchemaValue(value, unwrappedSchema)) {
+                throw new UserError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(unwrappedSchema)}.`);
+            }
+            return value;
+        case "boolean":
+            if (typeof value !== "boolean") {
+                throw new UserError(`Invalid value for "${label}". Expected a boolean.`);
+            }
+            return value;
+        case "enum":
+            return validateEnum(value, unwrappedSchema, label);
+        case "array":
+            if (!Array.isArray(value)) {
+                throw new UserError(`Invalid value for "${label}". Expected an array.`);
+            }
+            return value.map((item, index) => validateSchemaValue(unwrappedSchema.item, item, casing, `${label}[${index}]`));
+        case "object":
+            return validateObjectSchema(unwrappedSchema, value, casing, label);
+    }
+}
+function validateObjectSchema(schema, value, casing, label) {
+    if (!isPlainObject(value)) {
+        throw new UserError(`Invalid value for "${label}". Expected an object.`);
+    }
+    const result = {};
+    const expectedKeys = new Map();
+    for (const [key, childSchema] of Object.entries(schema.shape)) {
+        expectedKeys.set(formatSegment(key, casing), [key, childSchema]);
+    }
+    for (const key of Object.keys(value)) {
+        if (!expectedKeys.has(key)) {
+            const fieldLabel = label.length === 0 ? key : `${label}.${key}`;
+            throw new UserError(`Unexpected parameter "${fieldLabel}".`);
+        }
+    }
+    for (const [inputKey, [outputKey, rawChildSchema]] of expectedKeys.entries()) {
+        const childSchema = unwrapOptional(rawChildSchema);
+        const hasValue = Object.prototype.hasOwnProperty.call(value, inputKey);
+        const fieldLabel = label.length === 0 ? inputKey : `${label}.${inputKey}`;
+        if (!hasValue) {
+            if (childSchema.default !== undefined) {
+                result[outputKey] = childSchema.default;
+                continue;
+            }
+            if (isOptional(rawChildSchema)) {
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${fieldLabel}".`);
+        }
+        result[outputKey] = validateSchemaValue(rawChildSchema, value[inputKey], casing, fieldLabel);
+    }
+    return result;
+}
+function validateToolArguments(schema, argumentsValue, casing) {
+    return validateObjectSchema(schema, argumentsValue ?? {}, casing, "");
+}
+function isContentBlock(value) {
+    if (!isPlainObject(value) || typeof value.type !== "string") {
+        return false;
+    }
+    return (value.type === "text" ||
+        value.type === "image" ||
+        value.type === "audio" ||
+        value.type === "resource");
+}
+function toToolContent(result) {
+    if (result === undefined) {
+        return [];
+    }
+    if (Array.isArray(result)) {
+        return result.flatMap((item) => toToolContent(item));
+    }
+    if (typeof result === "string" ||
+        typeof result === "number" ||
+        typeof result === "boolean") {
+        return [{ type: "text", text: String(result) }];
+    }
+    if (result === null) {
+        return [{ type: "text", text: "null" }];
+    }
+    if (isContentBlock(result)) {
+        return [result];
+    }
+    return [{ type: "text", text: JSON.stringify(result) }];
+}
+function toToolError(error) {
+    if (error instanceof ToolError) {
+        return error;
+    }
+    if (error instanceof UserError) {
+        return new ToolError(JSON_RPC_ERROR_CODES.INVALID_PARAMS, error.message);
+    }
+    if (error instanceof Error) {
+        return new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, error.message);
+    }
+    return new ToolError(JSON_RPC_ERROR_CODES.INTERNAL_ERROR, String(error));
+}
+export function createMCPServer(roots, options) {
+    const root = normalizeRoots(roots);
+    const casing = options.casing ?? "snake";
+    const services = (options.services ?? {});
+    validateServices(services);
+    const tools = enumerateTools(root, casing, options.tools);
+    const server = createServer({ name: options.name, version: options.version });
+    for (const tool of tools) {
+        server.tool(tool.name, tool.description, tool.inputSchema, async (argumentsValue) => {
+            try {
+                const secrets = resolveCommandSecrets(tool.command);
+                const baseContext = {
+                    ...services,
+                    secrets,
+                    fetch: globalThis.fetch,
+                    fs: createFs(),
+                    env: createEnv(),
+                    progress() {
+                        return undefined;
+                    },
+                };
+                await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });
+                const params = validateToolArguments(tool.command.params, argumentsValue, casing);
+                const result = await tool.command.handler({
+                    ...baseContext,
+                    params,
+                });
+                return toToolContent(result);
+            }
+            catch (error) {
+                throw toToolError(error);
+            }
+        });
+    }
+    return {
+        ...server,
+        connect(transport) {
+            return server.connectSDK(transport);
+        },
+    };
+}
+export async function runMCP(roots, options) {
+    const server = createMCPServer(roots, options);
+    await server.listen();
+}

package/dist/number-schema.d.ts

@@ -0,0 +1,3 @@
+import type { NumberSchema } from "agent-kit-schema";
+export declare function isValidNumberSchemaValue(value: unknown, schema: NumberSchema): value is number;
+export declare function getExpectedNumberDescription(schema: NumberSchema): string;

package/dist/number-schema.js

@@ -0,0 +1,8 @@
+export function isValidNumberSchemaValue(value, schema) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        (schema.jsonType !== "integer" || Number.isInteger(value)));
+}
+export function getExpectedNumberDescription(schema) {
+    return schema.jsonType === "integer" ? "an integer" : "a number";
+}

package/dist/renderer.d.ts

@@ -0,0 +1,5 @@
+import type { Command, RenderPrimitives } from "./index.js";
+export type OutputMode = "rich" | "md" | "json";
+type WriteFn = (chunk: string) => void;
+export declare function renderResult(command: Command<any, any, any, any>, result: unknown, output: OutputMode, primitives: RenderPrimitives, write?: WriteFn): void;
+export {};

package/dist/renderer.js

@@ -0,0 +1,148 @@
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isArrayOfObjects(value) {
+    return Array.isArray(value) && value.every((entry) => isObject(entry));
+}
+function stringifyValue(value) {
+    if (value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return stringifyJson(value);
+}
+function stringifyJson(value, spaces) {
+    try {
+        return JSON.stringify(value, (_key, currentValue) => (typeof currentValue === "bigint" ? currentValue.toString() : currentValue), spaces) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function renderObjectTable(result, primitives) {
+    const rows = Object.entries(result).map(([key, value]) => ({
+        key,
+        value: stringifyValue(value),
+    }));
+    return primitives.renderTable({
+        theme: primitives.getTheme(),
+        columns: [
+            {
+                name: "key",
+                title: "Key",
+                alignment: "left",
+                maxLen: Math.max("Key".length, ...rows.map((row) => row.key.length)),
+            },
+            {
+                name: "value",
+                title: "Value",
+                alignment: "left",
+                maxLen: Math.max("Value".length, ...rows.map((row) => row.value.length)),
+            },
+        ],
+        rows,
+    });
+}
+function renderObjectMarkdown(result) {
+    return Object.entries(result)
+        .map(([key, value]) => `- ${key}: ${stringifyValue(value)}`)
+        .join("\n");
+}
+function getColumnNames(rows) {
+    const names = new Set();
+    for (const row of rows) {
+        for (const name of Object.keys(row)) {
+            names.add(name);
+        }
+    }
+    return [...names];
+}
+function renderArrayTable(result, primitives) {
+    if (result.length === 0) {
+        return "[]";
+    }
+    const columnNames = getColumnNames(result);
+    return primitives.renderTable({
+        theme: primitives.getTheme(),
+        columns: columnNames.map((name) => ({
+            name,
+            title: name,
+            alignment: "left",
+            maxLen: Math.max(name.length, ...result.map((row) => (name in row ? stringifyValue(row[name]).length : 0))),
+        })),
+        rows: result.map((row) => Object.fromEntries(columnNames.map((name) => [name, name in row ? stringifyValue(row[name]) : ""]))),
+    });
+}
+function renderArrayMarkdown(result) {
+    if (result.length === 0) {
+        return "[]";
+    }
+    const columnNames = getColumnNames(result);
+    const header = `| ${columnNames.join(" | ")} |`;
+    const separator = `| ${columnNames.map(() => ":---").join(" | ")} |`;
+    const rows = result.map((row) => `| ${columnNames
+        .map((name) => (name in row ? stringifyValue(row[name]).replaceAll("|", "\\|") : ""))
+        .join(" | ")} |`);
+    return [header, separator, ...rows].join("\n");
+}
+function autoRender(result, output, primitives) {
+    if (result === null || result === undefined) {
+        if (output === "json") {
+            return stringifyJson({ ok: true }, 2);
+        }
+        return "Done.";
+    }
+    if (typeof result === "string") {
+        if (output === "json") {
+            return stringifyJson({ result }, 2);
+        }
+        return result;
+    }
+    if (isObject(result)) {
+        if (output === "rich") {
+            return renderObjectTable(result, primitives);
+        }
+        if (output === "md") {
+            return renderObjectMarkdown(result);
+        }
+        return stringifyJson(result, 2);
+    }
+    if (isArrayOfObjects(result)) {
+        if (output === "md") {
+            return renderArrayMarkdown(result);
+        }
+        if (output === "json") {
+            return stringifyJson(result, 2);
+        }
+        return renderArrayTable(result, primitives);
+    }
+    return stringifyJson(result, 2);
+}
+export function renderResult(command, result, output, primitives, write = (chunk) => {
+    process.stdout.write(chunk);
+}) {
+    if (output === "json" && command.render?.json) {
+        const payload = command.render.json(result, primitives);
+        if (payload !== undefined) {
+            write(`${stringifyJson(payload, 2)}\n`);
+        }
+        return;
+    }
+    if (output === "md" && command.render?.markdown) {
+        const payload = command.render.markdown(result, primitives);
+        if (typeof payload === "string" && payload.length > 0) {
+            write(`${payload}\n`);
+        }
+        return;
+    }
+    if (output === "rich" && command.render?.rich) {
+        command.render.rich(result, primitives);
+        return;
+    }
+    const payload = autoRender(result, output, primitives);
+    if (payload.length > 0) {
+        write(`${payload}\n`);
+    }
+}

package/dist/schema-scope.d.ts

@@ -0,0 +1,4 @@
+import type { AnySchema } from "agent-kit-schema";
+type SchemaScope = "cli" | "mcp" | "sdk";
+export declare function filterSchemaForScope(schema: AnySchema, scope: SchemaScope): AnySchema | undefined;
+export {};

package/dist/schema-scope.js

@@ -0,0 +1,34 @@
+export function filterSchemaForScope(schema, scope) {
+    if (schema.scope !== undefined && !schema.scope.includes(scope)) {
+        return undefined;
+    }
+    switch (schema.kind) {
+        case "optional": {
+            const inner = filterSchemaForScope(schema.inner, scope);
+            if (inner === undefined) {
+                return undefined;
+            }
+            if (inner.requiredScopes?.includes(scope)) {
+                return inner;
+            }
+            return { ...schema, inner };
+        }
+        case "array": {
+            const item = filterSchemaForScope(schema.item, scope);
+            return item === undefined ? undefined : { ...schema, item };
+        }
+        case "string":
+        case "number":
+        case "boolean":
+        case "enum":
+            return schema;
+        case "object":
+            return {
+                ...schema,
+                shape: Object.fromEntries(Object.entries(schema.shape).flatMap(([key, childSchema]) => {
+                    const filtered = filterSchemaForScope(childSchema, scope);
+                    return filtered === undefined ? [] : [[key, filtered]];
+                })),
+            };
+    }
+}

package/dist/sdk.compile-check.d.ts

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

package/dist/sdk.compile-check.js

@@ -0,0 +1,79 @@
+import { S } from "agent-kit-schema";
+import { defineCommand, defineGroup } from "./index.js";
+import { createSDK } from "./sdk.js";
+const ignoredRoot = defineGroup({
+    name: "root",
+    children: [
+        defineGroup({
+            name: "poe-code",
+            children: [
+                defineGroup({
+                    name: "generate",
+                    children: [
+                        defineCommand({
+                            name: "text",
+                            scope: ["sdk"],
+                            params: S.Object({
+                                prompt_text: S.String(),
+                                max_tokens: S.Optional(S.Number()),
+                            }),
+                            handler: async ({ params }) => ({
+                                model: "demo",
+                                content: params.prompt_text,
+                                maxTokens: params.max_tokens ?? 0,
+                            }),
+                        }),
+                        defineCommand({
+                            name: "HTTPServer",
+                            scope: ["sdk"],
+                            params: S.Object({
+                                APIKey: S.String(),
+                            }),
+                            handler: async ({ params }) => ({
+                                apiKey: params.APIKey,
+                            }),
+                        }),
+                        defineCommand({
+                            name: "cli-only",
+                            scope: ["cli"],
+                            params: S.Object({}),
+                            handler: async () => "hidden",
+                        }),
+                    ],
+                }),
+            ],
+        }),
+    ],
+});
+const ignoredOptions = {
+    casing: "camel",
+    services: {
+        logger: console,
+    },
+};
+const ignoredSdk = createSDK(ignoredRoot, ignoredOptions);
+const ignoredResult = ignoredSdk.poeCode.generate.text({
+    promptText: "hello",
+    maxTokens: 128,
+});
+void ignoredResult.then((value) => {
+    void value.model;
+    void value.content;
+    void value.maxTokens;
+});
+const ignoredHttpServerResult = ignoredSdk.poeCode.generate.httpServer({
+    apiKey: "secret",
+});
+void ignoredHttpServerResult.then((value) => {
+    void value.apiKey;
+});
+// @ts-expect-error cli-only commands are not exposed in the SDK surface
+void ignoredSdk.poeCode.generate.cliOnly;
+// @ts-expect-error wrong parameter name
+ignoredSdk.poeCode.generate.text({ prompt_text: "hello" });
+// @ts-expect-error wrong parameter type
+ignoredSdk.poeCode.generate.text({ promptText: 123 });
+// @ts-expect-error acronym command names should still camel-case cleanly
+void ignoredSdk.poeCode.generate.hTTPServer;
+// @ts-expect-error acronym parameter names should camel-case cleanly
+ignoredSdk.poeCode.generate.httpServer({ aPIKey: "secret" });