mindoodb 0.0.2 → 0.0.3

package/patches/PATCHES.md

@@ -0,0 +1,111 @@
+# Patches
+
+This project uses [patch-package](https://github.com/ds300/patch-package) to fix bugs in dependencies. Patches are applied automatically on `npm install` via the `postinstall` script.
+
+All patches target the specific dependency versions listed below. After upgrading a patched dependency, verify whether the upstream fix has been merged and remove the patch if so.
+
+> **Note:** `react-native-quick-crypto` contains symlinks in its bundled `OpenSSL.xcframework`, which prevents `patch-package` from auto-generating patches. To regenerate that patch, use `git diff` manually against a clean copy of the package (see procedure below).
+
+---
+
+## react-native+0.76.9.patch
+
+**File changed:** `ReactCommon/jsc/JSCRuntime.cpp`
+
+### Problem
+
+React Native's JSC (JavaScriptCore) runtime has `JSCRuntime::createArrayBuffer()` stubbed as:
+
+```cpp
+throw std::logic_error("Not implemented");
+```
+
+This breaks any NitroModules HybridObject method that returns an `ArrayBuffer` from native to JS (e.g., `Hash.digest()` in react-native-quick-crypto). The error surfaces as:
+
+```
+Hash.digest(...): Not implemented
+```
+
+### Fix
+
+Implements `createArrayBuffer()` using the JSC C API function `JSObjectMakeArrayBufferWithBytesNoCopy`. The implementation:
+
+1. Moves the `shared_ptr<MutableBuffer>` onto the heap so it outlives the function call.
+2. Creates a JSC ArrayBuffer that points directly to the buffer's data (zero-copy).
+3. Registers a deallocator callback that deletes the shared_ptr when the JS garbage collector collects the ArrayBuffer.
+4. Cleans up the heap allocation on failure before re-throwing.
+
+### Upstream status
+
+Not yet fixed in react-native 0.76.x. The Hermes engine implements this method; only JSC is missing it.
+
+---
+
+## react-native-quick-crypto+1.0.7.patch
+
+**Files changed:**
+- `cpp/random/HybridRandom.cpp`
+- `src/random.ts`
+
+### Problem 1: NULL pointer crash in native randomFillSync (SIGSEGV)
+
+After extended runtime (~9 hours), the app crashes with a SIGSEGV in OpenSSL's `RAND_bytes` writing to address `0x0`. The crash originates from `HybridRandom::randomFillSync()` at line 42.
+
+**Root cause:** `buffer.get()->data()` can return `nullptr` when the JS ArrayBuffer reference has been invalidated. NitroModules' `JSArrayBuffer::data()` is explicitly marked `NULLABLE` and returns `nullptr` when:
+- The JS garbage collector has collected the underlying ArrayBuffer
+- WASM memory growth has detached the ArrayBuffer
+- The `BorrowingReference` to the JS object is no longer valid
+
+The native code had **no null check** before passing the pointer to `RAND_bytes()`.
+
+**Fix (HybridRandom.cpp):** Added a null check on the data pointer before calling `RAND_bytes`. If null, throws a descriptive `std::runtime_error` that surfaces as a catchable JS exception instead of a fatal SIGSEGV.
+
+### Problem 2: WASM memory corruption from TypedArray view handling
+
+The original `randomFillSync` TypeScript implementation calls `abvToArrayBuffer(buffer)` which extracts the underlying `.buffer` property from TypedArray views. This **discards the view's `byteOffset` and `byteLength`**, using the full underlying ArrayBuffer's `byteLength` instead.
+
+When automerge's WASM module calls `crypto.getRandomValues(wasmMemoryView)`:
+- The TypedArray's `.buffer` is `WebAssembly.Memory.buffer` (the entire WASM linear memory, potentially megabytes)
+- `abvToArrayBuffer()` returns this full buffer
+- `size ?? buffer.byteLength` resolves to the entire WASM memory size
+- The native side writes random bytes to the **entire WASM linear memory**, destroying the heap, stack, and all data
+
+This causes automerge to crash with `RuntimeError: Out of bounds memory access` on the next WASM allocation (e.g., `dlmalloc::malloc` during `AutoCommit::new`).
+
+> This bug exists in the **unpatched original code** as well, not just our patch. It is masked when WASM rarely calls `getRandomValues`, but is triggered reliably when automerge's Rust code needs random bytes for HashMap seeding.
+
+**Fix (random.ts):** Rewrote `randomFillSync` to:
+
+1. **Preserve TypedArray view info** before extracting the underlying buffer: reads `buffer.byteOffset` and `buffer.byteLength` from the original TypedArray, so we know exactly which portion of the underlying buffer to fill.
+2. **Create an owned ArrayBuffer** of just the fill size (not the entire underlying buffer). This ensures the native side always receives a valid, correctly-sized buffer that won't be detached by WASM memory growth or GC.
+3. **Copy random bytes back** to the exact correct position in the original buffer using `viewByteOffset + offset`.
+
+### Upstream status
+
+Neither fix has been submitted upstream to react-native-quick-crypto.
+
+---
+
+## Regenerating the quick-crypto patch
+
+Because `patch-package` cannot handle symlinks in `OpenSSL.xcframework`, use this manual procedure:
+
+```bash
+# 1. Get a clean copy of the package
+npm pack react-native-quick-crypto@1.0.7 --pack-destination /tmp
+mkdir -p /tmp/qc-orig && tar -xzf /tmp/react-native-quick-crypto-1.0.7.tgz -C /tmp/qc-orig
+
+# 2. Set up a temp git repo for diffing
+mkdir /tmp/qc-git && cd /tmp/qc-git && git init
+mkdir -p node_modules/react-native-quick-crypto/{cpp/random,src}
+cp /tmp/qc-orig/package/cpp/random/HybridRandom.cpp node_modules/react-native-quick-crypto/cpp/random/
+cp /tmp/qc-orig/package/src/random.ts node_modules/react-native-quick-crypto/src/
+git add . && git commit -m "original"
+
+# 3. Copy in your modified files
+cp <project>/node_modules/react-native-quick-crypto/cpp/random/HybridRandom.cpp node_modules/react-native-quick-crypto/cpp/random/
+cp <project>/node_modules/react-native-quick-crypto/src/random.ts node_modules/react-native-quick-crypto/src/
+
+# 4. Generate the patch
+git diff --no-color > <project>/patches/react-native-quick-crypto+1.0.7.patch
+```

package/patches/react-native+0.76.9.patch

@@ -0,0 +1,34 @@
+diff --git a/node_modules/react-native/ReactCommon/jsc/JSCRuntime.cpp b/node_modules/react-native/ReactCommon/jsc/JSCRuntime.cpp
+index e63260a..b806880 100644
+--- a/node_modules/react-native/ReactCommon/jsc/JSCRuntime.cpp
++++ b/node_modules/react-native/ReactCommon/jsc/JSCRuntime.cpp
+@@ -1120,7 +1120,28 @@ jsi::Array JSCRuntime::createArray(size_t length) {
+ 
+ jsi::ArrayBuffer JSCRuntime::createArrayBuffer(
+     std::shared_ptr<jsi::MutableBuffer> buffer) {
+-  throw std::logic_error("Not implemented");
++  JSValueRef exc = nullptr;
++  // Move the shared_ptr into heap storage so it survives until JSC deallocates
++  // the ArrayBuffer. The deallocator callback deletes it when the JS GC
++  // collects the ArrayBuffer object.
++  auto* pointerHolder =
++      new std::shared_ptr<jsi::MutableBuffer>(std::move(buffer));
++  JSObjectRef obj = JSObjectMakeArrayBufferWithBytesNoCopy(
++      ctx_,
++      (*pointerHolder)->data(),
++      (*pointerHolder)->size(),
++      [](void* /*bytes*/, void* deallocatorContext) {
++        delete static_cast<std::shared_ptr<jsi::MutableBuffer>*>(
++            deallocatorContext);
++      },
++      pointerHolder,
++      &exc);
++  if (!obj) {
++    // Clean up on failure before throwing
++    delete pointerHolder;
++    checkException(exc);
++  }
++  return createObject(obj).getArrayBuffer(*this);
+ }
+ 
+ size_t JSCRuntime::size(const jsi::Array& arr) {

package/patches/react-native-quick-crypto+1.0.7.patch

@@ -0,0 +1,42 @@
+diff --git a/node_modules/react-native-quick-crypto/cpp/random/HybridRandom.cpp b/node_modules/react-native-quick-crypto/cpp/random/HybridRandom.cpp
+index b1a132c..e48eb06 100644
+--- a/node_modules/react-native-quick-crypto/cpp/random/HybridRandom.cpp
++++ b/node_modules/react-native-quick-crypto/cpp/random/HybridRandom.cpp
+@@ -39,6 +39,9 @@ std::shared_ptr<ArrayBuffer> HybridRandom::randomFillSync(const std::shared_ptr<
+   size_t size = checkSize(dSize);
+   size_t offset = checkOffset(dSize, dOffset);
+   uint8_t* data = buffer.get()->data();
++  if (!data) {
++    throw std::runtime_error("randomFillSync: ArrayBuffer data pointer is null (buffer may have been detached or garbage collected)");
++  }
+   if (RAND_bytes(data + offset, (int)size) != 1) {
+     throw std::runtime_error("error calling RAND_bytes: " + std::to_string(ERR_get_error()));
+   }
+diff --git a/node_modules/react-native-quick-crypto/src/random.ts b/node_modules/react-native-quick-crypto/src/random.ts
+index 4066c5a..753da81 100644
+--- a/node_modules/react-native-quick-crypto/src/random.ts
++++ b/node_modules/react-native-quick-crypto/src/random.ts
+@@ -73,9 +73,20 @@ export function randomFillSync<T extends ABV>(
+ 
+ export function randomFillSync(buffer: ABV, offset: number = 0, size?: number) {
+   getNative();
+-  buffer = abvToArrayBuffer(buffer);
+-  const res = random.randomFillSync(buffer, offset, size ?? buffer.byteLength);
+-  buffer = res;
++  // Preserve the view's byte range before extracting the underlying ArrayBuffer.
++  // This is critical when buffer is a TypedArray view into a larger buffer
++  // (e.g. WebAssembly.Memory) — we must only fill the view's portion, not the
++  // entire underlying buffer.
++  const viewByteOffset = ArrayBuffer.isView(buffer) ? buffer.byteOffset : 0;
++  const viewByteLength = ArrayBuffer.isView(buffer) ? buffer.byteLength : buffer.byteLength;
++  const fillSize = size ?? viewByteLength;
++  // Create an owned ArrayBuffer so native code is not dependent on the original
++  // buffer reference staying valid (WASM memory growth can detach ArrayBuffers).
++  const owned = new ArrayBuffer(fillSize);
++  const res = random.randomFillSync(owned, 0, fillSize);
++  // Copy the random bytes back into the caller's buffer at the correct position
++  const src = abvToArrayBuffer(buffer);
++  new Uint8Array(src, viewByteOffset + offset, fillSize).set(new Uint8Array(res));
+   return buffer;
+ }
+ 

package/scripts/cli.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+'use strict';
+
+const command = process.argv[2];
+
+switch (command) {
+  case 'setup-react-native':
+    require('./setup-react-native.js');
+    break;
+  default:
+    console.log('MindooDB CLI');
+    console.log('');
+    console.log('Usage:');
+    console.log('  npx mindoodb setup-react-native   Set up MindooDB for React Native / Expo');
+    console.log('');
+    if (command) {
+      console.error(`Unknown command: ${command}`);
+      process.exit(1);
+    }
+    break;
+}

package/scripts/setup-react-native.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const readline = require('readline');
+
+// Resolve paths
+const projectDir = process.cwd();
+const mindoodbDir = path.dirname(__dirname); // node_modules/mindoodb
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function copyFileWithPrompt(src, dest, description) {
+  if (fs.existsSync(dest)) {
+    console.log(`  [exists] ${path.relative(projectDir, dest)} (skipped)`);
+    return false;
+  }
+  const destDir = path.dirname(dest);
+  if (!destDir) return false;
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log(`  [created] ${path.relative(projectDir, dest)}`);
+  return true;
+}
+
+async function main() {
+  console.log('');
+  console.log('MindooDB - React Native Setup');
+  console.log('=============================');
+  console.log('');
+
+  // Verify we're in a project directory
+  const projectPkgPath = path.join(projectDir, 'package.json');
+  if (!fs.existsSync(projectPkgPath)) {
+    console.error('Error: No package.json found in current directory.');
+    console.error('Run this command from your React Native project root.');
+    process.exit(1);
+  }
+
+  const projectPkg = JSON.parse(fs.readFileSync(projectPkgPath, 'utf8'));
+
+  // ── Step 1: Copy patches ──────────────────────────────────────────────
+  console.log('Step 1: Copying patches...');
+  const patchesDir = path.join(mindoodbDir, 'patches');
+  const destPatchesDir = path.join(projectDir, 'patches');
+
+  if (fs.existsSync(patchesDir)) {
+    fs.mkdirSync(destPatchesDir, { recursive: true });
+    const patchFiles = fs.readdirSync(patchesDir).filter(f => f.endsWith('.patch') || f.endsWith('.md'));
+    for (const file of patchFiles) {
+      copyFileWithPrompt(
+        path.join(patchesDir, file),
+        path.join(destPatchesDir, file),
+        file
+      );
+    }
+  } else {
+    console.log('  Warning: patches directory not found in mindoodb package.');
+    console.log('  You may need to copy patches manually from the mindoodb repository.');
+  }
+  console.log('');
+
+  // ── Step 2: Install patch-package ─────────────────────────────────────
+  console.log('Step 2: Checking patch-package...');
+  const hasPatchPackage = !!(projectPkg.devDependencies?.['patch-package'] || projectPkg.dependencies?.['patch-package']);
+  if (!hasPatchPackage) {
+    const answer = await ask('  Install patch-package as a devDependency? (Y/n) ');
+    if (answer !== 'n') {
+      console.log('  Installing patch-package...');
+      try {
+        execSync('npm install --save-dev patch-package', { cwd: projectDir, stdio: 'inherit' });
+      } catch (e) {
+        console.error('  Failed to install patch-package. Please install it manually:');
+        console.error('    npm install --save-dev patch-package');
+      }
+    }
+  } else {
+    console.log('  patch-package already installed.');
+  }
+  console.log('');
+
+  // ── Step 3: Add postinstall script ────────────────────────────────────
+  console.log('Step 3: Checking postinstall script...');
+  // Re-read package.json in case npm install changed it
+  const updatedPkg = JSON.parse(fs.readFileSync(projectPkgPath, 'utf8'));
+  if (!updatedPkg.scripts) updatedPkg.scripts = {};
+  if (!updatedPkg.scripts.postinstall) {
+    updatedPkg.scripts.postinstall = 'patch-package';
+    fs.writeFileSync(projectPkgPath, JSON.stringify(updatedPkg, null, 2) + '\n');
+    console.log('  Added "postinstall": "patch-package" to package.json');
+  } else if (!updatedPkg.scripts.postinstall.includes('patch-package')) {
+    console.log(`  Warning: postinstall script exists but does not include patch-package:`);
+    console.log(`    "${updatedPkg.scripts.postinstall}"`);
+    console.log('  Please add "patch-package" to your postinstall script manually.');
+  } else {
+    console.log('  postinstall script already configured.');
+  }
+  console.log('');
+
+  // ── Step 4: Install dependencies ──────────────────────────────────────
+  console.log('Step 4: Required dependencies...');
+  const requiredDeps = [
+    'react-native-automerge-generated',
+    'react-native-quick-crypto',
+    'react-native-nitro-modules',
+    'expo-standard-web-crypto',
+    'expo-crypto',
+    'text-encoding',
+    'react-native-url-polyfill',
+    'punycode',
+    'node-forge',
+    'tweetnacl',
+    '@babel/runtime',
+  ];
+
+  const missingDeps = requiredDeps.filter(dep => {
+    return !updatedPkg.dependencies?.[dep] && !updatedPkg.devDependencies?.[dep];
+  });
+
+  if (missingDeps.length > 0) {
+    console.log('  The following dependencies are required but not installed:');
+    for (const dep of missingDeps) {
+      console.log(`    - ${dep}`);
+    }
+    console.log('');
+    const answer = await ask('  Install these dependencies? (Y/n) ');
+    if (answer !== 'n') {
+      console.log('  Installing...');
+      try {
+        execSync(`npm install ${missingDeps.join(' ')}`, { cwd: projectDir, stdio: 'inherit' });
+      } catch (e) {
+        console.error('  Some dependencies failed to install. Please install them manually:');
+        console.error(`    npm install ${missingDeps.join(' ')}`);
+      }
+    }
+  } else {
+    console.log('  All required dependencies already installed.');
+  }
+  console.log('');
+
+  // ── Step 5: Copy template files ───────────────────────────────────────
+  console.log('Step 5: Copying starter files...');
+  const templatesDir = path.join(mindoodbDir, 'templates', 'reactnative');
+  if (fs.existsSync(templatesDir)) {
+    copyFileWithPrompt(
+      path.join(templatesDir, 'mindoodb-polyfills.js'),
+      path.join(projectDir, 'mindoodb-polyfills.js'),
+      'polyfills file'
+    );
+  } else {
+    console.log('  Warning: templates directory not found in mindoodb package.');
+  }
+  console.log('');
+
+  // ── Step 6: Check app.json ────────────────────────────────────────────
+  console.log('Step 6: Checking app.json...');
+  const appJsonPath = path.join(projectDir, 'app.json');
+  if (fs.existsSync(appJsonPath)) {
+    try {
+      const appJson = JSON.parse(fs.readFileSync(appJsonPath, 'utf8'));
+      const iosEngine = appJson?.expo?.ios?.jsEngine;
+      if (iosEngine === 'jsc') {
+        console.log('  ios.jsEngine is set to "jsc".');
+        console.log('  This is supported, and the bundled react-native patch addresses JSC ArrayBuffer issues.');
+      } else {
+        console.log('  Hermes (default) is recommended and works with native Automerge.');
+      }
+    } catch (e) {
+      console.log('  Could not parse app.json. Ensure your Expo app config is valid.');
+    }
+  } else {
+    console.log('  No app.json found. If using Expo, this is expected only in unusual project layouts.');
+  }
+  console.log('');
+
+  // ── Step 7: Print Metro config snippet ────────────────────────────────
+  console.log('Step 7: Metro configuration');
+  console.log('');
+  console.log('  Add the following to your metro.config.js:');
+  console.log('');
+  console.log('  ──────────────────────────────────────────────────');
+  const snippetPath = path.join(templatesDir, 'metro.config.snippet.js');
+  if (fs.existsSync(snippetPath)) {
+    const snippet = fs.readFileSync(snippetPath, 'utf8');
+    for (const line of snippet.split('\n')) {
+      console.log(`  ${line}`);
+    }
+  } else {
+    console.log('  // See docs/reactnative.md for Metro configuration');
+  }
+  console.log('  ──────────────────────────────────────────────────');
+  console.log('');
+
+  // ── Summary ───────────────────────────────────────────────────────────
+  console.log('');
+  console.log('Setup complete! Next steps:');
+  console.log('');
+  console.log('  1. Add `import "./mindoodb-polyfills";` at the very top of your entry point (index.js)');
+  console.log('  2. Update your metro.config.js with the snippet above');
+  console.log('  3. Initialize native Automerge in your entry point:');
+  console.log('       import { UseApi } from "@automerge/automerge/slim";');
+  console.log('       import { nativeApi } from "react-native-automerge-generated";');
+  console.log('       UseApi(nativeApi);');
+  console.log('  4. Run `npx patch-package` to apply the patches');
+  console.log('  5. Rebuild your native app (expo prebuild --clean && expo run:ios)');
+  console.log('');
+  console.log('  For a complete working example, see the template files:');
+  console.log(`    ${path.relative(projectDir, path.join(mindoodbDir, 'templates', 'reactnative'))}/`);
+  console.log('');
+  console.log('  Full documentation:');
+  console.log(`    ${path.relative(projectDir, path.join(mindoodbDir, 'docs', 'reactnative.md'))}`);
+  console.log('');
+}
+
+main().catch(err => {
+  console.error('Setup failed:', err.message);
+  process.exit(1);
+});