@zlnap/astrolabe 0.0.0-stage → 0.17.0

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @zlnap/astrolabe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Astrolabe AI：面向 AI 编码助手的本地代码检索与导航 MCP server（二进制名 `astrolabe`）。与 npm 上无关的 `astrolabe`、`astrolabe-ai` 包不是同一个项目。本包是**零依赖**的 Node shim：通过 `optionalDependencies` 安装当前平台的原生二进制，再把 stdin/stdout/stderr、退出码和信号原样交给它。
+
+```bash
+npx -y @zlnap/astrolabe /path/to/repo
+```
+
+MCP 客户端（推荐一键配置）：
+
+```bash
+npx -y @zlnap/astrolabe setup
+```
+
+Detects Claude Code, Cursor, Codex, Windsurf, Cline, Roo, Continue, OpenCode, DeepSeek Harness, Codebuddy, Grok Build, Kimi Code, and ZCode. Merges MCP config (OpenCode V1/V2/jsonc; Grok `[mcp_servers.*]` TOML; ZCode `mcp.servers`; DSH installs the native guard plugin + `cordis.patch.yml` merge). Optional `--with-hooks` installs OpenCode's guard plugin and hook recipes for Codebuddy / Grok / Kimi / ZCode (ZCode: no `SessionEnd`, do not hang cleanup on `Stop`). Flags: `--yes`, `--clients=…`, `--dry-run`, `--with-hooks`, `--list`.
+
+探测本机 Claude Code / Cursor / Codex 等，交互勾选后合并写入 MCP 配置（`--yes`、`--dry-run`、`--list` 可用）。手动配置示例：
+
+```json
+{
+  "mcpServers": {
+    "astrolabe": {
+      "command": "npx",
+      "args": ["-y", "@zlnap/astrolabe", ".", "--context=cursor"]
+    }
+  }
+}
+```
+
+日志走 stderr，JSON-RPC 走 stdin/stdout，shim 不会缓冲或改写任何通道。
+
+若平台包因 `--omit=optional`、`--ignore-scripts` 或 npm 11 以下的 lockfile bug 缺失，shim 会从 GitHub Releases 下载对应 target 的归档，校验 SHA256 后缓存到 `~/.astrolabe/bin/`。

package/bin/astrolabe.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+'use strict';
+
+const argv = process.argv.slice(2);
+
+// `astrolabe setup` is implemented in Node (detect agents + merge MCP configs).
+// Intercept before resolving / spawning the native binary.
+if (argv[0] === 'setup') {
+  const { run } = require('../lib/setup');
+  try {
+    process.exitCode = run(argv.slice(1));
+  } catch (error) {
+    console.error(`[astrolabe setup] ${error.message || error}`);
+    process.exitCode = 1;
+  }
+} else {
+  const { resolveBinary } = require('../lib/resolve');
+  const { runBinary } = require('../lib/run');
+
+  resolveBinary()
+    .then((binPath) => {
+      runBinary(binPath, argv);
+    })
+    .catch((error) => {
+      console.error(`[astrolabe] ${error.message || error}`);
+      process.exit(1);
+    });
+}

package/lib/download.js

@@ -0,0 +1,355 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { archiveName } = require('./platforms');
+
+const DEFAULT_HOST = 'https://github.com';
+const DEFAULT_REPO = 'wojiushirencai/Astrolabe';
+const MAX_REDIRECTS = 10;
+const REQUEST_TIMEOUT_MS = 60_000;
+
+function cacheRoot() {
+  if (process.env.ASTROLABE_CACHE_DIR) {
+    return process.env.ASTROLABE_CACHE_DIR;
+  }
+  return path.join(os.homedir(), '.astrolabe', 'bin');
+}
+
+function releaseRepo() {
+  return process.env.ASTROLABE_RELEASE_REPO || DEFAULT_REPO;
+}
+
+function releaseHost() {
+  return (process.env.ASTROLABE_RELEASE_HOST || DEFAULT_HOST).replace(/\/$/, '');
+}
+
+/// Human-facing releases page for `version`, used in error messages.
+function releasesTagUrl(version) {
+  return `${releaseHost()}/${releaseRepo()}/releases/tag/v${version}`;
+}
+
+function releasesBaseUrl(version) {
+  if (process.env.ASTROLABE_RELEASES_BASE_URL) {
+    return process.env.ASTROLABE_RELEASES_BASE_URL.replace(/\/$/, '');
+  }
+  return `${releaseHost()}/${releaseRepo()}/releases/download/v${version}`;
+}
+
+function requestHeaders(url, isRedirect = false) {
+  const headers = {
+    Accept: 'application/octet-stream',
+    'User-Agent': `astrolabe-npm/${require('../package.json').version}`,
+  };
+  if (isRedirect) {
+    return headers;
+  }
+  let host;
+  try {
+    host = new URL(url).host.toLowerCase();
+  } catch {
+    return headers;
+  }
+
+  // Never attach credentials to external redirect targets (AWS S3, Aliyun OSS, CDNs)
+  if (
+    host.endsWith('.amazonaws.com') ||
+    host.endsWith('.aliyuncs.com') ||
+    host.endsWith('.githubusercontent.com')
+  ) {
+    return headers;
+  }
+
+  let relHost = '';
+  try {
+    const raw = process.env.ASTROLABE_RELEASES_BASE_URL || releaseHost();
+    relHost = new URL(raw.includes('://') ? raw : `https://${raw}`).host.toLowerCase();
+  } catch {
+    relHost = '';
+  }
+
+  const isMatchingReleaseHost = relHost && host === relHost;
+  const isDirectReleaseEndpoint =
+    host === 'github.com' ||
+    host === 'api.github.com' ||
+    host === 'gitee.com' ||
+    host === 'api.gitee.com';
+
+  if (!isMatchingReleaseHost && !isDirectReleaseEndpoint) {
+    return headers;
+  }
+
+  const token = releaseTokenFor(url);
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+/// Only send a credential to the host it was issued for.
+///
+/// `GITHUB_TOKEN` is set in most CI environments, and releases now live on
+/// Gitee: attaching it unconditionally would hand a GitHub credential to an
+/// unrelated host on every install. `ASTROLABE_RELEASE_TOKEN` is explicit
+/// and goes to whichever host the user pointed the download at.
+function releaseTokenFor(url) {
+  let host;
+  try {
+    host = new URL(url).host.toLowerCase();
+  } catch {
+    return undefined;
+  }
+
+  if (
+    host.endsWith('.amazonaws.com') ||
+    host.endsWith('.aliyuncs.com') ||
+    host.endsWith('.githubusercontent.com')
+  ) {
+    return undefined;
+  }
+
+  if (process.env.ASTROLABE_RELEASE_TOKEN) {
+    return process.env.ASTROLABE_RELEASE_TOKEN;
+  }
+  if (host === 'github.com' || host.endsWith('.github.com')) {
+    return process.env.ASTROLABE_GITHUB_TOKEN || process.env.GITHUB_TOKEN;
+  }
+  return undefined;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function downloadToFile(url, dest, redirectsLeft = MAX_REDIRECTS, isRedirect = false) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith('https:') ? https : http;
+    const req = client.get(url, { headers: requestHeaders(url, isRedirect) }, (res) => {
+      const status = res.statusCode || 0;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) {
+          reject(new Error(`too many redirects fetching ${url}`));
+          return;
+        }
+        const next = new URL(res.headers.location, url).toString();
+        downloadToFile(next, dest, redirectsLeft - 1, true).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${status} fetching ${url}`));
+        return;
+      }
+      const out = fs.createWriteStream(dest);
+      res.pipe(out);
+      out.on('finish', () => out.close(() => resolve(dest)));
+      out.on('error', reject);
+    });
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error(`timed out fetching ${url}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+function sha256File(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(file);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+function parseSha256Sums(text) {
+  const map = new Map();
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    let match = line.match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (match) {
+      map.set(path.basename(match[2].replace(/^\.\//, '')), match[1].toLowerCase());
+      continue;
+    }
+    match = line.match(/^SHA256 \((.+)\) = ([0-9a-fA-F]{64})$/);
+    if (match) {
+      map.set(path.basename(match[1]), match[2].toLowerCase());
+    }
+  }
+  return map;
+}
+
+function extractArchive(archivePath, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const result = spawnSync('tar', ['-xf', archivePath, '-C', destDir], {
+    encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0) {
+    if (process.platform === 'win32' && archivePath.endsWith('.zip')) {
+      // Pass paths via env vars so PowerShell never interpolates them inside
+      // a double-quoted -Command string (paths can contain `$`, `` ` ``, `"`).
+      const psResult = spawnSync(
+        'powershell.exe',
+        [
+          '-NoProfile',
+          '-NonInteractive',
+          '-Command',
+          'Expand-Archive -LiteralPath $env:ASTROLABE_ZIP_SRC -DestinationPath $env:ASTROLABE_ZIP_DST -Force',
+        ],
+        {
+          encoding: 'utf8',
+          env: {
+            ...process.env,
+            ASTROLABE_ZIP_SRC: archivePath,
+            ASTROLABE_ZIP_DST: destDir,
+          },
+        },
+      );
+      if (psResult.error) {
+        throw new Error(`failed to extract ${archivePath}: ${psResult.error.message}`);
+      }
+      if (psResult.status !== 0) {
+        throw new Error(
+          `failed to extract ${archivePath}: ${psResult.stderr || psResult.stdout || `exit ${psResult.status}`}`,
+        );
+      }
+      return;
+    }
+    if (result.error) {
+      throw new Error(`failed to extract ${archivePath}: ${result.error.message}`);
+    }
+    throw new Error(
+      `failed to extract ${archivePath}: ${result.stderr || result.stdout || `exit ${result.status}`}`,
+    );
+  }
+}
+
+function findBinary(dir, binaryName) {
+  const direct = path.join(dir, binaryName);
+  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) {
+    return direct;
+  }
+
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && (entry.name === binaryName || entry.name === 'astrolabe' || entry.name === 'astrolabe.exe')) {
+        return full;
+      }
+    }
+  }
+  throw new Error(`archive did not contain ${binaryName}`);
+}
+
+function ensureExecutable(file) {
+  if (process.platform === 'win32') return;
+  const mode = fs.statSync(file).mode;
+  if ((mode & 0o111) === 0) {
+    fs.chmodSync(file, mode | 0o755);
+  }
+}
+
+async function withLock(lockDir, fn) {
+  fs.mkdirSync(lockDir, { recursive: true });
+  const lockPath = path.join(lockDir, 'download.lock');
+  const started = Date.now();
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx');
+      try {
+        return await fn();
+      } finally {
+        fs.closeSync(fd);
+        try {
+          fs.unlinkSync(lockPath);
+        } catch {
+          // ignore
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (Date.now() - started > 120_000) {
+        throw new Error('timed out waiting for astrolabe binary download lock');
+      }
+      await sleep(200);
+    }
+  }
+}
+
+async function downloadRelease(platform, version) {
+  const destDir = path.join(cacheRoot(), version, platform.key);
+  const destBin = path.join(destDir, platform.binaryName);
+  if (fs.existsSync(destBin)) {
+    ensureExecutable(destBin);
+    return destBin;
+  }
+
+  return withLock(destDir, async () => {
+    if (fs.existsSync(destBin)) {
+      ensureExecutable(destBin);
+      return destBin;
+    }
+
+    const base = releasesBaseUrl(version);
+    const archive = archiveName(platform, version);
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astrolabe-dl-'));
+    const sumsPath = path.join(tmpDir, 'SHA256SUMS');
+    const archivePath = path.join(tmpDir, archive);
+    const extractDir = path.join(tmpDir, 'extract');
+
+    try {
+      await downloadToFile(`${base}/SHA256SUMS`, sumsPath);
+      const sums = parseSha256Sums(fs.readFileSync(sumsPath, 'utf8'));
+      const expected = sums.get(archive);
+      if (!expected) {
+        throw new Error(`SHA256SUMS has no entry for ${archive}`);
+      }
+
+      await downloadToFile(`${base}/${archive}`, archivePath);
+      const actual = await sha256File(archivePath);
+      if (actual !== expected) {
+        throw new Error(
+          `SHA256 mismatch for ${archive}: expected ${expected}, got ${actual}`,
+        );
+      }
+
+      extractArchive(archivePath, extractDir);
+      const extracted = findBinary(extractDir, platform.binaryName);
+      fs.copyFileSync(extracted, destBin);
+      ensureExecutable(destBin);
+      return destBin;
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+}
+
+module.exports = {
+  cacheRoot,
+  downloadRelease,
+  releasesBaseUrl,
+  releasesTagUrl,
+  releaseTokenFor,
+  ensureExecutable,
+  parseSha256Sums,
+  sha256File,
+};

package/lib/platforms.js

@@ -0,0 +1,158 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+
+/**
+ * Single source of truth for npm platform packages and GitHub Release artifacts.
+ *
+ * Release contract (consumed by the GitHub Releases pipeline):
+ *   tag:        v${version}          e.g. v0.1.0
+ *   unix:       astrolabe-<version>-<rustTarget>.tar.gz
+ *   windows:    astrolabe-<version>-<rustTarget>.zip
+ *   checksums:  SHA256SUMS           GNU coreutils format (`<hex>  <filename>`)
+ *   archive root contains the binary named `astrolabe` or `astrolabe.exe`.
+ */
+const PLATFORMS = [
+  {
+    key: 'darwin-arm64',
+    npmPackage: '@zlnap/darwin-arm64',
+    rustTarget: 'aarch64-apple-darwin',
+    npmOs: 'darwin',
+    npmCpu: 'arm64',
+    npmLibc: null,
+    archiveExt: '.tar.gz',
+    binaryName: 'astrolabe',
+  },
+  {
+    key: 'darwin-x64',
+    npmPackage: '@zlnap/darwin-x64',
+    rustTarget: 'x86_64-apple-darwin',
+    npmOs: 'darwin',
+    npmCpu: 'x64',
+    npmLibc: null,
+    archiveExt: '.tar.gz',
+    binaryName: 'astrolabe',
+  },
+  {
+    key: 'linux-x64-gnu',
+    npmPackage: '@zlnap/linux-x64-gnu',
+    rustTarget: 'x86_64-unknown-linux-gnu',
+    npmOs: 'linux',
+    npmCpu: 'x64',
+    npmLibc: 'glibc',
+    archiveExt: '.tar.gz',
+    binaryName: 'astrolabe',
+  },
+  {
+    key: 'linux-x64-musl',
+    npmPackage: '@zlnap/linux-x64-musl',
+    rustTarget: 'x86_64-unknown-linux-musl',
+    npmOs: 'linux',
+    npmCpu: 'x64',
+    npmLibc: 'musl',
+    archiveExt: '.tar.gz',
+    binaryName: 'astrolabe',
+  },
+  {
+    key: 'linux-arm64-gnu',
+    npmPackage: '@zlnap/linux-arm64-gnu',
+    rustTarget: 'aarch64-unknown-linux-gnu',
+    npmOs: 'linux',
+    npmCpu: 'arm64',
+    npmLibc: 'glibc',
+    archiveExt: '.tar.gz',
+    binaryName: 'astrolabe',
+  },
+  {
+    key: 'win32-x64-msvc',
+    npmPackage: '@zlnap/win32-x64-msvc',
+    rustTarget: 'x86_64-pc-windows-msvc',
+    npmOs: 'win32',
+    npmCpu: 'x64',
+    npmLibc: null,
+    archiveExt: '.zip',
+    binaryName: 'astrolabe.exe',
+  },
+];
+
+function archiveName(platform, version) {
+  return `astrolabe-${version}-${platform.rustTarget}${platform.archiveExt}`;
+}
+
+function isMuslLinux() {
+  if (process.platform !== 'linux') return false;
+
+  try {
+    const ldd = fs.readFileSync('/usr/bin/ldd', 'utf8');
+    if (ldd.includes('musl')) return true;
+  } catch {
+    // no /usr/bin/ldd
+  }
+
+  try {
+    if (fs.existsSync('/etc/alpine-release')) return true;
+  } catch {
+    // ignore
+  }
+
+  try {
+    if (typeof process.report?.getReport === 'function') {
+      const report = process.report.getReport();
+      if (report && typeof report === 'object') {
+        const shared = report.sharedObjects || [];
+        if (shared.some((entry) => /libc\.musl-/.test(entry))) return true;
+        const glibc = report.header && report.header.glibcVersionRuntime;
+        if (glibc) return false;
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return false;
+}
+
+function detectPlatform() {
+  const npmOs = process.platform;
+  const npmCpu = os.arch();
+  const npmLibc = npmOs === 'linux' ? (isMuslLinux() ? 'musl' : 'glibc') : null;
+
+  const match = PLATFORMS.find((platform) => {
+    if (platform.npmOs !== npmOs) return false;
+    if (platform.npmCpu !== npmCpu) return false;
+    if (platform.npmLibc && platform.npmLibc !== npmLibc) return false;
+    return true;
+  });
+
+  if (!match) {
+    const host = `${npmOs}-${npmCpu}${npmLibc ? `-${npmLibc}` : ''}`;
+    const supported = PLATFORMS.map((platform) => platform.key).join(', ');
+    throw new Error(
+      `astrolabe has no prebuilt binary for ${host}. Supported platforms: ${supported}`,
+    );
+  }
+
+  return match;
+}
+
+function platformByKey(key) {
+  const match = PLATFORMS.find((platform) => platform.key === key);
+  if (!match) {
+    throw new Error(`unknown platform key: ${key}`);
+  }
+  return match;
+}
+
+function platformByRustTarget(rustTarget) {
+  return PLATFORMS.find((platform) => platform.rustTarget === rustTarget) || null;
+}
+
+module.exports = {
+  PLATFORMS,
+  archiveName,
+  detectPlatform,
+  isMuslLinux,
+  platformByKey,
+  platformByRustTarget,
+};

package/lib/resolve.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { downloadRelease, ensureExecutable, releasesTagUrl } = require('./download');
+const { PLATFORMS, detectPlatform } = require('./platforms');
+
+const VERSION = require('../package.json').version;
+
+function packageRoot(npmPackage) {
+  const pkgJson = require.resolve(`${npmPackage}/package.json`);
+  return path.dirname(pkgJson);
+}
+
+function listInstalledPlatformPackages() {
+  const found = [];
+  for (const platform of PLATFORMS) {
+    try {
+      found.push(platform.npmPackage);
+      require.resolve(`${platform.npmPackage}/package.json`);
+    } catch {
+      found.pop();
+    }
+  }
+  return found;
+}
+
+function materializeIfVirtual(binPath, platform) {
+  const normalized = binPath.replace(/\\/g, '/');
+  if (!normalized.includes('.zip/')) {
+    return binPath;
+  }
+  const destDir = path.join(
+    require('./download').cacheRoot(),
+    VERSION,
+    `${platform.key}-pnp`,
+  );
+  const dest = path.join(destDir, platform.binaryName);
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(destDir, { recursive: true });
+    fs.copyFileSync(binPath, dest);
+    ensureExecutable(dest);
+  }
+  return dest;
+}
+
+function resolveOptionalBinary(platform) {
+  const binPath = path.join(packageRoot(platform.npmPackage), platform.binaryName);
+  if (!fs.existsSync(binPath)) {
+    throw Object.assign(
+      new Error(
+        `${platform.npmPackage} is installed but ${platform.binaryName} is missing`,
+      ),
+      { code: 'ASTROLABE_BINARY_MISSING' },
+    );
+  }
+  return materializeIfVirtual(binPath, platform);
+}
+
+function envOverridePath() {
+  const fromEnv = process.env.ASTROLABE_BINARY_PATH;
+  if (!fromEnv) return null;
+  if (!fs.existsSync(fromEnv)) {
+    console.error(`[astrolabe] ignoring ASTROLABE_BINARY_PATH, file not found: ${fromEnv}`);
+    return null;
+  }
+  return fromEnv;
+}
+
+async function resolveBinary() {
+  const override = envOverridePath();
+  if (override) return override;
+
+  const platform = detectPlatform();
+
+  try {
+    const binPath = resolveOptionalBinary(platform);
+    ensureExecutable(binPath);
+    return binPath;
+  } catch (error) {
+    if (error && error.code !== 'MODULE_NOT_FOUND' && error.code !== 'ASTROLABE_BINARY_MISSING') {
+      throw error;
+    }
+  }
+
+  try {
+    return await downloadRelease(platform, VERSION);
+  } catch (downloadError) {
+    const others = listInstalledPlatformPackages().filter(
+      (name) => name !== platform.npmPackage,
+    );
+    const otherHint = others.length
+      ? `\nFound platform package(s) for a different architecture: ${others.join(', ')}.\n` +
+        `This usually means node_modules was copied across OS/arch, or the lockfile was generated by npm < 11 which can drop optionalDependencies.`
+      : `\nCommon causes: npm/pnpm/yarn --omit=optional, --ignore-scripts, or a lockfile generated on another OS/arch (npm < 11 bug).`;
+
+    throw new Error(
+      `Could not locate ${platform.npmPackage} (needed on this machine) and GitHub Releases fallback failed: ${downloadError.message}` +
+        otherHint +
+        `\nTried: ${require('./download').cacheRoot()}/${VERSION}/${platform.key}/` +
+        `\nReleases: ${releasesTagUrl(VERSION)}`,
+    );
+  }
+}
+
+module.exports = { resolveBinary };