Sign in

pulls/pr_01m47d15m3e54sn21z27rpy5n9

public

pr_01m47d15m3e54sn21z27rpy5n9/packages/contracts/src/projects.ts

96 lines3,954 bytesCodeBlame
1import type { User, Viewer } from "./identity";
2import type { RepoPath } from "./repos";
3import type { Result } from "./result";
4
5/**
6 * Projects: the thing a workspace builds and runs. A project has exactly
7 * one source, where its code lives; everything about running it
8 * (deployments, environments, domains, secrets and variables) belongs to
9 * the project, while branches, pull requests and review stay with the
10 * repository. One repository may carry several projects, each from its own
11 * root directory. Every repository on g1t gets a project of its own name.
12 */
13
14/** Where a project's code lives. */
15export type ProjectSource =
16 /** A repository hosted on g1t. */
17 | { kind: "hosted"; repoId: string; repo: RepoPath; rootDir: string; defaultBranch: string }
18 /** Mirrored from another host; coming next. */
19 | { kind: "mirror"; provider: "github" | "gitlab" | "bitbucket"; url: string; rootDir: string };
20
21export type Project = {
22 id: string;
23 /** The workspace's slug. */
24 workspace: string;
25 /** Unique in its workspace; the project's address is `g1t.sh/<workspace>/<slug>`. */
26 slug: string;
27 name: string;
28 description: string | null;
29 source: ProjectSource;
30 /** Whether its repository is private: only people with a role on it can see it. */
31 private: boolean;
32 /** Whether its repository is archived: read-only, kept for reference. */
33 archived: boolean;
34 /** Whether it is the project its repository's workflows read secrets from. */
35 primary: boolean;
36 createdBy: string;
37 /** RFC 3339. */
38 createdAt: string;
39 updatedAt: string;
40};
41
42export type NewProject = {
43 name: string;
44 description?: string | null;
45 /** The hosted repository it builds from. */
46 repo: RepoPath;
47 /** Where in the repository it lives; empty for the whole repository. */
48 rootDir?: string;
49};
50
51/** One end of a dependency, as a page shows it. */
52export type DependencyLink = {
53 slug: string;
54 name: string;
55 /** The variable carrying the other project's address, such as `API_URL`. */
56 as: string | null;
57 /** Declared on the site, or in the project's `.g1t/project.yml`. */
58 source: "ui" | "file";
59};
60
61/** What a project uses, and what uses it. */
62export type Dependencies = { dependsOn: DependencyLink[]; usedBy: DependencyLink[] };
63
64/** A project's dependencies by id, for services. */
65export type ProjectGraph = {
66 dependsOn: { id: string; slug: string; workspace: string; as: string | null }[];
67 usedBy: { id: string; slug: string; workspace: string; as: string | null }[];
68};
69
70export interface ProjectsApi {
71 /** A workspace's projects, by name. Members, or anyone for public repositories. */
72 list(workspace: string, viewer: Viewer): Promise<Result<Project[]>>;
73 get(workspace: string, slug: string, viewer: Viewer): Promise<Result<Project>>;
74 /** The projects built from a repository, its primary one first. For services. */
75 byRepo(repoId: string): Promise<Project[]>;
76 /** Members only. */
77 create(actor: User, workspace: string, input: NewProject): Promise<Result<Project>>;
78 /** Members only. */
79 update(
80 actor: User,
81 workspace: string,
82 slug: string,
83 changes: { name?: string; description?: string | null; rootDir?: string },
84 ): Promise<Result<Project>>;
85 /** What a project uses and what uses it. Whoever may see the project. */
86 dependencies(workspace: string, slug: string, viewer: Viewer): Promise<Result<Dependencies>>;
87 /**
88 * `slug` uses `on`, with `as` the variable that carries `on`'s address.
89 * Members only; refused if it would make a cycle.
90 */
91 addDependency(actor: User, workspace: string, slug: string, on: string, as: string | null): Promise<Result<Dependencies>>;
92 /** Members only. A dependency from `.g1t/project.yml` is changed there. */
93 removeDependency(actor: User, workspace: string, slug: string, on: string): Promise<Result<Dependencies>>;
94 /** For services: a project's dependencies by id. */
95 graph(projectId: string): Promise<ProjectGraph>;
96}