API and implementation requirements
This page defines the seven responsibilities discussed in “Codebase API” as target requirements. It is not an inventory of current routes and does not assert that unimplemented endpoints are available.
1. Sync execution and update tracking — first priority
- Accept synchronization as a durable job, independent of the HTTP connection. Normally return
202 Acceptedwith an identifier for tracking the job. - A request with a wait limit must not stop the job when that limit expires. Its status remains retrievable using the same identifier.
- Record repository, requester, target ref, state, attempt count, start/completion times, and credential-free failure reasons. Separate job state from mirror readiness.
- Recover unfinished jobs after process restarts. Automatically retry transient failures with backoff, distinguishing non-retryable failures.
- Trigger synchronization from GitHub updates and safely handle duplicate events, duplicate requests, and concurrent updates to the same repository.
- Manage multiple repository jobs on the server. A sequential browser loop must not own completion.
Acceptance: Synchronization completes after the page closes, recovers after a process restart, and incorporates GitHub updates. A returning UI can inspect job status and the last applied commit.
2. Git storage and delivery — first priority
- Store Git objects and refs with workspace, repository, and commit identity.
- Avoid downloading and restoring the entire bundle for each read. Reuse data across incremental updates and repeated reads.
- Keep the previous complete generation readable during updates and publish consistent refs on completion.
- Clean up generations, unreferenced objects, and failed-sync temporary data without deleting active generations.
- Define capacity, execution time, concurrency, and retention as service constraints with explicit limit errors. Raising the existing 100 MiB and 120-second constants alone is insufficient.
- Enforce workspace boundaries and current authorization even when reusing stored or cached data.
Acceptance: Agreed repository sizes and concurrency workloads support repeated reads without full restoration. Interrupted synchronization preserves the readable generation, and cleanup retains referenced data. Set numeric targets from measurements.
3. File and history reads
| Operation | Required contract |
|---|---|
| Tree, file, README | Repository, ref or commit SHA, path → children, content, type, size |
| History | Ref/path and continuation cursor → commits, next cursor |
| Commit detail | SHA → author, date, message, parents, changed files, additions/deletions |
| Diff comparison | Base/head → files, hunks, line locations, binary and size limits |
| Revision browsing | Read by immutable commit SHA independently of branch movement |
Acceptance: History continues beyond 20 commits. Users navigate between real commit details, diffs, and files at that revision.
4. Ownership, permissions, administration
Connect workspace ownership and read / write / admin grants to collaborator and access-confirmation UI. Authorize grant listing, creation, changes, and revocation on the server.
Define unlinking separately from repository deletion. Specify automatic-sync shutdown, retained data, running jobs, and existing credentials. Explicitly distinguish Forge deletion from GitHub deletion; never silently delete the GitHub source.
Acceptance: Grant changes affect browsing, synchronization, and downloads; collaborators are real users. After unlinking or deletion, new jobs and credentials cannot use stale permissions.
5. Clone and agent access
Provide Git HTTPS delivery from Forge itself. The Code menu, CLI, and agents must retrieve the Forge repository instead of merely cloning GitHub directly.
Define issuance, validation, and revocation of short-lived credentials scoped to repository, operation, and expiry. Separate browser-session APIs from CLI/agent authentication. Keep credentials out of URLs and logs. Bundles may remain a download option but are not a substitute for ongoing Git delivery.
Acceptance: CLI and agents clone/fetch from Forge without copying browser cookies. Expired, revoked, and insufficient credentials are rejected.
6. PRs, reviews, Checks
Read real GitHub PR lists, details, base/head, changed files, diffs, comments, reviews, and Checks into the shared UI, including pagination and update timestamps.
Complete read integration first. Enable comment submission, reviews, and merging only after write permissions and destinations are defined.
Acceptance: Product PR screens operate on real data without exposing fixtures or unavailable submission actions.
7. Writes and source-of-truth changes — later phase
Retain repository creation, commit/push, merge, and write-direction switching as future requirements. They are not acceptance conditions for the read-only mirror.
Before implementation, decide whether GitHub or Forge owns the source of truth, permitted write directions, conflicts, protected branches, Checks, stale-head handling, auditing, and recovery. A write grant does not establish Git write support.
Sequence and references
Implement 1 + 2 → 3 + 4 → 5 → 6 → 7. Establish URLs and concrete schemas in OpenAPI from these requirements. This document alone does not change existing HTTP contracts.
The user-provided Cursor Sync Mirror specification is the reference for asynchronous acceptance and continued execution after a wait limit. Do not assert equivalent capacity limits or availability SLAs.
Inspect openapi/spec3.yaml, apps/server/src/modules/forge/, and packages/contracts/src/forge.ts for current implementation. Evaluate completion against service-level acceptance conditions even when incremental improvements such as short-lived caches are present.