npm - @volter/twin-github - Versions diffs - 0.1.0 - Mend

@volter/twin-github 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/LICENSE +202 -0
package/README.md +80 -0
package/client/github-mirror.css +958 -0
package/client/github-mirror.tsx +1513 -0
package/package.json +73 -0
package/src/cli.ts +40 -0
package/src/github-capabilities.ts +2144 -0
package/src/github-conformance.ts +94 -0
package/src/github-connector.ts +644 -0
package/src/github-events.ts +95 -0
package/src/github-graphql.ts +187 -0
package/src/github-mirror-ui.ts +416 -0
package/src/github-server.ts +35 -0
package/src/github-twin.ts +6568 -0
package/src/github-ui-conformance.ts +112 -0
package/src/github-ui-structure.ts +256 -0
package/src/index.ts +23 -0
package/test-fixtures/github-a11y-reference.pr-list.json +1447 -0
package/test-fixtures/github-comment-schema.json +702 -0
package/test-fixtures/github-known-deviations.json +95 -0
package/test-fixtures/github-openapi-operations.json +110 -0
package/test-fixtures/github-pull-schema.json +3601 -0
package/test-fixtures/github-review-schema.json +236 -0

package/src/github-mirror-ui.ts ADDED Viewed

@@ -0,0 +1,416 @@
+// GitHub UI mirror (scorecard R13) — a GitHub-style React app (Bun-bundled) over
+// the twin's github world. Serves `/api/state` in the shape the client renders
+// (pull requests grouped by repo — the per-repo selector), built from the twin's
+// own evidence + local-write state. The client is the shared world UI-mirror design.
+//
+// Honesty: the github world is an EVIDENCE mirror — observed data carries PR
+// metadata + review/comment COUNTS but not their content; local simulator/fork
+// writes carry titles/bodies. So review/comment timeline entries are surfaced from
+// the observed counts and labelled as such; PR titles/bodies appear when present.
+import { discussionCategoriesFor, githubState } from './github-twin.ts';
+// eslint note: the mirror reads the full twin state below; the destructure picks the
+// collections each screen needs.
+const CLIENT_ENTRY = new URL('../client/github-mirror.tsx', import.meta.url).pathname;
+const CLIENT_CSS = new URL('../client/github-mirror.css', import.meta.url).pathname;
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>GitHub UI mirror (twin)</title><link rel="stylesheet" href="/assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="/assets/app.js"></script></body></html>`;
+let clientBundle: Promise<string> | null = null;
+export function buildGithubMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY], target: 'browser', minify: true })
+      .then(async (result) => {
+        if (!result.success) throw new Error(result.logs.map((l) => l.message).join('\n') || 'github UI mirror client build failed');
+        return result.outputs[0]!.text();
+      })
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+const OBSERVED = 'content not mirrored by the evidence twin';
+/** Build the UI-mirror `/api/state` payload from the twin's github world. */
+export function githubMirrorState(root?: string): Record<string, unknown> {
+  const { prs, issues, reviews: foldedReviews, comments: foldedComments, statuses, checkRuns, milestones, workflows: foldedWorkflows, workflowRuns, jobs, releases: foldedReleases, releaseAssets, tags, discussions: foldedDiscussions, discussionComments: foldedDiscussionComments, discussionCategories: customCategories, contents: foldedContents, notifications: foldedNotifications, deployments: foldedDeployments, deploymentStatuses: foldedDeploymentStatuses, environments: foldedEnvironments, projects: foldedProjects, projectFields: foldedProjectFields, projectItems: foldedProjectItems, projectViews: foldedProjectViews, repos: foldedRepos, collaborators: foldedCollaborators, webhooks: foldedWebhooks, branches: foldedBranches } = githubState(root);
+  // CI rollup per PR head_sha from commit statuses + check runs (a LOCAL CI construct;
+  // observed-only PRs carry no head_sha CI, so this stays null for them — honesty).
+  // Precedence mirrors GitHub's rollup: any failure/error → 'failure'; any pending/queued/
+  // in_progress → 'pending'; all success/neutral → 'success'.
+  const ciStatusFor = (repository: string, headSha?: string): string | undefined => {
+    if (!headSha) return undefined;
+    const relStatuses = statuses.filter((s) => s.repository === repository && s.sha === headSha);
+    const relChecks = checkRuns.filter((c) => c.repository === repository && c.head_sha === headSha);
+    if (!relStatuses.length && !relChecks.length) return undefined;
+    const states: string[] = [
+      ...relStatuses.map((s) => s.state),
+      ...relChecks.map((c) => (c.status === 'completed' ? (c.conclusion ?? 'neutral') : 'pending')),
+    ];
+    if (states.some((s) => s === 'failure' || s === 'error')) return 'failure';
+    if (states.some((s) => s === 'pending')) return 'pending';
+    return 'success';
+  };
+  const pullRequests = prs.map((pr) => {
+    // A PR's merge state: an explicit merged write wins; otherwise the recorded state,
+    // defaulting to open. We never fabricate a title for observed-only PRs.
+    const state = pr.merged ? 'merged' : (pr.state ?? 'open');
+    // milestone: a local PATCH stores the NUMBER; surface its title from state.milestones.
+    const ms = pr.milestone !== undefined ? milestones.find((m) => m.repository === pr.repository && m.number === pr.milestone) : undefined;
+    return {
+      repo: pr.repository,
+      number: pr.number,
+      title: pr.title,
+      body: pr.body,
+      state,
+      merged: pr.merged ?? false,
+      mergedAt: pr.merged_at,
+      mergeCommit: pr.merge_commit_sha,
+      url: `https://github.com/${pr.repository}/pull/${pr.number}`,
+      baseBranch: pr.base_ref,
+      headSha: pr.head_sha,
+      changedFiles: pr.changed_files,
+      commitsCount: pr.commits,
+      commentsCount: pr.comment_count,
+      reviewCount: pr.review_count,
+      reviewCommentsCount: foldedComments.filter((c) => c.repository === pr.repository && c.number === pr.number && c.kind === 'review').length,
+      labels: (pr.labels ?? []).map((name) => ({ name })),
+      assignees: pr.assignees ?? [],
+      // requested reviewers (LOCAL writes): bare logins distinct from submitted reviews.
+      requestedReviewers: pr.requested_reviewers ?? [],
+      // milestone title (LOCAL write); undefined for observed-only PRs.
+      milestone: ms?.title,
+      // additions/deletions line counts: roll up from a carried file list on LOCAL writes;
+      // undefined for observed-only PRs (the evidence fold never carries line counts).
+      additions: pr.additions,
+      deletions: pr.deletions,
+      // CI rollup over head_sha statuses + check-runs; undefined when no CI evidence.
+      ciStatus: ciStatusFor(pr.repository, pr.head_sha),
+    };
+  });
+  // Per-commit detail + per-file diffs ride on LOCAL PR writes only (observed PR evidence
+  // carries COUNTS, never content) — so these lists are empty for observed-only PRs, keeping
+  // the mirror honest. Each entry is tagged with repo+number so the client can scope it to
+  // the selected PR, mirroring the GitHub conversation's Commits + Files-changed sections.
+  const commits = prs.flatMap((pr) =>
+    (pr.commits_list ?? []).map((c) => ({
+      repo: pr.repository,
+      number: pr.number,
+      sha: c.sha,
+      message: c.message,
+      author: c.author_name,
+      date: c.author_date,
+      url: `https://github.com/${pr.repository}/commit/${c.sha}`,
+    })),
+  );
+  const files = prs.flatMap((pr) =>
+    (pr.files ?? []).map((f) => ({
+      repo: pr.repository,
+      number: pr.number,
+      filename: f.filename,
+      status: f.status,
+      additions: f.additions,
+      deletions: f.deletions,
+      changes: f.changes,
+      // patch: the unified-diff hunk text (LOCAL writes only) — the Files-changed diff view
+      // renders these as +/- lines; observed PRs carry no per-file diff so this is undefined.
+      patch: f.patch,
+    })),
+  );
+  // First-class issues (a LOCAL construct) grouped per repo via the `repo` field, like PRs.
+  const issuesOut = issues.map((iss) => {
+    const ms = iss.milestone !== undefined ? milestones.find((m) => m.repository === iss.repository && m.number === iss.milestone) : undefined;
+    return {
+      repo: iss.repository,
+      number: iss.number,
+      title: iss.title,
+      body: iss.body,
+      state: iss.state ?? 'open',
+      url: `https://github.com/${iss.repository}/issues/${iss.number}`,
+      createdAt: iss.created_at,
+      updatedAt: iss.updated_at,
+      labels: (iss.labels ?? []).map((name) => ({ name })),
+      assignees: iss.assignees ?? [],
+      milestone: ms?.title,
+      stateReason: iss.state_reason ?? undefined,
+      locked: iss.locked ?? false,
+      // linked PRs/issues (a LOCAL relation): surface as typed references the client links.
+      linked: (iss.linked ?? []).map((l) => ({
+        type: l.type,
+        number: l.number,
+        url: l.type === 'pull_request'
+          ? `https://github.com/${iss.repository}/pull/${l.number}`
+          : `https://github.com/${iss.repository}/issues/${l.number}`,
+      })),
+      // issue comments (kind:'issue' on the shared comment space) — the detail page renders
+      // these in its timeline; observed comments carry no body (labelled, never fabricated).
+      comments: foldedComments
+        .filter((c) => c.kind === 'issue' && c.repository === iss.repository && c.number === iss.number)
+        .map((c) => ({ id: c.id, author: c.body === undefined ? '(observed)' : 'simulator', body: c.body ?? `Comment observed — ${OBSERVED}.`, createdAt: c.created_at })),
+      // a derived timeline of state-change events (labeled/assigned/milestoned/locked/closed)
+      // mirroring the issue's current modeled state — the detail page renders it as a feed.
+      timeline: [
+        ...(iss.labels ?? []).map((name) => ({ event: 'labeled', detail: name })),
+        ...(iss.assignees ?? []).map((login) => ({ event: 'assigned', detail: `@${login}` })),
+        ...(iss.locked ? [{ event: 'locked', detail: iss.active_lock_reason ?? '' }] : []),
+        ...(iss.state === 'closed' ? [{ event: 'closed', detail: iss.state_reason ?? '' }] : []),
+      ],
+    };
+  });
+  // Reviews carry state/body for LOCAL writes; observed reviews carry neither, so we
+  // label them honestly as observed-only rather than fabricating review content.
+  const reviews = foldedReviews.map((r) => {
+    const observed = r.state === undefined && r.body === undefined;
+    return {
+      repo: r.repository,
+      number: r.number,
+      reviewer: observed ? '(observed)' : 'simulator',
+      state: r.state ?? 'reviewed',
+      body: r.body ?? (observed ? `Review observed — ${OBSERVED}.` : ''),
+      submittedAt: r.submitted_at,
+      observed,
+    };
+  });
+  // Issue comments and review (diff-thread) comments are split by kind so the client can
+  // render them in their right place. Observed comments carry no body — label them.
+  const toComment = (c: (typeof foldedComments)[number]) => {
+    const observed = c.body === undefined;
+    return {
+      repo: c.repository,
+      number: c.number,
+      author: observed ? '(observed)' : 'simulator',
+      body: c.body ?? (observed ? `Comment observed — ${OBSERVED}.` : ''),
+      createdAt: c.created_at,
+      observed,
+    };
+  };
+  const comments = foldedComments.filter((c) => c.kind === 'issue').map(toComment);
+  const reviewComments = foldedComments.filter((c) => c.kind === 'review').map(toComment);
+  // Actions (workflows + runs + jobs) — a LOCAL construct (running real CI is the only Actions
+  // non-goal; the run/job OBJECTS are modeled). Surfaced per-repo like PRs/issues. Runs carry
+  // status/conclusion the client renders as badges; jobs are scoped to a run by run_id.
+  const workflows = foldedWorkflows.map((w) => ({
+    repo: w.repository,
+    id: w.id,
+    name: w.name,
+    path: w.path,
+    state: w.state ?? 'active',
+  }));
+  const runs = workflowRuns.map((r) => {
+    const wf = foldedWorkflows.find((w) => w.repository === r.repository && w.id === r.workflow_id);
+    return {
+      repo: r.repository,
+      id: r.id,
+      workflowId: r.workflow_id,
+      workflowName: wf?.name ?? r.name,
+      name: r.name,
+      runNumber: r.run_number,
+      event: r.event,
+      status: r.status,
+      conclusion: r.conclusion,
+      headSha: r.head_sha,
+      headBranch: r.head_branch,
+      createdAt: r.created_at,
+      updatedAt: r.updated_at,
+      url: `https://github.com/${r.repository}/actions/runs/${r.id}`,
+      jobCount: jobs.filter((j) => j.repository === r.repository && j.run_id === r.id).length,
+    };
+  });
+  const runJobs = jobs.map((j) => ({
+    repo: j.repository,
+    id: j.id,
+    runId: j.run_id,
+    name: j.name,
+    status: j.status,
+    conclusion: j.conclusion,
+    steps: j.steps.map((s) => ({ name: s.name, status: s.status, conclusion: s.conclusion, number: s.number })),
+  }));
+  // Releases (a LOCAL construct — there is no observed release evidence; release ASSETS are
+  // metadata only, the binary bytes are the declared Non-goal). Surfaced per-repo like PRs.
+  // Each release carries its tag/name/draft/prerelease flags + its asset catalog; tags are
+  // the published-release tag list (derived, no git blob bytes).
+  const releases = foldedReleases.map((r) => ({
+    repo: r.repository,
+    id: r.id,
+    tagName: r.tag_name,
+    name: r.name,
+    body: r.body,
+    draft: r.draft ?? false,
+    prerelease: r.prerelease ?? false,
+    createdAt: r.created_at,
+    publishedAt: r.published_at,
+    targetCommitish: r.target_commitish,
+    url: `https://github.com/${r.repository}/releases/tag/${encodeURIComponent(r.tag_name)}`,
+    assets: releaseAssets
+      .filter((a) => a.repository === r.repository && a.release_id === r.id)
+      .map((a) => ({ id: a.id, name: a.name, label: a.label, contentType: a.content_type, size: a.size ?? 0, downloadCount: a.download_count ?? 0 })),
+  }));
+  const tagList = tags.map((t) => ({ repo: t.repository, name: t.name, commitSha: t.commit_sha }));
+  // Discussions (a LOCAL construct — no observed discussion evidence; modeled over REST,
+  // honestly noted as a deviation since real GitHub Discussions are GraphQL). Each discussion
+  // carries its category (resolved from the per-repo category list), state/lock, the chosen
+  // answer pointer, and its comments/replies (with the is_answer flag). Surfaced per-repo.
+  const discussionRepos = new Set(foldedDiscussions.map((d) => d.repository));
+  const categoryByRepoSlug = new Map<string, { name: string; emoji?: string; isAnswerable: boolean }>();
+  for (const r of discussionRepos) for (const c of discussionCategoriesFor(r, customCategories)) categoryByRepoSlug.set(`${r}#${c.slug}`, { name: c.name, emoji: c.emoji, isAnswerable: c.is_answerable ?? false });
+  const discussions = foldedDiscussions.map((d) => {
+    const cat = d.category_slug ? categoryByRepoSlug.get(`${d.repository}#${d.category_slug}`) : undefined;
+    const threadComments = foldedDiscussionComments.filter((c) => c.repository === d.repository && c.discussion_number === d.number);
+    return {
+      repo: d.repository,
+      number: d.number,
+      title: d.title,
+      body: d.body,
+      state: d.locked ? 'locked' : (d.state ?? 'open'),
+      locked: d.locked ?? false,
+      categorySlug: d.category_slug,
+      categoryName: cat?.name,
+      categoryEmoji: cat?.emoji,
+      isAnswerable: cat?.isAnswerable ?? false,
+      answerCommentId: d.answer_comment_id ?? null,
+      isAnswered: d.answer_comment_id != null,
+      commentsCount: threadComments.length,
+      createdAt: d.created_at,
+      updatedAt: d.updated_at,
+      url: `https://github.com/${d.repository}/discussions/${d.number}`,
+      comments: threadComments.map((c) => ({
+        id: c.id,
+        parentId: c.parent_id ?? null,
+        body: c.body,
+        isAnswer: c.is_answer ?? false,
+        createdAt: c.created_at,
+      })),
+    };
+  });
+  // Repo contents (a LOCAL construct) — the Code/file browser tree. Each entry carries its
+  // path + size; the browser renders the directory tree per repo (no blob bytes rendered).
+  const contents = foldedContents.map((c) => ({ repo: c.repository, path: c.path, size: c.size, sha: c.sha, branch: c.branch ?? 'main' }));
+  // Notifications (a LOCAL construct) — the inbox screen. unread flag + reason + subject.
+  const notifications = foldedNotifications.map((n) => ({ id: n.id, repo: n.repository, title: n.subject_title, type: n.subject_type, reason: n.reason, unread: n.unread, updatedAt: n.updated_at }));
+  // Deployments (a LOCAL construct) — the repo's Deployments/Environments screen. Each
+  // deployment carries its environment + ref + the LATEST status (the deployment's state),
+  // mirroring GitHub's Environments view (most-recent deployment per environment, with state).
+  const deployments = foldedDeployments.map((d) => {
+    const statusesForDep = foldedDeploymentStatuses.filter((s) => s.deployment_id === d.id).sort((a, b) => b.id - a.id);
+    const latest = statusesForDep[0];
+    return {
+      repo: d.repository,
+      id: d.id,
+      ref: d.ref,
+      sha: d.sha,
+      environment: d.environment,
+      task: d.task,
+      description: d.description ?? undefined,
+      production: d.production_environment ?? false,
+      transient: d.transient_environment ?? false,
+      createdAt: d.created_at,
+      state: latest?.state ?? 'pending',
+      environmentUrl: latest?.environment_url,
+      url: `https://github.com/${d.repository}/deployments`,
+      statuses: statusesForDep.map((s) => ({ id: s.id, state: s.state, description: s.description ?? undefined, createdAt: s.created_at })),
+    };
+  });
+  // Environments (a LOCAL construct) — protection-rule summaries per environment.
+  const environments = foldedEnvironments.map((e) => ({
+    repo: e.repository,
+    name: e.name,
+    waitTimer: e.wait_timer,
+    reviewers: e.reviewers ?? [],
+    protected: Boolean(e.wait_timer) || Boolean(e.reviewers?.length),
+  }));
+  // ── Projects v2 board (a LOCAL construct) — the Project board screen. Each project carries
+  //   its views (board/table) + its Status field's options as COLUMNS, and its items grouped
+  //   into those columns by their Status field value (the board's swim-lanes). Data-coupled:
+  //   seeding a project + a Status field + items moves the column counts the board renders.
+  const projectBoards = foldedProjects.map((p) => {
+    const fields = foldedProjectFields.filter((f) => f.project_id === p.id);
+    const statusField = fields.find((f) => f.data_type === 'single_select') ?? fields.find((f) => /status/i.test(f.name));
+    const columnNames = statusField?.options?.map((o) => o.name) ?? [];
+    const items = foldedProjectItems.filter((i) => i.project_id === p.id);
+    const columns = columnNames.map((name) => ({
+      name,
+      cards: items
+        .filter((i) => String((i.field_values as Record<string, unknown>)[statusField!.name] ?? '') === name)
+        .map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })),
+    }));
+    // items with no (or an unrecognized) status land in a "No Status" lane (GitHub behavior).
+    const noStatus = items.filter((i) => !columnNames.includes(String((i.field_values as Record<string, unknown>)[statusField?.name ?? ''] ?? '')));
+    return {
+      id: p.id, number: p.number, title: p.title, owner: p.owner, closed: p.closed ?? false,
+      views: foldedProjectViews.filter((v) => v.project_id === p.id).map((v) => ({ number: v.number, name: v.name, layout: v.layout })),
+      fields: fields.map((f) => ({ name: f.name, dataType: f.data_type })),
+      itemCount: items.length,
+      columns,
+      noStatus: { name: 'No Status', cards: noStatus.map((i) => ({ id: i.id, title: i.title ?? `#${i.content_id ?? i.id}`, contentType: i.content_type })) },
+      url: `https://github.com/${p.owner_type === 'organization' ? 'orgs/' : 'users/'}${p.owner}/projects/${p.number}`,
+    };
+  });
+  // ── Insights / Pulse / Contributors (DERIVED per repo from the modeled PRs/issues/commits) —
+  //   the Pulse screen's counts (merged/opened PRs, opened/closed issues) + a contributors
+  //   leaderboard from the per-commit authors the twin tracks. Data-coupled: each new PR/issue
+  //   moves a Pulse count; each new commit author moves a contributor's commit total.
+  const repoNames = new Set<string>([...prs.map((p) => p.repository), ...issues.map((i) => i.repository), ...foldedRepos.map((r) => r.full_name)]);
+  const insights = [...repoNames].sort().map((repo) => {
+    const repoPrs = prs.filter((p) => p.repository === repo);
+    const repoIssues = issues.filter((i) => i.repository === repo);
+    const contribCounts = new Map<string, number>();
+    for (const pr of repoPrs) for (const c of pr.commits_list ?? []) { const a = c.author_name ?? '(unknown)'; contribCounts.set(a, (contribCounts.get(a) ?? 0) + 1); }
+    return {
+      repo,
+      pulse: {
+        mergedPrs: repoPrs.filter((p) => p.merged).length,
+        openPrs: repoPrs.filter((p) => !p.merged && (p.state ?? 'open') === 'open').length,
+        openedIssues: repoIssues.filter((i) => (i.state ?? 'open') === 'open').length,
+        closedIssues: repoIssues.filter((i) => i.state === 'closed').length,
+      },
+      contributors: [...contribCounts.entries()].map(([login, commits]) => ({ login, commits })).sort((a, b) => b.commits - a.commits),
+    };
+  });
+  // ── Settings (DERIVED per repo from the modeled repo config + collaborators/webhooks/branches)
+  //   the repo Settings screens (General / Collaborators / Webhooks / Branches). Data-coupled:
+  //   adding a collaborator or webhook moves the counts/rows the settings screen renders.
+  const settings = foldedRepos.map((r) => ({
+    repo: r.full_name,
+    general: { defaultBranch: r.default_branch, private: r.private ?? false, hasIssues: r.has_issues ?? true, hasProjects: r.has_projects ?? true, hasWiki: r.has_wiki ?? true, hasDiscussions: r.has_discussions ?? false, description: r.description ?? null },
+    collaborators: foldedCollaborators.filter((c) => c.repository === r.full_name).map((c) => ({ login: c.login, permission: c.permission })),
+    webhooks: foldedWebhooks.filter((h) => h.repository === r.full_name).map((h) => ({ id: h.id, url: h.url, active: h.active, events: h.events })),
+    branches: foldedBranches.filter((b) => b.repository === r.full_name).map((b) => ({ name: b.name, protected: b.protected ?? false })),
+  }));
+  return {
+    github: { pullRequests, issues: issuesOut, reviews, commits, comments, reviewComments, files, workflows, runs, jobs: runJobs, releases, tags: tagList, discussions, contents, notifications, deployments, environments, projectBoards, insights, settings },
+    fetchedAt: new Date().toISOString(),
+  };
+}
+/** Serve the GitHub UI mirror (React app) + its `/api/state` backing the client. */
+export function createGithubMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildGithubMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return new Response(Bun.file(CLIENT_CSS), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && url.pathname === '/api/state') {
+        return Response.json(githubMirrorState(options.root));
+      }
+      if (request.method === 'GET') {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      return new Response('method not allowed', { status: 405 });
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+export function githubMirrorHtml(): string {
+  return APP_SHELL;
+}

package/src/github-server.ts ADDED Viewed

@@ -0,0 +1,35 @@
+// 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).
+import { applyGithubWrite, handleGithubRequest } from './github-twin.ts';
+import { emitGithubEvent } from './github-events.ts';
+export function createGithubTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
+  const readOnly = options.readOnly ?? false;
+  const server = Bun.serve({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      const path = url.pathname + url.search;
+      if (request.method === 'GET') {
+        if (url.pathname === '/' || url.pathname === '') return Response.json({ service: 'github', readOnly, evidence_only: true });
+        const { status, body } = handleGithubRequest({ method: 'GET', path, ...(options.root !== undefined ? { root: options.root } : {}) });
+        // 204 (e.g. "check if PR merged") carries no body.
+        if (status === 204 || body === undefined) return new Response(null, { status });
+        return Response.json(body as Record<string, unknown>, { status });
+      }
+      if (request.method === 'POST' || request.method === 'PATCH' || request.method === 'PUT' || request.method === 'DELETE') {
+        const text = await request.text();
+        const { response, webhook } = await applyGithubWrite({ method: request.method, path, body: text, ...(options.root !== undefined ? { root: options.root } : {}), readOnly });
+        if (webhook) await emitGithubEvent(webhook, { occurredAt: new Date().toISOString() });
+        // 204 (e.g. workflow_dispatch) carries no body.
+        if (response.status === 204 || response.body === undefined) return new Response(null, { status: response.status });
+        return Response.json(response.body as Record<string, unknown>, { status: response.status });
+      }
+      return Response.json({ message: `method ${request.method} not supported` }, { status: 405 });
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}