@shinobiapps/shinobi 0.1.2 → 0.1.4
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 +68 -11
- package/CODE_OF_CONDUCT.md +1 -1
- package/README.md +369 -271
- package/SECURITY.md +1 -1
- package/dist/cli.js +29 -24
- package/dist/cli.js.map +1 -1
- package/dist/commands/init.d.ts +2 -0
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +41 -21
- package/dist/commands/init.js.map +1 -1
- package/dist/dashboard/auth.js +5 -5
- package/dist/dashboard-spa/assets/{index-BiTX3zpZ.js → index-BgInVUB2.js} +2 -2
- package/dist/dashboard-spa/assets/{index-BiTX3zpZ.js.map → index-BgInVUB2.js.map} +1 -1
- package/dist/dashboard-spa/assets/index-h7KmljOs.css +1 -0
- package/dist/dashboard-spa/index.html +2 -2
- package/dist/lib/migrations.js +6 -6
- package/dist/lib/priority.js +6 -6
- package/dist/models/activity.js +2 -2
- package/dist/models/context.js +2 -2
- package/dist/models/dead_ends.js +11 -11
- package/dist/models/decisions.js +15 -15
- package/dist/models/notes.js +6 -6
- package/dist/models/plans.js +2 -2
- package/dist/models/projects.d.ts +2 -0
- package/dist/models/projects.d.ts.map +1 -1
- package/dist/models/projects.js +51 -24
- package/dist/models/projects.js.map +1 -1
- package/dist/models/sessions.js +23 -23
- package/dist/models/subtasks.js +19 -19
- package/dist/services/embedding/store.js +5 -5
- package/docs/architecture.md +108 -108
- package/docs/configuration.md +73 -73
- package/docs/plugin-development.md +104 -104
- package/docs/sponsorship.md +1 -1
- package/package.json +97 -97
- package/dist/dashboard-spa/assets/index-CrKsQshV.css +0 -1
package/docs/architecture.md
CHANGED
|
@@ -1,108 +1,108 @@
|
|
|
1
|
-
# Shinobi architecture
|
|
2
|
-
|
|
3
|
-
## Module layout
|
|
4
|
-
|
|
5
|
-
```
|
|
6
|
-
shinobi/
|
|
7
|
-
├── src/
|
|
8
|
-
│ ├── cli.ts — Top-level command dispatch
|
|
9
|
-
│ ├── commands/
|
|
10
|
-
│ │ ├── init.ts — `shinobi init`
|
|
11
|
-
│ │ └── sync.ts — `shinobi sync {init,push,pull,status}`
|
|
12
|
-
│ ├── lib/
|
|
13
|
-
│ │ ├── db.ts — better-sqlite3 singleton, WAL + FK + busy_timeout
|
|
14
|
-
│ │ ├── migrations.ts — Scan migrations/, sha256 checksum, apply pending
|
|
15
|
-
│ │ ├── config.ts — Read/write ~/.shinobi/config.json
|
|
16
|
-
│ │ ├── json.ts — parseJsonOrNull / stringifyOrNull
|
|
17
|
-
│ │ ├── fts.ts — escapeFtsQuery
|
|
18
|
-
│ │ └── priority.ts — Shared CASE expression for ORDER BY priority
|
|
19
|
-
│ ├── models/ — Functional, no classes. Each file exports interfaces + functions.
|
|
20
|
-
│ │ ├── projects.ts
|
|
21
|
-
│ │ ├── subtasks.ts — Includes nextTask (priority + dep resolution)
|
|
22
|
-
│ │ ├── decisions.ts
|
|
23
|
-
│ │ ├── dead_ends.ts
|
|
24
|
-
│ │ ├── notes.ts
|
|
25
|
-
│ │ ├── plans.ts — Auto-versioned saves
|
|
26
|
-
│ │ ├── context.ts — Patch semantics (only present fields overwrite)
|
|
27
|
-
│ │ ├── sessions.ts
|
|
28
|
-
│ │ ├── activity.ts — Includes linkCommit helper
|
|
29
|
-
│ │ └── *-helpers.ts — Hydration helpers extracted to avoid import cycles
|
|
30
|
-
│ ├── services/
|
|
31
|
-
│ │ ├── embedding/
|
|
32
|
-
│ │ │ ├── types.ts — EmbeddingProvider interface
|
|
33
|
-
│ │ │ ├── openai.ts — text-embedding-3-small (1536d default)
|
|
34
|
-
│ │ │ ├── voyage.ts — voyage-3-lite (512d default)
|
|
35
|
-
│ │ │ ├── ollama.ts — nomic-embed-text (768d default)
|
|
36
|
-
│ │ │ ├── factory.ts — Pick provider from env
|
|
37
|
-
│ │ │ ├── vector-math.ts — pack / unpack / cosineSim
|
|
38
|
-
│ │ │ └── store.ts — updateRowEmbedding / semanticSearch
|
|
39
|
-
│ │ └── plugins/
|
|
40
|
-
│ │ ├── state.ts — Loaded plugins registry (avoids import cycle)
|
|
41
|
-
│ │ ├── api.ts — Read-only ShinobiApi facade
|
|
42
|
-
│ │ ├── discovery.ts — Tier 1 (user dir) + Tier 2 (npm) scan
|
|
43
|
-
│ │ └── registry.ts — Validate + register plugin tools
|
|
44
|
-
│ ├── server/
|
|
45
|
-
│ │ ├── mcp.ts — Server boot, ListTools + CallTool handlers
|
|
46
|
-
│ │ └── tools/ — 37 tool definitions
|
|
47
|
-
│ │ ├── types.ts — ShinobiTool interface
|
|
48
|
-
│ │ ├── registry.ts — Global tool list + appendTool
|
|
49
|
-
│ │ ├── args.ts — Typed arg coercion
|
|
50
|
-
│ │ ├── index.ts — registerBuiltins (called at startup)
|
|
51
|
-
│ │ └── *.ts — One file per tool group
|
|
52
|
-
│ └── dashboard/
|
|
53
|
-
│ ├── server.ts — Hono app + routes
|
|
54
|
-
│ ├── layout.ts — Base HTML + embedded CSS / JS
|
|
55
|
-
│ └── views.ts — Per-view HTML generators
|
|
56
|
-
├── migrations/
|
|
57
|
-
│ ├── 0001_initial_schema.sql — 8 tables (projects, subtasks, decisions, dead_ends, notes, plans, context, sessions) + FTS5 mirrors
|
|
58
|
-
│ └── 0002_activity_and_links.sql — activity table + subtask embedding columns
|
|
59
|
-
├── scripts/ — Smoke test harnesses (not shipped in tarball)
|
|
60
|
-
└── dist/ — Compiled JS shipped via `npm pack`
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
## Request lifecycle (MCP)
|
|
64
|
-
|
|
65
|
-
```
|
|
66
|
-
MCP client (Claude Code) ─stdio─→ shinobi mcp
|
|
67
|
-
│
|
|
68
|
-
├─ applyPendingMigrations()
|
|
69
|
-
├─ registerBuiltins() ← 37 tool defs
|
|
70
|
-
├─ loadDiscoveredPlugins() ← scan ~/.shinobi/plugins + node_modules/@shinobi/plugin-*
|
|
71
|
-
│
|
|
72
|
-
└─ Server.connect(StdioServerTransport)
|
|
73
|
-
│
|
|
74
|
-
├─ ListToolsRequest → allTools() with schemas
|
|
75
|
-
└─ CallToolRequest → getTool(name).handler(args)
|
|
76
|
-
│
|
|
77
|
-
├─ Model write (sync, transactional)
|
|
78
|
-
├─ updateRowEmbedding (async, optional)
|
|
79
|
-
└─ recordActivity
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
## Request lifecycle (dashboard)
|
|
83
|
-
|
|
84
|
-
```
|
|
85
|
-
Browser → http://127.0.0.1:8765/<path>
|
|
86
|
-
│
|
|
87
|
-
└─ Hono router
|
|
88
|
-
├─ GET routes → model read → renderXxxView(...) → c.html(...)
|
|
89
|
-
└─ PATCH /api/* → model write → c.json(...)
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
The dashboard is the same Node process as the MCP server when launched together; today they are separate CLI subcommands (`shinobi mcp` vs `shinobi dashboard`) and each opens its own DB handle.
|
|
93
|
-
|
|
94
|
-
## Storage
|
|
95
|
-
|
|
96
|
-
SQLite via better-sqlite3. WAL mode + foreign_keys ON + busy_timeout 5000ms. Migrations are forward-only with sha256 checksum tracking — if an applied migration file changes content, the runner halts with a `mismatched` count.
|
|
97
|
-
|
|
98
|
-
FTS5 mirrors live alongside their base tables (`subtasks_fts`, `decisions_fts`, `dead_ends_fts`, `notes_fts`) with `ai`/`ad`/`au` triggers keeping them synchronized. Searches use `MATCH` against the FTS5 table and JOIN back to the base table by rowid.
|
|
99
|
-
|
|
100
|
-
Embeddings live in BLOB columns (`embedding`, `embedding_provider`, `embedding_dims`) on `decisions`, `dead_ends`, `notes`, and `subtasks`. The provider name is stored alongside so a switch in provider (different dimensions) doesn't produce silent comparison errors.
|
|
101
|
-
|
|
102
|
-
## Sync model
|
|
103
|
-
|
|
104
|
-
`shinobi sync push` does `wal_checkpoint(TRUNCATE)` + `db.backup()` + git add+commit+push. `shinobi sync pull` does git pull + file copy back. There is no merge; the writer is whichever machine pushed last. For multi-writer scenarios, consider holding off on `pull` while another machine is mid-edit.
|
|
105
|
-
|
|
106
|
-
## Plugin contract
|
|
107
|
-
|
|
108
|
-
A plugin is an ES module that exports `default` (or `register`) accepting `(registry, api)`. The `api` is a read-only facade — plugins can read projects/subtasks/decisions but cannot mutate state. Plugin tools must use the `plugin_*` prefix to avoid colliding with built-ins.
|
|
1
|
+
# Shinobi architecture
|
|
2
|
+
|
|
3
|
+
## Module layout
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
shinobi/
|
|
7
|
+
├── src/
|
|
8
|
+
│ ├── cli.ts — Top-level command dispatch
|
|
9
|
+
│ ├── commands/
|
|
10
|
+
│ │ ├── init.ts — `shinobi init`
|
|
11
|
+
│ │ └── sync.ts — `shinobi sync {init,push,pull,status}`
|
|
12
|
+
│ ├── lib/
|
|
13
|
+
│ │ ├── db.ts — better-sqlite3 singleton, WAL + FK + busy_timeout
|
|
14
|
+
│ │ ├── migrations.ts — Scan migrations/, sha256 checksum, apply pending
|
|
15
|
+
│ │ ├── config.ts — Read/write ~/.shinobi/config.json
|
|
16
|
+
│ │ ├── json.ts — parseJsonOrNull / stringifyOrNull
|
|
17
|
+
│ │ ├── fts.ts — escapeFtsQuery
|
|
18
|
+
│ │ └── priority.ts — Shared CASE expression for ORDER BY priority
|
|
19
|
+
│ ├── models/ — Functional, no classes. Each file exports interfaces + functions.
|
|
20
|
+
│ │ ├── projects.ts
|
|
21
|
+
│ │ ├── subtasks.ts — Includes nextTask (priority + dep resolution)
|
|
22
|
+
│ │ ├── decisions.ts
|
|
23
|
+
│ │ ├── dead_ends.ts
|
|
24
|
+
│ │ ├── notes.ts
|
|
25
|
+
│ │ ├── plans.ts — Auto-versioned saves
|
|
26
|
+
│ │ ├── context.ts — Patch semantics (only present fields overwrite)
|
|
27
|
+
│ │ ├── sessions.ts
|
|
28
|
+
│ │ ├── activity.ts — Includes linkCommit helper
|
|
29
|
+
│ │ └── *-helpers.ts — Hydration helpers extracted to avoid import cycles
|
|
30
|
+
│ ├── services/
|
|
31
|
+
│ │ ├── embedding/
|
|
32
|
+
│ │ │ ├── types.ts — EmbeddingProvider interface
|
|
33
|
+
│ │ │ ├── openai.ts — text-embedding-3-small (1536d default)
|
|
34
|
+
│ │ │ ├── voyage.ts — voyage-3-lite (512d default)
|
|
35
|
+
│ │ │ ├── ollama.ts — nomic-embed-text (768d default)
|
|
36
|
+
│ │ │ ├── factory.ts — Pick provider from env
|
|
37
|
+
│ │ │ ├── vector-math.ts — pack / unpack / cosineSim
|
|
38
|
+
│ │ │ └── store.ts — updateRowEmbedding / semanticSearch
|
|
39
|
+
│ │ └── plugins/
|
|
40
|
+
│ │ ├── state.ts — Loaded plugins registry (avoids import cycle)
|
|
41
|
+
│ │ ├── api.ts — Read-only ShinobiApi facade
|
|
42
|
+
│ │ ├── discovery.ts — Tier 1 (user dir) + Tier 2 (npm) scan
|
|
43
|
+
│ │ └── registry.ts — Validate + register plugin tools
|
|
44
|
+
│ ├── server/
|
|
45
|
+
│ │ ├── mcp.ts — Server boot, ListTools + CallTool handlers
|
|
46
|
+
│ │ └── tools/ — 37 tool definitions
|
|
47
|
+
│ │ ├── types.ts — ShinobiTool interface
|
|
48
|
+
│ │ ├── registry.ts — Global tool list + appendTool
|
|
49
|
+
│ │ ├── args.ts — Typed arg coercion
|
|
50
|
+
│ │ ├── index.ts — registerBuiltins (called at startup)
|
|
51
|
+
│ │ └── *.ts — One file per tool group
|
|
52
|
+
│ └── dashboard/
|
|
53
|
+
│ ├── server.ts — Hono app + routes
|
|
54
|
+
│ ├── layout.ts — Base HTML + embedded CSS / JS
|
|
55
|
+
│ └── views.ts — Per-view HTML generators
|
|
56
|
+
├── migrations/
|
|
57
|
+
│ ├── 0001_initial_schema.sql — 8 tables (projects, subtasks, decisions, dead_ends, notes, plans, context, sessions) + FTS5 mirrors
|
|
58
|
+
│ └── 0002_activity_and_links.sql — activity table + subtask embedding columns
|
|
59
|
+
├── scripts/ — Smoke test harnesses (not shipped in tarball)
|
|
60
|
+
└── dist/ — Compiled JS shipped via `npm pack`
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Request lifecycle (MCP)
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
MCP client (Claude Code) ─stdio─→ shinobi mcp
|
|
67
|
+
│
|
|
68
|
+
├─ applyPendingMigrations()
|
|
69
|
+
├─ registerBuiltins() ← 37 tool defs
|
|
70
|
+
├─ loadDiscoveredPlugins() ← scan ~/.shinobi/plugins + node_modules/@shinobi/plugin-*
|
|
71
|
+
│
|
|
72
|
+
└─ Server.connect(StdioServerTransport)
|
|
73
|
+
│
|
|
74
|
+
├─ ListToolsRequest → allTools() with schemas
|
|
75
|
+
└─ CallToolRequest → getTool(name).handler(args)
|
|
76
|
+
│
|
|
77
|
+
├─ Model write (sync, transactional)
|
|
78
|
+
├─ updateRowEmbedding (async, optional)
|
|
79
|
+
└─ recordActivity
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Request lifecycle (dashboard)
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
Browser → http://127.0.0.1:8765/<path>
|
|
86
|
+
│
|
|
87
|
+
└─ Hono router
|
|
88
|
+
├─ GET routes → model read → renderXxxView(...) → c.html(...)
|
|
89
|
+
└─ PATCH /api/* → model write → c.json(...)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
The dashboard is the same Node process as the MCP server when launched together; today they are separate CLI subcommands (`shinobi mcp` vs `shinobi dashboard`) and each opens its own DB handle.
|
|
93
|
+
|
|
94
|
+
## Storage
|
|
95
|
+
|
|
96
|
+
SQLite via better-sqlite3. WAL mode + foreign_keys ON + busy_timeout 5000ms. Migrations are forward-only with sha256 checksum tracking — if an applied migration file changes content, the runner halts with a `mismatched` count.
|
|
97
|
+
|
|
98
|
+
FTS5 mirrors live alongside their base tables (`subtasks_fts`, `decisions_fts`, `dead_ends_fts`, `notes_fts`) with `ai`/`ad`/`au` triggers keeping them synchronized. Searches use `MATCH` against the FTS5 table and JOIN back to the base table by rowid.
|
|
99
|
+
|
|
100
|
+
Embeddings live in BLOB columns (`embedding`, `embedding_provider`, `embedding_dims`) on `decisions`, `dead_ends`, `notes`, and `subtasks`. The provider name is stored alongside so a switch in provider (different dimensions) doesn't produce silent comparison errors.
|
|
101
|
+
|
|
102
|
+
## Sync model
|
|
103
|
+
|
|
104
|
+
`shinobi sync push` does `wal_checkpoint(TRUNCATE)` + `db.backup()` + git add+commit+push. `shinobi sync pull` does git pull + file copy back. There is no merge; the writer is whichever machine pushed last. For multi-writer scenarios, consider holding off on `pull` while another machine is mid-edit.
|
|
105
|
+
|
|
106
|
+
## Plugin contract
|
|
107
|
+
|
|
108
|
+
A plugin is an ES module that exports `default` (or `register`) accepting `(registry, api)`. The `api` is a read-only facade — plugins can read projects/subtasks/decisions but cannot mutate state. Plugin tools must use the `plugin_*` prefix to avoid colliding with built-ins.
|
package/docs/configuration.md
CHANGED
|
@@ -1,73 +1,73 @@
|
|
|
1
|
-
# Shinobi configuration
|
|
2
|
-
|
|
3
|
-
All configuration is via environment variables. `~/.shinobi/.env` is loaded automatically by the CLI; values in `process.env` take precedence.
|
|
4
|
-
|
|
5
|
-
## Storage
|
|
6
|
-
|
|
7
|
-
| Variable | Default | Purpose |
|
|
8
|
-
|---|---|---|
|
|
9
|
-
| `SHINOBI_DB_PATH` | `~/.shinobi/shinobi.db` | SQLite file. WAL mode is enforced; the directory is created if missing. |
|
|
10
|
-
| `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Where `config.json` and `.env` live. The default plugins directory is also derived from this. |
|
|
11
|
-
| `SHINOBI_MIGRATIONS_DIR` | `<package>/migrations` | Override the migrations source. Useful only for dev / testing. |
|
|
12
|
-
|
|
13
|
-
## Dashboard
|
|
14
|
-
|
|
15
|
-
| Variable | Default | Purpose |
|
|
16
|
-
|---|---|---|
|
|
17
|
-
| `SHINOBI_DASHBOARD_PORT` | `8765` | Dashboard HTTP port. |
|
|
18
|
-
| `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Bind host. Loopback (`127.0.0.1`, `localhost`, `::1`) skips auth; anything else (e.g. `0.0.0.0` for LAN access) auto-enables token auth. |
|
|
19
|
-
| `SHINOBI_DASHBOARD_TOKEN` | _(none)_ | Override the dashboard auth token. When unset and a non-loopback host is used, a token is auto-generated and persisted to `~/.shinobi/dashboard-token`. |
|
|
20
|
-
|
|
21
|
-
### Auth flow (non-loopback only)
|
|
22
|
-
|
|
23
|
-
When the dashboard binds to a non-loopback host, every route except `GET /health` requires a token. Accepted credential locations, checked in order:
|
|
24
|
-
|
|
25
|
-
1. `Authorization: Bearer <token>` header
|
|
26
|
-
2. `X-Shinobi-Token: <token>` header
|
|
27
|
-
3. `shinobi_token` cookie (set automatically after a successful `?token=` query)
|
|
28
|
-
4. `?token=<token>` query string — used once, the response sets the cookie
|
|
29
|
-
|
|
30
|
-
Loopback binds skip the middleware entirely so local development stays zero-friction. The token file is created with `0600` permissions on POSIX systems.
|
|
31
|
-
|
|
32
|
-
## Plugins
|
|
33
|
-
|
|
34
|
-
| Variable | Default | Purpose |
|
|
35
|
-
|---|---|---|
|
|
36
|
-
| `SHINOBI_PLUGINS_DIR` | `~/.shinobi/plugins` | Directory scanned for user-tier plugins (`.js` / `.mjs` files). |
|
|
37
|
-
|
|
38
|
-
Npm-tier plugins are discovered from `node_modules/@shinobi/plugin-*` in the current working directory at server start.
|
|
39
|
-
|
|
40
|
-
## Embeddings (optional)
|
|
41
|
-
|
|
42
|
-
Shinobi falls back to FTS5 fulltext search by default. Configure a provider to enable semantic recall.
|
|
43
|
-
|
|
44
|
-
| Variable | Values | Default |
|
|
45
|
-
|---|---|---|
|
|
46
|
-
| `SHINOBI_EMBED_PROVIDER` | `openai` / `voyage` / `ollama` / `none` | `none` |
|
|
47
|
-
| `SHINOBI_EMBED_API_KEY` | provider auth token | falls back to `OPENAI_API_KEY` / `VOYAGE_API_KEY` |
|
|
48
|
-
| `SHINOBI_EMBED_MODEL` | model identifier | `text-embedding-3-small` (OpenAI) / `voyage-3-lite` (Voyage) / `nomic-embed-text` (Ollama) |
|
|
49
|
-
| `SHINOBI_EMBED_DIMS` | integer | `1536` (OpenAI) / `512` (Voyage) / `768` (Ollama) |
|
|
50
|
-
| `SHINOBI_OLLAMA_URL` | URL | `http://localhost:11434` |
|
|
51
|
-
|
|
52
|
-
When a provider is configured, write paths (`log_decision`, `log_dead_end`, `add_note`, `create_task`, `bulk_create_tasks`) generate and store embeddings synchronously after the row insert. Read paths (`recall`, `check_dead_ends`) prefer semantic match and fall back to FTS5 when no embedding is available.
|
|
53
|
-
|
|
54
|
-
## Recall mode
|
|
55
|
-
|
|
56
|
-
`recall` accepts an optional `mode` argument: `auto` (default), `semantic`, or `fulltext`. The `auto` mode picks semantic when an embedding provider is configured, otherwise fulltext.
|
|
57
|
-
|
|
58
|
-
## Sync
|
|
59
|
-
|
|
60
|
-
Configured per machine via `shinobi sync init`. The resulting `~/.shinobi/config.json` shape:
|
|
61
|
-
|
|
62
|
-
```json
|
|
63
|
-
{
|
|
64
|
-
"sync": {
|
|
65
|
-
"repo_path": "/path/to/local/clone",
|
|
66
|
-
"branch": "main",
|
|
67
|
-
"last_push_at": "2026-05-23T16:30:00.000Z",
|
|
68
|
-
"last_pull_at": null
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
There is no env override for sync paths — use `shinobi sync init <path> [branch]` to reconfigure.
|
|
1
|
+
# Shinobi configuration
|
|
2
|
+
|
|
3
|
+
All configuration is via environment variables. `~/.shinobi/.env` is loaded automatically by the CLI; values in `process.env` take precedence.
|
|
4
|
+
|
|
5
|
+
## Storage
|
|
6
|
+
|
|
7
|
+
| Variable | Default | Purpose |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `SHINOBI_DB_PATH` | `~/.shinobi/shinobi.db` | SQLite file. WAL mode is enforced; the directory is created if missing. |
|
|
10
|
+
| `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Where `config.json` and `.env` live. The default plugins directory is also derived from this. |
|
|
11
|
+
| `SHINOBI_MIGRATIONS_DIR` | `<package>/migrations` | Override the migrations source. Useful only for dev / testing. |
|
|
12
|
+
|
|
13
|
+
## Dashboard
|
|
14
|
+
|
|
15
|
+
| Variable | Default | Purpose |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `SHINOBI_DASHBOARD_PORT` | `8765` | Dashboard HTTP port. |
|
|
18
|
+
| `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Bind host. Loopback (`127.0.0.1`, `localhost`, `::1`) skips auth; anything else (e.g. `0.0.0.0` for LAN access) auto-enables token auth. |
|
|
19
|
+
| `SHINOBI_DASHBOARD_TOKEN` | _(none)_ | Override the dashboard auth token. When unset and a non-loopback host is used, a token is auto-generated and persisted to `~/.shinobi/dashboard-token`. |
|
|
20
|
+
|
|
21
|
+
### Auth flow (non-loopback only)
|
|
22
|
+
|
|
23
|
+
When the dashboard binds to a non-loopback host, every route except `GET /health` requires a token. Accepted credential locations, checked in order:
|
|
24
|
+
|
|
25
|
+
1. `Authorization: Bearer <token>` header
|
|
26
|
+
2. `X-Shinobi-Token: <token>` header
|
|
27
|
+
3. `shinobi_token` cookie (set automatically after a successful `?token=` query)
|
|
28
|
+
4. `?token=<token>` query string — used once, the response sets the cookie
|
|
29
|
+
|
|
30
|
+
Loopback binds skip the middleware entirely so local development stays zero-friction. The token file is created with `0600` permissions on POSIX systems.
|
|
31
|
+
|
|
32
|
+
## Plugins
|
|
33
|
+
|
|
34
|
+
| Variable | Default | Purpose |
|
|
35
|
+
|---|---|---|
|
|
36
|
+
| `SHINOBI_PLUGINS_DIR` | `~/.shinobi/plugins` | Directory scanned for user-tier plugins (`.js` / `.mjs` files). |
|
|
37
|
+
|
|
38
|
+
Npm-tier plugins are discovered from `node_modules/@shinobi/plugin-*` in the current working directory at server start.
|
|
39
|
+
|
|
40
|
+
## Embeddings (optional)
|
|
41
|
+
|
|
42
|
+
Shinobi falls back to FTS5 fulltext search by default. Configure a provider to enable semantic recall.
|
|
43
|
+
|
|
44
|
+
| Variable | Values | Default |
|
|
45
|
+
|---|---|---|
|
|
46
|
+
| `SHINOBI_EMBED_PROVIDER` | `openai` / `voyage` / `ollama` / `none` | `none` |
|
|
47
|
+
| `SHINOBI_EMBED_API_KEY` | provider auth token | falls back to `OPENAI_API_KEY` / `VOYAGE_API_KEY` |
|
|
48
|
+
| `SHINOBI_EMBED_MODEL` | model identifier | `text-embedding-3-small` (OpenAI) / `voyage-3-lite` (Voyage) / `nomic-embed-text` (Ollama) |
|
|
49
|
+
| `SHINOBI_EMBED_DIMS` | integer | `1536` (OpenAI) / `512` (Voyage) / `768` (Ollama) |
|
|
50
|
+
| `SHINOBI_OLLAMA_URL` | URL | `http://localhost:11434` |
|
|
51
|
+
|
|
52
|
+
When a provider is configured, write paths (`log_decision`, `log_dead_end`, `add_note`, `create_task`, `bulk_create_tasks`) generate and store embeddings synchronously after the row insert. Read paths (`recall`, `check_dead_ends`) prefer semantic match and fall back to FTS5 when no embedding is available.
|
|
53
|
+
|
|
54
|
+
## Recall mode
|
|
55
|
+
|
|
56
|
+
`recall` accepts an optional `mode` argument: `auto` (default), `semantic`, or `fulltext`. The `auto` mode picks semantic when an embedding provider is configured, otherwise fulltext.
|
|
57
|
+
|
|
58
|
+
## Sync
|
|
59
|
+
|
|
60
|
+
Configured per machine via `shinobi sync init`. The resulting `~/.shinobi/config.json` shape:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"sync": {
|
|
65
|
+
"repo_path": "/path/to/local/clone",
|
|
66
|
+
"branch": "main",
|
|
67
|
+
"last_push_at": "2026-05-23T16:30:00.000Z",
|
|
68
|
+
"last_pull_at": null
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
There is no env override for sync paths — use `shinobi sync init <path> [branch]` to reconfigure.
|
|
@@ -1,104 +1,104 @@
|
|
|
1
|
-
# Writing a Shinobi plugin
|
|
2
|
-
|
|
3
|
-
Plugins extend the MCP tool surface without modifying the Shinobi source. They run inside the same Node process and have read-only access to the database via the `ShinobiApi` facade.
|
|
4
|
-
|
|
5
|
-
## Quick start
|
|
6
|
-
|
|
7
|
-
Create a file in `~/.shinobi/plugins/` (or wherever `SHINOBI_PLUGINS_DIR` points):
|
|
8
|
-
|
|
9
|
-
```js
|
|
10
|
-
// ~/.shinobi/plugins/hello-world.js
|
|
11
|
-
export default function register(registry, api) {
|
|
12
|
-
registry.registerTool({
|
|
13
|
-
name: 'plugin_hello_world',
|
|
14
|
-
description: 'Echo a friendly message',
|
|
15
|
-
inputSchema: {
|
|
16
|
-
type: 'object',
|
|
17
|
-
properties: {
|
|
18
|
-
name: { type: 'string' },
|
|
19
|
-
},
|
|
20
|
-
required: ['name'],
|
|
21
|
-
additionalProperties: false,
|
|
22
|
-
},
|
|
23
|
-
handler: (args) => ({ greeting: `Hello, ${args.name}!` }),
|
|
24
|
-
});
|
|
25
|
-
}
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Restart your MCP client and `mcp__shinobi__plugin_hello_world` is available.
|
|
29
|
-
|
|
30
|
-
## Naming
|
|
31
|
-
|
|
32
|
-
Plugin tools MUST match `/^plugin_[a-z][a-z0-9_]*$/`. Names without the `plugin_` prefix are rejected at registration time.
|
|
33
|
-
|
|
34
|
-
## The `api` facade
|
|
35
|
-
|
|
36
|
-
The second argument to `register` and to every handler call (when you pass it through) is a read-only facade. Available methods:
|
|
37
|
-
|
|
38
|
-
```ts
|
|
39
|
-
listProjects(opts?: { includeArchived?: boolean; status?: Status }): Project[]
|
|
40
|
-
getProject(id: number): Project | null
|
|
41
|
-
projectsMatchingTargetPath(filePath: string): Project[]
|
|
42
|
-
|
|
43
|
-
listSubtasks(opts?: { projectId?: number; status?: Status; sessionId?: string }): Subtask[]
|
|
44
|
-
getSubtask(id: number): Subtask | null
|
|
45
|
-
searchSubtasks(query: string, projectId?: number, limit?: number): Subtask[]
|
|
46
|
-
|
|
47
|
-
searchDecisions(query: string, projectId?: number, limit?: number): Decision[]
|
|
48
|
-
listDecisions(opts?: ListDecisionsOptions): Decision[]
|
|
49
|
-
|
|
50
|
-
checkDeadEnds(input: { approach: string; files?: string[]; projectId?: number; limit?: number }): DeadEnd[]
|
|
51
|
-
listDeadEnds(opts?: { projectId?: number; limit?: number }): DeadEnd[]
|
|
52
|
-
|
|
53
|
-
searchNotes(query: string, projectId?: number, limit?: number): Note[]
|
|
54
|
-
listNotes(opts?: { projectId?: number; limit?: number }): Note[]
|
|
55
|
-
|
|
56
|
-
getContext(projectId: number): Context | null
|
|
57
|
-
listActivity(opts?: ListActivityOptions): ActivityRow[]
|
|
58
|
-
|
|
59
|
-
getProjectSnapshot(projectId: number): {
|
|
60
|
-
project: Project | null;
|
|
61
|
-
subtasks: Subtask[];
|
|
62
|
-
recent_decisions: Decision[];
|
|
63
|
-
recent_dead_ends: DeadEnd[];
|
|
64
|
-
context: Context | null;
|
|
65
|
-
}
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
Plugins cannot directly mutate state. If you need writes, return a description of what to write and have the LLM call a built-in tool.
|
|
69
|
-
|
|
70
|
-
## Async handlers
|
|
71
|
-
|
|
72
|
-
Handlers may be async. Throw on invalid input; the MCP server catches and returns `isError: true` to the client.
|
|
73
|
-
|
|
74
|
-
```js
|
|
75
|
-
export default function register(registry, api) {
|
|
76
|
-
registry.registerTool({
|
|
77
|
-
name: 'plugin_fetch_stuff',
|
|
78
|
-
description: 'Fetch from an external API',
|
|
79
|
-
inputSchema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
|
|
80
|
-
handler: async (args) => {
|
|
81
|
-
const r = await fetch(args.url);
|
|
82
|
-
if (!r.ok) throw new Error(`http ${r.status}`);
|
|
83
|
-
return await r.json();
|
|
84
|
-
},
|
|
85
|
-
});
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
## Npm-tier plugins
|
|
90
|
-
|
|
91
|
-
Plugins can be published as npm packages with the name pattern `@shinobi/plugin-*`. Shinobi scans `node_modules/@shinobi/` in the CWD at start. Your `package.json` should set `"main"` (or `"exports.\".\".import"`) to a module that exports `default` matching the same register signature.
|
|
92
|
-
|
|
93
|
-
## Verifying a plugin loaded
|
|
94
|
-
|
|
95
|
-
Call `mcp__shinobi__plugin_hello` from your MCP client. It returns the list of discovered plugins with their registered tool names and any load errors.
|
|
96
|
-
|
|
97
|
-
## Failure modes
|
|
98
|
-
|
|
99
|
-
- **No default export** — the plugin file loads but contributes nothing; `plugin_hello` reports `error: "no default/register export"`.
|
|
100
|
-
- **Throwing register** — the plugin's tools are not registered; the throw is captured to `error`.
|
|
101
|
-
- **Name collision** — registration throws synchronously; surface in `plugin_hello`.
|
|
102
|
-
- **Bad inputSchema** — accepted at registration; only fails at call time when MCP validates.
|
|
103
|
-
|
|
104
|
-
Plugins do not impede built-in tool availability — a broken plugin leaves the built-ins intact.
|
|
1
|
+
# Writing a Shinobi plugin
|
|
2
|
+
|
|
3
|
+
Plugins extend the MCP tool surface without modifying the Shinobi source. They run inside the same Node process and have read-only access to the database via the `ShinobiApi` facade.
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
Create a file in `~/.shinobi/plugins/` (or wherever `SHINOBI_PLUGINS_DIR` points):
|
|
8
|
+
|
|
9
|
+
```js
|
|
10
|
+
// ~/.shinobi/plugins/hello-world.js
|
|
11
|
+
export default function register(registry, api) {
|
|
12
|
+
registry.registerTool({
|
|
13
|
+
name: 'plugin_hello_world',
|
|
14
|
+
description: 'Echo a friendly message',
|
|
15
|
+
inputSchema: {
|
|
16
|
+
type: 'object',
|
|
17
|
+
properties: {
|
|
18
|
+
name: { type: 'string' },
|
|
19
|
+
},
|
|
20
|
+
required: ['name'],
|
|
21
|
+
additionalProperties: false,
|
|
22
|
+
},
|
|
23
|
+
handler: (args) => ({ greeting: `Hello, ${args.name}!` }),
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Restart your MCP client and `mcp__shinobi__plugin_hello_world` is available.
|
|
29
|
+
|
|
30
|
+
## Naming
|
|
31
|
+
|
|
32
|
+
Plugin tools MUST match `/^plugin_[a-z][a-z0-9_]*$/`. Names without the `plugin_` prefix are rejected at registration time.
|
|
33
|
+
|
|
34
|
+
## The `api` facade
|
|
35
|
+
|
|
36
|
+
The second argument to `register` and to every handler call (when you pass it through) is a read-only facade. Available methods:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
listProjects(opts?: { includeArchived?: boolean; status?: Status }): Project[]
|
|
40
|
+
getProject(id: number): Project | null
|
|
41
|
+
projectsMatchingTargetPath(filePath: string): Project[]
|
|
42
|
+
|
|
43
|
+
listSubtasks(opts?: { projectId?: number; status?: Status; sessionId?: string }): Subtask[]
|
|
44
|
+
getSubtask(id: number): Subtask | null
|
|
45
|
+
searchSubtasks(query: string, projectId?: number, limit?: number): Subtask[]
|
|
46
|
+
|
|
47
|
+
searchDecisions(query: string, projectId?: number, limit?: number): Decision[]
|
|
48
|
+
listDecisions(opts?: ListDecisionsOptions): Decision[]
|
|
49
|
+
|
|
50
|
+
checkDeadEnds(input: { approach: string; files?: string[]; projectId?: number; limit?: number }): DeadEnd[]
|
|
51
|
+
listDeadEnds(opts?: { projectId?: number; limit?: number }): DeadEnd[]
|
|
52
|
+
|
|
53
|
+
searchNotes(query: string, projectId?: number, limit?: number): Note[]
|
|
54
|
+
listNotes(opts?: { projectId?: number; limit?: number }): Note[]
|
|
55
|
+
|
|
56
|
+
getContext(projectId: number): Context | null
|
|
57
|
+
listActivity(opts?: ListActivityOptions): ActivityRow[]
|
|
58
|
+
|
|
59
|
+
getProjectSnapshot(projectId: number): {
|
|
60
|
+
project: Project | null;
|
|
61
|
+
subtasks: Subtask[];
|
|
62
|
+
recent_decisions: Decision[];
|
|
63
|
+
recent_dead_ends: DeadEnd[];
|
|
64
|
+
context: Context | null;
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Plugins cannot directly mutate state. If you need writes, return a description of what to write and have the LLM call a built-in tool.
|
|
69
|
+
|
|
70
|
+
## Async handlers
|
|
71
|
+
|
|
72
|
+
Handlers may be async. Throw on invalid input; the MCP server catches and returns `isError: true` to the client.
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
export default function register(registry, api) {
|
|
76
|
+
registry.registerTool({
|
|
77
|
+
name: 'plugin_fetch_stuff',
|
|
78
|
+
description: 'Fetch from an external API',
|
|
79
|
+
inputSchema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
|
|
80
|
+
handler: async (args) => {
|
|
81
|
+
const r = await fetch(args.url);
|
|
82
|
+
if (!r.ok) throw new Error(`http ${r.status}`);
|
|
83
|
+
return await r.json();
|
|
84
|
+
},
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Npm-tier plugins
|
|
90
|
+
|
|
91
|
+
Plugins can be published as npm packages with the name pattern `@shinobi/plugin-*`. Shinobi scans `node_modules/@shinobi/` in the CWD at start. Your `package.json` should set `"main"` (or `"exports.\".\".import"`) to a module that exports `default` matching the same register signature.
|
|
92
|
+
|
|
93
|
+
## Verifying a plugin loaded
|
|
94
|
+
|
|
95
|
+
Call `mcp__shinobi__plugin_hello` from your MCP client. It returns the list of discovered plugins with their registered tool names and any load errors.
|
|
96
|
+
|
|
97
|
+
## Failure modes
|
|
98
|
+
|
|
99
|
+
- **No default export** — the plugin file loads but contributes nothing; `plugin_hello` reports `error: "no default/register export"`.
|
|
100
|
+
- **Throwing register** — the plugin's tools are not registered; the throw is captured to `error`.
|
|
101
|
+
- **Name collision** — registration throws synchronously; surface in `plugin_hello`.
|
|
102
|
+
- **Bad inputSchema** — accepted at registration; only fails at call time when MCP validates.
|
|
103
|
+
|
|
104
|
+
Plugins do not impede built-in tool availability — a broken plugin leaves the built-ins intact.
|
package/docs/sponsorship.md
CHANGED
|
@@ -45,7 +45,7 @@ Different value props, no overlap.
|
|
|
45
45
|
|
|
46
46
|
## How to apply for the free OSS-project tier
|
|
47
47
|
|
|
48
|
-
Email contact@shinobi-apps.
|
|
48
|
+
Email contact@shinobi-apps.com with:
|
|
49
49
|
- The repo URL
|
|
50
50
|
- Brief description of the project
|
|
51
51
|
- How you'd use Shinobi in your workflow
|