cowork-cli 0.0.1 → 1.0.0

package/src/engine/tools/findFile.js

@@ -0,0 +1,74 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+
+/**
+ * findFile tool: Finds files by name using regex.
+ * @param {Object} args
+ * @param {string} args.pattern Regex pattern to match filenames.
+ * @param {string} args.dirPath Root directory to search (default: current directory).
+ * @param {boolean} args.recursive Whether to search subdirectories (default: true).
+ * @param {number} args.limit Maximum number of results (default: 15, max: 15).
+ */
+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');
+    } catch (e) {
+      return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
+    }
+
+    const ignoreList = await getIgnorePatterns();
+    const results = [];
+    let totalFound = 0;
+
+    async function walk(currentPath) {
+      if (results.length >= finalLimit) return;
+
+      let items;
+      try {
+        items = await fs.readdir(currentPath, { withFileTypes: true });
+      } catch (err) {
+        return; // Skip unreadable directories
+      }
+
+      for (const item of items) {
+        if (results.length >= finalLimit) break;
+        if (shouldIgnore(item.name, ignoreList)) continue;
+
+        const fullPath = path.join(currentPath, item.name);
+        
+        if (item.isDirectory()) {
+          if (recursive) {
+            await walk(fullPath);
+          }
+        } else if (item.isFile()) {
+          if (regex.test(item.name)) {
+            results.push(path.relative(process.cwd(), fullPath));
+          }
+        }
+      }
+    }
+
+    await walk(dirPath);
+
+    if (results.length === 0) {
+      return `No files found matching "${pattern}" in "${dirPath}".`;
+    }
+
+    let output = results.join('\n');
+    if (results.length >= finalLimit) {
+      output += `\n[Warning: Truncated at ${finalLimit} matches]`;
+    }
+    return output;
+
+  } catch (err) {
+    return `Error searching for files: ${err.message}`;
+  }
+}

package/src/engine/tools/index.js

@@ -0,0 +1,204 @@
+import readFile from './readFile.js';
+import readDir from './readDir.js';
+import projectTree from './projectTree.js';
+import readFileChunk from './readFileChunk.js';
+import searchText from './searchText.js';
+import webFetch from './webFetch.js';
+import listTools from './listTools.js';
+import findFile from './findFile.js';
+import findDir from './findDir.js';
+import askUser from './askUser.js';
+import askConfirm from './askConfirm.js';
+
+export const toolDefinitions = [
+  {
+    type: "function",
+    function: {
+      name: "readFile",
+      description: "Read a file's full content. Best for files <1MB.",
+      parameters: {
+        type: "object",
+        properties: {
+          filePath: { type: "string", description: "Path to the file." }
+        },
+        required: ["filePath"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "readDir",
+      description: "List directory contents, including types (DIR/FILE).",
+      parameters: {
+        type: "object",
+        properties: {
+          dirPath: { type: "string", description: "Path to the directory." }
+        },
+        required: ["dirPath"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "projectTree",
+      description: "Generate a visual directory tree. Respects .gitignore.",
+      parameters: {
+        type: "object",
+        properties: {
+          dirPath: { type: "string", description: "The folder to act as root for the tree." }
+        },
+        required: ["dirPath"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "readFileChunk",
+      description: "Read specific line ranges. Ideal for large files.",
+      parameters: {
+        type: "object",
+        properties: {
+          filePath: { type: "string", description: "Path to the file." },
+          startLine: { type: "number", description: "1-based start line." },
+          endLine: { type: "number", description: "1-based end line (inclusive)." }
+        },
+        required: ["filePath", "startLine", "endLine"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "searchText",
+      description: "Regex search in files/folders. Supports recursion and .gitignore.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Regex or text pattern." },
+          path: { type: "string", description: "File or directory to search." },
+          recursive: { type: "boolean", description: "Search subdirectories? (default: false)" }
+        },
+        required: ["pattern", "path"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "webFetch",
+      description: "Fetch and clean text from a URL. Ideal for docs/APIs.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full HTTP/HTTPS URL." }
+        },
+        required: ["url"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "listTools",
+      description: "List all available tools and usage guidelines.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "findFile",
+      description: "Find files by name using regex. Supports recursion and .gitignore.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Regex pattern to match filenames." },
+          dirPath: { type: "string", description: "Root directory to search (default: '.')." },
+          recursive: { type: "boolean", description: "Search subdirectories? (default: true)" },
+          limit: { type: "number", description: "Maximum number of results (default: 15, max: 15)." }
+        },
+        required: ["pattern"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "findDir",
+      description: "Find directories by name using regex. Supports recursion and .gitignore.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Regex pattern to match directory names." },
+          dirPath: { type: "string", description: "Root directory to search (default: '.')." },
+          recursive: { type: "boolean", description: "Search subdirectories? (default: true)" },
+          limit: { type: "number", description: "Maximum number of results (default: 15, max: 15)." }
+        },
+        required: ["pattern"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "askUser",
+      description: "Ask the user an open-ended question via the terminal and get a free-text response.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "The question to ask the user." }
+        },
+        required: ["question"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "askConfirm",
+      description: "Ask the user a yes/no confirmation question. Use this instead of askUser when only a boolean decision is needed. Returns { confirmed: true } for yes, { confirmed: false } for no, and { confirmed: false, dismissed: true } if the user cancels with Ctrl+C.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "The yes/no question to ask the user." }
+        },
+        required: ["question"]
+      }
+    }
+  }
+];
+
+const toolImplementations = {
+  readFile,
+  readDir,
+  projectTree,
+  readFileChunk,
+  searchText,
+  webFetch,
+  listTools,
+  findFile,
+  findDir,
+  askUser,
+  askConfirm
+};
+
+/**
+ * Dispatches a tool call to the appropriate implementation.
+ * @param {string} name Tool name.
+ * @param {Object} args Tool arguments.
+ * @returns {Promise<string>} Tool execution result.
+ */
+export async function dispatchTool(name, args) {
+  const tool = toolImplementations[name];
+  if (!tool) {
+    return `Error: Tool '${name}' not found.`;
+  }
+  return await tool(args);
+}

package/src/engine/tools/listTools.js

@@ -0,0 +1,79 @@
+/**
+ * Returns a detailed list of all available tools, their purpose, and usage guidelines.
+ * @returns {Promise<string>} A formatted string containing tool documentation.
+ */
+export default async function listTools() {
+  const tools = [
+    {
+      name: "readFile",
+      usage: "readFile({ filePath: 'src/main.js' })",
+      description: "Reads the entire content of a file. Use this for small to medium files (<1MB) when you need full context.",
+      whenToUse: "When you need to analyze a specific file's logic or structure completely."
+    },
+    {
+      name: "readDir",
+      usage: "readDir({ dirPath: 'src/' })",
+      description: "Lists all files and directories in a given path, indicating their types.",
+      whenToUse: "To explore the contents of a specific folder without generating a full tree."
+    },
+    {
+      name: "projectTree",
+      usage: "projectTree({ dirPath: '.' })",
+      description: "Generates a visual directory tree of the project while respecting .gitignore rules.",
+      whenToUse: "To get a high-level overview of the project structure and find where specific modules are located."
+    },
+    {
+      name: "readFileChunk",
+      usage: "readFileChunk({ filePath: 'large-file.log', startLine: 100, endLine: 200 })",
+      description: "Reads a specific range of lines from a file.",
+      whenToUse: "Essential for very large files or when you only need a specific snippet/function from a file."
+    },
+    {
+      name: "searchText",
+      usage: "searchText({ pattern: 'TODO', path: 'src/', recursive: true })",
+      description: "Performs a regex search for text across files and directories. Respects .gitignore.",
+      whenToUse: "To find variable usages, search for specific strings, or locate technical debt across the codebase."
+    },
+    {
+      name: "webFetch",
+      usage: "webFetch({ url: 'https://docs.example.com' })",
+      description: "Fetches and extracts clean text from a web URL, removing HTML clutter.",
+      whenToUse: "To gather information from online documentation, API references, or external technical articles."
+    },
+    {
+      name: "findFile",
+      usage: "findFile({ pattern: 'config.*\\\\.js$', dirPath: 'src/', limit: 10 })",
+      description: "Finds files by name using regex. Supports recursion and respects .gitignore. Max 15 results.",
+      whenToUse: "When you know the name or part of the name of a file but don't know its exact location."
+    },
+    {
+      name: "findDir",
+      usage: "findDir({ pattern: 'models', recursive: true })",
+      description: "Finds directories by name using regex. Supports recursion and respects .gitignore. Max 15 results.",
+      whenToUse: "To locate specific modules or folder structures within the project."
+    },
+    {
+      name: "listTools",
+      usage: "listTools({})",
+      description: "Lists all tools available to the AI with detailed descriptions and usage examples.",
+      whenToUse: "Use this if you are unsure which tool is best suited for the current task."
+    },
+    {
+      name: "askUser",
+      usage: "askUser({ question: 'What is the API endpoint for this service?' })",
+      description: "Asks the user a specific question via the terminal and waits for a text response.",
+      whenToUse: "When you need specific information, clarification, or feedback from the user that cannot be found in the codebase."
+    }
+  ];
+
+  let output = "AVAILABLE TOOLS:\n";
+
+  tools.forEach(tool => {
+    output += `[${tool.name}]\n`;
+    output += `Desc:${tool.description}\n`;
+    output += `Use:${tool.whenToUse}\n`;
+    output += `Ex:${tool.usage}\n`;
+  });
+
+  return output.trim();
+}

package/src/engine/tools/projectTree.js

@@ -0,0 +1,89 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+
+const MAX_DEPTH = 10;
+const MAX_ITEMS = 500;
+
+/**
+ * Generates a robust, visual tree of the project structure.
+ * @param {Object} args Arguments.
+ * @param {string} args.dirPath The root directory to start from.
+ * @returns {Promise<string>} Tree-like string representation.
+ */
+export default async function projectTree({ dirPath }) {
+  let itemCount = 0;
+  let isTruncated = false;
+
+  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();
+
+    async function buildTree(currentDir, depth = 0, currentPrefix = '') {
+      if (depth > MAX_DEPTH || itemCount >= MAX_ITEMS) {
+        if (itemCount >= MAX_ITEMS) isTruncated = true;
+        return '';
+      }
+
+      let items;
+      try {
+        items = await fs.readdir(currentDir, { withFileTypes: true });
+      } catch (err) {
+        if (err.code === 'EACCES') return `${currentPrefix}└[Permission Denied]\n`;
+        return `${currentPrefix}└[Error: ${err.code}]\n`;
+      }
+
+      const filteredItems = items
+        .filter(item => !shouldIgnore(item.name, ignoreList))
+        .sort((a, b) => {
+          if (a.isDirectory() && !b.isDirectory()) return -1;
+          if (!a.isDirectory() && b.isDirectory()) return 1;
+          return a.name.localeCompare(b.name);
+        });
+
+      let result = '';
+      for (let i = 0; i < filteredItems.length; i++) {
+        if (itemCount >= MAX_ITEMS) {
+          isTruncated = true;
+          break;
+        }
+
+        const item = filteredItems[i];
+        const isLast = i === filteredItems.length - 1 || itemCount + 1 >= MAX_ITEMS;
+        const marker = isLast ? '└' : '├';
+        const childPrefix = isLast ? ' ' : '│';
+
+        result += `${currentPrefix}${marker}${item.name}${item.isDirectory() ? '/' : ''}\n`;
+        itemCount++;
+
+        if (item.isDirectory()) {
+          const fullPath = path.join(currentDir, item.name);
+          result += await buildTree(fullPath, depth + 1, currentPrefix + childPrefix);
+        }
+      }
+      return result;
+    }
+
+    const rootName = path.basename(absolutePath) || absolutePath;
+    const tree = await buildTree(absolutePath);
+    
+    let finalOutput = `${rootName}/\n${tree || '└(empty)'}`;
+    finalOutput = finalOutput.trimEnd();
+
+    if (isTruncated) {
+      finalOutput += `\n[Warning: Truncated at ${MAX_ITEMS} items]`;
+    }
+
+    return finalOutput;
+
+  } catch (err) {
+    if (err.code === 'ENOENT') return `Error: Directory not found at '${dirPath}'.`;
+    return `Error generating tree: ${err.message}`;
+  }
+}

package/src/engine/tools/readDir.js

@@ -0,0 +1,32 @@
+import fs from 'fs/promises';
+import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+
+/**
+ * Implementation of the readDir tool.
+ * @param {Object} args Arguments from the model.
+ * @param {string} args.dirPath Path to the directory.
+ * @returns {Promise<string>} List of files and folders or error message.
+ */
+export default async function readDir({ dirPath }) {
+  try {
+    const ignoreList = await getIgnorePatterns();
+    const items = await fs.readdir(dirPath, { withFileTypes: true });
+    
+    const formattedItems = items
+      .filter(item => !shouldIgnore(item.name, ignoreList))
+      .map(item => {
+        const type = item.isDirectory() ? '[D]' : '[F]';
+        return `${type}${item.name}`;
+      });
+
+    if (formattedItems.length === 0) {
+      return `Directory '${dirPath}' is empty (or all items are ignored).`;
+    }
+
+    return formattedItems.join('\n');
+  } catch (err) {
+    if (err.code === 'ENOENT') return `Error: Directory not found at '${dirPath}'.`;
+    if (err.code === 'ENOTDIR') return `Error: '${dirPath}' is not a directory.`;
+    return `Error reading directory: ${err.message}`;
+  }
+}

package/src/engine/tools/readFile.js

@@ -0,0 +1,41 @@
+import fs from 'fs/promises';
+import { Buffer } from 'buffer';
+
+const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit
+
+/**
+ * Implementation of the readFile tool.
+ * @param {Object} args Arguments from the model.
+ * @param {string} args.filePath Path to the file.
+ * @returns {Promise<string>} File content or error message.
+ */
+export default async function readFile({ filePath }) {
+  try {
+    const stats = await fs.stat(filePath);
+    
+    if (!stats.isFile()) {
+      return `Error: '${filePath}' is not a file.`;
+    }
+
+    if (stats.size > MAX_FILE_SIZE) {
+      return `Error: File is too large (${(stats.size / 1024 / 1024).toFixed(1)}MB). Maximum allowed size is 1MB. Use 'readFileChunk' to read specific parts of this file.`;
+    }
+
+    // Binary check: read first 1KB and look for null bytes
+    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 `Error: '${filePath}' appears to be a binary file. Reading binary files is not supported.`;
+      }
+    }
+
+    const content = await fs.readFile(filePath, 'utf8');
+    return content;
+  } catch (err) {
+    if (err.code === 'ENOENT') return `Error: File not found at '${filePath}'.`;
+    return `Error reading file: ${err.message}`;
+  }
+}

package/src/engine/tools/readFileChunk.js

@@ -0,0 +1,48 @@
+import fs from 'fs/promises';
+import { Buffer } from 'buffer';
+
+/**
+ * Implementation of the readFileChunk tool.
+ * @param {Object} args Arguments from the model.
+ * @param {string} args.filePath Path to the file.
+ * @param {number} args.startLine The 1-based start line.
+ * @param {number} args.endLine The 1-based end line (inclusive).
+ * @returns {Promise<string>} File chunk or error message.
+ */
+export default async function readFileChunk({ filePath, startLine, endLine }) {
+  try {
+    const stats = await fs.stat(filePath);
+    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 { 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 lines = data.split('\n');
+    
+    // Boundary validation
+    const totalLines = lines.length;
+    const actualStart = Math.max(1, startLine);
+    const actualEnd = Math.min(totalLines, endLine);
+
+    if (actualStart > totalLines) {
+      return `Error: startLine (${startLine}) is beyond the end of the file (Total lines: ${totalLines}).`;
+    }
+    if (actualStart > actualEnd) {
+      return `Error: startLine (${startLine}) is greater than endLine (${endLine}).`;
+    }
+
+    const chunk = lines.slice(actualStart - 1, actualEnd);
+    const header = `--- ${filePath} (Lines ${actualStart}-${actualEnd} of ${totalLines}) ---\n`;
+    return header + chunk.join('\n');
+  } catch (err) {
+    if (err.code === 'ENOENT') return `Error: File not found at '${filePath}'.`;
+    return `Error reading file chunk: ${err.message}`;
+  }
+}