refactor: normalise on rootDir in most usages

[danielroe]

🔗 Linked issue

resolves #365
closes #450

📚 Description

this is backwards-compatible. it removes the deprecation of the positional rootDir argument, which is too firmly entrenched in nuxt examples and documentation to remove at this point.

and it hides --cwd in most cases, while still supporting it, to avoid confusion between 'working directory' and 'root directory'. as a side effect, we also resolve #365 because we parse/handle cwd manually 🙌

[pkg-pr-new]

• nuxt-cli-playground

  npm i https://pkg.pr.new/create-nuxt@1398
  

  npm i https://pkg.pr.new/nuxi@1398
  

  npm i https://pkg.pr.new/@nuxt/cli@1398
  

commit: e60fbf0

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks

---

_{Comparing refactor/rootdir (e60fbf0) with main (27d8296)}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 47d91356-af3d-4ee5-95a1-f6121c5a1ef4

📥 Commits

Reviewing files that changed from the base of the PR and between 74699ee and e60fbf0.

📒 Files selected for processing (26)

• packages/nuxt-cli/src/commands/_shared.ts
• packages/nuxt-cli/src/commands/analyze.ts
• packages/nuxt-cli/src/commands/build.ts
• packages/nuxt-cli/src/commands/cleanup.ts
• packages/nuxt-cli/src/commands/dev-child.ts
• packages/nuxt-cli/src/commands/dev.ts
• packages/nuxt-cli/src/commands/devtools.ts
• packages/nuxt-cli/src/commands/generate.ts
• packages/nuxt-cli/src/commands/info.ts
• packages/nuxt-cli/src/commands/init.ts
• packages/nuxt-cli/src/commands/prepare.ts
• packages/nuxt-cli/src/commands/preview.ts
• packages/nuxt-cli/src/commands/test.ts
• packages/nuxt-cli/src/commands/typecheck.ts
• packages/nuxt-cli/src/commands/upgrade.ts
• packages/nuxt-cli/src/main.ts
• packages/nuxt-cli/src/run-command.ts
• packages/nuxt-cli/src/run.ts
• packages/nuxt-cli/src/utils/args.ts
• packages/nuxt-cli/src/utils/paths.ts
• packages/nuxt-cli/test/unit/commands/typecheck.spec.ts
• packages/nuxt-cli/test/unit/global-args.spec.ts
• packages/nuxt-cli/test/unit/help.spec.ts
• packages/nuxt-cli/test/unit/run.spec.ts
• packages/nuxt-cli/test/unit/utils/args.spec.ts
• packages/nuxt-cli/test/unit/utils/paths.spec.ts

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

• packages/nuxt-cli/test/unit/run.spec.ts
• packages/nuxt-cli/src/commands/test.ts
• packages/nuxt-cli/src/commands/cleanup.ts
• packages/nuxt-cli/src/commands/devtools.ts
• packages/nuxt-cli/src/commands/build.ts
• packages/nuxt-cli/src/commands/init.ts
• packages/nuxt-cli/test/unit/global-args.spec.ts
• packages/nuxt-cli/src/commands/analyze.ts
• packages/nuxt-cli/src/commands/dev.ts
• packages/nuxt-cli/src/main.ts
• packages/nuxt-cli/src/run-command.ts
• packages/nuxt-cli/src/commands/dev-child.ts
• packages/nuxt-cli/src/commands/generate.ts
• packages/nuxt-cli/src/commands/info.ts
• packages/nuxt-cli/src/commands/typecheck.ts
• packages/nuxt-cli/test/unit/commands/typecheck.spec.ts
• packages/nuxt-cli/src/utils/args.ts
• packages/nuxt-cli/src/commands/prepare.ts
• packages/nuxt-cli/src/commands/_shared.ts
• packages/nuxt-cli/src/utils/paths.ts
• packages/nuxt-cli/test/unit/utils/paths.spec.ts
• packages/nuxt-cli/test/unit/help.spec.ts

---

📝 Walkthrough

Walkthrough

The CLI now exposes a unified optional ROOTDIR argument and resolves it through resolveRootDir, with --cwd taking precedence and warning on conflicts. Raw --cwd arguments are normalized before command parsing while preserving caller arrays. Nuxt commands now use the shared argument and path utilities. Tests cover normalization, precedence, forwarding, immutability, command invocation, and updated help output.

Estimated code review effort: 4 (Complex) | ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 27.27% 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
Title check	✅ Passed	The title is concise and accurately summarizes the main change: standardizing CLI usage around rootDir.
Description check	✅ Passed	The description is clearly related to the changeset and mentions the same rootDir and --cwd behavior.
Linked Issues check	✅ Passed	The code supports --cwd before subcommands and modernizes rootDir handling in line with the linked issues [#365, #450].
Out of Scope Changes check	✅ Passed	I don't see unrelated or out-of-scope code changes beyond the CLI argument and test updates.

✨ 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 refactor/rootdir

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 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/nuxt-cli/src/utils/args.ts`:
- Around line 24-25: Update the argument-building logic around the rawArgs
construction to insert the normalized --cwd flag immediately before the --
separator when one is present, rather than always appending it. Preserve
existing behavior when no separator exists, and add a unit test covering nuxi
--cwd apps/web test -- --watch so the parser receives cwd correctly.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 67c68061-5ec3-4d63-8eab-8c01732f5c41

📥 Commits

Reviewing files that changed from the base of the PR and between 79a829d and c71eb76.

📒 Files selected for processing (26)

• packages/nuxt-cli/src/commands/_shared.ts
• packages/nuxt-cli/src/commands/analyze.ts
• packages/nuxt-cli/src/commands/build.ts
• packages/nuxt-cli/src/commands/cleanup.ts
• packages/nuxt-cli/src/commands/dev-child.ts
• packages/nuxt-cli/src/commands/dev.ts
• packages/nuxt-cli/src/commands/devtools.ts
• packages/nuxt-cli/src/commands/generate.ts
• packages/nuxt-cli/src/commands/info.ts
• packages/nuxt-cli/src/commands/init.ts
• packages/nuxt-cli/src/commands/prepare.ts
• packages/nuxt-cli/src/commands/preview.ts
• packages/nuxt-cli/src/commands/test.ts
• packages/nuxt-cli/src/commands/typecheck.ts
• packages/nuxt-cli/src/commands/upgrade.ts
• packages/nuxt-cli/src/main.ts
• packages/nuxt-cli/src/run-command.ts
• packages/nuxt-cli/src/run.ts
• packages/nuxt-cli/src/utils/args.ts
• packages/nuxt-cli/src/utils/paths.ts
• packages/nuxt-cli/test/unit/commands/typecheck.spec.ts
• packages/nuxt-cli/test/unit/global-args.spec.ts
• packages/nuxt-cli/test/unit/help.spec.ts
• packages/nuxt-cli/test/unit/run.spec.ts
• packages/nuxt-cli/test/unit/utils/args.spec.ts
• packages/nuxt-cli/test/unit/utils/paths.spec.ts