fix(runner): link pinned packages into the outer hop

[Chase J (chajac)]

Note

PR body AI drafted & edited as needed

Overview of Changes

qawolf flows run fails with ERR_MODULE_NOT_FOUND: Cannot find package '@qawolf/flows' when a project dependency (e.g. @qawolf/pom) peer-depends on a pinned executor package. The fallback npm install --legacy-peer-deps never installs peer deps, and the inner hop that owns the pinned packages is not on the resolution path of packages living in the outer hop — Node resolution only walks upward, and exec/node_modules is a sibling subtree. Flows built on the page-object pattern hit this on every install-mode run, on all three channels (node, bun, compiled binary).

How it works

• Outer-hop pinned links (outerHop.ts): after the fallback install, every pinned package is linked from the managed runtime into runDir/node_modules via linkPinnedPackages — extracted from populateInnerHop and now shared by both hops. Executor names are already stripped from the install list so no collision is possible, and an npm-installed copy of a pinned package (regular transitive dep) is replaced — the whole run resolves a single instance of each executor package through the shared realpath. Symlink-mode outer hops are untouched: we never inject into the user's tree, and package managers install peers there natively.
• Pin bump: @qawolf/flows 0.1.1 → 0.1.4, satisfying @qawolf/pom's ^0.1.4 peer range. 0.1.4 adds expect-webdriverio as a peer and imports it from configureFlowRuntime (loaded on every run), so it is pinned too (5.6.5) — the --legacy-peer-deps managed-runtime install would otherwise never provide it.

Testing

bun run typecheck
bun run lint
bun run format:check
bun run knip
bun run test
bun run build

• New tests: pinned links created in install mode; prefer-pinned replacement of an npm-installed copy; no injection in symlink mode. Install-mode tests moved to outerHop.install.test.ts (file-size cap).
• A/B verified on real builds against a repro project declaring @qawolf/pom with no local node_modules:

Scenario	Pre-fix	Fixed
Repro project (@qawolf/pom dep), node CLI	❌ Cannot find package '@qawolf/flows' from @qawolf/pom/dist	✅ pass
Same project, compiled binary	❌ ResolveMessage: Cannot find module '@qawolf/flows/web'	✅ pass
Real pulled bundle using the POM pattern (17 deps, latest + workspace:* specs)	❌ fails at import on every POM-importing flow	✅ pass, including a full real flow run to completion (98s)

Checklist

• Changes follow the code style of this project
• Self-review completed
• Tests added/updated (or not applicable)
• No breaking changes (or described below)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1b6cbf3c-3dba-4824-9553-52968c651941

📥 Commits

Reviewing files that changed from the base of the PR and between 05de8e4 and d55f6ab.

⛔ Files ignored due to path filters (1)

• bun.lock is excluded by !**/*.lock

📒 Files selected for processing (10)

• .changeset/outer-hop-pinned-links.md
• package.json
• scripts/genDependencyVersions.ts
• src/domains/runtimeEnv/innerHop.ts
• src/domains/runtimeEnv/linkPinnedPackages.ts
• src/domains/runtimeEnv/outerHop.install.test.ts
• src/domains/runtimeEnv/outerHop.test.ts
• src/domains/runtimeEnv/outerHop.ts
• src/domains/runtimeEnv/pinnedPackages.ts
• src/domains/runtimeEnv/prepareRunDir.ts

---

Walkthrough

The runtime dependency set updates @qawolf/flows and adds the generated expect-webdriverio version to pinned packages. A shared utility now links pinned packages from the managed dependency root into inner and installed outer hops, replacing existing targets when necessary. populateOuterHop receives depsRoot, and prepareRunDir forwards it. Tests cover install fallback, symlink replacement, non-install modes, and dependency-root handling.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant prepareRunDir
  participant populateOuterHop
  participant linkPinnedPackages
  participant depsRoot
  prepareRunDir->>populateOuterHop: pass depsRoot
  populateOuterHop->>linkPinnedPackages: link pinned packages after install
  linkPinnedPackages->>depsRoot: read pinned packages
  linkPinnedPackages-->>populateOuterHop: create links in runDir/node_modules

Loading

Suggested reviewers: michael-pr

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows Conventional Commits and accurately summarizes the outer-hop pinned-package fix.
Description check	✅ Passed	The description covers overview, testing, and checklist sections and is mostly complete against the template.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch outer-hop-pinned-links

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

_{Comment @coderabbitai help to get the list of available commands.}