Sign in

flagon-io/g1t

public

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

g1t/packages/contracts/src/repos.ts

229 lines7,577 bytesCodeBlame
1import type { User, Viewer } from "./identity";
2import type { Result } from "./result";
3
4export type Repo = {
5 id: string;
6 /** The slug of the workspace that owns it: the first URL segment. */
7 namespace: string;
8 name: string;
9 description: string | null;
10 isPrivate: boolean;
11 ownerId: string;
12 defaultBranch: string;
13 /** Set when this repo is a pull request's working copy of another repo. */
14 forkOf: string | null;
15 /**
16 * Whether the default branch is protected: it changes only by merging a
17 * pull request, and pushes to it are refused.
18 */
19 protected: boolean;
20 /** RFC 3339. */
21 createdAt: string;
22 /**
23 * Words that say what it is about, for search and Explore: lowercase
24 * letters, digits and hyphens, at most 20.
25 */
26 topics: string[];
27};
28
29/** The most topics a repository has, and the longest topic. */
30export const MAX_TOPICS = 20;
31export const MAX_TOPIC_CHARS = 35;
32
33export type RepoPath = { namespace: string; name: string };
34
35export type Commit = {
36 hash: string;
37 treeHash: string;
38 message: string;
39 author: { name: string; email: string };
40 parents: string[];
41 /** RFC 3339. */
42 authoredAt: string;
43};
44
45export type TreeEntry = {
46 name: string;
47 hash: string;
48 kind: "tree" | "blob" | "symlink" | "gitlink" | "exec";
49};
50
51export type TreeView = {
52 repo: Repo;
53 ref: string;
54 path: string;
55 /** Null when the repo has no commits yet. */
56 head: Commit | null;
57 entries: TreeEntry[];
58 readme: { name: string; text: string | null } | null;
59};
60
61export type BlobView = {
62 repo: Repo;
63 ref: string;
64 path: string;
65 size: number;
66 /** Null when the file is binary or too large to show. */
67 text: string | null;
68};
69
70/** A git remote and a short-lived credential for it. */
71export type GitAccess = { remote: string; token: string };
72
73export type GitService = "git-upload-pack" | "git-receive-pack";
74
75export type CreateRepoInput = {
76 /** The workspace to create it in; the creator must be a member. */
77 namespace: string;
78 name: string;
79 description?: string | null;
80 isPrivate?: boolean;
81 /**
82 * The https address of a public git repository to copy the default branch
83 * of, such as `https://github.com/owner/repo`.
84 */
85 importUrl?: string;
86};
87
88/** Repositories: metadata, contents and git access. */
89export interface ReposApi {
90 get(path: RepoPath, viewer: Viewer): Promise<Result<Repo>>;
91 getById(id: string, viewer: Viewer): Promise<Result<Repo>>;
92 /**
93 * The workspaces in which this account made a public repository, and so
94 * a public project anyone can see. By account id.
95 */
96 publicNamespaces(ownerId: string): Promise<string[]>;
97 /** Repos the viewer may see, newest first, optionally matching `query`. */
98 list(
99 viewer: Viewer,
100 options?: {
101 query?: string;
102 /** Only repos in this workspace. */
103 namespace?: string;
104 /** Only repos in workspaces the viewer belongs to. */
105 memberOnly?: boolean;
106 },
107 ): Promise<Repo[]>;
108 create(owner: User, input: CreateRepoInput): Promise<Result<Repo>>;
109 /**
110 * Changes whichever details are given. Members of the repository's
111 * workspace only. An empty description clears it.
112 */
113 update(
114 actor: User,
115 path: RepoPath,
116 changes: { description?: string; isPrivate?: boolean; protected?: boolean; topics?: string[] },
117 ): Promise<Result<Repo>>;
118
119 tree(path: RepoPath, viewer: Viewer, ref: string | null, treePath: string): Promise<Result<TreeView>>;
120 blob(path: RepoPath, viewer: Viewer, ref: string, filePath: string): Promise<Result<BlobView>>;
121 log(path: RepoPath, viewer: Viewer, ref: string | null, limit: number): Promise<Result<Commit[]>>;
122 /**
123 * Who last changed each line of a file as of `ref` (the default branch if
124 * null). Not found when the file is missing or is not text.
125 */
126 blame(path: RepoPath, viewer: Viewer, ref: string | null, filePath: string): Promise<Result<Blame>>;
127
128 /**
129 * A copy-on-write copy of `source`, hidden from listings, for one pull request
130 * to work in.
131 */
132 forkForPull(sourceId: string, pullId: string, actor: User): Promise<Result<Repo>>;
133
134 /**
135 * Authorizes a git operation and returns where to send it. Pushing to a
136 * repo that does not exist creates it in the pusher's own namespace.
137 */
138 gitAccess(path: RepoPath, viewer: Viewer, service: GitService): Promise<Result<GitAccess>>;
139
140 /** The repository's branches, default branch first. */
141 branches(path: RepoPath, viewer: Viewer): Promise<Result<Branch[]>>;
142
143 /**
144 * Moves a repository's default branch to the head of a pull request's
145 * source: a fork (`sourceId` is the fork) or one of the repository's own
146 * branches (`sourceId` is the repository, and `branch` is required).
147 * Refused with "conflict" when the source is behind, since that would
148 * discard commits.
149 */
150 land(sourceId: string, actor: User, branch?: string | null): Promise<Result<{ commit: string; previous: string | null }>>;
151
152 /**
153 * What `head` changes relative to `base`. `head` is a branch or a commit
154 * and defaults to the default branch. With no `base`, a fork is compared
155 * with the last commit it shares with the repository it came from, and a
156 * branch with the point where it left the default branch.
157 */
158 compare(repoId: string, viewer: Viewer, base?: string | null, head?: string | null): Promise<Result<Comparison>>;
159}
160
161/** Lines `start` to `end` (inclusive, from 1) last changed by `commit`. */
162export type BlameRange = { start: number; end: number; commit: string };
163
164/** Who last changed each line of a file. */
165export type Blame = {
166 /** The commit the file was read at. */
167 head: string;
168 /** Every line, in order, in runs that share a commit. */
169 ranges: BlameRange[];
170 /** The commits the ranges name, each once. */
171 commits: Commit[];
172 /** True when the history was too long to read in full. */
173 partial: boolean;
174};
175
176/** A branch and the commit it points to. */
177export type Branch = { name: string; hash: string };
178
179/**
180 * What came of bringing a pull request up to date with the default branch
181 * without a sandbox. `needs_agent` pushed nothing: the runner's `update`
182 * merges it in a sandbox, with an agent if it conflicts.
183 */
184export type PullBranchUpdate =
185 | { outcome: "updated"; commit: string; previous: string }
186 | { outcome: "up_to_date"; commit: string }
187 | {
188 outcome: "needs_agent";
189 /**
190 * `overlap`: both sides changed some of the same files. `conflicting`:
191 * merging is known to conflict. `unsupported`: it could not be worked
192 * out without git, such as for a very large change.
193 */
194 reason: "overlap" | "conflicting" | "unsupported";
195 detail: string;
196 /** The files both changed, or that conflict, when known. */
197 paths: string[];
198 };
199
200export type DiffLine = {
201 kind: "context" | "add" | "delete";
202 /** Line number in the old file; null for added lines. */
203 old: number | null;
204 /** Line number in the new file; null for deleted lines. */
205 new: number | null;
206 text: string;
207};
208
209/** A run of changed lines with their surrounding context. */
210export type Hunk = { lines: DiffLine[] };
211
212export type FileDiff = {
213 path: string;
214 status: "added" | "modified" | "deleted";
215 additions: number;
216 deletions: number;
217 /** True when the file is binary or too large, so no lines are shown. */
218 binary: boolean;
219 hunks: Hunk[];
220};
221
222/** What changed between two commits. */
223export type Comparison = {
224 base: string | null;
225 head: string;
226 files: FileDiff[];
227 /** True when the change was too large to return in full. */
228 truncated: boolean;
229};