catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/scripts/build.js

@@ -1,12 +1,13 @@
 import path from "path"
 import { spawn } from "child_process"
-import { arrayToObject, resolveOutputMode, getDebugEnvInfo } from "./scriptUtils.js"
+import { arrayToObject, loaderImportArg, resolveOutputMode, getDebugEnvInfo } from "./scriptUtils.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
-import { readFileSync, existsSync, rmSync } from "fs"
+import { readFileSync, readdirSync, existsSync, rmSync } from "fs"
+import { gzipSync } from "zlib"
 import { createRequire } from "module"
-import { wrapForeignError, formatError } from "../errors/index.js"
-import { runStaticPreflightOrExit } from "./preflight.js"
+import { getDocUrl, ERROR_CODES } from "../errors/index.js"
+import { runStaticPreflightOrExit, writeBuildInfo } 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
@@ -16,9 +17,23 @@ runStaticPreflightOrExit()
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
+
+// src/cli is CommonJS so src/native (also CJS) can share it; pull it in here
+// rather than duplicating the visual language for the web commands.
+const requireCjs = createRequire(import.meta.url)
+const { header, step, glyph, t, GUTTER, duration, bytes } = requireCjs("../cli/theme.js")
+const { diagnostic, verboseOutput } = requireCjs("../cli/diagnostic.js")
+const { Spinner } = requireCjs("../cli/spinner.js")
+const { loadAppConfig } = requireCjs("../cli/appConfig.js")
+const { bundleWarnings } = requireCjs("../cli/buildWarnings.js")
+const { extractBuildErrors, outputTail } = requireCjs("../cli/buildErrors.js")
+const { hintFor } = requireCjs("../cli/hints.js")
 const loaderPath = path.resolve(__dirname, "../../dist/vite/node-loader.mjs")
-const configPath = path.join(process.env.PWD, "config/config.json")
-const configJSON = JSON.parse(readFileSync(configPath), "utf-8")
+
+// A missing or malformed config used to throw a raw ENOENT/SyntaxError stack at
+// module load, before any output at all. Note the "utf-8" was being passed as
+// JSON.parse's reviver argument, not as the read encoding.
+const configJSON = loadAppConfig(process.env.PWD || process.cwd())
 
 // Resolve vite's actual JS entry point rather than spawning the "vite" command name,
 // which on Windows only resolves via the npm-installed .cmd shim (i.e. requires a shell).
@@ -27,27 +42,220 @@ const require = createRequire(import.meta.url)
 const viteBinPath = path.join(path.dirname(require.resolve("vite/package.json")), "bin", "vite.js")
 
 /**
+ * A child's exit code, or 1 when there is not a usable one.
+ *
+ * Spawn failures carry a string `code` like "ENOENT", and process.exit throws
+ * ERR_INVALID_ARG_TYPE on anything that is not an integer -- which would
+ * replace the friendly error with an internal stack trace.
+ */
+const MAX_CAPTURED_BYTES = 1024 * 1024
+
+function exitCodeFrom(error) {
+    return Number.isInteger(error?.code) ? error.code : 1
+}
+
+/**
+ * Run one build step, capturing its output.
+ *
+ * Output is piped rather than inherited. With inherit the bundler wrote
+ * straight to the terminal at column 0 -- so two parallel bundles interleaved,
+ * the same error printed once per bundle, and the parent held nothing but an
+ * exit code. Holding the text is what makes it possible to find the real
+ * compiler error, dedupe it, and show it in the house style.
+ *
  * @param {string[]} args
  * @param {import('child_process').SpawnOptions} options
+ * @param {string} label - names this step, e.g. "client"
  */
-function runBuildStep(args, options) {
+function runBuildStep(args, options, label = "Build step") {
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, args, options)
+        const child = spawn(process.execPath, args, {
+            ...options,
+            stdio: ["inherit", "pipe", "pipe"],
+        })
+
+        // Only the tail is ever shown, so a pathological build cannot grow
+        // this without bound.
+        let output = ""
+        const keep = (chunk) => {
+            output += chunk.toString()
+            if (output.length > MAX_CAPTURED_BYTES) output = output.slice(-MAX_CAPTURED_BYTES)
+        }
+        child.stdout.on("data", keep)
+        child.stderr.on("data", keep)
+
         child.on("close", (code) => {
             if (code === 0) {
-                resolve()
+                resolve({ label, output })
             } else {
-                reject(Object.assign(new Error(`Build step failed with exit code ${code}`), { code }))
+                reject(
+                    Object.assign(new Error(`${label} failed with exit code ${code}`), {
+                        code,
+                        label,
+                        output,
+                    })
+                )
             }
         })
         child.on("error", reject)
     })
 }
 
+/**
+ * Report bundle failures once each, not once per bundle.
+ *
+ * One broken import fails both bundles, so the naive loop printed the same
+ * error twice with two identical hints. Errors are keyed on their cause, and
+ * the bundles they broke become a dim suffix rather than a second block.
+ */
+function shortenPaths(text, cwd) {
+    return String(text).split(`${cwd}/`).join("")
+}
+
+/** A step's own last words, fenced under the diagnostic that names it. */
+function fencedTail(output, lines = 8) {
+    const tail = outputTail(output || "", lines)
+    return tail
+        ? tail
+              .split("\n")
+              .map((line) => `${GUTTER}${t.dim(glyph.pipe)} ${t.dim(line)}`)
+              .join("\n") + "\n\n"
+        : ""
+}
+
+function reportBundleFailures(failures, cwd) {
+    // Every bundle failure is the registry's upstream wrapper: its code and
+    // docs head each block, as they did before the extracted-error view.
+    const code = ERROR_CODES.BUNDLE_UPSTREAM_ERROR
+    const docs = getDocUrl(code)
+    const byCause = new Map()
+    const unrecognised = []
+
+    for (const failure of failures) {
+        const found = extractBuildErrors(failure.output, { toolchain: "vite" })
+        if (found.length === 0) {
+            unrecognised.push(failure)
+            continue
+        }
+        for (const error of found) {
+            const key = `${error.file || ""}:${error.line || ""}:${error.message}`
+            const existing = byCause.get(key)
+            if (existing) existing.bundles.push(failure.label)
+            else byCause.set(key, { ...error, bundles: [failure.label] })
+        }
+    }
+
+    // Nothing recognised: fence the bundler's own words rather than inventing
+    // a summary that says less than they do. Rendered even when the other
+    // bundle's error was recognised, so neither failure goes unreported.
+    const unrecognisedReport = unrecognised
+        .map(
+            (failure) =>
+                diagnostic({
+                    message: `The ${failure.label || "production"} bundle failed`,
+                    code,
+                    scope: "production build",
+                    docs,
+                    cwd,
+                }) + fencedTail(failure.output)
+        )
+        .join("")
+
+    // Each cause renders as the same diagnostic block every other failure
+    // uses: message, location, the source around it, and a hint when the
+    // cause is one we understand.
+    const recognisedReport = [...byCause.values()]
+        .map((cause) =>
+            diagnostic({
+                message: shortenPaths(cause.message, cwd),
+                code,
+                scope: `${cause.bundles.join(" + ")} bundle`,
+                file: cause.file ? path.resolve(cwd, cause.file.replace(/^(\.\.\/)+/, "")) : undefined,
+                line: cause.line,
+                // esbuild reports columns 0-based; the frame's caret is 1-based.
+                column: cause.column != null ? cause.column + 1 : undefined,
+                hint: hintFor(cause.message)?.hint,
+                docs,
+                cwd,
+            })
+        )
+        .join("")
+
+    return recognisedReport + unrecognisedReport
+}
+
+/**
+ * List what was actually produced, largest first, with gzip where we have it.
+ *
+ * Reads the directory rather than parsing the bundler's output: the files on
+ * disk are the truth, and this keeps working if the bundler changes format.
+ */
+function printAssetTable(outputPath, label) {
+    const entries = []
+
+    const walk = (dir, prefix) => {
+        let items
+        try {
+            items = readdirSync(dir, { withFileTypes: true })
+        } catch (error) {
+            return
+        }
+        for (const item of items) {
+            // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal - names come from readdirSync of our own build output.
+            const full = path.join(dir, item.name)
+            const rel = prefix ? `${prefix}/${item.name}` : item.name
+            if (item.isDirectory()) {
+                walk(full, rel)
+            } else if (/\.(js|css|mjs|cjs)$/.test(item.name)) {
+                try {
+                    const raw = readFileSync(full)
+                    entries.push({ name: rel, size: raw.length, gzip: gzipSync(raw).length })
+                } catch (error) {
+                    // A file we cannot read is not worth failing a build over.
+                }
+            }
+        }
+    }
+
+    walk(outputPath, "")
+    if (entries.length === 0) return
+
+    // The server bundle never reaches a browser, so its per-file sizes are not
+    // something to optimise; one total line keeps it visible without crowding
+    // the table people actually read.
+    const server = entries.filter((entry) => entry.name.startsWith("server/"))
+    entries.splice(0, entries.length, ...entries.filter((entry) => !entry.name.startsWith("server/")))
+
+    entries.sort((a, b) => b.size - a.size)
+    const shown = entries.slice(0, 12)
+    const width = Math.max(...shown.map((e) => e.name.length))
+
+    console.log(`\n${GUTTER}${t.bold("Client")}  ${t.dim(`${label}/`)}`)
+    for (const [index, entry] of shown.entries()) {
+        const isLast = index === shown.length - 1 && entries.length === shown.length
+        console.log(
+            `${GUTTER}${t.dim(isLast ? glyph.last : glyph.branch)} ${entry.name.padEnd(width + 2)}` +
+                `${bytes(entry.size).padStart(9)}` +
+                `${t.dim(`  ${bytes(entry.gzip).padStart(8)} gzip`)}`
+        )
+    }
+    if (entries.length > shown.length) {
+        console.log(`${GUTTER}${t.dim(glyph.last)} ${t.dim(`and ${entries.length - shown.length} more`)}`)
+    }
+    if (server.length) {
+        const total = server.reduce((sum, entry) => sum + entry.size, 0)
+        const files = `${server.length} file${server.length === 1 ? "" : "s"}`
+        console.log(
+            `\n${GUTTER}${t.bold("Server")}  ${t.dim(`${label}/server/`)}  ${t.dim(`${files}, ${bytes(total)}`)}`
+        )
+    }
+}
+
 /**
  * @description - builds the application for production
  */
 async function build() {
+    const startedAt = Date.now()
     const commandLineArguments = process.argv.slice(2)
     const argumentsObject = arrayToObject(commandLineArguments)
     const outputMode = resolveOutputMode(process.argv)
@@ -57,21 +265,26 @@ async function build() {
     const packageJson = JSON.parse(readFileSync(path.join(process.env.PWD, "package.json"), "utf-8"))
     const { name } = packageJson
 
+    process.stdout.write(header("catalyst build", "production"))
+
     const buildOutputPath = path.join(process.env.PWD, configJSON.BUILD_OUTPUT_PATH || "build")
     if (existsSync(buildOutputPath)) {
-        console.log("🧹 Clearing previous build output...")
+        const cleaning = Date.now()
         rmSync(buildOutputPath, { recursive: true, force: true })
+        console.log(step("Cleaned previous output", Date.now() - cleaning))
     }
 
-    console.log("🏗️  Building application for production...")
-
     const baseEnv = {
         ...process.env,
+        // The children are piped now, so their stdout is not a TTY and the
+        // bundler would drop colour. Forward our own terminal's answer, so a
+        // redirect to a file still comes out plain.
+        ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: "1" } : {}),
         src_path: process.env.PWD,
         NODE_ENV: "production",
         VITE_BUILD_MODE: "true",
         APPLICATION: name || "catalyst_app",
-        NODE_OPTIONS: `--loader ${loaderPath}`,
+        NODE_OPTIONS: `--import ${loaderImportArg(loaderPath)}`,
         CATALYST_OUTPUT_MODE: outputMode,
         ...argumentsObject,
         filterKeys: JSON.stringify([
@@ -85,41 +298,100 @@ async function build() {
 
     const serverBuildArgs = [viteBinPath, "build", "--config", "./dist/vite/vite.config.server.js", "--ssr"]
     const clientBuildArgs = [viteBinPath, "build", "--config", "./dist/vite/vite.config.client.js"]
-    const spawnBase = {
-        cwd: dirname,
-        stdio: "inherit",
+    const spawnBase = { cwd: dirname }
+
+    // A live row while the bundles build: a large app takes tens of seconds
+    // here, and a screen that stops changing reads as a hang. Both children
+    // are piped, so nothing else writes to the terminal meanwhile.
+    const bundling = new Spinner().start("Building client and server bundles")
+
+    // Both bundles build in parallel and their output is captured, so failures
+    // are reported once, attributed to the bundle that produced them.
+    // allSettled rather than all: if both bundles are broken, Promise.all would
+    // report only whichever rejected first and hide the other.
+    const results = await Promise.allSettled([
+        runBuildStep(
+            serverBuildArgs,
+            { ...spawnBase, env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "ssr" } },
+            "server"
+        ),
+        runBuildStep(
+            clientBuildArgs,
+            { ...spawnBase, env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "client" } },
+            "client"
+        ),
+    ])
+
+    const failures = results.filter((result) => result.status === "rejected").map((result) => result.reason)
+
+    if (failures.length > 0) {
+        bundling.stop("fail", "Build failed")
+        process.stderr.write(reportBundleFailures(failures, process.env.PWD))
+        // --verbose/--debug add the registry code and the bundler's full
+        // output under the extracted errors.
+        if (outputMode !== "default") {
+            process.stderr.write(
+                verboseOutput({
+                    code: ERROR_CODES.BUNDLE_UPSTREAM_ERROR,
+                    docs: getDocUrl(ERROR_CODES.BUNDLE_UPSTREAM_ERROR),
+                    output: failures.map((failure) => `[${failure.label}]\n${failure.output}`).join("\n"),
+                    mode: outputMode,
+                    error: failures[0],
+                    env: outputMode === "debug" ? getDebugEnvInfo() : undefined,
+                })
+            )
+        }
+        process.exit(exitCodeFrom(failures[0]))
     }
 
-    console.log("🔧📦 Building server and client bundles in parallel...")
+    // Warnings that survived the config filters were captured and then thrown
+    // away on a green build, so a real one (a circular dependency, an oversized
+    // chunk) vanished silently. Surface them under the step that produced them.
+    const warnings = results
+        .filter((result) => result.status === "fulfilled")
+        .flatMap((result) => bundleWarnings(result.value.output, result.value.label))
 
-    try {
-        await Promise.all([
-            runBuildStep(serverBuildArgs, {
-                ...spawnBase,
-                env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "ssr" },
-            }),
-            runBuildStep(clientBuildArgs, {
-                ...spawnBase,
-                env: { ...baseEnv, CATALYST_VITE_CACHE_ID: "client" },
-            }),
-        ])
-    } catch (err) {
-        console.error("❌ Build failed!")
-        const debugEnv = outputMode === "debug" ? getDebugEnvInfo() : undefined
-        console.error(formatError(wrapForeignError("BUNDLE", err), outputMode, debugEnv))
-        process.exit(1)
+    bundling.stop("done", "Built client and server bundles")
+    // Warnings belong to the step that produced them, beneath it.
+    for (const warning of warnings) {
+        console.log(`${GUTTER}${t.dim(glyph.pipe)} ${t.warn(glyph.warn)} ${t.dim(warning)}`)
     }
 
-    console.log("✅ Server and client builds completed!")
+    // Lets `serve` refuse a build that no longer matches config/config.json.
+    writeBuildInfo(process.env.PWD, configJSON, argumentsObject)
 
-    await runBuildStep(["./dist/scripts/generateOfflineManifest.js"], {
-        ...spawnBase,
-        env: baseEnv,
-    })
+    const manifest = new Spinner().start("Generating offline manifest")
+    try {
+        await runBuildStep(
+            ["./dist/scripts/generateOfflineManifest.js"],
+            { ...spawnBase, env: baseEnv },
+            "Generating the offline manifest"
+        )
+    } catch (error) {
+        manifest.stop("fail", "Generating offline manifest failed")
+        // Without this the manifest step fell through to the top-level handler,
+        // which prints a raw stack trace. The step's output is captured, so
+        // show its tail -- the exit code alone says nothing about why -- and
+        // all of it under --verbose/--debug.
+        process.stderr.write(
+            diagnostic({
+                message: `Generating the offline manifest failed: ${error.message}`,
+                scope: "offline manifest",
+            }) + (outputMode === "default" ? fencedTail(error.output) : "")
+        )
+        if (outputMode !== "default") {
+            process.stderr.write(verboseOutput({ output: error.output, mode: outputMode, error }))
+        }
+        process.exit(exitCodeFrom(error))
+    }
+    manifest.stop("done", "Generated offline manifest")
+
+    printAssetTable(buildOutputPath, configJSON.BUILD_OUTPUT_PATH || "build")
 
-    console.log("🎉 Build completed successfully!")
-    console.log("📁 Built files are located in the 'build' directory")
-    console.log("🚀 Run 'npm run serve' to start the production server")
+    console.log(`\n${GUTTER}${t.ok(glyph.done)} ${t.bold(`Built in ${duration(Date.now() - startedAt)}`)}`)
+    console.log(
+        `${GUTTER}  ${t.dim("Run ")}${t.accent("catalyst serve")}${t.dim(" to start the production server")}\n`
+    )
 }
 
 build().catch((err) => {

package/dist/scripts/generateOfflineManifest.js

@@ -53,6 +53,14 @@ export function collectOfflineRoutes(routes, basePath = "", parentOffline = fals
 }
 
 async function loadAppRoutes(appRoot) {
+    // The shared dev config's `server` block wins over the inline options
+    // below, and its isProduction is captured at module load so NODE_ENV
+    // cannot be flipped here. This flag is the supported opt-out: without it
+    // the manifest step opens an HMR websocket and prints "Port 24678 is
+    // already in use" whenever a dev server happens to be running.
+    const previousNoHmr = process.env.CATALYST_NO_HMR
+    process.env.CATALYST_NO_HMR = "true"
+
     const vite = await createViteServer({
         configFile: path.resolve(__dirname, "../vite/vite.config.js"),
         root: appRoot,
@@ -73,6 +81,8 @@ async function loadAppRoutes(appRoot) {
         return typeof routesModule.getRoutes === "function" ? routesModule.getRoutes() : []
     } finally {
         await vite.close()
+        if (previousNoHmr === undefined) delete process.env.CATALYST_NO_HMR
+        else process.env.CATALYST_NO_HMR = previousNoHmr
     }
 }
 
@@ -106,7 +116,7 @@ export async function generateOfflineManifest() {
     copyIfExists(path.join(appRoot, "public/offline.html"), path.join(buildDir, "offline.html"))
     fs.copyFileSync(path.join(__dirname, "../offline/catalyst-sw.js"), path.join(buildDir, "catalyst-sw.js"))
 
-    console.log(`Catalyst offline manifest generated: ${routes.length} route(s)`)
+    // The CLI reports this step; printing it here too duplicated the line.
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {

package/dist/scripts/loadEnvironmentVariables.js

@@ -1,14 +1,19 @@
 import path from "path"
 import fs from "fs"
+import { createRequire } from "module"
+
+const { diagnostic } = createRequire(import.meta.url)("../cli/diagnostic.js")
 
 /**
  * @description stores all config.json key value into process.env before server starts.
  */
 const loadEnvironmentVariables = async () => {
+    // Declared outside the try so the catch can point the diagnostic at it.
+    let appConfigPath
     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")
+        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)
@@ -45,7 +50,24 @@ const loadEnvironmentVariables = async () => {
         // still keeping every pre-existing process.env entry via the spread.
         process.env = { ...process.env, ...newConfig }
     } catch (error) {
-        console.error("Error loading environment variables:", error)
+        // This runs before the server starts, for both `start` and `serve`, so
+        // a missing or malformed config used to greet the user with a raw
+        // ENOENT/SyntaxError stack trace as the very first thing they saw.
+        process.stderr.write(
+            diagnostic({
+                message:
+                    error.code === "ENOENT"
+                        ? "Config file not found"
+                        : error instanceof SyntaxError
+                          ? `Config file is not valid JSON: ${error.message}`
+                          : `Could not load configuration: ${error.message}`,
+                file: appConfigPath,
+                hint:
+                    error.code === "ENOENT"
+                        ? "Every Catalyst app needs a config/config.json at its root."
+                        : undefined,
+            })
+        )
         throw error
     }
 }

package/dist/scripts/preServerInit.js

@@ -3,16 +3,32 @@ import { createRequire } from "module"
 import loadEnvironmentVariables from "./loadEnvironmentVariables.js"
 import { validatePreInitServer, handleError, safeCallNamed } from "../server/utils/validator.js"
 
+const { diagnostic, registryFailure } = createRequire(import.meta.url)("../cli/diagnostic.js")
+
+// A startup check that fails: one diagnostic, then exit. A throw here printed
+// Node's stack for a problem whose fix is one install command. The CLI that
+// spawned this process sees the diagnostic and does not add its own.
+function failStartup(message, hint) {
+    process.stderr.write(diagnostic({ message, scope: "server", hint }))
+    process.exit(1)
+}
+
 // 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."
+    failStartup(
+        "process.env.src_path is not set, so the application root cannot be resolved",
+        "Start the server with `catalyst start` or `catalyst serve` from the application root."
     )
 }
 
+// validator.ts renders registry errors through this. It is also bundled into
+// the app's SSR build, which cannot reach the CLI by a relative path, so the
+// server process hands the renderer over here, in the first module it loads.
+// eslint-disable-next-line no-undef -- the scripts lint env predates globalThis
+globalThis.__catalystRenderRegistryError = (error, scope) => registryFailure(error, { scope, cwd: appRoot })
+
 // 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.
@@ -22,9 +38,9 @@ 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}`
+    failStartup(
+        `catalyst-core needs react-router ${REQUIRED_REACT_ROUTER}, and it is not installed`,
+        `Install it with \`npm install react-router@${REQUIRED_REACT_ROUTER}\`.`
     )
 }
 const [major, minor, patch] = reactRouterVersion.split("-")[0].split(".").map(Number)
@@ -33,9 +49,9 @@ const isValid =
     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}`
+    failStartup(
+        `catalyst-core needs react-router ${REQUIRED_REACT_ROUTER}, but the app has ${reactRouterVersion}`,
+        `Upgrade it with \`npm install react-router@${REQUIRED_REACT_ROUTER}\`.`
     )
 }
 
@@ -46,7 +62,13 @@ try {
 } catch {
     // No hooks file — preServerInit remains undefined
 }
-await loadEnvironmentVariables()
+try {
+    await loadEnvironmentVariables()
+} catch {
+    // loadEnvironmentVariables already printed an actionable message. Letting
+    // this propagate would print the raw stack again as an unhandled rejection.
+    process.exit(1)
+}
 
 // preServerInit is an OPTIONAL hook — an app with no server/index.js is
 // valid, so PREFLIGHT-010 (missing) is deliberately not surfaced here. But