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