@volter/twin-github 0.1.2 → 2.0.0

package/src/semantics/meta.ts

@@ -0,0 +1,139 @@
+// GitHub's platform meta family: the service root, the rate limit, and the stateless reference
+// catalogs (gitignore templates, licenses, emojis, service metadata) and the Markdown renderer.
+// None of it is account state; every answer is fixed data or computed from the request.
+import { createHash } from 'node:crypto';
+import type { Semantics } from '@volter/world-core';
+import { githubNotFound } from '../github-twin.ts';
+import { gh, send } from './shared.ts';
+
+// ── Static meta catalogs (the platform's stateless reference endpoints) ───────────────────
+// GitHub serves these from a fixed, well-known catalog (they are not per-account state). The
+// twin returns a faithful representative subset — vendor-shaped objects, deterministic, never
+// fabricated per-request. (The real catalogs are long; a representative slice is honest here.)
+const GITIGNORE_TEMPLATES = ['Node', 'Python', 'Go', 'Rust', 'Java', 'Ruby', 'C', 'C++', 'VisualStudio'];
+const GITIGNORE_SOURCE: Record<string, string> = {
+  Node: 'node_modules\nnpm-debug.log\n.env\ndist\n',
+  Python: '__pycache__/\n*.py[cod]\n.venv\n.env\n',
+  Go: '*.exe\n*.test\n/vendor/\n',
+};
+const LICENSES = [
+  { key: 'mit', name: 'MIT License', spdx_id: 'MIT' },
+  { key: 'apache-2.0', name: 'Apache License 2.0', spdx_id: 'Apache-2.0' },
+  { key: 'gpl-3.0', name: 'GNU General Public License v3.0', spdx_id: 'GPL-3.0' },
+  { key: 'bsd-3-clause', name: 'BSD 3-Clause "New" or "Revised" License', spdx_id: 'BSD-3-Clause' },
+  { key: 'unlicense', name: 'The Unlicense', spdx_id: 'Unlicense' },
+];
+const EMOJIS: Record<string, string> = {
+  '+1': 'https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png',
+  '-1': 'https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png',
+  smile: 'https://github.githubassets.com/images/icons/emoji/unicode/1f604.png',
+  rocket: 'https://github.githubassets.com/images/icons/emoji/unicode/1f680.png',
+  tada: 'https://github.githubassets.com/images/icons/emoji/unicode/1f389.png',
+  eyes: 'https://github.githubassets.com/images/icons/emoji/unicode/1f440.png',
+  heart: 'https://github.githubassets.com/images/icons/emoji/unicode/2764.png',
+};
+/** A .gitignore template's text, by its name (any case); undefined for a name the catalog lacks. */
+export function gitignoreTemplate(name: string): string | undefined {
+  const found = GITIGNORE_TEMPLATES.find((t) => t.toLowerCase() === name.toLowerCase());
+  return found && (GITIGNORE_SOURCE[found] ?? `# ${found} .gitignore\n`);
+}
+// The license texts GitHub serves, [year] and [fullname] left for whoever copies them in: MIT's is the body
+// docs.github.com/rest/licenses/licenses#get-a-license shows (its example's leading blank lines dropped). Where the
+// documentation stops: the other catalog licenses keep their name alone.
+const LICENSE_TEXTS: Record<string, string> = {
+  mit: 'The MIT License (MIT)\n\nCopyright (c) [year] [fullname]\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n',
+};
+/** A license's text, by its key (any case); undefined for a key the catalog lacks. Given a holder, its placeholders are
+ *  filled as the license's implementation note says: [year] with the year and [fullname] with the copyright holder. */
+export function licenseTemplate(key: string, fill?: { year: string; fullname: string }): string | undefined {
+  const found = LICENSES.find((l) => l.key === key.toLowerCase());
+  if (!found) return undefined;
+  const text = LICENSE_TEXTS[found.key] ?? `${found.name}\n`;
+  return fill ? text.replaceAll('[year]', fill.year).replaceAll('[fullname]', fill.fullname) : text;
+}
+function licenseToRest(l: (typeof LICENSES)[number]): Record<string, unknown> {
+  return { key: l.key, name: l.name, spdx_id: l.spdx_id, url: `https://api.github.com/licenses/${l.key}`, node_id: createHash('sha256').update(`license:${l.key}`).digest('base64').slice(0, 16), html_url: `https://choosealicense.com/licenses/${l.key}/` };
+}
+// A minimal-but-faithful GitHub-Flavored-Markdown renderer for POST /markdown. GitHub returns
+// rendered HTML; the twin supports the common inline/block forms (headings, bold, italic,
+// inline code, links) deterministically. Not a full CommonMark engine — a faithful subset.
+function renderMarkdown(text: string): string {
+  const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  const inline = (s: string) =>
+    esc(s)
+      .replace(/`([^`]+)`/g, '<code>$1</code>')
+      .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+      .replace(/\*([^*]+)\*/g, '<em>$1</em>')
+      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  const out: string[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trimEnd();
+    if (!line) continue;
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) { const lvl = h[1]!.length; out.push(`<h${lvl}>${inline(h[2]!)}</h${lvl}>`); continue; }
+    out.push(`<p>${inline(line)}</p>`);
+  }
+  return out.join('\n');
+}
+
+export function metaSemantics(_opts: { readOnly?: boolean }): Record<string, Semantics> {
+  const metaRoot: Semantics = async (ctx) => {
+    const a = 'https://api.github.com';
+    return ctx.reply({
+      current_user_url: `${a}/user`, current_user_authorizations_html_url: 'https://github.com/settings/connections/applications{/client_id}',
+      authorizations_url: `${a}/authorizations`, code_search_url: `${a}/search/code?q={query}{&page,per_page,sort,order}`,
+      commit_search_url: `${a}/search/commits?q={query}{&page,per_page,sort,order}`, emails_url: `${a}/user/emails`, emojis_url: `${a}/emojis`,
+      events_url: `${a}/events`, feeds_url: `${a}/feeds`, followers_url: `${a}/user/followers`, following_url: `${a}/user/following{/target}`,
+      gists_url: `${a}/gists{/gist_id}`, hub_url: `${a}/hub`, issue_search_url: `${a}/search/issues?q={query}{&page,per_page,sort,order}`,
+      issues_url: `${a}/issues`, keys_url: `${a}/user/keys`, label_search_url: `${a}/search/labels?q={query}&repository_id={repository_id}{&page,per_page}`,
+      notifications_url: `${a}/notifications`, organization_url: `${a}/orgs/{org}`, organization_repositories_url: `${a}/orgs/{org}/repos{?type,page,per_page,sort}`,
+      organization_teams_url: `${a}/orgs/{org}/teams`, public_gists_url: `${a}/gists/public`, rate_limit_url: `${a}/rate_limit`,
+      repository_url: `${a}/repos/{owner}/{repo}`, repository_search_url: `${a}/search/repositories?q={query}{&page,per_page,sort,order}`,
+      current_user_repositories_url: `${a}/user/repos{?type,page,per_page,sort}`, starred_url: `${a}/user/starred{/owner}{/repo}`,
+      starred_gists_url: `${a}/gists/starred`, topic_search_url: `${a}/search/topics?q={query}{&page,per_page}`, user_url: `${a}/users/{user}`,
+      user_organizations_url: `${a}/user/orgs`, user_repositories_url: `${a}/users/{user}/repos{?type,page,per_page,sort}`,
+      user_search_url: `${a}/search/users?q={query}{&page,per_page,sort,order}`,
+    });
+  };
+  const rateLimitGet: Semantics = async (ctx) => {
+    const reset = 4102444800; // 2100-01-01T00:00:00Z — a stable, far-future sentinel.
+    const bucket = (limit: number) => ({ limit, used: 0, remaining: limit, reset });
+    const resources = { core: bucket(5000), search: bucket(30), graphql: bucket(5000), integration_manifest: bucket(5000), code_scanning_upload: bucket(500) };
+    return ctx.reply({ resources, rate: resources.core });
+  };
+  const gitignoreGetTemplate: Semantics = async (ctx) => {
+    const name = GITIGNORE_TEMPLATES.find((t) => t.toLowerCase() === decodeURIComponent(gh(ctx).seg[2]!).toLowerCase());
+    if (!name) return send(ctx, githubNotFound());
+    return ctx.reply({ name, source: gitignoreTemplate(name) });
+  };
+  const licensesGet: Semantics = async (ctx) => {
+    const l = LICENSES.find((x) => x.key === decodeURIComponent(gh(ctx).seg[1]!).toLowerCase());
+    if (!l) return send(ctx, githubNotFound());
+    return ctx.reply({ ...licenseToRest(l), description: `${l.name}.`, permissions: [], conditions: [], limitations: [], body: licenseTemplate(l.key), featured: l.key === 'mit' });
+  };
+  const markdownRender: Semantics = async (ctx) => {
+    const { body } = gh(ctx);
+    if (typeof body.text !== 'string') return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Markdown', field: 'text', code: 'missing_field' }] }, 422);
+    return ctx.reply(renderMarkdown(body.text));
+  };
+  return {
+    // the twin's own root: which service this is and whether it takes writes
+    // the API's root: the URL templates of its resources, as api.github.com answers (docs.github.com/rest/meta/meta#github-api-root)
+    'meta/root': metaRoot,
+    // Rate limit: the twin is local + unmetered, so it reports a faithful full-budget envelope
+    // in GitHub's exact {resources:{core,search,...}, rate} shape. The reset is a fixed sentinel
+    // (deterministic — never Date.now()).
+    'rate-limit/get': rateLimitGet,
+    'gitignore/get-all-templates': async (ctx) => ctx.reply(GITIGNORE_TEMPLATES),
+    'gitignore/get-template': gitignoreGetTemplate,
+    'licenses/get-all-commonly-used': async (ctx) => ctx.reply(LICENSES.map(licenseToRest)),
+    'licenses/get': licensesGet,
+    // the named-emoji → asset-URL map
+    'emojis/get': async (ctx) => ctx.reply(EMOJIS),
+    // the platform's service metadata envelope
+    'meta/get': async (ctx) => ctx.reply({ verifiable_password_authentication: false, ssh_key_fingerprints: {}, hooks: [], web: [], api: [], git: [], packages: [], pages: [], importer: [], actions: [], dependabot: [] }),
+    // Render Markdown to HTML (GitHub returns text/html). The twin renders a faithful GFM subset
+    // deterministically; `text` is required (422 when absent, like GitHub).
+    'markdown/render': markdownRender,
+  };
+}

package/src/semantics/notifications.ts

@@ -0,0 +1,58 @@
+// The notifications GitHub sends the signed-in person (the World's user): when someone else @mentions them, assigns
+// them, asks for their review, or comments on or reviews their issue or pull request, the thread for that issue or pull
+// request is unread in their inbox with the reason (docs.github.com/account-and-profile/managing-subscriptions-and-
+// notifications-on-github/setting-up-notifications/about-notifications#reasons-for-receiving-notifications). One
+// thread per issue or pull request: a new reason on it marks it unread again. The person's own acts notify no one.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+import { GITHUB_WORLD_USER, type GithubWriteEvent } from '../github-twin.ts';
+import { gh, put } from './shared.ts';
+
+const loginOf = (u: unknown): string | undefined => (u && typeof u === 'object' ? ((u as { login?: unknown }).login as string | undefined) : undefined);
+const mentions = (text: unknown, login: string): boolean => typeof text === 'string' && new RegExp(`(^|[^\\w-])@${login}\\b`, 'i').test(text);
+
+/** Whether a review request names the World's user. */
+function reviewRequestedOf(event: GithubWriteEvent, me: string): boolean {
+  const requested = (event.pr?.requested_reviewers as unknown[] | undefined) ?? [];
+  return requested.some((r) => (typeof r === 'string' ? r : loginOf(r)) === me);
+}
+/** Why an event notifies the World's user, or nothing. */
+function reasonFor(event: GithubWriteEvent, me: string, author: string | null | undefined): string | undefined {
+  const text = event.comment?.body ?? event.review?.body ?? event.issue?.body ?? event.body;
+  if (mentions(text, me)) return 'mention';
+  if (event.event === 'pull_request' && event.action === 'review_requested' && reviewRequestedOf(event, me)) return 'review_requested';
+  if (event.event === 'issues' && (event.action === 'opened' || event.action === 'assigned' || event.action === 'edited')) {
+    const assignees = (event.issue?.assignees as unknown[] | undefined) ?? [];
+    if (assignees.some((a) => loginOf(a) === me)) return 'assign';
+  }
+  if ((event.event === 'issue_comment' || event.event === 'pull_request_review') && author === me) return 'author';
+  return undefined;
+}
+
+/** The thread an event puts in the World's user's inbox, when it concerns them and someone else did it. */
+export async function notify(ctx: SemanticsContext, event: GithubWriteEvent): Promise<void> {
+  const { caller, state } = gh(ctx);
+  const me = GITHUB_WORLD_USER;
+  if (!caller || caller === me || !event.number) return;
+  const st = state();
+  const pr = st.prs.find((p) => p.repository === event.repository && Number(p.number) === event.number);
+  const issue = st.issues.find((i) => i.repository === event.repository && Number(i.number) === event.number);
+  const author = pr?.user_login ?? (issue as { user_login?: string | null } | undefined)?.user_login ?? undefined;
+  const reason = reasonFor(event, me, author);
+  if (!reason) return;
+  const isPull = Boolean(pr) || event.event.startsWith('pull_request');
+  const id = String(parseInt(createHash('sha256').update(`${event.repository}#${event.number}`).digest('hex').slice(0, 8), 16));
+  // an ignored thread stays quiet; an unsubscribed one until the next @mention, which subscribes the person again
+  const thread = st.notifications.find((n) => n.id === id);
+  if (thread?.subscription?.ignored) return;
+  if (thread?.subscription === null && reason !== 'mention') return;
+  await put(ctx, {
+    operation: 'notification.create', subjectType: 'notification', subjectId: `notification:${id}`,
+    fields: {
+      id, repository: event.repository, subject_title: String(pr?.title ?? issue?.title ?? `#${event.number}`),
+      subject_type: isPull ? 'PullRequest' : 'Issue', subject_url: `https://api.github.com/repos/${event.repository}/${isPull ? 'pulls' : 'issues'}/${event.number}`,
+      reason, unread: true, updated_at: ctx.occurredAt,
+      ...(thread?.subscription === null ? { subscription: { subscribed: true, ignored: false, created_at: ctx.occurredAt } } : {}),
+    },
+  });
+}

package/src/semantics/orgs.ts

@@ -0,0 +1,383 @@
+// GitHub's organizations family: an organization's profile, members and memberships, outside
+// collaborators, organization webhooks, issue types, its repositories, and teams (their members and
+// repository grants). A bare organization is auto-vivified by its first edit (the twin cannot observe
+// the enterprise flow that creates one). Team discussions, which GitHub no longer publishes, stay on
+// the hand-written route.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  GITHUB_WORLD_USER, githubNotFound, paginate, seedUser, toGithubIssueType, toGithubOrg, toGithubOrgMembership, toGithubOrgWebhook, toGithubRepo, toGithubTeam, toGithubTeamMembership, toGithubUser, twinUserId,
+  type GithubRepo, type GithubTeam, type GithubState } from '../github-twin.ts';
+import { asView, gh, nextSeq, put, send, type Gh } from './shared.ts';
+
+const invalid = (ctx: SemanticsContext, resource: string, field: string, code: string, documentation_url?: string): Response =>
+  ctx.reply({ message: 'Validation Failed', errors: [{ resource, field, code }], ...(documentation_url ? { documentation_url } : {}) }, 422);
+
+// GitHub's team-name → slug derivation (lowercase, non-alphanum → '-', collapse/trim dashes).
+function slugifyTeamName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').replace(/-+/g, '-');
+}
+
+/** The team a path under /orgs/:org/teams/:slug names, or nothing. */
+function teamOf(g: Gh): { org: string; slug: string; team: GithubTeam | undefined } {
+  const org = decodeURIComponent(g.seg[1]!);
+  const slug = decodeURIComponent(g.seg[3]!);
+  return { org, slug, team: g.state().teams.find((t) => t.org === org && t.slug === slug) };
+}
+
+/** A read or write under a team: Not Found when the team does not exist. */
+const underTeam = (serve: (ctx: SemanticsContext, g: Gh, org: string, slug: string, team: GithubTeam) => Promise<Response>): Semantics => async (ctx) => {
+  const g = gh(ctx);
+  const { org, slug, team } = teamOf(g);
+  return team ? serve(ctx, g, org, slug, team) : send(ctx, githubNotFound());
+};
+
+async function removeOrgMember(ctx: SemanticsContext): Promise<Response> {
+  const { seg, state } = gh(ctx);
+  const org = decodeURIComponent(seg[1]!); const login = decodeURIComponent(seg[3]!);
+  if (!state().orgMembers.some((m) => m.org === org && m.login === login)) return send(ctx, githubNotFound());
+  await put(ctx, { operation: 'org_membership.remove', subjectType: 'org_membership', subjectId: `orgmember:${org}#${login}`, fields: { deleted: true, org, login } });
+  return send(ctx, { status: 204, body: undefined });
+}
+
+/** Edit an issue type (GitHub's PUT; the hand-written route keeps the PATCH it also answered). */
+async function updateIssueType(ctx: SemanticsContext): Promise<Response> {
+  const { seg, body, occurredAt, state } = gh(ctx);
+  const org = decodeURIComponent(seg[1]!); const id = Number(decodeURIComponent(seg[3]!));
+  const existing = state().issueTypes.find((t) => t.org === org && t.id === id);
+  if (!existing) return send(ctx, githubNotFound());
+  // the update is a PUT: name and is_enabled are required, as on create (docs.github.com/rest/orgs/issue-types)
+  if (!body.name) return invalid(ctx, 'IssueType', 'name', 'missing_field');
+  if (typeof body.is_enabled !== 'boolean') return invalid(ctx, 'IssueType', 'is_enabled', 'missing_field');
+  const fields: Record<string, unknown> = { org, name: existing.name, description: existing.description, color: existing.color, is_enabled: existing.is_enabled, created_at: existing.created_at, updated_at: occurredAt };
+  for (const k of ['name', 'description', 'color'] as const) if (body[k] !== undefined) fields[k] = body[k];
+  if (body.is_enabled !== undefined) fields.is_enabled = body.is_enabled !== false;
+  await put(ctx, { operation: 'issue_type.update', subjectType: 'issue_type', subjectId: `issuetype:${id}`, fields });
+  return ctx.reply(toGithubIssueType(state().issueTypes.find((x) => x.org === org && x.id === id)!));
+}
+
+/** An organization's outside collaborators: people with access to one of its repositories who are not its members,
+ *  and members it converted (docs.github.com/organizations/managing-user-access-to-your-organizations-repositories). */
+function outsideOf(st: GithubState, org: string): string[] {
+  const members = new Set(st.orgMembers.filter((m) => m.org === org && m.state === 'active').map((m) => m.login));
+  const logins = new Set([...st.outsideCollaborators.filter((c) => c.org === org).map((c) => c.login), ...st.collaborators.filter((c) => c.repository.startsWith(`${org}/`)).map((c) => c.login)]);
+  return [...logins].filter((l) => !members.has(l)).sort();
+}
+
+export function orgsSemantics(): Record<string, Semantics> {
+  const orgsGet: Semantics = async (ctx) => {
+    const { seg, caller, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    const st = state();
+    const o = st.orgs.find((x) => x.login === login);
+    if (!o) return send(ctx, githubNotFound());
+    // GitHub reports the two-factor requirement only to the organization's owners.
+    const owner = !!caller && st.orgMembers.some((m) => m.org === login && m.login === caller && m.role === 'admin' && (m.state ?? 'active') === 'active');
+    return ctx.reply({ ...toGithubOrg(o, st), ...(owner ? { two_factor_requirement_enabled: o.two_factor_requirement_enabled === true } : {}) });
+  };
+  const orgsUpdate: Semantics = async (ctx) => {
+    const { seg, body, occurredAt, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    const prev = state().orgs.find((o) => o.login === login);
+    // an organization is created on github.com (the twin's door, POST /_twin/orgs), never by an edit
+    if (!prev) return send(ctx, githubNotFound());
+    const fields: Record<string, unknown> = { login, updated_at: occurredAt, created_at: prev.created_at ?? occurredAt };
+    for (const k of ['description', 'name', 'company', 'blog', 'location', 'email', 'billing_email'] as const) if (body[k] !== undefined) fields[k] = body[k];
+    await put(ctx, { operation: 'organization.update', subjectType: 'organization', subjectId: `org:${login}`, fields });
+    return ctx.reply(toGithubOrg(state().orgs.find((x) => x.login === login)!, state()));
+  };
+  const orgsListMembers: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const role = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('role') ?? 'all';
+    if (!['all', 'admin', 'member'].includes(role)) return invalid(ctx, 'Organization', 'role', 'invalid', 'https://docs.github.com/rest/orgs/members#list-organization-members');
+    const members = state().orgMembers.filter((m) => m.org === org && m.state === 'active' && (role === 'all' || m.role === role));
+    return ctx.reply(paginate(members, query).map((m) => asView('simple-user', toGithubUser(seedUser(m.login)))));
+  };
+  const orgsCheckMembershipForUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const m = state().orgMembers.find((x) => x.org === org && x.login === decodeURIComponent(seg[3]!) && x.state === 'active');
+    return send(ctx, m ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const orgsGetMembershipForUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const login = decodeURIComponent(seg[3]!);
+    const m = state().orgMembers.find((x) => x.org === org && x.login === login);
+    return send(ctx, m ? { status: 200, body: toGithubOrgMembership(m) } : githubNotFound());
+  };
+  const orgsListPendingInvitations: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const pending = state().orgMembers.filter((m) => m.org === org && m.state === 'pending');
+    return ctx.reply(paginate(pending, query).map((m) => ({
+      id: twinUserId(`${org}#${m.login}`), node_id: null, login: m.login, email: null, role: m.role === 'admin' ? 'admin' : 'direct_member',
+      created_at: m.created_at ?? null, failed_at: null, failed_reason: null, inviter: toGithubUser(seedUser(GITHUB_WORLD_USER)), team_count: 0,
+      invitation_teams_url: `https://api.github.com/organizations/${org}/invitations/${m.login}/teams`, invitation_source: 'member',
+    })));
+  };
+  const orgsListMembershipsForAuthenticatedUser: Semantics = async (ctx) => {
+    const { caller, query, state } = gh(ctx);
+    const me = caller ?? GITHUB_WORLD_USER;
+    const wanted = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('state');
+    return ctx.reply(paginate(state().orgMembers.filter((m) => m.login === me && (!wanted || m.state === wanted)), query).map(toGithubOrgMembership));
+  };
+  const orgsGetMembershipForAuthenticatedUser: Semantics = async (ctx) => {
+    const { caller, seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[3]!);
+    const m = state().orgMembers.find((x) => x.org === org && x.login === (caller ?? GITHUB_WORLD_USER));
+    return send(ctx, m ? { status: 200, body: toGithubOrgMembership(m) } : githubNotFound());
+  };
+  const orgsListOutsideCollaborators: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(outsideOf(state(), org), query).map((login) => asView('simple-user', toGithubUser(seedUser(login)))));
+  };
+  const orgsConvertMemberToOutsideCollaborator: Semantics = async (ctx) => {
+    const { seg } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const login = decodeURIComponent(seg[3]!);
+    await put(ctx, { operation: 'outside_collaborator.add', subjectType: 'outside_collaborator', subjectId: `outsidecollab:${org}#${login}`, fields: { org, login } });
+    // they are no longer a member, nor on its teams; the repositories they worked in stay theirs
+    const st = gh(ctx).state();
+    const membership = st.orgMembers.find((m) => m.org === org && m.login === login);
+    if (membership) await put(ctx, { operation: 'org_membership.remove', subjectType: 'org_membership', subjectId: `orgmember:${org}#${login}`, fields: { ...membership, deleted: true } });
+    for (const t of st.teamMembers.filter((m) => m.org === org && m.login === login)) {
+      await put(ctx, { operation: 'team_membership.remove', subjectType: 'team_membership', subjectId: `teammember:${org}#${t.team_slug}#${login}`, fields: { ...t, deleted: true } });
+    }
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const orgsRemoveOutsideCollaborator: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const login = decodeURIComponent(seg[3]!);
+    const st = state();
+    if (!outsideOf(st, org).includes(login)) return send(ctx, githubNotFound());
+    if (st.outsideCollaborators.some((c) => c.org === org && c.login === login)) await put(ctx, { operation: 'outside_collaborator.remove', subjectType: 'outside_collaborator', subjectId: `outsidecollab:${org}#${login}`, fields: { deleted: true, org, login } });
+    for (const c of st.collaborators.filter((x) => x.login === login && x.repository.startsWith(`${org}/`))) {
+      await put(ctx, { operation: 'collaborator.remove', subjectType: 'collaborator', subjectId: `collab:${c.repository}#${login}`, fields: { deleted: true, repository: c.repository, login } });
+    }
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const orgsListWebhooks: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().orgWebhooks.filter((h) => h.org === org), query).map(toGithubOrgWebhook));
+  };
+  const orgsGetWebhook: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const h = state().orgWebhooks.find((x) => x.org === org && x.id === Number(decodeURIComponent(seg[3]!)));
+    return send(ctx, h ? { status: 200, body: toGithubOrgWebhook(h) } : githubNotFound());
+  };
+  const orgsCreateWebhook: Semantics = async (ctx) => {
+    const { seg, body, occurredAt, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const cfg = (body.config ?? {}) as Record<string, any>;
+    if (!cfg.url) return invalid(ctx, 'Hook', 'config', 'missing_field');
+    const seq = nextSeq(ctx, 'orghook');
+    const fields = { org, active: body.active !== false, events: Array.isArray(body.events) ? body.events : ['push'], url: String(cfg.url), content_type: cfg.content_type ?? 'form', created_at: occurredAt, updated_at: occurredAt };
+    await put(ctx, { operation: 'org_webhook.create', subjectType: 'org_webhook', subjectId: `orghook:${seq}`, fields });
+    return ctx.reply(toGithubOrgWebhook(state().orgWebhooks.find((x) => x.org === org && x.id === seq)!), 201);
+  };
+  const orgsUpdateWebhook: Semantics = async (ctx) => {
+    const { seg, body, occurredAt, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const id = Number(decodeURIComponent(seg[3]!));
+    const existing = state().orgWebhooks.find((h) => h.org === org && h.id === id);
+    if (!existing) return send(ctx, githubNotFound());
+    const cfg = (body.config ?? {}) as Record<string, any>;
+    const fields: Record<string, unknown> = { org, created_at: existing.created_at, updated_at: occurredAt, url: existing.url, content_type: existing.content_type, events: existing.events, active: existing.active };
+    if (body.active !== undefined) fields.active = body.active !== false;
+    if (Array.isArray(body.events)) fields.events = body.events;
+    if (cfg.url !== undefined) fields.url = String(cfg.url);
+    if (cfg.content_type !== undefined) fields.content_type = cfg.content_type;
+    await put(ctx, { operation: 'org_webhook.update', subjectType: 'org_webhook', subjectId: `orghook:${id}`, fields });
+    return ctx.reply(toGithubOrgWebhook(state().orgWebhooks.find((x) => x.org === org && x.id === id)!));
+  };
+  const orgsDeleteWebhook: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const id = Number(decodeURIComponent(seg[3]!));
+    if (!state().orgWebhooks.find((h) => h.org === org && h.id === id)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'org_webhook.delete', subjectType: 'org_webhook', subjectId: `orghook:${id}`, fields: { deleted: true, org } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const orgsListIssueTypes: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().issueTypes.filter((t) => t.org === org), query).map(toGithubIssueType));
+  };
+  const orgsCreateIssueType: Semantics = async (ctx) => {
+    const { seg, body, occurredAt, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    // name and is_enabled are required (docs.github.com/rest/orgs/issue-types#create-issue-type-for-an-organization)
+    if (!body.name) return invalid(ctx, 'IssueType', 'name', 'missing_field');
+    if (typeof body.is_enabled !== 'boolean') return invalid(ctx, 'IssueType', 'is_enabled', 'missing_field');
+    if (state().issueTypes.some((t) => t.org === org && t.name === String(body.name))) return invalid(ctx, 'IssueType', 'name', 'already_exists');
+    const seq = nextSeq(ctx, 'issuetype');
+    const fields = { org, name: String(body.name), description: body.description ?? null, color: body.color ?? null, is_enabled: body.is_enabled, created_at: occurredAt, updated_at: occurredAt };
+    await put(ctx, { operation: 'issue_type.create', subjectType: 'issue_type', subjectId: `issuetype:${seq}`, fields });
+    return ctx.reply(toGithubIssueType(state().issueTypes.find((x) => x.org === org && x.name === String(body.name))!));
+  };
+  const orgsDeleteIssueType: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!); const id = Number(decodeURIComponent(seg[3]!));
+    if (!state().issueTypes.find((t) => t.org === org && t.id === id)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'issue_type.delete', subjectType: 'issue_type', subjectId: `issuetype:${id}`, fields: { deleted: true, org } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const reposListForOrg: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    const params = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+    let items = state().repos.filter((r) => r.owner === org);
+    const type = params.get('type');
+    if (type === 'public') items = items.filter((r) => !(r.private ?? false));
+    else if (type === 'private') items = items.filter((r) => r.private ?? false);
+    else if (type === 'forks') items = items.filter((r) => r.fork ?? false);
+    else if (type === 'sources') items = items.filter((r) => !(r.fork ?? false));
+    const sort = params.get('sort');
+    if (sort === 'full_name') items = [...items].sort((a, b) => (a.full_name < b.full_name ? -1 : 1));
+    else if (sort === 'created') items = [...items].sort((a, b) => ((a.created_at ?? '') < (b.created_at ?? '') ? 1 : -1));
+    else if (sort === 'updated') items = [...items].sort((a, b) => ((a.updated_at ?? '') < (b.updated_at ?? '') ? 1 : -1));
+    return ctx.reply(paginate(items, query).map(toGithubRepo));
+  };
+  const teamsList: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const org = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().teams.filter((t) => t.org === org), query).map((t) => asView('team', toGithubTeam(t))));
+  };
+  const teamsUpdateInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug, existing) => {
+    const fields: Record<string, unknown> = { org, slug, name: existing.name, description: existing.description, privacy: existing.privacy, permission: existing.permission, created_at: existing.created_at, updated_at: g.occurredAt };
+    for (const k of ['name', 'description', 'privacy', 'permission'] as const) if (g.body[k] !== undefined) fields[k] = g.body[k];
+    await put(ctx, { operation: 'team.update', subjectType: 'team', subjectId: `team:${existing.id}`, fields });
+    return ctx.reply(toGithubTeam(g.state().teams.find((x) => x.org === org && x.slug === slug)!, g.state()));
+  }))(ctx);
+  const teamsDeleteInOrg: Semantics = (ctx) => (underTeam(async (ctx, _g, org, _slug, existing) => {
+    await put(ctx, { operation: 'team.delete', subjectType: 'team', subjectId: `team:${existing.id}`, fields: { deleted: true, org } });
+    return send(ctx, { status: 204, body: undefined });
+  }))(ctx);
+  const teamsListMembersInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug) => {
+    const role = new URLSearchParams((g.query ?? '').replace(/^\?/, '')).get('role') ?? 'all';
+    if (!['all', 'member', 'maintainer'].includes(role)) return invalid(ctx, 'Team', 'role', 'invalid', 'https://docs.github.com/rest/teams/members#list-team-members');
+    const members = g.state().teamMembers.filter((m) => m.org === org && m.team_slug === slug && (m.state ?? 'active') === 'active' && (role === 'all' || m.role === role));
+    return ctx.reply(paginate(members, g.query).map((m) => asView('team-member', toGithubUser(seedUser(m.login)))));
+  }))(ctx);
+  const teamsRemoveMembershipForUserInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug) => {
+    const login = decodeURIComponent(g.seg[5]!);
+    if (!g.state().teamMembers.some((m) => m.org === org && m.team_slug === slug && m.login === login)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'team_membership.remove', subjectType: 'team_membership', subjectId: `teammember:${org}#${slug}#${login}`, fields: { deleted: true, org, team_slug: slug, login } });
+    return send(ctx, { status: 204, body: undefined });
+  }))(ctx);
+  const teamsListReposInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug) => {
+    const st = g.state();
+    const items = st.teamRepos.filter((x) => x.org === org && x.team_slug === slug).map((t) => st.repos.find((r) => r.full_name === t.repository)).filter((r): r is GithubRepo => !!r);
+    return ctx.reply(paginate(items, g.query).map(toGithubRepo));
+  }))(ctx);
+  const teamsCheckPermissionsForRepoInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug) => {
+    const repo = `${decodeURIComponent(g.seg[5]!)}/${decodeURIComponent(g.seg[6]!)}`;
+    return send(ctx, g.state().teamRepos.find((x) => x.org === org && x.team_slug === slug && x.repository === repo) ? { status: 204, body: undefined } : githubNotFound());
+  }))(ctx);
+  const teamsRemoveRepoInOrg: Semantics = (ctx) => (underTeam(async (ctx, g, org, slug) => {
+    const repo = `${decodeURIComponent(g.seg[5]!)}/${decodeURIComponent(g.seg[6]!)}`;
+    if (!g.state().teamRepos.some((x) => x.org === org && x.team_slug === slug && x.repository === repo)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'team_repo.remove', subjectType: 'team_repo', subjectId: `teamrepo:${org}#${slug}#${repo}`, fields: { deleted: true, org, team_slug: slug, repository: repo } });
+    return send(ctx, { status: 204, body: undefined });
+  }))(ctx);
+  return {
+    'orgs/get': orgsGet,
+    'orgs/update': orgsUpdate,
+    // `role` filters as GitHub does: all (the default), admin or member; any other value is a validation error.
+    'orgs/list-members': orgsListMembers,
+    // 204 member / 404 not
+    'orgs/check-membership-for-user': orgsCheckMembershipForUser,
+    'orgs/remove-member': removeOrgMember,
+    'orgs/get-membership-for-user': orgsGetMembershipForUser,
+    // Invite or set a role (docs.github.com/rest/orgs/members#set-organization-membership-for-a-user): someone not
+    // yet a member is invited, pending until they accept (PATCH /user/memberships/orgs/{org}); a member's role
+    // changes in place.
+    'orgs/set-membership-for-user': async (ctx) => {
+      const { seg, body, occurredAt, state } = gh(ctx);
+      const org = decodeURIComponent(seg[1]!); const login = decodeURIComponent(seg[3]!);
+      if (body.role !== undefined && body.role !== 'admin' && body.role !== 'member') return invalid(ctx, 'Membership', 'role', 'invalid', 'https://docs.github.com/rest/orgs/members#set-organization-membership-for-a-user');
+      const role = body.role === 'admin' ? 'admin' : 'member';
+      const prior = state().orgMembers.find((x) => x.org === org && x.login === login);
+      await put(ctx, { operation: 'org_membership.upsert', subjectType: 'org_membership', subjectId: `orgmember:${org}#${login}`, fields: { org, login, role, state: prior?.state ?? 'pending', created_at: prior?.created_at ?? occurredAt } });
+      return ctx.reply(toGithubOrgMembership(state().orgMembers.find((x) => x.org === org && x.login === login)!));
+    },
+    // the invitations waiting on their invitee (docs.github.com/rest/orgs/members#list-pending-organization-invitations)
+    'orgs/list-pending-invitations': orgsListPendingInvitations,
+    // the signed-in person's own memberships, and accepting an invitation: state 'active' is the only one accepted
+    // (docs.github.com/rest/orgs/members#update-an-organization-membership-for-the-authenticated-user)
+    'orgs/list-memberships-for-authenticated-user': orgsListMembershipsForAuthenticatedUser,
+    'orgs/get-membership-for-authenticated-user': orgsGetMembershipForAuthenticatedUser,
+    'orgs/update-membership-for-authenticated-user': async (ctx) => {
+      const { caller, seg, body, state } = gh(ctx);
+      const org = decodeURIComponent(seg[3]!); const me = caller ?? GITHUB_WORLD_USER;
+      const m = state().orgMembers.find((x) => x.org === org && x.login === me);
+      if (!m) return send(ctx, githubNotFound());
+      if (body.state !== 'active') return invalid(ctx, 'Membership', 'state', 'invalid', 'https://docs.github.com/rest/orgs/members#update-an-organization-membership-for-the-authenticated-user');
+      await put(ctx, { operation: 'org_membership.upsert', subjectType: 'org_membership', subjectId: `orgmember:${org}#${me}`, fields: { ...m, state: 'active' } });
+      // the teams they were invited to take them in with the organization
+      for (const t of state().teamMembers.filter((x) => x.org === org && x.login === me && x.state === 'pending')) {
+        await put(ctx, { operation: 'team_membership.upsert', subjectType: 'team_membership', subjectId: `teammember:${org}#${t.team_slug}#${me}`, fields: { ...t, state: 'active' } });
+      }
+      return ctx.reply(toGithubOrgMembership(state().orgMembers.find((x) => x.org === org && x.login === me)!));
+    },
+    'orgs/remove-membership-for-user': removeOrgMember,
+    'orgs/list-outside-collaborators': orgsListOutsideCollaborators,
+    'orgs/convert-member-to-outside-collaborator': orgsConvertMemberToOutsideCollaborator,
+    // removing an outside collaborator takes away their access to every repository of the organization
+    'orgs/remove-outside-collaborator': orgsRemoveOutsideCollaborator,
+    'orgs/list-webhooks': orgsListWebhooks,
+    'orgs/get-webhook': orgsGetWebhook,
+    'orgs/create-webhook': orgsCreateWebhook,
+    'orgs/update-webhook': orgsUpdateWebhook,
+    'orgs/delete-webhook': orgsDeleteWebhook,
+    'orgs/list-issue-types': orgsListIssueTypes,
+    'orgs/create-issue-type': orgsCreateIssueType,
+    'orgs/update-issue-type': updateIssueType,
+    'orgs/delete-issue-type': orgsDeleteIssueType,
+    // repositories an org owns; ?type=(all|public|private|forks|sources) and ?sort=(created|updated|full_name)
+    'repos/list-for-org': reposListForOrg,
+    // ── teams ──
+    'teams/list': teamsList,
+    'teams/get-by-name': underTeam(async (ctx, g, _org, _slug, team) => ctx.reply(toGithubTeam(team, g.state()))),
+    'teams/create': async (ctx) => {
+      const { seg, body, occurredAt, state } = gh(ctx);
+      const org = decodeURIComponent(seg[1]!);
+      if (!body.name) return invalid(ctx, 'Team', 'name', 'missing_field');
+      const slug = slugifyTeamName(String(body.name));
+      if (state().teams.some((t) => t.org === org && t.slug === slug)) return invalid(ctx, 'Team', 'name', 'already_exists');
+      const seq = nextSeq(ctx, 'team');
+      const fields = { org, slug, name: String(body.name), description: body.description ?? null, privacy: body.privacy ?? 'secret', permission: body.permission ?? 'pull', created_at: occurredAt, updated_at: occurredAt };
+      await put(ctx, { operation: 'team.create', subjectType: 'team', subjectId: `team:${seq}`, fields });
+      return ctx.reply(toGithubTeam(state().teams.find((x) => x.org === org && x.slug === slug)!, state()), 201);
+    },
+    'teams/update-in-org': teamsUpdateInOrg,
+    'teams/delete-in-org': teamsDeleteInOrg,
+    // `role` filters as GitHub does: all (the default), member or maintainer; only active memberships are listed.
+    'teams/list-members-in-org': teamsListMembersInOrg,
+    'teams/get-membership-for-user-in-org': underTeam(async (ctx, g, org, slug) => {
+      const m = g.state().teamMembers.find((x) => x.org === org && x.team_slug === slug && x.login === decodeURIComponent(g.seg[5]!));
+      return send(ctx, m ? { status: 200, body: toGithubTeamMembership(m, g.state()) } : githubNotFound());
+    }),
+    'teams/add-or-update-membership-for-user-in-org': underTeam(async (ctx, g, org, slug) => {
+      const login = decodeURIComponent(g.seg[5]!);
+      const role = g.body.role === 'maintainer' ? 'maintainer' : 'member';
+      // someone not yet in the organization is invited to it, and their team membership is pending until they accept
+      // (docs.github.com/rest/teams/members#add-or-update-team-membership-for-a-user)
+      const membership = g.state().orgMembers.find((m) => m.org === org && m.login === login);
+      if (!membership) await put(ctx, { operation: 'org_membership.upsert', subjectType: 'org_membership', subjectId: `orgmember:${org}#${login}`, fields: { org, login, role: 'member', state: 'pending', created_at: g.occurredAt } });
+      const state = membership?.state === 'active' ? 'active' : 'pending';
+      await put(ctx, { operation: 'team_membership.upsert', subjectType: 'team_membership', subjectId: `teammember:${org}#${slug}#${login}`, fields: { org, team_slug: slug, login, role, state } });
+      return ctx.reply(toGithubTeamMembership(g.state().teamMembers.find((x) => x.org === org && x.team_slug === slug && x.login === login)!, g.state()));
+    }),
+    'teams/remove-membership-for-user-in-org': teamsRemoveMembershipForUserInOrg,
+    'teams/list-repos-in-org': teamsListReposInOrg,
+    // 204 when the team holds a grant on the repo, else 404
+    'teams/check-permissions-for-repo-in-org': teamsCheckPermissionsForRepoInOrg,
+    'teams/add-or-update-repo-permissions-in-org': underTeam(async (ctx, g, org, slug) => {
+      const repo = `${decodeURIComponent(g.seg[5]!)}/${decodeURIComponent(g.seg[6]!)}`;
+      await put(ctx, { operation: 'team_repo.grant', subjectType: 'team_repo', subjectId: `teamrepo:${org}#${slug}#${repo}`, fields: { org, team_slug: slug, repository: repo, permission: g.body.permission ?? 'pull' } });
+      return send(ctx, { status: 204, body: undefined });
+    }),
+    'teams/remove-repo-in-org': teamsRemoveRepoInOrg,
+  };
+}