File Listing

// Using SDK
const result = await sandbox.files.list({
  dirPath: '/opt/app'
});

result.files.forEach(file => {
  console.log(`${file.type}: ${file.name} (${file.size} bytes)`);
});

POST /files/list HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "dirPath": "/opt/app"
}

{
  "success": true,
  "files": [
    {
      "name": "src",
      "path": "/opt/app/src",
      "type": "directory",
      "size": 4096,
      "modified": "2025-10-16T12:00:00Z",
      "permissions": "drwxr-xr-x"
    },
    {
      "name": "package.json",
      "path": "/opt/app/package.json",
      "type": "file",
      "size": 1245,
      "modified": "2025-10-16T11:30:00Z",
      "permissions": "-rw-r--r--"
    },
    {
      "name": ".gitignore",
      "path": "/opt/app/.gitignore",
      "type": "file",
      "size": 326,
      "modified": "2025-10-15T10:00:00Z",
      "permissions": "-rw-r--r--",
      "hidden": true
    }
  ],
  "path": "/opt/app",
  "total": 3
}

// List all files recursively
const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

// Result includes all nested files

// Show hidden files (starting with .)
const result = await sandbox.files.list({
  dirPath: '/opt/app',
  includeHidden: true
});

const result = await sandbox.files.list({
  dirPath: '/opt/app'
});

// Filter directories only
const dirs = result.files.filter(f => f.type === 'directory');

// Filter files only
const files = result.files.filter(f => f.type === 'file');

const result = await sandbox.files.list({
  dirPath: '/opt/app/src',
  recursive: true
});

const jsFiles = result.files.filter(f => 
  f.type === 'file' && f.name.endsWith('.js')
);

jsFiles.forEach(file => {
  console.log(file.path);
});

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

const largeFiles = result.files
  .filter(f => f.type === 'file' && f.size > 1024 * 1024) // > 1 MB
  .sort((a, b) => b.size - a.size);

console.log('Large files:');
largeFiles.forEach(file => {
  console.log(`${file.path} - ${(file.size / 1024 / 1024).toFixed(2)} MB`);
});

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

const recent = result.files
  .filter(f => f.type === 'file')
  .sort((a, b) => new Date(b.modified) - new Date(a.modified))
  .slice(0, 10);

console.log('10 most recently modified files:');
recent.forEach(file => {
  console.log(`${file.path} - ${file.modified}`);
});

const result = await sandbox.files.list({
  dirPath: '/opt/app/src',
  recursive: true
});

const byExtension = {};

result.files
  .filter(f => f.type === 'file')
  .forEach(file => {
    const ext = file.name.split('.').pop() || 'no-extension';
    byExtension[ext] = (byExtension[ext] || 0) + 1;
  });

console.log('Files by extension:', byExtension);
// { js: 42, json: 3, md: 2, ... }

function buildTree(files) {
  const tree = {};
  
  files.forEach(file => {
    const parts = file.path.split('/').filter(Boolean);
    let current = tree;
    
    parts.forEach((part, index) => {
      if (index === parts.length - 1) {
        current[part] = file;
      } else {
        current[part] = current[part] || {};
        current = current[part];
      }
    });
  });
  
  return tree;
}

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

const tree = buildTree(result.files);
console.log(JSON.stringify(tree, null, 2));

const result = await sandbox.files.list({
  dirPath: '/opt/app',
  recursive: true
});

const stats = {
  totalFiles: result.files.filter(f => f.type === 'file').length,
  totalDirs: result.files.filter(f => f.type === 'directory').length,
  totalSize: result.files.reduce((sum, f) => sum + f.size, 0),
  hiddenFiles: result.files.filter(f => f.hidden).length
};

console.log(`Total: ${stats.totalFiles} files, ${stats.totalDirs} directories`);
console.log(`Size: ${(stats.totalSize / 1024 / 1024).toFixed(2)} MB`);

// ✅ Good - specific directory
await sandbox.files.list({ dirPath: '/opt/app/src' });

// ❌ Bad - entire filesystem
await sandbox.files.list({ dirPath: '/', recursive: true });

let cachedListing = null;
let cacheTime = null;

async function getFiles(force = false) {
  if (force || !cachedListing || Date.now() - cacheTime > 60000) {
    cachedListing = await sandbox.files.list({ dirPath: '/opt/app' });
    cacheTime = Date.now();
  }
  return cachedListing;
}

// For small directories
await sandbox.files.list({ dirPath: '/opt/app/src', recursive: true });

// For large directories, paginate or use search instead
const results = await sandbox.search.filenames({ query: '*.js' });