Skip to main content
Glama
README.md
# forge

[![make.fun](https://make.fun/badge/github-core-clone-01.svg)](https://make.fun/bounty/github-core-clone-01)
[![rank](https://make.fun/badge/github-core-clone-01/aboybro/forge/rank.svg)](https://make.fun/bounty/github-core-clone-01)
[![reward](https://make.fun/badge/github-core-clone-01/aboybro/forge/reward.svg)](https://make.fun/bounty/github-core-clone-01)

A GitHub-compatible git forge in one dependency-free Node process: git
smart-HTTP (protocol v2 and v0), the GitHub REST v3 API, the GraphQL v4 API and
the Model Context Protocol, all over the same in-memory store. No git binary,
no database, no network — the whole forge is the standard library.

## Run

```sh
node --experimental-strip-types main.ts
```

`main.ts` is the entrypoint the harness runs: it listens on an ephemeral port,
registers it at `$MAKEFUN_ENV_URL/register`, polls `$MAKEFUN_ENV_URL/done`
until the trial ends, then exits 0. The bearer token for every API call is
`$MAKEFUN_SHOP_TOKEN`.

For local development:

```sh
MAKEFUN_SHOP_TOKEN=dev-token node --experimental-strip-types dev.ts 8080
```

Then the forge listens on `http://127.0.0.1:8080` and the token is `dev-token`.

## What it serves

- **Git smart-HTTP** — `/{owner}/{repo}.git/info/refs`,
  `git-upload-pack` (v2 `ls-refs` and `fetch`, with a v0 fallback) and
  `git-receive-pack` (v0, `report-status` + sideband). Clone, fetch, push and
  pull work end-to-end with a real `git` client: shallow and deepen fetches,
  thin packs, OFS and REF deltas, annotated-tag peeling, unborn HEAD, and
  per-ref fast-forward validation (a non-fast-forward push is `ng` and the ref
  does not move).
- **REST v3** (`/api/v3`) — repositories (create/list/get/patch/delete, with
  pagination `Link` headers), branches, commits, git refs, contents
  (create/update/delete with real git blob SHAs), labels, issues and comments,
  pull requests with files, diff stats and squash merges. A repository belongs
  to the login the token names; the same name under another owner is 404.
- **GraphQL v4** (`/api/graphql`) — `viewer`, `repository`, `issue` and
  `pullRequest` reads, `__type` introspection, issue lists with `states`,
  `orderBy` and cursor pagination, `node(id:)` with stable opaque Relay ids,
  the `createIssue`, `closeIssue`, `createPullRequest`, `mergePullRequest` and
  `addComment` mutations, and batched operation arrays.
- **MCP** (`/mcp`) — JSON-RPC 2.0 Streamable HTTP: `server/discover` for the
  modern revision and `initialize` for the legacy handshake, `tools/list`
  with the six tools (`create_repo`, `get_repo`, `create_issue`,
  `list_issues`, `create_pull_request`, `merge_pull_request`), and `tools/call`
  acting on the same store as REST.

## Layout

- `main.ts` — the harness lifecycle (listen, register, poll `/done`, exit).
- `app.ts` — the HTTP server: routing, bearer auth, request ids, JSON bodies.
- `dev.ts` — the local runner.
- `src/store.ts` — the forge state: repos, objects, refs, issues, pull
  requests, the deterministic clock and id counters, fetch selection and the
  three-way squash merge.
- `src/gitobj.ts` — SHA-1 object ids, pkt-lines, pack read/write with delta
  resolution, tree/commit/tag parsing.
- `src/gitproto.ts` — the git wire: advertisements, ls-refs, fetch, receive-pack.
- `src/rest.ts` — the REST v3 dispatcher.
- `src/graphql.ts` — a hand-rolled GraphQL parser and executor.
- `src/mcp.ts` — the MCP endpoint.
- `src/scenario.ts` — the scenario seed: the viewer and teammate logins are
  derived from the same seed the harness uses, so the forge and the suite
  agree on who the token names.

## Determinism

Nothing a check can read depends on the wall clock or on randomness:
timestamps come from `MAKEFUN_TRIAL_NOW` (falling back to a fixed epoch) plus
a monotonic counter, and ids come from counters. The same trial replays to the
same answers.