skill-flow 1.0.4 → 1.0.6

package/dist/services/source-service.js

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
 import path from "node:path";
 import { copyDirectory, ensureDir, hashDirectory, pathExists, readJsonFile, removePath } from "../utils/fs.js";
 import { installClawHubSkill, } from "../utils/clawhub.js";
@@ -13,10 +15,14 @@ export class SourceService {
         this.inventoryService = inventoryService;
     }
     async addSource(locator, options = {}) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
-        const resolved = await this.resolveSource(locator, options);
+        const { manifest, lockFile } = await this.store.readState();
+        const resolved = this.resolveUniqueLocalSource(await this.resolveSource(locator, options), manifest.sources);
+        if (manifest.sources.some((source) => source.id === resolved.sourceId && source.locator === resolved.locator)) {
+            return fail({
+                code: "SOURCE_EXISTS",
+                message: `Skills group '${formatGroupLabel({ id: resolved.sourceId, locator: resolved.locator, displayName: resolved.displayName })}' is already registered with id '${resolved.sourceId}'.`,
+            });
+        }
         if (manifest.sources.some((source) => source.id === resolved.sourceId)) {
             return fail({
                 code: "SOURCE_EXISTS",
@@ -48,8 +54,7 @@ export class SourceService {
         manifest.bindings[resolved.sourceId] = { targets: {} };
         lockFile.sources.push(snapshot.data.lock);
         lockFile.leafInventory.push(...snapshot.data.leafs);
-        await this.store.writeManifest(manifest);
-        await this.store.writeLock(lockFile);
+        await this.store.writeState(manifest, lockFile);
         return ok({
             manifest: snapshot.data.manifest,
             lock: snapshot.data.lock,
@@ -58,9 +63,7 @@ export class SourceService {
         }, snapshot.warnings);
     }
     async updateSources(sourceIds) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         const selectedIds = sourceIds?.length
             ? sourceIds
             : manifest.sources.map((source) => source.id);
@@ -74,9 +77,43 @@ export class SourceService {
                     message: `Skills group id '${sourceId}' is not registered.`,
                 });
             }
-            let changed;
             try {
-                changed = await this.updateSource(source, currentLock);
+                const sourceChanged = await this.updateSource(source, currentLock);
+                const sourceMeta = {
+                    ...(source.requestedPath ? { requestedPath: source.requestedPath } : {}),
+                    ...(source.selectionMode ? { selectionMode: source.selectionMode } : {}),
+                };
+                if (!sourceChanged) {
+                    updated.push({
+                        sourceId,
+                        changed: false,
+                        addedLeafIds: [],
+                        removedLeafIds: [],
+                        invalidatedLeafIds: [],
+                        diffs: [],
+                        ...sourceMeta,
+                    });
+                    continue;
+                }
+                const snapshot = await this.buildSnapshot(source.kind, source.id, source.locator, source.displayName, currentLock.checkoutPath, source.requestedPath, {}, { allowEmptyLeafs: true });
+                if (!snapshot.ok) {
+                    return fail(snapshot.errors, snapshot.warnings);
+                }
+                const diff = this.buildSourceUpdateDiff(source, lockFile.leafInventory.filter((leaf) => leaf.sourceId === sourceId), snapshot.data.leafs, snapshot.data.lock.invalidLeafs);
+                lockFile.sources = lockFile.sources.map((item) => item.id === sourceId ? snapshot.data.lock : item);
+                lockFile.leafInventory = [
+                    ...lockFile.leafInventory.filter((leaf) => leaf.sourceId !== sourceId),
+                    ...snapshot.data.leafs,
+                ];
+                updated.push({
+                    sourceId,
+                    changed: sourceChanged,
+                    addedLeafIds: diff.addedLeafIds,
+                    removedLeafIds: diff.removedLeafIds,
+                    invalidatedLeafIds: diff.invalidatedLeafIds,
+                    diffs: diff.diffs,
+                    ...sourceMeta,
+                });
             }
             catch (error) {
                 return fail({
@@ -88,45 +125,12 @@ export class SourceService {
                     message: `Unable to update skills group id '${sourceId}': ${String(error)}`,
                 });
             }
-            if (!changed) {
-                updated.push({
-                    sourceId,
-                    changed: false,
-                    addedLeafIds: [],
-                    removedLeafIds: [],
-                    invalidatedLeafIds: [],
-                });
-                continue;
-            }
-            const snapshot = await this.buildSnapshot(source.kind, source.id, source.locator, source.displayName, currentLock.checkoutPath, source.requestedPath, {}, { allowEmptyLeafs: true });
-            if (!snapshot.ok) {
-                return fail(snapshot.errors, snapshot.warnings);
-            }
-            const previousLeafs = lockFile.leafInventory.filter((leaf) => leaf.sourceId === sourceId);
-            const previousLeafIds = new Set(previousLeafs.map((leaf) => leaf.id));
-            const nextLeafIds = new Set(snapshot.data.leafs.map((leaf) => leaf.id));
-            const previousInvalidPaths = new Set(currentLock.invalidLeafs.map((leaf) => leaf.path));
-            const nextInvalidPaths = new Set(snapshot.data.lock.invalidLeafs.map((leaf) => leaf.path));
-            lockFile.sources = lockFile.sources.map((item) => item.id === sourceId ? snapshot.data.lock : item);
-            lockFile.leafInventory = [
-                ...lockFile.leafInventory.filter((leaf) => leaf.sourceId !== sourceId),
-                ...snapshot.data.leafs,
-            ];
-            updated.push({
-                sourceId,
-                changed: true,
-                addedLeafIds: [...nextLeafIds].filter((id) => !previousLeafIds.has(id)),
-                removedLeafIds: [...previousLeafIds].filter((id) => !nextLeafIds.has(id)),
-                invalidatedLeafIds: [...nextInvalidPaths].filter((value) => !previousInvalidPaths.has(value)),
-            });
         }
-        await this.store.writeLock(lockFile);
+        await this.store.writeState(manifest, lockFile);
         return ok({ updated });
     }
     async removeSource(sourceIds) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         const removed = [];
         for (const sourceId of sourceIds) {
             const currentSource = manifest.sources.find((source) => source.id === sourceId);
@@ -147,14 +151,11 @@ export class SourceService {
             }
             removed.push(sourceId);
         }
-        await this.store.writeManifest(manifest);
-        await this.store.writeLock(lockFile);
+        await this.store.writeState(manifest, lockFile);
         return ok({ removed });
     }
     async reconcileInventory(sourceIds, options = {}) {
-        await this.store.init();
-        const manifest = await this.store.readManifest();
-        const lockFile = await this.store.readLock();
+        const { manifest, lockFile } = await this.store.readState();
         const selectedIds = sourceIds?.length
             ? sourceIds
             : manifest.sources.map((source) => source.id);
@@ -204,8 +205,7 @@ export class SourceService {
             updatedSourceIds.push(sourceId);
         }
         if (updatedSourceIds.length > 0) {
-            await this.store.writeManifest(manifest);
-            await this.store.writeLock(lockFile);
+            await this.store.writeState(manifest, lockFile);
         }
         return ok({ updatedSourceIds });
     }
@@ -214,6 +214,147 @@ export class SourceService {
         const hasLegacyTargetNames = sourceDeployments.some((deployment) => path.basename(deployment.targetPath).startsWith(`${sourceId}--`));
         return hasGeneratedLeafs || hasLegacyTargetNames;
     }
+    buildSourceUpdateDiff(source, previousLeafs, nextLeafs, nextInvalidLeafs) {
+        const requestedPath = this.normalizeRequestedPath(source.requestedPath);
+        const requestedPathOption = requestedPath ? { requestedPath } : {};
+        const diffs = [];
+        const addedLeafIds = [];
+        const removedLeafIds = [];
+        const invalidatedLeafIds = [];
+        const matchedPreviousIds = new Set();
+        const matchedNextIds = new Set();
+        const nextById = new Map(nextLeafs.map((leaf) => [leaf.id, leaf]));
+        const nextInvalidPaths = new Set(nextInvalidLeafs.map((leaf) => leaf.path));
+        for (const previousLeaf of previousLeafs) {
+            const nextLeaf = nextById.get(previousLeaf.id);
+            if (!nextLeaf || previousLeaf.contentHash === nextLeaf.contentHash) {
+                continue;
+            }
+            diffs.push(this.createDiffItem("changed", source.id, nextLeaf, {
+                ...requestedPathOption,
+                previousLeafId: previousLeaf.id,
+                previousRelativePath: previousLeaf.relativePath,
+                previousContentHash: previousLeaf.contentHash,
+            }));
+            matchedPreviousIds.add(previousLeaf.id);
+            matchedNextIds.add(nextLeaf.id);
+        }
+        const previousByHash = new Map();
+        const nextByHash = new Map();
+        for (const previousLeaf of previousLeafs) {
+            if (matchedPreviousIds.has(previousLeaf.id)) {
+                continue;
+            }
+            const list = previousByHash.get(previousLeaf.contentHash) ?? [];
+            list.push(previousLeaf);
+            previousByHash.set(previousLeaf.contentHash, list);
+        }
+        for (const nextLeaf of nextLeafs) {
+            if (matchedNextIds.has(nextLeaf.id)) {
+                continue;
+            }
+            const list = nextByHash.get(nextLeaf.contentHash) ?? [];
+            list.push(nextLeaf);
+            nextByHash.set(nextLeaf.contentHash, list);
+        }
+        for (const contentHash of [...previousByHash.keys()].sort()) {
+            const previousGroup = previousByHash.get(contentHash) ?? [];
+            const nextGroup = nextByHash.get(contentHash) ?? [];
+            if (previousGroup.length !== 1 || nextGroup.length !== 1) {
+                continue;
+            }
+            const previousLeaf = previousGroup[0];
+            const nextLeaf = nextGroup[0];
+            if (previousLeaf.id === nextLeaf.id ||
+                !this.canClassifyAsMoved(requestedPath, previousLeaf.relativePath, nextLeaf.relativePath)) {
+                continue;
+            }
+            diffs.push(this.createDiffItem("moved", source.id, nextLeaf, {
+                ...requestedPathOption,
+                previousLeafId: previousLeaf.id,
+                previousRelativePath: previousLeaf.relativePath,
+                previousContentHash: previousLeaf.contentHash,
+            }));
+            matchedPreviousIds.add(previousLeaf.id);
+            matchedNextIds.add(nextLeaf.id);
+        }
+        for (const previousLeaf of previousLeafs) {
+            if (matchedPreviousIds.has(previousLeaf.id)) {
+                continue;
+            }
+            if (nextInvalidPaths.has(previousLeaf.relativePath)) {
+                diffs.push(this.createDiffItem("invalidated", source.id, previousLeaf, {
+                    ...requestedPathOption,
+                    previousLeafId: previousLeaf.id,
+                    previousRelativePath: previousLeaf.relativePath,
+                    previousContentHash: previousLeaf.contentHash,
+                }));
+                invalidatedLeafIds.push(previousLeaf.id);
+                matchedPreviousIds.add(previousLeaf.id);
+            }
+        }
+        for (const previousLeaf of previousLeafs) {
+            if (matchedPreviousIds.has(previousLeaf.id)) {
+                continue;
+            }
+            diffs.push(this.createDiffItem("removed", source.id, previousLeaf, {
+                ...requestedPathOption,
+                previousLeafId: previousLeaf.id,
+                previousRelativePath: previousLeaf.relativePath,
+                previousContentHash: previousLeaf.contentHash,
+            }));
+            removedLeafIds.push(previousLeaf.id);
+            matchedPreviousIds.add(previousLeaf.id);
+        }
+        for (const nextLeaf of nextLeafs) {
+            if (matchedNextIds.has(nextLeaf.id)) {
+                continue;
+            }
+            diffs.push(this.createDiffItem("added", source.id, nextLeaf, requestedPathOption));
+            addedLeafIds.push(nextLeaf.id);
+            matchedNextIds.add(nextLeaf.id);
+        }
+        return {
+            diffs,
+            addedLeafIds,
+            removedLeafIds,
+            invalidatedLeafIds,
+        };
+    }
+    createDiffItem(kind, sourceId, leaf, extras = {}) {
+        return {
+            kind,
+            sourceId,
+            leafId: leaf.id,
+            relativePath: leaf.relativePath,
+            contentHash: leaf.contentHash,
+            ...(extras.requestedPath ? { requestedPath: extras.requestedPath } : {}),
+            ...(extras.previousLeafId ? { previousLeafId: extras.previousLeafId } : {}),
+            ...(extras.previousRelativePath ? { previousRelativePath: extras.previousRelativePath } : {}),
+            ...(extras.previousContentHash ? { previousContentHash: extras.previousContentHash } : {}),
+        };
+    }
+    canClassifyAsMoved(requestedPath, previousRelativePath, nextRelativePath) {
+        if (!requestedPath) {
+            return true;
+        }
+        return (this.isWithinRequestedPath(previousRelativePath, requestedPath) &&
+            this.isWithinRequestedPath(nextRelativePath, requestedPath));
+    }
+    normalizeRequestedPath(requestedPath) {
+        if (!requestedPath) {
+            return undefined;
+        }
+        const normalized = requestedPath.replace(/^\.\/+/, "").replace(/\/+$/, "");
+        return normalized.length > 0 ? normalized : undefined;
+    }
+    isWithinRequestedPath(relativePath, requestedPath) {
+        const normalizedPath = this.normalizeRequestedPath(requestedPath);
+        if (!normalizedPath) {
+            return true;
+        }
+        return (relativePath === normalizedPath || relativePath.startsWith(`${normalizedPath}/`));
+    }
     async buildSnapshot(kind, sourceId, locator, displayName, checkoutPath, requestedPathOrOptions = undefined, addOptions = {}, maybeOptions = {}) {
         const requestedPath = typeof requestedPathOrOptions === "string" ? requestedPathOrOptions : undefined;
         const options = typeof requestedPathOrOptions === "string"
@@ -230,11 +371,14 @@ export class SourceService {
         })));
         if (((requestedPath && requestedMatches.length === 0) || scanned.leafs.length === 0) &&
             !options.allowEmptyLeafs) {
+            const emptyReason = scanned.skillFileCount === 0
+                ? " No SKILL.md files were found."
+                : "";
             return fail({
                 code: requestedPath ? "SOURCE_PATH_NOT_FOUND" : "NO_VALID_LEAFS",
                 message: requestedPath
                     ? `Source '${displayName}' does not contain a valid skill at '${requestedPath}'.`
-                    : `Source '${displayName}' has no valid skills.`,
+                    : `Source '${displayName}' has no valid skills.${emptyReason}`,
             }, scanned.invalidLeafs.map((leaf) => ({
                 code: "INVALID_LEAF",
                 message: `${leaf.path}: ${leaf.reason}`,
@@ -278,6 +422,10 @@ export class SourceService {
             leafs: scanned.leafs,
         }, [
             ...metadataWarnings,
+            ...scanned.duplicateLeafs.map((leaf) => ({
+                code: "DUPLICATE_LEAF",
+                message: `${leaf.path}: Duplicate skill content skipped because ${leaf.keptPath} was discovered first`,
+            })),
             ...scanned.invalidLeafs.map((leaf) => ({
                 code: "INVALID_LEAF",
                 message: `${leaf.path}: ${leaf.reason}`,
@@ -286,12 +434,12 @@ export class SourceService {
     }
     async normalizeLocator(locator) {
         const trimmed = locator.trim();
-        if (/^[^/\s]+\/[^/\s]+$/.test(trimmed)) {
-            return `https://github.com/${trimmed}.git`;
-        }
         if (trimmed.startsWith("git@") || trimmed.startsWith("http")) {
             return trimmed;
         }
+        if (/^[^/\s]+\/[^/\s]+$/.test(trimmed)) {
+            return `https://github.com/${trimmed}.git`;
+        }
         const resolvedPath = path.resolve(trimmed);
         if (await pathExists(resolvedPath)) {
             return resolvedPath;
@@ -300,8 +448,10 @@ export class SourceService {
     }
     async resolveSource(locator, options) {
         const trimmed = locator.trim();
-        const resolvedPath = path.resolve(trimmed);
-        if (await pathExists(resolvedPath)) {
+        const fileLocatorPath = this.parseFileLocator(trimmed);
+        const resolvedPath = path.resolve(fileLocatorPath ?? trimmed);
+        if (await pathExists(resolvedPath) &&
+            (!fileLocatorPath || !(await this.isGitRepositoryPath(resolvedPath)))) {
             return {
                 kind: "local",
                 locator: resolvedPath,
@@ -311,17 +461,28 @@ export class SourceService {
                 ...(options.path ? { requestedPath: options.path } : {}),
             };
         }
-        const treeLocator = this.parseGitHubTreeLocator(trimmed);
+        const treeLocator = this.parseTreeLocator(trimmed);
         if (treeLocator) {
+            const requestedPath = this.joinRequestedPaths(treeLocator.requestedPath, options.path);
             return {
                 kind: "git",
                 locator: treeLocator.repoLocator,
                 gitLocator: await this.normalizeLocator(treeLocator.repoLocator),
                 displayName: options.displayNameOverride ?? deriveDisplayName(treeLocator.repoLocator),
                 sourceId: options.sourceIdOverride ?? deriveSourceId(treeLocator.repoLocator),
-                ...(options.path ?? treeLocator.requestedPath
-                    ? { requestedPath: options.path ?? treeLocator.requestedPath }
-                    : {}),
+                ...(requestedPath ? { requestedPath } : {}),
+            };
+        }
+        const shorthandLocator = this.parseGitHubShorthandSubpath(trimmed);
+        if (shorthandLocator) {
+            const requestedPath = this.joinRequestedPaths(shorthandLocator.requestedPath, options.path);
+            return {
+                kind: "git",
+                locator: shorthandLocator.repoLocator,
+                gitLocator: await this.normalizeLocator(shorthandLocator.repoLocator),
+                displayName: options.displayNameOverride ?? deriveDisplayName(shorthandLocator.repoLocator),
+                sourceId: options.sourceIdOverride ?? deriveSourceId(shorthandLocator.repoLocator),
+                ...(requestedPath ? { requestedPath } : {}),
             };
         }
         const clawhubMatch = trimmed.match(/^clawhub:([^@\s]+)(?:@(.+))?$/);
@@ -361,36 +522,145 @@ export class SourceService {
             ...(options.path ? { requestedPath: options.path } : {}),
         };
     }
-    parseGitHubTreeLocator(locator) {
+    resolveUniqueLocalSource(resolved, existingSources) {
+        if (resolved.kind !== "local" || !resolved.localPath) {
+            return resolved;
+        }
+        if (existingSources.some((source) => source.kind === "local" && path.resolve(source.locator) === resolved.localPath)) {
+            return resolved;
+        }
+        const folderName = path.basename(resolved.localPath);
+        const parentFolderName = path.basename(path.dirname(resolved.localPath));
+        const displayCandidates = [
+            folderName,
+            `${parentFolderName}_${folderName}`,
+        ];
+        const takenIds = new Set(existingSources.map((source) => source.id));
+        const takenLabels = new Set(existingSources
+            .filter((source) => source.kind === "local")
+            .map((source) => source.displayName));
+        for (const candidate of displayCandidates) {
+            const sourceId = deriveSourceId(candidate);
+            if (!takenIds.has(sourceId) && !takenLabels.has(candidate)) {
+                return {
+                    ...resolved,
+                    displayName: candidate,
+                    sourceId,
+                };
+            }
+        }
+        const baseDisplayName = `${parentFolderName}_${folderName}`;
+        let index = 2;
+        while (true) {
+            const displayName = `${baseDisplayName}_${index}`;
+            const sourceId = deriveSourceId(displayName);
+            if (!takenIds.has(sourceId) && !takenLabels.has(displayName)) {
+                return {
+                    ...resolved,
+                    displayName,
+                    sourceId,
+                };
+            }
+            index += 1;
+        }
+    }
+    parseTreeLocator(locator) {
         try {
             const url = new URL(locator);
-            if (url.hostname !== "github.com") {
-                return null;
-            }
             const parts = url.pathname.split("/").filter(Boolean);
-            if (parts.length < 5 || parts[2] !== "tree") {
-                return null;
+            if (url.hostname === "github.com") {
+                if (parts.length < 5 || parts[2] !== "tree") {
+                    return null;
+                }
+                const owner = parts[0];
+                const repo = parts[1];
+                const requestedPath = parts.slice(4).join("/");
+                if (!owner || !repo || !requestedPath) {
+                    return null;
+                }
+                return {
+                    repoLocator: `https://github.com/${owner}/${repo}.git`,
+                    requestedPath,
+                };
+            }
+            if (url.hostname === "gitlab.com") {
+                const markerIndex = parts.findIndex((segment, index) => segment === "-" && parts[index + 1] === "tree");
+                if (markerIndex < 2) {
+                    return null;
+                }
+                const requestedPath = parts.slice(markerIndex + 3).join("/");
+                return {
+                    repoLocator: `https://gitlab.com/${parts.slice(0, markerIndex).join("/")}.git`,
+                    ...(requestedPath ? { requestedPath } : {}),
+                };
             }
-            const owner = parts[0];
-            const repo = parts[1];
-            const requestedPath = parts.slice(4).join("/");
-            if (!owner || !repo || !requestedPath) {
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    parseGitHubShorthandSubpath(locator) {
+        const trimmed = locator.replace(/\/+$/, "");
+        const parts = trimmed.split("/");
+        if (parts.length < 3) {
+            return null;
+        }
+        const owner = parts[0];
+        const rawRepo = parts[1];
+        const requestedPath = parts.slice(2).join("/");
+        if (!owner || !rawRepo || !requestedPath) {
+            return null;
+        }
+        const repo = rawRepo.replace(/\.git$/i, "");
+        return {
+            repoLocator: `https://github.com/${owner}/${repo}.git`,
+            requestedPath,
+        };
+    }
+    parseFileLocator(locator) {
+        if (!locator.startsWith("file://")) {
+            return null;
+        }
+        try {
+            const fileUrl = new URL(locator);
+            if (fileUrl.protocol !== "file:") {
                 return null;
             }
-            return {
-                repoLocator: `https://github.com/${owner}/${repo}.git`,
-                requestedPath,
-            };
+            return path.resolve(decodeURIComponent(fileUrl.pathname));
         }
         catch {
             return null;
         }
     }
+    async isGitRepositoryPath(candidatePath) {
+        if (await pathExists(path.join(candidatePath, ".git"))) {
+            return true;
+        }
+        return (await pathExists(path.join(candidatePath, "HEAD")) &&
+            await pathExists(path.join(candidatePath, "objects")) &&
+            await pathExists(path.join(candidatePath, "refs")));
+    }
+    joinRequestedPaths(basePath, childPath) {
+        const normalizedBase = this.normalizeRequestedPath(basePath);
+        const normalizedChild = this.normalizeRequestedPath(childPath);
+        if (!normalizedBase) {
+            return normalizedChild;
+        }
+        if (!normalizedChild) {
+            return normalizedBase;
+        }
+        if (normalizedChild === normalizedBase ||
+            normalizedChild.startsWith(`${normalizedBase}/`)) {
+            return normalizedChild;
+        }
+        return `${normalizedBase}/${normalizedChild}`;
+    }
     findRequestedLeafs(leafs, requestedPath) {
-        if (!requestedPath) {
+        const normalizedPath = this.normalizeRequestedPath(requestedPath);
+        if (!normalizedPath) {
             return leafs;
         }
-        const normalizedPath = requestedPath.replace(/^\.\/+/, "").replace(/\/+$/, "");
         return leafs.filter((leaf) => leaf.relativePath === normalizedPath ||
             leaf.relativePath.startsWith(`${normalizedPath}/`));
     }
@@ -416,8 +686,7 @@ export class SourceService {
     }
     async updateSource(source, currentLock) {
         if (source.kind === "local") {
-            const contentHash = await hashDirectory(currentLock.checkoutPath);
-            return contentHash !== currentLock.contentHash;
+            return this.refreshLocalSourceCheckout(source, currentLock);
         }
         if (source.kind === "git") {
             await git(["pull", "--ff-only"], { cwd: currentLock.checkoutPath });
@@ -444,6 +713,45 @@ export class SourceService {
         }
         return false;
     }
+    async refreshLocalSourceCheckout(source, currentLock) {
+        const tempCheckoutPath = `${currentLock.checkoutPath}.${process.pid}.${crypto.randomUUID()}.refresh`;
+        const backupPath = `${currentLock.checkoutPath}.${process.pid}.${crypto.randomUUID()}.backup`;
+        try {
+            if (!(await pathExists(source.locator))) {
+                throw new Error(`Local source origin is missing at ${source.locator}.`);
+            }
+            await copyDirectory(source.locator, tempCheckoutPath);
+            const nextHash = await hashDirectory(tempCheckoutPath);
+            const checkoutExists = await pathExists(currentLock.checkoutPath);
+            const currentHash = checkoutExists ? await hashDirectory(currentLock.checkoutPath) : undefined;
+            if (checkoutExists && nextHash === currentLock.contentHash && currentHash === nextHash) {
+                await removePath(tempCheckoutPath);
+                return false;
+            }
+            if (checkoutExists) {
+                await fs.rename(currentLock.checkoutPath, backupPath);
+                try {
+                    await fs.rename(tempCheckoutPath, currentLock.checkoutPath);
+                }
+                catch (error) {
+                    await fs.rename(backupPath, currentLock.checkoutPath).catch(() => { });
+                    throw error;
+                }
+                finally {
+                    await removePath(backupPath).catch(() => { });
+                }
+            }
+            else {
+                await fs.rename(tempCheckoutPath, currentLock.checkoutPath);
+            }
+            return true;
+        }
+        catch (error) {
+            await removePath(tempCheckoutPath).catch(() => { });
+            await removePath(backupPath).catch(() => { });
+            throw error;
+        }
+    }
     async readSourceSnapshot(kind, checkoutPath) {
         if (kind === "local") {
             return {