toolcraft 0.0.11 → 0.0.12

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/task-list/README.md

@@ -4,10 +4,13 @@ Multi-list task manager with pluggable storage backends.
 
 ## Backends
 
-`@poe-code/task-list` exposes one API over two backends:
+`@poe-code/task-list` exposes one API over these backends:
 
-- `markdown-dir`: one Markdown file per task, organized into subdirectories per list
-- `yaml-file`: one YAML document with a top-level `lists:` mapping
+| Backend | Storage |
+| --- | --- |
+| `markdown-dir` | One Markdown file per task, organized into subdirectories per list. |
+| `yaml-file` | One YAML document with a top-level `lists:` mapping. |
+| `gh-issues` | GitHub Issues in one repository, ordered and state-tracked through a GitHub Project v2 Status field. |
 
 The task lifecycle is `draft -> planned -> in-progress -> done -> archived`. `archived` is terminal.
 
@@ -47,7 +50,7 @@ Pass a custom machine with `openTaskList({ stateMachine })`. If omitted, the pac
 
 | Option | Type | Default | Behavior |
 | --- | --- | --- | --- |
-| `type` | `"markdown-dir" \| "yaml-file"` | required | Selects the backend implementation. |
+| `type` | `"markdown-dir" \| "yaml-file" \| "gh-issues"` | required | Selects the backend implementation. |
 | `path` | `string` | required | Root directory for `markdown-dir` or YAML file path for `yaml-file`. |
 | `defaults` | `TaskDefaults` | `{ metadata: {} }` | Seeds omitted metadata on new tasks only. New tasks always start at the configured state machine's initial state. |
 | `create` | `boolean` | `false` | Creates missing storage for the selected backend when enabled. |
@@ -58,7 +61,9 @@ Pass a custom machine with `openTaskList({ stateMachine })`. If omitted, the pac
 
 ## Env vars
 
-None.
+| Env var | Behavior |
+| --- | --- |
+| `GH_HOST` | Defers to gh CLI's host configuration; set GH_HOST to override. |
 
 ## Usage
 
@@ -105,6 +110,36 @@ await planning.fire("review-release", "plan");
 await planning.fire("review-release", "start");
 ```
 
+### `gh-issues`
+
+```ts
+import { openTaskList } from "@poe-code/task-list";
+
+const taskList = await openTaskList({
+  type: "gh-issues",
+  repo: "octo-org/octo-repo",
+  project: {
+    owner: "octo-org",
+    number: 7
+  }
+});
+
+const project = taskList.list("octo-org/7");
+
+await taskList.lists(); // ["octo-org/7"]
+
+const created = await project.create({
+  id: "local-id-is-ignored",
+  name: "Review release checklist"
+});
+
+await project.fire(created.id, "In Progress");
+await project.move(created.id, { position: "top" });
+await project.move(created.id, { after: "42" });
+```
+
+`gh-issues` exposes one list named `${project.owner}/${project.number}`. `create()` ignores `TaskCreate.id` because GitHub assigns issue numbers. `fire(state)` writes the Project v2 `Status` field to the matching single-select option. `move()` reorders project items.
+
 ## Notes
 
 The package never overwrites existing task files or store files. `defaults.metadata` is applied only when creating new tasks and does not retroactively update existing tasks.
@@ -112,3 +147,12 @@ The package never overwrites existing task files or store files. `defaults.metad
 Task state changes are event-driven: use `fire(id, event)` to move between states, `canFire(id, event)` to check whether an event is currently legal, and `events(id)` to list the currently legal event names. There is no `transition()` API.
 
 `create()` always starts new tasks at `stateMachine.initial`. `update()` cannot change `state`; use `fire()` instead.
+
+### `gh-issues` limitations
+
+- The state machine is fetched at open and frozen for the session; re-open to refresh project Status options.
+- `archived` is not supported and returns an empty result.
+- `update()` does not write labels, assignees, or milestone in v1.
+- `moveBetweenLists()` is unsupported on `gh-issues`.
+- `id` on `TaskCreate` is ignored on this backend.
+- `gh auth token` must be available, or pass `auth: { token }`.

package/node_modules/@poe-code/task-list/dist/backends/gh-issues-client.d.ts

@@ -0,0 +1,19 @@
+import { type Runner } from "@poe-code/process-runner";
+export interface GhClientOptions {
+    token: string;
+    endpoint?: string;
+    fetch?: typeof fetch;
+}
+export interface GhClient {
+    graphql<T>(query: string, variables: Record<string, unknown>): Promise<T>;
+}
+export declare function createGhClient(options: GhClientOptions): GhClient;
+export interface ResolveAuthOptions {
+    explicitToken?: string;
+    runner?: Runner;
+}
+export declare function resolveAuth(options: ResolveAuthOptions): Promise<string>;
+export interface ResolveEndpointOptions {
+    env?: Record<string, string | undefined>;
+}
+export declare function resolveEndpoint(options?: ResolveEndpointOptions): string;