toolcraft 0.0.5 → 0.0.7

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

@@ -0,0 +1,32 @@
+function write(options) {
+    return {
+        kind: "templateWrite",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+function mergeToml(options) {
+    return {
+        kind: "templateMergeToml",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+function mergeJson(options) {
+    return {
+        kind: "templateMergeJson",
+        target: options.target,
+        templateId: options.templateId,
+        context: options.context,
+        label: options.label
+    };
+}
+export const templateMutation = {
+    write,
+    mergeToml,
+    mergeJson
+};

package/node_modules/@poe-code/config-mutations/dist/template/render.d.ts

@@ -0,0 +1,7 @@
+export type TemplateVariables = Record<string, string | number | boolean | string[]>;
+/**
+ * Render a mustache template with the given variables.
+ * Arrays are automatically joined with newlines.
+ * HTML escaping is disabled.
+ */
+export declare function renderTemplate(template: string, variables: TemplateVariables): string;

package/node_modules/@poe-code/config-mutations/dist/template/render.js

@@ -0,0 +1,28 @@
+import Mustache from "mustache";
+// Disable HTML escaping - we're rendering prompts, not HTML
+const originalEscape = Mustache.escape;
+/**
+ * Render a mustache template with the given variables.
+ * Arrays are automatically joined with newlines.
+ * HTML escaping is disabled.
+ */
+export function renderTemplate(template, variables) {
+    // Pre-process variables to handle arrays
+    const processed = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (Array.isArray(value)) {
+            processed[key] = value.join("\n");
+        }
+        else {
+            processed[key] = value;
+        }
+    }
+    // Temporarily disable HTML escaping
+    Mustache.escape = (text) => text;
+    try {
+        return Mustache.render(template, processed);
+    }
+    finally {
+        Mustache.escape = originalEscape;
+    }
+}

package/node_modules/@poe-code/config-mutations/dist/testing/format-utils.d.ts

@@ -0,0 +1,7 @@
+import type { ConfigObject } from "../types.js";
+export declare function parseToml(content: string): ConfigObject;
+export declare function serializeToml(obj: ConfigObject): string;
+export declare function parseJson(content: string): ConfigObject;
+export declare function serializeJson(obj: ConfigObject): string;
+export declare function parseYaml(content: string): ConfigObject;
+export declare function serializeYaml(obj: ConfigObject): string;

package/node_modules/@poe-code/config-mutations/dist/testing/format-utils.js

@@ -0,0 +1,21 @@
+import { jsonFormat } from "../formats/json.js";
+import { tomlFormat } from "../formats/toml.js";
+import { yamlFormat } from "../formats/yaml.js";
+export function parseToml(content) {
+    return tomlFormat.parse(content);
+}
+export function serializeToml(obj) {
+    return tomlFormat.serialize(obj);
+}
+export function parseJson(content) {
+    return jsonFormat.parse(content);
+}
+export function serializeJson(obj) {
+    return jsonFormat.serialize(obj);
+}
+export function parseYaml(content) {
+    return yamlFormat.parse(content);
+}
+export function serializeYaml(obj) {
+    return yamlFormat.serialize(obj);
+}

package/node_modules/@poe-code/config-mutations/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+export { createMockFs } from "./mock-fs.js";
+export type { MockFileSystem } from "./mock-fs.js";
+export { parseToml, serializeToml, parseJson, serializeJson, parseYaml, serializeYaml } from "./format-utils.js";

package/node_modules/@poe-code/config-mutations/dist/testing/index.js

@@ -0,0 +1,2 @@
+export { createMockFs } from "./mock-fs.js";
+export { parseToml, serializeToml, parseJson, serializeJson, parseYaml, serializeYaml } from "./format-utils.js";

package/node_modules/@poe-code/config-mutations/dist/testing/mock-fs.d.ts

@@ -0,0 +1,25 @@
+import type { FileSystem } from "../types.js";
+export interface MockFileSystem extends FileSystem {
+    /** Current file contents, keyed by absolute path */
+    files: Record<string, string>;
+    /** Created directories */
+    directories: Set<string>;
+    /** Check if a path exists (file or directory) */
+    exists(path: string): boolean;
+    /** Get file content or undefined if not found */
+    getContent(path: string): string | undefined;
+    /** Read file with encoding overloads for compatibility */
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    readFile(path: string): Promise<Buffer>;
+}
+export interface MockFsOptions {
+    /** Initial files - paths can use ~ which will be expanded to homeDir */
+    [path: string]: string;
+}
+/**
+ * Create an in-memory mock filesystem for testing mutations.
+ *
+ * @param initialFiles - Initial files to populate the filesystem with
+ * @param homeDir - Home directory for ~ expansion (defaults to /home/test)
+ */
+export declare function createMockFs(initialFiles?: MockFsOptions, homeDir?: string): MockFileSystem;

package/node_modules/@poe-code/config-mutations/dist/testing/mock-fs.js

@@ -0,0 +1,170 @@
+import path from "node:path";
+const DEFAULT_HOME_DIR = "/home/test";
+/**
+ * Create an in-memory mock filesystem for testing mutations.
+ *
+ * @param initialFiles - Initial files to populate the filesystem with
+ * @param homeDir - Home directory for ~ expansion (defaults to /home/test)
+ */
+export function createMockFs(initialFiles, homeDir = DEFAULT_HOME_DIR) {
+    const files = {};
+    const directories = new Set();
+    // Initialize with provided files
+    if (initialFiles) {
+        for (const [filePath, content] of Object.entries(initialFiles)) {
+            const absolutePath = expandPath(filePath, homeDir);
+            files[absolutePath] = content;
+            // Ensure parent directories exist
+            const parentDir = path.dirname(absolutePath);
+            addDirectoryTree(parentDir, directories);
+        }
+    }
+    // Ensure home directory exists
+    addDirectoryTree(homeDir, directories);
+    const mockFs = {
+        files,
+        directories,
+        exists(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            return absolutePath in files || directories.has(absolutePath);
+        },
+        getContent(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            return files[absolutePath];
+        },
+        async readFile(filePath, encoding) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files)) {
+                const error = new Error(`ENOENT: no such file or directory, open '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            const content = files[absolutePath];
+            if (encoding) {
+                return content;
+            }
+            return Buffer.from(content, "utf8");
+        },
+        async writeFile(filePath, content, options) {
+            void options; // TypeScript satisfaction
+            const absolutePath = expandPath(filePath, homeDir);
+            // Ensure parent directory exists
+            const parentDir = path.dirname(absolutePath);
+            if (!directories.has(parentDir)) {
+                const error = new Error(`ENOENT: no such file or directory, open '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            if (typeof content === "string") {
+                files[absolutePath] = content;
+            }
+            else if (Buffer.isBuffer(content)) {
+                files[absolutePath] = content.toString("utf8");
+            }
+            else {
+                files[absolutePath] = Buffer.from(content.buffer, content.byteOffset, content.byteLength).toString("utf8");
+            }
+        },
+        async mkdir(dirPath, options) {
+            const absolutePath = expandPath(dirPath, homeDir);
+            if (options?.recursive) {
+                addDirectoryTree(absolutePath, directories);
+            }
+            else {
+                // Check parent exists
+                const parentDir = path.dirname(absolutePath);
+                if (parentDir !== absolutePath && !directories.has(parentDir)) {
+                    const error = new Error(`ENOENT: no such file or directory, mkdir '${absolutePath}'`);
+                    error.code = "ENOENT";
+                    throw error;
+                }
+                directories.add(absolutePath);
+            }
+        },
+        async unlink(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files)) {
+                const error = new Error(`ENOENT: no such file or directory, unlink '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            delete files[absolutePath];
+        },
+        async stat(filePath) {
+            const absolutePath = expandPath(filePath, homeDir);
+            if (absolutePath in files) {
+                return { mode: 0o644 };
+            }
+            if (directories.has(absolutePath)) {
+                return { mode: 0o755 };
+            }
+            const error = new Error(`ENOENT: no such file or directory, stat '${absolutePath}'`);
+            error.code = "ENOENT";
+            throw error;
+        },
+        async readdir(dirPath) {
+            const absolutePath = expandPath(dirPath, homeDir);
+            if (absolutePath in files) {
+                const error = new Error(`ENOTDIR: not a directory, scandir '${absolutePath}'`);
+                error.code = "ENOTDIR";
+                throw error;
+            }
+            if (!directories.has(absolutePath)) {
+                const error = new Error(`ENOENT: no such file or directory, scandir '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            const entries = new Set();
+            for (const filePath of Object.keys(files)) {
+                if (path.dirname(filePath) === absolutePath) {
+                    entries.add(path.basename(filePath));
+                }
+            }
+            for (const dir of directories) {
+                if (dir !== absolutePath && path.dirname(dir) === absolutePath) {
+                    entries.add(path.basename(dir));
+                }
+            }
+            return Array.from(entries);
+        },
+        async chmod(filePath, mode) {
+            void mode; // In mock fs, we don't actually store mode changes
+            const absolutePath = expandPath(filePath, homeDir);
+            if (!(absolutePath in files) && !directories.has(absolutePath)) {
+                const error = new Error(`ENOENT: no such file or directory, chmod '${absolutePath}'`);
+                error.code = "ENOENT";
+                throw error;
+            }
+            // Mode change is a no-op in mock fs but we don't throw
+        }
+    };
+    return mockFs;
+}
+/**
+ * Expand ~ to homeDir in a path.
+ */
+function expandPath(inputPath, homeDir) {
+    if (inputPath.startsWith("~/")) {
+        return path.join(homeDir, inputPath.slice(2));
+    }
+    if (inputPath === "~") {
+        return homeDir;
+    }
+    if (inputPath.startsWith("~")) {
+        // ~something (not ~/) - treat as relative path from home
+        return path.join(homeDir, inputPath.slice(1));
+    }
+    return inputPath;
+}
+/**
+ * Add a directory and all its parent directories to the set.
+ */
+function addDirectoryTree(dirPath, directories) {
+    const parts = dirPath.split(path.sep).filter(Boolean);
+    let current = "/";
+    directories.add(current);
+    for (const part of parts) {
+        current = path.join(current, part);
+        directories.add(current);
+    }
+}

package/node_modules/@poe-code/config-mutations/dist/types.d.ts

@@ -0,0 +1,156 @@
+export type ConfigPrimitive = string | number | boolean | null;
+export type ConfigValue = ConfigPrimitive | ConfigObject | ConfigArray | Date;
+export interface ConfigObject {
+    [key: string]: ConfigValue;
+}
+export type ConfigArray = ConfigValue[];
+export declare function isConfigObject(value: unknown): value is ConfigObject;
+export interface FileSystem {
+    readFile(path: string, encoding: "utf8"): Promise<string>;
+    writeFile(path: string, content: string, options?: {
+        encoding: "utf8";
+    }): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive: boolean;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rm?(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readdir(path: string): Promise<string[]>;
+    chmod?(path: string, mode: number): Promise<void>;
+}
+export type TemplateLoader = (templateId: string) => Promise<string>;
+export interface ConfigFormat {
+    /** Parse string content into object */
+    parse(content: string): ConfigObject;
+    /** Serialize object to string (with consistent formatting) */
+    serialize(obj: ConfigObject): string;
+    /** Deep merge patch into base, returning new object */
+    merge(base: ConfigObject, patch: ConfigObject): ConfigObject;
+    /** Remove keys matching shape from object, returning new object */
+    prune(obj: ConfigObject, shape: ConfigObject): {
+        changed: boolean;
+        result: ConfigObject;
+    };
+}
+export interface PathMapper {
+    /** Map a target directory to a different location (e.g., for isolated configs) */
+    mapTargetDirectory(input: {
+        targetDirectory: string;
+    }): string;
+}
+export interface MutationContext {
+    /** Filesystem interface - required */
+    fs: FileSystem;
+    /** Home directory for ~ expansion - required */
+    homeDir: string;
+    /** Optional dry-run mode */
+    dryRun?: boolean;
+    /** Optional observers for logging */
+    observers?: MutationObservers;
+    /** Required for template mutations */
+    templates?: TemplateLoader;
+    /** Optional path mapper for redirecting paths (used for isolated configs) */
+    pathMapper?: PathMapper;
+}
+export interface MutationOptions {
+    [key: string]: unknown;
+}
+export type ValueResolver<T> = T | ((ctx: MutationOptions) => T);
+interface BaseMutation {
+    /** Human-readable label for logging */
+    label?: string;
+}
+export interface ConfigMergeMutation extends BaseMutation {
+    kind: "configMerge";
+    target: ValueResolver<string>;
+    value: ValueResolver<ConfigObject>;
+    format?: "json" | "toml" | "yaml";
+    pruneByPrefix?: Record<string, string>;
+}
+export interface ConfigPruneMutation extends BaseMutation {
+    kind: "configPrune";
+    target: ValueResolver<string>;
+    shape: ValueResolver<ConfigObject>;
+    format?: "json" | "toml" | "yaml";
+    onlyIf?: (doc: ConfigObject, ctx: MutationOptions) => boolean;
+}
+export interface ConfigTransformMutation extends BaseMutation {
+    kind: "configTransform";
+    target: ValueResolver<string>;
+    format?: "json" | "toml" | "yaml";
+    transform: (content: ConfigObject, ctx: MutationOptions) => {
+        content: ConfigObject | null;
+        changed: boolean;
+    };
+}
+export interface EnsureDirectoryMutation extends BaseMutation {
+    kind: "ensureDirectory";
+    path: ValueResolver<string>;
+}
+export interface RemoveDirectoryMutation extends BaseMutation {
+    kind: "removeDirectory";
+    path: ValueResolver<string>;
+    force?: boolean;
+}
+export interface RemoveFileMutation extends BaseMutation {
+    kind: "removeFile";
+    target: ValueResolver<string>;
+    whenEmpty?: boolean;
+    whenContentMatches?: RegExp;
+}
+export interface ChmodMutation extends BaseMutation {
+    kind: "chmod";
+    target: ValueResolver<string>;
+    mode: number;
+}
+export interface BackupMutation extends BaseMutation {
+    kind: "backup";
+    target: ValueResolver<string>;
+}
+export interface TemplateWriteMutation extends BaseMutation {
+    kind: "templateWrite";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export interface TemplateMergeTomlMutation extends BaseMutation {
+    kind: "templateMergeToml";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export interface TemplateMergeJsonMutation extends BaseMutation {
+    kind: "templateMergeJson";
+    target: ValueResolver<string>;
+    templateId: string;
+    context?: ValueResolver<ConfigObject>;
+}
+export type Mutation = ConfigMergeMutation | ConfigPruneMutation | ConfigTransformMutation | EnsureDirectoryMutation | RemoveDirectoryMutation | RemoveFileMutation | ChmodMutation | BackupMutation | TemplateWriteMutation | TemplateMergeTomlMutation | TemplateMergeJsonMutation;
+export type MutationEffect = "none" | "mkdir" | "write" | "delete" | "chmod" | "copy";
+export type MutationDetail = "create" | "update" | "delete" | "noop" | "backup";
+export interface MutationOutcome {
+    changed: boolean;
+    effect: MutationEffect;
+    detail?: MutationDetail;
+}
+export interface MutationDetails {
+    kind: string;
+    label: string;
+    targetPath?: string;
+}
+export interface MutationObservers {
+    onStart?(details: MutationDetails): void;
+    onComplete?(details: MutationDetails, outcome: MutationOutcome): void;
+    onError?(details: MutationDetails, error: unknown): void;
+}
+export interface MutationResult {
+    changed: boolean;
+    effects: MutationOutcome[];
+}
+export {};

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

@@ -0,0 +1,6 @@
+// ============================================================================
+// Config Object Types
+// ============================================================================
+export function isConfigObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,33 @@
+{
+  "name": "@poe-code/config-mutations",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "mustache": "^4.2.0",
+    "smol-toml": "^1.3.0",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/mustache": "^4.2.6"
+  }
+}

package/node_modules/@poe-code/file-lock/README.md

@@ -0,0 +1,52 @@
+# @poe-code/file-lock
+
+Atomic file locking built on lockfile creation with `open(..., "wx")` and timestamped stale cleanup.
+
+It creates a sibling lockfile at `<filePath>.lock`, retries with bounded backoff when the lock is already held, and automatically reclaims stale locks. Locks from the current host are reclaimed immediately when their recorded process is no longer running; other locks fall back to the lockfile timestamp and `staleMs`.
+
+## Public API
+
+### `acquireFileLock(filePath, options?)`
+
+```ts
+function acquireFileLock(
+  filePath: string,
+  options?: FileLockOptions
+): Promise<ReleaseLock>;
+```
+
+Attempts to acquire an exclusive lock for `filePath` and resolves to an async release function. If the lock already exists, acquisition retries until it succeeds, the lock is considered stale and cleaned up, the provided abort signal fires, or retries are exhausted. When retries are exhausted, it throws `LockTimeoutError`.
+
+## Options
+
+| Option | Type | Default | Behavior |
+| --- | --- | --- | --- |
+| `staleMs` | `number` | `1_000` | Lockfile age in milliseconds after which an existing lock is treated as stale and removed when live local PID metadata does not prove the owner is still running. |
+| `retries` | `number` | `20` | Number of retry attempts after the initial acquire attempt. |
+| `minTimeout` | `number` | `25` | Minimum retry backoff in milliseconds. |
+| `maxTimeout` | `number` | `250` | Maximum retry backoff in milliseconds. |
+| `isPidRunning` | `(pid: number) => boolean` | `process.kill(pid, 0)` check | Injectable process liveness check used to reclaim dead local lock owners. |
+| `signal` | `AbortSignal` | none | Cancels acquisition while waiting between retries and rejects with an abort error. |
+| `fs` | `FileLockFs` | `node:fs/promises` adapter | Injectable filesystem used for lock creation, metadata reading, inspection, and deletion. |
+
+## Env vars
+
+None.
+
+## Usage
+
+```ts
+import { acquireFileLock } from "@poe-code/file-lock";
+
+const release = await acquireFileLock("/repo/workflow.md");
+
+try {
+  // Do work while holding the lock.
+} finally {
+  await release();
+}
+```
+
+## Notes
+
+`@poe-code/agent-harness-tools` re-exports `acquireFileLock` as `lockWorkflow`.

package/node_modules/@poe-code/file-lock/dist/index.d.ts

@@ -0,0 +1 @@
+export { acquireFileLock, LockTimeoutError, type FileLockFs, type FileLockOptions, type ReleaseLock } from "./lock.js";

package/node_modules/@poe-code/file-lock/dist/index.js

@@ -0,0 +1 @@
+export { acquireFileLock, LockTimeoutError } from "./lock.js";

package/node_modules/@poe-code/file-lock/dist/lock.d.ts

@@ -0,0 +1,27 @@
+export interface FileLockFs {
+    open(path: string, flags: string): Promise<{
+        close(): Promise<void>;
+        writeFile(data: string, options?: BufferEncoding | {
+            encoding?: BufferEncoding;
+        }): Promise<void>;
+    }>;
+    stat(path: string): Promise<{
+        mtimeMs: number;
+    }>;
+    readFile?(path: string, encoding: BufferEncoding): Promise<string>;
+    unlink(path: string): Promise<void>;
+}
+export interface FileLockOptions {
+    staleMs?: number;
+    retries?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    fs?: FileLockFs;
+    isPidRunning?: (pid: number) => boolean;
+    signal?: AbortSignal;
+}
+export type ReleaseLock = () => Promise<void>;
+export declare class LockTimeoutError extends Error {
+    constructor(message: string);
+}
+export declare function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<ReleaseLock>;