@cogineai/dearharness 0.1.0

package/dist/extensions/loader.js

@@ -0,0 +1,58 @@
+import { pathToFileURL } from 'node:url';
+import { resolveWorkspacePath } from '../tools/path.js';
+import { policyInstructionsExtension } from './builtin/policy-instructions.js';
+const BUILTIN_EXTENSIONS = {
+    'policy-instructions': policyInstructionsExtension
+};
+async function importExtension(specifier, cwd) {
+    if (specifier.startsWith('builtin:')) {
+        const builtin = BUILTIN_EXTENSIONS[specifier.slice('builtin:'.length)];
+        if (!builtin) {
+            throw new Error(`Unknown built-in extension: ${specifier}`);
+        }
+        return builtin;
+    }
+    if (specifier.startsWith('.')) {
+        const { targetRealPath } = await resolveWorkspacePath(cwd, specifier);
+        try {
+            const mod = await import(pathToFileURL(targetRealPath).href);
+            return (mod.default ?? mod.extension);
+        }
+        catch (error) {
+            throw new Error(`Failed to load extension ${specifier}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new Error(`Unsupported extension specifier in Phase 2: ${specifier}`);
+}
+export async function loadExtensions(cwd, specifiers) {
+    const loaded = [];
+    const names = new Set();
+    for (const specifier of specifiers) {
+        const extension = await importExtension(specifier, cwd);
+        if (!extension || typeof extension.name !== 'string') {
+            throw new Error(`Extension ${specifier} must export a named CliqExtension`);
+        }
+        if (extension.instructionSources !== undefined && !Array.isArray(extension.instructionSources)) {
+            throw new Error(`Extension ${specifier} has invalid instructionSources, expected array`);
+        }
+        if ((extension.instructionSources ?? []).some((source) => typeof source !== 'function')) {
+            throw new Error(`Extension ${specifier} has invalid instructionSource item, expected function`);
+        }
+        if (extension.hooks !== undefined && !Array.isArray(extension.hooks)) {
+            throw new Error(`Extension ${specifier} has invalid hooks, expected array`);
+        }
+        if ((extension.hooks ?? []).some((hook) => !hook || typeof hook !== 'object' || Array.isArray(hook))) {
+            throw new Error(`Extension ${specifier} has invalid hook item, expected object`);
+        }
+        if (names.has(extension.name)) {
+            throw new Error(`duplicate extension name: ${extension.name}`);
+        }
+        names.add(extension.name);
+        loaded.push({
+            name: extension.name,
+            instructionSources: extension.instructionSources ?? [],
+            hooks: extension.hooks ?? []
+        });
+    }
+    return loaded;
+}

package/dist/extensions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/harness/install-applicator.js

@@ -0,0 +1,126 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { collectPlannedManagedPaths, isPathOwnedByPackage, normalizeInstallPath, } from './install-plan.js';
+function resolveInside(root, relativeInput) {
+    if (path.isAbsolute(relativeInput)) {
+        throw new Error(`path must be relative: ${relativeInput}`);
+    }
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`path must stay inside ${root}: ${relativeInput}`);
+    }
+    return target;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function managedBlock(packageId, resourceId, content) {
+    const key = `${packageId}/${resourceId}`;
+    return [
+        `<!-- dearharness:begin ${key} -->`,
+        content.trimEnd(),
+        `<!-- dearharness:end ${key} -->`,
+        '',
+    ].join('\n');
+}
+function upsertManagedBlock(existing, packageId, resourceId, content) {
+    const key = `${packageId}/${resourceId}`;
+    const begin = `<!-- dearharness:begin ${key} -->`;
+    const end = `<!-- dearharness:end ${key} -->`;
+    const block = managedBlock(packageId, resourceId, content);
+    const pattern = new RegExp(`${escapeRegExp(begin)}[\\s\\S]*?${escapeRegExp(end)}\\n?`);
+    if (pattern.test(existing)) {
+        return existing.replace(pattern, block);
+    }
+    const prefix = existing.trimEnd();
+    return prefix.length > 0 ? `${prefix}\n\n${block}` : block;
+}
+async function projectWorkspaceFileToCandidate(source, candidateWorkspace, packageId, lockfile) {
+    for (const workspaceFile of source.validation.workspaceFiles) {
+        const sourcePath = resolveInside(source.rootPath, workspaceFile.source);
+        const targetPath = resolveInside(candidateWorkspace, workspaceFile.target);
+        const targetRelativePath = normalizeInstallPath(workspaceFile.target);
+        if (workspaceFile.mergePolicy === 'append_managed_block') {
+            const sourceContent = await fs.readFile(sourcePath, 'utf8');
+            const existingContent = (await pathExists(targetPath)) ? await fs.readFile(targetPath, 'utf8') : '';
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            await fs.writeFile(targetPath, upsertManagedBlock(existingContent, packageId, workspaceFile.id, sourceContent));
+            continue;
+        }
+        if (workspaceFile.mergePolicy === 'replace_managed_file') {
+            if ((await pathExists(targetPath)) && !isPathOwnedByPackage(lockfile, targetRelativePath, packageId)) {
+                continue;
+            }
+            await fs.mkdir(path.dirname(targetPath), { recursive: true });
+            await fs.copyFile(sourcePath, targetPath);
+            continue;
+        }
+        if (await pathExists(targetPath)) {
+            continue;
+        }
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.copyFile(sourcePath, targetPath);
+    }
+}
+async function copyDeclaredSkillsToCandidate(source, candidateWorkspace) {
+    if (!source.validation.ok) {
+        return;
+    }
+    for (const skill of source.validation.skills) {
+        const sourcePath = resolveInside(source.rootPath, skill.source);
+        const targetPath = resolveInside(candidateWorkspace, path.join('skills', skill.id));
+        await fs.rm(targetPath, { recursive: true, force: true });
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.cp(sourcePath, targetPath, { recursive: true });
+    }
+}
+export const deterministicInstallApplicator = async ({ source, targetWorkspace, candidateWorkspace, lockfile, }) => {
+    if (!source.validation.ok) {
+        return [
+            {
+                mode: 'deterministic',
+                status: 'skipped',
+                summary: 'Skipped deterministic projection because source validation failed.',
+                managedPaths: [],
+            },
+        ];
+    }
+    const packageId = source.validation.package?.id ?? 'unknown-package';
+    await copyDeclaredSkillsToCandidate(source, candidateWorkspace);
+    await projectWorkspaceFileToCandidate(source, candidateWorkspace, packageId, lockfile);
+    return [
+        {
+            mode: 'deterministic',
+            status: 'applied',
+            summary: 'Projected declared skills and workspace files into the candidate workspace.',
+            managedPaths: await collectPlannedManagedPaths(source.validation, targetWorkspace, lockfile),
+        },
+    ];
+};
+function normalizeManagedPaths(paths) {
+    if (!paths)
+        return [];
+    return paths.map(normalizeInstallPath).filter(Boolean);
+}
+export async function runInstallApplicators(context, applicators) {
+    const steps = [];
+    for (const applicator of applicators) {
+        for (const step of await applicator(context)) {
+            steps.push({
+                ...step,
+                managedPaths: normalizeManagedPaths(step.managedPaths),
+            });
+        }
+    }
+    return steps;
+}

package/dist/harness/install-apply.js

@@ -0,0 +1,156 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { verifyAppliedInstall } from './install-verification.js';
+import { upsertInstallLockfileEntry } from './lockfile.js';
+export class InstallApplyError extends Error {
+    rollback;
+    constructor(error, rollback) {
+        const message = rollback.ok
+            ? `install apply failed and rollback succeeded: ${renderError(error)}`
+            : `install apply failed and rollback had errors: ${renderError(error)}`;
+        super(message, { cause: error });
+        this.name = 'InstallApplyError';
+        this.rollback = rollback;
+    }
+}
+function renderError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function resolveInside(root, relativeInput) {
+    if (path.isAbsolute(relativeInput)) {
+        throw new Error(`path must be relative: ${relativeInput}`);
+    }
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`path must stay inside ${root}: ${relativeInput}`);
+    }
+    return target;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function uniquePaths(paths) {
+    return [...new Set(paths)].sort((left, right) => left.localeCompare(right));
+}
+async function collectExistingParentDirectories(root, relativePath) {
+    const directories = new Set();
+    let current = path.dirname(relativePath);
+    while (current && current !== '.') {
+        if (await pathExists(resolveInside(root, current))) {
+            directories.add(current);
+        }
+        current = path.dirname(current);
+    }
+    return directories;
+}
+async function createSnapshot(targetWorkspace, backupRoot, relativePath) {
+    const targetPath = resolveInside(targetWorkspace, relativePath);
+    const backupPath = resolveInside(backupRoot, relativePath);
+    const existed = await pathExists(targetPath);
+    const existingParentDirectories = await collectExistingParentDirectories(targetWorkspace, relativePath);
+    if (existed) {
+        await fs.mkdir(path.dirname(backupPath), { recursive: true });
+        await fs.copyFile(targetPath, backupPath);
+    }
+    return { path: relativePath, existed, backupPath, existingParentDirectories };
+}
+async function createApplySnapshots(targetWorkspace, backupRoot, plannedChanges) {
+    const targetPaths = uniquePaths([
+        ...plannedChanges.map((change) => change.path),
+        '.dearclaw/install-lock.json',
+    ]);
+    const snapshots = [];
+    for (const targetPath of targetPaths) {
+        snapshots.push(await createSnapshot(targetWorkspace, backupRoot, targetPath));
+    }
+    return snapshots;
+}
+async function removeEmptyParents(root, relativePath, existingParentDirectories) {
+    let current = path.dirname(relativePath);
+    while (current && current !== '.') {
+        if (existingParentDirectories.has(current)) {
+            return;
+        }
+        try {
+            await fs.rmdir(resolveInside(root, current));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTEMPTY') {
+                throw error;
+            }
+            return;
+        }
+        current = path.dirname(current);
+    }
+}
+async function restoreSnapshot(targetWorkspace, snapshot) {
+    const targetPath = resolveInside(targetWorkspace, snapshot.path);
+    if (snapshot.existed) {
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.copyFile(snapshot.backupPath, targetPath);
+        return;
+    }
+    await fs.rm(targetPath, { recursive: true, force: true });
+    await removeEmptyParents(targetWorkspace, snapshot.path, snapshot.existingParentDirectories);
+}
+async function rollbackSnapshots(targetWorkspace, snapshots) {
+    const restoredPaths = [];
+    const errors = [];
+    for (const snapshot of [...snapshots].reverse()) {
+        try {
+            await restoreSnapshot(targetWorkspace, snapshot);
+            restoredPaths.push(snapshot.path);
+        }
+        catch (error) {
+            errors.push({ path: snapshot.path, error: renderError(error) });
+        }
+    }
+    return { ok: errors.length === 0, restoredPaths, errors };
+}
+async function applyWorkspaceTransaction(transaction, plannedChanges, copyFile) {
+    for (const change of plannedChanges) {
+        const targetPath = resolveInside(transaction.targetWorkspace, change.path);
+        if (change.kind === 'delete') {
+            await fs.rm(targetPath, { recursive: true, force: true });
+            continue;
+        }
+        const sourcePath = resolveInside(transaction.candidateWorkspace, change.path);
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await copyFile(sourcePath, targetPath);
+    }
+}
+export async function applyInstallWithRollback(options) {
+    const backupRoot = path.join(options.transaction.stagingPath, 'apply-backup');
+    const snapshots = await createApplySnapshots(options.transaction.targetWorkspace, backupRoot, options.plannedChanges);
+    const copyFile = options.applyCopyFile ?? fs.copyFile;
+    const writeLockfileEntry = options.writeLockfileEntry ?? upsertInstallLockfileEntry;
+    try {
+        await applyWorkspaceTransaction(options.transaction, options.plannedChanges, copyFile);
+        await writeLockfileEntry(options.transaction.targetWorkspace, options.lockfile, options.plannedLockfileEntry);
+        const verification = await verifyAppliedInstall({
+            targetWorkspace: options.transaction.targetWorkspace,
+            candidateWorkspace: options.transaction.candidateWorkspace,
+            plannedChanges: options.plannedChanges,
+            plannedLockfileEntry: options.plannedLockfileEntry,
+        });
+        if (!verification.ok) {
+            throw new Error(`post-apply verification failed: ${JSON.stringify(verification.issues)}`);
+        }
+        return { verification };
+    }
+    catch (error) {
+        const rollback = await rollbackSnapshots(options.transaction.targetWorkspace, snapshots);
+        throw new InstallApplyError(error, rollback);
+    }
+    finally {
+        await fs.rm(backupRoot, { recursive: true, force: true });
+    }
+}

package/dist/harness/install-plan.js

@@ -0,0 +1,154 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+export function normalizeInstallPath(value) {
+    return value.replace(/\\/g, '/').split('/').filter(Boolean).join('/');
+}
+function pathsOverlap(left, right) {
+    if (!left || !right)
+        return false;
+    return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+function uniqueSorted(values) {
+    return [...new Set(values.map(normalizeInstallPath).filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}
+function resolveInside(root, relativeInput) {
+    if (path.isAbsolute(relativeInput)) {
+        throw new Error(`path must be relative: ${relativeInput}`);
+    }
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`path must stay inside ${root}: ${relativeInput}`);
+    }
+    return target;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function findManagedOwner(lockfile, targetPath) {
+    const normalizedTarget = normalizeInstallPath(targetPath);
+    for (const installed of lockfile.installed) {
+        for (const managedPath of installed.managedPaths) {
+            if (pathsOverlap(normalizeInstallPath(managedPath), normalizedTarget)) {
+                return { packageId: installed.packageId, managedPath: normalizeInstallPath(managedPath) };
+            }
+        }
+    }
+    return null;
+}
+export function isPathOwnedByPackage(lockfile, targetPath, packageId) {
+    return findManagedOwner(lockfile, targetPath)?.packageId === packageId;
+}
+export async function collectPlannedManagedPaths(validation, targetWorkspace, lockfile) {
+    const packageSummary = validation.package;
+    if (!validation.ok || !packageSummary)
+        return [];
+    const managedPaths = validation.skills.map((skill) => `skills/${skill.id}`);
+    for (const workspaceFile of validation.workspaceFiles) {
+        const targetPath = normalizeInstallPath(workspaceFile.target);
+        const targetExists = await pathExists(resolveInside(targetWorkspace, targetPath));
+        const ownedByPackage = isPathOwnedByPackage(lockfile, targetPath, packageSummary.id);
+        if (workspaceFile.mergePolicy === 'append_managed_block') {
+            managedPaths.push(targetPath);
+        }
+        else if (!targetExists || ownedByPackage) {
+            managedPaths.push(targetPath);
+        }
+    }
+    return uniqueSorted(managedPaths);
+}
+export async function buildPlannedLockfileEntry(source, targetWorkspace, lockfile) {
+    const packageSummary = source.validation.package;
+    if (!source.validation.ok || !packageSummary)
+        return null;
+    return {
+        packageId: packageSummary.id,
+        packageType: packageSummary.type,
+        version: packageSummary.version,
+        manifestUrl: source.input,
+        sha256: source.sha256,
+        installedBy: 'dearharness',
+        managedPaths: await collectPlannedManagedPaths(source.validation, targetWorkspace, lockfile),
+    };
+}
+function addConflict(conflicts, seen, conflict) {
+    const key = JSON.stringify(conflict);
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    conflicts.push(conflict);
+}
+export async function detectInstallPlanConflicts(source, targetWorkspace, lockfile) {
+    const conflicts = [];
+    const seen = new Set();
+    for (const error of lockfile.errors) {
+        addConflict(conflicts, seen, { kind: 'lockfile_invalid', path: lockfile.path, error });
+    }
+    const packageSummary = source.validation.package;
+    if (!source.validation.ok || !packageSummary) {
+        return conflicts;
+    }
+    for (const operation of source.validation.configOperations) {
+        if (operation.optional)
+            continue;
+        addConflict(conflicts, seen, {
+            kind: 'config_operation_not_applied',
+            op: operation.op,
+            ...(operation.agentId ? { agentId: operation.agentId } : {}),
+        });
+    }
+    for (const pluginRequirement of source.validation.pluginRequirements) {
+        if (!pluginRequirement.required)
+            continue;
+        addConflict(conflicts, seen, {
+            kind: 'required_plugin_not_verified',
+            pluginId: pluginRequirement.id,
+            installPolicy: pluginRequirement.installPolicy,
+        });
+    }
+    for (const plannedPath of await collectPlannedManagedPaths(source.validation, targetWorkspace, lockfile)) {
+        const owner = findManagedOwner(lockfile, plannedPath);
+        if (owner && owner.packageId !== packageSummary.id) {
+            addConflict(conflicts, seen, {
+                kind: 'target_managed_by_other_package',
+                path: plannedPath,
+                ownerPackageId: owner.packageId,
+            });
+        }
+    }
+    for (const skill of source.validation.skills) {
+        const targetPath = `skills/${skill.id}`;
+        const owner = findManagedOwner(lockfile, targetPath);
+        if (owner)
+            continue;
+        if (await pathExists(resolveInside(targetWorkspace, targetPath))) {
+            addConflict(conflicts, seen, { kind: 'target_exists_unmanaged', path: targetPath });
+        }
+    }
+    for (const workspaceFile of source.validation.workspaceFiles) {
+        if (workspaceFile.mergePolicy !== 'replace_managed_file')
+            continue;
+        const targetPath = normalizeInstallPath(workspaceFile.target);
+        const owner = findManagedOwner(lockfile, targetPath);
+        if (owner) {
+            if (owner.packageId !== packageSummary.id) {
+                addConflict(conflicts, seen, {
+                    kind: 'target_managed_by_other_package',
+                    path: targetPath,
+                    ownerPackageId: owner.packageId,
+                });
+            }
+            continue;
+        }
+        if (await pathExists(resolveInside(targetWorkspace, targetPath))) {
+            addConflict(conflicts, seen, { kind: 'replace_managed_file_without_owner', path: targetPath });
+        }
+    }
+    return conflicts;
+}

package/dist/harness/install-runner.js

@@ -0,0 +1,178 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { deterministicInstallApplicator, runInstallApplicators, } from './install-applicator.js';
+import { applyInstallWithRollback } from './install-apply.js';
+import { buildPlannedLockfileEntry, detectInstallPlanConflicts, findManagedOwner, } from './install-plan.js';
+import { readInstallLockfile } from './lockfile.js';
+import { materializeHarnessSource } from './source.js';
+import { createWorkspaceTransaction, diffWorkspaceTransaction, } from './transaction.js';
+function resolveInside(root, relativeInput) {
+    if (path.isAbsolute(relativeInput)) {
+        throw new Error(`path must be relative: ${relativeInput}`);
+    }
+    const target = path.resolve(root, relativeInput);
+    const relative = path.relative(root, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`path must stay inside ${root}: ${relativeInput}`);
+    }
+    return target;
+}
+async function pathExists(target) {
+    try {
+        await fs.access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeManagedPath(value) {
+    if (value.includes('\0') || path.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value)) {
+        throw new Error(`managed path must be relative: ${value}`);
+    }
+    const parts = value.replace(/\\/g, '/').split('/').filter(Boolean);
+    if (parts.length === 0 || parts.some((part) => part === '.' || part === '..')) {
+        throw new Error(`managed path must stay inside target workspace: ${value}`);
+    }
+    return parts.join('/');
+}
+function uniqueSortedManagedPaths(values) {
+    return [...new Set(values.map(normalizeManagedPath))].sort((left, right) => left.localeCompare(right));
+}
+function collectApplicatorManagedPaths(steps) {
+    return uniqueSortedManagedPaths(steps.flatMap((step) => step.managedPaths ?? []));
+}
+function isCoveredByBasePath(targetPath, basePaths) {
+    return basePaths.some((basePath) => targetPath === basePath || targetPath.startsWith(`${basePath}/`));
+}
+function isCoveredByManagedPath(targetPath, managedPaths) {
+    return managedPaths.some((managedPath) => targetPath === managedPath || targetPath.startsWith(`${managedPath}/`));
+}
+function mergeManagedPaths(entry, applicatorManagedPaths) {
+    return {
+        ...entry,
+        managedPaths: uniqueSortedManagedPaths([...entry.managedPaths, ...applicatorManagedPaths]),
+    };
+}
+function addConflict(conflicts, seen, conflict) {
+    const key = JSON.stringify(conflict);
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    conflicts.push(conflict);
+}
+async function detectApplicatorManagedPathConflicts(packageId, managedPaths, targetWorkspace, lockfile) {
+    const conflicts = [];
+    const seen = new Set();
+    for (const managedPath of managedPaths) {
+        const owner = findManagedOwner(lockfile, managedPath);
+        if (owner) {
+            if (owner.packageId !== packageId) {
+                addConflict(conflicts, seen, {
+                    kind: 'target_managed_by_other_package',
+                    path: managedPath,
+                    ownerPackageId: owner.packageId,
+                });
+            }
+            continue;
+        }
+        if (await pathExists(resolveInside(targetWorkspace, managedPath))) {
+            addConflict(conflicts, seen, { kind: 'target_exists_unmanaged', path: managedPath });
+        }
+    }
+    return conflicts;
+}
+function detectUnownedPlannedChangeConflicts(plannedChanges, plannedLockfileEntry) {
+    if (!plannedLockfileEntry)
+        return [];
+    const conflicts = [];
+    const seen = new Set();
+    for (const change of plannedChanges) {
+        if (isCoveredByManagedPath(change.path, plannedLockfileEntry.managedPaths)) {
+            continue;
+        }
+        addConflict(conflicts, seen, { kind: 'planned_change_without_ownership', path: change.path });
+    }
+    return conflicts;
+}
+function describePlannedConfigOperations(source) {
+    return source.validation.configOperations.map((operation) => ({
+        kind: 'openclaw_config_operation',
+        op: operation.op,
+        ...(operation.agentId ? { agentId: operation.agentId } : {}),
+        optional: operation.optional,
+    }));
+}
+export async function executeHarnessInstall(options) {
+    const materialize = options.materializeHarnessSource ?? materializeHarnessSource;
+    const source = await materialize(options.source, { expectedSha256: options.expectedSha256 });
+    try {
+        const transaction = await createWorkspaceTransaction(options.targetWorkspace);
+        try {
+            const lockfile = await readInstallLockfile(transaction.targetWorkspace);
+            const baseConflicts = await detectInstallPlanConflicts(source, transaction.targetWorkspace, lockfile);
+            const applicators = [
+                deterministicInstallApplicator,
+                ...(source.validation.ok ? options.additionalApplicators ?? [] : []),
+            ];
+            const applicatorSteps = await runInstallApplicators({
+                source,
+                targetWorkspace: transaction.targetWorkspace,
+                candidateWorkspace: transaction.candidateWorkspace,
+                lockfile,
+            }, applicators);
+            const basePlannedLockfileEntry = await buildPlannedLockfileEntry(source, transaction.targetWorkspace, lockfile);
+            const applicatorManagedPaths = collectApplicatorManagedPaths(applicatorSteps);
+            const baseManagedPaths = basePlannedLockfileEntry?.managedPaths ?? [];
+            const additionalManagedPaths = applicatorManagedPaths.filter((managedPath) => !isCoveredByBasePath(managedPath, baseManagedPaths));
+            const packageId = source.validation.package?.id;
+            const applicatorConflicts = source.validation.ok && packageId
+                ? await detectApplicatorManagedPathConflicts(packageId, additionalManagedPaths, transaction.targetWorkspace, lockfile)
+                : [];
+            const plannedChanges = await diffWorkspaceTransaction(transaction);
+            const plannedLockfileEntry = basePlannedLockfileEntry
+                ? mergeManagedPaths(basePlannedLockfileEntry, applicatorManagedPaths)
+                : null;
+            const ownershipConflicts = detectUnownedPlannedChangeConflicts(plannedChanges, plannedLockfileEntry);
+            const conflicts = [...baseConflicts, ...applicatorConflicts, ...ownershipConflicts];
+            const canApply = source.validation.ok && conflicts.length === 0 && plannedLockfileEntry !== null;
+            let applied = false;
+            let verification = null;
+            if (options.mode === 'apply' && canApply && plannedLockfileEntry) {
+                const applyResult = await applyInstallWithRollback({
+                    transaction,
+                    plannedChanges,
+                    lockfile,
+                    plannedLockfileEntry,
+                });
+                verification = applyResult.verification;
+                applied = true;
+            }
+            return {
+                command: 'install',
+                dryRun: options.mode === 'dry_run',
+                applied,
+                targetWorkspace: transaction.targetWorkspace,
+                source: {
+                    input: source.input,
+                    kind: source.kind,
+                    sha256: source.sha256,
+                },
+                validation: source.validation,
+                applicatorSteps,
+                plannedChanges,
+                plannedOperations: describePlannedConfigOperations(source),
+                conflicts,
+                canApply,
+                plannedLockfileEntry,
+                verification,
+            };
+        }
+        finally {
+            await transaction.cleanup();
+        }
+    }
+    finally {
+        await source.cleanup();
+    }
+}