@sparkelf/dsh-knowledge-base 0.0.0-stage → 0.1.0

package/lib/types/client/roleSummary.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What each role in the grant table actually amounts to.
+ *
+ * A role is not stored anywhere: it exists because grants name it. That is a good
+ * property to inherit — a role cannot outlive its resources or appear with none —
+ * but it means "list the roles" is a question about the grants, answered by
+ * reading them. This module is that reading, kept out of the component so it can
+ * be tested without a DOM.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/roleSummary
+ */
+import type { GrantView } from '../api.ts';
+/** One role as the overview shows it. */
+export interface RoleSummary {
+    /** Role id, which is the `principalId` its grants carry. */
+    id: string;
+    /** Display name, falling back to the id when no locale entry matches. */
+    label: string;
+    /** Actions granted anywhere by this role, collapsed so a full house reads `all`. */
+    actions: string[];
+    /** Distinct paths it reaches. */
+    paths: string[];
+    /** Whether this is one of the two the product ships with. */
+    builtIn: boolean;
+}
+/**
+ * Collapse raw action strings into the shortest describing list.
+ *
+ * The client needs this independently of the server: the overview renders grants
+ * the server already wrote, so it summarizes what is there rather than what a
+ * request asked for.
+ *
+ * @param actions - raw action strings.
+ * @returns `['all']` when all four concrete actions are held, else the subset.
+ */
+export declare function summarizeRoleActions(actions: readonly string[]): string[];
+/**
+ * Read the roles out of a grant table.
+ *
+ * Only `role` grants contribute: a user grant is not a role, and inventing one
+ * per user would flood the list with rows that mean nothing.
+ *
+ * @param grants - the grant table.
+ * @param locale - `zh` or `en`, for the built-in role names.
+ * @returns one entry per role named by a grant, built-ins first then alphabetical.
+ */
+export declare function buildRoleSummaries(grants: readonly GrantView[], locale?: 'zh' | 'en'): RoleSummary[];

package/lib/types/client/saveAudit.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Wire the knowledge base into the sidebar editor's save events.
+ *
+ * The knowledge base does not own the editor. Documents are shown in the host's own
+ * file window, and that window saves through its own route -- so a save never passes
+ * through a knowledge-base code path, and an audit trail written only from this
+ * plugin's routes would miss every edit made in the editor.
+ *
+ * The sidebar therefore accepts two registrations, both optional to it:
+ *
+ * - A **save actor** answers "who is acting right now". The knowledge base registers
+ *   one that reports the DataOps identity the Host resolved.
+ * - A **save listener** receives every successful save after the bytes landed.
+ *
+ * The knowledge base registers both. What it does with an event is deliberately
+ * duller than it could be: it posts the save to its own append-only audit route and
+ * forgets about it. Delivery is fire-and-forget, so a knowledge base that is down,
+ * slow, or misconfigured cannot turn a completed save into a failed one -- which is
+ * the whole reason the sidebar calls listeners without awaiting them.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Turn an absolute path back into a knowledge-base relative path.
+ *
+ * The sidebar reports absolute paths because that is what it edits. The audit route
+ * speaks the relative paths every other knowledge-base surface uses, so the mount
+ * point is stripped here rather than sending an absolute path the route would have
+ * to guess a root for.
+ * @param absolutePath - the path the sidebar saved.
+ * @param mountPoint - the knowledge root, absolute.
+ * @returns The relative path, or undefined when the save was outside the root.
+ */
+export declare function toKnowledgePath(absolutePath: string, mountPoint: string): string | undefined;
+/**
+ * Decide whether a save belongs to the knowledge base, and under which path.
+ *
+ * Two shapes show up in practice and both mean the same document:
+ *
+ * - The editor reports an absolute path when it edits outside a session workspace.
+ * - It reports a path relative to the session workspace (`kb/test-toc.md`) when the
+ *   document was reached through the workspace, which is the ordinary case here: the
+ *   knowledge view is linked into `/workspace/kb`.
+ *
+ * The knowledge root is reported by the page as its configured mount point, and the
+ * view is what the editor actually opens, so the mount point's last segment (`kb`)
+ * is the prefix that identifies knowledge-base saves in the relative shape. Matching
+ * on that segment rather than on the full absolute path is what makes the workspace
+ * route work at all.
+ * @param savedPath - the path the editor reported.
+ * @param mountPoint - the knowledge root as the page configured it.
+ * @returns The knowledge-base relative path, or undefined when the save is elsewhere.
+ */
+export declare function matchKnowledgeSave(savedPath: string, mountPoint: string): string | undefined;
+/**
+ * Register the knowledge base as a save actor and a save listener.
+ *
+ * Safe to call on a host without the extension: every access is optional and an
+ * absent service simply means nothing is registered. The returned disposer removes
+ * both registrations, so a plugin unload cannot leave a listener pointing at a
+ * closed page.
+ *
+ * @param ctx - the client context the page runs in.
+ * @param mountPoint - the knowledge root, used to keep saves outside it out of the trail.
+ * @returns A disposer, or a no-op when the sidebar service is absent.
+ */
+export declare function registerSaveAudit(ctx: unknown): () => void;
+/**
+ * Install the resolver that reports the knowledge root.
+ *
+ * The page is what knows the mount point (it comes from the Host's config), and the
+ * save listener needs it to tell a knowledge-base save from any other file's save.
+ * Passing a getter rather than a string keeps the registration alive across a mount
+ * point that arrives after the listener is installed.
+ * @param resolver - returns the current knowledge root, absolute.
+ */
+export declare function setMountPointResolver(resolver: () => string): void;
+/** Install the resolver the plugin's apply step owns. */
+export declare function setActorResolver(resolver: () => string | undefined): void;
+/**
+ * Publish the DataOps identity to the save-actor registration.
+ *
+ * The page resolves it through its own status call; the registration lives at plugin
+ * scope, so the value travels through here rather than being fetched twice.
+ * @param id - the caller id DataOps reported, or undefined when none is known.
+ */
+export declare function publishActor(id: string | undefined): void;

package/lib/types/client/useFavorites.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The favourites store the tree's star column renders.
+ *
+ * A star is a document-level preference, so it lives beside `.pinned.json` and
+ * `.kb-tree-state.json` in the caller's own view directory rather than in browser
+ * storage: a reader who stars a report on one machine expects to find it starred on
+ * the next, and a browser profile is not the unit a knowledge base follows.
+ *
+ * The write path is deliberately the same shape as `useTreeState`'s. A reader who
+ * stars a few rows in a row makes one gesture per row, and writing through
+ * immediately would put a round trip behind each click; saves are therefore
+ * coalesced behind one timer, only one is ever on the wire, and the latest state
+ * always wins. The optimistic update exists because a star is a one-click
+ * affordance on the row the reader is looking at -- waiting for a round trip
+ * before it fills in makes the control feel broken when it is merely slow.
+ *
+ * Keeping this a separate hook rather than extending `useTreeState` is a
+ * consequence of the two having different payload shapes and different failure
+ * costs: a lost expansion collapses a folder, while a lost star loses the mark the
+ * reader was just told had been saved.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the tree. */
+export interface FavoritesStore {
+    /** Relative paths of the starred rows, as the Host last answered. */
+    relPaths: readonly string[];
+    /** Whether one path is starred. */
+    has: (relPath: string) => boolean;
+    /**
+     * Star or unstar one path.
+     *
+     * Idempotent in the direction asked for, like `setPinned`: asking for the state
+     * that already holds writes nothing, so a double click cannot toggle a star back
+     * off by accident.
+     */
+    setFavorite: (relPath: string, favorite: boolean) => void;
+    /** Re-read from the Host. */
+    refresh: () => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's favourites.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where a favourites request would name a view that does not exist yet.
+ * @returns The store; `relPaths` is empty until the first read answers.
+ */
+export declare function useFavorites(enabled: boolean): FavoritesStore;

package/lib/types/client/usePinnedPaths.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The pinned-path store the rail renders.
+ *
+ * Pins are a document-level preference, so they live in the caller's own view
+ * directory on the share rather than in browser storage; the Host owns that file
+ * and this hook only reads and writes it through the two routes. The optimistic
+ * update exists because toggling a pin is a one-click gesture on a menu the reader
+ * is looking at: waiting for a round trip before the row moves makes the control
+ * feel broken when it is merely slow. A failed write reloads from the Host rather
+ * than leaving the guess on screen.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the rail. */
+export interface PinnedStore {
+    /** Pinned paths, in the order the Host returned them. */
+    relPaths: readonly string[];
+    /** Whether one path is pinned. */
+    has: (relPath: string) => boolean;
+    /**
+     * Add or remove one path.
+     *
+     * Idempotent in the direction asked for: pinning an already-pinned path leaves
+     * the list alone rather than toggling it off, so a double click cannot silently
+     * undo the first one.
+     */
+    setPinned: (relPath: string, pinned: boolean) => void;
+    /** Re-read from the Host. */
+    refresh: () => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's pins.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where a pin request would name a tree that does not exist yet.
+ * @returns The store.
+ */
+export declare function usePinnedPaths(enabled: boolean): PinnedStore;

package/lib/types/client/useTreeState.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The set of folders the reader has open in the explorer, remembered across visits.
+ *
+ * Expansion is a document-level preference, so it lives beside `.pinned.json` and
+ * `.view-mode.json` in the caller's view directory rather than in browser storage: a
+ * reader who opens `department/platform` on one machine expects to find it open on the
+ * next, and a browser profile is not the unit a knowledge base follows.
+ *
+ * Two costs shape the implementation.
+ *
+ * The read is a Host round trip, so the tree renders collapsed first and expands once
+ * the answer lands. Rendering it collapsed is the honest initial state: it is exactly
+ * what a reader who never opened a folder sees, and the alternative -- holding the whole
+ * tree back until a preference resolves -- would trade a flicker for a blank panel.
+ *
+ * The write happens on every toggle, and a reader opening a deep path toggles once per
+ * level, so writing through immediately would put four round trips behind one gesture.
+ * Saves are therefore coalesced: the first toggle arms a timer, later toggles inside the
+ * window replace the pending payload, and the timer sends whatever the latest state is.
+ * A save still in flight when the reader keeps clicking leaves a dirty flag rather than
+ * queueing a second request, so the wire never carries more than one save at a time and
+ * the last state always wins.
+ *
+ * A failed write is not surfaced as a page error. This is a view preference whose worst
+ * outcome is a folder that comes back closed, and shouting at a reader for it would be
+ * worse than the outcome; the next successful save repairs it.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** What the hook exposes to the rail. */
+export interface TreeStateStore {
+    /** Absolute paths of the expanded folders, as the Host last answered. */
+    expanded: readonly string[];
+    /** Toggle one directory open or closed. */
+    toggle: (path: string) => void;
+    /** Set the whole set at once (a reveal, or a Host round trip). */
+    setExpanded: (paths: readonly string[]) => void;
+}
+/**
+ * Read and write the caller's expanded folders.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where there is no view directory holding the preference.
+ * @param root - the knowledge root, used to bound what is stored; '' while unknown.
+ * @returns The store; `expanded` is empty until the first read answers.
+ */
+export declare function useTreeState(enabled: boolean, root?: string): TreeStateStore;

package/lib/types/client/useViewMode.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The list/grid preference the rail renders.
+ *
+ * A document-level preference stored beside the pins, for the same reason they are:
+ * a reader who switches to the grid on one machine expects it on the next. The
+ * optimistic update exists because the toggle is a one-click gesture on a control
+ * the reader is looking at, and waiting for a round trip before the layout changes
+ * makes it feel broken when it is merely slow. A failed write reloads from the Host
+ * rather than leaving the guess on screen.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Which layout the rail is showing.
+ *
+ * `explorer` renders the product's own file explorer (see `KnowledgeFileTree`), which is
+ * the tree a reader already knows from the workspace sidebar. It is a third option rather
+ * than a replacement because the two layouts answer different questions: the listing shows
+ * knowledge-base state the explorer has no concept of (whether a row is readable, its
+ * pinned mark, multi-select for a batch grant), while the explorer brings the affordances a
+ * file tree is expected to have (sort, inline rename, drag-and-drop, upload strip).
+ */
+export type ViewMode = 'list' | 'grid' | 'explorer';
+/** What the hook exposes to the rail. */
+export interface ViewModeStore {
+    /** The stored layout. */
+    mode: ViewMode;
+    /** Switch layouts, writing through to the Host. */
+    setMode: (mode: ViewMode) => void;
+    /** Set when the last write was refused, so the surface can say why. */
+    error: string | undefined;
+}
+/**
+ * Read and write the caller's layout preference.
+ * @param enabled - false while the mount point is unknown, which is the only state
+ *   where there is no view directory to hold the preference.
+ * @returns The store.
+ */
+export declare function useViewMode(enabled: boolean): ViewModeStore;

package/lib/types/deploy.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Idempotent deployment recipes for the knowledge base.
+ *
+ * Every step here is a *plan*: a named sequence of shell commands plus the
+ * predicate that decides whether the step already ran. The Settings panel shows
+ * each step, runs it over the {@link RemoteRunner} seam, and reports the output.
+ *
+ * Rules these recipes must satisfy:
+ * - Re-runnable. Clicking twice must not install twice, start two servers, or
+ *   fail because something already exists.
+ * - Read-only probes first. A status step never mutates anything.
+ * - The commands are quoted for a POSIX shell and never interpolate untrusted
+ *   input without quoting.
+ *
+ * @module @sparkelf/dsh-knowledge-base/deploy
+ */
+/**
+ * MinerU deployment tiers this plugin can prepare.
+ *
+ * MinerU 4.x recognises exactly these two (`mineru/types.py`: `DEPLOYMENT_TIERS`), and
+ * `models download --tier` validates against that tuple. The `flash` name that also exists in
+ * MinerU is a *quality* tier for the parsers that need no local weights, not a deployment
+ * tier, so it cannot be prepared and is not offered here.
+ */
+export type MineruTier = 'basic' | 'standard';
+/** Small-model backend for MinerU. */
+export type MineruBackend = 'onnx' | 'torch';
+/** One step of a deployment plan. */
+export interface DeployStep {
+    /** Stable id used by the UI. */
+    id: string;
+    /** Human-facing label key. */
+    label: string;
+    /**
+     * Commands to run in order. Each is a complete shell line.
+     * `{{...}}` placeholders are substituted from {@link DeployPlanContext}.
+     */
+    commands: string[];
+    /** How long this step may take; model downloads are slow. */
+    timeoutMs: number;
+}
+/** Values substituted into command templates. */
+export interface DeployPlanContext {
+    /** Absolute path of the authoritative knowledge tree. */
+    actualRoot: string;
+    /** Absolute path of the per-user view tree. */
+    viewRoot: string;
+    /** Tier to deploy. */
+    tier: MineruTier;
+    /** Small-model backend. */
+    backend: MineruBackend;
+    /** TCP port the MinerU API listens on. */
+    port: number;
+    /** Client hosts allowed to mount the NFS export, as an exports spec. */
+    permitted: string;
+    /** Host serving the export, as `address` or `address:/path` (the pseudo root). */
+    server: string;
+    /** Where the client mounts the export, i.e. the browsable knowledge tree. */
+    mountPoint: string;
+    /** Memory ceiling in MiB for the MinerU service; clamped to half the host's RAM. */
+    memoryMaxMiB?: number;
+    /**
+     * How a remote deployment reaches its share.
+     *
+     * Decides which transport steps {@link deploymentPlan} emits. Absent means `nfs`, the
+     * shape this plan had before the protocol existed.
+     */
+    protocol?: 'nfs' | 'sshfs';
+    /** SSHFS: remote host. */
+    sshHost?: string;
+    /** SSHFS: login user on the remote host. */
+    sshUser?: string;
+    /** SSHFS: TCP port the SSH daemon listens on. */
+    sshPort?: number;
+    /**
+     * SSHFS: path of the private key on the HOST, when the credential store resolves to a
+     * file. Optional: an ssh-agent-managed key needs no `-i`.
+     */
+    sshKeyPath?: string;
+    /** SSHFS: absolute path of the shared directory on the remote host. */
+    sshRemotePath?: string;
+    /** SSHFS: extra `-o` options, appended to the ones the step requires. */
+    sshMountOptions?: string;
+}
+/**
+ * Memory ceiling for the MinerU service when the config names none.
+ *
+ * The `basic` tier peaked at 1.86 GB resident while parsing a one-page PDF (measured
+ * 2026-10-15), so a ceiling near the steady-state size leaves `MemoryHigh` no headroom. On a
+ * host without swap that reads as a stalled parse rather than a slow one, because throttling
+ * has nowhere to spill. The service step clamps this to half of RAM, so the number only has to
+ * be generous on a roomy machine.
+ */
+export declare const DEFAULT_MINERU_MEMORY_MAX_MIB = 4096;
+/** Rotate a single-quoted shell string safely. */
+export declare function shquote(value: string): string;
+/** Substitute `{{name}}` placeholders; unknown names are left intact. */
+export declare function renderCommand(template: string, context: DeployPlanContext): string;
+/** Marker the image keeps so a redeploy can prove which tier is present. */
+export declare const KB_STATE_FILE = "/var/lib/dataops-kb/state.json";
+/**
+ * Read-only environment probe.
+ *
+ * Establishes which install path is available so the UI can disable the steps
+ * that cannot work: a host without Python cannot take the pip path.
+ * @returns the probe step.
+ */
+export declare function probeStep(): DeployStep;
+/**
+ * Install the MinerU package and download the selected tier's models.
+ *
+ * The base package (`mineru>=4.0,<5`) is the CPU path: it brings ONNX and
+ * llama.cpp but not vLLM, which needs a GPU this environment does not have.
+ * @param context - deployment values.
+ * @returns the install step.
+ */
+export declare function mineruInstallStep(context: DeployPlanContext): DeployStep;
+/**
+ * Install a systemd unit that serves the MinerU HTTP API.
+ *
+ * A unit rather than a bare background process so the service survives logout
+ * and can be restarted by the same click.
+ * @param context - deployment values.
+ * @returns the service step.
+ */
+export declare function mineruServiceStep(context: DeployPlanContext): DeployStep;
+/**
+ * Verify the MinerU API actually answers.
+ *
+ * This is the check that catches the parameter-compatibility question: the
+ * plugin posts multipart form fields while MinerU 4.x reads a request body, so
+ * a pass here is the evidence that the two agree.
+ * @param context - deployment values.
+ * @returns the verification step.
+ */
+export declare function mineruVerifyStep(context: DeployPlanContext): DeployStep;
+/**
+ * Deploy the NFS export of the knowledge tree.
+ *
+ * Uses the container image rather than host packages: Docker is already present
+ * on the target, the image carries the userspace tools, and its default export
+ * template already includes `no_root_squash`, which hardlinking across NFS
+ * requires.
+ * @param context - deployment values.
+ * @returns the NFS step.
+ */
+export declare function nfsDeployStep(context: DeployPlanContext): DeployStep;
+/**
+ * Prove hardlinks work across the NFS export.
+ *
+ * Creating a hard link between the authoritative tree and a view directory is
+ * the single operation the whole permission model depends on, and it is also
+ * the operation most likely to fail (wrong export scope, `root_squash`, split
+ * filesystems). A pass here is the acceptance test for the storage side.
+ * @param context - deployment values.
+ * @returns the storage verification step.
+ */
+export declare function nfsVerifyStep(context: DeployPlanContext): DeployStep;
+/**
+ * Mount the exported share at the mount point, with the option this deployment needs.
+ *
+ * `noresvport` is not decorative here. This host runs WSL2 with
+ * `networkingMode=mirrored`, where an NFS mount without it hangs until timeout
+ * (`mount.nfs: Connection timed out`) while `rpcinfo`, `showmount -e` and a plain TCP
+ * connect to 2049 all still succeed. Measured 2026-10-16 against a server that mounts
+ * fine from its own kernel, and A/B verified: without the option the mount fails, with
+ * it the mount succeeds, repeatably. Microsoft documents the same failure for mirrored
+ * networking (WSL issue 12508), which is still open.
+ *
+ * The NFS client normally opts into a reserved source port, which requires a reply the
+ * mirrored networking stack does not deliver; `noresvport` drops that requirement.
+ *
+ * @param context - Deployment paths and the export address.
+ * @returns The mount step.
+ */
+export declare function nfsMountStep(context: DeployPlanContext): DeployStep;
+/**
+ * Mount a remote directory over SSHFS on the HOST.
+ *
+ * The same shape as {@link nfsMountStep}, for a host that cannot mount NFS: the container
+ * has no `CAP_SYS_ADMIN` and cannot mount anything itself, so this runs on the Host and the
+ * resulting directory is bound in at `mountPoint` like any other.
+ *
+ * Two details are not incidental:
+ * - `StrictHostKeyChecking=accept-new` is limited to this invocation. Accepting an unknown
+ *   host key globally would silence the one warning that catches a swapped host, so the
+ *   trust-on-first-use decision is scoped to the connection whose key the operator is
+ *   establishing.
+ * - The reconnect options are not optional here. An SSHFS mount whose connection drops
+ *   returns EIO to every reader until someone unmounts it; `reconnect` plus a keepalive is
+ *   what makes a transient network blip a stall instead of a broken knowledge base.
+ * @param context - transport and target paths from the deployment config.
+ * @returns the mount step.
+ */
+export declare function sshfsMountStep(context: DeployPlanContext): DeployStep;
+/**
+ * Verify the SSHFS mount is present, readable, and actually a FUSE mount.
+ *
+ * Separate from the mount step because "the command exited 0" and "the reader will see
+ * files" are different claims: a stale empty directory satisfies the first and not the
+ * second, and the filesystem type is what tells them apart.
+ * @param context - transport and target paths from the deployment config.
+ * @returns the verification step.
+ */
+export declare function sshfsVerifyStep(context: DeployPlanContext): DeployStep;
+/** The full ordered plan the Settings panel presents. */
+export declare function deploymentPlan(context: DeployPlanContext): DeployStep[];
+/** Look up one step by id. */
+export declare function findStep(id: string, context: DeployPlanContext): DeployStep | undefined;

package/lib/types/extract.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Convert an uploaded document into Markdown so its text becomes greppable.
+ *
+ * The knowledge tree doubles as a document store and as what an agent greps. A
+ * `.docx` on disk is neither: its bytes answer no query. Every upload therefore
+ * lands twice — the original, byte for byte, plus a `.md` sibling holding the
+ * extracted text — so a reader can still open the real file while a search sees
+ * the words inside it.
+ *
+ * Extraction is delegated rather than implemented here. Three authorities
+ * already exist in this deployment and each owns one format family:
+ *
+ * - MinerU (`/file_parse`) parses PDF and office documents with layout models.
+ *   It is the best answer for a scanned PDF and the one authority that can
+ *   recognise tables inside one.
+ * - LibreOffice converts the legacy binary formats (`.doc`, `.xls`, `.ppt`) that
+ *   MinerU and the Python readers refuse.
+ * - `python-docx` / `openpyxl` / `python-pptx` / `pypdf` read the modern formats
+ *   directly, without a service round trip.
+ *
+ * None of them is reimplemented in TypeScript: a `.docx` is a ZIP of XML and a
+ * second parser would only disagree with the first. This module decides WHICH
+ * authority to ask and what to do when it cannot answer, which is the part that
+ * is specific to this plugin.
+ *
+ * A failed extraction never fails the upload. The original is already written and
+ * remains the source of truth; the caller learns that no `.md` was produced, and
+ * the file stays readable through the original.
+ *
+ * @module @sparkelf/dsh-knowledge-base/extract
+ */
+/** Formats whose text this module knows how to extract. */
+export declare const EXTRACTABLE_EXTENSIONS: readonly [".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp", ".rtf"];
+/** One extractable extension. */
+export type ExtractableExtension = typeof EXTRACTABLE_EXTENSIONS[number];
+/** How one request to the extraction authorities ended. */
+export interface ExtractResult {
+    /** Markdown text, when extraction produced any. */
+    markdown?: string;
+    /**
+     * Which authority answered. Reported so a bad conversion can be traced.
+     *
+     * `mineru-ocr` means the first pass classified the document as text and came back
+     * too thin to search, so the same parser was asked again with OCR forced. It is a
+     * separate value because the two passes can disagree, and a reader debugging a
+     * missing line needs to know which one produced the file.
+     */
+    via?: 'mineru' | 'mineru-ocr' | 'libreoffice' | 'python' | 'native';
+    /** Why no markdown was produced. Present whenever {@link markdown} is absent. */
+    reason?: string;
+}
+/**
+ * Whether this path names a document worth extracting.
+ *
+ * Compared case-insensitively because a browser reports the extension as the
+ * user typed it, and a `.PDF` is the same format as a `.pdf`.
+ *
+ * @param relPath - the uploaded path, relative to the knowledge root.
+ * @returns true when {@link extractDocument} has an authority for it.
+ */
+export declare function isExtractable(relPath: string): boolean;
+/**
+ * The Markdown sibling an extracted document lands beside.
+ *
+ * Appending rather than replacing the extension keeps two same-named uploads
+ * from colliding: `报告.docx` becomes `报告.docx.md`, so it cannot overwrite a
+ * `报告.md` the user wrote by hand.
+ *
+ * @param relPath - the uploaded document's path.
+ * @returns the markdown path to write.
+ */
+export declare function markdownSiblingOf(relPath: string): string;
+/**
+ * Whether MinerU should be asked before the local readers.
+ *
+ * PDF only: a PDF carries no recoverable structure beyond its layout, which is
+ * exactly what MinerU models. An office document still has its XML, and the
+ * direct readers keep more of it (a spreadsheet's cell grid survives
+ * `openpyxl` and is flattened by a layout parser).
+ *
+ * @param ext - lowercased extension including the dot.
+ * @returns true when the remote parser is the better authority.
+ */
+export declare function prefersRemoteParser(ext: string): boolean;
+/**
+ * Ask MinerU to parse one file and return its Markdown.
+ *
+ * The service answers with a task handle for large files and the body directly
+ * for small ones, so both shapes are accepted. A non-200 answer is a miss, not
+ * a failure of the upload.
+ *
+ * @param baseUrl - MinerU service base URL, without a trailing slash.
+ * @param fullPath - absolute path of the document on this host.
+ * @param fileName - name to report to the service.
+ * @returns the Markdown, or undefined when the service could not parse it.
+ */
+/**
+ * Whether an extraction came back too small to be worth searching.
+ *
+ * Not a judgement about document quality: a 200-character memo is a real document,
+ * and treating it as a failure would re-run OCR over something already correct. The
+ * test targets the specific shape of a mis-classified scan -- pages of content that
+ * came back as a title and a page number -- so it counts what is left after markup
+ * rather than trusting a single threshold on the whole answer.
+ *
+ * @param markdown - what the parser returned.
+ * @returns true when the answer is short enough that a classifier mistake is likely.
+ */
+export declare function looksTooThinToSearch(markdown: string): boolean;
+/** Services and commands extraction may use, as configured for this deployment. */
+export interface ExtractOptions {
+    /** MinerU base URL. Empty disables the remote parser. */
+    mineruUrl?: string;
+}
+/**
+ * Extract one document to Markdown.
+ *
+ * Authorities are tried in an order that puts the best answer first for each
+ * format, and every step degrades to the next rather than failing: a PDF whose
+ * MinerU call times out still gets `pypdf`'s text layer.
+ *
+ * @param fullPath - absolute path of the written document.
+ * @param relPath - the same document's knowledge-relative path, for the title.
+ * @param options - services this deployment exposes.
+ * @returns the Markdown and the authority that produced it, or the reason none did.
+ */
+export declare function extractDocument(fullPath: string, relPath: string, options?: ExtractOptions): Promise<ExtractResult>;
+/**
+ * Whether a file exists and is a regular file.
+ *
+ * @param path - absolute path to test.
+ * @returns true when it is there.
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Write extracted markdown beside its document.
+ *
+ * Kept separate from {@link extractDocument} so the write is testable without an
+ * extraction service.
+ *
+ * @param markdownPath - absolute path of the `.md` sibling.
+ * @param markdown - the text to write.
+ */
+export declare function writeExtractedMarkdown(markdownPath: string, markdown: string): Promise<void>;