Merge pull request #22 from Litenova-Solutions/release/v3.1.1

Release 3.1.1: extension fixes, codebase-owned versioning, and defensive indexing

Author: litenova

.github/workflows/ci.yml

@@ -20,6 +20,10 @@ jobs:
         with:
           dotnet-version: '10.0.x'
 
+      - name: Verify version consistency
+        shell: pwsh
+        run: ./build/verify-version.ps1
+
       - name: Restore
         run: dotnet restore Fuse.slnx
 

.github/workflows/ext-release.yml

@@ -1,16 +1,34 @@
 name: Extension release (platform VSIXes)
 
-# Produces a platform-specific VSIX per OS/arch with a self-contained Fuse host bundled in (so the extension
-# runs with no global install). Manually dispatched or on an ext-v* tag. Each platform builds on its matching
-# OS so the host publishes natively; the six VSIXes are uploaded as artifacts for a maintainer to publish.
+# Part of the vX.Y.Z release: the same tag that ships the .NET tool ships the VS Code extension. Builds a
+# platform-specific VSIX per OS/arch with a self-contained Fuse host bundled in (so the extension runs with no
+# global install), each on its matching OS so the host publishes natively, then publishes all six to the VS Code
+# Marketplace and Open VSX. Publishing is gated on the VSCE_PAT / OVSX_PAT secrets, so until those are set the
+# release still builds the VSIXes as artifacts. A manual dispatch builds artifacts without publishing.
 on:
   workflow_dispatch:
   push:
-    tags: ['ext-v*']
+    tags: ['v*.*.*']
 
 jobs:
+  verify:
+    name: Verify version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # The codebase owns the version (see build/verify-version.ps1). On a release tag, fail unless the tag
+      # matches package.json and the sibling packages; on manual dispatch, just check cross-package consistency.
+      - name: Verify version
+        shell: pwsh
+        run: |
+          if ("${{ github.ref_type }}" -eq "tag") { ./build/verify-version.ps1 -Tag "${{ github.ref_name }}" }
+          else { ./build/verify-version.ps1 }
+
   package:
     name: Package ${{ matrix.vsceTarget }}
+    needs: verify
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -70,3 +88,41 @@ jobs:
         with:
           name: fuse-vscode-${{ matrix.vsceTarget }}
           path: ext/vscode/*.vsix
+
+  publish:
+    name: Publish to marketplaces
+    needs: package
+    runs-on: ubuntu-latest
+    # Only publish on a release tag; a manual dispatch stops at the artifacts. Each step is further gated on its
+    # token secret, so the job is a clean no-op until the secrets are configured.
+    if: github.ref_type == 'tag'
+    env:
+      VSCE_PAT: ${{ secrets.VSCE_PAT }}
+      OVSX_PAT: ${{ secrets.OVSX_PAT }}
+    steps:
+      - name: Download platform VSIXes
+        uses: actions/download-artifact@v4
+        with:
+          path: vsix
+          pattern: fuse-vscode-*
+          merge-multiple: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # All six platform VSIXes carry the same version and distinct targets, so one publish uploads them as the
+      # platform variants of one Marketplace version.
+      - name: Publish to VS Code Marketplace
+        if: env.VSCE_PAT != ''
+        run: npx --yes @vscode/vsce publish --pat "$VSCE_PAT" --packagePath vsix/*.vsix
+
+      - name: Publish to Open VSX
+        if: env.OVSX_PAT != ''
+        run: |
+          for f in vsix/*.vsix; do npx --yes ovsx publish "$f" -p "$OVSX_PAT"; done
+
+      - name: Report skipped publish
+        if: env.VSCE_PAT == '' && env.OVSX_PAT == ''
+        run: echo "::notice::No VSCE_PAT or OVSX_PAT secret configured; the six VSIXes were built as artifacts but not published."

.github/workflows/mcp-registry.yml

@@ -38,20 +38,16 @@ jobs:
           fi
           echo "Manifest description length ${len}/100 - OK."
 
-      - name: Resolve package version
+      # server.json is the source of truth for the version (see build/set-version.ps1). On a tag, fail if the
+      # manifest does not match it; on manual dispatch, just check cross-package consistency. Then read the
+      # published version from the manifest itself, no tag rewrite.
+      - name: Verify version and read from manifest
+        shell: pwsh
         run: |
-          set -euo pipefail
-          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
-            VERSION="${GITHUB_REF_NAME#v}"
-            jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' \
-              mcp-registry/server.json > mcp-registry/server.tmp
-            mv mcp-registry/server.tmp mcp-registry/server.json
-            echo "server.json version set from tag to $VERSION"
-          else
-            VERSION="$(jq -r '.version' mcp-registry/server.json)"
-            echo "No tag; using server.json version $VERSION"
-          fi
-          echo "PKG_VERSION=$VERSION" >> "$GITHUB_ENV"
+          if ("${{ github.ref_type }}" -eq "tag") { ./build/verify-version.ps1 -Tag "${{ github.ref_name }}" }
+          else { ./build/verify-version.ps1 }
+          $v = (Get-Content mcp-registry/server.json -Raw | ConvertFrom-Json).version
+          "PKG_VERSION=$v" >> $env:GITHUB_ENV
 
       - name: Install mcp-publisher
         run: |

.github/workflows/publish.yml

@@ -23,12 +23,15 @@ jobs:
         with:
           dotnet-version: '10.0.x'
 
-      - name: Extract version from tag
+      - name: Verify version and read from codebase
         id: version
-        shell: bash
+        shell: pwsh
         run: |
-          VERSION="${GITHUB_REF_NAME#v}"
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          # The codebase is the source of truth; fail the release if the tag does not match it.
+          ./build/verify-version.ps1 -Tag "${{ github.ref_name }}"
+          $v = ([xml](Get-Content Directory.Build.props)).Project.PropertyGroup.Version |
+               Where-Object { $_ } | Select-Object -First 1
+          "version=$v" >> $env:GITHUB_OUTPUT
 
       - name: Install Linux publish prerequisites
         run: |

.github/workflows/release.yml

@@ -26,11 +26,13 @@ jobs:
         with:
           dotnet-version: '10.0.x'
 
-      - name: Extract version from tag
+      - name: Verify version and read from codebase
         id: version
         shell: pwsh
         run: |
-          $version = "${{ github.ref_name }}".TrimStart('v')
+          ./build/verify-version.ps1 -Tag "${{ github.ref_name }}"
+          $version = ([xml](Get-Content Directory.Build.props)).Project.PropertyGroup.Version |
+                     Where-Object { $_ } | Select-Object -First 1
           echo "VERSION=$version" >> $env:GITHUB_OUTPUT
 
       - name: Publish self-contained win-x64
@@ -85,9 +87,14 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y clang zlib1g-dev
 
-      - name: Extract version from tag
+      - name: Verify version and read from codebase
         id: version
-        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+        shell: pwsh
+        run: |
+          ./build/verify-version.ps1 -Tag "${{ github.ref_name }}"
+          $version = ([xml](Get-Content Directory.Build.props)).Project.PropertyGroup.Version |
+                     Where-Object { $_ } | Select-Object -First 1
+          echo "VERSION=$version" >> $env:GITHUB_OUTPUT
 
       - name: Publish self-contained linux-x64
         run: |

AGENTS.md

@@ -40,6 +40,7 @@ Build first, then test with `--no-build`. CI verifies build, test, format, and a
 - External-process arguments are bounded. Commands built from a variable-length path or id list (for example the git invocations in `GitStatsProvider` and `GitChangeDetector`) must chunk the list or pass it via stdin. A single concatenated command line overflows the OS limit on large repos and silently degrades to empty results.
 - Tests must actually run. When adding a test, confirm the test command discovers and executes it (the count goes up). The extension contract suite is wired through `ext/vscode/package.json` `test:contract`; a test placed where that script does not reach is dead. A green gate that ran zero new tests is not coverage.
 - Behavior changes are not silent. A change that alters throw or propagation behavior (for example SQLite flush exhaustion swallowing instead of rethrowing) is a behavior change; call it out, do not fold it into an "add logging" change.
+- Upgrades degrade to a clear message or a rebuild, never an opaque failure. Renaming or removing an MCP tool must keep the old name registered as a deprecation shim (in `FuseDeprecatedTools`) that returns an actionable message naming the replacement, for one major version; a client that cached the old surface across an upgrade must not see a bare `Unknown tool`. A change to the index extraction contract must either bump `WorkspaceIndexSchema.TargetVersion` or ride the Fuse-version stamp (`fuse_version` in `index_meta`, compared by `FuseBuildInfo.IsCompatible`), so a stale on-disk index rebuilds itself rather than serving stale data. The changelog entry names the reload or rebuild.
 
 ## MCP Tools
 
@@ -62,6 +63,8 @@ All numbers come from `tests/benchmarks/results` (the recorded data) and the ben
 
 - Branch off `main`; open a PR via `gh` when verified. Do not merge, self-approve, or enable auto-merge; leave merges to reviewers.
 - Keep build, test, and format green. New public API without XML docs is incomplete.
+- The product version lives in the codebase, not in the git tag. `Directory.Build.props` `<Version>` is the single source of truth for every .NET assembly; the VS Code extension (`ext/vscode/package.json`), the MCP registry manifest (`mcp-registry/server.json`), and the docs site (`site/package.json`) carry the same number. Bump all of them with `build/set-version.ps1 <version>`, never by hand one at a time. `build/verify-version.ps1` fails CI if the packages disagree, and on a release it fails if the tag does not match the codebase version.
+- One tag releases everything. The flow is: run `build/set-version.ps1 X.Y.Z`, commit, then push a matching `vX.Y.Z` tag. That single tag triggers the NuGet publish (`publish.yml`), the GitHub release binaries (`release.yml`), the MCP registry (`mcp-registry.yml`), and the VS Code extension (`ext-release.yml`, which builds the six platform VSIXes and publishes them to the VS Code Marketplace and Open VSX when the `VSCE_PAT` / `OVSX_PAT` secrets are set, otherwise it just uploads the VSIXes as artifacts). Every one of these verifies the tag against the codebase version first, so a mismatched tag fails the release rather than shipping the wrong number. There is no separate extension tag; the old `ext-v*` trigger is retired.
 
 ## Writing Style (docs and prose)
 

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to Fuse are documented here. The format is based on Keep a Changelog. Fuse 3.0 is a product overhaul; backward compatibility with 2.x output, commands, and the MCP tool surface is not a goal.
 
+## [3.1.1] - 2026-07-01
+
+### Added
+
+- **`fuse update` command.** Updates the global tool with the process-lock choreography a bare `dotnet tool update` cannot do on its own: it stops the running Fuse hosts that hold the file locks (for example the one an editor extension spawns), then hands the update to a small detached script that waits for the current process to exit before replacing the tool files. This works around the fact that a running .NET global tool locks its own files on Windows. Reload the editor window afterward so its MCP client re-handshakes with the new tool surface.
+- **Deprecation shims for the retired V2 MCP tool names.** `fuse_toc`, `fuse_skeleton`, `fuse_search`, `fuse_focus`, `fuse_changes`, `fuse_ask`, `fuse_dotnet`, and `fuse_generic` are registered again as thin tools that return an actionable message naming the V3 replacement. A client that cached the old tool surface and was upgraded underneath now gets clear guidance instead of an opaque `Unknown tool` error. They will be removed in the next major.
+
+### Changed
+
+- **The index self-heals on an incompatible upgrade.** The index records the Fuse build that wrote it; when a later run's `major.minor` differs, the index rebuilds automatically before it is read, so a minor upgrade never serves stale extraction. A patch release keeps the contract and does not force a rebuild. `fuse diagnostics` reports both the running version and the version that built the index.
+
+### Changed
+
+- **The product version is owned by the codebase, not the git tag.** `Directory.Build.props` `<Version>` is the single source of truth for every .NET assembly, and the VS Code extension, the MCP registry manifest, and the docs site carry the same number. `build/set-version.ps1` bumps all of them at once and `build/verify-version.ps1` fails CI on any drift, or on a release tag that does not match. This also fixes the index version stamp: `FuseBuildInfo` now reports the real product version (previously the non-CLI assemblies were left at 1.0.0), so the version-drift self-heal and `fuse diagnostics` report correctly.
+
+### Fixed
+
+- **Indexing is defensive against duplicate and foreign content.** The trigger was Claude Code writing full duplicate checkouts under `.claude/worktrees/`, so `fuse_localize` returned ten candidates that were all worktree copies. The fix is layered rather than a single name: (1) discovery prunes any nested version-control root (git worktree, submodule, or embedded clone) anywhere under the workspace, not just `.claude`; (2) for a git repository the file set now comes from git itself (tracked plus untracked-but-not-ignored), so other worktrees and ignored trees are excluded by construction, with the directory walk as the fallback; (3) the excluded-directory set is shared by the scanner and the .NET discoverer, widened to the common tooling, build, and dependency directories, and extensible per repository through a `.fuseignore` file; (4) byte-identical solution copies no longer flip discovery into projects mode; and (5) retrieval collapses byte-identical files, so a query never returns several copies of one source file even if duplication reaches the index.
+- **VS Code host connection gave up too early and orphaned the host.** The extension waited only about three seconds for a freshly spawned host to create its named pipe, so a cold .NET host under load (a debugger attached, other extensions busy) surfaced as `connect ENOENT`, and the supervisor left the still-starting host orphaned on the pipe. The connect now waits against a generous deadline, bails out early if the host process exits before it serves, kills the host if it does give up so no orphan squats the pipe, and reports a spawn error. Activation no longer blocks on the connect.
+- **VS Code host handshake serialized PascalCase, breaking the extension.** The `fuse host` JSON-RPC endpoint applied the source-generated context as a resolver but not its camelCase naming policy, so the wire emitted `ProtocolVersion` where the extension's `vscode-jsonrpc` client reads `protocolVersion`. Every field deserialized as its default, surfacing as an opaque "Fuse host protocol mismatch: host undefined". The host now sets the camelCase policy on the formatter, and a cross-formatter regression test (a camelCase client, matching the extension) guards it; the prior same-formatter test could not see the casing.
+
 ## [3.1.0] - 2026-06-30
 
 Fuse 3.1 sharpens the .NET semantic engine on the modes where 3.0 was weakest: open-ended discovery, language breadth, and first-call latency. Dense retrieval is now on by default and fully offline, the open-ended path refuses and routes instead of guessing on a vague request, and more of the codebase's own vocabulary is searchable without a model. The numbers behind every claim are on the [benchmarks page](https://fuse.codes/docs/project/benchmarks).

Directory.Build.props

@@ -1,6 +1,10 @@
 <Project>
   <PropertyGroup>
     <RepoRoot Condition="'$(RepoRoot)' == ''">$([System.IO.Path]::GetFullPath('$(MSBuildThisFileDirectory)'))</RepoRoot>
+    <!-- Single source of truth for the product version, applied to every Fuse assembly so the CLI, the host,
+         and FuseBuildInfo (the index version stamp) all report the same number. The release tag must match this
+         (enforced by build/verify-version.ps1); bump every package in lockstep with build/set-version.ps1. -->
+    <Version>3.1.1</Version>
     <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>

build/pack-tool.ps1

@@ -1,12 +1,22 @@
 param(
-    [string]$Version = "2.0.0",
+    # Empty means read the single source of truth in Directory.Build.props, so a local pack is correctly
+    # versioned without passing anything. CI passes the file version explicitly after verifying it matches the tag.
+    [string]$Version = "",
     [string[]]$Rids = @("win-x64", "linux-x64", "osx-x64")
 )
 
 $ErrorActionPreference = "Stop"
 $PSNativeCommandUseErrorActionPreference = $true
 
 $root = Split-Path -Parent $PSScriptRoot
+
+if ([string]::IsNullOrWhiteSpace($Version)) {
+    $propsPath = Join-Path $root "Directory.Build.props"
+    $Version = ([xml](Get-Content $propsPath)).Project.PropertyGroup.Version |
+        Where-Object { $_ } | Select-Object -First 1
+    if ([string]::IsNullOrWhiteSpace($Version)) { throw "No <Version> found in $propsPath" }
+    Write-Host "Using version $Version from Directory.Build.props"
+}
 $cliProject = Join-Path $root "src/Host/Fuse.Cli/Fuse.Cli.csproj"
 $outputDir = Join-Path $root "src/Host/Fuse.Cli/nupkg"
 $runtimeRoot = Join-Path $root "artifacts/runtime"

build/set-version.ps1

@@ -0,0 +1,39 @@
+# Sets the product version across every package in one step: the .NET source of truth (Directory.Build.props),
+# the VS Code extension (package.json plus its lock, via npm), the MCP registry manifest (both version fields),
+# and the docs website. Run this, commit, then tag the matching version; build/verify-version.ps1 enforces the
+# match in CI.
+#
+#   ./build/set-version.ps1 3.1.2
+param(
+    [Parameter(Mandatory)][string]$Version
+)
+
+$ErrorActionPreference = "Stop"
+$root = Split-Path -Parent $PSScriptRoot
+
+# .NET: the single <Version> in Directory.Build.props.
+$props = Join-Path $root "Directory.Build.props"
+(Get-Content $props -Raw) -replace '<Version>[^<]*</Version>', "<Version>$Version</Version>" |
+    Set-Content $props -NoNewline
+Write-Host "Directory.Build.props -> $Version"
+
+# VS Code extension: npm keeps package.json and package-lock.json in sync.
+Push-Location (Join-Path $root "ext/vscode")
+try { npm version $Version --no-git-tag-version --allow-same-version | Out-Null }
+finally { Pop-Location }
+Write-Host "ext/vscode/package.json -> $Version"
+
+# MCP registry manifest: both the server version and the package version. Edited by regex so the file layout is
+# preserved (ConvertTo-Json would reformat the whole document).
+$serverJson = Join-Path $root "mcp-registry/server.json"
+(Get-Content $serverJson -Raw) -replace '"version":\s*"[^"]*"', "`"version`": `"$Version`"" |
+    Set-Content $serverJson -NoNewline
+Write-Host "mcp-registry/server.json -> $Version"
+
+# Docs website: pin package.json to the same version.
+$siteJson = Join-Path $root "site/package.json"
+(Get-Content $siteJson -Raw) -replace '"version":\s*"[^"]*"', "`"version`": `"$Version`"" |
+    Set-Content $siteJson -NoNewline
+Write-Host "site/package.json -> $Version"
+
+& (Join-Path $PSScriptRoot "verify-version.ps1")