toolcraft 0.0.17 → 0.0.18

package/dist/mcp.d.ts

@@ -1,5 +1,6 @@
 import { type SDKTransport, type Server as TinyServer } from "tiny-stdio-mcp-server";
 import type { Group } from "./index.js";
+import { type ErrorReportsOption } from "./error-report.js";
 import { type HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type Casing = "snake" | "camel";
 type CmdkitServer = Omit<TinyServer, "connect"> & {
@@ -27,6 +28,7 @@ export interface RunMCPOptions<TServices extends object = Record<string, unknown
      */
     omitRootToolNamePrefix?: boolean;
     services?: TServices;
+    errorReports?: ErrorReportsOption;
     /**
      * Controls MCP input-schema key casing and accepted argument-key casing.
      *

package/dist/mcp.js

@@ -1,14 +1,28 @@
 import { access, readFile, writeFile } from "node:fs/promises";
-import { createServer, JSON_RPC_ERROR_CODES, ToolError, } from "tiny-stdio-mcp-server";
+import { createServer, JSON_RPC_ERROR_CODES, ToolError } from "tiny-stdio-mcp-server";
 import { toJsonSchema } from "toolcraft-schema";
-import { UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { ToolcraftBugError, UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { writeErrorReport } from "./error-report.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
-import { ApprovalDeclinedError, invokeWithHumanInLoop, } from "./human-in-loop/index.js";
+import { ApprovalDeclinedError, invokeWithHumanInLoop } from "./human-in-loop/index.js";
 import { hasMcpProxyGroups, resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { filterSchemaForScope } from "./schema-scope.js";
-const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
+import { enableSourceMaps } from "./stack-trim.js";
+import { suggest } from "./suggest.js";
+import { throwValidationErrors } from "./validation-errors.js";
+const RESERVED_SERVICE_NAMES = new Set([
+    "params",
+    "secrets",
+    "fetch",
+    "fs",
+    "env",
+    "progress",
+    "runtimeOptions",
+    "root"
+]);
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
 function normalizeRoots(roots) {
     if (!Array.isArray(roots)) {
         return roots;
@@ -18,7 +32,7 @@ function normalizeRoots(roots) {
         name: "",
         aliases: [],
         secrets: {},
-        children: roots,
+        children: roots
     };
 }
 function splitWords(value) {
@@ -39,7 +53,9 @@ function splitWords(value) {
         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 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());
@@ -59,7 +75,7 @@ function formatSegment(segment, casing) {
         return words.join("_");
     }
     return words
-        .map((word, index) => index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+        .map((word, index) => (index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`))
         .join("");
 }
 function unwrapOptional(schema) {
@@ -88,42 +104,45 @@ function createFs() {
             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.`);
+            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
         }
     }
 }
+function formatAvailableList(values) {
+    return `Available: ${[...values].sort().join(", ")}.`;
+}
 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),
+                items: applySchemaCasing(schema.items, casing)
             };
         }
         return schema;
     }
     const properties = Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [
         formatSegment(key, casing),
-        applySchemaCasing(value, casing),
+        applySchemaCasing(value, casing)
     ]));
     const required = schema.required?.map((key) => formatSegment(key, casing));
     return {
         ...schema,
         properties,
-        ...(required === undefined ? {} : { required }),
+        ...(required === undefined ? {} : { required })
     };
 }
 function collectParamSummaries(schema, casing, path = [], inheritedOptional = false) {
@@ -175,14 +194,14 @@ function enumerateTools(root, casing, allowlist, omitRootToolNamePrefix) {
                 return;
             }
             if (params === undefined || params.kind !== "object") {
-                throw new Error(`Bug: command "${name}" must define an object params schema for MCP.`);
+                throw new ToolcraftBugError(`command "${name}" must define an object params schema for MCP.`);
             }
             tools.push({
                 command: node,
                 commandPath: [...commandPath, node.name].join("."),
                 name,
                 description: buildToolDescription(node.description, params, casing),
-                inputSchema: applySchemaCasing(toJsonSchema(params), casing),
+                inputSchema: applySchemaCasing(toJsonSchema(params), casing)
             });
             return;
         }
@@ -212,13 +231,13 @@ function renderPendingApproval(pending) {
         content: [
             {
                 type: "text",
-                text: `Queued for human approval (id: ${pending.approvalId}). Track with \`toolcraft approvals show ${pending.approvalId}\`.`,
+                text: `Queued for human approval (id: ${pending.approvalId}). Track with \`toolcraft approvals show ${pending.approvalId}\`.`
             },
             {
                 type: "text",
-                text: JSON.stringify(pending),
-            },
-        ],
+                text: JSON.stringify(pending)
+            }
+        ]
     };
 }
 function renderDeclinedApproval(error) {
@@ -227,26 +246,45 @@ function renderDeclinedApproval(error) {
         content: [
             {
                 type: "text",
-                text: error.reason === undefined ? "Declined." : `Declined: ${error.reason}`,
+                text: error.reason === undefined ? "Declined." : `Declined: ${error.reason}`
             },
             {
                 type: "text",
                 text: JSON.stringify({
                     outcome: "declined",
                     reason: error.reason,
-                    commandPath: error.commandPath,
-                }),
-            },
-        ],
+                    commandPath: error.commandPath
+                })
+            }
+        ]
     };
 }
-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 formatEnumError(value, schema, label) {
+    const suggestionLine = typeof value === "string"
+        ? formatEnumSuggestionLine(value, schema.values.map((candidate) => String(candidate)))
+        : " ";
+    return `Invalid value for "${label}".${suggestionLine}Expected one of: ${schema.values.map((candidate) => String(candidate)).join(", ")}, got ${describeReceived(value)}.`;
 }
-function validateSchemaValue(schema, value, casing, label) {
+function formatEnumSuggestionLine(value, values) {
+    const suggestions = suggest(value, values);
+    return suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?\n` : " ";
+}
+function describeReceived(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "missing";
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    if (typeof value === "object")
+        return "object";
+    if (typeof value === "string") {
+        const s = value.length > 40 ? `${value.slice(0, 40)}…` : value;
+        return `${JSON.stringify(s)}`;
+    }
+    return JSON.stringify(value);
+}
+function validateSchemaValue(schema, value, casing, label, errors) {
     const unwrappedSchema = unwrapOptional(schema);
     if (value === null && unwrappedSchema.nullable === true) {
         return null;
@@ -254,33 +292,53 @@ function validateSchemaValue(schema, value, casing, label) {
     switch (unwrappedSchema.kind) {
         case "string":
             if (typeof value !== "string") {
-                throw new UserError(`Invalid value for "${label}". Expected a string.`);
+                errors.push({
+                    path: label,
+                    message: `Invalid value for "${label}". Expected a string, got ${describeReceived(value)}.`
+                });
             }
             return value;
         case "number":
             if (!isValidNumberSchemaValue(value, unwrappedSchema)) {
-                throw new UserError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(unwrappedSchema)}.`);
+                errors.push({
+                    path: label,
+                    message: `Invalid value for "${label}". Expected ${getExpectedNumberDescription(unwrappedSchema)}, got ${describeReceived(value)}.`
+                });
             }
             return value;
         case "boolean":
             if (typeof value !== "boolean") {
-                throw new UserError(`Invalid value for "${label}". Expected a boolean.`);
+                errors.push({
+                    path: label,
+                    message: `Invalid value for "${label}". Expected a boolean, got ${describeReceived(value)}.`
+                });
             }
             return value;
         case "enum":
-            return validateEnum(value, unwrappedSchema, label);
+            if (!unwrappedSchema.values.includes(value)) {
+                errors.push({ path: label, message: formatEnumError(value, unwrappedSchema, label) });
+            }
+            return value;
         case "array":
             if (!Array.isArray(value)) {
-                throw new UserError(`Invalid value for "${label}". Expected an array.`);
+                errors.push({
+                    path: label,
+                    message: `Invalid value for "${label}". Expected an array, got ${describeReceived(value)}.`
+                });
+                return value;
             }
-            return value.map((item, index) => validateSchemaValue(unwrappedSchema.item, item, casing, `${label}[${index}]`));
+            return value.map((item, index) => validateSchemaValue(unwrappedSchema.item, item, casing, `${label}[${index}]`, errors));
         case "object":
-            return validateObjectSchema(unwrappedSchema, value, casing, label);
+            return validateObjectSchema(unwrappedSchema, value, casing, label, errors);
     }
 }
-function validateObjectSchema(schema, value, casing, label) {
+function validateObjectSchema(schema, value, casing, label, errors) {
     if (!isPlainObject(value)) {
-        throw new UserError(`Invalid value for "${label}". Expected an object.`);
+        errors.push({
+            path: label,
+            message: `Invalid value for "${label}". Expected an object, got ${describeReceived(value)}.`
+        });
+        return {};
     }
     const result = {};
     const expectedKeys = new Map();
@@ -290,7 +348,10 @@ function validateObjectSchema(schema, value, casing, label) {
     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}".`);
+            errors.push({
+                path: fieldLabel,
+                message: `Unexpected parameter "${fieldLabel}". ${formatAvailableList([...expectedKeys.keys()].map((expectedKey) => label.length === 0 ? expectedKey : `${label}.${expectedKey}`))}`
+            });
         }
     }
     for (const [inputKey, [outputKey, rawChildSchema]] of expectedKeys.entries()) {
@@ -305,14 +366,18 @@ function validateObjectSchema(schema, value, casing, label) {
             if (isOptional(rawChildSchema)) {
                 continue;
             }
-            throw new UserError(`Missing required parameter "${fieldLabel}".`);
+            errors.push({ path: fieldLabel, message: `Missing required parameter "${fieldLabel}".` });
+            continue;
         }
-        result[outputKey] = validateSchemaValue(rawChildSchema, value[inputKey], casing, fieldLabel);
+        result[outputKey] = validateSchemaValue(rawChildSchema, value[inputKey], casing, fieldLabel, errors);
     }
     return result;
 }
 function validateToolArguments(schema, argumentsValue, casing) {
-    return validateObjectSchema(schema, argumentsValue ?? {}, casing, "");
+    const errors = [];
+    const result = validateObjectSchema(schema, argumentsValue ?? {}, casing, "", errors);
+    throwValidationErrors(errors);
+    return result;
 }
 function isContentBlock(value) {
     if (!isPlainObject(value) || typeof value.type !== "string") {
@@ -330,9 +395,7 @@ function toToolContent(result) {
     if (Array.isArray(result)) {
         return result.flatMap((item) => toToolContent(item));
     }
-    if (typeof result === "string" ||
-        typeof result === "number" ||
-        typeof result === "boolean") {
+    if (typeof result === "string" || typeof result === "number" || typeof result === "boolean") {
         return [{ type: "text", text: String(result) }];
     }
     if (result === null) {
@@ -362,7 +425,7 @@ function createResolvedMCPServer(root, options) {
     const servicesWithBuiltIns = {
         ...services,
         runtimeOptions,
-        root,
+        root
     };
     validateServices(services);
     const tools = enumerateTools(root, casing, options.tools, options.omitRootToolNamePrefix ?? false);
@@ -370,8 +433,10 @@ function createResolvedMCPServer(root, options) {
     const server = createServer({ name: options.name, version });
     for (const tool of tools) {
         server.tool(tool.name, tool.description, tool.inputSchema, async (argumentsValue) => {
+            let params;
+            let secrets;
             try {
-                const secrets = resolveCommandSecrets(tool.command);
+                secrets = resolveCommandSecrets(tool.command);
                 const baseContext = {
                     ...servicesWithBuiltIns,
                     secrets,
@@ -380,13 +445,13 @@ function createResolvedMCPServer(root, options) {
                     env: createEnv(),
                     progress() {
                         return undefined;
-                    },
+                    }
                 };
                 await assertCommandRequirements(tool.command, { ...baseContext, params: undefined });
-                const params = validateToolArguments(tool.command.params, argumentsValue, casing);
+                params = validateToolArguments(tool.command.params, argumentsValue, casing);
                 const result = await invokeWithHumanInLoop(tool.command, {
                     ...baseContext,
-                    params,
+                    params
                 }, runtimeOptions, tool.commandPath);
                 if (isHumanInLoopPending(result)) {
                     return renderPendingApproval(result);
@@ -397,6 +462,16 @@ function createResolvedMCPServer(root, options) {
                 if (error instanceof ApprovalDeclinedError) {
                     return renderDeclinedApproval(error);
                 }
+                await writeErrorReport({
+                    command: tool.command,
+                    commandPath: tool.commandPath,
+                    env: process.env,
+                    error,
+                    errorReports: options.errorReports,
+                    params,
+                    projectRoot: options.projectRoot,
+                    secrets
+                });
                 throw toToolError(error);
             }
         });
@@ -405,13 +480,13 @@ function createResolvedMCPServer(root, options) {
         ...server,
         connect(transport) {
             return server.connectSDK(transport);
-        },
+        }
     };
 }
 function resolveMCPVersion(version) {
     const resolvedVersion = version ?? findEntrypointPackageMetadata(process.argv[1])?.version;
     if (resolvedVersion === undefined) {
-        throw new Error("MCP version is required when no package.json version can be inferred from the entrypoint.");
+        throw new Error('MCP server version is required. Pass version: "x.y.z" to createMCPServer / runMCP, or run toolcraft from a project whose package.json defines "version".');
     }
     return resolvedVersion;
 }
@@ -430,14 +505,14 @@ function createDeferredMCPServer(root, options) {
         },
         connect(transport) {
             return resolveServer().then((server) => server.connect(transport));
-        },
+        }
     }, {
         get(target, property, receiver) {
             if (property === "then") {
                 return resolveServer().then.bind(resolveServer());
             }
             return Reflect.get(target, property, receiver);
-        },
+        }
     });
 }
 export function createMCPServer(roots, options) {
@@ -448,6 +523,7 @@ export function createMCPServer(roots, options) {
     return createDeferredMCPServer(root, options);
 }
 export async function runMCP(roots, options) {
+    enableSourceMaps();
     const root = mergeApprovalsGroup(normalizeRoots(roots));
     await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const server = createResolvedMCPServer(root, options);

package/dist/sdk.d.ts

@@ -1,5 +1,6 @@
 import type { ObjectSchema, Static } from "toolcraft-schema";
 import type { Group, Scope } from "./index.js";
+import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopPending, HumanInLoopRuntimeOptions } from "./human-in-loop/index.js";
 type ScopeInput = readonly Scope[] | undefined;
 type HumanInLoopMode = "sync" | "async";
@@ -12,8 +13,8 @@ type IncludesSDK<TScope> = TScope extends readonly Scope[] ? "sdk" extends TScop
 type EffectiveCommandHumanInLoopMode<TOwnHumanInLoopMode extends HumanInLoopModeInput, TInheritedHumanInLoopMode extends HumanInLoopMode | undefined> = TOwnHumanInLoopMode extends HumanInLoopMode ? TOwnHumanInLoopMode : TOwnHumanInLoopMode extends null ? undefined : TInheritedHumanInLoopMode;
 type EffectiveGroupHumanInLoopMode<TOwnHumanInLoopMode extends HumanInLoopModeInput, TInheritedHumanInLoopMode extends HumanInLoopMode | undefined> = TOwnHumanInLoopMode extends HumanInLoopMode ? TOwnHumanInLoopMode : TOwnHumanInLoopMode extends null ? undefined : TInheritedHumanInLoopMode;
 type Separator = "-" | "_" | " " | ".";
-type IsUppercase<TValue extends string> = TValue extends Uppercase<TValue> ? TValue extends Lowercase<TValue> ? false : true : false;
-type IsLowercase<TValue extends string> = TValue extends Lowercase<TValue> ? TValue extends Uppercase<TValue> ? false : true : false;
+type IsUppercase<TValue extends string> = TValue extends Uppercase<TValue> ? (TValue extends Lowercase<TValue> ? false : true) : false;
+type IsLowercase<TValue extends string> = TValue extends Lowercase<TValue> ? (TValue extends Uppercase<TValue> ? false : true) : false;
 type LastCharacter<TValue extends string> = TValue extends `${infer THead}${infer TTail}` ? TTail extends "" ? THead : LastCharacter<TTail> : never;
 type PushCurrentWord<TCurrent extends string, TWords extends readonly string[]> = TCurrent extends "" ? TWords : [...TWords, Lowercase<TCurrent>];
 type SplitCamelWords<TValue extends string, TCurrent extends string = "", TWords extends readonly string[] = []> = TValue extends `${infer TChar}${infer TRest}` ? TChar extends Separator ? SplitCamelWords<TRest, "", PushCurrentWord<TCurrent, TWords>> : IsUppercase<TChar> extends true ? TCurrent extends "" ? SplitCamelWords<TRest, TChar, TWords> : TRest extends `${infer TNext}${string}` ? IsLowercase<LastCharacter<TCurrent>> extends true ? SplitCamelWords<TRest, TChar, PushCurrentWord<TCurrent, TWords>> : IsLowercase<TNext> extends true ? SplitCamelWords<TRest, TChar, PushCurrentWord<TCurrent, TWords>> : SplitCamelWords<TRest, `${TCurrent}${TChar}`, TWords> : SplitCamelWords<TRest, `${TCurrent}${TChar}`, TWords> : SplitCamelWords<TRest, `${TCurrent}${TChar}`, TWords> : PushCurrentWord<TCurrent, TWords>;
@@ -64,6 +65,7 @@ export interface CreateSDKOptions<TServices extends object = Record<string, unkn
     casing?: "camel";
     humanInLoop?: HumanInLoopRuntimeOptions;
     projectRoot?: string;
+    errorReports?: ErrorReportsOption;
 }
 export declare function createSDK<TRootInfo, TServices extends object = Record<string, unknown>>(root: Group<any> & {
     readonly __agentKitGroupTypeInfo: TRootInfo;