@myerscarpenter/quest-dev 1.2.0 → 1.3.0

package/src/commands/stay-awake.ts

@@ -1,43 +1,100 @@
 /**
  * Quest stay-awake command
- * Keeps Quest screen awake by setting screen timeout to 24 hours
- * Restores original timeout on exit (Ctrl-C)
+ * Uses Meta Scriptable Testing API (content://com.oculus.rc) to disable
+ * autosleep, guardian, and system dialogs for automated testing.
+ *
+ * Cleanup is critical: with autosleep disabled, the headset drains battery
+ * quickly. A watchdog child process ensures cleanup happens even if the
+ * parent is killed (TaskStop, terminal close, claude code exit).
  */
 
-import { checkADBPath } from '../utils/adb.js';
-import { execCommand } from '../utils/exec.js';
+import { checkADBPath, getBatteryInfo, formatBatteryInfo } from '../utils/adb.js';
+import { loadPin, loadConfig } from '../utils/config.js';
+import { execCommand, execCommandFull } from '../utils/exec.js';
 import { execSync, spawn, ChildProcess } from 'child_process';
 import * as os from 'os';
 import * as fs from 'fs';
 
+export interface TestProperties {
+  disable_guardian: boolean;
+  disable_dialogs: boolean;
+  disable_autosleep: boolean;
+  set_proximity_close: boolean;
+}
+
 /**
- * Get current screen timeout setting
+ * Build ADB args for SET_PROPERTY call
  */
-async function getScreenTimeout(): Promise<number> {
-  const output = await execCommand('adb', ['shell', 'settings', 'get', 'system', 'screen_off_timeout']);
-  return parseInt(output.trim(), 10);
+export function buildSetPropertyArgs(pin: string, enabled: boolean): string[] {
+  return [
+    'shell', 'content', 'call',
+    '--uri', 'content://com.oculus.rc',
+    '--method', 'SET_PROPERTY',
+    '--extra', `disable_guardian:b:${enabled}`,
+    '--extra', `disable_dialogs:b:${enabled}`,
+    '--extra', `disable_autosleep:b:${enabled}`,
+    '--extra', `set_proximity_close:b:${enabled}`,
+    '--extra', `PIN:s:${pin}`,
+  ];
 }
 
 /**
- * Set screen timeout (in milliseconds)
+ * Parse GET_PROPERTY Bundle output into structured data
+ * Input: "Bundle[{disable_guardian=true, set_proximity_close=true, disable_dialogs=true, disable_autosleep=true}]"
  */
-async function setScreenTimeout(timeout: number): Promise<void> {
-  await execCommand('adb', ['shell', 'settings', 'put', 'system', 'screen_off_timeout', timeout.toString()]);
+export function parseTestProperties(output: string): TestProperties {
+  const defaults: TestProperties = {
+    disable_guardian: false,
+    disable_dialogs: false,
+    disable_autosleep: false,
+    set_proximity_close: false,
+  };
+
+  const match = output.match(/Bundle\[\{(.+)\}\]/);
+  if (!match) return defaults;
+
+  const pairs = match[1].split(',').map(s => s.trim());
+  for (const pair of pairs) {
+    const [key, value] = pair.split('=');
+    if (key && value && key in defaults) {
+      (defaults as any)[key] = value === 'true';
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Call SET_PROPERTY to enable or disable test mode
+ */
+async function setTestProperties(pin: string, enabled: boolean): Promise<void> {
+  const args = buildSetPropertyArgs(pin, enabled);
+  await execCommand('adb', args);
 }
 
 /**
- * Disable Quest proximity sensor (keeps screen on even when not worn)
+ * Call GET_PROPERTY and return parsed test properties
  */
-async function disableProximitySensor(): Promise<void> {
-  await execCommand('adb', ['shell', 'am', 'broadcast', '-a', 'com.oculus.vrpowermanager.prox_close']);
+async function getTestProperties(): Promise<TestProperties> {
+  const result = await execCommandFull('adb', [
+    'shell', 'content', 'call',
+    '--uri', 'content://com.oculus.rc',
+    '--method', 'GET_PROPERTY',
+  ]);
+  return parseTestProperties(result.stdout);
 }
 
 /**
- * Enable Quest proximity sensor (re-enable normal behavior)
- * Note: automation_disable actually RE-ENABLES normal proximity sensor automation
+ * Format test properties for display
  */
-async function enableProximitySensor(): Promise<void> {
-  await execCommand('adb', ['shell', 'am', 'broadcast', '-a', 'com.oculus.vrpowermanager.automation_disable']);
+function formatTestProperties(props: TestProperties): string {
+  const lines = [
+    `  Guardian disabled:  ${props.disable_guardian}`,
+    `  Dialogs disabled:  ${props.disable_dialogs}`,
+    `  Autosleep disabled: ${props.disable_autosleep}`,
+    `  Proximity close:   ${props.set_proximity_close}`,
+  ];
+  return lines.join('\n');
 }
 
 /**
@@ -47,35 +104,47 @@ async function wakeScreen(): Promise<void> {
   await execCommand('adb', ['shell', 'input', 'keyevent', 'KEYCODE_WAKEUP']);
 }
 
+/**
+ * Show current test properties status
+ */
+export async function stayAwakeStatus(): Promise<void> {
+  checkADBPath();
+  const props = await getTestProperties();
+  console.log('Scriptable Testing properties:');
+  console.log(formatTestProperties(props));
+}
+
+/**
+ * Manually disable test mode (restore all properties)
+ */
+export async function stayAwakeDisable(cliPin?: string): Promise<void> {
+  checkADBPath();
+  const pin = loadPin(cliPin);
+  await setTestProperties(pin, false);
+  console.log('Test mode disabled — guardian, dialogs, and autosleep restored');
+}
+
 /**
  * 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
+export async function stayAwakeWatchdog(parentPid: number, pin: string): Promise<void> {
+  const pollInterval = 5000;
 
   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' });
+        const args = buildSetPropertyArgs(pin, false);
+        execSync(`adb ${args.join(' ')}`, { stdio: 'ignore' });
 
-        // Cleanup PID file
         const pidFile = `${os.homedir()}/.quest-dev-stay-awake.pid`;
-        try {
-          fs.unlinkSync(pidFile);
-        } catch {}
+        try { fs.unlinkSync(pidFile); } catch {}
 
-        console.log(`Screen timeout restored to ${originalTimeout}ms (${Math.round(originalTimeout / 1000)}s)`);
-        console.log('Proximity sensor re-enabled');
+        console.log('Test mode disabled — guardian, dialogs, and autosleep restored');
       } catch (err) {
         console.error('Failed to restore settings:', (err as Error).message);
       }
@@ -88,11 +157,15 @@ export async function stayAwakeWatchdog(parentPid: number, originalTimeout: numb
 /**
  * Main stay-awake command handler
  */
-export async function stayAwakeCommand(idleTimeout: number = 300000): Promise<void> {
-  // Check prerequisites
+export async function stayAwakeCommand(
+  cliPin?: string,
+  cliIdleTimeout?: number,
+  cliLowBattery?: number,
+  verbose: boolean = false,
+): Promise<void> {
   checkADBPath();
 
-  // Check devices without verbose output
+  // Check devices
   try {
     const output = await execCommand('adb', ['devices']);
     const lines = output.trim().split('\n').slice(1);
@@ -107,81 +180,87 @@ export async function stayAwakeCommand(idleTimeout: number = 300000): Promise<vo
     process.exit(1);
   }
 
+  const config = loadConfig();
+  const pin = loadPin(cliPin);
+  const idleTimeout = cliIdleTimeout ?? config.idleTimeout ?? 300000;
+  const lowBattery = cliLowBattery ?? config.lowBattery ?? 10;
+
   // 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
+      process.kill(existingPid, 0);
       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);
-  }
+  // Show current state
+  const beforeProps = await getTestProperties();
+  console.log('Current test properties:');
+  console.log(formatTestProperties(beforeProps));
 
   // Write PID file
   try {
     fs.writeFileSync(pidFilePath, process.pid.toString());
   } catch (error) {
-    console.warn('Failed to write PID file, hook will not work');
+    console.warn('Failed to write PID file');
   }
 
-  // Spawn child watchdog process
+  // Spawn watchdog child process
   let childProcess: ChildProcess | null = null;
   try {
     childProcess = spawn(process.execPath, [
-      process.argv[1], // quest-dev script path
+      process.argv[1],
       'stay-awake-watchdog',
       '--parent-pid', process.pid.toString(),
-      '--original-timeout', originalTimeout.toString()
+      '--pin', pin,
     ], {
       detached: true,
-      stdio: 'ignore'
+      stdio: 'ignore',
     });
-
-    childProcess.unref(); // Allow parent to exit without waiting for child
+    childProcess.unref();
   } catch (error) {
     console.warn('Failed to spawn watchdog child process');
   }
 
-  // Wake screen and disable proximity sensor
+  // Enable test mode
+  try {
+    await setTestProperties(pin, true);
+    console.log('Test mode enabled — guardian, dialogs, and autosleep disabled');
+  } catch (error) {
+    console.error('Failed to enable test mode:', (error as Error).message);
+    console.error('Requires Quest OS v44+ and a valid Meta Store PIN.');
+    process.exit(1);
+  }
+
+  // Wake screen
   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);
+    console.error('Failed to wake screen:', (error as Error).message);
   }
 
-  // Set timeout to 24 hours (86400000ms)
-  const longTimeout = 86400000;
+  // Battery monitoring state
+  let lastReportedBucket = -1; // Track 5% boundary crossings
+
+  // Initial battery check
   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.`);
+    const battery = await getBatteryInfo();
+    console.log(`Battery: ${formatBatteryInfo(battery)}`);
+    lastReportedBucket = Math.floor(battery.level / 5) * 5;
   } catch (error) {
-    console.error('Failed to set screen timeout');
-    process.exit(1);
+    console.warn('Failed to read battery status');
   }
 
-  // Idle timer mechanism
+  console.log(`Quest will stay awake (idle timeout: ${Math.round(idleTimeout / 1000)}s, low battery exit: ${lowBattery}%). Press Ctrl-C to restore.`);
+
+  // Idle timer
   let idleTimerHandle: NodeJS.Timeout | null = null;
   let cleanupInProgress = false;
 
@@ -193,62 +272,71 @@ export async function stayAwakeCommand(idleTimeout: number = 300000): Promise<vo
     }, idleTimeout);
   };
 
-  // Set up cleanup on exit (must be synchronous for signal handlers)
+  // Cleanup handler
   const cleanup = () => {
-    if (cleanupInProgress) return; // Guard against double-cleanup
+    if (cleanupInProgress) return;
     cleanupInProgress = true;
 
-    // Clear idle timer
     if (idleTimerHandle) clearTimeout(idleTimerHandle);
+    if (batteryInterval) clearInterval(batteryInterval);
 
-    // Kill child watchdog
     if (childProcess) {
-      try {
-        childProcess.kill();
-      } catch {}
+      try { childProcess.kill(); } catch {}
     }
 
-    console.log('\nRestoring original settings...');
+    console.log('\nRestoring 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`);
+      try { fs.unlinkSync(pidFilePath); } catch {}
+
+      const args = buildSetPropertyArgs(pin, false);
+      execSync(`adb ${args.join(' ')}`, { stdio: 'ignore' });
+      console.log('Test mode disabled — guardian, dialogs, and autosleep restored');
     } catch (error) {
       console.error('Failed to restore settings:', (error as Error).message);
     }
     process.exit(0);
   };
 
-  // Handle Ctrl-C and termination
+  // Signal handlers
   process.on('SIGINT', cleanup);
   process.on('SIGTERM', cleanup);
   process.on('SIGHUP', cleanup);
 
-  // Handle SIGUSR1 for activity reset
+  // Activity reset via SIGUSR1
   process.on('SIGUSR1', () => {
-    console.log('Activity detected, resetting idle timer');
+    const now = new Date().toLocaleTimeString();
+    console.log(`[${now}] 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
+  // Battery monitoring loop (every 60s)
+  const batteryInterval = setInterval(async () => {
+    try {
+      const battery = await getBatteryInfo();
+      const currentBucket = Math.floor(battery.level / 5) * 5;
+
+      if (verbose) {
+        console.log(`Battery: ${formatBatteryInfo(battery)}`);
+      } else if (currentBucket !== lastReportedBucket) {
+        console.log(`Battery: ${formatBatteryInfo(battery)}`);
+      }
+      lastReportedBucket = currentBucket;
+
+      if (battery.level <= lowBattery && battery.state === 'not charging') {
+        console.log(`\nBattery critically low (${battery.level}%), exiting to preserve battery...`);
+        cleanup();
+      }
+    } catch {
+      // Ignore battery check failures (device might be briefly unavailable)
+    }
+  }, 60000);
 
-  // Prevent process from exiting
+  // Keep process alive
+  console.log('Keeping Quest awake...');
   await new Promise<void>((resolve) => {
-    // This will only resolve when cleanup is called
     process.on('exit', () => resolve());
   });
 }

package/src/index.ts

@@ -14,7 +14,7 @@ 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';
+import { stayAwakeCommand, stayAwakeWatchdog, stayAwakeStatus, stayAwakeDisable } from './commands/stay-awake.js';
 
 // Read version from package.json
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -155,17 +155,52 @@ cli.command(
 // Stay-awake command
 cli.command(
   'stay-awake',
-  'Keep Quest screen awake (sets 24hr timeout, restores on Ctrl-C)',
+  'Keep Quest awake (disables autosleep, guardian, dialogs)',
   (yargs) => {
-    return yargs.option('idle-timeout', {
-      describe: 'Idle timeout in milliseconds (default: 300000 = 5 minutes)',
-      type: 'number',
-      default: 300000,
-      alias: 'i'
-    });
+    return yargs
+      .option('pin', {
+        describe: 'Meta Store PIN (or set in .quest-dev.json / ~/.config/quest-dev/config.json)',
+        type: 'string',
+      })
+      .option('idle-timeout', {
+        describe: 'Idle timeout in milliseconds (default: 300000 = 5 minutes, or set idleTimeout in config)',
+        type: 'number',
+        alias: 'i',
+      })
+      .option('low-battery', {
+        describe: 'Exit when battery drops to this percentage (default: 10, or set lowBattery in config)',
+        type: 'number',
+      })
+      .option('disable', {
+        describe: 'Manually restore all test properties and exit',
+        type: 'boolean',
+        default: false,
+      })
+      .option('status', {
+        describe: 'Show current property values and exit',
+        type: 'boolean',
+        default: false,
+      })
+      .option('verbose', {
+        describe: 'Print battery level on every check (every 60s)',
+        type: 'boolean',
+        default: false,
+        alias: 'v',
+      });
   },
   async (argv) => {
-    await stayAwakeCommand(argv.idleTimeout as number);
+    if (argv.status) {
+      await stayAwakeStatus();
+    } else if (argv.disable) {
+      await stayAwakeDisable(argv.pin as string | undefined);
+    } else {
+      await stayAwakeCommand(
+        argv.pin as string | undefined,
+        argv.idleTimeout as number | undefined,
+        argv.lowBattery as number | undefined,
+        argv.verbose as boolean,
+      );
+    }
   }
 );
 
@@ -177,15 +212,15 @@ cli.command(
     return yargs
       .option('parent-pid', {
         type: 'number',
-        demandOption: true
+        demandOption: true,
       })
-      .option('original-timeout', {
-        type: 'number',
-        demandOption: true
+      .option('pin', {
+        type: 'string',
+        demandOption: true,
       });
   },
   async (argv) => {
-    await stayAwakeWatchdog(argv.parentPid as number, argv.originalTimeout as number);
+    await stayAwakeWatchdog(argv.parentPid as number, argv.pin as string);
   }
 );
 

package/src/utils/adb.ts

@@ -345,18 +345,21 @@ export async function checkQuestAwake(): Promise<void> {
   }
 }
 
+export interface BatteryInfo {
+  level: number;
+  state: 'fast charging' | 'charging' | 'not charging';
+}
+
 /**
- * Get Quest battery status
- * Returns percentage and charging state in one line
+ * Get Quest battery info as structured data
  */
-export async function getBatteryStatus(): Promise<string> {
+export async function getBatteryInfo(): Promise<BatteryInfo> {
   const result = await execCommandFull('adb', ['shell', 'dumpsys', 'battery']);
 
   if (result.code !== 0) {
     throw new Error('Failed to get battery status');
   }
 
-  // Parse battery info
   let level = 0;
   let acPowered = false;
   let usbPowered = false;
@@ -376,18 +379,19 @@ export async function getBatteryStatus(): Promise<string> {
     }
   }
 
-  // Determine charging state
-  let state: string;
+  let state: BatteryInfo['state'];
   if (acPowered || usbPowered) {
-    // Fast charging is typically > 2A (2000000 microamps)
-    if (maxChargingCurrent > 2000000) {
-      state = 'fast charging';
-    } else {
-      state = 'charging';
-    }
+    state = maxChargingCurrent > 2000000 ? 'fast charging' : 'charging';
   } else {
     state = 'not charging';
   }
 
-  return `${level}% ${state}`;
+  return { level, state };
+}
+
+/**
+ * Format battery info as a human-readable string
+ */
+export function formatBatteryInfo(info: BatteryInfo): string {
+  return `${info.level}% ${info.state}`;
 }

package/src/utils/config.ts

@@ -0,0 +1,66 @@
+/**
+ * Config file loading for quest-dev
+ * Resolves settings from CLI flags → .quest-dev.json → ~/.config/quest-dev/config.json
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export interface QuestDevConfig {
+  pin?: string;
+  idleTimeout?: number;
+  lowBattery?: number;
+}
+
+const CONFIG_LOCATIONS = [
+  join(process.cwd(), '.quest-dev.json'),
+  join(homedir(), '.config', 'quest-dev', 'config.json'),
+];
+
+function tryReadConfig(path: string): QuestDevConfig | null {
+  try {
+    const content = readFileSync(path, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load merged config from all config file locations.
+ * First file found wins for each field.
+ */
+export function loadConfig(): QuestDevConfig {
+  const merged: QuestDevConfig = {};
+
+  for (const path of CONFIG_LOCATIONS) {
+    const config = tryReadConfig(path);
+    if (!config) continue;
+    if (merged.pin === undefined && config.pin) merged.pin = config.pin;
+    if (merged.idleTimeout === undefined && config.idleTimeout !== undefined) merged.idleTimeout = config.idleTimeout;
+    if (merged.lowBattery === undefined && config.lowBattery !== undefined) merged.lowBattery = config.lowBattery;
+  }
+
+  return merged;
+}
+
+/**
+ * Resolve PIN from CLI flag, then config files
+ */
+export function loadPin(cliPin?: string): string {
+  if (cliPin) return cliPin;
+
+  const config = loadConfig();
+  if (config.pin) return config.pin;
+
+  console.error('Error: No PIN found');
+  console.error('');
+  console.error('Provide a PIN via one of:');
+  console.error('  --pin <pin>                           CLI flag');
+  console.error('  .quest-dev.json                       { "pin": "1234" }');
+  console.error('  ~/.config/quest-dev/config.json       { "pin": "1234" }');
+  console.error('');
+  console.error('The PIN is your Meta Store PIN for the logged-in account.');
+  process.exit(1);
+}

package/src/utils/exec.ts

@@ -17,7 +17,6 @@ export function execCommand(command: string, args: string[] = []): Promise<strin
   return new Promise((resolve, reject) => {
     const proc = spawn(command, args, {
       stdio: 'pipe',
-      shell: true
     });
 
     let stdout = '';
@@ -54,7 +53,6 @@ export function execCommandFull(command: string, args: string[] = []): Promise<E
   return new Promise((resolve) => {
     const proc = spawn(command, args, {
       stdio: 'pipe',
-      shell: true
     });
 
     let stdout = '';