@volter/twin-github 0.1.0 → 0.1.1

package/src/github-ui-conformance.ts

@@ -4,7 +4,7 @@
 //
 // 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;
+// client + the `mirror` store 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
@@ -40,7 +40,7 @@ export const GITHUB_UI_INVENTORY: UiSurface[] = [
   { 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
+  // reviewCommentsCount is computed + emitted in the mirror store 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

package/src/index.ts

@@ -1,23 +1,89 @@
 // @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 { applyGithubWrite, githubState, handleGithubRequest, syncPrHeadsToBranchTip, toGithubComment, toGithubIssue, toGithubRest, toGithubReview, toGithubReviewComment } from './github-twin.ts';
+// The REAL git plane: bare repos under the twin's state dir + the git smart-HTTP protocol
+// (clone/fetch/push by an unmodified `git` CLI), reconciled with the Git Data REST surface.
+export {
+  bareRepoDir, ensureBareRepo, hasBareRepo, listGitPlaneRefs, objectExistsInPlane,
+  readGitBlobFromPlane, readGitCommitFromPlane, readGitTagFromPlane, readGitTreeFromPlane,
+  updateGitRefInPlane, writeGitBlobToPlane, writeGitCommitToPlane, writeGitTagToPlane, writeGitTreeToPlane,
+} from './github-git-plane.ts';
+export { handleGithubGitSmartHttp, parseGitSmartHttpPath, reconcileGitPlaneRefs } from './github-git-http.ts';
+export type { GitSmartHttpResponse, GitSmartHttpRoute } from './github-git-http.ts';
 export type { GithubComment, GithubIssue, GithubPr, GithubResponse, GithubReview, GithubState, GithubWriteEvent, GithubWriteOutcome } from './github-twin.ts';
-export { createGithubTwinServer } from './github-server.ts';
+export { createGithubTwinFetch, 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';
+// The mirror is a pure frontend (R3): shell + assets + the mounted adapter. Its state comes
+// from the twin's store door, whose projection lives server-side in github-mirror-state.ts.
+export { buildGithubMirrorClient, createGithubMirrorServer, githubMirrorHtml } from './github-mirror-ui.ts';
+export { githubMirrorState } from './github-mirror-state.ts';
+export { GITHUB_MIRROR_STORE, GITHUB_MIRROR_STORE_PATH, GITHUB_WEB_ORIGIN, githubIssuePath, githubPullPath } from './github-shared.ts';
 export {
   liveGithubExecute, observedPrsToResources, pullGithubPrs, pushGithubAction,
-  pushPendingGithubActions, syncGithubFromReal,
+  pushGithubToRemote, pushPendingGithubActions, syncGithubFromReal, syncGithubFromRemote,
 } from './github-connector.ts';
-export type { GithubExecute } from './github-connector.ts';
+export type { GithubExecute, LiveGithubOptions } from './github-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveGithubExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is GitHub's DECLARATION — and uniquely, its weights ARE GitHub's own published point costs
+// (1 for a read, 5 for a write). Exported so an operator can inspect spend (`snapshot`) and so a
+// caller can catch `GithubBudgetError` by type; there is deliberately no export that disables it.
+export {
+  GITHUB_BUDGET_BURST_CEILING,
+  GITHUB_BUDGET_CEILING,
+  GITHUB_BUDGET_MAX_RETRY_AFTER_S,
+  GITHUB_BUDGET_WINDOW_MS,
+  GITHUB_CALL_WEIGHTS,
+  GITHUB_RATE_BUDGET,
+  GithubBudget,
+  GithubBudgetError,
+  githubBudgetPath,
+  githubCallWeight,
+} from './github-budget.ts';
+export type { GithubBudgetErrorKind, GithubBudgetOptions, GithubBudgetReservation, GithubBudgetSnapshot } from './github-budget.ts';
 
 // Registry descriptor (#1).
 import type { TwinPack } from '@volter/twin';
+import { GITHUB_RATE_BUDGET as RATE_BUDGET } from './github-budget.ts';
 export const pack: TwinPack = {
   vendor: 'github',
+  // The SAME object github-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  pullPosture: 'continuous',
+  pullPostureReason:
+    "GitHub REST is 5000 req/hour authenticated with X-RateLimit-* headers on every response, so a scheduled sync can measure its own headroom.",
   transport: 'rest',
+  archetype: 'engine-control',
   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.',
+  // Adoption + interception, all in the pack's one home (TWIN-PACK-CONTRACT back-migration
+  // 2026-08-31; the eight SDK names, the `@octokit/` scope and the bare `github`/`gh` stems moved
+  // off the central maps unchanged). The two canonical Octokit clients plus the official
+  // auth/webhook companions — each battery-observed as a repo's ONLY GitHub dep — and the whole
+  // `@octokit/` scope so an unlisted satellite still detects. Stems: the bare GITHUB_*/GH_* pair
+  // and the credential-var shapes real apps use for their GitHub App / OAuth App connections
+  // (BACKEND_GITHUB_*, INF_APP_CONNECTION_GITHUB_APP_*, …_GITHUB_OAUTH_*, …_GITHUB_RADAR_APP_*).
+  adoption: {
+    // COMMUNITY: GitHub ships no official Python SDK (octokit is JS, go-github is Go), and `PyGithub`
+    // is the de-facto Python client of the same REST API.
+    pypi: ['pygithub'],
+    sdks: [
+      '@octokit/rest', '@octokit/core', 'octokit',
+      '@octokit/auth-app', '@octokit/auth-oauth-app', '@octokit/auth-oauth-device',
+      '@octokit/graphql', '@octokit/webhooks',
+    ],
+    scopes: ['@octokit/'],
+    envStems: [
+      'GITHUB', 'GH',
+      'BACKENDGITHUB', 'INFAPPCONNECTIONGITHUBAPP',
+      'INFAPPCONNECTIONGITHUBOAUTH', 'INFAPPCONNECTIONGITHUBRADARAPP',
+      // appsmith names its GitHub OAuth app APPSMITH_OAUTH2_GITHUB_CLIENT_ID/_SECRET — the same
+      // app-prefixed shape as the INFAPPCONNECTION* stems above (ladder classification 2026-09-02).
+      'APPSMITHOAUTH2GITHUB',
+    ],
+  },
+  hosts: [{ host: 'api.github.com' }],
 };