@houwert/conductor 0.19.1 → 0.21.0

package/README.md

@@ -38,7 +38,18 @@ One agent writes the feature. Another taps through the app. They talk. It works.
 npm install -g @houwert/conductor
 ```
 
-That's it. Conductor is a pure CLI — no Claude Code plugin or skill is registered. Wire it into your agent however you like (a custom `CLAUDE.md`, a project skill, a slash command — it's up to you). Run `conductor --help` for the full command reference, or `conductor <command> --help` for per-command flags.
+That's it. Conductor is a pure CLI. To teach an AI agent how to use it, set up the bundled skills in your repo:
+
+```bash
+conductor init            # interactive: pick scope + skills, writes them into .claude/skills/
+conductor init --yes      # non-interactive: install all skills into ./.claude/skills/
+conductor init --global   # install into ~/.claude/skills/ for all repos
+conductor init --force    # re-sync skills you've already installed
+```
+
+`init` is the one manual setup step — run it once per repo. In a terminal it walks you through which skills and where; piped or headless (CI/agent) it installs everything non-interactively. It drops a set of capability-scoped Claude Code skills — `conductor-device-interact`, `conductor-inspect`, `conductor-create-flow`, `conductor-metro-debugger`, `conductor-profiler`, and `conductor-device-setup` — that document every command and the act → observe → act workflow.
+
+When you upgrade conductor, re-run `conductor init --force` to re-sync the installed skills (it stamps the installed version, so `init` tells you when they're out of date, and prunes any skills no longer shipped). Or wire it in however you like (a custom `CLAUDE.md`, a slash command — it's up to you). Run `conductor --help` for the full command reference, or `conductor <command> --help` for per-command flags.
 
 ### 📱 What the CLI can do
 
@@ -52,6 +63,7 @@ That's it. Conductor is a pure CLI — no Claude Code plugin or skill is registe
 | Flows | `run-flow`, `run-flow-inline`, `run-parallel` |
 | Devices | `start-device`, `list-devices`, `set-location`, `set-orientation` |
 | Web setup | `install-web [browser]` (installs a Playwright browser; `--check` prints status) |
+| Discovery | `list-options [command]` / `<command> --options` (valid values for enumerated params) |
 
 ## 🔨 Building locally
 

package/dist/commands/capture-ui.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.captureUI = captureUI;
-exports.HELP = `  capture-ui [--output <path>]         Capture screenshot + hierarchy + a11y snapshot (for Argus UI panel)`;
+exports.HELP = `  capture-ui [--output <path.json>]    Capture screenshot + hierarchy + a11y snapshot as a JSON bundle (for Argus UI panel)`;
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const runner_js_1 = require("../runner.js");
@@ -17,6 +17,19 @@ const a11y_js_1 = require("../drivers/a11y.js");
 const snapshot_store_js_1 = require("../snapshot-store.js");
 async function captureUI(outputPath, opts = {}, sessionName = 'default') {
     try {
+        // capture-ui always emits a JSON bundle (screenshot is embedded as base64).
+        // Reject non-JSON output paths up front so a `.png`/`.jpg` mistake doesn't
+        // silently produce an image-named file full of JSON. Use take-screenshot
+        // for an actual image.
+        if (outputPath) {
+            const ext = path_1.default.extname(outputPath).toLowerCase();
+            if (ext && ext !== '.json') {
+                (0, output_js_1.printError)(`capture-ui — \`--output\` must be a .json path (got "${ext}"). ` +
+                    `capture-ui writes a JSON bundle (screenshot + hierarchy + a11y snapshot), not an image. ` +
+                    `Use \`take-screenshot\` to save an image file.`, opts);
+                return 1;
+            }
+        }
         const driver = await (0, runner_js_1.getDriver)(sessionName);
         const capturedAt = new Date().toISOString();
         let platform;

package/dist/commands/debug.js

@@ -11,7 +11,7 @@ exports.debugInspectElement = debugInspectElement;
 exports.debugLogRegistry = debugLogRegistry;
 exports.debugReload = debugReload;
 exports.HELP = `  debug status [--port N]              Show RN debugger connection info
-  debug evaluate <expr> [--port N]     Run JS in the app runtime (Hermes/Fusebox)
+  debug evaluate <expr> [--port N]     Run JS in the app runtime (RN: Hermes/Fusebox; web: page context)
   debug component-tree [--port N]      Print the React component tree (on-screen)
   debug inspect-element <x,y>          Print the React component at a screen point
   debug log-registry [--source metro]  Summarize recent Metro/Hermes console logs`;
@@ -22,6 +22,18 @@ const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const metro_js_1 = require("../drivers/log-sources/metro.js");
 const metro_scripts_js_1 = require("../drivers/metro-scripts.js");
 const logs_js_1 = require("./logs.js");
+const runner_js_1 = require("../runner.js");
+const web_js_1 = require("../drivers/web.js");
+/** Resolve the web driver when this session targets a web device, else null (→ Metro path). */
+async function webDriverFor(sessionName) {
+    if (!sessionName || sessionName === 'default')
+        return null;
+    const platform = await (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined);
+    if (platform !== 'web')
+        return null;
+    const driver = await (0, runner_js_1.getDriver)(sessionName);
+    return driver instanceof web_js_1.WebDriver ? driver : null;
+}
 function newRequestId() {
     return crypto_1.default.randomBytes(6).toString('hex');
 }
@@ -88,6 +100,26 @@ async function debugEvaluate(expr, opts, sessionName, debugOpts) {
         (0, output_js_1.printError)('debug evaluate requires a JS expression', opts);
         return 1;
     }
+    // Web: evaluate in the page runtime via Playwright (no Metro/Hermes).
+    const web = await webDriverFor(sessionName);
+    if (web) {
+        try {
+            const { result, error } = await web.evaluate(expr);
+            if (error) {
+                (0, output_js_1.printError)(`debug evaluate — ${error}`, opts);
+                return 1;
+            }
+            if (opts.json)
+                (0, output_js_1.printData)({ result }, opts);
+            else
+                console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+            return 0;
+        }
+        catch (err) {
+            (0, output_js_1.printError)(`debug evaluate — ${err instanceof Error ? err.message : String(err)}`, opts);
+            return 1;
+        }
+    }
     const port = debugOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     try {

package/dist/commands/init.js

@@ -0,0 +1,240 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.init = init;
+exports.HELP = `  init [target-dir]                    Set up conductor in a repo: install the agent skills into .claude/skills/
+                                       Interactive when run in a terminal; non-interactive otherwise.
+    --global                          Install into ~/.claude/skills/ instead of the current repo
+    --force                           Re-sync skills that are already installed (overwrite)
+    --yes, -y                         Skip prompts and accept defaults (install all skills)`;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_1 = __importDefault(require("readline/promises"));
+const output_js_1 = require("../output.js");
+const pkg_root_js_1 = require("../pkg-root.js");
+/** Skills conductor installs are namespaced with this prefix; prune is bounded to it. */
+const SKILL_PREFIX = 'conductor-';
+/** Records what conductor installed into a skills dir, so we can detect staleness and prune. */
+const MANIFEST_FILE = '.conductor-skills.json';
+/**
+ * The skill templates ship inside the published package under `skills/`
+ * (declared in package.json `files`), one directory per `conductor-<capability>`
+ * skill, each containing a SKILL.md. `findPkgRoot` resolves the package root for
+ * both the production build (dist/) and the test build (which has an extra `src/`
+ * path level), mirroring how the bundled drivers are located.
+ */
+function bundledSkillsRoot() {
+    return path_1.default.join((0, pkg_root_js_1.findPkgRoot)(__dirname), 'skills');
+}
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join((0, pkg_root_js_1.findPkgRoot)(__dirname), 'package.json'), 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Enumerate bundled skill directories (those containing a SKILL.md). */
+function listBundledSkills(skillsRoot) {
+    if (!fs_1.default.existsSync(skillsRoot))
+        return [];
+    return fs_1.default
+        .readdirSync(skillsRoot)
+        .filter((name) => fs_1.default.existsSync(path_1.default.join(skillsRoot, name, 'SKILL.md')))
+        .sort();
+}
+function readManifest(destRoot) {
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(path_1.default.join(destRoot, MANIFEST_FILE), 'utf-8'));
+        if (raw && Array.isArray(raw.skills)) {
+            return { version: String(raw.version ?? 'unknown'), skills: raw.skills.map(String) };
+        }
+    }
+    catch {
+        /* missing or corrupt → treat as no prior install */
+    }
+    return null;
+}
+function writeManifest(destRoot, manifest) {
+    fs_1.default.mkdirSync(destRoot, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(destRoot, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + '\n');
+}
+function copySkill(srcDir, destDir) {
+    fs_1.default.mkdirSync(destDir, { recursive: true });
+    for (const entry of fs_1.default.readdirSync(srcDir)) {
+        const from = path_1.default.join(srcDir, entry);
+        if (!fs_1.default.statSync(from).isFile())
+            continue;
+        fs_1.default.copyFileSync(from, path_1.default.join(destDir, entry));
+    }
+}
+/**
+ * Remove skills conductor previously installed that are no longer bundled (renamed
+ * or dropped). Bounded to skills recorded in our manifest and the `conductor-`
+ * prefix, so it never touches user-authored or third-party skills.
+ */
+function pruneOrphans(destRoot, prev, bundled) {
+    if (!prev)
+        return [];
+    const pruned = [];
+    for (const name of prev.skills) {
+        if (!name.startsWith(SKILL_PREFIX) || bundled.has(name))
+            continue;
+        const dir = path_1.default.join(destRoot, name);
+        if (fs_1.default.existsSync(dir)) {
+            fs_1.default.rmSync(dir, { recursive: true, force: true });
+            pruned.push(name);
+        }
+    }
+    return pruned;
+}
+function resolveDestRoot(global, targetDir) {
+    return global
+        ? path_1.default.join(os_1.default.homedir(), '.claude', 'skills')
+        : path_1.default.join(path_1.default.resolve(targetDir ?? process.cwd()), '.claude', 'skills');
+}
+/**
+ * Setting up conductor is the one manual, human-driven step — so when `init` runs
+ * in a real terminal we walk the dev through scope and skill selection, the way
+ * argent's wizard does. Headless/agent/CI runs (no TTY, --json, or --yes) take the
+ * non-interactive path with sensible defaults: all skills, project scope.
+ */
+async function promptPlan(skills, version, targetDir, flags) {
+    const rl = promises_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // Scope — skip the prompt if the flags already decided it.
+        let global = flags.global;
+        if (!flags.global && targetDir === undefined) {
+            const ans = (await rl.question('Where should the skills be installed?\n' +
+                '  1) This project (./.claude/skills)  [default]\n' +
+                '  2) Globally (~/.claude/skills)\n' +
+                '> ')).trim();
+            global = ans === '2';
+        }
+        const destRoot = resolveDestRoot(global, targetDir);
+        // Skill selection.
+        let selected = skills;
+        const sel = (await rl.question(`\nInstall all ${skills.length} skills, or choose a subset?\n` +
+            '  1) All  [default]\n' +
+            '  2) Select\n' +
+            '> ')).trim();
+        if (sel === '2') {
+            skills.forEach((name, i) => console.log(`  ${i + 1}) ${name}`));
+            const picks = (await rl.question('Enter numbers (comma-separated): ')).trim();
+            const chosen = picks
+                .split(',')
+                .map((s) => parseInt(s.trim(), 10) - 1)
+                .filter((i) => i >= 0 && i < skills.length)
+                .map((i) => skills[i]);
+            if (chosen.length > 0)
+                selected = [...new Set(chosen)];
+        }
+        // Offer to re-sync already-installed skills. If they're from an older
+        // conductor, say so and default to yes; otherwise default to no.
+        let force = flags.force;
+        if (!force) {
+            const existing = selected.filter((name) => fs_1.default.existsSync(path_1.default.join(destRoot, name)));
+            if (existing.length > 0) {
+                const prev = readManifest(destRoot);
+                const stale = prev !== null && prev.version !== version;
+                const prompt = stale
+                    ? `\n${existing.length} installed skill(s) are from conductor v${prev?.version} (this is v${version}). Re-sync (overwrite) them? [Y/n] `
+                    : `\n${existing.length} of these are already installed. Re-sync (overwrite) them? [y/N] `;
+                const ans = (await rl.question(prompt)).trim().toLowerCase();
+                force = stale ? ans !== 'n' && ans !== 'no' : ans === 'y' || ans === 'yes';
+            }
+        }
+        return { destRoot, selected, force };
+    }
+    finally {
+        rl.close();
+    }
+}
+async function init(opts, targetDir, flags) {
+    try {
+        if (targetDir !== undefined && flags.global) {
+            (0, output_js_1.printError)('init: pass a target directory or --global, not both.', opts);
+            return 1;
+        }
+        const srcRoot = bundledSkillsRoot();
+        const skills = listBundledSkills(srcRoot);
+        if (skills.length === 0) {
+            (0, output_js_1.printError)(`No bundled skill templates found at ${srcRoot}`, opts);
+            return 1;
+        }
+        const version = packageVersion();
+        const bundledSet = new Set(skills);
+        const interactive = !opts.json && !flags.yes && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+        const plan = interactive
+            ? await promptPlan(skills, version, targetDir, flags)
+            : {
+                destRoot: resolveDestRoot(flags.global, targetDir),
+                selected: skills,
+                force: flags.force,
+            };
+        const prev = readManifest(plan.destRoot);
+        const installed = [];
+        const skipped = [];
+        for (const name of plan.selected) {
+            const destDir = path_1.default.join(plan.destRoot, name);
+            if (fs_1.default.existsSync(destDir) && !plan.force) {
+                skipped.push(name);
+                continue;
+            }
+            copySkill(path_1.default.join(srcRoot, name), destDir);
+            installed.push(name);
+        }
+        // Remove skills we previously installed that are no longer bundled.
+        const pruned = pruneOrphans(plan.destRoot, prev, bundledSet);
+        // Update the manifest. Only claim the current version when we fully re-synced
+        // (force); otherwise existing skills may still be stale, so keep the old stamp.
+        const present = skills.filter((name) => fs_1.default.existsSync(path_1.default.join(plan.destRoot, name)));
+        if (present.length > 0) {
+            const stampVersion = !prev || plan.force ? version : prev.version;
+            writeManifest(plan.destRoot, { version: stampVersion, skills: present });
+        }
+        const stale = !plan.force && prev !== null && prev.version !== version && skipped.length > 0;
+        if (opts.json) {
+            (0, output_js_1.printData)({ status: 'ok', dir: plan.destRoot, version, installed, skipped, pruned, stale }, opts);
+            return 0;
+        }
+        // argent-style messaging.
+        if (installed.length > 0) {
+            console.log(`\nInstalling skills…`);
+            for (const name of installed)
+                console.log(`  + ${name}`);
+            console.log(`Skills installed → ${plan.destRoot}`);
+        }
+        if (pruned.length > 0) {
+            console.log(`Pruned skills no longer shipped: ${pruned.join(', ')}`);
+        }
+        if (skipped.length > 0) {
+            console.log(`Already installed (skipped): ${skipped.join(', ')}. Re-run with --force to re-sync.`);
+        }
+        if (stale) {
+            console.log(`Note: skipped skills are from conductor v${prev?.version} (this is v${version}). Re-run \`conductor init --force\` to update them.`);
+        }
+        if (installed.length === 0 && pruned.length === 0 && skipped.length > 0) {
+            console.log('Nothing to do — all selected skills already installed.');
+        }
+        else {
+            console.log('Conductor is ready. Restart your agent / Claude Code session to pick up the skills.');
+        }
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        (0, output_js_1.printError)(`init failed: ${message}`, opts);
+        // Manual fallback, in the spirit of argent's "install manually" note.
+        if (!opts.json) {
+            console.error('To install manually, copy the bundled skills into your skills directory:');
+            console.error(`  cp -r "${bundledSkillsRoot()}"/* ./.claude/skills/`);
+        }
+        return 1;
+    }
+}

package/dist/commands/logs.js

@@ -42,6 +42,21 @@ function formatEntry(entry, opts) {
     }
     return line;
 }
+/**
+ * Ensure both the device driver and its daemon are up before reading logs.
+ *
+ * getDriver() starts the daemon when the driver *port* is closed, but skips it
+ * when the port is already open — which happens after the daemon idle-times-out
+ * while leaving the driver alive (e.g. tvOS deliberately keeps its runner up
+ * across daemon restarts). The log collector lives inside the daemon, so a live
+ * driver port is not enough: we must guarantee the daemon socket itself is up,
+ * otherwise the log source connects to a dead socket. startDaemon() is
+ * idempotent — it returns immediately when the daemon already answers /status.
+ */
+async function ensureLogDaemon(sessionName) {
+    await (0, runner_js_1.getDriver)(sessionName);
+    await (0, client_js_1.startDaemon)(sessionName);
+}
 async function resolvePlatformAndDevice(sessionName) {
     try {
         const driver = await (0, runner_js_1.getDriver)(sessionName);
@@ -130,7 +145,7 @@ async function logs(opts = {}, sessionName = 'default', { source, level, list, r
     try {
         // ── Snapshot mode (--recent N) ──────────────────────────────────────────
         if (recent !== undefined) {
-            await (0, runner_js_1.getDriver)(sessionName);
+            await ensureLogDaemon(sessionName);
             const minSeverity = level ? (types_js_1.LEVEL_SEVERITY[level] ?? 0) : 0;
             const entries = await (0, client_js_1.fetchDaemonLogs)(sessionName, { limit: recent, level });
             for (const entry of entries) {
@@ -145,7 +160,7 @@ async function logs(opts = {}, sessionName = 'default', { source, level, list, r
         }
         // ── Streaming modes ─────────────────────────────────────────────────────
         // Ensure daemon is running; its log collector auto-discovers Metro.
-        await (0, runner_js_1.getDriver)(sessionName);
+        await ensureLogDaemon(sessionName);
         const minSeverity = level ? (types_js_1.LEVEL_SEVERITY[level] ?? 0) : 0;
         const logSource = new daemon_js_1.DaemonLogSource(sessionName);
         await logSource.connect();

package/dist/commands/network.js

@@ -3,12 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.networkLogs = networkLogs;
 exports.networkRequest = networkRequest;
-exports.HELP = `  network logs [--port N] [--limit N]  Read recent HTTP traffic (installs a fetch/XHR shim once)
+exports.HELP = `  network logs [--port N] [--limit N]  Read recent HTTP traffic (RN: fetch/XHR shim; web: all traffic via Playwright)
   network request <url> [--method M] [--body STR] [--header K=V] [--port N]
                                        Issue an HTTP request from the app's context`;
 const output_js_1 = require("../output.js");
 const metro_cdp_js_1 = require("../drivers/metro-cdp.js");
 const bootstrap_js_1 = require("../drivers/bootstrap.js");
+const runner_js_1 = require("../runner.js");
+const web_js_1 = require("../drivers/web.js");
+/** Resolve the web driver when this session targets a web device, else null (→ Metro path). */
+async function webDriverFor(sessionName) {
+    if (!sessionName || sessionName === 'default')
+        return null;
+    const platform = await (0, bootstrap_js_1.detectPlatform)(sessionName).catch(() => undefined);
+    if (platform !== 'web')
+        return null;
+    const driver = await (0, runner_js_1.getDriver)(sessionName);
+    return driver instanceof web_js_1.WebDriver ? driver : null;
+}
+function formatNetEntry(e) {
+    const ts = e.timestamp.slice(11, 23);
+    const status = e.error ? `ERR ${e.error}` : e.status !== null ? String(e.status) : '...';
+    const dur = e.durationMs !== null ? `${e.durationMs}ms` : '-';
+    return `${ts}  ${status.padEnd(6)} ${e.method.padEnd(6)} ${e.url} (${dur}, ${e.resourceType ?? e.kind ?? ''})`;
+}
 const INSTALL_SHIM_SCRIPT = `
 (() => {
   if (globalThis.__CONDUCTOR_NET__ && globalThis.__CONDUCTOR_NET__.installed) {
@@ -99,8 +117,30 @@ function resolveSession(sessionName) {
     };
 }
 async function networkLogs(opts, sessionName, netOpts) {
-    const port = netOpts.port ?? 8081;
     const limit = netOpts.limit ?? 50;
+    // Web: Playwright captures all traffic natively — no Metro, no injected shim.
+    const web = await webDriverFor(sessionName);
+    if (web) {
+        try {
+            const { entries } = await web.networkLogs({ limit });
+            if (opts.json) {
+                (0, output_js_1.printData)({ installed: true, count: entries.length, entries }, opts);
+            }
+            else if (entries.length === 0) {
+                console.log('No network entries captured yet. Reload the app and try again.');
+            }
+            else {
+                for (const e of entries)
+                    console.log(formatNetEntry(e));
+            }
+            return 0;
+        }
+        catch (err) {
+            (0, output_js_1.printError)(`network logs — ${err instanceof Error ? err.message : String(err)}`, opts);
+            return 1;
+        }
+    }
+    const port = netOpts.port ?? 8081;
     const { deviceId, platformPromise } = resolveSession(sessionName);
     try {
         const platform = await platformPromise;
@@ -144,6 +184,31 @@ async function networkRequest(url, opts, sessionName, reqOpts) {
             headers[h.slice(0, idx)] = h.slice(idx + 1);
     }
     const body = reqOpts.body;
+    // Web: issue via the browser context (shares the page's cookies/session).
+    const web = await webDriverFor(sessionName);
+    if (web) {
+        try {
+            const result = await web.networkRequest(url, { method, headers, body });
+            if (opts.json)
+                (0, output_js_1.printData)(result, opts);
+            else {
+                if (result.error)
+                    console.error(`error: ${result.error}`);
+                console.log(`status: ${result.status ?? 'n/a'}`);
+                for (const [k, v] of Object.entries(result.headers ?? {}))
+                    console.log(`${k}: ${v}`);
+                if (result.body !== undefined) {
+                    console.log('');
+                    console.log(result.body);
+                }
+            }
+            return result.ok ? 0 : 1;
+        }
+        catch (err) {
+            (0, output_js_1.printError)(`network request — ${err instanceof Error ? err.message : String(err)}`, opts);
+            return 1;
+        }
+    }
     const init = JSON.stringify({
         method,
         headers,

package/dist/commands/options.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.listOptions = listOptions;
+exports.HELP = `  list-options [command|param]         List valid values for enumerated parameters
+    (e.g. \`list-options press-key\`, \`list-options direction\`, or no arg for all)`;
+const output_js_1 = require("../output.js");
+const enum_options_js_1 = require("../enum-options.js");
+function renderParam(p) {
+    const lines = [];
+    lines.push(`${p.command} ${p.param}`);
+    lines.push(`  ${p.description}`);
+    for (const v of p.values) {
+        lines.push(v.description ? `    ${v.value}  —  ${v.description}` : `    ${v.value}`);
+    }
+    if (p.note)
+        lines.push(`  note: ${p.note}`);
+    return lines.join('\n');
+}
+/**
+ * List valid values for enumerated parameters. With no query, lists every
+ * enumerated parameter. With a query, filters by command name, parameter name,
+ * or value.
+ */
+function listOptions(query, opts = {}) {
+    const matches = (0, enum_options_js_1.findEnumParams)(query);
+    if (matches.length === 0) {
+        const available = (0, enum_options_js_1.commandsWithEnums)().join(', ');
+        (0, output_js_1.printError)(`No enumerated parameters match "${query}". Commands with options: ${available}`, opts);
+        return 1;
+    }
+    if (opts.json) {
+        (0, output_js_1.printData)(matches.map((p) => ({
+            command: p.command,
+            param: p.param,
+            description: p.description,
+            values: p.values.map((v) => v.value),
+            note: p.note ?? null,
+        })), opts);
+        return 0;
+    }
+    console.log(matches.map(renderParam).join('\n\n'));
+    return 0;
+}

package/dist/commands/press-key.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HELP = void 0;
+exports.VALID_KEYS = exports.HELP = void 0;
 exports.pressKey = pressKey;
 exports.HELP = `  press-key <key>                     Press a key (Enter, Backspace, Home, ...)`;
 const runner_js_1 = require("../runner.js");
@@ -8,7 +8,7 @@ const output_js_1 = require("../output.js");
 const ios_js_1 = require("../drivers/ios.js");
 const android_js_1 = require("../drivers/android.js");
 const web_js_1 = require("../drivers/web.js");
-const VALID_KEYS = [
+exports.VALID_KEYS = [
     'Enter',
     'Backspace',
     'Home',
@@ -107,12 +107,12 @@ const ANDROID_KEYCODE = {
 };
 async function pressKey(key, opts = {}, sessionName = 'default') {
     if (!key) {
-        (0, output_js_1.printError)(`press-key requires <key>. Valid keys: ${VALID_KEYS.join(', ')}`, opts);
+        (0, output_js_1.printError)(`press-key requires <key>. Valid keys: ${exports.VALID_KEYS.join(', ')}`, opts);
         return 1;
     }
-    const matched = VALID_KEYS.find((k) => k.toLowerCase() === key.toLowerCase());
+    const matched = exports.VALID_KEYS.find((k) => k.toLowerCase() === key.toLowerCase());
     if (!matched) {
-        (0, output_js_1.printError)(`Unknown key "${key}". Valid keys: ${VALID_KEYS.join(', ')}`, opts);
+        (0, output_js_1.printError)(`Unknown key "${key}". Valid keys: ${exports.VALID_KEYS.join(', ')}`, opts);
         return 1;
     }
     const result = await (0, runner_js_1.runDirect)(async (driver) => {
@@ -149,6 +149,13 @@ async function pressKey(key, opts = {}, sessionName = 'default') {
                 Escape: 'Escape',
                 Home: 'Home',
                 End: 'End',
+                // Canvas webtv apps (Lightning/WPE) navigate focus via the D-pad, which they listen
+                // for as arrow keys (and Enter for select). Maps the TV remote onto web keyboard.
+                'Remote Dpad Up': 'ArrowUp',
+                'Remote Dpad Down': 'ArrowDown',
+                'Remote Dpad Left': 'ArrowLeft',
+                'Remote Dpad Right': 'ArrowRight',
+                'Remote Dpad Center': 'Enter',
             };
             const webKey = WEB_KEY_MAP[matched];
             if (webKey) {

package/dist/commands/set-viewport.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HELP = void 0;
+exports.PRESETS = exports.HELP = void 0;
 exports.setViewport = setViewport;
 exports.HELP = `  set-viewport [<width> <height>]      Resize the web browser viewport (web only)
     --preset <mobile|tablet|desktop>  Use a device preset instead of explicit width/height
@@ -12,7 +12,7 @@ exports.HELP = `  set-viewport [<width> <height>]      Resize the web browser vi
 const runner_js_1 = require("../runner.js");
 const web_js_1 = require("../drivers/web.js");
 const output_js_1 = require("../output.js");
-const PRESETS = {
+exports.PRESETS = {
     mobile: { width: 390, height: 844, deviceScaleFactor: 3, isMobile: true },
     tablet: { width: 820, height: 1180, deviceScaleFactor: 2, isMobile: true },
     desktop: { width: 1280, height: 800, deviceScaleFactor: 1, isMobile: false },
@@ -23,9 +23,9 @@ async function setViewport(flags, opts = {}, sessionName = 'default') {
     let isMobile = flags.mobile;
     let scale = flags.scale;
     if (flags.preset !== undefined) {
-        const preset = PRESETS[flags.preset.toLowerCase()];
+        const preset = exports.PRESETS[flags.preset.toLowerCase()];
         if (!preset) {
-            (0, output_js_1.printError)(`--preset must be one of: ${Object.keys(PRESETS).join(', ')}`, opts);
+            (0, output_js_1.printError)(`--preset must be one of: ${Object.keys(exports.PRESETS).join(', ')}`, opts);
             return 1;
         }
         width ?? (width = preset.width);