stwaidele/dorfteich
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 22 Wiki Activity

Plugin SDK: manifest schema, validation, and RPC protocol #70

New Issue
Closed
opened 2026-07-04 14:52:36 +02:00 by fable-5 · 1 comment
fable-5 commented 2026-07-04 14:52:36 +02:00
Collaborator
Copy Link

Context

The SDK is the contract between host and plugins; everything else in M7 builds on it (ADR 0008, plugin-architecture.md).

Scope

Implement packages/plugin-sdk: Zod manifest schema (id, name, version, apiVersion, kind, extensionPoints, permissions, fallback, license, i18n refs) with validation + precise error messages; the typed postMessage RPC protocol (request/response with ids, timeouts, capability names) as host-side and plugin-side helpers (createPlugin, host router); protocol documentation in the package README with a sequence diagram.

Acceptance criteria

  • manifest fixtures (valid + 10 invalid variants) validate with actionable errors
  • RPC roundtrip works in a jsdom test (request, response, timeout, unknown-capability rejection)
  • apiVersion compatibility check helper with tests
  • SDK builds standalone (a plugin author needs only this package)

Technical notes

  • ADR 0008, plugin-architecture.md (manifest example is normative).

Dependencies

Depends on #1.

Size: ~1.5 days

Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add de and en), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.

## Context The SDK is the contract between host and plugins; everything else in M7 builds on it (ADR 0008, plugin-architecture.md). ## Scope Implement `packages/plugin-sdk`: Zod manifest schema (id, name, version, apiVersion, kind, extensionPoints, permissions, fallback, license, i18n refs) with validation + precise error messages; the typed postMessage RPC protocol (request/response with ids, timeouts, capability names) as host-side and plugin-side helpers (`createPlugin`, host router); protocol documentation in the package README with a sequence diagram. ## Acceptance criteria - [ ] manifest fixtures (valid + 10 invalid variants) validate with actionable errors - [ ] RPC roundtrip works in a jsdom test (request, response, timeout, unknown-capability rejection) - [ ] apiVersion compatibility check helper with tests - [ ] SDK builds standalone (a plugin author needs only this package) ## Technical notes - ADR 0008, plugin-architecture.md (manifest example is normative). ## Dependencies Depends on #1. **Size**: ~1.5 days --- *Conventions: English code/comments, clear human-readable code, no hard-coded UI strings (ADR 0012, add `de` **and** `en`), permission checks only via the shared guard (docs/architecture/permissions.md). Read the referenced ADRs before starting.*
fable-5 added this to the M7 — Plugins milestone 2026-07-04 14:52:36 +02:00
fable-5 added the
plugins
 label 2026-07-04 14:52:36 +02:00
opus-4-8 commented 2026-07-10 16:28:51 +02:00
Collaborator
Copy Link

Done in ec6ca80 — pipeline green (all 8 contexts; Promote to Int is skipped via RUN_INT_DEPLOY=false, INT stays down by design).

New standalone package @dorfteich/plugin-sdk (only zod), the contract every other M7 story builds on (ADR 0008, plugin-architecture.md).

Acceptance criteria

  • manifest fixtures (3 valid + 14 invalid) validate with actionable { path, message } errors — each asserted individually, plus spot-checks on path/message
  • RPC roundtrip in a jsdom MessageChannel test: request/response, arg passing, timeout, unknown-method, undeclared-capability rejection, dispose
  • checkApiVersion compatibility helper with tests
  • SDK builds standalone (tsup ESM+CJS+types)

Contents

  • manifest.ts — Zod schema + validateManifest/parseManifest; cross-field rules (extension-point↔kind match, unique ids, section_style declares no permissions).
  • api-version.ts — checkApiVersion against the host's supported major range.
  • capabilities.ts — capability names + method→capability map (single source of truth for the permission gate).
  • rpc.ts — transport-agnostic createRpcEndpoint (ids, per-request timeouts, unknown_method/endpoint_disposed) + windowTransport adapter.
  • host.ts — createHostBridge: routes plugin calls through the manifest permission gate; drives render/edit/destroy.
  • plugin.ts — createPlugin: answers lifecycle calls, exposes a typed host proxy.
  • README.md — protocol doc with a mermaid sequence diagram.

51 tests green; repo-wide typecheck + lint clean. Next: the install/storage path (#71) and the sandbox host runtime (#73) consume this SDK.

Done in `ec6ca80` — pipeline green (all 8 contexts; *Promote to Int* is skipped via `RUN_INT_DEPLOY=false`, INT stays down by design). New standalone package **`@dorfteich/plugin-sdk`** (only `zod`), the contract every other M7 story builds on (ADR 0008, plugin-architecture.md). **Acceptance criteria** - [x] manifest fixtures (3 valid + 14 invalid) validate with actionable `{ path, message }` errors — each asserted individually, plus spot-checks on path/message - [x] RPC roundtrip in a jsdom `MessageChannel` test: request/response, arg passing, timeout, unknown-method, undeclared-capability rejection, dispose - [x] `checkApiVersion` compatibility helper with tests - [x] SDK builds standalone (tsup ESM+CJS+types) **Contents** - `manifest.ts` — Zod schema + `validateManifest`/`parseManifest`; cross-field rules (extension-point↔kind match, unique ids, `section_style` declares no permissions). - `api-version.ts` — `checkApiVersion` against the host's supported major range. - `capabilities.ts` — capability names + method→capability map (single source of truth for the permission gate). - `rpc.ts` — transport-agnostic `createRpcEndpoint` (ids, per-request timeouts, `unknown_method`/`endpoint_disposed`) + `windowTransport` adapter. - `host.ts` — `createHostBridge`: routes plugin calls through the manifest permission gate; drives `render`/`edit`/`destroy`. - `plugin.ts` — `createPlugin`: answers lifecycle calls, exposes a typed `host` proxy. - `README.md` — protocol doc with a mermaid sequence diagram. 51 tests green; repo-wide typecheck + lint clean. Next: the install/storage path (#71) and the sandbox host runtime (#73) consume this SDK.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels   
area:auth

   
area:docs

   
area:export

   
area:ops

   
area:storage

   
area:supply-chain

   
auth

Authentication, permissions, quotas

  
backend

API server (apps/api)

  
blocked

Blocked on external dependency/infrastructure

  
collab

Collaboration server (apps/collab)

  
deployment

Docker, CI/CD, hosting

  
docs

Documentation

  
effort:L

   
effort:M

   
effort:S

   
frontend

SPA (apps/web)

  
plugins

Plugin system and SDK

  
qa

Tests, fixtures, e2e

  
vs-nfd

   
vs-nfd:blocker
No Label
area:auth
area:docs
area:export
area:ops
area:storage
area:supply-chain
auth
backend
blocked
collab
deployment
docs
effort:L
effort:M
effort:S
frontend
plugins
qa
vs-nfd
vs-nfd:blocker
Milestone
Clear milestone
No items
No Milestone
M7 — Plugins
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: stwaidele/dorfteich#70
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?