sailfork / t3code-github / .repos/ alchemy-effect/ packages/ github/ src/ Collaborator.ts

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 CollaboratorProps {
  /**
   * Repository owner — a user or organization login.
   */
  owner: string;

  /**
   * Repository name.
   */
  repository: string;

  /**
   * GitHub username to grant access.
   */
  username: string;

  /**
   * Permission level to grant.
   * - `pull` — read-only access
   * - `push` — read and write access
   * - `maintain` — read, write, and manage issues/PRs
   * - `triage` — read and manage issues/PRs without write access
   * - `admin` — full admin access
   *
   * @default "push"
   */
  permission?: "pull" | "push" | "maintain" | "triage" | "admin";

  /**
   * 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 Collaborator extends Resource<
  "GitHub.Collaborator",
  CollaboratorProps,
  {
    /**
     * GitHub username.
     */
    username: string;

    /**
     * Permission level granted.
     */
    permission: string;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub repository collaborator.
 *
 * `Collaborator` grants a user direct access to a repository. For
 * organization-owned repositories, prefer `GitHub.TeamAccess` to grant
 * access through teams instead of individual users.
 *
 * Collaborators default to **retain** on removal — destroying the stack does
 * NOT remove the collaborator, preventing accidental lockout. Opt in to
 * actual removal by wrapping the resource in {@link destroy}() from
 * `alchemy/RemovalPolicy`.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied by
 * `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token needs
 * `repo` scope (and `admin:repo` for removal when opted in via `destroy()`).
 *
 * ### Adding a Collaborator
 * **Example:** Grant Push Access
 * ```typescript
 * yield* GitHub.Collaborator("collaborator", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   username: "contributor",
 *   permission: "push",
 * })
 * ```
 *
 * **Example:** Grant Admin Access
 * ```typescript
 * yield* GitHub.Collaborator("admin", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   username: "team-lead",
 *   permission: "admin",
 * })
 * ```
 *
 * **Example:** Grant Read-Only Access
 * ```typescript
 * yield* GitHub.Collaborator("readonly", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   username: "auditor",
 *   permission: "pull",
 * })
 * ```
 *
 * ### Removing a Collaborator
 * **Example:** Allow Removal on Destroy
 * ```typescript
 * import { destroy } from "alchemy/RemovalPolicy"
 *
 * yield* GitHub.Collaborator("temp", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   username: "contractor",
 *   permission: "push",
 * }).pipe(destroy())
 * ```
 *
 * @resource
 * @product Repository
 */
export const Collaborator = Resource<Collaborator>("GitHub.Collaborator", {
  defaultRemovalPolicy: "retain",
});

export const CollaboratorProvider = () =>
  Provider.succeed(Collaborator, {
    diff: Effect.fn(function* ({ news, olds }) {
      if (!isResolved(news)) return;
      if (olds === undefined) return;
      if (
        news.owner !== olds.owner ||
        news.repository !== olds.repository ||
        news.username !== olds.username ||
        (yield* gitHubBaseUrlChanged(olds, news))
      ) {
        return { action: "replace" };
      }
    }),

    reconcile: Effect.fn(
      function* ({ news }) {
        // Ensure & Sync — PUT is idempotent; creates or updates permission
        yield* Repos.addCollaborator({
          owner: news.owner,
          repo: news.repository,
          username: news.username,
          permission: news.permission ?? "push",
        });

        return {
          username: news.username,
          permission: news.permission ?? "push",
        };
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    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.listCollaborators.items({
              owner: repo.owner.login,
              repo: repo.name,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((collaborators) =>
              collaborators.map((collab) => ({
                username: collab.login,
                permission: collab.permissions?.admin
                  ? ("admin" as const)
                  : collab.permissions?.maintain
                    ? ("maintain" as const)
                    : collab.permissions?.push
                      ? ("push" as const)
                      : collab.permissions?.triage
                        ? ("triage" as const)
                        : ("pull" as const),
              })),
            ),
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(
      function* ({ olds }) {
        yield* Repos.removeCollaborator({
          owner: olds.owner,
          repo: olds.repository,
          username: olds.username,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });