sailfork / t3code-github / .repos/ alchemy-effect/ packages/ frontend-frameworks/ src/ nuxt/ source.ts

import * as NodeCrypto from "node:crypto";
import * as NodePath from "node:path";
import { fileURLToPath } from "node:url";
/**
 * `@alchemy.run/frontend-frameworks/nuxt/source` — alchemy Worker source provider for Nuxt
 * projects.
 *
 * The default export satisfies alchemy's `WorkerSourceModule` contract
 * (`packages/cloudflare/src/Workers/Source.ts`) **structurally**:
 * the `Source*` shapes below mirror alchemy's `SourceProvider` /
 * `SourceContext` / `SourceBuildOutput` interfaces rather than importing
 * them, so this package carries no dependency on alchemy. Version skew
 * degrades to a load-time `SourceProviderError` on the alchemy side.
 *
 * Semantics mirror alchemy's built-in vite source
 * (`Workers/Sources/Vite.ts`):
 *
 * - `build()` runs the Nuxt Framework service (the project's `@nuxt/kit`
 *   driven programmatically with nitro's `cloudflare_module` preset,
 *   wrangler-free) and maps its `BuildOutput` onto the source contract:
 *   `serverModules` (entry first) → bundle files, `clientDirectory`
 *   (`.output/public`) → assets (manifest-hashed, honoring `.assetsignore` /
 *   `_headers` / `_redirects`), project-tree hash → the `input` hash slot.
 * - `hash()` recomputes the `input` hash **without building** — a memo hash
 *   over the project tree (gitignore-aware by default, narrowable via
 *   `memo.include`/`memo.exclude`), the discovered external workspaces, the
 *   lockfile, this package's version, and the build-affecting options.
 * - `dev()` starts Nuxt's own dev server (nitro dev, SSR in a Node worker
 *   THREAD, full HMR) with the Worker's bindings served on
 *   `event.context.cloudflare` through cloudflare-runtime's platform proxy
 *   (wrangler-free), and returns the server-mode dev handle. Literal env
 *   values are laid over the proxied bindings; resource bindings round-trip
 *   to the proxy's workerd instance, so dev state is live and shared.
 */
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import type * as Path from "effect/Path";
import type { PlatformError } from "effect/PlatformError";
import * as Redacted from "effect/Redacted";
import type * as Scope from "effect/Scope";
import { glob } from "tinyglobby";
import { resolveBuildEnv, runBuildChild } from "../core/BuildChild.ts";
import { makeCloudflareTarget } from "./cloudflare.ts";
import { make as makeNuxt, type NuxtOptions } from "./Nuxt.ts";

const PROVIDER = "@alchemy.run/frontend-frameworks/nuxt/source";

// ─────────────────────────────────────────────────────────────────────
// Structural mirror of alchemy's Worker source contract
// (packages/cloudflare/src/Workers/Source.ts). Do not import
// alchemy here — the contract is structural by design.
// ─────────────────────────────────────────────────────────────────────

/** Mirror of alchemy's `SourceHash`. */
export interface SourceHash {
  readonly bundle: string | undefined;
  readonly assets: string | undefined;
  readonly input: string | undefined;
  readonly additionalWorkspaces: Array<string> | undefined;
}

/** Mirror of alchemy's `Bundle.BundleFile` / `Bundle.BundleOutput`. */
export interface SourceBundleFile {
  readonly path: string;
  readonly content: string | Uint8Array;
  readonly hash: string;
}

export interface SourceBundleOutput {
  readonly files: [SourceBundleFile, ...Array<SourceBundleFile>];
  readonly hash: string;
}

/** Mirror of alchemy's `AssetReadResult` (`Workers/Assets.ts`). */
export interface SourceAssetReadResult {
  directory: string;
  config: Record<string, unknown> | undefined;
  manifest: Record<string, { hash: string; size: number }>;
  _headers: string | undefined;
  _redirects: string | undefined;
  hash: string;
}

/** Mirror of alchemy's `SourceBuildOutput`. */
export interface SourceBuildOutput {
  readonly bundle: SourceBundleOutput | undefined;
  readonly assets: SourceAssetReadResult | undefined;
  readonly hash: SourceHash;
}

/** Mirror of alchemy's `SourceContext` (the subset this source reads). */
export interface SourceContext {
  readonly id: string;
  readonly workerName: string;
  readonly compatibility: {
    readonly date: string;
    readonly flags: Array<string>;
  };
  readonly stack: { readonly name: string; readonly stage: string };
  readonly env: Record<string, unknown> | undefined;
  readonly assets: Record<string, unknown> | string | undefined;
}

/** Mirror of alchemy's `DevContext` (the subset this source reads). */
export interface SourceDevContext extends SourceContext {
  /**
   * Runtime wiring derived by alchemy's LocalWorkerProvider. `bindings` are
   * cloudflare-runtime `BindingHook`s — typed opaquely here to keep this
   * module free of an alchemy/cloudflare-runtime type dependency.
   */
  readonly worker: {
    readonly name: string;
    readonly bindings: ReadonlyArray<unknown>;
    /** The Worker's runtime settings; `workerd` reaches the dev platform proxy. */
    readonly options: { readonly workerd?: unknown };
  };
  /**
   * The host's pre-built `Context<RuntimeServices>` (opaque here). Handed
   * to the dev platform proxy so remote()-lowered bindings resolve against
   * the host's runtime stack.
   */
  readonly runtimeContext: unknown;
}

/** Mirror of alchemy's server-mode `SourceDevHandle`. */
export interface SourceDevHandle {
  readonly mode: "server";
  readonly url: URL;
  readonly serviceBinding?: "http";
}

/**
 * Same tag as alchemy's `Cloudflare.Workers.SourceProviderError`, so the
 * errors this module raises are members of alchemy's closed `SourceError`
 * union structurally.
 */
export class SourceProviderError extends Data.TaggedError(
  "Cloudflare.Workers.SourceProviderError",
)<{
  readonly provider: string;
  readonly message: string;
  readonly cause?: unknown;
}> {}

export type SourceError = SourceProviderError | PlatformError;

type SourceServices = FileSystem.FileSystem | Path.Path;

/** Mirror of alchemy's `SourceProvider` (structural). */
export interface SourceProvider {
  readonly ownsAssets: boolean;
  readonly devAssetsBinding?: boolean;
  readonly build: (
    ctx: SourceContext,
  ) => Effect.Effect<SourceBuildOutput, SourceError, SourceServices>;
  readonly hash: (
    ctx: SourceContext,
    previous: SourceHash | undefined,
  ) => Effect.Effect<Partial<SourceHash>, SourceError, SourceServices>;
  readonly dev: (
    ctx: SourceDevContext,
  ) => Effect.Effect<SourceDevHandle, SourceError, SourceServices | Scope.Scope>;
}

// ─────────────────────────────────────────────────────────────────────
// Descriptor options (JSON-serializable — they persist in alchemy state
// and participate in the Worker's metadata hash)
// ─────────────────────────────────────────────────────────────────────

export interface NuxtMemoOptions {
  /** Glob patterns of files to hash, relative to `rootDir`. @default all non-gitignored files */
  readonly include?: Array<string> | undefined;
  /** Glob patterns to exclude. @default gitignore rules from `rootDir` up to the repo root */
  readonly exclude?: Array<string> | undefined;
  /**
   * Include the nearest package-manager lockfile in the hash.
   * @default true when both `include` and `exclude` are unset
   */
  readonly lockfile?: boolean | undefined;
}

export interface NuxtSourceOptions {
  /**
   * Nuxt project root (the directory containing `nuxt.config.ts`). Relative
   * paths resolve from the process working directory. @default process.cwd()
   */
  readonly rootDir?: string | undefined;
  /** Narrows the rebuild-detection input hash. */
  readonly memo?: NuxtMemoOptions | undefined;
  /**
   * Nuxt config overrides merged over the project's own `nuxt.config.ts`
   * (integration wins). Must be JSON-serializable — it persists in state.
   */
  readonly nuxt?: Record<string, unknown> | undefined;
  /**
   * The USER's worker entry (the custom-entry carriage): a module that wraps
   * nitro's emitted handler and adds its own exports (Durable Object
   * classes, ...). Relative paths resolve against `rootDir`.
   */
  readonly main?: string | undefined;
}

// ─────────────────────────────────────────────────────────────────────
// Hashing (mirrors alchemy's Command/Memo.ts + Util/sha256.ts semantics:
// machine-independent — only relative paths and file bytes are hashed)
// ─────────────────────────────────────────────────────────────────────

const sha256Hex = (input: string | Uint8Array): Effect.Effect<string> =>
  Effect.sync(() => NodeCrypto.createHash("sha256").update(input).digest("hex"));

/** Recursively sort object keys so JSON.stringify is order-stable. */
const stableValue = (value: unknown): unknown => {
  if (Array.isArray(value)) {
    return value.map(stableValue);
  }
  if (value !== null && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value as Record<string, unknown>)
        .filter(([, v]) => v !== undefined)
        .sort(([a], [b]) => a.localeCompare(b))
        .map(([k, v]) => [k, stableValue(v)]),
    );
  }
  return value;
};

const sha256Stable = (input: unknown): Effect.Effect<string> =>
  sha256Hex(JSON.stringify(stableValue(input) ?? null));

/**
 * Convert gitignore-style rules into glob `ignore` patterns — a copy of
 * alchemy's `Util/gitignore-rules-to-globs.ts` (common cases only).
 */
const gitignoreRulesToGlobs = (rules: ReadonlyArray<string>): Array<string> => {
  const out: Array<string> = [];
  for (const raw of rules) {
    const line = raw.trim();
    if (line.length === 0 || line.startsWith("#") || line.startsWith("!")) {
      continue;
    }
    let rest = line;
    const dirOnly = rest.endsWith("/");
    if (dirOnly) {
      rest = rest.slice(0, -1);
    }
    rest = rest.replace(/\\/g, "/");
    if (rest.length === 0) continue;
    const anchored = rest.startsWith("/");
    if (anchored) {
      rest = rest.slice(1);
    }
    if (rest.length === 0) continue;
    const hasSlash = rest.includes("/");
    if (dirOnly) {
      out.push(anchored || hasSlash ? `${rest}/**` : `**/${rest}/**`);
    } else if (anchored || hasSlash) {
      out.push(rest, `${rest}/**`);
    } else {
      out.push(`**/${rest}`, `**/${rest}/**`);
    }
  }
  return out;
};

const findUp = Effect.fnUntraced(function* (
  fs: FileSystem.FileSystem,
  cwd: string,
  filenames: Array<string>,
) {
  let dir = cwd;
  for (;;) {
    for (const filename of filenames) {
      const file = NodePath.join(dir, filename);
      if (yield* fs.exists(file)) {
        return file;
      }
    }
    const parent = NodePath.dirname(dir);
    if (parent === dir) {
      return undefined;
    }
    dir = parent;
  }
});

/** Collect `.gitignore` rules from `cwd` up to the repo root (parents first). */
const readGitIgnoreRules = (
  fs: FileSystem.FileSystem,
  cwd: string,
): Effect.Effect<Array<string>, PlatformError> =>
  Effect.gen(function* () {
    const rules = yield* fs.readFileString(NodePath.join(cwd, ".gitignore")).pipe(
      Effect.map((file) => file.split("\n")),
      Effect.catchTag("PlatformError", () => Effect.succeed([] as Array<string>)),
    );
    const parent = NodePath.dirname(cwd);
    if (parent === cwd || (yield* fs.exists(NodePath.join(cwd, ".git")))) {
      return rules;
    }
    const parentRules = yield* readGitIgnoreRules(fs, parent);
    return [...parentRules, ...rules];
  });

/**
 * Deterministic content hash of the files in `cwd` matched by `memo` —
 * mirror of alchemy's `hashDirectory` (`Command/Memo.ts`).
 */
const hashDirectory = Effect.fnUntraced(function* (cwd: string, memo: NuxtMemoOptions | undefined) {
  const fs = yield* FileSystem.FileSystem;
  const include = memo?.include ?? ["**/*"];
  const exclude = memo?.exclude ?? [
    "**/.git/**",
    ...gitignoreRulesToGlobs(yield* readGitIgnoreRules(fs, cwd)),
  ];
  const lockfile = memo?.lockfile ?? !(memo?.include || memo?.exclude);
  const [files, lockfilePath] = yield* Effect.all(
    [
      Effect.promise(() =>
        glob(include, {
          cwd,
          ignore: exclude,
          onlyFiles: true,
          expandDirectories: false,
          dot: true,
        }),
      ),
      lockfile
        ? Effect.map(
            findUp(fs, cwd, [
              "bun.lock",
              "bun.lockb",
              "package-lock.json",
              "pnpm-lock.yaml",
              "yarn.lock",
            ]),
            (file) => (file ? NodePath.relative(cwd, file) : undefined),
          )
        : Effect.undefined,
    ],
    { concurrency: "unbounded" },
  );
  if (lockfilePath && !files.includes(lockfilePath)) {
    files.push(lockfilePath);
  }
  const hashes = yield* Effect.forEach(
    files.sort(),
    (file) =>
      fs.readFile(NodePath.join(cwd, file)).pipe(
        Effect.flatMap(sha256Hex),
        Effect.map((hash) => `${file}:${hash}`),
      ),
    { concurrency: 16 },
  );
  return yield* sha256Stable(hashes);
});

/** This package's version — part of the `input` hash so an integration upgrade busts the memo. */
const packageVersion = Effect.gen(function* () {
  const fs = yield* FileSystem.FileSystem;
  const dir = NodePath.dirname(fileURLToPath(import.meta.url));
  const content = yield* fs.readFileString(NodePath.join(dir, "../../package.json"));
  return (JSON.parse(content) as { version: string }).version;
});

/**
 * The rebuild-free `input` hash: project tree + external workspaces +
 * package version + build-affecting options. Mirrors alchemy's
 * `hashViteInput` semantics (`Workers/Sources/Vite.ts`) — never hashes
 * absolute paths, so relocating an identical tree is a no-op.
 */
const hashNuxtInput = Effect.fnUntraced(function* (
  rootDir: string,
  options: NuxtSourceOptions,
  workspaces: Iterable<string>,
) {
  const version = yield* packageVersion;
  const hashWorkspace = (cwd: string, memo?: NuxtMemoOptions) =>
    hashDirectory(NodePath.resolve(rootDir, cwd), memo).pipe(
      Effect.map((hash) => `${NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd))}:${hash}`),
    );
  const [root, ...workspaceHashes] = yield* Effect.all(
    [hashWorkspace(rootDir, options.memo), ...Array.from(workspaces, (cwd) => hashWorkspace(cwd))],
    { concurrency: "unbounded" },
  );
  const hash = yield* sha256Stable({
    version,
    options: {
      memo: options.memo,
      nuxt: options.nuxt,
      main: options.main,
    },
    tree: [root, ...workspaceHashes.sort()],
  });
  return {
    hash,
    workspaces: Array.from(workspaces, (cwd) =>
      NodePath.relative(rootDir, NodePath.resolve(rootDir, cwd)),
    ),
  };
});

// ─────────────────────────────────────────────────────────────────────
// Assets (mirror of alchemy's `readAssets` in `Workers/Assets.ts`:
// manifest of 32-hex content hashes, honoring `.assetsignore`,
// `_headers`, `_redirects`; the overall hash excludes the directory
// path so identical bytes hash identically across machines)
// ─────────────────────────────────────────────────────────────────────

const MAX_ASSET_SIZE = 1024 * 1024 * 25; // 25MB (Cloudflare limit)
const MAX_ASSET_COUNT = 20_000;

const maybeReadString = (fs: FileSystem.FileSystem, file: string) =>
  fs
    .readFileString(file)
    .pipe(
      Effect.catchTag("PlatformError", (error) =>
        error.reason._tag === "NotFound" ? Effect.undefined : Effect.fail(error),
      ),
    );

const readAssetsDirectory = Effect.fnUntraced(function* (
  directory: string,
  config: Record<string, unknown> | undefined,
) {
  const fs = yield* FileSystem.FileSystem;
  const [ignore, _headers, _redirects] = yield* Effect.all([
    maybeReadString(fs, NodePath.join(directory, ".assetsignore")),
    maybeReadString(fs, NodePath.join(directory, "_headers")),
    maybeReadString(fs, NodePath.join(directory, "_redirects")),
  ]);
  const files = yield* Effect.promise(() =>
    glob(["**/*"], {
      cwd: directory,
      ignore: [
        ".assetsignore",
        "_headers",
        "_redirects",
        ...gitignoreRulesToGlobs(ignore?.split("\n") ?? []),
      ],
      onlyFiles: true,
      expandDirectories: false,
      dot: true,
    }),
  );
  if (files.length > MAX_ASSET_COUNT) {
    return yield* new SourceProviderError({
      provider: PROVIDER,
      message: `Too many assets in ${directory} (maximum is ${MAX_ASSET_COUNT}, found ${files.length})`,
    });
  }
  const entries = yield* Effect.forEach(
    files.sort(),
    Effect.fnUntraced(function* (name) {
      const file = NodePath.join(directory, name);
      const content = yield* fs.readFile(file);
      if (content.byteLength > MAX_ASSET_SIZE) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: `Asset ${name} is too large (the maximum size is 25 MB)`,
        });
      }
      const hash = (yield* sha256Hex(content)).slice(0, 32);
      return [`/${name.replaceAll("\\", "/")}`, { hash, size: content.byteLength }] as const;
    }),
    { concurrency: 16 },
  );
  const manifest = Object.fromEntries([...entries].sort((a, b) => a[0].localeCompare(b[0])));
  const hash = yield* sha256Stable({ config, manifest, _headers, _redirects });
  return {
    directory,
    config,
    manifest,
    _headers,
    _redirects,
    hash,
  } satisfies SourceAssetReadResult;
});

// ─────────────────────────────────────────────────────────────────────
// The provider
// ─────────────────────────────────────────────────────────────────────

const wrapFrameworkError = (error: { readonly message: string; readonly cause?: unknown }) =>
  new SourceProviderError({
    provider: PROVIDER,
    message: error.message,
    cause: error.cause ?? error,
  });

const assetsConfig = (assets: SourceContext["assets"]): Record<string, unknown> | undefined => {
  if (assets === undefined || typeof assets === "string") {
    return undefined;
  }
  const { directory: _directory, hash: _hash, ...config } = assets;
  return Object.keys(config).length > 0 ? config : undefined;
};

/**
 * Resolve the Worker's literal env values as dev env overrides: strings
 * pass through, `Redacted<string>`s are unwrapped, everything else
 * (Effects, resource bindings) is skipped — those are delivered as real
 * bindings through the platform proxy via `ctx.worker.bindings`. A
 * same-named literal wins over the proxied value.
 */
const resolveDevEnvOverrides = (
  env: Record<string, unknown> | undefined,
): Record<string, unknown> => {
  const out: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(env ?? {})) {
    if (typeof value === "string") {
      out[key] = value;
    } else if (Redacted.isRedacted(value) && typeof Redacted.value(value) === "string") {
      out[key] = Redacted.value(value);
    }
  }
  return out;
};

/**
 * The production build runs in a disposable child process with
 * `cwd = project root` (see `core/BuildChild.ts`): `loadNuxt` executes the
 * user's `nuxt.config.ts` and modules, which may read the cwd, mutate
 * `process.env`, or `process.chdir` — none of which may touch the engine
 * process. The shared `core/BuildChildRunner`
 * entry imports this module in the child and calls the exported
 * {@link buildInChild}.
 */
export interface NuxtBuildChildConfig {
  readonly rootDir: string;
  readonly compatibilityDate: string;
  readonly compatibilityFlags: Array<string>;
  readonly main: string | undefined;
  readonly nuxt: Record<string, unknown> | undefined;
}

export const buildInChild = (config: NuxtBuildChildConfig) =>
  Effect.gen(function* () {
    const framework = yield* makeNuxt({
      root: config.rootDir,
      target: makeCloudflareTarget,
      compatibilityDate: config.compatibilityDate,
      compatibilityFlags: config.compatibilityFlags,
      main: config.main,
      nuxt: config.nuxt,
    });
    return yield* framework.build({ root: config.rootDir });
  });

export const makeNuxtSource = (options: NuxtSourceOptions): SourceProvider => {
  const rootDir = NodePath.resolve(options.rootDir ?? process.cwd());
  const frameworkOptions = (ctx: SourceContext, dev?: NuxtOptions["dev"]): NuxtOptions => ({
    root: rootDir,
    // This module is Cloudflare-specific by contract (it implements alchemy's
    // Cloudflare Worker source), so it passes the target factory directly
    // instead of relying on specifier resolution from the project's
    // node_modules.
    target: makeCloudflareTarget,
    compatibilityDate: ctx.compatibility.date,
    compatibilityFlags: ctx.compatibility.flags,
    main: options.main,
    nuxt: options.nuxt,
    dev,
  });
  return {
    ownsAssets: true,
    // The dev platform proxy serves the public directory to `ASSETS`.
    devAssetsBinding: true,
    build: Effect.fnUntraced(function* (ctx) {
      const output = yield* runBuildChild({
        module: import.meta.url,
        rootDir,
        framework: "nuxt",
        env: resolveBuildEnv(ctx.env),
        config: {
          rootDir,
          compatibilityDate: ctx.compatibility.date,
          compatibilityFlags: ctx.compatibility.flags,
          main: options.main,
          nuxt: options.nuxt,
        } satisfies NuxtBuildChildConfig,
      }).pipe(Effect.mapError(wrapFrameworkError));
      if (output.serverModules === undefined || output.serverModules.length === 0) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: "The Nuxt build produced no server modules",
        });
      }
      if (output.clientDirectory === undefined) {
        return yield* new SourceProviderError({
          provider: PROVIDER,
          message: "The Nuxt build produced no client directory",
        });
      }
      const files = output.serverModules.map((module): SourceBundleFile => ({
        path: module.name,
        content: module.content,
        hash: module.hash,
      })) as [SourceBundleFile, ...Array<SourceBundleFile>];
      const [bundleHash, assets, input] = yield* Effect.all(
        [
          sha256Stable(files.map((file) => `${file.path}:${file.hash}`)),
          readAssetsDirectory(
            NodePath.resolve(rootDir, output.clientDirectory),
            assetsConfig(ctx.assets),
          ),
          hashNuxtInput(rootDir, options, output.externalWorkspaces),
        ],
        { concurrency: "unbounded" },
      );
      return {
        bundle: { files, hash: bundleHash },
        assets,
        hash: {
          bundle: bundleHash,
          assets: assets.hash,
          input: input.hash,
          additionalWorkspaces: input.workspaces,
        },
      } satisfies SourceBuildOutput;
    }),
    hash: Effect.fnUntraced(function* (_ctx, previous) {
      const { hash, workspaces } = yield* hashNuxtInput(
        rootDir,
        options,
        previous?.additionalWorkspaces ?? [],
      );
      return { input: hash, additionalWorkspaces: workspaces };
    }),
    dev: Effect.fnUntraced(function* (ctx: SourceDevContext) {
      const framework = yield* makeNuxt(
        frameworkOptions(ctx, {
          env: resolveDevEnvOverrides(ctx.env),
          bindings: ctx.worker.bindings,
          // The host's runtime stack (includes remote-bindings support) —
          // the dev platform proxy is hosted in it instead of the
          // credential-free internal layer, so `Alchemy.remote()` bindings
          // resolve in dev.
          services: ctx.runtimeContext,
          workerd: ctx.worker.options.workerd,
        }),
      );
      const server = yield* framework
        .dev({ root: rootDir, port: 0 })
        .pipe(Effect.mapError(wrapFrameworkError));
      return {
        mode: "server",
        url: new URL(server.url),
        serviceBinding: "http",
      } satisfies SourceDevHandle;
    }),
  };
};

/**
 * The `WorkerSourceModule` contract: alchemy dynamically imports this module
 * and calls `make(descriptor.options)`.
 */
const sourceModule = {
  make: (options: unknown): Effect.Effect<SourceProvider, SourceProviderError> =>
    Effect.succeed(makeNuxtSource((options ?? {}) as NuxtSourceOptions)),
};

export default sourceModule;