@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/project-inspection.mjs

@@ -0,0 +1,227 @@
+import { createHash } from 'node:crypto';
+
+import { getRuntimeProfile } from './runtime-profile.mjs';
+import { projectRouteKey } from './projects/trusted-roots-projects.mjs';
+
+const DEFAULT_LIST_LIMIT = 50;
+const MAX_LIST_LIMIT = 200;
+const CURSOR_VERSION = 1;
+
+export const PROJECT_INSPECTION_VIEWS = Object.freeze([
+  'summary',
+  'tree',
+  'git_status',
+  'git_diff',
+  'readme',
+  'package'
+]);
+
+function boundedInteger(value, fallback, min, max, label) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw new Error(`Invalid ${label}: ${value}. Expected an integer from ${min} to ${max}.`);
+  }
+  return number;
+}
+
+function cursorVersion(kind, parts) {
+  return createHash('sha256').update(`${kind}\n${parts.join('\n')}`).digest('base64url').slice(0, 16);
+}
+
+function encodeCursor(kind, offset, version) {
+  return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, kind, offset, version }), 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor, { kind, version }) {
+  if (!cursor) return 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('Invalid cursor: expected an opaque cursor returned by the previous page.');
+  }
+  if (
+    parsed?.v !== CURSOR_VERSION ||
+    parsed?.kind !== kind ||
+    parsed?.version !== version ||
+    !Number.isInteger(parsed?.offset) ||
+    parsed.offset < 0
+  ) {
+    throw new Error('Invalid or stale cursor: request parameters or catalog version changed.');
+  }
+  return parsed.offset;
+}
+
+function projectPathExposure(context = {}) {
+  if (typeof context.exposePaths === 'boolean') return context.exposePaths;
+  return Boolean(
+    context.projectRegistry?.exposeProjectPaths ||
+    context.env?.MCP_EXPOSE_PROJECT_PATHS === 'true'
+  );
+}
+
+function projectLookupError(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  return error;
+}
+
+function visibleDevices(context = {}) {
+  if (typeof context.listVisibleDevices === 'function') {
+    const devices = context.listVisibleDevices();
+    return Array.isArray(devices) ? devices : [];
+  }
+  return Array.isArray(context.devices) ? context.devices : [];
+}
+
+function requireVisibleOnlineDevice(context, deviceId) {
+  const id = String(deviceId || '').trim();
+  if (!id) throw projectLookupError('DEVICE_ID_REQUIRED', 'device_id is required.');
+  const device = visibleDevices(context).find(item => String(item?.deviceId || '').trim() === id);
+  if (!device) throw projectLookupError('DEVICE_NOT_FOUND', `Unknown or unavailable device_id: ${id}`);
+  if (device.revoked || !device.online) throw projectLookupError('DEVICE_OFFLINE', `Device ${id} is offline or revoked.`);
+  return device;
+}
+
+function getProject(projectRegistry, deviceId, projectId) {
+  const id = String(projectId || '').trim();
+  if (!id) throw projectLookupError('PROJECT_ID_REQUIRED', 'project_id is required.');
+  const project = projectRegistry?.projectRoutes?.get(projectRouteKey(deviceId, id));
+  if (!project) throw projectLookupError('PROJECT_DEVICE_MISMATCH', `project_id ${id} is not configured for device_id ${deviceId}.`);
+  return project;
+}
+
+export function resolveProjectRoute(context = {}, { deviceId, projectId } = {}) {
+  const normalizedDeviceId = String(deviceId || '').trim();
+  requireVisibleOnlineDevice(context, normalizedDeviceId);
+  return getProject(context.projectRegistry, normalizedDeviceId, projectId);
+}
+
+function projectListItem(project, projectRegistry, exposePaths) {
+  const item = {
+    device_id: project.deviceId,
+    project_id: project.projectId,
+    displayName: project.displayName,
+    default: projectRegistry?.defaultProjectId === project.projectId
+  };
+  if (exposePaths) item.repoRoot = project.repoRoot;
+  return item;
+}
+
+export function listProjects(context = {}, options = {}) {
+  const projectRegistry = context.projectRegistry;
+  const exposePaths = projectPathExposure(context);
+  const deviceId = String(options.device_id ?? options.deviceId ?? '').trim();
+  requireVisibleOnlineDevice(context, deviceId);
+  const query = String(options.query || '').trim().toLowerCase();
+  const limit = boundedInteger(options.limit, DEFAULT_LIST_LIMIT, 1, MAX_LIST_LIMIT, 'limit');
+  const all = [...(projectRegistry?.projectRoutes?.values() || [])]
+    .filter(project => project.deviceId === deviceId);
+  const matched = all
+    .map(project => {
+      const id = String(project.projectId || '').toLowerCase();
+      const display = String(project.displayName || '').toLowerCase();
+      const exact = query && (id === query || display === query);
+      const contains = !query || id.includes(query) || display.includes(query);
+      return { project, exact, contains };
+    })
+    .filter(entry => entry.contains)
+    .sort((a, b) => {
+      if (a.exact !== b.exact) return a.exact ? -1 : 1;
+      return a.project.projectId.localeCompare(b.project.projectId);
+    });
+  const version = cursorVersion('projects', [
+    deviceId,
+    query,
+    ...matched.map(entry => `${entry.project.projectId}:${entry.project.displayName}`)
+  ]);
+  const offset = decodeCursor(options.cursor, { kind: 'projects', version });
+  if (offset > matched.length) throw new Error('Invalid or stale cursor: project offset is outside the current result set.');
+  const page = matched.slice(offset, offset + limit);
+  const nextOffset = offset + page.length;
+  const truncated = nextOffset < matched.length;
+  return {
+    items: page.map(entry => projectListItem(entry.project, projectRegistry, exposePaths)),
+    truncated,
+    nextCursor: truncated ? encodeCursor('projects', nextOffset, version) : null,
+    total: matched.length,
+    pathExposure: exposePaths
+  };
+}
+
+function projectRelativePath(encodedPath) {
+  const decoded = decodeURIComponent(encodedPath || '');
+  const portable = decoded.replaceAll('\\', '/');
+  if (!decoded || portable.startsWith('/') || /^[A-Za-z]:\//.test(portable) || portable.split('/').includes('..')) {
+    throw new Error('Invalid project-relative resource path.');
+  }
+  return decoded;
+}
+
+function remoteInspectionArguments(project, view, options = {}) {
+  const args = {
+    device_id: project.deviceId,
+    path: project.repoRoot,
+    project_id: project.projectId,
+    view
+  };
+  if (view === 'tree') {
+    if (options.depth !== undefined) args.depth = options.depth;
+    if (options.limit !== undefined) args.limit = options.limit;
+    if (options.cursor !== undefined) args.cursor = options.cursor;
+  }
+  if (view === 'git_diff' && options.staged !== undefined) args.staged = options.staged === true;
+  return args;
+}
+
+function shapeInspectionResult(project, context, view, remote = {}) {
+  const identity = { device_id: project.deviceId, project_id: project.projectId };
+  if (view === 'summary') {
+    const result = {
+      ...identity,
+      displayName: project.displayName,
+      defaultRootName: remote.defaultRootName || project.projectId,
+      default: context.projectRegistry?.defaultProjectId === project.projectId,
+      hasPackageJson: Boolean(remote.hasPackageJson),
+      hasReadme: Boolean(remote.hasReadme),
+      runtimeProfile: getRuntimeProfile(context.env || process.env).name
+    };
+    if (projectPathExposure(context)) result.repoRoot = project.repoRoot;
+    return result;
+  }
+  return { ...identity, ...remote };
+}
+
+export async function readProjectResourceFile(context = {}, { deviceId, projectId, encodedPath } = {}) {
+  const project = resolveProjectRoute(context, { deviceId, projectId });
+  if (typeof context.callDeviceTool !== 'function') {
+    throw projectLookupError('DEVICE_EXECUTION_UNAVAILABLE', 'Project file access requires device execution routing.');
+  }
+  const remote = await context.callDeviceTool('project_inspect', {
+    device_id: project.deviceId,
+    path: project.repoRoot,
+    project_id: project.projectId,
+    view: 'file',
+    relative_path: projectRelativePath(encodedPath)
+  });
+  if (!remote || typeof remote.text !== 'string') throw new Error('Invalid project file response from device.');
+  return remote.text;
+}
+
+export async function inspectProject(context = {}, options = {}) {
+  const view = String(options.view || 'summary');
+  if (!PROJECT_INSPECTION_VIEWS.includes(view)) {
+    throw new Error(`Invalid project inspection view: ${view}. Expected one of: ${PROJECT_INSPECTION_VIEWS.join(', ')}.`);
+  }
+  const deviceId = String(options.deviceId ?? options.device_id ?? '').trim();
+  const project = resolveProjectRoute(context, { deviceId, projectId: options.projectId ?? options.project_id });
+  if (typeof context.callDeviceTool !== 'function') {
+    throw projectLookupError('DEVICE_EXECUTION_UNAVAILABLE', 'Project inspection requires device execution routing.');
+  }
+  const remote = await context.callDeviceTool('project_inspect', remoteInspectionArguments(project, view, options));
+  if (!remote || typeof remote !== 'object' || Array.isArray(remote)) {
+    throw new Error('Invalid project inspection response from device.');
+  }
+  return shapeInspectionResult(project, context, view, remote);
+}

package/control-plane/scripts/projects/project-id.mjs

@@ -0,0 +1,69 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+export const PROJECT_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+export function normalizeProjectId(value) {
+  return String(value ?? '').trim();
+}
+
+export function isValidProjectId(value) {
+  const projectId = normalizeProjectId(value);
+  return PROJECT_ID_PATTERN.test(projectId) && !projectId.includes('/') && !projectId.includes('\\') && !projectId.includes(':');
+}
+
+export function assertValidProjectId(value) {
+  const projectId = normalizeProjectId(value);
+  if (!isValidProjectId(projectId)) {
+    const error = new Error(`Invalid projectId: ${value}`);
+    error.code = 'INVALID_PROJECT_ID';
+    error.details = {
+      projectId: value,
+      pattern: PROJECT_ID_PATTERN.source
+    };
+    throw error;
+  }
+  return projectId;
+}
+
+export function slugifyProjectId(value) {
+  const slug = String(value ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+|[._-]+$/g, '')
+    .replace(/-{2,}/g, '-')
+    .slice(0, 64);
+
+  return isValidProjectId(slug) ? slug : 'project';
+}
+
+function shortPathHash(rootPath) {
+  return crypto.createHash('sha1').update(path.resolve(String(rootPath))).digest('hex').slice(0, 8);
+}
+
+function finalPathSegments(rootPath) {
+  const resolved = path.resolve(String(rootPath));
+  const parsed = path.parse(resolved);
+  const relative = resolved.slice(parsed.root.length);
+  return relative.split(/[\\/]+/).filter(Boolean);
+}
+
+export function generateProjectIdForRoot(rootPath, usedProjectIds = new Set()) {
+  const used = usedProjectIds instanceof Set ? usedProjectIds : new Set(usedProjectIds || []);
+  const segments = finalPathSegments(rootPath);
+  const folder = segments.at(-1) || 'project';
+  const parent = segments.at(-2);
+
+  const candidates = [slugifyProjectId(folder)];
+  if (parent) candidates.push(slugifyProjectId(`${parent}-${folder}`));
+
+  for (const candidate of candidates) {
+    if (!used.has(candidate)) return candidate;
+  }
+
+  const base = candidates.at(-1) || 'project';
+  const suffix = shortPathHash(rootPath);
+  const maxBaseLength = 64 - suffix.length - 1;
+  return `${base.slice(0, maxBaseLength).replace(/[._-]+$/g, '')}-${suffix}`;
+}

package/control-plane/scripts/projects/trusted-roots-projects.mjs

@@ -0,0 +1,375 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as toml from 'smol-toml';
+
+import {
+  assertValidProjectId,
+  generateProjectIdForRoot,
+  normalizeProjectId
+} from './project-id.mjs';
+
+function cleanRootPath(rootPath) {
+  return String(rootPath ?? '')
+    .trim()
+    .replace(/^[']|[']$/g, '')
+    .replace(/^["]|["]$/g, '')
+    .replace(/^\\\\\?\\/, '');
+}
+
+function isWindowsDrivePath(rootPath) {
+  return /^[A-Za-z]:[\\/]/.test(String(rootPath || ''));
+}
+
+function normalizeRootPath(rootPath) {
+  const cleaned = cleanRootPath(rootPath);
+  if (process.platform !== 'win32' && isWindowsDrivePath(cleaned)) {
+    return cleaned.replace(/\\/g, '/');
+  }
+  return path.resolve(cleaned);
+}
+
+function isInsideRoot(candidatePath, rootPath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function normalizeDeviceId(value) {
+  const deviceId = String(value || '').trim();
+  if (!deviceId) return undefined;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(deviceId)) {
+    const error = new Error(`Invalid device_id: ${deviceId}`);
+    error.code = 'INVALID_DEVICE_ID';
+    throw error;
+  }
+  return deviceId;
+}
+
+export function projectRouteKey(deviceId, projectId) {
+  return `${String(deviceId || '').trim()}\u0000${String(projectId || '').trim()}`;
+}
+
+export function trustedRootEntryToLine(entry, context = {}) {
+  if (typeof entry === 'string') return expandTrustedRootPlaceholders(entry, context);
+  if (!entry || typeof entry !== 'object') return '';
+  const rawRoot = entry.path ?? entry.root;
+  if (!rawRoot) return '';
+  const root = expandTrustedRootPlaceholders(String(rawRoot), context);
+  const projectId = entry.project_id ?? entry.projectId;
+  const displayName = entry.display_name ?? entry.displayName;
+  const deviceId = entry.device_id ?? entry.deviceId;
+  const fields = [root];
+  if (projectId !== undefined || displayName !== undefined || deviceId !== undefined) fields.push(projectId === undefined ? '' : String(projectId));
+  if (displayName !== undefined || deviceId !== undefined) fields.push(displayName === undefined ? '' : String(displayName));
+  if (deviceId !== undefined) fields.push(String(deviceId));
+  return fields.join(' | ');
+}
+
+export function trustedRootsTomlToRaw(trustedRootsRaw, context = {}) {
+  if (!trustedRootsRaw) return '';
+  const entries = Array.isArray(trustedRootsRaw.roots) ? trustedRootsRaw.roots : [];
+  return entries.map(entry => trustedRootEntryToLine(entry, context)).filter(Boolean).join('\n');
+}
+
+export function expandTrustedRootPlaceholders(value, { repoRoot = process.cwd(), home = process.env.HOME || process.env.USERPROFILE || '' } = {}) {
+  return String(value).replace(/\$\{([^}]+)\}/g, (match, name) => {
+    if (name === 'repoRoot') return repoRoot;
+    if (name === 'home') return home;
+    return match;
+  });
+}
+
+export function loadUnifiedMcpTomlConfig(configPath) {
+  if (!configPath || !fs.existsSync(configPath)) return {};
+  return toml.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+export function defaultUnifiedMcpConfigPath(repoRoot = process.cwd()) {
+  return path.resolve(repoRoot, 'config/mcp-servers.toml');
+}
+
+export function findUnifiedMcpConfigPath(env = process.env, repoRoot = process.cwd()) {
+  if (String(env.MCP_UPSTREAM_CONFIG || '').trim()) {
+    const value = String(env.MCP_UPSTREAM_CONFIG).trim().replace(/^['"]|['"]$/g, '');
+    return path.isAbsolute(value) ? path.resolve(value) : path.resolve(repoRoot, value);
+  }
+  const candidate = defaultUnifiedMcpConfigPath(repoRoot);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
+export function trustedRootsRawFromSources({ rawConfig = {}, repoRoot = process.cwd() } = {}) {
+  return trustedRootsTomlToRaw(rawConfig.trusted_roots, { repoRoot });
+}
+
+export function loadTrustedRootsRawFromUnifiedConfig({ env = process.env, repoRoot = process.cwd() } = {}) {
+  const configPath = findUnifiedMcpConfigPath(env, repoRoot);
+  const rawConfig = loadUnifiedMcpTomlConfig(configPath);
+  return trustedRootsRawFromSources({ rawConfig, env, repoRoot });
+}
+
+export function splitTrustedRootConfig(rawValue) {
+  return String(rawValue || '')
+    .split(/[\r\n;]+/)
+    .map(entry => entry.trim())
+    .filter(entry => entry && !entry.startsWith('#'));
+}
+
+export function resolveTrustedRootPaths(rawValue, fallbackRoot) {
+  const roots = [];
+  if (fallbackRoot) {
+    roots.push(normalizeRootPath(fallbackRoot));
+  }
+
+  for (const entry of splitTrustedRootConfig(rawValue)) {
+    const parsed = parseTrustedRootLine(entry);
+    if (parsed?.root) {
+      roots.push(parsed.root);
+    }
+  }
+
+  const resolvedRoots = [...new Set(roots)];
+  const existingRoots = [];
+  const missingRoots = [];
+  for (const root of resolvedRoots) {
+    if (fs.existsSync(root)) {
+      existingRoots.push(root);
+    } else {
+      missingRoots.push(root);
+    }
+  }
+
+  if (existingRoots.length === 0) {
+    throw new Error(`No trusted roots exist. Configured roots: ${resolvedRoots.join('; ')}`);
+  }
+
+  return { existingRoots, missingRoots, resolvedRoots };
+}
+
+export function parseTrustedRootLine(line, options = {}) {
+  const lineNumber = options.lineNumber;
+  const raw = String(line ?? '');
+  const trimmed = raw.trim();
+
+  if (!trimmed || trimmed.startsWith('#')) {
+    return null;
+  }
+
+  const parts = raw.split('|').map(part => part.trim());
+  if (parts.length > 4) {
+    const error = new Error(`Invalid trusted root line${lineNumber ? ` ${lineNumber}` : ''}: expected at most 4 pipe-separated fields`);
+    error.code = 'INVALID_TRUSTED_ROOT_LINE';
+    error.details = { line, lineNumber };
+    throw error;
+  }
+
+  const root = cleanRootPath(parts[0]);
+  if (!root) {
+    const error = new Error(`Invalid trusted root line${lineNumber ? ` ${lineNumber}` : ''}: missing path`);
+    error.code = 'INVALID_TRUSTED_ROOT_LINE';
+    error.details = { line, lineNumber };
+    throw error;
+  }
+
+  if (!path.isAbsolute(root) && !isWindowsDrivePath(root)) {
+    const error = new Error(`Trusted root must be absolute: ${root}`);
+    error.code = 'TRUSTED_ROOT_MUST_BE_ABSOLUTE';
+    error.details = { root, lineNumber };
+    throw error;
+  }
+
+  const resolvedRoot = normalizeRootPath(root);
+  const explicitProjectId = parts.length >= 2 && parts[1] !== '';
+  const projectId = explicitProjectId ? assertValidProjectId(parts[1]) : undefined;
+  const displayName = parts.length >= 3 && parts[2] !== '' ? parts[2] : undefined;
+  const explicitDeviceId = parts.length >= 4 && parts[3] !== '';
+  const deviceId = explicitDeviceId ? normalizeDeviceId(parts[3]) : undefined;
+
+  return {
+    rawLine: raw,
+    lineNumber,
+    root: resolvedRoot,
+    projectId,
+    displayName,
+    deviceId,
+    explicitProjectId,
+    explicitDeviceId
+  };
+}
+
+export function normalizeTrustedRootEntries(linesOrEntries, options = {}) {
+  const entries = [];
+  const usedGeneratedIds = new Set();
+  const explicitIds = new Set();
+  const seenRoots = new Set();
+
+  const parsedEntries = linesOrEntries.map((item, index) => {
+    if (typeof item === 'string') return parseTrustedRootLine(item, { lineNumber: index + 1 });
+    return item;
+  }).filter(Boolean);
+
+  for (const entry of parsedEntries) {
+    const root = normalizeRootPath(entry.root);
+    const deviceId = normalizeDeviceId(entry.deviceId ?? entry.device_id);
+    const normalizedRootKey = process.platform === 'win32' ? root.toLowerCase() : root;
+    const rootKey = `${deviceId || ''}\u0000${normalizedRootKey}`;
+    if (seenRoots.has(rootKey)) continue;
+    seenRoots.add(rootKey);
+
+    let projectId;
+    const explicitProjectId = Boolean(entry.explicitProjectId || entry.projectId);
+    if (entry.projectId) {
+      projectId = assertValidProjectId(entry.projectId);
+      explicitIds.add(projectId);
+    } else {
+      projectId = generateProjectIdForRoot(root, new Set([...explicitIds, ...usedGeneratedIds]));
+      usedGeneratedIds.add(projectId);
+    }
+
+    entries.push({
+      ...entry,
+      root,
+      projectId,
+      deviceId,
+      displayName: entry.displayName || projectId,
+      explicitProjectId,
+      explicitDeviceId: Boolean(entry.explicitDeviceId || deviceId)
+    });
+  }
+
+  return entries;
+}
+
+export function buildTrustedRootsProjectRegistry(entries, options = {}) {
+  const normalizedEntries = normalizeTrustedRootEntries(entries, options);
+  const legacyProjects = new Map();
+  const projectRoutes = new Map();
+  const missingRoots = [];
+
+  function addEntry(target, key, entry) {
+    const existing = target.get(key);
+    if (!existing) {
+      target.set(key, {
+        projectId: entry.projectId,
+        deviceId: entry.deviceId || null,
+        displayName: entry.displayName,
+        repoRoot: entry.root,
+        trustedRoots: [entry.root],
+        extraTrustedRoots: [],
+        explicitProjectId: entry.explicitProjectId,
+        explicitDeviceId: entry.explicitDeviceId
+      });
+      return;
+    }
+    if (!existing.trustedRoots.includes(entry.root)) {
+      existing.trustedRoots.push(entry.root);
+      existing.extraTrustedRoots.push(entry.root);
+    }
+    existing.explicitProjectId = existing.explicitProjectId || entry.explicitProjectId;
+    existing.explicitDeviceId = existing.explicitDeviceId || entry.explicitDeviceId;
+  }
+
+  for (const entry of normalizedEntries) {
+    if (options.checkExists && !fs.existsSync(entry.root)) {
+      missingRoots.push(entry.root);
+      if (options.missingRootMode === 'error') {
+        const error = new Error(`Trusted root does not exist: ${entry.root}`);
+        error.code = 'TRUSTED_ROOT_NOT_FOUND';
+        error.details = { root: entry.root };
+        throw error;
+      }
+    }
+
+    if (entry.deviceId) {
+      addEntry(projectRoutes, projectRouteKey(entry.deviceId, entry.projectId), entry);
+    } else {
+      addEntry(legacyProjects, entry.projectId, entry);
+    }
+  }
+
+  // Legacy project-only lookup remains available only when the id identifies
+  // exactly one route. Ambiguous ids deliberately have no project-only entry.
+  const projects = new Map(legacyProjects);
+  const routesByProjectId = new Map();
+  for (const route of projectRoutes.values()) {
+    const routes = routesByProjectId.get(route.projectId) || [];
+    routes.push(route);
+    routesByProjectId.set(route.projectId, routes);
+  }
+  const ambiguousProjectIds = new Set();
+  for (const [projectId, routes] of routesByProjectId) {
+    if (legacyProjects.has(projectId) || routes.length !== 1) {
+      projects.delete(projectId);
+      ambiguousProjectIds.add(projectId);
+    } else {
+      projects.set(projectId, routes[0]);
+    }
+  }
+
+  const allTrustedRoots = [...new Set(normalizedEntries.map(entry => entry.root))];
+  const rootIndex = [];
+  for (const project of projects.values()) {
+    for (const root of project.trustedRoots) {
+      rootIndex.push({ projectId: project.projectId, deviceId: project.deviceId, root });
+    }
+  }
+  rootIndex.sort((a, b) => b.root.length - a.root.length);
+
+  const requestedDefault = normalizeProjectId(options.defaultProjectId || '');
+  const defaultProjectId = requestedDefault || normalizedEntries[0]?.projectId;
+
+  return {
+    mode: 'trusted-roots-projects',
+    defaultProjectId,
+    requireProjectId: Boolean(options.requireProjectId),
+    pathInference: options.pathInference !== false,
+    exposeProjectPaths: Boolean(options.exposeProjectPaths),
+    projects,
+    projectRoutes,
+    ambiguousProjectIds,
+    rootIndex,
+    allTrustedRoots,
+    missingRoots
+  };
+}
+
+export function buildTrustedRootsProjectRegistryFromRaw(rawValue, options = {}) {
+  const configuredEntries = splitTrustedRootConfig(rawValue);
+  const fallbackEntries = options.fallbackRoot ? [options.fallbackRoot] : [];
+  return buildTrustedRootsProjectRegistry(configuredEntries.length > 0 ? configuredEntries : fallbackEntries, options);
+}
+
+export function loadTrustedRootsProjectRegistry(configPath, options = {}) {
+  const content = fs.readFileSync(configPath, 'utf8');
+  return buildTrustedRootsProjectRegistry(content.split(/\r?\n/), options);
+}
+
+export function listProjectSummaries(registry, options = {}) {
+  const showPaths = Boolean(options.showPaths && registry.exposeProjectPaths);
+  const projects = [...registry.projects.values()].map(project => {
+    const summary = {
+      projectId: project.projectId,
+      displayName: project.displayName
+    };
+    if (showPaths) {
+      summary.repoRoot = project.repoRoot;
+      summary.trustedRoots = [...project.trustedRoots];
+    }
+    return summary;
+  });
+
+  return {
+    defaultProjectId: registry.defaultProjectId,
+    requireProjectId: registry.requireProjectId,
+    pathInference: registry.pathInference,
+    exposeProjectPaths: registry.exposeProjectPaths,
+    projects,
+    warnings: options.showPaths && !registry.exposeProjectPaths
+      ? ['Path exposure is disabled. Set MCP_EXPOSE_PROJECT_PATHS=true to include local paths.']
+      : []
+  };
+}
+
+export function inferProjectIdFromPath(registry, candidatePath) {
+  const resolved = normalizeRootPath(candidatePath);
+  const match = registry.rootIndex.find(entry => isInsideRoot(resolved, entry.root));
+  return match?.projectId;
+}