@jundle/cloudflare 0.0.0-stage → 0.0.1-0

package/src/build.js

@@ -0,0 +1,327 @@
+// @jundle/cloudflare — the Cloudflare Workers BUILD plugin
+// (SPEC §16.13). The runtime plugin (src/index.js) is dev-only;
+// this is its build half, auto-registered by jundle core when a
+// build entry's runtime is "@jundle/cloudflare" (runtime
+// implies it, SPEC §16.13): core appends it to config.plugins
+// before the inventory is built, with options { configDir,
+// wranglerConfig }, and merges its externals into every
+// graph's external list in buildEngineConfig. It can also be
+// declared explicitly in config.plugins — core then augments
+// its options with configDir/wranglerConfig instead of
+// registering it twice.
+//
+// Two hooks, both wired in the all-native bridge:
+// - resolveId: the five cloudflare:* builtins from
+//   @cloudflare/vite-plugin (exact match, not a prefix) are
+//   returned as external. Belt-and-braces — the graph-list
+//   merge already externalizes them before any resolveId
+//   runs, including for dep bundling (which never yields
+//   resolveId). The hook also covers a plugin declared
+//   without the runtime, where no merge happens.
+// - writeBundle: after the files are on disk, emit the
+//   deployment config mirroring @cloudflare/vite-plugin
+//   v1.64 (output-config.ts + deploy-config.ts): the
+//   generated <outDir>/wrangler.json, <outDir>/.dev.vars
+//   when local dev vars exist, and
+//   <configDir>/.wrangler/deploy/config.json pointing at
+//   the generated wrangler.json. Files are written with
+//   fs directly: writeBundle's this.emitFile drops assets
+//   with a warning (late emitState), so they never appear
+//   in the build's written-file list — that is expected.
+//   generateBundle is deferred in the native bridge, so
+//   writeBundle is the v1 hook; a native generateBundle
+//   yield is the clean long-term fix.
+//
+// The wrangler file is the single source of truth for the
+// deployment config (SPEC §16.3): it is read with the
+// package's existing readWranglerConfig (wrangler's
+// unstable_readConfig), never duplicated in jundle config.
+// Top-level/default env only (named env.* is out of scope,
+// SPEC decisions O10).
+import fs from "node:fs";
+import path from "node:path";
+import { createUnplugin } from "unplugin";
+import { readWranglerConfig } from "./config.js";
+
+// The Workers runtime builtins, exactly
+// @cloudflare/vite-plugin's cloudflareBuiltInModules
+// (v1.64.0, src/plugins/output-config.ts). Exact match
+// only: "cloudflare:*" as a pattern would never match
+// the engine's exact-or-pat/ external check, and a
+// prefix match here would externalize future unknown
+// subpaths. Core merges this same list into every
+// graph's external list (build.js buildEngineConfig);
+// keep the two in sync — the test asserts they match.
+export const CLOUDFLARE_BUILTINS = [
+  "cloudflare:email",
+  "cloudflare:node",
+  "cloudflare:sockets",
+  "cloudflare:workers",
+  "cloudflare:workflows",
+];
+const BUILTIN_RE = /^cloudflare:(email|node|sockets|workers|workflows)$/;
+
+// Quote a value so wrangler reads it back unchanged when
+// it parses the emitted .dev.vars (upstream
+// quoteForDotenv, output-config.ts): pick the first quote
+// character that does not appear in the value (single,
+// then backtick, then double). Throw rather than silently
+// corrupt a value that cannot be losslessly serialized.
+export function quoteForDotenv(value) {
+  if (!value.includes("'")) return `'${value}'`;
+  if (!value.includes("`")) return `\`${value}\``;
+  if (!value.includes('"') && !/[\\\n\r]/.test(value)) return `"${value}"`;
+  throw new Error(
+    "CF plugin: unable to serialize .dev.vars value: contains every supported quote character or unsafe escape sequence",
+  );
+}
+
+export function serializeDevVars(devVars) {
+  return Object.entries(devVars || {})
+    .map(([key, value]) => `${key}=${quoteForDotenv(String(value ?? ""))}\n`)
+    .join("");
+}
+
+// Rebase a source-relative path (resolved against the
+// wrangler file's directory) to be relative to the
+// output directory (upstream rebasePathToOutput). "." when
+// the two directories coincide. Always posix separators:
+// wrangler.json paths are posix.
+function rebasePathToOutput(sourcePath, sourceConfigDir, outputDir) {
+  const rel = path.relative(outputDir, path.resolve(sourceConfigDir, sourcePath));
+  return rel.split(path.sep).join("/") || ".";
+}
+
+// Upstream rewriteMigrationsPattern (output-config.ts),
+// ported verbatim: strip the source migrations dir prefix
+// from the pattern and re-root it under the output
+// migrations dir. Undefined stays undefined (the key is
+// then omitted from the emitted config).
+export function rewriteMigrationsPattern(migrationsPattern, fromMigrationsDir, toMigrationsDir) {
+  if (migrationsPattern === undefined) return undefined;
+  const normalizedDir = path.posix.normalize(fromMigrationsDir.split(path.sep).join("/"));
+  const normalizedPattern = path.posix.normalize(migrationsPattern.split(path.sep).join("/"));
+  const suffix =
+    normalizedDir === "."
+      ? normalizedPattern
+      : path.posix.relative(normalizedDir, normalizedPattern);
+  return path.posix.normalize(toMigrationsDir === "." ? suffix : `${toMigrationsDir}/${suffix}`);
+}
+
+// The generated <outDir>/wrangler.json (upstream
+// getOutputConfig, output-config.ts): the user's wrangler
+// config, spread first, then the build overrides. Pure
+// function, exported for tests.
+// - main: the server entry chunk, outDir-relative (e.g.
+//   "server/server.js").
+// - no_bundle: true (the chunk is already bundled).
+// - rules: ESModule for all JS/MJS.
+// - assets: only when the build has client output — the
+//   built client directory is always "client" under the
+//   outDir (emit.rs maps react-client -> client), so the
+//   directory is "client" regardless of what the user's
+//   assets said (a string assets value is normalised to
+//   object form first, as bindings.js does for dev).
+// - containers: dockerfile/build_context rebased to the
+//   output dir, build_vars passed through. (Containers are
+//   out of scope for the dev runner, SPEC §16.3, but a
+//   verbatim passthrough would leave stale source-relative
+//   paths in a deployed config, so they are rebased.)
+// - d1_databases: migrations_dir defaults to "migrations"
+//   and is rebased; migrations_pattern is rewritten.
+// - upload_source_maps: true only when the user did not
+//   set it and the entry chunk has a .map in the bundle
+//   (builds always emit sourcemaps, build.js hardcodes
+//   sourcemap: true — the bundle-list check is the
+//   evidence, not the assumption).
+// - configPath (the source file pointer, if
+//   unstable_readConfig returned one) is stripped: it
+//   describes the source file, never the output.
+// - An empty unsafe: {} is deleted (upstream).
+// Every other field (name, compatibility_date/flags,
+// vars, bindings) passes through verbatim.
+export function getOutputConfig({ userConfig, main, includeAssets, outDir, configDir, sourcemaps }) {
+  // unstable_readConfig returns an absolute configPath;
+  // resolve a relative one against configDir so the
+  // rebase base is never accidentally process.cwd().
+  const sourceConfigDir = userConfig.configPath
+    ? path.dirname(path.resolve(configDir, userConfig.configPath))
+    : configDir;
+  const rebase = (p) => rebasePathToOutput(p, sourceConfigDir, outDir);
+  const out = {
+    ...userConfig,
+    main,
+    no_bundle: true,
+    rules: [{ type: "ESModule", globs: ["**/*.js", "**/*.mjs"] }],
+  };
+  delete out.configPath;
+  if (includeAssets) {
+    const assets =
+      userConfig.assets && typeof userConfig.assets === "object" ? userConfig.assets : {};
+    out.assets = { ...assets, directory: "client" };
+  } else {
+    delete out.assets;
+  }
+  if (Array.isArray(userConfig.containers)) {
+    out.containers = userConfig.containers.map((container) => {
+      if (container.images === undefined) return container;
+      return {
+        ...container,
+        images: Object.fromEntries(
+          Object.entries(container.images).map(([name, image]) => {
+            if (image.dockerfile === undefined) return [name, image];
+            return [
+              name,
+              {
+                ...image,
+                dockerfile: rebase(image.dockerfile),
+                ...(image.build_context === undefined
+                  ? {}
+                  : { build_context: rebase(image.build_context) }),
+                ...(image.build_vars === undefined ? {} : { build_vars: image.build_vars }),
+              },
+            ];
+          }),
+        ),
+      };
+    });
+  }
+  if (Array.isArray(userConfig.d1_databases)) {
+    out.d1_databases = userConfig.d1_databases.map((database) => {
+      const sourceMigrationsDir = database.migrations_dir ?? "migrations";
+      const outputMigrationsDir = rebase(sourceMigrationsDir);
+      const pattern = rewriteMigrationsPattern(
+        database.migrations_pattern,
+        sourceMigrationsDir,
+        outputMigrationsDir,
+      );
+      return {
+        ...database,
+        migrations_dir: outputMigrationsDir,
+        ...(pattern === undefined ? {} : { migrations_pattern: pattern }),
+      };
+    });
+  }
+  if (userConfig.upload_source_maps === undefined && sourcemaps) {
+    out.upload_source_maps = true;
+  }
+  if (out.unsafe && typeof out.unsafe === "object" && Object.keys(out.unsafe).length === 0) {
+    delete out.unsafe;
+  }
+  return out;
+}
+
+// The deploy redirect (upstream writeDeployConfig,
+// deploy-config.ts): <configDir>/.wrangler/deploy/
+// config.json, whose configPath is relative from the
+// deploy dir to the generated wrangler.json. wrangler
+// deploy reads the GENERATED config, not the source
+// wrangler file. Single-worker jundle has no auxiliary
+// or prerender workers, so those are [] / omitted.
+export function buildDeployConfig({ configDir, outDir }) {
+  const deployDir = path.join(configDir, ".wrangler", "deploy");
+  return {
+    configPath: path
+      .relative(deployDir, path.join(outDir, "wrangler.json"))
+      .split(path.sep)
+      .join("/"),
+    auxiliaryWorkers: [],
+  };
+}
+
+// Find the Worker entry in server-manifest.json: the
+// entry carrying runtime "@jundle/cloudflare". Fallback
+// is the first entry (the process entry) — for a plugin
+// declared explicitly without a CF runtime entry, the
+// main is still the entry chunk; only a manifest with no
+// entries at all is a hard error.
+function getCloudflareEntry(manifest) {
+  const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
+  if (!entries.length) {
+    throw new Error(
+      "CF plugin: server-manifest.json has no entries; cannot determine the Worker entry chunk for wrangler.json",
+    );
+  }
+  return entries.find((e) => e.runtime === "@jundle/cloudflare") || entries[0];
+}
+
+// The build plugin (unplugin factory, as the demo plugin
+// in examples/rsc-app/plugins/demo-plugin.js). Options
+// are core-managed when auto-registered: { configDir,
+// wranglerConfig? }. A user declaring the plugin
+// explicitly passes the same options; configDir is
+// required for the wrangler output (the writeBundle
+// handler only receives { dir } + the file list, never
+// configDir — so it must be captured here, in the
+// closure, at construction time).
+const cloudflareBuildPlugin = createUnplugin((options = {}) => {
+  const configDir = options.configDir;
+  const wranglerConfig = options.wranglerConfig ?? null;
+  return {
+    name: "@jundle/cloudflare",
+    enforce: "pre",
+    resolveId(source) {
+      if (BUILTIN_RE.test(source)) return { id: source, external: true };
+      return null;
+    },
+    async writeBundle(writeOptions, bundle) {
+      if (!configDir || typeof configDir !== "string") {
+        throw new Error(
+          "CF plugin: writeBundle needs the project directory (configDir); it is passed by jundle core when the plugin is auto-registered for a @jundle/cloudflare runtime entry, or as the plugin option { configDir } when declared explicitly",
+        );
+      }
+      const outDir = writeOptions?.dir ? path.resolve(writeOptions.dir) : null;
+      if (!outDir) {
+        throw new Error("CF plugin: writeBundle received no output directory (options.dir)");
+      }
+      const manifestPath = path.join(outDir, "server-manifest.json");
+      let manifest;
+      try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      } catch (e) {
+        throw new Error(
+          `CF plugin: cannot read ${manifestPath} for the wrangler output (load error: ${e.message})`,
+        );
+      }
+      const entry = getCloudflareEntry(manifest);
+      const main = entry.chunk;
+      if (!main || typeof main !== "string") {
+        throw new Error(
+          `CF plugin: server-manifest.json entry ${JSON.stringify(entry.id ?? entry.file)} has no chunk path; cannot set wrangler.json main`,
+        );
+      }
+      const { config: userConfig, devVars } = await readWranglerConfig({
+        configDir,
+        wranglerConfig,
+      });
+      const files = Array.isArray(bundle) ? bundle : [];
+      const includeAssets =
+        files.some((f) => f === "client" || f.startsWith("client/")) ||
+        fs.existsSync(path.join(outDir, "client"));
+      const sourcemaps = files.includes(`${main}.map`);
+      const outputConfig = getOutputConfig({
+        userConfig,
+        main,
+        includeAssets,
+        outDir,
+        configDir,
+        sourcemaps,
+      });
+      fs.writeFileSync(
+        path.join(outDir, "wrangler.json"),
+        `${JSON.stringify(outputConfig, null, 2)}\n`,
+      );
+      if (devVars && Object.keys(devVars).length > 0) {
+        fs.writeFileSync(path.join(outDir, ".dev.vars"), serializeDevVars(devVars));
+      }
+      const deployDir = path.join(configDir, ".wrangler", "deploy");
+      fs.mkdirSync(deployDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(deployDir, "config.json"),
+        `${JSON.stringify(buildDeployConfig({ configDir, outDir }), null, 2)}\n`,
+      );
+    },
+  };
+});
+
+export default cloudflareBuildPlugin;

package/src/config.js

@@ -0,0 +1,82 @@
+// Wrangler config reading for the CF plugin (SPEC §16.3).
+// The single jundle-side setting is which wrangler config file
+// to use (dev.environments.<env>.wranglerConfig, relative to
+// the jundle config dir). Everything else comes from the
+// wrangler file on disk — nothing is duplicated in jundle
+// config. If wranglerConfig is omitted, auto-discover from the
+// project root (the jundle config dir) in order wrangler.jsonc,
+// wrangler.json, wrangler.toml. If workerd is selected and no
+// wrangler file is found, a clear error names the missing file.
+// Config is read via wrangler's own utilities
+// (unstable_readConfig); the wrangler version is pinned in
+// this package's dependencies because the `unstable_` prefix
+// means the API can change across versions.
+// Secrets: wrangler `vars` + `.dev.vars` (read from disk
+// alongside the wrangler file, falling back to the project
+// root). `.dev.vars` is parsed as a dotenv subset (KEY=VALUE
+// lines, # comments, surrounding quotes stripped); wrangler's
+// own reader is not exported, so this is jundle's parser.
+import fs from "node:fs";
+import path from "node:path";
+import { unstable_readConfig } from "wrangler";
+
+const DISCOVER_ORDER = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
+
+export function resolveWranglerFile({ configDir, wranglerConfig }) {
+  if (wranglerConfig) {
+    const file = path.resolve(configDir, wranglerConfig);
+    if (!fs.existsSync(file)) {
+      throw new Error(
+        `CF plugin: wrangler config file not found: ${file} (dev.environments.<env>.wranglerConfig)`,
+      );
+    }
+    return file;
+  }
+  for (const name of DISCOVER_ORDER) {
+    const file = path.join(configDir, name);
+    if (fs.existsSync(file)) return file;
+  }
+  throw new Error(
+    `CF plugin: no wrangler config file found (looked for ${DISCOVER_ORDER.join(", ")} in ${configDir}). ` +
+      `Set dev.environments.<env>.wranglerConfig to the wrangler config file to use.`,
+  );
+}
+
+export function parseDevVars(text) {
+  const vars = {};
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key) vars[key] = value;
+  }
+  return vars;
+}
+
+export function readDevVars({ wranglerFile, configDir }) {
+  // Alongside the wrangler file first, then the project root.
+  const candidates = [
+    path.join(path.dirname(wranglerFile), ".dev.vars"),
+    path.join(configDir, ".dev.vars"),
+  ];
+  for (const file of candidates) {
+    if (fs.existsSync(file)) return parseDevVars(fs.readFileSync(file, "utf8"));
+  }
+  return {};
+}
+
+export async function readWranglerConfig({ configDir, wranglerConfig }) {
+  const file = resolveWranglerFile({ configDir, wranglerConfig });
+  const config = await unstable_readConfig({ config: file });
+  const devVars = readDevVars({ wranglerFile: file, configDir });
+  return { file, config, devVars };
+}