@solaqua/gji 0.9.0 → 0.11.0

package/dist/dependency-bootstrap.js

@@ -0,0 +1,566 @@
+import { execFile } from "node:child_process";
+import { lstat, readFile, realpath, rm } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { cloneFailureScope, defaultCloneFailureStore, } from "./clone-failure-store.js";
+import { runCommand } from "./command-runner.js";
+import { cloneDir, isCloneDestinationExistsError, isCloneInProgressError, isCloneUnsupportedError, } from "./dir-clone.js";
+import { pathExists } from "./fs-utils.js";
+import { inspectDestination } from "./safe-destination.js";
+const execFileAsync = promisify(execFile);
+export async function prepareDependencyBootstrap(mode, context) {
+    if (mode === "off")
+        return { mode, targets: [] };
+    const adapters = createBootstrapAdapters(context.checkUvRuntime ?? defaultCheckUvRuntime, context.cargoBuildCommand);
+    const sourceRoots = [];
+    for (const sourceRoot of uniquePaths([
+        context.repoRoot,
+        context.currentRoot,
+    ])) {
+        if (await isAllowedSourceRoot(context.repoRoot, sourceRoot)) {
+            sourceRoots.push(sourceRoot);
+        }
+    }
+    const targets = [];
+    const plannedRelativePaths = new Set();
+    for (const adapter of adapters) {
+        if (plannedRelativePaths.has(adapter.relativePath))
+            continue;
+        let fallback;
+        let selected;
+        for (const sourceRoot of sourceRoots) {
+            const target = await adapter.detect({
+                detectionRoot: context.detectionRoot,
+                sourceRoot,
+                worktreePath: context.worktreePath,
+            });
+            if (!target)
+                continue;
+            const seedable = mode !== "install-only" && (await adapter.canSeed(target));
+            const candidate = { adapter, target, seedable };
+            fallback ??= candidate;
+            if (mode === "install-only" || seedable) {
+                selected = candidate;
+                break;
+            }
+        }
+        const plannedTarget = selected ?? fallback;
+        if (plannedTarget) {
+            targets.push(plannedTarget);
+            plannedRelativePaths.add(adapter.relativePath);
+        }
+    }
+    return { mode, targets };
+}
+export async function detectDependencyBootstrapCandidate(context) {
+    const plan = await prepareDependencyBootstrap("cow-then-repair", context);
+    const planned = plan.targets[0];
+    if (!planned)
+        return null;
+    return {
+        adapter: planned.adapter.name,
+        kind: planned.adapter.kind,
+        lockfile: planned.adapter.lockfile,
+        target: planned.target.relativePath,
+        repairCommand: planned.target.repairCommand,
+        seedable: planned.seedable,
+    };
+}
+export function previewDependencyBootstrap(plan) {
+    return {
+        mode: plan.mode,
+        targets: plan.targets.map(({ adapter, target, seedable }) => ({
+            adapter: adapter.output(target).adapter,
+            kind: adapter.kind,
+            target: adapter.output(target).target,
+            repairCommand: target.repairCommand,
+            seedable,
+            strategy: bootstrapStrategy(plan.mode, target, seedable),
+        })),
+    };
+}
+export async function executeDependencyBootstrap(plan, options) {
+    if (plan.mode === "off")
+        return { mode: plan.mode, ready: true, events: [] };
+    const events = [];
+    const failureStore = options.failureStore ?? defaultCloneFailureStore;
+    const cloneDirectory = options.cloneDirectory ?? cloneDir;
+    const execution = {
+        runCommand: options.runCommand ?? runCommand,
+        stderr: options.stderr ?? (() => undefined),
+        stdout: options.stdout ?? ((chunk) => process.stdout.write(chunk)),
+    };
+    const seededDirectories = new Set(options.seededDirectories ?? []);
+    if (plan.targets.length === 0) {
+        recordBootstrapEvent(events, options.reporter, {
+            adapter: "none",
+            kind: "dependency",
+            reason: "no-lockfile",
+            state: "skipped",
+            target: "",
+            message: "no supported dependency or build-state lockfile was detected",
+        });
+        return { mode: plan.mode, ready: true, events };
+    }
+    for (const { adapter, target, seedable } of plan.targets) {
+        await executeBootstrapTarget(adapter, target, seedable, plan.mode, cloneDirectory, failureStore, execution, seededDirectories.has(target.relativePath), events, options.reporter, options.repoRoot);
+    }
+    return {
+        mode: plan.mode,
+        ready: !events.some(({ state }) => state === "failed"),
+        events,
+    };
+}
+async function executeBootstrapTarget(adapter, target, seedable, mode, cloneDirectory, failureStore, execution, seededBySyncDirs, events, reporter, repoRoot) {
+    const destinationInspection = await inspectDestination(target.worktreePath, target.targetPath);
+    if (destinationInspection.kind === "unsafe") {
+        recordBootstrapFailure(events, reporter, adapter, target, destinationInspection.reason, "destination-unsafe");
+        return;
+    }
+    if (mode === "install-only") {
+        await repairTarget(adapter, target, execution, false, target.existingBeforeBootstrap ? "preserve" : "empty", events, reporter);
+        return;
+    }
+    let seeded = false;
+    const failureScope = seedable
+        ? await cloneFailureScope(adapter.seedPath(target), target.targetPath)
+        : undefined;
+    let ownership = target.existingBeforeBootstrap
+        ? "preserve"
+        : "empty";
+    const destinationExistsNow = destinationInspection.kind === "exists";
+    if (target.existingBeforeBootstrap) {
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            reason: "target-exists",
+            state: "skipped",
+            target: target.relativePath,
+            message: "target already existed; using it as the repair input",
+        });
+    }
+    else if (seededBySyncDirs && destinationExistsNow) {
+        if (seedable) {
+            seeded = true;
+            ownership = "syncDirs";
+            recordBootstrapEvent(events, reporter, {
+                adapter: adapter.name,
+                kind: adapter.kind,
+                reason: "generic-seed",
+                state: "seeded",
+                target: target.relativePath,
+                message: "reusing a seed created by syncDirs",
+            });
+        }
+        else {
+            ownership = "preserve";
+            recordBootstrapEvent(events, reporter, {
+                adapter: adapter.name,
+                kind: adapter.kind,
+                reason: "generic-seed",
+                state: "fallback",
+                target: target.relativePath,
+                message: "syncDirs created a generic target; this adapter uses repair without CoW",
+            });
+        }
+    }
+    else if (destinationExistsNow) {
+        ownership = "preserve";
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            reason: "destination-race",
+            state: "skipped",
+            target: target.relativePath,
+            message: "target appeared during bootstrap; preserving it as the repair input",
+        });
+    }
+    else if (seedable &&
+        (await failureStore.isCached(repoRoot, target.relativePath, failureScope))) {
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            reason: "cow-failure-cached",
+            state: "fallback",
+            target: target.relativePath,
+            message: "previous CoW failure is cached; repairing from an empty target",
+        });
+    }
+    else if (seedable) {
+        try {
+            await cloneDirectory(adapter.seedPath(target), target.targetPath, {
+                destinationRoot: target.worktreePath,
+                measureBytes: reporter.measureCloneSize,
+            });
+            await failureStore.clear(repoRoot, target.relativePath, failureScope);
+            seeded = true;
+            ownership = "adapter";
+            recordBootstrapEvent(events, reporter, {
+                adapter: adapter.name,
+                kind: adapter.kind,
+                state: "seeded",
+                target: target.relativePath,
+                message: "seeded with copy-on-write",
+            });
+        }
+        catch (error) {
+            if (isCloneDestinationExistsError(error)) {
+                ownership = "preserve";
+                recordBootstrapEvent(events, reporter, {
+                    adapter: adapter.name,
+                    kind: adapter.kind,
+                    state: "skipped",
+                    target: target.relativePath,
+                    message: "target appeared during CoW seeding; preserving it as the repair input",
+                });
+                await repairTarget(adapter, target, execution, false, ownership, events, reporter);
+                return;
+            }
+            if (isCloneInProgressError(error)) {
+                recordBootstrapFailure(events, reporter, adapter, target, `CoW seed is already in progress: ${toErrorMessage(error)}`, "clone-in-progress");
+                return;
+            }
+            if (isCloneUnsupportedError(error)) {
+                await failureStore.cache(repoRoot, target.relativePath, toErrorMessage(error), failureScope);
+            }
+            recordBootstrapEvent(events, reporter, {
+                adapter: adapter.name,
+                kind: adapter.kind,
+                reason: "cow-unsupported",
+                state: "fallback",
+                target: target.relativePath,
+                message: `CoW seed failed; repairing from an empty target (${toErrorMessage(error)})`,
+            });
+        }
+    }
+    else {
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            reason: "seed-unavailable",
+            state: "fallback",
+            target: target.relativePath,
+            message: "CoW seed is unavailable; repairing from an empty target",
+        });
+    }
+    await repairTarget(adapter, target, execution, seeded, ownership, events, reporter);
+}
+async function repairTarget(adapter, target, execution, seeded, ownership, events, reporter) {
+    const beforeRepairInspection = await inspectDestination(target.worktreePath, target.targetPath);
+    if (beforeRepairInspection.kind === "unsafe") {
+        recordBootstrapFailure(events, reporter, adapter, target, beforeRepairInspection.reason, "destination-unsafe");
+        return;
+    }
+    const presentBeforeRepair = beforeRepairInspection.kind === "exists";
+    try {
+        await adapter.repair(target, execution);
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            state: target.repairState,
+            target: target.relativePath,
+            message: seeded
+                ? "reused and repaired"
+                : "installed or repaired from a clean target",
+        });
+    }
+    catch (firstError) {
+        const firstFailureContext = {
+            target,
+            ownership,
+            targetExistedBeforeRepair: presentBeforeRepair,
+        };
+        const cleanupError = await adapter
+            .cleanupAfterRepairFailure(firstFailureContext)
+            .then(() => undefined)
+            .catch((error) => toErrorMessage(error));
+        if (!adapter.shouldRetryAfterRepairFailure(firstFailureContext)) {
+            recordBootstrapFailure(events, reporter, adapter, target, formatRepairFailure(firstError, cleanupError === undefined ? undefined : cleanupError), "repair-failed");
+            return;
+        }
+        if (cleanupError) {
+            recordBootstrapFailure(events, reporter, adapter, target, formatRepairFailure(firstError, cleanupError), "repair-cleanup-failed");
+            return;
+        }
+        recordBootstrapEvent(events, reporter, {
+            adapter: adapter.name,
+            kind: adapter.kind,
+            reason: "seed-repair-failed",
+            state: "fallback",
+            target: target.relativePath,
+            message: `seed repair failed; removed the seed and retrying clean (${toErrorMessage(firstError)})`,
+        });
+        const beforeRetryInspection = await inspectDestination(target.worktreePath, target.targetPath);
+        if (beforeRetryInspection.kind === "unsafe") {
+            recordBootstrapFailure(events, reporter, adapter, target, beforeRetryInspection.reason, "destination-unsafe");
+            return;
+        }
+        const presentBeforeRetry = beforeRetryInspection.kind === "exists";
+        try {
+            await adapter.repair(target, execution);
+            recordBootstrapEvent(events, reporter, {
+                adapter: adapter.name,
+                kind: adapter.kind,
+                reason: "repair-retry",
+                state: target.repairState,
+                target: target.relativePath,
+                message: "installed or repaired from a clean target",
+            });
+        }
+        catch (secondError) {
+            const cleanupError = await adapter
+                .cleanupAfterRepairFailure({
+                target,
+                ownership,
+                targetExistedBeforeRepair: presentBeforeRetry,
+            })
+                .then(() => undefined)
+                .catch((error) => toErrorMessage(error));
+            recordBootstrapFailure(events, reporter, adapter, target, formatRepairFailure(secondError, cleanupError), "repair-failed");
+        }
+    }
+}
+function recordBootstrapFailure(events, reporter, adapter, target, message, reason) {
+    recordBootstrapEvent(events, reporter, {
+        adapter: adapter.name,
+        kind: adapter.kind,
+        reason,
+        state: "failed",
+        target: target.relativePath,
+        message,
+    });
+}
+function recordBootstrapEvent(events, reporter, event) {
+    events.push(event);
+    reporter.dependency(event);
+}
+function formatRepairFailure(error, cleanupError) {
+    const message = `repair failed: ${toErrorMessage(error)}`;
+    return cleanupError ? `${message}; cleanup failed: ${cleanupError}` : message;
+}
+function bootstrapStrategy(mode, target, seedable) {
+    if (mode === "install-only" || target.repairState === "installed") {
+        return "install-only";
+    }
+    return seedable ? "cow-then-repair" : "repair-only";
+}
+function createBootstrapAdapters(checkUvRuntime, cargoBuildCommand) {
+    return [
+        new LockfileBootstrapAdapter({
+            name: "pnpm",
+            kind: "dependency",
+            lockfile: "pnpm-lock.yaml",
+            relativePath: "node_modules",
+            repairCommand: "pnpm install --frozen-lockfile",
+            shell: false,
+            beforeRepair: async (target) => {
+                if (!target.existingBeforeBootstrap) {
+                    await rm(join(target.targetPath, ".modules.yaml"), {
+                        force: true,
+                    });
+                }
+            },
+        }),
+        new LockfileBootstrapAdapter({
+            name: "yarn",
+            kind: "dependency",
+            lockfile: "yarn.lock",
+            relativePath: "node_modules",
+            repairCommand: "yarn install --immutable",
+            shell: false,
+        }),
+        new LockfileBootstrapAdapter({
+            name: "npm",
+            kind: "dependency",
+            lockfile: "package-lock.json",
+            relativePath: "node_modules",
+            repairCommand: "npm ci",
+            shell: false,
+            seedPolicy: "never",
+            repairCommandOverride: (target) => target.existingBeforeBootstrap ? "npm install" : "npm ci",
+            repairState: "installed",
+        }),
+        new LockfileBootstrapAdapter({
+            name: "bundler",
+            kind: "dependency",
+            lockfile: "Gemfile.lock",
+            relativePath: "vendor/bundle",
+            repairCommand: "bundle install",
+            shell: false,
+            commandOptions: () => ({
+                env: { BUNDLE_PATH: "vendor/bundle" },
+            }),
+        }),
+        new LockfileBootstrapAdapter({
+            name: "uv",
+            kind: "dependency",
+            lockfile: "uv.lock",
+            relativePath: ".venv",
+            repairCommand: "uv sync --locked",
+            shell: false,
+            canSeedOverride: checkUvRuntime,
+        }),
+        new LockfileBootstrapAdapter({
+            name: "cargo",
+            kind: "build-cache",
+            lockfile: "Cargo.lock",
+            relativePath: "target",
+            repairCommand: cargoBuildCommand?.trim() || "cargo check",
+            shell: cargoBuildCommand ? undefined : false,
+        }),
+    ];
+}
+class LockfileBootstrapAdapter {
+    kind;
+    lockfile;
+    name;
+    relativePath;
+    defaultRepairCommand;
+    shell;
+    seedPolicy;
+    canSeedOverride;
+    beforeRepair;
+    commandOptions;
+    repairCommandOverride;
+    repairState;
+    constructor(spec) {
+        this.name = spec.name;
+        this.kind = spec.kind;
+        this.lockfile = spec.lockfile;
+        this.relativePath = spec.relativePath;
+        this.defaultRepairCommand = spec.repairCommand;
+        this.shell = spec.shell;
+        this.seedPolicy = spec.seedPolicy ?? "always";
+        this.canSeedOverride = spec.canSeedOverride;
+        this.beforeRepair = spec.beforeRepair;
+        this.commandOptions = spec.commandOptions;
+        this.repairCommandOverride = spec.repairCommandOverride;
+        this.repairState = spec.repairState ?? "repaired";
+    }
+    async detect(context) {
+        const detectionRoot = context.detectionRoot ?? context.sourceRoot;
+        if (!(await pathExists(join(detectionRoot, this.lockfile))))
+            return null;
+        const sourcePath = join(context.sourceRoot, this.relativePath);
+        const targetPath = join(context.worktreePath, this.relativePath);
+        const destinationInspection = await inspectDestination(context.worktreePath, targetPath);
+        const target = {
+            adapter: this.name,
+            kind: this.kind,
+            relativePath: this.relativePath,
+            sourceRoot: context.sourceRoot,
+            worktreePath: context.worktreePath,
+            sourcePath,
+            targetPath,
+            repairCommand: this.defaultRepairCommand,
+            repairState: this.repairState,
+            existingBeforeBootstrap: destinationInspection.kind === "exists",
+        };
+        return {
+            ...target,
+            repairCommand: this.repairCommandOverride?.(target) ?? target.repairCommand,
+        };
+    }
+    seedPath(target) {
+        return target.sourcePath;
+    }
+    async repair(target, context) {
+        await this.beforeRepair?.(target);
+        await context.runCommand(target.repairCommand, target.worktreePath, context.stderr, context.stdout, {
+            ...this.commandOptions?.(target),
+            shell: this.shell,
+        });
+    }
+    async canSeed(target) {
+        if (this.seedPolicy === "never")
+            return false;
+        if (!(await safeSourceDirectory(target)))
+            return false;
+        return (await this.canSeedOverride?.(target)) ?? true;
+    }
+    output(target) {
+        return {
+            adapter: this.name,
+            kind: this.kind,
+            target: target.relativePath,
+            repairCommand: target.repairCommand,
+        };
+    }
+    shouldRetryAfterRepairFailure(context) {
+        return context.ownership === "adapter" || context.ownership === "syncDirs";
+    }
+    async cleanupAfterRepairFailure(context) {
+        if (context.target.existingBeforeBootstrap) {
+            return;
+        }
+        if (context.ownership === "adapter" || context.ownership === "syncDirs") {
+            await rm(context.target.targetPath, { force: true, recursive: true });
+            return;
+        }
+        if (context.ownership === "empty" && !context.targetExistedBeforeRepair) {
+            await rm(context.target.targetPath, { force: true, recursive: true });
+        }
+    }
+}
+async function safeSourceDirectory(target) {
+    try {
+        const [root, source] = await Promise.all([
+            realpath(target.sourceRoot),
+            realpath(target.sourcePath),
+        ]);
+        const sourceStats = await lstat(source);
+        return sourceStats.isDirectory() && isWithin(root, source);
+    }
+    catch {
+        return false;
+    }
+}
+async function defaultCheckUvRuntime(target) {
+    try {
+        const config = await readFile(join(target.sourcePath, "pyvenv.cfg"), "utf8");
+        const expected = config.match(/^version\s*=\s*(\d+\.\d+)/mu)?.[1];
+        if (!expected)
+            return false;
+        const sourceInterpreter = join(target.sourcePath, process.platform === "win32" ? "Scripts/python.exe" : "bin/python");
+        const fingerprintScript = "import platform, sys; print(f'{sys.version_info.major}.{sys.version_info.minor}|{platform.machine()}|{sys.implementation.cache_tag}')";
+        const [source, current] = await Promise.all([
+            execFileAsync(sourceInterpreter, ["-c", fingerprintScript]),
+            execFileAsync("python3", ["-c", fingerprintScript]),
+        ]);
+        const sourceFingerprint = source.stdout.trim();
+        const currentFingerprint = current.stdout.trim();
+        return (sourceFingerprint === currentFingerprint &&
+            sourceFingerprint.startsWith(`${expected}|`));
+    }
+    catch {
+        return false;
+    }
+}
+function uniquePaths(paths) {
+    return [...new Set(paths.filter((path) => Boolean(path)))];
+}
+async function isAllowedSourceRoot(repoRoot, sourceRoot) {
+    try {
+        const [resolvedRepoRoot, resolvedSourceRoot] = await Promise.all([
+            realpath(repoRoot),
+            realpath(sourceRoot),
+        ]);
+        if (resolvedRepoRoot === resolvedSourceRoot)
+            return true;
+        const gitFile = await readFile(join(resolvedSourceRoot, ".git"), "utf8");
+        const gitDirectory = gitFile.match(/^gitdir:\s*(.+)$/mu)?.[1];
+        if (!gitDirectory)
+            return false;
+        return isWithin(join(resolvedRepoRoot, ".git", "worktrees"), resolve(resolvedSourceRoot, gitDirectory));
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(root, candidate) {
+    const distance = relative(root, candidate);
+    return (distance === "" || (distance !== ".." && !distance.startsWith(`..${sep}`)));
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/dir-clone.d.ts

@@ -0,0 +1,33 @@
+export interface CloneDirResult {
+    bytes?: number;
+    ms: number;
+}
+export interface CloneRequestOptions {
+    destinationRoot?: string;
+    measureBytes?: boolean;
+}
+export interface CloneDirOptions extends CloneRequestOptions {
+    platform?: NodeJS.Platform;
+    runCommand?: (command: string, args: string[]) => Promise<void>;
+    copyDirectory?: (source: string, destination: string) => Promise<void>;
+    copyFile?: (source: string, destination: string) => Promise<void>;
+}
+export type CloneDirectory = (source: string, destination: string, options?: CloneRequestOptions) => Promise<CloneDirResult>;
+export declare function waitForCloneLock(destination: string, timeoutMs?: number): Promise<boolean>;
+export declare function cloneDir(source: string, destination: string, options?: CloneDirOptions): Promise<CloneDirResult>;
+export declare class CloneDestinationExistsError extends Error {
+    readonly code = "GJI_CLONE_DESTINATION_EXISTS";
+    constructor(destination: string);
+}
+export declare class CloneUnsupportedError extends Error {
+    readonly code = "GJI_CLONE_UNSUPPORTED";
+    constructor(reason: string);
+}
+export declare class CloneInProgressError extends Error {
+    readonly code = "GJI_CLONE_IN_PROGRESS";
+    constructor(destination: string);
+}
+export declare function isCloneDestinationExistsError(error: unknown): error is CloneDestinationExistsError;
+export declare function isCloneUnsupportedError(error: unknown): boolean;
+export declare function isCloneInProgressError(error: unknown): error is CloneInProgressError;
+export declare function directorySize(path: string): Promise<number>;