@houwert/conductor 0.27.0 → 0.27.2

package/dist/drivers/flow-runner.js

@@ -7,11 +7,13 @@ exports.parseFlowFile = parseFlowFile;
 exports.parseFlowString = parseFlowString;
 exports.executeFlow = executeFlow;
 exports.resolvePoint = resolvePoint;
+exports.resolvePath = resolvePath;
 /**
  * Native Conductor YAML flow parser and executor.
  * Parses flow YAML files and executes commands directly using IOSDriver / AndroidDriver.
  */
 const promises_1 = __importDefault(require("fs/promises"));
+const node_fs_1 = require("node:fs");
 const path_1 = __importDefault(require("path"));
 const node_vm_1 = __importDefault(require("node:vm"));
 const js_yaml_1 = __importDefault(require("js-yaml"));
@@ -1368,8 +1370,72 @@ async function executeCommandBody(key, val, driver, opts) {
     }
 }
 // ── Utilities ─────────────────────────────────────────────────────────────────
+// Resolve a `file:` reference from within a flow. A path starting with `@` is an
+// alias of the form `@name/rest`, where `name` maps to a directory declared under
+// `paths:` in the nearest `config.yaml`. Everything else keeps the historical
+// behavior: resolved relative to the flow file's directory (`cwd`).
+// Mirrors the plexinc/maestro FlowPathResolver.
 function resolvePath(filePath, cwd) {
-    return path_1.default.isAbsolute(filePath) ? filePath : path_1.default.join(cwd ?? process.cwd(), filePath);
+    const base = cwd ?? process.cwd();
+    if (filePath.startsWith('@'))
+        return resolvePathAlias(filePath, base);
+    return path_1.default.isAbsolute(filePath) ? filePath : path_1.default.join(base, filePath);
+}
+const CONFIG_FILE_NAMES = ['config.yaml', 'config.yml'];
+// Cache discovered config → paths map for the process lifetime (flows are short-lived).
+const configPathsCache = new Map();
+function resolvePathAlias(requestedPath, startDir) {
+    const body = requestedPath.slice(1);
+    const separator = body.indexOf('/');
+    const alias = separator >= 0 ? body.slice(0, separator) : body;
+    const remainder = separator >= 0 ? body.slice(separator + 1) : '';
+    const configPath = findWorkspaceConfig(startDir);
+    if (!configPath) {
+        throw new Error(`Path alias '@${alias}' used but no config.yaml was found in any parent directory. ` +
+            'Declare aliases under `paths:` in a workspace config.yaml.');
+    }
+    const paths = readWorkspacePaths(configPath);
+    const target = paths[alias];
+    if (target === undefined) {
+        const known = Object.keys(paths).sort();
+        throw new Error(`Unknown path alias '@${alias}' referenced in a flow. ` +
+            `Known aliases in ${configPath}: [${known.join(', ')}]`);
+    }
+    const configDir = path_1.default.dirname(path_1.default.resolve(configPath));
+    const targetDir = path_1.default.normalize(path_1.default.resolve(configDir, target));
+    if (!(0, node_fs_1.existsSync)(targetDir) || !(0, node_fs_1.statSync)(targetDir).isDirectory()) {
+        throw new Error(`Path alias '@${alias}' points to '${targetDir}', which is not an existing directory.`);
+    }
+    return path_1.default.normalize(path_1.default.resolve(targetDir, remainder));
+}
+function findWorkspaceConfig(startDir) {
+    let dir = path_1.default.resolve(startDir);
+    while (dir) {
+        for (const name of CONFIG_FILE_NAMES) {
+            const candidate = path_1.default.join(dir, name);
+            if ((0, node_fs_1.existsSync)(candidate))
+                return candidate;
+        }
+        const parent = path_1.default.dirname(dir);
+        dir = parent === dir ? null : parent;
+    }
+    return null;
+}
+function readWorkspacePaths(configPath) {
+    const cached = configPathsCache.get(configPath);
+    if (cached)
+        return cached;
+    let paths = {};
+    try {
+        const doc = js_yaml_1.default.load((0, node_fs_1.readFileSync)(configPath, 'utf-8'));
+        if (doc && typeof doc.paths === 'object' && doc.paths)
+            paths = doc.paths;
+    }
+    catch {
+        // A malformed config leaves aliases unresolved; the unknown-alias error below is clearer.
+    }
+    configPathsCache.set(configPath, paths);
+    return paths;
 }
 function resolveAppId(val, cmdName) {
     if (typeof val === 'string' && val)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

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

@@ -74,7 +74,7 @@ screen recording, clipboard, `clear-state`/`uninstall-app`.
 | 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`, `--inject` |
+| `conductor launch-app <appId>`                        | Launch app (saved to session); `--no-stop-app`, `--argument key=value`, `--inject` (enables the `native-*` in-process instrument — see `conductor-native`) |
 | `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                           |

package/skills/conductor-inspect/SKILL.md

@@ -29,48 +29,13 @@ conductor capture-ui --output /tmp/screen.json
 conductor tap-on @e5
 ```
 
-## Native in-process inspection (iOS/tvOS simulator)
+## Native internals (colors, fonts, layers, live-edit)
 
 The commands above observe the app **externally** (accessibility snapshots), so
-they can't see real component colors, fonts, or the view-controller stack. When
-you need that native detail, launch the app with an injected in-process library
-and use the `native-*` commands. Requires `launch-app <appId> --inject` first
-(iOS/tvOS simulator only).
-
-| Command | Purpose |
-|---|---|
-| `conductor native-ping` | Verify the injected in-process control library is alive |
-| `conductor native-inspect` | Real UIView/CALayer tree: resolved colors (`#RRGGBBAA`), fonts, text (incl. React Native Fabric), corner radius, borders, shadows, gradients, and each node's `absFrame` |
-| `conductor native-nav` | Navigation state: `UINavigationController` stacks, tab selection, presented controllers, titles |
-| `conductor native-screenshot --output <p.png>` | In-process PNG of the key window |
-| `conductor native-image <x,y,w,h> --output <p.png>` | Extract a component as a PNG — pass a node's `absFrame` from `native-inspect` |
-| `conductor native-snapshot <id> --output <p.png>` | Isolated PNG of one view's own content (transparent) — per-layer texture for a 3D explosion; `--with-subviews` composites the subtree |
-| `conductor native-console [--since <n>]` / `native-network [--since <n>]` | App stdout/stderr + captured HTTP; poll with the returned `cursor` |
-| `conductor native-heap --pattern <s> \| --class <name> \| --read <addr> [--key <keyPath>]` | Live-object browser (find classes/instances, read a property off an address) |
-| `conductor native-appearance <light\|dark\|system> \| --direction <ltr\|rtl> \| --anim-speed <n>` | Force appearance / RTL / freeze animations app-wide |
-| `conductor native-eval '<swift>'` | Compile & run arbitrary Swift inside the app (full UIKit / ObjC-runtime access); `--mode full` for a whole function body. e.g. `native-eval 'UIScreen.main.bounds'` |
-| `conductor native-raw <path>` | Escape hatch — GET any in-process endpoint (e.g. `'/get?id=..&keyPath=layer.cornerRadius'`, `'/class?id=..'`, `'/responders?id=..'`, `'/swiftui'`, `'/defaults'`, `'/focus'`, `'/snapshots?scale=0.5'`). Full list in `packages/ios-inproc/README.md`. |
-| `conductor native-view <id>` | Full property detail for one view (class chain, transform, layer, gestures, text/font) |
-| `conductor native-set <id> <key> <value>` | **Live-edit** a property: alpha, hidden, backgroundColor, tintColor, cornerRadius, borderWidth, borderColor, frame, text, textColor. `text`/`textColor` work on RN Fabric text views too |
-| `conductor native-props <id>` | React Native Fabric props: typed `ViewProps` + the raw JS prop bag (Fabric host views only) |
-
-> **Editing RN Fabric text/props:** the native plane can't set text on `RCTParagraphComponentView` (no native setter) and `native-props` returns `rawProps: null` on Fabric. Edit through React instead with `conductor native-rn-set --react-tag <n> --path children --value '"…"'` (and read raw JSX props with `native-rn-props --react-tag <n>`). `reactTag` comes from this tree's `rn.reactTag`. See the conductor-metro-debugger skill. Dev builds only.
-| `conductor native-constraints <id>` | Auto Layout constraints affecting a view + ambiguity |
-| `conductor native-hittest <x,y>` | Topmost view at a point + ancestor chain (select-by-point) |
-| `conductor native-highlight <id>` | Flash a highlight over the view on the device |
-| `conductor native-find [--class <name>] [--text <s>]` | Search views by class and/or text |
-
-Every `native-inspect` node has a stable `id` (for this launch). The Reveal-style loop:
-inspect → pick an `id` → `native-view` for detail → `native-set` to edit live → see it
-on the device. IDs are pointer-based and reset each launch, so re-inspect after relaunch.
-
-```bash
-conductor launch-app com.example.app --inject
-conductor native-inspect                              # tree with ids, colors, fonts, absFrame
-conductor native-view 0x10280d0c0                     # full detail for a view
-conductor native-set 0x10280d0c0 backgroundColor '#FF3B30FF'   # live-edit, visible on device
-conductor native-image 816,286,288,288 --output /tmp/avatar.png
-```
+they can't see real component colors, fonts, or the view-controller stack. For
+that native detail — or to live-edit a running app's view properties, force
+appearance/RTL, or run Swift in-process — use the **`conductor-native`** skill
+(`launch-app --inject` + the `native-*` commands; iOS/tvOS simulator, dev builds).
 
 ## Assertions
 

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

@@ -21,7 +21,8 @@ Playwright web.
 | `conductor native-rn-set --react-tag <n> --path <dot.path> --value <json>` | Live-edit an RN component's props via React DevTools `overrideProps` (text via `--path children`, color via `--path style.color`). Dev builds only |
 | `conductor native-rn-props --react-tag <n>` | Raw JSX props (`memoizedProps`) of an RN fiber by reactTag — the JS-side truth for Fabric where native `/props` `rawProps` is null |
 
-`--react-tag` comes from `native-inspect`'s `rn.reactTag`. `--value` is JSON (a bare
+`--react-tag` comes from `native-inspect`'s `rn.reactTag` (see `conductor-native`
+for the native-plane instrument). `--value` is JSON (a bare
 string works for text). `--path` is a dot path into props: `children`, `style.color`,
 `style.fontSize`, `accessibilityLabel`. `style.color` works whether the component's
 `style` is an object or a composed array. These drive React itself over Metro CDP, so

package/skills/conductor-native/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: conductor-native
+description: Inspect and live-edit a running app's native internals with the conductor CLI's in-process instrument (iOS/tvOS simulator, requires launch-app --inject). Use when you need real native view details the accessibility tree can't show — resolved colors/fonts/layers, the UIViewController/navigation stack, Auto Layout constraints, live-object heap — or to tweak the running app in place: set a view's properties (color, text, frame), force dark/RTL/animation state, or run arbitrary Swift inside the process.
+---
+
+# Conductor — native in-process inspection & live editing
+
+The external commands in `conductor-inspect` observe the app through the
+**accessibility tree**, so they can't see real component colors, fonts, layers,
+or the view-controller stack. When you need that native detail — or want to
+tweak the running app in place — launch with an injected in-process library and
+use the `native-*` commands.
+
+Requires `launch-app <appId> --inject` first. **iOS/tvOS simulator, dev builds
+only.** IDs are pointer-based and reset each launch, so re-inspect after relaunch.
+
+## Inspect the native plane
+
+| Command | Purpose |
+|---|---|
+| `conductor native-ping` | Verify the injected in-process control library is alive |
+| `conductor native-inspect` | Real UIView/CALayer tree: resolved colors (`#RRGGBBAA`), fonts, text (incl. React Native Fabric), corner radius, borders, shadows, gradients, and each node's `absFrame` |
+| `conductor native-nav` | Navigation state: `UINavigationController` stacks, tab selection, presented controllers, titles |
+| `conductor native-view <id>` | Full property detail for one view (class chain, transform, layer, gestures, text/font) |
+| `conductor native-props <id>` | React Native Fabric props: typed `ViewProps` + the raw JS prop bag (Fabric host views only) |
+| `conductor native-constraints <id>` | Auto Layout constraints affecting a view + ambiguity |
+| `conductor native-hittest <x,y>` | Topmost view at a point + ancestor chain (select-by-point) |
+| `conductor native-find [--class <name>] [--text <s>]` | Search views by class and/or text |
+| `conductor native-heap --pattern <s> \| --class <name> \| --read <addr> [--key <keyPath>]` | Live-object browser (find classes/instances, read a property off an address) |
+| `conductor native-console [--since <n>]` / `native-network [--since <n>]` | App stdout/stderr + captured HTTP; poll with the returned `cursor` |
+| `conductor native-screenshot --output <p.png>` | In-process PNG of the key window |
+| `conductor native-image <x,y,w,h> --output <p.png>` | Extract a component as a PNG — pass a node's `absFrame` from `native-inspect` |
+| `conductor native-snapshot <id> --output <p.png>` | Isolated PNG of one view's own content (transparent); `--with-subviews` composites the subtree |
+| `conductor native-raw <path>` | Escape hatch — GET any in-process endpoint (e.g. `'/get?id=..&keyPath=layer.cornerRadius'`, `'/class?id=..'`, `'/responders?id=..'`, `'/swiftui'`, `'/defaults'`, `'/focus'`, `'/snapshots?scale=0.5'`). Full list in `packages/ios-inproc/README.md`. |
+
+## Live-edit the running app
+
+| Command | Purpose |
+|---|---|
+| `conductor native-set <id> <key> <value>` | **Live-edit** a property: alpha, hidden, backgroundColor, tintColor, cornerRadius, borderWidth, borderColor, frame, text, textColor. `text`/`textColor` work on RN Fabric text views too |
+| `conductor native-highlight <id>` | Flash a highlight over the view on the device |
+| `conductor native-appearance <light\|dark\|system> \| --direction <ltr\|rtl> \| --anim-speed <n>` | Force appearance / RTL / freeze animations app-wide |
+| `conductor native-eval '<swift>'` | Compile & run arbitrary Swift inside the app (full UIKit / ObjC-runtime access); `--mode full` for a whole function body. e.g. `native-eval 'UIScreen.main.bounds'` |
+
+> **Editing RN Fabric text/props:** the native plane can't set text on `RCTParagraphComponentView` (no native setter) and `native-props` returns `rawProps: null` on Fabric. Edit through React instead with `conductor native-rn-set --react-tag <n> --path children --value '"…"'` (and read raw JSX props with `native-rn-props --react-tag <n>`). `reactTag` comes from this tree's `rn.reactTag`. See the `conductor-metro-debugger` skill. Dev builds only.
+
+## The Reveal-style loop
+
+Every `native-inspect` node has a stable `id` (for this launch): inspect →
+pick an `id` → `native-view` for detail → `native-set` to edit live → see it on
+the device. Re-inspect after relaunch (IDs reset).
+
+```bash
+conductor launch-app com.example.app --inject
+conductor native-inspect                              # tree with ids, colors, fonts, absFrame
+conductor native-view 0x10280d0c0                     # full detail for a view
+conductor native-set 0x10280d0c0 backgroundColor '#FF3B30FF'   # live-edit, visible on device
+conductor native-image 816,286,288,288 --output /tmp/avatar.png
+```
+
+## Related
+
+- `conductor-inspect` — external observation (a11y snapshots, screenshots, `@eN` refs) + assertions.
+- `conductor-metro-debugger` — the React/JS plane: `native-rn-set` / `native-rn-props`, `debug evaluate`, component tree, logs, network.