[WIP] feature: shell integration 💻

.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"
+  //   ]
 }

jest.config.js

@@ -1,11 +1,18 @@
 /** @type {import('ts-jest').JestConfigWithTsJest} **/
 module.exports = {
-    testEnvironment: 'node',
-    testMatch: ['<rootDir>/src/**/*.test.ts'],
-    transform: {
-        '^.+.tsx?$': ['ts-jest', {}],
-    },
     // Limit workers to avoid OOM kills on machines with many cores.
     // Each ts-jest worker loads the TypeScript compiler and consumes ~500MB+.
     maxWorkers: '50%',
+    projects: [
+        {
+            displayName: 'extension',
+            testEnvironment: 'node',
+            testMatch: ['<rootDir>/src/**/*.test.ts'],
+            transform: {
+                '^.+\\.tsx?$': ['ts-jest', {}],
+            },
+        },
+        '<rootDir>/packages/schema-analyzer',
+        '<rootDir>/packages/documentdb-constants',
+    ],
 };

l10n/bundle.l10n.json

@@ -415,7 +415,6 @@
   "Error running process: ": "Error running process: ",
   "Error saving the document": "Error saving the document",
   "Error validating collection name availability: {0}": "Error validating collection name availability: {0}",
-  "Error while loading the autocompletion data": "Error while loading the autocompletion data",
   "Error while loading the data": "Error while loading the data",
   "Error while loading the document": "Error while loading the document",
   "Error while refreshing the document": "Error while refreshing the document",
@@ -521,7 +520,7 @@
   "Failed to validate source collection: {0}": "Failed to validate source collection: {0}",
   "Failed with code \"{0}\".": "Failed with code \"{0}\".",
   "Fair": "Fair",
-  "Filter: Enter the DocumentDB query filter in JSON format": "Filter: Enter the DocumentDB query filter in JSON format",
+  "Filter: Enter the DocumentDB query filter": "Filter: Enter the DocumentDB query filter",
   "Find Query": "Find Query",
   "Finished importing": "Finished importing",
   "Folder name cannot be empty": "Folder name cannot be empty",
@@ -616,18 +615,18 @@
   "Invalid Connection String: {error}": "Invalid Connection String: {error}",
   "Invalid connection type selected.": "Invalid connection type selected.",
   "Invalid document ID: {0}": "Invalid document ID: {0}",
-  "Invalid filter syntax: {0}. Please use valid JSON, for example: { \"name\": \"value\" }": "Invalid filter syntax: {0}. Please use valid JSON, for example: { \"name\": \"value\" }",
+  "Invalid filter syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { name: \"value\" }": "Invalid filter syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { name: \"value\" }",
   "Invalid folder type.": "Invalid folder type.",
   "Invalid mongoShell command format": "Invalid mongoShell command format",
   "Invalid node type.": "Invalid node type.",
   "Invalid payload for create index action": "Invalid payload for create index action",
   "Invalid payload for drop index action": "Invalid payload for drop index action",
   "Invalid payload for modify index action": "Invalid payload for modify index action",
   "Invalid projection syntax: {0}": "Invalid projection syntax: {0}",
-  "Invalid projection syntax: {0}. Please use valid JSON, for example: { \"fieldName\": 1 }": "Invalid projection syntax: {0}. Please use valid JSON, for example: { \"fieldName\": 1 }",
+  "Invalid projection syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { fieldName: 1 }": "Invalid projection syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { fieldName: 1 }",
   "Invalid semver \"{0}\".": "Invalid semver \"{0}\".",
   "Invalid sort syntax: {0}": "Invalid sort syntax: {0}",
-  "Invalid sort syntax: {0}. Please use valid JSON, for example: { \"fieldName\": 1 }": "Invalid sort syntax: {0}. Please use valid JSON, for example: { \"fieldName\": 1 }",
+  "Invalid sort syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { fieldName: 1 }": "Invalid sort syntax: {0}. Please use valid JSON or a DocumentDB API expression, for example: { fieldName: 1 }",
   "It could be better": "It could be better",
   "It looks like there aren't any other folders to move these items into.\nYou might want to create a new folder first.\n\nNote: You can't move items between 'DocumentDB Local' and regular connections.": "It looks like there aren't any other folders to move these items into.\nYou might want to create a new folder first.\n\nNote: You can't move items between 'DocumentDB Local' and regular connections.",
   "item": "item",
@@ -721,7 +720,6 @@
   "No matching resources found.": "No matching resources found.",
   "No node selected.": "No node selected.",
   "No parent folder selected.": "No parent folder selected.",
-  "No properties found in the schema at path \"{0}\"": "No properties found in the schema at path \"{0}\"",
   "No public connectivity": "No public connectivity",
   "No result returned from the MongoDB shell.": "No result returned from the MongoDB shell.",
   "No results found": "No results found",