sailfork / t3code-github / .repos/ alchemy-effect/ packages/ git/ src/ GitHubCompat.ts

import type { RuntimeContext } from "alchemy/RuntimeContext";
/**
 * GitHub REST v3 compatibility facade (`/api/v3/**`) — DESIGN.md "Tier 1".
 *
 * Lets GitHub-flavored tooling talk to the service unmodified. The target
 * consumers are `gh api` (via `GH_HOST=<host>` + `GH_ENTERPRISE_TOKEN`,
 * which sends REST to `https://<host>/api/v3/...`) and Octokit-style SDKs
 * pointed at a GitHub Enterprise `baseUrl`. Only the REST plane is
 * mimicked — the `gh pr`/`gh issue` porcelain commands speak GraphQL and
 * are out of scope (use `gh api` paths instead).
 *
 * This module is a pure TRANSLATION layer: every route parses GitHub's
 * request shapes, calls the same Repo-DO RPCs the native `/api/v1` plane
 * uses (auth enforcement stays in the DO), and re-shapes responses into
 * GitHub's JSON. GitHub-isms handled here:
 *
 * - `Authorization: token <t>` (gh's scheme) — parsed by `Auth.ts`
 *   alongside Bearer/Basic.
 * - A merged PR is `state: "closed"` with `merged: true` (our tri-state
 *   `merged` collapses into GitHub's boolean).
 * - Errors are `{ message }` with GitHub's status conventions (401
 *   "Requires authentication", 404 "Not Found", 405 for unsupported merge
 *   methods, 409 for conflicts).
 * - List pagination is RFC-5988 `Link: <...>; rel="next"` headers. The
 *   next URL carries an opaque `cursor` (not a page number) — `gh api
 *   --paginate` and Octokit follow the URL verbatim, so keyset cursors
 *   work transparently.
 *
 * Deliberately absent (documented, not accidental): issues, reviews,
 * comments, checks, search, GraphQL, rename detection in file lists, and
 * additions/deletions line counts (reported as 0 — the server does not
 * compute content diffs; fetch blobs and diff client-side).
 */
import * as Effect from "effect/Effect";
import { Base64 } from "effect/encoding";
import * as HttpRouter from "effect/http/HttpRouter";
import * as HttpServerRequest from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import type { DiffEntryData } from "./Protocol/TreeDiff.ts";
import type { RegistryEntry } from "./RegistryObject.ts";
import type {
  CommitData,
  CommitDiffData,
  CompareData,
  FileData,
  MergePullResult,
  PullData,
  PullDetailData,
  PullsPage,
  RefsPage,
  RepoMetaData,
  CommitLogPage,
  SignatureData,
} from "./RepoObject.ts";

// ─────────────────────────────────────────────────────────────────────────────
// Dependencies injected by the Worker
// ─────────────────────────────────────────────────────────────────────────────

/** Outcome of the Worker's shared owner/repo + credential prelude. */
export type CompatPrelude =
  | { readonly kind: "halt"; readonly response: HttpServerResponse.HttpServerResponse }
  | { readonly kind: "ok"; readonly entry: RegistryEntry };

/** The slice of the Repo-DO stub the facade calls. */
export interface CompatRepoStub {
  readonly getRepoMeta: () => Effect.Effect<
    RepoMetaData,
    { readonly _tag: string },
    RuntimeContext
  >;
  readonly listRefs: (
    prefix?: string,
  ) => Effect.Effect<RefsPage, { readonly _tag: string }, RuntimeContext>;
  readonly readCommitLog: (input: {
    readonly ref?: string | undefined;
    readonly cursor?: string | undefined;
    readonly limit?: number | undefined;
  }) => Effect.Effect<CommitLogPage, { readonly _tag: string }, RuntimeContext>;
  readonly readCommitDiff: (input: {
    readonly oid: string;
  }) => Effect.Effect<CommitDiffData, { readonly _tag: string }, RuntimeContext>;
  readonly compareCommits: (input: {
    readonly base: string;
    readonly head: string;
  }) => Effect.Effect<CompareData, { readonly _tag: string }, RuntimeContext>;
  readonly readFileAtPath: (input: {
    readonly ref?: string | undefined;
    readonly path: string;
  }) => Effect.Effect<FileData, { readonly _tag: string }, RuntimeContext>;
  readonly createPull: (input: {
    readonly title: string;
    readonly body?: string | undefined;
    readonly base: string;
    readonly head: string;
  }) => Effect.Effect<PullData, { readonly _tag: string }, RuntimeContext>;
  readonly listPulls: (input: {
    readonly state?: "open" | "closed" | "merged" | "all" | undefined;
    readonly cursor?: string | undefined;
    readonly limit?: number | undefined;
  }) => Effect.Effect<PullsPage, { readonly _tag: string }, RuntimeContext>;
  readonly getPull: (
    number: number,
  ) => Effect.Effect<PullDetailData, { readonly _tag: string }, RuntimeContext>;
  readonly updatePull: (input: {
    readonly number: number;
    readonly title?: string | undefined;
    readonly body?: string | null | undefined;
    readonly state?: "open" | "closed" | undefined;
  }) => Effect.Effect<PullData, { readonly _tag: string }, RuntimeContext>;
  readonly mergePull: (input: {
    readonly number: number;
    readonly message?: string | undefined;
    readonly expectedHeadOid?: string | undefined;
  }) => Effect.Effect<MergePullResult, { readonly _tag: string }, RuntimeContext>;
}

export interface GitHubCompatOptions {
  /**
   * The Worker's `rawRestPrelude`: resolves `owner/repo`, parses
   * credentials (anonymous allowed — public repos), and 404s/500s early.
   */
  readonly prelude: (
    owner: string,
    repo: string,
  ) => Effect.Effect<CompatPrelude, never, HttpServerRequest.HttpServerRequest | RuntimeContext>;
  /** Repo-DO stub by repoId (the Worker's `repos.getByName`). */
  readonly stub: (repoId: string) => CompatRepoStub;
}

// ─────────────────────────────────────────────────────────────────────────────
// Small helpers
// ─────────────────────────────────────────────────────────────────────────────

const OID_RE = /^[0-9a-f]{40}$/;

const iso = (epochMs: number): string => new Date(epochMs).toISOString();

const isoSeconds = (sig: SignatureData): string => new Date(sig.date * 1000).toISOString();

/** Stable 48-bit integer id from a string (GitHub ids are numbers). */
const intId = (value: string): number => {
  let hash = 0xcbf29ce484222325n;
  for (let index = 0; index < value.length; index++) {
    hash ^= BigInt(value.charCodeAt(index));
    hash = (hash * 0x100000001b3n) & 0xffffffffffffn;
  }
  return Number(hash);
};

const shortRef = (ref: string): string => ref.replace(/^refs\/heads\//, "");

/** `https://host` of the incoming request (same derivation as remotes). */
const originOf = Effect.gen(function* () {
  const request = yield* HttpServerRequest.HttpServerRequest;
  const host = request.headers.host;
  const proto = request.headers["x-forwarded-proto"] ?? "https";
  return host === undefined ? "" : `${proto}://${host}`;
});

const ghJson = (
  value: unknown,
  options?: { readonly status?: number; readonly headers?: Record<string, string> },
) =>
  HttpServerResponse.json(value, {
    status: options?.status ?? 200,
    headers: options?.headers,
  }).pipe(Effect.orDie);

const ghError = (status: number, message: string) => ghJson({ message }, { status });

const ghNotFound = ghError(404, "Not Found");

/**
 * Maps the DO's typed error union onto GitHub's status conventions. Every
 * facade route ends with this — unknown tags become 500s via `Effect.die`
 * (defects, not silent 200s).
 */
const ghCatch = <A, R>(
  effect: Effect.Effect<A, { readonly _tag: string; readonly message?: string }, R>,
): Effect.Effect<A | HttpServerResponse.HttpServerResponse, never, R> =>
  effect.pipe(
    Effect.catchIf(
      (error): error is { _tag: string } => typeof error?._tag === "string",
      (error) => {
        switch (error._tag) {
          case "RepoNotFound":
          case "RefNotFound":
          case "ObjectNotFound":
          case "PullNotFound":
          case "BranchMissing":
            return ghNotFound;
          case "WrongObjectType":
          case "ValidationError":
          case "NoMergeBase":
            return ghError(422, "Validation Failed");
          case "PullExists":
            return ghError(
              422,
              "Validation Failed: a pull request already exists for this head/base",
            );
          case "PullStateConflict":
          case "NothingToMerge":
            return ghError(405, "Pull Request is not mergeable");
          case "MergeConflict":
            return ghError(409, "Merge conflict");
          case "RefConflict":
            return ghError(409, "Head branch was modified. Review and try the merge again.");
          case "ReadOnlyRepo":
            return ghError(403, "Repository is archived (read-only)");
          case "StoreError":
            return ghError(500, "Internal error");
          default:
            return Effect.die(error);
        }
      },
    ),
  );

// ─────────────────────────────────────────────────────────────────────────────
// Shape mappers (our data → GitHub JSON)
// ─────────────────────────────────────────────────────────────────────────────

const ghUser = (login: string) => ({
  login,
  id: intId(login),
  node_id: `U_${login}`,
  type: "User",
  site_admin: false,
});

const ghRepo = (meta: RepoMetaData, origin: string) => ({
  id: intId(meta.repoId),
  node_id: meta.repoId,
  name: meta.name,
  full_name: `${meta.owner}/${meta.name}`,
  owner: ghUser(meta.owner),
  private: !meta.public,
  visibility: meta.public ? "public" : "private",
  html_url: `${origin}/${meta.owner}/${meta.name}`,
  description: meta.description,
  fork: meta.forkOf !== null,
  url: `${origin}/api/v3/repos/${meta.owner}/${meta.name}`,
  clone_url: `${origin}/${meta.owner}/${meta.name}.git`,
  git_url: `${origin}/${meta.owner}/${meta.name}.git`,
  ssh_url: `${origin}/${meta.owner}/${meta.name}.git`,
  default_branch: meta.defaultBranch,
  created_at: iso(meta.createdAt),
  updated_at: iso(meta.createdAt),
  pushed_at: iso(meta.createdAt),
  archived: meta.readOnly,
  disabled: false,
  size: Math.ceil(meta.objects.bytes / 1024),
});

const ghCommit = (commit: CommitData, origin: string, repoUrl: string) => ({
  sha: commit.oid,
  node_id: commit.oid,
  url: `${repoUrl}/commits/${commit.oid}`,
  html_url: `${origin.replace("/api/v3", "")}`,
  commit: {
    message: commit.message,
    author: {
      name: commit.author.name,
      email: commit.author.email,
      date: isoSeconds(commit.author),
    },
    committer: {
      name: commit.committer.name,
      email: commit.committer.email,
      date: isoSeconds(commit.committer),
    },
    tree: { sha: commit.tree },
  },
  author: null,
  committer: null,
  parents: commit.parents.map((sha) => ({ sha, url: `${repoUrl}/commits/${sha}` })),
});

/**
 * One changed file, GitHub `pulls/:n/files` shape. `additions`/`deletions`
 * are 0 by design: the server never computes content diffs (DESIGN.md
 * §"content diffs are client-side").
 */
const ghFile = (entry: DiffEntryData) => ({
  sha: entry.newOid ?? entry.oldOid ?? "",
  filename: entry.path,
  status: entry.status,
  additions: 0,
  deletions: 0,
  changes: 0,
  previous_filename: undefined,
});

const ghPullState = (state: PullData["state"]): "open" | "closed" =>
  state === "open" ? "open" : "closed";

const ghPull = (pull: PullData & Partial<PullDetailData>, meta: RepoMetaData, origin: string) => {
  const repoUrl = `${origin}/api/v3/repos/${meta.owner}/${meta.name}`;
  return {
    id: intId(`${meta.repoId}#${pull.number}`),
    node_id: `PR_${meta.repoId}_${pull.number}`,
    number: pull.number,
    state: ghPullState(pull.state),
    merged: pull.state === "merged",
    locked: false,
    draft: false,
    title: pull.title,
    body: pull.body,
    user: ghUser(meta.owner),
    html_url: `${origin}/${meta.owner}/${meta.name}/pulls/${pull.number}`,
    url: `${repoUrl}/pulls/${pull.number}`,
    created_at: iso(pull.createdAt),
    updated_at: iso(pull.updatedAt),
    closed_at: pull.state === "open" ? null : iso(pull.updatedAt),
    merged_at: pull.mergedAt === null ? null : iso(pull.mergedAt ?? 0),
    merge_commit_sha: pull.mergeCommit,
    base: {
      ref: shortRef(pull.baseRef),
      label: `${meta.owner}:${shortRef(pull.baseRef)}`,
      sha: pull.baseOid ?? "",
      repo: { full_name: `${meta.owner}/${meta.name}` },
    },
    head: {
      ref: shortRef(pull.headRef),
      label: `${meta.owner}:${shortRef(pull.headRef)}`,
      sha: pull.headOid ?? "",
      repo: { full_name: `${meta.owner}/${meta.name}` },
    },
    mergeable: pull.mergeable ?? null,
    mergeable_state:
      pull.mergeableReason === "conflict" ? "dirty" : pull.mergeable === true ? "clean" : "unknown",
  };
};

// ─────────────────────────────────────────────────────────────────────────────
// The routes
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Builds the `/api/v3` route layer. Mounted by the GitWorker next to the
 * git wire routes; every repo-scoped route flows through the same
 * `prelude` (owner/name resolution)
 * as the raw REST routes.
 */
export const gitHubCompatRoutes = (options: GitHubCompatOptions) => {
  const { prelude, stub } = options;

  /** Repo-scoped route body: prelude, then handler with entry+auth. */
  const withRepo = <R>(
    handler: (context: {
      readonly entry: RegistryEntry;
      readonly repo: CompatRepoStub;
      readonly origin: string;
      readonly repoUrl: string;
      readonly request: HttpServerRequest.HttpServerRequest;
      readonly url: URL;
      readonly params: Readonly<Record<string, string | undefined>>;
    }) => Effect.Effect<HttpServerResponse.HttpServerResponse, { readonly _tag: string }, R>,
  ) =>
    Effect.gen(function* () {
      const request = yield* HttpServerRequest.HttpServerRequest;
      const params = yield* HttpRouter.params;
      const owner = (params.owner ?? "").toLowerCase();
      const name = (params.repo ?? "").toLowerCase();
      const resolved = yield* prelude(owner, name);
      if (resolved.kind === "halt") {
        // The prelude's plain-text halts become GitHub JSON errors.
        const status = resolved.response.status;
        return yield* status === 404 ? ghNotFound : ghError(status, "Internal error");
      }
      const origin = yield* originOf;
      const result = yield* ghCatch(
        handler({
          entry: resolved.entry,
          repo: stub(resolved.entry.repoId),
          origin,
          repoUrl: `${origin}/api/v3/repos/${owner}/${name}`,
          request,
          url: new URL(request.url, "http://internal"),
          params,
        }),
      );
      return result as HttpServerResponse.HttpServerResponse;
    });

  /** `Link: <…>; rel="next"` for cursor pages, GitHub-style. */
  const linkHeaders = (
    base: string,
    query: URLSearchParams,
    nextCursor: string | null,
  ): Record<string, string> => {
    if (nextCursor === null) return {};
    const next = new URLSearchParams(query);
    next.set("cursor", nextCursor);
    return { link: `<${base}?${next}>; rel="next"` };
  };

  const perPage = (url: URL): number => {
    const raw = Number.parseInt(url.searchParams.get("per_page") ?? "30", 10);
    return Number.isFinite(raw) ? Math.max(1, Math.min(raw, 100)) : 30;
  };

  /** Resolves `:sha` path segments that may be refs (GitHub allows both). */
  const resolveSha = (repo: CompatRepoStub, revision: string) =>
    OID_RE.test(revision)
      ? Effect.succeed(revision)
      : repo
          .readCommitLog({ ref: revision, limit: 1 })
          .pipe(Effect.map((page) => page.items[0]?.oid ?? revision));

  return {
    /** `GET /api/v3/user` — the credential probe; override the `user` handler in your `github` group to answer from your users. */
    user: () => ghJson(ghUser("git")),
    /** `GET /api/v3/repos/:owner/:repo` */
    repo: () =>
      withRepo(({ repo, origin }) =>
        repo.getRepoMeta().pipe(Effect.flatMap((meta) => ghJson(ghRepo(meta, origin)))),
      ),
    /** `GET /api/v3/repos/:owner/:repo/branches` */
    branches: () =>
      withRepo(({ repo }) =>
        repo.listRefs("refs/heads/").pipe(
          Effect.flatMap((page) =>
            ghJson(
              page.refs.map((ref) => ({
                name: shortRef(ref.name),
                commit: { sha: ref.oid },
                protected: false,
              })),
            ),
          ),
        ),
      ),
    /** `GET /api/v3/repos/:owner/:repo/commits` */
    commits: () =>
      withRepo(({ repo, origin, repoUrl, url }) =>
        repo
          .readCommitLog({
            ref: url.searchParams.get("sha") ?? undefined,
            cursor: url.searchParams.get("cursor") ?? undefined,
            limit: perPage(url),
          })
          .pipe(
            Effect.flatMap((page) =>
              ghJson(
                page.items.map((commit) => ghCommit(commit, origin, repoUrl)),
                {
                  headers: linkHeaders(
                    `${repoUrl}/commits`,
                    url.searchParams,
                    page.hasMore ? page.nextCursor : null,
                  ),
                },
              ),
            ),
          ),
      ),
    /** `GET /api/v3/repos/:owner/:repo/commits/:sha` */
    commit: () =>
      withRepo(({ repo, origin, repoUrl, params }) =>
        Effect.gen(function* () {
          const oid = yield* resolveSha(repo, params.sha ?? "");
          const log = yield* repo.readCommitLog({ ref: oid, limit: 1 });
          const commit = log.items[0];
          if (commit === undefined) return yield* ghNotFound;
          const diff = yield* repo.readCommitDiff({ oid });
          return yield* ghJson({
            ...ghCommit(commit, origin, repoUrl),
            files: diff.files.map(ghFile),
          });
        }),
      ),
    /** `GET /api/v3/repos/:owner/:repo/contents/*` */
    contents: () =>
      withRepo(({ repo, url, repoUrl }) =>
        Effect.gen(function* () {
          const marker = "/contents/";
          const at = url.pathname.indexOf(marker);
          const path = decodeURIComponent(url.pathname.slice(at + marker.length));
          if (path.length === 0) return yield* ghNotFound;
          const ref = url.searchParams.get("ref") ?? undefined;
          const file = yield* repo.readFileAtPath({ ref, path });
          return yield* ghJson({
            type: "file",
            encoding: "base64",
            size: file.size,
            name: path.split("/").pop(),
            path,
            sha: file.oid,
            url: `${repoUrl}/contents/${path}`,
            content: Base64.encode(file.content),
          });
        }),
      ),
    /** `GET /api/v3/repos/:owner/:repo/pulls` */
    pulls: () =>
      withRepo(({ repo, origin, repoUrl, url }) =>
        Effect.gen(function* () {
          // GitHub's `closed` includes merged; our store distinguishes.
          const requested = url.searchParams.get("state") ?? "open";
          const state =
            requested === "open"
              ? ("open" as const)
              : requested === "all"
                ? ("all" as const)
                : ("all" as const);
          const page = yield* repo.listPulls({
            state,
            cursor: url.searchParams.get("cursor") ?? undefined,
            limit: perPage(url),
          });
          const meta = yield* repo.getRepoMeta();
          const items = page.items.filter((pull) =>
            requested === "all"
              ? true
              : requested === "open"
                ? pull.state === "open"
                : pull.state !== "open",
          );
          return yield* ghJson(
            items.map((pull) => ghPull(pull, meta, origin)),
            {
              headers: linkHeaders(
                `${repoUrl}/pulls`,
                url.searchParams,
                page.hasMore ? page.nextCursor : null,
              ),
            },
          );
        }),
      ),
    /** `POST /api/v3/repos/:owner/:repo/pulls` */
    createPull: () =>
      withRepo(({ repo, origin, request }) =>
        Effect.gen(function* () {
          const body = (yield* request.json.pipe(
            Effect.mapError(() => ({ _tag: "ValidationError" as const })),
          )) as { title?: string; head?: string; base?: string; body?: string };
          if (!body.title || !body.head || !body.base) {
            return yield* ghError(422, "Validation Failed: title, head and base are required");
          }
          const pull = yield* repo.createPull({
            title: body.title,
            body: body.body,
            base: body.base,
            head: body.head,
          });
          const meta = yield* repo.getRepoMeta();
          return yield* ghJson(ghPull(pull, meta, origin), { status: 201 });
        }),
      ),
    /** `GET /api/v3/repos/:owner/:repo/pulls/:number` */
    pull: () =>
      withRepo(({ repo, origin, params }) =>
        Effect.gen(function* () {
          const number = Number.parseInt(params.number ?? "", 10);
          if (!Number.isFinite(number)) return yield* ghNotFound;
          const pull = yield* repo.getPull(number);
          const meta = yield* repo.getRepoMeta();
          return yield* ghJson(ghPull(pull, meta, origin));
        }),
      ),
    /** `PATCH /api/v3/repos/:owner/:repo/pulls/:number` */
    updatePull: () =>
      withRepo(({ repo, origin, params, request }) =>
        Effect.gen(function* () {
          const number = Number.parseInt(params.number ?? "", 10);
          if (!Number.isFinite(number)) return yield* ghNotFound;
          const body = (yield* request.json.pipe(
            Effect.mapError(() => ({ _tag: "ValidationError" as const })),
          )) as { title?: string; body?: string | null; state?: string };
          if (body.state !== undefined && body.state !== "open" && body.state !== "closed") {
            return yield* ghError(422, "Validation Failed: invalid state");
          }
          const pull = yield* repo.updatePull({
            number,
            title: body.title,
            body: body.body,
            state: body.state as "open" | "closed" | undefined,
          });
          const meta = yield* repo.getRepoMeta();
          return yield* ghJson(ghPull(pull, meta, origin));
        }),
      ),
    /** `PUT /api/v3/repos/:owner/:repo/pulls/:number/merge` */
    mergePull: () =>
      withRepo(({ repo, params, request }) =>
        Effect.gen(function* () {
          const number = Number.parseInt(params.number ?? "", 10);
          if (!Number.isFinite(number)) return yield* ghNotFound;
          const raw = yield* request.json.pipe(Effect.orElseSucceed(() => ({})));
          const body = raw as { commit_message?: string; sha?: string; merge_method?: string };
          if (body.merge_method !== undefined && body.merge_method !== "merge") {
            // squash/rebase rewrite history server-side — not supported.
            return yield* ghError(405, `Merge method '${body.merge_method}' is not supported`);
          }
          const result = yield* repo.mergePull({
            number,
            message: body.commit_message,
            expectedHeadOid: body.sha,
          });
          return yield* ghJson({
            sha: result.oid,
            merged: true,
            message: "Pull Request successfully merged",
          });
        }),
      ),
    /** `GET /api/v3/repos/:owner/:repo/pulls/:number/files` */
    pullFiles: () =>
      withRepo(({ repo, params }) =>
        Effect.gen(function* () {
          const number = Number.parseInt(params.number ?? "", 10);
          if (!Number.isFinite(number)) return yield* ghNotFound;
          const pull = yield* repo.getPull(number);
          // Open PR with live branches: three-dot compare. Merged PR: the
          // merge commit's first-parent diff is the canonical record.
          if (pull.baseOid !== null && pull.headOid !== null) {
            const compare = yield* repo.compareCommits({ base: pull.baseRef, head: pull.headRef });
            return yield* ghJson(compare.files.map(ghFile));
          }
          if (pull.mergeCommit !== null) {
            const diff = yield* repo.readCommitDiff({ oid: pull.mergeCommit });
            return yield* ghJson(diff.files.map(ghFile));
          }
          return yield* ghJson([]);
        }),
      ),
  };
};