@myerscarpenter/quest-dev 1.0.8 → 1.2.0

package/src/commands/logcat.ts

@@ -0,0 +1,288 @@
+/**
+ * Quest logcat command
+ * Captures Android logcat to files for Quest debugging
+ *
+ * CRITICAL: Quest's ring buffer fills in seconds under VR load.
+ * Always capture to a file BEFORE testing to avoid losing crash logs.
+ */
+
+import { resolve, join } from 'path';
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, symlinkSync, statSync, readlinkSync, openSync } from 'fs';
+import { spawn } from 'child_process';
+import { checkADBPath, checkADBDevices } from '../utils/adb.js';
+import { execCommand, execCommandFull } from '../utils/exec.js';
+
+const LOG_DIR = process.env.LOG_DIR || 'logs/logcat';
+const PID_FILE = join(LOG_DIR, '.logcat_pid');
+const LOGFILE_LINK = join(LOG_DIR, 'latest.txt');
+
+/**
+ * Ensure log directory exists
+ */
+function ensureLogDir(): void {
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Check if a process is running by PID
+ */
+function isProcessRunning(pid: number): boolean {
+  try {
+    // Sending signal 0 checks if process exists without killing it
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read PID from PID file
+ */
+function readPidFile(): number | null {
+  if (!existsSync(PID_FILE)) {
+    return null;
+  }
+  try {
+    const pidStr = readFileSync(PID_FILE, 'utf-8').trim();
+    return parseInt(pidStr, 10);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write PID to PID file
+ */
+function writePidFile(pid: number): void {
+  writeFileSync(PID_FILE, pid.toString(), 'utf-8');
+}
+
+/**
+ * Delete PID file
+ */
+function deletePidFile(): void {
+  if (existsSync(PID_FILE)) {
+    unlinkSync(PID_FILE);
+  }
+}
+
+/**
+ * Get the latest log file path
+ */
+function getLatestLogFile(): string | null {
+  if (!existsSync(LOGFILE_LINK)) {
+    return null;
+  }
+  try {
+    const target = readlinkSync(LOGFILE_LINK);
+    const fullPath = join(LOG_DIR, target);
+    if (existsSync(fullPath)) {
+      return fullPath;
+    }
+  } catch {
+    // Symlink might be broken
+  }
+  return null;
+}
+
+/**
+ * Get file size and line count
+ */
+function getFileStats(filePath: string): { size: string; lines: number } | null {
+  try {
+    const stats = statSync(filePath);
+    const sizeInBytes = stats.size;
+    let sizeStr: string;
+
+    if (sizeInBytes < 1024) {
+      sizeStr = `${sizeInBytes}B`;
+    } else if (sizeInBytes < 1024 * 1024) {
+      sizeStr = `${(sizeInBytes / 1024).toFixed(1)}K`;
+    } else {
+      sizeStr = `${(sizeInBytes / (1024 * 1024)).toFixed(1)}M`;
+    }
+
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').length;
+
+    return { size: sizeStr, lines };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Start logcat capture
+ */
+export async function startCommand(filter?: string): Promise<void> {
+  // Check for existing capture
+  const existingPid = readPidFile();
+  if (existingPid && isProcessRunning(existingPid)) {
+    console.error('Already capturing. Use "quest-dev logcat stop" first.');
+    process.exit(1);
+  }
+
+  // Check prerequisites
+  checkADBPath();
+  await checkADBDevices();
+
+  ensureLogDir();
+
+  // Generate log filename
+  const timestamp = new Date().toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\..+/, '')
+    .replace('T', '_')
+    .slice(0, 15); // YYYYMMDD_HHMMSS
+  const logFile = join(LOG_DIR, `logcat_${timestamp}.txt`);
+
+  console.log(`Starting capture to: ${logFile}`);
+
+  // Clear the buffer first - critical for Quest
+  try {
+    await execCommand('adb', ['logcat', '-c']);
+    console.log('Ring buffer cleared.');
+  } catch (error) {
+    console.error('Failed to clear ring buffer:', (error as Error).message);
+    process.exit(1);
+  }
+
+  if (filter) {
+    console.log(`Filter: ${filter}`);
+  }
+
+  // Start background logcat process
+  const args = ['logcat', '-v', 'threadtime'];
+  if (filter) {
+    args.push(filter);
+  }
+
+  // Open file for writing
+  const fd = openSync(logFile, 'w');
+
+  const proc = spawn('adb', args, {
+    stdio: ['ignore', fd, fd],
+    detached: true
+  });
+
+  // Unref so parent can exit immediately
+  proc.unref();
+
+  // Save PID
+  writePidFile(proc.pid!);
+
+  // Update symlink
+  try {
+    if (existsSync(LOGFILE_LINK)) {
+      unlinkSync(LOGFILE_LINK);
+    }
+    symlinkSync(`logcat_${timestamp}.txt`, LOGFILE_LINK);
+  } catch (error) {
+    console.warn('Warning: Failed to create symlink:', (error as Error).message);
+  }
+
+  console.log(`Capturing (PID: ${proc.pid})`);
+  console.log('');
+  console.log('Now run your test. When done: quest-dev logcat stop');
+}
+
+/**
+ * Stop logcat capture
+ */
+export async function stopCommand(): Promise<void> {
+  const pid = readPidFile();
+
+  if (!pid) {
+    console.log('No capture in progress');
+    return;
+  }
+
+  if (isProcessRunning(pid)) {
+    try {
+      process.kill(pid, 'SIGTERM');
+      console.log(`Capture stopped (PID: ${pid})`);
+    } catch (error) {
+      console.log(`Capture process already ended (PID: ${pid})`);
+    }
+  } else {
+    console.log('Capture process already ended');
+  }
+
+  deletePidFile();
+
+  // Show file info
+  const latestFile = getLatestLogFile();
+  if (latestFile) {
+    const stats = getFileStats(latestFile);
+    if (stats) {
+      console.log('');
+      console.log(`Log file: ${latestFile}`);
+      console.log(`Size: ${stats.size} (${stats.lines} lines)`);
+    }
+  }
+}
+
+/**
+ * Show capture status
+ */
+export async function statusCommand(): Promise<void> {
+  const pid = readPidFile();
+
+  if (pid && isProcessRunning(pid)) {
+    console.log(`Capturing (PID: ${pid})`);
+
+    const latestFile = getLatestLogFile();
+    if (latestFile) {
+      const stats = getFileStats(latestFile);
+      if (stats) {
+        console.log(`File: ${latestFile}`);
+        console.log(`Size: ${stats.size} (${stats.lines} lines)`);
+      }
+    }
+  } else {
+    console.log('Not capturing');
+
+    // Show recent logs
+    if (existsSync(LOG_DIR)) {
+      console.log('');
+      console.log('Recent logs:');
+      try {
+        const result = await execCommandFull('ls', ['-lht', join(LOG_DIR, '*.txt')]);
+        if (result.code === 0) {
+          const lines = result.stdout.trim().split('\n').slice(0, 5);
+          lines.forEach(line => console.log('  ' + line));
+        }
+      } catch {
+        // Ignore
+      }
+    }
+  }
+}
+
+/**
+ * Tail current capture
+ */
+export async function tailCommand(): Promise<void> {
+  const latestFile = getLatestLogFile();
+
+  if (!latestFile) {
+    console.error('No active log file');
+    process.exit(1);
+  }
+
+  console.log(`Tailing: ${latestFile}`);
+  console.log('Press Ctrl+C to stop\n');
+
+  // Use tail -f
+  const tailProc = spawn('tail', ['-f', latestFile], {
+    stdio: 'inherit'
+  });
+
+  tailProc.on('error', (error) => {
+    console.error('Failed to tail log:', error.message);
+    process.exit(1);
+  });
+}

package/src/commands/open.ts

@@ -17,8 +17,8 @@ import { execCommand, execCommandFull } from '../utils/exec.js';
 /**
  * Close all tabs except the one with the target URL
  */
-async function closeOtherTabs(targetUrl: string): Promise<void> {
-  const cdpPort = getCDPPort();
+async function closeOtherTabs(targetUrl: string, browser: string): Promise<void> {
+  const cdpPort = await getCDPPort(browser);
 
   try {
     // Get list of tabs
@@ -66,8 +66,8 @@ async function closeOtherTabs(targetUrl: string): Promise<void> {
 /**
  * Try to navigate or reload existing tab via cdp-cli
  */
-async function tryNavigateExistingTab(targetUrl: string): Promise<boolean> {
-  const cdpPort = getCDPPort();
+async function tryNavigateExistingTab(targetUrl: string, browser: string): Promise<boolean> {
+  const cdpPort = await getCDPPort(browser);
 
   try {
     // Get list of tabs using cdp-cli
@@ -142,7 +142,11 @@ async function tryNavigateExistingTab(targetUrl: string): Promise<boolean> {
 /**
  * Main open command handler
  */
-export async function openCommand(url: string, closeOthers: boolean = false): Promise<void> {
+export async function openCommand(
+  url: string,
+  closeOthers: boolean = false,
+  browser: string = 'com.oculus.browser'
+): Promise<void> {
   // Parse URL to determine if we need reverse port forwarding
   let parsedUrl: URL;
   try {
@@ -175,27 +179,27 @@ export async function openCommand(url: string, closeOthers: boolean = false): Pr
   // Set up port forwarding
   if (port !== null) {
     // Localhost URL: need reverse forwarding so Quest can reach the dev server
-    await ensurePortForwarding(port);
+    await ensurePortForwarding(port, browser);
   } else {
     // External URL: only need CDP forwarding to control the browser
-    await ensureCDPForwarding();
+    await ensureCDPForwarding(browser);
   }
 
   // Check if browser is running
-  const browserRunning = await isBrowserRunning();
+  const browserRunning = await isBrowserRunning(browser);
 
   if (!browserRunning) {
-    console.log('Quest browser is not running');
-    await launchBrowser(url);
+    console.log('Browser is not running');
+    await launchBrowser(url, browser);
   } else {
-    console.log('Quest browser is already running');
+    console.log('Browser is already running');
 
     // Try to navigate existing or blank tab via cdp-cli first
-    const navigated = await tryNavigateExistingTab(url);
+    const navigated = await tryNavigateExistingTab(url, browser);
 
     if (!navigated) {
       console.log('No existing or blank tab found, opening URL...');
-      await launchBrowser(url);
+      await launchBrowser(url, browser);
     }
   }
 
@@ -204,7 +208,7 @@ export async function openCommand(url: string, closeOthers: boolean = false): Pr
     // Wait for browser to stabilize after launch/navigation
     console.log('Waiting for browser to stabilize...');
     await new Promise(resolve => setTimeout(resolve, 2000));
-    await closeOtherTabs(url);
+    await closeOtherTabs(url, browser);
   }
 
   console.log('\nDone!\n');

package/src/commands/screenshot.ts

@@ -3,9 +3,33 @@
  * Triggers Quest's native screenshot service and pulls the file
  */
 
-import { resolve } from 'path';
+import { resolve, join } from 'path';
+import { existsSync, statSync } from 'fs';
 import { checkADBPath, checkADBDevices, checkUSBFileTransfer, checkQuestAwake } from '../utils/adb.js';
 import { execCommand, execCommandFull } from '../utils/exec.js';
+import { generateScreenshotFilename } from '../utils/filename.js';
+
+/**
+ * Validate directory exists and is writable
+ */
+function validateDirectory(dirPath: string): void {
+  const resolvedPath = resolve(dirPath);
+
+  if (!existsSync(resolvedPath)) {
+    console.error(`Error: Directory does not exist: ${resolvedPath}`);
+    console.error('');
+    console.error('Please create the directory first.');
+    console.error('');
+    process.exit(1);
+  }
+
+  const stat = statSync(resolvedPath);
+  if (!stat.isDirectory()) {
+    console.error(`Error: Path is not a directory: ${resolvedPath}`);
+    console.error('');
+    process.exit(1);
+  }
+}
 
 /**
  * Trigger Quest screenshot service
@@ -106,14 +130,37 @@ async function deleteRemoteScreenshot(filename: string): Promise<void> {
   }
 }
 
+/**
+ * Add caption to JPEG COM metadata
+ */
+async function addJpegMetadata(filePath: string, caption: string): Promise<boolean> {
+  try {
+    const { exiftool } = await import('exiftool-vendored');
+    await exiftool.write(filePath, { Comment: caption });
+    await exiftool.end();
+    console.log(`Caption added: "${caption}"`);
+    return true;
+  } catch (error) {
+    console.error('Warning: Failed to add caption metadata:', (error as Error).message);
+    return false;
+  }
+}
+
 /**
  * Main screenshot command handler
  */
-export async function screenshotCommand(outputPath: string): Promise<void> {
-  const resolvedPath = resolve(outputPath);
+export async function screenshotCommand(directoryPath: string, caption: string | undefined): Promise<void> {
+  const resolvedDir = resolve(directoryPath);
 
   console.log('\nQuest Screenshot\n');
 
+  // Validate directory (fail-fast before expensive ADB ops)
+  validateDirectory(resolvedDir);
+
+  // Generate filename
+  const localFilename = generateScreenshotFilename();
+  const outputPath = join(resolvedDir, localFilename);
+
   // Check prerequisites
   checkADBPath();
   await checkADBDevices();
@@ -130,7 +177,7 @@ export async function screenshotCommand(outputPath: string): Promise<void> {
 
   // Wait for screenshot to save and verify it's complete (has JPEG EOI marker)
   console.log('Waiting for screenshot to save...');
-  let filename: string | null = null;
+  let questFilename: string | null = null;
   const maxAttempts = 20;
 
   for (let i = 0; i < maxAttempts; i++) {
@@ -141,14 +188,14 @@ export async function screenshotCommand(outputPath: string): Promise<void> {
       // Check that the JPEG is fully written (has EOI marker)
       const complete = await isJpegComplete(newScreenshot);
       if (complete) {
-        filename = newScreenshot;
-        console.log(`Screenshot ready: ${filename}`);
+        questFilename = newScreenshot;
+        console.log(`Screenshot ready: ${questFilename}`);
         break;
       }
     }
   }
 
-  if (!filename) {
+  if (!questFilename) {
     console.error('Error: Screenshot was not created or is incomplete');
     console.error('');
     console.error('The screenshot service was triggered but no valid screenshot appeared.');
@@ -162,12 +209,17 @@ export async function screenshotCommand(outputPath: string): Promise<void> {
   }
 
   // Pull screenshot
-  if (!await pullScreenshot(filename, resolvedPath)) {
+  if (!await pullScreenshot(questFilename, outputPath)) {
     process.exit(1);
   }
 
+  // Add metadata (non-fatal, only if caption provided)
+  if (caption) {
+    await addJpegMetadata(outputPath, caption);
+  }
+
   // Delete from Quest after successful pull
-  await deleteRemoteScreenshot(filename);
+  await deleteRemoteScreenshot(questFilename);
 
   console.log('\nDone!\n');
 }