From 494ea2c03136b1b76731d2a74e4662745e47ca13 Mon Sep 17 00:00:00 2001 From: sunerpy Date: Sun, 16 Aug 2026 19:06:47 +0800 Subject: [PATCH] feat(zed): rename the extension id and reap superseded binaries MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Zed registry requires an extension id that conveys what the extension does; the bare `codegraph` only qualifies under the exception for widely known tooling, which does not apply. Rename to `mcp-server-codegraph`: the registry carries 44 `mcp-server-*` entries and no `*-mcp-server` ones, and an id cannot be changed after publication. The `[context_servers.codegraph]` key stays. It is not required to match the extension id — the published `chrome-devtools-mcp` declares a different one — and `codegraph install` plus every hand-written Zed config already reference `context_servers.codegraph`. Reap superseded `codegraph-*` version dirs after a successful download so the extension work directory stops growing with every release. The reap is gated on the download path, so a cache hit never runs it; it is prefix-scoped, so unrelated state survives; and removal is best-effort, so a directory that cannot be deleted never fails a launch. --- README.md | 33 ++++++++-------- editors/zed/Cargo.lock | 2 +- editors/zed/Cargo.toml | 2 +- editors/zed/README.md | 79 +++++++++++++++++++++++--------------- editors/zed/extension.toml | 6 +-- editors/zed/src/lib.rs | 27 ++++++++++--- 6 files changed, 92 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index fdc70c8d..b0e5ab12 100644 --- a/README.md +++ b/README.md @@ -294,18 +294,14 @@ needed. ### Install -**Preferred — official registry (once published):** +**Preferred — official registry:** Search for **"CodeGraph"** in Zed's extension registry (`zed: extensions` from the -command palette) and click Install. The extension auto-downloads the CodeGraph +command palette) and click Install. It is listed as **CodeGraph MCP Server** +(extension ID `mcp-server-codegraph`). The extension auto-downloads the CodeGraph binary for your platform on first launch. -> The extension is being submitted to the -> [`zed-industries/extensions`](https://github.com/zed-industries/extensions) -> registry. Once accepted it will be searchable there. Until then, use the -> dev-install path below. - -**Dev install (before publication / for local development):** +**Dev install (for local development):** 1. Clone this repository. 2. In Zed, open the command palette and run **`zed: install dev extension`**. @@ -326,22 +322,29 @@ codegraph-/codegraph # Linux / macOS codegraph-/codegraph.exe # Windows ``` -This path is **relative to the extension's working directory** that Zed manages -(inside Zed's extensions data directory, typically -`~/.local/share/zed/extensions/installed/codegraph/` on Linux, -`~/Library/Application Support/Zed/extensions/installed/codegraph/` on macOS, or -`%APPDATA%\Zed\extensions\installed\codegraph\` on Windows). +This path is **relative to the extension's working directory** that Zed manages, +which is keyed on the extension ID: typically +`~/.local/share/zed/extensions/work/mcp-server-codegraph/` on Linux, +`~/Library/Application Support/Zed/extensions/work/mcp-server-codegraph/` on +macOS, or `%LOCALAPPDATA%\Zed\extensions\work\mcp-server-codegraph\` on Windows. For example, after downloading version `v0.25.0` on Linux the binary lives at: ``` -~/.local/share/zed/extensions/installed/codegraph/codegraph-v0.25.0/codegraph +~/.local/share/zed/extensions/work/mcp-server-codegraph/codegraph-v0.25.0/codegraph ``` When the CodeGraph CLI ships a new release the extension picks up the new binary automatically on the next launch — **no extension re-publish or manual update required**. If the GitHub API is unreachable, the extension falls back to the -newest cached binary it finds. +binary it has already cached. + +Right after each successful download the extension removes the other +`codegraph-*/` directories in that working directory, so the cache keeps exactly +one binary instead of one per release. A launch that hits the cache does no +cleanup, the in-use version is always kept, and a directory that cannot be +deleted (an in-use `codegraph.exe` on Windows) never fails the launch. See +[`editors/zed/README.md`](editors/zed/README.md) for the full cleanup contract. ### Override with your own binary diff --git a/editors/zed/Cargo.lock b/editors/zed/Cargo.lock index d8a726fe..699b2eea 100644 --- a/editors/zed/Cargo.lock +++ b/editors/zed/Cargo.lock @@ -40,7 +40,7 @@ checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" [[package]] name = "codegraph-zed" -version = "0.1.0" +version = "0.2.0" dependencies = [ "zed_extension_api", ] diff --git a/editors/zed/Cargo.toml b/editors/zed/Cargo.toml index 355c1d9e..e6a5176d 100644 --- a/editors/zed/Cargo.toml +++ b/editors/zed/Cargo.toml @@ -5,7 +5,7 @@ # oracle, and guardrail are entirely unaffected. Never published to crates.io. [package] name = "codegraph-zed" -version = "0.1.0" +version = "0.2.0" edition = "2021" publish = false diff --git a/editors/zed/README.md b/editors/zed/README.md index f8c11e3f..49f0c40f 100644 --- a/editors/zed/README.md +++ b/editors/zed/README.md @@ -11,18 +11,14 @@ AI/LLM inside it — pure pre-computed structure for your agent to consume. ## Install -### Preferred — official registry (once published) +### Preferred — official registry Search for **"CodeGraph"** in Zed's extension registry (`zed: extensions` from -the command palette) and click Install. The extension auto-downloads the -CodeGraph binary for your platform on first launch. +the command palette) and click Install. It is listed as **CodeGraph MCP Server** +(extension ID `mcp-server-codegraph`). The extension auto-downloads the CodeGraph +binary for your platform on first launch. -> The extension is being submitted to the -> [`zed-industries/extensions`](https://github.com/zed-industries/extensions) -> registry. Once accepted it will be searchable there. Until then, use the -> dev-install path below. - -### Dev install (before publication / for local development) +### Dev install (for local development) 1. Clone this repository. 2. In Zed, run **`zed: install dev extension`** from the command palette. @@ -48,26 +44,44 @@ codegraph-/codegraph # Linux / macOS codegraph-/codegraph.exe # Windows ``` -This path is **relative to the extension's working directory** that Zed manages -(inside Zed's extensions data directory). The full on-disk location is: +This path is **relative to the extension's working directory** that Zed manages — +`/extensions/work/mcp-server-codegraph/`, keyed on the extension +ID. The full on-disk location is: -| Platform | Full path | -| -------- | ------------------------------------------------------------------------------------------------ | -| Linux | `~/.local/share/zed/extensions/installed/codegraph/codegraph-/codegraph` | -| macOS | `~/Library/Application Support/Zed/extensions/installed/codegraph/codegraph-/codegraph` | -| Windows | `%APPDATA%\Zed\extensions\installed\codegraph\codegraph-\codegraph.exe` | +| Platform | Full path | +| -------- | ------------------------------------------------------------------------------------------------------ | +| Linux | `~/.local/share/zed/extensions/work/mcp-server-codegraph/codegraph-/codegraph` | +| macOS | `~/Library/Application Support/Zed/extensions/work/mcp-server-codegraph/codegraph-/codegraph` | +| Windows | `%LOCALAPPDATA%\Zed\extensions\work\mcp-server-codegraph\codegraph-\codegraph.exe` | For example, after downloading version `v0.25.0` on Linux the binary lives at: ``` -~/.local/share/zed/extensions/installed/codegraph/codegraph-v0.25.0/codegraph +~/.local/share/zed/extensions/work/mcp-server-codegraph/codegraph-v0.25.0/codegraph ``` Because the cache is keyed on the release version, when the CodeGraph CLI ships a new release the extension picks up the new binary automatically on the next launch — **no extension re-publish or manual update required**. If the GitHub -API is unreachable (offline), the extension falls back to the newest binary it -has already cached. +API is unreachable (offline), the extension falls back to the binary it has +already cached. + +### Cleanup of superseded binaries + +Immediately after a successful download the extension deletes every other +`codegraph-*/` directory in its working directory, so the cache holds exactly one +CodeGraph binary rather than accumulating one per release. Details: + +- It runs **only after a download**. A launch that finds the wanted version + already cached does no filesystem cleanup at all. +- Only entries whose name starts with `codegraph-` are considered, and the + version currently in use is always kept. +- Deletion is best-effort. A directory that cannot be removed (for example an + in-use `codegraph.exe` on Windows) is left in place and never fails the + server launch; the next update retries it. + +To reclaim the space by hand instead, delete the `codegraph-*` directories under +the working-directory path in the table above. ## Use your own CodeGraph binary or pin a project path @@ -158,35 +172,36 @@ To submit this extension to the official [`zed-industries/extensions`](https://github.com/zed-industries/extensions) registry so users can install it via `zed: extensions`, follow these steps: -1. **Bump the version** in `editors/zed/extension.toml` to match the current - CodeGraph release (e.g. `version = "0.2.0"`). +1. **Bump the version** in `editors/zed/extension.toml` (and `Cargo.toml`, in + lockstep) whenever the extension's WASM logic changes. 2. **Fork** [`zed-industries/extensions`](https://github.com/zed-industries/extensions). -3. **Add this repo as a git submodule** under `extensions/codegraph/`: +3. **Add this repo as a git submodule** under `extensions/mcp-server-codegraph/`: ```bash - git submodule add https://github.com/sunerpy/codegraph-rust extensions/codegraph + git submodule add https://github.com/sunerpy/codegraph-rust extensions/mcp-server-codegraph ``` The registry expects the extension root (containing `extension.toml`) at - `extensions/codegraph/editors/zed/`, so point the submodule at the repo root - and Zed's tooling walks for the manifest. - - > Alternatively, if the registry requires the extension root at the submodule - > root, extract just `editors/zed/` into a dedicated repo first and submodule - > that instead. + `extensions/mcp-server-codegraph/editors/zed/`, so point the submodule at the + repo root and declare that subdirectory as the extension `path`. 4. **Add an entry** to the top-level `extensions.toml` in the `zed-industries/extensions` repo: ```toml - [codegraph] - submodule = "extensions/codegraph" + [mcp-server-codegraph] + submodule = "extensions/mcp-server-codegraph" + path = "editors/zed" version = "0.2.0" ``` - The `id` field (`codegraph`) must match the `id` in `extension.toml`. + The table key (`mcp-server-codegraph`) must match the `id` in + `extension.toml`. Registry policy requires MCP-server extensions to carry an + `mcp-server` prefix or suffix in that ID; the ID **cannot be changed after + publication**, so discoverability by the plain word "codegraph" comes from the + `name` field (`CodeGraph MCP Server`), which Zed also searches. 5. **Open a pull request** against `zed-industries/extensions`. The Zed team reviews and merges it; once merged the extension becomes searchable in Zed's diff --git a/editors/zed/extension.toml b/editors/zed/extension.toml index 45e21e76..7fc3f723 100644 --- a/editors/zed/extension.toml +++ b/editors/zed/extension.toml @@ -1,7 +1,7 @@ -id = "codegraph" -name = "CodeGraph" +id = "mcp-server-codegraph" +name = "CodeGraph MCP Server" description = "CodeGraph deterministic code knowledge graph as an MCP context server" -version = "0.1.0" +version = "0.2.0" schema_version = 1 authors = ["sunerpy "] repository = "https://github.com/sunerpy/codegraph-rust" diff --git a/editors/zed/src/lib.rs b/editors/zed/src/lib.rs index be0aea5a..8cc65ce2 100644 --- a/editors/zed/src/lib.rs +++ b/editors/zed/src/lib.rs @@ -63,11 +63,11 @@ impl CodeGraphExtension { format!("{}/{}", Self::version_dir(version), Self::binary_name()) } - /// Newest existing `./codegraph-*/codegraph[.exe]` on disk, if any. Used as - /// an offline fallback when `latest_github_release` fails. "Newest" is by - /// lexicographically-greatest directory name, which matches semantic order - /// for the zero-padded-free `vX.Y.Z` tags this project uses well enough as - /// a best-effort offline fallback. + /// The cached `./codegraph-*/codegraph[.exe]` on disk, if any. Used as an + /// offline fallback when `latest_github_release` fails. `resolve_binary` + /// reaps superseded version dirs after each download, so in practice at most + /// one candidate survives; the sort is a vestigial tie-break for a cache + /// left behind by an older extension build. fn newest_cached_binary() -> Option { let name = Self::binary_name(); let mut candidates: Vec = std::fs::read_dir(".") @@ -133,6 +133,23 @@ impl CodeGraphExtension { zed::download_file(&asset.download_url, &version_dir, file_type)?; zed::make_file_executable(&binary_path)?; + // Reap superseded version dirs so the cache does not grow without bound. + // Placement is load-bearing: only a successful download reaches here, so + // a cache hit never reaps. The `codegraph-` gate spares unrelated state + // Zed may keep here, and removal is `.ok()` rather than `?` because an + // undeletable dir (an in-use `.exe` on Windows) must not fail a launch. + let entries = std::fs::read_dir(".") + .map_err(|err| format!("failed to list the extension working directory: {err}"))?; + for entry in entries { + let entry = + entry.map_err(|err| format!("failed to read a working directory entry: {err}"))?; + if let Some(name) = entry.file_name().to_str() { + if name.starts_with("codegraph-") && name != version_dir { + std::fs::remove_dir_all(entry.path()).ok(); + } + } + } + self.cached_binary_path = Some(binary_path.clone()); Ok(binary_path) }