@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/types/Version.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Version type definitions for ngdpbase
+ *
+ * This module defines types for page versioning, including version metadata,
+ * manifests, and version history structures used by VersioningFileProvider.
+ */
+import { DiffTuple } from '../utils/DeltaStorage.js';
+/**
+ * Version metadata
+ *
+ * Metadata for a single page version. Stored in manifest.json as the single
+ * source of truth for all version information.
+ */
+export interface VersionMetadata {
+    /** Version number (1-based) */
+    version: number;
+    /** Author user ID or 'system' */
+    author: string;
+    /** Timestamp (ISO 8601 format) */
+    timestamp: string;
+    /** Change type */
+    changeType: 'create' | 'update' | 'minor' | 'major';
+    /** Change description/commit message */
+    message?: string;
+    /** SHA-256 hash of content for integrity verification */
+    contentHash: string;
+    /** Content size in bytes */
+    contentSize: number;
+    /** Whether content is compressed (.gz) */
+    compressed: boolean;
+    /** Whether stored as diff (true) or full content (false) */
+    isDelta: boolean;
+    /** If delta, the base version number */
+    baseVersion?: number;
+    /** Compression ratio (0-100) if compressed */
+    compressionRatio?: number;
+}
+/**
+ * Version manifest
+ *
+ * Single source of truth for all versions of a page. Stored as manifest.json
+ * in the page's version directory.
+ */
+export interface VersionManifest {
+    /** Page UUID */
+    pageUuid: string;
+    /** Page title (for reference) */
+    pageTitle: string;
+    /** Total number of versions */
+    totalVersions: number;
+    /** Current version number */
+    currentVersion: number;
+    /** Array of version metadata (sorted by version number) */
+    versions: VersionMetadata[];
+    /** Manifest creation timestamp */
+    createdAt: string;
+    /** Last manifest update timestamp */
+    updatedAt: string;
+    /** Versioning configuration at time of creation */
+    config?: {
+        deltaStorageEnabled: boolean;
+        compressionEnabled: boolean;
+        checkpointInterval: number;
+    };
+}
+/**
+ * Version content
+ *
+ * Full content for a specific version, reconstructed from deltas if necessary.
+ */
+export interface VersionContent {
+    /** Version number */
+    version: number;
+    /** Full page content (markdown) */
+    content: string;
+    /** Version metadata */
+    metadata: VersionMetadata;
+}
+/**
+ * Version diff result
+ *
+ * Result of comparing two versions.
+ */
+export interface VersionDiff {
+    /** Old version number */
+    fromVersion: number;
+    /** New version number */
+    toVersion: number;
+    /** Diff operations (from fast-diff) */
+    diff: DiffTuple[];
+    /** Diff statistics */
+    stats: {
+        additions: number;
+        deletions: number;
+        unchanged: number;
+    };
+    /** Old version metadata */
+    fromMetadata: VersionMetadata;
+    /** New version metadata */
+    toMetadata: VersionMetadata;
+}
+/**
+ * Version history entry
+ *
+ * Simplified version info for history listings.
+ */
+export interface VersionHistoryEntry {
+    /** Version number */
+    version: number;
+    /** Author user ID or 'system' */
+    author: string;
+    /** Timestamp (ISO 8601 format) */
+    timestamp: string;
+    /** Change type */
+    changeType: 'create' | 'update' | 'minor' | 'major';
+    /** Change description */
+    message?: string;
+    /** Content size in bytes */
+    contentSize: number;
+    /** Whether compressed */
+    compressed: boolean;
+}
+/**
+ * Version storage info
+ *
+ * Information about version storage and disk usage.
+ */
+export interface VersionStorageInfo {
+    /** Page UUID */
+    pageUuid: string;
+    /** Total number of versions */
+    totalVersions: number;
+    /** Total storage size in bytes (all versions) */
+    totalSize: number;
+    /** Storage size with compression/deltas in bytes */
+    storageSize: number;
+    /** Space saved (0-100) */
+    spaceSavings: number;
+    /** Average version size */
+    avgVersionSize: number;
+    /** Number of compressed versions */
+    compressedVersions: number;
+    /** Number of delta versions */
+    deltaVersions: number;
+    /** Oldest version timestamp */
+    oldestVersion: string;
+    /** Newest version timestamp */
+    newestVersion: string;
+}
+/**
+ * Version retention policy
+ *
+ * Configuration for version retention and cleanup.
+ */
+export interface VersionRetentionPolicy {
+    /** Maximum number of versions to keep (0 = unlimited) */
+    maxVersions: number;
+    /** Number of days to retain versions (0 = unlimited) */
+    retentionDays: number;
+    /** Always keep version 1 (baseline) */
+    keepBaseline: boolean;
+    /** Always keep current version */
+    keepCurrent: boolean;
+    /** Checkpoint interval for full snapshots */
+    checkpointInterval: number;
+    /** Keep all checkpoint versions */
+    keepCheckpoints: boolean;
+}
+/**
+ * Version cleanup result
+ *
+ * Result of running version cleanup/maintenance.
+ */
+export interface VersionCleanupResult {
+    /** Page UUID */
+    pageUuid: string;
+    /** Number of versions before cleanup */
+    versionsBefore: number;
+    /** Number of versions after cleanup */
+    versionsAfter: number;
+    /** Number of versions deleted */
+    versionsDeleted: number;
+    /** Space freed in bytes */
+    spaceFreed: number;
+    /** Deleted version numbers */
+    deletedVersions: number[];
+    /** Errors encountered */
+    errors?: string[];
+}

package/lib/src/types/WikiEngine.d.ts

@@ -0,0 +1,128 @@
+/**
+ * WikiEngine type definitions
+ *
+ * Defines the core WikiEngine interface and manager registry types.
+ * WikiEngine is the central orchestrator that manages all subsystems.
+ */
+import { WikiConfig } from './Config.js';
+import type { Logger } from 'winston';
+import type { Application, Request, RequestHandler, Router, RouterOptions } from 'express';
+import type express from 'express';
+/**
+ * All known manager names as a union type
+ * Use with getManager() for type-safe access when combined with explicit type parameter
+ */
+export type ManagerName = 'ConfigurationManager' | 'PageManager' | 'UserManager' | 'PolicyInformationPoint' | 'PluginManager' | 'RenderingManager' | 'SearchManager' | 'VariableManager' | 'ValidationManager' | 'SchemaManager' | 'PolicyManager' | 'PolicyValidator' | 'PolicyEvaluator' | 'ExportManager' | 'ImportManager' | 'TemplateManager' | 'AttachmentManager' | 'BackupManager' | 'CacheManager' | 'AuditManager' | 'NotificationManager' | 'CatalogManager';
+/**
+ * Manager registry - maps manager names to manager instances
+ * Note: Uses 'any' for backwards compatibility with existing code
+ */
+export interface ManagerRegistry {
+    [managerName: string]: unknown;
+}
+/**
+ * WikiEngine interface
+ *
+ * The core engine that orchestrates all wiki functionality.
+ * Manages initialization, configuration, and provides access to all managers.
+ */
+export interface WikiEngine {
+    /** Wiki configuration */
+    config?: WikiConfig;
+    /** Logger instance (winston Logger) */
+    logger?: Logger;
+    /** Engine start time */
+    startTime?: number;
+    /**
+     * Express application instance — available for add-ons to mount routes and
+     * middleware via engine.app.use().  Set by app.js before AddonsManager
+     * initialises (#359).
+     */
+    app?: Application;
+    /**
+     * The data every page view gets — the header, the left menu, the CSRF token,
+     * the signed-in user — exactly as core's own views get it
+     * (WikiRoutes.getCommonTemplateData). An add-on route that renders a view
+     * spreads it first: `res.render(view, { ...(await engine.templateData?.(req)), ... })`.
+     * One path (#1749): no add-on builds its own. Set by app.ts once the routes
+     * exist; add-ons call it per request.
+     */
+    templateData?: (req: Request) => Promise<Record<string, unknown>>;
+    /**
+     * An Express `Router` from core's own Express (#1861). Add-ons build routers
+     * here and mount them with `engine.app.use(...)`; they never value-import
+     * `express` (an installed add-on has none to resolve). `lint:addons` enforces it.
+     */
+    createRouter(options?: RouterOptions): Router;
+    /**
+     * `express.static` from core's own Express, for an add-on's `public/`
+     * folder (#1861): `engine.app?.use('/addons/x', engine.serveStatic(dir))`.
+     */
+    serveStatic(root: string, options?: Parameters<typeof express.static>[1]): RequestHandler;
+    /**
+     * Initialize the wiki engine
+     * @param config - Wiki configuration
+     * @returns The initialized engine or void
+     */
+    initialize(config?: WikiConfig): Promise<void>;
+    /**
+     * Initialize AddonsManager — call from app.ts after session/userContext middleware.
+     */
+    initializeAddons(): Promise<void>;
+    /**
+     * Get a manager by name
+     * @param managerName - Name of the manager
+     * @returns Manager instance or undefined
+     *
+     * @example
+     * // Type-safe usage with explicit type parameter:
+     * const pageManager = engine.getManager<PageManager>('PageManager');
+     */
+    getManager<T = unknown>(managerName: string): T | undefined;
+    /**
+     * Register a manager
+     * @param managerName - Name of the manager
+     * @param manager - Manager instance
+     */
+    registerManager(managerName: string, manager: unknown): void;
+    /**
+     * Get wiki configuration
+     * @returns Wiki configuration object
+     */
+    getConfig(): WikiConfig;
+    /**
+     * Shutdown the wiki engine
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Record a configuration value that cannot be used (#1152).
+     *
+     * Recorded rather than thrown so `initialize()` finishes and the admin
+     * screens exist — the instance then serves maintenance mode with a route to
+     * the repair, instead of exiting and leaving the filesystem as the only way
+     * back. Only for values an administrator can fix through the admin UI; a
+     * failure of the machinery needed to serve that UI is fatal and still throws.
+     */
+    blockConfiguration(reason: string): void;
+    /** Configuration values that could not be used, in the order found (#1152). */
+    getBlockingConditions(): readonly string[];
+    /**
+     * Get all registered manager names
+     * @returns Array of manager names
+     */
+    getRegisteredManagers(): string[];
+    /**
+     * Return the optional-capability map set during initialization.
+     * Used by templates to conditionally show/hide panels for disabled features.
+     * @returns Record mapping capability ID → boolean (e.g. { media: false })
+     */
+    getCapabilities(): Record<string, boolean>;
+    /**
+     * Record whether an optional capability is active.
+     * @param id - Capability identifier (e.g. 'media', 'audit')
+     * @param enabled - Whether the capability is active
+     */
+    setCapability(id: string, enabled: boolean): void;
+    /** Allow additional properties for extensibility */
+    [key: string]: any;
+}

package/lib/src/types/express.d.ts

@@ -0,0 +1,120 @@
+/// <reference types="express" preserve="true" />
+/// <reference types="express-session" preserve="true" />
+/// <reference types="multer" preserve="true" />
+/**
+ * Express type extensions for ngdpbase: `req.userContext`, `req.session`'s
+ * fields, uploads.
+ *
+ * A module, not a hand-written `.d.ts` (#1665): tsc emits
+ * `dist/src/types/express.d.ts` from it, and `src/context/ApiContext.ts`
+ * imports it, so an add-on that typechecks against `dist/` — bundled or
+ * external — sees these properties through the types it already imports, with
+ * no tsconfig entry. A hand-written `.d.ts` was never emitted, so external
+ * add-ons could not see it at all.
+ *
+ * Being a module also ends the restated copies the `.d.ts` needed: the share
+ * and sign-in shapes are imported, not transcribed.
+ */
+import type { ShareGrant } from './Share.js';
+import type { ProxyClaim } from '../managers/UserManager.js';
+import type { SignInRecord, PendingConnection } from '../managers/AuthManager.js';
+declare module 'express-session' {
+    interface SessionData {
+        csrfToken?: string;
+        username?: string;
+        userId?: string;
+        user?: unknown;
+        isAuthenticated?: boolean;
+        roles?: string[];
+        /** Opaque handle to this session's private-store key bag (#1382). Random, never the session id; never key bytes. */
+        privateStoreHandle?: string;
+        /** The account's password-change generation when this session signed in (#1482). */
+        sessionGeneration?: number;
+        /** How this session signed in: provider, factors with their times, amr / aal / acr (#1523). */
+        signIn?: SignInRecord;
+        /** A pending WebAuthn challenge (#448): single-use, tied to its purpose, short-lived. */
+        passkeyChallenge?: {
+            value: string;
+            purpose: 'register' | 'authenticate' | 'reauth';
+            expires: number;
+        };
+        /** A sign-in waiting for its second factor: the handle, and where to go after (#1523). No identity yet. */
+        pendingSignIn?: string;
+        pendingRedirect?: string;
+        /** A verified outside identity no account has connected, waiting for the person to sign in another way (#1743). */
+        pendingConnection?: PendingConnection;
+        /** When this session last made a request, epoch ms — kept only while an idle timeout is set (#1546). */
+        lastActivity?: number;
+        /** When this session signed in, epoch ms: the start of `ngdpbase.session.max-age` (#1767). A re-authentication never moves it. */
+        signedInAt?: number;
+        /**
+         * The proxy grant this session acts under (#1762 slice 4), chosen at
+         * `/account/acting-for`; absent while the person acts as themselves. Only
+         * a name: the grant is re-read live on every request
+         * (`AuthManager.subjectActingFor`), and a dead one clears it.
+         */
+        actingFor?: string;
+        [key: string]: unknown;
+    }
+}
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * The identity this request carries, written by the session and bearer
+             * middleware in `app.ts`.
+             *
+             * __`viaToken` is declared here deliberately (#1164, #1173).__ It was
+             * absent while `app.ts` wrote it and every route read it, so the type
+             * described a user with no delegation. `ApiContext.from()` copied "the
+             * fields" — the fields the TYPE named — and the token was gone before
+             * any permission check ran. Reaching it required a cast, and a cast is
+             * what a wrong type feels like from the inside.
+             *
+             * A token is a __delegation from this user__, not a separate actor: it
+             * carries the permissions they delegated, and authority is still the
+             * user's, resolved live. So it belongs on the identity, beside them.
+             *
+             * The `[key: string]: unknown` index signature below is why none of this
+             * was a compile error — it permits any field, so omitting one is always
+             * legal. Removing it is what would make a dropped field fail the build;
+             * that is a larger change and is not made here.
+             *
+             * __Required, not optional (#1418).__ The session middleware in `app.ts`
+             * writes it on every request before any route is registered — the
+             * signed-in user, the anonymous subject, or (bearer middleware) the
+             * token's subject — and nothing registered ahead of it reads it. Typed
+             * optional, every route had to invent something for the case that
+             * cannot happen, and the thing invented was a default actor (P1). A
+             * handler forwards `req.userContext`; it never supplies one.
+             */
+            userContext: {
+                /** #1212: the three authorisation fields are required — the session and bearer middleware always write them. */
+                username: string;
+                email?: string;
+                displayName?: string;
+                roles: string[];
+                isAuthenticated: boolean;
+                authenticated?: boolean;
+                isSystem?: boolean;
+                permissions?: string[];
+                /** The agent token this request arrived with, when it did. */
+                viaToken?: {
+                    id: string;
+                    name: string;
+                    scopes: string[];
+                };
+                /** The share this request presented, when it did (#1222). Forwarded like `viaToken`. */
+                viaShare?: ShareGrant;
+                /** The proxy grant someone is acting for this person under (#1762). Forwarded like `viaToken`. */
+                viaProxy?: ProxyClaim;
+                [key: string]: unknown;
+            };
+            file?: Multer.File;
+            files?: Multer.File[] | {
+                [fieldname: string]: Multer.File[];
+            };
+        }
+    }
+}
+export {};

package/lib/src/types/express.js

@@ -0,0 +1 @@
+export {};

package/lib/src/types/guards.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Type guards for runtime type checking
+ *
+ * This module provides type guard functions that can be used to validate
+ * data structures at runtime and provide TypeScript type narrowing.
+ */
+import { WikiPage, PageFrontmatter, PageInfo } from './Page.js';
+import { VersionMetadata, VersionManifest } from './Version.js';
+import { User, UserSession } from './User.js';
+import { AttachmentMetadata, AuditEvent } from './Provider.js';
+/**
+ * Check if value is a valid PageFrontmatter object
+ */
+export declare function isPageFrontmatter(value: unknown): value is PageFrontmatter;
+/**
+ * Check if value is a valid WikiPage object
+ */
+export declare function isWikiPage(value: unknown): value is WikiPage;
+/**
+ * Check if value is a valid PageInfo object
+ */
+export declare function isPageInfo(value: unknown): value is PageInfo;
+/**
+ * Check if value is a valid VersionMetadata object
+ */
+export declare function isVersionMetadata(value: unknown): value is VersionMetadata;
+/**
+ * Check if value is a valid VersionManifest object
+ */
+export declare function isVersionManifest(value: unknown): value is VersionManifest;
+/**
+ * Check if value is a valid User object
+ */
+export declare function isUser(value: unknown): value is User;
+/**
+ * Check if value is a valid UserSession object
+ */
+export declare function isUserSession(value: unknown): value is UserSession;
+/**
+ * Check if value is a valid AttachmentMetadata object
+ */
+export declare function isAttachmentMetadata(value: unknown): value is AttachmentMetadata;
+/**
+ * Check if value is a valid AuditEvent object
+ */
+export declare function isAuditEvent(value: unknown): value is AuditEvent;
+/**
+ * Check if value is a valid UUID (v4 format)
+ */
+export declare function isUuid(value: unknown): value is string;
+/**
+ * Check if value is a valid ISO 8601 timestamp
+ */
+export declare function isIsoTimestamp(value: unknown): value is string;
+/**
+ * Check if value is a valid email address
+ */
+export declare function isEmail(value: unknown): value is string;
+/**
+ * Validate and assert PageFrontmatter
+ * @throws {TypeError} if validation fails
+ */
+export declare function assertPageFrontmatter(value: unknown): asserts value is PageFrontmatter;
+/**
+ * Validate and assert WikiPage
+ * @throws {TypeError} if validation fails
+ */
+export declare function assertWikiPage(value: unknown): asserts value is WikiPage;
+/**
+ * Validate and assert VersionMetadata
+ * @throws {TypeError} if validation fails
+ */
+export declare function assertVersionMetadata(value: unknown): asserts value is VersionMetadata;
+/**
+ * Validate and assert User
+ * @throws {TypeError} if validation fails
+ */
+export declare function assertUser(value: unknown): asserts value is User;

package/lib/src/types/heic-decode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ambient declaration for `heic-decode` (no published types).
+ *
+ * The module's default export decodes the primary image of a HEIC/HEIF buffer
+ * via WASM libheif. Used only by the imageTransform fallback (#1076).
+ */
+declare module 'heic-decode' {
+  interface DecodedImage {
+    width: number;
+    height: number;
+    /** RGBA pixel data, width × height × 4 bytes. */
+    data: ArrayBuffer;
+  }
+  function decode(options: { buffer: Buffer | Uint8Array }): Promise<DecodedImage>;
+  export default decode;
+}

package/lib/src/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * ngdpbase Type Definitions
+ *
+ * Central export point for all TypeScript type definitions used throughout
+ * the ngdpbase application. Import types from this module to ensure consistency.
+ *
+ * @example
+ * import { WikiPage, PageFrontmatter, User } from '../types/index.js';
+ *
+ * @module types
+ */
+export { PageFrontmatter, WikiPage, PageInfo, PageSaveOptions, PageSearchResult, PageListOptions } from './Page.js';
+export { VersionMetadata, VersionManifest, VersionContent, VersionDiff, VersionHistoryEntry, VersionStorageInfo, VersionRetentionPolicy, VersionCleanupResult } from './Version.js';
+export { User, UserPreferences, UserCreateData, UserUpdateData, UserSession, AuthResult, Role, Permission, UserProfile } from './User.js';
+export { WikiConfig, VersioningConfig, SearchProviderConfig, ApplicationOrganizationConfig, ConfigPropertyDescriptor, ConfigChangeEvent, ConfigValidationResult } from './Config.js';
+export { BaseProvider, PageProvider, VersioningPageProvider, UserProvider, AttachmentProvider, AttachmentMetadata, SearchProvider, CacheProvider, AuditProvider, AuditEvent } from './Provider.js';
+export { WikiEngine, ManagerRegistry } from './WikiEngine.js';
+export { ProviderCapability, AssetGPS, AssetCamera, AssetMetadata, AssetDimensions, AssetUsageRights, AssetUsageStats, AssetRecord, AssetQuery, AssetPage, AssetInput, AssetProvider } from './Asset.js';
+export { isPageFrontmatter, isWikiPage, isPageInfo, isVersionMetadata, isVersionManifest, isUser, isUserSession, isAttachmentMetadata, isAuditEvent, isUuid, isIsoTimestamp, isEmail, assertPageFrontmatter, assertWikiPage, assertVersionMetadata, assertUser } from './guards.js';

package/lib/src/types/linkedom.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Minimal type declaration for linkedom.
+ * linkedom has no official @types package; this covers the APIs used in this project.
+ */
+declare module 'linkedom' {
+  interface LinkedomText {
+    textContent: string | null;
+    nodeType: number;
+    nodeName: string;
+  }
+
+  interface LinkedomComment {
+    textContent: string | null;
+    nodeType: number;
+    nodeName: string;
+  }
+
+  interface LinkedomNodeList extends ArrayLike<LinkedomNode> {
+    length: number;
+  }
+
+  interface LinkedomHTMLCollection extends ArrayLike<LinkedomElement> {
+    length: number;
+  }
+
+  type LinkedomNode = LinkedomElement | LinkedomText | LinkedomComment;
+
+  interface LinkedomElement {
+    innerHTML: string;
+    outerHTML: string;
+    textContent: string | null;
+    className: string;
+    nodeType: number;
+    nodeName: string;
+    tagName: string;
+    childNodes: LinkedomNodeList;
+    firstChild: LinkedomNode | null;
+    lastChild: LinkedomNode | null;
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | null;
+    removeAttribute(name: string): void;
+    appendChild(node: LinkedomNode): LinkedomNode;
+    insertBefore(newNode: LinkedomNode, referenceNode: LinkedomNode | null): LinkedomNode;
+    removeChild(node: LinkedomNode): LinkedomNode;
+    replaceChild(newNode: LinkedomNode, oldNode: LinkedomNode): LinkedomNode;
+    replaceWith(node: LinkedomNode): void;
+    remove(): void;
+    querySelector(selector: string): LinkedomElement | null;
+    querySelectorAll(selector: string): LinkedomElement[];
+    getElementsByClassName(className: string): LinkedomHTMLCollection;
+    getElementsByTagName(tagName: string): LinkedomHTMLCollection;
+  }
+
+  interface LinkedomDocument {
+    body: LinkedomElement;
+    documentElement?: LinkedomElement;
+    createElement(tag: string): LinkedomElement;
+    createTextNode(text: string): LinkedomText;
+    createComment(text: string): LinkedomComment;
+    getElementById(id: string): LinkedomElement | null;
+    querySelector(selector: string): LinkedomElement | null;
+    querySelectorAll(selector: string): LinkedomElement[];
+  }
+
+  function parseHTML(html: string): { document: LinkedomDocument };
+
+  export {
+    parseHTML,
+    LinkedomDocument,
+    LinkedomElement,
+    LinkedomText,
+    LinkedomComment,
+    LinkedomNode,
+    LinkedomNodeList,
+    LinkedomHTMLCollection
+  };
+}

package/lib/src/types/markdown-it-plugins.d.ts

@@ -0,0 +1,21 @@
+/**
+ * markdown-it plugins that ship without type declarations (#1273).
+ * markdown-it-anchor ships its own.
+ */
+declare module 'markdown-it-sub' {
+  import type { PluginSimple } from 'markdown-it';
+  const plugin: PluginSimple;
+  export default plugin;
+}
+
+declare module 'markdown-it-sup' {
+  import type { PluginSimple } from 'markdown-it';
+  const plugin: PluginSimple;
+  export default plugin;
+}
+
+declare module 'markdown-it-task-lists' {
+  import type { PluginWithOptions } from 'markdown-it';
+  const plugin: PluginWithOptions<{ enabled?: boolean; label?: boolean; labelAfter?: boolean }>;
+  export default plugin;
+}