toolcraft 0.0.11 → 0.0.13

package/dist/renderer.d.ts

@@ -1,5 +1,11 @@
 import type { Command, RenderPrimitives } from "./index.js";
 export type OutputMode = "rich" | "md" | "json";
-type WriteFn = (chunk: string) => void;
-export declare function renderResult(command: Command<any, any, any, any>, result: unknown, output: OutputMode, primitives: RenderPrimitives, write?: WriteFn): void;
+type WriteStream = "stdout" | "stderr";
+type WriteFn = (chunk: string, stream?: WriteStream) => void;
+export interface RenderResultStatus {
+    mcpError: boolean;
+}
+export declare function renderObjectTable(result: Record<string, unknown>, primitives: RenderPrimitives): string;
+export declare function renderArrayTable(result: Array<Record<string, unknown>>, primitives: RenderPrimitives): string;
+export declare function renderResult(command: Command<any, any, any, any>, result: unknown, output: OutputMode, primitives: RenderPrimitives, write?: WriteFn): RenderResultStatus;
 export {};

package/dist/renderer.js

@@ -1,6 +1,47 @@
+import YAML from "yaml";
 function isObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function isMcpCallToolResult(value) {
+    if (!isObject(value)) {
+        return false;
+    }
+    const hasContent = Array.isArray(value.content);
+    const hasStructured = value.structuredContent !== undefined;
+    if (!hasContent && !hasStructured) {
+        return false;
+    }
+    return Object.keys(value).every((key) => key === "content" || key === "structuredContent" || key === "isError" || key === "_meta");
+}
+function isMcpTextContent(value) {
+    return isObject(value) && value.type === "text" && typeof value.text === "string";
+}
+function extractMcpPayload(envelope) {
+    const structuredContent = envelope.structuredContent;
+    if (isObject(structuredContent) && "result" in structuredContent) {
+        return structuredContent.result;
+    }
+    if (structuredContent !== undefined) {
+        return structuredContent;
+    }
+    if (Array.isArray(envelope.content)) {
+        const text = envelope.content
+            .filter(isMcpTextContent)
+            .map((block) => block.text)
+            .join("\n");
+        return text.length > 0 ? text : undefined;
+    }
+    return undefined;
+}
+function unwrapMcpEnvelope(result) {
+    if (!isMcpCallToolResult(result)) {
+        return { result, mcpError: false };
+    }
+    return {
+        result: extractMcpPayload(result),
+        mcpError: result.isError === true,
+    };
+}
 function isArrayOfObjects(value) {
     return Array.isArray(value) && value.every((entry) => isObject(entry));
 }
@@ -21,7 +62,7 @@ function stringifyJson(value, spaces) {
         return String(value);
     }
 }
-function renderObjectTable(result, primitives) {
+export function renderObjectTable(result, primitives) {
     const rows = Object.entries(result).map(([key, value]) => ({
         key,
         value: stringifyValue(value),
@@ -59,7 +100,7 @@ function getColumnNames(rows) {
     }
     return [...names];
 }
-function renderArrayTable(result, primitives) {
+export function renderArrayTable(result, primitives) {
     if (result.length === 0) {
         return "[]";
     }
@@ -87,7 +128,7 @@ function renderArrayMarkdown(result) {
         .join(" | ")} |`);
     return [header, separator, ...rows].join("\n");
 }
-function autoRender(result, output, primitives) {
+function autoRender(result, output, _primitives) {
     if (result === null || result === undefined) {
         if (output === "json") {
             return stringifyJson({ ok: true }, 2);
@@ -100,14 +141,16 @@ function autoRender(result, output, primitives) {
         }
         return result;
     }
+    if (output === "rich" && Array.isArray(result) && result.every((value) => typeof value === "string")) {
+        return result.join("\n");
+    }
     if (isObject(result)) {
-        if (output === "rich") {
-            return renderObjectTable(result, primitives);
-        }
         if (output === "md") {
             return renderObjectMarkdown(result);
         }
-        return stringifyJson(result, 2);
+        if (output === "json") {
+            return stringifyJson(result, 2);
+        }
     }
     if (isArrayOfObjects(result)) {
         if (output === "md") {
@@ -116,33 +159,49 @@ function autoRender(result, output, primitives) {
         if (output === "json") {
             return stringifyJson(result, 2);
         }
-        return renderArrayTable(result, primitives);
+    }
+    if (output === "rich") {
+        return YAML.stringify(result);
     }
     return stringifyJson(result, 2);
 }
-export function renderResult(command, result, output, primitives, write = (chunk) => {
+export function renderResult(command, result, output, primitives, write = (chunk, stream = "stdout") => {
+    if (stream === "stderr") {
+        process.stderr.write(chunk);
+        return;
+    }
     process.stdout.write(chunk);
 }) {
+    const unwrapped = unwrapMcpEnvelope(result);
+    result = unwrapped.result;
+    if (unwrapped.mcpError) {
+        const payload = autoRender(result, output, primitives);
+        if (payload.length > 0) {
+            write(`${payload}\n`, "stderr");
+        }
+        return { mcpError: true };
+    }
     if (output === "json" && command.render?.json) {
         const payload = command.render.json(result, primitives);
         if (payload !== undefined) {
             write(`${stringifyJson(payload, 2)}\n`);
         }
-        return;
+        return { mcpError: false };
     }
     if (output === "md" && command.render?.markdown) {
         const payload = command.render.markdown(result, primitives);
         if (typeof payload === "string" && payload.length > 0) {
             write(`${payload}\n`);
         }
-        return;
+        return { mcpError: false };
     }
     if (output === "rich" && command.render?.rich) {
         command.render.rich(result, primitives);
-        return;
+        return { mcpError: false };
     }
     const payload = autoRender(result, output, primitives);
     if (payload.length > 0) {
         write(`${payload}\n`);
     }
+    return { mcpError: false };
 }

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

@@ -0,0 +1,4 @@
+import type { CommandInfo, FormatColumnsOptions, OptionInfo } from "./help-formatter.js";
+export declare function formatColumns(opts: FormatColumnsOptions): string;
+export declare function formatCommandList(commands: CommandInfo[]): string;
+export declare function formatOptionList(options: OptionInfo[]): string;

package/node_modules/@poe-code/design-system/dist/components/help-formatter-plain.js

@@ -0,0 +1,132 @@
+function stripAnsi(value) {
+    let output = "";
+    for (let index = 0; index < value.length; index += 1) {
+        if (value[index] === "\u001b") {
+            if (value[index + 1] === "[") {
+                index += 2;
+                while (index < value.length) {
+                    const code = value.charCodeAt(index);
+                    if (code >= 0x40 && code <= 0x7e) {
+                        break;
+                    }
+                    index += 1;
+                }
+            }
+            continue;
+        }
+        output += value[index];
+    }
+    return output;
+}
+function toAscii(value) {
+    let output = "";
+    const stripped = stripAnsi(value);
+    for (let index = 0; index < stripped.length; index += 1) {
+        const code = stripped.charCodeAt(index);
+        output += code <= 0x7f ? stripped[index] : "?";
+    }
+    return output;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function padEndVisible(value, width) {
+    return value + " ".repeat(Math.max(0, width - value.length));
+}
+function isWhitespace(char) {
+    return char === " " || char === "\n" || char === "\t" || char === "\r";
+}
+function splitWords(value) {
+    const words = [];
+    let word = "";
+    for (const char of value) {
+        if (isWhitespace(char)) {
+            if (word) {
+                words.push(word);
+                word = "";
+            }
+            continue;
+        }
+        word += char;
+    }
+    if (word) {
+        words.push(word);
+    }
+    return words;
+}
+function wrapWords(value, width) {
+    const words = splitWords(value);
+    if (words.length === 0) {
+        return [""];
+    }
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (!line) {
+            line = word;
+            continue;
+        }
+        if (line.length + 1 + word.length <= width) {
+            line += ` ${word}`;
+            continue;
+        }
+        lines.push(line);
+        line = word;
+    }
+    lines.push(line);
+    return lines;
+}
+export function formatColumns(opts) {
+    const rows = opts.rows.map((row) => ({
+        left: toAscii(row.left),
+        right: toAscii(row.right)
+    }));
+    if (rows.length === 0) {
+        return "";
+    }
+    const totalWidth = opts.totalWidth ?? process.stdout.columns ?? 100;
+    const minLeftWidth = opts.minLeftWidth ?? 12;
+    const maxLeftWidth = opts.maxLeftWidth ?? 32;
+    const gap = opts.gap ?? 3;
+    const indent = opts.indent ?? 2;
+    const maxLeftContentWidth = Math.max(...rows.map((row) => row.left.length));
+    const leftWidth = clamp(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
+    const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+    const firstIndent = " ".repeat(indent);
+    const continuationIndent = " ".repeat(indent + leftWidth);
+    return rows
+        .flatMap((row) => {
+        if (row.right.length === 0) {
+            return [`${firstIndent}${row.left}`];
+        }
+        const rightLines = wrapWords(row.right, rightWidth);
+        if (row.left.length > leftWidth) {
+            return [
+                `${firstIndent}${row.left}`,
+                ...rightLines.map((line) => `${continuationIndent}${line}`)
+            ];
+        }
+        const firstLine = `${firstIndent}${padEndVisible(row.left, leftWidth)}${rightLines[0]}`;
+        const continuationLines = rightLines
+            .slice(1)
+            .map((line) => `${continuationIndent}${line}`);
+        return [firstLine, ...continuationLines];
+    })
+        .join("\n");
+}
+export function formatCommandList(commands) {
+    return formatColumns({
+        rows: commands.map((cmd) => ({
+            left: cmd.name,
+            right: cmd.description
+        }))
+    });
+}
+export function formatOptionList(options) {
+    return formatColumns({
+        rows: options.map((opt) => ({
+            left: opt.flags,
+            right: opt.description
+        }))
+    });
+}

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

@@ -6,12 +6,25 @@ export interface OptionInfo {
     flags: string;
     description: string;
 }
+export interface FormatColumnsOptions {
+    rows: Array<{
+        left: string;
+        right: string;
+    }>;
+    totalWidth?: number;
+    minLeftWidth?: number;
+    maxLeftWidth?: number;
+    gap?: number;
+    indent?: number;
+}
+export declare function formatColumns(opts: FormatColumnsOptions): 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 formatColumns: typeof formatColumns;
     readonly formatCommand: typeof formatCommand;
     readonly formatUsage: typeof formatUsage;
     readonly formatOption: typeof formatOption;

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

@@ -1,24 +1,133 @@
 import { text } from "./text.js";
-import { widths } from "../tokens/widths.js";
+function stripAnsi(value) {
+    let output = "";
+    for (let index = 0; index < value.length; index += 1)
+        if (value[index] === "\u001b" && value[index + 1] === "[")
+            while (index < value.length && value[index] !== "m")
+                index += 1;
+        else
+            output += value[index];
+    return output;
+}
+function visibleWidth(value) {
+    return stripAnsi(value).length;
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function padEndVisible(value, width) {
+    return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
+}
+function isWhitespace(char) {
+    return char === " " || char === "\n" || char === "\t" || char === "\r";
+}
+function splitWords(value) {
+    const words = [];
+    let word = "";
+    for (const char of value) {
+        if (isWhitespace(char)) {
+            if (word) {
+                words.push(word);
+                word = "";
+            }
+            continue;
+        }
+        word += char;
+    }
+    if (word) {
+        words.push(word);
+    }
+    return words;
+}
+function wrapWords(value, width) {
+    const words = splitWords(value);
+    if (words.length === 0) {
+        return [""];
+    }
+    const lines = [];
+    let line = "";
+    for (const word of words) {
+        if (!line) {
+            line = word;
+            continue;
+        }
+        if (visibleWidth(line) + 1 + visibleWidth(word) <= width) {
+            line += ` ${word}`;
+            continue;
+        }
+        lines.push(line);
+        line = word;
+    }
+    lines.push(line);
+    return lines;
+}
+export function formatColumns(opts) {
+    const { rows } = opts;
+    if (rows.length === 0) {
+        return "";
+    }
+    const totalWidth = opts.totalWidth ?? process.stdout.columns ?? 100;
+    const minLeftWidth = opts.minLeftWidth ?? 12;
+    const maxLeftWidth = opts.maxLeftWidth ?? 32;
+    const gap = opts.gap ?? 3;
+    const indent = opts.indent ?? 2;
+    const maxLeftContentWidth = Math.max(...rows.map((row) => visibleWidth(row.left)));
+    const leftWidth = clamp(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
+    const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+    const firstIndent = " ".repeat(indent);
+    const continuationIndent = " ".repeat(indent + leftWidth);
+    return rows
+        .flatMap((row) => {
+        if (row.right.length === 0) {
+            return [`${firstIndent}${row.left}`];
+        }
+        const rightLines = wrapWords(row.right, rightWidth);
+        if (visibleWidth(row.left) > leftWidth) {
+            return [
+                `${firstIndent}${row.left}`,
+                ...rightLines.map((line) => `${continuationIndent}${line}`)
+            ];
+        }
+        const firstLine = `${firstIndent}${padEndVisible(row.left, leftWidth)}${rightLines[0]}`;
+        const continuationLines = rightLines
+            .slice(1)
+            .map((line) => `${continuationIndent}${line}`);
+        return [firstLine, ...continuationLines];
+    })
+        .join("\n");
+}
 export function formatCommand(name, description) {
-    const paddedName = name.padEnd(widths.helpColumn);
-    return `  ${text.command(paddedName)}  ${description}`;
+    return formatColumns({
+        rows: [{ left: text.command(name), right: description }]
+    });
 }
 export function formatUsage(command, args) {
     const argsStr = args ? ` ${text.argument(args)}` : "";
     return `${text.usageCommand(command)}${argsStr}`;
 }
 export function formatOption(flags, description) {
-    const paddedFlags = flags.padEnd(widths.helpColumn);
-    return `  ${text.option(paddedFlags)}  ${description}`;
+    return formatColumns({
+        rows: [{ left: text.option(flags), right: description }]
+    });
 }
 export function formatCommandList(commands) {
-    return commands.map((cmd) => formatCommand(cmd.name, cmd.description)).join("\n");
+    return formatColumns({
+        rows: commands.map((cmd) => ({
+            left: text.command(cmd.name),
+            right: cmd.description
+        }))
+    });
 }
 export function formatOptionList(options) {
-    return options.map((opt) => formatOption(opt.flags, opt.description)).join("\n");
+    return formatColumns({
+        rows: options.map((opt) => ({
+            left: text.option(opt.flags),
+            right: opt.description
+        }))
+    });
 }
 export const helpFormatter = {
+    formatColumns,
     formatCommand,
     formatUsage,
     formatOption,

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

@@ -2,8 +2,8 @@ export { text } from "./text.js";
 export { symbols } from "./symbols.js";
 export { createLogger, logger } from "./logger.js";
 export type { LoggerOutput } from "./logger.js";
-export { helpFormatter, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
-export type { CommandInfo, OptionInfo } from "./help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
+export type { CommandInfo, OptionInfo, FormatColumnsOptions } from "./help-formatter.js";
 export { formatCommandNotFound } from "./command-errors.js";
 export { formatCommandNotFoundPanel } from "./command-errors.js";
 export { renderTable } from "./table.js";

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

@@ -1,7 +1,7 @@
 export { text } from "./text.js";
 export { symbols } from "./symbols.js";
 export { createLogger, logger } from "./logger.js";
-export { helpFormatter, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
 export { formatCommandNotFound } from "./command-errors.js";
 export { formatCommandNotFoundPanel } from "./command-errors.js";
 export { renderTable } from "./table.js";

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

@@ -2,6 +2,7 @@ export declare const text: {
     readonly intro: (content: string) => string;
     readonly heading: (content: string) => string;
     readonly section: (content: string) => string;
+    readonly sectionHeader: (content: string) => string;
     readonly command: (content: string) => string;
     readonly argument: (content: string) => string;
     readonly option: (content: string) => string;

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

@@ -27,6 +27,14 @@ export const text = {
             return `**${content}**`;
         return typography.bold(content);
     },
+    sectionHeader(content) {
+        const format = resolveOutputFormat();
+        if (format === "json")
+            return content;
+        if (format === "markdown")
+            return `## ${content}`;
+        return typography.bold(content.toUpperCase());
+    },
     command(content) {
         const format = resolveOutputFormat();
         if (format === "json")

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

@@ -8,8 +8,9 @@ export { text } from "./components/text.js";
 export { symbols } from "./components/symbols.js";
 export { createLogger, logger } from "./components/logger.js";
 export type { LoggerOutput } from "./components/logger.js";
-export { helpFormatter, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
-export type { CommandInfo, OptionInfo } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
+export * as helpFormatterPlain from "./components/help-formatter-plain.js";
+export type { CommandInfo, OptionInfo, FormatColumnsOptions } from "./components/help-formatter.js";
 export { formatCommandNotFound } from "./components/command-errors.js";
 export { formatCommandNotFoundPanel } from "./components/command-errors.js";
 export { renderTable } from "./components/table.js";

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

@@ -8,7 +8,8 @@ export { widths } from "./tokens/widths.js";
 export { text } from "./components/text.js";
 export { symbols } from "./components/symbols.js";
 export { createLogger, logger } from "./components/logger.js";
-export { helpFormatter, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
+export * as helpFormatterPlain from "./components/help-formatter-plain.js";
 export { formatCommandNotFound } from "./components/command-errors.js";
 export { formatCommandNotFoundPanel } from "./components/command-errors.js";
 export { renderTable } from "./components/table.js";

package/node_modules/@poe-code/process-runner/README.md

@@ -0,0 +1,41 @@
+# @poe-code/process-runner
+
+Low-level process execution abstraction. Single interface for launching processes on the host or inside Docker containers.
+
+## Overview
+
+- No external dependencies
+- Consumed by `@poe-code/agent-spawn`
+- Consumed by `process-launcher`
+
+## Host Factory
+
+- `createHostRunner(options)` returns a `Runner` that launches commands with `node:child_process.spawn`.
+- `options.detached` starts the child as a detached process and uses process-group kill on Unix.
+- `hostExecutionEnvFactory` implements the shared execution environment contract for local host execution.
+- Host environments do not upload, download, detach, or reattach because the caller workspace is already local and there is no addressable remote environment.
+
+## Docker Factories
+
+- `createDockerRunner(options)` returns a one-shot `Runner` that executes each command in a Docker or Podman container.
+- `dockerExecutionEnvFactory` creates an addressable long-lived container environment for Poe Code runtime jobs.
+- Docker environments support workspace upload/download, command execution, interactive shell, detach, attach, and cleanup.
+
+`DockerRunnerOptions`:
+
+- `image`: container image to run.
+- `engine`: `docker` or `podman`; detected when omitted.
+- `context`: Docker context name; detected when omitted.
+- `mounts`: container mounts.
+- `ports`: port mappings.
+- `network`: Docker network.
+- `extraArgs`: additional runtime arguments.
+- `containerName`: optional container name prefix.
+
+## Environment variables
+
+This package exposes no environment variables.
+
+## Configuration
+
+This package currently exposes no package-level configuration options.

package/node_modules/@poe-code/process-runner/dist/docker/args.d.ts

@@ -0,0 +1,2 @@
+import type { DockerRunArgs } from "../types.js";
+export declare function buildDockerRunArgs(input: DockerRunArgs): string[];

package/node_modules/@poe-code/process-runner/dist/docker/args.js

@@ -0,0 +1,40 @@
+import path from "node:path";
+export function buildDockerRunArgs(input) {
+    const args = [input.engine];
+    if (input.engine === "docker" && input.context) {
+        args.push("--context", input.context);
+    }
+    args.push("run");
+    if (input.rm) {
+        args.push("--rm");
+    }
+    if (input.detached) {
+        args.push("-d");
+    }
+    if (input.interactive) {
+        args.push("-i");
+    }
+    if (input.tty) {
+        args.push("-t");
+    }
+    args.push("--name", input.containerName);
+    if (input.cwd !== undefined) {
+        args.push("-w", input.cwd);
+    }
+    for (const [key, value] of Object.entries(input.env ?? {})) {
+        args.push("-e", `${key}=${value}`);
+    }
+    for (const mount of input.mounts) {
+        const volume = `${path.resolve(mount.source)}:${mount.target}${mount.readonly ? ":ro" : ""}`;
+        args.push("-v", volume);
+    }
+    for (const port of input.ports) {
+        const mapping = `${port.host}:${port.container}${port.protocol === undefined || port.protocol === "tcp" ? "" : `/${port.protocol}`}`;
+        args.push("-p", mapping);
+    }
+    if (input.network !== undefined) {
+        args.push("--network", input.network);
+    }
+    args.push(...input.extraArgs, input.image, input.command, ...input.args);
+    return args;
+}

package/node_modules/@poe-code/process-runner/dist/docker/context.d.ts

@@ -0,0 +1,3 @@
+import type { Engine } from "../types.js";
+export declare function detectContext(): string | null;
+export declare function buildContextArgs(engine: Engine, context: string | null): string[];

package/node_modules/@poe-code/process-runner/dist/docker/context.js

@@ -0,0 +1,30 @@
+import { execSync } from "node:child_process";
+export function detectContext() {
+    try {
+        const output = execSync("colima list --json", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"]
+        });
+        const lines = output.trim().split("\n").filter(Boolean);
+        for (const line of lines) {
+            const profile = JSON.parse(line);
+            if (profile.status === "Running" && profile.runtime === "docker") {
+                const name = profile.name ?? profile.profile;
+                if (!name) {
+                    continue;
+                }
+                return name === "default" ? "colima" : `colima-${name}`;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function buildContextArgs(engine, context) {
+    if (engine === "docker" && context) {
+        return ["--context", context];
+    }
+    return [];
+}