@saluzi/codegraph 0.1.0 → 0.2.1

package/scripts/extract-release-notes.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Extract a release-notes block from CHANGELOG.md for a given version
+ * (or unwrap text supplied on stdin), then join hard-wrapped paragraphs.
+ *
+ * Why: GitHub renders release-note Markdown with GFM hard breaks, so
+ * every `\n` becomes `<br>`. The CHANGELOG is hard-wrapped at ~75
+ * chars for readable diffs, which then renders as awkward visible
+ * line breaks on the release page. This script joins indented
+ * continuation lines into a single line per bullet so the GFM
+ * renderer produces clean paragraphs.
+ *
+ * Repo-level CHANGELOG.md viewing is unaffected (CommonMark treats
+ * newlines as spaces there).
+ *
+ * Usage:
+ *   extract-release-notes.mjs <version>     # read CHANGELOG.md
+ *   extract-release-notes.mjs --stdin       # read from stdin (any text)
+ */
+
+import { readFileSync } from 'fs';
+
+const arg = process.argv[2];
+if (!arg) {
+  console.error('usage: extract-release-notes.mjs <version> | --stdin');
+  process.exit(1);
+}
+
+let block;
+if (arg === '--stdin') {
+  block = readFileSync(0, 'utf8').replace(/\r\n?/g, '\n').split('\n');
+} else {
+  const version = arg;
+  const escaped = version.replace(/\./g, '\\.');
+  const headerRe = new RegExp(`^## \\[${escaped}\\]`);
+  const anyHeaderRe = /^## \[/;
+  const lines = readFileSync('CHANGELOG.md', 'utf8').split('\n');
+  const start = lines.findIndex((l) => headerRe.test(l));
+  if (start === -1) {
+    console.error(`no '## [${version}]' entry found in CHANGELOG.md`);
+    process.exit(1);
+  }
+  const after = lines.findIndex((l, i) => i > start && anyHeaderRe.test(l));
+  block = lines.slice(start, after === -1 ? lines.length : after);
+}
+
+// Track a stack of `{ indent: number }` frames so a continuation line
+// can attach to the right ancestor. Handles the post-nested-list
+// continuation pattern:
+//
+//     - top-level
+//         - nested
+//       back to top-level  <- 2-space indent, joins the top-level bullet
+const out = [];
+let buf = '';
+let stack = [];
+
+function flushBuf() {
+  if (buf !== '') {
+    out.push(buf);
+    buf = '';
+  }
+}
+
+function leadingSpaces(s) {
+  const m = s.match(/^(\s*)/);
+  return m ? m[1].length : 0;
+}
+
+// Bullets: `-`, `*`, `digit.` only. `+` is intentionally excluded — the
+// CHANGELOG uses literal `+` inline (`config + instructions`) and we
+// don't want to misread those as nested bullets.
+const listItemRe = /^(\s*)([-*]|\d+\.)\s+/;
+const fenceRe = /^\s*```/;
+
+let inFence = false;
+
+for (const line of block) {
+  // Fenced code blocks: pass through verbatim, no joining.
+  if (fenceRe.test(line)) {
+    flushBuf();
+    stack = [];
+    out.push(line);
+    inFence = !inFence;
+    continue;
+  }
+  if (inFence) {
+    out.push(line);
+    continue;
+  }
+  if (/^\s*$/.test(line)) {
+    flushBuf();
+    out.push('');
+    continue;
+  }
+  if (/^#/.test(line)) {
+    flushBuf();
+    stack = [];
+    out.push(line);
+    continue;
+  }
+  const itemMatch = line.match(listItemRe);
+  if (itemMatch) {
+    flushBuf();
+    const indent = itemMatch[1].length;
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    stack.push({ indent });
+    buf = line;
+    continue;
+  }
+  if (/^\s/.test(line)) {
+    const indent = leadingSpaces(line);
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      flushBuf();
+      stack.pop();
+    }
+    const trimmed = line.replace(/^\s+/, '');
+    buf = buf === '' ? trimmed : `${buf} ${trimmed}`;
+    continue;
+  }
+  flushBuf();
+  stack = [];
+  out.push(line);
+}
+flushBuf();
+
+process.stdout.write(out.join('\n'));
+if (!out[out.length - 1]?.endsWith('\n')) process.stdout.write('\n');

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 @colbymchenry/codegraph (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("@colbymchenry/codegraph")` 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
+//   @colbymchenry/codegraph-<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 = '@colbymchenry/codegraph-' + 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(
+    'codegraph: 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 @colbymchenry/codegraph --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx @colbymchenry/codegraph 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;
+}

package/scripts/npm-shim.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+'use strict';
+//
+// npm thin-installer launcher for CodeGraph.
+//
+// The heavy artifact (a vendored Node runtime + the app) ships as a per-platform
+// optionalDependency: @colbymchenry/codegraph-<platform>-<arch>. npm installs
+// only the one matching the host, via each package's `os`/`cpu` fields (the
+// esbuild pattern). This shim — run by the user's OWN Node — locates that bundle
+// and execs its launcher, so the real work always runs on the bundled Node 24
+// (with node:sqlite), regardless of the user's Node version. The user's Node is
+// only ever a launcher; even an ancient version can run this file.
+//
+// Self-heal (issue #303): some registries — notably the npmmirror/cnpm mirrors,
+// and some corporate proxies — don't reliably mirror the per-platform
+// optionalDependencies. npm treats an unfetchable optional dep as success and
+// silently skips it, so the bundle goes missing and every command fails. When
+// the installed bundle can't be resolved, this shim falls back to downloading
+// the matching bundle straight from GitHub Releases — the very archive
+// install.sh uses — into a cache dir, then runs that. Knobs:
+//   CODEGRAPH_NO_DOWNLOAD=1     disable the network fallback (print guidance)
+//   CODEGRAPH_INSTALL_DIR=DIR   cache location (default: ~/.codegraph)
+//   CODEGRAPH_DOWNLOAD_BASE=URL release-download base (for mirrors/air-gapped)
+//
+// Wired up at release time as the main package's `bin`:
+//   "bin": { "codegraph": "npm-shim.js" }
+// with the platform packages listed in `optionalDependencies`.
+
+var childProcess = require('child_process');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@colbymchenry/codegraph-' + target;
+var isWindows = process.platform === 'win32';
+var REPO = 'colbymchenry/codegraph';
+
+main().catch(function (e) {
+  process.stderr.write('codegraph: ' + (e && e.message ? e.message : String(e)) + '\n');
+  process.exit(1);
+});
+
+async function main() {
+  // Happy path: the npm-installed optional dependency. Fall back to a download
+  // when the registry didn't deliver it.
+  var resolved = resolveInstalledBundle() || (await selfHealBundle());
+  // Thread the MCP host's pid (our parent) down to the bundled server so its
+  // orphan watchdog can poll the host directly. Without this, the server can
+  // only watch THIS shim — and a shim killed during the server's first ~100ms
+  // of startup used to leave the server orphaned forever (issue #1185). An
+  // already-set value (an outer launcher) wins.
+  var env = Object.assign({}, process.env);
+  if (!env.CODEGRAPH_HOST_PPID) env.CODEGRAPH_HOST_PPID = String(process.ppid);
+  var res = childProcess.spawnSync(resolved.command, resolved.args, { stdio: 'inherit', windowsHide: true, env: env });
+  if (res.error) {
+    process.stderr.write('codegraph: ' + res.error.message + '\n');
+    process.exit(1);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+// Resolve the launcher from the installed per-platform optionalDependency.
+// Returns {command, args} or null if the package isn't installed.
+function resolveInstalledBundle() {
+  try {
+    if (isWindows) {
+      // Modern Node refuses to spawn the bundle's .cmd directly (EINVAL, the
+      // CVE-2024-27980 hardening on Node 24), so invoke the bundled node.exe
+      // against the app entry point and pass --liftoff-only here.
+      var nodeExe = require.resolve(pkg + '/node.exe');
+      var entry = require.resolve(pkg + '/lib/dist/bin/codegraph.js');
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+    return { command: require.resolve(pkg + '/bin/codegraph'), args: process.argv.slice(2) };
+  } catch (e) {
+    return null;
+  }
+}
+
+// Locate the launcher inside an extracted GitHub bundle directory (same
+// node/lib/bin layout as the npm platform package). Returns {command, args} or
+// null when the directory doesn't hold a usable bundle yet.
+function launcherIn(dir) {
+  if (isWindows) {
+    var nodeExe = path.join(dir, 'node.exe');
+    var entry = path.join(dir, 'lib', 'dist', 'bin', 'codegraph.js');
+    if (fs.existsSync(nodeExe) && fs.existsSync(entry)) {
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+  } else {
+    var launcher = path.join(dir, 'bin', 'codegraph');
+    if (fs.existsSync(launcher)) return { command: launcher, args: process.argv.slice(2) };
+  }
+  return null;
+}
+
+// --liftoff-only keeps tree-sitter's WASM grammars off V8's turboshaft tier to
+// avoid the Zone OOM on Node >= 22 (issues #293/#298). The unix bin/codegraph
+// launcher already passes it; on Windows we invoke node.exe directly so add it.
+function liftoff(entry) {
+  return ['--liftoff-only', entry].concat(process.argv.slice(2));
+}
+
+// Download + cache the platform bundle from GitHub Releases. Returns
+// {command, args}; exits the process with guidance if it can't.
+async function selfHealBundle() {
+  var version = readVersion();
+  var bundlesDir = path.join(process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph'), 'bundles');
+  var dest = path.join(bundlesDir, target + '-' + version);
+
+  // Already downloaded by a previous run? Use it even when downloads are
+  // disabled — CODEGRAPH_NO_DOWNLOAD blocks fetching, not a cached bundle.
+  var cached = launcherIn(dest);
+  if (cached) { pruneOldBundles(bundlesDir, dest); return cached; }
+
+  if (process.env.CODEGRAPH_NO_DOWNLOAD) {
+    fail('the network fallback is disabled (CODEGRAPH_NO_DOWNLOAD is set).');
+  }
+
+  var asset = 'codegraph-' + target + (isWindows ? '.zip' : '.tar.gz');
+  var base = process.env.CODEGRAPH_DOWNLOAD_BASE || ('https://github.com/' + REPO + '/releases/download');
+  var url = base + '/v' + version + '/' + asset;
+
+  process.stderr.write(
+    'codegraph: platform bundle missing (registry did not provide ' + pkg + ').\n' +
+    'codegraph: downloading ' + asset + ' from GitHub Releases (' + version + ')...\n'
+  );
+
+  // Stage inside bundlesDir so the final rename is on the same filesystem (atomic,
+  // no EXDEV across tmpfs). Strip the archive's top-level codegraph-<target>/ dir.
+  fs.mkdirSync(bundlesDir, { recursive: true });
+  var stage = fs.mkdtempSync(path.join(bundlesDir, '.dl-'));
+  try {
+    var archivePath = path.join(stage, asset);
+    await download(url, archivePath, 6);
+    await verifyChecksum(archivePath, asset, base, version);
+    var extracted = path.join(stage, 'bundle');
+    fs.mkdirSync(extracted);
+    extract(archivePath, extracted);
+
+    var raced = launcherIn(dest); // another process may have finished meanwhile
+    if (raced) { rmrf(stage); return raced; }
+    try {
+      fs.renameSync(extracted, dest);
+    } catch (e) {
+      var other = launcherIn(dest); // lost the race but theirs is valid
+      if (other) { rmrf(stage); return other; }
+      throw e;
+    }
+  } catch (e) {
+    rmrf(stage);
+    fail('download failed (' + e.message + ').\n  URL: ' + url);
+  }
+  rmrf(stage);
+
+  var ready = launcherIn(dest);
+  if (!ready) fail('downloaded bundle is missing its launcher under ' + dest + '.');
+  pruneOldBundles(bundlesDir, dest);
+  process.stderr.write('codegraph: bundle ready.\n');
+  return ready;
+}
+
+function readVersion() {
+  try {
+    return require(path.join(__dirname, 'package.json')).version;
+  } catch (e) {
+    fail('could not read this package\'s version to locate a matching release.');
+  }
+}
+
+// GET with manual redirect following (GitHub release URLs redirect to a CDN).
+function download(url, dest, redirectsLeft) {
+  return new Promise(function (resolve, reject) {
+    var https = require('https');
+    // timeout is an idle/inactivity timeout — it won't kill a slow-but-progressing
+    // download, only a stalled connection (so a blocked mirror fails fast with
+    // guidance instead of hanging the user's command forever).
+    var req = https.get(url, { headers: { 'User-Agent': 'codegraph-npm-shim' }, timeout: 30000 }, function (res) {
+      var status = res.statusCode;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) { reject(new Error('too many redirects')); return; }
+        download(new URL(res.headers.location, url).toString(), dest, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) { res.resume(); reject(new Error('HTTP ' + status)); return; }
+      var file = fs.createWriteStream(dest);
+      res.on('error', reject);
+      res.pipe(file);
+      file.on('error', reject);
+      file.on('finish', function () { file.close(function () { resolve(); }); });
+    });
+    req.on('timeout', function () { req.destroy(new Error('connection timed out')); });
+    req.on('error', reject);
+  });
+}
+
+// Best-effort integrity check. When the release publishes a SHA256SUMS file, the
+// downloaded archive MUST match its listed hash or we abort. When that file is
+// absent (older releases) or simply unreachable, we proceed — the archive still
+// arrived from GitHub over TLS. So tampering/corruption is caught, while a
+// missing checksum never breaks an install.
+async function verifyChecksum(archivePath, asset, base, version) {
+  var sumsPath = archivePath + '.SHA256SUMS';
+  try {
+    await download(base + '/v' + version + '/SHA256SUMS', sumsPath, 6);
+  } catch (e) {
+    return; // not published / unreachable → skip
+  }
+  var expected = null;
+  var lines = fs.readFileSync(sumsPath, 'utf8').split('\n');
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (m && path.basename(m[2].trim()) === asset) { expected = m[1].toLowerCase(); break; }
+  }
+  if (!expected) return; // asset not listed → nothing to check
+  var actual = require('crypto').createHash('sha256').update(fs.readFileSync(archivePath)).digest('hex');
+  if (actual !== expected) {
+    throw new Error('checksum mismatch for ' + asset +
+      ' (expected ' + expected.slice(0, 12) + '…, got ' + actual.slice(0, 12) + '…)');
+  }
+  process.stderr.write('codegraph: checksum verified.\n');
+}
+
+// Extract via the system tar — present on macOS, Linux, and Windows 10+
+// (bsdtar reads .zip too). No third-party dependency in the shim.
+function extract(archive, destDir) {
+  var args = isWindows
+    ? ['-xf', archive, '-C', destDir, '--strip-components=1']
+    : ['-xzf', archive, '-C', destDir, '--strip-components=1'];
+  var res = childProcess.spawnSync('tar', args, { stdio: 'ignore', windowsHide: true });
+  if (res.error) throw new Error('tar unavailable: ' + res.error.message);
+  if (res.status !== 0) throw new Error('tar exited ' + res.status);
+}
+
+function rmrf(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) { /* best effort */ }
+}
+
+// Drop sibling bundles for OTHER versions of this same platform target, keeping
+// only keepDir. The self-heal cache otherwise accumulates a full ~50 MB bundle
+// per version forever (issue #1074). Best-effort: a locked/busy dir (a
+// concurrent run still mapping an older node.exe on Windows) just stays — rmrf
+// already swallows its own errors, and the readdir is guarded — so cleanup can
+// never break a working command. Only this target's "<target>-<version>" dirs
+// are touched; other platforms' bundles and the ".dl-*" staging dirs are left
+// alone.
+function pruneOldBundles(bundlesDir, keepDir) {
+  var keep = path.basename(keepDir);
+  try {
+    var names = fs.readdirSync(bundlesDir);
+    for (var i = 0; i < names.length; i++) {
+      var name = names[i];
+      if (name === keep) continue;
+      if (name.indexOf(target + '-') !== 0) continue;
+      rmrf(path.join(bundlesDir, name));
+    }
+  } catch (e) { /* best effort — never break a working run over cleanup */ }
+}
+
+function fail(reason) {
+  process.stderr.write(
+    'codegraph: no prebuilt bundle for ' + target + '.\n' +
+    (reason ? 'codegraph: ' + reason + '\n' : '') +
+    'Expected the optional package ' + pkg + ' to be installed.\n' +
+    'A registry mirror (e.g. npmmirror/cnpm) that did not mirror the per-platform\n' +
+    'package is the usual cause. Fixes:\n' +
+    '  - install from the official registry:\n' +
+    '      npm i -g @colbymchenry/codegraph --registry=https://registry.npmjs.org\n' +
+    '  - or use the standalone installer (no Node required):\n' +
+    '      curl -fsSL https://raw.githubusercontent.com/' + REPO + '/main/install.sh | sh\n'
+  );
+  process.exit(1);
+}

package/scripts/pack-npm.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Assemble the npm thin-installer packages from built bundles (esbuild pattern).
+#
+# Produces, under release/npm/:
+#   codegraph-<target>/   one per built bundle — the vendored Node + app, tagged
+#                         with os/cpu so npm installs only the matching one.
+#   main/                 the @colbymchenry/codegraph shim package: a tiny bin
+#                         that execs the matching platform bundle, with every
+#                         platform package in optionalDependencies.
+#
+# The release pipeline then `npm publish`es each dir. This does NOT touch the
+# repo's package.json — the dev/from-source path keeps working; the *published*
+# main package's shape is generated here.
+#
+# Prereq: run build-bundle.sh for each target first (release/codegraph-*.tar.gz).
+# Usage:  scripts/pack-npm.sh [version]    (default: version from package.json)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="${1:-$(node -p "require('$ROOT/package.json').version")}"
+SCOPE="@colbymchenry"
+REL="$ROOT/release"
+NPM="$REL/npm"
+
+rm -rf "$NPM"
+mkdir -p "$NPM/main"
+
+shopt -s nullglob
+archives=("$REL"/codegraph-*.tar.gz "$REL"/codegraph-*.zip)
+[ ${#archives[@]} -gt 0 ] || { echo "[pack-npm] no bundles in $REL — run build-bundle.sh first" >&2; exit 1; }
+
+targets=()
+for archive in "${archives[@]}"; do
+  fname="$(basename "$archive")"
+  case "$fname" in
+    *.tar.gz) base="${fname%.tar.gz}" ;;   # codegraph-<target>
+    *.zip)    base="${fname%.zip}" ;;
+  esac
+  target="${base#codegraph-}"             # <target>, e.g. darwin-arm64 / win32-x64
+  os="${target%-*}"                       # darwin | linux | win32
+  arch="${target##*-}"                    # arm64 | x64
+  pkgdir="$NPM/$base"
+  mkdir -p "$pkgdir"
+  case "$fname" in
+    *.zip)
+      tmpx="$(mktemp -d)"
+      unzip -q "$archive" -d "$tmpx"
+      mv "$tmpx/codegraph-${target}"/* "$pkgdir"/
+      rm -rf "$tmpx"
+      nodefile="node.exe"
+      ;;
+    *)
+      tar -xzf "$archive" -C "$pkgdir" --strip-components=1
+      nodefile="node"
+      ;;
+  esac
+  VERSION="$VERSION" SCOPE="$SCOPE" TARGET="$target" OSV="$os" ARCHV="$arch" NODEFILE="$nodefile" \
+    node -e '
+      const fs=require("fs");
+      fs.writeFileSync(process.argv[1], JSON.stringify({
+        name: `${process.env.SCOPE}/codegraph-${process.env.TARGET}`,
+        version: process.env.VERSION,
+        description: `CodeGraph self-contained bundle for ${process.env.TARGET}`,
+        os: [process.env.OSV], cpu: [process.env.ARCHV],
+        files: [process.env.NODEFILE, "lib", "bin"],
+        license: "MIT"
+      }, null, 2) + "\n");
+    ' "$pkgdir/package.json"
+  targets+=("$target")
+  echo "[pack-npm] ${SCOPE}/codegraph-${target}@${VERSION}"
+done
+
+# Main shim package.
+#   npm-shim.js  CLI/MCP launcher (execs the bundled Node) — the `bin`.
+#   npm-sdk.js   programmatic/embedded entry (#354): re-exports the installed
+#                platform bundle's compiled library — the `main`.
+#   dist/        the .d.ts tree only (types). The runtime .js stays in the
+#                per-platform bundle so its deps aren't duplicated here.
+cp "$ROOT/scripts/npm-shim.js" "$NPM/main/npm-shim.js"
+cp "$ROOT/scripts/npm-sdk.js" "$NPM/main/npm-sdk.js"
+[ -f "$ROOT/README.md" ] && cp "$ROOT/README.md" "$NPM/main/README.md"
+
+# Ship the type declarations so `types`/`exports.types` resolve. Built from this
+# same release, so they can't skew from the runtime npm-sdk.js re-exports.
+[ -f "$ROOT/dist/index.d.ts" ] || ( echo "[pack-npm] building dist for .d.ts" >&2 && cd "$ROOT" && npm run build >/dev/null )
+ROOT="$ROOT" DEST="$NPM/main" node -e '
+  const fs=require("fs"), path=require("path");
+  const src=path.join(process.env.ROOT,"dist"), dest=path.join(process.env.DEST,"dist");
+  fs.cpSync(src, dest, { recursive:true, filter(s){
+    try { return fs.statSync(s).isDirectory() || s.endsWith(".d.ts"); } catch (e) { return false; }
+  }});
+'
+
+VERSION="$VERSION" SCOPE="$SCOPE" TARGETS="${targets[*]}" \
+  node -e '
+    const fs=require("fs");
+    const opt={};
+    for (const t of process.env.TARGETS.split(/\s+/).filter(Boolean))
+      opt[`${process.env.SCOPE}/codegraph-${t}`]=process.env.VERSION;
+    fs.writeFileSync(process.argv[1], JSON.stringify({
+      name: `${process.env.SCOPE}/codegraph`,
+      version: process.env.VERSION,
+      description: "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
+      bin: { codegraph: "npm-shim.js" },
+      main: "npm-sdk.js",
+      types: "dist/index.d.ts",
+      exports: {
+        ".": { types: "./dist/index.d.ts", default: "./npm-sdk.js" },
+        "./package.json": "./package.json"
+      },
+      optionalDependencies: opt,
+      files: ["npm-shim.js","npm-sdk.js","dist","README.md"],
+      license: "MIT"
+    }, null, 2) + "\n");
+  ' "$NPM/main/package.json"
+
+echo "[pack-npm] ${SCOPE}/codegraph@${VERSION} (${#targets[@]} platform packages in optionalDependencies)"
+echo "[pack-npm] output: $NPM"