sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ astro/ Astro.ts

import type { AstroInlineConfig, AstroIntegration } from "astro";
import type * as AstroNamespace from "astro";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Path from "effect/Path";
import type * as ViteModule from "vite";
import * as FrameworkCore from "../core/index.ts";
import { NODE_ENVIRONMENTS } from "./environments.ts";
import {
  DEFAULT_TARGET_SPECIFIER,
  isAstroTarget,
  type AstroTarget,
  type AstroTargetInput,
} from "./Target.ts";

type AstroModule = typeof AstroNamespace;

/**
 * Options for the Astro `Framework` integration. The deploy target is passed
 * as a value (`target`), keeping this module platform-neutral: all
 * platform-specific behavior (adapter/integration selection, bundler plugin
 * injection, dev SSR execution) lives in the target module.
 */
export interface AstroFrameworkOptions<TargetConfig = unknown> {
  /**
   * The deploy target: an `AstroTarget` value, a `(config) => AstroTarget`
   * factory, or a module specifier resolved from the project's own
   * `node_modules`. Defaults to this package's Cloudflare target module
   * (`"@alchemy.run/frontend-frameworks/astro/cloudflare"`). Factories and specifiers are
   * applied to {@link targetConfig}.
   */
  readonly target?: AstroTargetInput<TargetConfig> | undefined;
  /**
   * Target configuration passed to a target factory or specifier-loaded
   * target module. Opaque to this module — its shape belongs to the target
   * (Cloudflare: `{ worker?: CloudflareVitePluginOptions,
   * sessionKVBindingName?: string }`). Unused when {@link target} is already
   * a target *value*.
   */
  readonly targetConfig?: TargetConfig | undefined;
  /**
   * Extra Astro config merged into the in-memory `AstroInlineConfig`
   * (`site`, `base`, `integrations`, `devToolbar`, `vite`, ...). The
   * project's own `astro.config.*` file loads natively; this inline config
   * is merged OVER it by astro (arrays like `integrations`/`vite.plugins`
   * concatenate, scalars override). `root` is pinned; `output` is only set
   * when passed here (so a config file's `output` — or astro's `"static"`
   * default — is honored). Do not pass `adapter` — the deploy target
   * provides it, and a user-declared adapter fails the build with an
   * actionable error.
   */
  readonly astro?: AstroInlineConfig | undefined;
  /**
   * Path to an alternate Astro config file, resolved against {@link root}
   * when relative (astro itself resolves a relative `configFile` against
   * the process cwd, so this module anchors it to the project root before
   * handing it over). Defaults to astro's own config discovery
   * (`astro.config.*` in the project root).
   */
  readonly config?: string | undefined;
  /** Project root. Defaults to the process working directory. */
  readonly root?: string | undefined;
}

/** Inputs for {@link makeAstroInlineConfig} (exported for testing). */
export interface AstroConfigInputs {
  /** Absolute project root. */
  readonly root: string;
  /**
   * The deploy target's integration. Injected via `integrations` (after the
   * user's) rather than `adapter`: it registers itself as the adapter at
   * `astro:config:done`, where it also rejects a user-declared adapter with
   * an actionable error.
   */
  readonly integration: AstroIntegration;
  /** User Astro config merged in (its `vite.plugins` are preserved). */
  readonly userConfig?: AstroInlineConfig | undefined;
  /** Dev-server port (merged into `server.port`). */
  readonly port?: number | undefined;
  /** Dev-server host (merged into `server.host`). */
  readonly host?: string | undefined;
  /**
   * Extra Vite plugins appended after the user's (e.g. the build-output
   * collector).
   */
  readonly extraVitePlugins?: ReadonlyArray<ViteModule.Plugin> | undefined;
}

/**
 * Build the in-memory `AstroInlineConfig` — the overlay astro merges OVER
 * the project's own `astro.config.*` (which loads natively; `configFile`
 * is left undiscovered-default unless the user overlay carries one, so a
 * project without a config file falls back to a purely programmatic
 * config). Astro's `resolveConfig` merge
 * gives this inline config precedence: arrays (`integrations`,
 * `vite.plugins`) concatenate after the file's, scalars override.
 *
 * - The deploy target's integration is appended to `integrations` (it
 *   registers itself as the adapter at `astro:config:done` and fails the
 *   build if the user config already declares an `adapter`).
 * - `output` is NOT set unless the caller passes it explicitly: the inline
 *   config merges OVER the project's `astro.config.*`, so a default here
 *   would clobber the file's `output` (e.g. an explicit `"static"`). With
 *   neither source setting it, astro's own default (`"static"`, with
 *   per-route `prerender = false` opt-outs enabled by the adapter) applies.
 * - User `vite.plugins` are preserved ahead of the collector.
 */
export const makeAstroInlineConfig = (inputs: AstroConfigInputs): AstroInlineConfig => {
  const user = inputs.userConfig;
  const serverOverrides = {
    ...(inputs.port !== undefined ? { port: inputs.port } : {}),
    ...(inputs.host !== undefined ? { host: inputs.host } : {}),
  };
  const server: AstroInlineConfig["server"] =
    Object.keys(serverOverrides).length === 0
      ? user?.server
      : typeof user?.server === "function"
        ? (options) => ({
            ...(user.server as (options: unknown) => object)(options),
            ...serverOverrides,
          })
        : { ...user?.server, ...serverOverrides };
  return {
    logLevel: "warn",
    ...user,
    root: inputs.root,
    integrations: [...(user?.integrations ?? []), inputs.integration],
    server,
    vite: {
      ...user?.vite,
      plugins: [...(user?.vite?.plugins ?? []), ...(inputs.extraVitePlugins ?? [])],
    },
  };
};

/**
 * The Astro implementation of framework-core's `Framework` service.
 *
 * - `build` resolves the deploy target, then either delegates wholesale to
 *   `target.build` (when the target defines one) or runs astro's programmatic
 *   `build(AstroInlineConfig)` with the target's adapter integration and the
 *   shared build-output collector on the `ssr` environment (skipping astro's
 *   node-side `astro`/`prerender` environments), finishing with
 *   `applyDeployTargetFinish`. `serverModules[0]` is the ssr entry chunk
 *   (`server/entry.mjs`); `clientDirectory` is `dist/client`, captured as a
 *   path so prerendered HTML written after the Vite build rides along.
 * - `dev` runs astro's `dev()` with the target's adapter integration; with
 *   the Cloudflare target the `ssr` environment executes inside workerd via
 *   the cloudflare-vite-plugin module runner, with in-memory bindings — no
 *   wrangler config anywhere. Closing the Scope stops the server.
 *
 * Returns the service implementation as an Effect (the alchemy-side
 * `FrameworkModule` contract); use {@link layer} for the `Layer` form the
 * e2e harness consumes.
 */
export const make = <TargetConfig = unknown>(
  options?: AstroFrameworkOptions<TargetConfig>,
): Effect.Effect<FrameworkCore.Framework["Service"], never, FileSystem.FileSystem | Path.Path> =>
  Effect.gen(function* () {
    const fs = yield* FileSystem.FileSystem;
    const path = yield* Path.Path;

    const fail = (message: string) => (cause: unknown) =>
      new FrameworkCore.FrameworkError({
        framework: "astro",
        message,
        cause,
      });

    const failTarget = (error: FrameworkCore.DeployTargetError) =>
      new FrameworkCore.FrameworkError({
        framework: "astro",
        message: error.message,
        cause: error.cause ?? error,
      });

    // Astro's dev()/build() record telemetry events by default.
    yield* Effect.sync(() => {
      process.env.ASTRO_TELEMETRY_DISABLED ??= "1";
    });

    const resolveRoot = (override: string | undefined) =>
      Effect.sync(() => path.resolve(override ?? options?.root ?? process.cwd()));

    /**
     * The user's inline Astro overlay with `config` resolved into
     * `configFile`, anchored to the project root (astro resolves a
     * relative `configFile` against the process cwd, not `root`).
     */
    const resolveUserAstro = (root: string): AstroInlineConfig | undefined =>
      options?.config === undefined
        ? options?.astro
        : { ...options?.astro, configFile: path.resolve(root, options.config) };

    const resolveTarget = (
      root: string,
    ): Effect.Effect<AstroTarget, FrameworkCore.FrameworkError> =>
      FrameworkCore.resolveDeployTarget<AstroTarget, TargetConfig | undefined>(
        root,
        (options?.target ?? DEFAULT_TARGET_SPECIFIER) as FrameworkCore.DeployTargetInput<
          AstroTarget,
          TargetConfig | undefined
        >,
        options?.targetConfig,
      ).pipe(
        Effect.mapError(failTarget),
        Effect.flatMap((target) =>
          isAstroTarget(target)
            ? Effect.succeed(target)
            : Effect.fail(
                fail(
                  "The resolved deploy target is not an AstroTarget: it must provide an " +
                    "`integration: () => AstroIntegration` hook",
                )(undefined),
              ),
        ),
      );

    const loadAstro = (root: string): Effect.Effect<AstroModule, FrameworkCore.FrameworkError> =>
      FrameworkCore.loadProjectModule<AstroModule>(root, "astro").pipe(
        Effect.mapError(fail("Failed to load the project's astro")),
      );

    const makeConfig = (
      root: string,
      target: AstroTarget,
      overrides?: Pick<AstroConfigInputs, "port" | "host" | "extraVitePlugins">,
    ): AstroInlineConfig =>
      makeAstroInlineConfig({
        root,
        integration: target.integration(),
        userConfig: resolveUserAstro(root),
        ...overrides,
      });

    return FrameworkCore.Framework.of({
      build: Effect.fn(function* (buildOptions) {
        const root = yield* resolveRoot(buildOptions?.root);
        const target = yield* resolveTarget(root);
        if (target.build !== undefined) {
          // Wholesale build takeover: the target owns the entire
          // production build (the OpenNext-style case). The inline Astro
          // overlay rides along (with `config` already resolved into an
          // absolute `configFile`) so a child-process build can
          // reconstruct the framework with the same options.
          return yield* target
            .build({
              root,
              framework: "astro",
              env: buildOptions?.env,
              astro: resolveUserAstro(root),
            })
            .pipe(
              Effect.provideService(FileSystem.FileSystem, fs),
              Effect.provideService(Path.Path, path),
              Effect.mapError(failTarget),
            );
        }
        const astro = yield* loadAstro(root);
        const collector = yield* FrameworkCore.makeBuildOutputCollector({
          entryEnvironment: "ssr",
          skipEnvironments: NODE_ENVIRONMENTS,
          selectEntry: target.selectServerEntry,
        }).pipe(Effect.provideService(FileSystem.FileSystem, fs));
        const config = makeConfig(root, target, {
          extraVitePlugins: [collector.plugin],
        });
        yield* Effect.tryPromise({
          try: async () => await astro.build(config),
          catch: fail("Failed to build"),
        });
        // Disk re-read: astro injects the serialized SSR manifest into the
        // entry chunk on disk *after* the bundler finishes (the in-memory
        // capture still contains the `@@ASTRO_MANIFEST_REPLACE@@`
        // placeholder), and prunes the prerender-only chunks.
        const output = yield* collector
          .collect({ fromDisk: true })
          .pipe(Effect.mapError((error) => fail(error.message)(error.cause)));
        // The astro build is delivered in-memory (no on-disk entry handed
        // over), so the finish context carries no `entry`.
        return yield* FrameworkCore.applyDeployTargetFinish(target, output, {
          root,
          framework: "astro",
        }).pipe(
          Effect.provideService(FileSystem.FileSystem, fs),
          Effect.provideService(Path.Path, path),
          Effect.mapError(failTarget),
        );
      }),
      dev: Effect.fn(function* (devOptions) {
        const root = yield* resolveRoot(devOptions?.root);
        const target = yield* resolveTarget(root);
        const astro = yield* loadAstro(root);
        // `port: 0` (true OS-assigned) when the Vite under Astro is
        // >= 8.2.1, probed ephemeral port otherwise — see
        // `resolveViteDevPort`. Astro's dev server runs on Astro's own
        // Vite dependency, so the version is resolved from the astro
        // package's directory, not the project root.
        const viteVersion = yield* FrameworkCore.resolveProjectPackageDirectory(root, "astro").pipe(
          Effect.flatMap((astroDirectory) =>
            FrameworkCore.resolveInstalledPackageVersion(astroDirectory, "vite"),
          ),
          Effect.orElseSucceed(() => undefined),
        );
        const port = yield* FrameworkCore.resolveViteDevPort(viteVersion, devOptions?.port);
        const config = makeConfig(root, target, {
          port,
          host: devOptions?.host,
        });
        const server = yield* Effect.acquireRelease(
          Effect.tryPromise({
            try: async () => await astro.dev(config),
            catch: fail("Failed to start the astro dev server"),
          }),
          (server) => Effect.promise(async () => await server.stop()),
        );
        const url =
          server.resolvedUrls?.local[0] ??
          (typeof server.address.port === "number"
            ? `http://localhost:${server.address.port}/`
            : undefined);
        if (url === undefined) {
          return yield* fail("Could not determine the URL of the astro dev server")(undefined);
        }
        return { url };
      }),
    });
  });

/**
 * The `Layer` form of {@link make} — the shape the e2e harness's framework
 * factory contract expects (`(options) => Layer<Framework>`).
 */
export const layer = <TargetConfig = unknown>(
  options?: AstroFrameworkOptions<TargetConfig>,
): Layer.Layer<FrameworkCore.Framework, never, FileSystem.FileSystem | Path.Path> =>
  Layer.effect(FrameworkCore.Framework, make(options));