repotracer 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# repotracer
+
+RepoTracer is an MCP server whose `repo_scout` tool runs an isolated, read-only Luna process and returns validated source citations to Codex Sol.
+
+## Setup
+
+```bash
+npx repotracer setup
+```
+
+The installer downloads the native binary, verifies its SHA-256 checksum, copies it to `~/.repotracer/bin/repotracer`, registers the stdio MCP server, and adds the Codex routing skill.
+
+Codex must already be installed and signed in. RepoTracer reuses that login and does not require another API key.
+
+```bash
+npm install -g @openai/codex
+codex login
+npx repotracer setup
+repotracer doctor
+```
+
+Preview without changing files:
+
+```bash
+npx repotracer setup --dry-run
+```
+
+## Commands
+
+```bash
+repotracer "where is auth handled?"
+repotracer scout "trace refresh token rotation"
+repotracer doctor
+repotracer status
+repotracer uninstall --yes
+```
+
+## Permanent install
+
+```bash
+npm install -g repotracer
+# or
+cargo install --git https://github.com/repotracer/repotracer --locked repotracer
+```
+
+Supported platforms: macOS arm64 and x64, Linux arm64 and x64, and Windows x64. Node.js 18 or newer.
+
+Read the [documentation and benchmarks](https://github.com/repotracer/repotracer).
+
+MIT licensed.

package/bin/repotracer.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function platformKey() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin' && a === 'arm64') return 'darwin-arm64';
+  if (p === 'darwin' && a === 'x64') return 'darwin-x64';
+  if (p === 'linux' && a === 'x64') return 'linux-x64';
+  if (p === 'linux' && a === 'arm64') return 'linux-arm64';
+  if (p === 'win32' && a === 'x64') return 'windows-x64';
+  return `${p}-${a}`;
+}
+
+function findBinary() {
+  const ext = process.platform === 'win32' ? '.exe' : '';
+  const name = `repotracer${ext}`;
+  // Vendored binary first. The target/ paths only exist in a source checkout and
+  // let the benchmark harness run this launcher without publishing. A bare name on
+  // PATH is deliberately NOT a candidate: silently running an unrelated or stale
+  // `repotracer` is worse than failing with instructions.
+  const candidates = [
+    process.env.REPOTRACER_BIN,
+    path.join(__dirname, '..', 'vendor', platformKey(), name),
+    path.join(__dirname, '..', '..', '..', 'target', 'release', name),
+    path.join(__dirname, '..', '..', '..', 'target', 'debug', name),
+  ].filter(Boolean);
+
+  return candidates.find(candidate => fs.existsSync(candidate)) || null;
+}
+
+function persistForSetup(bin, args, home = os.homedir()) {
+  if (!path.isAbsolute(bin) || !args.includes('setup') || args.includes('--dry-run')) return bin;
+
+  const name = process.platform === 'win32' ? 'repotracer.exe' : 'repotracer';
+  const directory = path.join(home, '.repotracer', 'bin');
+  const destination = path.join(directory, name);
+  if (path.resolve(bin) === path.resolve(destination)) return bin;
+
+  const temporary = `${destination}.tmp-${process.pid}`;
+  fs.mkdirSync(directory, { recursive: true });
+  try {
+    fs.copyFileSync(bin, temporary);
+    if (process.platform !== 'win32') fs.chmodSync(temporary, 0o755);
+    try {
+      fs.renameSync(temporary, destination);
+    } catch (error) {
+      if (!['EEXIST', 'EPERM'].includes(error.code)) throw error;
+      fs.rmSync(destination, { force: true });
+      fs.renameSync(temporary, destination);
+    }
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+  // The setup TUI reports the final binary path itself; stay quiet unless debugging.
+  if (process.env.REPOTRACER_DEBUG) console.log(`repotracer: installed CLI at ${destination}`);
+  return destination;
+}
+
+function main(args = process.argv.slice(2)) {
+  const found = findBinary();
+  if (!found) {
+    console.error(`repotracer: native binary not found for ${platformKey()}.`);
+    console.error('Reinstall with: npm install -g repotracer');
+    return 1;
+  }
+
+  const bin = persistForSetup(found, args);
+  const result = spawnSync(bin, args, { stdio: 'inherit' });
+  if (result.error) console.error(`repotracer: could not start: ${result.error.message}`);
+  return result.status == null ? 1 : result.status;
+}
+
+if (require.main === module) process.exit(main());
+
+module.exports = { findBinary, main, persistForSetup, platformKey };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "repotracer",
+  "version": "0.1.0",
+  "description": "Local repository scout for AI coding agents. Small models search. Big models solve.",
+  "bin": {
+    "repotracer": "bin/repotracer.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/fetch-binary.js",
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "coding-agent",
+    "codex",
+    "repository",
+    "code-search",
+    "local-ai"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/repotracer/repotracer#readme",
+  "bugs": {
+    "url": "https://github.com/repotracer/repotracer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/repotracer/repotracer.git",
+    "directory": "packages/npm"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/fetch-binary.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const pkg = require('../package.json');
+
+function platformKey(platform = process.platform, arch = process.arch) {
+  const supported = {
+    'darwin-arm64': 'darwin-arm64',
+    'darwin-x64': 'darwin-x64',
+    'linux-arm64': 'linux-arm64',
+    'linux-x64': 'linux-x64',
+    'win32-x64': 'windows-x64',
+  };
+  const key = supported[`${platform}-${arch}`];
+  if (!key) throw new Error(`unsupported platform: ${platform}-${arch}`);
+  return key;
+}
+
+async function download(fetchImpl, url) {
+  const response = await fetchImpl(url, {
+    headers: { 'User-Agent': `repotracer-npm/${pkg.version}` },
+  });
+  if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+function expectedChecksum(sums, asset) {
+  for (const line of sums.split(/\r?\n/)) {
+    const match = line.trim().match(/^([a-fA-F0-9]{64})\s+(.+)$/);
+    if (match && path.basename(match[2]) === asset) return match[1].toLowerCase();
+  }
+  throw new Error(`${asset} is missing from SHA256SUMS`);
+}
+
+async function install(options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  const key = platformKey(platform, arch);
+  const executable = platform === 'win32' ? 'repotracer.exe' : 'repotracer';
+  const asset = `repotracer-${key}${executable.endsWith('.exe') ? '.exe' : ''}`;
+  const root = options.root || path.join(__dirname, '..');
+  const baseUrl = options.baseUrl
+    || process.env.REPOTRACER_RELEASE_BASE_URL
+    || `https://github.com/repotracer/repotracer/releases/download/v${pkg.version}`;
+  const fetchImpl = options.fetchImpl || globalThis.fetch;
+
+  if (!fetchImpl) throw new Error('Node.js 18 or newer is required');
+  if (!options.quiet) console.log(`repotracer: downloading v${pkg.version} for ${key}...`);
+
+  const [binary, sums] = await Promise.all([
+    download(fetchImpl, `${baseUrl}/${asset}`),
+    download(fetchImpl, `${baseUrl}/SHA256SUMS`),
+  ]);
+  const expected = expectedChecksum(sums.toString('utf8'), asset);
+  const actual = crypto.createHash('sha256').update(binary).digest('hex');
+  if (actual !== expected) throw new Error(`checksum mismatch for ${asset}`);
+
+  const directory = path.join(root, 'vendor', key);
+  const destination = path.join(directory, executable);
+  const temporary = `${destination}.tmp-${process.pid}`;
+  fs.mkdirSync(directory, { recursive: true });
+  try {
+    fs.writeFileSync(temporary, binary, { flag: 'wx', mode: 0o755 });
+    try {
+      fs.renameSync(temporary, destination);
+    } catch (error) {
+      if (!['EEXIST', 'EPERM'].includes(error.code)) throw error;
+      fs.rmSync(destination, { force: true });
+      fs.renameSync(temporary, destination);
+    }
+    if (process.platform !== 'win32') fs.chmodSync(destination, 0o755);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+
+  if (!options.quiet) console.log(`repotracer: installed ${destination}`);
+  return destination;
+}
+
+if (require.main === module) {
+  install().catch((error) => {
+    console.error(`repotracer: installation failed: ${error.message}`);
+    console.error(`repotracer: GitHub Release v${pkg.version} must exist before npm installation.`);
+    process.exit(1);
+  });
+}
+
+module.exports = { expectedChecksum, install, platformKey };