@noy-db/to-icloud 0.2.0 → 0.3.0-pre.1

package/dist/index.d.ts

@@ -66,7 +66,7 @@ interface ICloudStoreOptions {
  * Build a `NoydbPodStore` over an iCloud Drive folder. Wrap with
  * `wrapBundleStore()` to consume via `createNoydb({ store })`.
  */
-declare function icloud(options: ICloudStoreOptions): NoydbPodStore;
+declare function toIcloud(options: ICloudStoreOptions): NoydbPodStore;
 /**
  * Wire a Node `fs/promises` implementation as an `ICloudFs`. Dynamic
  * import keeps the package browser-loadable (the caller's bundler
@@ -74,4 +74,4 @@ declare function icloud(options: ICloudStoreOptions): NoydbPodStore;
  */
 declare function nodeFs(): Promise<ICloudFs>;
 
-export { DEFAULT_FOLDER, type ICloudFs, type ICloudStoreOptions, icloud, nodeFs };
+export { DEFAULT_FOLDER, type ICloudFs, type ICloudStoreOptions, nodeFs, toIcloud };

package/dist/index.js

@@ -10,7 +10,7 @@ function isStub(name) {
 function isConflictCopy(name, expected) {
   return name.includes("'s conflicted copy") || name.includes("(conflicted copy") && name.endsWith(expected.slice(expected.lastIndexOf(".")));
 }
-function icloud(options) {
+function toIcloud(options) {
   const suffix = options.suffix ?? ".noydb";
   const dir = options.folder.replace(/\/+$/, "");
   const { fs } = options;
@@ -142,7 +142,7 @@ async function nodeFs() {
 }
 export {
   DEFAULT_FOLDER,
-  icloud,
-  nodeFs
+  nodeFs,
+  toIcloud
 };
 //# sourceMappingURL=index.js.map

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 `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":";AAyCA,SAAS,+BAA+B;AAGjC,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,SAA4C;AACjE,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 toIcloud(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,6 +1,6 @@
 {
   "name": "@noy-db/to-icloud",
-  "version": "0.2.0",
+  "version": "0.3.0-pre.1",
   "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>",
@@ -31,10 +31,10 @@
     "node": ">=22.0.0"
   },
   "peerDependencies": {
-    "@noy-db/hub": "^0.3.0"
+    "@noy-db/hub": "^0.3.0 || ^0.4.0-pre.10"
   },
   "devDependencies": {
-    "@noy-db/hub": "0.3.0",
+    "@noy-db/hub": "0.4.0-pre.10",
     "@types/node": "^22.0.0"
   },
   "keywords": [