toolcraft-openapi 0.0.1

package/dist/naming.js

@@ -0,0 +1,218 @@
+import { UserError } from "agent-kit";
+export const METHOD_DEFAULTS = {
+    delete: {
+        collection: "delete",
+        resource: "delete",
+        confirm: true
+    },
+    get: {
+        collection: "list",
+        resource: "view",
+        genericVerbs: ["get", "list", "view"],
+        preferOperationIdWhenPathTailIsGeneric: true
+    }
+};
+export function deriveNoun(operation, path, operationId) {
+    const noun = operation.tags?.[0];
+    if (typeof noun !== "string" || noun.length === 0) {
+        const fallbackNoun = deriveNounFromPath(path);
+        if (fallbackNoun === undefined) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} must define tags[0] or a static resource segment in the path to derive a command noun.`);
+        }
+        return fallbackNoun;
+    }
+    return toKebabCase(noun);
+}
+export function deriveVerb(method, path, operation, operationId, noun) {
+    const segments = splitPathSegments(path);
+    const defaults = METHOD_DEFAULTS[method];
+    if (defaults !== undefined) {
+        const lastSegment = segments.at(-1);
+        if (isPathTemplateSegment(lastSegment)) {
+            return defaults.resource;
+        }
+        if (defaults.preferOperationIdWhenPathTailIsGeneric === true) {
+            const derived = deriveVerbFromOperationId(method, operation.operationId, noun, defaults);
+            const pathTail = lastSegment === undefined ? undefined : toKebabCase(lastSegment);
+            if (derived !== undefined) {
+                if (pathTail === undefined || derived !== pathTail) {
+                    return derived;
+                }
+                if (!operationIdStartsWithCollectionVerb(method, operation.operationId, noun, defaults)) {
+                    return pathTail;
+                }
+            }
+        }
+        return defaults.collection;
+    }
+    const derived = deriveVerbFromOperationId(method, operation.operationId, noun);
+    if (derived !== undefined) {
+        return derived;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} is missing an operationId, so agent-kit-openapi cannot derive a stable command verb.`);
+}
+export function normalizeParamName(name) {
+    return toCamelCase(name);
+}
+export function toPascalCase(value) {
+    const camel = toCamelCase(value);
+    return camel.length === 0 ? camel : `${camel[0]?.toUpperCase() ?? ""}${camel.slice(1)}`;
+}
+export function toCamelCase(value) {
+    return splitWords(value)
+        .map((word, index) => (index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`))
+        .join("");
+}
+export function toKebabCase(value) {
+    return splitWords(value).join("-");
+}
+export function toCliFlag(value) {
+    return toKebabCase(value);
+}
+export function splitWords(value) {
+    const normalized = value
+        .replaceAll("-", " ")
+        .replaceAll("_", " ")
+        .replaceAll(".", " ")
+        .replaceAll("/", " ");
+    return normalized
+        .split(" ")
+        .flatMap(splitCamelCaseWord)
+        .filter((word) => word.length > 0)
+        .map((word) => word.toLowerCase());
+}
+export function toMcpPrefix(name) {
+    return name.replaceAll("-", "_");
+}
+export function isIdentifierName(value) {
+    return /^[$A-Z_a-z][$\w]*$/u.test(value);
+}
+function splitPathSegments(path) {
+    return path.split("/").filter((segment) => segment.length > 0);
+}
+function deriveNounFromPath(path) {
+    return splitPathSegments(path)
+        .find((segment) => !isPathTemplateSegment(segment) && segment !== "api" && !isVersionWord(segment))
+        ?.split("/")
+        .map((segment) => toKebabCase(segment))
+        .find((segment) => segment.length > 0);
+}
+function isPathTemplateSegment(segment) {
+    return segment !== undefined && segment.startsWith("{") && segment.endsWith("}");
+}
+function deriveVerbFromOperationId(method, operationId, noun, defaults) {
+    const words = normalizeOperationIdWords(method, operationId, noun);
+    if (words === undefined) {
+        return undefined;
+    }
+    const verbWords = stripLeadingGenericVerb(words, defaults?.genericVerbs);
+    return verbWords.length === 0 ? undefined : verbWords.join("-");
+}
+function operationIdStartsWithCollectionVerb(method, operationId, noun, defaults) {
+    const words = normalizeOperationIdWords(method, operationId, noun);
+    return words?.[0] === defaults.collection;
+}
+function normalizeOperationIdWords(method, operationId, noun) {
+    if (operationId === undefined) {
+        return undefined;
+    }
+    const nounWords = splitWords(noun);
+    return dedupeAdjacentWords(trimTrailingNounUnlessItConsumesAll(trimTrailingMethod(trimLeadingWords(splitWords(operationId).filter((word) => !isVersionWord(word)), nounWords), method), nounWords));
+}
+function stripLeadingGenericVerb(words, genericVerbs) {
+    if (genericVerbs === undefined || words.length <= 1 || !genericVerbs.includes(words[0] ?? "")) {
+        return words;
+    }
+    let start = 1;
+    while (start < words.length - 1 && words[start] === words[0]) {
+        start += 1;
+    }
+    return words.slice(start);
+}
+function trimTrailingNounUnlessItConsumesAll(words, nounWords) {
+    const withoutTrailingNoun = trimTrailingWords(words, nounWords);
+    return withoutTrailingNoun.length === 0 ? words : withoutTrailingNoun;
+}
+function trimLeadingWords(words, prefix) {
+    if (prefix.length === 0 || prefix.length > words.length) {
+        return words;
+    }
+    for (let index = 0; index < prefix.length; index += 1) {
+        if (words[index] !== prefix[index]) {
+            return words;
+        }
+    }
+    return words.slice(prefix.length);
+}
+function trimTrailingWords(words, suffix) {
+    if (suffix.length === 0 || suffix.length >= words.length) {
+        return words;
+    }
+    const start = words.length - suffix.length;
+    for (let index = 0; index < suffix.length; index += 1) {
+        if (words[start + index] !== suffix[index]) {
+            return words;
+        }
+    }
+    return words.slice(0, start);
+}
+function trimTrailingMethod(words, method) {
+    return words.at(-1) === method ? words.slice(0, -1) : words;
+}
+function dedupeAdjacentWords(words) {
+    if (words.length === 0) {
+        return [];
+    }
+    const deduped = [words[0] ?? ""];
+    for (let index = 1; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if (word !== deduped.at(-1)) {
+            deduped.push(word);
+        }
+    }
+    return deduped;
+}
+function isVersionWord(word) {
+    if (!word.startsWith("v") || word.length < 2) {
+        return false;
+    }
+    for (const character of word.slice(1)) {
+        if (character < "0" || character > "9") {
+            return false;
+        }
+    }
+    return true;
+}
+function splitCamelCaseWord(value) {
+    if (value.length === 0) {
+        return [];
+    }
+    const words = [value[0] ?? ""];
+    for (let index = 1; index < value.length; index += 1) {
+        const character = value[index] ?? "";
+        const previous = value[index - 1] ?? "";
+        const next = value[index + 1];
+        if (shouldStartNewWord(previous, character, next)) {
+            words.push(character);
+            continue;
+        }
+        const currentWord = words.at(-1) ?? "";
+        words[words.length - 1] = `${currentWord}${character}`;
+    }
+    return words;
+}
+function shouldStartNewWord(previous, character, next) {
+    if (!isUppercaseLetter(character)) {
+        return false;
+    }
+    if (isLowercaseLetter(previous)) {
+        return true;
+    }
+    return isUppercaseLetter(previous) && next !== undefined && isLowercaseLetter(next);
+}
+function isLowercaseLetter(character) {
+    return character >= "a" && character <= "z";
+}
+function isUppercaseLetter(character) {
+    return character >= "A" && character <= "Z";
+}

package/dist/request-shape.d.ts

@@ -0,0 +1,15 @@
+export declare const REQUEST_PARAM_SECTIONS: readonly [{
+    readonly location: "path";
+    readonly key: "pathParams";
+    readonly omittable: false;
+}, {
+    readonly location: "query";
+    readonly key: "query";
+    readonly omittable: false;
+}, {
+    readonly location: "body";
+    readonly key: "body";
+    readonly omittable: true;
+}];
+export type RequestParamSection = (typeof REQUEST_PARAM_SECTIONS)[number];
+export type RequestSectionKey = RequestParamSection["key"];

package/dist/request-shape.js

@@ -0,0 +1,5 @@
+export const REQUEST_PARAM_SECTIONS = [
+    { location: "path", key: "pathParams", omittable: false },
+    { location: "query", key: "query", omittable: false },
+    { location: "body", key: "body", omittable: true }
+];

package/dist/runtime.d.ts

@@ -0,0 +1,13 @@
+import { type CommandNode } from "agent-kit";
+import { type DefineClientOptions, type DefinedClient, type OpenApiClientServices } from "./define-client.js";
+import { type OpenApiDocument } from "./generate.js";
+import { type OpenApiSourceFileSystem } from "./spec-source.js";
+export type OpenApiDocumentSource = OpenApiDocument | string | URL;
+export interface CommandsFromSpecOptions {
+    cwd?: string;
+    fetch?: typeof globalThis.fetch;
+    fs?: OpenApiSourceFileSystem;
+}
+export type DefineClientFromSpecOptions<TServices extends object = Record<string, never>> = Omit<DefineClientOptions<TServices>, "commands"> & CommandsFromSpecOptions;
+export declare function commandsFromSpec(source: OpenApiDocumentSource, options?: CommandsFromSpecOptions): Promise<CommandNode<OpenApiClientServices>[]>;
+export declare function defineClientFromSpec<TServices extends object = Record<string, never>>(spec: OpenApiDocumentSource, options: DefineClientFromSpecOptions<TServices>): Promise<DefinedClient<TServices>>;

package/dist/runtime.js

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import { defineCommand, defineGroup, S } from "agent-kit";
+import { defineClient } from "./define-client.js";
+import { collectSchemaOptionEntries, collectGeneratedCommands } from "./generate.js";
+import { groupByNoun } from "./group-by-noun.js";
+import { requestJson } from "./http.js";
+import { buildRequestShape, executePreflightBlocks } from "./interpreter.js";
+import { parseOpenApiDocument, readOpenApiSourceText } from "./spec-source.js";
+const RUNTIME_COMMAND_SCOPE = ["cli", "mcp", "sdk"];
+export async function commandsFromSpec(source, options = {}) {
+    const document = await resolveDocument(source, options);
+    return createRuntimeGroups(collectGeneratedCommands(document));
+}
+export async function defineClientFromSpec(spec, options) {
+    const { cwd, fetch, fs: specFs, ...clientOptions } = options;
+    const commands = (await commandsFromSpec(spec, {
+        cwd,
+        fetch,
+        fs: specFs
+    }));
+    return defineClient({ ...clientOptions, commands });
+}
+async function resolveDocument(source, options) {
+    if (typeof source !== "string" && !(source instanceof URL)) {
+        return source;
+    }
+    const sourceText = await readOpenApiSourceText(source, {
+        cwd: options.cwd ?? process.cwd(),
+        fetch: options.fetch ?? globalThis.fetch,
+        fs: options.fs ?? fs
+    });
+    return parseOpenApiDocument(sourceText, source);
+}
+function createRuntimeGroups(commands) {
+    return groupByNoun(commands).map(({ noun, commands: nounCommands }) => defineGroup({
+        name: noun,
+        children: nounCommands.map((command) => createRuntimeCommand(command))
+    }));
+}
+function createRuntimeCommand(command) {
+    const paramsSchema = S.Object(Object.fromEntries(command.params.map((param) => [param.paramName, createRuntimeParamSchema(param)])), command.paramsSchemaOptions);
+    return defineCommand({
+        name: command.verb,
+        ...(command.description === undefined ? {} : { description: command.description }),
+        scope: RUNTIME_COMMAND_SCOPE,
+        ...(command.confirm ? { confirm: true } : {}),
+        params: paramsSchema,
+        handler: createRuntimeHandler(command)
+    });
+}
+function createRuntimeHandler(command) {
+    return async ({ params, baseUrl, tokenSource, fetch }) => {
+        const resolvedValues = executePreflightBlocks(command.preflightBlocks, params);
+        const requestShape = buildRequestShape(command.requestFields, command.sectionRenders, command.optionalSections, params, resolvedValues);
+        return requestJson({
+            baseUrl,
+            path: command.path,
+            method: command.method,
+            auth: command.auth,
+            tokenSource,
+            fetch,
+            dryRun: params.dryRun,
+            verbose: params.verbose,
+            ...requestShape
+        });
+    };
+}
+function createRuntimeParamSchema(param) {
+    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.scope);
+    return param.optional ? S.Optional(definition) : definition;
+}
+function createRuntimeDefinition(definition, description, shortFlag, scope) {
+    const options = createRuntimeSchemaOptions(definition, description, shortFlag, scope);
+    return RUNTIME_DEFINITION_BUILDERS[definition.kind](definition, options);
+}
+const RUNTIME_DEFINITION_BUILDERS = {
+    array: (definition, options) => {
+        const itemDefinition = createRuntimeDefinition(definition.itemDefinition, undefined, undefined, undefined);
+        return options === undefined ? S.Array(itemDefinition) : S.Array(itemDefinition, options);
+    },
+    boolean: (_definition, options) => options === undefined ? S.Boolean() : S.Boolean(options),
+    enum: (definition, options) => options === undefined ? S.Enum(definition.enumValues) : S.Enum(definition.enumValues, options),
+    number: (_definition, options) => options === undefined ? S.Number() : S.Number(options),
+    string: (_definition, options) => options === undefined ? S.String() : S.String(options)
+};
+function createRuntimeSchemaOptions(definition, description, shortFlag, scope) {
+    const options = Object.fromEntries(collectSchemaOptionEntries({
+        definition,
+        description,
+        shortFlag,
+        scope
+    }).map(({ key, value }) => [key, Array.isArray(value) ? [...value] : value]));
+    return Object.keys(options).length === 0 ? undefined : options;
+}

package/dist/spec-source.d.ts

@@ -0,0 +1,11 @@
+import type { OpenApiDocument } from "./generate.js";
+export interface OpenApiSourceFileSystem {
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+}
+export interface OpenApiSourceServices {
+    cwd: string;
+    fetch: typeof globalThis.fetch;
+    fs: OpenApiSourceFileSystem;
+}
+export declare function readOpenApiSourceText(input: string | URL, services: OpenApiSourceServices): Promise<string>;
+export declare function parseOpenApiDocument(sourceText: string, input: string | URL): OpenApiDocument;

package/dist/spec-source.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { UserError } from "agent-kit";
+export async function readOpenApiSourceText(input, services) {
+    const inputUrl = input instanceof URL ? input : tryParseUrl(input);
+    const sourceLabel = formatSourceLabel(input);
+    try {
+        if (typeof input === "string" && inputUrl === null) {
+            return await services.fs.readFile(path.resolve(services.cwd, input), "utf8");
+        }
+        if (inputUrl === null) {
+            throw new UserError(`Unsupported OpenAPI input ${JSON.stringify(sourceLabel)}.`);
+        }
+        if (inputUrl.protocol === "file:") {
+            return await services.fs.readFile(fileURLToPath(inputUrl), "utf8");
+        }
+        if (inputUrl.protocol !== "http:" && inputUrl.protocol !== "https:") {
+            throw new UserError(`Unsupported OpenAPI input URL protocol ${JSON.stringify(inputUrl.protocol)}.`);
+        }
+        const response = await services.fetch(inputUrl.toString());
+        if (!response.ok) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: ${response.status} ${response.statusText}`);
+        }
+        return await response.text();
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            throw error;
+        }
+        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+export function parseOpenApiDocument(sourceText, input) {
+    let parsed;
+    try {
+        parsed = parseYaml(sourceText);
+    }
+    catch (error) {
+        throw new UserError(`Failed to parse OpenAPI document ${JSON.stringify(formatSourceLabel(input))}: ${getErrorMessage(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UserError(`OpenAPI document ${JSON.stringify(formatSourceLabel(input))} must parse to an object.`);
+    }
+    return parsed;
+}
+function tryParseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function formatSourceLabel(source) {
+    return source instanceof URL ? source.toString() : source;
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

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

@@ -0,0 +1,11 @@
+export declare function renderAgentMessage(text: string): void;
+export declare function renderToolStart(kind: string, title: string): void;
+export declare function renderToolComplete(kind: string): void;
+export declare function renderReasoning(text: string): void;
+export declare function renderUsage(tokens: {
+    input: number;
+    output: number;
+    cached?: number;
+    costUsd?: number;
+}): void;
+export declare function renderError(message: string): void;

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

@@ -0,0 +1,121 @@
+import chalk from "chalk";
+import { resolveOutputFormat } from "../internal/output-format.js";
+import { renderMarkdown } from "../terminal-markdown/index.js";
+import { getAcpWriter } from "./writer.js";
+function truncate(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    if (maxLength <= 3)
+        return text.slice(0, maxLength);
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+const KIND_COLORS = {
+    exec: (text) => chalk.yellow(text),
+    edit: (text) => chalk.magenta(text),
+    read: (text) => chalk.cyan(text),
+    search: (text) => chalk.blue(text),
+    think: (text) => chalk.dim(text),
+    other: (text) => chalk.dim(text)
+};
+function colorForKind(kind) {
+    return KIND_COLORS[kind] ?? ((text) => chalk.dim(text));
+}
+function writeLine(line) {
+    getAcpWriter()(line);
+}
+const AGENT_PREFIX = `${chalk.green.bold("✓")} agent: `;
+function formatCost(costUsd) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: "USD",
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 6
+    }).format(costUsd);
+}
+export function renderAgentMessage(text) {
+    const format = resolveOutputFormat();
+    if (format === "markdown") {
+        writeLine(`- **agent:** ${text}`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({ event: "agent_message", text }));
+        return;
+    }
+    const rendered = renderMarkdown(text).trimEnd();
+    writeLine(`${AGENT_PREFIX}${rendered}`);
+}
+export function renderToolStart(kind, title) {
+    const format = resolveOutputFormat();
+    if (format === "markdown") {
+        writeLine(`- *→ ${kind}: ${title}*`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({ event: "tool_start", kind, title }));
+        return;
+    }
+    const color = colorForKind(kind);
+    writeLine(color(`  → ${kind}: ${title}`));
+}
+export function renderToolComplete(kind) {
+    const format = resolveOutputFormat();
+    if (format === "markdown") {
+        writeLine(`- *✓ ${kind}*`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({ event: "tool_complete", kind }));
+        return;
+    }
+    const color = colorForKind(kind);
+    writeLine(color(`  ✓ ${kind}`));
+}
+export function renderReasoning(text) {
+    const format = resolveOutputFormat();
+    if (format === "markdown") {
+        writeLine(`- *thinking:* ${truncate(text, 80)}`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({ event: "reasoning", text }));
+        return;
+    }
+    writeLine(chalk.dim(`  ✓ ${truncate(text, 80)}`));
+}
+export function renderUsage(tokens) {
+    const format = resolveOutputFormat();
+    const cached = typeof tokens.cached === "number" && tokens.cached > 0 ? ` (${tokens.cached} cached)` : "";
+    let cost = "";
+    if (typeof tokens.costUsd === "number") {
+        cost = ` (${formatCost(tokens.costUsd)})`;
+    }
+    if (format === "markdown") {
+        writeLine(`- **tokens:** ${tokens.input} in → ${tokens.output} out${cost}`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({
+            event: "usage",
+            inputTokens: tokens.input,
+            outputTokens: tokens.output,
+            cachedTokens: tokens.cached ?? 0,
+            costUsd: tokens.costUsd ?? 0
+        }));
+        return;
+    }
+    writeLine("");
+    writeLine(chalk.green(`✓ tokens: ${tokens.input} in${cached} → ${tokens.output} out${cost}`));
+}
+export function renderError(message) {
+    const format = resolveOutputFormat();
+    if (format === "markdown") {
+        writeLine(`- **error:** ${message}`);
+        return;
+    }
+    if (format === "json") {
+        writeLine(JSON.stringify({ event: "error", message }));
+        return;
+    }
+    writeLine(chalk.red(`✗ ${message}`));
+}

package/node_modules/@poe-code/design-system/dist/acp/index.d.ts

@@ -0,0 +1,3 @@
+export { renderAgentMessage, renderToolStart, renderToolComplete, renderReasoning, renderUsage, renderError } from "./components.js";
+export { getAcpWriter, withAcpWriter } from "./writer.js";
+export type { AcpLineWriter } from "./writer.js";

package/node_modules/@poe-code/design-system/dist/acp/index.js

@@ -0,0 +1,2 @@
+export { renderAgentMessage, renderToolStart, renderToolComplete, renderReasoning, renderUsage, renderError } from "./components.js";
+export { getAcpWriter, withAcpWriter } from "./writer.js";

package/node_modules/@poe-code/design-system/dist/acp/writer.d.ts

@@ -0,0 +1,13 @@
+export type AcpLineWriter = (line: string) => void;
+/**
+ * Return the writer active in the current async context, or the default
+ * stdout writer if none is bound.
+ */
+export declare function getAcpWriter(): AcpLineWriter;
+/**
+ * Run `fn` with `writer` bound as the active ACP line writer. All calls to
+ * `renderAgentMessage`, `renderToolStart`, `renderAcpEvent`, etc. made inside
+ * `fn` (or async work awaited from `fn`) will go through `writer` instead of
+ * writing to `process.stdout`.
+ */
+export declare function withAcpWriter<T>(writer: AcpLineWriter, fn: () => Promise<T>): Promise<T>;

package/node_modules/@poe-code/design-system/dist/acp/writer.js

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+const defaultWriter = (line) => {
+    process.stdout.write(`${line}\n`);
+};
+/**
+ * Return the writer active in the current async context, or the default
+ * stdout writer if none is bound.
+ */
+export function getAcpWriter() {
+    return storage.getStore() ?? defaultWriter;
+}
+/**
+ * Run `fn` with `writer` bound as the active ACP line writer. All calls to
+ * `renderAgentMessage`, `renderToolStart`, `renderAcpEvent`, etc. made inside
+ * `fn` (or async work awaited from `fn`) will go through `writer` instead of
+ * writing to `process.stdout`.
+ */
+export function withAcpWriter(writer, fn) {
+    return storage.run(writer, fn);
+}

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

@@ -0,0 +1,16 @@
+export declare function formatCommandNotFound(input: {
+    unknownCommand: string;
+    helpCommand: string;
+}): {
+    label: string;
+    hint: string;
+};
+export declare function formatCommandNotFoundPanel(input: {
+    unknownCommand: string;
+    helpCommand: string;
+    title?: string;
+}): {
+    title: string;
+    label: string;
+    footer: string;
+};

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

@@ -0,0 +1,22 @@
+import { typography } from "../tokens/typography.js";
+import { text } from "./text.js";
+export function formatCommandNotFound(input) {
+    const unknown = input.unknownCommand.length > 0
+        ? input.unknownCommand
+        : "<command>";
+    return {
+        label: `${typography.bold("Unknown command:")} ${text.command(unknown)}`,
+        hint: `${text.muted("Run")} ${text.usageCommand(input.helpCommand)} ${text.muted("for available commands.")}`
+    };
+}
+export function formatCommandNotFoundPanel(input) {
+    const message = formatCommandNotFound({
+        unknownCommand: input.unknownCommand,
+        helpCommand: input.helpCommand
+    });
+    return {
+        title: input.title ?? "command not found",
+        label: message.label,
+        footer: message.hint
+    };
+}

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

@@ -0,0 +1,20 @@
+export interface CommandInfo {
+    name: string;
+    description: string;
+}
+export interface OptionInfo {
+    flags: string;
+    description: string;
+}
+export declare function formatCommand(name: string, description: string): string;
+export declare function formatUsage(command: string, args?: string): string;
+export declare function formatOption(flags: string, description: string): string;
+export declare function formatCommandList(commands: CommandInfo[]): string;
+export declare function formatOptionList(options: OptionInfo[]): string;
+export declare const helpFormatter: {
+    readonly formatCommand: typeof formatCommand;
+    readonly formatUsage: typeof formatUsage;
+    readonly formatOption: typeof formatOption;
+    readonly formatCommandList: typeof formatCommandList;
+    readonly formatOptionList: typeof formatOptionList;
+};