cowork-cli 1.2.0 → 2.0.1

package/README.md

@@ -56,6 +56,7 @@ cwk "Explain the data flow in the engine/ models"
 - **Zero-Whitespace UI**: High-density terminal output designed for professionals. No fluff, no headers, just data.
 - **Interactive Feedback**: The AI can request clarifications via the `askUser` tool or trigger an interactive `[ Yes ]  No` toggle using `askConfirm`.
 - **Smart Discovery**: Built-in `searchText`, `findFile`, and `projectTree` tools that respect your `.gitignore`.
+- **Web Research**: Dynamically search the web (`webSearch`) and read documentation (`webFetch`) directly from the CLI.
 - **Surgical I/O**: Read entire files or specific line ranges (`readFileChunk`) with automatic binary detection.
 - **Piping Support**: Pipe logs or diffs directly into `cwk` for instant analysis.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-cli",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "work with cowork",
   "bin": {
     "cwk": "bin/cli.js"
@@ -35,4 +35,4 @@
     "ipaddr.js": "^2.4.0",
     "openai": "^6.38.0"
   }
-}
+}

package/src/engine/models/BaseModel.js

@@ -181,6 +181,7 @@ export default class BaseModel {
           readFileChunk: 'peeking',
           searchText: 'searching',
           webFetch: 'fetching',
+          webSearch: 'searching web',
           findFile: 'finding',
           findDir: 'finding',
           listTools: 'listing'
@@ -189,7 +190,11 @@ export default class BaseModel {
         const label = toolLabels[name] || name;
         let displayArg = "";
 
-        if (name === 'searchText') displayArg = `'${args.pattern}' in ${args.path}`;
+        if (name === 'searchText') {
+          const ctx = (args.context != null && args.context !== 2) ? ` [C${args.context}]` : '';
+          displayArg = `'${args.pattern}' in ${args.path}${ctx}`;
+        }
+        else if (name === 'webSearch') displayArg = `'${args.query}'`;
         else if (name === 'findFile' || name === 'findDir') displayArg = `'${args.pattern}' in ${args.dirPath || '.'}`;
         else if (name === 'readFileChunk') displayArg = `${args.filePath} [L${args.startLine}-${args.endLine}]`;
         else displayArg = args.url || args.filePath || args.dirPath || args.path || args.pattern || JSON.stringify(args);

package/src/engine/tools/index.js

@@ -4,6 +4,7 @@ import projectTree from './projectTree.js';
 import readFileChunk from './readFileChunk.js';
 import searchText from './searchText.js';
 import webFetch from './webFetch.js';
+import webSearch from './webSearch.js';
 import listTools from './listTools.js';
 import findFile from './findFile.js';
 import findDir from './findDir.js';
@@ -73,13 +74,14 @@ export const toolDefinitions = [
     type: "function",
     function: {
       name: "searchText",
-      description: "Regex search in files/folders. Supports recursion and .gitignore.",
+      description: "Regex search in files/folders. Returns matching lines with surrounding context lines. 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)" }
+          recursive: { type: "boolean", description: "Search subdirectories? (default: false)" },
+          context: { type: "number", description: "Lines of context around each match (default: 2, max: 5)." }
         },
         required: ["pattern", "path"]
       }
@@ -99,6 +101,21 @@ export const toolDefinitions = [
       }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "webSearch",
+      description: "Search the web to find URLs, docs, and solutions. Returns a list of titles, URLs, and snippet summaries. Always use this first to find a URL before calling webFetch.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The search term/query." },
+          limit: { type: "number", description: "Max results to return (default: 5, max: 20)." }
+        },
+        required: ["query"]
+      }
+    }
+  },
   {
     type: "function",
     function: {
@@ -182,6 +199,7 @@ const toolImplementations = {
   readFileChunk,
   searchText,
   webFetch,
+  webSearch,
   listTools,
   findFile,
   findDir,

package/src/engine/tools/listTools.js

@@ -30,9 +30,9 @@ export default async function listTools() {
     },
     {
       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."
+      usage: "searchText({ pattern: 'safePath', path: 'src/', recursive: true, context: 3 })",
+      description: "Performs a regex search for text across files and directories. Returns each match with surrounding context lines (default: 2, max: 5). Overlapping context windows are merged. Respects .gitignore.",
+      whenToUse: "To find variable usages, trace function calls, or locate patterns across the codebase. Increase context when you need more surrounding code per match."
     },
     {
       name: "webFetch",
@@ -40,6 +40,12 @@ export default async function listTools() {
       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: "webSearch",
+      usage: "webSearch({ query: 'nodejs fetch api example', limit: 5 })",
+      description: "Searches the web dynamically and returns a list of titles, direct URLs, and snippet summaries (default: 5, max: 20).",
+      whenToUse: "When you need to search the web for external documentation, solutions, or API references before using webFetch to read a specific page."
+    },
     {
       name: "findFile",
       usage: "findFile({ pattern: 'config.*\\\\.js$', dirPath: 'src/', limit: 10 })",
@@ -63,6 +69,12 @@ export default async function listTools() {
       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."
+    },
+    {
+      name: "askConfirm",
+      usage: "askConfirm({ question: 'Should I proceed with deleting this file?' })",
+      description: "Asks the user a yes/no question using an interactive toggle. Returns { confirmed: true } for yes, { confirmed: false } for no, or { confirmed: false, dismissed: true } on cancellation.",
+      whenToUse: "When only a boolean decision is needed from the user. Prefer this over askUser for simple yes/no choices."
     }
   ];
 

package/src/engine/tools/searchText.js

@@ -6,11 +6,12 @@ import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../
 const MAX_MATCHES_PER_FILE = 20;
 const MAX_TOTAL_MATCHES = 100;
 const MAX_DEPTH = 10;
+const CONTEXT_LINES = 2;
 
 /**
  * Enhanced searchText tool with recursion, ignore rules, and safety limits.
  */
-export default async function searchText({ pattern, path: searchPath, recursive = false }) {
+export default async function searchText({ pattern, path: searchPath, recursive = false, context = CONTEXT_LINES }) {
   let totalMatches = 0;
   let isTruncated = false;
 
@@ -66,12 +67,13 @@ export default async function searchText({ pattern, path: searchPath, recursive
             await walk(fullPath, depth + 1, childIgnores);
           }
         } else if (item.isFile()) {
-          const fileMatches = await searchInFile(fullPath, regex);
+          const allowed = MAX_TOTAL_MATCHES - totalMatches;
+          const fileMatches = await searchInFile(fullPath, regex, context);
           if (fileMatches.length > 0) {
-            const allowedInFile = Math.min(fileMatches.length, MAX_TOTAL_MATCHES - totalMatches);
+            const allowedInFile = Math.min(fileMatches.length, allowed);
             results.push({
               file: path.relative(process.cwd(), fullPath),
-              matches: fileMatches.slice(0, allowedInFile)
+              blocks: fileMatches.slice(0, allowedInFile)
             });
             totalMatches += allowedInFile;
             if (fileMatches.length > allowedInFile) isTruncated = true;
@@ -81,12 +83,12 @@ export default async function searchText({ pattern, path: searchPath, recursive
     };
 
     if (stats.isFile()) {
-      const fileMatches = await searchInFile(resolvedPath, regex);
+      const fileMatches = await searchInFile(resolvedPath, regex, context);
       if (fileMatches.length > 0) {
         const allowed = Math.min(fileMatches.length, MAX_TOTAL_MATCHES);
         results.push({
           file: path.relative(process.cwd(), resolvedPath),
-          matches: fileMatches.slice(0, allowed)
+          blocks: fileMatches.slice(0, allowed)
         });
         totalMatches = allowed;
         if (fileMatches.length > allowed) isTruncated = true;
@@ -98,7 +100,7 @@ export default async function searchText({ pattern, path: searchPath, recursive
     if (results.length === 0) return "No matches found.";
 
     let output = results.map(res => {
-      return `[${res.file}]\n${res.matches.join('\n')}`;
+      return `[${res.file}]\n${res.blocks.join('\n---\n')}`;
     }).join('\n');
 
     if (isTruncated) {
@@ -113,8 +115,11 @@ export default async function searchText({ pattern, path: searchPath, recursive
   }
 }
 
-async function searchInFile(filePath, regex) {
+async function searchInFile(filePath, regex, contextLines = CONTEXT_LINES) {
+  const CTX = Math.min(Math.max(0, contextLines), 5);
+
   try {
+    // Binary check — read first 1KB
     const handle = await fs.open(filePath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
@@ -125,16 +130,51 @@ async function searchInFile(filePath, regex) {
 
     const content = await fs.readFile(filePath, 'utf8');
     const lines = content.split('\n');
-    const matches = [];
 
+    // Collect all matching line indices (0-based)
+    const matchIndices = [];
     for (let i = 0; i < lines.length; i++) {
       if (regex.test(lines[i])) {
-        matches.push(`${i + 1}:${lines[i].trim()}`);
-        if (matches.length >= MAX_MATCHES_PER_FILE) break;
+        matchIndices.push(i);
+        if (matchIndices.length >= MAX_MATCHES_PER_FILE * 3) break; // Internal safety cap
+      }
+    }
+
+    if (matchIndices.length === 0) return [];
+
+    // Build context windows, merging overlapping ones
+    const blocks = [];
+    let currentBlock = null;
+
+    for (const idx of matchIndices) {
+      const start = Math.max(0, idx - CTX);
+      const end = Math.min(lines.length - 1, idx + CTX);
+
+      if (currentBlock && start <= currentBlock.end + 1) {
+        // Overlapping or adjacent — merge into current block
+        currentBlock.end = Math.max(currentBlock.end, end);
+        currentBlock.matchIndices.add(idx);
+      } else {
+        if (currentBlock) blocks.push(formatBlock(lines, currentBlock));
+        if (blocks.length >= MAX_MATCHES_PER_FILE) break;
+        currentBlock = { start, end, matchIndices: new Set([idx]) };
       }
     }
-    return matches;
+    if (currentBlock && blocks.length < MAX_MATCHES_PER_FILE) {
+      blocks.push(formatBlock(lines, currentBlock));
+    }
+
+    return blocks;
   } catch (err) {
     return [];
   }
 }
+
+function formatBlock(lines, block) {
+  let output = "";
+  for (let i = block.start; i <= block.end; i++) {
+    const prefix = block.matchIndices.has(i) ? "► " : "  ";
+    output += `${i + 1}:${prefix}${lines[i]}\n`;
+  }
+  return output.trim();
+}

package/src/engine/tools/webSearch.js

@@ -0,0 +1,78 @@
+const TIMEOUT_MS = 10000;
+const MAX_RESULTS_HARD_LIMIT = 20;
+
+/**
+ * Searches the web using DuckDuckGo HTML (zero dependencies).
+ * Extracts title, clean URL, and snippet summary.
+ * 
+ * @param {Object} args
+ * @param {string} args.query - The search query.
+ * @param {number} [args.limit=5] - Max results to return (max 20).
+ * @returns {Promise<string>} JSON string of search results or error message.
+ */
+export default async function webSearch({ query, limit = 5 }) {
+  if (!query) return "Error: Search query cannot be empty.";
+
+  const maxLimit = Math.min(Math.max(1, limit), MAX_RESULTS_HARD_LIMIT);
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    const response = await fetch('https://html.duckduckgo.com/html/', {
+      method: 'POST',
+      signal: controller.signal,
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+      },
+      body: `q=${encodeURIComponent(query)}`
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const html = await response.text();
+    const results = [];
+    
+    // Split HTML into result blocks. 
+    // The slice(1) skips the header block before the first result.
+    const blocks = html.split('class="links_main links_deep result__body"').slice(1);
+    
+    for (const block of blocks) {
+      if (results.length >= maxLimit) break;
+      
+      const titleMatch = block.match(/<h2 class="result__title">[\s\S]*?<a[^>]*>([\s\S]*?)<\/a>/i);
+      const snippetMatch = block.match(/<a class="result__snippet[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i);
+      
+      if (titleMatch && snippetMatch) {
+        // Strip nested HTML tags (like <b> tags for highlighted keywords)
+        const title = titleMatch[1].replace(/<[^>]+>/g, '').trim();
+        const snippet = snippetMatch[2].replace(/<[^>]+>/g, '').trim();
+        
+        // Clean DuckDuckGo's tracking wrapper from the URL
+        let url = snippetMatch[1];
+        if (url.startsWith('//duckduckgo.com/l/?uddg=')) {
+          url = decodeURIComponent(url.split('uddg=')[1].split('&')[0]);
+        }
+        
+        results.push({ title, url, snippet });
+      }
+    }
+
+    if (results.length === 0) {
+      return "No results found.";
+    }
+
+    return JSON.stringify(results, null, 2);
+
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      return `Error: Request timed out after ${TIMEOUT_MS}ms`;
+    }
+    return `Error searching web: ${err.message}`;
+  }
+}

package/src/utils/fsUtils.js

@@ -207,31 +207,51 @@ export function clearIgnoreCache() {
  * 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 {string}   name         Item basename.
+ * @param {Object[]} ignoreList   Structured pattern objects.
  * @param {Object}   [options]
- * @param {boolean}  [options.isDirectory] Whether the item is a directory.
+ * @param {boolean}  [options.isDirectory]   Whether the item is a directory.
  *                   When omitted, directory-only patterns match regardless
  *                   (backward-compatible with existing callers).
+ * @param {string}   [options.relativePath]  Path relative to the project root
+ *                   (e.g. `"src/internal/foo.js"`).  When provided, patterns
+ *                   that contain a `/` are tested against this value instead
+ *                   of being skipped.  When omitted the old skip behaviour is
+ *                   preserved for backward compatibility.
  * @returns {boolean} `true` if the item should be skipped.
  */
 export function shouldIgnore(name, ignoreList, options = {}) {
-  const { isDirectory } = options;
+  const { isDirectory, relativePath } = 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;
+    let matches = false;
+
+    if (entry.hasSlash) {
+      // Path-scoped pattern — needs a full relative path to evaluate.
+      // Without one we conservatively skip it (backward-compatible).
+      if (!relativePath) continue;
+
+      if (entry.hasGlob && entry.regex) {
+        matches = entry.regex.test(relativePath);
+      } else {
+        // Exact segment match: the pattern must equal the relative path
+        // OR appear as a leading path prefix followed by a separator.
+        matches =
+          relativePath === entry.pattern ||
+          relativePath.startsWith(entry.pattern + '/');
+      }
+    } else {
+      // Basename-only pattern — match against the entry name.
+      matches = entry.hasGlob && entry.regex
+        ? entry.regex.test(name)
+        : name === entry.pattern;
+    }
 
     if (matches) {
       ignored = !entry.negated;
@@ -263,7 +283,7 @@ export function safePath(inputPath) {
  *
  * Rejects:
  *  1. Symbolic links (could escape the project sandbox).
- *  2. Names matched by the ignore list.
+ *  2. Names matched by the ignore list (basename AND path-scoped patterns).
  *  3. Paths that resolve outside `process.cwd()`.
  *
  * @param {import('fs').Dirent} dirent      Directory entry from `readdir`.
@@ -274,12 +294,15 @@ export function safePath(inputPath) {
 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();
+  const resolved = path.resolve(parentPath, dirent.name);
   if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
 
+  const isDir = dirent.isDirectory();
+  // Compute the relative path so shouldIgnore() can evaluate path-scoped
+  // patterns like `tests/fixtures/` in addition to bare-name patterns.
+  const relativePath = path.relative(root, resolved);
+  if (shouldIgnore(dirent.name, ignoreList, { isDirectory: isDir, relativePath })) return false;
+
   return true;
 }