catalyst-core 0.3.0-beta.5 → 0.3.0-canary.2

package/dist/server/utils/validator.js

@@ -1,164 +1,139 @@
-import pc from "picocolors"
+import pc from "ansis";
+import { createError, formatError, ERROR_CODES } from "../../errors/index.js";
+import { resolveOutputMode, getDebugEnvInfo } from "../../scripts/scriptUtils.js";
 
-const handleError = (e) => {
-    console.log(pc.red("Failed to start server: "), e)
-}
+// Resolved once at module load — this module runs inside expressServer.js,
+// spawned by serve.js/start.js which forward the mode via
+// CATALYST_OUTPUT_MODE. Passed an empty argv on purpose: this process never
+// sees the parent's CLI flags, so only CATALYST_OUTPUT_MODE is real input.
+const outputMode = resolveOutputMode([], process.env);
 
-const validatePreInitServer = (fn) => {
-    try {
-        if (!fn) throw new Error("preServerInit named function should be defined in server/index.js")
-        if (typeof fn !== "function")
-            throw new Error("preServerInit should be function present in server/index.js")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateMiddleware = (fn) => {
-    try {
-        if (!fn) throw new Error("addMiddlewares named function not found in server/server.js")
-        if (typeof fn !== "function")
-            throw new Error("addMiddlewares should be function present in server/server.js")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateReducerFunction = (fn) => {
-    try {
-        if (!fn) throw new Error("reducer not found in src/js/containers/App/reducer")
-        if (typeof fn !== "function")
-            throw new Error("reducer should present in src/js/containers/App/reducer")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateConfigFile = (obj) => {
-    try {
-        if (!obj) throw new Error("config not found in config folder")
-        if (typeof obj !== "object")
-            throw new Error(
-                "config object should be exported from config folder inside your project root directory"
-            )
-        if (typeof obj === "object") {
-            const requiredConfigKeys = {
-                NODE_SERVER_HOSTNAME: "",
-                NODE_SERVER_PORT: "",
-                WEBPACK_DEV_SERVER_HOSTNAME: "",
-                WEBPACK_DEV_SERVER_PORT: "",
-                BUILD_OUTPUT_PATH: "",
-                PUBLIC_STATIC_ASSET_PATH: "",
-                PUBLIC_STATIC_ASSET_URL: "",
-                CLIENT_ENV_VARIABLES: [],
-                ANALYZE_BUNDLE: "",
-            }
-            for (let key in requiredConfigKeys) {
-                if (!(key in obj)) throw new Error(`${key} key not found inside config.json`)
-            }
-        }
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validatePackageJson = (obj) => {
-    try {
-        if (!obj) throw new Error("package.json not found in the project")
-        if (typeof obj !== "object")
-            throw new Error("package.json should be defined in project root directory")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateModuleAlias = (obj) => {
-    try {
-        if (!obj) throw new Error("moduleAliases not found in package.json file present in root directory.")
-        if (typeof obj !== "object")
-            throw new Error("moduleAliases named object should be exported from package.json")
-        if (typeof obj === "object") {
-            const requiredModuleAliases = {
-                "@api": "api.js",
-                "@containers": "src/js/containers",
-                "@server": "server",
-                "@config": "config",
-                "@css": "src/static/css",
-                "@routes": "src/js/routes/",
-            }
-            for (let key in requiredModuleAliases) {
-                if (key.includes("catalyst"))
-                    throw new Error(`Catalyst keyword is restricted for defining aliases`)
-                if (!(key in obj)) throw new Error(`${key} module alias not defined inside package.json`)
-            }
-        }
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateConfigureStore = (fn) => {
-    try {
-        if (!fn) throw new Error("configureStore not found in file src/js/store/index.js")
-        if (typeof fn !== "function")
-            throw new Error("configureStore should be function exported from src/js/store/index.js")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateGetRoutes = (fn) => {
-    try {
-        if (!fn) throw new Error("getRoutes not found in file src/js/routes/utils.js")
-        if (typeof fn !== "function")
-            throw new Error("getRoutes should be function exported from src/js/routers/index.js")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
-
-const validateCustomDocument = (fn) => {
-    try {
-        if (!fn) throw new Error("document not found in file server/document.js")
-        if (typeof fn !== "function")
-            throw new Error("document should be a react component exported from server/document.js")
-        return true
-    } catch (e) {
-        handleError(e)
-    }
-}
+// The validate* functions are PURE: they return `null` when the input is
+// valid and a `CatalystError` (never thrown, never logged) when it isn't.
+// This lets two very different callers share one definition:
+//   - scripts/preflight.js (parent CLI process) collects the errors from
+//     several validators and prints them all, then exits non-zero.
+//   - the in-server call sites (expressServer.js, handler.jsx) log the
+//     single error and fall back, keeping the request alive.
+// `handleError` below is the shared "log it, in whatever output mode" helper
+// those in-server sites use.
+const handleError = e => {
+  const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
+  if (outputMode === "default") {
+    console.log(pc.red("Failed to start server: "), formatError(e, outputMode));
+  } else {
+    console.log(formatError(e, outputMode, debugEnv));
+  }
+};
+const validatePreInitServer = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_PRE_SERVER_INIT_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_PRE_SERVER_INIT_NOT_FUNCTION);
+  return null;
+};
+const validateMiddleware = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_MIDDLEWARE_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_MIDDLEWARE_NOT_FUNCTION);
+  return null;
+};
+const validateReducerFunction = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_REDUCER_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_REDUCER_NOT_FUNCTION);
+  return null;
+};
+const validateConfigFile = obj => {
+  if (!obj) return createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING);
+  if (typeof obj !== "object") return createError(ERROR_CODES.PREFLIGHT_CONFIG_NOT_OBJECT);
+  const requiredConfigKeys = ["NODE_SERVER_HOSTNAME", "NODE_SERVER_PORT", "BUILD_OUTPUT_PATH", "PUBLIC_STATIC_ASSET_PATH", "PUBLIC_STATIC_ASSET_URL", "CLIENT_ENV_VARIABLES"];
+  for (const key of requiredConfigKeys) {
+    if (!(key in obj)) return createError(ERROR_CODES.PREFLIGHT_CONFIG_KEY_MISSING, {
+      details: `${key} key not found inside config.json`
+    });
+  }
+  return null;
+};
+const validatePackageJson = obj => {
+  if (!obj) return createError(ERROR_CODES.PREFLIGHT_PACKAGE_JSON_MISSING);
+  if (typeof obj !== "object") return createError(ERROR_CODES.PREFLIGHT_PACKAGE_JSON_INVALID);
+  return null;
+};
+const validateModuleAlias = obj => {
+  if (!obj) return createError(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_MISSING);
+  if (typeof obj !== "object") return createError(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_NOT_OBJECT);
+  // A consumer app must not shadow the framework's own "@catalyst*" aliases
+  // (both "@catalyst/…" and "@catalyst-…" are reserved) with its own
+  // moduleAliases entries — check the INPUT's keys, not the required list
+  // (that check was previously on the wrong side and could never fire;
+  // PREFLIGHT-008). Anchored to the start and case-insensitive: a bare
+  // `.includes("catalyst")` also (wrongly) rejected unrelated names like
+  // "@my-catalyst-helpers", which don't shadow anything.
+  if (Object.keys(obj).some(key => /^@catalyst($|[/-])/i.test(key))) return createError(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_RESTRICTED);
+  const requiredModuleAliases = ["@api", "@containers", "@server", "@config", "@css", "@routes"];
+  for (const key of requiredModuleAliases) {
+    if (!(key in obj)) return createError(ERROR_CODES.PREFLIGHT_MODULE_ALIAS_KEY_MISSING, {
+      details: `${key} module alias not defined inside package.json`
+    });
+  }
+  return null;
+};
+const validateConfigureStore = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_CONFIGURE_STORE_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_CONFIGURE_STORE_NOT_FUNCTION);
+  return null;
+};
+const validateGetRoutes = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_GET_ROUTES_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_GET_ROUTES_NOT_FUNCTION);
+  return null;
+};
+const validateCustomDocument = fn => {
+  if (!fn) return createError(ERROR_CODES.PREFLIGHT_CUSTOM_DOCUMENT_MISSING);
+  if (typeof fn !== "function") return createError(ERROR_CODES.PREFLIGHT_CUSTOM_DOCUMENT_NOT_FUNCTION);
+  return null;
+};
 
 /**
- * Safely call a function, catching and logging any errors.
- * Used for user-defined hooks (onRouteMatch, onFetcherError, etc.)
- * that should never crash the SSR pipeline.
+ * Safely call a function, catching and logging any errors — including a
+ * rejected promise if `fn` is async. Used for user-defined hooks
+ * (preServerInit, onRouteMatch, onFetcherError, onServerError, etc.) that
+ * should never crash the SSR pipeline.
+ *
+ * Async by necessity: awaiting `fn`'s return value is the only way to catch
+ * a rejection in the same try/catch as a synchronous throw. Existing call
+ * sites that don't await safeCall(...) are unaffected — they already
+ * treated its return value as fire-and-forget — but the rejection now
+ * reaches the same structured-error path a sync throw does, instead of
+ * surfacing as an unhandled promise rejection.
  */
-const safeCall = (fn, ...args) => {
-    if (typeof fn !== "function") return
-    try {
-        return fn(...args)
-    } catch (e) {
-        console.error("Error in user hook:", e)
-    }
-}
+const safeCall = async (fn, ...args) => {
+  if (typeof fn !== "function") return;
+  try {
+    return await fn(...args);
+  } catch (e) {
+    const wrapped = createError(ERROR_CODES.PROCESS_USER_HOOK_FAILED, {
+      cause: e
+    });
+    const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
+    console.error(formatError(wrapped, outputMode, debugEnv));
+  }
+};
 
-export {
-    validateConfigFile,
-    validateConfigureStore,
-    validateCustomDocument,
-    validateGetRoutes,
-    validatePackageJson,
-    validateReducerFunction,
-    validateModuleAlias,
-    validatePreInitServer,
-    validateMiddleware,
-    safeCall,
-}
+/**
+ * Same as safeCall, but names the specific hook (e.g. "preServerInit") in the
+ * error so it's identifiable rather than generic. Used at call sites that know
+ * which hook they're invoking.
+ */
+const safeCallNamed = async (hookName, fn, ...args) => {
+  if (typeof fn !== "function") return;
+  try {
+    return await fn(...args);
+  } catch (e) {
+    const code = hookName === "preServerInit" ? ERROR_CODES.PROCESS_SERVER_INIT_FAILED : ERROR_CODES.PROCESS_USER_HOOK_FAILED;
+    const wrapped = createError(code, {
+      details: `The "${hookName}" hook threw. See the cause below.`,
+      cause: e
+    });
+    const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined;
+    console.error(formatError(wrapped, outputMode, debugEnv));
+  }
+};
+export { handleError, validateConfigFile, validateConfigureStore, validateCustomDocument, validateGetRoutes, validatePackageJson, validateReducerFunction, validateModuleAlias, validatePreInitServer, validateMiddleware, safeCall, safeCallNamed };

package/dist/vite/inject-cache-key-plugin.js

@@ -1,9 +1,6 @@
 import path from "path"
-import { readFileSync, existsSync, statSync } from "fs"
-import { fileURLToPath } from "url"
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
+import { existsSync, statSync } from "fs"
+import { getModuleAliases } from "./moduleAliases.js"
 
 // Cache for loaded aliases
 let aliasCache = null
@@ -18,28 +15,7 @@ function loadAliases() {
     }
 
     const appRoot = process.env.src_path || process.cwd()
-    const appPackageJsonConfig = path.resolve(appRoot, "package.json")
-    const catalystPackageJsonConfig = path.resolve(__dirname, "../../package.json")
-
-    let appModuleAliases = {}
-    let catalystModuleAliases = {}
-
-    try {
-        const appPackageJson = JSON.parse(readFileSync(appPackageJsonConfig, "utf8"))
-        appModuleAliases = appPackageJson._moduleAliases || {}
-    } catch {
-        // Silently fail if app package.json doesn't exist or is invalid
-    }
-
-    try {
-        const catalystPackageJson = JSON.parse(readFileSync(catalystPackageJsonConfig, "utf8"))
-        catalystModuleAliases = catalystPackageJson._moduleAliases || {}
-    } catch {
-        // Silently fail if catalyst package.json doesn't exist or is invalid
-    }
-
-    // Application aliases take precedence over catalyst-core aliases
-    const allAliases = { ...catalystModuleAliases, ...appModuleAliases }
+    const allAliases = getModuleAliases(appRoot)
 
     aliasCache = {}
     for (const [alias, aliasPath] of Object.entries(allAliases)) {

package/dist/vite/moduleAliases.js

@@ -0,0 +1,36 @@
+// Single source of truth for merging the consuming app's `_moduleAliases` with
+// catalyst-core's own. Three call sites (vite.config.js, node-loader.mjs,
+// inject-cache-key-plugin.js) previously each read both package.jsons and
+// merged them inline, and their spread order had drifted apart. Path resolution
+// deliberately stays with the callers — they resolve differently — so this owns
+// only the reading and the precedence.
+
+import path from "path"
+import fs from "fs"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+function readModuleAliases(packageJsonPath) {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"))
+        return packageJson._moduleAliases || {}
+    } catch {
+        return {}
+    }
+}
+
+/**
+ * Raw (unresolved) alias map for an app root, with the app's own aliases taking
+ * precedence over catalyst-core's on key collision.
+ *
+ * @param {string} [appRoot] - The consuming application's root directory. Defaults to process.cwd().
+ * @returns {Record<string, string>} Merged alias name -> raw alias path.
+ */
+export function getModuleAliases(appRoot = process.cwd()) {
+    const appModuleAliases = readModuleAliases(path.resolve(appRoot, "package.json"))
+    const catalystModuleAliases = readModuleAliases(path.resolve(__dirname, "../../package.json"))
+
+    return { ...catalystModuleAliases, ...appModuleAliases }
+}

package/dist/vite/node-loader.mjs

@@ -3,9 +3,7 @@ import { dirname, resolve as resolvePath, join, extname } from "path"
 import { readFileSync, existsSync, statSync } from "fs"
 import { createRequire } from "module"
 import { transformSync } from "esbuild"
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
+import { getModuleAliases } from "./moduleAliases.js"
 
 // Cache for loaded aliases
 let aliasCache = null
@@ -20,32 +18,7 @@ function loadAliases() {
 
     const appRoot = process.env.src_path || process.cwd()
 
-    const appPackageJsonConfig = resolvePath(appRoot, "package.json")
-    const catalystPackageJsonConfig = resolvePath(__dirname, "../../package.json")
-
-    let appModuleAliases = {}
-    let catalystModuleAliases = {}
-
-    // Read aliases from consuming application's package.json
-    try {
-        const appPackageJsonContent = readFileSync(appPackageJsonConfig, "utf8")
-        const appPackageJson = JSON.parse(appPackageJsonContent)
-        appModuleAliases = appPackageJson._moduleAliases || {}
-    } catch (error) {
-        // Silently fail if app package.json doesn't exist or is invalid
-    }
-
-    // Read aliases from catalyst-core's package.json
-    try {
-        const catalystPackageJsonContent = readFileSync(catalystPackageJsonConfig, "utf8")
-        const catalystPackageJson = JSON.parse(catalystPackageJsonContent)
-        catalystModuleAliases = catalystPackageJson._moduleAliases || {}
-    } catch (error) {
-        // Silently fail if catalyst package.json doesn't exist or is invalid
-    }
-
-    // Application aliases take precedence over catalyst-core aliases
-    const allAliases = { ...catalystModuleAliases, ...appModuleAliases }
+    const allAliases = getModuleAliases(appRoot)
 
     // Convert aliases to resolved paths
     aliasCache = {}

package/dist/vite/resolveDevServerConfig.js

@@ -10,7 +10,9 @@
 export function resolveDevBase(devServer = {}) {
     const base = devServer?.base
     if (!base || base === "/") return "/"
-    return `/${String(base).trim().replace(/^\/+|\/+$/g, "")}`
+    return `/${String(base)
+        .trim()
+        .replace(/^\/+|\/+$/g, "")}`
 }
 
 /**
@@ -36,6 +38,7 @@ export function resolveDevFsAllow(devFs, frameworkPaths) {
  * first so the framework-owned `hmr` and `fs` always win.
  */
 export function buildDevServer(devServer = {}, { frameworkPaths, isProduction = false } = {}) {
+    // eslint-disable-next-line no-unused-vars -- base is destructured only to omit it from serverOverrides
     const { base, hmr, fs, ...serverOverrides } = devServer
     return {
         ...serverOverrides,

package/dist/vite/vite.config.js

@@ -4,6 +4,7 @@ import svgr from "vite-plugin-svgr"
 import { builtinModules, createRequire } from "node:module"
 import { loadCustomViteConfig } from "./loadCustomViteConfig.js"
 import { resolveDevBase, buildDevServer } from "./resolveDevServerConfig.js"
+import { getModuleAliases } from "./moduleAliases.js"
 
 /**
  * Treat all .scss imports as CSS modules (webpack compat).
@@ -103,35 +104,7 @@ const __dirname = dirname(__filename)
 import path from "path"
 import fs from "fs"
 
-const packageJsonConfig = path.resolve(process.env.src_path, "package.json")
-const catalystPackageJsonConfig = path.resolve(__dirname, "../../package.json")
-
-let packageJsonContent, catalystPackageJsonContent
-let _moduleAliases = {},
-    catalyst_moduleAliases = {}
-
-try {
-    packageJsonContent = fs.readFileSync(packageJsonConfig, "utf8")
-    const packageJson = JSON.parse(packageJsonContent)
-    _moduleAliases = packageJson._moduleAliases || {}
-} catch (error) {
-    // nosemgrep: javascript.lang.security.audit.unsafe-formatstring.unsafe-formatstring - packageJsonConfig is a build-time-resolved local path, not attacker-controlled; console.warn here does no printf-style substitution.
-    console.warn(`Failed to read or parse package.json from ${packageJsonConfig}:`, error.message)
-}
-
-try {
-    catalystPackageJsonContent = fs.readFileSync(catalystPackageJsonConfig, "utf8")
-    const catalystPackageJson = JSON.parse(catalystPackageJsonContent)
-    catalyst_moduleAliases = catalystPackageJson._moduleAliases || {}
-} catch (error) {
-    console.warn(
-        // nosemgrep: javascript.lang.security.audit.unsafe-formatstring.unsafe-formatstring - catalystPackageJsonConfig is a build-time-resolved local path, not attacker-controlled; console.warn here does no printf-style substitution.
-        `Failed to read or parse catalyst package.json from ${catalystPackageJsonConfig}:`,
-        error.message
-    )
-}
-
-const allAliases = { ..._moduleAliases, ...catalyst_moduleAliases }
+const allAliases = getModuleAliases(process.env.src_path)
 
 import { imageUrl, fontUrl } from "./scssParams.js"
 

package/dist/web-router/components/MetaTag.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @description renders meta tags component assigned to setMetaData
+ */
+export declare const MetaTag: () => any;

package/dist/web-router/components/MetaTag.jsx

@@ -1,34 +1,32 @@
-import React, { useContext, useState, useEffect } from "react"
-import { HelmetProvider, Helmet } from "react-helmet-async"
-import { OneMgRouterContext } from "../context.jsx"
-import { useRouterData } from "./RouterDataProvider.jsx"
-import { deleteHeadTagsByDataAttribute, getMetaData } from "../utils/metaDataUtils.jsx"
-import { useLocation } from "react-router"
+import React, { useContext, useState, useEffect } from "react";
+import { HelmetProvider, Helmet } from "react-helmet-async";
+import { OneMgRouterContext } from "../context.jsx";
+import { useRouterData } from "./RouterDataProvider.jsx";
+import { deleteHeadTagsByDataAttribute, getMetaData } from "../utils/metaDataUtils.jsx";
+import { useLocation } from "react-router";
 
 /**
  * @description renders meta tags component assigned to setMetaData
  */
 export const MetaTag = () => {
-    const { matchedRoutes } = useContext(OneMgRouterContext)
-    const routeData = useRouterData()
-    const location = useLocation()
-    const [metaTags, setMetaTags] = useState([<meta key={0}></meta>])
-
-    useEffect(() => {
-        const mergedMetaTags = getMetaData(matchedRoutes, routeData)
-        if (Array.isArray(mergedMetaTags) && mergedMetaTags.length > 0) {
-            setMetaTags(mergedMetaTags)
-        }
-        return () => deleteHeadTagsByDataAttribute("catalyst")
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [location])
-
-    if (Array.isArray(metaTags) && metaTags.length >= 0) {
-        return (
-            <HelmetProvider>
-                <Helmet>{metaTags}</Helmet>
-            </HelmetProvider>
-        )
+  const {
+    matchedRoutes
+  } = useContext(OneMgRouterContext);
+  const routeData = useRouterData();
+  const location = useLocation();
+  const [metaTags, setMetaTags] = useState([<meta key={0}></meta>]);
+  useEffect(() => {
+    const mergedMetaTags = getMetaData(matchedRoutes, routeData);
+    if (Array.isArray(mergedMetaTags) && mergedMetaTags.length > 0) {
+      setMetaTags(mergedMetaTags);
     }
-    return <></>
-}
+    return () => deleteHeadTagsByDataAttribute("catalyst");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location]);
+  if (Array.isArray(metaTags) && metaTags.length >= 0) {
+    return <HelmetProvider>
+                <Helmet>{metaTags}</Helmet>
+            </HelmetProvider>;
+  }
+  return <></>;
+};