fix(core): address review feedback on graceful shutdown

- Extract hard-coded timeout into FORCE_SHUTDOWN_TIMEOUT_MS constant
- Add JSDoc for shutdown function with @param and @returns
- Log error in catch block instead of swallowing silently

Author: PierreBrisorgueil

lib/app.js

@@ -127,13 +127,22 @@ const start = async () => {
   }
 };
 
-// Shut down the server
+const FORCE_SHUTDOWN_TIMEOUT_MS = 5000;
+
+/**
+ * Gracefully shut down the server, disconnecting services before exiting.
+ * If the server promise rejects (e.g. failed to start), logs the error and exits.
+ * A forced exit is triggered after {@link FORCE_SHUTDOWN_TIMEOUT_MS} ms if shutdown hangs.
+ *
+ * @param {Promise<{http: import('http').Server}>} server - Promise returned by {@link start}
+ * @returns {Promise<void>} Resolves when shutdown is initiated (process exits via callback)
+ */
 const shutdown = async (server) => {
-  // Force exit after 5s if graceful shutdown hangs
+  // Force exit if graceful shutdown hangs
   const forceTimeout = setTimeout(() => {
     console.error(chalk.red('Forced shutdown (timeout)'));
     process.exit(1);
-  }, 5000);
+  }, FORCE_SHUTDOWN_TIMEOUT_MS);
   forceTimeout.unref();
 
   try {
@@ -147,8 +156,8 @@ const shutdown = async (server) => {
       }
       process.exit();
     });
-  } catch {
-    // Server never started — just exit
+  } catch (err) {
+    console.error(chalk.red('Shutdown error: server never started or shutdown failed'), err);
     process.exit(1);
   }
 };