@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/github-mirror-state.js

@@ -0,0 +1,335 @@
+// GitHub MIRROR STATE — the ONE named store the mirror console renders (runtime contract
+// R5, the store door; R3, mirror purity): `GET /twin/store/mirror`, declared on the pack's
+// own fetch adapter (`github-server.ts`) and served from it. A deterministic projection of
+// the stored state — pull requests grouped by repo (the per-repo selector), issues,
+// reviews/comments, Actions, releases, discussions, contents, notifications, deployments,
+// projects, insights and settings — built from the twin's own evidence + local-write state.
+// No wall-clock, no randomness: the same stored state projects the same bytes. Server-side
+// only — the mirror module (`github-mirror-ui.ts`) never imports this; it reads the door
+// over the wire. The git plane (bare repos, smart-HTTP) is never read here: the projection
+// is over the folded REST state alone.
+//
+// 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.js";
+import { GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from "./github-shared.js";
+const OBSERVED = 'content not mirrored by the evidence twin';
+/** The `mirror` store: the whole console payload, projected from the twin's github world. */
+export function githubMirrorState(root) {
+    const { prs: foldedPrs, issues, reviews: foldedReviews, comments: foldedComments, statuses, checkRuns, milestones, workflows: foldedWorkflows, workflowRuns, jobs, releases: foldedReleases, releaseAssets, tags, discussions: foldedDiscussions, discussionComments: foldedDiscussionComments, 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);
+    // Only PULL REQUESTS are pull requests. The fold's `prs` map also holds the shells it
+    // materializes for the review/comment counters, which hang off issue numbers too — the
+    // mirror is a door onto the same world the REST list serves, and the two must agree about
+    // what a pull request is.
+    const prs = foldedPrs.filter((p) => p.is_pull_request);
+    // 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, headSha) => {
+        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 = [
+            ...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: `${GITHUB_WEB_ORIGIN}${githubPullPath(pr.repository, 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 and per-file diffs live in the git plane, which this projection does not read: the console
+    // reads them over REST (client/pulls-rest.ts).
+    const commits = [];
+    const files = [];
+    // 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: `${GITHUB_WEB_ORIGIN}${githubIssuePath(iss.repository, 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,
+            // 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) => {
+        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: `${GITHUB_WEB_ORIGIN}/${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: `${GITHUB_WEB_ORIGIN}/${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();
+    for (const r of discussionRepos)
+        for (const c of discussionCategoriesFor(r))
+            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: `${GITHUB_WEB_ORIGIN}/${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: `${GITHUB_WEB_ORIGIN}/${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 boards — the Project board screen. Each project carries its views and its first single-select
+    //   field's options as COLUMNS, with its items grouped into them by that field's value; an item with none lands
+    //   in "No Status" (GitHub's board). Data-coupled: a field, an item or a value moves what 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');
+        const items = foldedProjectItems.filter((i) => i.project_id === p.id);
+        const card = (i) => ({ id: i.id, title: i.title ?? `#${i.content_number ?? i.id}`, contentType: i.content_type });
+        const optionOf = (i) => statusField?.options?.find((o) => o.id === i.field_values?.[statusField.id]);
+        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: (statusField?.options ?? []).map((o) => ({ name: o.name, cards: items.filter((i) => optionOf(i)?.id === o.id).map(card) })),
+            noStatus: { name: 'No Status', cards: items.filter((i) => !optionOf(i)).map(card) },
+            url: `${GITHUB_WEB_ORIGIN}/${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). Data-coupled: each new
+    //   PR/issue moves a Pulse count.
+    const repoNames = new Set([...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);
+        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,
+            },
+            // commit authors live in the git plane, which this projection does not read
+            contributors: [],
+        };
+    });
+    // ── 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 },
+    };
+}

package/dist/src/github-mirror-ui.d.ts

@@ -0,0 +1,20 @@
+export declare function buildGithubMirrorClient(): Promise<string>;
+/**
+ * Serve the GitHub UI mirror (React app) with the twin's own fetch adapter mounted beside it.
+ *
+ * Every data path on this host IS the twin: reads fold from stored state, writes go through
+ * the twin's real write path (webhooks emitted like every write), the doors answer — the
+ * exact closure `createGithubTwinServer` serves, so the mirror host and the API host cannot
+ * drift. There is no mirror-private route: `/api/state` (the old fold) answers with the
+ * vendor's own `Not Found` envelope, because GitHub has no such endpoint.
+ */
+export declare function createGithubMirrorServer(options: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+export declare function githubMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function githubMirrorStyles(): Promise<string>;

package/dist/src/github-mirror-ui.js

@@ -0,0 +1,101 @@
+// GitHub UI mirror (scorecard R13) — a GitHub-style React app (Bun-bundled) over the
+// twin's github world. A PURE FRONTEND (runtime contract R3): this module is the shell +
+// its assets and one listener that mounts the pack's OWN fetch adapter beside them. It
+// imports no handler and no twin-internal module, and holds no mirror-private data path:
+// the client reads the world through the twin's store door (`GET /twin/store/mirror`, the
+// ONE named projection `github-mirror-state.ts` builds server-side), and any write a
+// console makes goes through the vendor's own REST API on the same origin — the wire a
+// real GitHub client speaks, so the mirror renders a twin or a real account unchanged,
+// pointed at any origin by configuration. The client is the shared world UI-mirror design.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createGithubTwinFetch } from "./github-server.js";
+const CLIENT_ENTRY = () => new URL('../client/github-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/github-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><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>`;
+// cache: the built client bundle, memoized per process — a build artifact, never twin state (the tree
+// holds what this UI renders); cleared on a failed build so the next request rebuilds.
+let clientBundle = null;
+export function buildGithubMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+// GitHub's REST surface and the console's own routes share ONE path grammar (real GitHub
+// splits them across its API host and its web host): `/pulls`, `/notifications`,
+// `/projects/…` and `/{owner}/{repo}/…` are both an API path and a console deep link. On
+// this one host a request is the console's when it is a DOCUMENT NAVIGATION — the browser
+// asks for `text/html` — and the twin's otherwise (an API client and the console's own
+// store read ask for JSON), the ordinary history-fallback rule every SPA host applies.
+function wantsDocument(request) {
+    return request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html');
+}
+// The git smart-HTTP grammar (`/{owner}/{repo}/info/refs`, `…/git-upload-pack`,
+// `…/git-receive-pack`): the git plane stays on the twin's API host — the console host
+// carries no clone/push lane, so a git client here gets the plain refusal, never the shell.
+function isGitSmartHttpPath(pathname) {
+    return /^\/[^/]+\/[^/]+\/(?:info\/refs|git-upload-pack|git-receive-pack)$/.test(pathname);
+}
+/**
+ * Serve the GitHub UI mirror (React app) with the twin's own fetch adapter mounted beside it.
+ *
+ * Every data path on this host IS the twin: reads fold from stored state, writes go through
+ * the twin's real write path (webhooks emitted like every write), the doors answer — the
+ * exact closure `createGithubTwinServer` serves, so the mirror host and the API host cannot
+ * drift. There is no mirror-private route: `/api/state` (the old fold) answers with the
+ * vendor's own `Not Found` envelope, because GitHub has no such endpoint.
+ */
+export async function createGithubMirrorServer(options) {
+    const twin = createGithubTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}) });
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+        // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+        // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+        // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+        // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+        // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+        // on loopback, so the verify's fetches deterministically reach THIS server.
+        hostname: '127.0.0.1',
+        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 fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            // The uniform doors (`/twin`, `/twin/store/<name>`) are the twin's, whoever asks.
+            if (url.pathname === '/twin' || url.pathname.startsWith('/twin/'))
+                return twin(request);
+            if (isGitSmartHttpPath(url.pathname))
+                return new Response('not found', { status: 404 });
+            // The console: its root and every document navigation (deep links included).
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '' || wantsDocument(request))) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // Everything else is the vendor's wire: the mounted adapter answers as the API host would.
+            return twin(request);
+        },
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+export function githubMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function githubMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

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

@@ -0,0 +1,14 @@
+/** Options shared by the fetch handler and the Bun.serve wrapper around it. `port` is a BIND
+ *  concern the fetch ignores; it stays in one shape so a caller configures the twin once
+ *  whichever way it is mounted. */
+export type GithubTwinOptions = {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+    clock?: () => string;
+};
+export declare function createGithubTwinFetch(options: GithubTwinOptions): (request: Request) => Promise<Response>;
+export declare function createGithubTwinServer(options: GithubTwinOptions): Promise<{
+    port: number;
+    stop: () => void;
+}>;