@adhd/apigen-base-errors 0.1.1

package/README.md

@@ -0,0 +1,19 @@
+# @adhd/apigen-base-errors
+
+Canonical error model for apigen — one set of error codes mapped to each transport's status
+convention (HTTP, gRPC, CLI exit, MCP), plus streaming-error phase helpers. Pure TypeScript
+(**platform: shared**).
+
+Part of [apigen](../README.md).
+
+## Public API
+
+```ts
+import { ERROR_CODES, HTTP_STATUS, GRPC_CODE, CLI_EXIT_CODE, MCP_ERROR_KIND, statusMaps, ApiError, toStreamingError, isBeforeFirstChunk, isAfterFirstChunk } from '@adhd/apigen-base-errors';
+```
+
+- **`ERROR_CODES` / `ApiErrorCode`** — the canonical code set.
+- **`HTTP_STATUS` / `GRPC_CODE` / `CLI_EXIT_CODE` / `MCP_ERROR_KIND` / `statusMaps`** —
+  per-transport mappings so every surface reports the same error consistently.
+- **`ApiError`** — the error carrier; the **streaming helpers** classify before/after-first-chunk
+  errors for correct mid-stream reporting.

package/index.d.ts

@@ -0,0 +1 @@
+export { ERROR_CODES, type ApiErrorCode, HTTP_STATUS, GRPC_CODE, CLI_EXIT_CODE, MCP_ERROR_KIND, statusMaps, ApiError, isApiError, type StreamingPhase, type BeforeFirstChunkError, type AfterFirstChunkError, type StreamingErrorCarrier, toStreamingError, isBeforeFirstChunk, isAfterFirstChunk, } from './lib/errors';

package/index.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=["invalid_argument","unauthenticated","permission_denied","not_found","internal"],i={invalid_argument:400,unauthenticated:401,permission_denied:403,not_found:404,internal:500},o={invalid_argument:"INVALID_ARGUMENT",unauthenticated:"UNAUTHENTICATED",permission_denied:"PERMISSION_DENIED",not_found:"NOT_FOUND",internal:"INTERNAL"},s={invalid_argument:2,unauthenticated:3,permission_denied:3,not_found:4,internal:1},u={invalid_argument:"error",unauthenticated:"error",permission_denied:"error",not_found:"error",internal:"error"},d={http:i,grpc:o,cli:s,mcp:u};class c extends Error{constructor(n,e,a){super(e),this.name="ApiError",this.code=n,this.details=a,Object.setPrototypeOf(this,new.target.prototype)}toJSON(){const n={code:this.code,message:this.message};return this.details!==void 0&&(n.details=this.details),n}}function _(t){return typeof t=="object"&&t!==null&&t.name==="ApiError"&&r.includes(t.code)&&typeof t.toJSON=="function"}function E(t,n,e=0){return t==="before-first-chunk"?{phase:t,error:n}:{phase:t,error:n,chunksDelivered:e}}function f(t){return t.phase==="before-first-chunk"}function p(t){return t.phase==="after-first-chunk"}exports.ApiError=c;exports.CLI_EXIT_CODE=s;exports.ERROR_CODES=r;exports.GRPC_CODE=o;exports.HTTP_STATUS=i;exports.MCP_ERROR_KIND=u;exports.isAfterFirstChunk=p;exports.isApiError=_;exports.isBeforeFirstChunk=f;exports.statusMaps=d;exports.toStreamingError=E;

package/index.mjs

@@ -0,0 +1,74 @@
+const r = [
+  "invalid_argument",
+  "unauthenticated",
+  "permission_denied",
+  "not_found",
+  "internal"
+], o = {
+  invalid_argument: 400,
+  unauthenticated: 401,
+  permission_denied: 403,
+  not_found: 404,
+  internal: 500
+}, s = {
+  invalid_argument: "INVALID_ARGUMENT",
+  unauthenticated: "UNAUTHENTICATED",
+  permission_denied: "PERMISSION_DENIED",
+  not_found: "NOT_FOUND",
+  internal: "INTERNAL"
+}, u = {
+  invalid_argument: 2,
+  unauthenticated: 3,
+  permission_denied: 3,
+  not_found: 4,
+  internal: 1
+}, a = {
+  invalid_argument: "error",
+  unauthenticated: "error",
+  permission_denied: "error",
+  not_found: "error",
+  internal: "error"
+}, d = {
+  http: o,
+  grpc: s,
+  cli: u,
+  mcp: a
+};
+class c extends Error {
+  constructor(n, e, i) {
+    super(e), this.name = "ApiError", this.code = n, this.details = i, Object.setPrototypeOf(this, new.target.prototype);
+  }
+  /** Serialise to a plain object suitable for JSON transport. */
+  toJSON() {
+    const n = {
+      code: this.code,
+      message: this.message
+    };
+    return this.details !== void 0 && (n.details = this.details), n;
+  }
+}
+function _(t) {
+  return typeof t == "object" && t !== null && t.name === "ApiError" && r.includes(t.code) && typeof t.toJSON == "function";
+}
+function f(t, n, e = 0) {
+  return t === "before-first-chunk" ? { phase: t, error: n } : { phase: t, error: n, chunksDelivered: e };
+}
+function p(t) {
+  return t.phase === "before-first-chunk";
+}
+function h(t) {
+  return t.phase === "after-first-chunk";
+}
+export {
+  c as ApiError,
+  u as CLI_EXIT_CODE,
+  r as ERROR_CODES,
+  s as GRPC_CODE,
+  o as HTTP_STATUS,
+  a as MCP_ERROR_KIND,
+  h as isAfterFirstChunk,
+  _ as isApiError,
+  p as isBeforeFirstChunk,
+  d as statusMaps,
+  f as toStreamingError
+};

package/lib/errors.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @adhd/apigen-base-errors
+ *
+ * Canonical error taxonomy for apigen — §9.1 of the apigen SPEC.
+ *
+ * Exports:
+ *  - `ApiErrorCode`   — the gRPC-style canonical code set (string union + const object)
+ *  - `ApiError`       — the thrown error class carrying code + message + details
+ *  - `HTTP_STATUS`    — code → HTTP status code map
+ *  - `GRPC_CODE`      — code → gRPC status code name map
+ *  - `CLI_EXIT_CODE`  — code → CLI process exit code map
+ *  - `MCP_ERROR_KIND` — code → MCP error shape indicator ('error')
+ *  - `statusMaps`     — convenience bundle of all four maps
+ *  - `StreamingPhase` — 'before-first-chunk' | 'after-first-chunk' discriminant
+ *  - `StreamingErrorCarrier` — discriminated union: how an in-flight stream delivers a terminal error
+ *  - `toStreamingError` — factory that wraps an ApiError into the correct carrier for the phase
+ */
+/** The five gRPC-style canonical error codes recognised by apigen. */
+export declare const ERROR_CODES: readonly ["invalid_argument", "unauthenticated", "permission_denied", "not_found", "internal"];
+/** String-union type for the canonical error codes. */
+export type ApiErrorCode = (typeof ERROR_CODES)[number];
+/** Maps each canonical code to its HTTP status code. */
+export declare const HTTP_STATUS: Record<ApiErrorCode, number>;
+/** Maps each canonical code to its gRPC status name. */
+export declare const GRPC_CODE: Record<ApiErrorCode, string>;
+/** Maps each canonical code to its CLI process exit code. */
+export declare const CLI_EXIT_CODE: Record<ApiErrorCode, number>;
+/**
+ * MCP surfaces all apigen errors as the MCP `error` result kind.
+ * Maps each canonical code to the MCP error shape indicator.
+ */
+export declare const MCP_ERROR_KIND: Record<ApiErrorCode, 'error'>;
+/** Convenience bundle: all four transport maps keyed by transport name. */
+export declare const statusMaps: {
+    readonly http: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", number>;
+    readonly grpc: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", string>;
+    readonly cli: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", number>;
+    readonly mcp: Record<"invalid_argument" | "unauthenticated" | "permission_denied" | "not_found" | "internal", "error">;
+};
+/**
+ * The canonical apigen error.  Every transport adapter catches this and maps
+ * `code` to the native status using the tables above.
+ */
+export declare class ApiError extends Error {
+    /** gRPC-style canonical error code. */
+    readonly code: ApiErrorCode;
+    /** Optional structured details (passed through to MCP / HTTP body). */
+    readonly details?: unknown;
+    constructor(code: ApiErrorCode, message: string, details?: unknown);
+    /** Serialise to a plain object suitable for JSON transport. */
+    toJSON(): {
+        code: ApiErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Structural (duck-typed) `ApiError` check — deliberately NOT `instanceof
+ * ApiError`.
+ *
+ * `apigen-engine-runtime` (and every other `platform:node`/`platform:shared`
+ * `@adhd/*` package built via the shared vite config, see
+ * `tools/vite-plugins/externalize.mjs`) BUNDLES its `@adhd/*` dependencies —
+ * including this package — straight into its own `dist` output instead of
+ * externalizing them, so `ApiError` gets re-compiled as a private, separately
+ * identified class inside every consumer's bundle. `err instanceof ApiError`
+ * only succeeds when the checking code and the throwing code share the exact
+ * same loaded copy of this class; the moment one side loads a *different*
+ * bundle of `@adhd/apigen-base-errors` than the other (e.g. a transport
+ * adapter importing this package directly while the error was thrown from
+ * inside another package's bundled copy of `makeValidateLayer` — this is
+ * exactly what happens once real `node_modules` linking, e.g. under pnpm,
+ * makes a package resolve to its pre-built `dist` instead of source), the
+ * classes are structurally identical but referentially distinct and
+ * `instanceof` silently returns `false`. See BACKLOG.md
+ * `BUG-APIGEN-PLUGIN-IN-PROCESS-VALIDATE-500-001` (validate-layer 500-vs-400
+ * misclassification) and `BUG-APIGEN-STREAM-ERROR-CODE-MISCLASSIFY-001`
+ * (mcp-plugin stream error code misclassification) — same root cause,
+ * independently confirmed from two different call sites.
+ *
+ * This guard is immune to that hazard: it only inspects the plain,
+ * cross-realm-safe properties every `ApiError` instance carries (`name`,
+ * `code`, `toJSON`), which survive bundling/inlining identically regardless
+ * of which physical class definition constructed the object.
+ */
+export declare function isApiError(err: unknown): err is ApiError;
+/**
+ * Discriminant that records whether the first chunk was already flushed.
+ * Determines the carrier shape used to deliver a terminal stream error.
+ */
+export type StreamingPhase = 'before-first-chunk' | 'after-first-chunk';
+/**
+ * Carrier for a terminal streaming error **before** the first chunk was sent.
+ * Adapters handle this identically to a normal (non-streaming) §9 error.
+ */
+export interface BeforeFirstChunkError {
+    readonly phase: 'before-first-chunk';
+    /** The underlying canonical error. */
+    readonly error: ApiError;
+}
+/**
+ * Carrier for a terminal streaming error **after** the first chunk was flushed.
+ * The status line is already gone; error must be delivered in-band per transport:
+ *
+ * | Transport        | Mechanism                                            |
+ * |------------------|------------------------------------------------------|
+ * | HTTP SSE/chunked | terminal `event: error` frame carrying the ApiError  |
+ * | gRPC             | trailing status (native gRPC trailers)                |
+ * | MCP              | progressive error notification                       |
+ * | CLI              | flush partial stdout, write ApiError to stderr, exit |
+ */
+export interface AfterFirstChunkError {
+    readonly phase: 'after-first-chunk';
+    /** The underlying canonical error, to be delivered in-band. */
+    readonly error: ApiError;
+    /**
+     * The number of chunks successfully delivered before the error occurred.
+     * Informational — lets CLI adapters decide whether stdout has content.
+     */
+    readonly chunksDelivered: number;
+}
+/** Discriminated union of the two streaming error carrier shapes. */
+export type StreamingErrorCarrier = BeforeFirstChunkError | AfterFirstChunkError;
+/**
+ * Factory: wrap an `ApiError` in the appropriate streaming carrier.
+ *
+ * @param phase           - whether the first chunk was already flushed
+ * @param error           - the terminal error
+ * @param chunksDelivered - (after-first-chunk only) chunks sent before failure
+ */
+export declare function toStreamingError(phase: 'before-first-chunk', error: ApiError): BeforeFirstChunkError;
+export declare function toStreamingError(phase: 'after-first-chunk', error: ApiError, chunksDelivered: number): AfterFirstChunkError;
+/**
+ * Type guard: narrows a `StreamingErrorCarrier` to `BeforeFirstChunkError`.
+ */
+export declare function isBeforeFirstChunk(c: StreamingErrorCarrier): c is BeforeFirstChunkError;
+/**
+ * Type guard: narrows a `StreamingErrorCarrier` to `AfterFirstChunkError`.
+ */
+export declare function isAfterFirstChunk(c: StreamingErrorCarrier): c is AfterFirstChunkError;

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@adhd/apigen-base-errors",
+  "version": "0.1.1",
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}