@oxy.so/doctor 1.2.0 → 1.4.0

package/README.md

@@ -32,7 +32,34 @@ gated on it, red at once; each app still has to upgrade inside the window.
 Duplicate locked versions and a missing lockfile are always errors.
 Operational failures use status 2. Default mode is informational.
 
+It also checks that every app (a manifest on `@oxy.so/services` and on `expo`
+or `react-native`) declares each REQUIRED native peer of the services it has
+installed, an **error** otherwise (`undeclared-native-peer`, with the
+`npx expo install …` line). Expo's autolinking skips optional peers and an
+undeclared native module installs at whatever version the package manager
+picks: an Android release without `expo-crypto` built, then had no CSPRNG and
+no sign-in. The check reads the installed `@oxy.so/services` manifest, so run it
+after `bun install`; a manifest whose services is not installed is listed as
+unverified (`nativePeersUnverified` in `--json`), never passed.
+
 Use Renovate with a shared organisation preset for grouped, reviewable updates.
 Require normal tests and typecheck before merging; never use `latest` ranges or
 mutate dependencies during application startup or CI. Renovate proposes
 changes; Doctor detects drift and duplicate installations.
+
+## Android emulator preflight
+
+`oxy-emulator-preflight --serial emulator-5554` checks that the explicitly
+selected serial occurs exactly once as an online device in `adb devices -l`,
+then asks its emulator console for the AVD name. It prints only the serial on
+success and exits nonzero on invalid input, offline or ambiguous devices, an
+unavailable ADB, or a missing AVD response. It never starts an emulator or runs
+shell, installation, clearing, or uninstallation commands on a device.
+
+The caller must carry the returned serial into every subsequent command, for
+example using `adb -s "$serial" ...`; never rely on ADB's default selection.
+Run the preflight immediately before the operation and fail on errors. This is a
+read-only selection check, not an atomic device lock: devices can disconnect or
+change between commands. It does not prove the AVD is disposable, has no user
+data, or is isolated from production networks. Those are separate prerequisites
+for an isolated mobile test.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/doctor",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Read-only health checks for Oxy ecosystem repositories",
   "repository": {
     "type": "git",
@@ -9,7 +9,8 @@
   },
   "type": "module",
   "bin": {
-    "oxy-doctor": "./src/cli.mjs"
+    "oxy-doctor": "./src/cli.mjs",
+    "oxy-emulator-preflight": "./src/emulator-preflight.mjs"
   },
   "exports": {
     ".": "./src/checks.mjs"
@@ -19,8 +20,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun test tests",
-    "prepublishOnly": "bun run test"
+    "test": "bun test tests"
   },
   "publishConfig": {
     "access": "public"

package/src/checks.mjs

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
 export const FIRST_PARTY_SCOPES = ['@oxy.so/'];
@@ -155,6 +155,76 @@ function catalogEntries(rootManifest) {
   return rows;
 }
 
+/** The SDK whose native peers an app has to declare itself. */
+export const NATIVE_PEER_HOST = '@oxy.so/services';
+
+/** The installed directory of `name`, found the way Node and Metro walk node_modules. */
+function installedPackageDir(name, from) {
+  let directory = from;
+  while (true) {
+    const candidate = join(directory, 'node_modules', name);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+    const parent = dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+/** Ships native code autolinking must link: the markers Expo and the React Native CLI read. */
+export function isNativeModulePackage(directory) {
+  return (
+    existsSync(join(directory, 'expo-module.config.json')) ||
+    existsSync(join(directory, 'react-native.config.js')) ||
+    existsSync(join(directory, 'android')) ||
+    existsSync(join(directory, 'ios')) ||
+    readdirSync(directory).some((entry) => entry.endsWith('.podspec'))
+  );
+}
+
+/**
+ * Required native peers of `@oxy.so/services` that an app (a manifest on
+ * services and on `expo` or `react-native`) does not declare. Expo's autolinking skips OPTIONAL peers, and an undeclared native
+ * module is installed at whatever version the package manager picks rather than
+ * the build `expo install` pins for the app's SDK; `expo-crypto` missing from
+ * Allo's release APK broke the CSPRNG and sign-in. Reads the INSTALLED services
+ * manifest, so it needs `bun install` first; without one the manifest is
+ * reported as unverified rather than passed.
+ *
+ * @returns {Promise<{ finding?: object, unverified?: string }>}
+ */
+export async function nativePeerCheck(root, manifestPath, manifest) {
+  const declared = { ...manifest.dependencies, ...manifest.devDependencies };
+  // Only an APP is autolinked: a manifest on services that is no Expo / React
+  // Native project (a monorepo root holding it for hoisting, a library) is not.
+  if (!(NATIVE_PEER_HOST in declared) || !('expo' in declared || 'react-native' in declared))
+    return {};
+  const relative = manifestPath.slice(root.length + 1);
+  const servicesDir = installedPackageDir(NATIVE_PEER_HOST, dirname(manifestPath));
+  if (!servicesDir) return { unverified: relative };
+  const services = JSON.parse(await readFile(join(servicesDir, 'package.json'), 'utf8'));
+  const meta = services.peerDependenciesMeta ?? {};
+  const missing = Object.keys(services.peerDependencies ?? {})
+    .filter((name) => meta[name]?.optional !== true && !(name in declared))
+    .filter((name) => {
+      const directory = installedPackageDir(name, servicesDir);
+      // Not installed at all: a required peer is missing outright.
+      return directory === null || isNativeModulePackage(directory);
+    })
+    .sort();
+  if (missing.length === 0) return {};
+  return {
+    finding: {
+      severity: 'error',
+      code: 'undeclared-native-peer',
+      package: NATIVE_PEER_HOST,
+      version: services.version,
+      manifest: relative,
+      missing,
+      message: `${relative} uses ${NATIVE_PEER_HOST} ${services.version} but does not declare its required native peer${missing.length === 1 ? '' : 's'} ${missing.join(', ')}; run \`npx expo install ${missing.join(' ')}\` in ${dirname(relative) || '.'}`,
+    },
+  };
+}
+
 /**
  * @param {string} root
  * @param {(name: string) => Promise<{ version: string, publishedAt: string }>} fetchLatest
@@ -168,6 +238,7 @@ export async function inspectRepository(
   const rootManifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
   const manifestPaths = await collectManifests(root, rootManifest);
   const usages = new Map();
+  const findings = [];
   for (const { section, name, range } of catalogEntries(rootManifest)) {
     if (!isFirstPartyPackage(name)) continue;
     const rows = usages.get(name) ?? [];
@@ -195,9 +266,15 @@ export async function inspectRepository(
       }
     }
   }
+  const unverified = [];
+  for (const path of manifestPaths) {
+    const manifest = JSON.parse(await readFile(path, 'utf8'));
+    const result = await nativePeerCheck(root, path, manifest);
+    if (result.finding) findings.push(result.finding);
+    if (result.unverified) unverified.push(result.unverified);
+  }
   const lockPath = join(root, 'bun.lock');
   const lockfile = existsSync(lockPath) ? await readFile(lockPath, 'utf8') : null;
-  const findings = [];
   if (!lockfile)
     findings.push({ severity: 'error', code: 'missing-lockfile', message: 'bun.lock is missing' });
   await Promise.all(
@@ -244,7 +321,13 @@ export async function inspectRepository(
       }
     }),
   );
-  return { root, manifests: manifestPaths.length, packages: usages.size, findings };
+  return {
+    root,
+    manifests: manifestPaths.length,
+    packages: usages.size,
+    findings,
+    nativePeersUnverified: unverified,
+  };
 }
 
 /** The `latest` dist-tag of `name` and when that version was published. */

package/src/cli.mjs

@@ -31,6 +31,10 @@ try {
       `Oxy Doctor: ${report.packages} first-party packages across ${report.manifests} manifests`,
     );
     if (report.findings.length === 0) console.log('✓ No dependency-health findings');
+    for (const manifest of report.nativePeersUnverified)
+      console.log(
+        `? ${manifest}: @oxy.so/services is not installed, so its native peers were not checked (run bun install first)`,
+      );
     for (const finding of report.findings)
       console.log(`${finding.severity === 'error' ? '✗' : '!'} ${finding.message}`);
   }

package/src/emulator-preflight.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+
+const usage = 'Usage: oxy-emulator-preflight --serial emulator-<port>';
+const args = process.argv.slice(2);
+if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+  console.log(usage);
+  process.exit(0);
+}
+
+function fail(message) {
+  console.error(`Emulator preflight failed: ${message}`);
+  process.exit(1);
+}
+
+if (args.length !== 2 || args[0] !== '--serial' || !/^emulator-\d{4,5}$/.test(args[1] ?? '')) {
+  fail(`an explicit emulator serial is required. ${usage}`);
+}
+const serial = args[1];
+
+function adb(...arguments_) {
+  const result = spawnSync('adb', arguments_, {
+    encoding: 'utf8',
+    timeout: 10_000,
+    maxBuffer: 1_000_000,
+  });
+  if (result.error || result.status !== 0) {
+    fail(`adb ${arguments_[0]} failed or timed out`);
+  }
+  return result.stdout;
+}
+
+const lines = adb('devices', '-l').split(/\r?\n/);
+if (!lines.some((line) => line.trim() === 'List of devices attached')) {
+  fail('unrecognized adb devices output');
+}
+const matches = lines
+  .map((line) => line.trim().split(/\s+/))
+  .filter(([candidate]) => candidate === serial);
+if (matches.length !== 1 || matches[0][1] !== 'device') {
+  fail('the selected emulator must appear exactly once and be online');
+}
+
+// A serial-shaped name alone is not proof that adb is talking to an emulator.
+// The console command is read-only and must return one AVD name followed by OK.
+const reply = adb('-s', serial, 'emu', 'avd', 'name').trim().split(/\r?\n/);
+if (reply.length !== 2 || !/^[A-Za-z0-9_.-]+$/.test(reply[0]) || reply[1] !== 'OK') {
+  fail('the selected device did not identify itself as an Android AVD');
+}
+console.log(serial);