ownkey 1.0.1 → 1.0.2

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 (2) hide show
  1. package/README.md +216 -46
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,86 +1,256 @@
1
- # OwnKey CLI
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/ArpitK24/OwnKey/main/assets/logo.png" alt="OwnKey" width="420">
3
+ </p>
2
4
 
3
- > AI-powered code analysis that works with or without a database
5
+ <h3 align="center">The local-first AI coding agent that runs on your own keys.</h3>
4
6
 
5
- [![npm version](https://img.shields.io/npm/v/ownkey.svg)](https://www.npmjs.com/package/ownkey)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+ <p align="center">
8
+ Scan a codebase, get reviewable suggestions as unified diffs, apply them with automatic backups, and undo in one command.<br>
9
+ OpenAI, Anthropic, Google Gemini, or fully offline with Ollama. No account, no telemetry, no required database.
10
+ </p>
7
11
 
8
- **OwnKey** is a local-first AI coding agent that analyzes your codebase and provides intelligent suggestions for bugs, security issues, performance improvements, and code quality.
12
+ <p align="center">
13
+ <a href="https://www.npmjs.com/package/ownkey"><img src="https://img.shields.io/npm/v/ownkey?style=flat-square&color=111111&label=npm" alt="npm version"></a>
14
+ <a href="https://www.npmjs.com/package/ownkey"><img src="https://img.shields.io/npm/dm/ownkey?style=flat-square&color=111111" alt="npm downloads"></a>
15
+ <img src="https://img.shields.io/node/v/ownkey?style=flat-square&color=111111" alt="node version">
16
+ <a href="https://github.com/ArpitK24/OwnKey/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/ownkey?style=flat-square&color=111111" alt="license"></a>
17
+ </p>
9
18
 
10
- 🌐 **[Full Documentation](https://ownkey.qzz.io)**
19
+ <p align="center">
20
+ <a href="https://ownkey.qzz.io/docs">Documentation</a> &nbsp;&middot;&nbsp;
21
+ <a href="https://ownkey.qzz.io/docs/getting-started">Quick start</a> &nbsp;&middot;&nbsp;
22
+ <a href="https://ownkey.qzz.io/docs/commands">CLI reference</a> &nbsp;&middot;&nbsp;
23
+ <a href="https://github.com/ArpitK24/OwnKey/blob/main/CHANGELOG.md">Changelog</a>
24
+ </p>
11
25
 
12
- ## ✨ Features
26
+ ---
27
+
28
+ ## Overview
13
29
 
14
- - 🤖 **Multi-Provider AI** - Supports Google Gemini, OpenAI, Anthropic Claude, and Ollama
15
- - 🔒 **Privacy-First** - Works completely offline with local-only mode
16
- - 💾 **Optional Database** - Supabase integration for persistent history (optional)
17
- - 🚀 **Auto-Model Detection** - Instantly supports new AI models without CLI updates
18
- - 🎯 **Smart Suggestions** - Identifies bugs, security issues, performance problems, and more
19
- - ⚡ **Apply & Undo** - Safely apply suggestions with automatic backups
30
+ OwnKey is a command-line coding agent for developers who want AI code review without handing their workflow to a hosted service. It reads your project locally, sends only the files under analysis to the model provider you choose, and returns structured suggestions: bugs, security issues, performance problems, refactors, and more, each with a severity, a rationale, and a patch you can inspect before anything touches disk.
31
+
32
+ ```text
33
+ scan -> suggest -> apply -> undo
34
+ map review patch restore
35
+ ```
20
36
 
21
- ## 🚀 Quick Start
37
+ | | |
38
+ |---|---|
39
+ | **Bring your own key** | Use your existing OpenAI, Anthropic, or Gemini account, or any OpenAI-compatible endpoint. You pay your provider directly; OwnKey adds nothing in between. |
40
+ | **Fully offline option** | Point OwnKey at a local Ollama server and no code leaves your machine. |
41
+ | **Review before write** | Every suggestion carries a unified diff. `apply` previews it and asks for confirmation; `--dry-run` never writes. |
42
+ | **Safe by default** | Each apply creates a backup first. `undo` restores modified files and removes files the apply created. |
43
+ | **Standalone** | Suggestions and backups live in `~/.ownkey`. A Postgres or Supabase database is optional, for teams that want shared history. |
22
44
 
23
- ### Installation
45
+ ## Requirements
46
+
47
+ - Node.js 18 or later
48
+ - An API key for OpenAI, Anthropic, or Google Gemini, **or** a running [Ollama](https://ollama.com) server
49
+
50
+ ## Installation
24
51
 
25
52
  ```bash
26
53
  npm install -g ownkey
54
+ ownkey --version
27
55
  ```
28
56
 
29
- ### Basic Usage
57
+ ## Quick start
58
+
59
+ **1. Configure a provider**
60
+
61
+ ```bash
62
+ # Hosted providers
63
+ ownkey config --provider openai --api-key sk-...
64
+ ownkey config --provider anthropic --api-key sk-ant-...
65
+ ownkey config --provider gemini --api-key AIza...
66
+
67
+ # Fully local, no key required
68
+ ownkey config --provider ollama --model qwen2.5-coder:latest
69
+ ```
70
+
71
+ Any model your key can access works. Set it with `--model`; OwnKey does not maintain a model allowlist.
72
+
73
+ **2. Analyze a project**
30
74
 
31
75
  ```bash
32
- # Configure with your AI provider
33
- ownkey config --provider gemini --api-key YOUR_API_KEY
76
+ cd my-project
77
+ ownkey scan . # see what will be analyzed
78
+ ownkey suggest . # generate suggestions
79
+ ```
80
+
81
+ **3. Review and apply**
34
82
 
35
- # Analyze your code
36
- ownkey suggest .
83
+ ```bash
84
+ ownkey apply # list pending suggestions
85
+ ownkey apply <id> --dry-run # preview the diff, write nothing
86
+ ownkey apply <id> # preview, confirm, apply with backup
87
+ ownkey apply --all --severity high # apply everything rated high or critical
88
+ ```
37
89
 
38
- # List pending suggestions, preview one, then apply it
39
- ownkey apply
40
- ownkey apply local-123456789-0 --dry-run
41
- ownkey apply local-123456789-0
90
+ **4. Undo if needed**
42
91
 
43
- # Undo if needed
44
- ownkey undo
92
+ ```bash
93
+ ownkey undo --list # recent applies
94
+ ownkey undo <backup-id> # restore that apply
45
95
  ```
46
96
 
47
- ### Local-Only Mode
97
+ ## Commands
98
+
99
+ | Command | Purpose |
100
+ |---|---|
101
+ | `ownkey config` | Set the AI provider, model, endpoint, and optional database. Run with no flags for an interactive wizard. |
102
+ | `ownkey scan [path]` | List the files OwnKey would analyze, honoring `.gitignore` and `.ownkeyignore`. |
103
+ | `ownkey suggest [path]` | Analyze files and store suggestions for review. |
104
+ | `ownkey apply [id]` | Apply one suggestion, or all pending ones with `--all`. |
105
+ | `ownkey undo [backup-id]` | Restore files from a backup created by `apply`. |
106
+
107
+ <details>
108
+ <summary><strong>Full option reference</strong></summary>
109
+
110
+ #### `ownkey config`
111
+
112
+ | Option | Description |
113
+ |---|---|
114
+ | `--show` | Print the current configuration (keys are masked). |
115
+ | `--provider <name>` | `openai`, `anthropic`, `gemini`, or `ollama`. |
116
+ | `--api-key <key>` | Provider API key. Not needed for Ollama. |
117
+ | `--model <model>` | Any model available to your key or Ollama server. |
118
+ | `--endpoint <url>` | Ollama server URL, or an OpenAI-compatible base URL with `--provider openai`. |
119
+ | `--database-url <url>` | Optional Postgres connection string for shared history. |
120
+ | `--no-database` | Remove the database and use local storage only. |
121
+ | `--reset` | Reset configuration to defaults. |
122
+ | `-y, --yes` | Skip confirmation prompts. |
123
+
124
+ #### `ownkey scan [path]`
125
+
126
+ | Option | Description |
127
+ |---|---|
128
+ | `--max-file-size <size>` | Skip files larger than this. Default `500kb`. |
129
+ | `--ignore <patterns...>` | Additional ignore patterns. |
130
+
131
+ #### `ownkey suggest [path]`
132
+
133
+ | Option | Description |
134
+ |---|---|
135
+ | `--type <type>` | `bug`, `security`, `performance`, `refactor`, `style`, `architecture`, `test`, or `documentation`. |
136
+ | `--severity <level>` | Minimum severity: `critical`, `high`, `medium`, `low`, `info`. |
137
+ | `--max-files <n>` | Maximum files to analyze. Default `10`. |
48
138
 
49
- No database required! OwnKey automatically stores suggestions in `~/.ownkey/storage/`:
139
+ #### `ownkey apply [id]`
140
+
141
+ | Option | Description |
142
+ |---|---|
143
+ | `--dry-run` | Show the diff without writing. |
144
+ | `--auto` | Apply without the confirmation prompt (for scripts and CI). |
145
+ | `--all` | Apply every pending suggestion for the project. |
146
+ | `--severity <level>` | With `--all`, only apply at or above this severity. |
147
+ | `--project <path>` | Project the suggestions belong to. Default `.`. |
148
+ | `--force` | Apply matching hunks even if others do not match. |
149
+ | `--no-backup` | Skip the backup. Not recommended. |
150
+
151
+ #### `ownkey undo [backup-id]`
152
+
153
+ | Option | Description |
154
+ |---|---|
155
+ | `--list` | List recent applies. |
156
+ | `--all` | Undo all applies from today. |
157
+ | `-y, --yes` | Skip the confirmation prompt. |
158
+
159
+ #### Global options
160
+
161
+ `--local-only`, `--verbose`, `--debug`, `--quiet`
162
+
163
+ </details>
164
+
165
+ ## Providers
166
+
167
+ | Provider | Setup | Notes |
168
+ |---|---|---|
169
+ | OpenAI | `--provider openai --api-key <key>` | Any chat model on your account. |
170
+ | Anthropic | `--provider anthropic --api-key <key>` | Any Claude model on your account. |
171
+ | Google Gemini | `--provider gemini --api-key <key>` | Keys from Google AI Studio. |
172
+ | Ollama | `--provider ollama [--endpoint http://host:11434]` | Runs entirely on your hardware. No key. |
173
+ | OpenAI-compatible | `--provider openai --endpoint <base-url> --api-key <key>` | OpenRouter, Groq, LM Studio, vLLM, and similar. |
50
174
 
51
175
  ```bash
52
- ownkey suggest . --local-only
176
+ # Example: OpenRouter through the OpenAI-compatible endpoint
177
+ ownkey config --provider openai \
178
+ --endpoint https://openrouter.ai/api/v1 \
179
+ --api-key sk-or-... \
180
+ --model anthropic/claude-sonnet-4.5
53
181
  ```
54
182
 
55
- ### With Database (Optional)
183
+ ## How apply works
184
+
185
+ 1. The suggestion's unified diff is parsed and matched against the current file. Small line-number drift is tolerated; hunks whose context does not match are rejected rather than guessed.
186
+ 2. The diff is shown and you confirm (skipped with `--auto`, not available without a terminal unless `--auto` is set).
187
+ 3. A backup of every affected file is written to `~/.ownkey/backups`.
188
+ 4. Changes are written, preserving the file's line endings. New files proposed by the model are created.
189
+ 5. The suggestion is marked applied, so it cannot be applied twice by accident.
190
+
191
+ `ownkey undo` reverses step 4 exactly, including removing files that the apply created.
192
+
193
+ ## Data and privacy
194
+
195
+ | Location | Contents |
196
+ |---|---|
197
+ | `~/.ownkey/config.json` | Provider, model, endpoint, and database settings. |
198
+ | OS keychain | API keys, by default. |
199
+ | `~/.ownkey/keys.enc` | Encrypted key file, used when no keychain is available or `OWNKEY_NO_KEYCHAIN=1` is set. |
200
+ | `~/.ownkey/storage/` | Suggestions, kept for 7 days and capped at 100 per project. |
201
+ | `~/.ownkey/backups/` | File backups created by `apply`. |
202
+
203
+ OwnKey has no telemetry and no OwnKey-operated servers. The only network traffic is to the model provider you configured and, if you enabled it, your own database. With Ollama, analysis is fully local.
56
204
 
57
- For persistent history across devices, add any Postgres database (Supabase works great). Use the
58
- **connection string** from Supabase → Connect → Session pooler; tables are created automatically:
205
+ Exclude files from analysis with a `.ownkeyignore` file in the project root (same syntax as `.gitignore`). Common build output, dependencies, lockfiles, binaries, and `.env` are excluded by default.
206
+
207
+ ## Optional database
208
+
209
+ For shared history across machines or a team, connect any Postgres database. Tables are created and migrated automatically on first use.
59
210
 
60
211
  ```bash
212
+ # Supabase: Project -> Connect -> Session pooler connection string
61
213
  ownkey config --database-url "postgresql://postgres.<ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres"
62
- ownkey suggest .
214
+
215
+ # Return to local-only at any time
216
+ ownkey config --no-database
63
217
  ```
64
218
 
65
- `--supabase-url` still works as an alias. Remove it any time with `ownkey config --no-database`.
219
+ If the database is unreachable, OwnKey falls back to local storage and keeps working. `--supabase-url` is accepted as an alias for `--database-url`.
66
220
 
67
- ## 📚 Documentation
221
+ ## Using OwnKey in scripts and CI
68
222
 
69
- Visit **[ownkey.qzz.io](https://ownkey.qzz.io)** for complete documentation:
223
+ Every interactive step has a flag, and OwnKey never blocks waiting for input when there is no terminal.
70
224
 
71
- - [Getting Started](https://ownkey.qzz.io/docs/getting-started)
72
- - [AI Providers Setup](https://ownkey.qzz.io/docs/providers)
73
- - [Commands Reference](https://ownkey.qzz.io/docs/commands)
74
- - [Database Setup](https://ownkey.qzz.io/docs/database)
225
+ ```bash
226
+ export OWNKEY_NO_KEYCHAIN=1
227
+ ownkey config --provider openai --api-key "$OPENAI_API_KEY" --yes
228
+ ownkey suggest . --severity high
229
+ ownkey apply --all --severity high --auto
230
+ ```
75
231
 
76
- ## 🤝 Contributing
232
+ ## Development
77
233
 
78
- Contributions are welcome! Please feel free to submit a Pull Request.
234
+ ```bash
235
+ git clone https://github.com/ArpitK24/OwnKey.git
236
+ cd OwnKey
237
+ npm install
238
+ npm run build
239
+ npm test
240
+ ```
79
241
 
80
- ## 📄 License
242
+ The test suite runs every command end to end against a mock Ollama server, plus unit tests for the diff engine and response parsing. Database tests are opt-in:
81
243
 
82
- MIT © [OwnKey](https://ownkey.qzz.io)
244
+ ```bash
245
+ OWNKEY_TEST_DATABASE_URL=postgresql://user:pass@localhost:5432/postgres npm test
246
+ ```
83
247
 
84
- ---
248
+ ## Contributing
249
+
250
+ Issues and pull requests are welcome. For a change in behavior, please open an issue first to discuss it. Before submitting, run `npm run build` and `npm test`.
251
+
252
+ Report bugs at [github.com/ArpitK24/OwnKey/issues](https://github.com/ArpitK24/OwnKey/issues).
253
+
254
+ ## License
85
255
 
86
- **[Website](https://ownkey.qzz.io)** • **[Documentation](https://ownkey.qzz.io/docs)** • **[GitHub](https://github.com/ArpitK24/ownkey)**
256
+ [MIT](LICENSE) &copy; 2026 OwnKey
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ownkey",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Local-first AI coding agent CLI: scan, suggest, apply and undo with your own keys (OpenAI, Anthropic, Gemini, Ollama)",
5
5
  "main": "dist/index.js",
6
6
  "bin": {