toolcraft 0.0.50 → 0.0.52

package/node_modules/@poe-code/agent-defs/README.md

@@ -0,0 +1,35 @@
+# @poe-code/agent-defs
+
+Shared catalog of supported coding-agent definitions.
+
+This package owns the declarative agent metadata used by CLI, SDK, spawn,
+configuration, and UI surfaces: stable ids, labels, aliases, config paths,
+binary names, API-shape support, OTEL capture wiring, and brand colors.
+
+## Usage
+
+```ts
+import { allAgents, normalizeAgentId, parseAgentSpecifier } from "@poe-code/agent-defs";
+
+const specifier = parseAgentSpecifier("claude:sonnet");
+const normalized = normalizeAgentId(specifier.agent);
+const codex = allAgents.find((agent) => agent.id === "codex");
+```
+
+## Public API
+
+- `allAgents`: frozen list of built-in `AgentDefinition` records.
+- `resolveAgentId(input)`: resolves ids, names, and aliases to a stable agent id.
+- `parseAgentSpecifier(input)`: parses `agent` or `agent:model` input.
+- `formatAgentSpecifier(specifier)`: formats an agent specifier.
+- `normalizeAgentId(input)`: normalizes the agent part through the registry.
+- Agent definition exports such as `codexAgent`, `claudeCodeAgent`, and `geminiCliAgent`.
+
+## Config Options
+
+This package does not load external config. Agent definitions are declared in
+source and exposed as immutable data.
+
+## Environment Variables
+
+This package does not read or expose environment variables.

package/node_modules/@poe-code/agent-human-in-loop/dist/providers/mock.js

@@ -3,9 +3,16 @@ export function mockProvider(answer) {
         id: "mock",
         async requestApproval(_request) {
             if (typeof answer === "function") {
-                return await answer();
+                return cloneApprovalResult(await answer());
             }
-            return answer;
+            return cloneApprovalResult(answer);
         },
     };
 }
+function cloneApprovalResult(result) {
+    return result.outcome === "approved"
+        ? { outcome: "approved" }
+        : result.reason === undefined
+            ? { outcome: "declined" }
+            : { outcome: "declined", reason: result.reason };
+}

package/node_modules/@poe-code/agent-human-in-loop/dist/providers/osascript-script.js

@@ -24,7 +24,9 @@ export function parseStdout(out) {
         ? out.slice(0, -2)
         : out.endsWith("\n")
             ? out.slice(0, -1)
-            : out;
+            : out.endsWith("\r")
+                ? out.slice(0, -1)
+                : out;
     switch (value) {
         case "Approve":
         case "APPROVED":

package/node_modules/@poe-code/agent-human-in-loop/dist/request-approval.js

@@ -1,4 +1,46 @@
-export function requestApproval(args) {
+export async function requestApproval(args) {
     const { provider, ...request } = args;
-    return provider.requestApproval(request);
+    return normalizeApprovalResult(await provider.requestApproval(normalizeApprovalRequest(request)));
+}
+function normalizeApprovalRequest(request) {
+    if (typeof request.message !== "string" || request.message.trim().length === 0) {
+        throw new Error("Approval request message must not be blank");
+    }
+    if (request.declineInputPrompt !== undefined &&
+        typeof request.declineInputPrompt !== "string") {
+        throw new Error("Approval request declineInputPrompt must be a string");
+    }
+    return request.declineInputPrompt === undefined
+        ? { message: request.message }
+        : {
+            message: request.message,
+            declineInputPrompt: request.declineInputPrompt,
+        };
+}
+function normalizeApprovalResult(result) {
+    if (!isObjectRecord(result)) {
+        throw new Error("Approval provider returned an invalid result");
+    }
+    const outcome = getOwnEntry(result, "outcome");
+    if (outcome === "approved") {
+        return { outcome: "approved" };
+    }
+    if (outcome === "declined") {
+        const reason = getOwnEntry(result, "reason");
+        if (reason === undefined) {
+            return { outcome: "declined" };
+        }
+        if (typeof reason === "string") {
+            return { outcome: "declined", reason };
+        }
+    }
+    throw new Error("Approval provider returned an invalid result");
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getOwnEntry(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key)
+        ? record[key]
+        : undefined;
 }

package/node_modules/@poe-code/agent-human-in-loop/package.json

@@ -20,6 +20,5 @@
   "files": [
     "dist"
   ],
-  "dependencies": {},
   "devDependencies": {}
 }

package/node_modules/@poe-code/agent-mcp-config/README.md

@@ -0,0 +1,54 @@
+# @poe-code/agent-mcp-config
+
+MCP configuration writer for supported local coding agents.
+
+This package maps a normalized MCP server entry to each agent's native config
+file, config key, file format, and shape. It is used by configure and
+unconfigure flows so caller code can stay declarative.
+
+## Usage
+
+```ts
+import { configure, unconfigure, supportedAgents } from "@poe-code/agent-mcp-config";
+
+await configure(
+  "codex",
+  {
+    name: "workspace",
+    config: { transport: "stdio", command: "node", args: ["./mcp.js"] }
+  },
+  { fs, homeDir: "/Users/me", platform: "darwin" }
+);
+
+console.log(supportedAgents);
+```
+
+## Public API
+
+- `configure(agentId, server, options)`: adds or replaces a matching MCP server entry.
+- `unconfigure(agentId, server, options)`: removes an MCP server entry.
+- `supportedAgents`: agent ids with config-file MCP support.
+- `isSupported(agentId)`: returns whether an agent has MCP config support.
+- `resolveAgentSupport(input)`: resolves aliases and returns support metadata.
+- `UnsupportedAgentError`: thrown for unsupported known agents.
+
+## Config Options
+
+`ApplyOptions` controls how mutations are applied:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `fs` | `FileSystem` | Filesystem adapter from `@poe-code/config-mutations`. |
+| `homeDir` | `string` | Home directory used to resolve `~` in agent config paths. |
+| `platform` | `"darwin" \| "linux" \| "win32"` | Selects platform-specific config paths. |
+| `dryRun` | `boolean` | Computes mutations without writing files. |
+| `observers` | `MutationObservers` | Receives mutation lifecycle events. |
+
+The package's built-in agent config table declares `configFile`, `configKey`,
+`format`, `shape`, and optional `mcpOutputFormat` per supported agent.
+
+## Environment Variables
+
+This package does not read or expose environment variables. Server-specific
+environment variables may be written into target agent config files when they
+are present in an `McpStdioServer` entry.

package/node_modules/@poe-code/agent-mcp-config/package.json

@@ -18,8 +18,6 @@
     "dist"
   ],
   "dependencies": {
-    "@poe-code/agent-defs": "*",
-    "@poe-code/config-mutations": "*",
     "yaml": "^2.8.3"
   }
 }

package/node_modules/@poe-code/config-mutations/README.md

@@ -0,0 +1,55 @@
+# @poe-code/config-mutations
+
+Composable file and config mutation engine.
+
+This package applies ordered filesystem, JSON, TOML, YAML, and template
+mutations with dry-run support and observer hooks. Callers inject the filesystem
+so tests can use in-memory adapters and production flows can use
+`node:fs/promises`.
+
+## Usage
+
+```ts
+import { configMutation, fileMutation, runMutations } from "@poe-code/config-mutations";
+
+await runMutations(
+  [
+    fileMutation.ensureDirectory({ path: "~/.config/example" }),
+    configMutation.merge({
+      target: "~/.config/example/config.json",
+      format: "json",
+      value: { enabled: true }
+    })
+  ],
+  { fs, homeDir: "/Users/me" }
+);
+```
+
+## Public API
+
+- `runMutations(mutations, context)`: applies mutations in order.
+- `configMutation`: builders for config merge, prune, and transform mutations.
+- `fileMutation`: builders for directory, file, backup, restore, and mode mutations.
+- `templateMutation`: builders for template writes and template-backed config merges.
+- `renderTemplate(template, variables)`: renders template variables.
+- Filesystem helpers: `isNotFound`, `readFileIfExists`, `pathExists`, and `createTimestamp`.
+
+## Config Options
+
+`MutationContext` controls execution:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `fs` | `FileSystem` | Required filesystem adapter. |
+| `homeDir` | `string` | Required home directory for `~` expansion. |
+| `dryRun` | `boolean` | Reports changes without writing them. |
+| `observers` | `MutationObservers` | Receives mutation lifecycle events. |
+| `templates` | `TemplateLoader` | Loads templates referenced by template mutations. |
+| `pathMapper` | `PathMapper` | Redirects target directories for isolated config flows. |
+
+Mutation builders also expose per-mutation options such as target path, format,
+label, force removal, backup behavior, template id, and transform callbacks.
+
+## Environment Variables
+
+This package does not read or expose environment variables.

package/node_modules/@poe-code/config-mutations/dist/execution/apply-mutation.d.ts

@@ -1,4 +1,5 @@
 import type { Mutation, MutationContext, MutationOutcome, MutationDetails, MutationOptions } from "../types.js";
+export declare function resolveMutationDetails(mutation: Mutation, context: MutationContext, options: MutationOptions): MutationDetails;
 export declare function applyMutation(mutation: Mutation, context: MutationContext, options: MutationOptions): Promise<{
     outcome: MutationOutcome;
     details: MutationDetails;

package/node_modules/@poe-code/config-mutations/dist/execution/apply-mutation.js

@@ -126,6 +126,58 @@ function describeMutation(kind, targetPath) {
             return "Operation";
     }
 }
+function mutationTargetPath(mutation, options) {
+    switch (mutation.kind) {
+        case "ensureDirectory":
+        case "removeDirectory":
+            return resolveValue(mutation.path, options);
+        case "removeFile":
+        case "chmod":
+        case "backup":
+        case "restoreBackup":
+        case "configMerge":
+        case "configPrune":
+        case "configTransform":
+        case "templateWrite":
+        case "templateMergeToml":
+        case "templateMergeJson":
+            return resolveValue(mutation.target, options);
+        default:
+            return undefined;
+    }
+}
+export function resolveMutationDetails(mutation, context, options) {
+    try {
+        const rawTarget = mutationTargetPath(mutation, options);
+        if (rawTarget === undefined) {
+            return {
+                kind: mutation.kind,
+                label: mutation.label ?? mutation.kind
+            };
+        }
+        try {
+            const targetPath = resolvePath(rawTarget, context.homeDir, context.pathMapper);
+            return {
+                kind: mutation.kind,
+                label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+                targetPath
+            };
+        }
+        catch {
+            return {
+                kind: mutation.kind,
+                label: mutation.label ?? describeMutation(mutation.kind, rawTarget),
+                targetPath: undefined
+            };
+        }
+    }
+    catch {
+        return {
+            kind: mutation.kind,
+            label: mutation.label ?? mutation.kind
+        };
+    }
+}
 function pruneKeysByPrefix(table, prefix) {
     const result = {};
     for (const [key, value] of Object.entries(table)) {
@@ -223,6 +275,7 @@ async function applyEnsureDirectory(mutation, context, options) {
         label: mutation.label ?? describeMutation(mutation.kind, targetPath),
         targetPath
     };
+    await assertRegularWriteTarget(context, targetPath);
     const existed = await pathExists(context.fs, targetPath);
     if (!context.dryRun) {
         await context.fs.mkdir(targetPath, { recursive: true });
@@ -342,6 +395,7 @@ async function applyChmod(mutation, context, options) {
         };
     }
     try {
+        await assertRegularWriteTarget(context, targetPath);
         const stat = await context.fs.stat(targetPath);
         const currentMode = typeof stat.mode === "number" ? stat.mode & 0o777 : null;
         if (currentMode === mutation.mode) {
@@ -376,6 +430,7 @@ async function applyBackup(mutation, context, options) {
         label: mutation.label ?? describeMutation(mutation.kind, targetPath),
         targetPath
     };
+    await assertRegularWriteTarget(context, targetPath);
     if (mutation.once && (await findLatestGeneratedBackup(context.fs, targetPath)) !== null) {
         return {
             outcome: { changed: false, effect: "none", detail: "noop" },
@@ -524,6 +579,9 @@ async function applyConfigMerge(mutation, context, options) {
         preserveContent = null;
     }
     const value = resolveValue(mutation.value, options);
+    if (!isConfigObject(value)) {
+        throw new Error(`configMerge value must be an object for "${rawPath}".`);
+    }
     // Keep prefix pruning on the same proto-safe object-write path as normal merges.
     let merged;
     if (mutation.pruneByPrefix) {
@@ -661,6 +719,13 @@ async function applyConfigTransform(mutation, context, options) {
         };
     }
     const serialized = serializeConfigUpdate(format, preserveContent, current, transformed);
+    const serializedChanged = serialized !== rawContent;
+    if (!serializedChanged) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
     if (!context.dryRun) {
         await writeAtomically(context, targetPath, serialized);
     }

package/node_modules/@poe-code/config-mutations/dist/execution/run-mutations.js

@@ -1,4 +1,4 @@
-import { applyMutation } from "./apply-mutation.js";
+import { applyMutation, resolveMutationDetails } from "./apply-mutation.js";
 /**
  * Execute an array of mutations in order.
  *
@@ -21,12 +21,9 @@ export async function runMutations(mutations, context, options) {
     };
 }
 async function executeMutation(mutation, context, options) {
+    const pendingDetails = resolveMutationDetails(mutation, context, options);
     // Call onStart observer
-    context.observers?.onStart?.({
-        kind: mutation.kind,
-        label: mutation.label ?? mutation.kind,
-        targetPath: undefined // Will be resolved during apply
-    });
+    context.observers?.onStart?.(pendingDetails);
     try {
         const { outcome, details } = await applyMutation(mutation, context, options);
         // Call onComplete observer
@@ -35,11 +32,7 @@ async function executeMutation(mutation, context, options) {
     }
     catch (error) {
         // Call onError observer
-        context.observers?.onError?.({
-            kind: mutation.kind,
-            label: mutation.label ?? mutation.kind,
-            targetPath: undefined
-        }, error);
+        context.observers?.onError?.(pendingDetails, error);
         // Re-throw the error
         throw error;
     }

package/node_modules/@poe-code/config-mutations/package.json

@@ -22,7 +22,6 @@
     "dist"
   ],
   "dependencies": {
-    "toolcraft-design": "*",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.3.0",
     "yaml": "^2.8.1"

package/node_modules/@poe-code/frontmatter/dist/fences.d.ts

@@ -1,8 +1,25 @@
 export type FrontmatterBlock = {
     raw: string;
     body: string;
+    rawStart: number;
+    rawEnd: number;
 };
 export type SplitFrontmatterResult = FrontmatterBlock | {
     body: string;
 };
+export type InspectFrontmatterResult = (FrontmatterBlock & {
+    kind: "frontmatter";
+}) | {
+    kind: "missing-closing-fence";
+    raw: string;
+    rawStart: number;
+    rawEnd: number;
+    body: "";
+    message: string;
+    position: number;
+} | {
+    kind: "body";
+    body: string;
+};
 export declare function splitFrontmatterBlock(source: string): SplitFrontmatterResult;
+export declare function inspectFrontmatterBlock(source: string): InspectFrontmatterResult;

package/node_modules/@poe-code/frontmatter/dist/fences.js

@@ -1,15 +1,43 @@
+const MISSING_END_DELIMITER_MESSAGE = "Missing YAML frontmatter end delimiter (---).";
 export function splitFrontmatterBlock(source) {
+    const inspected = inspectFrontmatterBlock(source);
+    if (inspected.kind === "body") {
+        return { body: inspected.body };
+    }
+    if (inspected.kind === "missing-closing-fence") {
+        throw new Error(inspected.message);
+    }
+    return {
+        raw: inspected.raw,
+        rawStart: inspected.rawStart,
+        rawEnd: inspected.rawEnd,
+        body: inspected.body
+    };
+}
+export function inspectFrontmatterBlock(source) {
     const content = source.startsWith("\uFEFF") ? source.slice(1) : source;
+    const sourceOffset = source.length - content.length;
     const opening = readOpeningFence(content);
     if (opening === undefined) {
-        return { body: source };
+        return { kind: "body", body: source };
     }
     const closing = findClosingFence(content, opening.next);
     if (closing === undefined) {
-        throw new Error("Missing YAML frontmatter end delimiter (---).");
+        return {
+            kind: "missing-closing-fence",
+            raw: content.slice(opening.next),
+            rawStart: sourceOffset + opening.next,
+            rawEnd: source.length,
+            body: "",
+            message: MISSING_END_DELIMITER_MESSAGE,
+            position: source.length
+        };
     }
     return {
+        kind: "frontmatter",
         raw: content.slice(opening.next, closing.index),
+        rawStart: sourceOffset + opening.next,
+        rawEnd: sourceOffset + closing.index,
         body: content.slice(closing.end + closing.lineBreakLength)
     };
 }
@@ -18,7 +46,7 @@ function readOpeningFence(source) {
         return undefined;
     }
     const lineEnd = findLineEnd(source, 0);
-    if (lineEnd.lineBreakLength === 0 || source.slice(0, lineEnd.index) !== "---") {
+    if (lineEnd.lineBreakLength === 0 || !isFenceLine(source.slice(0, lineEnd.index))) {
         return undefined;
     }
     return { next: lineEnd.index + lineEnd.lineBreakLength };
@@ -27,7 +55,7 @@ function findClosingFence(source, start) {
     let lineStart = start;
     while (lineStart <= source.length) {
         const lineEnd = findLineEnd(source, lineStart);
-        if (isClosingFenceLine(source.slice(lineStart, lineEnd.index))) {
+        if (isFenceLine(source.slice(lineStart, lineEnd.index))) {
             return {
                 index: lineStart,
                 end: lineEnd.index,
@@ -41,7 +69,7 @@ function findClosingFence(source, start) {
     }
     return undefined;
 }
-function isClosingFenceLine(line) {
+function isFenceLine(line) {
     if (!line.startsWith("---")) {
         return false;
     }

package/node_modules/@poe-code/frontmatter/dist/parse.js

@@ -1,5 +1,5 @@
 import { LineCounter, parse, parseDocument } from "yaml";
-import { splitFrontmatterBlock } from "./fences.js";
+import { inspectFrontmatterBlock, splitFrontmatterBlock } from "./fences.js";
 export class FrontmatterParseError extends Error {
     constructor(message) {
         super(message);
@@ -20,9 +20,9 @@ export function parseFrontmatter(source, options = {}) {
     };
 }
 export function parseFrontmatterDocument(source, options = {}) {
-    const split = splitFrontmatter(source);
-    const lineCounter = new LineCounter();
-    if (split.raw === undefined) {
+    const split = inspectFrontmatterBlock(source);
+    const lineCounter = createSourceLineCounter(source);
+    if (split.kind === "body") {
         return {
             frontmatter: {},
             body: split.body,
@@ -30,14 +30,26 @@ export function parseFrontmatterDocument(source, options = {}) {
             lineCounter
         };
     }
-    const document = parseDocument(normalizeYamlLineEndings(split.raw), {
-        lineCounter,
+    if (split.kind === "missing-closing-fence") {
+        return {
+            frontmatter: {},
+            body: split.body,
+            errors: [{ message: split.message, pos: [split.position, split.position] }],
+            lineCounter
+        };
+    }
+    const yamlLineCounter = new LineCounter();
+    const normalizedYaml = normalizeYamlLineEndings(split.raw);
+    const document = parseDocument(normalizedYaml, {
+        lineCounter: yamlLineCounter,
         prettyErrors: false,
         uniqueKeys: options.uniqueKeys ?? false
     });
     const errors = document.errors.map((error) => ({
         message: error.message,
-        ...(error.pos === undefined ? {} : { pos: error.pos })
+        ...(error.pos === undefined
+            ? {}
+            : { pos: translateYamlErrorPosition(error.pos, split) })
     }));
     if (errors.length > 0) {
         return {
@@ -47,12 +59,72 @@ export function parseFrontmatterDocument(source, options = {}) {
             lineCounter
         };
     }
-    return {
-        frontmatter: normalizeYamlFrontmatter(document.toJSON()),
-        body: split.body,
-        errors,
-        lineCounter
-    };
+    try {
+        return {
+            frontmatter: normalizeYamlFrontmatter(document.toJSON()),
+            body: split.body,
+            errors,
+            lineCounter
+        };
+    }
+    catch (error) {
+        if (error instanceof FrontmatterParseError) {
+            return {
+                frontmatter: {},
+                body: split.body,
+                errors: [{ message: error.message }],
+                lineCounter
+            };
+        }
+        throw error;
+    }
+}
+function createSourceLineCounter(source) {
+    const lineCounter = new LineCounter();
+    lineCounter.addNewLine(0);
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source[index];
+        if (character === "\n") {
+            lineCounter.addNewLine(index + 1);
+            continue;
+        }
+        if (character === "\r") {
+            lineCounter.addNewLine(index + (source[index + 1] === "\n" ? 2 : 1));
+            if (source[index + 1] === "\n") {
+                index += 1;
+            }
+        }
+    }
+    return lineCounter;
+}
+function translateYamlErrorPosition(pos, split) {
+    return pos.map((offset) => split.rawStart + normalizeYamlErrorOffset(split.raw, offset));
+}
+function normalizeYamlErrorOffset(raw, offset) {
+    if (offset >= raw.length && endsWithLineBreak(raw)) {
+        return findPreviousLineStart(raw, raw.length);
+    }
+    return offset;
+}
+function endsWithLineBreak(value) {
+    return value.endsWith("\n") || value.endsWith("\r");
+}
+function findPreviousLineStart(value, end) {
+    let index = end - 1;
+    if (value[index] === "\n") {
+        index -= 1;
+    }
+    if (value[index] === "\r") {
+        index -= 1;
+    }
+    while (index >= 0) {
+        const character = value[index];
+        if (character === "\n" || character === "\r") {
+            return index + 1;
+        }
+        index -= 1;
+    }
+    return 0;
 }
 function splitFrontmatter(source) {
     try {
@@ -102,7 +174,7 @@ function normalizeYamlFrontmatter(value) {
     if (value === null || value === undefined) {
         return {};
     }
-    if (!isRecord(value)) {
+    if (!isPlainRecord(value)) {
         throw new FrontmatterParseError("YAML frontmatter must parse to an object.");
     }
     return normalizeYamlValue(value);

package/node_modules/@poe-code/frontmatter/dist/stringify.js

@@ -2,6 +2,7 @@ import { stringify } from "yaml";
 import { FrontmatterParseError } from "./parse.js";
 export function stringifyFrontmatter(frontmatter, body) {
     try {
+        assertFrontmatterRoot(frontmatter);
         assertAcyclic(frontmatter);
         return `---\n${stringify(frontmatter, { aliasDuplicateObjects: false }).trimEnd()}\n---\n${body}`;
     }
@@ -13,6 +14,11 @@ export function stringifyFrontmatter(frontmatter, body) {
         throw new FrontmatterParseError(`Invalid YAML frontmatter: ${message}`);
     }
 }
+function assertFrontmatterRoot(value) {
+    if (!isPlainRecord(value)) {
+        throw new FrontmatterParseError("YAML frontmatter must parse to an object.");
+    }
+}
 function assertAcyclic(value, seen = new WeakSet()) {
     if (typeof value !== "object" || value === null) {
         return;
@@ -33,3 +39,10 @@ function assertAcyclic(value, seen = new WeakSet()) {
     }
     seen.delete(value);
 }
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}