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 page | 1 | import type { User, Viewer } from "./identity"; |
| 2 | import type { RepoPath } from "./repos"; | |
| 3 | import 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. */ | |
| 15 | export 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 | ||
| 21 | export 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 incidents | 28 | /** The project's own description, or its repository's while it has none. */ |
| Projects: what a workspace builds and runs, first on every page | 29 | description: string | null; |
| Fast pages, required checks on the branch, self-hosted runners, honest incidents | 30 | /** Whether `description` is its repository's, following it as it changes. */ |
| 31 | descriptionInherited: boolean; | |
| Projects: what a workspace builds and runs, first on every page | 32 | source: ProjectSource; |
| Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look | 33 | /** 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 page | 34 | private: boolean; |
| Invite-only launch: sign in with GitHub, repository access and lifecycle, many emails, a new look | 35 | /** Whether its repository is archived: read-only, kept for reference. */ |
| 36 | archived: boolean; | |
| Projects: what a workspace builds and runs, first on every page | 37 | /** 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 production | 39 | /** 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 page | 49 | createdBy: string; |
| 50 | /** RFC 3339. */ | |
| 51 | createdAt: string; | |
| 52 | updatedAt: string; | |
| Projects: when each was last pushed, and how active it is lately | 53 | /** RFC 3339: when its repository was last pushed to; null until it is, after projects began keeping it. */ |
| 54 | pushedAt: string | null; | |
| 55 | /** | |
| 56 | * How active it is lately: each push, issue or pull request opened or | |
| 57 | * closed, review, comment and deployment counts one, halving every week. | |
| 58 | * 0 for none. | |
| 59 | */ | |
| 60 | activity: number; | |
| Projects: what a workspace builds and runs, first on every page | 61 | }; |
| 62 | ||
| A project is an app or a library: libraries show their package and how to ship a release, not production | 63 | /** Whether a project deploys: decided from the project, or set by a person. */ |
| 64 | export type DeploysSetting = "auto" | "yes" | "no"; | |
| 65 | ||
| 66 | /** | |
| 67 | * An app deploys and gets production, previews and domains; a library (or | |
| 68 | * a tool) is published and installed, so its pages offer releases and | |
| 69 | * packages instead. | |
| 70 | */ | |
| 71 | export type ProjectKind = "app" | "library"; | |
| 72 | ||
| 73 | /** | |
| 74 | * What decided the kind: the setting, Deployments being on, a package its | |
| 75 | * repository publishes, its files, or nothing (an app, by default). | |
| 76 | * `detail` says it in a sentence. | |
| 77 | */ | |
| 78 | export type KindReason = { by: "set" | "deployments" | "packages" | "files" | "default"; detail: string }; | |
| 79 | ||
| 80 | /** Where a library's files say it is published. */ | |
| 81 | export type ProjectEcosystem = "composer" | "npm" | "cargo" | "go" | "python"; | |
| 82 | ||
| Projects: what a workspace builds and runs, first on every page | 83 | export type NewProject = { |
| 84 | name: string; | |
| 85 | description?: string | null; | |
| 86 | /** The hosted repository it builds from. */ | |
| 87 | repo: RepoPath; | |
| 88 | /** Where in the repository it lives; empty for the whole repository. */ | |
| 89 | rootDir?: string; | |
| 90 | }; | |
| 91 | ||
| Project dependencies: addresses, preview stacks, Affects, and agents who know | 92 | /** One end of a dependency, as a page shows it. */ |
| 93 | export type DependencyLink = { | |
| 94 | slug: string; | |
| 95 | name: string; | |
| 96 | /** The variable carrying the other project's address, such as `API_URL`. */ | |
| 97 | as: string | null; | |
| 98 | /** Declared on the site, or in the project's `.g1t/project.yml`. */ | |
| 99 | source: "ui" | "file"; | |
| 100 | }; | |
| 101 | ||
| 102 | /** What a project uses, and what uses it. */ | |
| 103 | export type Dependencies = { dependsOn: DependencyLink[]; usedBy: DependencyLink[] }; | |
| 104 | ||
| 105 | /** A project's dependencies by id, for services. */ | |
| 106 | export type ProjectGraph = { | |
| 107 | dependsOn: { id: string; slug: string; workspace: string; as: string | null }[]; | |
| 108 | usedBy: { id: string; slug: string; workspace: string; as: string | null }[]; | |
| 109 | }; | |
| 110 | ||
| Projects: pinned and recent projects, per person per workspace | 111 | /** |
| 112 | * What a person keeps at hand in a workspace: the projects they pinned, in | |
| 113 | * their order, then the ones they opened last that they have not pinned. | |
| 114 | * Only projects they can still see. | |
| 115 | */ | |
| 116 | export type ProjectShortcuts = { pinned: Project[]; recent: Project[] }; | |
| 117 | ||
| Projects: what a workspace builds and runs, first on every page | 118 | export interface ProjectsApi { |
| 119 | /** A workspace's projects, by name. Members, or anyone for public repositories. */ | |
| 120 | list(workspace: string, viewer: Viewer): Promise<Result<Project[]>>; | |
| 121 | get(workspace: string, slug: string, viewer: Viewer): Promise<Result<Project>>; | |
| 122 | /** The projects built from a repository, its primary one first. For services. */ | |
| 123 | byRepo(repoId: string): Promise<Project[]>; | |
| 124 | /** Members only. */ | |
| 125 | create(actor: User, workspace: string, input: NewProject): Promise<Result<Project>>; | |
| Fast pages, required checks on the branch, self-hosted runners, honest incidents | 126 | /** Members only. A null or blank description goes back to the repository's. */ |
| Projects: what a workspace builds and runs, first on every page | 127 | update( |
| 128 | actor: User, | |
| 129 | workspace: string, | |
| 130 | slug: string, | |
| A project is an app or a library: libraries show their package and how to ship a release, not production | 131 | changes: { name?: string; description?: string | null; rootDir?: string; deploys?: DeploysSetting }, |
| Projects: what a workspace builds and runs, first on every page | 132 | ): Promise<Result<Project>>; |
| A project is an app or a library: libraries show their package and how to ship a release, not production | 133 | /** For deployments: Deployments were turned on or off for the project. */ |
| 134 | deploymentsChanged(projectId: string, enabled: boolean): Promise<void>; | |
| Project dependencies: addresses, preview stacks, Affects, and agents who know | 135 | /** What a project uses and what uses it. Whoever may see the project. */ |
| 136 | dependencies(workspace: string, slug: string, viewer: Viewer): Promise<Result<Dependencies>>; | |
| 137 | /** | |
| 138 | * `slug` uses `on`, with `as` the variable that carries `on`'s address. | |
| 139 | * Members only; refused if it would make a cycle. | |
| 140 | */ | |
| 141 | addDependency(actor: User, workspace: string, slug: string, on: string, as: string | null): Promise<Result<Dependencies>>; | |
| 142 | /** Members only. A dependency from `.g1t/project.yml` is changed there. */ | |
| 143 | removeDependency(actor: User, workspace: string, slug: string, on: string): Promise<Result<Dependencies>>; | |
| 144 | /** For services: a project's dependencies by id. */ | |
| 145 | graph(projectId: string): Promise<ProjectGraph>; | |
| Projects: pinned and recent projects, per person per workspace | 146 | /** A person's pinned and recent projects in a workspace. Empty for anyone else. */ |
| 147 | shortcuts(workspace: string, viewer: Viewer): Promise<ProjectShortcuts>; | |
| 148 | /** | |
| 149 | * Pins a project the person can see, at `position` (0 first) or at the | |
| 150 | * end; pinning one already pinned moves it. A person's own, at most 8 a | |
| 151 | * workspace. Returns their pins, in order. | |
| 152 | */ | |
| 153 | pin(actor: User, workspace: string, slug: string, position?: number | null): Promise<Result<Project[]>>; | |
| 154 | /** Unpins it. Returns their pins, in order. */ | |
| 155 | unpin(actor: User, workspace: string, slug: string): Promise<Result<Project[]>>; | |
| 156 | /** Puts their pins in this order: every pinned project's slug, once. */ | |
| 157 | reorderPins(actor: User, workspace: string, slugs: string[]): Promise<Result<Project[]>>; | |
| 158 | /** The person opened the project: it leads their recent ones. */ | |
| 159 | visited(actor: User, projectId: string): Promise<void>; | |
| Projects: what a workspace builds and runs, first on every page | 160 | } |