@ekairos/story 1.21.36-beta.0 → 1.21.38-beta.0

package/dist/ekairos.config.js

@@ -1,4 +1,15 @@
 import { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, } from "./story.config";
+const GLOBAL_EKAIROS_CONFIG = Symbol.for("@ekairos/story.ekairosConfig");
+function setGlobalEkairosConfig(config) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ;
+        globalThis[GLOBAL_EKAIROS_CONFIG] = config;
+    }
+    catch {
+        // ignore
+    }
+}
 /**
  * Creates a small "framework-style" config object that can be executed in the step runtime.
  *
@@ -7,7 +18,7 @@ import { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeCo
  */
 export function createEkairosConfig(params) {
     const stories = params.stories ?? [];
-    return {
+    const config = {
         stories,
         runtime: params.runtime,
         setup() {
@@ -23,4 +34,8 @@ export function createEkairosConfig(params) {
                 s.register();
         },
     };
+    // Register globally (process-level) so libraries/steps can access it transparently.
+    // Note: This does NOT call `setup()` (no runtime side-effects).
+    setGlobalEkairosConfig(config);
+    return config;
 }

package/dist/next.d.ts

@@ -0,0 +1,22 @@
+export type NextConfigLike = {
+    webpack?: (config: any, options: any) => any;
+};
+type WithEkairosRuntimeOptions = {
+    /**
+     * Module that registers the story runtime factory (usually `./src/ekairos.ts`).
+     *
+     * This module should be **runtime-only** (server) and should only register factories/config,
+     * not create network/db clients eagerly.
+     */
+    bootstrapModule: string;
+};
+/**
+ * Next.js helper to ensure the story runtime factory is registered in *every* server bundle.
+ *
+ * This is the most explicit & DX-friendly option:
+ * - No per-route/workflow imports
+ * - No "magic" root bootstrap file
+ * - Works for step runtimes because the server entry will always evaluate your bootstrap module
+ */
+export declare function withEkairosRuntime(nextConfig: NextConfigLike, opts: WithEkairosRuntimeOptions): NextConfigLike;
+export {};

package/dist/next.js

@@ -0,0 +1,61 @@
+import { createRequire } from "node:module";
+function injectBootstrapIntoEntries(entries, bootstrap) {
+    for (const key of Object.keys(entries)) {
+        const entry = entries[key];
+        // Webpack 5 "EntryDescription" form
+        if (entry && typeof entry === "object" && !Array.isArray(entry) && "import" in entry) {
+            const imports = entry.import;
+            if (Array.isArray(imports)) {
+                if (!imports.includes(bootstrap))
+                    entry.import = [bootstrap, ...imports];
+            }
+            else if (typeof imports === "string") {
+                if (imports !== bootstrap)
+                    entry.import = [bootstrap, imports];
+            }
+            continue;
+        }
+        if (Array.isArray(entry)) {
+            if (!entry.includes(bootstrap))
+                entries[key] = [bootstrap, ...entry];
+            continue;
+        }
+        if (typeof entry === "string") {
+            if (entry !== bootstrap)
+                entries[key] = [bootstrap, entry];
+        }
+    }
+}
+/**
+ * Next.js helper to ensure the story runtime factory is registered in *every* server bundle.
+ *
+ * This is the most explicit & DX-friendly option:
+ * - No per-route/workflow imports
+ * - No "magic" root bootstrap file
+ * - Works for step runtimes because the server entry will always evaluate your bootstrap module
+ */
+export function withEkairosRuntime(nextConfig, opts) {
+    const bootstrapModule = opts.bootstrapModule;
+    const userWebpack = nextConfig.webpack;
+    return {
+        ...nextConfig,
+        webpack: (config, options) => {
+            const out = userWebpack ? userWebpack(config, options) : config;
+            if (!options?.isServer)
+                return out;
+            const req = createRequire(import.meta.url);
+            const contextDir = (out && out.context) || process.cwd();
+            // Resolve relative to the app project (webpack context), not to this package.
+            const resolvedBootstrap = req.resolve(bootstrapModule, {
+                paths: [contextDir],
+            });
+            const originalEntry = out.entry;
+            out.entry = async () => {
+                const entries = typeof originalEntry === "function" ? await originalEntry() : originalEntry;
+                injectBootstrapIntoEntries(entries, resolvedBootstrap);
+                return entries;
+            };
+            return out;
+        },
+    };
+}

package/dist/runtime.d.ts

@@ -8,5 +8,6 @@
  * - Do NOT import this entrypoint from client/browser code.
  * - Keep `@ekairos/story` main entrypoint safe to import from schema/domain modules.
  */
-export { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, resolveStoryRuntime, type StoryEnvironment, type StoryRuntime, type StoryRuntimeResolver, } from "./story.config";
+export { configureStoryRuntime, configureStoryRuntimeBootstrap, getEkairosConfig, isStoryRuntimeConfigured, resolveStoryRuntime, type StoryEnvironment, type StoryRuntime, type StoryRuntimeResolver, } from "./story.config";
 export { createEkairosConfig, type EkairosConfig, type RegistrableStory, } from "./ekairos.config";
+export { withEkairosRuntime } from "./next";

package/dist/runtime.js

@@ -8,5 +8,6 @@
  * - Do NOT import this entrypoint from client/browser code.
  * - Keep `@ekairos/story` main entrypoint safe to import from schema/domain modules.
  */
-export { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, resolveStoryRuntime, } from "./story.config";
+export { configureStoryRuntime, configureStoryRuntimeBootstrap, getEkairosConfig, isStoryRuntimeConfigured, resolveStoryRuntime, } from "./story.config";
 export { createEkairosConfig, } from "./ekairos.config";
+export { withEkairosRuntime } from "./next";

package/dist/story.config.d.ts

@@ -1,4 +1,5 @@
 import type { StoryStore } from "./story.store";
+import type { EkairosConfig } from "./ekairos.config";
 /**
  * ## story.config.ts
  *
@@ -16,6 +17,7 @@ export type StoryRuntime = {
     store: StoryStore;
 };
 export type StoryRuntimeResolver<Env extends StoryEnvironment = StoryEnvironment> = (env: Env) => Promise<StoryRuntime> | StoryRuntime;
+export declare function getEkairosConfig(): EkairosConfig | null;
 /**
  * Optional global bootstrap hook for step runtimes.
  *

package/dist/story.config.js

@@ -1,12 +1,37 @@
-import { pathToFileURL } from "node:url";
-import { join } from "node:path";
 let runtimeResolver = null;
+const GLOBAL_RUNTIME_RESOLVER = Symbol.for("@ekairos/story.runtimeResolver");
+const GLOBAL_RUNTIME_BOOTSTRAP = Symbol.for("@ekairos/story.runtimeBootstrap");
+const GLOBAL_EKAIROS_CONFIG = Symbol.for("@ekairos/story.ekairosConfig");
+function getGlobal(key) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const v = globalThis?.[key];
+        return v ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function setGlobal(key, value) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ;
+        globalThis[key] = value;
+    }
+    catch {
+        // ignore
+    }
+}
 function getRuntimeResolver() {
-    return runtimeResolver;
+    return runtimeResolver ?? getGlobal(GLOBAL_RUNTIME_RESOLVER);
+}
+export function getEkairosConfig() {
+    return getGlobal(GLOBAL_EKAIROS_CONFIG);
 }
 let runtimeBootstrap = null;
 export function configureStoryRuntimeBootstrap(bootstrap) {
     runtimeBootstrap = bootstrap;
+    setGlobal(GLOBAL_RUNTIME_BOOTSTRAP, bootstrap);
 }
 /**
  * Configure the story runtime resolver (global).
@@ -16,6 +41,7 @@ export function configureStoryRuntimeBootstrap(bootstrap) {
  */
 export function configureStoryRuntime(resolver) {
     runtimeResolver = resolver;
+    setGlobal(GLOBAL_RUNTIME_RESOLVER, runtimeResolver);
 }
 export function isStoryRuntimeConfigured() {
     return Boolean(runtimeResolver);
@@ -23,45 +49,15 @@ export function isStoryRuntimeConfigured() {
 export async function resolveStoryRuntime(env) {
     if (!getRuntimeResolver()) {
         // Best-effort: allow the step runtime to self-bootstrap once.
-        if (runtimeBootstrap) {
-            await runtimeBootstrap();
-        }
-        // Convention bootstrap (portable, runtime-resolvable):
-        // If the host app provides an `ekairos.bootstrap.js` at the project root, we can load it
-        // from the step runtime using a file URL. This avoids relying on bundler-only aliases.
+        const bootstrap = runtimeBootstrap ?? getGlobal(GLOBAL_RUNTIME_BOOTSTRAP);
+        if (bootstrap)
+            await bootstrap();
+        // Transparent fallback: if the host app created an `ekairosConfig` (via createEkairosConfig),
+        // it is available process-wide. We only call setup() when runtime is actually needed.
         if (!getRuntimeResolver()) {
-            const cwd = typeof process !== "undefined" && process.cwd ? process.cwd() : null;
-            if (cwd) {
-                const candidates = [
-                    "ekairos.bootstrap.js",
-                    "ekairos.bootstrap.cjs",
-                    "ekairos.bootstrap.mjs",
-                ];
-                for (const filename of candidates) {
-                    try {
-                        await import(pathToFileURL(join(cwd, filename)).href);
-                        break;
-                    }
-                    catch {
-                        // ignore
-                    }
-                }
-            }
-        }
-        // Convention bootstrap (Next.js / monorepo apps):
-        // If the app exposes `src/ekairos.ts` and uses the `@/` alias, loading that module will
-        // run `ekairosConfig.setup()` which configures the resolver + bootstrap hook.
-        //
-        // This is intentionally ONLY attempted when runtime is missing, and is safe as long as
-        // `story.config` is not part of client bundles (see `@ekairos/story/runtime`).
-        if (!getRuntimeResolver()) {
-            try {
-                // @ts-expect-error - optional, app-provided convention module
-                await import("@/ekairos");
-            }
-            catch {
-                // ignore: module missing / alias not configured
-            }
+            const cfg = getEkairosConfig();
+            if (cfg?.setup)
+                cfg.setup();
         }
         // If bootstrap succeeded, proceed.
         const resolver = getRuntimeResolver();
@@ -70,11 +66,8 @@ export async function resolveStoryRuntime(env) {
         throw new Error([
             "Story runtime is not configured.",
             "",
-            "Convention:",
-            "- Create an app-level `ekairos.ts` that exports `ekairosConfig = createEkairosConfig({ runtime })`",
-            "- Ensure `ekairosConfig.setup()` runs in the step runtime (module load / worker boot).",
-            "",
-            "If you already have that file, ensure it is evaluated in the step runtime before calling story store steps.",
+            "Ensure your app registers a story runtime factory (global) in the step runtime,",
+            "before calling store steps.",
         ].join("\n"));
     }
     return await getRuntimeResolver()(env);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/story",
-  "version": "1.21.36-beta.0",
+  "version": "1.21.38-beta.0",
   "description": "Pulzar Story - Workflow-based AI Stories",
   "type": "module",
   "main": "dist/index.js",
@@ -28,6 +28,11 @@
       "import": "./dist/runtime.js",
       "default": "./dist/runtime.js"
     },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "default": "./dist/next.js"
+    },
     "./instant": {
       "types": "./dist/stores/instant.store.d.ts",
       "import": "./dist/stores/instant.store.js",
@@ -43,7 +48,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.52",
-    "@ekairos/domain": "^1.21.36-beta.0",
+    "@ekairos/domain": "^1.21.38-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "@vercel/sandbox": "^0.0.23",