diffwiki-core 0.4.0 → 0.5.0-rc.202607230329.fb70592

package/dist/index.d.cts

@@ -1,10 +1,20 @@
-type CollectionType = 'global' | 'repo';
+import { SearchDoc } from './bm25.cjs';
+export { RankableFields, rankDocs, tokenize } from './bm25.cjs';
+import { LogLevel, Logger } from '@logtape/logtape';
+
+type CollectionType = 'global' | 'repo' | 'external';
 interface CollectionEntry {
     name: string;
     type: CollectionType;
-    /** Absolute path to the collection's directory. */
+    /** Absolute path to the collection's content directory. */
     path: string;
     createdAt: string;
+    /** External only: stable git repo id (see `repoId`). Identity + dedupe key. */
+    id?: string;
+    /** External only: absolute repo root (branch/behind + open-at-root). */
+    repoRoot?: string;
+    /** External only: content dir relative to `repoRoot` (default "docs"). */
+    docsDir?: string;
 }
 interface Registry {
     version: number;
@@ -12,6 +22,7 @@ interface Registry {
 }
 interface Config {
     defaultCollection?: string;
+    defaultSearch?: string;
 }
 interface Article {
     title: string;
@@ -50,6 +61,142 @@ interface ArticleContent {
     /** Absolute path to the file on disk. */
     path: string;
 }
+type PluginKind = 'search';
+declare const NATIVE_ENGINE = "native";
+interface QueryOptions {
+    engine?: string;
+    collection?: string;
+    type?: string;
+    limit?: number;
+}
+interface QueryHit {
+    collection: string;
+    path: string;
+    title: string;
+    tags: string[];
+    snippet?: string;
+    score?: number;
+    docid?: string;
+}
+type DiagnosticLevel = 'ok' | 'warn' | 'error';
+interface Diagnostic {
+    level: DiagnosticLevel;
+    message: string;
+}
+interface PluginRecord {
+    name: string;
+    kind: PluginKind;
+    command: string[];
+    version?: string;
+    /** Capabilities cached at install/register time via the `describe` op. */
+    capabilities?: PluginCapabilities;
+    enabled: boolean;
+    managed?: boolean;
+}
+interface PluginRegistryFile {
+    version: number;
+    plugins: PluginRecord[];
+}
+/** Capabilities a plugin advertises via the `describe` op, cached in the registry. */
+interface PluginCapabilities {
+    /** Search types the plugin supports (e.g. `['keyword', 'semantic', 'hybrid']`). */
+    searchTypes: string[];
+    /** Whether the plugin supports filtering results by collection. */
+    collectionFilter: boolean;
+    /** Whether the plugin handles lifecycle events (article/collection mutations). */
+    events: boolean;
+}
+interface PluginReadiness {
+    toolInstalled: boolean;
+    modelsPresent: boolean;
+    indexBuilt: boolean;
+    docsIndexed: number;
+    embeddingsPending: number;
+    firstSearchCost: 'instant' | 'model-load' | 'model-download';
+}
+interface PluginHealth {
+    ready: boolean;
+    readiness?: PluginReadiness;
+    diagnostics: Diagnostic[];
+}
+interface SearchMode {
+    plugin: string;
+    type: string;
+    label: string;
+}
+type PluginEvent = 'collection-added' | 'collection-removed' | 'article-created' | 'article-updated' | 'article-removed';
+/**
+ * Host-side facade for a search plugin. Each method is backed by a one-shot
+ * subprocess invocation -- there is no persistent process and no `close()`.
+ */
+interface SearchProvider {
+    /** Plugin name. */
+    name: string;
+    /** Plugin capabilities (cached from the `describe` op). */
+    capabilities: PluginCapabilities;
+    /** Run a search query and return hits with absolute paths. */
+    handleSearch(term: string, collections: CollectionEntry[], opts?: QueryOptions): Promise<QueryHit[]>;
+    /** Rebuild the search index. Returns the number of documents indexed. */
+    reindex(collections: CollectionEntry[], opts?: {
+        embed?: boolean;
+    }): Promise<number>;
+    /** Emit a lifecycle event to the plugin (best-effort). */
+    emitEvent(event: PluginEvent, collection: string, relPath: string | undefined, collections: CollectionEntry[]): Promise<void>;
+    /** Check plugin health and readiness. */
+    health(collections: CollectionEntry[]): Promise<PluginHealth>;
+}
+interface NodeMeta {
+    branch?: string;
+    behind?: number;
+}
+interface TreeNode {
+    name: string;
+    title?: string;
+    path?: string;
+    children?: TreeNode[];
+    /** Set only on top-level collection rows: git branch/behind badge data. */
+    meta?: NodeMeta;
+}
+interface CollectionInfo {
+    name: string;
+    type: CollectionType;
+    path: string;
+    branch?: string;
+    behind?: number;
+}
+interface CollectionTree {
+    collection: CollectionInfo;
+    nodes: TreeNode[];
+}
+interface TocItem {
+    slug: string;
+    text: string;
+    depth: number;
+}
+interface DocData {
+    coll: string;
+    slug: string;
+    title: string;
+    tags: string[];
+    html: string;
+    toc: TocItem[];
+    path: string;
+}
+interface ListingEntry {
+    name: string;
+    title: string;
+    path: string;
+    isDir: boolean;
+}
+type PageData = ({
+    kind: 'doc';
+} & DocData) | {
+    kind: 'listing';
+    coll: string;
+    slug: string;
+    title: string;
+    entries: ListingEntry[];
+};
 
 /** Base class for all expected, user-facing diffwiki failures. */
 declare class DiffwikiError extends Error {
@@ -70,6 +217,14 @@ declare class ArticleNotFoundError extends DiffwikiError {
 declare class InvalidTargetError extends DiffwikiError {
     constructor(target: string, expected: string);
 }
+declare class PluginError extends DiffwikiError {
+}
+declare class WorktreeNotAllowedError extends DiffwikiError {
+    constructor(root: string);
+}
+declare class CollectionAlreadyAddedError extends DiffwikiError {
+    constructor(name: string);
+}
 
 /** Root of all global diffwiki state. Overridable via DIFFWIKI_HOME (used by tests). */
 declare function resolveHome(): string;
@@ -77,6 +232,8 @@ declare function registryPath(): string;
 declare function configPath(): string;
 declare function collectionsDir(): string;
 declare function collectionDir(name: string): string;
+declare function pluginsDir(): string;
+declare function pluginsRegistryPath(): string;
 
 declare function readConfig(): Promise<Config>;
 declare function writeConfig(config: Config): Promise<void>;
@@ -110,6 +267,7 @@ declare function serializeArticle(article: SerializableArticle): string;
 
 declare function listCollections(): Promise<CollectionEntry[]>;
 declare function findCollection(name: string): Promise<CollectionEntry | undefined>;
+declare function findCollectionById(id: string): Promise<CollectionEntry | undefined>;
 declare function createCollection(name: string): Promise<CollectionEntry>;
 /**
  * Remove a collection from the registry. For `global` collections we own the
@@ -147,26 +305,225 @@ interface InitOptions {
     wikiPath?: string;
 }
 declare function initRepoWiki(opts: InitOptions): Promise<CollectionEntry>;
+interface AddExternalOptions {
+    cwd: string;
+    /** Content dir relative to the repo root. Default "docs". */
+    docsDir?: string;
+}
+/**
+ * Register the git repo containing `cwd` as an `external` collection: title from
+ * the git remote (fallback repo dir), content dir `docs/` by default, git-only
+ * (auto `git init`), unique by repo id, and refusing linked worktrees.
+ */
+declare function addExternalCollection(opts: AddExternalOptions): Promise<CollectionEntry>;
+/**
+ * The registered collection the current directory belongs to: an external
+ * collection whose repo id matches, else any collection whose content path (or
+ * repoRoot) contains `cwd`. Undefined when cwd is outside every known collection.
+ */
+declare function resolveCwdCollection(cwd: string): Promise<CollectionEntry | undefined>;
+interface CollectionGitStatus {
+    branch?: string;
+    ahead: number;
+    behind: number;
+    hasUpstream: boolean;
+}
+/**
+ * Branch + upstream status for an external collection, from its repo root.
+ * Undefined for non-external collections or when git is unavailable (e.g. during
+ * static generation) — callers warn + omit.
+ */
+declare function collectionGitStatus(entry: CollectionEntry): Promise<CollectionGitStatus | undefined>;
 
-interface QueryHit {
-    collection: string;
-    path: string;
-    title: string;
-    tags: string[];
+/** Absolute working-tree root, or undefined when `cwd` is not inside a git repo. */
+declare function gitToplevel(cwd: string): Promise<string | undefined>;
+/**
+ * True when `cwd` sits inside a *linked* worktree (not the primary working tree).
+ * In the primary tree `--absolute-git-dir` and `--git-common-dir` resolve to the
+ * same directory; in a linked worktree the git-dir is `<common>/worktrees/<name>`.
+ */
+declare function isLinkedWorktree(cwd: string): Promise<boolean>;
+/** Short repo name from the `origin` remote URL (basename, `.git` stripped), or undefined. */
+declare function repoRemoteName(cwd: string): Promise<string | undefined>;
+/**
+ * A stable identifier for the repo, independent of checkout location. Prefers the
+ * root (first) commit hash — identical across clones/worktrees; falls back to the
+ * normalised origin URL when there is no commit yet. Undefined when neither exists.
+ */
+declare function repoId(cwd: string): Promise<string | undefined>;
+/** Current short branch name, or undefined (detached HEAD / not a repo). */
+declare function currentBranch(cwd: string): Promise<string | undefined>;
+interface UpstreamStatus {
+    branch?: string;
+    ahead: number;
+    behind: number;
+    hasUpstream: boolean;
 }
 /**
- * DUMMY search: case-insensitive substring match over title, filename, and tags.
- * Real QMD-based semantic search replaces this later.
+ * Ahead/behind counts of the current branch versus its upstream. `hasUpstream` is
+ * false when no upstream is configured (then ahead/behind are 0).
  */
-declare function query(term: string, collection?: string): Promise<QueryHit[]>;
+declare function upstreamStatus(cwd: string): Promise<UpstreamStatus>;
+/** Ensure `cwd` is inside a git repo, running `git init` if not. Returns the toplevel. */
+declare function ensureGitRepo(cwd: string): Promise<string>;
 
-type DiagnosticLevel = 'ok' | 'warn' | 'error';
-interface Diagnostic {
-    level: DiagnosticLevel;
-    message: string;
+/** Map core article nodes to UI nav nodes, assigning each its route path. */
+declare function toTreeNodes(coll: string, nodes: ArticleNode[]): TreeNode[];
+declare function buildCollections(): Promise<CollectionInfo[]>;
+declare function buildNavTree(): Promise<CollectionTree[]>;
+/** Resolve a route to a rendered doc or a generated directory listing (or null). */
+declare function resolvePage(coll: string, slug: string): Promise<PageData | null>;
+
+/**
+ * Search query routing.
+ *
+ * `query()` is the primary search entry point. It resolves the search engine
+ * (explicit opt, config default, first enabled plugin, or native BM25), runs
+ * the search, and falls back to native on plugin failure. The built-in native
+ * search is a zero-dependency BM25-ranked full-text search across title, body,
+ * tags, and collection name.
+ *
+ * @module
+ */
+
+/**
+ * Built-in JS-native search: BM25-ranked full-text search over an article's
+ * title, body, tags, and collection name -- across every registered collection's
+ * ABSOLUTE registry path (so in-repo wikis outside ~/.diffwiki are searched too).
+ * No `find`/OS shelling -- cross-platform and dependency-free.
+ *
+ * When `term` is empty, returns all articles unranked (no score) to preserve
+ * the "browse all" behavior.
+ */
+declare function nativeSearch(term: string, collections: CollectionEntry[], collection?: string): Promise<QueryHit[]>;
+/**
+ * Resolve the engine + type that `query()` would use when the caller passes no
+ * explicit engine/type. Reads cached capabilities from the registry -- no spawn.
+ */
+declare function resolveDefaultSearchMode(): Promise<{
+    engine: string;
+    type: string;
+}>;
+/**
+ * The result of a {@link search} call: the hits plus the metadata a host UI
+ * needs to tell the user WHICH engine ran and whether it silently degraded.
+ *
+ * `fellBackToNative` is true whenever the resolved engine could not serve the
+ * search (no provider, or `handleSearch` threw) and native BM25 produced these
+ * hits instead. `error`, when set, is the captured message from the failing
+ * engine — a failing engine is thus distinguishable from an engine that
+ * legitimately found zero results.
+ */
+interface SearchOutcome {
+    /** The hits to display (from the engine, or from native on fallback). */
+    hits: QueryHit[];
+    /** The engine that was resolved and attempted (may differ from what produced `hits`). */
+    engine: string;
+    /** True when native BM25 produced `hits` because the engine failed/was unavailable. */
+    fellBackToNative: boolean;
+    /** The captured failure message from the engine, when it errored. */
+    error?: string;
 }
+/**
+ * Search articles via the resolved search engine, surfacing engine failures.
+ *
+ * Routing precedence: explicit `opts.engine` -> `config.defaultSearch` ->
+ * first enabled plugin -> native BM25.
+ *
+ * On ANY engine failure (no provider, or `handleSearch` throws) the error
+ * message is CAPTURED, native BM25 is run as a fallback, and the outcome
+ * reports `{ fellBackToNative: true, error }`. On success it reports
+ * `{ fellBackToNative: false }` with the engine's hits. This lets callers
+ * distinguish "the engine broke" from "the engine found nothing".
+ */
+declare function search(term: string, opts?: QueryOptions): Promise<SearchOutcome>;
+/**
+ * Search articles via the resolved search engine (native fallback on plugin
+ * failure). A thin wrapper over {@link search} that returns just the hits;
+ * engine errors are swallowed. Use {@link search} to surface those errors.
+ *
+ * Routing precedence: explicit `opts.engine` -> `config.defaultSearch` ->
+ * first enabled plugin -> native BM25.
+ */
+declare function query(term: string, opts?: QueryOptions): Promise<QueryHit[]>;
+
+/**
+ * Build the search index: one {@link SearchDoc} per article, carrying routing
+ * metadata (collection/slug/title/tags) AND the pre-tokenized fields BM25 ranks.
+ * The static exporter serialises this to `search-index.json`; the browser ranks it
+ * with the shared `rankDocs` (same algorithm as the server's native search), so
+ * keyword search works fully offline on the static site.
+ */
+declare function buildSearchIndex(collection?: string): Promise<SearchDoc[]>;
+
+/**
+ * Diagnostics and health checks.
+ *
+ * `doctor()` inspects the diffwiki home directory, registry, collections,
+ * config, and every registered plugin to produce a list of human-readable
+ * diagnostics at ok/warn/error severity levels.
+ *
+ * @module
+ */
+
+/** Run all diagnostics and return the results. */
 declare function doctor(): Promise<Diagnostic[]>;
 
+/**
+ * Centralized logging for diffwiki host code, built on LogTape.
+ *
+ * diffwiki-core (and the plugin SDK) are LIBRARIES: they obtain loggers via
+ * {@link getLogger} and emit records, but they NEVER call LogTape's
+ * `configure()`/`configureSync()`. Per the LogTape library-vs-app pattern, a
+ * library stays silent until the surrounding APPLICATION (the CLI or the web
+ * app) installs sinks. `getLogger` called before any `configure` is a safe
+ * no-op, so importing this module has no side effects.
+ *
+ * All diffwiki loggers live under the `['diffwiki', ...]` category so an app can
+ * route the whole tree with a single logger config entry. Plugin diagnostics
+ * are forwarded under `['diffwiki', 'plugin', <name>]` (see `plugins/host.ts`).
+ *
+ * [DEVIATION] The task brief lists the level name `warn`, but the installed
+ * `@logtape/logtape` (2.2.4) names that level `warning` (levels are
+ * `trace|debug|info|warning|error|fatal`). We follow the installed types:
+ * {@link DiffwikiLogLevel} uses `warning`, and {@link resolveLogLevel} defaults
+ * to `warning`. Note LogTape's Logger METHOD for that level is still `.warn()`.
+ *
+ * @module
+ */
+
+/**
+ * A diffwiki log level. Identical to LogTape's `LogLevel`
+ * (`trace|debug|info|warning|error|fatal`); re-exported so host and app code can
+ * refer to it without importing LogTape directly.
+ */
+type DiffwikiLogLevel = LogLevel;
+/**
+ * Get a diffwiki logger under the shared `['diffwiki', ...]` category root.
+ *
+ * This is a thin wrapper over LogTape's `getLogger`. It does NOT configure
+ * LogTape — libraries stay silent until an app calls `configure()`. Passing a
+ * string scope is sugar for a single-element category array.
+ *
+ * @param scope - A scope name (e.g. `'query'`) or a nested category path
+ *   (e.g. `['plugin', 'diffwiki-qmd']`).
+ * @returns A LogTape {@link Logger} under `['diffwiki', ...scope]`.
+ */
+declare function getLogger(scope: string | string[]): Logger;
+/**
+ * Resolve the diffwiki log level from the environment.
+ *
+ * Reads `DIFFWIKI_LOG` (one of `trace|debug|info|warning|error|fatal`, case
+ * insensitive) and returns it, falling back to the documented default
+ * (`warning`) when unset or unrecognized. Apps use this to pick the app-level
+ * sink's `lowestLevel` at startup.
+ *
+ * @param env - The environment to read (defaults to `process.env`). Injectable
+ *   for tests.
+ * @returns The resolved {@link DiffwikiLogLevel}.
+ */
+declare function resolveLogLevel(env?: NodeJS.ProcessEnv): DiffwikiLogLevel;
+
 /**
  * Build a nested ArticleNode[] from a flat list of relative file paths.
  * Pure — no I/O. Directories become branches; files become leaves whose `slug`
@@ -186,12 +543,6 @@ declare function listArticleTree(coll: string): Promise<ArticleNode[]>;
  */
 declare function readArticle(coll: string, slug: string): Promise<ArticleContent>;
 
-/** A heading extracted for the table of contents (h2/h3). */
-interface TocItem {
-    slug: string;
-    text: string;
-    depth: number;
-}
 /** The result of rendering an article body to HTML. */
 interface RenderedArticle {
     /** Fully-rendered, Shiki-highlighted HTML — mounted directly on the client (no eval). */
@@ -208,4 +559,166 @@ interface RenderedArticle {
  */
 declare function renderArticle(body: string): Promise<RenderedArticle>;
 
-export { type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, type CollectionEntry, CollectionExistsError, CollectionNotFoundError, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type InitOptions, InvalidTargetError, NoDefaultCollectionError, type ParsedArticle, type QueryHit, REPO_CONFIG_FILE, type Registry, type RenderedArticle, type RepoConfig, type SerializableArticle, type TocItem, addTags, buildArticleTree, collectionDir, collectionsDir, configPath, createArticle, createCollection, doctor, findCollection, getConfigValue, initRepoWiki, listArticleTree, listCollections, parseAddTarget, parseArticle, parsePathTarget, query, readArticle, readConfig, readRegistry, readRepoConfig, registerCollection, registryPath, removeArticle, removeCollection, removeTags, renderArticle, resolveHome, serializeArticle, setConfigValue, setTags, slugify, unregisterCollection, updateArticleBody, writeConfig, writeRegistry };
+/**
+ * Host-side plugin invocation and search-provider loading.
+ *
+ * `invokePlugin()` spawns a plugin subprocess, writes a single JSON request to
+ * stdin (then closes it), reads the JSON response from stdout, and lets the
+ * process exit. Progress/diagnostic logs arrive on STDERR as structured
+ * `{log:{level,message}}` JSON lines; the host forwards each to a LogTape logger
+ * scoped by plugin name and keeps the raw stderr for on-error context.
+ *
+ * `loadSearchProvider()` returns a `SearchProvider` backed by one-shot
+ * invocations — each method call spawns the plugin fresh. `listSearchModes()`
+ * reads cached capabilities from the registry rather than spawning each plugin.
+ *
+ * @module
+ */
+
+/**
+ * Load a search provider backed by one-shot subprocess invocations. Each method
+ * on the returned `SearchProvider` spawns the plugin binary, sends one JSON
+ * request, and reads the response. Returns `null` if no matching enabled plugin
+ * is found or the plugin fails its `describe` handshake.
+ *
+ * @param name - Optional plugin name. If omitted, the first enabled search plugin is used.
+ */
+declare function loadSearchProvider(name?: string): Promise<SearchProvider | null>;
+/**
+ * List all available search modes, starting with native BM25. Reads cached
+ * capabilities from the plugin registry rather than spawning each plugin.
+ * Plugins without cached capabilities (registered before the SDK refactor) are
+ * skipped -- re-register to populate them.
+ */
+declare function listSearchModes(): Promise<SearchMode[]>;
+
+/**
+ * Plugin lifecycle management.
+ *
+ * Handles installing (from npm), registering (from an existing binary),
+ * removing, and listing plugins. Installation and registration both run
+ * a `describe` op to validate the plugin and cache its capabilities in
+ * the registry, then a best-effort `setup` op to provision the plugin.
+ *
+ * @module
+ */
+
+/** Create the managed plugin root (an isolated npm project) and return its path. */
+declare function ensurePluginRoot(): Promise<string>;
+/** One provisioning step reported by a plugin's `setup` op. */
+interface SetupStep {
+    step: string;
+    ok: boolean;
+    message?: string;
+}
+/** The captured result of a plugin's `setup` op. */
+interface SetupOutcome {
+    /** Whether the plugin provisioned to a ready-to-search state. */
+    ready: boolean;
+    /** Per-step results (e.g. verify-qmd, add-collections, index). */
+    steps: SetupStep[];
+}
+/** The result of {@link installPlugin}: the registered record + the setup outcome (if setup ran). */
+interface InstallOutcome {
+    record: PluginRecord;
+    /** The setup result, or undefined when setup was skipped (`opts.setup === false`). */
+    setup?: SetupOutcome;
+}
+/**
+ * Install an npm spec into the managed root, register the discovered search bin,
+ * run a `describe` to validate and cache capabilities, then (unless `opts.setup
+ * === false`) run the plugin's `setup` op so the user lands on a working search.
+ */
+declare function installPlugin(spec: string, opts?: {
+    setup?: boolean;
+    prefetchModels?: boolean;
+}): Promise<InstallOutcome>;
+/**
+ * Register an existing executable as a search plugin. Validates by running
+ * `describe`, caches capabilities, then runs `setup` best-effort.
+ */
+declare function registerPlugin(name: string, command: string[]): Promise<PluginRecord>;
+/** Uninstall a managed plugin's package and deregister it. */
+declare function removePlugin(name: string): Promise<void>;
+/** List every registered plugin, marking whether it currently responds to `describe`. */
+declare function listPlugins(): Promise<Array<PluginRecord & {
+    spawnable: boolean;
+}>>;
+
+/**
+ * Plugin lifecycle event emission.
+ *
+ * Fires a lifecycle event at the active search plugin -- best-effort and
+ * non-blocking. diffwiki emits events on every content mutation (article
+ * create/update/remove, collection add/remove). A plugin's `onEvent`
+ * handler can self-manage in response (e.g. incremental reindex).
+ *
+ * Events are an optimisation, not the correctness path: the mtime-staleness
+ * lazy reindex on `search` remains the guarantee, so a dropped event only
+ * costs a later lazy rebuild, never wrong results.
+ *
+ * @module
+ */
+
+/**
+ * Emit a lifecycle event to the active search plugin.
+ *
+ * This function is designed to be called fire-and-forget: `void emitPluginEvent(...)`.
+ * It only invokes the plugin when the plugin has `capabilities.events === true`.
+ * Every error is swallowed -- a slow or absent plugin can neither stall nor
+ * fail a content mutation.
+ */
+declare function emitPluginEvent(event: PluginEvent, collection: string, relPath?: string): Promise<void>;
+
+/**
+ * Known plugin catalog.
+ *
+ * A built-in directory of official diffwiki plugins that users can install.
+ * This is discovery only -- installing goes through `installPlugin(spec)`.
+ *
+ * @module
+ */
+
+/**
+ * A plugin diffwiki knows about and can recommend — the "app store" catalog.
+ * Discovery only; installing still goes through `installPlugin(spec)`.
+ */
+interface KnownPlugin {
+    name: string;
+    kind: PluginKind;
+    /** The argument for `diffwiki plugin install <spec>` (the npm package name). */
+    spec: string;
+    description: string;
+    /** External tool the plugin drives, shown as a prerequisite hint. */
+    requires?: string;
+}
+/** Return a copy of the known/official plugins available to install. */
+declare function listAvailablePlugins(): KnownPlugin[];
+
+/**
+ * Plugin registry persistence.
+ *
+ * Manages the `~/.diffwiki/plugins.json` file that stores plugin records.
+ * Each record includes the plugin's name, kind, command argv, version,
+ * cached capabilities (populated at install/register time via `describe`),
+ * and enabled/managed flags.
+ *
+ * @module
+ */
+
+/** Read the plugin registry from disk. Returns an empty registry if the file does not exist. */
+declare function readPluginRegistry(): Promise<PluginRegistryFile>;
+/** Write the plugin registry to disk, creating the home directory if needed. */
+declare function writePluginRegistry(registry: PluginRegistryFile): Promise<void>;
+/** Insert or replace the plugin record with the same name. */
+declare function upsertPlugin(record: PluginRecord): Promise<void>;
+/** Remove a plugin record by name. */
+declare function deregisterPlugin(name: string): Promise<void>;
+/** List all enabled plugins of a given kind. */
+declare function listEnabledPlugins(kind: PluginKind): Promise<PluginRecord[]>;
+/** Find a single enabled plugin by kind and optionally by name. Returns the first if name is omitted. */
+declare function findEnabledPlugin(kind: PluginKind, name?: string): Promise<PluginRecord | undefined>;
+/** Find a plugin record by name (regardless of enabled state). */
+declare function findPluginRecord(name: string): Promise<PluginRecord | undefined>;
+
+export { type AddExternalOptions, type Article, type ArticleContent, type ArticleNode, ArticleNotFoundError, CollectionAlreadyAddedError, type CollectionEntry, CollectionExistsError, type CollectionGitStatus, type CollectionInfo, CollectionNotFoundError, type CollectionTree, type CollectionType, type Config, type Diagnostic, type DiagnosticLevel, DiffwikiError, type DiffwikiLogLevel, type DocData, type InitOptions, type InstallOutcome, InvalidTargetError, type KnownPlugin, type ListingEntry, NATIVE_ENGINE, NoDefaultCollectionError, type NodeMeta, type PageData, type ParsedArticle, type PluginCapabilities, PluginError, type PluginEvent, type PluginHealth, type PluginKind, type PluginReadiness, type PluginRecord, type PluginRegistryFile, type QueryHit, type QueryOptions, REPO_CONFIG_FILE, type Registry, type RenderedArticle, type RepoConfig, SearchDoc, type SearchMode, type SearchOutcome, type SearchProvider, type SerializableArticle, type SetupOutcome, type SetupStep, type TocItem, type TreeNode, type UpstreamStatus, WorktreeNotAllowedError, addExternalCollection, addTags, buildArticleTree, buildCollections, buildNavTree, buildSearchIndex, collectionDir, collectionGitStatus, collectionsDir, configPath, createArticle, createCollection, currentBranch, deregisterPlugin, doctor, emitPluginEvent, ensureGitRepo, ensurePluginRoot, findCollection, findCollectionById, findEnabledPlugin, findPluginRecord, getConfigValue, getLogger, gitToplevel, initRepoWiki, installPlugin, isLinkedWorktree, listArticleTree, listAvailablePlugins, listCollections, listEnabledPlugins, listPlugins, listSearchModes, loadSearchProvider, nativeSearch, parseAddTarget, parseArticle, parsePathTarget, pluginsDir, pluginsRegistryPath, query, readArticle, readConfig, readPluginRegistry, readRegistry, readRepoConfig, registerCollection, registerPlugin, registryPath, removeArticle, removeCollection, removePlugin, removeTags, renderArticle, repoId, repoRemoteName, resolveCwdCollection, resolveDefaultSearchMode, resolveHome, resolveLogLevel, resolvePage, search, serializeArticle, setConfigValue, setTags, slugify, toTreeNodes, unregisterCollection, updateArticleBody, upsertPlugin, upstreamStatus, writeConfig, writePluginRegistry, writeRegistry };