@decocms/start 4.0.0 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "4.0.0",
+  "version": "4.2.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/sdk/sampler.test.ts

@@ -5,14 +5,29 @@ import {
   SamplingDecision,
 } from "@opentelemetry/sdk-trace-base";
 import { describe, expect, it } from "vitest";
-import { createUrlBasedHeadSampler, decodeSamplingConfig, URLBasedSampler } from "./sampler";
+import {
+  createUrlBasedHeadSampler,
+  DEFAULT_SAMPLE_RATIO,
+  decodeSamplingConfig,
+  URLBasedSampler,
+} from "./sampler";
 
-const TRACE_ID = "0000000000000000ffffffffffffffff";
+// Two trace IDs at opposite ends of the TraceIdRatioBased accumulator.
+// `accumulate(traceId)` xors the trace ID in 8-hex-char chunks; threshold at
+// ratio R is `floor(R * 0xffffffff)`. See
+// `@opentelemetry/sdk-trace-base/src/sampler/TraceIdRatioBasedSampler`.
+//
+//   LOW:  0x00000000 ^ 0x00000000 ^ 0xffffffff ^ 0xffffffff = 0
+//         → 0 < threshold for any ratio > 0 → SAMPLED at any ratio > 0
+//   HIGH: 0xffffffff ^ 0x00000000 ^ 0x00000000 ^ 0x00000000 = 0xffffffff
+//         → never below threshold for ratio < 1.0 → DROPPED at any ratio < 1
+const LOW_TRACE_ID = "0000000000000000ffffffffffffffff";
+const HIGH_TRACE_ID = "ffffffff000000000000000000000000";
 
-function decide(sampler: URLBasedSampler, path: string) {
+function decide(sampler: URLBasedSampler, path: string, traceId = LOW_TRACE_ID) {
   return sampler.shouldSample(
     ROOT_CONTEXT,
-    TRACE_ID,
+    traceId,
     "span-name",
     SpanKind.SERVER,
     { "url.path": path },
@@ -21,7 +36,28 @@ function decide(sampler: URLBasedSampler, path: string) {
 }
 
 describe("URLBasedSampler", () => {
-  it("falls back to default ratio when no rule matches", () => {
+  it("exposes 0.1 as the framework-wide default sample ratio", () => {
+    expect(DEFAULT_SAMPLE_RATIO).toBe(0.1);
+  });
+
+  it("defaults to DEFAULT_SAMPLE_RATIO (0.1) when config omits `default`", () => {
+    const s = new URLBasedSampler();
+    // LOW_TRACE_ID accumulates to 0 — sampled at any ratio > 0, including 0.1.
+    expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    // HIGH_TRACE_ID accumulates to ~uint32 max — dropped at 0.1, would be
+    // kept only at ratio ~= 1. This is the assertion that catches an
+    // accidental revert to the old `?? 1.0` fallback.
+    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(SamplingDecision.NOT_RECORD);
+  });
+
+  it("explicit `default: 1` opts in to AlwaysOn (records every trace)", () => {
+    const s = new URLBasedSampler({ default: 1 });
+    expect(decide(s, "/anything", HIGH_TRACE_ID).decision).toBe(
+      SamplingDecision.RECORD_AND_SAMPLED,
+    );
+  });
+
+  it("falls back to provided default ratio when no rule matches", () => {
     const s = new URLBasedSampler({ default: 1.0 });
     expect(decide(s, "/anything").decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
   });
@@ -40,7 +76,7 @@ describe("URLBasedSampler", () => {
 
   it("falls back to default when no path attribute is present", () => {
     const s = new URLBasedSampler({ default: 1.0 });
-    const result = s.shouldSample(ROOT_CONTEXT, TRACE_ID, "noop", SpanKind.INTERNAL, {}, []);
+    const result = s.shouldSample(ROOT_CONTEXT, LOW_TRACE_ID, "noop", SpanKind.INTERNAL, {}, []);
     expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
   });
 
@@ -50,7 +86,7 @@ describe("URLBasedSampler", () => {
       rules: [{ pattern: "^/wanted", ratio: 1.0 }],
     });
     const ok = (attrs: Record<string, string>) =>
-      s.shouldSample(ROOT_CONTEXT, TRACE_ID, "n", SpanKind.SERVER, attrs, []);
+      s.shouldSample(ROOT_CONTEXT, LOW_TRACE_ID, "n", SpanKind.SERVER, attrs, []);
 
     expect(ok({ "url.path": "/wanted/x" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
     expect(ok({ "http.target": "/wanted/y" }).decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
@@ -103,18 +139,20 @@ describe("createUrlBasedHeadSampler", () => {
     expect(sampler).toBeInstanceOf(ParentBasedSampler);
   });
 
-  it("applies the default-ratio = 1.0 when config is null", () => {
-    // Smoke test only — sampler internals are validated above.
+  it("applies DEFAULT_SAMPLE_RATIO when config is null", () => {
     const sampler = createUrlBasedHeadSampler(null);
+    // High-accumulating trace ID is dropped at 0.1 — proves the ParentBased
+    // wrapper inherits the URLBasedSampler default and isn't accidentally
+    // forcing AlwaysOn.
     const result = sampler.shouldSample(
       ROOT_CONTEXT,
-      TRACE_ID,
+      HIGH_TRACE_ID,
       "n",
       SpanKind.SERVER,
       { "url.path": "/" },
       [],
     );
-    expect(result.decision).toBe(SamplingDecision.RECORD_AND_SAMPLED);
+    expect(result.decision).toBe(SamplingDecision.NOT_RECORD);
   });
 });
 

package/src/sdk/sampler.ts

@@ -9,6 +9,13 @@
  * decision when one exists (i.e. distributed traces are kept consistent end
  * to end).
  *
+ * **Default ratio.** When no `default` is provided in the config (or the env
+ * var is unset entirely), the sampler keeps **10%** of traces. Production
+ * storefront traffic at full sampling will burn HyperDX ingest quotas
+ * quickly — for an unconfigured site we'd rather drop 90% than overspend by
+ * default. Sites that genuinely want every trace recorded must opt-in
+ * explicitly with `OTEL_SAMPLING_CONFIG` setting `default: 1`.
+ *
  * @example
  * ```jsonc
  * // base64-encode this and set as OTEL_SAMPLING_CONFIG:
@@ -41,12 +48,23 @@ export interface SamplingRule {
 }
 
 export interface SamplingConfig {
-  /** Default sample ratio applied when no rule matches. Defaults to 1.0 (always sample). */
+  /**
+   * Default sample ratio applied when no rule matches. Defaults to **0.1**
+   * (10% sampled) when omitted. Set to `1` to record every trace
+   * (only do this when you need a full debug stream and accept the cost).
+   */
   default?: number;
   /** Ordered list of rules. First match wins. */
   rules?: SamplingRule[];
 }
 
+/**
+ * Default ratio applied by `URLBasedSampler` when neither the config nor a
+ * matching rule specifies one. Centralised so tests + docs share a single
+ * source of truth.
+ */
+export const DEFAULT_SAMPLE_RATIO = 0.1;
+
 interface CompiledRule {
   re: RegExp;
   sampler: Sampler;
@@ -61,7 +79,7 @@ export class URLBasedSampler implements Sampler {
   private readonly rules: CompiledRule[];
 
   constructor(config: SamplingConfig = {}) {
-    this.defaultSampler = ratioToSampler(config.default ?? 1.0);
+    this.defaultSampler = ratioToSampler(config.default ?? DEFAULT_SAMPLE_RATIO);
     this.rules = (config.rules ?? []).map((rule) => ({
       re: new RegExp(rule.pattern),
       sampler: ratioToSampler(rule.ratio),
@@ -128,7 +146,7 @@ function extractPath(attrs: Attributes): string | null {
 
 /**
  * Decode a base64-encoded `OTEL_SAMPLING_CONFIG` value into a `SamplingConfig`.
- * Returns `null` (caller falls back to default ratio 1.0) on:
+ * Returns `null` (caller falls back to `DEFAULT_SAMPLE_RATIO`, currently 0.1) on:
  *  - missing / empty input
  *  - invalid base64
  *  - JSON parse failure

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();
+  });
+});