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

import * as Repos from "@distilled.cloud/github/repos";
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 Data from "effect/Data";
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 class RepositoryOperationFailed extends Data.TaggedError("RepositoryOperationFailed")<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

export interface RepositoryProps {
  /**
   * Repository owner — a user or organization login.
   *
   * Changing the owner replaces the repository: a NEW, EMPTY repository is
   * created under the new owner — history, issues, and pull requests are
   * not carried over. The old repository is retained on GitHub under the
   * default `retain` removal policy; it is only deleted when the resource
   * opted into deletion via `destroy()`. To actually move a repository
   * between owners with its history, transfer it in the GitHub UI/API
   * first, then update `owner` here and deploy with `--adopt`.
   */
  owner: string;

  /**
   * Repository name. Renaming (deploying with the same logical ID and a
   * different `name`) renames the existing repository in place rather than
   * replacing it.
   */
  name: string;

  /**
   * Short description shown on the repository page.
   */
  description?: string;

  /**
   * Homepage URL shown on the repository page.
   */
  homepage?: string;

  /**
   * Repository visibility. `internal` is only valid for repositories owned by
   * an organization on GitHub Enterprise. When omitted, GitHub's default
   * applies (`public`).
   * @default "public"
   */
  visibility?: "public" | "private" | "internal";

  /**
   * Whether the Issues tab is enabled.
   * @default true
   */
  hasIssues?: boolean;

  /**
   * Whether the Projects tab is enabled.
   * @default true
   */
  hasProjects?: boolean;

  /**
   * Whether the Wiki tab is enabled.
   * @default true
   */
  hasWiki?: boolean;

  /**
   * Whether GitHub Discussions are enabled.
   * @default false
   */
  hasDiscussions?: boolean;

  /**
   * Whether the repository is a template repository.
   * @default false
   */
  isTemplate?: boolean;

  /**
   * Whether the repository is archived (read-only).
   * @default false
   */
  archived?: boolean;

  /**
   * The default branch name. Only applied to repositories that already have
   * at least one branch — setting it on an empty repository has no effect.
   */
  defaultBranch?: string;

  /**
   * Whether squash merges are allowed.
   * @default true
   */
  allowSquashMerge?: boolean;

  /**
   * Whether merge commits are allowed.
   * @default true
   */
  allowMergeCommit?: boolean;

  /**
   * Whether rebase merges are allowed.
   * @default true
   */
  allowRebaseMerge?: boolean;

  /**
   * Whether auto-merge is enabled for pull requests.
   * @default false
   */
  allowAutoMerge?: boolean;

  /**
   * Whether head branches are automatically deleted after a pull request is
   * merged.
   * @default false
   */
  deleteBranchOnMerge?: boolean;

  /**
   * Repository topics. The provided list fully replaces the existing topics.
   */
  topics?: string[];

  /**
   * Initialize the repository with an empty README on creation. Only used at
   * create time — ignored on subsequent updates.
   * @default false
   */
  autoInit?: boolean;

  /**
   * Name of the `.gitignore` template to apply on creation (e.g. `"Node"`).
   * Only used at create time.
   */
  gitignoreTemplate?: string;

  /**
   * Keyword of the license template to apply on creation (e.g. `"mit"`).
   * Only used at create time.
   */
  licenseTemplate?: 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 Repository extends Resource<
  "GitHub.Repository",
  RepositoryProps,
  {
    /**
     * Numeric GitHub repository ID.
     */
    repoId: number;

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

    /**
     * Full name in `owner/name` form.
     */
    fullName: string;

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

    /**
     * Git protocol clone URL (`git://`).
     */
    gitUrl: string;

    /**
     * SSH clone URL (`git@github.com:owner/name.git`).
     */
    sshUrl: string;

    /**
     * HTTPS clone URL.
     */
    cloneUrl: string;

    /**
     * The resolved default branch name.
     */
    defaultBranch: string;

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

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

/**
 * A GitHub repository.
 *
 * `Repository` manages the lifecycle of a repository owned by a user or
 * organization. The repository is created on first deploy and its settings are
 * converged on every subsequent deploy.
 *
 * Repositories default to **retain** on removal — destroying the stack does
 * NOT delete the repository on GitHub, protecting its irreplaceable history
 * (issues, pull requests, commits). Opt in to actual deletion by wrapping the
 * resource (or the whole stack) 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 `delete_repo` when deletion is opted in via `destroy()`).
 * ### Creating a Repository
 * **Example:** Basic Repository
 * ```typescript
 * const repo = yield* GitHub.Repository("api", {
 *   owner: "my-org",
 *   name: "api",
 *   description: "API service",
 *   autoInit: true,
 * });
 * ```
 *
 * **Example:** Private Repository with Settings
 * ```typescript
 * const repo = yield* GitHub.Repository("internal-tools", {
 *   owner: "my-org",
 *   name: "internal-tools",
 *   visibility: "private",
 *   hasWiki: false,
 *   hasProjects: false,
 *   deleteBranchOnMerge: true,
 * });
 * ```
 *
 * **Example:** Initialize from Templates
 * The `autoInit`, `gitignoreTemplate`, and `licenseTemplate` props seed the
 * first commit. They are only honored at create time — changing them on a
 * later deploy has no effect on an existing repository.
 * ```typescript
 * const repo = yield* GitHub.Repository("service", {
 *   owner: "my-org",
 *   name: "service",
 *   autoInit: true,
 *   gitignoreTemplate: "Node",
 *   licenseTemplate: "mit",
 * });
 * ```
 *
 * ### Topics and Merge Configuration
 * **Example:** Repository with Topics and Merge Policy
 * ```typescript
 * const repo = yield* GitHub.Repository("sdk", {
 *   owner: "my-org",
 *   name: "sdk",
 *   topics: ["typescript", "effect", "sdk"],
 *   allowMergeCommit: false,
 *   allowRebaseMerge: false,
 *   allowSquashMerge: true,
 *   allowAutoMerge: true,
 * });
 * ```
 *
 * ### Renaming a Repository
 * **Example:** Rename in Place
 * Keep the same logical ID and change `name` to rename the live repository
 * instead of replacing it — the repository's history, issues, and pull
 * requests are preserved. Only changing `owner` triggers a replacement.
 * ```typescript
 * // First deploy creates "api".
 * const repo = yield* GitHub.Repository("api", {
 *   owner: "my-org",
 *   name: "api",
 * });
 *
 * // A later deploy with the SAME logical ID ("api") renames it to "gateway".
 * const repo = yield* GitHub.Repository("api", {
 *   owner: "my-org",
 *   name: "gateway",
 * });
 * ```
 *
 * ### Archiving a Repository
 * **Example:** Make a Repository Read-Only
 * Archiving sets the repository to read-only. Set `archived` back to `false`
 * on a later deploy to un-archive it.
 * ```typescript
 * yield* GitHub.Repository("legacy", {
 *   owner: "my-org",
 *   name: "legacy-service",
 *   archived: true,
 * });
 * ```
 *
 * ### Wiring with Other Resources
 * The repository's outputs can drive other GitHub resources so the whole
 * repository configuration lives in one program.
 *
 * **Example:** Seed a Variable into the Repository
 * ```typescript
 * const repo = yield* GitHub.Repository("api", {
 *   owner: "my-org",
 *   name: "api",
 *   autoInit: true,
 * });
 *
 * yield* GitHub.Variable("region", {
 *   owner: "my-org",
 *   repository: repo.name!,
 *   name: "AWS_REGION",
 *   value: "us-east-1",
 * });
 * ```
 *
 * **Example:** Store a Secret in the Repository
 * ```typescript
 * import * as Redacted from "effect/Redacted";
 *
 * const repo = yield* GitHub.Repository("api", {
 *   owner: "my-org",
 *   name: "api",
 *   autoInit: true,
 * });
 *
 * yield* GitHub.Secret("deploy-token", {
 *   owner: "my-org",
 *   repository: repo.name!,
 *   name: "DEPLOY_TOKEN",
 *   value: Redacted.make("my-secret-value"),
 * });
 * ```
 *
 * ### Deleting a Repository
 * **Example:** Allow Repository Deletion
 * ```typescript
 * import { destroy } from "alchemy/RemovalPolicy";
 *
 * yield* GitHub.Repository("ephemeral", {
 *   owner: "my-org",
 *   name: "ephemeral-preview",
 * }).pipe(destroy());
 * ```
 *
 * @resource
 * @product Repository
 */
export const Repository = Resource<Repository>("GitHub.Repository", {
  defaultRemovalPolicy: "retain",
});

export const RepositoryProvider = () =>
  Provider.succeed(Repository, {
    stables: ["repoId", "nodeId"],

    // Structural changes are the owner (we deliberately do NOT call GitHub's
    // transfer API — user-to-user transfers require out-of-band acceptance
    // and cannot converge deterministically) and the host (the same repo
    // name on a different GitHub instance is a different repository). A
    // `name` change is a rename, handled in `reconcile`, not a replacement.
    //
    // Replacement is guarded by the resource's default `retain` removal
    // policy: the engine creates the new repository and RETAINS the old one
    // on GitHub (Apply honors `retain` for the replaced old generation), so
    // history is never destroyed unless the user opted into `destroy()`.
    diff: Effect.fn(function* ({ news, olds }) {
      if (!isResolved(news)) return;
      if (olds === undefined) return;
      if (news.owner !== olds.owner || (yield* gitHubBaseUrlChanged(olds, news))) {
        return { action: "replace" };
      }
    }),

    reconcile: Effect.fn(
      function* ({ news, olds }) {
        const getRepo = (repo: string) =>
          Repos.get({ owner: news.owner, repo }).pipe(
            Effect.catchTag("NotFound", () => Effect.undefined),
          );

        // Observe — probe for the live repository under the desired name. On a
        // rename (name changed since last deploy) the desired name 404s, so fall
        // back to the prior name so we converge by renaming rather than creating
        // a duplicate.
        let observed = yield* getRepo(news.name);
        if (observed === undefined && olds?.name !== undefined && olds.name !== news.name) {
          observed = yield* getRepo(olds.name);
        }

        // Ensure — create the repository when it does not exist. The owner may be
        // a user or an organization; pick the matching create endpoint.
        if (observed === undefined) {
          const owner = yield* Users.getByUsername({ username: news.owner });

          const createInput = {
            name: news.name,
            description: news.description,
            homepage: news.homepage,
            has_issues: news.hasIssues,
            has_projects: news.hasProjects,
            has_wiki: news.hasWiki,
            is_template: news.isTemplate,
            auto_init: news.autoInit,
            gitignore_template: news.gitignoreTemplate,
            license_template: news.licenseTemplate,
            allow_squash_merge: news.allowSquashMerge,
            allow_merge_commit: news.allowMergeCommit,
            allow_rebase_merge: news.allowRebaseMerge,
            allow_auto_merge: news.allowAutoMerge,
            delete_branch_on_merge: news.deleteBranchOnMerge,
          };

          observed = yield* (
            owner.type === "Organization"
              ? // The org endpoint accepts `visibility` directly, which is the
                // sole authority over public/private/internal. `internal` is
                // only valid here.
                Repos.createInOrg({ org: news.owner, ...createInput, visibility: news.visibility })
              : // A personal account is either a `User` or a `Bot`; both create
                // through the authenticated-user endpoint, which only
                // understands the boolean `private` flag.
                Repos.createForAuthenticatedUser({
                  ...createInput,
                  private: news.visibility ? news.visibility !== "public" : undefined,
                })
          ).pipe(
            // A 422 means the name already exists — treat as a create race
            // and re-observe so the sync step converges its settings.
            Effect.catchTag("UnprocessableEntity", () => Effect.undefined),
          );

          if (observed === undefined) {
            observed = yield* getRepo(news.name);
          }
          if (observed === undefined) {
            return yield* new RepositoryOperationFailed({
              message: `Failed to create or locate GitHub repository ${news.owner}/${news.name}`,
            });
          }
        }

        // Sync — converge settings (and the name on a rename) against the live
        // repository. GitHub's update is an idempotent PATCH, so we always issue
        // it with the desired settings. `archived` is applied in a separate,
        // later PATCH because an archived repository rejects any other settings
        // change in the same call.
        const repoName = observed.name;
        const updateInput = {
          owner: news.owner,
          repo: repoName,
          name: news.name,
          description: news.description,
          homepage: news.homepage,
          private: news.visibility ? news.visibility !== "public" : undefined,
          visibility: news.visibility,
          has_issues: news.hasIssues,
          has_projects: news.hasProjects,
          has_wiki: news.hasWiki,
          has_discussions: news.hasDiscussions,
          is_template: news.isTemplate,
          allow_squash_merge: news.allowSquashMerge,
          allow_merge_commit: news.allowMergeCommit,
          allow_rebase_merge: news.allowRebaseMerge,
          allow_auto_merge: news.allowAutoMerge,
          delete_branch_on_merge: news.deleteBranchOnMerge,
          // Only set the default branch when it actually differs from the
          // observed branch. GitHub returns 422 if the branch does not yet
          // exist (e.g. an empty repo), so the 422 handler below strips it and
          // retries rather than hard-failing — the branch may be created right
          // after this deploy.
          default_branch:
            news.defaultBranch !== undefined && observed.default_branch !== news.defaultBranch
              ? news.defaultBranch
              : undefined,
        };

        const updated = yield* Repos.update(updateInput).pipe(
          // A 422 on a default-branch update usually means the branch does not
          // exist yet. Drop it and retry so the rest of the settings still
          // converge.
          Effect.catchTag("UnprocessableEntity", (error) => {
            if (!updateInput.default_branch) return Effect.fail(error);
            const { default_branch: _default_branch, ...withoutBranch } = updateInput;
            return Repos.update(withoutBranch);
          }),
        );

        // Sync — apply `archived` in its own PATCH. Use the confirmed
        // post-rename name from the first update so the call targets the right
        // repo. Archiving is one-directional in this PATCH: only send it when
        // explicitly provided.
        if (news.archived !== undefined) {
          yield* Repos.update({ owner: news.owner, repo: updated.name, archived: news.archived });
        }

        // Sync — topics are managed via a dedicated endpoint. The provided list
        // fully replaces existing topics, so removing the field (defined -> undefined)
        // must clear them. Use the confirmed post-rename name from the first PATCH.
        if (news.topics !== undefined || olds?.topics !== undefined) {
          yield* Repos.replaceAllTopics({
            owner: news.owner,
            repo: updated.name,
            names: news.topics ?? [],
          });
        }

        return attrsOf(updated);
      },
      (effect, { news }) => effect.pipe(withBaseUrl(news.baseUrl)),
    ),

    // Enumerate every repository the authenticated token can see. GitHub has no
    // account/region scope resolved from env services — the ambient scope is the
    // token itself, so we list the authenticated user's repositories (across all
    // owners/orgs the token is a member of), every page. Each list item is a
    // full repository object, so it hydrates directly into the same
    // `Attributes` shape `read` returns.
    list: Effect.fn(function* () {
      const repos = yield* Stream.runCollect(
        Repos.listForAuthenticatedUser.items({ per_page: 100 }),
      );
      return repos.map(attrsOf);
    }),

    // Read by the numeric repository ID, which is stable across renames. This
    // refreshes the output attributes (including the current name) so that a
    // subsequent delete targets the live repository even when a prior rename's
    // state persistence failed.
    read: Effect.fn(
      function* ({ output }) {
        if (output === undefined) {
          return undefined;
        }
        return yield* Repos.getById({ id: output.repoId }).pipe(
          Effect.map(attrsOf),
          Effect.catchTag("NotFound", () => Effect.undefined),
        );
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),

    delete: Effect.fn(
      function* ({ olds, output }) {
        // Resolve the current repository name via the stable numeric ID. A rename
        // whose state persistence failed leaves `olds.name` stale; deleting by
        // the stale name 404s and silently leaves the repo behind. Looking it up
        // by `repoId` gives us the live name.
        const current =
          output?.repoId !== undefined
            ? yield* Repos.getById({ id: output.repoId }).pipe(
                Effect.catchTag("NotFound", () => Effect.undefined),
              )
            : undefined;

        yield* Repos.Delete({
          owner: current?.owner.login ?? olds.owner,
          repo: current?.name ?? olds.name,
        }).pipe(Effect.catchTag("NotFound", () => Effect.void));
      },
      (effect, { olds }) => effect.pipe(withBaseUrl(olds.baseUrl)),
    ),
  });

const attrsOf = (data: {
  id: number;
  node_id: string;
  full_name: string;
  html_url: string;
  git_url: string;
  ssh_url: string;
  clone_url: string;
  default_branch: string;
  created_at: string | null;
  updated_at: string | null;
}) => ({
  repoId: data.id,
  nodeId: data.node_id,
  fullName: data.full_name,
  htmlUrl: data.html_url,
  gitUrl: data.git_url,
  sshUrl: data.ssh_url,
  cloneUrl: data.clone_url,
  defaultBranch: data.default_branch,
  createdAt: data.created_at ?? new Date().toISOString(),
  updatedAt: data.updated_at ?? new Date().toISOString(),
});