@solaqua/gji 0.10.0 → 0.12.0

package/dist/dir-clone.js

@@ -0,0 +1,505 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, cp, lstat, mkdir, mkdtemp, opendir, readdir, readFile, readlink, realpath, rename, rm, rmdir, symlink, unlink, utimes, writeFile, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { isAlreadyExistsError, isNotFoundError } from "./fs-utils.js";
+import { inspectDestination, openDestinationDirectory, } from "./safe-destination.js";
+const execFileAsync = promisify(execFile);
+const CLONE_LOCK_TTL_MS = 24 * 60 * 60 * 1000;
+const CLONE_LOCK_SUFFIX = ".gji-clone-lock";
+const SIZE_ESTIMATE_MAX_ENTRIES = 1_000_000;
+const SIZE_ESTIMATE_MAX_MS = 5_000;
+export async function waitForCloneLock(destination, timeoutMs = 5_000) {
+    const lockPath = `${destination}${CLONE_LOCK_SUFFIX}`;
+    const deadline = Date.now() + timeoutMs;
+    while (await cloneLockExists(lockPath)) {
+        if (await cloneLockIsStale(lockPath))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return true;
+}
+async function cloneLockIsStale(lockPath) {
+    try {
+        const freshnessPath = await lockFreshnessPath(lockPath);
+        const stats = await lstat(freshnessPath);
+        return Date.now() - stats.mtimeMs >= CLONE_LOCK_TTL_MS;
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        return false;
+    }
+}
+async function cloneLockExists(lockPath) {
+    try {
+        return await destinationExists(lockPath);
+    }
+    catch (error) {
+        if ("code" in error &&
+            error.code === "ENOTDIR") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function cloneDir(source, destination, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const strategy = cloneStrategy(platform);
+    if (!isClonePlatformSupported(platform)) {
+        throw new CloneUnsupportedError(`platform ${platform} has no CoW strategy`);
+    }
+    const sourcePath = await realpath(source);
+    const sourceStats = await lstat(sourcePath);
+    if (!sourceStats.isDirectory()) {
+        throw new Error("source is not a directory");
+    }
+    if (await destinationExists(destination)) {
+        throw new CloneDestinationExistsError(destination);
+    }
+    const startedAt = Date.now();
+    const parent = dirname(destination);
+    let safeParent;
+    try {
+        if (options.destinationRoot) {
+            const parentInspection = await inspectDestination(options.destinationRoot, parent);
+            if (parentInspection.kind === "unsafe") {
+                throw new Error(parentInspection.reason);
+            }
+            safeParent = await openDestinationDirectory(options.destinationRoot, parent);
+        }
+        else {
+            await mkdir(parent, { recursive: true });
+        }
+        const operationParent = safeParent?.path ?? parent;
+        const operationDestination = join(operationParent, basename(destination));
+        if (await destinationExists(operationDestination)) {
+            throw new CloneDestinationExistsError(destination);
+        }
+        const lockPath = `${destination}${CLONE_LOCK_SUFFIX}`;
+        const lockToken = await acquireCloneLock(lockPath, destination);
+        const stopLockHeartbeat = startLockHeartbeat(lockPath, lockToken);
+        let temporaryRoot;
+        let reservationPath;
+        const reservationEntries = [];
+        try {
+            reservationPath = await reserveDestination(operationDestination);
+            temporaryRoot = await mkdtemp(join(operationParent, `.${basename(destination)}.gji-clone-`));
+            const temporaryDestination = join(temporaryRoot, basename(destination));
+            const copyDirectory = options.copyDirectory ??
+                (platformIsDarwin(platform)
+                    ? runNativeCloneDirectory
+                    : async (source, target) => {
+                        if (!strategy) {
+                            throw new CloneUnsupportedError(`platform ${platform} has no CoW strategy`);
+                        }
+                        const runCommand = options.runCommand ?? runCloneCommand;
+                        await runCommand("cp", strategy(source, target));
+                    });
+            try {
+                await copyDirectory(sourcePath, temporaryDestination);
+            }
+            catch (error) {
+                if (isUnsupportedCloneError(error)) {
+                    throw new CloneUnsupportedError(toErrorMessage(error));
+                }
+                throw error;
+            }
+            await publishCloneContents(temporaryDestination, operationDestination, reservationPath, (entry) => reservationEntries.push(entry), options.copyFile ?? runForcedCloneFileCopy);
+            reservationPath = undefined;
+        }
+        finally {
+            stopLockHeartbeat();
+            if (reservationPath) {
+                await cleanupReservedDestination(operationDestination, reservationPath, reservationEntries);
+            }
+            try {
+                if (temporaryRoot) {
+                    await rm(temporaryRoot, { force: true, recursive: true });
+                }
+            }
+            catch {
+                // Cleanup is best effort and must not mask the clone result.
+            }
+            try {
+                await releaseCloneLock(lockPath, lockToken);
+            }
+            catch {
+                // A stale lock is reclaimed on a later attempt.
+            }
+        }
+        const bytes = options.measureBytes === false
+            ? undefined
+            : await estimateCloneBytes(sourcePath);
+        return { bytes, ms: Date.now() - startedAt };
+    }
+    finally {
+        await safeParent?.close().catch(() => undefined);
+    }
+}
+async function runNativeCloneDirectory(source, destination) {
+    await cp(source, destination, {
+        errorOnExist: true,
+        force: false,
+        mode: constants.COPYFILE_FICLONE_FORCE,
+        preserveTimestamps: true,
+        recursive: true,
+    });
+}
+export class CloneDestinationExistsError extends Error {
+    code = "GJI_CLONE_DESTINATION_EXISTS";
+    constructor(destination) {
+        super(`destination already exists: ${destination}`);
+        this.name = "CloneDestinationExistsError";
+    }
+}
+export class CloneUnsupportedError extends Error {
+    code = "GJI_CLONE_UNSUPPORTED";
+    constructor(reason) {
+        super(`copy-on-write cloning is not supported: ${reason}`);
+        this.name = "CloneUnsupportedError";
+    }
+}
+export class CloneInProgressError extends Error {
+    code = "GJI_CLONE_IN_PROGRESS";
+    constructor(destination) {
+        super(`copy-on-write clone already in progress: ${destination}`);
+        this.name = "CloneInProgressError";
+    }
+}
+export function isCloneDestinationExistsError(error) {
+    return error instanceof CloneDestinationExistsError;
+}
+export function isCloneUnsupportedError(error) {
+    return (error instanceof CloneUnsupportedError || isUnsupportedCloneError(error));
+}
+export function isCloneInProgressError(error) {
+    return error instanceof CloneInProgressError;
+}
+export async function directorySize(path) {
+    const stats = await lstat(path);
+    if (!stats.isDirectory())
+        return stats.size;
+    const pending = [path];
+    let total = 0;
+    let entryCount = 0;
+    const startedAt = Date.now();
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!current)
+            continue;
+        const directory = await opendir(current);
+        try {
+            for await (const entry of directory) {
+                entryCount += 1;
+                if (entryCount > SIZE_ESTIMATE_MAX_ENTRIES ||
+                    Date.now() - startedAt > SIZE_ESTIMATE_MAX_MS) {
+                    throw new Error("directory size estimate exceeded its safety limit");
+                }
+                const entryPath = join(current, entry.name);
+                if (entry.isDirectory())
+                    pending.push(entryPath);
+                else
+                    total += (await lstat(entryPath)).size;
+            }
+        }
+        finally {
+            await directory.close().catch(() => undefined);
+        }
+    }
+    return total;
+}
+function cloneStrategy(platform) {
+    if (platform === "linux") {
+        return (source, destination) => [
+            "-a",
+            "--reflink=always",
+            source,
+            destination,
+        ];
+    }
+    return null;
+}
+function isClonePlatformSupported(platform) {
+    return platform === "darwin" || platform === "linux";
+}
+async function estimateCloneBytes(path) {
+    try {
+        return await directorySize(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function runCloneCommand(command, args) {
+    try {
+        await execFileAsync(command, args);
+    }
+    catch (error) {
+        if (isUnsupportedCloneError(error)) {
+            throw new CloneUnsupportedError(toErrorMessage(error));
+        }
+        throw error;
+    }
+}
+async function acquireCloneLock(lockPath, destination) {
+    const lockToken = randomUUID();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await mkdir(lockPath);
+            try {
+                await writeFile(join(lockPath, ownerFileName(lockToken)), `${lockToken}\n`, {
+                    flag: "wx",
+                });
+            }
+            catch (error) {
+                await rm(lockPath, { force: true, recursive: true });
+                throw error;
+            }
+            return lockToken;
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error))
+                throw error;
+        }
+        let lockStats;
+        try {
+            lockStats = await lstat(await lockFreshnessPath(lockPath));
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                continue;
+            throw error;
+        }
+        if (Date.now() - lockStats.mtimeMs < CLONE_LOCK_TTL_MS) {
+            throw new CloneInProgressError(destination);
+        }
+        const stalePath = `${lockPath}.stale-${randomUUID()}`;
+        try {
+            await rename(lockPath, stalePath);
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                continue;
+            throw error;
+        }
+        try {
+            await mkdir(lockPath);
+            try {
+                await writeFile(join(lockPath, ownerFileName(lockToken)), `${lockToken}\n`, {
+                    flag: "wx",
+                });
+            }
+            catch (error) {
+                await rm(lockPath, { force: true, recursive: true });
+                throw error;
+            }
+            try {
+                await rm(stalePath, { force: true, recursive: true });
+            }
+            catch (cleanupError) {
+                await releaseCloneLock(lockPath, lockToken).catch(() => undefined);
+                throw cleanupError;
+            }
+            return lockToken;
+        }
+        catch (error) {
+            await rm(stalePath, { force: true, recursive: true }).catch(() => undefined);
+            if (isAlreadyExistsError(error))
+                continue;
+            throw error;
+        }
+    }
+    throw new CloneInProgressError(destination);
+}
+async function lockFreshnessPath(lockPath) {
+    try {
+        const entries = await readdir(lockPath);
+        const owner = entries.find((entry) => entry.startsWith("owner-"));
+        return owner ? join(lockPath, owner) : lockPath;
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            throw error;
+        return lockPath;
+    }
+}
+async function publishCloneContents(temporaryDestination, destination, reservationPath, onEntryPublished, copyFileEntry) {
+    const reservationName = basename(reservationPath);
+    const destinationEntries = await readdir(destination);
+    if (destinationEntries.length !== 1 ||
+        destinationEntries[0] !== reservationName) {
+        throw new CloneDestinationExistsError(destination);
+    }
+    const temporaryEntries = await readdir(temporaryDestination);
+    for (const entry of temporaryEntries) {
+        await publishCloneEntry(join(temporaryDestination, entry), join(destination, entry), () => onEntryPublished(entry), copyFileEntry);
+    }
+    await unlink(reservationPath);
+}
+async function publishCloneEntry(source, destination, onCreated, copyFileEntry) {
+    const sourceStats = await lstat(source);
+    if (sourceStats.isDirectory()) {
+        try {
+            await mkdir(destination);
+        }
+        catch (error) {
+            if (isAlreadyExistsError(error)) {
+                throw new CloneDestinationExistsError(destination);
+            }
+            throw error;
+        }
+        onCreated();
+        for (const entry of await readdir(source)) {
+            await publishCloneEntry(join(source, entry), join(destination, entry), () => undefined, copyFileEntry);
+        }
+        await copyCloneMetadata(sourceStats, destination);
+        return;
+    }
+    if (sourceStats.isSymbolicLink()) {
+        try {
+            await symlink(await readlink(source), destination);
+        }
+        catch (error) {
+            if (isAlreadyExistsError(error)) {
+                throw new CloneDestinationExistsError(destination);
+            }
+            throw error;
+        }
+        onCreated();
+        return;
+    }
+    if (!sourceStats.isFile()) {
+        throw new Error(`unsupported clone entry type: ${source}`);
+    }
+    try {
+        await copyFileEntry(source, destination);
+    }
+    catch (error) {
+        if (isAlreadyExistsError(error)) {
+            throw new CloneDestinationExistsError(destination);
+        }
+        if (isUnsupportedCloneError(error)) {
+            throw new CloneUnsupportedError(toErrorMessage(error));
+        }
+        throw error;
+    }
+    onCreated();
+    await copyCloneMetadata(sourceStats, destination);
+}
+async function runForcedCloneFileCopy(source, destination) {
+    await cp(source, destination, {
+        errorOnExist: true,
+        force: false,
+        mode: constants.COPYFILE_FICLONE_FORCE,
+        preserveTimestamps: true,
+    });
+}
+async function copyCloneMetadata(sourceStats, destination) {
+    await chmod(destination, Number(sourceStats.mode) & 0o7777);
+    await utimes(destination, sourceStats.atime, sourceStats.mtime);
+}
+async function reserveDestination(destination) {
+    try {
+        await mkdir(destination);
+    }
+    catch (error) {
+        if (isAlreadyExistsError(error)) {
+            throw new CloneDestinationExistsError(destination);
+        }
+        throw error;
+    }
+    const reservationPath = join(destination, `.gji-clone-reservation-${randomUUID()}`);
+    try {
+        await writeFile(reservationPath, "gji clone reservation\n", {
+            flag: "wx",
+        });
+        return reservationPath;
+    }
+    catch (error) {
+        await rmdir(destination).catch(() => undefined);
+        throw error;
+    }
+}
+async function cleanupReservedDestination(destination, reservationPath, reservationEntries) {
+    try {
+        const entries = await readdir(destination);
+        const ownedEntries = new Set([
+            basename(reservationPath),
+            ...reservationEntries,
+        ]);
+        if (entries.every((entry) => ownedEntries.has(entry))) {
+            await rm(destination, { force: true, recursive: true });
+        }
+    }
+    catch {
+        // Preserve a destination that was changed by another process.
+    }
+}
+async function destinationExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundError(error))
+            return false;
+        throw error;
+    }
+}
+function startLockHeartbeat(lockPath, lockToken) {
+    const timer = setInterval(() => {
+        void refreshCloneLock(lockPath, lockToken);
+    }, CLONE_LOCK_TTL_MS / 3);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+async function refreshCloneLock(lockPath, lockToken) {
+    try {
+        const ownerPath = join(lockPath, ownerFileName(lockToken));
+        await readFile(ownerPath, "utf8");
+        const now = new Date();
+        await utimes(ownerPath, now, now);
+    }
+    catch {
+        // Lock refresh is advisory; the owner check prevents touching a replacement lock.
+    }
+}
+async function releaseCloneLock(lockPath, lockToken) {
+    try {
+        const ownerPath = join(lockPath, ownerFileName(lockToken));
+        await unlink(ownerPath);
+        await rmdir(lockPath);
+    }
+    catch (error) {
+        if (!isNotFoundError(error) && !isDirectoryNotEmptyError(error))
+            throw error;
+    }
+}
+function ownerFileName(lockToken) {
+    return `owner-${lockToken}`;
+}
+function isUnsupportedCloneError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const code = "code" in error ? error.code : "";
+    if (["EINVAL", "ENOSYS", "ENOTSUP", "EOPNOTSUPP", "EXDEV"].includes(code ?? "")) {
+        return true;
+    }
+    return /clonefile|reflink|unsupported|operation not supported|not supported|invalid cross-device|cross-device/iu.test(error.message);
+}
+function isDirectoryNotEmptyError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOTEMPTY");
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function platformIsDarwin(platform) {
+    return platform === "darwin";
+}

package/dist/doctor.js

@@ -12,6 +12,7 @@ import { detectRepository } from "./repo.js";
 import { loadRegistry, REGISTRY_FILE_PATH, removeMissingRegistryEntries, } from "./repo-registry.js";
 import { resolveSupportedShell } from "./shell.js";
 import { executableExists, hasShellIntegration, resolveCompletionPath, resolveShellConfigPath, } from "./shell-setup.js";
+import { loadSlots } from "./slots.js";
 const execFileAsync = promisify(execFile);
 const MINIMUM_GIT_VERSION = { major: 2, minor: 17 };
 export async function runDoctorCommand(options) {
@@ -82,10 +83,30 @@ async function collectDoctorInspection(cwd, home, shell) {
             await checkWorktreeBase(repository, effectiveConfig, home),
             registry.check,
             await checkEditor(effectiveConfig),
+            await checkOrphanSlots(home),
         ],
         missingRegistryPaths: registry.missingPaths,
     };
 }
+async function checkOrphanSlots(home) {
+    const slots = await loadSlots(home);
+    const missing = (await Promise.all(Object.keys(slots).map(async (path) => {
+        try {
+            await access(path);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }))).filter(Boolean).length;
+    return {
+        id: "slots",
+        message: missing === 0
+            ? "worktree slots healthy"
+            : `${missing} orphaned worktree slot${missing === 1 ? "" : "s"}`,
+        status: "ok",
+    };
+}
 function buildDoctorFixes(missingRegistryPaths) {
     if (missingRegistryPaths.length === 0)
         return [];

package/dist/done.d.ts

@@ -0,0 +1,10 @@
+export interface DoneCommandOptions {
+    branch?: string;
+    cwd: string;
+    force?: boolean;
+    json?: boolean;
+    keepBranch?: boolean;
+    stderr: (chunk: string) => void;
+    stdout: (chunk: string) => void;
+}
+export declare function runDoneCommand(options: DoneCommandOptions): Promise<number>;