toolcraft 0.0.39 → 0.0.41

package/README.md

@@ -61,6 +61,9 @@ export const greet = defineCommand({
     name: S.String({ description: "Who to greet" }),
     loud: S.Optional(S.Boolean({ default: false }))
   }),
+  result: S.Object({
+    message: S.String()
+  }),
   handler: async ({ params }) => {
     const message = `Hello, ${params.name}`;
     return { message: params.loud ? message.toUpperCase() : message };
@@ -180,6 +183,10 @@ The same `root` flows into all three. No duplication.
 
 **CLI help**: group help lists visible child commands with their parameter tokens inline. Required options appear as `--name <type>`, optional options and defaults appear in brackets like `[--limit <number>]`, and positional parameters render as positional tokens like `<name>` or `[name]` depending on whether they are required. Command-specific `--help` still shows the detailed parameter table.
 
+**Examples**: commands may declare `examples: Array<{ title, params }>` alongside their params.
+CLI help renders an `Examples` section for the command, and MCP tool descriptions include the
+same examples so agents see concrete argument shapes.
+
 ## Secrets
 
 Declare env-backed secrets on a command or group. Toolcraft reads `process.env` at command-run time and passes the values to the handler:
@@ -250,11 +257,16 @@ Services are merged into the handler context alongside the built-ins (`fetch`, `
 
 ## Output rendering
 
-Handlers return raw values. Add per-format renderers when you want richer CLI output:
+Handlers return raw values. Add `result:` when a command returns structured data and may be exposed over MCP; Toolcraft turns that schema into MCP `outputSchema`, validates the returned object, returns it as `structuredContent`, and keeps a JSON text backstop for older MCP clients.
+
+Add per-format renderers when you want richer CLI output:
 
 ```ts
 defineCommand({
   // ...
+  result: S.Object({
+    rows: S.Array(S.Object({ id: S.Number() }))
+  }),
   handler: async () => ({ rows: [{ id: 1 }, { id: 2 }] }),
   render: {
     rich: (result, { renderTable }) =>
@@ -265,7 +277,27 @@ defineCommand({
 });
 ```
 
-CLI picks `rich` by default, `--json` switches to `json`. SDK and MCP always return the raw handler value.
+## HTTP errors
+
+Toolcraft exports a fixed HTTP error hierarchy for transports and generated API clients:
+
+- `HttpError`
+- `ClientError`
+- `BadRequestError`
+- `AuthenticationError`
+- `PermissionDeniedError`
+- `NotFoundError`
+- `ConflictError`
+- `UnprocessableEntityError`
+- `RateLimitError`
+- `ServerError`
+- `InternalServerError`
+- `ServiceUnavailableError`
+
+Each error carries `status`, optional `code`, optional `requestId`, and serializable `request` and
+`response` context.
+
+CLI picks `rich` by default, `--json` switches to `json`. SDK calls return the raw handler value. MCP calls with `result:` return the handler value as `structuredContent` using the configured MCP casing; MCP calls without `result:` keep content-block behavior.
 
 ## MCP proxy: adopt an existing MCP server
 
@@ -428,6 +460,7 @@ If you have an existing MCP server you want to keep running, use the MCP proxy:
 - `aliases?: string[]`
 - `positional?: string[]` — parameter names mapped from CLI argv order.
 - `params: S.Object(...)` — input schema from `toolcraft-schema`.
+- `result?: S.Object(...)` — structured result schema for MCP `outputSchema`; must be a root object.
 - `secrets?: Record<string, { env: string; description?: string; optional?: boolean }>`
 - `scope?: Array<"cli" | "mcp" | "sdk">` — defaults to `["cli", "sdk"]`.
 - `confirm?: boolean` — deprecated CLI-only TTY confirmation; use `humanInLoop` instead. Cannot be combined with `humanInLoop`.
@@ -436,6 +469,10 @@ If you have an existing MCP server you want to keep running, use the MCP proxy:
 - `handler: (ctx) => Promise<unknown>`
 - `render?: { rich?, markdown?, json? }` — per-format output renderers.
 
+Parameter schemas may set `short: "x"` for a short CLI flag and `cliAliases: ["alias"]` for
+additional long CLI flags. For example, `rawResponse` normally maps to `--raw-response`; adding
+`cliAliases: ["raw"]` also accepts `--raw` while the SDK parameter remains `rawResponse`.
+
 ### `defineGroup(config)`
 
 - `name: string`
@@ -473,7 +510,7 @@ If you have an existing MCP server you want to keep running, use the MCP proxy:
 - `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.
 - `omitRootToolNamePrefix?: boolean` — defaults to `false`. Set to `true` to omit the root group name from single-root MCP tool names (`bot__create`).
-- `casing?: "snake" | "camel"` — affects MCP **input-schema property names** only. Tool names always stay `__`-joined snake_case.
+- `casing?: "snake" | "camel"` — affects MCP input-schema property names, output-schema property names, and structured result keys. Tool names always stay `__`-joined snake_case.
 
 ### `HumanInLoopRuntimeOptions`
 
@@ -500,7 +537,7 @@ type HumanInLoopRuntimeOptions = {
 
 - `defineCommand`, `defineGroup`
 - `S`, `toJsonSchema`, type helpers — re-exported from `toolcraft-schema`
-- `UserError`, `ApprovalDeclinedError`
+- `UserError`, `ApprovalDeclinedError`, `HttpError` and the HTTP error subclasses.
 - Type exports: `Command`, `Group`, `Scope`, `HandlerContext`, `HumanInLoopConfig`, `HumanInLoopPending`, `HumanInLoopRuntimeOptions`, schema types from `toolcraft-schema`.
 
 Subpath imports:

package/dist/cli.js

@@ -175,6 +175,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 optionAttribute: toOptionAttribute([...nextPath, childSchema.discriminator], casing),
                 commanderOptionAttribute: toCommanderOptionAttribute([...nextPath, childSchema.discriminator], casing, globalLongOptionFlags),
                 optionFlag: toOptionFlag([...nextPath, childSchema.discriminator], casing),
+                longAliases: [],
                 shortFlag: undefined,
                 schema: createSyntheticEnumSchema(branchIds),
                 description: childSchema.description,
@@ -226,6 +227,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 optionAttribute: toOptionAttribute(controlPath, casing),
                 commanderOptionAttribute: toCommanderOptionAttribute(controlPath, casing, globalLongOptionFlags),
                 optionFlag: toOptionFlag(controlPath, casing),
+                longAliases: [],
                 shortFlag: undefined,
                 schema: createSyntheticEnumSchema(branchIds),
                 description: childSchema.description,
@@ -312,6 +314,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
             optionAttribute: toOptionAttribute(nextPath, casing),
             commanderOptionAttribute: toCommanderOptionAttribute(nextPath, casing, globalLongOptionFlags),
             optionFlag: toOptionFlag(nextPath, casing),
+            longAliases: [...(childSchema.cliAliases ?? [])].map((alias) => alias.startsWith("--") ? alias : `--${alias}`),
             shortFlag: childSchema.short,
             schema: childSchema,
             description: childSchema.description,
@@ -368,9 +371,9 @@ function formatOptionFlags(field, globalLongOptionFlags) {
         return `-${field.shortFlag}`;
     }
     if (field.shortFlag === undefined) {
-        return field.optionFlag;
+        return [field.optionFlag, ...field.longAliases].join(", ");
     }
-    return `-${field.shortFlag}, ${field.optionFlag}`;
+    return [`-${field.shortFlag}`, field.optionFlag, ...field.longAliases].join(", ");
 }
 function formatPositionalToken(field) {
     const optionalPositional = field.optional || field.hasDefault;
@@ -639,22 +642,30 @@ function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
     }
     return new Set(flags);
 }
-function validateUniqueOptionFlags(fields) {
+function validateUniqueOptionFlags(fields, globalLongOptionFlags) {
     const fieldsByFlag = new Map();
     for (const field of fields) {
         if (field.positionalIndex !== undefined) {
             continue;
         }
-        const existing = fieldsByFlag.get(field.optionFlag);
-        if (existing !== undefined) {
-            throw new UserError(`Parameters "${existing.displayPath}" and "${field.displayPath}" use conflicting CLI flag "${field.optionFlag}".`);
+        for (const flag of [field.optionFlag, ...field.longAliases]) {
+            if (globalLongOptionFlags.has(flag)) {
+                if (flag === field.optionFlag && field.shortFlag !== undefined) {
+                    continue;
+                }
+                throw new UserError(`Parameter "${field.displayPath}" uses reserved CLI flag "${flag}". Add a short flag or rename the parameter.`);
+            }
+            const existing = fieldsByFlag.get(flag);
+            if (existing !== undefined) {
+                throw new UserError(`Parameters "${existing.displayPath}" and "${field.displayPath}" use conflicting CLI flag "${flag}".`);
+            }
+            fieldsByFlag.set(flag, field);
         }
-        fieldsByFlag.set(field.optionFlag, field);
     }
 }
 function createCommanderOption(flags, description, field) {
     const option = new Option(flags, description);
-    if (field.commanderOptionAttribute !== field.optionAttribute) {
+    if (field.commanderOptionAttribute !== field.optionAttribute || field.longAliases.length > 0) {
         option.attributeName = () => field.commanderOptionAttribute;
     }
     return option;
@@ -958,6 +969,23 @@ function formatSecretDescription(secret) {
     }
     return secret.optional === true ? "Optional secret" : "Required secret";
 }
+function formatExampleValue(value) {
+    if (typeof value === "string" && value.length > 0 && !value.includes(" ")) {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function formatExampleCommand(breadcrumb, rootUsageName, params) {
+    const commandPath = buildUsageLine(breadcrumb, rootUsageName, "");
+    const flags = Object.entries(params).map(([key, value]) => {
+        const flag = `--${key}`;
+        return typeof value === "boolean" ? (value ? flag : `--no-${key}`) : `${flag} ${formatExampleValue(value)}`;
+    });
+    return [commandPath, ...flags].filter((token) => token.length > 0).join(" ");
+}
+function formatExampleRows(examples, breadcrumb, rootUsageName) {
+    return examples.map((example) => `${example.title}\n  ${formatExampleCommand(breadcrumb, rootUsageName, example.params)}`);
+}
 function wrapOptionalCommandParameterToken(token, optional) {
     return optional ? `[${token}]` : token;
 }
@@ -1098,6 +1126,9 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     if (secretRows.length > 0) {
         sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
     }
+    if (command.examples.length > 0) {
+        sections.push(`${text.sectionHeader("Examples")}\n${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`);
+    }
     const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
     const usageSuffix = positionalFields.length > 0
         ? `[OPTIONS] ${positionalFields.map(formatPositionalToken).join(" ")}`
@@ -1162,7 +1193,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
         const command = new CommanderCommand(node.name);
         const collected = collectFields(node.params, casing, globalLongOptionFlags);
         const fields = assignPositionals(collected.fields, node.positional);
-        validateUniqueOptionFlags(fields);
+        validateUniqueOptionFlags(fields, globalLongOptionFlags);
         if (node.description !== undefined) {
             command.description(node.description);
         }

package/dist/http-errors.d.ts

@@ -0,0 +1,57 @@
+export interface HttpErrorRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+export interface HttpErrorResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: unknown;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly request: HttpErrorRequest;
+    readonly response: HttpErrorResponse;
+    get body(): unknown;
+    constructor(args: {
+        request: HttpErrorRequest;
+        response: HttpErrorResponse;
+        code?: string;
+        requestId?: string;
+        message?: string;
+    });
+}
+export declare class ClientError extends HttpError {
+}
+export declare class BadRequestError extends ClientError {
+}
+export declare class AuthenticationError extends ClientError {
+}
+export declare class PermissionDeniedError extends ClientError {
+}
+export declare class NotFoundError extends ClientError {
+}
+export declare class ConflictError extends ClientError {
+}
+export declare class UnprocessableEntityError extends ClientError {
+}
+export declare class RateLimitError extends ClientError {
+}
+export declare class ServerError extends HttpError {
+}
+export declare class InternalServerError extends ServerError {
+}
+export declare class ServiceUnavailableError extends ServerError {
+}
+export declare function createHttpError(args: {
+    request: HttpErrorRequest;
+    response: HttpErrorResponse;
+    code?: string;
+    requestId?: string;
+    message?: string;
+}): HttpError;

package/dist/http-errors.js

@@ -0,0 +1,72 @@
+export class HttpError extends Error {
+    status;
+    statusText;
+    code;
+    requestId;
+    request;
+    response;
+    get body() {
+        return this.response.body;
+    }
+    constructor(args) {
+        super(args.message ??
+            `${args.request.method} ${args.request.url} → ${args.response.status} ${args.response.statusText}`);
+        this.name = new.target.name;
+        this.status = args.response.status;
+        this.statusText = args.response.statusText;
+        this.code = args.code;
+        this.requestId = args.requestId;
+        this.request = args.request;
+        this.response = args.response;
+    }
+}
+export class ClientError extends HttpError {
+}
+export class BadRequestError extends ClientError {
+}
+export class AuthenticationError extends ClientError {
+}
+export class PermissionDeniedError extends ClientError {
+}
+export class NotFoundError extends ClientError {
+}
+export class ConflictError extends ClientError {
+}
+export class UnprocessableEntityError extends ClientError {
+}
+export class RateLimitError extends ClientError {
+}
+export class ServerError extends HttpError {
+}
+export class InternalServerError extends ServerError {
+}
+export class ServiceUnavailableError extends ServerError {
+}
+export function createHttpError(args) {
+    const ErrorClass = getHttpErrorClass(args.response.status);
+    return new ErrorClass(args);
+}
+function getHttpErrorClass(status) {
+    switch (status) {
+        case 400:
+            return BadRequestError;
+        case 401:
+            return AuthenticationError;
+        case 403:
+            return PermissionDeniedError;
+        case 404:
+            return NotFoundError;
+        case 409:
+            return ConflictError;
+        case 422:
+            return UnprocessableEntityError;
+        case 429:
+            return RateLimitError;
+        case 500:
+            return InternalServerError;
+        case 503:
+            return ServiceUnavailableError;
+        default:
+            return status >= 400 && status < 500 ? ClientError : status >= 500 ? ServerError : HttpError;
+    }
+}

package/dist/index.d.ts

@@ -58,6 +58,10 @@ export interface CheckResult {
     ok: boolean;
     message?: string;
 }
+export interface CommandExample {
+    title: string;
+    params: Record<string, unknown>;
+}
 export type GroupCheckContext<TServices extends object = EmptyServices> = TServices & {
     params?: unknown;
     secrets?: Record<string, string | undefined>;
@@ -95,9 +99,11 @@ export type HandlerContext<TParamsSchema extends ObjectSchema<any> = AnyObjectSc
 export interface CommandConfig<TServices extends object, TParamsSchema extends ObjectSchema<any>, TSecrets extends SecretDeclarations | undefined, TResult> {
     name: string;
     description?: string;
+    examples?: CommandExample[];
     aliases?: string[];
     positional?: string[];
     params: TParamsSchema;
+    result?: ObjectSchema<any>;
     secrets?: TSecrets;
     scope?: Scope[];
     confirm?: boolean;
@@ -110,9 +116,11 @@ export interface Command<TServices extends object = EmptyServices, TParamsSchema
     kind: "command";
     name: string;
     description?: string;
+    examples: CommandExample[];
     aliases: string[];
     positional: string[];
     params: TParamsSchema;
+    result?: ObjectSchema<any>;
     secrets: SecretDeclarations;
     scope: Scope[];
     confirm: boolean;
@@ -187,6 +195,8 @@ export declare function defineGroup<TServices extends object = EmptyServices, TN
 }): Group<TServices> & TypedGroupMetadata<TServices, TName, TChildren, TOwnScope, ResolveOwnHumanInLoopMode<TOwnHumanInLoop>>;
 export declare function getCommandSourcePath(command: Command<any, any, any, any>): string | undefined;
 export { S, toJsonSchema } from "toolcraft-schema";
+export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
+export type { HttpErrorRequest, HttpErrorResponse } from "./http-errors.js";
 export { ApprovalDeclinedError, ToolcraftBugError, UserError };
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";
 export type { PackageMetadata } from "./package-metadata.js";

package/dist/index.js

@@ -35,6 +35,12 @@ function cloneRequires(requires) {
 function cloneStringArray(values) {
     return values === undefined ? undefined : [...values];
 }
+function cloneCommandExamples(examples) {
+    return (examples ?? []).map((example) => ({
+        title: example.title,
+        params: { ...example.params }
+    }));
+}
 function cloneStringRecord(values) {
     return values === undefined ? undefined : { ...values };
 }
@@ -286,9 +292,11 @@ function createBaseCommand(config) {
         kind: "command",
         name: config.name,
         description: config.description,
+        examples: cloneCommandExamples(config.examples),
         aliases: [...(config.aliases ?? [])],
         positional: [...(config.positional ?? [])],
         params: config.params,
+        result: config.result,
         secrets: cloneSecrets(config.secrets),
         scope: resolveCommandScope(config.scope, undefined),
         confirm: config.confirm ?? false,
@@ -300,6 +308,8 @@ function createBaseCommand(config) {
     Object.defineProperty(command, commandConfigSymbol, {
         value: {
             scope: cloneScope(config.scope),
+            examples: cloneCommandExamples(config.examples),
+            result: config.result,
             humanInLoop: config.humanInLoop,
             secrets: cloneSecrets(config.secrets),
             requires: cloneRequires(config.requires),
@@ -348,9 +358,11 @@ function materializeCommand(command, inherited) {
         kind: "command",
         name: command.name,
         description: command.description,
+        examples: cloneCommandExamples(internal.examples),
         aliases: [...command.aliases],
         positional: [...command.positional],
         params: command.params,
+        result: internal.result,
         secrets: mergeSecrets(inherited.secrets, internal.secrets),
         scope: resolveCommandScope(internal.scope, inherited.scope),
         confirm: command.confirm,
@@ -362,6 +374,8 @@ function materializeCommand(command, inherited) {
     Object.defineProperty(materialized, commandConfigSymbol, {
         value: {
             scope: cloneScope(internal.scope),
+            examples: cloneCommandExamples(internal.examples),
+            result: internal.result,
             humanInLoop: internal.humanInLoop,
             secrets: cloneSecrets(internal.secrets),
             requires: cloneRequires(internal.requires),
@@ -453,5 +467,6 @@ export function getCommandSourcePath(command) {
     return command[commandSourcePathSymbol];
 }
 export { S, toJsonSchema } from "toolcraft-schema";
+export { AuthenticationError, BadRequestError, ClientError, ConflictError, HttpError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, ServerError, ServiceUnavailableError, UnprocessableEntityError, createHttpError } from "./http-errors.js";
 export { ApprovalDeclinedError, ToolcraftBugError, UserError };
 export { findPackageMetadata, packageMetadata } from "./package-metadata.js";

package/dist/mcp-proxy.js

@@ -68,23 +68,38 @@ function createProxyCommand(parent, tool, commandName, connection) {
     if (params.kind !== "object") {
         throw new Error(`upstream tool "${tool.name}" must define an object input schema`);
     }
+    const result = tool.outputSchema === undefined
+        ? undefined
+        : convertJsonSchema(tool.outputSchema);
+    if (result !== undefined && result.kind !== "object") {
+        throw new Error(`upstream tool "${tool.name}" must define an object output schema`);
+    }
     return markProxyNode({
         kind: "command",
         name: commandName,
         description: tool.description,
+        examples: [],
         aliases: [],
         positional: [],
         params,
+        ...(result === undefined ? {} : { result }),
         secrets: cloneSecrets(parent.secrets),
         scope: cloneScope(parent.scope) ?? ["cli", "sdk"],
         confirm: false,
         requires: parent.requires,
         handler: async (ctx) => {
             const client = await ensureConnected(connection);
-            return client.callTool({
+            const toolResult = await client.callTool({
                 name: tool.name,
                 arguments: ctx.params,
             });
+            if (result === undefined) {
+                return toolResult;
+            }
+            if (toolResult.structuredContent === undefined) {
+                throw new Error(`upstream tool "${tool.name}" declared outputSchema but returned no structuredContent`);
+            }
+            return toolResult.structuredContent;
         },
         render: undefined,
     });