adminizer 5.0.0-build.8 → 5.1.0-build.24

package/lib/docs/AbstractDocumentation.d.ts

@@ -0,0 +1,100 @@
+import type { Adminizer } from '../Adminizer.js';
+export interface DocMeta {
+    /** Stable document identifier; the only handle that ever leaves the abstraction. */
+    id: string;
+    /** Title in the requested locale when a translation exists. */
+    title: string;
+    /** Viewer grouping. */
+    section?: string;
+    keywords: string[];
+    /** Model resource names this document is about. */
+    models: string[];
+    /** Express-style admin path patterns (`:id` placeholders) the document is bound to. */
+    urls: string[];
+    /**
+     * Per-document access right, required on top of the base documentation
+     * token. References an existing token (registered by the host or an app);
+     * documentation never creates tokens itself.
+     */
+    accessRightsToken?: string;
+    /** Locales this document is available in. */
+    locales?: string[];
+}
+export interface DocContent {
+    meta: DocMeta;
+    /** Content in the locale that was actually served. */
+    markdown: string;
+    locale: string;
+}
+export interface DocSearchQuery {
+    /** Full-text query; matched against title, keywords and content. */
+    query?: string;
+    /** Every listed keyword must be present on the document. */
+    keywords?: string[];
+    /** Narrow the scope to documents bound to this admin path. */
+    url?: string;
+    /** Narrow the scope to documents bound to this model. */
+    model?: string;
+}
+export interface DocSearchResult {
+    meta: DocMeta;
+    /** Matched lines with a little surrounding context, best matches first. */
+    snippets: string[];
+}
+/**
+ * The single contract of the documentation subsystem. Everything adminizer
+ * does with documentation — listing, reading, searching, resolving links —
+ * goes through this class; where documents live, how translations are stored
+ * and how search works are private details of the implementation.
+ *
+ * One implementation is active per adminizer instance (a singleton registered
+ * on startup). Implementations know nothing about users or permissions: the
+ * access layer is applied by adminizer on top of every result.
+ *
+ * Only `list` and `get` are required. The base class implements search,
+ * context matching, the keyword map and link resolution on top of them; an
+ * implementation overrides any of those when it can do better (e.g. database
+ * full-text search).
+ */
+export declare abstract class AbstractDocumentation {
+    /** Set when the implementation is registered; not part of the contract. */
+    adminizer: Adminizer;
+    /**
+     * Metadata of every document, without content, in the requested locale.
+     * Falls back to the best available translation per document.
+     */
+    abstract list(locale?: string): Promise<DocMeta[]>;
+    /**
+     * One document in the requested locale. How the translation is obtained
+     * is up to the implementation; when the locale is unavailable it serves
+     * the best available version and reports which locale it actually is.
+     */
+    abstract get(id: string, locale?: string): Promise<DocContent | undefined>;
+    /**
+     * Keyword filter plus full-text scan over `list()`/`get()`. Content is
+     * only fetched for documents that survive the metadata filters.
+     */
+    search(query: DocSearchQuery, locale?: string): Promise<DocSearchResult[]>;
+    /** Documents bound to a place in the admin panel: a URL and/or a model. */
+    forContext(ctx: {
+        url?: string;
+        model?: string;
+    }, locale?: string): Promise<DocMeta[]>;
+    /** Keyword → document ids, aggregated from metadata. */
+    keywords(locale?: string): Promise<Map<string, string[]>>;
+    /**
+     * Resolves a reference written inside `fromId` to the id of the target
+     * document. How authors spell references is implementation-specific; the
+     * default only understands plain document ids (with an optional anchor).
+     */
+    resolveLink(_fromId: string, ref: string): Promise<string | undefined>;
+    /**
+     * Change notification: consumers subscribe to drop their caches. Optional;
+     * implementations without it are treated as static.
+     */
+    onChange?(cb: (ids?: string[]) => void): void;
+    /** Matches an Express-style pattern (`/model/:name`) against a concrete path. */
+    protected matchesUrl(pattern: string, url: string): boolean;
+    /** Lines containing the query, trimmed to a little context around the match. */
+    protected extractSnippets(markdown: string, query: string): string[];
+}

package/lib/docs/AbstractDocumentation.js

@@ -0,0 +1,108 @@
+const SNIPPET_LIMIT = 3;
+const SNIPPET_CONTEXT = 120;
+/**
+ * The single contract of the documentation subsystem. Everything adminizer
+ * does with documentation — listing, reading, searching, resolving links —
+ * goes through this class; where documents live, how translations are stored
+ * and how search works are private details of the implementation.
+ *
+ * One implementation is active per adminizer instance (a singleton registered
+ * on startup). Implementations know nothing about users or permissions: the
+ * access layer is applied by adminizer on top of every result.
+ *
+ * Only `list` and `get` are required. The base class implements search,
+ * context matching, the keyword map and link resolution on top of them; an
+ * implementation overrides any of those when it can do better (e.g. database
+ * full-text search).
+ */
+export class AbstractDocumentation {
+    /** Set when the implementation is registered; not part of the contract. */
+    adminizer;
+    /**
+     * Keyword filter plus full-text scan over `list()`/`get()`. Content is
+     * only fetched for documents that survive the metadata filters.
+     */
+    async search(query, locale) {
+        const wanted = (query.query ?? '').trim().toLowerCase();
+        const keywords = (query.keywords ?? []).map((keyword) => keyword.trim().toLowerCase()).filter(Boolean);
+        let candidates = await this.forContext({ url: query.url, model: query.model }, locale);
+        if (keywords.length > 0) {
+            candidates = candidates.filter((meta) => {
+                const present = meta.keywords.map((keyword) => keyword.toLowerCase());
+                return keywords.every((keyword) => present.includes(keyword));
+            });
+        }
+        if (!wanted)
+            return candidates.map((meta) => ({ meta, snippets: [] }));
+        const results = [];
+        for (const meta of candidates) {
+            const inMeta = meta.title.toLowerCase().includes(wanted)
+                || meta.keywords.some((keyword) => keyword.toLowerCase().includes(wanted));
+            const content = await this.get(meta.id, locale);
+            const snippets = content ? this.extractSnippets(content.markdown, wanted) : [];
+            if (inMeta || snippets.length > 0)
+                results.push({ meta, snippets });
+        }
+        return results;
+    }
+    /** Documents bound to a place in the admin panel: a URL and/or a model. */
+    async forContext(ctx, locale) {
+        const documents = await this.list(locale);
+        const url = ctx.url?.trim();
+        const model = ctx.model?.trim();
+        if (!url && !model)
+            return documents;
+        return documents.filter((meta) => (!url || meta.urls.some((pattern) => this.matchesUrl(pattern, url)))
+            && (!model || meta.models.includes(model)));
+    }
+    /** Keyword → document ids, aggregated from metadata. */
+    async keywords(locale) {
+        const map = new Map();
+        for (const meta of await this.list(locale)) {
+            for (const raw of meta.keywords) {
+                const keyword = raw.trim();
+                if (!keyword)
+                    continue;
+                const ids = map.get(keyword) ?? [];
+                if (!ids.includes(meta.id))
+                    ids.push(meta.id);
+                map.set(keyword, ids);
+            }
+        }
+        return map;
+    }
+    /**
+     * Resolves a reference written inside `fromId` to the id of the target
+     * document. How authors spell references is implementation-specific; the
+     * default only understands plain document ids (with an optional anchor).
+     */
+    async resolveLink(_fromId, ref) {
+        const id = ref.trim().replace(/#.*$/, '');
+        if (!id)
+            return undefined;
+        const documents = await this.list();
+        return documents.find((meta) => meta.id === id)?.id;
+    }
+    /** Matches an Express-style pattern (`/model/:name`) against a concrete path. */
+    matchesUrl(pattern, url) {
+        const path = url.replace(/[?#].*$/, '').replace(/\/+$/, '') || '/';
+        const source = pattern.replace(/\/+$/, '') || '/';
+        const regex = new RegExp(`^${source.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/:[A-Za-z0-9_]+/g, '[^/]+')}$`);
+        return regex.test(path);
+    }
+    /** Lines containing the query, trimmed to a little context around the match. */
+    extractSnippets(markdown, query) {
+        const snippets = [];
+        for (const line of markdown.split('\n')) {
+            const index = line.toLowerCase().indexOf(query);
+            if (index === -1)
+                continue;
+            const start = Math.max(0, index - SNIPPET_CONTEXT / 2);
+            const snippet = line.slice(start, start + query.length + SNIPPET_CONTEXT).trim();
+            snippets.push(`${start > 0 ? '…' : ''}${snippet}${start + query.length + SNIPPET_CONTEXT < line.length ? '…' : ''}`);
+            if (snippets.length >= SNIPPET_LIMIT)
+                break;
+        }
+        return snippets;
+    }
+}

package/lib/docs/DocumentationHandler.d.ts

@@ -0,0 +1,100 @@
+import type { User } from '../../models/User.js';
+import type { Adminizer } from '../Adminizer.js';
+import type { AbstractDocumentation, DocContent, DocMeta, DocSearchQuery, DocSearchResult } from './AbstractDocumentation.js';
+export declare const DOCUMENTATION_BASE_TOKEN = "read-documentation";
+export declare const DOCUMENTATION_DEPARTMENT = "documentation";
+/** Contextual table of contents handed to the UI as a shared Inertia prop. */
+export interface DocContextSummary {
+    count: number;
+    items: Array<{
+        id: string;
+        title: string;
+        section?: string;
+    }>;
+}
+/**
+ * The adminizer-side facade of the documentation subsystem: holds the single
+ * active `AbstractDocumentation` implementation and applies access rights to
+ * every result before it can reach the UI, the HTTP API or the assistant.
+ *
+ * Implementations know nothing about users; a document a user may not read
+ * simply does not exist for them — it is absent from listings, search results,
+ * the keyword map and link resolution.
+ *
+ * Per-document rights are declarative: the document author references an
+ * existing access token in the metadata (a model token like `read-Test-model`
+ * via `models`, or any custom token via `accessRightsToken`). The subsystem
+ * never creates tokens from documents — a referenced token that nobody
+ * registered simply keeps the document admin-only.
+ */
+export declare class DocumentationHandler {
+    private readonly adminizer;
+    private readonly bind?;
+    private service?;
+    private owner?;
+    private bound;
+    /**
+     * `bind` is the wiring Adminizer installs (token, navigation, skills, HTTP
+     * routes); it runs at most once, the moment the feature has both of its
+     * switches: `config.documentation.enabled` and a registered implementation.
+     */
+    constructor(adminizer: Adminizer, bind?: () => void);
+    /** Base access token; without it the whole subsystem is invisible. */
+    get baseToken(): string;
+    get enabled(): boolean;
+    isRegistered(): boolean;
+    /**
+     * Activates the singleton implementation. Registering a second one is an
+     * error: replacing the active service must be an explicit `unregister`
+     * followed by a new `register`.
+     *
+     * With `config.documentation.enabled` set, the first registration also
+     * brings the subsystem up — token, navigation, skills and HTTP routes.
+     * None of it exists before that, so a missing implementation is
+     * indistinguishable from a disabled feature.
+     */
+    register(service: AbstractDocumentation, owner?: string): void;
+    /**
+     * Runs the installed wiring once both switches of the feature hold. Called
+     * from `register()` and again from `Adminizer.init` — that second call
+     * covers a service registered before the config was read. Re-registering
+     * after an `unregister` reuses the wiring instead of mounting it twice.
+     */
+    activate(): void;
+    unregister(owner?: string): boolean;
+    /** The locale documentation is served in when the consumer names none. */
+    localeFor(user?: User): string | undefined;
+    /** Metadata of every document this user may read. */
+    list(user: User, locale?: string): Promise<DocMeta[]>;
+    /** One document, or `undefined` when it does not exist for this user. */
+    get(user: User, id: string, locale?: string): Promise<DocContent | undefined>;
+    search(user: User, query: DocSearchQuery, locale?: string): Promise<DocSearchResult[]>;
+    /** Whether the subsystem is up and this user may read documentation at all. */
+    canRead(user?: User): Promise<boolean>;
+    /**
+     * The contextual table of contents of an admin page: metadata only, and
+     * `null` when the subsystem is off or the user may not read documentation.
+     * Shared with every page as a prop, so it never throws.
+     */
+    forContextMeta(user: User, url: string, locale?: string): Promise<DocContextSummary | null>;
+    /** Documents bound to a place in the admin panel this user may read. */
+    forContext(user: User, ctx: {
+        url?: string;
+        model?: string;
+    }, locale?: string): Promise<DocMeta[]>;
+    /**
+     * Keyword → document ids over accessible documents only: keywords of a
+     * hidden document never reach the map, empty keywords are dropped.
+     */
+    keywords(user: User, locale?: string): Promise<Map<string, string[]>>;
+    /** Resolves an in-document reference; a target this user may not read stays unresolved. */
+    resolveLink(user: User, fromId: string, ref: string): Promise<string | undefined>;
+    private requireService;
+    private permitted;
+    /**
+     * The access decision of the subsystem: the base token, then the per-doc
+     * token, then — for model-bound documents — read access to at least one of
+     * the models, with the same token DataAccessor gates the data itself.
+     */
+    private allowed;
+}

package/lib/docs/DocumentationHandler.js

@@ -0,0 +1,198 @@
+export const DOCUMENTATION_BASE_TOKEN = 'read-documentation';
+export const DOCUMENTATION_DEPARTMENT = 'documentation';
+/**
+ * The adminizer-side facade of the documentation subsystem: holds the single
+ * active `AbstractDocumentation` implementation and applies access rights to
+ * every result before it can reach the UI, the HTTP API or the assistant.
+ *
+ * Implementations know nothing about users; a document a user may not read
+ * simply does not exist for them — it is absent from listings, search results,
+ * the keyword map and link resolution.
+ *
+ * Per-document rights are declarative: the document author references an
+ * existing access token in the metadata (a model token like `read-Test-model`
+ * via `models`, or any custom token via `accessRightsToken`). The subsystem
+ * never creates tokens from documents — a referenced token that nobody
+ * registered simply keeps the document admin-only.
+ */
+export class DocumentationHandler {
+    adminizer;
+    bind;
+    service;
+    owner;
+    bound = false;
+    /**
+     * `bind` is the wiring Adminizer installs (token, navigation, skills, HTTP
+     * routes); it runs at most once, the moment the feature has both of its
+     * switches: `config.documentation.enabled` and a registered implementation.
+     */
+    constructor(adminizer, bind) {
+        this.adminizer = adminizer;
+        this.bind = bind;
+    }
+    /** Base access token; without it the whole subsystem is invisible. */
+    get baseToken() {
+        return DOCUMENTATION_BASE_TOKEN;
+    }
+    get enabled() {
+        return this.adminizer.config.documentation?.enabled === true && Boolean(this.service);
+    }
+    isRegistered() {
+        return Boolean(this.service);
+    }
+    /**
+     * Activates the singleton implementation. Registering a second one is an
+     * error: replacing the active service must be an explicit `unregister`
+     * followed by a new `register`.
+     *
+     * With `config.documentation.enabled` set, the first registration also
+     * brings the subsystem up — token, navigation, skills and HTTP routes.
+     * None of it exists before that, so a missing implementation is
+     * indistinguishable from a disabled feature.
+     */
+    register(service, owner = 'host') {
+        if (this.service) {
+            throw new Error(`Documentation service is already registered by "${this.owner}"`);
+        }
+        service.adminizer = this.adminizer;
+        this.service = service;
+        this.owner = owner;
+        this.activate();
+    }
+    /**
+     * Runs the installed wiring once both switches of the feature hold. Called
+     * from `register()` and again from `Adminizer.init` — that second call
+     * covers a service registered before the config was read. Re-registering
+     * after an `unregister` reuses the wiring instead of mounting it twice.
+     */
+    activate() {
+        if (this.bound || !this.bind || !this.service)
+            return;
+        if (this.adminizer.config?.documentation?.enabled !== true)
+            return;
+        this.bound = true;
+        this.bind();
+    }
+    unregister(owner) {
+        if (!this.service || (owner && this.owner !== owner))
+            return false;
+        this.service = undefined;
+        this.owner = undefined;
+        return true;
+    }
+    /** The locale documentation is served in when the consumer names none. */
+    localeFor(user) {
+        if (user?.locale)
+            return user.locale;
+        const translation = this.adminizer.config.translation;
+        return typeof translation === 'object' && translation ? translation.defaultLocale : undefined;
+    }
+    /** Metadata of every document this user may read. */
+    async list(user, locale) {
+        const service = this.requireService();
+        return this.permitted(user, await service.list(locale));
+    }
+    /** One document, or `undefined` when it does not exist for this user. */
+    async get(user, id, locale) {
+        const service = this.requireService();
+        const content = await service.get(id, locale);
+        if (!content || !(await this.allowed(user, content.meta)))
+            return undefined;
+        return content;
+    }
+    async search(user, query, locale) {
+        const service = this.requireService();
+        const results = await service.search(query, locale);
+        const filtered = [];
+        for (const result of results) {
+            if (await this.allowed(user, result.meta))
+                filtered.push(result);
+        }
+        return filtered;
+    }
+    /** Whether the subsystem is up and this user may read documentation at all. */
+    async canRead(user) {
+        if (!this.enabled || !user)
+            return false;
+        return Boolean(await this.adminizer.accessRightsHelper.hasPermission(this.baseToken, user));
+    }
+    /**
+     * The contextual table of contents of an admin page: metadata only, and
+     * `null` when the subsystem is off or the user may not read documentation.
+     * Shared with every page as a prop, so it never throws.
+     */
+    async forContextMeta(user, url, locale) {
+        if (!(await this.canRead(user)))
+            return null;
+        const documents = await this.forContext(user, { url }, locale ?? this.localeFor(user));
+        return {
+            count: documents.length,
+            items: documents.map((meta) => ({ id: meta.id, title: meta.title, section: meta.section })),
+        };
+    }
+    /** Documents bound to a place in the admin panel this user may read. */
+    async forContext(user, ctx, locale) {
+        const service = this.requireService();
+        return this.permitted(user, await service.forContext(ctx, locale));
+    }
+    /**
+     * Keyword → document ids over accessible documents only: keywords of a
+     * hidden document never reach the map, empty keywords are dropped.
+     */
+    async keywords(user, locale) {
+        const service = this.requireService();
+        const visible = new Set((await this.list(user, locale)).map((meta) => meta.id));
+        const map = new Map();
+        for (const [keyword, ids] of await service.keywords(locale)) {
+            const permitted = ids.filter((id) => visible.has(id));
+            if (permitted.length > 0)
+                map.set(keyword, permitted);
+        }
+        return map;
+    }
+    /** Resolves an in-document reference; a target this user may not read stays unresolved. */
+    async resolveLink(user, fromId, ref) {
+        const service = this.requireService();
+        const target = await service.resolveLink(fromId, ref);
+        if (!target)
+            return undefined;
+        const metas = await service.list();
+        const meta = metas.find((candidate) => candidate.id === target);
+        if (!meta || !(await this.allowed(user, meta)))
+            return undefined;
+        return target;
+    }
+    requireService() {
+        if (!this.service)
+            throw new Error('No documentation service is registered');
+        return this.service;
+    }
+    async permitted(user, metas) {
+        const filtered = [];
+        for (const meta of metas) {
+            if (await this.allowed(user, meta))
+                filtered.push(meta);
+        }
+        return filtered;
+    }
+    /**
+     * The access decision of the subsystem: the base token, then the per-doc
+     * token, then — for model-bound documents — read access to at least one of
+     * the models, with the same token DataAccessor gates the data itself.
+     */
+    async allowed(user, meta) {
+        const has = (token) => this.adminizer.accessRightsHelper.hasPermission(token, user);
+        if (!(await has(this.baseToken)))
+            return false;
+        if (meta.accessRightsToken && !(await has(meta.accessRightsToken)))
+            return false;
+        if (meta.models.length > 0) {
+            for (const model of meta.models) {
+                if (await has(`read-${model}-model`))
+                    return true;
+            }
+            return false;
+        }
+        return true;
+    }
+}

package/lib/docs/FileDocumentation.d.ts

@@ -0,0 +1,47 @@
+import { AbstractDocumentation, DocContent, DocMeta } from './AbstractDocumentation.js';
+export interface FileDocumentationOptions {
+    /** Directory scanned (recursively) for markdown documents. */
+    dir: string;
+    /** Locale of files without a locale suffix. @default "en" */
+    defaultLocale?: string;
+    /** Watch the directory and drop the cache on changes. @default false */
+    watch?: boolean;
+}
+/**
+ * The reference implementation bundled with adminizer: documents are markdown
+ * files with a frontmatter header, translations are sibling files with a
+ * locale suffix (`intro.md` + `intro.ru.md` → document `intro` in two
+ * locales). Structural metadata (bindings, rights, section) is taken from the
+ * default-locale file; title and keywords are translatable per file.
+ *
+ * Frontmatter is an intentionally small `key: value` subset (quoted strings,
+ * `[a, b]` inline lists, `- item` dash lists), not full YAML.
+ */
+export declare class FileDocumentation extends AbstractDocumentation {
+    private readonly dir;
+    private readonly defaultLocale;
+    private cache?;
+    private readonly changeCallbacks;
+    private watcher?;
+    private watchDebounce?;
+    constructor(options: FileDocumentationOptions);
+    list(locale?: string): Promise<DocMeta[]>;
+    get(id: string, locale?: string): Promise<DocContent | undefined>;
+    onChange(cb: (ids?: string[]) => void): void;
+    /** Drops the cache; the next call rescans the directory. */
+    reload(): void;
+    stopWatcher(): void;
+    private startWatcher;
+    private scan;
+    private scanDirectory;
+    /** `<id>.md` is the default locale, `<id>.<locale>.md` a translation. */
+    private parseFile;
+    private buildMeta;
+    /** Exact locale, else the default locale, else whatever exists. */
+    private pickTranslation;
+    private splitFrontmatter;
+    private parseFrontmatter;
+    private stringList;
+    private unquote;
+    private extractTitle;
+}