@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/utils/PathPreflight.js

@@ -0,0 +1,50 @@
+/**
+ * Preflight a configured filesystem path before anything tries to write to it.
+ *
+ * Detects ONE thing: a macOS `/Volumes/<X>/...` path whose mount is absent,
+ * where `fs.ensureDir` would otherwise crash the engine with an opaque
+ * `EACCES`. A mistyped path elsewhere is not caught at all — #645 tracks
+ * widening it.
+ *
+ * __The platform is injectable, and that is not a convenience.__ The check
+ * runs only on darwin, so on Linux CI the branch was unreachable: every
+ * assertion covering it was guarded by `if (process.platform === 'darwin')`
+ * and silently skipped, while `managerStatus.test.ts` asserted the degraded
+ * state unguarded and failed on every CI run. A test that can only pass on one
+ * developer's operating system is not a test of anything CI can protect, and a
+ * continuously-red check is one nobody reads.
+ *
+ * With the seam, the darwin logic is exercised on every platform, and the
+ * production default is still `process.platform`.
+ */
+import * as fs from 'fs';
+function realIsDirectory(path) {
+    try {
+        return fs.statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function checkConfiguredPath(p, options = {}) {
+    if (!p)
+        return { ok: true };
+    const platform = options.platform ?? process.platform;
+    const isDirectory = options.isDirectory ?? realIsDirectory;
+    if (platform === 'darwin' && p.startsWith('/Volumes/')) {
+        const segments = p.split('/').filter(Boolean);
+        if (segments.length >= 2) {
+            const mountRoot = `/${segments[0]}/${segments[1]}`;
+            if (!isDirectory(mountRoot)) {
+                return {
+                    ok: false,
+                    reason: 'missing-mount',
+                    missingMount: mountRoot,
+                    message: `Configured path "${p}" expects ${mountRoot} to be a mounted volume, but it is not currently mounted. ` +
+                        'Mount the volume, or update the configuration to point at an existing path.'
+                };
+            }
+        }
+    }
+    return { ok: true };
+}

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

@@ -0,0 +1,40 @@
+/**
+ * SectionUtils — extract and splice markdown sections for section editing.
+ *
+ * A "section" is an ATX-style heading (# through ######) plus all content
+ * up to (but not including) the next heading of the same or higher level.
+ *
+ * Frontmatter (YAML between leading --- delimiters) is preserved intact and
+ * excluded from section numbering. Headings inside fenced code blocks are
+ * ignored to avoid false positives.
+ */
+/**
+ * Convert heading text to its anchor slug. This IS the heading-id format:
+ * the page converter uses it via markdown-it-anchor (#1273, decision R2), so
+ * section links (#500) and rendered ids cannot drift apart.
+ *
+ * Algorithm mirrors GitHub Flavored Markdown:
+ *   1. Lowercase
+ *   2. Remove any character that is not a letter, digit, space, or hyphen
+ *   3. Replace whitespace runs with a single hyphen
+ *   4. Trim leading/trailing hyphens
+ *
+ * Examples:
+ *   "PLA (Polylactic Acid)"  → "pla-polylactic-acid"
+ *   "3D Printing Filaments"  → "3d-printing-filaments"
+ *   "Hello World"            → "hello-world"
+ */
+export declare function headingSlug(text: string): string;
+/** Return the number of sections (headings) in the document */
+export declare function getSectionCount(markdown: string): number;
+/**
+ * Extract the raw markdown for section N (0-indexed).
+ * Returns null if sectionIndex is out of range.
+ */
+export declare function extractSection(markdown: string, sectionIndex: number): string | null;
+/**
+ * Replace section N with newContent, returning the full updated markdown.
+ * The frontmatter and all other sections are preserved unchanged.
+ * Returns the original markdown if sectionIndex is out of range.
+ */
+export declare function spliceSection(markdown: string, sectionIndex: number, newContent: string): string;

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

@@ -0,0 +1,144 @@
+/**
+ * Addon defaults as a layer of the configuration merge (#1220).
+ *
+ * Every addon may ship `config/default-config.json`. Until #1220 those keys
+ * were injected at runtime, after the engine had initialised, whole-key and
+ * only when absent — so an addon could set its own settings but never add an
+ * entry to a catalog map such as `ngdpbase.permissions.definitions` or
+ * `ngdpbase.access.policies`, and the managers that copy those catalogs at
+ * boot never saw anything an addon said.
+ *
+ * Now the addon files are a layer between the shipped defaults and the
+ * operator's custom file:
+ *
+ *     merged = deepMerge(deepMerge(shipped, addons…), custom)
+ *
+ * The deep merge merges maps per entry and `id` arrays by id, so an addon adds
+ * a permission definition and its own policy additively and never touches a
+ * shipped entry. The operator's file still wins over everything.
+ *
+ * Discovery follows `ngdpbase.managers.addons-manager.addons-path` exactly as
+ * AddonsManager does — directories and `node_modules:` patterns — so bundled
+ * and external addons are treated alike. Only an addon whose
+ * `ngdpbase.addons.<slug>.enabled` is true in the shipped+custom view
+ * contributes; a disabled addon's opinions do not reach the catalog.
+ *
+ * One exception, `ngdpbase.system-category` (#1559): the system-categories an
+ * addon declares are read from every installed addon's file, enabled or not,
+ * so turning an addon off never makes its pages and vault unreachable. A
+ * turned-off addon's entries are not offered (`enabled: false`); each entry is
+ * stamped with its `owner`, the addon's slug, and the owner's declaration of
+ * the fields in OWNER_DECIDED_FIELDS stands over the operator's file. An entry
+ * that claims another owner, reuses another entry's key or vault, or has a
+ * value of the wrong type is refused, with a problem line naming it, and its
+ * addon is then not loaded at all (operator, 2026-10-16): none of its other
+ * keys apply, and its sound entries are kept as a turned-off addon's are.
+ *
+ * A second, `ngdpbase.addons.<slug>.database` (#1860): an addon's database
+ * declaration is read the same way, from every installed addon, so a
+ * turned-off addon's database stays known (and is backed up, #1723). It is
+ * 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.
+ */
+import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
+export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
+export declare const ADDONS_MANAGER_ENABLED_KEY = "ngdpbase.managers.addons-manager.enabled";
+export interface AddonDefaults {
+    slug: string;
+    dir: string;
+    source: 'directory' | 'npm';
+    /**
+     * Whether the addon is switched on. A turned-off addon's file is read for its
+     * system-categories alone (#1559); none of its other keys reach the merge.
+     */
+    enabled: boolean;
+    /** The addon's default-config.json with `_`-prefixed comment keys dropped. */
+    defaults: Record<string, unknown>;
+    /** Set when the file exists but could not be parsed; the addon then contributes nothing. */
+    error?: string;
+}
+/** Is this addon switched on in the shipped+custom view? */
+export declare function isAddonEnabled(base: Record<string, unknown>, slug: string): boolean;
+/**
+ * Every addon directory the configured path names, plus the installed add-ons
+ * in `<data>/addons` (#1830: only those the lock file names for a slug in the
+ * install map), whether or not it is enabled.
+ */
+export declare function discoverAddonDirs(base: Record<string, unknown>, cwd?: string, dataFolder?: string): Array<{
+    dir: string;
+    source: 'directory' | 'npm';
+}>;
+/**
+ * The defaults of every installed addon, enabled or not, in discovery order,
+ * each marked with whether it is `enabled`: the merge takes everything from
+ * an enabled addon and only the system-categories from a turned-off one
+ * (#1559). An addon with no default-config.json is omitted; one whose file
+ * cannot be parsed is returned with `error` set so the caller can say so
+ * rather than silently skip it.
+ */
+export declare function discoverAddonDefaults(base: Record<string, unknown>, cwd?: string, dataFolder?: string): AddonDefaults[];
+export interface AddonDatabaseLayer {
+    /** Every sound declaration, of every installed addon, `enabled` as its addon is. */
+    declarations: AddonDatabaseDeclaration[];
+    /** Addons whose declaration was refused, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * The databases the addons declare (#1860), from every addon's file whether
+ * or not it is enabled. An addon declares only under its own slug; a second
+ * declaration of one owner's ledger is refused. `custom` is the operator's
+ * 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;
+/**
+ * shipped ⊕ addons ⊕ custom, in that order of precedence (custom wins), with
+ * the problems found in the addons' system-categories (#1559).
+ *
+ * Each enabled addon folds onto the shipped defaults in turn, not onto the
+ * other addons alone: an addon's list of names for a set map (`secret-keys`)
+ * then adds to the shipped set, and a second addon's list adds again rather
+ * than replacing the first (#1612). `ngdpbase.system-category` is taken from
+ * every addon, enabled or not, through {@link addonCategoryLayer}, and its
+ * owner-decided fields stand over custom.
+ */
+export declare function mergeWithAddonLayer<T extends Record<string, unknown>>(shipped: T, addons: readonly AddonDefaults[], custom: Partial<T>): {
+    merged: T;
+    problems: string[];
+    refused: Map<string, string>;
+    databases: AddonDatabaseDeclaration[];
+};
+/**
+ * The full merge for a caller with the two files already read (the manager,
+ * and the pre-engine reader): discover addons against the shipped+custom view,
+ * then fold them in beneath custom. `declared` is the same merge without
+ * custom (#1638); `addons` lists the enabled addons whose keys apply;
+ * `problems` names every addon system-category refused, every operator value
+ * an owner's declaration overrode, and every turned-off addon whose file
+ * 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).
+ */
+export declare function mergeConfigWithAddons<T extends Record<string, unknown>>(shipped: T, custom: Partial<T>, cwd?: string, dataFolder?: string): {
+    merged: T;
+    declared: T;
+    addons: AddonDefaults[];
+    problems: string[];
+    refused: Map<string, string>;
+    databases: AddonDatabaseDeclaration[];
+};
+export interface MergedConfigFiles {
+    merged: Record<string, unknown>;
+    customKeys: Set<string>;
+    addons: AddonDefaults[];
+}
+/**
+ * The merged configuration for a caller that runs before the engine exists
+ * (#1214): the two files plus the addon layer, the same merge the manager
+ * performs. Returns null on any failure: a missing or malformed file must not
+ * stop the server binding a socket; the port simply falls back. No `${VAR}`
+ * resolution and no env-key overrides — those are `getProperty`'s job.
+ */
+export declare function loadMergedConfigSync(env?: Record<string, string | undefined>, cwd?: string): MergedConfigFiles | null;

package/lib/src/utils/addonConfigLayer.js

@@ -0,0 +1,382 @@
+/**
+ * Addon defaults as a layer of the configuration merge (#1220).
+ *
+ * Every addon may ship `config/default-config.json`. Until #1220 those keys
+ * were injected at runtime, after the engine had initialised, whole-key and
+ * only when absent — so an addon could set its own settings but never add an
+ * entry to a catalog map such as `ngdpbase.permissions.definitions` or
+ * `ngdpbase.access.policies`, and the managers that copy those catalogs at
+ * boot never saw anything an addon said.
+ *
+ * Now the addon files are a layer between the shipped defaults and the
+ * operator's custom file:
+ *
+ *     merged = deepMerge(deepMerge(shipped, addons…), custom)
+ *
+ * The deep merge merges maps per entry and `id` arrays by id, so an addon adds
+ * a permission definition and its own policy additively and never touches a
+ * shipped entry. The operator's file still wins over everything.
+ *
+ * Discovery follows `ngdpbase.managers.addons-manager.addons-path` exactly as
+ * AddonsManager does — directories and `node_modules:` patterns — so bundled
+ * and external addons are treated alike. Only an addon whose
+ * `ngdpbase.addons.<slug>.enabled` is true in the shipped+custom view
+ * contributes; a disabled addon's opinions do not reach the catalog.
+ *
+ * One exception, `ngdpbase.system-category` (#1559): the system-categories an
+ * addon declares are read from every installed addon's file, enabled or not,
+ * so turning an addon off never makes its pages and vault unreachable. A
+ * turned-off addon's entries are not offered (`enabled: false`); each entry is
+ * stamped with its `owner`, the addon's slug, and the owner's declaration of
+ * the fields in OWNER_DECIDED_FIELDS stands over the operator's file. An entry
+ * that claims another owner, reuses another entry's key or vault, or has a
+ * value of the wrong type is refused, with a problem line naming it, and its
+ * addon is then not loaded at all (operator, 2026-10-16): none of its other
+ * keys apply, and its sound entries are kept as a turned-off addon's are.
+ *
+ * A second, `ngdpbase.addons.<slug>.database` (#1860): an addon's database
+ * declaration is read the same way, from every installed addon, so a
+ * turned-off addon's database stays known (and is backed up, #1723). It is
+ * 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.
+ */
+import fs from 'fs';
+import path from 'path';
+import { isDeepStrictEqual } from 'util';
+import { configFilePaths, deepMergeConfigs, deepMergeObjects, instanceDataFolder, isPlainObject, readConfigFilesSync } from './configFiles.js';
+import { configuredInstallSlugs, findNodeModulesDir, installedAddonsDir, matchNpmPackageDirs, resolveAddonSlug, splitAddonsPath } from './addonsPathResolver.js';
+import { lockedAddonDirsSync } from './addonLock.js';
+import { parsePrivatestore } from './privateStorePath.js';
+import { OWNER_DECIDED_FIELDS, SYSTEM_CATEGORY_KEY, systemCategoryValueProblems } from './systemCategoryRules.js';
+import { addonDatabaseKey, addonDatabaseKeySlug, addonDatabaseProblems } from './addonDatabaseRules.js';
+export const ADDONS_PATH_KEY = 'ngdpbase.managers.addons-manager.addons-path';
+export const ADDONS_MANAGER_ENABLED_KEY = 'ngdpbase.managers.addons-manager.enabled';
+/** Is this addon switched on in the shipped+custom view? */
+export function isAddonEnabled(base, slug) {
+    return base[`ngdpbase.addons.${slug}.enabled`] === true;
+}
+/**
+ * Every addon directory the configured path names, plus the installed add-ons
+ * in `<data>/addons` (#1830: only those the lock file names for a slug in the
+ * install map), whether or not it is enabled.
+ */
+export function discoverAddonDirs(base, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
+    if (base[ADDONS_MANAGER_ENABLED_KEY] === false)
+        return [];
+    const { directories, npmPatterns } = splitAddonsPath(base[ADDONS_PATH_KEY] ?? './addons');
+    const found = [];
+    for (const raw of directories) {
+        const root = path.resolve(cwd, raw);
+        let entries;
+        try {
+            entries = fs.readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'shared')
+                continue;
+            found.push({ dir: path.join(root, entry.name), source: 'directory' });
+        }
+    }
+    const installed = installedAddonsDir(dataFolder, cwd);
+    if (!found.some((f) => path.dirname(f.dir) === installed)) {
+        for (const dir of lockedAddonDirsSync(installed, configuredInstallSlugs(base)))
+            found.push({ dir, source: 'directory' });
+    }
+    const nmRoot = npmPatterns.length > 0 ? findNodeModulesDir(cwd) : null;
+    if (nmRoot) {
+        for (const pattern of npmPatterns) {
+            for (const dir of matchNpmPackageDirs(nmRoot, pattern))
+                found.push({ dir, source: 'npm' });
+        }
+    }
+    return found;
+}
+/**
+ * The defaults of every installed addon, enabled or not, in discovery order,
+ * each marked with whether it is `enabled`: the merge takes everything from
+ * an enabled addon and only the system-categories from a turned-off one
+ * (#1559). An addon with no default-config.json is omitted; one whose file
+ * cannot be parsed is returned with `error` set so the caller can say so
+ * rather than silently skip it.
+ */
+export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
+    const out = [];
+    for (const { dir, source } of discoverAddonDirs(base, cwd, dataFolder)) {
+        const slug = resolveAddonSlug(dir, source);
+        const enabled = isAddonEnabled(base, slug);
+        const file = path.join(dir, 'config', 'default-config.json');
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (!isPlainObject(raw))
+                throw new Error('not a JSON object');
+            const defaults = {};
+            for (const [key, value] of Object.entries(raw))
+                if (!key.startsWith('_'))
+                    defaults[key] = value;
+            out.push({ slug, dir, source, enabled, defaults });
+        }
+        catch (err) {
+            out.push({ slug, dir, source, enabled, defaults: {}, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return out;
+}
+function vaultIdOf(entry) {
+    return parsePrivatestore(entry?.storageLocation?.privatestore)?.vaultId;
+}
+/**
+ * The system-categories the addons declare (#1559), from every addon's file
+ * whether or not it is enabled. `shipped` and `custom` are the site's own
+ * category maps: an addon may not take a key the shipped map has, nor a vault
+ * another entry names.
+ */
+function addonCategoryLayer(shipped, custom, addons) {
+    const siteKeys = new Set(isPlainObject(shipped) ? Object.keys(shipped) : []);
+    const vaultKey = new Map();
+    for (const map of [shipped, custom]) {
+        if (!isPlainObject(map))
+            continue;
+        for (const [key, entry] of Object.entries(map)) {
+            const vaultId = vaultIdOf(entry);
+            if (vaultId && !vaultKey.has(vaultId))
+                vaultKey.set(vaultId, key);
+        }
+    }
+    const layer = { entries: {}, turnedOff: new Set(), refused: new Map(), problems: [] };
+    const declaredBy = new Map();
+    for (const addon of addons) {
+        const declared = addon.defaults[SYSTEM_CATEGORY_KEY];
+        if (declared === undefined)
+            continue;
+        const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+        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`);
+            layer.refused.set(addon.slug, `its system-category declaration was refused: ${reason}`);
+            continue;
+        }
+        const refusedHere = [];
+        const acceptedHere = [];
+        for (const [key, entry] of Object.entries(declared)) {
+            const reasons = [];
+            if (!isPlainObject(entry)) {
+                reasons.push('the entry is not an object');
+            }
+            else {
+                if (entry.owner !== undefined && entry.owner !== addon.slug) {
+                    reasons.push(`its owner is ${JSON.stringify(entry.owner)}; an add-on declares only its own, owner '${addon.slug}'`);
+                }
+                if (siteKeys.has(key))
+                    reasons.push(`'${key}' is one of the site's own system-categories`);
+                else if (declaredBy.has(key))
+                    reasons.push(`add-on '${declaredBy.get(key)}' already declares '${key}'`);
+                if (entry.default === true)
+                    reasons.push('default: true belongs to the site\'s default system-category only');
+                const privatestore = entry.storageLocation?.privatestore;
+                const vaultId = vaultIdOf(entry);
+                if (privatestore !== undefined && !vaultId) {
+                    reasons.push(`storageLocation.privatestore must be pages/<parent>/{user}/<vault id>/, got ${JSON.stringify(privatestore)}`);
+                }
+                else if (vaultId && vaultKey.has(vaultId) && vaultKey.get(vaultId) !== key) {
+                    reasons.push(`its vault '${vaultId}' is already the vault of system-category '${vaultKey.get(vaultId)}'`);
+                }
+                reasons.push(...systemCategoryValueProblems(key, entry).map((p) => p.message));
+            }
+            if (reasons.length > 0) {
+                layer.problems.push(`${who}: system-category '${key}' is refused (${reasons.join('; ')}); the add-on is not loaded`);
+                refusedHere.push(`'${key}' (${reasons.join('; ')})`);
+                continue;
+            }
+            layer.entries[key] = { ...entry, owner: addon.slug };
+            acceptedHere.push(key);
+            declaredBy.set(key, addon.slug);
+            const vaultId = vaultIdOf(entry);
+            if (vaultId)
+                vaultKey.set(vaultId, key);
+        }
+        // An add-on with a refused entry is not loaded (operator, 2026-10-16), so
+        // its sound entries are kept as a turned-off add-on's are: readable, never
+        // offered.
+        if (refusedHere.length > 0)
+            layer.refused.set(addon.slug, `its system-category declaration was refused: ${refusedHere.join('; ')}`);
+        if (!addon.enabled || refusedHere.length > 0) {
+            for (const key of acceptedHere) {
+                layer.entries[key].enabled = false;
+                layer.turnedOff.add(key);
+            }
+        }
+    }
+    return layer;
+}
+/**
+ * The databases the addons declare (#1860), from every addon's file whether
+ * or not it is enabled. An addon declares only under its own slug; a second
+ * declaration of one owner's ledger is refused. `custom` is the operator's
+ * file: a value there for a declaration's key is ignored, and said so.
+ */
+export function addonDatabaseLayer(addons, custom) {
+    const layer = { declarations: [], refused: new Map(), problems: [] };
+    const ledgerBy = new Map();
+    for (const addon of addons) {
+        const reasons = [];
+        let declared;
+        for (const [key, value] of Object.entries(addon.defaults)) {
+            const slug = addonDatabaseKeySlug(key);
+            if (slug === null)
+                continue;
+            if (slug === addon.slug)
+                declared = value;
+            else
+                reasons.push(`it declares ${key}; an add-on declares only its own, ${addonDatabaseKey(addon.slug)}`);
+        }
+        if (declared !== undefined) {
+            const valueProblems = addonDatabaseProblems(declared);
+            reasons.push(...valueProblems);
+            if (valueProblems.length === 0) {
+                const { owner, ledgerTable } = declared;
+                const by = ledgerBy.get(`${owner}/${ledgerTable}`);
+                if (by)
+                    reasons.push(`add-on '${by}' already declares ledger '${ledgerTable}' of database '${owner}'`);
+            }
+        }
+        if (reasons.length > 0) {
+            const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+            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;
+        }
+        if (declared === undefined)
+            continue;
+        const { owner, ledgerTable, encrypt } = declared;
+        ledgerBy.set(`${owner}/${ledgerTable}`, addon.slug);
+        layer.declarations.push({ owner, ledgerTable, encrypt, declaredBy: addon.slug, enabled: addon.enabled });
+        if (custom[addonDatabaseKey(addon.slug)] !== undefined) {
+            layer.problems.push(`app-custom-config.json sets ${addonDatabaseKey(addon.slug)}, which is the declaration of add-on '${addon.slug}'; the site's value is ignored`);
+        }
+    }
+    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
+ * the operator's file's, and a turned-off addon's entry is never offered.
+ * Returns the merged map with that applied, and a line for each value of the
+ * operator's that is ignored.
+ */
+function ownerDeclarationsStand(merged, layer, custom) {
+    if (!isPlainObject(merged))
+        return { categories: merged, problems: [] };
+    const categories = { ...merged };
+    const problems = [];
+    for (const [key, declared] of Object.entries(layer.entries)) {
+        const entry = categories[key];
+        if (!isPlainObject(entry))
+            continue;
+        const site = isPlainObject(custom) && isPlainObject(custom[key]) ? custom[key] : {};
+        const restored = { ...entry };
+        for (const field of OWNER_DECIDED_FIELDS) {
+            if (declared[field] === undefined)
+                delete restored[field];
+            else
+                restored[field] = declared[field];
+            if (site[field] !== undefined && !isDeepStrictEqual(site[field], declared[field])) {
+                problems.push(`app-custom-config.json sets ${SYSTEM_CATEGORY_KEY}.${key}.${field}, which is the declaration of its owner '${String(declared.owner)}'; the site's value is ignored`);
+            }
+        }
+        if (layer.turnedOff.has(key))
+            restored.enabled = false;
+        categories[key] = restored;
+    }
+    return { categories, problems };
+}
+/**
+ * shipped ⊕ addons ⊕ custom, in that order of precedence (custom wins), with
+ * the problems found in the addons' system-categories (#1559).
+ *
+ * Each enabled addon folds onto the shipped defaults in turn, not onto the
+ * other addons alone: an addon's list of names for a set map (`secret-keys`)
+ * then adds to the shipped set, and a second addon's list adds again rather
+ * than replacing the first (#1612). `ngdpbase.system-category` is taken from
+ * every addon, enabled or not, through {@link addonCategoryLayer}, and its
+ * owner-decided fields stand over custom.
+ */
+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 refused = new Map(layer.refused);
+    for (const [slug, reason] of databaseLayer.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
+        .filter((a) => a.enabled && !refused.has(a.slug))
+        .reduce((acc, a) => {
+        const rest = { ...a.defaults };
+        delete rest[SYSTEM_CATEGORY_KEY];
+        for (const key of Object.keys(rest))
+            if (addonDatabaseKeySlug(key) !== null)
+                delete rest[key];
+        return deepMergeObjects(acc, rest);
+    }, shipped);
+    if (Object.keys(layer.entries).length === 0) {
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems], refused, databases };
+    }
+    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 };
+}
+/**
+ * The full merge for a caller with the two files already read (the manager,
+ * and the pre-engine reader): discover addons against the shipped+custom view,
+ * then fold them in beneath custom. `declared` is the same merge without
+ * custom (#1638); `addons` lists the enabled addons whose keys apply;
+ * `problems` names every addon system-category refused, every operator value
+ * an owner's declaration overrode, and every turned-off addon whose file
+ * 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).
+ */
+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 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`);
+    return {
+        merged,
+        declared: mergeWithAddonLayer(shipped, all, {}).merged,
+        addons: all.filter((a) => a.enabled && !refused.has(a.slug)),
+        problems: [...unreadable, ...problems],
+        refused,
+        databases
+    };
+}
+/**
+ * The merged configuration for a caller that runs before the engine exists
+ * (#1214): the two files plus the addon layer, the same merge the manager
+ * performs. Returns null on any failure: a missing or malformed file must not
+ * stop the server binding a socket; the port simply falls back. No `${VAR}`
+ * resolution and no env-key overrides — those are `getProperty`'s job.
+ */
+export function loadMergedConfigSync(env = process.env, cwd = process.cwd()) {
+    try {
+        const paths = configFilePaths(env, cwd);
+        const files = readConfigFilesSync(paths);
+        const { merged, addons } = mergeConfigWithAddons(files.defaultConfig ?? {}, files.customConfig, cwd, paths.instanceDataFolder);
+        return { merged, customKeys: files.customKeys, addons };
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,25 @@
+/** A canonical add-on slug: lowercase letters and digits, single dashes. */
+export declare const ADDON_SLUG: RegExp;
+/** The values `encrypt` may take. */
+export declare const DATABASE_ENCRYPT_VALUES: readonly ["required", "optional"];
+export type DatabaseEncrypt = typeof DATABASE_ENCRYPT_VALUES[number];
+/** The configuration key under which an add-on declares its database. */
+export declare function addonDatabaseKey(slug: string): string;
+/** The slug in a `ngdpbase.addons.<slug>.database` key, or null for any other key. */
+export declare function addonDatabaseKeySlug(key: string): string | null;
+/** What a ledger table of this owner must start with: the slug, dashes as underscores, then `_`. */
+export declare function ledgerPrefix(owner: string): string;
+/** One accepted declaration, as core knows it whether or not its add-on is on. */
+export interface AddonDatabaseDeclaration {
+    /** Whose file: `<owner>.db` beside the application database. */
+    owner: string;
+    /** The migration ledger this declaration is for. */
+    ledgerTable: string;
+    encrypt: DatabaseEncrypt;
+    /** The add-on whose file declares it. */
+    declaredBy: string;
+    /** Whether that add-on is switched on and was not refused. */
+    enabled: boolean;
+}
+/** What is wrong with one declaration, one line per problem. Empty when sound. */
+export declare function addonDatabaseProblems(value: unknown): string[];