@myerscarpenter/quest-dev 1.0.0

package/build/utils/exec.js

@@ -0,0 +1,66 @@
+/**
+ * Shell command execution utilities
+ */
+import { spawn } from 'child_process';
+/**
+ * Execute a shell command and return a promise with stdout
+ */
+export function execCommand(command, args = []) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, {
+            stdio: 'pipe',
+            shell: true
+        });
+        let stdout = '';
+        let stderr = '';
+        if (proc.stdout) {
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        proc.on('close', (code) => {
+            if (code === 0) {
+                resolve(stdout);
+            }
+            else {
+                reject(new Error(`Command failed with code ${code}: ${stderr}`));
+            }
+        });
+        proc.on('error', reject);
+    });
+}
+/**
+ * Execute a shell command and return full result (doesn't throw on non-zero exit)
+ */
+export function execCommandFull(command, args = []) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, args, {
+            stdio: 'pipe',
+            shell: true
+        });
+        let stdout = '';
+        let stderr = '';
+        if (proc.stdout) {
+            proc.stdout.on('data', (data) => {
+                stdout += data.toString();
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+        }
+        proc.on('close', (code) => {
+            resolve({ stdout, stderr, code: code ?? 1 });
+        });
+        proc.on('error', (err) => {
+            resolve({ stdout, stderr: err.message, code: 1 });
+        });
+    });
+}
+//# sourceMappingURL=exec.js.map

package/build/utils/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAQtC;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,OAAiB,EAAE;IAC9D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YAChC,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC9B,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC9B,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,KAAK,CAAC,4BAA4B,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC;YACnE,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,OAAiB,EAAE;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YAChC,KAAK,EAAE,MAAM;YACb,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC9B,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC9B,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACvB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@myerscarpenter/quest-dev",
+  "version": "1.0.0",
+  "description": "CLI for Meta Quest Browser development - screenshot and URL opening via ADB and cdp-cli",
+  "type": "module",
+  "bin": {
+    "quest-dev": "./build/index.js"
+  },
+  "main": "./build/index.js",
+  "keywords": [
+    "meta",
+    "quest",
+    "quest-browser",
+    "adb",
+    "cli",
+    "automation",
+    "vr",
+    "xr",
+    "screenshot"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/myers/quest-dev"
+  },
+  "dependencies": {
+    "which": "^4.0.0",
+    "yargs": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.3",
+    "@types/which": "^3.0.4",
+    "@types/yargs": "^17.0.33",
+    "@vitest/ui": "^4.0.3",
+    "c8": "^10.1.3",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@myerscarpenter/cdp-cli": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@myerscarpenter/cdp-cli": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf build",
+    "build": "pnpm run clean && tsc && chmod +x build/index.js",
+    "start": "pnpm run build && node build/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "version:patch": "pnpm version patch",
+    "version:minor": "pnpm version minor",
+    "version:major": "pnpm version major"
+  }
+}

package/src/commands/open.ts

@@ -0,0 +1,138 @@
+/**
+ * Quest open command
+ * Opens a URL in Quest browser with proper ADB port forwarding
+ */
+
+import {
+  checkADBPath,
+  checkADBDevices,
+  ensurePortForwarding,
+  isBrowserRunning,
+  launchBrowser,
+  getCDPPort
+} from '../utils/adb.js';
+import { execCommand, execCommandFull } from '../utils/exec.js';
+
+/**
+ * Try to navigate or reload existing tab via cdp-cli
+ */
+async function tryNavigateExistingTab(targetUrl: string): Promise<boolean> {
+  const cdpPort = getCDPPort();
+
+  try {
+    // Get list of tabs using cdp-cli
+    const result = await execCommandFull('cdp-cli', ['--cdp-url', `http://localhost:${cdpPort}`, 'tabs']);
+
+    if (result.code !== 0) {
+      console.log('cdp-cli tabs command failed, will launch browser directly');
+      return false;
+    }
+
+    // Parse NDJSON output to find tabs
+    const lines = result.stdout.trim().split('\n').filter(line => line.trim());
+    const tabs: Array<{ id: string; url: string; title: string }> = [];
+
+    for (const line of lines) {
+      try {
+        const tab = JSON.parse(line);
+        if (tab.id && tab.url !== undefined) {
+          tabs.push(tab);
+        }
+      } catch {
+        // Skip non-JSON lines
+      }
+    }
+
+    // First, check if URL is already open
+    const existingTab = tabs.find(tab => tab.url === targetUrl);
+    if (existingTab) {
+      console.log(`Found existing tab with URL: ${targetUrl}`);
+
+      // Reload the tab
+      const reloadResult = await execCommandFull('cdp-cli', [
+        '--cdp-url', `http://localhost:${cdpPort}`,
+        'go', existingTab.id, 'reload'
+      ]);
+
+      if (reloadResult.code === 0) {
+        console.log('Reloaded existing tab');
+        return true;
+      }
+    }
+
+    // Second, look for a blank tab to navigate
+    const blankTab = tabs.find(tab =>
+      tab.url === 'about:blank' ||
+      tab.url === 'chrome://newtab/' ||
+      tab.url === 'chrome://panel-app-nav/ntp' ||  // Quest New Tab page
+      tab.url === ''
+    );
+
+    if (blankTab) {
+      console.log('Found blank tab, navigating it...');
+
+      const navResult = await execCommandFull('cdp-cli', [
+        '--cdp-url', `http://localhost:${cdpPort}`,
+        'go', blankTab.id, targetUrl
+      ]);
+
+      if (navResult.code === 0) {
+        console.log('Navigated blank tab to URL');
+        return true;
+      }
+    }
+
+    return false;
+  } catch (error) {
+    console.log('CDP operation failed:', (error as Error).message);
+    return false;
+  }
+}
+
+/**
+ * Main open command handler
+ */
+export async function openCommand(url: string): Promise<void> {
+  // Parse port from URL
+  let port: number;
+  try {
+    const parsedUrl = new URL(url);
+    port = parseInt(parsedUrl.port, 10);
+    if (!port || isNaN(port)) {
+      console.error('Error: Could not parse port from URL:', url);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error: Invalid URL:', url);
+    process.exit(1);
+  }
+
+  console.log(`\nOpening ${url} on Quest...\n`);
+
+  // Check prerequisites
+  checkADBPath();
+  await checkADBDevices();
+
+  // Set up port forwarding (idempotent)
+  await ensurePortForwarding(port);
+
+  // Check if browser is running
+  const browserRunning = await isBrowserRunning();
+
+  if (!browserRunning) {
+    console.log('Quest browser is not running');
+    await launchBrowser(url);
+  } else {
+    console.log('Quest browser is already running');
+
+    // Try to navigate existing or blank tab via cdp-cli first
+    const navigated = await tryNavigateExistingTab(url);
+
+    if (!navigated) {
+      console.log('No existing or blank tab found, opening URL...');
+      await launchBrowser(url);
+    }
+  }
+
+  console.log('\nDone!\n');
+}

package/src/commands/screenshot.ts

@@ -0,0 +1,102 @@
+/**
+ * Quest screenshot command
+ * Triggers Quest's native screenshot service and pulls the file
+ */
+
+import { resolve } from 'path';
+import { checkADBPath, checkADBDevices } from '../utils/adb.js';
+import { execCommand } from '../utils/exec.js';
+
+/**
+ * Trigger Quest screenshot service
+ */
+async function triggerScreenshot(): Promise<boolean> {
+  try {
+    await execCommand('adb', [
+      'shell',
+      'am',
+      'startservice',
+      '-n',
+      'com.oculus.metacam/.capture.CaptureService',
+      '-a',
+      'TAKE_SCREENSHOT'
+    ]);
+    console.log('Screenshot service triggered');
+    return true;
+  } catch (error) {
+    console.error('Failed to trigger screenshot:', (error as Error).message);
+    return false;
+  }
+}
+
+/**
+ * Get most recent screenshot filename from Quest
+ */
+async function getMostRecentScreenshot(): Promise<string | null> {
+  try {
+    const output = await execCommand('adb', ['shell', 'ls', '-t', '/sdcard/Oculus/Screenshots/']);
+    const files = output.split('\n').filter(line => line.trim() && line.endsWith('.jpg'));
+
+    if (files.length === 0) {
+      console.error('No screenshots found in /sdcard/Oculus/Screenshots/');
+      return null;
+    }
+
+    const mostRecent = files[0].trim();
+    console.log(`Found most recent screenshot: ${mostRecent}`);
+    return mostRecent;
+  } catch (error) {
+    console.error('Failed to list screenshots:', (error as Error).message);
+    return null;
+  }
+}
+
+/**
+ * Pull screenshot from Quest to local path
+ */
+async function pullScreenshot(filename: string, outputPath: string): Promise<boolean> {
+  try {
+    const remotePath = `/sdcard/Oculus/Screenshots/${filename}`;
+    await execCommand('adb', ['pull', remotePath, outputPath]);
+    console.log(`Screenshot saved to: ${outputPath}`);
+    return true;
+  } catch (error) {
+    console.error('Failed to pull screenshot:', (error as Error).message);
+    return false;
+  }
+}
+
+/**
+ * Main screenshot command handler
+ */
+export async function screenshotCommand(outputPath: string): Promise<void> {
+  const resolvedPath = resolve(outputPath);
+
+  console.log('\nQuest Screenshot\n');
+
+  // Check prerequisites
+  checkADBPath();
+  await checkADBDevices();
+
+  // Trigger screenshot
+  if (!await triggerScreenshot()) {
+    process.exit(1);
+  }
+
+  // Wait for screenshot to save
+  console.log('Waiting for screenshot to save...');
+  await new Promise(resolve => setTimeout(resolve, 2000));
+
+  // Get most recent screenshot
+  const filename = await getMostRecentScreenshot();
+  if (!filename) {
+    process.exit(1);
+  }
+
+  // Pull screenshot
+  if (!await pullScreenshot(filename, resolvedPath)) {
+    process.exit(1);
+  }
+
+  console.log('\nDone!\n');
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+/**
+ * Quest Dev CLI
+ * Command-line tools for Meta Quest Browser development
+ */
+
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { screenshotCommand } from './commands/screenshot.js';
+import { openCommand } from './commands/open.js';
+
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(
+  readFileSync(join(__dirname, '../package.json'), 'utf-8')
+);
+const version = packageJson.version;
+
+// Create CLI
+const cli = yargs(hideBin(process.argv))
+  .scriptName('quest-dev')
+  .version(version)
+  .usage('Usage: $0 <command> [options]')
+  .demandCommand(1, 'You must provide a command')
+  .strict()
+  .fail((msg, err, yargs) => {
+    if (msg) {
+      console.error(`Error: ${msg}\n`);
+    }
+    if (err) {
+      console.error(err.message);
+    }
+    console.error('Run "quest-dev --help" for usage information.');
+    process.exit(1);
+  })
+  .help()
+  .alias('help', 'h')
+  .epilog('Requires ADB to be installed and Quest connected via USB with debugging enabled.');
+
+// Screenshot command
+cli.command(
+  'screenshot <output>',
+  'Take a screenshot from Quest and save to local file',
+  (yargs) => {
+    return yargs.positional('output', {
+      describe: 'Output file path (e.g., ~/screenshots/test.jpg)',
+      type: 'string',
+      demandOption: true
+    });
+  },
+  async (argv) => {
+    await screenshotCommand(argv.output as string);
+  }
+);
+
+// Open command
+cli.command(
+  'open <url>',
+  'Open URL in Quest browser with ADB port forwarding',
+  (yargs) => {
+    return yargs.positional('url', {
+      describe: 'URL to open (e.g., http://localhost:9004/myapp/)',
+      type: 'string',
+      demandOption: true
+    });
+  },
+  async (argv) => {
+    await openCommand(argv.url as string);
+  }
+);
+
+// Parse and execute
+cli.parse();

package/src/utils/adb.ts

@@ -0,0 +1,197 @@
+/**
+ * ADB utilities for Quest device communication
+ */
+
+import which from 'which';
+import net from 'net';
+import { execCommand, execCommandFull } from './exec.js';
+
+const CDP_PORT = 9223; // Chrome DevTools Protocol port (Quest browser default)
+
+/**
+ * Check if ADB is available on PATH
+ */
+export function checkADBPath(): string {
+  try {
+    const adbPath = which.sync('adb');
+    console.log(`Found ADB at: ${adbPath}`);
+    return adbPath;
+  } catch (error) {
+    console.error('Error: ADB not found in PATH');
+    console.error('');
+    console.error('Please install Android Platform Tools and add adb to your PATH:');
+    console.error('https://developer.android.com/tools/releases/platform-tools');
+    console.error('');
+    console.error('Installation instructions:');
+    console.error('- macOS: brew install android-platform-tools');
+    console.error('- Linux: sudo apt install adb (or equivalent)');
+    console.error('- Windows: Download from the link above and add to PATH');
+    console.error('');
+    process.exit(1);
+  }
+}
+
+/**
+ * Restart ADB server if it's in a bad state
+ */
+async function restartADBServer(): Promise<boolean> {
+  console.log('ADB server appears to be in a bad state, restarting...');
+  try {
+    // Kill server (ignore errors - it might already be dead)
+    await execCommandFull('adb', ['kill-server']);
+    // Start server
+    await execCommand('adb', ['start-server']);
+    console.log('ADB server restarted successfully');
+    return true;
+  } catch (error) {
+    console.error('Failed to restart ADB server:', (error as Error).message);
+    return false;
+  }
+}
+
+/**
+ * Check if ADB devices are connected (with auto-recovery for server issues)
+ */
+export async function checkADBDevices(retryCount = 0): Promise<boolean> {
+  try {
+    const output = await execCommand('adb', ['devices']);
+    const lines = output.trim().split('\n').slice(1); // Skip header
+    const devices = lines.filter(line => line.trim() && !line.includes('List of devices'));
+
+    if (devices.length === 0) {
+      console.error('Error: No ADB devices connected');
+      console.error('');
+      console.error('Please connect your Quest device via USB and enable USB debugging');
+      console.error('');
+      process.exit(1);
+    }
+
+    console.log(`Found ${devices.length} ADB device(s)`);
+    return true;
+  } catch (error) {
+    const errorMsg = (error as Error).message;
+    // Check if it's a server issue
+    const isServerIssue = errorMsg.includes('protocol fault') ||
+                         errorMsg.includes('Connection reset') ||
+                         errorMsg.includes('server version') ||
+                         errorMsg.includes('cannot connect to daemon');
+
+    if (isServerIssue && retryCount === 0) {
+      const restarted = await restartADBServer();
+      if (restarted) {
+        return await checkADBDevices(1);
+      }
+    }
+
+    console.error('Error: Failed to list ADB devices:', errorMsg);
+    console.error('');
+    console.error('Try running: adb kill-server && adb start-server');
+    console.error('');
+    process.exit(1);
+  }
+}
+
+/**
+ * Check if a port is already listening on localhost
+ */
+export function isPortListening(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    socket.setTimeout(500);
+    socket.on('connect', () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.on('timeout', () => {
+      socket.destroy();
+      resolve(false);
+    });
+    socket.on('error', () => {
+      resolve(false);
+    });
+    socket.connect(port, '127.0.0.1');
+  });
+}
+
+/**
+ * Idempotently set up ADB port forwarding for a given port
+ */
+export async function ensurePortForwarding(port: number): Promise<void> {
+  try {
+    // Check reverse forwarding (Quest -> Host for dev server)
+    const reverseList = await execCommand('adb', ['reverse', '--list']);
+    const reverseExists = reverseList.includes(`tcp:${port}`);
+
+    if (reverseExists) {
+      console.log(`ADB reverse port forwarding already set up: Quest:${port} -> Host:${port}`);
+    } else {
+      await execCommand('adb', ['reverse', `tcp:${port}`, `tcp:${port}`]);
+      console.log(`ADB reverse port forwarding set up: Quest:${port} -> Host:${port}`);
+    }
+
+    // Check forward forwarding (Host -> Quest for CDP)
+    const cdpPortListening = await isPortListening(CDP_PORT);
+
+    if (cdpPortListening) {
+      console.log(`CDP port ${CDP_PORT} already listening (forwarding assumed active)`);
+    } else {
+      try {
+        await execCommand('adb', ['forward', `tcp:${CDP_PORT}`, 'localabstract:chrome_devtools_remote']);
+        console.log(`ADB forward port forwarding set up: Host:${CDP_PORT} -> Quest:chrome_devtools_remote (CDP)`);
+      } catch (forwardError) {
+        const errorMsg = (forwardError as Error).message;
+        if (errorMsg.includes('Address already in use')) {
+          console.log(`CDP port ${CDP_PORT} is now active (another process set it up)`);
+        } else {
+          throw forwardError;
+        }
+      }
+    }
+  } catch (error) {
+    console.error('Failed to set up port forwarding:', (error as Error).message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Check if Quest browser is running
+ */
+export async function isBrowserRunning(): Promise<boolean> {
+  try {
+    const result = await execCommandFull('adb', ['shell', 'ps | grep com.oculus.browser']);
+    return result.stdout.includes('com.oculus.browser');
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Launch Quest browser with a URL using am start
+ */
+export async function launchBrowser(url: string): Promise<boolean> {
+  console.log('Launching Quest browser...');
+  try {
+    await execCommand('adb', [
+      'shell',
+      'am',
+      'start',
+      '-a',
+      'android.intent.action.VIEW',
+      '-d',
+      url,
+      'com.oculus.browser'
+    ]);
+    console.log(`Quest browser launched with URL: ${url}`);
+    return true;
+  } catch (error) {
+    console.error('Failed to launch Quest browser:', (error as Error).message);
+    return false;
+  }
+}
+
+/**
+ * Get CDP port
+ */
+export function getCDPPort(): number {
+  return CDP_PORT;
+}