@wspc/cli 0.1.14 → 0.1.15

package/dist/cli.js

@@ -1520,9 +1520,9 @@ function createConsistencyFetch(opts) {
 }
 
 // src/version.ts
-var VERSION = "0.1.14";
+var VERSION = "0.1.15";
 var SPEC_SHA = "bec760cd";
-var SPEC_FETCHED_AT = "2026-07-08T06:11:14.456Z";
+var SPEC_FETCHED_AT = "2026-07-13T04:21:22.596Z";
 var API_BASE = "https://api.wspc.ai";
 
 // src/index.ts
@@ -4851,6 +4851,7 @@ async function expectJsonResult(result) {
   if (result.data == null) throw new Error("empty response");
   return result.data;
 }
+var SYNC_CLIENT_HEADERS = { "x-wspc-client": "drive-sync" };
 function driveContentUrl(baseUrl, id) {
   const baseWithTrailingSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
   return new URL(`drive/libraries/${encodeURIComponent(id)}/files/content`, baseWithTrailingSlash);
@@ -4878,6 +4879,7 @@ async function createDriveApi(opts = {}) {
       const result = await driveFileDelete({
         client: rawClient,
         path: { id },
+        headers: SYNC_CLIENT_HEADERS,
         body: {
           path,
           expected_entry_version: expectedEntryVersion
@@ -4895,7 +4897,8 @@ async function createDriveApi(opts = {}) {
         method: "PUT",
         headers: {
           "content-type": "application/octet-stream",
-          "x-drive-content-sha256": sha256
+          "x-drive-content-sha256": sha256,
+          ...SYNC_CLIENT_HEADERS
         },
         body
       });
@@ -5155,9 +5158,44 @@ function driveBindCommand() {
 // src/handwritten/commands/drive/sync.ts
 import { Command as Command80 } from "commander";
 import { mkdir as mkdir3, readFile as readFile4, rm as rm3, writeFile as writeFile3 } from "fs/promises";
-import { basename as basename3, dirname as dirname2, join as join5, posix as pathPosix2, resolve as resolve3 } from "path";
+import { basename as basename3, dirname as dirname2, join as join6, posix as pathPosix2, resolve as resolve3 } from "path";
 import { createHash as createHash3, randomUUID as randomUUID4 } from "crypto";
 
+// src/handwritten/commands/drive/debug-log.ts
+import { appendFileSync, mkdirSync, renameSync, statSync } from "fs";
+import { join as join3 } from "path";
+var noopDriveDebugLogger = { log() {
+} };
+var DEBUG_LOG_FILE = "debug.log";
+var MAX_DEBUG_LOG_BYTES = 10 * 1024 * 1024;
+function createDriveDebugLogger(root, options = {}) {
+  const clock = options.clock ?? systemDriveClock;
+  const maxBytes = options.maxBytes ?? MAX_DEBUG_LOG_BYTES;
+  const dir = join3(root, DRIVE_DIR);
+  const file = join3(dir, DEBUG_LOG_FILE);
+  let warned = false;
+  return {
+    log(event, fields = {}) {
+      try {
+        mkdirSync(dir, { recursive: true });
+        try {
+          if (statSync(file).size > maxBytes) renameSync(file, `${file}.old`);
+        } catch {
+        }
+        appendFileSync(file, `${JSON.stringify({ ts: driveIsoTimestamp(clock), event, ...fields })}
+`);
+      } catch (error) {
+        if (!warned) {
+          warned = true;
+          const message = error instanceof Error ? error.message : String(error);
+          process.stderr.write(`wspc drive: debug log write failed: ${message}
+`);
+        }
+      }
+    }
+  };
+}
+
 // src/handwritten/commands/drive/decision.ts
 function decideDriveAction(entry, local, remote) {
   if (!entry) return decideWithoutBase(local, remote);
@@ -5417,7 +5455,7 @@ function safeShortVersionId(versionId) {
 import { createHash } from "crypto";
 import { constants as fsConstants } from "fs";
 import { open as open2, readdir, lstat } from "fs/promises";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 async function scanDriveFiles(root, options = {}) {
   const candidates = [];
   const files = {};
@@ -5443,7 +5481,7 @@ async function scanDriveFiles(root, options = {}) {
         await options.onPathError(nextDrivePath, error);
         continue;
       }
-      const nextPath = join3(currentPath, entry.name);
+      const nextPath = join4(currentPath, entry.name);
       const stats = await lstat(nextPath);
       if (stats.isSymbolicLink()) {
         continue;
@@ -5536,7 +5574,7 @@ async function hashDriveFile(path) {
 // src/handwritten/commands/drive/local-mutations.ts
 import { createWriteStream as createWriteStream2 } from "fs";
 import { link, mkdir as mkdir2, readFile as readFile3, rename as rename2, rm as rm2, unlink, writeFile as writeFile2 } from "fs/promises";
-import { basename as basename2, dirname, join as join4 } from "path";
+import { basename as basename2, dirname, join as join5 } from "path";
 import { createHash as createHash2, randomUUID as randomUUID3 } from "crypto";
 import { Readable as Readable2, Transform } from "stream";
 import { pipeline as pipeline2 } from "stream/promises";
@@ -5552,7 +5590,7 @@ async function assertLocalStillScanned(localPath, scanned) {
 async function writeMergedLocalFile(root, path, bytes, digest, scanned, onLocalMutation) {
   const target = resolveInsideRoot(root, path);
   await mkdir2(dirname(target), { recursive: true });
-  const tmp = join4(dirname(target), `.${basename2(target)}.wspc-merge-${randomUUID3()}.tmp`);
+  const tmp = join5(dirname(target), `.${basename2(target)}.wspc-merge-${randomUUID3()}.tmp`);
   try {
     await writeFile2(tmp, bytes, { flag: "wx" });
     return await installMergedLocalFile(root, path, tmp, scanned, digest, bytes.byteLength, onLocalMutation);
@@ -5604,7 +5642,7 @@ async function installMergedLocalFile(root, path, tmp, scanned, mergedSha256, me
   }
 }
 async function restoreMergedLocalFile(target, backup, backupSha256, backupSizeBytes, mergedSha256, mergedSizeBytes) {
-  const quarantine = join4(dirname(target), `.${basename2(target)}.wspc-merge-restore-${randomUUID3()}.tmp`);
+  const quarantine = join5(dirname(target), `.${basename2(target)}.wspc-merge-restore-${randomUUID3()}.tmp`);
   try {
     await rename2(target, quarantine);
   } catch (error) {
@@ -5634,7 +5672,7 @@ async function restoreMergedLocalFile(target, backup, backupSha256, backupSizeBy
 async function downloadRemote(root, libraryId, path, api, expectedSha256, entry, onLocalMutation) {
   const target = resolveInsideRoot(root, path);
   await mkdir2(dirname(target), { recursive: true });
-  const tmp = join4(dirname(target), `.${basename2(target)}.wspc-download-${randomUUID3()}.tmp`);
+  const tmp = join5(dirname(target), `.${basename2(target)}.wspc-download-${randomUUID3()}.tmp`);
   try {
     const response = await api.downloadFile(libraryId, path);
     if (!response.body) {
@@ -5768,7 +5806,7 @@ async function localFileExists(path) {
   return digest !== void 0;
 }
 function localMutationBackupPath(target) {
-  return join4(dirname(target), `.${basename2(target)}.wspc-backup-${randomUUID3()}.tmp`);
+  return join5(dirname(target), `.${basename2(target)}.wspc-backup-${randomUUID3()}.tmp`);
 }
 function expectedLocalBaseSha256(entry) {
   return entry?.last_local_sha256 ?? entry?.content_sha256;
@@ -5846,18 +5884,22 @@ function emptySummary() {
 function isActionableAction(action) {
   return action.type !== "unchanged" && action.type !== "state_only" && action.type !== "remove_state";
 }
-async function runDriveSyncOnce(root, api, clock = systemDriveClock, onProgress) {
+async function runDriveSyncOnce(root, api, clock = systemDriveClock, onProgress, debug = noopDriveDebugLogger) {
   return withDriveLock(root, async () => {
     let state = await readDriveState(root);
     const syncApi = api ?? await createDriveApi();
     const summary = emptySummary();
     const blockedPaths = /* @__PURE__ */ new Set();
+    const scanStartedMs = Date.now();
     const localFiles = await scanDriveFiles(root, {
       onPathError: async (path, error) => {
         await recordPathError(summary, blockedPaths, path, error);
       }
     });
+    const scanMs = Date.now() - scanStartedMs;
+    const manifestStartedMs = Date.now();
     const remoteFiles = await fetchRemoteManifest(root, state, syncApi, summary, blockedPaths);
+    const manifestMs = Date.now() - manifestStartedMs;
     const paths = Array.from(
       /* @__PURE__ */ new Set([...Object.keys(localFiles), ...Object.keys(remoteFiles), ...Object.keys(state.entries)])
     ).filter((path) => !blockedPaths.has(path)).sort((left, right) => left.localeCompare(right));
@@ -5866,11 +5908,27 @@ async function runDriveSyncOnce(root, api, clock = systemDriveClock, onProgress)
     ).length;
     let processed = 0;
     onProgress?.(processed, total);
+    const processStartedMs = Date.now();
     for (const path of paths) {
       const remote = remoteFiles[path];
-      const action = decideDriveAction(state.entries[path], localFiles[path], remote);
-      const result = await processPath({ root, state, api: syncApi, path, action, remote, local: localFiles[path], summary, clock });
+      const local = localFiles[path];
+      const action = decideDriveAction(state.entries[path], local, remote);
+      if (isActionableAction(action)) {
+        debug.log("decision", decisionFields(path, action, state.entries[path], local, remote));
+      }
+      const previousConflict = state.conflicts[path];
+      const result = await processPath({ root, state, api: syncApi, path, action, remote, local, summary, clock });
       state = result.state;
+      const recordedConflict = state.conflicts[path];
+      if (recordedConflict !== void 0 && recordedConflict !== previousConflict) {
+        debug.log("conflict", {
+          path,
+          reason: recordedConflict.reason,
+          ...recordedConflict.type === void 0 ? {} : { type: recordedConflict.type },
+          ...recordedConflict.strategy === void 0 ? {} : { strategy: recordedConflict.strategy },
+          ...recordedConflict.conflict_paths === void 0 ? {} : { conflict_paths: recordedConflict.conflict_paths }
+        });
+      }
       if (isActionableAction(action)) {
         processed += 1;
         onProgress?.(processed, total);
@@ -5878,9 +5936,20 @@ async function runDriveSyncOnce(root, api, clock = systemDriveClock, onProgress)
       if (result.stop) break;
     }
     recordUnresolvedConflicts(summary, state);
+    debug.log("sync_phases", { scan_ms: scanMs, manifest_ms: manifestMs, process_ms: Date.now() - processStartedMs });
     return summary;
   });
 }
+function decisionFields(path, action, entry, local, remote) {
+  return {
+    path,
+    action: action.type,
+    ..."reason" in action && action.reason !== void 0 ? { reason: action.reason } : {},
+    ...entry === void 0 ? {} : { base_version_id: entry.current_version_id, base_entry_version: entry.entry_version, base_sha256: entry.content_sha256 },
+    ...local === void 0 ? {} : { local_sha256: local.sha256, local_size_bytes: local.size_bytes },
+    ...remote === void 0 ? {} : { remote_version_id: remote.current_version_id, remote_entry_version: remote.entry_version, remote_sha256: remote.content_sha256 }
+  };
+}
 function driveSyncCommand(api) {
   const sync = new Command80("sync").description("Drive sync commands");
   sync.command("once").description("Run one Drive sync pass").argument("[path]", "local folder path", ".").action(async (path) => {
@@ -6194,7 +6263,7 @@ async function writeConflictCopy(root, path, side, versionId, bytes, clock) {
     const target = resolveInsideRoot(root, candidate);
     await mkdir3(dirname2(target), { recursive: true });
     for (; ; ) {
-      const tmp = join5(dirname2(target), `.${basename3(target)}.wspc-conflict-${randomUUID4()}.tmp`);
+      const tmp = join6(dirname2(target), `.${basename3(target)}.wspc-conflict-${randomUUID4()}.tmp`);
       let tmpWritten = false;
       try {
         await writeFile3(tmp, bytes, { flag: "wx" });
@@ -6636,7 +6705,8 @@ function webSocketError(event) {
 
 // src/handwritten/commands/drive/watch.ts
 async function runDriveWatch(root, options = {}) {
-  const runSync = options.runSync ?? ((syncRoot, onProgress) => runDriveSyncOnce(syncRoot, void 0, void 0, onProgress));
+  const dbg = options.debugLogger ?? (options.debug ? createDriveDebugLogger(root) : noopDriveDebugLogger);
+  const runSync = options.runSync ?? ((syncRoot, onProgress) => runDriveSyncOnce(syncRoot, void 0, void 0, onProgress, dbg));
   const debounceMs = options.debounceMs ?? 500;
   const remoteDebounceMs = options.remoteDebounceMs ?? 2e3;
   const emit = options.onEvent ?? ((event) => {
@@ -6647,6 +6717,7 @@ async function runDriveWatch(root, options = {}) {
     }
     render({ kind: "drive_watch", display: { shape: "object" } }, event);
   });
+  let nextTrigger = "initial";
   let debounceTimer;
   let debounceDeadlineMs;
   let retryTimer;
@@ -6671,14 +6742,28 @@ async function runDriveWatch(root, options = {}) {
         rerunRequested = false;
         try {
           emit({ kind: "drive_sync_start" });
+          dbg.log("sync_start", { trigger: nextTrigger });
+          const startedAtMs = Date.now();
           const summary = await runSync(root, (processed, total) => {
             emit({ kind: "drive_sync_progress", processed, total });
           });
           emit({ kind: "drive_sync_once", ...summary });
+          dbg.log("sync_end", {
+            duration_ms: Date.now() - startedAtMs,
+            uploaded: summary.uploaded,
+            downloaded: summary.downloaded,
+            deleted: summary.deleted,
+            merged: summary.merged,
+            unchanged: summary.unchanged,
+            conflicts: summary.conflicts,
+            errors: summary.errors
+          });
           backoffMs = 1e3;
         } catch (error) {
           if (isAuthError(error) || isFatalWatchError(error) || !isRetryableWatchError(error)) throw error;
           emit({ kind: "drive_watch_retry", delay_ms: backoffMs, error: errorMessage2(error) });
+          dbg.log("retry", { delay_ms: backoffMs, error: errorMessage2(error) });
+          nextTrigger = "retry";
           if (stopped) return;
           await waitForManagedTimer(backoffMs);
           if (stopped) return;
@@ -6696,7 +6781,8 @@ async function runDriveWatch(root, options = {}) {
     debounceTimer = void 0;
     debounceDeadlineMs = void 0;
   }
-  function scheduleSync(delayMs) {
+  function scheduleSync(delayMs, trigger) {
+    nextTrigger = trigger;
     if (running) {
       rerunRequested = true;
       return;
@@ -6767,7 +6853,8 @@ async function runDriveWatch(root, options = {}) {
     source = options.source ?? createDefaultWatchSource(root);
     source.onChange((path) => {
       if (isDriveInternalPath(root, path)) return;
-      scheduleSync(debounceMs);
+      dbg.log("fs_event", { path: relative2(root, path) });
+      scheduleSync(debounceMs, "local");
     });
     emit({ kind: "drive_watch_started", root, library_id: state.library_id });
     realtimeSource?.start({
@@ -6776,11 +6863,12 @@ async function runDriveWatch(root, options = {}) {
       },
       onEvent(event) {
         emit(realtimeEvent(event));
+        dbg.log("realtime_event", { ...event });
         if (event.immediate) {
-          scheduleSync(0);
+          scheduleSync(0, "remote");
           return;
         }
-        scheduleSync(event.debounce_ms ?? remoteDebounceMs);
+        scheduleSync(event.debounce_ms ?? remoteDebounceMs, "remote");
       },
       onReconnect(delayMs, error) {
         emit({ kind: "drive_realtime_reconnecting", delay_ms: delayMs, error });
@@ -6809,8 +6897,9 @@ async function runDriveWatch(root, options = {}) {
   }
 }
 function driveWatchCommand(options = {}) {
-  return new Command81("watch").description("Watch a bound Drive folder and sync local changes").argument("[path]", "local folder path", ".").action(async (path) => {
-    await runDriveWatch(resolve4(path), options);
+  return new Command81("watch").description("Watch a bound Drive folder and sync local changes").argument("[path]", "local folder path", ".").option("--debug", "append debug NDJSON events to <folder>/.wspc-drive/debug.log").action(async (path, flags) => {
+    const debug = options.debug ?? (flags.debug === true || process.env.WSPC_DRIVE_DEBUG === "1");
+    await runDriveWatch(resolve4(path), { ...options, debug });
   });
 }
 function createDefaultWatchSource(root) {