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

package/lib/types/permissions.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Five knowledge-base permissions and the roles that bundle them.
+ *
+ * A knowledge base needs one vocabulary everyone can agree on before it can have a
+ * permission screen. DataOps already owns the enforcement — this module does NOT
+ * re-decide who may read a path. What it adds is the product's own vocabulary on
+ * top of that enforcement:
+ *
+ * - **Five actions**, not three. An editor who may add a document is not
+ *   automatically allowed to delete one, so `create` and `delete` stay separate.
+ *   `all` exists because "give this person everything on this folder" is the
+ *   common case, and spelling it as four grants invites three of them being
+ *   forgotten.
+ * - **Two built-in roles** that are scoped here rather than in DataOps, because
+ *   "super administrator" means super-administrator-of-the-knowledge-base, not of
+ *   the platform. Treating it as a global DataOps role would hand out far more
+ *   than the label promises.
+ *
+ * ## The one rule that keeps this honest
+ *
+ * {@link permissionToDataOpsActions} only ever expresses a requirement, and
+ * {@link dataOpsActionsToPermissions} only ever NARROWS one. A permission the
+ * product shows must be one DataOps can enforce; when the two disagree the
+ * narrower answer wins, because showing a permission that will be refused is
+ * worse than not showing it.
+ *
+ * @module @sparkelf/dsh-knowledge-base/permissions
+ */
+/**
+ * One action a caller can hold on a knowledge path.
+ *
+ * `all` is deliberately last and deliberately not a fifth privilege: it is the
+ * union of the four before it. {@link expandActions} is the only correct way to
+ * read it.
+ */
+export declare const KNOWLEDGE_ACTIONS: readonly ["read", "create", "update", "delete", "all"];
+/** One knowledge action. */
+export type KnowledgeAction = typeof KNOWLEDGE_ACTIONS[number];
+/** The four concrete actions `all` stands for, in the order a UI should show them. */
+export declare const CONCRETE_ACTIONS: readonly ["read", "create", "update", "delete"];
+/** One concrete action, never `all`. */
+export type ConcreteKnowledgeAction = typeof CONCRETE_ACTIONS[number];
+/** Display name per action, for the permission screen. */
+export declare const ACTION_LABELS: Readonly<Record<KnowledgeAction, {
+    zh: string;
+    en: string;
+}>>;
+/**
+ * Whether a value names a knowledge action.
+ *
+ * @param value - candidate, typically read from a request body.
+ * @returns true when it is one of {@link KNOWLEDGE_ACTIONS}.
+ */
+export declare function isKnowledgeAction(value: unknown): value is KnowledgeAction;
+/**
+ * Expand any action set into the concrete actions it grants.
+ *
+ * `all` becomes the four concrete actions; anything else passes through. The
+ * result is de-duplicated and ordered by {@link CONCRETE_ACTIONS}, so two callers
+ * holding the same privileges always produce the same list and a comparison does
+ * not depend on input order.
+ *
+ * @param actions - whatever a grant or a request holds.
+ * @returns the concrete actions, ordered and unique.
+ */
+export declare function expandActions(actions: readonly KnowledgeAction[]): ConcreteKnowledgeAction[];
+/**
+ * Collapse concrete actions back into the shortest describing set.
+ *
+ * The inverse of {@link expandActions}: four concrete actions answer `['all']`,
+ * because that is what the grant table should store and what the UI should show.
+ * A partial set stays explicit so nothing looks broader than it is.
+ *
+ * @param actions - any actions, including `all`.
+ * @returns `['all']` when everything is held, else the concrete subset.
+ */
+export declare function collapseActions(actions: readonly KnowledgeAction[]): KnowledgeAction[];
+/**
+ * Whether a held set covers every action another set requires.
+ *
+ * Used by the permission screen to answer "does this grant already give them
+ * that", and by the role editor to refuse a downgrade that was meant to be a
+ * no-op.
+ *
+ * @param held - actions the caller currently has.
+ * @param required - actions the operation needs.
+ * @returns true when every required action is held.
+ */
+export declare function coversActions(held: readonly KnowledgeAction[], required: readonly KnowledgeAction[]): boolean;
+/**
+ * Translate a product permission into the DataOps actions that would satisfy it.
+ *
+ * A grant request is a REQUIREMENT, not a decision: these actions are what the
+ * caller asks DataOps to record, and DataOps still decides whether it may.
+ *
+ * @param action - one knowledge action, `all` included.
+ * @returns the DataOps actions to record, or an empty list for an unknown action.
+ */
+export declare function permissionToDataOpsActions(action: KnowledgeAction): string[];
+/**
+ * Translate the DataOps actions a caller actually holds into product permissions.
+ *
+ * This NARROWS: only actions listed in {@link DATA_OPS_ACTION_MAP} contribute, so a
+ * `comment` grant shows nothing rather than something the plugin cannot enforce.
+ *
+ * @param dataOpsActions - actions DataOps reported as allowed.
+ * @returns the product permissions those actions justify.
+ */
+export declare function dataOpsActionsToPermissions(dataOpsActions: readonly string[]): KnowledgeAction[];
+/**
+ * Identifier of the built-in role that may do anything anywhere.
+ *
+ * The prefix keeps it from colliding with a DataOps role code: this is a role OF
+ * THE KNOWLEDGE BASE, and a DataOps role that happens to be called `admin` must
+ * not silently acquire its powers.
+ */
+export declare const SUPER_ADMIN_ROLE = "knowledge-super-admin";
+/** Identifier of the built-in role that administers one department's documents. */
+export declare const DEPARTMENT_ADMIN_ROLE = "knowledge-dept-admin";
+/** One built-in role. */
+export interface BuiltInRole {
+    /** Stable id, stored as the grant's `principalId`. */
+    id: string;
+    /** Display name. */
+    name: {
+        zh: string;
+        en: string;
+    };
+    /** What the role can do, for the role list. */
+    description: {
+        zh: string;
+        en: string;
+    };
+    /** Actions it confers on a path it covers. */
+    actions: readonly KnowledgeAction[];
+    /** Whether the role's coverage depends on the caller's own department. */
+    departmentScoped: boolean;
+    /**
+     * Whether it may be removed.
+     *
+     * Always false for the built-ins: a knowledge base with no super administrator
+     * has nobody able to restore one, which is a state no screen should be able to
+     * reach.
+     */
+    removable: false;
+}
+/** The roles every knowledge base starts with. */
+export declare const BUILT_IN_ROLES: readonly BuiltInRole[];
+/**
+ * Look a built-in role up by id.
+ *
+ * @param id - role id, typically a grant's `principalId`.
+ * @returns the role, or undefined when the id names no built-in.
+ */
+export declare function builtInRoleOf(id: string): BuiltInRole | undefined;
+/**
+ * The path prefix a department-scoped role covers.
+ *
+ * With an organization path the prefix is the caller's OWN department folder inside
+ * the nested layout, `department/<ancestor>/.../<own>/`. A department administrator
+ * manages their own department's documents, not an ancestor's: a parent folder holds
+ * sibling departments they have no business in.
+ *
+ * The nested prefix ends with the caller's own code and starts at the organization
+ * root, because the path is root-first. That is why this returns a whole prefix
+ * rather than a bare code: the caller's code alone appears at several depths.
+ *
+ * Without a usable path (an older backend) the legacy single-level
+ * `department/<code>/` is returned, so an un-upgraded deployment keeps exactly the
+ * permissions it had.
+ *
+ * @param departmentCode - the caller's own department code.
+ * @param departmentPathCodes - the caller's organization path, root first.
+ * @returns The prefix, or undefined when there is no department to scope to.
+ */
+export declare function departmentScopeOf(departmentCode: string | undefined, departmentPathCodes?: readonly string[]): string | undefined;
+/**
+ * Whether one built-in role covers one path for one caller.
+ *
+ * The prefix is compared as a PREFIX of the finished path, so a department
+ * administrator's own folder covers everything inside it but never a peer's. The
+ * nested prefix carries the caller's whole chain, so `department/A/B/` covers
+ * `department/A/B/2026/计划.md` and never `department/A/C/...`: sharing the ancestor
+ * `A` is not enough to reach a sibling.
+ *
+ * @param roleId - the built-in role's id.
+ * @param relPath - path relative to the knowledge root.
+ * @param departmentCode - the caller's department, when they have one.
+ * @param departmentPathCodes - the caller's organization path, root first.
+ * @returns true when the role confers its actions on that path for that caller.
+ */
+export declare function builtInRoleCoversPath(roleId: string, relPath: string, departmentCode: string | undefined, departmentPathCodes?: readonly string[]): boolean;
+/**
+ * Every action a role confers on a path, for a given caller.
+ *
+ * @param roleId - role id.
+ * @param relPath - path relative to the knowledge root.
+ * @param departmentCode - the caller's department, when they have one.
+ * @param departmentPathCodes - the caller's organization path, root first.
+ * @returns the concrete actions, empty when the role does not cover the path.
+ */
+export declare function builtInRoleActionsOn(roleId: string, relPath: string, departmentCode: string | undefined, departmentPathCodes?: readonly string[]): ConcreteKnowledgeAction[];
+/** The result of asking whether a role may do something to a path. */
+export interface RoleDecision {
+    /** Whether the role covers the path at all. */
+    covered: boolean;
+    /** Actions granted on it. */
+    actions: ConcreteKnowledgeAction[];
+    /** One sentence explaining a refusal, for the UI to show verbatim. */
+    reason?: string;
+}
+/**
+ * Explain whether a role grants an action on a path.
+ *
+ * The explanation is part of the answer rather than something a screen composes
+ * afterwards: a refusal that says only "denied" cannot be acted on, and the two
+ * reasons here are very different problems — the wrong department is a
+ * permission request, an unknown role is a stale screen.
+ *
+ * @param roleId - role id.
+ * @param relPath - path relative to the knowledge root.
+ * @param action - the action being attempted.
+ * @param departmentCode - the caller's department, when they have one.
+ * @param departmentPathCodes - the caller's organization path, root first.
+ * @returns the decision, with a reason whenever it is negative.
+ */
+export declare function decideRoleAction(roleId: string, relPath: string, action: KnowledgeAction, departmentCode: string | undefined, departmentPathCodes?: readonly string[]): RoleDecision;
+/**
+ * Whether a role id names a built-in role rather than one an administrator made.
+ *
+ * The permission screen needs this to decide whether to offer a delete button,
+ * and a grant does not record the difference: only the id does.
+ *
+ * @param roleId - role id from a grant.
+ * @returns true when it is one of {@link BUILT_IN_ROLES}.
+ */
+export declare function isBuiltInRole(roleId: string): boolean;

package/lib/types/protocol.d.ts

@@ -0,0 +1,229 @@
+/**
+ * The knowledge-base protocol contract.
+ *
+ * This module is the Client's authoritative declaration of what the
+ * knowledge-base capability needs from its backend. A DataOps deployment
+ * implements these endpoints; this package never talks to the NAS directly and
+ * never decides authorization itself.
+ *
+ * Design boundary (see the design textbook, chapter 9):
+ * - Transport is HTTPS with the DataOps session credential.
+ * - Retrieval is NOT part of this protocol. Content search runs over the
+ *   mounted copy with the official `grep` and `read` tools, because the mount
+ *   makes the remote tree a local path. Only configuration, authorization
+ *   changes, and index generation cross this boundary.
+ * - File transfer is NOT part of this protocol. Files are read and written
+ *   through the mount point.
+ *
+ * @module @sparkelf/dsh-knowledge-base/protocol
+ */
+/** How this capability identifies its remote backend to the user. */
+export interface KnowledgeBackend {
+    /** Base URL of the DataOps knowledge API, without a trailing slash. */
+    baseUrl: string;
+    /** Credential reference holding the DataOps session token. */
+    credentialRef: string;
+}
+/**
+ * Resolved mount layout, as reported by the backend.
+ *
+ * The backend owns these values because it also owns the authorization model:
+ * the view root a user sees is derived from their grants, not from client
+ * configuration.
+ */
+export interface KnowledgeConfig {
+    /** Human-facing identifier of the storage host, for display only. */
+    host: string;
+    /**
+     * Absolute path of the authoritative file tree on the storage host.
+     * Never mounted into a container.
+     */
+    actualRoot: string;
+    /**
+     * Absolute path of the calling user's view tree on the storage host.
+     * This is the directory a container mounts.
+     */
+    viewRoot: string;
+    /** Absolute path where the view tree is mounted inside the container. */
+    mountPoint: string;
+    /** NFS export host, when the deployment uses the NFS transport. */
+    nfsServer?: string;
+    /** Read-only summaries the deployment wants shown beside the connection. */
+    notes?: string[];
+}
+/**
+ * One access grant.
+ *
+ * The fields mirror the DataOps permission store, whose resource type and id are
+ * free-form strings, so a knowledge path needs no schema change: the file is
+ * addressed as the resource id under the knowledge resource type.
+ */
+export interface KnowledgeGrant {
+    /** Stable identifier of this grant. */
+    id: string;
+    /** Path relative to {@link KnowledgeConfig.actualRoot}. */
+    relPath: string;
+    /** Whether this entry authorizes a file or a whole directory. */
+    kind: 'file' | 'directory';
+    /** Principal kind the grant names. */
+    principalType: KnowledgeGrantPrincipalType;
+    /** Principal id within its kind: a user id, role code, department code, or group id. */
+    principalId: string;
+    /** Permission the grant confers. */
+    action: string;
+    /** Display name of whoever granted it. */
+    grantedBy: string;
+    /** ISO-8601 timestamp of the grant. */
+    grantedAt: string;
+}
+/** Principal kinds the DataOps permission store accepts. */
+export type KnowledgeGrantPrincipalType = 'user' | 'role' | 'department' | 'group';
+/** Progress of one index job. */
+export interface KnowledgeIndexJob {
+    /** Job identifier used for polling. */
+    jobId: string;
+    /** Terminal or in-flight state. */
+    state: 'queued' | 'running' | 'succeeded' | 'failed';
+    /** Total files selected for this run. */
+    total: number;
+    /** Files processed so far. */
+    done: number;
+    /** Relative paths that failed, with their reasons. */
+    failures: Array<{
+        relPath: string;
+        reason: string;
+    }>;
+}
+/**
+ * Aggregated view and index state.
+ *
+ * Both halves are derived from the mounted tree rather than reported by a
+ * backend: the count walks the mount, and indexing is the tree itself because
+ * retrieval reads it with grep and read. A null count means the mount is absent,
+ * which is an expected state before the storage host is attached.
+ */
+export type { KnowledgeSshView } from './api.ts';
+export interface KnowledgeStatus {
+    /** Files visible under the mount point, or null when nothing is mounted there. */
+    visibleFiles: number | null;
+    /** ISO-8601 timestamp of the last successful view synchronization. */
+    lastSyncAt: string | null;
+    /** The in-flight index job, when one is running. */
+    indexing: {
+        running: boolean;
+        jobId?: string;
+        progress?: number;
+    };
+}
+/**
+ * One grant to create.
+ *
+ * A path is addressed as the resource id under the knowledge resource type, and
+ * the principal travels as a (kind, id) pair because the permission store keys
+ * grants that way. The plugin therefore never builds a policy of its own: it
+ * names the principal and lets DataOps decide whether that principal exists and
+ * what the caller may do.
+ */
+export interface KnowledgeGrantRequest {
+    /** Path relative to {@link KnowledgeConfig.actualRoot}. */
+    relPath: string;
+    /** Principal kind the grant names. */
+    principalType: KnowledgeGrantPrincipalType;
+    /** Principal id within its kind. */
+    principalId: string;
+    /** Permission to confer, defaulting to read. */
+    action?: string;
+}
+/** One grant to remove. The fields identify the row; the rest is untouched. */
+export interface KnowledgeRevokeRequest {
+    /** Path relative to {@link KnowledgeConfig.actualRoot}. */
+    relPath: string;
+    /** Principal kind the grant names. */
+    principalType: KnowledgeGrantPrincipalType;
+    /** Principal id within its kind. */
+    principalId: string;
+    /** Permission the grant confers; identifies the row together with the above. */
+    action: string;
+}
+/** Request to index one path, or the whole tree when `relPath` is omitted. */
+export interface KnowledgeIndexRequest {
+    /** Path relative to {@link KnowledgeConfig.actualRoot}. */
+    relPath?: string;
+    /** Rebuild even when the source seems unchanged. */
+    force?: boolean;
+}
+/**
+ * Endpoint paths this protocol requires a backend to implement.
+ *
+ * Kept as data rather than free strings so Client and backend can share one
+ * list and drift is caught by the type checker and by tests.
+ *
+ * Every path here was matched against a controller in `dataops/backend` rather
+ * than assumed: the global prefix is `api`, and the permission routes belong to
+ * `system/resource-permissions`. An earlier revision of this list invented an
+ * `/api/kb/*` family that no controller ever served, so every call answered 404
+ * while the plugin reported itself merely unconfigured. Config, status, and
+ * indexing have no backend counterpart at all and are derived on the Host
+ * instead; only the grants routes are remote.
+ */
+export declare const ENDPOINTS: {
+    /**
+     * Knowledge file grants. The permission store keys a grant by resource type
+     * and id, and a knowledge path is addressed as the id under
+     * {@link KB_RESOURCE_TYPE}; the kind travels in the request body.
+     */
+    readonly grants: "/api/system/resource-permissions/grants";
+    /**
+     * Principal directories, so the permission surface can offer the subjects that
+     * actually exist instead of asking an operator to transcribe a UUID.
+     *
+     * The permission store matches a user by primary key and everything else by
+     * `code`, so these are the only places a valid identifier can come from. Each
+     * one is a controller in `dataops/backend` and answers `{ items: [...] }`
+     * except departments, which nests its rows under `departments`.
+     */
+    readonly users: "/api/system/users";
+    readonly roles: "/api/system/roles";
+    readonly departments: "/api/system/departments";
+    readonly groups: "/api/system/groups";
+    /**
+     * Resolve one path's permissions for the CALLING user.
+     *
+     * This controller is `@SelfScoped`, so the answer is always about the caller and
+     * no other identity can be asked about. That is what lets a per-user view be
+     * built without this plugin evaluating a grant itself: it asks, per path,
+     * whether the caller may read it, and links what the answer allows.
+     */
+    readonly resolve: "/api/system/resource-permissions/resolve";
+    /** The authenticated caller, whose id keys their view directory. */
+    readonly me: "/api/auth/me";
+    /**
+     * Templates a reader can start from, which are DataOps wiki pages carrying the
+     * `report_template` category (`resource-wiki-core.controller.ts`, `@Get('pages/templates')`).
+     *
+     * The plugin keeps no template store: the pages a team already wrote ARE the
+     * templates, and duplicating them here would create a second copy to keep in
+     * step. The endpoint answers an empty list today because no page carries that
+     * category yet.
+     */
+    readonly templates: "/api/resources/wiki/pages/templates";
+};
+/**
+ * Resource type the knowledge base records its paths under.
+ *
+ * The DataOps permission store treats the type as a free-form string, so the
+ * knowledge tree needs no schema change to be grantable. The value is the one
+ * `dataops/backend/src/system/resource-permissions/resource-permissions.types.ts`
+ * exports for this purpose.
+ */
+export declare const KB_RESOURCE_TYPE = "knowledge-base-file";
+/**
+ * Whether a backend serves remote knowledge state.
+ *
+ * Config, status, and indexing are derived on the Host from the mounted tree and
+ * the local index, so they need no remote counterpart. Only the grant routes
+ * reach DataOps, and this constant names the one path they use.
+ */
+export declare const REMOTE_GRANTS_PATH: "/api/system/resource-permissions/grants";
+/** Join a base URL and an endpoint path without doubling or dropping the slash. */
+export declare function joinUrl(baseUrl: string, path: string): string;

package/lib/types/remote.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Deployment-runner seam for the knowledge base.
+ *
+ * Deploying MinerU or an NFS export means running commands on a remote host.
+ * This plugin does not implement SSH: the workspace already ships
+ * `@sparkelf/dsh-ssh-manager`, which owns connection handling, host-key
+ * verification, credential storage, and command execution. Reusing it keeps one
+ * authoritative credential store and one host inventory, per the managed
+ * DataOps authorization rule in AGENTS.md.
+ *
+ * The seam is intentionally narrow: callers pass a host id and a command, and
+ * receive stdout/stderr/exit code. Swapping the transport (for example to an
+ * in-process call) requires no change to callers.
+ *
+ * @module @sparkelf/dsh-knowledge-base/remote
+ */
+/** Result of one remote command. */
+export interface RemoteCommandResult {
+    /** Process exit status, or null when the command died from a signal. */
+    exitCode: number | null;
+    /** Captured standard output. */
+    stdout: string;
+    /** Captured standard error. */
+    stderr: string;
+    /** True when the transport truncated the output. */
+    truncated: boolean;
+}
+/** One SSH host as the manager reports it. Secrets are never included. */
+export interface RemoteHost {
+    id: string;
+    name: string;
+    hostname: string;
+    username: string;
+    port: number;
+    /** Host-key fingerprint the manager will verify against. */
+    knownHostFingerprint: string | null;
+    /** Whether a usable credential is configured for this host. */
+    credentialConfigured: boolean;
+}
+/** Transport the deployment steps run over. */
+export interface RemoteRunner {
+    /** List the hosts available for deployment. */
+    listHosts(): Promise<RemoteHost[]>;
+    /**
+     * Run one command on a host.
+     * @param hostId - id from {@link RemoteHost}.
+     * @param command - shell command executed by the remote login shell.
+     * @param timeoutMs - abort the command after this long.
+     */
+    execute(hostId: string, command: string, timeoutMs?: number): Promise<RemoteCommandResult>;
+}
+/** Why a remote call failed. */
+export declare class RemoteError extends Error {
+    readonly code: 'manager-unavailable' | 'unknown-host' | 'transport';
+    constructor(message: string, code: RemoteError['code'], options?: ErrorOptions);
+}
+/** Options accepted by {@link sshManagerRunner}. */
+export interface SshManagerRunnerOptions {
+    /**
+     * Origin the ssh-manager API answers on, for example `http://127.0.0.1:3080`.
+     * Required on the Host: `fetch` in Node rejects a relative URL outright, so a
+     * path-only base cannot work there even though the browser would accept it.
+     */
+    origin: string;
+    /** Request timeout for inventory reads. */
+    timeoutMs?: number;
+}
+/**
+ * The listener facts {@link originFrom} reads.
+ *
+ * `protocol` is optional because the seam added it after the peer range this
+ * package declares against; a deployment without it speaks plain HTTP, which is
+ * also the default here.
+ */
+export interface WebServerFacts {
+    /** Configured bind address. */
+    host: string;
+    /** Live listening port. */
+    port: number;
+    /** `http:` or `https:`, when the seam reports it. */
+    protocol?: 'http:' | 'https:';
+}
+/**
+ * Build the origin this process's own HTTP server answers on.
+ *
+ * A Host-side plugin cannot call its sibling's route with a relative path: Node's
+ * `fetch` throws `Failed to parse URL` before any request is made, which is why
+ * the runner needs this. `ctx.webServer` exposes the listener's real host, port,
+ * and protocol, so the value follows configuration rather than a guessed port.
+ *
+ * @param webServer - the live listener facts.
+ * @returns an origin suitable for {@link SshManagerRunnerOptions.origin}.
+ */
+export declare function originFrom(webServer: WebServerFacts): string;
+/**
+ * Build a runner that reaches SSH hosts through the ssh-manager HTTP API.
+ *
+ * The manager already exposes `hosts.list`-equivalent state and
+ * `hosts.execute`; this adapter only adapts shapes, so a change to the
+ * manager's own auth or approval rules takes effect here without a code change.
+ *
+ * @param options - optional base URL and timeout overrides.
+ * @returns a runner bound to the manager API.
+ */
+export declare function sshManagerRunner(options: SshManagerRunnerOptions): RemoteRunner;