@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/semantics/repos.js

@@ -0,0 +1,390 @@
+// A repository itself: create (with its git plane and default branch), read, edit, delete, fork; its
+// topics, forks, languages, contributors, traffic, archive redirects, the comparison of two refs, and
+// its collaborators and assignable users. Repository writes announce the repository, fork and
+// member webhooks.
+import { Buffer } from 'node:buffer';
+import { GITHUB_WORLD_USER, defaultBranchCommits, mergeBaseInPlane, planeAncestors, planeCommitBody, resolvePlaneRef, deleteBareRepo, diffFilesInPlane, hasBareRepo, ensureBareRepo, forkBareRepo, githubNotFound, isValidBranchName, listGitPlaneRefs, paginate, seedUser, setBareRepoHead, githubApps, toGithubAppInstallation, toGithubCollaborator, toGithubRepo, toGithubUser, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTreeToPlane, } from "../github-twin.js";
+import { announce, asView, gh, identityOf, nextSeq, put, send } from "./shared.js";
+import { gitignoreTemplate, licenseTemplate } from "./meta.js";
+import { emitGithubAppEvent } from "../github-events.js";
+const repoOf = (ctx) => {
+    const { repo, state } = gh(ctx);
+    return state().repos.find((x) => x.full_name === repo);
+};
+/** The name a license's copyright line gives an account: an organization's name, a person's profile name, else the login. */
+function holderOf(g, owner) {
+    const org = g.state().orgs.find((o) => o.login === owner);
+    if (org)
+        return String(org.name ?? org.login);
+    return owner === (g.caller ?? 'octocat') ? identityOf(g).name : owner;
+}
+/** Create a repository for `owner` (+ its git plane and default branch). 422 for a name GitHub
+ *  refuses (it would be unservable as a plane path) or one that exists. */
+async function createRepo(ctx, owner) {
+    const { body, occurredAt, root, state } = gh(ctx);
+    if (!body.name)
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'name', code: 'missing_field' }] }, 422);
+    const name = String(body.name);
+    if (!/^[A-Za-z0-9_.-]+$/.test(name) || name === '.' || name === '..' || !/^[A-Za-z0-9_.-]+$/.test(owner))
+        return invalidRepository(ctx, 'name');
+    const full = `${owner}/${name}`;
+    if (state().repos.some((r) => r.full_name === full))
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', code: 'already_exists', field: 'name' }] }, 422);
+    const seq = nextSeq(ctx, 'repo');
+    const fields = { owner, name, description: body.description ?? null, private: body.private === true, default_branch: body.default_branch ?? 'main', has_issues: body.has_issues ?? true, has_projects: body.has_projects ?? true, has_wiki: body.has_wiki ?? true, has_discussions: body.has_discussions ?? false, homepage: body.homepage ?? null, created_at: occurredAt, updated_at: occurredAt };
+    await put(ctx, { operation: 'repository.create', subjectType: 'repository', subjectId: `repo:${seq}`, fields });
+    // the new repository is at once clonable (empty) and pushable by an unmodified git client; it has no
+    // branch until something is committed, unless auto_init or a template makes the initial commit on the default
+    // branch as the signed-in person: a README for auto_init, the .gitignore and LICENSE templates named
+    // (docs.github.com/rest/repos/repos#create-a-repository-for-the-authenticated-user). That a template alone makes
+    // the commit, with no README, is github.com's behaviour as its new-repository page shows it; the REST reference
+    // does not say.
+    const branch = String(fields.default_branch);
+    ensureBareRepo(full, root, branch);
+    const files = [
+        ['README.md', body.auto_init === true ? `# ${name}\n${body.description ? `\n${String(body.description)}\n` : ''}` : undefined],
+        ['.gitignore', typeof body.gitignore_template === 'string' ? gitignoreTemplate(body.gitignore_template) : undefined],
+        // the license with its year and holder filled, as GitHub commits it: the year made, and the owning account's name
+        // (the organization's, or the person's) (docs.github.com/rest/licenses/licenses#get-a-license, its implementation)
+        ['LICENSE', typeof body.license_template === 'string' ? licenseTemplate(body.license_template, { year: String(occurredAt).slice(0, 4), fullname: holderOf(gh(ctx), owner) }) : undefined],
+    ];
+    const initial = files.filter((f) => f[1] !== undefined);
+    if (initial.length) {
+        const entries = await Promise.all(initial.map(async ([path, text]) => ({ path, mode: '100644', type: 'blob', sha: await writeGitBlobToPlane(full, Buffer.from(text).toString('base64'), root) })));
+        const tree = await writeGitTreeToPlane(full, entries, undefined, root);
+        const me = identityOf(gh(ctx));
+        const commit = await writeGitCommitToPlane(full, { message: 'Initial commit', treeSha: tree, parents: [], author: me, committer: me, occurredAt }, root);
+        await updateGitRefInPlane(full, `refs/heads/${branch}`, commit, root, undefined);
+        await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${full}#refs/heads/${branch}`, fields: { repository: full, ref: `refs/heads/${branch}`, object_sha: commit, object_type: 'commit' } });
+        await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${full}#${branch}`, fields: { repository: full, name: branch, commit_sha: commit } });
+        // each file's receipt, as a Contents write keeps one (semantics/contents.ts): the repository's facts read them
+        for (const [i, [path, text]] of initial.entries()) {
+            const content_b64 = Buffer.from(text).toString('base64');
+            await put(ctx, { operation: 'content_file.create', subjectType: 'content_file', subjectId: `content:${full}#${branch}:${path}`, fields: { repository: full, path, branch, sha: entries[i].sha, content_b64, size: text.length, deleted: false } });
+        }
+    }
+    // every new repository has GitHub's default labels (docs.github.com/issues/using-labels-and-milestones-to-track-work/
+    // managing-labels#about-default-labels)
+    for (const [label, color, description] of DEFAULT_LABELS) {
+        await put(ctx, { operation: 'label.create', subjectType: 'label', subjectId: `label:${nextSeq(ctx, 'label')}`, fields: { repository: full, name: label, color, description, default: true } });
+    }
+    const answer = toGithubRepo(state().repos.find((x) => x.full_name === full));
+    await announce(ctx, [{ event: 'repository', action: 'created', repository: full, number: 0 }]);
+    return ctx.reply(answer, 201);
+}
+/** GitHub's default labels, with their colours and descriptions as github.com shows them. */
+const DEFAULT_LABELS = [
+    ['bug', 'd73a4a', "Something isn't working"], ['documentation', '0075ca', 'Improvements or additions to documentation'],
+    ['duplicate', 'cfd3d7', 'This issue or pull request already exists'], ['enhancement', 'a2eeef', 'New feature or request'],
+    ['good first issue', '7057ff', 'Good for newcomers'], ['help wanted', '008672', 'Extra attention is needed'],
+    ['invalid', 'e4e669', "This doesn't seem right"], ['question', 'd876e3', 'Further information is requested'],
+    ['wontfix', 'ffffff', 'This will not be worked on'],
+];
+// The fields a subject names its repository by: its own, a fork's parent, a project card's content, the container
+// of an Actions secret or variable, a notification's subject, a pull request's or a run's head repository.
+const NAMED_BY = ['repository', 'parent_full_name', 'content_repository', 'container', 'subject_url', 'head_repo', 'head_repository'];
+/** `text` with the repository `from` named `to` wherever it stands as a whole name (`octocat/tessellate`, never the
+ *  start of `octocat/tessellate.dev`). */
+const renamed = (text, from, to) => text.replace(new RegExp(`(?<![A-Za-z0-9_.-])${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![A-Za-z0-9_.-])`, 'g'), to);
+/** Everything a repository holds moves with it to its new name (docs.github.com/rest/repos/repos#transfer-a-repository:
+ *  a transfer keeps the issues, pull requests, releases, stars and history). A subject whose id names the repository
+ *  is written anew under the new name and the old id points there (`moved_to`, which the projection follows); any
+ *  other subject has its naming fields rewritten in place. The git plane's refs move to the new name (the objects are
+ *  the World's, shared). The previous owner's teams lose their access. */
+async function moveRepository(ctx, from, to) {
+    const { root } = gh(ctx);
+    for (const row of ctx.tree()) {
+        if (row.deleted === true || typeof row.moved_to === 'string' || row.type === 'repository' || row.type === 'webhook_delivery')
+            continue;
+        const type = String(row.type);
+        const id = String(row.id);
+        if (type === 'team_repo' && row.repository === from) {
+            await put(ctx, { operation: 'repository.transfer', subjectType: type, subjectId: id, fields: { deleted: true } });
+            continue;
+        }
+        const fields = ctx.own(row);
+        delete fields.id;
+        delete fields.type;
+        delete fields.updatedAt;
+        const changed = Object.fromEntries(NAMED_BY.filter((k) => typeof fields[k] === 'string' && renamed(String(fields[k]), from, to) !== fields[k]).map((k) => [k, renamed(String(fields[k]), from, to)]));
+        const newId = renamed(id, from, to);
+        if (newId !== id) {
+            // an issue, pull request or environment keeps the id it was given where it was made
+            const born = ['issue', 'pull_request', 'environment'].includes(type) ? { born_in: fields.born_in ?? from } : {};
+            await put(ctx, { operation: 'repository.transfer', subjectType: type, subjectId: newId, fields: { ...fields, ...changed, ...born } });
+            await put(ctx, { operation: 'repository.transfer', subjectType: type, subjectId: id, fields: { deleted: true, moved_to: newId } });
+        }
+        else if (Object.keys(changed).length) {
+            await put(ctx, { operation: 'repository.transfer', subjectType: type, subjectId: id, fields: changed });
+        }
+    }
+    forkBareRepo(from, to, root);
+    deleteBareRepo(from, root);
+}
+/** A transfer to a person waits for them to accept it from an email GitHub sends them; until then the repository
+ *  stays where it is and the answer names its original owner (docs.github.com/rest/repos/repos#transfer-a-repository). */
+const transferAwaitingAcceptance = (ctx, r) => ctx.reply(toGithubRepo(r), 202);
+/** GitHub's refusal of a repository name or default branch that is not one. */
+function invalidRepository(ctx, field) {
+    return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', field, code: 'invalid' }] }, 422);
+}
+/** GET .../tarball|zipball/:ref → 302 to codeload (the bytes are not modeled). */
+const archive = (fmt) => async (ctx) => {
+    const { repo, seg } = gh(ctx);
+    if (!repoOf(ctx))
+        return send(ctx, githubNotFound());
+    return ctx.reply({ location: `https://codeload.github.com/${repo}/legacy.${fmt}/${decodeURIComponent(seg[4])}` }, 302);
+};
+/** Traffic is not observable offline: an honest zero-history answer for a repository that exists. */
+const traffic = (body) => async (ctx) => (repoOf(ctx) ? ctx.reply(body) : send(ctx, githubNotFound()));
+/** The people who can be assigned in a repository (docs.github.com/rest/issues/assignees). */
+export function assignable(st, repo) {
+    const owner = repo.split('/')[0];
+    const isOrg = st.orgs.some((o) => o.login === owner);
+    const people = new Set([...(isOrg ? st.orgMembers.filter((m) => m.org === owner && m.state === 'active').map((m) => m.login) : [owner]), ...st.collaborators.filter((c) => c.repository === repo).map((c) => c.login)]);
+    return [...people].sort();
+}
+export function reposSemantics() {
+    const reposGet = async (ctx) => {
+        const r = repoOf(ctx);
+        return send(ctx, r ? { status: 200, body: toGithubRepo(r) } : githubNotFound());
+    };
+    const reposDelete = async (ctx) => {
+        const { repo, root } = gh(ctx);
+        const r0 = repoOf(ctx);
+        if (!r0)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'repository.delete', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields: { deleted: true, owner: r0.owner, name: r0.name } });
+        deleteBareRepo(repo, root);
+        await announce(ctx, [{ event: 'repository', action: 'deleted', repository: repo, number: 0 }]);
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const reposListForks = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().repos.filter((x) => x.fork && x.parent_full_name === repo), query).map((r) => asView('minimal-repository', toGithubRepo(r))));
+    };
+    const reposReplaceAllTopics = async (ctx) => {
+        const { body, occurredAt } = gh(ctx);
+        const r0 = repoOf(ctx);
+        if (!r0)
+            return send(ctx, githubNotFound());
+        const names = Array.isArray(body.names) ? body.names.map(String) : [];
+        await put(ctx, { operation: 'repository.set_topics', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields: { owner: r0.owner, name: r0.name, topics: names, updated_at: occurredAt } });
+        return ctx.reply({ names });
+    };
+    const reposListLanguages = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const defaultBranch = repoOf(ctx)?.default_branch ?? 'main';
+        const extLang = { ts: 'TypeScript', tsx: 'TypeScript', js: 'JavaScript', jsx: 'JavaScript', py: 'Python', go: 'Go', rs: 'Rust', java: 'Java', rb: 'Ruby', css: 'CSS', html: 'HTML', md: 'Markdown', json: 'JSON', sh: 'Shell' };
+        const totals = {};
+        for (const c of state().contents.filter((x) => x.repository === repo && (x.branch ?? defaultBranch) === defaultBranch)) {
+            const lang = extLang[c.path.split('.').pop()?.toLowerCase() ?? ''];
+            if (lang)
+                totals[lang] = (totals[lang] ?? 0) + (c.size ?? 0);
+        }
+        return ctx.reply(totals);
+    };
+    const reposListContributors = async (ctx) => {
+        const { repo, query, state, root } = gh(ctx);
+        const counts = new Map();
+        for (const c of await defaultBranchCommits(state(), repo, root))
+            if (c.author)
+                counts.set(c.author, (counts.get(c.author) ?? 0) + 1);
+        const items = [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([login, contributions]) => asView('contributor', { ...toGithubUser(seedUser(login)), contributions }));
+        return ctx.reply(paginate(items, query));
+    };
+    const reposCompareCommits = async (ctx) => {
+        const { repo, seg, root, state } = gh(ctx);
+        const basehead = decodeURIComponent(seg.slice(4).join('/'));
+        const [base, head] = basehead.split('...');
+        const branch = state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+        const baseSha = base ? await resolvePlaneRef(repo, base, branch, root) : null;
+        const headSha = head ? await resolvePlaneRef(repo, head, branch, root) : null;
+        if (!baseSha || !headSha)
+            return send(ctx, githubNotFound());
+        const [ofBase, ofHead] = [await planeAncestors(repo, baseSha, root), await planeAncestors(repo, headSha, root)];
+        const ahead = [...ofHead.keys()].filter((c) => !ofBase.has(c)).reverse();
+        const behind = [...ofBase.keys()].filter((c) => !ofHead.has(c));
+        const mergeBase = (await mergeBaseInPlane(repo, baseSha, headSha, root)) ?? baseSha;
+        const diff = (await diffFilesInPlane(repo, mergeBase, headSha, root, { patch: true })) ?? [];
+        const bodies = [];
+        for (const c of ahead) {
+            const b = await planeCommitBody(repo, c, root);
+            if (b)
+                bodies.push(b);
+        }
+        return ctx.reply({
+            url: `https://api.github.com/repos/${repo}/compare/${basehead}`, html_url: `https://github.com/${repo}/compare/${basehead}`,
+            status: ahead.length && behind.length ? 'diverged' : ahead.length ? 'ahead' : behind.length ? 'behind' : 'identical',
+            ahead_by: ahead.length, behind_by: behind.length, total_commits: ahead.length,
+            base_commit: await planeCommitBody(repo, baseSha, root), merge_base_commit: await planeCommitBody(repo, mergeBase, root),
+            commits: bodies,
+            files: diff.map((f) => ({ sha: f.sha ?? null, filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, changes: f.additions + f.deletions,
+                blob_url: `https://github.com/${repo}/blob/${headSha}/${f.filename}`, raw_url: `https://github.com/${repo}/raw/${headSha}/${f.filename}`, contents_url: `https://api.github.com/repos/${repo}/contents/${f.filename}?ref=${headSha}`, ...(f.patch !== undefined ? { patch: f.patch } : {}) })),
+        });
+    };
+    const reposListCollaborators = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().collaborators.filter((c) => c.repository === repo), query).map(toGithubCollaborator));
+    };
+    const reposCheckCollaborator = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const login = decodeURIComponent(seg[4]);
+        return send(ctx, state().collaborators.some((x) => x.repository === repo && x.login === login) ? { status: 204, body: undefined } : githubNotFound());
+    };
+    const reposGetCollaboratorPermissionLevel = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const login = decodeURIComponent(seg[4]);
+        // `permission` is the legacy base role (maintain maps to write, triage to read), `role_name` the role itself
+        // (docs.github.com/rest/collaborators/collaborators#get-repository-permissions-for-a-user)
+        const c = state().collaborators.find((x) => x.repository === repo && x.login === login);
+        const role = { push: 'write', pull: 'read' }[c?.permission ?? ''] ?? c?.permission ?? 'none';
+        const permission = { maintain: 'write', triage: 'read' }[role] ?? role;
+        return ctx.reply({ permission, role_name: role, user: c ? toGithubCollaborator(c) : null });
+    };
+    const reposRemoveCollaborator = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const login = decodeURIComponent(seg[4]);
+        if (!state().collaborators.find((c) => c.repository === repo && c.login === login))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'collaborator.remove', subjectType: 'collaborator', subjectId: `collab:${repo}#${login}`, fields: { deleted: true, repository: repo, login } });
+        await announce(ctx, [{ event: 'member', action: 'removed', repository: repo, number: 0 }]);
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const issuesListAssignees = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(assignable(state(), repo).map((l) => asView('simple-user', toGithubUser(seedUser(l)))), query));
+    };
+    const issuesCheckUserCanBeAssigned = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        return send(ctx, assignable(state(), repo).includes(decodeURIComponent(seg[4])) ? { status: 204, body: undefined } : githubNotFound());
+    };
+    return {
+        'repos/get': reposGet,
+        'repos/create-for-authenticated-user': async (ctx) => createRepo(ctx, 'octocat'),
+        'repos/create-in-org': async (ctx) => createRepo(ctx, String(gh(ctx).seg[1])),
+        // A default_branch change re-points the plane's HEAD too (a clone checks out the new one); a name
+        // git would refuse is GitHub's 422, checked before anything is written.
+        'repos/update': async (ctx) => {
+            const { repo, body, occurredAt, root, state } = gh(ctx);
+            const r0 = repoOf(ctx);
+            if (!r0)
+                return send(ctx, githubNotFound());
+            const fields = { owner: r0.owner, name: r0.name, updated_at: occurredAt };
+            for (const k of ['description', 'private', 'default_branch', 'homepage', 'has_issues', 'has_projects', 'has_wiki', 'has_discussions', 'archived']) {
+                if (body[k] !== undefined)
+                    fields[k] = body[k];
+            }
+            if (body.name !== undefined)
+                fields.name = String(body.name);
+            // a new name follows creation's rule; the default branch must be one the repository has
+            if (body.name !== undefined && (!/^[A-Za-z0-9_.-]+$/.test(String(body.name)) || ['.', '..'].includes(String(body.name))))
+                return invalidRepository(ctx, 'name');
+            if (body.default_branch !== undefined && (!isValidBranchName(String(body.default_branch)) || (hasBareRepo(repo, root) && !(await listGitPlaneRefs(repo, root)).some((r) => r.ref === `refs/heads/${String(body.default_branch)}`))))
+                return invalidRepository(ctx, 'default_branch');
+            await put(ctx, { operation: 'repository.update', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields });
+            if (body.default_branch !== undefined)
+                setBareRepoHead(repo, String(body.default_branch), root);
+            const answer = toGithubRepo(state().repos.find((x) => x.id === r0.id));
+            await announce(ctx, [{ event: 'repository', action: 'edited', repository: repo, number: 0 }]);
+            return ctx.reply(answer);
+        },
+        // the plane dies with the repository: a later re-create must not inherit its history
+        'repos/delete': reposDelete,
+        // A fork copies the parent's object store and refs (what GitHub does server-side), and the copied
+        // refs get their rows, so REST and a clone agree. 202.
+        'repos/create-fork': async (ctx) => {
+            const { repo, seg, body, occurredAt, root, state, caller } = gh(ctx);
+            const parent = repoOf(ctx);
+            // the fork is the forker's, or the organization's they name
+            const owner = String(body.organization ?? caller ?? GITHUB_WORLD_USER);
+            const name = String(body.name ?? seg[2]);
+            if (!/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(name) || ['.', '..'].includes(owner) || ['.', '..'].includes(name))
+                return invalidRepository(ctx, 'name');
+            const full = `${owner}/${name}`;
+            const seq = nextSeq(ctx, 'repo');
+            const fields = { owner, name, fork: true, parent_full_name: repo, description: parent?.description ?? null, default_branch: parent?.default_branch ?? 'main', created_at: occurredAt, updated_at: occurredAt };
+            await put(ctx, { operation: 'repository.fork', subjectType: 'repository', subjectId: `repo:${seq}`, fields });
+            forkBareRepo(repo, full, root, String(fields.default_branch));
+            for (const planeRef of await listGitPlaneRefs(full, root)) {
+                await put(ctx, { operation: 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${full}#${planeRef.ref}`, fields: { repository: full, ref: planeRef.ref, object_sha: planeRef.object_sha, object_type: planeRef.object_type === 'tag' ? 'tag' : 'commit' } });
+                if (planeRef.ref.startsWith('refs/heads/')) {
+                    const bn = planeRef.ref.slice('refs/heads/'.length);
+                    await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${full}#${bn}`, fields: { repository: full, name: bn, commit_sha: planeRef.object_sha } });
+                }
+            }
+            const answer = toGithubRepo(state().repos.find((x) => x.full_name === full));
+            await announce(ctx, [{ event: 'fork', action: 'created', repository: repo, number: 0 }]);
+            return ctx.reply(answer, 202);
+        },
+        // Transfer to an organization the caller may create repositories in: at once, under the organization, with
+        // everything the repository holds (docs.github.com/rest/repos/repos#transfer-a-repository). Only an admin of the
+        // repository transfers it: its owner, or an owner of the organization that owns it.
+        'repos/transfer': async (ctx) => {
+            const { repo, body, caller, occurredAt, state } = gh(ctx);
+            const r0 = repoOf(ctx);
+            if (!r0)
+                return send(ctx, githubNotFound());
+            const me = caller ?? GITHUB_WORLD_USER;
+            const st = state();
+            const admin = r0.owner === me || st.orgMembers.some((m) => m.org === r0.owner && m.login === me && m.role === 'admin' && m.state === 'active');
+            const newOwner = String(body.new_owner ?? '');
+            const name = String(body.new_name ?? r0.name);
+            if (!admin)
+                return ctx.reply({ message: 'You must be an admin to transfer a repository.', documentation_url: 'https://docs.github.com/rest/repos/repos#transfer-a-repository' }, 403);
+            if (!st.orgs.some((o) => o.login === newOwner))
+                return transferAwaitingAcceptance(ctx, r0);
+            if (!st.orgMembers.some((m) => m.org === newOwner && m.login === me && m.state === 'active') || st.repos.some((x) => x.full_name === `${newOwner}/${name}`) || !/^[A-Za-z0-9_.-]+$/.test(name))
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'new_owner', code: 'invalid' }] }, 422);
+            const to = `${newOwner}/${name}`;
+            await moveRepository(ctx, repo, to);
+            await put(ctx, { operation: 'repository.transfer', subjectType: 'repository', subjectId: `repo:${r0.id}`, fields: { owner: newOwner, name, updated_at: occurredAt } });
+            for (const fork of state().repos.filter((x) => x.parent_full_name === repo))
+                await put(ctx, { operation: 'repository.transfer', subjectType: 'repository', subjectId: `repo:${fork.id}`, fields: { parent_full_name: to } });
+            await announce(ctx, [{ event: 'repository', action: 'transferred', repository: to, number: 0 }]);
+            // the repository leaves the previous owner's app installations that had it selected, and each app hears so
+            // (docs.github.com/webhooks/webhook-events-and-payloads#installation_repositories)
+            for (const i of state().appInstallations.filter((x) => x.account_login === r0.owner && x.repository_selection === 'selected' && (x.repositories ?? []).includes(repo))) {
+                await put(ctx, { operation: 'app_installation.remove_repository', subjectType: 'app_installation', subjectId: `installation:${i.id}`, fields: { repositories: (i.repositories ?? []).filter((n) => n !== repo), updated_at: occurredAt } });
+                const app = githubApps(ctx.root).find((a) => a.slug === i.app_slug);
+                const now = state().appInstallations.find((x) => x.id === i.id);
+                if (app) {
+                    try {
+                        await emitGithubAppEvent(app, 'installation_repositories', { action: 'removed', installation: toGithubAppInstallation(now), repository_selection: 'selected', repositories_added: [], repositories_removed: [{ id: r0.id, name: r0.name, full_name: repo, private: r0.private ?? false }], sender: { login: caller ?? GITHUB_WORLD_USER, type: 'User' } }, { occurredAt, ...(ctx.root !== undefined ? { root: ctx.root } : {}) });
+                    }
+                    catch { /* a delivery failure never fails the transfer */ }
+                }
+            }
+            return ctx.reply(toGithubRepo(state().repos.find((x) => x.id === r0.id)), 202);
+        },
+        // repos with fork:true whose parent is this one
+        'repos/list-forks': reposListForks,
+        'repos/get-all-topics': async (ctx) => ctx.reply({ names: repoOf(ctx)?.topics ?? [] }),
+        'repos/replace-all-topics': reposReplaceAllTopics,
+        // bytes per language, from the default branch's files (their extensions and sizes); {} when none
+        'repos/list-languages': reposListLanguages,
+        // commit counts per author on the default branch's history
+        'repos/list-contributors': reposListContributors,
+        // Two refs compared on the repository's history (three-dot: from their merge base): the commits the head has that
+        // the base lacks (oldest first), how far each is ahead and behind, and the files changed since the merge base
+        // (docs.github.com/rest/commits/commits#compare-two-commits). A pair that does not resolve is not found.
+        'repos/compare-commits': reposCompareCommits,
+        'repos/get-views': traffic({ count: 0, uniques: 0, views: [] }),
+        'repos/get-clones': traffic({ count: 0, uniques: 0, clones: [] }),
+        'repos/get-top-referrers': traffic([]),
+        'repos/get-top-paths': traffic([]),
+        'repos/download-tarball-archive': archive('tar.gz'),
+        'repos/download-zipball-archive': archive('zip'),
+        'repos/list-collaborators': reposListCollaborators,
+        // 204 when a collaborator, else 404
+        'repos/check-collaborator': reposCheckCollaborator,
+        'repos/get-collaborator-permission-level': reposGetCollaboratorPermissionLevel,
+        // GitHub answers a new collaborator with an invitation (201)
+        // adding a collaborator is semantics/repo-invitations.ts: it invites them
+        'repos/remove-collaborator': reposRemoveCollaborator,
+        // assignable users are the repository's collaborators
+        // who can be assigned: the repository's owner when a person, its collaborators, and its organization's members
+        'issues/list-assignees': issuesListAssignees,
+        'issues/check-user-can-be-assigned': issuesCheckUserCanBeAssigned,
+    };
+}

package/dist/src/semantics/rulesets.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare function rulesetsSemantics(): Record<string, Semantics>;

package/dist/src/semantics/rulesets.js

@@ -0,0 +1,111 @@
+import { githubNotFound, observedId, paginate, recordRulesetVersion, toGithubRuleset, twinUserId } from "../github-twin.js";
+import { gh, nextSeq, put, send } from "./shared.js";
+const suiteOf = (repo, x, full) => ({ id: x.id, actor_id: twinUserId(x.actor_login), actor_name: x.actor_login, before_sha: x.before_sha, after_sha: x.after_sha, ref: x.ref,
+    repository_id: observedId(`repository:${repo}`), repository_name: repo.split('/')[1], pushed_at: x.pushed_at, result: x.result, evaluation_result: x.result === 'fail' ? 'fail' : 'pass',
+    ...(full ? { rule_evaluations: x.rules.map((r) => ({ rule_source: { type: 'ruleset', id: r.ruleset_id, name: r.ruleset_name }, enforcement: r.enforcement, result: r.result, rule_type: r.rule_type, details: r.details })) } : {}) });
+// GitHub names each version's actor by account id and type
+const versionOf = (v, full) => ({ version_id: v.version_id, actor: { id: v.actor_login ? twinUserId(v.actor_login) : null, type: 'User' }, updated_at: v.updated_at, ...(full ? { state: v.state } : {}) });
+const rulesetOf = (ctx) => {
+    const { repo, seg, state } = gh(ctx);
+    return state().rulesets.find((x) => x.repository === repo && x.id === Number(decodeURIComponent(seg[4])));
+};
+/** Record the version a ruleset write made, through this request's context. */
+const version = (ctx, id) => {
+    const { repo, caller, occurredAt, root } = gh(ctx);
+    return recordRulesetVersion(repo, id, caller ?? '', occurredAt, root, (w) => put(ctx, w));
+};
+export function rulesetsSemantics() {
+    const reposGetRepoRulesets = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().rulesets.filter((r) => r.repository === repo), query).map(toGithubRuleset));
+    };
+    const reposGetRepoRuleset = async (ctx) => {
+        const r = rulesetOf(ctx);
+        return send(ctx, r ? { status: 200, body: toGithubRuleset(r) } : githubNotFound());
+    };
+    const reposGetRepoRulesetHistory = async (ctx) => {
+        const r = rulesetOf(ctx);
+        if (!r)
+            return send(ctx, githubNotFound());
+        return ctx.reply(paginate([...(r.versions ?? [])].reverse(), gh(ctx).query).map((v) => versionOf(v, false)));
+    };
+    const reposGetRepoRulesetVersion = async (ctx) => {
+        const r = rulesetOf(ctx);
+        if (!r)
+            return send(ctx, githubNotFound());
+        const v = [...(r.versions ?? [])].reverse().find((x) => x.version_id === Number(decodeURIComponent(gh(ctx).seg[6])));
+        return send(ctx, v ? { status: 200, body: versionOf(v, true) } : githubNotFound());
+    };
+    const reposCreateRepoRuleset = async (ctx) => {
+        const { repo, body, occurredAt, state } = gh(ctx);
+        if (!body.name)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Ruleset', field: 'name', code: 'missing_field' }] }, 422);
+        const id = nextSeq(ctx, 'ruleset');
+        const fields = { repository: repo, name: String(body.name), target: String(body.target ?? 'branch'), enforcement: String(body.enforcement ?? 'active'), rules: Array.isArray(body.rules) ? body.rules : [], conditions: body.conditions, bypass_actors: Array.isArray(body.bypass_actors) ? body.bypass_actors : [], created_at: occurredAt, updated_at: occurredAt };
+        await put(ctx, { operation: 'ruleset.create', subjectType: 'ruleset', subjectId: `ruleset:${id}`, fields });
+        await version(ctx, id);
+        return ctx.reply(toGithubRuleset(state().rulesets.find((x) => x.id === id)), 201);
+    };
+    const reposUpdateRepoRuleset = async (ctx) => {
+        const { repo, body, occurredAt, state } = gh(ctx);
+        const existing = rulesetOf(ctx);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const id = existing.id;
+        const fields = { repository: repo, updated_at: occurredAt };
+        if (body.name !== undefined)
+            fields.name = String(body.name);
+        if (body.target !== undefined)
+            fields.target = String(body.target);
+        if (body.enforcement !== undefined)
+            fields.enforcement = String(body.enforcement);
+        if (body.rules !== undefined)
+            fields.rules = Array.isArray(body.rules) ? body.rules : [];
+        if (body.conditions !== undefined)
+            fields.conditions = body.conditions;
+        if (body.bypass_actors !== undefined)
+            fields.bypass_actors = Array.isArray(body.bypass_actors) ? body.bypass_actors : [];
+        await put(ctx, { operation: 'ruleset.update', subjectType: 'ruleset', subjectId: `ruleset:${id}`, fields });
+        await version(ctx, id);
+        return ctx.reply(toGithubRuleset(state().rulesets.find((x) => x.id === id)));
+    };
+    const reposDeleteRepoRuleset = async (ctx) => {
+        const { repo } = gh(ctx);
+        const existing = rulesetOf(ctx);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'ruleset.delete', subjectType: 'ruleset', subjectId: `ruleset:${existing.id}`, fields: { deleted: true, repository: repo } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const reposGetRepoRuleSuites = async (ctx) => {
+        const { repo, query, occurredAt, state } = gh(ctx);
+        const q = new URLSearchParams(query?.startsWith('?') ? query.slice(1) : (query ?? ''));
+        const span = { hour: 36e5, day: 864e5, week: 6048e5, month: 2592e6 }[q.get('time_period') ?? 'day'];
+        if (!span)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'RuleSuite', field: 'time_period', code: 'invalid' }] }, 422);
+        const since = Date.parse(occurredAt) - span;
+        const ref = q.get('ref'), actor = q.get('actor_name'), result = q.get('rule_suite_result');
+        const hits = state().ruleSuites.filter((x) => x.repository === repo && Date.parse(x.pushed_at) >= since && (!ref || x.ref === ref || x.ref === `refs/heads/${ref}`) && (!actor || x.actor_login === actor) && (!result || result === 'all' || x.result === result)).reverse();
+        return ctx.reply(paginate(hits, query).map((x) => suiteOf(repo, x, false)));
+    };
+    const reposGetRepoRuleSuite = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const x = state().ruleSuites.find((y) => y.repository === repo && y.id === Number(decodeURIComponent(seg[5])));
+        return send(ctx, x ? { status: 200, body: suiteOf(repo, x, true) } : githubNotFound());
+    };
+    return {
+        'repos/get-repo-rulesets': reposGetRepoRulesets,
+        'repos/get-repo-ruleset': reposGetRepoRuleset,
+        // newest first
+        'repos/get-repo-ruleset-history': reposGetRepoRulesetHistory,
+        'repos/get-repo-ruleset-version': reposGetRepoRulesetVersion,
+        'repos/create-repo-ruleset': reposCreateRepoRuleset,
+        // GitHub's PUT (the hand-written route keeps the PATCH it also answered)
+        'repos/update-repo-ruleset': reposUpdateRepoRuleset,
+        'repos/delete-repo-ruleset': reposDeleteRepoRuleset,
+        // Rule insights, newest first, filtered by ref, actor_name, rule_suite_result and a time_period
+        // (hour, day, week, month) reaching back from now; GitHub keeps no longer window than a month.
+        'repos/get-repo-rule-suites': reposGetRepoRuleSuites,
+        'repos/get-repo-rule-suite': reposGetRepoRuleSuite,
+    };
+}

package/dist/src/semantics/search.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare function searchSemantics(): Record<string, Semantics>;

package/dist/src/semantics/search.js

@@ -0,0 +1,84 @@
+import { defaultBranchCommits, paginate, planeCommitBody, pullRequestAsIssue, seedUser, toGithubIssue, toGithubRepo, toGithubUser } from "../github-twin.js";
+import { asView, gh } from "./shared.js";
+function read(ctx) {
+    const { query, state } = gh(ctx);
+    const q = (new URLSearchParams((query ?? '').replace(/^\?/, '')).get('q') ?? '').toLowerCase();
+    const terms = q.replace(/\b\w+:\S+/g, '').trim().split(/\s+/).filter(Boolean); // strip qualifiers like repo:/is:
+    const matchText = (...vals) => terms.length === 0 || terms.every((t) => vals.some((v) => (v ?? '').toLowerCase().includes(t)));
+    return { q, repoQual: /repo:(\S+)/.exec(q)?.[1], matchText, query, state: state() };
+}
+const found = (ctx, total, items) => ctx.reply({ total_count: total, incomplete_results: false, items });
+export function searchSemantics() {
+    const searchIssuesAndPullRequests = async (ctx) => {
+        const { q, repoQual, matchText, query, state } = read(ctx);
+        const wantPr = /\bis:pr\b/.test(q);
+        const wantIssue = /\bis:issue\b/.test(q);
+        const wantOpen = /\bis:open\b/.test(q);
+        const wantClosed = /\bis:closed\b/.test(q);
+        const issueItems = state.issues.map((i) => ({ obj: toGithubIssue(i, state.milestones, undefined, state.comments), repo: i.repository, isPr: false, st: i.state ?? 'open', t: i.title, b: i.body }));
+        // Same marker, same reason as the pulls list and the activity feed: a counter shell is
+        // not a pull request, and search must not answer for one (it would also DOUBLE the
+        // issue it shadows — once as itself, once as a phantom PR at the same number).
+        // a pull request is found as the issue it also is, carrying its pull_request key
+        const prItems = state.prs.filter((p) => p.is_pull_request).map((p) => ({ obj: toGithubIssue(pullRequestAsIssue(p), state.milestones, p, state.comments), repo: p.repository, isPr: true, st: p.state ?? 'open', t: p.title, b: p.body }));
+        let pool = [...issueItems, ...prItems];
+        if (wantPr && !wantIssue)
+            pool = pool.filter((x) => x.isPr);
+        if (wantIssue && !wantPr)
+            pool = pool.filter((x) => !x.isPr);
+        if (wantOpen && !wantClosed)
+            pool = pool.filter((x) => x.st === 'open');
+        if (wantClosed && !wantOpen)
+            pool = pool.filter((x) => x.st === 'closed');
+        if (repoQual)
+            pool = pool.filter((x) => x.repo === repoQual);
+        pool = pool.filter((x) => matchText(x.t, x.b));
+        return found(ctx, pool.length, paginate(pool.map((x) => asView('issue-search-result-item', { ...x.obj, score: 1 })), query));
+    };
+    const searchRepos = async (ctx) => {
+        const { matchText, query, state } = read(ctx);
+        const pool = state.repos.filter((r) => matchText(r.name, r.full_name, r.description ?? undefined));
+        return found(ctx, pool.length, paginate(pool.map((r) => asView('repo-search-result-item', { ...toGithubRepo(r), score: 1 })), query));
+    };
+    const searchUsers = async (ctx) => {
+        const { matchText, query, state } = read(ctx);
+        const logins = new Set();
+        for (const c of state.collaborators)
+            logins.add(c.login);
+        for (const r of state.repos)
+            logins.add(r.owner);
+        const pool = [...logins].filter((l) => matchText(l)).map(seedUser);
+        return found(ctx, pool.length, paginate(pool.map((u) => asView('user-search-result-item', { ...toGithubUser(u), score: 1 })), query));
+    };
+    const searchCode = async (ctx) => {
+        const { repoQual, matchText, query, state } = read(ctx);
+        // GitHub searches the default branch's code (docs.github.com/search-github/searching-on-github/searching-code)
+        const onDefault = (c) => (c.branch ?? 'main') === (state.repos.find((r) => r.full_name === c.repository)?.default_branch ?? 'main');
+        const pool = state.contents.filter((c) => (!repoQual || c.repository === repoQual) && onDefault(c) && matchText(c.path));
+        const items = paginate(pool, query).map((c) => ({ name: c.path.split('/').pop(), path: c.path, sha: c.sha, url: `https://api.github.com/repos/${c.repository}/contents/${c.path}?ref=${c.sha}`, git_url: `https://api.github.com/repos/${c.repository}/git/blobs/${c.sha}`, repository: { full_name: c.repository }, html_url: `https://github.com/${c.repository}/blob/${c.branch ?? 'main'}/${c.path}`, score: 1 }));
+        return found(ctx, pool.length, items);
+    };
+    const searchCommits = async (ctx) => {
+        const { repoQual, matchText, query, state } = read(ctx);
+        const all = [];
+        for (const r of state.repos.filter((x) => !repoQual || x.full_name === repoQual)) {
+            for (const c of await defaultBranchCommits(state, r.full_name, gh(ctx).root)) {
+                const body = matchText(c.message) ? await planeCommitBody(r.full_name, c.sha, gh(ctx).root) : null;
+                if (body)
+                    all.push(asView('commit-search-result-item', { ...body, repository: asView('minimal-repository', toGithubRepo(r)), score: 1 }));
+            }
+        }
+        return found(ctx, all.length, paginate(all, query));
+    };
+    return {
+        // Issues + PRs (real GitHub's issue search spans both). Honor is:issue / is:pr / is:open|closed.
+        'search/issues-and-pull-requests': searchIssuesAndPullRequests,
+        'search/repos': searchRepos,
+        // The set of known logins = collaborators + repo owners. Faithful local search domain.
+        'search/users': searchUsers,
+        'search/code': searchCode,
+        // Commits on each repository's default branch whose message matches (GitHub searches default branches only,
+        // docs.github.com/search-github/searching-on-github/searching-commits)
+        'search/commits': searchCommits,
+    };
+}

package/dist/src/semantics/security.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare function securitySemantics(): Record<string, Semantics>;