feat(vscode): improve launcher clarity, range-aware source reveal, and marketplace readiness

orenlab · orenlab · commit 37c24e381bf9 · 2026-04-05T23:03:32.000+05:00
- make unsupported CodeClone runtime errors explain which launcher the extension resolved and whether it came from the workspace, explicit settings, PATH, or repo-local uv fallback
- document that auto launcher resolution prefers the current workspace virtualenv before falling back to PATH
- fix source reveal for clone review by hydrating canonical finding detail when summary locations are range-truncated, so block and segment findings reveal the full span instead of only the first line
- bump the preview VS Code extension to 0.2.1, refresh packaged metadata, and add the live Marketplace listing across the repo and extension docs
diff --git a/README.md b/README.md
@@ -164,7 +164,7 @@ Optional read-only MCP server for AI agents and IDE clients.
 21 tools + 10 resources — never mutates source, baselines, or repo state.
 
 ```bash
-uv tool install "codeclone[mcp]"       # or: uv pip install "codeclone[mcp]"
+uv tool install --pre "codeclone[mcp]"       # or: uv pip install --pre "codeclone[mcp]"
 
 codeclone-mcp --transport stdio            # local (Claude Code, Codex, Copilot, Gemini CLI)
 codeclone-mcp --transport streamable-http  # remote / HTTP-only clients
@@ -179,7 +179,7 @@ Docs:
 
 | Surface                   | Location                                                                                                                     | Purpose                                            |
 |---------------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
-| **VS Code extension**     | [`extensions/vscode-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/vscode-codeclone)                 | Triage-first structural review in the editor       |
+| **VS Code extension**     | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone)                                 | Triage-first structural review in the editor       |
 | **Claude Desktop bundle** | [`extensions/claude-desktop-codeclone/`](https://github.com/orenlab/codeclone/tree/main/extensions/claude-desktop-codeclone) | Local `.mcpb` install with pre-loaded instructions |
 | **Codex plugin**          | [`plugins/codeclone/`](https://github.com/orenlab/codeclone/tree/main/plugins/codeclone)                                     | Native discovery, two skills, and MCP definition   |
 
diff --git a/docs/book/21-vscode-extension.md b/docs/book/21-vscode-extension.md
@@ -8,6 +8,8 @@ Document the current contract and behavior of the VS Code extension shipped in
 This chapter describes the extension as an interface layer over existing
 CodeClone contracts. It does not define a second analysis truth model.
 
+Marketplace: [orenlab.codeclone](https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone)
+
 ## Position in the platform
 
 The VS Code extension is:
@@ -120,6 +122,9 @@ The extension runs as a workspace extension and requires:
 - a local `codeclone-mcp` launcher, or an explicitly configured launcher
 - CodeClone `2.0.0b4` or newer
 
+In `auto` mode, launcher resolution prefers the current workspace virtualenv
+before `PATH`.
+
 For this reason:
 
 - Restricted Mode support is `limited`
diff --git a/docs/claude-desktop-bundle.md b/docs/claude-desktop-bundle.md
@@ -11,7 +11,7 @@ production-first structural review.
 ## Install
 
 ```bash
-uv tool install "codeclone[mcp]"    # or: uv pip install "codeclone[mcp]"
+uv tool install --pre "codeclone[mcp]"    # or: uv pip install --pre "codeclone[mcp]"
 codeclone-mcp --help                # verify
 ```
 
diff --git a/docs/codex-plugin.md b/docs/codex-plugin.md
@@ -16,7 +16,7 @@ Repo-local discovery via `.agents/plugins/marketplace.json`.
 ## Install
 
 ```bash
-uv tool install "codeclone[mcp]"    # or: uv pip install "codeclone[mcp]"
+uv tool install --pre "codeclone[mcp]"    # or: uv pip install --pre "codeclone[mcp]"
 codeclone-mcp --help                # verify
 ```
 
diff --git a/docs/mcp.md b/docs/mcp.md
@@ -10,9 +10,9 @@ Works with any MCP-capable client regardless of backend model.
 ## Install
 
 ```bash
-uv tool install "codeclone[mcp]"    # install as a standalone tool
+uv tool install --pre "codeclone[mcp]"    # install as a standalone tool
 # or, inside an existing environment
-uv pip install "codeclone[mcp]"     # add the MCP extra to that environment
+uv pip install --pre "codeclone[mcp]"     # add the MCP extra to that environment
 ```
 
 ## Quick client setup
@@ -246,7 +246,10 @@ All clients use the same server — only the registration format differs.
   "mcpServers": {
     "codeclone": {
       "command": "codeclone-mcp",
-      "args": ["--transport", "stdio"]
+      "args": [
+        "--transport",
+        "stdio"
+      ]
     }
   }
 }
@@ -274,13 +277,13 @@ If `codeclone-mcp` is not on `PATH`, use an absolute path to the launcher.
 
 ## Troubleshooting
 
-| Problem                                                   | Fix                                                                            |
-|-----------------------------------------------------------|--------------------------------------------------------------------------------|
-| `CodeClone MCP support requires the optional 'mcp' extra` | `uv tool install "codeclone[mcp]"` or `uv pip install "codeclone[mcp]"`        |
-| Client cannot find `codeclone-mcp`                        | `uv tool install "codeclone[mcp]"` or use an absolute launcher path            |
-| Client only accepts remote MCP                            | Use `streamable-http` transport                                                |
-| Agent reads stale results                                 | Call `analyze_repository` again; `latest` always points to the most recent run |
-| `changed_paths` rejected                                  | Pass a `list[str]` of repo-relative paths, not a comma-separated string        |
+| Problem                                                   | Fix                                                                                 |
+|-----------------------------------------------------------|-------------------------------------------------------------------------------------|
+| `CodeClone MCP support requires the optional 'mcp' extra` | `uv tool install --pre "codeclone[mcp]"` or `uv pip install --pre "codeclone[mcp]"` |
+| Client cannot find `codeclone-mcp`                        | `uv tool install --pre "codeclone[mcp]"` or use an absolute launcher path           |
+| Client only accepts remote MCP                            | Use `streamable-http` transport                                                     |
+| Agent reads stale results                                 | Call `analyze_repository` again; `latest` always points to the most recent run      |
+| `changed_paths` rejected                                  | Pass a `list[str]` of repo-relative paths, not a comma-separated string             |
 
 ## See also
 
diff --git a/docs/vscode-extension.md b/docs/vscode-extension.md
@@ -6,6 +6,8 @@ CodeClone ships a preview VS Code extension in
 It is a native IDE surface over `codeclone-mcp` and is designed for
 baseline-aware, triage-first structural review inside the editor.
 
+Marketplace: [CodeClone for VS Code](https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone)
+
 ## What it is for
 
 The extension helps you:
@@ -27,16 +29,19 @@ The extension needs a local `codeclone-mcp` launcher.
 
 Minimum supported CodeClone version: `2.0.0b4`.
 
+In `auto` mode, it checks the current workspace virtualenv before falling back
+to `PATH`.
+
 Recommended install for the preview extension:
 
 ```bash
-uv tool install "codeclone[mcp]>=2.0.0b4"
+uv tool install --pre "codeclone[mcp]"
 ```
 
 If you want the launcher inside the current environment instead:
 
 ```bash
-uv pip install "codeclone[mcp]>=2.0.0b4"
+uv pip install --pre "codeclone[mcp]"
 ```
 
 Verify the launcher:
diff --git a/extensions/claude-desktop-codeclone/README.md b/extensions/claude-desktop-codeclone/README.md
@@ -9,14 +9,14 @@ Read-only, baseline-aware, local stdio only.
 ## Install
 
 ```bash
-uv tool install "codeclone[mcp]"
-codeclone-mcp --help                # verify launcher
+uv tool install --pre "codeclone[mcp]"
+codeclone-mcp --help                       # verify launcher
 ```
 
 If you want to keep the launcher inside an existing environment instead, use:
 
 ```bash
-uv pip install "codeclone[mcp]"
+uv pip install --pre "codeclone[mcp]"
 ```
 
 Build and install the bundle:
diff --git a/extensions/vscode-codeclone/CHANGELOG.md b/extensions/vscode-codeclone/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Change Log
 
+## 0.2.1
+
+- refresh packaged extension metadata for prerelease validation
+
 ## 0.2.0
 
 - add a native preview VS Code extension for `codeclone-mcp`
diff --git a/extensions/vscode-codeclone/README.md b/extensions/vscode-codeclone/README.md
@@ -2,6 +2,8 @@
 
 CodeClone for VS Code is a native IDE surface for `codeclone-mcp`.
 
+Marketplace: [CodeClone for VS Code](https://marketplace.visualstudio.com/items?itemName=orenlab.codeclone)
+
 It brings CodeClone's baseline-aware structural analysis into the editor without
 creating a second truth model. The extension stays read-only with respect to
 repository state and uses the same canonical report semantics as the CLI, HTML
@@ -42,16 +44,19 @@ CodeClone for VS Code needs a local `codeclone-mcp` launcher.
 
 Minimum supported CodeClone version: `2.0.0b4`.
 
+In `auto` mode, the extension checks the current workspace virtualenv before
+falling back to `PATH`.
+
 Recommended install for the preview extension:
 
 ```bash
-uv tool install "codeclone[mcp]>=2.0.0b4"
+uv tool install --pre "codeclone[mcp]"
 ```
 
 If you want the launcher inside the current environment instead:
 
 ```bash
-uv pip install "codeclone[mcp]>=2.0.0b4"
+uv pip install --pre "codeclone[mcp]"
 ```
 
 Verify the launcher:
diff --git a/extensions/vscode-codeclone/package-lock.json b/extensions/vscode-codeclone/package-lock.json
diff --git a/extensions/vscode-codeclone/package.json b/extensions/vscode-codeclone/package.json
@@ -2,7 +2,7 @@
   "name": "codeclone",
   "displayName": "CodeClone",
   "description": "Baseline-aware, triage-first structural review for Python, powered by CodeClone MCP.",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "preview": true,
   "publisher": "orenlab",
   "license": "MPL-2.0",
diff --git a/extensions/vscode-codeclone/src/extension.js b/extensions/vscode-codeclone/src/extension.js
@@ -78,11 +78,14 @@ const {
     isMinimumSupportedCodeCloneVersion,
     resolveAnalysisSettings,
     sameAnalysisSettings,
+    locationsNeedDetailHydration,
     normalizedLaunchSpec,
     parseUtcTimestamp,
+    revealLineSpan,
     resolveWorkspacePath,
     signedInteger,
     staleMessage,
+    unsupportedVersionMessage,
     workspaceLocalLauncherCandidates,
 } = require("./support");
 
@@ -570,6 +573,7 @@ class CodeCloneController {
                 command: configuredCommand,
                 args: Array.isArray(configuredArgs) ? configuredArgs : [],
                 cwd: folder.uri.fsPath,
+                source: "configured",
             });
         }
         const candidates = workspaceLocalLauncherCandidates(folder.uri.fsPath);
@@ -585,18 +589,21 @@ class CodeCloneController {
                 command: localLauncher,
                 args: Array.isArray(configuredArgs) ? configuredArgs : [],
                 cwd: folder.uri.fsPath,
+                source: "workspaceLocal",
             });
         }
         const primary = /** @type {any} */ (normalizedLaunchSpec({
             command: "codeclone-mcp",
             args: Array.isArray(configuredArgs) ? configuredArgs : [],
             cwd: folder.uri.fsPath,
+            source: "path",
         }));
         primary.fallback = (await looksLikeCodeCloneRepo(folder.uri.fsPath))
             ? normalizedLaunchSpec({
                 command: "uv",
                 args: ["run", "codeclone-mcp"],
                 cwd: folder.uri.fsPath,
+                source: "uvFallback",
             })
             : null;
         return primary;
@@ -647,7 +654,11 @@ class CodeCloneController {
             this.updateContextKeys();
             this.updateStatusBar();
             throw new MCPClientError(
-                `The local CodeClone MCP server is not supported. It reported version ${reportedVersion}; this extension requires CodeClone >= ${MINIMUM_SUPPORTED_CODECLONE_VERSION}.`
+                unsupportedVersionMessage(
+                    reportedVersion,
+                    MINIMUM_SUPPORTED_CODECLONE_VERSION,
+                    effectiveLaunchSpec
+                )
             );
         }
         this.updateContextKeys();
@@ -1148,16 +1159,31 @@ class CodeCloneController {
         if (!state) {
             return null;
         }
-        let locations = normalizeFindingLocations(state.folder, activeNode.locations);
-        let detailPayload = null;
-        if (locations.length === 0) {
+        let detailPayload =
+            activeNode.detailPayload && typeof activeNode.detailPayload === "object"
+                ? activeNode.detailPayload
+                : null;
+        let locations = detailPayload
+            ? normalizeFindingLocations(state.folder, detailPayload.locations)
+            : normalizeFindingLocations(state.folder, activeNode.locations);
+        if (
+            !detailPayload ||
+            locations.length === 0 ||
+            locationsNeedDetailHydration(activeNode.locations)
+        ) {
             await this.ensureConnected(state.folder);
             detailPayload = await this.client.callTool("get_finding", {
                 run_id: activeNode.runId,
                 finding_id: activeNode.findingId,
                 detail_level: "normal",
             });
-            locations = normalizeFindingLocations(state.folder, detailPayload.locations);
+            const detailLocations = normalizeFindingLocations(
+                state.folder,
+                detailPayload.locations
+            );
+            if (detailLocations.length > 0) {
+                locations = detailLocations;
+            }
         }
         const resolved = {
             ...activeNode,
@@ -1932,18 +1958,17 @@ class CodeCloneController {
                 preview: true,
             });
             if (typeof line === "number") {
-                const startLine = Math.max(line - 1, 0);
-                const finalLine = Math.max(
-                    typeof endLine === "number" ? endLine - 1 : startLine,
-                    startLine
-                );
-                const position = new vscode.Position(startLine, 0);
+                const span = revealLineSpan(line, endLine, document.lineCount);
+                if (!span) {
+                    return;
+                }
+                const position = new vscode.Position(span.startLine, 0);
                 const endPosition = new vscode.Position(
-                    finalLine,
-                    document.lineAt(finalLine).range.end.character
+                    span.finalLine,
+                    document.lineAt(span.finalLine).range.end.character
                 );
                 const range = new vscode.Range(position, endPosition);
-                editor.selection = new vscode.Selection(position, position);
+                editor.selection = new vscode.Selection(position, endPosition);
                 editor.revealRange(range, vscode.TextEditorRevealType.InCenter);
                 this.flashRevealRange(editor, range);
             }
diff --git a/extensions/vscode-codeclone/src/support.js b/extensions/vscode-codeclone/src/support.js
diff --git a/extensions/vscode-codeclone/test/support.test.js b/extensions/vscode-codeclone/test/support.test.js
diff --git a/plugins/codeclone/README.md b/plugins/codeclone/README.md
