Sign in

flagon-io/g1t

public

g1t/packages/contracts/src/projects.ts

131 lines5,715 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.

Projects: what a workspace builds and runs, first on every page1import 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;
Fast pages, required checks on the branch, self-hosted runners, honest incidents28 /** The project's own description, or its repository's while it has none. */
Projects: what a workspace builds and runs, first on every page29 description: string | null;
Fast pages, required checks on the branch, self-hosted runners, honest incidents30 /** Whether `description` is its repository's, following it as it changes. */
31 descriptionInherited: boolean;
Projects: what a workspace builds and runs, first on every page32 source: ProjectSource;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look33 /** Whether its repository is private: only people with a role on it can see it. */
Projects: what a workspace builds and runs, first on every page34 private: boolean;
Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look35 /** Whether its repository is archived: read-only, kept for reference. */
36 archived: boolean;
Projects: what a workspace builds and runs, first on every page37 /** Whether it is the project its repository's workflows read secrets from. */
38 primary: boolean;
A project is an app or a library: libraries show their package and how to ship a release, not production39 /** Whether it deploys, as set in its settings: `auto` decides from the project itself. */
40 deploys: DeploysSetting;
41 /** What it is, from `deploys`, or for `auto` from its deployments, packages and files. */
42 kind: ProjectKind;
43 /** Why it is that kind. */
44 kindReason: KindReason;
45 /** What `auto` decides, whatever the setting is, to show beside it. */
46 detected: { kind: ProjectKind; reason: KindReason };
47 /** The ecosystem its files say it publishes to, for how to publish; null when none says. */
48 ecosystem: ProjectEcosystem | null;
Projects: what a workspace builds and runs, first on every page49 createdBy: string;
50 /** RFC 3339. */
51 createdAt: string;
52 updatedAt: string;
53};
54
A project is an app or a library: libraries show their package and how to ship a release, not production55/** Whether a project deploys: decided from the project, or set by a person. */
56export type DeploysSetting = "auto" | "yes" | "no";
57
58/**
59 * An app deploys and gets production, previews and domains; a library (or
60 * a tool) is published and installed, so its pages offer releases and
61 * packages instead.
62 */
63export type ProjectKind = "app" | "library";
64
65/**
66 * What decided the kind: the setting, Deployments being on, a package its
67 * repository publishes, its files, or nothing (an app, by default).
68 * `detail` says it in a sentence.
69 */
70export type KindReason = { by: "set" | "deployments" | "packages" | "files" | "default"; detail: string };
71
72/** Where a library's files say it is published. */
73export type ProjectEcosystem = "composer" | "npm" | "cargo" | "go" | "python";
74
Projects: what a workspace builds and runs, first on every page75export type NewProject = {
76 name: string;
77 description?: string | null;
78 /** The hosted repository it builds from. */
79 repo: RepoPath;
80 /** Where in the repository it lives; empty for the whole repository. */
81 rootDir?: string;
82};
83
Project dependencies: addresses, preview stacks, Affects, and agents who know84/** One end of a dependency, as a page shows it. */
85export type DependencyLink = {
86 slug: string;
87 name: string;
88 /** The variable carrying the other project's address, such as `API_URL`. */
89 as: string | null;
90 /** Declared on the site, or in the project's `.g1t/project.yml`. */
91 source: "ui" | "file";
92};
93
94/** What a project uses, and what uses it. */
95export type Dependencies = { dependsOn: DependencyLink[]; usedBy: DependencyLink[] };
96
97/** A project's dependencies by id, for services. */
98export type ProjectGraph = {
99 dependsOn: { id: string; slug: string; workspace: string; as: string | null }[];
100 usedBy: { id: string; slug: string; workspace: string; as: string | null }[];
101};
102
Projects: what a workspace builds and runs, first on every page103export interface ProjectsApi {
104 /** A workspace's projects, by name. Members, or anyone for public repositories. */
105 list(workspace: string, viewer: Viewer): Promise<Result<Project[]>>;
106 get(workspace: string, slug: string, viewer: Viewer): Promise<Result<Project>>;
107 /** The projects built from a repository, its primary one first. For services. */
108 byRepo(repoId: string): Promise<Project[]>;
109 /** Members only. */
110 create(actor: User, workspace: string, input: NewProject): Promise<Result<Project>>;
Fast pages, required checks on the branch, self-hosted runners, honest incidents111 /** Members only. A null or blank description goes back to the repository's. */
Projects: what a workspace builds and runs, first on every page112 update(
113 actor: User,
114 workspace: string,
115 slug: string,
A project is an app or a library: libraries show their package and how to ship a release, not production116 changes: { name?: string; description?: string | null; rootDir?: string; deploys?: DeploysSetting },
Projects: what a workspace builds and runs, first on every page117 ): Promise<Result<Project>>;
A project is an app or a library: libraries show their package and how to ship a release, not production118 /** For deployments: Deployments were turned on or off for the project. */
119 deploymentsChanged(projectId: string, enabled: boolean): Promise<void>;
Project dependencies: addresses, preview stacks, Affects, and agents who know120 /** What a project uses and what uses it. Whoever may see the project. */
121 dependencies(workspace: string, slug: string, viewer: Viewer): Promise<Result<Dependencies>>;
122 /**
123 * `slug` uses `on`, with `as` the variable that carries `on`'s address.
124 * Members only; refused if it would make a cycle.
125 */
126 addDependency(actor: User, workspace: string, slug: string, on: string, as: string | null): Promise<Result<Dependencies>>;
127 /** Members only. A dependency from `.g1t/project.yml` is changed there. */
128 removeDependency(actor: User, workspace: string, slug: string, on: string): Promise<Result<Dependencies>>;
129 /** For services: a project's dependencies by id. */
130 graph(projectId: string): Promise<ProjectGraph>;
Projects: what a workspace builds and runs, first on every page131}