@myerscarpenter/quest-dev 1.0.0 → 1.0.3

package/.github/workflows/publish.yml

@@ -9,7 +9,7 @@ jobs:
   test-and-publish:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write  # Required for creating releases
       id-token: write  # Required for OIDC trusted publishing
     steps:
       - uses: actions/checkout@v4
@@ -39,3 +39,8 @@ jobs:
 
       - name: Publish to npm
         run: npm publish --provenance --access public
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create ${{ github.ref_name }} --generate-notes

package/README.md

@@ -0,0 +1,80 @@
+# quest-dev
+
+CLI tools for Meta Quest Browser development. Take screenshots and open URLs on your Quest device via ADB.
+
+## Installation
+
+```bash
+npm install -g @myerscarpenter/quest-dev
+```
+
+## Prerequisites
+
+- **ADB** - Android Debug Bridge must be installed and in your PATH
+  - macOS: `brew install android-platform-tools`
+  - Linux: `sudo apt install adb`
+  - Windows: [Download Platform Tools](https://developer.android.com/tools/releases/platform-tools)
+
+- **Quest Device** - Connected via USB with [Developer Mode and USB Debugging enabled](https://developers.meta.com/horizon/documentation/native/android/mobile-device-setup/)
+
+- **cdp-cli** (optional) - For smart tab reuse in the `open` command
+
+  ```bash
+  npm install -g @myerscarpenter/cdp-cli
+  ```
+
+## Usage
+
+### Screenshot
+
+Take a screenshot from Quest and save it locally:
+
+```bash
+quest-dev screenshot ./screenshot.jpg
+quest-dev screenshot ~/Pictures/quest-capture.jpg
+```
+
+This uses Quest's native screenshot service which captures the full VR view, including immersive content that CDP screenshots can't capture.
+
+### Open URL
+
+Open a URL in Quest Browser with automatic ADB port forwarding:
+
+```bash
+quest-dev open http://localhost:3000/
+quest-dev open http://localhost:9004/my-xr-app/
+```
+
+This command:
+
+1. Sets up ADB reverse port forwarding (Quest → Host) so the Quest can reach your dev server
+2. Sets up ADB forward port forwarding (Host → Quest) for CDP communication
+3. If Quest Browser is already running with the URL, reloads the tab
+4. If a blank tab exists, navigates it to the URL
+5. Otherwise, launches Quest Browser with the URL
+
+Port forwarding is idempotent - safe to run multiple times without issues.
+
+## How It Works
+
+- **screenshot**: Triggers `com.oculus.metacam/.capture.CaptureService` via ADB, waits for the screenshot to save, then pulls the most recent file from `/sdcard/Oculus/Screenshots/`
+
+- **open**: Uses ADB for port forwarding and browser launching. If `cdp-cli` is installed, it uses CDP to intelligently reuse existing tabs instead of opening new ones.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm run build
+
+# Run locally
+node build/index.js screenshot ./test.jpg
+node build/index.js open http://localhost:3000/
+```
+
+## License
+
+MIT

package/build/index.js

@@ -33,7 +33,7 @@ const cli = yargs(hideBin(process.argv))
 })
     .help()
     .alias('help', 'h')
-    .epilog('Requires ADB to be installed and Quest connected via USB with debugging enabled.');
+    .epilog('Requires ADB and Quest connected via USB. Sets up CDP on port 9223 for cdp-cli.');
 // Screenshot command
 cli.command('screenshot <output>', 'Take a screenshot from Quest and save to local file', (yargs) => {
     return yargs.positional('output', {
@@ -45,7 +45,7 @@ cli.command('screenshot <output>', 'Take a screenshot from Quest and save to loc
     await screenshotCommand(argv.output);
 });
 // Open command
-cli.command('open <url>', 'Open URL in Quest browser with ADB port forwarding', (yargs) => {
+cli.command('open <url>', 'Open URL in Quest browser (sets up dev server + CDP debugging port forwarding)', (yargs) => {
     return yargs.positional('url', {
         describe: 'URL to open (e.g., http://localhost:9004/myapp/)',
         type: 'string',

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,iCAAiC;AACjC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;AACF,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;AAEpC,aAAa;AACb,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACrC,UAAU,CAAC,WAAW,CAAC;KACvB,OAAO,CAAC,OAAO,CAAC;KAChB,KAAK,CAAC,+BAA+B,CAAC;KACtC,aAAa,CAAC,CAAC,EAAE,4BAA4B,CAAC;KAC9C,MAAM,EAAE;KACR,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;IACxB,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;KACD,IAAI,EAAE;KACN,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;KAClB,MAAM,CAAC,kFAAkF,CAAC,CAAC;AAE9F,qBAAqB;AACrB,GAAG,CAAC,OAAO,CACT,qBAAqB,EACrB,qDAAqD,EACrD,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE;QAChC,QAAQ,EAAE,iDAAiD;QAC3D,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,iBAAiB,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAC;AACjD,CAAC,CACF,CAAC;AAEF,eAAe;AACf,GAAG,CAAC,OAAO,CACT,YAAY,EACZ,oDAAoD,EACpD,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE;QAC7B,QAAQ,EAAE,kDAAkD;QAC5D,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,WAAW,CAAC,IAAI,CAAC,GAAa,CAAC,CAAC;AACxC,CAAC,CACF,CAAC;AAEF,oBAAoB;AACpB,GAAG,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,iCAAiC;AACjC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAC1D,CAAC;AACF,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC;AAEpC,aAAa;AACb,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;KACrC,UAAU,CAAC,WAAW,CAAC;KACvB,OAAO,CAAC,OAAO,CAAC;KAChB,KAAK,CAAC,+BAA+B,CAAC;KACtC,aAAa,CAAC,CAAC,EAAE,4BAA4B,CAAC;KAC9C,MAAM,EAAE;KACR,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE;IACxB,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC;KACD,IAAI,EAAE;KACN,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;KAClB,MAAM,CAAC,iFAAiF,CAAC,CAAC;AAE7F,qBAAqB;AACrB,GAAG,CAAC,OAAO,CACT,qBAAqB,EACrB,qDAAqD,EACrD,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE;QAChC,QAAQ,EAAE,iDAAiD;QAC3D,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,iBAAiB,CAAC,IAAI,CAAC,MAAgB,CAAC,CAAC;AACjD,CAAC,CACF,CAAC;AAEF,eAAe;AACf,GAAG,CAAC,OAAO,CACT,YAAY,EACZ,gFAAgF,EAChF,CAAC,KAAK,EAAE,EAAE;IACR,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE;QAC7B,QAAQ,EAAE,kDAAkD;QAC5D,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC,CAAC;AACL,CAAC,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;IACb,MAAM,WAAW,CAAC,IAAI,CAAC,GAAa,CAAC,CAAC;AACxC,CAAC,CACF,CAAC;AAEF,oBAAoB;AACpB,GAAG,CAAC,KAAK,EAAE,CAAC"}

package/package.json

@@ -1,12 +1,24 @@
 {
   "name": "@myerscarpenter/quest-dev",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "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",
+  "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"
+  },
   "keywords": [
     "meta",
     "quest",
@@ -47,17 +59,5 @@
     "@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/index.ts

@@ -39,7 +39,7 @@ const cli = yargs(hideBin(process.argv))
   })
   .help()
   .alias('help', 'h')
-  .epilog('Requires ADB to be installed and Quest connected via USB with debugging enabled.');
+  .epilog('Requires ADB and Quest connected via USB. Sets up CDP on port 9223 for cdp-cli.');
 
 // Screenshot command
 cli.command(
@@ -60,7 +60,7 @@ cli.command(
 // Open command
 cli.command(
   'open <url>',
-  'Open URL in Quest browser with ADB port forwarding',
+  'Open URL in Quest browser (sets up dev server + CDP debugging port forwarding)',
   (yargs) => {
     return yargs.positional('url', {
       describe: 'URL to open (e.g., http://localhost:9004/myapp/)',

package/tests/adb.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { isPortListening, getCDPPort } from '../src/utils/adb.js';
+import net from 'net';
+
+describe('isPortListening', () => {
+  it('should return false for a port that is not listening', async () => {
+    // Use a high port number unlikely to be in use
+    const result = await isPortListening(59999);
+    expect(result).toBe(false);
+  });
+
+  it('should return true for a port that is listening', async () => {
+    // Create a temporary server
+    const server = net.createServer();
+    await new Promise<void>((resolve) => {
+      server.listen(0, '127.0.0.1', () => resolve());
+    });
+
+    const address = server.address() as net.AddressInfo;
+    const port = address.port;
+
+    const result = await isPortListening(port);
+    expect(result).toBe(true);
+
+    // Clean up
+    server.close();
+  });
+});
+
+describe('getCDPPort', () => {
+  it('should return the default CDP port', () => {
+    const port = getCDPPort();
+    expect(port).toBe(9223);
+  });
+});

package/tests/exec.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { execCommand, execCommandFull } from '../src/utils/exec.js';
+
+describe('execCommand', () => {
+  it('should execute a simple command and return stdout', async () => {
+    const result = await execCommand('echo', ['hello']);
+    expect(result.trim()).toBe('hello');
+  });
+
+  it('should reject on non-zero exit code', async () => {
+    await expect(execCommand('sh -c "exit 1"', [])).rejects.toThrow();
+  });
+
+  it('should handle shell commands', async () => {
+    const result = await execCommand('echo', ['foo bar']);
+    expect(result.trim()).toBe('foo bar');
+  });
+});
+
+describe('execCommandFull', () => {
+  it('should return full result with exit code 0 on success', async () => {
+    const result = await execCommandFull('echo', ['test']);
+    expect(result.code).toBe(0);
+    expect(result.stdout.trim()).toBe('test');
+  });
+
+  it('should return non-zero exit code without throwing', async () => {
+    const result = await execCommandFull('sh -c "exit 42"', []);
+    expect(result.code).toBe(42);
+  });
+
+  it('should capture stderr', async () => {
+    const result = await execCommandFull('sh -c "echo error >&2"', []);
+    expect(result.stderr.trim()).toBe('error');
+  });
+});