diffwiki-core 0.14.0 → 0.15.0

package/dist/frontmatter-ghMCpLNf.d.cts

@@ -0,0 +1,585 @@
+/**
+ * Wire-protocol and SDK types shared by the plugin authoring SDK (`sdk.ts`) and
+ * re-exported to plugin authors via the `diffwiki-core/plugin` subpath.
+ *
+ * @module
+ */
+/** Log severity levels for plugin diagnostic messages. */
+type LogLevel = 'info' | 'warn' | 'error';
+/** A logging function that plugins use to emit diagnostic messages to stderr. */
+type PluginLogFn = (level: LogLevel, message: string) => void;
+/** A wire-format collection as received in handler params. */
+interface WireCollection {
+    name: string;
+    path: string;
+}
+/** Diagnostic entry returned by the health handler. */
+interface WireDiagnostic {
+    level: 'ok' | 'warn' | 'error';
+    message: string;
+}
+/** Readiness details returned by the health handler. */
+interface WireReadiness {
+    toolInstalled: boolean;
+    modelsPresent: boolean;
+    indexBuilt: boolean;
+    docsIndexed: number;
+    embeddingsPending: number;
+    firstSearchCost: 'instant' | 'model-load' | 'model-download';
+}
+/** A single search hit returned by the search handler. */
+interface SearchHandlerHit {
+    collection: string;
+    relPath: string;
+    title: string;
+    snippet?: string;
+    score?: number;
+    docid?: string;
+    tags?: string[];
+    /** Verbatim engine chunk (unsanitized), surfaced in the search UI's inspection popover. */
+    rawChunk?: string;
+    /** The chunk cleaned to plain text, untruncated (full form for the popover). */
+    cleanedChunk?: string;
+    /** Absolute source line the chunk starts at, when the engine reports it. */
+    line?: number;
+    /** True when `snippet` is a body-preview fallback rather than the cleaned chunk. */
+    snippetFromBody?: boolean;
+}
+/** Result shape returned by the search handler. */
+interface SearchHandlerResult {
+    hits: SearchHandlerHit[];
+}
+/** Result shape returned by the index handler. */
+interface IndexHandlerResult {
+    indexed: number;
+}
+/** Result shape returned by the health handler. */
+interface HealthHandlerResult {
+    ready: boolean;
+    readiness?: WireReadiness;
+    diagnostics: WireDiagnostic[];
+}
+/** Result shape returned by the setup handler. */
+interface SetupHandlerResult {
+    ready: boolean;
+    steps?: Array<{
+        step: string;
+        ok: boolean;
+        message?: string;
+    }>;
+}
+/** Result shape returned by the onEvent handler. */
+interface EventHandlerResult {
+    accepted: boolean;
+}
+/** Parameters passed to the search handler. */
+/** A caller-supplied, pre-expanded query variant passed through to the engine. */
+interface SearchExpansion {
+    type: 'lex' | 'vec' | 'hyde';
+    query: string;
+}
+interface SearchParams {
+    term: string;
+    collections: WireCollection[];
+    collection?: string;
+    type?: string;
+    limit?: number;
+    /** Pre-expanded query variants from an upstream LLM; engines that support
+     *  structured search use these instead of expanding `term` themselves. */
+    expansions?: SearchExpansion[];
+}
+/** Parameters passed to the index handler. */
+interface IndexParams {
+    collections: WireCollection[];
+    embed?: boolean;
+}
+/** Parameters passed to the setup handler. */
+interface SetupParams {
+    collections: WireCollection[];
+    embed?: boolean;
+    prefetchModels?: boolean;
+}
+/** Parameters passed to the onEvent handler. */
+interface EventParams {
+    event: string;
+    collection: WireCollection;
+    relPath?: string;
+    collections: WireCollection[];
+}
+/** Parameters passed to the health handler. */
+interface HealthParams {
+    collections: WireCollection[];
+}
+/** Plugin capabilities advertised during describe. */
+interface PluginCapabilities$1 {
+    searchTypes: string[];
+    collectionFilter: boolean;
+    events: boolean;
+}
+/**
+ * An external executable a plugin needs at runtime (e.g. `qmd`, `rg`).
+ *
+ * Declaring a dependency lets the plugin resolve the binary uniformly and lets
+ * `setup`/`health` report it. When `npm` is set, the package is expected to be a
+ * regular dependency in the plugin's own `package.json`, so `diffwiki plugin
+ * install` pulls it transitively and {@link ResolvedDependency} finds its bin in
+ * the plugin's `node_modules` — no global install required.
+ */
+interface PluginDependency {
+    /** The executable name, e.g. `'qmd'` or `'rg'`. */
+    command: string;
+    /** npm package that provides the executable; when set, the local bin is preferred over PATH. */
+    npm?: string;
+    /** Human-facing manual install hint, shown when the dependency is unresolved. */
+    hint?: string;
+}
+/**
+ * The outcome of resolving a {@link PluginDependency}: the argv prefix to invoke
+ * it, plus where it was found. `command` is null when unresolved.
+ */
+interface ResolvedDependency {
+    dependency: PluginDependency;
+    /** Argv prefix to spawn the tool, or null if unresolved. */
+    command: string[] | null;
+    /** How it resolved: the npm-provided local bin, the system PATH, or nowhere. */
+    source: 'npm' | 'path' | 'missing';
+}
+/** The handler functions a plugin provides. */
+interface PluginHandlers {
+    /** Handle a search request. Required for search plugins. */
+    search: (params: SearchParams, log: PluginLogFn) => Promise<SearchHandlerResult> | SearchHandlerResult;
+    /** Handle a reindex request. Optional -- defaults to `{ indexed: 0 }`. */
+    index?: (params: IndexParams, log: PluginLogFn) => Promise<IndexHandlerResult> | IndexHandlerResult;
+    /** Handle an initial setup/provisioning request. Optional -- defaults to `{ ready: true }`. */
+    setup?: (params: SetupParams, log: PluginLogFn) => Promise<SetupHandlerResult> | SetupHandlerResult;
+    /** Handle a lifecycle event (article/collection add/update/remove). Optional. */
+    onEvent?: (params: EventParams, log: PluginLogFn) => Promise<EventHandlerResult> | EventHandlerResult;
+    /** Report plugin health and readiness. Optional. */
+    health?: (params: HealthParams, log: PluginLogFn) => Promise<HealthHandlerResult> | HealthHandlerResult;
+}
+/** The definition object passed to `definePlugin()`. */
+interface PluginDefinition {
+    /** Plugin name (must match the name used in `diffwiki plugin register`). */
+    name: string;
+    /** Plugin kind. Currently only `'search'` is supported. */
+    kind: 'search';
+    /** Semantic version string. */
+    version?: string;
+    /** Plugin capabilities advertised to the host. */
+    capabilities: PluginCapabilities$1;
+    /** External executables the plugin needs. Reported via `describe` and resolvable via {@link ResolvedDependency}. */
+    dependencies?: PluginDependency[];
+    /** Handler functions for each operation. */
+    handlers: PluginHandlers;
+}
+/** The object returned by `definePlugin()`. Call `.run()` to serve one request. */
+interface DefinedPlugin {
+    /** The plugin definition. */
+    definition: PluginDefinition;
+    /**
+     * Read one JSON request from stdin, dispatch to the matching handler, write
+     * the JSON response to stdout, and exit. Exit code 0 on success, 1 on
+     * handler error. Logs go to stderr.
+     */
+    run: () => void;
+}
+/** Options for `runProcess` and `runProcessJson`. */
+interface RunProcessOptions {
+    /** Environment variables for the child process. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Timeout in milliseconds. No timeout by default. */
+    timeout?: number;
+}
+
+/** Audience axis — who an article is for. Private is never published; system is diffwiki-internal (hidden unless `showSystem`). Missing/invalid → 'public'. */
+type Audience = 'public' | 'private' | 'system';
+/** Lifecycle axis — readiness. Draft is unpublished; deprecated is superseded. Missing/invalid → 'published'. */
+type PublishStatus = 'draft' | 'published' | 'deprecated';
+type CollectionType = 'global' | 'repo' | 'external';
+interface CollectionEntry {
+    name: string;
+    type: CollectionType;
+    /** Absolute path to the collection's content directory. */
+    path: string;
+    createdAt: string;
+    /** Marks a diffwiki-internal collection (e.g. `transcripts`). 'system' hides it unless `showSystem`. */
+    audience?: Audience;
+    /** 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;
+    collections: CollectionEntry[];
+}
+interface Config {
+    defaultCollection?: string;
+    defaultSearch?: string;
+    /** Editor command used by `diffwiki edit` (e.g. "code -w", "hx"). Falls back to $VISUAL/$EDITOR. */
+    editor?: string;
+    /** Reveal system-audience content in search, nav, and the UI (default: false). Stored as boolean or "true". */
+    showSystem?: boolean;
+}
+interface Article {
+    title: string;
+    tags: string[];
+    /** Absolute path to the article file. */
+    path: string;
+    collection: string;
+}
+interface RepoConfig {
+    collection: string;
+    /** Path to the wiki directory, relative to the repo root. */
+    path: string;
+}
+/** A home-page card (VitePress-style): icon + title + subtitle linking into the site. */
+interface HomeCard {
+    /** Icon name from the curated home-card icon set; unknown/missing → no icon. */
+    icon?: string;
+    title: string;
+    subtitle?: string;
+    /** In-site path, e.g. "/getting-started". */
+    link: string;
+}
+/** Home-page customization from `diffwiki.yaml` → `site.home`. */
+interface SiteHome {
+    /** Line shown under the wordmark on the home page. */
+    tagline?: string;
+    /** Cards rendered below the search bar. */
+    cards?: HomeCard[];
+}
+/** Footer copyright notice from `diffwiki.yaml` → `site.copyright`. Applies to the
+ *  site/software; article CONTENT copyright stays with its respective authors. */
+interface SiteCopyright {
+    /** The full notice text, e.g. "© 2026 Acme, Inc." */
+    text: string;
+    /** Optional URL — renders the notice as a link. */
+    url?: string;
+}
+/** Site-level config from `diffwiki.yaml` → `site`. The diffwiki logo + wordmark
+ *  are fixed branding and deliberately not configurable. */
+interface SiteConfig {
+    /** Project repository URL for the top-nav GitHub link. */
+    repo?: string;
+    /** Footer copyright notice; no default — the footer is empty when unset. */
+    copyright?: SiteCopyright;
+    home?: SiteHome;
+}
+/** One collection declared in `diffwiki.yaml` → `collections[]`. */
+interface ProjectCollection {
+    name: string;
+    /** Content directory, relative to the project root. */
+    path: string;
+    /** Optional display order (ascending). Unset sorts after ordered ones, keeping list order. */
+    order?: number;
+}
+/** Optional recall/search context from `diffwiki.yaml` → `context`. */
+interface ProjectContext {
+    /** Collection names recall/search should filter to by default. */
+    collections: string[];
+}
+/**
+ * Normalised repo-root `diffwiki.yaml`. The extended form carries `site` +
+ * `collections[]`; the legacy `{ collection, path }` form is folded into a
+ * one-element `collections` by the parser.
+ */
+interface ProjectConfig {
+    site?: SiteConfig;
+    collections: ProjectCollection[];
+    context?: ProjectContext;
+}
+/** A node in a collection's article tree. Branches have `children`; leaves have `slug`. */
+interface ArticleNode {
+    /** Segment label — dir name for branches, filename-without-ext for leaves. */
+    name: string;
+    /** Display title — frontmatter `title` (leaf) or the folder's index title, else `name`. */
+    title?: string;
+    /**
+     * Path within the collection, without extension, e.g. "guide/setup". Set on
+     * leaves (the article) and on branches (the folder, navigable to its index).
+     */
+    slug?: string;
+    /** Audience, set only when 'private' (omitted for 'public'). */
+    audience?: Audience;
+    /** Lifecycle status, set only when 'draft' (omitted for 'published'). */
+    status?: PublishStatus;
+    /** Frontmatter `order` — nav sort within a folder (ascending; unset sorts after). */
+    order?: number;
+    /** Branch only: nested nodes. */
+    children?: ArticleNode[];
+}
+/** A resolved article's content, returned by `readArticle`. */
+interface ArticleContent {
+    coll: string;
+    slug: string;
+    title: string;
+    tags: string[];
+    /** Audience from frontmatter ('public' when absent). */
+    audience: Audience;
+    /** Lifecycle status from frontmatter ('published' when absent). */
+    status: PublishStatus;
+    /** Frontmatter-stripped body (md/mdx). */
+    body: string;
+    /** Absolute path to the file on disk. */
+    path: string;
+    /**
+     * True when the resolved file is a folder-index page (`<slug>/index.md` or
+     * `<slug>/README.md`) rather than a leaf `<slug>.md`. The route slug is the
+     * same for both, so this flag is needed to resolve folder-local relative
+     * links against the article's own folder.
+     */
+    isIndex: boolean;
+}
+type PluginKind = 'search';
+declare const NATIVE_ENGINE = "native";
+
+interface QueryOptions {
+    engine?: string;
+    /** Limit to a single collection name, or a set of names. Empty/undefined = all. */
+    collection?: string | string[];
+    type?: string;
+    limit?: number;
+    /** Reveal system-audience content (default: config `showSystem`, else false). */
+    showSystem?: boolean;
+    /**
+     * Pre-expanded query variants (from a smarter upstream LLM). When present, an
+     * engine that supports structured search should use these instead of expanding
+     * the bare term itself. The `term` is still passed as ranking intent.
+     */
+    expansions?: SearchExpansion[];
+}
+interface QueryHit {
+    collection: string;
+    path: string;
+    title: string;
+    tags: string[];
+    snippet?: string;
+    score?: number;
+    docid?: string;
+    /** Verbatim engine chunk (unsanitized) for the search UI's inspection popover. */
+    rawChunk?: string;
+    /** The chunk cleaned to plain text, untruncated (full form for the popover). */
+    cleanedChunk?: string;
+    /** Absolute source line the chunk starts at, when the engine reports it. */
+    line?: number;
+    /** True when `snippet` is a body-preview fallback rather than the cleaned chunk. */
+    snippetFromBody?: boolean;
+}
+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;
+    /** Audience; present only when 'private' (drives the sidebar lock). */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft' (drives the sidebar DRAFT tag). */
+    status?: PublishStatus;
+    children?: TreeNode[];
+    /** Set only on top-level collection rows: git branch/behind badge data. */
+    meta?: NodeMeta;
+}
+interface CollectionInfo {
+    name: string;
+    type: CollectionType;
+    path: string;
+    /** Display title from the collection's root index page frontmatter; falls back to `name` in the UI. */
+    title?: string;
+    branch?: string;
+    behind?: number;
+    /** Audience from the collection's root index page; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status from the collection's root index page; present only when 'draft'. */
+    status?: PublishStatus;
+}
+interface CollectionTree {
+    collection: CollectionInfo;
+    nodes: TreeNode[];
+}
+interface TocItem {
+    slug: string;
+    text: string;
+    depth: number;
+}
+interface DocData {
+    coll: string;
+    slug: string;
+    title: string;
+    tags: string[];
+    /** Audience; present only when 'private'. */
+    audience?: Audience;
+    /** Lifecycle status; present only when 'draft'. */
+    status?: PublishStatus;
+    html: string;
+    toc: TocItem[];
+    path: string;
+    /** ISO-8601 creation date, sourced from git history / filesystem (not frontmatter). */
+    created?: string;
+    /** ISO-8601 last-update date, sourced from git history / filesystem (not frontmatter). */
+    updated?: string;
+    /** Local knowledge-graph neighbourhood for this page (this node + its direct links). */
+    graph: LocalGraph;
+}
+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[];
+};
+/**
+ * One node in the knowledge graph. Two kinds:
+ * - `article` — a wiki page. `id` is `"<coll>/<slug>"`, with `coll`/`slug` set.
+ * - `tag` — an Obsidian-style tag hub. `id` is `"tag:<name>"`; `coll`/`slug` are
+ *   empty (a tag is not a page, so clicking it never navigates), `title` is `#name`.
+ */
+interface GraphNode {
+    id: string;
+    kind: 'article' | 'tag';
+    coll: string;
+    slug: string;
+    title: string;
+}
+/**
+ * A graph edge. `kind` distinguishes an explicit hyperlink between two articles
+ * (`link`) from an article↔tag-hub membership edge (`tag`). For `link` edges the
+ * direction (source→target) is the link direction; `tag` edges go article→tag.
+ */
+interface GraphEdge {
+    source: string;
+    target: string;
+    kind: 'link' | 'tag';
+}
+/** The whole-wiki knowledge graph. */
+interface LinkGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/**
+ * The local neighbourhood of one node: the node itself plus its directly linked
+ * (outgoing) and linking (incoming) neighbours, and the edges among them. `focus`
+ * is the id of the page this neighbourhood is centred on.
+ */
+interface LocalGraph {
+    focus: string;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+
+interface ParsedArticle {
+    title: string;
+    tags: string[];
+    created?: string;
+    audience: Audience;
+    status: PublishStatus;
+    body: string;
+}
+interface SerializableArticle {
+    title: string;
+    tags: string[];
+    audience?: Audience;
+    status?: PublishStatus;
+    body: string;
+}
+/**
+ * Remove a leading frontmatter block, returning the body **verbatim** — unlike
+ * {@link parseArticle}, no leading-whitespace trimming — so a caller that needs
+ * the body's original line offsets (e.g. a search index that blanks frontmatter
+ * to keep source line numbers aligned) can reconstruct them from the removed
+ * span. Returns the input unchanged when there is no frontmatter.
+ */
+declare function stripFrontmatter(raw: string): string;
+/**
+ * Parse a document's YAML frontmatter into a raw key/value object (every key,
+ * not just the article axes), plus the body. Bundler-safe via the pinned `yaml`
+ * engine. Use this for metadata files (e.g. template frontmatter carrying
+ * `shape`/`purpose`) where {@link parseArticle}'s fixed fields don't fit.
+ */
+declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+declare function parseArticle(raw: string): ParsedArticle;
+declare function serializeArticle(article: SerializableArticle): string;
+
+export { type ResolvedDependency as $, type Audience as A, type PluginHealth as B, type Config as C, type Diagnostic as D, type PluginReadiness as E, type ProjectCollection as F, type GraphEdge as G, type HomeCard as H, type ProjectContext as I, type SearchExpansion as J, type SerializableArticle as K, type LinkGraph as L, type SiteCopyright as M, NATIVE_ENGINE as N, type SiteHome as O, type PublishStatus as P, type QueryHit as Q, type Registry as R, type SiteConfig as S, type TreeNode as T, parseArticle as U, parseFrontmatter as V, serializeArticle as W, stripFrontmatter as X, type PluginDefinition as Y, type DefinedPlugin as Z, type PluginDependency as _, type CollectionEntry as a, type RunProcessOptions as a0, type EventHandlerResult as a1, type EventParams as a2, type HealthHandlerResult as a3, type HealthParams as a4, type IndexHandlerResult as a5, type IndexParams as a6, type LogLevel as a7, type PluginCapabilities$1 as a8, type PluginHandlers as a9, type PluginLogFn as aa, type SearchHandlerHit as ab, type SearchHandlerResult as ac, type SearchParams as ad, type SetupHandlerResult as ae, type SetupParams as af, type WireCollection as ag, type WireDiagnostic as ah, type WireReadiness as ai, type Article as b, type RepoConfig as c, type ProjectConfig as d, type CollectionInfo as e, type CollectionTree as f, type PageData as g, type ArticleNode as h, type QueryOptions as i, type ParsedArticle as j, type ArticleContent as k, type TocItem as l, type LocalGraph as m, type SearchMode as n, type SearchProvider as o, type PluginRecord as p, type PluginEvent as q, type PluginKind as r, type PluginRegistryFile as s, type CollectionType as t, type DiagnosticLevel as u, type DocData as v, type GraphNode as w, type ListingEntry as x, type NodeMeta as y, type PluginCapabilities as z };