@jk3labs/paperclip-plugin-file-browser 0.2.3 → 0.2.5

package/README.md

@@ -1,30 +1,91 @@
-# JKL File Browser
+# Paperclip File Browser Plugin
 
-A file browser plugin for Paperclip workspaces
+A Paperclip plugin for browsing, downloading, and zipping files in the workspace.
 
-## Development
+## Installation
 
-```bash
-pnpm install
-pnpm dev            # watch builds
-pnpm dev:ui         # local dev server with hot-reload events
-pnpm test
-```
+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:
 
-`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.
+   ```bash
+   npx tsc
+   ```
 
+4. Install the plugin in Paperclip:
 
+   ```bash
+   paperclipai plugin install ./paperclip-plugin-file-browser
+   ```
 
-## Install Into Paperclip
+## API Endpoints
 
-```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
+### 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"
+}
 ```
 
-## Build Options
+**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
 
-- `pnpm build` uses esbuild presets from `@jkawwa/paperclipai-plugin-sdk/bundlers`.
-- `pnpm build:rollup` uses rollup presets from the same SDK.
+- 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,140 @@
+"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 supertest_1 = __importDefault(require("supertest"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+jest.mock('archiver', () => {
+    return jest.fn().mockImplementation(() => {
+        const { PassThrough } = require('stream');
+        const stream = new PassThrough();
+        setTimeout(() => { stream.end(); }, 50);
+        return {
+            pipe: (dest) => { stream.pipe(dest); return dest; },
+            directory: () => { },
+            finalize: jest.fn().mockResolvedValue(undefined),
+        };
+    });
+});
+const index_1 = __importDefault(require("../index"));
+const mockRootDir = path_1.default.join(__dirname, 'mock-root');
+function createApp() {
+    const app = (0, express_1.default)();
+    const routers = [];
+    const context = {
+        addRouter: (basePath, router) => {
+            routers.push({ basePath, router });
+        },
+        environment: {
+            rootDir: mockRootDir,
+        },
+    };
+    index_1.default.register(context);
+    for (const { basePath, router } of routers) {
+        app.use(basePath, router);
+    }
+    return app;
+}
+describe('File Browser Plugin', () => {
+    let app;
+    const mockFilePath = path_1.default.join(mockRootDir, 'test.txt');
+    const mockDirPath = path_1.default.join(mockRootDir, 'test-dir');
+    const mockNestedFilePath = path_1.default.join(mockDirPath, 'nested.txt');
+    beforeAll(async () => {
+        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(mockNestedFilePath, 'nested content');
+        app = createApp();
+    });
+    afterAll(async () => {
+        await fs_extra_1.default.remove(mockRootDir);
+    });
+    describe('Plugin registration', () => {
+        it('should throw if rootDir is invalid', () => {
+            const badContext = {
+                addRouter: () => { },
+                environment: { rootDir: '/nonexistent/path/that/does/not/exist' },
+            };
+            expect(() => index_1.default.register(badContext)).toThrow('Invalid root directory');
+        });
+        it('should register a router on /files', () => {
+            const registeredPaths = [];
+            const ctx = {
+                addRouter: (basePath) => { registeredPaths.push(basePath); },
+                environment: { rootDir: mockRootDir },
+            };
+            index_1.default.register(ctx);
+            expect(registeredPaths).toContain('/files');
+        });
+    });
+    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');
+            expect(response.body.currentPath).toBe('');
+        });
+        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');
+            expect(response.body.directories).toEqual([]);
+        });
+        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);
+        });
+        it('should return 403 for path traversal attempt', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/list?path=../../../etc');
+            expect(response.status).toBe(403);
+        });
+    });
+    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 400 when path is missing', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/download');
+            expect(response.status).toBe(400);
+            expect(response.body.error).toBe('Path parameter is required');
+        });
+        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);
+        });
+        it('should return 403 for path traversal attempt', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/download?path=../../../etc/passwd');
+            expect(response.status).toBe(403);
+        });
+    });
+    describe('GET /files/zip', () => {
+        it('should return a zip response for a valid directory', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/zip?path=test-dir');
+            expect(response.status).toBe(200);
+        });
+        it('should return 400 when path is missing', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/zip');
+            expect(response.status).toBe(400);
+            expect(response.body.error).toBe('Path parameter is required');
+        });
+        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);
+        });
+        it('should return 404 when path points to a file', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/zip?path=test.txt');
+            expect(response.status).toBe(404);
+        });
+        it('should return 403 for path traversal attempt', async () => {
+            const response = await (0, supertest_1.default)(app).get('/files/zip?path=../../../etc');
+            expect(response.status).toBe(403);
+        });
+    });
+});

package/dist/index.js

@@ -0,0 +1,110 @@
+"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 workspace.',
+    register: (context) => {
+        const router = express_1.default.Router();
+        const rootDir = context.environment.rootDir;
+        // Validate rootDir exists
+        if (!rootDir || !(fs_extra_1.default.existsSync(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/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/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json', 'node'],
+};

package/manifest.ts

@@ -0,0 +1,15 @@
+import type { PaperclipPluginManifestV1 } from '@paperclipai/shared';
+
+export const manifest: PaperclipPluginManifestV1 = {
+  id: 'jkl.file-browser',
+  apiVersion: 1,
+  version: '1.0.0',
+  displayName: 'File Browser',
+  description: 'A plugin to browse files in the Paperclip workspace.',
+  author: 'JKL <support@jkl.co>',
+  categories: ['utilities'],
+  capabilities: [],
+  entrypoints: {
+    worker: 'dist/index.js',
+  },
+};

package/package.json

@@ -1,48 +1,34 @@
-{
-  "name": "@jk3labs/paperclip-plugin-file-browser",
-  "version": "0.2.3",
-  "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.5",
+  "description": "A Paperclip plugin for browsing files in the workspace",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "paperclip",
+    "plugin",
+    "file-browser"
+  ],
+  "author": "JKL",
+  "license": "ISC",
+  "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/supertest": "^7.2.0",
+    "jest": "^30.4.2",
+    "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 workspace."
+}