toolcraft 0.0.17 → 0.0.19

package/dist/index.js

@@ -1,7 +1,8 @@
 import { fileURLToPath } from "node:url";
 import { ApprovalDeclinedError } from "./human-in-loop/types.js";
 import { mergeHumanInLoopFromGroup, validateHumanInLoopOnDefine } from "./human-in-loop/config.js";
-import { UserError } from "./user-error.js";
+import { ToolcraftBugError, UserError } from "./user-error.js";
+import { suggest } from "./suggest.js";
 const commandConfigSymbol = Symbol("toolcraft.command.config");
 const groupConfigSymbol = Symbol("toolcraft.group.config");
 const commandSourcePathSymbol = Symbol("toolcraft.command.sourcePath");
@@ -12,7 +13,7 @@ function cloneSecretDefinition(secret) {
     return {
         env: secret.env,
         description: secret.description,
-        optional: secret.optional,
+        optional: secret.optional
     };
 }
 function cloneSecrets(secrets) {
@@ -28,7 +29,7 @@ function cloneRequires(requires) {
     return {
         auth: requires.auth,
         apiVersion: requires.apiVersion,
-        check: requires.check,
+        check: requires.check
     };
 }
 function cloneStringArray(values) {
@@ -46,13 +47,13 @@ function cloneMcpServerConfig(config) {
             transport: "stdio",
             command: config.command,
             args: cloneStringArray(config.args),
-            env: cloneStringRecord(config.env),
+            env: cloneStringRecord(config.env)
         };
     }
     return {
         transport: "http",
         url: config.url,
-        headers: cloneStringRecord(config.headers),
+        headers: cloneStringRecord(config.headers)
     };
 }
 function cloneRenameMap(rename) {
@@ -156,11 +157,9 @@ function mergeRequires(parent, child) {
     const merged = {
         auth: child?.auth ?? parent?.auth,
         apiVersion: child?.apiVersion ?? parent?.apiVersion,
-        check: composeChecks(parent?.check, child?.check),
+        check: composeChecks(parent?.check, child?.check)
     };
-    if (merged.auth === undefined &&
-        merged.apiVersion === undefined &&
-        merged.check === undefined) {
+    if (merged.auth === undefined && merged.apiVersion === undefined && merged.check === undefined) {
         return undefined;
     }
     return merged;
@@ -207,12 +206,33 @@ export function resolveCommandSecrets(command, env = process.env) {
         const value = env[secret.env];
         if (value === undefined && secret.optional !== true) {
             const details = secret.description ? `\n  ${secret.description}` : "";
-            throw new UserError(`Error: Missing required secret ${secret.env}${details}`);
+            const candidates = Object.keys(env).filter((candidate) => candidate !== secret.env && env[candidate] !== undefined);
+            const suggestions = suggestSecretEnv(secret.env, candidates);
+            const suggestionLine = suggestions.length > 0 ? `\nDid you mean: ${suggestions.join(", ")}?` : "";
+            throw new UserError(`Missing required secret ${secret.env}${details}${suggestionLine}`);
         }
         secrets[name] = value;
     }
     return secrets;
 }
+function suggestSecretEnv(input, candidates) {
+    const directSuggestions = suggest(input, candidates);
+    if (!input.includes("_")) {
+        return directSuggestions;
+    }
+    const inputParts = input.split("_");
+    const firstPart = inputParts[0];
+    const lastPart = inputParts[inputParts.length - 1];
+    const relatedCandidates = candidates.filter((candidate) => {
+        const candidateParts = candidate.split("_");
+        return (candidateParts[0] === firstPart &&
+            candidateParts[candidateParts.length - 1] === lastPart);
+    });
+    const expandedSuggestions = suggest(input, relatedCandidates, {
+        threshold: Math.max(4, Math.floor(input.length / 4))
+    });
+    return [...new Set([...directSuggestions, ...expandedSuggestions])].slice(0, 3);
+}
 export async function assertCommandRequirements(command, context, options = {}) {
     const requires = command.requires;
     if (requires === undefined) {
@@ -221,22 +241,22 @@ export async function assertCommandRequirements(command, context, options = {})
     const env = options.env ?? process.env;
     const authEnvVar = options.authEnvVar ?? "POE_API_KEY";
     if (requires.auth === true && env[authEnvVar] === undefined) {
-        throw new UserError(`Error: Command "${command.name}" requires authentication.\n  Run 'poe-code login' first.`);
+        throw new UserError(`Command "${command.name}" requires authentication.\n  Run 'poe-code login' first.`);
     }
     if (requires.apiVersion !== undefined) {
         const minimumVersion = parseMinimumApiVersion(requires.apiVersion);
         if (minimumVersion === undefined) {
-            throw new UserError(`Error: Command "${command.name}" has invalid apiVersion requirement "${requires.apiVersion}". Expected format ">=X.Y.Z".`);
+            throw new UserError(`Command "${command.name}" has invalid apiVersion requirement "${requires.apiVersion}". Expected format ">=X.Y.Z".`);
         }
         if (options.apiVersion === undefined) {
-            throw new UserError(`Error: Command "${command.name}" requires API version ${requires.apiVersion}, but no runner API version was provided.`);
+            throw new UserError(`Command "${command.name}" requires API version ${requires.apiVersion}, but no runner API version was provided.`);
         }
         const runnerVersion = parseSimpleSemver(options.apiVersion);
         if (runnerVersion === undefined) {
-            throw new UserError(`Error: Command "${command.name}" requires API version ${requires.apiVersion}, but runner API version "${options.apiVersion}" is not valid semver.`);
+            throw new UserError(`Command "${command.name}" requires API version ${requires.apiVersion}, but runner API version "${options.apiVersion}" is not valid semver.`);
         }
         if (compareSemver(runnerVersion, minimumVersion) < 0) {
-            throw new UserError(`Error: Command "${command.name}" requires API version ${requires.apiVersion}, but runner API version is ${options.apiVersion}.`);
+            throw new UserError(`Command "${command.name}" requires API version ${requires.apiVersion}, but runner API version is ${options.apiVersion}.`);
         }
     }
     const checkResult = await requires.check?.(context);
@@ -247,7 +267,7 @@ export async function assertCommandRequirements(command, context, options = {})
 function mergeSecrets(parent, child) {
     return cloneSecrets({
         ...parent,
-        ...child,
+        ...child
     });
 }
 function resolveCommandScope(ownScope, inheritedScope) {
@@ -270,7 +290,7 @@ function createBaseCommand(config) {
         humanInLoop: config.humanInLoop,
         requires: cloneRequires(config.requires),
         handler: config.handler,
-        render: config.render,
+        render: config.render
     };
     Object.defineProperty(command, commandConfigSymbol, {
         value: {
@@ -278,8 +298,8 @@ function createBaseCommand(config) {
             humanInLoop: config.humanInLoop,
             secrets: cloneSecrets(config.secrets),
             requires: cloneRequires(config.requires),
-            sourcePath: inferCommandSourcePath(),
-        },
+            sourcePath: inferCommandSourcePath()
+        }
     });
     return command;
 }
@@ -294,7 +314,7 @@ function createBaseGroup(config) {
         secrets: cloneSecrets(config.secrets),
         requires: cloneRequires(config.requires),
         children: [],
-        default: undefined,
+        default: undefined
     };
     Object.defineProperty(group, groupConfigSymbol, {
         value: {
@@ -306,8 +326,8 @@ function createBaseGroup(config) {
             rename: cloneRenameMap(config.rename),
             requires: cloneRequires(config.requires),
             children: [...config.children],
-            default: config.default,
-        },
+            default: config.default
+        }
     });
     return group;
 }
@@ -332,7 +352,7 @@ function materializeCommand(command, inherited) {
         humanInLoop: mergeHumanInLoopFromGroup(inherited.humanInLoop, internal.humanInLoop),
         requires: mergeRequires(inherited.requires, internal.requires),
         handler: command.handler,
-        render: command.render,
+        render: command.render
     };
     Object.defineProperty(materialized, commandConfigSymbol, {
         value: {
@@ -340,11 +360,11 @@ function materializeCommand(command, inherited) {
             humanInLoop: internal.humanInLoop,
             secrets: cloneSecrets(internal.secrets),
             requires: cloneRequires(internal.requires),
-            sourcePath: internal.sourcePath,
-        },
+            sourcePath: internal.sourcePath
+        }
     });
     Object.defineProperty(materialized, commandSourcePathSymbol, {
-        value: internal.sourcePath,
+        value: internal.sourcePath
     });
     return materialized;
 }
@@ -353,7 +373,7 @@ function mergeInheritedMetadata(group, inherited) {
         scope: resolveGroupScope(group.scope, inherited.scope),
         humanInLoop: mergeHumanInLoopFromGroup(inherited.humanInLoop, group.humanInLoop),
         secrets: mergeSecrets(inherited.secrets, group.secrets),
-        requires: mergeRequires(inherited.requires, group.requires),
+        requires: mergeRequires(inherited.requires, group.requires)
     };
 }
 function materializeGroup(group, inherited) {
@@ -364,11 +384,11 @@ function materializeGroup(group, inherited) {
     if (internal.default !== undefined) {
         const defaultIndex = internal.children.indexOf(internal.default);
         if (defaultIndex === -1) {
-            throw new UserError(`Default command "${internal.default.name}" must be listed in children.`);
+            throw new ToolcraftBugError(`Default command "${internal.default.name}" must be listed in children.`);
         }
         const resolvedDefault = materializedChildren[defaultIndex];
         if (resolvedDefault?.kind !== "command") {
-            throw new UserError(`Default child "${internal.default.name}" must be a command.`);
+            throw new ToolcraftBugError(`Default child "${internal.default.name}" must be a command.`);
         }
         defaultChild = resolvedDefault;
     }
@@ -382,7 +402,7 @@ function materializeGroup(group, inherited) {
         secrets: mergedInherited.secrets,
         requires: mergedInherited.requires,
         children: materializedChildren,
-        default: defaultChild,
+        default: defaultChild
     };
     Object.defineProperty(materialized, groupConfigSymbol, {
         value: {
@@ -394,8 +414,8 @@ function materializeGroup(group, inherited) {
             rename: cloneRenameMap(internal.rename),
             requires: cloneRequires(internal.requires),
             children: [...internal.children],
-            default: internal.default,
-        },
+            default: internal.default
+        }
     });
     return materialized;
 }
@@ -411,7 +431,7 @@ export function defineCommand(config) {
         scope: undefined,
         humanInLoop: undefined,
         secrets: {},
-        requires: undefined,
+        requires: undefined
     });
 }
 export function defineGroup(config) {
@@ -421,12 +441,12 @@ export function defineGroup(config) {
         scope: undefined,
         humanInLoop: undefined,
         secrets: {},
-        requires: undefined,
+        requires: undefined
     });
 }
 export function getCommandSourcePath(command) {
     return command[commandSourcePathSymbol];
 }
 export { S, toJsonSchema } from "toolcraft-schema";
-export { ApprovalDeclinedError, UserError };
+export { ApprovalDeclinedError, ToolcraftBugError, UserError };
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";

package/dist/json-schema-converter.d.ts

@@ -4,6 +4,7 @@ export interface JsonSchema {
     $defs?: Record<string, JsonSchema>;
     $ref?: string;
     additionalProperties?: boolean | JsonSchema;
+    allOf?: readonly JsonSchema[];
     anyOf?: readonly JsonSchema[];
     const?: unknown;
     default?: unknown;

package/dist/json-schema-converter.js

@@ -2,17 +2,17 @@ import { S } from "toolcraft-schema";
 export function convertJsonSchema(schema) {
     if (hasSelfReferencingRef(schema, schema)) {
         return applyMetadata(S.Json(), schema, {
-            nullable: schema.nullable === true,
+            nullable: schema.nullable === true
         });
     }
-    return convertSchema(schema, schema);
+    return convertSchema(schema, schema, []);
 }
-function convertSchema(schema, root) {
-    const resolvedSchema = resolveReferencedSchema(schema, root);
+function convertSchema(schema, root, path) {
+    const resolvedSchema = resolveReferencedSchema(schema, root, path);
     const normalizedSchema = normalizeNullability(resolvedSchema);
-    const composition = normalizedSchema.schema.oneOf ?? normalizedSchema.schema.anyOf;
+    const composition = getComposition(normalizedSchema.schema);
     if (Array.isArray(normalizedSchema.schema.type)) {
-        throw new Error(`Unsupported JSON Schema type array: ${JSON.stringify(normalizedSchema.schema.type)}.`);
+        throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" has an unsupported type "${formatJsonSchemaType(normalizedSchema.schema.type)}". Supported: string, number, integer, boolean, array, object.`);
     }
     if (resolvedSchema.const !== undefined) {
         return convertConstSchema(resolvedSchema, normalizedSchema.nullable);
@@ -21,11 +21,14 @@ function convertSchema(schema, root) {
         return convertEnumSchema(resolvedSchema, normalizedSchema.nullable);
     }
     if (composition !== undefined) {
-        return convertCompositionSchema(normalizedSchema.schema, root, normalizedSchema.nullable);
+        return convertCompositionSchema(normalizedSchema.schema, root, normalizedSchema.nullable, path);
     }
     if (isRecordSchema(normalizedSchema.schema)) {
-        return applyMetadata(S.Record(convertSchema(normalizedSchema.schema.additionalProperties, root)), normalizedSchema.schema, {
-            nullable: normalizedSchema.nullable,
+        return applyMetadata(S.Record(convertSchema(normalizedSchema.schema.additionalProperties, root, [
+            ...path,
+            "additionalProperties"
+        ])), normalizedSchema.schema, {
+            nullable: normalizedSchema.nullable
         });
     }
     switch (normalizedSchema.schema.type) {
@@ -34,40 +37,41 @@ function convertSchema(schema, root) {
                 ...createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getStringDefault(normalizedSchema.schema.default)),
                 ...(normalizedSchema.schema.pattern === undefined
                     ? {}
-                    : { pattern: normalizedSchema.schema.pattern }),
+                    : { pattern: normalizedSchema.schema.pattern })
             });
         case "number":
             return S.Number(createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getNumberDefault(normalizedSchema.schema.default)));
         case "integer":
             return S.Number({
                 ...createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getIntegerDefault(normalizedSchema.schema.default)),
-                jsonType: "integer",
+                jsonType: "integer"
             });
         case "boolean":
             return S.Boolean(createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getBooleanDefault(normalizedSchema.schema.default)));
         case "array":
             if (normalizedSchema.schema.items === undefined) {
-                throw new Error('JSON Schema arrays must define "items".');
+                throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" is an array but is missing the "items" field. Add "items": { ... } to declare the element type.`);
             }
-            return S.Array(convertSchema(normalizedSchema.schema.items, root), createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getArrayDefault(normalizedSchema.schema.default)));
+            return S.Array(convertSchema(normalizedSchema.schema.items, root, [...path, "items"]), createCommonOptions(normalizedSchema.schema, normalizedSchema.nullable, getArrayDefault(normalizedSchema.schema.default)));
         case "object":
             return convertObjectSchema(normalizedSchema.schema, root, {
                 nullable: normalizedSchema.nullable,
+                path
             });
         case "null":
             return applyMetadata(S.Json(), normalizedSchema.schema, {
                 default: getJsonDefault(normalizedSchema.schema.default) ?? null,
-                nullable: true,
+                nullable: true
             });
         case undefined:
             if (normalizedSchema.nullable) {
                 return applyMetadata(S.Json(), normalizedSchema.schema, {
-                    nullable: true,
+                    nullable: true
                 });
             }
-            throw new Error("Unsupported JSON Schema: missing type, enum, const, or composition.");
+            throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" must declare one of: "type", "enum", "const", "oneOf", "anyOf", or "allOf".`);
     }
-    throw new Error(`Unsupported JSON Schema type: ${JSON.stringify(normalizedSchema.schema.type)}.`);
+    throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" has an unsupported type "${formatJsonSchemaType(normalizedSchema.schema.type)}". Supported: string, number, integer, boolean, array, object.`);
 }
 function convertConstSchema(schema, nullable) {
     if (isPrimitiveEnumValue(schema.const)) {
@@ -76,13 +80,13 @@ function convertConstSchema(schema, nullable) {
             default: schema.const,
             ...(schema.type === "integer" && typeof schema.const === "number"
                 ? { jsonType: "integer" }
-                : {}),
+                : {})
         });
     }
     return applyMetadata(S.Json(), schema, {
         default: schema.const,
         nullable: nullable || schema.const === null,
-        description: appendDescription(schema.description, `Constant JSON value: ${JSON.stringify(schema.const)}.`),
+        description: appendDescription(schema.description, `Constant JSON value: ${JSON.stringify(schema.const)}.`)
     });
 }
 function convertEnumSchema(schema, nullable) {
@@ -94,64 +98,75 @@ function convertEnumSchema(schema, nullable) {
             ...createCommonOptions(schema, nullable || hasNull, getPrimitiveEnumDefault(schema.default, nonNullValues)),
             ...(schema.type === "integer" && nonNullValues.every((value) => Number.isInteger(value))
                 ? { jsonType: "integer" }
-                : {}),
+                : {})
         });
     }
     return applyMetadata(S.Json(), schema, {
         nullable: nullable || hasNull,
-        description: appendDescription(schema.description, `Allowed JSON values: ${values.map((value) => JSON.stringify(value)).join(", ")}.`),
+        description: appendDescription(schema.description, `Allowed JSON values: ${values.map((value) => JSON.stringify(value)).join(", ")}.`)
     });
 }
-function convertCompositionSchema(schema, root, nullable) {
-    const branches = [...(schema.oneOf ?? schema.anyOf ?? [])].map((branch) => resolveReferencedSchema(branch, root));
-    const discriminator = findDiscriminator(branches, root);
+function convertCompositionSchema(schema, root, nullable, path) {
+    const composition = getComposition(schema);
+    const branchSchemas = composition?.branches ?? [];
+    const keyword = composition?.keyword ?? "oneOf";
+    const branches = branchSchemas.map((branch, index) => resolveReferencedSchema(branch, root, [...path, keyword, String(index)]));
+    const discriminator = findDiscriminator(branches, root, path);
     if (discriminator !== undefined) {
-        const convertedBranches = Object.fromEntries(branches.map((branch) => [
+        const convertedBranches = Object.fromEntries(branches.map((branch, index) => [
             getDiscriminatorLiteral(branch, discriminator, root),
             convertObjectSchema(branch, root, {
                 omitProperty: discriminator,
-            }),
+                path: [...path, keyword, String(index)]
+            })
         ]));
         return applyMetadata(S.OneOf({
             discriminator,
-            branches: convertedBranches,
+            branches: convertedBranches
         }), schema, {
-            nullable,
+            nullable
         });
     }
-    return applyMetadata(S.Union(branches.map((branch) => convertObjectSchema(branch, root, {}))), schema, {
-        nullable,
+    return applyMetadata(S.Union(branches.map((branch, index) => convertObjectSchema(branch, root, {
+        path: [...path, keyword, String(index)]
+    }))), schema, {
+        nullable
     });
 }
 function convertObjectSchema(schema, root, options) {
-    const resolvedSchema = resolveReferencedSchema(schema, root);
+    const resolvedSchema = resolveReferencedSchema(schema, root, options.path);
     const normalizedSchema = normalizeNullability(resolvedSchema);
     const properties = normalizedSchema.schema.properties ?? {};
     const requiredKeys = new Set(normalizedSchema.schema.required ?? []);
     const shape = {};
-    if (normalizedSchema.schema.type !== "object" && normalizedSchema.schema.properties === undefined) {
-        throw new Error("Expected an object schema branch.");
+    if (normalizedSchema.schema.type !== "object" &&
+        normalizedSchema.schema.properties === undefined) {
+        throw new Error(`Expected "${formatJsonSchemaPath(options.path)}" to be an object schema (got "${describeObjectSchemaKind(normalizedSchema.schema)}").`);
     }
     for (const [key, propertySchema] of Object.entries(properties)) {
         if (key === options.omitProperty) {
             continue;
         }
-        const convertedProperty = convertSchema(propertySchema, root);
+        const convertedProperty = convertSchema(propertySchema, root, [
+            ...options.path,
+            "properties",
+            key
+        ]);
         shape[key] = requiredKeys.has(key) ? convertedProperty : S.Optional(convertedProperty);
     }
     return applyMetadata(S.Object(shape, {
         ...(typeof normalizedSchema.schema.additionalProperties === "boolean"
             ? { additionalProperties: normalizedSchema.schema.additionalProperties }
-            : {}),
+            : {})
     }), normalizedSchema.schema, {
-        nullable: options.nullable ?? normalizedSchema.nullable,
+        nullable: options.nullable ?? normalizedSchema.nullable
     });
 }
 function createCommonOptions(schema, nullable, defaultValue) {
     return {
         ...(schema.description === undefined ? {} : { description: schema.description }),
         ...(defaultValue === undefined ? {} : { default: defaultValue }),
-        ...(nullable ? { nullable: true } : {}),
+        ...(nullable ? { nullable: true } : {})
     };
 }
 function applyMetadata(schema, source, overrides) {
@@ -174,25 +189,53 @@ function normalizeNullability(schema) {
     if (!Array.isArray(schema.type)) {
         return {
             schema,
-            nullable: schema.nullable === true,
+            nullable: schema.nullable === true
         };
     }
     const nextTypes = schema.type.filter((value) => value !== "null");
     if (nextTypes.length === schema.type.length) {
         return {
             schema,
-            nullable: schema.nullable === true,
+            nullable: schema.nullable === true
         };
     }
     return {
         schema: {
             ...schema,
             type: nextTypes.length === 0 ? undefined : nextTypes.length === 1 ? nextTypes[0] : nextTypes,
-            nullable: undefined,
+            nullable: undefined
         },
-        nullable: true,
+        nullable: true
     };
 }
+function getComposition(schema) {
+    if (schema.oneOf !== undefined) {
+        return { keyword: "oneOf", branches: schema.oneOf };
+    }
+    if (schema.anyOf !== undefined) {
+        return { keyword: "anyOf", branches: schema.anyOf };
+    }
+    if (schema.allOf !== undefined) {
+        return { keyword: "allOf", branches: schema.allOf };
+    }
+    return undefined;
+}
+function formatJsonSchemaPath(path) {
+    if (path.length === 0) {
+        return "#";
+    }
+    return `#/${path.map(escapeJsonPointerSegment).join("/")}`;
+}
+function formatJsonSchemaType(type) {
+    return Array.isArray(type) ? JSON.stringify(type) : String(type);
+}
+function describeObjectSchemaKind(schema) {
+    const type = schema.type;
+    if (typeof type === "string") {
+        return type;
+    }
+    return type === undefined ? "unknown" : JSON.stringify(type);
+}
 function isRecordSchema(schema) {
     const propertyKeys = Object.keys(schema.properties ?? {});
     return (schema.type === "object" &&
@@ -200,10 +243,10 @@ function isRecordSchema(schema) {
         typeof schema.additionalProperties === "object" &&
         schema.additionalProperties !== null);
 }
-function findDiscriminator(branches, root) {
+function findDiscriminator(branches, root, path) {
     const [firstBranch] = branches;
     if (firstBranch === undefined) {
-        throw new Error("JSON Schema composition requires at least one branch.");
+        throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" uses oneOf/anyOf/allOf but has no branches.`);
     }
     const candidateKeys = Object.keys(firstBranch.properties ?? {});
     for (const candidate of candidateKeys) {
@@ -233,7 +276,7 @@ function getDiscriminatorLiteral(branch, key, root) {
     if (propertySchema === undefined) {
         return undefined;
     }
-    const resolvedProperty = resolveReferencedSchema(propertySchema, root);
+    const resolvedProperty = resolveReferencedSchema(propertySchema, root, []);
     if (typeof resolvedProperty.const === "string") {
         return resolvedProperty.const;
     }
@@ -244,17 +287,17 @@ function getDiscriminatorLiteral(branch, key, root) {
     }
     return undefined;
 }
-function resolveReferencedSchema(schema, root) {
+function resolveReferencedSchema(schema, root, path) {
     if (schema.$ref === undefined) {
         return schema;
     }
     const resolvedTarget = resolveLocalRef(root, schema.$ref);
     if (resolvedTarget === undefined) {
-        throw new Error(`Unsupported JSON Schema $ref: ${JSON.stringify(schema.$ref)}.`);
+        throw new Error(`JSON Schema "${formatJsonSchemaPath(path)}" uses "$ref": ${schema.$ref}. toolcraft only supports internal refs like "#/components/schemas/Foo".`);
     }
     const { $ref: ignoredRef, ...siblingKeywords } = schema;
     void ignoredRef;
-    const resolvedSchema = resolveReferencedSchema(resolvedTarget, root);
+    const resolvedSchema = resolveReferencedSchema(resolvedTarget, root, path);
     if (Object.keys(siblingKeywords).length === 0) {
         return resolvedSchema;
     }
@@ -265,13 +308,13 @@ function mergeJsonSchemas(base, overlay) {
         ? undefined
         : {
             ...(base.properties ?? {}),
-            ...(overlay.properties ?? {}),
+            ...(overlay.properties ?? {})
         };
     const mergedDefs = base.$defs === undefined && overlay.$defs === undefined
         ? undefined
         : {
             ...(base.$defs ?? {}),
-            ...(overlay.$defs ?? {}),
+            ...(overlay.$defs ?? {})
         };
     const mergedRequired = base.required === undefined && overlay.required === undefined
         ? undefined
@@ -281,7 +324,7 @@ function mergeJsonSchemas(base, overlay) {
         ...overlay,
         ...(mergedDefs === undefined ? {} : { $defs: mergedDefs }),
         ...(mergedProperties === undefined ? {} : { properties: mergedProperties }),
-        ...(mergedRequired === undefined ? {} : { required: mergedRequired }),
+        ...(mergedRequired === undefined ? {} : { required: mergedRequired })
     };
 }
 function hasSelfReferencingRef(schema, root, path = "#", activePaths = new Set()) {
@@ -293,11 +336,13 @@ function hasSelfReferencingRef(schema, root, path = "#", activePaths = new Set()
             return true;
         }
         const target = resolveLocalRef(root, localRefPath);
-        if (target !== undefined && hasSelfReferencingRef(target, root, localRefPath, nextActivePaths)) {
+        if (target !== undefined &&
+            hasSelfReferencingRef(target, root, localRefPath, nextActivePaths)) {
             return true;
         }
     }
-    if (schema.items !== undefined && hasSelfReferencingRef(schema.items, root, `${path}/items`, nextActivePaths)) {
+    if (schema.items !== undefined &&
+        hasSelfReferencingRef(schema.items, root, `${path}/items`, nextActivePaths)) {
         return true;
     }
     if (typeof schema.additionalProperties === "object" &&
@@ -325,6 +370,11 @@ function hasSelfReferencingRef(schema, root, path = "#", activePaths = new Set()
             return true;
         }
     }
+    for (const [index, childSchema] of (schema.allOf ?? []).entries()) {
+        if (hasSelfReferencingRef(childSchema, root, `${path}/allOf/${index}`, nextActivePaths)) {
+            return true;
+        }
+    }
     return false;
 }
 function getLocalRefPath(ref) {

package/dist/mcp-proxy.d.ts

@@ -5,6 +5,7 @@ export interface ResolveMcpProxyOptions {
     projectRoot?: string;
 }
 export declare function hasMcpProxyGroups(root: Group<any>): boolean;
+export declare function findProjectRoot(from?: string): string | undefined;
 export declare function resolveCachePath(name: string, projectRoot?: string): string;
 export declare function parseRefreshEnv(value: string | undefined): "all" | Set<string> | undefined;
 export declare function dialUpstream(name: string, config: McpServerConfig): Promise<McpClient>;

package/dist/mcp-proxy.js

@@ -327,22 +327,29 @@ function collectProxyGroups(root) {
 export function hasMcpProxyGroups(root) {
     return collectProxyGroups(root).length > 0;
 }
-export function resolveCachePath(name, projectRoot) {
-    if (projectRoot !== undefined) {
-        return path.join(projectRoot, ".toolcraft", "mcp", `${name}.json`);
-    }
+export function findProjectRoot(from = process.cwd()) {
     let current = process.cwd();
+    if (from !== current) {
+        current = path.resolve(from);
+    }
     while (true) {
         if (existsSync(path.join(current, "package.json"))) {
-            return path.join(current, ".toolcraft", "mcp", `${name}.json`);
+            return current;
         }
         const parent = path.dirname(current);
         if (parent === current) {
-            throw new Error(`Could not find package.json above "${process.cwd()}" while resolving MCP cache path.`);
+            return undefined;
         }
         current = parent;
     }
 }
+export function resolveCachePath(name, projectRoot) {
+    const resolvedProjectRoot = projectRoot ?? findProjectRoot();
+    if (resolvedProjectRoot === undefined) {
+        throw new Error(`Could not find package.json above "${process.cwd()}" while resolving MCP cache path.`);
+    }
+    return path.join(resolvedProjectRoot, ".toolcraft", "mcp", `${name}.json`);
+}
 export function parseRefreshEnv(value) {
     const trimmed = value?.trim();
     if (trimmed === undefined || trimmed.length === 0) {