Skip to content

feat(cli): refuse vp dev/build in Nuxt and Astro projects - #2456

Draft
fengmk2 wants to merge 7 commits into
mainfrom
feat/dev-framework-guard
Draft

fengmk2 wants to merge 7 commits into
mainfrom
feat/dev-framework-guard

Conversation

@fengmk2

@fengmk2 fengmk2 commented Aug 14, 2026 •

Copy link
Copy Markdown
Member

Refs #1506. First step from #1506 (comment): detect a Nuxt or Astro config, refuse vp dev / vp build, and point at vp run dev.

Both commands run the bundled Vite CLI, which cannot serve or build a Nuxt or Astro project: dev answers every URL with 404, and build fails on the missing index.html entry (repros: nuxt, astro). Now:

$ vp dev
error: this project uses Nuxt (nuxt.config.ts). `vp dev` runs the bundled Vite CLI, not the Nuxt CLI.
hint: did you mean `vp run dev`?

The guard sits in the NAPI binding dispatch, so the local and global CLI behave the same. It checks the config files each framework loader resolves: nuxt.config.{js,ts,mjs,cjs,mts,cts} and astro.config.{mjs,js,ts,mts}, with the upstream sources cited in code comments. Without a dev/build script, the hint points at a script that runs the framework command under another name, or at vp exec nuxt dev. The guard checks direct invocations only: a command spawned from a task or package script, such as a "dev": "vp dev" script, runs as invoked. An explicit --config/-c flag skips the refusal. A positional directory target (vp dev apps/web) is not inspected.

Covered by unit tests, the builtin_framework_guard PTY snapshot fixture (local and global flavors), and docs updates in guide/run.md and guide/troubleshooting.md.

vp dev and vp build run the bundled Vite CLI, which cannot serve or
build a Nuxt or Astro project: dev answers every URL with 404 and build
fails on the missing index.html entry. Detect nuxt.config.* or
astro.config.* next to the nearest package.json and stop with an error
that points at vp run <command>. An explicit --config/-c flag skips the
refusal.

Refs #1506
@netlify

netlify Bot commented Aug 14, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for viteplus-preview canceled.

Name Link
🔨 Latest commit ae9bdba
🔍 Latest deploy log https://app.netlify.com/projects/viteplus-preview/deploys/6a81a057f1aafb00082d00b6

@github-actions

github-actions Bot commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor

✅ Staging deployment successful!

Preview: https://viteplus-staging.void.app/
Commit: ae9bdba

@fengmk2 fengmk2 added the preview-build Publish this PR's commits to the registry bridge as preview builds label Aug 14, 2026
@github-actions

github-actions Bot commented Aug 14, 2026 •

Copy link
Copy Markdown
Contributor

Native binary sizes (ae9bdba)

Final release artifacts built by the canonical build-upstream and build-windows-cli actions.

Artifact Format Base PR Change
vp (Linux x64) Binary 10.67 MiB 10.67 MiB 0 B (0.00%)
vp (Linux x64) gzip -9 4.62 MiB 4.62 MiB 0 B (0.00%)
NAPI (Linux x64) Binary 32.02 MiB 32.03 MiB +12.00 KiB (+0.04%)
NAPI (Linux x64) gzip -9 12.61 MiB 12.61 MiB +1.67 KiB (+0.01%)
vp (macOS ARM64) Binary 7.98 MiB 7.98 MiB 0 B (0.00%)
vp (macOS ARM64) gzip -9 4.03 MiB 4.03 MiB 0 B (0.00%)
NAPI (macOS ARM64) Binary 39.68 MiB 39.68 MiB +16 B (+0.00%)
NAPI (macOS ARM64) gzip -9 16.92 MiB 16.92 MiB +3.97 KiB (+0.02%)
vp (Windows x64) Binary 8.55 MiB 8.55 MiB 0 B (0.00%)
vp (Windows x64) gzip -9 3.73 MiB 3.73 MiB +1 B (+0.00%)
NAPI (Windows x64) Binary 26.89 MiB 26.90 MiB +8.50 KiB (+0.03%)
NAPI (Windows x64) gzip -9 10.68 MiB 10.68 MiB +1.35 KiB (+0.01%)
Trampoline (Windows x64) Binary 205.00 KiB 205.00 KiB 0 B (0.00%)
Trampoline (Windows x64) gzip -9 99.00 KiB 99.00 KiB -1 B (-0.00%)
Installer (Windows x64) Binary 4.47 MiB 4.47 MiB 0 B (0.00%)
Installer (Windows x64) gzip -9 2.09 MiB 2.09 MiB 0 B (0.00%)

Astro only searches astro.config.{mjs,js,ts,mts} (configPaths in
withastro/astro), so drop the .cjs/.cts names it never loads. Nuxt
resolves nuxt.config through c12, which accepts all six script
extensions. Cite the pinned upstream sources in the framework table.

Also reword the refusal to 'this project uses <name>' and drop the
article field it needed.
Split the refusal error into two sentences and rewrite the guard
comments, docs, and fixture comments in short active sentences.
Re-record the fixture snapshots for the new wording.
Without a script named after the command, the old hint pointed at a
vp run task that does not exist. The hint now picks the first path
that works: the same-name script, a script that runs the framework
command under another name (matched on whitespace boundaries against
the nuxt/nuxi/astro bins), or the framework CLI through vp exec.
Add snapshot coverage for the no-scripts and renamed-script cases.
@fengmk2

fengmk2 commented Aug 14, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8abcf9a6b5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/cli/binding/src/cli/framework_guard.rs Outdated
Comment thread packages/cli/binding/src/cli/mod.rs Outdated
Comment thread docs/guide/troubleshooting.md Outdated
A package script can run vp dev or vp build itself. The guard now
checks direct invocations only, with the same task and
npm_lifecycle_event gate the script note uses (extracted as
spawned_from_script). Add task-spawned and npm-spawned snapshot cases
that build through a nested vp build without a refusal.
@tobiasdiez

Copy link
Copy Markdown

From a user's perspective, would it not be more convenient if vp dev actually falls back to vp run dev for a nuxt project?

As far as I understand the discussion in #1506, proper support for nuxt/astro is desired just not very high on the prio queue. So for training the correct muscle memory, supporting vp dev in some form would be nice.

@fengmk2

fengmk2 commented Aug 16, 2026

Copy link
Copy Markdown
Member Author

@tobiasdiez That's a different issue. Currently, built-in commands are still not allowed to be overridden.

Run the refusal after resolve_app_target, so defaultPackage keeps
acting as an implicit -C and the hint comes from the target package.
The script note asks the guard first (print-free applies) and stays
silent right before a refusal.

Let help and version requests reach the tool: vp dev --help prints the
Vite help again. Tokens after the -- terminator stay positionals, for
the config bypass too.

Qualify the docs: the hint points at the matching script, or at vp exec
when no script matches.
@fengmk2

fengmk2 commented Aug 16, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dad5d88aec

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/cli/binding/src/cli/framework_guard.rs Outdated
Comment thread packages/cli/binding/src/cli/framework_guard.rs Outdated
Comment thread packages/cli/binding/src/cli/framework_guard.rs Outdated
Comment thread packages/cli/binding/src/cli/mod.rs Outdated
Classify the args with the app-target walk: a positional is the Vite
root and becomes the guarded directory, and explicit invocations
(help/version, --config) reach the tool. This replaces the hand-rolled
flag scans.

Validate the same-named script's command before recommending it: an
unrelated "dev": "storybook dev" no longer becomes the hint.

Carry the resolved target into the hints as -C <target> after a
defaultPackage or picker retarget, and for positional roots.

Refuse at a framework workspace root instead of falling into package
elicitation. An explicit defaultPackage still wins.
fengmk2 pushed a commit that referenced this pull request Oct 15, 2026
<!-- claude-projects-attribution: {"github_login":"Brooooooklyn"} -->
_Requested by **Brooklyn** · [project
thread](https://claude.ai/code/project/chan_018s9RxRdtH424j2EhXdzV3N?thread=cmsg_018s9RxRdtH424j2EhXdzV3NQxbeR8Pt7qaqSQwoq9rEFo)_

<!-- routine:prune-tests:duplicate-shell-and-helper-tests -->

Before: `vp_global_cli` and `vp_pm_cli` carried Rust unit tests that
could not fail when the product broke: an `assert!(true)` in
`create.rs`, four `env use` shell-detection tests that repeat
`commands::shell` tests for code `env use` only imports, and three tests
of test-only helpers. `upgrade_check.rs` had 20 hand-unrolled lookup
tests.

After: those 8 tests are gone and the 20 lookup tests are 2 table-driven
tests that keep every row and comment, with the failing row named in the
assertion message. Only test code changes: every hunk is inside a
`#[cfg(test)]` module or the `#[cfg(test)]`-only
`resolution::test_utils` module.

How: each candidate was defended by mutating product code with the most
realistic regression only it would catch, running the crate's tests, and
reverting. No deleted test failed alone on any mutation.

### Totals

| | Before (origin/main c04bcf6) | After |
|---|---|---|
| Files touched | – | 5 |
| `vp_global_cli` cases collected (Linux) | 502 (+2 ignored) | 479 (+2
ignored) |
| `vp_pm_cli` cases collected | 923 (+2 ignored) | 920 (+2 ignored) |

- Cases deleted: **8** of 1,425 collected in the two touched crates.
Repo-wide: about 2,432 `#[test]`/`#[tokio::test]` attributes in tracked
Rust (static count) and 1,492 static `it`/`test` calls in 101 JS spec
files (not collected; Vitest needs a full `packages/core` build).
- Cases folded: **20 into 2**, every row and comment kept.
Runner-collected total: −26.
- Net lines: **−159** (+42 / −201).
- Runtime saved: about 0.03 s (the 8 deleted cases each report 0.000 s;
the 20 folded cases summed 0.028 s against 0.011 s for the 2
replacements).
- Test-binary time on this shared machine: `vp_global_cli` 3.13 s → 3.32
s, `vp_pm_cli` 27.81 s → 29.06 s (noise).

### Per file

1. **`crates/vp_global_cli/src/commands/create.rs` ›
`test_create_command_module_exists`**
   - Class: tautology (`assert!(true)`).
- Best defense: M1 (delegate `"new"` instead of `"create"`) passes all
502 tests, so this test cannot fail. The whole `mod tests` goes.
- Coverage gap (pre-existing, unchanged by this PR): no unit test covers
`vp create` delegation. It may be covered by the PTY snapshot suite,
which was not run.
2. **`crates/vp_global_cli/src/commands/env/use.rs` ›
`test_detect_shell_vp_shell_{powershell,fish,nu}`,
`test_detect_shell_posix_default`**
- Class: duplicates of stronger tests. `detect_shell` /
`Shell::from_str` live in `commands/shell.rs`; `env use` only imports
them.
- Still covered: `fish` is byte-identical to
`commands::shell::tests::test_detect_shell_vp_shell_fish`; `nu` to
`test_detect_shell_vp_shell_explicit`; lowercase `powershell` by
`test_shell_from_str` and `test_detect_shell_vp_shell_case_insensitive`;
`posix_default` by `test_detect_shell_defaults_without_vp_shell`.
- Best defenses M2–M5: each failed the nominee together with at least
one `commands::shell` test.
- The `use vp_shared::env_vars;` import is now `#[cfg(windows)]`, since
only the three Windows-only tests in the module still use it.
3. **`crates/vp_pm_cli/src/resolution/test_utils.rs` ›
`parses_args_without_a_program_name`,
`parses_subcommands_without_a_program_name`**
   - Class: test tooling testing test tooling.
- Best defense: M7 fails 122 tests and M8 fails 17; every resolution
parser test exercises these helpers.
4. **`crates/vp_pm_cli/src/resolution/commands/list.rs` ›
`list_args_helper_keeps_pattern`** (and its test-only `list_args`
helper, which had no other caller)
- Class: test tooling testing test tooling; it only checked struct
construction.
- Best defenses: M9 fails only
`test_list_with_pattern_and_pass_through_args`; M10 fails
`test_parser_accepts_short_dev_and_global_flags` and
`cli::tests::projects_managed_global_commands`. The nominee passes both.

### Folds (`crates/vp_global_cli/src/upgrade_check.rs`)

- The 9 `is_newer_version_*` tests → `is_newer_version_compares_semver`
(12 rows, original comments kept, one comment added for the `0.0.0`
dev-build row).
- The 11 `should_run_for_*` / `should_not_run_for_*` tests →
`should_run_for_command_skips_excluded_and_machine_readable_commands`
(11 rows).
- M11, M12 and M13 still fail the folded tables.

### Kept after defense — do not re-nominate

None: no nominee survived its defense.

### Case counts

| file | before | after | delta | expected delta |
|---|---|---|---|---|
| vp_global_cli `commands/create.rs` | 1 | 0 | −1 | −1 |
| vp_global_cli `commands/env/use.rs` (Linux) | 16 | 12 | −4 | −4 |
| vp_global_cli `upgrade_check.rs` | 36 | 18 | −18 | −18 (20 folded into
2) |
| vp_pm_cli `resolution/commands/list.rs` | 45 | 44 | −1 | −1 |
| vp_pm_cli `resolution/test_utils.rs` | 2 | 0 | −2 | −2 |
| **Crates total** | 1,425 | 1,399 | −26 | −26 |

**0 new failures** (0 failed and 4 ignored, before and after).

### Mutations

Each was temporary and reverted (`git status` clean afterwards).

1. M1 `create.rs:15`: delegate `"new"` instead of `"create"`. Failed:
none.
2. M2 `shell.rs:30`: `"fish"` → `"fishshell"`. Failed: `use::…_fish`,
`shell::test_shell_from_str`, `shell::…_fish`.
3. M3 `shell.rs:31`: `"nu" | "nushell"` → `"nushell"`. Failed:
`use::…_nu`, `shell::…_explicit`, `shell::test_shell_from_str`.
4. M4 `shell.rs:32`: drop `"powershell"`. Failed: `use::…_powershell`,
`shell::…_case_insensitive`, `shell::test_shell_from_str`.
5. M5 `shell.rs:54`: default always `Cmd`. Failed:
`use::…_posix_default`, `shell::…_defaults_without_vp_shell`,
`shell::…_invalid_vp_shell_falls_back_to_default`.
6. M6 `shell.rs:49`: upper-case the value. Failed: none (equivalent
mutation; `from_str` lowercases).
7. M7 `test_utils.rs:70`: `test_argv` no longer prepends a program name.
Failed: 122 tests, including both nominees.
8. M8 `test_utils.rs:57`: `parse_subcommand` gets raw args. Failed: 17
tests (`config`, `dist_tag`, `owner`, `stage`, `token`, plus the
nominee).
9. M9 `list.rs:78-80`: pnpm drops the pattern. Failed:
`test_list_with_pattern_and_pass_through_args` only.
10. M10 `list.rs:11`: `pattern` becomes `#[arg(long)]`. Failed:
`test_parser_accepts_short_dev_and_global_flags`,
`cli::tests::projects_managed_global_commands`.
11. M11 `upgrade_check.rs:170` (after the fold): `>` → `>=`. Failed:
`is_newer_version_compares_semver`.
12. M12 `upgrade_check.rs:338` (after the fold): `Upgrade` removed from
the excluded commands. Failed:
`should_run_for_command_skips_excluded_and_machine_readable_commands`.
13. M13 `upgrade_check.rs:165` (after the fold): the `0.0.0` early
return removed. Failed: `is_newer_version_compares_semver`.

### What ran and what did not

- Ran, at origin/main and on this branch: `cargo test -p vp_global_cli`
and `cargo test -p vp_pm_cli` with `--report-time`; `cargo clippy -p
vp_global_cli -p vp_pm_cli --all-targets --all-features -- --deny
warnings` with the `just lint` allow-list; `cargo fmt --all -- --check`;
`git diff --check`. All pass.
- Not run: the full workspace `just test` / `just lint` / `just check`;
Windows targets (none installed here, so the `#[cfg(windows)]` import
gate was reviewed but not compiled; Windows CI will compile it); the
JS/Vitest suite; the PTY snapshot suite.

### Excluded pull requests

55 open PRs touch 737 files between them; none of the 5 files here is
among them. #3055 #3052 #3051 #3049 #3047 #3046 #3044 #3040 #3038 #3037
#3020 #3018 #3014 #3012 #3009 #3008 #3000 #2986 #2981 #2966 #2936 #2922
#2900 #2863 #2862 #2810 #2792 #2740 #2721 #2699 #2695 #2574 #2557 #2552
#2549 #2543 #2542 #2541 #2483 #2475 #2463 #2462 #2461 #2456 #2428 #2418
#2357 #2267 #2125 #1958 #1783 #1782 #1614 #1517 #1180.

### Age check (cutoff: 30 days, 2026-09-14)

First-added dates from `git log -S`, followed across the `vite_*` →
`vp_*` crate rename.

| Test | First added |
|---|---|
| `test_create_command_module_exists` | 2026-02-10 (a29ac83, #570) |
| `test_detect_shell_posix_default` | 2026-02-07 (194c0dc, #524) |
| `test_detect_shell_vp_shell_{powershell,fish,nu}` | 2026-05-24
(53ae721, #1658) |
| `test_utils` tests and `list_args_helper_keeps_pattern` | 2026-08-03
(c1574dd, #2140) |
| The 20 folded `upgrade_check` tests | 2026-03-30 (db75675) |

None was added for a bug or incident, and none is in a permission,
security or entitlement suite.

### Checks

| Check | Before | After |
|---|---|---|
| Tests `vp_global_cli` | 502 pass | 479 pass |
| Tests `vp_pm_cli` | 923 pass | 920 pass |
| Clippy (deny warnings) | pass | pass |
| rustfmt | – | pass |
| `git diff --check` | – | clean |

To revert: `git revert 687935d`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01PxVsmvB9xfZKfVnUonY8kf

---
_Generated by [Claude
Code](https://claude.ai/code/session_01PxVsmvB9xfZKfVnUonY8kf)_

Co-authored-by: Claude <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

preview-build Publish this PR's commits to the registry bridge as preview builds

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants