@crewhaus/errors 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crewhaus/errors",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Typed error hierarchy shared across factory layers",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/errors"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/errors#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CompilerError,
+  ConfigError,
+  CrewhausError,
+  McpConnectionError,
+  McpError,
+  McpProtocolError,
+  RuntimeError,
+  SpecParseError,
+} from "./index";
+
+describe("CrewhausError", () => {
+  test("extends Error and exposes a code", () => {
+    const err = new CrewhausError("config", "boom");
+    expect(err).toBeInstanceOf(Error);
+    expect(err).toBeInstanceOf(CrewhausError);
+    expect(err.code).toBe("config");
+    expect(err.message).toBe("boom");
+    expect(err.name).toBe("CrewhausError");
+  });
+
+  test("toJSON serializes message and code", () => {
+    const err = new CrewhausError("runtime", "oops");
+    expect(err.toJSON()).toEqual({
+      name: "CrewhausError",
+      code: "runtime",
+      message: "oops",
+      cause: undefined,
+    });
+  });
+
+  test("preserves cause via Error.cause", () => {
+    const root = new Error("root");
+    const err = new CompilerError("could not lower", root);
+    expect(err.cause).toBe(root);
+  });
+
+  test("toJSON serializes a plain Error cause", () => {
+    const root = new Error("root");
+    const err = new CompilerError("compile failed", root);
+    expect(err.toJSON().cause).toEqual({ name: "Error", message: "root" });
+  });
+
+  test("toJSON recursively serializes a CrewhausError cause", () => {
+    const inner = new SpecParseError("bad yaml");
+    const outer = new CompilerError("compile failed", inner);
+    expect(outer.toJSON().cause).toEqual({
+      name: "SpecParseError",
+      code: "spec_parse",
+      message: "bad yaml",
+      cause: undefined,
+    });
+  });
+
+  test("toJSON stringifies non-Error causes", () => {
+    const err = new RuntimeError("x", "string-cause");
+    expect(err.toJSON().cause).toEqual({ message: "string-cause" });
+  });
+});
+
+describe("subclasses", () => {
+  test("each subclass tags itself with the right code", () => {
+    expect(new SpecParseError("x").code).toBe("spec_parse");
+    expect(new CompilerError("x").code).toBe("compiler");
+    expect(new RuntimeError("x").code).toBe("runtime");
+    expect(new ConfigError("x").code).toBe("config");
+    expect(new McpError("x").code).toBe("mcp");
+    expect(new McpConnectionError("x").code).toBe("mcp");
+    expect(new McpProtocolError("x").code).toBe("mcp");
+  });
+
+  test("each subclass has a stable name (for instanceof / log filtering)", () => {
+    expect(new SpecParseError("x").name).toBe("SpecParseError");
+    expect(new CompilerError("x").name).toBe("CompilerError");
+    expect(new RuntimeError("x").name).toBe("RuntimeError");
+    expect(new ConfigError("x").name).toBe("ConfigError");
+    expect(new McpError("x").name).toBe("McpError");
+    expect(new McpConnectionError("x").name).toBe("McpConnectionError");
+    expect(new McpProtocolError("x").name).toBe("McpProtocolError");
+  });
+
+  test("subclasses are instanceof their parent", () => {
+    expect(new SpecParseError("x")).toBeInstanceOf(CrewhausError);
+    expect(new CompilerError("x")).toBeInstanceOf(CrewhausError);
+    expect(new RuntimeError("x")).toBeInstanceOf(CrewhausError);
+    expect(new ConfigError("x")).toBeInstanceOf(CrewhausError);
+    expect(new McpError("x")).toBeInstanceOf(CrewhausError);
+    expect(new McpConnectionError("x")).toBeInstanceOf(McpError);
+    expect(new McpProtocolError("x")).toBeInstanceOf(McpError);
+  });
+
+  test("McpConnectionError serializes via toJSON", () => {
+    const err = new McpConnectionError("connection lost", new Error("ECONNREFUSED"));
+    expect(err.toJSON()).toEqual({
+      name: "McpConnectionError",
+      code: "mcp",
+      message: "connection lost",
+      cause: { name: "Error", message: "ECONNREFUSED" },
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Typed error hierarchy for factory.
+ * Catalog F-foundations (`error-types`) — every later layer imports this
+ * for structured error reporting instead of throwing raw `Error`s.
+ *
+ * Each error carries a stable `code` for programmatic dispatch and serializes
+ * its full cause chain via `toJSON()` for the logging layer.
+ */
+
+export type ErrorCode =
+  | "spec_parse"
+  | "compiler"
+  | "runtime"
+  | "config"
+  | "tool"
+  | "mcp"
+  | "adapter"
+  | "channel";
+
+export type SerializedError = {
+  name: string;
+  code: ErrorCode;
+  message: string;
+  cause?: SerializedError | { name?: string; message: string };
+};
+
+export class CrewhausError extends Error {
+  override readonly name: string = "CrewhausError";
+  readonly code: ErrorCode;
+
+  constructor(code: ErrorCode, message: string, cause?: unknown) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.code = code;
+  }
+
+  toJSON(): SerializedError {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      cause: serializeCause(this.cause),
+    };
+  }
+}
+
+function serializeCause(cause: unknown): SerializedError["cause"] {
+  if (cause === undefined) return undefined;
+  if (cause instanceof CrewhausError) return cause.toJSON();
+  if (cause instanceof Error) return { name: cause.name, message: cause.message };
+  return { message: String(cause) };
+}
+
+export class SpecParseError extends CrewhausError {
+  override readonly name = "SpecParseError";
+  constructor(message: string, cause?: unknown) {
+    super("spec_parse", message, cause);
+  }
+}
+
+export class CompilerError extends CrewhausError {
+  override readonly name = "CompilerError";
+  constructor(message: string, cause?: unknown) {
+    super("compiler", message, cause);
+  }
+}
+
+export class RuntimeError extends CrewhausError {
+  override readonly name = "RuntimeError";
+  constructor(message: string, cause?: unknown) {
+    super("runtime", message, cause);
+  }
+}
+
+export class ConfigError extends CrewhausError {
+  override readonly name = "ConfigError";
+  constructor(message: string, cause?: unknown) {
+    super("config", message, cause);
+  }
+}
+
+export class McpError extends CrewhausError {
+  override readonly name: string = "McpError";
+  constructor(message: string, cause?: unknown) {
+    super("mcp", message, cause);
+  }
+}
+
+export class McpConnectionError extends McpError {
+  override readonly name = "McpConnectionError";
+}
+
+export class McpProtocolError extends McpError {
+  override readonly name = "McpProtocolError";
+}
+
+/**
+ * Section 17 — base for all model-provider adapter failures (auth, request
+ * marshalling, stream parsing, network). Carries `providerId` so callers can
+ * branch on which adapter raised; `cause` keeps the underlying SDK error
+ * accessible via `toJSON()` for the trace/log layer.
+ */
+export class AdapterError extends CrewhausError {
+  override readonly name: string = "AdapterError";
+  readonly providerId: string;
+  constructor(providerId: string, message: string, cause?: unknown) {
+    super("adapter", message, cause);
+    this.providerId = providerId;
+  }
+}
+
+/**
+ * Section 17 — missing or invalid credentials for a model provider. Surfaces
+ * with a setup hint pointing at the relevant env var.
+ */
+export class ProviderAuthError extends AdapterError {
+  override readonly name = "ProviderAuthError";
+}