@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/semantics/gists.js

@@ -0,0 +1,86 @@
+// GitHub's gists family: create, list, read, edit and delete a gist. A gist's id is minted from a
+// sequence (`gist:<hash>`), its files are stored whole and merged on edit, and every create and edit of its files
+// saves a version the gist's history lists and a revision read returns.
+import { createHash } from 'node:crypto';
+import { GITHUB_WORLD_USER, githubNotFound, paginate, toGithubGist } from "../github-twin.js";
+import { gh, put, send } from "./shared.js";
+const gist = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const g = state().gists.find((x) => x.id === decodeURIComponent(seg[1]));
+    return send(ctx, g ? { status: 200, body: toGithubGist(g) } : githubNotFound());
+};
+// a gist as one of its versions stood: its files then (docs.github.com/rest/gists/gists#get-a-gist-revision)
+const revision = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const g = state().gists.find((x) => x.id === decodeURIComponent(seg[1]));
+    const v = g?.history?.find((h) => h.version === decodeURIComponent(seg[2]));
+    return send(ctx, g && v ? { status: 200, body: toGithubGist({ ...g, files: v.files, updated_at: v.committed_at }) } : githubNotFound());
+};
+/** A saved version of a gist's files: its sha, and the lines added and removed since the one before. */
+function version(gistId, files, before, at, login, n) {
+    const lines = (fs) => new Set(fs.flatMap((f) => (f.content ?? '').split('\n').map((l) => `${f.filename}:${l}`)));
+    const [now, then] = [lines(files), lines(before)];
+    return {
+        version: createHash('sha1').update(`${gistId}:${n}:${JSON.stringify(files)}`).digest('hex'), committed_at: at, user_login: login, files,
+        additions: [...now].filter((l) => !then.has(l)).length, deletions: [...then].filter((l) => !now.has(l)).length,
+    };
+}
+export function gistsSemantics() {
+    const gistsList = async (ctx) => {
+        const { query, state } = gh(ctx);
+        return ctx.reply(paginate(state().gists, query).map(toGithubGist));
+    };
+    const gistsCreate = async (ctx) => {
+        const { body, occurredAt, state } = gh(ctx);
+        const filesIn = (body.files ?? {});
+        const files = Object.entries(filesIn).map(([filename, v]) => ({ filename, content: v?.content ?? '', size: (v?.content ?? '').length }));
+        if (!files.length)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Gist', field: 'files', code: 'missing_field' }] }, 422);
+        // one past every gist stored, tombstones included: each create mints its own id
+        const seq = ctx.rowsRaw('gist', { withDeleted: true }).length + 1;
+        const gistId = createHash('sha256').update(`gist:${seq}`).digest('hex').slice(0, 20);
+        const fields = { id: gistId, owner: gh(ctx).caller ?? GITHUB_WORLD_USER, description: body.description ?? null, public: body.public === true, files, created_at: occurredAt, updated_at: occurredAt, history: [version(gistId, files, [], occurredAt, gh(ctx).caller ?? GITHUB_WORLD_USER, 1)] };
+        await put(ctx, { operation: 'gist.create', subjectType: 'gist', subjectId: `gist:${gistId}`, fields });
+        return ctx.reply(toGithubGist(state().gists.find((x) => x.id === gistId)), 201);
+    };
+    const gistsUpdate = async (ctx) => {
+        const { seg, body, occurredAt, state } = gh(ctx);
+        const gistId = decodeURIComponent(seg[1]);
+        const existing = state().gists.find((g) => g.id === gistId);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const fields = { id: gistId, updated_at: occurredAt };
+        if (body.description !== undefined)
+            fields.description = body.description;
+        if (body.files !== undefined) {
+            const merged = new Map(existing.files.map((f) => [f.filename, f]));
+            for (const [filename, v] of Object.entries(body.files)) {
+                if (v === null)
+                    merged.delete(filename);
+                else
+                    merged.set(filename, { filename: v.filename ?? filename, content: v.content ?? merged.get(filename)?.content ?? '', size: (v.content ?? '').length });
+            }
+            fields.files = [...merged.values()];
+            const history = existing.history ?? [];
+            fields.history = [version(gistId, fields.files, existing.files, occurredAt, gh(ctx).caller ?? GITHUB_WORLD_USER, history.length + 1), ...history];
+        }
+        await put(ctx, { operation: 'gist.update', subjectType: 'gist', subjectId: `gist:${gistId}`, fields });
+        return ctx.reply(toGithubGist(state().gists.find((x) => x.id === gistId)));
+    };
+    const gistsDelete = async (ctx) => {
+        const { seg, state } = gh(ctx);
+        const gistId = decodeURIComponent(seg[1]);
+        if (!state().gists.find((g) => g.id === gistId))
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'gist.delete', subjectType: 'gist', subjectId: `gist:${gistId}`, fields: { deleted: true, id: gistId } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        'gists/list': gistsList,
+        'gists/get': gist,
+        'gists/get-revision': revision,
+        'gists/create': gistsCreate,
+        'gists/update': gistsUpdate,
+        'gists/delete': gistsDelete,
+    };
+}

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

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

package/dist/src/semantics/git.js

@@ -0,0 +1,235 @@
+// 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 { closePrsForDeletedBranch, deleteGitRefInPlane, githubNotFound, isAncestorInPlane, listGitPlaneRefs, objectExistsInPlane, objectTypeInPlane, readGitBlobFromPlane, readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane, syncPrHeadsToBranchTip, toGithubGitBlob, toGithubGitCommit, toGithubGitRef, toGithubGitTagObject, toGithubGitTree, updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane, } from "../github-twin.js";
+import { announce, atomic, gh, identityOf, put, send } from "./shared.js";
+/** 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) {
+    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) => async (ctx) => (unnamed(ctx) ? send(ctx, githubNotFound()) : serve(ctx));
+const invalid = (ctx, message) => ctx.reply({ message }, 422);
+const missing = (ctx, resource, fields) => 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) => `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, ref, sha, events) {
+    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, ref, sha, events) {
+    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() {
+    const gitGetRef = async (ctx) => {
+        const { repo, root, state } = gh(ctx);
+        const current = new Map(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 = 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 = 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 = 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 = 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 = (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 = (ctx) => (gitWrite(async (ctx) => {
+        const { repo, body, root, state } = gh(ctx);
+        if (!Array.isArray(body.tree))
+            return missing(ctx, 'Tree', ['tree']);
+        const entries = body.tree.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 = (ctx) => (gitWrite(async (ctx) => {
+        const { repo, body, occurredAt, root, state } = gh(ctx);
+        const absent = ['message', 'tree'].filter((k) => body[k] === undefined);
+        if (absent.length)
+            return missing(ctx, 'Commit', absent);
+        const parents = Array.isArray(body.parents) ? body.parents.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 = (ctx) => (gitWrite(async (ctx) => {
+        const { repo, body, occurredAt, root, state } = gh(ctx);
+        const absent = ['tag', 'message', 'object'].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 = (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 = [{ 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 = (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 = [{ 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'].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 = [{ 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,
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { FieldResolver } from '../graphql-wire.js';
+/** The closing-keyword issue linkage (Closes/Fixes/Resolves #n) real GitHub derives from the PR body. */
+export declare function closingIssueNumbersFromBody(body: string | undefined): number[];
+export declare function githubGraphql(): {
+    resolvers: Record<string, FieldResolver>;
+    stored: Record<string, string[]>;
+};