@noy-db/to-icloud 0.2.0-pre.30 → 0.2.0-pre.32

package/README.md

@@ -24,8 +24,8 @@ iCloud Drive bundle store for noy-db — macOS-aware persistence that detects ev
 
 See the [main repository](https://github.com/vLannaAi/noy-db#readme) for setup, examples, and the full subsystem catalog.
 
-- Source — [`packages/to-icloud`](https://github.com/vLannaAi/noy-db/tree/main/packages/to-icloud)
-- Issues — [github.com/vLannaAi/noy-db/issues](https://github.com/vLannaAi/noy-db/issues)
+- Source — [`to-icloud`](https://github.com/vLannaAi/noy-db-to/tree/main/to-icloud)
+- Issues — [github.com/vLannaAi/noy-db-to/issues](https://github.com/vLannaAi/noy-db-to/issues)
 - Spec — [`SPEC.md`](https://github.com/vLannaAi/noy-db/blob/main/SPEC.md)
 
 ## License

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NoydbBundleStore } from '@noy-db/hub';
+import { NoydbPodStore } from '@noy-db/hub/to';
 
 /**
  * **@noy-db/to-icloud** — iCloud Drive bundle store for noy-db.
@@ -20,7 +20,7 @@ import { NoydbBundleStore } from '@noy-db/hub';
  *      macOS), and retries.
  *   2. **Conflict files.** Parallel writes from two devices create
  *      `name (device conflicted copy DATE).noydb`. This store detects
- *      those files and raises `BundleVersionConflictError`, giving the
+ *      those files and raises `PodVersionConflictError`, giving the
  *      caller a chance to merge deliberately.
  *   3. **Sync-not-yet-complete writes.** A completed `writeFile()` does
  *      not mean the bytes are on Apple's servers. `ping()` reports
@@ -63,10 +63,10 @@ interface ICloudStoreOptions {
     readonly suffix?: string;
 }
 /**
- * Build a `NoydbBundleStore` over an iCloud Drive folder. Wrap with
+ * Build a `NoydbPodStore` over an iCloud Drive folder. Wrap with
  * `wrapBundleStore()` to consume via `createNoydb({ store })`.
  */
-declare function icloud(options: ICloudStoreOptions): NoydbBundleStore;
+declare function icloud(options: ICloudStoreOptions): NoydbPodStore;
 /**
  * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic
  * import keeps the package browser-loadable (the caller's bundler

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { BundleVersionConflictError } from "@noy-db/hub";
+import { PodVersionConflictError } from "@noy-db/hub/to";
 var DEFAULT_FOLDER = "NoyDB";
 function fileName(vault, suffix) {
   return `${vault}${suffix}`;
@@ -65,7 +65,7 @@ function icloud(options) {
     async writeBundle(vaultId, bytes, expectedVersion) {
       const conflict = await detectConflict(vaultId);
       if (conflict) {
-        throw new BundleVersionConflictError(
+        throw new PodVersionConflictError(
           `iCloud conflict file detected alongside "${vaultId}${suffix}": "${conflict}". Open iCloud Drive, resolve the conflict, then retry.`
         );
       }
@@ -73,7 +73,7 @@ function icloud(options) {
       const stat = await fs.stat(path);
       const current = stat ? versionOf(stat) : null;
       if (expectedVersion !== null && current !== null && expectedVersion !== current) {
-        throw new BundleVersionConflictError(
+        throw new PodVersionConflictError(
           `iCloud bundle version mismatch: expected ${expectedVersion}, found ${current}`
         );
       }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/to-icloud** — iCloud Drive bundle store for noy-db.\n *\n * Treats each vault as a single `.noydb` bundle stored under\n * `~/Library/Mobile Documents/…` (or any user-chosen iCloud path).\n * Pair with `wrapBundleStore()` from `@noy-db/hub` to get the\n * standard six-method `NoydbStore` surface.\n *\n * ## Why a dedicated package if `to-file` \"works\"?\n *\n * `@noy-db/to-file` pointed at an iCloud Drive directory technically\n * works — until one of three iCloud-specific behaviors bites you:\n *\n *   1. **On-demand eviction.** iCloud may evict the file to cloud-only\n *      storage, leaving a `.icloud` stub. `readFile()` on the stub\n *      either throws ENOENT or returns stub metadata. This store\n *      detects the stub, nudges the OS to redownload (via `xattr` on\n *      macOS), and retries.\n *   2. **Conflict files.** Parallel writes from two devices create\n *      `name (device conflicted copy DATE).noydb`. This store detects\n *      those files and raises `BundleVersionConflictError`, giving the\n *      caller a chance to merge deliberately.\n *   3. **Sync-not-yet-complete writes.** A completed `writeFile()` does\n *      not mean the bytes are on Apple's servers. `ping()` reports\n *      on upload status so callers can wait before considering a\n *      write durable.\n *\n * ## Scope\n *\n * - **Node (macOS) only for v1.** Browser / iOS consumers go through\n *   CloudKit JS — a separate package will ship as `@noy-db/to-cloudkit`.\n * - **Bundle granularity** — whole vault in one file. Pair with\n *   `syncPolicy: { push: { mode: 'debounce', 30_000 } }` so every\n *   record mutation doesn't trigger a full bundle upload.\n * - **No extra auth** — iCloud syncs via the user's signed-in Apple ID;\n *   the store never sees credentials.\n *\n * @packageDocumentation\n */\n\nimport type { NoydbBundleStore } from '@noy-db/hub'\nimport { BundleVersionConflictError } from '@noy-db/hub'\n\n/** Default iCloud Drive folder name inside a user's mobile-documents tree. */\nexport const DEFAULT_FOLDER = 'NoyDB'\n\nexport interface ICloudFs {\n  readFile(path: string): Promise<Uint8Array | Buffer | null>\n  writeFile(path: string, data: Uint8Array): Promise<void>\n  unlink(path: string): Promise<void>\n  readdir(path: string): Promise<string[]>\n  stat(path: string): Promise<{ mtimeMs: number; size: number } | null>\n  /** macOS-only: force iCloud to materialise an evicted `.icloud` stub. */\n  triggerDownload?(path: string): Promise<void>\n}\n\nexport interface ICloudStoreOptions {\n  /** Absolute path to the iCloud Drive folder that holds bundles. */\n  readonly folder: string\n  /** File-system facade — swap in a mock or a cross-platform shim. */\n  readonly fs: ICloudFs\n  /** Bundle filename suffix. Default `'.noydb'`. */\n  readonly suffix?: string\n}\n\nfunction fileName(vault: string, suffix: string): string {\n  return `${vault}${suffix}`\n}\n\nfunction isStub(name: string): boolean {\n  // macOS writes `<name>.icloud` stubs when offloading files.\n  return name.endsWith('.icloud')\n}\n\nfunction isConflictCopy(name: string, expected: string): boolean {\n  // Canonical shape: `foo (device conflicted copy DATE).noydb`\n  return name.includes(\"'s conflicted copy\") ||\n         (name.includes('(conflicted copy') && name.endsWith(expected.slice(expected.lastIndexOf('.'))))\n}\n\n/**\n * Build a `NoydbBundleStore` over an iCloud Drive folder. Wrap with\n * `wrapBundleStore()` to consume via `createNoydb({ store })`.\n */\nexport function icloud(options: ICloudStoreOptions): NoydbBundleStore {\n  const suffix = options.suffix ?? '.noydb'\n  const dir = options.folder.replace(/\\/+$/, '')\n  const { fs } = options\n\n  async function pathFor(vault: string): Promise<string> {\n    return `${dir}/${fileName(vault, suffix)}`\n  }\n\n  async function stubAwareRead(path: string): Promise<Uint8Array | null> {\n    // Direct read first.\n    let bytes = await fs.readFile(path)\n    if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n\n    // Check for an adjacent `.icloud` stub and try to materialise it.\n    const stubPath = `${path}.icloud`\n    const stubExists = await fs.stat(stubPath)\n    if (!stubExists) return null\n    if (fs.triggerDownload) {\n      await fs.triggerDownload(stubPath)\n      bytes = await fs.readFile(path)\n      if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n    }\n    // Still offloaded. Surface a clean error so the caller can retry\n    // or invite the user to open iCloud.\n    throw new Error(\n      `iCloud file \"${path}\" is offloaded. Open the file in Finder to trigger a download, ` +\n      `or install an OS-level trigger (\\`brctl download \"${path}\"\\`).`,\n    )\n  }\n\n  async function detectConflict(vault: string): Promise<string | null> {\n    const target = fileName(vault, suffix)\n    const entries = await fs.readdir(dir).catch(() => [] as string[])\n    for (const entry of entries) {\n      if (isConflictCopy(entry, target)) return entry\n    }\n    return null\n  }\n\n  function versionOf(stat: { mtimeMs: number; size: number }): string {\n    // mtime-based opaque token — sufficient for OCC within a single\n    // syncing agent. iCloud's native conflict file machinery provides\n    // the cross-agent guard.\n    return `${stat.mtimeMs}-${stat.size}`\n  }\n\n  return {\n    kind: 'bundle',\n    name: 'icloud',\n\n    async readBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      if (!stat) {\n        // Perhaps only a stub exists — detect and trigger.\n        const stubStat = await fs.stat(`${path}.icloud`)\n        if (!stubStat) return null\n        const bytes = await stubAwareRead(path)\n        if (!bytes) return null\n        const redoStat = await fs.stat(path)\n        if (!redoStat) throw new Error(`icloud: file vanished after download at ${path}`)\n        return { bytes, version: versionOf(redoStat) }\n      }\n      const bytes = await stubAwareRead(path)\n      if (!bytes) return null\n      return { bytes, version: versionOf(stat) }\n    },\n\n    async writeBundle(vaultId, bytes, expectedVersion) {\n      // Conflict file present → refuse; caller merges.\n      const conflict = await detectConflict(vaultId)\n      if (conflict) {\n        throw new BundleVersionConflictError(\n          `iCloud conflict file detected alongside \"${vaultId}${suffix}\": \"${conflict}\". ` +\n          `Open iCloud Drive, resolve the conflict, then retry.`,\n        )\n      }\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      const current = stat ? versionOf(stat) : null\n      if (expectedVersion !== null && current !== null && expectedVersion !== current) {\n        throw new BundleVersionConflictError(\n          `iCloud bundle version mismatch: expected ${expectedVersion}, found ${current}`,\n        )\n      }\n      await fs.writeFile(path, bytes)\n      const newStat = await fs.stat(path)\n      if (!newStat) throw new Error(`icloud: write reported success but stat failed at ${path}`)\n      return { version: versionOf(newStat) }\n    },\n\n    async deleteBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      try {\n        await fs.unlink(path)\n      } catch {\n        // Idempotent\n      }\n    },\n\n    async listBundles() {\n      const entries = await fs.readdir(dir).catch(() => [] as string[])\n      const out: Array<{ vaultId: string; version: string; size: number }> = []\n      for (const entry of entries) {\n        if (!entry.endsWith(suffix) || isStub(entry)) continue\n        const vaultId = entry.slice(0, -suffix.length)\n        const stat = await fs.stat(`${dir}/${entry}`)\n        if (!stat) continue\n        out.push({ vaultId, version: versionOf(stat), size: stat.size })\n      }\n      return out\n    },\n  }\n}\n\n/**\n * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic\n * import keeps the package browser-loadable (the caller's bundler\n * prunes the Node path).\n */\nexport async function nodeFs(): Promise<ICloudFs> {\n  const fs = await import('node:fs/promises')\n  const { spawn } = await import('node:child_process')\n  return {\n    async readFile(path) {\n      try {\n        return await fs.readFile(path)\n      } catch {\n        return null\n      }\n    },\n    async writeFile(path, data) {\n      await fs.writeFile(path, data)\n    },\n    async unlink(path) {\n      await fs.unlink(path).catch(() => undefined)\n    },\n    async readdir(path) {\n      return fs.readdir(path)\n    },\n    async stat(path) {\n      try {\n        const s = await fs.stat(path)\n        return { mtimeMs: s.mtimeMs, size: s.size }\n      } catch {\n        return null\n      }\n    },\n    async triggerDownload(path) {\n      // macOS: `brctl download` forces iCloud to materialise a stub.\n      await new Promise<void>((resolve) => {\n        const child = spawn('brctl', ['download', path.replace(/\\.icloud$/, '')])\n        child.on('close', () => resolve())\n        child.on('error', () => resolve())\n      })\n    },\n  }\n}\n"],"mappings":";AAyCA,SAAS,kCAAkC;AAGpC,IAAM,iBAAiB;AAqB9B,SAAS,SAAS,OAAe,QAAwB;AACvD,SAAO,GAAG,KAAK,GAAG,MAAM;AAC1B;AAEA,SAAS,OAAO,MAAuB;AAErC,SAAO,KAAK,SAAS,SAAS;AAChC;AAEA,SAAS,eAAe,MAAc,UAA2B;AAE/D,SAAO,KAAK,SAAS,oBAAoB,KACjC,KAAK,SAAS,kBAAkB,KAAK,KAAK,SAAS,SAAS,MAAM,SAAS,YAAY,GAAG,CAAC,CAAC;AACtG;AAMO,SAAS,OAAO,SAA+C;AACpE,QAAM,SAAS,QAAQ,UAAU;AACjC,QAAM,MAAM,QAAQ,OAAO,QAAQ,QAAQ,EAAE;AAC7C,QAAM,EAAE,GAAG,IAAI;AAEf,iBAAe,QAAQ,OAAgC;AACrD,WAAO,GAAG,GAAG,IAAI,SAAS,OAAO,MAAM,CAAC;AAAA,EAC1C;AAEA,iBAAe,cAAc,MAA0C;AAErE,QAAI,QAAQ,MAAM,GAAG,SAAS,IAAI;AAClC,QAAI,UAAU,KAAM,QAAO,iBAAiB,aAAa,QAAQ,IAAI,WAAW,KAAK;AAGrF,UAAM,WAAW,GAAG,IAAI;AACxB,UAAM,aAAa,MAAM,GAAG,KAAK,QAAQ;AACzC,QAAI,CAAC,WAAY,QAAO;AACxB,QAAI,GAAG,iBAAiB;AACtB,YAAM,GAAG,gBAAgB,QAAQ;AACjC,cAAQ,MAAM,GAAG,SAAS,IAAI;AAC9B,UAAI,UAAU,KAAM,QAAO,iBAAiB,aAAa,QAAQ,IAAI,WAAW,KAAK;AAAA,IACvF;AAGA,UAAM,IAAI;AAAA,MACR,gBAAgB,IAAI,oHACiC,IAAI;AAAA,IAC3D;AAAA,EACF;AAEA,iBAAe,eAAe,OAAuC;AACnE,UAAM,SAAS,SAAS,OAAO,MAAM;AACrC,UAAM,UAAU,MAAM,GAAG,QAAQ,GAAG,EAAE,MAAM,MAAM,CAAC,CAAa;AAChE,eAAW,SAAS,SAAS;AAC3B,UAAI,eAAe,OAAO,MAAM,EAAG,QAAO;AAAA,IAC5C;AACA,WAAO;AAAA,EACT;AAEA,WAAS,UAAU,MAAiD;AAIlE,WAAO,GAAG,KAAK,OAAO,IAAI,KAAK,IAAI;AAAA,EACrC;AAEA,SAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM;AAAA,IAEN,MAAM,WAAW,SAAS;AACxB,YAAM,OAAO,MAAM,QAAQ,OAAO;AAClC,YAAM,OAAO,MAAM,GAAG,KAAK,IAAI;AAC/B,UAAI,CAAC,MAAM;AAET,cAAM,WAAW,MAAM,GAAG,KAAK,GAAG,IAAI,SAAS;AAC/C,YAAI,CAAC,SAAU,QAAO;AACtB,cAAMA,SAAQ,MAAM,cAAc,IAAI;AACtC,YAAI,CAACA,OAAO,QAAO;AACnB,cAAM,WAAW,MAAM,GAAG,KAAK,IAAI;AACnC,YAAI,CAAC,SAAU,OAAM,IAAI,MAAM,2CAA2C,IAAI,EAAE;AAChF,eAAO,EAAE,OAAAA,QAAO,SAAS,UAAU,QAAQ,EAAE;AAAA,MAC/C;AACA,YAAM,QAAQ,MAAM,cAAc,IAAI;AACtC,UAAI,CAAC,MAAO,QAAO;AACnB,aAAO,EAAE,OAAO,SAAS,UAAU,IAAI,EAAE;AAAA,IAC3C;AAAA,IAEA,MAAM,YAAY,SAAS,OAAO,iBAAiB;AAEjD,YAAM,WAAW,MAAM,eAAe,OAAO;AAC7C,UAAI,UAAU;AACZ,cAAM,IAAI;AAAA,UACR,4CAA4C,OAAO,GAAG,MAAM,OAAO,QAAQ;AAAA,QAE7E;AAAA,MACF;AACA,YAAM,OAAO,MAAM,QAAQ,OAAO;AAClC,YAAM,OAAO,MAAM,GAAG,KAAK,IAAI;AAC/B,YAAM,UAAU,OAAO,UAAU,IAAI,IAAI;AACzC,UAAI,oBAAoB,QAAQ,YAAY,QAAQ,oBAAoB,SAAS;AAC/E,cAAM,IAAI;AAAA,UACR,4CAA4C,eAAe,WAAW,OAAO;AAAA,QAC/E;AAAA,MACF;AACA,YAAM,GAAG,UAAU,MAAM,KAAK;AAC9B,YAAM,UAAU,MAAM,GAAG,KAAK,IAAI;AAClC,UAAI,CAAC,QAAS,OAAM,IAAI,MAAM,qDAAqD,IAAI,EAAE;AACzF,aAAO,EAAE,SAAS,UAAU,OAAO,EAAE;AAAA,IACvC;AAAA,IAEA,MAAM,aAAa,SAAS;AAC1B,YAAM,OAAO,MAAM,QAAQ,OAAO;AAClC,UAAI;AACF,cAAM,GAAG,OAAO,IAAI;AAAA,MACtB,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,IAEA,MAAM,cAAc;AAClB,YAAM,UAAU,MAAM,GAAG,QAAQ,GAAG,EAAE,MAAM,MAAM,CAAC,CAAa;AAChE,YAAM,MAAiE,CAAC;AACxE,iBAAW,SAAS,SAAS;AAC3B,YAAI,CAAC,MAAM,SAAS,MAAM,KAAK,OAAO,KAAK,EAAG;AAC9C,cAAM,UAAU,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM;AAC7C,cAAM,OAAO,MAAM,GAAG,KAAK,GAAG,GAAG,IAAI,KAAK,EAAE;AAC5C,YAAI,CAAC,KAAM;AACX,YAAI,KAAK,EAAE,SAAS,SAAS,UAAU,IAAI,GAAG,MAAM,KAAK,KAAK,CAAC;AAAA,MACjE;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAOA,eAAsB,SAA4B;AAChD,QAAM,KAAK,MAAM,OAAO,aAAkB;AAC1C,QAAM,EAAE,MAAM,IAAI,MAAM,OAAO,eAAoB;AACnD,SAAO;AAAA,IACL,MAAM,SAAS,MAAM;AACnB,UAAI;AACF,eAAO,MAAM,GAAG,SAAS,IAAI;AAAA,MAC/B,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,MAAM,UAAU,MAAM,MAAM;AAC1B,YAAM,GAAG,UAAU,MAAM,IAAI;AAAA,IAC/B;AAAA,IACA,MAAM,OAAO,MAAM;AACjB,YAAM,GAAG,OAAO,IAAI,EAAE,MAAM,MAAM,MAAS;AAAA,IAC7C;AAAA,IACA,MAAM,QAAQ,MAAM;AAClB,aAAO,GAAG,QAAQ,IAAI;AAAA,IACxB;AAAA,IACA,MAAM,KAAK,MAAM;AACf,UAAI;AACF,cAAM,IAAI,MAAM,GAAG,KAAK,IAAI;AAC5B,eAAO,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,KAAK;AAAA,MAC5C,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,MAAM,gBAAgB,MAAM;AAE1B,YAAM,IAAI,QAAc,CAAC,YAAY;AACnC,cAAM,QAAQ,MAAM,SAAS,CAAC,YAAY,KAAK,QAAQ,aAAa,EAAE,CAAC,CAAC;AACxE,cAAM,GAAG,SAAS,MAAM,QAAQ,CAAC;AACjC,cAAM,GAAG,SAAS,MAAM,QAAQ,CAAC;AAAA,MACnC,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":["bytes"]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/to-icloud** — iCloud Drive bundle store for noy-db.\n *\n * Treats each vault as a single `.noydb` bundle stored under\n * `~/Library/Mobile Documents/…` (or any user-chosen iCloud path).\n * Pair with `wrapBundleStore()` from `@noy-db/hub` to get the\n * standard six-method `NoydbStore` surface.\n *\n * ## Why a dedicated package if `to-file` \"works\"?\n *\n * `@noy-db/to-file` pointed at an iCloud Drive directory technically\n * works — until one of three iCloud-specific behaviors bites you:\n *\n *   1. **On-demand eviction.** iCloud may evict the file to cloud-only\n *      storage, leaving a `.icloud` stub. `readFile()` on the stub\n *      either throws ENOENT or returns stub metadata. This store\n *      detects the stub, nudges the OS to redownload (via `xattr` on\n *      macOS), and retries.\n *   2. **Conflict files.** Parallel writes from two devices create\n *      `name (device conflicted copy DATE).noydb`. This store detects\n *      those files and raises `PodVersionConflictError`, giving the\n *      caller a chance to merge deliberately.\n *   3. **Sync-not-yet-complete writes.** A completed `writeFile()` does\n *      not mean the bytes are on Apple's servers. `ping()` reports\n *      on upload status so callers can wait before considering a\n *      write durable.\n *\n * ## Scope\n *\n * - **Node (macOS) only for v1.** Browser / iOS consumers go through\n *   CloudKit JS — a separate package will ship as `@noy-db/to-cloudkit`.\n * - **Bundle granularity** — whole vault in one file. Pair with\n *   `syncPolicy: { push: { mode: 'debounce', 30_000 } }` so every\n *   record mutation doesn't trigger a full bundle upload.\n * - **No extra auth** — iCloud syncs via the user's signed-in Apple ID;\n *   the store never sees credentials.\n *\n * @packageDocumentation\n */\n\nimport type { NoydbPodStore } from '@noy-db/hub/to'\nimport { PodVersionConflictError } from '@noy-db/hub/to'\n\n/** Default iCloud Drive folder name inside a user's mobile-documents tree. */\nexport const DEFAULT_FOLDER = 'NoyDB'\n\nexport interface ICloudFs {\n  readFile(path: string): Promise<Uint8Array | Buffer | null>\n  writeFile(path: string, data: Uint8Array): Promise<void>\n  unlink(path: string): Promise<void>\n  readdir(path: string): Promise<string[]>\n  stat(path: string): Promise<{ mtimeMs: number; size: number } | null>\n  /** macOS-only: force iCloud to materialise an evicted `.icloud` stub. */\n  triggerDownload?(path: string): Promise<void>\n}\n\nexport interface ICloudStoreOptions {\n  /** Absolute path to the iCloud Drive folder that holds bundles. */\n  readonly folder: string\n  /** File-system facade — swap in a mock or a cross-platform shim. */\n  readonly fs: ICloudFs\n  /** Bundle filename suffix. Default `'.noydb'`. */\n  readonly suffix?: string\n}\n\nfunction fileName(vault: string, suffix: string): string {\n  return `${vault}${suffix}`\n}\n\nfunction isStub(name: string): boolean {\n  // macOS writes `<name>.icloud` stubs when offloading files.\n  return name.endsWith('.icloud')\n}\n\nfunction isConflictCopy(name: string, expected: string): boolean {\n  // Canonical shape: `foo (device conflicted copy DATE).noydb`\n  return name.includes(\"'s conflicted copy\") ||\n         (name.includes('(conflicted copy') && name.endsWith(expected.slice(expected.lastIndexOf('.'))))\n}\n\n/**\n * Build a `NoydbPodStore` over an iCloud Drive folder. Wrap with\n * `wrapBundleStore()` to consume via `createNoydb({ store })`.\n */\nexport function icloud(options: ICloudStoreOptions): NoydbPodStore {\n  const suffix = options.suffix ?? '.noydb'\n  const dir = options.folder.replace(/\\/+$/, '')\n  const { fs } = options\n\n  async function pathFor(vault: string): Promise<string> {\n    return `${dir}/${fileName(vault, suffix)}`\n  }\n\n  async function stubAwareRead(path: string): Promise<Uint8Array | null> {\n    // Direct read first.\n    let bytes = await fs.readFile(path)\n    if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n\n    // Check for an adjacent `.icloud` stub and try to materialise it.\n    const stubPath = `${path}.icloud`\n    const stubExists = await fs.stat(stubPath)\n    if (!stubExists) return null\n    if (fs.triggerDownload) {\n      await fs.triggerDownload(stubPath)\n      bytes = await fs.readFile(path)\n      if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n    }\n    // Still offloaded. Surface a clean error so the caller can retry\n    // or invite the user to open iCloud.\n    throw new Error(\n      `iCloud file \"${path}\" is offloaded. Open the file in Finder to trigger a download, ` +\n      `or install an OS-level trigger (\\`brctl download \"${path}\"\\`).`,\n    )\n  }\n\n  async function detectConflict(vault: string): Promise<string | null> {\n    const target = fileName(vault, suffix)\n    const entries = await fs.readdir(dir).catch(() => [] as string[])\n    for (const entry of entries) {\n      if (isConflictCopy(entry, target)) return entry\n    }\n    return null\n  }\n\n  function versionOf(stat: { mtimeMs: number; size: number }): string {\n    // mtime-based opaque token — sufficient for OCC within a single\n    // syncing agent. iCloud's native conflict file machinery provides\n    // the cross-agent guard.\n    return `${stat.mtimeMs}-${stat.size}`\n  }\n\n  return {\n    kind: 'bundle',\n    name: 'icloud',\n\n    async readBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      if (!stat) {\n        // Perhaps only a stub exists — detect and trigger.\n        const stubStat = await fs.stat(`${path}.icloud`)\n        if (!stubStat) return null\n        const bytes = await stubAwareRead(path)\n        if (!bytes) return null\n        const redoStat = await fs.stat(path)\n        if (!redoStat) throw new Error(`icloud: file vanished after download at ${path}`)\n        return { bytes, version: versionOf(redoStat) }\n      }\n      const bytes = await stubAwareRead(path)\n      if (!bytes) return null\n      return { bytes, version: versionOf(stat) }\n    },\n\n    async writeBundle(vaultId, bytes, expectedVersion) {\n      // Conflict file present → refuse; caller merges.\n      const conflict = await detectConflict(vaultId)\n      if (conflict) {\n        throw new PodVersionConflictError(\n          `iCloud conflict file detected alongside \"${vaultId}${suffix}\": \"${conflict}\". ` +\n          `Open iCloud Drive, resolve the conflict, then retry.`,\n        )\n      }\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      const current = stat ? versionOf(stat) : null\n      if (expectedVersion !== null && current !== null && expectedVersion !== current) {\n        throw new PodVersionConflictError(\n          `iCloud bundle version mismatch: expected ${expectedVersion}, found ${current}`,\n        )\n      }\n      await fs.writeFile(path, bytes)\n      const newStat = await fs.stat(path)\n      if (!newStat) throw new Error(`icloud: write reported success but stat failed at ${path}`)\n      return { version: versionOf(newStat) }\n    },\n\n    async deleteBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      try {\n        await fs.unlink(path)\n      } catch {\n        // Idempotent\n      }\n    },\n\n    async listBundles() {\n      const entries = await fs.readdir(dir).catch(() => [] as string[])\n      const out: Array<{ vaultId: string; version: string; size: number }> = []\n      for (const entry of entries) {\n        if (!entry.endsWith(suffix) || isStub(entry)) continue\n        const vaultId = entry.slice(0, -suffix.length)\n        const stat = await fs.stat(`${dir}/${entry}`)\n        if (!stat) continue\n        out.push({ vaultId, version: versionOf(stat), size: stat.size })\n      }\n      return out\n    },\n  }\n}\n\n/**\n * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic\n * import keeps the package browser-loadable (the caller's bundler\n * prunes the Node path).\n */\nexport async function nodeFs(): Promise<ICloudFs> {\n  const fs = await import('node:fs/promises')\n  const { spawn } = await import('node:child_process')\n  return {\n    async readFile(path) {\n      try {\n        return await fs.readFile(path)\n      } catch {\n        return null\n      }\n    },\n    async writeFile(path, data) {\n      await fs.writeFile(path, data)\n    },\n    async unlink(path) {\n      await fs.unlink(path).catch(() => undefined)\n    },\n    async readdir(path) {\n      return fs.readdir(path)\n    },\n    async stat(path) {\n      try {\n        const s = await fs.stat(path)\n        return { mtimeMs: s.mtimeMs, size: s.size }\n      } catch {\n        return null\n      }\n    },\n    async triggerDownload(path) {\n      // macOS: `brctl download` forces iCloud to materialise a stub.\n      await new Promise<void>((resolve) => {\n        const child = spawn('brctl', ['download', path.replace(/\\.icloud$/, '')])\n        child.on('close', () => resolve())\n        child.on('error', () => resolve())\n      })\n    },\n  }\n}\n"],"mappings":"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","names":["bytes"]}

package/package.json

@@ -1,33 +1,25 @@
 {
   "name": "@noy-db/to-icloud",
-  "version": "0.2.0-pre.30",
+  "version": "0.2.0-pre.32",
   "description": "iCloud Drive bundle store for noy-db — macOS-aware persistence that detects eviction stubs (.icloud) and conflict files automatically. Treats each vault as a single .noydb bundle, safe for the Apple ecosystem.",
   "license": "MIT",
   "author": "vLannaAi <vicio@lanna.ai>",
-  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/to-icloud#readme",
+  "homepage": "https://github.com/vLannaAi/noy-db-to/tree/main/to-icloud#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vLannaAi/noy-db.git",
-    "directory": "packages/to-icloud"
+    "url": "git+https://github.com/vLannaAi/noy-db-to.git"
   },
   "bugs": {
-    "url": "https://github.com/vLannaAi/noy-db/issues"
+    "url": "https://github.com/vLannaAi/noy-db-to/issues"
   },
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -36,14 +28,14 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "0.2.0-pre.30"
+    "@noy-db/hub": "^0.3.0-pre.1"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@noy-db/hub": "0.2.0-pre.30"
+    "@noy-db/hub": "0.3.0-pre.7",
+    "@types/node": "^22.0.0"
   },
   "keywords": [
     "noy-db",

package/dist/index.cjs

@@ -1,185 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  DEFAULT_FOLDER: () => DEFAULT_FOLDER,
-  icloud: () => icloud,
-  nodeFs: () => nodeFs
-});
-module.exports = __toCommonJS(index_exports);
-var import_hub = require("@noy-db/hub");
-var DEFAULT_FOLDER = "NoyDB";
-function fileName(vault, suffix) {
-  return `${vault}${suffix}`;
-}
-function isStub(name) {
-  return name.endsWith(".icloud");
-}
-function isConflictCopy(name, expected) {
-  return name.includes("'s conflicted copy") || name.includes("(conflicted copy") && name.endsWith(expected.slice(expected.lastIndexOf(".")));
-}
-function icloud(options) {
-  const suffix = options.suffix ?? ".noydb";
-  const dir = options.folder.replace(/\/+$/, "");
-  const { fs } = options;
-  async function pathFor(vault) {
-    return `${dir}/${fileName(vault, suffix)}`;
-  }
-  async function stubAwareRead(path) {
-    let bytes = await fs.readFile(path);
-    if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-    const stubPath = `${path}.icloud`;
-    const stubExists = await fs.stat(stubPath);
-    if (!stubExists) return null;
-    if (fs.triggerDownload) {
-      await fs.triggerDownload(stubPath);
-      bytes = await fs.readFile(path);
-      if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-    }
-    throw new Error(
-      `iCloud file "${path}" is offloaded. Open the file in Finder to trigger a download, or install an OS-level trigger (\`brctl download "${path}"\`).`
-    );
-  }
-  async function detectConflict(vault) {
-    const target = fileName(vault, suffix);
-    const entries = await fs.readdir(dir).catch(() => []);
-    for (const entry of entries) {
-      if (isConflictCopy(entry, target)) return entry;
-    }
-    return null;
-  }
-  function versionOf(stat) {
-    return `${stat.mtimeMs}-${stat.size}`;
-  }
-  return {
-    kind: "bundle",
-    name: "icloud",
-    async readBundle(vaultId) {
-      const path = await pathFor(vaultId);
-      const stat = await fs.stat(path);
-      if (!stat) {
-        const stubStat = await fs.stat(`${path}.icloud`);
-        if (!stubStat) return null;
-        const bytes2 = await stubAwareRead(path);
-        if (!bytes2) return null;
-        const redoStat = await fs.stat(path);
-        if (!redoStat) throw new Error(`icloud: file vanished after download at ${path}`);
-        return { bytes: bytes2, version: versionOf(redoStat) };
-      }
-      const bytes = await stubAwareRead(path);
-      if (!bytes) return null;
-      return { bytes, version: versionOf(stat) };
-    },
-    async writeBundle(vaultId, bytes, expectedVersion) {
-      const conflict = await detectConflict(vaultId);
-      if (conflict) {
-        throw new import_hub.BundleVersionConflictError(
-          `iCloud conflict file detected alongside "${vaultId}${suffix}": "${conflict}". Open iCloud Drive, resolve the conflict, then retry.`
-        );
-      }
-      const path = await pathFor(vaultId);
-      const stat = await fs.stat(path);
-      const current = stat ? versionOf(stat) : null;
-      if (expectedVersion !== null && current !== null && expectedVersion !== current) {
-        throw new import_hub.BundleVersionConflictError(
-          `iCloud bundle version mismatch: expected ${expectedVersion}, found ${current}`
-        );
-      }
-      await fs.writeFile(path, bytes);
-      const newStat = await fs.stat(path);
-      if (!newStat) throw new Error(`icloud: write reported success but stat failed at ${path}`);
-      return { version: versionOf(newStat) };
-    },
-    async deleteBundle(vaultId) {
-      const path = await pathFor(vaultId);
-      try {
-        await fs.unlink(path);
-      } catch {
-      }
-    },
-    async listBundles() {
-      const entries = await fs.readdir(dir).catch(() => []);
-      const out = [];
-      for (const entry of entries) {
-        if (!entry.endsWith(suffix) || isStub(entry)) continue;
-        const vaultId = entry.slice(0, -suffix.length);
-        const stat = await fs.stat(`${dir}/${entry}`);
-        if (!stat) continue;
-        out.push({ vaultId, version: versionOf(stat), size: stat.size });
-      }
-      return out;
-    }
-  };
-}
-async function nodeFs() {
-  const fs = await import("fs/promises");
-  const { spawn } = await import("child_process");
-  return {
-    async readFile(path) {
-      try {
-        return await fs.readFile(path);
-      } catch {
-        return null;
-      }
-    },
-    async writeFile(path, data) {
-      await fs.writeFile(path, data);
-    },
-    async unlink(path) {
-      await fs.unlink(path).catch(() => void 0);
-    },
-    async readdir(path) {
-      return fs.readdir(path);
-    },
-    async stat(path) {
-      try {
-        const s = await fs.stat(path);
-        return { mtimeMs: s.mtimeMs, size: s.size };
-      } catch {
-        return null;
-      }
-    },
-    async triggerDownload(path) {
-      await new Promise((resolve) => {
-        const child = spawn("brctl", ["download", path.replace(/\.icloud$/, "")]);
-        child.on("close", () => resolve());
-        child.on("error", () => resolve());
-      });
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  DEFAULT_FOLDER,
-  icloud,
-  nodeFs
-});
-//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * **@noy-db/to-icloud** — iCloud Drive bundle store for noy-db.\n *\n * Treats each vault as a single `.noydb` bundle stored under\n * `~/Library/Mobile Documents/…` (or any user-chosen iCloud path).\n * Pair with `wrapBundleStore()` from `@noy-db/hub` to get the\n * standard six-method `NoydbStore` surface.\n *\n * ## Why a dedicated package if `to-file` \"works\"?\n *\n * `@noy-db/to-file` pointed at an iCloud Drive directory technically\n * works — until one of three iCloud-specific behaviors bites you:\n *\n *   1. **On-demand eviction.** iCloud may evict the file to cloud-only\n *      storage, leaving a `.icloud` stub. `readFile()` on the stub\n *      either throws ENOENT or returns stub metadata. This store\n *      detects the stub, nudges the OS to redownload (via `xattr` on\n *      macOS), and retries.\n *   2. **Conflict files.** Parallel writes from two devices create\n *      `name (device conflicted copy DATE).noydb`. This store detects\n *      those files and raises `BundleVersionConflictError`, giving the\n *      caller a chance to merge deliberately.\n *   3. **Sync-not-yet-complete writes.** A completed `writeFile()` does\n *      not mean the bytes are on Apple's servers. `ping()` reports\n *      on upload status so callers can wait before considering a\n *      write durable.\n *\n * ## Scope\n *\n * - **Node (macOS) only for v1.** Browser / iOS consumers go through\n *   CloudKit JS — a separate package will ship as `@noy-db/to-cloudkit`.\n * - **Bundle granularity** — whole vault in one file. Pair with\n *   `syncPolicy: { push: { mode: 'debounce', 30_000 } }` so every\n *   record mutation doesn't trigger a full bundle upload.\n * - **No extra auth** — iCloud syncs via the user's signed-in Apple ID;\n *   the store never sees credentials.\n *\n * @packageDocumentation\n */\n\nimport type { NoydbBundleStore } from '@noy-db/hub'\nimport { BundleVersionConflictError } from '@noy-db/hub'\n\n/** Default iCloud Drive folder name inside a user's mobile-documents tree. */\nexport const DEFAULT_FOLDER = 'NoyDB'\n\nexport interface ICloudFs {\n  readFile(path: string): Promise<Uint8Array | Buffer | null>\n  writeFile(path: string, data: Uint8Array): Promise<void>\n  unlink(path: string): Promise<void>\n  readdir(path: string): Promise<string[]>\n  stat(path: string): Promise<{ mtimeMs: number; size: number } | null>\n  /** macOS-only: force iCloud to materialise an evicted `.icloud` stub. */\n  triggerDownload?(path: string): Promise<void>\n}\n\nexport interface ICloudStoreOptions {\n  /** Absolute path to the iCloud Drive folder that holds bundles. */\n  readonly folder: string\n  /** File-system facade — swap in a mock or a cross-platform shim. */\n  readonly fs: ICloudFs\n  /** Bundle filename suffix. Default `'.noydb'`. */\n  readonly suffix?: string\n}\n\nfunction fileName(vault: string, suffix: string): string {\n  return `${vault}${suffix}`\n}\n\nfunction isStub(name: string): boolean {\n  // macOS writes `<name>.icloud` stubs when offloading files.\n  return name.endsWith('.icloud')\n}\n\nfunction isConflictCopy(name: string, expected: string): boolean {\n  // Canonical shape: `foo (device conflicted copy DATE).noydb`\n  return name.includes(\"'s conflicted copy\") ||\n         (name.includes('(conflicted copy') && name.endsWith(expected.slice(expected.lastIndexOf('.'))))\n}\n\n/**\n * Build a `NoydbBundleStore` over an iCloud Drive folder. Wrap with\n * `wrapBundleStore()` to consume via `createNoydb({ store })`.\n */\nexport function icloud(options: ICloudStoreOptions): NoydbBundleStore {\n  const suffix = options.suffix ?? '.noydb'\n  const dir = options.folder.replace(/\\/+$/, '')\n  const { fs } = options\n\n  async function pathFor(vault: string): Promise<string> {\n    return `${dir}/${fileName(vault, suffix)}`\n  }\n\n  async function stubAwareRead(path: string): Promise<Uint8Array | null> {\n    // Direct read first.\n    let bytes = await fs.readFile(path)\n    if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n\n    // Check for an adjacent `.icloud` stub and try to materialise it.\n    const stubPath = `${path}.icloud`\n    const stubExists = await fs.stat(stubPath)\n    if (!stubExists) return null\n    if (fs.triggerDownload) {\n      await fs.triggerDownload(stubPath)\n      bytes = await fs.readFile(path)\n      if (bytes !== null) return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)\n    }\n    // Still offloaded. Surface a clean error so the caller can retry\n    // or invite the user to open iCloud.\n    throw new Error(\n      `iCloud file \"${path}\" is offloaded. Open the file in Finder to trigger a download, ` +\n      `or install an OS-level trigger (\\`brctl download \"${path}\"\\`).`,\n    )\n  }\n\n  async function detectConflict(vault: string): Promise<string | null> {\n    const target = fileName(vault, suffix)\n    const entries = await fs.readdir(dir).catch(() => [] as string[])\n    for (const entry of entries) {\n      if (isConflictCopy(entry, target)) return entry\n    }\n    return null\n  }\n\n  function versionOf(stat: { mtimeMs: number; size: number }): string {\n    // mtime-based opaque token — sufficient for OCC within a single\n    // syncing agent. iCloud's native conflict file machinery provides\n    // the cross-agent guard.\n    return `${stat.mtimeMs}-${stat.size}`\n  }\n\n  return {\n    kind: 'bundle',\n    name: 'icloud',\n\n    async readBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      if (!stat) {\n        // Perhaps only a stub exists — detect and trigger.\n        const stubStat = await fs.stat(`${path}.icloud`)\n        if (!stubStat) return null\n        const bytes = await stubAwareRead(path)\n        if (!bytes) return null\n        const redoStat = await fs.stat(path)\n        if (!redoStat) throw new Error(`icloud: file vanished after download at ${path}`)\n        return { bytes, version: versionOf(redoStat) }\n      }\n      const bytes = await stubAwareRead(path)\n      if (!bytes) return null\n      return { bytes, version: versionOf(stat) }\n    },\n\n    async writeBundle(vaultId, bytes, expectedVersion) {\n      // Conflict file present → refuse; caller merges.\n      const conflict = await detectConflict(vaultId)\n      if (conflict) {\n        throw new BundleVersionConflictError(\n          `iCloud conflict file detected alongside \"${vaultId}${suffix}\": \"${conflict}\". ` +\n          `Open iCloud Drive, resolve the conflict, then retry.`,\n        )\n      }\n      const path = await pathFor(vaultId)\n      const stat = await fs.stat(path)\n      const current = stat ? versionOf(stat) : null\n      if (expectedVersion !== null && current !== null && expectedVersion !== current) {\n        throw new BundleVersionConflictError(\n          `iCloud bundle version mismatch: expected ${expectedVersion}, found ${current}`,\n        )\n      }\n      await fs.writeFile(path, bytes)\n      const newStat = await fs.stat(path)\n      if (!newStat) throw new Error(`icloud: write reported success but stat failed at ${path}`)\n      return { version: versionOf(newStat) }\n    },\n\n    async deleteBundle(vaultId) {\n      const path = await pathFor(vaultId)\n      try {\n        await fs.unlink(path)\n      } catch {\n        // Idempotent\n      }\n    },\n\n    async listBundles() {\n      const entries = await fs.readdir(dir).catch(() => [] as string[])\n      const out: Array<{ vaultId: string; version: string; size: number }> = []\n      for (const entry of entries) {\n        if (!entry.endsWith(suffix) || isStub(entry)) continue\n        const vaultId = entry.slice(0, -suffix.length)\n        const stat = await fs.stat(`${dir}/${entry}`)\n        if (!stat) continue\n        out.push({ vaultId, version: versionOf(stat), size: stat.size })\n      }\n      return out\n    },\n  }\n}\n\n/**\n * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic\n * import keeps the package browser-loadable (the caller's bundler\n * prunes the Node path).\n */\nexport async function nodeFs(): Promise<ICloudFs> {\n  const fs = await import('node:fs/promises')\n  const { spawn } = await import('node:child_process')\n  return {\n    async readFile(path) {\n      try {\n        return await fs.readFile(path)\n      } catch {\n        return null\n      }\n    },\n    async writeFile(path, data) {\n      await fs.writeFile(path, data)\n    },\n    async unlink(path) {\n      await fs.unlink(path).catch(() => undefined)\n    },\n    async readdir(path) {\n      return fs.readdir(path)\n    },\n    async stat(path) {\n      try {\n        const s = await fs.stat(path)\n        return { mtimeMs: s.mtimeMs, size: s.size }\n      } catch {\n        return null\n      }\n    },\n    async triggerDownload(path) {\n      // macOS: `brctl download` forces iCloud to materialise a stub.\n      await new Promise<void>((resolve) => {\n        const child = spawn('brctl', ['download', path.replace(/\\.icloud$/, '')])\n        child.on('close', () => resolve())\n        child.on('error', () => resolve())\n      })\n    },\n  }\n}\n"],"mappings":"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","names":["bytes"]}

package/dist/index.d.cts

@@ -1,77 +0,0 @@
-import { NoydbBundleStore } from '@noy-db/hub';
-
-/**
- * **@noy-db/to-icloud** — iCloud Drive bundle store for noy-db.
- *
- * Treats each vault as a single `.noydb` bundle stored under
- * `~/Library/Mobile Documents/…` (or any user-chosen iCloud path).
- * Pair with `wrapBundleStore()` from `@noy-db/hub` to get the
- * standard six-method `NoydbStore` surface.
- *
- * ## Why a dedicated package if `to-file` "works"?
- *
- * `@noy-db/to-file` pointed at an iCloud Drive directory technically
- * works — until one of three iCloud-specific behaviors bites you:
- *
- *   1. **On-demand eviction.** iCloud may evict the file to cloud-only
- *      storage, leaving a `.icloud` stub. `readFile()` on the stub
- *      either throws ENOENT or returns stub metadata. This store
- *      detects the stub, nudges the OS to redownload (via `xattr` on
- *      macOS), and retries.
- *   2. **Conflict files.** Parallel writes from two devices create
- *      `name (device conflicted copy DATE).noydb`. This store detects
- *      those files and raises `BundleVersionConflictError`, giving the
- *      caller a chance to merge deliberately.
- *   3. **Sync-not-yet-complete writes.** A completed `writeFile()` does
- *      not mean the bytes are on Apple's servers. `ping()` reports
- *      on upload status so callers can wait before considering a
- *      write durable.
- *
- * ## Scope
- *
- * - **Node (macOS) only for v1.** Browser / iOS consumers go through
- *   CloudKit JS — a separate package will ship as `@noy-db/to-cloudkit`.
- * - **Bundle granularity** — whole vault in one file. Pair with
- *   `syncPolicy: { push: { mode: 'debounce', 30_000 } }` so every
- *   record mutation doesn't trigger a full bundle upload.
- * - **No extra auth** — iCloud syncs via the user's signed-in Apple ID;
- *   the store never sees credentials.
- *
- * @packageDocumentation
- */
-
-/** Default iCloud Drive folder name inside a user's mobile-documents tree. */
-declare const DEFAULT_FOLDER = "NoyDB";
-interface ICloudFs {
-    readFile(path: string): Promise<Uint8Array | Buffer | null>;
-    writeFile(path: string, data: Uint8Array): Promise<void>;
-    unlink(path: string): Promise<void>;
-    readdir(path: string): Promise<string[]>;
-    stat(path: string): Promise<{
-        mtimeMs: number;
-        size: number;
-    } | null>;
-    /** macOS-only: force iCloud to materialise an evicted `.icloud` stub. */
-    triggerDownload?(path: string): Promise<void>;
-}
-interface ICloudStoreOptions {
-    /** Absolute path to the iCloud Drive folder that holds bundles. */
-    readonly folder: string;
-    /** File-system facade — swap in a mock or a cross-platform shim. */
-    readonly fs: ICloudFs;
-    /** Bundle filename suffix. Default `'.noydb'`. */
-    readonly suffix?: string;
-}
-/**
- * Build a `NoydbBundleStore` over an iCloud Drive folder. Wrap with
- * `wrapBundleStore()` to consume via `createNoydb({ store })`.
- */
-declare function icloud(options: ICloudStoreOptions): NoydbBundleStore;
-/**
- * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic
- * import keeps the package browser-loadable (the caller's bundler
- * prunes the Node path).
- */
-declare function nodeFs(): Promise<ICloudFs>;
-
-export { DEFAULT_FOLDER, type ICloudFs, type ICloudStoreOptions, icloud, nodeFs };