feat(release): publish a linux-arm64 engine (#20)

* feat(release): publish a linux-arm64 engine

ARM Linux users had no engine at all: platformBinaryName() returned null
for linux-arm64, so npm's postinstall printed "unsupported platform" and
exited, and the JetBrains resolver refused too. Issue #15 came from one of
the few people who worked around that by building from source.

Adds the asset to both client mappings and to the release, and pins how it
is built:

scripts/build-linux-arm64.sh builds in a container because there is no
arm64 Linux build machine, and the compatibility floor is easy to get
wrong. It does not only build - it refuses to produce a binary that would
narrow support:

  - __libc_single_threaded must land in writable memory. An immutable
    definition is read-only and, on aarch64, also exported, so glibc's
    startup write to it faults before main(). That was issue #15, and this
    is its regression guard.
  - the glibc floor must stay <= 2.30 and GLIBCXX <= 3.4.29, the floors
    measured from the shipped x64 asset.

Ubuntu 20.04 + gcc-11 is the only combination measured to give both a
working link and those floors. The alternatives failed and the reasons are
recorded in the script: Debian 11 (gcc 10) cannot resolve ONNX Runtime's
__throw_bad_array_new_length or __aarch64_cas8_sync; SLES 15 SP4's own
gcc11 ships no outline atomics; Ubuntu 22.04 links but floors at glibc
2.34, which would have given ARM a narrower support range than x64.

Verified by running the built binary: it works on SLES 15 SP4, Ubuntu
22.04+, Debian 12+, RHEL 9+ and Amazon Linux 2023, and not on Ubuntu
20.04, Debian 11, RHEL 8 or Amazon Linux 2 - identical to the x64 asset.
Note the binding constraint is GLIBCXX_3.4.29, not glibc, which is why it
does not run on its own build host.

Also collapses three hand-kept copies of the platform list into one.
PUBLISHED_BINARIES in bin/fetch-engine.js is now the source of truth, read
by publish-release-assets.sh and package-npm.sh, so a sixth platform
cannot be published without every client resolving it - the drift that
made this change touch five files. A `while read` loop rather than
mapfile: these scripts run under macOS's bash 3.2, where mapfile does not
exist and would have silently yielded an empty list.

The two tests asserting linux-arm64 was unsupported are inverted rather
than deleted; both languages now assert it resolves to its own asset and
never to the x64 one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rVbt7rENTwXkdHt3Bpgb5

* docs: state the platform support matrix, including both Linux floors

The project published no platform requirements anywhere users could read
them, while the internal build notes claimed a Linux range that was wrong.
A user on RHEL 8 hitting `GLIBCXX_3.4.29 not found` had nothing to consult.

Two floors matter and only one of them is obvious. glibc 2.30 is not the
binding constraint: the engine embeds ONNX Runtime, built with GCC 11, so
it also needs libstdc++ >= GLIBCXX_3.4.29. Checking only glibc is what
produced the earlier claim that Debian 11 and Ubuntu 20.04 were supported;
both ship 3.4.28 and have never been able to start the engine.

The runs / does-not-run table is measured by executing the 0.20.1 binaries
on each distribution, not inferred from symbol versions, and is identical
for linux-x64 and linux-arm64. Also documents linux-arm64 as supported,
and gives the GLIBCXX error the remedy that does not require a distro
upgrade.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017rVbt7rENTwXkdHt3Bpgb5

* no-mistakes(review): gate arm64 build provenance, harden shim check, fix stale docs

* no-mistakes(review): record source commit per asset and gate release on agreement

* no-mistakes(document): correct stale engine platform counts in client docs

* no-mistakes(document): replace dangling build-notes pointers, correct engine download sizes

* no-mistakes(lint): restore vscode eslint config, clear resulting lint errors

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: anvanster

README.md

@@ -405,6 +405,42 @@ A single Rust binary serves both MCP and LSP protocols.
 
 ---
 
+## Supported platforms
+
+The engine is a native binary, downloaded for your platform on first run.
+
+| Platform | Architectures |
+|---|---|
+| macOS | Apple Silicon (arm64) and Intel (x64) |
+| Linux | x64 and arm64 |
+| Windows | x64 (Windows on ARM runs the x64 build under emulation) |
+
+**Linux requires glibc 2.30 or newer *and* a libstdc++ from GCC 11 or newer
+(`GLIBCXX_3.4.29`).** The second requirement is the binding one, and it is not
+implied by the first — the engine embeds ONNX Runtime, which is built with
+GCC 11.
+
+| Runs | Does not run |
+|---|---|
+| SLES 15 SP4 | Ubuntu 20.04 |
+| Ubuntu 22.04 and newer | Debian 11 |
+| Debian 12 and newer | RHEL / CentOS 8 |
+| RHEL 9 and newer | Amazon Linux 2 |
+| Amazon Linux 2023 | |
+
+Both Linux architectures have identical requirements. If the engine exits
+immediately with a message like
+
+```
+version `GLIBCXX_3.4.29' not found (required by codegraph-server)
+```
+
+the distribution's C++ runtime is older than the engine needs; installing a
+newer `libstdc++` (for example RHEL 8's `gcc-toolset-11`) resolves it without
+upgrading the distribution.
+
+---
+
 ## Building from Source
 
 ```bash

jetbrains/README.md

@@ -39,8 +39,8 @@ the dependency ever becomes a problem.
 ## Engine resolution
 
 The plugin does **not** bundle engine binaries, and neither does any other
-client any more: bundling all four platforms meant a ~120 MB download for the
-one binary a given user can actually run.
+client any more: bundling every platform meant a download several times the size
+of the one binary a given user can actually run.
 The engine is published once as GitHub release assets and each client fetches
 what its platform needs, into the shared `~/.codegraph/bin`.
 

jetbrains/src/main/kotlin/ai/codegraph/jetbrains/indexing/IndexingStartupActivity.kt

@@ -38,7 +38,7 @@ class IndexingStartupActivity : ProjectActivity {
 
         val resolved = CodeGraphServerResolver.resolve(project.basePath, settings.serverPath)
         if (resolved == null) {
-            // Offered rather than done automatically: this is a ~30 MB download
+            // Offered rather than done automatically: this is a ~120 MB download
             // of a native binary that will run with the user's permissions, and
             // starting that unasked on project open is not a decision the
             // plugin should make for them.

jetbrains/src/main/kotlin/ai/codegraph/jetbrains/server/CodeGraphServerResolver.kt

@@ -59,13 +59,13 @@ data class ResolverEnvironment(
 /**
  * Locates the `codegraph-server` engine binary.
  *
- * Resolution order mirrors `vscode/src/server.ts`, with one deliberate
- * difference: the JetBrains plugin does not bundle platform binaries. The VSIX
- * carries four of them (100-126 MB each) because VS Code can ship per-platform
- * artifacts; the JetBrains Marketplace cannot, so a bundled plugin would be a
- * ~120 MB download for every user regardless of platform. Instead the binary is
- * resolved from an existing install and, failing that, downloaded once into the
- * managed install directory (Phase 1).
+ * Resolution order mirrors `vscode/src/server.ts`. No client bundles platform
+ * binaries any more (each engine is 100-126 MB), and the case against it is
+ * strongest here: VS Code could at least ship one artifact per platform, while
+ * the JetBrains Marketplace serves a single artifact to everyone, so a bundled
+ * plugin would carry every published engine to every user. Instead the binary
+ * is resolved from an existing install and, failing that, downloaded once into
+ * the managed install directory (Phase 1).
  *
  * Order:
  *  1. Explicit user override (settings)
@@ -83,14 +83,18 @@ object CodeGraphServerResolver {
     /**
      * Binary name for this platform, or null when no engine is published for it.
      *
-     * Only macOS is built for both architectures. Windows on ARM runs the x64
-     * build under the OS's own emulation layer, so it is served the x64 asset;
-     * Linux has no such layer, and falling back to x64 there installs ~30 MB
-     * that cannot execute, which surfaces as an exec-format error at first use
-     * instead of as the unsupported platform it is.
+     * macOS and Linux are both built for x64 and arm64, and are answered by
+     * exact platform-arch match and nothing else: falling back to x64 on an
+     * arm64 machine installs ~120 MB that cannot execute, which surfaces as an
+     * exec-format error at first use instead of as the unsupported platform it
+     * is. Windows on ARM is the one exception - it runs the x64 build under the
+     * OS's own emulation layer, so refusing it would leave those users with no
+     * engine at all.
      *
      * Mirrors `platformBinaryName()` in `mcp-package/bin/fetch-engine.js`, which
-     * is the same rule for the JavaScript channels.
+     * is the same rule for the JavaScript channels. The plugin cannot import
+     * that list, so this mapping has to be edited in lockstep with it whenever a
+     * platform is added or dropped.
      */
     fun platformBinaryNameOrNull(env: ResolverEnvironment = ResolverEnvironment.fromSystem()): String? {
         val os = env.osName.lowercase()
@@ -104,7 +108,11 @@ object CodeGraphServerResolver {
                 else -> null
             }
             os.contains("win") -> if (isX64 || isArm64) "codegraph-server-win32-x64.exe" else null
-            os.contains("linux") -> if (isX64) "codegraph-server-linux-x64" else null
+            os.contains("linux") -> when {
+                isArm64 -> "codegraph-server-linux-arm64"
+                isX64 -> "codegraph-server-linux-x64"
+                else -> null
+            }
             else -> null
         }
     }

jetbrains/src/main/kotlin/ai/codegraph/jetbrains/server/EngineDownloader.kt

@@ -18,11 +18,11 @@ import java.util.Locale
  * Fetches the engine for this platform into the managed install directory.
  *
  * The plugin does not bundle engines: the JetBrains Marketplace serves one
- * artifact to every platform, so bundling all four would mean a ~120 MB
- * download for every user to obtain the ~30 MB they can run. The alternative
- * for users without Node is worse - install a 498 MB npm package for one
- * binary - so the engine is fetched directly from the release that
- * `scripts/publish-release-assets.sh` produces.
+ * artifact to every platform, so bundling every published engine would mean a
+ * download several times the size of the one a given user can run. Sending
+ * users to the npm package instead is not an answer either: it needs Node, and
+ * it fetches the same engine from the same release. So the engine is fetched
+ * directly from the release that `scripts/publish-release-assets.sh` produces.
  *
  * Downloads are verified against the checksum published beside each asset. An
  * engine is a native binary that runs with the user's permissions; TLS says

jetbrains/src/test/kotlin/ai/codegraph/jetbrains/server/CodeGraphServerResolverTest.kt

@@ -160,18 +160,19 @@ class CodeGraphServerResolverTest : BasePlatformTestCase() {
         }
     }
 
-    fun `test arm64 linux has no published engine but arm64 windows emulates x64`() {
-        // Handing the x64 asset to an arm64 Linux machine installs something
-        // that cannot execute, which shows up as an exec-format error rather
-        // than as the missing build it is. Windows on ARM is the exception: it
-        // runs x64 binaries under the OS's own emulation, so refusing there
-        // would leave those users with no engine for no reason.
+    fun `test arm64 linux gets its own engine and arm64 windows emulates x64`() {
+        // Linux arm64 has its own published build, so it must resolve to that
+        // and never to the x64 asset: handing x64 to an arm64 machine installs
+        // something that cannot execute, which shows up as an exec-format error
+        // rather than as the wrong build it is. Windows on ARM is the
+        // exception - it runs x64 under the OS's own emulation, so refusing
+        // there would leave those users with no engine for no reason.
         fun nameFor(os: String, arch: String) = CodeGraphServerResolver.platformBinaryNameOrNull(
             ResolverEnvironment(fakeHome, emptyList(), os, arch),
         )
 
-        assertNull(nameFor("Linux", "aarch64"))
-        assertNull(nameFor("Linux", "arm64"))
+        assertEquals("codegraph-server-linux-arm64", nameFor("Linux", "aarch64"))
+        assertEquals("codegraph-server-linux-arm64", nameFor("Linux", "arm64"))
         assertEquals("codegraph-server-win32-x64.exe", nameFor("Windows 11", "aarch64"))
         assertEquals("codegraph-server-win32-x64.exe", nameFor("Windows 11", "arm64"))
         assertEquals("codegraph-server-linux-x64", nameFor("Linux", "x86_64"))

jetbrains/src/test/kotlin/ai/codegraph/jetbrains/server/EngineDownloaderTest.kt

@@ -64,9 +64,12 @@ class EngineDownloaderTest : BasePlatformTestCase() {
         ResolverEnvironment(homeDir = home, pathEntries = emptyList(), osName = os, osArch = arch)
 
     /**
-     * Windows and Linux are published for x64 only, so an arm64 environment
-     * there is an unsupported platform rather than a machine that downloads the
-     * x64 build.
+     * Defaults to arm64 because that is the machine these tests describe: macOS
+     * and Linux each publish their own arm64 engine, and Windows on ARM is
+     * served the x64 one it emulates. The Windows cases below pass `amd64`
+     * explicitly so they read as the platform they are testing rather than
+     * relying on that fallback. Which name each pair resolves to is
+     * `CodeGraphServerResolverTest`'s subject, not this file's.
      */
     private fun downloader(os: String, arch: String = "aarch64") =
         EngineDownloader(env(os, arch), baseUrl())
@@ -81,6 +84,21 @@ class EngineDownloaderTest : BasePlatformTestCase() {
         assertTrue("the engine must be executable", path.toFile().canExecute())
     }
 
+    fun `test an arm64 linux ide installs the arm64 engine`() {
+        // The platform this channel gained. Both Linux assets are published, so
+        // a mapping that fell back to x64 would install cleanly here and only
+        // fail when the IDE tried to start the engine - which is why the whole
+        // download is exercised and not just the name it resolves to.
+        publish("0.20.1", "codegraph-server-linux-arm64", "arm64 engine".toByteArray())
+        publish("0.20.1", "codegraph-server-linux-x64", "x64 engine".toByteArray())
+
+        val path = downloader("Linux").download("0.20.1")
+
+        assertEquals("codegraph-server-linux-arm64", path.fileName.toString())
+        assertEquals("arm64 engine", Files.readString(path))
+        assertTrue("the engine must be executable", path.toFile().canExecute())
+    }
+
     fun `test windows also installs the runtime library the engine loads`() {
         publish("0.19.1", "codegraph-server-win32-x64.exe", "engine".toByteArray())
         publish("0.19.1", EngineDownloader.WINDOWS_SIDECAR, "onnx".toByteArray())

mcp-package/bin/fetch-engine.js

@@ -113,6 +113,32 @@ const ARCH_MAP = { arm64: "arm64", x64: "x64", x86_64: "x64" };
  */
 const VERSION_MARKER = ".engine-version";
 
+/**
+ * Every engine binary a release publishes.
+ *
+ * This is the single list for everything that can reach it. publish-release-
+ * assets.sh uploads exactly these and package-npm.sh probes exactly these, both
+ * by reading this export rather than repeating it - hand-kept copies of the same
+ * list are how a release ends up publishing a platform no client asks for, or
+ * asking for one it never published.
+ *
+ * One copy cannot be removed: `CodeGraphServerResolver.platformBinaryNameOrNull`
+ * in the JetBrains plugin is Kotlin and cannot import this file, so it restates
+ * the same rule and has to be edited alongside this list. Its own test asserts
+ * the mapping; nothing can cross-check the two automatically.
+ *
+ * `onnxruntime.dll` is deliberately absent: it is a sidecar of the Windows
+ * engine, not an engine, and requiredAssets() is what decides when it is
+ * needed.
+ */
+const PUBLISHED_BINARIES = [
+  "codegraph-server-darwin-arm64",
+  "codegraph-server-darwin-x64",
+  "codegraph-server-linux-arm64",
+  "codegraph-server-linux-x64",
+  "codegraph-server-win32-x64.exe",
+];
+
 /**
  * Asset name for the running platform, matching the names
  * publish-release-assets.sh uploads. Returns null when unsupported, so callers
@@ -122,16 +148,16 @@ function platformBinaryName(platform = os.platform(), arch = os.arch()) {
   const p = PLATFORM_MAP[platform];
   const a = ARCH_MAP[arch];
   if (!p || !a) return null;
-  // macOS is the only platform published for both architectures.
-  if (p === "darwin") return `codegraph-server-darwin-${a}`;
   // Windows on ARM runs x64 executables under the OS's own emulation layer, so
   // the x64 asset is the correct answer there and refusing it would leave those
-  // users with no engine at all.
+  // users with no engine at all. Linux and macOS have no such layer, so they
+  // are answered by exact platform-arch match and nothing else: handing an x64
+  // build to an arm64 machine installs ~120 MB that cannot execute, which
+  // surfaces as an exec-format error at first use rather than as the
+  // unsupported platform it is.
   if (p === "win32") return "codegraph-server-win32-x64.exe";
-  // Linux has no such layer. Handing the x64 build to an arm64 machine installs
-  // ~30 MB that cannot execute, which surfaces as an exec-format error at first
-  // use rather than as the unsupported platform it is.
-  return a === "x64" ? "codegraph-server-linux-x64" : null;
+  const name = `codegraph-server-${p}-${a}`;
+  return PUBLISHED_BINARIES.includes(name) ? name : null;
 }
 
 /** Numeric release components, or null when [version] is not one. */
@@ -415,6 +441,7 @@ async function ensureEngine(version, targetDir, options = {}) {
 module.exports = {
   RELEASE_BASE,
   ENGINE_VERSION,
+  PUBLISHED_BINARIES,
   WINDOWS_SIDECAR,
   VERSION_MARKER,
   EngineInUseError,

mcp-package/test/fetch-engine.test.js

@@ -27,6 +27,7 @@ const {
   ensureEngine,
   requiredAssets,
   platformBinaryName,
+  PUBLISHED_BINARIES,
   redirectTarget,
   installedVersion,
   compareVersions,
@@ -109,6 +110,39 @@ async function run() {
     }
   }
 
+  // --- an arm64 linux machine installs the arm64 engine ----------------
+  // The whole install, not just the name mapping: before linux-arm64 was
+  // published this threw, and the failure worth guarding against now is the
+  // quiet one - the x64 asset is served alongside, so a rule that fell back to
+  // it would install cleanly here and only fail when the user tried to run it.
+  {
+    const dir = scratch();
+    const release = await startRelease({
+      "codegraph-server-linux-arm64": { content: "arm64 engine" },
+      "codegraph-server-linux-x64": { content: "x64 engine" },
+    });
+    try {
+      const { binary, fetched } = await ensureEngine(VERSION, dir, {
+        platform: "linux",
+        arch: "arm64",
+        baseUrl: release.baseUrl,
+      });
+      check(
+        path.basename(binary) === "codegraph-server-linux-arm64",
+        "an arm64 linux install fetches the arm64 engine"
+      );
+      check(fs.readFileSync(binary, "utf8") === "arm64 engine", "and it is the arm64 build");
+      check(
+        fetched.length === 1 && !fs.existsSync(path.join(dir, "codegraph-server-linux-x64")),
+        "and nothing else, least of all the x64 build"
+      );
+      check(installedVersion(dir) === VERSION, "and the release it came from is recorded");
+    } finally {
+      release.server.close();
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+
   // --- a corrupted download installs nothing ---------------------------
   {
     const dir = scratch();
@@ -412,8 +446,12 @@ async function run() {
   // --- only published platform/arch pairs resolve to an asset ----------
   // An x64 asset handed to an arm64 Linux machine downloads and chmods cleanly
   // and then fails to exec, which is far harder to read than "not published".
-  // Windows on ARM is the exception: it emulates x64, so the x64 build runs.
-  check(platformBinaryName("linux", "arm64") === null, "linux-arm64 has no published engine");
+  // Linux arm64 now has its own build, so it must resolve to that one and never
+  // to the x64 asset. Windows on ARM stays the exception: it emulates x64.
+  check(
+    platformBinaryName("linux", "arm64") === "codegraph-server-linux-arm64",
+    "linux-arm64 resolves to its own engine, not the x64 one"
+  );
   check(
     platformBinaryName("win32", "arm64") === "codegraph-server-win32-x64.exe",
     "win32-arm64 uses the x64 engine, which Windows emulates"
@@ -427,7 +465,30 @@ async function run() {
     "darwin-arm64 does"
   );
   check(platformBinaryName("linux", "x64") === "codegraph-server-linux-x64", "linux-x64 does");
-  check(requiredAssets("linux", "arm64").length === 0, "an unpublished pair needs no assets");
+  check(
+    requiredAssets("linux", "arm64").length === 1 &&
+      requiredAssets("linux", "arm64")[0] === "codegraph-server-linux-arm64",
+    "linux-arm64 needs the engine and no sidecar"
+  );
+  // A platform with no build must still resolve to nothing rather than to
+  // someone else's binary.
+  check(platformBinaryName("linux", "riscv64") === null, "an unbuilt arch resolves to nothing");
+  check(requiredAssets("linux", "riscv64").length === 0, "an unpublished pair needs no assets");
+  // Every name the mapping can return has to be a name the release publishes,
+  // or an install fetches a 404.
+  for (const [p, a] of [
+    ["darwin", "arm64"],
+    ["darwin", "x64"],
+    ["linux", "arm64"],
+    ["linux", "x64"],
+    ["win32", "x64"],
+  ]) {
+    const name = platformBinaryName(p, a);
+    check(
+      PUBLISHED_BINARIES.includes(name),
+      `${p}-${a} resolves to a published asset (${name})`
+    );
+  }
 
   console.log("");
   console.log(`${failures} failure(s)`);