chore: add yarn start:android-usb for local USB device testing

scripts/AGENTS.md

@@ -4,7 +4,7 @@ These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then
 
 - Keep scripts non-interactive and idempotent. Print the command, URL, branch, or path being acted on so failures are diagnosable.
 - Use repo-relative paths and environment variables instead of user-specific absolute paths.
-- For dev-server helpers, default to `http://5chan.localhost:1355` and respect the existing `PORTLESS=0` fallback instead of hard-coding alternate ports.
+- For dev-server helpers, default to `http://5chan.localhost:1355` and respect the existing `PORTLESS=0` fallback instead of hard-coding alternate ports. For USB Android preview, `scripts/start-android-usb.mjs` mirrors bitsocial-web: `adb reverse` plus Vite on `127.0.0.1` so the device opens `http://localhost:<port>`.
 - Keep shell helpers thin. When logic becomes stateful or cross-platform, prefer a Node script.
 - Git and worktree helpers must validate input and default to safe operations.
 - If a helper deletes local branches automatically, document the exact eligibility checks and keep the behavior conservative.

scripts/dev-server-utils.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const repoRoot = path.resolve(__dirname, '..');
+export const isWindows = process.platform === 'win32';
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port);
+  });
+}
+
+export async function resolvePort(requestedPort) {
+  let port = requestedPort;
+
+  while (!(await checkPort(port))) {
+    port += 1;
+  }
+
+  return port;
+}
+
+export function startVite(host, port) {
+  const child = spawn('corepack', ['yarn', 'exec', 'vite', '--host', host, '--port', String(port), '--strictPort'], {
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      PORTLESS: '0',
+    },
+    stdio: 'inherit',
+  });
+
+  const forwardSignal = (signal) => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  };
+
+  const onSigint = () => forwardSignal('SIGINT');
+  const onSigterm = () => forwardSignal('SIGTERM');
+
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+
+  child.on('exit', (code, signal) => {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+
+    process.exit(code ?? 0);
+  });
+
+  return child;
+}

scripts/start-android-usb.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { isWindows, repoRoot, resolvePort, startVite } from './dev-server-utils.mjs';
+
+const adbBin = isWindows ? 'adb.exe' : 'adb';
+const host = '127.0.0.1';
+const requestedPort = Number(process.env.ANDROID_USB_PORT || 1355);
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function runPrestart() {
+  const pre = spawnSync('corepack', ['yarn', 'run', 'prestart'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (pre.status !== 0) {
+    fail(`prestart failed with exit code ${pre.status ?? 'unknown'}`);
+  }
+}
+
+function getReadyDevices() {
+  const adbDevices = spawnSync(adbBin, ['devices'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+
+  if (adbDevices.error) {
+    fail('ADB not found. Install Android platform-tools, connect the phone over USB, and enable USB debugging.');
+  }
+
+  if (adbDevices.status !== 0) {
+    fail(`ADB check failed: ${adbDevices.stderr.trim() || adbDevices.stdout.trim() || 'unknown error'}`);
+  }
+
+  const devices = adbDevices.stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('List of devices attached'));
+
+  const readyDevices = devices.filter((line) => line.endsWith('\tdevice')).map((line) => line.split('\t')[0]);
+
+  if (readyDevices.length === 0) {
+    const detail = devices.length > 0 ? ` Detected states: ${devices.join(', ')}` : '';
+    fail(`No Android device is ready over USB.${detail} Connect the phone, unlock it, trust the computer, and enable USB debugging.`);
+  }
+
+  return readyDevices;
+}
+
+function reversePorts(devices, port) {
+  for (const serial of devices) {
+    const adbReverse = spawnSync(adbBin, ['-s', serial, 'reverse', `tcp:${port}`, `tcp:${port}`], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+
+    if (adbReverse.status !== 0) {
+      fail(`ADB reverse failed for ${serial}: ${adbReverse.stderr.trim() || adbReverse.stdout.trim() || 'unknown error'}`);
+    }
+  }
+}
+
+runPrestart();
+
+const devices = getReadyDevices();
+const port = await resolvePort(requestedPort);
+
+reversePorts(devices, port);
+
+console.log('');
+console.log(`Starting Android USB preview from ${repoRoot}`);
+console.log(`Host URL: http://${host}:${port}`);
+if (port !== requestedPort) {
+  console.log(`Preferred port ${requestedPort} is busy, so this run will use ${port}.`);
+}
+console.log(`ADB reverse is active for: ${devices.join(', ')}`);
+console.log(`Open http://localhost:${port} in Chrome on the Android device.`);
+console.log('');
+
+startVite(host, port);