vectra 0.12.2 → 0.14.0

package/src/storage/LocalFileStorage.spec.ts

@@ -0,0 +1,292 @@
+import assert from 'node:assert';
+import sinon from 'sinon';
+import fs from 'fs/promises';
+import path from 'path';
+import { LocalFileStorage } from './LocalFileStorage';
+import { FileStorageUtilities } from './FileStorageUtilities';
+
+describe('LocalFileStorage', () => {
+  let storage: LocalFileStorage;
+
+  afterEach(async () => {
+    sinon.restore();
+  });
+
+  describe('constructor and getFullPath', () => {
+    it('returns relativePath if no rootFolder and relativePath non-empty', () => {
+      storage = new LocalFileStorage();
+      // @ts-ignore access private for test
+      assert.strictEqual(storage['getFullPath']('some/path'), 'some/path');
+    });
+
+    it("returns '.' if no rootFolder and relativePath empty", () => {
+      storage = new LocalFileStorage();
+      // @ts-ignore access private for test
+      assert.strictEqual(storage['getFullPath'](''), '.');
+    });
+
+    it('returns rootFolder if rootFolder set and relativePath empty', () => {
+      storage = new LocalFileStorage('/root');
+      // @ts-ignore access private for test
+      assert.strictEqual(storage['getFullPath'](''), '/root');
+    });
+
+    it('joins rootFolder and relativePath if both set', () => {
+      storage = new LocalFileStorage('/root');
+      // @ts-ignore access private for test
+      assert.strictEqual(storage['getFullPath']('sub/folder'), path.join('/root', 'sub/folder'));
+    });
+  });
+
+  describe('createFile', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('writes a new file with Buffer content', async () => {
+      const writeFileStub = sinon.stub(fs, 'writeFile').resolves();
+      const content = Buffer.from('hello');
+      await storage.createFile('file.txt', content);
+      sinon.assert.calledWith(writeFileStub, path.join('/root', 'file.txt'), content, { flag: 'wx' });
+    });
+
+    it('writes a new file with string content as UTF-8', async () => {
+      const writeFileStub = sinon.stub(fs, 'writeFile').resolves();
+      const content = 'hello';
+      await storage.createFile('file.txt', content);
+      sinon.assert.calledWith(
+        writeFileStub,
+        path.join('/root', 'file.txt'),
+        Buffer.from(content, 'utf8'),
+        { flag: 'wx' }
+      );
+    });
+
+    it('bubbles up error if file already exists', async () => {
+      sinon.stub(fs, 'writeFile').rejects(new Error('EEXIST'));
+      await assert.rejects(async () => {
+        await storage.createFile('file.txt', 'content');
+      });
+    });
+
+    it('bubbles up error if parent directory does not exist', async () => {
+      sinon.stub(fs, 'writeFile').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.createFile('nonexistent/file.txt', 'content');
+      });
+    });
+  });
+
+  describe('createFolder', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('creates nested directory structure recursively', async () => {
+      const mkdirStub = sinon.stub(fs, 'mkdir').resolves();
+      await storage.createFolder('nested/folder');
+      sinon.assert.calledWith(mkdirStub, path.join('/root', 'nested/folder'), { recursive: true });
+    });
+
+    it('calling again on same path still calls mkdir (idempotent due to recursive:true)', async () => {
+      const mkdirStub = sinon.stub(fs, 'mkdir').resolves();
+      await storage.createFolder('nested/folder');
+      await storage.createFolder('nested/folder');
+      sinon.assert.calledTwice(mkdirStub);
+    });
+  });
+
+  describe('deleteFile', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('deletes existing file', async () => {
+      const unlinkStub = sinon.stub(fs, 'unlink').resolves();
+      await storage.deleteFile('file.txt');
+      sinon.assert.calledWith(unlinkStub, path.join('/root', 'file.txt'));
+    });
+
+    it('bubbles up error when file does not exist', async () => {
+      sinon.stub(fs, 'unlink').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.deleteFile('missing.txt');
+      });
+    });
+  });
+
+  describe('deleteFolder', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('deletes existing folder recursively', async () => {
+      const rmStub = sinon.stub(fs, 'rm').resolves();
+      await storage.deleteFolder('folder');
+      sinon.assert.calledWith(rmStub, path.join('/root', 'folder'), { recursive: true });
+    });
+
+    it('bubbles up error when folder does not exist', async () => {
+      sinon.stub(fs, 'rm').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.deleteFolder('missing');
+      });
+    });
+  });
+
+  describe('getDetails', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('returns correct details for file', async () => {
+      const statStub = sinon.stub(fs, 'stat').resolves({
+        isDirectory: () => false,
+        isFile: () => true,
+      } as any);
+      const getFileTypeStub = sinon.stub(FileStorageUtilities, 'getFileType').returns('txt');
+
+      const details = await storage.getDetails('file.txt');
+      assert.strictEqual(details.name, 'file.txt');
+      assert.strictEqual(details.path, 'file.txt');
+      assert.strictEqual(details.isFolder, false);
+      assert.strictEqual(details.fileType, 'txt');
+
+      sinon.assert.calledWith(statStub, path.join('/root', 'file.txt'));
+      sinon.assert.calledWith(getFileTypeStub, 'file.txt');
+    });
+
+    it('returns correct details for folder', async () => {
+      sinon.stub(fs, 'stat').resolves({
+        isDirectory: () => true,
+        isFile: () => false,
+      } as any);
+
+      const details = await storage.getDetails('folder');
+      assert.strictEqual(details.name, 'folder');
+      assert.strictEqual(details.path, 'folder');
+      assert.strictEqual(details.isFolder, true);
+      assert.strictEqual(details.fileType, undefined);
+    });
+
+    it('bubbles up error for non-existent path', async () => {
+      sinon.stub(fs, 'stat').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.getDetails('missing');
+      });
+    });
+  });
+
+  describe('listFiles', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('returns entries for folder with files and subfolders', async () => {
+      const dirents = [
+        { name: 'file1.txt', isDirectory: () => false, isFile: () => true },
+        { name: 'subfolder', isDirectory: () => true, isFile: () => false },
+      ];
+      sinon.stub(fs, 'readdir').resolves(dirents as any);
+      const getFileTypeStub = sinon.stub(FileStorageUtilities, 'getFileType').callsFake((name: string) => {
+        if (name === 'file1.txt') return 'txt';
+        return undefined;
+      });
+
+      const results = await storage.listFiles('folder');
+      assert.strictEqual(results.length, 2);
+
+      assert.strictEqual(results[0].name, 'file1.txt');
+      assert.strictEqual(results[0].path, path.join('/root', 'folder', 'file1.txt'));
+      assert.strictEqual(results[0].isFolder, false);
+      assert.strictEqual(results[0].fileType, 'txt');
+
+      assert.strictEqual(results[1].name, 'subfolder');
+      assert.strictEqual(results[1].path, path.join('/root', 'folder', 'subfolder'));
+      assert.strictEqual(results[1].isFolder, true);
+      assert.strictEqual(results[1].fileType, undefined);
+
+      sinon.assert.calledWith(getFileTypeStub, 'file1.txt');
+    });
+
+    it('ignores filter argument', async () => {
+      sinon.stub(fs, 'readdir').resolves([]);
+      const results = await storage.listFiles('folder', { any: true } as any);
+      assert.ok(Array.isArray(results));
+      assert.strictEqual(results.length, 0);
+    });
+  });
+
+  describe('pathExists', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('returns true for existing file or folder', async () => {
+      sinon.stub(fs, 'access').resolves();
+      const exists = await storage.pathExists('file.txt');
+      assert.strictEqual(exists, true);
+    });
+
+    it('returns false for non-existent path', async () => {
+      sinon.stub(fs, 'access').rejects(new Error('ENOENT'));
+      const exists = await storage.pathExists('missing');
+      assert.strictEqual(exists, false);
+    });
+  });
+
+  describe('readFile', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('reads and returns exact bytes', async () => {
+      const content = Buffer.from('hello');
+      sinon.stub(fs, 'readFile').resolves(content);
+      const result = await storage.readFile('file.txt');
+      assert.strictEqual(result, content);
+    });
+
+    it('bubbles up error when file does not exist', async () => {
+      sinon.stub(fs, 'readFile').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.readFile('missing.txt');
+      });
+    });
+  });
+
+  describe('upsertFile', () => {
+    beforeEach(() => {
+      storage = new LocalFileStorage('/root');
+    });
+
+    it('creates new file when absent', async () => {
+      const writeFileStub = sinon.stub(fs, 'writeFile').resolves();
+      await storage.upsertFile('file.txt', 'content');
+      sinon.assert.calledWith(
+        writeFileStub,
+        path.join('/root', 'file.txt'),
+        Buffer.from('content', 'utf8'),
+        { flag: 'w' }
+      );
+    });
+
+    it('overwrites existing file', async () => {
+      const writeFileStub = sinon.stub(fs, 'writeFile').resolves();
+      await storage.upsertFile('file.txt', Buffer.from('new content'));
+      sinon.assert.calledWith(
+        writeFileStub,
+        path.join('/root', 'file.txt'),
+        Buffer.from('new content'),
+        { flag: 'w' }
+      );
+    });
+
+    it('bubbles up error if parent directory does not exist', async () => {
+      sinon.stub(fs, 'writeFile').rejects(new Error('ENOENT'));
+      await assert.rejects(async () => {
+        await storage.upsertFile('nonexistent/file.txt', 'content');
+      });
+    });
+  });
+});

package/src/storage/LocalFileStorage.ts

@@ -0,0 +1,98 @@
+import { FileDetails, FileStorage, ListFilesFilter } from "./FileStorage";
+import { FileStorageUtilities } from "./FileStorageUtilities";
+import fs from "fs/promises";
+import * as path from "node:path";
+
+/**
+ * A `FileStorage` implementation that uses the local file system.
+ */
+export class LocalFileStorage implements FileStorage {
+    private _rootFolder: string | undefined;
+
+    /**
+     * Creates a new `LocalFileStorage` instance.
+     * @param rootFolder Optional. Root folder to use for file operations. If not provided, paths passed to operations should be fully qualified.
+     */
+    constructor(rootFolder?: string) {
+        this._rootFolder = rootFolder;
+    }
+
+    async createFile(filePath: string, content: Buffer|string): Promise<void> {
+        // Convert content to buffer if it's a string
+        if (typeof content == 'string') {
+            content = Buffer.from(content, 'utf8');
+        }
+
+        // Write the file
+        await fs.writeFile(this.getFullPath(filePath), content, { flag: 'wx' });
+    }
+
+    async createFolder(folderPath: string): Promise<void> {
+        await fs.mkdir(this.getFullPath(folderPath), { recursive: true });
+    }
+
+    async deleteFile(filePath: string): Promise<void> {
+        await fs.unlink(this.getFullPath(filePath));
+    }
+
+    async deleteFolder(folderPath: string): Promise<void> {
+        await fs.rm(this.getFullPath(folderPath), { recursive: true });
+    }
+
+    async getDetails(fileOrFolderPath: string): Promise<FileDetails> {
+        const stats = await fs.stat(this.getFullPath(fileOrFolderPath));
+        return {
+            name: path.basename(fileOrFolderPath),
+            path: fileOrFolderPath,
+            isFolder: stats.isDirectory(),
+            fileType: stats.isFile() ? FileStorageUtilities.getFileType(fileOrFolderPath) : undefined
+        };
+    }
+
+    async listFiles(folderPath: string, _filter?: ListFilesFilter | undefined): Promise<FileDetails[]> {
+        const folder = this.getFullPath(folderPath);
+        const list = await fs.readdir(folder, { withFileTypes: true });
+        return list.map((entry) => {
+            return {
+                name: entry.name,
+                path: path.join(folder, entry.name),
+                isFolder: entry.isDirectory(),
+                fileType: entry.isFile() ? FileStorageUtilities.getFileType(entry.name) : undefined
+            };
+        });
+    }
+
+    async pathExists(fileOrFolderPath: string): Promise<boolean> {
+        try {
+            await fs.access(this.getFullPath(fileOrFolderPath));
+            return true;
+        } catch (err: unknown) {
+            return false;
+        }
+    }
+
+    async readFile(filePath: string): Promise<Buffer> {
+        return await fs.readFile(this.getFullPath(filePath));
+    }
+
+    async upsertFile(filePath: string, content: Buffer|string): Promise<void> {
+         // Convert content to buffer if it's a string
+         if (typeof content == 'string') {
+            content = Buffer.from(content, 'utf8');
+        }
+
+        // Write the file
+       await fs.writeFile(this.getFullPath(filePath), content, { flag: 'w' });
+    }
+
+    private getFullPath(relativePath: string): string {
+        if (!this._rootFolder) {
+            return relativePath.length > 0 ? relativePath : '.';
+        } else if (relativePath.length == 0) {
+            return this._rootFolder;
+        } else {
+            return path.join(this._rootFolder, relativePath);
+        }
+    }
+
+}

package/src/storage/VirtualFileStorage.spec.ts

@@ -0,0 +1,307 @@
+import assert from 'node:assert';
+import * as path from 'path';
+import { VirtualFileStorage } from './VirtualFileStorage';
+import { FileStorageUtilities } from './FileStorageUtilities';
+
+describe('VirtualFileStorage', () => {
+  let storage: VirtualFileStorage;
+
+  beforeEach(() => {
+    storage = new VirtualFileStorage();
+  });
+
+  describe('createFile', () => {
+    it('creates a new file with string content', async () => {
+      await storage.createFile('file.txt', 'hello');
+      const details = await storage.getDetails('file.txt');
+      assert.strictEqual(details.name, 'file.txt');
+      assert.strictEqual(details.path, path.normalize('file.txt'));
+      assert.strictEqual(details.isFolder, false);
+      assert.strictEqual(
+        details.fileType,
+        FileStorageUtilities.getFileType(path.normalize('file.txt'))
+      );
+      const content = await storage.readFile('file.txt');
+      assert.deepStrictEqual(content, Buffer.from('hello', 'utf8'));
+    });
+
+    it('creates a new file with Buffer content', async () => {
+      const buf = Buffer.from('buffer content');
+      await storage.createFile('bufferfile.bin', buf);
+      const content = await storage.readFile('bufferfile.bin');
+      assert.deepStrictEqual(content, buf);
+    });
+
+    it('throws when file already exists (including folder at path)', async () => {
+      await storage.createFile('dup.txt', 'content');
+      await assert.rejects(async () => {
+        await storage.createFile('dup.txt', 'new content');
+      }, /File already exists/);
+
+      await storage.createFolder('folder');
+      await assert.rejects(async () => {
+        await storage.createFile('folder', 'content');
+      }, /File already exists/);
+    });
+
+    it('throws when creating file with normalized duplicate path', async () => {
+      await storage.createFile('a/../b/file.txt', 'content');
+      await assert.rejects(async () => {
+        await storage.createFile('b/file.txt', 'content');
+      }, /File already exists/);
+    });
+  });
+
+  describe('createFolder', () => {
+    it('creates a new folder', async () => {
+      await storage.createFolder('myfolder');
+      const details = await storage.getDetails('myfolder');
+      assert.strictEqual(details.name, 'myfolder');
+      assert.strictEqual(details.isFolder, true);
+      assert.strictEqual(details.fileType, undefined);
+    });
+
+    it('is idempotent when folder already exists', async () => {
+      await storage.createFolder('myfolder');
+      await storage.createFolder('myfolder'); // no error
+    });
+
+    it('throws when a file exists at that path', async () => {
+      await storage.createFile('file.txt', 'content');
+      await assert.rejects(async () => {
+        await storage.createFolder('file.txt');
+      }, /Cannot create folder/);
+    });
+
+    it('does not create parent folders automatically', async () => {
+      // Implementation creates only the explicit folder entry
+      await storage.createFolder('parent/child');
+
+      // Only 'parent/child' exists, not 'parent'
+      await assert.rejects(async () => {
+        await storage.getDetails('parent');
+      }, /Path not found/);
+
+      const details = await storage.getDetails('parent/child');
+      assert.strictEqual(details.isFolder, true);
+    });
+  });
+
+  describe('deleteFile', () => {
+    it('deletes an existing file', async () => {
+      await storage.createFile('file.txt', 'content');
+      await storage.deleteFile('file.txt');
+      const exists = await storage.pathExists('file.txt');
+      assert.strictEqual(exists, false);
+      await assert.rejects(async () => {
+        await storage.readFile('file.txt');
+      }, /File not found/);
+    });
+
+    it('throws when deleting a folder as file', async () => {
+      await storage.createFolder('folder');
+      await assert.rejects(async () => {
+        await storage.deleteFile('folder');
+      }, /Cannot delete file/);
+    });
+
+    it('no error when deleting non-existent file', async () => {
+      await storage.deleteFile('nonexistent');
+    });
+  });
+
+  describe('deleteFolder', () => {
+    it('deletes an existing folder', async () => {
+      await storage.createFolder('folder');
+      await storage.deleteFolder('folder');
+      const exists = await storage.pathExists('folder');
+      assert.strictEqual(exists, false);
+    });
+
+    it('throws when deleting a file as folder', async () => {
+      await storage.createFile('file.txt', 'content');
+      await assert.rejects(async () => {
+        await storage.deleteFolder('file.txt');
+      }, /Cannot delete folder/);
+    });
+
+    it('no error when deleting non-existent folder', async () => {
+      await storage.deleteFolder('nonexistent');
+    });
+
+    it('does not delete children when deleting folder', async () => {
+      await storage.createFolder('parent');
+      await storage.createFile('parent/child.txt', 'content');
+      await storage.deleteFolder('parent');
+
+      // Parent deleted
+      const parentExists = await storage.pathExists('parent');
+      assert.strictEqual(parentExists, false);
+
+      // Child still exists
+      const childExists = await storage.pathExists('parent/child.txt');
+      assert.strictEqual(childExists, true);
+    });
+  });
+
+  describe('getDetails', () => {
+    it('returns details for existing file', async () => {
+      await storage.createFile('file.txt', 'content');
+      const details = await storage.getDetails('file.txt');
+      assert.strictEqual(details.name, 'file.txt');
+      assert.strictEqual(details.path, path.normalize('file.txt'));
+      assert.strictEqual(details.isFolder, false);
+      assert.strictEqual(
+        details.fileType,
+        FileStorageUtilities.getFileType(path.normalize('file.txt'))
+      );
+    });
+
+    it('returns details for existing folder', async () => {
+      await storage.createFolder('folder');
+      const details = await storage.getDetails('folder');
+      assert.strictEqual(details.name, 'folder');
+      assert.strictEqual(details.path, path.normalize('folder'));
+      assert.strictEqual(details.isFolder, true);
+      assert.strictEqual(details.fileType, undefined);
+    });
+
+    it('throws for non-existent path', async () => {
+      await assert.rejects(async () => {
+        await storage.getDetails('missing');
+      }, /Path not found/);
+    });
+  });
+
+  describe('listFiles', () => {
+    beforeEach(async () => {
+      await storage.createFolder('a');
+      await storage.createFolder('a/b');
+      await storage.createFile('a/file1.txt', 'content1');
+      await storage.createFile('a/b/file2.txt', 'content2');
+      await storage.createFolder('c');
+      await storage.createFile('fileRoot.txt', 'root');
+    });
+
+    it('returns immediate children only', async () => {
+      const listA = await storage.listFiles('a');
+      assert(listA.some(e => e.name === 'file1.txt'));
+      assert(listA.some(e => e.name === 'b'));
+      assert(!listA.some(e => e.name === 'file2.txt'));
+
+      const listRoot = await storage.listFiles('');
+      assert(listRoot.some(e => e.name === 'a'));
+      assert(listRoot.some(e => e.name === 'c'));
+      assert(listRoot.some(e => e.name === 'fileRoot.txt'));
+    });
+
+    it('respects filter "all"', async () => {
+      const all = await storage.listFiles('a', 'all');
+      assert(all.some(e => e.isFolder));
+      assert(all.some(e => !e.isFolder));
+    });
+
+    it('respects filter "files"', async () => {
+      const files = await storage.listFiles('a', 'files');
+      assert(files.every(e => !e.isFolder));
+      assert(files.some(e => e.name === 'file1.txt'));
+      assert(!files.some(e => e.name === 'b'));
+    });
+
+    it('respects filter "folders"', async () => {
+      const folders = await storage.listFiles('a', 'folders');
+      assert(folders.every(e => e.isFolder));
+      assert(folders.some(e => e.name === 'b'));
+      assert(!folders.some(e => e.name === 'file1.txt'));
+    });
+
+    it('normalizes folderPath', async () => {
+      const list1 = await storage.listFiles('a/');
+      const list2 = await storage.listFiles('a');
+      assert.deepStrictEqual(list1, list2);
+    });
+  });
+
+  describe('pathExists', () => {
+    it('returns true for existing file and folder', async () => {
+      await storage.createFile('file.txt', 'content');
+      await storage.createFolder('folder');
+      assert.strictEqual(await storage.pathExists('file.txt'), true);
+      assert.strictEqual(await storage.pathExists('folder'), true);
+    });
+
+    it('returns false for missing path', async () => {
+      assert.strictEqual(await storage.pathExists('missing'), false);
+    });
+  });
+
+  describe('readFile', () => {
+    it('returns exact Buffer written', async () => {
+      const buf = Buffer.from('data');
+      await storage.createFile('file.txt', buf);
+      const read = await storage.readFile('file.txt');
+      assert.deepStrictEqual(read, buf);
+    });
+
+    it('throws when path does not exist', async () => {
+      await assert.rejects(async () => {
+        await storage.readFile('missing.txt');
+      }, /File not found/);
+    });
+
+    it('throws when path is a folder', async () => {
+      await storage.createFolder('folder');
+      await assert.rejects(async () => {
+        await storage.readFile('folder');
+      }, /Cannot read file/);
+    });
+
+    it('returns empty buffer if content is undefined (forced)', async () => {
+      // Force an entry with undefined content to hit the fallback branch
+      (storage as any)._entries.set('emptyfile.txt', {
+        details: {
+          name: 'emptyfile.txt',
+          path: path.normalize('emptyfile.txt'),
+          isFolder: false,
+          fileType: FileStorageUtilities.getFileType(path.normalize('emptyfile.txt')),
+        },
+        content: undefined,
+      });
+      const content = await storage.readFile('emptyfile.txt');
+      assert.deepStrictEqual(content, Buffer.from('', 'utf8'));
+    });
+  });
+
+  describe('upsertFile', () => {
+    it('creates new file when missing with string content', async () => {
+      await storage.upsertFile('newfile.txt', 'content');
+      const details = await storage.getDetails('newfile.txt');
+      assert.strictEqual(details.isFolder, false);
+      assert.strictEqual(
+        details.fileType,
+        FileStorageUtilities.getFileType(path.normalize('newfile.txt'))
+      );
+      const content = await storage.readFile('newfile.txt');
+      assert.deepStrictEqual(content, Buffer.from('content', 'utf8'));
+    });
+
+    it('replaces content of existing file and keeps correct fileType', async () => {
+      await storage.createFile('file.txt', 'old');
+      await storage.upsertFile('file.txt', Buffer.from('new'));
+      const content = await storage.readFile('file.txt');
+      assert.deepStrictEqual(content, Buffer.from('new'));
+      const details = await storage.getDetails('file.txt');
+      assert.strictEqual(
+        details.fileType,
+        FileStorageUtilities.getFileType(path.normalize('file.txt'))
+      );
+    });
+
+    it('throws when a folder exists at that path', async () => {
+      await storage.createFolder('folder');
+      await assert.rejects(async () => {
+        await storage.upsertFile('folder', 'content');
+      }, /Cannot write file/);
+    });
+  });
+});