@zq-silk/yui 0.6.0 → 0.6.2

package/dist/release/workflowFileLock.js

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, linkSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Cross-process mutual exclusion for one workflow's engine runs. Each CLI
+ * invocation is a fresh Node process, so an in-process map cannot coordinate
+ * across processes; this lock lives under the FileTaskStore root instead.
+ *
+ * The lock is a directory created atomically with mkdir(2): its existence is
+ * the lock, so a second acquirer fails with EEXIST while the first holds it.
+ * The owner receipt (pid + unique fence token) is written to a temp name and
+ * renamed into place, so a reader observes either no receipt or a complete
+ * one. Incomplete metadata is never reclaimed as dead: a lock without a
+ * complete, parseable receipt is treated as live (its owner may be between
+ * the mkdir and the receipt rename), so the empty-file window of the old
+ * O_EXCL file lock can never produce two owners. A complete receipt whose
+ * process is dead is reclaimed.
+ *
+ * Release verifies the fence token before removing the directory, so a lock
+ * that was legitimately transferred (a stale holder was reclaimed and a new
+ * owner acquired) is never removed by a stale release closure.
+ */
+const WORKFLOW_LOCK_DIRECTORY = ".release-workflow-locks";
+const OWNER_RECEIPT_NAME = "owner";
+const DEFAULT_LOCK_TIMEOUT_MS = 600_000;
+const DEFAULT_LOCK_RETRY_MS = 20;
+export async function acquireWorkflowFileLock(rootDir, taskId, workflowId, options = {}) {
+    const lockRoot = join(rootDir, WORKFLOW_LOCK_DIRECTORY);
+    mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+    const lockDir = join(lockRoot, `${sanitizeLockPart(taskId)}--${sanitizeLockPart(workflowId)}.lock`);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+    const retryMs = options.retryMs ?? DEFAULT_LOCK_RETRY_MS;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            mkdirSync(lockDir, { mode: 0o700 });
+            const token = writeOwnerReceipt(lockDir);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                // Only remove the lock we own: a receipt with another token means
+                // the lock was transferred and a different owner now holds it.
+                if (!receiptNamesOwner(lockDir, token))
+                    return;
+                rmSync(lockDir, { recursive: true, force: true });
+            };
+        }
+        catch (error) {
+            if (!isEExist(error))
+                throw error;
+            reclaimDeadWorkflowLock(lockDir);
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for the release workflow lock: ${taskId}/${workflowId}.`);
+            }
+            // Yield to the event loop so a concurrent run in the same process can
+            // progress while this one waits.
+            await new Promise((resolve) => setTimeout(resolve, retryMs));
+        }
+    }
+}
+/**
+ * Writes the owner receipt atomically: a temp file inside the (already
+ * exclusively owned) lock directory, renamed to the receipt name. A reader
+ * therefore sees a complete receipt or none, never a partial one. A failure
+ * here would strand the lock after our death (it could never be reclaimed
+ * without a receipt), so the lock directory is removed and the error raised.
+ */
+function writeOwnerReceipt(lockDir) {
+    const token = randomUUID();
+    const receipt = { pid: process.pid, token };
+    const temp = join(lockDir, `.owner.${token}.tmp`);
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(temp, join(lockDir, OWNER_RECEIPT_NAME));
+    }
+    catch (error) {
+        rmSync(lockDir, { recursive: true, force: true });
+        throw error;
+    }
+    return token;
+}
+/**
+ * The complete owner receipt, or null when the lock carries no complete
+ * receipt (the owner may be mid-acquisition) or an unparseable one. Null
+ * means "do not reclaim": incomplete metadata is never treated as dead.
+ */
+function readOwnerReceipt(lockDir) {
+    let raw;
+    try {
+        raw = readFileSync(join(lockDir, OWNER_RECEIPT_NAME), "utf8");
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return null;
+        const receipt = parsed;
+        if (typeof receipt.pid !== "number" || !Number.isInteger(receipt.pid) || receipt.pid <= 0) {
+            return null;
+        }
+        if (typeof receipt.token !== "string" || receipt.token.length === 0)
+            return null;
+        return { pid: receipt.pid, token: receipt.token };
+    }
+    catch {
+        return null;
+    }
+}
+function receiptNamesOwner(lockDir, token) {
+    return readOwnerReceipt(lockDir)?.token === token;
+}
+/**
+ * Reclaims a lock whose owner process is dead. A lock without a complete
+ * receipt is left alone: its owner may be between the mkdir and the receipt
+ * rename, and reclaiming in that window would hand the pathname to a second
+ * owner while the first still believes it holds the lock.
+ *
+ * The reclaim itself is serialized with an atomic marker created via
+ * `linkSync`: only one process can create the marker, so a second reclaimer
+ * cannot remove a lock that was already reclaimed and re-acquired by a
+ * third process between the first reclaimer's receipt check and its delete.
+ * The receipt is re-read under the marker so a transferred lock is never
+ * removed.
+ */
+function reclaimDeadWorkflowLock(lockDir) {
+    const receipt = readOwnerReceipt(lockDir);
+    if (receipt === null)
+        return;
+    if (processIsAlive(receipt.pid))
+        return;
+    const markerPath = join(lockDir, ".reclaiming");
+    const tempPath = join(lockDir, `.reclaiming.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(tempPath, "wx", 0o600);
+        try {
+            writeFileSync(fd, `${process.pid}\n`, { mode: 0o600 });
+        }
+        finally {
+            closeSync(fd);
+        }
+        try {
+            linkSync(tempPath, markerPath);
+        }
+        catch (error) {
+            if (!isEExist(error))
+                throw error;
+            // A concurrent or crashed reclaim left a marker. If its process is
+            // dead, the marker is stale: remove it and claim once.
+            if (!isReclaimMarkerStale(markerPath))
+                return;
+            rmSync(markerPath, { force: true });
+            linkSync(tempPath, markerPath);
+        }
+    }
+    catch (error) {
+        rmSync(tempPath, { force: true });
+        if (isEnoent(error))
+            return; // Lock directory was removed
+        throw error;
+    }
+    try {
+        // Re-read under the marker: the lock may have been transferred to a
+        // live owner between our first read and the marker claim.
+        const current = readOwnerReceipt(lockDir);
+        if (current === null)
+            return;
+        if (current.token !== receipt.token)
+            return;
+        if (processIsAlive(current.pid))
+            return;
+        rmSync(lockDir, { recursive: true, force: true });
+    }
+    finally {
+        rmSync(markerPath, { force: true });
+    }
+}
+function isReclaimMarkerStale(markerPath) {
+    try {
+        const pid = parseInt(readFileSync(markerPath, "utf8").trim(), 10);
+        return Number.isInteger(pid) && pid > 0 && !processIsAlive(pid);
+    }
+    catch {
+        return false;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isEperm(error);
+    }
+}
+function isEExist(error) {
+    return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+function isEnoent(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isEperm(error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+}
+function sanitizeLockPart(value) {
+    return value.replace(/[^A-Za-z0-9_-]/g, "-");
+}

package/dist/repository/gitWorkspace.js

@@ -44,6 +44,55 @@ export class NodeGitWorkspace {
                 return null;
         }
     }
+    /**
+     * Whether two commits hold the same tree content on the given paths.
+     * An enqueued ChangeSet whose head agrees with the target on every path
+     * it touched is already represented there and converges without a new
+     * commit, even when other unrelated changes landed in between.
+     *
+     * The captured paths are literal filenames, so `--literal-pathspecs`
+     * disables pathspec magic: a name such as `:(exclude)*` must not exclude
+     * every path and fake a converged tree.  It is a global option and
+     * therefore must precede the `diff` subcommand.
+     */
+    async treesAgreeOnPaths(input) {
+        if (input.paths.length === 0)
+            return false;
+        return gitSucceeds([
+            "-C", input.repositoryPath,
+            "--literal-pathspecs",
+            "diff", "--quiet",
+            input.leftCommit, input.rightCommit,
+            "--", ...input.paths
+        ]);
+    }
+    /**
+     * Every path changed between two commits.  The integration queue uses this
+     * to fence a validated entry: a target advance whose real path delta
+     * overlaps the entry's own paths (or whose impact cannot be proven)
+     * invalidates the entry's reusable evidence.
+     */
+    async changedFilesBetween(input) {
+        const output = await git([
+            "-C", input.repositoryPath,
+            "diff", "--name-only",
+            input.fromCommit, input.toCommit
+        ]);
+        return output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    }
+    /**
+     * Files deleted between two commits.  Uses `--diff-filter=D` so a rename
+     * reports its source path here (and its destination in `changedFilesBetween`),
+     * letting the containment proof verify both sides of a rename.
+     */
+    async deletedFilesBetween(input) {
+        const output = await git([
+            "-C", input.repositoryPath,
+            "diff", "--name-only", "--diff-filter=D", "--no-renames",
+            input.fromCommit, input.toCommit
+        ]);
+        return output.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+    }
     /**
      * Resolve the configured Project branch directly from its remote.  This is
      * deliberately read-only: unlike `refresh`, it never advances the stable
@@ -307,6 +356,19 @@ export class NodeGitWorkspace {
             baseCommit: baseCommit.toLowerCase()
         };
     }
+    async assertRefAt(repositoryPath, ref, expectedCommit) {
+        const root = (await this.inspect(repositoryPath)).root;
+        // `git update-ref <ref> <new> <old>` is atomic: it succeeds only when the
+        // ref still points at <old>.  Using the same commit for both new and old
+        // makes it a pure compare-and-swap probe — the ref does not move, but a
+        // concurrent advance between the last read and this call is detected.
+        await git([
+            "-C", root, "update-ref",
+            safeRef(ref),
+            expectedCommit,
+            expectedCommit
+        ]);
+    }
     async refExists(repositoryPath, ref) {
         const root = (await this.inspect(repositoryPath)).root;
         return gitSucceeds([
@@ -420,6 +482,56 @@ export class NodeGitWorkspace {
             ]);
         }
     }
+    async assertNoForeignWorktreeOnRef(input) {
+        const root = (await this.inspect(input.repositoryPath)).root;
+        const wanted = safeRef(input.ref);
+        // The recorded worktree is removed in the same archive flow; it is the
+        // only same-repo worktree on the ref that may stay for now. A path that
+        // no longer exists cannot match a live worktree.
+        const excluded = input.excludeWorktreePath === undefined
+            ? undefined
+            : await realpath(resolve(input.excludeWorktreePath)).catch(() => undefined);
+        const porcelain = await git(["-C", root, "worktree", "list", "--porcelain"]);
+        const records = [];
+        let current = { prunable: false };
+        for (const line of porcelain.split("\n")) {
+            if (line.length === 0) {
+                const path = current.path;
+                if (path !== undefined) {
+                    records.push({ path, branch: current.branch, prunable: current.prunable });
+                }
+                current = { prunable: false };
+                continue;
+            }
+            if (line.startsWith("worktree ")) {
+                current.path = line.slice("worktree ".length);
+            }
+            else if (line.startsWith("branch ")) {
+                current.branch = line.slice("branch ".length);
+            }
+            else if (line.startsWith("prunable")) {
+                current.prunable = true;
+            }
+        }
+        const lastPath = current.path;
+        if (lastPath !== undefined) {
+            records.push({ path: lastPath, branch: current.branch, prunable: current.prunable });
+        }
+        for (const record of records) {
+            // A dead registration (its directory is gone) occupies nothing; a
+            // worktree on another ref or a detached HEAD does not occupy this one.
+            if (record.prunable || record.branch !== wanted)
+                continue;
+            // git reports canonical absolute paths; compare canonicals so a
+            // symlinked workspace root cannot make the recorded worktree look
+            // foreign.
+            const canonical = await realpath(record.path).catch(() => record.path);
+            if (canonical === excluded)
+                continue;
+            throw new Error(`Ref ${wanted} is checked out by a worktree outside this Home's management ` +
+                `(${record.path}); the archive refuses to delete the ref and strand that worktree.`);
+        }
+    }
     async isAncestor(repositoryPath, ancestor, descendant) {
         const root = (await this.inspect(repositoryPath)).root;
         return gitSucceeds([
@@ -577,12 +689,53 @@ export class NodeGitWorkspace {
         }
         return "removed";
     }
+    /**
+     * Remove a stranded worktree whose Git common-dir no longer matches the
+     * Project's current repository (e.g. after a `project migrate` switched the
+     * catalog). The normal {@link removeWorktree} path rejects such worktrees
+     * via `assertOwnedWorktree`; this fallback inspects and removes through the
+     * worktree's own Git identity instead. Only call for unadopted worktrees
+     * that are safe to discard (e.g. Lane preparation compensation).
+     */
+    async removeStrandedWorktree(path) {
+        const kind = await pathKind(path);
+        if (kind === undefined)
+            return "missing";
+        if (kind === "symlink")
+            throw new Error("Stranded worktree path must not be a symbolic link.");
+        // Inspect dirty state through the worktree's own Git, bypassing the
+        // Project ownership check that fails after a catalog switch.
+        const porcelain = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+        if (porcelain.length > 0)
+            return "dirty";
+        try {
+            await git(["-C", path, "worktree", "remove", "--force", "--", path]);
+        }
+        catch {
+            // The worktree's common-dir (old external repo) may itself be gone.
+            // Remove the directory directly; the worktree is unadopted.
+            await rm(path, { recursive: true, force: true });
+        }
+        return "removed";
+    }
     async inspectRecordedWorktree(input) {
         const inspected = await inspectExactRecordedWorktree(input);
         return inspected?.state ?? "missing";
     }
     async removeRecordedWorktree(input) {
-        const inspected = await inspectExactRecordedWorktree(input);
+        let inspected;
+        try {
+            inspected = await inspectExactRecordedWorktree(input);
+        }
+        catch (error) {
+            // A deleted external checkout takes the worktree's common dir with it,
+            // so every git op against the worktree fails. When the Project
+            // repository itself is gone, the worktree's Git identity, HEAD, index,
+            // and dirty state can no longer be proven. An extant directory is
+            // retained and the caller fails closed with a manual-cleanup diagnosis;
+            // only a directory that is also absent is treated as missing.
+            return await recordedWorktreeWithoutRepository(input, error);
+        }
         if (inspected === undefined)
             return "missing";
         if (inspected.state === "dirty")
@@ -776,6 +929,29 @@ async function resolveRefCommit(repositoryPath, ref) {
         throw new Error("Git returned an invalid ref commit.");
     return commit;
 }
+/**
+ * Classify a recorded worktree whose Project repository can no longer be
+ * inspected. A deleted external checkout takes the worktree's common dir with
+ * it, so the worktree's Git identity, HEAD, index, and dirty/untracked state
+ * cannot be proven. An extant directory is retained and the caller fails
+ * closed with a bounded manual-cleanup diagnosis; only a directory that is
+ * also absent is treated as missing. The exact recorded identity is
+ * re-validated so a mismatched path/branch is never classified.
+ */
+async function recordedWorktreeWithoutRepository(input, cause) {
+    if (await pathKind(input.repositoryPath) !== undefined)
+        throw cause;
+    const identity = worktreeIdentity(input.taskSegment, input.roleName);
+    const expectedPath = managedPath(resolve(input.container), identity.directory);
+    if (resolve(input.path) !== expectedPath || input.branch !== identity.branch) {
+        throw cause;
+    }
+    if (await pathKind(expectedPath) === undefined)
+        return "missing";
+    throw new Error(`Recorded worktree survives its Project repository and needs manual cleanup: ${expectedPath}. `
+        + `The Project repository is gone, so the worktree's Git state cannot be verified; `
+        + `remove the directory manually once its contents are safe.`);
+}
 async function retainCommitRef(repositoryPath, ref, commit) {
     const target = safeRef(ref);
     if (await gitSucceeds([