@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/github-server.js

@@ -0,0 +1,240 @@
+// GitHub twin HTTP server — serve the real GitHub REST API over HTTP so the real
+// `@octokit/rest` client (pointed at this baseUrl) works unmodified (R1). Reads
+// fold observed evidence + action overlay; writes (simulator/fork) become local
+// actions and fire GitHub webhooks (R17). Mirror mode rejects writes (R4).
+// The git SMART-HTTP protocol (clone/fetch/push by an unmodified `git` CLI) is served
+// FIRST — its routes (/:owner/:repo/info/refs, git-upload-pack, git-receive-pack) are
+// binary pkt-line streams over the kernel's git library (github-git-http.ts); a push is
+// announced as an API commit's is (semantics/shared.ts announce).
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest, spanning } from "./manifest.js";
+import { githubSemantics } from "./semantics/index.js";
+import { githubGraphql } from "./semantics/graphql.js";
+import { createGraphqlWire } from "./graphql-wire.js";
+import { githubState, handleGithubDoor, revokedToken } from "./github-twin.js";
+import { announce } from "./semantics/shared.js";
+import { answerVendorErrors, RefusedWriteError } from '@volter/world-core';
+import { worldNow, statefulTwinManifest } from '@volter/world-core';
+import { createHash } from 'node:crypto';
+import { githubOAuthFlow } from "./screens/oauth.js";
+import { githubSessionFlow } from "./screens/session.js";
+import { githubNpmRegistry } from "./npm-registry.js";
+import { githubAppInstallationFlow } from "./screens/app-installation.js";
+import { githubAppManifestFlow } from "./screens/app-manifest.js";
+import { assetUploads } from "./semantics/releases.js";
+import { handleGithubGitSmartHttp, parseGitSmartHttpPath } from "./github-git-http.js";
+import { githubMirrorState } from "./github-mirror-state.js";
+import { GITHUB_MIRROR_STORE } from "./github-shared.js";
+// THE STORE DOOR (runtime contract R5c; mirror purity R3): named, deterministic projections
+// over stored state, served at `GET /twin/store/<name>` and listed in the manifest as
+// `stores` — the kernel adapter's door (`createTwinFetchFromHandler`), carried here by the
+// pack's own fetch because github's wire exceeds the handler shape (the git smart-HTTP
+// plane's binary pkt-line streams). GitHub's ONE store is `mirror`: everything the mirror
+// console renders, projected from the folded state (`github-mirror-state.ts`), so the
+// mirror reads twin state ONLY over this door — never by importing the handler. The
+// door's shapes — the manifest's `stores` + `doors.store`, the 404 body for an unknown
+// name — are the kernel door's, byte for byte.
+const STORE_DOOR = '/twin/store/';
+/**
+ * The whole GitHub serve path as a plain `(Request) => Response` — the `/twin` manifest, the
+ * git smart-HTTP bridge, REST reads and the write path with its webhook emission. NOTHING
+ * about it is port-bound, and `createGithubTwinServer` is one line of `Bun.serve` around it,
+ * so the standalone (R1) and any in-process lane execute the SAME bytes of serving code.
+ *
+ * The GIT PLANE is the KERNEL'S GIT LIBRARY (docs/contributing/architecture.md#the-engine-slot):
+ * one content-addressed object store per world over the blob seam, refs as world state, smart HTTP
+ * in pure JS — Bun and workerd alike, no `git` binary. Every plane touch on the REST read path is
+ * still existence-guarded (`hasBareRepo`), so a world with no repositories answers from the folded
+ * state alone, which is exactly what a pull-fed remote mirror serves (R14: `syncGithubFromRemote` folds PRs,
+ * reviews, comments and issues; none of that needs the plane).
+ */
+/** A release asset's upload: its raw bytes and media type go to the upload operation beside a request with no body,
+ *  since the operation reads them as the file (semantics/releases.ts). */
+async function uploadingAsset(request, inner) {
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    const type = request.headers.get('content-type');
+    const headers = new Headers(request.headers);
+    headers.delete('content-type');
+    headers.delete('content-length');
+    return assetUploads.run({ bytes, type }, () => inner(new Request(request.url, { method: request.method, headers })));
+}
+/** GitHub's refusal of a request body that is not JSON. */
+function malformedJson() {
+    return Response.json({ message: 'invalid JSON body' }, { status: 400 });
+}
+export function createGithubTwinFetch(options) {
+    const readOnly = options.readOnly ?? false;
+    const stores = { [GITHUB_MIRROR_STORE]: () => githubMirrorState(options.root) };
+    const storeNames = Object.keys(stores).sort();
+    const now = options.clock ?? worldNow;
+    const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+    // The twin's doors, in front of GitHub's API: discovery, the store door, the git plane and the stand-ins for acts
+    // GitHub does in its web UI (github-twin.ts handleGithubDoor).
+    const doors = async (request) => {
+        const url = new URL(request.url);
+        const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+        // GET /twin — the discovery manifest (education inside the twin). It EDUCATES the
+        // kernel door's way: the store names + the door's path ride on the manifest.
+        if (request.method === 'GET' && cleanPath === '/twin') {
+            const manifest = statefulTwinManifest({ vendor: 'github', twinOf: 'the GitHub REST pull-request API', stores: 'repositories, pull requests, reviews and comments' });
+            const doors = manifest.doors !== null && typeof manifest.doors === 'object' ? manifest.doors : {};
+            return Response.json({ ...manifest, stores: storeNames, doors: { ...doors, store: 'GET /twin/store/<name>' } });
+        }
+        // GET /twin/store/<name> — the store door (see STORE_DOOR above).
+        if (request.method === 'GET' && cleanPath.startsWith(STORE_DOOR)) {
+            const name = cleanPath.slice(STORE_DOOR.length);
+            const store = stores[name];
+            if (store === undefined)
+                return Response.json({ error: 'unknown store', store: name, stores: storeNames }, { status: 404 });
+            return Response.json(store());
+        }
+        // git smart-HTTP (binary protocol, not JSON). Route-parse BEFORE touching the body so ordinary REST POSTs are
+        // never double-buffered.
+        if ((request.method === 'GET' || request.method === 'POST') && parseGitSmartHttpPath(request.method, url.pathname)) {
+            const occurredAt = now();
+            const git = await handleGithubGitSmartHttp({
+                method: request.method,
+                pathname: url.pathname,
+                query: url.searchParams,
+                ...(request.method === 'POST' ? { body: new Uint8Array(await request.arrayBuffer()) } : {}),
+                ...(options.root !== undefined ? { root: options.root } : {}),
+                readOnly,
+                contentEncoding: request.headers.get('content-encoding') ?? '',
+                gitProtocol: request.headers.get('git-protocol') ?? '',
+                occurredAt,
+            });
+            if (git) {
+                // a push moves branches as an API commit does: GitHub's own processes read it (workflows, secret scanning,
+                // Dependabot, rulesets) and its webhooks are delivered (semantics/shared.ts announce)
+                if (git.webhooks.length) {
+                    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), GIT_OPERATION, { ...scope, clock: () => occurredAt });
+                    await announce(ctx, git.webhooks);
+                }
+                return new Response(git.body, { status: git.status, headers: { 'content-type': git.contentType, 'cache-control': 'no-cache' } });
+            }
+        }
+        return readOnly ? undefined : handleGithubDoor(request, { ...scope, now });
+    };
+    // An archived repository is read-only (docs.github.com/repositories/archiving-a-github-repository/archiving-repositories/
+    // about-archiving-repositories): GitHub refuses a write to it, except the repository's own edit (which unarchives it),
+    // deleting it, and a person's own watch of it.
+    const cross = crossCutting(manifest, { readOnly, ...scope });
+    const readOnlyWhenArchived = (request, next) => {
+        if (request.method === 'GET' || request.method === 'HEAD')
+            return next();
+        const seg = new URL(request.url).pathname.split('/').filter(Boolean);
+        if (seg[0] !== 'repos' || !seg[2] || seg.length === 3 || (seg.length === 4 && seg[3] === 'subscription'))
+            return next();
+        if (!githubState(scope.root).repos.find((r) => r.full_name === `${seg[1]}/${seg[2]}`)?.archived)
+            return next();
+        return Promise.resolve(Response.json({ message: 'Repository was archived so is read-only.', documentation_url: 'https://docs.github.com/articles/about-archiving-repositories' }, { status: 403 }));
+    };
+    // a refused or failed write at the head (kernel head.ts) answers in the vendor's own error shape
+    // The derived dispatch owns the REST wire: semantics handlers, then the derived core; an operation neither
+    // serves answers GitHub's Not Found.
+    const inner = createDerivedFetch({
+        surface: githubSurface,
+        handlers: bindSemantics(manifest, githubSemantics({ readOnly }), scope),
+        core: coreFor(manifest, scope),
+        around: (call, next) => readOnlyWhenArchived(call.request, () => cross(call, next)),
+        gap: () => vendorError(manifest, manifest.notFound),
+    });
+    // GraphQL is a second wire over the same state: the vendor's schema and the pack's resolvers, which get
+    // the handler interface for their request (semanticsContext). A query selecting a field nothing models
+    // answers GitHub's undefinedField error; a read-only twin refuses a mutation as it refuses any write.
+    const graphqlSemantics = githubGraphql();
+    const graphqlWire = createGraphqlWire({
+        loadSdl: async () => (await import('./generated/graphql-sdl.gen.json', { with: { type: 'json' } })).default.sdl,
+        resolvers: graphqlSemantics.resolvers,
+        stored: graphqlSemantics.stored,
+        context: async (request) => ({ ctx: await semanticsContext(manifest, request, GRAPHQL_OPERATION, { ...scope, clock: now }) }),
+        unmodeled: ({ type, field }) => Response.json({ errors: [{ message: `Field '${field}' doesn't exist on type '${type}' in the twin's modeled GraphQL subset`, type: 'undefinedField' }] }),
+    });
+    const graphql = async (request) => {
+        if (readOnly) {
+            const { query } = (await request.clone().json().catch(() => ({})));
+            if (typeof query === 'string' && /^\s*mutation\b/.test(query))
+                return Response.json({ message: 'twin is read-only (mirror mode); start in simulator/fork to write' }, { status: 403 });
+        }
+        return graphqlWire(request);
+    };
+    // GitHub reads a write's body as JSON whatever its content type says (manifest.body.json), and
+    // answers 400 to one that does not parse.
+    const routes = compileSurface(githubSurface);
+    const rest = async (request) => {
+        const url = new URL(request.url);
+        const matched = readOnly || request.method === 'GET' || request.method === 'HEAD' ? undefined : matchOperation(routes, request.method, url.pathname, url.searchParams);
+        if (!matched)
+            return inner(request);
+        // a release asset's body is the file itself, posted to the release's upload_url on uploads.github.com, not to the
+        // API host (docs.github.com/rest/releases/assets#upload-a-release-asset). Where the documentation stops and the
+        // twin decides: api.github.com answers the path as a route it does not serve, GitHub's 404; any other host is the
+        // twin's own address (a World's mount, a local port), where the two GitHub hosts cannot be told apart.
+        if (matched.operation.id === 'repos/upload-release-asset') {
+            if (url.hostname === 'api.github.com')
+                return Response.json({ message: 'Not Found', documentation_url: 'https://docs.github.com/rest', status: '404' }, { status: 404 });
+            return uploadingAsset(request, inner);
+        }
+        const text = await request.clone().text();
+        if (!text)
+            return inner(request);
+        try {
+            JSON.parse(text);
+        }
+        catch {
+            return malformedJson();
+        }
+        return inner(request);
+    };
+    // github.com's OAuth web flow (a hosted flow: the consent screen and the code exchange) sits beside the API
+    // the sign-in every page sends a visitor to who is not signed in (src/screens/session.tsx)
+    const session = githubSessionFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+    const oauth = githubOAuthFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+    // and a GitHub App's installation page (src/screens/app-installation.tsx)
+    const appInstall = githubAppInstallationFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+    // and the page that registers a GitHub App from a manifest (src/screens/app-manifest.tsx)
+    const appManifest = githubAppManifestFlow({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+    // and GitHub Packages' npm registry, where `npm publish` puts a package (src/npm-registry.ts)
+    const npmRegistry = githubNpmRegistry({ ...(options.root !== undefined ? { root: options.root } : {}), now });
+    const wires = async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '');
+        const flow = readOnly ? undefined : (await session(request)) ?? (await oauth(request)) ?? (await appInstall(request)) ?? (await appManifest(request)) ?? (await npmRegistry(request));
+        if (flow)
+            return flow;
+        return request.method === 'POST' && (path === '/graphql' || path === '/api/graphql') ? graphql(request) : rest(request);
+    };
+    const served = async (request) => (await doors(request)) ?? wires(request);
+    const vended = answerVendorErrors(served, (error) => Response.json({ message: error instanceof RefusedWriteError ? `Validation Failed: ${error.message}` : error.message, errors: [{ resource: 'Write', code: error instanceof RefusedWriteError ? 'refused' : 'failed', message: error.message }], documentation_url: 'https://docs.github.com/rest' }, { status: 422 }));
+    // Every answer carries GitHub's own headers for when and which request it was: Date on the World's clock (a response
+    // dated by the host's clock contradicts the World's time) and an x-github-request-id in GitHub's colon-separated hex
+    // form, derived from the instant, the request and a counter so the same request twice gets two ids.
+    let answered = 0;
+    // which part serves each spec operation (the derived dispatch's owners), for the pack's report
+    return Object.assign(async (request) => {
+        const token = (request.headers.get('authorization') ?? '').replace(/^(?:bearer|token)\s+/i, '').trim() || undefined;
+        const res = revokedToken(token, options.root) ? vendorError(manifest, { status: 401, message: 'Bad credentials' }) : await vended(request);
+        const at = now();
+        const headers = new Headers(res.headers);
+        headers.set('date', new Date(at).toUTCString());
+        if (!headers.has('x-github-request-id')) {
+            const h = createHash('sha256').update(`${at}:${request.method}:${request.url}:${answered++}`).digest('hex').toUpperCase();
+            headers.set('x-github-request-id', `${h.slice(0, 4)}:${h.slice(4, 9)}:${h.slice(9, 15)}:${h.slice(15, 21)}:${h.slice(21, 29)}`);
+        }
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    }, { owners: inner.owners });
+}
+/** The GraphQL wire's requests, as the handler interface names them. */
+const GRAPHQL_OPERATION = { id: 'graphql', method: 'POST', path: '/graphql', class: 'action' };
+/** A git push, as the handler interface names it. */
+const GIT_OPERATION = { id: 'git-receive-pack', method: 'POST', path: '/{owner}/{repo}.git/git-receive-pack', class: 'action' };
+// The REST surface, with the path parameters GitHub lets hold slashes (manifest.ts `spanning`).
+const githubSurface = { ...surface, spanning };
+export async function createGithubTwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createGithubTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/dist/src/github-shared.d.ts

@@ -0,0 +1,12 @@
+/** The ONE named store the mirror renders from: `GET /twin/store/${GITHUB_MIRROR_STORE}`
+ *  (runtime contract R5 — the store door — is the only way a mirror reads twin state). */
+export declare const GITHUB_MIRROR_STORE = "mirror";
+/** The store door's path, relative to the twin's base (the mirror host's origin). */
+export declare const GITHUB_MIRROR_STORE_PATH = "/twin/store/mirror";
+/** GitHub's web origin — the projection's `url` fields are real github.com links. */
+export declare const GITHUB_WEB_ORIGIN = "https://github.com";
+/** A pull request's web path (`/{owner}/{repo}/pull/{n}`) — the projection's `url` tail and
+ *  the console's own route for an opened PR are the same grammar, real GitHub's. */
+export declare function githubPullPath(repo: string, number: number | string): string;
+/** An issue's web path (`/{owner}/{repo}/issues/{n}`), the same way. */
+export declare function githubIssuePath(repo: string, number: number | string): string;

package/dist/src/github-shared.js

@@ -0,0 +1,21 @@
+// GitHub SHARED helpers — pure shape functions both sides of the wire need: the twin's
+// mirror-state projection (server side, `github-mirror-state.ts`) and the mirror's React
+// client (`client/github-mirror.tsx`). Plain data in → plain data out; no state access,
+// no `@volter/world-core`, no Bun/node imports — this module rides into the browser bundle
+// unchanged.
+/** The ONE named store the mirror renders from: `GET /twin/store/${GITHUB_MIRROR_STORE}`
+ *  (runtime contract R5 — the store door — is the only way a mirror reads twin state). */
+export const GITHUB_MIRROR_STORE = 'mirror';
+/** The store door's path, relative to the twin's base (the mirror host's origin). */
+export const GITHUB_MIRROR_STORE_PATH = `/twin/store/${GITHUB_MIRROR_STORE}`;
+/** GitHub's web origin — the projection's `url` fields are real github.com links. */
+export const GITHUB_WEB_ORIGIN = 'https://github.com';
+/** A pull request's web path (`/{owner}/{repo}/pull/{n}`) — the projection's `url` tail and
+ *  the console's own route for an opened PR are the same grammar, real GitHub's. */
+export function githubPullPath(repo, number) {
+    return `/${repo}/pull/${number}`;
+}
+/** An issue's web path (`/{owner}/{repo}/issues/{n}`), the same way. */
+export function githubIssuePath(repo, number) {
+    return `/${repo}/issues/${number}`;
+}