@volter/twin-github 0.1.2 → 2.0.0

package/src/semantics/git.ts

@@ -0,0 +1,226 @@
+// The Git Data API: blobs, trees, commits, annotated tags and refs, backed by the git plane (the
+// engine slot): each create writes a REAL git object into the repository's store and answers its
+// real sha, so a REST-authored chain (blob → tree → commit → ref) is fetchable by an unmodified git
+// client. The kernel records every write as well (the ledger the projection, mirror and webhooks
+// fold). A ref write is a push, as on GitHub: it moves the branch, re-points or closes the open pull
+// requests riding it, and announces push (and pull_request synchronize/closed).
+import { Buffer } from 'node:buffer';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import {
+  closePrsForDeletedBranch, deleteGitRefInPlane, githubNotFound, isAncestorInPlane, listGitPlaneRefs, objectExistsInPlane, objectTypeInPlane, readGitBlobFromPlane,
+  readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane, syncPrHeadsToBranchTip, toGithubGitBlob, toGithubGitCommit, toGithubGitRef, toGithubGitTagObject,
+  toGithubGitTree, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane,
+  type GithubGitRef, type GithubGitTreeEntry, type GithubWriteEvent,
+} from '../github-twin.ts';
+import { announce, atomic, gh, identityOf, put, send } from './shared.ts';
+
+/** An owner/name the plane's path validation rejects can never name a twin repository: GitHub's 404,
+ *  rather than a store error. */
+function unnamed(ctx: SemanticsContext): boolean {
+  const { seg } = gh(ctx);
+  return !/^[A-Za-z0-9_.-]+$/.test(seg[1]!) || !/^[A-Za-z0-9_.-]+$/.test(seg[2]!) || ['.', '..'].includes(seg[1]!) || ['.', '..'].includes(seg[2]!);
+}
+/** A Git Data write: Not Found for a repository name the plane cannot hold. */
+const gitWrite = (serve: Semantics): Semantics => async (ctx) => (unnamed(ctx) ? send(ctx, githubNotFound()) : serve(ctx));
+
+const invalid = (ctx: SemanticsContext, message: string): Response => ctx.reply({ message }, 422);
+const missing = (ctx: SemanticsContext, resource: string, fields: string[]): Response =>
+  ctx.reply({ message: 'Validation Failed', errors: fields.map((field) => ({ resource, field, code: 'missing_field' })) }, 422);
+
+/** The ref a path names under git/refs/ or git/ref/ (heads/x, tags/x; a ref may hold slashes). */
+const refName = (ctx: SemanticsContext): string => `refs/${decodeURIComponent(gh(ctx).seg.slice(5).join('/'))}`;
+
+/** A branch ref's move: the branch row follows, and the open pull requests riding it are re-pointed. */
+async function followBranch(ctx: SemanticsContext, ref: string, sha: string, events: GithubWriteEvent[]): Promise<void> {
+  if (ref.startsWith('refs/heads/')) await branchMoved(ctx, ref, sha, events);
+}
+/** A branch ref written through the Git Data API: its branch row and the pull requests riding it follow. */
+async function branchMoved(ctx: SemanticsContext, ref: string, sha: string, events: GithubWriteEvent[]): Promise<void> {
+  const { repo, root, occurredAt } = gh(ctx);
+  const branch = ref.slice('refs/heads/'.length);
+  await put(ctx, { operation: 'branch.create', subjectType: 'branch', subjectId: `branch:${repo}#${branch}`, fields: { repository: repo, name: branch, commit_sha: sha } });
+  await syncPrHeadsToBranchTip(repo, branch, sha, root, occurredAt, (pr, base) => events.push({ event: 'pull_request', action: 'synchronize', repository: base, number: Number(pr.number), pr }), atomic(ctx));
+}
+
+export function gitSemantics(): Record<string, Semantics> {
+  const gitGetRef: Semantics = async (ctx) => {
+    const { repo, root, state } = gh(ctx);
+    const current = new Map<string, GithubGitRef>(state().gitRefs.filter((r) => r.repository === repo).map((r) => [r.ref, r]));
+    for (const r of await listGitPlaneRefs(repo, root)) current.set(r.ref, { ...r, repository: repo });
+    const r = current.get(refName(ctx));
+    return send(ctx, r ? { status: 200, body: toGithubGitRef(r) } : githubNotFound());
+  };
+  const gitGetCommit: Semantics = async (ctx) => {
+    const { repo, seg, root, state } = gh(ctx);
+    const sha = decodeURIComponent(seg[5]!);
+    const c = state().gitCommits.find((x) => x.repository === repo && x.sha === sha)
+      ?? await (async () => { const p = await readGitCommitFromPlane(repo, sha, root); return p ? { repository: repo, ...p } : undefined; })();
+    return send(ctx, c ? { status: 200, body: toGithubGitCommit(c) } : githubNotFound());
+  };
+  const gitGetTree: Semantics = async (ctx) => {
+    const { repo, seg, root, state } = gh(ctx);
+    const sha = decodeURIComponent(seg[5]!);
+    const t = state().gitTrees.find((x) => x.repository === repo && x.sha === sha)
+      ?? await (async () => { const p = await readGitTreeFromPlane(repo, sha, root); return p ? { repository: repo, sha, tree: p, truncated: false } : undefined; })();
+    return send(ctx, t ? { status: 200, body: toGithubGitTree(t) } : githubNotFound());
+  };
+  const gitGetBlob: Semantics = async (ctx) => {
+    const { repo, seg, root, state } = gh(ctx);
+    const sha = decodeURIComponent(seg[5]!);
+    const b = state().gitBlobs.find((x) => x.repository === repo && x.sha === sha)
+      ?? await (async () => { const p = await readGitBlobFromPlane(repo, sha, root); return p ? { repository: repo, sha, content_b64: p.content_b64, size: p.size, encoding: 'base64' } : undefined; })();
+    return send(ctx, b ? { status: 200, body: toGithubGitBlob(b) } : githubNotFound());
+  };
+  const gitGetTag: Semantics = async (ctx) => {
+    const { repo, seg, root, state } = gh(ctx);
+    const sha = decodeURIComponent(seg[5]!);
+    const t = state().gitTagObjects.find((x) => x.repository === repo && x.sha === sha)
+      ?? await (async () => { const p = await readGitTagFromPlane(repo, sha, root); return p ? { repository: repo, ...p } : undefined; })();
+    return send(ctx, t ? { status: 200, body: toGithubGitTagObject(t) } : githubNotFound());
+  };
+  const gitCreateBlob: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, body, root } = gh(ctx);
+    if (body.content === undefined) return missing(ctx, 'Blob', ['content']);
+    const encoding = String(body.encoding ?? 'utf-8');
+    const content_b64 = encoding === 'base64' ? String(body.content) : Buffer.from(String(body.content), 'utf-8').toString('base64');
+    let size = 0; try { size = Buffer.from(content_b64, 'base64').length; } catch { size = content_b64.length; }
+    const sha = await writeGitBlobToPlane(repo, content_b64, root);
+    await put(ctx, { operation: 'git_blob.create', subjectType: 'git_blob', subjectId: `gitblob:${repo}#${sha}`, fields: { repository: repo, sha, content_b64, size, encoding: 'base64' } });
+    return ctx.reply({ sha, url: `https://api.github.com/repos/${repo}/git/blobs/${sha}` }, 201);
+  }))(ctx);
+  const gitCreateTree: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, body, root, state } = gh(ctx);
+    if (!Array.isArray(body.tree)) return missing(ctx, 'Tree', ['tree']);
+    const entries: GithubGitTreeEntry[] = (body.tree as Array<Record<string, unknown>>).map((e) => ({
+      path: String(e.path ?? ''), mode: String(e.mode ?? '100644'), type: String(e.type ?? 'blob'), sha: e.sha === null ? '' : String(e.sha ?? ''),
+      ...(e.size !== undefined ? { size: Number(e.size) } : {}),
+    }));
+    if (entries.some((e) => e.sha !== '' && !/^[0-9a-f]{40}$/i.test(e.sha))) return invalid(ctx, 'The sha parameter must be exactly 40 characters and contain only [0-9a-f]');
+    // a base_tree the store does not hold is a 422: dropping it would lose the base's entries
+    if (body.base_tree !== undefined && (!/^[0-9a-f]{40}$/i.test(String(body.base_tree)) || await objectTypeInPlane(repo, String(body.base_tree), root) !== 'tree')) {
+      return invalid(ctx, `The base tree parameter (${String(body.base_tree)}) is not a valid tree`);
+    }
+    const sha = await writeGitTreeToPlane(repo, entries, body.base_tree !== undefined ? String(body.base_tree) : undefined, root);
+    // the kernel row records the tree the plane now holds (after the overlay)
+    const planeTree = await readGitTreeFromPlane(repo, sha, root) ?? entries.filter((e) => e.sha);
+    await put(ctx, { operation: 'git_tree.create', subjectType: 'git_tree', subjectId: `gittree:${repo}#${sha}`, fields: { repository: repo, sha, tree: planeTree, truncated: false } });
+    return ctx.reply(toGithubGitTree(state().gitTrees.find((x) => x.repository === repo && x.sha === sha)!), 201);
+  }))(ctx);
+  const gitCreateCommit: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, body, occurredAt, root, state } = gh(ctx);
+    const absent = (['message', 'tree'] as const).filter((k) => body[k] === undefined);
+    if (absent.length) return missing(ctx, 'Commit', absent);
+    const parents = Array.isArray(body.parents) ? (body.parents as unknown[]).map(String) : [];
+    if (!/^[0-9a-f]{40}$/i.test(String(body.tree)) || parents.some((p) => !/^[0-9a-f]{40}$/i.test(p))) return invalid(ctx, 'The tree and parent parameters must be exactly 40 characters and contain only [0-9a-f]');
+    // GitHub defaults the author to the signed-in person and the committer to the author
+    const me = identityOf(gh(ctx));
+    const author = { name: String(body.author?.name ?? me.name), email: String(body.author?.email ?? me.email) };
+    const committer = body.committer?.name !== undefined || body.committer?.email !== undefined
+      ? { name: String(body.committer?.name ?? author.name), email: String(body.committer?.email ?? author.email) }
+      : author;
+    const sha = await writeGitCommitToPlane(repo, {
+      message: String(body.message), treeSha: String(body.tree), parents,
+      author, committer,
+      occurredAt: String(body.author?.date ?? body.committer?.date ?? occurredAt),
+    }, root);
+    // the kernel row records the identity the object's bytes carry
+    const fields = { repository: repo, sha, message: String(body.message), tree_sha: String(body.tree), parents, author_name: author.name, author_email: author.email, created_at: occurredAt };
+    await put(ctx, { operation: 'git_commit.create', subjectType: 'git_commit', subjectId: `gitcommit:${repo}#${sha}`, fields });
+    return ctx.reply(toGithubGitCommit(state().gitCommits.find((x) => x.repository === repo && x.sha === sha)!), 201);
+  }))(ctx);
+  const gitCreateTag: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, body, occurredAt, root, state } = gh(ctx);
+    const absent = (['tag', 'message', 'object'] as const).filter((k) => body[k] === undefined);
+    if (absent.length) return missing(ctx, 'Tag', absent);
+    if (!/^[0-9a-f]{40}$/i.test(String(body.object))) return invalid(ctx, 'The object parameter must be exactly 40 characters and contain only [0-9a-f]');
+    const me = identityOf(gh(ctx));
+    const tagger = { name: String(body.tagger?.name ?? me.name), email: String(body.tagger?.email ?? me.email) };
+    const sha = await writeGitTagToPlane(repo, {
+      tag: String(body.tag), message: String(body.message), objectSha: String(body.object), objectType: String(body.type ?? 'commit'),
+      ...(tagger !== undefined ? { tagger } : {}), occurredAt: String(body.tagger?.date ?? occurredAt),
+    }, root);
+    const fields = { repository: repo, sha, tag: String(body.tag), message: String(body.message), object_sha: String(body.object), object_type: String(body.type ?? 'commit'), tagger_name: body.tagger?.name, created_at: occurredAt };
+    await put(ctx, { operation: 'git_tag_object.create', subjectType: 'git_tag_object', subjectId: `gittag:${repo}#${sha}`, fields });
+    return ctx.reply(toGithubGitTagObject(state().gitTagObjects.find((x) => x.repository === repo && x.sha === sha)!), 201);
+  }))(ctx);
+  const gitUpdateRef: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, body, root, state } = gh(ctx);
+    const ref = refName(ctx);
+    const existing = state().gitRefs.find((x) => x.repository === repo && x.ref === ref);
+    if (!existing) return send(ctx, githubNotFound());
+    if (body.sha === undefined) return missing(ctx, 'Reference', ['sha']);
+    const force = body.force === true || body.force === 'true';
+    if (!force
+      && await objectExistsInPlane(repo, existing.object_sha, root) && await objectExistsInPlane(repo, String(body.sha), root)
+      && !await isAncestorInPlane(repo, existing.object_sha, String(body.sha), root)) {
+      return invalid(ctx, 'Update is not a fast forward');
+    }
+    await put(ctx, { operation: 'git_ref.update', subjectType: 'git_ref', subjectId: `gitref:${repo}#${ref}`, fields: { repository: repo, ref, object_sha: String(body.sha), object_type: existing.object_type } });
+    await updateGitRefInPlane(repo, ref, String(body.sha), root);
+    const events: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref, before: existing.object_sha, after: String(body.sha) }];
+    await followBranch(ctx, ref, String(body.sha), events);
+    const answer = toGithubGitRef(state().gitRefs.find((x) => x.repository === repo && x.ref === ref)!);
+    await announce(ctx, events);
+    return ctx.reply(answer);
+  }))(ctx);
+  const gitDeleteRef: Semantics = (ctx) => (gitWrite(async (ctx) => {
+    const { repo, root, occurredAt, state } = gh(ctx);
+    const ref = refName(ctx);
+    const existing = state().gitRefs.find((x) => x.repository === repo && x.ref === ref);
+    if (!existing) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'git_ref.delete', subjectType: 'git_ref', subjectId: `gitref:${repo}#${ref}`, fields: { deleted: true, repository: repo, ref } });
+    await deleteGitRefInPlane(repo, ref, root);
+    const events: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref, before: existing.object_sha, after: '0'.repeat(40) }];
+    if (ref.startsWith('refs/heads/')) {
+      const branch = ref.slice('refs/heads/'.length);
+      if (state().branches.some((b) => b.repository === repo && b.name === branch)) {
+        await put(ctx, { operation: 'branch.delete', subjectType: 'branch', subjectId: `branch:${repo}#${branch}`, fields: { deleted: true, repository: repo, name: branch } });
+      }
+      await closePrsForDeletedBranch(repo, branch, root, occurredAt, (pr, base) => events.push({ event: 'pull_request', action: 'closed', repository: base, number: Number(pr.number), pr }), atomic(ctx), { operation: 'git/delete-ref', actor: 'api' });
+    }
+    await announce(ctx, events);
+    return send(ctx, { status: 204, body: undefined });
+  }))(ctx);
+  return {
+    // exactly one ref (heads/x or tags/x), the kernel's refs overlaid by the plane's
+    'git/get-ref': gitGetRef,
+    // Object reads consult the kernel row first (REST-authored objects land in both with the same real
+    // sha), then the plane, so an object that arrived by `git push` is visible here too.
+    'git/get-commit': gitGetCommit,
+    'git/get-tree': gitGetTree,
+    'git/get-blob': gitGetBlob,
+    'git/get-tag': gitGetTag,
+    // content in base64 or utf-8; answers {sha, url}
+    'git/create-blob': gitCreateBlob,
+    // {tree:[{path,mode,type,sha}]} with base_tree overlay semantics (sha:null deletes a path), as GitHub
+    'git/create-tree': gitCreateTree,
+    // {message, tree, parents}; an author or committer date pins the sha as GitHub honors it
+    'git/create-commit': gitCreateCommit,
+    // an ANNOTATED tag object {tag, message, object, type}
+    'git/create-tag': gitCreateTag,
+    // {ref:'refs/heads/x', sha}; 422 when either is missing or the ref exists. A ref minted against a
+    // sha the plane has never seen stays control-plane-only.
+    'git/create-ref': gitWrite(async (ctx) => {
+      const { repo, body, root, state } = gh(ctx);
+      const absent = (['ref', 'sha'] as const).filter((k) => body[k] === undefined);
+      if (absent.length) return missing(ctx, 'Reference', absent);
+      const ref = String(body.ref);
+      if (!ref.startsWith('refs/')) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Reference', field: 'ref', code: 'invalid' }] }, 422);
+      if (state().gitRefs.some((x) => x.repository === repo && x.ref === ref)) return invalid(ctx, 'Reference already exists');
+      const planeType = await objectTypeInPlane(repo, String(body.sha), root);
+      const object_type = planeType === 'tag' || (ref.startsWith('refs/tags/') && state().gitTagObjects.some((t) => t.repository === repo && t.sha === String(body.sha))) ? 'tag' : 'commit';
+      await put(ctx, { operation: 'git_ref.create', subjectType: 'git_ref', subjectId: `gitref:${repo}#${ref}`, fields: { repository: repo, ref, object_sha: String(body.sha), object_type } });
+      await updateGitRefInPlane(repo, ref, String(body.sha), root);
+      const events: GithubWriteEvent[] = [{ event: 'push', action: '', repository: repo, number: 0, ref, before: '0'.repeat(40), after: String(body.sha) }];
+      await followBranch(ctx, ref, String(body.sha), events);
+      const answer = toGithubGitRef(state().gitRefs.find((x) => x.repository === repo && x.ref === ref)!);
+      await announce(ctx, events);
+      return ctx.reply(answer, 201);
+    }),
+    // Fast-forward, or force-update, a ref. A non-fast-forward needs force (true or "true", as gh's -F
+    // and -f send it); decidable only when both commits are in the plane.
+    'git/update-ref': gitUpdateRef,
+    // deleting a branch ref removes the branch and closes the open pull requests riding it
+    'git/delete-ref': gitDeleteRef,
+  };
+}