@mc1global/opencode-jarvis 0.10.0 → 0.11.0
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/QUICK-GUIDE.md +42 -28
- package/README.md +288 -165
- package/dist/hooks/first-run-guide.d.ts.map +1 -1
- package/dist/hooks/first-run-guide.js +35 -2
- package/dist/hooks/first-run-guide.js.map +1 -1
- package/dist/hooks/slash-commands.d.ts +36 -0
- package/dist/hooks/slash-commands.d.ts.map +1 -0
- package/dist/hooks/slash-commands.js +121 -0
- package/dist/hooks/slash-commands.js.map +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +14 -1
- package/dist/index.js.map +1 -1
- package/package.json +2 -1
- package/scripts/setup/setup-linux.sh +124 -0
- package/scripts/setup/setup-macos.sh +137 -0
- package/scripts/setup/setup-wsl.sh +175 -0
package/README.md
CHANGED
|
@@ -4,31 +4,44 @@ A native [OpenCode](https://opencode.ai) plugin providing multi-agent developmen
|
|
|
4
4
|
|
|
5
5
|
Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
|
|
6
6
|
|
|
7
|
+
---
|
|
8
|
+
|
|
7
9
|
## Prerequisites
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | Azure DevOps board sync | Optional |
|
|
11
|
+
- **[OpenCode](https://opencode.ai) CLI** — Host runtime for the plugin (**required**)
|
|
12
|
+
- **[Bun](https://bun.sh) >= 1.0** — Production runtime for bun:sqlite (**required**)
|
|
13
|
+
- **[Ollama](https://ollama.ai)** + `embeddinggemma` model — Local embeddings for RAG semantic search (**required for RAG**)
|
|
14
|
+
- **Node.js >= 20** — Test runner only (dev)
|
|
15
|
+
- **[Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** — Azure DevOps board sync (optional)
|
|
16
|
+
- **[Dagger CLI](https://docs.dagger.io/install)** — Container CI/CD gate execution (optional)
|
|
17
|
+
|
|
18
|
+
---
|
|
18
19
|
|
|
19
20
|
## Quick Start
|
|
20
21
|
|
|
21
|
-
### 1
|
|
22
|
+
### Step 1 — Install prerequisites
|
|
23
|
+
|
|
24
|
+
Choose your operating system below. Each section includes both **manual commands** and a link to an **automated setup script** that handles everything.
|
|
25
|
+
|
|
26
|
+
#### macOS
|
|
27
|
+
|
|
28
|
+
**Automated** (recommended):
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-macos.sh | bash
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Or download `scripts/setup/setup-macos.sh` from the repository and run it locally.
|
|
22
35
|
|
|
23
|
-
**
|
|
36
|
+
**Manual:**
|
|
24
37
|
|
|
25
38
|
```bash
|
|
26
39
|
# Bun (required — SQLite runtime)
|
|
27
40
|
curl -fsSL https://bun.sh/install | bash
|
|
28
41
|
|
|
29
|
-
# Ollama (required
|
|
42
|
+
# Ollama + embedding model (required for RAG)
|
|
30
43
|
brew install ollama
|
|
31
|
-
ollama serve # start the server
|
|
44
|
+
ollama serve # start the server (keep running)
|
|
32
45
|
ollama pull embeddinggemma # download the embedding model
|
|
33
46
|
|
|
34
47
|
# Optional: Azure DevOps sync
|
|
@@ -38,42 +51,154 @@ brew install azure-cli && az login
|
|
|
38
51
|
brew install dagger/tap/dagger
|
|
39
52
|
```
|
|
40
53
|
|
|
41
|
-
|
|
54
|
+
#### Linux (Ubuntu/Debian/Fedora/Arch)
|
|
55
|
+
|
|
56
|
+
**Automated** (recommended):
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-linux.sh | bash
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Or download `scripts/setup/setup-linux.sh` from the repository and run it locally.
|
|
63
|
+
|
|
64
|
+
**Manual:**
|
|
42
65
|
|
|
43
66
|
```bash
|
|
67
|
+
# Bun (required)
|
|
44
68
|
curl -fsSL https://bun.sh/install | bash
|
|
69
|
+
|
|
70
|
+
# Ollama + embedding model (required for RAG)
|
|
45
71
|
curl -fsSL https://ollama.ai/install.sh | sh
|
|
46
|
-
ollama serve
|
|
72
|
+
ollama serve # start the server (keep running)
|
|
73
|
+
ollama pull embeddinggemma # download the embedding model
|
|
74
|
+
|
|
75
|
+
# Optional: Azure CLI (Debian/Ubuntu)
|
|
76
|
+
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
|
|
77
|
+
|
|
78
|
+
# Optional: Dagger CLI
|
|
79
|
+
curl -fsSL https://dl.dagger.io/dagger/install.sh | sh
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
#### Windows (WSL)
|
|
83
|
+
|
|
84
|
+
> OpenCode recommends Windows Subsystem for Linux (WSL) for the best experience.
|
|
85
|
+
> See the [OpenCode WSL guide](https://opencode.ai/docs/windows-wsl) for details.
|
|
86
|
+
|
|
87
|
+
**Step 0 — Install WSL** (if you haven't already):
|
|
88
|
+
|
|
89
|
+
Open **PowerShell as Administrator** and run:
|
|
90
|
+
|
|
91
|
+
```powershell
|
|
92
|
+
wsl --install
|
|
47
93
|
```
|
|
48
94
|
|
|
49
|
-
|
|
95
|
+
Restart your computer, then open the **Ubuntu** terminal app.
|
|
50
96
|
|
|
51
|
-
|
|
97
|
+
**Step 1 — Run the setup script inside WSL:**
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# From your WSL terminal (Ubuntu):
|
|
101
|
+
curl -fsSL https://raw.githubusercontent.com/user/repo/main/scripts/setup/setup-wsl.sh | bash
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Or download `scripts/setup/setup-wsl.sh` from the repository and run it inside WSL.
|
|
105
|
+
|
|
106
|
+
**Manual (inside WSL terminal):**
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
# OpenCode CLI
|
|
110
|
+
curl -fsSL https://opencode.ai/install | bash
|
|
111
|
+
|
|
112
|
+
# Bun (required)
|
|
113
|
+
curl -fsSL https://bun.sh/install | bash
|
|
114
|
+
|
|
115
|
+
# Ollama + embedding model (required for RAG)
|
|
116
|
+
curl -fsSL https://ollama.ai/install.sh | sh
|
|
117
|
+
ollama serve # start the server (keep running in a separate terminal)
|
|
118
|
+
ollama pull embeddinggemma # download the embedding model
|
|
119
|
+
|
|
120
|
+
# Optional: Azure CLI
|
|
121
|
+
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash && az login
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
> **WSL performance tip:** For best results, keep your project files in the WSL
|
|
125
|
+
> filesystem (`~/code/my-project`) rather than on `/mnt/c/`. See
|
|
126
|
+
> [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl) for more.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
### Step 2 — Add the plugin to your project
|
|
131
|
+
|
|
132
|
+
Create an `opencode.json` file **in your project root directory**:
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
your-project/ <-- your project root
|
|
136
|
+
opencode.json <-- CREATE THIS FILE HERE
|
|
137
|
+
package.json
|
|
138
|
+
src/
|
|
139
|
+
...
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Content of `opencode.json`:
|
|
52
143
|
|
|
53
144
|
```json
|
|
54
145
|
{
|
|
146
|
+
"$schema": "https://opencode.ai/config.json",
|
|
55
147
|
"plugin": ["@mc1global/opencode-jarvis"]
|
|
56
148
|
}
|
|
57
149
|
```
|
|
58
150
|
|
|
59
151
|
OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
|
|
60
152
|
|
|
61
|
-
|
|
153
|
+
#### Where exactly does `opencode.json` go?
|
|
154
|
+
|
|
155
|
+
OpenCode supports config files at **two levels**. Choose one (or both — they merge):
|
|
156
|
+
|
|
157
|
+
**Project-level** (recommended for teams):
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
/home/you/code/my-project/opencode.json # Linux/WSL
|
|
161
|
+
/Users/you/code/my-project/opencode.json # macOS
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
This is committed to git so your whole team gets the plugin. OpenCode looks for this file in the current directory or traverses up to the nearest git root.
|
|
165
|
+
|
|
166
|
+
**Global-level** (applies to ALL your projects):
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
~/.config/opencode/opencode.json # Linux/macOS/WSL
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Use this if you want JARVIS active on every project without adding `opencode.json` to each one.
|
|
173
|
+
|
|
174
|
+
> **Precedence:** Project config overrides global config for conflicting keys.
|
|
175
|
+
> Non-conflicting settings from both are merged. See the
|
|
176
|
+
> [OpenCode config docs](https://opencode.ai/docs/config#locations) for details.
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
### Step 3 — First launch (automatic)
|
|
62
181
|
|
|
63
182
|
Run `opencode` in your project directory. JARVIS initializes everything:
|
|
64
183
|
|
|
184
|
+
```bash
|
|
185
|
+
cd /path/to/your/project # must contain opencode.json (or have one globally)
|
|
186
|
+
opencode
|
|
65
187
|
```
|
|
66
|
-
What JARVIS creates automatically on first load:
|
|
67
188
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
189
|
+
On first load, JARVIS creates these files and directories automatically:
|
|
190
|
+
|
|
191
|
+
```
|
|
192
|
+
your-project/
|
|
193
|
+
.jarvis/ SQLite database + RAG indexes (local, gitignored)
|
|
194
|
+
config/jarvis.yaml Default configuration (commit this)
|
|
195
|
+
obsidian-vault/ Documentation skeleton (commit this)
|
|
196
|
+
AGENTS.md Agent operational guide (commit this)
|
|
72
197
|
```
|
|
73
198
|
|
|
74
199
|
On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
|
|
75
200
|
|
|
76
|
-
### 4
|
|
201
|
+
### Step 4 — First session recommended steps
|
|
77
202
|
|
|
78
203
|
The agent should run these on first use (JARVIS prompts automatically):
|
|
79
204
|
|
|
@@ -82,7 +207,7 @@ The agent should run these on first use (JARVIS prompts automatically):
|
|
|
82
207
|
3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
|
|
83
208
|
4. **`kanban-board-view`** tool — See the kanban board
|
|
84
209
|
|
|
85
|
-
### 5
|
|
210
|
+
### Step 5 — Verify your setup
|
|
86
211
|
|
|
87
212
|
The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
|
|
88
213
|
|
|
@@ -102,130 +227,108 @@ Summary: 6 pass, 2 warn, 0 fail (8 total)
|
|
|
102
227
|
Status: HEALTHY
|
|
103
228
|
```
|
|
104
229
|
|
|
105
|
-
|
|
230
|
+
---
|
|
106
231
|
|
|
107
|
-
|
|
232
|
+
## File Locations Reference
|
|
233
|
+
|
|
234
|
+
### In your project (committed to git, shared with team)
|
|
108
235
|
|
|
109
236
|
```
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
.opencode/commands/ Slash commands (/healthcheck, /sync-azure, /start-card)
|
|
237
|
+
your-project/
|
|
238
|
+
opencode.json Plugin declaration (Step 2 above)
|
|
239
|
+
config/jarvis.yaml Configuration (auto-created, then customized)
|
|
240
|
+
AGENTS.md Agent operational guide (auto-generated)
|
|
241
|
+
obsidian-vault/ Documentation vault
|
|
116
242
|
```
|
|
117
243
|
|
|
118
|
-
### Local per machine (NOT
|
|
244
|
+
### Local per machine (NOT committed — add to .gitignore)
|
|
119
245
|
|
|
120
246
|
```
|
|
121
|
-
|
|
122
|
-
.jarvis/
|
|
247
|
+
your-project/
|
|
248
|
+
.jarvis/jarvis.db SQLite: kanban, sessions, metrics, sync mappings
|
|
249
|
+
.jarvis/rag/ Vectra vector store (RAG embeddings)
|
|
123
250
|
```
|
|
124
251
|
|
|
125
|
-
### Global (shared across all projects)
|
|
252
|
+
### Global (shared across all your projects)
|
|
126
253
|
|
|
127
254
|
```
|
|
128
|
-
~/.
|
|
129
|
-
~/.
|
|
255
|
+
~/.config/opencode/opencode.json Global OpenCode config (optional)
|
|
256
|
+
~/.jarvis/registry.db Workspace registry (cross-project)
|
|
257
|
+
~/.cache/opencode/node_modules/ Plugin npm cache (managed by OpenCode)
|
|
130
258
|
```
|
|
131
259
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
### Skills (loaded on demand via `skill()` tool)
|
|
135
|
-
|
|
136
|
-
| Skill | Description |
|
|
137
|
-
|---|---|
|
|
138
|
-
| `jarvis-onboarding` | Setup, healthcheck, RAG indexing, tool reference |
|
|
139
|
-
| `jarvis-kanban` | Card lifecycle, grooming, sprints, gate tasks |
|
|
140
|
-
| `jarvis-azure-sync` | Azure DevOps push/pull/sync, PR creation |
|
|
141
|
-
|
|
142
|
-
### Commands (slash commands in any session)
|
|
260
|
+
---
|
|
143
261
|
|
|
144
|
-
|
|
145
|
-
|---|---|
|
|
146
|
-
| `/healthcheck` | Run diagnostics with actionable fix guidance |
|
|
147
|
-
| `/sync-azure` | Execute Azure DevOps sync workflow |
|
|
148
|
-
| `/start-card CD-XXX` | Start working on a kanban card (full lifecycle) |
|
|
262
|
+
## Setup Scripts
|
|
149
263
|
|
|
150
|
-
|
|
264
|
+
Automated setup scripts are available in the `scripts/setup/` directory of this repository. Each script installs all non-npm prerequisites for JARVIS (Bun, Ollama, embedding model) and optionally Azure CLI and Dagger:
|
|
151
265
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
cd jarvis-plugin
|
|
266
|
+
- **`scripts/setup/setup-macos.sh`** — macOS with Homebrew
|
|
267
|
+
- **`scripts/setup/setup-linux.sh`** — Ubuntu, Debian, Fedora, Arch Linux
|
|
268
|
+
- **`scripts/setup/setup-wsl.sh`** — Windows Subsystem for Linux (includes OpenCode CLI install + WSL detection)
|
|
156
269
|
|
|
157
|
-
|
|
158
|
-
npm install
|
|
270
|
+
Each script is interactive, checks for existing installations, and clearly reports what it does.
|
|
159
271
|
|
|
160
|
-
|
|
161
|
-
npm run build
|
|
272
|
+
---
|
|
162
273
|
|
|
163
|
-
|
|
164
|
-
{
|
|
165
|
-
"plugin": {
|
|
166
|
-
"jarvis": {
|
|
167
|
-
"path": "/path/to/jarvis-plugin"
|
|
168
|
-
}
|
|
169
|
-
}
|
|
170
|
-
}
|
|
171
|
-
```
|
|
274
|
+
## Available Commands
|
|
172
275
|
|
|
173
|
-
|
|
276
|
+
Commands are available in any OpenCode session:
|
|
174
277
|
|
|
175
|
-
|
|
278
|
+
- **`/healthcheck`** — Run diagnostics with actionable fix guidance
|
|
279
|
+
- **`/sync-azure`** — Execute Azure DevOps sync workflow
|
|
280
|
+
- **`/start-card CD-XXX`** — Start working on a kanban card (full lifecycle)
|
|
281
|
+
- **`/config`** — Agent-guided configuration wizard
|
|
176
282
|
|
|
177
|
-
|
|
178
|
-
bun run src/mcp-server.ts --directory /path/to/project
|
|
179
|
-
```
|
|
283
|
+
## Available Skills (loaded on demand via `skill()` tool)
|
|
180
284
|
|
|
181
|
-
|
|
285
|
+
- **`jarvis-kanban`** — Card lifecycle, grooming, sprints, gate tasks
|
|
286
|
+
- **`jarvis-azure-sync`** — Azure DevOps push/pull/sync, PR creation
|
|
287
|
+
- **`jarvis-onboarding`** — Setup, healthcheck, RAG indexing, tool reference
|
|
182
288
|
|
|
183
|
-
|
|
184
|
-
mcp-server:
|
|
185
|
-
transport: "stdio"
|
|
186
|
-
enabledTools: null # null = all tools, or list specific tool names
|
|
187
|
-
```
|
|
289
|
+
---
|
|
188
290
|
|
|
189
291
|
## Features
|
|
190
292
|
|
|
191
|
-
###
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
| **Event Handlers** | `event` | Token usage tracking and cross-context event handling |
|
|
293
|
+
### 115 Tools across 15 categories
|
|
294
|
+
|
|
295
|
+
- **Context Memory** (8) — `context-session-*`, `context-todo-*`, `context-note-*`, `context-search`
|
|
296
|
+
- **Kanban Cards** (12) — `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief`
|
|
297
|
+
- **Kanban Board** (15) — `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check`
|
|
298
|
+
- **Kanban Grooming** (4) — `kanban-grooming-validate`, `kanban-card-scope-doc/criteria/estimate`, `kanban-card-gate`
|
|
299
|
+
- **Governance** (2) — `governance-validate`, `governance-policies`
|
|
300
|
+
- **Token Metrics** (7) — `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate`
|
|
301
|
+
- **RAG** (8) — `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index`
|
|
302
|
+
- **Data** (3) — `data-yaml-get`, `data-json-get`, `data-csv-query`
|
|
303
|
+
- **Vault** (11) — `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage`
|
|
304
|
+
- **Agent** (8) — `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn`
|
|
305
|
+
- **Domain Map** (2) — `domain-map-analyze`, `domain-map-view`
|
|
306
|
+
- **Workspace** (4) — `workspace-info/list/update/link`
|
|
307
|
+
- **Environment** (6) — `env-init/create/list/status/merge/delete`
|
|
308
|
+
- **Pipeline** (10) — `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold`
|
|
309
|
+
- **Azure Sync** (10) — `azure-sync-*`, `azure-pr-*`
|
|
310
|
+
- **Bootstrap** (3) — `jarvis-bootstrap`, `jarvis-healthcheck`, `jarvis-terminal-commands`
|
|
311
|
+
|
|
312
|
+
### 8 Hooks
|
|
313
|
+
|
|
314
|
+
- **Context Compacting** — Injects session context when context window compacts
|
|
315
|
+
- **First-Run Guide** — Injects setup instructions on first session
|
|
316
|
+
- **Shell Environment** — Injects JARVIS env vars into shell sessions
|
|
317
|
+
- **Guardrails** — Governance policy enforcement on tool invocations
|
|
318
|
+
- **Event Handlers** — Token usage tracking and cross-context event handling
|
|
319
|
+
- **Execution Journal** — Crash recovery via tool execution state tracking
|
|
320
|
+
- **Slash Commands** — `/healthcheck`, `/sync-azure`, `/start-card`, `/config`
|
|
321
|
+
- **Config Command** — Agent-guided configuration editing
|
|
221
322
|
|
|
222
323
|
### 13 Governance Policies
|
|
223
324
|
|
|
224
325
|
Runtime-enforced via `tool.execute.before` hook. Covers: CSV/YAML/env file access, force push protection, SQLite CLI blocking, destructive shell ops, credential file protection, and more.
|
|
225
326
|
|
|
327
|
+
---
|
|
328
|
+
|
|
226
329
|
## Configuration
|
|
227
330
|
|
|
228
|
-
All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults
|
|
331
|
+
All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults:
|
|
229
332
|
|
|
230
333
|
```yaml
|
|
231
334
|
# RAG embedding settings
|
|
@@ -267,32 +370,35 @@ pipeline:
|
|
|
267
370
|
|
|
268
371
|
Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
|
|
269
372
|
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## MCP Server Mode
|
|
376
|
+
|
|
377
|
+
JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
bun run src/mcp-server.ts --directory /path/to/project
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
Configure tool filtering in `config/jarvis.yaml` under `mcp-server`.
|
|
384
|
+
|
|
385
|
+
---
|
|
386
|
+
|
|
270
387
|
## Architecture
|
|
271
388
|
|
|
272
389
|
```
|
|
273
390
|
jarvis-plugin/
|
|
274
391
|
src/
|
|
275
|
-
domain/
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
environment/ # Container-use environment management
|
|
286
|
-
agent-registry/ # Agent profile management
|
|
287
|
-
pipeline/ # CI/CD pipeline entities, gate enforcement
|
|
288
|
-
config/ # Configuration value objects + defaults
|
|
289
|
-
application/ # Use cases with DTOs (11 bounded contexts)
|
|
290
|
-
infrastructure/ # SQLite repos, Vectra, Ollama, FS adapters
|
|
291
|
-
tools/ # 20 tool modules (113 tools total)
|
|
292
|
-
hooks/ # 5 hooks (guardrails, compacting, first-run, events, shell-env)
|
|
293
|
-
tests/ # 2,520+ tests across 85 test suites
|
|
294
|
-
obsidian-vault/ # Structured documentation
|
|
295
|
-
config/ # jarvis.yaml configuration
|
|
392
|
+
domain/ Pure business logic, zero external deps (11 bounded contexts)
|
|
393
|
+
application/ Use cases with DTOs
|
|
394
|
+
infrastructure/ SQLite repos, Vectra, Ollama, FS adapters
|
|
395
|
+
tools/ 20 tool modules (115 tools total)
|
|
396
|
+
hooks/ 8 hooks
|
|
397
|
+
tests/ 2,670+ tests across 93 test suites
|
|
398
|
+
scripts/setup/ Per-OS automated setup scripts
|
|
399
|
+
obsidian-vault/ Structured documentation
|
|
400
|
+
config/ jarvis.yaml configuration
|
|
401
|
+
templates/ AGENTS.md template engine
|
|
296
402
|
```
|
|
297
403
|
|
|
298
404
|
**Key constraints:**
|
|
@@ -304,6 +410,8 @@ jarvis-plugin/
|
|
|
304
410
|
- 11 bounded contexts with strict DDD boundaries
|
|
305
411
|
- Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
|
|
306
412
|
|
|
413
|
+
---
|
|
414
|
+
|
|
307
415
|
## Storage
|
|
308
416
|
|
|
309
417
|
All data is stored locally:
|
|
@@ -313,30 +421,48 @@ All data is stored locally:
|
|
|
313
421
|
- `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
|
|
314
422
|
- `~/.jarvis/registry.db` — Central workspace registry (cross-project)
|
|
315
423
|
|
|
316
|
-
The `JARVIS_HOME` environment variable overrides `~/.jarvis/` default.
|
|
424
|
+
The `JARVIS_HOME` environment variable overrides the `~/.jarvis/` default.
|
|
425
|
+
|
|
426
|
+
---
|
|
317
427
|
|
|
318
|
-
## Development
|
|
428
|
+
## Local Development
|
|
319
429
|
|
|
320
430
|
```bash
|
|
431
|
+
# Clone
|
|
432
|
+
git clone <repo-url> jarvis-plugin
|
|
433
|
+
cd jarvis-plugin
|
|
434
|
+
|
|
435
|
+
# Install dependencies
|
|
436
|
+
npm install
|
|
437
|
+
|
|
438
|
+
# Build
|
|
439
|
+
npm run build
|
|
440
|
+
|
|
321
441
|
# Run all tests
|
|
322
442
|
npm test
|
|
323
443
|
|
|
324
444
|
# Type check (zero errors required)
|
|
325
445
|
npm run lint
|
|
326
446
|
|
|
327
|
-
# Build
|
|
328
|
-
npm run build
|
|
329
|
-
|
|
330
447
|
# Single test file
|
|
331
448
|
node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
|
|
332
449
|
|
|
333
450
|
# Watch mode
|
|
334
451
|
npm run dev
|
|
335
452
|
|
|
336
|
-
#
|
|
337
|
-
|
|
453
|
+
# Configure for local plugin development in OpenCode:
|
|
454
|
+
# Add to your project's opencode.json:
|
|
455
|
+
{
|
|
456
|
+
"plugin": {
|
|
457
|
+
"jarvis": {
|
|
458
|
+
"path": "/absolute/path/to/jarvis-plugin"
|
|
459
|
+
}
|
|
460
|
+
}
|
|
461
|
+
}
|
|
338
462
|
```
|
|
339
463
|
|
|
464
|
+
---
|
|
465
|
+
|
|
340
466
|
## Troubleshooting
|
|
341
467
|
|
|
342
468
|
**Ollama connection refused**
|
|
@@ -352,10 +478,17 @@ npx tsx scripts/rag-index.ts --clear
|
|
|
352
478
|
- Try full reindex: use `rag-index` tool with `clear: true`
|
|
353
479
|
|
|
354
480
|
**Plugin not loading in OpenCode**
|
|
355
|
-
- Verify `opencode.json`
|
|
481
|
+
- Verify `opencode.json` exists in your project root (or globally at `~/.config/opencode/opencode.json`)
|
|
482
|
+
- Verify it contains `"plugin": ["@mc1global/opencode-jarvis"]`
|
|
356
483
|
- Check `~/.cache/opencode/node_modules/` for the installed package
|
|
357
484
|
- Ensure Bun is installed (required for production runtime)
|
|
358
485
|
|
|
486
|
+
**Windows: Plugin not loading**
|
|
487
|
+
- JARVIS must run inside WSL, not native Windows PowerShell/cmd
|
|
488
|
+
- Install prerequisites inside WSL using `setup-wsl.sh`
|
|
489
|
+
- Run `opencode` from your WSL terminal
|
|
490
|
+
- See [OpenCode WSL docs](https://opencode.ai/docs/windows-wsl)
|
|
491
|
+
|
|
359
492
|
**MCP server fails to start**
|
|
360
493
|
- Ensure Bun is installed: `bun --version`
|
|
361
494
|
- Run manually: `bun run src/mcp-server.ts --directory .`
|
|
@@ -365,30 +498,20 @@ npx tsx scripts/rag-index.ts --clear
|
|
|
365
498
|
- Ensure Azure CLI is authenticated: `az login`
|
|
366
499
|
- Test connectivity: use `azure-sync-config` tool
|
|
367
500
|
|
|
368
|
-
|
|
369
|
-
- Remember: `exactOptionalPropertyTypes` requires conditional spreading for optional props
|
|
370
|
-
- Use `import type` for type-only imports (`verbatimModuleSyntax`)
|
|
371
|
-
- Array indexing returns `T | undefined` (`noUncheckedIndexedAccess`)
|
|
501
|
+
---
|
|
372
502
|
|
|
373
503
|
## Dependencies
|
|
374
504
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
## Test Coverage
|
|
387
|
-
|
|
388
|
-
- **2,520+ tests** across 85 test suites
|
|
389
|
-
- Domain, application, infrastructure, and tools layers tested
|
|
390
|
-
- In-memory SQLite for fast, isolated integration tests
|
|
391
|
-
- `tsc --noEmit` zero errors with all strict flags
|
|
505
|
+
- `bun:sqlite` — Local SQLite database (production)
|
|
506
|
+
- `better-sqlite3` — SQLite for tests (Node.js)
|
|
507
|
+
- `js-yaml` — YAML file parsing
|
|
508
|
+
- `vectra` — Local vector store for RAG
|
|
509
|
+
- `ollama` — Embedding generation via local Ollama
|
|
510
|
+
- `@langchain/textsplitters` — Code-aware text chunking for RAG
|
|
511
|
+
- `@opencode-ai/plugin` — OpenCode plugin SDK (peer dependency)
|
|
512
|
+
- `@modelcontextprotocol/sdk` — MCP server protocol (optional)
|
|
513
|
+
|
|
514
|
+
---
|
|
392
515
|
|
|
393
516
|
## License
|
|
394
517
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"first-run-guide.d.ts","sourceRoot":"","sources":["../../src/hooks/first-run-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;
|
|
1
|
+
{"version":3,"file":"first-run-guide.d.ts","sourceRoot":"","sources":["../../src/hooks/first-run-guide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,GACxB,CACD,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC7C,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,KACzB,OAAO,CAAC,IAAI,CAAC,CAoBjB"}
|