@decocms/start 4.0.0 → 4.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/sdk/logger.test.ts

@@ -6,6 +6,7 @@ import {
   getLogLevel,
   type LoggerAdapter,
   logger,
+  serializeError,
   setLogLevel,
 } from "./logger";
 
@@ -133,3 +134,55 @@ describe("configureLogger", () => {
     logSpy.mockRestore();
   });
 });
+
+describe("serializeError", () => {
+  it("flattens an Error into a JSON-safe shape with stack", () => {
+    const err = new Error("boom");
+    const out = serializeError(err);
+    expect(out).toEqual({ name: "Error", message: "boom", stack: err.stack });
+  });
+
+  it("preserves subclass name (TypeError, RangeError, custom)", () => {
+    expect(serializeError(new TypeError("bad type")).name).toBe("TypeError");
+    class MyErr extends Error {
+      override name = "MyErr";
+    }
+    expect(serializeError(new MyErr("custom")).name).toBe("MyErr");
+  });
+
+  it("survives JSON.stringify round-trip", () => {
+    const err = new Error("round-trip");
+    const out = serializeError(err);
+    expect(() => JSON.parse(JSON.stringify(out))).not.toThrow();
+    expect(JSON.parse(JSON.stringify(out)).message).toBe("round-trip");
+  });
+
+  it("captures plain objects as JSON in message, marking them as NonError", () => {
+    const out = serializeError({ code: 500, body: "vtex down" });
+    expect(out.name).toBe("NonError");
+    expect(out.message).toBe('{"code":500,"body":"vtex down"}');
+    expect(out.stack).toBeUndefined();
+  });
+
+  it("falls back to String() when an object has circular refs", () => {
+    const circ: Record<string, unknown> = { a: 1 };
+    circ.self = circ;
+    const out = serializeError(circ);
+    expect(out.name).toBe("NonError");
+    expect(typeof out.message).toBe("string");
+    expect(out.stack).toBeUndefined();
+  });
+
+  it("handles primitives (string, number, null, undefined)", () => {
+    expect(serializeError("just a string")).toEqual({
+      name: "NonError",
+      message: "just a string",
+    });
+    expect(serializeError(42)).toEqual({ name: "NonError", message: "42" });
+    expect(serializeError(null)).toEqual({ name: "NonError", message: "null" });
+    expect(serializeError(undefined)).toEqual({
+      name: "NonError",
+      message: "undefined",
+    });
+  });
+});

package/src/sdk/logger.ts

@@ -127,11 +127,25 @@ function shouldLog(level: LogLevel): boolean {
 // ---------------------------------------------------------------------------
 
 /**
- * Mirrors `@deco/deco/o11y` logger:
- *  - first arg is the message
+ * Strict structured logger. Mirrors `@deco/deco/o11y`:
+ *  - first arg is a human-readable message string
  *  - optional second arg is a flat attributes object
  *
- * Adapters decide the destination (stdout JSON, OTLP, both, …).
+ * Adapters decide the destination (stdout JSON, OTLP, both, …). The
+ * contract is intentionally narrow so structured output stays predictable
+ * across all sinks.
+ *
+ * @example
+ * ```ts
+ * logger.info("checkout started", { orderFormId, items });
+ * logger.warn("retrying vtex call", { attempt, host });
+ *
+ * // For Errors, serialize explicitly into the attrs payload:
+ * try { ... } catch (err) {
+ *   const e = serializeError(err);
+ *   logger.error(e.message, { error: e, stage: "checkout" });
+ * }
+ * ```
  */
 export interface Logger {
   debug(msg: string, attrs?: Record<string, unknown>): void;
@@ -140,6 +154,47 @@ export interface Logger {
   error(msg: string, attrs?: Record<string, unknown>): void;
 }
 
+/**
+ * Normalised, JSON-safe error shape suitable for inclusion in logger
+ * attributes. `serializeError` always returns this shape regardless of
+ * what was thrown.
+ */
+export interface SerializedError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+/**
+ * Convert any thrown value into a flat, structured object that survives
+ * `JSON.stringify` and round-trips cleanly to OTel / Cloudflare Logs.
+ * Strict logger sites should call this from their catch blocks rather
+ * than passing the Error directly.
+ *
+ * @example
+ * ```ts
+ * try { ... } catch (err) {
+ *   const e = serializeError(err);
+ *   logger.error(e.message, { error: e });
+ * }
+ * ```
+ */
+export function serializeError(err: unknown): SerializedError {
+  if (err instanceof Error) {
+    return { name: err.name, message: err.message, stack: err.stack };
+  }
+  if (err && typeof err === "object") {
+    let body: string;
+    try {
+      body = JSON.stringify(err);
+    } catch {
+      body = String(err);
+    }
+    return { name: "NonError", message: body };
+  }
+  return { name: "NonError", message: String(err) };
+}
+
 function emit(level: LogLevel, msg: string, attrs?: Record<string, unknown>): void {
   if (!shouldLog(level)) return;
   try {

package/src/vite/plugin.js

@@ -31,7 +31,7 @@
  * export default defineConfig({ plugins: [decoVitePlugin(), ...] });
  * ```
  */
-import { readFileSync, existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 // Bare-specifier stubs resolved by ID before Vite touches them.
 /** @type {Record<string, string>} */
@@ -44,6 +44,23 @@ const CLIENT_STUBS = {
   "tanstack-start-injected-head-scripts:v": "\0stub:tanstack-head-scripts",
 };
 
+// SSR-only stubs. Same mechanism as CLIENT_STUBS but applied to the worker
+// SSR build instead of the browser build.
+/** @type {Record<string, string>} */
+const SSR_STUBS = {
+  // `@opentelemetry/resources` (transitively pulled in by sdk-logs /
+  // sdk-metrics / exporter-* OTel packages — five copies in node_modules due
+  // to OTel monorepo peer-dep version pinning) statically imports bare `fs`
+  // inside its node-platform machine-id detectors. We never call those
+  // detectors — `instrumentWorker` builds the OTel Resource from explicit
+  // attributes only — but Vite's CF Workers SSR resolver still walks the
+  // re-export barrel and chokes on the bare `fs` specifier (workerd's
+  // `nodejs_compat` only exposes the prefixed `node:fs`, not the legacy
+  // bare form). Stub it; the static import resolves and the unreachable
+  // detector code is never executed.
+  fs: "\0stub:bare-fs",
+};
+
 // Minimal stub source for each virtual module.
 /** @type {Record<string, string>} */
 const STUB_SOURCE = {
@@ -72,13 +89,18 @@ const STUB_SOURCE = {
     "export default { AsyncLocalStorage: _ALS, AsyncResource, executionAsyncId, createHook };",
   ].join("\n"),
 
-  "\0stub:tanstack-head-scripts":
-    "export const injectedHeadScripts = undefined;",
+  "\0stub:tanstack-head-scripts": "export const injectedHeadScripts = undefined;",
 
   // The admin schema bundle is server-only — the client receives pre-resolved
   // blocks via the SSR payload. Stubbing it on the client cuts a large module
   // (typically 0.5-5 MB) out of the browser bundle.
   "\0stub:meta-gen": "export default {};",
+
+  // Bare `fs` shim — see SSR_STUBS comment above for the rationale. Surfaces
+  // just enough of `import { promises as fs } from 'fs'` to satisfy static
+  // module resolution; method calls would throw, but the OTel detector code
+  // path is unreachable from `instrumentWorker`.
+  "\0stub:bare-fs": "export const promises = {}; export default { promises };",
 };
 
 /** @returns {import("vite").PluginOption} */
@@ -89,6 +111,9 @@ export function decoVitePlugin() {
     enforce: "pre",
 
     resolveId(id, importer, options) {
+      // SSR-only stubs — must be checked first since the client guard below
+      // returns undefined for everything that hasn't matched yet on SSR.
+      if (options?.ssr && SSR_STUBS[id]) return SSR_STUBS[id];
       // Server builds keep the real modules.
       if (options?.ssr) return undefined;
       // Bare-specifier exact-match stubs (react-dom/server, node:stream, etc.).
@@ -98,10 +123,7 @@ export function decoVitePlugin() {
       // plugin works whether `setup.ts` imports the .json directly (current)
       // or a future variant routes through a generated .ts wrapper.
       // Requires `importer` so we don't accidentally stub the entry module.
-      if (
-        importer &&
-        (id.endsWith("meta.gen.json") || id.endsWith("meta.gen.ts"))
-      ) {
+      if (importer && (id.endsWith("meta.gen.json") || id.endsWith("meta.gen.ts"))) {
         return "\0stub:meta-gen";
       }
       return undefined;
@@ -154,7 +176,6 @@ export function decoVitePlugin() {
       const siteName = process.env.DECO_SITE_NAME;
       const envName = process.env.DECO_ENV_NAME;
       if (siteName && envName) {
-
         // Daemon files are .ts and live inside node_modules. Node's
         // experimental strip-types refuses to transpile node_modules, so
         // a plain dynamic `import()` blows up under `vite dev`. Use tsx's
@@ -214,18 +235,12 @@ export function decoVitePlugin() {
           rollupOptions: {
             output: {
               manualChunks(id) {
-                if (
-                  id.includes("node_modules/react-dom") ||
-                  id.includes("node_modules/react/")
-                ) {
+                if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/")) {
                   return "vendor-react";
                 }
 
                 // TanStack Router — client-side router (always needed)
-                if (
-                  id.includes("@tanstack/react-router") ||
-                  id.includes("@tanstack/router-core")
-                ) {
+                if (id.includes("@tanstack/react-router") || id.includes("@tanstack/router-core")) {
                   return "vendor-router";
                 }
 
@@ -275,8 +290,7 @@ export function decoVitePlugin() {
     configEnvironment(name, env) {
       if (name === "ssr" || name === "client") {
         env.optimizeDeps = env.optimizeDeps || {};
-        env.optimizeDeps.esbuildOptions =
-          env.optimizeDeps.esbuildOptions || {};
+        env.optimizeDeps.esbuildOptions = env.optimizeDeps.esbuildOptions || {};
         env.optimizeDeps.esbuildOptions.jsx = "automatic";
         env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
       }

package/src/vite/plugin.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { decoVitePlugin } from "./plugin.js";
+
+/**
+ * The Vite plugin's `resolveId` / `load` hooks are pure functions over their
+ * inputs, so we can exercise them without spinning up a Vite environment.
+ */
+
+function getPlugin() {
+  const result = decoVitePlugin();
+  // decoVitePlugin returns a single plugin object today, but the type is
+  // `PluginOption` which permits arrays — handle both.
+  return Array.isArray(result) ? result[0] : result;
+}
+
+describe("decoVitePlugin SSR stubs", () => {
+  it("rewrites bare `fs` to a virtual module on SSR", () => {
+    const p = getPlugin();
+    const id = p.resolveId.call({}, "fs", undefined, { ssr: true });
+    expect(id).toBe("\0stub:bare-fs");
+  });
+
+  it("does NOT rewrite bare `fs` on client (browser builds don't import fs)", () => {
+    const p = getPlugin();
+    const id = p.resolveId.call({}, "fs", undefined, { ssr: false });
+    expect(id).toBeUndefined();
+  });
+
+  it("loads an empty surface for the bare-fs virtual module", () => {
+    const p = getPlugin();
+    const src = p.load.call({}, "\0stub:bare-fs", { ssr: true });
+    expect(src).toContain("export const promises = {}");
+    expect(src).toContain("export default");
+  });
+
+  it("does not interfere with real SSR modules", () => {
+    const p = getPlugin();
+    expect(p.resolveId.call({}, "@decocms/start/cms", undefined, { ssr: true })).toBeUndefined();
+  });
+});
+
+describe("decoVitePlugin client stubs (regression guard)", () => {
+  it("still rewrites node:async_hooks on the client build", () => {
+    const p = getPlugin();
+    const id = p.resolveId.call({}, "node:async_hooks", undefined, { ssr: false });
+    expect(id).toBe("\0stub:node-async-hooks");
+  });
+
+  it("does not rewrite client stubs on SSR", () => {
+    const p = getPlugin();
+    const id = p.resolveId.call({}, "react-dom/server", undefined, { ssr: true });
+    expect(id).toBeUndefined();
+  });
+});