@ltm-alpha/alpha-cs 1.6.0

package/scripts/go-rebrand.mjs

@@ -0,0 +1,114 @@
+import fs from "fs";
+import path from "path";
+const ROOT = process.cwd();
+const SKIP_DIRS = new Set(["node_modules", ".git", "ltm-alpha-cs-kernel"]);
+
+function shouldSkip(p) {
+  const rel = path.relative(ROOT, p);
+  return rel.split(path.sep).some(s => SKIP_DIRS.has(s));
+}
+
+const replacements = [
+  ["Alpha Code Sense", "Alpha Code Sense"],
+  ["alpha_cs_explore", "alpha_cs_explore"],
+  ["alpha_cs_node", "alpha_cs_node"],
+  ["alpha_cs_search", "alpha_cs_search"],
+  ["alpha_cs_callers", "alpha_cs_callers"],
+  ["alpha_cs_callees", "alpha_cs_callees"],
+  ["alpha_cs_impact", "alpha_cs_impact"],
+  ["alpha_cs_files", "alpha_cs_files"],
+  ["alpha_cs_status", "alpha_cs_status"],
+  ["alpha_cs_affected", "alpha_cs_affected"],
+  ["alpha_cs_context", "alpha_cs_context"],
+  ["alpha_cs_query", "alpha_cs_query"],
+  ["alpha_cs_sync", "alpha_cs_sync"],
+  ["alpha_cs_serve", "alpha_cs_serve"],
+  ["alpha_cs_upgrade", "alpha_cs_upgrade"],
+  ["alpha_cs_uninstall", "alpha_cs_uninstall"],
+  ["alpha_cs_install", "alpha_cs_install"],
+  ["alpha_cs_uninit", "alpha_cs_uninit"],
+  ["alpha_cs_daemon", "alpha_cs_daemon"],
+  ["alpha_cs_hook", "alpha_cs_hook"],
+  ["alpha_cs_init", "alpha_cs_init"],
+  ["alpha_cs_index", "alpha_cs_index"],
+  ["ALPHA_CS_VERSION", "ALPHA_CS_VERSION"],
+  ["ALPHA_CS_INSTALL_DIR", "ALPHA_CS_INSTALL_DIR"],
+  ["ALPHA_CS_BIN_DIR", "ALPHA_CS_BIN_DIR"],
+  ["ALPHA_CS_NO_DAEMON", "ALPHA_CS_NO_DAEMON"],
+  ["ALPHA_CS_TELEMETRY", "ALPHA_CS_TELEMETRY"],
+  ["ALPHA_CS_HOST_PPID", "ALPHA_CS_HOST_PPID"],
+  ["ALPHA_CS_DIR", "ALPHA_CS_DIR"],
+  ["ALPHA_CS_NO_DOWNLOAD", "ALPHA_CS_NO_DOWNLOAD"],
+  ["ALPHA_CS_DOWNLOAD_BASE", "ALPHA_CS_DOWNLOAD_BASE"],
+  ["ALPHA_CS_WAL_VALVE_MB", "ALPHA_CS_WAL_VALVE_MB"],
+  ["ALPHA_CS_WAL_HEAL_MB", "ALPHA_CS_WAL_HEAL_MB"],
+  ["ALPHA_CS_MCP_TOOLS", "ALPHA_CS_MCP_TOOLS"],
+  ["ALPHA_CS_NO_WATCH", "ALPHA_CS_NO_WATCH"],
+  ["ALPHA_CS_ASCII", "ALPHA_CS_ASCII"],
+  ["ALPHA_CS_UNICODE", "ALPHA_CS_UNICODE"],
+  ["ALPHA_CS_NO_UPDATE_CHECK", "ALPHA_CS_NO_UPDATE_CHECK"],
+  ["ALPHA_CS_NO_INSTALL_REFRESH", "ALPHA_CS_NO_INSTALL_REFRESH"],
+  ["ALPHA_CS_NO_PROMPT_HOOK", "ALPHA_CS_NO_PROMPT_HOOK"],
+  ["ALPHA_CS_PROMPT_HOOK", "ALPHA_CS_PROMPT_HOOK"],
+  ["ALPHA_CS_NO_UPGRADE", "ALPHA_CS_NO_UPGRADE"],
+  ["ALPHA_CS_PACK_UI", "ALPHA_CS_PACK_UI"],
+  ["LTM/alpha-code-sense", "LTM/alpha-code-sense"],
+  ["@LTM/alpha-code-sense", "@ltm/alpha-cs"],
+  ["alphacodesense.com", "alphacodesense.com"],
+  ["@alphacodesense", "@alphacodesense"],
+  ["alpha-codesense.json", "alpha-codesense.json"],
+  ["alpha-cs.db", "alpha-cs.db"],
+  [".alpha-cs", ".alpha-cs"],
+];
+
+function walk(dir) {
+  for (const e of fs.readdirSync(dir, {withFileTypes:true})) {
+    const p = path.join(dir, e.name);
+    if (shouldSkip(p)) continue;
+    if (e.isDirectory()) { walk(p); continue; }
+    const ext = path.extname(e.name).toLowerCase();
+    if ([".png",".jpg",".jpeg",".gif",".ico",".wasm",".woff",".woff2",".svg"].includes(ext)) continue;
+    if (e.name === "package-lock.json" || e.name === "Cargo.lock") continue;
+    try {
+      let c = fs.readFileSync(p, "utf-8");
+      let changed = false;
+      for (const [from, to] of replacements) {
+        while (c.includes(from)) {
+          c = c.replace(from, to);
+          changed = true;
+        }
+      }
+      if (changed) {
+        fs.writeFileSync(p, c, "utf-8");
+        console.log("  " + path.relative(ROOT, p));
+      }
+    } catch(e) {}
+  }
+}
+
+console.log("=== Rebranding ===\n");
+const oldBin = path.join(ROOT, "src", "bin", "ltm-alpha-cs.ts");
+const newBin = path.join(ROOT, "src", "bin", "ltm-alpha-cs.ts");
+if (fs.existsSync(oldBin)) {
+  fs.renameSync(oldBin, newBin);
+  console.log("Renamed: ltm-alpha-cs.ts -> ltm-alpha-cs.ts");
+}
+walk(ROOT);
+
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf-8"));
+pkg.name = "@ltm/alpha-cs";
+pkg.description = "Alpha Code Sense by LTM - Supercharge AI coding agents.";
+pkg.repository = { type: "git", url: "https://github.com/LTM/alpha-code-sense.git" };
+pkg.bin = { "ltm-alpha-cs": "./dist/bin/ltm-alpha-cs.js" };
+pkg.author = "LTM";
+pkg.keywords = ["code-intelligence", "knowledge-graph", "static-analysis", "alpha-code-sense"];
+delete pkg.workspaces;
+fs.writeFileSync(path.join(ROOT, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
+
+const uiPkgPath = path.join(ROOT, "ui", "package.json");
+const uiPkg = JSON.parse(fs.readFileSync(uiPkgPath, "utf-8"));
+uiPkg.name = "@ltm/alpha-cs-ui";
+delete uiPkg.private;
+fs.writeFileSync(uiPkgPath, JSON.stringify(uiPkg, null, 2) + "\n");
+
+console.log("\nDone");

package/scripts/kernel-parity.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * Kernel↔wasm extraction parity harness (R2/R3 of the kernel migration).
+ *
+ * Runs BOTH extraction paths over the given files/directories and diffs the
+ * per-file ExtractionResults as sets (nodes/edges/refs, canonicalized), so a
+ * behavioral gap in the native kernel shows up as a categorized diff instead
+ * of a graph-dump surprise later. This is the fast inner loop; the §5 gate's
+ * full-repo dump-diff still runs before any default-on.
+ *
+ * Usage:
+ *   node scripts/kernel-parity.mjs <file-or-dir>... [--lang typescript,tsx]
+ *        [--max-samples N] [--list-files] [--max-deferral 0.1]
+ *
+ * --max-deferral: the broken-kernel backstop (default 0.1). For C/C++ pass
+ * 0.5: macro-heavy C/C++ trees genuinely parse with errors at 10–40% file
+ * rates even after the preParse blanking family (git 19%, protobuf 26%, fmt
+ * 42% — measured 2026-07-17), and every erroring file defers BY POLICY, so
+ * the 10% bar calibrated on the 0–0.4% incidence of ts/java/py/go would fail
+ * healthy sweeps. A broken walker still trips 0.5 (it defers ~everything).
+ *
+ * Requires: npm run build (dist/) and a staged kernel (npm run build:kernel).
+ * Exit code: 0 = parity, 1 = diffs found, 2 = setup error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dist = (p) => path.join(ROOT, 'dist', p);
+
+const args = process.argv.slice(2);
+const paths = [];
+let langFilter = null;
+let maxSamples = 5;
+let listFiles = false;
+let maxDeferral = 0.1;
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--lang') langFilter = new Set(args[++i].split(','));
+  else if (args[i] === '--max-samples') maxSamples = Number(args[++i]);
+  else if (args[i] === '--list-files') listFiles = true;
+  else if (args[i] === '--max-deferral') maxDeferral = Number(args[++i]);
+  else paths.push(args[i]);
+}
+if (paths.length === 0) {
+  console.error('usage: kernel-parity.mjs <file-or-dir>... [--lang ts,tsx] [--max-samples N]');
+  process.exit(2);
+}
+
+const KERNEL_LANGS = new Set(['typescript', 'tsx', 'javascript', 'jsx', 'java', 'python', 'go', 'c', 'cpp', 'rust', 'csharp', 'ruby', 'php', 'swift', 'kotlin', 'r', 'lua', 'luau', 'scala', 'dart']);
+const EXTS = new Map([
+  ['.ts', 'typescript'], ['.mts', 'typescript'], ['.cts', 'typescript'],
+  ['.tsx', 'tsx'], ['.js', 'javascript'], ['.mjs', 'javascript'],
+  ['.cjs', 'javascript'], ['.jsx', 'jsx'], ['.java', 'java'], ['.py', 'python'], ['.pyw', 'python'], ['.go', 'go'],
+  // C/C++ (R7a). `.h` needs CONTENT sniffing (C vs C++) — resolved per file
+  // in the run loop via detectLanguage, matching the real indexer's routing.
+  ['.c', 'c'], ['.h', 'detect'],
+  ['.cpp', 'cpp'], ['.cc', 'cpp'], ['.cxx', 'cpp'], ['.hpp', 'cpp'], ['.hxx', 'cpp'],
+  ['.metal', 'cpp'], ['.cu', 'cpp'], ['.cuh', 'cpp'],
+  ['.rs', 'rust'], // R7b
+  ['.cs', 'csharp'], // R7b
+  ['.rb', 'ruby'], ['.rake', 'ruby'], // R7b
+  ['.php', 'php'], ['.module', 'php'], ['.install', 'php'], ['.theme', 'php'], ['.inc', 'php'], // R7b
+  ['.swift', 'swift'], // R7b
+  ['.kt', 'kotlin'], ['.kts', 'kotlin'], // R7b
+  ['.r', 'r'], // R7b batch 4 — real-world casing is `.R`; extname lowercased below
+  ['.lua', 'lua'], ['.luau', 'luau'], // R7b batch 4
+  ['.scala', 'scala'], ['.sc', 'scala'], // R7b batch 4
+  ['.dart', 'dart'], // R7b batch 4
+]);
+
+/** Collect candidate files. */
+function collect(p, out) {
+  let st;
+  try {
+    st = fs.statSync(p); // dangling symlinks (Linux-tree dtc fixtures) throw
+  } catch {
+    return;
+  }
+  if (st.isDirectory()) {
+    const base = path.basename(p);
+    if (base === 'node_modules' || base === '.git' || base === 'dist' || base === '.codegraph') return;
+    for (const e of fs.readdirSync(p)) collect(path.join(p, e), out);
+  } else if (EXTS.has(path.extname(p).toLowerCase())) {
+    // Lowercased to match the real indexer's routing (detectLanguage
+    // lowercases the extension — `.R` is the dominant real-world casing).
+    const lang = EXTS.get(path.extname(p).toLowerCase());
+    // 'detect' (.h) resolves per file in the run loop; under --lang it rides
+    // along whenever either C-family language is requested.
+    const passes =
+      !langFilter ||
+      (lang === 'detect' ? langFilter.has('c') || langFilter.has('cpp') : langFilter.has(lang));
+    if (passes) out.push({ file: p, lang });
+  }
+}
+
+const files = [];
+for (const p of paths) collect(path.resolve(p), files);
+if (files.length === 0) {
+  console.error('no matching files');
+  process.exit(2);
+}
+
+// --- load the built engine ---------------------------------------------------
+const { extractFromSource } = await import(dist('extraction/tree-sitter.js'));
+const { initGrammars, loadGrammarsForLanguages, detectLanguage } = await import(dist('extraction/grammars.js'));
+const kernel = await import(dist('extraction/kernel/index.js'));
+
+await initGrammars();
+await loadGrammarsForLanguages([...KERNEL_LANGS]);
+
+if (!kernel.getKernel()) {
+  console.error('kernel .node not found — run: npm run build:kernel');
+  process.exit(2);
+}
+
+// --- canonicalization ---------------------------------------------------------
+/**
+ * Node identity for cross-referencing edges/refs: the node id itself (both
+ * paths compute the same deterministic ids, and id embeds kind+name+line).
+ */
+function canonNode(n) {
+  const out = {
+    id: n.id, kind: n.kind, name: n.name, qualifiedName: n.qualifiedName,
+    filePath: n.filePath, language: n.language,
+    startLine: n.startLine, endLine: n.endLine,
+    startColumn: n.startColumn, endColumn: n.endColumn,
+  };
+  for (const k of ['docstring', 'signature', 'visibility', 'isExported', 'isAsync', 'isStatic', 'isAbstract', 'returnType']) {
+    if (n[k] !== undefined) out[k] = n[k];
+  }
+  if (n.decorators !== undefined) out.decorators = n.decorators;
+  if (n.typeParameters !== undefined) out.typeParameters = n.typeParameters;
+  return JSON.stringify(out);
+}
+
+function canonEdge(e) {
+  const out = { source: e.source, target: e.target, kind: e.kind };
+  if (e.line !== undefined) out.line = e.line;
+  if (e.column !== undefined) out.column = e.column;
+  if (e.provenance !== undefined) out.provenance = e.provenance;
+  if (e.metadata !== undefined) out.metadata = e.metadata;
+  return JSON.stringify(out);
+}
+
+function canonRef(r) {
+  // FULL object — a field only one path sets is a parity bug (the vitest
+  // parity suite caught decode.ts pre-filling filePath/language this way).
+  const out = {
+    from: r.fromNodeId, name: r.referenceName, kind: r.referenceKind,
+    line: r.line, column: r.column,
+  };
+  for (const k of ['filePath', 'language', 'candidates', 'rowId']) {
+    if (r[k] !== undefined) out[k] = r[k];
+  }
+  return JSON.stringify(out);
+}
+
+function diffSets(aList, bList) {
+  const a = new Map(); // canon -> count (multiset — duplicates matter)
+  const b = new Map();
+  for (const x of aList) a.set(x, (a.get(x) ?? 0) + 1);
+  for (const x of bList) b.set(x, (b.get(x) ?? 0) + 1);
+  const onlyA = [];
+  const onlyB = [];
+  for (const [k, c] of a) {
+    const d = c - (b.get(k) ?? 0);
+    for (let i = 0; i < d; i++) onlyA.push(k);
+  }
+  for (const [k, c] of b) {
+    const d = c - (a.get(k) ?? 0);
+    for (let i = 0; i < d; i++) onlyB.push(k);
+  }
+  return { onlyA, onlyB };
+}
+
+// --- run ----------------------------------------------------------------------
+const buckets = new Map(); // category -> {count, samples[]}
+function report(category, sample) {
+  let b = buckets.get(category);
+  if (!b) buckets.set(category, (b = { count: 0, samples: [] }));
+  b.count++;
+  if (b.samples.length < maxSamples) b.samples.push(sample);
+}
+
+let filesWithDiffs = 0;
+let filesOk = 0;
+let deferred = 0;
+let processed = 0; // collected files minus content-detect skips
+let totals = { nodes: 0, edges: 0, refs: 0 };
+
+process.env.CODEGRAPH_KERNEL_LANGS = 'all';
+
+for (const { file, lang: extLang } of files) {
+  const source = fs.readFileSync(file, 'utf8');
+  const rel = path.relative(ROOT, file);
+  // `.h` resolves C vs C++ by content — the same call the indexer makes.
+  const lang = extLang === 'detect' ? detectLanguage(rel, source) : extLang;
+  if (!KERNEL_LANGS.has(lang)) continue;
+  if (langFilter && !langFilter.has(lang)) continue;
+  processed++;
+
+  delete process.env.CODEGRAPH_KERNEL; // kernel path on
+  const kres = kernel.tryKernelExtract(rel, source, lang);
+  if (!kres) {
+    // Expected: files with parse errors defer to wasm (parity by
+    // construction — both arms run the same extractor). Counted, and
+    // guarded below so a broken kernel can't silently defer everything.
+    deferred++;
+    report('kernel-deferred', rel);
+    continue;
+  }
+  process.env.CODEGRAPH_KERNEL = '0'; // wasm path
+  const wres = extractFromSource(rel, source, lang);
+  delete process.env.CODEGRAPH_KERNEL;
+
+  totals.nodes += wres.nodes.length;
+  totals.edges += wres.edges.length;
+  totals.refs += wres.unresolvedReferences.length;
+
+  let fileHasDiff = false;
+  const tables = [
+    ['node', wres.nodes.map(canonNode), kres.nodes.map(canonNode)],
+    ['edge', wres.edges.map(canonEdge), kres.edges.map(canonEdge)],
+    ['ref', wres.unresolvedReferences.map(canonRef), kres.unresolvedReferences.map(canonRef)],
+  ];
+  for (const [table, wasm, kern] of tables) {
+    const { onlyA, onlyB } = diffSets(wasm, kern);
+    for (const x of onlyA) {
+      fileHasDiff = true;
+      const o = JSON.parse(x);
+      report(`${table}:missing-in-kernel:${o.kind ?? ''}`, `${rel}: ${x}`);
+    }
+    for (const x of onlyB) {
+      fileHasDiff = true;
+      const o = JSON.parse(x);
+      report(`${table}:extra-in-kernel:${o.kind ?? ''}`, `${rel}: ${x}`);
+    }
+    // ORDER matters too: identical multisets in a different emission order
+    // change DB rowids, and resolution iterates refs in rowid order — the
+    // full-index dump-diff would surface it as a downstream mystery. Catch it
+    // here instead.
+    if (onlyA.length === 0 && onlyB.length === 0) {
+      for (let i = 0; i < wasm.length; i++) {
+        if (wasm[i] !== kern[i]) {
+          fileHasDiff = true;
+          report(`${table}:order-mismatch`, `${rel}: index ${i}: wasm=${wasm[i]} kernel=${kern[i]}`);
+          break;
+        }
+      }
+    }
+  }
+  if (fileHasDiff) {
+    filesWithDiffs++;
+    if (listFiles) console.log(`DIFF ${rel}`);
+  } else {
+    filesOk++;
+  }
+}
+
+console.log(`\n=== kernel parity: ${filesOk}/${processed} files byte-parity` +
+  ` (${filesWithDiffs} with diffs, ${deferred} deferred-to-wasm)` +
+  ` | wasm totals: ${totals.nodes} nodes / ${totals.edges} edges / ${totals.refs} refs ===\n`);
+
+const sorted = [...buckets.entries()].sort((a, b) => b[1].count - a[1].count);
+for (const [cat, { count, samples }] of sorted) {
+  console.log(`--- ${cat}: ${count}`);
+  for (const s of samples) console.log(`    ${s.length > 400 ? s.slice(0, 400) + '…' : s}`);
+}
+
+// Deferrals are per-file parse-error routing (expected; rare for most
+// languages, routine for macro-heavy C/C++ — see --max-deferral above). A
+// rate past the threshold means the kernel is broken and hiding behind the
+// fallback — fail loudly.
+const deferralRate = deferred / Math.max(processed, 1);
+if (deferralRate > maxDeferral) {
+  console.error(
+    `deferral rate ${(deferralRate * 100).toFixed(1)}% exceeds ${(maxDeferral * 100).toFixed(0)}% — kernel likely broken`
+  );
+  process.exit(1);
+}
+process.exit(filesWithDiffs > 0 ? 1 : 0);

package/scripts/local-install.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Build the current branch and link it as the global `codegraph` for
+# hands-on testing. Replaces any existing global install for as long
+# as the symlink is in place.
+#
+# Usage:
+#   ./scripts/local-install.sh           # build + link
+#   ./scripts/local-install.sh --undo    # unlink + restore the published version
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+PKG=$(node -p "require('./package.json').name")
+VERSION=$(node -p "require('./package.json').version")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [ "${1:-}" = "--undo" ]; then
+  echo "→ unlinking ${PKG}"
+  npm unlink -g "${PKG}" >/dev/null 2>&1 || true
+  echo "→ reinstalling published ${PKG}"
+  npm install -g "${PKG}"
+  echo "done: global codegraph -> $(command -v codegraph)"
+  exit 0
+fi
+
+echo "→ building ${PKG} ${VERSION} (${BRANCH})"
+npm run build
+
+echo "→ linking globally"
+npm link
+
+LINKED=$(command -v codegraph || echo "(not on PATH)")
+echo
+echo "✓ global codegraph now points to this branch"
+echo "  binary:  ${LINKED}"
+echo "  branch:  ${BRANCH}"
+echo "  version: ${VERSION}"
+echo
+echo "To restore the published version:"
+echo "  ./scripts/local-install.sh --undo"

package/scripts/npm-sdk.js

@@ -0,0 +1,75 @@
+'use strict';
+//
+// Programmatic / embedded SDK entry for @ltm/alpha-cs (issue #354).
+//
+// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
+// the tool never depends on the user's runtime. Embedded library consumers are
+// the opposite case: they already run their own Node and just want the compiled
+// API — `require("@ltm/alpha-cs")` returning the CodeGraph class et al.
+//
+// The compiled library + its production dependencies (web-tree-sitter,
+// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
+//   @ltm/alpha-cs-<platform>-<arch>/lib/dist/index.js
+// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
+// the main package thin — no second 50 MB copy of the grammars — while making the
+// SDK work in the consumer's process. Types are a separate concern: the main
+// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
+// the same release so it can never skew from the runtime it re-exports.
+//
+// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
+// the SQLite adapter — so loading this module is safe on older Node, and the
+// node:sqlite requirement surfaces with an actionable error only when a DB is
+// actually opened. Heavy extraction additionally wants the bundled launcher's
+// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
+// host that drives large indexing should pass that flag to its own Node.
+
+var path = require('path');
+var os = require('os');
+var fs = require('fs');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@ltm-alpha/alpha-cs-' + target;
+
+module.exports = require(resolveLibrary());
+
+// Locate the compiled library entry inside the installed per-platform bundle.
+// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
+// is present, so an embedded consumer knows exactly what to install.
+function resolveLibrary() {
+  // 1) The npm-installed optional dependency — the normal case.
+  try {
+    return require.resolve(pkg + '/lib/dist/index.js');
+  } catch (e) {
+    /* fall through to the self-healed cache */
+  }
+
+  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
+  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
+  //    cached bundle here — unlike the CLI shim we never trigger a network
+  //    download from inside require(), which must stay synchronous and cheap.
+  var cached = cachedLibrary();
+  if (cached) return cached;
+
+  throw new Error(
+    'alpha-cs: the programmatic API is unavailable because the platform bundle\n' +
+    '(' + pkg + ') is not installed.\n' +
+    'The compiled library ships inside that per-platform optional dependency.\n' +
+    'Fixes:\n' +
+    '  - install from the official npm registry so the matching bundle is fetched:\n' +
+    '      npm i @ltm/alpha-cs --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx @ltm/alpha-cs status`) to\n' +
+    '    self-heal the bundle into ~/.codegraph, then require() will find it.'
+  );
+}
+
+function cachedLibrary() {
+  try {
+    var version = require(path.join(__dirname, 'package.json')).version;
+    var base = process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph');
+    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
+    if (fs.existsSync(lib)) return lib;
+  } catch (e) {
+    /* no readable cache → caller reports the install guidance */
+  }
+  return null;
+}