sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ foldkit/ Foldkit.ts

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 * as Schema from "effect/Schema";
import type { Plugin } from "vite";
import * as Core from "../core/index.ts";
import type { NodeServeHtmlHandling, NodeServeNotFoundHandling } from "../core/NodeServe.ts";
import { make as makeVite, type ViteBuildConfig } from "../vite/Vite.ts";

/** The completed-build contract exposed by @foldkit/vite-plugin >= 0.25.0. */
export const BuildMetadata = Schema.Struct({
  root: Schema.String,
  clientDirectory: Schema.String,
  serverDirectory: Schema.String,
  serverEntry: Schema.String,
  manifest: Schema.Struct({
    schemaVersion: Schema.Literals([1]),
    client: Schema.String,
    server: Schema.String,
    serverEntry: Schema.String,
    prerendered: Schema.Array(Schema.String),
  }),
});
export type BuildMetadata = typeof BuildMetadata.Type;

export interface FoldkitTargetConfig {
  /** Serializable overrides for the project's Vite configuration. */
  readonly vite?: ViteBuildConfig | undefined;
  /** AWS topology: browser-only, prerendered assets, or a server with assets. Omit for automatic detection. */
  readonly output?: "spa" | "static" | "server" | undefined;
  /** Override the default SPA fallback for browser-only builds. */
  readonly notFoundHandling?: NodeServeNotFoundHandling | undefined;
  /** Override static HTML routing. */
  readonly htmlHandling?: NodeServeHtmlHandling | undefined;
}
export interface FoldkitTarget extends Core.DeployTarget<FoldkitTargetConfig> {}
export type FoldkitTargetInput = Core.DeployTargetInput<FoldkitTarget, FoldkitTargetConfig>;
export interface FoldkitOptions extends FoldkitTargetConfig {
  /** Project directory. @default process.cwd() */
  readonly root?: string | undefined;
  /** Deployment target. @default "@alchemy.run/frontend-frameworks/foldkit/aws" */
  readonly target?: FoldkitTargetInput | undefined;
  /** Native Vite development server options. */
  readonly dev?: { readonly port?: number | undefined } | undefined;
}
export const DEFAULT_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/foldkit/aws";

interface ViteBuilder {
  readonly config: {
    readonly root: string;
    readonly base: string;
    readonly plugins: ReadonlyArray<Pick<Plugin, "name" | "api">>;
    readonly build: { readonly outDir: string };
  };
  readonly environments: Record<
    string,
    {
      readonly config: {
        readonly root: string;
        readonly base: string;
        readonly build: { readonly outDir: string };
      };
    }
  >;
  readonly buildApp: () => Promise<unknown>;
  readonly build: (environment: unknown) => Promise<unknown>;
}
interface ViteModule {
  readonly createBuilder: (config: Record<string, unknown>) => Promise<ViteBuilder>;
}
const fail = (message: string, cause?: unknown) =>
  new Core.FrameworkError({ framework: "foldkit", message, cause });

/** Capture the plugin API before building, but only read it after buildApp succeeds. */
export const metadataReader = (plugins: ViteBuilder["config"]["plugins"]) => {
  const plugin = plugins.find((plugin) => plugin.name === "foldkit:build");
  if (!plugin) return undefined;
  if (typeof plugin.api?.getBuildMetadata !== "function") {
    throw fail("Foldkit SSR requires @foldkit/vite-plugin >= 0.25.0 with getBuildMetadata().");
  }
  // oxlint-disable-next-line effecttsgo/schema-sync -- read inside Vite's build callback; a throw is caught by its tryPromise
  return () => Schema.decodeUnknownSync(BuildMetadata)(plugin.api.getBuildMetadata());
};

/** Package only deployment artifacts, including independently configured client/server directories. */
export const readFoldkitOutput = (
  root: string,
  clientDirectory: string,
  metadata?: BuildMetadata,
  output?: FoldkitTargetConfig["output"],
) =>
  Effect.gen(function* () {
    const fs = yield* FileSystem.FileSystem;
    const path = yield* Path.Path;
    if (output === "spa" && metadata) {
      return yield* fail(
        'Foldkit produced a server build. Set output: "server" for SSR/hybrid or output: "static" for prerendered assets.',
      );
    }
    if (output === "server" && !metadata) {
      return yield* fail(
        'Foldkit produced no server handler. Enable ssr.build in vite.config.ts or omit output: "server".',
      );
    }
    if (output === "static" && metadata && metadata.manifest.prerendered.length === 0) {
      return yield* fail(
        'Static Foldkit output requires prerendered pages. Configure ssr.build.prerender or use output: "server".',
      );
    }
    // Packaging lives outside `.alchemy`, which Neon's packager refuses to
    // ship from, and like it is gitignored and excluded from build memos.
    const distDirectory = path.join(root, "node_modules", ".cache", "alchemy", "foldkit");
    const isWithin = (parent: string, child: string) => {
      const relative = path.relative(parent, child);
      return (
        relative === "" ||
        (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))
      );
    };
    for (const directory of [clientDirectory, ...(metadata ? [metadata.serverDirectory] : [])]) {
      if (isWithin(distDirectory, directory) || isWithin(directory, distDirectory)) {
        return yield* fail(
          "Foldkit output directories must not overlap node_modules/.cache/alchemy/foldkit, which is reserved for deployment packaging.",
        );
      }
    }
    if (
      metadata &&
      (!isWithin(metadata.serverDirectory, metadata.serverEntry) ||
        metadata.serverEntry === metadata.serverDirectory)
    ) {
      return yield* fail("Foldkit's server entry must be inside its server output directory.");
    }
    yield* fs.remove(distDirectory, { recursive: true, force: true });
    yield* fs.makeDirectory(distDirectory, { recursive: true });
    const client = path.join(distDirectory, "client");
    yield* fs.copy(clientDirectory, client);
    if (!metadata || output === "static") {
      return {
        output: {
          distDirectory,
          clientDirectory: client,
          serverModules: undefined,
          externalWorkspaces: new Set<string>(),
        } satisfies Core.BuildOutput,
        entry: undefined,
      };
    }
    const server = path.join(distDirectory, "server");
    yield* fs.copy(metadata.serverDirectory, server);
    const entryName = path
      .relative(metadata.serverDirectory, metadata.serverEntry)
      .replaceAll("\\", "/");
    const modules = yield* Core.readServerModulesFromDisk({
      directory: server,
      prefix: "server",
    });
    if (!modules.some((module) => module.name === `server/${entryName}`)) {
      return yield* fail("Foldkit's generated server entry is missing from the build output.");
    }
    return {
      output: {
        distDirectory,
        clientDirectory: client,
        serverModules: Core.sortServerModules(modules, `server/${entryName}`),
        externalWorkspaces: new Set<string>(),
      } satisfies Core.BuildOutput,
      entry: path.join(server, entryName),
    };
  }).pipe(
    Effect.mapError((cause) =>
      cause instanceof Core.FrameworkError
        ? cause
        : fail("Failed to collect Foldkit build output", cause),
    ),
  );

/** Build with the project's plugin and host its native development server. */
export const make: (
  options?: FoldkitOptions,
) => Effect.Effect<Core.Framework["Service"], never, FileSystem.FileSystem | Path.Path> =
  Effect.fnUntraced(function* (options: FoldkitOptions = {}) {
    const fs = yield* FileSystem.FileSystem;
    const path = yield* Path.Path;
    const baseRoot = options.root ?? process.cwd();
    const config: FoldkitTargetConfig = {
      vite: options.vite,
      output: options.output,
      notFoundHandling: options.notFoundHandling,
      htmlHandling: options.htmlHandling,
    };
    const native = yield* makeVite({
      root: baseRoot,
      vite: options.vite,
      dev: options.dev,
    });
    const provide = <A, E>(effect: Effect.Effect<A, E, FileSystem.FileSystem | Path.Path>) =>
      effect.pipe(
        Effect.provideService(FileSystem.FileSystem, fs),
        Effect.provideService(Path.Path, path),
      );
    const build: Core.Framework["Service"]["build"] = Effect.fn(function* (buildOptions) {
      const root = path.resolve(buildOptions?.root ?? baseRoot);
      const target = yield* Core.resolveDeployTarget<FoldkitTarget, FoldkitTargetConfig>(
        root,
        options.target ?? DEFAULT_TARGET_SPECIFIER,
        config,
      ).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
      const context = { root, framework: "foldkit", env: buildOptions?.env };
      if (target.build)
        return yield* provide(target.build(context)).pipe(
          Effect.mapError((error) => fail(error.message, error.cause)),
        );
      const vite = yield* Core.loadProjectModule<ViteModule>(root, "vite").pipe(
        Effect.mapError((error) => fail(error.message, error.cause)),
      );
      const built = yield* Effect.tryPromise({
        try: async () => {
          const outDir = options.vite?.outDir;
          const outputPlugin: Plugin = {
            name: "alchemy:foldkit-output",
            enforce: "post",
            config: (config) =>
              config.environments?.ssr?.build?.ssr
                ? {
                    // Like TanStack Start, deploy a self-contained Node bundle.
                    ssr: { noExternal: true },
                    environments: {
                      ...(outDir !== undefined
                        ? {
                            client: {
                              build: { outDir: path.join(outDir, "client") },
                            },
                          }
                        : {}),
                      ssr: {
                        resolve: { noExternal: true },
                        ...(outDir !== undefined
                          ? { build: { outDir: path.join(outDir, "server") } }
                          : {}),
                      },
                    },
                  }
                : undefined,
          };
          const builder = await vite.createBuilder({
            root,
            logLevel: "warn",
            ...(options.vite?.configFile !== undefined
              ? { configFile: path.resolve(root, options.vite.configFile) }
              : {}),
            ...(options.vite?.base !== undefined ? { base: options.vite.base } : {}),
            ...(outDir !== undefined ? { build: { outDir } } : {}),
            plugins: [outputPlugin],
          });
          const read = metadataReader(builder.config.plugins);
          // Without Foldkit's SSR build plugin the app is client-only; the
          // default `buildApp` would also build the `ssr` environment, whose
          // only input is `index.html`.
          if (read) await builder.buildApp();
          else await builder.build(builder.environments.client);
          const metadata = read?.();
          const client = builder.environments.client?.config ?? builder.config;
          return {
            metadata,
            assetBasePath: decodeURIComponent(new URL(client.base, "http://localhost").pathname),
            client: metadata?.clientDirectory ?? path.resolve(client.root, client.build.outDir),
          };
        },
        catch: (cause) => fail("Failed to build Foldkit", cause),
      });
      const collected = yield* provide(
        readFoldkitOutput(root, built.client, built.metadata, options.output),
      );
      return yield* provide(
        Core.applyDeployTargetFinish(target, collected.output, {
          ...context,
          entry: collected.entry,
          assetBasePath: built.assetBasePath,
        }),
      ).pipe(Effect.mapError((error) => fail(error.message, error.cause)));
    });
    return Core.Framework.of({ build, dev: native.dev });
  });

export const layer = (
  options?: FoldkitOptions,
): Layer.Layer<Core.Framework, never, FileSystem.FileSystem | Path.Path> =>
  Layer.effect(Core.Framework, make(options));