@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

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 (359) hide show
  1. package/CHANGELOG.md +292 -0
  2. package/README.md +8 -11
  3. package/docs/prefix-cache-architecture.md +14 -0
  4. package/package.json +22 -24
  5. package/packages/ask-user/README.md +55 -107
  6. package/packages/ask-user/ask-ui.ts +306 -732
  7. package/packages/ask-user/clipboard.ts +50 -0
  8. package/packages/ask-user/config.ts +74 -78
  9. package/packages/ask-user/package.json +2 -2
  10. package/packages/ask-user/questions.ts +151 -0
  11. package/packages/ask-user/skills/ask-user/SKILL.md +59 -133
  12. package/packages/ask-user/tools.ts +198 -432
  13. package/packages/autocomplete/package.json +1 -1
  14. package/packages/autocomplete/src/constants.ts +38 -43
  15. package/packages/autocomplete/src/sorting.ts +8 -0
  16. package/packages/background-tasks/package.json +2 -2
  17. package/packages/background-tasks/src/config.ts +0 -73
  18. package/packages/background-tasks/src/index.ts +20 -16
  19. package/packages/background-tasks/src/registry.ts +1 -171
  20. package/packages/background-tasks/src/types.ts +0 -32
  21. package/packages/btw/README.md +13 -56
  22. package/packages/btw/extensions/btw.ts +403 -1796
  23. package/packages/btw/package.json +5 -2
  24. package/packages/btw/skills/btw/SKILL.md +7 -143
  25. package/packages/compactor/README.md +56 -287
  26. package/packages/compactor/package.json +5 -9
  27. package/packages/compactor/skills/compactor/SKILL.md +13 -20
  28. package/packages/compactor/src/card.ts +90 -0
  29. package/packages/compactor/src/commands/index.ts +73 -130
  30. package/packages/compactor/src/compaction/compact-args.ts +5 -3
  31. package/packages/compactor/src/compaction/filter-noise.ts +1 -1
  32. package/packages/compactor/src/compaction/hooks.ts +487 -311
  33. package/packages/compactor/src/compaction/source.ts +178 -0
  34. package/packages/compactor/src/compaction/summarize.ts +586 -52
  35. package/packages/compactor/src/config/manager.ts +130 -127
  36. package/packages/compactor/src/config/schema.ts +32 -48
  37. package/packages/compactor/src/index.ts +40 -431
  38. package/packages/compactor/src/info-screen.ts +44 -190
  39. package/packages/compactor/src/session/recall-blocks.ts +1 -1
  40. package/packages/compactor/src/stats.ts +76 -0
  41. package/packages/compactor/src/tools/context-budget.ts +17 -34
  42. package/packages/compactor/src/tools/ctx-doctor.ts +45 -36
  43. package/packages/compactor/src/tools/register.ts +29 -269
  44. package/packages/compactor/src/types.ts +47 -186
  45. package/packages/core/README.md +25 -0
  46. package/packages/core/child-agent.ts +1 -0
  47. package/packages/core/command-echo.ts +63 -0
  48. package/packages/core/compaction-context.ts +41 -0
  49. package/packages/core/constants.ts +8 -38
  50. package/packages/core/events.ts +0 -53
  51. package/packages/core/fusion-status.ts +4 -0
  52. package/packages/core/global.d.ts +10 -0
  53. package/packages/core/harness-messages.ts +392 -0
  54. package/packages/core/index.ts +14 -0
  55. package/packages/core/kanboard-status.ts +49 -0
  56. package/packages/core/long-horizon-owner-status.ts +46 -0
  57. package/packages/core/model-cache.ts +81 -7
  58. package/packages/core/package.json +6 -3
  59. package/packages/core/src/attach/detect.ts +163 -0
  60. package/packages/core/src/child-agent/child-args.ts +31 -0
  61. package/packages/core/src/child-agent/delivery.ts +41 -0
  62. package/packages/core/src/child-agent/index.ts +5 -0
  63. package/packages/core/src/child-agent/readers.ts +203 -0
  64. package/packages/core/src/child-agent/runtime.ts +584 -0
  65. package/packages/core/src/evidence.ts +78 -0
  66. package/packages/core/src/hints/browser.ts +278 -0
  67. package/packages/core/src/hints/crab-data.ts +19 -0
  68. package/packages/core/src/hints/index.ts +865 -0
  69. package/packages/core/src/hints/lines.ts +607 -0
  70. package/packages/core/src/hints/store.ts +120 -0
  71. package/packages/core/src/jev/chatter.ts +24 -0
  72. package/packages/core/src/jev/settings.ts +177 -14
  73. package/packages/core/src/package-colors.ts +2 -0
  74. package/packages/core/src/settings/catalog.ts +39 -15
  75. package/packages/core/src/settings/engine.ts +48 -2
  76. package/packages/core/src/settings/hub.ts +83 -20
  77. package/packages/core/src/settings/open.ts +49 -0
  78. package/packages/core/src/settings/schema.ts +27 -7
  79. package/packages/core/src/tui/hub-kit.ts +18 -5
  80. package/packages/core/src/tui/kit.ts +198 -0
  81. package/packages/core/src/tui/progress.ts +73 -0
  82. package/packages/core/src/turn/arbiter.ts +290 -0
  83. package/packages/footer/README.md +4 -6
  84. package/packages/footer/package.json +3 -3
  85. package/packages/footer/src/glance-editor.ts +19 -11
  86. package/packages/footer/src/help.ts +1 -1
  87. package/packages/footer/src/index.ts +36 -3
  88. package/packages/footer/src/presets.ts +3 -4
  89. package/packages/footer/src/rendering/icons.ts +0 -20
  90. package/packages/footer/src/segments/compactor.ts +52 -142
  91. package/packages/footer/src/segments/status-ext.ts +0 -1
  92. package/packages/fusion/README.md +14 -4
  93. package/packages/fusion/package.json +4 -3
  94. package/packages/fusion/src/child-args.ts +1 -0
  95. package/packages/fusion/src/index.ts +161 -8
  96. package/packages/fusion/src/pi-settings.ts +57 -0
  97. package/packages/fusion/src/picker.ts +186 -51
  98. package/packages/fusion/src/preset.ts +56 -2
  99. package/packages/fusion/src/prompts.ts +1 -1
  100. package/packages/fusion/src/sidekick-runtime.ts +1 -420
  101. package/packages/fusion/src/tools.ts +107 -128
  102. package/packages/fusion/src/transcript.ts +27 -85
  103. package/packages/info-screen/package.json +2 -2
  104. package/packages/input-shortcuts/README.md +18 -30
  105. package/packages/input-shortcuts/package.json +2 -2
  106. package/packages/input-shortcuts/src/burst.ts +88 -0
  107. package/packages/input-shortcuts/src/chord-overlay.ts +20 -70
  108. package/packages/input-shortcuts/src/cleared-input.ts +97 -0
  109. package/packages/input-shortcuts/src/index.ts +99 -193
  110. package/packages/input-shortcuts/src/last-response.ts +40 -0
  111. package/packages/input-shortcuts/src/registers.ts +8 -23
  112. package/packages/input-shortcuts/src/types.ts +4 -16
  113. package/packages/input-shortcuts/src/undo-redo.ts +59 -47
  114. package/packages/kanboard/README.md +51 -47
  115. package/packages/kanboard/index.ts +293 -55
  116. package/packages/kanboard/package.json +8 -8
  117. package/packages/kanboard/skills/kanboard/SKILL.md +61 -27
  118. package/packages/kanboard/src/badges.ts +93 -0
  119. package/packages/kanboard/src/bin.ts +4 -2
  120. package/packages/kanboard/src/commands.ts +218 -84
  121. package/packages/kanboard/src/debug.ts +20 -0
  122. package/packages/kanboard/src/guard.ts +267 -109
  123. package/packages/kanboard/src/monitor.ts +330 -0
  124. package/packages/kanboard/src/notice-buffer.ts +74 -0
  125. package/packages/kanboard/src/progress.ts +27 -0
  126. package/packages/kanboard/src/reminders.ts +234 -0
  127. package/packages/kanboard/src/settings.ts +69 -15
  128. package/packages/kanboard/src/shapes.ts +5 -0
  129. package/packages/long-horizon/index.ts +190 -13
  130. package/packages/long-horizon/package.json +3 -3
  131. package/packages/long-horizon/src/commands.ts +103 -7
  132. package/packages/long-horizon/src/compaction-brief.ts +35 -0
  133. package/packages/long-horizon/src/engine/continuation.ts +84 -15
  134. package/packages/long-horizon/src/engine/goal-state.ts +64 -13
  135. package/packages/long-horizon/src/engine/nudge-stash.ts +71 -0
  136. package/packages/long-horizon/src/engine/ralph.ts +3 -2
  137. package/packages/long-horizon/src/engine/runaway.ts +68 -11
  138. package/packages/long-horizon/src/engine/verifier.ts +19 -0
  139. package/packages/long-horizon/src/gate.ts +37 -12
  140. package/packages/long-horizon/src/judge/resolve.ts +1 -0
  141. package/packages/long-horizon/src/owner.ts +35 -2
  142. package/packages/long-horizon/src/progress.ts +87 -0
  143. package/packages/long-horizon/src/prompts/goal.ts +1 -1
  144. package/packages/long-horizon/src/runtime.ts +172 -18
  145. package/packages/long-horizon/src/settings.ts +54 -39
  146. package/packages/long-horizon/src/tools/goal.ts +6 -0
  147. package/packages/long-horizon/src/tools/graph.ts +1 -1
  148. package/packages/long-horizon/src/tools/swarm.ts +3 -3
  149. package/packages/mcp/package.json +2 -2
  150. package/packages/memory/commands.ts +7 -2
  151. package/packages/memory/index.ts +210 -32
  152. package/packages/memory/package.json +3 -3
  153. package/packages/memory/save-session.ts +264 -0
  154. package/packages/memory/settings.ts +17 -0
  155. package/packages/memory/tools.ts +253 -203
  156. package/packages/notify/package.json +2 -2
  157. package/packages/skill-registry/README.md +53 -16
  158. package/packages/skill-registry/index.ts +230 -0
  159. package/packages/skill-registry/package.json +19 -8
  160. package/packages/skill-registry/src/editor.ts +206 -0
  161. package/packages/skill-registry/src/judge.ts +289 -0
  162. package/packages/skill-registry/src/registry.ts +87 -0
  163. package/packages/skill-registry/src/settings.ts +259 -0
  164. package/packages/skill-registry/src/vault.ts +80 -0
  165. package/packages/subagents/README.md +39 -119
  166. package/packages/subagents/package.json +6 -13
  167. package/packages/subagents/skills/subagents/SKILL.md +18 -42
  168. package/packages/subagents/src/agents.ts +213 -0
  169. package/packages/subagents/src/cards.ts +182 -0
  170. package/packages/subagents/src/index.ts +609 -1084
  171. package/packages/subagents/src/manager.ts +429 -0
  172. package/packages/subagents/src/profiles.ts +130 -0
  173. package/packages/subagents/src/transcript.ts +154 -0
  174. package/packages/subagents/src/ui.ts +389 -0
  175. package/packages/unipi/bundled.js +39756 -45569
  176. package/packages/unipi/index.ts +55 -10
  177. package/packages/updater/package.json +2 -2
  178. package/packages/utility/README.md +76 -69
  179. package/packages/utility/package.json +2 -2
  180. package/packages/utility/skills/image/SKILL.md +37 -0
  181. package/packages/utility/skills/utility/SKILL.md +17 -60
  182. package/packages/utility/src/answer/extract.ts +128 -0
  183. package/packages/utility/src/answer/index.ts +213 -0
  184. package/packages/utility/src/answer/reply.ts +133 -0
  185. package/packages/utility/src/answer/web.ts +167 -0
  186. package/packages/utility/src/attach/index.ts +205 -0
  187. package/packages/utility/src/commands.ts +38 -142
  188. package/packages/utility/src/diagnostics/engine.ts +50 -5
  189. package/packages/utility/src/image/index.ts +33 -0
  190. package/packages/utility/src/image/models.ts +221 -0
  191. package/packages/{image/src → utility/src/image}/recognize.ts +2 -2
  192. package/packages/utility/src/image/settings.ts +178 -0
  193. package/packages/{image/src/image-source.ts → utility/src/image/source.ts} +1 -1
  194. package/packages/utility/src/image/tools.ts +168 -0
  195. package/packages/utility/src/image/transports.ts +186 -0
  196. package/packages/utility/src/index.ts +68 -389
  197. package/packages/utility/src/lifecycle/cleanup.ts +116 -311
  198. package/packages/utility/src/rename/gate.ts +102 -0
  199. package/packages/utility/src/rename/index.ts +191 -0
  200. package/packages/utility/src/rename/session.ts +170 -0
  201. package/packages/utility/src/render/delegated.ts +285 -0
  202. package/packages/utility/src/render/harness.ts +683 -0
  203. package/packages/utility/src/render/parse.ts +156 -0
  204. package/packages/utility/src/render/pi-settings.ts +38 -0
  205. package/packages/utility/src/render/reply-bg.ts +307 -0
  206. package/packages/utility/src/render/simple.ts +724 -0
  207. package/packages/utility/src/render/spacing.ts +235 -0
  208. package/packages/utility/src/render/styled.ts +251 -0
  209. package/packages/utility/src/render/tools.ts +353 -0
  210. package/packages/utility/src/settings.ts +166 -233
  211. package/packages/utility/src/types.ts +1 -222
  212. package/packages/watchdog/index.ts +17 -6
  213. package/packages/watchdog/package.json +3 -3
  214. package/packages/watchdog/src/config.ts +3 -2
  215. package/packages/web-api/package.json +2 -2
  216. package/packages/workflow/README.md +3 -0
  217. package/packages/workflow/index.ts +0 -2
  218. package/packages/workflow/package.json +2 -2
  219. package/packages/workflow/src/permission/decide.ts +6 -4
  220. package/packages/workflow/src/permission/index.ts +17 -7
  221. package/packages/workflow/src/permission/settings.ts +39 -4
  222. package/packages/workflow/src/plan/index.ts +19 -4
  223. package/packages/background-tasks/extensions/delegate-child.ts +0 -1
  224. package/packages/background-tasks/src/context-parent-snapshot.ts +0 -142
  225. package/packages/background-tasks/src/context-token-budget.ts +0 -903
  226. package/packages/background-tasks/src/context-visible-conversation-v2.ts +0 -551
  227. package/packages/background-tasks/src/delegate/artifacts.ts +0 -487
  228. package/packages/background-tasks/src/delegate/budget.ts +0 -415
  229. package/packages/background-tasks/src/delegate/hook-contract-evidence.json +0 -18
  230. package/packages/background-tasks/src/delegate/hook-contract.ts +0 -154
  231. package/packages/background-tasks/src/delegate/launch.ts +0 -484
  232. package/packages/background-tasks/src/delegate/result-package.ts +0 -459
  233. package/packages/background-tasks/src/delegate/runner.ts +0 -430
  234. package/packages/background-tasks/src/delegate/seed.ts +0 -423
  235. package/packages/background-tasks/src/delegate/types.ts +0 -323
  236. package/packages/background-tasks/src/delegate-child-extension.ts +0 -978
  237. package/packages/background-tasks/src/delegate-extension.ts +0 -654
  238. package/packages/background-tasks/src/fixtures/delegate-context-incident.json +0 -17
  239. package/packages/compactor/skills/compactor-detail/SKILL.md +0 -116
  240. package/packages/compactor/skills/compactor-doctor/SKILL.md +0 -71
  241. package/packages/compactor/skills/compactor-stats/SKILL.md +0 -51
  242. package/packages/compactor/src/compaction/build-sections.ts +0 -76
  243. package/packages/compactor/src/compaction/extract/goals.ts +0 -36
  244. package/packages/compactor/src/compaction/extract/preferences.ts +0 -40
  245. package/packages/compactor/src/compaction/format.ts +0 -53
  246. package/packages/compactor/src/compaction/merge.ts +0 -143
  247. package/packages/compactor/src/config/presets.ts +0 -160
  248. package/packages/compactor/src/executor/executor.ts +0 -233
  249. package/packages/compactor/src/executor/runtime.ts +0 -115
  250. package/packages/compactor/src/security/evaluator.ts +0 -89
  251. package/packages/compactor/src/security/policy.ts +0 -96
  252. package/packages/compactor/src/security/scanner.ts +0 -65
  253. package/packages/compactor/src/session/auto-inject.ts +0 -60
  254. package/packages/compactor/src/session/db.ts +0 -325
  255. package/packages/compactor/src/session/extract.ts +0 -144
  256. package/packages/compactor/src/session/resume-inject.ts +0 -64
  257. package/packages/compactor/src/session/snapshot.ts +0 -327
  258. package/packages/compactor/src/tools/ctx-batch-execute.ts +0 -41
  259. package/packages/compactor/src/tools/ctx-execute-file.ts +0 -23
  260. package/packages/compactor/src/tools/ctx-execute.ts +0 -23
  261. package/packages/compactor/src/tools/ctx-stats.ts +0 -96
  262. package/packages/image/README.md +0 -99
  263. package/packages/image/package.json +0 -61
  264. package/packages/image/skills/image/SKILL.md +0 -76
  265. package/packages/image/src/generate.ts +0 -256
  266. package/packages/image/src/index.ts +0 -135
  267. package/packages/image/src/models.ts +0 -519
  268. package/packages/image/src/openai-images-api.ts +0 -282
  269. package/packages/image/src/register-providers.ts +0 -209
  270. package/packages/image/src/settings.ts +0 -173
  271. package/packages/image/src/tools.ts +0 -326
  272. package/packages/input-shortcuts/src/clipboard.ts +0 -119
  273. package/packages/kanboard/src/runner.ts +0 -817
  274. package/packages/skill-registry/skills/auto/SKILL.md +0 -465
  275. package/packages/skill-registry/skills/brainstorm/SKILL.md +0 -219
  276. package/packages/skill-registry/skills/chore-create/SKILL.md +0 -315
  277. package/packages/skill-registry/skills/chore-execute/SKILL.md +0 -314
  278. package/packages/skill-registry/skills/consolidate/SKILL.md +0 -142
  279. package/packages/skill-registry/skills/consultant/SKILL.md +0 -97
  280. package/packages/skill-registry/skills/debug/SKILL.md +0 -228
  281. package/packages/skill-registry/skills/document/SKILL.md +0 -120
  282. package/packages/skill-registry/skills/fix/SKILL.md +0 -212
  283. package/packages/skill-registry/skills/gather-context/SKILL.md +0 -145
  284. package/packages/skill-registry/skills/plan/SKILL.md +0 -231
  285. package/packages/skill-registry/skills/quick-fix/SKILL.md +0 -135
  286. package/packages/skill-registry/skills/quick-work/SKILL.md +0 -110
  287. package/packages/skill-registry/skills/research/SKILL.md +0 -251
  288. package/packages/skill-registry/skills/review-work/SKILL.md +0 -187
  289. package/packages/skill-registry/skills/scan-issues/SKILL.md +0 -195
  290. package/packages/skill-registry/skills/work/SKILL.md +0 -218
  291. package/packages/skill-registry/skills/worktree-create/SKILL.md +0 -69
  292. package/packages/skill-registry/skills/worktree-list/SKILL.md +0 -78
  293. package/packages/skill-registry/skills/worktree-merge/SKILL.md +0 -89
  294. package/packages/subagents/agents/delegate.md +0 -14
  295. package/packages/subagents/agents/oracle.md +0 -78
  296. package/packages/subagents/agents/researcher.md +0 -52
  297. package/packages/subagents/agents/reviewer.md +0 -80
  298. package/packages/subagents/agents/scout.md +0 -50
  299. package/packages/subagents/agents/worker.md +0 -59
  300. package/packages/subagents/prompts/council.md +0 -48
  301. package/packages/subagents/prompts/gather-context-and-clarify.md +0 -13
  302. package/packages/subagents/prompts/parallel-cleanup.md +0 -59
  303. package/packages/subagents/prompts/parallel-research.md +0 -50
  304. package/packages/subagents/prompts/parallel-review.md +0 -54
  305. package/packages/subagents/prompts/review-loop.md +0 -43
  306. package/packages/subagents/skills/council-mode/SKILL.md +0 -230
  307. package/packages/subagents/skills/subagents/references/constraints-and-recipes.md +0 -259
  308. package/packages/subagents/skills/subagents/references/execution-controls.md +0 -454
  309. package/packages/subagents/skills/subagents/references/management-authoring-rpc.md +0 -161
  310. package/packages/subagents/skills/subagents/references/multi-lane-orchestration.md +0 -39
  311. package/packages/subagents/skills/subagents/references/prompting-and-roles.md +0 -267
  312. package/packages/subagents/src/acceptance.ts +0 -331
  313. package/packages/subagents/src/agent-manager.ts +0 -405
  314. package/packages/subagents/src/agent-memory.ts +0 -300
  315. package/packages/subagents/src/agent-overrides.ts +0 -183
  316. package/packages/subagents/src/agent-runner.ts +0 -271
  317. package/packages/subagents/src/async-runner.ts +0 -422
  318. package/packages/subagents/src/authority-policy.ts +0 -47
  319. package/packages/subagents/src/budgets.ts +0 -285
  320. package/packages/subagents/src/child-safety.ts +0 -140
  321. package/packages/subagents/src/config.ts +0 -249
  322. package/packages/subagents/src/conversation-viewer.ts +0 -281
  323. package/packages/subagents/src/core-compat.ts +0 -94
  324. package/packages/subagents/src/custom-agents.ts +0 -343
  325. package/packages/subagents/src/file-system-retry.ts +0 -50
  326. package/packages/subagents/src/fleet-data.ts +0 -105
  327. package/packages/subagents/src/fleet-view.ts +0 -322
  328. package/packages/subagents/src/foreground-detach.ts +0 -59
  329. package/packages/subagents/src/fork-context.ts +0 -285
  330. package/packages/subagents/src/global.d.ts +0 -7
  331. package/packages/subagents/src/guide.ts +0 -129
  332. package/packages/subagents/src/mission-state.ts +0 -133
  333. package/packages/subagents/src/mission-store.ts +0 -436
  334. package/packages/subagents/src/output-limits.ts +0 -142
  335. package/packages/subagents/src/parity-types.ts +0 -315
  336. package/packages/subagents/src/pi-args.ts +0 -167
  337. package/packages/subagents/src/result-files.ts +0 -232
  338. package/packages/subagents/src/result-watcher.ts +0 -221
  339. package/packages/subagents/src/retained-children.ts +0 -176
  340. package/packages/subagents/src/run-fanout-budget.ts +0 -356
  341. package/packages/subagents/src/scheduled-runs.ts +0 -349
  342. package/packages/subagents/src/schemas.ts +0 -263
  343. package/packages/subagents/src/slash-commands.ts +0 -80
  344. package/packages/subagents/src/supervisor-channel.ts +0 -249
  345. package/packages/subagents/src/tool-handler.ts +0 -1144
  346. package/packages/subagents/src/types.ts +0 -238
  347. package/packages/subagents/src/widget.ts +0 -457
  348. package/packages/subagents/src/workflow-script.ts +0 -737
  349. package/packages/subagents/src/workflow-worker.ts +0 -384
  350. package/packages/subagents/src/worktree.ts +0 -614
  351. package/packages/utility/src/analytics/collector.ts +0 -293
  352. package/packages/utility/src/info-screen.ts +0 -80
  353. package/packages/utility/src/lifecycle/process.ts +0 -162
  354. package/packages/utility/src/prefix-cache.ts +0 -263
  355. package/packages/utility/src/skill-discovery.ts +0 -542
  356. package/packages/utility/src/tools/env.ts +0 -113
  357. package/packages/utility/src/tui/name-badge-state.ts +0 -315
  358. package/packages/utility/src/tui/name-badge.ts +0 -109
  359. /package/packages/{subagents/src → core/src/child-agent}/pi-spawn.ts +0 -0
@@ -50,7 +50,7 @@ import {
50
50
  HubSearch,
51
51
  type HubKey,
52
52
  } from "../tui/hub-kit.js";
53
- import { loadModelCatalogEntries, type ModelCatalogEntry } from "./catalog.js";
53
+ import { loadModelCatalogEntries, matchesCapability, type ModelCatalogEntry } from "./catalog.js";
54
54
  import { loadModelCatalog } from "./catalog.js";
55
55
  import {
56
56
  enumOption,
@@ -66,6 +66,7 @@ import {
66
66
  getSettingsDefinition,
67
67
  listSettingsDefinitions,
68
68
  setSettings,
69
+ unsetSettings,
69
70
  settingsLayers,
70
71
  type SettingsScope,
71
72
  } from "./engine.js";
@@ -83,12 +84,15 @@ export interface SettingsHubDeps {
83
84
  readonly runAction?: (command: string) => void | Promise<void>;
84
85
  /** Terminal rows for viewport sizing (tests inject; default stdout.rows). */
85
86
  readonly terminalRows?: () => number;
87
+ /** Open with this search filter applied (`/unipi:settings skills`). */
88
+ readonly initialFilter?: string;
86
89
  }
87
90
 
88
91
  type Mode = "list" | "search" | "input" | "model";
89
92
 
90
93
  interface Row {
91
- readonly kind: "header" | "field" | "toggle";
94
+ /** "note" = a page section's description line (non-selectable, like headers). */
95
+ readonly kind: "header" | "field" | "toggle" | "note";
92
96
  readonly id: string;
93
97
  readonly label: string;
94
98
  readonly namespace?: string;
@@ -101,6 +105,8 @@ interface Row {
101
105
  }
102
106
 
103
107
  const PAGE_ROWS = 10;
108
+ /** Header bands and section notes are not selectable. */
109
+ const isBand = (r: Row | undefined): boolean => r?.kind === "header" || r?.kind === "note";
104
110
  /** Picked value meaning "open the inline editor with the raw text". */
105
111
  const CUSTOM_VALUE = Symbol("custom");
106
112
  const HISTORY_CAP = 50;
@@ -112,6 +118,20 @@ const bold = (t: string) => overlayTheme.bold(t);
112
118
  * Quick-cycle an enum to the NEXT LISTED option — `custom…` is never offered;
113
119
  * a custom (unlisted) value restarts at the first option.
114
120
  */
121
+ /** Enum picker value for "use default" — clears the project key. */
122
+ const USE_DEFAULT = "__unipi_use_default__";
123
+
124
+ /** Enum options for the current scope: clearable fields add "use default" when
125
+ * writing the project scope. */
126
+ function enumOptionsFor(field: SettingsField, projectScope: boolean): { value: string; label: string }[] {
127
+ if (field.type !== "enum") return [];
128
+ const opts = field.options.map(enumOption);
129
+ if (field.clearable === true && projectScope) {
130
+ opts.push({ value: USE_DEFAULT, label: "use default" });
131
+ }
132
+ return opts;
133
+ }
134
+
115
135
  export function nextEnumValue(field: SettingsField, current: unknown): { value: unknown; label: string } | null {
116
136
  if (field.type !== "enum" || field.options.length === 0) return null;
117
137
  const opts = field.options.map(enumOption);
@@ -173,6 +193,8 @@ export class SettingsHub {
173
193
  rows: Row[];
174
194
  cursor: number;
175
195
  scroll: number;
196
+ /** The parent's search filter, restored on pop. */
197
+ filter: string;
176
198
  }> = [];
177
199
  private readonly runActionFn?: (command: string) => void | Promise<void>;
178
200
  private readonly terminalRowsFn: () => number;
@@ -190,6 +212,11 @@ export class SettingsHub {
190
212
  this.runActionFn = deps.runAction;
191
213
  this.terminalRowsFn = deps.terminalRows ?? (() => process.stdout.rows ?? 40);
192
214
  this.buildRows();
215
+ if (deps.initialFilter?.trim()) {
216
+ this.filter = deps.initialFilter.trim();
217
+ this.cursor = 0;
218
+ this.normalizeCursor();
219
+ }
193
220
  }
194
221
 
195
222
  private valueOf(namespace: string): Record<string, unknown> {
@@ -219,8 +246,9 @@ export class SettingsHub {
219
246
  namespace: def.namespace,
220
247
  });
221
248
  for (const field of section.fields) {
249
+ if (field.scopes && !field.scopes.includes(this.scope)) continue;
222
250
  rows.push({
223
- kind: "field", id: `${def.namespace}::${field.key}`,
251
+ kind: "field", id: `${def.namespace}::${field.key}::${field.label}`,
224
252
  label: field.label, namespace: def.namespace, field,
225
253
  context: `${def.label} ${section.title}`,
226
254
  });
@@ -240,8 +268,9 @@ export class SettingsHub {
240
268
  advancedOf: def.namespace,
241
269
  });
242
270
  for (const field of section.fields) {
271
+ if (field.scopes && !field.scopes.includes(this.scope)) continue;
243
272
  rows.push({
244
- kind: "field", id: `${def.namespace}::${field.key}`,
273
+ kind: "field", id: `${def.namespace}::${field.key}::${field.label}`,
245
274
  label: field.label, namespace: def.namespace, field,
246
275
  context: `${def.label} ${section.title}`,
247
276
  advancedOf: def.namespace,
@@ -281,7 +310,7 @@ export class SettingsHub {
281
310
  let currentHeader: Row | undefined;
282
311
  let headerPushed = false;
283
312
  for (const r of pageRows) {
284
- if (r.kind === "toggle") continue; // no toggle rows while searching
313
+ if (r.kind === "toggle" || r.kind === "note") continue; // no toggle/note rows while searching
285
314
  if (r.kind === "header") {
286
315
  currentHeader = r;
287
316
  headerPushed = false;
@@ -306,20 +335,20 @@ export class SettingsHub {
306
335
 
307
336
  /** First selectable (non-header) row index at or after `from` (or -1). */
308
337
  private nextSelectable(visible: Row[], from: number): number {
309
- for (let i = from; i < visible.length; i++) if (visible[i]!.kind !== "header") return i;
338
+ for (let i = from; i < visible.length; i++) if (!isBand(visible[i])) return i;
310
339
  return -1;
311
340
  }
312
341
 
313
342
  /** Previous selectable row index at or before `from` (or -1). */
314
343
  private prevSelectable(visible: Row[], from: number): number {
315
- for (let i = from; i >= 0; i--) if (visible[i]!.kind !== "header") return i;
344
+ for (let i = from; i >= 0; i--) if (!isBand(visible[i])) return i;
316
345
  return -1;
317
346
  }
318
347
 
319
348
  /** Normalize cursor onto a selectable row (headers never hold the cursor). */
320
349
  private normalizeCursor(): void {
321
350
  const visible = this.visibleRows();
322
- if (visible[this.cursor]?.kind === "header" || this.cursor >= visible.length) {
351
+ if (isBand(visible[this.cursor]) || this.cursor >= visible.length) {
323
352
  const i = this.nextSelectable(visible, this.cursor);
324
353
  this.cursor = i >= 0 ? i : Math.max(0, this.prevSelectable(visible, this.cursor - 1));
325
354
  }
@@ -336,8 +365,10 @@ export class SettingsHub {
336
365
  const prev = getField(current, row.field.key);
337
366
  const next = setField(current, row.field.key, value);
338
367
  this.values.set(row.namespace, next);
339
- setSettings(row.namespace, setField({}, row.field.key, value), this.scope, this.cwd);
340
- this.history.push({ namespace: row.namespace, key: row.field.key, prev, scope: this.scope, label: row.label });
368
+ const scope = ("scope" in row.field ? row.field.scope : undefined) ?? this.scope;
369
+ if (value === USE_DEFAULT) unsetSettings(row.namespace, row.field.key, scope, this.cwd);
370
+ else setSettings(row.namespace, setField({}, row.field.key, value), scope, this.cwd);
371
+ this.history.push({ namespace: row.namespace, key: row.field.key, prev, scope, label: row.label });
341
372
  if (this.history.length > HISTORY_CAP) this.history.shift();
342
373
  this.onChanged?.(row.namespace);
343
374
  }
@@ -349,7 +380,8 @@ export class SettingsHub {
349
380
  if (!entry) return;
350
381
  const next = setField(this.valueOf(entry.namespace), entry.key, entry.prev);
351
382
  this.values.set(entry.namespace, next);
352
- setSettings(entry.namespace, setField({}, entry.key, entry.prev), entry.scope, this.cwd);
383
+ if (entry.prev === undefined) unsetSettings(entry.namespace, entry.key, entry.scope, this.cwd);
384
+ else setSettings(entry.namespace, setField({}, entry.key, entry.prev), entry.scope, this.cwd);
353
385
  this.toast = `undo: ${entry.label}`;
354
386
  this.onChanged?.(entry.namespace);
355
387
  }
@@ -378,9 +410,13 @@ export class SettingsHub {
378
410
  kind: "header", id: `${namespace}::page::${section.title}`,
379
411
  label: section.title, namespace,
380
412
  });
413
+ if (section.description) {
414
+ rows.push({ kind: "note", id: `${namespace}::page::${section.title}::note`, label: section.description, namespace });
415
+ }
381
416
  for (const field of section.fields) {
417
+ if (field.scopes && !field.scopes.includes(this.scope)) continue;
382
418
  rows.push({
383
- kind: "field", id: `${namespace}::${field.key}`,
419
+ kind: "field", id: `${namespace}::${field.key}::${field.label}`,
384
420
  label: field.label, namespace, field,
385
421
  context: section.title,
386
422
  });
@@ -393,7 +429,9 @@ export class SettingsHub {
393
429
  if (row.kind !== "field" || !row.namespace || row.field?.type !== "page") return;
394
430
  // Dynamic pages resolve their sections at open time (live registries).
395
431
  const sections = typeof row.field.sections === "function" ? row.field.sections() : row.field.sections;
396
- // A page is a fresh context — a root-level filter must not bleed into it.
432
+ // A page is a fresh context — a root-level filter must not bleed into it
433
+ // (it comes back on Esc).
434
+ const parentFilter = this.filter;
397
435
  this.filter = "";
398
436
  this.searchInput = null;
399
437
  this.pageStack.push({
@@ -402,6 +440,7 @@ export class SettingsHub {
402
440
  rows: this.pageRows(row.namespace, sections),
403
441
  cursor: this.cursor, // parent's return position
404
442
  scroll: this.scroll,
443
+ filter: parentFilter,
405
444
  });
406
445
  this.cursor = 0;
407
446
  this.scroll = 0;
@@ -411,6 +450,7 @@ export class SettingsHub {
411
450
  private popPage(): void {
412
451
  const top = this.pageStack.pop();
413
452
  if (!top) return;
453
+ this.filter = top.filter;
414
454
  this.cursor = top.cursor;
415
455
  this.scroll = top.scroll;
416
456
  this.toast = `back: ${top.label}`;
@@ -438,6 +478,9 @@ export class SettingsHub {
438
478
  const projectAllowed = defs.some((d) => d.projectOverrides !== false);
439
479
  if (!projectAllowed && this.scope === "global") return;
440
480
  this.scope = this.scope === "global" ? "project" : "global";
481
+ this.buildRows();
482
+ this.cursor = Math.min(this.cursor, Math.max(0, this.rows.length - 1));
483
+ this.scroll = 0;
441
484
  }
442
485
 
443
486
  // ── key handling ────────────────────────────────────────────────────────
@@ -486,6 +529,10 @@ export class SettingsHub {
486
529
  if (key === "search") {
487
530
  this.mode = "search";
488
531
  this.searchInput = new HubSearch("/");
532
+ if (this.filter) {
533
+ this.searchInput.input.setValue(this.filter);
534
+ this.searchInput.filter = this.filter;
535
+ }
489
536
  return;
490
537
  }
491
538
  // Recovery keys (omp principle: defaults are always one key away).
@@ -502,6 +549,7 @@ export class SettingsHub {
502
549
  }
503
550
  if (key === "back") {
504
551
  if (this.pageStack.length > 0) this.popPage();
552
+ else if (this.filter) this.exitSearch(); // first Esc clears an applied filter
505
553
  else this.onClose();
506
554
  return;
507
555
  }
@@ -523,8 +571,13 @@ export class SettingsHub {
523
571
  // Quick action: boolean toggle + enum cycle only; everything else no-op.
524
572
  if (field.type === "boolean") this.applyChange(row, value !== true);
525
573
  else if (field.type === "enum") {
526
- const next = nextEnumValue(field, value);
527
- if (next) this.applyChange(row, next.value);
574
+ // For clearable fields in project scope, "use default" joins the cycle.
575
+ const opts = enumOptionsFor(field, this.scope === "project");
576
+ if (opts.length === 0) return;
577
+ const cur = String(value ?? "");
578
+ const idx = opts.findIndex((o) => o.value === cur);
579
+ const next = opts[idx === -1 ? 0 : (idx + 1) % opts.length]!;
580
+ this.applyChange(row, next.value);
528
581
  }
529
582
  return;
530
583
  }
@@ -616,8 +669,7 @@ export class SettingsHub {
616
669
  } else {
617
670
  const entries = this.entries();
618
671
  if (field.capability) {
619
- const want = field.capability === "image-input" ? "image" : field.capability;
620
- options = entries.filter((e) => e.input.includes(want)).map((e) => e.id);
672
+ options = entries.filter((e) => matchesCapability(e, field.capability!)).map((e) => e.id);
621
673
  header = `${field.capability} models · ${options.length}`;
622
674
  } else if (field.filter) {
623
675
  const matches = field.filter;
@@ -662,7 +714,7 @@ export class SettingsHub {
662
714
  private openEnumList(row: Row): void {
663
715
  const field = row.field!;
664
716
  if (field.type !== "enum") return;
665
- const opts = field.options.map(enumOption);
717
+ const opts = enumOptionsFor(field, this.scope === "project");
666
718
  const custom = field.allowCustom === true;
667
719
  const options = custom ? [...opts.map((o) => o.label), "custom…"] : opts.map((o) => o.label);
668
720
  const values: unknown[] = custom ? [...opts.map((o) => o.value), CUSTOM_VALUE] : opts.map((o) => o.value);
@@ -925,6 +977,9 @@ export class SettingsHub {
925
977
  const label = open ? "▾ Advanced" : "▸ Advanced";
926
978
  return this.exactRow(this.rowColumns(cursor, label, "enter/tab/space", inner, selected, row.namespace), inner);
927
979
  }
980
+ if (row.kind === "note") {
981
+ return this.exactRow(dim(` ${row.label}`), inner);
982
+ }
928
983
  if (row.kind === "header") {
929
984
  const tag = row.layerTag ? ` [${row.layerTag}]` : "";
930
985
  // Distinct full-width band (bg wrap is width-safe — measures on plain);
@@ -933,7 +988,13 @@ export class SettingsHub {
933
988
  }
934
989
  const field = row.field!;
935
990
  if (field.type === "page") {
936
- return this.exactRow(this.rowColumns(cursor, row.label, "› open", inner, selected, row.namespace), inner);
991
+ let summary = "";
992
+ try {
993
+ summary = field.summary ? field.summary(this.valueOf(row.namespace!)) : "";
994
+ } catch {
995
+ summary = "";
996
+ }
997
+ return this.exactRow(this.rowColumns(cursor, row.label, summary ? `${summary} ›` : "› open", inner, selected, row.namespace), inner);
937
998
  }
938
999
  if (field.type === "action") {
939
1000
  return this.exactRow(this.rowColumns(cursor, row.label, "⏎ run", inner, selected, row.namespace), inner);
@@ -984,7 +1045,7 @@ export class SettingsHub {
984
1045
  out.push(this.exactRow(sel ? ` ${bold(label)}` : ` ${dim(label)}`, inner));
985
1046
  }
986
1047
  // Pad to exactly 5 rows so the panel never jumps.
987
- for (let i = filtered.length - start; i < 5; i++) out.push(this.exactRow(` ${dim(" ·")}`, inner));
1048
+ for (let i = filtered.length - start; i < 5; i++) out.push(this.exactRow(" ", inner));
988
1049
  out.push(this.exactRow(dim(" enter/tab pick · esc cancel"), inner));
989
1050
  return out;
990
1051
  }
@@ -1044,6 +1105,8 @@ export class SettingsHub {
1044
1105
 
1045
1106
  if (this.mode === "search" && this.searchInput) {
1046
1107
  for (const l of this.searchInput.input.render(Math.max(8, inner - 2))) body.push(this.exactRow(` ${l}`, inner));
1108
+ } else if (this.filter) {
1109
+ body.push(this.exactRow(dim(` / ${this.filter} · / edit · esc clear`), inner));
1047
1110
  }
1048
1111
 
1049
1112
  const visible = this.visibleRows();
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Open the unified settings hub as an overlay — shared by /unipi:settings and
3
+ * any module that wants to land the user on its own rows (`/unipi:skills`
4
+ * opens it filtered to "skills").
5
+ */
6
+
7
+ import { runCommandByName } from "../../command-runner.js";
8
+ import { HUB_OVERLAY_OPTIONS } from "../tui/hub-kit.js";
9
+ import { SettingsHub } from "./hub.js";
10
+
11
+ interface HubHostContext {
12
+ hasUI: boolean;
13
+ cwd?: string;
14
+ ui: {
15
+ notify(message: string, type?: "info" | "warning" | "error"): void;
16
+ custom<T>(factory: (tui: { requestRender(): void }, theme: unknown, keybindings: unknown, done: (result: T) => void) => unknown, options?: unknown): Promise<T>;
17
+ };
18
+ }
19
+
20
+ export async function openSettingsHub(ctx: HubHostContext, options: { filter?: string; onChanged?: (namespace: string) => void } = {}): Promise<void> {
21
+ if (!ctx.hasUI) throw new Error("/unipi:settings needs the interactive TUI");
22
+ await ctx.ui.custom<void>(
23
+ (tui, _theme, _keybindings, done) => {
24
+ const hub = new SettingsHub({
25
+ cwd: ctx.cwd ?? process.cwd(),
26
+ ...(options.filter ? { initialFilter: options.filter } : {}),
27
+ ...(options.onChanged ? { onChanged: options.onChanged } : {}),
28
+ runAction: async (command) => {
29
+ const ran = await runCommandByName(command, ctx);
30
+ if (!ran) ctx.ui.notify(`no handler registered for ${command}`, "warning");
31
+ },
32
+ });
33
+ hub.onClose = () => done();
34
+ return {
35
+ focused: true,
36
+ invalidate: () => hub.invalidate(),
37
+ render: (width: number) => hub.render(width),
38
+ handleInput: (data: string) => {
39
+ hub.handleInput(data);
40
+ tui.requestRender();
41
+ },
42
+ dispose: () => {},
43
+ };
44
+ },
45
+ HUB_OVERLAY_OPTIONS,
46
+ ).catch(() => {
47
+ // Overlay errors are non-blocking.
48
+ });
49
+ }
@@ -11,8 +11,13 @@
11
11
  * secret → Input submenu, value masked in the list (API keys etc.)
12
12
  */
13
13
 
14
- export type SettingsField =
15
- | { readonly key: string; readonly type: "boolean"; readonly label: string; readonly description?: string }
14
+ export type SettingsField = (
15
+ | {
16
+ readonly key: string;
17
+ readonly type: "boolean";
18
+ readonly label: string;
19
+ readonly description?: string;
20
+ }
16
21
  | {
17
22
  readonly key: string;
18
23
  readonly type: "enum";
@@ -30,6 +35,13 @@ export type SettingsField =
30
35
  readonly hint?: string;
31
36
  /** Gate custom input on submit; returns an error message or null. */
32
37
  readonly validate?: (raw: string) => string | null;
38
+ /** Pin the write to a scope (e.g. a "default" field that is global-only). */
39
+ readonly scope?: "global";
40
+ /**
41
+ * Show a trailing "use default" option when writing the project scope —
42
+ * selecting it deletes the project key so the global value applies.
43
+ */
44
+ readonly clearable?: boolean;
33
45
  }
34
46
  | {
35
47
  readonly key: string;
@@ -80,10 +92,12 @@ export type SettingsField =
80
92
  /** Shown when "" (e.g. "inherit (session model)"). */
81
93
  readonly emptyLabel?: string;
82
94
  /**
83
- * Filter the registry catalog by the model's declared `input` array:
84
- * "text" → must include "text"; "image-input" → must include "image".
95
+ * Filter the catalog by declared modalities:
96
+ * "text" → text output (chat models); "image-input" → image in, text out
97
+ * (vision); "image-output" → image out (generation); "image-edit" →
98
+ * image in + image out.
85
99
  */
86
- readonly capability?: "text" | "image-input";
100
+ readonly capability?: "text" | "image-input" | "image-output" | "image-edit";
87
101
  /** When set, the picker lists ONLY these ids (+ custom…), not the catalog. */
88
102
  readonly presets?: readonly string[];
89
103
  /**
@@ -97,7 +111,7 @@ export type SettingsField =
97
111
  /** Sibling key (same namespace) whose value selects a presetsByProvider list. */
98
112
  readonly providerKey?: string;
99
113
  /** Extra catalog filter (e.g. image's looksLikeImageGenerator); no presets. */
100
- readonly filter?: (entry: { readonly id: string; readonly input: string[] }) => boolean;
114
+ readonly filter?: (entry: { readonly id: string; readonly input: string[]; readonly output?: string[] }) => boolean;
101
115
  }
102
116
  | {
103
117
  /** Nested config page (Enter/Tab opens; Esc pops). Fields use FULL keys. */
@@ -110,6 +124,8 @@ export type SettingsField =
110
124
  * driven pages (info groups, footer segments) stay live.
111
125
  */
112
126
  readonly sections: readonly SettingsSection[] | (() => readonly SettingsSection[]);
127
+ /** Value shown on the row instead of "› open" (e.g. "on · listed"). */
128
+ readonly summary?: (values: Record<string, unknown>) => string;
113
129
  }
114
130
  | {
115
131
  /** Runs a named command (registered via core registerCommandRunner). */
@@ -144,7 +160,11 @@ export type SettingsField =
144
160
  readonly description?: string;
145
161
  /** The full item universe in canonical order. */
146
162
  readonly items: () => readonly { readonly value: string; readonly label: string }[];
147
- };
163
+ } ) & {
164
+ /** Hub scopes this field appears in; absent = both (the default).
165
+ * e.g. a project-override row hides in the global scope. */
166
+ readonly scopes?: ("global" | "project")[];
167
+ };
148
168
 
149
169
  export interface SettingsSection {
150
170
  /** Section heading in the hub (e.g. "Judge", "Badge"). */
@@ -62,6 +62,18 @@ export const HUB_WIDE_OVERLAY_OPTIONS: {
62
62
  overlayOptions: () => ({ anchor: "center", width: 120, minWidth: 100 }),
63
63
  };
64
64
 
65
+ /**
66
+ * The /unipi:model picker's pre-hub sizing (faccc253): percentage width so
67
+ * model names, badges, and the price panel don't truncate at ~80 cols.
68
+ */
69
+ export const HUB_PICKER_OVERLAY_OPTIONS: {
70
+ readonly overlay: true;
71
+ readonly overlayOptions: () => OverlayOptions;
72
+ } = {
73
+ overlay: true,
74
+ overlayOptions: () => ({ anchor: "center", width: "88%", minWidth: 72, maxHeight: "80%" }),
75
+ };
76
+
65
77
  const hubDim = (t: string): string => hubTheme.fg("textMuted", t);
66
78
  const hubBold = (t: string): string => hubTheme.bold(t);
67
79
 
@@ -117,19 +129,20 @@ export function hubExactRow(content: string, inner: number): string {
117
129
  return content + " ".repeat(inner - w);
118
130
  }
119
131
 
120
- /** Plain-text group-mark cell: `▌` for colored namespaces, else a space. */
121
- export function hubMarkChar(namespace: string | undefined): string {
122
- return namespaceColor(namespace ?? "") ? "▌" : " ";
132
+ /** Plain-text group-mark cell: always the `▌` left border. */
133
+ export function hubMarkChar(_namespace: string | undefined): string {
134
+ return "▌";
123
135
  }
124
136
 
125
137
  /**
126
- * Styled `▌` group mark — bold + the namespace's ANSI color. Closes with
138
+ * Styled `▌` group mark — bold + the namespace's ANSI color (dim when the
139
+ * namespace has no package color). Closes with
127
140
  * targeted-off codes ([22m[39m), never [0m: a full reset mid-line would kill
128
141
  * an enclosing background paint.
129
142
  */
130
143
  export function hubMarkSpan(namespace: string | undefined): string {
131
144
  const color = namespaceColor(namespace ?? "");
132
- return color ? `${color}${hubBold("▌")}\x1b[39m` : " ";
145
+ return color ? `${color}${hubBold("▌")}\x1b[39m` : hubDim(hubBold("▌"));
133
146
  }
134
147
 
135
148
  export interface HubRowOptions {
@@ -0,0 +1,198 @@
1
+ /**
2
+ * @pi-unipi/core — shared TUI kit: one visual language for every UniPi surface.
3
+ *
4
+ * spinner crafted, multi-cell, colour-animated (pi uses braille ⠋⠙⠹…)
5
+ * badge inverse chip `AGENT`, `DONE`, `WAIT` …
6
+ * leader left ···· right on one line
7
+ * rail `▌ left right` — memory's framing
8
+ * progressBar `████▒▒░░░░` — solid done, shade in progress, light left
9
+ *
10
+ * Everything takes theme tokens (never raw hex) so it follows the Pi theme.
11
+ * Preview every piece with `npm run tui:gallery`.
12
+ */
13
+
14
+ import type { ThemeColor } from "@earendil-works/pi-coding-agent";
15
+ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
16
+
17
+ export interface KitTheme {
18
+ fg(color: ThemeColor, text: string): string;
19
+ bold(text: string): string;
20
+ }
21
+
22
+ // ── spinners ────────────────────────────────────────────────────────────────
23
+
24
+ export type SpinnerStyle = "orbit" | "comet" | "scanner" | "helix" | "diamond" | "bars" | "quad";
25
+ export const SPINNER_STYLES: readonly SpinnerStyle[] = ["orbit", "comet", "scanner", "helix", "diamond", "bars", "quad"];
26
+ /** The UniPi default. Change here to switch every surface at once. */
27
+ export const DEFAULT_SPINNER: SpinnerStyle = "orbit";
28
+ export const SPINNER_MS = 90;
29
+
30
+ /** Braille dot bit for (column 0..1, row 0..3) inside one cell. */
31
+ const DOT = [
32
+ [0x01, 0x02, 0x04, 0x40],
33
+ [0x08, 0x10, 0x20, 0x80],
34
+ ] as const;
35
+ const braille = (bits: number) => String.fromCharCode(0x2800 + bits);
36
+ /** Head → tail colours for trails. */
37
+ const TRAIL: ThemeColor[] = ["accent", "muted", "dim"];
38
+
39
+ /** Paint dots on a (cells×2) × 4 braille canvas; each cell takes the colour of its brightest dot. */
40
+ function canvas(t: KitTheme, cells: number, dots: Array<{ x: number; y: number; level: number }>): string {
41
+ const bits = new Array<number>(cells).fill(0);
42
+ const level = new Array<number>(cells).fill(99);
43
+ for (const d of dots) {
44
+ const c = Math.floor(d.x / 2);
45
+ if (c < 0 || c >= cells) continue;
46
+ bits[c]! |= DOT[d.x % 2]![d.y]!;
47
+ level[c] = Math.min(level[c]!, d.level);
48
+ }
49
+ return bits.map((b, i) => (b === 0 ? " " : t.fg(TRAIL[Math.min(level[i]!, TRAIL.length - 1)]!, braille(b)))).join("");
50
+ }
51
+
52
+ // 4×4 perimeter of a two-cell braille block, clockwise.
53
+ const ORBIT: Array<[number, number]> = [[0, 0], [1, 0], [2, 0], [3, 0], [3, 1], [3, 2], [3, 3], [2, 3], [1, 3], [0, 3], [0, 2], [0, 1]];
54
+
55
+ const STYLES: Record<SpinnerStyle, { cells: number; frame: (t: KitTheme, n: number) => string }> = {
56
+ // A dot circling a 4×4 grid with a fading two-dot tail.
57
+ orbit: {
58
+ cells: 2,
59
+ frame: (t, n) => canvas(t, 2, [0, 1, 2].map((k) => {
60
+ const [x, y] = ORBIT[(n - k + ORBIT.length * 4) % ORBIT.length]!;
61
+ return { x, y, level: k };
62
+ })),
63
+ },
64
+ // A comet bouncing across three cells, trail fading behind it.
65
+ comet: {
66
+ cells: 3,
67
+ frame: (t, n) => {
68
+ const span = 6;
69
+ const p = n % (span * 2 - 2);
70
+ const x = p < span ? p : span * 2 - 2 - p;
71
+ const dir = p < span ? -1 : 1;
72
+ return canvas(t, 3, [0, 1, 2].map((k) => ({ x: x + dir * k, y: 1 + (k === 0 ? 0 : 1) * ((n + k) % 2), level: k })));
73
+ },
74
+ },
75
+ // ◆ sweeping over three cells, ◇ neighbours.
76
+ scanner: {
77
+ cells: 3,
78
+ frame: (t, n) => {
79
+ const p = n % 4;
80
+ const x = p < 3 ? p : 1;
81
+ return [0, 1, 2].map((i) => (i === x ? t.fg("accent", "◆") : Math.abs(i - x) === 1 ? t.fg("muted", "◇") : t.fg("dim", "·"))).join("");
82
+ },
83
+ },
84
+ // A sine wave scrolling through two braille cells.
85
+ helix: {
86
+ cells: 2,
87
+ frame: (t, n) => canvas(t, 2, [0, 1, 2, 3].map((x) => ({ x, y: Math.round(((Math.sin((x + n) / 1.3) + 1) / 2) * 3), level: x === 3 ? 0 : x === 2 ? 0 : 1 }))),
88
+ },
89
+ // ◇ ◈ ◆ ◈ with a brightness pulse.
90
+ diamond: {
91
+ cells: 1,
92
+ frame: (t, n) => {
93
+ const f = n % 6;
94
+ const glyph = ["◇", "◈", "◆", "◆", "◈", "◇"][f]!;
95
+ const color: ThemeColor = f === 2 || f === 3 ? "accent" : f === 1 || f === 4 ? "muted" : "dim";
96
+ return t.fg(color, glyph);
97
+ },
98
+ },
99
+ // Three bars breathing out of phase.
100
+ bars: {
101
+ cells: 3,
102
+ frame: (t, n) => {
103
+ const H = "▁▂▃▄▅▆▇█";
104
+ return [0, 1, 2].map((i) => {
105
+ const h = Math.round(((Math.sin((n - i * 2) / 2) + 1) / 2) * 7);
106
+ return t.fg(h > 5 ? "accent" : h > 2 ? "muted" : "dim", H[h]!);
107
+ }).join("");
108
+ },
109
+ },
110
+ // A quarter block rotating.
111
+ quad: {
112
+ cells: 1,
113
+ frame: (t, n) => t.fg(n % 2 === 0 ? "accent" : "muted", ["▖", "▘", "▝", "▗"][n % 4]!),
114
+ },
115
+ };
116
+
117
+ /** Current frame of a spinner (time-based, so any re-render animates it). */
118
+ export function spinner(t: KitTheme, style: SpinnerStyle = DEFAULT_SPINNER, now = Date.now()): string {
119
+ return STYLES[style].frame(t, Math.floor(now / SPINNER_MS));
120
+ }
121
+
122
+ /** Frame by index (tests, gallery). */
123
+ export function spinnerFrame(t: KitTheme, style: SpinnerStyle, n: number): string {
124
+ return STYLES[style].frame(t, n);
125
+ }
126
+
127
+ export function spinnerCells(style: SpinnerStyle = DEFAULT_SPINNER): number {
128
+ return STYLES[style].cells;
129
+ }
130
+
131
+ /** A static glyph padded to the spinner's width, so text doesn't jump when running ends. */
132
+ export function settledGlyph(glyph: string, style: SpinnerStyle = DEFAULT_SPINNER): string {
133
+ return glyph + " ".repeat(Math.max(0, spinnerCells(style) - visibleWidth(glyph)));
134
+ }
135
+
136
+ // ── states ──────────────────────────────────────────────────────────────────
137
+
138
+ export type RunState = "running" | "completed" | "failed" | "cancelled";
139
+ export const STATE_COLOR: Record<RunState, ThemeColor> = { running: "accent", completed: "success", failed: "error", cancelled: "warning" };
140
+ export const STATE_GLYPH: Record<Exclude<RunState, "running">, string> = { completed: "✓", failed: "✗", cancelled: "⊘" };
141
+ export const STATE_BADGE: Record<RunState, string> = { running: "RUN ", completed: "DONE", failed: "FAIL", cancelled: "STOP" };
142
+
143
+ /** Spinner while running, else the coloured settled glyph (same width). */
144
+ export function stateGlyph(t: KitTheme, state: RunState, now = Date.now()): string {
145
+ return state === "running" ? spinner(t, DEFAULT_SPINNER, now) : t.fg(STATE_COLOR[state], settledGlyph(STATE_GLYPH[state]));
146
+ }
147
+
148
+ // ── lines ───────────────────────────────────────────────────────────────────
149
+
150
+ /** Inverse chip: ` DONE ` on the colour. Needs no extra glyphs or fonts. */
151
+ export function badge(t: KitTheme, color: ThemeColor, label: string): string {
152
+ return `\x1b[7m${t.fg(color, ` ${label} `)}\x1b[27m`;
153
+ }
154
+
155
+ /** `left ········ right`, fitted to width. */
156
+ export function leader(t: KitTheme, left: string, right: string, width: number): string {
157
+ const gap = width - visibleWidth(left) - visibleWidth(right);
158
+ if (gap < 4) return truncateToWidth(`${left} ${right}`, width, "…");
159
+ return `${left} ${t.fg("borderMuted", "·".repeat(gap - 2))} ${right}`;
160
+ }
161
+
162
+ /** Left + right on one line, padded between. */
163
+ export function spread(left: string, right: string, width: number): string {
164
+ if (right === "") return truncateToWidth(left, width, "…");
165
+ const gap = width - visibleWidth(left) - visibleWidth(right);
166
+ if (gap < 2) return truncateToWidth(`${left} ${right}`, width, "…");
167
+ return `${left}${" ".repeat(gap)}${right}`;
168
+ }
169
+
170
+ /** `▌ left right` — a coloured bar that groups related lines. */
171
+ export function rail(t: KitTheme, color: ThemeColor, left: string, right: string, width: number): string {
172
+ return spread(`${t.fg(color, "▌")} ${left}`, right, width);
173
+ }
174
+
175
+ // ── progress ────────────────────────────────────────────────────────────────
176
+
177
+ const EIGHTHS = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
178
+
179
+ /** Smooth meter (8 steps per cell) for scores: `█████▍░░`. */
180
+ export function meter(t: KitTheme, ratio: number, width = 8, color: ThemeColor = "accent"): string {
181
+ const units = Math.round(Math.max(0, Math.min(1, ratio)) * width * 8);
182
+ const full = "█".repeat(Math.floor(units / 8)) + EIGHTHS[units % 8]!;
183
+ return t.fg(color, full) + t.fg("borderMuted", "░".repeat(Math.max(0, width - visibleWidth(full))));
184
+ }
185
+
186
+ /**
187
+ * `████▒▒░░░░`: `done` solid, `active` shaded (in progress), the rest light.
188
+ * Counts are clamped; total 0 renders an empty track.
189
+ */
190
+ export function progressBar(t: KitTheme, done: number, active: number, total: number, width = 20, color: ThemeColor = "accent"): string {
191
+ if (total <= 0) return t.fg("borderMuted", "░".repeat(width));
192
+ const d = Math.max(0, Math.min(total, done));
193
+ const a = Math.max(0, Math.min(total - d, active));
194
+ const solid = Math.round((d / total) * width);
195
+ const shade = a > 0 ? Math.max(1, Math.round(((d + a) / total) * width) - solid) : 0;
196
+ const rest = Math.max(0, width - solid - shade);
197
+ return t.fg(color, "█".repeat(solid)) + t.fg(color, "▒".repeat(Math.min(shade, width - solid))) + t.fg("borderMuted", "░".repeat(rest));
198
+ }