refactor(build): replace relative-depth self-reference guessing with Node's own package self-referencing

The previous commit's fix for the cross-context (in-process test vs
compiled dist/) self-relative-path problem was a "try depth N, then
depth N+1" heuristic (resolveOwnPackageSiblingPath /
resolveMonorepoSiblingPath). It worked, but it's not the correct tool
for the job: Node has a purpose-built, standard mechanism for exactly
this -- a package importing its own files by its own published name
("self-referencing"), resolved via the package.json "exports" map the
same way any external "@loopover/x/..." import would be. That's robust
by construction (walks up through node_modules from the calling file's
own location, landing on the one real file regardless of that file's
current directory depth) rather than by guessing candidate depths.

Adds a minimal "exports" map to both packages' package.json (own
package.json + the one or two other self-referenced files each needs)
and switches every "own package.json"-style self-reference --
bin/loopover-mcp.ts (package.json, CHANGELOG.md), lib/version.ts's
static JSON import, lib/status.ts's two require() calls, and
bin/loopover-miner-mcp.ts -- to import.meta.resolve()/self-referencing
require() against the published package name instead. The one
remaining depth-guessing fallback (lib/status.ts's monorepo-sibling
loopover-engine lookup) is intentionally left as-is: it's a
last-resort fallback for when real node_modules resolution has already
failed, so a self-referencing lookup (which uses the identical
resolution mechanism) wouldn't diversify the fallback at all -- trying
both plausible sibling-directory depths is the actually-correct
strategy for that specific case, not a shortcut.

Validated: typecheck clean, both packages rebuild cleanly, full
unsharded suite still 21,541/21,541 passing, and both self-referencing
subpaths resolve correctly via direct node -e checks.

Author: JSONbored

packages/loopover-mcp/bin/loopover-mcp.ts

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { buildFeasibilityVerdict, buildPrTextLint, buildGateDispositions, buildPublicPrBodyDraft } from "@loopover/engine";
@@ -48,25 +48,24 @@ import { redactKnownLocalPaths, redactLocalPath } from "../lib/redact-local-path
 // side by side unaliased would read as the same function (#6238).
 import { recordMcpToolCall as recordLocalMcpToolCall } from "../lib/telemetry.js";
 
-// Path to a file next to this package's own root, computed relative to THIS module's own on-disk
-// location -- which differs by one directory level depending on how this file is currently running:
-// imported in-process (e.g. by the vitest unit tests that exercise the CLI dispatcher + stdio tools
-// directly against bin/loopover-mcp.ts, per the invokedPath check below) resolves relative to the
-// real source bin/, while a real CLI invocation resolves relative to the compiled dist/bin/ (one
-// level deeper, since the 2026-07-24 dist/ migration; see tsconfig.json's outDir comment). A single
-// hardcoded relative depth can only ever be correct for one of those two contexts, so this tries
-// both, preferring whichever the current on-disk layout actually has.
-function resolveOwnPackageSiblingPath(...segments: string[]): URL {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const fromBin = join(here, "..", ...segments);
-  if (existsSync(fromBin)) return pathToFileURL(fromBin);
-  return pathToFileURL(join(here, "..", "..", ...segments));
+// Self-referencing package import (Node's own mechanism for "resolve a file that belongs to my own
+// package, correctly, regardless of my own current location on disk") -- requires the "exports" map
+// in this package's own package.json (the "./x": "./x" entries there are what make this resolvable
+// at all). Robust by construction, not by guessing: whether this file is running as the real source
+// bin/loopover-mcp.ts (imported in-process by tests that exercise the CLI dispatcher + stdio tools
+// directly, per the invokedPath check below) or as the compiled dist/bin/loopover-mcp.js (a real CLI
+// invocation), import.meta.resolve walks up from THIS file's own location through node_modules the
+// same way any external consumer's "@loopover/mcp/..." import would, landing on the one real
+// package.json/CHANGELOG.md either way -- no relative-depth arithmetic, so a future directory move
+// can never silently break this again the way the pre-dist/-migration relative path did.
+function resolveOwnPackageFile(specifier: string): URL {
+  return new URL(import.meta.resolve(specifier));
 }
 
 // Read name/version from this package's own package.json (always present in any install --
 // global, npx, or local -- npm ships it regardless of the "files" allowlist) instead of hand-synced
 // literals, so a release bump never has a second place to forget.
-const ownPackageJson = JSON.parse(readFileSync(resolveOwnPackageSiblingPath("package.json"), "utf8"));
+const ownPackageJson = JSON.parse(readFileSync(resolveOwnPackageFile("@loopover/mcp/package.json"), "utf8"));
 
 const defaultApiUrl = "https://api.loopover.ai";
 const legacyDefaultApiUrls = new Set([
@@ -86,7 +85,7 @@ const decisionPackCacheSchemaVersion = 1;
 const decisionPackCacheMaxEntries = 25;
 const decisionPackCacheMaxBytes = 512 * 1024;
 const cliTextFileMaxBytes = 1024 * 1024;
-const changelogPath = resolveOwnPackageSiblingPath("CHANGELOG.md");
+const changelogPath = resolveOwnPackageFile("@loopover/mcp/CHANGELOG.md");
 const cliArgs = process.argv.slice(2);
 
 // #7764: true only when this file is the process entrypoint (`node .../loopover-mcp.js`, incl. via the npm

packages/loopover-mcp/package.json

@@ -28,6 +28,10 @@
   "bin": {
     "loopover-mcp": "dist/bin/loopover-mcp.js"
   },
+  "exports": {
+    "./package.json": "./package.json",
+    "./CHANGELOG.md": "./CHANGELOG.md"
+  },
   "files": [
     "dist",
     "scripts",

packages/loopover-miner/bin/loopover-miner-mcp.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import { readFileSync, realpathSync } from "node:fs";
-import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -52,12 +51,17 @@ import { captureMinerErrorAndFlush, initMinerSentry } from "../lib/sentry.js";
 //     from ORB's hosted, maintainer-authenticated loopover_get_outcome_calibration tool.
 
 // Read the version from this package's own package.json (always shipped) rather than a hand-synced
-// literal, so a release bump never has a second place to forget -- same approach as the mcp harness.
-// Resolve via fileURLToPath(import.meta.url) (a string) rather than `new URL(...)` so the path never
-// materializes as a `URL` object -- the repo-root tsconfig this file is also checked under (its type
-// surface is imported by the MCP unit tests) resolves the global `URL` to a shape whose iterator lacks
-// `[Symbol.dispose]`, which readFileSync's node typings reject; a plain string sidesteps that entirely.
-const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "../package.json");
+// literal, so a release bump never has a second place to forget. Self-referencing package import
+// (requires the "exports" map in this package's own package.json) -- robust by construction to
+// however this file is currently running, whether as the real source bin/loopover-miner-mcp.ts
+// (imported in-process by test/unit/miner-mcp-*.test.ts) or the compiled dist/bin/loopover-miner-mcp.js
+// (a real CLI invocation): import.meta.resolve walks up from THIS file's own location through
+// node_modules the same way an external "@loopover/miner/..." import would, landing on the one real
+// package.json either way -- no relative-path arithmetic to break if this file ever moves again.
+// fileURLToPath (a plain string), not `new URL(...)` -- the repo-root tsconfig this file is also
+// checked under (its type surface is imported by the MCP unit tests) resolves the global `URL` to a
+// shape whose iterator lacks `[Symbol.dispose]`, which readFileSync's node typings reject.
+const packageJsonPath = fileURLToPath(import.meta.resolve("@loopover/miner/package.json"));
 const ownPackageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 
 /** Optional filters accepted by loopover_miner_get_audit_feed (#5158). */

packages/loopover-miner/lib/status.ts

@@ -132,7 +132,7 @@ export function buildEngineVersionDisplay(readInstalled: () => string | null = r
   if (installed) return installed;
   try {
     /* v8 ignore next -- package.json declares @loopover/engine in every supported miner build */
-    return (requireFromHere()("../package.json") as PackageJsonShape).dependencies?.[ENGINE_PACKAGE] ?? null;
+    return (requireFromHere()("@loopover/miner/package.json") as PackageJsonShape).dependencies?.[ENGINE_PACKAGE] ?? null;
   } catch {
     /* v8 ignore next -- import metadata/package resolution failure is bundler-only; normal Node tests resolve it */
     return null;
@@ -275,7 +275,7 @@ function checkEngineVersionSkew(): DoctorCheck {
 
 /** The minimum Node major version from the package's `engines.node` floor (e.g. ">=22.13.0" → 22). */
 function requiredNodeMajor(): number {
-  const engines = (requireFromHere()("../package.json") as PackageJsonShape).engines;
+  const engines = (requireFromHere()("@loopover/miner/package.json") as PackageJsonShape).engines;
   /* v8 ignore next -- package.json's required engines.node is a build-time invariant */
   const match = typeof engines?.node === "string" ? engines.node.match(/(\d+)/) : null;
   /* v8 ignore next -- a matching engines.node floor always includes the captured major */

packages/loopover-miner/lib/version.ts

@@ -1,4 +1,10 @@
-import ownPackageJson from "../package.json" with { type: "json" };
+// Self-referencing package import (requires the "exports" map in this package's own package.json) --
+// robust by construction to however this file is currently running, whether as the real source
+// lib/version.ts (imported in-process by tests) or the compiled dist/lib/version.js (a real CLI
+// invocation): resolution walks up from THIS file's own location through node_modules the same way an
+// external "@loopover/miner/..." import would, landing on the one real package.json either way -- no
+// relative-path arithmetic to break if this file ever moves again.
+import ownPackageJson from "@loopover/miner/package.json" with { type: "json" };
 
 /** Package.json semver at import time — the laptop npm-install default. */
 export const MINER_PACKAGE_VERSION: string = ownPackageJson.version;