@volter/twin-github 0.1.1 → 2.0.0

package/src/semantics/packages.ts

@@ -0,0 +1,59 @@
+// GitHub's packages family, for the authenticated user: list, read and delete packages and their
+// versions, newest version first. Packages are published to GitHub's npm registry (src/npm-registry.ts);
+// the twin's user is `octocat`.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { githubNotFound, paginate, toGithubPackage, toGithubPackageVersion, type GithubPackage, type GithubState } from '../github-twin.ts';
+import { gh, put, send } from './shared.ts';
+
+const versionCount = (st: GithubState, p: GithubPackage): number => st.packageVersions.filter((v) => v.owner === p.owner && v.package_type === p.package_type && v.package_name === p.name).length;
+
+/** A read or write under /user/packages/:type/:name: Not Found when the package does not exist. */
+const underPackage = (serve: (ctx: SemanticsContext, st: GithubState, pkg: GithubPackage, type: string, name: string) => Promise<Response>): Semantics => async (ctx) => {
+  const { seg, state } = gh(ctx);
+  const type = decodeURIComponent(seg[2]!);
+  const name = decodeURIComponent(seg[3]!);
+  const st = state();
+  const pkg = st.packages.find((p) => p.owner === 'octocat' && p.package_type === type && p.name === name);
+  return pkg ? serve(ctx, st, pkg, type, name) : send(ctx, githubNotFound());
+};
+
+export function packagesSemantics(): Record<string, Semantics> {
+  const packagesListPackagesForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    const st = state();
+    const pkgType = new URLSearchParams((query ?? '').replace(/^\?/, '')).get('package_type');
+    let items = st.packages.filter((p) => p.owner === 'octocat');
+    if (pkgType) items = items.filter((p) => p.package_type === pkgType);
+    return ctx.reply(paginate(items, query).map((p) => toGithubPackage(p, versionCount(st, p))));
+  };
+  const packagesDeletePackageForAuthenticatedUser: Semantics = (ctx) => (underPackage(async (ctx, _st, pkg, type, name) => {
+    await put(ctx, { operation: 'package.delete', subjectType: 'package', subjectId: `package:${pkg.id}`, fields: { deleted: true, name } });
+    for (const v of gh(ctx).state().packageVersions.filter((x) => x.owner === 'octocat' && x.package_type === type && x.package_name === name)) {
+      await put(ctx, { operation: 'package_version.delete', subjectType: 'package_version', subjectId: `packageversion:${v.id}`, fields: { deleted: true, package_name: name } });
+    }
+    return send(ctx, { status: 204, body: undefined });
+  }))(ctx);
+  const packagesDeletePackageVersionForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const type = decodeURIComponent(seg[2]!); const name = decodeURIComponent(seg[3]!); const vid = Number(decodeURIComponent(seg[5]!));
+    if (!state().packageVersions.find((x) => x.owner === 'octocat' && x.package_type === type && x.package_name === name && x.id === vid)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'package_version.delete', subjectType: 'package_version', subjectId: `packageversion:${vid}`, fields: { deleted: true, package_name: name } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const packagesGetAllPackageVersionsForPackageOwnedByAuthenticatedUser: Semantics = (ctx) => (underPackage(async (ctx, st, _pkg, type, name) =>
+    ctx.reply(paginate(st.packageVersions.filter((v) => v.owner === 'octocat' && v.package_type === type && v.package_name === name).sort((a, b) => String(b.created_at ?? '').localeCompare(String(a.created_at ?? '')) || b.id - a.id), gh(ctx).query).map(toGithubPackageVersion))))(ctx);
+  const packagesGetPackageVersionForAuthenticatedUser: Semantics = (ctx) => (underPackage(async (ctx, st, _pkg, type, name) => {
+    const vid = Number(decodeURIComponent(gh(ctx).seg[5]!));
+    const v = st.packageVersions.find((x) => x.owner === 'octocat' && x.package_type === type && x.package_name === name && x.id === vid);
+    return send(ctx, v ? { status: 200, body: toGithubPackageVersion(v) } : githubNotFound());
+  }))(ctx);
+  return {
+    'packages/list-packages-for-authenticated-user': packagesListPackagesForAuthenticatedUser,
+    'packages/get-package-for-authenticated-user': underPackage(async (ctx, st, pkg) => ctx.reply(toGithubPackage(pkg, versionCount(st, pkg)))),
+    'packages/get-all-package-versions-for-package-owned-by-authenticated-user': packagesGetAllPackageVersionsForPackageOwnedByAuthenticatedUser,
+    'packages/get-package-version-for-authenticated-user': packagesGetPackageVersionForAuthenticatedUser,
+    // deleting a package deletes its versions
+    'packages/delete-package-for-authenticated-user': packagesDeletePackageForAuthenticatedUser,
+    'packages/delete-package-version-for-authenticated-user': packagesDeletePackageVersionForAuthenticatedUser,
+  };
+}

package/src/semantics/pages.ts

@@ -0,0 +1,154 @@
+// GitHub's Pages family: a repository's Pages site (create, read, update, delete) and its builds. A
+// requested build is recorded built at once (the twin publishes nothing).
+import { createHash } from 'node:crypto';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { GITHUB_WORLD_USER, githubNotFound, paginate, toGithubPagesBuild, toGithubPagesSite } from '../github-twin.ts';
+import { gh, nextSeq, put, send } from './shared.ts';
+import { canWrite } from './push-reactions.ts';
+
+/** POST creates the site (409 when enabled), PUT edits it (404 when not): the source branch and path,
+ *  the custom domain, the build type and HTTPS enforcement. */
+async function writeSite(ctx: SemanticsContext, creating: boolean): Promise<Response> {
+  const { repo, body, occurredAt, state } = gh(ctx);
+  // Pages belongs to a repository: none, no site (docs.github.com/rest/pages/pages#create-a-apiname-pages-site)
+  if (!state().repos.some((r) => r.full_name === repo)) return send(ctx, githubNotFound());
+  const existing = state().pagesSites.find((s) => s.repository === repo);
+  if (creating && existing) return ctx.reply({ message: 'Pages is already enabled for this repository.' }, 409);
+  if (!creating && !existing) return send(ctx, githubNotFound());
+  const src = body.source ?? {};
+  const fields: Record<string, unknown> = { repository: repo, updated_at: occurredAt };
+  if (creating) fields.created_at = occurredAt;
+  if (src.branch !== undefined) fields.source_branch = String(src.branch);
+  if (src.path !== undefined) fields.source_path = String(src.path);
+  // a new custom domain starts its certificate and turns HTTPS enforcement off until it is issued; enforcing it
+  // before then is refused (docs.github.com/pages/getting-started-with-github-pages/securing-your-github-pages-site-with-https)
+  const domainChanged = body.cname !== undefined && body.cname !== (existing?.cname ?? null);
+  if (body.cname !== undefined) fields.cname = body.cname;
+  if (domainChanged) { fields.cert_requested_at = body.cname ? occurredAt : null; fields.https_enforced = false; }
+  if (body.build_type !== undefined) fields.build_type = String(body.build_type);
+  if (body.https_enforced !== undefined) { const refused = enforceHttps(ctx, body, existing, domainChanged, fields); if (refused) return refused; }
+  if (creating) { fields.status = 'building'; if (fields.source_branch === undefined) fields.source_branch = 'main'; if (fields.source_path === undefined) fields.source_path = '/'; }
+  await put(ctx, { operation: creating ? 'pages_site.create' : 'pages_site.update', subjectType: 'pages_site', subjectId: `pages:${repo}`, fields });
+  if (!creating) return send(ctx, { status: 204, body: undefined });
+  return ctx.reply(siteBody(ctx, state().pagesSites.find((s) => s.repository === repo)!), 201);
+}
+
+/** HTTPS enforcement turned on or off: refused while the custom domain's certificate is still being issued. */
+function enforceHttps(ctx: SemanticsContext, body: Record<string, any>, existing: { cname?: string | null; cert_requested_at?: string | null } | undefined, domainChanged: boolean, fields: Record<string, unknown>): Response | undefined {
+  const { occurredAt } = gh(ctx);
+  const cname = domainChanged ? body.cname : existing?.cname;
+  const requested = domainChanged ? occurredAt : existing?.cert_requested_at;
+  if (body.https_enforced === true && cname && certificateState(requested, occurredAt) !== 'approved') {
+    return ctx.reply({ message: 'The certificate does not exist yet', documentation_url: 'https://docs.github.com/rest/pages/pages#update-information-about-a-apiname-pages-site' }, 422);
+  }
+  fields.https_enforced = Boolean(body.https_enforced);
+  return undefined;
+}
+
+// How long a custom domain's certificate takes to issue: GitHub says it can take a while and gives no figure, so
+// fifteen minutes is the twin's; the refusal's wording above is the twin's too.
+const CERT_MS = 15 * 60 * 1000;
+function certificateState(requestedAt: string | undefined | null, now: string): string {
+  return requestedAt && Date.parse(now) - Date.parse(requestedAt) >= CERT_MS ? 'approved' : 'authorization_pending';
+}
+
+/** The site as GitHub answers it: with its custom domain's certificate as the clock finds it. */
+function siteBody(ctx: SemanticsContext, site: ReturnType<Gh['state']>['pagesSites'][number]): Record<string, unknown> {
+  const body = toGithubPagesSite(site);
+  if (!site.cname) return body;
+  const requested = site.cert_requested_at;
+  const state = certificateState(requested, gh(ctx).occurredAt);
+  return {
+    ...body,
+    https_certificate: {
+      state, description: state === 'approved' ? 'The certificate has been approved.' : 'The certificate is being issued.',
+      domains: [site.cname, `www.${site.cname}`], ...(state === 'approved' && requested ? { expires_at: new Date(Date.parse(requested) + 90 * 86_400_000).toISOString().slice(0, 10) } : {}),
+    },
+  };
+}
+
+/** A read under the site's builds: Not Found when Pages is not enabled. */
+const builds = (serve: (ctx: SemanticsContext, list: ReturnType<Gh['state']>['pagesBuilds']) => Response): Semantics => async (ctx) => {
+  const { repo, state } = gh(ctx);
+  const st = state();
+  if (!st.pagesSites.find((s) => s.repository === repo)) return send(ctx, githubNotFound());
+  return serve(ctx, st.pagesBuilds.filter((b) => b.repository === repo));
+};
+type Gh = ReturnType<typeof gh>;
+
+const DEPLOY_DOCS = 'https://docs.github.com/rest/pages/pages#create-a-github-pages-deployment';
+/** A Pages deployment by its id or the build version (a commit sha) it deployed. */
+const deploymentOf = (ctx: SemanticsContext) => {
+  const { repo, seg } = gh(ctx);
+  const key = decodeURIComponent(seg[5]!);
+  return ctx.tree().find((r) => r.type === 'pages_deployment' && r.repository === repo && r.deleted !== true && (String(r.number) === key || r.pages_build_version === key));
+};
+
+export function pagesSemantics(): Record<string, Semantics> {
+  const reposGetPagesDeployment: Semantics = async (ctx) => {
+    const d = deploymentOf(ctx);
+    return send(ctx, d ? { status: 200, body: { status: d.status } } : githubNotFound());
+  };
+  const reposCancelPagesDeployment: Semantics = async (ctx) => {
+    const d = deploymentOf(ctx);
+    return send(ctx, d ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const reposDeletePagesSite: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    if (!state().pagesSites.find((s) => s.repository === repo)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'pages_site.delete', subjectType: 'pages_site', subjectId: `pages:${repo}`, fields: { deleted: true, repository: repo } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const reposGetPagesBuild: Semantics = (ctx) => (builds((ctx, list) => {
+    const id = Number(decodeURIComponent(gh(ctx).seg[5]!));
+    const b = list.find((x) => x.id === id);
+    return send(ctx, b ? { status: 200, body: toGithubPagesBuild(b) } : githubNotFound());
+  }))(ctx);
+  const reposRequestPagesBuild: Semantics = async (ctx) => {
+    const { repo, occurredAt, state } = gh(ctx);
+    if (!state().pagesSites.find((s) => s.repository === repo)) return send(ctx, githubNotFound());
+    const id = nextSeq(ctx, 'pagesbuild');
+    await put(ctx, { operation: 'pages_build.create', subjectType: 'pages_build', subjectId: `pagesbuild:${id}`, fields: { repository: repo, status: 'built', commit: createHash('sha256').update(`${repo}:build:${id}`).digest('hex').slice(0, 40), duration: 1000, created_at: occurredAt } });
+    return ctx.reply({ status: 'queued', url: `https://api.github.com/repos/${repo}/pages/builds/latest` }, 201);
+  };
+  return {
+    // A workflow's deploy step publishes the artifact its upload step made (actions/deploy-pages): with the run's
+    // GITHUB_TOKEN, which needs pages: write, or a person's with write access; pages_build_version and the run's
+    // oidc_token are required, and an artifact_id must name an artifact of the repository
+    // (docs.github.com/rest/pages/pages#create-a-github-pages-deployment). Where the documentation stops and the twin
+    // decides: the deployment succeeds at once and the site is built; the OIDC token is not verified.
+    'repos/create-pages-deployment': async (ctx) => {
+      const { repo, body, token, caller, occurredAt, state } = gh(ctx);
+      const st = state();
+      const site = st.pagesSites.find((x) => x.repository === repo);
+      if (!site) return send(ctx, githubNotFound());
+      const grant = token ? ctx.tree().find((r) => r.type === 'app_token' && r.token === token && r.deleted !== true) : undefined;
+      if (grant ? (grant.permissions as Record<string, string> | undefined)?.pages !== 'write' : !canWrite(st, repo, caller ?? GITHUB_WORLD_USER)) return ctx.reply({ message: 'Resource not accessible by integration', documentation_url: DEPLOY_DOCS }, 403);
+      const absent = (['pages_build_version', 'oidc_token'] as const).filter((k) => !body[k]);
+      if (body.artifact_id === undefined && body.artifact_url === undefined) absent.push('artifact_id' as never);
+      if (absent.length) return ctx.reply({ message: 'Validation Failed', errors: absent.map((field) => ({ resource: 'PagesDeployment', field, code: 'missing_field' })), documentation_url: DEPLOY_DOCS }, 422);
+      if (body.artifact_id !== undefined && !st.actionsArtifacts.some((a) => a.repository === repo && a.id === Number(body.artifact_id))) return send(ctx, githubNotFound());
+      const number = ctx.tree().filter((r) => r.type === 'pages_deployment' && r.repository === repo).length + 1;
+      await put(ctx, { operation: 'pages_deployment.create', subjectType: 'pages_deployment', subjectId: `pagesdeploy:${repo}#${number}`, fields: { repository: repo, number, pages_build_version: String(body.pages_build_version), artifact_id: body.artifact_id ?? null, environment: body.environment ?? 'github-pages', status: 'succeed', created_at: occurredAt } });
+      await put(ctx, { operation: 'pages_site.update', subjectType: 'pages_site', subjectId: `pages:${repo}`, fields: { repository: repo, status: 'built', updated_at: occurredAt } });
+      const page = site.cname ? `https://${site.cname}/` : `https://${repo.split('/')[0]}.github.io/${repo.split('/')[1]}/`;
+      return ctx.reply({ id: number, status_url: `https://api.github.com/repos/${repo}/pages/deployments/${number}`, page_url: page, preview_url: page });
+    },
+    'repos/get-pages-deployment': reposGetPagesDeployment,
+    // a deployment that has finished can no longer be cancelled; the twin's finish at once
+    'repos/cancel-pages-deployment': reposCancelPagesDeployment,
+    'repos/get-pages': async (ctx) => {
+      const { repo, state } = gh(ctx);
+      const site = state().pagesSites.find((s) => s.repository === repo);
+      return send(ctx, site ? { status: 200, body: siteBody(ctx, site) } : githubNotFound());
+    },
+    'repos/create-pages-site': async (ctx) => writeSite(ctx, true),
+    'repos/update-information-about-pages-site': async (ctx) => writeSite(ctx, false),
+    'repos/delete-pages-site': reposDeletePagesSite,
+    'repos/list-pages-builds': builds((ctx, list) => ctx.reply(paginate(list, gh(ctx).query).map(toGithubPagesBuild))),
+    'repos/get-latest-pages-build': builds((ctx, list) => send(ctx, list.length ? { status: 200, body: toGithubPagesBuild(list[0]!) } : githubNotFound())),
+    'repos/get-pages-build': reposGetPagesBuild,
+    // GitHub queues a build (201); the twin records it built
+    'repos/request-pages-build': reposRequestPagesBuild,
+  };
+}

package/src/semantics/projects.ts

@@ -0,0 +1,246 @@
+// GitHub's Projects (v2) family, as GitHub's REST surface addresses a project: by its owner (an organization, or a
+// user by login or by id) and its number. A project is created and closed over GraphQL (semantics/graphql.ts); its
+// fields, items and views are REST's (docs.github.com/rest/projects).
+//
+// Where the documentation stops and the twin decides: a view's `filter` is read as space-separated `field:value`
+// terms (a field's name, a single-select option's name) and `is:issue`, `is:pr`, `is:draft`; any other term is
+// ignored. Adding an item already on the project answers that item, as GraphQL's addProjectV2ItemById does.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  GITHUB_WORLD_USER, githubIssueId, githubNotFound, observedId, paginate, toGithubIssue, toGithubProject, toGithubRest, toSimpleUser, twinUserId,
+  type GithubProject, type GithubProjectField, type GithubProjectItem, type GithubState,
+} from '../github-twin.ts';
+import { asView, gh, nextSeq, put, send } from './shared.ts';
+
+const DATA_TYPES = ['text', 'number', 'date', 'single_select'];
+const COLORS = ['BLUE', 'GRAY', 'GREEN', 'ORANGE', 'PINK', 'PURPLE', 'RED', 'YELLOW'];
+const LAYOUTS = ['table', 'board', 'roadmap'];
+
+const invalid = (ctx: SemanticsContext, resource: string, field: string, code = 'invalid'): Response =>
+  ctx.reply({ message: 'Validation Failed', errors: [{ resource, field, code }], documentation_url: 'https://docs.github.com/rest/projects' }, 422);
+
+/** The project a request names: `/orgs/{org}/…`, `/users/{username}/…`, or a user by id (`/user/{user_id}/…`,
+ *  `/users/{user_id}/…` on the operations GitHub addresses that way). */
+function projectOf(ctx: SemanticsContext): GithubProject | undefined {
+  const { seg, state } = gh(ctx);
+  const byOrg = seg[0] === 'orgs';
+  const byId = ctx.call.operation.id === 'projects/create-draft-item-for-authenticated-user' || ctx.call.operation.id === 'projects/create-view-for-user';
+  const who = decodeURIComponent(seg[1]!);
+  const number = Number(decodeURIComponent(seg[3]!));
+  return state().projects.find((p) => p.number === number && p.owner_type === (byOrg ? 'organization' : 'user')
+    && (byId ? String(twinUserId(p.owner)) === who : p.owner === who));
+}
+
+function projectUrl(p: GithubProject): string {
+  return `https://api.github.com/${p.owner_type === 'organization' ? 'orgs' : 'users'}/${p.owner}/projectsV2/${p.number}`;
+}
+
+function toField(p: GithubProject, f: GithubProjectField): Record<string, unknown> {
+  return {
+    id: f.id, node_id: `PVTF_${f.id}`, project_url: projectUrl(p), name: f.name, data_type: f.data_type,
+    ...(f.options ? { options: f.options.map((o) => ({ id: o.id, name: { raw: o.name, html: o.name }, description: { raw: o.description, html: o.description }, color: o.color })) } : {}),
+    created_at: f.created_at ?? null, updated_at: f.updated_at ?? f.created_at ?? null,
+  };
+}
+
+/** What an item tracks: the issue, the pull request, or the draft's own title and body. */
+function contentOf(st: GithubState, item: GithubProjectItem): Record<string, unknown> | null {
+  if (item.content_type === 'DraftIssue') return draftContent(item);
+  if (item.content_type === 'PullRequest') return pullContent(st, item);
+  const iss = st.issues.find((x) => x.repository === item.content_repository && x.number === item.content_number);
+  return iss ? asView('issue', toGithubIssue(iss, st.milestones, undefined, st.comments)) : null;
+}
+/** A draft item's content: its own title and body. */
+function draftContent(item: GithubProjectItem): Record<string, unknown> {
+  return { id: item.id, node_id: `DI_${item.id}`, title: item.title ?? '', body: item.body ?? null, user: toSimpleUser(item.creator_login ?? GITHUB_WORLD_USER), created_at: item.created_at ?? null, updated_at: item.updated_at ?? null };
+}
+/** A pull request item's content: the pull request. */
+function pullContent(st: GithubState, item: GithubProjectItem): Record<string, unknown> | null {
+  const pr = st.prs.find((x) => x.is_pull_request && x.repository === item.content_repository && x.number === item.content_number);
+  return pr ? asView('pull-request-simple', toGithubRest(pr, st.milestones)) : null;
+}
+
+function toItem(st: GithubState, p: GithubProject, item: GithubProjectItem, withFields: boolean): Record<string, unknown> {
+  const fields = st.projectFields.filter((f) => f.project_id === p.id);
+  return {
+    id: item.id, node_id: `PVTI_${item.id}`, project_url: projectUrl(p), content_type: item.content_type, content: contentOf(st, item),
+    creator: toSimpleUser(item.creator_login ?? GITHUB_WORLD_USER), created_at: item.created_at ?? null, updated_at: item.updated_at ?? item.created_at ?? null,
+    archived_at: null, item_url: `${projectUrl(p)}/items/${item.id}`,
+    ...(withFields ? { fields: fields.filter((f) => item.field_values?.[f.id] !== undefined).map((f) => ({ id: f.id, name: f.name, data_type: f.data_type, value: item.field_values[f.id] })) } : {}),
+  };
+}
+
+/** Whether an item passes a view's filter (see the header for the terms read). */
+function passes(st: GithubState, p: GithubProject, item: GithubProjectItem, filter: string | null | undefined): boolean {
+  const fields = st.projectFields.filter((f) => f.project_id === p.id);
+  for (const term of (filter ?? '').split(/\s+/).filter(Boolean)) {
+    const [key, want] = [term.slice(0, term.indexOf(':')), term.slice(term.indexOf(':') + 1)];
+    if (key === 'is') {
+      const kind = { issue: 'Issue', pr: 'PullRequest', draft: 'DraftIssue' }[want];
+      if (kind && item.content_type !== kind) return false;
+      continue;
+    }
+    const field = fields.find((f) => f.name.toLowerCase() === key.toLowerCase());
+    if (!field) continue;
+    const value = item.field_values?.[field.id];
+    const shown = field.data_type === 'single_select' ? field.options?.find((o) => o.id === value)?.name : value;
+    if (String(shown ?? '').toLowerCase() !== want.toLowerCase()) return false;
+  }
+  return true;
+}
+
+/** Operations on a project that exists, or GitHub's Not Found. */
+const onProject = (run: (ctx: SemanticsContext, p: GithubProject) => Promise<Response>): Semantics => async (ctx) => {
+  const p = projectOf(ctx);
+  return p ? run(ctx, p) : send(ctx, githubNotFound());
+};
+
+const itemOf = (ctx: SemanticsContext, p: GithubProject): GithubProjectItem | undefined =>
+  gh(ctx).state().projectItems.find((i) => i.project_id === p.id && i.id === Number(decodeURIComponent(gh(ctx).seg[5]!)));
+
+const listForOwner = (type: 'organization' | 'user'): Semantics => async (ctx) => {
+  const { seg, query, state } = gh(ctx);
+  const owner = decodeURIComponent(seg[1]!);
+  return ctx.reply(paginate(state().projects.filter((p) => p.owner === owner && p.owner_type === type), query).map(toGithubProject));
+};
+
+const createDraft: Semantics = (ctx) => onProject(async (ctx, p) => {
+  const { body, occurredAt, caller } = gh(ctx);
+  if (typeof body.title !== 'string' || !body.title) return invalid(ctx, 'ProjectV2Item', 'title', 'missing_field');
+  const id = nextSeq(ctx, 'projectitem');
+  await put(ctx, { operation: 'project_item.create', subjectType: 'project_item', subjectId: `projectitem:${id}`, fields: { project_id: p.id, content_type: 'DraftIssue', title: body.title, body: body.body ?? null, field_values: {}, creator_login: caller ?? GITHUB_WORLD_USER, created_at: occurredAt, updated_at: occurredAt } });
+  const st = gh(ctx).state();
+  return ctx.reply(toItem(st, p, st.projectItems.find((i) => i.id === id)!, false), 201);
+})(ctx);
+
+/** A single-select field's options: at least one, each named, with a colour of GitHub's when given. */
+const validOptions = (raw: unknown): boolean => Array.isArray(raw) && raw.length > 0 && !raw.some((o: Record<string, unknown>) => typeof o?.name !== 'string' || (o.color !== undefined && !COLORS.includes(String(o.color))));
+
+const addField = onProject(async (ctx, p) => {
+  const { body, occurredAt, state } = gh(ctx);
+  if (typeof body.name !== 'string' || !body.name) return invalid(ctx, 'ProjectV2Field', 'name', 'missing_field');
+  if (!DATA_TYPES.includes(String(body.data_type))) return invalid(ctx, 'ProjectV2Field', 'data_type');
+  if (state().projectFields.some((f) => f.project_id === p.id && f.name.toLowerCase() === String(body.name).toLowerCase())) return invalid(ctx, 'ProjectV2Field', 'name', 'already_exists');
+  const raw = body.single_select_options;
+  if (body.data_type === 'single_select' && !validOptions(raw)) return invalid(ctx, 'ProjectV2Field', 'single_select_options');
+  const id = nextSeq(ctx, 'projectfield');
+  const options = body.data_type === 'single_select' ? (raw as Array<Record<string, unknown>>).map((o, i) => ({ id: (observedId(`projectfield:${id}:option:${i}`) >>> 0).toString(16).slice(0, 8), name: String(o.name), description: String(o.description ?? ''), color: String(o.color ?? 'GRAY') })) : undefined;
+  await put(ctx, { operation: 'project_field.create', subjectType: 'project_field', subjectId: `projectfield:${id}`, fields: { project_id: p.id, name: body.name, data_type: body.data_type, ...(options ? { options } : {}), created_at: occurredAt, updated_at: occurredAt } });
+  return ctx.reply(toField(p, gh(ctx).state().projectFields.find((f) => f.id === id)!), 201);
+});
+
+const addItem = onProject(async (ctx, p) => {
+  const { body, occurredAt, caller, state } = gh(ctx);
+  if (body.type !== 'Issue' && body.type !== 'PullRequest') return invalid(ctx, 'ProjectV2Item', 'type');
+  const st = state();
+  // by its id, or by its repository and number
+  const target = body.type === 'Issue'
+    ? st.issues.find((i) => (body.id !== undefined ? githubIssueId(i.born_in ?? i.repository, i.number) === Number(body.id) : i.repository === `${String(body.owner)}/${String(body.repo)}` && i.number === Number(body.number)))
+    : st.prs.find((x) => x.is_pull_request && (body.id !== undefined ? observedId(`pull_request:${x.born_in ?? x.repository}#${x.number}`) === Number(body.id) : x.repository === `${String(body.owner)}/${String(body.repo)}` && x.number === Number(body.number)));
+  if (!target) return send(ctx, githubNotFound());
+  const already = st.projectItems.find((i) => i.project_id === p.id && i.content_type === body.type && i.content_repository === target.repository && i.content_number === target.number);
+  if (already) return ctx.reply(toItem(st, p, already, false), 201);
+  const id = nextSeq(ctx, 'projectitem');
+  await put(ctx, { operation: 'project_item.create', subjectType: 'project_item', subjectId: `projectitem:${id}`, fields: { project_id: p.id, content_type: body.type, content_repository: target.repository, content_number: target.number, field_values: {}, creator_login: caller ?? GITHUB_WORLD_USER, created_at: occurredAt, updated_at: occurredAt } });
+  const now = state();
+  return ctx.reply(toItem(now, p, now.projectItems.find((i) => i.id === id)!, false), 201);
+});
+
+// A field's value: text as given, a number, a date (YYYY-MM-DD), a single-select option's id; null clears it.
+const updateItem = onProject(async (ctx, p) => {
+  const { body, occurredAt, state } = gh(ctx);
+  const item = itemOf(ctx, p);
+  if (!item) return send(ctx, githubNotFound());
+  if (!Array.isArray(body.fields) || !body.fields.length) return invalid(ctx, 'ProjectV2Item', 'fields', 'missing_field');
+  const fields = state().projectFields.filter((f) => f.project_id === p.id);
+  const values: Record<string, unknown> = { ...item.field_values };
+  for (const change of body.fields as Array<Record<string, unknown>>) {
+    const field = fields.find((f) => f.id === Number(change.id));
+    if (!field) return invalid(ctx, 'ProjectV2ItemFieldValue', 'id');
+    const v = change.value;
+    const ok = v === null
+      || (field.data_type === 'text' && typeof v === 'string')
+      || (field.data_type === 'number' && typeof v === 'number')
+      || (field.data_type === 'date' && typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v))
+      || (field.data_type === 'single_select' && field.options?.some((o) => o.id === v));
+    if (!ok) return invalid(ctx, 'ProjectV2ItemFieldValue', 'value');
+    if (v === null) delete values[field.id]; else values[field.id] = v;
+  }
+  await put(ctx, { operation: 'project_item.update', subjectType: 'project_item', subjectId: `projectitem:${item.id}`, fields: { field_values: values, updated_at: occurredAt } });
+  const st = state();
+  return ctx.reply(toItem(st, p, st.projectItems.find((i) => i.id === item.id)!, true));
+});
+
+const createView: Semantics = (ctx) => onProject(async (ctx, p) => {
+  const { body, occurredAt, caller, state } = gh(ctx);
+  if (typeof body.name !== 'string' || !body.name) return invalid(ctx, 'ProjectV2View', 'name', 'missing_field');
+  if (!LAYOUTS.includes(String(body.layout))) return invalid(ctx, 'ProjectV2View', 'layout');
+  const number = Math.max(0, ...state().projectViews.filter((v) => v.project_id === p.id).map((v) => v.number)) + 1;
+  const id = nextSeq(ctx, 'projectview');
+  const list = (k: string): unknown[] => (Array.isArray(body[k]) ? (body[k] as unknown[]) : []);
+  await put(ctx, { operation: 'project_view.create', subjectType: 'project_view', subjectId: `projectview:${id}`, fields: { project_id: p.id, number, name: body.name, layout: body.layout, filter: typeof body.filter === 'string' ? body.filter : null, visible_fields: list('visible_fields'), sort_by: list('sort_by'), group_by: list('group_by'), vertical_group_by: list('vertical_group_by'), creator_login: caller ?? GITHUB_WORLD_USER, created_at: occurredAt, updated_at: occurredAt } });
+  const v = state().projectViews.find((x) => x.id === id)!;
+  return ctx.reply({
+    id: v.id, number: v.number, name: v.name, layout: v.layout, node_id: `PVTV_${v.id}`, project_url: projectUrl(p),
+    html_url: `https://github.com/${p.owner_type === 'organization' ? 'orgs' : 'users'}/${p.owner}/projects/${p.number}/views/${v.number}`,
+    creator: toSimpleUser(v.creator_login ?? GITHUB_WORLD_USER), created_at: v.created_at ?? null, updated_at: v.updated_at ?? null,
+    filter: v.filter ?? null, visible_fields: v.visible_fields ?? [], sort_by: v.sort_by ?? [], group_by: v.group_by ?? [], vertical_group_by: v.vertical_group_by ?? [],
+  }, 201);
+})(ctx);
+
+export function projectsSemantics(): Record<string, Semantics> {
+  const listFields = onProject(async (ctx, p) => ctx.reply(paginate(gh(ctx).state().projectFields.filter((f) => f.project_id === p.id), gh(ctx).query).map((f) => toField(p, f))));
+  const getField: Semantics = (ctx) => onProject(async (ctx, p) => {
+    const f = gh(ctx).state().projectFields.find((x) => x.project_id === p.id && x.id === Number(decodeURIComponent(gh(ctx).seg[5]!)));
+    return f ? ctx.reply(toField(p, f)) : send(ctx, githubNotFound());
+  })(ctx);
+  const listItems: Semantics = (ctx) => onProject(async (ctx, p) => {
+    const st = gh(ctx).state();
+    return ctx.reply(paginate(st.projectItems.filter((i) => i.project_id === p.id), gh(ctx).query).map((i) => toItem(st, p, i, true)));
+  })(ctx);
+  const getItem: Semantics = (ctx) => onProject(async (ctx, p) => {
+    const item = itemOf(ctx, p);
+    return item ? ctx.reply(toItem(gh(ctx).state(), p, item, true)) : send(ctx, githubNotFound());
+  })(ctx);
+  const deleteItem: Semantics = (ctx) => onProject(async (ctx, p) => {
+    const item = itemOf(ctx, p);
+    if (!item) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'project_item.delete', subjectType: 'project_item', subjectId: `projectitem:${item.id}`, fields: { deleted: true, project_id: p.id } });
+    return send(ctx, { status: 204, body: undefined });
+  })(ctx);
+  const listViewItems: Semantics = (ctx) => onProject(async (ctx, p) => {
+    const st = gh(ctx).state();
+    const view = st.projectViews.find((v) => v.project_id === p.id && v.number === Number(decodeURIComponent(gh(ctx).seg[5]!)));
+    if (!view) return send(ctx, githubNotFound());
+    return ctx.reply(paginate(st.projectItems.filter((i) => i.project_id === p.id && passes(st, p, i, view.filter)), gh(ctx).query).map((i) => toItem(st, p, i, true)));
+  })(ctx);
+  const get = onProject(async (ctx, p) => ctx.reply(toGithubProject(p)));
+  return {
+    'projects/list-for-org': listForOwner('organization'),
+    'projects/list-for-user': listForOwner('user'),
+    'projects/get-for-org': get,
+    'projects/get-for-user': get,
+    'projects/create-draft-item-for-org': createDraft,
+    'projects/create-draft-item-for-authenticated-user': createDraft,
+    'projects/list-fields-for-org': listFields,
+    'projects/list-fields-for-user': listFields,
+    'projects/add-field-for-org': addField,
+    'projects/add-field-for-user': addField,
+    'projects/get-field-for-org': getField,
+    'projects/get-field-for-user': getField,
+    'projects/list-items-for-org': listItems,
+    'projects/list-items-for-user': listItems,
+    'projects/add-item-for-org': addItem,
+    'projects/add-item-for-user': addItem,
+    'projects/get-org-item': getItem,
+    'projects/get-user-item': getItem,
+    'projects/update-item-for-org': updateItem,
+    'projects/update-item-for-user': updateItem,
+    'projects/delete-item-for-org': deleteItem,
+    'projects/delete-item-for-user': deleteItem,
+    'projects/create-view-for-org': createView,
+    'projects/create-view-for-user': createView,
+    'projects/list-view-items-for-org': listViewItems,
+    'projects/list-view-items-for-user': listViewItems,
+  };
+}