@defai.digital/ax-cli 2.3.0 → 2.4.0

package/.ax-cli/CUSTOM.md

@@ -1,97 +1,119 @@
-# Custom Instructions for AX CLI
+# @defai.digital/ax-cli - Quick Reference
 
-**Project**: @defai.digital/ax-cli v1.1.0
-**Type**: cli
-**Language**: TypeScript
-**Stack**: React, Vitest, Zod, Commander, Ink, ESM, TypeScript
+**Type:** cli | **Lang:** TypeScript | **Ver:**  v2.3.1
+**Stack:** React, Vitest, Zod, Commander, Ink, ESM, TypeScript
 
-Generated: 11/19/2025, 2:45:34 AM
+---
 
-## Project Context
+## 🎯 Critical Rules
 
-- **Entry Point**: `dist/index.js`
-- **Package Manager**: npm
-- **Module System**: ESM
-- **CLI Tool**: This is a command-line interface application
+1. **ESM Imports:** Always use `.js` extension: `import { x } from './y.js'`
+2. **Validation:** Use zod for all external inputs
+3. **Types:** Explicit return types required on all functions
+4. **Testing:** 80%+ coverage, test error paths
+5. **Modules:** Use `import/export` (not `require/module.exports`)
 
-## Code Conventions
+---
+
+## 📋 Project Overview
+
+**Entry:** `dist/index.js` | **PM:** npm | **Module:** ESM
+
+
+**Directories:**
+- `src/` - Source code
+- `tests/` - Tests
+- `src/tools/` - Tools
+- `src/commands/` - Commands
+- `src/utils/` - Utilities
+
+---
+
+## 🔧 Code Patterns
 
 ### TypeScript
-- Use explicit type annotations for function parameters and returns
-- Prefer `const` and `let` over `var`
-- Use strict mode (strict type checking enabled)
-- **CRITICAL**: Always use `.js` extension in import statements (ESM requirement)
-  - Example: `import { foo } from "./bar.js"` (NOT "./bar" or "./bar.ts")
-
-### ES Modules
-- Use `import/export` syntax (not `require/module.exports`)
-- Top-level await is supported
-
-### Validation
-- Use **zod** for runtime validation
-- Validate all external inputs (API requests, file reads, user input)
-- Use `.safeParse()` for error handling
-
-## File Structure
-
-- **Source Code**: `src/`
-- **Tests**: `tests/`
-- **Tools**: `src/tools/`
-
-### Typical Structure
-- Commands: `src/commands/`
-- Utilities: `src/utils/`
-- Types: `src/types/`
-
-### Key Files
-- `package.json`: Node.js package configuration
-- `tsconfig.json`: TypeScript configuration
-- `vitest.config.ts`: Vitest test configuration
-- `.eslintrc.js`: ESLint configuration
-- `README.md`: Project documentation
-- `CLAUDE.md`: Claude-specific instructions
-
-## Development Workflow
-
-### Before Making Changes
-1. Read relevant files with `view_file` to understand current implementation
-2. Use `search` to find related code or patterns
-3. Check existing tests to understand expected behavior
-
-### Making Changes
-1. **NEVER** use `create_file` on existing files - use `str_replace_editor` instead
-2. Make focused, atomic changes
-3. Preserve existing code style and patterns
-4. Update related tests when modifying functionality
-
-### After Changes
-1. Run linter: `eslint . --ext .js,.jsx,.ts,.tsx`
-2. Run tests: `vitest run`
-3. Build: `tsc`
-
-## Testing Guidelines
-
-### Vitest
-- Use `describe`, `it`, `expect` for test structure
-- Place tests in `tests/` directory or `*.test.ts` files
-- Test edge cases: empty inputs, null/undefined, boundary conditions
-- Include Unicode and special character tests where relevant
-
-### Coverage Requirements
-- Aim for high test coverage (80%+ for new code)
-- Always test error paths and edge cases
-- Test both success and failure scenarios
-
-## Available Scripts
-
-- **Development**: `bun run src/index.ts`
-- **Build**: `tsc`
-- **Test**: `vitest run`
-- **Lint**: `eslint . --ext .js,.jsx,.ts,.tsx`
-
-### Quick Commands
+
+✅ **DO:**
+```typescript
+// Explicit types
+function process(x: string): Promise<Result> { }
+
+// ESM imports with .js extension
+import { foo } from './bar.js';
+```
+
+❌ **DON'T:**
+```typescript
+// No any types
+function process(x: any) { }  // ❌
+
+// Missing .js extension
+import { foo } from './bar';  // ❌
+```
+
+### Validation (zod)
+
+✅ **DO:**
+```typescript
+const result = schema.safeParse(data);
+if (!result.success) {
+  return { success: false, error: result.error };
+}
+```
+
+### CLI Commands
+Commands should:
+- Accept options via flags (`-f, --flag <value>`)
+- Validate input before execution
+- Provide clear error messages
+- Return exit codes (0 = success, 1+ = error)
+
+---
+
+## 🔄 Workflow
+
+**Before:**
+- Read files to understand implementation
+- Search for related patterns
+- Review tests for expected behavior
+
+**Changes:**
+- Edit existing files (never recreate)
+- Keep changes focused and atomic
+- Preserve code style
+- Update tests when changing functionality
+
+**After:**
+1. Lint: `eslint . --ext .js,.jsx,.ts,.tsx`
+2. Test: `vitest run`
+3. Build: `npm run build:schemas && tsc`
+
+**Quick Commands:**
 ```bash
-npm run dev    # Start development
-npm test   # Run tests
-npm run build  # Build for production
-```
+npm run dev     # Development
+npm test    # Run tests
+npm run build   # Production build
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### "Module not found" errors
+**Solution:** Add `.js` extension to imports (ESM requirement)
+```typescript
+// ✅ Correct
+import { x } from './y.js';
+
+// ❌ Wrong
+import { x } from './y';  // Missing .js
+```
+
+### zod validation errors
+**Solution:** Use `.safeParse()` for detailed error messages. Check schema matches data structure.
+
+### Tests fail locally but pass in CI
+**Solution:** Check Node version, clear node_modules, check environment-specific code
+
+### TypeScript compilation errors
+**Solution:** Check `tsconfig.json` settings, ensure all types are imported, verify `moduleResolution`

package/.ax-cli/index.json

@@ -1,6 +1,6 @@
 {
   "projectName": "@defai.digital/ax-cli",
-  "version": "1.1.0",
+  "version": "2.3.1",
   "primaryLanguage": "TypeScript",
   "techStack": [
     "React",
@@ -16,6 +16,7 @@
   "directories": {
     "source": "src",
     "tests": "tests",
+    "config": "config",
     "tools": "src/tools"
   },
   "keyFiles": [
@@ -33,11 +34,11 @@
     "validation": "zod"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "npm run build:schemas && tsc",
     "test": "vitest run",
     "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
     "dev": "bun run src/index.ts"
   },
   "packageManager": "npm",
-  "lastAnalyzed": "2025-11-19T07:45:34.457Z"
+  "lastAnalyzed": "2025-11-19T22:52:24.501Z"
 }

package/README.md

@@ -6,9 +6,9 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9%2B-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-[![macOS](https://img.shields.io/badge/macOS-26-000000?style=flat-square&logo=apple)](https://www.apple.com/macos/)
-[![Windows](https://img.shields.io/badge/Windows-11-0078D6?style=flat-square&logo=windows)](https://www.microsoft.com/windows/)
-[![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-E95420?style=flat-square&logo=ubuntu)](https://ubuntu.com/)
+[![macOS](https://img.shields.io/badge/macOS-26-blue?style=flat-square&logo=apple)](https://www.apple.com/macos/)
+[![Windows](https://img.shields.io/badge/Windows-11-blue?style=flat-square&logo=windows)](https://www.microsoft.com/windows/)
+[![Ubuntu](https://img.shields.io/badge/Ubuntu-24.04-blue?style=flat-square&logo=ubuntu)](https://ubuntu.com/)
 
 ![AX CLI Logo](.github/assets/ax-cli.png)
 
@@ -29,9 +29,6 @@ ax-cli init
 
 # Start interactive mode
 ax-cli
-
-# Run headless command
-ax-cli -p "list all TypeScript files"
 ```
 
 ## ✨ Features
@@ -93,16 +90,6 @@ AX CLI officially supports the following platforms:
 npm install -g @defai.digital/ax-cli
 ```
 
-### Local Development
-
-```bash
-git clone https://github.com/defai-digital/ax-cli.git
-cd ax-cli
-npm install
-npm run build
-npm link
-```
-
 [Installation Guide →](docs/installation.md)
 
 ## ⚙️ Configuration
@@ -156,6 +143,46 @@ ax-cli -p "write tests for utils/" --max-tool-rounds 50
 ax-cli -p "refactor" --model glm-4.6
 ```
 
+### 🔌 VSCode Integration (NEW!)
+
+AX CLI integrates seamlessly with Visual Studio Code via tasks and keyboard shortcuts:
+
+```bash
+# Analyze current file
+ax-cli --prompt "Analyze this file" --file src/index.ts --json --vscode
+
+# Explain selected code
+ax-cli --prompt "Explain this code" --selection "function foo() {...}" --json --vscode
+
+# Review git changes
+ax-cli --prompt "Review my changes" --git-diff --json --vscode
+
+# Analyze specific line range
+ax-cli --prompt "Optimize this section" --file app.ts --line-range 50-100 --json
+```
+
+**Quick Setup:**
+```bash
+# Copy VSCode templates to your project
+cd your-project
+mkdir -p .vscode
+cp node_modules/@defai.digital/ax-cli/templates/vscode/*.json .vscode/
+
+# Start using with Cmd+Shift+P → "Tasks: Run Task" → Select AX task
+```
+
+**Pre-configured Tasks:**
+- 🔍 Analyze Current File
+- 📝 Explain Selection
+- 🔄 Review Git Changes
+- 🧪 Generate Tests
+- 📚 Document Code
+- ♻️ Refactor Selection
+- 🐛 Find Bugs
+- ⚡ Optimize Performance
+
+[VSCode Integration Guide →](docs/vscode-integration-guide.md)
+
 ### Project Initialization
 
 ```bash

package/config/prompts.yaml

@@ -12,6 +12,7 @@ system_prompt:
       - "Precision: Make exact, targeted changes - never broad strokes"
       - "Self-Correction: Validate your work and fix issues immediately"
       - "Minimal Verbosity: Show results, not commentary"
+      - "Smart Tool Usage: Answer simple questions directly. Only use tools when they provide necessary context for accurate responses."
 
   tools_header: "Available Tools:"
 
@@ -84,6 +85,12 @@ system_prompt:
            - Configuration files (package.json, tsconfig.json)
            - Then specific modules as needed
 
+        4. CRITICAL - Complete the task:
+           - Gather information ONCE, then act on it
+           - Don't repeat the same exploration tools
+           - After getting tool results, USE them to complete the user's request
+           - Example: If asked for line count and you found files, COUNT them - don't search again
+
     file_operations:
       title: "FILE OPERATION SAFETY"
       steps:
@@ -108,6 +115,8 @@ system_prompt:
         - "Explain complex decisions only when necessary"
         - "Errors: state problem → show fix → done"
         - "Success: confirm completion → show key changes"
+        - "Simple questions: Answer directly without unnecessary tool calls"
+        - "If you find yourself calling the same tool multiple times with no progress, STOP and provide a direct answer"
 
     confirmation_behavior:
       title: "USER CONFIRMATION FLOW"

package/config/settings.yaml

@@ -5,6 +5,7 @@ agent:
   max_tool_rounds: 400
   default_timeout: 360000  # 6 minutes in milliseconds
   default_max_tokens: 8192
+  max_recent_tool_calls: 20  # Keep only last 20 unique tool calls
 
 file:
   max_file_size: 1048576  # 1MB in bytes
@@ -29,6 +30,7 @@ token:
   default_model: gpt-4
   default_encoding: cl100k_base
   cache_max_size: 1000
+  chars_per_token_estimate: 4  # Rough approximation for token estimation
 
 cache:
   default_max_size: 1000

package/dist/agent/llm-agent.d.ts

@@ -40,11 +40,28 @@ export declare class LLMAgent extends EventEmitter {
     private contextManager;
     private abortController;
     private maxToolRounds;
+    private recentToolCalls;
     constructor(apiKey: string, baseURL?: string, model?: string, maxToolRounds?: number);
     private initializeMCP;
     private isGrokModel;
+    /**
+     * Detect if a tool call is repetitive (likely causing a loop)
+     * Returns true if the same tool with similar arguments was called multiple times recently
+     */
+    private isRepetitiveToolCall;
+    /**
+     * Reset the tool call tracking (called at start of new user message)
+     */
+    private resetToolCallTracking;
     private shouldUseSearchFor;
     processUserMessage(message: string): Promise<ChatEntry[]>;
+    /**
+     * Recursively merge streaming delta into accumulated message
+     */
+    private reduceStreamDelta;
+    /**
+     * Accumulate streaming message chunks
+     */
     private messageReducer;
     /**
      * Prepare user message and apply context management