@lunora/vite 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -0,0 +1,374 @@
+import { CodegenOptions } from '@lunora/codegen';
+import errorOverlayPlugin from '@visulima/vite-overlay';
+import { Plugin } from 'vite';
+import { FrameworkDetection, DetectedFramework, materializeRemoteWranglerConfig, readProjectRemotePreference } from '@lunora/config';
+export { type DetectedFramework, type FrameworkClass, type FrameworkDetection, detectFramework } from '@lunora/config';
+import { AddressInfo } from 'node:net';
+/** Options forwarded to `@cloudflare/vite-plugin`'s cloudflare plugin. */
+type CloudflarePluginOptions = Record<string, unknown>;
+/**
+* Options forwarded to `@visulima/vite-overlay`'s error-overlay plugin. Derived
+* from the plugin's own factory signature so it tracks the real shape
+* (`forwardConsole`, `forwardedConsoleMethods`, `reactPluginName`,
+* `solutionFinders`, `showBallonButton`, `vuePluginName`, …).
+*/
+type OverlayPluginOptions = NonNullable<Parameters<typeof errorOverlayPlugin>[0]>;
+interface LunoraPluginOptions {
+  /**
+  * Which machine-readable API spec(s) codegen emits into `_generated/`.
+  * `"openapi"` (default) writes `openapi.json` (OpenAPI 3.1; RPC + REST),
+  * `"openrpc"` writes `openrpc.json` (OpenRPC 1.x; RPC-only), `"both"` writes
+  * both, and `"none"` writes neither. Forwarded to `runCodegen({ apiSpec })`;
+  * the value set is derived from `CodegenOptions` so it can't drift.
+  */
+  apiSpec?: CodegenOptions["apiSpec"];
+  /** Pass through to `@cloudflare/vite-plugin`. Pass `false` to opt out. Defaults to `true`. */
+  cloudflare?: boolean | CloudflarePluginOptions;
+  /** Directory name (relative to `projectRoot`) where generated files are written. Defaults to `"lunora/_generated"`. */
+  generatedDir?: string;
+  /**
+  * Inject `@visulima/vite-overlay` for runtime errors (dev only). Pass
+  * `false` to opt out, or an options object to forward to the overlay.
+  * Defaults to `true`.
+  */
+  overlay?: boolean | OverlayPluginOptions;
+  /** Project root containing the `lunora/` directory. Defaults to `process.cwd()`. */
+  projectRoot?: string;
+  /** Directory name (relative to `projectRoot`) containing `schema.ts` and function files. Defaults to `"lunora"`. */
+  schemaDir?: string;
+  /** Serve the Lunora studio at `/__lunora` during dev. Pass `false` to opt out. Defaults to `true`. */
+  studio?: boolean;
+  /** Validate that `wrangler.jsonc` declares the bindings the schema implies. Defaults to `true`. */
+  validateWrangler?: boolean;
+}
+/** Resolved options after merging defaults. */
+interface ResolvedLunoraPluginOptions {
+  apiSpec: NonNullable<CodegenOptions["apiSpec"]>;
+  cloudflare: false | CloudflarePluginOptions;
+  generatedDir: string;
+  overlay: false | OverlayPluginOptions;
+  projectRoot: string;
+  schemaDir: string;
+  studio: boolean;
+  validateWrangler: boolean;
+}
+/**
+* The plugins `lunora()` returns. A mutable `Plugin[]` (not `ReadonlyArray`) so
+* it slots directly into Vite's `plugins` — which recursively flattens nested
+* plugin arrays — without a spread: `plugins: [lunora()]`.
+*/
+type LunoraPlugins = Plugin[];
+/**
+* Vite plugin that runs `@lunora/codegen` on startup and on file changes
+* inside the lunora schema directory.
+*/
+declare const codegenPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+interface ReconcileResult {
+  /** `true` when `wrangler.jsonc` was rewritten. */
+  changed: boolean;
+  /** Human-readable reason when reconciliation was skipped (for logging). */
+  reason?: string;
+  /** Resolved wrangler path, or `undefined` when none was found. */
+  wranglerPath?: string;
+}
+/**
+* Reconcile the codegen-derived cron schedules into the project's
+* `wrangler.jsonc` `triggers.crons` array, preserving comments and formatting
+* via `jsonc-parser`'s structural edits.
+*
+* When `triggers.crons` already matches `cronTriggers`, nothing is written (so
+* we don't churn the file or trip the dev server's file watcher). When the
+* project declares no crons, a stale non-empty array is cleared so removed
+* crons stop firing.
+*
+* This intentionally writes the SAME `triggers.crons` shape the
+* `@lunora/config` validator accepts, so the wrangler validator never fights
+* the generated value.
+*/
+declare const reconcileWranglerCrons: (projectRoot: string, cronTriggers: ReadonlyArray<string>) => ReconcileResult;
+/**
+* Dev-only Vite plugin that offers to scaffold `.dev.vars` before the worker
+* boots. `@cloudflare/vite-plugin` loads `.dev.vars` into the worker's `env`,
+* but the file is gitignored — so a fresh clone has none and the worker throws
+* on the first required secret (e.g. `AUTH_SECRET is required`). When a
+* `.dev.vars.example` exists, we prompt to generate `.dev.vars` from it with
+* secrets auto-filled. Identical behaviour to `lunora dev` — both call
+* `ensureDevVariables` from `@lunora/config`.
+*
+* Runs in `configResolved` (awaited by Vite) so it completes before the
+* Cloudflare plugin reads the file. Non-interactive runs decline silently.
+*/
+declare const devVariablesPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+/**
+* Worker env var the dev tooling sets so the Lunora runtime recognises a
+* development deployment (`@lunora/do`'s `isDevEnvironment`) and therefore
+* streams every RPC dispatch summary to the terminal by default — the
+* `lunora dev` CLI sets the same var via `wrangler dev --var`.
+*
+* It is injected ONLY during `vite` serve, never a production `vite build`, so
+* it can never leak into a deployed worker. A `WORKER_ENV` the user already
+* declares (in `wrangler.jsonc` `[vars]` or `.dev.vars`) takes precedence, so
+* this only fills the gap when none is set.
+*/
+declare const DEV_WORKER_ENV_VAR = "WORKER_ENV";
+declare const DEV_WORKER_ENV_VALUE = "development";
+/** The structural slice of `@cloudflare/vite-plugin`'s worker config we read/write. */
+/**
+* Wrap the cloudflare-plugin options so the dev worker's `vars` gain a
+* `WORKER_ENV` of `development` when — and only when — `isServe()` reports a
+* `vite` serve. Any `config` customizer the caller already supplied is
+* preserved and applied first; an existing `WORKER_ENV` wins, so a user
+* override is never clobbered.
+*/
+declare const withDevWorkerEnv: (options: CloudflarePluginOptions, isServe: () => boolean) => CloudflarePluginOptions;
+/**
+* A Vite plugin that captures the resolved command (`serve` vs `build`) so
+* {@link withDevWorkerEnv} injects the dev var only during `vite`, plus an
+* `isServe` probe sharing the same closure. `enforce: "pre"` so the command is
+* captured before the cloudflare plugin resolves its worker config.
+*/
+declare const createCommandProbe: () => {
+  isServe: () => boolean;
+  plugin: Plugin;
+};
+/**
+* Mutable, plugin-shared context. The `lunora()` factory creates one instance
+* and threads it through every Lunora sub-plugin, so detection runs once and
+* downstream plugins (codegen, composition, the dev hint) read the same result
+* without re-scanning `package.json`. PLAN4 §2.4.
+*/
+interface LunoraPluginContext {
+  /** The detected framework + class, populated during `config` / `configResolved`. `undefined` until detection runs. */
+  framework?: FrameworkDetection;
+}
+/** Create an empty shared context object for one `lunora()` invocation. */
+/**
+* The virtual module id the Lunora plugin resolves to a generated, class-A
+* worker entry. A class-A template points its wrangler `main` at this id (or
+* re-exports it from a one-line `src/server.ts`) and never hand-writes
+* `createWorker({ httpRouter })` — the plugin composes the framework's SSR
+* handler under `composeWorker`'s `httpRouter` seam for it.
+*
+* Exposed publicly so `@lunora/cli`'s build/deploy path and the templates can
+* reference the same constant rather than re-typing the literal.
+*/
+declare const LUNORA_WORKER_VIRTUAL_ID: string;
+/**
+* Per-class-A-framework wiring the generated worker entry needs: how to obtain
+* the framework's SSR handler as a `composeWorker`-compatible `httpRouter`.
+*
+* `imports` is the full import statement(s) the generated entry needs (each
+* framework controls its own import shape — a namespace import, or a named one);
+* `handler` is a JS expression (evaluated in the generated module's scope, where
+* `imports`' symbols are in scope) that yields an `HttpRouterLike`
+* (`{ fetch(request, env?, ctx?) }`). Both are data — not codegen branches — so
+* the set of supported class-A frameworks is one readable table and adding a
+* framework is a pure data edit.
+*
+* Honesty note: these handler expressions encode each framework's *documented*
+* Cloudflare SSR-handler shape — the same expressions the hand-wired template
+* entries use today (React Router's `createRequestHandler` over its virtual
+* server build; SolidStart's `cloudflare-module` handler; TanStack Start's
+* server entry). The plugin just emits them so the developer doesn't.
+*/
+interface ClassAWiring {
+  /** JS expression yielding the `httpRouter` ({ fetch }), referencing symbols brought in by `imports`. */
+  handler: string;
+  /** The import statement(s) the generated entry needs to bring `handler`'s symbols into scope. */
+  imports: string;
+}
+declare const CLASS_A_WIRING: Readonly<Partial<Record<DetectedFramework, ClassAWiring>>>;
+/**
+* Whether the detected framework is one the plugin can auto-compose. Only
+* class-A frameworks with a known SSR-handler wiring qualify; everything else
+* (class B/C, `none`) falls back to the existing flow.
+*/
+declare const isAutoComposable: (context: LunoraPluginContext) => boolean;
+/**
+* Build the source of the virtual class-A worker entry. Pure (no fs / no Vite),
+* so the emitted composition is unit-testable in isolation.
+*
+* The emitted module imports the framework SSR handler + the project's
+* generated artifacts (functions registry, OpenAPI doc, `createShardDO`) and
+* composes them through `composeWorker` — reserved `/_lunora/*` paths route to
+* Lunora, everything else falls through to the framework SSR handler. The
+* `generatedImportBase` MUST be an absolute filesystem path to the `_generated`
+* directory. Virtual modules have no real filesystem path, so relative specifiers
+* like `./lunora/_generated/functions` cannot be resolved by Vite/rolldown from a
+* virtual module id. Absolute paths are resolved correctly in all environments
+* (Vite 8 + rolldown 1.x confirmed).
+*/
+declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedImportBase: string, hasContainers?: boolean, useUmbrella?: boolean) => string;
+/**
+* Vite plugin that auto-composes a detected class-A meta-framework's SSR
+* handler with Lunora into one Cloudflare Worker (PLAN4 §2.4 / §3 class-A row).
+*
+* Mechanism: it resolves the {@link LUNORA_WORKER_VIRTUAL_ID} virtual module to
+* a generated worker entry that wires the framework SSR handler under
+* `composeWorker`'s `httpRouter` seam — so the developer never writes
+* `createWorker({ httpRouter })`. The composed worker is an ordinary module
+* entry, so it HMRs under `@cloudflare/vite-plugin` exactly like a hand-written
+* one (PLAN4 M5 risk #5): the virtual entry only imports the framework handler
+* and the generated artifacts, both of which the framework's plugin + codegen
+* already make HMR-aware.
+*
+* Safety: it is a strict no-op unless `context.framework.class === "A"` with a
+* known wiring. For class-C (SPA) projects and undetected frameworks it
+* resolves/loads nothing. `cloudflare: false` does NOT disable the virtual
+* entry — it only means "don't add the Cloudflare Vite plugin a second time"
+* (the user supplied it themselves); the composed worker must still be
+* resolvable so the user-supplied CF plugin can find the wrangler `main`.
+*/
+declare const frameworkComposePlugin: (options: ResolvedLunoraPluginOptions, context: LunoraPluginContext) => Plugin;
+/**
+* Vite plugin (serve-only) that formats Lunora worker logs in the terminal.
+* Patches `process.stdout`/`process.stderr` once the dev server is configured
+* and restores them when it closes.
+*/
+declare const logStreamPlugin: () => Plugin;
+/** The decision a {@link planViteRemoteBindings} call returns. */
+interface ViteRemotePlan {
+  /** Idempotent disposer for the temp config; always present + safe to call. */
+  cleanup: () => void;
+  /**
+  * Absolute path to the materialized temp wrangler config to hand the
+  * cloudflare plugin's `configPath`, or `undefined` when remote mode is off
+  * or nothing was materialized (no eligible binding, no wrangler file, …).
+  */
+  configPath?: string;
+  /** Whether remote mode was requested for this dev session. */
+  enabled: boolean;
+  /** Why remote mode didn't take effect despite being requested, for logging. */
+  reason?: string;
+}
+/** Inputs to the Vite remote-binding decision — injectable so tests don't touch the env/fs. */
+interface PlanViteRemoteOptions {
+  /** Injection seam — defaults to the real materializer. */
+  materialize?: typeof materializeRemoteWranglerConfig;
+  /** Project root containing `wrangler.jsonc` + the optional `lunora.json`. */
+  projectRoot: string;
+  /** Injection seam — defaults to the real `lunora.json` reader. */
+  readPreference?: typeof readProjectRemotePreference;
+  /** The raw `LUNORA_REMOTE` env value; defaults to `process.env.LUNORA_REMOTE`. */
+  remoteEnv?: string;
+}
+/**
+* Decide whether the Vite dev worker uses remote bindings and, if so,
+* materialize the temp config. Pure decision + a single fs write via the
+* injected materializer; returns a `cleanup` for the dev server's close hook.
+*
+* There is no `--remote` flag on the Vite path (Vite has no Lunora CLI flags),
+* so the precedence reduces to `LUNORA_REMOTE` env > `lunora.json` `remote`.
+*/
+declare const planViteRemoteBindings: (options: PlanViteRemoteOptions) => ViteRemotePlan;
+/**
+* Wrap the cloudflare-plugin options so the dev worker loads the materialized
+* remote temp config (via `configPath`) when — and only when — remote mode is
+* on AND it's a `vite` serve. A `configPath` the caller already set wins (their
+* explicit choice), and during a production build nothing is injected, so the
+* deployed worker is never affected.
+*
+* Returns the wrapped options plus the plan, so `index.ts` can register the
+* cleanup on a close hook. Materialization happens lazily inside the `configPath`
+* resolution path: it's only meaningful during serve, but computing it eagerly
+* is harmless (the materializer is a no-op when disabled) and keeps the wiring
+* simple — the plan is computed once here.
+*/
+declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: () => boolean, plan: ViteRemotePlan) => CloudflarePluginOptions;
+/**
+* A tiny Vite plugin that runs the remote temp-config disposer when the dev
+* server tears down (`buildEnd` fires on close in serve; `closeBundle` covers
+* the build/close path). Idempotent cleanup means firing on both is safe.
+*/
+declare const remoteBindingsCleanupPlugin: (cleanup: () => void) => Plugin;
+/** Dev-server path the studio SPA is served from. */
+declare const STUDIO_PATH = "/__lunora";
+/** Static asset routes the studio document references. */
+
+/**
+* Build the user-facing studio URL from the dev server's resolved address.
+* Pure so it can be unit-tested without a live server. Prefers Vite's own
+* `resolvedUrls.local` (honours `host` / `base` / https); falls back to the raw
+* socket address, bracketing IPv6 and normalising the wildcard host.
+*/
+declare const buildStudioUrl: (input: {
+  address?: AddressInfo | string;
+  base?: string;
+  resolvedLocal?: string;
+}) => string;
+/**
+* Vite plugin that serves the composed Lunora studio at
+* {@link STUDIO_PATH} during dev and prints its URL once the server is
+* listening. Dev-only (`apply: "serve"`); it adds nothing to production builds.
+*
+* Because `lunora dev` spawns Vite, this makes the studio available on
+* `lunora dev` and on a plain `vite` with no per-project files. The studio
+* is served as a prebuilt static bundle, independent of the host app.
+*/
+declare const studioPlugin: () => Plugin;
+/**
+* When a module under `lunora/` throws while the Worker entry is first
+* evaluated, `@cloudflare/vite-plugin` surfaces the failure from deep inside
+* its `runner-worker` running in `workerd`. The real error crosses a workerd
+* RPC boundary on the way out, which drops the user-code stack frames — so all
+* the dev server sees is a bare, file-less message like:
+*
+* ```
+* TypeError: Cannot read properties of undefined (reading 'string')
+*     at runInRunnerObject (workers/runner-worker/index.js:107:3)
+*     at getWorkerEntryExportTypes (workers/runner-worker/index.js:246:24)
+* ```
+*
+* The classic cause is a **circular import**: a `lunora/` query/mutation/action
+* module runs `mutation({ args: { x: v.string() } })` at the top level while the
+* module it imported `v`/`query`/`mutation` from is still mid-initialization, so
+* those bindings read as `undefined`. The message names a validator method
+* (`'string'`, `'id'`, …) but never the file.
+*
+* We can't recover the dropped frames at this layer, but we can recognise the
+* shape of the failure and append an actionable hint pointing at the likely
+* cause — turning a dead-end stack into something a user can act on.
+*/
+declare const WORKER_STARTUP_HINT: string;
+/**
+* True when `error` looks like a Worker-entry evaluation failure routed through
+* `@cloudflare/vite-plugin`'s runner worker (the stack references the runner
+* worker / export-types probe). Kept narrow so we only annotate this specific
+* class of dev-startup error.
+*/
+declare const isWorkerEntryEvalError: (error: unknown) => boolean;
+/**
+* Append {@link WORKER_STARTUP_HINT} to a recognised Worker-entry eval error
+* (idempotently). Any other value is returned untouched.
+*/
+declare const augmentWorkerStartupError: (error: unknown) => unknown;
+/**
+* Wrap the startup hooks of `@cloudflare/vite-plugin`'s plugins so a Worker-entry
+* evaluation failure carries the Lunora hint. Returns a new array; the input
+* plugins are shallow-cloned (never mutated in place) so re-using the cloudflare
+* plugin instances elsewhere stays safe.
+*/
+declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[];
+/**
+* Vite plugin that validates the project's `wrangler.jsonc` against the
+* bindings implied by `lunora/schema.ts`. Throws (Vite renders nicely) on
+* missing requirements during `configResolved`. Delegates the parsing /
+* validation logic to `@lunora/config` so the rules stay in lockstep with
+* the CLI (`lunora deploy`).
+*/
+declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+/**
+* Lunora Vite plugin. Returns a flat array of Vite plugins that:
+*
+* 1. Run `@lunora/codegen` on startup + on schema file changes.
+* 2. Validate the project's `wrangler.jsonc` against the schema's implied bindings.
+* 3. Inject `@visulima/vite-overlay` for runtime error overlays (unless `overlay: false`).
+* 4. Include `@cloudflare/vite-plugin` so users get one-import setup (unless `cloudflare: false`).
+*
+* `@cloudflare/vite-plugin` and `@visulima/vite-overlay` are direct dependencies,
+* so they're imported statically — opt out per-feature via the options rather
+* than relying on whether they're installed.
+*/
+declare const lunora: (options?: LunoraPluginOptions) => LunoraPlugins;
+declare const VERSION = "0.0.0";
+export { CLASS_A_WIRING, type ClassAWiring, type CloudflarePluginOptions, DEV_WORKER_ENV_VALUE, DEV_WORKER_ENV_VAR, LUNORA_WORKER_VIRTUAL_ID, type LunoraPluginOptions, type LunoraPlugins, type OverlayPluginOptions, type PlanViteRemoteOptions, type ReconcileResult, type ResolvedLunoraPluginOptions, STUDIO_PATH, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, planViteRemoteBindings, reconcileWranglerCrons, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };