codelantern-agent-cli 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Code Lantern CLI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,364 @@
-# Temporary Holding Version
+# 🏮 Code Lantern CLI (`codelantern-agent-cli`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Personal AI coding assistant for the terminal powered directly by the Google Gemini API.**  
+> Cross-platform terminal command: **`lantern`**  
+> Default model: **`gemini-3.8-flash`**
+
+Code Lantern CLI is an autonomous terminal coding assistant designed to help you inspect, build, edit, and troubleshoot codebases directly from your shell. It calls Google's official Gemini API directly using `@google/genai`—it does not depend on Antigravity, Codex, or Gemini CLI being installed.
+
+---
+
+## ⚡ Key Highlights
+
+- **Direct Gemini Connection**: Native integration with Google's `@google/genai` TypeScript SDK using `gemini-3.8-flash` by default.
+- **Cross-Platform Architecture**: Engineered to run consistently on **macOS** (both Apple Silicon M-series and Intel x86_64) and **Windows** (Command Prompt, PowerShell, Windows Terminal), as well as Linux.
+- **Safe Mode with Diff Previews**: Inspects before modifying. Shows colored unified patch diffs (`+ added`, `- removed`) and command previews before requesting interactive approval.
+- **Deliberate YOLO Mode (`--yolo`)**: Auto-approves operations when explicitly requested, while maintaining strict workspace containment and secret shielding boundaries.
+- **Read-Only Plan Mode (`lantern plan`)**: Formulates comprehensive, step-by-step implementation plans without mutating files or running shell commands.
+- **Piped Unix / PowerShell Workflows**: Pipe test failures, git diffs, or files into Lantern:
+  - macOS/Linux: `npm test 2>&1 | lantern "diagnose error"`
+  - Windows PowerShell: `Get-Content error.log | lantern "how do I fix this?"`
+- **Context Awareness**: Respects `.gitignore`, ignores vendor and build trees (`node_modules`, `dist`, `.git`), detects `LANTERN.md` / `GEMINI.md` project rules, and renders ASCII file trees.
+- **Security Sandbox**: Rejects path traversal (`../../`) and symlink escapes. Masks `.env` files, private keys, and scrubs API tokens from transcripts and logs.
+- **Model Context Protocol (MCP)**: Native stdio client integration via `@modelcontextprotocol/sdk` to dynamically expose external database, API, and tool servers to Gemini.
+- **Rich Terminal Experience**: Streaming responses, syntax-highlighted markdown, animated spinners, multiline prompt input (`\`), command history, and slash commands.
+
+---
+
+## 💻 System Prerequisites
+
+| Requirement | Supported Version / Details |
+| :--- | :--- |
+| **Node.js** | `>= 18.0.0` (Node 20 or Node 22 LTS recommended) |
+| **npm** | `>= 9.0.0` |
+| **Operating Systems** | macOS 12+ (Apple Silicon `arm64` & Intel `x64`), Windows 10/11 (PowerShell & CMD), Linux |
+| **API Key** | Google Gemini API Key ([Get one free at Google AI Studio](https://aistudio.google.com/app/apikey)) |
+
+---
+
+## 📦 Installation
+
+### Option A: Local Development Installation
+
+Clone or open the project folder in your terminal:
+
+```bash
+cd "my own cli"
+
+# 1. Install dependencies
+npm install
+
+# 2. Build the executable
+npm run build
+
+# 3. Link the 'lantern' command globally
+npm link
+```
+
+Verify your installation:
+
+```bash
+lantern --version
+# Output: 1.0.0
+```
+
+### Option B: Global Installation after Publishing to npm
+
+Once published to npm under `codelantern-agent-cli`:
+
+#### On macOS / Linux:
+```bash
+npm install -g codelantern-agent-cli
+lantern --version
+```
+
+#### On Windows (PowerShell or Command Prompt):
+```powershell
+npm install -g codelantern-agent-cli
+lantern --version
+```
+*npm automatically generates `lantern.cmd` and `lantern.ps1` wrappers on Windows, placing them in your npm global PATH.*
+
+---
+
+## 🔑 Gemini API Key Configuration
+
+Code Lantern CLI reads your API key from the standard environment variable `GEMINI_API_KEY`.
+
+### macOS / Linux (`zsh` or `bash`)
+
+Add to `~/.zshrc` or `~/.bashrc`:
+```bash
+export GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
+```
+Or set it for the current session:
+```bash
+export GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
+```
+
+### Windows (PowerShell)
+
+For the current session:
+```powershell
+$env:GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
+```
+
+Persistently for user environment:
+```powershell
+[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'AIzaSyYourActualGeminiApiKeyHere', 'User')
+```
+
+### Windows (Command Prompt `cmd.exe`)
+
+For current session:
+```cmd
+set GEMINI_API_KEY=AIzaSyYourActualGeminiApiKeyHere
+```
+
+Persistently:
+```cmd
+setx GEMINI_API_KEY "AIzaSyYourActualGeminiApiKeyHere"
+```
+
+> **Security Note:** Code Lantern never prints, commits, logs, or saves your raw API key in session transcripts.
+
+---
+
+## 🩺 Diagnostics (`lantern doctor`)
+
+Run `lantern doctor` at any time to verify your environment, API key validity, git availability, and MCP servers:
+
+```bash
+lantern doctor
+```
+
+Example output:
+```text
+🏮 Code Lantern Doctor — Diagnostics
+──────────────────────────────────────────────────────────────────────────────
+✓ Platform / OS:          macOS (Apple Silicon)
+✓ Node.js Runtime:        v26.12.1 (compatible)
+✓ GEMINI_API_KEY:         Found (AIza...W9q0)
+✓ Gemini API Auth:        Verified (contacted 'gemini-3.8-flash')
+✓ Git CLI:                Available (git version 2.54.0)
+✓ Config File:            ~/.codelantern/config.json (Model: gemini-3.8-flash)
+✓ Session Storage:        ~/.codelantern/sessions (0 stored session(s))
+ℹ MCP Configuration:      No external MCP servers configured (optional)
+✓ Project Instructions:   Found (LANTERN.md) in /workspace
+──────────────────────────────────────────────────────────────────────────────
+✨ All systems healthy! Code Lantern CLI is ready to assist.
+```
+
+---
+
+## 📖 Command Reference
+
+| Command | Action |
+| :--- | :--- |
+| **`lantern`** | Launch the interactive conversational REPL |
+| **`lantern ask "<question>"`** | One-shot prompt execution with streaming answer |
+| **`lantern plan "<task>"`** | Read-only inspection & implementation plan |
+| **`lantern resume [sessionId]`** | Resume the most recent or specified session |
+| **`lantern sessions`** | List saved local sessions |
+| **`lantern sessions --export <id>`** | Export session transcript to Markdown or JSON |
+| **`lantern sessions --delete <id>`** | Delete a saved session by ID |
+| **`lantern config`** | View active configuration |
+| **`lantern config set <key> <val>`** | Update a configuration setting |
+| **`lantern doctor`** | Diagnose environment, credentials, and connectivity |
+| **`lantern mcp`** | Manage configured MCP servers (`list`, `add`, `remove`, `test`) |
+| **`lantern --help`** | View all CLI flags and options |
+| **`lantern --version`** | Output version string |
+
+### Global Options
+
+- **`-m, --model <id>`**: Override model ID (default: `gemini-3.8-flash`).
+- **`-C, --cwd <path>`**: Set workspace directory for agent operations.
+- **`-s, --session <id>`**: Use or resume a specific session ID.
+- **`-a, --attach <files...>`**: Attach text files, images (`.png`, `.jpg`, `.webp`), or PDFs.
+- **`--yolo`**: Skip interactive confirmation prompts for file edits and shell commands.
+- **`--json`**: Output results formatted as JSON.
+
+---
+
+## 💡 Usage Examples
+
+### 1. Interactive Shell
+
+```bash
+lantern
+```
+
+Inside the interactive REPL:
+- Type your question or task naturally.
+- Use `\` at the end of a line for multiline continuation.
+- Enclose multiline code blocks inside `""" ... """`.
+- Press `Up`/`Down` arrows to navigate previous prompt history.
+- Available slash commands:
+  - `/help` — List available commands and tools.
+  - `/clear` — Clear terminal screen.
+  - `/status` — View workspace, model, token count, and active session ID.
+  - `/model [id]` — Switch model on the fly (e.g. `/model gemini-3.8-flash`).
+  - `/plan [on|off]` — Toggle read-only plan mode.
+  - `/yolo [on|off]` — Toggle YOLO mode for the session.
+  - `/sessions` — List saved sessions.
+  - `/history` — Print recent conversation turns.
+  - `/export [md|json]` — Export current session transcript.
+  - `/exit` or `/quit` — Save session and exit.
+
+### 2. One-Shot Question with File Attachment
+
+```bash
+lantern ask "Refactor this component to use React hooks" --attach src/components/UserProfile.tsx
+```
+
+### 3. Read-Only Planning Mode
+
+```bash
+lantern plan "Design an authentication system using JWT tokens with refresh cookies"
+```
+
+### 4. Piped Standard Input
+
+```bash
+# macOS / Linux
+cat build.log | lantern "Summarize the root cause of these compiler errors"
+
+# Windows PowerShell
+Get-Content build.log | lantern "Summarize the root cause of these compiler errors"
+```
+
+---
+
+## 🛡️ Approval & YOLO Modes
+
+Code Lantern defaults to **Safe Mode**.
+
+### Safe Mode (Default)
+
+1. **Before Editing Files**: Displays an ANSI color-coded patch diff showing exact removals in red and additions in green:
+   ```text
+   Approve this action? [y/N / (a)ll-yolo]:
+   ```
+2. **Before Creating Files**: Displays a line-numbered preview of the file.
+3. **Before Executing Shell Commands**: Displays the exact command and working directory.
+
+### YOLO Mode (`--yolo`)
+
+Run Lantern with `--yolo` or enter `yolo` / `a` at an approval prompt to auto-approve safe modifications for that execution:
+```bash
+lantern --yolo ask "Run npm test and fix failing assertions"
+```
+
+### Unconditional Safety Invariants
+
+- **Strict Workspace Containment**: Lantern cannot read, edit, or execute outside your workspace directory. Path traversal attempts (`../../`) and symlink escapes are rejected.
+- **Secret Shielding**: `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, and credential JSON files are blocked from reading or being sent to Gemini.
+- **Destructive Command Firewall**: Destructive system commands (e.g. `rm -rf /`, `mkfs`, Windows `format c:`, `del /s /q c:\*`) are strictly blocked across all platforms.
+- **Token Redaction**: Any API keys detected in text are automatically masked before saving or displaying.
+
+---
+
+## 🔌 Model Context Protocol (MCP)
+
+Connect external tool servers using the official Model Context Protocol stdio transport:
+
+```bash
+# Add SQLite database MCP server
+lantern mcp add sqlite npx -y @modelcontextprotocol/server-sqlite ./data.db
+
+# Test server connection and inspect exposed tools
+lantern mcp test sqlite
+
+# List configured MCP servers
+lantern mcp list
+
+# Disable or enable a server
+lantern mcp disable sqlite
+lantern mcp enable sqlite
+
+# Remove a server
+lantern mcp remove sqlite
+```
+
+---
+
+## ⚙️ Configuration & Project Instructions
+
+Configurations are persisted in `~/.codelantern/config.json` (or `%USERPROFILE%\.codelantern\config.json` on Windows):
+
+```bash
+# View configuration
+lantern config
+
+# Update settings
+lantern config set defaultModel gemini-3.8-flash
+lantern config set maxSteps 30
+lantern config set temperature 0.2
+```
+
+### Project Instructions (`LANTERN.md`)
+
+Place a `LANTERN.md` (or `GEMINI.md`) file in your project root to provide persistent instructions to Code Lantern:
+
+```markdown
+# Project Instructions
+- Codebase language: TypeScript (NodeNext modules)
+- Run `npm test` before concluding file edits
+- Keep imports organized alphabetically
+```
+
+---
+
+## 🚀 npm Release Checklist
+
+To publish `codelantern-agent-cli` to npm:
+
+1. **Ensure Tests Pass**:
+   ```bash
+   npm test
+   npm run lint
+   npm run build
+   ```
+2. **Verify Pack Contents**:
+   ```bash
+   npm pack --dry-run
+   ```
+   *Verify that only `dist/`, `README.md`, and `LICENSE` are included. Ensure no `.env`, `.codelantern/`, or test files are listed.*
+3. **Log in to npm**:
+   ```bash
+   npm login
+   ```
+4. **Publish**:
+   ```bash
+   npm publish --access public
+   ```
+
+---
+
+## 🧪 Testing
+
+Run the automated cross-platform test suite:
+
+```bash
+npm test
+```
+
+Run TypeScript compilation check:
+
+```bash
+npm run lint
+```
+
+---
+
+## ⚠️ Known Limitations & Platform Notes
+
+- **Directly Tested Platform**: Built and fully tested on **macOS (Apple Silicon arm64, Node v26)** with all 23 automated unit and integration tests passing.
+- **Windows Platform**: Designed with standard Node.js APIs (`path.normalize`, `path.sep`, `windowsHide`, CRLF normalization, command guard patterns). Physical hardware testing on Windows 10/11 is recommended upon clone or CI run.
+- **Terminal Colors**: A modern terminal emulator with ANSI color support (macOS Terminal, iTerm2, Windows Terminal, VS Code Integrated Terminal) is recommended.
+
+---
+
+## 📄 License
+
+MIT © Code Lantern CLI Contributors