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

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

@@ -0,0 +1,83 @@
+/**
+ * The knowledge base's search: find a document, then open it.
+ *
+ * The field itself lives in the page's rail, not here, because it is navigation:
+ * a reader reaches "find a document" the same way they reach the permission or
+ * indexing section, and a menu row labelled "Search" asked them to click through
+ * to a box before they could type. `useKnowledgeSearch` owns the one piece of
+ * state both halves need, so the rail's field and this result list cannot
+ * disagree about which term produced which hits.
+ *
+ * This replaces an earlier summary of mount state, which answered a question the
+ * operator had not asked: the mount path, the file count, and a sync timestamp are
+ * facts about the deployment, while the reason to open this page is to locate a
+ * document.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One result row, as the Host returns it. */
+interface SearchHit {
+    /** Path relative to the mount point. */
+    relPath: string;
+    /** File name alone. */
+    name: string;
+    /** Whether the term matched the file body rather than only its name. */
+    inContent: boolean;
+    /** Matching line, when the term was found inside the file. */
+    line?: string;
+    /** 1-based line number of {@link line}. */
+    lineNumber?: number;
+    /** Last-modified instant in Unix ms, when the Host could stat the file. */
+    mtimeMs?: number;
+}
+/** What {@link useKnowledgeSearch} hands back to the rail and the result list. */
+export interface KnowledgeSearchState {
+    /** Current term, owned here so the field and the results read one value. */
+    term: string;
+    /** Replace the term. */
+    setTerm: (value: string) => void;
+    /** Hits for the settled term, empty while idle. */
+    hits: SearchHit[];
+    /** Which surface the result list should draw. */
+    status: 'idle' | 'searching' | 'done' | 'error';
+    /** Index of the keyboard-highlighted row. */
+    active: number;
+    /** Highlight a row, so pointer movement and the arrow keys agree. */
+    setActive: (index: number) => void;
+    /** Arrow-key handling for the rail's field. */
+    onKeyDown: (event: {
+        key: string;
+        preventDefault: () => void;
+    }) => void;
+}
+/**
+ * Own the search term, its debounced request, and the highlighted row.
+ *
+ * Extracted rather than left inside the result component because the field it is
+ * driven by now sits in the rail: a hook keeps one owner for the term while the
+ * input and the list render in different regions of the page.
+ *
+ * @param mountPoint - the mount to search; empty while the page is still loading.
+ * @returns The term, its hits, and the keyboard handler for the field.
+ */
+export declare function useKnowledgeSearch(mountPoint: string): KnowledgeSearchState;
+/** Props for the result list. */
+export interface KnowledgeSearchProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Term and hits, owned by {@link useKnowledgeSearch}. */
+    search: KnowledgeSearchState;
+    /** Called with the chosen path so the page can show its preview. */
+    onOpen: (path: string) => void;
+    /** Locale tag, used to render dates and relative spans in the reader's language. */
+    locale?: string;
+    /** Shown while no term is entered, so the surface is useful before searching. */
+    idle?: React.ReactNode;
+}
+/**
+ * Render the results for the rail's search field.
+ * @param props - copy resolver, the search state, and the open callback.
+ * @returns The result list, or the idle content when nothing is typed.
+ */
+export declare function KnowledgeSearch(props: KnowledgeSearchProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * The rail's section bands: a name with an optional trailing glyph cluster.
+ *
+ * Copied from the shell's own browser header,
+ * `ui-workspace/src/client/rows/WorkspaceBrowser.module.css` (`.sectionHeader` /
+ * `.sectionLabel` + `.iconButton`). That band is the one a reader compares this
+ * page against, because it is what the right sidebar shows for 工作区 in the same
+ * window. The metrics were also measured live on the running shell on 2026-10-17
+ * and agree with the stylesheet exactly: a 36px row, `gap: 4px`,
+ * `padding-left: 4px`, a label at 14px/20px, and 28x28 buttons on an 8px radius.
+ *
+ * Two details are the stylesheet's own and easy to get wrong:
+ *
+ * - The label is *not* bold. `--dsw-font-s-14` is 14px/22px, while this band's
+ *   line-height is an explicit 20px, so the shorthand is paired with the measured
+ *   line-height rather than allowed to win.
+ * - The name inherits the band's ink, which the stylesheet sets to
+ *   `--dsw-alias-label-tertiary`; the buttons carry
+ *   `--dsw-alias-label-secondary` of their own. Measured live, the name is
+ *   `#adb2b8` and the buttons `#cfd3d6`, which is that same split.
+ *
+ * The band is a plain `div` with a name span and a button cluster rather than a
+ * heading element: it labels a region that already carries its own landmark, and
+ * a second heading level here would put an unlabelled h3 in the heading outline.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { ReactNode } from 'react';
+/** Props for one section band. */
+export interface KnowledgeSectionHeaderProps {
+    /** Localized section name, rendered at the measured 14px/20px. */
+    name: ReactNode;
+    /**
+     * The trailing controls.
+     *
+     * Optional because the pinned band's only control is the fold toggle, while
+     * the tree band carries three; a band with none renders the name alone.
+     */
+    actions?: ReactNode;
+    /** Extra class for the band, so a caller can add its own spacing. */
+    className?: string;
+}
+/**
+ * Render one section band.
+ * @param props - the name, its trailing controls, and optional placement.
+ * @returns The band.
+ */
+export declare function KnowledgeSectionHeader(props: KnowledgeSectionHeaderProps): import("react").JSX.Element;
+/** Props for one 28px glyph button in a band's cluster. */
+export interface KnowledgeIconButtonProps {
+    /** Localized accessible name; also the tooltip, as the shell's own buttons do. */
+    label: string;
+    /** The glyph, sized by the caller to the band's 16px step. */
+    children: ReactNode;
+    /** Invoked on activation. */
+    onClick: () => void;
+    /** Whether the control refuses activation. */
+    disabled?: boolean;
+    /** Whether the control's action is currently engaged, so it can report `aria-pressed`. */
+    pressed?: boolean;
+}
+/**
+ * Render one glyph button.
+ *
+ * A native button with the band's own class rather than the `Button` primitive:
+ * that primitive is the product's labelled action at a 36px control height, while
+ * this is the 28x28 icon control the band is specified around.
+ * @param props - the accessible name, glyph, and activation handler.
+ * @returns The button.
+ */
+export declare function KnowledgeIconButton(props: KnowledgeIconButtonProps): import("react").JSX.Element;

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

@@ -0,0 +1,45 @@
+/**
+ * The batch action bar that closes a multi-select session in the tree.
+ *
+ * Copied from the explorer's own `explorerSelectionBar` (`FileTree.tsx:2238`,
+ * `sidebar.module.css:932`): the same `role="toolbar"`, the same sticky bottom
+ * position, the same 28px minimum height, the same `bg-layer-2` fill and 4px
+ * radius, and the same split between a shrinking count on the left and the
+ * actions on the right. It is a copy rather than a second design because a reader
+ * sees that bar in this window's right sidebar, and the two are the same gesture.
+ *
+ * The actions are deliberately only the two this build can actually perform.
+ * Delete is absent because the trash has no decided retention or ownership
+ * semantics, and a destructive button wired to an undecided policy is worse than
+ * no button: the explorer's own bar carries delete, so its absence here is a
+ * decision rather than an oversight.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the batch bar. */
+export interface KnowledgeSelectionBarProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string, params?: Record<string, string | number>) => string;
+    /** How many rows are selected, for the count and the label. */
+    count: number;
+    /** Move every selected path into one folder the reader picks. */
+    onMove: () => void;
+    /** Pin every selected path. */
+    onPin: () => void;
+    /** Drop the selection. */
+    onClear: () => void;
+    /**
+     * Whether a batch write is in flight, so the actions can be held.
+     *
+     * A second click while the first is still moving would send the same paths twice,
+     * and the second would be refused as a missing source -- an error the reader
+     * would read as the feature being broken.
+     */
+    busy?: boolean;
+}
+/**
+ * Render the batch bar for the current selection.
+ * @param props - the count, the three actions, and the busy flag.
+ * @returns The toolbar.
+ */
+export declare function KnowledgeSelectionBar(props: KnowledgeSelectionBarProps): import("react").JSX.Element;

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

@@ -0,0 +1,96 @@
+/**
+ * TODO: this page is unreachable from the real entry, and needs a decision.
+ *
+ * Verified by driving the deployed product on 2026-10-21, not by reading the code:
+ * entering 知识库 and clicking 「设置」 in its own rail opens the DSH GLOBAL settings
+ * dialog (left nav: 通用设置/模型/内置插件/Agent 预设/DataOps/备份/知识库/插件市场/
+ * 侧边卡片), never this component. The rail row sets `selection.kind = 'settings'`,
+ * which `KnowledgePanel.tsx` renders as this surface, but the click that a reader can
+ * actually reach is the shell's own settings entry, so nothing in the real UI leads
+ * here. The review switch below therefore has no user-facing effect today.
+ *
+ * Deliberately NOT deleted: removing this file, the `rendered.kind === 'settings'`
+ * branch in `KnowledgePanel.tsx` and the `menu.settings` rail row is a cross-file
+ * structural change, and the choice between "delete the page" and "give it a real
+ * entry point" is a product decision rather than a cleanup. Left as-is with this note
+ * so the next change starts from the measured fact instead of re-deriving it.
+ *
+ * What WAS moved: the MinerU service address. It lived here for one round and was
+ * invisible to readers for exactly this reason; it now renders in
+ * `KnowledgeSettingsSection.tsx` (DSH global settings → 知识库), which is reachable.
+ */
+/**
+ * The settings surface of the management page.
+ *
+ * This page is now only the review switch: a DECISION about whether other people's
+ * contributions take effect immediately, so it is a control and it needs write
+ * access. The queue that decision governs and the trail of what it settled both
+ * moved to the Audit page, which is the surface an operator opens to get through
+ * work; parking a worklist under a configuration switch made them scroll past the
+ * setting to reach today's arrivals, and left two duplicate entry points pointing
+ * at the same two tables.
+ *
+ * The switch ships OFF. That is the product decision, not a default that drifted: an
+ * operator who never opens this page keeps the behaviour they had, and turning review
+ * on is a deliberate act with a visible consequence.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** This knowledge base's review settings, as the Host reports them. */
+export interface KnowledgeSettingsView {
+    /** Whether a write must be reviewed before it counts as published. */
+    reviewRequired: boolean;
+    /**
+     * MinerU's full base address, or `''` to derive it from the configured port.
+     *
+     * Absent from an older Host's answer, which reads as `''`: the field then shows
+     * "derived" rather than a value the Host never sent.
+     */
+    mineruBaseUrl?: string;
+}
+/** One recorded change, as the Host reports it. */
+export interface KnowledgeAuditEntryView {
+    /** ISO timestamp of the action. */
+    at: string;
+    /** DataOps user id that performed it: the identity the trail is checked against. */
+    actor: string;
+    /**
+     * That user's display name, when the entry carries one.
+     *
+     * Absent on entries written before it was recorded; the column falls back to the
+     * id so an old line still identifies its actor.
+     */
+    actorLabel?: string;
+    /** What they did. Mirrors the Host's own action union. */
+    action: 'create' | 'upload' | 'move' | 'approve' | 'reject' | 'edit';
+    /** The path the action concerned. */
+    relPath: string;
+    /** For a move, the destination path. */
+    toRelPath?: string;
+    /** Whether it took effect immediately or was parked for review or refused. */
+    outcome: 'applied' | 'pending' | 'rejected';
+}
+/** Props for the settings surface. */
+export interface KnowledgeSettingsProps {
+    /** Locale-bound copy for this package's namespace. */
+    t: (key: string) => string;
+}
+/** One submission waiting for review, as the Host reports it. */
+export interface PendingWriteView {
+    /** The parking name a decision is made against. */
+    name: string;
+    /** Who submitted it. */
+    userId: string;
+    /** The path it wants to occupy. */
+    relPath: string;
+    /** When it was submitted. */
+    at: string;
+    /** Size of the submitted bytes. */
+    bytes: number;
+}
+/**
+ * Render the review switch and the audit trail.
+ * @param props - copy resolver.
+ * @returns The settings surface.
+ */
+export declare function KnowledgeSettings(props: KnowledgeSettingsProps): import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { en } from './locales.ts';
+/** Values injected by the DSH Settings slot. */
+export interface KnowledgeSettingsInjected {
+    /** Translate one knowledge-base message key. */
+    t: (key: keyof typeof en) => string;
+}
+/** Props accepted by the injected Settings section. */
+export type KnowledgeSettingsProps = Partial<InjectFace<KnowledgeSettingsInjected>>;
+/**
+ * Render the knowledge-base connection, resolved paths, status, the read-only
+ * authorization summary, and the deployment wizard.
+ *
+ * Authorization itself is deliberately absent: DataOps owns grants, and this
+ * panel only reports what the backend says (AGENTS.md "Managed DataOps
+ * Authorization" forbids replicating that policy in a plugin).
+ *
+ * @param props - Settings slot injection values.
+ * @returns The localized Settings section, or nothing before injection.
+ */
+export declare function KnowledgeSettingsSection(props: KnowledgeSettingsProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,70 @@
+/**
+ * The Share dialog the knowledge tree's context menu opens.
+ *
+ * Sharing is a grant, and the grant route already exists: this dialog only chooses
+ * WHO receives it. The principal directory behind the picker is the same one the
+ * permission table reads, reached through the same `principals` route, so a reader
+ * who can grant from either surface picks from one list rather than two that can
+ * disagree.
+ *
+ * The picker is a text field plus a filtered list rather than a `<select>`: a real
+ * deployment has hundreds of people, and a closed control makes finding one a
+ * scroll. Filtering is local over the directory the Host already returned, so
+ * typing costs no round trip and stays responsive while a slow directory is still
+ * loading.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One selectable principal, as the Host's directory reports it. */
+export interface SharePrincipal {
+    /** Stable id the grant names. */
+    id: string;
+    /** What a reader recognises it by: a person's name, a role's title. */
+    label: string;
+    /** Optional second line: department, email, or whatever distinguishes two like-named ids. */
+    detail?: string;
+}
+/** The copy this dialog needs, so it renders in the reader's language. */
+export interface ShareDialogCopy {
+    title: string;
+    intro: string;
+    subjectType: string;
+    search: string;
+    searchPlaceholder: string;
+    noMatch: string;
+    loading: string;
+    empty: string;
+    cancel: string;
+    confirm: string;
+    working: string;
+    permission: string;
+    actionRead: string;
+    actionWrite: string;
+    actionManage: string;
+    chosen: string;
+    failed: string;
+    directoryFailed: string;
+    kind_user: string;
+    kind_role: string;
+    kind_department: string;
+    kind_group: string;
+}
+/** Props for the share dialog. */
+export interface KnowledgeShareDialogProps {
+    /** The path being shared, relative to the knowledge root, or null when closed. */
+    relPath: string | null;
+    /** Whether that path is a directory; only used to word the intro. */
+    isDir: boolean;
+    /** Locale-bound copy for this dialog. */
+    copy: ShareDialogCopy;
+    /** Close the dialog. */
+    onClose: () => void;
+    /** Called after a grant landed, so the page can refresh its permission view. */
+    onShared?: () => void;
+}
+/**
+ * The Share dialog.
+ * @param props - the target path, the copy, and the callbacks.
+ * @returns The modal, or nothing while it is closed.
+ */
+export declare function KnowledgeShareDialog(props: KnowledgeShareDialogProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,43 @@
+/**
+ * The template library: a card grid in an official dialog, with a maintenance side.
+ *
+ * A template is a document plus the few facts that describe it -- name, one-line
+ * description, category, optional tags. That is the whole model, and it is why the
+ * store is a directory of documents next to one JSON index rather than a table: the
+ * file IS the template, and the index only says what to call it.
+ *
+ * Two jobs live here, because they are two readings of the same list:
+ *
+ * - USING a template. A card's primary action copies the template's document into a
+ *   directory the reader picks, through the same upload route any new document uses,
+ *   then opens it. Nothing about a template is special enough to need its own write
+ *   path.
+ * - MAINTAINING the list. Adding a template is "choose a document, fill in the
+ *   metadata"; editing is the same form with the file already stored; taking one
+ *   offline removes the record and its document.
+ *
+ * The empty states are the honest ones: "nothing stored yet" and "could not read the
+ * store" are different facts and say so separately, because a reader told the library
+ * is empty will believe it.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the template library. */
+export interface KnowledgeTemplatesProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+    /** Close the dialog. */
+    onClose: () => void;
+    /** The knowledge root, for the "use this template" destination default. */
+    mountPoint?: string;
+    /** The caller's id, so the destination default prefers their own folder. */
+    callerId?: string;
+    /** Open a document once it has been created from a template. */
+    onOpen?: (relPath: string) => void;
+}
+/**
+ * Render the template library.
+ * @param props - copy resolver, the knowledge root, and the close handler.
+ * @returns The dialog.
+ */
+export declare function KnowledgeTemplates(props: KnowledgeTemplatesProps): import("react").JSX.Element;

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

@@ -0,0 +1,62 @@
+/**
+ * The Trash surface: what this caller removed, and the way back.
+ *
+ * ## What a removal is here
+ *
+ * Removing a document does not delete it. A view is hardlinks into one shared tree,
+ * so unlinking the caller's own link would be indistinguishable from a revoked grant
+ * and the next sync would put the link back. The removal is therefore recorded as a
+ * tombstone that filters this caller's view, and restoring deletes the note. See
+ * `src/trash.ts` for the full reasoning.
+ *
+ * ## Why restore can bring back nothing
+ *
+ * A grant can be withdrawn while a document sits in the trash. Restoring it then
+ * rebuilds the view without that document, which is the correct outcome and one the
+ * page has to say out loud -- a Restore button that appears to do nothing reads as a
+ * broken page.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the Trash surface. */
+export interface KnowledgeTrashProps {
+    /** Locale-bound copy resolver. */
+    t: (key: string) => string;
+}
+/** One removed path, as the route reports it. */
+interface TrashEntry {
+    /** Path relative to the knowledge root, in view coordinates. */
+    relPath: string;
+    /** Whether the removed entry was a file or a directory. */
+    kind: 'file' | 'directory';
+    /** Display name of whoever removed it. */
+    removedBy: string;
+    /** ISO-8601 instant of removal. */
+    removedAt: string;
+    /** Where it used to sit. */
+    originalPath: string;
+}
+/**
+ * Format one removal instant for a row.
+ *
+ * @param value - ISO-8601 instant from the route.
+ * @param locale - BCP-47 tag the browser should format in.
+ * @returns the local date and time, or the raw value when it cannot be read.
+ */
+export declare function formatRemovedAt(value: string, locale?: string): string;
+/**
+ * The last segment of a view path, which is the name a reader recognises.
+ *
+ * @param relPath - path in view coordinates.
+ * @returns that segment, or the whole path when it holds no separator.
+ */
+export declare function entryNameOf(relPath: string): string;
+/**
+ * Render the Trash surface.
+ *
+ * @param props - copy resolver.
+ * @returns The trash table, its empty state, and a restore action per row.
+ */
+export declare function KnowledgeTrash(props: KnowledgeTrashProps): import("react").JSX.Element;
+/** One removed path, re-exported for callers that build their own table. */
+export type { TrashEntry };

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

@@ -0,0 +1,37 @@
+/**
+ * Glyphs for the management page's own menu rows.
+ *
+ * These are the product's own icon components, not hand-drawn paths: the icon set
+ * already draws each glyph on the product grid with the product stroke weights
+ * (`ICON_REGULAR_STROKE` 1, `ICON_MEDIUM_STROKE` 1.3), and a local SVG with its own
+ * stroke reads noticeably heavier beside them. Colour rides `currentColor`, so a
+ * row's own text colour drives the glyph and no row needs an icon-specific rule.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** One rail section id, matching a selection kind. */
+export type SectionKind = 'home' | 'permissions' | 'indexing' | 'trash' | 'audit' | 'settings';
+/**
+ * The glyph matching one rail section.
+ *
+ * Kept as a map rather than a switch so the menu can render a row per entry and
+ * stay a single expression. The document glyph stands for Home because that is
+ * what the surface holds, and it is the same mark the left sidebar uses for this
+ * plugin, so the entry reads consistently in both rails.
+ * @param kind - section id, matching the selection kind.
+ * @param size - glyph size.
+ * @returns The glyph element.
+ */
+export declare function sectionGlyph(kind: SectionKind, size?: number): import("react").JSX.Element;
+/**
+ * The brand mark at the rail's top-left.
+ *
+ * The same glyph the left sidebar shows for this plugin, at the shell's menu-icon
+ * size rather than a rail-sized one: this row is a page header, and the sidebar's
+ * own larger step belongs to the global rail rather than to a page inside it.
+ * @param props - whether the rail is folded, which drops the mark to icon size.
+ * @returns The brand glyph.
+ */
+export declare function KnowledgeMenuBrand(props: {
+    folded: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,40 @@
+/**
+ * Ordering for the audit trail.
+ *
+ * Only the ordering lives here. Paging is the shared `paging.ts` utility that the other
+ * tables in this package use, adopted rather than duplicated: two implementations of
+ * "slice a page and clamp it" drift, and the one that is not used by the table next door
+ * is the one that gets the fix.
+ *
+ * The order is a correctness rule, not a presentation detail. The Host happens to append
+ * newest-last to its log, so a table that drew the array as received would look right
+ * until the writer changed. The reader's question is "what happened most recently", and
+ * that answer is computed here from the timestamps.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** The fields the ordering rule needs. */
+export interface AuditRow {
+    /** ISO-8601 instant the row records. */
+    at: string;
+    /** Path the action concerned, used as the tie-breaker. */
+    relPath: string;
+    /** What was done, used as the second tie-breaker. */
+    action: string;
+    /** Destination for a move, used as the last tie-breaker. */
+    toRelPath?: string;
+}
+/**
+ * Order rows newest first, with a stable tie-break.
+ *
+ * The secondary keys are what stop rows from swapping places between renders when several
+ * share an instant -- the normal case for a batch, where one action writes several rows
+ * with the same `at`. Without them the platform sort could order equal keys either way,
+ * and a reader paging forward would see a row twice or not at all.
+ *
+ * Ordering is total: `relPath`, then `action`, then `toRelPath` are all compared, and two
+ * rows equal in every one of those are indistinguishable to this table anyway.
+ * @param rows - the rows as received.
+ * @returns A new array; the input is not mutated.
+ */
+export declare function sortAuditRows<T extends AuditRow>(rows: readonly T[]): T[];

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

@@ -0,0 +1,57 @@
+/**
+ * The pure half of the tree's folder labels: which rows print a name instead of a slug.
+ *
+ * Kept apart from the rendering module for the reason stated in `permissionRows.ts`:
+ * a component module reaches the primitives package, which imports CSS, and a Node test
+ * runner cannot load a `.css` file. The label rules are the part worth testing without a
+ * DOM, so they live where a plain import can reach them.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client/departmentFolders
+ */
+/** The reader's own organization chain, as the Host reports it. */
+export interface DepartmentPath {
+    /** Codes from the organization root down to the caller's department. */
+    codes: readonly string[];
+    /** Display names, index-aligned with {@link codes}. */
+    names: readonly string[];
+}
+/**
+ * Tree-relative paths of the caller's own department chain, mapped to their names.
+ *
+ * The department bucket stores folders by code (`nanning-psb`), because a code is a
+ * stable slug: renaming a department cannot move a document. The reader, though, knows
+ * their organization by name, so those same rows have to print 「南宁市公安局」 rather
+ * than the slug.
+ *
+ * One entry per LEVEL rather than one for the leaf: the reader walks
+ * 「部门」 → 「南宁市公安局」 → 「数字侦察支队」 → 「数据实战大队」, so each of those
+ * three rows needs its own name.
+ *
+ * Only the caller's own chain is translated. A peer department's folder keeps printing
+ * its code, because this build has no name for it: the whole organization tree is
+ * readable only by an administrator, and deriving a "name" from a slug would put an
+ * invented label in front of the reader.
+ *
+ * A mismatched pair is refused whole rather than zipped to the shorter length: a
+ * partially labelled chain would put a correct name on one row and a raw code on the
+ * next, which reads as a missing department rather than as a missing translation.
+ *
+ * @param codes - codes from the organization root down, as DataOps reported them.
+ * @param names - display names, index-aligned.
+ * @returns The lookup keyed by tree-relative path, or undefined when nothing is usable.
+ */
+export declare function departmentPathLabels(codes: readonly string[] | undefined, names: readonly string[] | undefined): ReadonlyMap<string, string> | undefined;
+/**
+ * Resolve one tree-relative path to its printed label.
+ *
+ * Bucket labels are consulted first. The two maps address different rows today
+ * (`department` for the bucket, `department/<code>` and deeper for the chain), so the
+ * order changes no current label; it states that the audience name of a bucket is the
+ * one thing a data value must not override.
+ *
+ * @param relPath - path relative to the knowledge root.
+ * @param bucketLabels - the three audience names, keyed the same way.
+ * @param chainLabels - the caller's department chain, from {@link departmentPathLabels}.
+ * @returns The label to print, or undefined to print the row's own name.
+ */
+export declare function folderLabelOf(relPath: string, bucketLabels: Readonly<Record<string, string>> | undefined, chainLabels: ReadonlyMap<string, string> | undefined): string | undefined;

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

@@ -0,0 +1,34 @@
+/**
+ * Whether a deployment has anything the deployment wizard could act on.
+ *
+ * Its own module rather than a helper inside the settings component because the
+ * component imports CSS modules, and a test that wants to CALL this decision cannot
+ * load them. Keeping the predicate dependency-free means the rule is exercised
+ * directly instead of being matched as text in the file that happens to use it --
+ * an assertion on source text cannot notice an inverted branch.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/**
+ * Decide whether to render the deployment wizard.
+ *
+ * Every step in the plan executes ON A REMOTE HOST: the Host's `deploy.run` route
+ * refuses a request without a `hostId` ("Steps mutate a remote host"), and the MinerU
+ * steps are shell run there too -- they read the remote `/etc/os-release`, remote
+ * `uv`, remote `docker`. So the wizard is not an NFS-only block that a local
+ * deployment skips in part; with no SSH host configured it has nothing that can run,
+ * and seven disabled buttons are seven dead controls.
+ *
+ * A configured host is what makes the block meaningful, so that is the primary test.
+ * The deployment's own declared mode is the fallback: a `remote` deployment is one
+ * that intends to sync, so it keeps the wizard even before a host row exists -- the
+ * host list may be empty for a reason the reader can fix, and hiding the wizard would
+ * remove the only place that says so.
+ *
+ * A missing or unrecognised mode counts as `local`: the conservative direction,
+ * because local is the shape where the buttons would be a lie.
+ * @param hosts - the configured SSH hosts, as `deploy.hosts` reports them.
+ * @param storageMode - the deployment's declared mode, as `status` reports it.
+ * @returns true when the wizard has a remote target to act on.
+ */
+export declare function hasDeployTarget(hosts: readonly unknown[], storageMode: 'local' | 'remote' | undefined): boolean;