@sparkelf/dsh-knowledge-base 0.1.0 → 0.1.1

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

@@ -0,0 +1,81 @@
+/**
+ * Turning grants into the two "share" groups the Home tab shows.
+ *
+ * The split the reader cares about is DIRECTION: what has been shared with me, and what
+ * I have shared out. The grant data has no grantor field (the backend's `toSummary`
+ * omits it and the table has no `created_by`), so "who gave me this" cannot be answered
+ * from it. What CAN be answered is the audience side: which principal a grant names.
+ *
+ * Everything here is a pure function of the grant list plus the caller, which is what
+ * makes the two-way split testable without a browser.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One grant, in the shape the Host relays. */
+export interface ShareGrant {
+    /** Stable row id. */
+    id: string;
+    /** Path relative to the knowledge mount point. */
+    relPath: string;
+    /** Whether the path is a file or a directory. */
+    kind: 'file' | 'directory';
+    /** Principal kind the grant names. */
+    principalType: 'user' | 'role' | 'department' | 'group';
+    /** Principal id within its kind. */
+    principalId: string;
+    /** Permission the grant confers. */
+    action: string;
+}
+/** A principal name lookup: id per kind, falling back to the id itself. */
+export type PrincipalNameOf = (kind: ShareGrant['principalType'], id: string) => string | undefined;
+/** Which group one grant belongs to. */
+export type ShareDirection = 'received' | 'given';
+/** One row of either group. */
+export interface ShareRow {
+    /** Stable row id, taken from the grant. */
+    id: string;
+    /** Path relative to the knowledge mount point. */
+    relPath: string;
+    /** File name alone, for the row's title. */
+    name: string;
+    /** Directory the path sits in, for the location column. */
+    location: string;
+    /** Principal kind the grant names. */
+    principalType: ShareGrant['principalType'];
+    /** The audience this grant names, resolved to a display name when possible. */
+    audience: string;
+    /** The permission the grant confers. */
+    action: string;
+}
+/**
+ * Whether a grant names the caller directly.
+ *
+ * Only a `user` grant can: a role, department or group is an audience the caller
+ * belongs to rather than the caller themselves, and treating it as "me" would let a
+ * department-wide grant read as a personal share.
+ * @param grant - the grant to test.
+ * @param callerId - the caller's own user id, when known.
+ * @returns True when the grant names this exact user.
+ */
+export declare function isOwnGrant(grant: ShareGrant, callerId: string | undefined): boolean;
+/**
+ * Split grants into the two directions the Home tab shows.
+ *
+ * The rule is deliberately simple and says only what the data supports: a grant that
+ * names the caller is "shared with me"; every other grant is "shared out". It does NOT
+ * claim the caller created the latter -- the grantor is not in this data at all -- so
+ * callers must word that group as an audience ("I shared to X"), never as a fact about
+ * who granted it.
+ *
+ * A grant naming the caller is excluded from the outgoing group even when it also
+ * appears there, so one document cannot look like it was shared to the reader and by
+ * the reader at the same time.
+ * @param grants - every grant the Host relayed.
+ * @param callerId - the caller's own user id, when known.
+ * @param nameOf - the principal directory lookup.
+ * @returns Both groups, each in the order the grants arrived.
+ */
+export declare function splitShareRelations(grants: readonly ShareGrant[], callerId: string | undefined, nameOf: PrincipalNameOf): {
+    received: ShareRow[];
+    given: ShareRow[];
+};

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

@@ -0,0 +1,171 @@
+/**
+ * Drag-and-drop upload: the part that can be decided without a browser.
+ *
+ * A drop needs three things settled before anything is uploaded: which directory the
+ * pointer is over, whether that directory may receive a drop, and the list of files
+ * (with their paths inside a dropped folder) that the drop carried. All three are
+ * answers about *data*, not about React state, so they live here and are tested
+ * directly instead of through a rendered tree.
+ *
+ * The module deliberately does not touch `DataTransfer`, `FileList` or `document`.
+ * The test runner has no DOM (measured: `DataTransfer`, `FileList` and `document` are
+ * all undefined, only `File` exists), and a module that reached for them could only be
+ * tested by faking the entire browser. It describes the two shapes it needs instead,
+ * and the component adapts a real event to them at the boundary. That is also what
+ * keeps the traversal order and the collision rules honest: they are pure functions of
+ * their inputs, so a test can assert them without a browser.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** A file plus the path it should occupy under the drop target. */
+export interface DroppedFile {
+    /** The browser's `File`, or anything carrying a name and a byte source. */
+    file: unknown;
+    /**
+     * Path relative to the directory the reader dropped onto.
+     *
+     * A single dropped file carries only its name. A file from a dropped folder carries
+     * the folder's segments too (`specs/2026/api.md`), which is what preserves the shape
+     * the reader saw in the file manager instead of flattening it.
+     */
+    relativePath: string;
+}
+/**
+ * What a directory row knows about itself, as far as a drop is concerned.
+ *
+ * The two flags are separate on purpose. `isDirectory` says what the row IS; `drops`
+ * says whether this surface accepts drops AT ALL right now (an upload already running,
+ * or a read-only caller). A file row is a directory the drop must ignore, while a
+ * disabled directory row is one that must also ignore it -- the reason differs but the
+ * answer does not, so `acceptsDrop()` is the single place that combines them.
+ */
+export interface DropTargetLike {
+    /** The directory an accepted drop uploads into, relative to the knowledge root. */
+    relativePath: string;
+    /** Whether the row names a folder rather than a document. */
+    isDirectory: boolean;
+    /** Whether this surface accepts drops at the moment (false while busy/read-only). */
+    drops: boolean;
+}
+/** The minimum a drop event must expose for this module to read it. */
+export interface DropEventLike {
+    /** Whether the event carries file payload; a text drag must not upload anything. */
+    hasFiles: boolean;
+    /** The pending file list, or undefined when the browser exposes none. */
+    files: readonly DroppedFile[] | undefined;
+}
+/** Why a drop produced no upload. Each case is a different thing to tell the reader. */
+export type DropRefusal = 
+/** The pointer was over a document, or outside any drop target. */
+'not-a-directory'
+/** A drop target was hit but it is not accepting drops right now. */
+ | 'disabled'
+/** The target accepted, but the drop carried no files (a text or link drag). */
+ | 'no-files';
+/** The verdict for one drop. */
+export type DropPlan = {
+    kind: 'upload';
+    directory: string;
+    files: DroppedFile[];
+} | {
+    kind: 'refuse';
+    reason: DropRefusal;
+};
+/**
+ * Whether this row may receive the drop that is being dragged over it.
+ *
+ * Used by `dragover` to decide `preventDefault` (which is what makes the browser show
+ * "copy" and allows the drop) and whether to paint the highlight. It answers `false`
+ * for a document row so a file dragged onto a file is refused rather than silently
+ * doing nothing, and `false` while the surface is busy so a second drop cannot start
+ * a competing upload.
+ * @param target - the row under the pointer, or undefined outside any row.
+ * @returns Whether the row would accept a drop.
+ */
+export declare function acceptsDrop(target: DropTargetLike | undefined): boolean;
+/**
+ * Decide what one drop should do.
+ *
+ * Kept separate from the event so the refusal cases stay distinguishable: "you dropped
+ * it on a document" and "you dragged text, not files" need different sentences, and a
+ * single `undefined` return would force the caller to guess which happened.
+ * @param target - the row under the pointer, or undefined outside any row.
+ * @param event - the drop's payload.
+ * @returns The upload to perform, or why it was refused.
+ */
+export declare function planDrop(target: DropTargetLike | undefined, event: DropEventLike): DropPlan;
+/**
+ * Normalise a path relative to the drop target.
+ *
+ * Browsers report a dropped folder's contents with either separator (the `File` API on
+ * Windows reports `\`, `webkitRelativePath` uses `/`), and a leading separator would
+ * make the joined path absolute and fail the server's containment check. Both are
+ * collapsed here so the server sees one form.
+ * @param raw - the path as the browser reported it.
+ * @returns The path with forward slashes and no leading separator.
+ */
+export declare function normalizeDropPath(raw: string): string;
+/**
+ * Join a drop target with one file's own path.
+ * @param directory - the target directory relative to the knowledge root, `''` for the root.
+ * @param relativePath - the file's path inside the drop, already normalised or not.
+ * @returns The target path relative to the knowledge root.
+ */
+export declare function dropTargetPath(directory: string, relativePath: string): string;
+/**
+ * Collapse a dropped list to one entry per destination.
+ *
+ * Dropping the same folder twice, or a folder plus one of its files, would otherwise
+ * send two writes to the same path: the first succeeds and the second is refused as
+ * "already exists", so the reader would be shown a failure for a file that is actually
+ * there. The FIRST occurrence wins because that is the one the browser enumerated
+ * first, and its bytes are the ones the reader saw at the top of the drag.
+ * @param files - the dropped files.
+ * @returns One entry per distinct destination path, in first-seen order.
+ */
+export declare function dedupeDropped(files: readonly DroppedFile[]): DroppedFile[];
+/**
+ * One line describing the outcome of a whole drop, or undefined when there is nothing
+ * worth saying (all files landed).
+ *
+ * The reader dropped N files and gets one message: naming each failure is unreadable,
+ * while "some failed" without a count is not actionable. Partial success therefore
+ * states both numbers and names the first few failures, because the next step (retry
+ * that one, rename it, ask for access) depends on WHICH file was refused.
+ * @param results - one outcome per attempted file, in order.
+ * @param maxNames - how many failing names to spell out before summarising the rest.
+ * @returns The sentence to show, or undefined when every file landed.
+ */
+export declare function summarizeDrop(results: readonly {
+    relativePath: string;
+    ok: boolean;
+}[], maxNames?: number): {
+    ok: number;
+    failed: string[];
+} | undefined;
+/**
+ * Whether a drag event carries files this surface could upload.
+ *
+ * `types` is the only part of a `DataTransfer` readable during `dragover`: the payload
+ * itself is protected until the drop, so this is what `dragover` must ask to decide
+ * whether to `preventDefault`. An internal row drag sets `text/plain` and the knowledge
+ * base's own MIME type but NOT `Files`, which is how an in-page move stays a move.
+ * @param types - `event.dataTransfer.types`.
+ * @returns Whether the drag is an external file payload.
+ */
+export declare function isFileDrag(types: readonly string[] | undefined): boolean;
+/**
+ * Read the files of a drop as the shape {@link planDrop} takes.
+ *
+ * `webkitGetAsEntry` is preferred because it is the only way a DROPPED FOLDER arrives:
+ * folders never appear in `dataTransfer.files`, so a plain file list silently drops them
+ * and the reader sees "nothing happened". The entry API must be read synchronously from
+ * the drop handler (the payload enters protected mode once the event dispatch ends), so
+ * entries are captured here first and traversed afterwards.
+ *
+ * Falls back to the flat file list when the entry API is missing or yields nothing
+ * usable, which is also the correct behaviour for a browser that only reports files.
+ * @param transfer - the drop's `dataTransfer`.
+ * @returns One entry per file, with paths relative to the drop target.
+ */
+export declare function readDroppedFiles(transfer: DataTransfer | undefined | null): Promise<DroppedFile[]>;

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

@@ -0,0 +1,64 @@
+/**
+ * The React shell around the drag-and-drop decisions.
+ *
+ * Everything that can be decided without a browser lives in `useFileDrop.ts` next to
+ * this file -- the target rules, the path joining, the de-duplication, the summary.
+ * What is left is the one thing that genuinely needs a component: which row is
+ * currently painted as the drop target.
+ *
+ * Kept in its own module for two reasons. The pure module must stay importable from a
+ * test that has no DOM (measured: the runner has `File`, but no `DataTransfer`,
+ * `FileList` or `document`), and importing React into it would make that impossible.
+ * And the component wiring is the part that has to wait for the in-flight edits to
+ * `KnowledgeFileTree.tsx` / `KnowledgeHome.tsx` to land, so it is kept separate rather
+ * than half-merged.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { DropEventLike, DropPlan, DropTargetLike } from './useFileDrop.ts';
+/** What a component gets back from {@link useFileDrop}. */
+export interface FileDropHandle {
+    /** The path of the row that should paint its drop highlight, or undefined. */
+    highlighted: string | undefined;
+    /**
+     * Call from a row's `onDragOver`.
+     *
+     * Returns whether the row accepts this drag, which the caller uses to decide
+     * `event.preventDefault()`: without it the browser refuses the drop outright.
+     * @param target - the row under the pointer.
+     * @returns Whether the row would accept the drop.
+     */
+    onDragOver: (target: DropTargetLike | undefined) => boolean;
+    /**
+     * Call from a row's `onDragEnter`.
+     *
+     * @param target - the row the pointer entered.
+     * @returns Whether the row would accept the drop.
+     */
+    onDragEnter: (target: DropTargetLike | undefined) => boolean;
+    /**
+     * Call from a row's `onDragLeave`, and from the surface's own `onDragLeave` for the
+     * case where the pointer left the panel entirely.
+     * @param target - the row the pointer left, if any.
+     */
+    onDragLeave: (target?: DropTargetLike | undefined) => void;
+    /**
+     * Call from a row's `onDrop`. Clears the highlight and returns what to upload.
+     * @param target - the row the pointer was over.
+     * @param event - the drop payload.
+     * @returns The upload to perform, or why nothing happens.
+     */
+    onDrop: (target: DropTargetLike | undefined, event: DropEventLike) => DropPlan;
+    /** Clear the highlight without a drop (Escape, or the drag leaving the window). */
+    reset: () => void;
+}
+/**
+ * Track the drag state for one drop surface.
+ *
+ * Note the enter/leave counter. A drag crossing from a row onto its own child fires
+ * `dragleave` on the parent BEFORE `dragenter` on the child, so clearing the highlight
+ * on every `dragleave` makes it flicker off and back on. Counting enter/leave pairs is
+ * what keeps it stable; the counter reaching zero is the real exit.
+ * @returns The handle a component wires into its rows.
+ */
+export declare function useFileDrop(): FileDropHandle;

package/lib/types/extractionQueue.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Background extraction of a document's Markdown sibling.
+ *
+ * Upload and extraction are two different promises. The bytes are the uploader's
+ * deliverable and must be visible the moment the write lands; the `.md` sibling is
+ * derived text that may take a minute (a scanned PDF goes through MinerU, a legacy
+ * `.doc` through LibreOffice). Doing both inside the upload request made a slow
+ * parse look like a slow upload -- and a failed parse look like a failed upload.
+ *
+ * This queue separates them. `enqueue` never blocks and never throws: a failed
+ * extraction is a status, not an upload error. The queue lives in this process only
+ * (see {@link MAX_FINISHED_TASKS}) because the file itself is already durable; a
+ * restart loses the bookkeeping, and the manual `extract.retry` route is the recovery
+ * path. Persisting a queue would add a second source of truth about files that the
+ * filesystem already answers for.
+ *
+ * @module @sparkelf/dsh-knowledge-base/extractionQueue
+ */
+/** Lifecycle of one extraction task. */
+export type ExtractionState = 'pending' | 'running' | 'succeeded' | 'failed' | 'unsupported';
+/** One extraction task, as a reader observes it. */
+export interface ExtractionTask {
+    /** Knowledge-relative path of the SOURCE document. */
+    relPath: string;
+    /** Where the task is in its lifecycle. */
+    state: ExtractionState;
+    /** When the task was accepted, ISO-8601. */
+    queuedAt: string;
+    /** When the run started, ISO-8601. */
+    startedAt?: string;
+    /** When the run reached a terminal state, ISO-8601. */
+    finishedAt?: string;
+    /** The Markdown sibling that was written, when one was. */
+    markdown?: string;
+    /** Which authority produced the text (`mineru`, `libreoffice`, `python`, `native`). */
+    via?: string;
+    /** Why the extraction produced nothing, verbatim from the extractor. */
+    reason?: string;
+}
+/** What one run reports back to the queue. */
+export interface ExtractionOutcome {
+    /** Terminal state for this run. */
+    state: Exclude<ExtractionState, 'pending' | 'running'>;
+    /** The written sibling, when the run produced one. */
+    markdown?: string;
+    /** The authority that produced the text. */
+    via?: string;
+    /** Why nothing was produced. */
+    reason?: string;
+}
+/**
+ * How many extractions may run at once.
+ *
+ * One, deliberately. Every authority this drives is expensive in a way a second
+ * concurrent run makes worse: LibreOffice spawns a headless process per conversion and
+ * MinerU parses on the same small box the workspace already shares. Serializing also
+ * makes the observable order the submission order, which is what a reader retrying one
+ * file expects.
+ */
+export declare const MAX_CONCURRENT_EXTRACTIONS = 1;
+/**
+ * Most finished tasks remembered for status reads.
+ *
+ * The map is bookkeeping, not storage: an evicted entry loses only its status line,
+ * never a file. Bounded so a long-lived process does not accumulate one record per
+ * upload it ever saw. Running and pending tasks are never evicted.
+ */
+export declare const MAX_FINISHED_TASKS = 200;
+/** What the queue needs from the surrounding plugin, injected so it stays testable. */
+export interface ExtractionQueueOptions {
+    /**
+     * Run one extraction.
+     *
+     * Supplied by the plugin so this module owns scheduling only, not the extraction
+     * itself: the caller keeps the permission-checked `extractBeside` path in one place.
+     * @param relPath - the source document.
+     * @param mineruBaseUrl - the caller's own parser address, when set.
+     * @returns the terminal state of the run.
+     */
+    run: (relPath: string, mineruBaseUrl: string | undefined) => Promise<ExtractionOutcome>;
+    /**
+     * Whether this path can be extracted at all.
+     *
+     * Asked before queueing so an unsupported file answers immediately rather than
+     * occupying the single worker slot to discover it has no reader.
+     */
+    isExtractable: (relPath: string) => boolean;
+}
+/** One extraction queue. One instance per plugin registration. */
+export interface ExtractionQueue {
+    /**
+     * Accept a source document for background extraction.
+     *
+     * Never throws and never waits: the upload that calls this has already written its
+     * bytes, and nothing about a parse may change that answer. A repeat for the same
+     * path while one is still pending or running returns the existing task instead of
+     * queueing a second run.
+     * @param relPath - the source document, relative to the knowledge root.
+     * @param mineruBaseUrl - the caller's own parser address, when set.
+     * @returns the task as it stands right after the call.
+     */
+    enqueue: (relPath: string, mineruBaseUrl?: string) => ExtractionTask;
+    /**
+     * Read one task.
+     * @param relPath - the source document.
+     * @returns the task, or undefined when this process never saw it.
+     */
+    get: (relPath: string) => ExtractionTask | undefined;
+    /**
+     * Snapshot the queue for a status surface.
+     * @returns every remembered task plus what is running.
+     */
+    snapshot: () => {
+        running: string | undefined;
+        size: number;
+        tasks: ExtractionTask[];
+    };
+    /**
+     * Wait for one path's task to reach a terminal state.
+     *
+     * The manual-retry route waits on its own document, and it must wait on the TASK
+     * rather than on `drain()`. Two reasons, both about there being one truth:
+     *
+     * 1. `drain()` also waits for unrelated uploads queued ahead, so a retry would
+     *    report a delay that has nothing to do with this file.
+     * 2. The retry must NOT run its own extraction and then enqueue a second copy to
+     *    keep the status surface current. That is two runs of one document, and an
+     *    answer built from one run while `extract.status` reports the other -- the
+     *    exact split this method exists to remove.
+     *
+     * Resolves with the terminal task, or immediately with `undefined` when this
+     * process never queued that path (a restart, or a path it has not seen). Never
+     * rejects: the caller is a route, and the queue is not allowed to become an error
+     * path for an upload.
+     * @param relPath - the source document.
+     * @returns the terminal task, or undefined when the path was never queued.
+     */
+    settled: (relPath: string) => Promise<ExtractionTask | undefined>;
+    /**
+     * Wait for the queue to go idle.
+     *
+     * For tests and for a caller that asked to wait on one specific run; a reader never
+     * needs it. Resolves when nothing is pending or running.
+     * @returns when the worker has drained.
+     */
+    drain: () => Promise<void>;
+}
+/**
+ * Create an extraction queue.
+ *
+ * @param options - the runner and the predicate that decides whether a path has a reader.
+ * @returns a queue that runs at most {@link MAX_CONCURRENT_EXTRACTIONS} task at a time.
+ */
+export declare function createExtractionQueue(options: ExtractionQueueOptions): ExtractionQueue;

package/lib/types/index.d.ts

@@ -24,6 +24,7 @@ import { type KnowledgeConfig, type KnowledgeGrant, type KnowledgeGrantRequest,
 import { type KnowledgeStorageSettings, type ViewDelta } from './views.ts';
 import { type DeployPlanContext, type MineruBackend, type MineruTier } from './deploy.ts';
 import { type RemoteHost, type RemoteRunner } from './remote.ts';
+import { type ExtractionOutcome } from './extractionQueue.ts';
 /** Cordis plugin name. */
 export declare const name = "dsh-knowledge-base";
 /**
@@ -363,6 +364,21 @@ export interface KnowledgeEntry {
     readable?: boolean;
     /** Number of direct children, for a directory row. */
     childCount?: number;
+    /**
+     * Whether a reader exists for this file's format.
+     *
+     * Set on file rows only. The page uses it to decide whether "extract markdown" is a
+     * meaningful action for this row, so the menu does not have to know the extractor's
+     * extension list.
+     */
+    canExtract?: boolean;
+    /**
+     * Whether this file's `.md` sibling already exists.
+     *
+     * Set on file rows only, and only for formats that have an extractor. Lets the page
+     * say "already extracted" rather than offering a retry that would be refused.
+     */
+    hasMarkdown?: boolean;
 }
 /**
  * List one directory level with each child's modification time.
@@ -445,6 +461,18 @@ export interface PrincipalOption {
     id: string;
     /** Human-facing name, falling back to the id when the backend sends none. */
     label: string;
+    /** Login name, for users only: two accounts can share a display name. */
+    username?: string;
+    /**
+     * Role codes this principal belongs to.
+     *
+     * Users only, and only when the directory reported it. The permission overview needs
+     * this to answer "what does this PERSON have": a role grant confers access on every
+     * member, so without the membership a reader whose access is entirely role-derived
+     * would look like they hold nothing. Absent means the directory did not say -- which
+     * the page reports as unavailable inheritance rather than as no inheritance.
+     */
+    roleCodes?: string[];
 }
 /**
  * Read the principals of one kind from the backend.
@@ -666,6 +694,31 @@ export declare function extractBeside(config: Config, relPath: string, mineruUrl
     via?: string;
     reason?: string;
 } | undefined>;
+/**
+ * Translate {@link extractBeside}'s answer into a queue terminal state.
+ *
+ * The extractor reports three different outcomes through two fields, and they mean
+ * different things to a reader deciding what to do next:
+ *
+ * - `markdown` set, no `reason` — the sibling was written (`succeeded`).
+ * - `markdown` set WITH a `reason` — the text was produced but writing the sibling was
+ *   refused, typically because it already exists. The reason is kept so a retry can
+ *   report why nothing changed (`failed`, with the refusal verbatim).
+ * - `markdown` empty, `reason` set — no authority could read the document; this is the
+ *   `no-extractor-succeeded: …` case a reader retries after an upgrade.
+ *
+ * An `undefined` answer means the format has no extractor at all, which the queue
+ * normally prevents by asking `isExtractable` first; it is mapped for the caller that
+ * bypassed that gate rather than left to throw.
+ *
+ * @param outcome - what {@link extractBeside} returned.
+ * @returns the state the queue records.
+ */
+export declare function extractionOutcomeOf(outcome: {
+    markdown: string;
+    via?: string;
+    reason?: string;
+} | undefined): ExtractionOutcome;
 /**
  * MinerU's base URL for this deployment, or undefined when it is not configured.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-knowledge-base",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "DataOps-backed knowledge base for DeepSeek Harness: a left-sidebar destination, Settings configuration, and index tooling over a mounted NAS view.",
   "type": "module",
   "main": "./lib/index.js",