@lunora/vite 1.0.0-alpha.7 → 1.0.0-alpha.70

package/dist/index.d.mts

@@ -2,7 +2,7 @@ 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';
+export { type DetectedFramework, type FrameworkClass, type FrameworkDetection, type ReconcileCronsResult as ReconcileResult, detectFramework, reconcileWranglerCrons } from '@lunora/config';
 import { AddressInfo } from 'node:net';
 /** Options forwarded to `@cloudflare/vite-plugin`'s cloudflare plugin. */
 type CloudflarePluginOptions = Record<string, unknown>;
@@ -14,6 +14,15 @@ type CloudflarePluginOptions = Record<string, unknown>;
 */
 type OverlayPluginOptions = NonNullable<Parameters<typeof errorOverlayPlugin>[0]>;
 interface LunoraPluginOptions {
+  /**
+  * Allow a client-named NON-default shard / cross-shard fan-out WITHOUT an
+  * `authorizeShard`/`authorizeFanOut` callback. The auto-composed class-A worker
+  * (`virtual:lunora/worker`) default-denies such access (403 `FORBIDDEN_SHARD`);
+  * set this `true` to opt into open access — only safe when every table is
+  * protected by per-row RLS. A production sharded app should configure
+  * `authorizeShard` instead (via a hand-written class-B worker). Defaults to `false`.
+  */
+  allowUnauthenticatedShardAccess?: boolean;
   /**
   * Which machine-readable API spec(s) codegen emits into `_generated/`.
   * `"openapi"` (default) writes `openapi.json` (OpenAPI 3.1; RPC + REST),
@@ -43,6 +52,7 @@ interface LunoraPluginOptions {
 }
 /** Resolved options after merging defaults. */
 interface ResolvedLunoraPluginOptions {
+  allowUnauthenticatedShardAccess: boolean;
   apiSpec: NonNullable<CodegenOptions["apiSpec"]>;
   cloudflare: false | CloudflarePluginOptions;
   generatedDir: string;
@@ -63,37 +73,40 @@ type LunoraPlugins = Plugin[];
 * 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.
+* Dev-only plugin that tails the local dev containers' own stdout/stderr in the
+* Vite terminal.
 *
-* 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.
+* `@cloudflare/vite-plugin` builds and runs each declared container locally via
+* Docker (image `cloudflare-dev/&lt;class>:&lt;id>`) but only forwards the *worker's*
+* console — the container process's own output is otherwise invisible. This
+* plugin attaches to those Docker log streams (via `@lunora/config`'s
+* `streamContainerLogs`, which lazy-loads `dockerode`) and prints each line
+* through Vite's logger, branded and tagged `container:&lt;name>`.
 *
-* This intentionally writes the SAME `triggers.crons` shape the
-* `@lunora/config` validator accepts, so the wrangler validator never fights
-* the generated value.
+* A no-op when the project declares no containers (the common case): discovery
+* returns an empty list, so `dockerode` is never imported and no Docker work
+* starts. Set `LUNORA_CONTAINER_LOGS=0` to opt out. A missing/stopped Docker
+* engine degrades to a single warning rather than breaking dev.
 */
-declare const reconcileWranglerCrons: (projectRoot: string, cronTriggers: ReadonlyArray<string>) => ReconcileResult;
+declare const containerLogsPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+/** Vite plugin (serve-only) that writes the dev-server state record on listen and clears it on close. */
+declare const devStatePlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* 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`.
+* Dev-only Vite plugin that prepares `.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`). Two steps, both shared
+* with `lunora dev` via `@lunora/config`.
+*
+* First, {@link ensureDevVariables}: when a `.dev.vars.example` exists, prompt
+* to generate `.dev.vars` from it with secrets auto-filled. Second,
+* {@link fillDevSecrets}: fill any empty/placeholder secret already in
+* `.dev.vars` (a `lunora add`-scaffolded project writes secrets blank) and
+* ensure `LUNORA_ADMIN_TOKEN` is present + generated — so the worker boots with
+* working secrets and the Studio authenticates without its login gate. No
+* prompt: it only generates locally-derivable values and never overwrites a real
+* one.
 *
 * Runs in `configResolved` (awaited by Vite) so it completes before the
 * Cloudflare plugin reads the file. Non-interactive runs decline silently.
@@ -198,7 +211,7 @@ declare const isAutoComposable: (context: LunoraPluginContext) => boolean;
 * 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;
+declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedImportBase: string, hasContainers?: boolean, useUmbrella?: boolean, allowUnauthenticatedShardAccess?: 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).
@@ -221,9 +234,30 @@ declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedIm
 */
 declare const frameworkComposePlugin: (options: ResolvedLunoraPluginOptions, context: LunoraPluginContext) => Plugin;
 /**
+* The custom HMR event the Lunora Vite plugin sends on the client environment's
+* hot channel after a successful codegen run, in place of the old blanket
+* browser `full-reload`. The generated `api`/`server` modules are just
+* `FunctionReference` metadata, so Vite's granular module HMR re-imports the
+* changed `_generated/*` in place; this event is a non-destructive nudge that
+* lets open WebSocket subscriptions, optimistic state, the offline queue, and
+* form state survive a schema save.
+*
+* Kept in its own module (a single source of truth) so the codegen plugin —
+* whose sole export is the plugin factory — can reference it without becoming a
+* mixed default+named module, and so any future client-side listener can agree
+* on the exact string.
+*
+* There is no first-party client listener yet: `@lunora/client` / `@lunora/react`
+* ship as pre-bundled, side-effect-free dependencies where `import.meta.hot` is
+* `undefined` at runtime (Vite's dep optimizer), so a listener there would be
+* dead (and tree-shaken) code. A future app-local or codegen-emitted listener
+* can import this constant to re-validate active queries over the live socket.
+*/
+declare const LUNORA_API_UPDATED_EVENT = "lunora:api-updated";
+/**
 * 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.
+* Patches `process.stdout`/`process.stderr` fresh for each dev-server generation
+* and restores them when that server closes.
 */
 declare const logStreamPlugin: () => Plugin;
 /** The decision a {@link planViteRemoteBindings} call returns. */
@@ -264,23 +298,69 @@ declare const planViteRemoteBindings: (options: PlanViteRemoteOptions) => ViteRe
 /**
 * 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.
+* on and a temp config was materialized. A `configPath` the caller already set
+* wins (their explicit choice).
 *
-* 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.
+* Pure decision only — the serve-vs-build gate lives in
+* {@link remoteBindingsConfigPlugin}'s `config` hook, because the resolved Vite
+* `command` is unknown at plugin-factory time (when this runs). An eager serve
+* check here would always read `command` as undefined and strip `configPath`.
 */
-declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: () => boolean, plan: ViteRemotePlan) => CloudflarePluginOptions;
+declare const withRemoteBindings: (options: CloudflarePluginOptions, plan: ViteRemotePlan) => CloudflarePluginOptions;
+/**
+* A `enforce: "pre"` plugin whose `config` hook injects the materialized remote
+* temp config into the cloudflare plugin's `configPath` — but only on a `vite`
+* serve, never a production build (so the deployed worker is never affected).
+*
+* The deferral is the whole point: at plugin-factory time Vite has not yet told
+* us `serve` vs `build`, so the check must run in a `config` hook (where
+* `env.command` is known). It mutates the SAME options object handed to
+* `cloudflare()` in place — the cloudflare plugin reads `pluginConfig.configPath`
+* lazily inside its own `config` hook, which runs after this `enforce: "pre"`
+* one, so the injection takes effect. An eager factory-time serve check (the old
+* behaviour) always saw `command` undefined and silently dropped the path, so
+* remote bindings never activated on `vite dev`.
+*
+* When remote mode was requested but nothing materialized (no eligible binding,
+* no wrangler file, …), the plan's `reason` is logged so the degradation isn't
+* silent.
+*/
+declare const remoteBindingsConfigPlugin: (options: CloudflarePluginOptions, plan: ViteRemotePlan) => Plugin;
 /**
 * 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;
+/**
+* A `@visulima/vite-overlay` solution finder. Derived from the overlay's own
+* options type so the shape can't drift from the installed package. The overlay
+* runs every finder it's given (custom finders first, then its built-ins),
+* sorted by `priority` descending, and shows the first non-`undefined` result.
+*
+* Note: this type (and {@link Solution}) is re-exported from `@lunora/vite` and
+* intentionally tracks the installed `@visulima/vite-overlay` — if a future
+* overlay release changes the finder contract, that surfaces here as a compile
+* error rather than a silent drift.
+*/
+type SolutionFinder = NonNullable<OverlayPluginOptions["solutionFinders"]>[number];
+/** What a finder may return: a Markdown-rendered `{ header?, body }`, or `undefined` to defer. */
+type Solution = NonNullable<Awaited<ReturnType<SolutionFinder["handle"]>>>;
+/**
+* Lunora's solution finder for the dev error overlay. A single finder that
+* delegates to `@lunora/codegen`'s shared rule table (the same table the
+* standalone `lunora dev` CLI prints to the terminal) and returns the first
+* match — so one `priority` slot covers every Lunora rule and the overlay's
+* built-in finders still run for anything we don't recognize (we return
+* `undefined`).
+*
+* Priority is high so a Lunora-specific hint wins over the overlay's generic
+* finder for the same error; a user's own finder can still outrank it with a
+* higher `priority`.
+*/
+declare const lunoraSolutionFinder: SolutionFinder;
+/** The finders Lunora injects into the overlay by default. */
+declare const lunoraSolutionFinders: ReadonlyArray<SolutionFinder>;
 /** Dev-server path the studio SPA is served from. */
 declare const STUDIO_PATH = "/__lunora";
 /** Static asset routes the studio document references. */
@@ -358,6 +438,17 @@ declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[
 */
 declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
+* Resolve the `overlay` toggle into the overlay plugin's options — or `false` to
+* skip it. Lunora's solution finders are **prepended** so they run before the
+* overlay's built-ins; a user's own finders are appended and can still win per
+* error via a strictly higher `priority` (equal priority keeps Lunora first,
+* since the overlay sorts stably). Lunora also forwards both `error` AND `warn`
+* console calls by default (the overlay's own default is `["error"]` only) so
+* Lunora's branded `warn` advisories surface in the browser too — the user can
+* override `forwardedConsoleMethods`.
+*/
+declare const resolveOverlayOption: (overlay: LunoraPluginOptions["overlay"]) => false | OverlayPluginOptions;
+/**
 * Lunora Vite plugin. Returns a flat array of Vite plugins that:
 *
 * 1. Run `@lunora/codegen` on startup + on schema file changes.
@@ -370,5 +461,5 @@ declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) =>
 * 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 };
+declare const VERSION: string;
+export { CLASS_A_WIRING, type ClassAWiring, type CloudflarePluginOptions, DEV_WORKER_ENV_VALUE, DEV_WORKER_ENV_VAR, LUNORA_API_UPDATED_EVENT, LUNORA_WORKER_VIRTUAL_ID, type LunoraPluginOptions, type LunoraPlugins, type OverlayPluginOptions, type PlanViteRemoteOptions, type ResolvedLunoraPluginOptions, STUDIO_PATH, type Solution, type SolutionFinder, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, containerLogsPlugin, createCommandProbe, devStatePlugin, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, lunoraSolutionFinder, lunoraSolutionFinders, planViteRemoteBindings, remoteBindingsCleanupPlugin, remoteBindingsConfigPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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';
+export { type DetectedFramework, type FrameworkClass, type FrameworkDetection, type ReconcileCronsResult as ReconcileResult, detectFramework, reconcileWranglerCrons } from '@lunora/config';
 import { AddressInfo } from 'node:net';
 /** Options forwarded to `@cloudflare/vite-plugin`'s cloudflare plugin. */
 type CloudflarePluginOptions = Record<string, unknown>;
@@ -14,6 +14,15 @@ type CloudflarePluginOptions = Record<string, unknown>;
 */
 type OverlayPluginOptions = NonNullable<Parameters<typeof errorOverlayPlugin>[0]>;
 interface LunoraPluginOptions {
+  /**
+  * Allow a client-named NON-default shard / cross-shard fan-out WITHOUT an
+  * `authorizeShard`/`authorizeFanOut` callback. The auto-composed class-A worker
+  * (`virtual:lunora/worker`) default-denies such access (403 `FORBIDDEN_SHARD`);
+  * set this `true` to opt into open access — only safe when every table is
+  * protected by per-row RLS. A production sharded app should configure
+  * `authorizeShard` instead (via a hand-written class-B worker). Defaults to `false`.
+  */
+  allowUnauthenticatedShardAccess?: boolean;
   /**
   * Which machine-readable API spec(s) codegen emits into `_generated/`.
   * `"openapi"` (default) writes `openapi.json` (OpenAPI 3.1; RPC + REST),
@@ -43,6 +52,7 @@ interface LunoraPluginOptions {
 }
 /** Resolved options after merging defaults. */
 interface ResolvedLunoraPluginOptions {
+  allowUnauthenticatedShardAccess: boolean;
   apiSpec: NonNullable<CodegenOptions["apiSpec"]>;
   cloudflare: false | CloudflarePluginOptions;
   generatedDir: string;
@@ -63,37 +73,40 @@ type LunoraPlugins = Plugin[];
 * 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.
+* Dev-only plugin that tails the local dev containers' own stdout/stderr in the
+* Vite terminal.
 *
-* 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.
+* `@cloudflare/vite-plugin` builds and runs each declared container locally via
+* Docker (image `cloudflare-dev/&lt;class>:&lt;id>`) but only forwards the *worker's*
+* console — the container process's own output is otherwise invisible. This
+* plugin attaches to those Docker log streams (via `@lunora/config`'s
+* `streamContainerLogs`, which lazy-loads `dockerode`) and prints each line
+* through Vite's logger, branded and tagged `container:&lt;name>`.
 *
-* This intentionally writes the SAME `triggers.crons` shape the
-* `@lunora/config` validator accepts, so the wrangler validator never fights
-* the generated value.
+* A no-op when the project declares no containers (the common case): discovery
+* returns an empty list, so `dockerode` is never imported and no Docker work
+* starts. Set `LUNORA_CONTAINER_LOGS=0` to opt out. A missing/stopped Docker
+* engine degrades to a single warning rather than breaking dev.
 */
-declare const reconcileWranglerCrons: (projectRoot: string, cronTriggers: ReadonlyArray<string>) => ReconcileResult;
+declare const containerLogsPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
+/** Vite plugin (serve-only) that writes the dev-server state record on listen and clears it on close. */
+declare const devStatePlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
-* 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`.
+* Dev-only Vite plugin that prepares `.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`). Two steps, both shared
+* with `lunora dev` via `@lunora/config`.
+*
+* First, {@link ensureDevVariables}: when a `.dev.vars.example` exists, prompt
+* to generate `.dev.vars` from it with secrets auto-filled. Second,
+* {@link fillDevSecrets}: fill any empty/placeholder secret already in
+* `.dev.vars` (a `lunora add`-scaffolded project writes secrets blank) and
+* ensure `LUNORA_ADMIN_TOKEN` is present + generated — so the worker boots with
+* working secrets and the Studio authenticates without its login gate. No
+* prompt: it only generates locally-derivable values and never overwrites a real
+* one.
 *
 * Runs in `configResolved` (awaited by Vite) so it completes before the
 * Cloudflare plugin reads the file. Non-interactive runs decline silently.
@@ -198,7 +211,7 @@ declare const isAutoComposable: (context: LunoraPluginContext) => boolean;
 * 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;
+declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedImportBase: string, hasContainers?: boolean, useUmbrella?: boolean, allowUnauthenticatedShardAccess?: 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).
@@ -221,9 +234,30 @@ declare const buildWorkerEntrySource: (framework: DetectedFramework, generatedIm
 */
 declare const frameworkComposePlugin: (options: ResolvedLunoraPluginOptions, context: LunoraPluginContext) => Plugin;
 /**
+* The custom HMR event the Lunora Vite plugin sends on the client environment's
+* hot channel after a successful codegen run, in place of the old blanket
+* browser `full-reload`. The generated `api`/`server` modules are just
+* `FunctionReference` metadata, so Vite's granular module HMR re-imports the
+* changed `_generated/*` in place; this event is a non-destructive nudge that
+* lets open WebSocket subscriptions, optimistic state, the offline queue, and
+* form state survive a schema save.
+*
+* Kept in its own module (a single source of truth) so the codegen plugin —
+* whose sole export is the plugin factory — can reference it without becoming a
+* mixed default+named module, and so any future client-side listener can agree
+* on the exact string.
+*
+* There is no first-party client listener yet: `@lunora/client` / `@lunora/react`
+* ship as pre-bundled, side-effect-free dependencies where `import.meta.hot` is
+* `undefined` at runtime (Vite's dep optimizer), so a listener there would be
+* dead (and tree-shaken) code. A future app-local or codegen-emitted listener
+* can import this constant to re-validate active queries over the live socket.
+*/
+declare const LUNORA_API_UPDATED_EVENT = "lunora:api-updated";
+/**
 * 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.
+* Patches `process.stdout`/`process.stderr` fresh for each dev-server generation
+* and restores them when that server closes.
 */
 declare const logStreamPlugin: () => Plugin;
 /** The decision a {@link planViteRemoteBindings} call returns. */
@@ -264,23 +298,69 @@ declare const planViteRemoteBindings: (options: PlanViteRemoteOptions) => ViteRe
 /**
 * 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.
+* on and a temp config was materialized. A `configPath` the caller already set
+* wins (their explicit choice).
 *
-* 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.
+* Pure decision only — the serve-vs-build gate lives in
+* {@link remoteBindingsConfigPlugin}'s `config` hook, because the resolved Vite
+* `command` is unknown at plugin-factory time (when this runs). An eager serve
+* check here would always read `command` as undefined and strip `configPath`.
 */
-declare const withRemoteBindings: (options: CloudflarePluginOptions, isServe: () => boolean, plan: ViteRemotePlan) => CloudflarePluginOptions;
+declare const withRemoteBindings: (options: CloudflarePluginOptions, plan: ViteRemotePlan) => CloudflarePluginOptions;
+/**
+* A `enforce: "pre"` plugin whose `config` hook injects the materialized remote
+* temp config into the cloudflare plugin's `configPath` — but only on a `vite`
+* serve, never a production build (so the deployed worker is never affected).
+*
+* The deferral is the whole point: at plugin-factory time Vite has not yet told
+* us `serve` vs `build`, so the check must run in a `config` hook (where
+* `env.command` is known). It mutates the SAME options object handed to
+* `cloudflare()` in place — the cloudflare plugin reads `pluginConfig.configPath`
+* lazily inside its own `config` hook, which runs after this `enforce: "pre"`
+* one, so the injection takes effect. An eager factory-time serve check (the old
+* behaviour) always saw `command` undefined and silently dropped the path, so
+* remote bindings never activated on `vite dev`.
+*
+* When remote mode was requested but nothing materialized (no eligible binding,
+* no wrangler file, …), the plan's `reason` is logged so the degradation isn't
+* silent.
+*/
+declare const remoteBindingsConfigPlugin: (options: CloudflarePluginOptions, plan: ViteRemotePlan) => Plugin;
 /**
 * 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;
+/**
+* A `@visulima/vite-overlay` solution finder. Derived from the overlay's own
+* options type so the shape can't drift from the installed package. The overlay
+* runs every finder it's given (custom finders first, then its built-ins),
+* sorted by `priority` descending, and shows the first non-`undefined` result.
+*
+* Note: this type (and {@link Solution}) is re-exported from `@lunora/vite` and
+* intentionally tracks the installed `@visulima/vite-overlay` — if a future
+* overlay release changes the finder contract, that surfaces here as a compile
+* error rather than a silent drift.
+*/
+type SolutionFinder = NonNullable<OverlayPluginOptions["solutionFinders"]>[number];
+/** What a finder may return: a Markdown-rendered `{ header?, body }`, or `undefined` to defer. */
+type Solution = NonNullable<Awaited<ReturnType<SolutionFinder["handle"]>>>;
+/**
+* Lunora's solution finder for the dev error overlay. A single finder that
+* delegates to `@lunora/codegen`'s shared rule table (the same table the
+* standalone `lunora dev` CLI prints to the terminal) and returns the first
+* match — so one `priority` slot covers every Lunora rule and the overlay's
+* built-in finders still run for anything we don't recognize (we return
+* `undefined`).
+*
+* Priority is high so a Lunora-specific hint wins over the overlay's generic
+* finder for the same error; a user's own finder can still outrank it with a
+* higher `priority`.
+*/
+declare const lunoraSolutionFinder: SolutionFinder;
+/** The finders Lunora injects into the overlay by default. */
+declare const lunoraSolutionFinders: ReadonlyArray<SolutionFinder>;
 /** Dev-server path the studio SPA is served from. */
 declare const STUDIO_PATH = "/__lunora";
 /** Static asset routes the studio document references. */
@@ -358,6 +438,17 @@ declare const withWorkerStartupHint: (plugins: ReadonlyArray<Plugin>) => Plugin[
 */
 declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) => Plugin;
 /**
+* Resolve the `overlay` toggle into the overlay plugin's options — or `false` to
+* skip it. Lunora's solution finders are **prepended** so they run before the
+* overlay's built-ins; a user's own finders are appended and can still win per
+* error via a strictly higher `priority` (equal priority keeps Lunora first,
+* since the overlay sorts stably). Lunora also forwards both `error` AND `warn`
+* console calls by default (the overlay's own default is `["error"]` only) so
+* Lunora's branded `warn` advisories surface in the browser too — the user can
+* override `forwardedConsoleMethods`.
+*/
+declare const resolveOverlayOption: (overlay: LunoraPluginOptions["overlay"]) => false | OverlayPluginOptions;
+/**
 * Lunora Vite plugin. Returns a flat array of Vite plugins that:
 *
 * 1. Run `@lunora/codegen` on startup + on schema file changes.
@@ -370,5 +461,5 @@ declare const wranglerValidatorPlugin: (options: ResolvedLunoraPluginOptions) =>
 * 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 };
+declare const VERSION: string;
+export { CLASS_A_WIRING, type ClassAWiring, type CloudflarePluginOptions, DEV_WORKER_ENV_VALUE, DEV_WORKER_ENV_VAR, LUNORA_API_UPDATED_EVENT, LUNORA_WORKER_VIRTUAL_ID, type LunoraPluginOptions, type LunoraPlugins, type OverlayPluginOptions, type PlanViteRemoteOptions, type ResolvedLunoraPluginOptions, STUDIO_PATH, type Solution, type SolutionFinder, VERSION, type ViteRemotePlan, WORKER_STARTUP_HINT, augmentWorkerStartupError, buildStudioUrl, buildWorkerEntrySource, codegenPlugin, containerLogsPlugin, createCommandProbe, devStatePlugin, devVariablesPlugin, frameworkComposePlugin, isAutoComposable, isWorkerEntryEvalError, logStreamPlugin, lunora, lunoraSolutionFinder, lunoraSolutionFinders, planViteRemoteBindings, remoteBindingsCleanupPlugin, remoteBindingsConfigPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };

package/dist/index.mjs

@@ -1,22 +1,28 @@
+import { createRequire } from 'node:module';
 import { cloudflare } from '@cloudflare/vite-plugin';
 import errorOverlayPlugin from '@visulima/vite-overlay';
 import { detectAgentRules, claimAgentRulesHint, AGENT_RULES_HINT, detectFramework } from '@lunora/config';
-export { detectFramework } from '@lunora/config';
+export { detectFramework, reconcileWranglerCrons } from '@lunora/config';
 import { l as lunoraLine } from './packem_shared/log-BjO9EWah.mjs';
-import codegenPlugin from './packem_shared/codegenPlugin-MuvbqAP8.mjs';
-import devVariablesPlugin from './packem_shared/devVariablesPlugin-CVjkQay7.mjs';
+import codegenPlugin from './packem_shared/codegenPlugin-B8c38rky.mjs';
+import containerLogsPlugin from './packem_shared/containerLogsPlugin-DMssU3wb.mjs';
+import devStatePlugin from './packem_shared/devStatePlugin-DdjfMrhx.mjs';
+import devVariablesPlugin from './packem_shared/devVariablesPlugin-CDNSnvOP.mjs';
 import { createCommandProbe, withDevWorkerEnv } from './packem_shared/DEV_WORKER_ENV_VALUE-Coo6bgVz.mjs';
 export { DEV_WORKER_ENV_VALUE, DEV_WORKER_ENV_VAR } from './packem_shared/DEV_WORKER_ENV_VALUE-Coo6bgVz.mjs';
-import { frameworkComposePlugin } from './packem_shared/CLASS_A_WIRING-CZVcjgKo.mjs';
-export { CLASS_A_WIRING, LUNORA_WORKER_VIRTUAL_ID, buildWorkerEntrySource, isAutoComposable } from './packem_shared/CLASS_A_WIRING-CZVcjgKo.mjs';
-import logStreamPlugin from './packem_shared/logStreamPlugin-CqvZ17kd.mjs';
-import { planViteRemoteBindings, remoteBindingsCleanupPlugin, withRemoteBindings } from './packem_shared/planViteRemoteBindings-QN5ncUS1.mjs';
-import { studioPlugin } from './packem_shared/STUDIO_PATH-5ppCdBHa.mjs';
-export { STUDIO_PATH, buildStudioUrl } from './packem_shared/STUDIO_PATH-5ppCdBHa.mjs';
+import { frameworkComposePlugin } from './packem_shared/CLASS_A_WIRING-T1RohRZQ.mjs';
+export { CLASS_A_WIRING, LUNORA_WORKER_VIRTUAL_ID, buildWorkerEntrySource, isAutoComposable } from './packem_shared/CLASS_A_WIRING-T1RohRZQ.mjs';
+import logStreamPlugin from './packem_shared/logStreamPlugin-DeFzd_pC.mjs';
+import { planViteRemoteBindings, remoteBindingsCleanupPlugin, remoteBindingsConfigPlugin } from './packem_shared/planViteRemoteBindings-CRU90Bip.mjs';
+export { withRemoteBindings } from './packem_shared/planViteRemoteBindings-CRU90Bip.mjs';
+import { lunoraSolutionFinders } from './packem_shared/lunoraSolutionFinder-BKEAiUJP.mjs';
+export { lunoraSolutionFinder } from './packem_shared/lunoraSolutionFinder-BKEAiUJP.mjs';
+import { studioPlugin } from './packem_shared/STUDIO_PATH-U0eIaW1t.mjs';
+export { STUDIO_PATH, buildStudioUrl } from './packem_shared/STUDIO_PATH-U0eIaW1t.mjs';
 import { withWorkerStartupHint } from './packem_shared/WORKER_STARTUP_HINT-DhsXUW8k.mjs';
 export { WORKER_STARTUP_HINT, augmentWorkerStartupError, isWorkerEntryEvalError } from './packem_shared/WORKER_STARTUP_HINT-DhsXUW8k.mjs';
-import { wranglerValidatorPlugin } from './packem_shared/wranglerValidatorPlugin-CEoJEghS.mjs';
-export { reconcileWranglerCrons } from './packem_shared/reconcileWranglerCrons-PxGwfCp_.mjs';
+import { wranglerValidatorPlugin } from './packem_shared/wranglerValidatorPlugin-C5VWOD7N.mjs';
+export { default as LUNORA_API_UPDATED_EVENT } from './packem_shared/LUNORA_API_UPDATED_EVENT-BrkWk3rr.mjs';
 
 const agentRulesHintPlugin = (options) => {
   return {
@@ -81,6 +87,19 @@ const frameworkDetectPlugin = (options, context) => {
   };
 };
 
+const resolveOverlayOption = (overlay) => {
+  if (overlay === false) {
+    return false;
+  }
+  const userOverlay = overlay === true || overlay === void 0 ? {} : overlay;
+  return {
+    ...userOverlay,
+    // After the spread + nullish-coalesce so an explicit `undefined` from the
+    // user doesn't erase Lunora's default (the spread would otherwise win).
+    forwardedConsoleMethods: userOverlay.forwardedConsoleMethods ?? ["error", "warn"],
+    solutionFinders: [...lunoraSolutionFinders, ...userOverlay.solutionFinders ?? []]
+  };
+};
 const resolveOptions = (options) => {
   const input = options ?? {};
   const schemaDirectory = input.schemaDir ?? "lunora";
@@ -92,20 +111,13 @@ const resolveOptions = (options) => {
   } else {
     cloudflareOption = input.cloudflare;
   }
-  let overlayOption;
-  if (input.overlay === false) {
-    overlayOption = false;
-  } else if (input.overlay === true || input.overlay === void 0) {
-    overlayOption = {};
-  } else {
-    overlayOption = input.overlay;
-  }
   return {
+    allowUnauthenticatedShardAccess: input.allowUnauthenticatedShardAccess ?? false,
     apiSpec: input.apiSpec ?? "openapi",
     cloudflare: cloudflareOption,
     studio: input.studio ?? true,
     generatedDir: input.generatedDir ?? `${schemaDirectory}/_generated`,
-    overlay: overlayOption,
+    overlay: resolveOverlayOption(input.overlay),
     projectRoot: input.projectRoot ?? process.cwd(),
     schemaDir: schemaDirectory,
     validateWrangler: input.validateWrangler ?? true
@@ -128,6 +140,9 @@ const lunora = (options) => {
     devVariablesPlugin(resolved),
     codegenPlugin(resolved),
     logStreamPlugin(),
+    // Registers the running dev server in `.lunora/dev.json` so
+    // `lunora dev --background|stop|status|logs` manage Vite projects too.
+    devStatePlugin(resolved),
     agentRulesHintPlugin(resolved)
   ];
   if (resolved.studio) {
@@ -140,15 +155,19 @@ const lunora = (options) => {
     plugins.push(errorOverlayPlugin(resolved.overlay));
   }
   if (resolved.cloudflare !== false) {
+    plugins.push(containerLogsPlugin(resolved));
     const remotePlan = planViteRemoteBindings({ projectRoot: resolved.projectRoot });
-    if (remotePlan.enabled && remotePlan.configPath !== void 0) {
-      plugins.push(remoteBindingsCleanupPlugin(remotePlan.cleanup));
+    const cloudflareOptions = withDevWorkerEnv(resolved.cloudflare, isServe);
+    if (remotePlan.enabled) {
+      if (remotePlan.configPath !== void 0) {
+        plugins.push(remoteBindingsCleanupPlugin(remotePlan.cleanup));
+      }
+      plugins.push(remoteBindingsConfigPlugin(cloudflareOptions, remotePlan));
     }
-    const cloudflareOptions = withRemoteBindings(withDevWorkerEnv(resolved.cloudflare, isServe), isServe, remotePlan);
     plugins.push(...withWorkerStartupHint(cloudflare(cloudflareOptions)));
   }
   return plugins;
 };
-const VERSION = "0.0.0";
+const VERSION = createRequire(import.meta.url)("../package.json").version;
 
-export { VERSION, codegenPlugin, createCommandProbe, devVariablesPlugin, frameworkComposePlugin, logStreamPlugin, lunora, planViteRemoteBindings, remoteBindingsCleanupPlugin, studioPlugin, withDevWorkerEnv, withRemoteBindings, withWorkerStartupHint, wranglerValidatorPlugin };
+export { VERSION, codegenPlugin, containerLogsPlugin, createCommandProbe, devStatePlugin, devVariablesPlugin, frameworkComposePlugin, logStreamPlugin, lunora, lunoraSolutionFinders, planViteRemoteBindings, remoteBindingsCleanupPlugin, remoteBindingsConfigPlugin, resolveOverlayOption, studioPlugin, withDevWorkerEnv, withWorkerStartupHint, wranglerValidatorPlugin };