@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/releases.js

@@ -0,0 +1,231 @@
+// A repository's releases, their assets (metadata only: the bytes are out of scope) and its tags. Publishing a
+// release whose tag does not exist yet creates the tag on its target (docs.github.com/rest/releases/releases#create-a-
+// release); a draft makes none until it is published, and deleting a release keeps its tag. Creating, editing,
+// publishing and deleting a release, and uploading an asset, announce the release webhook.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Buffer } from 'node:buffer';
+import { GITHUB_WORLD_USER, githubNotFound, hasBareRepo, listGitPlaneRefs, paginate, planeAncestors, readGitTagFromPlane, resolvePlaneRef, toGithubRelease, toGithubReleaseAsset, toGithubTag, updateGitRefInPlane } from "../github-twin.js";
+import { announce, gh, nextSeq, put, send } from "./shared.js";
+const releaseOf = (ctx) => {
+    const { repo, seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[4]));
+    const st = state();
+    return { id, st, rel: st.releases.find((r) => r.repository === repo && r.id === id) };
+};
+/** A published release's tag, made on its target (a branch or a commit) when the repository has history and no such tag. */
+async function tagOnPublish(ctx, tag, target) {
+    const { repo, root, state } = gh(ctx);
+    if (!hasBareRepo(repo, root))
+        return;
+    const ref = `refs/tags/${tag}`;
+    if (!(await listGitPlaneRefs(repo, root)).some((r) => r.ref === ref))
+        await tagTarget(ctx, ref, target);
+}
+/** A release's tag, made on its target, as publishing the release makes it when the tag does not exist yet. */
+async function tagTarget(ctx, ref, target) {
+    const { repo, root, state } = gh(ctx);
+    const sha = await resolvePlaneRef(repo, target, state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main', root);
+    if (!sha || !(await updateGitRefInPlane(repo, ref, sha, root, null)))
+        return;
+    await put(ctx, { operation: 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${repo}#${ref}`, fields: { repository: repo, ref, object_sha: sha, object_type: 'commit' } });
+}
+/** GitHub's generated release notes for `tag` (docs.github.com/repositories/releasing-projects-on-github/automatically-
+ *  generated-release-notes, docs.github.com/rest/releases/releases#generate-release-notes-content-for-a-release): the
+ *  pull requests merged since the previous release, each with its author, the contributors whose first merged pull
+ *  request is among them, and the full changelog's link. The previous release is the latest published one other than
+ *  this tag's, unless `previous` names a tag. Where the documentation stops and the twin decides: a repository's
+ *  release.yml categories are not read. */
+export async function generatedNotes(ctx, tag, target, previous) {
+    const { repo, root, state } = gh(ctx);
+    const st = state();
+    const defaultBranch = st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main';
+    const head = (await resolvePlaneRef(repo, tag, defaultBranch, root)) ?? (await resolvePlaneRef(repo, target ?? defaultBranch, defaultBranch, root));
+    const prevTag = previous ?? st.releases.filter((r) => r.repository === repo && !r.draft && r.tag_name !== tag && r.published_at).sort((a, b) => String(b.published_at).localeCompare(String(a.published_at)) || b.id - a.id)[0]?.tag_name;
+    const prevSha = prevTag ? await resolvePlaneRef(repo, prevTag, defaultBranch, root) : null;
+    const reach = head ? await planeAncestors(repo, head, root) : new Map();
+    const before = prevSha ? await planeAncestors(repo, prevSha, root) : new Map();
+    const merged = st.prs.filter((p) => p.repository === repo && p.is_pull_request && p.merged && p.merge_commit_sha).sort((a, b) => a.number - b.number);
+    const inRange = merged.filter((p) => reach.has(p.merge_commit_sha) && !before.has(p.merge_commit_sha));
+    const url = `https://github.com/${repo}`;
+    const lines = [];
+    if (inRange.length)
+        lines.push("## What's Changed", ...inRange.map((p) => `* ${p.title ?? ''} by @${p.user_login ?? 'ghost'} in ${url}/pull/${p.number}`), '');
+    const firsts = inRange.filter((p) => p.user_login && merged.find((m) => m.user_login === p.user_login) === p);
+    if (firsts.length)
+        lines.push('## New Contributors', ...firsts.map((p) => `* @${p.user_login} made their first contribution in ${url}/pull/${p.number}`), '');
+    lines.push(`**Full Changelog**: ${prevTag ? `${url}/compare/${prevTag}...${tag}` : `${url}/commits/${tag}`}`);
+    return { name: tag, body: lines.join('\n') };
+}
+/** A release asset's upload as it arrived: its raw bytes and their media type, which the server hands the upload
+ *  operation (github-server.ts) since GitHub reads this body as the file, not as JSON. */
+export const assetUploads = new AsyncLocalStorage();
+export function releasesSemantics() {
+    const reposListReleases = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const st = state();
+        return ctx.reply(paginate(st.releases.filter((r) => r.repository === repo), query).map((r) => toGithubRelease(r, st.releaseAssets)));
+    };
+    const reposGetRelease = async (ctx) => {
+        const { st, rel } = releaseOf(ctx);
+        return send(ctx, rel ? { status: 200, body: toGithubRelease(rel, st.releaseAssets) } : githubNotFound());
+    };
+    const reposGetLatestRelease = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const st = state();
+        const latest = st.releases.filter((r) => r.repository === repo && !r.draft && !r.prerelease).sort((a, b) => b.id - a.id)[0];
+        return send(ctx, latest ? { status: 200, body: toGithubRelease(latest, st.releaseAssets) } : githubNotFound());
+    };
+    const reposGetReleaseByTag = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const st = state();
+        const tag = decodeURIComponent(seg.slice(5).join('/'));
+        const rel = st.releases.find((r) => r.repository === repo && r.tag_name === tag);
+        return send(ctx, rel ? { status: 200, body: toGithubRelease(rel, st.releaseAssets) } : githubNotFound());
+    };
+    const reposGetReleaseAsset = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const id = Number(decodeURIComponent(seg[5]));
+        const asset = state().releaseAssets.find((a) => a.repository === repo && a.id === id);
+        return send(ctx, asset ? { status: 200, body: toGithubReleaseAsset(asset) } : githubNotFound());
+    };
+    const reposListReleaseAssets = async (ctx) => {
+        const { id, st, rel } = releaseOf(ctx);
+        if (!rel)
+            return send(ctx, githubNotFound());
+        const { repo, query } = gh(ctx);
+        return ctx.reply(paginate(st.releaseAssets.filter((a) => a.repository === repo && a.release_id === id), query).map(toGithubReleaseAsset));
+    };
+    const reposListTags = async (ctx) => {
+        const { repo, query, root, state } = gh(ctx);
+        if (!hasBareRepo(repo, root))
+            return ctx.reply(paginate(state().tags.filter((t) => t.repository === repo), query).map(toGithubTag));
+        const tags = [];
+        for (const r of await listGitPlaneRefs(repo, root)) {
+            if (!r.ref.startsWith('refs/tags/'))
+                continue;
+            const commit = r.object_type === 'tag' ? ((await readGitTagFromPlane(repo, r.object_sha, root))?.object_sha ?? r.object_sha) : r.object_sha;
+            tags.push({ repository: repo, name: r.ref.slice('refs/tags/'.length), commit_sha: commit });
+        }
+        tags.sort((a, b) => b.name.localeCompare(a.name, undefined, { numeric: true }));
+        return ctx.reply(paginate(tags, query).map(toGithubTag));
+    };
+    const reposGenerateReleaseNotes = async (ctx) => {
+        const { repo, body, root, state } = gh(ctx);
+        if (!body.tag_name)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Release', field: 'tag_name', code: 'missing_field' }] }, 422);
+        if (body.previous_tag_name !== undefined && !(await resolvePlaneRef(repo, String(body.previous_tag_name), state().repos.find((r) => r.full_name === repo)?.default_branch ?? 'main', root)))
+            return send(ctx, githubNotFound());
+        return ctx.reply(await generatedNotes(ctx, String(body.tag_name), body.target_commitish, body.previous_tag_name === undefined ? undefined : String(body.previous_tag_name)));
+    };
+    const reposUpdateRelease = async (ctx) => {
+        const { id, rel: existing } = releaseOf(ctx);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const { repo, body, occurredAt, state } = gh(ctx);
+        const fields = { repository: repo };
+        if (body.tag_name !== undefined)
+            fields.tag_name = String(body.tag_name);
+        if (body.target_commitish !== undefined)
+            fields.target_commitish = String(body.target_commitish);
+        if (body.name !== undefined)
+            fields.name = body.name;
+        if (body.body !== undefined)
+            fields.body = body.body;
+        if (body.prerelease !== undefined)
+            fields.prerelease = body.prerelease === true;
+        if (body.draft !== undefined) {
+            fields.draft = body.draft === true;
+            if (body.draft === false && !existing.published_at)
+                fields.published_at = occurredAt;
+        }
+        await put(ctx, { operation: 'release.update', subjectType: 'release', subjectId: `release:${id}`, fields });
+        const now = state().releases.find((r) => r.id === id);
+        if (!now.draft)
+            await tagOnPublish(ctx, now.tag_name, now.target_commitish ?? 'main');
+        const st = state();
+        const answer = toGithubRelease(st.releases.find((r) => r.id === id), st.releaseAssets);
+        await announce(ctx, [{ event: 'release', action: 'edited', repository: repo, number: id }]);
+        return ctx.reply(answer);
+    };
+    const reposDeleteRelease = async (ctx) => {
+        const { id, rel: existing } = releaseOf(ctx);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const { repo } = gh(ctx);
+        await put(ctx, { operation: 'release.delete', subjectType: 'release', subjectId: `release:${id}`, fields: { deleted: true, repository: repo, tag_name: existing.tag_name } });
+        await announce(ctx, [{ event: 'release', action: 'deleted', repository: repo, number: id }]);
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        // newest first
+        'repos/list-releases': reposListReleases,
+        'repos/get-release': reposGetRelease,
+        // the most recent PUBLISHED release: GitHub excludes drafts and prereleases from "latest"
+        'repos/get-latest-release': reposGetLatestRelease,
+        'repos/get-release-by-tag': reposGetReleaseByTag,
+        'repos/get-release-asset': reposGetReleaseAsset,
+        'repos/list-release-assets': reposListReleaseAssets,
+        // tags, as published releases create them
+        // a repository's tags are its refs/tags, an annotated one peeled to the commit it tags; one known only through the
+        // API keeps the tags its releases made
+        'repos/list-tags': reposListTags,
+        // 422 without a tag_name; draft and prerelease default false; a published release gets its
+        // published_at (and its tag)
+        'repos/create-release': async (ctx) => {
+            const { repo, body, occurredAt, state, caller } = gh(ctx);
+            if (!body.tag_name)
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Release', field: 'tag_name', code: 'missing_field' }] }, 422);
+            const seq = nextSeq(ctx, 'release');
+            const draft = body.draft === true;
+            // generate_release_notes: the generated notes follow the body given, and name it when no name is
+            const notes = body.generate_release_notes === true ? await generatedNotes(ctx, String(body.tag_name), body.target_commitish, undefined) : undefined;
+            const fields = {
+                repository: repo, tag_name: String(body.tag_name), target_commitish: body.target_commitish ?? 'main',
+                name: body.name ?? notes?.name, body: notes ? [body.body, notes.body].filter((x) => typeof x === 'string' && x.length).join('\n\n') : body.body, draft, prerelease: body.prerelease === true,
+                created_at: occurredAt, published_at: draft ? undefined : occurredAt, author_login: caller ?? GITHUB_WORLD_USER,
+            };
+            await put(ctx, { operation: 'release.create', subjectType: 'release', subjectId: `release:${seq}`, fields });
+            if (!draft)
+                await tagOnPublish(ctx, String(body.tag_name), String(fields.target_commitish));
+            const st = state();
+            const answer = toGithubRelease(st.releases.find((r) => r.id === seq), st.releaseAssets);
+            await announce(ctx, [{ event: 'release', action: draft ? 'created' : 'published', repository: repo, number: seq }]);
+            return ctx.reply(answer, 201);
+        },
+        // the notes a release of tag_name would be generated with, and its name (200); a previous_tag_name that is no tag is 404
+        'repos/generate-release-notes': reposGenerateReleaseNotes,
+        // an edit, including publishing a draft (the first publication stamps published_at)
+        'repos/update-release': reposUpdateRelease,
+        'repos/delete-release': reposDeleteRelease,
+        // An asset's METADATA (name, label, content type, size); its bytes are out of scope. The name comes
+        // from the JSON body or, as on GitHub's upload endpoint, the `?name=` query.
+        // The asset is the request body, its raw bytes, with its media type in Content-Type; its name and label are query
+        // parameters (docs.github.com/rest/releases/assets#upload-a-release-asset). A second asset of one name is 422, as
+        // GitHub documents. Where the documentation stops and the twin decides: an upload with no Content-Type or no bytes
+        // is refused as a missing field, and the bytes are kept as the asset's content.
+        'repos/upload-release-asset': async (ctx) => {
+            const { id: releaseId, rel } = releaseOf(ctx);
+            if (!rel)
+                return send(ctx, githubNotFound());
+            const { repo, query, occurredAt, state, caller } = gh(ctx);
+            const q = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+            const name = q.get('name');
+            const upload = assetUploads.getStore() ?? { bytes: new Uint8Array(), type: null };
+            const absent = [...(!name ? ['name'] : []), ...(!upload.type ? ['content_type'] : []), ...(!upload.bytes.length ? ['size'] : [])];
+            if (absent.length)
+                return ctx.reply({ message: 'Validation Failed', errors: absent.map((field) => ({ resource: 'ReleaseAsset', field, code: 'missing_field' })), documentation_url: 'https://docs.github.com/rest/releases/assets#upload-a-release-asset' }, 422);
+            if (state().releaseAssets.some((a) => a.repository === repo && a.release_id === releaseId && a.name === name))
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'ReleaseAsset', field: 'name', code: 'already_exists' }], documentation_url: 'https://docs.github.com/rest/releases/assets#upload-a-release-asset' }, 422);
+            const seq = nextSeq(ctx, 'asset');
+            const fields = {
+                repository: repo, release_id: releaseId, name: String(name), label: q.get('label') ?? undefined,
+                content_type: upload.type, size: upload.bytes.length, content_b64: Buffer.from(upload.bytes).toString('base64'),
+                state: 'uploaded', download_count: 0, created_at: occurredAt, updated_at: occurredAt, uploader_login: caller ?? GITHUB_WORLD_USER,
+            };
+            await put(ctx, { operation: 'release_asset.create', subjectType: 'release_asset', subjectId: `asset:${seq}`, fields });
+            const answer = toGithubReleaseAsset(state().releaseAssets.find((a) => a.id === seq));
+            await announce(ctx, [{ event: 'release', action: 'released', repository: repo, number: releaseId }]);
+            return ctx.reply(answer, 201);
+        },
+    };
+}

package/dist/src/semantics/repo-invitations.d.ts

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

package/dist/src/semantics/repo-invitations.js

@@ -0,0 +1,98 @@
+import { GITHUB_WORLD_USER, githubNotFound, nodeId, paginate, toGithubRepo, toSimpleUser } from "../github-twin.js";
+import { me } from "./activity.js";
+import { announce, gh, nextSeq, put, send } from "./shared.js";
+const WEEK = 7 * 86_400_000;
+/** add-collaborator's permission names, as an invitation reports them. */
+const INVITED_AS = { pull: 'read', triage: 'triage', push: 'write', maintain: 'maintain', admin: 'admin' };
+const GRANTED_AS = { read: 'pull', triage: 'triage', write: 'push', maintain: 'maintain', admin: 'admin' };
+/** The invitations still standing (not accepted, declined or withdrawn). */
+function invitations(ctx) {
+    return ctx.tree()
+        .filter((r) => r.type === 'repo_invitation' && r.deleted !== true)
+        .map((r) => ({ id: Number(r.number), repository: String(r.repository), invitee: String(r.invitee), inviter: String(r.inviter), permission: String(r.permission), created_at: String(r.created_at) }));
+}
+const expired = (ctx, inv) => Date.parse(ctx.occurredAt) - Date.parse(inv.created_at) > WEEK;
+function toInvitation(ctx, inv) {
+    const repo = gh(ctx).state().repos.find((r) => r.full_name === inv.repository);
+    return {
+        id: inv.id, node_id: nodeId('RepositoryInvitation', inv.id), repository: repo ? toGithubRepo(repo) : { full_name: inv.repository }, invitee: toSimpleUser(inv.invitee), inviter: toSimpleUser(inv.inviter),
+        permissions: INVITED_AS[inv.permission] ?? inv.permission, created_at: inv.created_at, expired: expired(ctx, inv),
+        url: `https://api.github.com/user/repository_invitations/${inv.id}`, html_url: `https://github.com/${inv.repository}/invitations`,
+    };
+}
+const write = (ctx, operation, inv, fields) => put(ctx, { operation, subjectType: 'repo_invitation', subjectId: `repoinvite:${inv.id}`, fields: { number: inv.id, repository: inv.repository, invitee: inv.invitee, ...fields } });
+/** The invitation an address names, when it is the caller's own (the invitee's side) or the repository's (the inviter's). */
+function named(ctx, id, side) {
+    const inv = invitations(ctx).find((i) => i.id === Number(decodeURIComponent(id)));
+    if (!inv)
+        return undefined;
+    return side === 'invitee' ? (inv.invitee === me(ctx) ? inv : undefined) : (inv.repository === gh(ctx).repo ? inv : undefined);
+}
+const reposListInvitations = async (ctx) => {
+    const { repo, query } = gh(ctx);
+    return ctx.reply(paginate(invitations(ctx).filter((i) => i.repository === repo), query).map((i) => toInvitation(ctx, i)));
+};
+const reposUpdateInvitation = async (ctx) => {
+    const inv = named(ctx, gh(ctx).seg[4], 'repository');
+    if (!inv)
+        return send(ctx, githubNotFound());
+    const wanted = String(gh(ctx).body.permissions ?? '');
+    if (!GRANTED_AS[wanted])
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'RepositoryInvitation', field: 'permissions', code: 'invalid' }] }, 422);
+    const next = { ...inv, permission: GRANTED_AS[wanted] };
+    await write(ctx, 'repo_invitation.update', next, { permission: next.permission });
+    return ctx.reply(toInvitation(ctx, next));
+};
+const reposDeleteInvitation = async (ctx) => {
+    const inv = named(ctx, gh(ctx).seg[4], 'repository');
+    if (!inv)
+        return send(ctx, githubNotFound());
+    await write(ctx, 'repo_invitation.withdraw', inv, { deleted: true });
+    return send(ctx, { status: 204, body: undefined });
+};
+const reposDeclineInvitationForAuthenticatedUser = async (ctx) => {
+    const inv = named(ctx, gh(ctx).seg[2], 'invitee');
+    if (!inv)
+        return send(ctx, githubNotFound());
+    await write(ctx, 'repo_invitation.decline', inv, { deleted: true });
+    return send(ctx, { status: 204, body: undefined });
+};
+export const repoInvitationsSemantics = {
+    'repos/add-collaborator': async (ctx) => {
+        const { repo, seg, body, state, occurredAt, caller } = gh(ctx);
+        const login = decodeURIComponent(seg[4]);
+        const permission = String(body.permission ?? 'push');
+        const st = state();
+        const already = st.collaborators.some((c) => c.repository === repo && c.login === login);
+        const member = st.orgMembers.some((m) => m.org === repo.split('/')[0] && m.login === login && m.state === 'active');
+        if (already || member) {
+            await put(ctx, { operation: already ? 'collaborator.update' : 'collaborator.add', subjectType: 'collaborator', subjectId: `collab:${repo}#${login}`, fields: { repository: repo, login, permission } });
+            if (!already)
+                await announce(ctx, [{ event: 'member', action: 'added', repository: repo, number: 0 }]);
+            return send(ctx, { status: 204, body: undefined });
+        }
+        // inviting someone again changes the invitation that is still pending
+        const pending = invitations(ctx).find((i) => i.repository === repo && i.invitee === login);
+        const inv = { id: pending?.id ?? nextSeq(ctx, 'repoinvite'), repository: repo, invitee: login, inviter: pending?.inviter ?? caller ?? GITHUB_WORLD_USER, permission, created_at: pending?.created_at ?? occurredAt };
+        await write(ctx, pending ? 'repo_invitation.update' : 'repo_invitation.create', inv, { inviter: inv.inviter, permission, created_at: inv.created_at });
+        return ctx.reply(toInvitation(ctx, inv), 201);
+    },
+    'repos/list-invitations': reposListInvitations,
+    'repos/update-invitation': reposUpdateInvitation,
+    'repos/delete-invitation': reposDeleteInvitation,
+    'repos/list-invitations-for-authenticated-user': async (ctx) => {
+        const who = me(ctx);
+        return ctx.reply(paginate(invitations(ctx).filter((i) => i.invitee === who), gh(ctx).query).map((i) => toInvitation(ctx, i)));
+    },
+    // the invitee becomes a collaborator with the permission they were invited with
+    'repos/accept-invitation-for-authenticated-user': async (ctx) => {
+        const inv = named(ctx, gh(ctx).seg[2], 'invitee');
+        if (!inv || expired(ctx, inv))
+            return send(ctx, githubNotFound());
+        await write(ctx, 'repo_invitation.accept', inv, { deleted: true });
+        await put(ctx, { operation: 'collaborator.add', subjectType: 'collaborator', subjectId: `collab:${inv.repository}#${inv.invitee}`, fields: { repository: inv.repository, login: inv.invitee, permission: inv.permission } });
+        await announce(ctx, [{ event: 'member', action: 'added', repository: inv.repository, number: 0 }]);
+        return send(ctx, { status: 204, body: undefined });
+    },
+    'repos/decline-invitation-for-authenticated-user': reposDeclineInvitationForAuthenticatedUser,
+};

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

@@ -0,0 +1,17 @@
+import type { Semantics } from '@volter/world-core';
+/** The people who can be assigned in a repository (docs.github.com/rest/issues/assignees). */
+export declare function assignable(st: {
+    orgs: Array<{
+        login: string;
+    }>;
+    orgMembers: Array<{
+        org: string;
+        login: string;
+        state: string;
+    }>;
+    collaborators: Array<{
+        repository: string;
+        login: string;
+    }>;
+}, repo: string): string[];
+export declare function reposSemantics(): Record<string, Semantics>;