@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

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

@@ -0,0 +1,134 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { Role, RoleUpdate } from '../types/Role.js';
+import type { RoleProvider } from '../types/RoleProvider.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import type { JobContext } from '../context/JobContext.js';
+declare class RoleManager extends BaseManager {
+    readonly description = "Canonical OrganizationRole records (#617 follow-up)";
+    private provider;
+    private providerClass?;
+    private memberCache;
+    private byOrgPositionCache;
+    private metricsRef;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Strip the catalogue copy from role records written before #1431 step 1
+     * (operator, 2026-09-21).
+     *
+     * A record holds MEMBERSHIP only. Records created earlier also carried a
+     * copy of the role's catalogue entry — `roleName`, `description`,
+     * `issystem`, `icon`, `color` — and a `permissions` list under
+     * `additionalProperty`, taken at create time, never updated and never read.
+     * Configuration declares the role's settings and the policies decide what
+     * it permits, so the copy was a second source that had already drifted
+     * (jimstest's `admin` listed 17 permissions against the 21 granted).
+     *
+     * Runs at every start and does nothing once a store is clean, so every
+     * install created before the change is cleaned, not just one. Only the copy
+     * goes: `@id`, `namedPosition`, `organization` and `member` are untouched,
+     * as is any other `additionalProperty` entry.
+     */
+    private stripCatalogueCopies;
+    /** Provider accessor, mainly for tests. */
+    getProvider(): RoleProvider | null;
+    getById(id: string): Promise<Role | null>;
+    getByOrgAndPosition(organizationId: string, namedPosition: string): Promise<Role | null>;
+    listByMember(personId: string): Promise<Role[]>;
+    list(): Promise<Role[]>;
+    create(role: Role): Promise<Role>;
+    update(id: string, patch: RoleUpdate): Promise<Role | null>;
+    delete(id: string): Promise<boolean>;
+    /**
+     * Clear all caches. Called on every write (create/update/delete) — the
+     * simplest correct invalidation strategy. Per-key invalidation is an
+     * optimization that can come later if measurement shows it matters.
+     * Public so callers (e.g., admin "rebuild" tools) can force a cache miss.
+     */
+    invalidateCache(): void;
+    /**
+     * A user's base role names: the `namedPosition` of every role record whose
+     * `member[]` holds the user's Person `@id` (#617).
+     *
+     * The pseudo-roles `'Authenticated'` and `'All'` are NOT added here — the
+     * caller adds those when constructing `userContext.roles`.
+     *
+     * Returns `[]` when PersonManager is unavailable, the user has no Person
+     * record, no record lists them, or the lookup throws.
+     */
+    resolveUserRoles(username: string): Promise<string[]>;
+    /**
+     * The `required-aal` levels the OPERATOR set in their own config (#448,
+     * #1523), as opposed to the shipped defaults. An operator's level that no
+     * factor can reach refuses the boot; a shipped default that cannot be reached
+     * only degrades, so an upgrade never locks an instance out.
+     */
+    operatorRequiredAal(): Record<string, 1 | 2 | 3>;
+    /**
+     * The roles that set their own idle timeout (#1546): role name → minutes,
+     * from each definition's optional `idle-timeout-minutes`. Only positive
+     * numbers count; empty when no role sets one, which is the shipped default.
+     */
+    roleIdleTimeouts(): Record<string, number>;
+    /**
+     * The assurance level each role requires of a sign-in (#1523): role name →
+     * AAL 1–3, from each definition's `required-aal`. A role without one (or
+     * `anonymous`) requires nothing beyond being signed in.
+     */
+    roleRequiredAal(): Record<string, 1 | 2 | 3>;
+    hasRole(username: string, roleName: string): Promise<boolean>;
+    /** Assign one role to an existing account, and record it (#1204). */
+    assignRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
+    /** Remove one role from an existing account, and record it (#1204). */
+    removeRole(username: string, roleName: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Make the user's memberships go from `oldRoles` to `newRoles`. Used by
+     * UserManager when an account is created or edited; the account write
+     * records its own audit event, so this records none.
+     */
+    applyRoleDiff(username: string, oldRoles: string[], newRoles: string[]): Promise<void>;
+    /**
+     * Give `roleName` to every account in `usernames`, once (#1539).
+     *
+     * For a role every account must hold — `ngdpbase.user.account-roles` — that
+     * arrives on an instance which already has people. The role's record not
+     * existing is the record that it was never given: this adds every account,
+     * which creates the record, and from then on finds the record and does
+     * nothing, so an admin's later removal from one person stands. Each grant is
+     * a role change and is recorded as one, under the system context `ctx`,
+     * deferred until the audit sink is up when this runs at boot.
+     *
+     * @returns how many accounts were given the role (0 once it has been given)
+     */
+    grantToEveryAccountOnce(roleName: string, usernames: readonly string[], ctx: JobContext): Promise<number>;
+    /** Remove a deleted account's Person from every role it held. */
+    removeAllMemberships(username: string): Promise<void>;
+    /**
+     * Add the user's Person `@id` to the role record for (installOrg, roleName).
+     * Idempotent: a no-op when the Person is already a member.
+     *
+     * Failures are logged, not thrown — account writes must succeed even when
+     * role storage is degraded. #1027: every abandon path says why, because a
+     * silent one is indistinguishable from success.
+     */
+    private addMember;
+    private removeMember;
+    /**
+     * The role record for (installOrg, namedPosition), created when missing.
+     *
+     * #1429/#1431: the record holds __membership only__. It used to snapshot
+     * the catalogue entry too (display name, description, and `permissions`),
+     * a copy later catalogue edits never updated and nothing read. What a role
+     * permits is the policies, resolved at the moment of each decision.
+     */
+    private getOrCreateRoleRecord;
+    /** The account must exist; membership of a missing account is refused. */
+    private requireAccount;
+    /** #1204: a role assigned or removed is a user-edit; what the account may do changed. */
+    private recordRoleChange;
+    private requireProvider;
+    private getMetrics;
+    private normalizeProviderName;
+}
+export default RoleManager;

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

@@ -0,0 +1,402 @@
+import BaseManager, { BackupData } from './BaseManager.js';
+import { WikiEngine } from '../types/WikiEngine.js';
+/**
+ * Search result structure
+ */
+interface SearchResult {
+    name: string;
+    title?: string;
+    content?: string;
+    excerpt?: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+    category?: string;
+    userKeywords?: string[];
+    [key: string]: unknown;
+}
+/**
+ * Search options
+ */
+interface SearchOptions {
+    maxResults?: number;
+    offset?: number;
+    searchIn?: string[];
+    boost?: Record<string, number>;
+    /** WikiContext for the current request — used to filter private search results */
+    wikiContext?: WikiContext;
+    [key: string]: unknown;
+}
+/**
+ * Advanced search options
+ */
+interface AdvancedSearchOptions {
+    query?: string;
+    categories?: string[];
+    /** #706: knowledge-role values to filter by (source / citation / concept). */
+    knowledgeRoles?: string[];
+    userKeywords?: string[];
+    searchIn?: string[];
+    maxResults?: number;
+    offset?: number;
+    /** #643 / #774: date range (inclusive, whole-day). */
+    dateRange?: {
+        from?: string;
+        to?: string;
+    };
+    /** #774: which date field `dateRange` filters on. Default `'modified'`. */
+    dateField?: 'modified' | 'created';
+    [key: string]: unknown;
+}
+/**
+ * Search statistics structure
+ */
+interface SearchStatistics {
+    totalDocuments: number;
+    indexSize: number;
+    averageDocumentLength: number;
+    totalCategories: number;
+    totalUserKeywords: number;
+    [key: string]: unknown;
+}
+/**
+ * Page data for indexing
+ */
+interface PageData {
+    name: string;
+    title?: string;
+    content?: string;
+    metadata?: Record<string, unknown>;
+    category?: string;
+    userKeywords?: string[];
+    [key: string]: unknown;
+}
+/**
+ * WikiContext interface
+ */
+interface WikiContext {
+    userContext?: {
+        username?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * SearchManager - Handles search indexing and querying
+ *
+ * Similar to JSPWiki's SearchManager, this manager provides full-text search
+ * capabilities through a pluggable provider system. Supports different search
+ * backends (Lunr.js, Elasticsearch, etc.) via provider abstraction.
+ *
+ * Key features:
+ * - Pluggable search provider system
+ * - Full-text indexing of page content and metadata
+ * - Configurable search ranking and filtering
+ * - Automatic index rebuilding
+ * - Provider abstraction for different search engines
+ *
+ * Follows the provider pattern established in AttachmentManager, PageManager,
+ * CacheManager, and AuditManager for pluggable search backends.
+ *
+ * Configuration (all lowercase):
+ * - ngdpbase.search.enabled - Enable/disable search
+ * - ngdpbase.search.provider.default - Default provider name
+ * - ngdpbase.search.provider - Active provider name
+ * - ngdpbase.search.provider.lunr.* - LunrSearchProvider settings
+ *
+ * @class SearchManager
+ * @extends BaseManager
+ *
+ * @property {BaseSearchProvider|null} provider - The active search provider
+ * @property {string|null} providerClass - The class name of the loaded provider
+ *
+ * @see {@link BaseManager} for base functionality
+ * @see {@link LunrSearchProvider} for default provider implementation
+ *
+ * @example
+ * const searchManager = engine.getManager('SearchManager');
+ * const results = await searchManager.search('hello world');
+ * console.log(`Found ${results.length} pages`);
+ *
+ * Related: GitHub Issue #102 - Configuration reorganization
+ */
+declare class SearchManager extends BaseManager {
+    private provider;
+    private providerClass;
+    /**
+     * Creates a new SearchManager instance
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the SearchManager and load the configured provider
+     *
+     * Loads the search provider, builds the initial search index, and prepares
+     * the search system for queries.
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object (unused, reads from ConfigurationManager)
+     * @returns {Promise<void>}
+     * @throws {Error} If ConfigurationManager is not available or provider fails to load
+     *
+     * @example
+     * await searchManager.initialize();
+     * console.log('Search system ready');
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Normalize provider name to PascalCase class name
+     *
+     * @param {string} providerName - Provider name from config (e.g., 'lunrsearchprovider')
+     * @returns {string} PascalCase class name (e.g., 'LunrSearchProvider')
+     * @private
+     */
+    private normalizeProviderName;
+    /**
+     * Load the search provider dynamically
+     *
+     * @private
+     * @returns {Promise<void>}
+     * @throws {Error} If provider loading fails completely
+     */
+    private loadProvider;
+    /**
+     * Build search index from all pages
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If index building fails
+     */
+    buildSearchIndex(): Promise<void>;
+    /**
+     * Search for pages using WikiContext
+     *
+     * Performs a search using WikiContext as the single source of truth for user information.
+     * Logs search queries with user context for analytics and audit purposes.
+     *
+     * @async
+     * @param {WikiContext} wikiContext - The wiki context containing user info
+     * @param {string} query - Search query
+     * @param {SearchOptions} [options={}] - Additional search options
+     * @returns {Promise<SearchResult[]>} Search results
+     * @throws {Error} If wikiContext is not provided
+     *
+     * @example
+     * const results = await searchManager.searchWithContext(wikiContext, 'hello world');
+     * console.log(`Found ${results.length} pages`);
+     */
+    searchWithContext(wikiContext: WikiContext, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Public results, plus the requester's own private pages (#1458).
+     *
+     * The private matches come from the page door, which reads each of the
+     * REQUESTER'S OWN readable stores with their context — never from a store
+     * file read here, and never for anyone else's container: another user's
+     * search, and an admin's, reach none of them. A locked encrypted store
+     * yields nothing rather than an error.
+     *
+     * A private row carries the page's private name, so `pageUrl` links to it.
+     */
+    private mergeOwnPrivateResults;
+    /**
+     * Advanced search with WikiContext
+     *
+     * Performs advanced search with multiple criteria using WikiContext as the single source
+     * of truth. Logs detailed search parameters with user context for analytics.
+     *
+     * @async
+     * @param {WikiContext} wikiContext - The wiki context containing user info
+     * @param {AdvancedSearchOptions} [options={}] - Search options
+     * @returns {Promise<SearchResult[]>} Search results
+     * @throws {Error} If wikiContext is not provided
+     *
+     * @example
+     * const results = await searchManager.advancedSearchWithContext(wikiContext, {
+     *   query: 'tutorial',
+     *   categories: ['Documentation'],
+     *   maxResults: 20
+     * });
+     */
+    advancedSearchWithContext(wikiContext: WikiContext, options?: AdvancedSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Search for pages matching the query
+     *
+     * @param {string} query - Search query
+     * @param {SearchOptions} options - Search options
+     * @returns {Promise<SearchResult[]>} Search results
+     * @deprecated Use searchWithContext() with WikiContext instead
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Advanced search with multiple criteria support
+     *
+     * @param {AdvancedSearchOptions} options - Search options
+     * @returns {Promise<SearchResult[]>} Search results
+     * @deprecated Use advancedSearchWithContext() with WikiContext instead
+     */
+    advancedSearch(options?: AdvancedSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Suggest similar pages based on content
+     *
+     * @param {string} pageName - Source page name
+     * @param {number} limit - Maximum suggestions
+     * @returns {Promise<SearchResult[]>} Suggested pages
+     */
+    suggestSimilarPages(pageName: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Get search suggestions for autocomplete
+     *
+     * @param {string} partial - Partial search term
+     * @returns {Promise<string[]>} Suggested completions
+     */
+    getSuggestions(partial: string): Promise<string[]>;
+    /**
+     * Rebuild search index (called after page changes)
+     *
+     * @returns {Promise<void>}
+     */
+    rebuildIndex(): Promise<void>;
+    /**
+     * #724: true rebuild FROM DISK — clears the index + persisted cache and
+     * re-scans every page, so entries for deleted pages ("ghosts") are
+     * dropped by construction. This is the "Rebuild" to rebuildIndex()'s
+     * "Reindex" (mirrors media.rebuild vs media.rescan). Providers that lack
+     * a disk-reconciling rebuild fall back to the normal index build.
+     *
+     * @returns {Promise<void>}
+     */
+    rebuildFromDisk(): Promise<void>;
+    /**
+     * Add/update a page in the search index
+     *
+     * @param {string} pageName - Page name
+     * @param {PageData} pageData - Page data
+     * @returns {Promise<void>}
+     */
+    updatePageInIndex(pageName: string, pageData: PageData): Promise<void>;
+    /**
+     * Remove a page from the search index
+     *
+     * @param {string} pageName - Page name to remove
+     * @returns {Promise<void>}
+     */
+    removePageFromIndex(pageName: string): Promise<void>;
+    /**
+     * Search by multiple categories
+     *
+     * @param {string[]} categories - Array of category names to search
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    searchByCategories(categories: string[]): Promise<SearchResult[]>;
+    /**
+     * Search by multiple user keywords
+     *
+     * @param {string[]} keywords - Array of user keywords to search
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    searchByUserKeywordsList(keywords: string[]): Promise<SearchResult[]>;
+    /**
+     * Get all unique categories from indexed documents
+     *
+     * @returns {Promise<string[]>} List of categories
+     */
+    getAllCategories(): Promise<string[]>;
+    /**
+     * Get all unique user keywords from indexed documents
+     *
+     * @returns {Promise<string[]>} List of user keywords
+     */
+    getAllUserKeywords(): Promise<string[]>;
+    /**
+     * Return all systemKeywords present in the search index (union across all pages).
+     * Used to populate the "Browse / Filter by System Keyword" UI (#509).
+     * Returns [] if the active provider does not support this operation (e.g. Lunr).
+     */
+    getAllSystemKeywords(): Promise<string[]>;
+    /**
+     * Search pages that have all of the given system keywords.
+     * Returns [] if provider does not support systemKeywords filtering.
+     */
+    searchBySystemKeywordsList(keywords: string[]): Promise<SearchResult[]>;
+    /**
+     * Get systemKeywords stored in the search index for a specific page.
+     * Returns auto-tagged terms added by TaggingService at index time (#507).
+     * Returns [] if the active provider does not support this operation.
+     */
+    getPageSystemKeywords(pageName: string): Promise<string[]>;
+    /**
+     * Search by category only
+     *
+     * @param {string} category - Category to search for
+     * @returns {Promise<SearchResult[]>} Pages in category
+     */
+    searchByCategory(category: string): Promise<SearchResult[]>;
+    /**
+     * Search by user keywords only
+     *
+     * @param {string} keyword - Keyword to search for
+     * @returns {Promise<SearchResult[]>} Pages with keyword
+     */
+    searchByUserKeywords(keyword: string): Promise<SearchResult[]>;
+    getAllDocuments(): Promise<SearchResult[]>;
+    /**
+     * Get search statistics
+     *
+     * @returns {Promise<SearchStatistics>} Search statistics
+     */
+    getStatistics(): Promise<SearchStatistics>;
+    /**
+     * Get the total number of indexed documents
+     *
+     * @returns {Promise<number>} Number of documents
+     */
+    getDocumentCount(): Promise<number>;
+    /**
+     * Search by keywords
+     *
+     * @param {string[]} keywords - Keywords to search for
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    searchByKeywords(keywords: string[]): Promise<SearchResult[]>;
+    /**
+     * Add page to search index
+     *
+     * @param {PageData} page - Page object to add
+     * @returns {Promise<void>}
+     */
+    addToIndex(page: PageData): Promise<void>;
+    /**
+     * Remove page from search index
+     *
+     * @param {string} pageName - Name of page to remove
+     * @returns {Promise<void>}
+     */
+    removeFromIndex(pageName: string): Promise<void>;
+    /**
+     * Perform multi-criteria search
+     *
+     * @param {AdvancedSearchOptions} criteria - Search criteria object
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    multiSearch(criteria: AdvancedSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Backup search configuration and state
+     *
+     * @returns {Promise<BackupData>} Backup data
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore search from backup
+     *
+     * @param {BackupData} backupData - Backup data
+     * @returns {Promise<void>}
+     */
+    restore(backupData: BackupData): Promise<void>;
+    /**
+     * Shutdown search manager and close provider
+     *
+     * @returns {Promise<void>}
+     */
+    shutdown(): Promise<void>;
+}
+export default SearchManager;