DocumentDB Local with Quick Start helpers

[Tomasz Naumowicz (tnaum-ms)]

Summary

• Add a guided DocumentDB Local Quick Start flow that goes from a Docker-ready machine to an open local connection without leaving VS Code.
• Add managed instance lifecycle actions and status in the Connections view, including start, stop, restart, delete, recovery, and existing-instance safeguards.
• Add the Quick Start webview and extension-host services for provisioning, readiness checks, durable state, credential handling, telemetry, and actionable errors.
• Preserve manually added localhost connections alongside regular connections and detect DocumentDB Local instances added by hand.

Release integration

• Targets release/0.10.0.
• Merged the latest release/0.10.0 changes in commit 03125338.
• Resolved the router conflict by retaining the Quick Start router while adopting the relocated Collection Index router and the release branch toast-procedure split.

Validation

• npm run l10n
• npm run prettier-fix
• npm run lint
• Jest: 3,396 tests passed
• npm run build

[Tomasz Naumowicz (tnaum-ms)]

Iteration 2 of the code review — 9 items shipped, 1 deferred

Worklist: docs/ai-and-plans/PRs/798-local-quickstart/code-review-2026-08-04.md §11.4. One dedicated commit per item; each item's full write-up lives in that chapter next to the decision it implements.

#	Commit	Outcome
I2-1	ec0a77cb	✅ H5 regression test
I2-2	f473b02c	✅ Recreate-vs-fresh choice + explicit startFresh flag
I2-3	5e2c9314	✅ Existing-instance guard — on the Configure step
I2-4	a684ce95	✅ Actionable error nodes (closes N3)
I2-5	1a0f3ab9	✅ Tree renders from cache instead of blocking on Docker
I2-6	bef2128f	✅ suggestPort() skipped on polled readiness calls
I2-7	7ae61fd8	✅ Single-instance intent recorded at the multi-instance seams
I2-8	—	⏸ Deferred to Iteration 3 — see the bottom of this comment
I2-9	—	✅ Verified — L2 closed, no code needed
I2-10	81f062f8	✅ Password stripped from the tree model — answered in-thread
I2-17	bca46b67	✅ Cached tree error state cleared when the failure is fixed elsewhere

---

I2-2 — f473b02c Ask before recreating, and take the answer as an explicit flag (M4)

When stored credentials existed, the Configure step relabelled its settings — but the primary button still read Start DocumentDB Local, the footer still said "Nothing else on your machine is changed", and provision() force-removed the running container first. Opening Quick Start out of curiosity destroyed a running instance while the copy said the opposite.

Configure now asks, above the settings table:

• Use existing data — recreate the container and keep your documents
• Start fresh — erases all data in DocumentDB Local (never pre-selected)

The answer travels as AdvancedQuickStartOptions.startFresh instead of being inferred from getReusableCredentials(), and the primary label plus the footer note follow the selection. Per the agreed Q4 answer there is no extra confirmation dialog — the destructive option states the data loss in its own label, and a modal on top would prompt twice for a decision just made deliberately.

The RR4 / §5.2 volume-wipe gate is preserved: "Start fresh" is now the only path that may drop a volume, and it is an explicit user choice. This also resolves N1 by construction — there is no inferred value left to go stale.

willReuse / willReuseExistingInstance() are renamed to canReuseExistingData: the flag now names a capability rather than an outcome the service decides.

I2-3 — 5e2c9314 Guard the wizard when an instance already exists

Reaching the wizard while an instance exists should not normally be possible — the tree does not link to it in that state — but the command palette, a stale panel and cross-window races all still get there, and a healthy running instance could be walked straight into a destructive recreate.

Placement changed from the plan: the guard is on the Configure step, not Introduction. That is where the destructive decision is actually made and where the guard sits next to the "Start fresh" radio it forces; on Introduction it would be a speed bump the user clicks past before reaching the choice it guards.

Variant	MessageBar	Primary
Healthy (Running)	info	disabled — offers Open Connection / Close
Stopped	info	disabled — offers Start / Close
CredentialsMissing	warning	enabled, forced onto Start fresh

Missing is deliberately not guarded — recreating is exactly what that state asks for. The service's old hard refusal for the credential-unavailable case (which left the user hunting for a separate Delete Container) becomes an explicit, warned Start-fresh path inside the wizard.

I2-4 — a684ce95 Actionable error nodes (§9.2 Q4, N3)

Two dead ends removed. The state_error row showed status.errorMessage as its description with no command, and the NotInstalled branch pushed a second, message-only ${id}/error child (N3).

The tree now renders recovery actions, not error text: createRetryNode — pointed at the wizard, because for a provisioning failure that is the operation being retried — plus View setup log and, once a container exists, Delete Container. The message-only child is gone.

LocalQuickStartItem now implements TreeElementWithRetryChildren, which is what makes BaseExtendedTreeDataProvider cache the failed children. That is the mechanism behind the passive-vs-real retry distinction: a parent/whole-view refresh reuses the cached error children and never re-runs the failing operation (so no second modal), while clicking retry resets the cache and genuinely retries. Per the Q5 answer, no detectErrorState hook was added — Missing and CredentialsMissing are service states with their own actionable rows, not fetch failures.

I2-5 — 1a0f3ab9 Render the tree row from cache instead of blocking on Docker (M6)

getChildren() awaited refreshLiveState(), so every Connections-view refresh — connection add/remove/rename, folder ops, discovery refresh, ext.state transitions — paid a process spawn plus a Docker round-trip, for every user who has ever provisioned an instance.

The row now renders immediately from the last known state and the probe runs in the background via refreshLiveStateInBackground(). Rows a probe can actually change (Running / Stopped / Missing) show a Refreshing… hint while one is in flight, and onDidChangeStatus redraws them.

One thing worth a reviewer's eye: clearing that hint requires firing the status event even when nothing changed, and that event re-enters getChildren(). The 5 s BACKGROUND_REFRESH_COOLDOWN_MS is therefore load-bearing, not an optimisation — it is what stops the completion event arming the next probe and rebuilding H1 in a new shape. A regression test asserts one docker inspect for a burst of four calls.

I2-6 — bef2128f Skip suggestPort() on polled readiness calls (M6-b)

getDockerStatus ran suggestPort() on every call, including the readiness poll that re-runs on a 1–5 s backoff for up to 90 s; suggestPort() binds a probe socket per candidate and walks up to QUICK_START_PORT_SCAN_LIMIT ports. DockerStatusResult.suggestedPort is now optional and omitted when input.polled is set; the webview keeps its previous suggestion, so the Configure field is never blanked by a poll.

I2-7 — 7ae61fd8 Record the single-instance scope in code

The service layer is already multi-instance-shaped while the tree and webview assume exactly one instance, and a reader could not tell whether those seams were load-bearing or aspirational. Notes added at the instances map, reservedPorts(), listStatuses() and the operationId nonce — the last flagged as load-bearing today for concurrent windows (H3/H4), which was precisely the distinction that was unclear. Documentation-in-code only.

I2-1 — ec0a77cb Pin the H5 contract

The suite stayed green through H5 because IContainerRuntime, ext.secretStorage and the tree provider are all mocked. The new tests pin the contract that closed it: with an empty CredentialCache — the post-reload state that made H5 reproducible — the node still lists databases, QuickStartService is what supplies them, and the cache ends up populated as a side effect rather than a precondition. Also covers the no-stored-secret path (no client, error-recovery children, no throw out of getChildren()).

I2-17 — bca46b67 Clear the cached tree error state when the failure is fixed elsewhere

failedChildrenCache freezes a node's children once classified as failed. If the user then fixed the problem outside the tree — typically in the Quick Start webview — the row kept rendering the stale error node until a manual collapse/expand. onDidChangeStatus now resets the Quick Start subtree's error state before refreshing, mirroring the AtlasDiscoveryProvider.onDidChangeSession precedent.

I2-9 — L2 closed by verification

suggestPort() returns the instance's own recorded port when it is still free (already covered by "prefers the instance own recorded port so a recreate keeps its address"), and the Configure Address row renders it while portTouchedRef stops a suggestion from clobbering a typed value. No code needed.

I2-10 — 81f062f8 — answered in the review thread

Answered where it was raised: #discussion_r3714252974.

---

Not shipped: I2-8 (credential store consolidation) → Iteration 3

Approved, then deferred on two gates confirmed while scoping it:

1. TDD: contract tests. QuickStartProvisionDurability.test.ts asserts the persistence contract against the raw keys — secretKey(DEFAULT_ALIAS) written before the readiness probe and cleared on a failed attempt, readRegistry(globalState) showing provisioning → ready → missing. This item relocates exactly those keys. .github/copilot-instructions.md requires a maintainer decision before touching a TDD: suite.
2. Data safety. The migration must carry the secrets and the registry including the live lease fields (operationId, leaseAt), and must complete before reconcile() — the R1 ordering migrateLegacyQuickStartKeys already relies on. A mistake there is a silent volume wipe.

It is hygiene, not a fix — H5 was closed without it — and nothing else depends on it. Tracked as I3-1, blocked on I3-Q1 in §11.5.

---

Verification: npm run l10n → npm run prettier-fix → npm run lint (clean) → npx jest --no-coverage (204 suites / 3355 tests, all passing; +1 suite and +9 tests from this iteration) → npm run build (clean).

[Tomasz Naumowicz (tnaum-ms)]

Iteration 3 — b8e25fc3 Quick Start durable state moves to StorageService (I3-1)

The last outstanding review item. The managed instance's state was split across three ad-hoc stores — the connection string in a raw SecretStorage key, the image ref in globalState, and the instance list in a hand-rolled documentdb.quickstart.registry blob with its own write lock — which is why provision() had to hand-roll a two-phase commit across them (write the secret early, remember the previous value, restore it in finally).

It now lives in StorageService.get('local-quickstart'), workspace instances, one item per alias: the record in properties, the connection string in secrets. A state change is a single push(). Same idiom as the service-kubernetes sourceStore and the service-atlas-mongodb credential store, so the codebase has one storage pattern instead of a per-feature one.

Net −500 lines. quickStartRegistry.ts, migrateLegacyQuickStartKeys, secretKey(), imageRefKey(), the LEGACY_* constants and the pre-reconcile() migration step in ClustersExtension are all deleted.

Two things worth flagging

1. The blocker I recorded for this item did not exist. I deferred it out of Iteration 2 partly because a scoping summary said QuickStartProvisionDurability.test.ts contained a TDD:-prefixed contract suite, which repo policy says must not be rewritten without a maintainer decision. It does not — grep -rl "TDD:" src/ returns only query-language and playground files, none under src/services/localQuickStart/. The affected tests are ordinary it(...) cases. My mistake was recording a blocker from a summary of the tree rather than from the tree; the permission was granted anyway, so it cost only the deferral.

2. StorageService.push() never clears a secret. It writes the secret key when item.secrets is non-empty and simply doesn't touch it otherwise — so clearing credentials by pushing an item without them leaves the old secret readable. That silently breaks the H3 restore contract: a discarded provision would leave its credentials behind, and the next run would decide reusing from credentials no volume was ever initialized with. updateInstance now deletes the item before re-pushing when the credentials are being cleared (safe inside the lock; a crash between the two leaves no record, which is the harmless direction).

This is a property of the shared storage service, not of Quick Start — worth knowing for anything else built on it.

The existing coverage could not have caught it: "restores the previous credential state when the attempt fails" fails at docker run, i.e. before the early credential write, so the restore never ran. Two new cases cancel during the readiness wait — the path a user actually takes — and assert both that a fresh attempt's credentials are cleared and that a failed recreate puts the previous ones back.

No migration

Per the maintainer's call — the feature has not shipped, so there is nothing to migrate from. That is what took the risk out of this item: the danger was never the destination, it was a migration that had to carry live lease fields (operationId, leaseAt) ahead of reconcile(), where a mistake is a silent volume wipe. There is no such migration now.

Also dropped: the registry's nextSuffix counter, which had no production reader (multi-instance is out of scope) and has no home in a per-item store.

Coverage

New quickStartStore.test.ts — record/credential round-trip, credentials preserved when only the record is rewritten, create-on-first-write, the clear path, and the in-lock conditional delete the lease release depends on.

---

Verification: npm run prettier-fix → npm run lint (clean) → npx jest --no-coverage (204 suites / 3344 tests, all passing) → npm run build (clean).

All three review iterations are now closed — every finding routed through §11 of the review doc is resolved. What remains is the deferred pool (B1 footer experiment, N4, N7, multi-instance, issues #864/#865), none of it blocking and none of it release work.

[github-actions]

✅ Code Quality Checks

Check	Status	How to fix
Localization (l10n)	✅ Passed
ESLint	✅ Passed
Prettier formatting	✅ Passed

This comment is updated automatically on each push.

[github-actions]

📦 Build Size Report

Metric	Base (release/0.10.0)	PR	Delta
VSIX (vscode-documentdb-0.10.0-bug-bash-1.vsix)	8.01 MB	8.14 MB	⬆️ +135 KB (+1.7%)
Webview bundle (views.js)	5.88 MB	6.11 MB	⬆️ +231 KB (+3.8%)

Download artifact · updated automatically on each push.