@kaleabdenbel/llmweb 1.0.3 → 1.0.5

package/README.md

@@ -11,13 +11,19 @@ The data compiler that transforms messy application state into LLM-readable trut
 - **The Engine**: Compiles these into a single, structured JSON object for LLMs.
 - **Framework Adapters**: Utilities for [Next.js](docs/next.md), [React](docs/react.md), [Express](docs/express.md), and [Vanilla JS](docs/vanilla.md).
 
-## Installation
+## Quick Start
+
+The fastest way to get started is using the CLI:
 
 ```bash
-npm install llmweb
+npx llmweb init
 ```
 
-## Quick Start (Next.js)
+For a deep dive into the **Bridge Pattern**, **Server Actions**, and **Advanced Mapping**, check out our [Definitive Guide](docs/guide.md).
+
+---
+
+## Integration (Next.js)
 
 ### 1. Define your Truth
 

package/dist/adapters/express.d.mts

@@ -0,0 +1,8 @@
+import { L as LLMConfig } from '../index-B8G8cw7b.mjs';
+
+/**
+ * An Express middleware that serves the LLM truth.
+ */
+declare function llmMiddleware(config: LLMConfig): (req: any, res: any, next: any) => Promise<void>;
+
+export { llmMiddleware };

package/dist/adapters/express.d.ts

@@ -0,0 +1,8 @@
+import { L as LLMConfig } from '../index-B8G8cw7b.js';
+
+/**
+ * An Express middleware that serves the LLM truth.
+ */
+declare function llmMiddleware(config: LLMConfig): (req: any, res: any, next: any) => Promise<void>;
+
+export { llmMiddleware };

package/dist/adapters/express.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/adapters/express.ts
@@ -105,18 +115,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -146,13 +161,24 @@ async function compileLLM(config, loader, options = {}) {
 }
 
 // src/index.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : (0, import_node_path.join)(process.cwd(), path);
-  return (0, import_node_fs.readFileSync)(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 

package/dist/adapters/express.mjs

@@ -79,18 +79,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -120,13 +125,24 @@ async function compileLLM(config, loader, options = {}) {
 }
 
 // src/index.ts
-import { readFileSync } from "fs";
-import { join } from "path";
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : join(process.cwd(), path);
-  return readFileSync(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 

package/dist/adapters/next.d.mts

@@ -0,0 +1,21 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LLMConfig } from '../index-B8G8cw7b.mjs';
+
+interface LLMJsonProps {
+    config: LLMConfig;
+    /**
+     * Optional custom styling for the rendered JSON if viewing in a browser.
+     */
+    className?: string;
+}
+/**
+ * A Next.js Server Component that resolves the LLM truth and renders it.
+ * By default, it renders a <pre> tag with the JSON string.
+ */
+declare function LLMJson({ config, className }: LLMJsonProps): Promise<react_jsx_runtime.JSX.Element>;
+/**
+ * A helper for Next.js App Router Route Handlers (route.ts).
+ */
+declare function createLLMHandler(config: LLMConfig): () => Promise<Response>;
+
+export { LLMJson, createLLMHandler };

package/dist/adapters/next.d.ts

@@ -0,0 +1,21 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LLMConfig } from '../index-B8G8cw7b.js';
+
+interface LLMJsonProps {
+    config: LLMConfig;
+    /**
+     * Optional custom styling for the rendered JSON if viewing in a browser.
+     */
+    className?: string;
+}
+/**
+ * A Next.js Server Component that resolves the LLM truth and renders it.
+ * By default, it renders a <pre> tag with the JSON string.
+ */
+declare function LLMJson({ config, className }: LLMJsonProps): Promise<react_jsx_runtime.JSX.Element>;
+/**
+ * A helper for Next.js App Router Route Handlers (route.ts).
+ */
+declare function createLLMHandler(config: LLMConfig): () => Promise<Response>;
+
+export { LLMJson, createLLMHandler };

package/dist/adapters/next.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/adapters/next.tsx
@@ -106,18 +116,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -147,13 +162,24 @@ async function compileLLM(config, loader, options = {}) {
 }
 
 // src/index.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : (0, import_node_path.join)(process.cwd(), path);
-  return (0, import_node_fs.readFileSync)(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 

package/dist/adapters/next.mjs

@@ -79,18 +79,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -120,13 +125,24 @@ async function compileLLM(config, loader, options = {}) {
 }
 
 // src/index.ts
-import { readFileSync } from "fs";
-import { join } from "path";
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : join(process.cwd(), path);
-  return readFileSync(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 

package/dist/adapters/react.d.mts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LLMConfig } from '../index-B8G8cw7b.mjs';
+
+interface LLMJsonProps {
+    config: LLMConfig;
+    mode?: "script" | "window" | "pre";
+    targetKey?: string;
+    className?: string;
+}
+/**
+ * Universal LLMJson component for React environments.
+ * Handles server-side resolution in Next.js or client-side resolution (if needed).
+ *
+ * NOTE: When used in Next.js Server Components, this will be async.
+ * In standard Client Components, it expects an async resolution pattern or pre-resolved data.
+ */
+declare function LLMJson({ config, mode, targetKey, className, }: LLMJsonProps): Promise<react_jsx_runtime.JSX.Element>;
+/**
+ * Client-side component for injecting LLM truth.
+ * Uses useEffect to resolve data, suitable for standard React apps (CRA/Vite).
+ */
+declare function LLMInjector({ config, mode, targetKey, className, }: LLMJsonProps): react_jsx_runtime.JSX.Element | null;
+
+export { LLMInjector, LLMJson, type LLMJsonProps };

package/dist/adapters/react.d.ts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { L as LLMConfig } from '../index-B8G8cw7b.js';
+
+interface LLMJsonProps {
+    config: LLMConfig;
+    mode?: "script" | "window" | "pre";
+    targetKey?: string;
+    className?: string;
+}
+/**
+ * Universal LLMJson component for React environments.
+ * Handles server-side resolution in Next.js or client-side resolution (if needed).
+ *
+ * NOTE: When used in Next.js Server Components, this will be async.
+ * In standard Client Components, it expects an async resolution pattern or pre-resolved data.
+ */
+declare function LLMJson({ config, mode, targetKey, className, }: LLMJsonProps): Promise<react_jsx_runtime.JSX.Element>;
+/**
+ * Client-side component for injecting LLM truth.
+ * Uses useEffect to resolve data, suitable for standard React apps (CRA/Vite).
+ */
+declare function LLMInjector({ config, mode, targetKey, className, }: LLMJsonProps): react_jsx_runtime.JSX.Element | null;
+
+export { LLMInjector, LLMJson, type LLMJsonProps };

package/dist/adapters/react.js

@@ -117,18 +117,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -157,10 +162,6 @@ async function compileLLM(config, loader, options = {}) {
   return merge(staticTruth, dynamicTruth);
 }
 
-// src/index.ts
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-
 // src/core/injector.ts
 function toWindowString(data, key = "__LLM__") {
   const json = JSON.stringify(data);
@@ -168,11 +169,24 @@ function toWindowString(data, key = "__LLM__") {
 }
 
 // src/index.ts
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : (0, import_node_path.join)(process.cwd(), path);
-  return (0, import_node_fs.readFileSync)(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 
@@ -213,7 +227,9 @@ function LLMInjector({
   targetKey = "__LLM__",
   className
 }) {
-  const [truth, setTruth] = import_react.default.useState(null);
+  const [truth, setTruth] = import_react.default.useState(
+    typeof config.static === "object" ? config.static : null
+  );
   import_react.default.useEffect(() => {
     let mounted = true;
     createLLMSource(config).then((data) => {

package/dist/adapters/react.mjs

@@ -82,18 +82,23 @@ function merge(staticData, dynamicResults) {
 
 // src/core/compiler.ts
 async function compileLLM(config, loader, options = {}) {
-  let staticTruth = {};
-  if (config.static) {
+  const { static: staticRef, dynamic, ...topLevelMetadata } = config;
+  let staticTruth = { ...topLevelMetadata };
+  if (staticRef) {
     try {
-      const content = await loader(config.static);
-      if (content) {
-        staticTruth = JSON.parse(content);
+      if (typeof staticRef === "object") {
+        staticTruth = { ...staticTruth, ...staticRef };
+      } else {
+        const content = await loader(staticRef);
+        if (content) {
+          staticTruth = { ...staticTruth, ...JSON.parse(content) };
+        }
       }
     } catch (error) {
       if (options.failLoudly) {
-        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${config.static}. ${error}`);
+        throw new Error(`[llmweb] Static Truth Error: Failed to load/parse JSON at ${staticRef}. ${error}`);
       }
-      console.warn(`[llmweb] Warning: Could not load static JSON at ${config.static}. Proceeding with dynamic data only.`);
+      console.warn(`[llmweb] Warning: Could not load static JSON at ${staticRef}. Proceeding with dynamic data only.`);
     }
   }
   const dynamicTruth = {};
@@ -122,10 +127,6 @@ async function compileLLM(config, loader, options = {}) {
   return merge(staticTruth, dynamicTruth);
 }
 
-// src/index.ts
-import { readFileSync } from "fs";
-import { join } from "path";
-
 // src/core/injector.ts
 function toWindowString(data, key = "__LLM__") {
   const json = JSON.stringify(data);
@@ -133,11 +134,24 @@ function toWindowString(data, key = "__LLM__") {
 }
 
 // src/index.ts
-var nodeLoader = async (path) => {
-  const fullPath = path.startsWith("/") ? path : join(process.cwd(), path);
-  return readFileSync(fullPath, "utf-8");
-};
 async function createLLMSource(config, options = {}) {
+  const nodeLoader = async (path) => {
+    try {
+      const fs = await import(
+        /* webpackIgnore: true */
+        "fs"
+      );
+      const nodePath = await import(
+        /* webpackIgnore: true */
+        "path"
+      );
+      const fullPath = path.startsWith("/") ? path : nodePath.join(process.cwd(), path);
+      return fs.readFileSync(fullPath, "utf-8");
+    } catch (error) {
+      console.warn(`[llmweb] Warning: 'node:fs' not available. Skipping static file load: ${path}`);
+      return null;
+    }
+  };
   return compileLLM(config, nodeLoader, options);
 }
 
@@ -178,7 +192,9 @@ function LLMInjector({
   targetKey = "__LLM__",
   className
 }) {
-  const [truth, setTruth] = React.useState(null);
+  const [truth, setTruth] = React.useState(
+    typeof config.static === "object" ? config.static : null
+  );
   React.useEffect(() => {
     let mounted = true;
     createLLMSource(config).then((data) => {

package/dist/adapters/vanilla.d.mts

@@ -0,0 +1,8 @@
+import { L as LLMConfig } from '../index-B8G8cw7b.mjs';
+
+/**
+ * Vanilla JS helper to inject LLM truth into the DOM.
+ */
+declare function inject(config: LLMConfig, mode?: 'script' | 'window', targetKey?: string): Promise<void>;
+
+export { inject };

package/dist/adapters/vanilla.d.ts

@@ -0,0 +1,8 @@
+import { L as LLMConfig } from '../index-B8G8cw7b.js';
+
+/**
+ * Vanilla JS helper to inject LLM truth into the DOM.
+ */
+declare function inject(config: LLMConfig, mode?: 'script' | 'window', targetKey?: string): Promise<void>;
+
+export { inject };