@elizaos/plugin-device-filesystem 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+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,61 @@
+# @elizaos/plugin-device-filesystem
+
+Mobile-safe filesystem bridge for the elizaOS runtime.
+
+Adds a single `DeviceFilesystemBridge` service. Planner-visible read, write, and
+directory list operations are routed through the canonical `FILE` action with
+`target=device`:
+
+- `FILE` with `action=read`, `target=device` — read a file from the user's
+  device-files root.
+- `FILE` with `action=write`, `target=device` — write a file to the user's
+  device-files root.
+- `FILE` with `action=ls`, `target=device` — list a directory inside the user's
+  device-files root.
+
+## Backends
+
+The bridge picks one of two backends at startup:
+
+- **Capacitor** — when `window.Capacitor.isNativePlatform()` is true (iOS,
+  Android). Uses `@capacitor/filesystem` with `Directory.Documents` as the root.
+- **Node** — when not on Capacitor. Uses `fs/promises` rooted at
+  `resolveStateDir() + "/workspace"` (default
+  `~/.local/state/eliza/workspace` unless XDG or env overrides it).
+
+Both backends reject absolute paths, `..` traversal, NUL bytes, and (on Node)
+any resolution that escapes the workspace root.
+
+## FILE integration
+
+This package owns only the device filesystem bridge. It does not register
+planner-facing file actions. The `@elizaos/plugin-coding-tools` `FILE` action
+discovers the bridge by the `device_filesystem` service type and delegates
+`target=device` operations to it.
+
+## iOS Info.plist (apply in the host app)
+
+For iOS users to see files written into `Directory.Documents`, the host app's
+`Info.plist` needs the following keys added:
+
+```xml
+<key>UIFileSharingEnabled</key>
+<true/>
+<key>LSSupportsOpeningDocumentsInPlace</key>
+<true/>
+```
+
+Without those keys, files still write — they just aren't browsable from the
+Files.app side. Add them in the host app's iOS shell, not in this package.
+
+## Android
+
+No special manifest changes are required for Capacitor `Directory.Documents`
+(the Capacitor Filesystem plugin handles scoped storage and MediaStore on
+Android 10+). Cross-app sharing through `MediaStore.Downloads` belongs in the
+host app's AndroidManifest, not here.
+
+## Service type
+
+`DEVICE_FILESYSTEM_SERVICE_TYPE = "device_filesystem"`. Resolve programmatically
+with `getDeviceFilesystemBridge(runtime)`.

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@elizaos/plugin-device-filesystem",
+  "version": "2.0.3-beta.2",
+  "description": "Mobile-safe filesystem bridge for canonical FILE target=device operations on iOS/Android and desktop/AOSP.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaos/eliza.git"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "eliza",
+    "plugin",
+    "filesystem",
+    "capacitor",
+    "mobile",
+    "ios",
+    "android"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "dependencies": {
+    "@elizaos/core": "2.0.3-beta.2",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.3-beta.2"
+  },
+  "optionalDependencies": {
+    "@capacitor/filesystem": "^8.1.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@capacitor/filesystem": "^8.1.2",
+    "@types/node": "^25.0.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "bun run build.ts",
+    "dev": "bun --hot build.ts",
+    "clean": "rm -rf dist .turbo",
+    "test": "vitest run",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "lint:check": "bunx @biomejs/biome check .",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "check": "bun run typecheck && bun run test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  },
+  "eliza": {
+    "platforms": [
+      "node",
+      "ios",
+      "android"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Filesystem rooted under resolveStateDir()/workspace",
+      "ios": "Capacitor Filesystem Directory.Documents",
+      "android": "Capacitor Filesystem Directory.Documents"
+    }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}