cowork-cli 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "work with cowork",
   "bin": {
     "cwk": "bin/cli.js"

package/src/engine/tools/findDir.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 /**
  * findDir tool: Finds directories by name using regex.
@@ -13,10 +13,10 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
 export default async function findDir({ pattern, dirPath = '.', recursive = true, limit = 15 }) {
   try {
     if (!pattern) return "Error: Search pattern cannot be empty.";
-    
+
     // Enforce max limit of 15
     const finalLimit = Math.min(limit, 15);
-    
+
     let regex;
     try {
       regex = new RegExp(pattern, 'i');
@@ -24,10 +24,17 @@ export default async function findDir({ pattern, dirPath = '.', recursive = true
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    let resolvedPath;
+    try {
+      resolvedPath = safePath(dirPath);
+    } catch (err) {
+      return `Error: ${err.message}`;
+    }
+
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
 
-    async function walk(currentPath) {
+    async function walk(currentPath, ignoreList) {
       if (results.length >= finalLimit) return;
 
       let items;
@@ -39,23 +46,24 @@ export default async function findDir({ pattern, dirPath = '.', recursive = true
 
       for (const item of items) {
         if (results.length >= finalLimit) break;
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
-        
+
         if (item.isDirectory()) {
           if (regex.test(item.name)) {
             results.push(path.relative(process.cwd(), fullPath));
           }
-          
+
           if (recursive) {
-            await walk(fullPath);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, childIgnores);
           }
         }
       }
     }
 
-    await walk(dirPath);
+    await walk(resolvedPath, rootIgnoreList);
 
     if (results.length === 0) {
       return `No directories found matching "${pattern}" in "${dirPath}".`;

package/src/engine/tools/findFile.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 /**
  * findFile tool: Finds files by name using regex.
@@ -13,10 +13,10 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
 export default async function findFile({ pattern, dirPath = '.', recursive = true, limit = 15 }) {
   try {
     if (!pattern) return "Error: Search pattern cannot be empty.";
-    
+
     // Enforce max limit of 15
     const finalLimit = Math.min(limit, 15);
-    
+
     let regex;
     try {
       regex = new RegExp(pattern, 'i');
@@ -24,11 +24,17 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    let resolvedPath;
+    try {
+      resolvedPath = safePath(dirPath);
+    } catch (err) {
+      return `Error: ${err.message}`;
+    }
+
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
-    let totalFound = 0;
 
-    async function walk(currentPath) {
+    async function walk(currentPath, ignoreList) {
       if (results.length >= finalLimit) return;
 
       let items;
@@ -40,13 +46,14 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
 
       for (const item of items) {
         if (results.length >= finalLimit) break;
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
-        
+
         if (item.isDirectory()) {
           if (recursive) {
-            await walk(fullPath);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, childIgnores);
           }
         } else if (item.isFile()) {
           if (regex.test(item.name)) {
@@ -56,7 +63,7 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
       }
     }
 
-    await walk(dirPath);
+    await walk(resolvedPath, rootIgnoreList);
 
     if (results.length === 0) {
       return `No files found matching "${pattern}" in "${dirPath}".`;

package/src/engine/tools/projectTree.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 const MAX_DEPTH = 10;
 const MAX_ITEMS = 500;
@@ -15,17 +15,23 @@ export default async function projectTree({ dirPath }) {
   let itemCount = 0;
   let isTruncated = false;
 
+  let absolutePath;
+  try {
+    absolutePath = safePath(dirPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
   try {
-    const absolutePath = path.resolve(dirPath);
     const stats = await fs.stat(absolutePath);
-    
+
     if (!stats.isDirectory()) {
       return `Error: '${dirPath}' is not a directory.`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    const rootIgnoreList = await getIgnorePatterns();
 
-    async function buildTree(currentDir, depth = 0, currentPrefix = '') {
+    async function buildTree(currentDir, depth = 0, currentPrefix = '', ignoreList = rootIgnoreList) {
       if (depth > MAX_DEPTH || itemCount >= MAX_ITEMS) {
         if (itemCount >= MAX_ITEMS) isTruncated = true;
         return '';
@@ -40,7 +46,7 @@ export default async function projectTree({ dirPath }) {
       }
 
       const filteredItems = items
-        .filter(item => !shouldIgnore(item.name, ignoreList))
+        .filter(item => isSafeEntry(item, currentDir, ignoreList))
         .sort((a, b) => {
           if (a.isDirectory() && !b.isDirectory()) return -1;
           if (!a.isDirectory() && b.isDirectory()) return 1;
@@ -64,7 +70,8 @@ export default async function projectTree({ dirPath }) {
 
         if (item.isDirectory()) {
           const fullPath = path.join(currentDir, item.name);
-          result += await buildTree(fullPath, depth + 1, currentPrefix + childPrefix);
+          const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+          result += await buildTree(fullPath, depth + 1, currentPrefix + childPrefix, childIgnores);
         }
       }
       return result;
@@ -72,7 +79,7 @@ export default async function projectTree({ dirPath }) {
 
     const rootName = path.basename(absolutePath) || absolutePath;
     const tree = await buildTree(absolutePath);
-    
+
     let finalOutput = `${rootName}/\n${tree || '└(empty)'}`;
     finalOutput = finalOutput.trimEnd();
 

package/src/engine/tools/readDir.js

@@ -1,5 +1,5 @@
 import fs from 'fs/promises';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, safePath } from '../../utils/fsUtils.js';
 
 /**
  * Implementation of the readDir tool.
@@ -8,12 +8,19 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
  * @returns {Promise<string>} List of files and folders or error message.
  */
 export default async function readDir({ dirPath }) {
+  let resolvedPath;
+  try {
+    resolvedPath = safePath(dirPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
   try {
     const ignoreList = await getIgnorePatterns();
-    const items = await fs.readdir(dirPath, { withFileTypes: true });
-    
+    const items = await fs.readdir(resolvedPath, { withFileTypes: true });
+
     const formattedItems = items
-      .filter(item => !shouldIgnore(item.name, ignoreList))
+      .filter(item => isSafeEntry(item, resolvedPath, ignoreList))
       .map(item => {
         const type = item.isDirectory() ? '[D]' : '[F]';
         return `${type}${item.name}`;

package/src/engine/tools/readFile.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import { Buffer } from 'buffer';
+import { safePath } from '../../utils/fsUtils.js';
 
 const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit
 
@@ -10,9 +11,16 @@ const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit
  * @returns {Promise<string>} File content or error message.
  */
 export default async function readFile({ filePath }) {
+  let resolvedPath;
   try {
-    const stats = await fs.stat(filePath);
-    
+    resolvedPath = safePath(filePath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
+
     if (!stats.isFile()) {
       return `Error: '${filePath}' is not a file.`;
     }
@@ -22,17 +30,17 @@ export default async function readFile({ filePath }) {
     }
 
     // Binary check: read first 1KB and look for null bytes
-    const handle = await fs.open(filePath, 'r');
+    const handle = await fs.open(resolvedPath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) {
         return `Error: '${filePath}' appears to be a binary file. Reading binary files is not supported.`;
       }
     }
 
-    const content = await fs.readFile(filePath, 'utf8');
+    const content = await fs.readFile(resolvedPath, 'utf8');
     return content;
   } catch (err) {
     if (err.code === 'ENOENT') return `Error: File not found at '${filePath}'.`;

package/src/engine/tools/readFileChunk.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import { Buffer } from 'buffer';
+import { safePath } from '../../utils/fsUtils.js';
 
 /**
  * Implementation of the readFileChunk tool.
@@ -10,22 +11,29 @@ import { Buffer } from 'buffer';
  * @returns {Promise<string>} File chunk or error message.
  */
 export default async function readFileChunk({ filePath, startLine, endLine }) {
+  let resolvedPath;
   try {
-    const stats = await fs.stat(filePath);
+    resolvedPath = safePath(filePath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
     if (!stats.isFile()) return `Error: '${filePath}' is not a file.`;
 
     // Binary check: read first 1KB and look for null bytes
-    const handle = await fs.open(filePath, 'r');
+    const handle = await fs.open(resolvedPath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) return `Error: '${filePath}' appears to be a binary file. Reading binary files is not supported.`;
     }
 
-    const data = await fs.readFile(filePath, 'utf8');
+    const data = await fs.readFile(resolvedPath, 'utf8');
     const lines = data.split('\n');
-    
+
     // Boundary validation
     const totalLines = lines.length;
     const actualStart = Math.max(1, startLine);

package/src/engine/tools/searchText.js

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { Buffer } from 'buffer';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 const MAX_MATCHES_PER_FILE = 20;
 const MAX_TOTAL_MATCHES = 100;
@@ -14,8 +14,15 @@ export default async function searchText({ pattern, path: searchPath, recursive
   let totalMatches = 0;
   let isTruncated = false;
 
+  let resolvedPath;
   try {
-    const stats = await fs.stat(searchPath);
+    resolvedPath = safePath(searchPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
     if (!pattern) return "Error: Search pattern cannot be empty.";
 
     let regex;
@@ -25,15 +32,15 @@ export default async function searchText({ pattern, path: searchPath, recursive
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
 
-    const walk = async (currentPath, depth = 0) => {
+    const walk = async (currentPath, depth = 0, ignoreList = rootIgnoreList) => {
       if (totalMatches >= MAX_TOTAL_MATCHES) {
         isTruncated = true;
         return;
       }
-      
+
       if (depth > MAX_DEPTH) return;
 
       let items;
@@ -49,13 +56,14 @@ export default async function searchText({ pattern, path: searchPath, recursive
           break;
         }
 
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
 
         if (item.isDirectory()) {
           if (recursive || depth === 0) {
-            await walk(fullPath, depth + 1);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, depth + 1, childIgnores);
           }
         } else if (item.isFile()) {
           const fileMatches = await searchInFile(fullPath, regex);
@@ -73,18 +81,18 @@ export default async function searchText({ pattern, path: searchPath, recursive
     };
 
     if (stats.isFile()) {
-      const fileMatches = await searchInFile(searchPath, regex);
+      const fileMatches = await searchInFile(resolvedPath, regex);
       if (fileMatches.length > 0) {
         const allowed = Math.min(fileMatches.length, MAX_TOTAL_MATCHES);
         results.push({
-          file: path.relative(process.cwd(), searchPath),
+          file: path.relative(process.cwd(), resolvedPath),
           matches: fileMatches.slice(0, allowed)
         });
         totalMatches = allowed;
         if (fileMatches.length > allowed) isTruncated = true;
       }
     } else {
-      await walk(searchPath);
+      await walk(resolvedPath);
     }
 
     if (results.length === 0) return "No matches found.";
@@ -99,7 +107,6 @@ export default async function searchText({ pattern, path: searchPath, recursive
 
     return output;
 
-
   } catch (err) {
     if (err.code === 'ENOENT') return `Error: Path not found at '${searchPath}'.`;
     return `Error searching text: ${err.message}`;
@@ -111,7 +118,7 @@ async function searchInFile(filePath, regex) {
     const handle = await fs.open(filePath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) return []; // Skip binary
     }
@@ -119,7 +126,7 @@ async function searchInFile(filePath, regex) {
     const content = await fs.readFile(filePath, 'utf8');
     const lines = content.split('\n');
     const matches = [];
-    
+
     for (let i = 0; i < lines.length; i++) {
       if (regex.test(lines[i])) {
         matches.push(`${i + 1}:${lines[i].trim()}`);

package/src/utils/fsUtils.js

@@ -1,37 +1,285 @@
 import fs from 'fs/promises';
 import path from 'path';
 
-const DEFAULT_IGNORES = ['.git', 'node_modules', 'dist', 'build', '.npm', '.DS_Store'];
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_IGNORES = [
+  // VCS
+  '.git', '.svn', '.hg',
+  // Dependencies & build output
+  'node_modules', 'dist', 'build', '.npm',
+  // OS artifacts
+  '.DS_Store', 'Thumbs.db',
+  // Secrets — defense-in-depth even if .gitignore already covers them
+  '.env', '.env.*',
+  // Test / coverage artifacts
+  'coverage', '__pycache__', '.cache',
+  // IDE metadata
+  '.vscode', '.idea',
+];
+
+const MAX_GITIGNORE_SIZE = 64 * 1024; // 64 KB
+
+// ── Cache ────────────────────────────────────────────────────────────────────
+
+let _cachedPatterns = null;
+
+// ── Internal: Glob-to-RegExp (zero dependencies) ────────────────────────────
 
 /**
- * Loads .gitignore patterns from the current working directory.
- * @returns {Promise<string[]>} Array of ignore patterns.
+ * Converts a gitignore-style glob pattern to a RegExp.
+ * Supports `*`, `**`, `?`, and bracket classes `[abc]`.
+ * @param {string} pattern
+ * @returns {RegExp}
  */
-export async function getIgnorePatterns() {
-  const ignoreList = [...DEFAULT_IGNORES];
+function globToRegex(pattern) {
+  let i = 0;
+  let re = '';
+
+  while (i < pattern.length) {
+    const c = pattern[i];
+
+    if (c === '*') {
+      if (pattern[i + 1] === '*') {
+        // `**` — match everything including path separators
+        re += '.*';
+        i += 2;
+        if (pattern[i] === '/') i++;        // consume optional trailing `/`
+        continue;
+      }
+      re += '[^/]*';                         // `*` — any non-separator chars
+    } else if (c === '?') {
+      re += '[^/]';                          // `?` — single non-separator char
+    } else if (c === '[') {
+      // Bracket expression — locate the closing `]`
+      let j = i + 1;
+      if (j < pattern.length && pattern[j] === '!') j++;
+      if (j < pattern.length && pattern[j] === ']') j++;
+      while (j < pattern.length && pattern[j] !== ']') j++;
+
+      if (j >= pattern.length) {
+        re += '\\[';                         // no closing bracket → literal `[`
+      } else {
+        let cls = pattern.slice(i + 1, j).replace(/\\/g, '\\\\');
+        if (cls[0] === '!') cls = '^' + cls.slice(1);
+        re += `[${cls}]`;
+        i = j;                               // advance past `]`
+      }
+    } else if ('.+^${}()|\\'.includes(c)) {
+      re += '\\' + c;                        // escape regex meta chars
+    } else {
+      re += c;
+    }
+    i++;
+  }
+
+  return new RegExp(`^${re}$`);
+}
+
+// ── Internal: .gitignore Parser ──────────────────────────────────────────────
+
+/**
+ * Parses raw `.gitignore` content into structured pattern objects.
+ * Handles: comments, blank lines, negation (`!`), directory-only (`/`),
+ *          Windows `\r` line endings, and glob detection.
+ * @param {string} content
+ * @returns {Object[]}
+ */
+function parseGitignoreContent(content) {
+  const patterns = [];
+
+  for (const raw of content.split('\n')) {
+    let line = raw.replace(/\r$/, '').trim();   // strip Windows CR
+    if (!line || line.startsWith('#')) continue; // skip blanks & comments
+
+    // Negation
+    let negated = false;
+    if (line.startsWith('!')) {
+      negated = true;
+      line = line.slice(1).trim();
+      if (!line) continue;
+    }
+
+    // Directory-only marker
+    const dirOnly = line.endsWith('/');
+    if (dirOnly) line = line.slice(0, -1);
+
+    const hasGlob = /[*?[\]]/.test(line);
+    const hasSlash = line.includes('/');
+
+    patterns.push({
+      pattern: line,
+      negated,
+      dirOnly,
+      hasGlob,
+      hasSlash,
+      regex: hasGlob ? globToRegex(line) : null,
+    });
+  }
+
+  return patterns;
+}
+
+/**
+ * Builds structured pattern objects from a plain-string array
+ * (used for the hard-coded DEFAULT_IGNORES list).
+ * @param {string[]} list
+ * @returns {Object[]}
+ */
+function buildPatterns(list) {
+  return list.map(raw => {
+    const dirOnly = raw.endsWith('/');
+    const cleaned = dirOnly ? raw.slice(0, -1) : raw;
+    const hasGlob = /[*?[\]]/.test(cleaned);
+    return {
+      pattern: cleaned,
+      negated: false,
+      dirOnly,
+      hasGlob,
+      hasSlash: cleaned.includes('/'),
+      regex: hasGlob ? globToRegex(cleaned) : null,
+    };
+  });
+}
+
+// ── Internal: .gitignore Loader ──────────────────────────────────────────────
+
+/**
+ * Reads and parses the `.gitignore` file inside a directory.
+ * Returns an empty array if the file is missing, unreadable, or oversized.
+ * @param {string} dirPath Absolute directory path.
+ * @returns {Promise<Object[]>}
+ */
+async function loadGitignoreFromDir(dirPath) {
   try {
-    const gitignorePath = path.join(process.cwd(), '.gitignore');
+    const gitignorePath = path.join(dirPath, '.gitignore');
+    const stats = await fs.stat(gitignorePath);
+    if (stats.size > MAX_GITIGNORE_SIZE) return [];
+
     const content = await fs.readFile(gitignorePath, 'utf8');
-    const lines = content.split('\n')
-      .map(l => l.trim())
-      .filter(l => l && !l.startsWith('#'));
-    ignoreList.push(...lines);
-  } catch (e) {
-    // Ignore if not found or unreadable
+    return parseGitignoreContent(content);
+  } catch {
+    return [];
   }
-  return ignoreList;
 }
 
+// ── Public API ───────────────────────────────────────────────────────────────
+
 /**
- * Checks if a file or directory should be ignored.
- * @param {string} name Item name.
- * @param {string[]} ignoreList List of patterns.
- * @returns {boolean}
+ * Loads ignore patterns from `DEFAULT_IGNORES` + the root `.gitignore`.
+ * Results are cached for the lifetime of the process.
+ * @returns {Promise<Object[]>} Structured pattern objects.
  */
-export function shouldIgnore(name, ignoreList) {
-  for (const ignore of ignoreList) {
-    const pattern = ignore.endsWith('/') ? ignore.slice(0, -1) : ignore;
-    if (name === pattern) return true;
+export async function getIgnorePatterns() {
+  if (_cachedPatterns) return _cachedPatterns;
+
+  const defaults = buildPatterns(DEFAULT_IGNORES);
+  const gitignore = await loadGitignoreFromDir(process.cwd());
+
+  _cachedPatterns = [...defaults, ...gitignore];
+  return _cachedPatterns;
+}
+
+/**
+ * Loads additional `.gitignore` patterns from a nested directory and
+ * merges them **after** the parent list so they can override via negation.
+ * @param {string} dirPath     Absolute path of the directory to inspect.
+ * @param {Object[]} parentList Patterns inherited from the parent scope.
+ * @returns {Promise<Object[]>} Merged pattern list (parent + nested).
+ */
+export async function loadNestedIgnores(dirPath, parentList) {
+  const nested = await loadGitignoreFromDir(dirPath);
+  if (nested.length === 0) return parentList;
+  return [...parentList, ...nested];
+}
+
+/**
+ * Invalidates the cached ignore patterns.
+ */
+export function clearIgnoreCache() {
+  _cachedPatterns = null;
+}
+
+/**
+ * Checks if a name should be ignored.
+ *
+ * Pattern evaluation order matters — patterns are processed sequentially
+ * and the **last matching pattern wins**.  Negation patterns (`!`) can
+ * therefore un-ignore a previously ignored name.
+ *
+ * @param {string}   name       Item basename.
+ * @param {Object[]} ignoreList Structured pattern objects.
+ * @param {Object}   [options]
+ * @param {boolean}  [options.isDirectory] Whether the item is a directory.
+ *                   When omitted, directory-only patterns match regardless
+ *                   (backward-compatible with existing callers).
+ * @returns {boolean} `true` if the item should be skipped.
+ */
+export function shouldIgnore(name, ignoreList, options = {}) {
+  const { isDirectory } = options;
+  let ignored = false;
+
+  for (const entry of ignoreList) {
+    // Path-containing patterns (e.g. `docs/internal`) require full
+    // relative-path matching which callers don't supply — skip them.
+    if (entry.hasSlash) continue;
+
+    // Directory-only patterns (`build/`) don't apply to files.
+    // When `isDirectory` is undefined the caller didn't say, so we match
+    // to preserve backward compat with callers that only pass basenames.
+    if (entry.dirOnly && isDirectory === false) continue;
+
+    const matches = entry.hasGlob && entry.regex
+      ? entry.regex.test(name)
+      : name === entry.pattern;
+
+    if (matches) {
+      ignored = !entry.negated;
+    }
+  }
+
+  return ignored;
+}
+
+/**
+ * Resolves a path and verifies it stays within `process.cwd()`.
+ * Prevents directory-traversal attacks (e.g. `../../etc/passwd`).
+ *
+ * @param {string} inputPath The user- or model-supplied path.
+ * @returns {string} Resolved absolute path guaranteed to be inside the project.
+ * @throws {Error}  If the resolved path escapes the project root.
+ */
+export function safePath(inputPath) {
+  const root = process.cwd();
+  const resolved = path.resolve(root, inputPath);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+    throw new Error(`Access denied: '${inputPath}' resolves outside the project directory.`);
   }
-  return false;
+  return resolved;
+}
+
+/**
+ * Decides whether a directory entry is safe to traverse / read.
+ *
+ * Rejects:
+ *  1. Symbolic links (could escape the project sandbox).
+ *  2. Names matched by the ignore list.
+ *  3. Paths that resolve outside `process.cwd()`.
+ *
+ * @param {import('fs').Dirent} dirent      Directory entry from `readdir`.
+ * @param {string}              parentPath  Absolute path of the parent dir.
+ * @param {Object[]}            ignoreList  Structured pattern objects.
+ * @returns {boolean} `true` when the entry is safe to process.
+ */
+export function isSafeEntry(dirent, parentPath, ignoreList) {
+  if (dirent.isSymbolicLink()) return false;
+
+  const isDir = dirent.isDirectory();
+  if (shouldIgnore(dirent.name, ignoreList, { isDirectory: isDir })) return false;
+
+  const resolved = path.resolve(parentPath, dirent.name);
+  const root = process.cwd();
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
+
+  return true;
 }