fix: resolve Pro squad script dependencies

[rafaelscosta]

Summary

• Ports the approved fix: symlink node_modules so squad scripts can resolve framework deps #624 dependency-resolution fix into the active v4/Pro install path instead of only the legacy bin/aiox-init.js fallback.
• Adds an idempotent installer helper that links project node_modules to .aiox-core/node_modules only when the project has no node_modules of its own.
• Integrates that helper into Pro content scaffolding so copied squads/**/scripts can resolve framework dependencies like js-yaml.
• Keeps the legacy aiox-init.js fallback aligned with the original fix: symlink node_modules so squad scripts can resolve framework deps #624 patch.
• Bumps core package/manifest to 5.1.6.

Validation

• node -c packages/installer/src/installer/aiox-core-installer.js && node -c packages/installer/src/pro/pro-scaffolder.js && node -c bin/aiox-init.js
• npm test -- tests/installer/aiox-core-installer.test.js tests/installer/pro-scaffolder.test.js --runInBand
• Pro scaffolder smoke with real pro/ content: require.resolve('js-yaml') from squads/squad-creator-pro/scripts resolves through .aiox-core/node_modules
• npm run validate:manifest
• npm run validate:publish
• npm run lint -- --quiet
• npm run typecheck
• npm run test:ci — 314 suites passed, 7,834 tests passed, 149 skipped
• git diff --check

Refs #624

Summary by CodeRabbit

• New Features

  • Added an optional installer helper to create a project-level node_modules link to the framework when appropriate; installer now attempts this and reports status.

• Bug Fixes

  • Resolved dependency resolution issues for Pro squad scripts that previously failed with module not found errors when run from the installed project root.

• Tests

  • Added tests covering the new linking behavior and related regression scenarios.

• Chores

  • Version bumped to 5.1.6.

• Documentation

  • Updated story/docs describing the dependency-resolution fix and acceptance criteria.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aiox-core	Ready	Preview, Comment	May 7, 2026 1:00pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: eef097f2-f348-45ae-9763-60f4c42b6cbb

📥 Commits

Reviewing files that changed from the base of the PR and between 0fab945 and c955751.

📒 Files selected for processing (4)

• bin/aiox-init.js
• package.json
• packages/installer/package.json
• packages/installer/src/pro/pro-scaffolder.js

✅ Files skipped from review due to trivial changes (1)

• packages/installer/package.json

🚧 Files skipped from review as they are similar to previous changes (3)

• package.json
• bin/aiox-init.js
• packages/installer/src/pro/pro-scaffolder.js

---

Walkthrough

This PR adds ensureProjectNodeModulesLink(), exposes it via package exports, uses it in Pro-scaffolder and the legacy installer to create a project root node_modules link to .aiox-core/node_modules when appropriate, and adds tests, docs, and a version/manifest bump.

Changes

Squad Dependency Resolution Fix

Layer / File(s)	Summary
Public API & Core Logic packages/installer/src/installer/aiox-core-installer.js, packages/installer/package.json, package.json export entry	Add exported async ensureProjectNodeModulesLink() that checks project vs .aiox-core/node_modules, computes platform link type, creates the link when needed, and returns structured result objects.
Pro-Scaffolder Integration packages/installer/src/pro/pro-scaffolder.js	Import and call the new helper after installing squad commands; set result.dependencyResolution, register linked path for rollback on success, emit progress, and log warnings on failure.
Legacy Installer Alignment bin/aiox-init.js	Dynamically import the helper when available and invoke it after copying .aiox-core, printing success or a non-fatal warning on failure.
Tests & Documentation docs/stories/epic-123/STORY-123.10-squad-dependency-resolution.md, tests/installer/aiox-core-installer.test.js, tests/installer/pro-scaffolder.test.js	Add story documenting acceptance criteria; unit tests for linking success, non-overwrite when project has node_modules, and graceful failure; integration test verifying scaffolded squad scripts resolve framework deps via the link.
Version & Manifest Updates package.json, .aiox-core/install-manifest.yaml	Bump package version 5.1.5 → 5.1.6 and refresh install-manifest generated_at timestamp; add exports subpath for the new installer helper.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix: align Pro package release gates #657

Suggested labels

area: installer, area: pro, area: core, type: test

Suggested reviewers

• oalanicolas
• Pedrovaleriolopez

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix: resolve Pro squad script dependencies' directly and clearly summarizes the main change—fixing dependency resolution for Pro squad scripts by linking node_modules to .aiox-core/node_modules.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pr-624-squad-dependency-resolution-20260507

Warning

Review ran into problems

🔥 Problems

Timed out fetching pipeline failures after 30000ms

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

📊 Coverage Report

Coverage report not available

📈 Full coverage report available in Codecov

---

Generated by PR Automation (Story 6.1)

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

bin/aiox-init.js (1)

521-539: ⚡ Quick win

Avoid duplicating node_modules-link logic in legacy installer.

This block now duplicates behavior already implemented in ensureProjectNodeModulesLink; reusing that helper would reduce drift risk between install paths.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@bin/aiox-init.js` around lines 521 - 539, Replace the duplicated node_modules
symlink code with a call to the existing helper ensureProjectNodeModulesLink so
we don't drift behavior; locate the block that checks context.projectRoot and
targetCoreDir and remove it, then invoke ensureProjectNodeModulesLink(...) with
the same inputs (pass context and/or targetCoreDir as the helper expects) and
rely on that helper to perform platform-specific linking and logging/error
handling (ensureProjectNodeModulesLink, context.projectRoot, targetCoreDir are
the identifying symbols to use).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/installer/src/pro/pro-scaffolder.js`:
- Line 18: The require for ensureProjectNodeModulesLink in pro-scaffolder.js
uses a relative path; update that require to use the repository's
absolute-import module name (replace require('../installer/aiox-core-installer')
with the canonical absolute module import used elsewhere in the repo) so
ensureProjectNodeModulesLink is imported via the absolute module path and not a
relative path, then run lint/tests to verify.

---

Nitpick comments:
In `@bin/aiox-init.js`:
- Around line 521-539: Replace the duplicated node_modules symlink code with a
call to the existing helper ensureProjectNodeModulesLink so we don't drift
behavior; locate the block that checks context.projectRoot and targetCoreDir and
remove it, then invoke ensureProjectNodeModulesLink(...) with the same inputs
(pass context and/or targetCoreDir as the helper expects) and rely on that
helper to perform platform-specific linking and logging/error handling
(ensureProjectNodeModulesLink, context.projectRoot, targetCoreDir are the
identifying symbols to use).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9cc33941-5296-4414-83de-048545f2f1cb

📥 Commits

Reviewing files that changed from the base of the PR and between 125698c and 0fab945.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (8)

• .aiox-core/install-manifest.yaml
• bin/aiox-init.js
• docs/stories/epic-123/STORY-123.10-squad-dependency-resolution.md
• package.json
• packages/installer/src/installer/aiox-core-installer.js
• packages/installer/src/pro/pro-scaffolder.js
• tests/installer/aiox-core-installer.test.js
• tests/installer/pro-scaffolder.test.js