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

package/lib/types/api.d.ts

@@ -0,0 +1,574 @@
+/**
+ * The same-origin API surface shared by this package's two halves.
+ *
+ * The Host registers one prefix and dispatches on the trailing method name; the
+ * browser calls the same strings. Keeping them in one module is what stops the
+ * two halves drifting apart, which is exactly the failure this file was written
+ * to fix: the panel once called `/knowledge-base/config` while the Host served
+ * `/knowledge-base/api/config`.
+ *
+ * This module must stay dependency-free so both bundles can import it: the
+ * Client bundle rejects Node builtins and non-platform packages.
+ *
+ * @module @sparkelf/dsh-knowledge-base/api
+ */
+/** Prefix the Host registers and the browser calls. */
+export declare const KB_API_PREFIX = "/knowledge-base/api";
+/** Method names the Host dispatches on. */
+export declare const KB_API: {
+    /** Resolved layout plus whether the DataOps backend is wired. */
+    readonly config: "config";
+    /**
+     * Persist the operator's storage choices.
+     *
+     * Separate from {@link KB_API.config} because it is the only route here that writes
+     * deployment configuration: a read must never be able to change what a write controls.
+     */
+    readonly configSet: "config.set";
+    /** Aggregated view and index status. */
+    readonly status: "status";
+    /** Authorized paths for the calling user. */
+    readonly grants: "grants";
+    /** Grant one principal access to one path. */
+    readonly grant: "grant";
+    /** Revoke one previously granted path. */
+    readonly revoke: "revoke";
+    /** List the principals that can be granted, so the surface can offer a picker. */
+    readonly principals: "principals";
+    readonly roles: "roles";
+    readonly trash: "trash";
+    readonly trashRemove: "trash.remove";
+    readonly trashRestore: "trash.restore";
+    /** Search the mounted tree by file name and text. */
+    readonly search: "search";
+    /** List one directory level, with each entry's modification time. */
+    readonly list: "list";
+    /** Read one file for the preview, without needing a conversation session. */
+    readonly read: "read";
+    /** Rebuild the caller's visible tree from what DataOps resolves for them. */
+    readonly viewsSync: "views.sync";
+    /** Rescan the mounted tree and report its shape. */
+    readonly index: "index";
+    /**
+     * Report the mounted tree's per-directory shape.
+     *
+     * Separate from {@link KB_API.index}, which recounts and answers with a single
+     * total: this one answers with the rows the indexing table renders, so opening
+     * the page does not have to trigger a scan to have something to show.
+     */
+    readonly indexDirs: "index.dirs";
+    /**
+     * Start a document or folder in the authoritative tree.
+     *
+     * Not a per-user private space: the destination has no caller component, so a
+     * document created here is shared with everyone DataOps resolves as a reader of
+     * that path. That is the knowledge base's own semantic, and it is why the write
+     * needs write access rather than merely read.
+     */
+    readonly create: "create";
+    /**
+     * Replace one existing document's bytes.
+     *
+     * Kept separate from `create` because the two differ in what they must not do:
+     * a create refuses to overwrite, while an edit must write IN PLACE. Writing in
+     * place is the requirement, not an implementation detail -- the caller's view
+     * links this document to the authoritative copy by hardlink, and a
+     * write-temp-then-rename save (which is how the host's own editor saves) replaces
+     * the inode and silently leaves the view showing the old bytes.
+     */
+    readonly edit: "edit";
+    /**
+     * Record an edit that happened outside this plugin's write path.
+     *
+     * The host's file editor saves through its own route, so the knowledge base
+     * cannot intercept it without owning that editor. This route is the side channel:
+     * the page reports the save it observed, and the audit trail stays complete
+     * without the host's write path knowing the knowledge base exists.
+     */
+    readonly auditAppend: "audit.append";
+    /** Put one file's bytes into the authoritative tree under the same rules. */
+    readonly upload: "upload";
+    /**
+     * List the templates a reader can start from.
+     *
+     * A template is a DataOps wiki page whose category is `report_template`, so the
+     * Host relays `GET /api/resources/wiki/pages/templates` rather than keeping a
+     * second copy to keep in step.
+     */
+    readonly templates: "templates";
+    /**
+     * Add or replace one template: a document file plus its metadata.
+     *
+     * A template is exactly a document plus a small record describing it, so this
+     * route takes the file's text and the metadata in one body rather than modelling
+     * a second kind of object. The document is written through the same create/upload
+     * path a reader's own file uses, under a template directory the knowledge base
+     * owns, and the metadata goes beside it.
+     */
+    readonly templateSave: "template.save";
+    /** Remove one template: its document and its metadata record. */
+    readonly templateRemove: "template.remove";
+    /** Read the caller's pinned paths. */
+    readonly favoritesGet: "favorites.get";
+    readonly favoritesSet: "favorites.set";
+    readonly pinsGet: "pins.get";
+    /** Replace the caller's pinned paths. */
+    readonly pinsSet: "pins.set";
+    /**
+     * Read this knowledge base's review settings.
+     *
+     * Stored beside the pins and the view mode, in the caller's view directory. The answer
+     * defaults to review OFF, which is what a deployment that never opened the settings
+     * page must do.
+     */
+    readonly settingsGet: "settings.get";
+    /**
+     * Replace this knowledge base's review settings.
+     *
+     * Gated on write access rather than mere read: turning review on or off decides whether
+     * other people's contributions take effect immediately, which is an operator decision.
+     */
+    readonly settingsSet: "settings.set";
+    /**
+     * Read the audit trail for this knowledge base, newest first.
+     *
+     * Append-only on the Host side; this route only reads.
+     */
+    readonly auditList: "audit.list";
+    /**
+     * Rename one entry in place, keeping it in its own directory.
+     *
+     * Separate from `move` on purpose: that route deliberately concatenates the entry's
+     * CURRENT name onto the destination, so it cannot rename. Renaming is its own decision
+     * and gets its own check at the resulting path.
+     */
+    readonly rename: "rename";
+    /**
+     * Read one file as bytes for a save-to-disk, as opposed to `read` for on-screen text.
+     *
+     * Answers base64 so a binary file survives the JSON round trip; a markdown file uses
+     * the same route, because one download path is simpler than two.
+     */
+    readonly download: "download";
+    /**
+     * List the submissions waiting for review.
+     *
+     * Only meaningful when review is on, but it always answers: an empty queue is a
+     * valid state and the page shows it rather than hiding the section.
+     */
+    readonly pendingList: "pending.list";
+    /**
+     * Accept one submission, writing its bytes into the authoritative tree.
+     *
+     * Requires write access, like every other operation that changes shared content.
+     */
+    readonly pendingApprove: "pending.approve";
+    /**
+     * Refuse one submission and discard its bytes.
+     *
+     * Requires write access for the same reason: refusing someone else's contribution
+     * is a decision about shared content.
+     */
+    readonly pendingReject: "pending.reject";
+    /**
+     * Move or rename one entry inside the caller's tree.
+     *
+     * A rename rather than a copy, so the inode survives and every view's hardlink
+     * to it stays meaningful; the Host resynchronizes the caller's view afterwards,
+     * because a moved file's old path is a dead link until it does.
+     */
+    readonly copy: "copy";
+    readonly move: "move";
+    /** Read the caller's list/grid preference. */
+    readonly viewModeGet: "viewMode.get";
+    /** Replace the caller's list/grid preference. */
+    readonly viewModeSet: "viewMode.set";
+    /**
+     * Read which folders the caller had open in the explorer.
+     *
+     * Beside the layout preference for the same reason: it describes how this reader
+     * looks at the tree rather than what is in it, so it belongs to the caller's view
+     * instead of one browser's storage.
+     */
+    readonly treeStateGet: "treeState.get";
+    /** Replace the set of expanded folders. */
+    readonly treeStateSet: "treeState.set";
+    /** The ordered deployment steps and their recent runs. */
+    readonly deploySteps: "deploy.steps";
+    /** SSH hosts available as deployment targets. */
+    readonly deployHosts: "deploy.hosts";
+    /** Run one deployment step against one host. */
+    readonly deployRun: "deploy.run";
+};
+/** One method name. */
+export type KbApiMethod = (typeof KB_API)[keyof typeof KB_API];
+/** Absolute URL for one API method. */
+export declare function kbApiPath(method: KbApiMethod): string;
+/**
+ * Read a knowledge-base response as JSON without trusting it to BE JSON.
+ *
+ * Every route in this plugin answers JSON, but a response is not always this plugin's:
+ * a gateway, a proxy, an auth redirect, or a stopped DSH can all return HTML or plain
+ * text with a 2xx status. Calling `response.json()` on that throws a parser message like
+ * `Unexpected token 'D', "DataOps au"... is not valid JSON`, which then reached the page
+ * verbatim -- an internal parser complaint shown to a reader as if it were the document.
+ *
+ * This reads the body once as text and decides from the CONTENT whether it parsed, so a
+ * non-JSON answer becomes a sentence naming the status instead of a parser exception. The
+ * status is still surfaced, because "the server said no" and "the body was not JSON" are
+ * different problems an operator needs to tell apart.
+ * @param response - the fetch response.
+ * @returns The parsed body, or an object carrying a readable `error`.
+ */
+export declare function readKnowledgeJson<T extends Record<string, unknown>>(response: Response): Promise<T & {
+    error?: string;
+}>;
+/** Resolved layout as the panel renders it. */
+export interface KnowledgeConfigView {
+    /** Human-facing identifier of the storage host, empty when unconfigured. */
+    host: string;
+    /** Absolute path of the authoritative tree on the storage host. */
+    actualRoot: string;
+    /** Absolute path of the caller's view tree on the storage host. */
+    viewRoot: string;
+    /** Path where the view tree is mounted inside the container. */
+    mountPoint: string;
+    /** NFS export host, when the deployment uses the NFS transport. */
+    nfsServer?: string;
+    /** Whether a DataOps knowledge API base URL is configured. */
+    backendConfigured: boolean;
+    /** Why the backend probe failed, when it did. */
+    backendError?: {
+        message: string;
+        code?: string;
+    };
+    /** How a remote deployment reaches its share; absent means `nfs`. */
+    storageProtocol?: 'nfs' | 'sshfs';
+    /** SSHFS transport, present so the panel can show and edit what it will mount. */
+    ssh?: KnowledgeSshView;
+}
+/** One transport field the panel may persist. */
+export interface KnowledgeConfigWrite {
+    /** Storage shape to store. */
+    storageMode?: 'local' | 'remote';
+    /** Transport for a remote deployment. */
+    storageProtocol?: 'nfs' | 'sshfs';
+    /** NFS export host. */
+    nfsServer?: string;
+    /** SSHFS transport fields; the key is named by reference only. */
+    sshHost?: string;
+    sshUser?: string;
+    sshPort?: number;
+    sshRemotePath?: string;
+    sshMountOptions?: string;
+    sshKeyRef?: string;
+}
+/** What a config write actually stored, and what it could not. */
+export interface KnowledgeConfigWriteResult {
+    /** Fields written to the settings file. */
+    saved: string[];
+    /**
+     * True when the running deployment differs from what was just saved, so a restart is
+     * required before the change takes effect. The file is the record; the process read its
+     * configuration at startup.
+     */
+    restartRequired: boolean;
+    /** The config as it will read back after a restart. */
+    config: KnowledgeConfigView;
+    /** Fields refused, with the reason. */
+    refused?: {
+        field: string;
+        reason: string;
+    }[];
+}
+/**
+ * The SSHFS transport as the panel may see it.
+ *
+ * Every field here is safe to render: a host, a user, a port, a path, mount options, and
+ * a credential REFERENCE. The private key itself is never part of this shape -- there is
+ * no field it could travel in. `keyConfigured` is the resolved answer to "will the mount
+ * step find a key", which is the only thing the panel needs to know about it.
+ */
+export interface KnowledgeSshView {
+    /** Remote host, address or hostname. */
+    host: string;
+    /** Login user on that host. */
+    user: string;
+    /** TCP port the SSH daemon listens on. */
+    port: number;
+    /** Absolute path of the shared directory on the remote host. */
+    remotePath: string;
+    /** Extra `-o` options, as the operator typed them. */
+    mountOptions: string;
+    /** Name of the credential holding the private key. A reference, never the key. */
+    keyRef: string;
+    /** Whether that credential currently resolves to a usable key. */
+    keyConfigured: boolean;
+}
+/** Aggregated view and index status as the panel renders it. */
+export interface KnowledgeStatusView {
+    /**
+     * Which storage shape this deployment runs.
+     *
+     * `local` stores documents in the workspace itself; `remote` keeps the synchronized
+     * NFS shape. The settings page keys its whole storage section off this, so a reader
+     * never sees mount controls for a workspace that has no mount.
+     */
+    storageMode?: 'local' | 'remote';
+    /**
+     * How a remote deployment reaches its share.
+     *
+     * Reported for both modes so the panel can show the configured transport even while the
+     * deployment runs locally: a reader switching to remote needs to see what it will use
+     * before they commit to it.
+     */
+    storageProtocol?: 'nfs' | 'sshfs';
+    /**
+     * Who this page is acting as, as DataOps resolved them.
+     *
+     * Absent when the backend is unconfigured or did not answer. The page uses it to
+     * name the actor on editor saves, so the audit trail records a person rather than
+     * an anonymous edit.
+     *
+     * The organization path is optional because the backend may not report it: an older
+     * DataOps answers only `code`/`name`, and the tree then labels the department bucket
+     * with that single name exactly as it did before hierarchy existed. Code that
+     * assumed the path was present would break against such a backend.
+     */
+    caller?: {
+        userId: string;
+        label: string;
+        departmentCode?: string;
+        departmentName?: string;
+        departmentPathCodes?: string[];
+        departmentPathNames?: string[];
+    };
+    /** Visible file count, or null when the backend is not configured. */
+    visibleFiles: number | null;
+    /** ISO-8601 time of the last successful synchronization. */
+    lastSyncAt: string | null;
+    /** In-flight index state. */
+    indexing: {
+        running: boolean;
+        jobId?: string;
+        progress?: number;
+    };
+    /**
+     * Which of the two empty states applies when there is no file count.
+     *
+     * `null` for a count is compatible with a mount that is absent and with a pointer
+     * this plugin has not built yet, and those need different sentences: the first
+     * sends the reader to the deployment, the second resolves itself. The Host
+     * reports which one it is.
+     *
+     * Optional because a response from an older Host does not carry it; a reader that
+     * finds it absent falls back to the mount-not-present wording, which is the
+     * message that was correct before the two were told apart.
+     */
+    mountState?: 'mounted' | 'pointer-missing' | 'absent';
+    /**
+     * Whether the Host verified that this caller may manage grants.
+     *
+     * Decided on the Host by asking DataOps, and deliberately not derived here: a
+     * client-side decision would duplicate the policy in a process the user controls,
+     * where it governs rendering rather than access. Absent or false both mean "do not
+     * offer the surface", so a response from an older Host hides it rather than
+     * showing a menu whose writes the backend would reject.
+     */
+    canManageGrants?: boolean;
+}
+/** The principal kinds the DataOps backend accepts on a grant. */
+export type KnowledgeGrantSubjectType = 'user' | 'role' | 'department' | 'group';
+/**
+ * One grant as the permissions surface renders it.
+ *
+ * The shape mirrors what the backend stores, so the page can echo a row back when
+ * revoking it without keeping a second copy of the fields.
+ */
+export interface GrantView {
+    /** Stable row identifier. */
+    id: string;
+    /** Path the grant covers, 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: KnowledgeGrantSubjectType;
+    /** Principal id within its kind. */
+    principalId: string;
+    /** Permission the grant confers. */
+    action: string;
+    /** Who created the grant. */
+    grantedBy: string;
+    /** ISO-8601 creation time. */
+    grantedAt: string;
+}
+/** One deployment step as the browser receives it. */
+export interface DeployStepView {
+    id: string;
+    label: string;
+    timeoutMs: number;
+    commands: string[];
+}
+/** One recorded deployment run. */
+export interface DeployRunView {
+    stepId: string;
+    hostId: string;
+    state: 'running' | 'succeeded' | 'failed';
+    startedAt: string;
+    finishedAt: string | null;
+    log: string[];
+}
+/** One SSH host offered as a deployment target. */
+export interface DeployHostView {
+    id: string;
+    name: string;
+    hostname: string;
+    username: string;
+    port: number;
+    credentialConfigured: boolean;
+}
+/**
+ * The caller's pinned paths, as the browser renders them.
+ *
+ * Pins are a document-level preference rather than a per-device one, so they live
+ * in the caller's own view directory on the share rather than in browser storage:
+ * a reader who pins a folder on one machine expects it pinned on the next. The
+ * list is addressed by `relPath` only, because every path it may name has already
+ * been resolved as readable for this caller.
+ */
+export interface PinnedView {
+    /** Paths the caller pinned, relative to the mount point. */
+    relPaths: string[];
+    /**
+     * Paths that were dropped because the caller may no longer read them.
+     *
+     * Reported rather than silently discarded: a pin that disappears without a word
+     * reads as a bug, while a count explains a revoke.
+     */
+    dropped: string[];
+}
+/**
+ * The caller's favourited paths, as the browser renders them.
+ *
+ * A star marks a row the reader wanted to find again, so the list is addressed by
+ * `relPath` only: every entry has already been resolved as readable for this caller.
+ * Kept apart from {@link PinnedView} deliberately -- see `favoritesPathFor`.
+ */
+export interface FavoritesView {
+    /** Paths the caller starred, relative to the mount point. */
+    relPaths: string[];
+    /**
+     * Paths dropped because the caller may no longer read them.
+     *
+     * Reported rather than silently discarded, so a star that disappears after a
+     * revoke can be explained instead of looking like a bug.
+     */
+    dropped: string[];
+}
+/**
+ * One entry the caller may move, as the move route reports it.
+ *
+ * Returned instead of a bare boolean so the caller can tell a refusal apart from a
+ * move that did nothing: the route answers 403 for the first and 200 with both
+ * paths for the second.
+ */
+export interface MoveResultView {
+    /** The path the entry held before the move. */
+    from: string;
+    /** The path it holds now. */
+    to: string;
+    /**
+     * What the caller's view sync changed, so the surface can report a relink.
+     *
+     * A move changes two paths in the view -- the new one is linked and the old one
+     * is dropped -- and the reader is looking at the old one, so the count is the
+     * evidence that the tree they are about to re-read is current.
+     */
+    delta: {
+        linked: number;
+        unlinked: number;
+        unchanged: number;
+    };
+}
+/**
+ * The caller's list/grid preference.
+ *
+ * A document-level preference rather than a per-device one, stored beside the pins
+ * for the same reason: a reader who switches to the grid on one machine expects it
+ * on the next.
+ */
+export interface ViewModeView {
+    /** The stored layout. */
+    mode: 'list' | 'grid' | 'explorer';
+}
+/**
+ * The folders the caller had open in the explorer, as absolute paths.
+ *
+ * Absolute rather than tree-relative because that is the vocabulary the explorer
+ * speaks: it reports `onToggle` with the absolute path of the row and takes
+ * `expanded` the same way. Storing them in that form means neither side has to
+ * re-derive the root, and a folder that a grant revoke removed simply never
+ * matches a row again rather than pointing at some other directory's new occupant.
+ *
+ * An empty list is the correct answer both for "the reader has collapsed
+ * everything" and for "nothing was ever stored", which is why the two share one
+ * representation: the tree's default state IS all-collapsed.
+ */
+export interface TreeStateView {
+    /** Absolute paths of the folders the reader had expanded. */
+    expanded: string[];
+}
+/**
+ * One template: a document plus the metadata that describes it.
+ *
+ * Deliberately a flat record rather than a model with its own identity rules: the
+ * `id` is derived from the file name inside the template directory, so a template
+ * cannot exist without its document and deleting one cannot leave the other behind.
+ */
+export interface KnowledgeTemplateView {
+    /** Stable id, derived from the stored file's name. */
+    id: string;
+    /** Display name. */
+    title: string;
+    /** One-line description shown on the card. */
+    description: string;
+    /** Grouping label, e.g. `report` or `meeting`. */
+    category: string;
+    /** Free-form tags, already split. */
+    tags: string[];
+    /** The document's file name including its extension. */
+    fileName: string;
+    /** Extension without the dot, lower-cased; drives the card's file badge. */
+    extension: string;
+    /** Document size in bytes. */
+    bytes: number;
+    /** Last-modified instant, ISO-8601. */
+    updatedAt: string;
+    /** Where the document lives, relative to the knowledge root. */
+    relPath: string;
+}
+/** The template library as the Host answers it. */
+export interface KnowledgeTemplatesView {
+    /** Every stored template, newest first. */
+    templates: KnowledgeTemplateView[];
+    /** Set when the list was read but the store could not be (never both). */
+    error?: string;
+}
+/** The body of one template save. */
+export interface KnowledgeTemplateSaveInput {
+    /** Display name; also used to derive the file name when the document is new. */
+    title: string;
+    /** One-line description. */
+    description: string;
+    /** Grouping label. */
+    category: string;
+    /** Free-form tags. */
+    tags: string[];
+    /** The document's text. Required when creating, omitted when only metadata changes. */
+    content?: string;
+    /** The file name to store, including its extension. */
+    fileName: string;
+    /** Set when editing an existing template, so its document is replaced in place. */
+    id?: string;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * The audit surface: what is waiting for a decision, and what has already happened.
+ *
+ * These two belong on one page and were previously two sections of Settings, which
+ * was the wrong shelf for either. A review queue is a WORKLIST -- something an
+ * operator opens to get through -- and a trail is a RECORD of what the worklist
+ * already settled. Setting them under the review switch made the viewer scroll past
+ * configuration to find today's arrivals, and put a record of the past next to a
+ * control that governs the future.
+ *
+ * They share a page because they are one loop seen from two ends: a submission
+ * entering, and a decision leaving. Deciding in the first tab appends to the second,
+ * so keeping both on screen (one click apart) is what makes the loop legible.
+ *
+ * Both readings are loaded together and the tabs only choose which table is drawn,
+ * so the two can never show different answers to "is the queue empty".
+ *
+ * @module @sparkelf/dsh-knowledge-base/client
+ */
+/** Props for the audit surface. */
+export interface KnowledgeAuditProps {
+    /** Locale-bound copy resolver for this package's namespace. */
+    t: (key: string) => string;
+}
+/**
+ * Format an audit instant for a table cell.
+ *
+ * DataOps' own surfaces print `YYYY/MM/DD HH:mm`, and a reader comparing this trail
+ * against one of those should see the same date rather than a second dialect.
+ * @param value - ISO timestamp.
+ * @returns The formatted instant, or a dash when unparseable.
+ */
+export declare function formatAuditWhen(value: string): string;
+/**
+ * Render the audit page: one tab per end of the review loop.
+ * @param props - copy resolver.
+ * @returns The audit surface.
+ */
+export declare function KnowledgeAudit(props: KnowledgeAuditProps): import("react").JSX.Element;