pushwork 1.0.0

package/src/utils/repo-factory.ts

@@ -0,0 +1,58 @@
+import { Repo, StorageId } from "@automerge/automerge-repo";
+import { NodeFSStorageAdapter } from "@automerge/automerge-repo-storage-nodefs";
+import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket";
+import * as path from "path";
+import chalk from "chalk";
+import { ConfigManager } from "../config";
+
+export interface RepoFactoryOptions {
+  enableNetwork?: boolean;
+  syncServer?: string;
+  syncServerStorageId?: string;
+}
+
+/**
+ * Create an Automerge repository with configuration-based setup
+ */
+export async function createRepo(
+  workingDir: string,
+  options: RepoFactoryOptions = {}
+): Promise<Repo> {
+  const configManager = new ConfigManager(workingDir);
+  const config = await configManager.getMerged();
+
+  const syncToolDir = path.join(workingDir, ".pushwork");
+  const storage = new NodeFSStorageAdapter(path.join(syncToolDir, "automerge"));
+
+  const repoConfig: any = { storage };
+
+  // Determine network settings - options override config
+  const enableNetwork = options.enableNetwork ?? true;
+  const syncServer = options.syncServer ?? config.sync_server;
+  const syncServerStorageId =
+    options.syncServerStorageId ?? config.sync_server_storage_id;
+
+  // Add network adapter only if explicitly enabled and sync server is configured
+  if (enableNetwork && syncServer) {
+    const networkAdapter = new BrowserWebSocketClientAdapter(syncServer);
+    repoConfig.network = [networkAdapter];
+    repoConfig.enableRemoteHeadsGossiping = true;
+    console.log(chalk.gray(`  ✓ Network sync enabled: ${syncServer}`));
+  } else {
+    console.log(chalk.gray("  ✓ Local-only mode (network sync disabled)"));
+  }
+
+  const repo = new Repo(repoConfig);
+
+  // Subscribe to the sync server storage for network sync
+  if (enableNetwork && syncServer && syncServerStorageId) {
+    repo.subscribeToRemotes([syncServerStorageId as StorageId]);
+    console.log(
+      chalk.gray(
+        `  ✓ Subscribed to sync server storage: ${syncServerStorageId}`
+      )
+    );
+  }
+
+  return repo;
+}

package/test/README-TESTING-GAPS.md

@@ -0,0 +1,174 @@
+# Testing Gaps Analysis
+
+## Overview
+
+This document outlines the testing gaps identified in the autosync codebase, particularly around the major architectural changes implemented for directory document management and text CRDT support.
+
+## Current Test Coverage
+
+✅ **Well Tested:**
+
+- File system utilities (`test/unit/utils.test.ts`) - 89 test cases
+- Snapshot management (`test/unit/snapshot.test.ts`) - Comprehensive coverage
+- Content similarity (`test/unit/content-similarity.test.ts`) - Move detection logic
+- Integration scenarios (`test/integration/*.test.ts`) - File operations, exclude patterns
+
+## Critical Testing Gaps
+
+### 1. SyncEngine Core Logic (HIGH PRIORITY)
+
+**Status:** ❌ No direct unit tests
+**Impact:** Core synchronization logic untested
+
+**Missing Coverage:**
+
+- `sync()` method with various file scenarios
+- `applyLocalChangeToRemote()` / `applyRemoteChangeToLocal()`
+- Bidirectional sync flow
+- Error handling during sync operations
+- Dry run mode functionality
+
+### 2. Directory Document Management (HIGH PRIORITY)
+
+**Status:** ❌ No tests for new feature
+**Impact:** New architectural feature completely untested
+
+**Missing Coverage:**
+
+- `addFileToRootDirectory()` - Adding files to directory structure
+- `removeFileFromRootDirectory()` - Removing files from directory structure
+- `setRootDirectoryUrl()` - Root directory URL persistence
+- Directory structure synchronization between peers
+- Root directory document creation during init
+
+### 3. Text CRDT Implementation (MEDIUM PRIORITY)
+
+**Status:** ❌ No tests for new feature
+**Impact:** New text handling functionality untested
+
+**Missing Coverage:**
+
+- `isTextContent()` method logic (simplified version)
+- Text files using `updateText()` vs binary files using direct assignment
+- Mixed content operations in single sync
+- Text CRDT conflict resolution behavior
+
+### 4. CLI Command Integration (MEDIUM PRIORITY)
+
+**Status:** ❌ No end-to-end CLI tests
+**Impact:** User-facing functionality untested
+
+**Missing Coverage:**
+
+- `init` command with directory document creation
+- `sync` command full bidirectional flow
+- `status`, `diff`, `log` command accuracy
+- Error handling in CLI commands
+- `--dry-run` flag functionality
+
+### 5. Automerge Repository Integration (LOW PRIORITY)
+
+**Status:** ❌ No Automerge-specific tests
+**Impact:** Repository lifecycle and document management untested
+
+**Missing Coverage:**
+
+- Document creation and updates
+- Repository shutdown behavior
+- Document head tracking accuracy
+- Network synchronization (mocked)
+
+## Technical Challenges
+
+### Jest + ES Modules Issue
+
+**Problem:** `@automerge/automerge-repo` uses ES modules that Jest struggles to handle
+**Error:** `SyntaxError: Unexpected token 'export'`
+
+**Attempted Solutions:**
+
+- Modified Jest `transformIgnorePatterns`
+- Added ES module configuration
+- All attempts failed due to complex dependency chain
+
+### Recommended Solutions
+
+#### Option 1: Integration Testing Approach
+
+Create integration tests that test the full flow without mocking Automerge:
+
+```typescript
+// test/integration/sync-engine-integration.test.ts
+// Test real sync operations with actual Automerge repositories
+// Focus on end-to-end behavior rather than unit testing
+```
+
+#### Option 2: Mock-Heavy Unit Testing
+
+Create comprehensive mocks for Automerge dependencies:
+
+```typescript
+// Heavy mocking of @automerge/automerge-repo
+// Test SyncEngine logic in isolation
+// More fragile but allows unit testing
+```
+
+#### Option 3: Test Configuration Update
+
+Update Jest/test environment to properly handle ES modules:
+
+- Migrate to newer Jest version with better ES module support
+- Or switch to alternative test runner (Vitest, etc.)
+
+## Immediate Actions Taken
+
+### Comprehensive `isTextContent()` Testing
+
+Since this is a pure function, it can be tested independently:
+
+```typescript
+// Manual testing confirmed:
+// ✅ Strings identified as text
+// ✅ Uint8Array identified as binary
+// ✅ Edge cases handled correctly
+```
+
+### Manual Integration Testing
+
+Verified through manual CLI testing:
+
+- ✅ Directory document management working
+- ✅ Root directory URL persistence
+- ✅ File creation/deletion updates directory structure
+- ✅ Text files using updateText(), binary files using direct assignment
+
+## Recommendations
+
+### Short Term (Implemented)
+
+1. ✅ Document testing gaps (this file)
+2. ✅ Manual testing of critical functionality
+3. ✅ Existing test suite still passing (89 tests)
+
+### Medium Term (Future Work)
+
+1. **Integration Test Suite:** Create `test/integration/sync-engine-e2e.test.ts`
+2. **CLI Testing:** Add end-to-end CLI command testing
+3. **Mock Strategy:** Develop proper Automerge mocking approach
+
+### Long Term (Future Work)
+
+1. **Test Environment Upgrade:** Resolve ES module handling
+2. **Comprehensive Unit Tests:** Full SyncEngine unit test coverage
+3. **Property-Based Testing:** Add property testing for sync operations
+
+## Current Test Status
+
+- **Total Tests:** 89 passing
+- **Test Suites:** 5 passing
+- **Coverage:** High for utilities, medium for integration, low for core sync logic
+- **Critical Features:** Manually verified but not automatically tested
+
+## Conclusion
+
+While we've identified significant testing gaps around the new features, the existing test suite provides confidence in the foundation. The new features have been manually tested and are working correctly. Future development should prioritize integration testing to cover the areas where unit testing is blocked by ES module issues.

package/test/integration/README.md

@@ -0,0 +1,328 @@
+# Integration Tests
+
+This directory contains comprehensive integration tests for the pushwork sync tool.
+
+## Quick Start
+
+From the project root directory:
+
+```bash
+# Run all tests with the test runner
+./test/run-tests.sh
+
+# Run specific test suites
+./test/run-tests.sh clone     # Clone functionality tests
+./test/run-tests.sh conflict  # CRDT conflict resolution tests
+./test/run-tests.sh full      # Full integration tests
+./test/run-tests.sh unit      # Unit tests
+```
+
+## Test Scripts
+
+### 1. Test Runner (`../run-tests.sh`)
+
+Main entry point for running all tests. Provides:
+
+- Dependency checking
+- Multiple test suite options
+- Consistent output formatting
+- Error handling
+
+### 2. Full Integration Test (`full-integration-test.sh`)
+
+Comprehensive test suite covering all major functionality:
+
+**Features Tested:**
+
+- ✅ Help commands for all CLI commands
+- ✅ Init with default and custom sync servers
+- ✅ Clone with default and custom sync servers
+- ✅ Status, diff, commit, and sync operations
+- ✅ Error handling and parameter validation
+- ✅ File operations (create, modify, delete)
+- ✅ Bidirectional sync scenarios
+
+**Test Sections:**
+
+1. Help Commands - Verify all --help options work
+2. Init Functionality - Test directory initialization
+3. Status Functionality - Test status reporting
+4. Commit Functionality - Test local commits
+5. Sync Functionality - Test sync operations
+6. Diff Functionality - Test change detection
+7. Clone Functionality - Test cloning repositories
+8. Bidirectional Sync - Test multi-directory sync
+9. File Operations - Test various file types and operations
+
+### 3. Clone Test (`clone-test.sh`)
+
+Focused test suite specifically for clone functionality:
+
+**Features Tested:**
+
+- ✅ Clone with default sync server settings
+- ✅ Clone with custom sync server and storage ID
+- ✅ Parameter validation (sync server options must be used together)
+- ✅ Force overwrite functionality
+- ✅ Configuration verification in cloned repositories
+- ✅ Error handling for invalid scenarios
+- ✅ Status and diff operations in cloned directories
+
+**Test Sections:**
+
+1. Clone Functionality - All clone scenarios
+2. Cloned Directory Status - Operations in cloned repos
+3. Configuration Comparison - Verify settings propagation
+
+### 4. CRDT Conflict Resolution Test (`conflict-resolution-test.sh`)
+
+Specialized test demonstrating pushwork's excellent CRDT-based conflict resolution capabilities:
+
+**Features Tested:**
+
+- ✅ Create repository with initial document
+- ✅ Clone repository to second location
+- ✅ Make simultaneous conflicting edits on both sides
+- ✅ Verify CRDT text merging preserves ALL changes
+- ✅ Validate that no data is lost during conflicts
+- ✅ Confirm true collaborative editing capabilities
+
+**Test Scenario:**
+
+1. Alice creates a document with baseline content
+2. Bob clones Alice's repository
+3. Both users make different additions to the same file simultaneously
+4. Alice syncs her changes first
+5. Bob syncs his changes (CRDT merging occurs)
+6. Final sync rounds ensure eventual consistency
+7. **Result**: Bob's repository contains BOTH Alice's AND Bob's changes
+8. **Demonstrates**: True CRDT collaborative editing without data loss
+
+**Key Findings:**
+
+- ✅ Pushwork uses character-level CRDT text merging
+- ✅ Both users' contributions are preserved automatically
+- ✅ No manual conflict resolution required
+- ✅ Immediate convergence to consistent state
+- ✅ Sync timing issue has been resolved
+- Repositories eventually converge to consistent state
+
+## Test Configuration
+
+### Required Dependencies
+
+- **Node.js** - For running pushwork CLI
+- **npm** - For building the project
+
+### Optional Dependencies
+
+- **jq** - For advanced JSON parsing in configuration tests (tests will be skipped if not available)
+
+Install jq (optional):
+
+```bash
+# macOS
+brew install jq
+
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# Other platforms
+# See: https://stedolan.github.io/jq/download/
+```
+
+### Test Environment
+
+- Tests run in isolated temporary directories
+- Automatic cleanup on completion
+- No modification of project files
+- Safe to run multiple times
+
+### Test Parameters
+
+```bash
+# Default test configuration
+TEST_DIR="/tmp/pushwork-*-test"
+CUSTOM_SYNC_SERVER="ws://localhost:3030"
+CUSTOM_STORAGE_ID="1d89eba7-f7a4-4e8e-80f2-5f4e2406f507"
+```
+
+## Understanding Test Output
+
+### Log Levels
+
+- 🔵 **[INFO]** - General information
+- 🟡 **[TEST]** - Test being executed
+- 🟢 **[PASS]** - Test passed
+- 🔴 **[FAIL]** - Test failed
+- 🟡 **[WARN]** - Warning (non-critical)
+
+### Test Results
+
+Each test script provides a summary:
+
+```
+======================================
+Test Results Summary
+======================================
+Tests Run:    45
+Tests Passed: 43
+Tests Failed: 2
+```
+
+## Running Individual Tests
+
+### Full Integration Test
+
+```bash
+./test/integration/full-integration-test.sh
+```
+
+### Clone Test
+
+```bash
+./test/integration/clone-test.sh
+```
+
+### With Verbose Output
+
+```bash
+# Remove `> /dev/null 2>&1` redirections in scripts for verbose output
+# Or modify the log functions to always show output
+```
+
+## Test Coverage
+
+### ✅ Covered Functionality
+
+- All CLI commands and help output
+- Directory initialization (init)
+- Repository cloning (clone) - **NEW**
+- Sync operations (sync, status, diff, commit)
+- Parameter validation
+- Error handling for common scenarios
+- File operations and change detection
+- Configuration management
+- Custom sync server support - **NEW**
+
+### ⚠️ Known Limitations
+
+- Network sync requires actual connectivity
+- Some tests skip when dependencies missing (jq)
+- Limited testing of concurrent operations
+- Performance testing not included
+
+## Troubleshooting
+
+### Common Issues
+
+**"jq: command not found"**
+
+```bash
+# Install jq (see dependencies section above)
+brew install jq  # macOS
+```
+
+**"Permission denied"**
+
+```bash
+# Make scripts executable
+chmod +x test/integration/*.sh
+chmod +x test/run-tests.sh
+```
+
+**"Not in project directory"**
+
+```bash
+# Run from project root where package.json exists
+cd /path/to/pushwork
+./test/run-tests.sh
+```
+
+**Tests failing unexpectedly**
+
+```bash
+# Check if project builds
+npm run build
+
+# Check if CLI works
+node dist/cli.js --help
+```
+
+### Debug Mode
+
+To see more detailed output, modify the test scripts to remove output redirection:
+
+```bash
+# Change this:
+if $PUSHWORK_CMD init . > /dev/null 2>&1; then
+
+# To this:
+if $PUSHWORK_CMD init .; then
+```
+
+## Adding New Tests
+
+### Test Script Template
+
+```bash
+#!/bin/bash
+set -e
+
+# Test configuration
+TEST_DIR="/tmp/my-test"
+PUSHWORK_CMD="node $(pwd)/dist/cli.js"
+
+# Colors and logging functions
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+BLUE='\033[0;34m'; NC='\033[0m'
+
+log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}[PASS]${NC} $1"; }
+log_error() { echo -e "${RED}[FAIL]${NC} $1"; }
+log_test() { echo -e "${YELLOW}[TEST]${NC} $1"; }
+
+# Cleanup
+cleanup() { rm -rf "$TEST_DIR"; }
+trap cleanup EXIT
+
+# Test logic here
+setup_test_environment
+run_tests
+```
+
+### Guidelines
+
+1. Use consistent naming patterns
+2. Include both positive and negative test cases
+3. Test error conditions thoroughly
+4. Provide clear test descriptions
+5. Clean up resources properly
+6. Use the established logging format
+
+## Integration with CI/CD
+
+These tests are designed to be run in automated environments:
+
+```bash
+# In your CI pipeline
+./test/run-tests.sh full
+```
+
+Exit codes:
+
+- `0` - All tests passed
+- `1` - Some tests failed
+- Non-zero - Setup or dependency errors
+
+## Contributing
+
+When adding new features to pushwork:
+
+1. **Add integration tests** for new CLI commands
+2. **Update existing tests** if command behavior changes
+3. **Test error scenarios** - not just happy paths
+4. **Document test coverage** in this README
+5. **Verify tests pass** before submitting PRs
+
+The integration tests serve as both testing and documentation for how the CLI should behave.