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

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/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;

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

@@ -0,0 +1,27 @@
+/**
+ * Knowledge-base Client plugin.
+ *
+ * Registers three official DSH surfaces:
+ * - `sidebar.panellist` gives the left-sidebar menu entry.
+ * - The matching `main` key gives the management page the entry selects. The
+ *   page replaces the conversation area and carries its own master-detail
+ *   layout: a menu and the knowledge tree on the left, a content region on the
+ *   right.
+ * - `settings.section` gives the connection and status page.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type KnowledgeKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'settings.knowledgeBase': KnowledgeKey;
+    }
+}
+/** Client services required for these contributions. */
+export declare const inject: string[];
+/**
+ * Register the knowledge-base navigation entry and Settings section.
+ * @param ctx - DSH client context with locale and slot registries.
+ */
+export declare function apply(ctx: ClientContext): void;

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

@@ -0,0 +1,23 @@
+/**
+ * Copy for the Share dialog.
+ *
+ * The context menu's own labels are NOT here: they are `action*` keys in the shared
+ * namespace (`locales.ts`), because they are the same sentences the rest of the knowledge
+ * surface uses for the same verbs, and two copies of one sentence drift. What stays local
+ * is the dialog's copy, which is longer, dialog-specific, and not addressable from the
+ * settings namespace -- putting it in `locales.ts` would also mean touching a file several
+ * other changes are editing at once.
+ *
+ * `SHARE_ZH` is typed as the English record, so a key added to one and forgotten in the
+ * other fails to compile rather than rendering an English sentence inside a Chinese
+ * dialog.
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+import type { ShareDialogCopy } from './KnowledgeShareDialog.tsx';
+/**
+ * Resolve the share-dialog copy for one locale tag.
+ * @param locale - the reader's locale tag, as the page received it.
+ * @returns The English or Chinese record.
+ */
+export declare function shareCopyFor(locale: string | undefined): ShareDialogCopy;