@texisoft/nexus-plugin-testkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,78 @@
+TEXISOFT PROPRIETARY LICENSE
+
+Copyright (c) 2026 texisoft. All rights reserved.
+
+This software, including its source code, documentation and associated
+materials (the "Software"), is proprietary to texisoft ("Licensor"). It is made
+available on public package registries for distribution convenience only.
+Publication does NOT grant an open-source license and does NOT transfer or
+waive any right of the Licensor.
+
+1. Limited permission
+   Subject to this license, you may install and run the Software solely to
+   develop, test, build and publish plugins for the Nexus Discord bot platform
+   operated by the Licensor ("Nexus"), and only for as long as you comply with
+   this license. This permission is personal, non-exclusive, non-transferable,
+   non-sublicensable and revocable at any time.
+
+2. Restrictions
+   Except where applicable law expressly forbids the restriction, you may not:
+   a) copy, modify, adapt, translate or create derivative works of the Software;
+   b) redistribute, publish, sell, rent, lease, sublicense or otherwise make
+      the Software or any part of it available to third parties, whether
+      modified or not, including re-publishing it to any package registry or
+      repository;
+   c) decompile, reverse engineer or attempt to derive source code, algorithms
+      or the sandbox, permission or protocol design, except for the source
+      that is delivered in readable form with the package, which remains
+      subject to this license;
+   d) use the Software, or knowledge gained from it, to build, operate or
+      support a platform, service or product that competes with or replaces
+      Nexus, or that is compatible with Nexus plugins;
+   e) circumvent, disable or probe the security, sandbox, permission, rate
+      limit, review or consent mechanisms of Nexus, or use the Software to
+      attack, overload or gain unauthorized access to Nexus or any third
+      party;
+   f) remove or alter copyright, license or attribution notices;
+   g) use the Software to train, fine-tune or evaluate machine-learning models,
+      or to build datasets for that purpose.
+
+3. Your plugins
+   Plugins you write remain yours. Submitting a plugin to Nexus is governed by
+   the Nexus developer terms, not by this license. Bundled portions of the
+   Software that the build tooling inserts into your plugin may be distributed
+   only as part of that plugin and only to Nexus.
+
+4. Ownership
+   The Software is licensed, not sold. The Licensor retains all right, title
+   and interest, including all intellectual property rights.
+
+5. Termination
+   This license ends automatically and without notice if you breach it. On
+   termination you must stop using the Software and delete all copies. The
+   Licensor may also withdraw this license at any time by publishing a notice
+   or removing the Software.
+
+6. No warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   NON-INFRINGEMENT, AVAILABILITY OR COMPATIBILITY WITH ANY FUTURE VERSION. THE
+   SOFTWARE IS A PRE-1.0 RELEASE AND ITS INTERFACES MAY CHANGE WITHOUT NOTICE.
+
+7. Limitation of liability
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, LOSS OF
+   DATA, PROFITS OR GOODWILL, ARISING FROM OR RELATED TO THE SOFTWARE. THE
+   LICENSOR'S TOTAL LIABILITY IS LIMITED TO EUR 100, EXCEPT FOR LIABILITY THAT
+   CANNOT BE EXCLUDED UNDER APPLICABLE LAW (INTENT, GROSS NEGLIGENCE, INJURY
+   TO LIFE, BODY OR HEALTH, AND LIABILITY UNDER THE PRODUCT LIABILITY ACT).
+
+8. Governing law
+   This license is governed by the laws of the Federal Republic of Germany,
+   excluding its conflict-of-laws rules and the UN Convention on Contracts for
+   the International Sale of Goods. If you are a merchant or a legal entity,
+   the courts at the Licensor's registered seat have exclusive jurisdiction.
+
+9. Severability
+   If a provision is invalid, the remaining provisions stay in force and the
+   invalid provision is replaced by the closest valid one.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @texisoft/nexus-plugin-testkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zum Testen von Nexus-Plugins, ohne dass Bot, Server oder Discord laufen. Das Testkit simuliert Events, Commands, Interaktionen, Jobs, Speicher, HTTP und Discord und hält sich dabei an dieselben Regeln wie die Sandbox in Produktion.
+
+```bash
+npm install --save-dev @texisoft/nexus-plugin-testkit
+```
+
+## Beispiel
+
+```js
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { fileURLToPath } from 'node:url'
+import { createProjectHarness } from '@texisoft/nexus-plugin-testkit'
+
+const dir = fileURLToPath(new URL('..', import.meta.url))
+
+test('/hello antwortet und zählt hoch', async () => {
+  const harness = await createProjectHarness(dir)
+  const first = await harness.runCommand('hello')
+  assert.equal(first.ok, true)
+  assert.equal(harness.storage.get('hello:count'), 1)
+})
+```
+
+`createProjectHarness(dir)` lädt `manifest.json` und `index.js` deines Projekts. Danach stehen dir unter anderem `runCommand`, `emit` für Events, `runJob`, `runUiData` und `runUiAction` zur Verfügung, dazu Aufrufe für Interaktionen.
+
+Jeder Aufruf gibt `{ ok, value, error, replies, reply, calls, logs, delivered, durationMs }` zurück. Wenn dein Plugin einen Fehler auslöst, wirft das Testkit ihn nicht, sondern legt ihn in `error`, mit einem festen Code wie `permission_denied`, `http_blocked`, `quota_exceeded`, `rate_limited`, `invalid_args` oder `timeout`.
+
+## Wie in Produktion
+
+Ein `ctx`-Aufruf ohne deklarierte Berechtigung schlägt mit `permission_denied` fehl. Eine Registrierung ohne passende Berechtigung bricht den Start ab, und Commands, die nicht im Manifest stehen, werden abgelehnt. Aufrufe an `ctx` direkt in `setup()` liefern `unavailable`. Mit `devMode: true` kommen Events und Interaktionen anderer Mitglieder gar nicht erst an.
+
+Passend dazu gibt es `@texisoft/nexus-plugin-sdk` und `@texisoft/nexus-plugin-cli`.
+
+## Lizenz
+
+Node.js 22 oder neuer. Das Paket ist proprietär, alle Rechte bleiben bei texisoft. Du darfst es nur nutzen, um Plugins für Nexus zu entwickeln, Genaueres steht in der `LICENSE`. Die Version ist noch 0.x, Schnittstellen können sich ändern.

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@texisoft/nexus-plugin-testkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Test-Kit für Nexus-Plugins: simulierte Events, Commands, Interaktionen, Jobs, Storage, HTTP und Discord mit denselben Regeln wie in Produktion.",
+  "keywords": [
+    "nexus",
+    "discord",
+    "discord-bot",
+    "plugin",
+    "texisoft"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/texisoft/discord-nexus-bot.git",
+    "directory": "packages/plugin-testkit"
+  },
+  "homepage": "https://github.com/texisoft/discord-nexus-bot/tree/master/packages/plugin-testkit",
+  "bugs": {
+    "url": "https://github.com/texisoft/discord-nexus-bot/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./runner": "./src/runner.js",
+    "./project": "./src/project.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@texisoft/nexus-plugin-sdk": "^0.1.0"
+  }
+}

package/src/fixtures.js

@@ -0,0 +1,74 @@
+let counter = 0
+
+export function nextSnowflake() {
+  counter += 1
+  return String(400000000000000000n + BigInt(counter))
+}
+
+export const DEFAULT_IDS = Object.freeze({
+  guildId: '100000000000000001',
+  authorUserId: '200000000000000001',
+  otherUserId: '200000000000000002',
+  channelId: '300000000000000001'
+})
+
+export function makeUser(overrides = {}) {
+  const id = overrides.id ?? DEFAULT_IDS.authorUserId
+  return { id, username: `user${id.slice(-4)}`, bot: false, ...overrides }
+}
+
+export function makeMember(overrides = {}) {
+  return { userId: DEFAULT_IDS.authorUserId, nickname: null, roles: [], joinedAt: null, ...overrides }
+}
+
+export function makeMessage(overrides = {}) {
+  const authorId = overrides.authorId ?? overrides.author?.id ?? DEFAULT_IDS.authorUserId
+  return {
+    id: nextSnowflake(),
+    channelId: DEFAULT_IDS.channelId,
+    authorId,
+    author: makeUser({ id: authorId }),
+    content: 'Hallo Welt',
+    attachmentCount: 0,
+    createdAt: 1767225600000,
+    ...overrides
+  }
+}
+
+export const eventFixtures = Object.freeze({
+  messageCreate: (overrides = {}) => ({ message: makeMessage(overrides) }),
+  messageUpdate: (overrides = {}) => ({ message: makeMessage(overrides) }),
+  messageDelete: (overrides = {}) => ({ messageId: nextSnowflake(), channelId: DEFAULT_IDS.channelId, ...overrides }),
+  messageReactionAdd: (overrides = {}) => ({
+    messageId: nextSnowflake(), channelId: DEFAULT_IDS.channelId, userId: DEFAULT_IDS.authorUserId, emoji: { name: '👍' }, ...overrides
+  }),
+  messageReactionRemove: (overrides = {}) => ({
+    messageId: nextSnowflake(), channelId: DEFAULT_IDS.channelId, userId: DEFAULT_IDS.authorUserId, emoji: { name: '👍' }, ...overrides
+  }),
+  guildMemberAdd: (overrides = {}) => ({ user: makeUser(), member: makeMember(), ...overrides }),
+  guildMemberRemove: (overrides = {}) => ({ user: makeUser(), ...overrides }),
+  guildMemberUpdate: (overrides = {}) => ({
+    user: makeUser(), member: makeMember(), addedRoles: [], removedRoles: [], ...overrides
+  }),
+  voiceStateUpdate: (overrides = {}) => ({
+    userId: DEFAULT_IDS.authorUserId, oldChannelId: null, newChannelId: DEFAULT_IDS.channelId, ...overrides
+  })
+})
+
+export function actorOfEvent(name, payload) {
+  switch (name) {
+    case 'messageCreate':
+    case 'messageUpdate':
+      return payload?.message?.authorId ?? null
+    case 'messageReactionAdd':
+    case 'messageReactionRemove':
+    case 'voiceStateUpdate':
+      return payload?.userId ?? null
+    case 'guildMemberAdd':
+    case 'guildMemberRemove':
+    case 'guildMemberUpdate':
+      return payload?.user?.id ?? null
+    default:
+      return null
+  }
+}

package/src/harness.js

@@ -0,0 +1,499 @@
+import {
+  EVENT_NAMES, PROTOCOL_VERSION, RUNTIME_LIMITS as R, PluginValidationError, actionResultSchema, chartDataSchema,
+  checkCall, configValuesSchema, hasPermission, invokeSchema, isPluginDefinition, manifestSchema,
+  permissionForRegistration, registerSchema, shouldDeliverInDev, statDataSchema, tableDataSchema, utf8Size,
+  validate, validateCallArgs, validateFrame, validateOrThrow
+} from '@texisoft/nexus-plugin-sdk'
+import {
+  DEFAULT_IDS, actorOfEvent, eventFixtures, makeMember, makeUser, nextSnowflake
+} from './fixtures.js'
+import { PluginCallError, createPluginRunner } from './runner.js'
+import { createMemoryKv } from './storage.js'
+
+const DATA_SCHEMAS = { table: tableDataSchema, stat: statDataSchema, chart: chartDataSchema }
+
+const DISCORD_DEFAULTS = {
+  sendMessage: (a) => ({ id: nextSnowflake(), channelId: a.channelId }),
+  editMessage: (a) => ({ id: a.messageId, channelId: a.channelId }),
+  sendDm: (a) => ({ id: nextSnowflake(), channelId: nextSnowflake(), userId: a.userId }),
+  createThread: (a) => ({ id: nextSnowflake(), name: a.name }),
+  archiveThread: (a) => ({ threadId: a.threadId, archived: true, locked: a.locked === true }),
+  setThreadTags: (a) => ({ threadId: a.threadId, tagIds: a.tagIds }),
+  fetchMember: (a) => ({ userId: a.userId, nickname: null, roles: [] }),
+  fetchChannel: (a) => ({ id: a.channelId, name: 'kanal', type: 'text' }),
+  fetchRole: (a) => ({ id: a.roleId, name: 'rolle' })
+}
+
+let fakeDepth = 0
+let realNow = null
+
+async function withFakeNow(clock, fn) {
+  if (fakeDepth === 0) {
+    realNow = Date.now
+    Date.now = () => clock.now()
+  }
+  fakeDepth += 1
+  try {
+    return await fn()
+  } finally {
+    fakeDepth -= 1
+    if (fakeDepth === 0) {
+      Date.now = realNow
+      realNow = null
+    }
+  }
+}
+
+function createClock(start) {
+  let current = start
+  return { now: () => current, set: (value) => { current = value } }
+}
+
+function issueSummary(errors) {
+  return errors.map((e) => `${e.path || '<root>'}:${e.code}`).join(', ')
+}
+
+function matchMock(matcher, req) {
+  if (typeof matcher === 'function') return Boolean(matcher(req))
+  if (matcher instanceof RegExp) return matcher.test(req.url)
+  if (typeof matcher === 'string') {
+    const space = matcher.indexOf(' ')
+    if (space > 0 && /^[A-Z]+$/.test(matcher.slice(0, space))) return matcher.slice(0, space) === req.method && matcher.slice(space + 1) === req.url
+    return matcher === req.url
+  }
+  return false
+}
+
+function normalizeResponse(raw) {
+  const response = raw ?? {}
+  const headers = Object.fromEntries(Object.entries(response.headers ?? {}).map(([k, v]) => [k.toLowerCase(), String(v)]))
+  let text = response.text ?? ''
+  if (response.json !== undefined) {
+    text = JSON.stringify(response.json)
+    headers['content-type'] ??= 'application/json'
+  }
+  return { status: response.status ?? 200, headers, text: String(text) }
+}
+
+export function createTestHarness(plugin, options = {}) {
+  if (!isPluginDefinition(plugin)) throw new TypeError('createTestHarness: erwartet ein Ergebnis von definePlugin')
+  const manifest = validateOrThrow(manifestSchema, options.manifest)
+  const guildId = options.guildId ?? DEFAULT_IDS.guildId
+  const authorUserId = options.authorUserId ?? DEFAULT_IDS.authorUserId
+  const devMode = options.devMode ?? false
+  const locale = options.locale ?? manifest.locales.default
+  const deadlineMs = options.deadlineMs ?? R.invocationDeadlineMs
+  const clock = createClock(options.now ?? Date.now())
+  const kv = createMemoryKv({ quotaKb: manifest.permissions.storageQuotaKb, now: clock.now })
+  const allCalls = []
+  const allLogs = []
+  const records = new Map()
+  const mocks = []
+  const httpRequests = []
+  const discordResponders = new Map()
+  const discordCalls = []
+  const discordMessages = []
+  const configSchema = configValuesSchema(manifest.configSchema).partial()
+  const configFields = new Map(manifest.configSchema.map((f) => [f.key, f]))
+  const configValues = {}
+  let invocationCounter = 0
+  let runner = null
+  let startPromise = null
+  let jobTimers = []
+
+  for (const f of manifest.configSchema) if (f.default !== undefined) configValues[f.key] = structuredClone(f.default)
+
+  function setConfig(key, value) {
+    if (!configFields.has(key)) throw new PluginValidationError([{ path: key, code: 'unknown_key' }])
+    validateOrThrow(configSchema, { [key]: value })
+    configValues[key] = structuredClone(value)
+  }
+
+  for (const [key, value] of Object.entries(options.config ?? {})) setConfig(key, value)
+
+  function record(inv, entry) {
+    allCalls.push(entry)
+    records.get(inv.id)?.calls.push(entry)
+  }
+
+  function interactionCall(inv, method, args) {
+    if (inv.kind !== 'command' && inv.kind !== 'interaction') {
+      throw new PluginCallError('forbidden', `${method} ist nur in Command- und Interaktions-Aufrufen erlaubt`)
+    }
+    const s = inv.state
+    const rec = records.get(inv.id)
+    const type = method.slice('interaction.'.length)
+    if (type === 'reply' || type === 'update') {
+      if (type === 'update' && inv.kind !== 'interaction') throw new PluginCallError('forbidden', 'update ist nur für Komponenten-Interaktionen erlaubt')
+      if (s.replied) throw new PluginCallError('forbidden', 'Interaktion wurde bereits beantwortet')
+      s.replied = true
+      rec.replies.push({ type, message: args.message })
+    } else if (type === 'defer') {
+      if (s.replied || s.deferred) throw new PluginCallError('forbidden', 'Interaktion wurde bereits beantwortet')
+      s.deferred = true
+      rec.replies.push({ type, ephemeral: args.ephemeral })
+    } else if (type === 'followUp') {
+      if (!s.replied && !s.deferred) throw new PluginCallError('forbidden', 'followUp erfordert vorher reply oder defer')
+      rec.replies.push({ type, message: args.message })
+    } else if (type === 'showModal') {
+      if (s.replied || s.deferred) throw new PluginCallError('forbidden', 'Interaktion wurde bereits beantwortet')
+      s.replied = true
+      rec.replies.push({ type: 'modal', modal: args.modal })
+    }
+  }
+
+  async function httpFetch(inv, args) {
+    inv.state.http += 1
+    if (inv.state.http > R.httpRequestsPerInvocationMax) {
+      throw new PluginCallError('rate_limited', `Mehr als ${R.httpRequestsPerInvocationMax} HTTP-Anfragen je Aufruf`)
+    }
+    const req = { url: args.url, method: args.method, headers: args.headers ?? {}, body: args.body ?? null }
+    httpRequests.push(req)
+    const mock = mocks.find((m) => matchMock(m.matcher, req))
+    if (!mock) throw new PluginCallError('http_failed', `Kein HTTP-Mock für ${req.method} ${req.url}`)
+    let raw
+    try {
+      raw = typeof mock.responder === 'function' ? await mock.responder(req) : mock.responder
+    } catch (error) {
+      throw new PluginCallError('http_failed', error?.message ?? 'HTTP-Fehler')
+    }
+    const response = normalizeResponse(raw)
+    if (utf8Size(response.text) > R.httpResponseMaxBytes) {
+      throw new PluginCallError('http_failed', `Antwort größer als ${R.httpResponseMaxBytes} Bytes`)
+    }
+    return response
+  }
+
+  async function discordCall(method, args) {
+    const action = method.slice('discord.'.length)
+    const entry = { method: action, args: structuredClone(args) }
+    discordCalls.push(entry)
+    if (['sendMessage', 'editMessage', 'sendDm'].includes(action)) discordMessages.push(entry)
+    const responder = discordResponders.get(action)
+    if (responder !== undefined) return typeof responder === 'function' ? responder(args) : responder
+    return DISCORD_DEFAULTS[action] ? DISCORD_DEFAULTS[action](args) : null
+  }
+
+  async function call(method, rawArgs, inv) {
+    if (!inv) throw new PluginCallError('forbidden', 'ctx-Aufruf außerhalb eines Aufrufs')
+    const entry = { invocationId: inv.id, method, args: structuredClone(rawArgs), ok: true, error: null }
+    record(inv, entry)
+    try {
+      inv.state.calls += 1
+      if (inv.state.calls > R.callsPerInvocationMax) {
+        throw new PluginCallError('rate_limited', `Mehr als ${R.callsPerInvocationMax} ctx-Aufrufe je Aufruf`)
+      }
+      const verdict = checkCall(manifest, method, rawArgs)
+      if (!verdict.ok) {
+        const error = new PluginCallError(verdict.code, verdict.permission ? `Permission fehlt: ${verdict.permission}` : verdict.code)
+        error.permission = verdict.permission
+        throw error
+      }
+      const valid = validateCallArgs(method, rawArgs)
+      if (!valid.ok) throw new PluginCallError('invalid_args', issueSummary(valid.errors))
+      const args = valid.data
+      switch (method) {
+        case 'storage.kv.get': return kv.get(args.key)
+        case 'storage.kv.set': return kv.set(args.key, args.value, { ttlSeconds: args.ttlSeconds })
+        case 'storage.kv.delete': return kv.delete(args.key)
+        case 'storage.kv.list': return kv.list(args)
+        case 'storage.kv.incr': return kv.incr(args.key, args.by)
+        case 'config.get':
+          if (!configFields.has(args.key)) throw new PluginCallError('not_found', `Unbekannter Config-Schlüssel "${args.key}"`)
+          return structuredClone(configValues[args.key] ?? null)
+        case 'config.getAll': return structuredClone(configValues)
+        case 'http.fetch': return await httpFetch(inv, args)
+        case 'log.write': {
+          const log = { level: args.level, message: args.message }
+          allLogs.push(log)
+          records.get(inv.id)?.logs.push(log)
+          return undefined
+        }
+        default:
+          if (method.startsWith('interaction.')) return interactionCall(inv, method, args)
+          return await discordCall(method, args)
+      }
+    } catch (error) {
+      entry.ok = false
+      entry.error = { code: error.code ?? 'plugin_error', message: error.message }
+      throw error
+    }
+  }
+
+  function onRegister(registrations) {
+    const frame = validateFrame(registerSchema, { type: 'register', v: PROTOCOL_VERSION, registrations })
+    if (!frame.ok) throw new PluginCallError('invalid_message', `Ungültige Registrierung: ${issueSummary(frame.errors)}`)
+    const declared = new Set(manifest.commands.map((c) => c.name))
+    for (const r of registrations) {
+      const needed = permissionForRegistration(r.kind, r.name)
+      if (needed && !hasPermission(manifest, needed)) {
+        const error = new PluginCallError('permission_denied', `Permission fehlt: ${needed}`)
+        error.permission = needed
+        throw error
+      }
+      if (r.kind === 'command' && !declared.has(r.name)) {
+        throw new PluginCallError('forbidden', `Command "${r.name}" ist nicht im Manifest deklariert`)
+      }
+    }
+    if (registrations.filter((r) => r.kind === 'job').length > R.jobsMax) {
+      throw new PluginCallError('quota_exceeded', `Mehr als ${R.jobsMax} Jobs registriert`)
+    }
+  }
+
+  function createRunner() {
+    return createPluginRunner(plugin, {
+      meta: { guildId, pluginId: manifest.id, locale, defaultLocale: manifest.locales.default, supportedLocales: manifest.locales.supported },
+      call,
+      locales: options.locales ?? {},
+      onRegister
+    })
+  }
+
+  function start() {
+    if (!startPromise) {
+      runner = createRunner()
+      startPromise = withFakeNow(clock, () => runner.start()).then((registrations) => {
+        jobTimers = registrations
+          .filter((r) => r.kind === 'job' && r.options?.intervalSeconds)
+          .map((r) => ({ name: r.name, intervalMs: r.options.intervalSeconds * 1000, next: clock.now() + r.options.intervalSeconds * 1000 }))
+        return registrations
+      })
+    }
+    return startPromise
+  }
+
+  async function stop() {
+    if (!startPromise) return
+    const current = runner
+    const pending = startPromise
+    startPromise = null
+    runner = null
+    jobTimers = []
+    await pending.catch(() => {})
+    await current.stop().catch(() => {})
+  }
+
+  function skipped(reason) {
+    return { ok: true, value: undefined, error: null, delivered: false, skipped: reason, replies: [], reply: null, calls: [], logs: [], durationMs: 0 }
+  }
+
+  function gate(actorUserId) {
+    if (!devMode) return true
+    return shouldDeliverInDev({ authorUserId, actorUserId, guildId, boundGuilds: [guildId] })
+  }
+
+  function buildInvoke(kind, extra, actorUserId) {
+    invocationCounter += 1
+    return {
+      type: 'invoke', v: PROTOCOL_VERSION, id: `t${invocationCounter}`, guildId, actorUserId: actorUserId ?? null, deadlineMs, kind, ...extra
+    }
+  }
+
+  async function execute(message) {
+    const frame = validateFrame(invokeSchema, message)
+    if (!frame.ok) throw new PluginValidationError(frame.errors)
+    await start()
+    const rec = { calls: [], replies: [], logs: [] }
+    records.set(frame.data.id, rec)
+    const began = performance.now()
+    let outcome
+    try {
+      outcome = await withFakeNow(clock, () => runner.invoke(frame.data))
+    } finally {
+      records.delete(frame.data.id)
+    }
+    return {
+      ok: outcome.ok,
+      value: outcome.value,
+      error: outcome.error ?? null,
+      delivered: true,
+      replies: rec.replies,
+      reply: rec.replies.find((r) => r.type === 'reply' || r.type === 'update')?.message ?? null,
+      calls: rec.calls,
+      logs: rec.logs,
+      durationMs: performance.now() - began
+    }
+  }
+
+  function interactionBase(opts = {}) {
+    const user = opts.user ?? makeUser({ id: authorUserId })
+    return {
+      interactionId: nextSnowflake(),
+      guildId,
+      channelId: opts.channelId ?? DEFAULT_IDS.channelId,
+      user,
+      member: opts.member ?? makeMember({ userId: user.id }),
+      locale
+    }
+  }
+
+  function resolveOptionList(command, name, group, sub) {
+    const label = [name, group, sub].filter(Boolean).join(' ')
+    const hasNested = command.subcommands.length > 0 || command.groups.length > 0
+    if (!hasNested) {
+      if (group || sub) throw new TypeError(`/${name} hat keine Subcommands`)
+      return { options: command.options, label }
+    }
+    if (!sub) throw new TypeError(`/${name} braucht einen Subcommand`)
+    let list = command.subcommands
+    if (group) {
+      const found = command.groups.find((g) => g.name === group)
+      if (!found) throw new TypeError(`Gruppe "${group}" ist für /${name} nicht deklariert`)
+      list = found.subcommands
+    }
+    const subcommand = list.find((c) => c.name === sub)
+    if (!subcommand) throw new TypeError(`Subcommand "${sub}" ist für /${label} nicht deklariert`)
+    return { options: subcommand.options, label }
+  }
+
+  function checkOptions(name, given, group, sub) {
+    const command = manifest.commands.find((c) => c.name === name)
+    if (!command) throw new TypeError(`Command "${name}" ist nicht im Manifest deklariert`)
+    const resolved = resolveOptionList(command, name, group, sub)
+    const known = new Map(resolved.options.map((o) => [o.name, o]))
+    for (const key of Object.keys(given)) {
+      if (!known.has(key)) throw new TypeError(`Unbekannte Option "${key}" für /${resolved.label}`)
+    }
+    for (const o of resolved.options) {
+      const value = given[o.name]
+      if (value === undefined) {
+        if (o.required) throw new TypeError(`Pflicht-Option "${o.name}" fehlt für /${resolved.label}`)
+        continue
+      }
+      const ok = { string: 'string', integer: 'number', number: 'number', boolean: 'boolean', user: 'string', channel: 'string', role: 'string' }[o.type]
+      if (typeof value !== ok || (o.type === 'integer' && !Number.isInteger(value))) {
+        throw new TypeError(`Option "${o.name}" hat den falschen Typ (erwartet ${o.type})`)
+      }
+      if (o.min !== undefined && value < o.min) throw new TypeError(`Option "${o.name}" unter min`)
+      if (o.max !== undefined && value > o.max) throw new TypeError(`Option "${o.name}" über max`)
+      if (o.maxLength !== undefined && typeof value === 'string' && value.length > o.maxLength) throw new TypeError(`Option "${o.name}" über maxLength`)
+      if (o.choices && !o.choices.some((c) => c.value === value)) throw new TypeError(`Option "${o.name}" ist keine gültige Auswahl`)
+    }
+  }
+
+  async function emit(name, payload, opts = {}) {
+    if (!EVENT_NAMES.includes(name)) throw new TypeError(`Unbekanntes Event "${name}"`)
+    const dto = structuredClone(payload ?? eventFixtures[name]())
+    if (!manifest.permissions.messageContent) {
+      if (dto.message) delete dto.message.content
+      delete dto.oldContent
+    }
+    const actor = opts.actorUserId !== undefined ? opts.actorUserId : actorOfEvent(name, dto)
+    if (!gate(actor)) return skipped('dev_not_author')
+    return execute(buildInvoke('event', { name, payload: dto }, actor))
+  }
+
+  async function runCommand(name, opts = {}) {
+    const given = opts.options ?? {}
+    checkOptions(name, given, opts.subcommandGroup, opts.subcommand)
+    const base = interactionBase(opts)
+    if (!gate(base.user.id)) return skipped('dev_not_author')
+    const nested = {
+      ...(opts.subcommandGroup ? { subcommandGroup: opts.subcommandGroup } : {}),
+      ...(opts.subcommand ? { subcommand: opts.subcommand } : {})
+    }
+    return execute(buildInvoke('command', { interaction: { ...base, kind: 'command', commandName: name, ...nested, options: given } }, base.user.id))
+  }
+
+  async function component(kind, customId, extra, opts) {
+    const base = interactionBase(opts)
+    if (!gate(base.user.id)) return skipped('dev_not_author')
+    return execute(buildInvoke('interaction', { interaction: { ...base, kind, customId, ...extra } }, base.user.id))
+  }
+
+  const pressButton = (customId, opts = {}) => component('button', customId, { messageId: opts.messageId ?? nextSnowflake() }, opts)
+  const selectOption = (customId, values, opts = {}) => component('select', customId, { messageId: opts.messageId ?? nextSnowflake(), values }, opts)
+  const submitModal = (customId, fields, opts = {}) => component('modal', customId, { fields }, opts)
+
+  async function runJob(name) {
+    return execute(buildInvoke('job', { name }, null))
+  }
+
+  async function runUi(kind, name, params, opts) {
+    const viewer = opts.viewer ?? makeUser({ id: authorUserId })
+    const result = await execute(buildInvoke(kind, { name, params, viewer }, viewer.id))
+    if (result.ok && kind === 'uiAction') {
+      const check = validate(actionResultSchema, result.value)
+      if (!check.ok) return { ...result, ok: false, error: { code: 'invalid_args', message: `Aktionsergebnis ungültig: ${issueSummary(check.errors)}` } }
+    }
+    if (result.ok && opts.schema) {
+      const check = validate(DATA_SCHEMAS[opts.schema], result.value)
+      if (!check.ok) return { ...result, ok: false, error: { code: 'invalid_args', message: `Daten ungültig (${opts.schema}): ${issueSummary(check.errors)}` } }
+    }
+    return result
+  }
+
+  const runUiData = (name, params = {}, opts = {}) => runUi('uiData', name, params, opts)
+  const runUiAction = (name, params = {}, opts = {}) => runUi('uiAction', name, params, opts)
+
+  async function advance(ms) {
+    await start()
+    const target = clock.now() + ms
+    const results = []
+    for (;;) {
+      const due = jobTimers.filter((j) => j.next <= target).sort((a, b) => a.next - b.next)[0]
+      if (!due) break
+      clock.set(due.next)
+      due.next += due.intervalMs
+      results.push({ name: due.name, ...(await runJob(due.name)) })
+    }
+    clock.set(target)
+    return results
+  }
+
+  return {
+    manifest,
+    ids: { guildId, authorUserId },
+    start,
+    stop,
+    restart: async () => {
+      await stop()
+      return start()
+    },
+    registrations: async () => {
+      await start()
+      return runner.registry()
+    },
+    emit,
+    runCommand,
+    pressButton,
+    selectOption,
+    submitModal,
+    runJob,
+    runUiData,
+    runUiAction,
+    storage: {
+      get: kv.get, set: kv.set, delete: kv.delete, list: kv.list, incr: kv.incr, entries: kv.entries, clear: kv.clear, usedBytes: kv.usedBytes, quotaBytes: kv.quotaBytes
+    },
+    config: {
+      set: setConfig,
+      get: (key) => structuredClone(configValues[key] ?? null),
+      all: () => structuredClone(configValues)
+    },
+    http: {
+      mock: (matcher, responder) => { mocks.push({ matcher, responder }) },
+      reset: () => { mocks.length = 0 },
+      requests: httpRequests
+    },
+    discord: {
+      calls: discordCalls,
+      messages: discordMessages,
+      respond: (action, value) => { discordResponders.set(action, value) },
+      fail: (action, code = 'discord_failed', message) => {
+        discordResponders.set(action, () => { throw new PluginCallError(code, message ?? code) })
+      },
+      reset: () => {
+        discordCalls.length = 0
+        discordMessages.length = 0
+        discordResponders.clear()
+      }
+    },
+    calls: allCalls,
+    logs: allLogs,
+    clock: {
+      now: clock.now,
+      set: (value) => clock.set(typeof value === 'number' ? value : Date.parse(value)),
+      advance
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,7 @@
+export { createTestHarness } from './harness.js'
+export { createMemoryKv } from './storage.js'
+export { PluginCallError, createPluginRunner, createTranslator } from './runner.js'
+export {
+  DEFAULT_IDS, actorOfEvent, eventFixtures, makeMember, makeMessage, makeUser, nextSnowflake
+} from './fixtures.js'
+export { createProjectHarness, loadLocales, loadPluginProject } from './project.js'

package/src/project.js

@@ -0,0 +1,32 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createTestHarness } from './harness.js'
+
+export async function loadLocales(dir) {
+  const locales = {}
+  let files = []
+  try {
+    files = await readdir(join(dir, 'locales'))
+  } catch {
+    return locales
+  }
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue
+    locales[file.slice(0, -5)] = JSON.parse(await readFile(join(dir, 'locales', file), 'utf8'))
+  }
+  return locales
+}
+
+export async function loadPluginProject(dir) {
+  const root = resolve(dir)
+  const manifest = JSON.parse(await readFile(join(root, 'manifest.json'), 'utf8'))
+  const entry = join(root, manifest.main ?? 'index.js')
+  const module = await import(pathToFileURL(entry).href)
+  return { dir: root, manifest, locales: await loadLocales(root), plugin: module.default }
+}
+
+export async function createProjectHarness(dir, options = {}) {
+  const project = await loadPluginProject(dir)
+  return createTestHarness(project.plugin, { manifest: project.manifest, locales: project.locales, ...options })
+}

package/src/runner.js

@@ -0,0 +1,241 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+  DISCORD_ACTIONS, RUNTIME_LIMITS, isPluginDefinition, makeError
+} from '@texisoft/nexus-plugin-sdk'
+
+export class PluginCallError extends Error {
+  constructor(code, message) {
+    super(message ?? code)
+    this.name = 'PluginCallError'
+    this.code = code
+  }
+}
+
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error']
+
+function formatLogMessage(message) {
+  let text
+  try {
+    text = typeof message === 'string' ? message : JSON.stringify(message)
+  } catch {
+    text = String(message)
+  }
+  if (typeof text !== 'string' || text.length === 0) text = '(leer)'
+  return text.slice(0, RUNTIME_LIMITS.logMessageMax)
+}
+
+function resolveText(table, key) {
+  if (!table) return undefined
+  if (Object.hasOwn(table, key) && typeof table[key] === 'string') return table[key]
+  let node = table
+  for (const part of key.split('.')) {
+    if (node && typeof node === 'object' && Object.hasOwn(node, part)) node = node[part]
+    else return undefined
+  }
+  return typeof node === 'string' ? node : undefined
+}
+
+export function createTranslator({ locales = {}, locale, defaultLocale }) {
+  return (key, vars = {}) => {
+    const text = resolveText(locales[locale], key) ?? resolveText(locales[defaultLocale], key) ?? key
+    return text.replace(/\{(\w+)\}/g, (match, name) => (Object.hasOwn(vars, name) ? String(vars[name]) : match))
+  }
+}
+
+function toError(error) {
+  if (error instanceof PluginCallError) return makeError(error.code, error.message)
+  return makeError('plugin_error', error?.message ?? String(error))
+}
+
+export function toJsonValue(value) {
+  if (value === undefined) return undefined
+  try {
+    return JSON.parse(JSON.stringify(value))
+  } catch {
+    throw new PluginCallError('plugin_error', 'Rückgabewert ist kein gültiges JSON')
+  }
+}
+
+export function createPluginRunner(plugin, { meta, call, locales, onRegister } = {}) {
+  if (!isPluginDefinition(plugin)) throw new TypeError('createPluginRunner: erwartet ein Ergebnis von definePlugin')
+  const registry = []
+  const als = new AsyncLocalStorage()
+  let phase = 'new'
+  let ctx = null
+  const defaultLocale = meta.defaultLocale ?? meta.locale
+  const supportedLocales = meta.supportedLocales ?? [defaultLocale]
+  const currentLocale = () => als.getStore()?.locale ?? defaultLocale
+  const translate = (key, vars) => createTranslator({ locales, locale: currentLocale(), defaultLocale })(key, vars)
+
+  const rpc = (method, args) => {
+    if (phase !== 'running') {
+      return Promise.reject(new PluginCallError('unavailable', 'ctx-Aufrufe sind nur innerhalb eines Aufrufs erlaubt, nicht in setup()'))
+    }
+    return Promise.resolve(call(method, args ?? {}, als.getStore() ?? null))
+  }
+
+  const register = (kind, name, handler, options) => {
+    if (phase !== 'setup') throw new PluginCallError('unavailable', 'Registrierungen sind nur in setup() erlaubt')
+    if (typeof name !== 'string' || !name) throw new TypeError(`${kind}: Name muss ein nicht leerer String sein`)
+    if (typeof handler !== 'function') throw new TypeError(`${kind} "${name}": Handler muss eine Funktion sein`)
+    if (kind !== 'event' && registry.some((r) => r.kind === kind && r.name === name)) {
+      throw new TypeError(`doppelte Registrierung: ${kind}:${name}`)
+    }
+    registry.push({ kind, name, handler, options })
+  }
+
+  const log = Object.fromEntries(LOG_LEVELS.map((level) => [level, (message) => {
+    const store = als.getStore()
+    const promise = rpc('log.write', { level, message: formatLogMessage(message) }).catch(() => {})
+    store?.pending.add(promise)
+    promise.finally(() => store?.pending.delete(promise))
+  }]))
+
+  const interactionApi = Object.freeze({
+    reply: (message) => rpc('interaction.reply', { message }),
+    update: (message) => rpc('interaction.update', { message }),
+    defer: (options) => rpc('interaction.defer', options === undefined ? {} : options),
+    followUp: (message) => rpc('interaction.followUp', { message }),
+    showModal: (modal) => rpc('interaction.showModal', { modal })
+  })
+
+  const discord = Object.freeze(Object.fromEntries(
+    Object.keys(DISCORD_ACTIONS).map((action) => [action, (args = {}) => rpc(`discord.${action}`, args)])
+  ))
+
+  function buildCtx() {
+    return Object.freeze({
+      meta: Object.freeze({
+        guildId: meta.guildId,
+        pluginId: meta.pluginId,
+        get locale() {
+          return currentLocale()
+        }
+      }),
+      commands: Object.freeze({ on: (name, handler) => register('command', name, handler) }),
+      events: Object.freeze({ on: (name, handler) => register('event', name, handler) }),
+      interactions: Object.freeze({
+        button: (name, handler) => register('button', name, handler),
+        modal: (name, handler) => register('modal', name, handler),
+        select: (name, handler) => register('select', name, handler)
+      }),
+      jobs: Object.freeze({ schedule: (name, options, handler) => register('job', name, handler, options) }),
+      storage: Object.freeze({
+        kv: Object.freeze({
+          get: (key) => rpc('storage.kv.get', { key }),
+          set: (key, value, options) => rpc('storage.kv.set', {
+            key, value, ...(options && options.ttlSeconds !== undefined ? { ttlSeconds: options.ttlSeconds } : {})
+          }),
+          delete: (key) => rpc('storage.kv.delete', { key }),
+          list: (options) => rpc('storage.kv.list', options === undefined ? {} : options),
+          incr: (key, by) => rpc('storage.kv.incr', by === undefined ? { key } : { key, by })
+        })
+      }),
+      config: Object.freeze({
+        get: (key) => rpc('config.get', { key }),
+        getAll: () => rpc('config.getAll', {})
+      }),
+      http: Object.freeze({ fetch: (url, options) => rpc('http.fetch', { ...(options || {}), url }) }),
+      discord,
+      ui: Object.freeze({
+        data: (name, handler) => register('uiData', name, handler),
+        action: (name, handler) => register('uiAction', name, handler)
+      }),
+      log: Object.freeze(log),
+      t: translate
+    })
+  }
+
+  function selectHandlers(msg) {
+    if (msg.kind === 'event') return registry.filter((r) => r.kind === 'event' && r.name === msg.name)
+    if (msg.kind === 'command') return registry.filter((r) => r.kind === 'command' && r.name === msg.interaction.commandName)
+    if (msg.kind === 'interaction') {
+      const kind = msg.interaction.kind
+      const id = msg.interaction.customId
+      const prefix = `plugin:${meta.pluginId}:`
+      const stripped = id.startsWith(prefix) ? id.slice(prefix.length) : id
+      const ofKind = registry.filter((r) => r.kind === kind)
+      for (const candidate of [id, stripped]) {
+        const exact = ofKind.filter((r) => r.name === candidate)
+        if (exact.length > 0) return exact
+      }
+      const byPrefix = ofKind.find((r) => stripped.startsWith(`${r.name}:`))
+      return byPrefix ? ofKind.filter((r) => r.name === byPrefix.name) : []
+    }
+    return registry.filter((r) => r.kind === msg.kind && r.name === msg.name)
+  }
+
+  function runHandler(handler, msg) {
+    switch (msg.kind) {
+      case 'event': return handler(msg.payload, ctx)
+      case 'command':
+      case 'interaction': return handler(msg.interaction, interactionApi)
+      case 'job': return handler(Object.freeze({ name: msg.name }))
+      default: return handler(msg.params ?? {}, Object.freeze({ viewer: msg.viewer ?? null }))
+    }
+  }
+
+  async function start() {
+    if (phase !== 'new') throw new Error('Runner ist bereits gestartet')
+    phase = 'setup'
+    ctx = buildCtx()
+    await plugin.setup(ctx)
+    phase = 'running'
+    const registrations = registry.map((r) => ({ kind: r.kind, name: r.name, ...(r.options ? { options: r.options } : {}) }))
+    if (onRegister) await onRegister(registrations)
+    return registrations
+  }
+
+  async function invoke(msg) {
+    const requested = typeof msg.interaction?.locale === 'string' ? msg.interaction.locale.slice(0, 2).toLowerCase() : null
+    const inv = {
+      locale: requested && supportedLocales.includes(requested) ? requested : defaultLocale,
+      id: msg.id,
+      kind: msg.kind,
+      guildId: msg.guildId,
+      actorUserId: msg.actorUserId ?? null,
+      pending: new Set(),
+      state: { calls: 0, http: 0, replied: false, deferred: false }
+    }
+    let timer
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => resolve({ ok: false, error: makeError('timeout', 'Frist überschritten') }), msg.deadlineMs ?? RUNTIME_LIMITS.invocationDeadlineMs)
+    })
+    const work = als.run(inv, async () => {
+      try {
+        if (phase !== 'running') throw new PluginCallError('unavailable', 'Runner ist nicht gestartet')
+        const handlers = selectHandlers(msg)
+        if (handlers.length === 0) throw new PluginCallError('not_registered', 'Kein Handler registriert')
+        let value
+        let firstError = null
+        for (const entry of handlers) {
+          try {
+            const result = await runHandler(entry.handler, msg)
+            if (result !== undefined && value === undefined) value = result
+          } catch (error) {
+            if (firstError === null) firstError = error
+          }
+        }
+        await Promise.allSettled([...inv.pending])
+        if (firstError !== null) throw firstError
+        if (msg.kind === 'uiData' || msg.kind === 'uiAction') return { ok: true, value: toJsonValue(value) }
+        return { ok: true, value: undefined }
+      } catch (error) {
+        return { ok: false, error: toError(error) }
+      }
+    })
+    try {
+      return await Promise.race([work, deadline])
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  async function stop() {
+    const previous = phase
+    phase = 'stopped'
+    if (previous === 'running' && typeof plugin.teardown === 'function') await plugin.teardown(ctx)
+  }
+
+  return { start, invoke, stop, registry: () => registry.map(({ kind, name, options }) => ({ kind, name, options })) }
+}

package/src/storage.js

@@ -0,0 +1,87 @@
+import { utf8Size } from '@texisoft/nexus-plugin-sdk'
+import { PluginCallError } from './runner.js'
+
+export function createMemoryKv({ quotaKb = 0, now = () => Date.now() } = {}) {
+  const quotaBytes = quotaKb * 1024
+  const map = new Map()
+
+  const entrySize = (key, value) => utf8Size(key) + utf8Size(value)
+
+  function purge() {
+    const t = now()
+    for (const [key, entry] of map) {
+      if (entry.expiresAt !== null && entry.expiresAt <= t) map.delete(key)
+    }
+  }
+
+  function usedBytes() {
+    purge()
+    let total = 0
+    for (const [key, entry] of map) total += entrySize(key, entry.value)
+    return total
+  }
+
+  function assertQuota(key, value) {
+    const existing = map.get(key)
+    const next = usedBytes() - (existing ? entrySize(key, existing.value) : 0) + entrySize(key, value)
+    if (next > quotaBytes) {
+      throw new PluginCallError('quota_exceeded', `Speicherkontingent von ${quotaKb} KB überschritten`)
+    }
+  }
+
+  function get(key) {
+    purge()
+    const entry = map.get(key)
+    return entry ? structuredClone(entry.value) : null
+  }
+
+  function set(key, value, { ttlSeconds } = {}) {
+    purge()
+    const cloned = structuredClone(value)
+    assertQuota(key, cloned)
+    map.set(key, { value: cloned, expiresAt: ttlSeconds ? now() + ttlSeconds * 1000 : null })
+  }
+
+  function remove(key) {
+    purge()
+    map.delete(key)
+  }
+
+  function list({ prefix = '', limit = 100, cursor } = {}) {
+    purge()
+    const keys = [...map.keys()].filter((k) => k.startsWith(prefix)).sort()
+    const start = cursor ? keys.findIndex((k) => k > cursor) : 0
+    if (start === -1) return { keys: [] }
+    const page = keys.slice(start, start + limit)
+    const more = start + limit < keys.length
+    return more ? { keys: page, cursor: page[page.length - 1] } : { keys: page }
+  }
+
+  function incr(key, by = 1) {
+    purge()
+    const existing = map.get(key)
+    const current = existing ? existing.value : 0
+    if (typeof current !== 'number' || !Number.isFinite(current)) {
+      throw new PluginCallError('invalid_args', `Wert von "${key}" ist keine Zahl`)
+    }
+    const next = current + by
+    assertQuota(key, next)
+    map.set(key, { value: next, expiresAt: existing ? existing.expiresAt : null })
+    return next
+  }
+
+  return {
+    get,
+    set,
+    delete: remove,
+    list,
+    incr,
+    usedBytes,
+    quotaBytes: () => quotaBytes,
+    entries: () => {
+      purge()
+      return Object.fromEntries([...map].map(([k, e]) => [k, structuredClone(e.value)]))
+    },
+    clear: () => map.clear()
+  }
+}