@snaptrude/plugin-client 0.7.1 → 0.8.0

package/upgrade-notes/index.json

@@ -0,0 +1,36 @@
+{
+  "package": "@snaptrude/plugin-client",
+  "latest": "0.8.0",
+  "spans": [
+    {
+      "from": "0.4.0",
+      "to": "0.5.0",
+      "file": "0.4.0-to-0.5.0.md",
+      "breaking": false
+    },
+    {
+      "from": "0.5.0",
+      "to": "0.6.0",
+      "file": "0.5.0-to-0.6.0.md",
+      "breaking": false
+    },
+    {
+      "from": "0.6.0",
+      "to": "0.7.0",
+      "file": "0.6.0-to-0.7.0.md",
+      "breaking": true
+    },
+    {
+      "from": "0.7.0",
+      "to": "0.7.1",
+      "file": "0.7.0-to-0.7.1.md",
+      "breaking": false
+    },
+    {
+      "from": "0.7.1",
+      "to": "0.8.0",
+      "file": "0.7.1-to-0.8.0.md",
+      "breaking": true
+    }
+  ]
+}

package/AGENTS.md

@@ -1,86 +0,0 @@
-# Plugin Client — Agent Guide
-
-This package implements the plugin-core API for the **worker side** (plugin runtime).
-Plugins import `snaptrude` from this package to interact with the Snaptrude host.
-
-## Relationship to plugin-core
-
-> Source of truth: [`packages/plugin-core/AGENTS.md`](../plugin-core/AGENTS.md)
-
-This package implements the API surface defined in `@snaptrude/plugin-core`. Only the
-root `PluginApi` class is extended; every namespace under it is satisfied structurally
-by a generic RPC proxy (see below). When plugin-core changes its top-level shape,
-this package must be updated to match.
-
-## What this package contains
-
-- `src/api/index.ts` — `ClientPluginApi`: wires one generic RPC proxy per top-level namespace
-- `src/rpc-proxy.ts` — `createRpcNamespace()`: Proxy mapping dotted property paths to host RPC calls
-- `src/host-api.ts` — Comlink RPC wrapper (`HostApi.call()`); unwraps success/error results
-- `src/plugin-worker.ts` — `PluginWorker` base class (lifecycle, UI messaging, Comlink exposure)
-- `src/index.ts` — Exports the `snaptrude` singleton (`ClientPluginApi` instance)
-
-## Quick commands
-
-```bash
-pnpm check-types   # typecheck (no emit)
-pnpm build          # tsup build (ESM + CJS)
-pnpm dev            # tsup watch mode
-```
-
-## Implementation patterns
-
-### Everything is a generic RPC proxy (async, remote)
-
-Under the all-handle model there is no in-worker compute: `core.math.*` and
-`core.geom.*` values are opaque handles, so **every** namespace — `core.*`
-(including `core.units`), `design.*`, `entity.*`, `tools.*` — is a
-`createRpcNamespace<PluginXApi>("x")` Proxy. There are no hand-written
-per-method wrappers. Nested property access builds the dot-separated method
-path; the call marshals `{ method, args }` to the host via Comlink
-(`getHostApi().call()`):
-
-```typescript
-// src/api/index.ts — one proxy per top-level namespace
-this.core = createRpcNamespace<PluginCoreApi>("core")
-
-// Plugin code — positional args (whole tuple crosses the wire), values are handles:
-const v = await snaptrude.core.math.vec3.new(1, 2, 3)
-await snaptrude.entity.space.createRectangular(position, dimensions)
-//   → getHostApi().call({ method: "entity.space.createRectangular", args: [position, dimensions] })
-```
-
-The proxy is structurally cast to the abstract API type, so argument and return
-types are enforced by plugin-core while dispatch stays dynamic. The `method`
-string is exactly the property path and must match `PluginApiMethod`
-(auto-inferred from the class hierarchy in `plugin-core/src/host-utils.ts`).
-
-## When to update this package
-
-- **plugin-core adds/removes/changes a method**: Usually nothing to do here — the
-  proxy dispatches dynamically and types flow from plugin-core. Rebuild plugin-core,
-  then run `pnpm check-types` here.
-- **plugin-core adds a new top-level namespace on `PluginApi`**: Add a matching
-  `createRpcNamespace<PluginNewApi>("new")` property in `ClientPluginApi`
-  (`src/api/index.ts`). Nested modules under an existing namespace need no wiring.
-
-After making changes, always run `pnpm check-types` to verify everything compiles.
-
-## File mapping (plugin-core -> plugin-client)
-
-There are no per-namespace files here anymore — the whole plugin-core API tree is
-served by two files:
-
-| plugin-core                                   | plugin-client                                                        |
-| --------------------------------------------- | -------------------------------------------------------------------- |
-| `src/api/**` (all namespaces, e.g. `core.math.vec3`) | `src/api/index.ts` (`ClientPluginApi`, one `createRpcNamespace` each) |
-| `src/host-utils.ts` (`PluginApiMethod` types) | `src/rpc-proxy.ts` + `src/host-api.ts` (dispatch + Comlink transport) |
-
-## Downstream consumers
-
-Changes to this package's **public exports** affect:
-
-- Internal plugins under `plugins/`
-- Example plugins under `examples/`
-
-If you change or remove an export, search these directories for usage.

package/CLAUDE.md

@@ -1,11 +0,0 @@
-# CLAUDE.md
-
-> **All coding standards, checks, and guidance live in [`AGENTS.md`](AGENTS.md).**
-> `CLAUDE.md` is a pointer only — add all new rules, patterns, and instructions to `AGENTS.md`.
-
-See [AGENTS.md](AGENTS.md) for:
-
-- Implementation pattern (generic RPC proxy — every namespace is async host RPC)
-- File mapping from plugin-core to plugin-client
-- When and how to update this package in response to plugin-core changes
-- Downstream consumer notes

package/src/api/index.ts

@@ -1,45 +0,0 @@
-import {
-  PluginApi,
-  PluginCoreApi,
-  PluginDesignApi,
-  PluginEntityApi,
-  PluginProgramApi,
-  PluginPresentationApi,
-  PluginAnalysisApi,
-} from "@snaptrude/plugin-core"
-import { createRpcNamespace } from "../rpc-proxy"
-
-export class ClientPluginApi extends PluginApi {
-  private static instance: ClientPluginApi
-
-  /**
-   * Every namespace is fully remote under the all-handle model: math/geom now
-   * cross to the host (values are opaque handles), so there is no in-worker
-   * compute left. All dispatch through a single generic RPC Proxy. Units live
-   * under `core.units`, so they ride the `core` proxy.
-   */
-  public core: PluginCoreApi
-  public design: PluginDesignApi
-  public entity: PluginEntityApi
-  public program: PluginProgramApi
-  public presentation: PluginPresentationApi
-  public analysis: PluginAnalysisApi
-
-  private constructor() {
-    super()
-    this.core = createRpcNamespace<PluginCoreApi>("core")
-    this.design = createRpcNamespace<PluginDesignApi>("design")
-    this.entity = createRpcNamespace<PluginEntityApi>("entity")
-    this.program = createRpcNamespace<PluginProgramApi>("program")
-    this.presentation =
-      createRpcNamespace<PluginPresentationApi>("presentation")
-    this.analysis = createRpcNamespace<PluginAnalysisApi>("analysis")
-  }
-
-  static getInstance(): ClientPluginApi {
-    if (!ClientPluginApi.instance) {
-      ClientPluginApi.instance = new ClientPluginApi()
-    }
-    return ClientPluginApi.instance
-  }
-}

package/src/host-api.ts

@@ -1,87 +0,0 @@
-import * as Comlink from "comlink"
-import type {
-  PluginApiMethod,
-  PluginApiCallPayload,
-  PluginApiCallWrappedResult,
-  PluginApiCallResult,
-} from "@snaptrude/plugin-core"
-import { PluginError, fromEnvelope, makeClientEnvelope } from "@snaptrude/plugin-core"
-
-export interface HostApi {
-  call<M extends PluginApiMethod>(
-    payload: PluginApiCallPayload<M>
-  ): Promise<PluginApiCallWrappedResult<M>>
-}
-
-export interface HostApiWrapped {
-  call<M extends PluginApiMethod>(
-    payload: PluginApiCallPayload<M>
-  ): Promise<PluginApiCallResult<M>>
-}
-
-export function createHostApi(endpoint?: Comlink.Endpoint): HostApi {
-  return Comlink.wrap<HostApi>(
-    endpoint ?? (globalThis as unknown as Comlink.Endpoint)
-  ) as unknown as HostApi
-}
-
-let _instance: HostApi | null = null
-
-/** TEST SEAM ONLY: replace the Comlink host instance (pass `undefined` to reset). */
-export function __setHostApiInstance(instance?: HostApi): void {
-  _instance = instance ?? null
-}
-
-export function getHostApi(): HostApiWrapped {
-  if (!_instance) {
-    _instance = createHostApi()
-  }
-  return {
-    call: async <M extends PluginApiMethod>(payload: PluginApiCallPayload<M>): Promise<PluginApiCallResult<M>> => {
-      if (!_instance) {
-        throw new Error("Host API not initialized")
-      }
-
-      let result: PluginApiCallWrappedResult<M>
-      try {
-        result = await _instance.call(payload)
-      } catch (transportErr) {
-        // Comlink-level rejection: port closed, worker terminated, clone
-        // failure. Never a routed failure — the router always RETURNS its
-        // envelope — so normalize to a typed transport error.
-        if (PluginError.is(transportErr)) throw transportErr
-        throw rehydrate(
-          makeClientEnvelope(
-            "TRANSPORT_LOST",
-            transportErr instanceof Error ? transportErr.message : String(transportErr),
-            { methodPath: payload.method }
-          )
-        )
-      }
-
-      if (result.success) {
-        return result.data
-      }
-
-      // Structured envelope when the host provides one; legacy hosts (string
-      // `error` only) degrade to UNKNOWN with the message preserved.
-      throw rehydrate(
-        result.errorInfo ??
-          makeClientEnvelope("UNKNOWN", result.error ?? "Unknown host error", {
-            methodPath: payload.method,
-          })
-      )
-    }
-  }
-}
-
-/**
- * Envelope → typed `PluginError`, with the stack trimmed to the plugin's call
- * site (V8 only; harmless no-op elsewhere) instead of transport internals.
- */
-function rehydrate(envelope: Parameters<typeof fromEnvelope>[0]): PluginError {
-  const error = fromEnvelope(envelope)
-  ;(Error as { captureStackTrace?: (target: object, ctor: Function) => void })
-    .captureStackTrace?.(error, rehydrate)
-  return error
-}

package/src/index.ts

@@ -1,38 +0,0 @@
-import { ClientPluginApi } from "./api"
-
-export * from "./api"
-export * from "./host-api"
-export * from "./plugin-worker"
-
-// Error surface — plugins branch on `PluginError.is(e)` + `e.code`.
-export {
-  PluginError,
-  PluginValidationError,
-  PluginNotFoundError,
-  PluginPermissionError,
-  PluginHandleError,
-  PluginQuotaError,
-  PluginTimeoutError,
-  PluginTransportError,
-  PluginLifecycleError,
-  PluginExecutionError,
-  PluginInternalError,
-  fromEnvelope,
-  isErrorEnvelope,
-  isPluginErrorCode,
-  PLUGIN_ERROR_CODES,
-  CODE_META,
-} from "@snaptrude/plugin-core"
-export type {
-  ErrorEnvelope,
-  PluginErrorCode,
-  WirePluginErrorCode,
-  PluginErrorCategory,
-} from "@snaptrude/plugin-core"
-
-/**
- * The Snaptrude plugin client API.
- *
- * The main entry point for plugins to interact with the Snaptrude platform.
- */
-export const snaptrude = ClientPluginApi.getInstance()

package/src/plugin-worker.ts

@@ -1,99 +0,0 @@
-import * as Comlink from "comlink"
-
-export interface UIMessage {
-  action: string
-  payload: unknown
-}
-
-interface PluginConfig {
-  pluginId: string
-}
-
-/**
- * Base class for Snaptrude plugin workers.
- *
- * Handles Comlink wiring, host communication, and the standard lifecycle
- * methods (`init`, `destroy`, `ping`, `onUIMessage`). Subclass this and
- * override only the methods you need — then call `start()` to expose the
- * worker API.
- *
- * The plugin ID is received automatically from the host during
- * initialization — no need to pass it manually.
- *
- * @example
- * ```ts
- * import { PluginWorker } from "@snaptrude/plugin-client";
- *
- * class MyPlugin extends PluginWorker {
- *   async onUIMessage(message: UIMessage) {
- *     // handle messages from the UI panel
- *   }
- * }
- *
- * new MyPlugin().start();
- * ```
- */
-export abstract class PluginWorker {
-  protected pluginId!: string
-  private hostAPI: Comlink.Remote<Record<string, unknown>>
-
-  constructor() {
-    this.hostAPI = Comlink.wrap<Record<string, unknown>>(
-      self as unknown as Comlink.Endpoint
-    )
-  }
-
-  protected sendToUI(action: string, payload: unknown): void {
-    ;(this.hostAPI as Record<string, any>).ui.sendToUI({ action, payload })
-  }
-
-  /**
-   * Signal the host that this plugin has finished its work and should be
-   * stopped. Use this in headless (UI-less) plugins that run a task and
-   * self-terminate.
-   */
-  protected complete(): void {
-    ;(this.hostAPI as Record<string, any>).lifecycle.complete()
-  }
-
-  async init(): Promise<void> {
-    console.log(this.pluginId, "init() called")
-    console.log(this.pluginId, "Initialization complete")
-  }
-
-  async destroy(): Promise<void> {
-    console.log(this.pluginId, "destroy() called — cleaning up")
-  }
-
-  async ping(): Promise<string> {
-    return "pong"
-  }
-
-  async onUIMessage(_message: UIMessage): Promise<void> {
-    // Override in subclass to handle UI messages
-  }
-
-  /**
-   * Expose the worker API via Comlink and start listening.
-   * Call this once after constructing the plugin instance.
-   *
-   * The host calls `init(config)` with `{ pluginId }`,
-   * which is captured here to set `this.pluginId` before the
-   * subclass's `init()` runs.
-   */
-  start(): void {
-    Comlink.expose(
-      {
-        init: (config: PluginConfig) => {
-          this.pluginId = config.pluginId
-          return this.init()
-        },
-        destroy: () => this.destroy(),
-        ping: () => this.ping(),
-        onUIMessage: (message: UIMessage) => this.onUIMessage(message),
-      },
-      self as unknown as Comlink.Endpoint
-    )
-    console.log("Worker loaded, API exposed via Comlink")
-  }
-}

package/src/rpc-proxy.ts

@@ -1,56 +0,0 @@
-import type {
-  PluginApiCallPayload,
-  PluginApiMethod,
-} from "@snaptrude/plugin-core"
-import { getHostApi } from "./host-api"
-
-/**
- * Build a namespace object whose nested property access maps to a
- * dot-separated host RPC method path, and whose every call dispatches that
- * path through the host bridge.
- *
- * The host exposes the entire plugin API behind a single generic `call()`
- * (see the host `bridge.ts`), and the method string is exactly the property
- * path — so one Proxy replaces every hand-written per-method RPC wrapper for
- * every namespace (`core.*`, `design.*`, `entity.*`):
- *
- * The POSITIONAL transport forwards the whole argument tuple; the host router
- * spreads it back into the resolved method (`fn(...args)`):
- *
- * ```ts
- * snaptrude.core.math.vec3.new(1, 2, 3)
- *   // → getHostApi().call({ method: "core.math.vec3.new", args: [1, 2, 3] })
- * ```
- *
- * Typed at the call site, e.g. `createRpcNamespace<PluginEntityApi>("entity")`.
- * The Proxy is structurally cast to the abstract API type — argument and
- * return types are enforced by that type, while dispatch is dynamic.
- *
- * Every namespace uses this — including `core.math.*` and `core.geom.*`: under
- * the all-handle model there is no in-worker compute; math and geometry are
- * host calls like everything else.
- */
-export function createRpcNamespace<T extends object>(basePath: string): T {
-  const build = (path: string): unknown =>
-    new Proxy(NOOP, {
-      get(_target, prop) {
-        // Symbols and `then` must not resolve to a callable proxy, otherwise
-        // the namespace would look thenable and break Promise resolution if it
-        // ever reached an `await`.
-        if (typeof prop !== "string" || prop === "then") return undefined
-        return build(`${path}.${prop}`)
-      },
-      apply(_target, _thisArg, argArray: unknown[]) {
-        const payload = {
-          method: path,
-          args: argArray,
-        } as unknown as PluginApiCallPayload<PluginApiMethod>
-        return getHostApi().call(payload)
-      },
-    })
-
-  return build(basePath) as T
-}
-
-/** Proxy target must be callable for the `apply` trap; identity is irrelevant. */
-const NOOP = (): void => {}

package/test/host-api-errors.test.mjs

@@ -1,101 +0,0 @@
-// Node built-in test runner suite for host-api error rehydration.
-// Run: node --test test/host-api-errors.test.mjs
-// Imports the BUILT package (dist) — run `pnpm build` first.
-import test from "node:test"
-import assert from "node:assert/strict"
-import {
-  getHostApi,
-  __setHostApiInstance,
-  PluginError,
-  PluginQuotaError,
-  PluginTransportError,
-  PluginInternalError,
-} from "../dist/index.js"
-
-const PAYLOAD = { method: "design.boolean.union", args: [] }
-
-/** Install a fake Comlink instance whose call() resolves/rejects as directed. */
-function stubHost(behavior) {
-  __setHostApiInstance({ call: behavior })
-}
-
-test.afterEach(() => {
-  __setHostApiInstance(undefined)
-})
-
-test("success path returns data verbatim (handles are branded strings on the wire)", async () => {
-  const data = { value: 42, h: "mass_x" }
-  stubHost(async () => ({ success: true, data }))
-  const result = await getHostApi().call(PAYLOAD)
-  assert.equal(result, data) // pass-through: no cloning, no re-wrapping
-  assert.equal(result.value, 42)
-  assert.equal(result.h, "mass_x") // a handle IS its plain string id
-})
-
-test("errorInfo envelope rehydrates into the typed subclass with fields intact", async () => {
-  stubHost(async () => ({
-    success: false,
-    error: "Execution error: Rate limit exceeded",
-    errorInfo: {
-      envelopeVersion: 1,
-      code: "RATE_LIMITED",
-      message: "Rate limit exceeded",
-      errorId: "h-1",
-      details: { retryAfterMs: 250 },
-      methodPath: "design.boolean.union",
-    },
-  }))
-  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
-    assert.equal(PluginError.is(err), true)
-    assert.ok(err instanceof PluginQuotaError)
-    assert.equal(err.code, "RATE_LIMITED")
-    assert.equal(err.errorId, "h-1")
-    assert.deepEqual(err.details, { retryAfterMs: 250 })
-    assert.equal(err.methodPath, "design.boolean.union")
-    return true
-  })
-})
-
-test("unknown envelope code still rehydrates as a PluginError (forward compat)", async () => {
-  stubHost(async () => ({
-    success: false,
-    error: "Execution error: new thing",
-    errorInfo: {
-      envelopeVersion: 1,
-      code: "FUTURE_CODE",
-      message: "new thing",
-      errorId: "h-2",
-    },
-  }))
-  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
-    assert.equal(PluginError.is(err), true)
-    assert.equal(err.code, "FUTURE_CODE")
-    return true
-  })
-})
-
-test("legacy host (string error only) degrades to UNKNOWN with the message preserved", async () => {
-  stubHost(async () => ({ success: false, error: "Execution error: something broke" }))
-  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
-    assert.equal(PluginError.is(err), true)
-    assert.ok(err instanceof PluginInternalError)
-    assert.equal(err.code, "UNKNOWN")
-    assert.equal(err.message, "Execution error: something broke")
-    assert.ok(err.errorId.startsWith("c-"))
-    assert.equal(err.methodPath, "design.boolean.union")
-    return true
-  })
-})
-
-test("transport-level rejection normalizes to TRANSPORT_LOST", async () => {
-  stubHost(async () => {
-    throw new Error("port closed")
-  })
-  await assert.rejects(getHostApi().call(PAYLOAD), (err) => {
-    assert.ok(err instanceof PluginTransportError)
-    assert.equal(err.code, "TRANSPORT_LOST")
-    assert.equal(err.message, "port closed")
-    assert.ok(err.errorId.startsWith("c-"))
-    return true
-  })
-})

package/tsconfig.json

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

package/tsup.config.ts

@@ -1,12 +0,0 @@
-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,
-  }
-})