@jwilleke/ngdpbase-types 5.24.0 → 5.25.0

package/README.md

@@ -12,6 +12,6 @@ import { buildAddonHost, openAddonTestDatabase, toCsv, formatters } from '@jwill
 ```
 
 - The main entry is types only. Importing it at run time fails, on purpose.
-- `/testing` is for tests. `buildAddonHost(slug, defaults)` is the real host. `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
+- `/testing` is for tests. `buildAddonHost(slug, defaults, setEnabledForPerson?, engine?)` is the real host; `host.setEnabledForPerson` calls the setter you pass (it refuses without one), and `engine` names the system principal `host.systemContext(reason)` uses (core's fallback without one). `openAddonTestDatabase(owner, { migrations, ledgerTable })` is the handle `openAddonDatabase` returns, in memory. `toCsv` is `ExportManager.toCsv`. `formatters` is a plugin's `context.formatters`.
 
 The add-on guide is [docs/guides/addons-developer-guide.md](https://github.com/jwilleke/ngdpbase/blob/master/docs/guides/addons-developer-guide.md).

package/lib/packages/ngdpbase-types/index.d.ts

@@ -14,8 +14,8 @@
  * `@jwilleke/ngdpbase-types/testing`. A test holds this file to `export type`
  * only, so the published entry carries no JavaScript.
  */
-export type { AddonModule } from '../../src/managers/AddonsManager.js';
-export type { AddonHost } from '../../src/utils/addonHost.js';
+export type { AddonModule, AddonManifest, AddonListing } from '../../src/managers/AddonsManager.js';
+export type { AddonHost, PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export type { WikiEngine } from '../../src/types/WikiEngine.js';
 export type { ApiContext } from '../../src/context/ApiContext.js';
 export type { ActorContext } from '../../src/context/ActorContext.js';

package/lib/packages/ngdpbase-types/testing.d.ts

@@ -4,7 +4,7 @@
 import ExportManager from '../../src/managers/ExportManager.js';
 import { type AddonDatabaseOptions } from '../../src/managers/DatabaseManager.js';
 import { type SqliteHandle } from '../../src/providers/SqliteDatabaseProvider.js';
-import { type AddonHost } from '../../src/utils/addonHost.js';
+import { buildAddonHost as buildHost, type AddonHost, type PersonSwitchSetter } from '../../src/utils/addonHost.js';
 export { formatters } from '../../src/managers/PluginManager.js';
 /**
  * Core's `buildAddonHost`, with the audit registry bound to this add-on's
@@ -15,8 +15,13 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - The add-on's own `config/default-config.json`
+ * @param setEnabledForPerson - What `host.setEnabledForPerson` does in the
+ *   test (#1963); a site binds core's setter. Without one it refuses.
+ * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
+ *   names the system principal for `host.systemContext`; without one it is
+ *   core's fallback principal
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof buildHost>[3]): AddonHost;
 /** The add-on whose declaration a test database is checked against: its slug and its own `config/default-config.json`. */
 export interface AddonTestDatabaseDeclarer {
     slug: string;

package/lib/packages/ngdpbase-types/testing.js

@@ -14,10 +14,15 @@ export { formatters } from '../../src/managers/PluginManager.js';
  *
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - The add-on's own `config/default-config.json`
+ * @param setEnabledForPerson - What `host.setEnabledForPerson` does in the
+ *   test (#1963); a site binds core's setter. Without one it refuses.
+ * @param engine - Optional: an engine (or stand-in) whose PolicyInformationPoint
+ *   names the system principal for `host.systemContext`; without one it is
+ *   core's fallback principal
  */
-export function buildAddonHost(slug, addonDefaults) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson, engine) {
     bindAuditEvents((key, fallback) => addonDefaults[key] ?? fallback);
-    return buildHost(slug, addonDefaults);
+    return buildHost(slug, addonDefaults, setEnabledForPerson, engine);
 }
 /**
  * An add-on's database as `DatabaseManager.openAddonDatabase` returns it, in

package/lib/src/managers/AddonsManager.d.ts

@@ -10,7 +10,7 @@
  *
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/158}
  */
-import type { ActorContext } from '../context/ActorContext.js';
+import { type ActorContext } from '../context/ActorContext.js';
 import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
@@ -208,7 +208,49 @@ export interface AddonManifest {
      * docs/guides/addons-developer-guide.md "Declare a Private Store".
      */
     stores?: unknown;
+    /**
+     * #1963: each person turns this add-on on or off for themselves. Their
+     * switch is the preference `<slug>.enabled` (`personSwitchKey`), read only
+     * by `AddonsManager.enabledAddonsFor` and written only through
+     * `host.setEnabledForPerson`. Absent or anything but `true`: not per-person.
+     */
+    perPerson?: boolean;
+    /**
+     * #1965: the add-on's About page, a page it ships in `pages/`, by uuid or
+     * slug. `[{ConfigAccessor type='addons'}]` links to it ("More about it").
+     * The site overrides it with `ngdpbase.addons.<slug>.about-page`.
+     */
+    aboutPage?: string;
+    /**
+     * #1965: the heading the add-on is listed under, shared by related add-ons
+     * (e.g. "Accounting" for accounting, accounting-donations and accounting-dues).
+     */
+    family?: string;
+    /** #1965: `false` keeps plumbing (e.g. elasticsearch) out of the add-on listings. */
+    listed?: boolean;
+}
+/**
+ * One add-on as the listings show it (#1965), from `AddonsManager.listedAddons()`.
+ * `version`, `loaded` and `error` are for administrators; the plugin that
+ * renders a listing decides who sees them.
+ */
+export interface AddonListing {
+    slug: string;
+    description: string;
+    /** The heading it is grouped under, or null */
+    family: string | null;
+    /** The About page (uuid or slug), the site's override first; null when none */
+    aboutPage: string | null;
+    perPerson: boolean;
+    version: string;
+    loaded: boolean;
+    error: string | null;
 }
+/**
+ * The preference that holds a person's switch for a per-person add-on (#1963):
+ * `<slug>.enabled`. The one place the key is spelled.
+ */
+export declare function personSwitchKey(slug: string): string;
 /**
  * Details returned by add-on's status() method
  */
@@ -262,6 +304,7 @@ export interface AddonStatus {
  * AddonsManager - Manages optional add-on modules
  */
 declare class AddonsManager extends BaseManager {
+    #private;
     /** Map of discovered add-ons by name */
     private addons;
     /** Configured paths to addons directories (one or more) */
@@ -282,6 +325,8 @@ declare class AddonsManager extends BaseManager {
     private domainAddonName;
     /** #1883: the enabled add-ons that did not load this start, with why — each reported once. */
     private readonly loadFailures;
+    /** #1973: every enabled add-on has had its turn to load this boot (see {@link addonsLoaded}). */
+    private loadPassDone;
     constructor(engine: WikiEngine);
     /**
      * Initialize the AddonsManager
@@ -405,6 +450,20 @@ declare class AddonsManager extends BaseManager {
         ok: false;
         blockedBy: string[];
     };
+    /**
+     * The installed version of an add-on (#1973): the `version` in its
+     * package.json, or its module's `version` when the package.json has none.
+     * Undefined for an add-on that was not discovered.
+     *
+     * @param slug - The add-on's slug
+     */
+    getAddonVersion(slug: string): string | undefined;
+    /**
+     * Whether this boot's load pass is over (#1973): every enabled add-on has
+     * had its `register()` called, loaded or not. Until then, what an add-on has
+     * not registered yet says nothing about whether it still provides it.
+     */
+    addonsLoaded(): boolean;
     /**
      * Get add-on specific configuration
      */
@@ -614,6 +673,28 @@ declare class AddonsManager extends BaseManager {
      * other addons' saves or the core-preferences save.
      */
     saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<void>;
+    /**
+     * The add-ons the site's listings show (#1965): enabled, and not
+     * `listed: false` in their manifest, in load order. Cheap: it calls no
+     * add-on's status(), so a page can render it.
+     */
+    listedAddons(): AddonListing[];
+    /** #1963: the loaded add-ons whose manifest says `perPerson: true`, in load order. */
+    private perPersonAddons;
+    /**
+     * The per-person add-ons this subject has turned on (#1963): each loaded
+     * add-on whose manifest says `perPerson: true` and whose switch, the
+     * person's preference `<slug>.enabled`, is `true`.
+     *
+     * It reads exactly those keys and no other preference, so no access check
+     * or listing built on it can come to depend on an arbitrary setting. An
+     * anonymous subject, an unknown or inactive account, and the system
+     * principal (which has no account) have none.
+     *
+     * @param ctx - Whose add-ons: the request's subject, or a job's context
+     * @returns The slugs, in load order
+     */
+    enabledAddonsFor(ctx: ActorContext): Promise<string[]>;
     /**
      * Get count of loaded add-ons
      */

package/lib/src/security/PolicyInformationPoint.d.ts

@@ -1,4 +1,5 @@
 import BaseManager from '../managers/BaseManager.js';
+import type { ActorContext } from '../context/ActorContext.js';
 import { WikiEngine } from '../types/WikiEngine.js';
 import type { AgentTokenGrant, ProxyClaim } from '../managers/UserManager.js';
 import type { Request } from 'express';
@@ -201,6 +202,13 @@ declare class PolicyInformationPoint extends BaseManager {
      * session at all, so the session path alone would still have said Anonymous.
      */
     currentSubject(req: Request): Promise<UserContext>;
+    /**
+     * The subject's per-person add-ons that are turned on (#1963): an attribute
+     * the PIP supplies to a decision (the page audience `addon:<slug>`, #1964)
+     * the way it supplies roles from RoleManager. AddonsManager owns the answer;
+     * none when it is not running.
+     */
+    subjectEnabledAddons(ctx: ActorContext): Promise<string[]>;
     private userManager;
     private roleManager;
     /**

package/lib/src/utils/addonHost.d.ts

@@ -10,6 +10,11 @@
  * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
  *   this add-on declares in its own `config/default-config.json`, so one
  *   add-on cannot write records that look like another's or like core's;
+ * - `systemContext(reason)` is bound to the running engine, so the system
+ *   principal's name comes from core (`NGDPBASE_SYSTEM_USER`), never from
+ *   the add-on (#1973);
+ * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
+ *   bound to its slug, so it can never set another add-on's;
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -17,8 +22,9 @@
  */
 import type { Logger } from 'winston';
 import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
-import { actorOf } from '../context/ActorContext.js';
-import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { actorOf, type ActorContext } from '../context/ActorContext.js';
+import { jobContextFromRequest, jobContextFromSystem, type JobContext } from '../context/JobContext.js';
+import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
@@ -32,9 +38,25 @@ export interface AddonHost {
     readonly actorOf: typeof actorOf;
     readonly jobContextFromRequest: typeof jobContextFromRequest;
     readonly jobContextFromSystem: typeof jobContextFromSystem;
+    /**
+     * The context the add-on's own boot work runs under (#1973): core's system
+     * principal, with `reason` saying what and why, for the record. Pass it
+     * where a manager door asks for a context at start, such as
+     * `FormsDataManager.registerShippedForm`.
+     */
+    readonly systemContext: (reason: string) => JobContext;
     readonly logger: Logger;
     readonly guardedFetch: typeof guardedFetch;
+    /**
+     * #1963: turn this per-person add-on on (`true`) or off (`false`) for the
+     * person `ctx` acts as: their preference `<slug>.enabled`. Pass the context
+     * you were given (a profile hook's `ctx`). Refused when the add-on's manifest
+     * does not say `perPerson: true`, or the person may not manage their profile.
+     */
+    readonly setEnabledForPerson: PersonSwitchSetter;
 }
+/** Sets one add-on's per-person switch; core binds the slug when it builds the host (#1963). */
+export type PersonSwitchSetter = (ctx: ActorContext, on: boolean) => Promise<void>;
 /**
  * The audit event names one add-on declares: the permission entries carrying
  * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
@@ -47,5 +69,9 @@ export declare function addonDeclaredAuditEvents(addonDefaults: Record<string, u
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - That add-on's own default-config.json, as folded into
  *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ * @param setEnabledForPerson - This add-on's switch setter, slug already bound
+ *   (`AddonsManager` supplies it); without one, the host's setter refuses
+ * @param engine - The running engine, which names the system principal for
+ *   `systemContext`; without one (a test) it is core's fallback principal
  */
-export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>): AddonHost;
+export declare function buildAddonHost(slug: string, addonDefaults: Record<string, unknown>, setEnabledForPerson?: PersonSwitchSetter, engine?: Parameters<typeof systemContext>[0]): AddonHost;

package/lib/src/utils/addonHost.js

@@ -10,6 +10,11 @@
  * - `recordAuditEvent` and `addonAuditEventName` accept only the audit events
  *   this add-on declares in its own `config/default-config.json`, so one
  *   add-on cannot write records that look like another's or like core's;
+ * - `systemContext(reason)` is bound to the running engine, so the system
+ *   principal's name comes from core (`NGDPBASE_SYSTEM_USER`), never from
+ *   the add-on (#1973);
+ * - `setEnabledForPerson` sets this add-on's own per-person switch (#1963),
+ *   bound to its slug, so it can never set another add-on's;
  * - the object is `Object.freeze`d, so no add-on can replace a value.
  *
  * Additive only: nothing here is removed or renamed without a major release.
@@ -18,11 +23,14 @@
 import { ApiContext, ApiError, sendApiError } from '../context/ApiContext.js';
 import { actorOf } from '../context/ActorContext.js';
 import { jobContextFromRequest, jobContextFromSystem } from '../context/JobContext.js';
+import { systemContext } from '../context/bootActions.js';
 import { guardedFetch } from '../http/guardedFetch.js';
 import { recordAuditEvent } from './auditEvents.js';
 import { addonAuditEventName } from './auditEventNames.js';
 import { auditDeclarationsFrom } from './auditRegistry.js';
 import logger from './logger.js';
+/** A host built outside a site (the test kit, with no setter given) has no account store. */
+const noPersonSwitch = () => Promise.reject(new Error('setEnabledForPerson is not available: this host was built without a site'));
 /**
  * The audit event names one add-on declares: the permission entries carrying
  * an `audit` block, and the `ngdpbase.audit.events` entries, in that add-on's
@@ -45,8 +53,12 @@ function refuseUndeclared(slug, name, declared) {
  * @param slug - The add-on's canonical slug
  * @param addonDefaults - That add-on's own default-config.json, as folded into
  *   the configuration merge (`ConfigurationManager.getAddonDeclaredDefaults`)
+ * @param setEnabledForPerson - This add-on's switch setter, slug already bound
+ *   (`AddonsManager` supplies it); without one, the host's setter refuses
+ * @param engine - The running engine, which names the system principal for
+ *   `systemContext`; without one (a test) it is core's fallback principal
  */
-export function buildAddonHost(slug, addonDefaults) {
+export function buildAddonHost(slug, addonDefaults, setEnabledForPerson = noPersonSwitch, engine) {
     const declared = addonDeclaredAuditEvents(addonDefaults);
     const hostAddonAuditEventName = (name) => {
         const checked = addonAuditEventName(name);
@@ -66,7 +78,9 @@ export function buildAddonHost(slug, addonDefaults) {
         actorOf,
         jobContextFromRequest,
         jobContextFromSystem,
+        systemContext: (reason) => systemContext(engine, reason),
         logger: logger.child({ addon: slug }),
-        guardedFetch
+        guardedFetch,
+        setEnabledForPerson
     });
 }

package/lib/src/utils/addonPageSync.d.ts

@@ -34,8 +34,8 @@ export declare function evaluateSeededAddonPage(args: {
 /**
  * How a shipped item's sync status reads on an admin screen: the status words
  * and the edit protection of Admin → Required Pages, which every screen that
- * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`;
- * shipped forms, #1918).
+ * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`,
+ * #1918).
  *
  *  - `status` — `modified` when the live copy differs from what ships,
  *    `current` when it is the same.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.24.0",
+  "version": "5.25.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",