Skip to content
Sign in

flagon-io/g1t

public
0
453 linesCodeBlameRaw
1import type { Contributors, Languages, License, NewRelease, Release, ReleaseChange, RepoAbout, Stargazer, StarredRepo, Stars } from "./about";
2import type { User, Viewer } from "./identity";
3import type { Result } from "./result";
4
5export type Repo = {
6 id: string;
7 /** The slug of the workspace that owns it: the first URL segment. */
8 namespace: string;
9 name: string;
10 description: string | null;
11 isPrivate: boolean;
12 ownerId: string;
13 defaultBranch: string;
14 /** Set when this repo is a pull request's working copy of another repo. */
15 forkOf: string | null;
16 /**
17 * Whether the default branch is protected: it changes only by merging a
18 * pull request, and pushes to it are refused.
19 */
20 protected: boolean;
21 /** RFC 3339. */
22 createdAt: string;
23 /**
24 * Words that say what it is about, for search and Explore: lowercase
25 * letters, digits and hyphens, at most 20.
26 */
27 topics: string[];
28 /** Its home page, an http(s) address. */
29 website?: string | null;
30 /**
31 * RFC 3339: when it was archived. While archived it is read-only:
32 * pushes, merges, agents and workflows are refused, and issues and pull
33 * requests are locked. Null when it is not archived.
34 */
35 archivedAt?: string | null;
36};
37
38/** How long a deleted repository can be restored before it is purged. */
39export const RESTORE_DAYS = 30;
40
41/** A deleted repository, as its workspace's Recently deleted list shows it. */
42export type DeletedRepo = {
43 id: string;
44 namespace: string;
45 name: string;
46 description: string | null;
47 isPrivate: boolean;
48 /** RFC 3339. */
49 deletedAt: string;
50 /** The username of who deleted it. */
51 deletedBy: string;
52 /** RFC 3339: when it is purged, unless restored first. */
53 purgeAfter: string;
54};
55
56/** Whether a repository is archived or deleted, for services deciding whether to act on it. */
57export type RepoStatus = { archived: boolean; deleted: boolean };
58
59/** The most topics a repository has, and the longest topic. */
60export const MAX_TOPICS = 20;
61export const MAX_TOPIC_CHARS = 35;
62
63export type RepoPath = { namespace: string; name: string };
64
65export type Commit = {
66 hash: string;
67 treeHash: string;
68 message: string;
69 author: { name: string; email: string };
70 parents: string[];
71 /** RFC 3339. */
72 authoredAt: string;
73};
74
75export type TreeEntry = {
76 name: string;
77 hash: string;
78 kind: "tree" | "blob" | "symlink" | "gitlink" | "exec";
79};
80
81export type TreeView = {
82 repo: Repo;
83 ref: string;
84 path: string;
85 /** Null when the repo has no commits yet. */
86 head: Commit | null;
87 entries: TreeEntry[];
88 readme: { name: string; text: string | null } | null;
89};
90
91export type BlobView = {
92 repo: Repo;
93 ref: string;
94 path: string;
95 size: number;
96 /** Null when the file is binary or too large to show. */
97 text: string | null;
98};
99
100/** A git remote and a short-lived credential for it. */
101export type GitAccess = { remote: string; token: string };
102
103export type GitService = "git-upload-pack" | "git-receive-pack";
104
105export type CreateRepoInput = {
106 /** The workspace to create it in; the creator must be a member. */
107 namespace: string;
108 name: string;
109 description?: string | null;
110 isPrivate?: boolean;
111 /**
112 * The https address of a public git repository to copy the default branch
113 * of, such as `https://github.com/owner/repo`.
114 */
115 importUrl?: string;
116};
117
118/**
119 * Where repositories may be kept. `euAvailable`: an EU namespace takes new
120 * repositories, so a workspace may keep its data in the EU.
121 */
122export type StorageOptions = { euAvailable: boolean };
123
124/** Repositories: metadata, contents and git access. */
125export interface ReposApi {
126 get(path: RepoPath, viewer: Viewer): Promise<Result<Repo>>;
127 getById(id: string, viewer: Viewer): Promise<Result<Repo>>;
128 /**
129 * Of these ids (at most 500), the repositories the viewer can read, in
130 * one call. Forks and deleted repositories are left out.
131 */
132 readable(ids: string[], viewer: Viewer): Promise<Repo[]>;
133 /**
134 * The workspaces in which this account made a public repository, and so
135 * a public project anyone can see. By account id.
136 */
137 publicNamespaces(ownerId: string): Promise<string[]>;
138 /** Repos the viewer may see, newest first, optionally matching `query`. */
139 list(
140 viewer: Viewer,
141 options?: {
142 query?: string;
143 /** Only repos in this workspace. */
144 namespace?: string;
145 /** Only repos in workspaces the viewer belongs to. */
146 memberOnly?: boolean;
147 },
148 ): Promise<Repo[]>;
149 create(owner: User, input: CreateRepoInput): Promise<Result<Repo>>;
150 /**
151 * Changes whichever details are given. Members of the repository's
152 * workspace only. An empty description clears it.
153 */
154 update(
155 actor: User,
156 path: RepoPath,
157 changes: {
158 description?: string;
159 isPrivate?: boolean;
160 protected?: boolean;
161 topics?: string[];
162 /** An empty string clears it. */
163 website?: string;
164 },
165 ): Promise<Result<Repo>>;
166 /**
167 * Deletes the repository. Owners only, who type its full name as
168 * `confirm`. It is hidden at once and can be restored for
169 * `RESTORE_DAYS` days, then purged. Publishes `repo.deleted`.
170 */
171 delete(actor: User, path: RepoPath, confirm: string): Promise<Result<DeletedRepo>>;
172 /** A workspace's recently deleted repositories, newest first. Owners only; empty otherwise. */
173 deleted(viewer: Viewer, namespace: string): Promise<DeletedRepo[]>;
174 /** Brings a deleted repository back as it was. Owners only. Publishes `repo.restored`. */
175 restore(actor: User, path: RepoPath): Promise<Result<Repo>>;
176 /**
177 * Removes a deleted repository for good now, its git data with it, and
178 * frees its name. Owners only, who type its full name. Publishes `repo.purged`.
179 */
180 purge(actor: User, path: RepoPath, confirm: string): Promise<Result<boolean>>;
181 /**
182 * Renames the repository in its workspace. Owners only. The old path
183 * redirects until a repository is made there. Publishes `repo.renamed`.
184 */
185 rename(actor: User, path: RepoPath, name: string): Promise<Result<Repo>>;
186 /**
187 * Archives the repository (read-only) or unarchives it. Owners only.
188 * Publishes `repo.archived` or `repo.unarchived`.
189 */
190 archive(actor: User, path: RepoPath, archived: boolean): Promise<Result<Repo>>;
191 /**
192 * Makes the repository public or private. Owners only, who type its full
193 * name as `confirm`. Publishes `repo.updated` and `repo.visibility_changed`.
194 */
195 setVisibility(actor: User, path: RepoPath, isPrivate: boolean, confirm: string): Promise<Result<Repo>>;
196 /** Makes another existing branch the default. Members. */
197 setDefaultBranch(actor: User, path: RepoPath, branch: string): Promise<Result<Repo>>;
198 /**
199 * Renames a branch; pull requests from it follow, and addresses naming the
200 * old one redirect. Members; only owners rename the default branch.
201 */
202 renameBranch(actor: User, path: RepoPath, from: string, to: string): Promise<Result<Repo>>;
203 /** What a branch renamed away from `branch` is called now, or null. */
204 resolveBranch(repoId: string, branch: string): Promise<string | null>;
205 /** Whether a repository is archived or deleted; an unknown id answers as deleted. */
206 statusById(id: string): Promise<RepoStatus>;
207 /** What a workspace may choose about where its repositories are kept. */
208 storageOptions(): Promise<StorageOptions>;
209 /**
210 * Moves the repository to the workspace `to`, keeping its name, id and
211 * everything under it. The actor must own both workspaces. The old path
212 * redirects until a repository is made there. Publishes `repo.transferred`.
213 */
214 transfer(actor: User, path: RepoPath, to: string): Promise<Result<Repo>>;
215 /**
216 * Where a repository transferred away from `path` is now; null when
217 * `path` is a repository or never was one that moved. Callers check the
218 * viewer may see it there.
219 */
220 resolvePath(path: RepoPath): Promise<RepoPath | null>;
221
222 tree(path: RepoPath, viewer: Viewer, ref: string | null, treePath: string): Promise<Result<TreeView>>;
223 blob(path: RepoPath, viewer: Viewer, ref: string, filePath: string): Promise<Result<BlobView>>;
224 log(path: RepoPath, viewer: Viewer, ref: string | null, limit: number): Promise<Result<Commit[]>>;
225 /**
226 * Who last changed each line of a file as of `ref` (the default branch if
227 * null). Not found when the file is missing or is not text.
228 */
229 blame(path: RepoPath, viewer: Viewer, ref: string | null, filePath: string): Promise<Result<Blame>>;
230
231 /**
232 * A copy-on-write copy of `source`, hidden from listings, for one pull request
233 * to work in.
234 */
235 forkForPull(sourceId: string, pullId: string, actor: User): Promise<Result<Repo>>;
236
237 /**
238 * Authorizes a git operation and returns where to send it. Pushing to a
239 * repo that does not exist creates it in the pusher's own namespace.
240 */
241 gitAccess(path: RepoPath, viewer: Viewer, service: GitService): Promise<Result<GitAccess>>;
242
243 /** The repository's branches, default branch first. */
244 branches(path: RepoPath, viewer: Viewer): Promise<Result<Branch[]>>;
245
246 /** Which commit last changed each entry of a directory at `ref` (the default branch when null). */
247 lastCommits(path: RepoPath, viewer: Viewer, ref: string | null, treePath: string): Promise<Result<LastCommits>>;
248
249 /**
250 * How far each branch head has moved from `base` (the default branch's
251 * head commit), with each head's commit and `base`'s own, in one call.
252 * Kept by the pair of hashes in the repos service.
253 */
254 branchDrift(path: RepoPath, viewer: Viewer, base: string, heads: string[]): Promise<Result<BranchDrifts>>;
255
256 /** The repository's tags, newest commit first, at most 100. */
257 tags(path: RepoPath, viewer: Viewer): Promise<Result<Tag[]>>;
258
259 /**
260 * The Files page's About in one answer: license, security policy,
261 * languages, contributors, stars and releases. What comes from files and
262 * history is kept by commit and worked out in the background when it is
263 * behind the head (see `about.ts`).
264 */
265 about(path: RepoPath, viewer: Viewer): Promise<Result<RepoAbout>>;
266 languages(path: RepoPath, viewer: Viewer): Promise<Result<Languages>>;
267 /** Everyone whose commits are on the default branch, with their weeks. */
268 contributors(path: RepoPath, viewer: Viewer): Promise<Result<Contributors>>;
269 license(path: RepoPath, viewer: Viewer): Promise<Result<License | null>>;
270 /** How many starred it, and whether the viewer did. */
271 stars(path: RepoPath, viewer: Viewer): Promise<Result<Stars>>;
272 /** Stars it for the actor, or takes the star back. */
273 star(actor: User, path: RepoPath, starred: boolean): Promise<Result<Stars>>;
274 /** Who starred it, newest first, 100 a page from 1. */
275 stargazers(path: RepoPath, viewer: Viewer, page?: number): Promise<Result<Stargazer[]>>;
276 /** What a person starred that the viewer can see, newest first, at most 100. */
277 starred(username: string, viewer: Viewer): Promise<StarredRepo[]>;
278 /** Releases, newest first, at most 100: drafts only for those who can push. */
279 releases(path: RepoPath, viewer: Viewer): Promise<Result<Release[]>>;
280 /** One release by id or tag, or the latest. */
281 release(path: RepoPath, viewer: Viewer, which: { id?: string; tag?: string; latest?: boolean }): Promise<Result<Release>>;
282 /** Needs Write. A tag that does not exist yet is made at `target`. */
283 createRelease(actor: User, path: RepoPath, release: NewRelease): Promise<Result<Release>>;
284 updateRelease(actor: User, path: RepoPath, id: string, change: ReleaseChange): Promise<Result<Release>>;
285 /** The tag stays. */
286 deleteRelease(actor: User, path: RepoPath, id: string): Promise<Result<boolean>>;
287
288 /**
289 * Every file at `ref` (the default branch when null), at most `limit`
290 * (10,000 at most). No viewer: check access first.
291 */
292 listFiles(repoId: string, ref: string | null, limit: number): Promise<FileList>;
293
294 /** Blobs' bytes as standard base64, at most 100; `data` is null for one missing or over `maxBytes`. No viewer. */
295 rawBlobs(repoId: string, hashes: string[], maxBytes: number): Promise<RawBlob[]>;
296
297 /**
298 * Writes one file on a new branch made from the default branch's head, as
299 * one commit by `actor`, for a change g1t proposes on their behalf (a
300 * starter workflow). Refused unless they may push, when the branch exists,
301 * or when the file is already there.
302 */
303 commitFile(
304 repo: RepoPath,
305 actor: User,
306 file: { branch: string; path: string; content: string; message: string },
307 ): Promise<Result<{ branch: string; commit: string }>>;
308
309 /**
310 * Moves a repository's default branch to the head of a pull request's
311 * source: a fork (`sourceId` is the fork) or one of the repository's own
312 * branches (`sourceId` is the repository, and `branch` is required).
313 * Refused with "conflict" when the source is behind, since that would
314 * discard commits.
315 */
316 land(sourceId: string, actor: User, branch?: string | null): Promise<Result<{ commit: string; previous: string | null }>>;
317
318 /**
319 * What `head` changes relative to `base`. `head` is a branch or a commit
320 * and defaults to the default branch. With no `base`, a fork is compared
321 * with the last commit it shares with the repository it came from, and a
322 * branch with the point where it left the default branch.
323 */
324 /**
325 * With no `base`, a branch is compared from where it left `baseBranch`
326 * (the default branch when absent).
327 */
328 compare(
329 repoId: string,
330 viewer: Viewer,
331 base?: string | null,
332 head?: string | null,
333 baseBranch?: string | null,
334 ): Promise<Result<Comparison>>;
335
336 /**
337 * Services only, for the runner's sweep: up to `limit` queued nightly
338 * backups, each now running with a token of its own, so long as no more
339 * than `maxRunning` are then running. Empty when backups are off.
340 */
341 claimBackups(limit: number, maxRunning: number): Promise<BackupClaim[]>;
342
343 /**
344 * Services only: a backup's sandbox stopped before it reported, so the
345 * job is tried again later. Refused harmlessly once it has reported.
346 */
347 failBackup(jobId: string, token: string, error: string): Promise<Result<boolean>>;
348}
349
350/**
351 * A nightly backup to start (`g1t_contracts::backups`): the sandbox is
352 * given the job's id and token, and nothing else.
353 */
354export type BackupClaim = {
355 jobId: string;
356 token: string;
357 repoId: string;
358 path: RepoPath;
359};
360
361/** Lines `start` to `end` (inclusive, from 1) last changed by `commit`. */
362export type BlameRange = { start: number; end: number; commit: string };
363
364/** Who last changed each line of a file. */
365export type Blame = {
366 /** The commit the file was read at. */
367 head: string;
368 /** Every line, in order, in runs that share a commit. */
369 ranges: BlameRange[];
370 /** The commits the ranges name, each once. */
371 commits: Commit[];
372 /** True when the history was too long to read in full. */
373 partial: boolean;
374};
375
376/** A branch and the commit it points to. */
377export type Branch = { name: string; hash: string };
378
379/** Each entry's last commit; `complete` is false when some were not reached. */
380export type LastCommits = { entries: { name: string; commit: Commit }[]; complete: boolean };
381
382/** Commits a branch has that the default branch does not, and the other way round. */
383export type BranchDriftCount = { ahead: number; behind: number };
384
385/**
386 * `base`'s commit, and each head's commit and drift in the order asked;
387 * `drift` is null when the two histories do not meet within what is read.
388 */
389export type BranchDrifts = {
390 base: Commit | null;
391 branches: { head: string; commit: Commit | null; drift: BranchDriftCount | null }[];
392};
393
394/** A tag, and its commit when it could be read. */
395export type Tag = { name: string; commit: Commit | null };
396
397/** Files at a commit, and whether there were more than were listed. */
398export type FileList = { commit: string | null; files: { path: string; hash: string | null }[]; truncated: boolean };
399
400/** One blob's bytes, standard base64; null when missing or too large. */
401export type RawBlob = { hash: string; size: number; data: string | null };
402
403/**
404 * What came of bringing a pull request up to date with the default branch
405 * without a sandbox. `needs_agent` pushed nothing: the runner's `update`
406 * merges it in a sandbox, with an agent if it conflicts.
407 */
408export type PullBranchUpdate =
409 | { outcome: "updated"; commit: string; previous: string }
410 | { outcome: "up_to_date"; commit: string }
411 | {
412 outcome: "needs_agent";
413 /**
414 * `overlap`: both sides changed some of the same files. `conflicting`:
415 * merging is known to conflict. `unsupported`: it could not be worked
416 * out without git, such as for a very large change.
417 */
418 reason: "overlap" | "conflicting" | "unsupported";
419 detail: string;
420 /** The files both changed, or that conflict, when known. */
421 paths: string[];
422 };
423
424export type DiffLine = {
425 kind: "context" | "add" | "delete";
426 /** Line number in the old file; null for added lines. */
427 old: number | null;
428 /** Line number in the new file; null for deleted lines. */
429 new: number | null;
430 text: string;
431};
432
433/** A run of changed lines with their surrounding context. */
434export type Hunk = { lines: DiffLine[] };
435
436export type FileDiff = {
437 path: string;
438 status: "added" | "modified" | "deleted";
439 additions: number;
440 deletions: number;
441 /** True when the file is binary or too large, so no lines are shown. */
442 binary: boolean;
443 hunks: Hunk[];
444};
445
446/** What changed between two commits. */
447export type Comparison = {
448 base: string | null;
449 head: string;
450 files: FileDiff[];
451 /** True when the change was too large to return in full. */
452 truncated: boolean;
453};