@doubling/compound-sync 1.12.3 → 1.12.5

package/README.md

@@ -42,6 +42,19 @@ Compound Sync watches a local folder and your Compound workspace simultaneously.
   Shared with Me/          -- files shared with you (read-only)
 ```
 
+## Hidden sync metadata
+
+The daemon maintains per-machine state under your sync folder (dotfiles and
+directories, not uploaded to Compound):
+
+| Path | Purpose |
+| ---- | ------- |
+| `.compound-sync/manifest.json` | Maps synced paths to Firestore file IDs (startup reconcile) |
+| `.compound-sync-state.json` | Content-hash baseline for push/pull decisions |
+| `.compound-yjs-binding/` | Offline Yjs merge state per file |
+
+Do not edit these by hand. See [docs/features/sync/local-metadata.md](../docs/features/sync/local-metadata.md).
+
 ## Running
 
 After setup, start syncing with:
@@ -116,6 +129,10 @@ npm test
 - **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.
 
+### Logging convention
+
+Org-scoped output: `  [${orgId}] [tag] message`. Use `console.warn` for recoverable issues, `console.error` for failures. Tags like `[local scan]` and `[manifest reconcile]` identify subsystems.
+
 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

package/auth-persistence.d.ts

@@ -0,0 +1,22 @@
+export interface ResolveAuthFilePathInput {
+    authFileEnv?: string | null | undefined;
+    homeDir: string;
+    projectId?: string | undefined;
+    accountKey?: string | undefined;
+}
+export interface FilePersistenceClass {
+    new (): {
+        type: 'LOCAL';
+        _isAvailable(): Promise<boolean>;
+        _set(key: string, value: unknown): Promise<void>;
+        _get(key: string): Promise<unknown>;
+        _remove(key: string): Promise<void>;
+        _addListener(key: string, listener: unknown): void;
+        _removeListener(key: string, listener: unknown): void;
+    };
+    type: 'LOCAL';
+    unfreeze(): void;
+}
+export declare function resolveAuthFilePath({ authFileEnv, homeDir, projectId, accountKey, }: ResolveAuthFilePathInput): string;
+export declare function makeFilePersistence(filePath: string): FilePersistenceClass;
+//# sourceMappingURL=auth-persistence.d.ts.map

package/auth-persistence.js

@@ -14,98 +14,94 @@
 // desktop app give each account its own credentials file.
 //
 // Security: the file holds a refresh token, so it's written 0600.
-
 import fs from 'node:fs';
 import path from 'node:path';
-
 // Where to store an account's persisted auth. The desktop app passes
 // an explicit per-account path via the COMPOUND_AUTH_FILE env var
 // (each account gets its own file). The CLI falls back to a stable
 // per-(project, account) path under the user's config dir, keyed by
 // email (or orgId) so two accounts on the same project don't collide.
-export function resolveAuthFilePath({ authFileEnv, homeDir, projectId, accountKey }) {
-  if (authFileEnv) return authFileEnv;
-  const safeAccount = String(accountKey || 'default').replace(/[^a-zA-Z0-9._@-]/g, '_');
-  const safeProject = String(projectId || 'default').replace(/[^a-zA-Z0-9._-]/g, '_');
-  return path.join(homeDir, '.config', 'compound-sync', `${safeProject}__${safeAccount}.json`);
+export function resolveAuthFilePath({ authFileEnv, homeDir, projectId, accountKey, }) {
+    if (authFileEnv)
+        return authFileEnv;
+    const safeAccount = String(accountKey || 'default').replace(/[^a-zA-Z0-9._@-]/g, '_');
+    const safeProject = String(projectId || 'default').replace(/[^a-zA-Z0-9._-]/g, '_');
+    return path.join(homeDir, '.config', 'compound-sync', `${safeProject}__${safeAccount}.json`);
 }
-
 export function makeFilePersistence(filePath) {
-  // Freeze guard: starts true. During daemon startup the Firebase Auth
-  // SDK validates the cached refresh token against the backend. With
-  // App Check enforcement on Authentication enabled, that validation
-  // request lacks an App Check header (App Check is initialized after
-  // authStateReady today), the backend rejects, and the SDK calls
-  // _remove(userKey) on our persistence, wiping credentials. While
-  // frozen, _remove is a no-op. The daemon calls FilePersistence.unfreeze()
-  // after authStateReady resolves, restoring normal sign-out behavior.
-  // Per factory call (per account): unfreezing one account's persistence
-  // must not unfreeze another's.
-  let frozen = true;
-
-  function readStore() {
-    try {
-      return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-    } catch {
-      // Missing or unreadable file: start from an empty store.
-      return {};
+    // Freeze guard: starts true. During daemon startup the Firebase Auth
+    // SDK validates the cached refresh token against the backend. With
+    // App Check enforcement on Authentication enabled, that validation
+    // request lacks an App Check header (App Check is initialized after
+    // authStateReady today), the backend rejects, and the SDK calls
+    // _remove(userKey) on our persistence, wiping credentials. While
+    // frozen, _remove is a no-op. The daemon calls FilePersistence.unfreeze()
+    // after authStateReady resolves, restoring normal sign-out behavior.
+    // Per factory call (per account): unfreezing one account's persistence
+    // must not unfreeze another's.
+    let frozen = true;
+    function readStore() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return {};
+        }
+        catch {
+            // Missing or unreadable file: start from an empty store.
+            return {};
+        }
     }
-  }
-
-  function writeStore(store) {
-    // Atomic write: temp file + rename. fs.writeFileSync is not atomic,
-    // so a crash or kill mid-write would truncate the credentials file
-    // and the next launch would read it as an empty store (parse fail
-    // = {}), forcing a browser popup. rename(2) on the same filesystem
-    // is atomic, so on-disk state is always either the prior valid
-    // JSON or the new valid JSON.
-    const dir = path.dirname(filePath);
-    fs.mkdirSync(dir, { recursive: true });
-    const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
-    fs.writeFileSync(tmp, JSON.stringify(store), { mode: 0o600 });
-    fs.renameSync(tmp, filePath);
-  }
-
-  return class FilePersistence {
-    // Read by the SDK both as a static and as an instance property in
-    // different code paths; set both. 'LOCAL' = survives restarts.
-    static type = 'LOCAL';
-    type = 'LOCAL';
-
-    // Called by the daemon once auth restore is past the validation
-    // window (after authStateReady). Sign-out _remove calls after this
-    // point are honored normally.
-    static unfreeze() {
-      frozen = false;
+    function writeStore(store) {
+        // Atomic write: temp file + rename. fs.writeFileSync is not atomic,
+        // so a crash or kill mid-write would truncate the credentials file
+        // and the next launch would read it as an empty store (parse fail
+        // = {}), forcing a browser popup. rename(2) on the same filesystem
+        // is atomic, so on-disk state is always either the prior valid
+        // JSON or the new valid JSON.
+        const dir = path.dirname(filePath);
+        fs.mkdirSync(dir, { recursive: true });
+        const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(store), { mode: 0o600 });
+        fs.renameSync(tmp, filePath);
     }
-
-    async _isAvailable() {
-      return true;
-    }
-
-    async _set(key, value) {
-      const store = readStore();
-      store[key] = value;
-      writeStore(store);
-    }
-
-    async _get(key) {
-      const store = readStore();
-      return Object.prototype.hasOwnProperty.call(store, key) ? store[key] : null;
-    }
-
-    async _remove(key) {
-      // See the freeze comment above the closure. During init we keep
-      // the cached credential rather than letting the SDK's startup
-      // validation wipe it.
-      if (frozen) return;
-      const store = readStore();
-      delete store[key];
-      writeStore(store);
-    }
-
-    // Cross-tab change listeners are a browser concern; no-ops in Node.
-    _addListener(_key, _listener) {}
-    _removeListener(_key, _listener) {}
-  };
+    return class FilePersistence {
+        // Read by the SDK both as a static and as an instance property in
+        // different code paths; set both. 'LOCAL' = survives restarts.
+        static type = 'LOCAL';
+        type = 'LOCAL';
+        // Called by the daemon once auth restore is past the validation
+        // window (after authStateReady). Sign-out _remove calls after this
+        // point are honored normally.
+        static unfreeze() {
+            frozen = false;
+        }
+        async _isAvailable() {
+            return true;
+        }
+        async _set(key, value) {
+            const store = readStore();
+            store[key] = value;
+            writeStore(store);
+        }
+        async _get(key) {
+            const store = readStore();
+            return Object.prototype.hasOwnProperty.call(store, key) ? store[key] : null;
+        }
+        async _remove(key) {
+            // See the freeze comment above the closure. During init we keep
+            // the cached credential rather than letting the SDK's startup
+            // validation wipe it.
+            if (frozen)
+                return;
+            const store = readStore();
+            delete store[key];
+            writeStore(store);
+        }
+        // Cross-tab change listeners are a browser concern; no-ops in Node.
+        _addListener(_key, _listener) { }
+        _removeListener(_key, _listener) { }
+    };
 }
+//# sourceMappingURL=auth-persistence.js.map

package/config.d.ts

@@ -0,0 +1,13 @@
+export interface OrgConfig {
+    orgId: string;
+    localPath: string;
+}
+export interface NormalizedConfig {
+    projectId: string;
+    orgs: OrgConfig[];
+}
+export declare function resolveConfigPath(arg: string, defaultDir: string): string;
+export declare function normalizeConfig(raw: unknown): NormalizedConfig;
+export declare function loadConfig(absPath: string): NormalizedConfig | null;
+export declare function saveConfig(absPath: string, configObject: NormalizedConfig): void;
+//# sourceMappingURL=config.d.ts.map

package/config.js

@@ -19,85 +19,86 @@
 //     }
 //
 // `normalizeConfig` produces the multi-org shape from either.
-
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-
 function expandHome(p) {
-  if (typeof p !== 'string') return p;
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
+    if (p === '~')
+        return os.homedir();
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
 }
-
 // Resolve a --config arg to an absolute path.
 // Absolute paths are returned as-is. ~/ is expanded to the user home.
 // Otherwise the arg is treated as relative to defaultDir.
 export function resolveConfigPath(arg, defaultDir) {
-  const expanded = expandHome(arg);
-  if (path.isAbsolute(expanded)) return expanded;
-  return path.join(defaultDir, expanded);
+    const expanded = expandHome(arg);
+    if (path.isAbsolute(expanded))
+        return expanded;
+    return path.join(defaultDir, expanded);
 }
-
 // Normalize a raw config object into the multi-org shape.
 // Throws if required fields are missing or contradictory.
 export function normalizeConfig(raw) {
-  if (!raw || typeof raw !== 'object') {
-    throw new Error('Config must be an object');
-  }
-  if (!raw.projectId) {
-    throw new Error('Config is missing required field: projectId');
-  }
-
-  let orgs;
-  if (Array.isArray(raw.orgs)) {
-    orgs = raw.orgs;
-  } else if (raw.orgId) {
-    orgs = [{ orgId: raw.orgId, localPath: raw.localPath }];
-  } else {
-    throw new Error('Config must define either orgs[] or orgId');
-  }
-
-  if (orgs.length === 0) {
-    throw new Error('Config must define at least one org');
-  }
-
-  const seenPaths = new Set();
-  const normalizedOrgs = orgs.map((entry, idx) => {
-    if (!entry || typeof entry !== 'object') {
-      throw new Error(`orgs[${idx}] must be an object`);
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('Config must be an object');
     }
-    if (!entry.orgId) {
-      throw new Error(`orgs[${idx}] is missing required field: orgId`);
+    const r = raw;
+    const projectId = r['projectId'];
+    if (typeof projectId !== 'string' || !projectId) {
+        throw new Error('Config is missing required field: projectId');
     }
-    if (!entry.localPath) {
-      throw new Error(`orgs[${idx}] is missing required field: localPath`);
+    let orgs;
+    if (Array.isArray(r['orgs'])) {
+        orgs = r['orgs'];
     }
-    const localPath = expandHome(entry.localPath);
-    if (seenPaths.has(localPath)) {
-      throw new Error(`orgs[${idx}] has a duplicate localPath: ${localPath}`);
+    else if (r['orgId']) {
+        orgs = [{ orgId: r['orgId'], localPath: r['localPath'] }];
     }
-    seenPaths.add(localPath);
-    return { orgId: entry.orgId, localPath };
-  });
-
-  return { projectId: raw.projectId, orgs: normalizedOrgs };
+    else {
+        throw new Error('Config must define either orgs[] or orgId');
+    }
+    if (orgs.length === 0) {
+        throw new Error('Config must define at least one org');
+    }
+    const seenPaths = new Set();
+    const normalizedOrgs = orgs.map((entry, idx) => {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error(`orgs[${idx}] must be an object`);
+        }
+        const e = entry;
+        const orgId = e['orgId'];
+        if (typeof orgId !== 'string' || !orgId) {
+            throw new Error(`orgs[${idx}] is missing required field: orgId`);
+        }
+        const rawLocalPath = e['localPath'];
+        if (typeof rawLocalPath !== 'string' || !rawLocalPath) {
+            throw new Error(`orgs[${idx}] is missing required field: localPath`);
+        }
+        const localPath = expandHome(rawLocalPath);
+        if (seenPaths.has(localPath)) {
+            throw new Error(`orgs[${idx}] has a duplicate localPath: ${localPath}`);
+        }
+        seenPaths.add(localPath);
+        return { orgId, localPath };
+    });
+    return { projectId, orgs: normalizedOrgs };
 }
-
 // Load a config file from disk and return it normalized.
 // Returns null if the file doesn't exist (caller can trigger setup).
 // Throws if the file exists but is invalid JSON or fails normalization.
 export function loadConfig(absPath) {
-  if (!fs.existsSync(absPath)) return null;
-  const raw = JSON.parse(fs.readFileSync(absPath, 'utf-8'));
-  return normalizeConfig(raw);
+    if (!fs.existsSync(absPath))
+        return null;
+    const raw = JSON.parse(fs.readFileSync(absPath, 'utf-8'));
+    return normalizeConfig(raw);
 }
-
 // Write a config object to disk. Creates the parent directory chain if
 // it doesn't already exist (so callers can target paths like
 // ~/.config/compound-sync/work.json without manual mkdir).
 export function saveConfig(absPath, configObject) {
-  fs.mkdirSync(path.dirname(absPath), { recursive: true });
-  fs.writeFileSync(absPath, JSON.stringify(configObject, null, 2) + '\n');
+    fs.mkdirSync(path.dirname(absPath), { recursive: true });
+    fs.writeFileSync(absPath, JSON.stringify(configObject, null, 2) + '\n');
 }
+//# sourceMappingURL=config.js.map

package/files.d.ts

@@ -0,0 +1,221 @@
+import { type CollectionReference, type DocumentData } from 'firebase/firestore';
+import { type FirebaseStorage } from 'firebase/storage';
+import { type StorageData } from './storage-helpers.js';
+export { storagePathFor, extFromPath, contentByteSize, computeContentHash, isTextMimeType, mimeTypeFromExt, } from './storage-helpers.js';
+interface BlobLocation {
+    storage: FirebaseStorage;
+    orgId: string;
+    fileId: string;
+    ext: string;
+}
+export interface UploadBlobInput extends BlobLocation {
+    data: StorageData;
+    mimeType?: string;
+}
+interface ScopedFolderQuery {
+    filesRef: CollectionReference<DocumentData>;
+    scope: string;
+    teamId?: string | null | undefined;
+    userId?: string | undefined;
+}
+export interface EnsureFolderChainInput extends ScopedFolderQuery {
+    docPath: string;
+    now?: string | undefined;
+}
+export interface PushFolderInput extends ScopedFolderQuery {
+    docPath: string;
+    now?: string | undefined;
+}
+export type PushFolderOutcome = {
+    action: 'skipped';
+    reason: 'shared-scope';
+} | {
+    action: 'ensured';
+    folderId: string | null;
+};
+export interface DeleteFolderInput {
+    filesRef: CollectionReference<DocumentData>;
+    storage: FirebaseStorage;
+    orgId: string;
+    scope: string;
+    teamId?: string | null | undefined;
+    userId?: string | undefined;
+    docPath: string;
+}
+export type DeleteFolderOutcome = {
+    action: 'skipped';
+    reason: 'shared-scope';
+} | {
+    action: 'not-found';
+} | {
+    action: 'deleted';
+    folderId: string | null;
+    childCount: number;
+};
+export interface PushFileInput {
+    filesRef: CollectionReference<DocumentData>;
+    storage: FirebaseStorage;
+    orgId: string;
+    userId: string;
+    scope: string;
+    teamId?: string | null | undefined;
+    docPath: string;
+    data: StorageData;
+    mimeType?: string | undefined;
+    now?: string | undefined;
+    localModifiedAt?: string | null | undefined;
+}
+export interface PushedFileData {
+    type: 'file';
+    name: string;
+    parentId: string | null;
+    path: string;
+    createdAt: string;
+    updatedAt: string;
+    scope: string;
+    teamId: string | null;
+    ownerId: string | null;
+    sharedWith: string[];
+    storagePath: string;
+    contentHash: string;
+    size: number;
+    mimeType: string;
+}
+export type PushFileToCloudOutcome = {
+    action: 'skipped';
+    reason: 'shared-scope';
+} | {
+    action: 'noop';
+    fileId: string;
+} | {
+    action: 'skipped-stale';
+    fileId: string;
+} | {
+    action: 'created';
+    fileId: string;
+    fileData: PushedFileData;
+    storageError: unknown | null;
+} | {
+    action: 'updated';
+    fileId: string;
+    storageError: unknown | null;
+};
+export interface DeleteFileInput {
+    filesRef: CollectionReference<DocumentData>;
+    storage: FirebaseStorage;
+    orgId: string;
+    userId: string;
+    scope: string;
+    teamId?: string | null | undefined;
+    docPath: string;
+}
+export type DeleteFileOutcome = {
+    action: 'skipped';
+    reason: 'shared-scope';
+} | {
+    action: 'not-found';
+    fileId?: string;
+} | {
+    action: 'deleted';
+    fileId: string;
+};
+export declare function uploadBlob({ storage, orgId, fileId, ext, data, mimeType }: UploadBlobInput): Promise<void>;
+export declare function deleteBlob({ storage, orgId, fileId, ext }: BlobLocation): Promise<void>;
+/**
+ * Read a blob from Cloud Storage as raw bytes. Throws on any failure
+ * (missing blob, permission error, network).
+ */
+export declare function readBlob({ storage, orgId, fileId, ext }: BlobLocation): Promise<Buffer>;
+/**
+ * Read a blob and decode as UTF-8 text. Convenience for text/markdown
+ * callers.
+ */
+export declare function readBlobAsText(input: BlobLocation): Promise<string>;
+/**
+ * Ensure folder docs exist for every segment of `docPath` and return
+ * the id of the leaf folder. Idempotent: existing folder docs are
+ * reused; missing ones are created; folder docs missing the `path`
+ * field are backfilled.
+ *
+ * `docPath` is the FULL slash-joined path of the folder itself (NOT a
+ * file path). Pass `'A/B'` to ensure both `A` and `A/B` exist; the
+ * returned id is for `A/B`.
+ *
+ * Returns null if `docPath` is empty (root).
+ */
+export declare function ensureFolderChainInCloud({ filesRef, scope, teamId, userId, docPath, now, }: EnsureFolderChainInput): Promise<string | null>;
+/**
+ * Find or create the folder doc at `docPath`. Convenience wrapper
+ * around ensureFolderChainInCloud for callers that want to upsert a
+ * folder explicitly (e.g., chokidar `addDir` events).
+ *
+ * Returns:
+ *   { action: 'skipped',        reason: 'shared-scope' }
+ *   { action: 'ensured',        folderId }
+ */
+export declare function pushFolderToCloud({ filesRef, scope, teamId, userId, docPath, now, }: PushFolderInput): Promise<PushFolderOutcome>;
+/**
+ * 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, childCount }
+ */
+export declare function deleteFolderFromCloud({ filesRef, storage, orgId, scope, teamId, userId, docPath, }: DeleteFolderInput): Promise<DeleteFolderOutcome>;
+/**
+ * Push a file's content to the cloud: ensure the parent folder chain
+ * exists, upsert the Firestore metadata doc (with canonical fields
+ * including `type: 'file'`, `name`, `parentId`), and upload the blob.
+ *
+ * Args:
+ *   - data: the file's content. String, Buffer, or Uint8Array.
+ *   - mimeType: the file's mime type. Stored on the metadata doc and
+ *               used as the blob's Content-Type. Optional; if absent
+ *               for an existing file the existing mime is preserved,
+ *               and for new files defaults to 'text/markdown' to keep
+ *               legacy callers working.
+ *
+ *   - localModifiedAt: ISO timestamp of the local file's last
+ *               modification (mtime). When provided, a push that would
+ *               overwrite a server copy whose `updatedAt` is strictly
+ *               newer is skipped instead, so an older local file cannot
+ *               clobber a newer remote edit (last-write-wins, symmetric
+ *               with the firestore -> local pull guard). Omit it to
+ *               force the push regardless of timestamps (legacy callers).
+ *
+ * Returns one of:
+ *   { action: 'skipped',       reason: 'shared-scope' }
+ *   { action: 'noop',          fileId }
+ *   { action: 'skipped-stale', fileId }  // server copy is newer
+ *   { action: 'created',       fileId, fileData, storageError? }
+ *   { action: 'updated',       fileId, storageError? }
+ */
+export declare function pushFileToCloud({ filesRef, storage, orgId, userId, scope, teamId, docPath, data, mimeType, now, localModifiedAt, }: PushFileInput): Promise<PushFileToCloudOutcome>;
+/**
+ * Delete a file from Firestore and the corresponding Storage blob.
+ *
+ * Returns one of:
+ *   { action: 'skipped',        reason: 'shared-scope' }
+ *   { action: 'not-found' }
+ *   { action: 'deleted',        fileId }
+ *
+ * Blob deletion tolerates `storage/object-not-found`.
+ */
+export declare function deleteFileFromCloud({ filesRef, storage, orgId, userId, scope, teamId, docPath, }: DeleteFileInput): Promise<DeleteFileOutcome>;
+//# sourceMappingURL=files.d.ts.map