sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare-test-tools/ src/ e2e/ Options.ts

import type { CloudflareVitePluginOptions } from "@alchemy.run/cloudflare-runtime/vite";
import type { Framework } from "@alchemy.run/frontend-frameworks/core";
import * as Effect from "effect/Effect";
import type * as FileSystem from "effect/FileSystem";
import type * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import * as Predicate from "effect/Predicate";
import type * as Miniflare from "../miniflare/miniflare.ts";
import { Cwd } from "./Cwd.ts";

const kOptions = Symbol("@alchemy.run/cloudflare-test-tools/e2e/Options");

/**
 * Cloudflare-target configuration — everything the cloudflare deploy target
 * needs to build, dev-serve, and preview a fixture.
 */
export interface CloudflareTargetOptions {
  /**
   * Cloudflare worker configuration (compatibility date/flags, worker name,
   * bindings, assets) consumed by the built-in Vite implementation of the
   * `Framework` service — and, by convention, by framework packages named via
   * {@link Options.framework} (they read the same shape for their cloudflare
   * plugin options). Optional so assets-only fixtures can omit it.
   */
  readonly worker?: CloudflareVitePluginOptions;
  /**
   * Miniflare options for the preview server (`e2e preview` / the Playwright
   * `live` mode) — the cloudflare target's serving story for built output.
   */
  readonly preview?: Options.MiniflareOptions;
}

/**
 * Target selection + target-scoped config carriage: one optional key per
 * platform, opaque to everything except that platform's target. Cloudflare is
 * the only implemented target today; a future AWS target adds its own key
 * (e.g. `aws?: AwsTargetOptions`) without touching the framework plumbing.
 */
export interface TargetOptions {
  /**
   * Which platform target drives this fixture.
   * @default "cloudflare"
   */
  readonly name?: "cloudflare";
  readonly cloudflare?: CloudflareTargetOptions;
}

export interface Options {
  /**
   * The framework's project root, relative to the fixture root (the harness
   * cwd). Threaded by the harness into `Framework.build`/`Framework.dev`
   * (`FrameworkBuildOptions.root` / `FrameworkDevOptions.root`) so a fixture
   * whose app lives in a subdirectory (e.g. a monorepo-shaped fixture with the
   * Vite project at `app/`) needs no framework-Layer wrapping. The harness's
   * own persistence (`dist/build.json`) stays anchored at the fixture root.
   * @default the fixture root
   */
  readonly root?: string;
  /**
   * Deploy-target selection and target-scoped configuration. Defaults to the
   * cloudflare target. Frameworks and the harness read the resolved shape via
   * {@link resolveCloudflareOptions}, which also honors the deprecated
   * top-level `vite`/`miniflare` aliases.
   */
  readonly target?: TargetOptions;
  /**
   * @deprecated Alias for `target.cloudflare.worker` — kept so existing
   * `e2e.config.ts` files work unchanged. Prefer the target-scoped form.
   */
  readonly vite?: CloudflareVitePluginOptions;
  /**
   * @deprecated Alias for `target.cloudflare.preview` — kept so existing
   * `e2e.config.ts` files work unchanged. Prefer the target-scoped form.
   */
  readonly miniflare?: Options.MiniflareOptions;
  /**
   * The framework integration implementing `dev`/`build` for this fixture.
   *
   * - omitted — the built-in Vite implementation (default; zero behavior
   *   change for existing fixtures)
   * - a package specifier (e.g. `"@alchemy.run/frontend-frameworks/waku"`) — loaded from the
   *   *fixture's* own `node_modules`; the module must default-export (or
   *   named-export `framework`) a factory `(options: Options) =>
   *   Layer<Framework>` (a `Layer<Framework>` export is also accepted)
   * - a factory function — called with these options
   * - a `Layer<Framework>` — used as-is (build it yourself in `e2e.config.ts`
   *   by importing the framework package directly, for full type safety over
   *   framework-specific options)
   */
  readonly framework?: Options.FrameworkInput;
}

/**
 * The resolved cloudflare-target configuration: the target-scoped form merged
 * with the deprecated top-level aliases (target-scoped wins). This is the
 * single accessor the harness — and, by convention, framework packages that
 * read the harness options structurally — use to obtain cloudflare config;
 * nothing else should touch `options.vite` / `options.miniflare` directly.
 */
export const resolveCloudflareOptions = (
  options: Options,
): {
  worker: CloudflareVitePluginOptions | undefined;
  preview: Options.MiniflareOptions;
} => ({
  worker: options.target?.cloudflare?.worker ?? options.vite,
  preview: options.target?.cloudflare?.preview ?? options.miniflare ?? {},
});

/**
 * Resolve {@link Options.root} to an absolute project root (against the
 * harness cwd), or `undefined` when the fixture root is the project root —
 * the value the harness passes to `Framework.build`/`Framework.dev` as
 * `FrameworkBuildOptions.root` / `FrameworkDevOptions.root`.
 */
export const resolveRoot: (
  options: Options,
) => Effect.Effect<string | undefined, never, Path.Path> = Effect.fn(function* (options: Options) {
  if (options.root === undefined) {
    return undefined;
  }
  const path = yield* Path.Path;
  const cwd = yield* Cwd;
  return path.resolve(cwd, options.root);
});

export declare namespace Options {
  type Input = Options | Effect.Effect<Options>;
  type MiniflareOptions = {
    // `NonNullable` before `Omit`: newer miniflare versions surface the
    // optional `assets` slot as `{...} | undefined`, and `Omit` over a
    // union with `undefined` collapses to `{}`.
    [K in keyof Miniflare.Options]?: K extends "assets"
      ? Omit<NonNullable<Miniflare.Options[K]>, "directory">
      : Miniflare.Options[K];
  };

  /**
   * Services the harness runtime provides to a framework Layer while it is
   * being built (the package's Node platform services, plus a dotenv/env
   * `ConfigProvider`).
   */
  type FrameworkServices = FileSystem.FileSystem | Path.Path;

  /**
   * What a framework integration ultimately provides: a Layer for
   * framework-core's `Framework` service.
   */
  type FrameworkLayer = Layer.Layer<Framework, unknown, FrameworkServices>;

  /**
   * A factory producing the {@link FrameworkLayer} from the fixture's
   * options. May return the Layer directly or an Effect of it.
   */
  type FrameworkFactory = (
    options: Options,
  ) => FrameworkLayer | Effect.Effect<FrameworkLayer, unknown, FrameworkServices>;

  type FrameworkInput = string | FrameworkLayer | FrameworkFactory;
}

export const make = (options: Options.Input) => Object.assign(options, { [kOptions]: true });

export const load = Effect.fn(function* () {
  const path = yield* Path.Path;
  const cwd = yield* Cwd;
  const url = yield* path
    .toFileUrl(path.resolve(cwd, "e2e.config.ts"))
    .pipe(Effect.map((url) => url.href));
  const options = yield* Effect.promise(
    async () => await import(url).then((m) => m.default as Options.Input),
  );
  if (Effect.isEffect(options)) {
    return yield* options;
  }
  if (!Predicate.hasProperty(options, kOptions)) {
    throw new Error("No e2e.config.ts found");
  }
  return options;
});