pushwork 1.1.8 → 1.2.2

package/src/commands.ts

@@ -18,6 +18,7 @@ import {
   DirectoryDocument,
   CommandOptions,
 } from "./types";
+import { DEFAULT_SUBDUCTION_SERVER } from "./types/config";
 import { SyncEngine } from "./core";
 import { pathExists, ensureDirectoryExists, formatRelativePath } from "./utils";
 import { ConfigManager } from "./core/config";
@@ -42,19 +43,38 @@ interface CommandContext {
  */
 async function initializeRepository(
   resolvedPath: string,
-  overrides: Partial<DirectoryConfig>
+  overrides: Partial<DirectoryConfig>,
+  sub: boolean = false
 ): Promise<{ config: DirectoryConfig; repo: Repo; syncEngine: SyncEngine }> {
   // Create .pushwork directory structure
   const syncToolDir = path.join(resolvedPath, ConfigManager.CONFIG_DIR);
   await ensureDirectoryExists(syncToolDir);
   await ensureDirectoryExists(path.join(syncToolDir, "automerge"));
 
+  // Persist Subduction mode + server in config so subsequent commands pick
+  // them up. Without persisting sync_server here, `.pushwork/config.json`
+  // would retain the default WebSocket server even in --sub mode, and
+  // `pushwork config` / `status` would misreport the endpoint.
+  if (sub) {
+    const { sync_server_storage_id: _discarded, ...rest } = overrides;
+    overrides = {
+      ...rest,
+      subduction: true,
+      sync_server: rest.sync_server ?? DEFAULT_SUBDUCTION_SERVER,
+    };
+  }
+
   // Create configuration with overrides
   const configManager = new ConfigManager(resolvedPath);
-  const config = await configManager.initializeWithOverrides(overrides);
+  let config = await configManager.initializeWithOverrides(overrides);
+
+  if (sub && config.sync_server_storage_id !== undefined) {
+    config = { ...config, sync_server_storage_id: undefined };
+    await configManager.save(config);
+  }
 
   // Create repository and sync engine
-  const repo = await createRepo(resolvedPath, config);
+  const repo = await createRepo(resolvedPath, config, sub);
   const syncEngine = new SyncEngine(repo, resolvedPath, config);
 
   return { config, repo, syncEngine };
@@ -83,12 +103,33 @@ async function setupCommandContext(
   let config: DirectoryConfig;
 
   if (options?.forceDefaults) {
-    // Force mode: use defaults, only preserving root_directory_url from local config
+    // Force mode: use defaults, only preserving backend-selection keys from
+    // local config (root_directory_url, subduction flag, and the sync
+    // endpoint the user originally chose). Everything else (exclude
+    // patterns, artifact dirs, move threshold, etc.) is reset to defaults.
     const localConfig = await configManager.load();
     config = configManager.getDefaultDirectoryConfig();
     if (localConfig?.root_directory_url) {
       config.root_directory_url = localConfig.root_directory_url;
     }
+    if (localConfig?.subduction) {
+      config.subduction = localConfig.subduction;
+      config.sync_server = localConfig.sync_server ?? DEFAULT_SUBDUCTION_SERVER;
+      // sync_server_storage_id is meaningless in Subduction mode; drop it
+      // so the in-memory config reflects reality.
+      config.sync_server_storage_id = undefined;
+    } else {
+      // WebSocket mode: preserve the user's custom server + storage id
+      // if they configured one. Without this, `pushwork sync` (default
+      // force mode) would silently reset a custom --sync-server back to
+      // DEFAULT_SYNC_SERVER on every run.
+      if (localConfig?.sync_server) {
+        config.sync_server = localConfig.sync_server;
+      }
+      if (localConfig?.sync_server_storage_id) {
+        config.sync_server_storage_id = localConfig.sync_server_storage_id;
+      }
+    }
   } else {
     config = await configManager.getMerged();
   }
@@ -98,8 +139,22 @@ async function setupCommandContext(
     config = { ...config, sync_enabled: options.syncEnabled };
   }
 
+  const sub = config.subduction ?? false;
+  if (sub) {
+    // Default to the Subduction endpoint only if the user hasn't
+    // configured one. Respect any explicit sync_server value (including
+    // custom Subduction endpoints set via `init --sub --sync-server ...`).
+    if (!config.sync_server) {
+      config.sync_server = DEFAULT_SUBDUCTION_SERVER;
+    }
+    // sync_server_storage_id is a WebSocket-mode concept; clear it so
+    // the in-memory config reflects what waitForSync actually uses
+    // (head-stability polling, not getSyncInfo verification).
+    config.sync_server_storage_id = undefined;
+  }
+
   // Create repo with config
-  const repo = await createRepo(resolvedPath, config);
+  const repo = await createRepo(resolvedPath, config, sub);
 
   // Create sync engine
   const syncEngine = new SyncEngine(repo, resolvedPath, config);
@@ -115,6 +170,18 @@ async function setupCommandContext(
  * Safely shutdown a repository with proper error handling
  */
 async function safeRepoShutdown(repo: Repo): Promise<void> {
+  // TEMPORARY WORKAROUND: pushwork's Subduction sync-verification only
+  // watches local head stability, which doesn't actually confirm the
+  // server received anything. Give any in-flight `syncWithAllPeers`
+  // calls a chance to finish (and the scheduler time to heal transient
+  // failures) before we tear the repo down. Remove once awaitSynced()
+  // (or equivalent) lands in @automerge/automerge-repo@subduction.
+  const graceMsEnv = process.env.PUSHWORK_SYNC_GRACE_MS;
+  const graceMs = graceMsEnv !== undefined ? Number(graceMsEnv) : 3000;
+  if (Number.isFinite(graceMs) && graceMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, graceMs));
+  }
+
   // Handle uncaught WebSocket errors that occur during shutdown
   const uncaughtErrorHandler = (err: Error) => {
     if (err.message.includes("WebSocket")) {
@@ -157,7 +224,12 @@ export async function init(
 ): Promise<void> {
   const resolvedPath = path.resolve(targetPath);
 
+  const sub = options.sub ?? false;
+
   out.task(`Initializing`);
+  if (sub) {
+    out.taskLine("Using Subduction sync backend", true);
+  }
 
   await ensureDirectoryExists(resolvedPath);
 
@@ -173,7 +245,7 @@ export async function init(
   const { repo, syncEngine, config } = await initializeRepository(resolvedPath, {
     sync_server: options.syncServer,
     sync_server_storage_id: options.syncServerStorageId,
-  });
+  }, sub);
 
   // Create new root directory document
   out.update("Creating root directory");
@@ -189,21 +261,31 @@ export async function init(
   // Set root directory URL in snapshot
   await syncEngine.setRootDirectoryUrl(rootHandle.url);
 
-  // Wait for root document to sync to server if sync is enabled
-  // This ensures the document is uploaded before we exit
-  // waitForSync() verifies the server has the document by comparing local and remote heads
-  if (config.sync_enabled && config.sync_server_storage_id) {
-    out.update("Syncing to server");
-    const { failed } = await waitForSync([rootHandle], config.sync_server_storage_id);
-    if (failed.length > 0) {
-      out.taskLine("Root document failed to sync to server", true);
-      // Continue anyway - the document is created locally and will sync later
+  // Wait for root document to sync to server if sync is enabled.
+  // With Subduction, we skip StorageId-based sync verification —
+  // the SubductionSource handles sync internally.
+  if (config.sync_enabled && !sub) {
+    if (config.sync_server_storage_id) {
+      out.update("Syncing to server");
+      const { failed } = await waitForSync([rootHandle], config.sync_server_storage_id);
+      if (failed.length > 0) {
+        out.taskLine("Root document failed to sync to server", true);
+        // Continue anyway - the document is created locally and will sync later
+      }
+    } else {
+      // WebSocket mode without a storage id can't verify delivery via
+      // getSyncInfo. Warn loudly so users don't silently end up with
+      // data that never reached the server.
+      out.taskLine(
+        "Warning: sync_server_storage_id is not set; skipping post-init sync verification",
+        true
+      );
     }
   }
 
   // Run initial sync to capture existing files
   out.update("Running initial sync");
-  const result = await syncEngine.sync();
+  const result = await syncEngine.sync({ sub });
 
   out.update("Writing to disk");
   await safeRepoShutdown(repo);
@@ -232,10 +314,15 @@ export async function sync(
       : "Syncing"
   );
 
-  const { repo, syncEngine } = await setupCommandContext(targetPath, {
+  const { repo, syncEngine, config } = await setupCommandContext(targetPath, {
     forceDefaults: !options.gentle,
   });
 
+  const sub = config.subduction ?? false;
+  if (sub) {
+    out.taskLine("Using Subduction sync backend (from config)", true);
+  }
+
   if (options.nuclear) {
     await syncEngine.nuclearReset();
   }
@@ -286,7 +373,7 @@ export async function sync(
     out.log("");
     out.log("Run without --dry-run to apply these changes");
   } else {
-    const result = await syncEngine.sync();
+    const result = await syncEngine.sync({ sub });
 
     out.taskLine("Writing to disk");
     await safeRepoShutdown(repo);
@@ -329,6 +416,12 @@ export async function sync(
         out.warn(`... and ${result.errors.length - 5} more errors`);
       }
     }
+
+    // Always print the root URL
+    const rootUrl = await syncEngine.getRootDirectoryUrl();
+    if (rootUrl) {
+      out.info(`Root: ${rootUrl}`);
+    }
   }
 
   process.exit();
@@ -460,6 +553,7 @@ export async function status(
   statusInfo["Files"] = syncStatus.snapshot
     ? `${fileCount} tracked`
     : undefined;
+  statusInfo["Backend"] = config?.subduction ? "subduction" : "websocket";
   statusInfo["Sync"] = config?.sync_server;
 
   // Add more detailed info in verbose mode
@@ -587,7 +681,12 @@ export async function clone(
 
   const resolvedPath = path.resolve(targetPath);
 
+  const sub = options.sub ?? false;
+
   out.task(`Cloning ${rootUrl}`);
+  if (sub) {
+    out.taskLine("Using Subduction sync backend", true);
+  }
 
   // Check if directory exists and handle --force
   if (await pathExists(resolvedPath)) {
@@ -617,13 +716,14 @@ export async function clone(
     {
       sync_server: options.syncServer,
       sync_server_storage_id: options.syncServerStorageId,
-    }
+    },
+    sub
   );
 
   // Connect to existing root directory and download files
   out.update("Downloading files");
   await syncEngine.setRootDirectoryUrl(rootUrl as AutomergeUrl);
-  const result = await syncEngine.sync();
+  const result = await syncEngine.sync({ sub });
 
   out.update("Writing to disk");
   await safeRepoShutdown(repo);
@@ -633,6 +733,7 @@ export async function clone(
   out.obj({
     Path: resolvedPath,
     Files: `${result.filesChanged} downloaded`,
+    Backend: config.subduction ? "subduction" : "websocket",
     Sync: config.sync_server,
   });
   out.successBlock("CLONED", rootUrl);
@@ -819,6 +920,7 @@ export async function config(
     // Show basic config info
     out.infoBlock("CONFIGURATION");
     out.obj({
+      Backend: config.subduction ? "subduction" : "websocket",
       "Sync server": config.sync_server || "default",
       "Sync enabled": config.sync_enabled ? "yes" : "no",
       Exclusions: config.exclude_patterns?.length,
@@ -838,10 +940,12 @@ export async function watch(
   const script = options.script || "pnpm build";
   const watchDir = options.watchDir || "src"; // Default to watching 'src' directory
   const verbose = options.verbose || false;
-  const { repo, syncEngine, workingDir } = await setupCommandContext(
-    targetPath
+  const { repo, syncEngine, config, workingDir } = await setupCommandContext(
+    targetPath,
   );
 
+  const sub = config.subduction ?? false;
+
   const absoluteWatchDir = path.resolve(workingDir, watchDir);
 
   // Check if watch directory exists
@@ -856,6 +960,9 @@ export async function watch(
     "WATCHING",
     `${chalk.underline(formatRelativePath(watchDir))} for changes...`
   );
+  if (sub) {
+    out.info("Using Subduction sync backend (from config)");
+  }
   out.info(`Build script: ${script}`);
   out.info(`Working directory: ${workingDir}`);
 
@@ -894,7 +1001,7 @@ export async function watch(
 
       // Run sync
       out.task("Syncing");
-      const result = await syncEngine.sync();
+      const result = await syncEngine.sync({ sub });
 
       if (result.success) {
         if (result.filesChanged === 0 && result.directoriesChanged === 0) {
@@ -1023,7 +1130,7 @@ async function runScript(
 export async function root(
   rootUrl: string,
   targetPath: string = ".",
-  options: { force?: boolean } = {}
+  options: { force?: boolean; sub?: boolean } = {}
 ): Promise<void> {
   if (!rootUrl.startsWith("automerge:")) {
     out.error(
@@ -1035,6 +1142,7 @@ export async function root(
 
   const resolvedPath = path.resolve(targetPath);
   const syncToolDir = path.join(resolvedPath, ConfigManager.CONFIG_DIR);
+  const sub = options.sub ?? false;
 
   if (await pathExists(syncToolDir)) {
     if (!options.force) {
@@ -1057,11 +1165,27 @@ export async function root(
   };
   await fs.writeFile(snapshotPath, JSON.stringify(snapshot, null, 2), "utf-8");
 
-  // Ensure config exists
+  // Ensure config exists. In Subduction mode, persist the backend choice
+  // and the correct server so subsequent `sync` runs use the right endpoint.
   const configManager = new ConfigManager(resolvedPath);
-  await configManager.initializeWithOverrides({});
+  if (sub) {
+    let cfg = await configManager.initializeWithOverrides({
+      subduction: true,
+      sync_server: DEFAULT_SUBDUCTION_SERVER,
+    });
+    // Strip dead-baggage storage_id that getDefaultDirectoryConfig seeded.
+    if (cfg.sync_server_storage_id !== undefined) {
+      cfg = { ...cfg, sync_server_storage_id: undefined };
+      await configManager.save(cfg);
+    }
+  } else {
+    await configManager.initializeWithOverrides({});
+  }
 
   out.successBlock("ROOT SET", rootUrl);
+  if (sub) {
+    out.info("Using Subduction sync backend");
+  }
   process.exit();
 }
 

package/src/core/change-detection.ts

@@ -410,7 +410,7 @@ export class ChangeDetector {
 						const remoteContent = await this.getCurrentRemoteContent(entry.url)
 						const remoteHead = await this.getCurrentRemoteHead(entry.url)
 
-						if (localContent && remoteContent) {
+						if (localContent != null && remoteContent == null) {
 							// File exists both locally and remotely but not in snapshot
 							changes.push({
 								path: entryPath,
@@ -643,7 +643,7 @@ export class ChangeDetector {
 	private async getFileTypeFromContent(
 		content: string | Uint8Array | null
 	): Promise<FileType> {
-		if (!content) return FileType.TEXT
+		if (content == null) return FileType.TEXT
 
 		if (content instanceof Uint8Array) {
 			return FileType.BINARY

package/src/core/config.ts

@@ -212,6 +212,10 @@ export class ConfigManager {
       merged.sync_server_storage_id = override.sync_server_storage_id;
     }
 
+    if ("subduction" in override && override.subduction !== undefined) {
+      merged.subduction = override.subduction;
+    }
+
     if ("sync_enabled" in override && override.sync_enabled !== undefined) {
       merged.sync_enabled = override.sync_enabled;
     }

package/src/core/move-detection.ts

@@ -101,7 +101,9 @@ export class MoveDetector {
       typeof content1 === "string" ? content1.length : content1.length;
     const size2 =
       typeof content2 === "string" ? content2.length : content2.length;
-    const sizeDiff = Math.abs(size1 - size2) / Math.max(size1, size2);
+    const maxSize = Math.max(size1, size2);
+    if (maxSize === 0) return 1.0;
+    const sizeDiff = Math.abs(size1 - size2) / maxSize;
     if (sizeDiff > 0.5) return 0.0;
 
     // Binary files: hash mismatch = not a move

package/src/core/sync-engine.ts

@@ -197,16 +197,25 @@ export class SyncEngine {
 
 	/**
 	 * Get the appropriate URL for a subdirectory's directory entry.
-	 * Always uses plain URLs — versioned URLs on directories can cause
-	 * issues where consumers see a version without the docs array.
+	 * Artifact directories get versioned URLs (with heads) so consumers can
+	 * fetch the exact snapshotted version, matching how artifact files work.
+	 * Non-artifact directories get plain URLs for collaborative editing.
 	 */
-	private getDirEntryUrl(handle: DocHandle<unknown>): AutomergeUrl {
+	private getDirEntryUrl(handle: DocHandle<unknown>, dirPath: string): AutomergeUrl {
+		if (this.isArtifactPath(dirPath)) {
+			return this.getVersionedUrl(handle)
+		}
 		return getPlainUrl(handle.url)
 	}
 
 	/**
 	 * Set the root directory URL in the snapshot
 	 */
+	async getRootDirectoryUrl(): Promise<AutomergeUrl | undefined> {
+		const snapshot = await this.snapshotManager.load()
+		return snapshot?.rootDirectoryUrl
+	}
+
 	async setRootDirectoryUrl(url: AutomergeUrl): Promise<void> {
 		let snapshot = await this.snapshotManager.load()
 		if (!snapshot) {
@@ -423,7 +432,7 @@ export class SyncEngine {
 	/**
 	 * Run full bidirectional sync
 	 */
-	async sync(): Promise<SyncResult> {
+	async sync(options?: {sub?: boolean}): Promise<SyncResult> {
 		const result: SyncResult = {
 			success: false,
 			filesChanged: 0,
@@ -482,7 +491,6 @@ export class SyncEngine {
 					await waitForBidirectionalSync(
 						this.repo,
 						snapshot.rootDirectoryUrl,
-						this.config.sync_server_storage_id,
 						{
 							timeoutMs: 5000, // Increased timeout for initial sync
 							pollIntervalMs: 100,
@@ -526,6 +534,12 @@ export class SyncEngine {
 
 			// Wait for network sync (important for clone scenarios)
 			if (this.config.sync_enabled) {
+				const sub = options?.sub ?? false
+				// In Subduction mode, pass no StorageId so waitForSync
+				// falls back to head-stability polling. In WebSocket mode,
+				// pass the StorageId for precise getSyncInfo-based verification.
+				const storageId = sub ? undefined : this.config.sync_server_storage_id
+
 				try {
 					// Ensure root directory handle is tracked for sync
 					if (snapshot.rootDirectoryUrl) {
@@ -546,11 +560,13 @@ export class SyncEngine {
 						out.update(`Uploading ${allHandles.length} documents to sync server`)
 						const {failed} = await waitForSync(
 							allHandles,
-							this.config.sync_server_storage_id
+							storageId
 						)
 
-						// Recreate failed documents and retry once
-						if (failed.length > 0) {
+						// Recreate failed documents and retry once.
+						// Skip in Subduction mode — SubductionSource has its
+						// own heal-sync retry logic.
+						if (failed.length > 0 && !sub) {
 							debug(`sync: ${failed.length} documents failed, recreating`)
 							out.update(`Recreating ${failed.length} failed documents`)
 							const retryHandles = await this.recreateFailedDocuments(failed, snapshot)
@@ -559,7 +575,7 @@ export class SyncEngine {
 								out.update(`Retrying ${retryHandles.length} recreated documents`)
 								const retry = await waitForSync(
 									retryHandles,
-									this.config.sync_server_storage_id
+									storageId
 								)
 								if (retry.failed.length > 0) {
 									const msg = `${retry.failed.length} documents failed to sync to server after recreation`
@@ -572,6 +588,11 @@ export class SyncEngine {
 									})
 								}
 							}
+						} else if (failed.length > 0 && sub) {
+							const msg = `${failed.length} document${failed.length === 1 ? '' : 's'} did not converge during sync (Subduction will retry in the background; re-run sync to confirm)`
+							debug(`sync: ${msg}`)
+							out.taskLine(msg, true)
+							result.warnings.push(msg)
 						}
 
 						debug("sync: all handles synced to server")
@@ -585,7 +606,6 @@ export class SyncEngine {
 					await waitForBidirectionalSync(
 						this.repo,
 						snapshot.rootDirectoryUrl,
-						this.config.sync_server_storage_id,
 						{
 							timeoutMs: BIDIRECTIONAL_SYNC_TIMEOUT_MS,
 							pollIntervalMs: 100,
@@ -608,10 +628,15 @@ export class SyncEngine {
 							)
 						debug("sync: syncing root directory touch to server")
 						out.update("Syncing root directory update")
-						await waitForSync(
+						const rootSync = await waitForSync(
 							[rootHandle],
-							this.config.sync_server_storage_id
+							storageId
 						)
+						if (rootSync.failed.length > 0) {
+							const msg = "Root directory update did not converge to server; consumers may not see recent changes until next sync"
+							debug(`sync: ${msg}`)
+							result.warnings.push(msg)
+						}
 					}
 				} catch (error) {
 					debug(`sync: network sync error: ${error}`)
@@ -938,7 +963,7 @@ export class SyncEngine {
 							)
 						subdirUpdates.push({
 							name: childName,
-							url: this.getDirEntryUrl(childHandle),
+							url: this.getDirEntryUrl(childHandle, modifiedDir),
 						})
 					}
 				}
@@ -1438,7 +1463,7 @@ export class SyncEngine {
 						this.handlesByPath.set(directoryPath, childDirHandle)
 
 						// Get appropriate URL for directory entry
-						const entryUrl = this.getDirEntryUrl(childDirHandle)
+						const entryUrl = this.getDirEntryUrl(childDirHandle, directoryPath)
 
 						// Update snapshot with discovered directory
 						this.snapshotManager.updateDirectoryEntry(snapshot, directoryPath, {
@@ -1469,7 +1494,7 @@ export class SyncEngine {
 		const dirHandle = this.repo.create(dirDoc)
 
 		// Get appropriate URL for directory entry
-		const dirEntryUrl = this.getDirEntryUrl(dirHandle)
+		const dirEntryUrl = this.getDirEntryUrl(dirHandle, directoryPath)
 
 		// Add this directory to its parent
 		// Use plain URL for mutable handle

package/src/types/config.ts

@@ -6,6 +6,7 @@ import { StorageId } from "@automerge/automerge-repo";
 export const DEFAULT_SYNC_SERVER = "wss://sync3.automerge.org";
 export const DEFAULT_SYNC_SERVER_STORAGE_ID =
   "3760df37-a4c6-4f66-9ecd-732039a9385d" as StorageId;
+export const DEFAULT_SUBDUCTION_SERVER = "wss://subduction.sync.inkandswitch.com";
 
 /**
  * Global configuration options
@@ -25,6 +26,7 @@ export interface GlobalConfig {
  */
 export interface DirectoryConfig extends GlobalConfig {
   root_directory_url?: string;
+  subduction?: boolean;
   sync_enabled: boolean;
 }
 
@@ -42,6 +44,7 @@ export interface CloneOptions extends CommandOptions {
   force?: boolean; // Overwrite existing directory
   syncServer?: string; // Custom sync server URL
   syncServerStorageId?: StorageId; // Custom sync server storage ID
+  sub?: boolean;
 }
 
 /**
@@ -83,6 +86,7 @@ export interface CheckoutOptions extends CommandOptions {
 export interface InitOptions extends CommandOptions {
   syncServer?: string;
   syncServerStorageId?: StorageId;
+  sub?: boolean;
 }
 
 /**

package/src/utils/content.ts

@@ -16,7 +16,7 @@ export function isContentEqual(
   content2: string | Uint8Array | null
 ): boolean {
   if (content1 === content2) return true;
-  if (!content1 || !content2) return false;
+  if (content1 == null || content2 == null) return false;
 
   if (typeof content1 !== typeof content2) return false;