[WIP] feature: shell integration 💻

.azure-pipelines/compliance/CredScanSuppressions.json

@@ -6,11 +6,7 @@
       "_justification": "No need to scan external node modules."
     },
     {
-      "file": "test\\mongoGetCommand.test.ts",
-      "_justification": "Fake credentials used for unit tests."
-    },
-    {
-      "file": "src\\documentdb\\scrapbook\\mongoConnectionStrings.test.ts",
+      "file": "src\\documentdb\\mongoConnectionStrings.test.ts",
       "_justification": "Fake credentials used for unit tests."
     },
     {

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 # GitHub Copilot Instructions for vscode-documentdb
 
-VS Code Extension for Azure Cosmos DB and MongoDB. TypeScript (strict mode), React webviews, Jest testing.
+VS Code Extension for Azure Cosmos DB and the MongoDB API. TypeScript (strict mode), React webviews, Jest testing.
 
 ## Critical Build Commands
 
@@ -32,6 +32,12 @@ Before finishing work on a PR, agents **must** run the following steps in order:
 
 > ⚠️ **An agent must not finish or terminate until all three steps above have been run and pass successfully.** Skipping these steps leads to CI failures.
 
+## Git Safety
+
+- **Never use `git add -f`** to force-add files. If `git add` refuses a file, it is likely in `.gitignore` for a reason (e.g., `docs/plan/`, `docs/analysis/`, build outputs). Do NOT override this with `-f`.
+- When `git add` warns that a path is ignored, **stop and inform the user** instead of force-adding.
+- Files in `docs/plan/` and `docs/analysis/` are **local planning documents** that must not be committed to the repository.
+
 ## Project Structure
 
 | Folder          | Purpose                                    |
@@ -178,6 +184,32 @@ For Discovery View, both `treeId` and `clusterId` are sanitized (all `/` replace
 
 See `src/tree/models/BaseClusterModel.ts` and `docs/analysis/08-cluster-model-simplification-plan.md` for details.
 
+## Terminology
+
+This is a **DocumentDB** extension that uses the **MongoDB-compatible wire protocol**.
+
+- Use **"DocumentDB"** when referring to the database service itself.
+- Use **"MongoDB API"** or **"DocumentDB API"** when referring to the wire protocol, query language, or API compatibility layer.
+- **Never use "MongoDB" alone** as a product name in code, comments, docs, or user-facing strings.
+
+| ✅ Do                                                | ❌ Don't                         |
+| ---------------------------------------------------- | -------------------------------- |
+| `// Query operators supported by the DocumentDB API` | `// MongoDB query operators`     |
+| `// BSON types per the MongoDB API spec`             | `// Uses MongoDB's $match stage` |
+| `documentdbQuery` (variable name)                    | `mongoQuery`                     |
+
+This applies to: code comments, JSDoc/TSDoc, naming (prefer `documentdb` prefix), user-facing strings, docs, and test descriptions.
+
+## TDD Contract Tests
+
+Test suites prefixed with `TDD:` (e.g., `describe('TDD: Completion Behavior', ...)`) are **behavior contracts** written before the implementation. If a `TDD:` test fails after a code change:
+
+1. **Do NOT automatically fix the test.**
+2. **Stop and ask the user** whether the behavior change is intentional.
+3. The user decides: update the contract (test) or fix the implementation.
+
+This applies to any test whose name starts with `TDD:`, regardless of folder location.
+
 ## Additional Patterns
 
 For detailed patterns, see:

.github/workflows/main.yml

@@ -55,6 +55,9 @@ jobs:
             - name: 📦 Install Dependencies (npm ci)
               run: npm ci --prefer-offline --no-audit --no-fund --progress=false --verbose
 
+            - name: 🔨 Build Workspace Packages
+              run: npm run build --workspaces --if-present
+
             - name: 🌐 Check Localization Files
               run: npm run l10n:check
 

.gitignore

@@ -1,6 +1,9 @@
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.
 
+/docs/analysis/
+/docs/plan/
+
 # User-specific files
 *.suo
 *.user
@@ -157,6 +160,9 @@ PublishScripts/
 **/packages/*
 # except build/, which is used as an MSBuild target.
 !**/packages/build/
+# Include our monorepo packages at the root
+!/packages/
+!/packages/**
 # Uncomment if necessary however generally it will be regenerated when needed
 #!**/packages/repositories.config
 # NuGet v3's project.json files produces more ignoreable files
@@ -268,6 +274,7 @@ dist
 stats.json
 *.tgz
 *.zip
+*.tsbuildinfo
 
 # Scrapbooks
 *.mongo

.vscode/settings.json

@@ -1,33 +1,35 @@
 {
-    "editor.codeActionsOnSave": {
-        "source.fixAll.eslint": "explicit",
-        "source.organizeImports": "explicit"
-    },
-    "editor.detectIndentation": false,
-    "editor.formatOnSave": true,
-    "editor.formatOnPaste": false,
-    "editor.insertSpaces": true,
-    "editor.tabSize": 4,
-    "editor.defaultFormatter": "esbenp.prettier-vscode",
-    "files.insertFinalNewline": true,
-    "files.trimTrailingWhitespace": true,
-    "search.exclude": {
-        "out": true,
-        "**/node_modules": true,
-        ".vscode-test": true
-    },
-    "typescript.preferences.importModuleSpecifier": "relative",
-    "typescript.tsdk": "node_modules/typescript/lib",
-    "antlr4.generation": {
-        // Settings for "ANTLR4 grammar syntax support" extension
-        "mode": "internal",
-        "listeners": true,
-        "visitors": false
-    },
-    "vscode-nmake-tools.workspaceBuildDirectories": ["."],
-    "vscode-nmake-tools.installOsRepoRustHelperExtension": false,
-    "sarif-viewer.connectToGithubCodeScanning": "off"
-    // "eslint.workingDirectories": [
-    //     ".", "src"
-    //   ]
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit",
+    "source.organizeImports": "explicit"
+  },
+  "editor.detectIndentation": false,
+  "editor.formatOnSave": true,
+  "editor.formatOnPaste": false,
+  "editor.insertSpaces": true,
+  "editor.tabSize": 4,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "search.exclude": {
+    "out": true,
+    "**/node_modules": true,
+    ".vscode-test": true
+  },
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "antlr4.generation": {
+    // Settings for "ANTLR4 grammar syntax support" extension
+    "mode": "internal",
+    "listeners": true,
+    "visitors": false
+  },
+  "vscode-nmake-tools.workspaceBuildDirectories": ["."],
+  "vscode-nmake-tools.installOsRepoRustHelperExtension": false,
+  "sarif-viewer.connectToGithubCodeScanning": "off",
+  "jest.runMode": "deferred",
+  "testing.automaticallyOpenTestResults": "neverOpen"
+  // "eslint.workingDirectories": [
+  //     ".", "src"
+  //   ]
 }

README.md

@@ -44,14 +44,12 @@ Your feedback, contributions, and ideas shape the future of the extension.
 
 # Prerequisites
 
-- **Mongo Shell Requirement (Optional)**: Some advanced commands in the Mongo [scrapbook](#mongo-scrapbooks), as well as use of the MongoDB shell, require installing [MongoDB shell](https://docs.mongodb.com/manual/installation/).
+- **Shell Requirement (Optional)**: Use of the DocumentDB shell requires installing [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/).
 
 ## Known Issues
 
 Here are some known issues and limitations to be aware of when using the DocumentDB VS Code extension:
 
-- **Escaped Characters in Scrapbooks**: Scrapbook support for escaped characters is preliminary. Use double escaping for newlines (`\\n` instead of `\n`).
-
 <!-- region exclude-from-marketplace -->
 
 #### References

extension.bundle.ts

@@ -22,16 +22,12 @@ export { AzureAccountTreeItemBase, createAzureClient } from '@microsoft/vscode-a
 // eslint-disable-next-line no-restricted-imports -- bundle intentionally re-exports many helpers for tests; nonNull helpers are provided locally in this repo
 export * from '@microsoft/vscode-azext-utils';
 export { isWindows, wellKnownEmulatorPassword } from './src/constants';
-export { connectToClient, isCosmosEmulatorConnectionString } from './src/documentdb/scrapbook/connectToClient';
-export { MongoCommand } from './src/documentdb/scrapbook/MongoCommand';
+export { connectToClient, isCosmosEmulatorConnectionString } from './src/documentdb/connectToClient';
 export {
     addDatabaseToAccountConnectionString,
     encodeMongoConnectionString,
     getDatabaseNameFromConnectionString,
-} from './src/documentdb/scrapbook/mongoConnectionStrings';
-export * from './src/documentdb/scrapbook/registerScrapbookCommands';
-export { findCommandAtPosition, getAllCommandsFromText } from './src/documentdb/scrapbook/ScrapbookHelpers';
-export { ShellScriptRunner as MongoShell } from './src/documentdb/scrapbook/ShellScriptRunner';
+} from './src/documentdb/mongoConnectionStrings';
 export { activateInternal, deactivateInternal } from './src/extension';
 export { ext } from './src/extensionVariables';
 export { SettingUtils } from './src/services/SettingsService';