adminizer 5.0.0-build.2 → 5.0.0-build.21

package/lib/app-manager/AdminizerApp.d.ts

@@ -1,13 +1,16 @@
-import type { ActionType, AdminpanelConfig, AdminpanelIcon, ModelConfig } from "../../interfaces/adminpanelConfig";
-import type { AccessRightsToken, INotification, ModelResource } from "../../interfaces/types";
-import type { AbstractCatalog } from "../catalog/AbstractCatalog";
-import type { CatalogTemplateComponentResource } from "../catalog/CatalogTemplateComponentHandler";
-import type { AppModelAccess } from "../model/ModelHandler";
-import type { AbstractMediaManager } from "../media-manager/AbstractMediaManager";
-import type { Config, ControlType } from "../controls/Control";
-import type { User } from "../../models/User";
-import type { DataAccessor } from "../DataAccessor";
-import type { AbstractAiModelService } from "../ai-assistant/AbstractAiModelService";
+import type { ActionType, AdminpanelConfig, AdminpanelIcon, ModelConfig } from "../../interfaces/adminpanelConfig.js";
+import type { AccessRightsToken, INotification, ModelResource, PermissionContext } from "../../interfaces/types.js";
+import type { AbstractCatalog } from "../catalog/AbstractCatalog.js";
+import type { CatalogTemplateComponentResource } from "../catalog/CatalogTemplateComponentHandler.js";
+import type { AppModelAccess } from "../model/ModelHandler.js";
+import type { AbstractMediaManager } from "../media-manager/AbstractMediaManager.js";
+import type { Config, ControlType } from "../controls/Control.js";
+import type { User } from "../../models/User.js";
+import type { DataAccessor } from "../DataAccessor.js";
+import type { AbstractAiModelService } from "../ai-assistant/AbstractAiModelService.js";
+import type { AiAssistantUiMethod } from '../ai-assistant/AiAssistantUiMethodHandler.js';
+import type { AdminLink, AdminLinkTemplate } from '../admin-links/AdminLinkHandler.js';
+import type { AiAssistantAgentSkill } from '../ai-assistant/AiAssistantAgentSkillHandler.js';
 export type AppDisposer = () => void | Promise<void>;
 export type AppEventName = string | symbol;
 export type AppEventHandler<TPayload = any> = (payload: TPayload, runtime: AppRuntime) => void | Promise<void>;
@@ -127,9 +130,14 @@ export type AppWidgetResource = AppInfoWidgetResource | AppActionWidgetResource
 export interface AppRuntime {
     models: AppModelAccess;
     config: AppRuntimeConfig;
+    accessRights: AppRuntimeAccessRights;
     notifications: AppRuntimeNotifications;
     apps: AppRuntimeApps;
 }
+export interface AppRuntimeAccessRights {
+    hasPermission(token: string, user: User, context?: PermissionContext): Promise<boolean>;
+    getPermissionRights(token: string, user: User): string[] | null;
+}
 export interface AppRuntimeConfig {
     readonly routePrefix: string;
     getModelConfig(modelName: string): ModelConfig | undefined;
@@ -171,12 +179,28 @@ export interface AppAiAssistantContext {
     routePrefix: string;
     getModelResources(): ModelResource[];
     resolveModelResource(modelName: string): ModelResource | undefined;
-    hasPermission(token: string, user: User): boolean;
+    hasPermission(token: string, user: User): boolean | Promise<boolean>;
     createDataAccessor(modelResource: ModelResource, user: User, action: ActionType): DataAccessor;
+    /** UI tools available to this user, including methods registered by apps. */
+    getUiMethods(user: User): AiAssistantUiMethod[];
 }
 export interface AppAiAssistantResource {
     models: Array<(context: AppAiAssistantContext) => AbstractAiModelService | Promise<AbstractAiModelService>>;
 }
+export interface AppAiAssistantUiMethodResource extends AiAssistantUiMethod {
+    id: string;
+}
+export interface AppAiAssistantAgentSkillResource extends AiAssistantAgentSkill {
+}
+/** Skills contributed by an app. UI methods are browser skills; agent skills run on the server. */
+export interface AppSkills {
+    uiMethod(method: AppAiAssistantUiMethodResource): void;
+    agent(skill: AppAiAssistantAgentSkillResource): void;
+}
+export interface AppAdminLinkResource extends AdminLink {
+}
+export interface AppAdminLinkTemplateResource extends AdminLinkTemplate {
+}
 /**
  * Resource registration API provided while an app is being enabled.
  *
@@ -197,6 +221,11 @@ export interface AppSetupContext {
     model(model: AppModelResource): void;
     modelAccess(access: AppModelAccessResource): void;
     aiAssistant(resource: AppAiAssistantResource): void;
+    skills: AppSkills;
+    /** Register a standalone server page in the admin navigation and agent search. */
+    adminLink(link: AppAdminLinkResource): void;
+    /** Register a parametrized page (e.g. `/admin/orders/:id/invoice`) the assistant may open. */
+    adminLinkTemplate(template: AppAdminLinkTemplateResource): void;
     listener(event: AppEventName, handler: AppEventHandler): void;
 }
 /**

package/lib/app-manager/AppManager.d.ts

@@ -1,5 +1,5 @@
-import { Adminizer } from "../Adminizer";
-import { AbstractAdminizerApp, AppRuntime, AppRuntimeAppState } from "./AdminizerApp";
+import { Adminizer } from "../Adminizer.js";
+import { AbstractAdminizerApp, AppRuntime, AppRuntimeAppState } from "./AdminizerApp.js";
 export type AppState = AppRuntimeAppState;
 export declare class AppManager {
     private adminizer;

package/lib/app-manager/AppManager.js

@@ -1,6 +1,6 @@
 import { Adminizer } from "../Adminizer.js";
-import { AiAssistantHandler } from "../ai-assistant/AiAssistantHandler.js";
 import { DataAccessor } from "../DataAccessor.js";
+import { listModelResources, resolveModelResource } from "../../helpers/modelResourceHelper.js";
 class RuntimeAppSetupContext {
     adminizer;
     appName;
@@ -8,6 +8,8 @@ class RuntimeAppSetupContext {
     pendingModelRegistrations = [];
     pendingModelAccessRegistrations = [];
     pendingAiAssistantRegistrations = [];
+    pendingAiAssistantUiMethodRegistrations = [];
+    pendingAiAssistantAgentSkillRegistrations = [];
     pendingMediaManagerRegistrations = [];
     pendingCatalogRegistrations = [];
     configLayerIndex = 0;
@@ -15,7 +17,12 @@ class RuntimeAppSetupContext {
     constructor(adminizer, appName) {
         this.adminizer = adminizer;
         this.appName = appName;
+        this.skills = {
+            uiMethod: (method) => this.registerAiAssistantUiMethod(method),
+            agent: (skill) => this.registerAiAssistantAgentSkill(skill),
+        };
     }
+    skills;
     asset(asset) {
         const resourceId = `${this.appName}:${asset.id}`;
         const url = this.adminizer.assetHandler.register(this.appName, asset);
@@ -115,6 +122,32 @@ class RuntimeAppSetupContext {
     aiAssistant(resource) {
         this.pendingAiAssistantRegistrations.push(() => this.registerAiAssistant(resource));
     }
+    registerAiAssistantUiMethod(method) {
+        this.pendingAiAssistantUiMethodRegistrations.push(async () => {
+            this.adminizer.aiAssistantUiMethodHandler.register(method, this.appName);
+            this.disposers.push(() => this.adminizer.aiAssistantUiMethodHandler.unregister(method.id, this.appName));
+        });
+    }
+    registerAiAssistantAgentSkill(skill) {
+        this.pendingAiAssistantAgentSkillRegistrations.push(async () => {
+            this.adminizer.aiAssistantAgentSkillHandler.add(skill, this.appName);
+            this.disposers.push(() => {
+                this.adminizer.aiAssistantAgentSkillHandler.remove(skill.id, this.appName);
+            });
+        });
+    }
+    adminLink(link) {
+        const resourceId = this.adminizer.adminLinkHandler.add(link, this.appName);
+        this.disposers.push(() => {
+            this.adminizer.adminLinkHandler.remove(resourceId, this.appName);
+        });
+    }
+    adminLinkTemplate(template) {
+        const resourceId = this.adminizer.adminLinkHandler.addTemplate(template, this.appName);
+        this.disposers.push(() => {
+            this.adminizer.adminLinkHandler.removeTemplate(resourceId, this.appName);
+        });
+    }
     listener(event, handler) {
         const resourceId = `${this.appName}:${event.toString()}:${this.disposers.length + 1}`;
         const listener = (payload) => handler(payload, this.adminizer.appManager.createRuntime(this.appName));
@@ -137,28 +170,34 @@ class RuntimeAppSetupContext {
         await this.runRegistrationPhase(this.pendingModelRegistrations);
         await this.runRegistrationPhase(this.pendingModelAccessRegistrations);
         await this.runRegistrationPhase(this.pendingAiAssistantRegistrations);
+        await this.runRegistrationPhase(this.pendingAiAssistantUiMethodRegistrations);
+        await this.runRegistrationPhase(this.pendingAiAssistantAgentSkillRegistrations);
         await this.runRegistrationPhase(this.pendingMediaManagerRegistrations);
         await this.runRegistrationPhase(this.pendingCatalogRegistrations);
     }
     async registerAiAssistant(resource) {
-        const previousHandler = this.adminizer.aiAssistantHandler;
-        const handler = new AiAssistantHandler(this.adminizer);
+        // Models go into the shared handler instead of replacing it, so models
+        // registered directly by the host application keep working and several
+        // apps can contribute models at the same time.
+        const handler = this.adminizer.aiAssistantHandler;
         const context = this.createAiAssistantContext();
+        const modelIds = [];
         for (const modelFactory of resource.models) {
             const model = await modelFactory(context);
-            handler.registerModel(model);
+            handler.registerModel(model, this.appName);
+            modelIds.push(model.id);
         }
-        this.adminizer.aiAssistantHandler = handler;
         this.adminizer.emitter.emit("app:ai-assistant:registered", {
             appName: this.appName,
-            models: handler.getModels().map((model) => model.id),
+            models: modelIds,
         });
         this.disposers.push(() => {
-            if (this.adminizer.aiAssistantHandler === handler) {
-                this.adminizer.aiAssistantHandler = previousHandler;
+            for (const modelId of modelIds) {
+                this.adminizer.aiAssistantHandler.unregisterModel(modelId, this.appName);
             }
             this.adminizer.emitter.emit("app:ai-assistant:unregistered", {
                 appName: this.appName,
+                models: modelIds,
             });
         });
     }
@@ -347,52 +386,13 @@ class RuntimeAppSetupContext {
         return {
             runtime: this.adminizer.appManager.createRuntime(this.appName),
             routePrefix: this.adminizer.config.routePrefix,
-            getModelResources: () => this.getModelResources(),
-            resolveModelResource: (modelName) => this.resolveModelResource(modelName),
+            getModelResources: () => listModelResources(this.adminizer),
+            resolveModelResource: (modelName) => resolveModelResource(this.adminizer, modelName),
             hasPermission: (token, user) => this.adminizer.accessRightsHelper.hasPermission(token, user),
             createDataAccessor: (modelResource, user, action) => new DataAccessor(this.adminizer, user, modelResource, action),
+            getUiMethods: (user) => this.adminizer.aiAssistantUiMethodHandler.getAvailable(user),
         };
     }
-    getModelResources() {
-        const resources = [];
-        for (const [configName, configValue] of Object.entries(this.adminizer.config.models ?? {})) {
-            const normalizedConfig = this.normalizeModelConfig(configName, configValue);
-            const model = this.adminizer.modelHandler.model.get(normalizedConfig.model.toLowerCase());
-            if (!model) {
-                continue;
-            }
-            resources.push({
-                name: configName,
-                uri: `${this.adminizer.config.routePrefix}/model/${configName}`,
-                config: normalizedConfig,
-                model,
-            });
-        }
-        return resources;
-    }
-    resolveModelResource(modelName) {
-        const loweredName = modelName.toLowerCase();
-        return this.getModelResources().find((resource) => {
-            const modelId = resource.config.model?.toLowerCase();
-            return resource.name.toLowerCase() === loweredName || modelId === loweredName;
-        });
-    }
-    normalizeModelConfig(name, config) {
-        const baseConfig = {
-            model: name,
-            icon: "description",
-            title: name,
-            list: true,
-            add: true,
-            edit: true,
-            remove: true,
-            view: true,
-        };
-        if (typeof config === "boolean") {
-            return config ? baseConfig : { ...baseConfig, list: false, add: false, edit: false, remove: false, view: false };
-        }
-        return { ...baseConfig, ...config };
-    }
 }
 export class AppManager {
     adminizer;
@@ -505,6 +505,10 @@ export class AppManager {
                     return modelKey ? models[modelKey] : undefined;
                 },
             },
+            accessRights: {
+                hasPermission: async (token, user, context) => await this.adminizer.accessRightsHelper.hasPermission(token, user, context),
+                getPermissionRights: (token, user) => this.adminizer.accessRightsHelper.getPermissionRights(token, user),
+            },
             notifications: {
                 send: (notification) => this.adminizer.sendNotification(notification),
             },

package/lib/app-manager/AssetHandler.d.ts

@@ -1,5 +1,5 @@
-import type { Adminizer } from "../Adminizer";
-import type { AppAsset } from "./AdminizerApp";
+import type { Adminizer } from "../Adminizer.js";
+import type { AppAsset } from "./AdminizerApp.js";
 interface AssetRecord {
     id: string;
     appName: string;

package/lib/app-manager/ConfigLayerHandler.d.ts

@@ -1,5 +1,5 @@
-import type { Adminizer } from "../Adminizer";
-import type { AppConfigPatch } from "./AdminizerApp";
+import type { Adminizer } from "../Adminizer.js";
+import type { AppConfigPatch } from "./AdminizerApp.js";
 export interface ConfigLayerRecord {
     id: string;
     appName: string;

package/lib/app-manager/ControllerHandler.d.ts

@@ -1,5 +1,5 @@
-import type { Adminizer } from "../Adminizer";
-import type { AppController, AppControllerMethod } from "./AdminizerApp";
+import type { Adminizer } from "../Adminizer.js";
+import type { AppController, AppControllerMethod } from "./AdminizerApp.js";
 interface ControllerRecord {
     id: string;
     appName: string;

package/lib/catalog/AbstractCatalog.d.ts

@@ -1,4 +1,4 @@
-import { Adminizer } from "../Adminizer";
+import { Adminizer } from "../Adminizer.js";
 export interface CatalogStorageServices {
 }
 /**

package/lib/catalog/CatalogHandler.d.ts

@@ -1,4 +1,4 @@
-import { AbstractCatalog } from "./AbstractCatalog";
+import { AbstractCatalog } from "./AbstractCatalog.js";
 export interface CatalogRecord {
     id: string;
     appName: string;

package/lib/controls/ControlsHandler.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType } from "./Control";
+import { Control, ControlType } from "./Control.js";
 export declare class ControlsHandler {
     private controls;
     add(control: Control): void;

package/lib/controls/codeEditor/MonacoEditor.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Config, Path } from "../Control";
+import { Control, ControlType, Config, Path } from "../Control.js";
 export declare class MonacoEditor implements Control {
     readonly config: Config;
     readonly name: string;

package/lib/controls/geojsoneditor/GeoEditor.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Config, Path } from "../Control";
+import { Control, ControlType, Config, Path } from "../Control.js";
 export declare class GeoEditor implements Control {
     readonly config: Config;
     readonly name: string;

package/lib/controls/jsoneditor/JsonEditor.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Path, Config } from "../Control";
+import { Control, ControlType, Path, Config } from "../Control.js";
 export declare class JsonEditor implements Control {
     readonly config: Record<string, string | string[] | object | number | boolean>;
     readonly name: string;

package/lib/controls/markdown/ToastUiEditor.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Path, Config } from "../Control";
+import { Control, ControlType, Path, Config } from "../Control.js";
 export declare class ToastUiEditor implements Control {
     readonly config: Record<string, string | string[] | object | number | boolean>;
     readonly name: string;

package/lib/controls/table/Handsontable.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Config, Path } from "../Control";
+import { Control, ControlType, Config, Path } from "../Control.js";
 export declare class Handsontable implements Control {
     readonly config: Config;
     readonly name: string;

package/lib/controls/wysiwyg/CKeditor.d.ts

@@ -1,4 +1,4 @@
-import { Control, ControlType, Config, Path } from "../Control";
+import { Control, ControlType, Config, Path } from "../Control.js";
 export declare class CKeditor implements Control {
     readonly name: string;
     readonly type: ControlType;

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;
+    }
+}