@snaptrude/plugin-core 0.6.0 → 0.7.0

package/src/errors/plugin-error.ts

@@ -0,0 +1,134 @@
+import { CODE_META, isPluginErrorCode } from "./codes"
+import type { PluginErrorCategory, PluginErrorCode, WirePluginErrorCode } from "./codes"
+import { ERROR_ENVELOPE_VERSION, newErrorId } from "./envelope"
+import type { ErrorEnvelope } from "./envelope"
+
+/**
+ * Cross-copy brand: a plugin bundle may contain its OWN copy of this module,
+ * in which case `instanceof` fails across the two class identities.
+ * `Symbol.for` resolves to the same symbol in every copy within a realm, so
+ * `PluginError.is()` keeps working. Canonical check = `.is()` + `code`.
+ */
+const BRAND = Symbol.for("snaptrude.pluginError")
+
+interface Branded {
+  [BRAND]?: boolean
+}
+
+/**
+ * Typed error every failed plugin API call rejects with.
+ *
+ * Rehydrated client-side from the wire `ErrorEnvelope` (`fromEnvelope`) — the
+ * class itself never crosses the worker boundary. Branch on the stable string
+ * `code`; use `PluginError.is()` rather than `instanceof` (a bundled duplicate
+ * SDK copy breaks `instanceof`, never the brand).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await snaptrude.design.boolean.union(handles)
+ * } catch (e) {
+ *   if (PluginError.is(e) && e.code === "RATE_LIMITED") {
+ *     await sleep(e.details?.retryAfterMs as number)
+ *   } else {
+ *     throw e
+ *   }
+ * }
+ * ```
+ */
+export class PluginError extends Error {
+  readonly code: WirePluginErrorCode
+  readonly errorId: string
+  readonly details?: Record<string, unknown>
+  readonly handle?: string
+  readonly methodPath?: string
+  readonly hint?: string
+
+  constructor(envelope: ErrorEnvelope) {
+    super(envelope.message)
+    this.name = new.target.name
+    this.code = envelope.code
+    this.errorId = envelope.errorId
+    this.details = envelope.details
+    this.handle = envelope.handle
+    this.methodPath = envelope.methodPath
+    this.hint = envelope.hint ?? hintFor(envelope.code)
+    ;(this as Branded)[BRAND] = true
+  }
+
+  /** Canonical check — survives bundled duplicate SDK copies where `instanceof` fails. */
+  static is(value: unknown): value is PluginError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Branded)[BRAND] === true
+    )
+  }
+
+  /** Derived (not wire-carried) family of the code; unknown codes map to "internal". */
+  get category(): PluginErrorCategory {
+    return isPluginErrorCode(this.code) ? CODE_META[this.code].category : "internal"
+  }
+}
+
+// Category sugar — same brand, so `PluginError.is()` matches all of them.
+// Convenience for single-SDK-copy plugins; docs teach `.is()` + `code`.
+export class PluginValidationError extends PluginError {}
+export class PluginNotFoundError extends PluginError {}
+export class PluginPermissionError extends PluginError {}
+export class PluginHandleError extends PluginError {}
+export class PluginQuotaError extends PluginError {}
+export class PluginTimeoutError extends PluginError {}
+export class PluginTransportError extends PluginError {}
+export class PluginLifecycleError extends PluginError {}
+export class PluginExecutionError extends PluginError {}
+export class PluginInternalError extends PluginError {}
+
+type PluginErrorConstructor = new (envelope: ErrorEnvelope) => PluginError
+
+const CATEGORY_CLASS: Record<PluginErrorCategory, PluginErrorConstructor> = {
+  validation: PluginValidationError,
+  not_found: PluginNotFoundError,
+  permission: PluginPermissionError,
+  handle: PluginHandleError,
+  quota: PluginQuotaError,
+  timeout: PluginTimeoutError,
+  transport: PluginTransportError,
+  lifecycle: PluginLifecycleError,
+  execution: PluginExecutionError,
+  internal: PluginInternalError,
+}
+
+function hintFor(code: WirePluginErrorCode): string | undefined {
+  return isPluginErrorCode(code) ? CODE_META[code].hintTemplate : undefined
+}
+
+/**
+ * Rehydrate a wire envelope into the typed error the plugin catches.
+ * A code outside the known union (newer host) constructs the base
+ * `PluginError` with the code preserved verbatim.
+ */
+export function fromEnvelope(envelope: ErrorEnvelope): PluginError {
+  if (!isPluginErrorCode(envelope.code)) return new PluginError(envelope)
+  const ErrorClass = CATEGORY_CLASS[CODE_META[envelope.code].category]
+  return new ErrorClass(envelope)
+}
+
+/**
+ * Build an envelope for a CLIENT-detected failure (transport rejection,
+ * legacy host without `errorInfo`). Host-originated envelopes are built by
+ * the host's `toErrorEnvelope` mapper, never by this.
+ */
+export function makeClientEnvelope(
+  code: PluginErrorCode,
+  message: string,
+  extra?: Partial<Pick<ErrorEnvelope, "details" | "handle" | "methodPath" | "hint">>
+): ErrorEnvelope {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code,
+    message,
+    errorId: newErrorId("c-"),
+    ...extra,
+  }
+}

package/src/host-utils.ts

@@ -1,4 +1,5 @@
 import type { PluginApi } from "./api"
+import type { ErrorEnvelope } from "./errors"
 
 // -- Type Utilities for inferring method paths from the class hierarchy ------
 
@@ -60,5 +61,8 @@ export type PluginApiCallResult<M extends PluginApiMethod> =
 export type PluginApiCallWrappedResult<M extends PluginApiMethod> = {
   success: boolean;
   data?: PluginApiCallResult<M>;
+  /** Legacy failure message — kept verbatim for already-published plugins. */
   error?: string;
+  /** Structured failure (hosts ≥ error-envelope rollout). Present iff `success` is false. */
+  errorInfo?: ErrorEnvelope;
 }

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./api"
 export * from "./types"
 export * from "./host-utils"
 export * from "./handles"
+export * from "./errors"

package/test/errors.test.mjs

@@ -0,0 +1,184 @@
+// Node built-in test runner suite for the error module (codes/envelope/PluginError).
+// Run: node --test test/
+// Imports the BUILT package (dist) — run `pnpm build` first.
+import test from "node:test"
+import assert from "node:assert/strict"
+import {
+  PLUGIN_ERROR_CODES,
+  CODE_META,
+  isPluginErrorCode,
+  ERROR_ENVELOPE_VERSION,
+  isErrorEnvelope,
+  newErrorId,
+  PluginError,
+  PluginValidationError,
+  PluginQuotaError,
+  PluginTimeoutError,
+  PluginTransportError,
+  PluginInternalError,
+  fromEnvelope,
+  makeClientEnvelope,
+} from "../dist/index.js"
+
+const CATEGORIES = [
+  "validation", "not_found", "permission", "handle", "quota",
+  "timeout", "transport", "lifecycle", "execution", "internal",
+]
+
+function envelope(overrides = {}) {
+  return {
+    envelopeVersion: ERROR_ENVELOPE_VERSION,
+    code: "OPERATION_FAILED",
+    message: "it failed",
+    errorId: "test-id-1",
+    ...overrides,
+  }
+}
+
+// --- codes registry ---------------------------------------------------------
+
+test("every code has CODE_META with a valid category (union↔meta completeness)", () => {
+  for (const code of PLUGIN_ERROR_CODES) {
+    const meta = CODE_META[code]
+    assert.ok(meta, `missing CODE_META for ${code}`)
+    assert.ok(CATEGORIES.includes(meta.category), `bad category for ${code}: ${meta.category}`)
+  }
+  assert.equal(Object.keys(CODE_META).length, PLUGIN_ERROR_CODES.length)
+})
+
+test("codes are unique", () => {
+  assert.equal(new Set(PLUGIN_ERROR_CODES).size, PLUGIN_ERROR_CODES.length)
+})
+
+test("isPluginErrorCode narrows union members and rejects strangers", () => {
+  assert.equal(isPluginErrorCode("HANDLE_INVALID"), true)
+  assert.equal(isPluginErrorCode("TOTALLY_MADE_UP"), false)
+  assert.equal(isPluginErrorCode(""), false)
+})
+
+// --- envelope ----------------------------------------------------------------
+
+test("isErrorEnvelope accepts a minimal valid envelope", () => {
+  assert.equal(isErrorEnvelope(envelope()), true)
+})
+
+test("isErrorEnvelope accepts codes OUTSIDE the union (forward compat)", () => {
+  assert.equal(isErrorEnvelope(envelope({ code: "FUTURE_CODE" })), true)
+})
+
+test("isErrorEnvelope rejects malformed values", () => {
+  assert.equal(isErrorEnvelope(null), false)
+  assert.equal(isErrorEnvelope("boom"), false)
+  assert.equal(isErrorEnvelope({}), false)
+  assert.equal(isErrorEnvelope(envelope({ envelopeVersion: 2 })), false)
+  assert.equal(isErrorEnvelope(envelope({ errorId: undefined })), false)
+})
+
+test("newErrorId returns unique prefixed ids", () => {
+  const a = newErrorId("c-")
+  const b = newErrorId("c-")
+  assert.notEqual(a, b)
+  assert.ok(a.startsWith("c-"))
+})
+
+// --- PluginError rehydration --------------------------------------------------
+
+test("fromEnvelope picks the category sugar subclass", () => {
+  assert.ok(fromEnvelope(envelope({ code: "VALIDATION" })) instanceof PluginValidationError)
+  assert.ok(fromEnvelope(envelope({ code: "RATE_LIMITED" })) instanceof PluginQuotaError)
+  assert.ok(fromEnvelope(envelope({ code: "TIMEOUT" })) instanceof PluginTimeoutError)
+  assert.ok(fromEnvelope(envelope({ code: "TRANSPORT_LOST" })) instanceof PluginTransportError)
+  assert.ok(fromEnvelope(envelope({ code: "INTERNAL" })) instanceof PluginInternalError)
+})
+
+test("fromEnvelope preserves envelope fields on the error", () => {
+  const err = fromEnvelope(
+    envelope({
+      code: "OPERATION_FAILED",
+      details: { op: "union", handles: ["mass_1", "mass_2"] },
+      handle: "mass_1",
+      methodPath: "design.boolean.union",
+      hint: "check overlap",
+    })
+  )
+  assert.equal(err.code, "OPERATION_FAILED")
+  assert.equal(err.message, "it failed")
+  assert.equal(err.errorId, "test-id-1")
+  assert.deepEqual(err.details, { op: "union", handles: ["mass_1", "mass_2"] })
+  assert.equal(err.handle, "mass_1")
+  assert.equal(err.methodPath, "design.boolean.union")
+  assert.equal(err.hint, "check overlap")
+  assert.equal(err.category, "execution")
+})
+
+test("unknown code constructs base PluginError with code preserved verbatim", () => {
+  const err = fromEnvelope(envelope({ code: "FUTURE_CODE" }))
+  assert.equal(err.constructor, PluginError)
+  assert.equal(err.code, "FUTURE_CODE")
+  assert.equal(err.category, "internal")
+  assert.equal(PluginError.is(err), true)
+})
+
+test("hint falls back to the code's template when the envelope has none", () => {
+  const err = fromEnvelope(envelope({ code: "RATE_LIMITED" }))
+  assert.equal(err.hint, CODE_META.RATE_LIMITED.hintTemplate)
+})
+
+test("PluginError.is matches the brand across class identities (dual SDK copy)", () => {
+  // Simulate a second bundled copy: a plain object carrying the Symbol.for
+  // brand but NOT part of this module's prototype chain.
+  const impostor = Object.assign(new Error("from other copy"), {
+    [Symbol.for("snaptrude.pluginError")]: true,
+    code: "TIMEOUT",
+  })
+  assert.equal(impostor instanceof PluginError, false)
+  assert.equal(PluginError.is(impostor), true)
+  assert.equal(PluginError.is(new Error("plain")), false)
+  assert.equal(PluginError.is(null), false)
+})
+
+// --- makeClientEnvelope --------------------------------------------------------
+
+test("makeClientEnvelope mints a c- prefixed id and passes extras through", () => {
+  const env = makeClientEnvelope("TRANSPORT_LOST", "port closed", {
+    methodPath: "design.boolean.union",
+  })
+  assert.equal(isErrorEnvelope(env), true)
+  assert.equal(env.code, "TRANSPORT_LOST")
+  assert.ok(env.errorId.startsWith("c-"))
+  assert.equal(env.methodPath, "design.boolean.union")
+})
+
+// --- Registry snapshot (append-only guard) -----------------------------------
+// Deliberate: adding a code REQUIRES updating this list in the same change so
+// the addition is reviewed; removing or renaming one must fail loudly forever.
+
+test("PLUGIN_ERROR_CODES matches the reviewed snapshot (append-only contract)", () => {
+  assert.deepEqual([...PLUGIN_ERROR_CODES], [
+    "VALIDATION",
+    "INVALID_RPC_FORMAT",
+    "METHOD_NOT_FOUND",
+    "METHOD_NOT_PERMITTED",
+    "HANDLE_INVALID",
+    "HANDLE_KIND_MISMATCH",
+    "RESOURCE_QUOTA_EXCEEDED",
+    "RATE_LIMITED",
+    "PRECONDITION_FAILED",
+    "OPERATION_FAILED",
+    "TIMEOUT",
+    "CALL_TIMEOUT",
+    "TRANSPORT_LOST",
+    "PLUGIN_NOT_READY",
+    "PLUGIN_TERMINATED",
+    "RESULT_NOT_SERIALIZABLE",
+    "RESULT_TOO_LARGE",
+    "BATCH_PARTIAL",
+    "STORY_UPDATE_FAILED",
+    "STORY_HEIGHT_REJECTED",
+    "NO_ACTIVE_STRUCTURE",
+    "NO_ELIGIBLE_ELEMENTS",
+    "PROPOSAL_SWITCH_BLOCKED",
+    "INTERNAL",
+    "UNKNOWN",
+  ])
+})