@metaobjectsdev/render 1.0.8 → 1.0.9-rc.1

package/README.md

@@ -14,6 +14,10 @@ npm install @metaobjectsdev/render
 
 - **`render()`** — render a MetaObjects `template.output` / `template.prompt` against a typed payload. Deterministic and cache-stable (no whitespace drift that would silently break exact-prefix prompt-cache hits), so output is snapshot-testable.
 - **Provider-resolved partials + format-driven escaping** (text / html / xml / csv / json / markdown).
+- **Providers** — `InMemoryProvider` (root entry, browser-safe) and `FilesystemProvider`
+  (Node-only, on the `@metaobjectsdev/render/providers` subpath so the root entry never
+  pulls in `node:fs`). `new FilesystemProvider("./prompts").resolve("lobby/welcome")` reads
+  `./prompts/lobby/welcome.mustache`, exactly as the C#, Java and Python ports do.
 - **`verify()`** — a build-time drift check that every `{{field}}` referenced by a template resolves to a field on its payload value-object; a renamed field fails the build instead of silently degrading a prompt.
 
 This engine backs the prompt-construction pillar — the generated `render<Name>()` helpers emitted by `@metaobjectsdev/codegen-ts` wrap it. See the **metaobjects-prompts** skill and the repo `docs/` for authoring `template.*` and payload VOs.

package/dist/filesystem-provider.d.ts

@@ -0,0 +1,10 @@
+import type { Provider } from "./provider.js";
+/** The default template file extension, shared with every other port. */
+export declare const DEFAULT_TEMPLATE_EXTENSION = ".mustache";
+export declare class FilesystemProvider implements Provider {
+    private readonly extension;
+    private readonly root;
+    constructor(root: string, extension?: string);
+    resolve(ref: string): string | undefined;
+}
+//# sourceMappingURL=filesystem-provider.d.ts.map

package/dist/filesystem-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-provider.d.ts","sourceRoot":"","sources":["../src/filesystem-provider.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,cAAc,CAAC;AAKtD,qBAAa,kBAAmB,YAAW,QAAQ;IAGvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFpD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,EAAE,MAAM,EAAmB,SAAS,GAAE,MAAmC;IAIzF,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAezC"}

package/dist/filesystem-provider.js

@@ -0,0 +1,42 @@
+// Filesystem-backed provider: resolves a `group/source` reference to
+// <root>/<group>/<source>.mustache. NODE-ONLY — it is reachable solely through
+// the `@metaobjectsdev/render/providers` subpath so the package's root entry
+// stays importable in a browser bundle.
+//
+// Mirrors the C# MetaObjects.Render.FilesystemProvider, the Java
+// com.metaobjects.render.FilesystemProvider and the Python
+// metaobjects.render.FilesystemProvider: read the file when present, return
+// undefined when absent / unreadable / not a regular file, and refuse a ref that
+// escapes the root (undefined, never a throw).
+import { readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+/** The default template file extension, shared with every other port. */
+export const DEFAULT_TEMPLATE_EXTENSION = ".mustache";
+const REF_SEPARATOR = "/";
+const PARENT_SEGMENT = "..";
+export class FilesystemProvider {
+    extension;
+    root;
+    constructor(root, extension = DEFAULT_TEMPLATE_EXTENSION) {
+        this.extension = extension;
+        this.root = resolve(root);
+    }
+    resolve(ref) {
+        const segments = ref.split(REF_SEPARATOR).filter((s) => s.length > 0);
+        if (segments.length === 0 || segments.includes(PARENT_SEGMENT))
+            return undefined;
+        const candidate = resolve(this.root, ...segments) + this.extension;
+        // Path-traversal guard (belt-and-suspenders after the `..` check).
+        if (!candidate.startsWith(this.root + sep))
+            return undefined;
+        try {
+            if (!statSync(candidate).isFile())
+                return undefined;
+            return readFileSync(candidate, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=filesystem-provider.js.map

package/dist/filesystem-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-provider.js","sourceRoot":"","sources":["../src/filesystem-provider.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,+EAA+E;AAC/E,6EAA6E;AAC7E,wCAAwC;AACxC,EAAE;AACF,iEAAiE;AACjE,2DAA2D;AAC3D,4EAA4E;AAC5E,iFAAiF;AACjF,+CAA+C;AAE/C,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGzC,yEAAyE;AACzE,MAAM,CAAC,MAAM,0BAA0B,GAAG,WAAW,CAAC;AAEtD,MAAM,aAAa,GAAG,GAAG,CAAC;AAC1B,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,MAAM,OAAO,kBAAkB;IAGc;IAF1B,IAAI,CAAS;IAE9B,YAAY,IAAY,EAAmB,YAAoB,0BAA0B;QAA9C,cAAS,GAAT,SAAS,CAAqC;QACvF,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,GAAW;QACjB,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,OAAO,SAAS,CAAC;QAEjF,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;QACnE,mEAAmE;QACnE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QAE7D,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE;gBAAE,OAAO,SAAS,CAAC;YACpD,OAAO,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/dist/providers.d.ts

@@ -0,0 +1,3 @@
+export { FilesystemProvider, DEFAULT_TEMPLATE_EXTENSION } from "./filesystem-provider.js";
+export { type Provider, InMemoryProvider } from "./provider.js";
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,KAAK,QAAQ,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/providers.js

@@ -0,0 +1,7 @@
+// `@metaobjectsdev/render/providers` — the NODE-ONLY provider entry.
+//
+// The root entry (`@metaobjectsdev/render`) is browser-safe and must stay that
+// way; anything that touches the filesystem lives behind this subpath.
+export { FilesystemProvider, DEFAULT_TEMPLATE_EXTENSION } from "./filesystem-provider.js";
+export { InMemoryProvider } from "./provider.js";
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,+EAA+E;AAC/E,uEAAuE;AACvE,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAiB,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/render",
-  "version": "1.0.8",
+  "version": "1.0.9-rc.1",
   "description": "Logic-less, deterministic text render engine (Mustache) for MetaObjects templates — provider-resolved partials, format-driven escaping, zero core dependency.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,11 @@
       "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./providers": {
+      "bun": "./src/providers.ts",
+      "types": "./dist/providers.d.ts",
+      "default": "./dist/providers.js"
     }
   },
   "files": [

package/src/filesystem-provider.ts

@@ -0,0 +1,44 @@
+// Filesystem-backed provider: resolves a `group/source` reference to
+// <root>/<group>/<source>.mustache. NODE-ONLY — it is reachable solely through
+// the `@metaobjectsdev/render/providers` subpath so the package's root entry
+// stays importable in a browser bundle.
+//
+// Mirrors the C# MetaObjects.Render.FilesystemProvider, the Java
+// com.metaobjects.render.FilesystemProvider and the Python
+// metaobjects.render.FilesystemProvider: read the file when present, return
+// undefined when absent / unreadable / not a regular file, and refuse a ref that
+// escapes the root (undefined, never a throw).
+
+import { readFileSync, statSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import type { Provider } from "./provider.js";
+
+/** The default template file extension, shared with every other port. */
+export const DEFAULT_TEMPLATE_EXTENSION = ".mustache";
+
+const REF_SEPARATOR = "/";
+const PARENT_SEGMENT = "..";
+
+export class FilesystemProvider implements Provider {
+  private readonly root: string;
+
+  constructor(root: string, private readonly extension: string = DEFAULT_TEMPLATE_EXTENSION) {
+    this.root = resolve(root);
+  }
+
+  resolve(ref: string): string | undefined {
+    const segments = ref.split(REF_SEPARATOR).filter((s) => s.length > 0);
+    if (segments.length === 0 || segments.includes(PARENT_SEGMENT)) return undefined;
+
+    const candidate = resolve(this.root, ...segments) + this.extension;
+    // Path-traversal guard (belt-and-suspenders after the `..` check).
+    if (!candidate.startsWith(this.root + sep)) return undefined;
+
+    try {
+      if (!statSync(candidate).isFile()) return undefined;
+      return readFileSync(candidate, "utf8");
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/providers.ts

@@ -0,0 +1,6 @@
+// `@metaobjectsdev/render/providers` — the NODE-ONLY provider entry.
+//
+// The root entry (`@metaobjectsdev/render`) is browser-safe and must stay that
+// way; anything that touches the filesystem lives behind this subpath.
+export { FilesystemProvider, DEFAULT_TEMPLATE_EXTENSION } from "./filesystem-provider.js";
+export { type Provider, InMemoryProvider } from "./provider.js";