@moku-labs/worker 0.2.1 → 0.3.1

package/dist/cli.cjs

@@ -22,6 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 const require_storage = require("./storage-CgXl-dUA.cjs");
+let _moku_labs_common_cli = require("@moku-labs/common/cli");
 let node_child_process = require("node:child_process");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
@@ -691,58 +692,59 @@ const createCliApi = (ctx) => ({
 //#endregion
 //#region src/plugins/cli/handlers.ts
 /**
-* Builds the hook handlers that turn global deploy events into a live progress TUI
-* via ctx.log. Pure observers — print and return; never mutate state, never block
-* the deploy pipeline (fire-and-forget, spec/07 §3,§4).
+* Builds the hook handlers that turn global deploy events into a live progress TUI.
+* Each logs a clean, prefix-free message via `ctx.log`; the branded log sink (installed
+* by the cli plugin's onInit from `@moku-labs/common/cli`) adds the `›` marker, brand
+* color, and stderr routing. Pure observers — print and return; never mutate state,
+* never block the deploy pipeline (fire-and-forget, spec/07 §3,§4).
 *
 * @param ctx - CLI plugin context with injected log core API.
 * @returns Hook map for the three global deploy events.
 * @example
 * ```ts
 * const hooks = createCliHooks(ctx);
-* hooks["deploy:phase"]({ phase: "detect" }); // logs "> detect"
-* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "  + kv KV"
-* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // logs "done -> https://x.workers.dev"
+* hooks["deploy:phase"]({ phase: "detect" }); // logs "detect" → renders "  › detect"
+* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "kv KV" → "  › kv KV"
+* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // "deployed → https://x.workers.dev"
 * ```
 */
 const createCliHooks = (ctx) => ({
 	/**
-	* Print one line per pipeline phase: "> phase" or "> phase - detail".
+	* Log one clean line per pipeline phase: "phase" or "phase · detail".
 	*
 	* @param p - The deploy:phase event payload.
 	* @example
 	* ```ts
-	* handler({ phase: "detect" }); // "> detect"
-	* handler({ phase: "upload", detail: "3 files" }); // "> upload - 3 files"
+	* handler({ phase: "detect" }); // "detect"
+	* handler({ phase: "upload", detail: "3 files" }); // "upload · 3 files"
 	* ```
 	*/
 	"deploy:phase"(p) {
-		const detail = p.detail ? ` - ${p.detail}` : "";
-		ctx.log.info(`> ${p.phase}${detail}`);
+		ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
 	},
 	/**
-	* Print one indented line per provisioned resource: "  + kind name".
+	* Log one clean line per provisioned resource: "kind name".
 	*
 	* @param p - The provision:resource event payload.
 	* @example
 	* ```ts
-	* handler({ kind: "kv", name: "KV" }); // "  + kv KV"
+	* handler({ kind: "kv", name: "KV" }); // "kv KV"
 	* ```
 	*/
 	"provision:resource"(p) {
-		ctx.log.info(`  + ${p.kind} ${p.name}`);
+		ctx.log.info(`${p.kind} ${p.name}`);
 	},
 	/**
-	* Print the terminal success line with the deployed URL.
+	* Log the terminal success line with the deployed URL.
 	*
 	* @param p - The deploy:complete event payload.
 	* @example
 	* ```ts
-	* handler({ url: "https://my-worker.workers.dev" }); // "done -> https://my-worker.workers.dev"
+	* handler({ url: "https://my-worker.workers.dev" }); // "deployed → https://my-worker.workers.dev"
 	* ```
 	*/
 	"deploy:complete"(p) {
-		ctx.log.info(`done -> ${p.url}`);
+		ctx.log.info(`deployed → ${p.url}`);
 	}
 });
 /**
@@ -760,6 +762,10 @@ const createCliHooks = (ctx) => ({
 const cliPlugin = require_storage.createPlugin("cli", {
 	depends: [deployPlugin],
 	config: { port: 8787 },
+	onInit: (ctx) => {
+		ctx.log.clearSinks();
+		ctx.log.addSink((0, _moku_labs_common_cli.brandedSink)("info"));
+	},
 	api: (ctx) => createCliApi(ctx),
 	hooks: (ctx) => createCliHooks(ctx)
 });

package/dist/cli.mjs

@@ -1,4 +1,5 @@
 import { i as durableObjectsPlugin, n as queuesPlugin, o as d1Plugin, r as kvPlugin, t as storagePlugin, u as createPlugin } from "./storage-COo-F38H.mjs";
+import { brandedSink } from "@moku-labs/common/cli";
 import { spawn } from "node:child_process";
 import { readdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -667,58 +668,59 @@ const createCliApi = (ctx) => ({
 //#endregion
 //#region src/plugins/cli/handlers.ts
 /**
-* Builds the hook handlers that turn global deploy events into a live progress TUI
-* via ctx.log. Pure observers — print and return; never mutate state, never block
-* the deploy pipeline (fire-and-forget, spec/07 §3,§4).
+* Builds the hook handlers that turn global deploy events into a live progress TUI.
+* Each logs a clean, prefix-free message via `ctx.log`; the branded log sink (installed
+* by the cli plugin's onInit from `@moku-labs/common/cli`) adds the `›` marker, brand
+* color, and stderr routing. Pure observers — print and return; never mutate state,
+* never block the deploy pipeline (fire-and-forget, spec/07 §3,§4).
 *
 * @param ctx - CLI plugin context with injected log core API.
 * @returns Hook map for the three global deploy events.
 * @example
 * ```ts
 * const hooks = createCliHooks(ctx);
-* hooks["deploy:phase"]({ phase: "detect" }); // logs "> detect"
-* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "  + kv KV"
-* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // logs "done -> https://x.workers.dev"
+* hooks["deploy:phase"]({ phase: "detect" }); // logs "detect" → renders "  › detect"
+* hooks["provision:resource"]({ kind: "kv", name: "KV" }); // logs "kv KV" → "  › kv KV"
+* hooks["deploy:complete"]({ url: "https://x.workers.dev" }); // "deployed → https://x.workers.dev"
 * ```
 */
 const createCliHooks = (ctx) => ({
 	/**
-	* Print one line per pipeline phase: "> phase" or "> phase - detail".
+	* Log one clean line per pipeline phase: "phase" or "phase · detail".
 	*
 	* @param p - The deploy:phase event payload.
 	* @example
 	* ```ts
-	* handler({ phase: "detect" }); // "> detect"
-	* handler({ phase: "upload", detail: "3 files" }); // "> upload - 3 files"
+	* handler({ phase: "detect" }); // "detect"
+	* handler({ phase: "upload", detail: "3 files" }); // "upload · 3 files"
 	* ```
 	*/
 	"deploy:phase"(p) {
-		const detail = p.detail ? ` - ${p.detail}` : "";
-		ctx.log.info(`> ${p.phase}${detail}`);
+		ctx.log.info(p.detail ? `${p.phase} · ${p.detail}` : p.phase);
 	},
 	/**
-	* Print one indented line per provisioned resource: "  + kind name".
+	* Log one clean line per provisioned resource: "kind name".
 	*
 	* @param p - The provision:resource event payload.
 	* @example
 	* ```ts
-	* handler({ kind: "kv", name: "KV" }); // "  + kv KV"
+	* handler({ kind: "kv", name: "KV" }); // "kv KV"
 	* ```
 	*/
 	"provision:resource"(p) {
-		ctx.log.info(`  + ${p.kind} ${p.name}`);
+		ctx.log.info(`${p.kind} ${p.name}`);
 	},
 	/**
-	* Print the terminal success line with the deployed URL.
+	* Log the terminal success line with the deployed URL.
 	*
 	* @param p - The deploy:complete event payload.
 	* @example
 	* ```ts
-	* handler({ url: "https://my-worker.workers.dev" }); // "done -> https://my-worker.workers.dev"
+	* handler({ url: "https://my-worker.workers.dev" }); // "deployed → https://my-worker.workers.dev"
 	* ```
 	*/
 	"deploy:complete"(p) {
-		ctx.log.info(`done -> ${p.url}`);
+		ctx.log.info(`deployed → ${p.url}`);
 	}
 });
 /**
@@ -736,6 +738,10 @@ const createCliHooks = (ctx) => ({
 const cliPlugin = createPlugin("cli", {
 	depends: [deployPlugin],
 	config: { port: 8787 },
+	onInit: (ctx) => {
+		ctx.log.clearSinks();
+		ctx.log.addSink(brandedSink("info"));
+	},
 	api: (ctx) => createCliApi(ctx),
 	hooks: (ctx) => createCliHooks(ctx)
 });

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

@@ -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

@@ -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.2.1",
+  "version": "0.3.1",
   "description": "Cloudflare Worker framework for Moku — Durable Objects, Queues, R2, D1, and KV plugins that compose with Moku Web.",
   "repository": {
     "type": "git",
@@ -62,7 +62,7 @@
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
   "dependencies": {
-    "@moku-labs/common": "0.1.1",
+    "@moku-labs/common": "0.2.0",
     "@moku-labs/core": "0.1.4"
   },
   "devDependencies": {