Add project-scoped package managers

[Eduardo Villalpando Mello (edvilme)]

Fixes #1779

Summary

Adds project-scoped package manager instances for package managers whose behavior depends on the active Python project. Instead of threading project context through every package operation, a provider can implement PackageManager.createForProject(project) and return a manager bound to that project.

Changes

• Add the optional PackageManager.createForProject(project) API.
• Cache project-bound manager instances by provider and normalized project path while keeping project-independent managers shared.
• Preserve the registered provider ID for scoped managers and allow scoped managers to create package items.
• Forward package-change events from root and scoped managers through the internal and public APIs.
• Keep package watchers distinct by provider, environment, and project.
• Retain the scoped manager for package actions initiated from the project view.
• Bind Poetry package operations to an immutable PythonProject:
  • add, remove, show, and show --top-level run from the project directory.
  • manage and refresh reject when Poetry is not project-bound.
  • getPackages and getDirectPackageNames return undefined when Poetry is not project-bound.
  • Project-independent operations such as getVersion and formatInstallSpec remain available.
• Update the API package metadata, changelog, and documentation.

Validation

• npm run lint
• npm run compile-tests
• npm run unittest — 2,425 passing, 6 pending

[Rich Chiodo (rchiodo)]

🔒 Automated review in progress — Rich Chiodo (@rchiodo) is auto-reviewing this PR.

[Rich Chiodo (rchiodo)]

GitHub cannot anchor PR review comments to unchanged lines in the diff. Falling back to a general PR comment for src/managers/poetry/poetryPackageManager.ts:L184.

Warning · Non-blocking recommendation

📍 src/managers/poetry/poetryPackageManager.ts:174
getPackages fetches project-specific data but caches it solely by environment ID, so a subsequent request for another project sharing that environment can receive the first project's result. Include the normalized project directory in the cache key, or bypass the environment-only cache when explicit context is supplied.

[unverified]

[Copilot]

Copilot review overview

🟡 Changes recommended

Unscoped terminal watchers fail for Poetry, project-scoped managers are not evicted, and one unbound management path does not reject as documented.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 3

Open (3)

• Evict scoped managers when projects are removed · New
• Preserve project scope for terminal package watchers · New
• Validate project binding before manage exits or prompts · New

Resolved since last review (2)

• Key package cache by project context
• Use project-scoped manager when handling project packages

Files not reviewed (1)

• api/package-lock.json: Generated file

[Copilot]

Copilot review overview

🟡 Changes recommended

Unbound environment-view operations now fail for Poetry, and symlinked project directories resolve to the wrong working directory.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Rejecting unbound managers breaks environment-scoped UI callers · New
• Symlinked directories are misclassified due to exact FileType comparison · New

Resolved since last review (2)

• Reject unresolved directory URIs instead of using their parent project
• Invalidate package watchers when their scoped manager is replaced

Files not reviewed (1)

• api/package-lock.json: Generated file

[Rich Chiodo (rchiodo)]

Result: ⚠️ needs-more-tests

Verification details

Verification: Isolated verification observed failures that were not classified as caused by this PR: Dependency and test discovery.

Summary: Dependencies installed offline and TypeScript test compilation passed. Three targeted Mocha runs covering 106 tests all passed, including project scoping, event forwarding, watchers, Poetry working directories, and unbound-manager behavior. The discovery command's Git probe failed because the sandbox lacked Git metadata, unrelated to the PR. Coverage is still missing for the newly changed `managePackageVersion` scoped-manager error path.

Test runs: 5 passed, 1 failed

• ❌ Failed | unrelated to this PR | Dependency and test discovery | printf 'PROFILE=%s\n' "$AUTOMATION_SANDBOX_PROFILE"; test -d node_modules && echo 'node_modules=present' || echo 'node_modules=missing'; node -p "JSON.stringify(require('./package.json').scripts, null, 2)"; git diff --name-only HEAD^..HEAD
• ✅ Passed | Project-scoped package manager API and command tests | node ./node_modules/mocha/bin/mocha.js --no-config --require source-map-support/register --require out/test/unittests.js --ui tdd --timeout 180000 out/test/features/packageManager.api.unit.test.js out/test/features/envManagers.packageEvents.unit.test.js out/test/features/envCommands.unit.test.js out/test/extensionApi.unit.test.js
• ✅ Passed | Package watcher unit tests | node ./node_modules/mocha/bin/mocha.js --no-config --require source-map-support/register --require out/test/unittests.js --ui tdd --timeout 180000 out/test/managers/common/packageWatcher.unit.test.js
• ✅ Passed | Poetry package manager and headless conformance tests | node ./node_modules/mocha/bin/mocha.js --no-config --require source-map-support/register --require out/test/unittests.js --ui tdd --timeout 180000 out/test/managers/poetry/poetryPackageManager.unit.test.js out/test/managers/common/packageManagerHeadlessConformance.unit.test.js
• ✅ Passed | Offline dependency bootstrap | npm ci --offline
• ✅ Passed | Compile tests | npm run compile-tests

❌ Dependency and test discovery diagnostic output

PROFILE=typescript
node_modules=missing
Scripts included compile-tests and unittest.
warning: Not a git repository. Use --no-index to compare two paths outside a working tree

[Rich Chiodo (rchiodo)]

Result: ⚠️ needs-more-tests

Verification details

Verification: Isolated verification observed failures that were not classified as caused by this PR: Sandbox and test discovery probe.

Summary: Offline dependency setup and TypeScript test compilation succeeded. The targeted package-manager, event-forwarding, watcher, command, Poetry, and conformance tests passed, with the explicit targeted run reporting **107 passing**. The discovery probe only failed because the checkout lacked `HEAD^`, which is unrelated to the PR. Coverage is strong, but the new `managePackageVersion` project-required error path lacks a focused test.

Test runs: 5 passed, 1 failed

• ❌ Failed | unrelated to this PR | Sandbox and test discovery probe | printf '%s\n' "AUTOMATION_SANDBOX_PROFILE=${AUTOMATION_SANDBOX_PROFILE:-}"; node -e "const p=require('./package.json'); console.log(JSON.stringify({scripts:p.scripts},null,2))"; printf '\nnode_modules: '; test -d node_modules && echo present || echo missing; printf 'changed files:\n'; git diff --name-status HEAD^ HEAD
• ✅ Passed | TypeScript test compilation | npm run compile-tests
• ✅ Passed | Package manager API and package event tests | node ./node_modules/mocha/bin/mocha.js --config ./build/.mocha.unittests.json out/test/features/packageManager.api.unit.test.js out/test/features/envManagers.packageEvents.unit.test.js
• ✅ Passed | Package watcher and environment command tests | node ./node_modules/mocha/bin/mocha.js --config ./build/.mocha.unittests.json out/test/managers/common/packageWatcher.unit.test.js out/test/features/envCommands.unit.test.js
• ✅ Passed | Explicit targeted project-scoped package-manager unit tests | node ./node_modules/mocha/bin/mocha.js --no-config --require source-map-support/register --require ./out/test/unittests.js --ui tdd --timeout 180000 --reporter dot out/test/features/packageManager.api.unit.test.js out/test/features/envManagers.packageEvents.unit.test.js out/test/managers/common/packageWatcher.unit.test.js out/test/features/envCommands.unit.test.js out/test/managers/poetry/poetryPackageManager.unit.test.js out/test/managers/common/packageManagerHeadlessConformance.unit.test.js
• ✅ Passed | Offline dependency bootstrap | npm ci --offline

❌ Sandbox and test discovery probe diagnostic output

AUTOMATION_SANDBOX_PROFILE=typescript
node_modules: missing
changed files:
error: Could not access 'HEAD^'

[Rich Chiodo (rchiodo)]

Issue · Please address or respond

When zero or multiple projects match a project-aware manager, this reduces projectRequired to undefined and silently skips refresh. Switch on resolution.kind and surface PackageManagerRequiresProjectError, consistent with the public API and package-management command paths.

[unverified]