@cbartens/bkit 5.1.0 → 5.2.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 (193) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +92 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +10 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.prettierignore +1 -1
  136. package/.bkit/templates/context/bkit-expo.md +22 -13
  137. package/.bkit/templates/context/bkit-github.md +20 -6
  138. package/.bkit/templates/context/bkit-inngest.md +10 -4
  139. package/.bkit/templates/context/bkit-maestro.md +5 -5
  140. package/.bkit/templates/context/bkit-playwright.md +3 -3
  141. package/.bkit/templates/context/bkit-sentry.md +6 -5
  142. package/.bkit/templates/context/bkit-stripe.md +31 -8
  143. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  145. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  147. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  148. package/.bkit/templates/slop-scan.config.json +7 -2
  149. package/CHANGELOG.md +50 -0
  150. package/LICENSE.md +21 -161
  151. package/README.md +61 -28
  152. package/dist/checks/after/auth.js +28 -0
  153. package/dist/checks/after/github.js +4 -4
  154. package/dist/checks/after/index.js +29 -45
  155. package/dist/checks/after/managed.js +40 -1
  156. package/dist/checks/before/index.js +5 -4
  157. package/dist/checks/before/mcp.js +53 -53
  158. package/dist/checks/status-holes.js +1 -1
  159. package/dist/checks/tips/catalogue.js +297 -0
  160. package/dist/checks/tips/detect.js +130 -0
  161. package/dist/checks/tips/index.js +146 -0
  162. package/dist/cli.js +47 -9
  163. package/dist/commands/install/doctor.js +5 -1
  164. package/dist/commands/install/install.js +27 -7
  165. package/dist/commands/install/uninstall.js +31 -16
  166. package/dist/commands/install/upgrade.js +15 -32
  167. package/dist/commands/launch.js +27 -11
  168. package/dist/commands/tips.js +10 -0
  169. package/dist/commands/workflow/runs.js +52 -16
  170. package/dist/commands/workflow/runtime.js +8 -0
  171. package/dist/commands/workflow/steps.js +1 -0
  172. package/dist/commands/workflow/tests.js +541 -4
  173. package/dist/commands/workflow/workstreams.js +4 -4
  174. package/dist/install/cloud-env.js +3 -14
  175. package/dist/install/hosts.js +22 -0
  176. package/dist/install/managed-block.js +36 -0
  177. package/dist/install/manifest.js +45 -4
  178. package/dist/install/modules/antigravity.js +8 -7
  179. package/dist/install/modules/claude.js +6 -6
  180. package/dist/install/modules/cloud.js +2 -2
  181. package/dist/install/modules/codex.js +5 -5
  182. package/dist/install/modules/core.js +14 -5
  183. package/dist/install/modules/cursor.js +6 -6
  184. package/dist/install/modules/opencode.js +4 -4
  185. package/dist/install/payload-links.js +5 -5
  186. package/dist/install/placeholders.js +1 -1
  187. package/dist/install/version-file.js +12 -3
  188. package/dist/install/write.js +61 -2
  189. package/dist/shared/package-roots.js +8 -11
  190. package/package.json +4 -6
  191. package/.bkit/core/LICENSE.md +0 -149
  192. package/.bkit/shared/LICENSE.md +0 -22
  193. package/.bkit/templates/LICENSE.md +0 -22
@@ -0,0 +1,297 @@
1
+ // checks/tips/catalogue.ts — the setup-tip catalogue: one entry per template, tool or
2
+ // setting a consumer has not set up yet. Each workflow prints one tip at its close
3
+ // (`bkit tips --workflow=<name>`); `bkit tips` prints the top three; `.bkit/advisories.md`
4
+ // lists every firing tip under `Setup tips`.
5
+ //
6
+ // Array order is the priority: comms first (can workflows reach anything), then change
7
+ // quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
8
+ // setup-specific plumbing last. `workflows` names where a tip matters: a workflow shows
9
+ // its own tips first, in array order, then the rest. Comms tips name every workflow, so
10
+ // they lead everywhere until fixed.
11
+ //
12
+ // Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
13
+ // never name an outside service — examples of specific services go in `steps`, which is
14
+ // for the agent. A template's benefit reads the same here, in its `.bkit/templates.md`
15
+ // section opener and in the README's "Templates ready to adopt" row; change all three in
16
+ // the same commit.
17
+ //
18
+ // Detection rules: every `fires` is local (files, settings, environment) — no network.
19
+ // Where an advisory already detects the gap, `fires` calls that detector and `advisories`
20
+ // names its ids, so the tip and the advisory can never disagree and one
21
+ // `bkit.ignoreAdvisories` entry silences both.
22
+ import { detectContextFetchMissing } from "../before/context-fetch.js";
23
+ import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
24
+ import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
25
+ import { buildTrackerSetupAdvisory, readConsumerCloudAgents, readConsumerIssueTracker, } from "../after/github.js";
26
+ import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
27
+ import { detectInstalledHostModules } from "../../install/hosts.js";
28
+ import { readBkitConfig } from "../../shared/settings.js";
29
+ import { claudeSettingsHas, codexTopLevelHas, exists, hasLintStagedConfig, hasMcpServer, unlockedMcpServers, } from "./detect.js";
30
+ const hosts = (cwd) => detectInstalledHostModules(cwd);
31
+ /** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
32
+ export const ALL_WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
33
+ export const SETUP_TIPS = [
34
+ // --- connect: can bkit talk to anything at all -------------------------------------
35
+ {
36
+ id: "tracker",
37
+ workflows: ALL_WORKFLOWS,
38
+ title: "Connect an issue tracker",
39
+ line: "bkit isn't connected to an issue tracker, so it can't read the task it's working on or record what it did. Connect GitHub or Linear, or switch this tip off if you don't want one.",
40
+ why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
41
+ ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.issueTracker` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
42
+ steps: '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "issueTracker": "none" }` in `package.json`.',
43
+ advisories: ["tracker-setup-none"],
44
+ fires: (cwd) => buildTrackerSetupAdvisory(cwd)?.id === "tracker-setup-none",
45
+ },
46
+ {
47
+ id: "gh-mcp",
48
+ workflows: ALL_WORKFLOWS,
49
+ title: "Give bkit its GitHub token",
50
+ line: "You chose GitHub as your tracker, but bkit has no GitHub token, so every attempt to read an issue or open a pull request will fail. Add the token.",
51
+ why: "Choosing GitHub only tells bkit where your issues live. The token is what lets it actually sign in. Without it the setting looks right but nothing works, which is confusing to track down.",
52
+ ask: "Add my GitHub token as `BKIT_GH_TOKEN` in .bkit/.env, check .mcp.json has the `github` server, then run `direnv allow` and tell me to restart the editor.",
53
+ steps: "`.bkit/install.md` § Local env setup. The `github` server entry belongs in `.mcp.json` / `.cursor/mcp.json` (`.bkit/cloud.md` § MCP issue-tracker integration).",
54
+ advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
55
+ fires: (cwd) => readConsumerIssueTracker(cwd) === "github" &&
56
+ (!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
57
+ },
58
+ {
59
+ id: "bkit-env",
60
+ workflows: ALL_WORKFLOWS,
61
+ title: "Create bkit's private settings file",
62
+ line: "bkit's private settings file (.bkit/.env) is missing or has blank entries, so nothing that needs to sign in can. Create it and fill it in.",
63
+ why: "This one file holds the sign-in tokens every bkit tool reads. It's never shared or committed. Most other tips depend on it, so do this one early.",
64
+ ask: "Copy .bkit/.env.example to .bkit/.env and tell me which values I need to fill in.",
65
+ steps: "`.bkit/install.md` § Local env setup.",
66
+ advisories: ["mcp-env-missing-dotenv", "mcp-env-blank-key-*"],
67
+ fires: (cwd) => {
68
+ if (isCloudOrCi())
69
+ return false;
70
+ const tracker = readConsumerIssueTracker(cwd);
71
+ return (detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0);
72
+ },
73
+ },
74
+ {
75
+ id: "direnv",
76
+ workflows: ALL_WORKFLOWS,
77
+ title: "Load your tokens automatically",
78
+ line: "Your sign-in tokens are saved in .bkit/.env but not being loaded, so sign-ins will fail even though the file looks right. Set up direnv so they load whenever you open the project.",
79
+ why: "A saved file does nothing until something reads it. This is the most frustrating kind of breakage: nothing looks wrong, but every sign-in fails. direnv (a small tool that loads settings when you open a folder) fixes it once.",
80
+ ask: "Copy .bkit/templates/.envrc to .envrc, install direnv if it's missing (`brew install direnv` on a Mac, then add its shell hook), and run `direnv allow`.",
81
+ steps: "`.bkit/templates.md` § direnv.",
82
+ advisories: ["mcp-env-direnv-missing", "mcp-env-direnv-not-allowed"],
83
+ fires: (cwd) => {
84
+ if (isCloudOrCi() || !exists(cwd, ".bkit/.env"))
85
+ return false;
86
+ const tracker = readConsumerIssueTracker(cwd);
87
+ return (!exists(cwd, ".envrc") ||
88
+ detectDirenvMissing(cwd, tracker) !== null ||
89
+ detectDirenvNotAllowed(cwd, tracker) !== null);
90
+ },
91
+ },
92
+ // --- quality: is the change good -----------------------------------------------------
93
+ {
94
+ id: "serena",
95
+ workflows: ["design", "plan", "build"],
96
+ title: "Let agents look code up directly",
97
+ line: "Agents are finding code by searching for words, which is slower, costs more, and misses things. Set up Serena so they can look code up directly.",
98
+ why: 'Serena lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of guessing from text search and reading whole files. That means fewer accidental changes, fewer rounds of you correcting them, and lower running costs because they read less. It can only look things up, never change your files.',
99
+ ask: "Run `brew install uv` and `uv tool install -p 3.13 serena-agent`, copy .bkit/templates/.serena/project.yml to .serena/project.yml and .bkit/templates/scripts/serena/ to scripts/serena/, then add the `serena` server from scripts/serena/bkit-serena.mcp.json to .mcp.json (details: .bkit/templates.md § Serena).",
100
+ steps: "`.bkit/templates.md` § Serena.",
101
+ fires: (cwd) => !exists(cwd, ".serena/project.yml") || !hasMcpServer(cwd, "serena"),
102
+ },
103
+ {
104
+ id: "ci-workflow",
105
+ workflows: ["build", "ship"],
106
+ title: "Automatic checks on every change",
107
+ line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
108
+ why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
109
+ ask: "Copy .bkit/templates/.github/workflows/bkit-ci.yml to .github/workflows/bkit-ci.yml, replace `main` and `{{NODE_VERSION}}` in it with my default branch and Node major version, and add the `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
110
+ steps: "`.bkit/templates.md` § CI workflow and § Gate tool scripts.",
111
+ fires: (cwd) => !exists(cwd, `.github/workflows/${readBkitConfig(cwd).ciWorkflow}`),
112
+ },
113
+ {
114
+ id: "husky",
115
+ workflows: ["build"],
116
+ title: "Catch problems before they leave your machine",
117
+ line: "Mistakes are only caught after changes reach GitHub. Add the local checks so they're caught the moment a change is saved to git.",
118
+ why: "These run the same checks on your own computer, in seconds, whenever a change is committed or pushed. Without them you find out minutes later from a failed build, after the agent has moved on and fixing it costs more.",
119
+ ask: 'Run `pnpm add -D husky`, add `"prepare": "husky"` to the package.json scripts, copy .bkit/templates/.husky/pre-commit and .bkit/templates/.husky/pre-push to .husky/, and run `chmod +x .husky/pre-commit .husky/pre-push`.',
120
+ steps: "`.bkit/templates.md` § Git hooks.",
121
+ fires: (cwd) => !exists(cwd, ".husky/pre-commit"),
122
+ },
123
+ {
124
+ id: "prettier",
125
+ workflows: ["build"],
126
+ title: "Consistent formatting",
127
+ line: "There's no shared formatting setup, so reviews fill up with spacing changes that hide the real ones. Add Prettier with bkit's ignore file.",
128
+ why: "Prettier (a code formatter) makes every file follow the same layout. bkit's ignore file stops it reformatting bkit's own files, which would otherwise show up as false changes every time bkit updates.",
129
+ ask: 'Copy .bkit/templates/.prettierignore to .prettierignore first, then run `pnpm add -D prettier` and add `"format:check": "prettier --check ."` to the package.json scripts.',
130
+ steps: "`.bkit/templates.md` § Prettier.",
131
+ fires: (cwd) => !exists(cwd, ".prettierignore"),
132
+ },
133
+ {
134
+ id: "slop-scan",
135
+ workflows: ["build"],
136
+ title: "Catch junk code",
137
+ line: "Nothing catches the junk code AI tends to write. Add slop-scan so new junk gets flagged before it's merged.",
138
+ why: "Filler and dead code look fine when you skim a change, so they pile up unnoticed until the codebase is hard to trust. slop-scan flags only new problems, so it won't bury you in old ones.",
139
+ ask: 'Run `pnpm add -D slop-scan`, copy .bkit/templates/slop-scan.config.json to slop-scan.config.json and .bkit/templates/scripts/slop/ to scripts/slop/, and add `"lint:slop": "slop-scan scan ."` and `"slop:delta": "bkit ci slop"` to the package.json scripts.',
140
+ steps: "`.bkit/templates.md` § slop-scan.",
141
+ fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
142
+ },
143
+ {
144
+ id: "vale",
145
+ workflows: ["design", "plan"],
146
+ title: "Keep written docs tight",
147
+ line: "Nothing checks the project's written docs, so they slowly fill with vague, padded wording that agents then have to read. Add Vale.",
148
+ why: "Agents read your docs and instructions on every run. Padded writing costs time and money every time it's read, and vague rules get followed vaguely. Vale (a writing checker) flags it.",
149
+ ask: "Run `brew install vale`, copy .bkit/templates/.vale.ini to .vale.ini and .bkit/templates/.vale/styles/House/ to .vale/styles/House/, then run `vale sync`.",
150
+ steps: "`.bkit/templates.md` § Vale.",
151
+ fires: (cwd) => !exists(cwd, ".vale.ini"),
152
+ },
153
+ {
154
+ id: "lint-staged",
155
+ workflows: ["build"],
156
+ title: "Quick tidy-up on commit",
157
+ line: "The commit check has nothing to run. Add lint-staged so it tidies just the files you're committing.",
158
+ why: "It formats only the handful of files in each change, in about a second. Without it the commit check either does nothing or is slow enough that people start skipping it.",
159
+ ask: "Run `pnpm add -D lint-staged prettier` and copy .bkit/templates/.lintstagedrc.json to .lintstagedrc.json.",
160
+ steps: "`.bkit/templates.md` § lint-staged.",
161
+ fires: (cwd) => !hasLintStagedConfig(cwd),
162
+ },
163
+ // --- delivery: did it land well ------------------------------------------------------
164
+ {
165
+ id: "cloud",
166
+ workflows: ["ship"],
167
+ title: "Finish cloud setup",
168
+ line: "You've turned on cloud agents, but setup isn't finished, so cloud runs will stop partway. Finish the remaining steps.",
169
+ why: "With cloud agents, bkit runs on its own: a change that passes its checks gets shipped and one that fails gets investigated, with nobody at the keyboard. That only works once every piece is in place.",
170
+ ask: "Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml and .bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh to .claude/hooks/ (for Cursor: .bkit/templates/.cursor/environment.json and .bkit/templates/.cursor/Dockerfile to .cursor/), run `gh secret set ANTHROPIC_API_KEY`, then tell me which dashboard settings are left.",
171
+ steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
172
+ fires: (cwd) => {
173
+ const cloud = readConsumerCloudAgents(cwd);
174
+ if (cloud === "none")
175
+ return false;
176
+ if (cloud === "cursor") {
177
+ return !exists(cwd, ".cursor/environment.json") || !exists(cwd, ".cursor/Dockerfile");
178
+ }
179
+ if (!exists(cwd, ".github/workflows/bkit-cloud.yml"))
180
+ return true;
181
+ return cloud === "claude" && !exists(cwd, ".claude/hooks/bkit-cloud-bootstrap.sh");
182
+ },
183
+ },
184
+ {
185
+ id: "context-fetch",
186
+ workflows: ["debug"],
187
+ title: "Let debugging see real errors",
188
+ line: "When something breaks, the debug workflow can't see your live error reports or logs, so it has to guess from the code. Connect the services you use.",
189
+ why: "This lets /bkit-debug read the actual errors from your error tracker, hosting and database. Without it the agent works from guesses, and real problems stay hidden because nothing brings in the evidence.",
190
+ ask: "Copy the blocks for the services this project uses from .bkit/templates/context/ into .agents/context.md, below the `<!-- bkit:end -->` line, then tell me which tokens to add to .bkit/.env.",
191
+ steps: "`.bkit/templates.md` § Context-fetch blocks.",
192
+ advisories: ["context-fetch-missing"],
193
+ fires: (cwd) => detectContextFetchMissing(cwd) !== null,
194
+ },
195
+ {
196
+ id: "secrets-sync",
197
+ workflows: ["debug", "ship"],
198
+ title: "Keep passwords the same everywhere",
199
+ line: "Your deployment passwords are updated by hand in each service. Add bkit's sync tool so they're set in one place and copied everywhere.",
200
+ why: 'The same password usually lives in several places: your hosting, your database, GitHub. When one falls out of step you get "works for me, broken in production", the slowest kind of bug to find. This keeps them matching and proves it without showing any values.',
201
+ ask: "Copy .bkit/templates/scripts/secrets/ to scripts/secrets/, fill in scripts/secrets/bkit-secrets.config.mjs for the services this project uses, then run `node scripts/secrets/bkit-secrets.mjs sync --dry-run`.",
202
+ steps: "`.bkit/templates.md` § Secrets sync.",
203
+ fires: (cwd) => !exists(cwd, "scripts/secrets"),
204
+ },
205
+ // --- cost: running cost ---------------------------------------------------------------
206
+ {
207
+ id: "compaction-window",
208
+ workflows: ["design", "plan", "build"],
209
+ title: "Summarise long sessions earlier",
210
+ line: "Long sessions only summarise themselves when they're nearly full, so every step re-reads a huge history, and that re-reading is most of what a run costs. Set an earlier summarise point.",
211
+ why: "Each request re-reads the whole session so far. Left at the default, a session grows close to the model's full size before it summarises, and most subagents never summarise at all. An earlier summarise point keeps every request smaller.",
212
+ caution: "Summaries lose some detail. A summarise point set too low can stop agents mid-run. 300,000 tokens is a starting value, not yet checked on a real build.",
213
+ ask: 'Add `"autoCompactWindow": 300000` to .claude/settings.json. For Codex, add `model_auto_compact_token_limit = 300000` at the top of .codex/config.toml, above the first `[section]`.',
214
+ steps: '`.bkit/providers.md` § Context compaction. Claude Code: `"autoCompactWindow": 300000` in `.claude/settings.json`. Codex: `model_auto_compact_token_limit = 300000` in `.codex/config.toml`, above the first `[section]` header.',
215
+ fires: (cwd) => {
216
+ const h = hosts(cwd);
217
+ return ((h.has("claude") && !claudeSettingsHas(cwd, "autoCompactWindow")) ||
218
+ (h.has("codex") && !codexTopLevelHas(cwd, "model_auto_compact_token_limit")));
219
+ },
220
+ },
221
+ {
222
+ id: "mcp-scope",
223
+ workflows: ["design", "plan", "debug"],
224
+ title: "Lock MCP servers to this project",
225
+ line: "Some of this project's MCP servers can see every project on your account, so agents spend calls working out which one is yours. Lock them to this project.",
226
+ why: "An MCP server (a connection that lets an agent use an outside service directly) that can see your whole account makes agents look up account and project IDs before they can do anything. Locked to one project, those lookup steps disappear and every call goes straight to the right place.",
227
+ ask: "Lock each server URL in .mcp.json, .cursor/mcp.json and .opencode/opencode.json to this project, following .bkit/providers.md § MCP project scope.",
228
+ steps: "`.bkit/providers.md` § MCP project scope. Lock the server URL to one account and project in every host's MCP file, e.g. `https://mcp.sentry.dev/mcp/<org>/<project>`, `https://mcp.supabase.com/mcp?project_ref=<ref>&read_only=true`, `https://mcp.vercel.com/<team>/<project>`.",
229
+ fires: (cwd) => unlockedMcpServers(cwd).length > 0,
230
+ },
231
+ {
232
+ id: "claude-connectors",
233
+ workflows: ["design", "plan"],
234
+ title: "Stop loading claude.ai connectors in this project",
235
+ line: "Claude Code loads every connector on your claude.ai account in this project (for example email, calendar or file storage) and sends their names with every request, even when unused. If agents here don't use them, switch them off for this project.",
236
+ why: "Every connector's tool names are re-sent on every request, which is the largest part of the starting load you can remove. The connectors keep working in ordinary Claude chats (web and desktop app) and in cloud routines; only Claude Code in this project stops loading them.",
237
+ ask: 'Check whether agents in this project use any claude.ai connectors. If none, add `"disableClaudeAiConnectors": true` to .claude/settings.json.',
238
+ steps: '`.bkit/providers.md` § claude.ai connectors. Move anything agents use through a connector onto the project\'s MCP file first, then set `"disableClaudeAiConnectors": true` in `.claude/settings.json`.',
239
+ fires: (cwd) => hosts(cwd).has("claude") && !claudeSettingsHas(cwd, "disableClaudeAiConnectors"),
240
+ },
241
+ // --- optional: nice to have ------------------------------------------------------------
242
+ {
243
+ id: "graphify",
244
+ workflows: ["design", "plan"],
245
+ title: "A map of the code",
246
+ line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
247
+ why: "With a map, agents check what already exists before building it again. Without one, agents and reviews work out the structure from scratch each time. That's slower, and it's easy to miss how one change ripples into another part of the code.",
248
+ ask: 'Run `uv tool install "graphifyy[sql]"`, copy .bkit/templates/scripts/graphify/ to scripts/graphify/ and .bkit/templates/.graphifyignore to .graphifyignore, then add the graph scripts to package.json as listed in .bkit/templates.md § graphify.',
249
+ steps: "`.bkit/templates.md` § graphify.",
250
+ fires: (cwd) => !exists(cwd, "scripts/graphify"),
251
+ },
252
+ {
253
+ id: "dependabot-renovate",
254
+ workflows: ["ship"],
255
+ title: "Automatic updates",
256
+ line: "Nothing keeps the project's libraries up to date. Add an updater so you get small, safe updates instead of one big risky one later.",
257
+ why: "An updater opens a small pull request whenever a library you use has a new version. Skip it and updates pile up into one large upgrade that's far more likely to break something.",
258
+ ask: "Copy .bkit/templates/.github/dependabot.yml to .github/dependabot.yml (or .bkit/templates/.github/renovate.json5 to .github/renovate.json5 for Renovate instead) and commit it to the default branch.",
259
+ steps: "`.bkit/templates.md` § Dependabot and Renovate.",
260
+ advisories: ["dep-updater-absent"],
261
+ fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
262
+ },
263
+ {
264
+ id: "prettier-tables",
265
+ workflows: ["design", "plan"],
266
+ title: "Readable table changes",
267
+ line: "Optional: if your docs have tables, add this so editing one cell doesn't show the whole table as changed.",
268
+ why: "Changing one cell normally reformats the whole table, so a one-word edit looks like a page of changes and reviewers can't see what actually moved.",
269
+ ask: "Copy .bkit/templates/scripts/prettier/bkit-insert-ignore.mjs to scripts/prettier/ and run `node scripts/prettier/bkit-insert-ignore.mjs`.",
270
+ steps: "`.bkit/templates.md` § Prettier tables.",
271
+ fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
272
+ },
273
+ // --- setup: only some setups -----------------------------------------------------------
274
+ {
275
+ id: "cursor-files",
276
+ title: "Cursor editor settings",
277
+ line: "You use Cursor, but bkit's editor settings aren't added, so files aren't formatted when you save them. Add them.",
278
+ why: "The settings file turns on format-on-save and recommends the project's extensions, so every edit made in Cursor already matches the project's formatting.",
279
+ ask: "Copy .bkit/templates/.cursor/settings.json to .cursor/settings.json.",
280
+ steps: "`.bkit/templates.md` § Cursor.",
281
+ fires: (cwd) => hosts(cwd).has("cursor") && !exists(cwd, ".cursor/settings.json"),
282
+ },
283
+ {
284
+ id: "launchd",
285
+ title: "Tokens for apps opened from the Dock",
286
+ line: "On a Mac, apps opened from the Dock don't see your sign-in tokens, so they start signed out even though the same thing works in the terminal. Add bkit's loader.",
287
+ why: "The terminal loads your tokens, but apps started from the Dock or Finder skip that step. This one-time setup gives those apps the tokens too.",
288
+ ask: "Copy .bkit/templates/scripts/launchd/bkit-launchd-env.sh to scripts/launchd/, .bkit/templates/scripts/launchd/launchd.env.example to ~/.config/bkit/launchd.env and .bkit/templates/scripts/launchd/ai.bkit.launchd.plist to ~/Library/LaunchAgents/ (fill in its paths), then run `launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.",
289
+ steps: "`.bkit/templates.md` § Launchd GUI environment.",
290
+ fires: (cwd) => {
291
+ if (process.platform !== "darwin" || isCloudOrCi())
292
+ return false;
293
+ const h = hosts(cwd);
294
+ return (h.has("cursor") || h.has("opencode")) && !exists(cwd, "scripts/launchd");
295
+ },
296
+ },
297
+ ];
@@ -0,0 +1,130 @@
1
+ // checks/tips/detect.ts — local-only probes the setup-tip catalogue keys on: host MCP
2
+ // configs, host settings files, lint-staged config forms. No network.
3
+ import * as fs from "node:fs";
4
+ import * as path from "node:path";
5
+ import { parseJson } from "../../shared/json.js";
6
+ import { readPackageJson } from "../../shared/package-json.js";
7
+ /** True when `rel` exists under `cwd`. */
8
+ export const exists = (cwd, rel) => fs.existsSync(path.join(cwd, rel));
9
+ /** Parsed JSON object at `rel`, or `null` when absent, unparseable or not an object. */
10
+ function readJsonObject(cwd, rel) {
11
+ const p = path.join(cwd, rel);
12
+ if (!fs.existsSync(p))
13
+ return null;
14
+ const parsed = parseJson(fs.readFileSync(p, "utf-8"));
15
+ if (!parsed.ok)
16
+ return null;
17
+ const value = parsed.value;
18
+ return typeof value === "object" && value !== null && !Array.isArray(value)
19
+ ? value
20
+ : null;
21
+ }
22
+ /** Text of `rel`, or `""` when absent. */
23
+ function readText(cwd, rel) {
24
+ const p = path.join(cwd, rel);
25
+ return fs.existsSync(p) ? fs.readFileSync(p, "utf-8") : "";
26
+ }
27
+ /** Codex `[mcp_servers.<name>]` tables and their `url` keys. */
28
+ function codexMcpServers(toml) {
29
+ const out = [];
30
+ let current = null;
31
+ for (const line of toml.split(/\r?\n/)) {
32
+ const header = /^\s*\[([^\]]+)\]\s*$/.exec(line);
33
+ if (header) {
34
+ const m = /^mcp_servers\.("?)([^"]+)\1$/.exec(header[1].trim());
35
+ current = m ? { name: m[2], url: null } : null;
36
+ if (current)
37
+ out.push(current);
38
+ continue;
39
+ }
40
+ const url = /^\s*url\s*=\s*"([^"]*)"/.exec(line);
41
+ if (current && url)
42
+ current.url = url[1];
43
+ }
44
+ return out;
45
+ }
46
+ /**
47
+ * Every MCP server configured for any host: `.mcp.json` and `.cursor/mcp.json`
48
+ * (`mcpServers`), `.opencode/opencode.json` (`mcp`), `.codex/config.toml`
49
+ * (`[mcp_servers.<name>]`).
50
+ */
51
+ export function listMcpServers(cwd) {
52
+ const out = [];
53
+ const fromMap = (file, map) => {
54
+ if (typeof map !== "object" || map === null)
55
+ return;
56
+ for (const [name, entry] of Object.entries(map)) {
57
+ const url = entry?.url;
58
+ out.push({ file, name, url: typeof url === "string" ? url : null });
59
+ }
60
+ };
61
+ fromMap(".mcp.json", readJsonObject(cwd, ".mcp.json")?.mcpServers);
62
+ fromMap(".cursor/mcp.json", readJsonObject(cwd, ".cursor/mcp.json")?.mcpServers);
63
+ fromMap(".opencode/opencode.json", readJsonObject(cwd, ".opencode/opencode.json")?.mcp);
64
+ for (const s of codexMcpServers(readText(cwd, ".codex/config.toml"))) {
65
+ out.push({ file: ".codex/config.toml", ...s });
66
+ }
67
+ return out;
68
+ }
69
+ /** True when any host config declares an MCP server named `name`. */
70
+ export const hasMcpServer = (cwd, name) => listMcpServers(cwd).some((s) => s.name === name);
71
+ /**
72
+ * Remote MCP services that accept a URL locked to one account + project, and the test
73
+ * for a locked URL. A locked server hides its ID-lookup tools and defaults every call to
74
+ * that project.
75
+ */
76
+ const SCOPABLE_MCP_HOSTS = [
77
+ // https://mcp.sentry.dev/mcp/<org>/<project>
78
+ {
79
+ host: "mcp.sentry.dev",
80
+ locked: (u) => u.pathname.split("/").filter(Boolean).length >= 3,
81
+ },
82
+ // https://mcp.supabase.com/mcp?project_ref=<ref>
83
+ { host: "mcp.supabase.com", locked: (u) => u.searchParams.has("project_ref") },
84
+ // https://mcp.vercel.com/<team>/<project>
85
+ {
86
+ host: "mcp.vercel.com",
87
+ locked: (u) => u.pathname.split("/").filter(Boolean).length >= 2,
88
+ },
89
+ ];
90
+ /** MCP servers on a lockable service whose URL is not locked to one project. */
91
+ export function unlockedMcpServers(cwd) {
92
+ return listMcpServers(cwd).filter((s) => {
93
+ if (!s.url || !URL.canParse(s.url))
94
+ return false;
95
+ const url = new URL(s.url);
96
+ const service = SCOPABLE_MCP_HOSTS.find((h) => h.host === url.hostname);
97
+ return service !== undefined && !service.locked(url);
98
+ });
99
+ }
100
+ /** True when `.claude/settings.json` or `.claude/settings.local.json` sets `key`. */
101
+ export function claudeSettingsHas(cwd, key) {
102
+ return [".claude/settings.json", ".claude/settings.local.json"].some((rel) => {
103
+ const settings = readJsonObject(cwd, rel);
104
+ return settings !== null && key in settings;
105
+ });
106
+ }
107
+ /** True when `.codex/config.toml` sets `key` at top level (above the first table header). */
108
+ export function codexTopLevelHas(cwd, key) {
109
+ const topLevel = readText(cwd, ".codex/config.toml").split(/^\s*\[/m)[0] ?? "";
110
+ return new RegExp(`^\\s*${key}\\s*=`, "m").test(topLevel);
111
+ }
112
+ const LINT_STAGED_CONFIGS = [
113
+ ".lintstagedrc",
114
+ ".lintstagedrc.json",
115
+ ".lintstagedrc.yaml",
116
+ ".lintstagedrc.yml",
117
+ ".lintstagedrc.mjs",
118
+ ".lintstagedrc.cjs",
119
+ ".lintstagedrc.js",
120
+ "lint-staged.config.mjs",
121
+ "lint-staged.config.cjs",
122
+ "lint-staged.config.js",
123
+ ];
124
+ /** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
125
+ export function hasLintStagedConfig(cwd) {
126
+ if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel)))
127
+ return true;
128
+ const pkg = readPackageJson(cwd);
129
+ return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
130
+ }
@@ -0,0 +1,146 @@
1
+ // checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
2
+ // console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
3
+ import { ignoredAdvisoryIds, } from "../after/suppression.js";
4
+ import { SETUP_TIPS } from "./catalogue.js";
5
+ /** Tips `bkit tips` prints without `--all` or `--workflow`. */
6
+ export const TIPS_CAP = 3;
7
+ /** Tips a workflow prints at its close (`bkit tips --workflow=<name>`). */
8
+ export const WORKFLOW_TIPS_CAP = 1;
9
+ /** Section heading in the console checklist and `.bkit/advisories.md`. */
10
+ export const SETUP_TIPS_HEADING = "Setup tips";
11
+ /** Opening line of `bkit tips` output, by how many tips it prints. */
12
+ export const tipsIntro = (n) => n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
13
+ /** Where the full tip list lives. */
14
+ export const TIPS_DETAILS_POINTER = "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
15
+ /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
16
+ export const TIPS_SECTION_INTRO = "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
17
+ /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
18
+ export function matchesAdvisory(pattern, id) {
19
+ return pattern.endsWith("*") ? id.startsWith(pattern.slice(0, -1)) : id === pattern;
20
+ }
21
+ /** True when `ignored` names the tip's id or any advisory id it reuses. */
22
+ export function isTipSilenced(tip, ignored) {
23
+ if (ignored.has(tip.id))
24
+ return true;
25
+ const patterns = tip.advisories ?? [];
26
+ return [...ignored].some((id) => patterns.some((p) => matchesAdvisory(p, id)));
27
+ }
28
+ /** Every firing tip in priority order, minus the ones the root package.json silences. */
29
+ export function collectTips(cwd, catalogue = SETUP_TIPS) {
30
+ const ignored = ignoredAdvisoryIds(cwd);
31
+ const tips = [];
32
+ const suppressed = [];
33
+ for (const tip of catalogue) {
34
+ if (!tip.fires(cwd))
35
+ continue;
36
+ if (isTipSilenced(tip, ignored))
37
+ suppressed.push({ id: tip.id, scope: "." });
38
+ else
39
+ tips.push(tip);
40
+ }
41
+ return { tips, suppressed };
42
+ }
43
+ /**
44
+ * Drop advisory findings whose tip the root package.json silenced, so one
45
+ * `bkit.ignoreAdvisories` entry silences a tip and the advisories it reuses. Blockers are
46
+ * never dropped.
47
+ */
48
+ export function dropTipSilencedAdvisories(findings, cwd, onSuppressed, catalogue = SETUP_TIPS) {
49
+ const ignored = ignoredAdvisoryIds(cwd);
50
+ if (ignored.size === 0)
51
+ return findings;
52
+ const patterns = catalogue
53
+ .filter((tip) => isTipSilenced(tip, ignored))
54
+ .flatMap((tip) => tip.advisories ?? []);
55
+ return findings.filter((f) => {
56
+ if (f.severity !== "advisory" || !patterns.some((p) => matchesAdvisory(p, f.id)))
57
+ return true;
58
+ onSuppressed?.({ id: f.id, scope: "." });
59
+ return false;
60
+ });
61
+ }
62
+ /** One tip as numbered terminal lines: title, then line, ask and caution indented. */
63
+ function tipTextLines(tip, n) {
64
+ const lines = [`${n}. ${tip.title}`, ` ${tip.line}`, ` Ask your agent: "${tip.ask}"`];
65
+ if (tip.caution)
66
+ lines.push(` Caution: ${tip.caution}`);
67
+ return lines;
68
+ }
69
+ /** One tip as markdown paragraphs for a workflow's `## Setup Tips` section. */
70
+ function tipMarkdownLines(tip) {
71
+ const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
72
+ if (tip.caution)
73
+ lines.push("", `Caution: ${tip.caution}`);
74
+ return lines;
75
+ }
76
+ /**
77
+ * `tips` with the ones that matter in `workflow` first, each group in catalogue order.
78
+ * Comms tips name every workflow, so they stay first everywhere.
79
+ */
80
+ export function orderForWorkflow(tips, workflow) {
81
+ const own = tips.filter((t) => t.workflows?.includes(workflow));
82
+ return [...own, ...tips.filter((t) => !own.includes(t))];
83
+ }
84
+ /**
85
+ * `bkit tips` output, then where the rest live. `""` when no tip fires.
86
+ * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
87
+ * markdown paragraphs with no intro or numbers — the workflow appends them under its
88
+ * own `## Setup Tips` heading.
89
+ * - neither: the top `TIPS_CAP` tips as a numbered terminal list.
90
+ * - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
91
+ */
92
+ export function formatTips(tips, opts = {}) {
93
+ if (tips.length === 0)
94
+ return "";
95
+ const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
96
+ const cap = opts.workflow ? WORKFLOW_TIPS_CAP : TIPS_CAP;
97
+ const shown = opts.all ? ordered : ordered.slice(0, cap);
98
+ const rest = tips.length - shown.length;
99
+ const more = rest > 0 ? `${rest} more: \`bkit tips --all\`. ` : "";
100
+ if (opts.workflow && !opts.all) {
101
+ const lines = [];
102
+ for (const tip of shown)
103
+ lines.push(...tipMarkdownLines(tip), "");
104
+ lines.push(`${more}${TIPS_DETAILS_POINTER}`);
105
+ return lines.join("\n");
106
+ }
107
+ const lines = [tipsIntro(shown.length), ""];
108
+ shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
109
+ if (more)
110
+ lines.push(more.trimEnd());
111
+ lines.push(TIPS_DETAILS_POINTER);
112
+ return lines.join("\n");
113
+ }
114
+ /** The Setup tips block of the console checklist. `[]` when no tip fires. */
115
+ export function setupTipsChecklistLines(tips) {
116
+ if (tips.length === 0)
117
+ return [];
118
+ const lines = [`--- ${SETUP_TIPS_HEADING} ---`, TIPS_SECTION_INTRO, ""];
119
+ tips.forEach((tip, i) => {
120
+ lines.push(`${i + 1}. ${tip.title} (${tip.id})`);
121
+ lines.push(` ${tip.line}`);
122
+ lines.push(` Why: ${tip.why}`);
123
+ if (tip.caution)
124
+ lines.push(` Caution: ${tip.caution}`);
125
+ lines.push(` Ask your agent: "${tip.ask}"`);
126
+ lines.push(` Agent steps: ${tip.steps}`);
127
+ lines.push("");
128
+ });
129
+ return lines;
130
+ }
131
+ /** The `## Setup tips` section of `.bkit/advisories.md`. `[]` when no tip fires. */
132
+ export function setupTipsMarkdownLines(tips) {
133
+ if (tips.length === 0)
134
+ return [];
135
+ const lines = [`## ${SETUP_TIPS_HEADING}`, "", `> ${TIPS_SECTION_INTRO}`, ""];
136
+ tips.forEach((tip, i) => {
137
+ lines.push(`### ${i + 1}. ${tip.title} (\`${tip.id}\`)`, "");
138
+ lines.push(tip.line, "");
139
+ lines.push(`**Why:** ${tip.why}`, "");
140
+ if (tip.caution)
141
+ lines.push(`**Caution:** ${tip.caution}`, "");
142
+ lines.push(`**Ask your agent:** "${tip.ask}"`, "");
143
+ lines.push(`**Agent steps:** ${tip.steps}`, "");
144
+ });
145
+ return lines;
146
+ }