@ltm-alpha/alpha-cs 1.6.0

package/scripts/benchmarks/observe-index.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+"""Observe one owned benchmark child on Linux, without a wall-clock timeout.
+
+Usage: python3 observe-index.py NEW_RUN_DIR -- node measure-index.cjs ENGINE FIXTURE NEW_RUN_DIR native
+The child retains the caller's environment/affinity. No host settings are changed.
+"""
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+
+def read(path):
+    try:
+        return Path(path).read_text()
+    except (FileNotFoundError, PermissionError, ProcessLookupError):
+        return None
+
+
+def sample(pid):
+    tasks = {}
+    try:
+        for task in Path(f'/proc/{pid}/task').iterdir():
+            tasks[task.name] = {name: read(task / name) for name in ('stat', 'schedstat', 'wchan')}
+    except (FileNotFoundError, ProcessLookupError):
+        pass
+    # Both common cgroup layouts; unavailable counters are recorded as null.
+    paths = [
+        '/proc/stat', '/proc/meminfo', '/proc/loadavg', '/proc/diskstats',
+        '/proc/pressure/cpu', '/proc/pressure/io', '/proc/pressure/memory',
+        '/sys/fs/cgroup/cpu.stat', '/sys/fs/cgroup/cpu.max',
+        '/sys/fs/cgroup/memory.current', '/sys/fs/cgroup/memory.max',
+        '/sys/fs/cgroup/cpu,cpuacct/cpu.stat',
+        '/sys/fs/cgroup/cpu,cpuacct/cpu.cfs_quota_us',
+        '/sys/fs/cgroup/cpu,cpuacct/cpu.cfs_period_us',
+        '/sys/fs/cgroup/memory/memory.usage_in_bytes',
+        '/sys/fs/cgroup/memory/memory.limit_in_bytes',
+    ]
+    return {'epochMs': time.time() * 1000,
+            'process': {name: read(f'/proc/{pid}/{name}') for name in ('stat', 'status', 'io')},
+            'threads': tasks, 'host': {path: read(path) for path in paths}}
+
+
+def main():
+    if sys.platform != 'linux' or len(sys.argv) < 4 or sys.argv[2] != '--':
+        raise SystemExit(__doc__)
+    out = Path(sys.argv[1]).resolve()
+    out.mkdir(parents=True, exist_ok=False)  # Preserve completed/interrupted runs.
+    argv = sys.argv[3:]
+    command = {'argv': argv, 'startedEpochMs': time.time() * 1000,
+               'affinity': sorted(os.sched_getaffinity(0)), 'wallTimeout': None}
+    command_path = out / 'command.json'
+    command_path.write_text(json.dumps(command, indent=2))
+    start = time.monotonic()
+    with (out / 'console.log').open('w') as log, (out / 'resources.ndjson').open('w') as resources:
+        # Inherit the foreground process group: Ctrl-C reaches this owned child
+        # too. Never signal a PID discovered outside this invocation.
+        child = subprocess.Popen(argv, stdout=log, stderr=subprocess.STDOUT)
+        command['pid'] = child.pid
+        command_path.write_text(json.dumps(command, indent=2))
+        next_notice = start
+        try:
+            while child.poll() is None:
+                resources.write(json.dumps(sample(child.pid)) + '\n')
+                resources.flush()
+                now = time.monotonic()
+                if now >= next_notice:
+                    print(f'Benchmark PID {child.pid}: {now-start:.0f}s elapsed; progress in {out}', flush=True)
+                    next_notice = now + 30
+                time.sleep(2)
+        except BaseException:
+            # Record an explicit interrupted outcome, even when no final result
+            # exists. Give only our child a chance to stop, then reap it.
+            child.terminate()
+            try:
+                child.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                child.kill()
+                child.wait()
+            command['interrupted'] = True
+            raise
+        finally:
+            command.update(exit=child.poll(), wallSec=time.monotonic()-start)
+            command_path.write_text(json.dumps(command, indent=2))
+    return child.returncode
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/scripts/build-bundle.sh

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+#
+# Build a self-contained Alpha Code Sense bundle: an official Node runtime + the
+# compiled app + its production deps, so Alpha Code Sense runs with NO system Node and
+# NO native build — node:sqlite is built into the bundled Node. One archive per
+# platform.
+#
+# Because dropping better-sqlite3 left zero native addons, the recipe is pure
+# file-packaging (download the target's Node, copy the app, archive) — so any
+# platform's bundle can be built on any OS. No cross-compile, no native runners.
+#
+# Usage:
+#   scripts/build-bundle.sh <target> [node-version]
+#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
+#                  | win32-x64 | win32-arm64
+#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
+#
+# Output:
+#   unix:    release/codegraph-<target>.tar.gz   (launcher: bin/codegraph)
+#   windows: release/codegraph-<target>.zip      (launcher: bin/codegraph.cmd)
+set -euo pipefail
+
+TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
+NODE_VERSION="${2:-v24.16.0}"
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUT="$ROOT/release"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+ARCH="${TARGET##*-}"   # x64 | arm64
+OSFAM="${TARGET%-*}"   # darwin | linux | win32
+
+echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
+
+# 1. Download + extract the official Node runtime for the target platform.
+if [ "$OSFAM" = "win32" ]; then
+  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
+  if command -v unzip >/dev/null 2>&1; then
+    unzip -q "$WORK/node.zip" -d "$WORK"
+  else
+    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
+  fi
+  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
+else
+  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
+  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
+  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
+fi
+[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
+
+# 2. Build the app (compiled JS + copied wasm/schema assets).
+echo "[bundle] building app"
+( cd "$ROOT" && npm run build >/dev/null )
+
+# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
+STAGE="$WORK/alpha-cs-${TARGET}"
+mkdir -p "$STAGE/lib" "$STAGE/bin"
+cp -R "$ROOT/dist" "$STAGE/lib/dist"
+# The browser viewer rides along inside dist/viewer (built by `npm run build`
+# above). Fail here rather than shipping a bundle whose `codegraph ui` serves
+# a 404 — the copy is verified, not assumed.
+node "$ROOT/scripts/check-ui-build.mjs" --root "$STAGE/lib"
+cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
+echo "[bundle] installing production dependencies"
+# The staged package.json declares the `ui` workspace but the bundle carries
+# no ui/ source — only its build output. That is fine: ui/ has dev
+# dependencies only, so --omit=dev skips the workspace outright and no link
+# is created. (If a future npm starts erroring on the absent folder, stage a
+# stub ui/package.json before this line rather than editing the lock.)
+( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
+rm -f "$STAGE/lib/package-lock.json"
+
+# 3b. Native extraction kernel (optional). Included when a prebuilt .node for
+#     the target exists — release/kernel/<target>/codegraph-kernel.node (the
+#     release workflow's prebuild artifacts) or the locally staged
+#     codegraph-kernel/prebuilds/<target>/ (scripts/build-kernel.sh). Absent →
+#     the bundle simply runs the wasm extraction path; the kernel is a
+#     per-language speedup, never a requirement (see
+#     docs/design/rust-kernel-migration-plan.md).
+KERNEL_NODE=""
+for candidate in "$ROOT/release/kernel/${TARGET}/codegraph-kernel.node" \
+                 "$ROOT/codegraph-kernel/prebuilds/${TARGET}/codegraph-kernel.node"; do
+  if [ -f "$candidate" ]; then KERNEL_NODE="$candidate"; break; fi
+done
+if [ -n "$KERNEL_NODE" ]; then
+  mkdir -p "$STAGE/lib/kernel"
+  cp "$KERNEL_NODE" "$STAGE/lib/kernel/codegraph-kernel.node"
+  echo "[bundle] native kernel included ($KERNEL_NODE)"
+else
+  echo "[bundle] no native kernel for ${TARGET} — bundle uses the wasm extraction path"
+fi
+
+# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
+#    path, so no system Node is ever needed).
+#
+# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
+# baseline compiler so they never reach the turboshaft optimizing tier, whose
+# per-compilation Zone arena OOMs the whole process (`Fatal process out of
+# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
+# V8 engine init so it must be on node's command line; the parse worker inherits
+# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
+# also self-relaunches with this flag when launched without it, so non-bundled
+# runs are covered too; passing it here avoids that extra spawn.)
+if [ "$OSFAM" = "win32" ]; then
+  cp "$NODE_BIN" "$STAGE/node.exe"
+  printf '@"%%~dp0..\\node.exe" --liftoff-only --disable-warning=ExperimentalWarning "%%~dp0..\\lib\\dist\\bin\\codegraph.js" %%*\r\n' \
+    > "$STAGE/bin/ltm-alpha-cs.cmd"
+else
+  cp "$NODE_BIN" "$STAGE/node"
+  cat > "$STAGE/bin/ltm-alpha-cs" <<'LAUNCH'
+#!/bin/sh
+# Resolve symlinks (e.g. the ~/.local/bin/codegraph link install.sh creates) so
+# we find the real bundle dir, not the symlink's location.
+SELF="$0"
+while [ -L "$SELF" ]; do
+  target="$(readlink "$SELF")"
+  case "$target" in
+    /*) SELF="$target" ;;
+    *) SELF="$(dirname "$SELF")/$target" ;;
+  esac
+done
+DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
+# Thread the MCP host's pid to the server's orphan watchdog (issue #1185).
+# $PPID is our parent — the host itself when it launched this script directly;
+# an already-threaded value (the npm shim sets the true host pid) wins.
+CODEGRAPH_HOST_PPID="${CODEGRAPH_HOST_PPID:-$PPID}"
+export CODEGRAPH_HOST_PPID
+# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
+# --disable-warning=ExperimentalWarning: mute node:sqlite's per-thread
+# "experimental feature" warning that otherwise interleaves with the progress UI.
+exec "$DIR/node" --liftoff-only --disable-warning=ExperimentalWarning "$DIR/lib/dist/bin/ltm-alpha-cs.js" "$@"
+LAUNCH
+  chmod +x "$STAGE/bin/ltm-alpha-cs"
+fi
+
+# 5. Archive (.zip for Windows, .tar.gz otherwise).
+mkdir -p "$OUT"
+if [ "$OSFAM" = "win32" ]; then
+  ARCHIVE="$OUT/alpha-cs-${TARGET}.zip"
+  rm -f "$ARCHIVE"
+  ( cd "$WORK" && zip -rqX "$ARCHIVE" "alpha-cs-${TARGET}" )
+else
+  ARCHIVE="$OUT/alpha-cs-${TARGET}.tar.gz"
+  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
+  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "alpha-cs-${TARGET}"
+fi
+echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"

package/scripts/build-kernel.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+#
+# Build the native extraction kernel (codegraph-kernel) and stage the .node
+# where the TS loader (src/extraction/kernel/loader.ts) finds it for
+# from-source runs and tests:
+#
+#   codegraph-kernel/prebuilds/<platform>-<arch>/codegraph-kernel.node
+#
+# The kernel is OPTIONAL everywhere: when the .node is absent the extraction
+# path falls back to the wasm pipeline. This script needs a Rust toolchain
+# (rustup.rs); nothing else in the repo does.
+#
+# Usage:
+#   scripts/build-kernel.sh                 # host platform
+#   scripts/build-kernel.sh --target <rust-triple> [--platform <plat-arch>]
+#
+# The cross-compile form is what the release workflow uses (e.g.
+# --target x86_64-apple-darwin --platform darwin-x64 on a macos-arm runner).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+CRATE="$ROOT/codegraph-kernel"
+
+TARGET=""
+PLATFORM=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target)   TARGET="$2"; shift 2 ;;
+    --platform) PLATFORM="$2"; shift 2 ;;
+    *) echo "unknown arg: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Map a rust triple (or the host) to the bundle-target naming used across the
+# release pipeline (darwin-arm64, linux-x64, win32-arm64, ...).
+if [ -z "$PLATFORM" ]; then
+  if [ -n "$TARGET" ]; then
+    case "$TARGET" in
+      aarch64-apple-darwin)         PLATFORM="darwin-arm64" ;;
+      x86_64-apple-darwin)          PLATFORM="darwin-x64" ;;
+      x86_64-unknown-linux-gnu)     PLATFORM="linux-x64" ;;
+      aarch64-unknown-linux-gnu)    PLATFORM="linux-arm64" ;;
+      x86_64-pc-windows-msvc)       PLATFORM="win32-x64" ;;
+      aarch64-pc-windows-msvc)      PLATFORM="win32-arm64" ;;
+      *) echo "cannot map rust target '$TARGET' to a platform name; pass --platform" >&2; exit 1 ;;
+    esac
+  else
+    case "$(uname -s)-$(uname -m)" in
+      Darwin-arm64)  PLATFORM="darwin-arm64" ;;
+      Darwin-x86_64) PLATFORM="darwin-x64" ;;
+      Linux-x86_64)  PLATFORM="linux-x64" ;;
+      Linux-aarch64) PLATFORM="linux-arm64" ;;
+      MINGW*-x86_64|MSYS*-x86_64)   PLATFORM="win32-x64" ;;
+      MINGW*-aarch64|MSYS*-aarch64) PLATFORM="win32-arm64" ;;
+      *) echo "unrecognized host $(uname -s)-$(uname -m); pass --platform" >&2; exit 1 ;;
+    esac
+  fi
+fi
+
+echo "[kernel] building codegraph-kernel for ${PLATFORM}${TARGET:+ (target $TARGET)}"
+cd "$CRATE"
+if [ -n "$TARGET" ]; then
+  rustup target add "$TARGET" >/dev/null 2>&1 || true
+  cargo build --release --target "$TARGET"
+  OUTDIR="$CRATE/target/$TARGET/release"
+else
+  cargo build --release
+  OUTDIR="$CRATE/target/release"
+fi
+
+# cdylib name differs per OS; the staged name is always codegraph-kernel.node.
+case "$PLATFORM" in
+  darwin-*) LIB="$OUTDIR/libcodegraph_kernel.dylib" ;;
+  linux-*)  LIB="$OUTDIR/libcodegraph_kernel.so" ;;
+  win32-*)  LIB="$OUTDIR/codegraph_kernel.dll" ;;
+esac
+[ -f "$LIB" ] || { echo "[kernel] error: built library not found at $LIB" >&2; exit 1; }
+
+DEST="$CRATE/prebuilds/$PLATFORM"
+mkdir -p "$DEST"
+# rm first so the copy lands on a FRESH inode: overwriting a signed dylib in
+# place leaves macOS's per-inode signature cache stale, and every process
+# that then dlopens the staged .node is SIGKILLed at load (the on-disk
+# signature still verifies, which makes it maddening to diagnose).
+rm -f "$DEST/codegraph-kernel.node"
+cp "$LIB" "$DEST/codegraph-kernel.node"
+echo "[kernel] staged $DEST/codegraph-kernel.node ($(du -h "$DEST/codegraph-kernel.node" | cut -f1))"

package/scripts/check-ui-build.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Assert that the browser viewer actually built.
+ *
+ * `codegraph ui` serves dist/viewer/ as static files. If that tree is missing
+ * or half-written, the CLI still starts and the browser gets a 404 — a failure
+ * that would otherwise surface after the release is published. So the build
+ * fails here instead: index.html must exist, be non-trivial, and every local
+ * asset it references must be on disk next to it.
+ *
+ * It also re-asserts that the compiled engine is still there. The viewer build
+ * empties its own output directory, and `dist/ui/` — the obvious name — is
+ * where tsc puts the TERMINAL ui, so a mis-pointed outDir silently deletes
+ * modules the CLI requires at startup.
+ *
+ * The tree-sitter grammars in dist/extraction/wasm/ are checked the same way
+ * and for the same reason. They are copied by `npm run copy-assets`, they are
+ * what both indexing and the viewer's syntax classification parse with, and
+ * their absence is survivable at runtime — source is served unhighlighted —
+ * which is exactly why it has to fail here: nothing downstream would complain.
+ *
+ * Usage: node scripts/check-ui-build.mjs [--root <dir>]
+ *   --root  directory holding dist/ (default: the repo root). The release
+ *           bundler points this at its staging dir to verify the copy.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const rootFlag = argv.indexOf('--root');
+const staged = rootFlag >= 0 && Boolean(argv[rootFlag + 1]);
+const root = staged
+  ? resolve(argv[rootFlag + 1])
+  : resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const viewerDir = join(root, 'dist', 'viewer');
+const indexHtml = join(viewerDir, 'index.html');
+
+function fail(message, hint) {
+  console.error(`[check-ui-build] ${message}`);
+  if (hint) console.error(`[check-ui-build] ${hint}`);
+  process.exit(1);
+}
+
+if (!existsSync(indexHtml)) {
+  fail(
+    `missing ${indexHtml}`,
+    staged
+      ? 'this bundle predates the UI or was assembled from a stale archive — rebuild it with scripts/build-bundle.sh'
+      : 'the UI workspace did not build — run `npm run build:ui` (or `npm ci` if ui/ has no node_modules)'
+  );
+}
+
+const html = readFileSync(indexHtml, 'utf8');
+if (html.length < 200 || !/<div id="app">/.test(html)) {
+  fail(`${indexHtml} does not look like the built viewer (${html.length} bytes)`);
+}
+
+// Every local src=/href= in the document must resolve inside dist/ui. This is
+// what catches a partial write: index.html naming a hashed bundle that the
+// build never emitted.
+const referenced = [...html.matchAll(/\s(?:src|href)="([^"]+)"/g)].map((m) => m[1]);
+const local = referenced.filter(
+  (url) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url) && !url.startsWith('#')
+);
+
+const missing = [];
+let assets = 0;
+for (const url of local) {
+  const rel = url.replace(/^\.\//, '').replace(/[?#].*$/, '');
+  if (!rel) continue;
+  const onDisk = join(viewerDir, ...rel.split('/'));
+  if (!existsSync(onDisk) || !statSync(onDisk).isFile()) missing.push(rel);
+  else assets += 1;
+}
+
+if (missing.length > 0) {
+  fail(
+    `index.html references ${missing.length} file(s) that are not in dist/viewer: ${missing.join(', ')}`,
+    'the UI build was interrupted or dist/viewer was copied incompletely'
+  );
+}
+
+if (assets === 0) {
+  fail('index.html references no bundled assets — the UI build produced no JS/CSS');
+}
+
+// The viewer build must never have eaten the tsc output next door.
+for (const compiled of ['index.js', join('bin', 'ltm-alpha-cs.js'), join('ui', 'shimmer-progress.js')]) {
+  if (!existsSync(join(root, 'dist', compiled))) {
+    fail(
+      `dist/${compiled.split(sep).join('/')} is missing — the compiled engine is incomplete`,
+      "if this appeared with a UI change, check ui/vite.config.ts: build.outDir must stay dist/viewer, and emptyOutDir must never point at a directory tsc writes (dist/ui is the TERMINAL ui)"
+    );
+  }
+}
+
+// The vendored tree-sitter grammars (`npm run copy-assets`). The viewer reads
+// every file with the same grammar the engine indexed it with, so a missing
+// wasm is both an extraction gap and a silently unhighlighted screen.
+const wasmDir = join(root, 'dist', 'extraction', 'wasm');
+
+/**
+ * The grammars the syntax classification is gated on — the eight languages
+ * CG-57 measured parity against, plus the two the TS family needs. Every one is
+ * vendored (see VENDORED_WASM_LANGS), so all of them must be in this directory
+ * rather than resolved out of node_modules.
+ */
+const GATE_GRAMMARS = [
+  'tree-sitter-typescript.wasm',
+  'tree-sitter-tsx.wasm',
+  'tree-sitter-javascript.wasm',
+  'tree-sitter-go.wasm',
+  'tree-sitter-python.wasm',
+  'tree-sitter-rust.wasm',
+  'tree-sitter-swift.wasm',
+  'tree-sitter-c_sharp.wasm',
+  'tree-sitter-ruby.wasm',
+  'tree-sitter-php.wasm',
+];
+
+if (!existsSync(wasmDir)) {
+  fail(
+    `missing ${wasmDir}`,
+    staged
+      ? 'dist/extraction/wasm was not copied into the bundle — re-run scripts/build-bundle.sh'
+      : 'run `npm run copy-assets` (it copies src/extraction/wasm/*.wasm into dist/)'
+  );
+}
+
+// Against the source tree, the source directory IS the list — nothing to drift.
+// Inside a staged bundle there is no src/, so the gate list carries it.
+const expectedGrammars = new Set(GATE_GRAMMARS);
+const srcWasmDir = join(root, 'src', 'extraction', 'wasm');
+if (!staged && existsSync(srcWasmDir)) {
+  for (const name of readdirSync(srcWasmDir)) {
+    if (name.endsWith('.wasm')) expectedGrammars.add(name);
+  }
+}
+
+const missingGrammars = [...expectedGrammars].filter(
+  (name) => !existsSync(join(wasmDir, name))
+);
+if (missingGrammars.length > 0) {
+  fail(
+    `dist/extraction/wasm is missing ${missingGrammars.length} grammar(s): ${missingGrammars.join(', ')}`,
+    'the copy-assets step was interrupted or dist/extraction/wasm was copied incompletely'
+  );
+}
+
+const grammarCount = readdirSync(wasmDir).filter((n) => n.endsWith('.wasm')).length;
+
+console.log(
+  `[check-ui-build] dist/viewer ok (index.html + ${assets} referenced asset(s)); ` +
+    `dist/extraction/wasm ok (${grammarCount} grammars); dist/ engine intact`
+);

package/scripts/check-ui-package.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Finish and verify the `@ltm/alpha-cs-ui` build (task CG-61).
+ *
+ * `svelte-package` compiles the whole of `ui/src`, which is the right input —
+ * the components a host imports and the ones `codegraph ui` renders are the
+ * same files, and splitting them into two trees is how the two screens start
+ * to drift. But it means the emitted `dist/` also carries the standalone app's
+ * shell, and one of those files is a hazard rather than dead weight:
+ * `lib/router.svelte.js` attaches `hashchange`/`popstate` listeners at module
+ * scope. A host must never inherit a hash router just by rendering a Symbol
+ * view. So this script does three jobs, in order:
+ *
+ *   1. PRUNE the app-only files from the package.
+ *   2. RESOLVE the extensionless relative specifiers `svelte-package` leaves
+ *      behind, so the package works under Node's own ESM resolution and under
+ *      a consumer on `moduleResolution: node16`, not only inside a bundler.
+ *   3. ASSERT the result: the entry, the theme, every path in `exports`, the
+ *      five named components, and — the one that matters most — that nothing
+ *      outside `lib/adapter.js` talks to the network. The whole point of the
+ *      package is that a host's own adapter is the only way data arrives; a
+ *      stray `fetch` anywhere else is a screen that ignores it.
+ *
+ * Run by `npm run build:lib -w ui`. Exits non-zero on any failure.
+ */
+
+import { existsSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UI = fileURLToPath(new URL('../ui', import.meta.url));
+const DIST = join(UI, 'dist');
+
+/**
+ * The standalone viewer's shell — everything that is only reachable from
+ * `main.ts`. Listed by hand rather than derived, because getting it wrong in
+ * the derived direction (pruning something a component needs) is silent until
+ * a host imports it.
+ */
+const APP_ONLY = [
+  'main.js',
+  'main.d.ts',
+  'App.svelte',
+  'App.svelte.d.ts',
+  'app.css',
+  'components/TopBar.svelte',
+  'components/TopBar.svelte.d.ts',
+  'lib/router.svelte.js',
+  'lib/router.svelte.d.ts',
+];
+
+/** Extensions that already resolve; anything else is rewritten to `<spec>.js`. */
+const RESOLVES = ['.js', '.mjs', '.cjs', '.json', '.css', '.svg', '.png'];
+
+const fail = (message) => {
+  console.error(`[check-ui-package] ${message}`);
+  process.exitCode = 1;
+};
+
+if (!existsSync(DIST)) {
+  fail(`no ${relative(UI, DIST)} — run \`npm run build:lib -w ui\``);
+  process.exit(1);
+}
+
+/* ------------------------------------------------------------------ 1. prune */
+
+for (const entry of APP_ONLY) {
+  const path = join(DIST, entry);
+  if (existsSync(path)) rmSync(path, { recursive: true });
+}
+
+/* ------------------------------------------------------------------ walk it */
+
+function* files(dir) {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) yield* files(path);
+    else yield path;
+  }
+}
+
+const all = [...files(DIST)];
+
+/* ---------------------------------------------------------------- 2. resolve */
+
+/**
+ * `from './lib/adapter'` -> `from './lib/adapter.js'`, and
+ * `from './lib/trail.svelte'` -> `from './lib/trail.svelte.js'` (the emitted
+ * file for a `.svelte.ts` rune module).
+ *
+ * Driven by the filesystem rather than by the extension alone: `.svelte` is a
+ * real file for a component and a compiled `.js` for a rune module, and only
+ * looking is right for both.
+ */
+function resolveSpecifiers(source, fromFile) {
+  return source.replace(
+    /(\bfrom\s*|\bimport\s*\(\s*)(['"])(\.[^'"]*)\2/g,
+    (match, head, quote, spec) => {
+      if (RESOLVES.some((ext) => spec.endsWith(ext))) return match;
+      const target = resolve(dirname(fromFile), spec);
+      if (existsSync(target) && statSync(target).isFile()) return match;
+      if (!existsSync(`${target}.js`)) return match;
+      return `${head}${quote}${spec}.js${quote}`;
+    }
+  );
+}
+
+let rewritten = 0;
+for (const path of all) {
+  if (!/\.(js|d\.ts|svelte)$/.test(path)) continue;
+  const before = readFileSync(path, 'utf8');
+  const after = resolveSpecifiers(before, path);
+  if (after !== before) {
+    writeFileSync(path, after);
+    rewritten += 1;
+  }
+}
+
+/* ----------------------------------------------------------------- 3. assert */
+
+const manifest = JSON.parse(readFileSync(join(UI, 'package.json'), 'utf8'));
+
+// Every path the exports map promises has to be there. A missing one is a
+// package that installs cleanly and then fails at the consumer's first import.
+for (const [name, entry] of Object.entries(manifest.exports ?? {})) {
+  const targets = typeof entry === 'string' ? [entry] : Object.values(entry);
+  for (const target of targets) {
+    if (!target.startsWith('./')) continue;
+    if (!existsSync(join(UI, target))) fail(`exports["${name}"] -> ${target} is missing`);
+  }
+}
+
+// The exported screens, plus the two seams they are useless
+// without. Checked in the emitted JS, so a rename in index.ts that misses a
+// component fails here rather than in the Pro app.
+const entry = existsSync(join(DIST, 'index.js'))
+  ? readFileSync(join(DIST, 'index.js'), 'utf8')
+  : '';
+for (const name of [
+  'SymbolView',
+  'TypeHierarchy',
+  'FlowStrip',
+  'ArchitectureMap',
+  'DeadCodeView',
+  'TrailBar',
+  'SavedTrails',
+  'SearchPalette',
+  'CodegraphUi',
+  'setGraphAdapter',
+  'createHttpAdapter',
+  'setNavigationDriver',
+]) {
+  if (!new RegExp(`\\b${name}\\b`).test(entry)) fail(`dist/index.js does not export ${name}`);
+}
+
+// Nothing the app dragged in survives. A component still importing one of the
+// pruned modules would resolve to nothing in a host.
+for (const path of all) {
+  if (!existsSync(path)) continue;
+  const text = readFileSync(path, 'utf8');
+  for (const pruned of ['router.svelte', 'TopBar.svelte', 'app.css']) {
+    const importing = new RegExp(`(from|import\\()\\s*['"][^'"]*${pruned}`);
+    if (importing.test(text)) {
+      fail(`${relative(DIST, path)} still imports ${pruned}, which is app-only`);
+    }
+  }
+}
+
+// The data seam. `lib/adapter.js` is the ONE place that may reach the network;
+// anywhere else means a screen that ignores the host's adapter.
+for (const path of all) {
+  if (!existsSync(path) || !path.endsWith('.js')) continue;
+  if (path.endsWith(join('lib', 'adapter.js'))) continue;
+  const text = readFileSync(path, 'utf8')
+    // Comments talk about `fetch` and `EventSource` on purpose; only code counts.
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|\s)\/\/[^\n]*/g, '');
+  if (/\bnew EventSource\b|\bfetch\s*\(/.test(text)) {
+    fail(`${relative(DIST, path)} reaches the network directly — it must go through the adapter`);
+  }
+}
+
+if (process.exitCode) {
+  console.error('[check-ui-package] FAILED');
+  process.exit(1);
+}
+
+const count = [...files(DIST)].length;
+console.log(
+  `[check-ui-package] ok — ${count} files, ${rewritten} rewritten, ` +
+    `${APP_ONLY.length} app-only pruned (v${manifest.version})`
+);