@ziioapp/finder-opfs 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 ziioai
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @ziioapp/finder-opfs
+
+把 `@ziioapp/os-features` 的 ZiioApp OPFS 应用数据目录接入 `@ziioapp/finder`。这是可选适配包；Finder 核心不依赖它。
+
+```ts
+import { createOpfsFinderBackend } from "@ziioapp/finder-opfs";
+
+const opfsBackend = createOpfsFinderBackend({ appId: "unia" });
+await opfsBackend.ensureLayout();
+
+// <FinderDesktop backend={opfsBackend} api={finderStore} />
+```
+
+`appId` 决定文件根目录，即 `getZiioOpfsAppPaths(appId).appData`；可选 `userId` 会同时传给目录布局初始化。也可以通过 `id`、`label` 覆盖 Finder 中展示的后端标识和名称。调用 `ensureLayout()` 后再展示或操作文件。
+
+文件路径对 Finder 保持无前导斜杠的相对形式，适配器负责与 OPFS 绝对路径转换。它沿用原 `unia` 和 `demo-paper-smasher` 实现的读写、重命名及不支持原生 `move()` 时的复制回退逻辑。浏览器需要支持 OPFS；不同 origin／存储分区不会因为安装同一个包而自动共享文件。
+
+该包不适配 `opfs-tools` API；使用它的应用可以继续提供自己的 `FsBackend`。

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { FsBackend } from "@ziioapp/finder/backend";
+export interface CreateOpfsFinderBackendOptions {
+    appId: string;
+    userId?: string;
+    id?: string;
+    label?: string;
+}
+export interface OpfsFinderBackend extends FsBackend {
+    /** Initialize the ZiioApp directory layout before first use. */
+    ensureLayout(): Promise<void>;
+}
+/** Create an OPFS-backed Finder instance scoped to one ZiioApp app directory. */
+export declare function createOpfsFinderBackend(options: CreateOpfsFinderBackendOptions): OpfsFinderBackend;

package/dist/index.js

@@ -0,0 +1,137 @@
+import { guessContentType } from "@ziioapp/finder/format";
+import { ensureZiioOpfsLayout, getOpfsDirectoryHandle, getZiioOpfsAppPaths, joinRelativeOpfsPath, listOpfsDirectory, opfsBasename, opfsDirectoryExists, opfsDirname, opfsFileExists, readOpfsFile, removeOpfsEntry, stripOpfsPrefix, writeOpfsFile, } from "@ziioapp/os-features/opfs";
+const invalidEntryNameRe = /[/\\\0]/;
+function assertEntryName(name) {
+    if (!name || name === "." || name === ".." || invalidEntryNameRe.test(name)) {
+        throw new Error("名称不能为空，也不能包含路径分隔符。");
+    }
+}
+async function entryExists(path) {
+    const [fileExists, directoryExists] = await Promise.all([
+        opfsFileExists(path),
+        opfsDirectoryExists(path),
+    ]);
+    return fileExists || directoryExists;
+}
+async function copyEntry(sourcePath, targetPath) {
+    if (await opfsDirectoryExists(sourcePath)) {
+        await getOpfsDirectoryHandle(targetPath, { create: true });
+        const entries = await listOpfsDirectory(sourcePath);
+        await Promise.all(entries.map((entry) => copyEntry(entry.path, joinRelativeOpfsPath(targetPath, entry.name))));
+        return;
+    }
+    await writeOpfsFile(targetPath, await readOpfsFile(sourcePath));
+}
+/** Create an OPFS-backed Finder instance scoped to one ZiioApp app directory. */
+export function createOpfsFinderBackend(options) {
+    const { appId, userId, id = "opfs", label = "本地文件 (OPFS)" } = options;
+    const filesRoot = getZiioOpfsAppPaths(appId, { userId }).appData;
+    function resolvePath(visiblePath) {
+        return joinRelativeOpfsPath(filesRoot, visiblePath);
+    }
+    function toVisiblePath(path) {
+        return stripOpfsPrefix(path, filesRoot);
+    }
+    async function moveEntry(item, currentDir, newName) {
+        assertEntryName(newName);
+        const sourcePath = resolvePath(item.path);
+        const targetPath = resolvePath(joinRelativeOpfsPath(currentDir, newName));
+        if (await entryExists(targetPath)) {
+            throw new Error(`“${newName}”已经存在。`);
+        }
+        const sourceParent = await getOpfsDirectoryHandle(opfsDirname(sourcePath));
+        const sourceName = opfsBasename(sourcePath);
+        const sourceHandle = item.isDirectory
+            ? await sourceParent.getDirectoryHandle(sourceName)
+            : await sourceParent.getFileHandle(sourceName);
+        const move = sourceHandle.move;
+        if (typeof move === "function") {
+            const targetParent = await getOpfsDirectoryHandle(resolvePath(currentDir));
+            await move.call(sourceHandle, targetParent, newName);
+            return;
+        }
+        try {
+            await copyEntry(sourcePath, targetPath);
+        }
+        catch (error) {
+            await removeOpfsEntry(targetPath, { recursive: true }).catch(() => {
+                // Preserve the original copy error if cleanup also fails.
+            });
+            throw error;
+        }
+        await removeOpfsEntry(sourcePath, { recursive: item.isDirectory });
+    }
+    function toDriveItem(entry) {
+        return {
+            name: entry.name,
+            path: toVisiblePath(entry.path),
+            size: entry.size,
+            contentType: entry.type || guessContentType(entry.name),
+            modified: entry.lastModified
+                ? new Date(entry.lastModified).toLocaleString()
+                : "",
+            isDirectory: entry.kind === "directory",
+        };
+    }
+    return {
+        id,
+        label,
+        capabilities: {
+            upload: true,
+            mkdir: true,
+            rename: true,
+            remove: true,
+            cache: false,
+        },
+        async ensureLayout() {
+            await ensureZiioOpfsLayout({ appIds: [appId], userId });
+        },
+        initialPath() {
+            return "";
+        },
+        async list(path) {
+            const resolvedPath = resolvePath(path);
+            if (!(await opfsDirectoryExists(resolvedPath))) {
+                return { items: [], fromCache: false };
+            }
+            const entries = await listOpfsDirectory(resolvedPath);
+            return { items: entries.map(toDriveItem), fromCache: false };
+        },
+        async readBlob(item) {
+            return {
+                blob: await readOpfsFile(resolvePath(item.path)),
+                fromCache: false,
+            };
+        },
+        async upload(dirPath, files) {
+            for (const file of files)
+                assertEntryName(file.name);
+            await Promise.all(files.map((file) => writeOpfsFile(resolvePath(joinRelativeOpfsPath(dirPath, file.name)), file)));
+        },
+        async mkdir(dirPath, name) {
+            assertEntryName(name);
+            const path = resolvePath(joinRelativeOpfsPath(dirPath, name));
+            if (await entryExists(path)) {
+                throw new Error(`“${name}”已经存在。`);
+            }
+            await getOpfsDirectoryHandle(path, { create: true });
+        },
+        rename(item, currentDir, newName) {
+            return moveEntry(item, currentDir, newName);
+        },
+        async remove(item) {
+            await removeOpfsEntry(resolvePath(item.path), {
+                recursive: item.isDirectory,
+            });
+        },
+        canWriteDir() {
+            return true;
+        },
+        canWriteItem() {
+            return true;
+        },
+        notice() {
+            return null;
+        },
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ziioapp/finder-opfs",
+  "version": "0.1.0",
+  "description": "ZiioApp OPFS backend adapter for @ziioapp/finder",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@ziioapp/finder": "^0.1.0",
+    "@ziioapp/os-features": "^0.1.0",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@ziioapp/finder": "^0.1.0",
+    "@ziioapp/os-features": "^0.1.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "author": "ziioai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziioai/ziioos.git",
+    "directory": "packages/finder-opfs"
+  },
+  "homepage": "https://github.com/ziioai/ziioos#readme",
+  "bugs": {
+    "url": "https://github.com/ziioai/ziioos/issues"
+  },
+  "keywords": [
+    "finder",
+    "opfs",
+    "browser",
+    "ziioapp"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "node ../../scripts/build-package.mjs"
+  }
+}