pushwork 1.0.4 → 1.0.7

package/README.md

@@ -1,27 +1,16 @@
 # Pushwork
 
-A bidirectional file synchronization system using Automerge CRDTs for conflict-free collaborative editing.
+Bidirectional file synchronization using Automerge CRDTs for conflict-free collaborative editing.
 
-## Overview
+## Features
 
-Pushwork enables real-time collaboration on directories and files using **Conflict-free Replicated Data Types (CRDTs)**. Unlike traditional sync tools that require manual conflict resolution, Pushwork automatically merges changes from multiple users while preserving everyone's work.
-
-## Key Features
-
-- **Bidirectional Sync**: Keep local directories synchronized with remote Automerge repositories
-- **Conflict-Free**: Automatic conflict resolution using Automerge CRDTs - no merge conflicts ever
+- **Conflict-Free Sync**: Automatic conflict resolution using Automerge CRDTs
 - **Real-time Collaboration**: Multiple users can edit the same files simultaneously
 - **Intelligent Move Detection**: Detects file renames and moves based on content similarity
-- **Incremental Sync**: Only synchronizes changed files for maximum efficiency
-- **Network Resilient**: Works offline and gracefully handles network interruptions
+- **Offline Support**: Works offline and gracefully handles network interruptions
 - **Cross-Platform**: Runs on Windows, macOS, and Linux
-- **Rich CLI**: Full-featured command-line interface with comprehensive tooling
-
-## Quick Start
 
-### Installation
-
-Currently, install from source:
+## Installation
 
 ```bash
 pnpm install
@@ -29,207 +18,89 @@ pnpm run build
 pnpm link --global
 ```
 
-Note: you can also run this from NPX, I think.
-
-### Basic Usage
+Requires: Node.js 18+, pnpm 8.15.0+
 
-1. **Initialize a new repository:**
+## Quick Start
 
 ```bash
+# Initialize a directory
 pushwork init ./my-project
-```
-
-2. **Clone an existing repository:**
 
-```bash
-pushwork clone <automerge-url> ./cloned-project
-```
+# Clone an existing repository
+pushwork clone <automerge-url> ./project
 
-3. **Sync changes:**
-
-```bash
+# Sync changes
 pushwork sync
-```
 
-4. **Check status:**
-
-```bash
+# Check status
 pushwork status
-```
-
-## Commands
-
-### `init <path> [options]`
-
-Initialize sync in a directory, creating a new Automerge repository.
-
-```bash
-# Initialize with default sync server
-pushwork init ./my-project
-
-# Initialize with custom sync server
-pushwork init ./my-project \
-  --sync-server ws://localhost:3030 \
-  --sync-server-storage-id your-storage-id
-```
-
-**Options:**
-
-- `--sync-server <url>`: Custom sync server URL (requires storage-id)
-- `--sync-server-storage-id <id>`: Custom sync server storage ID (requires server)
 
-### `clone <url> <path> [options]`
-
-Clone an existing synced directory from an Automerge URL.
-
-```bash
-# Clone from default sync server
-pushwork clone automerge:abc123... ./cloned-project
-
-# Clone with custom sync server
-pushwork clone automerge:abc123... ./cloned-project \
-  --sync-server ws://localhost:3030 \
-  --sync-server-storage-id your-storage-id
-
-# Force overwrite existing directory
-pushwork clone automerge:abc123... ./existing-dir --force
-```
-
-**Options:**
-
-- `--force`: Overwrite existing directory
-- `--sync-server <url>`: Custom sync server URL
-- `--sync-server-storage-id <id>`: Custom sync server storage ID
-
-### `sync [options]`
-
-Run bidirectional synchronization between local files and remote repository.
-
-```bash
-# Preview changes without applying them
-pushwork sync --dry-run
-
-# Apply all changes
-pushwork sync
-
-# Verbose output
-pushwork sync --verbose
-```
-
-**Options:**
-
-- `--dry-run`: Preview changes without applying them
-- `--verbose`: Show detailed progress information
-
-### `diff [path] [options]`
-
-Show differences between local and remote state.
-
-```bash
-# Show all changes
-pushwork diff
-
-# Show changes for specific path
-pushwork diff src/
-
-# Show only changed file names
-pushwork diff --name-only
-
-# Use external diff tool
-pushwork diff --tool meld
+# Get shareable URL
+pushwork url
 ```
 
-**Options:**
-
-- `--tool <tool>`: Use external diff tool (meld, vimdiff, etc.)
-- `--name-only`: Show only changed file names
-
-### `status`
+## Commands
 
-Show current sync status and repository information.
+### Core Commands
 
-```bash
-pushwork status
-```
+**`init [path]`** - Initialize sync in a directory
 
-### `log [path] [options]`
+- `--sync-server <url>` - Custom sync server URL
+- `--sync-server-storage-id <id>` - Custom storage ID
+- `--debug` - Export performance flame graphs
 
-Show sync history for the repository or specific files.
+**`clone <url> <path>`** - Clone an existing synced directory
 
-```bash
-# Show repository history
-pushwork log
+- `--force` - Overwrite existing directory
+- `--sync-server <url>` - Custom sync server URL
+- `--sync-server-storage-id <id>` - Custom storage ID
 
-# Compact one-line format
-pushwork log --oneline
+**`sync [path]`** - Run bidirectional synchronization
 
-# History for specific path
-pushwork log src/important-file.txt
-```
+- `--dry-run` - Preview changes without applying
+- `--verbose` - Show detailed progress
+- `--debug` - Export performance flame graphs
 
-**Options:**
+**`status [path]`** - Show sync status and repository info
 
-- `--oneline`: Compact one-line per sync format
-- `--since <date>`: Show syncs since date
-- `--limit <n>`: Limit number of syncs shown (default: 10)
+- `--verbose` - Show detailed status including all tracked files
 
-### `url [path]`
+**`commit [path]`** - Commit local changes without network sync
 
-Show the Automerge root URL for sharing with others.
+- `--dry-run` - Preview what would be committed
+- `--debug` - Export performance flame graphs
 
-```bash
-# Get URL for current directory
-pushwork url
+### Utility Commands
 
-# Get URL for specific directory
-pushwork url ./my-project
-```
+**`diff [path]`** - Show differences between local and remote
 
-### `commit [path] [options]`
+- `--name-only` - Show only changed file names
 
-Commit local changes without network sync (useful for offline work).
+**`url [path]`** - Show the Automerge root URL for sharing
 
-```bash
-# Commit all changes
-pushwork commit
+**`ls [path]`** - List tracked files
 
-# Preview what would be committed
-pushwork commit --dry-run
+- `--long` - Show Automerge URLs
 
-# Commit specific directory
-pushwork commit ./src
-```
+**`config [path]`** - View or edit configuration
 
-**Options:**
+- `--list` - Show full configuration
+- `--get <key>` - Get specific config value (dot notation)
 
-- `--dry-run`: Show what would be committed without applying changes
+**`rm [path]`** - Remove local pushwork data
 
-### `checkout <sync-id> [path] [options]`
+**`watch [path]`** - Watch directory, build, and sync automatically
 
-Restore directory to state from previous sync (not yet implemented).
+- `--script <command>` - Build script (default: "pnpm build")
+- `--dir <dir>` - Directory to watch (default: "src")
+- `--verbose` - Show build output
 
-```bash
-# Restore entire directory
-pushwork checkout sync-123
+**`log [path]`** - Show sync history _(experimental, limited functionality)_
 
-# Force checkout even with uncommitted changes
-pushwork checkout sync-123 --force
-```
+**`checkout <sync-id> [path]`** - Restore to previous sync _(not yet implemented)_
 
 ## Configuration
 
-### Default Configuration
-
-Pushwork uses sensible defaults:
-
-- **Sync Server**: `wss://sync3.automerge.org`
-- **Storage ID**: `3760df37-a4c6-4f66-9ecd-732039a9385d`
-- **Excluded Patterns**: `.git`, `node_modules`, `*.tmp`, `.pushwork`
-- **Large File Threshold**: 100MB
-- **Move Detection Threshold**: 80% similarity
-
-### Directory Configuration
-
 Configuration is stored in `.pushwork/config.json`:
 
 ```json
@@ -255,36 +126,23 @@ Configuration is stored in `.pushwork/config.json`:
 
 ## How It Works
 
-### CRDT-Based Conflict Resolution
-
-Pushwork uses **Automerge CRDTs** to automatically resolve conflicts:
-
-- **Text Files**: Character-level merging preserves all changes
-- **Binary Files**: Last-writer-wins with automatic convergence
-- **Directory Structure**: Additive merging supports simultaneous file creation
-- **File Moves**: Intelligent detection prevents data loss during renames
-
-### Two-Phase Sync Process
-
-1. **Push Phase**: Apply local changes to Automerge documents
-2. **Pull Phase**: Apply remote changes to local filesystem
-3. **Convergence**: All repositories eventually reach identical state
+Pushwork uses Automerge CRDTs for automatic conflict resolution:
 
-### Change Detection
+- **Text files**: Character-level merging preserves all changes
+- **Binary files**: Last-writer-wins with automatic convergence
+- **Directories**: Additive merging supports simultaneous file creation
 
-- **Content-Based**: Uses Automerge document heads, not timestamps
-- **Efficient**: Only processes actually changed files
-- **Reliable**: Works across time zones and file system differences
-- **Resumable**: Interrupted syncs can be safely resumed
+Sync process:
 
-### Move Detection Algorithm
+1. **Push**: Apply local changes to Automerge documents
+2. **Pull**: Apply remote changes to local filesystem
+3. **Convergence**: All repositories reach identical state
 
-- Compares content similarity between deleted and created files
-- **Auto-apply**: Moves with >80% similarity (configurable)
-- **User prompt**: Moves with 50-80% similarity (configurable)
-- **Ignore**: Moves with <50% similarity
+State tracking:
 
-## Architecture
+- `.pushwork/snapshot.json` - Tracks sync state and file mappings
+- `.pushwork/config.json` - Configuration settings
+- Content-based change detection using Automerge document heads
 
 ### Document Schema
 
@@ -296,7 +154,10 @@ Pushwork uses **Automerge CRDTs** to automatically resolve conflicts:
   name: string;
   extension: string;
   mimeType: string;
-  content: Text | Uint8Array;
+  content: ImmutableString | Uint8Array;
+  metadata: {
+    permissions: number;
+  };
 }
 ```
 
@@ -310,153 +171,51 @@ Pushwork uses **Automerge CRDTs** to automatically resolve conflicts:
     type: "file" | "folder";
     url: AutomergeUrl;
   }>;
+  lastSyncAt?: number;
 }
 ```
 
-### Local State Management
+## Development
 
-- **Snapshot File**: `.pushwork/snapshot.json` tracks sync state
-- **Path Mapping**: Links filesystem paths to Automerge document URLs
-- **Head Tracking**: Enables efficient change detection
-- **Configuration**: `.pushwork/config.json` stores sync settings
-
-### Network Architecture
-
-- **Sync Server**: Handles real-time synchronization between clients
-- **Storage ID**: Isolates different collaboration groups
-- **WebSocket Connection**: Provides real-time updates
-- **Graceful Degradation**: Works offline with manual sync
-
-## Testing
-
-### Running Tests
-
-```bash
-# Build the project
-npm run build
-
-# Run unit tests
-npm test
-
-# Run integration tests
-./test/run-tests.sh
-
-# Test conflict resolution
-./test/integration/conflict-resolution-test.sh
-
-# Test clone functionality
-./test/integration/clone-test.sh
-```
-
-### Test Coverage
-
-- **Unit Tests**: Core functionality and utilities
-- **Integration Tests**: End-to-end sync scenarios
-- **Conflict Resolution**: CRDT merging behavior
-- **Clone Operations**: Repository sharing workflows
-
-## 🛠️ Development
-
-### Prerequisites
-
-- Node.js 18+
-- TypeScript 5+
-- pnpm (recommended) or npm
-
-### Development Setup
+### Setup
 
 ```bash
 git clone <repository-url>
 cd pushwork
-npm install
-npm run build
-
-# Development mode
-npm run dev
-
-# Watch mode for testing
-npm run test:watch
+pnpm install
+pnpm run build
+pnpm run dev          # Watch mode
+pnpm test             # Run tests
+pnpm run test:watch   # Watch mode for tests
 ```
 
 ### Project Structure
 
 ```
 src/
-├── cli/           # Command-line interface
-├── core/          # Core sync engine
-├── config/        # Configuration management
-├── types/         # TypeScript type definitions
-└── utils/         # Shared utilities
-
-test/
-├── unit/          # Unit tests
-└── integration/   # Integration tests
+├── cli/        # Command-line interface
+├── core/       # Core sync engine
+├── config/     # Configuration management
+├── tracing/    # Performance tracing
+├── types/      # TypeScript type definitions
+└── utils/      # Shared utilities
 ```
 
-## Real-World Collaboration Example
+### Testing
 
 ```bash
-# Alice initializes a project
-alice$ pushwork init ./shared-docs
-alice$ echo "Hello World" > shared-docs/readme.txt
-alice$ pushwork sync
-alice$ pushwork url
-# automerge:2V4w7zv8zkJYJxJsKaYhZ5NPjxA1
-
-# Bob clones Alice's project
-bob$ pushwork clone automerge:2V4w7zv8zkJYJxJsKaYhZ5NPjxA1 ./bobs-copy
-
-# Both edit the same file simultaneously
-alice$ echo "Alice's changes" >> shared-docs/readme.txt
-bob$ echo "Bob's changes" >> bobs-copy/readme.txt
-
-# Both sync - no conflicts!
-alice$ pushwork sync
-bob$ pushwork sync
-alice$ pushwork sync  # Gets Bob's changes
-
-# Final result contains both changes merged automatically
-alice$ cat shared-docs/readme.txt
-Hello World
-Alice's changes
-Bob's changes
+pnpm test                                              # Unit tests
+./test/run-tests.sh                                    # All integration tests
+./test/integration/conflict-resolution-test.sh         # Specific test
 ```
 
-## Troubleshooting
-
-### Common Issues
-
-**WebSocket Connection Errors**: Usually safe to ignore during shutdown
-
-**"Directory not initialized"**: Run `pushwork init .` first
-
-**Network Sync Timeout**: Check internet connection and sync server status
-
-**File Permission Errors**: Ensure write access to target directory
-
-### Debug Mode
+### Profiling
 
 ```bash
-# Enable verbose logging
-pushwork sync --verbose
-
-# Preview changes without applying
-pushwork sync --dry-run
-
-# Check repository status
-pushwork status
+pushwork sync --debug                                  # Export flame graphs
+clinic flame --collect-only -- node --enable-source-maps --prof $(pnpm root -g)/pushwork/dist/cli.js sync
 ```
 
 ## License
 
-MIT License - see LICENSE file for details.
-
-## Links
-
-- **Issues**: Report bugs and request features
-- **Documentation**: Additional guides and tutorials
-- **Automerge**: Learn more about CRDT technology
-
----
-
-** Ready to collaborate conflict-free? Get started with `pushwork init`!**
+MIT License

package/dist/.pushwork/automerge/st/orage-adapter-id

@@ -0,0 +1 @@
+e43182b5-f406-4319-8bac-ee54d9dec4a9

package/dist/.pushwork/config.json

@@ -0,0 +1,15 @@
+{
+  "sync_enabled": true,
+  "sync_server": "wss://sync3.automerge.org",
+  "sync_server_storage_id": "3760df37-a4c6-4f66-9ecd-732039a9385d",
+  "exclude_patterns": [
+    ".git",
+    "node_modules",
+    "*.tmp",
+    ".pushwork",
+    ".DS_Store"
+  ],
+  "sync": {
+    "move_detection_threshold": 0.7
+  }
+}

package/dist/.pushwork/snapshot.json

@@ -0,0 +1,7 @@
+{
+  "timestamp": 1764206435572,
+  "rootPath": "C:\\Users\\pvh\\Dev\\pushwork\\dist",
+  "rootDirectoryUrl": "automerge:3PDm3ekE2pmjGnWvDaG3vSR7ww98",
+  "files": [],
+  "directories": []
+}