@cbartens/bkit 5.2.4 → 5.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/.bkit/README.md +27 -11
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +18 -1
  6. package/.bkit/core/.bkit/README.md +26 -10
  7. package/.bkit/core/.bkit/cloud.md +40 -39
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +16 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +346 -0
  12. package/.bkit/core/.bkit/prompts.md +90 -74
  13. package/.bkit/core/.bkit/providers.md +42 -23
  14. package/.bkit/core/.bkit/templates.md +138 -19
  15. package/.bkit/core/.bkit/trackers.md +49 -4
  16. package/.bkit/core/.bkit/workflows.md +144 -123
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -6
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +77 -26
  70. package/.bkit/core/engine/cli.ts +57 -27
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +42 -32
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +73 -130
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  78. package/.bkit/core/engine/commands/land.ts +156 -0
  79. package/.bkit/core/engine/commands/lib.ts +45 -18
  80. package/.bkit/core/engine/commands/registry.ts +2 -0
  81. package/.bkit/core/engine/commands/tips.ts +12 -5
  82. package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
  83. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  84. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  85. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  86. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  88. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  89. package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
  90. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  91. package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
  92. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  93. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  94. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  95. package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
  96. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  97. package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
  98. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
  99. package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
  100. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  101. package/.bkit/core/engine/install/manifest.ts +14 -7
  102. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  103. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  104. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  105. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  106. package/.bkit/core/engine/install/modules/core.ts +106 -70
  107. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  108. package/.bkit/core/engine/install/modules/index.ts +7 -1
  109. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  110. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  111. package/.bkit/core/engine/install/placeholders.ts +16 -35
  112. package/.bkit/core/engine/install/write.ts +59 -12
  113. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  114. package/.bkit/core/engine/render/hosts.ts +47 -67
  115. package/.bkit/core/engine/render/models.ts +29 -11
  116. package/.bkit/core/engine/shared/branches.ts +13 -0
  117. package/.bkit/core/engine/shared/egress.ts +3 -3
  118. package/.bkit/core/engine/shared/json.ts +18 -1
  119. package/.bkit/core/engine/shared/package-json.ts +63 -0
  120. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  121. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  122. package/.bkit/core/engine/shared/settings.ts +44 -0
  123. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  124. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  125. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  126. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  127. package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
  128. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  130. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  132. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  133. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  134. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  135. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  136. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  137. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  138. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  139. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  140. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  141. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  142. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  143. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  144. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  145. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  146. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  148. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  149. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  150. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  151. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  152. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  153. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  154. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  155. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  156. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  157. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  158. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  159. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  160. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  161. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  162. package/.bkit/core/workflows/bkit-auto.md +2 -2
  163. package/.bkit/core/workflows/bkit-build.md +10 -10
  164. package/.bkit/core/workflows/bkit-debug.md +80 -44
  165. package/.bkit/core/workflows/bkit-design.md +22 -13
  166. package/.bkit/core/workflows/bkit-plan.md +33 -16
  167. package/.bkit/core/workflows/bkit-ship.md +87 -98
  168. package/.bkit/shared/.claude/bkit-cloud.md +58 -25
  169. package/.bkit/shared/.claude/settings.json +19 -0
  170. package/.bkit/shared/.cursor/mcp.json +2 -1
  171. package/.bkit/shared/.opencode/opencode.json +19 -1
  172. package/.bkit/shared/docs/deployments.md +49 -29
  173. package/.bkit/shared/docs/security.md +8 -6
  174. package/.bkit/shared/docs/testing.md +9 -5
  175. package/.bkit/shared/gitignore +1 -2
  176. package/.bkit/templates/.cursor/Dockerfile +30 -16
  177. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  178. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  179. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  180. package/.bkit/templates/.github/renovate.json5 +91 -12
  181. package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
  182. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  183. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  184. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  185. package/.bkit/templates/.husky/pre-commit +6 -0
  186. package/.bkit/templates/.husky/pre-push +15 -3
  187. package/.bkit/templates/.lintstagedrc.json +5 -1
  188. package/.bkit/templates/.oxlintrc.json +21 -0
  189. package/.bkit/templates/docs/capabilities.md +1 -1
  190. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  191. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  192. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  193. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  194. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  195. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  196. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  197. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  198. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  199. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  200. package/CHANGELOG.md +98 -3
  201. package/README.md +252 -122
  202. package/dist/checks/after/auth.js +10 -11
  203. package/dist/checks/after/ci-yml.js +11 -14
  204. package/dist/checks/after/github.js +32 -125
  205. package/dist/checks/after/index.js +3 -2
  206. package/dist/checks/after/managed.js +8 -24
  207. package/dist/checks/after/tools.js +3 -16
  208. package/dist/checks/before/context-fetch.js +1 -21
  209. package/dist/checks/before/index.js +6 -42
  210. package/dist/checks/before/mcp.js +14 -9
  211. package/dist/checks/before/repo.js +8 -11
  212. package/dist/checks/status-holes.js +5 -7
  213. package/dist/checks/tips/catalogue.js +65 -18
  214. package/dist/checks/tips/detect.js +41 -2
  215. package/dist/checks/tips/index.js +61 -25
  216. package/dist/cli.js +52 -26
  217. package/dist/commands/analysis.js +21 -5
  218. package/dist/commands/comply.js +40 -31
  219. package/dist/commands/harvest.js +12 -13
  220. package/dist/commands/install/doctor.js +55 -23
  221. package/dist/commands/install/install.js +72 -122
  222. package/dist/commands/install/uninstall.js +165 -31
  223. package/dist/commands/install/upgrade.js +46 -39
  224. package/dist/commands/land.js +129 -0
  225. package/dist/commands/lib.js +41 -16
  226. package/dist/commands/registry.js +2 -0
  227. package/dist/commands/tips.js +10 -3
  228. package/dist/commands/workflow/branches.js +303 -248
  229. package/dist/commands/workflow/counters.js +17 -7
  230. package/dist/commands/workflow/disk.js +452 -0
  231. package/dist/commands/workflow/fids.js +39 -0
  232. package/dist/commands/workflow/issues.js +63 -27
  233. package/dist/commands/workflow/ledgers.js +3 -1
  234. package/dist/commands/workflow/locks.js +35 -130
  235. package/dist/commands/workflow/prs.js +8 -5
  236. package/dist/commands/workflow/repo.js +2 -2
  237. package/dist/commands/workflow/roadmap.js +50 -57
  238. package/dist/commands/workflow/runs.js +5 -5
  239. package/dist/commands/workflow/runtime.js +3 -2
  240. package/dist/commands/workflow/status.js +32 -12
  241. package/dist/commands/workflow/steps.js +19 -11
  242. package/dist/commands/workflow/tests.js +16 -3
  243. package/dist/commands/workflow/workflows.js +390 -249
  244. package/dist/commands/workflow/workstreams.js +4 -2
  245. package/dist/commands/workflow/worktrees.js +15 -6
  246. package/dist/install/cloud-env.js +10 -23
  247. package/dist/install/manifest.js +14 -7
  248. package/dist/install/modules/antigravity.js +15 -26
  249. package/dist/install/modules/claude.js +17 -21
  250. package/dist/install/modules/cloud.js +6 -2
  251. package/dist/install/modules/codex.js +15 -29
  252. package/dist/install/modules/core.js +95 -63
  253. package/dist/install/modules/cursor.js +6 -9
  254. package/dist/install/modules/index.js +6 -1
  255. package/dist/install/modules/opencode.js +41 -72
  256. package/dist/install/network-allowlist.js +62 -0
  257. package/dist/install/placeholders.js +16 -35
  258. package/dist/install/write.js +55 -15
  259. package/dist/ledgers/telemetry.js +5 -4
  260. package/dist/render/hosts.js +30 -55
  261. package/dist/render/models.js +20 -9
  262. package/dist/shared/branches.js +11 -0
  263. package/dist/shared/egress.js +0 -2
  264. package/dist/shared/json.js +14 -0
  265. package/dist/shared/package-json.js +61 -0
  266. package/dist/shared/package-roots.js +0 -8
  267. package/dist/shared/protected-paths.js +5 -122
  268. package/dist/shared/settings.js +23 -1
  269. package/dist/shared/timeouts.js +8 -7
  270. package/package.json +21 -17
  271. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -3,6 +3,7 @@
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import { spawnSync } from "node:child_process";
6
+ import { readJsonFile } from "../../shared/json.js";
6
7
  import { isCloudOrCi } from "./env.js";
7
8
  // ---------------------------------------------------------------------------
8
9
  // Blocker detectors
@@ -21,18 +22,14 @@ export function detectMalformedPackageJson(cwd) {
21
22
  const pkgPath = path.join(cwd, "package.json");
22
23
  if (!fs.existsSync(pkgPath))
23
24
  return null;
24
- try {
25
- JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
25
+ if (readJsonFile(pkgPath).ok)
26
26
  return null;
27
- }
28
- catch {
29
- return {
30
- id: "malformed-package-json",
31
- severity: "blocker",
32
- detect: "package.json exists but contains invalid JSON.",
33
- action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
34
- };
35
- }
27
+ return {
28
+ id: "malformed-package-json",
29
+ severity: "blocker",
30
+ detect: "package.json exists but contains invalid JSON.",
31
+ action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
32
+ };
36
33
  }
37
34
  export function detectNotGitRepo(cwd, modules) {
38
35
  if (!modules.has("core"))
@@ -25,6 +25,7 @@
25
25
  import * as fs from "node:fs";
26
26
  import * as path from "node:path";
27
27
  import { fileURLToPath } from "node:url";
28
+ import { parseJson } from "../shared/json.js";
28
29
  import { getWorkflowsRoot } from "../shared/package-roots.js";
29
30
  // ---------------------------------------------------------------------------
30
31
  // Canonical ship step order (mirrors audits/workflows/ship-invariants.test.ts
@@ -46,7 +47,6 @@ export const SHIP_STEP_ORDER = [
46
47
  "ship-failure-diagnose",
47
48
  "ship-failure-remediate",
48
49
  "ship-switch-to-dev",
49
- "ship-worktree-cleanup",
50
50
  "ship-close-workflow",
51
51
  ];
52
52
  /** Steps that appear only in the merge-retry loop — never mandatory, never holes. */
@@ -274,12 +274,10 @@ export function auditStatusJsonl(statusJsonl, shipMd) {
274
274
  const trimmed = line.trim();
275
275
  if (!trimmed)
276
276
  continue;
277
- try {
278
- rows.push(JSON.parse(trimmed));
279
- }
280
- catch (_e) {
281
- void _e; // skip unparseable lines (advisory — never throw)
282
- }
277
+ // Unparseable lines are skipped (advisory — never throw).
278
+ const row = parseJson(trimmed);
279
+ if (row.ok)
280
+ rows.push(row.value);
283
281
  }
284
282
  // Filter to ship step-done rows + workflow-failed rows
285
283
  const shipStepRows = rows.filter((r) => r.type === "step-done" && r.workflow === "ship" && typeof r.step === "string");
@@ -1,12 +1,13 @@
1
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`.
2
+ // setting a consumer has not set up yet. Each workflow, `@bkit-audit-generate` and the
3
+ // ledger / roadmap updaters print one tip at their close (`bkit tips --workflow=<name>`,
4
+ // `audit` / `utility` for the agents); `bkit tips` prints the top three;
5
+ // `.bkit/advisories.md` lists every firing tip under `Setup tips`.
5
6
  //
6
7
  // Array order is the priority: comms first (can workflows reach anything), then change
7
8
  // quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
8
9
  // 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
+ // its own tips first, in array order, then the rest. Comms tips name every context, so
10
11
  // they lead everywhere until fixed.
11
12
  //
12
13
  // Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
@@ -19,22 +20,26 @@
19
20
  // Where an advisory already detects the gap, `fires` calls that detector and `advisories`
20
21
  // names its ids, so the tip and the advisory can never disagree and one
21
22
  // `bkit.ignoreAdvisories` entry silences both.
23
+ import * as fs from "node:fs";
24
+ import { machineStepsPath, REPO_STEPS } from "../../commands/workflow/disk.js";
22
25
  import { detectContextFetchMissing } from "../before/context-fetch.js";
23
26
  import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
24
27
  import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
25
- import { buildTrackerSetupAdvisory, readConsumerCloudAgents, readConsumerIssueTracker, } from "../after/github.js";
28
+ import { buildTrackerSetupAdvisory } from "../after/github.js";
26
29
  import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
27
30
  import { detectInstalledHostModules } from "../../install/hosts.js";
28
31
  import { readBkitConfig } from "../../shared/settings.js";
29
- import { claudeSettingsHas, codexTopLevelHas, exists, hasLintStagedConfig, hasMcpServer, unlockedMcpServers, } from "./detect.js";
32
+ import { anyWorkflowMentions, claudeSettingsHas, codexTopLevelHas, exists, hasJsTestRunner, hasLintStagedConfig, hasMcpServer, hasTestLinter, unlockedMcpServers, } from "./detect.js";
30
33
  const hosts = (cwd) => detectInstalledHostModules(cwd);
31
34
  /** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
32
35
  export const ALL_WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
36
+ /** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
37
+ export const EVERY_CONTEXT = [...ALL_WORKFLOWS, "audit", "utility"];
33
38
  export const SETUP_TIPS = [
34
39
  // --- connect: can bkit talk to anything at all -------------------------------------
35
40
  {
36
41
  id: "tracker",
37
- workflows: ALL_WORKFLOWS,
42
+ workflows: EVERY_CONTEXT,
38
43
  title: "Connect an issue tracker",
39
44
  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
45
  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.",
@@ -45,19 +50,19 @@ export const SETUP_TIPS = [
45
50
  },
46
51
  {
47
52
  id: "gh-mcp",
48
- workflows: ALL_WORKFLOWS,
53
+ workflows: EVERY_CONTEXT,
49
54
  title: "Give bkit its GitHub token",
50
55
  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
56
  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
57
  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
58
  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
59
  advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
55
- fires: (cwd) => readConsumerIssueTracker(cwd) === "github" &&
60
+ fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" &&
56
61
  (!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
57
62
  },
58
63
  {
59
64
  id: "bkit-env",
60
- workflows: ALL_WORKFLOWS,
65
+ workflows: EVERY_CONTEXT,
61
66
  title: "Create bkit's private settings file",
62
67
  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
68
  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.",
@@ -67,13 +72,13 @@ export const SETUP_TIPS = [
67
72
  fires: (cwd) => {
68
73
  if (isCloudOrCi())
69
74
  return false;
70
- const tracker = readConsumerIssueTracker(cwd);
75
+ const tracker = readBkitConfig(cwd).issueTracker;
71
76
  return (detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0);
72
77
  },
73
78
  },
74
79
  {
75
80
  id: "direnv",
76
- workflows: ALL_WORKFLOWS,
81
+ workflows: EVERY_CONTEXT,
77
82
  title: "Load your tokens automatically",
78
83
  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
84
  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.",
@@ -83,7 +88,7 @@ export const SETUP_TIPS = [
83
88
  fires: (cwd) => {
84
89
  if (isCloudOrCi() || !exists(cwd, ".bkit/.env"))
85
90
  return false;
86
- const tracker = readConsumerIssueTracker(cwd);
91
+ const tracker = readBkitConfig(cwd).issueTracker;
87
92
  return (!exists(cwd, ".envrc") ||
88
93
  detectDirenvMissing(cwd, tracker) !== null ||
89
94
  detectDirenvNotAllowed(cwd, tracker) !== null);
@@ -92,7 +97,7 @@ export const SETUP_TIPS = [
92
97
  // --- quality: is the change good -----------------------------------------------------
93
98
  {
94
99
  id: "serena",
95
- workflows: ["design", "plan", "build"],
100
+ workflows: ["design", "plan", "build", "audit", "utility"],
96
101
  title: "Let agents look code up directly",
97
102
  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
103
  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.',
@@ -102,7 +107,7 @@ export const SETUP_TIPS = [
102
107
  },
103
108
  {
104
109
  id: "ci-workflow",
105
- workflows: ["build", "ship"],
110
+ workflows: ["build", "ship", "audit"],
106
111
  title: "Automatic checks on every change",
107
112
  line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
108
113
  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".',
@@ -140,6 +145,16 @@ export const SETUP_TIPS = [
140
145
  steps: "`.bkit/templates.md` § slop-scan.",
141
146
  fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
142
147
  },
148
+ {
149
+ id: "test-lint",
150
+ workflows: ["build"],
151
+ title: "Catch tests that can't fail",
152
+ line: "Nothing checks your test files, so a test that asserts nothing, or asserts only inside an if, still passes and the suite stays green having proved nothing. Add Oxlint with bkit's test rules.",
153
+ why: "Oxlint (a fast code linter) fails the check on a test with no assertion, a branch inside a test, an assertion that may never run, a malformed assertion, or a promise nobody waits for. Without it those tests pass whatever the code does.",
154
+ ask: "Run `pnpm add -D oxlint oxlint-tsgolint`, copy .bkit/templates/.oxlintrc.json to .oxlintrc.json, and set the `lint` script in package.json to run `oxlint -c .oxlintrc.json --type-aware --deny-warnings` (add `&&` and the current lint command if the script already has one). Then fix every hit in the tests themselves.",
155
+ steps: "`.bkit/templates.md` § Oxlint.",
156
+ fires: (cwd) => hasJsTestRunner(cwd) && !hasTestLinter(cwd),
157
+ },
143
158
  {
144
159
  id: "vale",
145
160
  workflows: ["design", "plan"],
@@ -170,7 +185,7 @@ export const SETUP_TIPS = [
170
185
  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
186
  steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
172
187
  fires: (cwd) => {
173
- const cloud = readConsumerCloudAgents(cwd);
188
+ const cloud = readBkitConfig(cwd).cloudAgents;
174
189
  if (cloud === "none")
175
190
  return false;
176
191
  if (cloud === "cursor") {
@@ -239,9 +254,19 @@ export const SETUP_TIPS = [
239
254
  fires: (cwd) => hosts(cwd).has("claude") && !claudeSettingsHas(cwd, "disableClaudeAiConnectors"),
240
255
  },
241
256
  // --- optional: nice to have ------------------------------------------------------------
257
+ {
258
+ id: "issue-forms",
259
+ workflows: ["design", "plan", "debug"],
260
+ title: "Issue forms",
261
+ line: "Optional: add issue forms so every new issue asks for what the agent reads first.",
262
+ why: "Each workflow starts from the issue. A form for an idea, a well-defined change or a bug asks for the problem, what done looks like, or the steps to reproduce. Without one, issues often arrive as a title and a line, and the agent has to guess.",
263
+ ask: "Copy .bkit/templates/.github/ISSUE_TEMPLATE/ to .github/ISSUE_TEMPLATE/ and commit it to the default branch.",
264
+ steps: "`.bkit/templates.md` § Issue forms.",
265
+ fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" && !exists(cwd, ".github/ISSUE_TEMPLATE"),
266
+ },
242
267
  {
243
268
  id: "graphify",
244
- workflows: ["design", "plan"],
269
+ workflows: ["design", "plan", "audit"],
245
270
  title: "A map of the code",
246
271
  line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
247
272
  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.",
@@ -251,7 +276,7 @@ export const SETUP_TIPS = [
251
276
  },
252
277
  {
253
278
  id: "dependabot-renovate",
254
- workflows: ["ship"],
279
+ workflows: ["ship", "audit"],
255
280
  title: "Automatic updates",
256
281
  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
282
  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.",
@@ -260,6 +285,16 @@ export const SETUP_TIPS = [
260
285
  advisories: ["dep-updater-absent"],
261
286
  fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
262
287
  },
288
+ {
289
+ id: "trivy",
290
+ workflows: ["ship", "audit"],
291
+ title: "Security scan",
292
+ line: "Nothing stops a change that adds a known-vulnerable library, a risky container setting or a leaked password from merging. Add the scan that fails the check when it finds one.",
293
+ why: "An updater only offers fixes, and only once a fixed version exists. The scan checks every change, plus once a day, so a known problem fails the check before it merges and one with no fix yet still shows up.",
294
+ ask: "Copy .bkit/templates/.github/workflows/bkit-trivy.yml to .github/workflows/bkit-trivy.yml, replace {{DEFAULT_BRANCH}} with my default branch, and commit it.",
295
+ steps: "`.bkit/templates.md` § Trivy. Accept a finding in `.trivyignore.yaml` with `statement` + `expired_at`; never drop `--include-dev-deps`.",
296
+ fires: (cwd) => exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
297
+ },
263
298
  {
264
299
  id: "prettier-tables",
265
300
  workflows: ["design", "plan"],
@@ -279,6 +314,18 @@ export const SETUP_TIPS = [
279
314
  steps: "`.bkit/templates.md` § tmp/ prune.",
280
315
  fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
281
316
  },
317
+ {
318
+ id: "disk-prune",
319
+ workflows: ALL_WORKFLOWS,
320
+ title: "Keep enough disk free for new worktrees",
321
+ line: "Build caches, Docker images and simulators fill the disk until a workflow cannot make its worktree. Add your own clean-up steps, run after commits and pushes.",
322
+ why: "bkit deletes nothing on its own: you choose the steps, starting from examples that only delete what comes back by itself. Commits run the cheap steps, pushes run the rest, and a workflow runs them before making a worktree on a nearly full disk.",
323
+ ask: "Copy .bkit/templates/scripts/cleanup/bkit-disk-prune.mjs to scripts/cleanup/ and/or .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs to ~/.config/bkit/disk-prune.mjs, edit the steps, then paste the `disk prune` block from the end of each .bkit/templates/.husky hook at the end of yours.",
324
+ steps: "`.bkit/templates.md` § Disk prune.",
325
+ fires: (cwd) => exists(cwd, ".husky/pre-push") &&
326
+ !exists(cwd, REPO_STEPS) &&
327
+ !fs.existsSync(machineStepsPath()),
328
+ },
282
329
  // --- setup: only some setups -----------------------------------------------------------
283
330
  {
284
331
  id: "cursor-files",
@@ -1,9 +1,9 @@
1
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.
2
+ // configs, host settings files, lint-staged and test-linter config forms. No network.
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import { parseJson } from "../../shared/json.js";
6
- import { readPackageJson } from "../../shared/package-json.js";
6
+ import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
7
7
  /** True when `rel` exists under `cwd`. */
8
8
  export const exists = (cwd, rel) => fs.existsSync(path.join(cwd, rel));
9
9
  /** Parsed JSON object at `rel`, or `null` when absent, unparseable or not an object. */
@@ -121,6 +121,16 @@ const LINT_STAGED_CONFIGS = [
121
121
  "lint-staged.config.cjs",
122
122
  "lint-staged.config.js",
123
123
  ];
124
+ /** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
125
+ export function anyWorkflowMentions(cwd, needle) {
126
+ const dir = path.join(cwd, ".github", "workflows");
127
+ if (!fs.existsSync(dir))
128
+ return false;
129
+ return fs
130
+ .readdirSync(dir)
131
+ .filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
132
+ .some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
133
+ }
124
134
  /** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
125
135
  export function hasLintStagedConfig(cwd) {
126
136
  if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel)))
@@ -128,3 +138,32 @@ export function hasLintStagedConfig(cwd) {
128
138
  const pkg = readPackageJson(cwd);
129
139
  return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
130
140
  }
141
+ const OXLINT_CONFIGS = [
142
+ ".oxlintrc.json",
143
+ ...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `oxlint.config.${ext}`),
144
+ ];
145
+ const ESLINT_CONFIGS = [
146
+ ".eslintrc",
147
+ ...["json", "js", "cjs", "yaml", "yml"].map((ext) => `.eslintrc.${ext}`),
148
+ ...["js", "mjs", "cjs", "ts", "mts", "cts"].map((ext) => `eslint.config.${ext}`),
149
+ ];
150
+ /** A test-framework or test-library name inside an ESLint config means it lints tests. */
151
+ const TEST_LINT_PLUGIN = /vitest|jest|playwright|testing-library/i;
152
+ /** True when `package.json` lists a JS / TS test runner (Vitest or Jest) as a dependency. */
153
+ export const hasJsTestRunner = (cwd) => readDependencyNames(cwd).some((name) => name === "vitest" || name === "jest");
154
+ /**
155
+ * True when the repo already lints its test files: an Oxlint config or `oxlint` dependency,
156
+ * or an ESLint config (file or `package.json` `eslintConfig`) that names a test plugin.
157
+ */
158
+ export function hasTestLinter(cwd) {
159
+ if (OXLINT_CONFIGS.some((rel) => exists(cwd, rel)))
160
+ return true;
161
+ if (readDependencyNames(cwd).includes("oxlint"))
162
+ return true;
163
+ const eslintConfigs = ESLINT_CONFIGS.map((rel) => readText(cwd, rel));
164
+ const pkg = readPackageJson(cwd);
165
+ if (pkg.ok && pkg.pkg["eslintConfig"] !== undefined) {
166
+ eslintConfigs.push(JSON.stringify(pkg.pkg["eslintConfig"]));
167
+ }
168
+ return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
169
+ }
@@ -1,7 +1,7 @@
1
1
  // checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
2
2
  // console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
3
3
  import { ignoredAdvisoryIds, } from "../after/suppression.js";
4
- import { SETUP_TIPS } from "./catalogue.js";
4
+ import { ALL_WORKFLOWS, SETUP_TIPS } from "./catalogue.js";
5
5
  /** Tips `bkit tips` prints without `--all` or `--workflow`. */
6
6
  export const TIPS_CAP = 3;
7
7
  /** Tips a workflow prints at its close (`bkit tips --workflow=<name>`). */
@@ -12,6 +12,23 @@ export const SETUP_TIPS_HEADING = "Setup tips";
12
12
  export const tipsIntro = (n) => n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
13
13
  /** Where the full tip list lives. */
14
14
  export const TIPS_DETAILS_POINTER = "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
15
+ /** Last line of a workflow's `## bkit Tips`: how to silence what it shows, by id. */
16
+ export function silenceLine(ids) {
17
+ const names = ids.map((id) => `\`${id}\``);
18
+ const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
19
+ const what = ids.length > 1 ? "these tips" : "this tip";
20
+ return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
21
+ }
22
+ /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
23
+ export const STAR_TIP_ID = "bkit-star";
24
+ /** Older key that also silences `STAR_TIP`, so repos that set it keep the line off. */
25
+ export const STAR_TIP_OLD_ID = "star";
26
+ /**
27
+ * Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
28
+ * workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
29
+ * gap, so never in the checklist.
30
+ */
31
+ export const STAR_TIP = "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
15
32
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
16
33
  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
34
  /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
@@ -38,7 +55,8 @@ export function collectTips(cwd, catalogue = SETUP_TIPS) {
38
55
  else
39
56
  tips.push(tip);
40
57
  }
41
- return { tips, suppressed };
58
+ const star = !ignored.has(STAR_TIP_ID) && !ignored.has(STAR_TIP_OLD_ID);
59
+ return { tips, suppressed, star };
42
60
  }
43
61
  /**
44
62
  * Drop advisory findings whose tip the root package.json silenced, so one
@@ -66,12 +84,10 @@ function tipTextLines(tip, n) {
66
84
  lines.push(` Caution: ${tip.caution}`);
67
85
  return lines;
68
86
  }
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;
87
+ /** One tip as one markdown paragraph for a workflow's `## bkit Tips` section. */
88
+ function tipParagraph(tip) {
89
+ const caution = tip.caution ? ` Caution: ${tip.caution}` : "";
90
+ return `**${tip.title}.** ${tip.line} Ask your agent: "${tip.ask}"${caution}`;
75
91
  }
76
92
  /**
77
93
  * `tips` with the ones that matter in `workflow` first, each group in catalogue order.
@@ -81,33 +97,53 @@ export function orderForWorkflow(tips, workflow) {
81
97
  const own = tips.filter((t) => t.workflows?.includes(workflow));
82
98
  return [...own, ...tips.filter((t) => !own.includes(t))];
83
99
  }
100
+ /** True when `STAR_TIP` closes the output in `workflow`: bare `bkit tips` or a phase workflow. */
101
+ export function starShownIn(workflow) {
102
+ return !workflow || ALL_WORKFLOWS.includes(workflow);
103
+ }
84
104
  /**
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.
105
+ * `bkit tips` output. `""` when no tip fires and no star line shows.
106
+ * - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow as
107
+ * one markdown paragraph each, then `STAR_TIP` when shown, then `silenceLine` naming both — the
108
+ * workflow appends them under its own `## bkit Tips` heading.
109
+ * - neither: the top `TIPS_CAP` tips as a numbered terminal list, where the rest live,
110
+ * then `STAR_TIP` when shown.
90
111
  * - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
112
+ * `STAR_TIP` shows when `opts.star` is set and `starShownIn(workflow)`.
91
113
  */
92
114
  export function formatTips(tips, opts = {}) {
115
+ const star = !!opts.star && starShownIn(opts.workflow);
116
+ if (opts.workflow && !opts.all)
117
+ return formatWorkflowTips(tips, opts.workflow, star);
118
+ const body = formatSetupTips(tips, opts);
119
+ if (!star)
120
+ return body;
121
+ return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
122
+ }
123
+ /** `formatTips` for a workflow's `## bkit Tips`: tips, star line, how to silence both. */
124
+ function formatWorkflowTips(tips, workflow, star) {
125
+ const shown = orderForWorkflow(tips, workflow).slice(0, WORKFLOW_TIPS_CAP);
126
+ const ids = shown.map((t) => t.id);
127
+ const parts = shown.map(tipParagraph);
128
+ if (star) {
129
+ parts.push(STAR_TIP);
130
+ ids.push(STAR_TIP_ID);
131
+ }
132
+ if (ids.length === 0)
133
+ return "";
134
+ return [...parts, silenceLine(ids)].join("\n\n");
135
+ }
136
+ /** `formatTips` as a terminal list, without `STAR_TIP`. */
137
+ function formatSetupTips(tips, opts) {
93
138
  if (tips.length === 0)
94
139
  return "";
95
140
  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);
141
+ const shown = opts.all ? ordered : ordered.slice(0, TIPS_CAP);
98
142
  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
143
  const lines = [tipsIntro(shown.length), ""];
108
144
  shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
109
- if (more)
110
- lines.push(more.trimEnd());
145
+ if (rest > 0)
146
+ lines.push(`${rest} more: \`bkit tips --all\`.`);
111
147
  lines.push(TIPS_DETAILS_POINTER);
112
148
  return lines.join("\n");
113
149
  }
package/dist/cli.js CHANGED
@@ -69,6 +69,17 @@ export function parseComplyPhase(value) {
69
69
  ? value
70
70
  : null;
71
71
  }
72
+ /**
73
+ * Where `bkit tips --workflow=<name>` runs: a phase workflow, `audit` (`@bkit-audit-generate`)
74
+ * or `utility` (the ledger and roadmap updaters).
75
+ */
76
+ export const TIPS_CONTEXTS = [...COMPLY_PHASES, "audit", "utility"];
77
+ /** Narrow an unknown string to `TipsContext` or return null if invalid. */
78
+ export function parseTipsContext(value) {
79
+ return typeof value === "string" && TIPS_CONTEXTS.includes(value)
80
+ ? value
81
+ : null;
82
+ }
72
83
  // Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
73
84
  // intercepted by a dedicated branch in parseArgs before this set is consulted; the
74
85
  // generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
@@ -318,9 +329,9 @@ export function parseArgs(argv) {
318
329
  }
319
330
  if (flag.startsWith("workflow=") && verb === "tips") {
320
331
  const value = flag.slice("workflow=".length);
321
- tipsWorkflow = parseComplyPhase(value);
332
+ tipsWorkflow = parseTipsContext(value);
322
333
  if (tipsWorkflow === null) {
323
- console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${COMPLY_PHASES.join(", ")}`);
334
+ console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${TIPS_CONTEXTS.join(", ")}`);
324
335
  process.exit(1);
325
336
  }
326
337
  continue;
@@ -427,11 +438,15 @@ Usage:
427
438
  re-rendering. Copies under .bkit/templates/ are refreshed by
428
439
  install/upgrade and checked for staleness — adopt one by
429
440
  copying it elsewhere; that copy is yours. The CI gate.
441
+ Changes no managed file; rewrites .bkit/advisories.md.
430
442
  bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
431
443
  Upgrade everything installed (no module flags). Diffs old
432
444
  vs new templates; conflict list emitted to stderr. Use
433
445
  --auto-apply for CI (apply non-conflicting; exit non-zero
434
- on any conflict).
446
+ on any conflict). Only a whole file you edited since bkit
447
+ wrote it conflicts; rendered files (agents, commands,
448
+ skills, .bkit/*.md) are always re-rendered — bkit check
449
+ flags an edit to one.
435
450
  --to=<version> / --latest atomically BUMP @cbartens/bkit
436
451
  (pnpm add), then re-render + re-pin in one step — so a
437
452
  version bump can never drift from its rendered mirrors.
@@ -446,17 +461,22 @@ Usage:
446
461
  --nuke to force-remove manifest-listed files). Target with the
447
462
  same module flags as install (e.g. uninstall --claude); a
448
463
  targeted uninstall leaves core untouched.
449
- bkit doctor Read-only preflight + post-install advisory replay.
450
- Diagnose token surfaces and config drift. Exits 0.
464
+ bkit doctor Preflight + post-install advisory replay (changes no
465
+ managed file; rewrites .bkit/advisories.md). Diagnose
466
+ token surfaces and config drift. Exits 0.
451
467
  bkit tips [--workflow=<name>] [--all]
452
468
  Setup tips: what this repo has not set up yet, most useful
453
469
  first, each with a sentence to ask your agent. Top three
454
470
  by default; --workflow=design|plan|build|debug|ship puts
455
471
  the tips that matter there first and prints one (each
456
- workflow runs this at its close); --all lists every one.
457
- Local checks only. Exits 0.
472
+ workflow runs this at its close; audit and utility do the
473
+ same for audits and the ledger / roadmap updaters);
474
+ --all lists every one. Ends with a star line ("bkit-star"
475
+ in bkit.ignoreAdvisories silences it), except under
476
+ --workflow=audit|utility. Local checks only. Exits 0.
458
477
  bkit status Read-only host/provider status. Reports current host+provider
459
- (sampled from .opencode/opencode.json, .claude/, .cursor/).
478
+ (sampled from .claude/, .cursor/, package.json, and the
479
+ opencode agent model pins in .opencode/agents/).
460
480
  Writes nothing. Exits 0.
461
481
  bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
462
482
  macOS GUI apps launched from the Dock/Finder do not inherit
@@ -476,12 +496,13 @@ Usage:
476
496
  bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
477
497
  and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
478
498
  for docs/deferrals.jsonl and docs/failures.jsonl).
479
- Reads consumer paths from docs/consumers.md.
499
+ Reads consumer paths from harvest/consumers.md.
480
500
  DESTRUCTIVE: harvested friction rows are REMOVED from
481
501
  the consumer, but only after they are fsync'd and read
482
502
  back from harvest/. stats.jsonl is never modified.
483
- harvest/ accumulates and is never cleared — commit it,
484
- as it is the only record of pruned rows. Never commits
503
+ harvest/ accumulates and is never cleared; it is
504
+ gitignored, so it is the only record of pruned rows —
505
+ back it up. Never commits
485
506
  in any repo. Deduplicates by per-kind composite
486
507
  identity. Advisory + fail-open: exits 0.
487
508
  bkit telemetry summary [--phase=<workflow>]
@@ -494,7 +515,7 @@ Usage:
494
515
  (design|plan|build|debug|ship). Without it, prints the
495
516
  ledger-health line only. Read-only: exits 0.
496
517
  bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
497
- #183 size↔outcome regression, dispatch-size threshold,
518
+ change-size vs outcome regression, dispatch-size threshold,
498
519
  counterSource trust labelling, per-rule compliance
499
520
  rate over kind:"compliance" rows, and the
500
521
  unjustified-deferral rate per (subagent, model)
@@ -505,7 +526,7 @@ Usage:
505
526
 
506
527
  Core (implicit — no flag; installed/upgraded on every install):
507
528
  AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
508
- .agents/docs.md + .agents/shortcuts.md + .agents/skills.md managed blocks, .gitignore +
529
+ .agents/docs.md + .agents/skills.md managed blocks, .gitignore +
509
530
  .gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
510
531
  .bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
511
532
  runs (added when missing, never overwritten, left by uninstall). The tool scripts those
@@ -557,8 +578,10 @@ Dependency updaters (copy an example and own it):
557
578
  Cross-cutting / modifiers:
558
579
  --tracker=<name> Wire issue tracker integration. Values: github, linear, none
559
580
  (default). Records bkit.issueTracker in package.json and substitutes
560
- tracker snippets into command mirrors. Switching is free (re-run with
561
- a new value). Does NOT own AGENTS.md (which is tracker-agnostic).
581
+ tracker snippets into command mirrors. Re-renders every installed
582
+ host, and works alone (bkit install --tracker=github). Switching is
583
+ free; a switch removes the old linear MCP entry unless you edited it
584
+ (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
562
585
 
563
586
  Install flags:
564
587
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -573,8 +596,9 @@ Uninstall flags:
573
596
  --opencode=<provider>
574
597
  Surgical provider removal: removes that provider's block from
575
598
  opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
576
- agents/commands/gateguard. If the removed provider was active, re-render
577
- agents by running bkit install --opencode=<remaining> or bkit upgrade.
599
+ agents/commands/gateguard. If the removed provider was active, the first
600
+ remaining provider becomes active and the agents are re-rendered to its
601
+ model pins.
578
602
  Bare --opencode (no value) tears down the entire opencode host.
579
603
  --force Delete owned whole-file files even if consumer modified them.
580
604
  --nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
@@ -624,17 +648,18 @@ function commandsUsage() {
624
648
  }
625
649
  /**
626
650
  * Validate the verb/module-flag combination before any dispatch
627
- * work runs. `install` requires >=1 module flag (bare install errors);
628
- * `check` / `upgrade` take NO module flags — they
629
- * operate on everything already installed, so a stray flag is a hard error
630
- * pointing at the no-flag form. Returns the error message to print, or `null`
651
+ * work runs. `install` requires >=1 module flag or `--tracker=` (which re-renders
652
+ * every installed host); a bare install errors. `check` / `upgrade` take NO module
653
+ * flags — they operate on everything already installed, so a stray flag is a hard
654
+ * error pointing at the no-flag form. Returns the error message to print, or `null`
631
655
  * when the combination is valid.
632
656
  */
633
- export function validateModuleFlagsForVerb(verb, moduleFlags) {
634
- if (verb === "install" && moduleFlags.size === 0) {
657
+ export function validateModuleFlagsForVerb(verb, moduleFlags, tracker = null) {
658
+ if (verb === "install" && moduleFlags.size === 0 && tracker === null) {
635
659
  return ("[bkit] `bkit install` requires at least one module flag. Name what to install: " +
636
660
  "--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
637
- `--auto=<${CLOUD_VARIANTS.join("|")}>). Run \`bkit help\` for usage.`);
661
+ `--auto=<${CLOUD_VARIANTS.join("|")}>), or --tracker=<name> alone to switch the ` +
662
+ "tracker on what is installed. Run `bkit help` for usage.");
638
663
  }
639
664
  if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
640
665
  return (`[bkit] \`bkit ${verb}\` takes no module flags — it operates on everything already ` +
@@ -694,8 +719,9 @@ export async function main() {
694
719
  await launchApp(verb, process.cwd());
695
720
  return;
696
721
  }
697
- // install requires >=1 module flag; check/upgrade take NONE (validateModuleFlagsForVerb).
698
- const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags);
722
+ // install requires >=1 module flag or --tracker=; check/upgrade take NONE
723
+ // (validateModuleFlagsForVerb).
724
+ const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags, tracker);
699
725
  if (moduleFlagsError) {
700
726
  console.error(moduleFlagsError);
701
727
  process.exit(1);