cartethyia 2.5.10 → 2.6.1

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 (369) hide show
  1. package/.env.example +8 -0
  2. package/dist/dashboard/assets/{BannedPage-Cd30Z0b9.js → BannedPage-wr370U7a.js} +1 -1
  3. package/dist/dashboard/assets/BannedPage-wr370U7a.js.gz +0 -0
  4. package/dist/dashboard/assets/{CliToolDetailPage-wf5u-ww6.js → CliToolDetailPage-D1sCezWa.js} +1 -1
  5. package/dist/dashboard/assets/CliToolDetailPage-D1sCezWa.js.gz +0 -0
  6. package/dist/dashboard/assets/{CliToolsPage-DykPvuck.js → CliToolsPage-DVWbJPEQ.js} +1 -1
  7. package/dist/dashboard/assets/CliToolsPage-DVWbJPEQ.js.gz +0 -0
  8. package/dist/dashboard/assets/{CombosPage-DwvSD3vs.js → CombosPage-CZc7fyMe.js} +1 -1
  9. package/dist/dashboard/assets/CombosPage-CZc7fyMe.js.gz +0 -0
  10. package/dist/dashboard/assets/{ConsoleLogPage-CIr7KDex.js → ConsoleLogPage-OPN3qRCa.js} +1 -1
  11. package/dist/dashboard/assets/ConsoleLogPage-OPN3qRCa.js.gz +0 -0
  12. package/dist/dashboard/assets/{CustomizationPage-82X0DDdH.js → CustomizationPage-DGTSqmwm.js} +1 -1
  13. package/dist/dashboard/assets/CustomizationPage-DGTSqmwm.js.gz +0 -0
  14. package/dist/dashboard/assets/HealthEventsModal-BujG2QP4.js +1 -0
  15. package/dist/dashboard/assets/HealthEventsModal-BujG2QP4.js.gz +0 -0
  16. package/dist/dashboard/assets/{LoginPage-CS5mPuVF.js → LoginPage-C_Jd_KgP.js} +1 -1
  17. package/dist/dashboard/assets/LoginPage-C_Jd_KgP.js.gz +0 -0
  18. package/dist/dashboard/assets/{ModelPicker-C0UCUsVJ.js → ModelPicker-DVny4S5_.js} +1 -1
  19. package/dist/dashboard/assets/ModelPicker-DVny4S5_.js.gz +0 -0
  20. package/dist/dashboard/assets/OverviewPage-Bpbu-VeU.js +1 -0
  21. package/dist/dashboard/assets/OverviewPage-Bpbu-VeU.js.gz +0 -0
  22. package/dist/dashboard/assets/ProviderDetailPage-BEhXOO4L.js +3 -0
  23. package/dist/dashboard/assets/ProviderDetailPage-BEhXOO4L.js.gz +0 -0
  24. package/dist/dashboard/assets/{ProvidersPage-vdja5ZPK.js → ProvidersPage-DbQnexQd.js} +1 -1
  25. package/dist/dashboard/assets/ProvidersPage-DbQnexQd.js.gz +0 -0
  26. package/dist/dashboard/assets/{ProxyPage-BB4CNm4-.js → ProxyPage-ByprzADo.js} +1 -1
  27. package/dist/dashboard/assets/ProxyPage-ByprzADo.js.gz +0 -0
  28. package/dist/dashboard/assets/QuotaPage-CvSfv6tP.js +1 -0
  29. package/dist/dashboard/assets/QuotaPage-CvSfv6tP.js.gz +0 -0
  30. package/dist/dashboard/assets/SettingsPage-_NzLq3C-.js +1 -0
  31. package/dist/dashboard/assets/SettingsPage-_NzLq3C-.js.gz +0 -0
  32. package/dist/dashboard/assets/{SetupPage-FadUOl9S.js → SetupPage-Bg9DcG-G.js} +1 -1
  33. package/dist/dashboard/assets/SetupPage-Bg9DcG-G.js.gz +0 -0
  34. package/dist/dashboard/assets/{SortableList-Cfy6_Khv.js → SortableList-C2PWPzJm.js} +1 -1
  35. package/dist/dashboard/assets/SortableList-C2PWPzJm.js.gz +0 -0
  36. package/dist/dashboard/assets/{StudioPage-CM92fgJf.js → StudioPage-Dky1zZMt.js} +1 -1
  37. package/dist/dashboard/assets/StudioPage-Dky1zZMt.js.gz +0 -0
  38. package/dist/dashboard/assets/{UsagePage-BT4MyQeT.js → UsagePage-C5Vdpd_c.js} +2 -2
  39. package/dist/dashboard/assets/UsagePage-C5Vdpd_c.js.gz +0 -0
  40. package/dist/dashboard/assets/{api-keys-DQYLQxpW.js → api-keys-C23S9sgp.js} +1 -1
  41. package/dist/dashboard/assets/api-keys-C23S9sgp.js.gz +0 -0
  42. package/dist/dashboard/assets/{app-B7pVRhJ1.js → app-2KhtHCv9.js} +1 -1
  43. package/dist/dashboard/assets/{app-B7pVRhJ1.js.gz → app-2KhtHCv9.js.gz} +0 -0
  44. package/dist/dashboard/assets/app-CEeaMHOy.css +2 -0
  45. package/dist/dashboard/assets/app-CEeaMHOy.css.gz +0 -0
  46. package/dist/dashboard/assets/{assert-C9FD_JwJ.js → assert-DU6qrMA_.js} +1 -1
  47. package/dist/dashboard/assets/assert-DU6qrMA_.js.gz +0 -0
  48. package/dist/dashboard/assets/{badge-Bvyr7D0u.js → badge-CKsF123d.js} +1 -1
  49. package/dist/dashboard/assets/badge-CKsF123d.js.gz +0 -0
  50. package/dist/dashboard/assets/{banner-DIvKAZih.js → banner-8j7uChA9.js} +1 -1
  51. package/dist/dashboard/assets/banner-8j7uChA9.js.gz +0 -0
  52. package/dist/dashboard/assets/{card-D5_gYIS_.js → card-CdsSlWA3.js} +1 -1
  53. package/dist/dashboard/assets/card-CdsSlWA3.js.gz +0 -0
  54. package/dist/dashboard/assets/{cli-tools-CNqzrfdb.js → cli-tools-BaFUuFFF.js} +1 -1
  55. package/dist/dashboard/assets/cli-tools-BaFUuFFF.js.gz +0 -0
  56. package/dist/dashboard/assets/{clipboard-button-B6vDBtbm.js → clipboard-button-uL5aYLfW.js} +1 -1
  57. package/dist/dashboard/assets/clipboard-button-uL5aYLfW.js.gz +0 -0
  58. package/dist/dashboard/assets/{dialog-CpjrgdwJ.js → dialog-C07hr5_G.js} +1 -1
  59. package/dist/dashboard/assets/dialog-C07hr5_G.js.gz +0 -0
  60. package/dist/dashboard/assets/{drawer-BWmt3b5y.js → drawer-BPO1TcKH.js} +1 -1
  61. package/dist/dashboard/assets/drawer-BPO1TcKH.js.gz +0 -0
  62. package/dist/dashboard/assets/entry-BNFjUjQ0.js +4 -0
  63. package/dist/dashboard/assets/entry-BNFjUjQ0.js.gz +0 -0
  64. package/dist/dashboard/assets/{entry-C_oakV3z.js → entry-Bz_CtDfC.js} +1 -1
  65. package/dist/dashboard/assets/entry-Bz_CtDfC.js.gz +0 -0
  66. package/dist/dashboard/assets/entry-GJRbmrpA.js +1 -0
  67. package/dist/dashboard/assets/entry-GJRbmrpA.js.gz +0 -0
  68. package/dist/dashboard/assets/{github-badge-RRHHWGxh.js → github-badge-DmQreSDd.js} +1 -1
  69. package/dist/dashboard/assets/github-badge-DmQreSDd.js.gz +0 -0
  70. package/dist/dashboard/assets/{index-Bhey_rg_.js → index-DyllNVCY.js} +2 -2
  71. package/dist/dashboard/assets/index-DyllNVCY.js.gz +0 -0
  72. package/dist/dashboard/assets/{inline-C2_EQ5Uf.js → inline-C9dCYaBZ.js} +1 -1
  73. package/dist/dashboard/assets/inline-C9dCYaBZ.js.gz +0 -0
  74. package/dist/dashboard/assets/{input-BMRlQ450.js → input-CjCnXweJ.js} +1 -1
  75. package/dist/dashboard/assets/input-CjCnXweJ.js.gz +0 -0
  76. package/dist/dashboard/assets/{layout-XR5xP8ew.js → layout-V6y8DAkl.js} +1 -1
  77. package/dist/dashboard/assets/layout-V6y8DAkl.js.gz +0 -0
  78. package/dist/dashboard/assets/{list-row-Cw07dioc.js → list-row-CM1AaG_y.js} +1 -1
  79. package/dist/dashboard/assets/list-row-CM1AaG_y.js.gz +0 -0
  80. package/dist/dashboard/assets/{live-BivGfuUs.js → live-ta6GMb-8.js} +1 -1
  81. package/dist/dashboard/assets/live-ta6GMb-8.js.gz +0 -0
  82. package/dist/dashboard/assets/{model-bans-CmffjLuG.js → model-bans-BmYTmbAk.js} +1 -1
  83. package/dist/dashboard/assets/model-bans-BmYTmbAk.js.gz +0 -0
  84. package/dist/dashboard/assets/{mutation-46P0oWMe.js → mutation-g_fduiNw.js} +1 -1
  85. package/dist/dashboard/assets/mutation-g_fduiNw.js.gz +0 -0
  86. package/dist/dashboard/assets/{numbers-DrdA9oSM.js → numbers-BOevJzdz.js} +1 -1
  87. package/dist/dashboard/assets/numbers-BOevJzdz.js.gz +0 -0
  88. package/dist/dashboard/assets/{query-keys-BFhGpwR1.js → query-keys-UETqfytp.js} +1 -1
  89. package/dist/dashboard/assets/query-keys-UETqfytp.js.gz +0 -0
  90. package/dist/dashboard/assets/{routing-CAb4F37R.js → routing-BPUo-W8d.js} +1 -1
  91. package/dist/dashboard/assets/routing-BPUo-W8d.js.gz +0 -0
  92. package/dist/dashboard/assets/{select-CxVVB__N.js → select-DAhoTabv.js} +1 -1
  93. package/dist/dashboard/assets/select-DAhoTabv.js.gz +0 -0
  94. package/dist/dashboard/assets/{settings-DNX9sydi.js → settings--3hxSyry.js} +1 -1
  95. package/dist/dashboard/assets/settings--3hxSyry.js.gz +0 -0
  96. package/dist/dashboard/assets/{stack-uPOwM9Hs.js → stack-_gfTdLVB.js} +1 -1
  97. package/dist/dashboard/assets/stack-_gfTdLVB.js.gz +0 -0
  98. package/dist/dashboard/assets/{state-D1Yz79iL.js → state-2c5V4zo7.js} +1 -1
  99. package/dist/dashboard/assets/state-2c5V4zo7.js.gz +0 -0
  100. package/dist/dashboard/assets/{switch-sevsRrRo.js → switch-Dkke7Naf.js} +1 -1
  101. package/dist/dashboard/assets/switch-Dkke7Naf.js.gz +0 -0
  102. package/dist/dashboard/assets/{useMutation-Dem0lXQj.js → useMutation-EDFRkn1i.js} +1 -1
  103. package/dist/dashboard/assets/useMutation-EDFRkn1i.js.gz +0 -0
  104. package/dist/dashboard/index.html +1 -1
  105. package/dist/dashboard/index.html.gz +0 -0
  106. package/dist/dashboard/precompressed-assets.json +51 -51
  107. package/migrations/README.md +52 -52
  108. package/migrations/full-postgres/0020_add_telemetry_event_analytics.sql +77 -0
  109. package/migrations/full-postgres/0021_add_api_key_concurrency_tolerance.sql +13 -0
  110. package/migrations/full-postgres/0022_add_inferhub_config_key.sql +17 -0
  111. package/migrations/full-postgres/0023_drop_api_key_concurrency_tolerance.sql +13 -0
  112. package/migrations/lite-sqlite3/0020_add_telemetry_event_analytics.sql +69 -0
  113. package/migrations/lite-sqlite3/0021_add_api_key_concurrency_tolerance.sql +13 -0
  114. package/migrations/lite-sqlite3/0022_add_inferhub_config_key.sql +17 -0
  115. package/migrations/lite-sqlite3/0023_drop_api_key_concurrency_tolerance.sql +13 -0
  116. package/package.json +96 -95
  117. package/scripts/cli/admin.ts +126 -128
  118. package/scripts/cli/autostart.ts +237 -237
  119. package/scripts/cli/background.ts +123 -110
  120. package/scripts/cli/bin/carte.cjs +8 -8
  121. package/scripts/cli/bin/cartethyia.cjs +177 -167
  122. package/scripts/cli/console-menu.ts +45 -30
  123. package/scripts/cli/controller.ts +145 -0
  124. package/scripts/cli/env.ts +99 -99
  125. package/scripts/cli/gateway.ts +264 -260
  126. package/scripts/cli/instance.ts +234 -224
  127. package/scripts/cli/main.ts +195 -167
  128. package/scripts/cli/platform.ts +64 -64
  129. package/scripts/cli/prompt.ts +217 -79
  130. package/scripts/cli/services.ts +88 -88
  131. package/scripts/cli/setup.ts +445 -445
  132. package/scripts/cli/start.ts +85 -85
  133. package/scripts/cli/startup-signal.ts +23 -23
  134. package/scripts/cli/telemetry.ts +70 -0
  135. package/scripts/cli/tray/hidden-window.vbs +16 -2
  136. package/scripts/cli/tray/index.ts +263 -263
  137. package/scripts/cli/tray/windows.ps1 +107 -107
  138. package/scripts/cli/tray.ts +29 -4
  139. package/scripts/cli/update.ts +39 -39
  140. package/scripts/cli/version.ts +67 -67
  141. package/scripts/cli/wordmark.ts +58 -58
  142. package/src/boot/app.ts +16 -1
  143. package/src/boot/dependencies.ts +128 -25
  144. package/src/config/resources.ts +137 -0
  145. package/src/config/runtime.ts +133 -76
  146. package/src/config/spec.ts +30 -29
  147. package/src/config/telemetry.ts +0 -25
  148. package/src/console/api-keys/bucket-spend.ts +14 -17
  149. package/src/console/api-keys/contracts.ts +410 -410
  150. package/src/console/api-keys/routes.ts +12 -0
  151. package/src/console/audit/store.ts +2 -3
  152. package/src/console/auth/setup-service.ts +8 -1
  153. package/src/console/backup/routes.ts +7 -0
  154. package/src/console/backup/service.ts +463 -463
  155. package/src/console/backup/store.ts +16 -11
  156. package/src/console/backup/validate.ts +1 -4
  157. package/src/console/cli-tools/fs-ops.ts +18 -2
  158. package/src/console/data-management/contracts.ts +1 -8
  159. package/src/console/data-management/operations.ts +61 -48
  160. package/src/console/data-management/routes.ts +4 -2
  161. package/src/console/domain-registration.ts +25 -3
  162. package/src/console/inferhub/client.ts +139 -0
  163. package/src/console/inferhub/key-store.ts +129 -0
  164. package/src/console/inferhub/normalize.ts +347 -0
  165. package/src/console/inferhub/routes.ts +411 -0
  166. package/src/console/inferhub/store.ts +109 -0
  167. package/src/console/inferhub/types.ts +183 -0
  168. package/src/console/observability/contracts.ts +2 -41
  169. package/src/console/observability/store.ts +176 -371
  170. package/src/console/providers/catalog/public-model-store.ts +0 -0
  171. package/src/console/providers/catalog/store.ts +23 -36
  172. package/src/console/quota/account-quota-shared.ts +52 -52
  173. package/src/console/quota/account-quota-tenant.ts +16 -24
  174. package/src/console/quota/refresh.ts +441 -441
  175. package/src/console/routing/pools/import-parse.ts +206 -206
  176. package/src/console/routing/pools/operations.ts +543 -543
  177. package/src/console/routing/pools/probe-verdict.ts +132 -132
  178. package/src/console/routing/pools/routes.ts +181 -181
  179. package/src/console/settings/contracts.ts +42 -40
  180. package/src/console/settings/store.ts +25 -25
  181. package/src/console/share/share-stats.ts +22 -4
  182. package/src/console/share/share-usage.ts +30 -4
  183. package/src/console/shared/cursor.ts +15 -0
  184. package/src/console/updates/routes.ts +12 -0
  185. package/src/main.ts +13 -5
  186. package/src/network/pool/resolver.ts +1104 -1104
  187. package/src/observability/client-name.ts +22 -0
  188. package/src/observability/event-log.ts +5 -29
  189. package/src/observability/event-query.ts +690 -0
  190. package/src/observability/log-ring.ts +26 -2
  191. package/src/observability/log-sanitize.ts +118 -0
  192. package/src/observability/logger.ts +17 -13
  193. package/src/observability/metrics.ts +35 -0
  194. package/src/observability/payload-capture.ts +114 -41
  195. package/src/observability/payload-store.ts +249 -24
  196. package/src/observability/raw-event-writer.ts +118 -0
  197. package/src/observability/runtime-metrics.ts +71 -1
  198. package/src/observability/telemetry-buffer.ts +100 -17
  199. package/src/observability/telemetry-reconciliation.ts +417 -0
  200. package/src/persistence/boot.ts +20 -9
  201. package/src/persistence/db-pg.ts +13 -0
  202. package/src/persistence/db-sqlite.ts +569 -497
  203. package/src/persistence/dialect.ts +3 -2
  204. package/src/persistence/migrate.ts +181 -181
  205. package/src/persistence/schema.ts +1496 -1406
  206. package/src/persistence/shared-cache.ts +5 -1
  207. package/src/persistence/stores/api-key-store.ts +581 -581
  208. package/src/persistence/stores/telemetry-store.ts +124 -63
  209. package/src/protocol/reasoning-text.ts +30 -0
  210. package/src/protocol/response/chat.ts +33 -7
  211. package/src/protocol/response/codex.ts +14 -2
  212. package/src/protocol/response/messages.ts +5 -2
  213. package/src/providers/authentication/oauth-flow-store.ts +3 -10
  214. package/src/providers/bundled-discovery-providers.ts +122 -122
  215. package/src/providers/default-registry.ts +10 -0
  216. package/src/providers/discovery/catalog/catalog-blob.ts +18 -18
  217. package/src/providers/discovery/models-dev-catalog.ts +354 -354
  218. package/src/providers/discovery/probe-phases.ts +43 -7
  219. package/src/providers/discovery/probing-service.ts +70 -32
  220. package/src/providers/integrations/antigravity/antigravity.ts +9 -2
  221. package/src/providers/integrations/buddy/buddy-catalog-shared.ts +85 -17
  222. package/src/providers/integrations/buddy/buddy-chat-shared.ts +934 -934
  223. package/src/providers/integrations/buddy/buddy-checkin.ts +5 -9
  224. package/src/providers/integrations/buddy/buddy-discovery-shared.ts +3 -7
  225. package/src/providers/integrations/buddy/buddy-quota-shared.ts +3 -1
  226. package/src/providers/integrations/buddy/codebuddy/cn-provider.ts +57 -49
  227. package/src/providers/integrations/buddy/codebuddy/provider.ts +180 -180
  228. package/src/providers/integrations/buddy/workbuddy/provider.ts +206 -206
  229. package/src/providers/integrations/buddy/workbuddy/quota.ts +161 -161
  230. package/src/providers/integrations/claude/claude-quota.ts +2 -2
  231. package/src/providers/integrations/claude/claude-user-profiles.ts +3 -2
  232. package/src/providers/integrations/claude/claude.ts +3 -4
  233. package/src/providers/integrations/cline/cline.ts +94 -8
  234. package/src/providers/integrations/codex/codex.ts +61 -37
  235. package/src/providers/integrations/cursor/cursor-catalog.ts +368 -368
  236. package/src/providers/integrations/cursor/cursor-http2.ts +300 -300
  237. package/src/providers/integrations/cursor/cursor-identity.ts +2 -4
  238. package/src/providers/integrations/cursor/cursor-request.ts +11 -0
  239. package/src/providers/integrations/cursor/cursor.ts +29 -17
  240. package/src/providers/integrations/cursor/protocol/framing.ts +129 -129
  241. package/src/providers/integrations/cursor/protocol/messages.ts +2380 -2380
  242. package/src/providers/integrations/cursor/protocol/struct.ts +305 -305
  243. package/src/providers/integrations/cursor/protocol/tool-canonical.ts +275 -0
  244. package/src/providers/integrations/grok/grok-quota.ts +279 -279
  245. package/src/providers/integrations/grok/grok-ratelimit-store.ts +73 -73
  246. package/src/providers/integrations/grok/grok-ratelimit.ts +218 -218
  247. package/src/providers/integrations/hermes.ts +7 -1
  248. package/src/providers/integrations/inferhub.ts +201 -73
  249. package/src/providers/integrations/kilo/kilo.ts +152 -152
  250. package/src/providers/integrations/kiro/kiro-machine-id.ts +2 -4
  251. package/src/providers/integrations/openrouter/provider.ts +129 -129
  252. package/src/providers/integrations/qoder/qoder-quota.ts +193 -192
  253. package/src/providers/integrations/qoder/qoder-realm.ts +106 -106
  254. package/src/providers/integrations/trae/trae-oauth.ts +4 -26
  255. package/src/providers/integrations/trae/trae-quota.ts +389 -384
  256. package/src/providers/integrations/trae/trae-realm.ts +15 -2
  257. package/src/providers/integrations/xiaomi-mimo/think-stream.ts +100 -24
  258. package/src/providers/integrations/zcode/oauth.ts +1 -1
  259. package/src/providers/operations/account-health-service.ts +605 -279
  260. package/src/providers/provider-metadata.ts +12 -1
  261. package/src/providers/provider-model-definition.ts +373 -373
  262. package/src/providers/quota/quota-contracts.ts +3 -7
  263. package/src/providers/search/search-provider.ts +2 -6
  264. package/src/security/admission/contracts.ts +10 -0
  265. package/src/security/admission/in-memory-store.ts +89 -14
  266. package/src/security/admission/lua.ts +191 -182
  267. package/src/security/admission/redis-store.ts +30 -0
  268. package/src/security/admission/service.ts +18 -0
  269. package/src/security/api-key-auth-cache.ts +96 -0
  270. package/src/security/api-key-auth.ts +11 -100
  271. package/src/security/client-router-fingerprint.ts +3 -7
  272. package/src/security/ip-boundary.ts +7 -3
  273. package/src/shared/coerce.ts +67 -0
  274. package/src/shared/hash.ts +6 -0
  275. package/src/shared/time.ts +7 -0
  276. package/src/transport/dispatch/attempt-finalize.ts +26 -138
  277. package/src/transport/dispatch/attempt-loop.ts +103 -81
  278. package/src/transport/dispatch/capture-policy.ts +78 -0
  279. package/src/transport/dispatch/proxy-request.ts +4 -2
  280. package/src/transport/dispatch/streaming/encoder.ts +111 -5
  281. package/src/transport/dispatch/streaming/stream.ts +19 -2
  282. package/src/transport/dispatch/streaming/thinking-loop.ts +300 -0
  283. package/src/transport/failure-policy.ts +27 -0
  284. package/src/transport/guards/abuse-guard.ts +2 -2
  285. package/src/transport/guards/auth-guard.ts +17 -0
  286. package/src/transport/guards/body-policy.ts +3 -2
  287. package/src/transport/guards/concurrency-guard.ts +89 -13
  288. package/src/transport/guards/early-rejection-capture.ts +43 -3
  289. package/src/transport/guards/error-lifecycle.ts +10 -2
  290. package/src/transport/guards/guard-errors.ts +23 -0
  291. package/src/transport/guards/headroom-guard.ts +41 -7
  292. package/src/transport/guards/pipeline.ts +24 -0
  293. package/src/transport/guards/request-context.ts +2 -1
  294. package/src/transport/routing/admission.ts +51 -9
  295. package/src/transport/routing/bounded-lru.ts +49 -0
  296. package/src/transport/routing/candidate-index.ts +88 -0
  297. package/src/transport/routing/reservations.ts +121 -7
  298. package/src/transport/routing/round-robin.ts +10 -22
  299. package/src/transport/routing/route-catalog.ts +26 -13
  300. package/src/transport/routing/route-model.ts +22 -2
  301. package/src/transport/routing/router.ts +53 -31
  302. package/src/transport/surface/chat/encode.ts +2 -3
  303. package/src/transport/surface/chat/parse.ts +2 -1
  304. package/src/transport/surface/dialects.ts +11 -3
  305. package/src/transport/surface/messages/encode.ts +2 -1
  306. package/src/transport/surface/messages/parse.ts +3 -1
  307. package/src/transport/surface/messages/stream.ts +2 -6
  308. package/src/workers/maintenance-lease.ts +200 -0
  309. package/src/workers/scheduler.ts +101 -1
  310. package/dist/dashboard/assets/BannedPage-Cd30Z0b9.js.gz +0 -0
  311. package/dist/dashboard/assets/CliToolDetailPage-wf5u-ww6.js.gz +0 -0
  312. package/dist/dashboard/assets/CliToolsPage-DykPvuck.js.gz +0 -0
  313. package/dist/dashboard/assets/CombosPage-DwvSD3vs.js.gz +0 -0
  314. package/dist/dashboard/assets/ConsoleLogPage-CIr7KDex.js.gz +0 -0
  315. package/dist/dashboard/assets/CustomizationPage-82X0DDdH.js.gz +0 -0
  316. package/dist/dashboard/assets/HealthEventsModal-BYPucTTn.js +0 -1
  317. package/dist/dashboard/assets/HealthEventsModal-BYPucTTn.js.gz +0 -0
  318. package/dist/dashboard/assets/LoginPage-CS5mPuVF.js.gz +0 -0
  319. package/dist/dashboard/assets/ModelPicker-C0UCUsVJ.js.gz +0 -0
  320. package/dist/dashboard/assets/OverviewPage-Dk_ew3YU.js +0 -1
  321. package/dist/dashboard/assets/OverviewPage-Dk_ew3YU.js.gz +0 -0
  322. package/dist/dashboard/assets/ProviderDetailPage-CAiRn2Q0.js +0 -3
  323. package/dist/dashboard/assets/ProviderDetailPage-CAiRn2Q0.js.gz +0 -0
  324. package/dist/dashboard/assets/ProvidersPage-vdja5ZPK.js.gz +0 -0
  325. package/dist/dashboard/assets/ProxyPage-BB4CNm4-.js.gz +0 -0
  326. package/dist/dashboard/assets/QuotaPage-FEc4iNyq.js +0 -1
  327. package/dist/dashboard/assets/QuotaPage-FEc4iNyq.js.gz +0 -0
  328. package/dist/dashboard/assets/SettingsPage-Dlfi5L4N.js +0 -1
  329. package/dist/dashboard/assets/SettingsPage-Dlfi5L4N.js.gz +0 -0
  330. package/dist/dashboard/assets/SetupPage-FadUOl9S.js.gz +0 -0
  331. package/dist/dashboard/assets/SortableList-Cfy6_Khv.js.gz +0 -0
  332. package/dist/dashboard/assets/StudioPage-CM92fgJf.js.gz +0 -0
  333. package/dist/dashboard/assets/UsagePage-BT4MyQeT.js.gz +0 -0
  334. package/dist/dashboard/assets/api-keys-DQYLQxpW.js.gz +0 -0
  335. package/dist/dashboard/assets/app-CX_Z8cMs.css +0 -2
  336. package/dist/dashboard/assets/app-CX_Z8cMs.css.gz +0 -0
  337. package/dist/dashboard/assets/assert-C9FD_JwJ.js.gz +0 -0
  338. package/dist/dashboard/assets/badge-Bvyr7D0u.js.gz +0 -0
  339. package/dist/dashboard/assets/banner-DIvKAZih.js.gz +0 -0
  340. package/dist/dashboard/assets/card-D5_gYIS_.js.gz +0 -0
  341. package/dist/dashboard/assets/cli-tools-CNqzrfdb.js.gz +0 -0
  342. package/dist/dashboard/assets/clipboard-button-B6vDBtbm.js.gz +0 -0
  343. package/dist/dashboard/assets/dialog-CpjrgdwJ.js.gz +0 -0
  344. package/dist/dashboard/assets/drawer-BWmt3b5y.js.gz +0 -0
  345. package/dist/dashboard/assets/entry-B-gvimrg.js +0 -1
  346. package/dist/dashboard/assets/entry-B-gvimrg.js.gz +0 -0
  347. package/dist/dashboard/assets/entry-C_oakV3z.js.gz +0 -0
  348. package/dist/dashboard/assets/entry-Dj0cHfEc.js +0 -4
  349. package/dist/dashboard/assets/entry-Dj0cHfEc.js.gz +0 -0
  350. package/dist/dashboard/assets/github-badge-RRHHWGxh.js.gz +0 -0
  351. package/dist/dashboard/assets/index-Bhey_rg_.js.gz +0 -0
  352. package/dist/dashboard/assets/inline-C2_EQ5Uf.js.gz +0 -0
  353. package/dist/dashboard/assets/input-BMRlQ450.js.gz +0 -0
  354. package/dist/dashboard/assets/layout-XR5xP8ew.js.gz +0 -0
  355. package/dist/dashboard/assets/list-row-Cw07dioc.js.gz +0 -0
  356. package/dist/dashboard/assets/live-BivGfuUs.js.gz +0 -0
  357. package/dist/dashboard/assets/model-bans-CmffjLuG.js.gz +0 -0
  358. package/dist/dashboard/assets/mutation-46P0oWMe.js.gz +0 -0
  359. package/dist/dashboard/assets/numbers-DrdA9oSM.js.gz +0 -0
  360. package/dist/dashboard/assets/query-keys-BFhGpwR1.js.gz +0 -0
  361. package/dist/dashboard/assets/routing-CAb4F37R.js.gz +0 -0
  362. package/dist/dashboard/assets/select-CxVVB__N.js.gz +0 -0
  363. package/dist/dashboard/assets/settings-DNX9sydi.js.gz +0 -0
  364. package/dist/dashboard/assets/stack-uPOwM9Hs.js.gz +0 -0
  365. package/dist/dashboard/assets/state-D1Yz79iL.js.gz +0 -0
  366. package/dist/dashboard/assets/switch-sevsRrRo.js.gz +0 -0
  367. package/dist/dashboard/assets/useMutation-Dem0lXQj.js.gz +0 -0
  368. package/src/observability/event-compaction.ts +0 -317
  369. package/src/observability/event-day-index.ts +0 -439
@@ -1,167 +1,195 @@
1
- // dynamic-import-ok: subcommand dispatcher. Every branch lazy-loads only the
2
- // module its command needs so `cartethyia --help` and `cartethyia stop` do
3
- // not drag the gateway, dashboard, and database driver into memory.
4
- import { mkdirSync } from "node:fs";
5
- import { resolveUserConfigDir } from "../../src/config/package-paths";
6
- import { readRequiredBunVersion, assertBunVersion } from "./version";
7
- import { printUpdateInstructions, runDetachedUpdate } from "./update";
8
-
9
- process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
10
-
11
- const HELP = (minimumBunVersion: string) => `Cartethyia ${minimumBunVersion}+ (Bun is required)
12
-
13
- Usage:
14
- carte start, then show an arrow-key menu (no GUI needed)
15
- carte --tray start with a system-tray icon instead
16
- cartethyia setup [--non-interactive]
17
- cartethyia start
18
- cartethyia stop
19
- cartethyia menu
20
- cartethyia doctor
21
- cartethyia admin reset-lockout <username> <clientIp>
22
- cartethyia admin reset-lockout --all
23
- cartethyia update
24
-
25
- carte starts the gateway in the background and leaves only the console menu on
26
- your terminal — Open Console, Reset password, Backup, Update, Hide to tray,
27
- Exit. Arrow keys and Enter; no desktop environment needed, so it works over SSH
28
- and headless. A menu started by this command drains its child gateway on Exit;
29
- leaving a menu attached to an existing gateway only detaches. Use stop for that.
30
- carte --tray uses a system-tray icon instead, which needs a graphical session.
31
- Stop a detached gateway with cartethyia stop (or the install's ./carte stop).
32
- Setup explains Lite (embedded SQLite) and Full (external PostgreSQL), then saves
33
- configuration under the current user's Cartethyia config directory.
34
- `;
35
-
36
- /** Loads the user's `.env` into the environment without overriding it. */
37
- async function loadUserConfig(): Promise<void> {
38
- const configDir = process.env.CARTETHYIA_CONFIG_DIR;
39
- if (!configDir) throw new Error("Cartethyia config directory could not be resolved");
40
- mkdirSync(configDir, { recursive: true });
41
- // Imported here rather than at module scope: `support/env` pulls in the
42
- // package-root resolver and `node:fs/promises`, and `carte --help` (which
43
- // never reads a .env) should not pay for either before it prints.
44
- const { ENV_PATH, readEnvFile } = await import("./env");
45
- // Bun injects PORT=12800 when no explicit port was supplied. It is a
46
- // runner default, not an operator override; without removing it, a saved
47
- // custom port is ignored by npm/carte and the gateway starts on 12800.
48
- // Preserve any non-default/custom shell value exactly as before.
49
- if (process.env.PORT === "12800") delete process.env.PORT;
50
- const values = await readEnvFile(ENV_PATH);
51
- for (const [key, value] of Object.entries(values)) {
52
- if (!process.env[key]) process.env[key] = value;
53
- }
54
- }
55
-
56
- /**
57
- * Reports tray readiness to the launcher waiting on a signal file.
58
- *
59
- * Deferred to a dynamic import for the same reason as `loadUserConfig`: only
60
- * the tray path writes this file, so the other commands should not load
61
- * `node:fs` machinery they never touch.
62
- */
63
- async function reportTrayFailed(message: string): Promise<void> {
64
- const { reportTrayStartup } = await import("./startup-signal");
65
- reportTrayStartup({ status: "failed", message });
66
- }
67
-
68
- async function main(): Promise<void> {
69
- await assertBunVersion();
70
- const [command] = process.argv.slice(2);
71
- if (command === "setup" || command === "start" || command === "stop" || command === "tray" || command === "menu" || command === "doctor" || command === "admin") {
72
- await loadUserConfig();
73
- }
74
-
75
- switch (command) {
76
- case "setup": {
77
- const { setup } = await import("./setup");
78
- await setup();
79
- return;
80
- }
81
- case "start": {
82
- const { startForeground } = await import("./start");
83
- await startForeground();
84
- return;
85
- }
86
- case "stop": {
87
- const { resolvePort } = await import("../../src/config/runtime");
88
- const { ensureDrainToken, attachGateway, stopAttachedGateway } = await import("./instance");
89
- const port = resolvePort();
90
- const token = ensureDrainToken();
91
- const gateway = await attachGateway(port, token);
92
- if (!gateway) {
93
- console.log("No running Cartethyia gateway is owned by this installation.");
94
- return;
95
- }
96
- await stopAttachedGateway(gateway, token);
97
- console.log("Cartethyia stopped.");
98
- return;
99
- }
100
- case "menu": {
101
- const { startMenu } = await import("./console-menu");
102
- await startMenu();
103
- return;
104
- }
105
- case "tray": {
106
- const { startTray } = await import("./tray");
107
- await startTray();
108
- return;
109
- }
110
- case "autostart": {
111
- const { enableAutostart, disableAutostart, autostartStatus } = await import("./autostart");
112
- const arg = Bun.argv[3]?.trim();
113
- if (arg === "off" || arg === "disable") {
114
- const state = await disableAutostart();
115
- console.log(`Autostart disabled (${state.location || state.platform}).`);
116
- return;
117
- }
118
- if (arg === "status") {
119
- const state = autostartStatus();
120
- console.log(
121
- `Autostart: ${state.enabled ? "enabled" : "not enabled"} — ${state.location || state.platform}` +
122
- (state.reason ? ` (${state.reason})` : ""),
123
- );
124
- return;
125
- }
126
- // The tray is what autostart launches: a gateway alone has no session to
127
- // attach to and no icon to show.
128
- const state = await enableAutostart(process.execPath, [Bun.argv[1] ?? "carte", "tray"]);
129
- console.log(
130
- state.enabled
131
- ? `Autostart enabled — ${state.location}`
132
- : `Autostart not enabled: ${state.reason ?? "unknown reason"}`,
133
- );
134
- return;
135
- }
136
- case "doctor": {
137
- const { doctor } = await import("./doctor");
138
- await doctor();
139
- return;
140
- }
141
- case "admin": {
142
- if (process.argv[3] !== "reset-lockout") throw new Error("Usage: cartethyia admin reset-lockout <username> <clientIp> | --all");
143
- const { resetLockout } = await import("./admin");
144
- await resetLockout(process.argv.slice(4));
145
- return;
146
- }
147
- case "update":
148
- runDetachedUpdate();
149
- printUpdateInstructions("this install", null);
150
- return;
151
- case "--help":
152
- case "-h":
153
- case undefined:
154
- console.log(HELP(await readRequiredBunVersion()));
155
- return;
156
- default:
157
- console.error(`Unknown command: ${command}\n\n${HELP(await readRequiredBunVersion())}`);
158
- process.exitCode = 2;
159
- }
160
- }
161
-
162
- main().catch(async (error: unknown) => {
163
- const message = error instanceof Error ? error.message : "unknown error";
164
- if (process.argv[2] === "tray") await reportTrayFailed(message);
165
- console.error(`Cartethyia failed: ${message}`);
166
- process.exitCode = 1;
167
- });
1
+ // dynamic-import-ok: subcommand dispatcher. Every branch lazy-loads only the
2
+ // module its command needs so `cartethyia --help` and `cartethyia stop` do
3
+ // not drag the gateway, dashboard, and database driver into memory.
4
+ import { mkdirSync } from "node:fs";
5
+ import { PACKAGE_ROOT, resolveUserConfigDir } from "../../src/config/package-paths";
6
+ import { readRequiredBunVersion, assertBunVersion } from "./version";
7
+ import { printUpdateInstructions, runDetachedUpdate } from "./update";
8
+
9
+ process.env.CARTETHYIA_CONFIG_DIR ??= resolveUserConfigDir();
10
+ // Covers every entry into the CLI that is not the npm launcher — the menu's
11
+ // "Hide to Tray" spawns this file directly, and the compiled gateway binary
12
+ // it then starts resolves its assets from the package root. A compiled Bun
13
+ // executable has a virtual `import.meta.dir` (`B:/~BUN/root/cartethyia`), so
14
+ // an unset root becomes `B:\` and startup dies with
15
+ // `ENOENT: scandir 'B:\migrations\lite-sqlite3'`.
16
+ process.env.CARTETHYIA_PACKAGE_ROOT ??= PACKAGE_ROOT;
17
+
18
+ const HELP = (minimumBunVersion: string) => `Cartethyia ${minimumBunVersion}+ (Bun is required)
19
+
20
+ Usage:
21
+ carte start, then show an arrow-key menu (no GUI needed)
22
+ carte --tray start with a system-tray icon instead
23
+ cartethyia setup [--non-interactive]
24
+ cartethyia start
25
+ cartethyia stop
26
+ cartethyia menu
27
+ cartethyia doctor
28
+ cartethyia admin reset-lockout <username> <clientIp>
29
+ cartethyia admin reset-lockout --all
30
+ cartethyia telemetry reconcile --apply|--verify
31
+ cartethyia update
32
+
33
+ carte starts the gateway in the background and leaves only the console menu on
34
+ your terminal — Open Console, Reset password, Backup, Update, Hide to tray,
35
+ Exit. Arrow keys and Enter; no desktop environment needed, so it works over SSH
36
+ and headless. A menu started by this command drains its child gateway on Exit;
37
+ leaving a menu attached to an existing gateway only detaches. Use stop for that.
38
+ carte --tray uses a system-tray icon instead, which needs a graphical session.
39
+ Stop a detached gateway with cartethyia stop (or the install's ./carte stop).
40
+ Setup explains Lite (embedded SQLite) and Full (external PostgreSQL), then saves
41
+ configuration under the current user's Cartethyia config directory.
42
+ `;
43
+
44
+ /** Loads the user's `.env` into the environment without overriding it. */
45
+ async function loadUserConfig(): Promise<void> {
46
+ const configDir = process.env.CARTETHYIA_CONFIG_DIR;
47
+ if (!configDir) throw new Error("Cartethyia config directory could not be resolved");
48
+ mkdirSync(configDir, { recursive: true });
49
+ // Imported here rather than at module scope: `support/env` pulls in the
50
+ // package-root resolver and `node:fs/promises`, and `carte --help` (which
51
+ // never reads a .env) should not pay for either before it prints.
52
+ const { ENV_PATH, readEnvFile } = await import("./env");
53
+ // Bun injects PORT=12800 when no explicit port was supplied. It is a
54
+ // runner default, not an operator override; without removing it, a saved
55
+ // custom port is ignored by npm/carte and the gateway starts on 12800.
56
+ // Preserve any non-default/custom shell value exactly as before.
57
+ if (process.env.PORT === "12800") delete process.env.PORT;
58
+ const values = await readEnvFile(ENV_PATH);
59
+ for (const [key, value] of Object.entries(values)) {
60
+ if (!process.env[key]) process.env[key] = value;
61
+ }
62
+ }
63
+
64
+ /**
65
+ * Reports tray readiness to the launcher waiting on a signal file.
66
+ *
67
+ * Deferred to a dynamic import for the same reason as `loadUserConfig`: only
68
+ * the tray path writes this file, so the other commands should not load
69
+ * `node:fs` machinery they never touch.
70
+ */
71
+ async function reportTrayFailed(message: string): Promise<void> {
72
+ const { reportTrayStartup } = await import("./startup-signal");
73
+ reportTrayStartup({ status: "failed", message });
74
+ }
75
+
76
+ async function main(): Promise<void> {
77
+ await assertBunVersion();
78
+ const [command] = process.argv.slice(2);
79
+ if (command === "setup" || command === "start" || command === "stop" || command === "tray" || command === "menu" || command === "doctor" || command === "admin" || command === "telemetry") {
80
+ await loadUserConfig();
81
+ }
82
+
83
+ switch (command) {
84
+ case "setup": {
85
+ const { setup } = await import("./setup");
86
+ await setup();
87
+ return;
88
+ }
89
+ case "start": {
90
+ const { startForeground } = await import("./start");
91
+ await startForeground();
92
+ return;
93
+ }
94
+ case "stop": {
95
+ const { resolvePort } = await import("../../src/config/runtime");
96
+ const { ensureDrainToken, attachGateway, stopAttachedGateway } = await import("./instance");
97
+ const port = resolvePort();
98
+ const token = ensureDrainToken();
99
+ const gateway = await attachGateway(port, token);
100
+ if (!gateway) {
101
+ console.log("No running Cartethyia gateway is owned by this installation.");
102
+ return;
103
+ }
104
+ await stopAttachedGateway(gateway, token);
105
+ console.log("Cartethyia stopped.");
106
+ return;
107
+ }
108
+ case "menu": {
109
+ const { startMenu } = await import("./console-menu");
110
+ await startMenu();
111
+ return;
112
+ }
113
+ case "tray": {
114
+ const { startTray } = await import("./tray");
115
+ await startTray();
116
+ return;
117
+ }
118
+ case "autostart": {
119
+ const { enableAutostart, disableAutostart, autostartStatus } = await import("./autostart");
120
+ const arg = Bun.argv[3]?.trim();
121
+ if (arg === "off" || arg === "disable") {
122
+ const state = await disableAutostart();
123
+ console.log(`Autostart disabled (${state.location || state.platform}).`);
124
+ return;
125
+ }
126
+ if (arg === "status") {
127
+ const state = autostartStatus();
128
+ console.log(
129
+ `Autostart: ${state.enabled ? "enabled" : "not enabled"} — ${state.location || state.platform}` +
130
+ (state.reason ? ` (${state.reason})` : ""),
131
+ );
132
+ return;
133
+ }
134
+ // The tray is what autostart launches: a gateway alone has no session to
135
+ // attach to and no icon to show.
136
+ const state = await enableAutostart(process.execPath, [Bun.argv[1] ?? "carte", "tray"]);
137
+ console.log(
138
+ state.enabled
139
+ ? `Autostart enabled — ${state.location}`
140
+ : `Autostart not enabled: ${state.reason ?? "unknown reason"}`,
141
+ );
142
+ return;
143
+ }
144
+ case "doctor": {
145
+ const { doctor } = await import("./doctor");
146
+ await doctor();
147
+ return;
148
+ }
149
+ case "admin": {
150
+ if (process.argv[3] !== "reset-lockout") throw new Error("Usage: cartethyia admin reset-lockout <username> <clientIp> | --all");
151
+ const { resetLockout } = await import("./admin");
152
+ await resetLockout(process.argv.slice(4));
153
+ return;
154
+ }
155
+ case "telemetry": {
156
+ if (process.argv[3] !== "reconcile") {
157
+ console.error("Usage: cartethyia telemetry reconcile --apply|--verify");
158
+ process.exitCode = 2;
159
+ return;
160
+ }
161
+ const { telemetry } = await import("./telemetry");
162
+ await telemetry(process.argv.slice(4));
163
+ return;
164
+ }
165
+ case "update":
166
+ runDetachedUpdate();
167
+ printUpdateInstructions("this install", null);
168
+ return;
169
+ case "--help":
170
+ case "-h":
171
+ case undefined:
172
+ console.log(HELP(await readRequiredBunVersion()));
173
+ return;
174
+ default:
175
+ console.error(`Unknown command: ${command}\n\n${HELP(await readRequiredBunVersion())}`);
176
+ process.exitCode = 2;
177
+ }
178
+ }
179
+
180
+ main().catch(async (error: unknown) => {
181
+ const message = error instanceof Error ? error.message : "unknown error";
182
+ // Only the tray launched for this exact handoff may answer its parent's
183
+ // signal file. An independent `carte --tray` must never fail an unrelated
184
+ // menu that happens to be transferring ownership at the same time.
185
+ if (process.argv[2] === "tray" && process.env.CARTETHYIA_CONTROLLER_PARENT_PID) {
186
+ await reportTrayFailed(message);
187
+ }
188
+ if (message.includes("not starting another instance")) {
189
+ console.error(`Cartethyia is already running.\n${message}`);
190
+ process.exitCode = 1;
191
+ return;
192
+ }
193
+ console.error(`Cartethyia failed: ${message}`);
194
+ process.exitCode = 1;
195
+ });
@@ -1,64 +1,64 @@
1
- export type LocalPlatform = "windows" | "macos" | "linux" | "unknown";
2
-
3
- /** Detects the host platform once so setup/doctor share identical labels. */
4
- export function getLocalPlatform(): LocalPlatform {
5
- if (process.platform === "win32") return "windows";
6
- if (process.platform === "darwin") return "macos";
7
- if (process.platform === "linux") return "linux";
8
- return "unknown";
9
- }
10
-
11
- /**
12
- * Returns actionable hints for the configured local/external service.
13
- * These are hints only: setup never assumes Docker or silently mutates an
14
- * external service. Windows users commonly run PostgreSQL through Laragon;
15
- * Redis may be native, WSL-backed, or external.
16
- */
17
- export function getOsHints(service: "postgres" | "redis"): string[] {
18
- const platform = getLocalPlatform();
19
- if (platform === "windows") {
20
- return service === "postgres"
21
- ? [
22
- "Windows / Laragon:",
23
- " Start Laragon (Start All) and ensure PostgreSQL is enabled.",
24
- " Verify PostgreSQL is listening on the DATABASE_URL host/port (usually 5432).",
25
- " External PostgreSQL is also supported — keep DATABASE_URL unchanged and reachable.",
26
- ]
27
- : [
28
- "Windows / Redis:",
29
- " Start Redis through WSL, a native Redis-compatible service, or an external host.",
30
- " Verify Redis is listening on the REDIS_URL host/port (usually 6379).",
31
- " Or omit REDIS_URL to use the in-memory backend.",
32
- ];
33
- }
34
- if (platform === "macos") {
35
- return service === "postgres"
36
- ? [
37
- "macOS / Homebrew:",
38
- " brew services start postgresql@16 (or the installed PostgreSQL version).",
39
- " External PostgreSQL is also supported — verify DATABASE_URL reachability.",
40
- ]
41
- : [
42
- "macOS / Redis:",
43
- " brew services start redis, or use an external Redis instance.",
44
- " Or omit REDIS_URL to use the in-memory backend.",
45
- ];
46
- }
47
- if (platform === "linux") {
48
- return service === "postgres"
49
- ? [
50
- "Linux / systemd:",
51
- " sudo systemctl start postgresql (or the installed PostgreSQL service).",
52
- " External PostgreSQL is also supported — verify DATABASE_URL reachability.",
53
- ]
54
- : [
55
- "Linux / Redis:",
56
- " sudo systemctl start redis-server (or the installed Redis service).",
57
- " Or omit REDIS_URL to use the in-memory backend.",
58
- ];
59
- }
60
- return [
61
- `${service} is not reachable on this platform.`,
62
- "Verify the configured service URL or use an external service.",
63
- ];
64
- }
1
+ export type LocalPlatform = "windows" | "macos" | "linux" | "unknown";
2
+
3
+ /** Detects the host platform once so setup/doctor share identical labels. */
4
+ export function getLocalPlatform(): LocalPlatform {
5
+ if (process.platform === "win32") return "windows";
6
+ if (process.platform === "darwin") return "macos";
7
+ if (process.platform === "linux") return "linux";
8
+ return "unknown";
9
+ }
10
+
11
+ /**
12
+ * Returns actionable hints for the configured local/external service.
13
+ * These are hints only: setup never assumes Docker or silently mutates an
14
+ * external service. Windows users commonly run PostgreSQL through Laragon;
15
+ * Redis may be native, WSL-backed, or external.
16
+ */
17
+ export function getOsHints(service: "postgres" | "redis"): string[] {
18
+ const platform = getLocalPlatform();
19
+ if (platform === "windows") {
20
+ return service === "postgres"
21
+ ? [
22
+ "Windows / Laragon:",
23
+ " Start Laragon (Start All) and ensure PostgreSQL is enabled.",
24
+ " Verify PostgreSQL is listening on the DATABASE_URL host/port (usually 5432).",
25
+ " External PostgreSQL is also supported — keep DATABASE_URL unchanged and reachable.",
26
+ ]
27
+ : [
28
+ "Windows / Redis:",
29
+ " Start Redis through WSL, a native Redis-compatible service, or an external host.",
30
+ " Verify Redis is listening on the REDIS_URL host/port (usually 6379).",
31
+ " Or omit REDIS_URL to use the in-memory backend.",
32
+ ];
33
+ }
34
+ if (platform === "macos") {
35
+ return service === "postgres"
36
+ ? [
37
+ "macOS / Homebrew:",
38
+ " brew services start postgresql@16 (or the installed PostgreSQL version).",
39
+ " External PostgreSQL is also supported — verify DATABASE_URL reachability.",
40
+ ]
41
+ : [
42
+ "macOS / Redis:",
43
+ " brew services start redis, or use an external Redis instance.",
44
+ " Or omit REDIS_URL to use the in-memory backend.",
45
+ ];
46
+ }
47
+ if (platform === "linux") {
48
+ return service === "postgres"
49
+ ? [
50
+ "Linux / systemd:",
51
+ " sudo systemctl start postgresql (or the installed PostgreSQL service).",
52
+ " External PostgreSQL is also supported — verify DATABASE_URL reachability.",
53
+ ]
54
+ : [
55
+ "Linux / Redis:",
56
+ " sudo systemctl start redis-server (or the installed Redis service).",
57
+ " Or omit REDIS_URL to use the in-memory backend.",
58
+ ];
59
+ }
60
+ return [
61
+ `${service} is not reachable on this platform.`,
62
+ "Verify the configured service URL or use an external service.",
63
+ ];
64
+ }