@larose/pi-web 0.3.0

package/dist/server/git-workspaces.js

@@ -0,0 +1,559 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, lstat, mkdir, open, readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { AppError } from "./errors.js";
+const MANAGED_EXCLUDE = "/.pi/worktrees/";
+const GIT_MAX_BUFFER = 4 * 1024 * 1024;
+class GitCommandError extends Error {
+    exitCode;
+    unavailable;
+    stderr;
+    constructor(message, exitCode, unavailable, stderr, options) {
+        super(message, options);
+        this.name = "GitCommandError";
+        this.exitCode = exitCode;
+        this.unavailable = unavailable;
+        this.stderr = stderr;
+    }
+}
+function runFile(file, args) {
+    return new Promise((resolvePromise, reject) => {
+        execFile(file, [...args], {
+            encoding: "utf8",
+            maxBuffer: GIT_MAX_BUFFER,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        }, (error, stdout, stderr) => {
+            if (!error) {
+                resolvePromise({ stdout, stderr });
+                return;
+            }
+            const systemError = error;
+            const unavailable = systemError.code === "ENOENT";
+            const exitCode = typeof systemError.code === "number" ? systemError.code : null;
+            reject(new GitCommandError("Git command failed", exitCode, unavailable, stderr, { cause: error }));
+        });
+    });
+}
+function parsePorcelainWorktrees(output) {
+    const records = [];
+    for (const block of output.split("\0\0")) {
+        if (!block) {
+            continue;
+        }
+        const fields = block.split("\0");
+        const pathField = fields.find((field) => field.startsWith("worktree "));
+        if (!pathField) {
+            continue;
+        }
+        const commitField = fields.find((field) => field.startsWith("HEAD "));
+        const branchField = fields.find((field) => field.startsWith("branch refs/heads/"));
+        records.push({
+            path: pathField.slice("worktree ".length),
+            commit: commitField ? commitField.slice("HEAD ".length) : null,
+            branch: branchField ? branchField.slice("branch refs/heads/".length) : null,
+            detached: fields.includes("detached"),
+            bare: fields.includes("bare"),
+            prunable: fields.some((field) => field === "prunable" || field.startsWith("prunable ")),
+        });
+    }
+    return records;
+}
+function headFromRecord(record) {
+    if (record.branch) {
+        return { type: "branch", name: record.branch };
+    }
+    if ((record.detached || !record.branch) && record.commit) {
+        return { type: "detached", commit: record.commit, shortCommit: record.commit.slice(0, 12) };
+    }
+    return null;
+}
+function pathIsWithin(parent, candidate) {
+    const child = relative(parent, candidate);
+    return child === "" || (child !== ".." && !child.startsWith(`..${sep}`) && !isAbsolute(child));
+}
+async function canonicalDirectory(path, code = "invalid_cwd") {
+    try {
+        const canonical = await realpath(resolve(path));
+        const details = await stat(canonical);
+        if (!details.isDirectory()) {
+            throw new Error("Not a directory");
+        }
+        return canonical;
+    }
+    catch (error) {
+        throw new AppError(code, "The working directory does not exist or is inaccessible", 400, { cause: error });
+    }
+}
+async function optionalCanonicalDirectory(path) {
+    try {
+        const canonical = await realpath(path);
+        return (await stat(canonical)).isDirectory() ? canonical : null;
+    }
+    catch {
+        return null;
+    }
+}
+function unavailable(reasonCode, reason) {
+    return { available: false, reasonCode, reason };
+}
+function gitFailureMessage(error, fallback) {
+    if (!(error instanceof GitCommandError)) {
+        return fallback;
+    }
+    const detail = error.stderr.trim().split("\n")[0];
+    return detail ? `${fallback}: ${detail}` : fallback;
+}
+export class GitWorkspaceService {
+    gitBinary;
+    constructor(options = {}) {
+        this.gitBinary = options.gitBinary ?? "git";
+    }
+    async inspect(cwd) {
+        let canonicalCwd;
+        try {
+            canonicalCwd = await canonicalDirectory(cwd);
+        }
+        catch {
+            return {
+                context: null,
+                worktrees: [],
+                creation: unavailable("inspection_failed", "The working directory does not exist or is inaccessible."),
+            };
+        }
+        try {
+            const details = await this.repositoryDetails(canonicalCwd);
+            if (!details) {
+                if (await this.isBareRepository(canonicalCwd)) {
+                    return {
+                        context: null,
+                        worktrees: [],
+                        creation: unavailable("unsupported_repository", "This is a bare Git repository; managed worktrees require a non-bare repository checkout."),
+                    };
+                }
+                return {
+                    context: null,
+                    worktrees: [],
+                    creation: unavailable("not_git", "This directory is not inside a Git working tree."),
+                };
+            }
+            const worktrees = await this.mappedWorktrees(details);
+            const creation = await this.creationAvailability(details);
+            return { context: details.context, worktrees, creation };
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.unavailable) {
+                return {
+                    context: null,
+                    worktrees: [],
+                    creation: unavailable("git_unavailable", "Git is not installed or is not available to the server."),
+                };
+            }
+            return {
+                context: null,
+                worktrees: [],
+                creation: unavailable("inspection_failed", "Git metadata for this working directory could not be inspected."),
+            };
+        }
+    }
+    async removeWorktree(cwd, inputTarget, protectedCwds = []) {
+        const sourceCwd = await canonicalDirectory(cwd);
+        if (typeof inputTarget !== "string" || !isAbsolute(inputTarget.trim())) {
+            throw new AppError("invalid_worktree", "An absolute linked worktree path is required");
+        }
+        const target = await canonicalDirectory(inputTarget.trim(), "invalid_worktree");
+        let details;
+        try {
+            details = await this.repositoryDetails(sourceCwd);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.unavailable) {
+                throw new AppError("git_unavailable", "Git is not installed or is not available to the server", 503, {
+                    cause: error,
+                });
+            }
+            throw new AppError("git_inspection_failed", "Could not inspect Git metadata for the working directory", 422, {
+                cause: error,
+            });
+        }
+        if (!details) {
+            throw new AppError("not_git", "The working directory is not inside a Git working tree", 422);
+        }
+        if (!details.primaryRoot) {
+            throw new AppError("primary_worktree_unavailable", "Removing a linked worktree requires a usable repository checkout", 422);
+        }
+        if (target === details.primaryRoot) {
+            throw new AppError("primary_worktree_removal", "The repository checkout cannot be removed", 409);
+        }
+        let attached = false;
+        for (let index = 1; index < details.worktrees.length; index += 1) {
+            const worktree = details.worktrees[index];
+            if (!worktree || worktree.bare || worktree.prunable) {
+                continue;
+            }
+            if ((await optionalCanonicalDirectory(worktree.path)) === target) {
+                attached = true;
+                break;
+            }
+        }
+        if (!attached) {
+            throw new AppError("unknown_worktree", "The directory is not an attached linked worktree", 404);
+        }
+        for (const protectedCwd of protectedCwds) {
+            if (pathIsWithin(target, resolve(protectedCwd))) {
+                throw new AppError("worktree_in_use", "The linked worktree contains the Pi Web startup directory or an active session", 409);
+            }
+        }
+        try {
+            await this.git(details.primaryRoot, ["worktree", "remove", target]);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.unavailable) {
+                throw new AppError("git_unavailable", "Git is not installed or is not available to the server", 503, {
+                    cause: error,
+                });
+            }
+            throw new AppError("worktree_remove_failed", gitFailureMessage(error, "Git could not remove the linked worktree"), 409, { cause: error });
+        }
+        return { worktreeRoot: target };
+    }
+    async prepareWorktree(cwd, inputName) {
+        const sourceCwd = await canonicalDirectory(cwd);
+        const branch = await this.validateName(inputName, sourceCwd);
+        let details;
+        try {
+            details = await this.repositoryDetails(sourceCwd);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.unavailable) {
+                throw new AppError("git_unavailable", "Git is not installed or is not available to the server", 503, {
+                    cause: error,
+                });
+            }
+            throw new AppError("git_inspection_failed", "Could not inspect Git metadata for the working directory", 422, {
+                cause: error,
+            });
+        }
+        if (!details) {
+            if (await this.isBareRepository(sourceCwd)) {
+                throw new AppError("unsupported_repository", "Managed worktree creation requires a usable non-bare repository checkout", 422);
+            }
+            throw new AppError("not_git", "The working directory is not inside a Git working tree", 422);
+        }
+        const creation = await this.creationAvailability(details);
+        if (!creation.available) {
+            const code = creation.reasonCode === "primary_worktree_unavailable"
+                ? "primary_worktree_unavailable"
+                : "unsupported_repository";
+            throw new AppError(code, creation.reason, 422);
+        }
+        const repositoryRoot = details.context.repositoryRoot;
+        const managedParent = resolve(repositoryRoot, ".pi", "worktrees");
+        const target = resolve(managedParent, branch);
+        if (!pathIsWithin(repositoryRoot, managedParent) ||
+            !pathIsWithin(managedParent, target) ||
+            target === managedParent) {
+            throw new AppError("invalid_worktree_name", "The worktree name must resolve beneath the repository worktree directory");
+        }
+        await this.validateManagedAncestors(repositoryRoot);
+        try {
+            await lstat(target);
+            throw new AppError("worktree_path_exists", `The managed worktree path already exists: ${target}`, 409);
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw error;
+            }
+            if (error.code !== "ENOENT") {
+                throw new AppError("worktree_path_unavailable", "The managed worktree path could not be inspected", 422, {
+                    cause: error,
+                });
+            }
+        }
+        try {
+            await this.git(sourceCwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+            throw new AppError("worktree_branch_exists", `The branch already exists: ${branch}`, 409);
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw error;
+            }
+            if (!(error instanceof GitCommandError) || error.exitCode !== 1) {
+                throw new AppError("git_command_failed", "Could not check whether the worktree branch exists", 502, {
+                    cause: error,
+                });
+            }
+        }
+        try {
+            await mkdir(managedParent, { recursive: true });
+            const canonicalManagedParent = await realpath(managedParent);
+            if (!pathIsWithin(repositoryRoot, canonicalManagedParent)) {
+                throw new AppError("worktree_path_outside_repository", "The managed worktree directory resolves outside the repository checkout", 422);
+            }
+            await this.ensureExcluded(details.commonGitDir);
+            await this.git(sourceCwd, ["worktree", "add", "-b", branch, target, "HEAD"]);
+        }
+        catch (error) {
+            if (error instanceof AppError) {
+                throw error;
+            }
+            throw new AppError("worktree_create_failed", gitFailureMessage(error, "Git could not create the worktree"), 502, {
+                cause: error,
+            });
+        }
+        let rolledBack = false;
+        const rollback = async () => {
+            if (rolledBack) {
+                return;
+            }
+            const failures = [];
+            try {
+                await this.git(sourceCwd, ["worktree", "remove", "--force", target]);
+            }
+            catch (error) {
+                failures.push(gitFailureMessage(error, "could not remove the checkout"));
+            }
+            try {
+                await this.git(sourceCwd, ["branch", "-D", "--", branch]);
+            }
+            catch (error) {
+                failures.push(gitFailureMessage(error, "could not remove the branch"));
+            }
+            if (failures.length > 0) {
+                throw new AppError("worktree_cleanup_failed", `Could not fully roll back the new worktree: ${failures.join("; ")}`, 500);
+            }
+            rolledBack = true;
+        };
+        const mappedCwd = resolve(target, details.context.relativeCwd);
+        if (!pathIsWithin(target, mappedCwd)) {
+            return await this.rollbackPreparation(rollback, "The mapped working directory resolves outside the new worktree");
+        }
+        try {
+            const canonicalMappedCwd = await canonicalDirectory(mappedCwd, "worktree_mapped_cwd_missing");
+            if (!pathIsWithin(await realpath(target), canonicalMappedCwd)) {
+                return await this.rollbackPreparation(rollback, "The mapped working directory resolves outside the new worktree");
+            }
+            return { cwd: canonicalMappedCwd, worktreeRoot: await realpath(target), branch, rollback };
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "worktree_cleanup_failed") {
+                throw error;
+            }
+            return await this.rollbackPreparation(rollback, "The corresponding working directory does not exist in the new worktree", error);
+        }
+    }
+    async rollbackPreparation(rollback, message, cause) {
+        try {
+            await rollback();
+        }
+        catch (cleanupError) {
+            throw new AppError("worktree_cleanup_failed", `${message}. Cleanup also failed: ${cleanupError.message}`, 500, { cause: cleanupError });
+        }
+        throw new AppError("worktree_mapped_cwd_missing", message, 422, cause ? { cause } : undefined);
+    }
+    async validateManagedAncestors(repositoryRoot) {
+        for (const path of [resolve(repositoryRoot, ".pi"), resolve(repositoryRoot, ".pi", "worktrees")]) {
+            try {
+                await lstat(path);
+                const canonical = await optionalCanonicalDirectory(path);
+                if (!canonical) {
+                    throw new AppError("worktree_path_unavailable", "A managed worktree parent path is not a directory", 422);
+                }
+                if (!pathIsWithin(repositoryRoot, canonical)) {
+                    throw new AppError("worktree_path_outside_repository", "The managed worktree directory resolves outside the repository checkout", 422);
+                }
+            }
+            catch (error) {
+                if (error instanceof AppError) {
+                    throw error;
+                }
+                if (error.code === "ENOENT") {
+                    return;
+                }
+                throw new AppError("worktree_path_unavailable", "A managed worktree parent path could not be inspected", 422, {
+                    cause: error,
+                });
+            }
+        }
+    }
+    async validateName(input, cwd) {
+        if (typeof input !== "string") {
+            throw new AppError("invalid_worktree_name", "A worktree name is required");
+        }
+        const name = input.trim();
+        if (!name ||
+            name === "." ||
+            name === ".." ||
+            name.startsWith("-") ||
+            name.includes("/") ||
+            name.includes("\\") ||
+            basename(name) !== name) {
+            throw new AppError("invalid_worktree_name", "The worktree name must be one safe path segment and branch name");
+        }
+        try {
+            await this.git(cwd, ["check-ref-format", `refs/heads/${name}`]);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.unavailable) {
+                throw new AppError("git_unavailable", "Git is not installed or is not available to the server", 503, {
+                    cause: error,
+                });
+            }
+            throw new AppError("invalid_worktree_name", "The worktree name is not a valid Git branch name");
+        }
+        return name;
+    }
+    async isBareRepository(cwd) {
+        try {
+            return (await this.git(cwd, ["rev-parse", "--is-bare-repository"])).stdout.trim() === "true";
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.exitCode !== null) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async repositoryDetails(cwd) {
+        let worktreeRootOutput;
+        try {
+            worktreeRootOutput = await this.git(cwd, ["rev-parse", "--show-toplevel"]);
+        }
+        catch (error) {
+            if (error instanceof GitCommandError && error.exitCode !== null) {
+                return null;
+            }
+            throw error;
+        }
+        const worktreeRoot = await optionalCanonicalDirectory(worktreeRootOutput.stdout.trim());
+        if (!worktreeRoot || !pathIsWithin(worktreeRoot, cwd)) {
+            return null;
+        }
+        const [commonDirResult, worktreeListResult] = await Promise.all([
+            this.git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+            this.git(cwd, ["worktree", "list", "--porcelain", "-z"]),
+        ]);
+        const commonGitDir = await realpath(commonDirResult.stdout.trim());
+        const worktrees = parsePorcelainWorktrees(worktreeListResult.stdout);
+        const primaryRecord = worktrees[0];
+        const primaryRoot = primaryRecord && !primaryRecord.bare ? await optionalCanonicalDirectory(primaryRecord.path) : null;
+        const currentRecord = await this.findCurrentRecord(worktrees, worktreeRoot);
+        let head = currentRecord ? headFromRecord(currentRecord) : null;
+        if (!head) {
+            try {
+                const branch = (await this.git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"])).stdout.trim();
+                if (branch) {
+                    head = { type: "branch", name: branch };
+                }
+            }
+            catch (error) {
+                if (!(error instanceof GitCommandError) || error.exitCode === null) {
+                    throw error;
+                }
+            }
+        }
+        if (!head) {
+            const commit = (await this.git(cwd, ["rev-parse", "HEAD"])).stdout.trim();
+            head = { type: "detached", commit, shortCommit: commit.slice(0, 12) };
+        }
+        const relativeCwd = relative(worktreeRoot, cwd) || ".";
+        const repositoryRoot = primaryRoot ?? worktreeRoot;
+        return {
+            context: {
+                repositoryRoot,
+                worktreeRoot,
+                relativeCwd,
+                head,
+                isLinkedWorktree: primaryRoot ? worktreeRoot !== primaryRoot : true,
+            },
+            commonGitDir,
+            worktrees,
+            primaryRoot,
+        };
+    }
+    async findCurrentRecord(worktrees, worktreeRoot) {
+        for (const worktree of worktrees) {
+            const candidate = await optionalCanonicalDirectory(worktree.path);
+            if (candidate === worktreeRoot) {
+                return worktree;
+            }
+        }
+        return null;
+    }
+    async mappedWorktrees(details) {
+        const summaries = [];
+        for (let index = 0; index < details.worktrees.length; index += 1) {
+            const worktree = details.worktrees[index];
+            if (!worktree || worktree.bare || worktree.prunable) {
+                continue;
+            }
+            const root = await optionalCanonicalDirectory(worktree.path);
+            const head = headFromRecord(worktree);
+            if (!root || !head) {
+                continue;
+            }
+            const mapped = resolve(root, details.context.relativeCwd);
+            if (!pathIsWithin(root, mapped)) {
+                continue;
+            }
+            const cwd = await optionalCanonicalDirectory(mapped);
+            if (!cwd || !pathIsWithin(root, cwd)) {
+                continue;
+            }
+            summaries.push({ worktreeRoot: root, cwd, head, isLinkedWorktree: index !== 0 });
+        }
+        return summaries;
+    }
+    async creationAvailability(details) {
+        if (!details.primaryRoot) {
+            return unavailable("primary_worktree_unavailable", "A usable non-bare repository checkout is required to create a managed worktree.");
+        }
+        if (!isAbsolute(details.commonGitDir) || !isAbsolute(details.primaryRoot)) {
+            return unavailable("unsupported_repository", "This Git repository layout does not support managed worktrees.");
+        }
+        try {
+            await access(details.primaryRoot, constants.R_OK | constants.W_OK);
+            const [bareResult, primaryCommonResult] = await Promise.all([
+                this.git(details.primaryRoot, ["rev-parse", "--is-bare-repository"]),
+                this.git(details.primaryRoot, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+            ]);
+            const primaryCommonGitDir = await realpath(primaryCommonResult.stdout.trim());
+            if (bareResult.stdout.trim() !== "false" || primaryCommonGitDir !== details.commonGitDir) {
+                return unavailable("unsupported_repository", "This Git repository layout does not support managed worktrees.");
+            }
+        }
+        catch {
+            return unavailable("primary_worktree_unavailable", "The repository checkout is not accessible and writable, so a managed worktree cannot be created.");
+        }
+        return { available: true, reasonCode: null, reason: null };
+    }
+    async ensureExcluded(commonGitDir) {
+        const infoDir = join(commonGitDir, "info");
+        const excludePath = join(infoDir, "exclude");
+        await mkdir(infoDir, { recursive: true });
+        let contents = "";
+        try {
+            contents = await readFile(excludePath, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw new AppError("git_exclude_failed", "Could not read Git's local exclusion file", 500, { cause: error });
+            }
+        }
+        const lines = contents.split(/\r?\n/);
+        if (lines.includes(MANAGED_EXCLUDE)) {
+            return;
+        }
+        const prefix = contents.length > 0 && !contents.endsWith("\n") ? "\n" : "";
+        const file = await open(excludePath, "a");
+        try {
+            await file.write(`${prefix}${MANAGED_EXCLUDE}\n`);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    git(cwd, args) {
+        return runFile(this.gitBinary, ["-C", cwd, ...args]);
+    }
+}