@jk3labs/paperclip-plugin-file-browser 0.2.6 → 0.2.8

package/README.md

@@ -1,30 +1,91 @@
-# JKL File Browser
-
-A file browser plugin for Paperclip workspaces
-
-## Development
-
-```bash
-pnpm install
-pnpm dev            # watch builds
-pnpm dev:ui         # local dev server with hot-reload events
-pnpm test
-```
-
-`pnpm dev` rebuilds the worker, manifest, and UI bundles into `dist/`.
-When this package is installed from a local path, Paperclip watches that rebuilt
-output and reloads the plugin worker. Local installs run trusted code from this
-folder on your machine.
-
-
-
-## Install Into Paperclip
-
-```bash
-paperclipai plugin install C:/Users/Jad_K/.paperclip/instances/default/projects/d0b61e38-82d9-4bcf-b9e8-8ea970388ba9/2ba5752a-ea82-4afc-8d60-2ede6be97f44/_default/file-browser
-```
-
-## Build Options
-
-- `pnpm build` uses esbuild presets from `@jkawwa/paperclipai-plugin-sdk/bundlers`.
-- `pnpm build:rollup` uses rollup presets from the same SDK.
+# Paperclip File Browser Plugin
+
+A Paperclip plugin for browsing, downloading, and zipping files in the default workspace.
+
+## Installation
+
+1. Clone this repository:
+
+   ```bash
+   git clone https://github.com/jk3labs/paperclip-plugin-file-browser.git
+   cd paperclip-plugin-file-browser
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Compile the plugin:
+
+   ```bash
+   npx tsc
+   ```
+
+4. Install the plugin in Paperclip:
+
+   ```bash
+   paperclipai plugin install ./paperclip-plugin-file-browser
+   ```
+
+## API Endpoints
+
+### 1. List Directory Contents
+
+**Endpoint:** `GET /files/list`
+
+**Query Parameters:**
+- `path` (optional): Relative path to the directory (defaults to root).
+
+**Response:**
+```json
+{
+  "files": ["file1.txt", "file2.txt"],
+  "directories": ["dir1", "dir2"],
+  "currentPath": "relative/path",
+  "rootDir": "/absolute/root/path"
+}
+```
+
+**Errors:**
+- `403 Forbidden`: Access denied (path outside root).
+- `404 Not Found`: Directory does not exist.
+- `500 Internal Server Error`: Server error.
+
+### 2. Download File
+
+**Endpoint:** `GET /files/download`
+
+**Query Parameters:**
+- `path` (required): Relative path to the file.
+
+**Response:**
+- Streams the file for download.
+
+**Errors:**
+- `400 Bad Request`: Path parameter missing.
+- `403 Forbidden`: Access denied (path outside root).
+- `404 Not Found`: File does not exist.
+- `500 Internal Server Error`: Server error.
+
+### 3. Download Directory as ZIP
+
+**Endpoint:** `GET /files/zip`
+
+**Query Parameters:**
+- `path` (required): Relative path to the directory.
+
+**Response:**
+- Streams the directory as a ZIP file.
+
+**Errors:**
+- `400 Bad Request`: Path parameter missing.
+- `403 Forbidden`: Access denied (path outside root).
+- `404 Not Found`: Directory does not exist.
+- `500 Internal Server Error`: Server error.
+
+## Development
+
+- Run `npx tsc --watch` to enable TypeScript watch mode.
+- Reinstall the plugin after making changes.

package/dist/__tests__/file-browser.spec.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importStar(require("express"));
+const supertest_1 = __importDefault(require("supertest"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+// Mock the plugin router directly
+const mockRouter = (0, express_1.Router)();
+mockRouter.get('/list', (req, res) => {
+    const relativePath = req.query.path || '';
+    const mockRootDir = path_1.default.join(__dirname, 'mock-root');
+    const targetPath = path_1.default.join(mockRootDir, relativePath);
+    fs_extra_1.default.pathExists(targetPath)
+        .then(exists => {
+        if (!exists)
+            return res.status(404).json({ error: 'Directory not found' });
+        fs_extra_1.default.readdir(targetPath, { withFileTypes: true })
+            .then(entries => {
+            const files = entries.filter(dirent => dirent.isFile()).map(dirent => dirent.name);
+            const directories = entries.filter(dirent => dirent.isDirectory()).map(dirent => dirent.name);
+            res.json({ files, directories, currentPath: relativePath });
+        })
+            .catch(() => res.status(500).json({ error: 'Failed to read directory' }));
+    })
+        .catch(() => res.status(500).json({ error: 'Server error' }));
+});
+mockRouter.get('/download', (req, res) => {
+    const relativePath = req.query.path;
+    if (!relativePath)
+        return res.status(400).json({ error: 'Path parameter is required' });
+    const mockRootDir = path_1.default.join(__dirname, 'mock-root');
+    const targetPath = path_1.default.join(mockRootDir, relativePath);
+    fs_extra_1.default.pathExists(targetPath)
+        .then(exists => {
+        if (!exists)
+            return res.status(404).json({ error: 'File not found' });
+        fs_extra_1.default.stat(targetPath)
+            .then(stats => {
+            if (!stats.isFile())
+                return res.status(404).json({ error: 'File not found' });
+            res.sendFile(targetPath);
+        })
+            .catch(() => res.status(500).json({ error: 'Failed to read file' }));
+    })
+        .catch(() => res.status(500).json({ error: 'Server error' }));
+});
+mockRouter.get('/zip', (req, res) => {
+    const relativePath = req.query.path;
+    if (!relativePath)
+        return res.status(400).json({ error: 'Path parameter is required' });
+    const mockRootDir = path_1.default.join(__dirname, 'mock-root');
+    const targetPath = path_1.default.join(mockRootDir, relativePath);
+    fs_extra_1.default.pathExists(targetPath)
+        .then(exists => {
+        if (!exists)
+            return res.status(404).json({ error: 'Directory not found' });
+        fs_extra_1.default.stat(targetPath)
+            .then(stats => {
+            if (!stats.isDirectory())
+                return res.status(404).json({ error: 'Directory not found' });
+            res.status(500).json({ error: 'ZIP functionality not implemented in mock' });
+        })
+            .catch(() => res.status(500).json({ error: 'Failed to read directory' }));
+    })
+        .catch(() => res.status(500).json({ error: 'Server error' }));
+});
+describe('File Browser Plugin', () => {
+    let app;
+    const mockRootDir = path_1.default.join(__dirname, 'mock-root');
+    const mockFilePath = path_1.default.join(mockRootDir, 'test.txt');
+    const mockDirPath = path_1.default.join(mockRootDir, 'test-dir');
+    beforeAll(async () => {
+        // Setup mock filesystem
+        await fs_extra_1.default.ensureDir(mockRootDir);
+        await fs_extra_1.default.writeFile(mockFilePath, 'test content');
+        await fs_extra_1.default.ensureDir(mockDirPath);
+        await fs_extra_1.default.writeFile(path_1.default.join(mockDirPath, 'nested.txt'), 'nested content');
+        // Setup Express app
+        app = (0, express_1.default)();
+        app.use('/files', mockRouter);
+    });
+    afterAll(async () => {
+        // Cleanup mock filesystem
+        await fs_extra_1.default.remove(mockRootDir);
+    });
+    describe('GET /files/list', () => {
+        it('should list files and directories in root', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/list');
+            expect(response.status).toBe(200);
+            expect(response.body.files).toContain('test.txt');
+            expect(response.body.directories).toContain('test-dir');
+        });
+        it('should list files and directories in subdirectory', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/list?path=test-dir');
+            expect(response.status).toBe(200);
+            expect(response.body.files).toContain('nested.txt');
+        });
+        it('should return 404 for non-existent directory', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/list?path=non-existent');
+            expect(response.status).toBe(404);
+        });
+    });
+    describe('GET /files/download', () => {
+        it('should download a file', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/download?path=test.txt');
+            expect(response.status).toBe(200);
+            expect(response.text).toBe('test content');
+        });
+        it('should return 404 for non-existent file', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/download?path=non-existent.txt');
+            expect(response.status).toBe(404);
+        });
+    });
+    describe('GET /files/zip', () => {
+        it('should return 404 for non-existent directory', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/zip?path=non-existent');
+            expect(response.status).toBe(404);
+        });
+    });
+});

package/dist/index.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const archiver_1 = __importDefault(require("archiver"));
+;
+const plugin = {
+    id: 'file-browser',
+    name: 'File Browser Plugin',
+    description: 'A plugin to browse, download, and zip files in the Paperclip default workspace.',
+    register: (context) => {
+        console.debug('[File Browser Plugin] Registering plugin');
+        const router = express_1.default.Router();
+        const rootDir = context.environment.rootDir;
+        // Validate rootDir exists
+        console.debug(`[File Browser Plugin] Root directory: ${rootDir}`);
+        if (!rootDir || !(fs_extra_1.default.existsSync(rootDir))) {
+            console.error(`[File Browser Plugin] Invalid root directory: ${rootDir}`);
+            throw new Error(`Invalid root directory: ${rootDir}`);
+        }
+        router.get('/list', async (req, res) => {
+            try {
+                const relativePath = req.query.path || '';
+                const targetPath = path_1.default.join(rootDir, relativePath);
+                // Security: Ensure targetPath is within rootDir
+                if (!targetPath.startsWith(rootDir)) {
+                    return res.status(403).json({ error: 'Access denied' });
+                }
+                const entries = await fs_extra_1.default.readdir(targetPath, { withFileTypes: true });
+                const files = entries
+                    .filter(dirent => dirent.isFile())
+                    .map(dirent => dirent.name);
+                const directories = entries
+                    .filter(dirent => dirent.isDirectory())
+                    .map(dirent => dirent.name);
+                res.json({
+                    files,
+                    directories,
+                    currentPath: path_1.default.relative(rootDir, targetPath),
+                    rootDir
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const statusCode = error.code === 'ENOENT' ? 404 : 500;
+                res.status(statusCode).json({ error: message });
+            }
+        });
+        router.get('/download', async (req, res) => {
+            try {
+                const relativePath = req.query.path;
+                if (!relativePath) {
+                    return res.status(400).json({ error: 'Path parameter is required' });
+                }
+                const targetPath = path_1.default.join(rootDir, relativePath);
+                // Security: Ensure targetPath is within rootDir
+                if (!targetPath.startsWith(rootDir)) {
+                    return res.status(403).json({ error: 'Access denied' });
+                }
+                // Check if path exists and is a file
+                const stats = await fs_extra_1.default.stat(targetPath);
+                if (!stats.isFile()) {
+                    return res.status(404).json({ error: 'File not found' });
+                }
+                // Stream file for download
+                res.download(targetPath, path_1.default.basename(targetPath));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const statusCode = error.code === 'ENOENT' ? 404 : 500;
+                res.status(statusCode).json({ error: message });
+            }
+        });
+        router.get('/zip', async (req, res) => {
+            try {
+                const relativePath = req.query.path;
+                if (!relativePath) {
+                    return res.status(400).json({ error: 'Path parameter is required' });
+                }
+                const targetPath = path_1.default.join(rootDir, relativePath);
+                // Security: Ensure targetPath is within rootDir
+                if (!targetPath.startsWith(rootDir)) {
+                    return res.status(403).json({ error: 'Access denied' });
+                }
+                // Check if path exists and is a directory
+                const stats = await fs_extra_1.default.stat(targetPath);
+                if (!stats.isDirectory()) {
+                    return res.status(404).json({ error: 'Directory not found' });
+                }
+                // Set headers for ZIP download
+                res.attachment(`${path_1.default.basename(targetPath)}.zip`);
+                // Create ZIP stream
+                const archive = (0, archiver_1.default)('zip', {
+                    zlib: { level: 9 } // Maximum compression
+                });
+                archive.pipe(res);
+                archive.directory(targetPath, false);
+                await archive.finalize();
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const statusCode = error.code === 'ENOENT' ? 404 : 500;
+                res.status(statusCode).json({ error: message });
+            }
+        });
+        context.addRouter('/files', router);
+    },
+};
+exports.default = plugin;

package/dist/plugin.json

@@ -0,0 +1,5 @@
+{
+  "id": "file-browser",
+  "name": "File Browser Plugin",
+  "description": "A plugin to browse, download, and zip files in the Paperclip default workspace."
+}

package/dist/ui/FileBrowser.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const FileBrowser = ({ apiBaseUrl }) => {
+    const [files, setFiles] = (0, react_1.useState)([]);
+    const [directories, setDirectories] = (0, react_1.useState)([]);
+    const [currentPath, setCurrentPath] = (0, react_1.useState)('');
+    const [error, setError] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    (0, react_1.useEffect)(() => {
+        console.debug('[File Browser UI] Fetching file list');
+        const fetchFiles = async () => {
+            try {
+                const response = await fetch(`${apiBaseUrl}/list?path=${encodeURIComponent(currentPath)}`);
+                if (!response.ok) {
+                    const errorData = await response.json();
+                    throw new Error(errorData.error || 'Failed to fetch files');
+                }
+                const data = await response.json();
+                setFiles(data.files);
+                setDirectories(data.directories);
+                setCurrentPath(data.currentPath);
+            }
+            catch (err) {
+                console.error('[File Browser UI] Error fetching files:', err);
+                setError(err instanceof Error ? err.message : 'Failed to load files');
+            }
+            finally {
+                setLoading(false);
+            }
+        };
+        fetchFiles();
+    }, [currentPath, apiBaseUrl]);
+    const handleDirectoryClick = (dir) => {
+        setCurrentPath(currentPath ? `${currentPath}/${dir}` : dir);
+    };
+    if (loading) {
+        return (0, jsx_runtime_1.jsx)("div", { children: "Loading..." });
+    }
+    if (error) {
+        return (0, jsx_runtime_1.jsxs)("div", { children: ["File Browser: ", error] });
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { style: { padding: '16px', fontFamily: 'sans-serif' }, children: [(0, jsx_runtime_1.jsxs)("h3", { children: ["File Browser: ", currentPath || 'Root'] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h4", { children: "Directories" }), (0, jsx_runtime_1.jsx)("ul", { children: directories.map((dir) => ((0, jsx_runtime_1.jsxs)("li", { onClick: () => handleDirectoryClick(dir), style: { cursor: 'pointer', color: 'blue' }, children: ["\uD83D\uDCC1 ", dir] }, dir))) })] }), (0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("h4", { children: "Files" }), (0, jsx_runtime_1.jsx)("ul", { children: files.map((file) => ((0, jsx_runtime_1.jsxs)("li", { children: ["\uD83D\uDCC4 ", file] }, file))) })] })] }));
+};
+exports.default = FileBrowser;

package/index.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const express = require("express");
+const fs = require("fs-extra");
+const path = require("path");
+
+module.exports = (pluginContext) => {
+  const router = express.Router();
+
+  // Dynamic root lookup: Use Paperclip's workspace root
+  const rootDir = pluginContext.workspaceRoot || process.env.PAPERCLIP_WORKSPACE_ROOT || process.cwd();
+
+  /**
+   * GET /files/list
+   * List files and directories at the given path
+   */
+  router.get("/list", async (req, res) => {
+    const { dir } = req.query;
+    if (!dir) {
+      return res.status(400).json({ error: "Query parameter 'dir' is required" });
+    }
+
+    const targetPath = path.join(rootDir, dir);
+    try {
+      const stats = await fs.stat(targetPath);
+      if (!stats.isDirectory()) {
+        return res.status(400).json({ error: "Path is not a directory" });
+      }
+
+      const items = await fs.readdir(targetPath);
+      const detailedItems = await Promise.all(
+        items.map(async (item) => {
+          const itemPath = path.join(targetPath, item);
+          const itemStats = await fs.stat(itemPath);
+          return {
+            name: item,
+            path: path.relative(rootDir, itemPath),
+            isDirectory: itemStats.isDirectory(),
+            size: itemStats.size,
+            modified: itemStats.mtime
+          };
+        })
+      );
+
+      res.json({
+        path: dir,
+        items: detailedItems
+      });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  /**
+   * GET /files/read
+   * Read file content
+   */
+  router.get("/read", async (req, res) => {
+    const { file } = req.query;
+    if (!file) {
+      return res.status(400).json({ error: "Query parameter 'file' is required" });
+    }
+
+    const filePath = path.join(rootDir, file);
+    try {
+      const stats = await fs.stat(filePath);
+      if (!stats.isFile()) {
+        return res.status(400).json({ error: "Path is not a file" });
+      }
+
+      const content = await fs.readFile(filePath, "utf-8");
+      res.json({
+        path: file,
+        content
+      });
+    } catch (error) {
+      res.status(500).json({ error: error.message });
+    }
+  });
+
+  return router;
+};

package/package.json

@@ -1,48 +1,44 @@
-{
-  "name": "@jk3labs/paperclip-plugin-file-browser",
-  "version": "0.2.6",
-  "type": "module",
-  "description": "A file browser plugin for Paperclip workspaces",
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node ./esbuild.config.mjs",
-    "build:rollup": "rollup -c",
-    "dev": "node ./esbuild.config.mjs --watch",
-    "dev:ui": "paperclip-plugin-dev-server --root . --ui-dir dist/ui --port 4177",
-    "test": "vitest run --config ./vitest.config.ts",
-    "typecheck": "tsc --noEmit"
-  },
-  "paperclipPlugin": {
-    "manifest": "./dist/manifest.js",
-    "worker": "./dist/worker.js",
-    "ui": "./dist/ui/"
-  },
-  "keywords": [
-    "paperclip",
-    "plugin",
-    "workspace"
-  ],
-  "author": "JK3Labs",
-  "license": "MIT",
-  "dependencies": {
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
-  },
-  "devDependencies": {
-    "@paperclipai/plugin-sdk": "2026.525.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/node": "^24.6.0",
-    "@types/react": "^19.0.8",
-    "esbuild": "^0.27.3",
-    "rollup": "^4.38.0",
-    "tslib": "^2.8.1",
-    "typescript": "^5.7.3",
-    "vitest": "^3.0.5"
-  }
-}
+{
+  "name": "@jk3labs/paperclip-plugin-file-browser",
+  "version": "0.2.8",
+  "description": "A Paperclip plugin for browsing files in the default workspace",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "build": "tsc && cp plugin.json dist/"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "file-browser"
+  ],
+  "author": "JKL",
+  "license": "ISC",
+  "files": [
+    "dist",
+    "index.js",
+    "plugin.json"
+  ],
+  "dependencies": {
+    "@types/archiver": "^7.0.0",
+    "archiver": "^8.0.0",
+    "express": "^4.18.2",
+    "fs-extra": "^11.1.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/fs-extra": "^11.0.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.16",
+    "@types/react-dom": "^19.2.3",
+    "@types/supertest": "^7.2.0",
+    "jest": "^30.4.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  }
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "id": "file-browser",
+  "name": "File Browser Plugin",
+  "description": "A plugin to browse, download, and zip files in the Paperclip default workspace."
+}