@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

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

@@ -0,0 +1,426 @@
+/**
+ * The VariableManager is an interface responsible for managing variables used in the wiki (for example, constant variables that can be expanded inside pages).
+ * The WikiEngine creates and initializes the VariableManager when it is instantiated. It typically instantiates the default implementation called DefaultVariableManager.
+ * During the initialization phase of the WikiEngine, it creates instances of its core managers including VariableManager and calls their initialize() method passing context and properties.
+ * This setup allows JSPWiki to handle variable substitution and expansion consistently across the wiki pages.
+ * The VariableManager is accessible via WikiEngine.getManager('VariableManager') after initialization.
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type ConfigurationManager from './ConfigurationManager.js';
+/**
+ * Validation result interface
+ */
+export interface ValidationResult {
+    success: boolean;
+    error: string | null;
+}
+/**
+ * Metadata validation result interface
+ */
+export interface MetadataValidationResult extends ValidationResult {
+    warnings?: string[];
+}
+/**
+ * Page validation result interface
+ */
+export interface PageValidationResult extends MetadataValidationResult {
+    filenameValid: boolean;
+    metadataValid: boolean;
+    fixes?: FixSuggestions;
+}
+/**
+ * Content validation result interface
+ */
+export interface ContentValidationResult {
+    warnings: string[];
+}
+/**
+ * Where a category's pages come from (#1503): made on this site, shipped with
+ * the release in required-pages/, or kept in the repository's docs/ and never
+ * stored on the site. Replaces the old storageLocation words one for one
+ * (regular → site, required → shipped, github → repo).
+ */
+/** A new share link's maximum lifetime when a vault's system-category sets none (operator, 2026-09-30, #1388). */
+export declare const DEFAULT_SHARE_MAX_DAYS = 15;
+export type CategorySource = 'site' | 'shipped' | 'repo';
+/**
+ * A category entry's source. An entry without a valid one is a site category.
+ * The one rule every reader of a category's source goes through.
+ */
+export declare function categorySource(cfg: {
+    source?: string;
+} | null | undefined): CategorySource;
+/**
+ * What is wrong with a `ngdpbase.system-category` map, one line per problem
+ * (#1504). Empty when it is sound. Startup refuses a map with problems
+ * (operator, 2026-09-28): each one could put a private page in the wrong
+ * place, so it must never run.
+ *
+ * - exactly one entry has `default: true`;
+ * - every `storageLocation.privatestore` is `pages/<parent>/{user}/<vault id>/`;
+ * - no two entries share a vault;
+ * - every vault has the same parent folder.
+ */
+export declare function systemCategoryConfigProblems(categories: unknown): string[];
+/** The preference that holds a person's choice for a `defaultPrivate: 'choice'` system-category (#1504). */
+export declare function defaultPrivatePreferenceKey(category: string): string;
+/**
+ * System category configuration
+ */
+export interface CategoryConfig {
+    label: string;
+    description?: string;
+    default?: boolean;
+    source?: CategorySource;
+    enabled?: boolean;
+    key?: string;
+}
+/**
+ * System categories configuration map
+ */
+export type SystemCategoriesConfig = Record<string, CategoryConfig>;
+/**
+ * Options for generating metadata
+ */
+export interface GenerateMetadataOptions {
+    uuid?: string;
+    slug?: string;
+    'system-category'?: string;
+    userKeywords?: string[];
+    'user-keywords'?: string[];
+    [key: string]: unknown;
+}
+/**
+ * File data from gray-matter
+ */
+export interface FileData {
+    content: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Result of a cross-page conflict check
+ */
+export interface ConflictCheckResult {
+    hasConflict: boolean;
+    /** Type of conflict detected, or null if none */
+    conflictType: 'uuid-mismatch' | 'slug-duplicate' | 'title-duplicate' | null;
+    /** UUID of the conflicting page, if any */
+    conflictingUuid?: string;
+    /** Human-readable description */
+    message?: string;
+}
+/**
+ * Fix suggestions for validation issues
+ */
+export interface FixSuggestions {
+    filename: string | null;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Page metadata interface
+ */
+export interface PageMetadata {
+    title: string;
+    uuid: string;
+    slug: string;
+    'system-category': string;
+    'user-keywords': string[];
+    lastModified: string;
+    [key: string]: unknown;
+}
+/**
+ * ValidationManager - Ensures all files follow UUID naming and metadata conventions
+ *
+ * Validates page metadata and enforces architectural constraints including UUID-based
+ * naming, required metadata fields, valid system categories, and keyword limits.
+ *
+ * @class ValidationManager
+ * @extends BaseManager
+ *
+ * @property {string[]} requiredMetadataFields - Required metadata fields
+ * @property {string[]} validSystemCategories - Valid system category values
+ * @property {number} maxCategories - Maximum categories allowed
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const validationManager = engine.getManager('ValidationManager');
+ * const result = validationManager.validatePage(metadata);
+ * if (!result.valid) console.error(result.errors);
+ */
+declare class ValidationManager extends BaseManager {
+    private requiredMetadataFields;
+    private validSystemCategories;
+    private systemCategoriesConfig;
+    private validSystemKeywords;
+    private validKnowledgeRoles;
+    private validStatuses;
+    private defaultStatus;
+    /**
+     * Creates a new ValidationManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the ValidationManager
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object
+     * @returns {Promise<void>}
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * #1559: a mistyped `defaultPrivate` or `encrypt` in the site's own entries
+     * reads as false and fails open (pages start public, a vault is created
+     * unsealed). Warn, never force (operator, 2026-10-16): the site keeps
+     * running, the log says it at error, and admins get the non-dismissible
+     * degraded-subsystem banner on the dashboard (#1155) plus a system
+     * notification — the same pair UserManager uses for shared emails. Add-on
+     * entries never reach here mistyped: the merge refuses them.
+     */
+    private reportMistypedSiteValues;
+    /**
+     * Load system categories from ConfigurationManager
+     * @param {ConfigurationManager | undefined} configManager - Configuration manager instance
+     * @returns {void}
+     */
+    loadSystemCategories(configManager: ConfigurationManager | undefined): void;
+    /**
+     * Load system keywords from ConfigurationManager.
+     * Mirrors loadSystemCategories() — populates this.validSystemKeywords.
+     * @param {ConfigurationManager | undefined} configManager
+     */
+    loadSystemKeywords(configManager: ConfigurationManager | undefined): void;
+    /**
+     * Get all valid system keyword strings.
+     */
+    getValidSystemKeywords(): string[];
+    /**
+     * Load knowledge-role catalog (#706) from ConfigurationManager.
+     * Mirrors loadSystemCategories(). The constructor seeds a hardcoded
+     * fallback (`['source','citation','concept']`) so the hard-reject enum
+     * check still works if the catalog can't be read.
+     */
+    loadKnowledgeRoles(configManager: ConfigurationManager | undefined): void;
+    /**
+     * #893: load the editorial lifecycle catalog from `ngdpbase.status` config.
+     * Entries carry label / description / order (ascending rank) / enabled and
+     * one default:true entry (the state an absent status field means). Falls
+     * back to the hardcoded trio only when config is unavailable.
+     */
+    loadStatuses(configManager: ConfigurationManager | undefined): void;
+    /**
+     * #893: valid status labels, ordered ascending by catalog `order`
+     * (lowest → highest lifecycle rank). Copy — callers can't mutate state.
+     */
+    getValidStatuses(): string[];
+    /**
+     * #893: the status an ABSENT frontmatter field means (catalog default:true
+     * entry). This value is never written to frontmatter.
+     */
+    getDefaultStatus(): string;
+    /**
+     * Get all valid knowledge-role labels (#706).
+     */
+    getValidKnowledgeRoles(): string[];
+    /**
+     * Get system keyword labels marked default:true in ngdpbase.system-keywords config.
+     * These are applied automatically to every new page in generateValidMetadata().
+     */
+    getDefaultSystemKeywords(): string[];
+    /**
+     * Get system category configuration by label
+     * @param {string} label - Category label (e.g., "General", "System")
+     * @returns {CategoryConfig | null} Category configuration or null if not found
+     */
+    getCategoryConfig(label: string): CategoryConfig | null;
+    /**
+     * Where a category's pages come from (#1503)
+     * @param {string} category - Category label
+     * @returns {CategorySource} 'site', 'shipped' or 'repo'; an unknown category is 'site'
+     */
+    getCategorySource(category: string): CategorySource;
+    /**
+     * How a new page's Private box starts for this system-category and this
+     * person (#1504): the entry's `defaultPrivate` — `true`, `false`, or
+     * `choice`, where the person's `<system-category>.defaultPrivate`
+     * preference decides and someone who has not chosen starts private. No
+     * `defaultPrivate`, or an unknown system-category, starts public. It only
+     * sets the start: the box on the page always wins.
+     *
+     * @param category - the system-category's label
+     * @param preferences - the person's saved preferences
+     */
+    getDefaultPrivate(category: string, preferences?: Record<string, unknown>): boolean;
+    /**
+     * The vault a private page of this system-category goes to (#1505): the
+     * vault id its `storageLocation.privatestore` names, or null when it has no
+     * vault (its pages can never be private).
+     */
+    getVaultId(category: string): string | null;
+    /**
+     * The longest a new share link to this vault may last, in days (#1388): the
+     * `shareMaxDays` of the system-category whose `privatestore` names the vault,
+     * set by that entry's `owner`. {@link DEFAULT_SHARE_MAX_DAYS} when the entry
+     * sets none or no entry names the vault. It limits a link only when it is
+     * made; the owner may extend a live link past it.
+     */
+    getShareMaxDays(vaultId: string): number;
+    /** Whether pages of this system-category can be private: it declares a vault (`storageLocation.privatestore`, #1504). */
+    canBePrivate(category: string): boolean;
+    /** Whether this system-category lets each person choose (`defaultPrivate: 'choice'`), so a preference is shown (#1504). */
+    offersDefaultPrivatePreference(category: string): boolean;
+    /**
+     * Get all enabled system categories
+     * @returns {CategoryConfig[]} Array of category configurations
+     */
+    getAllSystemCategories(): CategoryConfig[];
+    /**
+     * Get the default system category
+     * @returns {string} Default category label
+     */
+    getDefaultSystemCategory(): string;
+    /**
+     * Sanitize all string metadata fields before saving.
+     *
+     * - URL-decodes values so that `%09Illinois` becomes `\tIllinois` before trimming
+     * - Trims all leading/trailing Unicode whitespace (spaces, tabs, newlines, NBSP, etc.)
+     * - For `user-keywords`: trims each element and removes any that become empty
+     *
+     * Should be called once at the top of every save path so callers never need
+     * to remember to sanitize individually.
+     *
+     * @param {Record<string, unknown>} metadata - Raw metadata from request or front-matter
+     * @returns {Record<string, unknown>} New object with sanitized values (original unchanged)
+     */
+    sanitizeMetadata(metadata: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Validate that a filename follows UUID naming convention
+     * @param {string} filename - The filename to validate
+     * @returns {ValidationResult} Validation result with success and error properties
+     */
+    validateFilename(filename: string): ValidationResult;
+    /**
+     * Validate page metadata contains all required fields with proper values
+     * @param {Record<string, unknown>} metadata - The metadata object to validate
+     * @returns {MetadataValidationResult} Validation result with success, error, and warnings properties
+     */
+    validateMetadata(metadata: Record<string, unknown>): MetadataValidationResult;
+    /**
+     * Validate slug format (URL-safe)
+     * @param {string} slug - The slug to validate
+     * @returns {boolean} True if valid
+     */
+    isValidSlug(slug: string): boolean;
+    /**
+     * Validate a complete page before saving
+     * @param {string} filename - The target filename
+     * @param {Record<string, unknown>} metadata - The page metadata
+     * @param {string | null} content - The page content (optional validation)
+     * @returns {PageValidationResult} Comprehensive validation result
+     */
+    validatePage(filename: string, metadata: Record<string, unknown>, content?: string | null): PageValidationResult;
+    /**
+     * Validate page content (optional checks)
+     * @param {string} content - The page content
+     * @returns {ContentValidationResult} Content validation result
+     */
+    validateContent(content: string): ContentValidationResult;
+    /**
+     * Collect blocking validation errors for save-time enforcement (#596).
+     *
+     * Delegates to FilterManager's chain (#1117 — the one owner of the filter
+     * capability), which runs each enabled filter's own collectErrors()
+     * method. Only `severity: 'error'` rule violations are returned —
+     * warnings are surfaced through the render-time annotation path inside
+     * MarkupParser, not here.
+     *
+     * Public surface for the save path: WikiRoutes.savePage calls this and
+     * returns 400 with the structured error array if non-empty. Frontend uses
+     * each error's `rule`, `message`, and optional `line`/`column` to surface
+     * the problem to the editor.
+     *
+     * Returns an empty array when:
+     *   - content is empty or not a string
+     *   - FilterManager is not available (shouldn't happen at runtime)
+     *   - the pipeline is disabled in config, or no filter implements collectErrors
+     *
+     * @param content - The page content to validate
+     * @param context - Optional context (pageName, userName) passed through to filters
+     * @returns Array of blocking validation errors; empty array when content passes
+     */
+    collectContentErrors(content: string, context?: {
+        pageName?: string;
+        userName?: string;
+    }): Promise<Array<{
+        filterId: string;
+        rule: string;
+        severity: 'error';
+        message: string;
+        line?: number;
+        column?: number;
+    }>>;
+    /**
+     * Generate properly formatted metadata for a new page
+     * @param {string} title - Page title
+     * @param {GenerateMetadataOptions} options - Additional metadata options
+     * @returns {PageMetadata} Complete metadata object with all required fields
+     */
+    generateValidMetadata(title: string, options?: GenerateMetadataOptions): PageMetadata;
+    /**
+     * Generate URL-safe slug from title.
+     * Unicode characters are transliterated to ASCII equivalents before stripping
+     * so that titles like "Aβ" produce "abeta" rather than "a" (#295).
+     * @param {string} title - Page title
+     * @returns {string} URL-safe slug
+     */
+    generateSlug(title: string): string;
+    /**
+     * The slug of a private page (#1456, operator 2026-09-22):
+     * `vaults--{owner}-{store}-{title}` (`private--` until #1507). The prefix is reserved —
+     * {@link generateSlug} collapses dash runs, so no public slug can contain
+     * `--`, and a public save never has to consult private slugs. A clash among
+     * one owner's stores is resolved by the caller, in that owner's stores only.
+     */
+    generatePrivateSlug(owner: string, store: string, title: string): string;
+    /** Transliteration table for common non-ASCII characters (#295). */
+    private static readonly UNICODE_MAP;
+    /**
+     * Check for conflicts with existing pages (duplicate title, slug, or UUID mismatch).
+     *
+     * Used when saving a new page or comparing required-pages sources against live pages.
+     * Checks slug first (most precise), then title.
+     *
+     * @async
+     * @param {string} uuid - The UUID of the page being checked
+     * @param {string} title - The page title
+     * @param {string} slug - The page slug
+     * @returns {Promise<ConflictCheckResult>} Conflict result
+     */
+    checkConflicts(uuid: string, title: string, slug: string, ctx: ActorContext): Promise<ConflictCheckResult>;
+    /**
+     * Generate UUID-based filename from metadata
+     * @param {PageMetadata} metadata - Page metadata containing UUID
+     * @returns {string} Filename in UUID.md format
+     */
+    generateFilename(metadata: PageMetadata): string;
+    /**
+     * Validate and fix an existing page file
+     * @param {string} filePath - Path to the existing file
+     * @param {FileData} fileData - Object with content and metadata from gray-matter
+     * @returns {PageValidationResult} Validation result with fix suggestions
+     */
+    validateExistingFile(filePath: string, fileData: FileData): PageValidationResult;
+    /**
+     * Generate suggestions to fix validation issues
+     * @param {string} filename - Current filename
+     * @param {Record<string, unknown>} metadata - Current metadata
+     * @returns {FixSuggestions} Fix suggestions
+     */
+    generateFixSuggestions(filename: string, metadata: Record<string, unknown>): FixSuggestions;
+}
+export default ValidationManager;

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

@@ -0,0 +1,145 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Variable handler function type
+ */
+export type VariableHandler = (context?: VariableContext) => string;
+/**
+ * Variable context interface - contains contextual information for variable expansion
+ */
+export interface VariableContext {
+    pageName?: string;
+    userName?: string;
+    userContext?: {
+        username?: string;
+        isAuthenticated?: boolean;
+        roles?: string[];
+        displayName?: string;
+        /** User's preferred locale (e.g., 'en-US') */
+        locale?: string;
+        /** User's timezone (e.g., 'America/New_York') */
+        timezone?: string;
+        /** Full user preferences object */
+        preferences?: {
+            locale?: string;
+            timezone?: string;
+            dateFormat?: string;
+            [key: string]: unknown;
+        };
+    };
+    requestInfo?: {
+        userAgent?: string;
+        clientIp?: string;
+        referer?: string;
+        sessionId?: string;
+        acceptLanguage?: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Debug information about registered variables
+ */
+export interface VariableDebugInfo {
+    totalVariables: number;
+    systemVariables: string[];
+    contextualVariables: string[];
+    allVariables: string[];
+}
+/**
+ * VariableManager - Handles the expansion of JSPWiki-style variables
+ *
+ * Provides dynamic variable expansion in wiki content. Variables are
+ * placeholders like [{$username}], [{$pageName}] that are replaced with
+ * actual values during rendering based on the current context.
+ *
+ * Supported variable categories:
+ * - Application info: appName, version, baseURL
+ * - Page context: pageName
+ * - User context: username, loginStatus, userRoles
+ * - Date/Time: date, time, timestamp, year, month, day
+ * - System info: uptime
+ *
+ * @class VariableManager
+ * @extends BaseManager
+ *
+ * @property {Map<string, VariableHandler>} variableHandlers - Variable name to handler function map
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const variableManager = engine.getManager('VariableManager');
+ * const expanded = variableManager.expandVariables('Hello [{$username}]!', context);
+ * // Returns: 'Hello admin!'
+ */
+declare class VariableManager extends BaseManager {
+    private variableHandlers;
+    /**
+     * Creates a new VariableManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the VariableManager and register core variables
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    initialize(): Promise<void>;
+    /**
+     * Registers the default set of JSPWiki-compatible variables.
+     */
+    private registerCoreVariables;
+    /**
+     * Get user's preferred locale from context.
+     * Priority: 1) preferences.locale, 2) userContext.locale, 3) Accept-Language header, 4) en-US
+     */
+    /**
+     * Resolve the current page provider's self-description, or null when the
+     * provider is absent or does not implement getProviderInfo().
+     *
+     * @private
+     * @returns {{ name?: string; description?: string } | null} Provider info or null
+     */
+    private getPageProviderInfo;
+    private getUserLocale;
+    /** Get user's preferred date format string (e.g. 'yyyy-MM-dd') from context, or null. */
+    private getUserDateFormat;
+    /** Get user's preferred time format ('12h' | '24h') from context, or null. */
+    private getUserTimeFormat;
+    /** Get user's preferred timezone from context, or null. */
+    private getUserTimezone;
+    /**
+     * Get browser information from user agent string
+     * @param {string} userAgent - User agent string
+     * @returns {string} Browser name and version
+     */
+    private getBrowserInfo;
+    /**
+     * Registers a new variable handler.
+     * @param {string} name The name of the variable (without brackets/dollar sign).
+     * @param {VariableHandler} handler A function that takes the WikiContext and returns the variable's value.
+     */
+    registerVariable(name: string, handler: VariableHandler): void;
+    /**
+     * Expands all variables in a given string of content.
+     * @param {string} content The content to process.
+     * @param {VariableContext} context The WikiContext for the current rendering operation.
+     * @returns {string} The content with variables expanded.
+     */
+    expandVariables(content: string, context?: VariableContext): string;
+    /**
+     * Get the value of a specific variable
+     * @param {string} varName - The variable name (without brackets/dollar sign)
+     * @param {VariableContext} context - Optional context for contextual variables
+     * @returns {string} The variable value
+     */
+    getVariable(varName: string, context?: VariableContext): string;
+    /**
+     * Get debug information about registered variables
+     * @returns {VariableDebugInfo} Debug information including system and contextual variables
+     */
+    getDebugInfo(): VariableDebugInfo;
+}
+export default VariableManager;

package/lib/src/middleware/csrf.d.ts

@@ -0,0 +1,3 @@
+import type { Request, Response, NextFunction } from 'express';
+export declare function generateCsrfToken(): string;
+export declare function csrfMiddleware(req: Request, res: Response, next: NextFunction): void;