feat(project): block add/remove command usage for v0 project on v1 CLI

[nborges-aws]

Description

Block agentcore add and agentcore remove at command line and TUI level when the current project is a v0 agentcore.json (version: 1). The middleware runs before project parsing and before the TUI launches.

This PR also extracts the project version check added in PR #2566 to our fsUtil shared helper, and is now reused in both places.

Screen.Recording.2026-10-12.at.3.43.50.PM.mov

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Other (please describe):

Testing

How have you tested the change?

• bun run test (x pass, 0 fail)
• I ran npm run test:unit and npm run test:integ
• I ran npm run typecheck
• I ran npm run lint
• If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the
terms of your choice.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Clean, well-scoped change. The extracted isV0Project helper is reused in both v0DependencyWarning and the new guard, the guard runs before withProject so the v1-schema parsing error can't leak out for add/remove, and the tests use real temp directories rather than fs mocks.

A couple of non-blocking observations the author may want to consider as follow-ups:

• New error short-circuits the stale-CDK guidance. The test uses the add/remove error even when the old CDK dependency warning applies confirms this is intentional, but V0_PROJECT_ADD_REMOVE_MESSAGE tells the user to migrate, and agentcore migrate currently throws NotImplementedError(MIGRATE_NOT_AVAILABLE_MESSAGE). A user on a v0 project with stale CDK deps who used to be pointed at npx @aws/agentcore@0 deploy now has no actionable path until migrate ships. Worth confirming this is the UX you want for the rc.
• cwd handling is slightly inconsistent with withProject. withProject accepts an optional cwd, while withV0ProjectGuard reads process.cwd() directly. In production wiring both resolve to the same directory, so this doesn't cause a bug today, but if a future caller passes a non-default cwd to withProject the two will disagree. Taking an optional cwd here would keep them in lockstep.

Neither needs to block the merge.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.54%. Comparing base (5d81751) to head (f28ebd0).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2581      +/-   ##
============================================
- Coverage     97.54%   97.54%   -0.01%     
============================================
  Files           657      658       +1     
  Lines         48779    48806      +27     
============================================
+ Hits          47580    47606      +26     
- Misses         1199     1200       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.