@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/host-utils.ts

@@ -0,0 +1,68 @@
+import type { PluginApi } from "./api"
+import type { ErrorEnvelope } from "./errors"
+
+// -- Type Utilities for inferring method paths from the class hierarchy ------
+
+/**
+ * UnionToIntersection is a type utility that converts a union type to an intersection type.
+ */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never
+
+type Flatten<T> = { [K in keyof T]: T[K] }
+
+/**
+ * The full parameter tuple of a method — the positional-args transport forwards
+ * the whole argument list (`[]` for no-arg methods).
+ */
+type MethodArgs<F extends (...args: any[]) => any> = Parameters<F>
+
+type MethodReturn<F extends (...args: any[]) => any> = Awaited<ReturnType<F>>
+
+/**
+ * Recursively walks a type tree and produces a union of single-key Records
+ * for every leaf method, using dot-separated paths as keys.
+ */
+type ExtractMethodPaths<T, Prefix extends string = ""> = {
+  [K in keyof T & string]: T[K] extends (...args: any[]) => any
+    ? Record<
+        `${Prefix}${K}`,
+        { args: MethodArgs<T[K]>; return: MethodReturn<T[K]> }
+      >
+    : T[K] extends object
+      ? ExtractMethodPaths<T[K], `${Prefix}${K}.`>
+      : never
+}[keyof T & string]
+
+// -- Plugin API method map ---------------------------------------------------
+
+/**
+ * Maps every plugin API method path to its argument and return types.
+ * Automatically inferred from the PluginApi abstract class hierarchy.
+ */
+export type PluginApiMethodMap = Flatten<
+  UnionToIntersection<ExtractMethodPaths<PluginApi>>
+>
+
+export type PluginApiMethod = keyof PluginApiMethodMap
+
+export type PluginApiCallPayload<M extends PluginApiMethod = PluginApiMethod> = {
+  method: M
+  /** Positional argument tuple, spread back into the method host-side. */
+  args: PluginApiMethodMap[M]["args"]
+}
+
+export type PluginApiCallResult<M extends PluginApiMethod> =
+  PluginApiMethodMap[M]["return"]
+
+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

@@ -0,0 +1,5 @@
+export * from "./api"
+export * from "./types"
+export * from "./host-utils"
+export * from "./handles"
+export * from "./errors"

package/src/types.ts

@@ -0,0 +1,16 @@
+/**
+ * A unique identifier for a component in the Snaptrude scene.
+ *
+ * Component IDs are returned by entity creation methods (e.g.
+ * {@linkcode PluginSpaceApi.createRectangular}) and can be used with
+ * query and transform methods throughout the API.
+ */
+export type ComponentId = string
+
+/**
+ * Return type for a plugin API method.
+ *
+ * Methods that require a host round-trip return `Promise<T>`,
+ * while pure local computations may return `T` directly.
+ */
+export type PluginApiReturn<T> = Promise<T> | T

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",
+  ])
+})

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "moduleResolution": "bundler",
+    "lib": [
+      "ES2020",
+      "ESNext.Disposable"
+    ],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "typeRoots": [],
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "dist"
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup"
+
+export default defineConfig( (options) => {
+  return {
+    entry: ["src/index.ts"],
+    format: ["cjs", "esm"],
+    dts: false,
+    sourcemap: true,
+    onSuccess: "tsc", // Run tsc to generate d.ts and d.ts.map
+    watch: options.watch,
+  }
+})