@seamward/cli 0.1.0-alpha.9

package/dist/setup-engine.js

@@ -0,0 +1,765 @@
+import { execFile } from "node:child_process";
+import { mkdir, readdir, readFile, realpath, rm, rmdir, stat, writeFile, } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { scanProject } from "./discovery.js";
+import { readProjectMetadata, } from "./project-metadata.js";
+import { applySetupPlan, createSetupPlan, discoverIntegrationScopes, inspectSetupActionEvidence, inspectSetupCompletionState, inspectSetupPlanFiles, inspectSetupRemoteLifecycle, operatorReviewableSetupActions, recordSourceBackedSetupEvidence, resetSetupCompletionState, setupPlanFile, setupStateLockFile, setupStateFile, supportedCollectorVersion, withSetupProjectLock, } from "./setup-plan.js";
+import { applyPlannedSourceInstrumentation } from "./source-instrumentation.js";
+function normalizedSelectionContracts(files) {
+    return [...new Set(files ?? [])]
+        .map((file) => file.split(path.sep).join("/").replace(/^\.\//, ""))
+        .sort();
+}
+function planMatchesSelection(plan, selection) {
+    if (plan.integrationScope?.direction !== selection.direction ||
+        plan.integrationScope.protocol !== selection.protocol) {
+        return false;
+    }
+    if (selection.findingIds) {
+        const planned = plan.actions
+            .flatMap((action) => action.type === "instrument_operation" && action.findingId
+            ? [action.findingId]
+            : [])
+            .sort();
+        if (JSON.stringify(planned) !==
+            JSON.stringify([...selection.findingIds].sort())) {
+            return false;
+        }
+    }
+    const registeredContracts = plan.actions
+        .filter((action) => action.type === "register_contract" && typeof action.file === "string")
+        .map(({ file }) => file)
+        .sort();
+    return (JSON.stringify(registeredContracts) ===
+        JSON.stringify(normalizedSelectionContracts(selection.contractFiles)));
+}
+export class LocalSetupEngineError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "LocalSetupEngineError";
+    }
+}
+const execFileAsync = promisify(execFile);
+function projectPath(root, relativeFile) {
+    const file = path.resolve(root, relativeFile.split("/").join(path.sep));
+    const relative = path.relative(root, file);
+    if (relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)) {
+        throw new LocalSetupEngineError("internal_error", "A setup-owned path escaped the project boundary");
+    }
+    return file;
+}
+async function snapshotFiles(root, relativeFiles) {
+    return Promise.all([...new Set(relativeFiles)].map(async (relativeFile) => {
+        const file = projectPath(root, relativeFile);
+        try {
+            const [content, metadata] = await Promise.all([
+                readFile(file),
+                stat(file),
+            ]);
+            return { file, content, mode: metadata.mode };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { file, content: null, mode: null };
+            }
+            throw error;
+        }
+    }));
+}
+async function restoreFiles(snapshots) {
+    for (const snapshot of snapshots) {
+        if (snapshot.content === null) {
+            await rm(snapshot.file, { force: true });
+            continue;
+        }
+        await mkdir(path.dirname(snapshot.file), { recursive: true });
+        await writeFile(snapshot.file, snapshot.content, {
+            mode: snapshot.mode ?? undefined,
+        });
+    }
+}
+async function setupMutationFiles(root, plan) {
+    let previousGeneratedFiles = [];
+    try {
+        previousGeneratedFiles = (await readSetupPlan(root, undefined, plan.setupId)).generatedFiles.map(({ path: file }) => file);
+    }
+    catch (error) {
+        if (!(error instanceof LocalSetupEngineError) ||
+            !["plan_not_found", "legacy_plan_requires_replan"].includes(error.code)) {
+            throw error;
+        }
+    }
+    return [
+        "package.json",
+        "pnpm-lock.yaml",
+        "package-lock.json",
+        "yarn.lock",
+        "bun.lock",
+        "bun.lockb",
+        setupPlanFile(plan),
+        setupStateFile(plan),
+        ...previousGeneratedFiles,
+        ...plan.generatedFiles.map(({ path: file }) => file),
+        ...plan.actions.flatMap((action) => action.type === "instrument_operation" && action.file
+            ? [action.file]
+            : []),
+    ];
+}
+async function runProjectVerification(root, plan) {
+    const packageDocument = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+    const scripts = packageDocument.scripts ?? {};
+    const selected = typeof scripts.verify === "string"
+        ? ["verify"]
+        : ["test", "typecheck", "build"].filter((script) => typeof scripts[script] === "string");
+    if (selected.length === 0) {
+        throw new LocalSetupEngineError("verification_failed", "No verify, test, typecheck, or build script is available to validate the setup");
+    }
+    const packageManager = plan.packageManager ?? "npm";
+    for (const script of selected) {
+        try {
+            await execFileAsync(packageManager, ["run", script], {
+                cwd: root,
+                env: childEnvironment({ setupVerification: true }),
+                timeout: 300_000,
+                maxBuffer: 2_000_000,
+            });
+        }
+        catch {
+            throw new LocalSetupEngineError("verification_failed", `Project verification failed while running ${packageManager} run ${script}`);
+        }
+    }
+    return {
+        command: selected
+            .map((script) => `${packageManager} run ${script}`)
+            .join(" && "),
+        exitCode: 0,
+        completedAt: new Date().toISOString(),
+    };
+}
+function childEnvironment(options) {
+    if (options?.setupVerification) {
+        const allowedNames = new Set([
+            "PATH",
+            "SHELL",
+            "TMPDIR",
+            "TMP",
+            "TEMP",
+            "LANG",
+            "LC_ALL",
+            "LC_CTYPE",
+            "TERM",
+            "CI",
+            "NO_COLOR",
+            "FORCE_COLOR",
+            "COLORTERM",
+            "SystemRoot",
+            "WINDIR",
+        ]);
+        return {
+            ...Object.fromEntries(Object.entries(process.env).filter(([name]) => allowedNames.has(name))),
+            SEAMWARD_INTERNAL_SETUP_VERIFICATION: "1",
+        };
+    }
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([name]) => !/(?:SEAMWARD|API_KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)/i.test(name)));
+    return environment;
+}
+async function installCollectorDependency(root, plan) {
+    if (!plan.install || !plan.packageManager)
+        return;
+    const packageSpec = `@seamward/collector@${supportedCollectorVersion}`;
+    const invocations = {
+        npm: [["npm", ["install", packageSpec]]],
+        pnpm: [
+            [
+                "pnpm",
+                [
+                    "pkg",
+                    "set",
+                    `dependencies.@seamward/collector=${supportedCollectorVersion}`,
+                ],
+            ],
+            ["pnpm", ["install", "--no-frozen-lockfile"]],
+        ],
+        yarn: [["yarn", ["add", packageSpec]]],
+        bun: [["bun", ["add", packageSpec]]],
+    };
+    try {
+        for (const [command, arguments_] of invocations[plan.packageManager]) {
+            await execFileAsync(command, arguments_, {
+                cwd: root,
+                env: childEnvironment(),
+                timeout: 120_000,
+                maxBuffer: 1_000_000,
+            });
+        }
+    }
+    catch {
+        throw new LocalSetupEngineError("internal_error", "The collector dependency could not be installed with the project's package manager");
+    }
+}
+async function readCollectorDependency(root) {
+    try {
+        const document = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+        const value = document.dependencies?.["@seamward/collector"] ??
+            document.devDependencies?.["@seamward/collector"];
+        if (typeof value !== "string") {
+            return {
+                present: false,
+                compatible: false,
+                version: null,
+                minimumVersion: supportedCollectorVersion,
+            };
+        }
+        const version = await resolveCollectorVersion(root, value);
+        return {
+            present: true,
+            compatible: version !== null && versionAtLeast(version, supportedCollectorVersion),
+            version: version ?? value,
+            minimumVersion: supportedCollectorVersion,
+        };
+    }
+    catch {
+        return {
+            present: false,
+            compatible: false,
+            version: null,
+            minimumVersion: supportedCollectorVersion,
+        };
+    }
+}
+function parseVersion(value) {
+    const match = value.match(/(?:^|[~^<>=\s])v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/);
+    if (!match)
+        return null;
+    return {
+        release: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: (match[4] ?? "")
+            .split(".")
+            .filter(Boolean)
+            .map((part) => (/^\d+$/.test(part) ? Number(part) : part)),
+    };
+}
+function versionAtLeast(value, minimum) {
+    const candidate = parseVersion(value);
+    const floor = parseVersion(minimum);
+    if (!candidate || !floor)
+        return false;
+    for (let index = 0; index < candidate.release.length; index += 1) {
+        if (candidate.release[index] > floor.release[index])
+            return true;
+        if (candidate.release[index] < floor.release[index])
+            return false;
+    }
+    if (candidate.prerelease.length === 0)
+        return true;
+    if (floor.prerelease.length === 0)
+        return false;
+    const length = Math.max(candidate.prerelease.length, floor.prerelease.length);
+    for (let index = 0; index < length; index += 1) {
+        const left = candidate.prerelease[index];
+        const right = floor.prerelease[index];
+        if (left === undefined)
+            return true;
+        if (right === undefined)
+            return false;
+        if (left === right)
+            continue;
+        if (typeof left === "number" && typeof right === "string")
+            return false;
+        if (typeof left === "string" && typeof right === "number")
+            return true;
+        return left > right;
+    }
+    return true;
+}
+async function readPackageVersion(file) {
+    try {
+        const document = JSON.parse(await readFile(file, "utf8"));
+        return typeof document.version === "string" ? document.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveCollectorVersion(root, declared) {
+    const declaredVersion = parseVersion(declared);
+    if (declaredVersion) {
+        return declared.match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)?.[0] ?? null;
+    }
+    const local = declared.match(/^(?:file|link):(.+)$/)?.[1];
+    if (local) {
+        const localVersion = await readPackageVersion(path.resolve(root, local, "package.json"));
+        if (localVersion)
+            return localVersion;
+    }
+    return readPackageVersion(path.join(root, "node_modules", "@seamward", "collector", "package.json"));
+}
+export async function readSetupPlan(root, expectedFingerprint, setupId) {
+    try {
+        const requested = setupId
+            ? `.seamward/integrations/${setupId}/setup-plan.json`
+            : ".seamward/setup-plan.json";
+        const plan = JSON.parse(await readFile(path.join(root, ...requested.split("/")), "utf8"));
+        if (plan.schemaVersion !== "0.2") {
+            throw new LocalSetupEngineError("legacy_plan_requires_replan", "This setup plan predates source-backed evidence. Analyze and plan again");
+        }
+        if (expectedFingerprint && plan.fingerprint !== expectedFingerprint) {
+            throw new LocalSetupEngineError("plan_not_found", "The requested setup plan was not found for this project");
+        }
+        return plan;
+    }
+    catch (error) {
+        if (error instanceof LocalSetupEngineError)
+            throw error;
+        throw new LocalSetupEngineError("plan_not_found", "The setup plan was not found. Analyze and plan this service first");
+    }
+}
+export async function readSetupPlans(root) {
+    const integrationDirectory = path.join(root, ".seamward", "integrations");
+    let entries;
+    try {
+        entries = await readdir(integrationDirectory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const setupIds = entries
+        .filter((entry) => entry.isDirectory() &&
+        !entry.isSymbolicLink() &&
+        /^[a-z0-9][a-z0-9-]{0,62}$/.test(entry.name))
+        .map(({ name }) => name)
+        .sort();
+    return Promise.all(setupIds.map((setupId) => readSetupPlan(root, undefined, setupId)));
+}
+export async function verifySetup(root, plan) {
+    await applySetupPlan(plan, root);
+    const inspected = await inspectSetupPlanFiles(plan, root);
+    const generatedFiles = inspected.filter(({ file }) => file !== setupPlanFile(plan));
+    const artifactsValid = inspected.every(({ present, matches }) => present && matches);
+    const collectorDependency = await readCollectorDependency(root);
+    const evidence = await inspectSetupActionEvidence(plan, root);
+    const instrumentationActions = evidence.filter(({ actionType }) => actionType === "instrument_operation");
+    const contractActions = evidence.filter(({ actionType }) => actionType === "register_contract");
+    const remoteLifecycle = await inspectSetupRemoteLifecycle(plan, root);
+    const { fingerprint: stateFingerprint } = await inspectSetupCompletionState(plan, root);
+    const localBlockers = [];
+    if (!artifactsValid)
+        localBlockers.push({ code: "generated_artifact_invalid" });
+    if (plan.install !== null && !collectorDependency.present) {
+        localBlockers.push({ code: "collector_dependency_missing" });
+    }
+    else if (collectorDependency.present && !collectorDependency.compatible) {
+        localBlockers.push({ code: "collector_dependency_incompatible" });
+    }
+    for (const action of instrumentationActions) {
+        if (action.status !== "source_verified") {
+            localBlockers.push({ code: `instrumentation_${action.status}` });
+        }
+    }
+    const lifecycleBlockers = [];
+    for (const action of contractActions) {
+        if (action.status !== "registered") {
+            lifecycleBlockers.push({ code: "contract_registration_pending" });
+        }
+    }
+    if (contractActions.length > 0 && !remoteLifecycle.activation) {
+        lifecycleBlockers.push({ code: "contract_activation_pending" });
+    }
+    if (!remoteLifecycle.firstObservation) {
+        lifecycleBlockers.push({ code: "first_observation_pending" });
+    }
+    const blockers = [...localBlockers, ...lifecycleBlockers];
+    return {
+        planFingerprint: plan.fingerprint,
+        stateFingerprint,
+        artifactsValid,
+        collectorDependency,
+        generatedFiles,
+        instrumentationActions,
+        contractActions,
+        remoteLifecycle,
+        sourceBackedComplete: localBlockers.length === 0 &&
+            instrumentationActions.every(({ status }) => status === "source_verified"),
+        localSetupComplete: localBlockers.length === 0,
+        setupComplete: blockers.length === 0,
+        blockers,
+    };
+}
+export async function applyLocalSetupBatch(rootDirectory, entries, retiredPlans = []) {
+    const root = await realpath(path.resolve(rootDirectory));
+    const mutationFiles = [
+        ...(await Promise.all(entries.map(({ plan }) => setupMutationFiles(root, plan)))).flat(),
+        ...retiredPlans.flatMap((plan) => retirementOwnedFiles(plan)),
+    ];
+    const snapshots = await snapshotFiles(root, mutationFiles);
+    const results = [];
+    try {
+        for (const { engine, plan } of entries) {
+            const result = await engine.applyLocal({
+                planFingerprint: plan.fingerprint,
+            });
+            if (result.status !== "verified") {
+                throw new LocalSetupEngineError("verification_failed", `Automatic setup could not safely transform ${plan.setupId ?? "the selected Integration"}`);
+            }
+            results.push({
+                ...(plan.setupId ? { setupId: plan.setupId } : {}),
+                result,
+            });
+        }
+        const retired = await retireLocalSetupBindings(root, retiredPlans);
+        const verificationPlan = entries[0]?.plan ?? retiredPlans[0];
+        if (verificationPlan) {
+            const finalVerification = await runProjectVerification(root, verificationPlan);
+            for (const { plan } of entries) {
+                const actions = operatorReviewableSetupActions(plan);
+                if (actions.length === 0)
+                    continue;
+                const completion = await inspectSetupCompletionState(plan, root);
+                await recordSourceBackedSetupEvidence(plan, root, actions.map(({ id }) => id), {
+                    write: true,
+                    expectedStateFingerprint: completion.fingerprint,
+                    evidence: "coding_agent_reviewed_setup",
+                    verification: finalVerification,
+                });
+            }
+        }
+        return {
+            applied: await Promise.all(results.map(async (applied, index) => ({
+                ...applied,
+                result: applied.result.status === "verified"
+                    ? {
+                        ...applied.result,
+                        verification: await verifySetup(root, entries[index].plan),
+                    }
+                    : applied.result,
+            }))),
+            retired,
+        };
+    }
+    catch (error) {
+        await restoreFiles(snapshots);
+        throw error;
+    }
+}
+function retirementOwnedFiles(plan) {
+    return [
+        ...plan.generatedFiles.map(({ path: file }) => file),
+        setupStateLockFile(plan),
+        setupStateFile(plan),
+        setupPlanFile(plan),
+    ];
+}
+export async function retireLocalSetupBindings(rootDirectory, plans) {
+    const root = await realpath(path.resolve(rootDirectory));
+    const results = [];
+    for (const plan of plans) {
+        if (!plan.setupId) {
+            throw new LocalSetupEngineError("internal_error", "Only named Integration bindings can be retired");
+        }
+        const generatedInspection = (await inspectSetupPlanFiles(plan, root)).filter(({ file }) => plan.generatedFiles.some(({ path: generated }) => generated === file));
+        if (generatedInspection.some(({ present, matches }) => present && !matches)) {
+            throw new LocalSetupEngineError("generated_file_conflict", `A generated file for ${plan.setupId} changed and will not be removed`);
+        }
+        const ownedFiles = retirementOwnedFiles(plan);
+        const snapshots = await snapshotFiles(root, ownedFiles);
+        const lockSnapshot = snapshots.find(({ file }) => file === projectPath(root, setupStateLockFile(plan)));
+        if (lockSnapshot && lockSnapshot.content !== null) {
+            throw new LocalSetupEngineError("apply_in_progress", `The setup binding for ${plan.setupId} is currently being updated`);
+        }
+        const integrationDirectory = path.dirname(projectPath(root, setupPlanFile(plan)));
+        try {
+            const entries = await readdir(integrationDirectory);
+            const ownedNames = new Set(ownedFiles
+                .filter((file) => path.dirname(projectPath(root, file)) === integrationDirectory)
+                .map((file) => path.basename(file)));
+            if (entries.some((entry) => !ownedNames.has(entry))) {
+                throw new LocalSetupEngineError("generated_file_conflict", `The setup directory for ${plan.setupId} contains files Seamward does not own`);
+            }
+            for (const file of ownedFiles) {
+                await rm(projectPath(root, file), { force: true });
+            }
+            await rmdir(integrationDirectory);
+            results.push({
+                setupId: plan.setupId,
+                files: snapshots
+                    .filter(({ content }) => content !== null)
+                    .map(({ file }) => path.relative(root, file).split(path.sep).join("/")),
+                remoteAction: "left_active",
+            });
+        }
+        catch (error) {
+            await restoreFiles(snapshots);
+            throw error;
+        }
+    }
+    return results;
+}
+export async function createLocalSetupEngine(options) {
+    const root = await realpath(path.resolve(options.root));
+    const setupId = options.setupId;
+    const plans = new Map();
+    const rememberPlan = (plan) => {
+        plans.delete(plan.fingerprint);
+        plans.set(plan.fingerprint, plan);
+        while (plans.size > 20) {
+            const oldest = plans.keys().next().value;
+            if (!oldest)
+                break;
+            plans.delete(oldest);
+        }
+    };
+    const resolvePlan = async (fingerprint) => {
+        const cached = plans.get(fingerprint);
+        if (cached)
+            return cached;
+        const saved = await readSetupPlan(root, fingerprint, setupId);
+        rememberPlan(saved);
+        return saved;
+    };
+    const analyze = async () => {
+        const [project, discovery] = await Promise.all([
+            readProjectMetadata(root),
+            scanProject(root),
+        ]);
+        return {
+            project,
+            discovery,
+            integrationScopes: discoverIntegrationScopes(discovery),
+            privacy: {
+                sourceContentReturned: false,
+                environmentFilesRead: false,
+                absolutePathsReturned: false,
+                credentialsReturned: false,
+            },
+        };
+    };
+    const applyReviewedPlan = async (plan) => {
+        let current = null;
+        try {
+            current = await readSetupPlan(root, undefined, plan.setupId);
+        }
+        catch (error) {
+            if (!(error instanceof LocalSetupEngineError) ||
+                !["plan_not_found", "legacy_plan_requires_replan"].includes(error.code)) {
+                throw error;
+            }
+            if (error.code === "legacy_plan_requires_replan") {
+                for (const generated of plan.generatedFiles) {
+                    try {
+                        await readFile(path.join(root, generated.path), "utf8");
+                        throw new LocalSetupEngineError("generated_file_conflict", "An existing generated file requires manual review before migration");
+                    }
+                    catch (fileError) {
+                        if (fileError instanceof LocalSetupEngineError)
+                            throw fileError;
+                        if (fileError.code !== "ENOENT") {
+                            throw fileError;
+                        }
+                    }
+                }
+            }
+        }
+        if (current && current.fingerprint !== plan.fingerprint) {
+            const inspected = await inspectSetupPlanFiles(current, root);
+            if (inspected.some(({ present, matches }) => !present || !matches)) {
+                throw new LocalSetupEngineError("generated_file_conflict", "An existing generated file changed and will not be overwritten");
+            }
+            const applied = await applySetupPlan(plan, root, {
+                write: true,
+                force: true,
+            });
+            await resetSetupCompletionState(plan, root);
+            return applied;
+        }
+        if (!current) {
+            const applied = await applySetupPlan(plan, root, {
+                write: true,
+                force: true,
+            });
+            await resetSetupCompletionState(plan, root);
+            return applied;
+        }
+        return applySetupPlan(plan, root, { write: true });
+    };
+    return {
+        analyze,
+        async plan(selection) {
+            try {
+                const saved = await readSetupPlan(root, undefined, setupId);
+                if (planMatchesSelection(saved, selection)) {
+                    const verification = await verifySetup(root, saved);
+                    if (verification.sourceBackedComplete) {
+                        rememberPlan(saved);
+                        return {
+                            plan: saved,
+                            applyPreview: await applySetupPlan(saved, root),
+                        };
+                    }
+                }
+            }
+            catch (error) {
+                if (!(error instanceof LocalSetupEngineError) ||
+                    !["plan_not_found", "legacy_plan_requires_replan"].includes(error.code)) {
+                    throw error;
+                }
+            }
+            const analysis = await analyze();
+            const plan = createSetupPlan(analysis.discovery, {
+                ...analysis.project,
+                integrationScope: {
+                    direction: selection.direction,
+                    protocol: selection.protocol,
+                },
+                contractFiles: selection.contractFiles ?? [],
+                ...(selection.findingIds ? { findingIds: selection.findingIds } : {}),
+                ...(setupId ? { setupId } : {}),
+            });
+            rememberPlan(plan);
+            return { plan, applyPreview: await applySetupPlan(plan, root) };
+        },
+        async applyGenerated(input) {
+            if (input.confirmation !== "write_generated_setup") {
+                throw new LocalSetupEngineError("confirmation_required", "Exact generated-setup confirmation is required");
+            }
+            return applySetupPlan(await resolvePlan(input.planFingerprint), root, {
+                write: true,
+            });
+        },
+        async replaceGenerated(input) {
+            if (input.confirmation !== "replace_generated_setup") {
+                throw new LocalSetupEngineError("confirmation_required", "Exact replacement confirmation is required");
+            }
+            const previous = await readSetupPlan(root, input.previousPlanFingerprint, setupId);
+            const next = await resolvePlan(input.planFingerprint);
+            if (JSON.stringify(previous.generatedFiles.map(({ path: file }) => file)) !== JSON.stringify(next.generatedFiles.map(({ path: file }) => file))) {
+                throw new LocalSetupEngineError("generated_file_conflict", "A replacement cannot change generated file paths");
+            }
+            const previousFiles = await inspectSetupPlanFiles(previous, root);
+            if (previousFiles.some(({ present, matches }) => !present || !matches)) {
+                throw new LocalSetupEngineError("generated_file_conflict", "A generated file changed after the previous plan was applied");
+            }
+            const applied = await applySetupPlan(next, root, {
+                write: true,
+                force: true,
+            });
+            await resetSetupCompletionState(next, root);
+            return applied;
+        },
+        async recordEvidence(input) {
+            if (input.confirmation !== "record_source_evidence") {
+                throw new LocalSetupEngineError("confirmation_required", "Exact source-evidence confirmation is required");
+            }
+            const plan = await resolvePlan(input.planFingerprint);
+            const selectedFiles = new Set(input.implementationFiles.map((file) => file.split(path.sep).join("/").replace(/^\.\//, "")));
+            const actions = operatorReviewableSetupActions(plan).filter((action) => action.file && selectedFiles.has(action.file));
+            if (actions.length === 0) {
+                throw new LocalSetupEngineError("no_matching_actions", "No planned instrumentation action matches the implementation files");
+            }
+            await recordSourceBackedSetupEvidence(plan, root, actions.map(({ id }) => id), {
+                write: true,
+                expectedStateFingerprint: input.expectedStateFingerprint,
+                ...(input.note ? { evidence: input.note } : {}),
+            });
+            return {
+                applied: true,
+                planFingerprint: plan.fingerprint,
+                recordedActions: actions.map(({ file }) => ({
+                    file: file ?? null,
+                    status: "recorded",
+                })),
+            };
+        },
+        async applyLocal(input) {
+            try {
+                return await withSetupProjectLock(root, ".seamward/setup-apply.lock", "Local setup apply is already in progress", async () => {
+                    const plan = await resolvePlan(input.planFingerprint);
+                    const actions = operatorReviewableSetupActions(plan);
+                    let current = null;
+                    try {
+                        current = await readSetupPlan(root, undefined, setupId);
+                    }
+                    catch (error) {
+                        if (!(error instanceof LocalSetupEngineError) ||
+                            !["plan_not_found", "legacy_plan_requires_replan"].includes(error.code)) {
+                            throw error;
+                        }
+                    }
+                    if (current?.fingerprint === plan.fingerprint) {
+                        const existingVerification = await verifySetup(root, plan);
+                        const existingState = await inspectSetupCompletionState(plan, root);
+                        const actionIds = new Set(actions.map(({ id }) => id));
+                        if (existingVerification.sourceBackedComplete &&
+                            existingState.state.completedActions
+                                .filter(({ actionId }) => actionIds.has(actionId))
+                                .every(({ verification }) => verification?.exitCode === 0)) {
+                            return {
+                                status: "verified",
+                                files: [],
+                                verification: existingVerification,
+                            };
+                        }
+                    }
+                    const snapshots = await snapshotFiles(root, await setupMutationFiles(root, plan));
+                    try {
+                        const dependency = await readCollectorDependency(root);
+                        if (!dependency.present) {
+                            await installCollectorDependency(root, plan);
+                        }
+                        const applied = await applyReviewedPlan(plan);
+                        const source = await applyPlannedSourceInstrumentation(plan, root);
+                        if (source.unsupported.length > 0) {
+                            await restoreFiles(snapshots);
+                            return {
+                                status: "source_changes_required",
+                                files: [],
+                                sourceChanges: source.unsupported,
+                                verification: await verifySetup(root, plan),
+                            };
+                        }
+                        const projectVerification = await runProjectVerification(root, plan);
+                        if (actions.length > 0) {
+                            const completion = await inspectSetupCompletionState(plan, root);
+                            await recordSourceBackedSetupEvidence(plan, root, actions.map(({ id }) => id), {
+                                write: true,
+                                expectedStateFingerprint: completion.fingerprint,
+                                evidence: "coding_agent_reviewed_setup",
+                                verification: projectVerification,
+                            });
+                        }
+                        return {
+                            status: "verified",
+                            files: [...new Set([...applied.files, ...source.changedFiles])],
+                            verification: await verifySetup(root, plan),
+                        };
+                    }
+                    catch (error) {
+                        await restoreFiles(snapshots);
+                        if (error instanceof LocalSetupEngineError)
+                            throw error;
+                        throw new LocalSetupEngineError("verification_failed", "The local setup could not be verified and all project changes were restored", { cause: error });
+                    }
+                });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    /local setup apply is already in progress/i.test(error.message)) {
+                    throw new LocalSetupEngineError("apply_in_progress", "Another local setup apply is already in progress");
+                }
+                if (error instanceof LocalSetupEngineError)
+                    throw error;
+                throw error;
+            }
+        },
+        async verify(input) {
+            return verifySetup(root, await resolvePlan(input.planFingerprint));
+        },
+    };
+}
+//# sourceMappingURL=setup-engine.js.map