@microck/canonfig 2.0.0 → 2.1.0

package/dist/harness-configuration/core/planner.js

@@ -0,0 +1,255 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Buffer } from "node:buffer";
+import { assertRealPathInside, assertSafeRelativePath, resolveInside } from "./path.js";
+import { assertNoSymlinkPathComponents, atomicWrite, ensureDirectoryNoFollow, readOptionalFile, removeFileAndEmptyParents, } from "./filesystem.js";
+import { loadState, writeState, HARNESS_CONFIGURATION_VERSION } from "./state.js";
+import { renderArtifacts } from "./render.js";
+import { sha256 } from "./hash.js";
+import { CanonfigError } from "./errors.js";
+function bytesEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return left === undefined && right === undefined;
+    const rightBytes = typeof right === "string" ? Buffer.from(right) : Buffer.from(right);
+    return Buffer.from(left).equals(rightBytes);
+}
+function isTextArtifacts(artifacts) {
+    return artifacts.every((artifact) => artifact.kind !== "replace" || typeof artifact.content === "string");
+}
+function selectedOwner(owner, targets) {
+    return owner === "common" || targets.includes(owner);
+}
+function ownerFor(artifacts, diagnostics, filePath) {
+    const owners = [...new Set(artifacts.map((artifact) => artifact.owner))];
+    if (owners.length > 1) {
+        diagnostics.push({
+            level: "error",
+            code: "ARTIFACT_OWNER_COLLISION",
+            message: `Multiple owners target ${filePath}: ${owners.join(", ")}`,
+            path: filePath,
+        });
+    }
+    return owners[0] ?? "common";
+}
+function modeFor(artifacts) {
+    const modes = artifacts.flatMap((artifact) => artifact.kind === "replace" && artifact.mode !== undefined ? [artifact.mode] : []);
+    return modes[0];
+}
+export async function createPlan(root, targets, artifacts, diagnostics = [], options = {}) {
+    const previousState = await loadState(root);
+    const nextArtifacts = {};
+    for (const [filePath, state] of Object.entries(previousState.artifacts)) {
+        if (!selectedOwner(state.owner, targets))
+            nextArtifacts[filePath] = state;
+    }
+    const groups = new Map();
+    for (const artifact of artifacts) {
+        const safePath = assertSafeRelativePath(artifact.path);
+        const list = groups.get(safePath) ?? [];
+        list.push({ ...artifact, path: safePath });
+        groups.set(safePath, list);
+    }
+    const entries = [];
+    for (const [filePath, group] of [...groups.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        const absolute = resolveInside(root, filePath);
+        await assertRealPathInside(root, absolute);
+        const currentBytes = await readOptionalFile(absolute);
+        const current = isTextArtifacts(group) && currentBytes !== undefined ? Buffer.from(currentBytes).toString("utf8") : currentBytes;
+        const previous = previousState.artifacts[filePath];
+        const rendered = renderArtifacts(group, current, previous, options.force ?? false);
+        const owner = ownerFor(group, diagnostics, filePath);
+        const mode = modeFor(group);
+        if (rendered.conflicts.length > 0) {
+            entries.push({
+                path: filePath,
+                owner,
+                action: "conflict",
+                reason: rendered.conflicts.join(" "),
+                before: typeof current === "string" ? current : undefined,
+                after: typeof rendered.content === "string" ? rendered.content : undefined,
+                content: rendered.content,
+                binary: rendered.content instanceof Uint8Array,
+                ...(mode === undefined ? {} : { mode }),
+            });
+            if (previous)
+                nextArtifacts[filePath] = previous;
+            continue;
+        }
+        if (rendered.content === undefined) {
+            entries.push({ path: filePath, owner, action: currentBytes === undefined ? "unchanged" : "delete" });
+            continue;
+        }
+        const contentHash = sha256(rendered.content);
+        const unmanagedIdenticalReplace = previous === undefined &&
+            currentBytes !== undefined &&
+            group.length === 1 &&
+            group[0]?.kind === "replace" &&
+            contentHash === sha256(currentBytes);
+        let nextState;
+        if (!unmanagedIdenticalReplace) {
+            nextState = {
+                owner,
+                hash: contentHash,
+                existedBefore: previous?.existedBefore ?? currentBytes !== undefined,
+                cleanup: rendered.cleanup,
+                ...(mode === undefined ? {} : { mode }),
+            };
+            nextArtifacts[filePath] = nextState;
+        }
+        else {
+            diagnostics.push({
+                level: "info",
+                code: "UNMANAGED_IDENTICAL",
+                message: `${filePath} already matches generated output; Canonfig left ownership unchanged.`,
+                path: filePath,
+            });
+        }
+        const action = currentBytes === undefined ? "create" : bytesEqual(currentBytes, rendered.content) ? "unchanged" : "update";
+        entries.push({
+            path: filePath,
+            owner,
+            action,
+            before: typeof current === "string" ? current : undefined,
+            after: typeof rendered.content === "string" ? rendered.content : undefined,
+            content: rendered.content,
+            binary: rendered.content instanceof Uint8Array,
+            ...(mode === undefined ? {} : { mode }),
+            ...(nextState === undefined ? {} : { nextState }),
+        });
+    }
+    const desiredPaths = new Set(groups.keys());
+    for (const [filePath, previous] of Object.entries(previousState.artifacts)) {
+        if (desiredPaths.has(filePath) || !selectedOwner(previous.owner, targets))
+            continue;
+        const absolute = resolveInside(root, filePath);
+        await assertRealPathInside(root, absolute);
+        const currentBytes = await readOptionalFile(absolute);
+        const current = currentBytes === undefined ? undefined : Buffer.from(currentBytes).toString("utf8");
+        const rendered = renderArtifacts([], current, previous, options.force ?? false);
+        if (rendered.conflicts.length > 0) {
+            entries.push({
+                path: filePath,
+                owner: previous.owner,
+                action: "conflict",
+                reason: rendered.conflicts.join(" "),
+                before: current,
+                after: typeof rendered.content === "string" ? rendered.content : undefined,
+            });
+            nextArtifacts[filePath] = previous;
+            continue;
+        }
+        const cleaned = previous.existedBefore ? rendered.content : undefined;
+        if (cleaned === undefined) {
+            entries.push({ path: filePath, owner: previous.owner, action: currentBytes === undefined ? "unchanged" : "delete", before: current });
+        }
+        else {
+            const action = bytesEqual(currentBytes, cleaned) ? "unchanged" : currentBytes === undefined ? "create" : "update";
+            entries.push({
+                path: filePath,
+                owner: previous.owner,
+                action,
+                before: current,
+                after: typeof cleaned === "string" ? cleaned : undefined,
+                content: cleaned,
+                binary: cleaned instanceof Uint8Array,
+                ...(previous.mode === undefined ? {} : { mode: previous.mode }),
+            });
+        }
+    }
+    const nextState = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        canonfigVersion: HARNESS_CONFIGURATION_VERSION,
+        artifacts: Object.fromEntries(Object.entries(nextArtifacts).sort(([left], [right]) => left.localeCompare(right))),
+    };
+    return { root, targets, entries: entries.sort((a, b) => a.path.localeCompare(b.path)), diagnostics, nextState };
+}
+async function snapshotFile(root, relativePath) {
+    const absolute = resolveInside(root, relativePath);
+    try {
+        const stats = await fs.lstat(absolute);
+        if (stats.isSymbolicLink()) {
+            return { path: relativePath, kind: "symlink", linkTarget: await fs.readlink(absolute) };
+        }
+        return {
+            path: relativePath,
+            kind: "file",
+            content: await fs.readFile(absolute),
+            mode: stats.mode & 0o777,
+        };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { path: relativePath, kind: "missing" };
+        throw error;
+    }
+}
+async function restoreSnapshots(root, snapshots) {
+    const failures = [];
+    for (const snapshot of [...snapshots].reverse()) {
+        const absolute = resolveInside(root, snapshot.path);
+        try {
+            if (snapshot.kind === "missing") {
+                await removeFileAndEmptyParents(absolute, root);
+            }
+            else if (snapshot.kind === "symlink") {
+                const parent = path.dirname(absolute);
+                await ensureDirectoryNoFollow(root, parent);
+                await assertNoSymlinkPathComponents(root, parent);
+                await fs.rm(absolute, { force: true });
+                await assertNoSymlinkPathComponents(root, parent);
+                await fs.symlink(snapshot.linkTarget, absolute);
+            }
+            else {
+                await atomicWrite(absolute, snapshot.content, snapshot.mode, root);
+            }
+        }
+        catch (error) {
+            failures.push({ path: snapshot.path, error });
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`Failed to restore ${failures.length} snapshot(s): ${failures.map(({ path: filePath, error }) => `${filePath}: ${String(error)}`).join("; ")}`);
+    }
+}
+export async function applyPlan(plan) {
+    const conflicts = plan.entries.filter((entry) => entry.action === "conflict");
+    const errors = plan.diagnostics.filter((diagnostic) => diagnostic.level === "error");
+    if (conflicts.length > 0 || errors.length > 0) {
+        throw new CanonfigError("PLAN_CONFLICT", `Plan has ${conflicts.length} conflict(s) and ${errors.length} error diagnostic(s).`);
+    }
+    const mutableEntries = plan.entries.filter((entry) => entry.action === "create" || entry.action === "update" || entry.action === "delete");
+    const snapshots = [];
+    for (const entry of mutableEntries) {
+        const absolute = resolveInside(plan.root, entry.path);
+        await assertRealPathInside(plan.root, absolute);
+        snapshots.push(await snapshotFile(plan.root, entry.path));
+    }
+    try {
+        for (const entry of mutableEntries) {
+            const absolute = resolveInside(plan.root, entry.path);
+            if (entry.action === "create" || entry.action === "update") {
+                if (entry.after === undefined && !entry.binary) {
+                    throw new CanonfigError("PLAN_INVALID", `Missing output content for ${entry.path}`);
+                }
+                const content = entry.content ?? entry.after;
+                if (content === undefined)
+                    throw new CanonfigError("PLAN_INVALID", `Missing output content for ${entry.path}`);
+                await atomicWrite(absolute, content, entry.mode, plan.root);
+            }
+            else {
+                await removeFileAndEmptyParents(absolute, plan.root);
+            }
+        }
+        await writeState(plan.root, plan.nextState);
+    }
+    catch (error) {
+        try {
+            await restoreSnapshots(plan.root, snapshots);
+        }
+        catch (rollbackError) {
+            throw new CanonfigError("APPLY_ROLLBACK_FAILED", `Harness apply failed and rollback also failed: ${String(rollbackError)}`, error);
+        }
+        throw error;
+    }
+}

package/dist/harness-configuration/core/render-cleanup.js

@@ -0,0 +1,91 @@
+import { sha256 } from "./hash.js";
+import { restoreJsonCleanup } from "./render-json.js";
+import { commentMarkers, locateBlock, parseJsonDocument, serializeJsonDocument, tomlBlockMarkers, } from "./render-utils.js";
+function removeManagedText(text, cleanup, force, conflicts) {
+    const markers = commentMarkers(cleanup.marker, cleanup.comments);
+    const located = locateBlock(text, markers.begin, markers.end);
+    if (located === undefined) {
+        conflicts.push(`Managed block ${cleanup.marker} is missing.`);
+        return text;
+    }
+    if (sha256(located.block) !== cleanup.blockHash && !force) {
+        conflicts.push(`Managed block ${cleanup.marker} was edited outside Canonfig.`);
+        return text;
+    }
+    return `${text.slice(0, located.start)}${text.slice(located.end)}`
+        .replace(/^\s+$/u, "");
+}
+function removeTomlBlock(text, cleanup, force, conflicts) {
+    const markers = tomlBlockMarkers(cleanup.marker);
+    const located = locateBlock(text, markers.begin, markers.end);
+    if (located === undefined) {
+        conflicts.push(`Managed TOML block ${cleanup.marker} is missing.`);
+        return text;
+    }
+    if (sha256(located.block) !== cleanup.blockHash && !force) {
+        conflicts.push(`Managed TOML block ${cleanup.marker} was edited outside Canonfig.`);
+        return text;
+    }
+    return `${text.slice(0, located.start)}${text.slice(located.end)}`;
+}
+function removeTomlKey(text, cleanup, conflicts) {
+    const lines = text.split(/\r?\n/u);
+    const marker = `# canonfig:key ${cleanup.marker}`;
+    const index = lines.findIndex((line) => line.includes(marker));
+    if (index < 0) {
+        conflicts.push(`Managed TOML key ${cleanup.section}.${cleanup.key} is missing.`);
+        return text;
+    }
+    if (cleanup.originalLine !== undefined)
+        lines[index] = cleanup.originalLine;
+    else
+        lines.splice(index, 1);
+    return lines.join("\n");
+}
+export function unapplyPrevious(current, previous, force, conflicts) {
+    if (previous === undefined)
+        return current;
+    let output = current;
+    const jsonCleanups = previous.cleanup.filter((cleanup) => cleanup.kind.startsWith("json-"));
+    let jsonDocument;
+    if (jsonCleanups.length > 0 && typeof output === "string" && output.trim() !== "") {
+        jsonDocument = parseJsonDocument(output, conflicts);
+    }
+    for (const cleanup of previous.cleanup) {
+        if (cleanup.kind === "replace") {
+            if (output === undefined)
+                continue;
+            if (sha256(output) !== previous.hash && !force) {
+                conflicts.push("Generated file was edited outside Canonfig.");
+                continue;
+            }
+            output = undefined;
+            continue;
+        }
+        if (output instanceof Uint8Array) {
+            conflicts.push("Cannot merge text cleanup into a binary file.");
+            continue;
+        }
+        if (cleanup.kind === "json-managed-map"
+            || cleanup.kind === "json-managed-array"
+            || cleanup.kind === "json-managed-hooks") {
+            if (jsonDocument !== undefined) {
+                restoreJsonCleanup(jsonDocument, cleanup, force, conflicts);
+            }
+            continue;
+        }
+        const text = output ?? "";
+        if (cleanup.kind === "managed-text") {
+            output = removeManagedText(text, cleanup, force, conflicts);
+        }
+        else if (cleanup.kind === "toml-block") {
+            output = removeTomlBlock(text, cleanup, force, conflicts);
+        }
+        else {
+            output = removeTomlKey(text, cleanup, conflicts);
+        }
+    }
+    if (jsonDocument !== undefined && typeof output === "string")
+        output = serializeJsonDocument(jsonDocument);
+    return output;
+}

package/dist/harness-configuration/core/render-json.js

@@ -0,0 +1,195 @@
+import { containsMarker, deepEqual, getAtPath, identityOf, isRecord, parseJsonDocument, serializeJsonDocument, setAtPath, } from "./render-utils.js";
+export function restoreJsonCleanup(document, cleanup, force, conflicts) {
+    if (cleanup.kind === "json-managed-map") {
+        for (const [key, expected] of Object.entries(cleanup.entries)) {
+            const currentMap = getAtPath(document, cleanup.path);
+            const current = isRecord(currentMap) ? currentMap[key] : undefined;
+            if (!deepEqual(current, expected) && !force) {
+                conflicts.push(`Managed JSON entry ${[...cleanup.path, key].join(".")} was edited outside Canonfig.`);
+                continue;
+            }
+            const original = cleanup.originals[key];
+            setAtPath(document, [...cleanup.path, key], original?.existed ? original.value : undefined);
+        }
+        return;
+    }
+    if (cleanup.kind === "json-managed-array") {
+        const current = getAtPath(document, cleanup.path);
+        if (!Array.isArray(current))
+            return;
+        const remaining = [...current];
+        for (const expected of cleanup.values) {
+            const expectedIdentity = identityOf(expected, cleanup.identity);
+            const index = remaining.findIndex((candidate) => cleanup.identity === undefined
+                ? deepEqual(candidate, expected)
+                : deepEqual(identityOf(candidate, cleanup.identity), expectedIdentity));
+            if (index >= 0)
+                remaining.splice(index, 1);
+        }
+        setAtPath(document, cleanup.path, remaining);
+        return;
+    }
+    const current = getAtPath(document, cleanup.path);
+    if (!isRecord(current))
+        return;
+    const next = {};
+    const managedEvents = cleanup.events === undefined
+        ? undefined
+        : new Set(cleanup.events);
+    for (const [event, entries] of Object.entries(current)) {
+        if (managedEvents !== undefined && !managedEvents.has(event)) {
+            next[event] = entries;
+            continue;
+        }
+        const filtered = Array.isArray(entries)
+            ? entries.filter((entry) => !containsMarker(entry, cleanup.marker))
+            : entries;
+        const original = cleanup.originals?.[event];
+        if (original?.existed === true && !Array.isArray(filtered))
+            next[event] = original.value;
+        else if (Array.isArray(filtered) && filtered.length > 0)
+            next[event] = filtered;
+        else if (original?.existed === true)
+            next[event] = original.value;
+    }
+    if (cleanup.pathExisted === false && Object.keys(next).length === 0) {
+        setAtPath(document, cleanup.path, undefined);
+    }
+    else {
+        setAtPath(document, cleanup.path, next);
+    }
+}
+export function applyJsonArtifact(input, artifact, force, conflicts) {
+    const document = parseJsonDocument(input.trim() === "" ? "{}" : input, conflicts);
+    const cleanup = [];
+    const appliedRootDefaults = {};
+    const rootDefaultOriginals = {};
+    for (const [key, value] of Object.entries(artifact.rootDefaults ?? {})) {
+        if (document[key] === undefined) {
+            rootDefaultOriginals[key] = { existed: false };
+            document[key] = value;
+            appliedRootDefaults[key] = value;
+        }
+    }
+    if (Object.keys(appliedRootDefaults).length > 0) {
+        cleanup.push({
+            kind: "json-managed-map",
+            path: [],
+            entries: appliedRootDefaults,
+            originals: rootDefaultOriginals,
+        });
+    }
+    for (const operation of artifact.operations) {
+        if (operation.kind === "defaults") {
+            for (const entry of operation.entries) {
+                if (getAtPath(document, entry.path) === undefined) {
+                    setAtPath(document, entry.path, entry.value);
+                }
+            }
+            continue;
+        }
+        if (operation.kind === "managed-map") {
+            const map = getAtPath(document, operation.path);
+            if (map !== undefined && !isRecord(map) && !force) {
+                conflicts.push(`JSON path ${operation.path.join(".")} is not an object and is not owned by Canonfig.`);
+                continue;
+            }
+            const object = isRecord(map) ? map : {};
+            const originals = {};
+            const applied = {};
+            for (const [key, value] of Object.entries(operation.entries)) {
+                const existed = Object.prototype.hasOwnProperty.call(object, key);
+                const current = object[key];
+                originals[key] = existed
+                    ? { existed: true, value: current }
+                    : { existed: false };
+                if (existed
+                    && !deepEqual(current, value)
+                    && operation.collision !== "replace"
+                    && !force) {
+                    conflicts.push(`JSON entry ${[...operation.path, key].join(".")} already exists and is not owned by Canonfig.`);
+                    continue;
+                }
+                setAtPath(document, [...operation.path, key], value);
+                applied[key] = value;
+            }
+            if (Object.keys(applied).length > 0) {
+                cleanup.push({
+                    kind: "json-managed-map",
+                    path: [...operation.path],
+                    entries: applied,
+                    originals,
+                });
+            }
+            continue;
+        }
+        if (operation.kind === "managed-array") {
+            const found = getAtPath(document, operation.path);
+            if (found !== undefined && !Array.isArray(found) && !force) {
+                conflicts.push(`JSON path ${operation.path.join(".")} is not an array and is not owned by Canonfig.`);
+                continue;
+            }
+            const values = Array.isArray(found) ? [...found] : [];
+            const added = [];
+            for (const value of operation.values) {
+                const identity = identityOf(value, operation.identity);
+                const existingIndex = values.findIndex((candidate) => operation.identity === undefined
+                    ? deepEqual(candidate, value)
+                    : deepEqual(identityOf(candidate, operation.identity), identity));
+                if (existingIndex < 0) {
+                    values.push(value);
+                    added.push(value);
+                }
+                else if (operation.identity !== undefined
+                    && !deepEqual(values[existingIndex], value)) {
+                    if (!force) {
+                        conflicts.push(`Array entry ${operation.path.join(".")} with ${operation.identity}=${String(identity)} already exists.`);
+                    }
+                    else {
+                        values[existingIndex] = value;
+                    }
+                }
+            }
+            setAtPath(document, operation.path, values);
+            if (added.length > 0) {
+                cleanup.push({
+                    kind: "json-managed-array",
+                    path: [...operation.path],
+                    values: added,
+                    ...(operation.identity === undefined ? {} : { identity: operation.identity }),
+                });
+            }
+            continue;
+        }
+        const existingValue = getAtPath(document, operation.path);
+        if (existingValue !== undefined && !isRecord(existingValue) && !force) {
+            conflicts.push(`JSON path ${operation.path.join(".")} is not an object and is not owned by Canonfig.`);
+            continue;
+        }
+        const existing = isRecord(existingValue) ? existingValue : {};
+        const next = {};
+        for (const [event, entries] of Object.entries(existing)) {
+            next[event] = Array.isArray(entries)
+                ? entries.filter((entry) => !containsMarker(entry, operation.marker))
+                : entries;
+        }
+        const originals = {};
+        for (const [event, entries] of Object.entries(operation.hooks)) {
+            originals[event] = Object.prototype.hasOwnProperty.call(existing, event)
+                ? { existed: true, value: existing[event] }
+                : { existed: false };
+            const current = Array.isArray(next[event]) ? next[event] : [];
+            next[event] = [...current, ...entries];
+        }
+        setAtPath(document, operation.path, next);
+        cleanup.push({
+            kind: "json-managed-hooks",
+            path: [...operation.path],
+            marker: operation.marker,
+            events: Object.keys(operation.hooks),
+            originals,
+            pathExisted: existingValue !== undefined,
+        });
+    }
+    return { text: serializeJsonDocument(document), cleanup };
+}

package/dist/harness-configuration/core/render-text.js

@@ -0,0 +1,134 @@
+import { sha256 } from "./hash.js";
+import { commentMarkers, findTomlSection, locateBlock, tomlBlockMarkers, } from "./render-utils.js";
+export function appendManagedText(text, artifact, force, conflicts) {
+    const markers = commentMarkers(artifact.marker, artifact.comments);
+    const existing = locateBlock(text, markers.begin, markers.end);
+    if (existing !== undefined) {
+        if (!force) {
+            conflicts.push(`An unmanaged block already uses marker ${artifact.marker}.`);
+        }
+        text = `${text.slice(0, existing.start)}${text.slice(existing.end)}`;
+    }
+    const block = `${markers.begin}\n${artifact.content.trim()}\n${markers.end}\n`;
+    const separator = text.trim() === ""
+        ? ""
+        : text.endsWith("\n\n")
+            ? ""
+            : text.endsWith("\n")
+                ? "\n"
+                : "\n\n";
+    return {
+        text: artifact.placement === "start"
+            ? `${block}${separator}${text}`
+            : `${text}${separator}${block}`,
+        cleanup: {
+            kind: "managed-text",
+            marker: artifact.marker,
+            comments: artifact.comments,
+            blockHash: sha256(block),
+        },
+    };
+}
+function parseTomlLiteralLine(line, key) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const match = line.match(new RegExp(`^\\s*${escaped}\\s*=\\s*(.*?)\\s*(?:#.*)?$`, "u"));
+    return match?.[1]?.trim();
+}
+function applyTomlEnsureKey(input, ensure, force, conflicts) {
+    const lines = input.replace(/\r\n/gu, "\n").split("\n");
+    let section = findTomlSection(lines, ensure.section);
+    if (section === undefined) {
+        if (lines.length > 0 && lines.at(-1) !== "")
+            lines.push("");
+        lines.push(`[${ensure.section}]`);
+        section = { header: lines.length - 1, end: lines.length };
+    }
+    const escaped = ensure.key.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const keyPattern = new RegExp(`^\\s*${escaped}\\s*=`, "u");
+    let keyIndex = -1;
+    for (let index = section.header + 1; index < section.end; index += 1) {
+        if (keyPattern.test(lines[index] ?? "")) {
+            keyIndex = index;
+            break;
+        }
+    }
+    const marker = `# canonfig:key ${ensure.marker}`;
+    const desiredLine = `${ensure.key} = ${ensure.value} ${marker}`;
+    if (keyIndex >= 0) {
+        const currentLine = lines[keyIndex] ?? "";
+        if (parseTomlLiteralLine(currentLine, ensure.key) === ensure.value) {
+            return { text: lines.join("\n") };
+        }
+        if (ensure.collision !== "replace" && !force) {
+            conflicts.push(`TOML key ${ensure.section}.${ensure.key} already exists and differs.`);
+            return { text: lines.join("\n") };
+        }
+        lines[keyIndex] = desiredLine;
+        return {
+            text: lines.join("\n"),
+            cleanup: {
+                kind: "toml-key",
+                section: ensure.section,
+                key: ensure.key,
+                marker: ensure.marker,
+                originalLine: currentLine,
+            },
+        };
+    }
+    lines.splice(section.end, 0, desiredLine);
+    return {
+        text: lines.join("\n"),
+        cleanup: {
+            kind: "toml-key",
+            section: ensure.section,
+            key: ensure.key,
+            marker: ensure.marker,
+        },
+    };
+}
+export function applyTomlArtifact(input, artifact, force, conflicts) {
+    let text = input.replace(/\r\n/gu, "\n");
+    const cleanup = [];
+    for (const ensure of artifact.ensureKeys ?? []) {
+        const result = applyTomlEnsureKey(text, ensure, force, conflicts);
+        text = result.text;
+        if (result.cleanup !== undefined)
+            cleanup.push(result.cleanup);
+    }
+    for (const managed of artifact.blocks ?? []) {
+        const markers = tomlBlockMarkers(managed.marker);
+        const existing = locateBlock(text, markers.begin, markers.end);
+        if (existing !== undefined) {
+            if (!force) {
+                conflicts.push(`An unmanaged TOML block already uses marker ${managed.marker}.`);
+            }
+            text = `${text.slice(0, existing.start)}${text.slice(existing.end)}`;
+        }
+        const sections = [...managed.content.matchAll(/^\s*\[([^\]]+)\]\s*$/gmu)]
+            .map((match) => match[1])
+            .filter((section) => section !== undefined);
+        for (const section of sections) {
+            if (findTomlSection(text.split("\n"), section) !== undefined) {
+                conflicts.push(`TOML section [${section}] already exists outside Canonfig's managed block.`);
+            }
+        }
+        const block = `${markers.begin}\n${managed.content.trim()}\n${markers.end}\n`;
+        const separator = text.trim() === ""
+            ? ""
+            : text.endsWith("\n\n")
+                ? ""
+                : text.endsWith("\n")
+                    ? "\n"
+                    : "\n\n";
+        text = `${text}${separator}${block}`;
+        cleanup.push({
+            kind: "toml-block",
+            marker: managed.marker,
+            blockHash: sha256(block),
+        });
+    }
+    return {
+        text: text.endsWith("\n") ? text : `${text}\n`,
+        cleanup,
+    };
+}