@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.
Files changed (378) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/CODE_OF_CONDUCT.md +70 -0
  3. package/LICENSE +21 -0
  4. package/README.md +269 -0
  5. package/SECURITY.md +75 -0
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +200 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/commands/cost.d.ts +9 -0
  11. package/dist/commands/cost.d.ts.map +1 -0
  12. package/dist/commands/cost.js +49 -0
  13. package/dist/commands/cost.js.map +1 -0
  14. package/dist/commands/digest.d.ts +29 -0
  15. package/dist/commands/digest.d.ts.map +1 -0
  16. package/dist/commands/digest.js +63 -0
  17. package/dist/commands/digest.js.map +1 -0
  18. package/dist/commands/init.d.ts +15 -0
  19. package/dist/commands/init.d.ts.map +1 -0
  20. package/dist/commands/init.js +81 -0
  21. package/dist/commands/init.js.map +1 -0
  22. package/dist/commands/sync.d.ts +5 -0
  23. package/dist/commands/sync.d.ts.map +1 -0
  24. package/dist/commands/sync.js +160 -0
  25. package/dist/commands/sync.js.map +1 -0
  26. package/dist/dashboard/auth.d.ts +17 -0
  27. package/dist/dashboard/auth.d.ts.map +1 -0
  28. package/dist/dashboard/auth.js +108 -0
  29. package/dist/dashboard/auth.js.map +1 -0
  30. package/dist/dashboard/server.d.ts +16 -0
  31. package/dist/dashboard/server.d.ts.map +1 -0
  32. package/dist/dashboard/server.js +1020 -0
  33. package/dist/dashboard/server.js.map +1 -0
  34. package/dist/dashboard/settings-store.d.ts +46 -0
  35. package/dist/dashboard/settings-store.d.ts.map +1 -0
  36. package/dist/dashboard/settings-store.js +183 -0
  37. package/dist/dashboard/settings-store.js.map +1 -0
  38. package/dist/dashboard-spa/apple-touch-icon.png +0 -0
  39. package/dist/dashboard-spa/assets/index-0vWLEg34.css +1 -0
  40. package/dist/dashboard-spa/assets/index-Rnhs9802.js +263 -0
  41. package/dist/dashboard-spa/assets/index-Rnhs9802.js.map +1 -0
  42. package/dist/dashboard-spa/icon-192.png +0 -0
  43. package/dist/dashboard-spa/icon-192.svg +4 -0
  44. package/dist/dashboard-spa/icon-512.png +0 -0
  45. package/dist/dashboard-spa/index.html +29 -0
  46. package/dist/dashboard-spa/manifest.webmanifest +37 -0
  47. package/dist/dashboard-spa/sw.js +111 -0
  48. package/dist/lib/config.d.ts +14 -0
  49. package/dist/lib/config.d.ts.map +1 -0
  50. package/dist/lib/config.js +36 -0
  51. package/dist/lib/config.js.map +1 -0
  52. package/dist/lib/db.d.ts +5 -0
  53. package/dist/lib/db.d.ts.map +1 -0
  54. package/dist/lib/db.js +33 -0
  55. package/dist/lib/db.js.map +1 -0
  56. package/dist/lib/fts.d.ts +2 -0
  57. package/dist/lib/fts.d.ts.map +1 -0
  58. package/dist/lib/fts.js +14 -0
  59. package/dist/lib/fts.js.map +1 -0
  60. package/dist/lib/json.d.ts +3 -0
  61. package/dist/lib/json.d.ts.map +1 -0
  62. package/dist/lib/json.js +16 -0
  63. package/dist/lib/json.js.map +1 -0
  64. package/dist/lib/migrations.d.ts +9 -0
  65. package/dist/lib/migrations.d.ts.map +1 -0
  66. package/dist/lib/migrations.js +94 -0
  67. package/dist/lib/migrations.js.map +1 -0
  68. package/dist/lib/priority.d.ts +2 -0
  69. package/dist/lib/priority.d.ts.map +1 -0
  70. package/dist/lib/priority.js +8 -0
  71. package/dist/lib/priority.js.map +1 -0
  72. package/dist/models/activity.d.ts +41 -0
  73. package/dist/models/activity.d.ts.map +1 -0
  74. package/dist/models/activity.js +55 -0
  75. package/dist/models/activity.js.map +1 -0
  76. package/dist/models/approvals.d.ts +43 -0
  77. package/dist/models/approvals.d.ts.map +1 -0
  78. package/dist/models/approvals.js +102 -0
  79. package/dist/models/approvals.js.map +1 -0
  80. package/dist/models/context.d.ts +25 -0
  81. package/dist/models/context.d.ts.map +1 -0
  82. package/dist/models/context.js +63 -0
  83. package/dist/models/context.js.map +1 -0
  84. package/dist/models/dead_ends-helpers.d.ts +3 -0
  85. package/dist/models/dead_ends-helpers.d.ts.map +1 -0
  86. package/dist/models/dead_ends-helpers.js +9 -0
  87. package/dist/models/dead_ends-helpers.js.map +1 -0
  88. package/dist/models/dead_ends.d.ts +41 -0
  89. package/dist/models/dead_ends.d.ts.map +1 -0
  90. package/dist/models/dead_ends.js +96 -0
  91. package/dist/models/dead_ends.js.map +1 -0
  92. package/dist/models/decision_drafts.d.ts +59 -0
  93. package/dist/models/decision_drafts.d.ts.map +1 -0
  94. package/dist/models/decision_drafts.js +105 -0
  95. package/dist/models/decision_drafts.js.map +1 -0
  96. package/dist/models/decisions-helpers.d.ts +3 -0
  97. package/dist/models/decisions-helpers.d.ts.map +1 -0
  98. package/dist/models/decisions-helpers.js +9 -0
  99. package/dist/models/decisions-helpers.js.map +1 -0
  100. package/dist/models/decisions.d.ts +51 -0
  101. package/dist/models/decisions.d.ts.map +1 -0
  102. package/dist/models/decisions.js +97 -0
  103. package/dist/models/decisions.js.map +1 -0
  104. package/dist/models/notes-helpers.d.ts +3 -0
  105. package/dist/models/notes-helpers.d.ts.map +1 -0
  106. package/dist/models/notes-helpers.js +9 -0
  107. package/dist/models/notes-helpers.js.map +1 -0
  108. package/dist/models/notes.d.ts +35 -0
  109. package/dist/models/notes.d.ts.map +1 -0
  110. package/dist/models/notes.js +66 -0
  111. package/dist/models/notes.js.map +1 -0
  112. package/dist/models/plans.d.ts +25 -0
  113. package/dist/models/plans.d.ts.map +1 -0
  114. package/dist/models/plans.js +39 -0
  115. package/dist/models/plans.js.map +1 -0
  116. package/dist/models/pr_links.d.ts +36 -0
  117. package/dist/models/pr_links.d.ts.map +1 -0
  118. package/dist/models/pr_links.js +45 -0
  119. package/dist/models/pr_links.js.map +1 -0
  120. package/dist/models/project_members.d.ts +22 -0
  121. package/dist/models/project_members.d.ts.map +1 -0
  122. package/dist/models/project_members.js +33 -0
  123. package/dist/models/project_members.js.map +1 -0
  124. package/dist/models/projects.d.ts +55 -0
  125. package/dist/models/projects.d.ts.map +1 -0
  126. package/dist/models/projects.js +126 -0
  127. package/dist/models/projects.js.map +1 -0
  128. package/dist/models/push_subscriptions.d.ts +24 -0
  129. package/dist/models/push_subscriptions.d.ts.map +1 -0
  130. package/dist/models/push_subscriptions.js +39 -0
  131. package/dist/models/push_subscriptions.js.map +1 -0
  132. package/dist/models/session_costs.d.ts +48 -0
  133. package/dist/models/session_costs.d.ts.map +1 -0
  134. package/dist/models/session_costs.js +77 -0
  135. package/dist/models/session_costs.js.map +1 -0
  136. package/dist/models/sessions.d.ts +41 -0
  137. package/dist/models/sessions.d.ts.map +1 -0
  138. package/dist/models/sessions.js +96 -0
  139. package/dist/models/sessions.js.map +1 -0
  140. package/dist/models/subtasks-helpers.d.ts +3 -0
  141. package/dist/models/subtasks-helpers.d.ts.map +1 -0
  142. package/dist/models/subtasks-helpers.js +9 -0
  143. package/dist/models/subtasks-helpers.js.map +1 -0
  144. package/dist/models/subtasks.d.ts +69 -0
  145. package/dist/models/subtasks.d.ts.map +1 -0
  146. package/dist/models/subtasks.js +215 -0
  147. package/dist/models/subtasks.js.map +1 -0
  148. package/dist/models/users.d.ts +25 -0
  149. package/dist/models/users.d.ts.map +1 -0
  150. package/dist/models/users.js +44 -0
  151. package/dist/models/users.js.map +1 -0
  152. package/dist/server/mcp.d.ts +6 -0
  153. package/dist/server/mcp.d.ts.map +1 -0
  154. package/dist/server/mcp.js +72 -0
  155. package/dist/server/mcp.js.map +1 -0
  156. package/dist/server/tools/approval.d.ts +3 -0
  157. package/dist/server/tools/approval.d.ts.map +1 -0
  158. package/dist/server/tools/approval.js +98 -0
  159. package/dist/server/tools/approval.js.map +1 -0
  160. package/dist/server/tools/args.d.ts +11 -0
  161. package/dist/server/tools/args.d.ts.map +1 -0
  162. package/dist/server/tools/args.js +79 -0
  163. package/dist/server/tools/args.js.map +1 -0
  164. package/dist/server/tools/context.d.ts +3 -0
  165. package/dist/server/tools/context.d.ts.map +1 -0
  166. package/dist/server/tools/context.js +72 -0
  167. package/dist/server/tools/context.js.map +1 -0
  168. package/dist/server/tools/dead_ends.d.ts +3 -0
  169. package/dist/server/tools/dead_ends.d.ts.map +1 -0
  170. package/dist/server/tools/dead_ends.js +111 -0
  171. package/dist/server/tools/dead_ends.js.map +1 -0
  172. package/dist/server/tools/decisions.d.ts +3 -0
  173. package/dist/server/tools/decisions.d.ts.map +1 -0
  174. package/dist/server/tools/decisions.js +101 -0
  175. package/dist/server/tools/decisions.js.map +1 -0
  176. package/dist/server/tools/extraction.d.ts +3 -0
  177. package/dist/server/tools/extraction.d.ts.map +1 -0
  178. package/dist/server/tools/extraction.js +145 -0
  179. package/dist/server/tools/extraction.js.map +1 -0
  180. package/dist/server/tools/git.d.ts +3 -0
  181. package/dist/server/tools/git.d.ts.map +1 -0
  182. package/dist/server/tools/git.js +86 -0
  183. package/dist/server/tools/git.js.map +1 -0
  184. package/dist/server/tools/history.d.ts +3 -0
  185. package/dist/server/tools/history.d.ts.map +1 -0
  186. package/dist/server/tools/history.js +51 -0
  187. package/dist/server/tools/history.js.map +1 -0
  188. package/dist/server/tools/index.d.ts +6 -0
  189. package/dist/server/tools/index.d.ts.map +1 -0
  190. package/dist/server/tools/index.js +41 -0
  191. package/dist/server/tools/index.js.map +1 -0
  192. package/dist/server/tools/notes.d.ts +3 -0
  193. package/dist/server/tools/notes.d.ts.map +1 -0
  194. package/dist/server/tools/notes.js +60 -0
  195. package/dist/server/tools/notes.js.map +1 -0
  196. package/dist/server/tools/plans.d.ts +3 -0
  197. package/dist/server/tools/plans.d.ts.map +1 -0
  198. package/dist/server/tools/plans.js +65 -0
  199. package/dist/server/tools/plans.js.map +1 -0
  200. package/dist/server/tools/plugin.d.ts +3 -0
  201. package/dist/server/tools/plugin.d.ts.map +1 -0
  202. package/dist/server/tools/plugin.js +26 -0
  203. package/dist/server/tools/plugin.js.map +1 -0
  204. package/dist/server/tools/projects.d.ts +3 -0
  205. package/dist/server/tools/projects.d.ts.map +1 -0
  206. package/dist/server/tools/projects.js +197 -0
  207. package/dist/server/tools/projects.js.map +1 -0
  208. package/dist/server/tools/recall.d.ts +3 -0
  209. package/dist/server/tools/recall.d.ts.map +1 -0
  210. package/dist/server/tools/recall.js +74 -0
  211. package/dist/server/tools/recall.js.map +1 -0
  212. package/dist/server/tools/registry.d.ts +8 -0
  213. package/dist/server/tools/registry.d.ts.map +1 -0
  214. package/dist/server/tools/registry.js +23 -0
  215. package/dist/server/tools/registry.js.map +1 -0
  216. package/dist/server/tools/subtasks.d.ts +3 -0
  217. package/dist/server/tools/subtasks.d.ts.map +1 -0
  218. package/dist/server/tools/subtasks.js +306 -0
  219. package/dist/server/tools/subtasks.js.map +1 -0
  220. package/dist/server/tools/types.d.ts +7 -0
  221. package/dist/server/tools/types.d.ts.map +1 -0
  222. package/dist/server/tools/types.js +2 -0
  223. package/dist/server/tools/types.js.map +1 -0
  224. package/dist/server/tools/workflow.d.ts +3 -0
  225. package/dist/server/tools/workflow.d.ts.map +1 -0
  226. package/dist/server/tools/workflow.js +434 -0
  227. package/dist/server/tools/workflow.js.map +1 -0
  228. package/dist/services/auth/magic-link.d.ts +27 -0
  229. package/dist/services/auth/magic-link.d.ts.map +1 -0
  230. package/dist/services/auth/magic-link.js +48 -0
  231. package/dist/services/auth/magic-link.js.map +1 -0
  232. package/dist/services/auth/session.d.ts +15 -0
  233. package/dist/services/auth/session.d.ts.map +1 -0
  234. package/dist/services/auth/session.js +65 -0
  235. package/dist/services/auth/session.js.map +1 -0
  236. package/dist/services/cost/claude-code-parser.d.ts +30 -0
  237. package/dist/services/cost/claude-code-parser.d.ts.map +1 -0
  238. package/dist/services/cost/claude-code-parser.js +110 -0
  239. package/dist/services/cost/claude-code-parser.js.map +1 -0
  240. package/dist/services/cost/pricing.d.ts +15 -0
  241. package/dist/services/cost/pricing.d.ts.map +1 -0
  242. package/dist/services/cost/pricing.js +33 -0
  243. package/dist/services/cost/pricing.js.map +1 -0
  244. package/dist/services/digest/generator.d.ts +51 -0
  245. package/dist/services/digest/generator.d.ts.map +1 -0
  246. package/dist/services/digest/generator.js +136 -0
  247. package/dist/services/digest/generator.js.map +1 -0
  248. package/dist/services/digest/scheduler.d.ts +3 -0
  249. package/dist/services/digest/scheduler.d.ts.map +1 -0
  250. package/dist/services/digest/scheduler.js +61 -0
  251. package/dist/services/digest/scheduler.js.map +1 -0
  252. package/dist/services/digest/telegram.d.ts +13 -0
  253. package/dist/services/digest/telegram.d.ts.map +1 -0
  254. package/dist/services/digest/telegram.js +68 -0
  255. package/dist/services/digest/telegram.js.map +1 -0
  256. package/dist/services/embedding/detect.d.ts +19 -0
  257. package/dist/services/embedding/detect.d.ts.map +1 -0
  258. package/dist/services/embedding/detect.js +64 -0
  259. package/dist/services/embedding/detect.js.map +1 -0
  260. package/dist/services/embedding/factory.d.ts +10 -0
  261. package/dist/services/embedding/factory.d.ts.map +1 -0
  262. package/dist/services/embedding/factory.js +79 -0
  263. package/dist/services/embedding/factory.js.map +1 -0
  264. package/dist/services/embedding/ollama.d.ts +14 -0
  265. package/dist/services/embedding/ollama.d.ts.map +1 -0
  266. package/dist/services/embedding/ollama.js +28 -0
  267. package/dist/services/embedding/ollama.js.map +1 -0
  268. package/dist/services/embedding/openai.d.ts +16 -0
  269. package/dist/services/embedding/openai.d.ts.map +1 -0
  270. package/dist/services/embedding/openai.js +33 -0
  271. package/dist/services/embedding/openai.js.map +1 -0
  272. package/dist/services/embedding/store.d.ts +25 -0
  273. package/dist/services/embedding/store.d.ts.map +1 -0
  274. package/dist/services/embedding/store.js +79 -0
  275. package/dist/services/embedding/store.js.map +1 -0
  276. package/dist/services/embedding/types.d.ts +9 -0
  277. package/dist/services/embedding/types.d.ts.map +1 -0
  278. package/dist/services/embedding/types.js +2 -0
  279. package/dist/services/embedding/types.js.map +1 -0
  280. package/dist/services/embedding/vector-math.d.ts +4 -0
  281. package/dist/services/embedding/vector-math.d.ts.map +1 -0
  282. package/dist/services/embedding/vector-math.js +27 -0
  283. package/dist/services/embedding/vector-math.js.map +1 -0
  284. package/dist/services/embedding/voyage.d.ts +16 -0
  285. package/dist/services/embedding/voyage.d.ts.map +1 -0
  286. package/dist/services/embedding/voyage.js +33 -0
  287. package/dist/services/embedding/voyage.js.map +1 -0
  288. package/dist/services/extraction/decision-extractor.d.ts +16 -0
  289. package/dist/services/extraction/decision-extractor.d.ts.map +1 -0
  290. package/dist/services/extraction/decision-extractor.js +111 -0
  291. package/dist/services/extraction/decision-extractor.js.map +1 -0
  292. package/dist/services/extraction/session-summarizer.d.ts +17 -0
  293. package/dist/services/extraction/session-summarizer.d.ts.map +1 -0
  294. package/dist/services/extraction/session-summarizer.js +112 -0
  295. package/dist/services/extraction/session-summarizer.js.map +1 -0
  296. package/dist/services/github/webhook.d.ts +17 -0
  297. package/dist/services/github/webhook.d.ts.map +1 -0
  298. package/dist/services/github/webhook.js +159 -0
  299. package/dist/services/github/webhook.js.map +1 -0
  300. package/dist/services/llm/factory.d.ts +3 -0
  301. package/dist/services/llm/factory.d.ts.map +1 -0
  302. package/dist/services/llm/factory.js +53 -0
  303. package/dist/services/llm/factory.js.map +1 -0
  304. package/dist/services/llm/openai-compat.d.ts +20 -0
  305. package/dist/services/llm/openai-compat.d.ts.map +1 -0
  306. package/dist/services/llm/openai-compat.js +53 -0
  307. package/dist/services/llm/openai-compat.js.map +1 -0
  308. package/dist/services/llm/types.d.ts +23 -0
  309. package/dist/services/llm/types.d.ts.map +1 -0
  310. package/dist/services/llm/types.js +2 -0
  311. package/dist/services/llm/types.js.map +1 -0
  312. package/dist/services/mentions/resolver.d.ts +36 -0
  313. package/dist/services/mentions/resolver.d.ts.map +1 -0
  314. package/dist/services/mentions/resolver.js +97 -0
  315. package/dist/services/mentions/resolver.js.map +1 -0
  316. package/dist/services/plugins/api.d.ts +55 -0
  317. package/dist/services/plugins/api.d.ts.map +1 -0
  318. package/dist/services/plugins/api.js +35 -0
  319. package/dist/services/plugins/api.js.map +1 -0
  320. package/dist/services/plugins/discovery.d.ts +7 -0
  321. package/dist/services/plugins/discovery.d.ts.map +1 -0
  322. package/dist/services/plugins/discovery.js +104 -0
  323. package/dist/services/plugins/discovery.js.map +1 -0
  324. package/dist/services/plugins/marketplace.d.ts +42 -0
  325. package/dist/services/plugins/marketplace.d.ts.map +1 -0
  326. package/dist/services/plugins/marketplace.js +186 -0
  327. package/dist/services/plugins/marketplace.js.map +1 -0
  328. package/dist/services/plugins/registry.d.ts +12 -0
  329. package/dist/services/plugins/registry.d.ts.map +1 -0
  330. package/dist/services/plugins/registry.js +66 -0
  331. package/dist/services/plugins/registry.js.map +1 -0
  332. package/dist/services/plugins/state.d.ts +12 -0
  333. package/dist/services/plugins/state.d.ts.map +1 -0
  334. package/dist/services/plugins/state.js +14 -0
  335. package/dist/services/plugins/state.js.map +1 -0
  336. package/dist/services/push/web-push.d.ts +26 -0
  337. package/dist/services/push/web-push.d.ts.map +1 -0
  338. package/dist/services/push/web-push.js +84 -0
  339. package/dist/services/push/web-push.js.map +1 -0
  340. package/dist/services/relay/client.d.ts +27 -0
  341. package/dist/services/relay/client.d.ts.map +1 -0
  342. package/dist/services/relay/client.js +219 -0
  343. package/dist/services/relay/client.js.map +1 -0
  344. package/dist/services/relay/types.d.ts +19 -0
  345. package/dist/services/relay/types.d.ts.map +1 -0
  346. package/dist/services/relay/types.js +2 -0
  347. package/dist/services/relay/types.js.map +1 -0
  348. package/dist/services/telemetry/client.d.ts +35 -0
  349. package/dist/services/telemetry/client.d.ts.map +1 -0
  350. package/dist/services/telemetry/client.js +125 -0
  351. package/dist/services/telemetry/client.js.map +1 -0
  352. package/dist/services/transcription/whisper.d.ts +16 -0
  353. package/dist/services/transcription/whisper.d.ts.map +1 -0
  354. package/dist/services/transcription/whisper.js +72 -0
  355. package/dist/services/transcription/whisper.js.map +1 -0
  356. package/docs/architecture.md +108 -0
  357. package/docs/configuration.md +73 -0
  358. package/docs/cursor-quirks.md +42 -0
  359. package/docs/embedding-providers.md +110 -0
  360. package/docs/github-integration.md +109 -0
  361. package/docs/plugin-development.md +104 -0
  362. package/docs/plugins.md +104 -0
  363. package/docs/relay.md +108 -0
  364. package/docs/remote-access.md +218 -0
  365. package/docs/sponsorship.md +54 -0
  366. package/migrations/.gitkeep +0 -0
  367. package/migrations/0001_initial_schema.sql +284 -0
  368. package/migrations/0002_activity_and_links.sql +26 -0
  369. package/migrations/0003_workspace.sql +7 -0
  370. package/migrations/0004_decision_drafts.sql +28 -0
  371. package/migrations/0005_project_summaries.sql +10 -0
  372. package/migrations/0006_push_and_approvals.sql +37 -0
  373. package/migrations/0007_session_costs.sql +17 -0
  374. package/migrations/0008_pr_links.sql +22 -0
  375. package/migrations/0009_telemetry.sql +17 -0
  376. package/migrations/0010_users_and_members.sql +40 -0
  377. package/migrations/0011_assignments_mentions.sql +20 -0
  378. 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.
@@ -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