@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,691 @@
+/**
+ * AddonsManager - Core Add-on Management System
+ *
+ * Handles discovery, registration, lifecycle management, and dependencies
+ * for optional ngdpbase add-ons. This enables optional business modules
+ * (person-contacts, financial-ledger, etc.) without modifying ngdpbase core.
+ *
+ * @class AddonsManager
+ * @extends BaseManager
+ *
+ * @see {@link https://github.com/jwilleke/ngdpbase/issues/158}
+ */
+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';
+import type { User } from '../types/User.js';
+import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
+import { type AddonHost } from '../utils/addonHost.js';
+/**
+ * Type passed to `AddonModule.profileSection()` (#534). Matches what
+ * `UserManager.getUser()` returns at runtime — `User` minus the password
+ * hash — so addons can read preferences/roles/email without coupling
+ * to whether the host happened to fetch the full User record.
+ */
+export type AddonProfileUser = Omit<User, 'password'>;
+/**
+ * Flatten nested plain-object values into dotted-key form (#534 defensive).
+ *
+ * `express.urlencoded({ extended: true })` keeps dotted form-field names FLAT
+ * by default — `<input name="journal.x">` → `body['journal.x']` directly,
+ * NOT `body.journal.x`. (Verified: qs's `allowDots` defaults to false, and
+ * body-parser doesn't override that.) But the WikiRoutes core code defends
+ * against a future config change with its own `getBodyValue` walker, and
+ * `AddonsManager.saveProfileSections` normalizes addon-bound body shape so
+ * addon authors can rely on flat lookups regardless of host config.
+ *
+ * Rules:
+ *   - Non-object values (string, number, boolean, null, undefined) pass
+ *     through as-is at the current dotted key.
+ *   - Arrays pass through as-is (not flattened element-wise — qs already
+ *     produces sensible array shapes for `name="x[]"` inputs).
+ *   - Plain objects are recursively flattened.
+ *   - Flat dotted keys present on the input pass through unchanged.
+ *   - If both flat (`'a.b': X`) and nested (`a: { b: Y }`) shapes are
+ *     present, the LAST seen during iteration wins — typically the nested
+ *     value, since flat dotted keys are inserted before nested objects in
+ *     qs output. This is intentional: nested is the more-specific shape.
+ */
+export declare function flattenDottedKeys(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * Standard interface that all add-ons must implement
+ */
+export interface AddonModule {
+    /** Unique identifier for the add-on */
+    name: string;
+    /** Semantic version string */
+    version: string;
+    /** Human-readable description */
+    description?: string;
+    /** Author name or organization */
+    author?: string;
+    /** List of add-on names this add-on depends on */
+    dependencies?: string[];
+    /**
+     * #1808: add-ons to load first when they are installed and enabled. Unlike
+     * `dependencies`, a missing or disabled one is skipped, not an error.
+     */
+    optionalDependencies?: string[];
+    /**
+     * Called during app startup if add-on is enabled.
+     * Use this to register routes, initialize databases, etc.
+     *
+     * #1813: `host` carries the core values an add-on uses (ApiContext,
+     * recordAuditEvent, logger, guardedFetch, …), built for this add-on and
+     * frozen. An add-on that takes two arguments keeps working until it moves.
+     */
+    register(engine: WikiEngine, config: Record<string, unknown>, host?: AddonHost): Promise<void> | void;
+    /**
+     * Optional health check returning add-on status details.
+     */
+    status?(): Promise<AddonStatusDetails> | AddonStatusDetails;
+    /**
+     * Optional `/profile` page extension hook (#534).
+     *
+     * When implemented, the addon contributes a section to the core profile
+     * page rather than maintaining a standalone settings route. The returned
+     * `html` is inserted **inside** the core preferences form, so the form
+     * fields it carries are submitted with the existing `POST /preferences`
+     * and surfaced to `saveProfileSection()` for persistence.
+     *
+     * Return `null` to opt out per-user (e.g. when the addon's feature is
+     * disabled for this user's roles).
+     *
+     * ⚠️ SECURITY — the returned `html` is rendered with EJS `<%- %>` (RAW,
+     * NOT escaped) inside the user's `/profile` form. **The addon is fully
+     * responsible for escaping any user-controlled data it interpolates.**
+     * Use `<%= %>` in your own EJS templates, or an explicit escape helper.
+     * A buggy `profileSection()` that string-concatenates user input becomes
+     * stored-XSS against every user who views their profile.
+     *
+     * Two specific things to avoid:
+     *   - Do NOT emit `<input name="_csrf" …>` — that would override the
+     *     host form's CSRF token and corrupt the user's save.
+     *   - Do NOT emit a wrapping `<form>` — your fields submit with the host
+     *     preferences form. A nested `<form>` is invalid HTML and browsers
+     *     will hoist your inputs unpredictably.
+     *
+     * RECOMMENDED — include a hidden marker so your paired `saveProfileSection`
+     * can distinguish "section was rendered but checkboxes unchecked" from
+     * "section was not rendered at all" (addon disabled mid-session, cached
+     * form). Without it, absent checkbox fields look identical to "user
+     * submitted no such field" and you may silently clobber stored values.
+     */
+    profileSection?(user: AddonProfileUser): Promise<AddonProfileSection | null> | AddonProfileSection | null;
+    /**
+     * Optional save handler paired with `profileSection()` (#534).
+     *
+     * Receives a shallow-cloned `req.body` from `POST /preferences`; the addon
+     * extracts whichever fields its `profileSection()` form rendered and
+     * persists them. Errors are caught by AddonsManager and logged — they
+     * do NOT block the core-preferences save or other addons' saves.
+     *
+     * Two pitfalls the implementation must guard against (the host cannot
+     * do this for you):
+     *
+     *   1. ABSENT-FIELD CLOBBER. HTML checkboxes only submit when checked, so
+     *      an absent key is ambiguous between "user unchecked it" and "the
+     *      field was never rendered". Without a presence signal (see the
+     *      recommended hidden marker on `profileSection()`), writing
+     *      `body['x'] === 'on'` unconditionally turns every save where the
+     *      section was hidden into a stealth reset to `false`.
+     *
+     *   2. CONFIG-GATED FIELDS. If your partial gates a field behind an admin
+     *      config flag (`<% if (enabled) %>`), your save handler MUST re-check
+     *      the same flag server-side before writing — otherwise a crafted
+     *      POST can bypass the admin's gate.
+     *
+     * __Since #1234 the first argument is the caller's context, not a name.__
+     * `ctx` is the request's subject (`PermissionSubject`: `username`, `roles`,
+     * `isAuthenticated`, `ipAddress`, `viaToken` / `viaShare` when delegated)
+     * — forward it to whatever you write (`userManager.updateUser(ctx.username,
+     * updates, ctx)`), never rebuild one from `ctx.username`. An addon still
+     * written against the old `(username, body)` shape gets a warning at load
+     * naming it; its saves then fail per call and are logged.
+     */
+    saveProfileSection?(ctx: ActorContext, body: Record<string, unknown>): Promise<void> | void;
+    /**
+     * Optional cleanup on app shutdown.
+     */
+    shutdown?(): Promise<void> | void;
+}
+/**
+ * Returned from `AddonModule.profileSection()` — a single section rendered as
+ * a card inside the `/profile` preferences form. `html` is inserted with `<%-`
+ * (raw); the addon is responsible for any escaping of its own data.
+ */
+export interface AddonProfileSection {
+    /** Heading shown in the card header (e.g. "Journal"). */
+    title: string;
+    /** Raw HTML rendered inside the card body; should contain form input fields. */
+    html: string;
+}
+/**
+ * One entry per addon that contributed a profile section, returned by
+ * `AddonsManager.getProfileSections()`. `addonName` is the registry key —
+ * useful for debug logging and CSS scoping.
+ */
+export interface AddonProfileSectionEntry extends AddonProfileSection {
+    addonName: string;
+}
+/**
+ * Shape of the `ngdpbase` key in an add-on's package.json.
+ * All fields are optional — omitting the key entirely is valid.
+ */
+export interface AddonManifest {
+    /**
+     * Canonical addon identity (#927). Authoritative id used as the registry
+     * key, the `ngdpbase.addons.<slug>.enabled` config key, dependency
+     * references, and the boot-time validator's match — read statically from
+     * `package.json` with no module import. When absent, identity falls back
+     * to the package/folder name (minus a conventional trailing `-addon`).
+     * The module's exported `name` is a display label and must equal this.
+     */
+    slug?: string;
+    /** 'domain' = this addon IS the site identity; 'additive' = augments an existing wiki */
+    type?: 'domain' | 'additive';
+    /**
+     * The oldest ngdpbase release this addon runs on (`x.y.z`). Checked before
+     * the addon is imported: on an older core it is not loaded, and its status
+     * says which release it needs, instead of failing at import with a missing
+     * module.
+     */
+    minVersion?: string;
+    /**
+     * Config keys this addon wants applied by default at load time.
+     * Each key is only set if the operator has not already explicitly
+     * set it in custom config. Values are ephemeral (merged config only,
+     * not persisted to app-custom-config.json).
+     */
+    domainDefaults?: Record<string, unknown>;
+    /** Capability flags this addon advertises */
+    capabilities?: string[];
+    /**
+     * Private store kinds this addon owns (#1414): `[{ id, encrypt }]`. Saved to
+     * configuration at the addon's first load, owned by its slug; from then on
+     * configuration wins and this is never consulted again. See
+     * docs/guides/addons-developer-guide.md "Declare a Private Store".
+     */
+    stores?: unknown;
+}
+/**
+ * Details returned by add-on's status() method
+ */
+export interface AddonStatusDetails {
+    healthy: boolean;
+    database?: string;
+    records?: number;
+    message?: string;
+    [key: string]: unknown;
+}
+/**
+ * Card registered by an add-on for display on the admin dashboard.
+ * The card's live stats are sourced from the add-on's existing status() method.
+ */
+export interface AddonDashboardCard {
+    /** Must match the add-on's registered name */
+    addonName: string;
+    /** Card heading */
+    title: string;
+    /** Font Awesome class, e.g. 'fas fa-wpforms' */
+    icon: string;
+    /** URL of the add-on's admin page */
+    adminUrl: string;
+}
+/**
+ * Status information returned by getStatus()
+ */
+export interface AddonStatus {
+    name: string;
+    version: string;
+    description: string;
+    author: string;
+    enabled: boolean;
+    loaded: boolean;
+    dependencies: string[];
+    /** #1808: loaded first when installed and enabled; never required */
+    optionalDependencies: string[];
+    error: string | null;
+    /** 'domain' | 'additive' | undefined (unset addons behave as additive) */
+    type?: 'domain' | 'additive';
+    details?: AddonStatusDetails;
+    statusError?: string;
+    /** #443: add-on ships a deployable theme/ (theme.json sentinel present) */
+    hasTheme?: boolean;
+    /** #443: themes/<name>/ already exists in the instance */
+    themeDeployed?: boolean;
+    /** #1414: what turning this addon off would shut — shown in the Disable confirmation */
+    disableWarnings?: string[];
+}
+/**
+ * AddonsManager - Manages optional add-on modules
+ */
+declare class AddonsManager extends BaseManager {
+    /** Map of discovered add-ons by name */
+    private addons;
+    /** Configured paths to addons directories (one or more) */
+    private addonsPaths;
+    /** Resolved absolute paths to addons directories */
+    private resolvedAddonsPaths;
+    /** #673: npm package globs (from `node_modules:` addons-path entries) to discover from node_modules. */
+    private npmAddonPatterns;
+    /** #1830: `<data>/addons`, where installed add-ons live; null when there is no data folder. */
+    private installedDir;
+    /** #1830: the installed add-ons verified this boot — the only ones loaded from `installedDir`. */
+    private verifiedInstalled;
+    /** Stylesheets registered by add-ons via registerStylesheet() */
+    private registeredStylesheets;
+    /** Dashboard cards registered by add-ons via registerDashboardCard() */
+    private dashboardCards;
+    /** Name of the first domain addon loaded — only one is permitted */
+    private domainAddonName;
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the AddonsManager
+     *
+     * Reads configuration, discovers add-ons, and loads enabled ones
+     * in dependency order.
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * #1830: install the add-ons `ngdpbase.addons.install` names into
+     * `<data>/addons` (sha512 and Sigstore provenance checked), or verify the
+     * ones already there. An empty map (the shipped default) does nothing at all.
+     * Every request — registry, attestations, the Sigstore TUF repository — goes
+     * through the guarded client and the egress policy (#1139). A problem with one add-on
+     * never stops the boot: it is logged and posted to admins, and that add-on is
+     * simply not there to load. When anything on disk changed, the configuration
+     * is re-merged so the add-on's config/default-config.json layer applies on
+     * this boot, not the next.
+     */
+    private installConfiguredAddons;
+    /**
+     * `addon-install` (#1830): written after every check passed and before
+     * anything is written to disk. on-failure: refuse — code does not join the
+     * site unrecorded, so a record that cannot be written stops the install
+     * (recordSystemAction throws, and the installer writes nothing).
+     */
+    private recordAddonInstall;
+    /**
+     * `addon-verify-failed` (#1830): an integrity, provenance, tarball, manifest,
+     * lock or folder check refused (or, for a repaired folder, found it changed).
+     * on-failure: continue — the refusal has already happened; a lost record
+     * must not change it.
+     */
+    private recordVerifyFailed;
+    /** Tell admins about an install problem (#1830). Best-effort, like recordSeedFailure. */
+    private notifyInstallProblem;
+    /**
+     * Discover available add-ons by scanning all configured addons directories.
+     */
+    discoverAddons(): Promise<void>;
+    /**
+     * #1830: register the add-ons in `<data>/addons` that the installer verified
+     * this boot. Anything else there — a folder copied in by hand, or one whose
+     * entry left the install map — is not loaded, and admins are told.
+     */
+    private scanInstalledAddons;
+    /**
+     * Scan a single addons directory and register any add-ons found.
+     */
+    private scanAddonsDirectory;
+    /**
+     * #673 (packaged model): discover addons published as npm packages, matching a
+     * `node_modules:<glob>` addons-path entry (e.g. `node_modules:@jwilleke/*-addon`).
+     * Each matching package is loaded through the same slug/module/register()
+     * contract as bundled and drop-in addons — only discovery differs.
+     */
+    private scanNpmAddons;
+    /** Locate the node_modules directory (app root / cwd). */
+    private findNodeModules;
+    /** Expand a `@scope/glob` (or bare `glob`) pattern to package directories. */
+    private resolveNpmAddonDirs;
+    /**
+     * Load a single addon from its directory (index.js/ts + optional package.json
+     * `ngdpbase` manifest) and register it. Shared by directory scans and npm
+     * (#673) discovery; `sourceLabel` is for logging only. `source` selects the
+     * no-slug identity fallback (#927): a directory addon's folder name is its
+     * identity verbatim, while an npm package strips the conventional `-addon`
+     * suffix. Duplicate ids are skipped — since npm discovery runs last, a
+     * bundled/drop-in addon wins.
+     */
+    private registerAddonFromDir;
+    /**
+     * 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.
+     */
+    private incompatibility;
+    /**
+     * Check if an add-on is enabled in configuration
+     */
+    isEnabled(addonName: string): boolean;
+    /**
+     * Validate that an add-on can be safely disabled (#617).
+     *
+     * Mirrors the enable-time topological-sort dep check at `resolveLoadOrder()`:
+     * if any *enabled* add-on declares `dependencies: ['<addonName>']`, the
+     * disable is blocked and the dependent's name is returned. Callers should
+     * surface the blocker to the operator and refuse the disable.
+     *
+     * @param addonName  The add-on the operator wants to disable.
+     * @returns          `{ ok: true }` if safe to disable. Otherwise
+     *                   `{ ok: false, blockedBy: ['dep1', 'dep2', ...] }` with
+     *                   the names of every enabled addon that depends on it.
+     */
+    canDisable(addonName: string): {
+        ok: true;
+    } | {
+        ok: false;
+        blockedBy: string[];
+    };
+    /**
+     * Get add-on specific configuration
+     */
+    getAddonConfig(addonName: string): Record<string, unknown>;
+    /**
+     * Seed wiki pages shipped with an add-on.
+     *
+     * If the add-on directory contains a `pages/` subdirectory, any `.md` files
+     * found there are copied to the instance pages directory — but only if a file
+     * with the same name does not already exist (user edits are never overwritten).
+     *
+     * This mirrors how `required-pages/` seeds core pages at install time.
+     *
+     * @param addonName  Name of the add-on (for logging)
+     * @param addonPath  Filesystem path to the add-on directory
+     */
+    /**
+     * Default edit-protection for a seeded addon page (#971, addons.md §3).
+     *
+     * §3 settled the mechanism: the seeder stamps frontmatter `access`, which
+     * Tier 1 of the evaluator honours directly, needs no `PolicyEvaluator`
+     * change, and is hash-neutral (`pageSourceHash` covers the body only, so
+     * adding metadata cannot disturb the #920 reseed comparison).
+     *
+     * §9 settled *who owns what*, and the two must be read together. A blanket
+     * admin lock would contradict the operator's decision that domain content
+     * pages "should be normal pages, purely seeded by the addon" — the addon
+     * provides a starting corpus and then lets go. So the default follows §9's
+     * ownership column rather than locking everything:
+     *
+     * | Category | Purpose | Default |
+     * |---|---|---|
+     * | `system` | Feature UI, site chrome — infrastructure | admin-only edit |
+     * | `documentation` | Help / docs — addon-owned | admin-only edit |
+     * | `general` | Domain content, demo — **instance-owned** | no stamp |
+     * | anything else | unclassified, treated as addon-owned | admin-only edit |
+     *
+     * An addon can always override by declaring its own `access`, which is the
+     * documented escape hatch in §3 and the reason the default is a default.
+     *
+     * @param category - The page's resolved `system-category`
+     * @returns The access object to stamp, or undefined to leave the page unprotected
+     */
+    private defaultAddonPageAccess;
+    /**
+     * Surface a page-level seed failure beyond the boot log (#951).
+     *
+     * A boot-time log line is invisible ten minutes later, which is how a page
+     * that never seeded stays missing for weeks. Raising an operator
+     * notification makes the failure outlive the boot it happened on.
+     *
+     * Deliberately NOT fail-fast. Refusing to start because a third-party addon
+     * shipped one malformed page turns an authoring typo into an outage, and the
+     * #672 precedent does not transfer — that was the operator's own config
+     * naming a nonexistent addon, which the operator can fix. A vendor's
+     * malformed file is not in the operator's control. Skip the page, report
+     * loudly, surface it after boot.
+     *
+     * Best-effort: notification failure must never break seeding.
+     */
+    private recordSeedFailure;
+    /**
+     * #1559: tell admins what the configuration merge refused in the add-ons'
+     * system-categories, or overrode in the operator's file — logged there at
+     * boot, surfaced here once notifications exist. Not fail-fast, for the
+     * reason recordSeedFailure gives: an add-on's file is not in the operator's
+     * control. A refused entry fails closed (its category and vault do not
+     * exist, so nothing is written unsealed or public by mistake). Best-effort.
+     */
+    private notifySystemCategoryProblems;
+    private seedAddonPages;
+    /** Pages reseeded by the current `seedAddonPages` pass (#920). */
+    private lastReseedCount;
+    /**
+     * An addon page this site already holds: metadata tidy-ups (#971, #1003) and
+     * the opt-in content reseed (#920), then a search-index refresh. Called by the
+     * shared seeder for each source page that is live (#1406).
+     */
+    private reconcileSeededAddonPage;
+    private getInstanceThemesDir;
+    /**
+     * True if the add-on ships a deployable theme. `theme/theme.json` is the
+     * presence sentinel (mirrors `pages/` needing at least one `.md`).
+     */
+    addonShipsTheme(addonPath: string): boolean;
+    /**
+     * #443: Deploy an add-on's `theme/` into the instance `themes/<name>/`.
+     *
+     * When an add-on ships a `theme/` subdirectory it should land in the
+     * instance themes directory the same way `seedAddonPages()` handles
+     * `pages/`. ThemeManager then reads it via `ngdpbase.theme.active` (set by
+     * the addon's domainDefaults) — no ThemeManager change needed.
+     *
+     * @param addonName  Add-on name (also the destination theme folder)
+     * @param addonPath  Filesystem path to the add-on directory
+     * @param overwrite  false (default) = first-boot copy, never overwrites an
+     *                    existing `themes/<name>/` (preserves instance edits);
+     *                    true = dashboard-triggered redeploy, replaces it.
+     * @returns Result describing what happened (for the admin UI).
+     */
+    seedAddonTheme(addonName: string, addonPath: string, overwrite?: boolean): Promise<{
+        ok: boolean;
+        deployed: boolean;
+        message: string;
+    }>;
+    /**
+     * #443: Dashboard-triggered theme (re)deploy — always overwrites so theme
+     * updates shipped by the add-on can be pulled in without a server restart
+     * (theme CSS is served as static files; a page reload suffices).
+     *
+     * @param addonName  Add-on name
+     * @returns Result for the admin UI
+     */
+    deployAddonTheme(addonName: string): Promise<{
+        ok: boolean;
+        deployed: boolean;
+        message: string;
+    }>;
+    /**
+     * Load all enabled add-ons in dependency order
+     */
+    private loadAddons;
+    /**
+     * Resolve dependency order using topological sort
+     *
+     * @returns Array of add-on names in load order
+     * @throws Error if circular dependency detected
+     */
+    resolveLoadOrder(): string[];
+    /**
+     * Load a single add-on
+     */
+    loadAddon(addonName: string): Promise<void>;
+    /**
+     * What turning this addon off would shut (#1414): one line per store kind it
+     * owns that users hold data in. Turning it off is warned, never refused —
+     * nothing is destroyed, the kind stays in configuration, every copy stays on
+     * disk (sealed ones keep their wrapped key), and turning it back on reopens
+     * them. Separate from `canDisable`, which stays synchronous: counting copies
+     * reads the disk.
+     */
+    storeDisableWarnings(addonName: string): Promise<string[]>;
+    /**
+     * Where the addon that owns a store kind stands, for the store door (#1414):
+     * loaded, enabled but failed to load, turned off, or not on this site.
+     */
+    storeOwnerState(addonName: string): StoreOwnerState;
+    /**
+     * Inject domainDefaults from the add-on's package.json ngdpbase key
+     * into the merged config, but only for keys not already explicitly
+     * set by the operator in custom config.
+     */
+    private applyDomainDefaults;
+    /**
+     * Get status of all discovered add-ons
+     */
+    getStatus(): Promise<AddonStatus[]>;
+    /**
+     * Collect profile-page sections contributed by loaded addons (#534).
+     *
+     * Iterates every loaded addon that implements `profileSection()`, fans
+     * out IN PARALLEL via `Promise.allSettled`, then packages results for
+     * `profile.ejs`. Errors and `null` returns are skipped (malformed shapes
+     * are logged so addon authors get a diagnostic instead of an invisibly-
+     * missing card). One failing addon must not break the profile page.
+     *
+     * Mirrors the `getStatus()` pattern but runs in parallel so page-render
+     * latency is bounded by the slowest addon, not the sum.
+     *
+     * Result order follows registration order of the addons map so the
+     * displayed section order is stable across renders.
+     */
+    getProfileSections(user: AddonProfileUser): Promise<AddonProfileSectionEntry[]>;
+    /**
+     * #1234: say at load when an addon still implements the pre-#1234 hook.
+     *
+     * The two shapes have the same arity, so the only tell is the name the
+     * addon gave its first parameter — a heuristic, and stated as one. A false
+     * negative costs nothing new: the save still fails per call and is logged
+     * by `saveProfileSections`. A hit turns that silent stop into a boot line
+     * naming the addon and the migration.
+     */
+    private warnOldProfileHook;
+    /**
+     * Fan out `POST /preferences` body to every loaded addon that registered a
+     * `saveProfileSection()` handler (#534).
+     *
+     * Runs SEQUENTIALLY — each addon's read-modify-write of user preferences
+     * (typical implementation: `getUser → merge → updateUser`) must see the
+     * previous addon's writes. Parallel execution would create a same-snapshot
+     * race where two addons read identical preferences, each merge their own
+     * keys, and the second writer clobbers the first writer's changes.
+     * Self-inflicted by the original #534 PR; reverted to sequential here.
+     *
+     * (`getProfileSections()` above stays parallel — it's a read path with no
+     * cross-addon write contention.)
+     *
+     * Body shape: the host normalizes whatever shape qs produced into FLAT
+     * dotted keys before fan-out, so addons always see `body['journal.X']`
+     * regardless of whether body-parser was configured with `allowDots: true`
+     * (which would have produced `body.journal.X` instead). This is a
+     * defensive contract — today's `express.urlencoded({ extended: true })`
+     * leaves dotted form-field names flat by default, but a future config
+     * change shouldn't silently break addons. See `flattenDottedKeys`.
+     *
+     * Errors are caught per-addon and logged so one bad addon cannot block
+     * other addons' saves or the core-preferences save.
+     */
+    saveProfileSections(ctx: ActorContext, body: Record<string, unknown>): Promise<void>;
+    /**
+     * Get count of loaded add-ons
+     */
+    private getLoadedCount;
+    /**
+     * Register a stylesheet URL to be injected into every page's <head>.
+     *
+     * Call this from your add-on's register() function:
+     * ```js
+     * const addonsManager = engine.getManager('AddonsManager');
+     * addonsManager.registerStylesheet('/addons/my-addon/css/style.css');
+     * ```
+     *
+     * The URL must be publicly accessible (served via Express static or a CDN).
+     * Add-on CSS files under `addons/<name>/public/` are automatically served at
+     * `/addons/<name>/public/` when the server starts.
+     *
+     * @param url    Public URL of the stylesheet (e.g. '/addons/my-addon/css/style.css')
+     * @param addonName  Optional: name of the registering add-on (for logging)
+     */
+    registerStylesheet(url: string, addonName?: string): void;
+    /**
+     * Return the ordered list of stylesheet URLs registered by all add-ons.
+     * Called by the template layer to inject <link> tags into <head>.
+     */
+    getRegisteredStylesheets(): string[];
+    /**
+     * Register a dashboard card for this add-on. Called from the add-on's register() function.
+     * Live stats shown on the card are sourced from the add-on's existing status() method.
+     */
+    registerDashboardCard(card: AddonDashboardCard): void;
+    /**
+     * Return all registered dashboard cards in registration order.
+     * Called by the admin dashboard route to populate the addon cards row.
+     */
+    getDashboardCards(): AddonDashboardCard[];
+    /**
+     * Get list of all discovered add-on names
+     */
+    getAddonNames(): string[];
+    /**
+     * Return the `pages/` directory path for each enabled addon that has one.
+     * Used by Required Pages Sync to surface addon pages alongside required pages.
+     */
+    getEnabledAddonPagesDirectories(): Array<{
+        name: string;
+        pagesDir: string;
+    }>;
+    /**
+     * #930: addon-seeded instance pages whose source file the addon **no longer
+     * ships** ("source removed"). Leave-and-flag — this only *detects*; nothing is
+     * deleted here. The admin surface surfaces these and offers an opt-in,
+     * versioned removal.
+     *
+     * Enumeration uses the indexed `system-category: addon` (via the search index)
+     * to narrow to addon pages — a small candidate set — instead of scanning the
+     * whole page store. Each candidate is attributed to its addon via the `addon`
+     * frontmatter stamp and diffed against that addon's CURRENT source UUID set.
+     * If search is unavailable, returns `[]` (detection is best-effort, never a
+     * source of deletions).
+     */
+    findOrphanedAddonPages(): Promise<Array<{
+        addonName: string;
+        uuid: string;
+        slug: string;
+        title: string;
+        userModified: boolean;
+    }>>;
+    /**
+     * Back-fill the page index's `addon` stamp for pages seeded before the field
+     * was indexed.
+     *
+     * Without this, orphan detection is blind on any existing instance: the field
+     * is written on save, and seeded pages are deliberately not re-saved once
+     * they exist. Cheap — it walks only each addon's own source pages (tens of
+     * files), never the whole page tree.
+     */
+    private backfillIndexAddonStamps;
+    /**
+     * Check if an add-on exists (discovered)
+     */
+    hasAddon(addonName: string): boolean;
+    /**
+     * Check if an add-on is loaded
+     */
+    isLoaded(addonName: string): boolean;
+    /**
+     * Graceful shutdown of all loaded add-ons
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Backup add-on manager state
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore is not supported for AddonsManager
+     * (add-ons are discovered at startup)
+     */
+    restore(backupData: BackupData): Promise<void>;
+}
+export default AddonsManager;