@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/activity.js

@@ -0,0 +1,161 @@
+import { GITHUB_WORLD_USER, githubActivityEvents, githubNotFound, paginate, seedUser, toGithubNotification, toGithubRepo, toGithubUser } from "../github-twin.js";
+import { announce, asView, gh, put, send } from "./shared.js";
+/** Mark one notification thread read (or unread), keeping the fields it was stored with. */
+function markThread(ctx, n, unread) {
+    return put(ctx, { operation: 'notification.read', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, repository: n.repository, subject_title: n.subject_title, subject_type: n.subject_type, reason: n.reason, unread, updated_at: ctx.occurredAt } });
+}
+/** The inbox as GitHub lists it: the most recently updated thread first. */
+const latestFirst = (threads) => threads.map((n, i) => [n, i]).sort((a, b) => String(b[0].updated_at ?? '').localeCompare(String(a[0].updated_at ?? '')) || b[1] - a[1]).map(([n]) => n);
+/** A thread's subscription as GitHub answers it. */
+function subscriptionOf(n) {
+    const sub = n.subscription === null ? { subscribed: false, ignored: false, created_at: undefined } : (n.subscription ?? { subscribed: true, ignored: false, created_at: n.updated_at });
+    return { subscribed: sub.subscribed, ignored: sub.ignored, reason: null, created_at: sub.created_at ?? null, url: `https://api.github.com/notifications/threads/${n.id}/subscription`, thread_url: `https://api.github.com/notifications/threads/${n.id}` };
+}
+/** Who the credential names: its user, or the World's own for its shared token. */
+export const me = (ctx) => gh(ctx).caller ?? GITHUB_WORLD_USER;
+/** GET .../stargazers and .../subscribers: everyone who stars or watches the repo. */
+const repoFans = (stars) => async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const st = state();
+    const items = (stars ? st.starEdges : st.watchEdges).filter((e) => e.to === repo).map((e) => asView('simple-user', toGithubUser(seedUser(e.from))));
+    return ctx.reply(paginate(items, query));
+};
+const star = (starred) => async (ctx) => {
+    const { seg } = gh(ctx);
+    const repo = `${seg[2]}/${seg[3]}`;
+    await put(ctx, { operation: starred ? 'star.add' : 'star.remove', subjectType: 'star', subjectId: `star:${me(ctx)}:${repo}`, fields: { repository: repo, starred } });
+    await announce(ctx, [{ event: 'star', action: starred ? 'created' : 'deleted', repository: repo, number: 0 }]);
+    return send(ctx, { status: 204, body: undefined });
+};
+const watch = (subscribed) => async (ctx) => {
+    const { repo } = gh(ctx);
+    await put(ctx, { operation: subscribed ? 'repo_subscription.watch' : 'repo_subscription.unwatch', subjectType: 'repo_subscription', subjectId: `watch:${me(ctx)}:${repo}`, fields: { repository: repo, subscribed } });
+    if (!subscribed)
+        return send(ctx, { status: 204, body: undefined });
+    return ctx.reply({ subscribed: true, ignored: false, reason: null, repository_url: `https://api.github.com/repos/${repo}` });
+};
+export function activitySemantics() {
+    const activityGetFeeds = async (ctx) => {
+        const api = 'https://github.com';
+        const link = (href) => ({ href, type: 'application/atom+xml' });
+        return ctx.reply({
+            timeline_url: `${api}/timeline`, user_url: `${api}/{user}`,
+            current_user_public_url: `${api}/octocat`, current_user_url: `${api}/octocat.private?token=t`,
+            current_user_actor_url: `${api}/octocat.private.actor?token=t`,
+            current_user_organization_url: '', current_user_organization_urls: [],
+            security_advisories_url: `${api}/security-advisories`,
+            _links: { timeline: link(`${api}/timeline`), user: link(`${api}/{user}`), current_user_public: link(`${api}/octocat`), security_advisories: link(`${api}/security-advisories`) },
+        });
+    };
+    const activityListPublicEvents = async (ctx) => {
+        const { query, state } = gh(ctx);
+        return ctx.reply(paginate(githubActivityEvents(state()), query));
+    };
+    const activityListRepoEvents = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(githubActivityEvents(state()).filter((e) => e.repo.name === repo), query));
+    };
+    const activityListNotificationsForAuthenticatedUser = async (ctx) => {
+        const { query, state } = gh(ctx);
+        const all = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('all') === 'true';
+        return ctx.reply(paginate(latestFirst(state().notifications.filter((n) => all || n.unread)), query).map(toGithubNotification));
+    };
+    const activityListRepoNotificationsForAuthenticatedUser = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const all = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('all') === 'true';
+        return ctx.reply(paginate(latestFirst(state().notifications.filter((n) => n.repository === repo && (all || n.unread))), query).map(toGithubNotification));
+    };
+    const activityGetThread = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]));
+        return send(ctx, n ? { status: 200, body: toGithubNotification(n) } : githubNotFound());
+    };
+    const activityGetThreadSubscriptionForAuthenticatedUser = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]));
+        return send(ctx, n ? { status: 200, body: subscriptionOf(n) } : githubNotFound());
+    };
+    const activitySetThreadSubscription = async (ctx) => {
+        const { seg, body, state, occurredAt } = gh(ctx);
+        const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]));
+        if (!n)
+            return send(ctx, githubNotFound());
+        const subscription = { subscribed: body.ignored !== true, ignored: body.ignored === true, created_at: occurredAt };
+        await put(ctx, { operation: 'notification.subscribe', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, subscription, ...(subscription.ignored ? { unread: false } : {}) } });
+        return ctx.reply(subscriptionOf({ ...n, subscription }));
+    };
+    const activityDeleteThreadSubscription = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]));
+        if (!n)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'notification.unsubscribe', subjectType: 'notification', subjectId: `notification:${n.id}`, fields: { id: n.id, subscription: null } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const activityMarkThreadAsRead = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const n = state().notifications.find((x) => x.id === decodeURIComponent(seg[2]));
+        if (!n)
+            return send(ctx, githubNotFound());
+        await markThread(ctx, n, false);
+        return send(ctx, { status: 205, body: undefined });
+    };
+    const activityMarkNotificationsAsRead = async (ctx) => {
+        for (const n of gh(ctx).state().notifications.filter((x) => x.unread))
+            await markThread(ctx, n, false);
+        return send(ctx, { status: 205, body: undefined });
+    };
+    const activityMarkRepoNotificationsAsRead = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        for (const n of state().notifications.filter((x) => x.repository === repo && x.unread))
+            await markThread(ctx, n, false);
+        return send(ctx, { status: 205, body: undefined });
+    };
+    const activityListReposStarredByAuthenticatedUser = async (ctx) => {
+        const { query, state } = gh(ctx);
+        const st = state();
+        const mine = st.starEdges.filter((e) => e.from === me(ctx)).map((e) => e.to);
+        const items = mine.map((full) => st.repos.find((r) => r.full_name === full)).filter((r) => !!r).map((r) => asView('repository', toGithubRepo(r)));
+        return ctx.reply(paginate(items, query));
+    };
+    const activityCheckRepoIsStarredByAuthenticatedUser = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        return send(ctx, state().starEdges.some((e) => e.from === me(ctx) && e.to === `${seg[2]}/${seg[3]}`) ? { status: 204, body: undefined } : githubNotFound());
+    };
+    const activityGetRepoSubscription = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        return send(ctx, state().watchEdges.some((e) => e.from === me(ctx) && e.to === repo) ? { status: 200, body: { subscribed: true, ignored: false, reason: null, repository_url: `https://api.github.com/repos/${repo}` } } : githubNotFound());
+    };
+    return {
+        // the feed-URL catalog (timeline/user/security-advisories links); stateless
+        'activity/get-feeds': activityGetFeeds,
+        // the public timeline: every modeled event
+        'activity/list-public-events': activityListPublicEvents,
+        // the same projection scoped to one repo
+        'activity/list-repo-events': activityListRepoEvents,
+        // the inbox: unread threads, or every thread with `all=true`
+        'activity/list-notifications-for-authenticated-user': activityListNotificationsForAuthenticatedUser,
+        'activity/list-repo-notifications-for-authenticated-user': activityListRepoNotificationsForAuthenticatedUser,
+        'activity/get-thread': activityGetThread,
+        'activity/get-thread-subscription-for-authenticated-user': activityGetThreadSubscriptionForAuthenticatedUser,
+        // subscribe, or ignore (mute) the thread, which also takes it out of the inbox
+        'activity/set-thread-subscription': activitySetThreadSubscription,
+        // unsubscribe: muted until the person is next @mentioned
+        'activity/delete-thread-subscription': activityDeleteThreadSubscription,
+        // mark a thread read (205)
+        'activity/mark-thread-as-read': activityMarkThreadAsRead,
+        'activity/mark-notifications-as-read': activityMarkNotificationsAsRead,
+        'activity/mark-repo-notifications-as-read': activityMarkRepoNotificationsAsRead,
+        'activity/list-stargazers-for-repo': repoFans(true),
+        'activity/list-watchers-for-repo': repoFans(false),
+        // the authenticated user's starred repos, and the membership check (204 starred / 404 not)
+        'activity/list-repos-starred-by-authenticated-user': activityListReposStarredByAuthenticatedUser,
+        'activity/check-repo-is-starred-by-authenticated-user': activityCheckRepoIsStarredByAuthenticatedUser,
+        'activity/star-repo-for-authenticated-user': star(true),
+        'activity/unstar-repo-for-authenticated-user': star(false),
+        // the authenticated user's watch on a repo ({subscribed:true} or 404)
+        'activity/get-repo-subscription': activityGetRepoSubscription,
+        'activity/set-repo-subscription': watch(true),
+        'activity/delete-repo-subscription': watch(false),
+    };
+}

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

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

package/dist/src/semantics/apps.js

@@ -0,0 +1,144 @@
+// GitHub's Apps family: an app by its slug, the app's installations and installation access tokens. An app
+// is registered through the twin's door (GitHub's settings UI has no API) and installed by a person on its
+// page (src/screens/app-installation.tsx); a token is minted deterministically from its installation.
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { githubApps, githubNotFound, paginate, toGithubApp, toGithubAppInstallation } from "../github-twin.js";
+import { gh, put, send } from "./shared.js";
+import { emitGithubAppEvent, githubAppDeliveries, githubAppDelivery } from "../github-events.js";
+// An app speaks for itself with a JSON Web Token it signs with its private key: its client ID (or app ID) as `iss`,
+// issued no later than now and expiring at most ten minutes after it was issued
+// (docs.github.com/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app).
+// The app's installations and their access tokens take only that token ("You must use a JWT to access this endpoint",
+// docs.github.com/rest/apps/apps). Where the evidence stops: the private key is generated on the app's settings page
+// and never leaves the app's server, so the twin holds no key to check the RS256 signature against; it reads the
+// token's claims, and a token whose claims do not name a registered app, or that is expired, is refused.
+const JWT_DOCS = 'https://docs.github.com/rest/apps/apps';
+const claimsOf = (token) => {
+    const parts = (token ?? '').split('.');
+    try {
+        return parts.length === 3 ? JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** The app a request's JWT authenticates, or nothing when the token is not a live JWT of a registered app. */
+function appOfJwt(ctx) {
+    const claims = claimsOf(gh(ctx).token);
+    const now = Math.floor(Date.parse(ctx.occurredAt) / 1000);
+    const live = typeof claims?.iat === 'number' && typeof claims.exp === 'number' && claims.iat <= now + 60 && claims.exp > now && claims.exp - claims.iat <= 600;
+    return live ? githubApps(ctx.root).find((a) => String(claims.iss) === a.client_id || String(claims.iss) === String(a.id)) : undefined;
+}
+/** GitHub's answer to a call on an app's own endpoints without a live JWT of the app. */
+const jwtRefused = (ctx) => ctx.reply({ message: 'A JSON web token could not be decoded', documentation_url: JWT_DOCS }, 401);
+/** An installation of the app the request's JWT authenticates, by its id. */
+const ownInstallation = (ctx, app) => gh(ctx).state().appInstallations.find((x) => x.id === Number(decodeURIComponent(gh(ctx).seg[2])) && x.app_slug === app.slug);
+export function appsSemantics() {
+    const appsGetBySlug = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const slug = decodeURIComponent(seg[1]);
+        const app = githubApps(ctx.root).find((a) => a.slug === slug);
+        return send(ctx, app ? { status: 200, body: toGithubApp(app, state().appInstallations.filter((i) => i.app_slug === slug).length, state()) } : githubNotFound());
+    };
+    const appsGetAuthenticated = async (ctx) => {
+        const app = appOfJwt(ctx);
+        if (!app)
+            return jwtRefused(ctx);
+        const { state } = gh(ctx);
+        return ctx.reply(toGithubApp(app, state().appInstallations.filter((i) => i.app_slug === app.slug).length, state()));
+    };
+    const appsListInstallations = async (ctx) => {
+        const app = appOfJwt(ctx);
+        if (!app)
+            return jwtRefused(ctx);
+        const { query, state } = gh(ctx);
+        return ctx.reply(paginate(state().appInstallations.filter((i) => i.app_slug === app.slug), query).map(toGithubAppInstallation));
+    };
+    const appsGetInstallation = async (ctx) => {
+        const app = appOfJwt(ctx);
+        if (!app)
+            return jwtRefused(ctx);
+        const i = ownInstallation(ctx, app);
+        return send(ctx, i ? { status: 200, body: toGithubAppInstallation(i) } : githubNotFound());
+    };
+    return {
+        // a public app's page data, by its slug
+        'apps/get-by-slug': appsGetBySlug,
+        // The application that sent a person to register it from its manifest exchanges the temporary code GitHub
+        // redirected back with for the app's credentials: once, within an hour, with no other authentication (201)
+        // (docs.github.com/rest/apps/apps#create-a-github-app-from-a-manifest,
+        // docs.github.com/apps/sharing-github-apps/registering-a-github-app-from-a-manifest). A code used or expired is
+        // Not Found. Where the documentation stops and the twin decides: the private key is a stand-in of the PEM's shape
+        // that nothing verifies (a JWT's signature is not checked, see appOfJwt).
+        'apps/create-from-manifest': async (ctx) => {
+            const { seg, occurredAt, state } = gh(ctx);
+            const code = decodeURIComponent(seg[1]);
+            const row = ctx.tree().find((r) => r.type === 'app_manifest_code' && r.code === code && r.deleted !== true);
+            const expired = row && Date.parse(occurredAt) - Date.parse(String(row.created_at)) > 60 * 60 * 1000;
+            const app = row && githubApps(ctx.root).find((a) => a.slug === row.app_slug);
+            if (!row || row.used === true || expired || !app)
+                return send(ctx, githubNotFound());
+            await put(ctx, { operation: 'app_manifest_code.use', subjectType: 'app_manifest_code', subjectId: `manifestcode:${code}`, fields: { used: true } });
+            const secret = (what) => createHash('sha256').update(`app:${app.slug}:${what}`).digest('hex');
+            const pem = `-----BEGIN RSA PRIVATE KEY-----\n${Buffer.from(secret('key') + secret('key2')).toString('base64').match(/.{1,64}/g).join('\n')}\n-----END RSA PRIVATE KEY-----\n`;
+            return ctx.reply({ ...toGithubApp(app, 0, state()), client_secret: secret('client').slice(0, 40), webhook_secret: app.webhook_secret ?? null, pem }, 201);
+        },
+        // the app the JWT authenticates (docs.github.com/rest/apps/apps#get-the-authenticated-app)
+        'apps/get-authenticated': appsGetAuthenticated,
+        // the deliveries of the app's own webhook, and one in detail with the payload it carried
+        // (docs.github.com/rest/apps/webhooks#list-deliveries-for-an-app-webhook)
+        'apps/list-webhook-deliveries': async (ctx) => {
+            const app = appOfJwt(ctx);
+            if (!app)
+                return jwtRefused(ctx);
+            return ctx.reply(paginate(githubAppDeliveries(app.id, ctx.root), gh(ctx).query));
+        },
+        'apps/get-webhook-delivery': async (ctx) => {
+            const app = appOfJwt(ctx);
+            if (!app)
+                return jwtRefused(ctx);
+            const d = githubAppDelivery(app.id, Number(decodeURIComponent(gh(ctx).seg[3])), ctx.root);
+            return send(ctx, d ? { status: 200, body: d } : githubNotFound());
+        },
+        // the app uninstalls itself from an account: the installation and its tokens are gone (204)
+        // (docs.github.com/rest/apps/apps#delete-an-installation-for-the-authenticated-app)
+        'apps/delete-installation': async (ctx) => {
+            const app = appOfJwt(ctx);
+            if (!app)
+                return jwtRefused(ctx);
+            const i = ownInstallation(ctx, app);
+            if (!i)
+                return send(ctx, githubNotFound());
+            await put(ctx, { operation: 'app_installation.delete', subjectType: 'app_installation', subjectId: `installation:${i.id}`, fields: { deleted: true } });
+            for (const t of ctx.tree().filter((r) => r.type === 'app_token' && r.installation_id === i.id && r.deleted !== true)) {
+                await put(ctx, { operation: 'app_token.revoke', subjectType: 'app_token', subjectId: String(t.id), fields: { deleted: true } });
+            }
+            try {
+                await emitGithubAppEvent(app, 'installation', { action: 'deleted', installation: toGithubAppInstallation(i), sender: { login: `${app.slug}[bot]`, type: 'Bot' } }, { occurredAt: ctx.occurredAt, ...(ctx.root !== undefined ? { root: ctx.root } : {}) });
+            }
+            catch { /* a delivery failure never fails the deletion */ }
+            return send(ctx, { status: 204, body: undefined });
+        },
+        // the installations of the app the JWT authenticates
+        'apps/list-installations': appsListInstallations,
+        'apps/get-installation': appsGetInstallation,
+        // A deterministic installation token (ghs_…) bound to the installation's permissions. Real tokens
+        // expire in about an hour; the twin answers a fixed far-future expiry (never the clock).
+        'apps/create-installation-access-token': async (ctx) => {
+            const app = appOfJwt(ctx);
+            if (!app)
+                return jwtRefused(ctx);
+            const { body } = gh(ctx);
+            const i = ownInstallation(ctx, app);
+            if (!i)
+                return send(ctx, githubNotFound());
+            const id = i.id;
+            const token = `ghs_${createHash('sha256').update(`insttoken:${id}`).digest('hex').slice(0, 36)}`;
+            const perms = body.permissions ?? i.permissions;
+            // the token is the app's credential for this installation: what it may do, and on which repositories
+            await put(ctx, { operation: 'app_token.create', subjectType: 'app_token', subjectId: `apptoken:${token}`, fields: { token, installation_id: id, app_slug: i.app_slug, account_login: i.account_login, permissions: perms, repository_selection: i.repository_selection, repositories: i.repositories ?? [] } });
+            return ctx.reply({ token, expires_at: '2100-01-01T00:00:00Z', permissions: perms, repository_selection: i.repository_selection }, 201);
+        },
+    };
+}

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

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

package/dist/src/semantics/branches.js

@@ -0,0 +1,136 @@
+import { githubNotFound, isAncestorInPlane, mergeIntoBranchInPlane, normalizeRequiredStatusChecks, paginate, resolvePlaneRef, toGithubBranch, toGithubBranchProtection, updateGitRefInPlane } from "../github-twin.js";
+import { announce, gh, put, send } from "./shared.js";
+const SYNC_DOCS = 'https://docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository';
+/** A fork's branch brought up to date with the same branch of the repository it was forked from: fast-forwarded when
+ *  it has nothing of its own, merged when it has, 409 when the merge conflicts, 422 when the repository is no fork or
+ *  names no branch (docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository). */
+const syncFork = async (ctx) => {
+    const { repo, body, root, occurredAt, state } = gh(ctx);
+    const fork = state().repos.find((r) => r.full_name === repo);
+    if (!fork)
+        return send(ctx, githubNotFound());
+    const branch = typeof body.branch === 'string' ? body.branch : '';
+    const upstream = fork.parent_full_name;
+    const theirs = upstream && branch ? await resolvePlaneRef(upstream, `refs/heads/${branch}`, branch, root) : null;
+    const ours = branch ? await resolvePlaneRef(repo, `refs/heads/${branch}`, branch, root) : null;
+    if (!upstream || !theirs || !ours)
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Repository', field: 'branch', code: 'invalid' }], documentation_url: SYNC_DOCS }, 422);
+    const base_branch = `${upstream.split('/')[0]}:${branch}`;
+    if (ours === theirs || await isAncestorInPlane(repo, theirs, ours, root))
+        return ctx.reply({ message: `This branch is not behind the upstream ${base_branch}.`, merge_type: 'none', base_branch });
+    const forward = await isAncestorInPlane(repo, ours, theirs, root);
+    const landed = forward ? (await updateGitRefInPlane(repo, `refs/heads/${branch}`, theirs, root, ours) ? { sha: theirs } : null) : await mergeIntoBranchInPlane(repo, branch, theirs, `Merge branch '${branch}' of github.com:${upstream}`, 'merge', occurredAt, root);
+    if (!landed || 'conflict' in landed)
+        return ctx.reply({ message: 'There are merge conflicts', documentation_url: SYNC_DOCS }, 409);
+    await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${repo}#refs/heads/${branch}`, fields: { repository: repo, ref: `refs/heads/${branch}`, object_sha: landed.sha, object_type: 'commit' } });
+    await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branch}`, fields: { repository: repo, name: branch, commit_sha: landed.sha } });
+    await announce(ctx, [{ event: 'push', action: '', repository: repo, number: 0, ref: `refs/heads/${branch}`, before: ours, after: landed.sha }]);
+    return ctx.reply({ message: forward ? `Successfully fetched and fast-forwarded from upstream ${base_branch}.` : `Successfully fetched and merged from upstream ${base_branch}.`, merge_type: forward ? 'fast-forward' : 'merge', base_branch });
+};
+const notProtected = { status: 404, body: { message: 'Branch not protected', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' } };
+/** The branch a protection path names (a name may hold slashes). */
+function branchOf(ctx) {
+    const { repo, seg, state } = gh(ctx);
+    const name = decodeURIComponent(seg[4]);
+    return { name, b: state().branches.find((x) => x.repository === repo && x.name === name) };
+}
+const protectionUrl = (repo, name) => `https://api.github.com/repos/${repo}/branches/${encodeURIComponent(name)}/protection`;
+/** Write a protected branch's config. */
+const protect = (ctx, name, b, protection_config) => put(ctx, { operation: 'branch.protect', subjectType: 'branch', subjectId: `branch:${gh(ctx).repo}#${name}`, fields: { repository: gh(ctx).repo, name, commit_sha: b.commit_sha, protected: true, protection_config } });
+export function branchesSemantics() {
+    const reposListBranches = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        return ctx.reply(paginate(state().branches.filter((b) => b.repository === repo), query).map(toGithubBranch));
+    };
+    const reposGetBranchProtection = async (ctx) => {
+        const { b } = branchOf(ctx);
+        return send(ctx, b?.protected ? { status: 200, body: toGithubBranchProtection(b) } : notProtected);
+    };
+    const reposGetStatusChecksProtection = async (ctx) => {
+        const { repo } = gh(ctx);
+        const { name, b } = branchOf(ctx);
+        if (!b?.protected)
+            return send(ctx, notProtected);
+        const rsc = b.protection_config?.required_status_checks;
+        if (!rsc)
+            return ctx.reply({ message: 'Required status checks not enabled', documentation_url: 'https://docs.github.com/rest/branches/branch-protection' }, 404);
+        const base = protectionUrl(repo, name);
+        return ctx.reply({ url: `${base}/required_status_checks`, strict: rsc.strict, contexts: rsc.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: rsc.checks });
+    };
+    const reposGetAdminBranchProtection = async (ctx) => {
+        const { repo } = gh(ctx);
+        const { name, b } = branchOf(ctx);
+        if (!b?.protected)
+            return send(ctx, notProtected);
+        return ctx.reply({ url: `${protectionUrl(repo, name)}/enforce_admins`, enabled: b.protection_config?.enforce_admins ?? false });
+    };
+    const reposUpdateStatusCheckProtection = async (ctx) => {
+        const { repo, body } = gh(ctx);
+        const { name, b } = branchOf(ctx);
+        if (!b?.protected)
+            return send(ctx, githubNotFound());
+        const prev = b.protection_config?.required_status_checks ?? { strict: false, contexts: [], checks: [] };
+        const next = normalizeRequiredStatusChecks({ strict: body.strict ?? prev.strict, contexts: body.contexts ?? (body.checks === undefined ? prev.contexts : undefined), checks: body.checks });
+        const base = protectionUrl(repo, name);
+        await protect(ctx, name, b, { ...(b.protection_config ?? {}), required_status_checks: next });
+        return ctx.reply({ url: `${base}/required_status_checks`, strict: next.strict, contexts: next.contexts, contexts_url: `${base}/required_status_checks/contexts`, checks: next.checks });
+    };
+    return {
+        'repos/merge-upstream': syncFork,
+        'repos/list-branches': reposListBranches,
+        // a branch name may hold slashes
+        'repos/get-branch': async (ctx) => {
+            const { repo, seg, state } = gh(ctx);
+            const name = decodeURIComponent(seg.slice(4).join('/'));
+            const b = state().branches.find((x) => x.repository === repo && x.name === name);
+            return send(ctx, b ? { status: 200, body: toGithubBranch(b) } : githubNotFound());
+        },
+        // the persisted config back out; 404 "Branch not protected" when protection is off
+        'repos/get-branch-protection': reposGetBranchProtection,
+        'repos/get-status-checks-protection': reposGetStatusChecksProtection,
+        'repos/get-admin-branch-protection': reposGetAdminBranchProtection,
+        // Protect and persist the config. GitHub 422s unless all four keys are present (each nullable,
+        // never omittable). A branch the twin has not seen is created by its first protection write.
+        'repos/update-branch-protection': async (ctx) => protection(ctx, true),
+        'repos/delete-branch-protection': async (ctx) => protection(ctx, false),
+        // update the required checks of a protected branch (404 when not protected)
+        'repos/update-status-check-protection': reposUpdateStatusCheckProtection,
+        'repos/set-admin-branch-protection': async (ctx) => enforceAdmins(ctx, true),
+        'repos/delete-admin-branch-protection': async (ctx) => enforceAdmins(ctx, false),
+    };
+}
+async function protection(ctx, protecting) {
+    const { repo, body, state } = gh(ctx);
+    const { name, b } = branchOf(ctx);
+    // a branch must exist to be protected (docs.github.com/rest/branches/branch-protection#update-branch-protection)
+    if (!b)
+        return ctx.reply({ message: 'Branch not found', documentation_url: 'https://docs.github.com/rest/branches/branch-protection#update-branch-protection' }, 404);
+    if (protecting) {
+        const missingKeys = ['required_status_checks', 'enforce_admins', 'required_pull_request_reviews', 'restrictions'].filter((k) => !(k in body));
+        if (missingKeys.length)
+            return ctx.reply({ message: 'Validation Failed', errors: missingKeys.map((field) => ({ resource: 'BranchProtection', field, code: 'missing_field' })) }, 422);
+    }
+    const protection_config = protecting
+        ? {
+            required_status_checks: normalizeRequiredStatusChecks(body.required_status_checks),
+            enforce_admins: body.enforce_admins === true,
+            required_pull_request_reviews: body.required_pull_request_reviews && typeof body.required_pull_request_reviews === 'object' ? body.required_pull_request_reviews : null,
+            restrictions: body.restrictions && typeof body.restrictions === 'object' ? body.restrictions : null,
+        }
+        : null;
+    await put(ctx, { operation: protecting ? 'branch.protect' : 'branch.unprotect', subjectType: 'branch', subjectId: `branch:${repo}#${name}`, fields: { repository: repo, name, commit_sha: b.commit_sha, protected: protecting, protection_config } });
+    if (!protecting)
+        return send(ctx, { status: 204, body: undefined });
+    return ctx.reply(toGithubBranchProtection(state().branches.find((x) => x.repository === repo && x.name === name)));
+}
+/** Toggle admin enforcement on a protected branch (404 when not protected). */
+async function enforceAdmins(ctx, enabled) {
+    const { repo } = gh(ctx);
+    const { name, b } = branchOf(ctx);
+    if (!b?.protected)
+        return send(ctx, githubNotFound());
+    await protect(ctx, name, b, { ...(b.protection_config ?? {}), enforce_admins: enabled });
+    if (!enabled)
+        return send(ctx, { status: 204, body: undefined });
+    return ctx.reply({ url: `${protectionUrl(repo, name)}/enforce_admins`, enabled });
+}

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

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

package/dist/src/semantics/checks.js

@@ -0,0 +1,176 @@
+import { combineStatuses, githubNotFound, paginate, planeCommitBody, toGithubAnnotation, toGithubCheckRun, toGithubCheckSuite, toGithubStatus, } from "../github-twin.js";
+import { gh, nextSeq, put, send } from "./shared.js";
+const refOf = (ctx) => decodeURIComponent(gh(ctx).seg[4]);
+/** The app a check-run write comes from, or GitHub's refusal when it is not an installed app allowed checks:write on
+ *  this repository. */
+function appWriting(ctx) {
+    const { token, repo } = gh(ctx);
+    const docs = 'https://docs.github.com/rest/checks/runs#create-a-check-run';
+    const grant = token ? ctx.tree().find((r) => r.type === 'app_token' && r.token === token && r.deleted !== true) : undefined;
+    if (!grant)
+        return { refused: ctx.reply({ message: 'You must authenticate via a GitHub App.', documentation_url: docs }, 403) };
+    const names = grant.repositories ?? [];
+    const covers = grant.repository_selection !== 'selected' ? repo.split('/')[0] === grant.account_login : names.some((n) => n === repo || `${String(grant.account_login)}/${n}` === repo);
+    if (grant.permissions?.checks !== 'write' || !covers)
+        return { refused: ctx.reply({ message: 'Resource not accessible by integration', documentation_url: docs }, 403) };
+    return { app: String(grant.app_slug) };
+}
+/** The commit a suite checks, as GitHub's simple-commit, read from the repository's git plane when it holds it. */
+async function headCommit(repo, sha, root) {
+    const c = await planeCommitBody(repo, sha, root);
+    if (!c?.commit)
+        return {};
+    const who = (p) => ({ name: p?.name ?? '', email: p?.email ?? '' });
+    return { head_commit: { id: sha, tree_id: c.commit.tree?.sha ?? '', message: c.commit.message ?? '', timestamp: c.commit.author?.date ?? '', author: who(c.commit.author), committer: who(c.commit.committer) } };
+}
+export function checksSemantics() {
+    const reposGetCombinedStatusForRef = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        return ctx.reply(combineStatuses(repo, refOf(ctx), state().statuses));
+    };
+    const reposListCommitStatusesForRef = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const ref = refOf(ctx);
+        return ctx.reply(paginate(state().statuses.filter((s) => s.repository === repo && s.sha === ref).sort((a, b) => b.id - a.id), query).map(toGithubStatus));
+    };
+    const reposCreateCommitStatus = async (ctx) => {
+        const { repo, body, occurredAt } = gh(ctx);
+        const sha = refOf(ctx);
+        if (!body.state)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Status', field: 'state', code: 'missing_field' }] }, 422);
+        if (!['error', 'failure', 'pending', 'success'].includes(body.state))
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Status', field: 'state', code: 'invalid' }] }, 422);
+        const seq = nextSeq(ctx, 'status');
+        const fields = { repository: repo, sha, state: body.state, context: body.context ?? 'default', description: body.description, target_url: body.target_url, created_at: occurredAt, updated_at: occurredAt };
+        await put(ctx, { operation: 'commit_status.create', subjectType: 'commit_status', subjectId: `status:${seq}`, fields });
+        return ctx.reply(toGithubStatus({ id: seq, ...fields }), 201);
+    };
+    const checksListSuitesForRef = async (ctx) => {
+        const { repo, state, root } = gh(ctx);
+        const ref = refOf(ctx);
+        const st = state();
+        const apps = [...new Set(st.checkRuns.filter((c) => c.repository === repo && c.head_sha === ref).map((c) => c.app_slug))];
+        const head = await headCommit(repo, ref, root);
+        const suites = apps.map((app) => ({ ...toGithubCheckSuite(repo, ref, st.checkRuns, app, st), ...head }));
+        return ctx.reply({ total_count: suites.length, check_suites: suites });
+    };
+    const checksGet = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const cr = state().checkRuns.find((c) => c.repository === repo && c.id === Number(refOf(ctx)));
+        return send(ctx, cr ? { status: 200, body: toGithubCheckRun(cr, state()) } : githubNotFound());
+    };
+    const checksListAnnotations = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const cr = state().checkRuns.find((c) => c.repository === repo && c.id === Number(refOf(ctx)));
+        if (!cr)
+            return send(ctx, githubNotFound());
+        return ctx.reply(paginate(cr.annotations ?? [], query).map((an) => toGithubAnnotation(cr, an)));
+    };
+    const checksGetSuite = async (ctx) => {
+        const { repo, state, root } = gh(ctx);
+        const st = state();
+        const id = Number(refOf(ctx));
+        const cr = st.checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id);
+        return send(ctx, cr ? { status: 200, body: { ...toGithubCheckSuite(repo, cr.head_sha, st.checkRuns, cr.app_slug, st), ...(await headCommit(repo, cr.head_sha, root)) } } : githubNotFound());
+    };
+    const checksListForSuite = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const st = state();
+        const id = Number(refOf(ctx));
+        if (!st.checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id))
+            return send(ctx, githubNotFound());
+        const items = st.checkRuns.filter((c) => c.repository === repo && (c.check_suite_id ?? 0) === id).sort((a, b) => a.id - b.id);
+        return ctx.reply({ total_count: items.length, check_runs: paginate(items, query).map((c) => toGithubCheckRun(c, state())) });
+    };
+    const checksUpdate = async (ctx) => {
+        const writer = appWriting(ctx);
+        if ('refused' in writer)
+            return writer.refused;
+        const { repo, body, occurredAt, state } = gh(ctx);
+        const id = Number(refOf(ctx));
+        const existing = state().checkRuns.find((c) => c.repository === repo && c.id === id);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        // an app updates only the check runs it created
+        if (existing.app_slug && existing.app_slug !== writer.app)
+            return ctx.reply({ message: 'Resource not accessible by integration', documentation_url: 'https://docs.github.com/rest/checks/runs#update-a-check-run' }, 403);
+        const fields = { repository: repo, head_sha: existing.head_sha, name: existing.name, app_slug: existing.app_slug ?? writer.app };
+        if (body.status !== undefined)
+            fields.status = String(body.status);
+        if (body.conclusion !== undefined) {
+            fields.conclusion = String(body.conclusion);
+            fields.status = body.status ?? 'completed';
+            fields.completed_at = body.completed_at ?? occurredAt;
+        }
+        fields.started_at = existing.started_at;
+        const output = body.output;
+        if (output) {
+            if (output.title !== undefined)
+                fields.output_title = String(output.title);
+            if (output.summary !== undefined)
+                fields.output_summary = String(output.summary);
+            if (output.text !== undefined)
+                fields.output_text = String(output.text);
+            const anns = Array.isArray(output.annotations) ? output.annotations : (existing.annotations ?? []);
+            fields.annotations = anns.map((an) => ({
+                path: String(an.path), start_line: Number(an.start_line), end_line: Number(an.end_line),
+                annotation_level: String(an.annotation_level), message: String(an.message),
+                title: an.title, raw_details: an.raw_details, start_column: an.start_column, end_column: an.end_column,
+            }));
+        }
+        else if (existing.annotations) {
+            fields.annotations = existing.annotations;
+        }
+        await put(ctx, { operation: 'check_run.update', subjectType: 'check_run', subjectId: `check:${id}`, fields });
+        return ctx.reply(toGithubCheckRun(state().checkRuns.find((c) => c.id === id), state()));
+    };
+    const checksRerequestSuite = async (ctx) => {
+        const { repo, state } = gh(ctx);
+        const id = Number(refOf(ctx));
+        if (!state().checkRuns.find((c) => c.repository === repo && (c.check_suite_id ?? 0) === id))
+            return send(ctx, githubNotFound());
+        return ctx.reply({}, 201);
+    };
+    return {
+        'repos/get-combined-status-for-ref': reposGetCombinedStatusForRef,
+        // newest first
+        'repos/list-commit-statuses-for-ref': reposListCommitStatusesForRef,
+        // 422 without a state or with one outside the enum
+        'repos/create-commit-status': reposCreateCommitStatus,
+        // {total_count, check_runs}, paginated over check_runs
+        'checks/list-for-ref': async (ctx) => {
+            const { repo, query, state } = gh(ctx);
+            const ref = refOf(ctx);
+            const items = state().checkRuns.filter((c) => c.repository === repo && c.head_sha === ref).sort((a, b) => a.id - b.id);
+            return ctx.reply({ total_count: items.length, check_runs: paginate(items, query).map((c) => toGithubCheckRun(c, state())) });
+        },
+        // one suite per app that ran checks on the commit
+        'checks/list-suites-for-ref': checksListSuitesForRef,
+        'checks/get': checksGet,
+        'checks/list-annotations': checksListAnnotations,
+        'checks/get-suite': checksGetSuite,
+        'checks/list-for-suite': checksListForSuite,
+        // queued unless it carries a conclusion (then completed)
+        'checks/create': async (ctx) => {
+            const writer = appWriting(ctx);
+            if ('refused' in writer)
+                return writer.refused;
+            const { repo, body, occurredAt, state } = gh(ctx);
+            const missing = ['name', 'head_sha'].filter((k) => !body[k]);
+            if (missing.length)
+                return ctx.reply({ message: 'Validation Failed', errors: missing.map((field) => ({ resource: 'CheckRun', field, code: 'missing_field' })) }, 422);
+            const seq = nextSeq(ctx, 'check');
+            const status = body.status ?? (body.conclusion ? 'completed' : 'queued');
+            const completed_at = body.conclusion ? (body.completed_at ?? occurredAt) : undefined;
+            const fields = { repository: repo, head_sha: body.head_sha, name: body.name, status, conclusion: body.conclusion, details_url: body.details_url, started_at: body.started_at ?? occurredAt, app_slug: writer.app, ...(body.external_id !== undefined ? { external_id: String(body.external_id) } : {}) };
+            if (completed_at !== undefined)
+                fields.completed_at = completed_at;
+            await put(ctx, { operation: 'check_run.create', subjectType: 'check_run', subjectId: `check:${seq}`, fields });
+            return ctx.reply(toGithubCheckRun(state().checkRuns.find((c) => c.id === seq), state()), 201);
+        },
+        // status, conclusion (which completes the run), and output with its annotations
+        'checks/update': checksUpdate,
+        // 201; nothing reruns
+        'checks/rerequest-suite': checksRerequestSuite,
+    };
+}

package/dist/src/semantics/code-scanning-upload.d.ts

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