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

@volter/twin-github 0.1.0 → 0.1.1

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 (21) hide show

package/README.md +162 -20
package/client/github-mirror.tsx +10 -4
package/package.json +2 -2
package/src/cli.ts +3 -2
package/src/github-a11y-snapshot.uitest.ts +117 -0
package/src/github-budget.ts +198 -0
package/src/github-capabilities.ts +502 -23
package/src/github-connector.ts +832 -61
package/src/github-events.ts +11 -1
package/src/github-git-http.ts +248 -0
package/src/github-git-plane.ts +511 -0
package/src/github-graphql.ts +212 -1
package/src/github-journey.uitest.ts +193 -0
package/src/github-mirror-state.ts +369 -0
package/src/github-mirror-ui.ts +53 -372
package/src/github-server.ts +125 -21
package/src/github-shared.ts +26 -0
package/src/github-twin.ts +821 -53
package/src/github-ui-conformance.ts +2 -2
package/src/index.ts +71 -5
package/test-fixtures/github-openapi-operations.json +467 -34

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

@@ -1,18 +1,16 @@
-// 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.
+// 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 { createGithubTwinFetch } from './github-server.ts';
-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 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">
@@ -22,7 +20,7 @@ const APP_SHELL = `<!doctype html>
 let clientBundle: Promise<string> | null = null;
 export function buildGithubMirrorClient(): Promise<string> {
   if (!clientBundle) {
-    clientBundle = Bun.build({ entrypoints: [CLIENT_ENTRY], target: 'browser', minify: true })
+    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();
@@ -32,362 +30,43 @@ export function buildGithubMirrorClient(): Promise<string> {
   return clientBundle;
 }
-const OBSERVED = 'content not mirrored by the evidence twin';
+// 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: Request): boolean {
+  return request.method === 'GET' && (request.headers.get('accept') ?? '').includes('text/html');
+}
-/** 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(),
-  };
+// 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: string): boolean {
+  return /^\/[^/]+\/[^/]+\/(?:info\/refs|git-upload-pack|git-receive-pack)$/.test(pathname);
 }
-/** Serve the GitHub UI mirror (React app) + its `/api/state` backing the client. */
+/**
+ * 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 function createGithubMirrorServer(options: { root?: string; port?: number }): { port: number; stop: () => void } {
+  const twin = createGithubTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}) });
   const server = Bun.serve({
+    // 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) {
@@ -397,15 +76,17 @@ export function createGithubMirrorServer(options: { root?: string; port?: number
         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));
+        return new Response(Bun.file(CLIENT_CSS()), { headers: { 'content-type': 'text/css; charset=utf-8' } });
       }
-      if (request.method === 'GET') {
+      // 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' } });
       }
-      return new Response('method not allowed', { status: 405 });
+      // 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) };

package/src/github-server.ts CHANGED Viewed

@@ -2,34 +2,138 @@
 // `@octokit/rest` client (pointed at this baseUrl) works unmodified (R1). Reads
 // fold observed evidence + action overlay; writes (simulator/fork) become local
 // actions and fire GitHub webhooks (R17). Mirror mode rejects writes (R4).
+// The git SMART-HTTP protocol (clone/fetch/push by an unmodified `git` CLI) is served
+// FIRST — its routes (/:owner/:repo/info/refs, git-upload-pack, git-receive-pack) are
+// binary pkt-line streams bridged to real `git` subprocesses (github-git-http.ts); a
+// receive-pack push emits `push` webhooks through the same emitGithubEvent pipeline.
 import { applyGithubWrite, handleGithubRequest } from './github-twin.ts';
+import { worldNow, statefulTwinManifest} from '@volter/twin';
 import { emitGithubEvent } from './github-events.ts';
+import { handleGithubGitSmartHttp, parseGitSmartHttpPath } from './github-git-http.ts';
+import { githubMirrorState } from './github-mirror-state.ts';
+import { GITHUB_MIRROR_STORE } from './github-shared.ts';
-export function createGithubTwinServer(options: { root?: string; port?: number; readOnly?: boolean }): { port: number; stop: () => void } {
+// THE STORE DOOR (runtime contract R5c; mirror purity R3): named, deterministic projections
+// over stored state, served at `GET /twin/store/<name>` and listed in the manifest as
+// `stores` — the kernel adapter's door (`createTwinFetchFromHandler`), carried here by the
+// pack's own fetch because github's wire exceeds the handler shape (the git smart-HTTP
+// plane's binary pkt-line streams). GitHub's ONE store is `mirror`: everything the mirror
+// console renders, projected from the folded state (`github-mirror-state.ts`), so the
+// mirror reads twin state ONLY over this door — never by importing the handler. The
+// door's shapes — the manifest's `stores` + `doors.store`, the 404 body for an unknown
+// name — are the kernel door's, byte for byte.
+const STORE_DOOR = '/twin/store/';
+/** 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 };
+/**
+ * The whole GitHub serve path as a plain `(Request) => Response` — the `/twin` manifest, the
+ * git smart-HTTP bridge, REST reads and the write path with its webhook emission. NOTHING
+ * about it is port-bound, and `createGithubTwinServer` is one line of `Bun.serve` around it,
+ * so the standalone (R1) and any in-process lane execute the SAME bytes of serving code.
+ *
+ * The GIT PLANE is a BUN-SHELL CAPABILITY, not a serve-path prerequisite: real bare repos
+ * on a real filesystem driven by real `git` subprocesses (github-git-plane.ts —
+ * `Bun.spawnSync(['git', …])` + `node:fs` under `worldPaths('github')`, bypassing the
+ * WorldStore seam by design: "the bare repo IS the object store, one store not two").
+ * Every plane touch on the REST read path is EXISTENCE-GUARDED (`hasBareRepo` →
+ * `existsSync`), so on a shell with no plane (workerd: no `git`, empty virtual fs) the
+ * plane is simply ABSENT — reads answer from the folded observed/action state alone, which
+ * is exactly what a pull-fed remote mirror serves (R14: `syncGithubFromRemote` folds PRs,
+ * reviews, comments and issues; none of that needs the plane). The git smart-HTTP branch
+ * is the one route that cannot degrade: it refuses loudly where `git` cannot be spawned,
+ * because a clone/push against a plane-less shell has no honest answer but no.
+ */
+export function createGithubTwinFetch(options: GithubTwinOptions): (request: Request) => Promise<Response> {
   const readOnly = options.readOnly ?? false;
+  const stores: Record<string, () => unknown> = { [GITHUB_MIRROR_STORE]: () => githubMirrorState(options.root) };
+  const storeNames = Object.keys(stores).sort();
+  return async function githubTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    const cleanPath = url.pathname.replace(/\/+$/, '') || '/';
+    // GET /twin — the discovery manifest (education inside the twin). It EDUCATES the
+    // kernel door's way: the store names + the door's path ride on the manifest.
+    if (request.method === 'GET' && cleanPath === '/twin') {
+      const manifest = statefulTwinManifest({ vendor: 'github', twinOf: 'the GitHub REST pull-request API', stores: 'repositories, pull requests, reviews and comments' });
+      const doors = manifest.doors !== null && typeof manifest.doors === 'object' ? (manifest.doors as Record<string, unknown>) : {};
+      return Response.json({ ...manifest, stores: storeNames, doors: { ...doors, store: 'GET /twin/store/<name>' } });
+    }
+    // GET /twin/store/<name> — the store door (see STORE_DOOR above).
+    if (request.method === 'GET' && cleanPath.startsWith(STORE_DOOR)) {
+      const name = cleanPath.slice(STORE_DOOR.length);
+      const store = stores[name];
+      if (store === undefined) return Response.json({ error: 'unknown store', store: name, stores: storeNames }, { status: 404 });
+      return Response.json(store());
+    }
+    const path = url.pathname + url.search;
+    // git smart-HTTP (binary protocol, not JSON) — try first; null means "not a git route".
+    // Route-parse BEFORE touching the body so ordinary REST POSTs are never double-buffered.
+    if ((request.method === 'GET' || request.method === 'POST') && parseGitSmartHttpPath(request.method, url.pathname)) {
+      // Plane-less shells (workerd) cannot spawn git: refuse the protocol loudly instead
+      // of dying mid-pkt-line. The REST evidence surface below still serves.
+      if (typeof Bun === 'undefined' || typeof Bun.spawnSync !== 'function') {
+        return Response.json({ message: 'git smart-HTTP is not served on this deployment (no git plane); the REST evidence surface is' }, { status: 501 });
+      }
+      const occurredAt = worldNow();
+      const git = await handleGithubGitSmartHttp({
+        method: request.method,
+        pathname: url.pathname,
+        query: url.searchParams,
+        ...(request.method === 'POST' ? { body: new Uint8Array(await request.arrayBuffer()) } : {}),
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        readOnly,
+        contentEncoding: request.headers.get('content-encoding') ?? '',
+        gitProtocol: request.headers.get('git-protocol') ?? '',
+        occurredAt,
+      });
+      if (git) {
+        // Webhook delivery is fire-and-forget (real GitHub: a delivery failure never fails
+        // the push) — a dead emit pipeline reddens the webhook verifies, not the protocol.
+        for (const webhook of git.webhooks) { try { await emitGithubEvent(webhook, { occurredAt }); } catch { /* fire-and-forget */ } }
+        return new Response(git.body as BodyInit, { status: git.status, headers: { 'content-type': git.contentType, 'cache-control': 'no-cache' } });
+      }
+    }
+    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();
+      // THE WORLD INSTANT, threaded into the write (R9). Without it `applyGithubWrite` falls back
+      // to `new Date().toISOString()`, and every wall-clock stamp it lands — `created_at`/
+      // `updated_at` on repos, issues, comments, reviews, statuses — differs between two
+      // identical worlds. The same instant then stamps the webhook deliveries below, so a write
+      // and its delivery can never disagree about when they happened.
+      const occurredAt = worldNow();
+      const outcome = await applyGithubWrite({ method: request.method, path, body: text, ...(options.root !== undefined ? { root: options.root } : {}), readOnly, occurredAt });
+      // Defensive 500 (never a thrown socket error) when a handler yields no response —
+      // real servers answer 500 to a handler fault; a throw here would surface as an
+      // unhandled rejection in embedding test runners instead of an HTTP status.
+      const response = outcome?.response;
+      if (!response) return Response.json({ message: 'twin handler returned no response' }, { status: 500 });
+      // Fire-and-forget, like real GitHub: a webhook delivery failure never fails the write.
+      for (const event of [...(outcome.webhook ? [outcome.webhook] : []), ...(outcome.webhooks ?? [])]) {
+        try { await emitGithubEvent(event, { occurredAt }); } catch { /* fire-and-forget */ }
+      }
+      // 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 });
+  };
+}
+export function createGithubTwinServer(options: GithubTwinOptions): { port: number; stop: () => void } {
   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 });
-    },
+    fetch: createGithubTwinFetch(options),
   });
   return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
 }