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

import * as Repos from "@distilled.cloud/github/repos";
import * as Teams from "@distilled.cloud/github/teams";
import * as Users from "@distilled.cloud/github/users";
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 EnvironmentProps {
  /**
   * Repository owner (user or organization).
   */
  owner: string;

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

  /**
   * Environment name (e.g. `production`, `staging`). The name is the
   * environment's identity — changing it replaces the environment.
   */
  name: string;

  /**
   * Minutes to wait before allowing deployments to proceed (0–43200,
   * i.e. up to 30 days). Requires a plan that supports environment
   * protection rules on the repository.
   * @default 0
   */
  waitTimer?: number;

  /**
   * Whether users who created or pushed the deployment are prevented
   * from approving their own deployment.
   * @default false
   */
  preventSelfReview?: boolean;

  /**
   * The people or teams that must review deployments to this environment.
   * Up to six users or teams in total; reviewers must have at least read
   * access to the repository. Users are referenced by login, teams by
   * slug (teams are only valid for organization-owned repositories).
   */
  reviewers?: {
    /**
     * User logins allowed to review deployments.
     */
    users?: string[];

    /**
     * Team slugs (within the owning organization) allowed to review
     * deployments.
     */
    teams?: string[];
  };

  /**
   * Which branches can deploy to this environment. Omit to allow all
   * branches. Set `protectedBranches: true` to restrict deployments to
   * branches with branch protection rules, or `customBranchPolicies` to a
   * list of branch name patterns (e.g. `["main", "release/*"]`).
   */
  deploymentBranchPolicy?: { protectedBranches: true } | { customBranchPolicies: 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 Environment extends Resource<
  "GitHub.Environment",
  EnvironmentProps,
  {
    /**
     * Numeric GitHub environment ID.
     */
    environmentId: number;

    /**
     * GraphQL node ID of the environment.
     */
    nodeId: string;

    /**
     * The environment name.
     */
    name: string;

    /**
     * URL to view the environment in a browser.
     */
    htmlUrl: string;

    /**
     * ISO-8601 timestamp of when the environment was created.
     */
    createdAt: string;

    /**
     * ISO-8601 timestamp of the last update.
     */
    updatedAt: string;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub Actions deployment environment.
 *
 * `Environment` manages a repository's deployment environment (e.g.
 * `production`, `staging`) along with its protection rules: required
 * reviewers, wait timers, self-review prevention, and deployment branch
 * policies. Pair it with `GitHub.Secret` and `GitHub.Variable` (both accept
 * an `environment` prop) to scope configuration to the environment.
 *
 * Environments are available on public repositories on every plan; private
 * repositories require GitHub Pro, Team, or Enterprise, and protection
 * rules on private repositories require Team or Enterprise.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied
 * by `GitHub.providers()` (env, stored PAT, `gh` CLI, or OAuth). The token
 * needs `repo` scope.
 * ### Creating an Environment
 * **Example:** Basic Environment
 * ```typescript
 * const production = yield* GitHub.Environment("production", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "production",
 * });
 * ```
 *
 * **Example:** Environment with Protection Rules
 * ```typescript
 * yield* GitHub.Environment("production", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "production",
 *   waitTimer: 30,
 *   preventSelfReview: true,
 *   reviewers: {
 *     users: ["release-manager"],
 *     teams: ["platform"],
 *   },
 * });
 * ```
 *
 * ### Deployment Branch Policies
 * **Example:** Restrict to Protected Branches
 * ```typescript
 * yield* GitHub.Environment("production", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "production",
 *   deploymentBranchPolicy: { protectedBranches: true },
 * });
 * ```
 *
 * **Example:** Restrict to Branch Name Patterns
 * ```typescript
 * yield* GitHub.Environment("production", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "production",
 *   deploymentBranchPolicy: {
 *     customBranchPolicies: ["main", "release/*"],
 *   },
 * });
 * ```
 *
 * ### Environment Secrets and Variables
 * **Example:** Scope Secrets and Variables to the Environment
 * ```typescript
 * const env = yield* GitHub.Environment("production", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "production",
 * });
 *
 * yield* GitHub.Secret("deploy-key", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   environment: env,
 *   name: "DEPLOY_KEY",
 *   value: Redacted.make("my-secret-value"),
 * });
 *
 * yield* GitHub.Variable("region", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   environment: env,
 *   name: "AWS_REGION",
 *   value: "us-east-1",
 * });
 * ```
 *
 * @resource
 * @product Actions
 */
export const Environment = Resource<Environment>("GitHub.Environment");

// At runtime, Resource references in props are resolved to their full
// attributes — so an `Environment` passed to another resource's
// `environment` prop arrives as `{ name: string; ... }` rather than the
// statically-typed Resource (whose attributes are `Output<...>`). We cast
// through the structural shape here.
export const resolveEnvironmentName = (
  environment: string | Environment | undefined,
): string | undefined => {
  const ref = environment as unknown as string | { name: string } | undefined;
  return ref === undefined ? undefined : typeof ref === "string" ? ref : ref.name;
};

export const EnvironmentProvider = () =>
  Provider.succeed(Environment, {
    stables: ["environmentId", "nodeId"],

    // The environment name is its path identity — GitHub has no rename, so
    // changing owner, repository, name, or the host 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, olds }) {
        const scope = { owner: news.owner, repo: news.repository, environment_name: news.name };

        // Resolve reviewer logins/slugs to the numeric IDs the API expects.
        const reviewers =
          news.reviewers === undefined
            ? null
            : [
                ...(yield* Effect.forEach(news.reviewers.users ?? [], (username) =>
                  Users.getByUsername({ username }).pipe(
                    Effect.map((user) => ({ type: "User" as const, id: user.id })),
                  ),
                )),
                ...(yield* Effect.forEach(news.reviewers.teams ?? [], (team_slug) =>
                  Teams.getByName({ org: news.owner, team_slug }).pipe(
                    Effect.map((team) => ({ type: "Team" as const, id: team.id })),
                  ),
                )),
              ];

        // Ensure & Sync — the PUT is a full upsert of the environment's
        // protection configuration. Protection rules are only sent when set now
        // or previously (olds): on private repos without GitHub Enterprise,
        // sending them at all — even as defaults — is rejected as a billing
        // error. A prop that was set before and is now removed is sent as its
        // explicit default so it converges. `prevent_self_review` and
        // `reviewers` are sent together: GitHub rejects the former when the
        // latter is omitted (an explicit `null` is accepted).
        const sendWaitTimer = news.waitTimer !== undefined || olds?.waitTimer !== undefined;
        const sendReviewers =
          news.reviewers !== undefined ||
          news.preventSelfReview !== undefined ||
          olds?.reviewers !== undefined ||
          olds?.preventSelfReview !== undefined;
        const environment = yield* Repos.createOrUpdateEnvironment({
          ...scope,
          ...(sendWaitTimer ? { wait_timer: news.waitTimer ?? 0 } : {}),
          ...(sendReviewers
            ? {
                prevent_self_review: news.preventSelfReview ?? false,
                reviewers: reviewers === null || reviewers.length === 0 ? null : reviewers,
              }
            : {}),
          deployment_branch_policy:
            news.deploymentBranchPolicy === undefined
              ? null
              : "protectedBranches" in news.deploymentBranchPolicy
                ? { protected_branches: true, custom_branch_policies: false }
                : { protected_branches: false, custom_branch_policies: true },
        });

        // Sync — custom branch policies live behind dedicated endpoints. Diff
        // the observed patterns against the desired list; create the missing
        // ones and delete the extras. Skipped entirely unless the policy mode
        // is custom (GitHub drops the policies itself when the mode changes).
        if (
          news.deploymentBranchPolicy !== undefined &&
          "customBranchPolicies" in news.deploymentBranchPolicy
        ) {
          const desired = news.deploymentBranchPolicy.customBranchPolicies;
          const observed = yield* Stream.runCollect(
            Repos.listDeploymentBranchPolicies.items({ ...scope, per_page: 100 }),
          );
          const observedNames = new Set(observed.map((policy) => policy.name));
          for (const name of desired) {
            if (!observedNames.has(name)) {
              yield* Repos.createDeploymentBranchPolicy({ ...scope, name, type: "branch" });
            }
          }
          for (const policy of observed) {
            if (
              policy.id !== undefined &&
              policy.name !== undefined &&
              !desired.includes(policy.name)
            ) {
              yield* Repos.deleteDeploymentBranchPolicy({ ...scope, branch_policy_id: policy.id });
            }
          }
        }

        return {
          environmentId: environment.id,
          nodeId: environment.node_id,
          name: environment.name,
          htmlUrl: environment.html_url,
          createdAt: environment.created_at,
          updatedAt: environment.updated_at,
        };
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    // Enumerate every environment across the repositories the token can see —
    // environments 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(
            Repos.getAllEnvironments.items({
              owner: repo.owner.login,
              repo: repo.name,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((environments) =>
              environments.map((environment) => ({
                environmentId: environment.id,
                nodeId: environment.node_id,
                name: environment.name,
                htmlUrl: environment.html_url,
                createdAt: environment.created_at,
                updatedAt: environment.updated_at,
              })),
            ),
            // Repos without environments support (plan limits) or where the
            // token lacks 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* Repos.deleteAnEnvironment({
          owner: olds.owner,
          repo: olds.repository,
          environment_name: olds.name,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });