pushwork 1.0.16 → 1.0.18

package/src/core/sync-engine.ts

@@ -37,6 +37,11 @@ import {ChangeDetector} from "./change-detection"
 import {MoveDetector} from "./move-detection"
 import {out} from "../utils/output"
 
+const isDebug = !!process.env.DEBUG
+function debug(...args: any[]) {
+	if (isDebug) console.error("[pushwork:engine]", ...args)
+}
+
 /**
  * Apply a change to a document handle, using changeAt when heads are available
  * to branch from a known version, otherwise falling back to change.
@@ -105,6 +110,30 @@ export class SyncEngine {
 		return stringifyAutomergeUrl({documentId, heads})
 	}
 
+	/**
+	 * Determine if a file path is inside an artifact directory.
+	 * Artifact files are stored as immutable strings (RawString) and
+	 * referenced with versioned URLs in directory entries.
+	 */
+	private isArtifactPath(filePath: string): boolean {
+		const artifactDirs = this.config.artifact_directories || []
+		return artifactDirs.some(
+			dir => filePath === dir || filePath.startsWith(dir + "/")
+		)
+	}
+
+	/**
+	 * Get the appropriate URL for a directory entry.
+	 * Artifact paths get versioned URLs (with heads) for exact version fetching.
+	 * Non-artifact paths get plain URLs for collaborative editing.
+	 */
+	private getEntryUrl(handle: DocHandle<unknown>, filePath: string): AutomergeUrl {
+		if (this.isArtifactPath(filePath)) {
+			return this.getVersionedUrl(handle)
+		}
+		return getPlainUrl(handle.url)
+	}
+
 	/**
 	 * Set the root directory URL in the snapshot
 	 */
@@ -240,8 +269,11 @@ export class SyncEngine {
 				(await this.snapshotManager.load()) ||
 				this.snapshotManager.createEmpty()
 
+			debug(`sync: rootDirectoryUrl=${snapshot.rootDirectoryUrl?.slice(0, 30)}..., files=${snapshot.files.size}, dirs=${snapshot.directories.size}`)
+
 			// Wait for initial sync to receive any pending remote changes
 			if (this.config.sync_enabled && snapshot.rootDirectoryUrl) {
+				debug("sync: waiting for initial bidirectional sync")
 				try {
 					await waitForBidirectionalSync(
 						this.repo,
@@ -259,6 +291,7 @@ export class SyncEngine {
 			}
 
 			// Detect all changes
+			debug("sync: detecting changes")
 			const changes = await this.changeDetector.detectChanges(snapshot)
 
 			// Detect moves
@@ -267,7 +300,10 @@ export class SyncEngine {
 				snapshot
 			)
 
+			debug(`sync: detected ${changes.length} changes, ${moves.length} moves, ${remainingChanges.length} remaining`)
+
 			// Phase 1: Push local changes to remote
+			debug("sync: phase 1 - pushing local changes")
 			const phase1Result = await this.pushLocalChanges(
 				remainingChanges,
 				moves,
@@ -279,6 +315,8 @@ export class SyncEngine {
 			result.errors.push(...phase1Result.errors)
 			result.warnings.push(...phase1Result.warnings)
 
+			debug(`sync: phase 1 complete - ${phase1Result.filesChanged} files, ${phase1Result.directoriesChanged} dirs changed`)
+
 			// Wait for network sync (important for clone scenarios)
 			if (this.config.sync_enabled) {
 				try {
@@ -296,6 +334,7 @@ export class SyncEngine {
 						const allHandles = Array.from(
 							this.handlesByPath.values()
 						)
+						debug(`sync: waiting for ${allHandles.length} handles to sync to server`)
 						await waitForSync(
 							allHandles,
 							this.config.sync_server_storage_id
@@ -303,6 +342,7 @@ export class SyncEngine {
 					}
 
 					// Wait for bidirectional sync to stabilize
+					debug("sync: waiting for bidirectional sync to stabilize")
 					await waitForBidirectionalSync(
 						this.repo,
 						snapshot.rootDirectoryUrl,
@@ -314,12 +354,14 @@ export class SyncEngine {
 						}
 					)
 				} catch (error) {
+					debug(`sync: network sync error: ${error}`)
 					out.taskLine(`Network sync failed: ${error}`, true)
 					result.warnings.push(`Network sync failed: ${error}`)
 				}
 			}
 
 			// Re-detect changes after network sync for fresh state
+			debug("sync: re-detecting changes after network sync")
 			const freshChanges = await this.changeDetector.detectChanges(snapshot)
 			const freshRemoteChanges = freshChanges.filter(
 				c =>
@@ -327,6 +369,7 @@ export class SyncEngine {
 					c.changeType === ChangeType.BOTH_CHANGED
 			)
 
+			debug(`sync: phase 2 - pulling ${freshRemoteChanges.length} remote changes`)
 			// Phase 2: Pull remote changes to local using fresh detection
 			const phase2Result = await this.pullRemoteChanges(
 				freshRemoteChanges,
@@ -508,8 +551,8 @@ export class SyncEngine {
 						// New file
 						const handle = await this.createRemoteFile(change)
 						if (handle) {
-							const versionedUrl = this.getVersionedUrl(handle)
-							newEntries.push({name: fileName, url: versionedUrl})
+							const entryUrl = this.getEntryUrl(handle, change.path)
+							newEntries.push({name: fileName, url: entryUrl})
 							this.snapshotManager.updateFileEntry(
 								snapshot,
 								change.path,
@@ -518,7 +561,7 @@ export class SyncEngine {
 										this.rootPath,
 										change.path
 									),
-									url: versionedUrl,
+									url: entryUrl,
 									head: handle.heads(),
 									extension: getFileExtension(change.path),
 									mimeType: getEnhancedMimeType(change.path),
@@ -534,7 +577,7 @@ export class SyncEngine {
 							snapshot,
 							change.path
 						)
-						// Get current versioned URL (updateRemoteFile updates snapshot)
+						// Get current entry URL (updateRemoteFile updates snapshot)
 						const updatedFileEntry = snapshot.files.get(change.path)
 						if (updatedFileEntry) {
 							const fileHandle =
@@ -543,7 +586,7 @@ export class SyncEngine {
 								)
 							updatedEntries.push({
 								name: fileName,
-								url: this.getVersionedUrl(fileHandle),
+								url: this.getEntryUrl(fileHandle, change.path),
 							})
 						}
 						result.filesChanged++
@@ -574,7 +617,7 @@ export class SyncEngine {
 							)
 						subdirUpdates.push({
 							name: childName,
-							url: this.getVersionedUrl(childHandle),
+							url: this.getEntryUrl(childHandle, modifiedDir),
 						})
 					}
 				}
@@ -688,12 +731,11 @@ export class SyncEngine {
 					)
 
 					if (fileEntry) {
-						// Get versioned URL from handle (includes heads)
 						const fileHandle = await this.repo.find<FileDocument>(fileEntry.url)
-						const versionedUrl = this.getVersionedUrl(fileHandle)
+						const entryUrl = this.getEntryUrl(fileHandle, change.path)
 						this.snapshotManager.updateFileEntry(snapshot, change.path, {
 							path: localPath,
-							url: versionedUrl,
+							url: entryUrl,
 							head: change.remoteHead,
 							extension: getFileExtension(change.path),
 							mimeType: getEnhancedMimeType(change.path),
@@ -755,11 +797,11 @@ export class SyncEngine {
 				}
 			})
 
-			// Get versioned URL after changes (includes current heads)
-			const versionedUrl = this.getVersionedUrl(handle)
+			// Get appropriate URL for directory entry
+			const entryUrl = this.getEntryUrl(handle, move.toPath)
 
-			// 4) Add file entry to destination directory with versioned URL
-			await this.addFileToDirectory(snapshot, move.toPath, versionedUrl)
+			// 4) Add file entry to destination directory
+			await this.addFileToDirectory(snapshot, move.toPath, entryUrl)
 
 			// Track file handle for network sync
 			this.handlesByPath.set(move.toPath, handle)
@@ -769,7 +811,7 @@ export class SyncEngine {
 			this.snapshotManager.updateFileEntry(snapshot, move.toPath, {
 				...fromEntry,
 				path: joinAndNormalizePath(this.rootPath, move.toPath),
-				url: versionedUrl,
+				url: entryUrl,
 				head: handle.heads(),
 			})
 		} catch (e) {
@@ -790,15 +832,21 @@ export class SyncEngine {
 		if (change.localContent === null) return null
 
 		const isText = this.isTextContent(change.localContent)
+		const isArtifact = this.isArtifactPath(change.path)
 
-		// Create initial document structure with empty string for text content.
-		// We then splice in the actual content so it's stored as collaborative text.
+		// For artifact files, store text as RawString (immutable snapshot).
+		// For regular files, store as collaborative text (empty string + splice).
 		const fileDoc: FileDocument = {
 			"@patchwork": {type: "file"},
 			name: change.path.split("/").pop() || "",
 			extension: getFileExtension(change.path),
 			mimeType: getEnhancedMimeType(change.path),
-			content: isText ? "" : change.localContent,
+			content:
+				isText && isArtifact
+					? new A.RawString(change.localContent as string) as unknown as string
+					: isText
+						? ""
+						: change.localContent,
 			metadata: {
 				permissions: 0o644,
 			},
@@ -806,8 +854,8 @@ export class SyncEngine {
 
 		const handle = this.repo.create(fileDoc)
 
-		// For text files, splice in the content so it's stored as collaborative text
-		if (isText && typeof change.localContent === "string") {
+		// For non-artifact text files, splice in the content so it's stored as collaborative text
+		if (isText && !isArtifact && typeof change.localContent === "string") {
 			handle.change((doc: FileDocument) => {
 				updateTextContent(doc, ["content"], change.localContent as string)
 			})
@@ -836,14 +884,21 @@ export class SyncEngine {
 		const doc = await handle.doc()
 		const rawContent = doc?.content
 
-		// If the existing content is an immutable string, we can't splice into it.
-		// Throw away the old document and create a brand new one with mutable text.
-		// The caller's batch directory update will pick up the new URL from snapshot.
-		if (rawContent != null && A.isImmutableString(rawContent)) {
-			out.taskLine(
-				`Replacing immutable string document for ${filePath}`,
-				true
-			)
+		// For artifact paths, always replace with a new document containing RawString.
+		// For non-artifact paths with immutable strings, replace with mutable text.
+		// In both cases we create a new document and update the snapshot URL.
+		const isArtifact = this.isArtifactPath(filePath)
+		if (
+			isArtifact ||
+			!doc ||
+			(rawContent != null && A.isImmutableString(rawContent))
+		) {
+			if (!isArtifact) {
+				out.taskLine(
+					`Replacing ${!doc ? 'unavailable' : 'immutable string'} document for ${filePath}`,
+					true
+				)
+			}
 			const fakeChange: DetectedChange = {
 				path: filePath,
 				changeType: ChangeType.LOCAL_ONLY,
@@ -855,10 +910,10 @@ export class SyncEngine {
 			}
 			const newHandle = await this.createRemoteFile(fakeChange)
 			if (newHandle) {
-				const versionedUrl = this.getVersionedUrl(newHandle)
+				const entryUrl = this.getEntryUrl(newHandle, filePath)
 				this.snapshotManager.updateFileEntry(snapshot, filePath, {
 					path: joinAndNormalizePath(this.rootPath, filePath),
-					url: versionedUrl,
+					url: entryUrl,
 					head: newHandle.heads(),
 					extension: getFileExtension(filePath),
 					mimeType: getEnhancedMimeType(filePath),
@@ -1040,19 +1095,18 @@ export class SyncEngine {
 						// Track discovered directory for sync
 						this.handlesByPath.set(directoryPath, childDirHandle)
 
-						// Get versioned URL for storage (includes current heads)
-						const versionedUrl = this.getVersionedUrl(childDirHandle)
+						// Get appropriate URL for directory entry
+						const entryUrl = this.getEntryUrl(childDirHandle, directoryPath)
 
-						// Update snapshot with discovered directory using versioned URL
+						// Update snapshot with discovered directory
 						this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
 							path: joinAndNormalizePath(this.rootPath, directoryPath),
-							url: versionedUrl,
+							url: entryUrl,
 							head: childDirHandle.heads(),
 							entries: [],
 						})
 
-						// Return versioned URL (callers use getPlainUrl() when they need to modify)
-						return versionedUrl
+						return entryUrl
 					} catch (resolveErr) {
 						// Failed to resolve directory - fall through to create a fresh directory document
 					}
@@ -1070,8 +1124,8 @@ export class SyncEngine {
 
 		const dirHandle = this.repo.create(dirDoc)
 
-		// Get versioned URL for the new directory (includes heads)
-		const versionedDirUrl = this.getVersionedUrl(dirHandle)
+		// Get appropriate URL for directory entry
+		const dirEntryUrl = this.getEntryUrl(dirHandle, directoryPath)
 
 		// Add this directory to its parent
 		// Use plain URL for mutable handle
@@ -1090,7 +1144,7 @@ export class SyncEngine {
 				doc.docs.push({
 					name: currentDirName,
 					type: "folder",
-					url: versionedDirUrl,
+					url: dirEntryUrl,
 				})
 				didChange = true
 			}
@@ -1107,16 +1161,15 @@ export class SyncEngine {
 			}
 		}
 
-		// Update snapshot with new directory (use versioned URL for storage)
+		// Update snapshot with new directory
 		this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
 			path: joinAndNormalizePath(this.rootPath, directoryPath),
-			url: versionedDirUrl,
+			url: dirEntryUrl,
 			head: dirHandle.heads(),
 			entries: [],
 		})
 
-		// Return versioned URL (callers use getPlainUrl() when they need to modify)
-		return versionedDirUrl
+		return dirEntryUrl
 	}
 
 	/**

package/src/types/config.ts

@@ -14,6 +14,7 @@ export interface GlobalConfig {
   sync_server?: string;
   sync_server_storage_id?: StorageId;
   exclude_patterns: string[];
+  artifact_directories: string[];
   sync: {
     move_detection_threshold: number;
   };

package/src/utils/network-sync.ts

@@ -9,6 +9,11 @@ import { out } from "./output";
 import { DirectoryDocument } from "../types";
 import { getPlainUrl } from "./directory";
 
+const isDebug = !!process.env.DEBUG;
+function debug(...args: any[]) {
+  if (isDebug) console.error("[pushwork:sync]", ...args);
+}
+
 /**
  * Wait for bidirectional sync to stabilize.
  * This function waits until document heads stop changing, indicating that
@@ -43,6 +48,8 @@ export async function waitForBidirectionalSync(
   let lastSeenHeads = new Map<string, string>();
   let stableCount = 0;
 
+  debug(`waitForBidirectionalSync: starting (timeout=${timeoutMs}ms, stableChecks=${stableChecksRequired})`);
+
   while (Date.now() - startTime < timeoutMs) {
     // Get current heads for all documents in the directory hierarchy
     const currentHeads = await getAllDocumentHeads(repo, rootDirectoryUrl);
@@ -52,10 +59,15 @@ export async function waitForBidirectionalSync(
 
     if (isStable) {
       stableCount++;
+      debug(`waitForBidirectionalSync: stable check ${stableCount}/${stableChecksRequired} (${currentHeads.size} docs)`);
       if (stableCount >= stableChecksRequired) {
+        debug(`waitForBidirectionalSync: converged in ${Date.now() - startTime}ms`);
         return; // Converged!
       }
     } else {
+      if (stableCount > 0) {
+        debug(`waitForBidirectionalSync: heads changed, resetting stable count`);
+      }
       stableCount = 0;
       lastSeenHeads = currentHeads;
     }
@@ -65,6 +77,7 @@ export async function waitForBidirectionalSync(
 
   // Timeout - but don't throw, just log a warning
   // The sync may still work, we just couldn't confirm stability
+  debug(`waitForBidirectionalSync: timed out after ${timeoutMs}ms`);
   out.taskLine(`Sync stability check timed out after ${timeoutMs}ms`, true);
 }
 
@@ -149,20 +162,22 @@ function headsMapEqual(
 export async function waitForSync(
   handlesToWaitOn: DocHandle<unknown>[],
   syncServerStorageId?: StorageId,
-  timeoutMs: number = 1000000,
+  timeoutMs: number = 60000,
 ): Promise<void> {
   const startTime = Date.now();
 
   if (!syncServerStorageId) {
-    // No sync server storage ID - skip network sync
+    debug("waitForSync: no sync server storage ID, skipping");
     return;
   }
 
   if (handlesToWaitOn.length === 0) {
-    // No documents to sync
+    debug("waitForSync: no documents to sync");
     return;
   }
 
+  debug(`waitForSync: waiting for ${handlesToWaitOn.length} documents (timeout=${timeoutMs}ms)`);
+
   let alreadySynced = 0;
 
   const promises = handlesToWaitOn.map((handle) => {
@@ -174,12 +189,14 @@ export async function waitForSync(
 
     if (wasAlreadySynced) {
       alreadySynced++;
+      debug(`waitForSync: ${handle.url.slice(0, 20)}... already synced`);
       return Promise.resolve();
     }
 
+    debug(`waitForSync: ${handle.url.slice(0, 20)}... waiting for convergence (remoteHeads=${remoteHeads ? 'present' : 'missing'})`);
+
     // Wait for convergence
     return new Promise<void>((resolve, reject) => {
-      // TODO: can we delete this polling?
       let pollInterval: NodeJS.Timeout;
 
       const cleanup = () => {
@@ -189,11 +206,13 @@ export async function waitForSync(
       };
 
       const onConverged = () => {
+        debug(`waitForSync: ${handle.url.slice(0, 20)}... converged in ${Date.now() - startTime}ms`);
         cleanup();
         resolve();
       };
 
       const timeout = setTimeout(() => {
+        debug(`waitForSync: ${handle.url.slice(0, 20)}... timed out after ${timeoutMs}ms`);
         cleanup();
         reject(
           new Error(
@@ -243,10 +262,10 @@ export async function waitForSync(
 
   try {
     await Promise.all(promises);
+    debug(`waitForSync: all ${handlesToWaitOn.length} documents synced in ${Date.now() - startTime}ms (${alreadySynced} were already synced)`);
   } catch (error) {
     const elapsed = Date.now() - startTime;
-    out.errorBlock("FAILED", `after ${elapsed}ms`);
-    out.crash(error);
+    debug(`waitForSync: failed after ${elapsed}ms: ${error}`);
     throw error;
   }
 }

package/test/integration/exclude-patterns.test.ts

@@ -106,6 +106,7 @@ describe("Exclude Patterns", () => {
       sync_server: "wss://test.server.com",
       sync_enabled: true,
       exclude_patterns: [".git", "*.tmp", ".pushwork", "*.env"],
+      artifact_directories: ["dist"],
       sync: {
         move_detection_threshold: 0.8,
       },

package/test/integration/fuzzer.test.ts

@@ -161,7 +161,7 @@ describe("Pushwork Fuzzer", () => {
       expect(contentA).toBe("Hello, Pushwork!");
       expect(contentB).toBe("Hello, Pushwork!");
       expect(contentA).toBe(contentB);
-    }, 10000); // 10 second timeout for this test
+    }, 30000); // 30 second timeout for this test
   });
 
   describe("Manual Fuzzing Tests", () => {

package/test/integration/sync-flow.test.ts

@@ -27,6 +27,7 @@ describe("Sync Flow Integration", () => {
         sync_server: "wss://test.server.com",
         sync_enabled: true,
         exclude_patterns: [".git", "*.tmp"],
+        artifact_directories: ["dist"],
         sync: {
           move_detection_threshold: 0.8,
         },
@@ -49,6 +50,7 @@ describe("Sync Flow Integration", () => {
         sync_server: "wss://local.server.com",
         sync_enabled: true,
         exclude_patterns: [".git", "*.tmp"],
+        artifact_directories: ["dist"],
         sync: {
           move_detection_threshold: 0.9,
         },