@volter/twin-github

The GitHub twin — a local replica of the GitHub REST pull-request API on the shared @volter/twin kernel. The real @octokit/rest client works against it unmodified.

Note: local simulator/fork writes carry full content (a created PR has a title/body/diffs). The connector's pull path currently folds observed events as metadata only (counts/refs, title: null) — that is a Planned gap (full content on pull), not an out-of-scope carve-out. The only deliberate GitHub out-of-scope carve-out is actual repository code/file contents (see Coverage below).

Surface

• REST API (github-twin.ts; HTTP wrapper github-server.ts → createGithubTwinServer): list/get PRs, issues, statuses/checks, milestones, and Actions (workflows/runs/jobs; dispatch/rerun/cancel writes).
• Writes (applyGithubWrite): create PR, edit PR, submit review, issue comment — local transactions (R3/R5/R18); the --read-only flag rejects writes.
• Webhooks (github-events.ts): pull_request / pull_request_review / issue_comment with the X-GitHub-Event header.
• Conformance (github-conformance.ts): field-name subset vs the vendored GitHub REST PR schema (PR + nested base/head/repo; _twin extras excluded).
• UI mirror (github-mirror-ui.ts): a GitHub-style PR browser (React) with a per-repo selector ("multiple githubs"), over the twin's github world via /api/state; observed review/comment counts are surfaced honestly.

CLI

world-github serve [--read-only] [--port N] [--root DIR]
world-github mirror [--port N] [--root DIR]
world-github conformance [--root DIR]

Point the real @octokit/rest Octokit at it via baseUrl.

Four ways to use it

1. Mock SDK — zero edits (preferred): GITHUB_TWIN_URL=http://127.0.0.1:PORT node --require @volter/twin/inject your-app redirects the real @octokit/rest from api.github.com to the twin. Or override directly: new Octokit({ baseUrl: 'http://127.0.0.1:PORT', auth: 'twin' }).
2. API + CLI — world-github serve (writable) + drive with volter-twin status|plan|refs github, then push.
3. Read-only — world-github serve --read-only: unlimited local reads, no rate limits; writes refuse like GitHub (4xx).
4. UI mirror — world-github mirror renders a GitHub-style view of the twin's state.

(See the repo's GETTING-STARTED → "Four ways to use a twin", and cookbook/zero-edit-inject.)

Coverage

Goal: honest, explicitly tracked coverage of GitHub's core feature surface. The only accepted carve-outs are explicit out-of-scope items. Tracked in three buckets — anything not done or carved out is a gap to close.

Done — PRs (create/edit/merge/list/get; full PR/issue content on pull — title/body/state and review/comment bodies fold from real GitHub, plus full content on local writes), first-class issues (pulled from real GitHub via GET /issues, PRs excluded), shared issue/PR number space (one per-repo counter, real GitHub behavior), reviews + diff-anchored review comments, issue comments, commit statuses, check runs, requested reviewers, milestones, labels/assignees, PR files/commits (local writes), Actions (workflows + workflow runs + jobs/steps — register/ list/get workflows, workflow_dispatch → queued run, rerun/cancel transitions, run filters status/branch/event, run jobs; rendered in the UI mirror Actions view), Actions secrets/variables (repo + org scope — secret values never returned, mirroring GitHub), Actions caches (list/delete by id or key), Actions artifacts (register/list/get/delete metadata), Actions run logs (302 redirect to a signed URL; bytes out of scope), Git Data API (refs create/get/update/delete, commits, trees, blobs with content, annotated tags), deployments + deployment statuses (create/list/filter + status history), environments (create/update/delete + protection-rule summaries; rendered in the UI mirror Deployments view), org repositories (GET /orgs/:org/repos with type/sort filters), issue pin/unpin, pagination, webhooks, UI mirror (rung-5 ✅), connector (pull content+issues + push: create/edit/ merge/review/comment/status/check/milestone/reviewers).

Planned (known-missing, will do) — Projects v2, branch protection rulesets, orgs/teams/members (membership), issue types (org-level) / issue transfer, the GraphQL API (only REST today), security (code-scanning/dependabot/secret-scanning), packages/pages/codespaces. (Actions log bytes stay out — CI-compute output, see Out of scope.)

Out of scope (deliberately not modeled, with reason) —

• Actual repository code / file contents (git blob bytes, raw file bodies, packfiles): large and redundant — the API objects (trees/blobs metadata, file lists, diff stats) are still covered.
• Running real CI compute (executing Actions workflows): infra, not the API — the run/job objects are covered.