feat(runner): isolate runtime deps to fix workspace monorepo failures

.changeset/layered-runtime-deps-resolution.md

@@ -0,0 +1,5 @@
+---
+"@qawolf/cli": minor
+---
+
+Resolve flow runtime dependencies through a layered, project-isolated `node_modules` so flows run correctly in monorepos, single-package projects, and empty directories across both the Node and compiled-binary channels. The CLI-owned executor is always pinned and never pollutes or is shadowed by the surrounding project, while the flow's own declared dependencies still resolve. Adds `qawolf install clear` to wipe the managed runtime cache.

knip.config.ts

@@ -12,7 +12,7 @@ const config: KnipConfig = {
   ignoreDependencies: [
     // TODO WIZ-10341 follow-up: consumed once the web-flow runner imports it.
     "@playwright/test",
-    // Installed into the flow env dir at runtime by ensureFlowDeps; not imported by the CLI.
+    // Installed into the managed runtime dir at runtime by ensureRuntimeEnv; not imported by the CLI.
     "appium",
     "appium-xcuitest-driver",
     "appium-uiautomator2-driver",

package.json

@@ -36,7 +36,7 @@
   },
   "scripts": {
     "build": "bun run generate && bun scripts/build.ts",
-    "build:binary": "bun run generate && bun scripts/buildBinary.ts",
+    "build:binary": "bun run build && bun scripts/buildBinary.ts",
     "dev": "bun run src/main.ts",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",

scripts/buildBinary.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 // Compiles the standalone binary (default dist/qawolf); the release-binaries workflow passes --target/--outfile per platform.
 import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 const { values } = parseArgs({
@@ -10,11 +11,33 @@ const { values } = parseArgs({
   },
 });
 
+// Generate the compile entry in dist/ (excluded from tsc + knip): it embeds the
+// already-built dist/cli.js as a Bun file asset, exports its extracted path via
+// env, then runs the CLI from source. Generated rather than kept in src/ so
+// neither tsc (which cannot model the file-asset import) nor knip (which cannot
+// see a string-arg entry) trips on it. cli.js is the same bundle the runner
+// spawns as a BUN_BE_BUN worker so flows resolve their own node_modules —
+// including native modules like sharp — at runtime, which the in-process
+// compiled resolver cannot. Never bundled into cli.js (build.ts builds
+// src/main.ts), so there is no embed cycle.
+const entryPath = "dist/binary-entry.ts";
+writeFileSync(
+  entryPath,
+  [
+    'import cliAsset from "./cli.js" with { type: "file" };',
+    "",
+    "process.env.QAWOLF_EMBEDDED_CLI_PATH = cliAsset;",
+    "",
+    'await import("../src/main.ts");',
+    "",
+  ].join("\n"),
+);
+
 const buildArgs = [
   "build",
   "--compile",
   ...(values.target ? [`--target=${values.target}`] : []),
-  "./src/main.ts",
+  entryPath,
   "--outfile",
   values.outfile,
   // unlike the npm bundle (build.ts), only these stay external — ensureDeps installs them on demand

skills/qawolf-cli/SKILL.md

@@ -48,6 +48,7 @@ write on timeout: it may have reached the server the first time.
 | `qawolf install`          | local                      | Install every runtime dependency the project's flows need                                                              |
 | `qawolf install android`  | local                      | Install Android system images, AVDs, and the Appium driver used by the project's Android flows                         |
 | `qawolf install browsers` | local                      | Install Playwright browsers used by the project's web flows                                                            |
+| `qawolf install clear`    | local                      | Remove the managed runtime cache (all installed runtime versions)                                                      |
 | `qawolf run create`       | write                      | Create a run for selected flows in an environment.                                                                     |
 
 <!-- commands-table:end -->

src/commands/__snapshots__/help.test.ts.snap

@@ -54,6 +54,8 @@ Commands:
                       flows
   android [pattern]   Install Android system images, AVDs, and the Appium driver
                       used by the project's Android flows
+  clear [options]     Remove the managed runtime cache (all installed runtime
+                      versions)
 
 Examples:
   $ qawolf install
@@ -90,6 +92,21 @@ Examples:
 "
 `;
 
+exports[`--help output qawolf install clear 1`] = `
+"Usage: qawolf install clear [options]
+
+Remove the managed runtime cache (all installed runtime versions)
+
+Options:
+  --yes       Skip the confirmation prompt (default: false)
+  -h, --help  display help for command
+
+Examples:
+  $ qawolf install clear
+  $ qawolf install clear --yes
+"
+`;
+
 exports[`--help output qawolf doctor 1`] = `
 "Usage: qawolf doctor [options]
 
@@ -155,6 +172,9 @@ Options:
                         false)
   --env <env>           Pull and run a flow from this environment (UUID or slug)
                         if not cached locally
+  --deps <dir>          Use this prepared dependency directory instead of
+                        auto-installing the runtime; or set QAWOLF_RUNTIME_DIR
+                        to relocate the managed runtime
   -h, --help            display help for command
 
 Examples:

src/commands/doctor/handler.ts

@@ -6,8 +6,9 @@ import { resolveApiKey } from "~/domains/auth/resolve.js";
 import { runChecks } from "~/domains/doctor/checks/index.js";
 import { renderResults } from "~/domains/doctor/render.js";
 import type { CheckResult } from "~/domains/doctor/types.js";
-import { resolveUniqueEnvDir } from "~/domains/flows/ensureDeps.js";
+import { resolveProjectDirSafe } from "~/domains/flows/ensureDeps.js";
 import { expandPatterns, makePeekFlowMeta } from "~/domains/flows/expand.js";
+import { resolveDepsRootIfPresent } from "~/domains/runtimeEnv/index.js";
 import { resolveAppiumBin } from "~/shell/appium/resolveAppiumBin.js";
 import {
   type CommandContext,
@@ -39,17 +40,17 @@ export async function handleDoctor(
   const cwd = process.cwd();
   const flowFiles = await expandPatterns([], cwd, undefined, fs);
 
-  // Playwright lives in the env dir (installed by ensureFlowDeps), not in cwd.
-  // Silently fall back to cwd when no env dir is found or flows span multiple packages.
-  let envDir: string | undefined;
-  try {
-    envDir = resolveUniqueEnvDir([...flowFiles], fs);
-  } catch {
-    // multiple env dirs — fall back to cwd
-  }
+  // Playwright/Appium live in the resolved runtime dir (managed env or project), not cwd.
+  const projectDir = resolveProjectDirSafe([...flowFiles], fs);
+  const envDir = resolveDepsRootIfPresent(
+    projectDir !== undefined ? { projectDir } : {},
+    fs,
+  );
   let playwrightCliPath: string | undefined;
   try {
-    playwrightCliPath = resolvePlaywrightCli(envDir ?? cwd, process.platform);
+    playwrightCliPath = envDir
+      ? resolvePlaywrightCli(envDir, process.platform)
+      : undefined;
   } catch {
     playwrightCliPath = undefined;
   }

src/commands/flows/buildFlowsRunDeps.ts

@@ -0,0 +1,61 @@
+import { makePeekFlowMeta } from "~/domains/flows/expand.js";
+import { findFlowStamp as defaultFindFlowStamp } from "~/shell/manifest/lookup.js";
+import { installBrowserList } from "~/domains/install/browsers.js";
+import { defaultSpawn } from "~/shell/spawn.js";
+import { resolvePlaywrightCli } from "~/shell/playwright.js";
+import { runAndroidFlow as defaultRunAndroidFlow } from "~/domains/runner/runAndroidFlow.js";
+import { runWebFlow as defaultRunWebFlow } from "~/domains/runner/runWebFlow.js";
+import { makePooledDispatch } from "~/domains/runner/makePooledDispatch.js";
+import type { createAndroidDeps } from "~/domains/runner/runAndroidFlowDeps.js";
+import type { RunWebFlowDeps } from "~/domains/runner/runWebFlow.js";
+import type {
+  FlowsRunDeps,
+  FlowsRunFlags,
+} from "~/domains/runner/runInternals.js";
+import type { CommandContext } from "~/shell/commandContext.js";
+
+import { buildRunReporter } from "./buildRunReporter.js";
+
+type BuildFlowsRunDepsArgs = {
+  ctx: CommandContext;
+  resolvedDir: string;
+  android: ReturnType<typeof createAndroidDeps>;
+  runWebFlowDeps: RunWebFlowDeps;
+  flags: FlowsRunFlags;
+};
+
+/**
+ * Assembles the runner dependency bundle for `flowsRun`. Identical across the
+ * local (`flows run`) and hybrid (`--env`) entry points, so both share this
+ * single builder. `runWebFlowDeps` is resolved by the caller (it is async and
+ * the injection point for tests) and passed in already awaited.
+ */
+export function buildFlowsRunDeps(args: BuildFlowsRunDepsArgs): FlowsRunDeps {
+  const { ctx, resolvedDir, android, runWebFlowDeps, flags } = args;
+  return {
+    peekFlowMeta: makePeekFlowMeta(ctx.fs),
+    installBrowsers: (innerCtx, browsers) =>
+      installBrowserList(innerCtx, browsers, {
+        spawn: defaultSpawn,
+        platform: process.platform,
+        playwrightCliPath: resolvePlaywrightCli(resolvedDir, process.platform),
+      }),
+    runWebFlow: defaultRunWebFlow,
+    runWebFlowDeps,
+    runAndroidFlow: defaultRunAndroidFlow,
+    runAndroidFlowDeps: android.deps,
+    bootAndroid: android.boot,
+    shutdownAndroid: android.shutdown,
+    createPooledDispatch: makePooledDispatch(resolvedDir),
+    findFlowStamp: defaultFindFlowStamp,
+    warn: (message) => ctx.ui.warn(message),
+    logger: ctx.log("runner"),
+    // Route reporter output through ctx.ui so streamed test logs stay inside the run's timeline.
+    reporter: buildRunReporter(flags, {
+      fs: ctx.fs,
+      stdout: { write: (text: string) => ctx.ui.write(text) },
+      stderr: { write: (text: string) => ctx.ui.write(text) },
+    }),
+    now: () => Date.now(),
+  };
+}