cowork-cli 0.0.1 → 1.0.0

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 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`.
+- **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": "1.0.0",
+  "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,11 @@
+{
+  "accents": {
+    "main":    "#7BA5DA",
+    "tool":    "#F2CF6E",
+    "data":    "#C2C6C5",
+    "success": "#7AC391",
+    "error":   "#E07070",
+    "dim":     "#606060",
+    "header":  "#A37ACC"
+  }
+}

package/src/configs/sys.txt

@@ -0,0 +1,33 @@
+# IDENTITY
+You are Cowork (cwk), an interactive CLI tool acting as a Full Engineering Read-Only Analyst.
+
+# CORE MANDATES
+- ONLY perform exactly what the user explicitly says.
+- NO unsolicited investigations, side tasks, or extra work of any kind.
+- Provide accurate data with absolute minimum token usage unless "deep work" is requested.
+
+# CONSTRAINTS (Terminal Environment)
+- NO conversational filler, pleasantries, preambles, or postambles.
+- NO Markdown (no *, `, #, or code blocks). NO XML/HTML tags.
+- Output ONLY structured, concise plain text with simple spacing/indentation.
+- Cite code locations using: file_path:line_number.
+
+# EXECUTION & STYLE
+- Answer directly without elaboration or explanation.
+- Use fewer than 4 lines (excluding tool use). One-word answers are preferred.
+- Use all tools efficiently (parallel/sequential) to minimize context usage.
+- Verify dependencies and mimic local code style; never assume availability.
+
+# EXAMPLES
+user: files in src/?
+assistant:
+src/foo.js
+src/bar.js
+
+user: where is foo?
+assistant:
+src/foo.js:12
+
+# CONTEXT
+Working directory: ${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 'cwk --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,228 @@
+import { toolDefinitions, dispatchTool } from '../tools/index.js';
+import { logger } from '../../utils/logger.js';
+import { ui } 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 {
+        ui.think();
+        const response = await this._getCompletion();
+        ui.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) {
+        ui.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;
+
+          ui.update(`Error ${err.status}. Retrying in ${(finalDelay/1000).toFixed(1)}s`);
+          await new Promise(resolve => setTimeout(resolve, finalDelay));
+          ui.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);
+
+        // ui.start() handles terminal-aware truncation internally.
+        if (name !== 'askUser' && name !== 'askConfirm') {
+          ui.start(label, displayArg);
+        }
+        
+        const result = await dispatchTool(name, args);
+        
+        if (name !== 'askUser' && name !== 'askConfirm') {
+          ui.stop();
+        }
+
+        this.addMessage('tool', result, { tool_call_id: toolCall.id });
+
+      } catch (err) {
+        ui.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,50 @@
+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));
+
+/**
+ * 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 sys.txt
+    let systemPrompt = null;
+    try {
+      const promptPath = path.join(__dirname, '../configs/sys.txt');
+      if (fs.existsSync(promptPath)) {
+        systemPrompt = fs.readFileSync(promptPath, 'utf8')
+          .replace('${folder}', process.cwd())
+          .replace(/\${year}/g, new Date().getFullYear());
+      }
+    } catch (e) {
+      // Fallback if prompt 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/askConfirm.js

@@ -0,0 +1,34 @@
+import { ui } from '../../utils/ui.js';
+
+/**
+ * askConfirm tool — asks the user a yes/no question via the terminal.
+ *
+ * Accepted inputs (case-insensitive):
+ *   yes → y, yes
+ *   no  → n, no
+ *   cancel → Ctrl+C (treated as no, with dismissed flag)
+ *
+ * Any other input is silently erased and the prompt re-appears.
+ *
+ * @param {Object} args
+ * @param {string} args.question  The yes/no question to ask.
+ * @returns {Promise<string>}     JSON: { confirmed } or { confirmed, dismissed }
+ */
+export default async function askConfirm({ question }) {
+  // 1. Input validation
+  if (!question || typeof question !== 'string' || question.trim().length === 0) {
+    return JSON.stringify({ error: "'question' must be a non-empty string.", dismissed: true });
+  }
+
+  // 2. TTY guard — cannot prompt in pipes or CI environments
+  if (!process.stdin.isTTY) {
+    return JSON.stringify({
+      error: 'stdin is not a TTY. Cannot prompt in non-interactive environments.',
+      dismissed: true,
+    });
+  }
+
+  // 3. Delegate entirely to UIEngine — it owns all terminal state
+  const result = await ui.confirm(question);
+  return JSON.stringify(result);
+}

package/src/engine/tools/askUser.js

@@ -0,0 +1,32 @@
+import { ui } from '../../utils/ui.js';
+
+/**
+ * Implementation of the askUser tool.
+ * Delegates rendering and input handling to the UIEngine singleton.
+ *
+ * @param {Object} args
+ * @param {string} args.question  The question to ask the user.
+ * @returns {Promise<string>}     JSON string: { answer } or { error, dismissed }.
+ */
+export default async function askUser({ question }) {
+  // 1. Input validation
+  if (!question || typeof question !== 'string' || question.trim().length === 0) {
+    return JSON.stringify({ error: "'question' must be a non-empty string.", dismissed: true });
+  }
+
+  // 2. TTY check
+  if (!process.stdin.isTTY) {
+    return JSON.stringify({ error: 'stdin is not a TTY. Cannot prompt in non-interactive environments.', dismissed: true });
+  }
+
+  try {
+    const answer = await ui.ask(question);
+    return JSON.stringify({ answer });
+  } catch (err) {
+    // ui.ask() rejects with { cancelled: true } on SIGINT, or an Error otherwise.
+    if (err && err.cancelled) {
+      return JSON.stringify({ error: 'User cancelled the request.', dismissed: true });
+    }
+    return JSON.stringify({ error: `System Error: ${err.message}`, dismissed: true });
+  }
+}

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}`;
+  }
+}