@moku-labs/worker 0.3.0 → 0.4.0

package/dist/{config-Bj3GUJT_.d.mts → config-50jmPyMv.d.mts}

@@ -33,6 +33,15 @@ type WorkerEvents = {
     kind: "kv" | "r2" | "d1" | "queue" | "do";
     name: string;
   };
+  "provision:plan": {
+    exists: number;
+    missing: number;
+    account: string;
+  };
+  "provision:skip": {
+    kind: "kv" | "r2" | "d1" | "queue" | "do";
+    name: string;
+  };
 };
 /**
  * Worker-bound plugin context for Layer-3 consumer plugins. Aliases the core

package/dist/index.cjs

@@ -482,7 +482,90 @@ const serverPlugin = require_storage.createPlugin("server", {
 	},
 	helpers: { endpoint }
 });
-const { createApp, createPlugin } = require_storage.createCore(require_storage.coreConfig, { plugins: [require_storage.bindingsPlugin, serverPlugin] });
+//#endregion
+//#region src/index.ts
+/**
+* @file `@moku-labs/worker` — server-side Cloudflare Workers app + deploy framework on `@moku-labs/core`.
+*
+* The package root exports the bound {@link createApp} factory (the Layer-3 entry
+* point), {@link createPlugin} for consumer plugins, every runtime plugin instance,
+* the `server`/`durable-objects` helpers, and the framework types. Node-only tooling
+* (`deploy`, `cli`) ships from the separate `@moku-labs/worker/cli` entry, never here.
+*
+* `createApp(options?)` boots a fully-typed, synchronous, per-isolate app. The
+* framework defaults `[logPlugin, envPlugin, stagePlugin, bindingsPlugin, serverPlugin]`
+* are applied first, then the `options` below are shallow-merged on top:
+*
+* - `config` — `Partial<WorkerConfig>`; defaults `{ stage: "production", name: "moku-worker", compatibilityDate: "" }`.
+*   `config.stage` is the single stage source: the framework mirrors it into the `stage` core
+*   plugin so `ctx.stage.*` / `app.stage.*` stay in lockstep with `ctx.global.stage` (see {@link createApp}).
+* - `pluginConfigs` — per-plugin config overrides keyed by plugin name (e.g. `server.endpoints`, `bindings.required`); default `{}`.
+* - `plugins` — extra `PluginInstance[]` appended to the defaults; default `[]`. Do NOT re-list a default plugin.
+* - `onReady` — optional `(app) => void`, runs after every plugin's `onInit`.
+* - `onError` — optional `(error) => void` boot/lifecycle error handler.
+* - `onStart` / `onStop` — optional `() => void | Promise<void>` runtime lifecycle hooks (`app.start()` / `app.stop()`).
+*
+* Re-listing a default plugin name in `plugins` throws
+* `TypeError: [moku-worker] Duplicate plugin name: "<name>"` — `bindings` and `server`
+* are already wired, so consumers list only the resource plugins they add (`kv`, `d1`, …).
+*
+* Minimal HTTP Worker (shape taken from the server integration test):
+*
+* ```typescript
+* import { createApp, endpoint } from "@moku-labs/worker";
+*
+* export const app = createApp({
+*   config: { name: "my-worker", compatibilityDate: "2024-09-23" },
+*   pluginConfigs: {
+*     server: { endpoints: [endpoint("/health").get(() => new Response("ok"))] }
+*   }
+* });
+*
+* // worker.ts — the default export is hand-assembled; no plugin produces it.
+* export default {
+*   fetch: (request: Request, env: Record<string, unknown>, ctx: ExecutionContext) =>
+*     app.server.handle(request, env, ctx)
+* } satisfies ExportedHandler;
+* ```
+*/
+const framework = require_storage.createCore(require_storage.coreConfig, { plugins: [require_storage.bindingsPlugin, serverPlugin] });
+const { createPlugin } = framework;
+/** The core-bound app factory; wrapped by {@link createApp} to bridge `config.stage`. */
+const boundCreateApp = framework.createApp;
+/**
+* Boots a fully-typed, synchronous, per-isolate Worker app — the Layer-3 entry point.
+*
+* Wraps the core-bound factory to BRIDGE the single consumer-facing `config.stage`
+* into the `stage` core plugin's own config, so the typed accessors
+* (`ctx.stage.isDev()` / `app.stage.current()` / …) can never diverge from the
+* global `ctx.global.stage`. Global config and core-plugin config resolve on two
+* SEPARATE cascades (spec/05 §1b), and a core plugin cannot read global config (its
+* context is `{ config, state }` only — spec/02 §6). `createApp` is the only layer
+* that sees the consumer's chosen stage, so it mirrors `config.stage` into the stage
+* plugin's level-4 `pluginConfigs` override (`WorkerConfig.stage → pluginConfigs.stage.stage`).
+* When `config.stage` is omitted, the global config and the stage plugin both fall back
+* to their identical `"production"` default. See the module JSDoc above for the full
+* options/defaults table.
+*
+* @param options - The createApp options (`config`, `pluginConfigs`, `plugins`, and lifecycle callbacks).
+* @returns The initialized app — every plugin's `onInit` has already run.
+* @example
+* ```typescript
+* const app = createApp({ config: { stage: "development", name: "my-worker" } });
+* app.stage.isDev(); // true — bridged from config.stage
+* ```
+*/
+const createApp = (options) => {
+	const explicitStage = options?.config?.stage;
+	if (explicitStage === void 0) return boundCreateApp(options);
+	return boundCreateApp({
+		...options,
+		pluginConfigs: {
+			...options?.pluginConfigs,
+			stage: { stage: explicitStage }
+		}
+	});
+};
 //#endregion
 exports.bindingsPlugin = require_storage.bindingsPlugin;
 exports.createApp = createApp;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-Bj3GUJT_.cjs";
-import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
+import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-50jmPyMv.cjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
+import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
 //#region \0rolldown/runtime.js
 declare namespace types_d_exports {
@@ -994,38 +994,64 @@ declare const stagePlugin: import("@moku-labs/core").CorePluginInstance<"stage",
 }>;
 //#endregion
 //#region src/index.d.ts
-declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
-    "server:matched": {
-      path: string;
-      method: string;
-    };
-  }> & {
-    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
-  }) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
-    "server:matched": {
-      path: string;
-      method: string;
-    };
-  }> & {
-    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
-  }) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>>, createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<WorkerConfig, WorkerEvents, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<WorkerConfig, WorkerEvents, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>>;
+/** The core-bound app factory; wrapped by {@link createApp} to bridge `config.stage`. */
+declare const boundCreateApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+}> & {
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
+}) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+}> & {
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
+}) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>>;
+/**
+ * Boots a fully-typed, synchronous, per-isolate Worker app — the Layer-3 entry point.
+ *
+ * Wraps the core-bound factory to BRIDGE the single consumer-facing `config.stage`
+ * into the `stage` core plugin's own config, so the typed accessors
+ * (`ctx.stage.isDev()` / `app.stage.current()` / …) can never diverge from the
+ * global `ctx.global.stage`. Global config and core-plugin config resolve on two
+ * SEPARATE cascades (spec/05 §1b), and a core plugin cannot read global config (its
+ * context is `{ config, state }` only — spec/02 §6). `createApp` is the only layer
+ * that sees the consumer's chosen stage, so it mirrors `config.stage` into the stage
+ * plugin's level-4 `pluginConfigs` override (`WorkerConfig.stage → pluginConfigs.stage.stage`).
+ * When `config.stage` is omitted, the global config and the stage plugin both fall back
+ * to their identical `"production"` default. See the module JSDoc above for the full
+ * options/defaults table.
+ *
+ * @param options - The createApp options (`config`, `pluginConfigs`, `plugins`, and lifecycle callbacks).
+ * @returns The initialized app — every plugin's `onInit` has already run.
+ * @example
+ * ```typescript
+ * const app = createApp({ config: { stage: "development", name: "my-worker" } });
+ * app.stage.isDev(); // true — bridged from config.stage
+ * ```
+ */
+declare const createApp: typeof boundCreateApp;
 //#endregion
 export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type PluginCtx, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, type WorkerPluginCtx, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-Bj3GUJT_.mjs";
+import { i as WorkerPluginCtx, n as WorkerEnv, r as WorkerEvents, t as WorkerConfig } from "./config-50jmPyMv.mjs";
 import { envPlugin, logPlugin } from "@moku-labs/common";
 import { PluginCtx, PluginCtx as PluginCtx$1, PluginInstance } from "@moku-labs/core";
 
@@ -994,38 +994,64 @@ declare const stagePlugin: import("@moku-labs/core").CorePluginInstance<"stage",
 }>;
 //#endregion
 //#region src/index.d.ts
-declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
-    "server:matched": {
-      path: string;
-      method: string;
-    };
-  }> & {
-    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
-  }) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
-    "server:matched": {
-      path: string;
-      method: string;
-    };
-  }> & {
-    endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
-  }) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>>, createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<WorkerConfig, WorkerEvents, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
-    stage: "production" | "development" | "test";
-  }, Record<string, never>, {
-    isDev: () => boolean;
-    isProduction: () => boolean;
-    current: () => "production" | "development" | "test";
-  }>]>>;
+declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<WorkerConfig, WorkerEvents, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>>;
+/** The core-bound app factory; wrapped by {@link createApp} to bridge `config.stage`. */
+declare const boundCreateApp: <const ExtraPlugins extends readonly import("@moku-labs/core").AnyPluginInstance[] = readonly []>(options?: import("@moku-labs/core").CreateAppOptions<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+}> & {
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
+}) | ExtraPlugins[number], [...ExtraPlugins], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>> | undefined) => import("@moku-labs/core").App<WorkerConfig, WorkerEvents, (import("@moku-labs/core").PluginInstance<"bindings", Config$4, Record<string, never>, BindingsApi, {}> & Record<never, never>) | (import("@moku-labs/core").PluginInstance<"server", ServerConfig, ServerState, Api$3, {
+  "server:matched": {
+    path: string;
+    method: string;
+  };
+}> & {
+  endpoint: <Path extends string>(path: Path) => EndpointBuilder<Path>;
+}) | ExtraPlugins[number], import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>, import("@moku-labs/core").CorePluginInstance<"stage", {
+  stage: "production" | "development" | "test";
+}, Record<string, never>, {
+  isDev: () => boolean;
+  isProduction: () => boolean;
+  current: () => "production" | "development" | "test";
+}>]>>;
+/**
+ * Boots a fully-typed, synchronous, per-isolate Worker app — the Layer-3 entry point.
+ *
+ * Wraps the core-bound factory to BRIDGE the single consumer-facing `config.stage`
+ * into the `stage` core plugin's own config, so the typed accessors
+ * (`ctx.stage.isDev()` / `app.stage.current()` / …) can never diverge from the
+ * global `ctx.global.stage`. Global config and core-plugin config resolve on two
+ * SEPARATE cascades (spec/05 §1b), and a core plugin cannot read global config (its
+ * context is `{ config, state }` only — spec/02 §6). `createApp` is the only layer
+ * that sees the consumer's chosen stage, so it mirrors `config.stage` into the stage
+ * plugin's level-4 `pluginConfigs` override (`WorkerConfig.stage → pluginConfigs.stage.stage`).
+ * When `config.stage` is omitted, the global config and the stage plugin both fall back
+ * to their identical `"production"` default. See the module JSDoc above for the full
+ * options/defaults table.
+ *
+ * @param options - The createApp options (`config`, `pluginConfigs`, `plugins`, and lifecycle callbacks).
+ * @returns The initialized app — every plugin's `onInit` has already run.
+ * @example
+ * ```typescript
+ * const app = createApp({ config: { stage: "development", name: "my-worker" } });
+ * app.stage.isDev(); // true — bridged from config.stage
+ * ```
+ */
+declare const createApp: typeof boundCreateApp;
 //#endregion
 export { type types_d_exports as Bindings, type types_d_exports$1 as D1, type types_d_exports$2 as DurableObjects, type PluginCtx, type types_d_exports$3 as Queues, type types_d_exports$4 as Server, type StageApi, type types_d_exports$5 as Storage, type WorkerConfig, type WorkerEnv, type WorkerEvents, type WorkerPluginCtx, bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };

package/dist/index.mjs

@@ -481,6 +481,89 @@ const serverPlugin = createPlugin$1("server", {
 	},
 	helpers: { endpoint }
 });
-const { createApp, createPlugin } = createCore(coreConfig, { plugins: [bindingsPlugin, serverPlugin] });
+//#endregion
+//#region src/index.ts
+/**
+* @file `@moku-labs/worker` — server-side Cloudflare Workers app + deploy framework on `@moku-labs/core`.
+*
+* The package root exports the bound {@link createApp} factory (the Layer-3 entry
+* point), {@link createPlugin} for consumer plugins, every runtime plugin instance,
+* the `server`/`durable-objects` helpers, and the framework types. Node-only tooling
+* (`deploy`, `cli`) ships from the separate `@moku-labs/worker/cli` entry, never here.
+*
+* `createApp(options?)` boots a fully-typed, synchronous, per-isolate app. The
+* framework defaults `[logPlugin, envPlugin, stagePlugin, bindingsPlugin, serverPlugin]`
+* are applied first, then the `options` below are shallow-merged on top:
+*
+* - `config` — `Partial<WorkerConfig>`; defaults `{ stage: "production", name: "moku-worker", compatibilityDate: "" }`.
+*   `config.stage` is the single stage source: the framework mirrors it into the `stage` core
+*   plugin so `ctx.stage.*` / `app.stage.*` stay in lockstep with `ctx.global.stage` (see {@link createApp}).
+* - `pluginConfigs` — per-plugin config overrides keyed by plugin name (e.g. `server.endpoints`, `bindings.required`); default `{}`.
+* - `plugins` — extra `PluginInstance[]` appended to the defaults; default `[]`. Do NOT re-list a default plugin.
+* - `onReady` — optional `(app) => void`, runs after every plugin's `onInit`.
+* - `onError` — optional `(error) => void` boot/lifecycle error handler.
+* - `onStart` / `onStop` — optional `() => void | Promise<void>` runtime lifecycle hooks (`app.start()` / `app.stop()`).
+*
+* Re-listing a default plugin name in `plugins` throws
+* `TypeError: [moku-worker] Duplicate plugin name: "<name>"` — `bindings` and `server`
+* are already wired, so consumers list only the resource plugins they add (`kv`, `d1`, …).
+*
+* Minimal HTTP Worker (shape taken from the server integration test):
+*
+* ```typescript
+* import { createApp, endpoint } from "@moku-labs/worker";
+*
+* export const app = createApp({
+*   config: { name: "my-worker", compatibilityDate: "2024-09-23" },
+*   pluginConfigs: {
+*     server: { endpoints: [endpoint("/health").get(() => new Response("ok"))] }
+*   }
+* });
+*
+* // worker.ts — the default export is hand-assembled; no plugin produces it.
+* export default {
+*   fetch: (request: Request, env: Record<string, unknown>, ctx: ExecutionContext) =>
+*     app.server.handle(request, env, ctx)
+* } satisfies ExportedHandler;
+* ```
+*/
+const framework = createCore(coreConfig, { plugins: [bindingsPlugin, serverPlugin] });
+const { createPlugin } = framework;
+/** The core-bound app factory; wrapped by {@link createApp} to bridge `config.stage`. */
+const boundCreateApp = framework.createApp;
+/**
+* Boots a fully-typed, synchronous, per-isolate Worker app — the Layer-3 entry point.
+*
+* Wraps the core-bound factory to BRIDGE the single consumer-facing `config.stage`
+* into the `stage` core plugin's own config, so the typed accessors
+* (`ctx.stage.isDev()` / `app.stage.current()` / …) can never diverge from the
+* global `ctx.global.stage`. Global config and core-plugin config resolve on two
+* SEPARATE cascades (spec/05 §1b), and a core plugin cannot read global config (its
+* context is `{ config, state }` only — spec/02 §6). `createApp` is the only layer
+* that sees the consumer's chosen stage, so it mirrors `config.stage` into the stage
+* plugin's level-4 `pluginConfigs` override (`WorkerConfig.stage → pluginConfigs.stage.stage`).
+* When `config.stage` is omitted, the global config and the stage plugin both fall back
+* to their identical `"production"` default. See the module JSDoc above for the full
+* options/defaults table.
+*
+* @param options - The createApp options (`config`, `pluginConfigs`, `plugins`, and lifecycle callbacks).
+* @returns The initialized app — every plugin's `onInit` has already run.
+* @example
+* ```typescript
+* const app = createApp({ config: { stage: "development", name: "my-worker" } });
+* app.stage.isDev(); // true — bridged from config.stage
+* ```
+*/
+const createApp = (options) => {
+	const explicitStage = options?.config?.stage;
+	if (explicitStage === void 0) return boundCreateApp(options);
+	return boundCreateApp({
+		...options,
+		pluginConfigs: {
+			...options?.pluginConfigs,
+			stage: { stage: explicitStage }
+		}
+	});
+};
 //#endregion
 export { bindingsPlugin, createApp, createPlugin, d1Plugin, defineDurableObject, durableObjectsPlugin, endpoint, envPlugin, kvPlugin, logPlugin, queuesPlugin, serverPlugin, stagePlugin, storagePlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moku-labs/worker",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Cloudflare Worker framework for Moku — Durable Objects, Queues, R2, D1, and KV plugins that compose with Moku Web.",
   "repository": {
     "type": "git",