cowork-cli 0.0.1 → 0.2.8

package/README.md

@@ -0,0 +1,78 @@
+# 🚀 cowork-cli (cwk)
+
+**Stop waiting. Start knowing.**
+
+`cowork-cli` (`cwk`) is the ultimate high-speed CLI Analyst for developers who need answers, not a conversation. It's a minimalist, context-aware co-processor that lives in your terminal and understands your code as well as you do.
+
+## 🔥 Universal AI Power
+
+Think your favorite model won't work? **Think again!** `cwk` is built to be compatible with **any** (yes, ANY!) OpenAI-compatible API endpoint on the planet.
+
+Whether you're running local models via Ollama, using specialized providers, or tapping into the world's most powerful LLMs via **OpenRouter**, `cwk` has you covered.
+
+### 🌟 Full Gemini Support
+Love Google's Gemini models? We do too. `cwk` features a specialized handler to preserve the high-density analytical capabilities of the Gemini suite, ensuring you get the best out of **Gemini 3.1 Pro** and **Flash**.
+
+---
+
+## 🛠️ Rapid Setup (OpenRouter Example)
+
+Get up and running in seconds. Just point `cwk` to your provider in your `~/.env` file:
+
+```env
+# Example using OpenRouter to access Gemini 3.1 Pro
+CWK_MODEL_NAME=google/gemini-3.1-pro
+CWK_MODEL_URL=https://openrouter.ai/api/v1
+CWK_MODEL_API_KEY=your_openrouter_key
+CWK_MODEL_TYPE=openai
+```
+
+---
+
+## ⚡ Real-World Usage
+
+`cwk` doesn't just "chat"—it **investigates**. It uses a suite of built-in tools to map your project, search for patterns, and read files before giving you a hard-hitting, plain-text technical answer.
+
+### 🔍 Explore your codebase
+```bash
+cwk "Where is the authentication logic handled?"
+```
+*`cwk` will automatically list directories, find relevant files, and peek at the code to give you a precise summary.*
+
+### 🛠️ Debug like a pro
+```bash
+cwk "Find all 'FIXME' tags in src/ and tell me which one is most critical"
+```
+
+### 🧠 Instant Documentation
+```bash
+cwk "Explain the data flow in the engine/ models"
+```
+
+---
+
+## ✨ Features that Matter
+
+- **Zero-Whitespace UI**: High-density terminal output designed for professionals. No fluff, no headers, just data.
+- **Interactive Feedback**: The AI can now ask you clarifying questions via the `askUser` tool when it needs more context.
+- **Smart Discovery**: Built-in `searchText`, `findFile`, and `projectTree` tools that respect your `.gitignore`.
+- **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.
+
+## 📦 Installation
+
+```bash
+npm install -g cowork-cli
+```
+
+## ⌨️ Commands
+
+| Command | Description |
+| :--- | :--- |
+| `cwk "query"` | Run a one-shot analysis on your codebase. |
+| `cwk -v`, `--version` | Display the current version of `cwk`. |
+| `cwk --help` | Show the minimalist help menu. |
+
+---
+
+*“cwk... how does this work again?”*

package/bin/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * @file cli.js
+ * @description Executable entry point for the cwk CLI tool.
+ * Handles top-level error boundaries and passes execution to the main application logic.
+ */
+
+import main from "../src/main.js";
+import { logger } from "../src/utils/logger.js";
+
+// Catch unhandled promise rejections
+process.on('unhandledRejection', (reason) => {
+  process.stdout.write('\x1b[?25h'); // Restore cursor
+  logger.error(`[Fatal] Unhandled Rejection: ${reason instanceof Error ? reason.message : reason}`);
+  process.exitCode = 1;
+});
+
+// Catch uncaught exceptions
+process.on('uncaughtException', (err) => {
+  process.stdout.write('\x1b[?25h'); // Restore cursor
+  logger.error(`[Fatal] Uncaught Exception: ${err.message}`);
+  process.exitCode = 1;
+});
+
+// Graceful exit on interrupt
+process.on('SIGINT', () => {
+  process.stdout.write('\x1b[?25h'); // Restore cursor
+  logger.secondary('Process interrupted by user.');
+  process.exit(130);
+});
+
+async function run() {
+  try {
+    // Pass command line arguments (excluding 'node' and the script path) to main
+    await main(process.argv.slice(2));
+  } catch (err) {
+    logger.error(`[Error]: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+run();

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "cowork-cli",
-  "version": "0.0.1",
-  "description": "Cowork CLI",
-  "type": "module",
+  "version": "0.2.8",
+  "description": "work with cowork",
   "bin": {
-    "cwk": "index.js"
+    "cwk": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "cli",
+    "ai"
+  ],
+  "homepage": "https://github.com/sapirrior/cowork-cli#readme",
+  "bugs": {
+    "url": "https://github.com/sapirrior/cowork-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sapirrior/cowork-cli.git"
+  },
+  "license": "MIT",
+  "author": "nolan stark",
+  "type": "module",
+  "main": "./src/main.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "license": "MIT"
-}
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "ipaddr.js": "^2.4.0",
+    "openai": "^6.38.0"
+  }
+}

package/src/configs/config.json

@@ -0,0 +1,8 @@
+{
+  "accents": {
+    "orangex": "#D97757",
+    "greyx": "#808080",
+    "resetx": "#FFFFFF"
+  },
+  "systemPrompt": "You are a concise Developer Analyst. Use available tools proactively to investigate and process the user query. Provide a direct answer based on your findings. ENVIRONMENT: Terminal. STRICT RULES: 1. NO conversational filler or pleasantries. 2. NO Markdown formatting (do not use asterisks, backticks, or hashes). 3. NO XML or HTML tags. 4. Output ONLY structured, concise plain text. 5. Use simple spacing and indentation for structure. CWD: ${folder}. Year: ${year}."
+}

package/src/engine/client.js

@@ -0,0 +1,26 @@
+import { OpenAI } from 'openai';
+import { loadConfig, validateConfig } from '../utils/configManager.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Initializes and returns an OpenAI client instance.
+ * @returns {OpenAI} An instance of the OpenAI client.
+ */
+function clientLoader() {
+  const config = loadConfig();
+  
+  if (!validateConfig(config)) {
+    throw new Error("Configuration missing or invalid. Please configure your ~/.env file (run 'btw --help' for details).");
+  }
+
+  // Normalize baseURL: remove trailing slashes as the SDK appends paths starting with /
+  const baseURL = config.model_url.replace(/\/+$/, '');
+
+  return new OpenAI({
+    apiKey: config.model_api_key,
+    baseURL: baseURL,
+    timeout: 60000 // 60 seconds timeout
+  });
+}
+
+export default clientLoader;

package/src/engine/models/BaseModel.js

@@ -0,0 +1,232 @@
+import { toolDefinitions, dispatchTool } from '../tools/index.js';
+import { logger } from '../../utils/logger.js';
+import { spinner } from '../../utils/ui.js';
+import { outputFormatted } from '../../utils/outputFormatter.js';
+
+/**
+ * Base class for AI model interaction handlers.
+ * Encapsulates message history, API calling with retries, and robust tool execution.
+ */
+export default class BaseModel {
+  /**
+   * @param {import('openai').OpenAI} client Initialized OpenAI client.
+   * @param {string} model Model identifier.
+   */
+  constructor(client, model) {
+    this.client = client;
+    this.model = model;
+    this.messages = [];
+    this.maxTurns = 15; // Safeguard against infinite tool-calling loops
+    this.lastRequestTime = 0; // For proactive throttling
+  }
+
+  /**
+   * Adds a message to the conversation history.
+   * @param {string} role 'user', 'assistant', 'system', or 'tool'.
+   * @param {string} content Message content.
+   * @param {Object} extra Additional fields (e.g., tool_call_id).
+   */
+  addMessage(role, content, extra = {}) {
+    this.messages.push({ role, content, ...extra });
+  }
+
+  /**
+   * Main execution loop for the model query.
+   * @param {string} query The user input.
+   * @param {string|null} systemPrompt Optional system-level instructions.
+   */
+  async run(query, systemPrompt = null) {
+    if (systemPrompt) {
+      this.addMessage('system', systemPrompt);
+    }
+    this.addMessage('user', query);
+    
+    let turn = 0;
+    while (turn < this.maxTurns) {
+      turn++;
+      
+      try {
+        spinner.start("Thinking");
+        const response = await this._getCompletion();
+        spinner.stop();
+
+        const message = response.choices[0].message;
+
+        // Let subclasses handle/format the response (e.g. Gemini thought signatures)
+        await this.handleResponse(message);
+
+        // Exit loop if no tool calls are requested (Final Answer)
+        if (!message.tool_calls || message.tool_calls.length === 0) {
+          if (message.content) {
+            const formatted = outputFormatted(message.content);
+            process.stdout.write(formatted);
+            if (!formatted.endsWith('\n')) {
+              process.stdout.write("\n");
+            }
+          }
+          return;
+        }
+
+        // Execute and record tool calls
+        await this._processToolCalls(message.tool_calls);
+
+      } catch (err) {
+        spinner.stop();
+        // Deep error logging for API failures
+        if (err.status) {
+          logger.error(`[API Error] Status: ${err.status}`);
+          if (err.response?.data) {
+             logger.error(`[API Error] Details: ${JSON.stringify(err.response.data)}`);
+          }
+        } else if (err.name === 'AbortError' || err.message.includes('timeout')) {
+          logger.error(`[Timeout Error]: The AI took too long to respond (60s).`);
+        } else {
+          logger.error(`[Error]: ${err.message}`);
+        }
+        throw err;
+      }
+    }
+
+    logger.secondary("[System]: Reached maximum conversation turns. Ending session.");
+  }
+
+  /**
+   * Private method to fetch completion with exponential backoff for transient errors.
+   * @private
+   */
+  async _getCompletion() {
+    let retries = 0;
+    const maxRetries = 5;
+    const minDelayBetweenRequests = 1000; // 1s proactive throttle
+    
+    while (retries <= maxRetries) {
+      try {
+        // 1. Proactive Throttling
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < minDelayBetweenRequests) {
+          const waitTime = minDelayBetweenRequests - timeSinceLastRequest;
+          await new Promise(resolve => setTimeout(resolve, waitTime));
+        }
+
+        const response = await this.client.chat.completions.create({
+          model: this.model,
+          messages: this.messages,
+          tools: toolDefinitions,
+          tool_choice: "auto"
+        });
+
+        // Update last request time on successful response
+        this.lastRequestTime = Date.now();
+        return response;
+
+      } catch (err) {
+        const isTransient = [429, 500, 502, 503, 504].includes(err.status);
+        if (isTransient && retries < maxRetries) {
+          retries++;
+          
+          let delay = Math.pow(2, retries) * 1000;
+          
+          // 2. Adhere to Retry-After header if present
+          const retryAfter = err.headers?.['retry-after'];
+          if (retryAfter) {
+            const seconds = parseInt(retryAfter);
+            if (!isNaN(seconds)) {
+              delay = seconds * 1000;
+            } else {
+              // Handle Date string
+              const retryDate = new Date(retryAfter);
+              if (!isNaN(retryDate.getTime())) {
+                delay = Math.max(0, retryDate.getTime() - Date.now());
+              }
+            }
+          }
+
+          // 3. Apply Jitter (randomness to prevent thundering herd)
+          const jitter = Math.random() * 500;
+          const finalDelay = delay + jitter;
+
+          spinner.update(`Error ${err.status}. Retrying in ${(finalDelay/1000).toFixed(1)}s`);
+          await new Promise(resolve => setTimeout(resolve, finalDelay));
+          spinner.update("Thinking");
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  /**
+   * Private method to handle tool calls with deep error recovery.
+   * @private
+   */
+  async _processToolCalls(toolCalls) {
+    for (const toolCall of toolCalls) {
+      const name = toolCall.function.name;
+      let args;
+      
+      try {
+        // 1. Robust Argument Parsing
+        try {
+          args = JSON.parse(toolCall.function.arguments);
+        } catch (parseErr) {
+          throw new Error(`Invalid JSON arguments provided for tool '${name}': ${parseErr.message}`);
+        }
+
+        // Semantic Tool Logging
+        const toolLabels = {
+          readFile: 'reading',
+          readDir: 'listing',
+          projectTree: 'mapping',
+          readFileChunk: 'peeking',
+          searchText: 'searching',
+          webFetch: 'fetching',
+          findFile: 'finding',
+          findDir: 'finding',
+          listTools: 'listing'
+        };
+
+        const label = toolLabels[name] || name;
+        let displayArg = "";
+
+        if (name === 'searchText') displayArg = `'${args.pattern}' in ${args.path}`;
+        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);
+
+        const displayStr = displayArg.length > 60 ? displayArg.slice(0, 57) + "..." : displayArg;
+
+        // NOTE: 'askUser' is interactive and handles its own semantic logging ([asking]) 
+        // to maintain terminal focus and avoid conflicts with the global spinner.
+        if (name !== 'askUser') {
+          logger.secondary(`[${label}] ${displayStr}`);
+          spinner.start(`[${label}] working`);
+        }
+        
+        const result = await dispatchTool(name, args);
+        
+        if (name !== 'askUser') {
+          spinner.stop();
+        }
+
+        this.addMessage('tool', result, { tool_call_id: toolCall.id });
+
+      } catch (err) {
+        spinner.stop();
+        const errorMsg = err.message;
+        logger.error(`[FAILED] ${name}: ${errorMsg}`);
+        
+        // 3. Model Recovery: Feed the error back to the model
+        this.addMessage('tool', `Error: ${errorMsg}`, { tool_call_id: toolCall.id });
+      }
+    }
+  }
+
+  /**
+   * Overridden by subclasses to handle provider-specific message formatting.
+   * @param {Object} message The message object from the API.
+   */
+  async handleResponse(message) {
+    this.messages.push(message);
+  }
+}

package/src/engine/models/default.js

@@ -0,0 +1,8 @@
+import BaseModel from './BaseModel.js';
+
+/**
+ * Standard OpenAI-compatible model handler.
+ */
+export default class DefaultModel extends BaseModel {
+  // Uses default implementation from BaseModel
+}

package/src/engine/models/gemini.js

@@ -0,0 +1,20 @@
+import BaseModel from './BaseModel.js';
+
+/**
+ * Gemini-specific model handler.
+ * Handles preservation of 'thought_signature' in tool calls.
+ */
+export default class GeminiModel extends BaseModel {
+  /**
+   * Gemini requires the 'thought_signature' and potentially other metadata
+   * to be passed back in the conversation history for tool-calling turns.
+   */
+  async handleResponse(message) {
+    // We push the full message object to ensure all provider-specific
+    // fields (like thought_signature) are preserved in the history.
+    this.messages.push(message);
+  }
+  
+  // We might need to override run to handle the 'extra_body' if the SDK is too strict,
+  // but let's try the simple history preservation first.
+}

package/src/engine/run.js

@@ -0,0 +1,51 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from '../utils/logger.js';
+import DefaultModel from './models/default.js';
+import GeminiModel from './models/gemini.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = path.join(__dirname, '../configs/config.json');
+
+/**
+ * Executes a chat completion query using the appropriate model handler.
+ * @param {import('openai').OpenAI} client The initialized OpenAI client.
+ * @param {Object} config The user configuration (from .env).
+ * @param {string} query The user query string.
+ */
+export default async function runQuery(client, config, query) {
+  if (!query) {
+    logger.error("Error: No query provided.");
+    return;
+  }
+
+  try {
+    // 1. Load and format system prompt from internal config
+    let systemPrompt = null;
+    try {
+      const internalConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+      if (internalConfig.systemPrompt) {
+        systemPrompt = internalConfig.systemPrompt
+          .replace('${folder}', process.cwd())
+          .replace('${year}', new Date().getFullYear());
+      }
+    } catch (e) {
+      // Fallback if config is missing - proceed without system prompt
+    }
+
+    const isGemini = config.model_type.toLowerCase() === 'gemini';
+    const modelHandler = isGemini 
+      ? new GeminiModel(client, config.model_name) 
+      : new DefaultModel(client, config.model_name);
+
+    await modelHandler.run(query, systemPrompt);
+  } catch (err) {
+    logger.error(`Error during AI execution: ${err.message}`);
+    if (err.status === 401) {
+      logger.secondary("Tip: Check if your API key is correct in your ~/.env file.");
+    } else if (err.status === 404) {
+      logger.secondary("Tip: The specified model or base URL might be incorrect.");
+    }
+  }
+}

package/src/engine/tools/askUser.js

@@ -0,0 +1,62 @@
+import readlinePromises from 'readline/promises';
+import readline from 'readline';
+import { stdin as input, stdout as output } from 'process';
+import { formatSecondary } from '../../utils/logger.js';
+
+/**
+ * Implementation of the askUser tool.
+ * Asks the user a single question via the terminal.
+ * 
+ * @param {Object} args
+ * @param {string} args.question The question to ask the user.
+ * @returns {Promise<string>} JSON string with answer or error.
+ */
+export default async function askUser({ question }) {
+  // 1. Input Validation
+  if (!question) {
+    return "Error: 'question' parameter is required.";
+  }
+  
+  if (typeof question !== 'string' || question.trim().length === 0) {
+    return "Error: 'question' must be a non-empty string.";
+  }
+
+  // 2. TTY Check: Ensure we have a terminal to interact with
+  if (!input.isTTY) {
+    return "Error: stdin is not a TTY. Cannot prompt user in non-interactive environments.";
+  }
+
+  const rl = readlinePromises.createInterface({ input, output });
+
+  return new Promise((resolve) => {
+    // 3. Graceful Signal Handling
+    rl.on('SIGINT', () => {
+      rl.close();
+      process.stdout.write(formatSecondary(` cancelled\n`));
+      resolve(JSON.stringify({ error: "user cancelled the request", dismissed: true }));
+    });
+
+    const doAsk = async () => {
+      try {
+        const answer = await rl.question(formatSecondary(`[asking] ${question} -> `));
+        const trimmed = answer.trim();
+
+        if (trimmed.length === 0) {
+          // Move cursor up and clear line reliably using Node's readline methods
+          readline.moveCursor(process.stdout, 0, -1);
+          readline.clearLine(process.stdout, 0);
+          readline.cursorTo(process.stdout, 0);
+          doAsk();
+        } else {
+          rl.close();
+          resolve(JSON.stringify({ answer: trimmed }));
+        }
+      } catch (err) {
+        rl.close();
+        resolve(JSON.stringify({ error: `System Error: ${err.message}`, dismissed: true }));
+      }
+    };
+
+    doAsk();
+  });
+}

package/src/engine/tools/findDir.js

@@ -0,0 +1,73 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+
+/**
+ * findDir tool: Finds directories by name using regex.
+ * @param {Object} args
+ * @param {string} args.pattern Regex pattern to match directory names.
+ * @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 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');
+    } catch (e) {
+      return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
+    }
+
+    const ignoreList = await getIgnorePatterns();
+    const results = [];
+
+    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 (regex.test(item.name)) {
+            results.push(path.relative(process.cwd(), fullPath));
+          }
+          
+          if (recursive) {
+            await walk(fullPath);
+          }
+        }
+      }
+    }
+
+    await walk(dirPath);
+
+    if (results.length === 0) {
+      return `No directories 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 directories: ${err.message}`;
+  }
+}