@meith/plugin-kit 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/plugin-kit",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The SDK for writing a Meith plugin: typed manifests, hooks, routes, pages and migrations.",
   "license": "LGPL-3.0-or-later",
   "repository": {
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/theme-kit": "^0.9.0"
+    "@meith/theme-kit": "^0.10.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/src/hooks.ts

@@ -74,7 +74,7 @@ export const HOOKS = {
     kind: 'filter',
     purpose:
       'The declarative directive list, so a plugin can add a `:::name` block or ' +
-      '`:name[…]` span without core changes.',
+      '`:name[…]` span without core changes. Board-wide: rendered bodies are stored and shared, so the set cannot depend on who is reading.',
   },
   'post.body.html': {
     kind: 'filter',
@@ -86,7 +86,9 @@ export const HOOKS = {
   },
   'smilies.list': {
     kind: 'filter',
-    purpose: 'The smilie set offered by the editor and substituted at render.',
+    purpose:
+      'The smilie set substituted at render. Board-wide, for the same reason ' +
+      'the directive list is.',
   },
   'word-filter.patterns': {
     kind: 'filter',
@@ -247,7 +249,9 @@ export const HOOKS = {
   },
   'view.redirect-notice': {
     kind: 'filter',
-    purpose: 'The interstitial shown after a mutation, before the meta refresh fires.',
+    purpose:
+      'The interstitial shown after a mutation, before the meta refresh fires. The target is re-checked against the board after the filter runs, so this ' +
+      'cannot send a member off-site.',
   },
 
   /* ---- Posting ---- */

package/src/host.ts

@@ -10,18 +10,40 @@ export interface HostLogger {
   readonly error: (message: string, detail: Record<string, unknown>) => void
 }
 
+export interface PluginFailure {
+  readonly pluginKey: string
+  readonly hook: string
+  readonly message: string
+  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
+}
+
+export interface DurablyDisabledPlugin {
+  readonly key: string
+  readonly reason: string
+}
+
 export interface PluginHostOptions {
   readonly plugins: readonly PluginDefinition[]
   readonly logger?: HostLogger | undefined
   readonly failureThreshold?: number | undefined
   readonly slowCallMs?: number | undefined
   readonly now?: (() => number) | undefined
+  readonly health?: PluginHealthSink | undefined
 }
 
 export interface PluginHealth {
   readonly key: string
   readonly enabled: boolean
   readonly operatorDisabled: boolean
+  readonly durablyDisabled: boolean
   readonly disabledReason: string | null
   readonly calls: number
   readonly failures: number
@@ -41,6 +63,7 @@ interface Entry {
 interface Stats {
   enabled: boolean
   operatorDisabled: boolean
+  durablyDisabled: boolean
   disabledReason: string | null
   calls: number
   failures: number
@@ -62,17 +85,20 @@ export class PluginHost {
   readonly #failureThreshold: number
   readonly #slowCallMs: number
   readonly #now: () => number
+  readonly #health: PluginHealthSink
 
   constructor(options: PluginHostOptions) {
     this.#logger = options.logger ?? { warn: () => {}, error: () => {} }
     this.#failureThreshold = options.failureThreshold ?? 5
     this.#slowCallMs = options.slowCallMs ?? 50
     this.#now = options.now ?? (() => performance.now())
+    this.#health = options.health ?? { failed: () => {} }
 
     for (const plugin of options.plugins) {
       this.#stats.set(plugin.key, {
         enabled: true,
         operatorDisabled: false,
+        durablyDisabled: false,
         disabledReason: null,
         calls: 0,
         failures: 0,
@@ -182,6 +208,7 @@ export class PluginHost {
         key,
         enabled: stats.enabled && !stats.operatorDisabled,
         operatorDisabled: stats.operatorDisabled,
+        durablyDisabled: stats.durablyDisabled,
         disabledReason: stats.disabledReason,
         calls: stats.calls,
         failures: stats.failures,
@@ -207,6 +234,32 @@ 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]))
+
+    for (const [key, stats] of this.#stats) {
+      const reason = disabled.get(key)
+
+      if (reason !== undefined) {
+        stats.durablyDisabled = true
+        stats.enabled = false
+        stats.disabledReason = reason
+        continue
+      }
+
+      if (stats.durablyDisabled) {
+        stats.durablyDisabled = false
+        stats.enabled = true
+        stats.disabledReason = null
+      }
+    }
+  }
+
   isEnabled(pluginKey: string): boolean {
     return this.#isEnabled(pluginKey)
   }
@@ -277,12 +330,10 @@ export class PluginHost {
     stats.lastError = { hook, message }
 
     this.#logger.error('plugin hook failed', { plugin: pluginKey, hook, message })
+    this.#health.failed({ pluginKey, hook, message, threshold: this.#failureThreshold })
 
     if (stats.failures >= this.#failureThreshold) {
-      this.disable(
-        pluginKey,
-        `${stats.failures} failures in this process, most recently in "${hook}"`,
-      )
+      this.disable(pluginKey, `${stats.failures} failures, most recently in "${hook}"`)
     }
   }
 }

package/src/index.ts

@@ -8,13 +8,21 @@ export {
   isHookName,
 } from './hooks'
 export {
+  type DurablyDisabledPlugin,
   emptyHost,
   type HostLogger,
   isFilter,
+  type PluginFailure,
   type PluginHealth,
+  type PluginHealthSink,
   PluginHost,
   type PluginHostOptions,
 } from './host'
+export {
+  type PluginNavigationPlacement,
+  pluginKeyOfNavigation,
+  pluginNavigationPlacements,
+} from './navigation'
 export type {
   DraftPayload,
   ForumRef,
@@ -44,6 +52,8 @@ export {
   type PluginDefinition,
   type PluginHooks,
   type PluginMigration,
+  type PluginNavigationAudience,
+  type PluginNavigationItem,
   type PluginNotificationKind,
   type PluginPageAccess,
   type PluginPageContext,
@@ -59,6 +69,7 @@ export {
   type PluginViewer,
   pluginAdminPath,
   pluginAdminRoutePath,
+  pluginNavigationKey,
   pluginNotificationKindId,
   pluginPagePath,
   pluginRoutePath,
@@ -79,6 +90,11 @@ export {
   REGION_NAMES,
   type RegionSpec,
 } from './regions'
+export {
+  renderingSignature,
+  rendersStoredContent,
+  STORED_RENDER_HOOKS,
+} from './rendering'
 export {
   type PluginData,
   type PluginGrantRow,

package/src/navigation.ts

@@ -0,0 +1,40 @@
+import {
+  type PluginDefinition,
+  type PluginNavigationAudience,
+  pluginNavigationKey,
+  pluginPagePath,
+} from './plugin'
+
+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
+  readonly labelArgs: Record<string, string | number> | null
+}
+
+export function pluginNavigationPlacements(
+  plugins: readonly PluginDefinition[],
+): readonly PluginNavigationPlacement[] {
+  return plugins.flatMap((plugin) =>
+    (plugin.navigation ?? []).map((item) => ({
+      key: pluginNavigationKey(plugin.key, item.key),
+      href: pluginPagePath(plugin.key, item.path),
+      audience: item.audience ?? ('all' as const),
+      parentKey: item.under === undefined ? null : pluginNavigationKey(plugin.key, item.under),
+      label: item.label,
+      labelKey: item.labelKey ?? null,
+      labelArgs: (item.labelArgs ?? null) as Record<string, string | number> | null,
+    })),
+  )
+}
+
+export function pluginKeyOfNavigation(key: string | null): string | null {
+  if (key === null) return null
+
+  const parts = key.split('.')
+  return parts.length === 3 && parts[0] === 'plugin' ? (parts[1] ?? null) : null
+}

package/src/payloads.ts

@@ -148,15 +148,22 @@ export interface HookSignatures {
     value: string
     context: ViewerRef & { source: 'post' | 'signature' | 'pm' }
   }
-  'markdown.directives': { value: readonly string[]; context: ForumRef | Record<string, never> }
+  'markdown.directives': {
+    value: readonly { readonly name: string; readonly block: boolean }[]
+    context: ForumRef | Record<string, never>
+  }
   'post.body.html': { value: string; context: PostRef & ViewerRef }
   'signature.html': { value: string; context: ViewerRef & { authorId: number } }
   'smilies.list': {
-    value: readonly { readonly code: string; readonly imageUrl: string }[]
-    context: ViewerRef
+    value: readonly { readonly code: string; readonly src: string; readonly alt?: string }[]
+    context: Record<string, never>
   }
   'word-filter.patterns': {
-    value: readonly { readonly pattern: string; readonly replacement: string }[]
+    value: readonly {
+      readonly pattern: string
+      readonly replacement: string
+      readonly wholeWord: boolean
+    }[]
     context: Record<string, never>
   }
 

package/src/plugin.ts

@@ -149,6 +149,35 @@ export interface PluginBoardPage {
   readonly render: (context: PluginPageContext) => ReactNode | Promise<ReactNode>
 }
 
+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
+}
+
 export interface PluginRuntimeContext {
   readonly settings: Readonly<Record<string, string | number | boolean>>
   readonly logger: {
@@ -169,6 +198,7 @@ export interface PluginNotificationKind {
   readonly description: string
   readonly descriptionKey?: string | undefined
   readonly emailByDefault?: boolean | undefined
+  readonly pushByDefault?: boolean | undefined
 }
 
 export interface PluginDefinition {
@@ -192,6 +222,7 @@ export interface PluginDefinition {
   readonly routes?: readonly PluginRoute[] | undefined
   readonly pages?: readonly PluginBoardPage[] | undefined
   readonly notifications?: readonly PluginNotificationKind[] | undefined
+  readonly navigation?: readonly PluginNavigationItem[] | undefined
   readonly allowedRedirectHosts?: readonly string[] | undefined
 
   readonly onInstall?: ((context: PluginRuntimeContext) => Promise<void> | void) | undefined
@@ -540,6 +571,64 @@ export function definePlugin(plugin: PluginDefinition): PluginDefinition {
     }
   }
 
+  assertUnique(
+    where,
+    'navigation item',
+    (plugin.navigation ?? []).map((item) => item.key),
+  )
+  for (const item of plugin.navigation ?? []) {
+    if (!TASK_ID_PATTERN.test(item.key)) {
+      throw new Error(
+        `${where}: navigation key "${item.key}" must be lower-case letters, digits and ` +
+          `hyphens. It becomes plugin.<plugin>.<key> in the board’s navigation, which is ` +
+          `how an operator’s edits survive a redeploy.`,
+      )
+    }
+    if (item.label.trim() === '') {
+      throw new Error(
+        `${where}: navigation item "${item.key}" needs a label — it is what the item is ` +
+          `called until an operator renames it.`,
+      )
+    }
+    if (item.path !== '' && !PAGE_PATH_PATTERN.test(item.path)) {
+      throw new Error(
+        `${where}: navigation item "${item.key}" points at "${item.path}", which is not ` +
+          `one of this plugin’s page paths. A navigation item links to a page the ` +
+          `plugin declares, not to anywhere on the board.`,
+      )
+    }
+    if (!(plugin.pages ?? []).some((page) => page.path === item.path)) {
+      throw new Error(
+        `${where}: navigation item "${item.key}" points at the page "${item.path}", ` +
+          `which this plugin does not declare.`,
+      )
+    }
+    if (
+      item.audience !== undefined &&
+      !['all', 'guests', 'members', 'staff'].includes(item.audience)
+    ) {
+      throw new Error(
+        `${where}: navigation item "${item.key}" audience must be all, guests, members ` +
+          `or staff.`,
+      )
+    }
+    if (item.under !== undefined) {
+      const parent = (plugin.navigation ?? []).find((other) => other.key === item.under)
+      if (parent === undefined || parent.key === item.key) {
+        throw new Error(
+          `${where}: navigation item "${item.key}" sits under "${item.under}", which is ` +
+            `not another navigation item of this plugin.`,
+        )
+      }
+      if (parent.under !== undefined) {
+        throw new Error(
+          `${where}: navigation item "${item.key}" cannot sit under "${item.under}", ` +
+            `which is itself nested — the board’s navigation is one level deep.`,
+        )
+      }
+    }
+  }
+
   assertUnique(
     where,
     'notification kind',
@@ -608,3 +697,7 @@ export function pluginAdminRoutePath(pluginKey: string, path: string): string {
 export function pluginPagePath(pluginKey: string, path: string): string {
   return `/plugins/${pluginKey}${path === '' ? '' : `/${path}`}`
 }
+
+export function pluginNavigationKey(pluginKey: string, itemKey: string): string {
+  return `plugin.${pluginKey}.${itemKey}`
+}

package/src/rendering.ts

@@ -0,0 +1,29 @@
+import type { HookName } from './hooks'
+import type { PluginDefinition } from './plugin'
+
+export const STORED_RENDER_HOOKS: readonly HookName[] = [
+  'markdown.parse.text',
+  'markdown.render.html',
+  'markdown.directives',
+  'smilies.list',
+]
+
+export function rendersStoredContent(plugin: PluginDefinition): boolean {
+  const hooks = Object.keys(plugin.hooks ?? {})
+  return STORED_RENDER_HOOKS.some((hook) => hooks.includes(hook))
+}
+
+export function renderingSignature(plugins: readonly PluginDefinition[]): number {
+  const parts = plugins
+    .filter(rendersStoredContent)
+    .map((plugin) => `${plugin.key}@${plugin.version}`)
+    .sort()
+
+  let hash = 2_166_136_261
+  for (const character of parts.join(',')) {
+    hash ^= character.codePointAt(0) ?? 0
+    hash = Math.imul(hash, 16_777_619)
+  }
+
+  return (hash >>> 1) + 1
+}

package/src/runtime.ts

@@ -104,6 +104,7 @@ export interface PluginNotifyKindInput {
   readonly description: string
   readonly descriptionKey?: string | undefined
   readonly emailByDefault?: boolean | undefined
+  readonly pushByDefault?: boolean | undefined
 }
 
 export interface PluginNotificationKindSpec {
@@ -115,6 +116,8 @@ export interface PluginNotificationKindSpec {
   readonly audience: 'member'
   readonly emailByDefault: boolean
   readonly emailConfigurable: true
+  readonly pushByDefault: boolean
+  readonly pushConfigurable: true
 }
 
 export interface PluginNotifyBackend {
@@ -140,6 +143,8 @@ export function pluginNotificationKindSpecs(
     audience: 'member',
     emailByDefault: kind.emailByDefault ?? true,
     emailConfigurable: true,
+    pushByDefault: kind.pushByDefault ?? false,
+    pushConfigurable: true,
   }))
 }