codelantern-agent-cli 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +167 -216
  2. package/dist/{chunk-Y3PEOLTZ.js → chunk-PELESOCI.js} +2365 -571
  3. package/dist/chunk-PELESOCI.js.map +1 -0
  4. package/dist/cli.js +678 -82
  5. package/dist/cli.js.map +1 -1
  6. package/dist/index.d.ts +285 -23
  7. package/dist/index.js +46 -7
  8. package/package.json +2 -2
  9. package/dist/chunk-Y3PEOLTZ.js.map +0 -1
package/README.md CHANGED
@@ -1,27 +1,37 @@
1
1
  # 🏮 Code Lantern CLI (`codelantern-agent-cli`)
2
2
 
3
- > **Personal AI coding assistant for the terminal powered directly by the Google Gemini API.**
4
- > Cross-platform terminal command: **`lantern`**
5
- > Default model: **`gemini-3.8-flash`**
3
+ > **Personal AI coding assistant for the terminal with multi-provider intelligence, portable skills, and ironclad safety.**
4
+ > Terminal command: **`lantern`**
5
+ > Published version: **`1.0.1`**
6
+ > Default model: **`gemini-3.8-flash`** (Google Gemini)
6
7
 
7
- 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.
8
+ Code Lantern CLI is a resilient, autonomous terminal coding assistant designed to help you inspect, build, edit, and troubleshoot codebases directly from your shell. It connects directly to your chosen AI providers—Google Gemini, OpenAI, Anthropic Claude, OpenRouter, or custom OpenAI-compatible endpoints—with zero third-party agent dependencies.
8
9
 
9
10
  ---
10
11
 
11
- ## ⚡ Key Highlights
12
-
13
- - **Direct Gemini Connection**: Native integration with Google's `@google/genai` TypeScript SDK using `gemini-3.8-flash` by default.
14
- - **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.
15
- - **Safe Mode with Diff Previews**: Inspects before modifying. Shows colored unified patch diffs (`+ added`, `- removed`) and command previews before requesting interactive approval.
16
- - **Deliberate YOLO Mode (`--yolo`)**: Auto-approves operations when explicitly requested, while maintaining strict workspace containment and secret shielding boundaries.
17
- - **Read-Only Plan Mode (`lantern plan`)**: Formulates comprehensive, step-by-step implementation plans without mutating files or running shell commands.
18
- - **Piped Unix / PowerShell Workflows**: Pipe test failures, git diffs, or files into Lantern:
19
- - macOS/Linux: `npm test 2>&1 | lantern "diagnose error"`
20
- - Windows PowerShell: `Get-Content error.log | lantern "how do I fix this?"`
21
- - **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.
22
- - **Security Sandbox**: Rejects path traversal (`../../`) and symlink escapes. Masks `.env` files, private keys, and scrubs API tokens from transcripts and logs.
23
- - **Model Context Protocol (MCP)**: Native stdio client integration via `@modelcontextprotocol/sdk` to dynamically expose external database, API, and tool servers to Gemini.
24
- - **Rich Terminal Experience**: Streaming responses, syntax-highlighted markdown, animated spinners, multiline prompt input (`\`), command history, and slash commands.
12
+ ## ⚡ What's New in v1.0.1
13
+
14
+ - 🚀 **Fix "Step 1: thinking" Hang & Slowness**:
15
+ - **Bounded Request & First-Token Timeouts (`TTFT`)**: Strict timeouts prevent indefinite network hangs with configurable `--timeout` (default: 60s) and `--first-token-timeout` (default: 30s).
16
+ - **Immediate Unbuffered Streaming**: Response tokens stream directly to stdout as they arrive.
17
+ - **Real-Time Spinner Stages**: Spinner transitions transparently across `Connecting...`, `Waiting for first token...`, `Receiving response...`, and `Executing tool [name]...`. Stale thinking states are completely eliminated.
18
+ - **Instant Cancellation (Ctrl+C)**: Pressing Ctrl+C aborts in-flight fetch and streaming requests instantly via linked `AbortController`, safely returning control to the prompt.
19
+ - **Safe Backoff Retries**: Transient HTTP failures (429/503) retry with small, capped backoff. Non-idempotent mutating tools (file edits, bash execution) are never duplicated.
20
+ - **Context Efficiency & Pruning**: Tool outputs exceeding 15KB are capped in session context, preventing memory bloat and preserving fast response times.
21
+ - **Timing Diagnostics**: Pass `--timing` or use `/timing` to display live latency benchmarks for connection, first-token arrival, tool steps, and total turn duration.
22
+ - 🌐 **Multi-Provider & Dynamic Model Architecture**:
23
+ - **Google Gemini**: Native official `@google/genai` SDK with `gemini-3.8-flash` as default.
24
+ - **OpenAI**: Native SSE streaming adapter supporting `gpt-4o`, `gpt-4o-mini`, `o1`, `o3-mini`, with function/tool calling.
25
+ - **Anthropic Claude**: Native SSE streaming adapter supporting `claude-3-7-sonnet`, `claude-3-5-sonnet`, and `claude-3-5-haiku`.
26
+ - **OpenRouter**: Access over 400 models dynamically via `https://openrouter.ai/api/v1` with dynamic catalog discovery.
27
+ - **Custom OpenAI-Compatible Providers**: Configure custom endpoints (Ollama, vLLM, DeepSeek, LocalAI) via base URL, API key, and model ID.
28
+ - **Secure AES-256-GCM Credential Vault**: Store provider API keys locally encrypted in `~/.codelantern/credentials.json` with machine-derived keys, or supply via standard environment variables (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`).
29
+ - **Management Commands**: `lantern providers`, `lantern models`, `lantern keys`, and `/provider`, `/model` slash commands.
30
+ - 🧩 **Portable Skills System (`SKILL.md`)**:
31
+ - Import, enable, and use skills defined in portable `SKILL.md` format (YAML frontmatter + markdown instructions + references).
32
+ - Discovered automatically from user directory (`~/.codelantern/skills/`) and project workspaces (`.codelantern/skills/`).
33
+ - Install skills easily via local path or Git: `lantern skills add <path-or-git-url>`.
34
+ - Transparent, non-intrusive keyword/intent matching automatically injects relevant domain instructions into system prompts without arbitrary script execution.
25
35
 
26
36
  ---
27
37
 
@@ -32,7 +42,7 @@ Code Lantern CLI is an autonomous terminal coding assistant designed to help you
32
42
  | **Node.js** | `>= 18.0.0` (Node 20 or Node 22 LTS recommended) |
33
43
  | **npm** | `>= 9.0.0` |
34
44
  | **Operating Systems** | macOS 12+ (Apple Silicon `arm64` & Intel `x64`), Windows 10/11 (PowerShell & CMD), Linux |
35
- | **API Key** | Google Gemini API Key ([Get one free at Google AI Studio](https://aistudio.google.com/app/apikey)) |
45
+ | **API Keys** | Any of: `GEMINI_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, or custom endpoint |
36
46
 
37
47
  ---
38
48
 
@@ -40,93 +50,144 @@ Code Lantern CLI is an autonomous terminal coding assistant designed to help you
40
50
 
41
51
  ### Option A: Local Development Installation
42
52
 
43
- Clone or open the project folder in your terminal:
44
-
45
53
  ```bash
46
54
  cd "my own cli"
47
55
 
48
56
  # 1. Install dependencies
49
57
  npm install
50
58
 
51
- # 2. Build the executable
59
+ # 2. Build the distribution bundle
52
60
  npm run build
53
61
 
54
- # 3. Link the 'lantern' command globally
62
+ # 3. Link globally for immediate use
55
63
  npm link
56
64
  ```
57
65
 
58
66
  Verify your installation:
59
-
60
67
  ```bash
61
68
  lantern --version
62
- # Output: 1.0.0
69
+ # Output: 1.0.1
63
70
  ```
64
71
 
65
- ### Option B: Global Installation after Publishing to npm
72
+ ### Option B: Global Installation from npm
66
73
 
67
- Once published to npm under `codelantern-agent-cli`:
74
+ Once published under `codelantern-agent-cli`:
68
75
 
69
- #### On macOS / Linux:
76
+ #### macOS & Linux:
70
77
  ```bash
71
78
  npm install -g codelantern-agent-cli
72
79
  lantern --version
73
80
  ```
74
81
 
75
- #### On Windows (PowerShell or Command Prompt):
82
+ #### Windows (PowerShell or Command Prompt):
76
83
  ```powershell
77
84
  npm install -g codelantern-agent-cli
78
85
  lantern --version
79
86
  ```
80
- *npm automatically generates `lantern.cmd` and `lantern.ps1` wrappers on Windows, placing them in your npm global PATH.*
87
+ *npm automatically generates `lantern.cmd` and `lantern.ps1` executables on Windows.*
81
88
 
82
89
  ---
83
90
 
84
- ## 🔑 Gemini API Key Configuration
91
+ ## 🔑 Credential & Key Management
85
92
 
86
- Code Lantern CLI reads your API key from the standard environment variable `GEMINI_API_KEY`.
93
+ Code Lantern supports two secure methods for supplying API keys:
87
94
 
88
- ### macOS / Linux (`zsh` or `bash`)
95
+ ### 1. Secure Local Vault (AES-256-GCM)
96
+ Store encrypted keys on your local machine using `lantern keys set`:
97
+ ```bash
98
+ lantern keys set gemini
99
+ lantern keys set openai
100
+ lantern keys set anthropic
101
+ lantern keys set openrouter
102
+ ```
103
+ Keys are encrypted using AES-256-GCM with a machine-unique key derived from your host identity. Keys are never logged, committed, or transmitted except directly to the provider endpoint.
89
104
 
90
- Add to `~/.zshrc` or `~/.bashrc`:
105
+ ### 2. Environment Variables
106
+ Standard environment variables take precedence when present:
91
107
  ```bash
92
- export GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
108
+ export GEMINI_API_KEY="AIzaSy..."
109
+ export OPENAI_API_KEY="sk-proj-..."
110
+ export ANTHROPIC_API_KEY="sk-ant-..."
111
+ export OPENROUTER_API_KEY="sk-or-v1-..."
93
112
  ```
94
- Or set it for the current session:
113
+
114
+ Inspect configured keys safely (masked):
95
115
  ```bash
96
- export GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
116
+ lantern keys list
97
117
  ```
98
118
 
99
- ### Windows (PowerShell)
119
+ ---
120
+
121
+ ## 🌐 Multi-Provider Management
100
122
 
101
- For the current session:
102
- ```powershell
103
- $env:GEMINI_API_KEY="AIzaSyYourActualGeminiApiKeyHere"
104
- ```
123
+ ### Switch Active Provider and Models
124
+ ```bash
125
+ # List all configured providers
126
+ lantern providers list
105
127
 
106
- Persistently for user environment:
107
- ```powershell
108
- [System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'AIzaSyYourActualGeminiApiKeyHere', 'User')
109
- ```
128
+ # Set default provider
129
+ lantern providers set-default openrouter
110
130
 
111
- ### Windows (Command Prompt `cmd.exe`)
131
+ # Test provider connectivity and latency
132
+ lantern providers test openrouter
133
+ lantern providers test gemini
112
134
 
113
- For current session:
114
- ```cmd
115
- set GEMINI_API_KEY=AIzaSyYourActualGeminiApiKeyHere
135
+ # Add a custom local Ollama or vLLM provider
136
+ lantern providers add ollama --base-url http://localhost:11434/v1 --model llama3.2:latest
137
+
138
+ # List available models for active provider
139
+ lantern models list
140
+
141
+ # Query models for a specific provider
142
+ lantern models list -p anthropic
143
+ lantern models list -p openrouter
144
+
145
+ # Set active default model
146
+ lantern models set gemini-3.8-flash
116
147
  ```
117
148
 
118
- Persistently:
119
- ```cmd
120
- setx GEMINI_API_KEY "AIzaSyYourActualGeminiApiKeyHere"
149
+ ---
150
+
151
+ ## 🧩 Portable Skills System (`SKILL.md`)
152
+
153
+ Code Lantern supports domain-specific skills using the standard `SKILL.md` format:
154
+
155
+ ```markdown
156
+ ---
157
+ name: build-your-own-x
158
+ description: Step-by-step architectural patterns for recreating technologies from scratch
159
+ ---
160
+ # Build Your Own X Instructions
161
+ When designing and implementing systems from scratch, follow these patterns...
121
162
  ```
122
163
 
123
- > **Security Note:** Code Lantern never prints, commits, logs, or saves your raw API key in session transcripts.
164
+ ### Managing Skills
165
+ ```bash
166
+ # List installed skills
167
+ lantern skills list
168
+
169
+ # Add a skill from a local folder or markdown file
170
+ lantern skills add ./my-skill
171
+
172
+ # Add a skill directly from a Git repository
173
+ lantern skills add https://github.com/example/coding-skills.git
174
+
175
+ # Inspect skill instructions and reference documents
176
+ lantern skills show build-your-own-x
177
+
178
+ # Enable or disable skills
179
+ lantern skills enable build-your-own-x
180
+ lantern skills disable build-your-own-x
181
+
182
+ # Remove a skill
183
+ lantern skills remove build-your-own-x
184
+ ```
124
185
 
125
186
  ---
126
187
 
127
188
  ## 🩺 Diagnostics (`lantern doctor`)
128
189
 
129
- Run `lantern doctor` at any time to verify your environment, API key validity, git availability, and MCP servers:
190
+ Run `lantern doctor` at any time to verify system health, network connectivity, latency, and keys:
130
191
 
131
192
  ```bash
132
193
  lantern doctor
@@ -138,12 +199,16 @@ Example output:
138
199
  ──────────────────────────────────────────────────────────────────────────────
139
200
  ✓ Platform / OS: macOS (Apple Silicon)
140
201
  ✓ Node.js Runtime: v26.12.1 (compatible)
141
- ✓ GEMINI_API_KEY: Found (AIza...W9q0)
142
- ✓ Gemini API Auth: Verified (contacted 'gemini-3.8-flash')
202
+ ✓ Active Provider: Google Gemini (gemini)
203
+ ✓ Active Model: gemini-3.8-flash
204
+ ✓ API Key (gemini): Configured [env] (AIza...W9q0)
205
+ ✓ Gemini API Auth: Verified (latency: 340ms)
206
+ ✓ Additional Providers: Configured (openrouter, openai)
143
207
  ✓ Git CLI: Available (git version 2.54.0)
144
- ✓ Config File: ~/.codelantern/config.json (Model: gemini-3.8-flash)
145
- ✓ Session Storage: ~/.codelantern/sessions (0 stored session(s))
146
- ℹ MCP Configuration: No external MCP servers configured (optional)
208
+ ✓ Config File: ~/.codelantern/config.json (Timeout: 60000ms, TTFT: 30000ms)
209
+ ✓ Session Storage: ~/.codelantern/sessions (1 stored session(s))
210
+ ✓ Skills: 1 installed (build-your-own-x)
211
+ ℹ MCP Servers: No external MCP servers configured (optional)
147
212
  ✓ Project Instructions: Found (LANTERN.md) in /workspace
148
213
  ──────────────────────────────────────────────────────────────────────────────
149
214
  ✨ All systems healthy! Code Lantern CLI is ready to assist.
@@ -156,206 +221,92 @@ Example output:
156
221
  | Command | Action |
157
222
  | :--- | :--- |
158
223
  | **`lantern`** | Launch the interactive conversational REPL |
159
- | **`lantern ask "<question>"`** | One-shot prompt execution with streaming answer |
160
- | **`lantern plan "<task>"`** | Read-only inspection & implementation plan |
224
+ | **`lantern ask "<question>"`** | One-shot prompt execution with streaming response |
225
+ | **`lantern plan "<task>"`** | Read-only inspection and implementation plan |
161
226
  | **`lantern resume [sessionId]`** | Resume the most recent or specified session |
162
- | **`lantern sessions`** | List saved local sessions |
163
- | **`lantern sessions --export <id>`** | Export session transcript to Markdown or JSON |
164
- | **`lantern sessions --delete <id>`** | Delete a saved session by ID |
165
- | **`lantern config`** | View active configuration |
166
- | **`lantern config set <key> <val>`** | Update a configuration setting |
167
- | **`lantern doctor`** | Diagnose environment, credentials, and connectivity |
168
- | **`lantern mcp`** | Manage configured MCP servers (`list`, `add`, `remove`, `test`) |
227
+ | **`lantern sessions`** | List saved local sessions (`--export <id>`, `--delete <id>`) |
228
+ | **`lantern providers`** | Manage AI providers (`list`, `set-default`, `test`, `add`, `remove`) |
229
+ | **`lantern models`** | List and select models (`list`, `set`, `-p <provider>`, `-r`, `--json`) |
230
+ | **`lantern keys`** | Manage encrypted API keys (`list`, `set`, `remove`) |
231
+ | **`lantern skills`** | Manage portable skills (`list`, `show`, `add`, `enable`, `disable`, `remove`) |
232
+ | **`lantern config`** | View or update configuration (`list`, `get`, `set`) |
233
+ | **`lantern doctor`** | Diagnose environment, credentials, latency, and MCP health |
234
+ | **`lantern mcp`** | Manage MCP servers (`list`, `add`, `remove`, `test`, `enable`, `disable`) |
169
235
  | **`lantern --help`** | View all CLI flags and options |
170
- | **`lantern --version`** | Output version string |
236
+ | **`lantern --version`** | Output version string (`1.0.1`) |
171
237
 
172
- ### Global Options
238
+ ### Global Flags
173
239
 
240
+ - **`-p, --provider <provider>`**: Select provider (`gemini`, `openai`, `anthropic`, `openrouter`, or custom).
174
241
  - **`-m, --model <id>`**: Override model ID (default: `gemini-3.8-flash`).
175
242
  - **`-C, --cwd <path>`**: Set workspace directory for agent operations.
176
243
  - **`-s, --session <id>`**: Use or resume a specific session ID.
177
244
  - **`-a, --attach <files...>`**: Attach text files, images (`.png`, `.jpg`, `.webp`), or PDFs.
178
245
  - **`--yolo`**: Skip interactive confirmation prompts for file edits and shell commands.
179
246
  - **`--json`**: Output results formatted as JSON.
247
+ - **`--timeout <ms>`**: Maximum total request duration (default: `60000`).
248
+ - **`--first-token-timeout <ms>`**: Maximum wait time for initial response token (default: `30000`).
249
+ - **`--timing`**: Display detailed execution and latency timing diagnostics.
250
+ - **`--fast`**: Enable low-latency mode where supported.
251
+ - **`--skill <skills...>`**: Explicitly activate one or more skills for the run.
180
252
 
181
253
  ---
182
254
 
183
- ## 💡 Usage Examples
255
+ ## 🛡️ Safe Mode & Invariants
184
256
 
185
- ### 1. Interactive Shell
186
-
187
- ```bash
188
- lantern
189
- ```
190
-
191
- Inside the interactive REPL:
192
- - Type your question or task naturally.
193
- - Use `\` at the end of a line for multiline continuation.
194
- - Enclose multiline code blocks inside `""" ... """`.
195
- - Press `Up`/`Down` arrows to navigate previous prompt history.
196
- - Available slash commands:
197
- - `/help` — List available commands and tools.
198
- - `/clear` — Clear terminal screen.
199
- - `/status` — View workspace, model, token count, and active session ID.
200
- - `/model [id]` — Switch model on the fly (e.g. `/model gemini-3.8-flash`).
201
- - `/plan [on|off]` — Toggle read-only plan mode.
202
- - `/yolo [on|off]` — Toggle YOLO mode for the session.
203
- - `/sessions` — List saved sessions.
204
- - `/history` — Print recent conversation turns.
205
- - `/export [md|json]` — Export current session transcript.
206
- - `/exit` or `/quit` — Save session and exit.
207
-
208
- ### 2. One-Shot Question with File Attachment
209
-
210
- ```bash
211
- lantern ask "Refactor this component to use React hooks" --attach src/components/UserProfile.tsx
212
- ```
213
-
214
- ### 3. Read-Only Planning Mode
215
-
216
- ```bash
217
- lantern plan "Design an authentication system using JWT tokens with refresh cookies"
218
- ```
219
-
220
- ### 4. Piped Standard Input
221
-
222
- ```bash
223
- # macOS / Linux
224
- cat build.log | lantern "Summarize the root cause of these compiler errors"
225
-
226
- # Windows PowerShell
227
- Get-Content build.log | lantern "Summarize the root cause of these compiler errors"
228
- ```
257
+ Code Lantern runs in **Safe Mode** by default:
258
+ 1. **Interactive Unified Diffs**: Displays colored unified diffs showing exact deletions in red and additions in green before touching any file.
259
+ 2. **Command Approvals**: Shows command line and working directory before running shell commands.
260
+ 3. **Workspace Boundary**: Strict containment prevents path traversal (`../../`) or symlink escapes outside the workspace.
261
+ 4. **Secret Firewall**: Blocks reading `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, or credential stores.
262
+ 5. **Destructive Command Guard**: Rejects destructive system commands (e.g., `rm -rf /`, Windows `format c:`, `del /s /q c:\*`).
229
263
 
230
264
  ---
231
265
 
232
- ## 🛡️ Approval & YOLO Modes
233
-
234
- Code Lantern defaults to **Safe Mode**.
266
+ ## 🧪 Automated Testing
235
267
 
236
- ### Safe Mode (Default)
237
-
238
- 1. **Before Editing Files**: Displays an ANSI color-coded patch diff showing exact removals in red and additions in green:
239
- ```text
240
- Approve this action? [y/N / (a)ll-yolo]:
241
- ```
242
- 2. **Before Creating Files**: Displays a line-numbered preview of the file.
243
- 3. **Before Executing Shell Commands**: Displays the exact command and working directory.
244
-
245
- ### YOLO Mode (`--yolo`)
246
-
247
- Run Lantern with `--yolo` or enter `yolo` / `a` at an approval prompt to auto-approve safe modifications for that execution:
248
- ```bash
249
- lantern --yolo ask "Run npm test and fix failing assertions"
250
- ```
251
-
252
- ### Unconditional Safety Invariants
253
-
254
- - **Strict Workspace Containment**: Lantern cannot read, edit, or execute outside your workspace directory. Path traversal attempts (`../../`) and symlink escapes are rejected.
255
- - **Secret Shielding**: `.env`, `.env.*`, `*.pem`, `*.key`, `id_rsa`, and credential JSON files are blocked from reading or being sent to Gemini.
256
- - **Destructive Command Firewall**: Destructive system commands (e.g. `rm -rf /`, `mkfs`, Windows `format c:`, `del /s /q c:\*`) are strictly blocked across all platforms.
257
- - **Token Redaction**: Any API keys detected in text are automatically masked before saving or displaying.
258
-
259
- ---
260
-
261
- ## 🔌 Model Context Protocol (MCP)
262
-
263
- Connect external tool servers using the official Model Context Protocol stdio transport:
264
-
265
- ```bash
266
- # Add SQLite database MCP server
267
- lantern mcp add sqlite npx -y @modelcontextprotocol/server-sqlite ./data.db
268
-
269
- # Test server connection and inspect exposed tools
270
- lantern mcp test sqlite
271
-
272
- # List configured MCP servers
273
- lantern mcp list
274
-
275
- # Disable or enable a server
276
- lantern mcp disable sqlite
277
- lantern mcp enable sqlite
278
-
279
- # Remove a server
280
- lantern mcp remove sqlite
281
- ```
282
-
283
- ---
284
-
285
- ## ⚙️ Configuration & Project Instructions
286
-
287
- Configurations are persisted in `~/.codelantern/config.json` (or `%USERPROFILE%\.codelantern\config.json` on Windows):
268
+ Code Lantern includes a comprehensive test suite covering security sandboxing, CRLF line endings, tool execution, session persistence, timeout handling, first-token limits, cancellation, AES-256 encryption, skills parsing, and provider registries:
288
269
 
289
270
  ```bash
290
- # View configuration
291
- lantern config
292
-
293
- # Update settings
294
- lantern config set defaultModel gemini-3.8-flash
295
- lantern config set maxSteps 30
296
- lantern config set temperature 0.2
297
- ```
298
-
299
- ### Project Instructions (`LANTERN.md`)
271
+ # Run test suite (32 automated checks)
272
+ npm test
300
273
 
301
- Place a `LANTERN.md` (or `GEMINI.md`) file in your project root to provide persistent instructions to Code Lantern:
274
+ # Run TypeScript typecheck
275
+ npm run lint
302
276
 
303
- ```markdown
304
- # Project Instructions
305
- - Codebase language: TypeScript (NodeNext modules)
306
- - Run `npm test` before concluding file edits
307
- - Keep imports organized alphabetically
277
+ # Build production bundle
278
+ npm run build
308
279
  ```
309
280
 
310
281
  ---
311
282
 
312
- ## 🚀 npm Release Checklist
283
+ ## 🚀 npm Publishing Guide (v1.0.1)
313
284
 
314
- To publish `codelantern-agent-cli` to npm:
285
+ To publish `codelantern-agent-cli@1.0.1` to npm:
315
286
 
316
- 1. **Ensure Tests Pass**:
287
+ 1. **Verify All Checks Pass**:
317
288
  ```bash
318
289
  npm test
319
290
  npm run lint
320
291
  npm run build
321
292
  ```
322
- 2. **Verify Pack Contents**:
293
+ 2. **Inspect Tarball Contents**:
323
294
  ```bash
324
295
  npm pack --dry-run
325
296
  ```
326
- *Verify that only `dist/`, `README.md`, and `LICENSE` are included. Ensure no `.env`, `.codelantern/`, or test files are listed.*
327
- 3. **Log in to npm**:
297
+ *Verify that only `dist/`, `README.md`, and `LICENSE` are included.*
298
+ 3. **Authenticate & Publish**:
328
299
  ```bash
329
300
  npm login
330
- ```
331
- 4. **Publish**:
332
- ```bash
333
301
  npm publish --access public
334
302
  ```
335
303
 
336
304
  ---
337
305
 
338
- ## 🧪 Testing
339
-
340
- Run the automated cross-platform test suite:
341
-
342
- ```bash
343
- npm test
344
- ```
345
-
346
- Run TypeScript compilation check:
347
-
348
- ```bash
349
- npm run lint
350
- ```
351
-
352
- ---
353
-
354
- ## ⚠️ Known Limitations & Platform Notes
306
+ ## ⚠️ Platform Verification Notes
355
307
 
356
- - **Directly Tested Platform**: Built and fully tested on **macOS (Apple Silicon arm64, Node v26)** with all 23 automated unit and integration tests passing.
357
- - **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.
358
- - **Terminal Colors**: A modern terminal emulator with ANSI color support (macOS Terminal, iTerm2, Windows Terminal, VS Code Integrated Terminal) is recommended.
308
+ - **macOS (Directly Verified)**: Developed, built, and verified on macOS (Apple Silicon arm64, Node v26) with all 32 automated tests passing and live provider connectivity verified.
309
+ - **Windows (Architecturally Supported)**: Built with portable Node.js APIs (`path.normalize`, `path.sep`, `windowsHide: true`, CRLF handling, and Windows command guards). Direct testing on native Windows hardware or Windows CI is recommended upon deployment.
359
310
 
360
311
  ---
361
312