@stacksjs/error-handling 0.70.73 → 0.70.75

package/dist/error-page-styles.d.ts

@@ -2,623 +2,4 @@
  * Laravel-style error page styles (v12.29+ local debug page).
  * Inline CSS — no external dependencies.
  */
-export declare const ERROR_PAGE_CSS: `
-  :root {
-    --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
-    --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
-    --neutral-50: #fafafa;
-    --neutral-100: #f5f5f5;
-    --neutral-200: #e5e5e5;
-    --neutral-300: #d4d4d4;
-    --neutral-400: #a3a3a3;
-    --neutral-500: #737373;
-    --neutral-600: #525252;
-    --neutral-700: #404040;
-    --neutral-800: #262626;
-    --neutral-900: #171717;
-    --neutral-950: #0a0a0a;
-    --rose-100: #ffe4e6;
-    --rose-200: #fecdd3;
-    --rose-500: #f43f5e;
-    --rose-600: #e11d48;
-    --rose-900: #881337;
-    --rose-950: #4c0519;
-    --blue-100: #dbeafe;
-    --blue-500: #3b82f6;
-    --blue-600: #2563eb;
-    --blue-700: #1d4ed8;
-    --blue-900: #1e3a8a;
-    --emerald-500: #10b981;
-    --amber-200: #fde68a;
-    --amber-600: #d97706;
-    --amber-900: #78350f;
-    --white: #fff;
-    --radius-md: 0.375rem;
-    --radius-lg: 0.5rem;
-    --radius-xl: 0.75rem;
-  }
-
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-
-  html {
-    -webkit-text-size-adjust: 100%;
-    color-scheme: light dark;
-  }
-
-  body {
-    font-family: var(--font-sans);
-    -webkit-font-smoothing: antialiased;
-    -moz-osx-font-smoothing: grayscale;
-    background: var(--neutral-50);
-    color: var(--neutral-950);
-    line-height: 1.5;
-    min-height: 100dvh;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    body {
-      background: var(--neutral-900);
-      color: var(--white);
-    }
-  }
-
-  .page {
-    max-width: 80rem;
-    margin: 0 auto;
-    padding: 3.5rem 1.5rem 2rem;
-  }
-
-  @media (min-width: 640px) {
-    .page { padding: 4rem 3.5rem 2rem; }
-  }
-
-  /* ── Header ── */
-  .header {
-    display: flex;
-    align-items: center;
-    justify-content: space-between;
-    gap: 1rem;
-    margin-bottom: 2rem;
-    flex-wrap: wrap;
-  }
-
-  .header-title {
-    display: flex;
-    align-items: center;
-    gap: 0.625rem;
-    font-size: 0.875rem;
-    font-weight: 500;
-    color: var(--neutral-600);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .header-title { color: var(--neutral-400); }
-  }
-
-  .header-dot {
-    width: 0.625rem;
-    height: 0.625rem;
-    border-radius: 9999px;
-    background: var(--rose-500);
-    flex-shrink: 0;
-  }
-
-  .btn-copy {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.375rem;
-    padding: 0.375rem 0.75rem;
-    font-size: 0.75rem;
-    font-weight: 500;
-    border: 1px solid var(--neutral-200);
-    border-radius: var(--radius-md);
-    background: var(--white);
-    color: var(--neutral-700);
-    cursor: pointer;
-    transition: background 0.15s, border-color 0.15s;
-  }
-
-  .btn-copy:hover { background: var(--neutral-100); }
-  .btn-copy.copied { border-color: var(--emerald-500); color: var(--emerald-500); }
-
-  @media (prefers-color-scheme: dark) {
-    .btn-copy {
-      background: var(--neutral-800);
-      border-color: rgba(255,255,255,0.1);
-      color: var(--neutral-200);
-    }
-    .btn-copy:hover { background: rgba(255,255,255,0.05); }
-  }
-
-  /* ── Error summary card ── */
-  .summary {
-    margin-bottom: 2rem;
-  }
-
-  .summary h1 {
-    font-size: 1.875rem;
-    font-weight: 600;
-    line-height: 1.2;
-    margin-bottom: 0.75rem;
-  }
-
-  .summary-file {
-    font-family: var(--font-mono);
-    font-size: 0.875rem;
-    color: var(--rose-600);
-    margin-bottom: 0.75rem;
-    word-break: break-all;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .summary-file { color: var(--rose-500); }
-  }
-
-  .summary-message {
-    font-size: 1.125rem;
-    color: var(--neutral-800);
-    margin-bottom: 1.25rem;
-    word-break: break-word;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .summary-message { color: var(--neutral-200); }
-  }
-
-  .badges {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.5rem;
-    margin-bottom: 1.25rem;
-  }
-
-  .badge {
-    display: inline-flex;
-    align-items: center;
-    padding: 0.25rem 0.5rem;
-    font-size: 0.6875rem;
-    font-weight: 600;
-    letter-spacing: 0.04em;
-    text-transform: uppercase;
-    border-radius: var(--radius-md);
-    border: 1px solid var(--neutral-200);
-    background: var(--neutral-100);
-    color: var(--neutral-600);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .badge {
-      border-color: rgba(255,255,255,0.1);
-      background: rgba(255,255,255,0.05);
-      color: var(--neutral-400);
-    }
-  }
-
-  .badge-status {
-    background: var(--rose-100);
-    border-color: var(--rose-200);
-    color: var(--rose-900);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .badge-status {
-      background: var(--rose-950);
-      border-color: var(--rose-900);
-      color: var(--rose-100);
-    }
-  }
-
-  .request-row {
-    display: flex;
-    align-items: center;
-    gap: 0.75rem;
-    flex-wrap: wrap;
-    font-size: 0.875rem;
-  }
-
-  .badge-method {
-    background: var(--blue-100);
-    border-color: transparent;
-    color: var(--blue-900);
-    font-family: var(--font-mono);
-    font-size: 0.6875rem;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .badge-method {
-      background: var(--blue-700);
-      color: var(--white);
-    }
-  }
-
-  .request-url {
-    font-family: var(--font-mono);
-    font-size: 0.8125rem;
-    color: var(--neutral-500);
-    word-break: break-all;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .request-url { color: var(--neutral-400); }
-  }
-
-  /* ── Hints ── */
-  .hints {
-    border: 1px solid var(--amber-200);
-    border-radius: var(--radius-lg);
-    background: #fffbeb;
-    margin-bottom: 2rem;
-    overflow: hidden;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .hints {
-      border-color: var(--amber-600);
-      background: rgba(120, 53, 15, 0.3);
-    }
-  }
-
-  .hints-header {
-    padding: 0.75rem 1rem;
-    font-size: 0.8125rem;
-    font-weight: 600;
-    color: var(--amber-900);
-    border-bottom: 1px solid var(--amber-200);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .hints-header { color: var(--amber-200); border-bottom-color: rgba(217,119,6,0.3); }
-  }
-
-  .hints-body {
-    padding: 1rem;
-    font-size: 0.875rem;
-    color: var(--neutral-700);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .hints-body { color: var(--neutral-300); }
-  }
-
-  .hints-body ul { margin: 0 0 0.75rem 1.25rem; }
-  .hints-body li { margin: 0.2rem 0; }
-  .hints-suggestion { font-weight: 500; margin-bottom: 0.5rem; }
-  .hints-doc { color: var(--blue-600); text-decoration: none; font-size: 0.8125rem; }
-  .hints-doc:hover { text-decoration: underline; }
-
-  /* ── Exception trace ── */
-  .trace {
-    margin-bottom: 2rem;
-  }
-
-  .trace-title {
-    font-size: 0.875rem;
-    font-weight: 600;
-    color: var(--neutral-500);
-    text-transform: uppercase;
-    letter-spacing: 0.05em;
-    margin-bottom: 1rem;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-title { color: var(--neutral-400); }
-  }
-
-  .trace-frame {
-    border: 1px solid var(--neutral-200);
-    border-radius: var(--radius-lg);
-    margin-bottom: 0.5rem;
-    overflow: hidden;
-    background: var(--white);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-frame {
-      border-color: rgba(255,255,255,0.1);
-      background: rgba(255,255,255,0.02);
-    }
-  }
-
-  .trace-frame-header {
-    display: flex;
-    align-items: baseline;
-    gap: 0.5rem;
-    padding: 0.75rem 1rem;
-    cursor: pointer;
-    font-size: 0.8125rem;
-    transition: background 0.15s;
-  }
-
-  .trace-frame-header:hover { background: var(--neutral-50); }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-frame-header:hover { background: rgba(255,255,255,0.03); }
-  }
-
-  .trace-frame-fn {
-    font-family: var(--font-mono);
-    color: var(--neutral-800);
-    flex: 1;
-    min-width: 0;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-frame-fn { color: var(--neutral-200); }
-  }
-
-  .trace-frame-file {
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    color: var(--neutral-400);
-    flex-shrink: 0;
-  }
-
-  .trace-frame-body {
-    display: none;
-    border-top: 1px solid var(--neutral-200);
-  }
-
-  .trace-frame.expanded .trace-frame-body { display: block; }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-frame-body { border-top-color: rgba(255,255,255,0.08); }
-  }
-
-  .trace-vendor {
-    border: 1px dashed var(--neutral-300);
-    border-radius: var(--radius-lg);
-    margin-bottom: 0.5rem;
-    overflow: hidden;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-vendor { border-color: rgba(255,255,255,0.15); }
-  }
-
-  .trace-vendor-toggle {
-    display: flex;
-    align-items: center;
-    gap: 0.5rem;
-    padding: 0.75rem 1rem;
-    font-size: 0.8125rem;
-    font-weight: 500;
-    color: var(--neutral-500);
-    cursor: pointer;
-    background: var(--neutral-50);
-    transition: background 0.15s;
-  }
-
-  .trace-vendor-toggle:hover { background: var(--neutral-100); }
-
-  @media (prefers-color-scheme: dark) {
-    .trace-vendor-toggle {
-      background: rgba(255,255,255,0.03);
-      color: var(--neutral-400);
-    }
-    .trace-vendor-toggle:hover { background: rgba(255,255,255,0.05); }
-  }
-
-  .trace-vendor-frames { display: none; padding: 0.25rem 0; }
-  .trace-vendor.expanded .trace-vendor-frames { display: block; }
-
-  /* ── Code snippet ── */
-  .code-block {
-    overflow-x: auto;
-    font-family: var(--font-mono);
-    font-size: 0.8125rem;
-    line-height: 1.6;
-    background: var(--neutral-950);
-    color: #abb2bf;
-  }
-
-  .code-line {
-    display: flex;
-    min-height: 1.5rem;
-  }
-
-  .code-line:nth-child(odd) { background: rgba(255,255,255,0.02); }
-  .code-line:nth-child(even) { background: rgba(255,255,255,0.04); }
-
-  .code-line.highlight {
-    background: rgba(244, 63, 94, 0.25) !important;
-  }
-
-  .code-ln {
-    width: 3.5rem;
-    text-align: right;
-    padding: 0 1rem 0 0.5rem;
-    color: var(--neutral-500);
-    user-select: none;
-    flex-shrink: 0;
-  }
-
-  .code-line.highlight .code-ln { color: var(--rose-500); }
-
-  .code-txt {
-    flex: 1;
-    padding-right: 1rem;
-    white-space: pre;
-  }
-
-  /* ── Context panels ── */
-  .context {
-    margin-bottom: 2rem;
-  }
-
-  .context-tabs {
-    display: flex;
-    gap: 0;
-    border-bottom: 2px solid var(--neutral-200);
-    overflow-x: auto;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .context-tabs { border-bottom-color: rgba(255,255,255,0.1); }
-  }
-
-  .context-tab {
-    padding: 0.625rem 1rem;
-    font-size: 0.8125rem;
-    font-weight: 500;
-    color: var(--neutral-500);
-    background: none;
-    border: none;
-    border-bottom: 2px solid transparent;
-    margin-bottom: -2px;
-    cursor: pointer;
-    white-space: nowrap;
-    transition: color 0.15s;
-  }
-
-  .context-tab:hover { color: var(--neutral-800); }
-  .context-tab.active {
-    color: var(--rose-600);
-    border-bottom-color: var(--rose-500);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .context-tab:hover { color: var(--neutral-200); }
-    .context-tab.active { color: var(--rose-500); }
-  }
-
-  .context-panel {
-    display: none;
-    padding: 1.25rem 0;
-  }
-
-  .context-panel.active { display: block; }
-
-  .kv-table {
-    width: 100%;
-    border-collapse: collapse;
-    font-size: 0.8125rem;
-  }
-
-  .kv-table tr {
-    border-bottom: 1px solid var(--neutral-100);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .kv-table tr { border-bottom-color: rgba(255,255,255,0.05); }
-  }
-
-  .kv-table td {
-    padding: 0.5rem 0.75rem;
-    vertical-align: top;
-  }
-
-  .kv-table td:first-child {
-    font-weight: 500;
-    color: var(--neutral-500);
-    width: 30%;
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    word-break: break-all;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .kv-table td:first-child { color: var(--neutral-400); }
-  }
-
-  .kv-table td:last-child {
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    word-break: break-all;
-    color: var(--neutral-800);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .kv-table td:last-child { color: var(--neutral-200); }
-  }
-
-  .query-item {
-    padding: 0.75rem 1rem;
-    margin-bottom: 0.5rem;
-    border: 1px solid var(--neutral-200);
-    border-radius: var(--radius-md);
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    background: var(--neutral-50);
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .query-item {
-      border-color: rgba(255,255,255,0.08);
-      background: rgba(255,255,255,0.03);
-    }
-  }
-
-  .query-time {
-    margin-top: 0.375rem;
-    font-size: 0.6875rem;
-    color: var(--neutral-400);
-  }
-
-  .json-block {
-    font-family: var(--font-mono);
-    font-size: 0.75rem;
-    background: var(--neutral-100);
-    border-radius: var(--radius-md);
-    padding: 1rem;
-    overflow-x: auto;
-    white-space: pre-wrap;
-    word-break: break-all;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .json-block {
-      background: rgba(255,255,255,0.05);
-      color: var(--neutral-200);
-    }
-  }
-
-  /* ── Production page ── */
-  .production-page {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    min-height: 100dvh;
-    text-align: center;
-    padding: 2rem;
-  }
-
-  .production-status {
-    font-size: 6rem;
-    font-weight: 700;
-    color: var(--neutral-200);
-    margin-bottom: 1rem;
-    line-height: 1;
-  }
-
-  @media (prefers-color-scheme: dark) {
-    .production-status { color: var(--neutral-700); }
-  }
-
-  .production-title {
-    font-size: 1.5rem;
-    font-weight: 600;
-    margin-bottom: 0.5rem;
-  }
-
-  .production-message {
-    color: var(--neutral-500);
-    margin-bottom: 2rem;
-    max-width: 28rem;
-  }
-
-  .production-link {
-    color: var(--blue-600);
-    text-decoration: none;
-    font-size: 0.875rem;
-  }
-
-  .production-link:hover { text-decoration: underline; }
-
-  @media (prefers-color-scheme: dark) {
-    .production-link { color: var(--blue-500); }
-  }
-`;
+export declare const ERROR_PAGE_CSS: string;

package/dist/error-page-template.d.ts

@@ -30,39 +30,7 @@ export declare function buildErrorMarkdown(opts: {
   frames: ParsedFrame[]
 }): string;
 export declare function wrapErrorPage(body: string, markdown: string): string;
-export declare const ERROR_PAGE_SCRIPT: `
-function initErrorPage() {
-  const copyBtn = document.getElementById('copy-markdown');
-  const markdown = document.getElementById('error-markdown');
-  if (copyBtn && markdown) {
-    copyBtn.addEventListener('click', async () => {
-      try {
-        await navigator.clipboard.writeText(markdown.textContent || '');
-        copyBtn.textContent = 'Copied!';
-        copyBtn.classList.add('copied');
-        setTimeout(() => {
-          copyBtn.textContent = 'Copy as Markdown';
-          copyBtn.classList.remove('copied');
-        }, 2000);
-      } catch {
-        copyBtn.textContent = 'Copy failed';
-      }
-    });
-  }
-
-  document.querySelectorAll('.context-tab').forEach(tab => {
-    tab.addEventListener('click', () => {
-      const id = tab.getAttribute('data-tab');
-      document.querySelectorAll('.context-tab').forEach(t => t.classList.remove('active'));
-      document.querySelectorAll('.context-panel').forEach(p => p.classList.remove('active'));
-      tab.classList.add('active');
-      const panel = document.querySelector('[data-panel="' + id + '"]');
-      if (panel) panel.classList.add('active');
-    });
-  });
-}
-document.addEventListener('DOMContentLoaded', initErrorPage);
-`;
+export declare const ERROR_PAGE_SCRIPT: string;
 export declare interface ParsedFrame {
   file: string
   line: number

package/dist/error-page.d.ts

@@ -30,123 +30,115 @@ export declare function renderError(error: Error, status?: number): Promise<stri
  * Create an error response
  */
 export declare function errorResponse(error: Error, status?: number, config?: ErrorPageConfig): Promise<Response>;
-// HTTP error definitions. Each entry includes a doc link, likely causes,
+/**
+ * HTTP error definitions. Each entry includes a doc link, likely causes,
 // and a concrete suggestion so the dev-mode error page reads like a hint
 // instead of just "something went wrong".
-export declare const HTTP_ERRORS: {
-  400: {
-  status: 400;
-  title: 'Bad Request';
-  message: 'The request was malformed or invalid.';
-  docLink: `${DOCS_BASE}/400`;
-  commonCauses: readonly ['JSON body is missing or has a syntax error', 'A required field is absent from the payload', 'Content-Type header does not match the body format'];
-  suggestion: 'Inspect the request body and Content-Type — most 400s come from malformed JSON or a missing required field.'
-};
-  401: {
-  status: 401;
-  title: 'Unauthorized';
-  message: 'Authentication is required to access this resource.';
-  docLink: `${DOCS_BASE}/401`;
-  commonCauses: readonly ['No Authorization header was sent', 'The bearer token expired', 'The session cookie was cleared'];
-  suggestion: 'Confirm a valid `Authorization: Bearer <token>` header is sent and the token has not expired.'
-};
-  403: {
-  status: 403;
-  title: 'Forbidden';
-  message: 'You do not have permission to access this resource.';
-  docLink: `${DOCS_BASE}/403`;
-  commonCauses: readonly ['The authenticated user lacks the required ability or role', 'A Gate or policy denied access (see app/Gates.ts)', 'The token was issued without the needed ability'];
-  suggestion: 'Check Gates / policies and the abilities encoded in the access token.'
-};
-  404: {
-  status: 404;
-  title: 'Not Found';
-  message: 'The requested resource could not be found.';
-  docLink: `${DOCS_BASE}/404`;
-  commonCauses: readonly ['The route is not registered in app/Routes.ts', 'A typo in the URL path', 'A model lookup returned no row (ModelNotFoundError)'];
-  suggestion: 'Run `buddy route:list` to see registered routes, or verify the model exists with the given id.'
-};
-  405: {
-  status: 405;
-  title: 'Method Not Allowed';
-  message: 'The request method is not supported for this resource.';
-  docLink: `${DOCS_BASE}/405`;
-  commonCauses: readonly ['The route is registered for a different HTTP method', 'A form posted GET when the route expects POST'];
-  suggestion: 'Confirm the HTTP method in `app/Routes.ts` matches what the client sent.'
-};
-  408: {
-  status: 408;
-  title: 'Request Timeout';
-  message: 'The request took too long to complete.';
-  docLink: `${DOCS_BASE}/408`;
-  commonCauses: readonly ['A long-running query or external API call exceeded the timeout', 'The client uploaded a slow body that stalled'];
-  suggestion: 'Move slow work into a queued job, or raise the route timeout if the work is genuinely long.'
-};
-  409: {
-  status: 409;
-  title: 'Conflict';
-  message: 'The request conflicts with the current state of the resource.';
-  docLink: `${DOCS_BASE}/409`;
-  commonCauses: readonly ['A unique-constraint violation (duplicate email, slug, etc.)', 'Optimistic locking detected a stale write'];
-  suggestion: 'Re-fetch the resource and retry, or surface the conflict to the user.'
-};
-  410: {
-  status: 410;
-  title: 'Gone';
-  message: 'The requested resource is no longer available.';
-  docLink: `${DOCS_BASE}/410`;
-  commonCauses: readonly ['The resource was permanently deleted', 'A signed URL expired'];
-  suggestion: 'Issue a fresh signed URL or fall back to the canonical resource.'
-};
-  422: {
-  status: 422;
-  title: 'Unprocessable Entity';
-  message: 'The request was well-formed but could not be processed.';
-  docLink: `${DOCS_BASE}/422`;
-  commonCauses: readonly ['Validation rules from the action / model rejected the payload', 'A field value is outside the allowed range or shape'];
-  suggestion: 'Inspect `errors` in the response body — each key maps to a failing field.'
-};
-  429: {
-  status: 429;
-  title: 'Too Many Requests';
-  message: 'You have exceeded the rate limit.';
-  docLink: `${DOCS_BASE}/429`;
-  commonCauses: readonly ['Rate-limit middleware tripped on this IP / token', 'A retry loop is hammering the endpoint'];
-  suggestion: 'Honor the `Retry-After` response header and back off before retrying.'
-};
-  500: {
-  status: 500;
-  title: 'Internal Server Error';
-  message: 'An unexpected error occurred on the server.';
-  docLink: `${DOCS_BASE}/500`;
-  commonCauses: readonly ['An unhandled exception in an action or middleware', 'A failing database connection or migration', 'A misconfigured environment variable'];
-  suggestion: 'Check server logs for the original stack trace — the error page above shows the throw site in dev.'
-};
-  502: {
-  status: 502;
-  title: 'Bad Gateway';
-  message: 'The server received an invalid response from an upstream server.';
-  docLink: `${DOCS_BASE}/502`;
-  commonCauses: readonly ['An upstream HTTP API returned a malformed response', 'A reverse proxy could not reach the origin'];
-  suggestion: 'Verify the upstream service is healthy and returning the expected content type.'
-};
-  503: {
-  status: 503;
-  title: 'Service Unavailable';
-  message: 'The service is temporarily unavailable.';
-  docLink: `${DOCS_BASE}/503`;
-  commonCauses: readonly ['Maintenance mode is enabled', 'A health check is failing', 'A dependency (db, redis, queue) is down'];
-  suggestion: 'Run `buddy doctor` and check dependent services.'
-};
-  504: {
-  status: 504;
-  title: 'Gateway Timeout';
-  message: 'The upstream server did not respond in time.';
-  docLink: `${DOCS_BASE}/504`;
-  commonCauses: readonly ['An upstream HTTP call exceeded its deadline', 'A long-running database query timed out'];
-  suggestion: 'Move the work to a queued job or raise the upstream timeout if the latency is expected.'
-}
-};
+ * @defaultValue
+ * ```ts
+ * {
+ *   400: {
+ *     status: 400,
+ *     title: 'Bad Request',
+ *     message: 'The request was malformed or invalid.',
+ *     commonCauses: [ 'JSON body is missing or has a syntax error', 'A required field is absent from the payload', 'Content-Type header does not match the body format', ],
+ *     suggestion: 'Inspect the request body and Content-Type — most 400s come from malformed JSON or a missing required field.'
+ *   },
+ *   401: {
+ *     status: 401,
+ *     title: 'Unauthorized',
+ *     message: 'Authentication is required to access this resource.',
+ *     commonCauses: [ 'No Authorization header was sent', 'The bearer token expired', 'The session cookie was cleared', ],
+ *     suggestion: 'Confirm a valid `Authorization: Bearer <token>` header is sent and the token has not expired.'
+ *   },
+ *   403: {
+ *     status: 403,
+ *     title: 'Forbidden',
+ *     message: 'You do not have permission to access this resource.',
+ *     commonCauses: [ 'The authenticated user lacks the required ability or role', 'A Gate or policy denied access (see app/Gates.ts)', 'The token was issued without the needed ability', ],
+ *     suggestion: 'Check Gates / policies and the abilities encoded in the access token.'
+ *   },
+ *   404: {
+ *     status: 404,
+ *     title: 'Not Found',
+ *     message: 'The requested resource could not be found.',
+ *     commonCauses: [ 'The route is not registered in app/Routes.ts', 'A typo in the URL path', 'A model lookup returned no row (ModelNotFoundError)', ],
+ *     suggestion: 'Run `buddy route:list` to see registered routes, or verify the model exists with the given id.'
+ *   },
+ *   405: {
+ *     status: 405,
+ *     title: 'Method Not Allowed',
+ *     message: 'The request method is not supported for this resource.',
+ *     commonCauses: [ 'The route is registered for a different HTTP method', 'A form posted GET when the route expects POST', ],
+ *     suggestion: 'Confirm the HTTP method in `app/Routes.ts` matches what the client sent.'
+ *   },
+ *   408: {
+ *     status: 408,
+ *     title: 'Request Timeout',
+ *     message: 'The request took too long to complete.',
+ *     commonCauses: [ 'A long-running query or external API call exceeded the timeout', 'The client uploaded a slow body that stalled', ],
+ *     suggestion: 'Move slow work into a queued job, or raise the route timeout if the work is genuinely long.'
+ *   },
+ *   409: {
+ *     status: 409,
+ *     title: 'Conflict',
+ *     message: 'The request conflicts with the current state of the resource.',
+ *     commonCauses: [ 'A unique-constraint violation (duplicate email, slug, etc.)', 'Optimistic locking detected a stale write', ],
+ *     suggestion: 'Re-fetch the resource and retry, or surface the conflict to the user.'
+ *   },
+ *   410: {
+ *     status: 410,
+ *     title: 'Gone',
+ *     message: 'The requested resource is no longer available.',
+ *     commonCauses: ['The resource was permanently deleted', 'A signed URL expired'],
+ *     suggestion: 'Issue a fresh signed URL or fall back to the canonical resource.'
+ *   },
+ *   422: {
+ *     status: 422,
+ *     title: 'Unprocessable Entity',
+ *     message: 'The request was well-formed but could not be processed.',
+ *     commonCauses: [ 'Validation rules from the action / model rejected the payload', 'A field value is outside the allowed range or shape', ],
+ *     suggestion: 'Inspect `errors` in the response body — each key maps to a failing field.'
+ *   },
+ *   429: {
+ *     status: 429,
+ *     title: 'Too Many Requests',
+ *     message: 'You have exceeded the rate limit.',
+ *     commonCauses: ['Rate-limit middleware tripped on this IP / token', 'A retry loop is hammering the endpoint'],
+ *     suggestion: 'Honor the `Retry-After` response header and back off before retrying.'
+ *   },
+ *   500: {
+ *     status: 500,
+ *     title: 'Internal Server Error',
+ *     message: 'An unexpected error occurred on the server.',
+ *     commonCauses: [ 'An unhandled exception in an action or middleware', 'A failing database connection or migration', 'A misconfigured environment variable', ],
+ *     suggestion: 'Check server logs for the original stack trace — the error page above shows the throw site in dev.'
+ *   },
+ *   502: {
+ *     status: 502,
+ *     title: 'Bad Gateway',
+ *     message: 'The server received an invalid response from an upstream server.',
+ *     commonCauses: ['An upstream HTTP API returned a malformed response', 'A reverse proxy could not reach the origin'],
+ *     suggestion: 'Verify the upstream service is healthy and returning the expected content type.'
+ *   },
+ *   503: {
+ *     status: 503,
+ *     title: 'Service Unavailable',
+ *     message: 'The service is temporarily unavailable.',
+ *     commonCauses: ['Maintenance mode is enabled', 'A health check is failing', 'A dependency (db, redis, queue) is down'],
+ *     suggestion: 'Run `buddy doctor` and check dependent services.'
+ *   },
+ *   504: {
+ *     status: 504,
+ *     title: 'Gateway Timeout',
+ *     message: 'The upstream server did not respond in time.',
+ *     commonCauses: ['An upstream HTTP call exceeded its deadline', 'A long-running database query timed out'],
+ *     suggestion: 'Move the work to a queued job or raise the upstream timeout if the latency is expected.'
+ *   }
+ * }
+ * ```
+ */
+export declare const HTTP_ERRORS: Record<HttpStatusCode, HttpError>;
 /**
  * Error Page Rendering - Ignition-style error pages
  *

package/dist/handler.d.ts

@@ -3,7 +3,7 @@ import type { LogErrorOptions } from '@stacksjs/logging';
 // Function to update the default log path when config is available
 export declare function setLogPath(path: string): void;
 export declare function writeToLogFile(message: string, options?: WriteOptions): Promise<void>;
-export declare function handleError(err: string | Error | object | unknown, options?: LogErrorOptions | Record<string, any>): Error;
+export declare function handleError(err: string | Error | object | unknown, options?: unknown): Error;
 /**
  * Context information attached to errors for better debugging.
  */

package/dist/handler.js

@@ -84,14 +84,14 @@ export async function writeToLogFile(message, options) {
   await fs.promises.appendFile(logFile, formattedMessage);
 }
 export function handleError(err, options) {
-  let errorMessage, contextData;
-  if (options && typeof options === "object" && !("shouldExit" in options) && !("silent" in options) && !("message" in options)) {
-    contextData = options;
-    options = void 0;
-  }
+  let errorMessage, contextData, errorOptions;
+  if (options && typeof options === "object" && (("shouldExit" in options) || ("silent" in options)))
+    errorOptions = options;
+  else if (options !== void 0)
+    contextData = options && typeof options === "object" ? options : { error: options };
   const errMsg = err instanceof Error ? err.message : typeof err === "string" ? err : JSON.stringify(err);
-  if (options && "message" in options)
-    errorMessage = `${errMsg}: ${options.message}`;
+  if (errorOptions?.message)
+    errorMessage = `${errMsg}: ${errorOptions.message}`;
   else
     errorMessage = errMsg;
   let logMessage = `ERROR: ${stripAnsi(errorMessage)}`;
@@ -104,5 +104,5 @@ Context: ${JSON.stringify(contextData, null, 2)}`;
   const error = Error(errorMessage);
   if (err instanceof Error)
     Object.assign(error, err);
-  return ErrorHandler.handle(error, { ...options, message: errorMessage });
+  return ErrorHandler.handle(error, errorOptions);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/error-handling",
   "type": "module",
-  "version": "0.70.73",
+  "version": "0.70.75",
   "description": "Type safe error handling.",
   "author": "Chris Breuer",
   "contributors": [
@@ -57,12 +57,12 @@
     "ts-syntax-highlighter": "^0.2.1"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.73",
-    "@stacksjs/config": "0.70.73",
-    "better-dx": "^0.2.12",
-    "@stacksjs/path": "0.70.73",
-    "@stacksjs/types": "0.70.73",
-    "@stacksjs/validation": "0.70.73"
+    "@stacksjs/cli": "0.70.75",
+    "@stacksjs/config": "0.70.75",
+    "better-dx": "^0.2.16",
+    "@stacksjs/path": "0.70.75",
+    "@stacksjs/types": "0.70.75",
+    "@stacksjs/validation": "0.70.75"
   },
   "sideEffects": false
 }