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 * 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 LabelProps {
/**
* Repository owner (user or organization).
*/
owner: string;
/**
* Repository name.
*/
repository: string;
/**
* Label name. The name is the label's identity — changing it replaces the
* label.
*/
name: string;
/**
* Label color (6-character hex code without the leading `#`).
* @default "ededed"
*/
color?: string;
/**
* Short description of the label.
*/
description?: string;
/**
* 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 Label extends Resource<
"GitHub.Label",
LabelProps,
{
/**
* Numeric label ID.
*/
labelId: number;
/**
* GraphQL node ID of the label.
*/
nodeId: string;
/**
* The label name.
*/
name: string;
/**
* The label color (6-character hex code without the leading `#`).
*/
color: string;
/**
* Label description.
*/
description: string | null;
/**
* URL to view the label in a browser.
*/
url: string;
/**
* Whether this is a default label (created by GitHub).
*/
default: boolean;
},
never,
GitHub.Providers
> {}
/**
* A GitHub repository label.
*
* `Label` manages repository labels for categorizing issues and pull requests.
* Labels are created on first deploy and updated in place on subsequent
* deploys when properties change.
*
* 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 Labels
* **Example:** Basic Label
* ```typescript
* const bug = yield* GitHub.Label("bug", {
* owner: "my-org",
* repository: "my-repo",
* name: "bug",
* color: "d73a4a",
* description: "Something isn't working",
* });
* ```
*
* **Example:** Multiple Labels
* ```typescript
* yield* GitHub.Label("feature", {
* owner: "my-org",
* repository: "my-repo",
* name: "feature",
* color: "a2eeef",
* description: "New feature or request",
* });
*
* yield* GitHub.Label("documentation", {
* owner: "my-org",
* repository: "my-repo",
* name: "documentation",
* color: "0075ca",
* description: "Improvements or additions to documentation",
* });
* ```
*
* ### Updating Labels
* Deploy with the same logical ID and different properties to update the
* existing label in place.
*
* **Example:** Update Color and Description
* ```typescript
* yield* GitHub.Label("priority-high", {
* owner: "my-org",
* repository: "my-repo",
* name: "priority: high",
* color: "ff0000",
* description: "Updated: Critical issues requiring immediate attention",
* });
* ```
*
* ### Label Color Codes
* GitHub uses 6-character hex codes without the `#` prefix. Common colors:
* - `d73a4a` - Red (bugs)
* - `0075ca` - Blue (documentation)
* - `a2eeef` - Light blue (features)
* - `7057ff` - Purple (good first issue)
* - `008672` - Green (improvement)
* - `e4e669` - Yellow (question)
*
* **Example:** Standard Label Set
* ```typescript
* const labels = [
* { name: "bug", color: "d73a4a", description: "Something isn't working" },
* { name: "enhancement", color: "a2eeef", description: "New feature" },
* { name: "documentation", color: "0075ca", description: "Documentation" },
* ];
*
* for (const { name, color, description } of labels) {
* yield* GitHub.Label(name, {
* owner: "my-org",
* repository: "my-repo",
* name,
* color,
* description,
* });
* }
* ```
*
* ### Replacing on Name Change
* Changing the name creates a new label and deletes the old one.
*
* **Example:** Replace by Changing Name
* ```typescript
* // First deploy creates "wip"
* const label = yield* GitHub.Label("work", {
* owner: "my-org",
* repository: "my-repo",
* name: "wip",
* color: "fbca04",
* });
*
* // Later deploy with same logical ID but different name replaces it
* const label = yield* GitHub.Label("work", {
* owner: "my-org",
* repository: "my-repo",
* name: "in-progress",
* color: "fbca04",
* });
* ```
*
* ### Wiring with Other Resources
* **Example:** Create Repository with Labels
* ```typescript
* const repo = yield* GitHub.Repository("api", {
* owner: "my-org",
* name: "api",
* autoInit: true,
* });
*
* yield* GitHub.Label("bug", {
* owner: repo.owner!,
* repository: repo.name!,
* name: "bug",
* color: "d73a4a",
* });
* ```
*
* @resource
* @product Issue
*/
export const Label = Resource<Label>("GitHub.Label");
export const LabelProvider = () =>
Provider.succeed(Label, {
stables: ["labelId", "nodeId"],
// A label belongs to (host, owner, repository, name) — 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.name !== olds.name ||
(yield* gitHubBaseUrlChanged(olds, news))
) {
return { action: "replace" };
}
}),
reconcile: Effect.fn(
function* ({ news }) {
const scope = { owner: news.owner, repo: news.repository, name: news.name };
// Observe — probe for an existing label by name
const observed = yield* Issues.getLabel(scope).pipe(
Effect.catchTag("NotFound", () => Effect.undefined),
);
// Ensure — when no label exists, create one
if (observed === undefined) {
return attrsOf(
yield* Issues.createLabel({
...scope,
color: news.color,
description: news.description,
}),
);
}
// Sync — update the existing label if any properties differ
return attrsOf(
yield* Issues.updateLabel({ ...scope, color: news.color, description: news.description }),
);
},
(effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
),
// Enumerate every label across the repositories the token can see —
// labels are keyed by {owner, repository, name} 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(
Issues.listLabelsForRepo.items({
owner: repo.owner.login,
repo: repo.name,
per_page: 100,
}),
).pipe(
Effect.map((labels) => labels.map(attrsOf)),
// Repos where the token lacks label 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 }) {
yield* Issues.deleteLabel({
owner: olds.owner,
repo: olds.repository,
name: olds.name,
}).pipe(Effect.catchTag("NotFound", () => Effect.void));
},
(effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
),
});
const attrsOf = (data: {
id: number;
node_id: string;
name: string;
color: string;
description: string | null;
url: string;
default: boolean;
}) => ({
labelId: data.id,
nodeId: data.node_id,
name: data.name,
color: data.color,
description: data.description,
url: data.url,
default: data.default,
});