pushwork 1.1.3 → 2.0.0-a.sub.0

package/CLAUDE.md

@@ -103,20 +103,24 @@ Stored in `.pushwork/config.json` (local) and `~/.pushwork/config.json` (global)
 
 Key fields:
 - `sync_enabled: boolean` - Whether to do network sync
-- `sync_server: string` - WebSocket relay URL (default: `wss://sync3.automerge.org`)
-- `sync_server_storage_id: StorageId` - Server identity for sync verification
+- `sync_server: string` - WebSocket relay URL (default: `wss://subduction.sync.inkandswitch.com`)
 - `exclude_patterns: string[]` - Gitignore-style patterns (default: `.git`, `node_modules`, `*.tmp`, `.pushwork`, `.DS_Store`)
 - `sync.move_detection_threshold: number` - Similarity threshold for move detection (0-1, default 0.7)
 
-## Network sync details
+## Network sync details (Subduction)
 
-- Uses `waitForSync()` to verify documents reach the server by comparing local and remote heads
+Pushwork uses Subduction for network sync. Subduction replaces the old `BrowserWebSocketClientAdapter` with a Subduction transport layer that handles sync automatically.
+
+- **Repo setup** (`src/utils/repo-factory.ts`): Creates a `WebCryptoSigner`, wraps `NodeFSStorageAdapter` in `SubductionStorageBridge`, hydrates `Subduction`, and calls `connectDiscover()` to the sync server. The `Repo` receives `{ subduction, storage }` instead of `{ storage, network }`.
+- **Sync verification**: Uses head-stability polling instead of `StorageId`-based `getSyncInfo()`. Both `waitForSync()` and `waitForBidirectionalSync()` poll document heads until they stabilize.
+- Uses `waitForSync()` to verify documents reach the server by polling head stability
 - Uses `waitForBidirectionalSync()` to poll until document heads stabilize (no more incoming changes)
   - Accepts optional `handles` param to check only specific handles instead of full tree traversal (used post-push in `sync()`)
   - Timeout scales dynamically: `max(timeoutMs, 5000 + docCount * 50)` so large trees don't prematurely time out
   - Tree traversal (`collectHeadsRecursive`) fetches siblings concurrently via `Promise.all`
 - Documents sync level-by-level, deepest first, so children are on the server before their parents
 - `handlesByPath` map tracks which documents changed and need syncing
+- Default sync server: `wss://subduction.sync.inkandswitch.com`
 
 ## Leaf-first ordering
 
@@ -132,6 +136,6 @@ Used throughout sync-engine: if heads are available, calls `handle.changeAt(head
 - **Avoid diffing artifact files.** `diffChars()` is O(n*m) and pointless for artifact directories since they use RawString (immutable snapshots). Artifact files should always be replaced with a fresh document rather than diffed+spliced. This applies to `updateRemoteFile()`, `applyMoveToRemote()`, and change detection. `ChangeDetector` skips `getContentAtHead()` and `getCurrentRemoteContent()` for artifact paths — it uses a SHA-256 `contentHash` stored in the snapshot to detect local changes, and checks heads to detect remote changes. If neither changed, the artifact is skipped entirely. The `contentHash` field on `SnapshotFileEntry` is optional and only populated for artifact files.
 - **Sync timeout recovery.** `waitForSync()` returns `{ failed: DocHandle[] }` instead of throwing. When documents fail to sync (timeout or unavailable), `recreateFailedDocuments()` creates new Automerge docs with the same content, updates snapshot entries and parent directory references, then retries once. If documents still fail after recreation, it's reported as an error (not a warning) so the sync shows as "PARTIAL" rather than "SYNCED".
 - **Document availability during clone.** `repo.find()` rejects with "Document X is unavailable" if the sync server doesn't have the document yet. `DocHandle.doc()` is synchronous and throws if the handle isn't ready. For clone scenarios, `sync()` retries `repo.find()` for the root document with exponential backoff (up to 6 attempts). `ChangeDetector.findDocument()` wraps `repo.find()` + `doc()` with retry logic for all document fetches during change detection.
-- **Server load.** `enableRemoteHeadsGossiping` is disabled — pushwork syncs directly with the server so the gossip protocol is unnecessary overhead. `waitForSync` processes documents in batches of 10 (`SYNC_BATCH_SIZE`) to avoid flooding the server with concurrent sync messages. Without batching, syncing 100+ documents simultaneously can overwhelm the sync server (which is single-threaded with no backpressure).
+- **Server load.** `waitForSync` processes documents in batches of 10 (`SYNC_BATCH_SIZE`) to avoid flooding the server with concurrent sync messages. Without batching, syncing 100+ documents simultaneously can overwhelm the sync server.
 - **`waitForBidirectionalSync` on large trees.** Full tree traversal (`getAllDocumentHeads`) is expensive because it `repo.find()`s every document. For post-push stabilization, pass the `handles` option to only check documents that actually changed. The initial pre-pull call still needs the full scan to discover remote changes. The dynamic timeout adds the first scan's duration on top of the base timeout, since the first scan is just establishing baseline — its duration shouldn't count against stability-wait time.
 - **Versioned URLs and `repo.find()`.** `repo.find(versionedUrl)` returns a view handle whose `.heads()` returns the VERSION heads, not the current document heads. Always use `getPlainUrl()` when you need the current/mutable state. The snapshot head update loop at the end of `sync()` must use `getPlainUrl(snapshotEntry.url)` — without this, artifact directories (which store versioned URLs) get stale heads written to the snapshot, causing `changeAt()` to fork from the wrong point on the next sync. This was the root cause of the artifact deletion resurrection bug: `batchUpdateDirectory` would `changeAt` from an empty directory state where the file entry didn't exist yet, so the splice found nothing to delete.

package/dist/cli/commands.d.ts

@@ -0,0 +1,71 @@
+import { Repo } from "@automerge/automerge-repo";
+import { CloneOptions, SyncOptions, DiffOptions, LogOptions, CheckoutOptions, DirectoryConfig } from "../types";
+import { SyncEngine } from "../core";
+/**
+ * Shared context that commands can use
+ */
+export interface CommandContext {
+    repo: Repo;
+    syncEngine: SyncEngine;
+    config: DirectoryConfig;
+    workingDir: string;
+}
+/**
+ * Shared pre-action that ensures repository and sync engine are properly initialized
+ * This function always works, with or without network connectivity
+ */
+export declare function setupCommandContext(workingDir?: string, customSyncServer?: string, customStorageId?: string, enableNetwork?: boolean): Promise<CommandContext>;
+/**
+ * Safely shutdown a repository with proper error handling
+ */
+export declare function safeRepoShutdown(repo: Repo, context?: string): Promise<void>;
+/**
+ * Common progress message helpers
+ */
+export declare const ProgressMessages: {
+    directoryFound: () => void;
+    configLoaded: () => void;
+    repoConnected: () => void;
+    syncServer: (server: string) => void;
+    storageId: (id: string) => void;
+    rootUrl: (url: string) => void;
+    changesWritten: () => void;
+    syncCompleted: (duration: number) => void;
+    directoryStructureCreated: () => void;
+    configSaved: () => void;
+    repoCreated: () => void;
+};
+/**
+ * Initialize sync in a directory
+ */
+export declare function init(targetPath: string, syncServer?: string, syncServerStorageId?: string): Promise<void>;
+/**
+ * Run bidirectional sync
+ */
+export declare function sync(options: SyncOptions): Promise<void>;
+/**
+ * Show differences between local and remote
+ */
+export declare function diff(targetPath: string | undefined, options: DiffOptions): Promise<void>;
+/**
+ * Show sync status
+ */
+export declare function status(): Promise<void>;
+/**
+ * Show sync history
+ */
+export declare function log(targetPath: string | undefined, options: LogOptions): Promise<void>;
+/**
+ * Checkout/restore from previous sync
+ */
+export declare function checkout(syncId: string, targetPath: string | undefined, options: CheckoutOptions): Promise<void>;
+/**
+ * Clone an existing synced directory from an AutomergeUrl
+ */
+export declare function clone(rootUrl: string, targetPath: string, options: CloneOptions): Promise<void>;
+/**
+ * Get the root URL for the current pushwork repository
+ */
+export declare function url(targetPath?: string): Promise<void>;
+export declare function commit(targetPath: string, dryRun?: boolean): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/cli/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAA2B,MAAM,2BAA2B,CAAC;AAI1E,OAAO,EAEL,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,eAAe,EAEhB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAMrC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,GAAE,MAAsB,EAClC,gBAAgB,CAAC,EAAE,MAAM,EACzB,eAAe,CAAC,EAAE,MAAM,EACxB,aAAa,GAAE,OAAc,GAC5B,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;yBAON,MAAM;oBAEX,MAAM;mBACP,MAAM;;8BAKK,MAAM;;;;CAOjC,CAAC;AA+DF;;GAEG;AACH,wBAAsB,IAAI,CACxB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,EACnB,mBAAmB,CAAC,EAAE,MAAM,GAC3B,OAAO,CAAC,IAAI,CAAC,CA6Hf;AAED;;GAEG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgM9D;AAED;;GAEG;AACH,wBAAsB,IAAI,CACxB,UAAU,oBAAM,EAChB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CA6Df;AAED;;GAEG;AACH,wBAAsB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CA6H5C;AAED;;GAEG;AACH,wBAAsB,GAAG,CACvB,UAAU,oBAAM,EAChB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,IAAI,CAAC,CA2Cf;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,oBAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;GAEG;AACH,wBAAsB,KAAK,CACzB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,IAAI,CAAC,CA6Hf;AAED;;GAEG;AACH,wBAAsB,GAAG,CAAC,UAAU,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCzD;AAED,wBAAsB,MAAM,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,OAAe,GACtB,OAAO,CAAC,IAAI,CAAC,CAgEf"}