catalyst-core 1.0.1 → 1.0.2-canary.2

package/dist/scripts/preflight.js

@@ -1,12 +1,29 @@
-import { readFileSync } from "fs"
+import { readFileSync, writeFileSync } from "fs"
 import path from "path"
+import { createRequire } from "module"
 import {
     validateConfigFile,
     validatePackageJson,
     validateModuleAlias,
 } from "../server/utils/validator.js"
 import { formatError, createError, ERROR_CODES } from "../errors/index.js"
-import { resolveOutputMode } from "./scriptUtils.js"
+import { resolveOutputMode, getDebugEnvInfo } from "./scriptUtils.js"
+
+const requireCjs = createRequire(import.meta.url)
+const { registryFailure } = requireCjs("../cli/diagnostic.js")
+const { GUTTER, glyph, t } = requireCjs("../cli/theme.js")
+
+/**
+ * A registry error as the CLI shows it: the diagnostic block by default, the
+ * registry's box under --verbose and --debug.
+ * @param {import("../errors/index.js").CatalystError} err
+ * @param {string} mode - "default" | "verbose" | "debug"
+ * @param {{scope?: string}} [options]
+ */
+export function renderRegistryError(err, mode, { scope } = {}) {
+    if (mode === "default") return registryFailure(err, { scope })
+    return formatError(err, mode, mode === "debug" ? getDebugEnvInfo() : undefined)
+}
 
 // Static preflight — the file-based checks a developer's misconfiguration
 // would trip. Runs in the parent CLI process (start.js / serve.js / build.js)
@@ -47,12 +64,19 @@ export function runStaticPreflight(appDir = process.env.PWD || process.cwd()) {
     const cfgPath = path.join(appDir, "config", "config.json")
     const cfg = readJson(cfgPath)
     if (cfg.error) {
+        // A file that exists but does not parse is not "missing": the default
+        // message and its "create the file" advice would send people the
+        // wrong way.
+        const unparsable = cfg.error.code !== "ENOENT"
         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}`,
+                details: unparsable
+                    ? `config/config.json could not be parsed: ${cfg.error.message}`
+                    : `config/config.json not found at ${cfgPath}`,
+                ...(unparsable && {
+                    message: "config/config.json is not valid JSON",
+                    suggestedAction: "Fix the JSON syntax in config/config.json at the position shown.",
+                }),
             })
         )
     } else {
@@ -101,11 +125,91 @@ export function runStaticPreflightOrExit(appDir = process.env.PWD || process.cwd
     if (failures.length === 0) return
 
     for (const err of failures) {
-        console.error(formatError(err, mode))
+        console.error(renderRegistryError(err, mode, { scope: "preflight" }))
+    }
+    // One block speaks for itself; a count only helps when there are several.
+    if (failures.length > 1) {
+        console.error(`${GUTTER}${t.dim(`${failures.length} problems found. Fix them and re-run.`)}\n`)
     }
-    console.error(
-        `\nPreflight failed with ${failures.length} error${failures.length === 1 ? "" : "s"}. ` +
-            `Fix the above and re-run.`
-    )
     process.exit(1)
 }
+
+// Records the config values a build was made with, so `serve` can refuse a
+// build that no longer matches config/config.json (issue #251).
+const BUILD_INFO_FILE = ".catalyst-build.json"
+
+/**
+ * Config values Vite inlines into the bundles at build time (see
+ * getClientEnvVariables in vite.config.js). KEY=value CLI arguments win over
+ * config.json, and objects are stored as JSON, as in loadEnvironmentVariables.
+ * @param {Record<string, unknown>} config - parsed config/config.json
+ * @param {Record<string, string>} [args] - KEY=value CLI arguments
+ */
+export function getInlinedConfig(config, args = {}) {
+    const values = { ...config, ...args }
+    let clientVars = values.CLIENT_ENV_VARIABLES ?? []
+    if (typeof clientVars === "string") clientVars = JSON.parse(clientVars)
+    const keys = ["PUBLIC_STATIC_ASSET_URL", "PUBLIC_STATIC_ASSET_PATH", ...clientVars]
+    return Object.fromEntries(
+        keys.map((key) => [key, typeof values[key] === "object" ? JSON.stringify(values[key]) : values[key]])
+    )
+}
+
+function buildInfoPath(appDir, config, args) {
+    return path.join(appDir, args.BUILD_OUTPUT_PATH || config.BUILD_OUTPUT_PATH || "build", BUILD_INFO_FILE)
+}
+
+/**
+ * @param {string} appDir
+ * @param {Record<string, unknown>} config
+ * @param {Record<string, string>} [args]
+ */
+export function writeBuildInfo(appDir, config, args = {}) {
+    writeFileSync(
+        buildInfoPath(appDir, config, args),
+        JSON.stringify(getInlinedConfig(config, args), null, 4)
+    )
+}
+
+/**
+ * Compare the values a build was made with against the current config.
+ * Anything that stops the comparison (a missing or unreadable build info
+ * file, e.g. from an older catalyst-core, an unparseable CLIENT_ENV_VARIABLES)
+ * only warns, so the build still serves.
+ * @param {string} [appDir]
+ * @param {Record<string, string>} [args]
+ * @returns {import("../errors/index.js").CatalystError | null}
+ */
+export function checkBuildMatchesConfig(appDir = process.env.PWD || process.cwd(), args = {}) {
+    const skip = (reason) => {
+        console.warn(`${GUTTER}${t.warn(glyph.warn)} ${t.dim(`Skipping the build/config check: ${reason}`)}`)
+        return null
+    }
+
+    // runStaticPreflightOrExit has already checked config.json.
+    const config = JSON.parse(readFileSync(path.join(appDir, "config", "config.json"), "utf8"))
+    const infoPath = buildInfoPath(appDir, config, args)
+    const info = readJson(infoPath)
+    if (info.error || !info.value || typeof info.value !== "object" || Array.isArray(info.value)) {
+        return skip(`${infoPath} is missing or invalid. Rebuild to enable it.`)
+    }
+
+    let current
+    try {
+        current = getInlinedConfig(config, args)
+    } catch (e) {
+        return skip(`could not read CLIENT_ENV_VARIABLES: ${e.message}`)
+    }
+
+    const keys = new Set([...Object.keys(info.value), ...Object.keys(current)])
+    const changed = [...keys].filter((key) => info.value[key] !== current[key])
+    if (changed.length === 0) return null
+
+    const show = (value) => (value === undefined ? "unset" : JSON.stringify(value))
+    const lines = changed.map(
+        (key) => `${key}: built with ${show(info.value[key])}, now ${show(current[key])}`
+    )
+    return createError(ERROR_CODES.PREFLIGHT_BUILD_STALE, {
+        details: `These values were inlined into the build and differ from config/config.json:\n  ${lines.join("\n  ")}`,
+    })
+}

package/dist/scripts/scriptUtils.js

@@ -2,6 +2,7 @@ import fs from "fs"
 import path from "path"
 import { fileURLToPath } from "url"
 import util from "node:util"
+import { pathToFileURL } from "url"
 import pkg from "ansis"
 const { gray, cyan } = pkg
 
@@ -49,6 +50,39 @@ export const printBundleInformation = () => {
     })
 }
 
+/**
+ * Propagate a spawnSync result to this process's exit code.
+ *
+ * Without this the wrapper always exits 0, so a server that failed to boot
+ * still reads as a successful run to CI and to shell `&&` chains.
+ *
+ * @param {import('child_process').SpawnSyncReturns<Buffer>} result
+ * @param {string} label - what was being started, for the error message
+ */
+
+/**
+ * A `--import` argument that registers a module loader.
+ *
+ * `--loader` is deprecated and makes Node print a four-line
+ * ExperimentalWarning to stderr for every process that uses it -- which meant
+ * 18 lines of warnings in a single `catalyst build`, since the flag is passed
+ * to both bundles and the manifest step. register() is the supported form and
+ * is silent.
+ *
+ * @param {string} loaderPath - absolute path to the loader module
+ */
+export function loaderImportArg(loaderPath) {
+    const url = pathToFileURL(loaderPath).href
+    return (
+        `data:text/javascript,` +
+        encodeURIComponent(
+            `import { register } from "node:module";` +
+                `import { pathToFileURL } from "node:url";` +
+                `register(${JSON.stringify(url)}, pathToFileURL("./"));`
+        )
+    )
+}
+
 export function arrayToObject(array) {
     const obj = {}
     array.forEach((item) => {

package/dist/scripts/serve.js

@@ -1,20 +1,33 @@
 import path from "path"
-import { spawnSync } from "child_process"
-import { arrayToObject, resolveOutputMode } from "./scriptUtils.js"
-import { runStaticPreflightOrExit } from "./preflight.js"
+import { spawn } from "child_process"
+import { arrayToObject, loaderImportArg, resolveOutputMode } from "./scriptUtils.js"
+import { runStaticPreflightOrExit, checkBuildMatchesConfig, renderRegistryError } from "./preflight.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
-import { readFileSync } from "fs"
+import { existsSync, readFileSync } from "fs"
+import { createRequire } from "module"
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
+
+const requireCjs = createRequire(import.meta.url)
+const { diagnostic } = requireCjs("../cli/diagnostic.js")
+const { superviseServer, ensurePortFree } = requireCjs("../cli/devOutput.js")
+const { loadAppConfig } = requireCjs("../cli/appConfig.js")
+
 const loaderPath = path.resolve(__dirname, "../../dist/vite/node-loader.mjs")
 const preInitPath = path.resolve(__dirname, "preServerInit.js")
 
 /**
- * @description - starts the application in production mode
+ * @description - serves the production build
+ *
+ * Output is inherited, not piped through the `start` formatter. Production
+ * output is read by log shippers (pm2, Docker, Datadog) one JSON line at a
+ * time, so every byte the app writes must arrive unaltered and on the stream
+ * it was written to. CATALYST_WRAPPED stays unset, so the server prints its
+ * banner plainly with no fences to consume.
  */
-function startProd() {
+async function startProd() {
     // Fail fast on a misconfigured app before spawning the production server.
     runStaticPreflightOrExit()
 
@@ -27,17 +40,58 @@ function startProd() {
     const packageJson = JSON.parse(readFileSync(path.join(process.env.PWD, "package.json"), "utf-8"))
     const { name } = packageJson
 
-    console.log("🚀 Starting production server...")
+    // Serving a build that was never made produces a stack trace from deep
+    // inside the server. Say the useful thing instead.
+    // From config.json, not the env: config values are promoted to env only
+    // inside the child, so reading env here always saw the default.
+    const appConfig = loadAppConfig(process.env.PWD || process.cwd())
+    const buildDir = path.join(
+        process.env.PWD,
+        appConfig.BUILD_OUTPUT_PATH || process.env.BUILD_OUTPUT_PATH || "build"
+    )
+    if (!existsSync(buildDir)) {
+        process.stderr.write(
+            diagnostic({
+                message: `No production build in ${path.relative(process.env.PWD, buildDir) || buildDir}/`,
+                scope: "server",
+                hint: "Run catalyst build first, then catalyst serve.",
+            })
+        )
+        process.exit(1)
+    }
+
+    // After the missing-build check, so a missing build gets that message
+    // rather than a "skipping the check" warning first.
+    const staleBuild = checkBuildMatchesConfig(undefined, argumentsObject)
+    if (staleBuild) {
+        process.stderr.write(renderRegistryError(staleBuild, outputMode, { scope: "server" }))
+        process.exit(1)
+    }
+
+    await ensurePortFree({
+        port: argumentsObject.NODE_SERVER_PORT || appConfig.NODE_SERVER_PORT,
+        host: argumentsObject.NODE_SERVER_HOSTNAME || appConfig.NODE_SERVER_HOSTNAME,
+        scope: "server",
+    })
 
     const inspectArgs = commandLineArguments.includes("--inspect") ? ["--inspect"] : []
-    spawnSync(
+    const child = spawn(
         "node",
-        [...inspectArgs, "--import", preInitPath, "--loader", loaderPath, "./dist/server/expressServer.js"],
+        [
+            ...inspectArgs,
+            "--import",
+            preInitPath,
+            "--import",
+            loaderImportArg(loaderPath),
+            "./dist/server/expressServer.js",
+        ],
         {
             cwd: dirname,
             stdio: "inherit",
             env: {
                 ...process.env,
+                // When the command was run, so "Ready in" counts the whole wait.
+                CATALYST_STARTED_AT: String(Math.round(performance.timeOrigin)),
                 src_path: process.env.PWD,
                 NODE_ENV: "production",
                 APPLICATION: name || "catalyst_app",
@@ -52,6 +106,8 @@ function startProd() {
             },
         }
     )
+
+    superviseServer(child, { scope: "server", label: "production server", passthrough: true })
 }
 
 startProd()

package/dist/scripts/start.js

@@ -1,20 +1,32 @@
 import path from "path"
-import { spawnSync } from "child_process"
-import { arrayToObject, resolveOutputMode } from "./scriptUtils.js"
+import { spawn } from "child_process"
+import { arrayToObject, loaderImportArg, resolveOutputMode } from "./scriptUtils.js"
 import { runStaticPreflightOrExit } from "./preflight.js"
 import { fileURLToPath } from "url"
 import { dirname } from "path"
 import { readFileSync } from "fs"
+import { createRequire } from "module"
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
+
+const requireCjs = createRequire(import.meta.url)
+const { superviseServer, ensurePortFree } = requireCjs("../cli/devOutput.js")
+const { loadAppConfig } = requireCjs("../cli/appConfig.js")
+
 const loaderPath = path.resolve(__dirname, "../../dist/vite/node-loader.mjs")
 const preInitPath = path.resolve(__dirname, "preServerInit.js")
 
 /**
- * @description - starts webpack dev server and node server.
+ * @description - starts the dev server
+ *
+ * stdio is piped rather than inherited so this command owns every line it
+ * prints. The server child speaks in three unrelated voices -- Node process
+ * warnings, Vite notices, and our own banner -- and inheriting stdio meant
+ * they interleaved raw, with the banner arriving last and reading as an
+ * afterthought.
  */
-function start() {
+async 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()
@@ -28,24 +40,49 @@ function start() {
     const packageJson = JSON.parse(readFileSync(path.join(process.env.PWD, "package.json"), "utf-8"))
     const { name } = packageJson
 
-    spawnSync("node", ["--import", preInitPath, "--loader", loaderPath, "./dist/server/expressServer.js"], {
-        cwd: dirname,
-        stdio: "inherit",
-        env: {
-            ...process.env,
-            src_path: process.env.PWD,
-            NODE_ENV: "development",
-            APPLICATION: name || "catalyst_app",
-            CATALYST_OUTPUT_MODE: outputMode,
-            ...argumentsObject,
-            filterKeys: JSON.stringify([
-                "src_path",
-                "NODE_ENV",
-                "APPLICATION",
-                ...Object.keys(argumentsObject),
-            ]),
-        },
+    const appConfig = loadAppConfig(process.env.PWD || process.cwd())
+    await ensurePortFree({
+        port: argumentsObject.NODE_SERVER_PORT || appConfig.NODE_SERVER_PORT,
+        host: argumentsObject.NODE_SERVER_HOSTNAME || appConfig.NODE_SERVER_HOSTNAME,
+        scope: "dev server",
     })
+
+    const child = spawn(
+        "node",
+        ["--import", preInitPath, "--import", loaderImportArg(loaderPath), "./dist/server/expressServer.js"],
+        {
+            cwd: dirname,
+            stdio: ["inherit", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                // Piping the child's stdout makes it a non-TTY, so colour
+                // libraries in the child disable themselves and the banner
+                // arrives grey. Pass our own terminal's answer down, so the
+                // child colours only when there is a real terminal to colour
+                // for -- and a redirect to a file still comes out plain.
+                ...(process.stdout.isTTY && !process.env.NO_COLOR ? { FORCE_COLOR: "1" } : {}),
+                // Tells the server its output is being consumed, so it may
+                // fence the banner. Unset when run directly.
+                CATALYST_WRAPPED: "1",
+                // When the command was run, so "Ready in" counts the whole wait.
+                CATALYST_STARTED_AT: String(Math.round(performance.timeOrigin)),
+                src_path: process.env.PWD,
+                NODE_ENV: "development",
+                APPLICATION: name || "catalyst_app",
+                CATALYST_OUTPUT_MODE: outputMode,
+                ...argumentsObject,
+                filterKeys: JSON.stringify([
+                    "CATALYST_WRAPPED",
+                    "src_path",
+                    "NODE_ENV",
+                    "APPLICATION",
+                    ...Object.keys(argumentsObject),
+                ]),
+            },
+        }
+    )
+
+    superviseServer(child, { scope: "dev server", label: "development server" })
 }
 
 start()

package/dist/server/expressServer.js

@@ -5,18 +5,106 @@ import compression from "compression";
 import cookieParser from "cookie-parser";
 import expressStaticGzip from "express-static-gzip";
 import { createServer as createViteServer } from "vite";
-import util from "node:util";
-import pc from "ansis";
+import os from "node:os";
 import fs from "fs";
-const {
-  cyan,
-  yellow,
-  green
-} = pc;
 import { toMountPathPrefix } from "../vite/resolveDevServerConfig.js";
 import { validateMiddleware, handleError, safeCall } from "./utils/validator.js";
 import { botDetectionMiddleware } from "./utils/botDetectionMiddleware.js";
 import { cjsRequire } from "./utils/cjsRequire.js";
+const {
+  header,
+  row,
+  glyph,
+  t,
+  GUTTER,
+  duration
+} = cjsRequire("../../cli/theme.js");
+const {
+  diagnostic,
+  runtimeFailure
+} = cjsRequire("../../cli/diagnostic.js");
+const {
+  hintFor
+} = cjsRequire("../../cli/hints.js");
+
+// "Ready in" should measure what the person waited for: from the moment they
+// ran the command, not from when this child process happened to load. The CLI
+// stamps that moment; run directly, module load is the best we have.
+const serverStartedAt = Number(process.env.CATALYST_STARTED_AT) || Date.now();
+const outputMode = process.env.CATALYST_OUTPUT_MODE || "default";
+const verbose = outputMode === "verbose" || outputMode === "debug";
+
+// Set in development once Vite is up: maps a stack from Vite's transformed SSR
+// modules back to the source lines the user wrote.
+let fixStacktrace = null;
+const stackFixed = new WeakSet();
+
+// Reloading a broken page re-throws the same error on every request. After the
+// first full report, a repeat gets one line until something different fails.
+let lastReport = null;
+
+/**
+ * Report a runtime error in the house style. Exposed on globalThis because the
+ * SSR handler is bundled into the app's build and cannot import this module's
+ * CLI helpers by path; it calls this when present.
+ */
+function reportRuntimeError({
+  error,
+  code,
+  docs,
+  scope
+}) {
+  if (fixStacktrace && error && typeof error === "object" && !stackFixed.has(error)) {
+    stackFixed.add(error);
+    try {
+      fixStacktrace(error);
+    } catch {
+      // A stack we cannot map is still worth printing as-is.
+    }
+  }
+  const fingerprint = `${code}|${error?.message ?? String(error)}|${String(error?.stack || "").split("\n")[1] || ""}`;
+  if (fingerprint === lastReport && outputMode === "default") {
+    process.stderr.write(`${GUTTER}${t.bad(glyph.fail)} ${t.dim(`Same error again${scope ? `  ${scope}` : ""}`)}\n`);
+    return;
+  }
+  lastReport = fingerprint;
+  process.stderr.write(runtimeFailure({
+    error,
+    code,
+    docs,
+    scope,
+    mode: outputMode,
+    env: outputMode === "debug" ? {
+      node: process.version,
+      platform: process.platform
+    } : undefined,
+    cwd: process.env.src_path || process.cwd()
+  }));
+}
+;
+globalThis.__catalystReportRuntimeError = reportRuntimeError;
+
+// Invisible fences around the banner block. The wrapper strips these; if the
+// server is run directly they are two blank-looking lines.
+const {
+  BANNER_START,
+  BANNER_END,
+  NEXT_STEP
+} = cjsRequire("../../cli/devOutput.js");
+
+/** First non-internal IPv4 address, so the banner can offer a LAN URL. */
+function lanAddress() {
+  try {
+    for (const interfaces of Object.values(os.networkInterfaces())) {
+      for (const entry of interfaces || []) {
+        if (entry.family === "IPv4" && !entry.internal) return entry.address;
+      }
+    }
+  } catch (error) {
+    // Not worth failing a server start over.
+  }
+  return null;
+}
 const {
   addMiddlewares
 } = await import(path.join(process.env.src_path, "server/server.js"));
@@ -31,7 +119,8 @@ function mountAIRouter(app) {
   } catch (resolveErr) {
     if (resolveErr.code !== "MODULE_NOT_FOUND") {
       console.error("[catalyst-core/ai] Unexpected error resolving catalyst-ai:", resolveErr);
-    } else {
+    } else if (verbose) {
+      // Not installing an optional package is not news on every start.
       console.debug("[catalyst-core/ai] catalyst-ai not installed — AI routes unavailable");
     }
     return;
@@ -54,7 +143,6 @@ function mountAIRouter(app) {
       return;
     }
     const aiBasePath = aiConfig.basePath || "/ai";
-    console.log(`[catalyst-core/ai] mounting AI router at ${aiBasePath}`);
     app.use(aiBasePath, aiRouter);
   } catch (mountErr) {
     console.error("[catalyst-core/ai] Failed to mount AI router:", mountErr);
@@ -97,15 +185,34 @@ function safeStringify(err) {
   }
 }
 process.on("uncaughtException", (err, origin) => {
-  console.log(process.stderr.fd);
-  console.log(`Caught exception: ${err}\n` + `Exception origin: ${origin}`);
+  // A server that cannot bind its port is dead -- swallowing that left the
+  // process alive but useless, so `catalyst start` hung with a blank screen.
+  // Report it the way every other failure is reported, then exit.
+  const code = err?.code;
+  if (code === "EADDRINUSE" || code === "EACCES") {
+    const known = hintFor(err.message);
+    process.stderr.write(diagnostic({
+      message: err.message,
+      scope: "dev server",
+      hint: known?.hint,
+      docs: known?.docs
+    }));
+    process.exit(1);
+  }
+  reportRuntimeError({
+    error: err,
+    scope: origin === "unhandledRejection" ? "unhandled rejection" : "uncaught exception"
+  });
 });
-process.on("uncaughtExceptionMonitor", (err, origin) => {
-  console.log(err, origin);
+process.on("unhandledRejection", err => {
+  // A rejection with a non-Error reason still deserves a readable line.
+  const error = err instanceof Error ? err : new Error(safeStringify(err) || String(err));
+  reportRuntimeError({
+    error,
+    scope: "unhandled rejection"
+  });
 });
-process.on("unhandledRejection", err => console.log("unhandledRejection in Catalyst", err?.stack || safeStringify(err)));
 process.on("SIGINT", function () {
-  console.log("SIGINT");
   process.exit(0);
 });
 process.on("message", function (msg) {
@@ -201,6 +308,7 @@ async function createServer() {
       appType: "custom",
       root: process.env.src_path
     });
+    fixStacktrace = error => vite.ssrFixStacktrace(error);
 
     // Expose Vite's resolved base to the SSR renderer so the URLs it injects
     // (client entry, react-refresh preamble) match the path Vite serves under.
@@ -241,11 +349,13 @@ async function createServer() {
         res.status(500).send("Error loading renderer");
       }
     } catch (err) {
-      console.error("SSR Error:", err);
-      if (vite) {
-        vite.ssrFixStacktrace(err);
-      }
-      res.status(500).send("Internal Server Error");
+      // Reached when the renderer itself fails to load or throws before
+      // its own error handling -- e.g. a syntax error in an app module.
+      reportRuntimeError({
+        error: err,
+        scope: `${req.method} ${req.originalUrl}`
+      });
+      if (!res.headersSent) res.status(500).send("Internal Server Error");
     }
   });
   app.listen({
@@ -253,26 +363,51 @@ async function createServer() {
     host
   }, error => {
     const {
-      APPLICATION,
       NODE_SERVER_HOSTNAME,
       NODE_SERVER_PORT
     } = process.env;
+    const isDev = process.env.NODE_ENV === "development";
     if (error) {
-      console.log("An error occured while starting the Application server : ", error);
+      const known = hintFor(error.message);
+      process.stderr.write(diagnostic({
+        message: `Could not start the server: ${error.message}`,
+        scope: isDev ? "dev server" : "server",
+        hint: known?.hint,
+        docs: known?.docs
+      }));
       safeCall(onServerError);
       return;
     }
-    if (process.env.NODE_ENV === "development") console.log(green("Compiled successfully!"));
-    console.log(`\nYou can now view ${APPLICATION} in the browser.\n`);
-    console.log(util.format("\tLocal:".padEnd(8), cyan(`http://${NODE_SERVER_HOSTNAME}:${NODE_SERVER_PORT}`)));
-    if (process.env.NODE_ENV === "development") {
-      console.log("\nNote that the development build is not optimized.");
-      console.log("To create a production build, use " + cyan("npm run build"));
-    } else {
-      console.log(green(`\nProduction server running in ${isProduction ? "production" : "development"} mode`));
+
+    // Reached from the listen callback, so this means a port was bound --
+    // it says nothing about whether anything compiled. Claiming a
+    // successful compile here was an outright lie when the bundle failed.
+    const elapsed = Date.now() - serverStartedAt;
+
+    // Fence the banner so the wrapper can forward it verbatim instead of
+    // guessing from its text -- colour codes made pattern-matching the
+    // lines unreliable, and the guesswork mis-filed the rule and the URL.
+    const wrapped = process.env.CATALYST_WRAPPED === "1";
+    if (wrapped) process.stdout.write(`${BANNER_START}\n`);
+    process.stdout.write(header(`catalyst ${isDev ? "start" : "serve"}`, isDev ? "development" : "production"));
+    console.log(`${GUTTER}${t.ok(glyph.done)} Ready in ${t.bold(duration(elapsed))}\n`);
+
+    // An app can bind to a LAN address rather than localhost, in which case
+    // "Local" and "Network" would print the same URL twice. Show the bound
+    // address as Local, and only offer a Network line when it differs.
+    const boundHost = NODE_SERVER_HOSTNAME || "localhost";
+    console.log(row("Local", t.accent(`http://${boundHost}:${NODE_SERVER_PORT}`)));
+    const lan = lanAddress();
+    const reachableEverywhere = boundHost === "0.0.0.0" || boundHost === "::";
+    if (lan && lan !== boundHost && (reachableEverywhere || boundHost === "localhost")) {
+      console.log(row("Network", t.dim(`http://${lan}:${NODE_SERVER_PORT}`)));
     }
-    console.log("\nFind out more about deployment here:");
-    console.log(yellow("\n https://catalyst.1mg.com/public_docs/content/deployment\n"));
+
+    // The next-step line is the one thing to act on, so it is handed to the
+    // wrapper fenced rather than printed here -- the wrapper prints it after
+    // any notices, which would otherwise bury it.
+    process.stdout.write(`${wrapped ? NEXT_STEP : ""}${GUTTER}${t.dim(isDev ? "Watching for changes. " : "Serving ")}` + `${isDev ? "" : t.accent(`${process.env.BUILD_OUTPUT_PATH || "build"}/`)}` + `${t.dim(isDev ? "Press Ctrl+C to stop." : ". Press Ctrl+C to stop.")}\n`);
+    if (wrapped) process.stdout.write(`${BANNER_END}\n`);
   });
 }
 createServer().catch(err => {