@meith/plugin-kit 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/plugin-kit",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "The SDK for writing a Meith plugin: typed manifests, hooks, routes, pages and migrations.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/core": "^0.21.1",
-    "@meith/theme-kit": "^0.21.1"
+    "@meith/core": "^0.22.0",
+    "@meith/theme-kit": "^0.22.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/src/host.ts

@@ -2,7 +2,13 @@ import type { ReactNode } from 'react'
 
 import { HOOKS, type HookName } from './hooks'
 import type { HookContext, HookValue } from './payloads'
-import type { HookRegistration, PluginContribution, PluginDefinition } from './plugin'
+import type {
+  HookRegistration,
+  HookRuntime,
+  PluginContribution,
+  PluginDefinition,
+  PluginRuntimeContext,
+} from './plugin'
 import type { PluginRegion, PluginRegionContext } from './regions'
 
 export interface HostLogger {
@@ -17,10 +23,6 @@ export interface PluginFailure {
   readonly threshold: number
 }
 
-/**
- * Where a failure goes once the host has counted it. The host stays
- * synchronous and fire-and-forgets; whoever supplies this owns the write.
- */
 export interface PluginHealthSink {
   readonly failed: (failure: PluginFailure) => void
 }
@@ -30,6 +32,8 @@ export interface DurablyDisabledPlugin {
   readonly reason: string
 }
 
+export type PluginRuntimeProvider = (pluginKey: string) => Promise<PluginRuntimeContext>
+
 export interface PluginHostOptions {
   readonly plugins: readonly PluginDefinition[]
   readonly logger?: HostLogger | undefined
@@ -37,6 +41,7 @@ export interface PluginHostOptions {
   readonly slowCallMs?: number | undefined
   readonly now?: (() => number) | undefined
   readonly health?: PluginHealthSink | undefined
+  readonly runtime?: PluginRuntimeProvider | undefined
 }
 
 export interface PluginHealth {
@@ -52,7 +57,7 @@ export interface PluginHealth {
   readonly lastError: { readonly hook: string; readonly message: string } | null
 }
 
-type StoredHandler = (value: unknown, context: unknown) => unknown
+type StoredHandler = (value: unknown, context: unknown, runtime: HookRuntime) => unknown
 
 interface Entry {
   readonly pluginKey: string
@@ -86,6 +91,7 @@ export class PluginHost {
   readonly #slowCallMs: number
   readonly #now: () => number
   readonly #health: PluginHealthSink
+  readonly #runtime: PluginRuntimeProvider
 
   constructor(options: PluginHostOptions) {
     this.#logger = options.logger ?? { warn: () => {}, error: () => {} }
@@ -93,6 +99,15 @@ export class PluginHost {
     this.#slowCallMs = options.slowCallMs ?? 50
     this.#now = options.now ?? (() => performance.now())
     this.#health = options.health ?? { failed: () => {} }
+    this.#runtime =
+      options.runtime ??
+      ((pluginKey) =>
+        Promise.reject(
+          new Error(
+            `plugin "${pluginKey}": this host was built without a runtime provider, so a hook ` +
+              'handler cannot reach settings, data, grants, users or notifications here.',
+          ),
+        ))
 
     for (const plugin of options.plugins) {
       this.#stats.set(plugin.key, {
@@ -158,7 +173,9 @@ export class PluginHost {
     for (const entry of entries) {
       if (!this.#isEnabled(entry.pluginKey)) continue
 
-      const result = await this.#call(entry.pluginKey, name, () => entry.handler(current, context))
+      const result = await this.#call(entry.pluginKey, name, () =>
+        entry.handler(current, context, this.#runtimeFor(entry.pluginKey)),
+      )
 
       if (result.ok && result.value !== undefined) current = result.value as HookValue<K>
     }
@@ -175,7 +192,17 @@ export class PluginHost {
 
     for (const entry of entries) {
       if (!this.#isEnabled(entry.pluginKey)) continue
-      await this.#call(entry.pluginKey, name, () => entry.handler(value, context))
+      await this.#call(entry.pluginKey, name, () =>
+        entry.handler(value, context, this.#runtimeFor(entry.pluginKey)),
+      )
+    }
+  }
+
+  #runtimeFor(pluginKey: string): HookRuntime {
+    let pending: Promise<PluginRuntimeContext> | null = null
+    return () => {
+      pending ??= this.#runtime(pluginKey)
+      return pending
     }
   }
 
@@ -234,11 +261,6 @@ export class PluginHost {
     }
   }
 
-  /**
-   * Reconcile against the durable record. The stored rows are the answer,
-   * not a hint: a plugin an operator has cleared comes back without a
-   * restart, and one another instance switched off is off here too.
-   */
   setDurablyDisabled(rows: readonly DurablyDisabledPlugin[]): void {
     const disabled = new Map(rows.map((row) => [row.key, row.reason]))
 

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   type PluginHealthSink,
   PluginHost,
   type PluginHostOptions,
+  type PluginRuntimeProvider,
 } from './host'
 export {
   type PluginNavigationPlacement,
@@ -44,6 +45,7 @@ export {
   type FilterHandler,
   type HookHandler,
   type HookRegistration,
+  type HookRuntime,
   MAX_ROUTE_BODY_BYTES,
   type PluginAdminPage,
   type PluginAdminPageContext,
@@ -76,6 +78,8 @@ export {
   pluginSettingKey,
   pluginTablePrefix,
   pluginTaskId,
+  unavailableHookRuntime,
+  unavailablePluginRuntime,
 } from './plugin'
 export {
   createRouteRateLimiter,

package/src/navigation.ts

@@ -9,7 +9,6 @@ export interface PluginNavigationPlacement {
   readonly key: string
   readonly href: string
   readonly audience: PluginNavigationAudience
-  /** The namespaced key of the sibling item this one sits under by default. */
   readonly parentKey: string | null
   readonly label: string
   readonly labelKey: string | null

package/src/plugin.ts

@@ -5,16 +5,29 @@ import type { Translator } from '@meith/theme-kit'
 import { type HOOKS, type HookName, isHookName } from './hooks'
 import type { HookContext, HookValue } from './payloads'
 import { isPluginRegion, type PluginRegion, type PluginRegionContext } from './regions'
-import type { PluginData, PluginGrants, PluginNotify, PluginUsers } from './runtime'
+import {
+  type PluginData,
+  type PluginGrants,
+  type PluginNotify,
+  type PluginUsers,
+  unavailablePluginData,
+  unavailablePluginGrants,
+  unavailablePluginNotify,
+  unavailablePluginUsers,
+} from './runtime'
+
+export type HookRuntime = () => Promise<PluginRuntimeContext>
 
 export type FilterHandler<K extends HookName> = (
   value: HookValue<K>,
   context: HookContext<K>,
+  runtime: HookRuntime,
 ) => HookValue<K> | Promise<HookValue<K>>
 
 export type EventHandler<K extends HookName> = (
   value: HookValue<K>,
   context: HookContext<K>,
+  runtime: HookRuntime,
 ) => void | Promise<void>
 
 export type HookHandler<K extends HookName> = (typeof HOOKS)[K]['kind'] extends 'filter'
@@ -153,28 +166,13 @@ type TranslationArgs = Parameters<Translator['t']>[1]
 
 export type PluginNavigationAudience = 'all' | 'guests' | 'members' | 'staff'
 
-/**
- * A board navigation entry a plugin asks for.
- *
- * It is a **request, not a placement**: the host writes it into the board's own
- * navigation table, where an operator renames, reorders, nests, scopes or hides
- * it like any other item. A plugin that appended to the header model instead
- * would put a link where no operator could reach it.
- */
 export interface PluginNavigationItem {
   readonly key: string
   readonly label: string
   readonly labelKey?: string | undefined
   readonly labelArgs?: TranslationArgs | undefined
-  /** A page path of this plugin's own — '' is its index page. */
   readonly path: string
   readonly audience?: PluginNavigationAudience | undefined
-  /**
-   * The `key` of another of this plugin's navigation items to sit under by
-   * default. The board's navigation is one level deep, so the item named here
-   * must itself be top-level. Like `audience`, it only seeds the row — the
-   * operator re-nests it like any other item.
-   */
   readonly under?: string | undefined
 }
 
@@ -191,6 +189,21 @@ export interface PluginRuntimeContext {
   readonly notify: PluginNotify
 }
 
+export function unavailablePluginRuntime(reason: string): PluginRuntimeContext {
+  return {
+    settings: {},
+    logger: { info: () => {}, warn: () => {}, error: () => {} },
+    grants: unavailablePluginGrants(reason),
+    data: unavailablePluginData(reason),
+    users: unavailablePluginUsers(reason),
+    notify: unavailablePluginNotify(reason),
+  }
+}
+
+export function unavailableHookRuntime(reason: string): HookRuntime {
+  return () => Promise.resolve(unavailablePluginRuntime(reason))
+}
+
 export interface PluginNotificationKind {
   readonly key: string
   readonly title: string
@@ -231,12 +244,6 @@ export interface PluginDefinition {
   readonly onUninstall?: ((context: PluginRuntimeContext) => Promise<void> | void) | undefined
 }
 
-/**
- * The rule a plugin key (and, by marketplace-gen.mjs's own mirrored copy, a
- * marketplace listing key) has to satisfy. Exported so
- * scripts/marketplace-gen.test.ts can pin its own copy directly against
- * this one rather than trusting the two stay in sync by comment alone.
- */
 export const KEY_PATTERN = /^[a-z][a-z0-9-]{1,39}$/
 const SETTING_KEY_PATTERN = /^[a-z][a-z0-9_]{1,39}$/
 const MIGRATION_ID_PATTERN = /^\d{4}_[a-z0-9_]{1,60}$/

package/src/settings.ts

@@ -47,11 +47,6 @@ export function parsePluginSetting(setting: PluginSetting, raw: string): PluginS
   return raw
 }
 
-/**
- * Matches a candidate select value against a setting's declared options —
- * trimmed and case-insensitively — and returns the *option's own* casing.
- * See "Settings" in docs/plugin-api.md.
- */
 function matchSelectOption(
   options: readonly { readonly value: string }[],
   candidate: PluginSettingValue | null,