@shinobiapps/shinobi 0.1.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/CHANGELOG.md +70 -0
- package/CODE_OF_CONDUCT.md +70 -0
- package/LICENSE +21 -0
- package/README.md +269 -0
- package/SECURITY.md +75 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.d.ts.map +1 -0
- package/dist/cli.js +200 -0
- package/dist/cli.js.map +1 -0
- package/dist/commands/cost.d.ts +9 -0
- package/dist/commands/cost.d.ts.map +1 -0
- package/dist/commands/cost.js +49 -0
- package/dist/commands/cost.js.map +1 -0
- package/dist/commands/digest.d.ts +29 -0
- package/dist/commands/digest.d.ts.map +1 -0
- package/dist/commands/digest.js +63 -0
- package/dist/commands/digest.js.map +1 -0
- package/dist/commands/init.d.ts +15 -0
- package/dist/commands/init.d.ts.map +1 -0
- package/dist/commands/init.js +81 -0
- package/dist/commands/init.js.map +1 -0
- package/dist/commands/sync.d.ts +5 -0
- package/dist/commands/sync.d.ts.map +1 -0
- package/dist/commands/sync.js +160 -0
- package/dist/commands/sync.js.map +1 -0
- package/dist/dashboard/auth.d.ts +17 -0
- package/dist/dashboard/auth.d.ts.map +1 -0
- package/dist/dashboard/auth.js +108 -0
- package/dist/dashboard/auth.js.map +1 -0
- package/dist/dashboard/server.d.ts +16 -0
- package/dist/dashboard/server.d.ts.map +1 -0
- package/dist/dashboard/server.js +1020 -0
- package/dist/dashboard/server.js.map +1 -0
- package/dist/dashboard/settings-store.d.ts +46 -0
- package/dist/dashboard/settings-store.d.ts.map +1 -0
- package/dist/dashboard/settings-store.js +183 -0
- package/dist/dashboard/settings-store.js.map +1 -0
- package/dist/dashboard-spa/apple-touch-icon.png +0 -0
- package/dist/dashboard-spa/assets/index-0vWLEg34.css +1 -0
- package/dist/dashboard-spa/assets/index-Rnhs9802.js +263 -0
- package/dist/dashboard-spa/assets/index-Rnhs9802.js.map +1 -0
- package/dist/dashboard-spa/icon-192.png +0 -0
- package/dist/dashboard-spa/icon-192.svg +4 -0
- package/dist/dashboard-spa/icon-512.png +0 -0
- package/dist/dashboard-spa/index.html +29 -0
- package/dist/dashboard-spa/manifest.webmanifest +37 -0
- package/dist/dashboard-spa/sw.js +111 -0
- package/dist/lib/config.d.ts +14 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +36 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/db.d.ts +5 -0
- package/dist/lib/db.d.ts.map +1 -0
- package/dist/lib/db.js +33 -0
- package/dist/lib/db.js.map +1 -0
- package/dist/lib/fts.d.ts +2 -0
- package/dist/lib/fts.d.ts.map +1 -0
- package/dist/lib/fts.js +14 -0
- package/dist/lib/fts.js.map +1 -0
- package/dist/lib/json.d.ts +3 -0
- package/dist/lib/json.d.ts.map +1 -0
- package/dist/lib/json.js +16 -0
- package/dist/lib/json.js.map +1 -0
- package/dist/lib/migrations.d.ts +9 -0
- package/dist/lib/migrations.d.ts.map +1 -0
- package/dist/lib/migrations.js +94 -0
- package/dist/lib/migrations.js.map +1 -0
- package/dist/lib/priority.d.ts +2 -0
- package/dist/lib/priority.d.ts.map +1 -0
- package/dist/lib/priority.js +8 -0
- package/dist/lib/priority.js.map +1 -0
- package/dist/models/activity.d.ts +41 -0
- package/dist/models/activity.d.ts.map +1 -0
- package/dist/models/activity.js +55 -0
- package/dist/models/activity.js.map +1 -0
- package/dist/models/approvals.d.ts +43 -0
- package/dist/models/approvals.d.ts.map +1 -0
- package/dist/models/approvals.js +102 -0
- package/dist/models/approvals.js.map +1 -0
- package/dist/models/context.d.ts +25 -0
- package/dist/models/context.d.ts.map +1 -0
- package/dist/models/context.js +63 -0
- package/dist/models/context.js.map +1 -0
- package/dist/models/dead_ends-helpers.d.ts +3 -0
- package/dist/models/dead_ends-helpers.d.ts.map +1 -0
- package/dist/models/dead_ends-helpers.js +9 -0
- package/dist/models/dead_ends-helpers.js.map +1 -0
- package/dist/models/dead_ends.d.ts +41 -0
- package/dist/models/dead_ends.d.ts.map +1 -0
- package/dist/models/dead_ends.js +96 -0
- package/dist/models/dead_ends.js.map +1 -0
- package/dist/models/decision_drafts.d.ts +59 -0
- package/dist/models/decision_drafts.d.ts.map +1 -0
- package/dist/models/decision_drafts.js +105 -0
- package/dist/models/decision_drafts.js.map +1 -0
- package/dist/models/decisions-helpers.d.ts +3 -0
- package/dist/models/decisions-helpers.d.ts.map +1 -0
- package/dist/models/decisions-helpers.js +9 -0
- package/dist/models/decisions-helpers.js.map +1 -0
- package/dist/models/decisions.d.ts +51 -0
- package/dist/models/decisions.d.ts.map +1 -0
- package/dist/models/decisions.js +97 -0
- package/dist/models/decisions.js.map +1 -0
- package/dist/models/notes-helpers.d.ts +3 -0
- package/dist/models/notes-helpers.d.ts.map +1 -0
- package/dist/models/notes-helpers.js +9 -0
- package/dist/models/notes-helpers.js.map +1 -0
- package/dist/models/notes.d.ts +35 -0
- package/dist/models/notes.d.ts.map +1 -0
- package/dist/models/notes.js +66 -0
- package/dist/models/notes.js.map +1 -0
- package/dist/models/plans.d.ts +25 -0
- package/dist/models/plans.d.ts.map +1 -0
- package/dist/models/plans.js +39 -0
- package/dist/models/plans.js.map +1 -0
- package/dist/models/pr_links.d.ts +36 -0
- package/dist/models/pr_links.d.ts.map +1 -0
- package/dist/models/pr_links.js +45 -0
- package/dist/models/pr_links.js.map +1 -0
- package/dist/models/project_members.d.ts +22 -0
- package/dist/models/project_members.d.ts.map +1 -0
- package/dist/models/project_members.js +33 -0
- package/dist/models/project_members.js.map +1 -0
- package/dist/models/projects.d.ts +55 -0
- package/dist/models/projects.d.ts.map +1 -0
- package/dist/models/projects.js +126 -0
- package/dist/models/projects.js.map +1 -0
- package/dist/models/push_subscriptions.d.ts +24 -0
- package/dist/models/push_subscriptions.d.ts.map +1 -0
- package/dist/models/push_subscriptions.js +39 -0
- package/dist/models/push_subscriptions.js.map +1 -0
- package/dist/models/session_costs.d.ts +48 -0
- package/dist/models/session_costs.d.ts.map +1 -0
- package/dist/models/session_costs.js +77 -0
- package/dist/models/session_costs.js.map +1 -0
- package/dist/models/sessions.d.ts +41 -0
- package/dist/models/sessions.d.ts.map +1 -0
- package/dist/models/sessions.js +96 -0
- package/dist/models/sessions.js.map +1 -0
- package/dist/models/subtasks-helpers.d.ts +3 -0
- package/dist/models/subtasks-helpers.d.ts.map +1 -0
- package/dist/models/subtasks-helpers.js +9 -0
- package/dist/models/subtasks-helpers.js.map +1 -0
- package/dist/models/subtasks.d.ts +69 -0
- package/dist/models/subtasks.d.ts.map +1 -0
- package/dist/models/subtasks.js +215 -0
- package/dist/models/subtasks.js.map +1 -0
- package/dist/models/users.d.ts +25 -0
- package/dist/models/users.d.ts.map +1 -0
- package/dist/models/users.js +44 -0
- package/dist/models/users.js.map +1 -0
- package/dist/server/mcp.d.ts +6 -0
- package/dist/server/mcp.d.ts.map +1 -0
- package/dist/server/mcp.js +72 -0
- package/dist/server/mcp.js.map +1 -0
- package/dist/server/tools/approval.d.ts +3 -0
- package/dist/server/tools/approval.d.ts.map +1 -0
- package/dist/server/tools/approval.js +98 -0
- package/dist/server/tools/approval.js.map +1 -0
- package/dist/server/tools/args.d.ts +11 -0
- package/dist/server/tools/args.d.ts.map +1 -0
- package/dist/server/tools/args.js +79 -0
- package/dist/server/tools/args.js.map +1 -0
- package/dist/server/tools/context.d.ts +3 -0
- package/dist/server/tools/context.d.ts.map +1 -0
- package/dist/server/tools/context.js +72 -0
- package/dist/server/tools/context.js.map +1 -0
- package/dist/server/tools/dead_ends.d.ts +3 -0
- package/dist/server/tools/dead_ends.d.ts.map +1 -0
- package/dist/server/tools/dead_ends.js +111 -0
- package/dist/server/tools/dead_ends.js.map +1 -0
- package/dist/server/tools/decisions.d.ts +3 -0
- package/dist/server/tools/decisions.d.ts.map +1 -0
- package/dist/server/tools/decisions.js +101 -0
- package/dist/server/tools/decisions.js.map +1 -0
- package/dist/server/tools/extraction.d.ts +3 -0
- package/dist/server/tools/extraction.d.ts.map +1 -0
- package/dist/server/tools/extraction.js +145 -0
- package/dist/server/tools/extraction.js.map +1 -0
- package/dist/server/tools/git.d.ts +3 -0
- package/dist/server/tools/git.d.ts.map +1 -0
- package/dist/server/tools/git.js +86 -0
- package/dist/server/tools/git.js.map +1 -0
- package/dist/server/tools/history.d.ts +3 -0
- package/dist/server/tools/history.d.ts.map +1 -0
- package/dist/server/tools/history.js +51 -0
- package/dist/server/tools/history.js.map +1 -0
- package/dist/server/tools/index.d.ts +6 -0
- package/dist/server/tools/index.d.ts.map +1 -0
- package/dist/server/tools/index.js +41 -0
- package/dist/server/tools/index.js.map +1 -0
- package/dist/server/tools/notes.d.ts +3 -0
- package/dist/server/tools/notes.d.ts.map +1 -0
- package/dist/server/tools/notes.js +60 -0
- package/dist/server/tools/notes.js.map +1 -0
- package/dist/server/tools/plans.d.ts +3 -0
- package/dist/server/tools/plans.d.ts.map +1 -0
- package/dist/server/tools/plans.js +65 -0
- package/dist/server/tools/plans.js.map +1 -0
- package/dist/server/tools/plugin.d.ts +3 -0
- package/dist/server/tools/plugin.d.ts.map +1 -0
- package/dist/server/tools/plugin.js +26 -0
- package/dist/server/tools/plugin.js.map +1 -0
- package/dist/server/tools/projects.d.ts +3 -0
- package/dist/server/tools/projects.d.ts.map +1 -0
- package/dist/server/tools/projects.js +197 -0
- package/dist/server/tools/projects.js.map +1 -0
- package/dist/server/tools/recall.d.ts +3 -0
- package/dist/server/tools/recall.d.ts.map +1 -0
- package/dist/server/tools/recall.js +74 -0
- package/dist/server/tools/recall.js.map +1 -0
- package/dist/server/tools/registry.d.ts +8 -0
- package/dist/server/tools/registry.d.ts.map +1 -0
- package/dist/server/tools/registry.js +23 -0
- package/dist/server/tools/registry.js.map +1 -0
- package/dist/server/tools/subtasks.d.ts +3 -0
- package/dist/server/tools/subtasks.d.ts.map +1 -0
- package/dist/server/tools/subtasks.js +306 -0
- package/dist/server/tools/subtasks.js.map +1 -0
- package/dist/server/tools/types.d.ts +7 -0
- package/dist/server/tools/types.d.ts.map +1 -0
- package/dist/server/tools/types.js +2 -0
- package/dist/server/tools/types.js.map +1 -0
- package/dist/server/tools/workflow.d.ts +3 -0
- package/dist/server/tools/workflow.d.ts.map +1 -0
- package/dist/server/tools/workflow.js +434 -0
- package/dist/server/tools/workflow.js.map +1 -0
- package/dist/services/auth/magic-link.d.ts +27 -0
- package/dist/services/auth/magic-link.d.ts.map +1 -0
- package/dist/services/auth/magic-link.js +48 -0
- package/dist/services/auth/magic-link.js.map +1 -0
- package/dist/services/auth/session.d.ts +15 -0
- package/dist/services/auth/session.d.ts.map +1 -0
- package/dist/services/auth/session.js +65 -0
- package/dist/services/auth/session.js.map +1 -0
- package/dist/services/cost/claude-code-parser.d.ts +30 -0
- package/dist/services/cost/claude-code-parser.d.ts.map +1 -0
- package/dist/services/cost/claude-code-parser.js +110 -0
- package/dist/services/cost/claude-code-parser.js.map +1 -0
- package/dist/services/cost/pricing.d.ts +15 -0
- package/dist/services/cost/pricing.d.ts.map +1 -0
- package/dist/services/cost/pricing.js +33 -0
- package/dist/services/cost/pricing.js.map +1 -0
- package/dist/services/digest/generator.d.ts +51 -0
- package/dist/services/digest/generator.d.ts.map +1 -0
- package/dist/services/digest/generator.js +136 -0
- package/dist/services/digest/generator.js.map +1 -0
- package/dist/services/digest/scheduler.d.ts +3 -0
- package/dist/services/digest/scheduler.d.ts.map +1 -0
- package/dist/services/digest/scheduler.js +61 -0
- package/dist/services/digest/scheduler.js.map +1 -0
- package/dist/services/digest/telegram.d.ts +13 -0
- package/dist/services/digest/telegram.d.ts.map +1 -0
- package/dist/services/digest/telegram.js +68 -0
- package/dist/services/digest/telegram.js.map +1 -0
- package/dist/services/embedding/detect.d.ts +19 -0
- package/dist/services/embedding/detect.d.ts.map +1 -0
- package/dist/services/embedding/detect.js +64 -0
- package/dist/services/embedding/detect.js.map +1 -0
- package/dist/services/embedding/factory.d.ts +10 -0
- package/dist/services/embedding/factory.d.ts.map +1 -0
- package/dist/services/embedding/factory.js +79 -0
- package/dist/services/embedding/factory.js.map +1 -0
- package/dist/services/embedding/ollama.d.ts +14 -0
- package/dist/services/embedding/ollama.d.ts.map +1 -0
- package/dist/services/embedding/ollama.js +28 -0
- package/dist/services/embedding/ollama.js.map +1 -0
- package/dist/services/embedding/openai.d.ts +16 -0
- package/dist/services/embedding/openai.d.ts.map +1 -0
- package/dist/services/embedding/openai.js +33 -0
- package/dist/services/embedding/openai.js.map +1 -0
- package/dist/services/embedding/store.d.ts +25 -0
- package/dist/services/embedding/store.d.ts.map +1 -0
- package/dist/services/embedding/store.js +79 -0
- package/dist/services/embedding/store.js.map +1 -0
- package/dist/services/embedding/types.d.ts +9 -0
- package/dist/services/embedding/types.d.ts.map +1 -0
- package/dist/services/embedding/types.js +2 -0
- package/dist/services/embedding/types.js.map +1 -0
- package/dist/services/embedding/vector-math.d.ts +4 -0
- package/dist/services/embedding/vector-math.d.ts.map +1 -0
- package/dist/services/embedding/vector-math.js +27 -0
- package/dist/services/embedding/vector-math.js.map +1 -0
- package/dist/services/embedding/voyage.d.ts +16 -0
- package/dist/services/embedding/voyage.d.ts.map +1 -0
- package/dist/services/embedding/voyage.js +33 -0
- package/dist/services/embedding/voyage.js.map +1 -0
- package/dist/services/extraction/decision-extractor.d.ts +16 -0
- package/dist/services/extraction/decision-extractor.d.ts.map +1 -0
- package/dist/services/extraction/decision-extractor.js +111 -0
- package/dist/services/extraction/decision-extractor.js.map +1 -0
- package/dist/services/extraction/session-summarizer.d.ts +17 -0
- package/dist/services/extraction/session-summarizer.d.ts.map +1 -0
- package/dist/services/extraction/session-summarizer.js +112 -0
- package/dist/services/extraction/session-summarizer.js.map +1 -0
- package/dist/services/github/webhook.d.ts +17 -0
- package/dist/services/github/webhook.d.ts.map +1 -0
- package/dist/services/github/webhook.js +159 -0
- package/dist/services/github/webhook.js.map +1 -0
- package/dist/services/llm/factory.d.ts +3 -0
- package/dist/services/llm/factory.d.ts.map +1 -0
- package/dist/services/llm/factory.js +53 -0
- package/dist/services/llm/factory.js.map +1 -0
- package/dist/services/llm/openai-compat.d.ts +20 -0
- package/dist/services/llm/openai-compat.d.ts.map +1 -0
- package/dist/services/llm/openai-compat.js +53 -0
- package/dist/services/llm/openai-compat.js.map +1 -0
- package/dist/services/llm/types.d.ts +23 -0
- package/dist/services/llm/types.d.ts.map +1 -0
- package/dist/services/llm/types.js +2 -0
- package/dist/services/llm/types.js.map +1 -0
- package/dist/services/mentions/resolver.d.ts +36 -0
- package/dist/services/mentions/resolver.d.ts.map +1 -0
- package/dist/services/mentions/resolver.js +97 -0
- package/dist/services/mentions/resolver.js.map +1 -0
- package/dist/services/plugins/api.d.ts +55 -0
- package/dist/services/plugins/api.d.ts.map +1 -0
- package/dist/services/plugins/api.js +35 -0
- package/dist/services/plugins/api.js.map +1 -0
- package/dist/services/plugins/discovery.d.ts +7 -0
- package/dist/services/plugins/discovery.d.ts.map +1 -0
- package/dist/services/plugins/discovery.js +104 -0
- package/dist/services/plugins/discovery.js.map +1 -0
- package/dist/services/plugins/marketplace.d.ts +42 -0
- package/dist/services/plugins/marketplace.d.ts.map +1 -0
- package/dist/services/plugins/marketplace.js +186 -0
- package/dist/services/plugins/marketplace.js.map +1 -0
- package/dist/services/plugins/registry.d.ts +12 -0
- package/dist/services/plugins/registry.d.ts.map +1 -0
- package/dist/services/plugins/registry.js +66 -0
- package/dist/services/plugins/registry.js.map +1 -0
- package/dist/services/plugins/state.d.ts +12 -0
- package/dist/services/plugins/state.d.ts.map +1 -0
- package/dist/services/plugins/state.js +14 -0
- package/dist/services/plugins/state.js.map +1 -0
- package/dist/services/push/web-push.d.ts +26 -0
- package/dist/services/push/web-push.d.ts.map +1 -0
- package/dist/services/push/web-push.js +84 -0
- package/dist/services/push/web-push.js.map +1 -0
- package/dist/services/relay/client.d.ts +27 -0
- package/dist/services/relay/client.d.ts.map +1 -0
- package/dist/services/relay/client.js +219 -0
- package/dist/services/relay/client.js.map +1 -0
- package/dist/services/relay/types.d.ts +19 -0
- package/dist/services/relay/types.d.ts.map +1 -0
- package/dist/services/relay/types.js +2 -0
- package/dist/services/relay/types.js.map +1 -0
- package/dist/services/telemetry/client.d.ts +35 -0
- package/dist/services/telemetry/client.d.ts.map +1 -0
- package/dist/services/telemetry/client.js +125 -0
- package/dist/services/telemetry/client.js.map +1 -0
- package/dist/services/transcription/whisper.d.ts +16 -0
- package/dist/services/transcription/whisper.d.ts.map +1 -0
- package/dist/services/transcription/whisper.js +72 -0
- package/dist/services/transcription/whisper.js.map +1 -0
- package/docs/architecture.md +108 -0
- package/docs/configuration.md +73 -0
- package/docs/cursor-quirks.md +42 -0
- package/docs/embedding-providers.md +110 -0
- package/docs/github-integration.md +109 -0
- package/docs/plugin-development.md +104 -0
- package/docs/plugins.md +104 -0
- package/docs/relay.md +108 -0
- package/docs/remote-access.md +218 -0
- package/docs/sponsorship.md +54 -0
- package/migrations/.gitkeep +0 -0
- package/migrations/0001_initial_schema.sql +284 -0
- package/migrations/0002_activity_and_links.sql +26 -0
- package/migrations/0003_workspace.sql +7 -0
- package/migrations/0004_decision_drafts.sql +28 -0
- package/migrations/0005_project_summaries.sql +10 -0
- package/migrations/0006_push_and_approvals.sql +37 -0
- package/migrations/0007_session_costs.sql +17 -0
- package/migrations/0008_pr_links.sql +22 -0
- package/migrations/0009_telemetry.sql +17 -0
- package/migrations/0010_users_and_members.sql +40 -0
- package/migrations/0011_assignments_mentions.sql +20 -0
- package/package.json +95 -0
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# GitHub deep integration
|
|
2
|
+
|
|
3
|
+
Shinobi listens for GitHub webhook events and automates three flows:
|
|
4
|
+
|
|
5
|
+
| GitHub event | What Shinobi does |
|
|
6
|
+
|---|---|
|
|
7
|
+
| **PR opened/edited** with `[SHI-N]` in title or body | Links the PR to subtask N (`pr_links` table), records `pr_opened` activity |
|
|
8
|
+
| **PR merged** | Auto-flips the linked subtask to `done`, records `subtask_auto_completed` activity with the merge URL |
|
|
9
|
+
| **PR comment** matching `/shinobi decision <kind>: <summary>` | Logs a decision (`logDecision`) on the project, linked to the subtask |
|
|
10
|
+
|
|
11
|
+
The `<kind>` values recognised: `architecture`, `library`, `pattern`,
|
|
12
|
+
`tradeoff`, `workaround`, `other`. Anything else falls back to `other`.
|
|
13
|
+
|
|
14
|
+
## Setup
|
|
15
|
+
|
|
16
|
+
### 1. Set the shared HMAC secret
|
|
17
|
+
|
|
18
|
+
Generate a random string and set it both on GitHub and on the agent:
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
# Generate
|
|
22
|
+
openssl rand -hex 32
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Add it to `~/.shinobi/.env`:
|
|
26
|
+
|
|
27
|
+
```ini
|
|
28
|
+
SHINOBI_GITHUB_WEBHOOK_SECRET=<the-hex-string>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Restart the dashboard. The endpoint `/api/github/webhook` now refuses any
|
|
32
|
+
request whose `X-Hub-Signature-256` does not match.
|
|
33
|
+
|
|
34
|
+
### 2. Expose the dashboard
|
|
35
|
+
|
|
36
|
+
The webhook URL must be reachable from GitHub. Easiest paths:
|
|
37
|
+
|
|
38
|
+
- **Cloudflare Tunnel** (recommended for ad-hoc use):
|
|
39
|
+
```sh
|
|
40
|
+
cloudflared tunnel --url http://127.0.0.1:8765
|
|
41
|
+
```
|
|
42
|
+
Use the printed `https://...trycloudflare.com/api/github/webhook` URL.
|
|
43
|
+
|
|
44
|
+
- **Persistent Tailscale Funnel / named CF Tunnel / public bind** with auth
|
|
45
|
+
forced on (see [`remote-access.md`](remote-access.md)).
|
|
46
|
+
|
|
47
|
+
### 3. Add the webhook on GitHub
|
|
48
|
+
|
|
49
|
+
Repository → Settings → Webhooks → Add webhook:
|
|
50
|
+
|
|
51
|
+
- **Payload URL**: `<your-public-base>/api/github/webhook`
|
|
52
|
+
- **Content type**: `application/json`
|
|
53
|
+
- **Secret**: same string you set in `~/.shinobi/.env`
|
|
54
|
+
- **Events**: select individual events:
|
|
55
|
+
- Pull requests
|
|
56
|
+
- Issue comments
|
|
57
|
+
- **Active**: ✓
|
|
58
|
+
|
|
59
|
+
GitHub sends a `ping` event on save — Shinobi responds with `pong` so you
|
|
60
|
+
should see a green check in the Webhook → Recent Deliveries panel.
|
|
61
|
+
|
|
62
|
+
## Tag syntax
|
|
63
|
+
|
|
64
|
+
Any PR title or body containing `[SHI-42]` (case-insensitive) links to
|
|
65
|
+
subtask #42. Example PR title:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
[SHI-185] feat: GitHub webhook receiver
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Decision comment syntax
|
|
72
|
+
|
|
73
|
+
In any PR comment:
|
|
74
|
+
|
|
75
|
+
```
|
|
76
|
+
/shinobi decision architecture: Switched from REST polling to WebSocket relay
|
|
77
|
+
to support real-time multi-agent sync. Trade-off: requires Cloudflare Worker
|
|
78
|
+
deployment but saves git push round-trips.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The first line becomes the decision `summary`; the full body becomes the
|
|
82
|
+
`rationale`. The decision attaches to the same subtask + project as the PR.
|
|
83
|
+
|
|
84
|
+
## What Shinobi does NOT do (yet)
|
|
85
|
+
|
|
86
|
+
- Post comments back to GitHub on subtask completion. The plumbing is
|
|
87
|
+
scaffolded (`SHINOBI_GITHUB_TOKEN` setting reserved) but the outbound
|
|
88
|
+
request is not implemented in this release.
|
|
89
|
+
- Auto-create PRs from subtasks.
|
|
90
|
+
- Reconcile force-pushed branches or rewritten commits.
|
|
91
|
+
|
|
92
|
+
## Inspecting linked PRs
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
curl http://127.0.0.1:8765/api/projects/36/pr-links
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Returns the most recent 50 links for the project, ordered by `opened_at`
|
|
99
|
+
descending, with `state` (`open` / `closed` / `merged`) and timestamps.
|
|
100
|
+
|
|
101
|
+
## Troubleshooting
|
|
102
|
+
|
|
103
|
+
- **401 invalid signature** — the secret on GitHub does not match the one
|
|
104
|
+
in `~/.shinobi/.env`. Re-paste both.
|
|
105
|
+
- **503 SHINOBI_GITHUB_WEBHOOK_SECRET not configured** — the env var is
|
|
106
|
+
empty; restart the dashboard after editing the file.
|
|
107
|
+
- **PR opens but no link created** — no `[SHI-N]` tag found, or the subtask
|
|
108
|
+
with that ID doesn't exist. Check the recent deliveries on GitHub to see
|
|
109
|
+
the dispatch outcome (`no_tag` / `subtask_not_found`).
|
|
@@ -0,0 +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.
|
package/docs/plugins.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Plugins
|
|
2
|
+
|
|
3
|
+
Shinobi loads plugins from two tiers:
|
|
4
|
+
|
|
5
|
+
- **User scripts** — drop a `.js` or `.mjs` file in `~/.shinobi/plugins/`.
|
|
6
|
+
Quickest path for one-off integrations.
|
|
7
|
+
- **npm packages** — install `@shinobi/plugin-<name>` or `shinobi-plugin-<name>`
|
|
8
|
+
via the dashboard `/plugins` page (or `npm install --prefix ~/.shinobi/plugins-npm <pkg>`).
|
|
9
|
+
Better for shareable, versioned plugins.
|
|
10
|
+
|
|
11
|
+
Both tiers are auto-discovered on dashboard startup; the loaded list is
|
|
12
|
+
visible at `/plugins` under "Loaded at last startup".
|
|
13
|
+
|
|
14
|
+
## Browsing the marketplace
|
|
15
|
+
|
|
16
|
+
Open `/plugins` in the dashboard:
|
|
17
|
+
|
|
18
|
+
1. Type a keyword in the search box (it runs three npm registry queries
|
|
19
|
+
simultaneously: `<query>` with `keywords:shinobi-plugin`, plus pattern
|
|
20
|
+
matches against `@shinobi/plugin-<query>` and `shinobi-plugin-<query>`).
|
|
21
|
+
2. Each result row shows package name, version, author, description, and
|
|
22
|
+
an Install / Uninstall button.
|
|
23
|
+
3. Install spawns `npm install --prefix ~/.shinobi/plugins-npm <pkg>` as a
|
|
24
|
+
child process — output is captured and the dashboard reports success
|
|
25
|
+
with a toast.
|
|
26
|
+
4. **Restart `shinobi dashboard` to pick up the new tools.** Discovery
|
|
27
|
+
only runs at startup.
|
|
28
|
+
|
|
29
|
+
## Anatomy of a plugin
|
|
30
|
+
|
|
31
|
+
Every plugin module exports a `register(tools)` function:
|
|
32
|
+
|
|
33
|
+
```js
|
|
34
|
+
// ~/.shinobi/plugins/example.mjs
|
|
35
|
+
export function register(tools) {
|
|
36
|
+
tools.appendTool({
|
|
37
|
+
name: 'plugin_echo',
|
|
38
|
+
description: 'Echoes its input back. Exists to prove the plugin system works.',
|
|
39
|
+
inputSchema: {
|
|
40
|
+
type: 'object',
|
|
41
|
+
properties: { message: { type: 'string' } },
|
|
42
|
+
required: ['message'],
|
|
43
|
+
additionalProperties: false,
|
|
44
|
+
},
|
|
45
|
+
handler: (args) => ({ echoed: args.message }),
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Plugins can register any number of MCP tools the same way built-in ones do.
|
|
51
|
+
The registry is global; collisions throw a clear error at startup.
|
|
52
|
+
|
|
53
|
+
## Publishing a plugin
|
|
54
|
+
|
|
55
|
+
There's no template repo yet — just create a tiny package that exports
|
|
56
|
+
`register`:
|
|
57
|
+
|
|
58
|
+
```json
|
|
59
|
+
{
|
|
60
|
+
"name": "@yourname/shinobi-plugin-jira",
|
|
61
|
+
"version": "0.1.0",
|
|
62
|
+
"description": "Sync Jira issues to Shinobi subtasks",
|
|
63
|
+
"type": "module",
|
|
64
|
+
"main": "index.js",
|
|
65
|
+
"keywords": ["shinobi-plugin", "jira"]
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The `keywords` field makes your package discoverable in the marketplace
|
|
70
|
+
search. Pick `@shinobi/plugin-*` (requires npm org membership — open an
|
|
71
|
+
issue) or `shinobi-plugin-*` (unscoped, available to anyone).
|
|
72
|
+
|
|
73
|
+
## Install location
|
|
74
|
+
|
|
75
|
+
- Default: `~/.shinobi/plugins-npm/node_modules/<pkg>`
|
|
76
|
+
- Override with `SHINOBI_PLUGINS_NPM_DIR=<path>` in `~/.shinobi/.env`
|
|
77
|
+
|
|
78
|
+
User scripts default location:
|
|
79
|
+
|
|
80
|
+
- Default: `~/.shinobi/plugins/`
|
|
81
|
+
- Override with `SHINOBI_PLUGINS_DIR=<path>`
|
|
82
|
+
|
|
83
|
+
## API
|
|
84
|
+
|
|
85
|
+
The dashboard exposes four endpoints used by the SPA:
|
|
86
|
+
|
|
87
|
+
| Method | Path | Body | Purpose |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| GET | `/api/plugins` | — | Lists loaded + installed plugins |
|
|
90
|
+
| POST | `/api/plugins/search` | `{ "query": "..." }` | npm registry search (filtered to shinobi plugins) |
|
|
91
|
+
| POST | `/api/plugins/install` | `{ "pkg": "@shinobi/plugin-x" }` | Spawns `npm install` |
|
|
92
|
+
| DELETE | `/api/plugins/:pkg` | — | Spawns `npm uninstall` |
|
|
93
|
+
|
|
94
|
+
Install/uninstall return the captured stdout/stderr plus a duration so the
|
|
95
|
+
dashboard can render a meaningful toast.
|
|
96
|
+
|
|
97
|
+
## Safety
|
|
98
|
+
|
|
99
|
+
- Install/uninstall refuse any package name that does not match the
|
|
100
|
+
`@shinobi/plugin-*` or `shinobi-plugin-*` patterns. This prevents the
|
|
101
|
+
dashboard from being abused as a generic npm runner.
|
|
102
|
+
- Loaded plugin tools share the same global registry as built-ins, so a
|
|
103
|
+
malicious plugin can register tools that shadow real ones — only install
|
|
104
|
+
packages you trust.
|
package/docs/relay.md
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Shinobi relay — multi-agent real-time sync
|
|
2
|
+
|
|
3
|
+
The relay broadcasts `sync-available` events between multiple agents working on
|
|
4
|
+
the same workspace, so that running `shinobi sync push` on machine A causes
|
|
5
|
+
machine B to auto-pull the new snapshot within ~1.5 seconds (vs. polling git
|
|
6
|
+
manually).
|
|
7
|
+
|
|
8
|
+
It is fully optional. Without it, cross-machine sync still works via
|
|
9
|
+
`shinobi sync push` + `shinobi sync pull` on demand.
|
|
10
|
+
|
|
11
|
+
## Architecture
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
┌─────────────────┐ WebSocket ┌──────────────────────┐
|
|
15
|
+
│ agent A (laptop)│ ─────────────────────────────▶│ Cloudflare Worker │
|
|
16
|
+
│ shinobi dashb. │ ◀─────── re-broadcast ──────▶│ + Durable Object │
|
|
17
|
+
└─────────────────┘ │ (per workspace) │
|
|
18
|
+
└──────────────────────┘
|
|
19
|
+
┌─────────────────┐ WebSocket ▲
|
|
20
|
+
│ agent B (phone) │ ──────────────────────────────────────┘
|
|
21
|
+
│ shinobi dashb. │
|
|
22
|
+
└─────────────────┘
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The Worker is essentially a thin pub/sub: it does not persist events, does not
|
|
26
|
+
inspect payloads, and re-broadcasts every message it receives to every other
|
|
27
|
+
socket in the same workspace (`Durable Object` keyed by `idFromName(workspace)`).
|
|
28
|
+
|
|
29
|
+
## Setup
|
|
30
|
+
|
|
31
|
+
### 1. Deploy the Worker
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
cd relay-worker
|
|
35
|
+
npm install
|
|
36
|
+
npx wrangler login # one-time
|
|
37
|
+
npx wrangler deploy
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The deploy command prints the Worker URL, e.g.
|
|
41
|
+
`https://shinobi-relay.<your-account>.workers.dev`. The WebSocket endpoint is
|
|
42
|
+
the same host with `wss://` and path `/ws`.
|
|
43
|
+
|
|
44
|
+
### 2. Set the shared secret
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
cd relay-worker
|
|
48
|
+
npx wrangler secret put SHINOBI_RELAY_TOKEN
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Paste any strong random value when prompted. This token must match
|
|
52
|
+
`SHINOBI_RELAY_TOKEN` configured on each agent.
|
|
53
|
+
|
|
54
|
+
> Skipping this step leaves the relay open to anyone who knows your Worker URL.
|
|
55
|
+
> Only acceptable for short-lived dev experiments.
|
|
56
|
+
|
|
57
|
+
### 3. Configure each agent
|
|
58
|
+
|
|
59
|
+
In each machine's `~/.shinobi/.env`:
|
|
60
|
+
|
|
61
|
+
```ini
|
|
62
|
+
SHINOBI_RELAY_URL=wss://shinobi-relay.<your-account>.workers.dev/ws
|
|
63
|
+
SHINOBI_RELAY_TOKEN=<the same secret you put on the Worker>
|
|
64
|
+
SHINOBI_RELAY_WORKSPACE=personal
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`SHINOBI_RELAY_WORKSPACE` is any string — agents that share the same string
|
|
68
|
+
share a relay channel. Use `personal` for your own machines, or a team name
|
|
69
|
+
to coordinate with others.
|
|
70
|
+
|
|
71
|
+
Restart the dashboard:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
shinobi dashboard
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Open `http://localhost:8765/relay` to verify the connection. The page polls
|
|
78
|
+
status every 3 seconds and exposes a manual broadcast test button.
|
|
79
|
+
|
|
80
|
+
## Protocol
|
|
81
|
+
|
|
82
|
+
Every WebSocket message is a JSON envelope:
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
{
|
|
86
|
+
type: 'sync-available' | 'activity' | 'presence',
|
|
87
|
+
workspace: string,
|
|
88
|
+
source_agent: string,
|
|
89
|
+
ts: string, // ISO-8601
|
|
90
|
+
payload: Record<string, unknown>
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The client ignores messages where `source_agent === own_agent_id` to avoid
|
|
95
|
+
self-loops.
|
|
96
|
+
|
|
97
|
+
Currently the only event the client *reacts* to is `sync-available`, which
|
|
98
|
+
debounces a call to `syncPull()` 1.5 seconds after receipt.
|
|
99
|
+
|
|
100
|
+
## Cost
|
|
101
|
+
|
|
102
|
+
Cloudflare Workers + Durable Objects free tier covers:
|
|
103
|
+
- 100,000 requests/day
|
|
104
|
+
- 100 GB-s of Durable Object time
|
|
105
|
+
- 1 GB egress
|
|
106
|
+
|
|
107
|
+
A single agent generating 10 sync events/day across a 2-machine setup is
|
|
108
|
+
well under 1% of the free tier.
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
# Remote access — reach the Shinobi dashboard from anywhere
|
|
2
|
+
|
|
3
|
+
Out of the box, `shinobi dashboard` binds to `127.0.0.1:8765`. The web UI and
|
|
4
|
+
JSON API are only reachable from the same machine. This is the safe default —
|
|
5
|
+
you should opt-in deliberately before exposing the dashboard to the internet.
|
|
6
|
+
|
|
7
|
+
Two practical paths to reach the dashboard from a phone, tablet, or another
|
|
8
|
+
laptop:
|
|
9
|
+
|
|
10
|
+
| Path | Trust model | Best when |
|
|
11
|
+
|------|-------------|-----------|
|
|
12
|
+
| **Tailscale** (recommended) | Mesh VPN, devices only see each other if both are logged in to the same tailnet | You want zero public exposure and trust the Tailscale account |
|
|
13
|
+
| **Cloudflare Tunnel** | Public URL fronted by Cloudflare with auth required | You want a phone-friendly `https://...` URL without VPN setup |
|
|
14
|
+
|
|
15
|
+
Both paths require **dashboard auth enabled**. The dashboard auto-enables auth
|
|
16
|
+
whenever it binds to anything other than a loopback address (`127.0.0.1`,
|
|
17
|
+
`localhost`, `::1`). If you change the bind host, also do a one-time
|
|
18
|
+
`shinobi dashboard` run to capture the printed `?token=...` URL.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Option A — Tailscale (recommended)
|
|
23
|
+
|
|
24
|
+
Tailscale is a WireGuard-based mesh VPN. Devices on the same tailnet can reach
|
|
25
|
+
each other by stable `100.x.y.z` IP (or magic DNS hostname like
|
|
26
|
+
`mylaptop.tailnet.ts.net`) without opening any port on your router or any
|
|
27
|
+
public URL.
|
|
28
|
+
|
|
29
|
+
### 1. Install on the dashboard host
|
|
30
|
+
|
|
31
|
+
```sh
|
|
32
|
+
# macOS / Linux
|
|
33
|
+
curl -fsSL https://tailscale.com/install.sh | sh
|
|
34
|
+
sudo tailscale up
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```powershell
|
|
38
|
+
# Windows: download installer from https://tailscale.com/download/windows
|
|
39
|
+
# Then run from elevated PowerShell:
|
|
40
|
+
tailscale up
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Authorize the machine via the browser link Tailscale prints.
|
|
44
|
+
|
|
45
|
+
Note your tailnet IP:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
tailscale ip -4
|
|
49
|
+
# e.g. 100.101.102.103
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### 2. Install on the phone
|
|
53
|
+
|
|
54
|
+
- iOS: <https://apps.apple.com/app/tailscale/id1470499037>
|
|
55
|
+
- Android: <https://play.google.com/store/apps/details?id=com.tailscale.ipn>
|
|
56
|
+
|
|
57
|
+
Log in to the same Tailscale account.
|
|
58
|
+
|
|
59
|
+
### 3. Bind the dashboard to your tailnet IP
|
|
60
|
+
|
|
61
|
+
In `~/.shinobi/.env`:
|
|
62
|
+
|
|
63
|
+
```ini
|
|
64
|
+
SHINOBI_DASHBOARD_HOST=0.0.0.0
|
|
65
|
+
SHINOBI_DASHBOARD_PORT=8765
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
> `0.0.0.0` binds to *every* network interface — including your LAN. If you
|
|
69
|
+
> want strictly tailnet-only, use the Tailscale IP from step 1 directly:
|
|
70
|
+
> `SHINOBI_DASHBOARD_HOST=100.101.102.103`. macOS/Linux tend to allow binding
|
|
71
|
+
> to the Tailscale IP cleanly; Windows sometimes does not, in which case
|
|
72
|
+
> `0.0.0.0` + Windows Firewall scoping is the practical workaround.
|
|
73
|
+
|
|
74
|
+
Restart the dashboard:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
shinobi dashboard
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The startup log now reads:
|
|
81
|
+
|
|
82
|
+
```
|
|
83
|
+
shinobi dashboard: listening on http://0.0.0.0:8765
|
|
84
|
+
shinobi dashboard: auth ON (non-loopback bind)
|
|
85
|
+
token file: /home/you/.shinobi/dashboard-token
|
|
86
|
+
open once: http://0.0.0.0:8765/?token=<random-64-chars>
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### 4. Open from the phone
|
|
90
|
+
|
|
91
|
+
In your phone browser, visit:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
http://100.101.102.103:8765/?token=<token from the log>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Once opened, the token is stored as a cookie and you do not need to paste it
|
|
98
|
+
again on that device.
|
|
99
|
+
|
|
100
|
+
### 5. Save to home screen (PWA install)
|
|
101
|
+
|
|
102
|
+
The dashboard ships a web manifest + service worker, so you can install it as
|
|
103
|
+
a PWA — looks like a native app, opens fullscreen. On iOS: Share → Add to Home
|
|
104
|
+
Screen. On Android: ⋮ → Install app.
|
|
105
|
+
|
|
106
|
+
This also enables push notifications (see `/push` page) which is the killer
|
|
107
|
+
combo with the `request_approval` MCP tool.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Option B — Cloudflare Tunnel (no VPN)
|
|
112
|
+
|
|
113
|
+
Cloudflare Tunnel (cloudflared) creates an outbound-only connection from your
|
|
114
|
+
machine to Cloudflare and gives you a public `https://...trycloudflare.com`
|
|
115
|
+
URL — no port forwarding, no public IP exposure.
|
|
116
|
+
|
|
117
|
+
### 1. Install cloudflared
|
|
118
|
+
|
|
119
|
+
```sh
|
|
120
|
+
# macOS
|
|
121
|
+
brew install cloudflared
|
|
122
|
+
|
|
123
|
+
# Linux (Debian/Ubuntu)
|
|
124
|
+
curl -L -o cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
|
|
125
|
+
sudo dpkg -i cloudflared.deb
|
|
126
|
+
|
|
127
|
+
# Windows: install via winget
|
|
128
|
+
winget install --id Cloudflare.cloudflared
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### 2. Spawn an ad-hoc tunnel
|
|
132
|
+
|
|
133
|
+
Keep the dashboard bound to `127.0.0.1` (the default) — cloudflared connects
|
|
134
|
+
to it locally.
|
|
135
|
+
|
|
136
|
+
```sh
|
|
137
|
+
shinobi dashboard # one terminal
|
|
138
|
+
cloudflared tunnel --url http://127.0.0.1:8765 # another terminal
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
cloudflared prints something like:
|
|
142
|
+
|
|
143
|
+
```
|
|
144
|
+
+--------------------------------------------------------------------------------------------+
|
|
145
|
+
| Your quick Tunnel has been created! Visit it at: |
|
|
146
|
+
| https://chunky-words-fall-here.trycloudflare.com |
|
|
147
|
+
+--------------------------------------------------------------------------------------------+
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### 3. Force auth on (the bind is still loopback)
|
|
151
|
+
|
|
152
|
+
The dashboard auto-enables auth for non-loopback binds. Because cloudflared
|
|
153
|
+
connects over `127.0.0.1`, you must force-enable auth so the tunneled
|
|
154
|
+
endpoint is not an open door:
|
|
155
|
+
|
|
156
|
+
```ini
|
|
157
|
+
# ~/.shinobi/.env
|
|
158
|
+
SHINOBI_DASHBOARD_HOST=127.0.0.1
|
|
159
|
+
SHINOBI_DASHBOARD_PORT=8765
|
|
160
|
+
SHINOBI_DASHBOARD_AUTH=on
|
|
161
|
+
# Optional — supply your own token; otherwise one is generated at
|
|
162
|
+
# ~/.shinobi/dashboard-token on first run:
|
|
163
|
+
# SHINOBI_DASHBOARD_TOKEN=<64-hex-chars>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Restart the dashboard. The first non-`/health` request without a valid
|
|
167
|
+
`?token=`, `Authorization: Bearer`, `x-shinobi-token`, or cookie is rejected
|
|
168
|
+
with `401`. Visit the public tunnel URL once with `?token=<value>` appended;
|
|
169
|
+
the dashboard sets a 30-day cookie and you do not need to paste it again on
|
|
170
|
+
that device.
|
|
171
|
+
|
|
172
|
+
You can read the generated token from `~/.shinobi/dashboard-token` at any
|
|
173
|
+
time. Rotate it by deleting that file (next start regenerates) or by setting
|
|
174
|
+
`SHINOBI_DASHBOARD_TOKEN` to a new value.
|
|
175
|
+
|
|
176
|
+
### 4. Persistent named tunnel (optional)
|
|
177
|
+
|
|
178
|
+
The ad-hoc URL rotates on every restart. For a stable URL:
|
|
179
|
+
|
|
180
|
+
```sh
|
|
181
|
+
cloudflared tunnel login
|
|
182
|
+
cloudflared tunnel create shinobi
|
|
183
|
+
# Map a hostname (requires a Cloudflare-managed domain):
|
|
184
|
+
cloudflared tunnel route dns shinobi shinobi.example.com
|
|
185
|
+
# Run:
|
|
186
|
+
cloudflared tunnel run shinobi
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Security checklist
|
|
192
|
+
|
|
193
|
+
Before exposing the dashboard, verify:
|
|
194
|
+
|
|
195
|
+
- [ ] Bind is non-loopback OR a tunnel is in front → **dashboard auth is ON**
|
|
196
|
+
- [ ] Token is at least 32 hex characters (default) and only shared on trusted devices
|
|
197
|
+
- [ ] `~/.shinobi/.env` is `chmod 600` (your secret keys live there)
|
|
198
|
+
- [ ] If using Cloudflare Tunnel, the named hostname is behind Cloudflare Access (Zero Trust → Access → Application) for SSO instead of a static token
|
|
199
|
+
- [ ] You restart the dashboard after any change to bind host/port/auth (these settings have `requiresRestart=true`)
|
|
200
|
+
|
|
201
|
+
## Combining with web push
|
|
202
|
+
|
|
203
|
+
Once the dashboard is reachable from your phone via Tailscale, also subscribe
|
|
204
|
+
the phone to push notifications via the `/push` page. This way:
|
|
205
|
+
|
|
206
|
+
1. Agent calls `request_approval` from MCP.
|
|
207
|
+
2. Phone gets a push notification with `[yes] [no]` action buttons.
|
|
208
|
+
3. Tap a button → response posts back even if the dashboard tab is closed.
|
|
209
|
+
4. MCP tool unblocks within ~1 second.
|
|
210
|
+
|
|
211
|
+
You can be on a beach and still gate AI agent decisions.
|
|
212
|
+
|
|
213
|
+
## Combining with multi-agent relay
|
|
214
|
+
|
|
215
|
+
See [`relay.md`](relay.md). If you set up both, every `shinobi sync push`
|
|
216
|
+
broadcasts to peer agents, and every peer auto-pulls within ~1.5 seconds.
|
|
217
|
+
Approvals + relay + push together turn Shinobi into a real-time coordination
|
|
218
|
+
fabric across all your machines.
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Sponsorship
|
|
2
|
+
|
|
3
|
+
If Shinobi saves you time, consider [sponsoring the project on GitHub](https://github.com/sponsors/numbererikson).
|
|
4
|
+
|
|
5
|
+
## What sponsorship pays for
|
|
6
|
+
|
|
7
|
+
100% goes to:
|
|
8
|
+
1. Dedicated maintenance time (issue triage, PR review, dependency
|
|
9
|
+
updates, release management).
|
|
10
|
+
2. Hosted infrastructure for the public demo (Postgres, R2 storage,
|
|
11
|
+
Cloudflare Worker).
|
|
12
|
+
3. Free hosted tier for verified open-source projects (apply via email).
|
|
13
|
+
|
|
14
|
+
## Tiers
|
|
15
|
+
|
|
16
|
+
These exist on the GitHub Sponsors page; replicating here for transparency.
|
|
17
|
+
|
|
18
|
+
| Tier | Monthly | What you get |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| Coffee | $5 | Knowing the project keeps maintained. README mention if you want. |
|
|
21
|
+
| Backer | $20 | All of above + priority issue triage flag on issues you open. |
|
|
22
|
+
| Sustaining | $100 | All of above + a quarterly 30-min office hours call (group session, capped at 8 participants/quarter). |
|
|
23
|
+
| Corporate | $500 | All of above + your logo on the README and marketing site sponsor section + named in the launch screencast credits. |
|
|
24
|
+
|
|
25
|
+
One-time donations are also welcome — `Buy Me a Coffee` and others get
|
|
26
|
+
linked when configured.
|
|
27
|
+
|
|
28
|
+
## No paywalled features
|
|
29
|
+
|
|
30
|
+
The self-hosted version of Shinobi will always have feature parity
|
|
31
|
+
with the hosted SaaS. Sponsorship buys *maintenance*, not access.
|
|
32
|
+
|
|
33
|
+
The hosted SaaS subscription buys *convenience* (we run it for you).
|
|
34
|
+
Different value props, no overlap.
|
|
35
|
+
|
|
36
|
+
## What sponsorship is NOT
|
|
37
|
+
|
|
38
|
+
- Not a way to influence the roadmap. Roadmap items come from real
|
|
39
|
+
user needs (yours included if you open issues). Sponsorship doesn't
|
|
40
|
+
jump the queue — but it does buy maintainer attention to your issues
|
|
41
|
+
via the priority flag.
|
|
42
|
+
- Not a guarantee of support response time. Use the Pro plan for that.
|
|
43
|
+
- Not a commercial license — Shinobi is MIT, you can already use it
|
|
44
|
+
for anything.
|
|
45
|
+
|
|
46
|
+
## How to apply for the free OSS-project tier
|
|
47
|
+
|
|
48
|
+
Email contact@shinobi-apps.hr with:
|
|
49
|
+
- The repo URL
|
|
50
|
+
- Brief description of the project
|
|
51
|
+
- How you'd use Shinobi in your workflow
|
|
52
|
+
|
|
53
|
+
We'll respond within 5 business days. The grant is 12 months of the
|
|
54
|
+
Team tier, renewable.
|
|
File without changes
|