@starpak/error 0.0.0-stage → 0.1.4

package/src/native.ts

@@ -0,0 +1,108 @@
+/**
+ * Spak Error - native error mapping
+ *
+ * Turns `errno` codes and well-known crash messages into Spak errors while
+ * keeping the original error as `cause`.
+ */
+
+import { CODES } from './codes'
+import { SpakError, isSpakError } from './error'
+
+/** POSIX/Node errno → Spak code. */
+export const ERRNO_MAP: Record<string, string> = {
+  ENOENT: CODES.FS_NOT_FOUND,
+  ENOTDIR: CODES.FS_NOT_FOUND,
+  EACCES: CODES.FS_DENIED_BY_OS,
+  EPERM: CODES.FS_OPERATION_NOT_PERMITTED,
+  ENOSPC: CODES.FS_NO_SPACE,
+  EMFILE: CODES.FS_TOO_MANY_OPEN_FILES,
+  ENFILE: CODES.FS_TOO_MANY_OPEN_FILES,
+  EISDIR: CODES.FS_IS_DIRECTORY,
+  EROFS: CODES.FS_DENIED_BY_OS,
+  EBADF: CODES.HANDLE_REVOKED,
+
+  EADDRINUSE: CODES.PORT_IN_USE,
+  EADDRNOTAVAIL: CODES.LISTEN_FAILED,
+  EACCES_LISTEN: CODES.LISTEN_FAILED,
+
+  ECONNREFUSED: CODES.NET_CONNECTION_REFUSED,
+  ECONNRESET: CODES.NET_CONNECTION_RESET,
+  ECONNABORTED: CODES.NET_CONNECTION_RESET,
+  EPIPE: CODES.NET_CONNECTION_RESET,
+  ETIMEDOUT: CODES.NET_TIMEOUT,
+  ESOCKETTIMEDOUT: CODES.NET_TIMEOUT,
+  ENOTFOUND: CODES.NET_DNS,
+  EAI_AGAIN: CODES.NET_DNS,
+
+  ERR_TLS_CERT_ALTNAME_INVALID: CODES.NET_TLS,
+  ERR_SSL_WRONG_VERSION_NUMBER: CODES.NET_TLS,
+  DEPTH_ZERO_SELF_SIGNED_CERT: CODES.NET_TLS,
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: CODES.NET_TLS,
+  SELF_SIGNED_CERT_IN_CHAIN: CODES.NET_TLS,
+
+  MODULE_NOT_FOUND: CODES.MODULE_NOT_FOUND,
+  ERR_MODULE_NOT_FOUND: CODES.MODULE_NOT_FOUND,
+  ERR_REQUIRE_ESM: CODES.MODULE_NOT_FOUND,
+  ERR_PACKAGE_PATH_NOT_EXPORTED: CODES.MODULE_NOT_FOUND,
+  ERR_INVALID_ARG_TYPE: CODES.BUILD_FAILED,
+}
+
+/** Message patterns for failures that have no errno (crashes, engine errors). */
+const MESSAGE_MAP: Array<{ pattern: RegExp, code: string }> = [
+  { pattern: /JavaScript heap out of memory/i, code: CODES.OUT_OF_MEMORY },
+  { pattern: /Maximum call stack size exceeded/i, code: CODES.STACK_OVERFLOW },
+  { pattern: /Segmentation fault|core dumped|double free|invalid pointer|bus error/i, code: CODES.NATIVE_CRASH },
+  { pattern: /Unexpected token .* in JSON|is not valid JSON|JSON at position/i, code: CODES.PAK_MANIFEST_INVALID },
+  { pattern: /\.l2s\.|FUSE|rename .*ENOENT/i, code: CODES.FS_RENAME_UNSUPPORTED },
+  { pattern: /socket hang up/i, code: CODES.NET_CONNECTION_RESET },
+  { pattern: /self-signed certificate|certificate has expired|unable to verify/i, code: CODES.NET_TLS },
+  { pattern: /basic auth|proxy authentication/i, code: CODES.NET_PROXY_AUTH },
+  { pattern: /Cannot find module/i, code: CODES.MODULE_NOT_FOUND },
+  { pattern: /EACCES.*listen|permission denied.*:?\d{2,5}/i, code: CODES.LISTEN_FAILED },
+]
+
+export interface NativeOptions {
+  where?: string
+  context?: Record<string, unknown>
+}
+
+/**
+ * Normalise any thrown value into a `SpakError`.
+ * Unknown shapes still produce an error (SPAK-9999) with the original cause.
+ */
+export function fromNative(error: unknown, options: NativeOptions = {}): SpakError {
+  if (isSpakError(error)) return error
+
+  const cause = error instanceof Error ? error : new Error(String(error))
+  const errno = typeof (error as { code?: unknown })?.code === 'string'
+    ? String((error as { code?: string }).code)
+    : undefined
+  const message = cause.message ?? ''
+  const context: Record<string, unknown> = { ...options.context }
+  if (errno) context.errno = errno
+
+  if (errno) {
+    const direct = ERRNO_MAP[errno]
+    if (direct) {
+      // Listen failures share EACCES with file access; the syscall tells them apart.
+      const syscall = String((error as { syscall?: unknown })?.syscall ?? '')
+      if (errno === 'EACCES' && syscall === 'listen') {
+        return new SpakError(CODES.LISTEN_FAILED, { cause, message, where: options.where, context })
+      }
+      if (errno === 'ENOENT' && /\.l2s\.|tmp_obj_|\.git\/objects/.test(message)) {
+        return new SpakError(CODES.FS_RENAME_UNSUPPORTED, { cause, message, where: options.where, context })
+      }
+      return new SpakError(direct, { cause, message, where: options.where, context })
+    }
+  }
+
+  for (const entry of MESSAGE_MAP) {
+    if (entry.pattern.test(message)) {
+      return new SpakError(entry.code, { cause, message, where: options.where, context })
+    }
+  }
+
+  return new SpakError(CODES.UNKNOWN, { cause, message, where: options.where, context })
+}
+
+export { ERRNO_MAP as ERRNO_TO_SPAK }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.