instruqt/scripts/trace-fs.js

CLI tool for deploying AI agent context documentation across multiple platforms with dual MERN/module support

/**
 * FS Tracing Module - Intercepts all file system operations to trace file access
 * Usage: node -r ./scripts/trace-fs.js node_modules/instruqt/bin/cli.js instruct npm
 */

const fs = require('fs');
const path = require('path');

// Store original methods
const originalReadFileSync = fs.readFileSync;
const originalExistsSync = fs.existsSync;
const originalReaddirSync = fs.readdirSync;
const originalStatSync = fs.statSync;

// Helper to format file paths for logging
function formatPath(filePath) {
  if (!filePath) return filePath;
  const cwd = process.cwd();
  if (filePath.startsWith(cwd)) {
    return `CWD${filePath.substring(cwd.length)}`;
  }
  return filePath;
}

// Helper to check if file path is relevant to instruqt
function isRelevantPath(filePath) {
  if (!filePath || typeof filePath !== 'string') return false;
  return filePath.includes('AGENTS.md') || 
         filePath.includes('contexts/') || 
         filePath.includes('instruqt');
}

// Intercept fs.readFileSync
fs.readFileSync = function(filePath, ...args) {
  const result = originalReadFileSync.apply(this, [filePath, ...args]);
  if (isRelevantPath(filePath)) {
    console.error(`🔍 FS-TRACE readFileSync: ${formatPath(filePath)}`);
    if (filePath.includes('AGENTS.md')) {
      const content = result.toString().substring(0, 100);
      console.error(`🔍 FS-TRACE AGENTS.md content preview: ${content.replace(/\n/g, '\\n')}`);
    }
  }
  return result;
};

// Intercept fs.existsSync  
fs.existsSync = function(filePath, ...args) {
  const result = originalExistsSync.apply(this, [filePath, ...args]);
  if (isRelevantPath(filePath)) {
    console.error(`🔍 FS-TRACE existsSync: ${formatPath(filePath)} -> ${result}`);
  }
  return result;
};

// Intercept fs.readdirSync
fs.readdirSync = function(dirPath, ...args) {
  const result = originalReaddirSync.apply(this, [dirPath, ...args]);
  if (isRelevantPath(dirPath)) {
    console.error(`🔍 FS-TRACE readdirSync: ${formatPath(dirPath)} -> [${result.join(', ')}]`);
  }
  return result;
};

// Intercept fs.statSync
fs.statSync = function(filePath, ...args) {
  const result = originalStatSync.apply(this, [filePath, ...args]);
  if (isRelevantPath(filePath)) {
    console.error(`🔍 FS-TRACE statSync: ${formatPath(filePath)} -> ${result.isFile() ? 'FILE' : 'DIR'}`);
  }
  return result;
};

console.error('🔍 FS-TRACE: File system tracing active. Monitoring AGENTS.md and contexts/ access.');