sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Pages/ Project.ts

import * as pages from "@distilled.cloud/cloudflare/pages";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import type { Input } from "alchemy/Input";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { arrayEqualsUnordered } from "alchemy/Util/equal";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Pages.Project" as const;
type TypeId = typeof TypeId;

/**
 * Build configuration for a Pages project. All fields are mutable in place.
 */
export interface BuildConfig {
  /**
   * Enable build caching for the project.
   */
  buildCaching?: boolean;
  /**
   * Command used to build the project (e.g. `npm run build`).
   */
  buildCommand?: string;
  /**
   * Output directory of the build, relative to `rootDir` (e.g. `dist`).
   */
  destinationDir?: string;
  /**
   * Directory to run the build command in. Defaults to the repository root.
   */
  rootDir?: string;
}

/**
 * A single environment variable on a Pages deployment environment.
 */
export interface EnvVar {
  /**
   * Whether the value is stored as plain text or encrypted as a secret.
   * @default "plain_text"
   */
  type?: "plain_text" | "secret_text";
  /**
   * The environment variable value.
   */
  value: string;
}

/**
 * Per-environment (preview / production) deployment configuration.
 *
 * Record-shaped fields (`envVars`, `kvNamespaces`, `d1Databases`,
 * `r2Buckets`) are reconciled key-by-key: Cloudflare's PATCH endpoint
 * deep-merges, so keys observed on the project but absent from the desired
 * config are explicitly removed.
 */
export interface DeploymentConfig {
  /**
   * Environment variables, keyed by variable name.
   */
  envVars?: Record<string, EnvVar>;
  /**
   * KV namespace bindings, keyed by binding name. The value is the KV
   * namespace id (e.g. `kvNamespace.namespaceId`).
   */
  kvNamespaces?: Record<string, string>;
  /**
   * D1 database bindings, keyed by binding name. The value is the D1
   * database UUID (e.g. `database.databaseId`).
   */
  d1Databases?: Record<string, string>;
  /**
   * R2 bucket bindings, keyed by binding name. The value is the bucket
   * name (e.g. `bucket.bucketName`).
   */
  r2Buckets?: Record<string, string>;
  /**
   * Compatibility date used by Pages Functions (e.g. `2025-01-01`).
   */
  compatibilityDate?: string;
  /**
   * Compatibility flags used by Pages Functions.
   */
  compatibilityFlags?: string[];
  /**
   * Whether requests are served (`true`) or rejected (`false`) when a
   * Pages Function exceeds its limits.
   */
  failOpen?: boolean;
  /**
   * Placement settings for Pages Functions (e.g. `{ mode: "smart" }`).
   */
  placement?: { mode: string };
}

/**
 * Deployment configuration for both Pages environments.
 */
export interface DeploymentConfigs {
  /**
   * Configuration applied to preview (non-production-branch) deployments.
   */
  preview?: DeploymentConfig;
  /**
   * Configuration applied to production deployments.
   */
  production?: DeploymentConfig;
}

export interface ProjectProps {
  /**
   * Name of the project. Forms the `<name>.pages.dev` subdomain, so it must
   * be unique across all of Cloudflare Pages and contain only lowercase
   * letters, numbers, and dashes. The name is the project's identity —
   * changing it triggers a replacement.
   * @default ${app}-${stage}-${id}
   */
  name?: string;
  /**
   * Production branch of the project. Deployments to this branch are
   * production deployments; any other branch produces a preview deployment.
   * Mutable in place.
   * @default "main"
   */
  productionBranch?: string;
  /**
   * Configs for the project build process. Mutable in place.
   */
  buildConfig?: BuildConfig;
  /**
   * Per-environment deployment configuration (env vars, bindings,
   * compatibility settings). Mutable in place.
   */
  deploymentConfigs?: DeploymentConfigs;
}

export interface ProjectAttributes {
  /**
   * Cloudflare-assigned UUID of the project.
   */
  projectId: string;
  /**
   * The Cloudflare account the project belongs to.
   */
  accountId: string;
  /**
   * Name of the project.
   */
  name: string;
  /**
   * The `*.pages.dev` subdomain serving the project (e.g.
   * `my-project.pages.dev`).
   */
  subdomain: string;
  /**
   * All domains attached to the project, including the `*.pages.dev`
   * subdomain and any custom domains.
   */
  domains: string[];
  /**
   * Production branch of the project.
   */
  productionBranch: string;
  /**
   * When the project was created.
   */
  createdOn: string;
}

export type Project = Resource<TypeId, ProjectProps, ProjectAttributes, never, Providers>;

/**
 * A Cloudflare Pages project (direct-upload).
 *
 * The project is the container for Pages deployments, custom domains, and
 * per-environment configuration. Created without git `source` integration,
 * it is a direct-upload project — deployments are pushed via the API or
 * `wrangler pages deploy`.
 *
 * The project `name` is its identity (it forms the `<name>.pages.dev`
 * subdomain), so renaming triggers a replacement. `productionBranch`,
 * `buildConfig`, and `deploymentConfigs` are all mutable in place.
 * ### Creating a Project
 * **Example:** Minimal project (generated name)
 * ```typescript
 * const project = yield* Cloudflare.Pages.Project("site", {});
 * // project.subdomain === "<generated-name>.pages.dev"
 * ```
 *
 * **Example:** Named project with a build config
 * ```typescript
 * const project = yield* Cloudflare.Pages.Project("site", {
 *   name: "my-site",
 *   productionBranch: "main",
 *   buildConfig: {
 *     buildCommand: "npm run build",
 *     destinationDir: "dist",
 *   },
 * });
 * ```
 *
 * ### Deployment Configuration
 * **Example:** Environment variables and bindings
 * ```typescript
 * const project = yield* Cloudflare.Pages.Project("site", {
 *   deploymentConfigs: {
 *     production: {
 *       compatibilityDate: "2026-08-31",
 *       envVars: {
 *         API_URL: { value: "https://api.example.com" },
 *         API_KEY: { type: "secret_text", value: apiKey },
 *       },
 *       kvNamespaces: {
 *         CACHE: kvNamespace.namespaceId,
 *       },
 *     },
 *   },
 * });
 * ```
 *
 * ### Custom Domains
 * **Example:** Attach a custom domain
 * ```typescript
 * const domain = yield* Cloudflare.Pages.Domain("site-domain", {
 *   projectName: project.name,
 *   name: "www.example.com",
 * });
 * ```
 *
 * @see https://developers.cloudflare.com/pages/
 *
 * @resource
 * @product Pages
 * @category Workers & Compute
 */
export const Project = Resource<Project>(TypeId);

/**
 * Returns true if the given value is a Project resource.
 */
export const isProject = (value: unknown): value is Project =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const ProjectProvider = () =>
  Provider.succeed(Project, {
    stables: ["projectId", "accountId", "name", "subdomain", "createdOn"],
    diff: Effect.fn(function* ({ id, olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if ((output?.accountId ?? accountId) !== accountId) {
        return { action: "replace" } as const;
      }
      // The name is the project's identity (it forms the *.pages.dev
      // subdomain) — renames are a delete + create.
      const oldName = output?.name ?? (yield* createProjectName(id, olds?.name));
      // Auto-generated names are engine-owned: the deployed name stays
      // authoritative even if the generator would name this id differently
      // today. Only an explicit user-provided name can force a replace.
      const name = news.name ?? oldName;
      if (name !== oldName) {
        return { action: "replace" } as const;
      }
      return undefined;
    }),
    read: Effect.fn(function* ({ id, output, olds }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;
      if (output?.name) {
        const observed = yield* getProject(acct, output.name);
        return observed ? toAttributes(observed, acct) : undefined;
      }
      // Cold read — the project name is deterministic, so look it up
      // directly. Pages projects carry no ownership markers we can
      // inspect, so an existing match is reported as Unowned and takeover
      // is gated behind the adopt policy.
      const name = yield* createProjectName(id, olds?.name);
      const observed = yield* getProject(acct, name);
      return observed ? Unowned(toAttributes(observed, acct)) : undefined;
    }),
    reconcile: Effect.fn(function* ({ id, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const name = news.name ?? output?.name ?? (yield* createProjectName(id));

      // 1. Observe — the project name is its identity; a 404 falls
      //    through to "missing" and we (re)create.
      let observed = yield* getProject(accountId, name);

      // 2. Ensure — create when missing, tolerating the AlreadyExists
      //    race by re-reading.
      if (!observed) {
        observed = yield* pages
          .createProject({
            accountId,
            name,
            productionBranch: news.productionBranch ?? "main",
            buildConfig: toApiBuildConfig(news.buildConfig),
            deploymentConfigs: toApiDeploymentConfigs(news.deploymentConfigs, undefined),
          })
          .pipe(
            Effect.catchTag("ProjectAlreadyExists", (originalError) =>
              Effect.gen(function* () {
                const existing = yield* getProject(accountId, name);
                if (!existing) return yield* originalError;
                return existing;
              }),
            ),
          );
      }

      // 3. Sync — diff observed cloud state against the desired props and
      //    PATCH only the delta. Cloudflare's PATCH deep-merges
      //    `deploymentConfigs`, so removed record keys are sent as
      //    explicit nulls.
      const patch = buildProjectPatch(news, observed);
      if (patch !== undefined) {
        observed = yield* pages.patchProject({
          accountId,
          projectName: name,
          ...patch,
        });
      }

      // 4. Return fresh attributes.
      return toAttributes(observed, accountId);
    }),
    delete: Effect.fn(function* ({ output }) {
      // Deleting a project deletes its deployments and detaches custom
      // domains. A missing project is success — delete is idempotent.
      yield* pages
        .deleteProject({
          accountId: output.accountId,
          projectName: output.name,
        })
        .pipe(Effect.catchTag("ProjectNotFound", () => Effect.void));
    }),
    // Pages projects are account-scoped; enumerate every project in the
    // account, paginating exhaustively, and hydrate each into the same
    // Attributes shape `read` returns.
    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      return yield* pages.listProjects.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((project): ProjectAttributes => ({
              projectId: project.id,
              accountId,
              name: project.name,
              subdomain: project.subdomain ?? `${project.name}.pages.dev`,
              domains: [...(project.domains ?? [])],
              productionBranch: project.productionBranch,
              createdOn: project.createdOn,
            })),
          ),
        ),
      );
    }),
  });

// ---------------------------------------------------------------------------
// Observation
// ---------------------------------------------------------------------------

type ObservedProject =
  | pages.GetProjectResponse
  | pages.CreateProjectResponse
  | pages.PatchProjectResponse;

/**
 * Read a project by name, mapping "gone" (`ProjectNotFound`, Cloudflare
 * error code 8000007) to `undefined`.
 */
const getProject = (accountId: string, projectName: string) =>
  pages
    .getProject({ accountId, projectName })
    .pipe(Effect.catchTag("ProjectNotFound", () => Effect.undefined));

/**
 * Pages project names form the `<name>.pages.dev` subdomain: lowercase
 * alphanumerics and dashes, at most 58 characters.
 */
const createProjectName = (id: string, name?: string) =>
  Effect.gen(function* () {
    return name ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 58 }));
  });

const toAttributes = (project: ObservedProject, accountId: string): ProjectAttributes => ({
  projectId: project.id,
  accountId,
  name: project.name,
  subdomain: project.subdomain ?? `${project.name}.pages.dev`,
  domains: [...(project.domains ?? [])],
  productionBranch: project.productionBranch,
  createdOn: project.createdOn,
});

// ---------------------------------------------------------------------------
// Desired-state mapping
// ---------------------------------------------------------------------------

type ApiBuildConfig = NonNullable<pages.CreateProjectRequest["buildConfig"]>;
type ApiDeploymentConfigs = NonNullable<pages.CreateProjectRequest["deploymentConfigs"]>;
type ApiEnvConfig = NonNullable<ApiDeploymentConfigs["production"]>;
type ObservedEnvConfig = pages.GetProjectResponse["deploymentConfigs"]["production"];

const toApiBuildConfig = (config: BuildConfig | undefined): ApiBuildConfig | undefined =>
  config === undefined
    ? undefined
    : {
        buildCaching: config.buildCaching,
        buildCommand: config.buildCommand,
        destinationDir: config.destinationDir,
        rootDir: config.rootDir,
      };

/**
 * Map the desired deployment config of one environment to the API shape.
 * When `observed` is provided, record-shaped fields include explicit
 * `null`s for observed keys absent from the desired config — Cloudflare's
 * PATCH endpoint deep-merges, so this is how keys are removed.
 */
const toApiEnvConfig = (
  desired: DeploymentConfig,
  observed: ObservedEnvConfig | undefined,
): ApiEnvConfig => ({
  envVars: mergeRecord(
    desired.envVars === undefined
      ? undefined
      : Object.fromEntries(
          Object.entries(desired.envVars).map(([key, envVar]) => [
            key,
            {
              type: envVar.type ?? "plain_text",
              value: envVar.value as string,
            },
          ]),
        ),
    observed?.envVars,
  ),
  kvNamespaces: mergeRecord(
    mapBindingRecord(desired.kvNamespaces, "namespace_id"),
    observed?.kvNamespaces,
  ),
  d1Databases: mergeRecord(mapBindingRecord(desired.d1Databases, "id"), observed?.d1Databases),
  r2Buckets: mergeRecord(mapBindingRecord(desired.r2Buckets, "name"), observed?.r2Buckets),
  compatibilityDate: desired.compatibilityDate,
  compatibilityFlags: desired.compatibilityFlags,
  failOpen: desired.failOpen,
  placement: desired.placement,
});

const mapBindingRecord = (
  record: Record<string, Input<string>> | undefined,
  idKey: string,
): Record<string, unknown> | undefined =>
  record === undefined
    ? undefined
    : Object.fromEntries(
        Object.entries(record).map(([binding, id]) => [binding, { [idKey]: id as string }]),
      );

/**
 * Overlay the desired record on top of the observed one, nulling observed
 * keys that are absent from the desired record so PATCH removes them.
 * `undefined` desired means "unmanaged" — leave the cloud state alone.
 */
const mergeRecord = (
  desired: Record<string, unknown> | undefined,
  observed: Record<string, unknown> | null | undefined,
): Record<string, unknown> | undefined => {
  if (desired === undefined) return undefined;
  const removals = Object.fromEntries(
    Object.keys(observed ?? {})
      .filter((key) => !(key in desired))
      .map((key) => [key, null]),
  );
  return { ...removals, ...desired };
};

const toApiDeploymentConfigs = (
  desired: DeploymentConfigs | undefined,
  observed: pages.GetProjectResponse["deploymentConfigs"] | undefined,
): ApiDeploymentConfigs | undefined => {
  if (desired === undefined) return undefined;
  const configs: ApiDeploymentConfigs = {};
  if (desired.preview !== undefined) {
    configs.preview = toApiEnvConfig(desired.preview, observed?.preview);
  }
  if (desired.production !== undefined) {
    configs.production = toApiEnvConfig(desired.production, observed?.production);
  }
  return configs;
};

// ---------------------------------------------------------------------------
// Drift detection
// ---------------------------------------------------------------------------

type ProjectPatchBody = Pick<
  pages.PatchProjectRequest,
  "productionBranch" | "buildConfig" | "deploymentConfigs"
>;

/**
 * Compute the PATCH body needed to converge the observed project to the
 * desired props, or `undefined` when the project is already converged.
 * Props left `undefined` are unmanaged and never touched.
 */
const buildProjectPatch = (
  news: ProjectProps,
  observed: ObservedProject,
): ProjectPatchBody | undefined => {
  const patch: ProjectPatchBody = {};
  let dirty = false;

  const desiredBranch = news.productionBranch ?? "main";
  if (observed.productionBranch !== desiredBranch) {
    patch.productionBranch = desiredBranch;
    dirty = true;
  }

  if (news.buildConfig !== undefined && buildConfigDirty(news.buildConfig, observed.buildConfig)) {
    patch.buildConfig = toApiBuildConfig(news.buildConfig);
    dirty = true;
  }

  if (news.deploymentConfigs !== undefined) {
    const desired = toApiDeploymentConfigs(
      news.deploymentConfigs,
      observedDeploymentConfigs(observed),
    );
    if (
      desired !== undefined &&
      deploymentConfigsDirty(desired, observedDeploymentConfigs(observed))
    ) {
      patch.deploymentConfigs = desired;
      dirty = true;
    }
  }

  return dirty ? patch : undefined;
};

const observedDeploymentConfigs = (
  observed: ObservedProject,
): pages.GetProjectResponse["deploymentConfigs"] => observed.deploymentConfigs;

const buildConfigDirty = (
  desired: BuildConfig,
  observed: ObservedProject["buildConfig"],
): boolean => {
  const fields: (keyof BuildConfig)[] = [
    "buildCaching",
    "buildCommand",
    "destinationDir",
    "rootDir",
  ];
  return fields.some(
    (field) => desired[field] !== undefined && desired[field] !== (observed?.[field] ?? undefined),
  );
};

const deploymentConfigsDirty = (
  desired: ApiDeploymentConfigs,
  observed: pages.GetProjectResponse["deploymentConfigs"] | undefined,
): boolean =>
  (desired.preview !== undefined && envConfigDirty(desired.preview, observed?.preview)) ||
  (desired.production !== undefined && envConfigDirty(desired.production, observed?.production));

const envConfigDirty = (
  desired: ApiEnvConfig,
  observed: ObservedEnvConfig | undefined,
): boolean => {
  if (
    desired.compatibilityDate !== undefined &&
    desired.compatibilityDate !== observed?.compatibilityDate
  ) {
    return true;
  }
  if (
    desired.compatibilityFlags !== undefined &&
    !arrayEqualsUnordered(desired.compatibilityFlags, observed?.compatibilityFlags ?? [])
  ) {
    return true;
  }
  if (desired.failOpen !== undefined && desired.failOpen !== observed?.failOpen) {
    return true;
  }
  if (desired.placement !== undefined && desired.placement.mode !== observed?.placement?.mode) {
    return true;
  }
  return (
    recordDirty(desired.envVars, observed?.envVars, envVarEquals) ||
    recordDirty(desired.kvNamespaces, observed?.kvNamespaces, deepEquals) ||
    recordDirty(desired.d1Databases, observed?.d1Databases, deepEquals) ||
    recordDirty(desired.r2Buckets, observed?.r2Buckets, deepEquals)
  );
};

/**
 * A merged desired record (which already contains `null` removal markers)
 * is dirty when any non-null entry differs from the observed value or any
 * null marker still has an observed value to remove.
 */
const recordDirty = (
  desired: Record<string, unknown> | undefined,
  observed: Record<string, unknown> | null | undefined,
  equals: (a: unknown, b: unknown) => boolean,
): boolean => {
  if (desired === undefined) return false;
  return Object.entries(desired).some(([key, value]) =>
    value === null
      ? observed?.[key] !== undefined && observed[key] !== null
      : !equals(value, observed?.[key]),
  );
};

/**
 * Secrets read back as `{ type: "secret_text" }` without a value, so a
 * desired secret with a value can never be proven converged — treat
 * matching-type secrets as equal and rely on PATCH idempotency.
 */
const envVarEquals = (desired: unknown, observed: unknown): boolean => {
  const d = desired as { type?: string; value?: string };
  const o = observed as { type?: string; value?: string } | undefined;
  if (o === undefined) return false;
  if (d.type === "secret_text") return o.type === "secret_text";
  return (o.type ?? "plain_text") === (d.type ?? "plain_text") && o.value === d.value;
};

const deepEquals = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);