@jundle/cloudflare 0.0.0-stage → 0.0.0

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@jundle/cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Cloudflare Workers runtime for the jundle dev server (workerd via Miniflare).",
+  "license": "ISC",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./build": {
+      "types": "./src/build.d.ts",
+      "default": "./src/build.js"
+    }
+  },
+  "dependencies": {
+    "miniflare": "4.20260730.0",
+    "unplugin": "3.7.0"
+  },
+  "peerDependencies": {
+    "wrangler": "4.156.0"
+  }
 }

package/src/bindings.js

@@ -0,0 +1,295 @@
+// Wrangler config -> Miniflare options (SPEC §16.3).
+// Every binding is wired; nothing is silently stubbed or
+// downgraded. Local by default; remote only where the spec
+// says so (AI / Browser Rendering / Vectorize are always
+// remote, and per-binding remote is a dev-server CLI flag,
+// handled by the caller via remoteBindings, not config).
+// Persistence mirrors wrangler dev: .wrangler/state/v3 under
+// the project root (KV, R2, D1, Durable Objects, Workflows
+// each get their own subdir there where Miniflare supports a
+// separate persist path).
+// D1 migrations: Miniflare itself has no migrations option —
+// wrangler dev applies them. The mapping keeps migrations_dir
+// on the database entry so the runner (CF-2) can apply the SQL
+// files after Miniflare starts; it is not dropped.
+// Remote credentials come from CLOUDFLARE_ACCOUNT_ID /
+// CLOUDFLARE_API_TOKEN. Without them, a remote-only binding
+// is a clear error naming what's missing (not a silent local
+// fallback).
+import path from "node:path";
+
+function persistDir(configDir, sub) {
+  return path.join(configDir, ".wrangler", "state", "v3", sub);
+}
+
+export function wranglerToMiniflareOptions({
+  config,
+  devVars,
+  configDir,
+  wranglerFile,
+  remoteBindings,
+}) {
+  const options = {
+    modules: true,
+    // The main Worker's name (from wrangler config): dispatch
+    // routes to it, not to the first worker in `workers`.
+    ...(config.name ? { name: config.name } : {}),
+    compatibilityDate: config.compatibility_date,
+    compatibilityFlags: config.compatibility_flags,
+    // Workerd runs with TZ=UTC (workerd does not read the
+    // system timezone; Date is always UTC there).
+    bindings: { ...config.vars, ...devVars },
+  };
+
+  // Remote bindings (CF-3): AI / Browser Rendering / Vectorize
+  // are ALWAYS remote (no local emulation), and any binding
+  // named in the entry options' remoteBindings list is remote
+  // for this session.
+  // Remote requires Cloudflare credentials AND a deployed
+  // remote proxy Worker URL (Miniflare's
+  // remoteProxyConnectionString is a URL to a proxy Worker —
+  // it is what `wrangler dev --remote` deploys). Without
+  // either, that is a clear error naming what is missing —
+  // never a silent local fallback (SPEC §16.3). Native proxy
+  // deployment (deploying the proxy Worker from jundle via
+  // the Cloudflare API) is a follow-up; until then, a
+  // pre-deployed proxy URL comes from
+  // CLOUDFLARE_REMOTE_PROXY_URL (e.g. one wrangler deployed).
+  const remoteNames = new Set(remoteBindings || []);
+  const alwaysRemote = [];
+  if (config.ai?.binding) alwaysRemote.push(["AI", config.ai.binding]);
+  if (config.browser?.binding) alwaysRemote.push(["Browser Rendering", config.browser.binding]);
+  if (config.vectorize?.length) {
+    for (const v of config.vectorize) alwaysRemote.push(["Vectorize", v.binding]);
+  }
+  for (const [, binding] of alwaysRemote) remoteNames.add(binding);
+  // Validate remoteBindings names against the bindings
+  // actually in the wrangler file (a typo must not silently
+  // do nothing — it must be a clear error).
+  if (remoteBindings?.length) {
+    const known = new Set([
+      ...(config.kv_namespaces || []).map((ns) => ns.binding),
+      ...(config.r2_buckets || []).map((b) => b.binding),
+      ...(config.d1_databases || []).map((db) => db.binding),
+      ...(config.durable_objects?.bindings || []).map((b) => b.name),
+      ...(config.queues?.producers || []).map((p) => p.binding),
+      ...(config.workflows || []).map((w) => w.binding),
+      ...(config.ai?.binding ? [config.ai.binding] : []),
+      ...(config.browser?.binding ? [config.browser.binding] : []),
+      ...(config.vectorize || []).map((v) => v.binding),
+      ...(config.services || []).map((s) => s.binding),
+    ]);
+    const unknown = remoteBindings.filter((b) => !known.has(b));
+    if (unknown.length) {
+      throw new Error(
+        `CF plugin: remoteBindings (entry options) names unknown binding(s): ${unknown.join(", ")} (not in the wrangler file)`,
+      );
+    }
+    const remoteServices = (config.services || []).filter((s) => remoteNames.has(s.binding));
+    if (remoteServices.length) {
+      throw new Error(
+        `CF plugin: remote service binding(s) ${remoteServices.map((s) => s.binding).join(", ")} are not supported yet (a remote service needs a service URL, not just a proxy — local service bindings via the workers array are supported; see CF-3 multi-worker)`,
+      );
+    }
+  }
+  let remoteProxyUrl = null;
+  if (remoteNames.size) {
+    const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
+    const apiToken = process.env.CLOUDFLARE_API_TOKEN;
+    const missing = [
+      !accountId && "CLOUDFLARE_ACCOUNT_ID",
+      !apiToken && "CLOUDFLARE_API_TOKEN",
+    ].filter(Boolean);
+    if (missing.length) {
+      const names = [
+        ...alwaysRemote.map(([kind, binding]) => `${kind} (${binding})`),
+        ...[...remoteNames].filter((b) => !alwaysRemote.some(([, ab]) => ab === b)),
+      ].join(", ");
+      throw new Error(
+        `CF plugin: remote binding(s) ${names} require Cloudflare credentials, but missing: ${missing.join(", ")}. ` +
+          `Set ${missing.join(" and ")} to use them (remote bindings have no local fallback).`,
+      );
+    }
+    remoteProxyUrl = process.env.CLOUDFLARE_REMOTE_PROXY_URL || null;
+    if (!remoteProxyUrl) {
+      throw new Error(
+        `CF plugin: remote binding(s) ${[...remoteNames].join(", ")} require a deployed remote proxy Worker URL (Miniflare remoteProxyConnectionString), but CLOUDFLARE_REMOTE_PROXY_URL is not set. ` +
+          `Deploy a remote proxy (e.g. via \`wrangler dev --remote\`, which deploys one) and set CLOUDFLARE_REMOTE_PROXY_URL to its URL. ` +
+          `Native proxy deployment from jundle is a follow-up; until then this is a clear error, not a silent local fallback.`,
+      );
+    }
+    options.cloudflareAccountId = accountId;
+    options.cloudflareApiToken = apiToken;
+  }
+  const isRemote = (binding) => remoteProxyUrl && remoteNames.has(binding);
+
+  // KV: local by default, persisted. Remote namespaces use
+  // the object form ({ id, remoteProxyConnectionString });
+  // if any namespace is remote the whole list becomes a
+  // Record (local entries keep their id as a plain string).
+  if (config.kv_namespaces?.length) {
+    if (config.kv_namespaces.some((ns) => isRemote(ns.binding))) {
+      options.kvNamespaces = {};
+      for (const ns of config.kv_namespaces) {
+        options.kvNamespaces[ns.binding] = isRemote(ns.binding)
+          ? { id: ns.id, remoteProxyConnectionString: remoteProxyUrl }
+          : ns.id;
+      }
+    } else {
+      options.kvNamespaces = config.kv_namespaces.map((ns) => ns.binding);
+    }
+    options.kvPersist = persistDir(configDir, "kv");
+  }
+
+  // R2: local by default, persisted. Same Record-form
+  // conversion as KV when any bucket is remote (id = the
+  // binding, matching the string[] form's bucket naming).
+  if (config.r2_buckets?.length) {
+    if (config.r2_buckets.some((b) => isRemote(b.binding))) {
+      options.r2Buckets = {};
+      for (const b of config.r2_buckets) {
+        options.r2Buckets[b.binding] = isRemote(b.binding)
+          ? { id: b.binding, remoteProxyConnectionString: remoteProxyUrl }
+          : b.binding;
+      }
+    } else {
+      options.r2Buckets = config.r2_buckets.map((b) => b.binding);
+    }
+    options.r2Persist = persistDir(configDir, "r2");
+  }
+
+  // D1: local by default, persisted. migrations_dir is kept
+  // for the runner to apply (see header).
+  if (config.d1_databases?.length) {
+    options.d1Databases = {};
+    for (const db of config.d1_databases) {
+      const id = db.database_id || db.database_name;
+      options.d1Databases[db.binding] = isRemote(db.binding)
+        ? { id, remoteProxyConnectionString: remoteProxyUrl }
+        : id;
+    }
+    options.d1Persist = persistDir(configDir, "d1");
+    options.d1Migrations = config.d1_databases
+      .filter((db) => db.migrations_dir)
+      .map((db) => ({
+        binding: db.binding,
+        dir: path.resolve(
+          path.dirname(wranglerFile || path.join(configDir, "wrangler.jsonc")),
+          db.migrations_dir,
+        ),
+      }));
+  }
+
+  // Durable Objects: class bindings mapped to classes the app
+  // exports; storage persisted; alarms are a runtime feature
+  // (no option needed — the DO class's alarm() handler runs).
+  if (config.durable_objects?.bindings?.length) {
+    options.durableObjects = {};
+    for (const b of config.durable_objects.bindings) {
+      options.durableObjects[b.name] = isRemote(b.name)
+        ? { className: b.class_name, remoteProxyConnectionString: remoteProxyUrl }
+        : b.class_name;
+    }
+    options.durableObjectsPersist = persistDir(configDir, "do");
+  }
+
+  // Queues: producers + consumers, local by default (local
+  // queues are in-memory only — Miniflare behavior, not
+  // hidden). Consumers dispatch to the app's exported queue()
+  // handler (Miniflare does this when the Worker exports it).
+  // A remote producer sends to the real Cloudflare queue;
+  // the consumer stays local (it is this Worker's handler).
+  if (config.queues?.producers?.length) {
+    options.queueProducers = {};
+    for (const p of config.queues.producers) {
+      options.queueProducers[p.binding] = isRemote(p.binding)
+        ? { queueName: p.queue, remoteProxyConnectionString: remoteProxyUrl }
+        : p.queue;
+    }
+  }
+  if (config.queues?.consumers?.length) {
+    options.queueConsumers = {};
+    for (const c of config.queues.consumers) {
+      options.queueConsumers[c.queue] = {
+        ...(c.max_batch_size !== undefined ? { maxBatchSize: c.max_batch_size } : {}),
+        ...(c.max_batch_timeout !== undefined ? { maxBatchTimeout: c.max_batch_timeout } : {}),
+        ...(c.max_retries !== undefined ? { maxRetries: c.max_retries } : {}),
+        ...(c.dead_letter_queue !== undefined ? { deadLetterQueue: c.dead_letter_queue } : {}),
+      };
+    }
+  }
+
+  // Workflows: mapped to Workflow classes the app exports;
+  // state persisted in Durable Objects (Miniflare handles the
+  // storage when workflowsPersist is set).
+  if (config.workflows?.length) {
+    options.workflows = {};
+    for (const w of config.workflows) {
+      options.workflows[w.binding] = isRemote(w.binding)
+        ? { name: w.name, className: w.class_name, remoteProxyConnectionString: remoteProxyUrl }
+        : { name: w.name, className: w.class_name };
+    }
+    options.workflowsPersist = persistDir(configDir, "workflows");
+  }
+
+  // Cron triggers (wrangler `triggers.crons`): Miniflare runs
+  // scheduled handlers on this schedule (and
+  // dispatchScheduled triggers one on demand). Mapped here
+  // so the config is honored, not dropped.
+  if (config.triggers?.crons?.length) {
+    options.crons = [...config.triggers.crons];
+  }
+
+  // Service bindings: a local Worker (by service name) or a
+  // remote service. Local services are resolved by the runner
+  // (CF-2) via Miniflare's worker registry; remote services
+  // need credentials and are handled in CF-3.
+  if (config.services?.length) {
+    options.serviceBindings = {};
+    for (const s of config.services) {
+      if (s.service) options.serviceBindings[s.binding] = s.service;
+    }
+  }
+
+  // Assets: bound to a local directory (wrangler `assets`
+  // config: { directory } or a plain path string).
+  // routerConfig.has_user_worker tells Miniflare's assets
+  // router that a user Worker exists to fall through to for
+  // non-asset paths; without it, Miniflare serves ONLY static
+  // files and every Worker route 404s (assets-only mode).
+  // With it, static files win for matching paths and the
+  // Worker handles the rest (the Workers Static Assets model).
+  if (config.assets) {
+    const dir = typeof config.assets === "string" ? config.assets : config.assets.directory;
+    if (dir)
+      options.assets = {
+        directory: path.resolve(configDir, dir),
+        routerConfig: { has_user_worker: true },
+      };
+  }
+
+  // AI / Browser Rendering / Vectorize: ALWAYS remote (no
+  // local emulation). Wired here (not just recorded) when a
+  // proxy URL is present; without credentials or a proxy URL
+  // the top-of-function checks already threw a clear error.
+  if (config.ai?.binding) {
+    options.ai = { binding: config.ai.binding, remoteProxyConnectionString: remoteProxyUrl };
+  }
+  if (config.browser?.binding) {
+    options.browserRendering = {
+      binding: config.browser.binding,
+      remoteProxyConnectionString: remoteProxyUrl,
+    };
+  }
+  if (config.vectorize?.length) {
+    options.vectorize = {};
+    for (const v of config.vectorize) {
+      options.vectorize[v.binding] = {
+        index_name: v.index_name,
+        remoteProxyConnectionString: remoteProxyUrl,
+      };
+    }
+  }
+
+  return options;
+}

package/src/build.d.ts

@@ -0,0 +1,145 @@
+// Type declarations for @jundle/cloudflare/build — the
+// Cloudflare Workers BUILD plugin (SPEC §16.13). See
+// src/build.js for the implementation; src/index.d.ts for
+// the runtime plugin and the WranglerConfig type (imported
+// here, not duplicated).
+import type { WranglerConfig } from "./index.js";
+
+/** The five Workers runtime builtins, exactly
+ * @cloudflare/vite-plugin's cloudflareBuiltInModules. */
+export declare const CLOUDFLARE_BUILTINS: readonly [
+  "cloudflare:email",
+  "cloudflare:node",
+  "cloudflare:sockets",
+  "cloudflare:workers",
+  "cloudflare:workflows",
+];
+
+/** Options for the build plugin, core-managed when
+ * auto-registered (SPEC §16.13). `configDir` is
+ * required: the writeBundle handler only receives
+ * { dir } + the file list, so the project directory
+ * must be captured at construction time. */
+export interface CloudflareBuildPluginOptions {
+  /** Project root: the wrangler file is resolved against this. */
+  configDir: string;
+  /**
+   * Path to the wrangler config file, resolved against
+   * configDir. Null/omitted auto-discovers wrangler.jsonc,
+   * wrangler.json, then wrangler.toml in the config directory.
+   */
+  wranglerConfig?: string | null;
+}
+
+/** Inputs to {@link getOutputConfig}. */
+export interface OutputConfigArgs {
+  /** The user's wrangler config, as read by readWranglerConfig. */
+  userConfig: WranglerConfig;
+  /** The server entry chunk, outDir-relative (e.g. "server/server.js"). */
+  main: string;
+  /** Whether the build has client output (drives assets.directory). */
+  includeAssets: boolean;
+  /** Absolute output directory (the worker outDir). */
+  outDir: string;
+  /** Project root, for rebasing source-relative paths. */
+  configDir: string;
+  /** Whether the entry chunk has a .map in the bundle. */
+  sourcemaps: boolean;
+}
+
+/**
+ * The generated <outDir>/wrangler.json (upstream
+ * getOutputConfig): the user's config with main,
+ * no_bundle, rules, rebased assets/containers/d1, and
+ * upload_source_maps applied. Other fields pass through
+ * verbatim; the return type is the input config plus the
+ * overrides, so it stays open via the index signature.
+ */
+export declare function getOutputConfig(args: OutputConfigArgs): WranglerConfig & {
+  main: string;
+  no_bundle: true;
+  rules: Array<{ type: "ESModule"; globs: string[] }>;
+  upload_source_maps?: boolean;
+};
+
+/** Quote one value for .dev.vars (upstream quoteForDotenv). */
+export declare function quoteForDotenv(value: string): string;
+
+/** Serialize local dev vars to .dev.vars file contents. */
+export declare function serializeDevVars(devVars: Record<string, string>): string;
+
+/** The <configDir>/.wrangler/deploy/config.json contents. */
+export interface DeployConfig {
+  /** Path relative from .wrangler/deploy/ to <outDir>/wrangler.json. */
+  configPath: string;
+  /** No auxiliary workers in single-worker jundle. */
+  auxiliaryWorkers: Array<{ configPath: string }>;
+}
+
+export declare function buildDeployConfig(args: {
+  configDir: string;
+  outDir: string;
+}): DeployConfig;
+
+/** Rewrite a D1 migrations_pattern from the source
+ * migrations dir to the output migrations dir. */
+export declare function rewriteMigrationsPattern(
+  migrationsPattern: string | undefined,
+  fromMigrationsDir: string,
+  toMigrationsDir: string,
+): string | undefined;
+
+/** The meta object core passes to the factory's `raw`. */
+export interface CloudflareBuildPluginMeta {
+  framework: "jundle";
+  versions: { unplugin: string; jundle: string };
+}
+
+/** The plugin object the factory produces. */
+export interface CloudflareBuildPlugin {
+  name: "@jundle/cloudflare";
+  enforce: "pre";
+  /**
+   * Returns `{ id: source, external: true }` for the
+   * exact five `cloudflare:*` builtins, `null` otherwise.
+   */
+  resolveId: (
+    source: string,
+    importer: string | undefined,
+    options: {
+      isEntry: boolean;
+      attributes: Record<string, string>;
+      custom?: unknown;
+      kind: "static" | "dynamic";
+    },
+  ) => { id: string; external: true } | null;
+  /** Emits the deployment config after the write phase. */
+  writeBundle: (options: { dir: string }, bundle: string[]) => Promise<void>;
+}
+
+/**
+ * The build plugin factory (unplugin, as the demo plugin
+ * in examples/rsc-app/plugins/demo-plugin.js). Core
+ * auto-registers it for a @jundle/cloudflare runtime
+ * entry; it can also be declared explicitly in
+ * config.plugins with the same options.
+ *
+ * Deliberately NOT typed via `unplugin`'s own types:
+ * core only ever calls `.raw(options, meta)` (see
+ * `plugin-inventory.js`), and importing unplugin's
+ * declarations pulls in its optional peer declarations
+ * (`@farmfe/core`, `rollup`, ...) which are not
+ * installed, breaking consumers' typechecks. The other
+ * framework adapters (`.vite`, `.rollup`, ...) exist at
+ * runtime but are not part of jundle's contract, so they
+ * are not declared here.
+ */
+export interface CloudflareBuildPluginFactory {
+  raw: (
+    options: CloudflareBuildPluginOptions,
+    meta: CloudflareBuildPluginMeta,
+  ) => CloudflareBuildPlugin | CloudflareBuildPlugin[];
+}
+
+declare const _default: CloudflareBuildPluginFactory;
+export default _default;