@pristine-ts/common 2.0.3 → 2.0.5

package/dist/lib/cjs/contexts/event-context.js

@@ -3,16 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventContext = void 0;
 /**
  * Per-event runtime state — the framework's correlation primitives plus a handle to
- * the per-event DI child container. Propagated implicitly via `AsyncLocalStorage`
- * (managed by `EventContextManager`) so downstream code doesn't have to thread these
- * fields through every method signature.
+ * the per-event DI child container and the active trace. Propagated implicitly via
+ * `AsyncLocalStorage` (managed by `EventContextManager`) so downstream code doesn't
+ * have to thread these fields through every method signature.
  *
  * **Not to be confused with `ExecutionContextInterface` (in `@pristine-ts/core`):**
  *   - `ExecutionContext` describes *where* the framework is running (AWS Lambda, CLI,
  *     Express, etc.) — set once per `kernel.handle()` call, immutable, host-shaped.
  *   - `EventContext` describes *which specific event* is being handled — set per event
- *     in the pipeline, mutable (`traceId` fills in once tracing starts), correlation-
- *     shaped.
+ *     in the pipeline, mutable (`traceId` / `trace` fill in once tracing starts),
+ *     correlation-shaped.
  *
  * One `kernel.handle()` call can produce multiple events (each event mapper can return
  * a list); each event gets its own `EventContext` instance.

package/dist/lib/cjs/contexts/event-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../../../src/contexts/event-context.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;CAYxB;AAZD,oCAYC"}
+{"version":3,"file":"event-context.js","sourceRoot":"","sources":["../../../../src/contexts/event-context.ts"],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;GAeG;AACH,MAAa,YAAY;CA2BxB;AA3BD,oCA2BC"}

package/dist/lib/cjs/decorators/decorators.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./inject-config.decorator"), exports);
 __exportStar(require("./module-scoped.decorator"), exports);
 __exportStar(require("./tag.decorator"), exports);
+__exportStar(require("./traced.decorator"), exports);
 //# sourceMappingURL=decorators.js.map

package/dist/lib/cjs/decorators/decorators.js.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,4DAA0C;AAC1C,kDAAgC"}
+{"version":3,"file":"decorators.js","sourceRoot":"","sources":["../../../../src/decorators/decorators.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,4DAA0C;AAC1C,kDAAgC;AAChC,qDAAmC"}

package/dist/lib/cjs/decorators/traced.decorator.js

@@ -0,0 +1,101 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traced = traced;
+const event_context_manager_1 = require("../managers/event-context.manager");
+/**
+ * Method decorator that wraps the decorated method in a span. The span is automatically
+ * ended when the method returns or throws, and the `TracingManager` is auto-resolved
+ * from the active `EventContext` — no need to inject it manually.
+ *
+ * ```ts
+ * class PaymentService {
+ *   @traced()                                // span name = "PaymentService.charge"
+ *   async charge(amount: number) { ... }
+ *
+ *   @traced("payment.refund.action")         // explicit name
+ *   async refund(chargeId: string) { ... }
+ * }
+ * ```
+ *
+ * **Behavior outside an event context.** When the decorated method runs without an
+ * active `EventContext` (e.g. a unit test calling the method directly, or background
+ * work that escaped the event lifecycle), the decorator is a no-op — the original
+ * method runs unchanged. Tracing must never throw or alter semantics.
+ *
+ * **Sync methods become async.** The decorator awaits the wrapped method internally,
+ * so any decorated method returns a `Promise`. Decorating a sync method changes its
+ * signature visible to callers — apply `@traced` to methods you'd already be awaiting
+ * (DB calls, HTTP, expensive computations), not to tight sync helpers.
+ *
+ * **Type-level caveat.** TypeScript's parameter and method decorator types don't carry
+ * enough information for the compiler to verify that the wrapped method's return type
+ * is compatible with `Promise<T>`. The wrapper is type-safe at runtime; the call site's
+ * static types are unchanged. Pair with explicit `: Promise<T>` annotations on the
+ * method when you want the static type to match what's actually returned.
+ *
+ * **Lives in `@pristine-ts/common`** so any package can use it without taking a direct
+ * dep on `@pristine-ts/telemetry`. The actual `TracingManager` implementation still
+ * lives in telemetry; this decorator only reads the active manager from the
+ * EventContext when one is present.
+ *
+ * @param spanName Optional explicit name for the span. Defaults to
+ *   `${ClassName}.${methodName}`.
+ */
+function traced(spanName) {
+    return (target, propertyKey, descriptor) => {
+        var _a, _b, _c;
+        const original = descriptor.value;
+        if (typeof original !== "function") {
+            // Decorator was applied to something other than a method (a getter, a property
+            // with no initial value, etc.). Leave it alone — silently no-op rather than
+            // throw at decoration time.
+            return descriptor;
+        }
+        // Resolve a stable default name at decoration time. `target.constructor.name` is
+        // the class name for instance methods; for static methods, `target.name` is the
+        // class. We cover both via the fallback chain.
+        const className = (_c = (_b = (_a = target === null || target === void 0 ? void 0 : target.constructor) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : target === null || target === void 0 ? void 0 : target.name) !== null && _c !== void 0 ? _c : "anonymous";
+        const resolvedName = spanName !== null && spanName !== void 0 ? spanName : `${className}.${String(propertyKey)}`;
+        descriptor.value = function (...args) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const tracingManager = event_context_manager_1.EventContextManager.tracingManager();
+                if (tracingManager === undefined) {
+                    // No active EventContext (unit test, background work, kernel boot before the
+                    // pipeline runs). Run the original unchanged — tracing must never throw or
+                    // alter semantics.
+                    return yield original.apply(this, args);
+                }
+                const span = tracingManager.startSpan(resolvedName);
+                try {
+                    return yield original.apply(this, args);
+                }
+                catch (error) {
+                    // Annotate the span with error info so it surfaces in the rendered tree
+                    // without forcing the caller to remember to add it themselves. `span.context`
+                    // is string-typed by design (cheap to serialize), so we coerce.
+                    if (error instanceof Error) {
+                        span.context = Object.assign(Object.assign({}, span.context), { error: "true", errorName: error.name, errorMessage: error.message });
+                    }
+                    else {
+                        span.context = Object.assign(Object.assign({}, span.context), { error: "true", errorName: "non-error-throw", errorMessage: String(error) });
+                    }
+                    throw error;
+                }
+                finally {
+                    span.end();
+                }
+            });
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=traced.decorator.js.map

package/dist/lib/cjs/decorators/traced.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traced.decorator.js","sourceRoot":"","sources":["../../../../src/decorators/traced.decorator.ts"],"names":[],"mappings":";;;;;;;;;;;AAyCA,wBAuDC;AAhGD,6EAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,SAAgB,MAAM,CAAC,QAAiB;IACtC,OAAO,CAAC,MAAW,EAAE,WAA4B,EAAE,UAA8B,EAAE,EAAE;;QACnF,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;YACnC,+EAA+E;YAC/E,4EAA4E;YAC5E,4BAA4B;YAC5B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,iFAAiF;QACjF,gFAAgF;QAChF,+CAA+C;QAC/C,MAAM,SAAS,GAAW,MAAA,MAAA,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,0CAAE,IAAI,mCAAI,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,mCAAI,WAAW,CAAC;QACnF,MAAM,YAAY,GAAG,QAAQ,aAAR,QAAQ,cAAR,QAAQ,GAAI,GAAG,SAAS,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEvE,UAAU,CAAC,KAAK,GAAG,UAA+B,GAAG,IAAW;;gBAC9D,MAAM,cAAc,GAAG,2CAAmB,CAAC,cAAc,EAAE,CAAC;gBAC5D,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;oBACjC,6EAA6E;oBAC7E,2EAA2E;oBAC3E,mBAAmB;oBACnB,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC1C,CAAC;gBAED,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;gBACpD,IAAI,CAAC;oBACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAC1C,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,wEAAwE;oBACxE,8EAA8E;oBAC9E,gEAAgE;oBAChE,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;wBAC3B,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,KAAK,CAAC,IAAI,EACrB,YAAY,EAAE,KAAK,CAAC,OAAO,GAC5B,CAAC;oBACJ,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,OAAO,mCACP,IAAI,CAAC,OAAO,KACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,iBAAiB,EAC5B,YAAY,EAAE,MAAM,CAAC,KAAK,CAAC,GAC5B,CAAC;oBACJ,CAAC;oBACD,MAAM,KAAK,CAAC;gBACd,CAAC;wBAAS,CAAC;oBACT,IAAI,CAAC,GAAG,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;SAAA,CAAC;QAEF,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/lib/cjs/enums/enums.js

@@ -18,4 +18,5 @@ __exportStar(require("./http-method.enum"), exports);
 __exportStar(require("./internal-container-parameter.enum"), exports);
 __exportStar(require("./metadata.enum"), exports);
 __exportStar(require("./service-definition-tag.enum"), exports);
+__exportStar(require("./span-keyname.enum"), exports);
 //# sourceMappingURL=enums.js.map

package/dist/lib/cjs/enums/enums.js.map

@@ -1 +1 @@
-{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,sEAAoD;AACpD,kDAAgC;AAChC,gEAA8C"}
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../../src/enums/enums.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,sEAAoD;AACpD,kDAAgC;AAChC,gEAA8C;AAC9C,sDAAoC"}

package/dist/lib/cjs/enums/span-keyname.enum.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanKeynameEnum = void 0;
+/**
+ * This enum is for the different span names that are integrated in Pristine.
+ */
+var SpanKeynameEnum;
+(function (SpanKeynameEnum) {
+    SpanKeynameEnum["ChildContainerCreation"] = "child.container.creation";
+    SpanKeynameEnum["ChildContainerRegistration"] = "child.container.registration";
+    SpanKeynameEnum["ConfigurationInitialization"] = "configuration.initialization";
+    SpanKeynameEnum["ErrorResponseInterceptors"] = "error.response.interceptors";
+    SpanKeynameEnum["EventDispatcherResolver"] = "event.dispatcher.resolver";
+    SpanKeynameEnum["EventExecution"] = "event.execution";
+    SpanKeynameEnum["EventInitialization"] = "event.initialization";
+    SpanKeynameEnum["EventPreMappingInterception"] = "event.pre-mapping.interception";
+    SpanKeynameEnum["EventPostMappingInterception"] = "event.post-mapping.interception";
+    SpanKeynameEnum["EventPreResponseMappingInterception"] = "event.pre-response-mapping.interception";
+    SpanKeynameEnum["EventPostResponseMappingInterception"] = "event.post-response-mapping.interception";
+    SpanKeynameEnum["EventMapping"] = "event.mapping";
+    SpanKeynameEnum["KernelInitialization"] = "kernel.initialization";
+    SpanKeynameEnum["ModuleInitialization"] = "module.initialization";
+    SpanKeynameEnum["ModuleInitializationImportModules"] = "module.initialization.import.modules";
+    SpanKeynameEnum["RequestExecution"] = "request.execution";
+    SpanKeynameEnum["RequestInterceptors"] = "request.interceptors";
+    SpanKeynameEnum["ResponseInterceptors"] = "response.interceptors";
+    SpanKeynameEnum["RootExecution"] = "root.execution";
+    SpanKeynameEnum["RouterControllerResolver"] = "router.controller.resolver";
+    SpanKeynameEnum["RouterFindMethodRouterNode"] = "router.find.method.router.node";
+    SpanKeynameEnum["RouterRequestAuthentication"] = "router.request.authentication";
+    SpanKeynameEnum["RouterRequestExecution"] = "router.request.execution";
+    SpanKeynameEnum["RouterSetup"] = "router.setup";
+})(SpanKeynameEnum || (exports.SpanKeynameEnum = SpanKeynameEnum = {}));
+//# sourceMappingURL=span-keyname.enum.js.map

package/dist/lib/cjs/enums/span-keyname.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-keyname.enum.js","sourceRoot":"","sources":["../../../../src/enums/span-keyname.enum.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,IAAY,eAyBX;AAzBD,WAAY,eAAe;IACzB,sEAAmD,CAAA;IACnD,8EAA2D,CAAA;IAC3D,+EAA4D,CAAA;IAC5D,4EAAyD,CAAA;IACzD,wEAAqD,CAAA;IACrD,qDAAkC,CAAA;IAClC,+DAA4C,CAAA;IAC5C,iFAA8D,CAAA;IAC9D,mFAAgE,CAAA;IAChE,kGAA+E,CAAA;IAC/E,oGAAiF,CAAA;IACjF,iDAA8B,CAAA;IAC9B,iEAA8C,CAAA;IAC9C,iEAA8C,CAAA;IAC9C,6FAA0E,CAAA;IAC1E,yDAAsC,CAAA;IACtC,+DAA4C,CAAA;IAC5C,iEAA8C,CAAA;IAC9C,mDAAgC,CAAA;IAChC,0EAAuD,CAAA;IACvD,gFAA6D,CAAA;IAC7D,gFAA6D,CAAA;IAC7D,sEAAmD,CAAA;IACnD,+CAA4B,CAAA;AAC9B,CAAC,EAzBW,eAAe,+BAAf,eAAe,QAyB1B"}

package/dist/lib/cjs/errors/bad-request.error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BadRequestError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/** 400. Caller sent malformed/invalid input. CLI exit `ExitCode.DataError` (65). */
+class BadRequestError extends pristine_error_1.PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.BadRequest, httpStatus: 400, exitCode: exit_code_enum_1.ExitCode.DataError, kind: pristine_error_kind_enum_1.PristineErrorKind.UserError }, options));
+    }
+}
+exports.BadRequestError = BadRequestError;
+//# sourceMappingURL=bad-request.error.js.map

package/dist/lib/cjs/errors/bad-request.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bad-request.error.js","sourceRoot":"","sources":["../../../../src/errors/bad-request.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D,oFAAoF;AACpF,MAAa,eAAgB,SAAQ,8BAAa;IAChD,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAAQ,CAAC,SAAS,EACjF,IAAI,EAAE,4CAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,0CAQC"}

package/dist/lib/cjs/errors/config.error.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/**
+ * Configuration loading / parsing / validation failure. No `httpStatus` — config errors
+ * shouldn't be exposed to HTTP callers, so the responder will treat them as 500 with
+ * sanitized message. CLI exit `ExitCode.Configuration` (78). Marked `SystemError` so the
+ * message isn't surfaced verbatim in production HTTP responses.
+ */
+class ConfigError extends pristine_error_1.PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.ConfigError, exitCode: exit_code_enum_1.ExitCode.Configuration, kind: pristine_error_kind_enum_1.PristineErrorKind.SystemError }, options));
+    }
+}
+exports.ConfigError = ConfigError;
+//# sourceMappingURL=config.error.js.map

package/dist/lib/cjs/errors/config.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.error.js","sourceRoot":"","sources":["../../../../src/errors/config.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D;;;;;GAKG;AACH,MAAa,WAAY,SAAQ,8BAAa;IAC5C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,WAAW,EAAE,QAAQ,EAAE,yBAAQ,CAAC,aAAa,EACrE,IAAI,EAAE,4CAAiB,CAAC,WAAW,IAChC,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,kCAQC"}

package/dist/lib/cjs/errors/conflict.error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConflictError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/** 409. Operation conflicts with existing state (duplicate, version mismatch, etc.). */
+class ConflictError extends pristine_error_1.PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.Conflict, httpStatus: 409, exitCode: exit_code_enum_1.ExitCode.Error, kind: pristine_error_kind_enum_1.PristineErrorKind.UserError }, options));
+    }
+}
+exports.ConflictError = ConflictError;
+//# sourceMappingURL=conflict.error.js.map

package/dist/lib/cjs/errors/conflict.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.error.js","sourceRoot":"","sources":["../../../../src/errors/conflict.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D,wFAAwF;AACxF,MAAa,aAAc,SAAQ,8BAAa;IAC9C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAAQ,CAAC,KAAK,EAC3E,IAAI,EAAE,4CAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,sCAQC"}

package/dist/lib/cjs/errors/errors.js

@@ -14,5 +14,18 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./loggable.error"), exports);
+__exportStar(require("./bad-request.error"), exports);
+__exportStar(require("./config.error"), exports);
+__exportStar(require("./conflict.error"), exports);
+__exportStar(require("./exit-code.enum"), exports);
+__exportStar(require("./forbidden.error"), exports);
+__exportStar(require("./internal.error"), exports);
+__exportStar(require("./not-found.error"), exports);
+__exportStar(require("./pristine-error-code.enum"), exports);
+__exportStar(require("./pristine-error-kind.enum"), exports);
+__exportStar(require("./pristine-error-options.interface"), exports);
+__exportStar(require("./pristine.error"), exports);
+__exportStar(require("./unauthorized.error"), exports);
+__exportStar(require("./usage.error"), exports);
+__exportStar(require("./validation.error"), exports);
 //# sourceMappingURL=errors.js.map

package/dist/lib/cjs/errors/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/errors/errors.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../src/errors/errors.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,iDAA+B;AAC/B,mDAAiC;AACjC,mDAAiC;AACjC,oDAAkC;AAClC,mDAAiC;AACjC,oDAAkC;AAClC,6DAA2C;AAC3C,6DAA2C;AAC3C,qEAAmD;AACnD,mDAAiC;AACjC,uDAAqC;AACrC,gDAA8B;AAC9B,qDAAmC"}

package/dist/lib/cjs/errors/exit-code.enum.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExitCode = void 0;
+/**
+ * Standard process exit codes, drawn from BSD's `sysexits.h` conventions. Surfaced by
+ * `CliErrorReporter` and `PristineError.options.exitCode` so shell pipelines can branch on
+ * meaningful failure categories rather than the binary "0 or non-zero" distinction.
+ *
+ * **Use the enum for framework-standard codes.** Consumers can pass raw numbers for any
+ * custom exit code — `PristineErrorOptions.exitCode` is typed `ExitCode | number`.
+ *
+ * Note that exit codes ≥ 64 (`Usage` and above) follow the `sysexits.h` registered
+ * meanings; lower codes (1, etc.) are conventional but not standardized.
+ *
+ * ```ts
+ * throw new ConfigError("Missing DATABASE_URL", {
+ *   exitCode: ExitCode.Configuration,   // 78 — picked up by shells aware of sysexits.h
+ * });
+ *
+ * throw new UsageError("Unknown flag --foo", {
+ *   exitCode: ExitCode.Usage,           // 64
+ * });
+ * ```
+ */
+var ExitCode;
+(function (ExitCode) {
+    /** Successful termination. */
+    ExitCode[ExitCode["Success"] = 0] = "Success";
+    /** Generic error. Default fallback for user-facing errors that don't specify a code. */
+    ExitCode[ExitCode["Error"] = 1] = "Error";
+    /** Command-line usage error (`EX_USAGE`). Bad flags, missing required args, unknown commands. */
+    ExitCode[ExitCode["Usage"] = 64] = "Usage";
+    /** Input data malformed (`EX_DATAERR`). Validation failed, body unparseable. */
+    ExitCode[ExitCode["DataError"] = 65] = "DataError";
+    /** Internal software error (`EX_SOFTWARE`). Default fallback for system errors. */
+    ExitCode[ExitCode["Software"] = 70] = "Software";
+    /** Can't create user output file (`EX_CANTCREAT`). */
+    ExitCode[ExitCode["Cantcreat"] = 73] = "Cantcreat";
+    /** Input/output error (`EX_IOERR`). */
+    ExitCode[ExitCode["IoError"] = 74] = "IoError";
+    /** Temporary failure, retry might succeed (`EX_TEMPFAIL`). */
+    ExitCode[ExitCode["Temporary"] = 75] = "Temporary";
+    /** Remote error in protocol (`EX_PROTOCOL`). */
+    ExitCode[ExitCode["Protocol"] = 76] = "Protocol";
+    /** Permission denied (`EX_NOPERM`). Authentication / authorization failures. */
+    ExitCode[ExitCode["NoPermission"] = 77] = "NoPermission";
+    /** Configuration error (`EX_CONFIG`). Missing or invalid config. */
+    ExitCode[ExitCode["Configuration"] = 78] = "Configuration";
+})(ExitCode || (exports.ExitCode = ExitCode = {}));
+//# sourceMappingURL=exit-code.enum.js.map

package/dist/lib/cjs/errors/exit-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-code.enum.js","sourceRoot":"","sources":["../../../../src/errors/exit-code.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,IAAY,QAiCX;AAjCD,WAAY,QAAQ;IAClB,8BAA8B;IAC9B,6CAAmB,CAAA;IAEnB,wFAAwF;IACxF,yCAAmB,CAAA;IAEnB,iGAAiG;IACjG,0CAAoB,CAAA;IAEpB,gFAAgF;IAChF,kDAAoB,CAAA;IAEpB,mFAAmF;IACnF,gDAAoB,CAAA;IAEpB,sDAAsD;IACtD,kDAAoB,CAAA;IAEpB,uCAAuC;IACvC,8CAAoB,CAAA;IAEpB,8DAA8D;IAC9D,kDAAoB,CAAA;IAEpB,gDAAgD;IAChD,gDAAoB,CAAA;IAEpB,gFAAgF;IAChF,wDAAoB,CAAA;IAEpB,oEAAoE;IACpE,0DAAoB,CAAA;AACtB,CAAC,EAjCW,QAAQ,wBAAR,QAAQ,QAiCnB"}

package/dist/lib/cjs/errors/forbidden.error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForbiddenError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/** 403. Caller is authenticated but lacks permission. CLI exit `ExitCode.NoPermission` (77). */
+class ForbiddenError extends pristine_error_1.PristineError {
+    constructor(message = "Forbidden", options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.Forbidden, httpStatus: 403, exitCode: exit_code_enum_1.ExitCode.NoPermission, kind: pristine_error_kind_enum_1.PristineErrorKind.UserError }, options));
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+//# sourceMappingURL=forbidden.error.js.map

package/dist/lib/cjs/errors/forbidden.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forbidden.error.js","sourceRoot":"","sources":["../../../../src/errors/forbidden.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D,gGAAgG;AAChG,MAAa,cAAe,SAAQ,8BAAa;IAC/C,YAAY,UAAkB,WAAW,EAAE,UAA2B,EAAE;QACtE,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAAQ,CAAC,YAAY,EACnF,IAAI,EAAE,4CAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,wCAQC"}

package/dist/lib/cjs/errors/internal.error.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InternalError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/**
+ * Catch-all for framework/system bugs that shouldn't be exposed verbatim. 500.
+ * CLI exit `ExitCode.Software` (70). `SystemError` triggers message sanitization in
+ * production mode.
+ */
+class InternalError extends pristine_error_1.PristineError {
+    constructor(message = "Internal error", options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.InternalError, httpStatus: 500, exitCode: exit_code_enum_1.ExitCode.Software, kind: pristine_error_kind_enum_1.PristineErrorKind.SystemError }, options));
+    }
+}
+exports.InternalError = InternalError;
+//# sourceMappingURL=internal.error.js.map

package/dist/lib/cjs/errors/internal.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.error.js","sourceRoot":"","sources":["../../../../src/errors/internal.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D;;;;GAIG;AACH,MAAa,aAAc,SAAQ,8BAAa;IAC9C,YAAY,UAAkB,gBAAgB,EAAE,UAA2B,EAAE;QAC3E,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,aAAa,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAAQ,CAAC,QAAQ,EACnF,IAAI,EAAE,4CAAiB,CAAC,WAAW,IAChC,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,sCAQC"}

package/dist/lib/cjs/errors/not-found.error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotFoundError = void 0;
+const exit_code_enum_1 = require("./exit-code.enum");
+const pristine_error_1 = require("./pristine.error");
+const pristine_error_code_enum_1 = require("./pristine-error-code.enum");
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/** 404. Resource doesn't exist. CLI exit `ExitCode.Error` (1). */
+class NotFoundError extends pristine_error_1.PristineError {
+    constructor(message, options = {}) {
+        super(message, Object.assign({ code: pristine_error_code_enum_1.PristineErrorCode.NotFound, httpStatus: 404, exitCode: exit_code_enum_1.ExitCode.Error, kind: pristine_error_kind_enum_1.PristineErrorKind.UserError }, options));
+    }
+}
+exports.NotFoundError = NotFoundError;
+//# sourceMappingURL=not-found.error.js.map

package/dist/lib/cjs/errors/not-found.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"not-found.error.js","sourceRoot":"","sources":["../../../../src/errors/not-found.error.ts"],"names":[],"mappings":";;;AAAA,qDAA0C;AAC1C,qDAA+C;AAC/C,yEAA6D;AAC7D,yEAA6D;AAK7D,kEAAkE;AAClE,MAAa,aAAc,SAAQ,8BAAa;IAC9C,YAAY,OAAe,EAAE,UAA2B,EAAE;QACxD,KAAK,CAAC,OAAO,kBACX,IAAI,EAAE,4CAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,EAAE,yBAAQ,CAAC,KAAK,EAC3E,IAAI,EAAE,4CAAiB,CAAC,SAAS,IAC9B,OAAO,EACV,CAAC;IACL,CAAC;CACF;AARD,sCAQC"}

package/dist/lib/cjs/errors/pristine-error-code.enum.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PristineErrorCode = void 0;
+/**
+ * Standard error-code catalog used across the framework. Each value is a `SCREAMING_SNAKE_CASE`
+ * slug surfaced in the HTTP response body (`{"code": ...}`) and on CLI stderr (`✗ CODE: ...`).
+ *
+ * **Use the enum members for framework-standard cases.** Consumers can add their own
+ * domain-specific codes by passing a plain string — `PristineErrorOptions.code` is typed
+ * `PristineErrorCode | string` so both the enum and free-form strings get autocomplete-
+ * friendly type checking.
+ *
+ * ```ts
+ * throw new PristineError("Token expired", {
+ *   code: "TOKEN_EXPIRED",                       // consumer-defined code
+ *   httpStatus: 401,
+ * });
+ *
+ * throw new PristineError("Item missing", {
+ *   code: PristineErrorCode.NotFound,            // framework-standard code
+ *   httpStatus: 404,
+ * });
+ * ```
+ */
+var PristineErrorCode;
+(function (PristineErrorCode) {
+    PristineErrorCode["BadRequest"] = "BAD_REQUEST";
+    PristineErrorCode["Unauthorized"] = "UNAUTHORIZED";
+    PristineErrorCode["Forbidden"] = "FORBIDDEN";
+    PristineErrorCode["NotFound"] = "NOT_FOUND";
+    PristineErrorCode["Conflict"] = "CONFLICT";
+    PristineErrorCode["ValidationFailed"] = "VALIDATION_FAILED";
+    PristineErrorCode["ConfigError"] = "CONFIG_ERROR";
+    PristineErrorCode["UsageError"] = "USAGE_ERROR";
+    PristineErrorCode["InternalError"] = "INTERNAL_ERROR";
+})(PristineErrorCode || (exports.PristineErrorCode = PristineErrorCode = {}));
+//# sourceMappingURL=pristine-error-code.enum.js.map

package/dist/lib/cjs/errors/pristine-error-code.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-code.enum.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-code.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,IAAY,iBAUX;AAVD,WAAY,iBAAiB;IAC3B,+CAAiC,CAAA;IACjC,kDAAkC,CAAA;IAClC,4CAA+B,CAAA;IAC/B,2CAA+B,CAAA;IAC/B,0CAA8B,CAAA;IAC9B,2DAAuC,CAAA;IACvC,iDAAkC,CAAA;IAClC,+CAAiC,CAAA;IACjC,qDAAoC,CAAA;AACtC,CAAC,EAVW,iBAAiB,iCAAjB,iBAAiB,QAU5B"}

package/dist/lib/cjs/errors/pristine-error-kind.enum.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PristineErrorKind = void 0;
+/**
+ * Categorizes a `PristineError` by who caused it. Replaces the older `expected: boolean`
+ * field, whose meaning ("expected by whom?") wasn't self-explanatory.
+ *
+ * The kind drives how the channel reporters render the error in production mode:
+ *
+ * - `UserError`: caller did something wrong. Message is safe to expose verbatim;
+ *   structured details surface as-is. HTTP responses use the carried `httpStatus`
+ *   (typically 4xx). CLI stderr shows the message and details.
+ *
+ * - `SystemError`: framework or downstream bug — not the caller's fault. In production
+ *   mode the message is replaced with a generic "Internal Server Error" / "Internal Error"
+ *   so internal details never leak to clients. Stack and cause chain are still logged
+ *   internally via the LogHandler for operators. In development mode (`PRISTINE_ENV=dev`)
+ *   the full message surfaces.
+ *
+ * Default is `UserError` — most thrown errors in framework and application code are caller-
+ * induced. `PristineError.from(unknown)` marks raw `Error` and non-Error throws as
+ * `SystemError` since they didn't opt into the typed contract.
+ */
+var PristineErrorKind;
+(function (PristineErrorKind) {
+    PristineErrorKind["UserError"] = "user-error";
+    PristineErrorKind["SystemError"] = "system-error";
+})(PristineErrorKind || (exports.PristineErrorKind = PristineErrorKind = {}));
+//# sourceMappingURL=pristine-error-kind.enum.js.map

package/dist/lib/cjs/errors/pristine-error-kind.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-kind.enum.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-kind.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,IAAY,iBAGX;AAHD,WAAY,iBAAiB;IAC3B,6CAA0B,CAAA;IAC1B,iDAA4B,CAAA;AAC9B,CAAC,EAHW,iBAAiB,iCAAjB,iBAAiB,QAG5B"}

package/dist/lib/cjs/errors/pristine-error-options.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=pristine-error-options.interface.js.map

package/dist/lib/cjs/errors/pristine-error-options.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine-error-options.interface.js","sourceRoot":"","sources":["../../../../src/errors/pristine-error-options.interface.ts"],"names":[],"mappings":""}

package/dist/lib/cjs/errors/pristine.error.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PristineError = void 0;
+const pristine_error_kind_enum_1 = require("./pristine-error-kind.enum");
+/**
+ * Single error base for the entire framework. Replaces the old `LoggableError` +
+ * `HttpError` + ad-hoc subclass hierarchy.
+ *
+ * **What it gives you**:
+ * - A structured `options` bag (`code`, `httpStatus`, `exitCode`, `details`, `cause`,
+ *   `kind`) read by both the HTTP and CLI channel reporters.
+ * - Automatic `error.name = ClassName` for subclasses.
+ * - Automatic prototype-chain fix via `new.target.prototype` — subclasses never need to
+ *   repeat the `Object.setPrototypeOf(this, FooError.prototype)` incantation, AND
+ *   `instanceof` works correctly for direct/standard-library/custom subclasses at any
+ *   depth (verified by spec).
+ * - Standard `Error.cause` propagation (Node 16.9+ native).
+ *
+ * **Subclass form** when a named class makes `instanceof` checks read better:
+ *
+ * ```ts
+ * export class TokenExpiredError extends UnauthorizedError {
+ *   constructor(tokenId: string) {
+ *     super("The token has expired", {
+ *       code: "TOKEN_EXPIRED",
+ *       details: { tokenId },
+ *     });
+ *   }
+ * }
+ * // ...
+ * try { ... }
+ * catch (e) { if (e instanceof TokenExpiredError) ... }   // works.
+ * ```
+ *
+ * **Direct form** when the call site self-documents:
+ *
+ * ```ts
+ * throw new PristineError(`User '${id}' not found`, {
+ *   code: PristineErrorCode.NotFound,
+ *   httpStatus: 404,
+ *   details: { resource: "User", id },
+ * });
+ * ```
+ *
+ * **Re-throw with enrichment** when catching, adding context, and re-throwing. Use the
+ * standard `cause` chain rather than mutating the original — this preserves the original
+ * error's identity for tooling that walks `error.cause`:
+ *
+ * ```ts
+ * try { await dispatcher.dispatch(event); }
+ * catch (cause) {
+ *   throw new PristineError("Event dispatch failed", {
+ *     code: "EVENT_DISPATCH_FAILED",
+ *     kind: PristineErrorKind.SystemError,
+ *     cause,
+ *     details: { eventId: event.id },
+ *   });
+ * }
+ * ```
+ */
+class PristineError extends Error {
+    constructor(message, options = {}) {
+        // Use the standard Error.cause slot so any tooling that knows the standard chain
+        // (debuggers, V8's default Error formatting, OpenTelemetry's exception recording)
+        // picks it up automatically. We don't need a custom `originalError` slot.
+        super(message, { cause: options.cause });
+        // `new.target` is the actual class being constructed (subclass or PristineError
+        // itself). Using it for both `name` and `setPrototypeOf` means subclasses never need
+        // to repeat the boilerplate, and `instanceof` works correctly at every depth.
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+        // `kind: UserError` is the default — most thrown errors are caller-induced. System
+        // errors get marked explicitly via `kind: PristineErrorKind.SystemError` (or by
+        // `PristineError.from` for unknown throws).
+        this.options = Object.assign({ kind: pristine_error_kind_enum_1.PristineErrorKind.UserError }, options);
+    }
+    /**
+     * Normalizes any thrown value into a `PristineError`. The chokepoint that every channel
+     * reporter funnels through before rendering, so the reporters never need to handle
+     * unknown shapes.
+     *
+     * - `PristineError` instances pass through unchanged.
+     * - `Error` instances are wrapped with `kind: SystemError` and propagated as `cause` —
+     *   the wrapper preserves the original message and stack for `mode === Development`
+     *   rendering.
+     * - Anything else (strings, numbers, `throw {someObject}`) is coerced via `String(...)`
+     *   into a message with `kind: SystemError`.
+     *
+     * The standard `Error.cause` chain is preserved: if the input has a `cause`, it stays
+     * on the wrapper (which itself has the input as its cause), so a debugger walking
+     * `error.cause.cause.cause` sees the full history.
+     */
+    static from(error) {
+        if (error instanceof PristineError) {
+            return error;
+        }
+        if (error instanceof Error) {
+            return new PristineError(error.message, {
+                cause: error,
+                kind: pristine_error_kind_enum_1.PristineErrorKind.SystemError,
+            });
+        }
+        return new PristineError(String(error), {
+            kind: pristine_error_kind_enum_1.PristineErrorKind.SystemError,
+        });
+    }
+}
+exports.PristineError = PristineError;
+//# sourceMappingURL=pristine.error.js.map

package/dist/lib/cjs/errors/pristine.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pristine.error.js","sourceRoot":"","sources":["../../../../src/errors/pristine.error.ts"],"names":[],"mappings":";;;AAAA,yEAA6D;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAa,aAAc,SAAQ,KAAK;IAGtC,YAAY,OAAe,EAAE,UAAgC,EAAE;QAC7D,iFAAiF;QACjF,kFAAkF;QAClF,0EAA0E;QAC1E,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEzC,gFAAgF;QAChF,qFAAqF;QACrF,8EAA8E;QAC9E,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAElD,mFAAmF;QACnF,gFAAgF;QAChF,4CAA4C;QAC5C,IAAI,CAAC,OAAO,mBAAK,IAAI,EAAE,4CAAiB,CAAC,SAAS,IAAK,OAAO,CAAE,CAAC;IACnE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,IAAI,CAAC,KAAc;QACxB,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,OAAO,IAAI,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE;gBACtC,KAAK,EAAE,KAAK;gBACZ,IAAI,EAAE,4CAAiB,CAAC,WAAW;aACpC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;YACtC,IAAI,EAAE,4CAAiB,CAAC,WAAW;SACpC,CAAC,CAAC;IACL,CAAC;CACF;AAnDD,sCAmDC"}