@decocms/start 3.0.0 → 4.1.0

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

package/.github/workflows/deploy.yml

@@ -1,141 +0,0 @@
-name: deploy (central)
-
-# Reusable workflow that drives `wrangler deploy` for any storefront repo.
-# Worker name is the storefront repo basename by convention; there is no
-# per-site registry. The deploy is gated by the `decocms-deployer` GitHub App
-# being installed on the target storefront repo -- the App-token mint fails
-# (and the deploy never starts) if the App isn't installed there.
-#
-# v3 architecture (D6.2): triggered via `workflow_dispatch` from the storefront,
-# authenticated as the `decocms-deployer` GitHub App. The deploy runs IN THIS
-# REPO'S CONTEXT, so `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` resolve
-# from this repo's plain repo secrets and never leave decocms/deco-start.
-#
-# Caller usage (in the storefront repo, `.github/workflows/deploy.yml`):
-#
-#   on:
-#     push:
-#       branches: [main]
-#   permissions:
-#     contents: read
-#   jobs:
-#     trigger:
-#       runs-on: ubuntu-latest
-#       steps:
-#         - uses: actions/create-github-app-token@v1
-#           id: app-token
-#           with:
-#             app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
-#             private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
-#             owner: decocms
-#             repositories: deco-start
-#         - env:
-#             GH_TOKEN: ${{ steps.app-token.outputs.token }}
-#           run: |
-#             gh workflow run deploy.yml \
-#               --repo decocms/deco-start \
-#               --ref v3 \
-#               -f site_owner=${GITHUB_REPOSITORY%%/*} \
-#               -f site_name=${GITHUB_REPOSITORY##*/}
-
-on:
-  workflow_dispatch:
-    inputs:
-      site_owner:
-        description: "GitHub org of the storefront (e.g. deco-sites). Defaults to deco-sites."
-        type: string
-        required: false
-        default: deco-sites
-      site_name:
-        description: "Storefront repo basename. Becomes the Cloudflare worker name."
-        type: string
-        required: true
-
-permissions:
-  contents: read
-
-concurrency:
-  group: deploy-${{ inputs.site_owner }}-${{ inputs.site_name }}
-  cancel-in-progress: false
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout deco-start (template + scripts)
-        uses: actions/checkout@v4
-
-      - name: Mint App token for storefront checkout
-        id: app-token
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
-          private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
-          owner: ${{ inputs.site_owner }}
-          repositories: ${{ inputs.site_name }}
-
-      # SECURITY: production deploys IGNORE any caller-supplied sha. The deploy
-      # always targets the storefront's CURRENT default-branch HEAD. This means
-      # an attacker with push to repo A who triggers a deploy of repo B can
-      # only force a no-op redeploy of B's current main -- they cannot select
-      # an arbitrary historical commit (no force-rollback attack).
-      - name: Resolve target sha (storefront default branch HEAD)
-        id: target
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          SITE_REPO: ${{ inputs.site_owner }}/${{ inputs.site_name }}
-        run: |
-          set -euo pipefail
-          DEFAULT_BRANCH=$(gh api "repos/$SITE_REPO" --jq .default_branch)
-          SHA=$(gh api "repos/$SITE_REPO/branches/$DEFAULT_BRANCH" --jq .commit.sha)
-          echo "ref=$DEFAULT_BRANCH" >> "$GITHUB_OUTPUT"
-          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
-          echo "::notice::Deploying $SITE_REPO @ $DEFAULT_BRANCH ($SHA)"
-
-      - name: Checkout storefront at default-branch HEAD
-        uses: actions/checkout@v4
-        with:
-          repository: ${{ inputs.site_owner }}/${{ inputs.site_name }}
-          ref: ${{ steps.target.outputs.sha }}
-          token: ${{ steps.app-token.outputs.token }}
-          path: site
-          fetch-depth: 1
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Restore npm cache
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: npm-${{ runner.os }}-${{ hashFiles('site/package-lock.json') }}
-          restore-keys: npm-${{ runner.os }}-
-
-      - name: Install dependencies
-        working-directory: site
-        run: |
-          if [ ! -f package-lock.json ]; then
-            npm install --package-lock-only
-          fi
-          npm ci
-
-      - name: Build
-        working-directory: site
-        run: npm run build
-
-      - name: Generate wrangler.jsonc from template
-        working-directory: site
-        env:
-          DECO_START_PATH: "${{ github.workspace }}"
-          WORKER_NAME: ${{ inputs.site_name }}
-          OUTPUT_PATH: "./wrangler.jsonc"
-        run: node "$DECO_START_PATH/scripts/deploy/build-wrangler-config.mjs"
-
-      - name: Deploy to Cloudflare Workers
-        working-directory: site
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          BUILD_HASH: ${{ steps.target.outputs.sha }}
-        run: npx wrangler deploy --var "BUILD_HASH:${BUILD_HASH:0:7}"

package/.github/workflows/preview.yml

@@ -1,200 +0,0 @@
-name: preview (central)
-
-# Reusable workflow that uploads a preview Worker version (alias) for any
-# storefront repo. Worker name is the storefront repo basename by convention;
-# there is no per-site registry. The preview is gated by the `decocms-deployer`
-# GitHub App being installed on the target storefront repo.
-#
-# v3 architecture (D6.2): triggered via `workflow_dispatch` from the storefront,
-# authenticated as the `decocms-deployer` GitHub App. CF secrets resolve from
-# this repo's plain repo secrets and never leave decocms/deco-start.
-#
-# Caller usage (in the storefront repo, `.github/workflows/preview.yml`):
-#
-#   on:
-#     pull_request:
-#       types: [opened, synchronize, reopened]
-#     push:
-#       branches: ['env/**']
-#   permissions:
-#     contents: read
-#   jobs:
-#     trigger:
-#       runs-on: ubuntu-latest
-#       steps:
-#         - id: meta
-#           run: |
-#             if [ "${{ github.event_name }}" = "pull_request" ]; then
-#               echo "alias=pr-${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
-#               echo "sha=${{ github.event.pull_request.head.sha }}" >> "$GITHUB_OUTPUT"
-#             else
-#               REF="${GITHUB_REF#refs/heads/env/}"
-#               echo "alias=$(echo "$REF" | sed 's|[^a-z0-9-]|-|g')" >> "$GITHUB_OUTPUT"
-#               echo "sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
-#             fi
-#         - uses: actions/create-github-app-token@v1
-#           id: app-token
-#           with:
-#             app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
-#             private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
-#             owner: decocms
-#             repositories: deco-start
-#         - env:
-#             GH_TOKEN: ${{ steps.app-token.outputs.token }}
-#           run: |
-#             gh workflow run preview.yml \
-#               --repo decocms/deco-start \
-#               --ref v3 \
-#               -f site_owner=${GITHUB_REPOSITORY%%/*} \
-#               -f site_name=${GITHUB_REPOSITORY##*/} \
-#               -f site_sha=${{ steps.meta.outputs.sha }} \
-#               -f alias=${{ steps.meta.outputs.alias }} \
-#               -f pr_number=${{ github.event.pull_request.number || '' }}
-#
-# Note on forks: pull_request runs from forked repos cannot access repo
-# secrets (incl. DECOCMS_DEPLOYER_APP_*), so they cannot trigger previews.
-
-on:
-  workflow_dispatch:
-    inputs:
-      site_owner:
-        description: "GitHub org of the storefront. Defaults to deco-sites."
-        type: string
-        required: false
-        default: deco-sites
-      site_name:
-        description: "Storefront repo basename. Becomes the Cloudflare worker name."
-        type: string
-        required: true
-      site_sha:
-        description: "Commit sha to build & preview. Trusted as-is (preview alias has no production blast radius)."
-        type: string
-        required: true
-      alias:
-        description: "Preview alias name (e.g. pr-123, feature-foo). Must match wrangler alias rules."
-        type: string
-        required: true
-      pr_number:
-        description: "Optional PR number on the storefront repo. If set, the preview URL is commented back on the PR."
-        type: string
-        required: false
-        default: ""
-
-permissions:
-  contents: read
-
-concurrency:
-  group: preview-${{ inputs.site_owner }}-${{ inputs.site_name }}-${{ inputs.alias }}
-  cancel-in-progress: true
-
-jobs:
-  preview:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout deco-start (template + scripts)
-        uses: actions/checkout@v4
-
-      - name: Validate alias format
-        env:
-          ALIAS: ${{ inputs.alias }}
-        run: |
-          set -euo pipefail
-          if ! echo "$ALIAS" | grep -Eq '^[a-z0-9][a-z0-9-]{0,62}$'; then
-            echo "::error::Invalid alias '$ALIAS'. Must be lowercase alphanumeric/hyphens, max 63 chars, start with alphanumeric."
-            exit 1
-          fi
-
-      - name: Mint App token for storefront checkout
-        id: app-token
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
-          private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
-          owner: ${{ inputs.site_owner }}
-          repositories: ${{ inputs.site_name }}
-
-      - name: Checkout storefront at requested sha
-        uses: actions/checkout@v4
-        with:
-          repository: ${{ inputs.site_owner }}/${{ inputs.site_name }}
-          ref: ${{ inputs.site_sha }}
-          token: ${{ steps.app-token.outputs.token }}
-          path: site
-          fetch-depth: 1
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Restore npm cache
-        uses: actions/cache@v4
-        with:
-          path: ~/.npm
-          key: npm-${{ runner.os }}-${{ hashFiles('site/package-lock.json') }}
-          restore-keys: npm-${{ runner.os }}-
-
-      - name: Install dependencies
-        working-directory: site
-        run: |
-          if [ ! -f package-lock.json ]; then
-            npm install --package-lock-only
-          fi
-          npm ci
-
-      - name: Build
-        working-directory: site
-        run: npm run build
-
-      - name: Generate wrangler.jsonc from template
-        working-directory: site
-        env:
-          DECO_START_PATH: "${{ github.workspace }}"
-          WORKER_NAME: ${{ inputs.site_name }}
-          OUTPUT_PATH: "./wrangler.jsonc"
-        run: node "$DECO_START_PATH/scripts/deploy/build-wrangler-config.mjs"
-
-      - name: Upload preview version
-        id: deploy
-        working-directory: site
-        env:
-          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
-          ALIAS: ${{ inputs.alias }}
-        run: |
-          set +e
-          OUTPUT=$(npx wrangler versions upload --preview-alias "$ALIAS" 2>&1)
-          EXIT_CODE=$?
-          set -e
-          echo "$OUTPUT"
-          if [ $EXIT_CODE -ne 0 ]; then
-            echo "::error::wrangler versions upload failed with exit code $EXIT_CODE"
-            exit $EXIT_CODE
-          fi
-          PREVIEW_URL=$(echo "$OUTPUT" | grep 'Version Preview URL:' | sed 's/.*Version Preview URL: //')
-          ALIAS_URL=$(echo "$OUTPUT" | grep 'Version Preview Alias URL:' | sed 's/.*Version Preview Alias URL: //')
-          echo "preview_url=${PREVIEW_URL}" >> "$GITHUB_OUTPUT"
-          echo "alias_url=${ALIAS_URL}" >> "$GITHUB_OUTPUT"
-
-      - name: Mint App token for PR comment
-        id: comment-token
-        if: inputs.pr_number != ''
-        uses: actions/create-github-app-token@v1
-        with:
-          app-id: ${{ secrets.DECOCMS_DEPLOYER_APP_ID }}
-          private-key: ${{ secrets.DECOCMS_DEPLOYER_APP_PRIVATE_KEY }}
-          owner: ${{ inputs.site_owner }}
-          repositories: ${{ inputs.site_name }}
-          permission-pull-requests: write
-
-      - name: Comment preview URL on storefront PR
-        if: inputs.pr_number != ''
-        env:
-          GH_TOKEN: ${{ steps.comment-token.outputs.token }}
-          REPO: ${{ inputs.site_owner }}/${{ inputs.site_name }}
-          PR_NUMBER: ${{ inputs.pr_number }}
-          PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
-          ALIAS_URL: ${{ steps.deploy.outputs.alias_url }}
-        run: |
-          set -euo pipefail
-          BODY=$(printf '### Preview deployed\n\n| | URL |\n|---|---|\n| **Version** | %s |\n| **Alias** | %s |\n' "$PREVIEW_URL" "$ALIAS_URL")
-          gh pr comment "$PR_NUMBER" --repo "$REPO" --body "$BODY"