homegraph 1.5.0 → 1.5.2

package/scripts/npm-shim.js

@@ -1,275 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-//
-// npm thin-installer launcher for HomeGraph.
-//
-// The heavy artifact (a vendored Node runtime + the app) ships as a per-platform
-// optionalDependency: homegraph-<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:
-//   HOMEGRAPH_NO_DOWNLOAD=1     disable the network fallback (print guidance)
-//   HOMEGRAPH_INSTALL_DIR=DIR   cache location (default: ~/.homegraph)
-//   HOMEGRAPH_DOWNLOAD_BASE=URL release-download base (for mirrors/air-gapped)
-//
-// Wired up at release time as the main package's `bin`:
-//   "bin": { "homegraph": "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 = 'homegraph-' + target;
-var isWindows = process.platform === 'win32';
-var REPO = 'homegraph/homegraph';
-
-main().catch(function (e) {
-  process.stderr.write('homegraph: ' + (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.HOMEGRAPH_HOST_PPID) env.HOMEGRAPH_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('homegraph: ' + 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/homegraph.js');
-      return { command: nodeExe, args: liftoff(entry) };
-    }
-    return { command: require.resolve(pkg + '/bin/homegraph'), 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', 'homegraph.js');
-    if (fs.existsSync(nodeExe) && fs.existsSync(entry)) {
-      return { command: nodeExe, args: liftoff(entry) };
-    }
-  } else {
-    var launcher = path.join(dir, 'bin', 'homegraph');
-    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/homegraph
-// 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.HOMEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.homegraph'), 'bundles');
-  var dest = path.join(bundlesDir, target + '-' + version);
-
-  // Already downloaded by a previous run? Use it even when downloads are
-  // disabled — HOMEGRAPH_NO_DOWNLOAD blocks fetching, not a cached bundle.
-  var cached = launcherIn(dest);
-  if (cached) { pruneOldBundles(bundlesDir, dest); return cached; }
-
-  if (process.env.HOMEGRAPH_NO_DOWNLOAD) {
-    fail('the network fallback is disabled (HOMEGRAPH_NO_DOWNLOAD is set).');
-  }
-
-  var asset = 'homegraph-' + target + (isWindows ? '.zip' : '.tar.gz');
-  var base = process.env.HOMEGRAPH_DOWNLOAD_BASE || ('https://github.com/' + REPO + '/releases/download');
-  var url = base + '/v' + version + '/' + asset;
-
-  process.stderr.write(
-    'homegraph: platform bundle missing (registry did not provide ' + pkg + ').\n' +
-    'homegraph: 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 homegraph-<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('homegraph: 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': 'homegraph-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('homegraph: 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(
-    'homegraph: no prebuilt bundle for ' + target + '.\n' +
-    (reason ? 'homegraph: ' + 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 homegraph --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/ohos-sdk-publish.mjs

@@ -1,133 +0,0 @@
-#!/usr/bin/env node
-/**
- * Build and optionally publish homegraph-ohos-api-db-<version> (one npm package per API version).
- *
- * Usage:
- *   node scripts/ohos-sdk-publish.mjs <zip-or-dir> [version] [--dry-run] [--no-publish]
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import {
-  resolveOhosSdkInput,
-  ohosApiDbFilename,
-  ohosApiDbPackageName,
-  indexOhosApiDb,
-} from '../dist/extraction/languages/arkts.js';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-function parseArgs(argv) {
-  const positional = [];
-  const flags = new Set();
-  for (let i = 2; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg.startsWith('--')) flags.add(arg);
-    else positional.push(arg);
-  }
-  return {
-    input: positional[0] ?? '',
-    version: positional[1] ?? '',
-    dryRun: flags.has('--dry-run'),
-    noPublish: flags.has('--no-publish'),
-  };
-}
-
-function buildNpmPackage(version, dbPath, outDir) {
-  const dbName = ohosApiDbFilename(version);
-  const pkgName = ohosApiDbPackageName(version);
-  fs.rmSync(outDir, { recursive: true, force: true });
-  fs.mkdirSync(path.join(outDir, 'scripts'), { recursive: true });
-  fs.copyFileSync(dbPath, path.join(outDir, dbName));
-
-  const postinstall = `#!/usr/bin/env node
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const dbName = ${JSON.stringify(dbName)};
-const src = path.join(__dirname, '..', dbName);
-const dest = path.join(os.homedir(), '.homegraph', 'api', dbName);
-if (!fs.existsSync(src)) process.exit(0);
-fs.mkdirSync(path.dirname(dest), { recursive: true });
-fs.copyFileSync(src, dest);
-`;
-  fs.writeFileSync(path.join(outDir, 'scripts', 'postinstall.js'), postinstall, { mode: 0o755 });
-  fs.writeFileSync(
-    path.join(outDir, 'package.json'),
-    JSON.stringify(
-      {
-        name: pkgName,
-        version: '1.0.0',
-        description: `Prebuilt HomeGraph OHOS API database for SDK ${version}`,
-        license: 'MIT',
-        files: [dbName, 'scripts/postinstall.js'],
-        scripts: { postinstall: 'node scripts/postinstall.js' },
-        homegraph: { ohosApiVersion: version, dbFile: dbName },
-      },
-      null,
-      2
-    ) + '\n'
-  );
-  return pkgName;
-}
-
-const { input, version, dryRun, noPublish } = parseArgs(process.argv);
-if (!input) {
-  console.error('Usage: node scripts/ohos-sdk-publish.mjs <zip-or-dir> [version] [--dry-run] [--no-publish]');
-  process.exit(1);
-}
-
-if (!fs.existsSync(path.join(ROOT, 'dist/extraction/languages/arkts.js'))) {
-  console.error('[ohos-sdk-publish] dist not built — run npm run build first');
-  process.exit(1);
-}
-
-const resolved = resolveOhosSdkInput({
-  inputPath: path.resolve(input),
-  versionOverride: version || undefined,
-});
-
-const dbPath = path.join(
-  fs.mkdtempSync(path.join(path.dirname(resolved.sdkHome), '.hg-ohos-pack-')),
-  ohosApiDbFilename(resolved.version)
-);
-const pkgDir = path.join(path.dirname(dbPath), 'npm-package');
-
-try {
-  process.stderr.write(`[ohos-sdk-publish] indexing ${resolved.version} …\n`);
-  const result = await indexOhosApiDb({
-    sdkHome: resolved.sdkHome,
-    version: resolved.version,
-    outputPath: dbPath,
-    onProgress: (p) => {
-      if (p.phase === 'arkts-batch') {
-        const label = p.subphase === 'scene' ? 'Scene' : 'Persist';
-        process.stderr.write(`\r${label}: ${p.current}/${p.total}`.padEnd(40));
-      }
-    },
-  });
-  process.stderr.write('\n');
-  if (!result.success) {
-    for (const err of result.errors.filter((e) => e.severity === 'error')) console.error(err.message);
-    process.exit(1);
-  }
-
-  const pkgName = buildNpmPackage(resolved.version, dbPath, pkgDir);
-  console.log(`[ohos-sdk-publish] package: ${pkgName} → ${pkgDir} (${result.nodesCreated} nodes)`);
-
-  if (dryRun || noPublish) {
-    console.log('[ohos-sdk-publish] skipping npm publish');
-    process.exit(0);
-  }
-  if (!process.env.NPM_TOKEN) {
-    console.error('[ohos-sdk-publish] NPM_TOKEN not set — package built, not published');
-    process.exit(0);
-  }
-
-  const { execFileSync } = await import('child_process');
-  execFileSync('npm', ['publish', '--access', 'public'], { cwd: pkgDir, stdio: 'inherit' });
-  console.log(`[ohos-sdk-publish] published ${pkgName}`);
-} finally {
-  resolved.cleanup?.();
-}

package/scripts/pack-npm.sh

@@ -1,119 +0,0 @@
-#!/usr/bin/env bash
-#
-# Assemble the npm thin-installer packages from built bundles (esbuild pattern).
-#
-# Produces, under release/npm/:
-#   homegraph-<target>/   one per built bundle — the vendored Node + app, tagged
-#                         with os/cpu so npm installs only the matching one.
-#   main/                 the homegraph 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/homegraph-*.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"/homegraph-*.tar.gz "$REL"/homegraph-*.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}" ;;   # homegraph-<target>
-    *.zip)    base="${fname%.zip}" ;;
-  esac
-  target="${base#homegraph-}"             # <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/homegraph-${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}/homegraph-${process.env.TARGET}`,
-        version: process.env.VERSION,
-        description: `HomeGraph 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}/homegraph-${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}/homegraph-${t}`]=process.env.VERSION;
-    fs.writeFileSync(process.argv[1], JSON.stringify({
-      name: `${process.env.SCOPE}/homegraph`,
-      version: process.env.VERSION,
-      description: "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
-      bin: { homegraph: "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}/homegraph@${VERSION} (${#targets[@]} platform packages in optionalDependencies)"
-echo "[pack-npm] output: $NPM"