@rvoh/psychic 3.10.1 → 3.11.0

package/dist/cjs/src/bin/helpers/OpenApiSpecDiff.js

@@ -90,6 +90,10 @@ export class OpenApiSpecDiff {
     }
     /**
      * Validates that oasdiff is installed and builds the oasdiff config
+     *
+     * Marked `protected` so tests can supply a deterministic config (e.g. a
+     * command guaranteed to fail) instead of probing the local oasdiff install
+     * and git remote. Production code never overrides this.
      */
     getOasDiffConfig() {
         const headBranch = this.getHeadBranch();
@@ -133,8 +137,10 @@ export class OpenApiSpecDiff {
             return output.trim();
         }
         catch (error) {
-            const errorOutput = error instanceof Error ? error.message : String(error);
-            return errorOutput;
+            // a failed oasdiff invocation must never be mistaken for diff output
+            // (previously the error text was returned and string-matched, so a
+            // broken oasdiff read as "no breaking changes")
+            throw new OasDiffCommandFailedError(subcommand, error);
         }
     }
     /**
@@ -159,25 +165,15 @@ export class OpenApiSpecDiff {
         }
         const breakingChanges = this.runOasDiffCommand('breaking', mainFilePath, currentFilePath);
         const changelogChanges = this.runOasDiffCommand('changelog', mainFilePath, currentFilePath);
-        const breaking = breakingChanges &&
-            !breakingChanges.includes('Command failed') &&
-            !this.isNoChangesOutput(breakingChanges)
+        const breaking = breakingChanges && !this.isNoChangesOutput(breakingChanges)
             ? breakingChanges.split('\n').filter(line => line.trim())
             : [];
-        const changelog = changelogChanges &&
-            !changelogChanges.includes('Command failed') &&
-            !this.isNoChangesOutput(changelogChanges)
+        const changelog = changelogChanges && !this.isNoChangesOutput(changelogChanges)
             ? changelogChanges.split('\n').filter(line => line.trim())
             : [];
-        const failedToCompare = breakingChanges.includes('Command failed')
-            ? breakingChanges
-            : changelogChanges.includes('Command failed')
-                ? changelogChanges
-                : '';
         return {
             breaking,
             changelog,
-            error: failedToCompare,
         };
     }
     /**
@@ -235,18 +231,23 @@ export class OpenApiSpecDiff {
             return result;
         }
         const tempMainFilePath = this.createTempFilePath(config.outputFilepath);
-        const mainContent = this.getHeadBranchContent(currentFilePath);
-        fs.mkdirSync(path.dirname(tempMainFilePath), { recursive: true });
-        fs.writeFileSync(tempMainFilePath, mainContent);
         try {
-            const { breaking, changelog, error } = this.compareSpecs(tempMainFilePath, currentFilePath);
+            // inside the try so a failed `git show` (e.g. file unreadable on the
+            // head branch) is recorded as this file's error instead of escaping
+            // and aborting the entire diff run with a raw error
+            const mainContent = this.getHeadBranchContent(currentFilePath);
+            fs.mkdirSync(path.dirname(tempMainFilePath), { recursive: true });
+            fs.writeFileSync(tempMainFilePath, mainContent);
+            const { breaking, changelog } = this.compareSpecs(tempMainFilePath, currentFilePath);
             result.breaking = breaking;
             result.changelog = changelog;
             result.hasChanges = breaking.length > 0 || changelog.length > 0;
-            result.error = error ?? '';
         }
         catch (error) {
-            result.error = `Could not retrieve ${config.outputFilepath} from ${this.oasdiffConfig?.headBranch} branch: ${String(error)}`;
+            result.error =
+                error instanceof OasDiffCommandFailedError
+                    ? error.message
+                    : `Could not retrieve ${config.outputFilepath} from ${this.oasdiffConfig?.headBranch} branch: ${String(error)}`;
         }
         finally {
             if (fs.existsSync(tempMainFilePath)) {
@@ -261,9 +262,11 @@ export class OpenApiSpecDiff {
     processResults(results) {
         let hasAnyChanges = false;
         let hasBreakingChanges = false;
+        const erroredFiles = [];
         for (const result of results) {
             if (result.error) {
                 this.logError(result);
+                erroredFiles.push(result.file);
             }
             else if (result.hasChanges) {
                 this.logChanges(result);
@@ -280,7 +283,7 @@ export class OpenApiSpecDiff {
                 this.logNoChanges(result);
             }
         }
-        this.logSummary(hasAnyChanges, hasBreakingChanges);
+        this.logSummary(hasAnyChanges, hasBreakingChanges, erroredFiles);
     }
     /**
      * Log error for a comparison result
@@ -337,7 +340,7 @@ export class OpenApiSpecDiff {
     /**
      * Log final summary and handle exit conditions
      */
-    logSummary(hasAnyChanges, hasBreakingChanges) {
+    logSummary(hasAnyChanges, hasBreakingChanges, erroredFiles) {
         DreamCLI.logger.logContinueProgress(`\n${colorize(`${'='.repeat(60)}`, { color: 'gray' })}`, {
             logPrefixColor: 'gray',
         });
@@ -351,6 +354,10 @@ export class OpenApiSpecDiff {
             });
             throw new BreakingChangesDetectedInOpenApiSpecError(this.oasdiffConfig);
         }
+        else if (erroredFiles.length > 0) {
+            DreamCLI.logger.logContinueProgress(`${colorize(`❌ CRITICAL:`, { color: 'redBright' })} ${colorize(`The OpenAPI diff tooling failed for: ${erroredFiles.join(', ')}. This result is inconclusive — it is NOT a clean "no breaking changes" result.`, { color: 'whiteBright' })}`, { logPrefixColor: 'redBright' });
+            throw new OpenApiSpecDiffToolFailureError(erroredFiles);
+        }
         else if (hasAnyChanges) {
             const summary = colorize(`📊 Summary: Some OpenAPI files have non-breaking changes in current branch compared to ${this.oasdiffConfig?.headBranch}`, { color: 'yellow' });
             DreamCLI.logger.logContinueProgress(summary, { logPrefixColor: 'yellow' });
@@ -385,3 +392,35 @@ export class BreakingChangesDetectedInOpenApiSpecError extends Error {
         return `Breaking changes detected in current branch compared to ${this.oasdiffConfig.headBranch}! Review before merging.`;
     }
 }
+/**
+ * Thrown when the diff tooling itself fails (oasdiff invocation error,
+ * unreadable head-branch spec, missing spec file), as opposed to oasdiff
+ * successfully running and detecting breaking changes
+ * ({@link BreakingChangesDetectedInOpenApiSpecError}). Under
+ * `psy diff:openapi --fail-on-breaking`, both exit nonzero, but with
+ * distinguishable messages: an inconclusive diff must never pass a CI gate
+ * as "no breaking changes".
+ */
+export class OpenApiSpecDiffToolFailureError extends Error {
+    erroredFiles;
+    constructor(erroredFiles) {
+        super();
+        this.erroredFiles = erroredFiles;
+        this.name = 'OpenApiSpecDiffToolFailureError';
+    }
+    get message() {
+        return `OpenAPI spec diff could not complete for: ${this.erroredFiles.join(', ')}. The diff tooling failed, so this result is inconclusive — this is a tool failure, NOT a breaking-changes result.`;
+    }
+}
+/**
+ * Internal marker for a failed oasdiff invocation, so
+ * {@link OpenApiSpecDiff.compareConfig} can distinguish "oasdiff itself
+ * failed" from "could not retrieve head-branch content" when recording
+ * a per-file error.
+ */
+export class OasDiffCommandFailedError extends Error {
+    constructor(subcommand, cause) {
+        super(`oasdiff ${subcommand} invocation failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = 'OasDiffCommandFailedError';
+    }
+}

package/dist/cjs/src/bin/index.js

@@ -13,7 +13,7 @@ import generateRouteTypes from './helpers/generateRouteTypes.js';
 import { OpenApiSpecDiff } from './helpers/OpenApiSpecDiff.js';
 import printControllerHierarchy, { controllerHierarchyViolations, } from './helpers/printControllerHierarchy.js';
 import printRoutes from './helpers/printRoutes.js';
-export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
+export { BreakingChangesDetectedInOpenApiSpecError, OpenApiSpecDiffToolFailureError, } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
     static async generateController(controllerName, actions) {
         await generateController({

package/dist/cjs/src/cli/index.js

@@ -1,5 +1,5 @@
 import { DreamCLI } from '@rvoh/dream/system';
-import PsychicBin, { BreakingChangesDetectedInOpenApiSpecError } from '../bin/index.js';
+import PsychicBin, { BreakingChangesDetectedInOpenApiSpecError, OpenApiSpecDiffToolFailureError, } from '../bin/index.js';
 import generateController from '../generate/controller.js';
 import generateSyncEnumsInitializer from '../generate/initializer/syncEnums.js';
 import generateSyncOpenapiTypescriptInitializer from '../generate/initializer/syncOpenapiTypescript.js';
@@ -408,6 +408,16 @@ ${INDENT}  pnpm psy diff:openapi --fail-on-breaking  # exit 1 if breaking change
                         process.exit(1);
                     }
                 }
+                else if (error instanceof OpenApiSpecDiffToolFailureError) {
+                    // a failed diff tool is inconclusive; under --fail-on-breaking an
+                    // inconclusive result must fail the CI gate rather than pass as
+                    // "no breaking changes". Without the flag (informational mode),
+                    // the failure is printed loudly but the exit code is unchanged.
+                    console.error(error.message);
+                    if (options.failOnBreaking) {
+                        process.exit(1);
+                    }
+                }
                 else {
                     throw error;
                 }

package/dist/cjs/src/psychic-app/index.js

@@ -487,6 +487,24 @@ Try setting it to something valid, like:
     plugin(cb) {
         this._plugins.push(cb);
     }
+    /**
+     * Registers a callback for one of psychic's lifecycle hooks.
+     *
+     * ### `server:error`
+     *
+     * Called any time the server encounters an error it isn't sure how to
+     * respond to (i.e. a 500). This covers errors thrown from controller
+     * actions as well as errors raised outside the router — e.g. in the body
+     * parser, cors callbacks, custom `psy.use` middleware, or after-routes
+     * mounts — which are captured by an error boundary mounted outermost in
+     * the middleware stack. Hooks are awaited and may shape the response via
+     * `ctx`; if they don't, psychic responds 500. Errors carrying a 4xx status
+     * (e.g. a body-parser 400) are rendered as that status and never reach
+     * `server:error` hooks.
+     *
+     * NOTE: once any `server:error` hook is registered, psychic considers the
+     * error handled and does not re-throw it to Koa.
+     */
     on(hookEventType, cb) {
         switch (hookEventType) {
             case 'server:error':

package/dist/cjs/src/router/index.js

@@ -11,6 +11,7 @@ import EnvInternal from '../helpers/EnvInternal.js';
 import errorIsRescuableHttpError from '../helpers/error/errorIsRescuableHttpError.js';
 import PsychicApp from '../psychic-app/index.js';
 import { applyResourcefulAction, convertRouteParams, lookupControllerOrFail, routePath, } from '../router/helpers.js';
+import { psychicRouterProcessedErrorStateKey } from '../server/helpers/errorBoundaryMiddleware.js';
 import RouteManager from './route-manager.js';
 import { ResourceMethods, ResourcesMethods, } from './types.js';
 const ERROR_LOGGING_DEPTH = 6;
@@ -317,6 +318,12 @@ suggested fix:  "${convertRouteParams(path)}"
                 controllerInstance['koaSendStatus'](400);
             }
             else {
+                // mark the request so the error-boundary middleware passes anything
+                // this branch throws straight through to Koa: the deliberate
+                // dev/test re-throw of a failing server:error hook below must not
+                // run the hooks a second time, and with no hooks registered the
+                // re-thrown action error keeps Koa's default handling
+                ctx.state[psychicRouterProcessedErrorStateKey] = true;
                 PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
                 if (PsychicApp.getOrFail().specialHooks.serverError.length) {
                     try {

package/dist/cjs/src/server/helpers/errorBoundaryMiddleware.js

@@ -0,0 +1,104 @@
+import * as util from 'node:util';
+import HttpError from '../../error/http/index.js';
+import EnvInternal from '../../helpers/EnvInternal.js';
+import PsychicApp from '../../psychic-app/index.js';
+export const ERROR_LOGGING_DEPTH = 6;
+/**
+ * @internal
+ *
+ * Set on `ctx.state` by the router when it processes an error thrown from a
+ * controller action (running `server:error` hooks when any are registered,
+ * or deliberately re-throwing to Koa when none are). The error boundary
+ * passes marked errors through untouched so a single request can never run
+ * `server:error` hooks twice, and so the router's deliberate dev/test
+ * re-throw behavior reaches Koa exactly as it did before the boundary
+ * existed.
+ */
+export const psychicRouterProcessedErrorStateKey = '_psychicRouterProcessedError';
+/**
+ * @internal
+ *
+ * The outermost middleware psychic mounts. Everything mounted after it —
+ * secure default headers, etag, cors, the body parser, `psy.use` middleware,
+ * after-routes mounts, and the router itself — runs inside `await next()`,
+ * so any error those layers throw (and the router doesn't catch) lands here
+ * instead of falling through to Koa's default handler.
+ *
+ * Errors carrying a 4xx status (e.g. a body-parser 400, or an `HttpError`
+ * thrown from custom middleware) already name their response: the boundary
+ * renders that status without involving `server:error` hooks. Anything else
+ * is a genuine server error: it is logged, given a default 500 response, and
+ * escalated to `server:error` hooks, which may reshape the response.
+ */
+export default function errorBoundaryMiddleware() {
+    return async function psychicErrorBoundary(ctx, next) {
+        try {
+            await next();
+        }
+        catch (error) {
+            const err = error;
+            // the router already processed this error (see the state key docs
+            // above); let it reach Koa unchanged
+            if (ctx.state[psychicRouterProcessedErrorStateKey])
+                throw err;
+            // once headers are out, the response can no longer be shaped; Koa's
+            // ctx.onerror knows how to clean up the socket, and the app-level
+            // 'error' listener registered by PsychicServer will log it
+            if (ctx.headerSent)
+                throw err;
+            const status = statusFromError(err);
+            if (status !== null && status < 500) {
+                // client-shaped errors are a handled response, not a server error;
+                // server:error hooks are never called for them
+                ctx.status = status;
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                ctx.body = err instanceof HttpError && err.data !== undefined ? err.data : '';
+                return;
+            }
+            PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
+            // default server-error response; server:error hooks may reshape it
+            ctx.status = status ?? 500;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            ctx.body = err instanceof HttpError && err.data !== undefined ? err.data : '';
+            try {
+                for (const hook of PsychicApp.getOrFail().specialHooks.serverError) {
+                    await hook(err, ctx);
+                }
+            }
+            catch (hookError) {
+                if (EnvInternal.isDevelopmentOrTest) {
+                    // mirror the router's deliberate dev/test behavior for throwing
+                    // server:error hooks: surface the hook error so specs can see it
+                    throw hookError;
+                }
+                else {
+                    PsychicApp.logWithLevel('error', `
+              Something went wrong while attempting to call your custom server:error hooks.
+              Psychic will rescue errors thrown here to prevent the server from crashing.
+              The error thrown is:
+            `);
+                    PsychicApp.logWithLevel('error', hookError);
+                }
+            }
+        }
+    };
+}
+/**
+ * @internal
+ *
+ * Extracts an http response status from an error when the error names one:
+ * psychic `HttpError` subclasses, Koa `ctx.throw`/http-errors errors, and
+ * body-parser failures all carry a numeric `status`. Guarded property access
+ * because the base `HttpError#status` getter throws.
+ */
+function statusFromError(err) {
+    try {
+        const status = err?.status;
+        if (typeof status === 'number' && status >= 400 && status <= 599)
+            return status;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cjs/src/server/helpers/startPsychicServer.js

@@ -7,9 +7,17 @@ import PsychicLogos from '../../cli/helpers/PsychicLogos.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import PsychicApp from '../../psychic-app/index.js';
 export default async function startPsychicServer({ app, port, sslCredentials, }) {
-    return await new Promise(accept => {
+    return await new Promise((accept, reject) => {
         const httpOrHttps = createPsychicHttpInstance(app, sslCredentials);
+        // typescript cannot call event-emitter methods on the http/https server
+        // union directly (incompatible overload sets), but both are EventEmitters
+        const emitter = httpOrHttps;
+        // without this listener, a failed bind (e.g. EADDRINUSE, EACCES) escapes
+        // as an uncaught 'error' event and this promise never settles
+        const onListenError = (error) => reject(error);
+        emitter.once('error', onListenError);
         const server = httpOrHttps.listen(port, () => {
+            emitter.off('error', onListenError);
             welcomeMessage({ port });
             accept(server);
         });

package/dist/cjs/src/server/index.js

@@ -4,10 +4,12 @@ import etag from '@koa/etag';
 import { closeAllDbConnections } from '@rvoh/dream/db';
 import Koa from 'koa';
 import conditional from 'koa-conditional-get';
+import * as util from 'node:util';
 import logIfDevelopment from '../controller/helpers/logIfDevelopment.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicApp from '../psychic-app/index.js';
 import PsychicRouter from '../router/index.js';
+import errorBoundaryMiddleware, { ERROR_LOGGING_DEPTH } from './helpers/errorBoundaryMiddleware.js';
 import startPsychicServer, { createPsychicHttpInstance, } from './helpers/startPsychicServer.js';
 // const debugEnabled = debuglog('psychic').enabled
 export default class PsychicServer {
@@ -32,6 +34,21 @@ export default class PsychicServer {
         if (this.booted)
             return;
         const psychicApp = PsychicApp.getOrFail();
+        // outermost middleware: catches errors thrown from anything mounted
+        // after it (body parser, cors, custom `psy.use` middleware, after-routes
+        // mounts) and escalates genuine server errors to server:error hooks.
+        // Errors from controller actions are still processed by the router; the
+        // boundary only sees errors the router never caught.
+        this.koaApp.use(errorBoundaryMiddleware());
+        // residual error sink: the few errors Koa surfaces outside the error
+        // boundary (errors thrown after headers were sent, response-stream
+        // failures, errors the router deliberately re-throws to Koa in
+        // dev/test). Registering a listener supersedes Koa's default stderr
+        // logger, so these flow through the configured psychic logger instead
+        // of going dark.
+        this.koaApp.on('error', (err) => {
+            PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
+        });
         this.setSecureDefaultHeaders();
         this.koaApp.use(async (ctx, next) => {
             Object.keys(psychicApp.defaultResponseHeaders).forEach(key => {
@@ -57,7 +74,7 @@ export default class PsychicServer {
             throw new Error(`
         Failed to boot psychic config. the error thrown was:
           ${error.message}
-      `);
+      `, { cause: error });
         }
         for (const serverInitAfterMiddlewareHook of PsychicApp.getOrFail().specialHooks
             .serverInitAfterMiddleware) {
@@ -134,9 +151,39 @@ export default class PsychicServer {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     $attached = {};
+    /**
+     * @internal
+     *
+     * the maximum number of milliseconds graceful shutdown is allowed
+     * to run before the process exits anyway, so that a hung
+     * `server:shutdown` hook or db close can never keep a dying
+     * process alive
+     */
+    static SHUTDOWN_TIMEOUT_MS = 15000;
     async shutdownAndExit() {
-        await this.stop();
-        process.exit();
+        let exitCode = 0;
+        try {
+            await this.stopWithTimeout();
+        }
+        catch (error) {
+            PsychicApp.logWithLevel('error', '[psychic] error during graceful shutdown:', error);
+            exitCode = 1;
+        }
+        process.exit(exitCode);
+    }
+    /**
+     * @internal
+     *
+     * runs {@link PsychicServer.stop}, rejecting if it has not settled
+     * within SHUTDOWN_TIMEOUT_MS
+     */
+    async stopWithTimeout() {
+        await Promise.race([
+            this.stop(),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`[psychic] graceful shutdown timed out after ${PsychicServer.SHUTDOWN_TIMEOUT_MS}ms`)), PsychicServer.SHUTDOWN_TIMEOUT_MS).unref();
+            }),
+        ]);
     }
     async stop({ bypassClosingDbConnections = false, gracefulShutdownTimeoutMillis = 10_000, } = {}) {
         for (const hook of PsychicApp.getOrFail().specialHooks.serverShutdown) {

package/dist/esm/src/bin/helpers/OpenApiSpecDiff.js

@@ -90,6 +90,10 @@ export class OpenApiSpecDiff {
     }
     /**
      * Validates that oasdiff is installed and builds the oasdiff config
+     *
+     * Marked `protected` so tests can supply a deterministic config (e.g. a
+     * command guaranteed to fail) instead of probing the local oasdiff install
+     * and git remote. Production code never overrides this.
      */
     getOasDiffConfig() {
         const headBranch = this.getHeadBranch();
@@ -133,8 +137,10 @@ export class OpenApiSpecDiff {
             return output.trim();
         }
         catch (error) {
-            const errorOutput = error instanceof Error ? error.message : String(error);
-            return errorOutput;
+            // a failed oasdiff invocation must never be mistaken for diff output
+            // (previously the error text was returned and string-matched, so a
+            // broken oasdiff read as "no breaking changes")
+            throw new OasDiffCommandFailedError(subcommand, error);
         }
     }
     /**
@@ -159,25 +165,15 @@ export class OpenApiSpecDiff {
         }
         const breakingChanges = this.runOasDiffCommand('breaking', mainFilePath, currentFilePath);
         const changelogChanges = this.runOasDiffCommand('changelog', mainFilePath, currentFilePath);
-        const breaking = breakingChanges &&
-            !breakingChanges.includes('Command failed') &&
-            !this.isNoChangesOutput(breakingChanges)
+        const breaking = breakingChanges && !this.isNoChangesOutput(breakingChanges)
             ? breakingChanges.split('\n').filter(line => line.trim())
             : [];
-        const changelog = changelogChanges &&
-            !changelogChanges.includes('Command failed') &&
-            !this.isNoChangesOutput(changelogChanges)
+        const changelog = changelogChanges && !this.isNoChangesOutput(changelogChanges)
             ? changelogChanges.split('\n').filter(line => line.trim())
             : [];
-        const failedToCompare = breakingChanges.includes('Command failed')
-            ? breakingChanges
-            : changelogChanges.includes('Command failed')
-                ? changelogChanges
-                : '';
         return {
             breaking,
             changelog,
-            error: failedToCompare,
         };
     }
     /**
@@ -235,18 +231,23 @@ export class OpenApiSpecDiff {
             return result;
         }
         const tempMainFilePath = this.createTempFilePath(config.outputFilepath);
-        const mainContent = this.getHeadBranchContent(currentFilePath);
-        fs.mkdirSync(path.dirname(tempMainFilePath), { recursive: true });
-        fs.writeFileSync(tempMainFilePath, mainContent);
         try {
-            const { breaking, changelog, error } = this.compareSpecs(tempMainFilePath, currentFilePath);
+            // inside the try so a failed `git show` (e.g. file unreadable on the
+            // head branch) is recorded as this file's error instead of escaping
+            // and aborting the entire diff run with a raw error
+            const mainContent = this.getHeadBranchContent(currentFilePath);
+            fs.mkdirSync(path.dirname(tempMainFilePath), { recursive: true });
+            fs.writeFileSync(tempMainFilePath, mainContent);
+            const { breaking, changelog } = this.compareSpecs(tempMainFilePath, currentFilePath);
             result.breaking = breaking;
             result.changelog = changelog;
             result.hasChanges = breaking.length > 0 || changelog.length > 0;
-            result.error = error ?? '';
         }
         catch (error) {
-            result.error = `Could not retrieve ${config.outputFilepath} from ${this.oasdiffConfig?.headBranch} branch: ${String(error)}`;
+            result.error =
+                error instanceof OasDiffCommandFailedError
+                    ? error.message
+                    : `Could not retrieve ${config.outputFilepath} from ${this.oasdiffConfig?.headBranch} branch: ${String(error)}`;
         }
         finally {
             if (fs.existsSync(tempMainFilePath)) {
@@ -261,9 +262,11 @@ export class OpenApiSpecDiff {
     processResults(results) {
         let hasAnyChanges = false;
         let hasBreakingChanges = false;
+        const erroredFiles = [];
         for (const result of results) {
             if (result.error) {
                 this.logError(result);
+                erroredFiles.push(result.file);
             }
             else if (result.hasChanges) {
                 this.logChanges(result);
@@ -280,7 +283,7 @@ export class OpenApiSpecDiff {
                 this.logNoChanges(result);
             }
         }
-        this.logSummary(hasAnyChanges, hasBreakingChanges);
+        this.logSummary(hasAnyChanges, hasBreakingChanges, erroredFiles);
     }
     /**
      * Log error for a comparison result
@@ -337,7 +340,7 @@ export class OpenApiSpecDiff {
     /**
      * Log final summary and handle exit conditions
      */
-    logSummary(hasAnyChanges, hasBreakingChanges) {
+    logSummary(hasAnyChanges, hasBreakingChanges, erroredFiles) {
         DreamCLI.logger.logContinueProgress(`\n${colorize(`${'='.repeat(60)}`, { color: 'gray' })}`, {
             logPrefixColor: 'gray',
         });
@@ -351,6 +354,10 @@ export class OpenApiSpecDiff {
             });
             throw new BreakingChangesDetectedInOpenApiSpecError(this.oasdiffConfig);
         }
+        else if (erroredFiles.length > 0) {
+            DreamCLI.logger.logContinueProgress(`${colorize(`❌ CRITICAL:`, { color: 'redBright' })} ${colorize(`The OpenAPI diff tooling failed for: ${erroredFiles.join(', ')}. This result is inconclusive — it is NOT a clean "no breaking changes" result.`, { color: 'whiteBright' })}`, { logPrefixColor: 'redBright' });
+            throw new OpenApiSpecDiffToolFailureError(erroredFiles);
+        }
         else if (hasAnyChanges) {
             const summary = colorize(`📊 Summary: Some OpenAPI files have non-breaking changes in current branch compared to ${this.oasdiffConfig?.headBranch}`, { color: 'yellow' });
             DreamCLI.logger.logContinueProgress(summary, { logPrefixColor: 'yellow' });
@@ -385,3 +392,35 @@ export class BreakingChangesDetectedInOpenApiSpecError extends Error {
         return `Breaking changes detected in current branch compared to ${this.oasdiffConfig.headBranch}! Review before merging.`;
     }
 }
+/**
+ * Thrown when the diff tooling itself fails (oasdiff invocation error,
+ * unreadable head-branch spec, missing spec file), as opposed to oasdiff
+ * successfully running and detecting breaking changes
+ * ({@link BreakingChangesDetectedInOpenApiSpecError}). Under
+ * `psy diff:openapi --fail-on-breaking`, both exit nonzero, but with
+ * distinguishable messages: an inconclusive diff must never pass a CI gate
+ * as "no breaking changes".
+ */
+export class OpenApiSpecDiffToolFailureError extends Error {
+    erroredFiles;
+    constructor(erroredFiles) {
+        super();
+        this.erroredFiles = erroredFiles;
+        this.name = 'OpenApiSpecDiffToolFailureError';
+    }
+    get message() {
+        return `OpenAPI spec diff could not complete for: ${this.erroredFiles.join(', ')}. The diff tooling failed, so this result is inconclusive — this is a tool failure, NOT a breaking-changes result.`;
+    }
+}
+/**
+ * Internal marker for a failed oasdiff invocation, so
+ * {@link OpenApiSpecDiff.compareConfig} can distinguish "oasdiff itself
+ * failed" from "could not retrieve head-branch content" when recording
+ * a per-file error.
+ */
+export class OasDiffCommandFailedError extends Error {
+    constructor(subcommand, cause) {
+        super(`oasdiff ${subcommand} invocation failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = 'OasDiffCommandFailedError';
+    }
+}

package/dist/esm/src/bin/index.js

@@ -13,7 +13,7 @@ import generateRouteTypes from './helpers/generateRouteTypes.js';
 import { OpenApiSpecDiff } from './helpers/OpenApiSpecDiff.js';
 import printControllerHierarchy, { controllerHierarchyViolations, } from './helpers/printControllerHierarchy.js';
 import printRoutes from './helpers/printRoutes.js';
-export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
+export { BreakingChangesDetectedInOpenApiSpecError, OpenApiSpecDiffToolFailureError, } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
     static async generateController(controllerName, actions) {
         await generateController({

package/dist/esm/src/cli/index.js

@@ -1,5 +1,5 @@
 import { DreamCLI } from '@rvoh/dream/system';
-import PsychicBin, { BreakingChangesDetectedInOpenApiSpecError } from '../bin/index.js';
+import PsychicBin, { BreakingChangesDetectedInOpenApiSpecError, OpenApiSpecDiffToolFailureError, } from '../bin/index.js';
 import generateController from '../generate/controller.js';
 import generateSyncEnumsInitializer from '../generate/initializer/syncEnums.js';
 import generateSyncOpenapiTypescriptInitializer from '../generate/initializer/syncOpenapiTypescript.js';
@@ -408,6 +408,16 @@ ${INDENT}  pnpm psy diff:openapi --fail-on-breaking  # exit 1 if breaking change
                         process.exit(1);
                     }
                 }
+                else if (error instanceof OpenApiSpecDiffToolFailureError) {
+                    // a failed diff tool is inconclusive; under --fail-on-breaking an
+                    // inconclusive result must fail the CI gate rather than pass as
+                    // "no breaking changes". Without the flag (informational mode),
+                    // the failure is printed loudly but the exit code is unchanged.
+                    console.error(error.message);
+                    if (options.failOnBreaking) {
+                        process.exit(1);
+                    }
+                }
                 else {
                     throw error;
                 }

package/dist/esm/src/psychic-app/index.js

@@ -487,6 +487,24 @@ Try setting it to something valid, like:
     plugin(cb) {
         this._plugins.push(cb);
     }
+    /**
+     * Registers a callback for one of psychic's lifecycle hooks.
+     *
+     * ### `server:error`
+     *
+     * Called any time the server encounters an error it isn't sure how to
+     * respond to (i.e. a 500). This covers errors thrown from controller
+     * actions as well as errors raised outside the router — e.g. in the body
+     * parser, cors callbacks, custom `psy.use` middleware, or after-routes
+     * mounts — which are captured by an error boundary mounted outermost in
+     * the middleware stack. Hooks are awaited and may shape the response via
+     * `ctx`; if they don't, psychic responds 500. Errors carrying a 4xx status
+     * (e.g. a body-parser 400) are rendered as that status and never reach
+     * `server:error` hooks.
+     *
+     * NOTE: once any `server:error` hook is registered, psychic considers the
+     * error handled and does not re-throw it to Koa.
+     */
     on(hookEventType, cb) {
         switch (hookEventType) {
             case 'server:error':

package/dist/esm/src/router/index.js

@@ -11,6 +11,7 @@ import EnvInternal from '../helpers/EnvInternal.js';
 import errorIsRescuableHttpError from '../helpers/error/errorIsRescuableHttpError.js';
 import PsychicApp from '../psychic-app/index.js';
 import { applyResourcefulAction, convertRouteParams, lookupControllerOrFail, routePath, } from '../router/helpers.js';
+import { psychicRouterProcessedErrorStateKey } from '../server/helpers/errorBoundaryMiddleware.js';
 import RouteManager from './route-manager.js';
 import { ResourceMethods, ResourcesMethods, } from './types.js';
 const ERROR_LOGGING_DEPTH = 6;
@@ -317,6 +318,12 @@ suggested fix:  "${convertRouteParams(path)}"
                 controllerInstance['koaSendStatus'](400);
             }
             else {
+                // mark the request so the error-boundary middleware passes anything
+                // this branch throws straight through to Koa: the deliberate
+                // dev/test re-throw of a failing server:error hook below must not
+                // run the hooks a second time, and with no hooks registered the
+                // re-thrown action error keeps Koa's default handling
+                ctx.state[psychicRouterProcessedErrorStateKey] = true;
                 PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
                 if (PsychicApp.getOrFail().specialHooks.serverError.length) {
                     try {

package/dist/esm/src/server/helpers/errorBoundaryMiddleware.js

@@ -0,0 +1,104 @@
+import * as util from 'node:util';
+import HttpError from '../../error/http/index.js';
+import EnvInternal from '../../helpers/EnvInternal.js';
+import PsychicApp from '../../psychic-app/index.js';
+export const ERROR_LOGGING_DEPTH = 6;
+/**
+ * @internal
+ *
+ * Set on `ctx.state` by the router when it processes an error thrown from a
+ * controller action (running `server:error` hooks when any are registered,
+ * or deliberately re-throwing to Koa when none are). The error boundary
+ * passes marked errors through untouched so a single request can never run
+ * `server:error` hooks twice, and so the router's deliberate dev/test
+ * re-throw behavior reaches Koa exactly as it did before the boundary
+ * existed.
+ */
+export const psychicRouterProcessedErrorStateKey = '_psychicRouterProcessedError';
+/**
+ * @internal
+ *
+ * The outermost middleware psychic mounts. Everything mounted after it —
+ * secure default headers, etag, cors, the body parser, `psy.use` middleware,
+ * after-routes mounts, and the router itself — runs inside `await next()`,
+ * so any error those layers throw (and the router doesn't catch) lands here
+ * instead of falling through to Koa's default handler.
+ *
+ * Errors carrying a 4xx status (e.g. a body-parser 400, or an `HttpError`
+ * thrown from custom middleware) already name their response: the boundary
+ * renders that status without involving `server:error` hooks. Anything else
+ * is a genuine server error: it is logged, given a default 500 response, and
+ * escalated to `server:error` hooks, which may reshape the response.
+ */
+export default function errorBoundaryMiddleware() {
+    return async function psychicErrorBoundary(ctx, next) {
+        try {
+            await next();
+        }
+        catch (error) {
+            const err = error;
+            // the router already processed this error (see the state key docs
+            // above); let it reach Koa unchanged
+            if (ctx.state[psychicRouterProcessedErrorStateKey])
+                throw err;
+            // once headers are out, the response can no longer be shaped; Koa's
+            // ctx.onerror knows how to clean up the socket, and the app-level
+            // 'error' listener registered by PsychicServer will log it
+            if (ctx.headerSent)
+                throw err;
+            const status = statusFromError(err);
+            if (status !== null && status < 500) {
+                // client-shaped errors are a handled response, not a server error;
+                // server:error hooks are never called for them
+                ctx.status = status;
+                // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+                ctx.body = err instanceof HttpError && err.data !== undefined ? err.data : '';
+                return;
+            }
+            PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
+            // default server-error response; server:error hooks may reshape it
+            ctx.status = status ?? 500;
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+            ctx.body = err instanceof HttpError && err.data !== undefined ? err.data : '';
+            try {
+                for (const hook of PsychicApp.getOrFail().specialHooks.serverError) {
+                    await hook(err, ctx);
+                }
+            }
+            catch (hookError) {
+                if (EnvInternal.isDevelopmentOrTest) {
+                    // mirror the router's deliberate dev/test behavior for throwing
+                    // server:error hooks: surface the hook error so specs can see it
+                    throw hookError;
+                }
+                else {
+                    PsychicApp.logWithLevel('error', `
+              Something went wrong while attempting to call your custom server:error hooks.
+              Psychic will rescue errors thrown here to prevent the server from crashing.
+              The error thrown is:
+            `);
+                    PsychicApp.logWithLevel('error', hookError);
+                }
+            }
+        }
+    };
+}
+/**
+ * @internal
+ *
+ * Extracts an http response status from an error when the error names one:
+ * psychic `HttpError` subclasses, Koa `ctx.throw`/http-errors errors, and
+ * body-parser failures all carry a numeric `status`. Guarded property access
+ * because the base `HttpError#status` getter throws.
+ */
+function statusFromError(err) {
+    try {
+        const status = err?.status;
+        if (typeof status === 'number' && status >= 400 && status <= 599)
+            return status;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/esm/src/server/helpers/startPsychicServer.js

@@ -7,9 +7,17 @@ import PsychicLogos from '../../cli/helpers/PsychicLogos.js';
 import EnvInternal from '../../helpers/EnvInternal.js';
 import PsychicApp from '../../psychic-app/index.js';
 export default async function startPsychicServer({ app, port, sslCredentials, }) {
-    return await new Promise(accept => {
+    return await new Promise((accept, reject) => {
         const httpOrHttps = createPsychicHttpInstance(app, sslCredentials);
+        // typescript cannot call event-emitter methods on the http/https server
+        // union directly (incompatible overload sets), but both are EventEmitters
+        const emitter = httpOrHttps;
+        // without this listener, a failed bind (e.g. EADDRINUSE, EACCES) escapes
+        // as an uncaught 'error' event and this promise never settles
+        const onListenError = (error) => reject(error);
+        emitter.once('error', onListenError);
         const server = httpOrHttps.listen(port, () => {
+            emitter.off('error', onListenError);
             welcomeMessage({ port });
             accept(server);
         });

package/dist/esm/src/server/index.js

@@ -4,10 +4,12 @@ import etag from '@koa/etag';
 import { closeAllDbConnections } from '@rvoh/dream/db';
 import Koa from 'koa';
 import conditional from 'koa-conditional-get';
+import * as util from 'node:util';
 import logIfDevelopment from '../controller/helpers/logIfDevelopment.js';
 import EnvInternal from '../helpers/EnvInternal.js';
 import PsychicApp from '../psychic-app/index.js';
 import PsychicRouter from '../router/index.js';
+import errorBoundaryMiddleware, { ERROR_LOGGING_DEPTH } from './helpers/errorBoundaryMiddleware.js';
 import startPsychicServer, { createPsychicHttpInstance, } from './helpers/startPsychicServer.js';
 // const debugEnabled = debuglog('psychic').enabled
 export default class PsychicServer {
@@ -32,6 +34,21 @@ export default class PsychicServer {
         if (this.booted)
             return;
         const psychicApp = PsychicApp.getOrFail();
+        // outermost middleware: catches errors thrown from anything mounted
+        // after it (body parser, cors, custom `psy.use` middleware, after-routes
+        // mounts) and escalates genuine server errors to server:error hooks.
+        // Errors from controller actions are still processed by the router; the
+        // boundary only sees errors the router never caught.
+        this.koaApp.use(errorBoundaryMiddleware());
+        // residual error sink: the few errors Koa surfaces outside the error
+        // boundary (errors thrown after headers were sent, response-stream
+        // failures, errors the router deliberately re-throws to Koa in
+        // dev/test). Registering a listener supersedes Koa's default stderr
+        // logger, so these flow through the configured psychic logger instead
+        // of going dark.
+        this.koaApp.on('error', (err) => {
+            PsychicApp.logWithLevel('error', util.inspect(err, { depth: ERROR_LOGGING_DEPTH }));
+        });
         this.setSecureDefaultHeaders();
         this.koaApp.use(async (ctx, next) => {
             Object.keys(psychicApp.defaultResponseHeaders).forEach(key => {
@@ -57,7 +74,7 @@ export default class PsychicServer {
             throw new Error(`
         Failed to boot psychic config. the error thrown was:
           ${error.message}
-      `);
+      `, { cause: error });
         }
         for (const serverInitAfterMiddlewareHook of PsychicApp.getOrFail().specialHooks
             .serverInitAfterMiddleware) {
@@ -134,9 +151,39 @@ export default class PsychicServer {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     $attached = {};
+    /**
+     * @internal
+     *
+     * the maximum number of milliseconds graceful shutdown is allowed
+     * to run before the process exits anyway, so that a hung
+     * `server:shutdown` hook or db close can never keep a dying
+     * process alive
+     */
+    static SHUTDOWN_TIMEOUT_MS = 15000;
     async shutdownAndExit() {
-        await this.stop();
-        process.exit();
+        let exitCode = 0;
+        try {
+            await this.stopWithTimeout();
+        }
+        catch (error) {
+            PsychicApp.logWithLevel('error', '[psychic] error during graceful shutdown:', error);
+            exitCode = 1;
+        }
+        process.exit(exitCode);
+    }
+    /**
+     * @internal
+     *
+     * runs {@link PsychicServer.stop}, rejecting if it has not settled
+     * within SHUTDOWN_TIMEOUT_MS
+     */
+    async stopWithTimeout() {
+        await Promise.race([
+            this.stop(),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error(`[psychic] graceful shutdown timed out after ${PsychicServer.SHUTDOWN_TIMEOUT_MS}ms`)), PsychicServer.SHUTDOWN_TIMEOUT_MS).unref();
+            }),
+        ]);
     }
     async stop({ bypassClosingDbConnections = false, gracefulShutdownTimeoutMillis = 10_000, } = {}) {
         for (const hook of PsychicApp.getOrFail().specialHooks.serverShutdown) {

package/dist/types/src/bin/helpers/OpenApiSpecDiff.d.ts

@@ -72,8 +72,12 @@ export declare class OpenApiSpecDiff {
     private getHeadBranch;
     /**
      * Validates that oasdiff is installed and builds the oasdiff config
+     *
+     * Marked `protected` so tests can supply a deterministic config (e.g. a
+     * command guaranteed to fail) instead of probing the local oasdiff install
+     * and git remote. Production code never overrides this.
      */
-    private getOasDiffConfig;
+    protected getOasDiffConfig(): OasDiffConfig;
     /**
      * Runs oasdiff command and returns the output
      */
@@ -149,3 +153,26 @@ export declare class BreakingChangesDetectedInOpenApiSpecError extends Error {
     constructor(oasdiffConfig: OasDiffConfig);
     get message(): string;
 }
+/**
+ * Thrown when the diff tooling itself fails (oasdiff invocation error,
+ * unreadable head-branch spec, missing spec file), as opposed to oasdiff
+ * successfully running and detecting breaking changes
+ * ({@link BreakingChangesDetectedInOpenApiSpecError}). Under
+ * `psy diff:openapi --fail-on-breaking`, both exit nonzero, but with
+ * distinguishable messages: an inconclusive diff must never pass a CI gate
+ * as "no breaking changes".
+ */
+export declare class OpenApiSpecDiffToolFailureError extends Error {
+    private readonly erroredFiles;
+    constructor(erroredFiles: string[]);
+    get message(): string;
+}
+/**
+ * Internal marker for a failed oasdiff invocation, so
+ * {@link OpenApiSpecDiff.compareConfig} can distinguish "oasdiff itself
+ * failed" from "could not retrieve head-branch content" when recording
+ * a per-file error.
+ */
+export declare class OasDiffCommandFailedError extends Error {
+    constructor(subcommand: string, cause: unknown);
+}

package/dist/types/src/bin/index.d.ts

@@ -1,4 +1,4 @@
-export { BreakingChangesDetectedInOpenApiSpecError } from './helpers/OpenApiSpecDiff.js';
+export { BreakingChangesDetectedInOpenApiSpecError, OpenApiSpecDiffToolFailureError, } from './helpers/OpenApiSpecDiff.js';
 export default class PsychicBin {
     static generateController(controllerName: string, actions: string[]): Promise<void>;
     static generateResource(route: string, fullyQualifiedModelName: string, columnsWithTypes: string[], options: {

package/dist/types/src/psychic-app/index.d.ts

@@ -259,6 +259,24 @@ export default class PsychicApp {
     use(on: PsychicUseEventType, handler: Koa.Middleware): void;
     use(handler: Koa.Middleware): void;
     plugin(cb: (app: PsychicApp) => void | Promise<void>): void;
+    /**
+     * Registers a callback for one of psychic's lifecycle hooks.
+     *
+     * ### `server:error`
+     *
+     * Called any time the server encounters an error it isn't sure how to
+     * respond to (i.e. a 500). This covers errors thrown from controller
+     * actions as well as errors raised outside the router — e.g. in the body
+     * parser, cors callbacks, custom `psy.use` middleware, or after-routes
+     * mounts — which are captured by an error boundary mounted outermost in
+     * the middleware stack. Hooks are awaited and may shape the response via
+     * `ctx`; if they don't, psychic responds 500. Errors carrying a 4xx status
+     * (e.g. a body-parser 400) are rendered as that status and never reach
+     * `server:error` hooks.
+     *
+     * NOTE: once any `server:error` hook is registered, psychic considers the
+     * error handled and does not re-throw it to Koa.
+     */
     on<T extends PsychicHookEventType>(hookEventType: T, cb: T extends 'server:error' ? (err: Error, ctx: Koa.Context) => void | Promise<void> : T extends 'server:init:before-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-middleware' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:start' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:shutdown' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'server:init:after-routes' ? (psychicServer: PsychicServer) => void | Promise<void> : T extends 'cli:start' ? (program: Command) => void | Promise<void> : T extends 'cli:sync' ? () => any : (conf: PsychicApp) => void | Promise<void>): void;
     set(option: 'openapi', name: string, value: NamedPsychicOpenapiOptions): void;
     set<Opt extends PsychicAppOption>(option: Opt, value: Opt extends 'appName' ? string : Opt extends 'apiOnly' ? boolean : Opt extends 'defaultResponseHeaders' ? Record<string, string | null> : Opt extends 'httpServerOptions' ? http.ServerOptions | https.ServerOptions : Opt extends 'encryption' ? PsychicAppEncryptionOptions : Opt extends 'cors' ? cors.Options : Opt extends 'cookie' ? CustomCookieOptions : Opt extends 'apiRoot' ? string : Opt extends 'importExtension' ? GeneratorImportStyle : Opt extends 'sessionCookieName' ? string : Opt extends 'json' ? BodyParserOptions : Opt extends 'logger' ? PsychicLogger : Opt extends 'ssl' ? PsychicSslCredentials : Opt extends 'openapi' ? DefaultPsychicOpenapiOptions : Opt extends 'paths' ? PsychicPathOptions : Opt extends 'port' ? number : Opt extends 'saltRounds' ? number : Opt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : Opt extends 'inflections' ? () => void | Promise<void> : Opt extends 'routes' ? (r: PsychicRouter) => void | Promise<void> : Opt extends 'redirectAllowedHosts' ? readonly string[] : never): void;

package/dist/types/src/server/helpers/errorBoundaryMiddleware.d.ts

@@ -0,0 +1,30 @@
+import Koa from 'koa';
+export declare const ERROR_LOGGING_DEPTH = 6;
+/**
+ * @internal
+ *
+ * Set on `ctx.state` by the router when it processes an error thrown from a
+ * controller action (running `server:error` hooks when any are registered,
+ * or deliberately re-throwing to Koa when none are). The error boundary
+ * passes marked errors through untouched so a single request can never run
+ * `server:error` hooks twice, and so the router's deliberate dev/test
+ * re-throw behavior reaches Koa exactly as it did before the boundary
+ * existed.
+ */
+export declare const psychicRouterProcessedErrorStateKey = "_psychicRouterProcessedError";
+/**
+ * @internal
+ *
+ * The outermost middleware psychic mounts. Everything mounted after it —
+ * secure default headers, etag, cors, the body parser, `psy.use` middleware,
+ * after-routes mounts, and the router itself — runs inside `await next()`,
+ * so any error those layers throw (and the router doesn't catch) lands here
+ * instead of falling through to Koa's default handler.
+ *
+ * Errors carrying a 4xx status (e.g. a body-parser 400, or an `HttpError`
+ * thrown from custom middleware) already name their response: the boundary
+ * renders that status without involving `server:error` hooks. Anything else
+ * is a genuine server error: it is logged, given a default 500 response, and
+ * escalated to `server:error` hooks, which may reshape the response.
+ */
+export default function errorBoundaryMiddleware(): Koa.Middleware;

package/dist/types/src/server/index.d.ts

@@ -16,7 +16,23 @@ export default class PsychicServer {
     start(port?: number): Promise<boolean>;
     attach(id: string, obj: any): void;
     $attached: Record<string, any>;
+    /**
+     * @internal
+     *
+     * the maximum number of milliseconds graceful shutdown is allowed
+     * to run before the process exits anyway, so that a hung
+     * `server:shutdown` hook or db close can never keep a dying
+     * process alive
+     */
+    static readonly SHUTDOWN_TIMEOUT_MS = 15000;
     private shutdownAndExit;
+    /**
+     * @internal
+     *
+     * runs {@link PsychicServer.stop}, rejecting if it has not settled
+     * within SHUTDOWN_TIMEOUT_MS
+     */
+    private stopWithTimeout;
     stop({ bypassClosingDbConnections, gracefulShutdownTimeoutMillis, }?: {
         bypassClosingDbConnections?: boolean;
         gracefulShutdownTimeoutMillis?: number;

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic",
   "description": "Typescript web framework",
-  "version": "3.10.1",
+  "version": "3.11.0",
   "author": "RVOHealth",
   "publishConfig": {
     "access": "public"