toolcraft 0.0.17 → 0.0.18

package/dist/sdk.js

@@ -1,11 +1,25 @@
 import { access, readFile, writeFile } from "node:fs/promises";
-import { UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { ToolcraftBugError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
+import { writeErrorReport } from "./error-report.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
 import { hasMcpProxyGroups, resolveMcpProxies } from "./mcp-proxy.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"]);
+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 splitWords(value) {
     const words = [];
     let current = "";
@@ -24,7 +38,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());
@@ -69,30 +85,52 @@ 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 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(", ")}.`);
+function formatAvailableList(values) {
+    return `Available: ${[...values].sort().join(", ")}.`;
+}
+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 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 value;
+    return JSON.stringify(value);
 }
-function validateSchemaValue(schema, value, label) {
+function validateSchemaValue(schema, value, label, errors) {
     const unwrappedSchema = unwrapOptional(schema);
     if (value === null && unwrappedSchema.nullable === true) {
         return null;
@@ -100,33 +138,53 @@ function validateSchemaValue(schema, value, 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, `${label}[${index}]`));
+            return value.map((item, index) => validateSchemaValue(unwrappedSchema.item, item, `${label}[${index}]`, errors));
         case "object":
-            return validateObjectSchema(unwrappedSchema, value, label);
+            return validateObjectSchema(unwrappedSchema, value, label, errors);
     }
 }
-function validateObjectSchema(schema, value, label) {
+function validateObjectSchema(schema, value, 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();
@@ -136,7 +194,10 @@ function validateObjectSchema(schema, value, 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()) {
@@ -151,14 +212,18 @@ function validateObjectSchema(schema, value, 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], fieldLabel);
+        result[outputKey] = validateSchemaValue(rawChildSchema, value[inputKey], fieldLabel, errors);
     }
     return result;
 }
 function validateSDKArguments(schema, argumentsValue) {
-    return validateObjectSchema(schema, argumentsValue ?? {}, "");
+    const errors = [];
+    const result = validateObjectSchema(schema, argumentsValue ?? {}, "", errors);
+    throwValidationErrors(errors);
+    return result;
 }
 function defineMember(target, key, value) {
     if (Object.prototype.hasOwnProperty.call(target, key)) {
@@ -168,10 +233,11 @@ function defineMember(target, key, value) {
         value,
         enumerable: true,
         configurable: false,
-        writable: false,
+        writable: false
     });
 }
 export function createSDK(root, options = {}) {
+    enableSourceMaps();
     const mergedRoot = mergeApprovalsGroup(root);
     if (!hasMcpProxyGroups(mergedRoot)) {
         return createResolvedSDK(mergedRoot, options);
@@ -186,29 +252,47 @@ function createResolvedSDK(root, options = {}) {
     function build(node, path) {
         if (node.kind === "command") {
             return async (params) => {
-                const secrets = resolveCommandSecrets(node);
-                const baseContext = {
-                    ...services,
-                    runtimeOptions,
-                    root,
-                    secrets,
-                    fetch: globalThis.fetch,
-                    fs: createFs(),
-                    env: createEnv(),
-                    progress() {
-                        return undefined;
-                    },
-                };
-                await assertCommandRequirements(node, { ...baseContext, params: undefined });
-                const paramsSchema = filterSchemaForScope(node.params, "sdk");
-                if (paramsSchema === undefined || paramsSchema.kind !== "object") {
-                    throw new Error(`Bug: command "${node.name}" must define an object params schema for SDK.`);
+                const commandPath = [...path, node.name].join(".");
+                let secrets;
+                let validatedParams;
+                try {
+                    secrets = resolveCommandSecrets(node);
+                    const baseContext = {
+                        ...services,
+                        runtimeOptions,
+                        root,
+                        secrets,
+                        fetch: globalThis.fetch,
+                        fs: createFs(),
+                        env: createEnv(),
+                        progress() {
+                            return undefined;
+                        }
+                    };
+                    await assertCommandRequirements(node, { ...baseContext, params: undefined });
+                    const paramsSchema = filterSchemaForScope(node.params, "sdk");
+                    if (paramsSchema === undefined || paramsSchema.kind !== "object") {
+                        throw new ToolcraftBugError(`command "${node.name}" must define an object params schema for SDK.`);
+                    }
+                    validatedParams = validateSDKArguments(paramsSchema, params);
+                    return await invokeWithHumanInLoop(node, {
+                        ...baseContext,
+                        params: validatedParams
+                    }, runtimeOptions, commandPath);
+                }
+                catch (error) {
+                    await writeErrorReport({
+                        command: node,
+                        commandPath,
+                        env: process.env,
+                        error,
+                        errorReports: options.errorReports,
+                        params: validatedParams,
+                        projectRoot: options.projectRoot,
+                        secrets
+                    });
+                    throw error;
                 }
-                const validatedParams = validateSDKArguments(paramsSchema, params);
-                return invokeWithHumanInLoop(node, {
-                    ...baseContext,
-                    params: validatedParams,
-                }, runtimeOptions, [...path, node.name].join("."));
             };
         }
         const output = {};
@@ -263,7 +347,7 @@ function createDeferredSDK(root, options) {
                 return path.length === 0 ? resolveSDK().then.bind(resolveSDK()) : undefined;
             }
             return createPathProxy([...path, property]);
-        },
+        }
     });
     return createPathProxy([]);
 }

package/dist/source-snippet.d.ts

@@ -0,0 +1,8 @@
+export interface SourceSnippetOptions {
+    source: string;
+    line: number;
+    column?: number;
+    context?: number;
+    filePath?: string;
+}
+export declare function renderSourceSnippet(opts: SourceSnippetOptions): string;

package/dist/source-snippet.js

@@ -0,0 +1,42 @@
+import { text } from "@poe-code/design-system";
+export function renderSourceSnippet(opts) {
+    const lines = opts.source.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+    const line = clampInteger(opts.line, 1, Math.max(lines.length, 1));
+    const context = Math.max(0, Math.floor(opts.context ?? 2));
+    const startLine = Math.max(1, line - context);
+    const endLine = Math.min(lines.length, line + context);
+    const gutterWidth = String(endLine).length;
+    const output = [];
+    if (opts.filePath !== undefined) {
+        output.push(muted(`--> ${opts.filePath}:${line}${opts.column === undefined ? "" : `:${Math.max(1, opts.column)}`}`));
+    }
+    output.push(renderDivider(gutterWidth));
+    for (let currentLine = startLine; currentLine <= endLine; currentLine += 1) {
+        const sourceLine = lines[currentLine - 1] ?? "";
+        output.push(`${muted(String(currentLine).padStart(gutterWidth, " "))} | ${sourceLine}`);
+        if (currentLine === line && opts.column !== undefined) {
+            const column = Math.max(1, Math.floor(opts.column));
+            output.push(`${muted(" ".repeat(gutterWidth))} | ${" ".repeat(column - 1)}${error("^")}`);
+        }
+    }
+    output.push(renderDivider(gutterWidth));
+    return output.join("\n");
+}
+function renderDivider(gutterWidth) {
+    return `${muted(" ".repeat(gutterWidth))} |`;
+}
+function clampInteger(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
+function muted(value) {
+    return shouldStyleStderr() ? text.muted(value) : value;
+}
+function error(value) {
+    return shouldStyleStderr() ? text.error(value) : value;
+}
+function shouldStyleStderr() {
+    return process.stderr.isTTY === true;
+}

package/dist/stack-trim.d.ts

@@ -0,0 +1,4 @@
+export type DebugStackMode = "trim" | "raw";
+export declare function enableSourceMaps(): void;
+export declare function formatDebugStack(stack: string, mode: DebugStackMode): string;
+export declare function trimStack(stack: string): string;

package/dist/stack-trim.js

@@ -0,0 +1,70 @@
+const HIDDEN_FRAME_SUMMARY_PREFIX = "    … (";
+const HIDDEN_FRAME_SUMMARY_SUFFIX = " hidden — pass --debug=raw to show)";
+export function enableSourceMaps() {
+    process.setSourceMapsEnabled?.(true);
+}
+export function formatDebugStack(stack, mode) {
+    return mode === "raw" ? stack : trimStack(stack);
+}
+export function trimStack(stack) {
+    const sections = splitStackSections(stack);
+    const trimmed = sections.map((section) => trimStackSection(section));
+    const hiddenFrameCount = trimmed.reduce((count, section) => count + section.hiddenFrameCount, 0);
+    if (hiddenFrameCount === 0) {
+        return stack;
+    }
+    return trimmed.flatMap((section) => section.lines).join("\n");
+}
+function splitStackSections(stack) {
+    const lines = stack.split("\n");
+    const firstLine = lines[0];
+    if (firstLine === undefined) {
+        return [];
+    }
+    const sections = [{ header: firstLine, lines: [] }];
+    for (const line of lines.slice(1)) {
+        if (isCauseHeader(line)) {
+            sections.push({ header: line, lines: [] });
+            continue;
+        }
+        sections[sections.length - 1]?.lines.push(line);
+    }
+    return sections;
+}
+function trimStackSection(section) {
+    const userFrames = [];
+    const skippedFrames = [];
+    for (const line of section.lines) {
+        if (isFrameworkOrRuntimeFrame(line)) {
+            skippedFrames.push(line);
+            continue;
+        }
+        userFrames.push(line);
+    }
+    if (skippedFrames.length === 0) {
+        return {
+            lines: [section.header, ...section.lines],
+            hiddenFrameCount: 0
+        };
+    }
+    return {
+        lines: [section.header, ...userFrames, formatHiddenFrameSummary(skippedFrames.length)],
+        hiddenFrameCount: skippedFrames.length
+    };
+}
+function isCauseHeader(line) {
+    return line.trimStart().startsWith("[cause]:");
+}
+function isFrameworkOrRuntimeFrame(line) {
+    const normalized = line.replaceAll("\\", "/");
+    return (normalized.includes("node_modules/toolcraft/") ||
+        normalized.includes("node_modules/toolcraft-openapi/") ||
+        normalized.includes("node_modules/toolcraft-schema/") ||
+        normalized.includes("node_modules/commander/") ||
+        normalized.includes("node:internal/") ||
+        normalized.includes("/packages/toolcraft/src/"));
+}
+function formatHiddenFrameSummary(count) {
+    const plural = count === 1 ? "" : "s";
+    return `${HIDDEN_FRAME_SUMMARY_PREFIX}${count} framework / runtime frame${plural}${HIDDEN_FRAME_SUMMARY_SUFFIX}`;
+}

package/dist/suggest.d.ts

@@ -0,0 +1,4 @@
+export declare function suggest(input: string, candidates: readonly string[], opts?: {
+    max?: number;
+    threshold?: number;
+}): string[];

package/dist/suggest.js

@@ -0,0 +1,46 @@
+export function suggest(input, candidates, opts = {}) {
+    if (input.length === 0) {
+        return [];
+    }
+    const max = opts.max ?? 3;
+    const threshold = opts.threshold ?? Math.max(1, Math.floor(input.length / 4));
+    return candidates
+        .map((candidate) => ({
+        candidate,
+        distance: damerauLevenshtein(input, candidate)
+    }))
+        .filter(({ distance }) => distance <= threshold)
+        .sort((left, right) => {
+        if (left.distance !== right.distance) {
+            return left.distance - right.distance;
+        }
+        return left.candidate.localeCompare(right.candidate);
+    })
+        .slice(0, max)
+        .map(({ candidate }) => candidate);
+}
+function damerauLevenshtein(left, right) {
+    const distances = Array.from({ length: left.length + 1 }, () => Array.from({ length: right.length + 1 }, () => 0));
+    for (let row = 0; row <= left.length; row += 1) {
+        distances[row][0] = row;
+    }
+    for (let column = 0; column <= right.length; column += 1) {
+        distances[0][column] = column;
+    }
+    for (let row = 1; row <= left.length; row += 1) {
+        for (let column = 1; column <= right.length; column += 1) {
+            const substitutionCost = left[row - 1] === right[column - 1] ? 0 : 1;
+            const deletion = distances[row - 1][column] + 1;
+            const insertion = distances[row][column - 1] + 1;
+            const substitution = distances[row - 1][column - 1] + substitutionCost;
+            distances[row][column] = Math.min(deletion, insertion, substitution);
+            if (row > 1 &&
+                column > 1 &&
+                left[row - 1] === right[column - 2] &&
+                left[row - 2] === right[column - 1]) {
+                distances[row][column] = Math.min(distances[row][column], distances[row - 2][column - 2] + 1);
+            }
+        }
+    }
+    return distances[left.length][right.length];
+}

package/dist/user-error.d.ts

@@ -1,3 +1,6 @@
 export declare class UserError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class ToolcraftBugError extends Error {
     constructor(message: string);
 }

package/dist/user-error.js

@@ -1,6 +1,12 @@
 export class UserError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UserError";
+    }
+}
+export class ToolcraftBugError extends Error {
     constructor(message) {
         super(message);
-        this.name = "UserError";
+        this.name = "ToolcraftBugError";
     }
 }

package/dist/validation-errors.d.ts

@@ -0,0 +1,5 @@
+export type ValidationError = {
+    path: string;
+    message: string;
+};
+export declare function throwValidationErrors(errors: readonly ValidationError[]): void;

package/dist/validation-errors.js

@@ -0,0 +1,18 @@
+import { UserError } from "./user-error.js";
+const MAX_RENDERED_VALIDATION_ERRORS = 10;
+export function throwValidationErrors(errors) {
+    if (errors.length === 0) {
+        return;
+    }
+    if (errors.length === 1) {
+        throw new UserError(errors[0]?.message ?? "Invalid parameters.");
+    }
+    const rendered = errors
+        .slice(0, MAX_RENDERED_VALIDATION_ERRORS)
+        .map((error) => `  - ${error.path}: ${error.message}`);
+    const remaining = errors.length - rendered.length;
+    if (remaining > 0) {
+        rendered.push(`  … and ${remaining} more`);
+    }
+    throw new UserError(`${errors.length} parameter errors:\n${rendered.join("\n")}`);
+}

package/node_modules/@poe-code/design-system/dist/components/help-formatter-plain.d.ts

@@ -1,4 +1,5 @@
 import type { CommandInfo, FormatColumnsOptions, OptionInfo } from "./help-formatter.js";
+export declare function stripAnsi(value: string): string;
 export declare function formatColumns(opts: FormatColumnsOptions): string;
 export declare function formatCommandList(commands: CommandInfo[]): string;
 export declare function formatOptionList(options: OptionInfo[]): string;

package/node_modules/@poe-code/design-system/dist/components/help-formatter-plain.js

@@ -1,4 +1,4 @@
-function stripAnsi(value) {
+export function stripAnsi(value) {
     let output = "";
     for (let index = 0; index < value.length; index += 1) {
         if (value[index] === "\u001b") {

package/node_modules/@poe-code/design-system/dist/components/text.d.ts

@@ -10,6 +10,7 @@ export declare const text: {
     readonly usageCommand: (content: string) => string;
     readonly link: (content: string) => string;
     readonly muted: (content: string) => string;
+    readonly error: (content: string) => string;
     readonly badge: (content: string) => string;
     readonly selectLabel: (label: string, detail?: string) => string;
 };

package/node_modules/@poe-code/design-system/dist/components/text.js

@@ -91,6 +91,14 @@ export const text = {
             return `*${content}*`;
         return getTheme().muted(content);
     },
+    error(content) {
+        const format = resolveOutputFormat();
+        if (format === "json")
+            return content;
+        if (format === "markdown")
+            return `**${content}**`;
+        return getTheme().error(content);
+    },
     badge(content) {
         const format = resolveOutputFormat();
         if (format === "json")

package/node_modules/@poe-code/design-system/dist/dashboard/buffer.js

@@ -126,6 +126,9 @@ export function cellToAnsi(cell) {
     if (style.dim) {
         painter = painter.dim;
     }
+    if (style.underline) {
+        painter = painter.underline;
+    }
     if (style.fg) {
         painter = applyForegroundColor(painter, style.fg);
     }
@@ -158,6 +161,9 @@ function normalizeStyle(style) {
     if (style?.dim !== undefined) {
         next.dim = style.dim;
     }
+    if (style?.underline !== undefined) {
+        next.underline = style.underline;
+    }
     return next;
 }
 function normalizeSize(value) {
@@ -168,7 +174,8 @@ function cellsEqual(left, right) {
         && left.style.fg === right.style.fg
         && left.style.bg === right.style.bg
         && left.style.bold === right.style.bold
-        && left.style.dim === right.style.dim;
+        && left.style.dim === right.style.dim
+        && left.style.underline === right.style.underline;
 }
 function applyForegroundColor(instance, color) {
     if (color.startsWith("#")) {

package/node_modules/@poe-code/design-system/dist/dashboard/keymap.d.ts

@@ -1,3 +1,8 @@
 import type { KeypressEvent } from "./terminal.js";
 import type { Command } from "./types.js";
 export declare function createKeymap(overrides?: Partial<Record<Command, string[]>>): (event: KeypressEvent) => Command | undefined;
+export declare function createKeymap<TCommand extends string>(overrides: Partial<Record<TCommand, string[]>> | undefined, options: {
+    commands: readonly TCommand[];
+    defaultBindings: Record<TCommand, readonly string[]>;
+}): (event: KeypressEvent) => TCommand | undefined;
+export declare function canonicalizeBinding(binding: string): string | undefined;