goatchain-cli 0.0.2-beta.10

package/README.md

@@ -0,0 +1,368 @@
+# GoatChain CLI 🐐
+
+> Interactive AI agent CLI for software engineering tasks with built-in file operations, web search, and planning capabilities
+
+[![npm version](https://badge.fury.io/js/goatchain-cli.svg)](https://badge.fury.io/js/goatchain-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ✨ Features
+
+- **🤖 Interactive AI Agent** - Real-time conversation with AI assistant for coding tasks
+- **📁 File Operations** - Read, write, edit files with built-in safety checks
+- **🔍 Code Navigation** - Glob search, grep, and AST-aware code analysis
+- **🌐 Web Search** - Integrated web search for up-to-date information
+- **📋 Plan Mode** - Structured planning workflow (plan → confirm → execute)
+- **💾 Session Management** - Save and restore conversation sessions
+- **🔧 Tool Integration** - Built-in tools for common development tasks
+- **🖼️ Image Support** - Attach and analyze images in conversations
+- **⚙️ Configurable** - Flexible configuration via environment and config files
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install globally via npm
+npm install -g goatchain-cli
+
+# Or use npx (recommended for first-time use)
+npx goatchain-cli
+
+# Or install locally in your project
+npm install --save-dev goatchain-cli
+```
+
+### Basic Usage
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY=your-api-key-here
+
+# Start the CLI
+goatchain
+
+# Or with npx
+npx goatchain-cli
+```
+
+### First Conversation
+
+```bash
+$ goatchain
+🤖 GoatChain CLI v0.0.2-beta.6
+
+Welcome! I'm your AI assistant. Type /help for commands or ask me anything.
+
+> Can you help me understand this TypeScript project?
+```
+
+## 📦 Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+```bash
+npm install -g goatchain-cli
+```
+
+### Method 2: Project-based Installation
+
+```bash
+# Add to your project
+npm install --save-dev goatchain-cli
+
+# Run from project directory
+npx goatchain
+```
+
+### Method 3: Direct from GitHub
+
+```bash
+# Run directly from GitHub repository
+npx github:zjywill/GoatChain#main:packages/cli
+```
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+```bash
+# Required: OpenAI API key
+export OPENAI_API_KEY=sk-...
+
+# Optional: Web search (Serper API)
+export SERPER_API_KEY=your-serper-key
+
+# Optional: Default model
+export GOATCHAIN_MODEL=gpt-4o
+
+# Optional: OpenAI-compatible base URL (e.g. DeepSeek / GLM)
+export GOATCHAIN_OPENAI_BASE_URL=...
+
+# Optional: Enable plan mode by default
+export GOATCHAIN_PLAN_MODE=1
+```
+
+### Local Configuration File
+
+Create `.goatchain/config.json` in your project:
+
+```json
+{
+  "model": {
+    "provider": "openai",
+    "modelId": "gpt-4o"
+  },
+  "tools": {
+    "webSearch": {
+      "apiKey": "your-serper-key",
+      "numResults": 10
+    }
+  },
+  "planMode": "on"
+}
+```
+
+## 🎯 Commands Reference
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show help information |
+| `/model <id>` | Switch model (e.g., `gpt-4o`, `gpt-3.5-turbo`) |
+| `/plan [on|off|toggle]` | Toggle plan mode |
+| `/approvals` | Select approval mode |
+| `/set <key> <value>` | Set request parameters |
+| `/unset <key>` | Clear a parameter |
+| `/params` | Show current parameters |
+
+### Session Management
+
+| Command | Description |
+|---------|-------------|
+| `/sessions` | List saved sessions |
+| `/use <sessionId>` | Restore a session |
+| `/save` | Save current session |
+| `/new` | Start new conversation |
+| `/status` | Show current status |
+
+### Tool Configuration
+
+| Command | Description |
+|---------|-------------|
+| `/tools` | List enabled tools |
+| `/base-url <url>` | Set API base URL |
+| `/api-key <key>` | Set API key |
+| `/web-search-key <key>` | Set web search API key |
+
+### OpenAI-Compatible Providers (DeepSeek / GLM)
+
+GoatChain CLI uses an OpenAI-compatible client. To use other providers, set `/base-url` (or `GOATCHAIN_OPENAI_BASE_URL`) and provide the matching API key via `/api-key` (or `OPENAI_API_KEY`).
+
+Examples of model ids you can select via `/model`:
+- DeepSeek: `deepseek-chat`, `deepseek-reasoner`, `deepseek-v3.1`
+- GLM: `glm-4-plus`, `glm-4-air`, `glm-4-flash`, `glm-4v-plus`
+
+## 🔧 Built-in Tools
+
+### File Operations
+
+- **Read** - Read files and directories
+- **Write** - Create new files
+- **Edit** - Modify existing files
+- **Glob** - Pattern-based file search
+- **Grep** - Content search across files
+
+### Development Tools
+
+- **WebSearch** - Internet search for current information
+- **AskUserQuestion** - Interactive user prompts for decisions
+- **TodoWrite** - Structured task planning
+- **Bash** - Execute shell commands
+
+### Code Analysis
+
+- **ast_grep_search** - AST-aware code pattern matching
+- **ast_grep_replace** - AST-aware code refactoring
+
+## 📋 Plan Mode
+
+Plan mode enables a structured workflow for complex tasks:
+
+```bash
+# Enable plan mode
+/plan on
+
+# Workflow:
+# 1. Agent explores codebase and researches request
+# 2. May ask clarifying questions
+# 3. Creates structured plan (3-8 steps)
+# 4. You review and approve plan
+# 5. Agent executes approved plan
+
+# File modifications are blocked during planning phase
+```
+
+## 💾 Session Management
+
+Sessions preserve conversation history and context:
+
+```bash
+# List available sessions
+/sessions
+
+# Restore a specific session
+/use session-id-here
+
+# Save current session
+/save
+
+# Start fresh
+/new
+```
+
+Sessions are stored in `.goatchain/sessions/` (gitignored).
+
+## 🔍 Web Search Integration
+
+Enable web search for current information:
+
+```bash
+# Set web search API key
+/web-search-key your-serper-api-key
+
+# Or set environment variable
+export SERPER_API_KEY=your-key
+
+# Web search will be available for weather, news, and current events
+```
+
+## 🖼️ Image Support
+
+Attach images to conversations for analysis:
+
+```bash
+# The agent can analyze images you attach
+# Supported formats: PNG, JPG, JPEG
+```
+
+## 🚀 Advanced Usage
+
+### Command Line Arguments
+
+```bash
+# Set API key via command line
+goatchain --api-key sk-...
+
+# Specify model
+goatchain --model gpt-4o
+
+# Set custom base URL
+goatchain --base-url https://api.openai.com/v1
+
+# Configure request parameters
+goatchain --max-tokens 2000 --temperature 0.7
+```
+
+### Integration with Projects
+
+```bash
+# Run in specific directory
+cd /path/to/your/project
+goatchain
+
+# The agent will automatically detect and analyze your codebase
+```
+
+### Environment-Specific Configuration
+
+```bash
+# Development environment
+export GOATCHAIN_PLAN_MODE=1
+export GOATCHAIN_MODEL=gpt-4o
+
+# Production-like environment (more conservative)
+export GOATCHAIN_PLAN_MODE=0
+export GOATCHAIN_MODEL=gpt-3.5-turbo
+```
+
+## 🛠️ Development
+
+### Building from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/zjywill/GoatChain.git
+cd GoatChain/packages/cli
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Test the CLI
+npm run smoke
+```
+
+### Project Structure
+
+```
+packages/cli/
+├── src/
+│   ├── index.ts          # Main CLI entry point
+│   ├── args.ts           # Command line argument parsing
+│   ├── sdk.ts            # GoatChain SDK integration
+│   ├── repl.ts           # Interactive REPL implementation
+│   ├── turn.ts           # Turn processing logic
+│   └── tools/            # Built-in tool implementations
+├── dist/                 # Built output
+└── package.json
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**"API key not found"**
+```bash
+# Set OpenAI API key
+export OPENAI_API_KEY=your-key
+```
+
+**"Model not available"**
+```bash
+# Switch to available model
+/model gpt-3.5-turbo
+```
+
+**Web search not working**
+```bash
+# Set Serper API key
+/web-search-key your-key
+```
+
+**File operations failing**
+- Check file permissions
+- Ensure files exist and are accessible
+- Verify path correctness
+
+### Debug Mode
+
+Enable verbose logging:
+```bash
+export DEBUG=goatchain:*
+goatchain
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the main [GoatChain repository](https://github.com/zjywill/GoatChain) for contribution guidelines.
+
+## 📄 License
+
+MIT © [Simon He](https://github.com/Simon-He95)
+
+---
+
+**Need help?** Type `/help` in the CLI or open an issue on GitHub.

package/dist/args-B4NUWmzz.js

@@ -0,0 +1,2 @@
+import{Command as e,InvalidArgumentError as t}from"commander";function n(e){let t=String(e??``).trim().toLowerCase().replace(/[-\s]+/g,`_`);return t===`read`||t===`readonly`||t===`read_only`?`read_only`:t===`agent`||t===`default`?`agent`:t===`full`||t===`full_access`||t===`agent_full`||t===`agent_full_access`?`full_access`:`read_only`}function r(e){return e===`read_only`?`Read Only`:e===`agent`?`Agent (current)`:`Agent (full access)`}function i(e){return{strategy:`high_risk`,autoApprove:e.envAutoApprove===`1`||e.envAutoApprove===!0||e.mode!==`read_only`}}function a(e){return{allowOutsideWorkspace:e===`full_access`,allowNetwork:e===`full_access`||e===`read_only`}}function o(){return[``,`Interactive slash commands:`,`  /help                     Show help`,`  /clear                    Clear pending attachments`,`  /approvals                Select approval mode (interactive)`,`  /model [id]               Show/set model id`,`  /workspace                Switch workspace root (interactive)`,`  /files                    Attach file(s) (interactive)`,`  /images                   Attach image(s) (interactive)`,`  /settings                 Base URL / API key / tokens`,`  /config [--json]          Print full config (secrets redacted)`,`  /output                   Output & UX options`,`  /agent                    Switch to agent mode (normal operation)`,`  /plan                     Switch to plan mode (read-only planning with TodoWrite)`,`  /diag                     Show last turn stop reason + tool calls`,`  /diagnostics              Alias for /diag`,`  /edit                     Compose a message in $EDITOR`,`  /multiline                Start multiline input (.send/.cancel)`,`  /set <k> <v>              Set request param (maxTokens/temperature/topP/...)`,`  /unset <k>                Clear request param`,`  /params                   Show current request params`,`  /base-url <url>           Set base URL (recreates client if needed)`,`  /api-key <key>            Set API key for this process (not printed)`,`  /web-search-key <key>     Set Serper API key for WebSearch tool (not printed)`,`  /tools                    List enabled tools`,`  /mcp [subcmd]             MCP servers (connect/disconnect/tools)`,`  /sessions                 List/pick/delete sessions`,`  /use <sessionId>          Switch session (restore history)`,`  /rm <sessionId...>        Delete session(s)`,`  /save                     Save current session/config`,`  /status                   Show current session/model info`,`  /new                      Start a new conversation (clears history)`,`  /compact                  Manually compress context (generate summary)`,`  /exit                     Exit`,``,`Mentions:`,`  @<query>                  Search workspace files/dirs (Enter inserts @path)`,``,`Keybindings:`,`  (Type @ or / to show suggestions; filters as you type)`,`  Tab                       Fill the selected suggestion`,`  ↑/↓                       Select a suggestion`,`  Enter                     Run /command, or insert @workspace path selection`,`  PgUp/PgDn/Home/End         Scroll fullscreen log`,`  Ctrl+K                    Open command palette`,`  Ctrl+O                    Manage attachments`,`  Ctrl+G                    Clear attachments`,``,`UI:`,`  GOATCHAIN_UI=inline       Disable fullscreen UI`,`  GOATCHAIN_UI=legacy       Disable interactive UI`,`  GOATCHAIN_UI=full         Force fullscreen UI`,`  GOATCHAIN_THEME=dark      Dark terminal theme (default)`,`  GOATCHAIN_THEME=light     Light terminal theme`,`  GOATCHAIN_ANIMATE=0       Disable splash animation`,``,`Approvals:`,`  GOATCHAIN_APPROVAL_MODE=read_only|agent|full_access`,`  (You can also change this in-app via /approvals)`,``,`Image attachments:`,`  (Also configurable via .goatchain/config.json -> ui.attachImages.*)`,`  GOATCHAIN_ATTACH_IMAGES_NOTE_TEMPLATE=<text>   Template supports {{items}}/{{count}}/{{json}}`,`  GOATCHAIN_ATTACH_IMAGES_NOTE_POSITION=start|before_images|after_images|before_text|after_text|end`,`  GOATCHAIN_ATTACH_IMAGES_IMAGES_POSITION=start|before_text|after_text|end`,`  GOATCHAIN_ATTACH_IMAGES_DATA_URL_MODE=none|prefix|full`,`  GOATCHAIN_ATTACH_IMAGES_MAX_DATA_URL_CHARS=8000`,``].join(`
+`)}function s(e){return n=>{let r=Number(n);if(!Number.isFinite(r))throw new t(`Invalid ${e}: ${n}`);return r}}function c(e){return n=>{let r=Number.parseInt(n,10);if(!Number.isFinite(r))throw new t(`Invalid ${e}: ${n}`);return r}}function l(t){return new e().name(`goatchain`).description(`A tiny interactive chat CLI built on agent-loop`).argument(`[prompt...]`,`one-shot prompt (omit to start interactive mode)`).option(`-k, --api-key <key>`,`OpenAI API key (or set OPENAI_API_KEY)`).option(`-m, --model <id>`,`Default model id (OpenAI)`).option(`--system <prompt>`,`System prompt`).option(`--base-url <url>`,`Override OpenAI base URL (proxy)`).option(`--serper-api-key <key>`,`Serper API key (enables WebSearch tool)`).option(`--web-search-api-key <key>`,`Alias for --serper-api-key`).option(`--serper-api-endpoint <url>`,`Serper API endpoint (WebSearch tool)`).option(`--web-search-api-endpoint <url>`,`Alias for --serper-api-endpoint`).option(`--serper-num-results <n>`,`Serper number of results (WebSearch tool)`,c(`serper-num-results`)).option(`--web-search-num-results <n>`,`Alias for --serper-num-results`,c(`web-search-num-results`)).option(`--max-tokens <n>`,`Max completion tokens`,c(`max-tokens`)).option(`--temperature <n>`,`Temperature (0-2)`,s(`temperature`)).option(`--top-p <n>`,`Top-p (0-1)`,s(`top-p`)).option(`--presence-penalty <n>`,`Presence penalty (-2..2)`,s(`presence-penalty`)).option(`--frequency-penalty <n>`,`Frequency penalty (-2..2)`,s(`frequency-penalty`)).option(`--seed <n>`,`Random seed`,c(`seed`)).option(`--timeout-ms <n>`,`Request timeout in ms`,c(`timeout-ms`)).option(`--session <id>`,`Use a saved session id (optional)`).version(t,`-v, --version`,`Show version`).helpOption(`-h, --help`,`Show help`).showHelpAfterError().showSuggestionAfterError().addHelpText(`after`,o())}function u(e,t){let n=l(t);n.parse(e,{from:`user`});let r=n.opts(),i=Array.isArray(n.args)?n.args.join(` `).trim():``,a=e=>typeof e==`number`&&Number.isFinite(e)?e:void 0,o=e=>typeof e==`number`&&Number.isFinite(e)?Math.trunc(e):void 0;return{apiKey:typeof r.apiKey==`string`&&r.apiKey.trim()?r.apiKey:void 0,modelId:typeof r.model==`string`&&r.model.trim()?r.model:void 0,system:typeof r.system==`string`&&r.system.trim()?r.system:void 0,baseUrl:typeof r.baseUrl==`string`&&r.baseUrl.trim()?r.baseUrl:void 0,webSearchApiKey:typeof r.webSearchApiKey==`string`&&r.webSearchApiKey.trim()?r.webSearchApiKey:typeof r.serperApiKey==`string`&&r.serperApiKey.trim()?r.serperApiKey:void 0,webSearchApiEndpoint:typeof r.webSearchApiEndpoint==`string`&&r.webSearchApiEndpoint.trim()?r.webSearchApiEndpoint:typeof r.serperApiEndpoint==`string`&&r.serperApiEndpoint.trim()?r.serperApiEndpoint:void 0,webSearchNumResults:typeof r.webSearchNumResults==`number`&&Number.isFinite(r.webSearchNumResults)?Math.trunc(r.webSearchNumResults):o(r.serperNumResults),maxTokens:o(r.maxTokens),temperature:a(r.temperature),topP:a(r.topP),presencePenalty:a(r.presencePenalty),frequencyPenalty:a(r.frequencyPenalty),seed:o(r.seed),timeoutMs:o(r.timeoutMs),sessionId:typeof r.session==`string`&&r.session.trim()?r.session:void 0,prompt:i}}export{a,r as i,o as n,i as o,u as r,n as s,l as t};

package/dist/chunk-B_5Rb6Gi.js

@@ -0,0 +1 @@
+import{createRequire as e}from"node:module";var t=Object.create,n=Object.defineProperty,r=Object.getOwnPropertyDescriptor,i=Object.getOwnPropertyNames,a=Object.getPrototypeOf,o=Object.prototype.hasOwnProperty,s=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports),c=(e,t,a,s)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var c=i(t),l=0,u=c.length,d;l<u;l++)d=c[l],!o.call(e,d)&&d!==a&&n(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(s=r(t,d))||s.enumerable});return e},l=(e,r,i)=>(i=e==null?{}:t(a(e)),c(r||!e||!e.__esModule?n(i,`default`,{value:e,enumerable:!0}):i,e)),u=e(import.meta.url);export{u as n,l as r,s as t};

package/dist/cli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './index.js'
+
+await main(process.argv.slice(2))