Skip to content

feat: experimental Termux/Android compatibility - #497

Open
PSYCH0patch wants to merge 1 commit into
tashfeenahmed:mainfrom
PSYCH0patch:feat/termux-compatibility
Open

feat: experimental Termux/Android compatibility#497
PSYCH0patch wants to merge 1 commit into
tashfeenahmed:mainfrom
PSYCH0patch:feat/termux-compatibility

Conversation

@PSYCH0patch

Copy link
Copy Markdown

Closes #308

Adds a Node.js built-in sqlite fallback so the server runs on Termux without needing better-sqlite3 native compilation or the Android NDK.

Changes

  • Move better-sqlite3 to optionalDependencies in server and desktop packages so npm install no longer fails on android platforms.
  • Add a node:sqlite adapter used when process.platform === 'android', with a SAVEPOINT-based transaction wrapper that supports nesting.
  • Default behavior on Linux/macOS/Windows/desktop is unchanged: the better-sqlite3 driver is still selected via the same factory hook, and connectDb still accepts an injected factory for tests.
  • Add test coverage for the fallback adapter, including nested transactions and rollback semantics.
  • Add docs/install/android-termux.md and a one-line README link so Android users have a supported install path.

Scope

Single concern: make the server start cleanly on Termux without touching desktop/server behavior on other platforms.

Testing

  • New test file server/src/__tests__/db/node-sqlite-fallback.test.ts verifies the node:sqlite adapter works and correctly handles nested SAVEPOINT transactions (commit + rollback semantics).
  • Full server test suite passes on non-Android platforms — behavior unchanged.

Verified end-to-end from a clean clone

Reproduced the full user flow on a fresh Termux install (Android 10+, Node LTS via nodejs-lts):

git clone -b feat/termux-compatibility https://github.com/PSYCH0patch/freellmapi.git
cd freellmapi
npm install
npm run dev

Result:

  • npm install completes in ~33s with no native compile step
  • Server boots on :3001, dashboard on :5173
  • DB initialized, migrations applied, models seeded
  • Catalog sync connects and polls normally
  • No NDK, no GYP_DEFINES, no manual rebuild required

Notes for reviewers

  • On Termux specifically, a handful of pre-existing test files that import 'better-sqlite3' directly (bypassing the adapter) can't be loaded because the package isn't installed on Android. These are development-only fixtures, not part of any runtime path, and refactoring them to use the adapter is intentionally left out of scope to keep this PR small. Happy to do that as a follow-up if you'd like.
  • optionalDependencies means desktop/server installs on Linux/macOS/Windows still get better-sqlite3 exactly as before — nothing changes for existing users.
  • Android support is labeled experimental in the docs.

Adds a Node.js built-in sqlite fallback so the server runs on Termux
without needing better-sqlite3 native compilation or the Android NDK.

Changes:
- Move better-sqlite3 to optionalDependencies in server and desktop
  packages so npm install no longer fails on android platforms.
- Add a node:sqlite adapter used when process.platform === 'android',
  with a SAVEPOINT-based transaction wrapper that supports nesting.
- Default behavior on Linux/macOS/Windows/desktop is unchanged: the
  better-sqlite3 driver is still selected via the same factory hook,
  and connectDb still accepts an injected factory for tests.
- Add test coverage for the fallback adapter, including nested
  transactions and rollback semantics.
- Add docs/install/android-termux.md and a one-line README link so
  Android users have a supported install path.

Refs tashfeenahmed#308
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs] Add Android/Termux installation guide

1 participant