dsh-folder-path 0.1.0 → 0.2.1

package/lib/types/index.d.ts

@@ -0,0 +1,110 @@
+/** Cordis plugin name; the profile row's `id` is independent of it. */
+export declare const name = "folder-path";
+/**
+ * The single endpoint the browser half calls. Hand-mirrored in
+ * `client/index.js`: the two halves ship as one package but cannot import each
+ * other (the browser bundle is a hand-written classic script).
+ */
+export declare const ROUTE_PATH = "/dsh-folder-path/api/v1/clipboard-paths";
+/**
+ * One clipboard item as the route reports it.
+ *
+ * `isDirectory` is always set by the host probes; `matchDirectories` only looks
+ * at `name`, so the test suite may hand it path/name pairs without the flag.
+ */
+export interface ClipboardEntry {
+    path: string;
+    name: string;
+    isDirectory: boolean;
+}
+/**
+ * The part of the profile row's `config` block this plugin reads.
+ */
+export interface FolderPathConfig {
+    /** Set `false` to mount the host half inert. */
+    enabled?: boolean;
+    /** Clipboard probe budget in milliseconds. */
+    timeoutMs?: number | string;
+    /** PowerShell executable used for the Windows probe. */
+    powershell?: string;
+    /** `osascript` executable used for the macOS probe. */
+    osascript?: string;
+    /** Allow a browser on another machine to read this host's clipboard. */
+    allowNonLoopback?: boolean;
+}
+/**
+ * The request shape the route handler reads: a Node HTTP request, narrowed to
+ * the fields this plugin touches.
+ */
+interface IncomingRequest {
+    method?: string;
+    headers: Record<string, string | undefined>;
+    socket?: {
+        remoteAddress?: string;
+    };
+    [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+}
+/** The response shape the route handler writes: a Node HTTP response. */
+interface OutgoingResponse {
+    writeHead(status: number, headers: Record<string, string | number>): void;
+    end(body?: string): void;
+}
+/** An exact-route handler as the DSH web server invokes it. */
+export type RouteHandler = (request: IncomingRequest, response: OutgoingResponse) => Promise<void>;
+/**
+ * The host context surface this plugin uses. DSH's real Cordis context is
+ * richer; only these members are touched, so the local interface is kept
+ * minimal instead of importing the host's types.
+ */
+export interface HostContext {
+    logger?: {
+        warn?: (message: string, ...args: unknown[]) => void;
+    };
+    inject(names: readonly string[], callback: (host: HostFiber) => void): void;
+}
+/** The fiber `ctx.inject` hands back once the web server service appears. */
+export interface HostFiber {
+    effect(factory: () => (() => void) | void, label: string): void;
+    webServer: {
+        register(route: {
+            kind: 'exact';
+            path: string;
+            handler: RouteHandler;
+        }): () => void;
+    };
+}
+/**
+ * Install the clipboard route.
+ *
+ * `webServer` is acquired through `ctx.inject` rather than read directly: the
+ * service appears asynchronously, and a plain read inside `apply` would silently
+ * see nothing and never register the route.
+ *
+ * @param ctx - host plugin context.
+ * @param config - the profile row's `config` block.
+ * @returns nothing; the route is registered once `webServer` appears.
+ */
+export declare function apply(ctx: HostContext, config?: FolderPathConfig): void;
+/**
+ * Filter clipboard directories down to the ones the browser is pasting.
+ *
+ * An empty `names` list means the caller wants every copied directory; a
+ * non-empty list is matched by basename, case-insensitively, because that is
+ * all the browser can see of the path.
+ *
+ * @param directories - directory entries from the clipboard.
+ * @param names - basenames the browser reported.
+ * @returns the matching entries, in clipboard order.
+ * @remarks Exported for the host test suite; the route is its only runtime caller.
+ */
+export declare function matchDirectories<T extends {
+    name: string;
+}>(directories: T[], names: string[]): T[];
+/**
+ * Parse the macOS probe's stdout into absolute paths.
+ * @param stdout - the probe's stdout.
+ * @returns the paths it reported, in clipboard order.
+ * @remarks Exported for the host test suite; the probe is its only runtime caller.
+ */
+export declare function parseProbePaths(stdout: unknown): string[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-folder-path",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "DSH 插件：粘贴（复制来的）文件夹时不再尝试上传，而是把它的完整路径作为文本插入输入框（Windows / macOS）。Paste a copied folder and get its full path as text instead of a failed upload (Windows and macOS).",
   "private": false,
   "publishConfig": {
@@ -8,6 +8,7 @@
   },
   "type": "module",
   "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
   "exports": {
     ".": {
       "default": "./lib/index.js"
@@ -19,6 +20,7 @@
   },
   "files": [
     "lib/index.js",
+    "lib/types",
     "lib/client.js",
     "client",
     "scripts",
@@ -31,9 +33,10 @@
     "docs"
   ],
   "scripts": {
-    "build": "node scripts/build-client.mjs",
-    "prepare": "node scripts/build-client.mjs",
-    "test": "node --check lib/index.js && node --check lib/client.js && node --test"
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.client.json && node scripts/build-client.mts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.client.json --noEmit",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test test/*.test.ts"
   },
   "engines": {
     "node": ">=24",
@@ -71,5 +74,9 @@
     "client": {
       "platform": "web"
     }
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
   }
 }

package/scripts/{build-client.mjs → build-client.mts}

@@ -1,25 +1,26 @@
 /**
- * Wrap the hand-written browser half into the DSH client bundle contract.
+ * Wrap the compiled browser half into the DSH client bundle contract.
  *
  * The client module system executes a plugin bundle as a plain classic script
  * that REGISTERS a lazy CJS factory:
  *
  *   window.__ModuleLoader__.load({ id, factory: (require) => exports })
  *
- * so the bundle needs no bundler. `client/index.js` defines `createPlugin`; this
- * script wraps it and writes `lib/client.js`, which is what `exports['./client']`
- * points at. Run by `npm run build` (and by `prepare`, so a `dsh plugin add`
- * always ships a bundle).
+ * so the bundle needs no bundler. `client/index.ts` defines `createPlugin`;
+ * `tsc -p tsconfig.client.json` compiles it to `.client-build/index.js`, and
+ * this script wraps that compiled output into `lib/client.js`, which is what
+ * `exports['./client']` points at. Run by `npm run build` (and by `prepare`, so
+ * a `dsh plugin add` always ships a bundle).
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
-const source = readFileSync(join(root, 'client', 'index.js'), 'utf8')
+const source = readFileSync(join(root, '.client-build', 'index.js'), 'utf8')
 const target = join(root, 'lib', 'client.js')
 
-const indent = (text) =>
+const indent = (text: string): string =>
   text
     .split('\n')
     .map((line) => (line.length > 0 ? `    ${line}` : line))
@@ -31,7 +32,7 @@ const bundle = `window.__ModuleLoader__.load({
     var module = { exports: {} };
     var exports = module.exports;
     Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-    // ---- client/index.js ----
+    // ---- .client-build/index.js ----
 ${indent(source)}
     const plugin = createPlugin(require);
     exports.apply = plugin.apply;