kovence-cli 0.0.0-stage → 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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project will be documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [1.0.0] - 2026-11-19
9
+
10
+ ### Added
11
+ - Zero-dependency multi-step AI coding-agent CLI (`kovence` / `kovence-cli`).
12
+ - Support for OpenAI-compatible and Anthropic API providers with retry/backoff, custom provider wizard (`/api add`), and `apiKeyEnv` isolation.
13
+ - Interactive full-screen TUI (`KovenceTUI`) with amber/dark/light/terminal themes, `@file` fuzzy picker, `@file:L10-50` line ranges, `!cmd` shell escape, and persistent input history.
14
+ - Permission engine with `default`, `accept-edits`, `plan`, and `auto` modes, plus interactive `Manage Permissions` panel inside `/settings`.
15
+ - Ephemeral `SUDO_ASKPASS` handling, resumable Range downloads with SHA-256 verification, file checkpoints with `/undo`, background tasks (`/tasks`), and `kovence doctor`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kovence
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,387 @@
1
- # Temporary Holding Version
1
+ # Kovence CLI
2
2
 
3
- 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.
3
+ > **Zero-dependency, multi-step AI coding-agent CLI for Node.js ≥ 20.12**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/kovence-cli.svg)](https://www.npmjs.com/package/kovence-cli)
6
+ [![npm downloads](https://img.shields.io/npm/dm/kovence-cli.svg)](https://www.npmjs.com/package/kovence-cli)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Node ≥ 20.12](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](https://nodejs.org)
9
+
10
+ Kovence CLI is a powerful, **fully autonomous** AI coding-agent that runs entirely in your terminal. It supports any OpenAI-compatible or Anthropic endpoint, has zero runtime npm dependencies, and ships with a full-screen TUI, session management, background tasks, file checkpoints, and undo.
11
+
12
+ **Homepage:** <https://kovence-cli.kovence.com>
13
+
14
+ ---
15
+
16
+ ## Table of Contents
17
+
18
+ - [Installation](#installation)
19
+ - [Quick Start](#quick-start)
20
+ - [Provider Setup](#provider-setup)
21
+ - [Agent Modes](#agent-modes)
22
+ - [CLI Flags](#cli-flags)
23
+ - [Slash Commands](#slash-commands)
24
+ - [Keyboard Shortcuts](#keyboard-shortcuts)
25
+ - [File Mentions (@file)](#file-mentions-file)
26
+ - [Background Tasks](#background-tasks)
27
+ - [Session Management](#session-management)
28
+ - [Settings Reference](#settings-reference)
29
+ - [Environment Diagnostics](#environment-diagnostics)
30
+ - [License](#license)
31
+
32
+ ---
33
+
34
+ ## Installation
35
+
36
+ ### Global install (recommended)
37
+
38
+ ```bash
39
+ npm install -g kovence-cli
40
+ ```
41
+
42
+ After install, the `kovence` command is available system-wide:
43
+
44
+ ```bash
45
+ kovence # Launch interactive TUI
46
+ kovence --help # Show help
47
+ kovence doctor # Run diagnostics
48
+ ```
49
+
50
+ ### Try without installing
51
+
52
+ ```bash
53
+ npx kovence-cli@latest
54
+ ```
55
+
56
+ ### From source
57
+
58
+ ```bash
59
+ git clone https://github.com/kovence/kovence-cli.git
60
+ cd kovence-cli
61
+ npm install -g .
62
+ ```
63
+
64
+ ---
65
+
66
+ ## Quick Start
67
+
68
+ 1. **Launch the TUI:**
69
+ ```bash
70
+ kovence
71
+ ```
72
+
73
+ 2. **Add an AI provider** — on first launch there is no default provider. Add one with:
74
+ ```
75
+ /api add
76
+ ```
77
+ Or open **Models → + Add Custom Provider** inside the TUI.
78
+
79
+ 3. **Start chatting** — type your message and press `Enter`. The agent will plan, call tools, and iterate autonomously.
80
+
81
+ 4. **Switch modes** with `Shift+Tab` or `/mode`:
82
+ - `plan` → read-only research
83
+ - `auto` → fully autonomous, no approval prompts
84
+
85
+ ---
86
+
87
+ ## Provider Setup
88
+
89
+ Kovence supports any **OpenAI-compatible** endpoint and **Anthropic** natively.
90
+
91
+ ### Interactive wizard
92
+
93
+ ```
94
+ /api add
95
+ ```
96
+
97
+ This opens a step-by-step wizard to enter your base URL, API key, and models. Providers are saved to `~/.config/kovence/providers.json`.
98
+
99
+ ### Secret hygiene with `apiKeyEnv`
100
+
101
+ Instead of storing your raw API key on disk, you can point to an environment variable:
102
+
103
+ ```json
104
+ {
105
+ "name": "openai",
106
+ "type": "openai",
107
+ "baseURL": "https://api.openai.com/v1",
108
+ "apiKeyEnv": "OPENAI_API_KEY"
109
+ }
110
+ ```
111
+
112
+ Kovence will read the key from your shell environment at runtime — it is never written to the config file.
113
+
114
+ ### Popular endpoints
115
+
116
+ | Provider | Base URL |
117
+ |---|---|
118
+ | OpenAI | `https://api.openai.com/v1` |
119
+ | Anthropic | _(select "anthropic" type)_ |
120
+ | Groq | `https://api.groq.com/openai/v1` |
121
+ | DeepSeek | `https://api.deepseek.com/v1` |
122
+ | Ollama (local) | `http://localhost:11434/v1` |
123
+ | LiteLLM proxy | `http://localhost:4000` |
124
+
125
+ ---
126
+
127
+ ## Agent Modes
128
+
129
+ Switch modes with `/mode` or `Shift+Tab`:
130
+
131
+ | Mode | Behavior |
132
+ |---|---|
133
+ | `default` | Confirms file edits, downloads, and shell commands per policy |
134
+ | `accept-edits` | Auto-approves workspace file edits; confirms commands and downloads |
135
+ | `plan` | Read-only research & planning; all mutating tools are blocked |
136
+ | `auto` | **Fully autonomous** — no approval prompts for any tool call |
137
+
138
+ > **Auto mode** is designed for truly autonomous operation. The agent never asks for tool approval. Safety comes from the permission engine, audit log, file checkpoints, and undo — not from prompts.
139
+
140
+ ---
141
+
142
+ ## CLI Flags
143
+
144
+ ```
145
+ kovence [options] [prompt]
146
+ kovence doctor
147
+ ```
148
+
149
+ | Flag | Description |
150
+ |---|---|
151
+ | `--provider <name>` | Use a configured provider by name |
152
+ | `-m, --model <name>` | Override the active model |
153
+ | `-p, --prompt <text>` | Non-interactive headless prompt (exits when done) |
154
+ | `-s, --system <text>` | Override the system prompt |
155
+ | `--mode <mode>` | Agent mode: `default \| accept-edits \| plan \| auto` |
156
+ | `-a, --auto` | Alias for `--mode auto` |
157
+ | `--add-dir <path>` | Grant workspace access to an extra directory (repeatable) |
158
+ | `--no-tools` | Disable all tool calling (chat-only mode) |
159
+ | `--no-summary` | Skip post-response session memory summarization |
160
+ | `--plain` | Use plain scrollback REPL instead of full-screen TUI |
161
+ | `--json` | Emit structured JSON result in `-p` headless mode |
162
+ | `--no-session` | Run without persisting session history to disk |
163
+ | `--debug` | Enable verbose debug tracing |
164
+ | `-t, --temp <num>` | Sampling temperature (`0.0` to `2.0`) |
165
+ | `--max-tokens <num>` | Max completion tokens |
166
+ | `--session <name>` | Resume or create a specific named session |
167
+ | `-c, --continue` | Resume the most recent session |
168
+ | `--new-session <name>` | Start a fresh session with the given name |
169
+ | `-v, --version` | Show version and exit |
170
+ | `-h, --help` | Show help and exit |
171
+ | `doctor` | Subcommand: check Node, tools, config, and provider reachability |
172
+
173
+ ### Headless / scripting example
174
+
175
+ ```bash
176
+ # Single-shot prompt, structured JSON output
177
+ kovence -p "summarize this file" --json
178
+
179
+ # Pipe output
180
+ echo "refactor this function" | kovence --plain --no-session
181
+ ```
182
+
183
+ ---
184
+
185
+ ## Slash Commands
186
+
187
+ Type `/` in the composer to see autocomplete suggestions.
188
+
189
+ | Command | Description |
190
+ |---|---|
191
+ | `/help` | Show all available commands |
192
+ | `/mode` | Switch agent mode (`default \| accept-edits \| plan \| auto`) |
193
+ | `/settings` | Open interactive Settings panel (`Ctrl+,`) |
194
+ | `/set <key> <val>` | Update a persisted setting directly |
195
+ | `/api` | Switch, add, or remove AI providers |
196
+ | `/model [name]` | Pick or switch the active model |
197
+ | `/sessions` | Session picker — list, switch, delete sessions (`Ctrl+S`) |
198
+ | `/new` | Open a new isolated session (`Ctrl+N`) |
199
+ | `/rename <name>` | Rename the current session |
200
+ | `/fork [name]` | Fork current session into a new branch |
201
+ | `/export [md\|json] [path]` | Export session transcript to a file |
202
+ | `/retry` | Retry the last failed or aborted turn |
203
+ | `/edit-last` | Pop the last turn and restore your prompt for editing |
204
+ | `/history` | Show session chat history |
205
+ | `/memory` | Show and manage session & global memory |
206
+ | `/todos` | Show current multi-step todo list |
207
+ | `/compact` | Compact history into a session summary |
208
+ | `/stats` | Show context size, speed, and token statistics |
209
+ | `/cost` | Show estimated session token cost in USD |
210
+ | `/copy` | Copy the last AI response to clipboard (`Ctrl+Y`) |
211
+ | `/select` | Toggle native terminal mouse-select mode (`F2`) |
212
+ | `/save` | Save/rename the current session |
213
+ | `/undo` | Roll back the last file edit/write/delete checkpoint |
214
+ | `/init` | Scan project and generate `KOVENCE.md` instructions |
215
+ | `/tasks [log <id> \| kill <id>]` | List, view logs, or stop background shell tasks |
216
+ | `/clear` | Clear current session history and memory |
217
+ | `/exit` | Exit Kovence CLI |
218
+
219
+ ---
220
+
221
+ ## Keyboard Shortcuts
222
+
223
+ ### Composer (input area)
224
+
225
+ | Key | Action |
226
+ |---|---|
227
+ | `Enter` | Send message |
228
+ | `Shift+Enter` / `Alt+Enter` | Insert newline |
229
+ | `Tab` | Accept autocomplete suggestion (slash command / `@file`) |
230
+ | `↑` / `↓` | Scroll through input history or suggestions |
231
+ | `Ctrl+Left` / `Alt+B` | Move cursor one word left |
232
+ | `Ctrl+Right` / `Alt+F` | Move cursor one word right |
233
+ | `Ctrl+W` / `Alt+Backspace` | Delete word to the left |
234
+ | `Ctrl+C` _(busy)_ | Cancel the current agent turn |
235
+ | `Ctrl+C` _(idle)_ | Exit Kovence CLI |
236
+
237
+ ### TUI global shortcuts
238
+
239
+ | Key | Action |
240
+ |---|---|
241
+ | `Ctrl+,` | Open Settings panel |
242
+ | `Ctrl+S` | Open session picker |
243
+ | `Ctrl+N` | Start a new session |
244
+ | `Ctrl+Y` | Copy last AI response to clipboard |
245
+ | `Ctrl+L` | Clear and redraw the screen |
246
+ | `Ctrl+O` | Toggle last collapsible block (tool output) |
247
+ | `Shift+Tab` | Cycle agent mode |
248
+ | `F2` | Toggle mouse-select mode |
249
+
250
+ ---
251
+
252
+ ## File Mentions (@file)
253
+
254
+ You can mention files directly in your prompt using the `@` syntax. Kovence will read the file content and include it in context.
255
+
256
+ ```
257
+ @README.md what does this say about installation?
258
+
259
+ @src/agent/turn.js:L1-80 explain this section
260
+ ```
261
+
262
+ - `@filename` — include the entire file
263
+ - `@filename:L10-50` — include only lines 10–50
264
+
265
+ Autocomplete is available: type `@` and press `Tab` to browse files.
266
+
267
+ ---
268
+
269
+ ## Background Tasks
270
+
271
+ ### Direct shell escape
272
+
273
+ In plain REPL mode, prefix a command with `!` to run it directly in your shell:
274
+
275
+ ```
276
+ !git status
277
+ !npm test
278
+ ```
279
+
280
+ ### Agent background tasks
281
+
282
+ The agent can run shell commands as background tasks (`run_command` with `background: true`). Manage them with:
283
+
284
+ ```
285
+ /tasks # List all running background tasks
286
+ /tasks log <id> # Stream logs from a task
287
+ /tasks kill <id> # Terminate a background task
288
+ ```
289
+
290
+ Background tasks persist across turns and are shown in the status bar when active.
291
+
292
+ ---
293
+
294
+ ## Session Management
295
+
296
+ ### Auto-naming
297
+
298
+ Sessions are automatically named from your first prompt (slugified, e.g., `fix-auth-bug`). You can rename anytime:
299
+
300
+ ```
301
+ /rename my-feature-branch
302
+ ```
303
+
304
+ ### Date grouping
305
+
306
+ The session picker (`Ctrl+S`) groups sessions by date (Today, Yesterday, This Week, etc.) for easy navigation.
307
+
308
+ ### Fork & Export
309
+
310
+ ```
311
+ /fork # Fork into a new session (preserves history)
312
+ /fork my-fork-name # Fork with a specific name
313
+
314
+ /export md # Export transcript as Markdown
315
+ /export json # Export as JSON
316
+ /export md ~/Desktop/session.md # Export to a specific path
317
+ ```
318
+
319
+ ### Edit last turn
320
+
321
+ ```
322
+ /edit-last # Removes the last turn and restores your prompt for editing
323
+ ```
324
+
325
+ ### Undo file changes
326
+
327
+ ```
328
+ /undo # Roll back the last file write/edit/delete (checkpoint-based)
329
+ ```
330
+
331
+ ---
332
+
333
+ ## Settings Reference
334
+
335
+ Open the interactive settings panel with `Ctrl+,` or `/settings`. Settings are saved to `~/.config/kovence/settings.json`.
336
+
337
+ | Setting | Values | Description |
338
+ |---|---|---|
339
+ | `agentMode` | `default \| accept-edits \| plan \| auto` | Default agent mode on launch |
340
+ | `toolPermission` | `default \| auto` | Tool permission policy |
341
+ | `nonWorkspaceAccess` | `true \| false` | Allow reads outside workspace |
342
+ | `model` | string | Default model name |
343
+ | `provider` | string | Default provider name |
344
+ | `toolsEnabled` | `true \| false` | Enable/disable tool calling |
345
+ | `autoSummarize` | `true \| false` | Auto-compact history when context is full |
346
+ | `maxToolSteps` | number | Max tool-call iterations per turn |
347
+ | `maxHistoryMessages` | number | Max messages kept in context |
348
+ | `contextWindow` | number | Context window size (tokens) |
349
+ | `temperature` | `0.0`–`2.0` | Sampling temperature |
350
+ | `maxTokens` | number | Max completion tokens |
351
+ | `verbosity` | `low \| normal \| high` | Tool output verbosity in TUI |
352
+ | `language` | `english \| banglish \| bangla` | Preferred response language |
353
+ | `renderingMode` | `fullscreen \| inline` | TUI layout mode |
354
+ | `queuedMessages` | `queue \| interrupt` | Behavior when a message arrives during a turn |
355
+ | `showTips` | `true \| false` | Show contextual tips in TUI |
356
+ | `showActiveTasks` | `true \| false` | Show background task count in status bar |
357
+ | `notifications` | `true \| false` | Desktop notifications on turn completion |
358
+ | `colorScheme` | `amber \| dark \| light \| terminal` | TUI color theme |
359
+
360
+ You can also set any value directly:
361
+
362
+ ```bash
363
+ # In the TUI composer:
364
+ /set agentMode auto
365
+ /set colorScheme dark
366
+ /set temperature 0.7
367
+ ```
368
+
369
+ ---
370
+
371
+ ## Environment Diagnostics
372
+
373
+ ```bash
374
+ kovence doctor
375
+ ```
376
+
377
+ Checks and reports on:
378
+ - Node.js version compatibility
379
+ - Required system tools (`git`, `curl`, etc.)
380
+ - Config and provider file validity
381
+ - Provider API reachability (live ping)
382
+
383
+ ---
384
+
385
+ ## License
386
+
387
+ MIT © Kovence
package/SECURITY.md ADDED
@@ -0,0 +1,13 @@
1
+ # Security Policy
2
+
3
+ ## Reporting a Vulnerability
4
+
5
+ If you discover a security vulnerability in `kovence-cli`, please do **not** open a public issue with exploit details. Instead, report it privately to the maintainers with reproduction steps, affected versions, and impact assessment.
6
+
7
+ ## Security Model Notes
8
+
9
+ - **API Keys**: Prefer storing API keys via `apiKeyEnv` (environment variable name) rather than plaintext in `~/.config/kovence/providers.json`. Provider config files are written with `0600` permissions.
10
+ - **Permission Modes**:
11
+ - `default`, `accept-edits`, and `plan` enforce interactive confirmation and workspace boundaries for mutating actions.
12
+ - `auto` mode is designed for autonomous execution without tool-approval prompts.
13
+ - **Sudo Handling**: Interactive `sudo` prompts use an ephemeral `SUDO_ASKPASS` helper (`0700` dir / `0600` script) cleaned up on exit.