@jwilleke/ngdpbase-types 5.19.0 → 5.20.0

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

@@ -17,6 +17,11 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import type { User } from '../types/User.js';
 import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
 import { type AddonHost } from '../utils/addonHost.js';
+/**
+ * #1883: what visitors see while a site-critical add-on that did not load
+ * holds the site in maintenance mode. Empty leaves only the page's heading.
+ */
+export declare const SITE_CRITICAL_PUBLIC_MESSAGE_KEY = "ngdpbase.managers.addons-manager.site-critical.public-message";
 /**
  * Type passed to `AddonModule.profileSection()` (#534). Matches what
  * `UserManager.getUser()` returns at runtime — `User` minus the password
@@ -280,6 +285,8 @@ declare class AddonsManager extends BaseManager {
     private dashboardCards;
     /** Name of the first domain addon loaded — only one is permitted */
     private domainAddonName;
+    /** #1883: the enabled add-ons that did not load this start, with why — each reported once. */
+    private readonly loadFailures;
     constructor(engine: WikiEngine);
     /**
      * Initialize the AddonsManager
@@ -351,6 +358,30 @@ declare class AddonsManager extends BaseManager {
      * bundled/drop-in addon wins.
      */
     private registerAddonFromDir;
+    /**
+     * Register an add-on that will not be loaded, so Admin → Add-ons shows it
+     * with the reason, and report it when it is enabled (#1883). The first
+     * add-on of a slug wins, as for a loadable one.
+     */
+    private refuseAddon;
+    /**
+     * #1883 (operator, 2026-10-18): the one rule for an enabled add-on that does
+     * not load, whatever the reason. Admins get a notification at the most
+     * severe level naming it and the reason, which says how to fix it where the
+     * reason does. A site-critical add-on (`ngdpbase.addons.<slug>.site-critical`)
+     * also holds the whole site in maintenance mode through core's survivable
+     * path (#1152): visitors see only the configured public message, with no
+     * details, and administrators can still sign in and reach /admin. Once per
+     * add-on per start. Nothing is opened in its place.
+     */
+    private recordLoadFailure;
+    /**
+     * #1883: an enabled add-on that discovery never found — its install failed
+     * (#1830), or only a stray folder answers it — did not load either.
+     */
+    private reportUndiscoveredAddons;
+    /** A notification to administrators; best-effort, like recordSeedFailure. */
+    private notifyAdmins;
     /**
      * Why an addon cannot run on this core (#1757): its manifest's `minVersion`
      * is newer than this release. Null when it can, or when it states none.

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

@@ -1052,6 +1052,15 @@ declare class AuthManager extends BaseManager {
     unlockVaults(username: string, password: string): Promise<string | undefined>;
     private vaultUnlocker;
     private warnedNoUnlocker;
+    /**
+     * The stored spelling of a username a sign-in brought (#1882), or null when
+     * no account has it. Lookups compare normalized (#1436), so "ADMIN" finds
+     * admin's record; the session, the audit record, the roles and the vault
+     * paths must carry the stored name, never the typed variant, which is a
+     * roleless twin. The one rule, asked by every door a sign-in passes:
+     * `authenticate`, `beginTwoStep` and `completeSignIn`.
+     */
+    private storedUsername;
     /** A fresh session for a sign-in (#1043); the one already on it ends first (#1626, #1670). */
     private regenerate;
     /**
@@ -1109,7 +1118,7 @@ declare class AuthManager extends BaseManager {
         ip?: string;
         userAgent?: string;
         privateStoreHandle?: string;
-    }): string;
+    }): Promise<string>;
     /** The pending sign-in, for the browser that started it; null when gone, expired, or another browser. */
     pendingSignIn(handle: string | undefined, binding: string | undefined): PendingSignIn | null;
     /**

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

@@ -60,10 +60,12 @@ declare class ConfigurationManager extends BaseManager {
     private addonLayers;
     /** #1559: add-on system-categories refused, and operator values an owner's declaration overrode; #1860: database declarations refused or overridden. */
     private systemCategoryProblems;
-    /** #1559: add-ons that must not load because an entry they declare was refused, by slug, with why; #1860: or their database declaration. */
+    /** #1559: add-ons that must not load because an entry they declare was refused, by slug, with why; #1860: or their database declaration; #1883: or a site-critical value that is not a boolean. */
     private refusedAddons;
     /** #1860: every installed add-on's sound database declaration, on or off. */
     private addonDatabases;
+    /** #1883: which add-ons put the site in maintenance mode when they fail to load, by slug. */
+    private siteCriticalAddons;
     private environment;
     private defaultConfigPath;
     private customConfigPath;
@@ -282,6 +284,14 @@ declare class ConfigurationManager extends BaseManager {
      * ({@link getAddonRefusal}). DatabaseManager is the reader.
      */
     getAddonDatabaseDeclarations(): readonly AddonDatabaseDeclaration[];
+    /**
+     * #1883: whether this add-on's failure to load puts the whole site in
+     * maintenance mode — `ngdpbase.addons.<slug>.site-critical`, from the
+     * operator's file or else the add-on's own, read even when the add-on was
+     * refused. A value that is not exactly true or false counts as true (and
+     * refuses the add-on, {@link getAddonRefusal}).
+     */
+    isAddonSiteCritical(slug: string): boolean;
     /**
      * #1813: what one enabled addon's own `config/default-config.json` declares,
      * exactly as it was folded into the merge — not the merged view, so the

package/lib/src/managers/DatabaseManager.js

@@ -255,7 +255,7 @@ class DatabaseManager extends BaseManager {
     static keyRefusal(declaration, key) {
         if (declaration.encrypt !== 'required' || key)
             return null;
-        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted (#1860)`;
+        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted. Set ${DATABASE_KEY_ENV} in the environment or the instance .env (<FAST_STORAGE>/.env) and restart (#1860, #1883)`;
     }
     // ---- Backup and restore (#1723) ------------------------------------------
     /**

package/lib/src/types/WikiEngine.d.ts

@@ -102,10 +102,21 @@ export interface WikiEngine {
      * the repair, instead of exiting and leaving the filesystem as the only way
      * back. Only for values an administrator can fix through the admin UI; a
      * failure of the machinery needed to serve that UI is fatal and still throws.
+     * Also a site-critical add-on that did not load (#1883, operator
+     * 2026-10-18): its fix may lie outside the UI (a key in the instance .env),
+     * and the admin notification says so.
      */
-    blockConfiguration(reason: string): void;
+    blockConfiguration(reason: string, options?: {
+        publicMessage?: string;
+    }): void;
     /** Configuration values that could not be used, in the order found (#1152). */
     getBlockingConditions(): readonly string[];
+    /**
+     * What visitors see in place of the reasons, when a reason was recorded with
+     * a `publicMessage` (#1883: a site-critical add-on that did not load); null
+     * when every reason may be shown.
+     */
+    getPublicBlockingMessage(): string | null;
     /**
      * Get all registered manager names
      * @returns Array of manager names

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

@@ -40,6 +40,12 @@
  * never merged into the configuration: DatabaseManager reads the declarations
  * from here, so the operator's file cannot change one. An invalid declaration
  * stops its addon loading, as a refused system-category does.
+ *
+ * A third, `ngdpbase.addons.<slug>.site-critical` (#1883): whether a failure of
+ * the addon to load puts the whole site in maintenance mode. Read from the
+ * addon's own file and from the operator's, which wins either way, and kept
+ * apart from the merge so a refused addon's value is still known. A value that
+ * is not exactly `true` or `false` refuses the addon and counts as `true`.
  */
 import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -78,6 +84,8 @@ export declare function discoverAddonDirs(base: Record<string, unknown>, cwd?: s
  * rather than silently skip it.
  */
 export declare function discoverAddonDefaults(base: Record<string, unknown>, cwd?: string, dataFolder?: string): AddonDefaults[];
+/** How a problem line names an addon; AddonsManager matches it to fold a refusal into its load-failure notice (#1883). */
+export declare function addonProblemSubject(slug: string, enabled: boolean): string;
 export interface AddonDatabaseLayer {
     /** Every sound declaration, of every installed addon, `enabled` as its addon is. */
     declarations: AddonDatabaseDeclaration[];
@@ -92,6 +100,25 @@ export interface AddonDatabaseLayer {
  * file: a value there for a declaration's key is ignored, and said so.
  */
 export declare function addonDatabaseLayer(addons: readonly AddonDefaults[], custom: Record<string, unknown>): AddonDatabaseLayer;
+/** The configuration key that makes an addon site-critical (#1883). */
+export declare function addonSiteCriticalKey(slug: string): string;
+export interface AddonSiteCriticalLayer {
+    /** Each addon with a value, by slug: true when its failure to load puts the site in maintenance mode. */
+    siteCritical: Map<string, boolean>;
+    /** Addons whose value is not exactly `true` or `false`, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * Which addons are site-critical (#1883): the operator's value if the
+ * operator's file sets one, else the addon's own (only under its own slug),
+ * else not. The operator's file wins in both directions, as for every addon
+ * key. The value is exactly `true` or `false`; anything else (the string
+ * `"true"` included) refuses the addon and counts as site-critical, so a
+ * mistyped value fails closed. `custom` keys for an addon with no file, or
+ * one that is not installed, count too.
+ */
+export declare function addonSiteCriticalLayer(addons: readonly AddonDefaults[], custom: Record<string, unknown>): AddonSiteCriticalLayer;
 /**
  * shipped ⊕ addons ⊕ custom, in that order of precedence (custom wins), with
  * the problems found in the addons' system-categories (#1559).
@@ -108,6 +135,7 @@ export declare function mergeWithAddonLayer<T extends Record<string, unknown>>(s
     problems: string[];
     refused: Map<string, string>;
     databases: AddonDatabaseDeclaration[];
+    siteCritical: Map<string, boolean>;
 };
 /**
  * The full merge for a caller with the two files already read (the manager,
@@ -119,7 +147,9 @@ export declare function mergeWithAddonLayer<T extends Record<string, unknown>>(s
  * could not be read; `refused` names, by slug, each addon that must not load
  * because an entry it declares was refused, and why (#1559), or because its
  * database declaration was (#1860); `databases` is every sound database
- * declaration of every installed addon, on or off (#1860).
+ * declaration of every installed addon, on or off (#1860); `siteCritical`
+ * says, by slug, which addons put the site in maintenance mode when they fail
+ * to load (#1883).
  */
 export declare function mergeConfigWithAddons<T extends Record<string, unknown>>(shipped: T, custom: Partial<T>, cwd?: string, dataFolder?: string): {
     merged: T;
@@ -128,6 +158,7 @@ export declare function mergeConfigWithAddons<T extends Record<string, unknown>>
     problems: string[];
     refused: Map<string, string>;
     databases: AddonDatabaseDeclaration[];
+    siteCritical: Map<string, boolean>;
 };
 export interface MergedConfigFiles {
     merged: Record<string, unknown>;

package/lib/src/utils/addonConfigLayer.js

@@ -40,6 +40,12 @@
  * never merged into the configuration: DatabaseManager reads the declarations
  * from here, so the operator's file cannot change one. An invalid declaration
  * stops its addon loading, as a refused system-category does.
+ *
+ * A third, `ngdpbase.addons.<slug>.site-critical` (#1883): whether a failure of
+ * the addon to load puts the whole site in maintenance mode. Read from the
+ * addon's own file and from the operator's, which wins either way, and kept
+ * apart from the merge so a refused addon's value is still known. A value that
+ * is not exactly `true` or `false` refuses the addon and counts as `true`.
  */
 import fs from 'fs';
 import path from 'path';
@@ -127,6 +133,10 @@ export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = in
     }
     return out;
 }
+/** How a problem line names an addon; AddonsManager matches it to fold a refusal into its load-failure notice (#1883). */
+export function addonProblemSubject(slug, enabled) {
+    return `add-on '${slug}'${enabled ? '' : ' (turned off)'}`;
+}
 function vaultIdOf(entry) {
     return parsePrivatestore(entry?.storageLocation?.privatestore)?.vaultId;
 }
@@ -154,7 +164,7 @@ function addonCategoryLayer(shipped, custom, addons) {
         const declared = addon.defaults[SYSTEM_CATEGORY_KEY];
         if (declared === undefined)
             continue;
-        const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+        const who = addonProblemSubject(addon.slug, addon.enabled);
         if (!isPlainObject(declared)) {
             const reason = `${SYSTEM_CATEGORY_KEY} must be a map of entries`;
             layer.problems.push(`${who}: ${reason}; it is refused and the add-on is not loaded`);
@@ -246,7 +256,7 @@ export function addonDatabaseLayer(addons, custom) {
             }
         }
         if (reasons.length > 0) {
-            const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+            const who = addonProblemSubject(addon.slug, addon.enabled);
             layer.problems.push(`${who}: its database declaration is refused (${reasons.join('; ')}); the add-on is not loaded`);
             layer.refused.set(addon.slug, `its database declaration was refused: ${reasons.join('; ')}`);
             continue;
@@ -262,6 +272,45 @@ export function addonDatabaseLayer(addons, custom) {
     }
     return layer;
 }
+/** The configuration key that makes an addon site-critical (#1883). */
+export function addonSiteCriticalKey(slug) {
+    return `ngdpbase.addons.${slug}.site-critical`;
+}
+/**
+ * Which addons are site-critical (#1883): the operator's value if the
+ * operator's file sets one, else the addon's own (only under its own slug),
+ * else not. The operator's file wins in both directions, as for every addon
+ * key. The value is exactly `true` or `false`; anything else (the string
+ * `"true"` included) refuses the addon and counts as site-critical, so a
+ * mistyped value fails closed. `custom` keys for an addon with no file, or
+ * one that is not installed, count too.
+ */
+export function addonSiteCriticalLayer(addons, custom) {
+    const layer = { siteCritical: new Map(), refused: new Map(), problems: [] };
+    const take = (slug, enabled, own) => {
+        const key = addonSiteCriticalKey(slug);
+        const fromSite = custom[key] !== undefined;
+        const value = fromSite ? custom[key] : own;
+        if (value === undefined)
+            return;
+        if (typeof value === 'boolean') {
+            layer.siteCritical.set(slug, value);
+            return;
+        }
+        const reason = `${key} must be true or false, got ${JSON.stringify(value)} in ${fromSite ? 'app-custom-config.json' : 'its config/default-config.json'}; it is treated as true`;
+        layer.siteCritical.set(slug, true);
+        layer.refused.set(slug, reason);
+        layer.problems.push(`${addonProblemSubject(slug, enabled)}: ${reason}; the add-on is not loaded`);
+    };
+    for (const addon of addons)
+        take(addon.slug, addon.enabled, addon.defaults[addonSiteCriticalKey(addon.slug)]);
+    for (const key of Object.keys(custom)) {
+        const slug = /^ngdpbase\.addons\.([^.]+)\.site-critical$/.exec(key)?.[1];
+        if (slug && !layer.siteCritical.has(slug))
+            take(slug, custom[`ngdpbase.addons.${slug}.enabled`] === true, undefined);
+    }
+    return layer;
+}
 /**
  * The owner's declaration stands (operator, 2026-09-29): for each entry an
  * addon declared, the fields in OWNER_DECIDED_FIELDS are the addon's, never
@@ -310,8 +359,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const customCategories = custom[SYSTEM_CATEGORY_KEY];
     const layer = addonCategoryLayer(shipped[SYSTEM_CATEGORY_KEY], customCategories, addons);
     const databaseLayer = addonDatabaseLayer(addons, custom);
+    const criticalLayer = addonSiteCriticalLayer(addons, custom);
+    const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of databaseLayer.refused)
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -325,14 +376,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems], refused, databases };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems], refused, databases };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,
@@ -344,12 +395,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
  * could not be read; `refused` names, by slug, each addon that must not load
  * because an entry it declares was refused, and why (#1559), or because its
  * database declaration was (#1860); `databases` is every sound database
- * declaration of every installed addon, on or off (#1860).
+ * declaration of every installed addon, on or off (#1860); `siteCritical`
+ * says, by slug, which addons put the site in maintenance mode when they fail
+ * to load (#1883).
  */
 export function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
     const base = deepMergeConfigs(shipped, custom);
     const all = discoverAddonDefaults(base, cwd, dataFolder);
-    const { merged, problems, refused, databases } = mergeWithAddonLayer(shipped, all, custom);
+    const { merged, problems, refused, databases, siteCritical } = mergeWithAddonLayer(shipped, all, custom);
     const unreadable = all
         .filter((a) => !a.enabled && a.error)
         .map((a) => `add-on '${a.slug}' (turned off): config/default-config.json could not be read (${a.error}); its system-categories and database are not known`);
@@ -359,7 +412,8 @@ export function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), data
         addons: all.filter((a) => a.enabled && !refused.has(a.slug)),
         problems: [...unreadable, ...problems],
         refused,
-        databases
+        databases,
+        siteCritical
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.19.0",
+  "version": "5.20.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",