toolcraft 0.0.6 → 0.0.8

package/README.md

@@ -441,19 +441,23 @@ If you have an existing MCP server you want to keep running, use the MCP proxy:
 - `casing?: "kebab" | "snake"` — generated CLI flag style.
 - `services?: TServices` — merged into every handler context.
 - `version?: string` — surfaced via `--version`.
+- `presets?: boolean` — enables `--preset <path>` for loading parameter defaults from JSON files.
 - `apiVersion?: string` — for `requires.apiVersion`.
 - `humanInLoop?: HumanInLoopRuntimeOptions`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 
 ### `createSDK(root, options)`
 
 - `casing?: "camel"` — generated SDK member style.
 - `services?` / `humanInLoop?` / `apiVersion?`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 
 ### `createMCPServer(root, options)` / `runMCP(root, options)`
 
 - `name: string`
 - `version: string`
 - `services?` / `humanInLoop?` / `apiVersion?`
+- `projectRoot?: string` — root used for MCP proxy cache files (`.toolcraft/mcp/*.json`).
 - `tools?: string[]` — allowlist of MCP tool names or group prefixes. Tool names are `__`-joined snake_case path segments (`root__bot__create`); a prefix like `root__bot` includes every descendant tool.
 - `casing?: "snake" | "camel"` — affects MCP **input-schema property names** only. Tool names always stay `__`-joined snake_case.
 

package/dist/cli.d.ts

@@ -5,10 +5,12 @@ export interface RunCLIOptions<TServices extends object = Record<string, unknown
     apiVersion?: string;
     casing?: Casing;
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
     rootDisplayName?: string;
     rootUsageName?: string;
     services?: TServices;
     version?: string;
+    presets?: boolean;
 }
 export declare function runCLI<TServices extends object = Record<string, unknown>>(roots: Group<TServices> | Group<TServices>[], options?: RunCLIOptions<TServices>): Promise<void>;
 export {};

package/dist/cli.js

@@ -126,7 +126,7 @@ function getRequiredBranchFingerprint(branch, casing) {
         .sort();
     return requiredKeys.join("+");
 }
-function collectFields(schema, casing, path = [], inheritedOptional = false, variantContext) {
+function collectFields(schema, casing, globalLongOptionFlags, path = [], inheritedOptional = false, variantContext) {
     const collected = {
         dynamicFields: [],
         fields: [],
@@ -138,7 +138,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
         const childSchema = unwrapOptional(rawChildSchema);
         const requiredWhenActive = rawChildSchema.kind !== "optional" && childSchema.default === undefined;
         if (childSchema.kind === "object") {
-            const nested = collectFields(childSchema, casing, nextPath, runtimeOptional, variantContext);
+            const nested = collectFields(childSchema, casing, globalLongOptionFlags, nextPath, runtimeOptional, variantContext);
             collected.dynamicFields.push(...nested.dynamicFields);
             collected.fields.push(...nested.fields);
             collected.variants.push(...nested.variants);
@@ -152,7 +152,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
                 path: [...nextPath, childSchema.discriminator],
                 displayPath: toDisplayPath([...nextPath, childSchema.discriminator]),
                 optionAttribute: toOptionAttribute([...nextPath, childSchema.discriminator], casing),
-                commanderOptionAttribute: toCommanderOptionAttribute([...nextPath, childSchema.discriminator], casing),
+                commanderOptionAttribute: toCommanderOptionAttribute([...nextPath, childSchema.discriminator], casing, globalLongOptionFlags),
                 optionFlag: toOptionFlag([...nextPath, childSchema.discriminator], casing),
                 shortFlag: undefined,
                 schema: createSyntheticEnumSchema(branchIds),
@@ -165,7 +165,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
             collected.fields.push(controlField);
             const branches = [];
             for (const [branchId, branchSchema] of Object.entries(childSchema.branches)) {
-                const branch = collectFields(branchSchema, casing, nextPath, true, {
+                const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
                     id: variantId,
                     branchId,
                 });
@@ -203,7 +203,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
                 path: controlPath,
                 displayPath: controlDisplayPath,
                 optionAttribute: toOptionAttribute(controlPath, casing),
-                commanderOptionAttribute: toCommanderOptionAttribute(controlPath, casing),
+                commanderOptionAttribute: toCommanderOptionAttribute(controlPath, casing, globalLongOptionFlags),
                 optionFlag: toOptionFlag(controlPath, casing),
                 shortFlag: undefined,
                 schema: createSyntheticEnumSchema(branchIds),
@@ -218,7 +218,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
             const branches = [];
             childSchema.branches.forEach((branchSchema, index) => {
                 const branchId = branchIds[index] ?? "";
-                const branch = collectFields(branchSchema, casing, nextPath, true, {
+                const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
                     id: variantId,
                     branchId,
                 });
@@ -289,7 +289,7 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
             path: nextPath,
             displayPath: toDisplayPath(nextPath),
             optionAttribute: toOptionAttribute(nextPath, casing),
-            commanderOptionAttribute: toCommanderOptionAttribute(nextPath, casing),
+            commanderOptionAttribute: toCommanderOptionAttribute(nextPath, casing, globalLongOptionFlags),
             optionFlag: toOptionFlag(nextPath, casing),
             shortFlag: childSchema.short,
             schema: childSchema,
@@ -304,10 +304,10 @@ function collectFields(schema, casing, path = [], inheritedOptional = false, var
     }
     return collected;
 }
-function toCommanderOptionAttribute(path, casing) {
+function toCommanderOptionAttribute(path, casing, globalLongOptionFlags) {
     const optionAttribute = toOptionAttribute(path, casing);
     const optionFlag = toOptionFlag(path, casing);
-    if (!GLOBAL_LONG_OPTION_FLAGS.has(optionFlag)) {
+    if (!globalLongOptionFlags.has(optionFlag)) {
         return optionAttribute;
     }
     return `param_${optionAttribute}`;
@@ -337,8 +337,8 @@ function assignPositionals(fields, positional) {
     });
     return fields;
 }
-function formatOptionFlags(field) {
-    const collidesWithGlobalFlag = GLOBAL_LONG_OPTION_FLAGS.has(field.optionFlag);
+function formatOptionFlags(field, globalLongOptionFlags) {
+    const collidesWithGlobalFlag = globalLongOptionFlags.has(field.optionFlag);
     if (collidesWithGlobalFlag) {
         if (field.shortFlag === undefined) {
             throw new UserError(`Parameter "${field.displayPath}" uses reserved CLI flag "${field.optionFlag}". Add a short flag or rename the parameter.`);
@@ -449,9 +449,9 @@ function parseArrayValue(value, schema, label) {
     }
     return splitArrayInput(value).map((item) => parseScalarValue(item, itemSchema, label));
 }
-function createOption(field) {
-    const flags = formatOptionFlags(field);
-    const collidesWithGlobalFlag = GLOBAL_LONG_OPTION_FLAGS.has(field.optionFlag);
+function createOption(field, globalLongOptionFlags) {
+    const flags = formatOptionFlags(field, globalLongOptionFlags);
+    const collidesWithGlobalFlag = globalLongOptionFlags.has(field.optionFlag);
     const commanderValue = (value) => (value === null ? NULL_OPTION_VALUE : value);
     if (field.schema.kind === "boolean") {
         if (collidesWithGlobalFlag) {
@@ -489,7 +489,10 @@ function createOption(field) {
     option.argParser((value) => commanderValue(parseScalarValue(value, field.schema, field.displayPath)));
     return [option];
 }
-const GLOBAL_LONG_OPTION_FLAGS = new Set(["--preset", "--yes", "--output", "--verbose"]);
+const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--verbose"];
+function getGlobalLongOptionFlags(presetsEnabled) {
+    return new Set(presetsEnabled ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS] : ALWAYS_GLOBAL_LONG_OPTION_FLAGS);
+}
 function createCommanderOption(flags, description, field) {
     const option = new Option(flags, description);
     if (field.commanderOptionAttribute !== field.optionAttribute) {
@@ -580,14 +583,14 @@ function describeSchemaType(schema) {
             throw new UserError("Unsupported CLI schema kind.");
     }
 }
-function formatHelpFieldFlags(field) {
+function formatHelpFieldFlags(field, globalLongOptionFlags) {
     if (field.positionalIndex !== undefined) {
         return formatPositionalToken(field);
     }
     if (field.schema.kind === "boolean") {
-        return `${formatOptionFlags(field)} [value]`;
+        return `${formatOptionFlags(field, globalLongOptionFlags)} [value]`;
     }
-    return `${formatOptionFlags(field)} <${describeSchemaType(field.schema)}>`;
+    return `${formatOptionFlags(field, globalLongOptionFlags)} <${describeSchemaType(field.schema)}>`;
 }
 function appendHelpMetadata(description, metadata) {
     if (metadata.length === 0) {
@@ -711,31 +714,40 @@ function formatSecretDescription(secret) {
     }
     return secret.optional === true ? "Optional secret" : "Required secret";
 }
-function formatCommandRows(group, scope) {
-    return getVisibleChildren(group, scope).map((child) => ({
-        name: child.aliases.length === 0 ? child.name : `${child.name} (${child.aliases.join(", ")})`,
-        description: child.description ?? "",
-    }));
+function formatCommandRowName(node, depth) {
+    const name = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
+    return `${"  ".repeat(depth)}${name}`;
+}
+function formatCommandRows(group, scope, depth = 0) {
+    return getVisibleChildren(group, scope).flatMap((child) => {
+        const row = {
+            name: formatCommandRowName(child, depth),
+            description: child.description ?? "",
+        };
+        if (child.kind === "command") {
+            return [row];
+        }
+        return [row, ...formatCommandRows(child, scope, depth + 1)];
+    });
 }
-function formatGlobalOptionRows(showVersion) {
-    const rows = [
-        {
+function formatGlobalOptionRows(showVersion, presetsEnabled) {
+    const rows = [];
+    if (presetsEnabled) {
+        rows.push({
             flags: "--preset <path>",
             description: "Load parameter defaults from a JSON file",
-        },
-        {
-            flags: "--yes",
-            description: "Accept defaults, skip prompts",
-        },
-        {
-            flags: "--output <format>",
-            description: "Output format (rich, md, json)",
-        },
-        {
-            flags: "-h, --help",
-            description: "Show help",
-        },
-    ];
+        });
+    }
+    rows.push({
+        flags: "--yes",
+        description: "Accept defaults, skip prompts",
+    }, {
+        flags: "--output <format>",
+        description: "Output format (rich, md, json)",
+    }, {
+        flags: "-h, --help",
+        description: "Show help",
+    });
     if (showVersion) {
         rows.push({
             flags: "--version",
@@ -754,13 +766,13 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const subPath = breadcrumb.slice(1).join(" ");
     return subPath ? `${rootUsageName} ${subPath} ${suffix}` : `${rootUsageName} ${suffix}`;
 }
-function renderGroupHelp(group, breadcrumb, scope, showVersion, rootUsageName) {
+function renderGroupHelp(group, breadcrumb, scope, showVersion, presetsEnabled, rootUsageName) {
     const sections = [];
     const commandRows = formatCommandRows(group, scope);
     if (commandRows.length > 0) {
         sections.push(`${text.section("Commands:")}\n${formatCommandList(commandRows)}`);
     }
-    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(showVersion))}`);
+    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(showVersion, presetsEnabled))}`);
     return renderHelpDocument({
         breadcrumb,
         usageLine: buildUsageLine(breadcrumb, rootUsageName, "[options] [command]"),
@@ -769,18 +781,19 @@ function renderGroupHelp(group, breadcrumb, scope, showVersion, rootUsageName) {
         sections,
     });
 }
-function renderLeafHelp(command, breadcrumb, casing, rootUsageName) {
+function renderLeafHelp(command, breadcrumb, casing, presetsEnabled, rootUsageName) {
     const sections = [];
-    const collected = collectFields(command.params, casing);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
     const optionRows = fields.map((field) => ({
-        flags: formatHelpFieldFlags(field),
+        flags: formatHelpFieldFlags(field, globalLongOptionFlags),
         description: formatHelpFieldDescription(field),
     })).concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
     if (optionRows.length > 0) {
         sections.push(`${text.section("Options:")}\n${formatOptionList(optionRows)}`);
     }
-    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(false))}`);
+    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(false, presetsEnabled))}`);
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
         sections.push(`${text.section("Secrets (via environment):")}\n${formatOptionList(secretRows)}`);
@@ -820,26 +833,26 @@ async function renderGeneratedHelp(root, argv, options) {
     const casing = options.casing ?? "kebab";
     await withOutputFormat(output, async () => {
         const rendered = target.node.kind === "group"
-            ? renderGroupHelp(target.node, target.breadcrumb, "cli", options.version !== undefined, options.rootUsageName)
-            : renderLeafHelp(target.node, target.breadcrumb, casing, options.rootUsageName);
+            ? renderGroupHelp(target.node, target.breadcrumb, "cli", options.version !== undefined, options.presets === true, options.rootUsageName)
+            : renderLeafHelp(target.node, target.breadcrumb, casing, options.presets === true, options.rootUsageName);
         process.stdout.write(rendered);
     });
 }
-function createNodeCommand(node, casing, execute, pathSegments = []) {
+function createNodeCommand(node, casing, globalLongOptionFlags, execute, presetsEnabled, pathSegments = []) {
     const nextPathSegments = [...pathSegments, node.name];
     if (node.kind === "command") {
         if (!node.scope.includes("cli")) {
             return null;
         }
         const command = new CommanderCommand(node.name);
-        const collected = collectFields(node.params, casing);
+        const collected = collectFields(node.params, casing, globalLongOptionFlags);
         const fields = assignPositionals(collected.fields, node.positional);
         if (node.description !== undefined) {
             command.description(node.description);
         }
         node.aliases.forEach((alias) => command.alias(alias));
         command.addHelpCommand(false);
-        addGlobalOptions(command);
+        addGlobalOptions(command, presetsEnabled);
         command.allowExcessArguments(true);
         if (collected.dynamicFields.length > 0) {
             command.allowUnknownOption(true);
@@ -849,7 +862,7 @@ function createNodeCommand(node, casing, execute, pathSegments = []) {
                 command.argument(formatPositionalToken(field));
                 continue;
             }
-            for (const option of createOption(field)) {
+            for (const option of createOption(field, globalLongOptionFlags)) {
                 command.addOption(option);
             }
         }
@@ -863,6 +876,7 @@ function createNodeCommand(node, casing, execute, pathSegments = []) {
                 dynamicFields: collected.dynamicFields,
                 fields,
                 positionalValues,
+                presetsEnabled,
                 rawArgv: actionCommand.args,
                 actionCommand,
                 variants: collected.variants,
@@ -874,7 +888,7 @@ function createNodeCommand(node, casing, execute, pathSegments = []) {
         return null;
     }
     const visibleChildren = node.children
-        .map((child) => createNodeCommand(child, casing, execute, nextPathSegments))
+        .map((child) => createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, nextPathSegments))
         .filter((child) => child !== null);
     const group = new CommanderCommand(node.name);
     if (node.description !== undefined) {
@@ -882,7 +896,7 @@ function createNodeCommand(node, casing, execute, pathSegments = []) {
     }
     node.aliases.forEach((alias) => group.alias(alias));
     group.addHelpCommand(false);
-    addGlobalOptions(group);
+    addGlobalOptions(group, presetsEnabled);
     for (const child of visibleChildren) {
         const isDefaultChild = node.default !== undefined &&
             node.default.scope.includes("cli") &&
@@ -891,9 +905,11 @@ function createNodeCommand(node, casing, execute, pathSegments = []) {
     }
     return group;
 }
-function addGlobalOptions(command) {
+function addGlobalOptions(command, presetsEnabled) {
+    if (presetsEnabled) {
+        command.option("--preset <path>", "Load parameter defaults from a JSON file.");
+    }
     command
-        .option("--preset <path>", "Load parameter defaults from a JSON file.")
         .option("--yes", "Accept defaults and skip prompts.")
         .option("--output <format>", "Output format.", (value) => {
         if (value === "rich" || value === "md" || value === "json") {
@@ -1927,7 +1943,7 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
     };
     await withOutputFormat(output, async () => {
         await assertCommandRequirements(state.command, preflightContext, runtime.requirementOptions);
-        const params = await resolveParams(state.fields, state.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, resolvedFlags.preset, shouldPrompt);
+        const params = await resolveParams(state.fields, state.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, state.presetsEnabled ? resolvedFlags.preset : undefined, shouldPrompt);
         const context = {
             ...preflightContext,
             params,
@@ -1987,7 +2003,7 @@ function handleRunError(error, verbose) {
 }
 export async function runCLI(roots, options = {}) {
     const root = mergeApprovalsGroup(normalizeRoots(roots, process.argv));
-    await resolveMcpProxies(root);
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
     const runtimeOptions = options.humanInLoop ?? {};
@@ -2010,7 +2026,9 @@ export async function runCLI(roots, options = {}) {
     program.exitOverride();
     program.showHelpAfterError();
     program.addHelpCommand(false);
-    addGlobalOptions(program);
+    const presetsEnabled = options.presets === true;
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    addGlobalOptions(program, presetsEnabled);
     if (version !== undefined) {
         program.version(version, "--version");
     }
@@ -2020,7 +2038,7 @@ export async function runCLI(roots, options = {}) {
         await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeOptions);
     };
     for (const child of root.children) {
-        const command = createNodeCommand(child, casing, execute);
+        const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled);
         if (command === null) {
             continue;
         }

package/dist/mcp-proxy.d.ts

@@ -1,8 +1,11 @@
 import type { McpServerConfig } from "@poe-code/agent-mcp-config";
 import { McpClient } from "tiny-mcp-client";
 import type { Group } from "./index.js";
+export interface ResolveMcpProxyOptions {
+    projectRoot?: string;
+}
 export declare function hasMcpProxyGroups(root: Group<any>): boolean;
 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>;
-export declare function resolveMcpProxies(root: Group<any>): Promise<void>;
+export declare function resolveMcpProxies(root: Group<any>, options?: ResolveMcpProxyOptions): Promise<void>;

package/dist/mcp-proxy.js

@@ -268,7 +268,7 @@ function isRefreshRequested(name, refresh) {
     }
     return refresh?.has(name) === true;
 }
-async function resolveSingleProxy(group) {
+async function resolveSingleProxy(group, options) {
     const internal = getInternalGroupConfig(group);
     const config = internal.mcp;
     if (config === undefined) {
@@ -276,7 +276,7 @@ async function resolveSingleProxy(group) {
     }
     const name = group.name;
     try {
-        const cachePath = resolveCachePath(name);
+        const cachePath = resolveCachePath(name, options.projectRoot);
         const refresh = parseRefreshEnv(process.env.TOOLCRAFT_MCP_REFRESH);
         let cache;
         if (isRefreshRequested(name, refresh)) {
@@ -377,7 +377,7 @@ export async function dialUpstream(name, config) {
     await client.connect(transport);
     return client;
 }
-export async function resolveMcpProxies(root) {
+export async function resolveMcpProxies(root, options = {}) {
     const groups = collectProxyGroups(root);
-    await Promise.all(groups.map((group) => resolveSingleProxy(group)));
+    await Promise.all(groups.map((group) => resolveSingleProxy(group, options)));
 }

package/dist/mcp.d.ts

@@ -9,6 +9,7 @@ export interface RunMCPOptions<TServices extends object = Record<string, unknown
     name: string;
     version?: string;
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
     /**
      * Optional allowlist of MCP tool names or group prefixes.
      *

package/dist/mcp.js

@@ -419,7 +419,7 @@ function createDeferredMCPServer(root, options) {
     let serverPromise;
     const resolveServer = () => {
         serverPromise ??= (async () => {
-            await resolveMcpProxies(root);
+            await resolveMcpProxies(root, { projectRoot: options.projectRoot });
             return createResolvedMCPServer(root, options);
         })();
         return serverPromise;
@@ -449,7 +449,7 @@ export function createMCPServer(roots, options) {
 }
 export async function runMCP(roots, options) {
     const root = mergeApprovalsGroup(normalizeRoots(roots));
-    await resolveMcpProxies(root);
+    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const server = createResolvedMCPServer(root, options);
     await server.listen();
 }

package/dist/sdk.d.ts

@@ -63,6 +63,7 @@ export interface CreateSDKOptions<TServices extends object = Record<string, unkn
     services?: TServices;
     casing?: "camel";
     humanInLoop?: HumanInLoopRuntimeOptions;
+    projectRoot?: string;
 }
 export declare function createSDK<TRootInfo, TServices extends object = Record<string, unknown>>(root: Group<any> & {
     readonly __agentKitGroupTypeInfo: TRootInfo;

package/dist/sdk.js

@@ -234,7 +234,7 @@ function createDeferredSDK(root, options) {
     let sdkPromise;
     const resolveSDK = () => {
         sdkPromise ??= (async () => {
-            await resolveMcpProxies(root);
+            await resolveMcpProxies(root, { projectRoot: options.projectRoot });
             return createResolvedSDK(root, options);
         })();
         return sdkPromise;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,7 @@
     "commander": "^14.0.3",
     "console-table-printer": "^2.15.0",
     "tiny-stdio-mcp-server": "^0.1.0",
-    "toolcraft-schema": "^0.0.6"
+    "toolcraft-schema": "^0.0.8"
   },
   "files": [
     "dist"