Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/repos.ts

155 lines4,903 bytesCodeBlame

Pick any line to see why it is the way it is: the commit, the pull request and issue it came from, and what the agent was thinking.

Initial g1t: services, event bus, intents and attempts1import type { User, Viewer } from "./identity";
2import type { Result } from "./result";
3
4export type Repo = {
5 id: string;
Workspaces own repositories6 /** The slug of the workspace that owns it: the first URL segment. */
Initial g1t: services, event bus, intents and attempts7 namespace: string;
8 name: string;
9 description: string | null;
10 isPrivate: boolean;
11 ownerId: string;
12 defaultBranch: string;
Issues and pull requests replace intents and attempts13 /** Set when this repo is a pull request's working copy of another repo. */
Initial g1t: services, event bus, intents and attempts14 forkOf: string | null;
RFC 3339 timestamps in identity and repos15 /** RFC 3339. */
16 createdAt: string;
Initial g1t: services, event bus, intents and attempts17};
18
19export type RepoPath = { namespace: string; name: string };
20
21export type Commit = {
22 hash: string;
23 treeHash: string;
24 message: string;
25 author: { name: string; email: string };
26 parents: string[];
RFC 3339 timestamps in identity and repos27 /** RFC 3339. */
28 authoredAt: string;
Initial g1t: services, event bus, intents and attempts29};
30
31export type TreeEntry = {
32 name: string;
33 hash: string;
34 kind: "tree" | "blob" | "symlink" | "gitlink" | "exec";
35};
36
37export type TreeView = {
38 repo: Repo;
39 ref: string;
40 path: string;
41 /** Null when the repo has no commits yet. */
42 head: Commit | null;
43 entries: TreeEntry[];
44 readme: { name: string; text: string | null } | null;
45};
46
47export type BlobView = {
48 repo: Repo;
49 ref: string;
50 path: string;
51 size: number;
52 /** Null when the file is binary or too large to show. */
53 text: string | null;
54};
55
56/** A git remote and a short-lived credential for it. */
57export type GitAccess = { remote: string; token: string };
58
59export type GitService = "git-upload-pack" | "git-receive-pack";
60
61export type CreateRepoInput = {
Workspaces own repositories62 /** The workspace to create it in; the creator must be a member. */
63 namespace: string;
Initial g1t: services, event bus, intents and attempts64 name: string;
65 description?: string | null;
66 isPrivate?: boolean;
67};
68
69/** Repositories: metadata, contents and git access. */
70export interface ReposApi {
71 get(path: RepoPath, viewer: Viewer): Promise<Result<Repo>>;
72 getById(id: string, viewer: Viewer): Promise<Result<Repo>>;
73 /** Repos the viewer may see, newest first, optionally matching `query`. */
Workspaces own repositories74 list(
75 viewer: Viewer,
76 options?: {
77 query?: string;
78 /** Only repos in this workspace. */
79 namespace?: string;
80 /** Only repos in workspaces the viewer belongs to. */
81 memberOnly?: boolean;
82 },
83 ): Promise<Repo[]>;
Initial g1t: services, event bus, intents and attempts84 create(owner: User, input: CreateRepoInput): Promise<Result<Repo>>;
85
86 tree(path: RepoPath, viewer: Viewer, ref: string | null, treePath: string): Promise<Result<TreeView>>;
87 blob(path: RepoPath, viewer: Viewer, ref: string, filePath: string): Promise<Result<BlobView>>;
88 log(path: RepoPath, viewer: Viewer, ref: string | null, limit: number): Promise<Result<Commit[]>>;
89
90 /**
Issues and pull requests replace intents and attempts91 * A copy-on-write copy of `source`, hidden from listings, for one pull request
Initial g1t: services, event bus, intents and attempts92 * to work in.
93 */
Issues and pull requests replace intents and attempts94 forkForPull(sourceId: string, pullId: string, actor: User): Promise<Result<Repo>>;
Initial g1t: services, event bus, intents and attempts95
96 /**
97 * Authorizes a git operation and returns where to send it. Pushing to a
98 * repo that does not exist creates it in the pusher's own namespace.
99 */
100 gitAccess(path: RepoPath, viewer: Viewer, service: GitService): Promise<Result<GitAccess>>;
Rust repos service with shipping; pull requests kept in the model101
Pull requests from branches102 /** The repository's branches, default branch first. */
103 branches(path: RepoPath, viewer: Viewer): Promise<Result<Branch[]>>;
104
Rust repos service with shipping; pull requests kept in the model105 /**
Pull requests from branches106 * Moves a repository's default branch to the head of a pull request's
107 * source: a fork (`sourceId` is the fork) or one of the repository's own
108 * branches (`sourceId` is the repository, and `branch` is required).
109 * Refused with "conflict" when the source is behind, since that would
Rust repos service with shipping; pull requests kept in the model110 * discard commits.
111 */
Pull requests from branches112 land(sourceId: string, actor: User, branch?: string | null): Promise<Result<{ commit: string; previous: string | null }>>;
Diffs on attempts; hosted agent presented as the g1t agent113
114 /**
Pull requests from branches115 * What `head` changes relative to `base`. `head` is a branch or a commit
116 * and defaults to the default branch. With no `base`, a fork is compared
117 * with the last commit it shares with the repository it came from, and a
118 * branch with the point where it left the default branch.
Diffs on attempts; hosted agent presented as the g1t agent119 */
Pull requests from branches120 compare(repoId: string, viewer: Viewer, base?: string | null, head?: string | null): Promise<Result<Comparison>>;
Initial g1t: services, event bus, intents and attempts121}
Diffs on attempts; hosted agent presented as the g1t agent122
Pull requests from branches123/** A branch and the commit it points to. */
124export type Branch = { name: string; hash: string };
125
Diffs on attempts; hosted agent presented as the g1t agent126export type DiffLine = {
127 kind: "context" | "add" | "delete";
128 /** Line number in the old file; null for added lines. */
129 old: number | null;
130 /** Line number in the new file; null for deleted lines. */
131 new: number | null;
132 text: string;
133};
134
135/** A run of changed lines with their surrounding context. */
136export type Hunk = { lines: DiffLine[] };
137
138export type FileDiff = {
139 path: string;
140 status: "added" | "modified" | "deleted";
141 additions: number;
142 deletions: number;
143 /** True when the file is binary or too large, so no lines are shown. */
144 binary: boolean;
145 hunks: Hunk[];
146};
147
148/** What changed between two commits. */
149export type Comparison = {
150 base: string | null;
151 head: string;
152 files: FileDiff[];
153 /** True when the change was too large to return in full. */
154 truncated: boolean;
155};