@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

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

@@ -282,7 +282,21 @@ export interface ManagerStatus {
     configKey?: string;
     /** Whether the feature is down or works but needs an admin (#1946). Present when degraded or failed. */
     kind?: DegradedKind;
+    /** Where the fix is, when it is not the setting `configKey` names (a record the app writes, not a value to edit). */
+    fixUrl?: string;
+    /** What the link to `fixUrl` says, e.g. "Open Admin → Backup". */
+    fixLabel?: string;
+    /** One line per problem, drawn as a list under `reason` (#2348). `reason` stays the headline and the audit text. */
+    details?: string[];
+    /** Buttons under the item (#2355): each posts a form to `action` with `fields`; the page adds the CSRF token. Labels and values are text. */
+    buttons?: Array<{
+        label: string;
+        action: string;
+        fields: Record<string, string>;
+    }>;
 }
+/** What a caller may add to a needs-attention status (#2348). */
+export type AttentionOptions = Pick<ManagerStatus, 'fixUrl' | 'fixLabel' | 'details' | 'buttons'>;
 declare abstract class BaseManager {
     /** Reference to the wiki engine */
     protected engine: WikiEngine;
@@ -425,18 +439,18 @@ declare abstract class BaseManager {
      *   starts degraded and stays degraded must not re-emit on every boot, or
      *   the signal is buried in its own noise.
      */
-    protected markDegraded(reason: string, configKey?: string): boolean;
+    protected markDegraded(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /**
      * Record that this manager works, but an administrator has something to do
      * (#1946). Still `degraded` — it stays on the dashboard, is audited, and
      * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
      * as down.
      */
-    protected markNeedsAttention(reason: string, configKey?: string): boolean;
+    protected markNeedsAttention(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     protected markDisabled(reason: string): boolean;
     /** Record that this manager could not initialise at all (#1155). */
-    protected markFailed(reason: string, configKey?: string): boolean;
+    protected markFailed(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /**
      * Record that this manager is working.
      *

package/lib/src/managers/BaseManager.js

@@ -18,6 +18,7 @@ import logger from '../utils/logger.js';
 import { checkConfiguredPath } from '../utils/PathPreflight.js';
 import { recordAuditEvent } from '../utils/auditEvents.js';
 import { AUDIT_EVENT } from '../utils/auditEventNames.js';
+import { STAGED_RESTORE_FIX, stagedRestoreNotApplied, UNUSABLE_FOLDER_REASON } from '../utils/plainAttention.js';
 class BaseManager {
     /** Reference to the wiki engine */
     engine;
@@ -121,7 +122,9 @@ class BaseManager {
         const { applyStagedPartsAtStart } = await import('./BackupManager.js');
         this.stagedRestore = applyStagedPartsAtStart(this.engine, this.registeredName(), declared);
         if (this.stagedRestore?.refused) {
-            this.markNeedsAttention(`A staged restore of ${declared.map((d) => d.part).join(', ')} was not applied: ${this.stagedRestore.refused}`);
+            // #2354: the dashboard says it in plain words; the parts and the cause stay in the log.
+            logger.warn(`[${this.constructor.name}] A staged restore of ${declared.map((d) => d.part).join(', ')} was not applied: ${this.stagedRestore.refused}`);
+            this.markNeedsAttention(stagedRestoreNotApplied('some of the site\'s data'), undefined, STAGED_RESTORE_FIX);
         }
     }
     /**
@@ -193,7 +196,8 @@ class BaseManager {
             // degrading manager already goes through, so setting the state here is
             // what makes twelve invisible degradations visible without each caller
             // remembering to say so.
-            this.markDegraded(result.message ?? 'the configured path could not be used', configKey);
+            // #2354: the dashboard says it in plain words; the path and key are in the line above.
+            this.markDegraded(UNUSABLE_FOLDER_REASON, configKey);
         }
         return result;
     }
@@ -216,8 +220,8 @@ class BaseManager {
      *   starts degraded and stays degraded must not re-emit on every boot, or
      *   the signal is buried in its own noise.
      */
-    markDegraded(reason, configKey) {
-        return this.transition({ state: 'degraded', reason, configKey, kind: 'outage' });
+    markDegraded(reason, configKey, opts = {}) {
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'outage', ...opts });
     }
     /**
      * Record that this manager works, but an administrator has something to do
@@ -225,16 +229,16 @@ class BaseManager {
      * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
      * as down.
      */
-    markNeedsAttention(reason, configKey) {
-        return this.transition({ state: 'degraded', reason, configKey, kind: 'attention' });
+    markNeedsAttention(reason, configKey, opts = {}) {
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'attention', ...opts });
     }
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     markDisabled(reason) {
         return this.transition({ state: 'disabled', reason });
     }
     /** Record that this manager could not initialise at all (#1155). */
-    markFailed(reason, configKey) {
-        return this.transition({ state: 'failed', reason, configKey, kind: 'outage' });
+    markFailed(reason, configKey, opts = {}) {
+        return this.transition({ state: 'failed', reason, configKey, kind: 'outage', ...opts });
     }
     /**
      * Record that this manager is working.

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

@@ -54,6 +54,8 @@ declare class ConfigurationManager extends BaseManager {
     private defaultConfig;
     private customConfig;
     private mergedConfig;
+    /** #2279: counts every change to `mergedConfig`, so a reader may keep what it derived from a value until the next one. */
+    private revision;
     /** #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. */
@@ -200,8 +202,19 @@ declare class ConfigurationManager extends BaseManager {
      * @throws {Error} If default configuration file cannot be loaded
      */
     private loadConfigurations;
+    /**
+     * A number that changes whenever the configuration in force changes (#2279):
+     * a load or reload, a save, a reset, a restore, a runtime value an add-on
+     * sets. Equal numbers mean nothing was changed through this manager, so
+     * what a reader derived from `getProperty` then still holds. A value
+     * returned by `getProperty` must not be changed in place; that is the one
+     * change this cannot see.
+     */
+    getRevision(): number;
     /** What the #2255 page-write migration rewrote in memory, one sentence each; PolicyDecisionPoint reports it. */
     pageWritePolicyMigration: string[];
+    /** Each `pageWritePolicyMigration` line in plain words, for the needs-attention entry. */
+    pageWritePolicyMigrationShown: Record<string, string>;
     /**
      * #2255: before the merge, rewrite the custom layer's stored copies of the
      * shipped role policies whose page writes moved to the category policies

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

@@ -56,7 +56,7 @@ declare class ConsentManager extends BaseManager {
     private readonly addons;
     /** Username → their records, read once and dropped on every write. */
     private readonly cache;
-    /** Document id → why it cannot be asked for; the needs-attention reason is made from these. */
+    /** Document id → why it cannot be asked for (the needs-attention reason is made from these), and whether it comes with an add-on (core's Required Pages Sync does not restore those). */
     private readonly problems;
     private attentionReason;
     constructor(engine: WikiEngine);

package/lib/src/managers/DatabaseManager.js

@@ -50,6 +50,7 @@ import { applyStagedRestore, manifestPath, runOffThread, setAsideStagedRestore,
 import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, LEFT_OUT_FOR_NO_KEY } from '../utils/backupKey.js';
 // The environment variable holding the SQLCipher key: one declaration, `src/utils/databaseKey.ts`.
 import { DATABASE_KEY_ENV } from '../utils/databaseKey.js';
+import { STAGED_RESTORE_FIX } from '../utils/plainAttention.js';
 export { DATABASE_KEY_ENV };
 // #1723, #1876: the backup key has one declaration (`src/utils/backupKey.ts`); re-exported for the callers that import it from here.
 export { BACKUP_KEY_ENV, backupKeyFingerprint } from '../utils/backupKey.js';
@@ -138,7 +139,7 @@ class DatabaseManager extends BaseManager {
         catch (err) {
             this.markUnavailable(`A staged database restore could not be put in place: ${err.message}. ` +
                 'No database was opened. Some databases may already be restored: each one moved is kept beside it as *.pre-restore, and the rest are still *.staged beside ' +
-                `${path.basename(manifestPath(file))}. Stop the server, put the files back as they should be, and restart (#1892)`);
+                `${path.basename(manifestPath(file))}. Stop the server, put the files back as they should be, and restart (#1892)`, 'A saved copy of the databases was being put back and it did not finish, so the site is in maintenance mode and no database is open. Some may already have been replaced. Ask whoever runs the server to check the database files and restart the site; this is done on the server, outside this page.');
             return;
         }
         // #1892: a database that cannot be opened safely (no key or the wrong key
@@ -151,7 +152,7 @@ class DatabaseManager extends BaseManager {
             provider = new SqliteDatabaseProvider(file, key, DATABASE_MIGRATIONS, 'schema_migrations', { busyTimeoutMs: this.busyTimeoutMs });
         }
         catch (err) {
-            this.markUnavailable(DatabaseManager.openFailure(file, err.message, key));
+            this.markUnavailable(DatabaseManager.openFailure(file, err.message, key), 'The database could not be opened safely, so the site is in maintenance mode. If its key is missing or wrong, fix it in the server\'s settings (outside this page) and restart the site. If the file is damaged, restore the databases from a backup.', STAGED_RESTORE_FIX);
             return;
         }
         this.provider = provider;
@@ -195,11 +196,12 @@ class DatabaseManager extends BaseManager {
      * administrators can sign in and reach /admin, and `reportAtBoot()` sends
      * them the reason as a critical notification once notifications exist.
      */
-    markUnavailable(reason) {
+    markUnavailable(reason, plain, fix) {
         this.unavailable = reason;
         this.provider = null;
         logger.error(`[DatabaseManager] ${reason}`);
-        this.markFailed(reason, 'ngdpbase.database.file');
+        // #2354: the dashboard says it in plain words; the developer text is the log line above.
+        this.markFailed(plain, 'ngdpbase.database.file', fix);
         // #1906: no message of its own, so visitors see the site's maintenance message.
         this.engine.maintenance.enter(reason);
     }
@@ -690,7 +692,13 @@ class DatabaseManager extends BaseManager {
     }
     /** Degrade for one cause; the dashboard shows every cause still standing. */
     fault(cause, reason, kind) {
-        this.faults.set(cause, { reason, kind });
+        // #2354: the dashboard shows the plain words; `reason` is the developer text, already logged by the caller.
+        const plain = cause === 'restore'
+            ? 'A saved copy of the databases was not put back when the site started, so the databases that were there before are still in use. Open the Backup page to see what to do next.'
+            : this.backupKey()
+                ? "The backup key is the same as the database key, so one stolen secret would open both. Give the backups a key of their own, in the server's settings, outside this page."
+                : "Databases are not being backed up, because the backup key is not set. This is set in the server's settings, outside this page.";
+        this.faults.set(cause, { reason, plain, kind });
         this.markFaults();
     }
     clearFault(cause) {
@@ -704,11 +712,12 @@ class DatabaseManager extends BaseManager {
     /** Every cause still standing; down when any one of them is (#1946). */
     markFaults() {
         const faults = [...this.faults.values()];
-        const reason = faults.map((f) => f.reason).join('; ');
+        const reason = faults.map((f) => f.plain).join(' ');
+        const fix = this.faults.has('restore') ? STAGED_RESTORE_FIX : {};
         if (faults.some((f) => f.kind === 'outage'))
-            this.markDegraded(reason);
+            this.markDegraded(reason, undefined, fix);
         else
-            this.markNeedsAttention(reason);
+            this.markNeedsAttention(reason, undefined, fix);
     }
     async notify(level, title, message) {
         try {

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

@@ -35,7 +35,7 @@ import type { MailAttachment, MailMessage, MailProvider } from '../mail/MailProv
 import type { ActorContext } from '../context/ActorContext.js';
 export type { MailAttachment } from '../mail/MailProvider.js';
 /** The degraded reason while sends fail; cleared by the next success. */
-export declare const SEND_FAILING_REASON = "outbound email is failing \u2014 see the server log and the administrator notification";
+export declare const SEND_FAILING_REASON = "The site can't send email right now. Check the email settings.";
 /** Title of the administrator notice. */
 export declare const SEND_FAILING_TITLE = "Email could not be sent";
 /** An attachment the message cannot carry (#1974): refused before sending, so it is not a delivery failure. */

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

@@ -10,17 +10,7 @@ export type { PdfOptions, PdfMargin, PdfPageSize } from '../export/pdfEngine.js'
  * when something asked for a PDF and could not have one; cleared by the next
  * render that works.
  */
-export declare const PDF_UNAVAILABLE_REASON = "PDF export unavailable: choose a PDF provider (local-chrome or chrome-service) in ngdpbase.export.pdf.provider, or fix the one chosen (the server log says why)";
-/**
- * Export file metadata interface
- */
-export interface ExportFileInfo {
-    filename: string;
-    path: string;
-    size: number;
-    created: Date;
-    modified: Date;
-}
+export declare const PDF_UNAVAILABLE_REASON = "PDFs can't be made right now. Choose how PDFs are made in the settings, or fix the one already chosen.";
 /**
  * Export configuration interface
  */
@@ -146,13 +136,6 @@ declare class ExportManager extends BaseManager {
      * @returns {Promise<void>}
      */
     initialize(config?: ExportConfig): Promise<void>;
-    /**
-     * Export a single page to HTML
-     * @param {string} pageName - Page name to export
-     * @param {ExportUser|null} user - User object for locale-aware formatting
-     * @returns {Promise<string>} HTML content
-     */
-    exportPageToHtml(pageName: string, ctx: ActorContext, user?: ExportUser | null): Promise<string>;
     /**
      * One page as a complete HTML document: its content rendered, with the
      * export's styling and metadata footer. It reads nothing: the caller has
@@ -171,32 +154,6 @@ declare class ExportManager extends BaseManager {
      * @returns {Promise<string>} Combined HTML content
      */
     exportPagesToHtml(pageNames: string[], ctx: ActorContext, user?: ExportUser | null): Promise<string>;
-    /**
-     * Export page(s) to markdown
-     * @param {string|string[]} pageNames - Single page name or array of page names
-     * @param {ExportUser|null} user - User object for locale-aware formatting
-     * @returns {Promise<string>} Markdown content
-     */
-    exportToMarkdown(pageNames: string | string[], ctx: ActorContext, user?: ExportUser | null): Promise<string>;
-    /**
-     * Save export to file
-     * @param {string} content - Content to save
-     * @param {string} filename - Filename
-     * @param {string} format - File format
-     * @returns {Promise<string>} File path
-     */
-    saveExport(content: string, filename: string, format: string): Promise<string>;
-    /**
-     * Get list of available exports
-     * @returns {Promise<ExportFileInfo[]>} List of export files
-     */
-    getExports(): Promise<ExportFileInfo[]>;
-    /**
-     * Delete an export file
-     * @param {string} filename - Export filename
-     * @returns {Promise<void>}
-     */
-    deleteExport(filename: string): Promise<void>;
     /**
      * Get formatted timestamp using user's locale
      * @param {ExportUser|null} user - User object (optional)

package/lib/src/managers/ExportManager.js

@@ -1,6 +1,5 @@
 import BaseManager from './BaseManager.js';
 import fs from 'fs/promises';
-import path from 'path';
 import LocaleUtils from '../utils/LocaleUtils.js';
 import logger from '../utils/logger.js';
 import { actorOf } from '../context/ActorContext.js';
@@ -15,7 +14,7 @@ export { PdfUnavailableError };
  * when something asked for a PDF and could not have one; cleared by the next
  * render that works.
  */
-export const PDF_UNAVAILABLE_REASON = 'PDF export unavailable: choose a PDF provider (local-chrome or chrome-service) in ngdpbase.export.pdf.provider, or fix the one chosen (the server log says why)';
+export const PDF_UNAVAILABLE_REASON = "PDFs can't be made right now. Choose how PDFs are made in the settings, or fix the one already chosen.";
 /** Shipped defaults of the `ngdpbase.export.pdf.*` keys. */
 const PDF_DEFAULTS = { provider: 'none', pageSize: 'Letter', timeoutMs: 30_000, maxConcurrent: 2, serviceMaxBytes: 52_428_800 };
 /**
@@ -34,7 +33,7 @@ const PDF_DEFAULTS = { provider: 'none', pageSize: 'Letter', timeoutMs: 30_000,
  *
  * @example
  * const exportManager = engine.getManager('ExportManager');
- * const html = await exportManager.exportPageToHtml('Main');
+ * const csv = exportManager.toCsv(['name'], [['Main']]);
  */
 /** A text cell starting with one of these runs as a spreadsheet formula. */
 const CSV_FORMULA_START = /^[=+\-@\t\r]/;
@@ -229,7 +228,7 @@ class ExportManager extends BaseManager {
         this.exportDirectory = config.exportDirectory
             || this.engine.getManager('ConfigurationManager')?.getResolvedDataPath('ngdpbase.directories.exports', '${FAST_STORAGE}/exports')
             || './exports';
-        const preflight = this.preflightConfiguredPath('exportDirectory', this.exportDirectory);
+        const preflight = this.preflightConfiguredPath('ngdpbase.directories.exports', this.exportDirectory);
         if (!preflight.ok) {
             this.exportDirectory = '';
             logger.info('ExportManager initialized (degraded — exports disabled)');
@@ -240,24 +239,6 @@ class ExportManager extends BaseManager {
         const pdfProviderName = this.engine.getManager('ConfigurationManager')?.getProperty('ngdpbase.export.pdf.provider', PDF_DEFAULTS.provider);
         logger.info(`ExportManager initialized (PDF provider: ${pdfProviderName ?? PDF_DEFAULTS.provider})`);
     }
-    /**
-     * Export a single page to HTML
-     * @param {string} pageName - Page name to export
-     * @param {ExportUser|null} user - User object for locale-aware formatting
-     * @returns {Promise<string>} HTML content
-     */
-    async exportPageToHtml(pageName, ctx, user = null) {
-        const pageManager = this.engine.getManager('PageManager');
-        const renderingManager = this.engine.getManager('RenderingManager');
-        if (!pageManager || !renderingManager) {
-            throw new Error('Required managers not available');
-        }
-        const page = (await pageManager.getPage(pageName, ctx));
-        if (!page) {
-            throw new Error(`Page '${pageName}' not found`);
-        }
-        return this.renderPageDocument(pageName, page, user);
-    }
     /**
      * One page as a complete HTML document: its content rendered, with the
      * export's styling and metadata footer. It reads nothing: the caller has
@@ -480,99 +461,6 @@ class ExportManager extends BaseManager {
 </html>`;
         return html;
     }
-    /**
-     * Export page(s) to markdown
-     * @param {string|string[]} pageNames - Single page name or array of page names
-     * @param {ExportUser|null} user - User object for locale-aware formatting
-     * @returns {Promise<string>} Markdown content
-     */
-    async exportToMarkdown(pageNames, ctx, user = null) {
-        const pageManager = this.engine.getManager('PageManager');
-        if (!pageManager) {
-            throw new Error('PageManager not available');
-        }
-        const names = Array.isArray(pageNames) ? pageNames : [pageNames];
-        let markdown = '';
-        if (names.length > 1) {
-            markdown += '# ngdpbase Export\n\n';
-            markdown += `*Exported on ${this.getFormattedTimestamp(user)}*\n\n`;
-            markdown += '## Table of Contents\n\n';
-            for (const pageName of names) {
-                markdown += `- [${pageName}](#${pageName.toLowerCase().replace(/[^a-z0-9]/g, '-')})\n`;
-            }
-            markdown += '\n---\n\n';
-        }
-        for (const pageName of names) {
-            const page = (await pageManager.getPage(pageName, ctx));
-            if (page) {
-                if (names.length > 1) {
-                    markdown += `# ${pageName}\n\n`;
-                }
-                markdown += page.content;
-                if (names.length > 1) {
-                    markdown += '\n\n---\n\n';
-                }
-            }
-        }
-        return markdown;
-    }
-    /**
-     * Save export to file
-     * @param {string} content - Content to save
-     * @param {string} filename - Filename
-     * @param {string} format - File format
-     * @returns {Promise<string>} File path
-     */
-    async saveExport(content, filename, format) {
-        const sanitizedFilename = filename.replace(/[^a-zA-Z0-9\-_]/g, '-');
-        const timestamp = new Date().toISOString().slice(0, 10);
-        const fullFilename = `${sanitizedFilename}_${timestamp}.${format}`;
-        const filePath = path.join(this.exportDirectory, fullFilename);
-        await fs.writeFile(filePath, content, 'utf8');
-        logger.info(`Exported to: ${fullFilename}`);
-        return filePath;
-    }
-    /**
-     * Get list of available exports
-     * @returns {Promise<ExportFileInfo[]>} List of export files
-     */
-    async getExports() {
-        try {
-            const files = await fs.readdir(this.exportDirectory);
-            const exports = [];
-            for (const file of files) {
-                const filePath = path.join(this.exportDirectory, file);
-                const stats = await fs.stat(filePath);
-                exports.push({
-                    filename: file,
-                    path: filePath,
-                    size: stats.size,
-                    created: stats.birthtime,
-                    modified: stats.mtime
-                });
-            }
-            return exports.sort((a, b) => b.created.getTime() - a.created.getTime());
-        }
-        catch (err) {
-            logger.error('Error getting exports:', err);
-            return [];
-        }
-    }
-    /**
-     * Delete an export file
-     * @param {string} filename - Export filename
-     * @returns {Promise<void>}
-     */
-    async deleteExport(filename) {
-        // Only a plain file name inside the export folder: never a path that
-        // reaches another folder.
-        if (!filename || filename !== path.basename(filename) || filename === '.' || filename === '..') {
-            throw new Error(`Not an export file name: ${filename}`);
-        }
-        const filePath = path.join(this.exportDirectory, filename);
-        await fs.unlink(filePath);
-        logger.info(`Deleted export: ${filename}`);
-    }
     /**
      * Get formatted timestamp using user's locale
      * @param {ExportUser|null} user - User object (optional)

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

@@ -633,6 +633,13 @@ declare class ImportManager extends BaseManager {
      * is permitted, and a refusal to someone who holds it is step-up's.
      */
     private mayExportPage;
+    /**
+     * `core.search` as an export source: a search's pages and files as one zip
+     * ({@link searchExportSource}). Like a page, a search is offered to a user
+     * who holds `page-export`, and read as the user who asked, each page and
+     * file by its own read check. Recorded as one `page-export` of the search.
+     */
+    private searchExportSource;
     /**
      * `core.pages` as an export source (#2120, D5: pages export checks
      * `page-export`). A page is offered for export when its reader may see it

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

@@ -1226,6 +1226,15 @@ declare class PageManager extends BaseManager implements CatalogSource {
         title: string;
         uuid: string;
     }>>;
+    /**
+     * Every public page stamped with one system-category (#2299), by the name
+     * `mayShowPage` takes. Vault pages are not listed: they are their owners', not
+     * an administrator's to be told about. Says nothing about who may see a page;
+     * the caller asks `mayShowPage` as the reader.
+     *
+     * @param category - The category's key or label, any case
+     */
+    listCategoryPages(category: string): Promise<string[]>;
     /** The store ids the requester has of their own (#1387). */
     listOwnStoreIds(ctx: ActorContext): Promise<string[]>;
     /**