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

import * as Actions from "@distilled.cloud/github/actions";
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 Environment, resolveEnvironmentName } from "./Environment.ts";
import type * as GitHub from "./Providers.ts";

export interface VariableProps {
  /**
   * Repository owner (user or organization).
   */
  owner: string;

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

  /**
   * Variable name (e.g. `AWS_ROLE_ARN`).
   */
  name: string;

  /**
   * Variable value.
   */
  value: string;

  /**
   * Optional environment. When set the variable is scoped to that GitHub
   * Actions environment instead of the whole repository. Accepts an
   * environment name or a `GitHub.Environment` resource.
   */
  environment?: string | Environment;

  /**
   * 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 Variable extends Resource<
  "GitHub.Variable",
  VariableProps,
  {
    /**
     * ISO-8601 timestamp of the last update.
     */
    updatedAt: string;
  },
  never,
  GitHub.Providers
> {}

/**
 * A GitHub Actions repository variable.
 *
 * `Variable` manages the lifecycle of a plain-text configuration variable
 * in GitHub Actions. Variables are visible in workflow logs and are
 * suitable for non-sensitive configuration like region names, environment
 * labels, or feature flags. For sensitive values, use `GitHub.Secret`
 * instead.
 *
 * Authentication is resolved via the GitHub `Credentials` service supplied
 * by `GitHub.providers()` (which uses the Alchemy AuthProvider — env,
 * stored PAT, `gh` CLI, or OAuth). The token needs `repo` scope for
 * private repositories or `public_repo` for public ones.
 * ### Repository Variables
 * Store variables accessible to all GitHub Actions workflows in the
 * repository.
 *
 * **Example:** Create a Repository Variable
 * ```typescript
 * yield* GitHub.Variable("aws-region", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "AWS_REGION",
 *   value: "us-east-1",
 * });
 * ```
 *
 * ### Environment Variables
 * Scope a variable to a specific GitHub Actions environment (e.g.
 * `production`, `staging`). Use `GitHub.Environment` to manage the
 * environment itself.
 *
 * **Example:** Create an Environment Variable
 * ```typescript
 * yield* GitHub.Variable("region", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   environment: "production",
 *   name: "AWS_REGION",
 *   value: "us-east-1",
 * });
 * ```
 *
 * ### Wiring with Other Resources
 * Pass output attributes from other resources into GitHub variables so
 * that CI workflows can reference them.
 *
 * **Example:** Store a Worker URL for CI
 * ```typescript
 * const worker = yield* Cloudflare.Worker("Api", { ... });
 *
 * yield* GitHub.Variable("api-url", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "API_URL",
 *   value: worker.url!,
 * });
 * ```
 *
 * **Example:** Multiple Variables
 * ```typescript
 * yield* GitHub.Variable("region", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "AWS_REGION",
 *   value: "us-east-1",
 * });
 *
 * yield* GitHub.Variable("stage", {
 *   owner: "my-org",
 *   repository: "my-repo",
 *   name: "DEPLOY_STAGE",
 *   value: "production",
 * });
 * ```
 *
 * @resource
 * @product Actions
 */
export const Variable = Resource<Variable>("GitHub.Variable");

export const VariableProvider = () =>
  Provider.succeed(Variable, {
    // A variable's entire identity is (host, owner, repository, environment,
    // name) — GitHub has no rename/move API for variables, so changing any
    // of them replaces the resource: the engine creates the new variable
    // first, then `delete` removes the old one from its old location.
    // Replacement is safe here — a variable is declarative config that is
    // fully re-creatable from props.
    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 ||
        resolveEnvironmentName(news.environment) !== resolveEnvironmentName(olds.environment) ||
        (yield* gitHubBaseUrlChanged(olds, news))
      ) {
        return { action: "replace" };
      }
    }),

    reconcile: Effect.fn(function* ({ news, olds }) {
      // A variable is keyed by its location (repo vs. environment). A
      // location change normally arrives as a replacement (see `diff`); this
      // guard is the safety net for the plan-time path where `news` contained
      // unresolved outputs and diff could not compare — delete the orphaned
      // variable from its old location before converging the new one.
      if (
        olds !== undefined &&
        resolveEnvironmentName(olds.environment) !== resolveEnvironmentName(news.environment)
      ) {
        yield* deleteVariable(olds);
      }

      // Observe — `name` is the path identifier; ask GitHub directly for the
      // live row. A 404 means it doesn't exist (deleted out-of-band, or never
      // created), so we converge by creating it; otherwise we PATCH the value.
      const observed = yield* getVariable(news);

      // Ensure — POST creates the variable.
      if (observed === undefined) {
        yield* createVariable(news);
        return { updatedAt: new Date().toISOString() };
      }

      // Sync — PATCH the value if it drifted; skip the call when the
      // observed value already matches to keep the API quiet.
      if (observed.value !== news.value) {
        yield* updateVariable(news);
      }
      return { updatedAt: new Date().toISOString() };
    }),

    // Enumerate every Actions variable visible to the authenticated token.
    // GitHub variables are keyed by {owner, repository, name} and there is no
    // account-wide "list all variables" endpoint, so the ambient scope is the
    // authenticated account: list every repository the token can see, then
    // exhaustively paginate each repo's variables and hydrate into the same
    // `Attributes` shape `reconcile` returns. Variable values are readable
    // (unlike secrets), but the resource's `Attributes` only exposes
    // `updatedAt`, so that's all we surface here.
    list: Effect.fn(function* () {
      const repos = yield* Stream.runCollect(
        Repos.listForAuthenticatedUser.items({ per_page: 100 }),
      );
      const perRepo = yield* Effect.forEach(
        repos,
        (repo) =>
          Stream.runCollect(
            Actions.listRepoVariables.items({
              owner: repo.owner.login,
              repo: repo.name,
              per_page: 100,
            }),
          ).pipe(
            Effect.map((variables) => variables.map((v) => ({ updatedAt: v.updated_at }))),
            // Repos with Actions disabled, or where the token lacks the
            // `repo`/`actions` scope, reject the variables endpoint with
            // 403/404 — skip them per the per-item not-found rule rather
            // than failing the whole enumeration.
            Effect.catchTag(["Forbidden", "NotFound"], () => Effect.succeed([])),
          ),
        { concurrency: 10 },
      );
      return perRepo.flat();
    }),

    delete: Effect.fn(function* ({ olds }) {
      yield* deleteVariable(olds);
    }),
  });

/** The variable's location: the repository, or one of its environments. */
const locate = (props: VariableProps) => ({
  scope: { owner: props.owner, repo: props.repository, name: props.name },
  environment: resolveEnvironmentName(props.environment),
});

const getVariable = Effect.fn(
  function* (props: VariableProps) {
    const { scope, environment } = locate(props);
    return yield* (
      environment !== undefined
        ? Actions.getEnvironmentVariable({ ...scope, environment_name: environment })
        : Actions.getRepoVariable(scope)
    ).pipe(Effect.catchTag("NotFound", () => Effect.undefined));
  },
  (effect, props) => effect.pipe(withBaseUrl(props.baseUrl)),
);

const createVariable = Effect.fn(
  function* (props: VariableProps) {
    const { scope, environment } = locate(props);
    yield* environment !== undefined
      ? Actions.createEnvironmentVariable({
          ...scope,
          environment_name: environment,
          value: props.value,
        })
      : Actions.createRepoVariable({ ...scope, value: props.value });
  },
  (effect, props) => effect.pipe(withBaseUrl(props.baseUrl)),
);

const updateVariable = Effect.fn(
  function* (props: VariableProps) {
    const { scope, environment } = locate(props);
    yield* environment !== undefined
      ? Actions.updateEnvironmentVariable({
          ...scope,
          environment_name: environment,
          value: props.value,
        })
      : Actions.updateRepoVariable({ ...scope, value: props.value });
  },
  (effect, props) => effect.pipe(withBaseUrl(props.baseUrl)),
);

const deleteVariable = Effect.fn(
  function* (props: VariableProps) {
    const { scope, environment } = locate(props);
    yield* (
      environment !== undefined
        ? Actions.deleteEnvironmentVariable({ ...scope, environment_name: environment })
        : Actions.deleteRepoVariable(scope)
    ).pipe(Effect.catchTag("NotFound", () => Effect.void));
  },
  (effect, props) => effect.pipe(withBaseUrl(props.baseUrl)),
);