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

import * as Repos from "@distilled.cloud/github/repos";
import * as Teams from "@distilled.cloud/github/teams";
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 TeamAccessProps {
  /**
   * Repository owner — must be an organization login.
   */
  owner: string;

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

  /**
   * Team slug within the organization (e.g. `platform`, `frontend`).
   */
  teamSlug: 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 TeamAccess extends Resource<
  "GitHub.TeamAccess",
  TeamAccessProps,
  {
    /**
     * Team slug.
     */
    teamSlug: string;

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

/**
 * A GitHub team repository access grant.
 *
 * `TeamAccess` grants a team access to a repository within an organization.
 * Teams provide a scalable way to manage repository permissions — add users
 * to teams instead of granting individual collaborator access.
 *
 * Team access grants default to **retain** on removal — destroying the stack
 * does NOT remove the team's access, 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:org` for managing team access.
 *
 * ### Granting Team Access
 * **Example:** Grant Push Access to a Team
 * ```typescript
 * yield* GitHub.TeamAccess("platform-access", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   teamSlug: "platform",
 *   permission: "push",
 * })
 * ```
 *
 * **Example:** Grant Admin Access to a Team
 * ```typescript
 * yield* GitHub.TeamAccess("admin-access", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   teamSlug: "admins",
 *   permission: "admin",
 * })
 * ```
 *
 * **Example:** Grant Read-Only Access
 * ```typescript
 * yield* GitHub.TeamAccess("readonly", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   teamSlug: "contractors",
 *   permission: "pull",
 * })
 * ```
 *
 * ### Multiple Teams
 * **Example:** Grant Different Permissions to Multiple Teams
 * ```typescript
 * yield* GitHub.TeamAccess("platform-write", {
 *   owner: "my-org",
 *   repository: "api",
 *   teamSlug: "platform",
 *   permission: "push",
 * })
 *
 * yield* GitHub.TeamAccess("security-read", {
 *   owner: "my-org",
 *   repository: "api",
 *   teamSlug: "security",
 *   permission: "pull",
 * })
 * ```
 *
 * ### Removing Team Access
 * **Example:** Allow Removal on Destroy
 * ```typescript
 * import { destroy } from "alchemy/RemovalPolicy"
 *
 * yield* GitHub.TeamAccess("temp", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   teamSlug: "contractors",
 *   permission: "push",
 * }).pipe(destroy())
 * ```
 *
 * @resource
 * @product Repository
 */
export const TeamAccess = Resource<TeamAccess>("GitHub.TeamAccess", {
  defaultRemovalPolicy: "retain",
});

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

    reconcile: Effect.fn(
      function* ({ news }) {
        // Ensure & Sync — PUT is idempotent; adds team or updates permission
        yield* Teams.addOrUpdateRepoPermissionsInOrg({
          org: news.owner,
          team_slug: news.teamSlug,
          owner: news.owner,
          repo: news.repository,
          permission: news.permission ?? "push",
        });

        return {
          teamSlug: news.teamSlug,
          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.listTeams.items({
              owner: repo.owner.login,
              repo: repo.name,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((teams) =>
              teams.map((team) => ({
                teamSlug: team.slug,
                permission: (team.permission ?? "push") as NonNullable<
                  TeamAccessProps["permission"]
                >,
              })),
            ),
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(
      function* ({ olds }) {
        yield* Teams.removeRepoInOrg({
          org: olds.owner,
          team_slug: olds.teamSlug,
          owner: olds.owner,
          repo: olds.repository,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });