Recommend and install/update the Azure Cosmos DB Shell

[Mike Krüger (mkrueger)]

Summary

Implements the PRD "Recommend Azure Cosmos DB Shell from the VS Code Extension." It adds:

1. A proactive, engagement-gated recommendation to install the Cosmos DB Shell that appears after a user actually works with Cosmos DB (opens a document / runs a query), and
2. An "Install or Update Azure Cosmos DB Shell" command surfaced both from the Command Palette and as a button in the cosmosDB.shell.path setting description.

Both paths reuse the existing dotnet tool install/launch pipeline rather than introducing a new multi-OS install matrix. The recommendation is opt-out via a new setting, is capped so it can't nag, and never emits PII/EUII.

---

Requirements met

Functional

Req	Description	Status
FR1	Trigger recommendation from real engagement (open document / run query), after N = 2 actions	✅ recordCosmosShellEngagementAndMaybeRecommend('openDocument' | 'runQuery')
FR2 / FR17	Never recommend if the Shell is already installed	✅ short-circuits on isCosmosDBShellInstalled()
FR3	At most once per session + lifetime impression cap = 2 (auto-suppress after)	✅ wasShownInSession + persisted impression count
FR4	"Later" defers for 7 days	✅ RECOMMENDATION_STATE_LATER_UNTIL cooldown
FR5 / FR6	Non-modal notification with 4 actions	✅ Install & Launch · Learn More · Later · Don't show again
FR7	All user-facing strings localizable	✅ l10n.t() / package.nls.json
FR8 / FR9	Install and launch via the existing pipeline	✅ Install & Launch runs COMMAND_LAUNCH_COSMOS_DB_SHELL
FR10	No secrets/PII in output or telemetry	✅ context.valuesToMask for endpoint, DB/container ids, credentials, tenant/MI ids, custom path
FR11	Handle missing .NET SDK gracefully	✅ error + "Download .NET SDK" action
FR12	Opt-out setting	✅ cosmosDB.shell.recommendation.enabled (default true)
FR13	State persists globally (per user, not per workspace)	✅ global state keys under ms-azuretools.vscode-cosmosdb.shellRecommendation
FR14	Centrally manageable / policy-style control	⚠️ Partial — setting uses "scope": "application" (globally managed via user settings). A true named extensionConfigurationPolicy lives in VS Code product.json and isn't available to a third-party extension.
FR18	Telemetry for shown / clicked / install outcomes	✅ recommendation.shown, recommendation.clicked, plus install/update tool + prompt events

Security / Privacy (SR1–SR5)

• No credentials, endpoints, resource names, paths, or queries written to the output channel or telemetry — sensitive launch context is pushed to context.valuesToMask (non-empty guards).
• Install/update runs the same trusted dotnet tool command already used by the extension; the resolved binary path is not echoed.

Accessibility (AX1–AX2)

• Uses standard VS Code notification / message APIs, so screen-reader announcement and keyboard interaction are handled by the platform.

---

How install / update works now (user scenarios)

Scenario A — Shell not installed, user is exploring Cosmos DB

1. User opens a document or runs a query in a Cosmos DB context.
2. After 2 such actions in a session, a non-modal recommendation appears (only if the Shell isn't installed, the setting is enabled, and it isn't suppressed / in cooldown).
3. Install & Launch → runs the existing dotnet tool install --global CosmosDBShell --prerelease pipeline (with .NET SDK-missing fallback prompts), then launches the Shell.
4. Learn More opens the Shell docs/package page. Later hides it for 7 days. Don't show again suppresses it permanently. Dismissing (X) just ends the session impression without changing state.
5. After the lifetime cap (2 impressions) is reached, it auto-suppresses.

Scenario B — Explicit "Install or Update Azure Cosmos DB Shell" (Command Palette, or the button in the cosmosDB.shell.path setting)

• Not installed → installs via the shared pipeline.
• Already installed → runs dotnet tool update --global CosmosDBShell --prerelease and refreshes install detection.
• Custom cosmosDB.shell.path configured → informs the user that automatic updates are unavailable for a custom path and offers a Settings shortcut (it won't touch the user-managed binary).
• .NET SDK missing → error with a "Download .NET SDK" action.
• After install/update, refreshCosmosDBShellSupport() invalidates the support cache and updates the vscodeDatabases.cosmosDBShellSupportEnabled context so the UI reflects the new state immediately.

Scenario C — Launch Shell command

• Still installs-if-missing only; updates are intentionally routed through the settings button / explicit command so launching stays fast.

---

Tests

• 7 new unit tests in src/cosmosDBShell/recommendation/shellRecommendation.test.ts covering the engagement threshold, installed/disabled gating, suppression + cooldown, lifetime-cap auto-suppress, concurrent de-dup, Later cooldown + impression reset, and dismissal.
• npm run build, npm run lint, npm run prettier-fix, and npm run l10n all pass.

Open item

• The Learn More URL currently points at the CosmosDBShell package page; swap it for the canonical docs page if/when one exists.

[Copilot]

Pull request overview

Adds a proactive, engagement-gated recommendation to install Azure Cosmos DB Shell and introduces an explicit “Install or Update Azure Cosmos DB Shell” command (plus a settings link), while reusing the existing dotnet tool pipeline and strengthening masking to avoid leaking sensitive launch context.

Changes:

• Records Cosmos DB “engagement” (open document / run query) and conditionally shows a non-modal, rate-limited Shell recommendation with telemetry.
• Adds an explicit install-or-update entry point that updates via dotnet tool update when the Shell is already installed and no custom Shell path is configured.
• Improves privacy hygiene by reducing sensitive output and expanding valuesToMask for Shell launch/connect flows.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/panels/trpc/routers/queryEditorRouter.ts	Records “runQuery” engagement to gate the proactive Shell recommendation.
src/cosmosDBShell/recommendation/shellRecommendation.ts	Implements the recommendation gating/state machine + shown/clicked telemetry.
src/cosmosDBShell/recommendation/shellRecommendation.test.ts	Adds unit tests covering gating, suppression/cooldown, de-dupe, and telemetry behavior.
src/cosmosDBShell/install/installPrompts.ts	Extends install pipeline to support update flow and adds an explicit install/update entry point.
src/cosmosDBShell/CosmosDBShellExtension.ts	Registers the new command and expands masking while reducing sensitive output logging.
src/cosmosDBShell/constants.ts	Adds command/setting IDs and persisted globalState keys for recommendation state.
src/commands/openDocument/openDocument.ts	Records “openDocument” engagement to gate the proactive Shell recommendation.
package.nls.json	Adds localized command title, settings markdown link, and new recommendation setting description.
package.json	Contributes the new command and adds the new setting; switches Shell path to markdownDescription.
l10n/bundle.l10n.json	Updates extracted localization strings for new prompts/actions.