@doubling/compound-sync 1.10.5 → 1.12.0

package/README.md

@@ -14,6 +14,16 @@ That's it. A browser window will open for sign-in (Google or email/password), th
 
 - [Node.js](https://nodejs.org/) (v18 or later)
 
+### TLS certificates
+
+On Node 22+ the daemon auto-detects the OS system certificate store (`/etc/ssl/cert.pem` on macOS, `/etc/ssl/certs/ca-certificates.crt` or `/etc/pki/tls/certs/ca-bundle.crt` on Linux) and re-execs itself with `NODE_EXTRA_CA_CERTS` set; otherwise `fetch()` to Google Identity / Firebase Auth endpoints fails with `auth/network-request-failed` because Node's bundled CA store doesn't match what those services use.
+
+If you're behind a corporate proxy with custom roots, set `NODE_EXTRA_CA_CERTS` explicitly to your bundle and the daemon will use that instead:
+
+```bash
+NODE_EXTRA_CA_CERTS=/path/to/corporate-bundle.pem npx @doubling/compound-sync
+```
+
 ## What it does
 
 Compound Sync watches a local folder and your Compound workspace simultaneously. Changes in either direction are synced automatically:
@@ -95,6 +105,19 @@ npm run test:integration
 npm test
 ```
 
+### TypeScript conventions (DOU-181)
+
+`sync/` is being migrated to TypeScript file-by-file. The conventions:
+
+- **Source layout: in-place.** Each `.ts` file emits `.js`, `.d.ts`, and source maps as siblings via `tsc` with `outDir: "."`. The emitted `.js` is a gitignored build artifact, never edited by hand; the `.ts` is the source.
+- **Imports always use the `.js` extension** (NodeNext convention). At runtime: in dev/test the `tsx` loader maps `./paths.js` to `./paths.ts` so source runs without a build step; in production the compiled `paths.js` exists alongside and resolves directly.
+- **Dev (no build needed):** `npm run sync` runs through `node --import tsx`, so `.ts` files load on demand.
+- **CI / publish:** `npm run build` compiles every `.ts` source to its `.js` sibling. `prepack` runs build automatically before `npm publish` so the npm tarball ships compiled JS. The desktop staging script also runs `npm run -w sync build` before copying.
+- **Typecheck:** `npm run typecheck` (alias for `tsc --noEmit`) at the workspace level, or at repo root `npm run typecheck` which runs web + sync together.
+- **Strictness:** `strict: true`, `noUncheckedIndexedAccess: true`, `noImplicitOverride: true`. No `any`. No `// @ts-ignore`. If a third-party module lacks types, declare its shape in a `.d.ts` or PR types upstream.
+
+Phase 1 migrated `paths.js` to `paths.ts` as proof of pattern. Phase 3 ([[DOU-183]]) migrates the remaining source files; everything in `sync/` will be `.ts` by the end.
+
 ### Publishing to npm
 
 After making changes to the sync daemon, publish a new version:

package/files.js

@@ -26,7 +26,7 @@
 //   2. Delete the Firestore metadata document.
 
 import {
-  doc, getDocs, setDoc, updateDoc, deleteDoc, query, where,
+  doc, getDoc, getDocs, setDoc, updateDoc, deleteDoc, query, where,
 } from 'firebase/firestore';
 import {
   ref as storageRef, uploadBytes, deleteObject, getBytes,
@@ -206,18 +206,32 @@ export async function pushFolderToCloud({
 }
 
 /**
- * Delete the folder doc at `docPath` if it exists. Does NOT cascade
- * to children (the sync daemon's `unlinkDir` event fires after its
- * children's `unlink` events have already cleaned up child docs, so
- * by the time we reach the folder it should be empty).
+ * Delete the folder doc at `docPath` AND every descendant (files and
+ * sub-folders) in the same scope. Cascade is authoritative: it does
+ * not rely on per-child `unlink` events to clean up children first.
+ *
+ * Pre-DOU-223 this function deleted only the folder doc, on the
+ * (wrong) assumption that chokidar would emit `unlink` for every
+ * child before the `unlinkDir` for the folder. macOS FSEvents
+ * coalescing and burst-event ordering broke that assumption,
+ * leaving orphan file docs that reconstituted the folder on the web
+ * via `getFoldersAndFiles` (which derives folder names from paths).
+ * The cascade closes the gap; if children's `unlink` events also
+ * fire in time, the cascade is a no-op for them.
+ *
+ * Storage blobs for descendant files are deleted before their
+ * Firestore docs so the Storage rule (which reads the doc to
+ * authorize) still passes.
  *
  * Returns:
  *   { action: 'skipped',   reason: 'shared-scope' }
  *   { action: 'not-found' }
- *   { action: 'deleted',   folderId }
+ *   { action: 'deleted',   folderId, childCount }
  */
 export async function deleteFolderFromCloud({
   filesRef,
+  storage,
+  orgId,
   scope,
   teamId,
   userId,
@@ -226,27 +240,65 @@ export async function deleteFolderFromCloud({
   if (scope === 'shared-with-me' || scope === 'shared-by-me') {
     return { action: 'skipped', reason: 'shared-scope' };
   }
-  let q;
+  // Pull every doc in this scope; cheap because vaults are small
+  // (hundreds of docs at most). Filtering in memory avoids the
+  // Firestore composite-index requirement for a path-prefix range
+  // query and keeps the cascade contract dead simple to reason about.
+  let scopeQuery;
   if (scope === 'private') {
-    q = query(filesRef,
-      where('type', '==', 'folder'),
+    scopeQuery = query(filesRef,
       where('scope', '==', 'private'),
-      where('ownerId', '==', userId),
-      where('path', '==', docPath));
+      where('ownerId', '==', userId));
   } else if (scope === 'team' && teamId) {
-    q = query(filesRef,
-      where('type', '==', 'folder'),
+    scopeQuery = query(filesRef,
       where('scope', '==', 'team'),
-      where('teamId', '==', teamId),
-      where('path', '==', docPath));
+      where('teamId', '==', teamId));
   } else {
     return { action: 'not-found' };
   }
-  const snap = await getDocs(q);
-  if (snap.empty) return { action: 'not-found' };
-  const docSnap = snap.docs[0];
-  await deleteDoc(docSnap.ref);
-  return { action: 'deleted', folderId: docSnap.id };
+  const snap = await getDocs(scopeQuery);
+
+  const prefix = docPath + '/';
+  let folderDocSnap = null;
+  const descendants = [];
+  snap.forEach((d) => {
+    const data = d.data();
+    const p = data.path;
+    if (!p) return;
+    if (data.type === 'folder' && p === docPath) {
+      folderDocSnap = d;
+    } else if (p.startsWith(prefix)) {
+      descendants.push({ id: d.id, ref: d.ref, data });
+    }
+  });
+
+  if (!folderDocSnap && descendants.length === 0) {
+    return { action: 'not-found' };
+  }
+
+  // Delete each descendant's blob (files only) then its doc.
+  for (const { id, ref, data } of descendants) {
+    if (data.type !== 'folder') {
+      const ext = extFromPath(data.path);
+      try {
+        await deleteBlob({ storage, orgId, fileId: id, ext });
+      } catch (err) {
+        // Orphan blob is a soft failure; the doc delete is the
+        // load-bearing state transition for the user's view.
+      }
+    }
+    await deleteDoc(ref);
+  }
+
+  if (folderDocSnap) {
+    await deleteDoc(folderDocSnap.ref);
+  }
+
+  return {
+    action: 'deleted',
+    folderId: folderDocSnap ? folderDocSnap.id : null,
+    childCount: descendants.length,
+  };
 }
 
 // ---- High-level coordinator ----
@@ -291,13 +343,6 @@ export async function pushFileToCloud({
   mimeType,
   now = new Date().toISOString(),
   localModifiedAt = null,
-  // The contentHash this caller saw as "current" when it last pulled.
-  // If the existing remote doc has a different contentHash, another
-  // writer landed an edit in the meantime; we refuse to overwrite and
-  // return action='conflict' so the caller can write a conflict copy
-  // and pull the new remote state. Undefined disables the check (used
-  // for create-from-nothing where no baseline exists).
-  expectedRemoteHash = undefined,
 }) {
   if (scope === 'shared-with-me' || scope === 'shared-by-me') {
     return { action: 'skipped', reason: 'shared-scope' };
@@ -379,23 +424,6 @@ export async function pushFileToCloud({
       && (existing.parentId == null ? null : existing.parentId) === parentId) {
     return { action: 'noop', fileId: docSnap.id };
   }
-  // Compare-and-swap (DOU-167): if the caller passed a baseline of
-  // what they last saw as current, refuse the push when the remote
-  // has moved on. The daemon will write the proposed local content
-  // to a sibling conflict file and pull the new remote state into
-  // the live path. Without this guard, a stale push silently
-  // overwrites another user's freshly-saved edits (data loss).
-  if (
-    expectedRemoteHash !== undefined &&
-    existing.contentHash !== expectedRemoteHash
-  ) {
-    return {
-      action: 'conflict',
-      fileId: docSnap.id,
-      remoteHash: existing.contentHash,
-      remoteData: { id: docSnap.id, ...existing },
-    };
-  }
   // Last-write-wins: never let an older local file overwrite a newer
   // server edit. The caller (sync daemon) passes the local file's mtime;
   // if the server doc was updated more recently, leave it for the
@@ -473,7 +501,29 @@ export async function deleteFileFromCloud({
   const ext = extFromPath(docPath);
   // Delete the Storage blob FIRST while the metadata doc still exists,
   // because the Storage rule's authorization check looks up the doc.
-  await deleteBlob({ storage, orgId, fileId, ext });
+  //
+  // Race tolerance (DOU-231 follow-up): a concurrent delete can remove
+  // the metadata doc between our snapshot read and our blob-delete
+  // (most commonly the cascade in deleteFolderFromCloud firing first
+  // for a path chokidar's per-file `unlink` event then re-tries via
+  // this function). After that delete, the Storage rule's
+  // `firestore.get(...).data.scope` reads null, the rule throws
+  // "Null value error", and the Storage SDK surfaces it as
+  // `storage/unauthorized`. In that specific case the desired end
+  // state (no doc, no blob) is already achieved, so treat as
+  // already-deleted instead of propagating a noisy auth error.
+  try {
+    await deleteBlob({ storage, orgId, fileId, ext });
+  } catch (err) {
+    const code = err && err.code;
+    if (code === 'storage/unauthorized') {
+      const recheck = await getDoc(docSnap.ref);
+      if (!recheck.exists()) {
+        return { action: 'not-found', fileId };
+      }
+    }
+    throw err;
+  }
   await deleteDoc(docSnap.ref);
   return { action: 'deleted', fileId };
 }