smart-context-mcp 0.8.0

package/src/tools/smart-search.js

@@ -0,0 +1,412 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { rgPath } from '@vscode/ripgrep';
+import { buildMetrics, persistMetrics } from '../metrics.js';
+import { loadIndex, queryIndex, queryRelated } from '../index.js';
+import { projectRoot } from '../utils/paths.js';
+import { isBinaryBuffer, isDockerfile, resolveSafePath } from '../utils/fs.js';
+import { truncate } from '../utils/text.js';
+
+const execFile = promisify(execFileCallback);
+const supportedGlobs = [
+  '*.js', '*.jsx', '*.ts', '*.tsx', '*.json', '*.mjs', '*.cjs',
+  '*.py', '*.toml', '*.yaml', '*.yml', '*.md', '*.graphql', '*.gql', '*.sql',
+  '*.go', '*.rs', '*.java', '*.sh', '*.bash', '*.zsh', '*.tf', '*.tfvars', '*.hcl',
+  'Dockerfile', 'Dockerfile.*',
+];
+const ignoredDirs = ['node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.venv', 'venv', '__pycache__', '.terraform'];
+const ignoredFileNames = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb', 'npm-shrinkwrap.json']);
+const fallbackExtensions = new Set(['.js', '.jsx', '.ts', '.tsx', '.json', '.mjs', '.cjs', '.py', '.toml', '.yaml', '.yml', '.md', '.graphql', '.gql', '.sql', '.go', '.rs', '.java', '.sh', '.bash', '.zsh', '.tf', '.tfvars', '.hcl']);
+const likelySourceExtensions = new Set(['.js', '.jsx', '.ts', '.tsx', '.py', '.graphql', '.gql', '.sql', '.go', '.rs', '.java', '.sh', '.bash', '.zsh']);
+const likelyConfigExtensions = new Set(['.json', '.toml', '.yaml', '.yml', '.tf', '.tfvars', '.hcl']);
+const lowSignalNames = ['changelog', 'readme', 'migration', 'license', 'licence', 'contributing', 'authors', 'code_of_conduct', 'security', 'history'];
+const testPatterns = ['.test.', '.spec.', '__tests__', '__mocks__', 'fixtures'];
+
+export const VALID_INTENTS = new Set(['implementation', 'debug', 'tests', 'config', 'docs', 'explore']);
+
+export const intentWeights = {
+  implementation: { src: 10, source: 14, config: 4, lowSignal: -35, test: -15 },
+  debug:          { src: 10, source: 14, config: 4, lowSignal: -35, test: -15 },
+  tests:          { src: 5,  source: 10, config: 0, lowSignal: -35, test: 10 },
+  config:         { src: 0,  source: 0,  config: 14, lowSignal: -20, test: -15 },
+  docs:           { src: 0,  source: 4,  config: 4, lowSignal: -10, test: -15 },
+  explore:        { src: 10, source: 14, config: 4, lowSignal: -35, test: -15 },
+};
+
+const defaultWeights = intentWeights.explore;
+
+const shouldIgnoreFile = (filePath) => ignoredFileNames.has(path.basename(filePath));
+
+const isSearchableFile = (entryName, fullPath) => fallbackExtensions.has(path.extname(entryName)) || isDockerfile(fullPath);
+
+export const walk = (dir, files = [], stats = { skippedDirs: 0 }) => {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    stats.skippedDirs++;
+    return files;
+  }
+
+  for (const entry of entries) {
+    if (ignoredDirs.includes(entry.name) || ignoredFileNames.has(entry.name)) {
+      continue;
+    }
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      walk(fullPath, files, stats);
+      continue;
+    }
+
+    if (isSearchableFile(entry.name, fullPath)) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+};
+
+const parseRgLine = (line, root) => {
+  const match = /^(.*?):(\d+):(.*)$/.exec(line);
+
+  if (!match) {
+    return null;
+  }
+
+  const [, relativePath, lineNumber, content] = match;
+  return {
+    file: path.join(root, relativePath),
+    lineNumber: Number(lineNumber),
+    content,
+  };
+};
+
+const searchWithRipgrep = async (root, query) => {
+  const args = [
+    '--line-number',
+    '--no-heading',
+    '--color',
+    'never',
+    '--smart-case',
+    '--fixed-strings',
+  ];
+
+  for (const dir of ignoredDirs) {
+    args.push('--glob', `!${dir}/**`);
+  }
+
+  for (const fileName of ignoredFileNames) {
+    args.push('--glob', `!${fileName}`);
+  }
+
+  for (const extension of supportedGlobs) {
+    args.push('--glob', extension);
+  }
+
+  args.push(query, '.');
+
+  try {
+    const { stdout } = await execFile(rgPath, args, {
+      cwd: root,
+      maxBuffer: 1024 * 1024 * 10,
+      timeout: 15000,
+    });
+
+    return stdout
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => parseRgLine(line, root))
+      .filter(Boolean)
+      .filter((match) => !shouldIgnoreFile(match.file));
+  } catch (error) {
+    if (error.code === 1) return [];
+    return null;
+  }
+};
+
+const MAX_FALLBACK_FILE_BYTES = 1024 * 1024;
+
+export const isSmartCaseSensitive = (query) => query !== query.toLowerCase();
+
+export const searchWithFallback = (root, query) => {
+  const walkStats = { skippedDirs: 0 };
+  const files = walk(root, [], walkStats);
+  const matches = [];
+  const caseSensitive = isSmartCaseSensitive(query);
+  const comparator = caseSensitive
+    ? (line) => line.includes(query)
+    : (line) => line.toLowerCase().includes(query.toLowerCase());
+  let skippedLarge = 0;
+  let skippedBinary = 0;
+  let skippedErrors = 0;
+
+  for (const file of files) {
+    try {
+      const stat = fs.statSync(file);
+      if (stat.size > MAX_FALLBACK_FILE_BYTES) { skippedLarge++; continue; }
+
+      const buffer = fs.readFileSync(file);
+      if (isBinaryBuffer(buffer)) { skippedBinary++; continue; }
+
+      const content = buffer.toString('utf8');
+      const lines = content.split('\n');
+
+      lines.forEach((line, index) => {
+        if (comparator(line)) {
+          matches.push({
+            file,
+            lineNumber: index + 1,
+            content: line,
+          });
+        }
+      });
+    } catch {
+      skippedErrors++;
+    }
+  }
+
+  return { matches, caseSensitive, skippedLarge, skippedBinary, skippedErrors, skippedDirs: walkStats.skippedDirs };
+};
+
+const formatMatch = (match) => `${match.file}:${match.lineNumber}:${match.content}`;
+
+const scoreGroup = (group, query, intent) => {
+  const w = (intent && intentWeights[intent]) || defaultWeights;
+  const normalizedQuery = query.toLowerCase();
+  const lowerFilePath = group.file.toLowerCase();
+  const fileName = path.basename(group.file).toLowerCase();
+  const extension = path.extname(group.file).toLowerCase();
+  const pathDepth = group.file.split(path.sep).length;
+  const sampleText = group.matches.slice(0, 5).map((match) => match.content.toLowerCase()).join(' ');
+  const pathSegments = lowerFilePath.split(/[\\/._-]+/).filter(Boolean);
+  let score = Math.min(group.count, 12) * 6;
+
+  if (fileName.includes(normalizedQuery)) {
+    score += 30;
+  }
+
+  if (pathSegments.includes(normalizedQuery)) {
+    score += 16;
+  }
+
+  if (lowerFilePath.includes(`${path.sep}src${path.sep}`)) {
+    score += w.src;
+  }
+
+  if (lowerFilePath.includes(`${path.sep}packages${path.sep}`) || lowerFilePath.includes(`${path.sep}apps${path.sep}`)) {
+    score += 8;
+  }
+
+  if (likelySourceExtensions.has(extension) || isDockerfile(group.file)) {
+    score += w.source;
+  } else if (likelyConfigExtensions.has(extension)) {
+    score += w.config;
+  }
+
+  if (sampleText.includes(normalizedQuery)) {
+    score += 8;
+  }
+
+  if (lowSignalNames.some((name) => fileName.includes(name))) {
+    score += w.lowSignal;
+  }
+
+  if (testPatterns.some((p) => lowerFilePath.includes(p))) {
+    score += w.test;
+  }
+
+  score -= Math.min(pathDepth, 12);
+
+  return score;
+};
+
+const groupMatches = (matches, query, intent, indexHits, graphHits) => {
+  const groups = new Map();
+
+  for (const match of matches) {
+    if (!groups.has(match.file)) {
+      groups.set(match.file, []);
+    }
+
+    groups.get(match.file).push(match);
+  }
+
+  const breakdown = { textMatch: 0, indexBoost: 0, graphBoost: 0 };
+
+  const sorted = [...groups.entries()]
+    .map(([file, fileMatches]) => {
+      let score = scoreGroup({ file, count: fileMatches.length, matches: fileMatches }, query, intent);
+      let boostSource = 'text';
+      if (indexHits?.has(file)) { score += 50; boostSource = 'index'; }
+      else if (graphHits?.has(file)) { score += 25; boostSource = 'graph'; }
+      return { file, count: fileMatches.length, score, matches: fileMatches, boostSource };
+    })
+    .sort((left, right) => right.score - left.score || right.count - left.count || left.file.localeCompare(right.file));
+
+  for (const g of sorted.slice(0, 10)) {
+    if (g.boostSource === 'index') breakdown.indexBoost++;
+    else if (g.boostSource === 'graph') breakdown.graphBoost++;
+    else breakdown.textMatch++;
+  }
+
+  return { groups: sorted, breakdown };
+};
+
+const buildCompactResult = (groups, totalMatches, query, root) => {
+  if (totalMatches <= 20) {
+    return groups
+      .flatMap((group) => group.matches)
+      .map(formatMatch)
+      .join('\n');
+  }
+
+  const lines = [
+    `query: ${query}`,
+    `root: ${root}`,
+    `total matches: ${totalMatches}`,
+    `matched files: ${groups.length}`,
+    '',
+    '# Top files',
+  ];
+
+  for (const group of groups.slice(0, 10)) {
+    lines.push(`${group.count} match(es), score ${group.score} :: ${group.file}`);
+  }
+
+  lines.push('', '# Sample matches');
+
+  for (const group of groups.slice(0, 5)) {
+    for (const match of group.matches.slice(0, 3)) {
+      lines.push(formatMatch(match));
+    }
+  }
+
+  return lines.join('\n');
+};
+
+export const smartSearch = async ({ query, cwd = '.', intent, _testForceWalk = false }) => {
+  const root = resolveSafePath(cwd);
+  const rgMatches = _testForceWalk ? null : await searchWithRipgrep(root, query);
+  const usedFallback = rgMatches === null;
+  const engine = usedFallback ? 'walk' : 'rg';
+
+  let rawMatches;
+  let provenance;
+
+  if (usedFallback) {
+    const fallback = searchWithFallback(root, query);
+    rawMatches = fallback.matches;
+    const skippedTotal = fallback.skippedLarge + fallback.skippedBinary + fallback.skippedErrors + fallback.skippedDirs;
+    const warnings = ['search used filesystem walk instead of ripgrep'];
+    if (skippedTotal > 0) warnings.push(`${skippedTotal} items skipped (${fallback.skippedDirs} dirs, ${fallback.skippedLarge + fallback.skippedBinary + fallback.skippedErrors} files)`);
+
+    provenance = {
+      fallbackReason: 'rg unavailable or failed',
+      caseMode: fallback.caseSensitive ? 'sensitive' : 'insensitive',
+      partial: skippedTotal > 0,
+      skippedItemsTotal: skippedTotal,
+      skippedLargeFiles: fallback.skippedLarge,
+      skippedBinaryFiles: fallback.skippedBinary,
+      skippedReadErrors: fallback.skippedErrors,
+      skippedDirs: fallback.skippedDirs,
+      warnings,
+    };
+  } else {
+    rawMatches = rgMatches;
+  }
+
+  rawMatches = rawMatches.filter((match) => !shouldIgnoreFile(match.file));
+
+  const seen = new Set();
+  const dedupedMatches = rawMatches.filter((match) => {
+    const key = `${match.file}:${match.lineNumber}:${match.content.trim()}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  const validIntent = intent && VALID_INTENTS.has(intent) ? intent : undefined;
+
+  const indexRoot = projectRoot;
+  let indexHits = null;
+  let graphHits = null;
+  let indexFreshness = 'unavailable';
+  let loadedIndex = null;
+  try {
+    loadedIndex = loadIndex(indexRoot);
+    if (loadedIndex) {
+      indexFreshness = 'fresh';
+      const hits = queryIndex(loadedIndex, query);
+      if (hits.length > 0) {
+        indexHits = new Set(hits.map((h) => path.join(indexRoot, h.path)));
+        const related = new Set();
+        for (const h of hits) {
+          const rel = queryRelated(loadedIndex, h.path);
+          for (const p of [...rel.importedBy, ...rel.tests, ...rel.imports]) {
+            const full = path.join(indexRoot, p);
+            if (!indexHits.has(full)) related.add(full);
+          }
+        }
+        if (related.size > 0) graphHits = related;
+      }
+    }
+  } catch {
+    // index unavailable — continue without it
+  }
+
+  const { groups, breakdown } = groupMatches(dedupedMatches, query, validIntent, indexHits, graphHits);
+
+  if (loadedIndex && indexFreshness === 'fresh') {
+    const topRelPaths = groups.slice(0, 10).map((g) => path.relative(indexRoot, g.file).replace(/\\/g, '/'));
+    for (const rp of topRelPaths) {
+      const entry = loadedIndex.files?.[rp];
+      if (!entry) continue;
+      try {
+        const diskMtime = Math.floor(fs.statSync(path.join(indexRoot, rp)).mtimeMs);
+        if (diskMtime !== entry.mtime) { indexFreshness = 'stale'; break; }
+      } catch { /* file gone or unreadable */ }
+    }
+  }
+
+  const rawText = dedupedMatches.map(formatMatch).join('\n');
+  const compressedText = truncate(buildCompactResult(groups, dedupedMatches.length, query, root), 5000);
+  const metrics = buildMetrics({
+    tool: 'smart_search',
+    target: `${root} :: ${query}`,
+    rawText,
+    compressedText,
+  });
+
+  await persistMetrics(metrics);
+
+  let retrievalConfidence = 'high';
+  if (provenance) {
+    retrievalConfidence = provenance.skippedItemsTotal > 0 ? 'low' : 'medium';
+  }
+
+  const confidence = { level: retrievalConfidence, indexFreshness };
+
+  const result = {
+    query,
+    root,
+    engine,
+    retrievalConfidence,
+    indexFreshness,
+    sourceBreakdown: breakdown,
+    confidence,
+    ...(validIntent ? { intent: validIntent } : {}),
+    ...(indexHits ? { indexBoosted: indexHits.size } : {}),
+    totalMatches: dedupedMatches.length,
+    matchedFiles: groups.length,
+    topFiles: groups.slice(0, 10).map((group) => ({ file: group.file, count: group.count, score: group.score })),
+    matches: compressedText,
+    metrics,
+  };
+
+  if (provenance) result.provenance = provenance;
+
+  return result;
+};

package/src/tools/smart-shell.js

@@ -0,0 +1,213 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { promisify } from 'node:util';
+import { rgPath } from '@vscode/ripgrep';
+import { buildMetrics, persistMetrics } from '../metrics.js';
+import { projectRoot } from '../utils/paths.js';
+import { pickRelevantLines, truncate, uniqueLines } from '../utils/text.js';
+
+const execFile = promisify(execFileCallback);
+const blockedPattern = /[|&;<>`\n\r]/;
+const allowedCommands = new Set(['pwd', 'ls', 'find', 'rg', 'git', 'npm', 'pnpm', 'yarn', 'bun']);
+const allowedGitSubcommands = new Set(['status', 'diff', 'show', 'log', 'branch', 'rev-parse']);
+const allowedPackageManagerSubcommands = new Set(['test', 'run', 'lint', 'build', 'typecheck', 'check']);
+const safeRunScriptPattern = /^(test|lint|build|typecheck|check|smoke|verify)(:|$)/;
+
+const tokenize = (command) => {
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let escape = false;
+
+  for (const char of command.trim()) {
+    if (escape) {
+      current += char;
+      escape = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escape = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escape || quote) {
+    throw new Error('Unterminated escape or quote sequence');
+  }
+
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+};
+
+const validateCommand = (command, tokens) => {
+  if (!command.trim()) {
+    return 'Command is empty';
+  }
+
+  if (blockedPattern.test(command) || command.includes('$(')) {
+    return 'Shell operators are not allowed';
+  }
+
+  if (tokens.length === 0) {
+    return 'Command is empty';
+  }
+
+  const [baseCommand, subcommand, thirdToken] = tokens;
+
+  if (!allowedCommands.has(baseCommand)) {
+    return `Command not allowed: ${baseCommand}`;
+  }
+
+  if (baseCommand === 'git' && !allowedGitSubcommands.has(subcommand)) {
+    return `Git subcommand not allowed: ${subcommand ?? '(missing)'}`;
+  }
+
+  if (baseCommand === 'find') {
+    const dangerousArgs = ['-exec', '-execdir', '-delete', '-ok', '-okdir'];
+    const hasDangerous = tokens.some((t) => dangerousArgs.includes(t));
+    if (hasDangerous) {
+      return `find argument not allowed: ${tokens.find((t) => dangerousArgs.includes(t))}`;
+    }
+  }
+
+  if (['npm', 'pnpm', 'yarn', 'bun'].includes(baseCommand)) {
+    if (!subcommand || !allowedPackageManagerSubcommands.has(subcommand)) {
+      return `Package manager subcommand not allowed: ${subcommand ?? '(missing)'}`;
+    }
+
+    if (subcommand === 'run' && (!thirdToken || !safeRunScriptPattern.test(thirdToken))) {
+      return `Package manager script not allowed: ${thirdToken ?? '(missing)'}`;
+    }
+  }
+
+  return null;
+};
+
+const buildBlockedResult = async (command, message) => {
+  const metrics = buildMetrics({
+    tool: 'smart_shell',
+    target: command,
+    rawText: command,
+    compressedText: message,
+  });
+
+  await persistMetrics(metrics);
+
+  return {
+    command,
+    exitCode: 126,
+    blocked: true,
+    output: message,
+    confidence: { blocked: true, timedOut: false },
+    metrics,
+  };
+};
+
+export const smartShell = async ({ command }) => {
+  let tokens;
+
+  try {
+    tokens = tokenize(command);
+  } catch (error) {
+    return await buildBlockedResult(command, error.message);
+  }
+
+  const validationError = validateCommand(command, tokens);
+
+  if (validationError) {
+    return await buildBlockedResult(command, validationError);
+  }
+
+  const [file, ...args] = tokens;
+
+  if (file === 'find' && !args.includes('-maxdepth')) {
+    const findGlobalOptions = new Set(['-L', '-H', '-P', '-O0', '-O1', '-O2', '-O3', '-D']);
+    let insertAt = 0;
+    while (insertAt < args.length && findGlobalOptions.has(args[insertAt])) {
+      insertAt += 1;
+      if (args[insertAt - 1] === '-D' && insertAt < args.length) insertAt += 1;
+    }
+    while (insertAt < args.length && !args[insertAt].startsWith('-')) {
+      insertAt += 1;
+    }
+    args.splice(insertAt, 0, '-maxdepth', '8');
+  }
+
+  const resolvedFile = file === 'rg' ? rgPath : file;
+  const execution = await execFile(resolvedFile, args, {
+    cwd: projectRoot,
+    maxBuffer: 1024 * 1024 * 10,
+    timeout: 15000,
+  }).then(
+    ({ stdout, stderr }) => ({ stdout, stderr, code: 0 }),
+    (error) => ({
+      stdout: error.stdout ?? '',
+      stderr: error.killed
+        ? `Command timed out after 15s: ${command}`
+        : (error.stderr ?? error.message ?? ''),
+      code: Number.isInteger(error.code) ? error.code : 1,
+      timedOut: !!error.killed,
+    }),
+  );
+
+  const rawText = [execution.stdout, execution.stderr].filter(Boolean).join('\n');
+  const relevant = pickRelevantLines(rawText, [
+    'error',
+    'warning',
+    'failed',
+    'exception',
+    'maximum update depth',
+    'entity not found',
+  ]);
+  const shouldPrioritizeRelevant = execution.code !== 0 || execution.timedOut;
+  const compressedSource = shouldPrioritizeRelevant && relevant ? relevant : rawText;
+  const compressedText = truncate(uniqueLines(compressedSource), 5000);
+  const metrics = buildMetrics({
+    tool: 'smart_shell',
+    target: command,
+    rawText,
+    compressedText,
+  });
+
+  await persistMetrics(metrics);
+
+  const result = {
+    command,
+    exitCode: execution.code,
+    blocked: false,
+    output: compressedText,
+    confidence: { blocked: false, timedOut: !!execution.timedOut },
+    metrics,
+  };
+
+  if (execution.timedOut) result.timedOut = true;
+
+  return result;
+};

package/src/utils/fs.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { projectRoot } from './paths.js';
+
+const assertInsideProject = (fullPath) => {
+  const relative = path.relative(projectRoot, fullPath);
+
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Path escapes project root: ${fullPath}`);
+  }
+};
+
+export const resolveSafePath = (inputPath = '.') => {
+  const fullPath = path.resolve(projectRoot, inputPath);
+  assertInsideProject(fullPath);
+  return fullPath;
+};
+
+const BINARY_CHECK_BYTES = 8192;
+
+export const isBinaryBuffer = (buffer) => {
+  const length = Math.min(buffer.length, BINARY_CHECK_BYTES);
+
+  for (let i = 0; i < length; i++) {
+    const byte = buffer[i];
+    if (byte === 0) return true;
+    if (byte < 8 && byte !== 7) return true;
+  }
+
+  return false;
+};
+
+export const isDockerfile = (filePath) => {
+  const baseName = path.basename(filePath).toLowerCase();
+  return baseName === 'dockerfile' || baseName.startsWith('dockerfile.');
+};
+
+export const readTextFile = (inputPath) => {
+  const fullPath = resolveSafePath(inputPath);
+  const raw = fs.readFileSync(fullPath);
+
+  if (isBinaryBuffer(raw)) {
+    throw new Error(`Binary file, cannot read as text: ${fullPath}`);
+  }
+
+  return { fullPath, content: raw.toString('utf8') };
+};

package/src/utils/paths.js

@@ -0,0 +1 @@
+export { devctxRoot, projectRoot, projectRootSource, setProjectRoot } from './runtime-config.js';

package/src/utils/runtime-config.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDir = path.dirname(currentFilePath);
+
+const readArgValue = (name) => {
+  const index = process.argv.indexOf(name);
+
+  if (index === -1) {
+    return null;
+  }
+
+  return process.argv[index + 1] ?? null;
+};
+
+const defaultDevctxRoot = path.resolve(currentDir, '..', '..');
+const defaultProjectRoot = path.resolve(defaultDevctxRoot, '..', '..');
+const projectRootArg = readArgValue('--project-root');
+const projectRootEnv = process.env.DEVCTX_PROJECT_ROOT ?? null;
+const rawProjectRoot = projectRootArg ?? projectRootEnv ?? defaultProjectRoot;
+
+export const devctxRoot = defaultDevctxRoot;
+export let projectRoot = path.resolve(rawProjectRoot);
+export const projectRootSource = projectRootArg ? 'argv' : projectRootEnv ? 'env' : 'default';
+
+export const setProjectRoot = (newRoot) => {
+  projectRoot = path.resolve(newRoot);
+};