profsynapse/nexus/nexus-mobile-compat

Nexus mobile & plugin-store safety

Nexus ships isDesktopOnly: false, so main.js runs on phones with no Node.js. The defect this skill exists to prevent has no compiler and no type behind it: a static import executes during module init, before any Platform.isDesktop check, so one import on the startup path takes the plugin down at launch on every phone — from a diff that looks unrelated.

The reachability checker below is now wired into the repo's own gate: npm run lint runs lint:obsidian (ESLint) then lint:mobile (this checker), and npm run build runs npm run lint first. A violation fails the build. Run the checker directly anyway while you work — the gate is the floor, not the loop.

Workflow

Pick the row that matches the job and follow that protocol. Do not improvise from this page; each protocol carries the steps and the checks.

1. Read the protocol the table names, in full, before editing anything.
2. Whatever the protocol, you MUST run the reachability checker before calling

the change done — it is the only guard for this defect class: ``bash node scripts/check-mobile-imports.mjs . # identical, the way the build invokes it: npm run lint:mobile ` scripts/check-mobile-imports.mjs` in the repo IS the checker — one implementation, edit it there. It was a Python script behind a launcher until 2026-08-15, when Obsidian's community scorecard failed build verification on a clean container that has Node but no Python. A build gate may only depend on what the build already needs.

It walks static imports from src/main.ts, follows no await import(), and exits non-zero when a Node built-in is reachable from init. Run --help for --trace <file> (is this module on the startup path, and via what chain) and --packages (which npm packages init loads).

1. npm run lint now runs both halves: ESLint for the store rules that are

mechanical, then the reachability checker. A green ESLint says nothing about reachability, and a green checker says nothing about the store rules — which is why the composed script runs both, and why npm run build calls it. ESLint additionally hard-errors on Node built-in and Node-dependent package imports under src/settings/components/** (issue #221): those shared UI primitives are reachable from init today, but the per-file ban holds even if the import graph shifts. The blocklists are the MOBILE_BANNED_* arrays at the top of eslint.config.mjs; widen the guard by adding a glob to that block's files.

1. NEVER treat obsidian dev:mobile on as evidence of mobile safety. It emulates

Platform.isMobile, touch and layout inside Electron, where require('fs') still resolves — this crash class cannot reproduce there. See references/init-order.md.

Map

• protocols/ the procedures above, each ending at the next one.
• references/ read on demand: init-order.md (why a platform guard below an

import is decoration, and what reachability really guarantees), plugin-store-rules.md (the store rules and which are already lint-enforced), pdfjs-in-electron.md (the worker constraint and the single sanctioned entry).

• The import-graph checker lives in the repo, not here:

scripts/check-mobile-imports.mjs. Run it; do not reimplement it as a grep — grep cannot see reachability, and this repo has known-correct hits that a grep reports as violations.

Boundaries

The full store guidance lives in docs/obsidian-plugin-guidelines.md; this skill is the part that bites in practice. Test lanes, the in-app Obsidian CLI loop and mock-versus-real questions belong to nexus-testing. Storage roots, the event store and migrations belong to nexus-storage. Release packaging belongs to nexus-release.