pushwork 1.0.0

package/test/unit/sync-timing.test.ts

@@ -0,0 +1,178 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { tmpdir } from "os";
+
+describe("Sync Timing Analysis", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = await fs.mkdtemp(path.join(tmpdir(), "sync-timing-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe("File Operation Timing", () => {
+    it("should measure rapid file operations timing", async () => {
+      const startTime = Date.now();
+
+      // Simulate rapid file operations similar to sync
+      const promises: Promise<void>[] = [];
+      for (let i = 0; i < 10; i++) {
+        promises.push(
+          fs.writeFile(path.join(testDir, `file${i}.txt`), `content${i}`)
+        );
+      }
+
+      await Promise.all(promises);
+      const totalTime = Date.now() - startTime;
+
+      console.log(`Created 10 files in ${totalTime}ms`);
+
+      // Verify all files exist
+      const files = await fs.readdir(testDir);
+      expect(files).toHaveLength(10);
+
+      // This test shows us baseline file operation timing
+      expect(totalTime).toBeLessThan(1000); // Should be fast for local operations
+    });
+
+    it("should measure sequential vs parallel file operations", async () => {
+      // Sequential operations
+      const sequentialStart = Date.now();
+      for (let i = 0; i < 5; i++) {
+        await fs.writeFile(path.join(testDir, `seq${i}.txt`), `content${i}`);
+      }
+      const sequentialTime = Date.now() - sequentialStart;
+
+      // Parallel operations
+      const parallelStart = Date.now();
+      const promises: Promise<void>[] = [];
+      for (let i = 0; i < 5; i++) {
+        promises.push(
+          fs.writeFile(path.join(testDir, `par${i}.txt`), `content${i}`)
+        );
+      }
+      await Promise.all(promises);
+      const parallelTime = Date.now() - parallelStart;
+
+      console.log(
+        `Sequential: ${sequentialTime}ms, Parallel: ${parallelTime}ms`
+      );
+
+      // Parallel should generally be faster
+      expect(parallelTime).toBeLessThanOrEqual(sequentialTime);
+
+      // Verify all files exist
+      const files = await fs.readdir(testDir);
+      expect(files).toHaveLength(10);
+    });
+
+    it("should test file operation atomicity", async () => {
+      const filePath = path.join(testDir, "test.txt");
+
+      // Write initial content
+      await fs.writeFile(filePath, "initial content");
+
+      // Rapid successive writes to same file
+      const writes: Promise<void>[] = [];
+      for (let i = 0; i < 5; i++) {
+        writes.push(fs.writeFile(filePath, `updated content ${i}`));
+      }
+
+      await Promise.all(writes);
+
+      // Check final content (should be one of the updates)
+      const finalContent = await fs.readFile(filePath, "utf8");
+      expect(finalContent).toMatch(/updated content \d/);
+
+      console.log(`Final content after rapid writes: "${finalContent}"`);
+    });
+  });
+
+  describe("Sync Completion Scenarios", () => {
+    it("should simulate the need for sync completion detection", async () => {
+      // This test simulates what might happen with network sync
+      // where we need to wait for operations to complete
+
+      const results: { operation: string; time: number }[] = [];
+
+      // Simulate "local" operations (fast)
+      const localStart = Date.now();
+      await fs.writeFile(path.join(testDir, "local.txt"), "local content");
+      const localTime = Date.now() - localStart;
+      results.push({ operation: "local write", time: localTime });
+
+      // Simulate "network" operations (slower with artificial delay)
+      const networkStart = Date.now();
+      await new Promise((resolve) => setTimeout(resolve, 50)); // 50ms delay
+      await fs.writeFile(path.join(testDir, "network.txt"), "network content");
+      const networkTime = Date.now() - networkStart;
+      results.push({ operation: "network write", time: networkTime });
+
+      console.log("Operation timing:");
+      results.forEach((r) => {
+        console.log(`  ${r.operation}: ${r.time}ms`);
+      });
+
+      // This demonstrates why we might need to wait for slower operations
+      expect(networkTime).toBeGreaterThan(localTime);
+      expect(networkTime).toBeGreaterThan(40); // Should include our delay
+    });
+
+    it("should test what happens without proper completion waiting", async () => {
+      // Simulate starting an operation but not waiting for it
+      const promises: Promise<void>[] = [];
+
+      // Start operations without awaiting
+      for (let i = 0; i < 3; i++) {
+        promises.push(
+          (async () => {
+            await new Promise((resolve) => setTimeout(resolve, 10 * i)); // Varying delays
+            await fs.writeFile(
+              path.join(testDir, `async${i}.txt`),
+              `content${i}`
+            );
+          })()
+        );
+      }
+
+      // Check immediately (before operations complete)
+      const filesImmediate = await fs.readdir(testDir);
+      console.log(`Files immediately: ${filesImmediate.length}`);
+
+      // Now wait for operations to complete
+      await Promise.all(promises);
+
+      // Check after completion
+      const filesAfter = await fs.readdir(testDir);
+      console.log(`Files after completion: ${filesAfter.length}`);
+
+      // This shows the difference between checking immediately vs waiting
+      expect(filesAfter.length).toBeGreaterThanOrEqual(filesImmediate.length);
+      expect(filesAfter).toHaveLength(3);
+    });
+  });
+
+  describe("Potential Race Conditions", () => {
+    it("should test for potential race conditions in file operations", async () => {
+      const sharedFile = path.join(testDir, "shared.txt");
+
+      // Multiple operations on the same file
+      const operations = [
+        fs.writeFile(sharedFile, "operation1"),
+        fs.writeFile(sharedFile, "operation2"),
+        fs.writeFile(sharedFile, "operation3"),
+      ];
+
+      await Promise.all(operations);
+
+      // Only one operation should "win"
+      const content = await fs.readFile(sharedFile, "utf8");
+      expect(["operation1", "operation2", "operation3"]).toContain(content);
+
+      console.log(`Final content from race condition: "${content}"`);
+    });
+  });
+});

package/test/unit/utils.test.ts

@@ -0,0 +1,368 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as tmp from "tmp";
+import {
+  pathExists,
+  getFileSystemEntry,
+  isTextFile,
+  readFileContent,
+  writeFileContent,
+  ensureDirectoryExists,
+  removePath,
+  listDirectory,
+  copyFile,
+  movePath,
+  calculateContentHash,
+  getMimeType,
+  getFileExtension,
+  normalizePath,
+  getRelativePath,
+} from "../../src/utils/fs";
+import { FileType } from "../../src/types";
+
+describe("File System Utilities", () => {
+  let tmpDir: string;
+  let cleanup: () => void;
+
+  beforeEach(() => {
+    const tmpObj = tmp.dirSync({ unsafeCleanup: true });
+    tmpDir = tmpObj.name;
+    cleanup = tmpObj.removeCallback;
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  describe("pathExists", () => {
+    it("should return true for existing files", async () => {
+      const filePath = path.join(tmpDir, "test.txt");
+      await fs.writeFile(filePath, "test content");
+
+      expect(await pathExists(filePath)).toBe(true);
+    });
+
+    it("should return false for non-existing files", async () => {
+      const filePath = path.join(tmpDir, "nonexistent.txt");
+
+      expect(await pathExists(filePath)).toBe(false);
+    });
+
+    it("should return true for existing directories", async () => {
+      expect(await pathExists(tmpDir)).toBe(true);
+    });
+  });
+
+  describe("getFileSystemEntry", () => {
+    it("should return metadata for files", async () => {
+      const filePath = path.join(tmpDir, "test.txt");
+      await fs.writeFile(filePath, "test content");
+
+      const entry = await getFileSystemEntry(filePath);
+
+      expect(entry).not.toBeNull();
+      expect(entry?.path).toBe(filePath);
+      expect(entry?.type).toBe(FileType.TEXT);
+      expect(entry?.size).toBe(12); // 'test content'.length
+      expect(entry?.mtime).toBeDefined();
+      expect(entry?.mtime.getTime()).toBeGreaterThan(0);
+      expect(typeof entry?.mtime.getTime()).toBe("number");
+    });
+
+    it("should return metadata for directories", async () => {
+      const dirPath = path.join(tmpDir, "subdir");
+      await fs.mkdir(dirPath);
+
+      const entry = await getFileSystemEntry(dirPath);
+
+      expect(entry).not.toBeNull();
+      expect(entry?.path).toBe(dirPath);
+      expect(entry?.type).toBe(FileType.DIRECTORY);
+    });
+
+    it("should return null for non-existing paths", async () => {
+      const entry = await getFileSystemEntry(path.join(tmpDir, "nonexistent"));
+      expect(entry).toBeNull();
+    });
+  });
+
+  describe("isTextFile", () => {
+    it("should detect text files by extension", async () => {
+      const filePath = path.join(tmpDir, "test.txt");
+      await fs.writeFile(filePath, "text content");
+
+      expect(await isTextFile(filePath)).toBe(true);
+    });
+
+    it("should detect JSON files as text", async () => {
+      const filePath = path.join(tmpDir, "test.json");
+      await fs.writeFile(filePath, '{"key": "value"}');
+
+      expect(await isTextFile(filePath)).toBe(true);
+    });
+
+    it("should detect binary files by content", async () => {
+      const filePath = path.join(tmpDir, "test.bin");
+      const binaryContent = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+      await fs.writeFile(filePath, binaryContent);
+
+      expect(await isTextFile(filePath)).toBe(false);
+    });
+  });
+
+  describe("readFileContent", () => {
+    it("should read text files as strings", async () => {
+      const filePath = path.join(tmpDir, "test.txt");
+      const content = "Hello, world!";
+      await fs.writeFile(filePath, content);
+
+      const result = await readFileContent(filePath);
+
+      expect(typeof result).toBe("string");
+      expect(result).toBe(content);
+    });
+
+    it("should read TypeScript files as strings", async () => {
+      const filePath = path.join(tmpDir, "component.ts");
+      const content = "interface User { name: string; age: number; }";
+      await fs.writeFile(filePath, content);
+
+      const result = await readFileContent(filePath);
+
+      expect(typeof result).toBe("string");
+      expect(result).toBe(content);
+    });
+
+    it("should read TSX files as strings", async () => {
+      const filePath = path.join(tmpDir, "Component.tsx");
+      const content = "export const App = () => <div>Hello World</div>;";
+      await fs.writeFile(filePath, content);
+
+      const result = await readFileContent(filePath);
+
+      expect(typeof result).toBe("string");
+      expect(result).toBe(content);
+    });
+
+    it("should read Vue files as strings", async () => {
+      const filePath = path.join(tmpDir, "App.vue");
+      const content = "<template><div>{{ message }}</div></template>";
+      await fs.writeFile(filePath, content);
+
+      const result = await readFileContent(filePath);
+
+      expect(typeof result).toBe("string");
+      expect(result).toBe(content);
+    });
+
+    it("should read SCSS files as strings", async () => {
+      const filePath = path.join(tmpDir, "styles.scss");
+      const content = "$primary: #007bff; .btn { color: $primary; }";
+      await fs.writeFile(filePath, content);
+
+      const result = await readFileContent(filePath);
+
+      expect(typeof result).toBe("string");
+      expect(result).toBe(content);
+    });
+
+    it("should read binary files as Uint8Array", async () => {
+      const filePath = path.join(tmpDir, "test.bin");
+      const binaryContent = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+      await fs.writeFile(filePath, binaryContent);
+
+      const result = await readFileContent(filePath);
+
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(Array.from(result as Uint8Array)).toEqual([
+        0x00, 0x01, 0x02, 0x03,
+      ]);
+    });
+  });
+
+  describe("writeFileContent", () => {
+    it("should write string content to files", async () => {
+      const filePath = path.join(tmpDir, "output.txt");
+      const content = "Test content";
+
+      await writeFileContent(filePath, content);
+
+      const written = await fs.readFile(filePath, "utf8");
+      expect(written).toBe(content);
+    });
+
+    it("should write binary content to files", async () => {
+      const filePath = path.join(tmpDir, "output.bin");
+      const content = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
+
+      await writeFileContent(filePath, content);
+
+      const written = await fs.readFile(filePath);
+      expect(Array.from(written)).toEqual([0x00, 0x01, 0x02, 0x03]);
+    });
+
+    it("should create directories if they don't exist", async () => {
+      const filePath = path.join(tmpDir, "nested", "deep", "file.txt");
+
+      await writeFileContent(filePath, "content");
+
+      expect(await pathExists(filePath)).toBe(true);
+      expect(await fs.readFile(filePath, "utf8")).toBe("content");
+    });
+  });
+
+  describe("ensureDirectoryExists", () => {
+    it("should create directories recursively", async () => {
+      const dirPath = path.join(tmpDir, "nested", "deep", "directory");
+
+      await ensureDirectoryExists(dirPath);
+
+      expect(await pathExists(dirPath)).toBe(true);
+      const stats = await fs.stat(dirPath);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    it("should not fail if directory already exists", async () => {
+      await ensureDirectoryExists(tmpDir);
+      await ensureDirectoryExists(tmpDir); // Should not throw
+
+      expect(await pathExists(tmpDir)).toBe(true);
+    });
+  });
+
+  describe("removePath", () => {
+    it("should remove files", async () => {
+      const filePath = path.join(tmpDir, "toremove.txt");
+      await fs.writeFile(filePath, "content");
+
+      await removePath(filePath);
+
+      expect(await pathExists(filePath)).toBe(false);
+    });
+
+    it("should remove directories recursively", async () => {
+      const dirPath = path.join(tmpDir, "toremove");
+      const filePath = path.join(dirPath, "file.txt");
+      await fs.mkdir(dirPath);
+      await fs.writeFile(filePath, "content");
+
+      await removePath(dirPath);
+
+      expect(await pathExists(dirPath)).toBe(false);
+    });
+
+    it("should not fail if path doesn't exist", async () => {
+      const nonExistentPath = path.join(tmpDir, "nonexistent");
+
+      await removePath(nonExistentPath); // Should not throw
+
+      expect(await pathExists(nonExistentPath)).toBe(false);
+    });
+  });
+
+  describe("listDirectory", () => {
+    beforeEach(async () => {
+      // Create test directory structure
+      await fs.mkdir(path.join(tmpDir, "subdir"));
+      await fs.writeFile(path.join(tmpDir, "file1.txt"), "content1");
+      await fs.writeFile(path.join(tmpDir, "file2.txt"), "content2");
+      await fs.writeFile(path.join(tmpDir, "subdir", "file3.txt"), "content3");
+    });
+
+    it("should list directory contents non-recursively", async () => {
+      const entries = await listDirectory(tmpDir, false);
+
+      const names = entries.map((e) => path.basename(e.path)).sort();
+      expect(names).toEqual(["file1.txt", "file2.txt", "subdir"]);
+    });
+
+    it("should list directory contents recursively", async () => {
+      const entries = await listDirectory(tmpDir, true);
+
+      const relativePaths = entries
+        .map((e) => path.relative(tmpDir, e.path))
+        .sort();
+
+      expect(relativePaths).toContain("file1.txt");
+      expect(relativePaths).toContain("file2.txt");
+      expect(relativePaths).toContain("subdir");
+      expect(relativePaths).toContain(path.join("subdir", "file3.txt"));
+    });
+  });
+
+  describe("calculateContentHash", () => {
+    it("should generate consistent hashes for string content", async () => {
+      const content = "test content";
+
+      const hash1 = await calculateContentHash(content);
+      const hash2 = await calculateContentHash(content);
+
+      expect(hash1).toBe(hash2);
+      expect(hash1).toHaveLength(64); // SHA-256 hex string
+    });
+
+    it("should generate consistent hashes for binary content", async () => {
+      const content = new Uint8Array([0x00, 0x01, 0x02, 0x03]);
+
+      const hash1 = await calculateContentHash(content);
+      const hash2 = await calculateContentHash(content);
+
+      expect(hash1).toBe(hash2);
+      expect(hash1).toHaveLength(64);
+    });
+
+    it("should generate different hashes for different content", async () => {
+      const content1 = "content1";
+      const content2 = "content2";
+
+      const hash1 = await calculateContentHash(content1);
+      const hash2 = await calculateContentHash(content2);
+
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+
+  describe("getMimeType", () => {
+    it("should return correct MIME type for text files", () => {
+      expect(getMimeType("test.txt")).toBe("text/plain");
+      expect(getMimeType("test.json")).toBe("application/json");
+      expect(getMimeType("test.html")).toBe("text/html");
+    });
+
+    it("should return default MIME type for unknown extensions", () => {
+      expect(getMimeType("test.unknown")).toBe("application/octet-stream");
+    });
+  });
+
+  describe("getFileExtension", () => {
+    it("should extract file extensions", () => {
+      expect(getFileExtension("test.txt")).toBe("txt");
+      expect(getFileExtension("archive.tar.gz")).toBe("gz");
+      expect(getFileExtension("noextension")).toBe("");
+    });
+  });
+
+  describe("normalizePath", () => {
+    it("should normalize path separators", () => {
+      expect(normalizePath("path\\to\\file")).toBe("path/to/file");
+      expect(normalizePath("path/to/file")).toBe("path/to/file");
+      expect(normalizePath("path//to//file")).toBe("path/to/file");
+    });
+  });
+
+  describe("getRelativePath", () => {
+    it("should return relative paths", () => {
+      const base = "/home/user/project";
+      const target = "/home/user/project/src/file.txt";
+
+      expect(getRelativePath(base, target)).toBe("src/file.txt");
+    });
+
+    it("should handle same directory", () => {
+      const base = "/home/user/project";
+      const target = "/home/user/project";
+
+      expect(getRelativePath(base, target)).toBe(".");
+    });
+  });
+});

package/tools/browser-sync/README.md

@@ -0,0 +1,116 @@
+# Browser Folder Sync - Patchwork Tool
+
+A patchwork tool that enables synchronizing local folders with Patchwork documents using the Chrome File System Access API.
+
+## Features
+
+- **📂 Folder Selection**: Native browser folder picker with persistent access
+- **🔄 Real-time Sync**: Manual sync with visual progress indicators
+- **📋 File Listing**: Browse files and folders with size information
+- **⚙️ Configurable Settings**: Auto-sync, exclude patterns, sync intervals
+- **🛡️ Permission Management**: Proper handling of File System Access API permissions
+- **🎨 Modern UI**: Clean, responsive interface with status indicators
+
+## Browser Support
+
+This tool requires browsers that support the File System Access API:
+
+- ✅ Chrome 86+
+- ✅ Edge 86+
+- ✅ Safari 15.2+ (limited support)
+- ❌ Firefox (not supported yet)
+
+## Usage
+
+1. **Load the Tool**: The tool appears as "Browser Sync" for folder documents in Patchwork
+2. **Select Folder**: Click "Select Folder" to choose a local directory
+3. **Grant Permissions**: Allow the browser to access the selected folder
+4. **Sync Files**: Use "Sync Now" for manual synchronization
+5. **Configure Settings**: Toggle auto-sync and adjust settings as needed
+
+## Technical Implementation
+
+### Architecture
+
+```
+Browser Sync Tool
+├── SimpleBrowserSyncTool.tsx    # Main React component
+├── polyfills.ts                 # Node.js browser compatibility
+├── types.ts                     # TypeScript interfaces
+└── styles.css                   # Tool styling
+```
+
+### Key Technologies
+
+- **File System Access API**: Native browser folder access
+- **React**: Component-based UI framework
+- **Patchwork SDK**: Integration with Patchwork platform
+- **Automerge**: CRDT-based document synchronization
+- **Vite**: Modern build tooling with browser optimization
+
+### Browser Polyfills
+
+The tool includes comprehensive polyfills for Node.js globals:
+
+- `process` object with environment variables
+- `Buffer` minimal implementation
+- `global` reference for compatibility
+
+### Build Configuration
+
+Vite configuration excludes Node.js modules and provides browser-safe aliases:
+
+- Disabled: `fs`, `path`, `crypto`, `glob`, and other Node.js modules
+- Polyfilled: `process`, `Buffer`, `global`
+- Optimized: ES2022 target with tree-shaking
+
+## Current Limitations
+
+1. **Demo Implementation**: Sync functionality is currently simulated
+2. **Basic File Listing**: No recursive directory traversal
+3. **No Real Persistence**: Changes aren't actually synced to Automerge docs
+4. **Simple UI**: Basic interface without advanced features
+
+## Future Enhancements
+
+To complete the full pushwork integration:
+
+1. **Real Sync Engine**: Integrate with pushwork's browser sync engine
+2. **Change Detection**: Implement file modification monitoring
+3. **Conflict Resolution**: Add CRDT-based merge capabilities
+4. **Performance**: Optimize for large directories
+5. **Advanced UI**: Add progress bars, conflict indicators, etc.
+
+## Development
+
+### Build Commands
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build for production
+pnpm run build
+
+# Watch mode (with auto-push to Patchwork)
+pnpm run watch
+```
+
+### Project Structure
+
+```
+tools/browser-sync/
+├── dist/                    # Built output
+├── src/
+│   ├── components/
+│   │   └── SimpleBrowserSyncTool.tsx
+│   ├── polyfills.ts
+│   ├── types.ts
+│   ├── index.ts
+│   └── styles.css
+├── package.json
+├── vite.config.ts
+└── patchwork.json
+```
+
+This tool demonstrates the foundation for browser-based file synchronization and can be extended to provide full pushwork compatibility for web-based collaborative editing.

package/tools/browser-sync/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pushwork/browser-sync",
+  "version": "0.1.0",
+  "description": "Browser folder sync tool for Patchwork",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "push": "pnpm build && patchwork push",
+    "watch": "nodemon --watch src -e js,tsx,ts,css,json --exec 'pnpm build && pnpm push'"
+  },
+  "keywords": [
+    "patchwork",
+    "sync",
+    "filesystem",
+    "browser",
+    "automerge"
+  ],
+  "author": "Pushwork Team",
+  "dependencies": {
+    "@automerge/automerge-repo": "2.0.0-alpha.23",
+    "@automerge/automerge-repo-react-hooks": "2.0.0-alpha.23",
+    "@patchwork/sdk": "file:../../../patchwork/sdk",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "pushwork": "file:../../",
+    "lucide-react": "^0.460.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@vitejs/plugin-react": "^4.3.1",
+    "nodemon": "^3.1.9",
+    "typescript": "^5.2.0",
+    "vite": "^5.3.4",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vite-plugin-top-level-await": "^1.4.2",
+    "vite-plugin-wasm": "^3.3.0"
+  },
+  "license": "MIT"
+}