@myerscarpenter/quest-dev 1.4.0 → 2.0.0

package/src/utils/filename.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { generateScreenshotFilename } from './filename.js';
+import { generateScreenshotFilename, slugifyCaption } from './filename.js';
 
 describe('generateScreenshotFilename', () => {
   it('formats UTC timestamp correctly', () => {
@@ -24,6 +24,24 @@ describe('generateScreenshotFilename', () => {
       .toBe('screenshot-2026-12-31-00-00-00-Z.jpg');
   });
 
+  it('includes slugified caption in filename', () => {
+    const date = new Date('2026-01-15T14:30:45Z');
+    expect(generateScreenshotFilename(date, 'Main Menu Screenshot'))
+      .toBe('screenshot-2026-01-15-14-30-45-Z-main-menu-screenshot.jpg');
+  });
+
+  it('truncates long captions to 25 chars', () => {
+    const date = new Date('2026-01-15T14:30:45Z');
+    expect(generateScreenshotFilename(date, 'This is a very long caption that should be truncated'))
+      .toBe('screenshot-2026-01-15-14-30-45-Z-this-is-a-very-long-capti.jpg');
+  });
+
+  it('omits slug when no caption provided', () => {
+    const date = new Date('2026-01-15T14:30:45Z');
+    expect(generateScreenshotFilename(date))
+      .toBe('screenshot-2026-01-15-14-30-45-Z.jpg');
+  });
+
   it('generates filename with current time when no date provided', () => {
     const filename = generateScreenshotFilename();
 
@@ -53,3 +71,25 @@ describe('generateScreenshotFilename', () => {
     }
   });
 });
+
+describe('slugifyCaption', () => {
+  it('lowercases and replaces spaces with dashes', () => {
+    expect(slugifyCaption('Main Menu')).toBe('main-menu');
+  });
+
+  it('replaces non-alphanumeric with dashes', () => {
+    expect(slugifyCaption('Hello, World! #1')).toBe('hello-world-1');
+  });
+
+  it('collapses consecutive dashes', () => {
+    expect(slugifyCaption('foo---bar')).toBe('foo-bar');
+  });
+
+  it('trims leading and trailing dashes', () => {
+    expect(slugifyCaption('--hello--')).toBe('hello');
+  });
+
+  it('truncates to 25 chars without trailing dash', () => {
+    expect(slugifyCaption('this is a very long caption that exceeds')).toBe('this-is-a-very-long-capti');
+  });
+});

package/src/utils/filename.ts

@@ -2,11 +2,25 @@
  * Filename generation utilities for screenshots
  */
 
+/**
+ * Slugify a caption for use in filenames.
+ * Lowercase, replace non-alphanumeric with dashes, collapse runs, trim, truncate to 25 chars.
+ */
+export function slugifyCaption(caption: string): string {
+  return caption
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 25)
+    .replace(/-$/, "");
+}
+
 /**
  * Generate UTC timestamp filename
  * Format: screenshot-YYYY-MM-DD-HH-MM-SS-Z.jpg
+ * With caption: screenshot-YYYY-MM-DD-HH-MM-SS-Z-slug.jpg
  */
-export function generateScreenshotFilename(date: Date = new Date()): string {
+export function generateScreenshotFilename(date: Date = new Date(), caption?: string): string {
   const year = date.getUTCFullYear();
   const month = String(date.getUTCMonth() + 1).padStart(2, '0');
   const day = String(date.getUTCDate()).padStart(2, '0');
@@ -14,5 +28,7 @@ export function generateScreenshotFilename(date: Date = new Date()): string {
   const minutes = String(date.getUTCMinutes()).padStart(2, '0');
   const seconds = String(date.getUTCSeconds()).padStart(2, '0');
 
-  return `screenshot-${year}-${month}-${day}-${hours}-${minutes}-${seconds}-Z.jpg`;
+  const base = `screenshot-${year}-${month}-${day}-${hours}-${minutes}-${seconds}-Z`;
+  const slug = caption ? slugifyCaption(caption) : "";
+  return slug ? `${base}-${slug}.jpg` : `${base}.jpg`;
 }

package/src/utils/jpeg-comment.ts

@@ -0,0 +1,30 @@
+/**
+ * JPEG COM marker insertion.
+ * Inserts a COM (0xFFFE) marker after the SOI marker without re-encoding.
+ */
+
+import { readFileSync, writeFileSync } from "fs";
+
+/**
+ * Insert a COM comment marker into a JPEG buffer.
+ * Splices after the SOI (FF D8) marker — no re-encoding, no quality loss.
+ */
+export function insertJpegComment(jpeg: Buffer, comment: string): Buffer {
+  if (jpeg[0] !== 0xff || jpeg[1] !== 0xd8) {
+    throw new Error("Not a valid JPEG (missing SOI marker)");
+  }
+  const payload = Buffer.from(comment, "utf-8");
+  const marker = Buffer.alloc(4);
+  marker.writeUInt16BE(0xfffe, 0);
+  marker.writeUInt16BE(payload.length + 2, 2);
+  return Buffer.concat([jpeg.subarray(0, 2), marker, payload, jpeg.subarray(2)]);
+}
+
+/**
+ * Add a COM comment to a JPEG file in-place.
+ */
+export function addJpegFileComment(filePath: string, comment: string): void {
+  const jpeg = readFileSync(filePath);
+  const result = insertJpegComment(jpeg, comment);
+  writeFileSync(filePath, result);
+}

package/src/utils/test-properties.ts

@@ -0,0 +1,94 @@
+/**
+ * Meta Scriptable Testing API (content://com.oculus.rc) utilities.
+ *
+ * Shared between stay-awake and cast commands for managing test mode
+ * properties (guardian, autosleep, dialogs, proximity).
+ */
+
+import { execCommand, execCommandFull } from "./exec.js";
+import { adbArgs } from "./adb.js";
+
+export interface TestProperties {
+  disable_guardian: boolean;
+  disable_dialogs: boolean;
+  disable_autosleep: boolean;
+  set_proximity_close: boolean;
+}
+
+/**
+ * Build ADB args for SET_PROPERTY call.
+ */
+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}`,
+  ];
+}
+
+/**
+ * Parse GET_PROPERTY Bundle output into structured data.
+ * Input: "Bundle[{disable_guardian=true, set_proximity_close=true, ...}]"
+ */
+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[key as keyof TestProperties] = value === "true";
+    }
+  }
+
+  return defaults;
+}
+
+/**
+ * Call SET_PROPERTY to enable or disable test mode.
+ */
+export async function setTestProperties(
+  pin: string,
+  enabled: boolean,
+): Promise<void> {
+  const args = adbArgs(...buildSetPropertyArgs(pin, enabled));
+  await execCommand("adb", args);
+}
+
+/**
+ * Call GET_PROPERTY and return parsed test properties.
+ */
+export async function getTestProperties(): Promise<TestProperties> {
+  const result = await execCommandFull("adb", adbArgs(
+    "shell", "content", "call",
+    "--uri", "content://com.oculus.rc",
+    "--method", "GET_PROPERTY",
+  ));
+  return parseTestProperties(result.stdout);
+}
+
+/**
+ * Format test properties for display.
+ */
+export 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");
+}

package/src/utils/verbose.ts

@@ -0,0 +1,14 @@
+/**
+ * Global verbose flag for debug output
+ */
+let _verbose = false;
+
+export function setVerbose(v: boolean): void {
+  _verbose = v;
+}
+
+export function verbose(...args: unknown[]): void {
+  if (_verbose) {
+    console.log('[verbose]', ...args);
+  }
+}

package/tests/cast/auto-layer.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * Auto-layer selection logic extracted from CastSession.
+ * Bug: when layer.id === 0 and is PANEL_APP, the condition
+ * `this._layerId === 0` is true, so it "selects" layer 0
+ * which is a no-op (already 0).  It should instead track
+ * whether a layer was ever explicitly selected.
+ */
+
+const LAYER_PANEL_APP = 0;
+const LAYER_EYE_BUFFER = 1;
+
+interface Layer {
+  id: number;
+  type: number;
+}
+
+function autoSelectLayer(
+  layers: Layer[],
+  currentLayerId: number,
+  hasAutoSelected: boolean,
+): { layerId: number; hasAutoSelected: boolean } {
+  let layerId = currentLayerId;
+  let selected = hasAutoSelected;
+  for (const layer of layers) {
+    if (layer.type === LAYER_PANEL_APP && !selected) {
+      layerId = layer.id;
+      selected = true;
+    }
+  }
+  return { layerId, hasAutoSelected: selected };
+}
+
+describe("auto-layer selection", () => {
+  it("selects first PANEL_APP layer", () => {
+    const result = autoSelectLayer(
+      [{ id: 5, type: LAYER_PANEL_APP }],
+      0,
+      false,
+    );
+    expect(result.layerId).toBe(5);
+    expect(result.hasAutoSelected).toBe(true);
+  });
+
+  it("selects PANEL_APP with id 0", () => {
+    const result = autoSelectLayer(
+      [{ id: 0, type: LAYER_PANEL_APP }],
+      0,
+      false,
+    );
+    // Should still mark as selected even when id is 0
+    expect(result.layerId).toBe(0);
+    expect(result.hasAutoSelected).toBe(true);
+  });
+
+  it("does not re-select after first auto-selection", () => {
+    const result = autoSelectLayer(
+      [
+        { id: 5, type: LAYER_PANEL_APP },
+        { id: 9, type: LAYER_PANEL_APP },
+      ],
+      0,
+      false,
+    );
+    expect(result.layerId).toBe(5); // first one wins
+  });
+
+  it("does not override manual selection", () => {
+    const result = autoSelectLayer(
+      [{ id: 5, type: LAYER_PANEL_APP }],
+      3, // manually set
+      true, // already selected
+    );
+    expect(result.layerId).toBe(3); // unchanged
+  });
+
+  it("ignores non-PANEL_APP layers", () => {
+    const result = autoSelectLayer(
+      [{ id: 2, type: LAYER_EYE_BUFFER }],
+      0,
+      false,
+    );
+    expect(result.layerId).toBe(0);
+    expect(result.hasAutoSelected).toBe(false);
+  });
+});

package/tests/cast/decoder.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { extractJpegFrames } from "../../src/cast/decoder.js";
+
+describe("extractJpegFrames", () => {
+  const SOI = Buffer.from([0xff, 0xd8]);
+  const EOI = Buffer.from([0xff, 0xd9]);
+
+  function makeJpeg(bodySize: number): Buffer {
+    const body = Buffer.alloc(bodySize, 0x42);
+    return Buffer.concat([SOI, body, EOI]);
+  }
+
+  it("returns no frames from empty buffer", () => {
+    const result = extractJpegFrames(Buffer.alloc(0));
+    expect(result.frames).toHaveLength(0);
+    expect(result.remainder.length).toBe(0);
+  });
+
+  it("returns no frames from buffer without markers", () => {
+    const result = extractJpegFrames(Buffer.alloc(100, 0x42));
+    expect(result.frames).toHaveLength(0);
+    expect(result.remainder.length).toBe(0);
+  });
+
+  it("extracts a single complete JPEG frame", () => {
+    const jpeg = makeJpeg(10);
+    const result = extractJpegFrames(jpeg);
+    expect(result.frames).toHaveLength(1);
+    expect(result.frames[0]).toEqual(jpeg);
+    expect(result.remainder.length).toBe(0);
+  });
+
+  it("extracts multiple JPEG frames", () => {
+    const j1 = makeJpeg(5);
+    const j2 = makeJpeg(8);
+    const buf = Buffer.concat([j1, j2]);
+    const result = extractJpegFrames(buf);
+    expect(result.frames).toHaveLength(2);
+    expect(result.frames[0]).toEqual(j1);
+    expect(result.frames[1]).toEqual(j2);
+    expect(result.remainder.length).toBe(0);
+  });
+
+  it("handles partial frame (SOI without EOI)", () => {
+    const partial = Buffer.concat([SOI, Buffer.alloc(10, 0x42)]);
+    const result = extractJpegFrames(partial);
+    expect(result.frames).toHaveLength(0);
+    expect(result.remainder).toEqual(partial);
+  });
+
+  it("extracts complete frame and keeps partial remainder", () => {
+    const complete = makeJpeg(5);
+    const partial = Buffer.concat([SOI, Buffer.alloc(3, 0x42)]);
+    const buf = Buffer.concat([complete, partial]);
+    const result = extractJpegFrames(buf);
+    expect(result.frames).toHaveLength(1);
+    expect(result.frames[0]).toEqual(complete);
+    expect(result.remainder).toEqual(partial);
+  });
+
+  it("skips garbage before SOI", () => {
+    const garbage = Buffer.alloc(20, 0xab);
+    const jpeg = makeJpeg(5);
+    const buf = Buffer.concat([garbage, jpeg]);
+    const result = extractJpegFrames(buf);
+    expect(result.frames).toHaveLength(1);
+    expect(result.frames[0]).toEqual(jpeg);
+  });
+
+  it("handles zero-length body JPEG", () => {
+    const jpeg = Buffer.concat([SOI, EOI]);
+    const result = extractJpegFrames(jpeg);
+    expect(result.frames).toHaveLength(1);
+    expect(result.frames[0]).toEqual(jpeg);
+  });
+
+  it("handles buffer that is just SOI", () => {
+    const result = extractJpegFrames(SOI);
+    expect(result.frames).toHaveLength(0);
+    expect(result.remainder).toEqual(SOI);
+  });
+});

package/tests/cast/session-restart.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { createServer, type Server, type Socket } from "node:net";
+
+/**
+ * Bug: session.restart() calls stop() which closes the TCP server,
+ * then calls start() which expects the server to be listening.
+ * The server must be re-bound (listen again) after close.
+ *
+ * We test the core invariant: after restart(), the server is listening.
+ */
+
+describe("TCP server re-bind after close", () => {
+  let server: Server;
+  let port: number;
+
+  beforeEach(async () => {
+    server = createServer();
+    // Bind to random port
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    port = (server.address() as { port: number }).port;
+  });
+
+  it("closed server does not accept connections", async () => {
+    server.close();
+    // Wait for close to complete
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Try to connect — should fail
+    const result = await new Promise<string>((resolve) => {
+      const sock = new (require("node:net").Socket)();
+      sock.on("error", () => resolve("refused"));
+      sock.on("connect", () => { sock.destroy(); resolve("connected"); });
+      sock.connect(port, "127.0.0.1");
+    });
+    expect(result).toBe("refused");
+  });
+
+  it("server can re-listen after close", async () => {
+    // Close then re-listen on same port
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await new Promise<void>((resolve, reject) => {
+      server.listen(port, "127.0.0.1", () => resolve());
+      server.on("error", reject);
+    });
+
+    // Should accept connections again
+    const result = await new Promise<string>((resolve) => {
+      const sock = new (require("node:net").Socket)();
+      sock.on("error", () => resolve("refused"));
+      sock.on("connect", () => { sock.destroy(); resolve("connected"); });
+      sock.connect(port, "127.0.0.1");
+    });
+    expect(result).toBe("connected");
+    server.close();
+  });
+});
+
+describe("connection count guard", () => {
+  it("should only process exactly 2 connections", () => {
+    const sockets: string[] = [];
+    let controlSocket: string | null = null;
+    let videoSocket: string | null = null;
+    let assignCount = 0;
+
+    // Simulates fixed connection handler using === 2
+    function onConnection(id: string) {
+      sockets.push(id);
+      if (sockets.length === 2) {
+        controlSocket = sockets[0];
+        videoSocket = sockets[1];
+        assignCount++;
+      }
+    }
+
+    onConnection("sock-a");
+    onConnection("sock-b");
+    onConnection("sock-c"); // spurious 3rd connection
+
+    expect(assignCount).toBe(1); // assigned exactly once
+    expect(controlSocket).toBe("sock-a");
+    expect(videoSocket).toBe("sock-b");
+  });
+
+  it("bug: >= 2 fires on every subsequent connection", () => {
+    const sockets: string[] = [];
+    let videoSocket: string | null = null;
+    let assignCount = 0;
+
+    // Old buggy handler using >= 2
+    function onConnection(id: string) {
+      sockets.push(id);
+      if (sockets.length >= 2) {
+        videoSocket = sockets[1];
+        assignCount++;
+      }
+    }
+
+    onConnection("sock-a");
+    onConnection("sock-b");
+    onConnection("sock-c"); // spurious 3rd
+
+    expect(assignCount).toBe(2); // BUG: assigned twice
+    expect(videoSocket).toBe("sock-b"); // at least video isn't overwritten to sock-c since sockets[1] is stable
+  });
+});

package/tests/config.test.ts

@@ -11,7 +11,7 @@ beforeEach(() => {
 });
 
 describe('loadConfig', () => {
-  it('returns empty object when no config files exist', () => {
+  it('returns empty object when no config file exists', () => {
     mockReadFileSync.mockImplementation(() => {
       throw new Error('ENOENT');
     });
@@ -20,31 +20,32 @@ describe('loadConfig', () => {
     expect(config).toEqual({});
   });
 
-  it('reads .quest-dev.json from cwd when present', () => {
+  it('reads ~/.config/quest-dev/config.json', () => {
     mockReadFileSync.mockImplementation((path) => {
-      if (String(path).endsWith('.quest-dev.json')) {
-        return JSON.stringify({ pin: '1234' });
+      if (String(path).endsWith('config.json')) {
+        return JSON.stringify({ pin: '1234', port: 8091 });
       }
       throw new Error('ENOENT');
     });
 
     const config = loadConfig();
     expect(config.pin).toBe('1234');
+    expect(config.port).toBe(8091);
   });
 
-  it('merges configs: local file wins over global file', () => {
-    mockReadFileSync.mockImplementation((path) => {
-      if (String(path).endsWith('.quest-dev.json')) {
-        return JSON.stringify({ pin: 'local-pin', idleTimeout: 5000 });
-      }
-      if (String(path).endsWith('config.json')) {
-        return JSON.stringify({ pin: 'global-pin', lowBattery: 15 });
-      }
-      throw new Error('ENOENT');
-    });
+  it('returns all config fields', () => {
+    mockReadFileSync.mockReturnValue(JSON.stringify({
+      pin: 'test-pin',
+      port: 9000,
+      device: '192.168.1.100',
+      idleTimeout: 5000,
+      lowBattery: 15,
+    }));
 
     const config = loadConfig();
-    expect(config.pin).toBe('local-pin');
+    expect(config.pin).toBe('test-pin');
+    expect(config.port).toBe(9000);
+    expect(config.device).toBe('192.168.1.100');
     expect(config.idleTimeout).toBe(5000);
     expect(config.lowBattery).toBe(15);
   });
@@ -52,18 +53,12 @@ describe('loadConfig', () => {
 
 describe('loadPin', () => {
   it('returns CLI pin when provided', () => {
-    // Should not even read config files
     const pin = loadPin('cli-pin');
     expect(pin).toBe('cli-pin');
   });
 
   it('falls back to config file pin', () => {
-    mockReadFileSync.mockImplementation((path) => {
-      if (String(path).endsWith('.quest-dev.json')) {
-        return JSON.stringify({ pin: 'config-pin' });
-      }
-      throw new Error('ENOENT');
-    });
+    mockReadFileSync.mockReturnValue(JSON.stringify({ pin: 'config-pin' }));
 
     const pin = loadPin();
     expect(pin).toBe('config-pin');

package/tests/daemon/api-status.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from "vitest";
+
+/**
+ * Bug: Dashboard api() helper doesn't check HTTP status codes.
+ * A 500 response with HTML body would throw an uncaught JSON parse error.
+ * Fix: check response.ok before parsing JSON.
+ */
+
+/** Fixed api helper that checks HTTP status. */
+async function apiFetch(
+  fetcher: typeof fetch,
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<unknown> {
+  const opts: RequestInit = { method };
+  if (body) {
+    opts.headers = { "Content-Type": "application/json" };
+    opts.body = JSON.stringify(body);
+  }
+  const r = await fetcher(path, opts);
+  if (!r.ok) {
+    // Try to parse JSON error, fall back to status text
+    let msg: string;
+    try {
+      const json = await r.json();
+      msg = json.error ?? r.statusText;
+    } catch {
+      msg = r.statusText;
+    }
+    throw new Error(`HTTP ${r.status}: ${msg}`);
+  }
+  return r.json();
+}
+
+function mockFetch(status: number, body: unknown, contentType = "application/json"): typeof fetch {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 500 ? "Internal Server Error" : "OK",
+    json: () => Promise.resolve(body),
+    headers: new Headers({ "content-type": contentType }),
+  }) as unknown as typeof fetch;
+}
+
+describe("api fetch with status checking", () => {
+  it("returns JSON on 200", async () => {
+    const f = mockFetch(200, { ok: true });
+    const result = await apiFetch(f, "GET", "/status");
+    expect(result).toEqual({ ok: true });
+  });
+
+  it("throws on 500 with JSON error body", async () => {
+    const f = mockFetch(500, { error: "something broke" });
+    await expect(apiFetch(f, "POST", "/cast/start")).rejects.toThrow(
+      "HTTP 500: something broke",
+    );
+  });
+
+  it("throws on 503 with fallback to statusText", async () => {
+    const f = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 503,
+      statusText: "Service Unavailable",
+      json: () => Promise.reject(new Error("not json")),
+    }) as unknown as typeof fetch;
+
+    await expect(apiFetch(f, "GET", "/cast/screenshot")).rejects.toThrow(
+      "HTTP 503: Service Unavailable",
+    );
+  });
+
+  it("passes body correctly", async () => {
+    const f = mockFetch(200, { ok: true });
+    await apiFetch(f, "POST", "/cast/pose", { dz: 0.3 });
+    expect(f).toHaveBeenCalledWith("/cast/pose", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: '{"dz":0.3}',
+    });
+  });
+});