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

package/dist/native/terminalProgress.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var pc = _interopRequireWildcard(require("picocolors"));
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+var _ansis = _interopRequireDefault(require("ansis"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 class TerminalProgress {
   constructor(steps, title = "Setup Progress", options = {}) {
     this.steps = new Map(Object.entries(steps).map(([id, description]) => [id, {
@@ -44,7 +44,7 @@ class TerminalProgress {
     console.log("\n".repeat(this.options.titlePaddingTop));
 
     // Print the title
-    console.log(`${pc.cyan(pc.bold(title))}`);
+    console.log(`${_ansis.default.cyan(_ansis.default.bold(title))}`);
 
     // Process and print each line of content
     for (const line of content) {
@@ -58,7 +58,7 @@ class TerminalProgress {
           color = "white"
         } = line;
         const indentation = " ".repeat(this.options.stepPaddingLeft + indent * 3);
-        const coloredText = pc[color] ? pc[color](text) : text;
+        const coloredText = _ansis.default[color] ? _ansis.default[color](text) : text;
         console.log(`${indentation}${prefix}${coloredText}`);
       }
     }
@@ -103,13 +103,13 @@ class TerminalProgress {
     const icon = TerminalProgress.icons[step.status] || TerminalProgress.icons.pending;
     switch (step.status) {
       case "completed":
-        return pc.green(icon);
+        return _ansis.default.green(icon);
       case "error":
-        return pc.red(icon);
+        return _ansis.default.red(icon);
       case "running":
-        return pc.blue(icon);
+        return _ansis.default.blue(icon);
       default:
-        return pc.gray(icon);
+        return _ansis.default.gray(icon);
     }
   }
   clearLines() {
@@ -126,23 +126,23 @@ class TerminalProgress {
     switch (type) {
       case "success":
         icon = TerminalProgress.icons.completed;
-        color = pc.green;
+        color = _ansis.default.green;
         break;
       case "error":
         icon = TerminalProgress.icons.error;
-        color = pc.red;
+        color = _ansis.default.red;
         break;
       case "warning":
         icon = TerminalProgress.icons.warning;
-        color = pc.yellow;
+        color = _ansis.default.yellow;
         break;
       case "prompt":
         icon = TerminalProgress.icons.prompt;
-        color = pc.yellow;
+        color = _ansis.default.yellow;
         break;
       default:
         icon = TerminalProgress.icons.info;
-        color = pc.blue;
+        color = _ansis.default.blue;
     }
     console.log(`${" ".repeat(this.options.stepPaddingLeft)}${color(icon)} ${message}`);
     this.resume();
@@ -158,8 +158,8 @@ class TerminalProgress {
     currentLineCount += this.options.titlePaddingTop;
 
     // Render title
-    output += `${pc.bold(pc.cyan(this.title))}\n`;
-    output += `${pc.gray("─".repeat(this.title.length))}\n`;
+    output += `${_ansis.default.bold(_ansis.default.cyan(this.title))}\n`;
+    output += `${_ansis.default.gray("─".repeat(this.title.length))}\n`;
     currentLineCount += 2;
 
     // Add padding after title
@@ -169,13 +169,13 @@ class TerminalProgress {
     // Render steps
     for (const step of this.steps.values()) {
       const icon = this.getStepIcon(step);
-      const description = step.status === "error" ? pc.red(step.description) : step.status === "completed" ? pc.green(step.description) : step.status === "running" ? pc.blue(step.description) : pc.gray(step.description);
+      const description = step.status === "error" ? _ansis.default.red(step.description) : step.status === "completed" ? _ansis.default.green(step.description) : step.status === "running" ? _ansis.default.blue(step.description) : _ansis.default.gray(step.description);
       const stepPadding = " ".repeat(this.options.stepPaddingLeft);
       output += `${stepPadding}${icon} ${description}\n`;
       currentLineCount++;
       if (step.status === "error" && step.error) {
         const errorPadding = " ".repeat(this.options.errorPaddingLeft);
-        output += `${errorPadding}${pc.red("↳")} ${pc.red(step.error)}\n`;
+        output += `${errorPadding}${_ansis.default.red("↳")} ${_ansis.default.red(step.error)}\n`;
         currentLineCount++;
       }
 

package/dist/router/ClientRouter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @returns returns browsers routers (client routes)
+ */
+declare const clientRouter: ({ routerInitialState }: {
+    routerInitialState?: any;
+    store?: any;
+}) => import("react-router").DataRouter;
+export default clientRouter;

package/dist/router/ClientRouter.js

@@ -1,15 +1,17 @@
-import { createBrowserRouter } from "../index.jsx"
-import { preparedRoutes } from "@catalyst/template/src/js/routes/utils"
-import { registerCatalystServiceWorker } from "../offline/registerServiceWorker.js"
-
-registerCatalystServiceWorker()
+import { createBrowserRouter } from "react-router";
+import { preparedRoutes } from "@catalyst/template/src/js/routes/utils";
+import { registerCatalystServiceWorker } from "../offline/registerServiceWorker.js";
+registerCatalystServiceWorker();
 
 /**
  * @returns returns browsers routers (client routes)
  */
-const clientRouter = ({ routerInitialState }) => {
-    const browserRouter = createBrowserRouter(preparedRoutes({ routerInitialState }))
-    return browserRouter
-}
-
-export default clientRouter
+const clientRouter = ({
+  routerInitialState
+}) => {
+  const browserRouter = createBrowserRouter(preparedRoutes({
+    routerInitialState
+  }));
+  return browserRouter;
+};
+export default clientRouter;

package/dist/router/ServerRouter.d.ts

@@ -0,0 +1,13 @@
+import type { Store } from "redux";
+/**
+ * Redux data handed to the server router by the SSR handler. `store` is the
+ * app's redux store (created by the app's `createStore`); `intialData` is the
+ * router initial state hydrated onto the client. The spelling of `intialData`
+ * is part of the frozen internal shape and is deliberately preserved.
+ */
+export interface ServerRouterProps {
+    store?: Store;
+    intialData?: any;
+}
+declare const ServerRouter: (reduxData: ServerRouterProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export default ServerRouter;

package/dist/router/ServerRouter.js

@@ -1,9 +1,21 @@
-import { useRoutes } from "../index.jsx"
-import { preparedRoutes } from "@catalyst/template/src/js/routes/utils"
+import { useRoutes } from "react-router";
+import { preparedRoutes } from "@catalyst/template/src/js/routes/utils";
 
-const ServerRouter = (reduxData) => {
-    const { store, intialData } = reduxData
-    return useRoutes(preparedRoutes({ store, routerInitialState: intialData }))
-}
+/**
+ * Redux data handed to the server router by the SSR handler. `store` is the
+ * app's redux store (created by the app's `createStore`); `intialData` is the
+ * router initial state hydrated onto the client. The spelling of `intialData`
+ * is part of the frozen internal shape and is deliberately preserved.
+ */
 
-export default ServerRouter
+const ServerRouter = reduxData => {
+  const {
+    store,
+    intialData
+  } = reduxData;
+  return useRoutes(preparedRoutes({
+    store,
+    routerInitialState: intialData
+  }));
+};
+export default ServerRouter;

package/dist/scripts/build.js

@@ -1,10 +1,18 @@
 import path from "path"
 import { spawn } from "child_process"
-import { arrayToObject } from "./scriptUtils.js"
+import { arrayToObject, resolveOutputMode, getDebugEnvInfo } from "./scriptUtils.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
 import { readFileSync, existsSync, rmSync } from "fs"
 import { createRequire } from "module"
+import { wrapForeignError, formatError } from "../errors/index.js"
+import { runStaticPreflightOrExit } from "./preflight.js"
+
+// Fail fast on a misconfigured app (missing/invalid config.json, package.json,
+// or moduleAliases) with a coded, doc-linked error — must run before the raw
+// config.json read below, which would otherwise crash with a bare
+// ENOENT/SyntaxError on a broken config.
+runStaticPreflightOrExit()
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -42,6 +50,7 @@ function runBuildStep(args, options) {
 async function build() {
     const commandLineArguments = process.argv.slice(2)
     const argumentsObject = arrayToObject(commandLineArguments)
+    const outputMode = resolveOutputMode(process.argv)
     const dirname = path.resolve(__dirname, "../../")
 
     // Read package.json
@@ -63,6 +72,7 @@ async function build() {
         VITE_BUILD_MODE: "true",
         APPLICATION: name || "catalyst_app",
         NODE_OPTIONS: `--loader ${loaderPath}`,
+        CATALYST_OUTPUT_MODE: outputMode,
         ...argumentsObject,
         filterKeys: JSON.stringify([
             "src_path",
@@ -93,8 +103,10 @@ async function build() {
                 env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "client" },
             }),
         ])
-    } catch {
+    } catch (err) {
         console.error("❌ Build failed!")
+        const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined
+        console.error(formatError(wrapForeignError("BUNDLE", err), outputMode, debugEnv))
         process.exit(1)
     }
 

package/dist/scripts/loadEnvironmentVariables.js

@@ -1,13 +1,14 @@
 import path from "path"
 import fs from "fs"
 
-const appConfigPath = path.resolve(process.env.src_path, "config/config.json")
-// import { validateConfigFile } from "../scripts/validator"
 /**
  * @description stores all config.json key value into process.env before server starts.
  */
 const loadEnvironmentVariables = async () => {
     try {
+        // Resolved at call time, not import time, so preServerInit.js can report a
+        // missing src_path before any path is built from it.
+        const appConfigPath = path.resolve(process.env.src_path, "config/config.json")
         const filterKeys = JSON.parse(process.env.filterKeys)
         const configContent = fs.readFileSync(appConfigPath, "utf8")
         const appConfig = JSON.parse(configContent)

package/dist/scripts/plugins.js

@@ -3,7 +3,7 @@ import path from "node:path"
 import readline from "node:readline"
 import { createRequire } from "node:module"
 import { fileURLToPath } from "node:url"
-import { bold, cyan, dim, green, red, yellow } from "picocolors"
+import { bold, cyan, dim, green, red, yellow } from "ansis"
 
 const require = createRequire(import.meta.url)
 const { discoverInternalPlugins, resolveInternalPluginsRoot } = require("../native/internalPluginUtils.js")

package/dist/scripts/preServerInit.js

@@ -1,13 +1,59 @@
 import path from "path"
+import { createRequire } from "module"
 import loadEnvironmentVariables from "./loadEnvironmentVariables.js"
-import { safeCall } from "../server/utils/validator.js"
+import { validatePreInitServer, handleError, safeCallNamed } from "../server/utils/validator.js"
+
+// src_path is the application root, set by the CLI when it spawns this process.
+// Without it every path below would be resolved against undefined.
+const appRoot = process.env.src_path
+if (!appRoot) {
+    throw new Error(
+        "catalyst-core: process.env.src_path is not set, so the application root cannot be resolved. " +
+            "Start the server with `catalyst serve` or `catalyst start` from the application root."
+    )
+}
+
+// react-router is a peer dependency: fail loudly at startup rather than on a
+// missing export deep inside a render. Resolve from the app root, not from
+// catalyst-core's own tree — the app's copy is the one vite and SSR load.
+const REQUIRED_REACT_ROUTER = "^7.18.2"
+const appRequire = createRequire(path.join(appRoot, "package.json"))
+let reactRouterVersion
+try {
+    reactRouterVersion = appRequire("react-router/package.json").version
+} catch {
+    throw new Error(
+        `catalyst-core requires react-router ${REQUIRED_REACT_ROUTER} as a peer dependency, but it is not installed. ` +
+            `Install it: npm install react-router@${REQUIRED_REACT_ROUTER}`
+    )
+}
+const [major, minor, patch] = reactRouterVersion.split("-")[0].split(".").map(Number)
+const isValid =
+    [major, minor, patch].every(Number.isFinite) &&
+    major === 7 &&
+    (minor > 18 || (minor === 18 && patch >= 2))
+if (!isValid) {
+    throw new Error(
+        `catalyst-core requires react-router ${REQUIRED_REACT_ROUTER}, but found ${reactRouterVersion}. ` +
+            `Install a compatible version: npm install react-router@${REQUIRED_REACT_ROUTER}`
+    )
+}
 
 let preServerInit
 try {
-    const hooks = await import(path.join(process.env.src_path, "server/index.js"))
+    const hooks = await import(path.join(appRoot, "server/index.js"))
     preServerInit = hooks.preServerInit
 } catch {
     // No hooks file — preServerInit remains undefined
 }
 await loadEnvironmentVariables()
-safeCall(preServerInit)
+
+// preServerInit is an OPTIONAL hook — an app with no server/index.js is
+// valid, so PREFLIGHT-010 (missing) is deliberately not surfaced here. But
+// if the app DID export something under that name and it isn't callable,
+// that's a real mistake worth flagging (PREFLIGHT-011).
+if (preServerInit !== undefined) {
+    const preInitErr = validatePreInitServer(preServerInit)
+    if (preInitErr) handleError(preInitErr)
+}
+await safeCallNamed("preServerInit", preServerInit)

package/dist/scripts/preflight.js

@@ -0,0 +1,111 @@
+import { readFileSync } from "fs"
+import path from "path"
+import {
+    validateConfigFile,
+    validatePackageJson,
+    validateModuleAlias,
+} from "../server/utils/validator.js"
+import { formatError, createError, ERROR_CODES } from "../errors/index.js"
+import { resolveOutputMode } from "./scriptUtils.js"
+
+// Static preflight — the file-based checks a developer's misconfiguration
+// would trip. Runs in the parent CLI process (start.js / serve.js / build.js)
+// BEFORE the server is spawned, so a bad config.json / package.json fails
+// fast with a coded, doc-linked error instead of a raw ENOENT or SyntaxError
+// deep in the boot sequence.
+//
+// The in-server hook validators (middleware / getRoutes / configureStore /
+// preInitServer / reducer / customDocument) are NOT run here — those need the
+// app's modules loaded, so they stay at their call sites in expressServer.js
+// and handler.jsx, where they log-and-continue.
+//
+// Behaviour: collect EVERY failure, print them all, then throw so the caller
+// exits non-zero. The caller is expected to catch and `process.exit(1)` —
+// see runStaticPreflightOrExit below.
+
+function readJson(filePath) {
+    try {
+        return { value: JSON.parse(readFileSync(filePath, "utf8")), error: null }
+    } catch (e) {
+        return { value: null, error: e }
+    }
+}
+
+/**
+ * Run the static preflight checks against an app directory.
+ * @param {string} [appDir] - the consumer app root. Defaults to the current
+ *   working directory. `process.env.PWD` is preferred when set (it survives a
+ *   `cd` in the invoking shell script), but it is not exported by every shell
+ *   / CI runner, so `process.cwd()` is the fallback — never `undefined`, which
+ *   would make the `path.join` calls below throw.
+ * @returns {import("../errors/index.js").CatalystError[]} all failures (empty = passed)
+ */
+export function runStaticPreflight(appDir = process.env.PWD || process.cwd()) {
+    const failures = []
+
+    // config/config.json
+    const cfgPath = path.join(appDir, "config", "config.json")
+    const cfg = readJson(cfgPath)
+    if (cfg.error) {
+        failures.push(
+            createError(ERROR_CODES.PREFLIGHT_CONFIG_MISSING, {
+                details:
+                    cfg.error.code === "ENOENT"
+                        ? `config/config.json not found at ${cfgPath}`
+                        : `config/config.json could not be parsed: ${cfg.error.message}`,
+            })
+        )
+    } else {
+        const err = validateConfigFile(cfg.value)
+        if (err) failures.push(err)
+    }
+
+    // package.json (+ its moduleAliases)
+    const pkgPath = path.join(appDir, "package.json")
+    const pkg = readJson(pkgPath)
+    if (pkg.error) {
+        failures.push(
+            createError(
+                pkg.error.code === "ENOENT"
+                    ? ERROR_CODES.PREFLIGHT_PACKAGE_JSON_MISSING
+                    : ERROR_CODES.PREFLIGHT_PACKAGE_JSON_INVALID,
+                {
+                    details:
+                        pkg.error.code === "ENOENT"
+                            ? `package.json not found at ${pkgPath} — run this command from the project root`
+                            : `package.json could not be parsed: ${pkg.error.message}`,
+                }
+            )
+        )
+    } else {
+        const pkgErr = validatePackageJson(pkg.value)
+        if (pkgErr) failures.push(pkgErr)
+
+        const aliases = pkg.value._moduleAliases ?? pkg.value.moduleAliases
+        const aliasErr = validateModuleAlias(aliases)
+        if (aliasErr) failures.push(aliasErr)
+    }
+
+    return failures
+}
+
+/**
+ * Run static preflight and, if anything failed, print every error in the
+ * caller's output mode and exit the process non-zero. Call this at the top
+ * of a CLI entry script (start / serve / build).
+ * @param {string} [appDir]
+ */
+export function runStaticPreflightOrExit(appDir = process.env.PWD || process.cwd()) {
+    const mode = resolveOutputMode(process.argv)
+    const failures = runStaticPreflight(appDir)
+    if (failures.length === 0) return
+
+    for (const err of failures) {
+        console.error(formatError(err, mode))
+    }
+    console.error(
+        `\nPreflight failed with ${failures.length} error${failures.length === 1 ? "" : "s"}. ` +
+            `Fix the above and re-run.`
+    )
+    process.exit(1)
+}

package/dist/scripts/scriptUtils.js

@@ -1,9 +1,13 @@
 import fs from "fs"
 import path from "path"
+import { fileURLToPath } from "url"
 import util from "node:util"
-import pkg from "picocolors"
+import pkg from "ansis"
 const { gray, cyan } = pkg
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+let cachedCatalystCoreVersion
+
 // Function to get file size synchronously
 function getFileSizeSync(filePath) {
     try {
@@ -53,3 +57,44 @@ export function arrayToObject(array) {
     })
     return obj
 }
+
+/**
+ * Resolve the output mode for error formatting from a bare boolean CLI flag
+ * (--debug/--verbose, matching the --inspect convention already used by
+ * serve.js — not arrayToObject, which requires --key=value and silently
+ * drops valueless flags) or an inherited CATALYST_OUTPUT_MODE env var, for
+ * scripts spawned as a child process (see serve.js/start.js forwarding it
+ * to expressServer.js). An explicit flag on argv wins over an inherited env
+ * value, so e.g. `catalyst serve --debug` overrides a parent that set
+ * CATALYST_OUTPUT_MODE=verbose.
+ */
+export function resolveOutputMode(argv = process.argv, env = process.env) {
+    if (argv.includes("--debug")) return "debug"
+    if (argv.includes("--verbose")) return "verbose"
+    if (env.CATALYST_OUTPUT_MODE === "debug" || env.CATALYST_OUTPUT_MODE === "verbose") {
+        return env.CATALYST_OUTPUT_MODE
+    }
+    return "default"
+}
+
+/**
+ * Environment info for debug-mode error output: catalyst-core's own
+ * installed version (read from this package's own package.json, not the
+ * consuming app's — so it reflects what's actually running, not just what
+ * the app's package.json range says), Node version, and platform.
+ */
+export function getDebugEnvInfo() {
+    if (cachedCatalystCoreVersion === undefined) {
+        try {
+            const pkgPath = path.resolve(__dirname, "../../package.json")
+            cachedCatalystCoreVersion = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version
+        } catch {
+            cachedCatalystCoreVersion = "unknown"
+        }
+    }
+    return {
+        node: process.version,
+        platform: process.platform,
+        catalystCore: cachedCatalystCoreVersion,
+    }
+}

package/dist/scripts/serve.js

@@ -1,6 +1,7 @@
 import path from "path"
 import { spawnSync } from "child_process"
-import { arrayToObject } from "./scriptUtils.js"
+import { arrayToObject, resolveOutputMode } from "./scriptUtils.js"
+import { runStaticPreflightOrExit } from "./preflight.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
 import { readFileSync } from "fs"
@@ -14,8 +15,12 @@ const preInitPath = path.resolve(__dirname, "preServerInit.js")
  * @description - starts the application in production mode
  */
 function startProd() {
+    // Fail fast on a misconfigured app before spawning the production server.
+    runStaticPreflightOrExit()
+
     const commandLineArguments = process.argv.slice(2)
     const argumentsObject = arrayToObject(commandLineArguments)
+    const outputMode = resolveOutputMode(process.argv)
     const dirname = path.resolve(__dirname, "../../")
 
     // Read package.json
@@ -35,13 +40,12 @@ function startProd() {
                 ...process.env,
                 src_path: process.env.PWD,
                 NODE_ENV: "production",
-                IS_DEV_COMMAND: false,
                 APPLICATION: name || "catalyst_app",
+                CATALYST_OUTPUT_MODE: outputMode,
                 ...argumentsObject,
                 filterKeys: JSON.stringify([
                     "src_path",
                     "NODE_ENV",
-                    "IS_DEV_COMMAND",
                     "APPLICATION",
                     ...Object.keys(argumentsObject),
                 ]),

package/dist/scripts/start.js

@@ -1,6 +1,7 @@
 import path from "path"
 import { spawnSync } from "child_process"
-import { arrayToObject } from "./scriptUtils.js"
+import { arrayToObject, resolveOutputMode } from "./scriptUtils.js"
+import { runStaticPreflightOrExit } from "./preflight.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
 import { readFileSync } from "fs"
@@ -14,8 +15,13 @@ const preInitPath = path.resolve(__dirname, "preServerInit.js")
  * @description - starts webpack dev server and node server.
  */
 function start() {
+    // Fail fast on a misconfigured app (missing/invalid config.json, package.json,
+    // or moduleAliases) with a coded, doc-linked error before spawning the server.
+    runStaticPreflightOrExit()
+
     const commandLineArguments = process.argv.slice(2)
     const argumentsObject = arrayToObject(commandLineArguments)
+    const outputMode = resolveOutputMode(process.argv)
     const dirname = path.resolve(__dirname, "../../")
 
     // Read package.json
@@ -29,13 +35,12 @@ function start() {
             ...process.env,
             src_path: process.env.PWD,
             NODE_ENV: "development",
-            IS_DEV_COMMAND: false,
             APPLICATION: name || "catalyst_app",
+            CATALYST_OUTPUT_MODE: outputMode,
             ...argumentsObject,
             filterKeys: JSON.stringify([
                 "src_path",
                 "NODE_ENV",
-                "IS_DEV_COMMAND",
                 "APPLICATION",
                 ...Object.keys(argumentsObject),
             ]),

package/dist/server/expressServer.d.ts

@@ -0,0 +1 @@
+export {};