@magland/mochi 0.3.1

package/dist/ops.js

@@ -0,0 +1,869 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NewBranchError = exports.MAX_UPLOAD_SIZE = exports.MAX_EDIT_SIZE = exports.OpError = void 0;
+exports.opErrorStatus = opErrorStatus;
+exports.createCollection = createCollection;
+exports.createRepo = createRepo;
+exports.forkRepo = forkRepo;
+exports.commitFiles = commitFiles;
+exports.commitFileChange = commitFileChange;
+exports.previewMerge = previewMerge;
+exports.mergeBranch = mergeBranch;
+exports.createBranch = createBranch;
+exports.deleteBranch = deleteBranch;
+exports.createTag = createTag;
+exports.deleteTag = deleteTag;
+exports.setDefaultBranch = setDefaultBranch;
+exports.setDescription = setDescription;
+exports.containedIn = containedIn;
+exports.renameRepo = renameRepo;
+exports.renameCollection = renameCollection;
+exports.deleteRepo = deleteRepo;
+exports.writeFile = writeFile;
+exports.createRepoWithReadme = createRepoWithReadme;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const atomic_1 = require("./atomic");
+const git_1 = require("./git");
+const perms_1 = require("./perms");
+const vault_1 = require("./vault");
+const pointer_1 = require("./pointer");
+const redirects_1 = require("./redirects");
+const layout_1 = require("./layout");
+const scan_1 = require("./scan");
+class OpError extends Error {
+    kind;
+    constructor(message, kind = 'invalid') {
+        super(message);
+        this.kind = kind;
+    }
+}
+exports.OpError = OpError;
+/**
+ * The HTTP status a failed operation deserves.
+ *
+ * Both transports were deciding this inline, and the spellings had drifted from
+ * each other: several read `kind === 'exists' ? 409 : 400`, which is right about
+ * a name already taken and wrong about a `conflict`, so a branch that moved
+ * under an edit came back as a malformed request. Since the whole point of the
+ * kind is to tell a caller whether retrying could help, that distinction is
+ * worth keeping in one place.
+ *
+ * `nochange` is 400 here because a caller that asked for a state the vault is
+ * already in has changed nothing. The JSON API answers it as a success instead,
+ * since it can say `changed: false` in the body where a rendered page cannot;
+ * `sendOpError` settles that case before consulting this.
+ */
+function opErrorStatus(kind) {
+    switch (kind) {
+        case 'notfound':
+            return 404;
+        case 'exists':
+        case 'conflict':
+            return 409;
+        default:
+            return 400;
+    }
+}
+/**
+ * The largest single file a commit made through the server may carry. Both
+ * transports use it, so that what the browser refuses to edit is what the API
+ * refuses to write.
+ */
+exports.MAX_EDIT_SIZE = 1024 * 1024;
+/**
+ * What one upload or one multi-file commit may carry in total. Big enough for
+ * the images and fixtures people add through a browser, small enough that the
+ * body can be held whole while it is parsed; anything larger belongs in a push,
+ * or in Git LFS.
+ */
+exports.MAX_UPLOAD_SIZE = 25 * 1024 * 1024;
+function authorEnv(author) {
+    return {
+        ...process.env,
+        GIT_AUTHOR_NAME: author.name,
+        GIT_AUTHOR_EMAIL: author.email,
+        GIT_COMMITTER_NAME: author.name,
+        GIT_COMMITTER_EMAIL: author.email,
+    };
+}
+function tmpFile(prefix) {
+    return path.join(os.tmpdir(), `${prefix}-${crypto.randomBytes(8).toString('hex')}`);
+}
+/**
+ * Create an empty collection: a directory in the vault with no repositories in
+ * it yet. Pushing to a new path creates its collection on the way (see
+ * createRepo), so this exists for the other order, where a collection is made
+ * first and filled afterwards, by an import or a push.
+ */
+function createCollection(root, name) {
+    if (!(0, scan_1.isValidName)(name) || (0, scan_1.isDotName)(name))
+        throw new OpError('invalid collection name');
+    const dir = (0, layout_1.collectionDir)(root, name);
+    if (fs.existsSync(dir))
+        throw new OpError(`collection ${name} already exists`, 'exists');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(path.join(dir, layout_1.REPOS_DIR));
+    return dir;
+}
+/**
+ * Refuse a name that would place a new repository on top of the directories
+ * another repository keeps beside it. Creation is the only place this is
+ * asked: a repository that already carries such a name goes on working.
+ */
+function checkNewRepoName(name) {
+    const suffix = (0, scan_1.reservedRepoSuffix)(name);
+    if (suffix) {
+        throw new OpError(`a repository may not be named to end in ${suffix}, which is reserved for the directories a repository keeps beside it`);
+    }
+}
+/**
+ * Refuse a dot-prefixed collection. A repository's collection is created on
+ * the way when it does not exist, here and in fork and move alike, so the
+ * three of them are where a collection can come into being under a name
+ * nobody typed into the new-collection form. Only a repository may carry a
+ * leading dot; see isDotName in src/scan.ts.
+ */
+function checkNewCollectionName(collection) {
+    if ((0, scan_1.isDotName)(collection))
+        throw new OpError('a collection name may not begin with a dot');
+}
+async function createRepo(root, collection, name, opts = {}) {
+    if (!(0, scan_1.isValidName)(collection) || !(0, scan_1.isValidName)(name))
+        throw new OpError('invalid collection or repository name');
+    checkNewCollectionName(collection);
+    checkNewRepoName(name);
+    fs.mkdirSync((0, layout_1.reposDir)(root, collection), { recursive: true });
+    const dir = (0, layout_1.repoPath)(root, collection, `${name}.git`);
+    await (0, git_1.execGit)(root, ['init', '--bare', '--initial-branch=main', dir]);
+    await (0, git_1.execGit)(dir, ['config', 'receive.denyNonFastForwards', 'true']);
+    await (0, git_1.execGit)(dir, ['config', 'receive.denyDeletes', 'true']);
+    await (0, git_1.execGit)(dir, ['config', 'receive.maxInputSize', String(2 * 1024 * 1024 * 1024)]);
+    // Written before the repository is announced anywhere, so a repository asked
+    // for as private is never public for even a moment.
+    if (opts.private)
+        (0, perms_1.setRepoPrivate)(dir, true);
+    return new git_1.GitRepo(dir, collection, name);
+}
+/**
+ * Fork a repository inside the vault: a bare clone of one repository into
+ * another collection, with the parent recorded so both ends can say where the
+ * fork came from.
+ *
+ * A local clone hardlinks its objects, so a fork of a large repository costs
+ * almost nothing on disk until one side or the other gains new objects. The
+ * `origin` remote git writes points at a filesystem path, which means nothing
+ * to anyone reading the fork, so it is removed and replaced by a `mochi
+ * .forkedFrom` entry naming `<collection>/<repo>`. Nothing else comes across:
+ * issues, releases, runs, and the site belong to the repository that has
+ * them, and a fork starts with none.
+ */
+async function forkRepo(root, collection, name, toCollection, toName) {
+    const source = (0, scan_1.findRepo)(root, collection, name);
+    if (!source)
+        throw new OpError(`repository ${collection}/${name} not found`, 'notfound');
+    if (!(0, scan_1.isValidName)(toCollection) || !(0, scan_1.isValidName)(toName)) {
+        throw new OpError('invalid collection or repository name');
+    }
+    checkNewCollectionName(toCollection);
+    checkNewRepoName(toName);
+    if (toCollection === collection && toName === name) {
+        throw new OpError('a repository cannot be forked onto itself');
+    }
+    if ((0, scan_1.findRepo)(root, toCollection, toName)) {
+        throw new OpError(`${toCollection}/${toName} already exists`, 'exists');
+    }
+    fs.mkdirSync((0, layout_1.reposDir)(root, toCollection), { recursive: true });
+    const dir = (0, layout_1.repoPath)(root, toCollection, `${toName}.git`);
+    await (0, git_1.execGit)(root, ['clone', '--bare', source.dir, dir]);
+    await (0, git_1.execGit)(dir, ['remote', 'remove', 'origin']).catch(() => undefined);
+    await (0, git_1.execGit)(dir, ['config', 'mochi.forkedFrom', `${collection}/${name}`]);
+    await (0, git_1.execGit)(dir, ['config', 'receive.denyNonFastForwards', 'true']);
+    await (0, git_1.execGit)(dir, ['config', 'receive.denyDeletes', 'true']);
+    await (0, git_1.execGit)(dir, ['config', 'receive.maxInputSize', String(2 * 1024 * 1024 * 1024)]);
+    const description = fs.existsSync(path.join(source.dir, 'description'))
+        ? fs.readFileSync(path.join(source.dir, 'description'), 'utf8')
+        : '';
+    if (description.trim() !== '' && !description.startsWith('Unnamed repository')) {
+        (0, atomic_1.writeFileAtomic)(path.join(dir, 'description'), description);
+    }
+    // A fork of a private repository starts private, so forking is never a way
+    // to publish what its parent was protecting. Collaborators do not come
+    // across: they belong to the parent, and the forker administers the fork.
+    if ((0, perms_1.repoIsPrivate)(source.dir))
+        (0, perms_1.setRepoPrivate)(dir, true);
+    return new git_1.GitRepo(dir, toCollection, toName);
+}
+async function refTip(repoDir, ref) {
+    try {
+        return (await (0, git_1.execGit)(repoDir, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]))
+            .toString('utf8')
+            .trim();
+    }
+    catch {
+        return null;
+    }
+}
+async function entryExists(repoDir, commit, filePath) {
+    try {
+        await (0, git_1.execGit)(repoDir, ['cat-file', '-e', `${commit}:${filePath}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function entryMode(repoDir, commit, filePath) {
+    const out = (await (0, git_1.execGit)(repoDir, ['ls-tree', commit, '--', filePath])).toString('utf8');
+    const m = out.match(/^(\d{6}) blob /);
+    if (!m)
+        throw new OpError(`${filePath} is not a file at this commit`, 'notfound');
+    return m[1];
+}
+/**
+ * Commit several files at once, which is what an upload is. Same index dance
+ * as commitFileChange and the same optimistic guard on the branch tip; the
+ * difference is only that a batch of paths goes in before the tree is
+ * written, so an upload of twenty files is one commit and not twenty.
+ *
+ * A path that already exists is replaced and keeps its mode, so re-uploading
+ * a script does not quietly drop its executable bit.
+ */
+async function commitFiles(repoDir, args) {
+    const { branch, files, message, author, expectedHead } = args;
+    const removals = args.removals ?? [];
+    if (!(0, git_1.isValidRefName)(branch) || branch.startsWith('-'))
+        throw new OpError('invalid branch name');
+    if (files.length === 0 && removals.length === 0)
+        throw new OpError('no files to commit');
+    for (const file of files) {
+        if (!(0, git_1.isValidRepoPath)(file.path) || file.path === '')
+            throw new OpError(`invalid file path: ${file.path}`);
+    }
+    for (const target of removals) {
+        if (!(0, git_1.isValidRepoPath)(target) || target === '')
+            throw new OpError(`invalid file path: ${target}`);
+    }
+    if (removals.length && expectedHead === null) {
+        throw new OpError('cannot delete a file on a branch that does not exist yet');
+    }
+    if (expectedHead !== null && !(0, git_1.isValidSha)(expectedHead))
+        throw new OpError('invalid expected commit');
+    const indexFile = tmpFile('mochi-index');
+    const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+    try {
+        let baseTree = null;
+        if (expectedHead !== null) {
+            baseTree = (await (0, git_1.execGit)(repoDir, ['rev-parse', `${expectedHead}^{tree}`])).toString('utf8').trim();
+            await (0, git_1.execGit)(repoDir, ['read-tree', expectedHead], { env });
+        }
+        else {
+            await (0, git_1.execGit)(repoDir, ['read-tree', '--empty'], { env });
+        }
+        for (const file of files) {
+            const mode = expectedHead !== null && (await entryExists(repoDir, expectedHead, file.path))
+                ? await entryMode(repoDir, expectedHead, file.path)
+                : '100644';
+            const contentFile = tmpFile('mochi-blob');
+            let blobSha;
+            try {
+                fs.writeFileSync(contentFile, file.content, { mode: 0o600 });
+                blobSha = (await (0, git_1.execGit)(repoDir, ['hash-object', '-w', '--', contentFile])).toString('utf8').trim();
+            }
+            finally {
+                fs.rmSync(contentFile, { force: true });
+            }
+            await (0, git_1.execGit)(repoDir, ['update-index', '--add', '--cacheinfo', `${mode},${blobSha},${file.path}`], { env });
+        }
+        for (const target of removals) {
+            if (!(await entryExists(repoDir, expectedHead, target))) {
+                throw new OpError(`${target} does not exist on ${branch}`, 'notfound');
+            }
+            // update-index --force-remove insists on a work tree; a zero-mode entry
+            // fed to --index-info removes a path without one.
+            await (0, git_1.execGit)(repoDir, ['update-index', '--index-info'], {
+                env,
+                input: `0 ${'0'.repeat(40)}\t${target}\n`,
+            });
+        }
+        const newTree = (await (0, git_1.execGit)(repoDir, ['write-tree'], { env })).toString('utf8').trim();
+        if (newTree === baseTree)
+            throw new OpError('those files are already in the repository, unchanged', 'nochange');
+        const commitArgs = ['commit-tree', newTree, '-m', message];
+        if (expectedHead !== null)
+            commitArgs.push('-p', expectedHead);
+        const newCommit = (await (0, git_1.execGit)(repoDir, commitArgs, { env: authorEnv(author) })).toString('utf8').trim();
+        try {
+            await (0, git_1.execGit)(repoDir, ['update-ref', `refs/heads/${branch}`, newCommit, expectedHead ?? '']);
+        }
+        catch (e) {
+            const tip = await refTip(repoDir, `refs/heads/${branch}`);
+            if (tip !== expectedHead) {
+                throw new OpError(`branch ${branch} has moved since you loaded this page`, 'conflict');
+            }
+            throw e;
+        }
+        return newCommit;
+    }
+    finally {
+        fs.rmSync(indexFile, { force: true });
+    }
+}
+async function commitFileChange(repoDir, args) {
+    const { branch, filePath, message, author, expectedHead, action } = args;
+    if (!(0, git_1.isValidRefName)(branch) || branch.startsWith('-'))
+        throw new OpError('invalid branch name');
+    if (!(0, git_1.isValidRepoPath)(filePath) || filePath === '')
+        throw new OpError('invalid file path');
+    if (expectedHead !== null && !(0, git_1.isValidSha)(expectedHead))
+        throw new OpError('invalid expected commit');
+    const toPath = action.kind === 'edit' && action.toPath && action.toPath !== filePath ? action.toPath : null;
+    if (toPath !== null && !(0, git_1.isValidRepoPath)(toPath))
+        throw new OpError('invalid file path');
+    if (expectedHead !== null) {
+        if (action.kind === 'create') {
+            if (await entryExists(repoDir, expectedHead, filePath)) {
+                throw new OpError(`${filePath} already exists on ${branch}`, 'exists');
+            }
+        }
+        else if (!(await entryExists(repoDir, expectedHead, filePath))) {
+            throw new OpError(`${filePath} does not exist on ${branch}`, 'notfound');
+        }
+        if (toPath !== null && (await entryExists(repoDir, expectedHead, toPath))) {
+            throw new OpError(`${toPath} already exists on ${branch}`, 'exists');
+        }
+    }
+    else if (action.kind !== 'create') {
+        throw new OpError('cannot edit or delete a file on a branch that does not exist');
+    }
+    const indexFile = tmpFile('mochi-index');
+    const env = { ...process.env, GIT_INDEX_FILE: indexFile };
+    try {
+        let baseTree = null;
+        if (expectedHead !== null) {
+            baseTree = (await (0, git_1.execGit)(repoDir, ['rev-parse', `${expectedHead}^{tree}`])).toString('utf8').trim();
+            await (0, git_1.execGit)(repoDir, ['read-tree', expectedHead], { env });
+        }
+        else {
+            await (0, git_1.execGit)(repoDir, ['read-tree', '--empty'], { env });
+        }
+        // update-index --force-remove insists on a work tree; feeding a zero-mode
+        // entry to --index-info removes a path without one.
+        const removePath = async (target) => {
+            await (0, git_1.execGit)(repoDir, ['update-index', '--index-info'], {
+                env,
+                input: `0 ${'0'.repeat(40)}\t${target}\n`,
+            });
+        };
+        if (action.kind === 'delete') {
+            await removePath(filePath);
+        }
+        else {
+            if (toPath !== null)
+                await removePath(filePath);
+            const mode = action.kind === 'edit' && expectedHead !== null
+                ? await entryMode(repoDir, expectedHead, filePath)
+                : '100644';
+            const contentFile = tmpFile('mochi-blob');
+            let blobSha;
+            try {
+                fs.writeFileSync(contentFile, action.content, { mode: 0o600 });
+                blobSha = (await (0, git_1.execGit)(repoDir, ['hash-object', '-w', '--', contentFile])).toString('utf8').trim();
+            }
+            finally {
+                fs.rmSync(contentFile, { force: true });
+            }
+            await (0, git_1.execGit)(repoDir, ['update-index', '--add', '--cacheinfo', `${mode},${blobSha},${toPath ?? filePath}`], {
+                env,
+            });
+        }
+        const newTree = (await (0, git_1.execGit)(repoDir, ['write-tree'], { env })).toString('utf8').trim();
+        if (newTree === baseTree)
+            throw new OpError('no changes to commit', 'nochange');
+        const commitArgs = ['commit-tree', newTree, '-m', message];
+        if (expectedHead !== null)
+            commitArgs.push('-p', expectedHead);
+        const newCommit = (await (0, git_1.execGit)(repoDir, commitArgs, { env: authorEnv(author) })).toString('utf8').trim();
+        try {
+            await (0, git_1.execGit)(repoDir, ['update-ref', `refs/heads/${branch}`, newCommit, expectedHead ?? '']);
+        }
+        catch (e) {
+            const tip = await refTip(repoDir, `refs/heads/${branch}`);
+            if (tip !== expectedHead) {
+                throw new OpError(`branch ${branch} has moved since you loaded this page`, 'conflict');
+            }
+            throw e;
+        }
+        return newCommit;
+    }
+    finally {
+        fs.rmSync(indexFile, { force: true });
+    }
+}
+/**
+ * Work out what merging `head` into branch `base` would come to, in a bare
+ * repository and without a work tree.
+ *
+ * `git merge-tree --write-tree` computes the merged tree in the object
+ * database and names the paths that conflict. The tree it writes when the
+ * merge is clean is not thrown away: the caller commits exactly that tree, so
+ * the merge a reader was shown is the merge that happens. An unreferenced
+ * tree left behind by a preview is ordinary garbage that git collects.
+ */
+async function planMerge(repoDir, base, head) {
+    if (!(0, git_1.isValidRefName)(base) || base.startsWith('-'))
+        throw new OpError('invalid base branch');
+    if (!(0, git_1.isValidRefName)(head) || head.startsWith('-'))
+        throw new OpError('invalid head ref');
+    const baseSha = await refTip(repoDir, `refs/heads/${base}`);
+    if (!baseSha)
+        throw new OpError(`branch ${base} not found`, 'notfound');
+    const headSha = await refTip(repoDir, head);
+    if (!headSha)
+        throw new OpError(`ref ${head} not found`, 'notfound');
+    // Nothing to merge: the head is already in the base's history.
+    if ((await (0, git_1.execGitStatus)(repoDir, ['merge-base', '--is-ancestor', headSha, baseSha])).code === 0) {
+        return { status: 'up-to-date' };
+    }
+    // The base has not moved since the head left it, so the merged tree is the
+    // head's own. A merge commit is still made rather than fast-forwarding:
+    // that commit is the record of the merge, and a history where a proposal
+    // simply appears says nothing about why it was taken. This is what GitHub's
+    // merge button does too.
+    if ((await (0, git_1.execGitStatus)(repoDir, ['merge-base', '--is-ancestor', baseSha, headSha])).code === 0) {
+        const tree = (await (0, git_1.execGit)(repoDir, ['rev-parse', `${headSha}^{tree}`])).toString('utf8').trim();
+        return { status: 'clean', tree, fastForward: true, baseSha, headSha };
+    }
+    const merged = await (0, git_1.execGitStatus)(repoDir, ['merge-tree', '--write-tree', '--name-only', baseSha, headSha]);
+    const lines = merged.stdout.split('\n');
+    const tree = (lines[0] ?? '').trim();
+    if (merged.code === 1 && (0, git_1.isValidSha)(tree)) {
+        // The conflicting paths follow the tree, one per line, and a blank line
+        // ends them before git's own narration of the merge.
+        const paths = [];
+        for (const line of lines.slice(1)) {
+            if (line.trim() === '')
+                break;
+            paths.push(line);
+        }
+        return { status: 'conflict', paths };
+    }
+    if (merged.code !== 0 || !(0, git_1.isValidSha)(tree)) {
+        throw new OpError(merged.stderr.trim() || 'the merge could not be computed');
+    }
+    return { status: 'clean', tree, fastForward: false, baseSha, headSha };
+}
+/** Whether a merge would apply cleanly, without changing anything. */
+async function previewMerge(repoDir, base, head) {
+    const plan = await planMerge(repoDir, base, head);
+    if (plan.status === 'clean') {
+        return { status: 'clean', fastForward: plan.fastForward, base: plan.baseSha, head: plan.headSha };
+    }
+    return plan;
+}
+/**
+ * Merge one ref into a branch and move the branch to the result.
+ *
+ * The branch moves with a guarded update-ref, so a branch that moved while
+ * the reader was deciding fails rather than losing the commit that moved it.
+ * Conflicts are reported, never committed: resolving them needs a work tree
+ * and a person, and the vault has neither.
+ */
+async function mergeBranch(repoDir, base, head, message, author, method = 'merge') {
+    const plan = await planMerge(repoDir, base, head);
+    if (plan.status !== 'clean')
+        return plan;
+    // A squash keeps the merged tree and drops the branch's shape: one commit
+    // on the base, with the base as its only parent, which is what makes the
+    // head's history disappear from the base and the head branch look unmerged
+    // afterwards. A merge keeps both parents, and with them the record of where
+    // the work came from.
+    const parents = method === 'squash' ? ['-p', plan.baseSha] : ['-p', plan.baseSha, '-p', plan.headSha];
+    const sha = (await (0, git_1.execGit)(repoDir, ['commit-tree', plan.tree, ...parents, '-m', message], {
+        env: authorEnv(author),
+    }))
+        .toString('utf8')
+        .trim();
+    await moveBranch(repoDir, base, sha, plan.baseSha);
+    return { status: 'merged', sha, before: plan.baseSha, fastForward: plan.fastForward };
+}
+/** Move a branch, refusing if it is no longer where the caller last saw it. */
+async function moveBranch(repoDir, branch, to, from) {
+    try {
+        await (0, git_1.execGit)(repoDir, ['update-ref', `refs/heads/${branch}`, to, from]);
+    }
+    catch {
+        throw new OpError(`branch ${branch} has moved since this page was loaded`, 'conflict');
+    }
+}
+async function createBranch(repoDir, name, fromRef) {
+    if (!(0, git_1.isValidRefName)(name) || name.startsWith('-'))
+        throw new OpError('invalid branch name');
+    if (!(0, git_1.isValidRefName)(fromRef) || fromRef.startsWith('-'))
+        throw new OpError('invalid source ref');
+    await (0, git_1.execGit)(repoDir, ['check-ref-format', `refs/heads/${name}`]);
+    const sha = await refTip(repoDir, fromRef);
+    if (!sha)
+        throw new OpError(`ref ${fromRef} not found`, 'notfound');
+    try {
+        await (0, git_1.execGit)(repoDir, ['update-ref', `refs/heads/${name}`, sha, '']);
+    }
+    catch {
+        throw new OpError(`branch ${name} already exists`, 'exists');
+    }
+}
+async function deleteBranch(repoDir, name) {
+    if (!(0, git_1.isValidRefName)(name) || name.startsWith('-'))
+        throw new OpError('invalid branch name');
+    // update-ref -d bypasses receive.denyDeletes, deliberately: the receive
+    // config guards against accidental `push --delete`, while deletion here is
+    // explicit, confirmed intent.
+    await (0, git_1.execGit)(repoDir, ['update-ref', '-d', `refs/heads/${name}`]);
+}
+async function createTag(repoDir, name, atRef) {
+    if (!(0, git_1.isValidRefName)(name) || name.startsWith('-'))
+        throw new OpError('invalid tag name');
+    if (!(0, git_1.isValidRefName)(atRef) || atRef.startsWith('-'))
+        throw new OpError('invalid target ref');
+    await (0, git_1.execGit)(repoDir, ['check-ref-format', `refs/tags/${name}`]);
+    const sha = await refTip(repoDir, atRef);
+    if (!sha)
+        throw new OpError(`ref ${atRef} not found`, 'notfound');
+    try {
+        await (0, git_1.execGit)(repoDir, ['update-ref', `refs/tags/${name}`, sha, '']);
+    }
+    catch {
+        throw new OpError(`tag ${name} already exists`, 'exists');
+    }
+}
+async function deleteTag(repoDir, name) {
+    if (!(0, git_1.isValidRefName)(name) || name.startsWith('-'))
+        throw new OpError('invalid tag name');
+    await (0, git_1.execGit)(repoDir, ['update-ref', '-d', `refs/tags/${name}`]);
+}
+async function setDefaultBranch(repoDir, branch) {
+    if (!(0, git_1.isValidRefName)(branch) || branch.startsWith('-'))
+        throw new OpError('invalid branch name');
+    const sha = await refTip(repoDir, `refs/heads/${branch}`);
+    if (!sha)
+        throw new OpError(`branch ${branch} not found`, 'notfound');
+    await (0, git_1.execGit)(repoDir, ['symbolic-ref', 'HEAD', `refs/heads/${branch}`]);
+}
+function setDescription(repoDir, text) {
+    const line = text.replace(/\s+/g, ' ').trim();
+    (0, atomic_1.writeFileAtomic)(path.join(repoDir, 'description'), line === '' ? '' : line + '\n');
+}
+function containedIn(rootReal, target) {
+    let real;
+    try {
+        real = fs.realpathSync(target);
+    }
+    catch {
+        return false;
+    }
+    return real.startsWith(rootReal + path.sep);
+}
+function siblingDir(root, collection, name, suffix) {
+    return (0, layout_1.repoPath)(root, collection, `${(0, scan_1.displayName)(name)}${suffix}`);
+}
+/**
+ * Rename a repository, or move it to another collection - the two are one
+ * operation, since both are a directory rename.
+ *
+ * Everything that belongs to the repository moves with it: the bare
+ * repository, its static site, its workflow runs, its issues, its pull
+ * requests, its releases, and its LFS objects. Leaving any of them behind
+ * would strand state that only that repository can reach, and worse, a
+ * repository later created under the old name would inherit it.
+ *
+ * The move is a sequence of renames rather than one atomic act, which is the
+ * honest limit of a filesystem-backed store. The repository itself moves
+ * first: if a later sibling fails, what is left behind is a directory beside
+ * the old name rather than a repository nobody can find.
+ */
+async function renameRepo(root, collection, name, toCollection, toName, ctx = {}) {
+    const repo = (0, scan_1.findRepo)(root, collection, name);
+    if (!repo)
+        throw new OpError(`repository ${collection}/${name} not found`, 'notfound');
+    if (!(0, scan_1.isValidName)(toCollection) || !(0, scan_1.isValidName)(toName)) {
+        throw new OpError('invalid collection or repository name');
+    }
+    checkNewCollectionName(toCollection);
+    checkNewRepoName(toName);
+    if (toCollection === collection && toName === name)
+        throw new OpError('that is already its name', 'nochange');
+    if ((0, scan_1.findRepo)(root, toCollection, toName)) {
+        throw new OpError(`${toCollection}/${toName} already exists`, 'exists');
+    }
+    const rootReal = fs.realpathSync(root);
+    if (!containedIn(rootReal, repo.dir)) {
+        throw new OpError('repository directory is outside the vault; refusing to move it');
+    }
+    // The .git suffix is optional on disk and is kept as it was found, so a
+    // move never changes how git-lfs derives its endpoint for this repository.
+    const suffix = path.basename(repo.dir).endsWith('.git') ? '.git' : '';
+    const destRepos = (0, layout_1.reposDir)(root, toCollection);
+    fs.mkdirSync(destRepos, { recursive: true });
+    const destRepo = path.join(destRepos, `${toName}${suffix}`);
+    if (fs.existsSync(destRepo))
+        throw new OpError(`${toCollection}/${toName} already exists`, 'exists');
+    // Every check has passed, so from here the move is going to happen: the run
+    // index is told to forget the old identity before the directories move out
+    // from under it. After the checks rather than before, so that a rename
+    // refused for a name that is taken leaves a running job's index entry alone.
+    ctx.runs?.forgetRepo(collection, name);
+    fs.renameSync(repo.dir, destRepo);
+    // The siblings, each moved only if it is there and inside the vault.
+    // containedIn resolves the path first, so a sibling that was never created
+    // fails the same check as one pointing out of the vault, and is skipped.
+    const move = (from, to) => {
+        if (!containedIn(rootReal, from))
+            return;
+        if (fs.existsSync(to)) {
+            throw new OpError(`${path.basename(to)} already exists next to ${toCollection}/${toName}`, 'exists');
+        }
+        fs.renameSync(from, to);
+    };
+    for (const suffix of scan_1.repoSiblingSuffixes) {
+        move(siblingDir(root, collection, name, suffix), path.join(destRepos, `${toName}${suffix}`));
+    }
+    // LFS objects carry the repository in their key or their path, so the store
+    // moves them itself. Unlike deletion this is not best-effort: an object left
+    // behind is one a clone of the moved repository cannot fetch.
+    if (ctx.lfs)
+        await ctx.lfs.renameRepo(collection, name, toCollection, toName);
+    // Last, and only once everything has arrived: the old address is remembered,
+    // so a clone or a link that still names it is redirected here rather than
+    // 404ing. Recorded after the moves for a reason - a redirect written first
+    // and a move that then failed would point at a repository that is not there.
+    // See src/redirects.ts for what the redirect does and does not survive.
+    (0, redirects_1.recordRepoRename)(root, collection, name, toCollection, toName);
+}
+/**
+ * Rename a collection.
+ *
+ * A collection holds everything of its own inside its directory, so unlike a
+ * repository move this is a single rename and not a sequence of them: the
+ * repositories, the directories each of them keeps beside it, and locally
+ * stored LFS objects all sit under the directory being moved and arrive at
+ * the new name together. Only objects in a bucket have to be dealt with
+ * separately, since their keys name the collection rather than living in it,
+ * and the store is asked to move each repository's for that reason.
+ *
+ * One thing a rename does not carry with it, and the interface says so before
+ * it is done: token scopes in vault.json still name the old collection. The
+ * old address itself is remembered, so requests for it are redirected here;
+ * see src/redirects.ts.
+ */
+async function renameCollection(root, name, toName, ctx = {}) {
+    if (!(0, scan_1.isValidName)(name) || !(0, scan_1.isValidName)(toName) || (0, scan_1.isDotName)(toName)) {
+        throw new OpError('invalid collection name');
+    }
+    const dir = (0, layout_1.collectionDir)(root, name);
+    let isDir = false;
+    try {
+        isDir = fs.statSync(dir).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir)
+        throw new OpError(`collection ${name} not found`, 'notfound');
+    if (toName === name)
+        throw new OpError('that is already its name', 'nochange');
+    const dest = (0, layout_1.collectionDir)(root, toName);
+    if (fs.existsSync(dest))
+        throw new OpError(`collection ${toName} already exists`, 'exists');
+    const rootReal = fs.realpathSync(root);
+    if (!containedIn(rootReal, dir)) {
+        throw new OpError('collection directory is outside the vault; refusing to move it');
+    }
+    // Read the repositories before the move, since afterwards they are only
+    // findable under the new name and the store still has to be told the old
+    // one.
+    const repos = (0, scan_1.listRepoDirs)(root, name).map(scan_1.displayName);
+    // As in renameRepo, and for every repository the collection holds: after the
+    // checks, before the directory moves.
+    for (const repo of repos)
+        ctx.runs?.forgetRepo(name, repo);
+    fs.renameSync(dir, dest);
+    // Objects in a bucket, as for a repository move: not best-effort, since an
+    // object left behind is one a clone of the moved repository cannot fetch.
+    // The local backend finds nothing to move, its directories having travelled
+    // with the collection already.
+    if (ctx.lfs) {
+        for (const repo of repos)
+            await ctx.lfs.renameRepo(name, repo, toName, repo);
+    }
+    // Implicit ownership follows from the collection's name, so a rename severs
+    // it: a user who renamed the collection named after them would be locked out
+    // of what is still theirs. The implicit owner, when there is such a user, is
+    // therefore written into the explicit owners the file carries across. Only
+    // ever added, never removed: the reverse rename leaves them listed, which is
+    // redundant beside the name and costs nothing.
+    const state = (0, vault_1.loadVault)(root);
+    if (state.status === 'ok' && state.vault.users[name] && name !== toName) {
+        (0, perms_1.addCollectionOwner)(root, toName, name);
+    }
+    // As for a repository: the old name is remembered, so every address under it
+    // - the collection page and every repository in it - is redirected to the new
+    // one until something else is created under that name.
+    (0, redirects_1.recordCollectionRename)(root, name, toName);
+}
+/**
+ * Delete a repository and everything it accumulated: the bare repository, its
+ * static site, its workflow runs, its issues, its pull requests, its
+ * releases, and its LFS objects.
+ */
+async function deleteRepo(root, collection, name, ctx = {}) {
+    const repo = (0, scan_1.findRepo)(root, collection, name);
+    if (!repo)
+        throw new OpError(`repository ${collection}/${name} not found`, 'notfound');
+    const rootReal = fs.realpathSync(root);
+    if (!containedIn(rootReal, repo.dir)) {
+        throw new OpError('repository directory is outside the vault; refusing to delete');
+    }
+    // As in renameRepo: after the checks, before the files go, so that nothing
+    // is dispatched for a repository that is about to stop existing.
+    ctx.runs?.forgetRepo(collection, name);
+    fs.rmSync(repo.dir, { recursive: true, force: true });
+    // The siblings go too: the site, the workflow runs, the issues, the pull
+    // requests, and the releases. Leaving any of them would orphan a history
+    // nothing can reach, and worse, a repository later created under the same
+    // name would inherit it, with run, issue, and pull numbers continuing from
+    // someone else's.
+    for (const suffix of scan_1.repoSiblingSuffixes) {
+        const dir = siblingDir(root, collection, name, suffix);
+        if (containedIn(rootReal, dir)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    // Stored LFS objects go too, best-effort: by this point the repository is
+    // gone and the objects are unreachable garbage, so a storage failure is
+    // logged rather than allowed to fail the deletion.
+    if (ctx.lfs) {
+        try {
+            await ctx.lfs.deleteRepo(collection, name);
+        }
+        catch (e) {
+            console.error(`LFS cleanup for ${collection}/${name} failed: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    // And any redirect that led here. A redirect pointing at a repository that
+    // no longer exists is inert, but one left pointing at a name that is later
+    // re-created would send traffic meant for the deleted repository to whatever
+    // took its place.
+    (0, redirects_1.forgetRepoRedirects)(root, collection, name);
+}
+/**
+ * A write that failed before it began, because the branch it was to go on could
+ * not be made. Distinct from the write's own failures because it means something
+ * different to a caller: a name already taken is somebody else's branch, not a
+ * file that is already there.
+ */
+class NewBranchError extends OpError {
+}
+exports.NewBranchError = NewBranchError;
+/** Whether a path holds a Git LFS pointer rather than the file itself. */
+async function isPointerAt(repoDir, commit, filePath) {
+    try {
+        const buf = await (0, git_1.execGit)(repoDir, ['cat-file', 'blob', `${commit}:${filePath}`]);
+        return (0, pointer_1.looksLikePointer)(buf);
+    }
+    catch {
+        return false;
+    }
+}
+async function writeFile(repoDir, request) {
+    let branch = request.branch;
+    if (request.newBranch) {
+        if (request.expectedHead === null) {
+            throw new NewBranchError('There is nothing to branch from yet; commit to this branch first.');
+        }
+        try {
+            await createBranch(repoDir, request.newBranch, request.expectedHead);
+        }
+        catch (e) {
+            if (e instanceof OpError)
+                throw new NewBranchError(e.message, e.kind);
+            throw new NewBranchError('Could not create that branch.');
+        }
+        branch = request.newBranch;
+    }
+    // The repository holds a pointer, not the file, so replacing it with text
+    // would replace the pointer and leave the object orphaned. Refused rather than
+    // done, in both transports, and checked here so that neither can skip it.
+    if (request.expectedHead !== null &&
+        request.action.kind !== 'create' &&
+        (await isPointerAt(repoDir, request.expectedHead, request.filePath))) {
+        throw new OpError(`${request.filePath} is stored with Git LFS; the repository holds only a pointer to it. Change it with a git client instead.`);
+    }
+    const sha = await commitFileChange(repoDir, {
+        branch,
+        filePath: request.filePath,
+        message: request.message,
+        author: request.author,
+        expectedHead: request.expectedHead,
+        action: request.action,
+    });
+    return { branch, sha, before: request.expectedHead };
+}
+/**
+ * Create a repository and, when asked, put a first commit in it. The README is
+ * what makes a new repository browsable rather than a page of instructions, and
+ * both transports offer it.
+ *
+ * The caller fires the push event, since it holds the CI engine.
+ */
+async function createRepoWithReadme(root, collection, name, opts) {
+    const repo = await createRepo(root, collection, name, { private: opts.private });
+    const description = (opts.description ?? '').trim();
+    if (description)
+        setDescription(repo.dir, description);
+    if (!opts.readme)
+        return { repo, sha: null };
+    const sha = await commitFileChange(repo.dir, {
+        branch: 'main',
+        filePath: 'README.md',
+        message: 'Initial commit',
+        author: opts.author,
+        expectedHead: null,
+        action: { kind: 'create', content: Buffer.from(`# ${name}\n${description ? `\n${description}\n` : ''}`) },
+    });
+    return { repo, sha };
+}