Add context-aware shell completion and inline suggestions

[tnaum-ms]

This pull request introduces advanced shell completion and inline suggestion ("ghost text") features to the DocumentDBShellPty class, greatly enhancing the interactive shell experience. It adds a tab-completion system, inline ghost text suggestions, and manages their rendering and acceptance, as well as related state and cleanup logic.

Shell Completion and Ghost Text Features:

• Added a ShellCompletionProvider and ShellGhostText to the shell PTY, supporting tab completion and inline ghost text suggestions. These are initialized in the constructor and managed as part of the shell session state. [1] [2]
• Implemented tab completion logic: pressing Tab invokes completion, inserts the common prefix or displays a completion list, and allows accepting ghost text with Tab or Right Arrow.
• Added ghost text evaluation: after buffer changes, the shell evaluates if an inline suggestion is appropriate, debounced for performance, and displays it if there's a single clear completion or matches smart patterns (e.g., suggesting find() after db.<collection>.).
• Provided logic to accept ghost text, inserting the suggestion into the buffer and clearing the inline display.
• Introduced a set of known database methods to avoid inappropriate ghost text suggestions.

Terminal State and Cleanup Improvements:

• Tracked terminal width for improved completion list rendering, and handled cleanup of timers and ghost text state on shell close and prompt reset. [1] [2] [3]
• Managed visibility state for completion lists and ghost text to ensure correct UI updates on user input and buffer changes.

These enhancements make the shell more user-friendly and efficient by providing context-aware completions and suggestions as users type.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR adds a self-contained tab-completion system and inline “ghost text” suggestions to the DocumentDB interactive shell PTY, providing a richer terminal editing experience without relying on VS Code’s proposed TerminalCompletionProvider API.

Changes:

• Added a completion provider + renderer to produce context-aware candidates and display multi-column completion lists in the terminal.
• Added ghost text lifecycle management and wired it into the PTY via new ShellInputHandler callbacks.
• Expanded unit tests and documentation to cover the new completion and ghost text behaviors.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/documentdb/shell/ShellInputHandler.ts	Adds Tab handling, buffer-change callbacks, cursor getter, and text insertion API for completions/ghost text.
src/documentdb/shell/ShellInputHandler.test.ts	Adds tests for Tab callback, cursor tracking, insertText, buffer-change callbacks, and ghost acceptance hook.
src/documentdb/shell/ShellGhostText.ts	New module to render/clear/reset inline ANSI ghost text suggestions.
src/documentdb/shell/ShellGhostText.test.ts	Unit tests for ghost text rendering lifecycle and ANSI output.
src/documentdb/shell/ShellCompletionRenderer.ts	New module to render completion lists and compute common prefixes.
src/documentdb/shell/ShellCompletionRenderer.test.ts	Unit tests for completion list layout/colors/truncation and common prefix behavior.
src/documentdb/shell/ShellCompletionProvider.ts	New context detector and candidate generator using caches/schema/operators/method metadata.
src/documentdb/shell/ShellCompletionProvider.test.ts	Unit tests covering context detection and candidate generation/filtering.
src/documentdb/shell/DocumentDBShellPty.ts	Wires Tab completion + ghost text into the PTY, adds dimension tracking, debounce timer, and cleanup.
docs/ai-and-plans/shell-autocompletion/9-shell-autocompletion.md	Adds architecture/design documentation for completion + ghost text.
docs/ai-and-plans/future-work/terminal-enhancements.md	Updates future-work doc to mark fallback completion as implemented and link to docs/issue.

[tnaum-ms]

Review issue #6 — insertText() doesn't fire onBufferChange (S4 — Low)

Issue: insertText() modifies _buffer and _cursor but doesn't call onBufferChange, creating an asymmetry with other buffer-mutating methods.

Action: Documented the contract in the JSDoc: insertText is intentionally a PTY-controlled mutation — the PTY handles follow-up evaluations (ghost text, etc.) after calling it. This prevents future code from incorrectly relying on onBufferChange for PTY-driven insertions.

Commit: 1dd1e0e

[tnaum-ms]

Review issue #8 — No rate limiting on background cache fetch triggers (S4 — Low)

Issue: getDatabaseCandidates and getDbDotCandidates fire background listDatabases()/listCollections() on every Tab press when the cache is empty. ClustersClient does not deduplicate concurrent requests, so rapid Tab pressing causes multiple identical network requests.

Action: Added a _backgroundFetchTriggered set that tracks in-flight fetches by resource key. Duplicate fetch requests for the same resource are suppressed while one is already in progress. The key is cleaned up in .finally() so the guard resets after the fetch completes (success or failure).

Commit: e8cce7b

[tnaum-ms]

Review issue #9 — DATABASE_METHODS hardcoded, not derived from types (S4 — Low)

Issue: DATABASE_METHODS was a hardcoded 14-entry Set. If a new database method is added to documentdb-shell-api-types, the completion provider would treat db.newMethod as a collection name.

Action: Replaced the hardcoded set with new Set(getMethodsByTarget('database').map((m) => m.name)), which is already imported and used elsewhere in the same file. The set now stays in sync automatically.

Commit: bd19c36