@volter/twin-github 0.1.0

package/src/github-ui-conformance.ts

@@ -0,0 +1,112 @@
+// GitHub UI conformance (RUNG-5) — the declared UI surface inventory for a GitHub
+// pull-request / issue view, classified against THIS twin, and the read-only
+// completeness check over it.
+//
+// Honesty: `status` is the current truth, kept honest by github-ui-conformance.test.ts,
+// which cross-checks every 'rendered' claim against the actual mirror (the bundled
+// client + the `/api/state` payload). `rendered` = the UI mirror shows it today;
+// `modeled` = the twin has the data but the mirror doesn't render it (a UI gap to
+// close); `unmodeled` = real GitHub shows it but the EVIDENCE twin doesn't model it
+// (a twin-model gap). The github world is an evidence mirror — OBSERVED PRs carry
+// metadata + review/comment COUNTS but never titles, bodies, authors, diffs, or
+// per-commit/per-file content. LOCAL simulator/fork writes, however, DO carry content,
+// including per-file diffs, per-commit detail, and additions/deletions line counts —
+// so those are MODELED features and the mirror renders them (empty for observed-only
+// PRs, preserving honesty). What stays 'unmodeled' is what the twin models for NEITHER
+// observed nor local writes: PR author identity and the head branch NAME.
+import { checkUiCompleteness, type UiSurface, type UiCompletenessReport } from '@volter/twin-tooling';
+
+/** What real GitHub shows on the PR list, PR conversation, and issues list — classified vs the twin. */
+export const GITHUB_UI_INVENTORY: UiSurface[] = [
+  // --- rendered: the mirror truly shows these today (proven in the test) ---
+  { key: 'prNumber', label: 'PR number (#123)', status: 'rendered' },
+  { key: 'title', label: 'PR title', status: 'rendered' },
+  { key: 'body', label: 'PR description / body', status: 'rendered' },
+  { key: 'stateBadge', label: 'State / merge badge (open/closed/merged)', status: 'rendered' },
+  { key: 'labels', label: 'Labels', status: 'rendered' },
+  { key: 'assignees', label: 'Assignees', status: 'rendered' },
+  { key: 'reviewers', label: 'Reviewers (state + login)', status: 'rendered' },
+  { key: 'reviewContent', label: 'Review submissions (body + state)', status: 'rendered' },
+  { key: 'comments', label: 'Issue comments / conversation', status: 'rendered' },
+  { key: 'reviewComments', label: 'Review (diff-thread) comments', status: 'rendered' },
+  { key: 'changedFilesCount', label: 'Changed-files count', status: 'rendered' },
+  { key: 'commitsCount', label: 'Commits count', status: 'rendered' },
+  { key: 'reviewCount', label: 'Review count', status: 'rendered' },
+  { key: 'commentsCount', label: 'Comment count', status: 'rendered' },
+  { key: 'baseBranch', label: 'Base branch ref', status: 'rendered' },
+  { key: 'headSha', label: 'Head commit sha', status: 'rendered' },
+  { key: 'mergeCommit', label: 'Merge commit sha', status: 'rendered' },
+  { key: 'mergedAt', label: 'Merged timestamp', status: 'rendered' },
+  { key: 'prUrl', label: 'Link to PR on GitHub', status: 'rendered' },
+  { key: 'issuesList', label: 'Issues list (first-class issues view)', status: 'rendered' },
+  { key: 'repoSelector', label: 'Per-repo selector (repo grouping)', status: 'rendered' },
+  // reviewCommentsCount is computed + emitted in /api/state and now rendered in the
+  // conversation header alongside reviewCount + commentsCount.
+  { key: 'reviewCommentsCount', label: 'Review-comment (diff-thread) count', status: 'rendered' },
+  // CI rollup (commit statuses + check-runs) over the PR head_sha — the twin now models
+  // statuses[]/checkRuns[]; the mirror renders a ✓/✗/● indicator + a Checks side-section.
+  { key: 'checksStatus', label: 'CI / status checks', status: 'rendered' },
+  // milestone: the twin models milestone NUMBER + state.milestones; the mirror renders
+  // the milestone title as a badge on PR/issue rows + a Milestone side-section.
+  { key: 'milestone', label: 'Milestone', status: 'rendered' },
+  // linked PRs/issues: the twin models issue.linked[]; the mirror renders typed
+  // cross-reference links on the issue rows.
+  { key: 'linkedIssues', label: 'Linked / source issue', status: 'rendered' },
+  // requested reviewers (distinct from submitted reviews): the twin models
+  // requested_reviewers[]; the mirror renders them as chips in the Reviewers side-section.
+  { key: 'requestedReviewers', label: 'Requested reviewers', status: 'rendered' },
+  // per-file diffs: the twin models pr.files (GithubPullFile) on LOCAL writes; the mirror
+  // renders the conversation's Files-changed section (filename + status + +/- counts).
+  // Empty for observed-only PRs (no per-file evidence) — honesty preserved.
+  { key: 'filesChangedContent', label: 'Per-file diff list (filenames + status + counts)', status: 'rendered' },
+  // additions/deletions: the twin rolls these up from the carried file list on LOCAL writes;
+  // the mirror renders them in the Aside snapshot counts. Undefined for observed-only PRs.
+  { key: 'diffStats', label: 'Additions / deletions line counts', status: 'rendered' },
+  // per-commit detail: the twin models pr.commits_list (GithubPullCommit) on LOCAL writes;
+  // the mirror renders the conversation's Commits section (sha + message + author + date).
+  // Empty for observed-only PRs (only a commit COUNT is observed) — honesty preserved.
+  { key: 'commitsContent', label: 'Per-commit list (sha + message + author)', status: 'rendered' },
+
+  // --- Actions (workflows + runs + jobs) — a LOCAL construct (running real CI is the only
+  //     Actions non-goal; the run/job OBJECTS are modeled + rendered in the Actions view) ---
+  // the Actions tab lists workflow runs; each run row carries a status/conclusion badge.
+  { key: 'actionsRunsList', label: 'Workflow runs list (Actions view)', status: 'rendered' },
+  // the run badge reflects status (queued/in_progress/completed) + conclusion (success/
+  // failure/cancelled), rendered as a glyph + label on every run row + the detail header.
+  { key: 'runStatusBadge', label: 'Run status / conclusion badge', status: 'rendered' },
+  // selecting a run renders a detail pane with its jobs + each job's steps.
+  { key: 'runJobs', label: 'Run detail — jobs + steps', status: 'rendered' },
+
+  // --- Releases (workflows of the repo's release channel) — a LOCAL construct (no observed
+  //     release evidence; release ASSET binary BYTES are the only Releases non-goal) ---
+  // the Releases tab lists releases; each row carries tag + name + draft/prerelease badge.
+  { key: 'releasesList', label: 'Releases list (Releases view)', status: 'rendered' },
+  // the channel badge reflects draft / prerelease / published, rendered on every row + header.
+  { key: 'releaseChannelBadge', label: 'Release channel badge (draft/prerelease/release)', status: 'rendered' },
+  // selecting a release renders a detail pane with its notes + ASSET catalog (metadata only).
+  { key: 'releaseAssets', label: 'Release detail — asset catalog (name/type/size)', status: 'rendered' },
+
+  // --- Discussions (a LOCAL construct; modeled over REST — a declared deviation from
+  //     GitHub's GraphQL Discussions API. No observed discussion evidence) ---
+  // the Discussions tab lists discussions; each row carries title + category + answer badge.
+  { key: 'discussionsList', label: 'Discussions list (Discussions view)', status: 'rendered' },
+  // the category chip reflects the discussion's category (Q&A categories are answerable).
+  { key: 'discussionCategory', label: 'Discussion category chip (General/Q&A/…)', status: 'rendered' },
+  // an answerable (Q&A) discussion shows an answered/unanswered badge.
+  { key: 'discussionAnswerStatus', label: 'Discussion answered/unanswered status (Q&A)', status: 'rendered' },
+  // selecting a discussion renders a detail pane with the opening post + the comment/reply
+  // thread, highlighting the accepted answer.
+  { key: 'discussionThread', label: 'Discussion detail — comment/reply thread + accepted answer', status: 'rendered' },
+
+  // --- unmodeled: real GitHub shows it, the evidence twin models it for neither
+  //     observed nor local writes (a genuine twin-model gap) ---
+  // The twin never carries author identity on a PR (observed evidence has only repo/number/
+  // counts; local writes don't capture the acting login into the PR object either).
+  { key: 'author', label: 'PR author (login + avatar)', status: 'unmodeled' },
+  // The twin tracks base_ref + head_sha but not the head branch NAME (only the head sha).
+  { key: 'headBranch', label: 'Head branch ref name', status: 'unmodeled' },
+];
+
+export function githubUiConformance(): UiCompletenessReport {
+  return checkUiCompleteness('github', GITHUB_UI_INVENTORY);
+}

package/src/github-ui-structure.ts

@@ -0,0 +1,256 @@
+// RUNG-5 STRUCTURAL DOM CHECKLIST for the GitHub mirror — the PROXIMITY half of the
+// UI rung. Completeness asks "does the mirror show the data?"; this asks "does the
+// mirror's rendered DOM look structurally like the real GitHub UI?" — the PR table
+// emits a row per PR, each row carries a state badge, the conversation pane has the
+// reviews/comments timeline, the Aside carries the reviewers/labels/assignees/milestone
+// sections, a CI status element renders, the issues view emits a row per issue.
+//
+// Each check's `present` is computed from the ACTUAL markup produced by
+// renderToStaticMarkup of the EXPORTED mirror components with seeded props — so a check
+// cannot pass unless the component truly emits that landmark. Not the bundle, not the
+// inventory: the real React render.
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createElement } from 'react';
+import { checkUiStructure, type UiStructureCheck, type UiStructureReport } from '@volter/twin-tooling';
+import {
+  PrList, Conversation, Aside, IssuesTable, CiStatus, ActionsView, ReleasesView, DiscussionsView, DeploymentsView,
+  type PullRequest, type Issue, type Review, type Commit, type Comment, type ChangedFile,
+  type WorkflowRun, type Job, type Release, type Discussion, type Deployment, type Environment,
+} from '../client/github-mirror.tsx';
+
+// ── Seeded props: one rich PR (reviews/comments/labels/assignees/CI/milestone/files)
+//    plus a second PR so the list has more than one row, and one issue. ───────────────
+const PR: PullRequest = {
+  repo: 'o/r', number: 1, title: 'Add feature', body: 'why this PR', state: 'open',
+  author: 'octocat', baseBranch: 'main', headBranch: 'feat', headSha: 'abcdef1234567',
+  createdAt: '2026-04-01T00:00:00Z', updatedAt: '2026-04-02T00:00:00Z',
+  additions: 42, deletions: 7, changedFiles: 2, commitsCount: 3,
+  commentsCount: 1, reviewCount: 1, reviewCommentsCount: 1,
+  labels: [{ name: 'bug' }, { name: 'enhancement' }],
+  assignees: ['alice'], requestedReviewers: ['carol'], milestone: 'v1.0',
+  ciStatus: 'success',
+};
+const PR_TWO: PullRequest = {
+  repo: 'o/r', number: 2, title: 'Fix bug', state: 'open', author: 'hubot',
+  createdAt: '2026-03-01T00:00:00Z', updatedAt: '2026-03-02T00:00:00Z', ciStatus: 'failure',
+};
+const ISSUE: Issue = {
+  repo: 'o/web', number: 1, title: 'An issue', state: 'open',
+  createdAt: '2026-04-04T00:00:00Z', updatedAt: '2026-04-04T00:00:00Z',
+  labels: [{ name: 'triage' }], assignees: ['bob'], milestone: 'v1.0',
+};
+const ISSUE_TWO: Issue = {
+  repo: 'o/web', number: 2, title: 'Another issue', state: 'closed',
+  createdAt: '2026-04-05T00:00:00Z', updatedAt: '2026-04-05T00:00:00Z',
+};
+const REVIEWS: Review[] = [{ repo: 'o/r', number: 1, reviewer: 'carol', state: 'approved', body: 'looks good', submittedAt: '2026-04-02T01:00:00Z' }];
+const COMMITS: Commit[] = [{ repo: 'o/r', number: 1, sha: 'abcdef1234567', message: 'do the thing', authorLogin: 'octocat', date: '2026-04-01T12:00:00Z' }];
+const COMMENTS: Comment[] = [{ repo: 'o/r', number: 1, author: 'dave', body: 'a note', createdAt: '2026-04-02T02:00:00Z' }];
+const REVIEW_COMMENTS: Comment[] = [{ repo: 'o/r', number: 1, author: 'erin', body: 'inline diff note', path: 'src/x.ts', createdAt: '2026-04-02T03:00:00Z' }];
+const FILES: ChangedFile[] = [{ repo: 'o/r', number: 1, filename: 'src/x.ts', status: 'modified', additions: 42, deletions: 7 }];
+// Actions: two runs (one completed/success, one cancelled) so the runs list has >1 row, plus
+// a job (with steps) for the first run so the run-detail jobs section renders.
+const RUNS: WorkflowRun[] = [
+  { repo: 'o/r', id: 101, workflowId: 1, workflowName: 'CI', runNumber: 1, event: 'workflow_dispatch', status: 'completed', conclusion: 'success', headSha: 'abcdef1234567', headBranch: 'main', jobCount: 1, url: 'https://github.com/o/r/actions/runs/101' },
+  { repo: 'o/r', id: 102, workflowId: 1, workflowName: 'CI', runNumber: 2, event: 'workflow_dispatch', status: 'completed', conclusion: 'cancelled', headSha: 'abcdef7654321', headBranch: 'dev', jobCount: 0 },
+];
+const JOBS: Job[] = [{ repo: 'o/r', id: 201, runId: 101, name: 'build', status: 'completed', conclusion: 'success', steps: [{ name: 'set up job', status: 'completed', conclusion: 'success', number: 1 }] }];
+// Releases: two releases (one published with an asset, one draft) so the list has >1 row and
+// the detail pane renders the asset catalog (metadata only — bytes are the Non-goal).
+const RELEASES: Release[] = [
+  { repo: 'o/r', id: 1, tagName: 'v1.0.0', name: 'First release', body: 'the notes', draft: false, prerelease: false, publishedAt: '2026-04-10T00:00:00Z', targetCommitish: 'main', url: 'https://github.com/o/r/releases/tag/v1.0.0', assets: [{ id: 11, name: 'app.zip', contentType: 'application/zip', size: 2048, downloadCount: 3 }] },
+  { repo: 'o/r', id: 2, tagName: 'v1.1.0-rc1', name: 'RC', draft: true, prerelease: true, createdAt: '2026-04-11T00:00:00Z', targetCommitish: 'main', assets: [] },
+];
+// Discussions: two discussions (one answerable Q&A with a chosen answer + a reply, one
+// General) so the list has >1 row and the detail pane renders the comment thread + the
+// accepted-answer landmark.
+const DISCUSSIONS: Discussion[] = [
+  {
+    repo: 'o/r', number: 1, title: 'How do I configure X?', body: 'I am stuck on X.', state: 'open',
+    categorySlug: 'q-a', categoryName: 'Q&A', categoryEmoji: '🙏', isAnswerable: true,
+    answerCommentId: 101, isAnswered: true, commentsCount: 2, updatedAt: '2026-04-12T00:00:00Z',
+    url: 'https://github.com/o/r/discussions/1',
+    comments: [
+      { id: 101, parentId: null, body: 'Do it this way.', isAnswer: true, createdAt: '2026-04-12T01:00:00Z' },
+      { id: 102, parentId: 101, body: 'Thanks, that worked!', isAnswer: false, createdAt: '2026-04-12T02:00:00Z' },
+    ],
+  },
+  {
+    repo: 'o/r', number: 2, title: 'Welcome!', body: 'Say hi here.', state: 'open',
+    categorySlug: 'general', categoryName: 'General', categoryEmoji: '💬', isAnswerable: false,
+    answerCommentId: null, isAnswered: false, commentsCount: 0, updatedAt: '2026-04-13T00:00:00Z', comments: [],
+  },
+];
+
+// Deployments: two deployments (one success in production, one pending in staging) so the
+// list has >1 row, plus two environments (one protected with a wait timer + reviewers, one
+// unprotected) so the environments list renders with a protection summary.
+const DEPLOYMENTS: Deployment[] = [
+  { repo: 'o/r', id: 1, ref: 'main', sha: 'abcdef1234567', environment: 'production', task: 'deploy', description: 'release v1', production: true, state: 'success', environmentUrl: 'https://app.example.com', createdAt: '2026-04-10T00:00:00Z', statuses: [{ id: 2, state: 'success' }, { id: 1, state: 'in_progress' }] },
+  { repo: 'o/r', id: 2, ref: 'dev', sha: 'fedcba7654321', environment: 'staging', task: 'deploy', state: 'pending', createdAt: '2026-04-11T00:00:00Z', statuses: [] },
+];
+const ENVIRONMENTS: Environment[] = [
+  { repo: 'o/r', name: 'production', waitTimer: 30, reviewers: ['alice', 'bob'], protected: true },
+  { repo: 'o/r', name: 'staging', reviewers: [], protected: false },
+];
+
+/** Count non-overlapping occurrences of a substring in `html`. */
+function count(html: string, marker: string): number {
+  if (!marker) return 0;
+  let n = 0;
+  let i = html.indexOf(marker);
+  while (i !== -1) { n += 1; i = html.indexOf(marker, i + marker.length); }
+  return n;
+}
+
+/** Render the exported presentational components to static HTML, once, deterministically. */
+export function renderGithubMirrorMarkup() {
+  return {
+    prList: renderToStaticMarkup(createElement(PrList, { prs: [PR, PR_TWO], reviews: REVIEWS, selectedKey: 'o/r#1' })),
+    conversation: renderToStaticMarkup(createElement(Conversation, { pr: PR, reviews: REVIEWS, commits: COMMITS, comments: COMMENTS, reviewComments: REVIEW_COMMENTS, files: FILES })),
+    aside: renderToStaticMarkup(createElement(Aside, { pr: PR, reviews: REVIEWS, commits: COMMITS, files: FILES })),
+    issues: renderToStaticMarkup(createElement(IssuesTable, { issues: [ISSUE, ISSUE_TWO] })),
+    ciStatus: renderToStaticMarkup(createElement(CiStatus, { status: 'success' })),
+    actions: renderToStaticMarkup(createElement(ActionsView, { runs: RUNS, jobs: JOBS, selectedRunId: 101 })),
+    releases: renderToStaticMarkup(createElement(ReleasesView, { releases: RELEASES, selectedReleaseId: 1 })),
+    discussions: renderToStaticMarkup(createElement(DiscussionsView, { discussions: DISCUSSIONS, selectedKey: 'o/r#1' })),
+    deployments: renderToStaticMarkup(createElement(DeploymentsView, { deployments: DEPLOYMENTS, environments: ENVIRONMENTS })),
+  };
+}
+
+/** The structural checklist: each `present` is derived from the rendered markup above. */
+export function githubUiStructureChecks(): UiStructureCheck[] {
+  const dom = renderGithubMirrorMarkup();
+  return [
+    {
+      key: 'pr-list-row-per-pr',
+      label: 'the PR list emits a row (.pr-row) per pull request',
+      present: count(dom.prList, 'class="pr-row') === 2,
+    },
+    {
+      key: 'pr-row-state-badge',
+      label: 'each PR row shows a state badge element (.state-badge)',
+      present: count(dom.prList, 'class="state-badge') >= 2,
+    },
+    {
+      key: 'pr-row-ci-status',
+      label: 'a PR row renders a CI status indicator (.ci-status)',
+      present: dom.prList.includes('class="ci-status'),
+    },
+    {
+      key: 'conversation-detail-pane',
+      label: 'the conversation/detail pane renders (section.conversation with a heading + state line)',
+      present: dom.conversation.includes('class="conversation"') && dom.conversation.includes('class="state-line"'),
+    },
+    {
+      key: 'conversation-comments-timeline',
+      label: 'the conversation pane has a comments timeline (.timeline-item with a .comment)',
+      present: dom.conversation.includes('class="timeline-item"') && dom.conversation.includes('class="comment"'),
+    },
+    {
+      key: 'conversation-reviews-section',
+      label: 'the conversation pane has a reviews section (.review-card)',
+      present: dom.conversation.includes('class="review-card"'),
+    },
+    {
+      key: 'conversation-files-changed',
+      label: 'the conversation pane has a files-changed section (.file-list with a .file-row)',
+      present: dom.conversation.includes('class="file-list"') && dom.conversation.includes('class="file-row"'),
+    },
+    {
+      key: 'aside-sidebar',
+      label: 'the detail Aside renders as a sidebar landmark (aside.sidebar)',
+      present: dom.aside.includes('<aside class="sidebar"'),
+    },
+    {
+      key: 'aside-reviewers-section',
+      label: 'the Aside has a Reviewers section',
+      present: dom.aside.includes('<h3>Reviewers</h3>'),
+    },
+    {
+      key: 'aside-labels-assignees-milestone',
+      label: 'the Aside has Labels, Assignees and Milestone sections',
+      present: dom.aside.includes('<h3>Labels</h3>') && dom.aside.includes('<h3>Assignees</h3>') && dom.aside.includes('<h3>Milestone</h3>'),
+    },
+    {
+      key: 'ci-status-element',
+      label: 'the CI status component renders a labelled status element (.ci-status.success)',
+      present: dom.ciStatus.includes('class="ci-status success"') && dom.ciStatus.includes('title="checks: success"'),
+    },
+    {
+      key: 'issues-row-per-issue',
+      label: 'the issues view emits a row (.issue-row) per issue',
+      present: count(dom.issues, 'issue-row') === 2,
+    },
+    {
+      key: 'actions-run-row-per-run',
+      label: 'the Actions view emits a run row (.run-row) per workflow run',
+      present: count(dom.actions, 'class="run-row') === 2,
+    },
+    {
+      key: 'actions-run-status-badge',
+      label: 'each run row shows a run status/conclusion badge (.run-badge)',
+      present: count(dom.actions, 'class="run-badge') >= 2,
+    },
+    {
+      key: 'actions-run-detail-jobs',
+      label: 'the run detail pane renders a jobs section (.job-list with a .job-row + .step-row)',
+      present: dom.actions.includes('class="job-list"') && dom.actions.includes('class="job-row"') && dom.actions.includes('class="step-row"'),
+    },
+    {
+      key: 'releases-row-per-release',
+      label: 'the Releases view emits a release row (.release-row) per release',
+      present: count(dom.releases, 'class="release-row') === 2,
+    },
+    {
+      key: 'releases-channel-badge',
+      label: 'each release row shows a draft/prerelease/release channel badge (.release-badge)',
+      present: count(dom.releases, 'class="release-badge') >= 2,
+    },
+    {
+      key: 'releases-detail-assets',
+      label: 'the release detail pane renders an asset catalog (.asset-list with an .asset-row)',
+      present: dom.releases.includes('class="asset-list"') && dom.releases.includes('class="asset-row"'),
+    },
+    {
+      key: 'discussions-row-per-discussion',
+      label: 'the Discussions view emits a discussion row (.discussion-row) per discussion',
+      present: count(dom.discussions, 'class="discussion-row') === 2,
+    },
+    {
+      key: 'discussions-category-badge',
+      label: 'each discussion row shows a category chip (.discussion-category)',
+      present: count(dom.discussions, 'class="discussion-category') >= 2,
+    },
+    {
+      key: 'discussions-answer-badge',
+      label: 'an answerable discussion shows an answered/unanswered badge (.answer-badge)',
+      present: dom.discussions.includes('class="answer-badge'),
+    },
+    {
+      key: 'discussions-detail-thread',
+      label: 'the discussion detail pane renders a comment thread (.comment-thread with a .thread-comment) + the accepted answer (.accepted-answer)',
+      present: dom.discussions.includes('class="comment-thread"') && dom.discussions.includes('class="thread-comment') && dom.discussions.includes('class="comment accepted-answer"'),
+    },
+    {
+      key: 'deployments-row-per-deployment',
+      label: 'the Deployments view emits a deployment row (.deployment-row) per deployment',
+      present: count(dom.deployments, 'class="deployment-row') === 2,
+    },
+    {
+      key: 'deployments-state-badge',
+      label: 'each deployment row shows a state badge (.deployment-state)',
+      present: count(dom.deployments, 'class="deployment-state') >= 2,
+    },
+    {
+      key: 'deployments-environments-list',
+      label: 'the Deployments view renders an environments list (.environments-list with an .environment-row + a protection summary)',
+      present: dom.deployments.includes('class="environments-list"') && dom.deployments.includes('class="environment-row"') && dom.deployments.includes('class="environment-protected'),
+    },
+  ];
+}
+
+/** RUNG-5 structural DOM report for the GitHub mirror. Read-only, deterministic. */
+export function githubUiStructure(): UiStructureReport {
+  return checkUiStructure('github', githubUiStructureChecks());
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+// @volter/twin-github — the GitHub PR-evidence twin (REST), on @volter/twin.
+export { applyGithubWrite, githubState, handleGithubRequest, toGithubComment, toGithubIssue, toGithubRest, toGithubReview, toGithubReviewComment } from './github-twin.ts';
+export type { GithubComment, GithubIssue, GithubPr, GithubResponse, GithubReview, GithubState, GithubWriteEvent, GithubWriteOutcome } from './github-twin.ts';
+export { createGithubTwinServer } from './github-server.ts';
+export { clearGithubWebhooks, emitGithubEvent, listGithubWebhooks, registerGithubWebhook } from './github-events.ts';
+export type { GithubWebhook, GithubWebhookDelivery } from './github-events.ts';
+export { buildGithubMirrorClient, createGithubMirrorServer, githubMirrorHtml, githubMirrorState } from './github-mirror-ui.ts';
+export {
+  liveGithubExecute, observedPrsToResources, pullGithubPrs, pushGithubAction,
+  pushPendingGithubActions, syncGithubFromReal,
+} from './github-connector.ts';
+export type { GithubExecute } from './github-connector.ts';
+
+// Registry descriptor (#1).
+import type { TwinPack } from '@volter/twin';
+export const pack: TwinPack = {
+  vendor: 'github',
+  transport: 'rest',
+  bin: 'world-github',
+  resources: ['pull_request', 'pull_request_review', 'pull_request_review_comment', 'issue', 'issue_comment'],
+  specSource: 'test-fixtures/github-pull-schema.json (full GitHub OpenAPI PR schema)',
+  description: 'GitHub PR-evidence REST twin — writes, webhooks, UI mirror.',
+};