@mickeypause/react-native-preview-cli 2.0.0

package/README.md

@@ -0,0 +1,14 @@
+# @mickeypause/react-native-preview-cli
+
+CLI bridge for `@mickeypause/react-native-preview`.
+
+```bash
+preview start --ios
+preview list
+preview select PreviewCard
+preview clear
+```
+
+`start` supports Expo projects on iOS simulators and Android emulators. It writes `.react-native-preview/session.json`, owns the local WebSocket bridge, and passes the selected endpoint through `EXPO_PUBLIC_REACT_NATIVE_PREVIEW_BRIDGE_URL`.
+
+The published `bin/preview.js` file is the executable npm CLI entrypoint. It is intentionally a thin launcher over the compiled `dist` API and is kept executable so npm can expose the `preview` command.

package/bin/preview.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+const {
+  requestSnapshot,
+  resolvePreview,
+  sendCommand,
+  startPreviewSession,
+} = require('../dist/index.js');
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args.shift();
+  const value = command === 'select' ? args.shift() : undefined;
+  if (command === 'start') {
+    const platform = args.includes('--ios') ? 'ios' : args.includes('--android') ? 'android' : null;
+    if (!platform) throw new Error('Choose a platform: preview start --ios or preview start --android');
+    const { session, server, app } = await startPreviewSession({ platform });
+    console.log(`[react-native-preview] bridge listening at ${session.url}`);
+    console.log(`[react-native-preview] app endpoint ${session.appUrl}`);
+    const cleanup = async () => {
+      await server.close();
+      app.kill('SIGTERM');
+      process.exit(0);
+    };
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    await new Promise((resolve) => app.once('exit', resolve));
+    await server.close();
+    return;
+  }
+  if (command === 'list') {
+    const snapshot = await requestSnapshot();
+    for (const preview of snapshot.previews) {
+      const selected = preview.id === snapshot.selectedId ? '*' : ' ';
+      console.log(`${selected} ${preview.name} (${preview.id})\n    ${preview.source}:${preview.line}:${preview.column}`);
+    }
+    return;
+  }
+  if (command === 'select') {
+    if (!value) throw new Error('Usage: preview select <name-or-id>');
+    const snapshot = await requestSnapshot();
+    await sendCommand({ type: 'select', id: resolvePreview(snapshot, value) });
+    return;
+  }
+  if (command === 'clear') {
+    await sendCommand({ type: 'clear' });
+    return;
+  }
+  throw new Error('Usage: preview start --ios|--android, preview list, preview select <name-or-id>, preview clear');
+}
+
+main().catch((error) => {
+  console.error(`[react-native-preview] ${error.message}`);
+  process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import type { BridgeMessage, PreviewSnapshot } from './protocol';
+export declare function requestSnapshot(url?: string): Promise<PreviewSnapshot>;
+export declare function sendCommand(message: Extract<BridgeMessage, {
+    type: 'select' | 'clear';
+}>, url?: string): Promise<void>;
+export declare function resolvePreview(snapshot: PreviewSnapshot, selector: string): string;

package/dist/client.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestSnapshot = requestSnapshot;
+exports.sendCommand = sendCommand;
+exports.resolvePreview = resolvePreview;
+const ws_1 = __importDefault(require("ws"));
+const server_1 = require("./server");
+function requestSnapshot(url = (0, server_1.readSession)().url) {
+    return new Promise((resolve, reject) => {
+        const socket = new ws_1.default(url);
+        const timeout = setTimeout(() => {
+            socket.close();
+            reject(new Error('Timed out waiting for the preview registry.'));
+        }, 3000);
+        socket.on('message', (data) => {
+            const message = JSON.parse(String(data));
+            if (message.type === 'registry-snapshot' || message.type === 'registry-updated') {
+                clearTimeout(timeout);
+                socket.close();
+                resolve(message.snapshot);
+            }
+        });
+        socket.on('error', (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
+function sendCommand(message, url = (0, server_1.readSession)().url) {
+    return new Promise((resolve, reject) => {
+        const socket = new ws_1.default(url);
+        socket.once('open', () => {
+            socket.send(JSON.stringify(message));
+            setTimeout(() => {
+                socket.close();
+                resolve();
+            }, 50);
+        });
+        socket.once('error', reject);
+    });
+}
+function resolvePreview(snapshot, selector) {
+    const byId = snapshot.previews.find((preview) => preview.id === selector);
+    if (byId)
+        return byId.id;
+    const matches = snapshot.previews.filter((preview) => preview.name === selector);
+    if (matches.length === 0)
+        throw new Error(`Preview not found: ${selector}`);
+    if (matches.length > 1) {
+        throw new Error(`Preview name is ambiguous: ${selector}. Use one of: ${matches.map((preview) => preview.id).join(', ')}`);
+    }
+    return matches[0].id;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './protocol';
+export { DEFAULT_PORT, SESSION_FILE, PreviewBridgeServer, findAvailablePort, hostForPlatform, isExpoProject, readSession, startPreviewSession, } from './server';
+export { requestSnapshot, resolvePreview, sendCommand } from './client';

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendCommand = exports.resolvePreview = exports.requestSnapshot = exports.startPreviewSession = exports.readSession = exports.isExpoProject = exports.hostForPlatform = exports.findAvailablePort = exports.PreviewBridgeServer = exports.SESSION_FILE = exports.DEFAULT_PORT = void 0;
+__exportStar(require("./protocol"), exports);
+var server_1 = require("./server");
+Object.defineProperty(exports, "DEFAULT_PORT", { enumerable: true, get: function () { return server_1.DEFAULT_PORT; } });
+Object.defineProperty(exports, "SESSION_FILE", { enumerable: true, get: function () { return server_1.SESSION_FILE; } });
+Object.defineProperty(exports, "PreviewBridgeServer", { enumerable: true, get: function () { return server_1.PreviewBridgeServer; } });
+Object.defineProperty(exports, "findAvailablePort", { enumerable: true, get: function () { return server_1.findAvailablePort; } });
+Object.defineProperty(exports, "hostForPlatform", { enumerable: true, get: function () { return server_1.hostForPlatform; } });
+Object.defineProperty(exports, "isExpoProject", { enumerable: true, get: function () { return server_1.isExpoProject; } });
+Object.defineProperty(exports, "readSession", { enumerable: true, get: function () { return server_1.readSession; } });
+Object.defineProperty(exports, "startPreviewSession", { enumerable: true, get: function () { return server_1.startPreviewSession; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "requestSnapshot", { enumerable: true, get: function () { return client_1.requestSnapshot; } });
+Object.defineProperty(exports, "resolvePreview", { enumerable: true, get: function () { return client_1.resolvePreview; } });
+Object.defineProperty(exports, "sendCommand", { enumerable: true, get: function () { return client_1.sendCommand; } });

package/dist/protocol.d.ts

@@ -0,0 +1,33 @@
+export interface PreviewDescriptor {
+    id: string;
+    name: string;
+    source: string;
+    line: number;
+    column: number;
+    moduleId: string;
+}
+export interface PreviewSnapshot {
+    previews: PreviewDescriptor[];
+    selectedId: string | null;
+}
+export type BridgeMessage = {
+    type: 'hello';
+    protocolVersion: 1;
+} | {
+    type: 'registry-snapshot';
+    snapshot: PreviewSnapshot;
+} | {
+    type: 'registry-updated';
+    snapshot: PreviewSnapshot;
+} | {
+    type: 'select';
+    id: string;
+} | {
+    type: 'clear';
+} | {
+    type: 'selection-changed';
+    id: string | null;
+} | {
+    type: 'error';
+    message: string;
+};

package/dist/protocol.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+export declare const DEFAULT_PORT = 45678;
+export declare const SESSION_FILE = ".react-native-preview/session.json";
+export interface PreviewSession {
+    port: number;
+    url: string;
+    appUrl: string;
+    platform: 'ios' | 'android';
+}
+export interface StartOptions {
+    platform: 'ios' | 'android';
+    port?: number;
+    projectRoot?: string;
+    sessionFile?: string;
+    expoCommand?: string;
+    spawnApp?: (command: string, args: string[], options: Parameters<typeof spawn>[2]) => ChildProcess;
+}
+export declare function isExpoProject(projectRoot?: string): boolean;
+export declare function findAvailablePort(preferred?: number, host?: string): Promise<number>;
+export declare class PreviewBridgeServer {
+    private readonly port;
+    private readonly host;
+    private readonly clients;
+    private readonly webSocketServer;
+    private snapshot;
+    constructor(port: number, host?: string);
+    get url(): string;
+    close(): Promise<void>;
+    private handle;
+    private send;
+    private broadcast;
+}
+export declare function startPreviewSession(options: StartOptions): Promise<{
+    session: PreviewSession;
+    server: PreviewBridgeServer;
+    app: ChildProcess;
+}>;
+export declare function readSession(sessionFile?: string): PreviewSession;
+export declare function hostForPlatform(platform: 'ios' | 'android'): string;

package/dist/server.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PreviewBridgeServer = exports.SESSION_FILE = exports.DEFAULT_PORT = void 0;
+exports.isExpoProject = isExpoProject;
+exports.findAvailablePort = findAvailablePort;
+exports.startPreviewSession = startPreviewSession;
+exports.readSession = readSession;
+exports.hostForPlatform = hostForPlatform;
+const node_net_1 = require("node:net");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_child_process_1 = require("node:child_process");
+const ws_1 = __importStar(require("ws"));
+exports.DEFAULT_PORT = 45678;
+exports.SESSION_FILE = '.react-native-preview/session.json';
+function isExpoProject(projectRoot = process.cwd()) {
+    try {
+        const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, 'package.json'), 'utf8'));
+        return Boolean(packageJson.dependencies?.expo || packageJson.devDependencies?.expo);
+    }
+    catch {
+        return false;
+    }
+}
+function findAvailablePort(preferred = exports.DEFAULT_PORT, host = '127.0.0.1') {
+    return new Promise((resolve, reject) => {
+        const server = (0, node_net_1.createServer)();
+        server.once('error', (error) => {
+            if (error.code === 'EADDRINUSE') {
+                findAvailablePort(preferred + 1, host).then(resolve, reject);
+            }
+            else {
+                reject(error);
+            }
+        });
+        server.listen(preferred, host, () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : preferred;
+            server.close(() => resolve(port));
+        });
+    });
+}
+class PreviewBridgeServer {
+    constructor(port, host = '127.0.0.1') {
+        this.port = port;
+        this.host = host;
+        this.clients = new Set();
+        this.snapshot = { previews: [], selectedId: null };
+        this.webSocketServer = new ws_1.Server({ port, host });
+        this.webSocketServer.on('connection', (socket) => {
+            this.clients.add(socket);
+            socket.on('message', (data) => this.handle(socket, String(data)));
+            socket.on('close', () => this.clients.delete(socket));
+            this.send(socket, { type: 'registry-snapshot', snapshot: this.snapshot });
+        });
+    }
+    get url() {
+        return `ws://${this.host}:${this.port}`;
+    }
+    close() {
+        for (const client of this.clients)
+            client.close();
+        return new Promise((resolve, reject) => this.webSocketServer.close((error) => error ? reject(error) : resolve()));
+    }
+    handle(sender, raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            this.send(sender, { type: 'error', message: 'Invalid bridge message.' });
+            return;
+        }
+        if (message.type === 'registry-snapshot' || message.type === 'registry-updated') {
+            const selectedId = this.snapshot.previews.some((preview) => preview.id === this.snapshot.selectedId)
+                ? this.snapshot.selectedId
+                : message.snapshot.selectedId;
+            this.snapshot = { ...message.snapshot, selectedId };
+            this.broadcast({ ...message, snapshot: this.snapshot });
+        }
+        else if (message.type === 'selection-changed') {
+            this.snapshot = { ...this.snapshot, selectedId: message.id };
+            this.broadcast(message);
+        }
+        else if (message.type === 'select') {
+            this.snapshot = { ...this.snapshot, selectedId: message.id };
+            this.broadcast(message);
+        }
+        else if (message.type === 'clear') {
+            this.snapshot = { ...this.snapshot, selectedId: null };
+            this.broadcast(message);
+        }
+        else if (message.type === 'hello') {
+            this.send(sender, { type: 'registry-snapshot', snapshot: this.snapshot });
+        }
+    }
+    send(socket, message) {
+        if (socket.readyState === ws_1.default.OPEN)
+            socket.send(JSON.stringify(message));
+    }
+    broadcast(message) {
+        for (const client of this.clients)
+            this.send(client, message);
+    }
+}
+exports.PreviewBridgeServer = PreviewBridgeServer;
+async function startPreviewSession(options) {
+    const projectRoot = options.projectRoot || process.cwd();
+    if (!isExpoProject(projectRoot)) {
+        throw new Error(`Expo project not detected in ${projectRoot}. Bare React Native launch is not supported yet.`);
+    }
+    const port = await findAvailablePort(options.port || Number(process.env.REACT_NATIVE_PREVIEW_PORT) || exports.DEFAULT_PORT);
+    const server = new PreviewBridgeServer(port);
+    const appHost = options.platform === 'android' ? '10.0.2.2' : '127.0.0.1';
+    const appUrl = `ws://${appHost}:${port}`;
+    const session = { port, url: server.url, appUrl, platform: options.platform };
+    const sessionFile = options.sessionFile || (0, node_path_1.join)(projectRoot, exports.SESSION_FILE);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(sessionFile), { recursive: true });
+    (0, node_fs_1.writeFileSync)(sessionFile, JSON.stringify(session, null, 2));
+    const command = options.expoCommand || 'npx';
+    const args = command === 'npx'
+        ? ['expo', 'start', '--dev-client', `--${options.platform}`]
+        : ['start', '--dev-client', `--${options.platform}`];
+    const spawnApp = options.spawnApp || ((cmd, cmdArgs, spawnOptions) => (0, node_child_process_1.spawn)(cmd, cmdArgs, spawnOptions));
+    const app = spawnApp(command, args, {
+        cwd: projectRoot,
+        env: { ...process.env, EXPO_PUBLIC_REACT_NATIVE_PREVIEW_BRIDGE_URL: appUrl },
+        stdio: 'inherit',
+    });
+    return { session, server, app };
+}
+function readSession(sessionFile = (0, node_path_1.join)(process.cwd(), exports.SESSION_FILE)) {
+    if (!(0, node_fs_1.existsSync)(sessionFile))
+        throw new Error(`No preview session found at ${sessionFile}. Run preview start first.`);
+    return JSON.parse((0, node_fs_1.readFileSync)(sessionFile, 'utf8'));
+}
+function hostForPlatform(platform) {
+    return platform === 'android' ? '10.0.2.2' : '127.0.0.1';
+}

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@mickeypause/react-native-preview-cli",
+  "version": "2.0.0",
+  "description": "CLI for the React Native preview bridge",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": { "preview": "bin/preview.js" },
+  "files": ["dist", "bin"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "license": "ISC",
+  "dependencies": { "ws": "^8.18.3" },
+  "devDependencies": { "@types/node": "^24.10.1", "typescript": "^5.9.3" }
+}