feat(runtime): Add portable resource root resolution

Add a shared resource-root resolver that prioritizes XCODEBUILDMCP_RESOURCE_ROOT, then executable-relative paths, then package-root fallback for npm/source installs. Route manifest and bundled AXe path discovery through the shared resolver so portable distributions and existing workflows use the same deterministic contract.

Also export DYLD_FRAMEWORK_PATH for bundled AXe execution and add tests that cover resource-root precedence and bundled framework environment behavior.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: cameroncooke

src/core/__tests__/resource-root.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  getBundledAxePath,
+  getBundledFrameworksDir,
+  getManifestsDir,
+  getResourceRoot,
+} from '../resource-root.ts';
+
+describe('resource-root', () => {
+  let originalExecPath: string;
+  let originalResourceRoot: string | undefined;
+  let tempDir: string;
+
+  beforeEach(() => {
+    originalExecPath = process.execPath;
+    originalResourceRoot = process.env.XCODEBUILDMCP_RESOURCE_ROOT;
+    tempDir = mkdtempSync(join(tmpdir(), 'xbmcp-resource-root-'));
+  });
+
+  afterEach(() => {
+    process.execPath = originalExecPath;
+    if (originalResourceRoot === undefined) {
+      delete process.env.XCODEBUILDMCP_RESOURCE_ROOT;
+    } else {
+      process.env.XCODEBUILDMCP_RESOURCE_ROOT = originalResourceRoot;
+    }
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('uses XCODEBUILDMCP_RESOURCE_ROOT when set', () => {
+    const explicitRoot = join(tempDir, 'explicit-root');
+    process.env.XCODEBUILDMCP_RESOURCE_ROOT = explicitRoot;
+
+    expect(getResourceRoot()).toBe(resolve(explicitRoot));
+    expect(getManifestsDir()).toBe(join(resolve(explicitRoot), 'manifests'));
+    expect(getBundledAxePath()).toBe(join(resolve(explicitRoot), 'bundled', 'axe'));
+  });
+
+  it('falls back to executable-relative root when resources exist next to executable', () => {
+    delete process.env.XCODEBUILDMCP_RESOURCE_ROOT;
+    const executableRoot = join(tempDir, 'portable-install', 'libexec');
+    mkdirSync(join(executableRoot, 'manifests', 'tools'), { recursive: true });
+    process.execPath = join(executableRoot, 'xcodebuildmcp');
+
+    expect(getResourceRoot()).toBe(executableRoot);
+    expect(getBundledFrameworksDir()).toBe(join(executableRoot, 'bundled', 'Frameworks'));
+  });
+});

src/core/manifest/load-manifest.ts

@@ -5,7 +5,6 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 import {
   toolManifestEntrySchema,
@@ -14,78 +13,12 @@ import {
   type WorkflowManifestEntry,
   type ResolvedManifest,
 } from './schema.ts';
+import { getManifestsDir, getPackageRoot } from '../resource-root.ts';
 
 // Re-export types for consumers
 export type { ResolvedManifest, ToolManifestEntry, WorkflowManifestEntry };
 import { isValidPredicate } from '../../visibility/predicate-registry.ts';
-
-// Capture import.meta.url at module load time (before any CJS bundling issues)
-// This works because the value is captured when the module is first evaluated
-const importMetaUrl: string | undefined = ((): string | undefined => {
-  try {
-    // This will be undefined in CJS bundles but valid in ESM
-    return import.meta.url;
-  } catch {
-    return undefined;
-  }
-})();
-
-/**
- * Get the current file path, handling both ESM and CJS contexts.
- * Smithery bundles to CJS where import.meta.url is undefined.
- */
-function getCurrentFilePath(): string {
-  // ESM context - use captured import.meta.url
-  if (importMetaUrl) {
-    return fileURLToPath(importMetaUrl);
-  }
-
-  // CJS context (Smithery bundle) - __filename is shimmed by esbuild
-  if (typeof __filename !== 'undefined' && __filename) {
-    return __filename as string;
-  }
-
-  // Fallback: try to resolve from cwd
-  const cwd = process.cwd();
-  const possiblePaths = [
-    path.join(cwd, 'build', 'core', 'manifest', 'load-manifest.ts'),
-    path.join(cwd, 'src', 'core', 'manifest', 'load-manifest.ts'),
-  ];
-  for (const p of possiblePaths) {
-    if (fs.existsSync(p)) {
-      return p;
-    }
-  }
-
-  throw new Error('Cannot determine current file path in this runtime context');
-}
-
-/**
- * Get the package root directory.
- * Works correctly for both development and npx/npm installs.
- */
-export function getPackageRoot(): string {
-  // Start from this file's directory and go up to find package.json
-  const currentFile = getCurrentFilePath();
-  let dir = path.dirname(currentFile);
-
-  // Walk up until we find package.json
-  while (dir !== path.dirname(dir)) {
-    if (fs.existsSync(path.join(dir, 'package.json'))) {
-      return dir;
-    }
-    dir = path.dirname(dir);
-  }
-
-  throw new Error('Could not find package root (no package.json found in parent directories)');
-}
-
-/**
- * Get the manifests directory path.
- */
-export function getManifestsDir(): string {
-  return path.join(getPackageRoot(), 'manifests');
-}
+export { getManifestsDir, getPackageRoot } from '../resource-root.ts';
 
 /**
  * Load all YAML files from a directory.

src/core/resource-root.ts

@@ -0,0 +1,81 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RESOURCE_ROOT_ENV_VAR = 'XCODEBUILDMCP_RESOURCE_ROOT';
+
+function hasResourceLayout(root: string): boolean {
+  return fs.existsSync(path.join(root, 'manifests')) || fs.existsSync(path.join(root, 'bundled'));
+}
+
+function findPackageRootFrom(startDir: string): string | null {
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+export function getPackageRoot(): string {
+  const candidates: string[] = [];
+  candidates.push(path.dirname(fileURLToPath(import.meta.url)));
+  candidates.push(process.cwd());
+  const entry = process.argv[1];
+  if (entry) {
+    candidates.push(path.dirname(entry));
+  }
+
+  for (const candidate of candidates) {
+    const found = findPackageRootFrom(candidate);
+    if (found) {
+      return found;
+    }
+  }
+
+  throw new Error('Could not find package root (no package.json found in parent directories)');
+}
+
+function getExecutableResourceRoot(): string | null {
+  const execPath = process.execPath;
+  if (!execPath) {
+    return null;
+  }
+
+  const candidateDirs = [path.dirname(execPath), path.dirname(path.dirname(execPath))];
+  for (const candidate of candidateDirs) {
+    if (hasResourceLayout(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+export function getResourceRoot(): string {
+  const explicitRoot = process.env[RESOURCE_ROOT_ENV_VAR];
+  if (explicitRoot) {
+    return path.resolve(explicitRoot);
+  }
+
+  const executableRoot = getExecutableResourceRoot();
+  if (executableRoot) {
+    return executableRoot;
+  }
+
+  return getPackageRoot();
+}
+
+export function getManifestsDir(): string {
+  return path.join(getResourceRoot(), 'manifests');
+}
+
+export function getBundledAxePath(): string {
+  return path.join(getResourceRoot(), 'bundled', 'axe');
+}
+
+export function getBundledFrameworksDir(): string {
+  return path.join(getResourceRoot(), 'bundled', 'Frameworks');
+}

src/utils/__tests__/axe-helpers.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getBundledAxeEnvironment } from '../axe-helpers.ts';
+
+describe('axe-helpers', () => {
+  let originalResourceRoot: string | undefined;
+  let originalDyldFrameworkPath: string | undefined;
+  let tempDir: string;
+
+  beforeEach(() => {
+    originalResourceRoot = process.env.XCODEBUILDMCP_RESOURCE_ROOT;
+    originalDyldFrameworkPath = process.env.DYLD_FRAMEWORK_PATH;
+    tempDir = mkdtempSync(join(tmpdir(), 'xbmcp-axe-helpers-'));
+  });
+
+  afterEach(() => {
+    if (originalResourceRoot === undefined) {
+      delete process.env.XCODEBUILDMCP_RESOURCE_ROOT;
+    } else {
+      process.env.XCODEBUILDMCP_RESOURCE_ROOT = originalResourceRoot;
+    }
+
+    if (originalDyldFrameworkPath === undefined) {
+      delete process.env.DYLD_FRAMEWORK_PATH;
+    } else {
+      process.env.DYLD_FRAMEWORK_PATH = originalDyldFrameworkPath;
+    }
+
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('returns DYLD_FRAMEWORK_PATH when bundled axe is resolved from resource root', () => {
+    const resourceRoot = join(tempDir, 'portable-root');
+    const axePath = join(resourceRoot, 'bundled', 'axe');
+    const frameworksDir = join(resourceRoot, 'bundled', 'Frameworks');
+    mkdirSync(frameworksDir, { recursive: true });
+    writeFileSync(axePath, '');
+    process.env.XCODEBUILDMCP_RESOURCE_ROOT = resourceRoot;
+    delete process.env.DYLD_FRAMEWORK_PATH;
+
+    const env = getBundledAxeEnvironment();
+    expect(env).toEqual({
+      DYLD_FRAMEWORK_PATH: frameworksDir,
+    });
+  });
+
+  it('preserves existing DYLD_FRAMEWORK_PATH entries when using bundled axe', () => {
+    const resourceRoot = join(tempDir, 'portable-root');
+    const axePath = join(resourceRoot, 'bundled', 'axe');
+    const frameworksDir = join(resourceRoot, 'bundled', 'Frameworks');
+    mkdirSync(frameworksDir, { recursive: true });
+    writeFileSync(axePath, '');
+    process.env.XCODEBUILDMCP_RESOURCE_ROOT = resourceRoot;
+    process.env.DYLD_FRAMEWORK_PATH = '/existing/frameworks';
+
+    const env = getBundledAxeEnvironment();
+    expect(env).toEqual({
+      DYLD_FRAMEWORK_PATH: `${frameworksDir}:/existing/frameworks`,
+    });
+  });
+});

src/utils/axe-helpers.ts

@@ -6,12 +6,13 @@
  */
 
 import { accessSync, constants, existsSync } from 'fs';
-import { dirname, join, resolve, delimiter } from 'path';
+import { delimiter, join, resolve } from 'path';
 import { createTextResponse } from './validation.ts';
 import type { ToolResponse } from '../types/common.ts';
 import type { CommandExecutor } from './execution/index.ts';
 import { getDefaultCommandExecutor } from './execution/index.ts';
 import { getConfig } from './config-store.ts';
+import { getBundledAxePath, getBundledFrameworksDir } from '../core/resource-root.ts';
 
 export type AxeBinarySource = 'env' | 'bundled' | 'path';
 
@@ -20,19 +21,6 @@ export type AxeBinary = {
   source: AxeBinarySource;
 };
 
-function getPackageRoot(): string {
-  const entry = process.argv[1];
-  if (entry) {
-    const entryDir = dirname(entry);
-    return dirname(entryDir);
-  }
-  return process.cwd();
-}
-
-// In the npm package, build/index.js is at the same level as bundled/
-// So we go up one level from build/ to get to the package root
-const bundledAxePath = join(getPackageRoot(), 'bundled', 'axe');
-
 function isExecutable(path: string): boolean {
   try {
     accessSync(path, constants.X_OK);
@@ -50,14 +38,8 @@ function resolveAxePathFromConfig(): string | null {
 }
 
 function resolveBundledAxePath(): string | null {
-  const entry = process.argv[1];
   const candidates = new Set<string>();
-  if (entry) {
-    const entryDir = dirname(entry);
-    candidates.add(join(dirname(entryDir), 'bundled', 'axe'));
-    candidates.add(join(entryDir, 'bundled', 'axe'));
-  }
-  candidates.add(bundledAxePath);
+  candidates.add(getBundledAxePath());
   candidates.add(join(process.cwd(), 'bundled', 'axe'));
 
   for (const candidate of candidates) {
@@ -110,9 +92,22 @@ export function getAxePath(): string | null {
  * Get environment variables needed for bundled AXe to run
  */
 export function getBundledAxeEnvironment(): Record<string, string> {
-  // No special environment variables needed - bundled AXe binary
-  // has proper @rpath configuration to find frameworks
-  return {};
+  const resolved = resolveAxeBinary();
+  if (resolved?.source !== 'bundled') {
+    return {};
+  }
+
+  const frameworksDir = getBundledFrameworksDir();
+  if (!existsSync(frameworksDir)) {
+    return {};
+  }
+
+  const currentFrameworkPath = process.env.DYLD_FRAMEWORK_PATH;
+  const frameworkPath = currentFrameworkPath
+    ? `${frameworksDir}${delimiter}${currentFrameworkPath}`
+    : frameworksDir;
+
+  return { DYLD_FRAMEWORK_PATH: frameworkPath };
 }
 
 /**