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

/**
 * Shared schemas of the git-service REST contract (DESIGN.md §5):
 * primitives, the tagged-error taxonomy, and the domain shapes. The
 * per-group endpoint declarations live in the sibling modules (`Repos.ts`,
 * `Refs.ts`, `Objects.ts`, `Pulls.ts`); the assembled `GitApi` lives in
 * `../Api.ts`.
 *
 * The groups carry no middleware and no auth errors of their own: the
 * `HttpApi` you mount them in decides who may call them, and application handlers
 * decide which refs may move.
 */
import * as Schema from "effect/Schema";
// Pulls in the `httpApiStatus` annotation augmentation used by the error
// classes below.
import "effect/http-api/HttpApiSchema";

// ─────────────────────────────────────────────────────────────────────────────
// Primitives
// ─────────────────────────────────────────────────────────────────────────────

/**
 * A 40-hex SHA-1 object id, branded so oids never mix with plain strings.
 * Widening to SHA-256 later is mechanical because every consumer goes
 * through this schema (DESIGN.md §1 "Hashing").
 */
export const Oid = Schema.String.check(Schema.isPattern(/^[0-9a-f]{40}$/)).pipe(
  Schema.brand("Oid"),
);

/** The decoded (branded) type of {@link Oid}. */
export type Oid = typeof Oid.Type;

/**
 * A repository name: 1–100 chars, alphanumeric with `._-` separators,
 * must start and end alphanumeric. Case-insensitive match, stored as given.
 */
export const RepoName = Schema.String.check(
  Schema.isPattern(/^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/i),
);

/**
 * An owner (namespace) name. Same grammar as {@link RepoName}. The literal
 * owner `api` is reserved (rejected by the Registry at creation) so the
 * `/api/v1` prefix can never collide with a repo URL.
 */
export const OwnerName = RepoName;

/**
 * A full ref name (`refs/heads/main`, `refs/tags/v1.0`). Rejects the
 * whitespace / `~^:?*[\` characters git itself forbids. HEAD is virtual
 * (symref to the default branch) and is never a valid `RefName` here.
 */
export const RefName = Schema.String.check(Schema.isPattern(/^refs\/[^\s~^:?*[\\]+$/));

/**
 * Lifecycle status of a repo. Async operations (import/fork/delete) flip
 * this field; clients poll `GET /repos/:owner/:repo` until `ready` (or 404
 * once a `deleting` repo's purge completes). There is no jobs API.
 */
export const RepoStatus = Schema.Literals(["ready", "importing", "forking", "deleting"]);

/** The decoded type of {@link RepoStatus}. */
export type RepoStatus = typeof RepoStatus.Type;

// ─────────────────────────────────────────────────────────────────────────────
// Error taxonomy (tagged, status-annotated)
// ─────────────────────────────────────────────────────────────────────────────

/** 403 — the repo is flagged `readOnly`; writes are rejected. */
export class ReadOnlyRepo extends Schema.TaggedError<ReadOnlyRepo>()(
  "ReadOnlyRepo",
  {},
  { httpApiStatus: 403 },
) {}

/** 403 — application policy refused a proposed ref update. */
export class PushDenied extends Schema.TaggedError<PushDenied>()(
  "PushDenied",
  { ref: Schema.String, reason: Schema.String },
  { httpApiStatus: 403 },
) {}

/** 404 — no repo at `owner/repo` (or it finished deleting). */
export class RepoNotFound extends Schema.TaggedError<RepoNotFound>()(
  "RepoNotFound",
  { owner: Schema.String, repo: Schema.String },
  { httpApiStatus: 404 },
) {}

/** 409 — a repo already exists at `owner/repo`. */
export class RepoAlreadyExists extends Schema.TaggedError<RepoAlreadyExists>()(
  "RepoAlreadyExists",
  { owner: Schema.String, repo: Schema.String },
  { httpApiStatus: 409 },
) {}

/**
 * 409 — the repo exists but is not `ready` (importing / forking /
 * deleting); retry after polling `GET /repos/:owner/:repo`.
 */
export class RepoNotReady extends Schema.TaggedError<RepoNotReady>()(
  "RepoNotReady",
  { status: RepoStatus },
  { httpApiStatus: 409 },
) {}

/** 404 — the named ref does not exist. */
export class RefNotFound extends Schema.TaggedError<RefNotFound>()(
  "RefNotFound",
  { ref: Schema.String },
  { httpApiStatus: 404 },
) {}

/**
 * 409 — compare-and-swap failure on a ref write: `expectedOid` did not
 * match the ref's current value (`currentOid`, `null` when the ref does
 * not exist).
 */
export class RefConflict extends Schema.TaggedError<RefConflict>()(
  "RefConflict",
  { ref: Schema.String, currentOid: Schema.NullOr(Oid) },
  { httpApiStatus: 409 },
) {}

/** 404 — no object with the given oid in this repo. */
export class ObjectNotFound extends Schema.TaggedError<ObjectNotFound>()(
  "ObjectNotFound",
  { oid: Schema.String },
  { httpApiStatus: 404 },
) {}

/** 422 — the object exists but has a different type than the endpoint expects. */
export class WrongObjectType extends Schema.TaggedError<WrongObjectType>()(
  "WrongObjectType",
  { oid: Schema.String, expected: Schema.String, actual: Schema.String },
  { httpApiStatus: 422 },
) {}

/**
 * 422 — the blob is too large for the base64 JSON endpoint (> 1 MiB);
 * use the raw streaming route `GET .../blobs/:oid/raw` instead.
 */
export class ObjectTooLarge extends Schema.TaggedError<ObjectTooLarge>()(
  "ObjectTooLarge",
  { oid: Schema.String, size: Schema.Number },
  { httpApiStatus: 422 },
) {}

/**
 * 422 — the two commits share no common ancestor within the walk bound
 * (disjoint histories, or divergence beyond the server's 10k-commit cap;
 * shallow imports can also surface this across the shallow boundary).
 */
export class NoMergeBase extends Schema.TaggedError<NoMergeBase>()(
  "NoMergeBase",
  { base: Oid, head: Oid },
  { httpApiStatus: 422 },
) {}

/** 502 — the async import job failed against the source remote. */
export class ImportFailed extends Schema.TaggedError<ImportFailed>()(
  "ImportFailed",
  { reason: Schema.String },
  { httpApiStatus: 502 },
) {}

/** 400 — semantically invalid request (e.g. reserved owner name). */
export class ValidationError extends Schema.TaggedError<ValidationError>()(
  "ValidationError",
  { message: Schema.String },
  { httpApiStatus: 400 },
) {}

/** 404 — no pull request with this number. */
export class PullNotFound extends Schema.TaggedError<PullNotFound>()(
  "PullNotFound",
  { number: Schema.Number },
  { httpApiStatus: 404 },
) {}

/** 422 — the PR's base or head branch does not exist (deleted after open). */
export class BranchMissing extends Schema.TaggedError<BranchMissing>()(
  "BranchMissing",
  { ref: Schema.String },
  { httpApiStatus: 422 },
) {}

/** 409 — an open PR for this base/head pair already exists. */
export class PullExists extends Schema.TaggedError<PullExists>()(
  "PullExists",
  { number: Schema.Number },
  { httpApiStatus: 409 },
) {}

/**
 * 409 — the operation is invalid in the PR's current state (e.g. merge a
 * merged PR, reopen a merged PR).
 */
export class PullStateConflict extends Schema.TaggedError<PullStateConflict>()(
  "PullStateConflict",
  {
    number: Schema.Number,
    state: Schema.Literals(["open", "closed", "merged"]),
  },
  { httpApiStatus: 409 },
) {}

/** 422 — head is already reachable from base; there is nothing to merge. */
export class NothingToMerge extends Schema.TaggedError<NothingToMerge>()(
  "NothingToMerge",
  { number: Schema.Number },
  { httpApiStatus: 422 },
) {}

/**
 * 409 — the three-way merge is not trivial: these paths changed on both
 * sides relative to the merge base.
 */
export class MergeConflict extends Schema.TaggedError<MergeConflict>()(
  "MergeConflict",
  {
    number: Schema.Number,
    /** Conflicting paths, capped at 20 (the full set may be larger). */
    paths: Schema.Array(Schema.String),
  },
  { httpApiStatus: 409 },
) {}

// ─────────────────────────────────────────────────────────────────────────────
// Auth middleware
// ─────────────────────────────────────────────────────────────────────────────

// ─────────────────────────────────────────────────────────────────────────────
// Domain shapes
// ─────────────────────────────────────────────────────────────────────────────

/**
 * A repository resource as returned by the management plane.
 */
/**
 * Where a repo's objects currently live (DESIGN.md §12.1). `loose` rows
 * hold their bytes in DO SQLite; `packed` objects have been compacted into
 * immutable R2 packs; `r2` objects are oversize singletons in R2.
 */
export class ObjectStats extends Schema.Class<ObjectStats>("ObjectStats")({
  /** Objects whose bytes are still in DO SQLite rows. */
  loose: Schema.Number,
  /** Commits, trees and tags kept in SQLite rows (never packed). */
  resident: Schema.Number,
  /** Objects compacted into R2 packs. */
  packed: Schema.Number,
  /** Oversize objects stored as standalone R2 keys. */
  r2: Schema.Number,
  /** Total compressed bytes across all locations. */
  bytes: Schema.Number,
}) {}

/**
 * Server-side timing of the most recent push (DESIGN.md §19 phase 0).
 *
 * Wall-clock `git push` time includes client-side packing and the upload,
 * so it bounds server cost rather than measuring it. These are measured
 * inside the Durable Object, around the work itself.
 */
export class PushStats extends Schema.Class<PushStats>("PushStats")({
  /** Objects in the pushed pack. */
  objects: Schema.Number,
  /** Pack bytes received. */
  bytes: Schema.Number,
  /** Parsing + staging the pack (inflate, sha1, SQL). */
  ingestMs: Schema.Number,
  /**
   * The SQL staging portion of `ingestMs`. `ingestMs - stageMs` is CPU:
   * inflate, sha1, delta resolution, commit/tree parsing. The split decides
   * whether sharding storage or hoisting parsing is the real win
   * (DESIGN.md §19).
   */
  stageMs: Schema.Number,
  /** The connectivity check. */
  connectivityMs: Schema.Number,
  /** The ref CAS transaction. */
  finalizeMs: Schema.Number,
  /** Everything the DO did for this push. */
  totalMs: Schema.Number,
  /**
   * Ingest split by phase (ms): inflate, hash, delta, deflate, copy, sink.
   * Meaningful as CPU only where the clock runs during synchronous work
   * (local workerd); production workerd freezes `performance.now()` between
   * awaits, so there only phases that yield to the event loop accumulate —
   * which is itself diagnostic (an async inflate path shows up, a sync one
   * reads 0).
   */
  phases: Schema.optional(Schema.Record(Schema.String, Schema.Number)),
}) {}

export class Repo extends Schema.Class<Repo>("Repo")({
  /** Owner (namespace) segment of the repo's URL. */
  owner: OwnerName,
  /** Repo name segment of the repo's URL. */
  name: RepoName,
  /**
   * The stable ULID identity of the repo. Renames never move data because
   * the Repo DO id derives from `repoId`, not `owner/name`.
   */
  repoId: Schema.String,
  /** Short branch name (e.g. `main`) that HEAD symrefs to. */
  defaultBranch: Schema.String,
  /** Optional human description. */
  description: Schema.NullOr(Schema.String),
  /** When `true`, receive-pack and REST ref writes are rejected. */
  readOnly: Schema.Boolean,
  /**
   * Public repos are readable (REST reads and `git clone`/`fetch`)
   * without any token; writes always require one.
   */
  public: Schema.Boolean,
  /** Parent `repoId` when this repo is a fork, else `null`. */
  forkOf: Schema.NullOr(Schema.String),
  /** Lifecycle status; poll this for async fork/import/delete progress. */
  status: RepoStatus,
  /** Creation time, epoch milliseconds. */
  createdAt: Schema.Number,
  /** Object storage breakdown (DESIGN.md §12.1). */
  objects: ObjectStats,
  /** Server-side timing of the last push, if any (DESIGN.md §19). */
  lastPush: Schema.NullOr(PushStats),
}) {}

/**
 * A ref (branch or tag). `peeled` carries the target commit for annotated
 * tags (the advertisement's `^{}` line).
 */
export class Ref extends Schema.Class<Ref>("Ref")({
  /** Full ref name, e.g. `refs/heads/main`. */
  name: RefName,
  /** The object the ref points at. */
  oid: Oid,
  /** For annotated tags: the peeled (commit) oid. */
  peeled: Schema.optional(Oid),
}) {}

/** An author/committer/tagger signature line. */
const Signature = Schema.Struct({
  name: Schema.String,
  email: Schema.String,
  /** Unix timestamp (seconds). */
  date: Schema.Number,
  /** Timezone offset as written, e.g. `+0200`. */
  tz: Schema.String,
});

/** Parsed commit metadata for the REST read surface. */
export class CommitInfo extends Schema.Class<CommitInfo>("CommitInfo")({
  oid: Oid,
  /** Root tree of the commit. */
  tree: Oid,
  /** Parent commit oids in order. */
  parents: Schema.Array(Oid),
  author: Signature,
  committer: Signature,
  /** Full commit message (verbatim, including trailing newline). */
  message: Schema.String,
}) {}

/** A single tree entry. `commit` type = gitlink (submodule). */
export class TreeEntry extends Schema.Class<TreeEntry>("TreeEntry")({
  /** Octal mode string as stored, e.g. `100644`, `40000`, `120000`. */
  mode: Schema.String,
  /** Entry name (single path segment). */
  name: Schema.String,
  oid: Oid,
  /** Entry kind derived from mode. */
  type: Schema.Literals(["blob", "tree", "commit"]),
}) {}

/**
 * File-level change status. v1 has no rename detection (see the DESIGN note
 * on the `diff` endpoint in `Objects.ts`); a v1.1 exact-oid pass would add
 * `"renamed"` + an `oldPath`.
 */
export const FileStatus = Schema.Literals(["added", "removed", "modified"]);

/** The decoded type of {@link FileStatus}. */
export type FileStatus = typeof FileStatus.Type;

/**
 * One changed file in a commit diff or comparison. Content is NOT included —
 * clients fetch old/new blobs by oid (`blobs/:oid`, `blobs/:oid/raw`) and
 * diff locally. `oldSize`/`newSize` let the client gate binary/oversize
 * files without a round trip. Gitlinks (mode 160000) appear as entries whose
 * oids are commit oids; clients render "Subproject commit ..." and must not
 * fetch them as blobs.
 */
export class DiffEntry extends Schema.Class<DiffEntry>("DiffEntry")({
  /** Full slash-separated path from the repo root. */
  path: Schema.String,
  status: FileStatus,
  /** Blob oid on the old side (absent for `added`). */
  oldOid: Schema.optional(Oid),
  /** Blob oid on the new side (absent for `removed`). */
  newOid: Schema.optional(Oid),
  /** Octal mode on the old side, e.g. `100644` (absent for `added`). */
  oldMode: Schema.optional(Schema.String),
  /** Octal mode on the new side (absent for `removed`). */
  newMode: Schema.optional(Schema.String),
  /** Uncompressed byte size of the old blob (absent for `added`/gitlinks). */
  oldSize: Schema.optional(Schema.Number),
  /** Uncompressed byte size of the new blob (absent for `removed`/gitlinks). */
  newSize: Schema.optional(Schema.Number),
}) {}

/** The changed-file list of one commit vs its first parent. */
export class CommitDiff extends Schema.Class<CommitDiff>("CommitDiff")({
  oid: Oid,
  /** The first parent the diff was computed against; `null` for a root
   * commit (diffed against the empty tree — every file is `added`). */
  parent: Schema.NullOr(Oid),
  files: Schema.Array(DiffEntry),
  /** `true` when the file list was cut at the server cap (1000 files). */
  truncated: Schema.Boolean,
}) {}

/** GitHub-style three-dot comparison of two commits. */
export class Comparison extends Schema.Class<Comparison>("Comparison")({
  /** Resolved base commit oid (tags peeled). */
  base: Oid,
  /** Resolved head commit oid (tags peeled). */
  head: Oid,
  /** Best common ancestor (first both-reachable commit by generation). */
  mergeBase: Oid,
  /** Commits reachable from head but not base (`git rev-list --count base..head`). */
  aheadBy: Schema.Number,
  /** Commits reachable from base but not head. */
  behindBy: Schema.Number,
  /** head-side commits, committer-time descending, capped at 250. */
  commits: Schema.Array(CommitInfo),
  commitsTruncated: Schema.Boolean,
  /** File diff of mergeBase..head (three-dot, like GitHub compare/PR). */
  files: Schema.Array(DiffEntry),
  filesTruncated: Schema.Boolean,
}) {}

/** Lifecycle state of a pull request. `merged` is terminal. */
export const PullState = Schema.Literals(["open", "closed", "merged"]);

/** The decoded type of {@link PullState}. */
export type PullState = typeof PullState.Type;

/**
 * A pull request. PRs track **live** branches by ref name — the row stores
 * intent + lifecycle, never a diff snapshot. Diff and mergeability are
 * recomputed from current ref tips on every read (see {@link PullDetail}).
 */
export class Pull extends Schema.Class<Pull>("Pull")({
  /** Per-repo monotonic PR number (1-based, never reused). */
  number: Schema.Int,
  title: Schema.String,
  body: Schema.NullOr(Schema.String),
  /** Full base ref name, e.g. `refs/heads/main`. */
  baseRef: RefName,
  /** Full head ref name, e.g. `refs/heads/feature`. */
  headRef: RefName,
  state: PullState,
  /** Creation time, epoch milliseconds. */
  createdAt: Schema.Number,
  /** Last update (title/body/state) time, epoch milliseconds. */
  updatedAt: Schema.Number,
  /** Merge time (epoch milliseconds); `null` unless `state` is `merged`. */
  mergedAt: Schema.NullOr(Schema.Number),
  /** FF: the head tip; the merge commit otherwise. Set iff state=merged. */
  mergeCommit: Schema.NullOr(Oid),
}) {}

/**
 * PR detail = the row + live computed compare fields. Live fields are
 * `null` when uncomputable: a missing base/head branch, a saturated
 * ancestor walk, or a merged PR (its record is `mergeCommit`).
 */
export class PullDetail extends Pull.extend<PullDetail>("PullDetail")({
  /** Current tip of `baseRef`; `null` if the branch is gone. */
  baseOid: Schema.NullOr(Oid),
  /** Current tip of `headRef`; `null` if the branch is gone. */
  headOid: Schema.NullOr(Oid),
  mergeBase: Schema.NullOr(Oid),
  /** Commits on head not on base (`null` when the walk saturates). */
  aheadBy: Schema.NullOr(Schema.Int),
  /** Commits on base not on head. */
  behindBy: Schema.NullOr(Schema.Int),
  /**
   * `true` = FF-able or trivially merge-able; `false` = conflicting paths
   * or up-to-date; `null` = uncomputable.
   */
  mergeable: Schema.NullOr(Schema.Boolean),
  /** Why: `"ff" | "merge-commit" | "conflict" | "up-to-date" | "unknown"`. */
  mergeableReason: Schema.NullOr(Schema.String),
}) {}

/** Response of a successful PR merge. */
export class MergeResult extends Schema.Class<MergeResult>("MergeResult")({
  /** How the merge landed. */
  method: Schema.Literals(["ff", "merge-commit"]),
  /** The oid the base ref now points at. */
  oid: Oid,
  /** The PR row after the merge (`state: "merged"`). */
  pull: Pull,
}) {}

/**
 * Response of repo create/fork/import: the repo plus a ready-to-use HTTPS
 * remote URL and a bootstrap `write` token, killing the create-then-mint
 * round trip.
 */
export class RepoCreated extends Schema.Class<RepoCreated>("RepoCreated")({
  repo: Repo,
  /** HTTPS clone URL for the new repo. */
  remote: Schema.String,
}) {}

/**
 * Cursor-paginated wrapper used by list endpoints.
 *
 * @example
 * ```typescript
 * const page = Paginated(Repo); // { items: Repo[], nextCursor, hasMore }
 * ```
 */
export const Paginated = <A extends Schema.Top>(items: A) =>
  Schema.Struct({
    items: Schema.Array(items),
    nextCursor: Schema.NullOr(Schema.String),
    hasMore: Schema.Boolean,
  });
// ─────────────────────────────────────────────────────────────────────────────
// Shared path-parameter structs
// ─────────────────────────────────────────────────────────────────────────────

/** `(owner, repo)` path segments shared by repo-scoped endpoints. */
export const RepoPath = Schema.Struct({ owner: OwnerName, repo: RepoName });

/** `(owner, repo, oid)` path segments for object read endpoints. */
export const RepoOidPath = Schema.Struct({
  owner: OwnerName,
  repo: RepoName,
  oid: Oid,
});