@volter/twin-github 0.1.0

package/src/github-events.ts

@@ -0,0 +1,95 @@
+// GitHub webhook emission (scorecard R17). Real GitHub fires webhooks on PR/review/
+// comment activity AND across the rest of the surface (release/repository/fork/member/
+// push/discussion/…) — `pull_request` (opened/edited/closed), `pull_request_review`
+// (submitted), `issue_comment` (created), and many more — so an app's webhook handler
+// runs. The twin builds the real GitHub webhook envelope (with the X-GitHub-Event header
+// + the HMAC X-Hub-Signature-256 when a secret is configured), delivers it to registered
+// endpoints (injected delivery: fake in tests, HTTP POST live), and LOGS each delivery so
+// it can be listed + redelivered (real GitHub's deliveries log). Deterministic: caller
+// supplies occurredAt; ids are derived from a stable per-process sequence.
+import { createHmac } from 'node:crypto';
+import type { GithubWriteEvent } from './github-twin.ts';
+
+export type GithubWebhook = { event: string; action: string; number: number; repository: { full_name: string }; pull_request?: Record<string, unknown>; issue?: { number: number }; comment?: { body: string }; review?: { body: string } };
+// Delivery receives the resolved headers too (X-GitHub-Event, X-GitHub-Delivery,
+// X-Hub-Signature-256) so a faithful consumer can verify the signature.
+export type GithubWebhookDelivery = (url: string, headerEvent: string, payload: GithubWebhook, headers: Record<string, string>) => Promise<void> | void;
+
+// A registered endpoint + its (optional) signing secret.
+type Endpoint = { url: string; secret?: string };
+const registry: Endpoint[] = [];
+export function registerGithubWebhook(url: string, secret?: string): void {
+  const existing = registry.find((e) => e.url === url);
+  if (existing) existing.secret = secret;
+  else registry.push({ url, secret });
+}
+export function clearGithubWebhooks(): void { registry.length = 0; deliveries.length = 0; deliverySeq = 0; }
+export function listGithubWebhooks(): string[] { return registry.map((e) => e.url); }
+
+// The deliveries log — one entry per (endpoint, event) delivery, with the exact payload
+// JSON so a redelivery replays it byte-for-byte (real GitHub keeps deliveries for redelivery).
+export type GithubDelivery = { id: string; url: string; event: string; action: string; payloadJson: string; deliveredAt?: string; secret?: string };
+const deliveries: GithubDelivery[] = [];
+let deliverySeq = 0;
+export function listGithubDeliveries(): GithubDelivery[] { return deliveries.map((d) => ({ ...d })); }
+
+/** The HMAC-SHA256 signature GitHub sends in X-Hub-Signature-256 (sha256=<hex>). */
+export function signGithubPayload(secret: string, payloadJson: string): string {
+  return `sha256=${createHmac('sha256', secret).update(payloadJson).digest('hex')}`;
+}
+
+const httpDelivery: GithubWebhookDelivery = async (url, _headerEvent, payload, headers) => {
+  try { await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(payload) }); }
+  catch { /* fire-and-forget, like real GitHub */ }
+};
+
+function buildPayload(write: GithubWriteEvent): GithubWebhook {
+  return {
+    event: write.event,
+    action: write.action,
+    number: write.number,
+    repository: { full_name: write.repository },
+    ...(write.event === 'pull_request' ? { pull_request: write.pr ?? { number: write.number } } : {}),
+    ...(write.event === 'issues' ? { issue: { number: write.number } } : {}),
+    ...(write.event === 'pull_request_review' ? { review: { body: write.body ?? '' }, pull_request: { number: write.number } } : {}),
+    ...(write.event === 'issue_comment' ? { comment: { body: write.body ?? '' } } : {}),
+  };
+}
+
+function headersFor(event: string, deliveryId: string, payloadJson: string, secret?: string): Record<string, string> {
+  const headers: Record<string, string> = { 'x-github-event': event, 'x-github-delivery': deliveryId };
+  if (secret) headers['x-hub-signature-256'] = signGithubPayload(secret, payloadJson);
+  return headers;
+}
+
+/** Emit a GitHub webhook for a twin write to registered endpoints. No-op when none registered. */
+export async function emitGithubEvent(
+  write: GithubWriteEvent,
+  opts: { occurredAt?: string; deliver?: GithubWebhookDelivery } = {},
+): Promise<GithubWebhook[]> {
+  if (registry.length === 0) return [];
+  const deliver = opts.deliver ?? httpDelivery;
+  const payload = buildPayload(write);
+  const payloadJson = JSON.stringify(payload);
+  const out: GithubWebhook[] = [];
+  for (const ep of registry) {
+    const id = `${++deliverySeq}`;
+    deliveries.push({ id, url: ep.url, event: write.event, action: write.action, payloadJson, deliveredAt: opts.occurredAt, secret: ep.secret });
+    const headers = headersFor(write.event, id, payloadJson, ep.secret);
+    await deliver(ep.url, write.event, payload, headers);
+    out.push(payload);
+  }
+  return out;
+}
+
+/** Redeliver a logged delivery by id — replays the EXACT payload to its endpoint. */
+export async function redeliverGithubDelivery(id: string, opts: { deliver?: GithubWebhookDelivery } = {}): Promise<boolean> {
+  const d = deliveries.find((x) => x.id === id);
+  if (!d) return false;
+  const deliver = opts.deliver ?? httpDelivery;
+  const newId = `${++deliverySeq}`;
+  deliveries.push({ ...d, id: newId });
+  const headers = headersFor(d.event, newId, d.payloadJson, d.secret);
+  await deliver(d.url, d.event, JSON.parse(d.payloadJson) as GithubWebhook, headers);
+  return true;
+}

package/src/github-graphql.ts

@@ -0,0 +1,187 @@
+// GitHub GraphQL API (v4) — a FAITHFUL SUBSET over the SAME projection the REST twin serves.
+// GitHub's GraphQL graph is enormous; this models a deliberately small, real slice and is
+// HONEST about its partial coverage: a field the twin does not model raises an
+// `undefinedField`-style GraphQL error (the same error class GitHub raises), rather than
+// fabricating a value. The op is resolved against `githubState` (the kernel projection) so it
+// is consistent with the REST surface byte-for-byte.
+//
+// Modeled subset:
+//   query { viewer { login name } }
+//   query { repository(owner, name) { name nameWithOwner isPrivate
+//             pullRequests(first) { totalCount nodes { number title state } }
+//             issues(first) { totalCount nodes { number title state } } } }
+//   query { node(id) { ... on PullRequest { number title } } }   — id = "PR_<owner>/<repo>#<n>"
+//   mutation { addComment(input: { subjectId, body }) { commentEdge { node { id body } } } }
+// Anything else (other root fields, unmodeled selection fields) → a typed GraphQL error.
+import { applyGithubWrite } from './github-twin.ts';
+import { githubState, type GithubState } from './github-twin.ts';
+
+export type GraphqlResult = { data?: Record<string, unknown> | null; errors?: Array<{ message: string; type?: string }> };
+
+// A field the twin doesn't model — surfaced as GitHub's `undefinedField` error class (honest
+// partial coverage). The query still fails rather than returning a fabricated value.
+function unmodeled(field: string, onType: string): { message: string; type: string } {
+  return { message: `Field '${field}' doesn't exist on type '${onType}' in the twin's modeled GraphQL subset`, type: 'undefinedField' };
+}
+
+// The fields the twin models per type — a selection naming anything else is an honest error.
+const VIEWER_FIELDS = new Set(['login', 'name', '__typename']);
+// `repo` appears as a token from the `...repo` fragment spread gh's RepositoryInfo query uses; the
+// fragment's own fields live in a separate `fragment repo on Repository {…}` block (validated below).
+const REPO_FIELDS = new Set([
+  'name', 'nameWithOwner', 'isPrivate', 'pullRequests', 'issues', '__typename',
+  // RepositoryInfo (gh pr create / gh repo view): the `repo` fragment + repo-level merge settings.
+  'id', 'owner', 'login', 'hasIssuesEnabled', 'description', 'hasWikiEnabled', 'viewerPermission',
+  'defaultBranchRef', 'parent', 'mergeCommitAllowed', 'rebaseMergeAllowed', 'squashMergeAllowed', 'repo',
+]);
+const PR_FIELDS = new Set(['number', 'title', 'state', 'id', '__typename',
+  // PR connection node fields gh pr view/list select (modeled from the PR projection).
+  'url', 'baseRefName', 'headRefName', 'isCrossRepository', 'headRepositoryOwner', 'login', 'name']);
+const ISSUE_FIELDS = new Set(['number', 'title', 'state', 'id', '__typename']);
+// Relay connection-level fields valid alongside nodes/totalCount (not object fields).
+const CONNECTION_FIELDS = new Set(['totalCount', 'nodes', 'edges', 'pageInfo', 'node', 'cursor', 'endCursor', 'hasNextPage', '__typename']);
+
+// Extract the inner-brace selection-set field names for a given parent (very small parser —
+// sufficient for the modeled subset; it reads identifiers, ignoring args/aliases/nesting we
+// resolve explicitly). Returns the top-level selected names under the FIRST `{...}` after the
+// parent token.
+function selectionFields(query: string, parentToken: string): string[] {
+  const idx = query.indexOf(parentToken);
+  if (idx < 0) return [];
+  // Skip an optional argument list `(...)` after the parent token BEFORE locating the selection
+  // set — real gh queries put object args there (e.g. `orderBy: { field: CREATED_AT }`), and the
+  // naive `indexOf('{')` would otherwise mistake that argument brace for the selection set.
+  let p = idx + parentToken.length;
+  while (p < query.length && /\s/.test(query[p]!)) p++;
+  if (query[p] === '(') { let d = 0; for (; p < query.length; p++) { if (query[p] === '(') d++; else if (query[p] === ')') { d--; if (d === 0) { p++; break; } } } }
+  const open = query.indexOf('{', p);
+  if (open < 0) return [];
+  let depth = 0; let end = -1;
+  for (let i = open; i < query.length; i++) { if (query[i] === '{') depth++; else if (query[i] === '}') { depth--; if (depth === 0) { end = i; break; } } }
+  if (end < 0) return [];
+  let inner = query.slice(open + 1, end);
+  // iteratively strip ALL nested blocks (and arg parens) so we only see THIS level's fields.
+  let prev = '';
+  while (prev !== inner) { prev = inner; inner = inner.replace(/\{[^{}]*\}/g, ' '); }
+  inner = inner.replace(/\([^()]*\)/g, ' ');
+  return [...inner.matchAll(/[A-Za-z_][A-Za-z0-9_]*/g)].map((m) => m[0]).filter((t) => t !== 'on');
+}
+
+// Resolve an argument value for `argName` from the query text: a string literal `arg:"x"` or
+// a variable reference `arg:$v` (looked up in `variables`). Returns undefined when absent.
+function argValue(query: string, argName: string, variables: Record<string, unknown>): string | undefined {
+  const lit = new RegExp(`${argName}:\\s*"([^"]*)"`).exec(query);
+  if (lit) return lit[1];
+  const ref = new RegExp(`${argName}:\\s*\\$([A-Za-z_][A-Za-z0-9_]*)`).exec(query);
+  if (ref && variables[ref[1]!] !== undefined) return String(variables[ref[1]!]);
+  return undefined;
+}
+
+function repoToNodes(state: GithubState, repo: string) {
+  const owner = repo.split('/')[0]!;
+  const prs = state.prs.filter((p) => p.repository === repo).map((p) => ({
+    number: p.number, title: p.title ?? null, state: (p.merged ? 'MERGED' : (p.state ?? 'open')).toUpperCase(), id: `PR_${repo}#${p.number}`,
+    // PR connection node fields gh's `pr view`/`pr list` request — all from the SAME PR projection.
+    url: `https://github.com/${repo}/pull/${p.number}`, baseRefName: p.base_ref ?? null, headRefName: p.head_ref ?? null,
+    isCrossRepository: false, headRepositoryOwner: { id: `U_${owner}`, login: owner, name: null },
+  }));
+  const issues = state.issues.filter((i) => i.repository === repo).map((i) => ({ number: i.number, title: i.title ?? null, state: (i.state ?? 'open').toUpperCase(), id: `I_${repo}#${i.number}` }));
+  return { prs, issues };
+}
+
+/** Resolve a GraphQL operation against the github world (the SAME projection as REST). */
+export async function resolveGithubGraphql(req: { query: string; variables?: Record<string, unknown>; root?: string }): Promise<GraphqlResult> {
+  const query = req.query;
+  const vars = req.variables ?? {};
+  const state = githubState(req.root);
+  const isMutation = /^\s*mutation\b/.test(query);
+
+  // ── mutation addComment(input: { subjectId, body }) ──────────────────────────────────────
+  if (isMutation) {
+    if (/\baddComment\b/.test(query)) {
+      // subjectId/body come from variables or inline input. subjectId "PR_<repo>#<n>" or "I_…".
+      const subjectId = String(vars.subjectId ?? argValue(query, 'subjectId', vars) ?? '');
+      const body = String(vars.body ?? argValue(query, 'body', vars) ?? '');
+      const m = /^(PR|I)_(.+)#(\d+)$/.exec(subjectId);
+      if (!m) return { errors: [{ message: `Could not resolve to a node with the global id of '${subjectId}'`, type: 'NOT_FOUND' }] };
+      const repo = m[2]!; const number = Number(m[3]);
+      // addComment maps onto the SAME write path the REST twin uses (issue comment).
+      const res = await applyGithubWrite({ method: 'POST', path: `/repos/${repo}/issues/${number}/comments`, body: JSON.stringify({ body }), root: req.root });
+      if (res.response.status !== 201) return { errors: [{ message: 'addComment failed', type: 'UNPROCESSABLE' }] };
+      const cid = (res.response.body as { id?: number }).id;
+      return { data: { addComment: { commentEdge: { node: { id: `IC_${repo}#${cid}`, body } } } } };
+    }
+    // mutation createPullRequest(input: { repositoryId, baseRefName, headRefName, title, body, draft })
+    // — gh pr create's mutation. Maps onto the SAME REST create path; returns the new PR's node id+url.
+    if (/\bcreatePullRequest\b/.test(query)) {
+      const input = (vars.input ?? {}) as Record<string, unknown>;
+      const m = /^R_(.+)$/.exec(String(input.repositoryId ?? ''));
+      if (!m) return { errors: [{ message: `Could not resolve to a Repository with the global id of '${String(input.repositoryId ?? '')}'`, type: 'NOT_FOUND' }] };
+      const repo = m[1]!;
+      const res = await applyGithubWrite({ method: 'POST', path: `/repos/${repo}/pulls`, body: JSON.stringify({ title: input.title, head: input.headRefName, base: input.baseRefName, body: input.body, draft: input.draft === true }), root: req.root });
+      if (res.response.status !== 201) return { errors: [{ message: 'createPullRequest failed', type: 'UNPROCESSABLE' }] };
+      const number = (res.response.body as { number?: number }).number;
+      return { data: { createPullRequest: { pullRequest: { id: `PR_${repo}#${number}`, url: `https://github.com/${repo}/pull/${number}` } } } };
+    }
+    return { errors: [{ message: 'Only addComment + createPullRequest are modeled in the twin GraphQL mutation subset', type: 'undefinedField' }] };
+  }
+
+  // ── query — resolve the recognized root fields; reject unmodeled ones honestly ────────────
+  const rootFields = selectionFields(query, query.match(/^\s*query/) ? 'query' : '{');
+  // viewer
+  if (/\bviewer\b/.test(query)) {
+    const bad = selectionFields(query, 'viewer').find((f) => !VIEWER_FIELDS.has(f));
+    if (bad) return { errors: [unmodeled(bad, 'User')] };
+    return { data: { viewer: { login: 'octocat', name: state.userProfile.name ?? 'The Octocat' } } };
+  }
+  // node(id)
+  if (/\bnode\b/.test(query)) {
+    const id = String(vars.id ?? argValue(query, 'id', vars) ?? '');
+    const m = /^(PR|I)_(.+)#(\d+)$/.exec(id);
+    if (!m) return { errors: [{ message: `Could not resolve to a node with the global id of '${id}'`, type: 'NOT_FOUND' }] };
+    const repo = m[2]!; const number = Number(m[3]);
+    const { prs, issues } = repoToNodes(state, repo);
+    const obj = m[1] === 'PR' ? prs.find((p) => p.number === number) : issues.find((i) => i.number === number);
+    if (!obj) return { errors: [{ message: `Could not resolve to a node with the global id of '${id}'`, type: 'NOT_FOUND' }] };
+    return { data: { node: { number: obj.number, title: obj.title, state: obj.state, id } } };
+  }
+  // repository(owner, name)
+  if (/\brepository\b/.test(query)) {
+    const owner = String(vars.owner ?? argValue(query, 'owner', vars) ?? '');
+    const name = String(vars.name ?? argValue(query, 'name', vars) ?? '');
+    const repo = `${owner}/${name}`;
+    const bad = selectionFields(query, 'repository').find((f) => !REPO_FIELDS.has(f));
+    if (bad) return { errors: [unmodeled(bad, 'Repository')] };
+    const known = state.repos.find((r) => r.full_name === repo);
+    const { prs, issues } = repoToNodes(state, repo);
+    // unmodeled subfields under pullRequests/issues nodes are honest errors too (connection-level
+    // fields like pageInfo/edges are allowed; only unknown PullRequest/Issue node fields error).
+    if (/\bpullRequests\b/.test(query)) { const b = selectionFields(query, 'pullRequests').find((f) => !PR_FIELDS.has(f) && !CONNECTION_FIELDS.has(f)); if (b) return { errors: [unmodeled(b, 'PullRequest')] }; }
+    if (/\bissues\b/.test(query)) { const b = selectionFields(query, 'issues').find((f) => !ISSUE_FIELDS.has(f) && !CONNECTION_FIELDS.has(f)); if (b) return { errors: [unmodeled(b, 'Issue')] }; }
+    // Honor the connection filter args gh sends: pullRequests(headRefName, states).
+    const headRefName = argValue(query, 'headRefName', vars);
+    const statesArg = vars.states ?? vars.state;
+    const prStates = Array.isArray(statesArg) ? statesArg.map((s) => String(s).toUpperCase()) : undefined;
+    const prNodes = prs
+      .filter((p) => headRefName === undefined || p.headRefName === headRefName)
+      .filter((p) => prStates === undefined || prStates.includes(p.state));
+    // The repo `fragment` fields (gh's RepositoryInfo); derived from the SAME repo projection REST
+    // serves. viewerPermission is ADMIN — the twin's loopback caller is the unauthenticated owner.
+    const repoFragment = {
+      id: `R_${repo}`, name, owner: { login: owner },
+      hasIssuesEnabled: known?.has_issues ?? true, description: known?.description ?? null,
+      hasWikiEnabled: known?.has_wiki ?? true, viewerPermission: 'ADMIN',
+      defaultBranchRef: { name: known?.default_branch ?? 'main' },
+    };
+    const repository: Record<string, unknown> = {
+      ...repoFragment, nameWithOwner: repo, isPrivate: known?.private ?? false,
+      parent: null, mergeCommitAllowed: true, rebaseMergeAllowed: true, squashMergeAllowed: true,
+      pullRequests: { totalCount: prNodes.length, nodes: prNodes, pageInfo: { hasNextPage: false, endCursor: null } },
+      issues: { totalCount: issues.length, nodes: issues.map((i) => ({ number: i.number, title: i.title, state: i.state })), pageInfo: { hasNextPage: false, endCursor: null } },
+    };
+    return { data: { repository } };
+  }
+  // any other top-level field is outside the modeled subset.
+  const unknownRoot = rootFields.find((f) => !['viewer', 'repository', 'node'].includes(f));
+  return { errors: [unmodeled(unknownRoot ?? rootFields[0] ?? 'unknown', 'Query')] };
+}