@cosmicdrift/kumiko-framework 0.1.0

package/src/errors/serialize.ts

@@ -0,0 +1,136 @@
+import type { KumikoError } from "./kumiko-error";
+
+// Wire format every 4xx/5xx response must match. The API routes use this
+// verbatim; keep it stable — the client SDK keys off these field names.
+//
+// `docsUrl` is the deep-link for self-service: default web/mobile renderers
+// show a "Mehr erfahren →" link pointing here. Computed from `details.reason`
+// (when set) or fallback to `code`. Always present, even when `details` is
+// stripped from the response (e.g. internal_error in production).
+export type ErrorResponseBody = {
+  readonly error: {
+    readonly code: string;
+    readonly i18nKey: string;
+    readonly i18nParams?: Readonly<Record<string, unknown>>;
+    readonly message: string;
+    readonly details?: unknown;
+    readonly docsUrl: string;
+    readonly requestId?: string;
+    readonly timestamp: string;
+  };
+};
+
+// InternalError deliberately omits `details` from the response in production,
+// because that field often carries the internal cause. The log still has
+// everything (see buildErrorLog).
+//
+// In dev/test the cause is exposed in the response body to make debugging
+// possible — without this, a crash in a handler comes back as a bare
+// "internal error" and developers have to add try/catch + UnprocessableError
+// just to see what went wrong (real footgun, not theoretical). The exposure
+// is gated on NODE_ENV !== "production" so a misconfigured prod deploy
+// doesn't leak stack traces over the wire.
+const CODES_WITHOUT_CLIENT_DETAILS = new Set(["internal_error"]);
+
+const isProductionEnv = (): boolean => process.env["NODE_ENV"] === "production";
+
+// Snapshot of the cause chain (top-most error only) suitable for inclusion
+// in dev-mode error responses. Stack is truncated to keep the body small.
+type DevCauseDetail = {
+  readonly causeName?: string;
+  readonly causeMessage?: string;
+  readonly causeStack?: string;
+};
+
+function devCauseDetail(cause: unknown): DevCauseDetail | undefined {
+  if (!(cause instanceof Error)) return undefined;
+  return {
+    causeName: cause.name,
+    causeMessage: cause.message,
+    ...(cause.stack && { causeStack: cause.stack.split("\n").slice(0, 8).join("\n") }),
+  };
+}
+
+export function serializeError(err: KumikoError, requestId?: string): ErrorResponseBody {
+  const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && isProductionEnv();
+  const exposeDeclaredDetails = err.details !== undefined && !stripped;
+
+  // For internal_error in dev/test, surface the cause chain so the
+  // response body has something useful instead of "internal error".
+  // Priority: declared details (if any) win over the cause snapshot —
+  // a hand-set details on InternalError should not be replaced.
+  const detailsForResponse = (() => {
+    if (exposeDeclaredDetails) return err.details;
+    if (CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && !isProductionEnv()) {
+      return devCauseDetail(err.cause);
+    }
+    return undefined;
+  })();
+
+  return {
+    error: {
+      code: err.code,
+      i18nKey: err.i18nKey,
+      ...(err.i18nParams && { i18nParams: err.i18nParams }),
+      message: err.message,
+      ...(detailsForResponse !== undefined && { details: detailsForResponse }),
+      docsUrl: err.docsUrl,
+      ...(requestId && { requestId }),
+      timestamp: new Date().toISOString(),
+    },
+  };
+}
+
+// Full forensic shape — stack, cause chain, details — meant for the log
+// emitter. Callers should pipe this through a sensitive-value filter before it
+// leaves the process (out of scope for v1).
+export type ErrorLogEntry = {
+  readonly name: string;
+  readonly code: string;
+  readonly httpStatus: number;
+  readonly message: string;
+  readonly i18nKey: string;
+  readonly details?: unknown;
+  readonly stack?: string;
+  readonly cause?: CauseSnapshot;
+};
+
+export function buildErrorLog(err: KumikoError): ErrorLogEntry {
+  return {
+    name: err.name,
+    code: err.code,
+    httpStatus: err.httpStatus,
+    message: err.message,
+    i18nKey: err.i18nKey,
+    ...(err.details !== undefined && { details: err.details }),
+    ...(err.stack && { stack: err.stack }),
+    ...(err.cause !== undefined && { cause: serializeCause(err.cause) }),
+  };
+}
+
+// Recursive cause snapshot — follows error.cause.cause... until the chain
+// ends or a non-Error appears. Hard cap at 10 levels to avoid pathological
+// cyclic cause chains hanging the serializer.
+type CauseSnapshot = {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly cause?: CauseSnapshot;
+};
+
+const MAX_CAUSE_DEPTH = 10;
+
+function serializeCause(cause: unknown, depth = 0): CauseSnapshot {
+  if (depth >= MAX_CAUSE_DEPTH) {
+    return { name: "CauseChainTruncated", message: `depth >= ${MAX_CAUSE_DEPTH}` };
+  }
+  if (cause instanceof Error) {
+    return {
+      name: cause.name,
+      message: cause.message,
+      ...(cause.stack && { stack: cause.stack }),
+      ...(cause.cause !== undefined && { cause: serializeCause(cause.cause, depth + 1) }),
+    };
+  }
+  return { name: "NonError", message: String(cause) };
+}

package/src/errors/transition-details.ts

@@ -0,0 +1,30 @@
+// Gemeinsame Detail-Shape für invalid_transition-Errors. Beide Pfade
+// (state-machine.assertTransition + failTransition) müssen identisch
+// strukturierte Details liefern, sonst können HTTP-Clients den 422-Body
+// nicht uniform parsen — `from`/`to`/`allowed` sind die strukturierten
+// Felder, `message` ist die menschen-lesbare Form.
+//
+// Kein Re-Export von "validTargets" (CSV-string) mehr — wer CSV will
+// baut's via `allowed.join(", ")`. Eine Shape, ein Vertrag.
+
+export type InvalidTransitionDetails = {
+  readonly from: string;
+  readonly to: string;
+  readonly allowed: readonly string[];
+  readonly message: string;
+};
+
+export function buildInvalidTransitionDetails(
+  from: string,
+  to: string,
+  allowed: readonly string[],
+): InvalidTransitionDetails {
+  return {
+    from,
+    to,
+    allowed,
+    message: `Invalid transition: "${from}" → "${to}". Allowed from "${from}": ${
+      allowed.length > 0 ? allowed.join(", ") : "none"
+    }`,
+  };
+}

package/src/errors/write-error-info.ts

@@ -0,0 +1,123 @@
+import { NotFoundError, UnprocessableError } from "./classes";
+import { KumikoError } from "./kumiko-error";
+import { FrameworkReasons } from "./reasons";
+import { buildInvalidTransitionDetails } from "./transition-details";
+
+// Plain, JSON-serializable snapshot of a KumikoError for use on the write-path
+// (WriteResult.error, BatchResult.error). The dispatcher stores results under
+// an idempotency key — a KumikoError instance wouldn't round-trip through
+// JSON, so we keep structural data only and rebuild the instance on demand
+// via reraiseAsKumikoError when we need to throw upstream again.
+export type WriteErrorInfo = {
+  readonly code: string;
+  readonly httpStatus: number;
+  readonly i18nKey: string;
+  readonly i18nParams?: Readonly<Record<string, unknown>>;
+  readonly message: string;
+  readonly details?: unknown;
+};
+
+// The failure half of WriteResult — `{ isSuccess: false } + error`. Named
+// so the three write-failure factories below and WriteResult share one
+// shape instead of restating it. Not generic: the error carries zero data,
+// so there's nothing for the caller to narrow.
+export type WriteFailure = {
+  readonly isSuccess: false;
+  readonly error: WriteErrorInfo;
+};
+
+// Convenience for call sites that return a failed WriteResult. Keeps the
+// pattern `return writeFailure(new NotFoundError(...))` compact so handlers
+// and the CrudExecutor don't need to spell out the shape each time.
+export function writeFailure(err: KumikoError): WriteFailure {
+  return { isSuccess: false, error: toWriteErrorInfo(err) };
+}
+
+// Focused convenience for the two most common handler failures: "X not found"
+// (typed 404) and "business rule violated: REASON" (typed 422 with the reason
+// string surfaced in details.reason). Reach for the concrete classes when you
+// need richer payload — these two cover the bulk of handler code.
+export function failNotFound(entity: string, id?: number | string): WriteFailure {
+  return writeFailure(new NotFoundError(entity, id));
+}
+
+export function failUnprocessable(
+  reason: string,
+  details?: Readonly<Record<string, unknown>>,
+): WriteFailure {
+  return writeFailure(new UnprocessableError(reason, details ? { details } : undefined));
+}
+
+/**
+ * Convenience für State-Transition-Rejects: produces a WriteFailure mit
+ * reason="invalid_transition" + strukturiertem `from`/`to`/`allowed`-
+ * Detail-Block + lesbarer message. Pattern hat sich in publicstatus-
+ * Maintenance + bestehenden state-machine-Helpers wiederholt — Helper
+ * sammelt das in einem Aufruf statt drei manuelle Detail-Felder.
+ *
+ * `allowed` ist typisch `MAINTENANCE_TRANSITIONS.allowedFrom(from)`.
+ */
+export function failTransition(from: string, to: string, allowed: readonly string[]): WriteFailure {
+  return writeFailure(
+    new UnprocessableError(FrameworkReasons.invalidTransition, {
+      i18nKey: "errors.invalidTransition",
+      details: buildInvalidTransitionDetails(from, to, allowed),
+    }),
+  );
+}
+
+export function toWriteErrorInfo(err: KumikoError): WriteErrorInfo {
+  // In dev/test surface the cause-snapshot through `details` so the
+  // HTTP response carries something useful. Without this, internal_error
+  // crashes round-trip through WriteErrorInfo (no cause field) and come
+  // back to the client as a bare `{ message: "internal error" }` —
+  // identical user-experience to a misconfigured prod, just slower
+  // because the dev has to add try/catch + console.log to find the
+  // actual stack. Same gating as serializeError: NODE_ENV !== production.
+  const causeDetails =
+    err.details === undefined && err.code === "internal_error" && err.cause instanceof Error
+      ? process.env["NODE_ENV"] !== "production"
+        ? {
+            causeName: err.cause.name,
+            causeMessage: err.cause.message,
+            ...(err.cause.stack && {
+              causeStack: err.cause.stack.split("\n").slice(0, 8).join("\n"),
+            }),
+          }
+        : undefined
+      : undefined;
+  const effectiveDetails = err.details ?? causeDetails;
+  return {
+    code: err.code,
+    httpStatus: err.httpStatus,
+    i18nKey: err.i18nKey,
+    message: err.message,
+    ...(err.i18nParams && { i18nParams: err.i18nParams }),
+    ...(effectiveDetails !== undefined && { details: effectiveDetails }),
+  };
+}
+
+// Reconstitutes an error from WriteErrorInfo so command() (throw-based) can
+// keep raising a KumikoError after the batch returned structural data. The
+// concrete subclass identity is lost here — callers can still read code /
+// httpStatus / details but `instanceof NotFoundError` won't work. That's OK:
+// the HTTP layer keys off code + httpStatus, not class identity.
+export function reraiseAsKumikoError(info: WriteErrorInfo): KumikoError {
+  return new ReraisedError(info);
+}
+
+class ReraisedError extends KumikoError {
+  readonly code: string;
+  readonly httpStatus: number;
+
+  constructor(info: WriteErrorInfo) {
+    super({
+      message: info.message,
+      i18nKey: info.i18nKey,
+      ...(info.i18nParams && { i18nParams: info.i18nParams }),
+      ...(info.details !== undefined && { details: info.details }),
+    });
+    this.code = info.code;
+    this.httpStatus = info.httpStatus;
+  }
+}

package/src/errors/zod-bridge.ts

@@ -0,0 +1,49 @@
+import type { ZodError, ZodIssue } from "zod";
+import { ValidationError, type ValidationFieldIssue } from "./classes";
+
+// Zod issues carry a .code and sometimes issue-specific params (min, max, etc).
+// We surface those under `params` so the client can render "must be at least N"
+// without re-parsing the message.
+//
+// Keep this list in sync with the issue-code matrix in classes.test.ts — that
+// test is what catches Zod upgrades introducing new param names.
+const ISSUE_PARAM_KEYS = [
+  "minimum",
+  "maximum",
+  "expected",
+  "received",
+  "type",
+  "inclusive",
+  "exact",
+  "keys",
+  // Zod 4 additions:
+  "format", // invalid_format (email, url, uuid, regex, ...)
+  "divisor", // not_multiple_of
+  "values", // invalid_value (enum / literal)
+  "pattern", // invalid_format with regex
+] as const;
+
+export function validationErrorFromZod(error: ZodError): ValidationError {
+  const fields = error.issues.map<ValidationFieldIssue>((issue) => {
+    const params = extractIssueParams(issue);
+    return {
+      path: issue.path.map(String).join(".") || "(root)",
+      code: issue.code,
+      i18nKey: `errors.validation.${issue.code}`,
+      ...(params && { params }),
+    };
+  });
+  return new ValidationError({ fields }, { cause: error });
+}
+
+function extractIssueParams(issue: ZodIssue): Readonly<Record<string, unknown>> | undefined {
+  // ZodIssue is a discriminated union with variant-specific params (minimum,
+  // maximum, expected, …); reading them generically requires widening since
+  // the union members don't share an index signature.
+  const out: Record<string, unknown> = {};
+  const bag = issue as unknown as Record<string, unknown>; // @cast-boundary zod-issue
+  for (const key of ISSUE_PARAM_KEYS) {
+    if (bag[key] !== undefined) out[key] = bag[key];
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}