grok-cli-acp 0.1.2

package/.grok/ENV_CONFIG_GUIDE.md

@@ -0,0 +1,173 @@
+# .env Configuration Guide for grok-cli
+
+This file documents the recommended `.env` configuration for the grok-cli project.
+
+## Location
+
+Create this file at: `grok-cli/.grok/.env`
+
+## Recommended Configuration
+
+```env
+# =============================================================================
+# GROK-CLI PROJECT CONFIGURATION
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# API Configuration
+# -----------------------------------------------------------------------------
+# Your Grok API key (REQUIRED - get from https://console.x.ai/)
+# GROK_API_KEY=xai-your-key-here
+
+# Default model to use for this project
+GROK_MODEL=grok-code-fast-1
+
+# Temperature setting (0.0 = deterministic, 1.0 = creative)
+GROK_TEMPERATURE=0.7
+
+# Maximum tokens in response
+GROK_MAX_TOKENS=4096
+
+# -----------------------------------------------------------------------------
+# Network Configuration (Starlink Optimized)
+# -----------------------------------------------------------------------------
+# Enable Starlink-specific optimizations
+GROK_STARLINK_OPTIMIZATIONS=true
+
+# Request timeout in seconds
+GROK_TIMEOUT=60
+
+# Maximum retry attempts for failed requests
+GROK_MAX_RETRIES=5
+
+# Base retry delay in milliseconds
+GROK_BASE_RETRY_DELAY=1000
+
+# Maximum retry delay in milliseconds
+GROK_MAX_RETRY_DELAY=30000
+
+# Connection timeout in seconds
+GROK_CONNECT_TIMEOUT=30
+
+# Read timeout in seconds
+GROK_READ_TIMEOUT=60
+
+# Enable network health monitoring
+GROK_HEALTH_MONITORING=true
+
+# -----------------------------------------------------------------------------
+# UI Configuration
+# -----------------------------------------------------------------------------
+# Enable colored output
+GROK_COLORS=true
+
+# Enable Unicode characters in output
+GROK_UNICODE=true
+
+# Enable progress bars
+GROK_PROGRESS_BARS=true
+
+# Enable animations
+GROK_ANIMATIONS=true
+
+# Show tips in interactive mode
+GROK_SHOW_TIPS=true
+
+# -----------------------------------------------------------------------------
+# Security Configuration
+# -----------------------------------------------------------------------------
+# Shell command approval mode: strict, default, or permissive
+GROK_SHELL_APPROVAL_MODE=default
+
+# Enable sandbox for shell commands
+GROK_SHELL_SANDBOX=true
+
+# -----------------------------------------------------------------------------
+# Logging Configuration
+# -----------------------------------------------------------------------------
+# Log level: trace, debug, info, warn, error
+GROK_LOG_LEVEL=info
+
+# Enable session logging
+GROK_SESSION_LOGGING=true
+
+# Log format: json or text
+GROK_LOG_FORMAT=json
+
+# Enable performance metrics
+GROK_PERFORMANCE_METRICS=true
+
+# -----------------------------------------------------------------------------
+# Context Configuration
+# -----------------------------------------------------------------------------
+# Maximum file size to include in context (in bytes)
+GROK_MAX_FILE_SIZE=1048576
+
+# Maximum total context size (in bytes)
+GROK_MAX_CONTEXT_SIZE=10485760
+
+# Enable smart context filtering
+GROK_SMART_CONTEXT_FILTERING=true
+
+# Respect .grokignore files
+GROK_RESPECT_GROKIGNORE=true
+
+# -----------------------------------------------------------------------------
+# Development Settings
+# -----------------------------------------------------------------------------
+# Enable preview features
+GROK_PREVIEW_FEATURES=true
+
+# Enable experimental features
+GROK_EXPERIMENTAL_FEATURES=false
+
+# Enable debug mode
+GROK_DEBUG=false
+
+# Enable verbose output
+GROK_VERBOSE=false
+```
+
+## Notes
+
+1. **API Key**: You must set `GROK_API_KEY` or `X_API_KEY`. For security, consider storing this in your system-wide `~/.grok/.env` instead of the project-level file.
+
+2. **Model Selection**: The `GROK_MODEL=grok-code-fast-1` setting is optimized for coding tasks. Other options:
+   - `grok-3` - Most capable, slower
+   - `grok-code-fast-1` - Fast, optimized for code
+   - `grok-2` - Balanced performance
+
+3. **Starlink Settings**: The network configuration is tuned for Starlink satellite internet with higher timeouts and retry logic to handle connection drops.
+
+4. **Priority Order**: Settings are loaded in this order (later overrides earlier):
+   - Built-in defaults
+   - System config (`~/.grok/.env`)
+   - Project config (`.grok/.env`) ← This file
+   - Environment variables
+   - CLI arguments (highest priority)
+
+## Quick Start
+
+To use this configuration:
+
+1. Copy the recommended settings above
+2. Create `.grok/.env` in your project root
+3. Paste the settings
+4. Uncomment and set `GROK_API_KEY` (or set it system-wide)
+5. Adjust other settings as needed
+
+## Verification
+
+After creating your `.env` file, verify it's being loaded:
+
+```bash
+grok config show
+```
+
+You should see:
+- Configuration: Project (.grok/.env)
+- Model: grok-code-fast-1
+
+## Security Note
+
+**Never commit `.env` files to git!** They're already in `.gitignore`, but be careful when sharing code.

package/.grok/QUICK_REFERENCE.md

@@ -0,0 +1,180 @@
+# Quick Reference: File Access Fixes
+
+## Problem & Solution
+
+**Problem:** grok-cli couldn't access files using relative paths like `./file.txt` or `src/main.rs`
+
+**Solution:** Added path resolution to convert relative paths to absolute before checking security
+
+## What Changed
+
+### Before ❌
+```bash
+cd /home/user/project
+grok query "read src/main.rs"
+# Error: Access denied: Path is not in a trusted directory
+```
+
+### After ✅
+```bash
+cd /home/user/project
+grok query "read src/main.rs"
+# ✅ Works! Resolves to /home/user/project/src/main.rs
+```
+
+## Now Supported
+
+| Path Type | Example | Status |
+|-----------|---------|--------|
+| Relative | `src/main.rs` | ✅ Works |
+| Current Dir | `./README.md` | ✅ Works |
+| Parent Dir | `../config.toml` | ✅ Works |
+| Absolute | `/home/user/project/file.txt` | ✅ Works |
+| Symlinks | `link.txt` → `/other/file.txt` | ✅ Resolves & checks |
+| Outside Workspace | `/etc/passwd` | ❌ Correctly denied |
+
+## Technical Details
+
+### Files Modified
+- `src/acp/security.rs` - Added `resolve_path()` method
+- `src/acp/tools.rs` - Updated all file tools
+- `src/acp/mod.rs` - Enhanced initialization
+
+### Key Changes
+1. **Working directory tracking** - SecurityPolicy stores current working directory
+2. **Path resolution** - Converts relative → absolute before security checks
+3. **Symlink following** - Uses `canonicalize()` to resolve symlinks
+4. **Parent directory support** - Handles `..` components correctly
+
+### Tests Added
+- 9 new security tests covering all path scenarios
+- All existing tests still pass
+- Test coverage for relative paths, symlinks, parent dirs, etc.
+
+## Common Use Cases
+
+### Reading Files in Current Directory
+```bash
+grok query "read README.md"
+grok query "read ./Cargo.toml"
+```
+
+### Reading Files in Subdirectories
+```bash
+grok query "read src/main.rs"
+grok query "read docs/guide.md"
+```
+
+### Accessing Parent Directory
+```bash
+cd src
+grok query "read ../README.md"
+```
+
+### Multiple Operations
+```bash
+grok query "read src/lib.rs and src/main.rs"
+```
+
+## Security
+
+### Still Protected ✅
+- Paths outside trusted directories are blocked
+- No security regressions
+- Deny-by-default policy maintained
+- Symlinks are resolved and checked
+
+### Trust Model
+1. Current directory is trusted by default
+2. Paths must resolve within trusted directories
+3. Symlinks are followed and destination is checked
+4. Relative paths work within trusted scope
+
+## Configuration
+
+### Model Selection
+Create `.grok/.env` in your project:
+```env
+GROK_MODEL=grok-code-fast-1
+```
+
+Or system-wide at `~/.grok/.env`
+
+### API Key (Required)
+```env
+GROK_API_KEY=xai-your-key-here
+```
+
+Store in system-wide `~/.grok/.env` for security
+
+## Verification
+
+Test that it works:
+```bash
+# Navigate to your project
+cd /path/to/your/project
+
+# Test relative path
+grok query "list files in current directory"
+
+# Test file reading
+grok query "read README.md"
+
+# Test subdirectory
+grok query "read src/main.rs"
+```
+
+## ACP Protocol
+
+The fix applies to:
+- ✅ Direct CLI usage
+- ✅ ACP protocol (Zed editor integration)
+- ✅ Interactive chat mode
+- ✅ All file operation tools
+
+## Documentation
+
+For detailed information:
+- `.grok/FILE_ACCESS_ANALYSIS.md` - Technical deep dive
+- `.grok/FILE_ACCESS_FIX_SUMMARY.md` - Complete summary
+- `.grok/ENV_CONFIG_GUIDE.md` - Configuration guide
+
+## Troubleshooting
+
+### Still getting access denied?
+1. Check you're in the project directory
+2. Verify path is correct: `ls -la <path>`
+3. Check if file exists
+4. Try absolute path to confirm it's a path resolution issue
+
+### Path not found?
+1. Verify working directory: `pwd`
+2. Check file exists: `ls <file>`
+3. Use tab completion to verify path
+4. Try `./<file>` prefix
+
+### Outside workspace?
+This is correct behavior - files outside your project are intentionally blocked for security.
+
+## Quick Test
+
+```bash
+# Create test file
+echo "Hello from grok-cli" > test.txt
+
+# Test reading it
+grok query "read test.txt"
+
+# Should show: "Hello from grok-cli"
+```
+
+## Summary
+
+✅ Relative paths now work correctly
+✅ Symlinks are resolved properly  
+✅ Parent directory access works
+✅ Security is maintained
+✅ All tests pass
+✅ Ready for production use
+
+The fix aligns grok-cli with gemini-cli's path handling approach while maintaining security.

package/.grok/README.md

@@ -0,0 +1,104 @@
+# .grok Directory Documentation
+
+This directory contains documentation for the grok-cli project's recent fixes and configuration.
+
+## 📚 Documentation Files
+
+### Quick Start
+- **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Quick reference card for file access fixes and common commands
+
+### Testing & Verification
+- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Step-by-step testing guide for verifying file access and Zed integration fixes
+
+### Configuration
+- **[ENV_CONFIG_GUIDE.md](ENV_CONFIG_GUIDE.md)** - Complete guide for `.env` configuration options
+
+### Technical Summary
+- **[COMPLETE_FIX_SUMMARY.md](COMPLETE_FIX_SUMMARY.md)** - Comprehensive summary of all fixes (file access & Zed integration)
+
+## 🎯 What Was Fixed
+
+### File Access with Relative Paths
+✅ CLI can now access files using relative paths (`src/main.rs`, `./README.md`, `../file.txt`)
+✅ Symlinks are properly resolved
+✅ Parent directory access works
+✅ Security is maintained
+
+### Zed Editor Integration
+✅ Workspace context is extracted from ACP session initialization
+✅ grok-cli properly trusts the workspace directory
+✅ File operations work within the project context
+
+## 🚀 Getting Started
+
+1. **Configure your model:**
+   ```bash
+   echo GROK_MODEL=grok-code-fast-1 > .env
+   ```
+
+2. **Test file access:**
+   ```bash
+   grok query "read README.md"
+   ```
+
+3. **Configure Zed:**
+   See [ENV_CONFIG_GUIDE.md](ENV_CONFIG_GUIDE.md) and `docs/ZED_INTEGRATION.md`
+
+4. **Run tests:**
+   Follow [TESTING_GUIDE.md](TESTING_GUIDE.md)
+
+## 📖 Which Doc Should I Read?
+
+- **Just want to get started?** → [QUICK_REFERENCE.md](QUICK_REFERENCE.md)
+- **Setting up configuration?** → [ENV_CONFIG_GUIDE.md](ENV_CONFIG_GUIDE.md)
+- **Testing the fixes?** → [TESTING_GUIDE.md](TESTING_GUIDE.md)
+- **Want full technical details?** → [COMPLETE_FIX_SUMMARY.md](COMPLETE_FIX_SUMMARY.md)
+
+## 📝 Configuration Priority
+
+Settings are loaded in this order (later overrides earlier):
+1. Built-in defaults
+2. System config (`~/.grok/.env`)
+3. Project config (`.grok/.env`) ← This directory
+4. Environment variables
+5. CLI arguments (highest priority)
+
+## ✅ Verification
+
+```bash
+# Check configuration
+grok config show
+
+# Should show:
+# Model: grok-code-fast-1
+# Configuration: Project (.grok/.env) or Hierarchical
+```
+
+## 🔒 Security Note
+
+Never commit `.env` files with API keys to git! They're in `.gitignore` by default.
+
+Store API keys in:
+- System-wide: `~/.grok/.env`
+- Project: `.grok/.env` (gitignored)
+- Environment: `export GROK_API_KEY=xai-...`
+
+## 📦 What's in .grok/.env?
+
+Example minimal configuration:
+```env
+# Model selection
+GROK_MODEL=grok-code-fast-1
+
+# API key (optional - better in ~/.grok/.env)
+# GROK_API_KEY=xai-your-key-here
+```
+
+See [ENV_CONFIG_GUIDE.md](ENV_CONFIG_GUIDE.md) for all available options.
+
+---
+
+**Last Updated:** 2025
+**Status:** Ready for Production
+**Author:** John McConnell (john.microtech@gmail.com)
+**Repository:** https://github.com/microtech/grok-cli