import * as Issues from "@distilled.cloud/github/issues";
import * as Repos from "@distilled.cloud/github/repos";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { dedent } from "alchemy/Util/dedent";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
import type * as GitHub from "./Providers.ts";
export interface IssueProps {
/**
* Repository owner (user or organization).
*/
owner: string;
/**
* Repository name.
*/
repository: string;
/**
* Issue title.
*/
title: string;
/**
* Issue body (supports GitHub Markdown).
*
* The body is automatically dedented, so you can use indented template
* literals without worrying about leading whitespace. Accepts
* `Output<string>` at the call site via `Output.interpolate` to embed
* resource attributes that are not yet resolved.
*/
body?: string;
/**
* State of the issue. Use "open" to reopen a closed issue or "closed" to
* close an open issue.
* @default "open"
*/
state?: "open" | "closed";
/**
* Labels to attach to the issue. The provided list fully replaces any
* existing labels.
*/
labels?: string[];
/**
* Assignees (user logins) to assign to the issue. The provided list fully
* replaces existing assignees.
*/
assignees?: string[];
/**
* Milestone number to assign to the issue. Use `null` to remove milestone.
*/
milestone?: number | null;
/**
* Override the GitHub host or API base URL for this resource only (e.g.
* `github.example.com` for GitHub Enterprise). Falls back to
* `GitHub.providers({ baseUrl })`, then to the host resolved by the auth
* provider. Changing it replaces the resource — the same name on a
* different GitHub instance is a different physical resource.
*/
baseUrl?: string;
}
export interface Issue extends Resource<
"GitHub.Issue",
IssueProps,
{
/**
* The numeric ID of the issue in GitHub.
*/
issueNumber: number;
/**
* GraphQL node ID of the issue.
*/
nodeId: string;
/**
* URL to view the issue in a browser.
*/
htmlUrl: string;
/**
* State of the issue (open or closed).
*/
state: "open" | "closed";
/**
* ISO-8601 timestamp of when the issue was created.
*/
createdAt: string;
/**
* ISO-8601 timestamp of the last update.
*/
updatedAt: string;
},
never,
GitHub.Providers
> {}
/**
* A GitHub repository issue.
*
* `Issue` manages the lifecycle of a single issue in a repository. Issues are
* created on the first deploy and updated in place on subsequent deploys when
* properties change. By default, issues are retained on destruction to preserve
* discussion history. Pipe the resource through `destroy()` to close the issue
* on destruction instead; its discussion remains on GitHub.
*
* Authentication is resolved via the GitHub `Credentials` service supplied by
* `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token needs
* `repo` scope for private repositories or `public_repo` for public ones.
*
* ### Creating Issues
* **Example:** Create a Basic Issue
* ```typescript
* const issue = yield* GitHub.Issue("bug-report", {
* owner: "my-org",
* repository: "my-repo",
* title: "Bug: Application crashes on startup",
* body: "## Description\n\nThe application crashes when...",
* })
* ```
*
* **Example:** Issue with Labels and Assignees
* ```typescript
* const issue = yield* GitHub.Issue("feature-request", {
* owner: "my-org",
* repository: "my-repo",
* title: "Feature: Add dark mode",
* body: "Users have requested...",
* labels: ["enhancement", "ui"],
* assignees: ["developer1"],
* })
* ```
*
* ### Updating Issues
* Deploy with the same logical ID and different properties to update the
* existing issue in place rather than creating a new one.
*
* **Example:** Update Issue State
* ```typescript
* const issue = yield* GitHub.Issue("resolved-bug", {
* owner: "my-org",
* repository: "my-repo",
* title: "Bug: Application crashes on startup",
* body: "This has been resolved.",
* state: "closed",
* })
* ```
*
* ### Issue with Milestone
* **Example:** Assign to Milestone
* ```typescript
* const issue = yield* GitHub.Issue("v1-task", {
* owner: "my-org",
* repository: "my-repo",
* title: "Implement authentication",
* milestone: 1,
* })
* ```
*
* ### Tracking Infrastructure Changes
* A common pattern is creating issues to track infrastructure changes or
* deployment status.
*
* **Example:** Infrastructure Status Issue
* ```typescript
* yield* GitHub.Issue("infra-status", {
* owner: "my-org",
* repository: "my-repo",
* title: "Infrastructure Status",
* body: Output.interpolate`
* ## Current Status
*
* **Database:** ${database.endpoint}
* **Cache:** ${cache.endpoint}
* `,
* labels: ["infrastructure"],
* })
* ```
*
* @resource
* @product Issue
*/
export const Issue = Resource<Issue>("GitHub.Issue", {
defaultRemovalPolicy: "retain",
});
export const IssueProvider = () =>
Provider.succeed(Issue, {
stables: ["issueNumber", "nodeId"],
// An issue belongs to (host, owner, repository) — its server-assigned
// number is meaningless elsewhere, so moving it replaces the resource:
// a fresh issue is created on the new repository, and the old one is
// retained by default (matching the resource's `retain` removal policy).
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
if (
news.owner !== olds.owner ||
news.repository !== olds.repository ||
(yield* gitHubBaseUrlChanged(olds, news))
) {
return { action: "replace" };
}
}),
reconcile: Effect.fn(
function* ({ news, output }) {
const body = news.body ? dedent(news.body) : "";
const state = news.state ?? "open";
const labels = news.labels ?? [];
const assignees = news.assignees ?? [];
const milestone = news.milestone ?? null;
let data =
output?.issueNumber !== undefined
? yield* Issues.get({
owner: news.owner,
repo: news.repository,
issue_number: output.issueNumber,
}).pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.undefined))
: undefined;
if (data === undefined) {
data = yield* Issues.create({
owner: news.owner,
repo: news.repository,
title: news.title,
body,
labels,
assignees,
milestone: milestone ?? undefined,
});
}
const sameNames = (observed: string[], desired: string[]) =>
JSON.stringify(observed.map((name) => name.toLowerCase()).sort()) ===
JSON.stringify(desired.map((name) => name.toLowerCase()).sort());
// Creation always opens an issue; sync also applies the desired initial state.
if (
data.title !== news.title ||
(data.body ?? "") !== body ||
data.state !== state ||
!sameNames(
data.labels.map((label) => (typeof label === "string" ? label : (label.name ?? ""))),
labels,
) ||
!sameNames(
(data.assignees ?? []).map((assignee) => assignee.login),
assignees,
) ||
(data.milestone?.number ?? null) !== milestone
) {
const issueNumber = data.number;
data = yield* Issues.update({
owner: news.owner,
repo: news.repository,
issue_number: issueNumber,
title: news.title,
body,
state,
labels,
assignees,
milestone,
});
}
return {
issueNumber: data.number,
nodeId: data.node_id,
htmlUrl: data.html_url,
state: data.state as "open" | "closed",
createdAt: data.created_at,
updatedAt: data.updated_at,
};
},
(effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
),
// Enumerate every issue across the repositories the token can see.
list: Effect.fn(function* () {
const repos = yield* Stream.runCollect(
Repos.listForAuthenticatedUser.items({ per_page: 100 }),
);
const perRepo = yield* Effect.forEach(
repos,
(repo) =>
Stream.runCollect(
Issues.listForRepo.items({
owner: repo.owner.login,
repo: repo.name,
state: "all",
per_page: 100,
}),
).pipe(
// Filter out pull requests (they appear in issues API)
Effect.map((issues) =>
issues
.filter((issue) => !issue.pull_request)
.map((issue) => ({
issueNumber: issue.number,
nodeId: issue.node_id,
htmlUrl: issue.html_url,
state: issue.state as "open" | "closed",
createdAt: issue.created_at,
updatedAt: issue.updated_at,
})),
),
// Repositories the token can list but not read, or with issues disabled.
Effect.catchTag(["Forbidden", "NotFound", "Gone"], () => Effect.succeed([])),
),
{ concurrency: 10 },
);
return perRepo.flat();
}),
delete: Effect.fn(
function* ({ olds, output }) {
// Opted-in destruction closes the issue without deleting its discussion.
if (output?.issueNumber !== undefined) {
yield* Issues.update({
owner: olds.owner,
repo: olds.repository,
issue_number: output.issueNumber,
state: "closed",
}).pipe(Effect.catchTag(["NotFound", "Gone"], () => Effect.void));
}
},
(effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
),
});