dsh-folder-path 0.1.0 → 0.2.1

package/README.md

@@ -128,10 +128,13 @@ dsh plugin --profile <profile> remove dsh-folder-path
 ## 开发
 
 ```sh
-npm run build   # client/index.js -> lib/client.js（把浏览器半边包成 __ModuleLoader__ bundle）
-npm test        # 语法检查 + 宿主路由 / 浏览器半契约 / 清单契约测试（node --test，无需 DSH 服务器）
+npm run build   # tsc: src/index.ts -> lib/index.js，client/index.ts -> .client-build/index.js；再包成 lib/client.js
+npm test        # 先 build，再跑宿主路由 / 浏览器半契约 / 清单契约测试（node --test，无需 DSH 服务器）
 ```
 
+宿主半边源码在 `src/index.ts`（TypeScript，`lib/index.js` 与 `lib/types/` 是 tsc 产物，随仓库提交）；
+浏览器半边是 `client/index.ts`（`.client-build/index.js` 是 tsc 产物），由构建脚本包成 `lib/client.js`。
+
 浏览器侧调试钩子（devtools 控制台）：
 
 ```js

package/README_EN.md

@@ -145,8 +145,8 @@ or this package's own `cordis.patch.yml`, which `dsh plugin add` wires in):
 ## Development
 
 ```sh
-npm run build   # client/index.js -> lib/client.js (wraps the browser half as a __ModuleLoader__ bundle)
-npm test        # syntax checks + host route / browser-half contract / manifest contract tests
+npm run build   # client/index.ts -> .client-build/index.js -> lib/client.js (wraps the browser half as a __ModuleLoader__ bundle)
+npm test        # builds both halves, then host route / browser-half contract / manifest contract tests
                 # (node --test, no DSH server needed)
 ```
 

package/client/globals.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Ambient declarations for the browser half.
+ *
+ * `client/index.ts` is a classic script (it has no imports or exports), so the
+ * bundle wrapper in `scripts/build-client.mts` can embed it inside a
+ * `window.__ModuleLoader__.load({ id, factory })` factory unchanged. The DOM
+ * types come from the `DOM` lib in `tsconfig.client.json`; only the two
+ * page globals this plugin defines or consumes are declared here.
+ */
+
+/** The troubleshooting hook the browser half installs on `window`. */
+interface FolderPathDebugHook {
+  /** The host route the plugin calls. */
+  route: string
+  /** Ask the host for the full paths behind these folder names. */
+  probe(names: string[]): Promise<{ paths: string[]; reason: string | null }>
+  /** Insert text through DSH's own paste path. */
+  insert(root: HTMLElement, text: string): void
+  /** Split a paste payload into directories and files. */
+  classify(dataTransfer: DataTransfer): { directories: string[]; files: File[] }
+}
+
+interface Window {
+  /** The DSH client module system; the bundle wrapper registers through it. */
+  __ModuleLoader__: {
+    load(registration: { id: string; factory: (require: (id: string) => unknown) => unknown }): void
+  }
+  /** Installed by `apply` so the devtools console can drive the plugin. */
+  __dshFolderPath?: FolderPathDebugHook
+}

package/client/{index.js → index.ts}

@@ -24,7 +24,7 @@
  * returns before `preventDefault()` unless a directory is present.
  */
 
-/** The host route; hand-mirrored from `lib/index.js` (ROUTE_PATH). */
+/** The host route; hand-mirrored from `src/index.ts` (ROUTE_PATH). */
 var ROUTE_PATH = '/dsh-folder-path/api/v1/clipboard-paths'
 
 /** Marks the synthetic events this plugin dispatches, so they are not re-read. */
@@ -36,6 +36,23 @@ var EDITABLE_SELECTOR = '[contenteditable=""],[contenteditable="true"]'
 /** How long a failure notice stays on screen. */
 var TOAST_MS = 5000
 
+/** Directories and files a paste carried, split apart by `classifyPayload`. */
+interface ClassifiedPayload {
+  directories: string[]
+  files: File[]
+}
+
+/** The host half's answer to a clipboard probe. */
+interface HostAnswer {
+  paths: string[]
+  reason: string | null
+}
+
+/** The browser Cordis context surface this plugin uses. */
+interface BrowserContext {
+  effect(factory: () => () => void, label: string): void
+}
+
 /**
  * Split a paste payload into directories and files.
  *
@@ -47,16 +64,16 @@ var TOAST_MS = 5000
  * @param dataTransfer - the event's clipboard or drag data.
  * @returns directory basenames and the non-directory files.
  */
-function classifyPayload(dataTransfer) {
-  var directories = []
-  var files = []
-  var items = dataTransfer.items ? Array.prototype.slice.call(dataTransfer.items) : []
+function classifyPayload(dataTransfer: DataTransfer): ClassifiedPayload {
+  var directories: string[] = []
+  var files: File[] = []
+  var items: DataTransferItem[] = dataTransfer.items ? Array.prototype.slice.call(dataTransfer.items) : []
 
   for (var index = 0; index < items.length; index += 1) {
     var item = items[index]
     if (item.kind !== 'file') continue
 
-    var entry = null
+    var entry: FileSystemEntry | null = null
     try {
       entry = typeof item.webkitGetAsEntry === 'function' ? item.webkitGetAsEntry() : null
     } catch (error) {
@@ -72,7 +89,7 @@ function classifyPayload(dataTransfer) {
         if (entry.name) directories.push(entry.name)
         continue
       }
-      var entryFile = null
+      var entryFile: File | null = null
       try {
         entryFile = item.getAsFile()
       } catch (error) {
@@ -82,7 +99,7 @@ function classifyPayload(dataTransfer) {
       continue
     }
 
-    var file = null
+    var file: File | null = null
     try {
       file = item.getAsFile()
     } catch (error) {
@@ -111,13 +128,13 @@ function classifyPayload(dataTransfer) {
  * @param target - the event target.
  * @returns the editable root element, or null.
  */
-function editableRootOf(target) {
-  var candidates = [target, document.activeElement]
+function editableRootOf(target: EventTarget | null): HTMLElement | null {
+  var candidates: Array<Element | null> = [target as Element | null, document.activeElement]
   for (var index = 0; index < candidates.length; index += 1) {
     var candidate = candidates[index]
     if (candidate && typeof candidate.closest === 'function') {
       var root = candidate.closest(EDITABLE_SELECTOR)
-      if (root !== null) return root
+      if (root !== null) return root as HTMLElement
     }
   }
   return null
@@ -128,7 +145,7 @@ function editableRootOf(target) {
  * @param names - directory basenames the browser saw.
  * @returns the resolved paths (empty when the host could not answer).
  */
-async function requestPaths(names) {
+async function requestPaths(names: string[]): Promise<HostAnswer> {
   var response = await fetch(ROUTE_PATH, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
@@ -153,13 +170,13 @@ async function requestPaths(names) {
  * @param root - the composer's editable root.
  * @param text - the text to insert.
  */
-function insertText(root, text) {
+function insertText(root: HTMLElement, text: string): void {
   root.focus({ preventScroll: true })
   try {
     var dataTransfer = new DataTransfer()
     dataTransfer.setData('text/plain', text)
     var event = new ClipboardEvent('paste', { clipboardData: dataTransfer, bubbles: true, cancelable: true })
-    event[SYNTHETIC] = true
+    ;(event as ClipboardEvent & Record<string, unknown>)[SYNTHETIC] = true
     root.dispatchEvent(event)
     if (event.defaultPrevented) return
   } catch (error) {
@@ -178,13 +195,13 @@ function insertText(root, text) {
  * @param root - the composer's editable root.
  * @param files - the files taken out of the original paste.
  */
-function forwardFiles(root, files) {
+function forwardFiles(root: HTMLElement, files: File[]): void {
   if (files.length === 0) return
   try {
     var dataTransfer = new DataTransfer()
     for (var index = 0; index < files.length; index += 1) dataTransfer.items.add(files[index])
     var event = new ClipboardEvent('paste', { clipboardData: dataTransfer, bubbles: true, cancelable: true })
-    event[SYNTHETIC] = true
+    ;(event as ClipboardEvent & Record<string, unknown>)[SYNTHETIC] = true
     root.dispatchEvent(event)
   } catch (error) {
     /* the paths are the point; a failed forward must not undo them */
@@ -196,7 +213,7 @@ function forwardFiles(root, files) {
  * @param reason - the host's reason code.
  * @returns the message to show.
  */
-function failureText(reason) {
+function failureText(reason: string | null): string {
   if (reason === 'unsupported-platform') return '当前宿主系统不支持读取剪贴板里的文件夹路径（仅支持 Windows / macOS）'
   if (reason === 'remote-not-supported') return '当前页面不在运行 dsh web 的这台机器上，读不到这台机器的剪贴板'
   if (reason === 'clipboard-error') return '读取剪贴板失败，没能解析文件夹的完整路径'
@@ -208,7 +225,7 @@ function failureText(reason) {
  * Show a short-lived notice above the composer.
  * @param message - the text to show.
  */
-function toast(message) {
+function toast(message: string): void {
   try {
     var element = document.createElement('div')
     element.textContent = message
@@ -231,15 +248,15 @@ function toast(message) {
  * @param require - the module system's synchronous require.
  * @returns the plugin's `apply`.
  */
-function createPlugin(require) {
+function createPlugin(require: (id: string) => unknown): { apply: (ctx: BrowserContext) => void } {
   /**
    * Resolve the pasted folders and put their paths in the composer.
    * @param root - the composer's editable root.
    * @param directories - the pasted directory basenames.
    * @param files - the non-directory files from the same paste.
    */
-  async function resolveAndInsert(root, directories, files) {
-    var result
+  async function resolveAndInsert(root: HTMLElement, directories: string[], files: File[]): Promise<void> {
+    var result: HostAnswer
     try {
       result = await requestPaths(directories)
     } catch (error) {
@@ -262,8 +279,8 @@ function createPlugin(require) {
    * Capture-phase paste handler: intercepts directory pastes only.
    * @param event - the paste event.
    */
-  function onPaste(event) {
-    if (event[SYNTHETIC] === true) return
+  function onPaste(event: ClipboardEvent): void {
+    if ((event as ClipboardEvent & Record<string, unknown>)[SYNTHETIC] === true) return
     if (!event.clipboardData) return
 
     var payload = classifyPayload(event.clipboardData)
@@ -281,7 +298,7 @@ function createPlugin(require) {
    * Mount the listener; the returned plugin is applied by the client runner.
    * @param ctx - browser Cordis context.
    */
-  function apply(ctx) {
+  function apply(ctx: BrowserContext): void {
     document.addEventListener('paste', onPaste, true)
     ctx.effect(
       function () {