toolcraft 0.0.5 → 0.0.7

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

@@ -0,0 +1,552 @@
+import Mustache from "mustache";
+import { getConfigFormat, detectFormat } from "../formats/index.js";
+import { resolvePath } from "./path-utils.js";
+import { isNotFound, readFileIfExists, pathExists, createTimestamp } from "../fs-utils.js";
+// ============================================================================
+// Helper Functions
+// ============================================================================
+function resolveValue(resolver, options) {
+    if (typeof resolver === "function") {
+        return resolver(options);
+    }
+    return resolver;
+}
+function createInvalidDocumentBackupPath(targetPath) {
+    const ext = targetPath.includes(".") ? targetPath.split(".").pop() : "bak";
+    return `${targetPath}.invalid-${createTimestamp()}.${ext}`;
+}
+async function backupInvalidDocument(fs, targetPath, content) {
+    const backupPath = createInvalidDocumentBackupPath(targetPath);
+    await fs.writeFile(backupPath, content, { encoding: "utf8" });
+}
+function describeMutation(kind, targetPath) {
+    const displayPath = targetPath ?? "target";
+    switch (kind) {
+        case "ensureDirectory":
+            return `Create ${displayPath}`;
+        case "removeDirectory":
+            return `Remove directory ${displayPath}`;
+        case "backup":
+            return `Backup ${displayPath}`;
+        case "templateWrite":
+            return `Write ${displayPath}`;
+        case "chmod":
+            return `Set permissions on ${displayPath}`;
+        case "removeFile":
+            return `Remove ${displayPath}`;
+        case "configMerge":
+        case "configPrune":
+        case "configTransform":
+        case "templateMergeToml":
+        case "templateMergeJson":
+            return `Update ${displayPath}`;
+        default:
+            return "Operation";
+    }
+}
+function pruneKeysByPrefix(table, prefix) {
+    const result = {};
+    for (const [key, value] of Object.entries(table)) {
+        if (!key.startsWith(prefix)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function isConfigObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeWithPruneByPrefix(base, patch, pruneByPrefix) {
+    const result = { ...base };
+    const prefixMap = pruneByPrefix ?? {};
+    for (const [key, value] of Object.entries(patch)) {
+        const current = result[key];
+        const prefix = prefixMap[key];
+        if (isConfigObject(current) && isConfigObject(value)) {
+            if (prefix) {
+                const pruned = pruneKeysByPrefix(current, prefix);
+                result[key] = { ...pruned, ...value };
+            }
+            else {
+                result[key] = mergeWithPruneByPrefix(current, value, prefixMap);
+            }
+            continue;
+        }
+        result[key] = value;
+    }
+    return result;
+}
+// ============================================================================
+// Apply Mutation
+// ============================================================================
+export async function applyMutation(mutation, context, options) {
+    switch (mutation.kind) {
+        case "ensureDirectory":
+            return applyEnsureDirectory(mutation, context, options);
+        case "removeDirectory":
+            return applyRemoveDirectory(mutation, context, options);
+        case "removeFile":
+            return applyRemoveFile(mutation, context, options);
+        case "chmod":
+            return applyChmod(mutation, context, options);
+        case "backup":
+            return applyBackup(mutation, context, options);
+        case "configMerge":
+            return applyConfigMerge(mutation, context, options);
+        case "configPrune":
+            return applyConfigPrune(mutation, context, options);
+        case "configTransform":
+            return applyConfigTransform(mutation, context, options);
+        case "templateWrite":
+            return applyTemplateWrite(mutation, context, options);
+        case "templateMergeToml":
+            return applyTemplateMerge(mutation, context, options, "toml");
+        case "templateMergeJson":
+            return applyTemplateMerge(mutation, context, options, "json");
+        default: {
+            const never = mutation;
+            throw new Error(`Unknown mutation kind: ${never.kind}`);
+        }
+    }
+}
+// ============================================================================
+// File Mutation Handlers
+// ============================================================================
+async function applyEnsureDirectory(mutation, context, options) {
+    const rawPath = resolveValue(mutation.path, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const existed = await pathExists(context.fs, targetPath);
+    if (!context.dryRun) {
+        await context.fs.mkdir(targetPath, { recursive: true });
+    }
+    return {
+        outcome: {
+            changed: !existed,
+            effect: "mkdir",
+            detail: existed ? "noop" : "create"
+        },
+        details
+    };
+}
+async function applyRemoveDirectory(mutation, context, options) {
+    const rawPath = resolveValue(mutation.path, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const existed = await pathExists(context.fs, targetPath);
+    if (!existed) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    if (typeof context.fs.rm !== "function") {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    if (mutation.force) {
+        if (!context.dryRun) {
+            await context.fs.rm(targetPath, { recursive: true, force: true });
+        }
+        return {
+            outcome: { changed: true, effect: "delete", detail: "delete" },
+            details
+        };
+    }
+    const entries = await context.fs.readdir(targetPath);
+    if (entries.length > 0) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    if (!context.dryRun) {
+        await context.fs.rm(targetPath, { recursive: true, force: true });
+    }
+    return {
+        outcome: { changed: true, effect: "delete", detail: "delete" },
+        details
+    };
+}
+async function applyRemoveFile(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    try {
+        const content = await context.fs.readFile(targetPath, "utf8");
+        const trimmed = content.trim();
+        // Check whenContentMatches guard
+        if (mutation.whenContentMatches && !mutation.whenContentMatches.test(trimmed)) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        // Check whenEmpty guard
+        if (mutation.whenEmpty && trimmed.length > 0) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        if (!context.dryRun) {
+            await context.fs.unlink(targetPath);
+        }
+        return {
+            outcome: { changed: true, effect: "delete", detail: "delete" },
+            details
+        };
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        throw error;
+    }
+}
+async function applyChmod(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    if (typeof context.fs.chmod !== "function") {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    try {
+        const stat = await context.fs.stat(targetPath);
+        const currentMode = typeof stat.mode === "number" ? stat.mode & 0o777 : null;
+        if (currentMode === mutation.mode) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        if (!context.dryRun) {
+            await context.fs.chmod(targetPath, mutation.mode);
+        }
+        return {
+            outcome: { changed: true, effect: "chmod", detail: "update" },
+            details
+        };
+    }
+    catch (error) {
+        if (isNotFound(error)) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        throw error;
+    }
+}
+async function applyBackup(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const content = await readFileIfExists(context.fs, targetPath);
+    if (content === null) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    if (!context.dryRun) {
+        const backupPath = `${targetPath}.backup-${createTimestamp()}`;
+        await context.fs.writeFile(backupPath, content, { encoding: "utf8" });
+    }
+    return {
+        outcome: { changed: true, effect: "copy", detail: "backup" },
+        details
+    };
+}
+// ============================================================================
+// Config Mutation Handlers
+// ============================================================================
+async function applyConfigMerge(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const formatName = mutation.format ?? detectFormat(rawPath);
+    if (!formatName) {
+        throw new Error(`Cannot detect config format for "${rawPath}". Provide explicit format option.`);
+    }
+    const format = getConfigFormat(formatName);
+    const rawContent = await readFileIfExists(context.fs, targetPath);
+    let current;
+    try {
+        current = rawContent === null ? {} : format.parse(rawContent);
+    }
+    catch {
+        // Invalid file - backup and start fresh
+        if (rawContent !== null) {
+            await backupInvalidDocument(context.fs, targetPath, rawContent);
+        }
+        current = {};
+    }
+    const value = resolveValue(mutation.value, options);
+    // Use mergeWithPruneByPrefix for TOML files with pruneByPrefix option
+    let merged;
+    if (mutation.pruneByPrefix) {
+        merged = mergeWithPruneByPrefix(current, value, mutation.pruneByPrefix);
+    }
+    else {
+        merged = format.merge(current, value);
+    }
+    const serialized = format.serialize(merged);
+    const changed = serialized !== rawContent;
+    if (changed && !context.dryRun) {
+        await context.fs.writeFile(targetPath, serialized, { encoding: "utf8" });
+    }
+    return {
+        outcome: {
+            changed,
+            effect: changed ? "write" : "none",
+            detail: changed ? (rawContent === null ? "create" : "update") : "noop"
+        },
+        details
+    };
+}
+async function applyConfigPrune(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const rawContent = await readFileIfExists(context.fs, targetPath);
+    if (rawContent === null) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    const formatName = mutation.format ?? detectFormat(rawPath);
+    if (!formatName) {
+        throw new Error(`Cannot detect config format for "${rawPath}". Provide explicit format option.`);
+    }
+    const format = getConfigFormat(formatName);
+    let current;
+    try {
+        current = format.parse(rawContent);
+    }
+    catch {
+        // Invalid file - can't prune, leave as-is
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    // Check onlyIf guard
+    if (mutation.onlyIf && !mutation.onlyIf(current, options)) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    const shape = resolveValue(mutation.shape, options);
+    const { changed, result } = format.prune(current, shape);
+    if (!changed) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    // Delete file if empty
+    if (Object.keys(result).length === 0) {
+        if (!context.dryRun) {
+            await context.fs.unlink(targetPath);
+        }
+        return {
+            outcome: { changed: true, effect: "delete", detail: "delete" },
+            details
+        };
+    }
+    const serialized = format.serialize(result);
+    if (!context.dryRun) {
+        await context.fs.writeFile(targetPath, serialized, { encoding: "utf8" });
+    }
+    return {
+        outcome: { changed: true, effect: "write", detail: "update" },
+        details
+    };
+}
+async function applyConfigTransform(mutation, context, options) {
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const formatName = mutation.format ?? detectFormat(rawPath);
+    if (!formatName) {
+        throw new Error(`Cannot detect config format for "${rawPath}". Provide explicit format option.`);
+    }
+    const format = getConfigFormat(formatName);
+    const rawContent = await readFileIfExists(context.fs, targetPath);
+    let current;
+    try {
+        current = rawContent === null ? {} : format.parse(rawContent);
+    }
+    catch {
+        if (rawContent !== null) {
+            await backupInvalidDocument(context.fs, targetPath, rawContent);
+        }
+        current = {};
+    }
+    const { content: transformed, changed } = mutation.transform(current, options);
+    if (!changed) {
+        return {
+            outcome: { changed: false, effect: "none", detail: "noop" },
+            details
+        };
+    }
+    // Delete file if null
+    if (transformed === null) {
+        if (rawContent === null) {
+            return {
+                outcome: { changed: false, effect: "none", detail: "noop" },
+                details
+            };
+        }
+        if (!context.dryRun) {
+            await context.fs.unlink(targetPath);
+        }
+        return {
+            outcome: { changed: true, effect: "delete", detail: "delete" },
+            details
+        };
+    }
+    const serialized = format.serialize(transformed);
+    if (!context.dryRun) {
+        await context.fs.writeFile(targetPath, serialized, { encoding: "utf8" });
+    }
+    return {
+        outcome: {
+            changed: true,
+            effect: "write",
+            detail: rawContent === null ? "create" : "update"
+        },
+        details
+    };
+}
+// ============================================================================
+// Template Mutation Handlers
+// ============================================================================
+async function applyTemplateWrite(mutation, context, options) {
+    if (!context.templates) {
+        throw new Error("Template mutations require a templates loader. " +
+            "Provide templates function to runMutations context.");
+    }
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const template = await context.templates(mutation.templateId);
+    const templateContext = mutation.context
+        ? resolveValue(mutation.context, options)
+        : {};
+    const rendered = Mustache.render(template, templateContext);
+    const existed = await pathExists(context.fs, targetPath);
+    if (!context.dryRun) {
+        await context.fs.writeFile(targetPath, rendered, { encoding: "utf8" });
+    }
+    return {
+        outcome: {
+            changed: true,
+            effect: "write",
+            detail: existed ? "update" : "create"
+        },
+        details
+    };
+}
+async function applyTemplateMerge(mutation, context, options, formatName) {
+    if (!context.templates) {
+        throw new Error("Template mutations require a templates loader. " +
+            "Provide templates function to runMutations context.");
+    }
+    const rawPath = resolveValue(mutation.target, options);
+    const targetPath = resolvePath(rawPath, context.homeDir, context.pathMapper);
+    const details = {
+        kind: mutation.kind,
+        label: mutation.label ?? describeMutation(mutation.kind, targetPath),
+        targetPath
+    };
+    const format = getConfigFormat(formatName);
+    // Load and render template
+    const template = await context.templates(mutation.templateId);
+    const templateContext = mutation.context
+        ? resolveValue(mutation.context, options)
+        : {};
+    const rendered = Mustache.render(template, templateContext);
+    // Parse rendered template
+    let templateDoc;
+    try {
+        templateDoc = format.parse(rendered);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse rendered template "${mutation.templateId}" as ${formatName.toUpperCase()}: ${error}`, { cause: error });
+    }
+    // Read and parse existing file
+    const rawContent = await readFileIfExists(context.fs, targetPath);
+    let current;
+    try {
+        current = rawContent === null ? {} : format.parse(rawContent);
+    }
+    catch {
+        if (rawContent !== null) {
+            await backupInvalidDocument(context.fs, targetPath, rawContent);
+        }
+        current = {};
+    }
+    // Merge
+    const merged = format.merge(current, templateDoc);
+    const serialized = format.serialize(merged);
+    const changed = serialized !== rawContent;
+    if (changed && !context.dryRun) {
+        await context.fs.writeFile(targetPath, serialized, { encoding: "utf8" });
+    }
+    return {
+        outcome: {
+            changed,
+            effect: changed ? "write" : "none",
+            detail: changed ? (rawContent === null ? "create" : "update") : "noop"
+        },
+        details
+    };
+}

package/node_modules/@poe-code/config-mutations/dist/execution/path-utils.d.ts

@@ -0,0 +1,17 @@
+import type { PathMapper } from "../types.js";
+/**
+ * Expand ~ shortcut to the provided home directory.
+ */
+export declare function expandHome(targetPath: string, homeDir: string): string;
+/**
+ * Validate that a path is home-relative (starts with ~).
+ * Throws if the path is not home-relative.
+ */
+export declare function validateHomePath(targetPath: string): void;
+/**
+ * Resolve a path with optional path mapping for isolated configurations.
+ * 1. Validates the path starts with ~
+ * 2. Expands ~ to home directory
+ * 3. If pathMapper is provided, maps the directory portion and reconstructs the path
+ */
+export declare function resolvePath(rawPath: string, homeDir: string, pathMapper?: PathMapper): string;

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

@@ -0,0 +1,58 @@
+import path from "node:path";
+/**
+ * Expand ~ shortcut to the provided home directory.
+ */
+export function expandHome(targetPath, homeDir) {
+    if (!targetPath?.startsWith("~")) {
+        return targetPath;
+    }
+    // Handle ~./ -> ~/.
+    if (targetPath.startsWith("~./")) {
+        targetPath = `~/.${targetPath.slice(3)}`;
+    }
+    let remainder = targetPath.slice(1);
+    // Remove leading slash or backslash
+    if (remainder.startsWith("/") || remainder.startsWith("\\")) {
+        remainder = remainder.slice(1);
+    }
+    else if (remainder.startsWith(".")) {
+        // Handle ~/.
+        remainder = remainder.slice(1);
+        if (remainder.startsWith("/") || remainder.startsWith("\\")) {
+            remainder = remainder.slice(1);
+        }
+    }
+    return remainder.length === 0 ? homeDir : path.join(homeDir, remainder);
+}
+/**
+ * Validate that a path is home-relative (starts with ~).
+ * Throws if the path is not home-relative.
+ */
+export function validateHomePath(targetPath) {
+    if (typeof targetPath !== "string" || targetPath.length === 0) {
+        throw new Error("Target path must be a non-empty string.");
+    }
+    if (!targetPath.startsWith("~")) {
+        throw new Error(`All target paths must be home-relative (start with ~). Received: "${targetPath}"`);
+    }
+}
+/**
+ * Resolve a path with optional path mapping for isolated configurations.
+ * 1. Validates the path starts with ~
+ * 2. Expands ~ to home directory
+ * 3. If pathMapper is provided, maps the directory portion and reconstructs the path
+ */
+export function resolvePath(rawPath, homeDir, pathMapper) {
+    validateHomePath(rawPath);
+    const expanded = expandHome(rawPath, homeDir);
+    if (!pathMapper) {
+        return expanded;
+    }
+    // Map the directory portion
+    const rawDirectory = path.dirname(expanded);
+    const mappedDirectory = pathMapper.mapTargetDirectory({
+        targetDirectory: rawDirectory
+    });
+    const filename = path.basename(expanded);
+    return filename.length === 0 ? mappedDirectory : path.join(mappedDirectory, filename);
+}

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

@@ -0,0 +1,7 @@
+import type { Mutation, MutationContext, MutationResult, MutationOptions } from "../types.js";
+/**
+ * Execute an array of mutations in order.
+ *
+ * All dependencies must be injected - no defaults, no globals.
+ */
+export declare function runMutations(mutations: Mutation[], context: MutationContext, options?: MutationOptions): Promise<MutationResult>;

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

@@ -0,0 +1,46 @@
+import { applyMutation } from "./apply-mutation.js";
+/**
+ * Execute an array of mutations in order.
+ *
+ * All dependencies must be injected - no defaults, no globals.
+ */
+export async function runMutations(mutations, context, options) {
+    const effects = [];
+    let anyChanged = false;
+    const resolverOptions = options ?? {};
+    for (const mutation of mutations) {
+        const { outcome } = await executeMutation(mutation, context, resolverOptions);
+        effects.push(outcome);
+        if (outcome.changed) {
+            anyChanged = true;
+        }
+    }
+    return {
+        changed: anyChanged,
+        effects
+    };
+}
+async function executeMutation(mutation, context, options) {
+    // Call onStart observer
+    context.observers?.onStart?.({
+        kind: mutation.kind,
+        label: mutation.label ?? mutation.kind,
+        targetPath: undefined // Will be resolved during apply
+    });
+    try {
+        const { outcome, details } = await applyMutation(mutation, context, options);
+        // Call onComplete observer
+        context.observers?.onComplete?.(details, outcome);
+        return { outcome, details };
+    }
+    catch (error) {
+        // Call onError observer
+        context.observers?.onError?.({
+            kind: mutation.kind,
+            label: mutation.label ?? mutation.kind,
+            targetPath: undefined
+        }, error);
+        // Re-throw the error
+        throw error;
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ConfigFormat } from "../types.js";
+export type FormatName = "json" | "toml" | "yaml";
+/**
+ * Get a format handler by path (auto-detect from extension) or explicit format name.
+ */
+export declare function getConfigFormat(pathOrFormat: string): ConfigFormat;
+/**
+ * Detect format name from a file path.
+ */
+export declare function detectFormat(path: string): FormatName | undefined;
+export { jsonFormat } from "./json.js";
+export { tomlFormat } from "./toml.js";
+export { yamlFormat } from "./yaml.js";