@houwert/conductor 0.20.0 → 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/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/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) => {

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

package/dist/enum-options.js

@@ -0,0 +1,130 @@
+"use strict";
+// Central registry of commands/parameters that only accept a fixed set of
+// enumerated values. The `list-options` command and the global `--options`
+// flag read from here so agents (and humans) can discover valid values without
+// trial-and-error.
+//
+// Where a value list already exists as the canonical source elsewhere, we
+// import it so this registry can never drift from what the command validates.
+// Small, stable 2–4 value lists are inlined with a pointer to their source.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENUM_PARAMS = void 0;
+exports.commandsWithEnums = commandsWithEnums;
+exports.findEnumParams = findEnumParams;
+const press_key_js_1 = require("./commands/press-key.js");
+const set_viewport_js_1 = require("./commands/set-viewport.js");
+const utils_js_1 = require("./utils.js");
+const types_js_1 = require("./drivers/log-sources/types.js");
+const DIRECTION_VALUES = utils_js_1.DIRECTIONS.map((d) => ({ value: d }));
+// `--level` accepts every key of LEVEL_SEVERITY (includes the `warn` alias).
+const LOG_LEVELS = Object.keys(types_js_1.LEVEL_SEVERITY).map((value) => ({ value }));
+exports.ENUM_PARAMS = [
+    {
+        command: 'press-key',
+        param: '<key>',
+        description: 'Key, hardware button, or remote button to press',
+        values: press_key_js_1.VALID_KEYS.map((value) => ({ value })),
+        note: 'Matched case-insensitively. Availability varies by platform: "Remote …" / "TV …" keys target tvOS and Android TV; hardware buttons (Home, Lock, Power, Volume…) target iOS/Android.',
+    },
+    {
+        command: 'scroll',
+        param: '--direction',
+        description: 'Scroll direction (default: down)',
+        values: DIRECTION_VALUES,
+    },
+    {
+        command: 'swipe',
+        param: '--direction',
+        description: 'Swipe direction (required unless --start/--end are given)',
+        values: DIRECTION_VALUES,
+    },
+    {
+        command: 'scroll-until-visible',
+        param: '--direction',
+        description: 'Scroll direction while searching (default: down)',
+        values: DIRECTION_VALUES,
+    },
+    {
+        command: 'set-orientation',
+        param: '<orientation>',
+        description: 'Device orientation',
+        // Source: VALID in commands/set-orientation.ts
+        values: [{ value: 'portrait' }, { value: 'landscape' }],
+    },
+    {
+        command: 'start-device',
+        param: '--platform',
+        description: 'Platform of the device to start',
+        // Source: switch in commands/start-device.ts
+        values: [{ value: 'ios' }, { value: 'android' }, { value: 'tvos' }, { value: 'web' }],
+    },
+    {
+        command: 'install-web',
+        param: '[browser]',
+        description: 'Playwright browser to install (default: chromium)',
+        // Source: validBrowsers in commands/install.ts
+        values: [{ value: 'chromium' }, { value: 'firefox' }, { value: 'webkit' }],
+    },
+    {
+        command: 'set-viewport',
+        param: '--preset',
+        description: 'Device size preset instead of explicit width/height (web only)',
+        values: Object.entries(set_viewport_js_1.PRESETS).map(([value, p]) => ({
+            value,
+            description: `${p.width}x${p.height} @${p.deviceScaleFactor}x${p.isMobile ? ', mobile' : ''}`,
+        })),
+    },
+    {
+        command: 'set-viewport',
+        param: '--color-scheme',
+        description: 'Emulate prefers-color-scheme (web only)',
+        values: [{ value: 'dark' }, { value: 'light' }],
+    },
+    {
+        command: 'logs',
+        param: '--source',
+        description: 'Filter logs by source (default: both)',
+        // Source: sourceFilter in commands/logs.ts
+        values: [{ value: 'metro' }, { value: 'device' }],
+    },
+    {
+        command: 'logs',
+        param: '--level',
+        description: 'Minimum log level to show',
+        values: LOG_LEVELS,
+        note: '"warn" is an alias for "warning".',
+    },
+    {
+        command: 'list-devices',
+        param: '--platform',
+        description: 'Filter listed devices by platform (also a global filter on most commands)',
+        values: [{ value: 'ios' }, { value: 'android' }, { value: 'tvos' }, { value: 'web' }],
+    },
+];
+/** All distinct command names that have at least one enumerated parameter. */
+function commandsWithEnums() {
+    return [...new Set(exports.ENUM_PARAMS.map((p) => p.command))];
+}
+/**
+ * Find enumerated parameters matching a query. Matches a command name (e.g.
+ * "press-key"), a bare parameter name (e.g. "direction", "--level"), or a
+ * value (e.g. "tvos"). Returns all params when query is empty.
+ */
+function findEnumParams(query) {
+    if (!query)
+        return exports.ENUM_PARAMS;
+    const norm = (s) => s
+        .toLowerCase()
+        .replace(/^-+/, '')
+        .replace(/[<>[\]]/g, '');
+    const q = norm(query);
+    // Exact matches (command, param, or value) take precedence so that an exact
+    // command name like "scroll" doesn't also drag in "scroll-until-visible".
+    const exact = exports.ENUM_PARAMS.filter((p) => p.command.toLowerCase() === q ||
+        norm(p.param) === q ||
+        p.values.some((v) => v.value.toLowerCase() === q));
+    if (exact.length > 0)
+        return exact;
+    // Otherwise fall back to substring matching to forgive partial queries.
+    return exports.ENUM_PARAMS.filter((p) => p.command.toLowerCase().includes(q) || norm(p.param).includes(q));
+}

package/dist/index.js

@@ -28,6 +28,7 @@ const press_key_js_1 = require("./commands/press-key.js");
 const session_js_1 = require("./commands/session.js");
 const daemon_js_1 = require("./commands/daemon.js");
 const install_js_1 = require("./commands/install.js");
+const init_js_1 = require("./commands/init.js");
 const device_pool_js_1 = require("./commands/device-pool.js");
 const run_parallel_js_1 = require("./commands/run-parallel.js");
 const run_sequence_js_1 = require("./commands/run-sequence.js");
@@ -59,6 +60,7 @@ const logs_js_1 = require("./commands/logs.js");
 const memory_js_1 = require("./commands/memory.js");
 const metro_js_1 = require("./commands/metro.js");
 const clipboard_js_1 = require("./commands/clipboard.js");
+const options_js_1 = require("./commands/options.js");
 const device_picker_js_1 = require("./device-picker.js");
 const update_check_js_1 = require("./update-check.js");
 const pkg_root_js_1 = require("./pkg-root.js");
@@ -101,6 +103,7 @@ const COMMAND_HELP = {
     'run-flow-inline': run_flow_inline_js_1.HELP,
     session: session_js_1.HELP,
     'install-web': install_js_1.HELP_INSTALL_WEB,
+    init: init_js_1.HELP,
     'daemon-start': daemon_js_1.HELP_DAEMON_START,
     'daemon-stop': daemon_js_1.HELP_DAEMON_STOP,
     'daemon-status': daemon_js_1.HELP_DAEMON_STATUS,
@@ -119,12 +122,14 @@ const COMMAND_HELP = {
     metro: metro_js_1.HELP,
     clipboard: clipboard_js_1.HELP,
     paste: '  paste                                Trigger OS-level paste (or type clipboard on iOS)',
+    'list-options': options_js_1.HELP,
 };
 const OPTIONS_HELP = `Options:
   --device <id>     Target device ID (also keys the session and daemon)
   --device-name <n> Target a booted device by name (resolved to ID from booted devices)
   --platform <p>    Filter to devices of this platform (ios, android, tvos, web)
   --json            Output as machine-readable JSON
+  --options         List valid values for a command's enumerated parameters and exit
   --verbose, -v     Log daemon calls, fallbacks, and raw output
   --version, -V     Print version number
   --help, -h        Show this help`;
@@ -141,6 +146,7 @@ async function main() {
         boolean: [
             'json',
             'help',
+            'options',
             'version',
             'clear',
             'list',
@@ -163,6 +169,9 @@ async function main() {
             'leaks',
             'snapshots',
             'growth-only',
+            'global',
+            'force',
+            'yes',
         ],
         string: [
             'device',
@@ -222,7 +231,7 @@ async function main() {
             'user-agent',
             'color-scheme',
         ],
-        alias: { h: 'help', v: 'verbose', V: 'version', o: 'output' },
+        alias: { h: 'help', v: 'verbose', V: 'version', o: 'output', y: 'yes' },
     });
     if (argv['verbose'])
         (0, verbose_js_1.setVerbose)(true);
@@ -234,6 +243,12 @@ async function main() {
         console.log(pkg.version);
         process.exit(0);
     }
+    // `<command> --options` lists the valid values for that command's enumerated
+    // parameters and exits — no device resolution needed. With no command it
+    // lists every enumerated parameter. `--help` still wins if both are passed.
+    if (argv['options'] && !argv['help'] && command !== 'list-options') {
+        process.exit((0, options_js_1.listOptions)(command, opts));
+    }
     // Handle help and unknown commands before device resolution —
     // no point prompting for a device if we're just printing help or erroring out.
     if (!command || argv['help']) {
@@ -252,11 +267,13 @@ async function main() {
         'stop-device',
         'delete-device',
         'install-web',
+        'init',
         'copy-app',
         'device-pool',
         'run-parallel',
         'metro',
         'workspace',
+        'list-options',
         // `logs --list` and `logs --source metro` only query Metro on localhost — no device needed
         // `logs` always needs a device session — Metro discovery is device-scoped.
         // `daemon-stop --all` stops every daemon — no device needed
@@ -418,6 +435,10 @@ async function main() {
             exitCode = await (0, press_key_js_1.pressKey)(key, opts, sessionName);
             break;
         }
+        case 'list-options': {
+            exitCode = (0, options_js_1.listOptions)(rest[0], opts);
+            break;
+        }
         case 'scroll': {
             const dir = (argv['direction'] || 'down').toLowerCase();
             exitCode = await (0, scroll_js_1.scroll)(dir, opts, sessionName);
@@ -610,6 +631,13 @@ async function main() {
         case 'session':
             exitCode = await (0, session_js_1.sessionCmd)(argv['clear'], argv['list'], opts, sessionName);
             break;
+        case 'init':
+            exitCode = await (0, init_js_1.init)(opts, rest[0], {
+                global: argv['global'],
+                force: argv['force'],
+                yes: argv['yes'],
+            });
+            break;
         case 'install-web':
             exitCode = await (0, install_js_1.installWebCli)(opts, argv['check'], rest[0]);
             break;

package/dist/utils.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTIONS = void 0;
 exports.sleep = sleep;
 exports.swipeCoords = swipeCoords;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+exports.DIRECTIONS = ['down', 'up', 'left', 'right'];
 function swipeCoords(dir) {
     switch (dir) {
         case 'down':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,8 @@
   "main": "./dist/index.js",
   "files": [
     "dist/",
-    "proto/"
+    "proto/",
+    "skills/"
   ],
   "scripts": {
     "build": "tsc",

package/skills/conductor-create-flow/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: conductor-create-flow
+description: Author and run Maestro-compatible YAML flows and command sequences with the conductor CLI, including recording flows from live interactions and sharding them across devices. Use when scripting a repeatable multi-step app journey, running an existing Maestro flow, recording a flow by interacting with the app, or running flows in parallel across booted devices.
+---
+
+# Conductor — flows
+
+A **flow** is a YAML file describing a sequence of conductor commands.
+Conductor's format is a subset of [Maestro](https://maestro.mobile.dev)'s — most
+existing Maestro flows run unchanged. Use flows for repeatable journeys; use
+`conductor-device-interact` for one-off ad-hoc steps.
+
+## Run flows
+
+| Command | Purpose |
+|---|---|
+| `conductor run-flow <file> [--env K=V] [--benchmark]` | Run a Maestro YAML flow file |
+| `conductor run-flow-inline '<yaml>' [--benchmark]` | Run inline YAML from the command line |
+| `conductor run-sequence [--file path.json]` | Run a JSON sequence of conductor commands serially; reads stdin if no `--file` |
+| `conductor run-parallel --flows-dir <path>` | Shard a directory of flows across all booted devices |
+
+`--benchmark` prints elapsed time per command and total flow time.
+
+## Flow YAML
+
+```yaml
+appId: com.example.myapp
+---
+- launchApp
+- tapOn: "Sign In"
+- inputText: "user@example.com"
+- assertVisible: "Dashboard"
+```
+
+`run-sequence` JSON shape (stops on first non-zero exit):
+
+```json
+{ "steps": [ { "cmd": "tap-on", "args": ["Login"] }, { "cmd": "input-text", "args": ["user@example.com"] } ] }
+```
+
+## Record a flow from your interactions
+
+| Command | Purpose |
+|---|---|
+| `conductor flow record start [--out path]` | Start recording this session's interactions to a YAML file |
+| `conductor flow record echo <text>` | Insert a `console.log` step |
+| `conductor flow record status` | Show the active recording path |
+| `conductor flow record finish` | Close the recording, print the file path |
+
+Record, then interact via `conductor-device-interact`; each action is appended
+to the flow. `finish` gives you a runnable `.yaml`.
+
+## Tips
+
+- Add `--json` for machine-readable output; a failed step exits non-zero.
+- `conductor run-flow --help` (and friends) for exact flags.

package/skills/conductor-device-interact/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: conductor-device-interact
+description: Drive a running iOS simulator, Android emulator, tvOS simulator, or Playwright web app with the conductor CLI. Use when launching apps, tapping UI elements, typing text, scrolling/swiping, performing gestures, pressing hardware/keyboard keys, opening URLs or deep links, navigating back, or verifying an app change in the real running app.
+---
+
+# Conductor — device interaction
+
+`conductor` drives a real running app the way a user would: launch it, tap,
+type, scroll, and assert. It bundles its own native drivers — no second CLI to
+install. Use it to verify a change in the actual app, not just in tests.
+
+To **observe** the screen (inspect the hierarchy, screenshot, read element
+state), use the `conductor-inspect` skill — it pairs with this one.
+
+## The core loop: act → observe → act
+
+Never tap blind, never assume the result. After every action, observe before
+the next one.
+
+1. **Observe** with `conductor capture-ui` (see `conductor-inspect`) to see the
+   screen and get short element refs (`@e1`, `@e2`, …).
+2. **Act** — `tap-on`, `input-text`, `scroll`, etc.
+3. **Confirm** with `assert-visible` / another `capture-ui`.
+
+```bash
+conductor launch-app com.example.myapp
+conductor capture-ui            # observe; get @eN refs
+conductor tap-on "Sign In"      # or: conductor tap-on @e3
+conductor input-text "user@example.com"
+conductor assert-visible "Dashboard"
+```
+
+## Interaction commands
+
+| Command | Purpose |
+|---|---|
+| `conductor launch-app <appId>` | Launch app (saved to session). `--no-stop-app` resumes; `--argument key=value` passes launch args |
+| `conductor stop-app [<appId>]` | Stop the app |
+| `conductor tap-on <element>` | Tap by text, id, or `@eN`. `--long-press`, `--double-tap`, `--optional`, `--index <n>` |
+| `conductor input-text <text>` | Type into the focused field |
+| `conductor erase-text [n]` | Erase n characters (default 50) |
+| `conductor press-key <key>` | Press a key (Enter, Backspace, Home, …) |
+| `conductor hide-keyboard` | Dismiss the on-screen keyboard |
+| `conductor back` | Press back |
+| `conductor scroll [--direction down\|up\|left\|right]` | Scroll |
+| `conductor scroll-until-visible <element> [--direction] [--timeout ms]` | Scroll until element appears |
+| `conductor swipe --direction <dir>` / `--start <x,y> --end <x,y> [--duration ms]` | Swipe |
+| `conductor open-link <url>` | Open a URL / deep link |
+| `conductor pinch [--scale N] [--center x,y]` | Two-finger pinch (scale<1 out, >1 in) |
+| `conductor rotate-gesture [--degrees N] [--center x,y]` | Two-finger rotate |
+| `conductor gesture <json\|--file path>` | Play a multi-touch path |
+| `conductor clipboard read` / `clipboard write <text>` / `paste` | Clipboard (iOS) |
+| `conductor list-options [command]` | List valid values for enumerated params |
+
+## Discovering valid values
+
+Several commands only accept a fixed set of values (`press-key <key>`,
+`--direction`, `set-orientation`, `set-viewport --preset`/`--color-scheme`,
+`logs --level`/`--source`, `--platform`). Don't guess — list them:
+
+- `conductor <command> --options` — valid values for that command, e.g.
+  `conductor press-key --options`, `conductor swipe --options`.
+- `conductor list-options [command|param]` — same data; with no argument it
+  lists every enumerated parameter, or filter by name (`list-options direction`).
+- Add `--json` for machine-readable output.
+
+## Selecting elements
+
+Positional `<element>` matches **accessibility id first, then visible text**.
+Disambiguate when multiple match:
+
+- `--id <id>` / `--text <text>` — id-only / text-only matching
+- `--index <n>` — nth match (0-based)
+- `--below` / `--above` / `--left-of` / `--right-of <text>` — relative position
+- `--focused`, `--enabled`, `--checked`, `--selected` — state filters
+- `--timeout <ms>` — wait for the element to appear
+- `--optional` — missing element is a no-op, not an error
+- `@eN` — exact element from the **last `capture-ui`** (cached coords, ephemeral
+  ~60s; re-capture after navigating)
+
+If you can't find an element, run `conductor inspect` or `capture-ui` to see the
+real ids and texts rather than guessing.
+
+## ⚠️ Don't reset state to "fix" navigation
+
+Never use `launch-app --clear-state`, `clear-state`, or `--clear-keychain` to
+clear focus or navigation — they **wipe user data and sign the user out**, and
+can't be undone without their credentials. Navigate out with `back` / Menu, or
+relaunch without the flag. (See `conductor-device-setup`.)
+
+## Tips
+
+- `--device <id>` / `--device-name <name>` targets a device; `--platform <ios|android|tvos|web>` scopes by platform.
+- Add `--json` for machine-readable output; failed assertions exit non-zero.
+- Run a per-session daemon for many commands (see `conductor-device-setup`).
+- `conductor <command> --help` for exact flags.

package/skills/conductor-device-setup/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: conductor-device-setup
+description: Boot, list, and manage devices and app installs for the conductor CLI — iOS simulators, Android emulators, tvOS simulators, and Playwright web browsers — plus sessions, the warm-driver daemon, and the parallel device pool. Use when starting or stopping a simulator/emulator/browser, installing or launching an app, setting up the web driver, keeping the driver warm, or coordinating multiple devices for parallel agents.
+---
+
+# Conductor — device & app setup
+
+Get a device running and an app installed before you drive it. Start here when
+nothing is booted yet.
+
+## Orient first
+
+```bash
+conductor workspace info     # detected project type, bundle IDs, devices, Metro port — best first call
+conductor list-devices       # booted + available devices
+conductor foreground-app     # bundle id of the app currently in front
+conductor list-apps          # installed app ids / package names
+```
+
+## Devices
+
+| Command | Purpose |
+|---|---|
+| `conductor start-device --platform <ios\|android\|tvos\|web>` | Boot a simulator/emulator or start the web driver |
+| `conductor start-device --os-version <n> --device-type <name>` | Pick OS version + device type (creates if needed) |
+| `conductor stop-device [<name-or-id>] [--all]` | Shut down device(s) |
+| `conductor delete-device <name-or-id> [--all]` | Delete simulator(s)/AVD(s)/web session(s) |
+| `conductor set-location --lat <n> --lng <n>` | Set GPS coordinates |
+| `conductor set-orientation <portrait\|landscape>` | Set orientation |
+| `conductor set-viewport [<w> <h>] [--preset mobile\|tablet\|desktop]` | Resize web viewport (web only) |
+| `conductor install-web [--check] [browser]` | Install a Playwright browser (chromium/firefox/webkit); `--check` = status |
+
+## App lifecycle
+
+| Command | Purpose |
+|---|---|
+| `conductor install-app <path>` | Install .app / .ipa / .apk |
+| `conductor launch-app <appId>` | Launch app (saved to session); `--no-stop-app`, `--argument key=value` |
+| `conductor stop-app [<appId>]` | Stop app |
+| `conductor uninstall-app <appId>` | Uninstall app |
+| `conductor copy-app <bundleId> --from <id> --to <id>` | Copy an installed app between iOS simulators |
+| `conductor download-app <appId> --output <path>` | Download installed app binary |
+
+### ⚠️ Destructive flags — ask the user first
+
+`conductor clear-state [<appId>]`, `launch-app --clear-state`, and
+`launch-app --clear-keychain` **wipe app data and sign the user out**, and can't
+be undone without their credentials. Never use them to "reset focus" or clear
+navigation — relaunch without the flag, or navigate out with `back` / Menu. If
+you genuinely need one, ask the human first.
+
+## Sessions, daemon & device pool
+
+A **session** remembers the last device + app so you don't re-specify them.
+Parallel agents each get their own `--session <name>` so they don't collide.
+
+| Command | Purpose |
+|---|---|
+| `conductor session [--clear] [--list]` | Show, clear, or list sessions |
+| `conductor daemon-start` | Start the per-session background daemon (keeps the driver warm — do this for any multi-step session) |
+| `conductor daemon-status` | Show daemon status |
+| `conductor daemon-stop [--all]` | Stop this session's daemon (`--all` = every session) |
+| `conductor device-pool --list` | List devices + pool status |
+| `conductor device-pool --acquire` | Claim a free device (prints id) |
+| `conductor device-pool --release <id>` | Release a device back to the pool |
+
+Don't leave a daemon running when you're done — `daemon-stop` it.
+
+## Tips
+
+- `--device <id>` / `--device-name <name>` targets a device; `--platform` scopes by platform.
+- Add `--json` for machine-readable output.
+- `conductor <command> --help` for exact flags.

package/skills/conductor-inspect/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: conductor-inspect
+description: Read the live UI state of a running app with the conductor CLI — view hierarchy, accessibility snapshot, screenshots, focused element, and element refs. Use when you need to see what's on screen, find an element's id/text/coordinates, take a screenshot, check focus, or assert that something is (or isn't) visible before or after acting.
+---
+
+# Conductor — inspection & assertions
+
+These commands let you **observe** a running app's screen so you know what to do
+next. Pair them with `conductor-device-interact`, which acts on what you find
+here. Always observe before you act, and confirm after.
+
+## Observe the screen
+
+| Command | Purpose |
+|---|---|
+| `conductor capture-ui [--output <path.json>]` | Screenshot + hierarchy + a11y snapshot in one JSON bundle; assigns short `@eN` refs. **Preferred way to observe.** |
+| `conductor inspect [--dump]` | Print the UI hierarchy (`--dump` = raw driver output) |
+| `conductor inspect --at <x,y> [--tappable]` | Topmost view at a screen point |
+| `conductor focused [--poll [ms]]` | Metadata of the focused element. `--poll` watches changes — only with a bounded use, then stop it |
+| `conductor take-screenshot [<element>] [--output <path>] [--full-page]` | Screenshot; crop to a matched element; `--full-page` (web) |
+
+`capture-ui` is the workhorse: it returns the screen as structured data **and**
+gives each element a ref like `@e3` that `conductor tap-on @e3` taps by cached
+coordinates. Refs are ephemeral (~60s) — re-capture after navigating or waiting.
+
+```bash
+conductor capture-ui --output /tmp/screen.json
+# read it: element texts, ids, frames, and @eN refs
+conductor tap-on @e5
+```
+
+## Assertions
+
+| Command | Purpose |
+|---|---|
+| `conductor assert-visible <element> [--timeout ms]` | Assert element is visible (non-zero exit on failure) |
+| `conductor assert-not-visible <element> [--timeout ms]` | Assert element is absent |
+
+Both take the same selectors as `tap-on`: `--id`, `--text`, `--index`,
+`--below` / `--above` / `--left-of` / `--right-of`, `--focused`, `--enabled`,
+`--checked`, `--selected`, `--optional`.
+
+## Tips
+
+- Add `--json` to parse output programmatically (pipe through `jq`).
+- When an interaction can't find an element, `inspect` / `capture-ui` shows the
+  real ids and texts on screen — don't guess selectors.
+- `conductor <command> --help` for exact flags.

package/skills/conductor-metro-debugger/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: conductor-metro-debugger
+description: Inspect a running app's JS runtime, logs, and network with the conductor CLI — evaluate JS in React Native (Hermes) or the web page, dump the React component tree, read console/Metro/device logs, and inspect or issue HTTP requests. Use when debugging app behavior, reading logs, evaluating expressions in the live runtime, inspecting React components, or examining network traffic.
+---
+
+# Conductor — runtime debugging, logs & network
+
+Inspect what a running app is doing under the UI — its JS runtime, console
+output, and HTTP traffic. Works against React Native (Hermes/Fusebox) and
+Playwright web.
+
+## Runtime (React Native / web)
+
+| Command | Purpose |
+|---|---|
+| `conductor debug status [--port N]` | RN debugger connection info |
+| `conductor debug evaluate <expr> [--port N]` | Run JS in the app runtime (Hermes or web page) |
+| `conductor debug component-tree [--port N]` | On-screen React component tree |
+| `conductor debug inspect-element <x,y>` | React component at a screen point |
+| `conductor debug log-registry [--source metro]` | Summarize recent Metro/Hermes console logs |
+
+## Logs
+
+| Command | Purpose |
+|---|---|
+| `conductor logs --recent <n>` | Last N buffered log lines — **agent-friendly, exits immediately** |
+| `conductor logs [--source metro\|device] [--level …] [--json] [--duration s]` | Stream logs (bound it with `--duration`) |
+| `conductor logs --list` | List Metro debugger targets for this device |
+
+Prefer `logs --recent N` over a bare `logs` stream — don't leave a stream
+running indefinitely.
+
+## Network
+
+| Command | Purpose |
+|---|---|
+| `conductor network logs [--limit N]` | Recent HTTP traffic (RN fetch/XHR shim; web via Playwright) |
+| `conductor network request <url> [--method M] [--body STR] [--header K=V]` | Issue an HTTP request from the app's context |
+
+## Metro bundler
+
+| Command | Purpose |
+|---|---|
+| `conductor metro reload [--port N] [--target N]` | Reload the JS bundle without restarting native |
+| `conductor metro stop [--port N]` | Stop the Metro bundler on a port (default 8081) |
+
+## Tips
+
+- `--port N` targets a specific Metro/debugger port when auto-detection isn't enough.
+- Add `--json` for machine-readable output.
+- For crashes and performance, see `conductor-profiler`.

package/skills/conductor-profiler/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: conductor-profiler
+description: Profile a running app's CPU, memory, and React render performance with the conductor CLI, and read crash reports. Use when investigating slowness, jank, memory growth or leaks, excessive React re-renders, or when an app has crashed and you need the crash report.
+---
+
+# Conductor — profiling & crashes
+
+Measure a running app's performance and inspect crashes.
+
+## Profiling
+
+| Command | Purpose |
+|---|---|
+| `conductor profile cpu --duration <s> [--out <path>]` | Record a CPU trace (iOS: xctrace, Android: simpleperf) |
+| `conductor profile memory --track <s> [--interval ms] [<appId>]` | Sample memory for N seconds, report deltas |
+| `conductor profile react start` / `profile react stop [--top N]` | Install a React commit-profiler hook, then summarize captured commits |
+
+## Memory
+
+| Command | Purpose |
+|---|---|
+| `conductor memory [<appId>]` | Device + app memory usage |
+| `conductor memory --objects` | Include per-class object counts (iOS heap; slower) |
+| `conductor memory --leaks` | Run leak detection (iOS only; slow, can pause the app) |
+| `conductor memory --save <name>` / `--diff <name>` / `--diff <name> --vs <other>` | Snapshot and diff memory reports |
+| `conductor memory --filter <regex>` / `--growth-only` / `--top <n>` | Narrow object/class tables (great for leak-hunting) |
+
+Typical leak hunt: `memory --save before`, exercise the screen, then
+`memory --diff before --growth-only`.
+
+## Crashes
+
+| Command | Purpose |
+|---|---|
+| `conductor crashes list [--app <bundleId>] [--since <duration>]` | List recent crash reports (iOS host + Android logcat) |
+| `conductor crashes show <id>` | Print a specific crash report |
+| `conductor crashes tail` | Stream new crash reports as they appear |
+
+## Tips
+
+- Add `--json` to parse reports programmatically.
+- These commands can be slow or pause the app — scope them with `--duration` / `--track` and avoid leaving `crashes tail` running.