@dsh-xhl/dsh-file-explorer 0.1.0

package/lib/types/context-types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Structural types for the cordis services this plugin consumes, plus the
+ * Context augmentation. Mirrors the actual runtime shapes; drift is contained
+ * to this file. Client-reachable declaration graph stays free of Node types.
+ */
+import type { Context } from 'cordis';
+/** The request face route handlers see (structural subset of node's IncomingMessage). */
+export interface FilexHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<string | Uint8Array>;
+}
+/** The response face route handlers write to (structural subset of ServerResponse). */
+export interface FilexHttpResponse {
+    statusCode: number;
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string | Uint8Array): void;
+}
+/** One named webserver route (mirror of the host-webserver WebRoute). */
+export interface FilexWebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: FilexHttpRequest, res: FilexHttpResponse) => void | Promise<void>;
+}
+/** The webServer service face this plugin uses. */
+export interface FilexWebServer {
+    register(route: FilexWebRoute): () => void;
+}
+/** A published session's header slice (authoritative cwd). */
+export interface FilexSessionHeader {
+    cwd?: string;
+}
+/** The host session store face (`ctx.sessions.get(id)` returns the live session). */
+export interface FilexSessionStore {
+    get(id: string): {
+        header: FilexSessionHeader;
+    } | undefined;
+    /** Resolve an Agent-scoped context view for one session (client runtime). */
+    scope(id: string): unknown | undefined;
+}
+/** Structural face of the framework session-list snapshot (`useSessions` selector input). */
+export interface FilexSessionListState {
+    /** The currently selected session id; undefined while none is selected / still loading. */
+    current?: string;
+    phase?: string;
+    byId?: Record<string, {
+        cwd?: string;
+        blank?: boolean;
+    }>;
+}
+/**
+ * The framework-injected `useSessions` selector hook — a standard prop of
+ * root-scoped slots (shell.overlay, sidebar, …). Subscribes to the session
+ * list store and re-renders on change.
+ */
+export type FilexUseSessions = (selector: (state: FilexSessionListState) => unknown) => unknown;
+/**
+ * The client workspaces service face (the chat's file-open funnel). Every
+ * chat-side path open — tool-row links, produced files, prose mentions —
+ * funnels through `openPath`, which the explorer intercepts.
+ */
+export interface FilexWorkspacesService {
+    /** Open a filesystem path through the Host (OS default application). */
+    openPath(path: string): Promise<void>;
+}
+/** The composer input face (client conversation service). */
+export interface FilexConversationInput {
+    state: {
+        getSnapshot(): {
+            draft: string;
+        };
+    };
+    setDraft(text: string): void;
+}
+/** The conversation service face (client, lazy via ctx.get('conversation')). */
+export interface FilexConversation {
+    input: {
+        for(actx: unknown): FilexConversationInput;
+    };
+}
+/** The client slots service face (register returns the disposer). */
+export interface FilexSlotsService {
+    register(options: {
+        name: string;
+        id?: string;
+        key?: string;
+        order?: number;
+        label?: string | (() => string);
+        inject?: (...args: unknown[]) => Record<string, unknown>;
+    }, component: unknown): () => void;
+    inject(key: string, callback: () => () => void): () => void;
+}
+declare module 'cordis' {
+    interface Context {
+        webServer: FilexWebServer;
+        sessions: FilexSessionStore;
+        slots: FilexSlotsService;
+        /** Client-only: the chat's file-open funnel the explorer intercepts. */
+        workspaces: FilexWorkspacesService;
+        /** Subscribe to session events (cordis event API). */
+        on(event: string, listener: (session: unknown, event: unknown) => void): () => void;
+        /** DSH-vendored cordis lifecycle helper. */
+        effect(fn: () => void | (() => void), label?: string): void;
+    }
+}
+export type { Context };

package/lib/types/index.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from './context-types.ts';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-file-explorer";
+/** Services required before mounting: the webserver routes and the session store. */
+export declare const inject: string[];
+/** Canonical containment check (case-aware on Windows, separator-normalized). */
+export declare function isWithin(parent: string, child: string): boolean;
+export declare function apply(ctx: Context): void;

package/lib/types/invariant.d.ts

@@ -0,0 +1,5 @@
+/** Assorted runtime invariants and assertions. */
+export declare function assert(value: unknown, message?: string): asserts value;
+export declare function assertNonNullable<T>(value: T | null | undefined, message?: string): T;
+/** Assert a plain record payload (JSON body guards). */
+export declare function isPlainRecord(value: unknown): value is Record<string, unknown>;

package/lib/types/trust-fence.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser-trust fence for the /filex routes: Host-header loopback passes,
+ * cross-site browser markers refuse. DNS-rebinding defense, not auth.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+interface ApiTrustRequest {
+    headers: IncomingHttpHeaders;
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Decide whether one request may reach the plugin routes. Only loopback
+ * Host authorities pass (the DSH web GUI is served from 127.0.0.1/localhost);
+ * cross-site browser requests are refused.
+ */
+export declare function isTrustedApiRequest(request: ApiTrustRequest): boolean;
+export {};

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@dsh-xhl/dsh-file-explorer",
+  "version": "0.1.0",
+  "description": "DSH 外部编译型插件：工作区文件预览 / 编辑（CodeMirror 6 编辑器 + 文件树 + 全文搜索 + Markdown/HTML/图片/PDF 预览）。移植自同目录下的动态 Cordis 插件版本。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-web-react"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"fs.rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsdown",
+    "prepare": "tsdown"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-web-react": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "cordis": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.4",
+    "@codemirror/lang-cpp": "^6.0.3",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-go": "^6.0.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-java": "^6.0.2",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-php": "^6.0.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/lang-vue": "^0.1.3",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/search": "6.7.1",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
+    "@lezer/highlight": "^1.2.3",
+    "vscode-icons-js": "^11.6.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-web-react": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.6.0"
+  }
+}