@openharness/provider-vfs 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @openharness/provider-vfs
+
+Virtual filesystem provider for [@openharness/core](../core). Gives your agents sandboxed, in-memory, or persistent file access instead of hitting the real filesystem.
+
+Built on [@platformatic/vfs](https://github.com/platformatic/vfs) (a userland shim for the upcoming `node:vfs`). When Node.js ships native VFS support, the provider will use it automatically — no code changes needed.
+
+## Install
+
+```bash
+npm install @openharness/provider-vfs @platformatic/vfs
+```
+
+Requires Node.js >= 22.
+
+## Usage
+
+```typescript
+import { createFsTools } from "@openharness/core";
+import { VfsFsProvider } from "@openharness/provider-vfs";
+
+// In-memory VFS (default) — fully ephemeral, no disk access
+const fsTools = createFsTools(new VfsFsProvider());
+```
+
+### Backends
+
+```typescript
+import { MemoryProvider, SqliteProvider, RealFSProvider } from "@platformatic/vfs";
+
+// SQLite-backed — persistent across restarts
+const fsTools = createFsTools(new VfsFsProvider({
+  provider: new SqliteProvider("/path/to/db.sqlite"),
+}));
+
+// Sandboxed real FS — real files, but the agent can't escape the root
+const fsTools = createFsTools(new VfsFsProvider({
+  provider: new RealFSProvider("/safe/workspace"),
+}));
+```
+
+### Pre-configured VFS
+
+If you need full control (overlay mode, custom mount point, etc.), create the VFS yourself:
+
+```typescript
+import { create, MemoryProvider } from "@platformatic/vfs";
+
+const vfs = create(new MemoryProvider(), { overlay: true, virtualCwd: true });
+vfs.mount("/workspace");
+
+const fsTools = createFsTools(new VfsFsProvider({ vfs }));
+```
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `vfs` | — | Pre-created `VirtualFileSystem` instance. Skips auto-creation. |
+| `provider` | `MemoryProvider` | VFS backend (`MemoryProvider`, `SqliteProvider`, `RealFSProvider`). |
+| `vfsOptions` | `{ moduleHooks: false, virtualCwd: true }` | Options passed to `create()`. |
+| `mountPoint` | `"/workspace"` | VFS mount point. |
+| `maxFileSize` | `10 MB` | Reject reads for files larger than this. |
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@openharness/provider-vfs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Virtual filesystem provider for @openharness/core — sandboxed, in-memory, or SQLite-backed file access for AI agents",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "agent",
+    "ai",
+    "vfs",
+    "virtual-filesystem",
+    "sandbox",
+    "openharness"
+  ],
+  "license": "ISC",
+  "dependencies": {
+    "@openharness/core": "0.4.5"
+  },
+  "peerDependencies": {
+    "@platformatic/vfs": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@platformatic/vfs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@platformatic/vfs": "^0.3.0",
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}