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

main
ts 380 lines 9.99 KB
Raw
1 import * as Issues from "@distilled.cloud/github/issues";
2 import * as Repos from "@distilled.cloud/github/repos";
3 import { isResolved } from "alchemy/Diff";
4 import * as Provider from "alchemy/Provider";
5 import { Resource } from "alchemy/Resource";
6 import * as Effect from "effect/Effect";
7 import * as Stream from "effect/Stream";
8 import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
9 import type * as GitHub from "./Providers.ts";
10
11 export interface MilestoneProps {
12 /**
13 * Repository owner (user or organization).
14 */
15 owner: string;
16
17 /**
18 * Repository name.
19 */
20 repository: string;
21
22 /**
23 * Milestone title. The title is the milestone's identity — changing it
24 * replaces the milestone.
25 */
26 title: string;
27
28 /**
29 * Milestone state.
30 * @default "open"
31 */
32 state?: "open" | "closed";
33
34 /**
35 * Description of the milestone.
36 */
37 description?: string;
38
39 /**
40 * Due date for the milestone (ISO-8601 format: `YYYY-MM-DD` or full
41 * `YYYY-MM-DDTHH:MM:SSZ`).
42 */
43 dueOn?: string;
44
45 /**
46 * Override the GitHub host or API base URL for this resource only (e.g.
47 * `github.example.com` for GitHub Enterprise). Falls back to
48 * `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
49 * provider. Changing it replaces the resource — the same name on a
50 * different GitHub instance is a different physical resource.
51 */
52 baseUrl?: string;
53 }
54
55 export interface Milestone extends Resource<
56 "GitHub.Milestone",
57 MilestoneProps,
58 {
59 /**
60 * The numeric milestone number.
61 */
62 milestoneNumber: number;
63
64 /**
65 * GraphQL node ID of the milestone.
66 */
67 nodeId: string;
68
69 /**
70 * The milestone title.
71 */
72 title: string;
73
74 /**
75 * Current state of the milestone.
76 */
77 state: "open" | "closed";
78
79 /**
80 * Milestone description.
81 */
82 description: string | null;
83
84 /**
85 * Due date for the milestone (ISO-8601 format).
86 */
87 dueOn: string | null;
88
89 /**
90 * URL to view the milestone in a browser.
91 */
92 htmlUrl: string;
93
94 /**
95 * ISO-8601 timestamp of when the milestone was created.
96 */
97 createdAt: string;
98
99 /**
100 * ISO-8601 timestamp of the last update.
101 */
102 updatedAt: string;
103
104 /**
105 * ISO-8601 timestamp when the milestone was closed.
106 */
107 closedAt: string | null;
108
109 /**
110 * Number of open issues in this milestone.
111 */
112 openIssues: number;
113
114 /**
115 * Number of closed issues in this milestone.
116 */
117 closedIssues: number;
118 },
119 never,
120 GitHub.Providers
121 > {}
122
123 /**
124 * A GitHub milestone.
125 *
126 * `Milestone` manages repository milestones for tracking issues and pull
127 * requests. Milestones are created on first deploy and updated in place on
128 * subsequent deploys when properties change.
129 *
130 * Authentication is resolved via the GitHub `Credentials` service supplied by
131 * `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token needs
132 * `repo` scope for private repositories or `public_repo` for public ones.
133 * ### Creating Milestones
134 * **Example:** Basic Milestone
135 * ```typescript
136 * const v1 = yield* GitHub.Milestone("v1", {
137 * owner: "my-org",
138 * repository: "my-repo",
139 * title: "v1.0.0",
140 * description: "First stable release",
141 * });
142 * ```
143 *
144 * **Example:** Milestone with Due Date
145 * ```typescript
146 * yield* GitHub.Milestone("sprint-1", {
147 * owner: "my-org",
148 * repository: "my-repo",
149 * title: "Sprint 1",
150 * description: "Complete user authentication",
151 * dueOn: "2026-12-31",
152 * });
153 * ```
154 *
155 * ### Updating Milestones
156 * Deploy with the same logical ID and different properties to update the
157 * existing milestone in place.
158 *
159 * **Example:** Update Description and Due Date
160 * ```typescript
161 * yield* GitHub.Milestone("v2", {
162 * owner: "my-org",
163 * repository: "my-repo",
164 * title: "v2.0.0",
165 * description: "Updated: API redesign and performance improvements",
166 * dueOn: "2027-06-30",
167 * });
168 * ```
169 *
170 * ### Closing and Reopening
171 * **Example:** Close a Milestone
172 * ```typescript
173 * yield* GitHub.Milestone("v1", {
174 * owner: "my-org",
175 * repository: "my-repo",
176 * title: "v1.0.0",
177 * state: "closed",
178 * });
179 * ```
180 *
181 * **Example:** Reopen a Milestone
182 * ```typescript
183 * yield* GitHub.Milestone("v1", {
184 * owner: "my-org",
185 * repository: "my-repo",
186 * title: "v1.0.0",
187 * state: "open",
188 * });
189 * ```
190 *
191 * ### Replacing on Title Change
192 * Changing the title creates a new milestone and deletes the old one.
193 *
194 * **Example:** Replace by Changing Title
195 * ```typescript
196 * // First deploy creates "Q1 2026"
197 * const milestone = yield* GitHub.Milestone("q1", {
198 * owner: "my-org",
199 * repository: "my-repo",
200 * title: "Q1 2026",
201 * });
202 *
203 * // Later deploy with same logical ID but different title replaces it
204 * const milestone = yield* GitHub.Milestone("q1", {
205 * owner: "my-org",
206 * repository: "my-repo",
207 * title: "Q1 2027",
208 * });
209 * ```
210 *
211 * ### Wiring with Other Resources
212 * **Example:** Create Repository with Milestone
213 * ```typescript
214 * import * as Output from "alchemy/Output";
215 *
216 * const repo = yield* GitHub.Repository("api", {
217 * owner: "my-org",
218 * name: "api",
219 * autoInit: true,
220 * });
221 *
222 * yield* GitHub.Milestone("launch", {
223 * owner: repo.owner!,
224 * repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
225 * title: "Initial Launch",
226 * dueOn: "2026-12-31",
227 * });
228 * ```
229 *
230 * @resource
231 * @product Issue
232 */
233 export const Milestone = Resource<Milestone>("GitHub.Milestone");
234
235 export const MilestoneProvider = () =>
236 Provider.succeed(Milestone, {
237 stables: ["milestoneNumber", "nodeId"],
238
239 // A milestone belongs to (host, owner, repository, title) — changing any
240 // of these replaces the resource.
241 diff: Effect.fn(function* ({ news, olds }) {
242 if (!isResolved(news)) return;
243 if (olds === undefined) return;
244 if (
245 news.owner !== olds.owner ||
246 news.repository !== olds.repository ||
247 news.title !== olds.title ||
248 (yield* gitHubBaseUrlChanged(olds, news))
249 ) {
250 return { action: "replace" };
251 }
252 }),
253
254 reconcile: Effect.fn(
255 function* ({ news }) {
256 const state = news.state ?? "open";
257 const description = news.description ?? "";
258 const requestedDueOn = news.dueOn;
259 const dueOn =
260 requestedDueOn === undefined
261 ? null
262 : yield* Effect.try(() => new Date(requestedDueOn).toISOString().replace(".000Z", "Z"));
263
264 // Observe — probe for an existing milestone by title. GitHub's list
265 // endpoint supports filtering by state, but we need to check both open
266 // and closed to find any existing milestone with this title.
267 const existingMilestones = yield* Stream.runCollect(
268 Issues.listMilestones.items({
269 owner: news.owner,
270 repo: news.repository,
271 state: "all",
272 per_page: 100,
273 }),
274 );
275
276 let observed = existingMilestones.find((m) => m.title === news.title);
277
278 // Ensure — when no milestone exists, create one
279 if (observed === undefined) {
280 observed = yield* Issues.createMilestone({
281 owner: news.owner,
282 repo: news.repository,
283 title: news.title,
284 state,
285 description,
286 due_on: dueOn ?? undefined,
287 });
288 }
289
290 // Creation can shift the due date; converge the returned state too.
291 if (
292 observed.state === state &&
293 (observed.description ?? "") === description &&
294 observed.due_on === dueOn
295 ) {
296 return attrsOf(observed);
297 }
298
299 return attrsOf(
300 yield* Issues.updateMilestone({
301 owner: news.owner,
302 repo: news.repository,
303 milestone_number: observed.number,
304 title: news.title,
305 state,
306 description,
307 due_on: dueOn,
308 }),
309 );
310 },
311 (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
312 ),
313
314 // Enumerate every milestone across the repositories the token can see —
315 // milestones are keyed by {owner, repository, title} with no account-wide
316 // list endpoint, so walk the repos like the Variable provider does.
317 list: Effect.fn(function* () {
318 const repos = yield* Stream.runCollect(
319 Repos.listForAuthenticatedUser.items({ per_page: 100 }),
320 );
321 const perRepo = yield* Effect.forEach(
322 repos,
323 (repo) =>
324 Stream.runCollect(
325 Issues.listMilestones.items({
326 owner: repo.owner.login,
327 repo: repo.name,
328 state: "all",
329 per_page: 100,
330 }),
331 ).pipe(
332 Effect.map((milestones) => milestones.map(attrsOf)),
333 // Repos where the token lacks milestone access reject with 403/404 —
334 // skip them rather than failing the whole enumeration.
335 Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
336 ),
337 { concurrency: 10 },
338 );
339 return perRepo.flat();
340 }),
341
342 delete: Effect.fn(
343 function* ({ olds, output }) {
344 yield* Issues.deleteMilestone({
345 owner: olds.owner,
346 repo: olds.repository,
347 milestone_number: output.milestoneNumber,
348 }).pipe(Effect.catchTag("NotFound", () => Effect.void));
349 },
350 (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
351 ),
352 });
353
354 const attrsOf = (data: {
355 number: number;
356 node_id: string;
357 title: string;
358 state: "open" | "closed";
359 description: string | null;
360 due_on: string | null;
361 html_url: string;
362 created_at: string;
363 updated_at: string;
364 closed_at: string | null;
365 open_issues: number;
366 closed_issues: number;
367 }) => ({
368 milestoneNumber: data.number,
369 nodeId: data.node_id,
370 title: data.title,
371 state: data.state,
372 description: data.description,
373 dueOn: data.due_on,
374 htmlUrl: data.html_url,
375 createdAt: data.created_at,
376 updatedAt: data.updated_at,
377 closedAt: data.closed_at,
378 openIssues: data.open_issues,
379 closedIssues: data.closed_issues,
380 });