@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,129 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Export file metadata interface
+ */
+export interface ExportFileInfo {
+    filename: string;
+    path: string;
+    size: number;
+    created: Date;
+    modified: Date;
+}
+/**
+ * Export configuration interface
+ */
+export interface ExportConfig extends Record<string, unknown> {
+    exportDirectory?: string;
+}
+/**
+ * User preferences interface (for locale support)
+ */
+export interface UserPreferences {
+    locale?: string;
+}
+/**
+ * User object interface (for locale-aware formatting)
+ */
+export interface ExportUser {
+    preferences?: UserPreferences;
+}
+/**
+ * Page object interface (minimal fields needed for export)
+ */
+export interface PageForExport {
+    content: string;
+    lastModified?: string;
+    'system-category'?: string;
+    'user-keywords'?: string[];
+    name?: string;
+}
+declare class ExportManager extends BaseManager {
+    private exportDirectory;
+    /**
+     * Creates a new ExportManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * One field of the one CSV writer for every export (RFC 4180): quoted when
+     * it holds a comma, quote or line break.
+     *
+     * A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return is
+     * run as a formula by Excel, LibreOffice and Google Sheets ("CSV injection",
+     * OWASP), so a text cell starting with one gets a leading `'`. Numbers are
+     * written as numbers: a negative amount stays `-12550`.
+     *
+     * @param value - The cell value
+     * @returns The field, ready to join with commas
+     */
+    csvCell(value: unknown): string;
+    /**
+     * A header row and data rows as one CSV document, each line ending CRLF.
+     * Every CSV export (the audit log, add-ons) goes through here.
+     *
+     * @param headers - The header row
+     * @param rows - The data rows
+     * @returns The CSV document
+     */
+    toCsv(headers: readonly string[], rows: readonly (readonly unknown[])[]): string;
+    /**
+     * Initialize the ExportManager
+     *
+     * @async
+     * @param {ExportConfig} [config={}] - Configuration object
+     * @param {string} [config.exportDirectory] - Export directory path
+     * @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>;
+    /**
+     * Export multiple pages to a single HTML file
+     * @param {string[]} pageNames - Array of page names
+     * @param {ExportUser|null} user - User object for locale-aware formatting
+     * @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)
+     * @returns {string} Formatted timestamp
+     */
+    getFormattedTimestamp(user?: ExportUser | null): string;
+}
+export default ExportManager;

package/lib/src/managers/ExportManager.js

@@ -0,0 +1,420 @@
+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';
+/**
+ * ExportManager - Handles page exports to multiple formats
+ *
+ * Similar to JSPWiki's export functionality, provides page export capabilities
+ * to HTML, PDF, markdown, and other formats.
+ *
+ * @class ExportManager
+ * @extends BaseManager
+ *
+ * @property {string} exportDirectory - Directory for exported files
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const exportManager = engine.getManager('ExportManager');
+ * const html = await exportManager.exportPageToHtml('Main');
+ */
+/** A text cell starting with one of these runs as a spreadsheet formula. */
+const CSV_FORMULA_START = /^[=+\-@\t\r]/;
+class ExportManager extends BaseManager {
+    exportDirectory;
+    /**
+     * Creates a new ExportManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine) {
+        super(engine);
+        this.exportDirectory = './exports';
+    }
+    /**
+     * One field of the one CSV writer for every export (RFC 4180): quoted when
+     * it holds a comma, quote or line break.
+     *
+     * A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return is
+     * run as a formula by Excel, LibreOffice and Google Sheets ("CSV injection",
+     * OWASP), so a text cell starting with one gets a leading `'`. Numbers are
+     * written as numbers: a negative amount stays `-12550`.
+     *
+     * @param value - The cell value
+     * @returns The field, ready to join with commas
+     */
+    csvCell(value) {
+        if (value === null || value === undefined)
+            return '';
+        if (typeof value === 'number' || typeof value === 'bigint' || typeof value === 'boolean')
+            return String(value);
+        let text = typeof value === 'string' ? value : JSON.stringify(value);
+        if (CSV_FORMULA_START.test(text))
+            text = `'${text}`;
+        return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+    }
+    /**
+     * A header row and data rows as one CSV document, each line ending CRLF.
+     * Every CSV export (the audit log, add-ons) goes through here.
+     *
+     * @param headers - The header row
+     * @param rows - The data rows
+     * @returns The CSV document
+     */
+    toCsv(headers, rows) {
+        return [headers, ...rows].map((row) => row.map((cell) => this.csvCell(cell)).join(',')).join('\r\n') + '\r\n';
+    }
+    /**
+     * Initialize the ExportManager
+     *
+     * @async
+     * @param {ExportConfig} [config={}] - Configuration object
+     * @param {string} [config.exportDirectory] - Export directory path
+     * @returns {Promise<void>}
+     */
+    async initialize(config = {}) {
+        await super.initialize(config);
+        // #1687: exports are files people generate — runtime data, so they live in
+        // the instance data folder, never in the checkout (root-owned in the image).
+        this.exportDirectory = config.exportDirectory
+            || this.engine.getManager('ConfigurationManager')?.getResolvedDataPath('ngdpbase.directories.exports', '${FAST_STORAGE}/exports')
+            || './exports';
+        const preflight = this.preflightConfiguredPath('exportDirectory', this.exportDirectory);
+        if (!preflight.ok) {
+            this.exportDirectory = '';
+            logger.info('ExportManager initialized (degraded — exports disabled)');
+            return;
+        }
+        // Create exports directory
+        await fs.mkdir(this.exportDirectory, { recursive: true });
+        logger.info('ExportManager initialized');
+    }
+    /**
+     * 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`);
+        }
+        // Render the page content (without user context for exports)
+        const renderedContent = await renderingManager.renderMarkdown(page.content, pageName, null);
+        // Create full HTML document
+        const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${pageName} - ngdpbase Export</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 2rem;
+            line-height: 1.6;
+        }
+        h1, h2, h3, h4, h5, h6 {
+            color: #333;
+            margin-top: 2rem;
+            margin-bottom: 1rem;
+        }
+        pre {
+            background: #f8f9fa;
+            padding: 1rem;
+            border-radius: 4px;
+            overflow-x: auto;
+        }
+        code {
+            background: #f8f9fa;
+            padding: 0.2rem 0.4rem;
+            border-radius: 3px;
+            font-size: 0.9em;
+        }
+        blockquote {
+            border-left: 4px solid #ddd;
+            padding-left: 1rem;
+            margin-left: 0;
+            color: #666;
+        }
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin: 1rem 0;
+        }
+        th, td {
+            border: 1px solid #ddd;
+            padding: 0.75rem;
+            text-align: left;
+        }
+        th {
+            background: #f8f9fa;
+            font-weight: 600;
+        }
+        .export-meta {
+            border-top: 1px solid #eee;
+            margin-top: 3rem;
+            padding-top: 1rem;
+            color: #666;
+            font-size: 0.9em;
+        }
+    </style>
+</head>
+<body>
+    <h1>${pageName}</h1>
+    ${renderedContent}
+
+    <div class="export-meta">
+        <p>Exported from ngdpbase on ${this.getFormattedTimestamp(user)}</p>
+        <p>Last modified: ${page.lastModified || 'Unknown'}</p>
+    ${page['system-category'] ? `<p>System Category: ${page['system-category']}</p>` : ''}
+    ${page['user-keywords'] && page['user-keywords'].length > 0 ? `<p>User Keywords: ${page['user-keywords'].join(', ')}</p>` : ''}
+    </div>
+</body>
+</html>`;
+        return html;
+    }
+    /**
+     * Export multiple pages to a single HTML file
+     * @param {string[]} pageNames - Array of page names
+     * @param {ExportUser|null} user - User object for locale-aware formatting
+     * @returns {Promise<string>} Combined HTML content
+     */
+    async exportPagesToHtml(pageNames, 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');
+        }
+        let combinedContent = '';
+        const validPages = [];
+        for (const pageName of pageNames) {
+            const page = (await pageManager.getPage(pageName, ctx));
+            if (page) {
+                const renderedContent = await renderingManager.renderMarkdown(page.content, pageName, null);
+                combinedContent += `
+          <div class="page-section" id="page-${pageName.replace(/[^a-zA-Z0-9]/g, '-')}">
+            <h1>${pageName}</h1>
+            ${renderedContent}
+            <hr style="margin: 3rem 0; border: none; border-top: 1px solid #eee;">
+          </div>
+        `;
+                validPages.push({ name: pageName, ...page });
+            }
+        }
+        // Create table of contents
+        const toc = validPages.map((page) => `<li><a href="#page-${page.name.replace(/[^a-zA-Z0-9]/g, '-')}">${page.name}</a></li>`).join('\n');
+        const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ngdpbase Export - ${validPages.length} Pages</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            max-width: 900px;
+            margin: 0 auto;
+            padding: 2rem;
+            line-height: 1.6;
+        }
+        .toc {
+            background: #f8f9fa;
+            padding: 2rem;
+            border-radius: 8px;
+            margin-bottom: 3rem;
+        }
+        .toc h2 {
+            margin-top: 0;
+        }
+        .toc ul {
+            columns: 2;
+            column-gap: 2rem;
+        }
+        .page-section {
+            margin-bottom: 4rem;
+        }
+        h1, h2, h3, h4, h5, h6 {
+            color: #333;
+            margin-top: 2rem;
+            margin-bottom: 1rem;
+        }
+        pre {
+            background: #f8f9fa;
+            padding: 1rem;
+            border-radius: 4px;
+            overflow-x: auto;
+        }
+        code {
+            background: #f8f9fa;
+            padding: 0.2rem 0.4rem;
+            border-radius: 3px;
+            font-size: 0.9em;
+        }
+        blockquote {
+            border-left: 4px solid #ddd;
+            padding-left: 1rem;
+            margin-left: 0;
+            color: #666;
+        }
+        table {
+            width: 100%;
+            border-collapse: collapse;
+            margin: 1rem 0;
+        }
+        th, td {
+            border: 1px solid #ddd;
+            padding: 0.75rem;
+            text-align: left;
+        }
+        th {
+            background: #f8f9fa;
+            font-weight: 600;
+        }
+        .export-meta {
+            border-top: 1px solid #eee;
+            margin-top: 3rem;
+            padding-top: 1rem;
+            color: #666;
+            font-size: 0.9em;
+        }
+        @media print {
+            .page-section {
+                break-inside: avoid;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="toc">
+        <h2>Table of Contents</h2>
+        <ul>
+            ${toc}
+        </ul>
+        <p><strong>${validPages.length}</strong> pages exported on ${this.getFormattedTimestamp(user)}</p>
+    </div>
+
+    ${combinedContent}
+
+    <div class="export-meta">
+        <p>Exported from ngdpbase on ${this.getFormattedTimestamp(user)}</p>
+        <p>Total pages: ${validPages.length}</p>
+    </div>
+</body>
+</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) {
+        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)
+     * @returns {string} Formatted timestamp
+     */
+    getFormattedTimestamp(user = null) {
+        const date = new Date();
+        if (user && user.preferences && user.preferences.locale) {
+            return LocaleUtils.formatDate(date, user.preferences.locale) + ' ' + LocaleUtils.formatTime(date, user.preferences.locale);
+        }
+        // Fallback to system default
+        return date.toLocaleString();
+    }
+}
+export default ExportManager;

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

@@ -0,0 +1,118 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type VaultPageNotesOutside, type PageRef } from '../utils/pageNotes.js';
+export interface PageFootnote {
+    id: string;
+    display: string;
+    url: string;
+    note: string;
+    createdBy: string;
+    createdAt: string;
+}
+export default class FootnoteManager extends BaseManager {
+    private storageDir;
+    private enabled;
+    /** Vault pages whose footnotes are still in the public folder (#1839), and the repair's re-check (#1842). */
+    private readonly outsideCheck;
+    constructor(engine: WikiEngine);
+    initialize(): Promise<void>;
+    isEnabled(): boolean;
+    /** The public folder and the vaults, as configured now (#1839). */
+    private roots;
+    /**
+     * Where `page`'s footnotes are (#1839): the public folder for a public page,
+     * the page's own vault for a vault page, read and written through that
+     * vault's store I/O. A locked vault, or a sealed kind's vault not yet
+     * opened, throws: a vault page's footnotes are never read or written in
+     * the clear.
+     */
+    private place;
+    private readMap;
+    private writeMap;
+    /**
+     * A page's footnotes, read as `ctx` may (#1839). Whether `ctx` may read the
+     * page is the caller's to decide, as for the page itself; this finds and
+     * opens them.
+     */
+    getFootnotes(page: PageRef, ctx: ActorContext): Promise<PageFootnote[]>;
+    /**
+     * Add a footnote on someone's behalf (#1233, security-posture P1).
+     *
+     * `ctx` is the request's subject — `wikiContext.userContext`, forwarded —
+     * or a JobContext for an import; never a name. `createdBy` is read from
+     * it, and the write is recorded as `footnote-edit` / `add`.
+     */
+    addFootnote(page: PageRef, data: {
+        display: string;
+        url: string;
+        note: string;
+    }, ctx: ActorContext): Promise<PageFootnote>;
+    /**
+     * #1125: import a footnote with an EXPLICIT id — the NCM conversion path.
+     *
+     * Unlike {@link addFootnote}, which assigns the next sequential id, this
+     * preserves the author's id verbatim: the body's `[^note-1]` refs resolve
+     * to `#footnote-note-1` in the rendered list, so renumbering would break
+     * every ref. Refuses to clobber an existing id (returns false) — the
+     * caller surfaces that as a warning and leaves the body definition alone.
+     */
+    importFootnote(page: PageRef, id: string, data: {
+        display: string;
+        url: string;
+        note: string;
+    }, ctx: ActorContext): Promise<boolean>;
+    /** The write behind `importFootnote` and `transferFromContent`; the callers record it, once each. */
+    private putImported;
+    /**
+     * #1125/#1126: transfer `[^id]: text` definitions from a body into this
+     * sidecar, returning the rewritten body. THE one implementation — the
+     * convert route, agent ingest, and ImportManager all delegate here, so the
+     * funnel cannot drift per-path. dryRun reports and rewrites without
+     * writing. A colliding id keeps its body definition and warns.
+     */
+    transferFromContent(page: PageRef, content: string, ctx: ActorContext, dryRun: boolean): Promise<{
+        content: string;
+        warnings: string[];
+    }>;
+    updateFootnote(page: PageRef, id: string, data: {
+        display: string;
+        url: string;
+        note: string;
+    }, ctx: ActorContext): Promise<PageFootnote | null>;
+    deleteFootnote(page: PageRef, id: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * `footnote-edit`, attributed from the context (#1233). Ids only — display,
+     * url and note are content, and the record does not repeat content.
+     * on-failure: continue, the page-edit footing.
+     */
+    private recordEdit;
+    hasFootnotes(page: PageRef, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Take a page's footnotes with it when it changes place (#1839): into a
+     * vault, out of one, or between two, through both sides' store I/O as its
+     * history goes, sealed into a sealed vault and opened coming out. The page
+     * door calls this after the page itself has moved; a rename in place moves
+     * nothing.
+     */
+    movePageFootnotes(uuid: string, fromName: string, toName: string, ctx: ActorContext): Promise<boolean>;
+    /** Vault pages whose footnotes the last check found in the public folder (#1839): owner, vault, page uuid. */
+    vaultPageNotesOutside(): VaultPageNotesOutside[];
+    /** Run that check again (#1842): after a repair, so the subsystem banner clears once nothing is left. */
+    recheckVaultPageNotesOutside(): Promise<VaultPageNotesOutside[]>;
+    /**
+     * Move vault page `uuid`'s footnotes left in the public folder into its
+     * vault (#1842), sealed when the vault is; merged with any the vault already
+     * has. Who may ask, and that `uuid` is a page of `vault`, is the caller's
+     * (`PageManager.repairVaultPage`) to decide.
+     *
+     * @returns how many footnotes were (or, with `dryRun`, would be) moved
+     */
+    moveOutsideFootnotesIntoVault(vault: {
+        owner: string;
+        store: string;
+    }, uuid: string, ctx: ActorContext, opts?: {
+        dryRun?: boolean;
+    }): Promise<number>;
+    shutdown(): Promise<void>;
+}