@myerscarpenter/quest-dev 1.1.0 → 1.2.1

package/src/commands/battery.ts

@@ -0,0 +1,34 @@
+/**
+ * Quest battery command
+ * Shows battery percentage and charging status
+ */
+
+import { checkADBPath, checkADBDevices, getBatteryStatus } from '../utils/adb.js';
+
+/**
+ * Main battery command handler
+ */
+export async function batteryCommand(): Promise<void> {
+  // Check prerequisites (silent)
+  checkADBPath();
+
+  // Check devices without verbose output
+  try {
+    const { execCommand } = await import('../utils/exec.js');
+    const output = await execCommand('adb', ['devices']);
+    const lines = output.trim().split('\n').slice(1);
+    const devices = lines.filter(line => line.trim() && !line.includes('List of devices'));
+
+    if (devices.length === 0) {
+      console.error('Error: No ADB devices connected');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error: Failed to list ADB devices');
+    process.exit(1);
+  }
+
+  // Get and display battery status
+  const status = await getBatteryStatus();
+  console.log(status);
+}

package/src/commands/logcat.ts

@@ -250,11 +250,13 @@ export async function statusCommand(): Promise<void> {
       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));
-        }
+        const { readdirSync } = await import('fs');
+        const files = readdirSync(LOG_DIR)
+          .filter(f => f.endsWith('.txt'))
+          .map(f => ({ name: f, mtime: statSync(join(LOG_DIR, f)).mtimeMs }))
+          .sort((a, b) => b.mtime - a.mtime)
+          .slice(0, 5);
+        files.forEach(f => console.log('  ' + f.name));
       } catch {
         // Ignore
       }

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');
 }

package/src/commands/stay-awake.ts

@@ -0,0 +1,254 @@
+/**
+ * Quest stay-awake command
+ * Keeps Quest screen awake by setting screen timeout to 24 hours
+ * Restores original timeout on exit (Ctrl-C)
+ */
+
+import { checkADBPath } from '../utils/adb.js';
+import { execCommand } from '../utils/exec.js';
+import { execSync, spawn, ChildProcess } from 'child_process';
+import * as os from 'os';
+import * as fs from 'fs';
+
+/**
+ * Get current screen timeout setting
+ */
+async function getScreenTimeout(): Promise<number> {
+  const output = await execCommand('adb', ['shell', 'settings', 'get', 'system', 'screen_off_timeout']);
+  return parseInt(output.trim(), 10);
+}
+
+/**
+ * Set screen timeout (in milliseconds)
+ */
+async function setScreenTimeout(timeout: number): Promise<void> {
+  await execCommand('adb', ['shell', 'settings', 'put', 'system', 'screen_off_timeout', timeout.toString()]);
+}
+
+/**
+ * Disable Quest proximity sensor (keeps screen on even when not worn)
+ */
+async function disableProximitySensor(): Promise<void> {
+  await execCommand('adb', ['shell', 'am', 'broadcast', '-a', 'com.oculus.vrpowermanager.prox_close']);
+}
+
+/**
+ * Enable Quest proximity sensor (re-enable normal behavior)
+ * Note: automation_disable actually RE-ENABLES normal proximity sensor automation
+ */
+async function enableProximitySensor(): Promise<void> {
+  await execCommand('adb', ['shell', 'am', 'broadcast', '-a', 'com.oculus.vrpowermanager.automation_disable']);
+}
+
+/**
+ * Wake the Quest screen
+ */
+async function wakeScreen(): Promise<void> {
+  await execCommand('adb', ['shell', 'input', 'keyevent', 'KEYCODE_WAKEUP']);
+}
+
+/**
+ * Child watchdog process - polls for parent death and cleans up
+ */
+export async function stayAwakeWatchdog(parentPid: number, originalTimeout: number): Promise<void> {
+  const pollInterval = 5000; // Check every 5 seconds
+
+  const checkParent = setInterval(() => {
+    try {
+      // Check if parent process still exists
+      process.kill(parentPid, 0);
+      // Parent still alive, continue polling
+    } catch {
+      // Parent is dead - perform cleanup
+      console.log('Parent process died, restoring Quest settings...');
+      clearInterval(checkParent);
+
+      // Restore settings synchronously
+      try {
+        execSync(`adb shell settings put system screen_off_timeout ${originalTimeout}`, { stdio: 'ignore' });
+        execSync(`adb shell am broadcast -a com.oculus.vrpowermanager.automation_disable`, { stdio: 'ignore' });
+
+        // Cleanup PID file
+        const pidFile = `${os.homedir()}/.quest-dev-stay-awake.pid`;
+        try {
+          fs.unlinkSync(pidFile);
+        } catch {}
+
+        console.log(`Screen timeout restored to ${originalTimeout}ms (${Math.round(originalTimeout / 1000)}s)`);
+        console.log('Proximity sensor re-enabled');
+      } catch (err) {
+        console.error('Failed to restore settings:', (err as Error).message);
+      }
+
+      process.exit(0);
+    }
+  }, pollInterval);
+}
+
+/**
+ * Main stay-awake command handler
+ */
+export async function stayAwakeCommand(idleTimeout: number = 300000): Promise<void> {
+  // Check prerequisites
+  checkADBPath();
+
+  // Check devices without verbose output
+  try {
+    const output = await execCommand('adb', ['devices']);
+    const lines = output.trim().split('\n').slice(1);
+    const devices = lines.filter(line => line.trim() && !line.includes('List of devices'));
+
+    if (devices.length === 0) {
+      console.error('Error: No ADB devices connected');
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error('Error: Failed to list ADB devices');
+    process.exit(1);
+  }
+
+  // PID file management
+  const pidFilePath = `${os.homedir()}/.quest-dev-stay-awake.pid`;
+
+  // Check for existing process
+  if (fs.existsSync(pidFilePath)) {
+    const existingPid = parseInt(fs.readFileSync(pidFilePath, 'utf-8'));
+    try {
+      process.kill(existingPid, 0); // Test if process exists
+      console.error(`Error: stay-awake is already running (PID: ${existingPid})`);
+      process.exit(1);
+    } catch {
+      // Process dead, cleanup stale PID file
+      fs.unlinkSync(pidFilePath);
+    }
+  }
+
+  // Get original timeout
+  let originalTimeout: number;
+
+  try {
+    originalTimeout = await getScreenTimeout();
+    console.log(`Original screen timeout: ${originalTimeout}ms (${Math.round(originalTimeout / 1000)}s)`);
+  } catch (error) {
+    console.error('Failed to get current screen timeout');
+    process.exit(1);
+  }
+
+  // Write PID file
+  try {
+    fs.writeFileSync(pidFilePath, process.pid.toString());
+  } catch (error) {
+    console.warn('Failed to write PID file, hook will not work');
+  }
+
+  // Spawn child watchdog process
+  let childProcess: ChildProcess | null = null;
+  try {
+    childProcess = spawn(process.execPath, [
+      process.argv[1], // quest-dev script path
+      'stay-awake-watchdog',
+      '--parent-pid', process.pid.toString(),
+      '--original-timeout', originalTimeout.toString()
+    ], {
+      detached: true,
+      stdio: 'ignore'
+    });
+
+    childProcess.unref(); // Allow parent to exit without waiting for child
+  } catch (error) {
+    console.warn('Failed to spawn watchdog child process');
+  }
+
+  // Wake screen and disable proximity sensor
+  try {
+    await wakeScreen();
+    console.log('Quest screen woken up');
+
+    await disableProximitySensor();
+    console.log('Proximity sensor disabled');
+  } catch (error) {
+    console.error('Failed to wake screen or disable proximity sensor:', (error as Error).message);
+  }
+
+  // Set timeout to 24 hours (86400000ms)
+  const longTimeout = 86400000;
+  try {
+    await setScreenTimeout(longTimeout);
+    console.log(`Screen timeout set to 24 hours`);
+    console.log(`Quest will stay awake (idle timeout: ${Math.round(idleTimeout / 1000)}s). Press Ctrl-C to restore original settings.`);
+  } catch (error) {
+    console.error('Failed to set screen timeout');
+    process.exit(1);
+  }
+
+  // Idle timer mechanism
+  let idleTimerHandle: NodeJS.Timeout | null = null;
+  let cleanupInProgress = false;
+
+  const resetIdleTimer = () => {
+    if (idleTimerHandle) clearTimeout(idleTimerHandle);
+    idleTimerHandle = setTimeout(() => {
+      console.log('\nIdle timeout reached, exiting...');
+      cleanup();
+    }, idleTimeout);
+  };
+
+  // Set up cleanup on exit (must be synchronous for signal handlers)
+  const cleanup = () => {
+    if (cleanupInProgress) return; // Guard against double-cleanup
+    cleanupInProgress = true;
+
+    // Clear idle timer
+    if (idleTimerHandle) clearTimeout(idleTimerHandle);
+
+    // Kill child watchdog
+    if (childProcess) {
+      try {
+        childProcess.kill();
+      } catch {}
+    }
+
+    console.log('\nRestoring original settings...');
+    try {
+      // Remove PID file
+      try {
+        fs.unlinkSync(pidFilePath);
+      } catch {}
+
+      // Restore Quest settings
+      execSync(`adb shell settings put system screen_off_timeout ${originalTimeout}`, { stdio: 'ignore' });
+      execSync(`adb shell am broadcast -a com.oculus.vrpowermanager.automation_disable`, { stdio: 'ignore' });
+      console.log(`Screen timeout restored to ${originalTimeout}ms (${Math.round(originalTimeout / 1000)}s)`);
+      console.log(`Proximity sensor re-enabled`);
+    } catch (error) {
+      console.error('Failed to restore settings:', (error as Error).message);
+    }
+    process.exit(0);
+  };
+
+  // Handle Ctrl-C and termination
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+  process.on('SIGHUP', cleanup);
+
+  // Handle SIGUSR1 for activity reset
+  process.on('SIGUSR1', () => {
+    console.log('Activity detected, resetting idle timer');
+    resetIdleTimer();
+  });
+
+  // Start idle timer
+  resetIdleTimer();
+
+  // Keep process running with an interval that does nothing
+  console.log('Keeping Quest awake...');
+  setInterval(() => {
+    // Do nothing, just keep process alive
+  }, 60000); // Check every minute
+
+  // Prevent process from exiting
+  await new Promise<void>((resolve) => {
+    // This will only resolve when cleanup is called
+    process.on('exit', () => resolve());
+  });
+}

package/src/index.ts

@@ -13,6 +13,8 @@ import { dirname, join } from 'path';
 import { screenshotCommand } from './commands/screenshot.js';
 import { openCommand } from './commands/open.js';
 import { startCommand, stopCommand, statusCommand, tailCommand } from './commands/logcat.js';
+import { batteryCommand } from './commands/battery.js';
+import { stayAwakeCommand, stayAwakeWatchdog } from './commands/stay-awake.js';
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -44,17 +46,26 @@ const cli = yargs(hideBin(process.argv))
 
 // Screenshot command
 cli.command(
-  'screenshot <output>',
-  'Take a screenshot from Quest and save to local file',
+  'screenshot <directory>',
+  'Take a screenshot from Quest and save to directory with auto-generated filename',
   (yargs) => {
-    return yargs.positional('output', {
-      describe: 'Output file path (e.g., ~/screenshots/test.jpg)',
-      type: 'string',
-      demandOption: true
-    });
+    return yargs
+      .positional('directory', {
+        describe: 'Output directory path (e.g., ~/screenshots)',
+        type: 'string',
+        demandOption: true
+      })
+      .option('caption', {
+        describe: 'Caption to embed in JPEG COM metadata',
+        type: 'string',
+        alias: 'c'
+      });
   },
   async (argv) => {
-    await screenshotCommand(argv.output as string);
+    await screenshotCommand(
+      argv.directory as string,
+      argv.caption as string | undefined
+    );
   }
 );
 
@@ -73,10 +84,20 @@ cli.command(
         describe: 'Close all other tabs before opening',
         type: 'boolean',
         default: false
+      })
+      .option('browser', {
+        describe: 'Browser package name (e.g., com.oculus.browser, org.chromium.chrome)',
+        type: 'string',
+        default: 'com.oculus.browser',
+        alias: 'b'
       });
   },
   async (argv) => {
-    await openCommand(argv.url as string, argv.closeOthers as boolean);
+    await openCommand(
+      argv.url as string,
+      argv.closeOthers as boolean,
+      argv.browser as string
+    );
   }
 );
 
@@ -121,5 +142,52 @@ cli.command(
   }
 );
 
+// Battery command
+cli.command(
+  'battery',
+  'Show Quest battery percentage and charging status',
+  () => {},
+  async () => {
+    await batteryCommand();
+  }
+);
+
+// Stay-awake command
+cli.command(
+  'stay-awake',
+  'Keep Quest screen awake (sets 24hr timeout, restores on Ctrl-C)',
+  (yargs) => {
+    return yargs.option('idle-timeout', {
+      describe: 'Idle timeout in milliseconds (default: 300000 = 5 minutes)',
+      type: 'number',
+      default: 300000,
+      alias: 'i'
+    });
+  },
+  async (argv) => {
+    await stayAwakeCommand(argv.idleTimeout as number);
+  }
+);
+
+// Stay-awake watchdog (internal subcommand, spawned by stay-awake parent)
+cli.command(
+  'stay-awake-watchdog',
+  false as any, // Hide from help
+  (yargs) => {
+    return yargs
+      .option('parent-pid', {
+        type: 'number',
+        demandOption: true
+      })
+      .option('original-timeout', {
+        type: 'number',
+        demandOption: true
+      });
+  },
+  async (argv) => {
+    await stayAwakeWatchdog(argv.parentPid as number, argv.originalTimeout as number);
+  }
+);
+
 // Parse and execute
 cli.parse();