From 4684e19fd77eb41b827293a6968a87ba5fe4f03f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20Kr=C3=BCger?= Date: Fri, 2 Oct 2026 14:32:23 +0200 Subject: [PATCH] Prepare 1.1.271-preview release notes Complete merged change coverage and retain the Unreleased heading when preparing releases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 1 + CHANGELOG.md | 37 ++++++++++++++++++++++++++------- 2 files changed, 31 insertions(+), 7 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 24abf69f..42db7043 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -39,6 +39,7 @@ ## Documentation - Update `README.md` for user-visible CLI changes. +- Always retain `## Unreleased` at the top of `CHANGELOG.md`, even when it is empty. When preparing a release, move its entries into a dated version section below it; never replace or remove the Unreleased heading. - Update the relevant docs in `docs/`, especially: - `docs/commands.md` for command usage - `docs/navigation.md` for CLI arguments and shell navigation diff --git a/CHANGELOG.md b/CHANGELOG.md index e31d8738..760da1d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,33 +2,53 @@ ## Unreleased +## 1.1.271-preview — 2026-10-02 + +### New features + +- **Transactional `batch` command.** Execute 1-100 `create`, `upsert`, `replace`, `delete`, or `patch` operations atomically within one partition key with `batch run --partition-key `. Interactive shells can also assemble a batch with `begin`/`add`/`execute`, inspect it with `status`/`show`, or discard it with `cancel`. A failed operation rolls back the entire batch. MCP exposes only the one-shot `run` mode because clients share shell state. ([#135](https://github.com/Azure/CosmosDBShell/pull/135)) +- **`query --explain`.** Inspect index usage, utilized and potential indexes, index-hit ratio, request charge, and a plain-language evaluation instead of returning documents. The probe reads only the first query page with `MaxItemCount = 1`; its metrics are estimates, and unavailable index metrics are reported as unknown rather than as a full scan. Available in interactive, machine-readable, and MCP output. ([#131](https://github.com/Azure/CosmosDBShell/pull/131)) +- **Read-only `doctor` diagnostics.** Run bounded local, DNS, data-plane, and optional ARM checks without changing connection or navigation or initiating interactive login. Supports explicit database/container targets, an opt-in constant-projection query, timeout controls, and structured reports with verdicts, timings, and observed RUs. `doctor who` adds known credential and scope information without claiming verified write access. Clock-skew estimates reuse existing response headers; a bounded public GitHub release lookup reports available updates and can be disabled with `--no-update-check`. ([#209](https://github.com/Azure/CosmosDBShell/pull/209)) +- **Live MCP shell-location resource.** Read `cosmos://shell/current-location` for both `currentLocation` and `currentAccountEndpoint`, and subscribe to updates caused by interactive or MCP navigation and connection changes. MCP `2026-07-28` clients use `subscriptions/listen`; clients using the `initialize` handshake use `resources/subscribe` and the session's GET stream. Notifications signal clients to reread the resource; explicit database/container arguments remain the reliable way to target independent operations. ([#223](https://github.com/Azure/CosmosDBShell/pull/223), [#231](https://github.com/Azure/CosmosDBShell/pull/231), [#232](https://github.com/Azure/CosmosDBShell/pull/232)) + ### Improvements -- Cosmos DB data-plane commands now consistently expose their aggregate observed request charge in structured output and connection-scoped `info` telemetry, including metadata/configuration operations, scripts, change feed reads, paginated operations, handled probes, and charged failures. Azure Resource Manager control-plane operations remain uncharged. -- Added `$sessionRequestCharge` and `$sessionChargedOperationCount` as read-only shell variables. Set `$sessionRequestChargeWarningThreshold` to a positive RU threshold to print one warning when the current connection reaches it; `info` reports it as `session.requestChargeWarningThreshold`. +- Cosmos DB data-plane commands now consistently expose their aggregate observed request charge in structured output and connection-scoped `info` telemetry, including metadata/configuration operations, scripts, change feed reads, paginated operations, handled probes, and charged failures. MCP results carry the observed cost in a top-level `requestCharge` field, including charged failures. Azure Resource Manager control-plane operations remain uncharged. ([#171](https://github.com/Azure/CosmosDBShell/pull/171)) +- Added `$sessionRequestCharge` and `$sessionChargedOperationCount` as read-only shell variables. Set `$sessionRequestChargeWarningThreshold` to a positive RU threshold to print one warning when the current connection reaches it; `info` reports it as `session.requestChargeWarningThreshold`. ([#171](https://github.com/Azure/CosmosDBShell/pull/171)) +- MCP `query` and container-item `ls` calls now return bounded, resumable pages with an opaque `continuationToken`. Pass a non-null token back as `continuation` with the same query and options to retrieve the next page. Database/container name listings remain complete, and interactive and scripted commands retain their existing multi-page behavior. ([#204](https://github.com/Azure/CosmosDBShell/pull/204)) +- The HTTP MCP server supports protocol `2026-07-28` without a session, including streamed `subscriptions/listen` updates and multi-round-trip destructive confirmations. Confirmation retries carry server-signed, single-use state tied to the exact command and shell context, expiring after 10 minutes. Clients using the `initialize` handshake retain session-based `elicitation/create`; their location subscriptions end when the session is deleted or has no open requests for 10 minutes. ([#231](https://github.com/Azure/CosmosDBShell/pull/231), [#232](https://github.com/Azure/CosmosDBShell/pull/232)) +- The welcome screen, command-example descriptions, runtime errors, and theme-preview labels now use localization resources and the OS UI language when translations are available, with English fallback for untranslated text. Added and refreshed catalogs for Czech, German, Spanish, French, Italian, Japanese, Korean, Polish, Brazilian Portuguese, Russian, Turkish, and Simplified and Traditional Chinese. Executable examples, command names, and flags remain unchanged. ([#206](https://github.com/Azure/CosmosDBShell/pull/206), [#211](https://github.com/Azure/CosmosDBShell/pull/211), [#212](https://github.com/Azure/CosmosDBShell/pull/212), [#213](https://github.com/Azure/CosmosDBShell/pull/213), [#216](https://github.com/Azure/CosmosDBShell/pull/216), [#217](https://github.com/Azure/CosmosDBShell/pull/217)) +- Cosmos DB SDK requests now include the shell application version in the user agent, making client versions identifiable in service diagnostics. ([#210](https://github.com/Azure/CosmosDBShell/pull/210)) - Destructive MCP confirmations now identify their target. The elicitation prompt adds the connected account endpoint and the current database/container location, and notes that explicit `--db`/`--con` arguments override that location. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) - Import and export no longer hold entire files in memory. CSV imports are parsed incrementally, and CSV exports spool documents to a private temporary file to determine the complete column set, so transfers no longer scale with document count. Allow temporary disk space for the CSV export spool in addition to the destination file. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) - Script diagnostics now report where a failure happened. Human-readable output shows the innermost source location first followed by the recorded function and script call sites, JSON errors carry the originating file, line, and column, and diagnostic logs retain both through the existing secret-redaction pipeline. Functions keep their defining file's location even when invoked from another file. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - The language server now applies the same validation as script execution: control-flow placement, duplicate function parameters, document-local function names, and commands and built-in options nested inside blocks, branches, loops, pipelines, and command expressions. Variable and function symbols are case-sensitive, so `$value` and `$Value` stay distinct. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - Host-requested cancellation now propagates through script files, blocks, loops, and function calls without being turned into a positional runtime error. The shell reports a neutral result, records the cancellation in the diagnostic log, and restores call scopes and source context. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - Documented the shell language in [programming](docs/programming.md): operator precedence and associativity, compound assignment, numeric promotion, a statement grammar, validation rules, and resource limits. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) -- `rm` accepts `--partition-key` (`--pk`) to restrict both the dry run and the deletion to one complete logical partition key, including typed and hierarchical keys. `rm --key=id --partition-key=` uses a point read or point delete instead of scanning the container, and its dry run reports the item's `id`, `partitionKey`, and `etag`. The new `--etag` option deletes that item only if its ETag still matches; a mismatch fails without retrying. ([#229](https://github.com/Azure/CosmosDBShell/issues/229)) +- `rm` accepts `--partition-key` (`--pk`) to restrict both the dry run and the deletion to one complete logical partition key, including typed and hierarchical keys. `rm --key=id --partition-key=` uses a point read or point delete instead of scanning the container, and its dry run reports the item's `id`, `partitionKey`, and `etag`. The new `--etag` option deletes that item only if its ETag still matches; a mismatch fails without retrying. ([#230](https://github.com/Azure/CosmosDBShell/pull/230), [#229](https://github.com/Azure/CosmosDBShell/issues/229)) ### Breaking changes +- MCP `query` and container-item `ls` no longer aggregate all pages in a single call. `max` bounds one page and must be positive; omitted or non-positive values use a default cap of 100. Clients must follow non-null `continuationToken` values rather than assuming a short page means exhaustion. A null token marks exhaustion unless `resultIncomplete` is true. ([#204](https://github.com/Azure/CosmosDBShell/pull/204)) - Malformed CSV files are now rejected instead of being silently misread. An unterminated or misplaced quote previously caused the remainder of the file to be absorbed into a single field, so the import reported success while writing corrupted items. Such files now abort with `Invalid CSV record at line `. Imports that previously appeared to succeed may now fail and require the source file to be corrected. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) - Command text and script files are now fully parsed and validated before any of their statements run, so a syntax or semantic error prevents the entire input from executing rather than failing part-way through. Invalid control flow is rejected: `return` requires an enclosing function or script file, `break` and `continue` require an enclosing loop in the same function or script, and duplicate function parameter names are refused. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - Calling a function with too few or too many arguments is now a usage error that exits with code `2`, including calls inside expressions. The function body does not run. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) -- Integer arithmetic now reports overflow as an error instead of wrapping. Integer literal magnitudes must be between `0` and `2147483647`; because the minus sign is a separate unary operator, the minimum integer must be written as `-2147483647 - 1`. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) +- Integer arithmetic now reports overflow as an error instead of wrapping. Shell integer literal magnitudes must be between `0` and `2147483647`; because the minus sign is a separate unary operator, the minimum shell integer must be written as `-2147483647 - 1`. Standalone large integer literals inside JSON objects and arrays are preserved as JSON numbers instead of being rejected; this does not extend the shell's integer arithmetic range. ([#208](https://github.com/Azure/CosmosDBShell/pull/208), [#225](https://github.com/Azure/CosmosDBShell/pull/225)) - JSON construction now preserves decimal types, so `$object = {"value":3.0}` stores JSON `3.0` and `$object.value / 2` produces `1.5`. It previously stored `3` and performed integer division, producing `1`. Scripts that relied on the old truncation must be reviewed. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - A failed command expression now propagates its error instead of silently producing an empty result. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) - Scripts are subject to fixed resource limits: a shared parser nesting budget of 128 entries, a maximum expression tree depth of 128 nodes, and at most 64 active function and script-file calls. Exceeding a limit fails with a diagnostic instead of continuing recursive parsing or execution. ([#208](https://github.com/Azure/CosmosDBShell/pull/208)) ### Fixes -- `mkdb`, `mkcon`, `create database`, and `create container` now work on serverless accounts. They previously requested autoscale throughput even when `--scale` and `--ru` were omitted, which serverless accounts reject. Omitting both options now creates the resource without throughput settings; supplying either option on a serverless account fails with an explanation. Provisioned accounts keep the existing autoscale default of 1000 RU/s. ([#218](https://github.com/Azure/CosmosDBShell/issues/218)) -- Vector `ORDER BY`, `ORDER BY RANK` relevance ranking, and object-shaped `DISTINCT` projections no longer fail with a continuation-token error. These query pipelines execute successfully but cannot export a resumable token, which was previously reported as a command failure. Such queries now return their documents; through MCP they keep reading until the requested limit instead of stopping after one page, and a truncated result is reported as `resultIncomplete` rather than as an exhausted result set. ([#219](https://github.com/Azure/CosmosDBShell/issues/219)) -- Local emulator outages are now detected across Cosmos DB commands. Requests fail promptly with an error and return the shell to its disconnected state instead of leaving an unresponsive session labeled as connected. +- Explicit JSON `null` values in ordinary MCP arguments are treated as omitted rather than failing nullable option binding, and are not echoed into history. Required arguments still fail validation when absent. `continuation` and the `rm` safety options `partition-key`/`pk` and `etag` reject explicit nulls instead of silently removing paging or deletion safeguards. Numeric arguments in echoed commands, confirmations, and history now use invariant formatting so they replay correctly under comma-decimal locales. ([#227](https://github.com/Azure/CosmosDBShell/pull/227)) +- Concurrent shell processes now merge saved history under a shared lock instead of overwriting each other's entries. Saves and clears publish a complete, flushed replacement, preserving the existing file on failed writes; failed clears report an error without discarding loaded history. Temporary history files use restricted permissions, including preserved access rules or owner-only access on Windows. ([#228](https://github.com/Azure/CosmosDBShell/pull/228)) +- CSV export now preserves scalar, array, and null query results in a scalar column, including results mixed with objects. The header is empty by default and can be named with `COSMOSDB_SHELL_CSV_SCALAR_COLUMN`; a collision with an object property fails explicitly. CSV import ignores empty headers only for empty cells and reports a line/column error for non-empty values under an empty header. ([#224](https://github.com/Azure/CosmosDBShell/pull/224)) +- Startup and interactive output no longer crash on terminals without ANSI support. Linux containers without ICU can run in .NET globalization-invariant mode using bundled English messages. ([#226](https://github.com/Azure/CosmosDBShell/pull/226)) +- Numeric parsing and conversion now use invariant culture, so decimal values in scripts and JSON properties behave consistently under comma-decimal locales. Large integer literals in JSON objects and arrays retain their exact JSON representation rather than overflowing the shell's 32-bit integer parser. ([#225](https://github.com/Azure/CosmosDBShell/pull/225)) +- Data-plane indexing-policy reads and replacements now preserve included/excluded paths, composite indexes, spatial indexes, and vector indexes instead of losing SDK collection properties during serialization. The policy conversion uses the Cosmos SDK's Newtonsoft.Json contract; document serialization remains on System.Text.Json. ([#215](https://github.com/Azure/CosmosDBShell/pull/215)) +- `mkdb`, `mkcon`, `create database`, and `create container` now work on serverless accounts. They previously requested autoscale throughput even when `--scale` and `--ru` were omitted, which serverless accounts reject. Omitting both options now creates the resource without throughput settings; supplying either option on a serverless account fails with an explanation. Provisioned accounts keep the existing autoscale default of 1000 RU/s. ([#222](https://github.com/Azure/CosmosDBShell/pull/222), [#218](https://github.com/Azure/CosmosDBShell/issues/218)) +- Vector `ORDER BY`, `ORDER BY RANK` relevance ranking, and object-shaped `DISTINCT` projections no longer fail with a continuation-token error. These query pipelines execute successfully but cannot export a resumable token, which was previously reported as a command failure. Such queries now return their documents; through MCP they keep reading until the requested limit instead of stopping after one page, and a truncated result is reported as `resultIncomplete` rather than as an exhausted result set. ([#221](https://github.com/Azure/CosmosDBShell/pull/221), [#219](https://github.com/Azure/CosmosDBShell/issues/219)) +- Local emulator outages are now detected across Cosmos DB commands. Requests fail promptly with an error and return the shell to its disconnected state instead of leaving an unresponsive session labeled as connected. ([#200](https://github.com/Azure/CosmosDBShell/pull/200)) - A failed or cancelled export no longer destroys its destination file. Exports are written to a temporary file in the destination directory and moved into place only after they complete, so an existing file survives query failures, write failures, and cancellation. An abrupt process termination can leave an unfinished `.cosmos-export-*.tmp` file behind. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) - `export --max` no longer requests a further query page once the limit is reached, so the reported request charge no longer includes a page whose items were discarded. Query iterators are now disposed. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) - Shell and MCP command execution is serialized, including nested shell calls, so concurrent requests can no longer interleave and corrupt the shared connection and navigation state. Waiting for a destructive confirmation does not hold the execution lock. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) @@ -45,6 +65,9 @@ ### Build & pipeline - Added a dependency on CsvHelper 33.1.0 for CSV parsing. ([#207](https://github.com/Azure/CosmosDBShell/pull/207)) +- Upgraded ModelContextProtocol and ModelContextProtocol.AspNetCore to 2.2.0 for the updated HTTP transport and subscription lifecycle. ([#231](https://github.com/Azure/CosmosDBShell/pull/231), [#232](https://github.com/Azure/CosmosDBShell/pull/232)) +- Added OneLoc catalog export, translation-resource generation, and CI checks that reject missing or stale committed localization catalogs. Local builds refresh the source catalog; CI verifies it without rewriting it. The localization tool project is now included in the solution. ([#206](https://github.com/Azure/CosmosDBShell/pull/206), [#220](https://github.com/Azure/CosmosDBShell/pull/220)) +- Pinned GitHub Actions to full-length commit SHAs and updated the grouped Actions dependencies. ([#202](https://github.com/Azure/CosmosDBShell/pull/202), [#203](https://github.com/Azure/CosmosDBShell/pull/203)) ## 1.1.209-preview — 2026-08-26