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 Option from "effect/Option";
import * as Stream from "effect/Stream";
import { withBaseUrl, gitHubBaseUrlChanged } from "./BaseUrl.ts";
import type * as GitHub from "./Providers.ts";
export interface ReleaseProps {
/**
* Repository owner (user or organization).
*/
owner: string;
/**
* Repository name.
*/
repository: string;
/**
* Git tag name for this release. The tag is the release's identity —
* changing it replaces the release.
*/
tagName: string;
/**
* Release title/name. If omitted, GitHub uses the tag name.
*/
name?: string;
/**
* Release notes/description (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;
/**
* Whether this is a draft release (not visible to users).
* @default false
*/
draft?: boolean;
/**
* Whether this is a prerelease (beta, alpha, etc.).
* @default false
*/
prerelease?: boolean;
/**
* Commitish (branch, commit SHA, or tag) to target. If the tag doesn't
* exist, the release will create it from this commitish. If omitted,
* GitHub defaults to the repository's default branch.
*/
targetCommitish?: string;
/**
* Whether to automatically generate release notes from commits.
* @default false
*/
generateReleaseNotes?: boolean;
/**
* 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 Release extends Resource<
"GitHub.Release",
ReleaseProps,
{
/**
* Numeric release ID.
*/
releaseId: number;
/**
* GraphQL node ID of the release.
*/
nodeId: string;
/**
* The git tag name.
*/
tagName: string;
/**
* The release name/title.
*/
name: string;
/**
* Release notes/description.
*/
body: string;
/**
* Whether this is a draft release.
*/
draft: boolean;
/**
* Whether this is a prerelease.
*/
prerelease: boolean;
/**
* URL to view the release in a browser.
*/
htmlUrl: string;
/**
* URL for uploading release assets.
*/
uploadUrl: string;
/**
* ISO-8601 timestamp of when the release was created.
*/
createdAt: string;
/**
* ISO-8601 timestamp of when the release was published.
*/
publishedAt: string | null;
},
never,
GitHub.Providers
> {}
/**
* A GitHub release.
*
* `Release` manages repository releases (tagged versions with notes,
* binaries, etc.). Releases are created on first deploy and updated in place
* on subsequent deploys when properties change. Publishing a draft converts it
* to a public release.
*
* 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 Releases
* **Example:** Basic Release
* ```typescript
* const v1 = yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.0",
* name: "Version 1.0.0",
* body: "First stable release",
* });
* ```
*
* **Example:** Prerelease
* ```typescript
* yield* GitHub.Release("beta", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v2.0.0-beta.1",
* name: "v2.0.0 Beta 1",
* body: "Beta release for testing",
* prerelease: true,
* });
* ```
*
* ### Draft Releases
* **Example:** Create Draft and Publish Later
* ```typescript
* // First deploy: create as draft
* const release = yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.0",
* name: "Version 1.0.0",
* body: "Release notes here",
* draft: true,
* });
*
* // Later deploy: publish by setting draft: false
* const release = yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.0",
* name: "Version 1.0.0",
* body: "Release notes here",
* draft: false,
* });
* ```
*
* ### Auto-Generated Release Notes
* **Example:** Generate Notes from Commits
* ```typescript
* yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.1.0",
* name: "Version 1.1.0",
* generateReleaseNotes: true,
* });
* ```
*
* ### Targeting Specific Commits
* **Example:** Release from Branch or Commit
* ```typescript
* yield* GitHub.Release("hotfix", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.1",
* name: "Hotfix 1.0.1",
* body: "Critical bug fix",
* targetCommitish: "hotfix-branch",
* });
* ```
*
* ### Updating Releases
* Deploy with the same logical ID and tag to update the existing release.
*
* **Example:** Update Release Notes
* ```typescript
* yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.0",
* name: "Version 1.0.0",
* body: `
* # What's New
*
* - Feature A
* - Feature B
* - Bug fixes
* `,
* });
* ```
*
* ### Replacing on Tag Change
* Changing the tag creates a new release and deletes the old one.
*
* **Example:** New Tag = New Release
* ```typescript
* // First deploy creates v1.0.0
* const release = yield* GitHub.Release("latest", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.0.0",
* });
*
* // Later deploy with different tag replaces it
* const release = yield* GitHub.Release("latest", {
* owner: "my-org",
* repository: "my-repo",
* tagName: "v1.1.0",
* });
* ```
*
* ### Wiring with Other Resources
* **Example:** Create Repository with Release
* ```typescript
* import * as Output from "alchemy/Output";
*
* const repo = yield* GitHub.Repository("sdk", {
* owner: "my-org",
* name: "sdk",
* autoInit: true,
* });
*
* yield* GitHub.Release("v1", {
* owner: "my-org",
* repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
* tagName: "v1.0.0",
* name: "Initial Release",
* body: "First public version of the SDK",
* });
* ```
*
* @resource
* @product Release
*/
export const Release = Resource<Release>("GitHub.Release");
export const ReleaseProvider = () =>
Provider.succeed(Release, {
stables: ["releaseId", "nodeId"],
// A release belongs to (host, owner, repository, tagName) — changing any
// of these replaces the resource.
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
if (
news.owner !== olds.owner ||
news.repository !== olds.repository ||
news.tagName !== olds.tagName ||
(yield* gitHubBaseUrlChanged(olds, news))
) {
return { action: "replace" };
}
}),
read: Effect.fn(function* ({ olds, output }) {
const observed = yield* findRelease(olds, output?.releaseId);
return observed === undefined ? undefined : attrsOf(observed);
}),
reconcile: Effect.fn(
function* ({ news, output }) {
const body = news.body !== undefined ? dedent(news.body) : undefined;
let observed = yield* findRelease(news, output?.releaseId);
if (observed === undefined) {
observed = yield* Repos.createRelease({
owner: news.owner,
repo: news.repository,
tag_name: news.tagName,
name: news.name,
body,
draft: news.draft,
prerelease: news.prerelease,
target_commitish: news.targetCommitish,
generate_release_notes: news.generateReleaseNotes,
}).pipe(
// A 422 is a create race (the tag already has a release): re-observe.
Effect.catchTag("UnprocessableEntity", (error) =>
findRelease(news).pipe(
Effect.flatMap((release) =>
release === undefined ? Effect.fail(error) : Effect.succeed(release),
),
),
),
);
}
const desired = {
name: news.name ?? news.tagName,
body: body ?? (news.generateReleaseNotes ? (observed.body ?? "") : ""),
draft: news.draft ?? false,
prerelease: news.prerelease ?? false,
};
if (
(observed.name ?? observed.tag_name) === desired.name &&
(observed.body ?? "") === desired.body &&
observed.draft === desired.draft &&
observed.prerelease === desired.prerelease
) {
return attrsOf(observed);
}
return attrsOf(
yield* Repos.updateRelease({
owner: news.owner,
repo: news.repository,
release_id: observed.id,
tag_name: news.tagName,
...desired,
}),
);
},
(effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
),
// Enumerate every release across the repositories the token can see —
// releases are keyed by {owner, repository, tagName} with no account-wide
// list endpoint, so walk the repos like the Variable provider does.
list: Effect.fn(function* () {
const repos = yield* Stream.runCollect(
Repos.listForAuthenticatedUser.items({ per_page: 100 }),
);
const perRepo = yield* Effect.forEach(
repos,
(repo) =>
Stream.runCollect(
Repos.listReleases.items({
owner: repo.owner.login,
repo: repo.name,
per_page: 100,
}),
).pipe(
Effect.map((releases) => releases.map(attrsOf)),
// Repos where the token lacks release access reject with 403/404 —
// skip them rather than failing the whole enumeration.
Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
),
{ concurrency: 10 },
);
return perRepo.flat();
}),
delete: Effect.fn(
function* ({ olds, output }) {
yield* Repos.deleteRelease({
owner: olds.owner,
repo: olds.repository,
release_id: output.releaseId,
}).pipe(Effect.catchTag("NotFound", () => Effect.void));
},
(effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
),
});
const findRelease = Effect.fn(
function* (props: ReleaseProps, releaseId?: number) {
const request = { owner: props.owner, repo: props.repository };
if (releaseId !== undefined) {
const existing = yield* Repos.getRelease({ ...request, release_id: releaseId }).pipe(
Effect.catchTag("NotFound", () => Effect.undefined),
);
if (existing !== undefined && existing.tag_name === props.tagName) return existing;
}
const published = yield* Repos.getReleaseByTag({ ...request, tag: props.tagName }).pipe(
Effect.catchTag("NotFound", () => Effect.undefined),
);
if (published !== undefined) return published;
// The tag endpoint excludes drafts, including drafts recovered without state.
return yield* Repos.listReleases.items({ ...request, per_page: 100 }).pipe(
Stream.filter((release) => release.tag_name === props.tagName),
Stream.runHead,
Effect.map(Option.getOrUndefined),
Effect.catchTag("NotFound", () => Effect.undefined),
);
},
(effect, props: ReleaseProps, _releaseId?: number) => effect.pipe(withBaseUrl(props.baseUrl)),
);
const attrsOf = (data: {
id: number;
node_id: string;
tag_name: string;
name: string | null;
body?: string | null;
draft: boolean;
prerelease: boolean;
html_url: string;
upload_url: string;
created_at: string;
published_at: string | null;
}) => ({
releaseId: data.id,
nodeId: data.node_id,
tagName: data.tag_name,
name: data.name ?? data.tag_name,
body: data.body ?? "",
draft: data.draft,
prerelease: data.prerelease,
htmlUrl: data.html_url,
uploadUrl: data.upload_url,
createdAt: data.created_at,
publishedAt: data.published_at,
});