toolcraft 0.0.107 → 0.0.108

package/composition.json

@@ -53,7 +53,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.107",
+      "version": "0.0.108",
       "license": "MIT"
     },
     {
@@ -63,7 +63,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.107",
+      "version": "0.0.108",
       "license": "MIT"
     }
   ]

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 import "./node-require-shim.js";
 import { configureTheme } from "toolcraft-design";
-import type { Group, HandlerFs, LogLevel, RuntimeLoggerInput } from "./index.js";
+import type { Command, Group, HandlerFs, LogLevel, RenderPrimitives, RuntimeLoggerInput } from "./index.js";
 import { type ErrorReportsOption } from "./error-report.js";
 import type { HumanInLoopRuntimeOptions } from "./human-in-loop/types.js";
 export { renderErrorReport } from "./error-report.js";
@@ -10,10 +10,21 @@ type Casing = "kebab" | "snake";
 export interface CLIControls {
     debug?: boolean;
     logLevel?: boolean;
-    output?: boolean;
+    output?: boolean | CLIOutputControl;
     verbose?: boolean;
     yes?: boolean;
 }
+export interface CLIOutputFormatContext {
+    command: Command<any, any, any, any>;
+    commandPath: string;
+    primitives: RenderPrimitives;
+    result: unknown;
+}
+export type CLIOutputFormatRenderer = (context: CLIOutputFormatContext) => string | undefined;
+export type CLIOutputFormats = Readonly<Record<string, CLIOutputFormatRenderer>>;
+export interface CLIOutputControl {
+    formats?: CLIOutputFormats;
+}
 export interface RunCLIOptions<TServices extends object = Record<string, unknown>> {
     apiVersion?: string;
     approvals?: boolean;
@@ -48,6 +59,7 @@ export interface CLICommandTreeSnapshotOption {
     positional?: boolean;
     global?: boolean;
     dynamic?: boolean;
+    choices?: string[];
 }
 export interface CLICommandTreeSnapshotCommand {
     kind: "command";

package/dist/cli.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { validate as validateSchema } from "toolcraft-schema";
 import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
-import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, resolveCommandSecrets } from "./index.js";
+import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { writeErrorReport } from "./error-report.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
@@ -662,14 +662,35 @@ function createOption(field, globalLongOptionFlags) {
     return [option];
 }
 function resolveCLIControls(controls) {
+    const outputFormats = typeof controls?.output === "object" ? (controls.output.formats ?? {}) : {};
+    validateOutputFormats(outputFormats);
     return {
         debug: controls?.debug === true,
         logLevel: controls?.logLevel === true,
-        output: controls?.output === true,
+        output: controls?.output === true || typeof controls?.output === "object",
+        outputFormats,
         verbose: controls?.verbose === true,
         yes: controls?.yes === true
     };
 }
+const BUILT_IN_OUTPUT_FORMATS = ["rich", "md", "markdown", "json"];
+function outputFormatNames(controls) {
+    return [...BUILT_IN_OUTPUT_FORMATS, ...Object.keys(controls.outputFormats)];
+}
+function validateOutputFormats(formats) {
+    for (const [name, renderer] of Object.entries(formats)) {
+        const hasWhitespace = name.split("").some((character) => character.trim() === "");
+        if (name.length === 0 || name.trim() !== name || hasWhitespace) {
+            throw new ToolcraftBugError(`Custom output format names must be non-empty and contain no whitespace: ${JSON.stringify(name)}.`);
+        }
+        if (BUILT_IN_OUTPUT_FORMATS.includes(name)) {
+            throw new ToolcraftBugError(`Custom output format "${name}" conflicts with a built-in format.`);
+        }
+        if (typeof renderer !== "function") {
+            throw new ToolcraftBugError(`Custom output format "${name}" must define a renderer function.`);
+        }
+    }
+}
 function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
     const flags = [];
     if (presetsEnabled) {
@@ -1129,7 +1150,7 @@ function formatGlobalOptionsLine(ctx) {
         flags.push("--yes");
     }
     if (ctx.controls.output) {
-        flags.push("--output <format>");
+        flags.push(`--output <${outputFormatNames(ctx.controls).join("|")}>`);
     }
     if (ctx.controls.verbose) {
         flags.push("-v, --verbose");
@@ -1535,13 +1556,15 @@ function createGlobalSnapshotOptions(presetsEnabled, versionEnabled, controls) {
         });
     }
     if (controls.output) {
+        const choices = outputFormatNames(controls);
         options.push({
             name: "output",
             flags: ["--output"],
             type: "enum",
             required: false,
             hidden: true,
-            description: "Output format."
+            description: "Output format.",
+            choices
         });
     }
     if (controls.debug) {
@@ -1656,15 +1679,19 @@ function addGlobalOptions(command, presetsEnabled, controls) {
         options.push(new Option("--yes", "Accept defaults and skip prompts."));
     }
     if (controls.output) {
-        options.push(new Option("--output <format>", "Output format.").argParser((value) => {
+        const choices = outputFormatNames(controls);
+        options.push(new Option("--output <format>", "Output format.").choices(choices).argParser((value) => {
             if (value === "rich" || value === "md" || value === "json") {
                 return value;
             }
             if (value === "markdown") {
                 return "md";
             }
-            throw new InvalidArgumentError(formatInvalidEnumMessage("--output", value, ["rich", "md", "markdown", "json"], {
-                candidates: ["rich", "markdown", "json"],
+            if (Object.hasOwn(controls.outputFormats, value)) {
+                return value;
+            }
+            throw new InvalidArgumentError(formatInvalidEnumMessage("--output", value, choices, {
+                candidates: ["rich", "markdown", "json", ...Object.keys(controls.outputFormats)],
                 threshold: 3
             }));
         }));
@@ -1834,11 +1861,11 @@ function resolveOutput(resolvedFlags) {
         return "json";
     }
     if (resolvedFlags.output !== undefined) {
-        return resolvedFlags.output;
+        return resolvedFlags.output === "markdown" ? "md" : resolvedFlags.output;
     }
     return "rich";
 }
-function resolveOutputFromArgv(argv) {
+function resolveOutputFromArgv(argv, formats = {}) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index] ?? "";
         if (token === "--json") {
@@ -1855,6 +1882,9 @@ function resolveOutputFromArgv(argv) {
             if (value === "markdown") {
                 return "md";
             }
+            if (value !== undefined && Object.hasOwn(formats, value)) {
+                return value;
+            }
             continue;
         }
         if (token.startsWith("--output=")) {
@@ -1865,17 +1895,21 @@ function resolveOutputFromArgv(argv) {
             if (value === "markdown") {
                 return "md";
             }
+            if (Object.hasOwn(formats, value)) {
+                return value;
+            }
         }
     }
     return "rich";
 }
-const DESIGN_SYSTEM_OUTPUT_BY_MODE = {
-    rich: "terminal",
-    md: "markdown",
-    json: "json"
-};
 function toDesignSystemOutput(output) {
-    return DESIGN_SYSTEM_OUTPUT_BY_MODE[output];
+    if (output === "md") {
+        return "markdown";
+    }
+    if (output === "json") {
+        return "json";
+    }
+    return "terminal";
 }
 async function withOutputFormat(output, fn) {
     const previous = process.env.OUTPUT_FORMAT;
@@ -2994,17 +3028,18 @@ function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, runtimeEnv, runtimeFs, outputEmitter, promptStreams, diagnosticsOptions, onErrorReportContext) {
+async function executeCommand(state, services, requirementOptions, runtimeFetch, runtimeOptions, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
     const logger = createLogger(outputEmitter);
+    const optionValues = state.actionCommand.optsWithGlobals();
+    const resolvedFlags = optionValues;
+    const output = resolveOutput(resolvedFlags);
     const primitives = {
         logger,
         renderTable,
         getTheme,
-        note
+        note,
+        outputFormat: output
     };
-    const optionValues = state.actionCommand.optsWithGlobals();
-    const resolvedFlags = optionValues;
-    const output = resolveOutput(resolvedFlags);
     const diagnostics = createRuntimeLogger({
         level: resolvedFlags.logLevel ??
             (diagnosticsOptions.verboseControlEnabled && resolvedFlags.verbose
@@ -3021,7 +3056,7 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         ? {
             commandPath: state.commandPath,
             params: {},
-            output,
+            output: "rich",
             stdinTTY,
             stdoutTTY
         }
@@ -3091,9 +3126,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
                             }
                         }
                         else {
-                            renderResult(state.command, event, output, primitives, outputEmitter === undefined
+                            renderCLIResult(state.command, state.commandPath, event, output, primitives, outputFormats, outputEmitter === undefined
                                 ? undefined
-                                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk));
+                                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk), outputEmitter);
                         }
                     }
                 }
@@ -3137,9 +3172,9 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
                 renderHumanInLoopPending(result);
                 return;
             }
-            const renderStatus = renderResult(state.command, result, output, primitives, outputEmitter === undefined
+            const renderStatus = renderCLIResult(state.command, state.commandPath, result, output, primitives, outputFormats, outputEmitter === undefined
                 ? undefined
-                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk));
+                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk), outputEmitter);
             if (renderStatus.mcpError) {
                 process.exitCode = 1;
             }
@@ -3155,6 +3190,25 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         throw error;
     }
 }
+function renderCLIResult(command, commandPath, result, output, primitives, outputFormats, write, emitExact) {
+    const customRenderer = outputFormats[output];
+    if (customRenderer === undefined) {
+        return renderResult(command, result, output, primitives, write);
+    }
+    const payload = customRenderer({ command, commandPath, primitives, result });
+    if (payload !== undefined && payload.length > 0) {
+        if (emitExact !== undefined) {
+            emitExact(payload);
+        }
+        else if (write === undefined) {
+            process.stdout.write(payload);
+        }
+        else {
+            write(payload);
+        }
+    }
+    return { mcpError: false };
+}
 function isStringRecord(value) {
     return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
@@ -3723,7 +3777,7 @@ export async function runCLI(roots, options = {}) {
         const execute = async (state) => {
             lastActionCommand = state.actionCommand;
             resolvedCommandPath = formatCliCommandPath(state.commandPath);
-            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, options.env, options.fs, options.outputEmitter, {
+            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, options.env, options.fs, options.outputEmitter, controls.outputFormats, {
                 input: options.promptInput,
                 output: options.promptOutput
             }, {
@@ -3785,7 +3839,9 @@ export async function runCLI(roots, options = {}) {
             debugStackMode: resolvedFlags !== undefined
                 ? resolveDebugStackMode(resolvedFlags.debug)
                 : getDebugStackModeFromArgv(argv),
-            output: resolvedFlags !== undefined ? resolveOutput(resolvedFlags) : resolveOutputFromArgv(argv),
+            output: resolvedFlags !== undefined
+                ? resolveOutput(resolvedFlags)
+                : resolveOutputFromArgv(argv, controls.outputFormats),
             verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : argv.includes("--verbose"),
             program,
             argv,

package/dist/composition.json

@@ -53,7 +53,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.107",
+      "version": "0.0.108",
       "license": "MIT"
     },
     {
@@ -63,7 +63,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.107",
+      "version": "0.0.108",
       "license": "MIT"
     }
   ]

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export interface RenderPrimitives {
     renderTable(options: RenderTableOptions): string;
     getTheme(): ThemePalette;
     note(message: string, title?: string): void;
+    outputFormat: string;
 }
 export interface CheckResult {
     ok: boolean;

package/dist/renderer.d.ts

@@ -1,5 +1,5 @@
 import type { Command, RenderPrimitives } from "./index.js";
-export type OutputMode = "rich" | "md" | "json";
+export type OutputMode = "rich" | "md" | "json" | (string & {});
 type WriteStream = "stdout" | "stderr";
 type WriteFn = (chunk: string, stream?: WriteStream) => void;
 export interface RenderResultStatus {

package/dist/testing/harness.d.ts

@@ -4,6 +4,7 @@ import { type FetchRoute } from "./fakes.js";
 import { type FsChange, type MemoryFs } from "./memory-fs.js";
 import { type ParityResult } from "./parity.js";
 import { type StreamStatusEvent } from "../stream.js";
+import { type CLIOutputFormats } from "../cli.js";
 export type PipelineStage = "resolve" | "secrets" | "requirements" | "params" | "confirm" | "handler" | "render";
 export type EffectEvent = {
     seq: number;
@@ -67,6 +68,7 @@ export interface RunResult<T> {
     };
 }
 export interface CommandTestHarness {
+    cli(args: string[], options?: HarnessCLIOptions): Promise<HarnessCLIResult>;
     run<T>(path: string[], params?: Record<string, unknown>): Promise<RunResult<T>>;
     stream<T>(path: string[], params?: Record<string, unknown>, options?: {
         limit?: number;
@@ -76,6 +78,14 @@ export interface CommandTestHarness {
     fs: MemoryFs;
     timeline: EffectEvent[];
 }
+export interface HarnessCLIOptions {
+    formats?: CLIOutputFormats;
+}
+export interface HarnessCLIResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
 export interface StreamRunResult<T> {
     ok: boolean;
     events: T[];
@@ -83,5 +93,5 @@ export interface StreamRunResult<T> {
     error?: unknown;
 }
 type EmptyHarnessServices = Record<string, never>;
-export declare function createCommandTestHarness<TServices extends object = EmptyHarnessServices>(root: Group, options?: HarnessOptions<TServices>): CommandTestHarness;
+export declare function createCommandTestHarness<TServices extends object = EmptyHarnessServices>(root: Group<TServices>, options?: HarnessOptions<TServices>): CommandTestHarness;
 export {};

package/dist/testing/harness.js

@@ -12,6 +12,7 @@ import { createMemoryFs } from "./memory-fs.js";
 import { runParity } from "./parity.js";
 import { createRenderCapture } from "./render-capture.js";
 import { createManagedStream } from "../stream.js";
+import { runCLI } from "../cli.js";
 function isHandlerFs(value) {
     return typeof value.readFile === "function";
 }
@@ -186,6 +187,33 @@ export function createCommandTestHarness(root, options = {}) {
     return {
         fs: memoryFs,
         timeline: cumulativeTimeline,
+        async cli(args, cliOptions = {}) {
+            let stdout = "";
+            const previousExitCode = process.exitCode;
+            process.exitCode = undefined;
+            try {
+                await runCLI(root, {
+                    argv: ["node", root.name, ...args],
+                    controls: { output: { formats: cliOptions.formats } },
+                    services,
+                    env: Object.fromEntries(Object.entries(options.env ?? {}).flatMap(([key, value]) => value === undefined ? [] : [[key, value]])),
+                    fs: memoryFs,
+                    fetch: runtimeFetch,
+                    logLevel: options.logLevel,
+                    outputEmitter(entry) {
+                        stdout += entry;
+                    }
+                });
+                return {
+                    exitCode: process.exitCode ?? 0,
+                    stdout,
+                    stderr: ""
+                };
+            }
+            finally {
+                process.exitCode = previousExitCode;
+            }
+        },
         async stream(requestedPath, inputParams = {}, streamOptions = {}) {
             const events = [];
             const statuses = [];
@@ -444,11 +472,11 @@ export function createCommandTestHarness(root, options = {}) {
                     rendered.rich = capture.output();
                 }
                 if (command.render?.markdown) {
-                    const capture = createRenderCapture();
+                    const capture = createRenderCapture("md");
                     rendered.markdown = stripAnsi(command.render.markdown(invoked, capture.primitives));
                 }
                 if (command.render?.json) {
-                    const capture = createRenderCapture();
+                    const capture = createRenderCapture("json");
                     rendered.json = command.render.json(invoked, capture.primitives);
                 }
                 return result({ ok: true, failedAt: undefined });

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { createCommandTestHarness, type CommandTestHarness, type ConfirmationRequest, type EffectEvent, type HarnessOptions, type PipelineStage, type RunResult, type StreamRunResult } from "./harness.js";
+export { createCommandTestHarness, type CommandTestHarness, type ConfirmationRequest, type EffectEvent, type HarnessCLIOptions, type HarnessCLIResult, type HarnessOptions, type PipelineStage, type RunResult, type StreamRunResult } from "./harness.js";
 export { fakeFetch, fakeService, type FetchRoute, type ServiceCall } from "./fakes.js";
 export { createMemoryFs, type FsChange, type MemoryFs } from "./memory-fs.js";
 export type { ParityResult, SurfaceOutcome } from "./parity.js";

package/dist/testing/render-capture.d.ts

@@ -3,4 +3,4 @@ export interface RenderCapture {
     primitives: RenderPrimitives;
     output(): string;
 }
-export declare function createRenderCapture(): RenderCapture;
+export declare function createRenderCapture(outputFormat?: string): RenderCapture;

package/dist/testing/render-capture.js

@@ -32,7 +32,7 @@ function createCaptureTheme() {
         intro: (text) => ` Poe - ${text} `
     };
 }
-export function createRenderCapture() {
+export function createRenderCapture(outputFormat = "rich") {
     const output = [];
     const captureTheme = createCaptureTheme();
     const emit = (message) => {
@@ -47,7 +47,8 @@ export function createRenderCapture() {
                 maxWidth: captureWidth
             }))),
             getTheme: () => captureTheme,
-            note: (message, title) => emit(title === undefined ? message : `${title}\n${message}`)
+            note: (message, title) => emit(title === undefined ? message : `${title}\n${message}`),
+            outputFormat
         },
         output: () => output.join("\n")
     };

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -150,7 +150,7 @@
     "auth-store"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.107",
+    "toolcraft-schema": "0.0.108",
     "toolcraft-design": "^0.0.2",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",