The best way to control Claude Code, Codex and more from any computer or phone

main
ts 385 lines 12.9 KB
Raw
1 import * as Repos from "@distilled.cloud/github/repos";
2 import * as Teams from "@distilled.cloud/github/teams";
3 import * as Users from "@distilled.cloud/github/users";
4 import { isResolved } from "alchemy/Diff";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import * as Effect from "effect/Effect";
8 import * as Stream from "effect/Stream";
9 import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
10 import type * as GitHub from "./Providers.ts";
11
12 export interface EnvironmentProps {
13 /**
14 * Repository owner (user or organization).
15 */
16 owner: string;
17
18 /**
19 * Repository name.
20 */
21 repository: string;
22
23 /**
24 * Environment name (e.g. `production`, `staging`). The name is the
25 * environment's identity — changing it replaces the environment.
26 */
27 name: string;
28
29 /**
30 * Minutes to wait before allowing deployments to proceed (0–43200,
31 * i.e. up to 30 days). Requires a plan that supports environment
32 * protection rules on the repository.
33 * @default 0
34 */
35 waitTimer?: number;
36
37 /**
38 * Whether users who created or pushed the deployment are prevented
39 * from approving their own deployment.
40 * @default false
41 */
42 preventSelfReview?: boolean;
43
44 /**
45 * The people or teams that must review deployments to this environment.
46 * Up to six users or teams in total; reviewers must have at least read
47 * access to the repository. Users are referenced by login, teams by
48 * slug (teams are only valid for organization-owned repositories).
49 */
50 reviewers?: {
51 /**
52 * User logins allowed to review deployments.
53 */
54 users?: string[];
55
56 /**
57 * Team slugs (within the owning organization) allowed to review
58 * deployments.
59 */
60 teams?: string[];
61 };
62
63 /**
64 * Which branches can deploy to this environment. Omit to allow all
65 * branches. Set `protectedBranches: true` to restrict deployments to
66 * branches with branch protection rules, or `customBranchPolicies` to a
67 * list of branch name patterns (e.g. `["main", "release/*"]`).
68 */
69 deploymentBranchPolicy?: { protectedBranches: true } | { customBranchPolicies: string[] };
70
71 /**
72 * Override the GitHub host or API base URL for this resource only (e.g.
73 * `github.example.com` for GitHub Enterprise). Falls back to
74 * `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
75 * provider. Changing it replaces the resource — the same name on a
76 * different GitHub instance is a different physical resource.
77 */
78 baseUrl?: string;
79 }
80
81 export interface Environment extends Resource<
82 "GitHub.Environment",
83 EnvironmentProps,
84 {
85 /**
86 * Numeric GitHub environment ID.
87 */
88 environmentId: number;
89
90 /**
91 * GraphQL node ID of the environment.
92 */
93 nodeId: string;
94
95 /**
96 * The environment name.
97 */
98 name: string;
99
100 /**
101 * URL to view the environment in a browser.
102 */
103 htmlUrl: string;
104
105 /**
106 * ISO-8601 timestamp of when the environment was created.
107 */
108 createdAt: string;
109
110 /**
111 * ISO-8601 timestamp of the last update.
112 */
113 updatedAt: string;
114 },
115 never,
116 GitHub.Providers
117 > {}
118
119 /**
120 * A GitHub Actions deployment environment.
121 *
122 * `Environment` manages a repository's deployment environment (e.g.
123 * `production`, `staging`) along with its protection rules: required
124 * reviewers, wait timers, self-review prevention, and deployment branch
125 * policies. Pair it with `GitHub.Secret` and `GitHub.Variable` (both accept
126 * an `environment` prop) to scope configuration to the environment.
127 *
128 * Environments are available on public repositories on every plan; private
129 * repositories require GitHub Pro, Team, or Enterprise, and protection
130 * rules on private repositories require Team or Enterprise.
131 *
132 * Authentication is resolved via the GitHub `Credentials` service supplied
133 * by `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token
134 * needs `repo` scope.
135 * ### Creating an Environment
136 * **Example:** Basic Environment
137 * ```typescript
138 * const production = yield* GitHub.Environment("production", {
139 * owner: "my-org",
140 * repository: "my-repo",
141 * name: "production",
142 * });
143 * ```
144 *
145 * **Example:** Environment with Protection Rules
146 * ```typescript
147 * yield* GitHub.Environment("production", {
148 * owner: "my-org",
149 * repository: "my-repo",
150 * name: "production",
151 * waitTimer: 30,
152 * preventSelfReview: true,
153 * reviewers: {
154 * users: ["release-manager"],
155 * teams: ["platform"],
156 * },
157 * });
158 * ```
159 *
160 * ### Deployment Branch Policies
161 * **Example:** Restrict to Protected Branches
162 * ```typescript
163 * yield* GitHub.Environment("production", {
164 * owner: "my-org",
165 * repository: "my-repo",
166 * name: "production",
167 * deploymentBranchPolicy: { protectedBranches: true },
168 * });
169 * ```
170 *
171 * **Example:** Restrict to Branch Name Patterns
172 * ```typescript
173 * yield* GitHub.Environment("production", {
174 * owner: "my-org",
175 * repository: "my-repo",
176 * name: "production",
177 * deploymentBranchPolicy: {
178 * customBranchPolicies: ["main", "release/*"],
179 * },
180 * });
181 * ```
182 *
183 * ### Environment Secrets and Variables
184 * **Example:** Scope Secrets and Variables to the Environment
185 * ```typescript
186 * const env = yield* GitHub.Environment("production", {
187 * owner: "my-org",
188 * repository: "my-repo",
189 * name: "production",
190 * });
191 *
192 * yield* GitHub.Secret("deploy-key", {
193 * owner: "my-org",
194 * repository: "my-repo",
195 * environment: env,
196 * name: "DEPLOY_KEY",
197 * value: Redacted.make("my-secret-value"),
198 * });
199 *
200 * yield* GitHub.Variable("region", {
201 * owner: "my-org",
202 * repository: "my-repo",
203 * environment: env,
204 * name: "AWS_REGION",
205 * value: "us-east-1",
206 * });
207 * ```
208 *
209 * @resource
210 * @product Actions
211 */
212 export const Environment = Resource<Environment>("GitHub.Environment");
213
214 // At runtime, Resource references in props are resolved to their full
215 // attributes — so an `Environment` passed to another resource's
216 // `environment` prop arrives as `{ name: string; ... }` rather than the
217 // statically-typed Resource (whose attributes are `Output<...>`). We cast
218 // through the structural shape here.
219 export const resolveEnvironmentName = (
220 environment: string | Environment | undefined,
221 ): string | undefined => {
222 const ref = environment as unknown as string | { name: string } | undefined;
223 return ref === undefined ? undefined : typeof ref === "string" ? ref : ref.name;
224 };
225
226 export const EnvironmentProvider = () =>
227 Provider.succeed(Environment, {
228 stables: ["environmentId", "nodeId"],
229
230 // The environment name is its path identity — GitHub has no rename, so
231 // changing owner, repository, name, or the host replaces the resource.
232 diff: Effect.fn(function* ({ news, olds }) {
233 if (!isResolved(news)) return;
234 if (olds === undefined) return;
235 if (
236 news.owner !== olds.owner ||
237 news.repository !== olds.repository ||
238 news.name !== olds.name ||
239 (yield* gitHubBaseUrlChanged(olds, news))
240 ) {
241 return { action: "replace" };
242 }
243 }),
244
245 reconcile: Effect.fn(
246 function* ({ news, olds }) {
247 const scope = { owner: news.owner, repo: news.repository, environment_name: news.name };
248
249 // Resolve reviewer logins/slugs to the numeric IDs the API expects.
250 const reviewers =
251 news.reviewers === undefined
252 ? null
253 : [
254 ...(yield* Effect.forEach(news.reviewers.users ?? [], (username) =>
255 Users.getByUsername({ username }).pipe(
256 Effect.map((user) => ({ type: "User" as const, id: user.id })),
257 ),
258 )),
259 ...(yield* Effect.forEach(news.reviewers.teams ?? [], (team_slug) =>
260 Teams.getByName({ org: news.owner, team_slug }).pipe(
261 Effect.map((team) => ({ type: "Team" as const, id: team.id })),
262 ),
263 )),
264 ];
265
266 // Ensure & Sync — the PUT is a full upsert of the environment's
267 // protection configuration. Protection rules are only sent when set now
268 // or previously (olds): on private repos without GitHub Enterprise,
269 // sending them at all — even as defaults — is rejected as a billing
270 // error. A prop that was set before and is now removed is sent as its
271 // explicit default so it converges. `prevent_self_review` and
272 // `reviewers` are sent together: GitHub rejects the former when the
273 // latter is omitted (an explicit `null` is accepted).
274 const sendWaitTimer = news.waitTimer !== undefined || olds?.waitTimer !== undefined;
275 const sendReviewers =
276 news.reviewers !== undefined ||
277 news.preventSelfReview !== undefined ||
278 olds?.reviewers !== undefined ||
279 olds?.preventSelfReview !== undefined;
280 const environment = yield* Repos.createOrUpdateEnvironment({
281 ...scope,
282 ...(sendWaitTimer ? { wait_timer: news.waitTimer ?? 0 } : {}),
283 ...(sendReviewers
284 ? {
285 prevent_self_review: news.preventSelfReview ?? false,
286 reviewers: reviewers === null || reviewers.length === 0 ? null : reviewers,
287 }
288 : {}),
289 deployment_branch_policy:
290 news.deploymentBranchPolicy === undefined
291 ? null
292 : "protectedBranches" in news.deploymentBranchPolicy
293 ? { protected_branches: true, custom_branch_policies: false }
294 : { protected_branches: false, custom_branch_policies: true },
295 });
296
297 // Sync — custom branch policies live behind dedicated endpoints. Diff
298 // the observed patterns against the desired list; create the missing
299 // ones and delete the extras. Skipped entirely unless the policy mode
300 // is custom (GitHub drops the policies itself when the mode changes).
301 if (
302 news.deploymentBranchPolicy !== undefined &&
303 "customBranchPolicies" in news.deploymentBranchPolicy
304 ) {
305 const desired = news.deploymentBranchPolicy.customBranchPolicies;
306 const observed = yield* Stream.runCollect(
307 Repos.listDeploymentBranchPolicies.items({ ...scope, per_page: 100 }),
308 );
309 const observedNames = new Set(observed.map((policy) => policy.name));
310 for (const name of desired) {
311 if (!observedNames.has(name)) {
312 yield* Repos.createDeploymentBranchPolicy({ ...scope, name, type: "branch" });
313 }
314 }
315 for (const policy of observed) {
316 if (
317 policy.id !== undefined &&
318 policy.name !== undefined &&
319 !desired.includes(policy.name)
320 ) {
321 yield* Repos.deleteDeploymentBranchPolicy({ ...scope, branch_policy_id: policy.id });
322 }
323 }
324 }
325
326 return {
327 environmentId: environment.id,
328 nodeId: environment.node_id,
329 name: environment.name,
330 htmlUrl: environment.html_url,
331 createdAt: environment.created_at,
332 updatedAt: environment.updated_at,
333 };
334 },
335 (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
336 ),
337
338 // Enumerate every environment across the repositories the token can see —
339 // environments are keyed by {owner, repository, name} with no account-wide
340 // list endpoint, so walk the repos like the Variable provider does.
341 list: Effect.fn(function* () {
342 const repos = yield* Stream.runCollect(
343 Repos.listForAuthenticatedUser.items({ per_page: 100 }),
344 );
345 const perRepo = yield* Effect.forEach(
346 repos,
347 (repo) =>
348 Stream.runCollect(
349 Repos.getAllEnvironments.items({
350 owner: repo.owner.login,
351 repo: repo.name,
352 per_page: 100,
353 }),
354 ).pipe(
355 Effect.map((environments) =>
356 environments.map((environment) => ({
357 environmentId: environment.id,
358 nodeId: environment.node_id,
359 name: environment.name,
360 htmlUrl: environment.html_url,
361 createdAt: environment.created_at,
362 updatedAt: environment.updated_at,
363 })),
364 ),
365 // Repos without environments support (plan limits) or where the
366 // token lacks access reject with 403/404 — skip them rather than
367 // failing the whole enumeration.
368 Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
369 ),
370 { concurrency: 10 },
371 );
372 return perRepo.flat();
373 }),
374
375 delete: Effect.fn(
376 function* ({ olds }) {
377 yield* Repos.deleteAnEnvironment({
378 owner: olds.owner,
379 repo: olds.repository,
380 environment_name: olds.name,
381 }).pipe(Effect.catchTag("NotFound", () => Effect.void));
382 },
383 (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
384 ),
385 });