@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,747 @@
+import { type ActorContext } from '../context/ActorContext.js';
+import { type EnvKeyMap, type PropertyDescription } from '../utils/configEnvKeys.js';
+import { WikiConfig } from '../types/Config.js';
+import BaseManager, { BackupData } from './BaseManager.js';
+import type { AddonDatabaseDeclaration } from '../utils/addonDatabaseRules.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+interface ConfigManagerBackupData extends BackupData {
+    customConfig: Partial<WikiConfig> | null;
+    environment?: string;
+    defaultConfig?: Partial<WikiConfig> | null;
+    mergedConfig?: Partial<WikiConfig> | null;
+    paths?: {
+        defaultConfigPath: string;
+        customConfigPath: string;
+    };
+    statistics?: {
+        defaultPropertiesCount: number;
+        customPropertiesCount: number;
+        mergedPropertiesCount: number;
+    };
+}
+/**
+ * ConfigurationManager - Handles JSPWiki-compatible configuration management
+ *
+ * Implements a two-tier configuration system that merges default settings with
+ * instance-specific overrides. This allows for flexible deployment configurations
+ * while maintaining sensible defaults.
+ *
+ * Configuration merge order (later overrides earlier):
+ * 1. config/app-default-config.json (base defaults - required, read-only)
+ * 2. INSTANCE_DATA_FOLDER/config/app-custom-config.json (instance overrides - optional)
+ *
+ * INSTANCE_DATA_FOLDER defaults to './data' but can be set via environment variable
+ * for Docker/Kubernetes deployments (typically '/app/data').
+ *
+ * @class ConfigurationManager
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {WikiConfig|null} defaultConfig - Default configuration (required)
+ * @property {Partial<WikiConfig>|null} customConfig - Custom local overrides (optional)
+ * @property {WikiConfig|null} mergedConfig - Final merged configuration
+ * @property {string} environment - Current environment (from NODE_ENV)
+ * @property {string} defaultConfigPath - Path to default config file
+ * @property {string} customConfigPath - Path to custom config file
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const configManager = engine.getManager('ConfigurationManager');
+ * const appName = configManager.getApplicationName();
+ * const port = configManager.getServerPort();
+ */
+declare class ConfigurationManager extends BaseManager {
+    private defaultConfig;
+    private customConfig;
+    private mergedConfig;
+    /** #1638: shipped ⊕ enabled addons, before the operator's file — what the build declares. */
+    private declaredConfig;
+    /** #1813: each enabled addon's own default-config.json, as folded into the merge. */
+    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. */
+    private refusedAddons;
+    /** #1860: every installed add-on's sound database declaration, on or off. */
+    private addonDatabases;
+    private environment;
+    private defaultConfigPath;
+    private customConfigPath;
+    private instanceDataFolder;
+    /**
+     * Creates a new ConfigurationManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the configuration manager
+     *
+     * Loads and merges all configuration files in the correct priority order.
+     *
+     * @async
+     * @returns {Promise<void>}
+     * @throws {Error} If default configuration file is not found
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * #642: returns true if `ngdpbase.application.base-url` was explicitly
+     * configured (in customConfig or via the NGDPBASE_BASE_URL env var), as
+     * opposed to falling through to the default. Consumers that need to emit
+     * absolute URLs to outside parties (magic-link auth, schema.org @ids,
+     * email templates) read this to decide whether the configured base URL
+     * is trustworthy or whether they should bail out / disable themselves.
+     *
+     * The migration shim in `migrateLegacyBaseUrl()` writes the canonical key
+     * into customConfig before this is called, so legacy `ngdpbase.base-url`
+     * and `ngdpbase.baseURL` configs return true here too.
+     */
+    isBaseUrlExplicit(): boolean;
+    /**
+     * #642: post-install startup invariant. Once `.install-complete` exists,
+     * the operator must have explicitly configured `ngdpbase.application.base-url`.
+     * Falling back to the default localhost URL silently emits broken
+     * absolute URLs (template variables, magic-link emails, org @ids), so we
+     * refuse to start instead.
+     *
+     * Pre-install (`.install-complete` absent), the default is fine — the
+     * install flow will set the value before completing.
+     */
+    private assertBaseUrlConfigured;
+    /**
+     * #658: refuse to start if `ngdpbase.application.contact.page` is set to
+     * `"contact"` — that would make /contact 302-redirect to /view/contact,
+     * which (because /view/contact does not exist) ends as a 404 anyway, but
+     * earlier intermediate routing or future renames could turn it into an
+     * actual redirect loop. Reject explicitly so operators see a clear error
+     * instead of a runtime surprise.
+     */
+    private assertContactPageNotLoop;
+    /**
+     * #670 Phase D: refuse to start if `ngdpbase.application.contact.recipient`
+     * contains a malformed address. The string accepts two patterns:
+     *
+     *   inline CSV         "alice@example.com, bob@example.com"
+     *   distribution list  "admins@example.com"
+     *
+     * The single-address form is just a degenerate CSV. We split on `,`, trim
+     * each segment, regex-check the shape, and throw if any segment fails. The
+     * regex is the same pragmatic shape check the form uses post-validation —
+     * not RFC-perfect; SMTP verifies the rest on send.
+     *
+     * Empty config is fine (recipient resolves at request time from the admin
+     * list — see UserManager.getContactRecipient). Whitespace-only segments
+     * (e.g., trailing comma "a@b, ") are treated as malformed because they
+     * usually indicate a typo.
+     */
+    private assertContactRecipientWellFormed;
+    /**
+     * #672: refuse to start if any `ngdpbase.addons.<id>.enabled = true` key
+     * references an `<id>` that has no matching addon in any configured
+     * `addons-path` entry — either a directory (bundled/drop-in) or, per
+     * #673/#924, an npm package matched by a `node_modules:<glob>` entry.
+     * The discovery logic mirrors what `AddonsManager` does at runtime —
+     * directory/package present with `index.js` or `index.ts` — but without
+     * importing the modules (boot-time speed; `ConfigurationManager.initialize()`
+     * runs before any managers). The directory-vs-npm-pattern split, npm glob
+     * matching, AND the canonical-identity resolution are all shared with
+     * `AddonsManager` via `utils/addonsPathResolver.ts` so the two can no
+     * longer drift out of sync (#924: they had, and packaged addons could
+     * never boot as a result).
+     *
+     * Catches the failure mode that caused the 2026-05-10 geohazardwatch.com
+     * outage: the deploy configmap had `ngdpbase.addons.ve-geology.enabled =
+     * true` but the on-disk addon was renamed to `geohazardwatch`, so
+     * `AddonsManager` silently treated the addon as disabled and registered
+     * none of its plugins/managers.
+     *
+     * #927: identity here is the canonical slug — `package.json`
+     * `ngdpbase.slug`, else the folder name minus a conventional trailing
+     * `-addon` (`resolvePackagedAddonSlug`). This is the EXACT same import-free
+     * resolution `AddonsManager.registerAddonFromDir()` uses as its registry
+     * key and `isEnabled` lookup, so this check is now precise rather than a
+     * guess: an enabled `<id>` is known iff the runtime would register under
+     * that same `<id>`. The only residual imprecision is a module whose
+     * exported `name` disagrees with its slug — but since #927 makes the slug
+     * (not `name`) the runtime identity too, that disagreement no longer
+     * affects either layer's `<id>`; it only earns a load-time warning.
+     */
+    private assertConfiguredAddonsExist;
+    /**
+     * Levenshtein-distance-based suggestion. Returns the closest candidate
+     * within edit distance 2, or null if no candidate is close enough.
+     * Used by `assertConfiguredAddonsExist` for did-you-mean error hints
+     * on typo-class misconfigs (rename-class misconfigs like
+     * "ve-geology" → "geohazardwatch" are too far apart and will return
+     * null, which is fine — the error message still lists every available
+     * addon so the operator can pick the right one).
+     */
+    private findClosestAddonName;
+    /**
+     * Reload configuration from disk
+     *
+     * @returns {Promise<void>}
+     */
+    reload(): Promise<void>;
+    /**
+     * Load and merge configurations from all sources
+     *
+     * Loads configurations in priority order and merges them into a single
+     * configuration object. Fields starting with '_' are treated as comments
+     * and excluded from the final configuration.
+     *
+     * Priority: default < custom (highest)
+     *
+     * @async
+     * @private
+     * @returns {Promise<void>}
+     * @throws {Error} If default configuration file cannot be loaded
+     */
+    private loadConfigurations;
+    /**
+     * #642: One-shot migration shim. If the custom config sets either of the
+     * legacy keys `ngdpbase.base-url` or `ngdpbase.baseURL`, copy the value
+     * into the canonical `ngdpbase.application.base-url` (unless that key is
+     * already set explicitly), then drop the legacy keys. Logs a deprecation
+     * warning so operators see they should update their custom config.
+     *
+     * Precedence when multiple legacy keys are present:
+     *   custom application.base-url  >  custom base-url  >  custom baseURL
+     */
+    private migrateLegacyBaseUrl;
+    /**
+     * #1117 slice 2: migration shim for the filter namespace. The old
+     * `ngdpbase.markup.filters.*` prefix described one consumer (markup
+     * rendering) of a capability that also gates saves —
+     * `…security.block-on-save` refuses content at the door, and an operator
+     * disabling "markup filters" to fix a rendering glitch would not expect to
+     * change what the system accepts. Keys now live under `ngdpbase.filters.*`.
+     *
+     * Every legacy key found in the CUSTOM config is copied to its new name
+     * (unless the new name is itself set explicitly — an explicit new key
+     * wins), then dropped, with one deprecation warning naming the count.
+     * Operating on customConfig before the merge means an operator's explicit
+     * legacy setting still overrides the shipped default under the new name —
+     * the case that must not silently break is a custom
+     * `…security.enabled=true` on an open-registration instance.
+     */
+    private migrateLegacyFilterNamespace;
+    /**
+     * Get a configuration property value
+     *
+     * Retrieves a property from the merged configuration with optional default value.
+     * Checks environment variables first for specific keys (Docker/Traefik support).
+     *
+     * Priority order:
+     * 1. Environment variables (for Docker/Traefik deployments)
+     * 2. Merged configuration (from config files)
+     * 3. Default value parameter
+     *
+     * @param {string} key - Configuration property key
+     * @param {*} [defaultValue=null] - Default value if property not found
+     * @returns {*} Configuration value or default
+     *
+     * @example
+     * const appName = configManager.getProperty('ngdpbase.application-name', 'MyWiki');
+     */
+    getProperty(key: string, defaultValue?: unknown): unknown;
+    /**
+     * #896: read a property from the SHIPPED defaults only, ignoring instance
+     * custom-config overrides. Used by vocabulary providers whose seed must not
+     * be shadowed by legacy whole-catalog snapshots in instance config (the
+     * #895 propagation bug). No env-override or env-ref resolution — defaults
+     * are repo-shipped literals.
+     */
+    getDefaultProperty(key: string, defaultValue?: unknown): unknown;
+    /**
+     * #1638: read a property as the build declares it — the shipped defaults
+     * with every ENABLED addon's default-config.json folded in — ignoring the
+     * operator's custom file. A registry check asks this when it must tell an
+     * entry the code can act on (shipped, or an enabled addon's) from one only
+     * the operator's file names. No env-override or env-ref resolution.
+     */
+    getDeclaredProperty(key: string, defaultValue?: unknown): unknown;
+    /**
+     * #1559: what was wrong with the system-categories add-ons declare — each
+     * entry refused, and each operator value an owner's declaration overrode —
+     * one line per problem, naming the entry and the field. #1860: the same for
+     * add-on database declarations.
+     */
+    getSystemCategoryProblems(): readonly string[];
+    /**
+     * #1559: why this add-on must not load — an entry its default-config.json
+     * declares under `ngdpbase.system-category` was refused, or its database
+     * declaration was (#1860) — or null. None of its other keys were merged.
+     */
+    getAddonRefusal(slug: string): string | null;
+    /**
+     * #1860: the database each installed add-on declares in its
+     * default-config.json (`ngdpbase.addons.<slug>.database`), whether or not it
+     * is turned on. A refused declaration is not here; its add-on is refused
+     * ({@link getAddonRefusal}). DatabaseManager is the reader.
+     */
+    getAddonDatabaseDeclarations(): readonly AddonDatabaseDeclaration[];
+    /**
+     * #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
+     * caller can tell what THIS addon said from what core or another addon said.
+     * Empty for an addon that ships no file, is disabled, or is unknown.
+     */
+    getAddonDeclaredDefaults(slug: string): Record<string, unknown>;
+    /**
+     * Resolve environment-variable references in a string config value.
+     *
+     * Two forms supported (#775):
+     *
+     * **`${VAR}` brace form** — embedded references, suitable for path templates
+     * like `"${FAST_STORAGE}/sessions"`. Silent on missing: leaves the
+     * unresolved placeholder intact (the value flows through to the caller,
+     * which typically fails later at point-of-use). Multiple embedded refs in
+     * one string work; partial-string refs work. **Use for paths and
+     * prefix-based templates.**
+     *
+     * **`$VAR` bare-whole-value form** — the ENTIRE config value is a single
+     * env-var reference. Strict on missing: throws with a clear message so
+     * the operator notices immediately at startup or first read. **Use for
+     * secrets** (API keys, SMTP passwords, etc.). Operators set these in
+     * `.env` alongside `FAST_STORAGE` / `SLOW_STORAGE` / `PORT`.
+     *
+     * **`$$literal` escape** — for the rare config value that genuinely
+     * starts with `$`. `"$$abc"` resolves to `"$abc"`.
+     *
+     * Non-string values pass through unchanged. Resolution happens at lookup
+     * time (per-`getProperty()` call), not at config load — so tests that
+     * mutate `process.env` mid-run see the new value on the next read.
+     *
+     * @param value - The raw config value (any type; only strings are processed)
+     * @param key   - The config key being looked up; included in error messages
+     *                so operators can find the offending entry.
+     * @returns The resolved value, or the input unchanged for non-strings /
+     *          non-refs.
+     * @throws  When the bare `$VAR` form references an unset env var.
+     */
+    private resolveEnvRef;
+    /** Audit counters for the boot-time env-ref summary log (#775). */
+    private _envRefHitCount;
+    private _envRefMissCount;
+    private _envRefBraceMissCount;
+    /**
+     * Get a config property with secrets masked to `"***"` for safe logging
+     * (#775). Returns the unmasked value for plain literals and brace-form
+     * resolved values; only the bare-form `$VAR` secrets return the mask.
+     *
+     * Use this on any log path that may print a config value. Boot banners,
+     * admin /config endpoint listings, debug-level config dumps.
+     *
+     * @param key          - Config key
+     * @param defaultValue - Default when key absent
+     * @returns The unmasked value, OR `"***"` if the raw config value was a
+     *          bare-form `$VAR` reference (indicating it carries a secret).
+     */
+    getMaskedProperty(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Set a configuration property (updates custom config)
+     *
+     * Sets a property value and persists it to the custom configuration file.
+     * This allows runtime configuration changes that survive restarts.
+     *
+     * @async
+     * @param {string} key - Configuration property key
+     * @param {*} value - Configuration value to set
+     * @param ctx - Who is changing it (#1179): the request's subject, or a
+     *   JobContext for a change no request drove. Mandatory and positional — a
+     *   config change is a security event and its record is read from this.
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await configManager.setProperty('ngdpbase.application-name', 'My Custom Wiki', wikiContext.userContext);
+     */
+    setProperty(key: string, value: unknown, ctx: ActorContext): Promise<void>;
+    /**
+     * Record a configuration change in the audit log (#1150).
+     *
+     * Emitted here rather than from the routes because this is the single write
+     * path — every deliberate change goes through it, and a producer that has to
+     * remember to call something is exactly what the #1120 registry exists to
+     * stop. The migration code inside this class writes `customConfig` directly
+     * and so is correctly not audited: it is not a decision anybody made.
+     *
+     * Deliberately AFTER the save rather than before. A change refused because
+     * its audit record could not be written would leave an operator unable to
+     * repair a broken audit configuration through the admin UI — a deadlock that
+     * costs more than the missing record. on-failure: continue for the same reason:
+     * the drop is counted and surfaced by recordAuditEvent, not fatal.
+     */
+    private recordConfigChange;
+    /**
+     * Apply a runtime-only config value (not persisted to custom config).
+     *
+     * Used by AddonsManager to inject domainDefaults without polluting
+     * the operator's app-custom-config.json. Because this only updates
+     * mergedConfig, the value disappears on next restart unless the addon
+     * is still loaded and re-injects it.
+     *
+     * @param key   Configuration property key
+     * @param value Value to apply
+     */
+    setRuntimeProperty(key: string, value: unknown): void;
+    /**
+     * Save custom configuration to file
+     *
+     * Persists the current custom configuration to disk with proper formatting.
+     *
+     * @async
+     * @private
+     * @returns {Promise<void>}
+     */
+    private saveCustomConfiguration;
+    /**
+     * Get all configuration properties
+     *
+     * Returns a copy of the entire merged configuration object.
+     *
+     * @returns {WikiConfig} All merged configuration properties
+     *
+     * @example
+     * const allConfig = configManager.getAllProperties();
+     * console.log(JSON.stringify(allConfig, null, 2));
+     */
+    /**
+     * The declared map of environment-owned config keys (#1089).
+     *
+     * Read straight from `mergedConfig` rather than through `getProperty`, which
+     * would recurse — `getProperty` calls this to decide whether the key it was
+     * asked for is env-owned.
+     */
+    private getEnvKeyMap;
+    /**
+     * Which keys the environment owns, and the variable that supplies each (#1089).
+     *
+     * Exposed so the admin configuration screen can render those keys read-only
+     * instead of accepting a write that cannot take effect.
+     */
+    getEnvControlledKeys(): EnvKeyMap;
+    /**
+     * Describe where a key's value actually comes from (#1089).
+     *
+     * The admin screen needs three separate facts that `getProperty` alone cannot
+     * express: the effective value, whether the environment owns the key, and
+     * which variable does. Without this it displayed `mergedConfig` — the raw JSON
+     * — while `getProperty` returned something else entirely, so the *read* side
+     * was wrong before anyone edited anything.
+     */
+    describeProperty(key: string): PropertyDescription;
+    getAllProperties(): WikiConfig;
+    /**
+     * Get a property value only if it was explicitly set in the custom config
+     * (i.e. not inherited from app-default-config.json).
+     * Returns null if the key is not present in the custom config.
+     *
+     * Use this when a theme or other subsystem should own a value by default and
+     * the config should only override it when the operator has explicitly said so.
+     *
+     * @param {string} key - Configuration key
+     * @returns {unknown} Custom config value, or null if not explicitly set
+     */
+    getCustomProperty(key: string): unknown;
+    /**
+     * Get application name
+     *
+     * @returns {string} Application name (defaults to 'ngdpbase')
+     *
+     * @example
+     * const name = configManager.getApplicationName(); // 'ngdpbase'
+     */
+    getApplicationName(): string;
+    /**
+     * Get base URL for the wiki
+     *
+     * @returns {string} Base URL (defaults to 'http://localhost:3000')
+     */
+    getBaseURL(): string;
+    /**
+     * Get front page name
+     *
+     * @returns {string} Front page name (defaults to 'Welcome')
+     */
+    getFrontPage(): string;
+    /**
+     * Get encoding
+     * @returns {string} Encoding
+     */
+    getEncoding(): string;
+    /**
+     * Get server port
+     * @returns {number} Server port
+     */
+    getServerPort(): number;
+    /**
+     * Get the set of recognised fenced code block language tags.
+     * Tags not in this set should be flagged as unknown on page save.
+     * @returns {Set<string>} Lower-cased tag names
+     */
+    getFencedCodeTags(): Set<string>;
+    /**
+     * Get server host
+     * @returns {string} Server host
+     */
+    getServerHost(): string;
+    /**
+     * Get session secret.
+     *
+     * #1194: no literal fallback. `ngdpbase.session.secret` is env-owned and
+     * `src/bootstrap-env.ts` guarantees `NGDPBASE_SESSION_SECRET` is set (or
+     * exits) before this class loads, so the env-keys path in getProperty()
+     * always answers. The shipped config value is a public string and must
+     * never be what this returns; an empty string is the honest answer if the
+     * guarantee is somehow broken. `app.ts` does not call this — it reads
+     * `resolveSessionSecret(process.env)` directly — and nothing else does.
+     *
+     * @returns {string} Session secret
+     */
+    getSessionSecret(): string;
+    /**
+     * Get session max age in milliseconds
+     * @returns {number} Session max age
+     */
+    getSessionMaxAge(): number;
+    /**
+     * Get session secure flag.
+     *
+     * #1043: these two compared against the STRING `'true'` while the config
+     * values are real booleans, so `getSessionSecure()` returned false even when
+     * the key was set to `true`. Nothing called either one — the session cookie
+     * is configured in `app.ts`, which reads the keys directly — so the bug was
+     * invisible until someone tried to use the accessor the config key advertises.
+     *
+     * Kept (public API, an embedder may call them) and made boolean-aware, so the
+     * next caller gets the answer the config actually holds.
+     *
+     * @returns {boolean} Session secure flag
+     */
+    getSessionSecure(): boolean;
+    /**
+     * Get session httpOnly flag. Defaults to true — the safe direction.
+     * @returns {boolean} Session httpOnly flag
+     */
+    getSessionHttpOnly(): boolean;
+    /**
+     * Get directory paths
+     * @returns {Object} Directory configuration
+     */
+    getDirectories(): {
+        pages: unknown;
+        templates: unknown;
+        resources: unknown;
+        data: unknown;
+        work: unknown;
+    };
+    /**
+     * Get the instance data folder path
+     *
+     * Returns the base folder for all instance-specific data (pages, users,
+     * attachments, logs, etc.). This can be configured via the INSTANCE_DATA_FOLDER
+     * environment variable, allowing instance data to be stored anywhere on the
+     * filesystem.
+     *
+     * @returns {string} Absolute path to the instance data folder
+     *
+     * @example
+     * const dataFolder = configManager.getInstanceDataFolder();
+     * // Returns '/var/lib/ngdpbase/data' if INSTANCE_DATA_FOLDER=/var/lib/ngdpbase/data
+     * // Returns resolved './data' path if not set
+     */
+    getInstanceDataFolder(): string;
+    /** This site's install marker (see {@link installCompletePath}). */
+    getInstallCompletePath(): string;
+    /** This site's custom config file: `<instance data folder>/config/<INSTANCE_CONFIG_FILE or app-custom-config.json>`. */
+    getCustomConfigPath(): string;
+    /**
+     * Resolve a data path relative to the instance data folder
+     *
+     * Takes a path that may contain './data/' prefix and resolves it relative
+     * to the configured INSTANCE_DATA_FOLDER. This allows all data paths in
+     * configuration to work correctly regardless of where instance data is stored.
+     *
+     * @param {string} relativePath - Path to resolve (may include './data/' prefix)
+     * @returns {string} Absolute resolved path under instance data folder
+     *
+     * @example
+     * // With INSTANCE_DATA_FOLDER=/var/lib/ngdpbase/data
+     * configManager.resolveDataPath('./data/pages');     // '/var/lib/ngdpbase/data/pages'
+     * configManager.resolveDataPath('data/users');       // '/var/lib/ngdpbase/data/users'
+     * configManager.resolveDataPath('./data/logs/audit.log'); // '/var/lib/ngdpbase/data/logs/audit.log'
+     * configManager.resolveDataPath('pages');            // '/var/lib/ngdpbase/data/pages'
+     */
+    resolveDataPath(relativePath: string): string;
+    /**
+     * Get a resolved configuration property for data paths
+     *
+     * Convenience method that gets a configuration property and resolves it
+     * if it appears to be a data path (starts with './data' or 'data/').
+     *
+     * @param {string} key - Configuration property key
+     * @param {string} defaultValue - Default value if property not found
+     * @returns {string} Resolved path or original value
+     *
+     * @example
+     * const pagesDir = configManager.getResolvedDataPath(
+     *   'ngdpbase.page.provider.filesystem.storagedir',
+     *   './data/pages'
+     * );
+     */
+    getResolvedDataPath(key: string, defaultValue: string): string;
+    /**
+     * Get manager-specific configuration
+     *
+     * Retrieves all configuration properties for a specific manager,
+     * including enabled status and manager-specific settings.
+     *
+     * @param {string} managerName - Name of the manager
+     * @returns {Object} Manager configuration object with enabled flag and settings
+     * @returns {boolean} config.enabled - Whether the manager is enabled
+     *
+     * @example
+     * const searchConfig = configManager.getManagerConfig('SearchManager');
+     * if (searchConfig.enabled) {
+     *   // Use search manager
+     * }
+     */
+    getManagerConfig(managerName: string): {
+        enabled: boolean;
+        [key: string]: unknown;
+    };
+    /**
+     * Get feature configuration
+     * @param {string} featureName - Name of feature
+     * @returns {Object} Feature configuration
+     */
+    getFeatureConfig(featureName: string): {
+        enabled: boolean;
+        [key: string]: unknown;
+    };
+    /**
+     * Get logging configuration
+     * @returns {Object} Logging configuration
+     */
+    getLoggingConfig(): {
+        level: unknown;
+        dir: unknown;
+        maxSize: unknown;
+        maxFiles: number;
+    };
+    /**
+     * Get search configuration
+     * @returns {Object} Search configuration
+     */
+    getSearchConfig(): {
+        indexDir: unknown;
+        enabled: boolean;
+    };
+    /**
+     * Get access control configuration
+     * @returns {Object} Access control configuration
+     */
+    getAccessControlConfig(): {
+        contextAware: {
+            enabled: boolean;
+            timeZone: unknown;
+        };
+        businessHours: {
+            enabled: boolean;
+            start: unknown;
+            end: unknown;
+            days: unknown;
+        };
+    };
+    /**
+     * Get audit configuration
+     * @returns {Object} Audit configuration
+     */
+    getAuditConfig(): {
+        enabled: boolean;
+        logDirectory: unknown;
+        logFile: unknown;
+        retention: {
+            maxFiles: number;
+            maxAge: unknown;
+        };
+        includeContext: {
+            ip: boolean;
+            userAgent: boolean;
+            timestamp: boolean;
+            decision: boolean;
+            reason: boolean;
+        };
+    };
+    /**
+     * Get RSS settings
+     * @returns {Object} RSS configuration
+     */
+    getRSSConfig(): {
+        generate: unknown;
+        fileName: unknown;
+        interval: unknown;
+        channelTitle: unknown;
+        channelDescription: unknown;
+    };
+    /**
+     * Reset configuration to defaults (admin only)
+     *
+     * Clears all custom configuration and resets to default values.
+     * This operation persists the empty custom configuration to disk.
+     *
+     * @async
+     * @returns {Promise<void>}
+     *
+     * @example
+     * await configManager.resetToDefaults();
+     * console.log('Configuration reset to defaults');
+     */
+    resetToDefaults(ctx: ActorContext): Promise<void>;
+    /**
+     * Get custom configuration for admin UI
+     *
+     * Returns only the custom overrides, useful for displaying
+     * which settings have been customized.
+     *
+     * @returns {Object} Custom configuration properties only
+     *
+     * @example
+     * const customSettings = configManager.getCustomProperties();
+     * console.log('Customized settings:', Object.keys(customSettings));
+     */
+    getCustomProperties(): Partial<WikiConfig>;
+    /**
+     * Get default configuration for comparison
+     *
+     * Returns the base default configuration, useful for comparison
+     * with current settings or resetting individual properties.
+     *
+     * @returns {WikiConfig} Default configuration properties
+     */
+    getDefaultProperties(): WikiConfig;
+    /**
+     * Backup configuration data
+     *
+     * Backs up the custom configuration (user overrides) which can be restored
+     * to recreate the user's configuration settings. We don't backup default or
+     * environment configs as those are part of the codebase.
+     *
+     * @returns {Promise<BackupData>} Backup data containing custom configuration
+     */
+    backup(): Promise<ConfigManagerBackupData>;
+    /**
+     * Restore configuration from backup data
+     *
+     * Restores the custom configuration (user overrides) from backup data.
+     * This will overwrite the current custom configuration file and reload
+     * all configurations to rebuild the merged config.
+     *
+     * @param {BackupData} backupData - Backup data from backup() method
+     * @returns {Promise<void>}
+     */
+    restore(backupData: ConfigManagerBackupData): Promise<void>;
+}
+export default ConfigurationManager;