@nebutra/errors 0.1.1 → 2.0.0

package/README.md

@@ -74,7 +74,7 @@ try {
 } catch (error) {
   if (isAppError(error)) {
     // Known error with code and status
-    console.log(error.code, error.statusCode);
+    return handleKnownError(error.code, error.statusCode);
   } else {
     // Unknown error
     throw new InternalError("Unexpected error");
@@ -99,5 +99,5 @@ try {
 
 ## Related
 
-- [API Gateway](../../backends/gateway/)
-- [Observability](../../infra/ops/observability/)
+- [API Gateway](../../../backends/gateway/)
+- [Observability](../../../infra/ops/observability/)

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Errors - Unified error handling for Nebutra services
+ *
+ * Provides:
+ * - Typed error classes
+ * - Consistent API error responses
+ * - Error serialization for logging
+ */
+export declare const ERROR_CODES: {
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    readonly DATABASE_ERROR: "DATABASE_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly SUBSCRIPTION_EXPIRED: "SUBSCRIPTION_EXPIRED";
+    readonly FEATURE_DISABLED: "FEATURE_DISABLED";
+    readonly TENANT_SUSPENDED: "TENANT_SUSPENDED";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export interface AppErrorOptions {
+    code: ErrorCode;
+    message: string;
+    statusCode?: number;
+    cause?: Error;
+    metadata?: Record<string, unknown>;
+    suggestion?: string;
+    isOperational?: boolean;
+}
+export declare class AppError extends Error {
+    readonly code: ErrorCode;
+    readonly statusCode: number;
+    readonly isOperational: boolean;
+    readonly metadata?: Record<string, unknown>;
+    readonly suggestion?: string;
+    readonly timestamp: string;
+    constructor(options: AppErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+export interface CapabilityErrorOptions {
+    statusCode?: number;
+    cause?: Error;
+    metadata?: Record<string, unknown>;
+    suggestion: string;
+    code?: ErrorCode;
+}
+export declare class CapabilityError extends AppError {
+    readonly capability: string;
+    constructor(capability: string, message: string, options: CapabilityErrorOptions);
+}
+export declare class ValidationError extends AppError {
+    readonly fields?: Record<string, string[]>;
+    constructor(message: string, fields?: Record<string, string[]>);
+}
+export declare class UnauthorizedError extends AppError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends AppError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends AppError {
+    constructor(resource?: string, id?: string);
+}
+export declare class ConflictError extends AppError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends AppError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number);
+}
+export declare class QuotaExceededError extends AppError {
+    constructor(quota: string, limit: number, current: number);
+}
+export declare class ExternalServiceError extends AppError {
+    constructor(service: string, cause?: Error);
+}
+export declare class DatabaseError extends AppError {
+    constructor(operation: string, cause?: Error);
+}
+export interface ApiErrorResponse {
+    error: {
+        code: ErrorCode;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+    requestId?: string;
+}
+export declare function toApiError(error: unknown, requestId?: string): ApiErrorResponse;
+export declare function getStatusCode(error: unknown): number;
+interface HonoContext {
+    req: {
+        header: (name: string) => string | undefined;
+    };
+    json: (data: unknown, status?: number) => unknown;
+}
+export interface ErrorHandlerOptions {
+    /**
+     * Called for every caught error so callers can route it to their structured
+     * logger (e.g. @nebutra/logger).  Defaults to a no-op — DO NOT rely on the
+     * previous process.stderr.write behaviour; pass an onError callback instead.
+     */
+    onError?: (error: unknown, meta: {
+        requestId?: string;
+        statusCode: number;
+    }) => void;
+}
+export declare function errorHandler(options?: ErrorHandlerOptions): (c: HonoContext, next: () => Promise<void>) => Promise<unknown>;
+/**
+ * Wrap async function with error handling
+ */
+export declare function tryCatch<T>(fn: () => Promise<T>, errorHandler?: (error: unknown) => T | Promise<T>): Promise<T>;
+/**
+ * Assert condition or throw error
+ */
+export declare function assert(condition: unknown, message: string): asserts condition;
+/**
+ * Assert not null/undefined or throw NotFoundError
+ */
+export declare function assertFound<T>(value: T | null | undefined, resource: string, id?: string): asserts value is T;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;CAuBd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAMvE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,QAAS,SAAQ,KAAK;IACjC,SAAgB,IAAI,EAAE,SAAS,CAAC;IAChC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,aAAa,EAAE,OAAO,CAAC;IACvC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,OAAO,EAAE,eAAe;IAqBpC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAWlC;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB;CAejF;AAMD,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;gBAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;CAY/D;AAED,qBAAa,iBAAkB,SAAQ,QAAQ;gBACjC,OAAO,SAAiB;CAIrC;AAED,qBAAa,cAAe,SAAQ,QAAQ;gBAC9B,OAAO,SAAc;CAIlC;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,QAAQ,SAAa,EAAE,EAAE,CAAC,EAAE,MAAM;CAK/C;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,OAAO,SAA4B;CAIhD;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,UAAU,CAAC,EAAE,MAAM;CAYhC;AAED,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAS1D;AAED,qBAAa,oBAAqB,SAAQ,QAAQ;gBACpC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAU3C;AAED,qBAAa,aAAc,SAAQ,QAAQ;gBAC7B,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAW7C;AAMD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QACL,IAAI,EAAE,SAAS,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAyB/E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKpD;AAMD,UAAU,WAAW;IACnB,GAAG,EAAE;QAAE,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IACtD,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACtF;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,IAC9C,GAAG,WAAW,EAAE,MAAM,MAAM,OAAO,CAAC,IAAI,CAAC,sBAgBxD;AAyCD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAO7E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,EAChB,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,IAAI,CAAC,CAIpB"}

package/dist/index.js

@@ -0,0 +1,294 @@
+/**
+ * Errors - Unified error handling for Nebutra services
+ *
+ * Provides:
+ * - Typed error classes
+ * - Consistent API error responses
+ * - Error serialization for logging
+ */
+// ============================================
+// Error Codes
+// ============================================
+export const ERROR_CODES = {
+    // Client errors (4xx)
+    BAD_REQUEST: "BAD_REQUEST",
+    UNAUTHORIZED: "UNAUTHORIZED",
+    FORBIDDEN: "FORBIDDEN",
+    NOT_FOUND: "NOT_FOUND",
+    CONFLICT: "CONFLICT",
+    VALIDATION_ERROR: "VALIDATION_ERROR",
+    RATE_LIMITED: "RATE_LIMITED",
+    QUOTA_EXCEEDED: "QUOTA_EXCEEDED",
+    // Server errors (5xx)
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+    SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+    EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR",
+    DATABASE_ERROR: "DATABASE_ERROR",
+    TIMEOUT: "TIMEOUT",
+    // Business errors
+    PAYMENT_REQUIRED: "PAYMENT_REQUIRED",
+    SUBSCRIPTION_EXPIRED: "SUBSCRIPTION_EXPIRED",
+    FEATURE_DISABLED: "FEATURE_DISABLED",
+    TENANT_SUSPENDED: "TENANT_SUSPENDED",
+};
+export class AppError extends Error {
+    code;
+    statusCode;
+    isOperational;
+    metadata;
+    suggestion;
+    timestamp;
+    constructor(options) {
+        super(options.message);
+        this.name = "AppError";
+        this.code = options.code;
+        this.statusCode = options.statusCode || getDefaultStatusCode(options.code);
+        this.isOperational = options.isOperational ?? true;
+        if (options.metadata !== undefined) {
+            this.metadata = options.metadata;
+        }
+        if (options.suggestion !== undefined) {
+            this.suggestion = options.suggestion;
+        }
+        this.timestamp = new Date().toISOString();
+        if (options.cause) {
+            this.cause = options.cause;
+        }
+        Error.captureStackTrace(this, this.constructor);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp,
+            suggestion: this.suggestion,
+            metadata: this.metadata,
+        };
+    }
+}
+export class CapabilityError extends AppError {
+    capability;
+    constructor(capability, message, options) {
+        super({
+            code: options.code ?? ERROR_CODES.EXTERNAL_SERVICE_ERROR,
+            message,
+            statusCode: options.statusCode ?? 502,
+            ...(options.cause !== undefined ? { cause: options.cause } : {}),
+            suggestion: options.suggestion,
+            metadata: {
+                capability,
+                ...(options.metadata ?? {}),
+            },
+        });
+        this.name = "CapabilityError";
+        this.capability = capability;
+    }
+}
+// ============================================
+// Specific Error Classes
+// ============================================
+export class ValidationError extends AppError {
+    fields;
+    constructor(message, fields) {
+        super({
+            code: ERROR_CODES.VALIDATION_ERROR,
+            message,
+            statusCode: 400,
+            ...(fields !== undefined && { metadata: { fields } }),
+        });
+        this.name = "ValidationError";
+        if (fields !== undefined) {
+            this.fields = fields;
+        }
+    }
+}
+export class UnauthorizedError extends AppError {
+    constructor(message = "Unauthorized") {
+        super({ code: ERROR_CODES.UNAUTHORIZED, message, statusCode: 401 });
+        this.name = "UnauthorizedError";
+    }
+}
+export class ForbiddenError extends AppError {
+    constructor(message = "Forbidden") {
+        super({ code: ERROR_CODES.FORBIDDEN, message, statusCode: 403 });
+        this.name = "ForbiddenError";
+    }
+}
+export class NotFoundError extends AppError {
+    constructor(resource = "Resource", id) {
+        const message = id ? `${resource} with id '${id}' not found` : `${resource} not found`;
+        super({ code: ERROR_CODES.NOT_FOUND, message, statusCode: 404 });
+        this.name = "NotFoundError";
+    }
+}
+export class ConflictError extends AppError {
+    constructor(message = "Resource already exists") {
+        super({ code: ERROR_CODES.CONFLICT, message, statusCode: 409 });
+        this.name = "ConflictError";
+    }
+}
+export class RateLimitError extends AppError {
+    retryAfter;
+    constructor(retryAfter) {
+        super({
+            code: ERROR_CODES.RATE_LIMITED,
+            message: "Too many requests",
+            statusCode: 429,
+            ...(retryAfter !== undefined && { metadata: { retryAfter } }),
+        });
+        this.name = "RateLimitError";
+        if (retryAfter !== undefined) {
+            this.retryAfter = retryAfter;
+        }
+    }
+}
+export class QuotaExceededError extends AppError {
+    constructor(quota, limit, current) {
+        super({
+            code: ERROR_CODES.QUOTA_EXCEEDED,
+            message: `${quota} quota exceeded (${current}/${limit})`,
+            statusCode: 429,
+            metadata: { quota, limit, current },
+        });
+        this.name = "QuotaExceededError";
+    }
+}
+export class ExternalServiceError extends AppError {
+    constructor(service, cause) {
+        super({
+            code: ERROR_CODES.EXTERNAL_SERVICE_ERROR,
+            message: `External service '${service}' failed`,
+            statusCode: 502,
+            ...(cause !== undefined && { cause }),
+            metadata: { service },
+        });
+        this.name = "ExternalServiceError";
+    }
+}
+export class DatabaseError extends AppError {
+    constructor(operation, cause) {
+        super({
+            code: ERROR_CODES.DATABASE_ERROR,
+            message: `Database operation '${operation}' failed`,
+            statusCode: 500,
+            ...(cause !== undefined && { cause }),
+            isOperational: false,
+            metadata: { operation },
+        });
+        this.name = "DatabaseError";
+    }
+}
+export function toApiError(error, requestId) {
+    if (error instanceof AppError) {
+        return {
+            error: {
+                code: error.code,
+                message: error.message,
+                ...((error.metadata !== undefined || error.suggestion !== undefined) && {
+                    details: {
+                        ...(error.metadata ?? {}),
+                        ...(error.suggestion !== undefined && { suggestion: error.suggestion }),
+                    },
+                }),
+            },
+            ...(requestId !== undefined && { requestId }),
+        };
+    }
+    // Unknown error - don't leak details
+    return {
+        error: {
+            code: ERROR_CODES.INTERNAL_ERROR,
+            message: "An unexpected error occurred",
+        },
+        ...(requestId !== undefined && { requestId }),
+    };
+}
+export function getStatusCode(error) {
+    if (error instanceof AppError) {
+        return error.statusCode;
+    }
+    return 500;
+}
+export function errorHandler(options = {}) {
+    return async (c, next) => {
+        try {
+            await next();
+        }
+        catch (error) {
+            const requestId = c.req.header("x-request-id");
+            const statusCode = getStatusCode(error);
+            const response = toApiError(error, requestId);
+            options.onError?.(error, requestId !== undefined ? { requestId, statusCode } : { statusCode });
+            return c.json(response, statusCode);
+        }
+    };
+}
+// ============================================
+// Utility Functions
+// ============================================
+function getDefaultStatusCode(code) {
+    switch (code) {
+        case ERROR_CODES.BAD_REQUEST:
+        case ERROR_CODES.VALIDATION_ERROR:
+            return 400;
+        case ERROR_CODES.UNAUTHORIZED:
+            return 401;
+        case ERROR_CODES.PAYMENT_REQUIRED:
+        case ERROR_CODES.SUBSCRIPTION_EXPIRED:
+            return 402;
+        case ERROR_CODES.FORBIDDEN:
+        case ERROR_CODES.FEATURE_DISABLED:
+        case ERROR_CODES.TENANT_SUSPENDED:
+            return 403;
+        case ERROR_CODES.NOT_FOUND:
+            return 404;
+        case ERROR_CODES.CONFLICT:
+            return 409;
+        case ERROR_CODES.RATE_LIMITED:
+        case ERROR_CODES.QUOTA_EXCEEDED:
+            return 429;
+        case ERROR_CODES.INTERNAL_ERROR:
+        case ERROR_CODES.DATABASE_ERROR:
+            return 500;
+        case ERROR_CODES.EXTERNAL_SERVICE_ERROR:
+            return 502;
+        case ERROR_CODES.SERVICE_UNAVAILABLE:
+            return 503;
+        case ERROR_CODES.TIMEOUT:
+            return 504;
+        default:
+            return 500;
+    }
+}
+/**
+ * Wrap async function with error handling
+ */
+export function tryCatch(fn, errorHandler) {
+    return fn().catch((error) => {
+        if (errorHandler) {
+            return errorHandler(error);
+        }
+        throw error;
+    });
+}
+/**
+ * Assert condition or throw error
+ */
+export function assert(condition, message) {
+    if (!condition) {
+        throw new AppError({
+            code: ERROR_CODES.BAD_REQUEST,
+            message,
+        });
+    }
+}
+/**
+ * Assert not null/undefined or throw NotFoundError
+ */
+export function assertFound(value, resource, id) {
+    if (value === null || value === undefined) {
+        throw new NotFoundError(resource, id);
+    }
+}

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@nebutra/errors",
-  "version": "0.1.1",
+  "version": "2.0.0",
   "description": "Unified error handling and API error responses",
   "private": false,
+  "nebutra": {
+    "status": "foundation",
+    "graph": "core",
+    "productionReady": false
+  },
   "license": "MIT",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
+  "files": [
+    "dist"
+  ],
   "devDependencies": {
     "@types/node": "^22.19.15",
     "typescript": "^5.9.3",
@@ -28,7 +40,8 @@
     "access": "public"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.json",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/errors@0.1.1 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/platform/errors
-> vitest run
-
-
- RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/platform/errors
-
- ✓ src/index.test.ts (1 test) 50ms
-
- Test Files  1 passed (1)
-      Tests  1 passed (1)
-   Start at  08:14:48
-   Duration  1.58s (transform 455ms, setup 0ms, import 577ms, tests 50ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/errors@0.1.1 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/platform/errors
-> tsc --noEmit
-

package/AGENTS.md

@@ -1,65 +0,0 @@
-# AGENTS.md — packages/errors
-
-Execution contract for Nebutra's shared error semantics package.
-
-## Scope
-
-Applies to everything under `packages/platform/errors/`.
-
-This package owns canonical application error codes, typed error classes,
-API-safe serialization helpers, and the framework-agnostic error middleware
-shape. It is the shared error vocabulary layer, not the place for service-local
-logging policy or provider-specific exception translation.
-
-## Source Of Truth
-
-- Public package surface: `package.json`, `src/index.ts`
-- Canonical error code catalog: `ERROR_CODES`
-- Base error class and serialization behavior: `AppError`, `AppErrorOptions`,
-  `AppError.toJSON()`
-- Specific error subclasses and their default status semantics:
-  `ValidationError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`,
-  `ConflictError`, `RateLimitError`, `QuotaExceededError`,
-  `ExternalServiceError`, `DatabaseError`
-- API response and status helpers: `toApiError`, `getStatusCode`
-- Framework boundary for request-safe error responses: `errorHandler`
-- Assertion and wrapper helpers: `tryCatch`, `assert`, `assertFound`
-
-Treat `README.md` as descriptive only. If docs drift, update `src/index.ts`
-instead of preserving outdated examples.
-
-## Contract Boundaries
-
-- Keep `ERROR_CODES` as the canonical shared vocabulary. Additive changes are
-  safest; renames or removals are compatibility changes for callers, handlers,
-  and logs.
-- Treat `AppError` and `ApiErrorResponse` as the stable serialization boundary.
-  Do not leak raw unknown errors or provider-specific details through
-  `toApiError`.
-- Preserve default status-code mapping in `getDefaultStatusCode()` unless the
-  compatibility change is deliberate and coordinated with consumers.
-- Keep `errorHandler()` framework-agnostic and request-safe. Its job is to map
-  errors into structured JSON and invoke the optional `onError` callback, not
-  to own logging destinations or transport-specific side effects.
-- Preserve the distinction between operational and non-operational errors.
-  `DatabaseError` and other server faults should not be quietly normalized into
-  benign client semantics.
-- Keep assertion helpers thin wrappers over the shared error types. Do not
-  embed app-specific policy or database lookups here.
-
-## Generated And Derived Files
-
-- This package currently exports source directly and has no checked-in
-  generated source of truth.
-- Do not hand-edit future build output, coverage artifacts, or transient
-  TypeScript output.
-- If packaging changes later, update the source files above rather than derived
-  artifacts.
-
-## Validation
-
-- Error type, code, or middleware changes:
-  `pnpm --filter @nebutra/errors exec tsc --noEmit`
-- Because this package currently has no package-local tests, verify the
-  narrowest downstream consumer that exercises the changed error contract when
-  behavior changes are non-trivial.

package/CHANGELOG.md

@@ -1,7 +0,0 @@
-# @nebutra/errors
-
-## 0.1.1
-
-### Patch Changes
-
-- Publish registry package metadata under the MIT license.

package/src/index.test.ts

@@ -1,22 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { CapabilityError, toApiError } from "./index";
-
-describe("CapabilityError", () => {
-  it("serializes a suggestion for API callers", () => {
-    const error = new CapabilityError("provider-registry", "Missing local model", {
-      suggestion: "Run provider-registry:doctor and install a local model.",
-      metadata: { provider: "ollama" },
-    });
-
-    expect(error.capability).toBe("provider-registry");
-    expect(error.suggestion).toContain("provider-registry:doctor");
-    expect(error.toJSON()).toMatchObject({
-      code: "EXTERNAL_SERVICE_ERROR",
-      suggestion: "Run provider-registry:doctor and install a local model.",
-      metadata: { capability: "provider-registry", provider: "ollama" },
-    });
-    expect(toApiError(error).error.details).toMatchObject({
-      suggestion: "Run provider-registry:doctor and install a local model.",
-    });
-  });
-});