The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }); |