@meith/plugin-kit 0.1.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@meith/plugin-kit",
+  "version": "0.1.0",
+  "description": "The SDK for writing a Meith plugin: typed manifests, hooks, routes, pages and migrations.",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/plugin-kit"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/theme-kit": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,497 @@
+/**
+ * The hook registry.
+ *
+ * Every point at which a plugin may observe or alter what the board does is
+ * named here, exactly once, with its **kind**. The registry is data for the same
+ * three reasons the slot registry is: a type map is derived from it, a host
+ * dispatches through it, and a documentation generator reads it.
+ *
+ * ## Two kinds, and the difference is the whole safety model
+ *
+ * A **filter** is handed a value and returns a replacement. Its result is used,
+ * so a filter that throws, hangs or returns rubbish changes what a reader sees.
+ * Filters are chained: each plugin receives what the previous one returned.
+ *
+ * An **event** is told that something happened and its return value is
+ * discarded. An event handler cannot change an outcome, which is why anything
+ * that merely wants to know — logging, an outbound webhook, a counter — must be
+ * an event and not a filter. Making it a filter would give it the power to
+ * corrupt the thing it only wanted to watch.
+ *
+ * The kind is declared rather than inferred because the same handler signature
+ * fits both, and the difference is invisible at the call site of a plugin.
+ *
+ * ## Deterministic
+ *
+ * "Typed deterministic hooks" is the acceptance criterion, and the second word
+ * is the harder one. Two plugins filtering the same value must compose the same
+ * way on every request, on every instance, in every deployment — otherwise a
+ * board's rendered output depends on module evaluation order, which differs
+ * between the dev server, a serverless bundle and the worker.
+ *
+ * So ordering is **(priority, plugin key)**, both total and both declared: never
+ * registration order, never the order `community.config.ts` happens to list plugins
+ * in, and never `Object.keys`. See `host.ts`.
+ *
+ * ## What is deliberately not here
+ *
+ * There is no hook that decides **authorization**, and there never will be one.
+ * `authorization.can()` is the single answer to "may this actor do this",
+ * and a plugin able to filter its result is a plugin able to grant itself
+ * anything. Plugins receive what a viewer may already see and change how it is
+ * presented or what happens afterwards.
+ *
+ * For the same reason there is no hook inside the visibility filter. A
+ * plugin that could rewrite a `where` clause is a plugin that can leak a private
+ * forum, and no amount of isolation makes that recoverable.
+ */
+
+export type HookKind = 'filter' | 'event'
+
+export interface HookSpec {
+  readonly kind: HookKind
+  /** What a plugin is seeing or changing. */
+  readonly purpose: string
+}
+
+/**
+ * Every hook, with its kind. `as const` so `HOOKS[K]['kind']` is a literal type
+ * and the handler signature can branch on it.
+ */
+export const HOOKS = {
+  /* ---- Content rendering ---- */
+  'markdown.parse.text': {
+    kind: 'filter',
+    purpose: 'The raw Markdown source, before it is parsed. Last chance to rewrite input.',
+  },
+  'markdown.render.html': {
+    kind: 'filter',
+    purpose:
+      'Rendered HTML, after the renderer has constructed it. Anything added here is ' +
+      'trusted output and nothing escapes it afterwards.',
+  },
+  'markdown.directives': {
+    kind: 'filter',
+    purpose:
+      'The declarative directive list, so a plugin can add a `:::name` block or ' +
+      '`:name[…]` span without core changes.',
+  },
+  'post.body.html': {
+    kind: 'filter',
+    purpose: 'One post’s rendered body, in the context of the thread it is being read in.',
+  },
+  'signature.html': {
+    kind: 'filter',
+    purpose: 'A member’s rendered signature, wherever it appears.',
+  },
+  'smilies.list': {
+    kind: 'filter',
+    purpose: 'The smilie set offered by the editor and substituted at render.',
+  },
+  'word-filter.patterns': {
+    kind: 'filter',
+    purpose: 'The render-time word filter’s pattern list.',
+  },
+
+  /* ---- View models ---- */
+  'view.header': {
+    kind: 'filter',
+    purpose: 'The header model, before the theme renders it.',
+  },
+  'view.user-panel': {
+    kind: 'filter',
+    purpose: 'The user panel model: greeting, counts, account links.',
+  },
+  'view.navigation': {
+    kind: 'filter',
+    purpose: 'The breadcrumb trail.',
+  },
+  'view.footer': {
+    kind: 'filter',
+    purpose: 'The footer model, including its link list.',
+  },
+  'view.forum-jump': {
+    kind: 'filter',
+    purpose:
+      'The jump box model. A plugin adding a destination must give it a real ' +
+      'forum id — the route re-authorises whatever is submitted.',
+  },
+  'view.announcement': {
+    kind: 'filter',
+    purpose:
+      'One announcement, on its way to the theme. Its body is already rendered ' +
+      'HTML from the board\u2019s own renderer, so a plugin replacing it is ' +
+      'replacing trusted markup — the one hook where that is true of a body.',
+  },
+  'view.board-index': {
+    kind: 'filter',
+    purpose: 'The index page model.',
+  },
+  'view.forum-row': {
+    kind: 'filter',
+    purpose: 'One forum row in a listing. Runs once per row — keep it cheap.',
+  },
+  'view.thread-row': {
+    kind: 'filter',
+    purpose: 'One thread row in a listing. Runs once per row.',
+  },
+  'view.post-bit': {
+    kind: 'filter',
+    purpose:
+      'One post as the theme will receive it. The busiest hook on the board: it ' +
+      'runs once per post on every thread page.',
+  },
+  'view.post-actions': {
+    kind: 'filter',
+    purpose: 'The per-post control links. Adding one here does not create permission to use it.',
+  },
+  'view.member-profile': {
+    kind: 'filter',
+    purpose: 'A member’s profile model, including its custom fields and action links.',
+  },
+  'view.board-stats': {
+    kind: 'filter',
+    purpose: 'The board totals block.',
+  },
+  'view.who-is-online': {
+    kind: 'filter',
+    purpose: 'The online list, already resolved against the reader.',
+  },
+  'view.latest-threads': {
+    kind: 'filter',
+    purpose:
+      'The index sidebar’s newest-threads panel. Runs again on every refresh ' +
+      'of the live region, not only on the page load — keep it cheap.',
+  },
+  'view.latest-posts': {
+    kind: 'filter',
+    purpose: 'The index sidebar’s newest-posts panel. Same refresh cost as view.latest-threads.',
+  },
+  'view.pagination': {
+    kind: 'filter',
+    purpose: 'A resolved page-link window.',
+  },
+  'view.search-form': {
+    kind: 'filter',
+    purpose: 'The search form model, including its filter options.',
+  },
+  'view.error-notice': {
+    kind: 'filter',
+    purpose: 'The error page model. Runs on the page that renders when things are broken.',
+  },
+  'view.shell': {
+    kind: 'filter',
+    purpose: 'The page frame’s model. Runs on every page including the error pages.',
+  },
+  'view.notice': {
+    kind: 'filter',
+    purpose: 'A board notice or flash message, before the theme renders it.',
+  },
+  'view.category-block': {
+    kind: 'filter',
+    purpose: 'One category on the index, with its rendered forum rows.',
+  },
+  'view.subforum-list': {
+    kind: 'filter',
+    purpose: 'The compact child-forum list above a thread listing.',
+  },
+  'view.forum-display': {
+    kind: 'filter',
+    purpose: 'A forum page’s model, including its rendered regions.',
+  },
+  'view.thread-view': {
+    kind: 'filter',
+    purpose: 'A thread page’s model, including its rendered post list.',
+  },
+  'view.post-form': {
+    kind: 'filter',
+    purpose: 'The composer page’s model. The form itself is app-rendered and arrives as a region.',
+  },
+  'view.redirect-notice': {
+    kind: 'filter',
+    purpose: 'The interstitial shown after a mutation, before the meta refresh fires.',
+  },
+
+  /* ---- Posting ---- */
+  'thread.create.validate': {
+    kind: 'filter',
+    purpose: 'Validation messages for a new thread. Returning a non-empty list refuses the post.',
+  },
+  'thread.create.before': {
+    kind: 'filter',
+    purpose: 'The thread draft, before it is written. Subject, body, prefix, options.',
+  },
+  'thread.created': {
+    kind: 'event',
+    purpose: 'A thread was created and committed.',
+  },
+  'post.create.validate': {
+    kind: 'filter',
+    purpose: 'Validation messages for a reply.',
+  },
+  'post.create.before': {
+    kind: 'filter',
+    purpose: 'The reply draft, before it is written.',
+  },
+  'post.created': {
+    kind: 'event',
+    purpose: 'A reply was created and committed.',
+  },
+  'post.edit.before': {
+    kind: 'filter',
+    purpose: 'An edit’s new body and reason, before the revision is written.',
+  },
+  'post.edited': {
+    kind: 'event',
+    purpose: 'A post was edited and a revision recorded.',
+  },
+  'post.delete.before': {
+    kind: 'event',
+    purpose: 'A post is about to be soft-deleted. Observation only: refusing is a permission.',
+  },
+  'post.deleted': {
+    kind: 'event',
+    purpose: 'A post was soft-deleted.',
+  },
+  'post.restored': {
+    kind: 'event',
+    purpose: 'A soft-deleted post was restored.',
+  },
+  'thread.moved': {
+    kind: 'event',
+    purpose: 'A thread changed forum. Carries both forum ids.',
+  },
+  'thread.merged': {
+    kind: 'event',
+    purpose: 'Two threads became one.',
+  },
+  'thread.split': {
+    kind: 'event',
+    purpose: 'Posts were split out into a new thread.',
+  },
+  'thread.locked': {
+    kind: 'event',
+    purpose: 'A thread was opened or closed.',
+  },
+  'thread.stickied': {
+    kind: 'event',
+    purpose: 'A thread was pinned or unpinned.',
+  },
+  'attachment.upload.validate': {
+    kind: 'filter',
+    purpose:
+      'Validation messages for an upload, after the magic-byte check. A plugin may ' +
+      'refuse a file core would accept; it can never accept one core refused.',
+  },
+  'attachment.uploaded': {
+    kind: 'event',
+    purpose: 'A file finished uploading and re-encoding.',
+  },
+  'attachment.deleted': {
+    kind: 'event',
+    purpose: 'An attachment was removed, by a member or by the orphan sweep.',
+  },
+  'poll.created': {
+    kind: 'event',
+    purpose: 'A poll was attached to a thread.',
+  },
+  'poll.voted': {
+    kind: 'event',
+    purpose: 'A vote was cast. Fires once; the database enforces one per member.',
+  },
+  'rating.recorded': {
+    kind: 'event',
+    purpose: 'A thread rating was recorded or changed.',
+  },
+
+  /* ---- Moderation ---- */
+  'report.created': {
+    kind: 'event',
+    purpose: 'Something was reported. The hook a notifier or a webhook wants.',
+  },
+  'report.resolved': {
+    kind: 'event',
+    purpose: 'A report was closed, with the resolution.',
+  },
+  'approval.queued': {
+    kind: 'event',
+    purpose: 'Content entered the approval queue.',
+  },
+  'approval.decided': {
+    kind: 'event',
+    purpose: 'Queued content was approved or rejected.',
+  },
+  'warning.issued': {
+    kind: 'event',
+    purpose: 'A warning was issued, with its points and expiry.',
+  },
+  'warning.revoked': {
+    kind: 'event',
+    purpose: 'A warning was revoked or expired.',
+  },
+  'moderation.logged': {
+    kind: 'event',
+    purpose: 'A moderation action was written to the log.',
+  },
+
+  /* ---- Identity ---- */
+  'user.register.validate': {
+    kind: 'filter',
+    purpose:
+      'Validation messages for a registration. Where a custom question or an ' +
+      'external blocklist belongs.',
+  },
+  'user.registered': {
+    kind: 'event',
+    purpose: 'An account was created, before or after activation depending on the mode.',
+  },
+  'user.activated': {
+    kind: 'event',
+    purpose: 'An account finished activation.',
+  },
+  'user.login.attempted': {
+    kind: 'event',
+    purpose:
+      'A sign-in was attempted, with the outcome. Never carries the password or the ' +
+      'session token.',
+  },
+  'user.logged-in': {
+    kind: 'event',
+    purpose: 'A session was established.',
+  },
+  'user.logged-out': {
+    kind: 'event',
+    purpose: 'A session was ended, by the member or by revocation.',
+  },
+  'user.banned': {
+    kind: 'event',
+    purpose: 'A member was banned, with the expiry when there is one.',
+  },
+  'user.unbanned': {
+    kind: 'event',
+    purpose: 'A ban was lifted or expired and the prior group restored.',
+  },
+  'user.groups.changed': {
+    kind: 'event',
+    purpose: 'Primary or secondary group membership changed.',
+  },
+  'user.profile.updated': {
+    kind: 'event',
+    purpose: 'A member saved profile or option changes.',
+  },
+  'user.merged': {
+    kind: 'event',
+    purpose: 'Two accounts were merged. Carries the winner and the account that went.',
+  },
+  'user.deleted': {
+    kind: 'event',
+    purpose: 'An account was pruned or deleted.',
+  },
+
+  /* ---- Mail, notifications, messages ---- */
+  'notification.create.before': {
+    kind: 'filter',
+    purpose: 'A notification about to be created. Returning `null` suppresses it.',
+  },
+  'notification.created': {
+    kind: 'event',
+    purpose: 'A notification was stored.',
+  },
+  'mail.send.before': {
+    kind: 'filter',
+    purpose:
+      'A queued message, before it is handed to the mail driver. Subject, body and ' +
+      'recipient; returning `null` drops it.',
+  },
+  'mail.sent': {
+    kind: 'event',
+    purpose: 'A message was accepted by the driver. Not proof of delivery.',
+  },
+  'pm.send.before': {
+    kind: 'filter',
+    purpose: 'A private message, before it is stored.',
+  },
+  'pm.sent': {
+    kind: 'event',
+    purpose: 'A private message was delivered to its recipients’ folders.',
+  },
+  'subscription.changed': {
+    kind: 'event',
+    purpose: 'A member subscribed to or unsubscribed from a thread or forum.',
+  },
+  'reputation.changed': {
+    kind: 'event',
+    purpose: 'Reputation was given, changed or removed.',
+  },
+
+  /* ---- Search, discovery, syndication ---- */
+  'search.query.before': {
+    kind: 'filter',
+    purpose: 'The parsed search terms, before the query runs. The scope is not filterable.',
+  },
+  'search.results': {
+    kind: 'filter',
+    purpose:
+      'A page of results, already permission-filtered in SQL. A plugin may reorder or ' +
+      'drop; adding a row here would add one the viewer may not see.',
+  },
+  'feed.items': {
+    kind: 'filter',
+    purpose: 'The items of a feed, rendered as a guest. Anything added is public.',
+  },
+  'sitemap.entries': {
+    kind: 'filter',
+    purpose: 'One chunk of the sitemap.',
+  },
+  'metadata.page': {
+    kind: 'filter',
+    purpose: 'Title, description and social card for a page.',
+  },
+
+  /* ---- Admin and system ---- */
+  'admin.navigation': {
+    kind: 'filter',
+    purpose: 'The admin panel’s section links, so a plugin page can be reached.',
+  },
+  'settings.saved': {
+    kind: 'event',
+    purpose: 'Board settings changed. Carries the keys, never the values.',
+  },
+  'task.run.before': {
+    kind: 'event',
+    purpose: 'A scheduled task is about to run.',
+  },
+  'task.run.after': {
+    kind: 'event',
+    purpose: 'A scheduled task finished, with its outcome and duration.',
+  },
+  'cache.invalidated': {
+    kind: 'event',
+    purpose: 'A cache tag was invalidated.',
+  },
+  'plugin.enabled': {
+    kind: 'event',
+    purpose: 'A plugin was enabled — including this one, which is how it learns it is on.',
+  },
+  'plugin.disabled': {
+    kind: 'event',
+    purpose:
+      'A plugin was disabled, by an operator or by the host after repeated failures. ' +
+      'Carries the reason.',
+  },
+} as const satisfies Readonly<Record<string, HookSpec>>
+
+/** Every hook name. Derived from the registry — never hand-written. */
+export type HookName = keyof typeof HOOKS
+
+/** The registry as an iterable list, in declaration order. */
+export const HOOK_NAMES = Object.keys(HOOKS) as readonly HookName[]
+
+/** Narrow an arbitrary string to a hook name. Used when validating a manifest. */
+export function isHookName(value: string): value is HookName {
+  return Object.hasOwn(HOOKS, value)
+}
+
+export function hookKind(name: HookName): HookKind {
+  return HOOKS[name].kind
+}