@cbartens/bkit 5.2.3 → 5.3.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 (254) hide show
  1. package/.bkit/README.md +29 -12
  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 +11 -0
  6. package/.bkit/core/.bkit/README.md +28 -11
  7. package/.bkit/core/.bkit/cloud.md +9 -8
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +15 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +345 -0
  12. package/.bkit/core/.bkit/prompts.md +88 -73
  13. package/.bkit/core/.bkit/providers.md +41 -22
  14. package/.bkit/core/.bkit/templates.md +125 -18
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +51 -45
  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 +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +10 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +22 -10
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +29 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +11 -3
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +19 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -5
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -5
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -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 -5
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +70 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  70. package/.bkit/core/engine/cli.ts +39 -16
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +17 -16
  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 +62 -126
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +58 -53
  78. package/.bkit/core/engine/commands/lib.ts +35 -10
  79. package/.bkit/core/engine/commands/tips.ts +8 -5
  80. package/.bkit/core/engine/commands/workflow/branches.ts +65 -11
  81. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  82. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  83. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  84. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  85. package/.bkit/core/engine/commands/workflow/repo.ts +18 -4
  86. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  87. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  88. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  89. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  90. package/.bkit/core/engine/commands/workflow/workflows.ts +19 -17
  91. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  92. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  93. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  94. package/.bkit/core/engine/install/manifest.ts +14 -7
  95. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  96. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  97. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  98. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  99. package/.bkit/core/engine/install/modules/core.ts +91 -70
  100. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  101. package/.bkit/core/engine/install/modules/index.ts +7 -1
  102. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  103. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  104. package/.bkit/core/engine/install/placeholders.ts +3 -18
  105. package/.bkit/core/engine/install/write.ts +59 -12
  106. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  107. package/.bkit/core/engine/render/hosts.ts +47 -67
  108. package/.bkit/core/engine/render/models.ts +29 -11
  109. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  110. package/.bkit/core/engine/shared/branches.ts +13 -0
  111. package/.bkit/core/engine/shared/egress.ts +3 -3
  112. package/.bkit/core/engine/shared/json.ts +18 -1
  113. package/.bkit/core/engine/shared/package-json.ts +63 -0
  114. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  115. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  116. package/.bkit/core/engine/shared/settings.ts +36 -0
  117. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  118. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  119. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  120. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  121. package/.bkit/core/prompts/bkit-audit-generate.md +65 -10
  122. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  123. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  124. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  125. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  126. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  127. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  128. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  130. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  132. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  133. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  134. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  135. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  136. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  137. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  138. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  139. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  140. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  141. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  142. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  143. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  144. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  145. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  146. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  148. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  149. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  150. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  151. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  152. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  153. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  154. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  155. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  156. package/.bkit/core/workflows/bkit-build.md +4 -4
  157. package/.bkit/core/workflows/bkit-debug.md +70 -34
  158. package/.bkit/core/workflows/bkit-design.md +3 -3
  159. package/.bkit/core/workflows/bkit-plan.md +12 -5
  160. package/.bkit/core/workflows/bkit-ship.md +6 -6
  161. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  162. package/.bkit/shared/.claude/settings.json +18 -0
  163. package/.bkit/shared/.cursor/mcp.json +2 -1
  164. package/.bkit/shared/.opencode/opencode.json +19 -1
  165. package/.bkit/shared/docs/deployments.md +20 -4
  166. package/.bkit/shared/docs/security.md +8 -6
  167. package/.bkit/shared/docs/testing.md +9 -5
  168. package/.bkit/templates/.cursor/Dockerfile +30 -16
  169. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  170. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  171. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  172. package/.bkit/templates/.github/renovate.json5 +91 -12
  173. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  174. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  175. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  176. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  177. package/.bkit/templates/.husky/pre-push +15 -3
  178. package/.bkit/templates/.oxlintrc.json +21 -0
  179. package/.bkit/templates/docs/capabilities.md +1 -1
  180. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  181. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  182. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  183. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  184. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  185. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  186. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  187. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  188. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  189. package/CHANGELOG.md +67 -3
  190. package/README.md +258 -129
  191. package/dist/checks/after/auth.js +10 -11
  192. package/dist/checks/after/ci-yml.js +11 -14
  193. package/dist/checks/after/github.js +32 -125
  194. package/dist/checks/after/index.js +3 -2
  195. package/dist/checks/after/managed.js +8 -24
  196. package/dist/checks/after/tools.js +3 -16
  197. package/dist/checks/before/context-fetch.js +1 -21
  198. package/dist/checks/before/index.js +6 -42
  199. package/dist/checks/before/mcp.js +14 -9
  200. package/dist/checks/before/repo.js +8 -11
  201. package/dist/checks/status-holes.js +5 -6
  202. package/dist/checks/tips/catalogue.js +60 -18
  203. package/dist/checks/tips/detect.js +41 -2
  204. package/dist/checks/tips/index.js +25 -5
  205. package/dist/cli.js +34 -14
  206. package/dist/commands/analysis.js +21 -5
  207. package/dist/commands/comply.js +20 -18
  208. package/dist/commands/harvest.js +12 -13
  209. package/dist/commands/install/doctor.js +55 -23
  210. package/dist/commands/install/install.js +62 -118
  211. package/dist/commands/install/uninstall.js +165 -31
  212. package/dist/commands/install/upgrade.js +55 -49
  213. package/dist/commands/lib.js +32 -10
  214. package/dist/commands/tips.js +6 -3
  215. package/dist/commands/workflow/branches.js +57 -13
  216. package/dist/commands/workflow/counters.js +17 -7
  217. package/dist/commands/workflow/fids.js +39 -0
  218. package/dist/commands/workflow/ledgers.js +3 -1
  219. package/dist/commands/workflow/prs.js +3 -3
  220. package/dist/commands/workflow/repo.js +16 -4
  221. package/dist/commands/workflow/roadmap.js +4 -4
  222. package/dist/commands/workflow/runs.js +5 -5
  223. package/dist/commands/workflow/steps.js +1 -0
  224. package/dist/commands/workflow/tests.js +16 -3
  225. package/dist/commands/workflow/workflows.js +19 -18
  226. package/dist/commands/workflow/workstreams.js +2 -1
  227. package/dist/commands/workflow/worktrees.js +4 -5
  228. package/dist/install/cloud-env.js +10 -23
  229. package/dist/install/manifest.js +14 -7
  230. package/dist/install/modules/antigravity.js +15 -26
  231. package/dist/install/modules/claude.js +17 -21
  232. package/dist/install/modules/cloud.js +6 -2
  233. package/dist/install/modules/codex.js +15 -29
  234. package/dist/install/modules/core.js +82 -63
  235. package/dist/install/modules/cursor.js +6 -9
  236. package/dist/install/modules/index.js +6 -1
  237. package/dist/install/modules/opencode.js +41 -72
  238. package/dist/install/network-allowlist.js +62 -0
  239. package/dist/install/placeholders.js +3 -16
  240. package/dist/install/write.js +55 -15
  241. package/dist/ledgers/telemetry.js +5 -4
  242. package/dist/render/hosts.js +30 -55
  243. package/dist/render/models.js +20 -9
  244. package/dist/shared/bkit-latest.js +150 -0
  245. package/dist/shared/branches.js +11 -0
  246. package/dist/shared/egress.js +0 -2
  247. package/dist/shared/json.js +14 -0
  248. package/dist/shared/package-json.js +61 -0
  249. package/dist/shared/package-roots.js +0 -8
  250. package/dist/shared/protected-paths.js +5 -122
  251. package/dist/shared/settings.js +18 -1
  252. package/dist/shared/timeouts.js +6 -0
  253. package/package.json +21 -17
  254. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -22,7 +22,7 @@
22
22
  import * as fs from "node:fs";
23
23
  import * as path from "node:path";
24
24
  import * as readline from "node:readline";
25
- import type { JsonValue, WriteSet } from "../../install/write.js";
25
+ import { isJsonObject, type JsonValue, type WriteSet } from "../../install/write.js";
26
26
  import { stripManagedBlock, detectMarkerStyle } from "../../install/managed-block.js";
27
27
  import { readTemplate } from "../../render/parts.js";
28
28
  import {
@@ -33,20 +33,34 @@ import {
33
33
  ISSUE_TRACKERS,
34
34
  } from "../../install/manifest.js";
35
35
  import { OPENCODE_PROVIDERS } from "../../shared/egress.js";
36
+ import { parseJson } from "../../shared/json.js";
36
37
  import {
38
+ hashFile,
37
39
  isConsumerModified,
38
40
  mergeCanonicalHashes,
39
41
  readBkitVersion,
40
42
  writeBkitVersion,
41
43
  } from "../../install/version-file.js";
42
44
  import {
45
+ getBkitDocsRoot,
43
46
  getPkgRoot,
44
47
  getSharedRoot,
45
48
  findTemplateSource,
46
49
  TEMPLATE_COPIES_DIR,
47
50
  } from "../../shared/package-roots.js";
48
51
  import { PAYLOAD_LINKS } from "../../install/payload-links.js";
49
- import { removeOpencodeProviderBlock, renderOpencodeJson } from "../../install/modules/opencode.js";
52
+ import {
53
+ removeOpencodeProviderBlock,
54
+ renderOpencodeAgentsCommands,
55
+ renderOpencodeJson,
56
+ } from "../../install/modules/opencode.js";
57
+ import {
58
+ applyModelOverrides,
59
+ buildOpencodeModelLookup,
60
+ parseEffortMap,
61
+ } from "../../render/models.js";
62
+ import { readInstallingVersion } from "../../shared/package-json.js";
63
+ import { readBkitConfig } from "../../shared/settings.js";
50
64
  import {
51
65
  CLAUDE_CLOUD_RELPATH,
52
66
  CURSOR_CLOUD_RELPATH,
@@ -54,6 +68,7 @@ import {
54
68
  } from "../../install/cloud-env.js";
55
69
  import type { ModuleFlag, UninstallFlags } from "../../cli.js";
56
70
  import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
71
+ import { type McpServerMapKey, unusedTrackerMcpServers } from "../../checks/before/mcp.js";
57
72
 
58
73
  // ---------------------------------------------------------------------------
59
74
  // Types
@@ -136,15 +151,8 @@ export function stripOpencodeJsonScope(
136
151
  cwd: string,
137
152
  ): Record<string, JsonValue> {
138
153
  const render = (tracker: IssueTracker, provider: string): Record<string, JsonValue> =>
139
- JSON.parse(renderOpencodeJson(templatePath, tracker, provider, cwd)) as Record<
140
- string,
141
- JsonValue
142
- >;
143
- const ownedMcp: Record<string, JsonValue> = {};
144
- for (const tracker of ISSUE_TRACKERS) {
145
- const { mcp } = render(tracker, OPENCODE_PROVIDERS[0]);
146
- if (isJsonObject(mcp)) Object.assign(ownedMcp, mcp);
147
- }
154
+ renderOpencodeDoc(templatePath, tracker, provider, cwd);
155
+ const ownedMcp = ownedOpencodeMcpEntries(templatePath, cwd);
148
156
  const ownedProviders: Record<string, JsonValue> = {};
149
157
  for (const provider of OPENCODE_PROVIDERS) {
150
158
  const rendered = render("none", provider).provider;
@@ -160,6 +168,28 @@ export function stripOpencodeJsonScope(
160
168
  return stripTier2JsonScope(out, rest);
161
169
  }
162
170
 
171
+ function renderOpencodeDoc(
172
+ templatePath: string,
173
+ tracker: IssueTracker,
174
+ provider: string,
175
+ cwd: string,
176
+ ): Record<string, JsonValue> {
177
+ return JSON.parse(renderOpencodeJson(templatePath, tracker, provider, cwd)) as Record<
178
+ string,
179
+ JsonValue
180
+ >;
181
+ }
182
+
183
+ /** Every tracker's `mcp` entry exactly as bkit renders it into `.opencode/opencode.json`. */
184
+ function ownedOpencodeMcpEntries(templatePath: string, cwd: string): Record<string, JsonValue> {
185
+ const owned: Record<string, JsonValue> = {};
186
+ for (const tracker of ISSUE_TRACKERS) {
187
+ const { mcp } = renderOpencodeDoc(templatePath, tracker, OPENCODE_PROVIDERS[0], cwd);
188
+ if (isJsonObject(mcp)) Object.assign(owned, mcp);
189
+ }
190
+ return owned;
191
+ }
192
+
163
193
  export function stripTier2JsonScope(
164
194
  consumerDoc: Record<string, JsonValue>,
165
195
  templateDoc: Record<string, JsonValue>,
@@ -237,23 +267,96 @@ export function stripMcpTrackerEntries(
237
267
 
238
268
  /**
239
269
  * Delete each entry of `doc[key]` identical to the same-named entry in `owned`, then drop
240
- * `doc[key]` once empty. Entries that differ, and names `owned` lacks, stay. Mutates `doc`.
270
+ * `doc[key]` once empty (unless `dropEmpty` is false). Entries that differ, and names `owned`
271
+ * lacks, stay. Mutates `doc`; returns the names deleted.
241
272
  */
242
273
  function removeOwnedEntries(
243
274
  doc: Record<string, JsonValue>,
244
275
  key: string,
245
276
  owned: Record<string, JsonValue>,
246
- ): void {
277
+ dropEmpty = true,
278
+ ): string[] {
247
279
  const entries = doc[key];
248
- if (!isJsonObject(entries)) return;
280
+ if (!isJsonObject(entries)) return [];
281
+ const removed: string[] = [];
249
282
  for (const [name, entry] of Object.entries(owned)) {
250
- if (JSON.stringify(entries[name]) === JSON.stringify(entry)) delete entries[name];
283
+ if (name in entries && JSON.stringify(entries[name]) === JSON.stringify(entry)) {
284
+ delete entries[name];
285
+ removed.push(name);
286
+ }
251
287
  }
252
- if (Object.keys(entries).length === 0) delete doc[key];
288
+ if (dropEmpty && Object.keys(entries).length === 0) delete doc[key];
289
+ return removed;
253
290
  }
254
291
 
255
- function isJsonObject(v: JsonValue | undefined): v is Record<string, JsonValue> {
256
- return v !== null && typeof v === "object" && !Array.isArray(v);
292
+ /** The files bkit writes a tracker MCP entry into, and the key of each one's server map. */
293
+ const TRACKER_MCP_FILES: ReadonlyArray<{ relPath: string; mapKey: McpServerMapKey }> = [
294
+ { relPath: ".mcp.json", mapKey: "mcpServers" },
295
+ { relPath: path.join(".cursor", "mcp.json"), mapKey: "mcpServers" },
296
+ { relPath: path.join(".opencode", "opencode.json"), mapKey: "mcp" },
297
+ ];
298
+
299
+ /**
300
+ * Tracker switch: remove each `unusedTrackerMcpServers(tracker)` entry from `.mcp.json`,
301
+ * `.cursor/mcp.json` and `.opencode/opencode.json` while it still equals bkit's template entry
302
+ * — the rule uninstall applies (`removeOwnedEntries`). An entry the consumer edited stays and
303
+ * is named in a warning. `.mcp.json` / `.cursor/mcp.json` keep an emptied `mcpServers` (the
304
+ * tracker-`none` render); `.opencode/opencode.json` drops an emptied `mcp`, as its render does.
305
+ * Absent and malformed files are skipped (the host module reports malformed JSON). Pushes each
306
+ * rewritten file onto `ws` and returns its path.
307
+ */
308
+ export function removeUnusedTrackerMcpEntries(
309
+ cwd: string,
310
+ tracker: IssueTracker,
311
+ dryRun: boolean,
312
+ ws: WriteSet,
313
+ logPrefix: string,
314
+ ): string[] {
315
+ const unused = unusedTrackerMcpServers(tracker);
316
+ const written: string[] = [];
317
+ for (const { relPath, mapKey } of TRACKER_MCP_FILES) {
318
+ const absPath = path.join(cwd, relPath);
319
+ const templatePath = findTemplateSource(relPath);
320
+ if (unused.length === 0 || templatePath === null || !fs.existsSync(absPath)) continue;
321
+ const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
322
+ const doc = parsed.ok ? (parsed.value as JsonValue) : null;
323
+ if (!isJsonObject(doc)) continue;
324
+ const servers = doc[mapKey];
325
+ if (!isJsonObject(servers)) continue;
326
+
327
+ let templateEntries: JsonValue | undefined;
328
+ if (mapKey === "mcp") {
329
+ templateEntries = ownedOpencodeMcpEntries(templatePath, cwd);
330
+ } else {
331
+ const template = parseJson(fs.readFileSync(templatePath, "utf-8"));
332
+ const templateDoc = template.ok ? (template.value as JsonValue) : null;
333
+ templateEntries = isJsonObject(templateDoc) ? templateDoc[mapKey] : undefined;
334
+ }
335
+ if (!isJsonObject(templateEntries)) continue;
336
+ const owned: Record<string, JsonValue> = {};
337
+ for (const name of unused) {
338
+ if (name in servers && name in templateEntries) owned[name] = templateEntries[name];
339
+ }
340
+
341
+ const removed = removeOwnedEntries(doc, mapKey, owned, mapKey === "mcp");
342
+ for (const name of Object.keys(owned).filter((n) => !removed.includes(n))) {
343
+ console.warn(
344
+ `${logPrefix} kept ${relPath} ${mapKey}.${name}: edited since bkit wrote it, and the ` +
345
+ `${tracker} tracker does not use it — remove it by hand if unneeded.`,
346
+ );
347
+ }
348
+ if (removed.length === 0) continue;
349
+ if (!dryRun) fs.writeFileSync(absPath, JSON.stringify(doc, null, 2) + "\n", "utf-8");
350
+ ws.writes.push({ path: absPath, action: "update" });
351
+ written.push(absPath);
352
+ for (const name of removed) {
353
+ console.log(
354
+ `${logPrefix} ${dryRun ? "[dry-run] " : ""}removed ${relPath} ${mapKey}.${name} ` +
355
+ `(the ${tracker} tracker does not use it)`,
356
+ );
357
+ }
358
+ }
359
+ return written;
257
360
  }
258
361
 
259
362
  // ---------------------------------------------------------------------------
@@ -273,8 +376,9 @@ const CORE_TEMPLATE_DOCTRINE: ManifestEntry[] = [
273
376
  { path: ".agents/context.md", format: "markered-text", module: "core" },
274
377
  { path: ".agents/docs.md", format: "markered-text", module: "core" },
275
378
  { path: ".agents/rules.md", format: "markered-text", module: "core" },
276
- { path: ".agents/shortcuts.md", format: "markered-text", module: "core" },
277
379
  { path: ".agents/skills.md", format: "markered-text", module: "core" },
380
+ // Retired path of `.bkit/lite.md` (5.1.0 – 5.2.4), for an install never upgraded since.
381
+ { path: ".agents/shortcuts.md", format: "markered-text", module: "core" },
278
382
  ];
279
383
 
280
384
  /**
@@ -604,12 +708,16 @@ export async function runUninstall(
604
708
  break;
605
709
  }
606
710
  const raw = fs.readFileSync(absPath, "utf-8");
607
- const consumerDoc = JSON.parse(raw) as Record<string, JsonValue>;
711
+ const consumerParsed = parseJson(raw);
712
+ if (!consumerParsed.ok) throw new Error(`${summary.file} is not valid JSON`);
713
+ const consumerDoc = consumerParsed.value as Record<string, JsonValue>;
608
714
  const templateRaw = fs.readFileSync(templatePath, "utf-8");
609
715
  // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS; stripOpencodeJsonScope
610
716
  // renders them for every tracker and provider bkit can have written.
611
717
  const isOpencodeJson = templateRaw.includes("@@OPENCODE_TRACKER_MCP@@");
612
- const templateDoc = JSON.parse(templateRaw) as Record<string, JsonValue>;
718
+ const templateParsed = parseJson(templateRaw);
719
+ if (!templateParsed.ok) throw new Error(`${templatePath} is not valid JSON`);
720
+ const templateDoc = templateParsed.value as Record<string, JsonValue>;
613
721
  // `.claude/settings.json` is not written verbatim: after rendering the
614
722
  // template, install appends one `WebFetch(domain:<d>)` grant per entry in
615
723
  // the resolved network allowlist and `mcp__…` grants per declared MCP
@@ -959,13 +1067,8 @@ export async function runSurgicalOpencodeUninstall(
959
1067
 
960
1068
  if (fs.existsSync(pkgPath)) {
961
1069
  const raw = fs.readFileSync(pkgPath, "utf-8");
962
- // Parse-or-sentinel idiom: keep the early-return outside the catch body.
963
- let pkg: Record<string, unknown> | null = null;
964
- try {
965
- pkg = JSON.parse(raw) as Record<string, unknown>;
966
- } catch {
967
- pkg = null;
968
- }
1070
+ const parsed = parseJson(raw);
1071
+ const pkg = parsed.ok ? (parsed.value as Record<string, unknown> | null) : null;
969
1072
  if (pkg === null) {
970
1073
  console.warn(`${LOG_PREFIX} package.json is malformed — skipping bkit section update`);
971
1074
  return;
@@ -1016,13 +1119,68 @@ export async function runSurgicalOpencodeUninstall(
1016
1119
  return;
1017
1120
  }
1018
1121
 
1019
- // 4. If was active → emit advisory (re-rendering agents requires full ModuleContext)
1122
+ // 4. If was active → re-render the agent pins for the new active provider, so `bkit check`
1123
+ // finds the mirrors in sync right after.
1020
1124
  if (wasActive && newActive !== null) {
1021
- console.log(
1022
- `${LOG_PREFIX}${tag} active provider switched to "${newActive}". ` +
1023
- `Run \`bkit install --opencode=${newActive}\` or \`bkit upgrade\` to re-render agent frontmatter.`,
1024
- );
1125
+ if (dryRun) {
1126
+ console.log(
1127
+ `${LOG_PREFIX}${tag} active provider would switch to "${newActive}" — .opencode/agents/ ` +
1128
+ `would be re-rendered to its model pins.`,
1129
+ );
1130
+ return;
1131
+ }
1132
+ const previousCwd = process.cwd();
1133
+ process.chdir(cwd);
1134
+ try {
1135
+ const written = rerenderOpencodeMirrors(newActive, LOG_PREFIX);
1136
+ console.log(
1137
+ `${LOG_PREFIX} active provider switched to "${newActive}" — re-rendered ` +
1138
+ `${written.length} .opencode/ agent/command file(s) to its model pins.`,
1139
+ );
1140
+ } finally {
1141
+ process.chdir(previousCwd);
1142
+ }
1143
+ }
1144
+ }
1145
+
1146
+ /**
1147
+ * Re-render `.opencode/agents/` + `.opencode/commands/` for `provider` — the per-agent model
1148
+ * pins `bkit check` expects once `provider` is the active one, consumer `.bkit/prompts.md`
1149
+ * § Model Overrides applied — and refresh their `.bkit/version` hashes. Renders into
1150
+ * process.cwd(), as the host renderers resolve consumer paths from it. Returns the paths written.
1151
+ */
1152
+ function rerenderOpencodeMirrors(provider: string, logPrefix: string): string[] {
1153
+ const cwd = process.cwd();
1154
+ const promptsMd = path.join(getBkitDocsRoot(), "prompts.md");
1155
+ const opencodeModelLookup = buildOpencodeModelLookup(promptsMd, provider);
1156
+ applyModelOverrides(opencodeModelLookup, provider, path.join(cwd, ".bkit", "prompts.md"));
1157
+ const written = renderOpencodeAgentsCommands({
1158
+ dryRun: false,
1159
+ tokens: { DEFAULT_BRANCH: "", PROJECT_NAME: "", REPO_SLUG: "" },
1160
+ modelLookup: new Map(),
1161
+ opencodeModelLookup,
1162
+ effortMap: parseEffortMap(promptsMd),
1163
+ opencodeProvider: provider,
1164
+ advisories: [],
1165
+ ws: { writes: [] },
1166
+ logPrefix,
1167
+ postDispatch: [],
1168
+ issueTracker: readBkitConfig(cwd).issueTracker,
1169
+ version: readInstallingVersion(),
1170
+ });
1171
+
1172
+ const versionFile = path.join(cwd, ".bkit", "version");
1173
+ const existing = readBkitVersion(versionFile);
1174
+ if (existing && written.length > 0) {
1175
+ const fresh: Record<string, string> = {};
1176
+ for (const rel of written) {
1177
+ const hash = hashFile(path.join(cwd, rel));
1178
+ if (hash) fresh[rel] = hash;
1179
+ }
1180
+ const { canonicalHashes } = mergeCanonicalHashes(cwd, existing.canonicalHashes, fresh);
1181
+ writeBkitVersion(versionFile, { ...existing, canonicalHashes });
1025
1182
  }
1183
+ return written;
1026
1184
  }
1027
1185
 
1028
1186
  export async function runUninstallCommand(
@@ -39,25 +39,25 @@ import {
39
39
  getCoreRoot,
40
40
  getSharedRoot,
41
41
  getBkitDocsRoot,
42
- getPkgRoot,
43
42
  } from "../../shared/package-roots.js";
44
- import type { ModuleFlag, UpgradeFlags } from "../../cli.js";
43
+ import { readDependencySpec, readInstallingVersion } from "../../shared/package-json.js";
44
+ import type { UpgradeFlags } from "../../cli.js";
45
45
  import {
46
- getInstallingVersion,
47
46
  requireOpencodeProvider,
48
47
  detectOpencodeProviders,
49
48
  runUpgradeAdvisories,
50
49
  } from "./install.js";
51
50
  import { setLogPrefix } from "../../shared/log-prefix.js";
51
+ import { BKIT_PACKAGE, lookupLatestPublished } from "../../shared/bkit-latest.js";
52
+ import { PACKAGE_RUNNER } from "../../shared/package-manager.js";
52
53
  import {
53
54
  getInstallManifest,
54
55
  getModuleManifest,
55
56
  type ModuleName,
56
57
  type IssueTracker,
57
- DEFAULT_ISSUE_TRACKER,
58
- parseIssueTracker,
59
58
  } from "../../install/manifest.js";
60
59
  import { OPTIN_MODULES } from "../../install/manifest.js";
60
+ import { readBkitConfig } from "../../shared/settings.js";
61
61
  import { detectInstalledHostModules } from "../../install/hosts.js";
62
62
  import { detectInstalledModules } from "./check.js";
63
63
  import { remapTemplateDest } from "../../install/template-copies.js";
@@ -66,7 +66,6 @@ import {
66
66
  CURSOR_CLOUD_RELPATH,
67
67
  writeClaudeCloudDoc,
68
68
  writeCursorCloudDoc,
69
- writeNetworkAllowlistArtifact,
70
69
  writeCursorCliPermissionsArtifact,
71
70
  } from "../../install/cloud-env.js";
72
71
  import { syncTemplateCopies, formatTemplateChanges } from "../../install/template-copies.js";
@@ -107,18 +106,36 @@ export type SelfBumpPlan =
107
106
  | { kind: "invalid"; message: string }
108
107
  /** Already at the target → caller falls through to a normal in-place re-render. */
109
108
  | { kind: "noop"; target: string }
110
- /** Install `target`, then re-exec the new binary to re-render + re-pin. */
111
- | { kind: "bump"; target: string };
109
+ /**
110
+ * Install `target`, then re-exec the new binary to re-render + re-pin. `fromSpec` names the
111
+ * non-registry spec being replaced when the installed version already equals `target`.
112
+ */
113
+ | { kind: "bump"; target: string; fromSpec?: string };
114
+
115
+ /**
116
+ * True when a `package.json` dependency spec resolves from the registry: a version, range or
117
+ * dist-tag. `file:` / `link:` / `workspace:` / `npm:` alias / git / URL / path specs are not.
118
+ */
119
+ export function isRegistrySpec(spec: string): boolean {
120
+ const s = spec.trim();
121
+ return !/[:/\\]/.test(s) && !s.startsWith(".");
122
+ }
112
123
 
113
124
  /**
114
125
  * Resolve the self-bump target and decide the action. `resolveLatest` is only
115
126
  * invoked for `--latest` (it shells out to the registry in production); injected
116
127
  * so tests stay offline. A leading `v` is tolerated on either source.
128
+ *
129
+ * `installedSpec` is the consumer `package.json` spec for @cbartens/bkit (`null` when
130
+ * undeclared). A matching version string is a no-op only when that spec resolves from the
131
+ * registry: a `file:` tarball or other non-registry install at the same version still bumps,
132
+ * so `pnpm add` replaces it with the published package.
117
133
  */
118
134
  export function planSelfBump(
119
135
  installed: string,
120
136
  flags: { toVersion: string | null; latest: boolean },
121
137
  resolveLatest: () => string,
138
+ installedSpec: string | null = null,
122
139
  ): SelfBumpPlan {
123
140
  let target: string;
124
141
  if (flags.toVersion !== null) {
@@ -140,8 +157,9 @@ export function planSelfBump(
140
157
  };
141
158
  }
142
159
  }
143
- if (target === installed.trim().replace(/^v/, "")) return { kind: "noop", target };
144
- return { kind: "bump", target };
160
+ if (target !== installed.trim().replace(/^v/, "")) return { kind: "bump", target };
161
+ if (installedSpec === null || isRegistrySpec(installedSpec)) return { kind: "noop", target };
162
+ return { kind: "bump", target, fromSpec: installedSpec };
145
163
  }
146
164
 
147
165
  export const LOG_PREFIX = "[bkit-upgrade]";
@@ -481,7 +499,7 @@ export function updateCanonicalHashesAfterUpgrade(
481
499
 
482
500
  const fresh: Record<string, string> = {};
483
501
  for (const relPath of seedablePaths) {
484
- // Exclude .agents/ internal files (docs.md, friction.md, rules.md, shortcuts.md,
502
+ // Exclude .agents/ internal files (docs.md, rules.md,
485
503
  // skills.md, .env.example etc.) from canonicalHashes — they are not consumer-facing files
486
504
  // whose hashes bkit uses for drift detection. Mirrors the same filter applied
487
505
  // in the install path (install/modules/index.ts postDispatch). Template copies carry no
@@ -536,18 +554,17 @@ export function updateCanonicalHashesAfterUpgrade(
536
554
  * registry auth). Hard-exits with guidance on failure — the caller has nothing
537
555
  * to fall back to.
538
556
  */
539
- async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
540
- const { spawnSync } = await import("node:child_process");
541
- const r = spawnSync("pnpm", ["view", "@cbartens/bkit", "version"], { cwd, encoding: "utf-8" });
542
- if (r.status !== 0 || !r.stdout || !r.stdout.trim()) {
557
+ function resolveLatestPublishedVersion(cwd: string): string {
558
+ const latest = lookupLatestPublished(cwd, null);
559
+ if (latest === null) {
543
560
  console.error(
544
- `${LOG_PREFIX} could not resolve the latest @cbartens/bkit version from the registry ` +
545
- `(pnpm view exit ${r.status ?? "null"}). Check your network / registry access, ` +
561
+ `${LOG_PREFIX} could not resolve the latest ${BKIT_PACKAGE} version from the registry ` +
562
+ `(pnpm view failed). Check your network / registry access, ` +
546
563
  `or pin a version with --to=<version>.`,
547
564
  );
548
565
  process.exit(1);
549
566
  }
550
- return r.stdout.trim();
567
+ return latest;
551
568
  }
552
569
 
553
570
  /**
@@ -561,14 +578,14 @@ async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
561
578
  * caller falls through to a normal in-place re-render.
562
579
  */
563
580
  export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boolean> {
564
- const installed = getInstallingVersion();
565
- // --latest needs async registry resolution, but planSelfBump's injected resolver
566
- // is sync; resolve the latest first (only when asked), then feed it a constant.
567
- const latestVersion = flags.latest ? await resolveLatestPublishedVersion(cwd) : "";
581
+ const installed = readInstallingVersion();
582
+ // Resolve the latest first (only when asked), then feed planSelfBump a constant.
583
+ const latestVersion = flags.latest ? resolveLatestPublishedVersion(cwd) : "";
568
584
  const resolvedPlan = planSelfBump(
569
585
  installed,
570
586
  { toVersion: flags.toVersion, latest: flags.latest },
571
587
  () => latestVersion,
588
+ readDependencySpec(cwd, BKIT_PACKAGE),
572
589
  );
573
590
 
574
591
  if (resolvedPlan.kind === "invalid") {
@@ -597,10 +614,11 @@ export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boo
597
614
  ...(inWorkspaceRoot ? ["-w"] : []),
598
615
  `@cbartens/bkit@${resolvedPlan.target}`,
599
616
  ];
600
- const addCmd = `pnpm ${addArgs.join(" ")}`;
617
+ const addCmd = [PACKAGE_RUNNER, ...addArgs].join(" ");
618
+ const from = resolvedPlan.fromSpec ? `${installed} (${resolvedPlan.fromSpec})` : installed;
601
619
  if (flags.dryRun) {
602
620
  console.log(
603
- `${LOG_PREFIX} [dry-run] would bump @cbartens/bkit ${installed} -> ${resolvedPlan.target} ` +
621
+ `${LOG_PREFIX} [dry-run] would bump @cbartens/bkit ${from} -> ${resolvedPlan.target} ` +
604
622
  `(${addCmd}), then re-render + re-pin via the ` +
605
623
  `freshly-installed binary. No changes made.`,
606
624
  );
@@ -608,8 +626,8 @@ export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boo
608
626
  }
609
627
 
610
628
  const { spawnSync } = await import("node:child_process");
611
- console.log(`${LOG_PREFIX} bumping @cbartens/bkit ${installed} -> ${resolvedPlan.target} ...`);
612
- const add = spawnSync("pnpm", addArgs, {
629
+ console.log(`${LOG_PREFIX} bumping @cbartens/bkit ${from} -> ${resolvedPlan.target} ...`);
630
+ const add = spawnSync(PACKAGE_RUNNER, addArgs, {
613
631
  cwd,
614
632
  stdio: "inherit",
615
633
  });
@@ -625,7 +643,7 @@ export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boo
625
643
  console.log(`${LOG_PREFIX} re-rendering with @cbartens/bkit@${resolvedPlan.target} ...`);
626
644
  const reArgs = ["exec", "bkit", "upgrade"];
627
645
  if (flags.nonInteractive) reArgs.push("--auto-apply");
628
- const re = spawnSync("pnpm", reArgs, { cwd, stdio: "inherit" });
646
+ const re = spawnSync(PACKAGE_RUNNER, reArgs, { cwd, stdio: "inherit" });
629
647
  process.exit(re.status ?? 1);
630
648
  }
631
649
 
@@ -642,6 +660,9 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
642
660
  if (handled) return;
643
661
  }
644
662
 
663
+ // Read before any write: a damaged bkit package stops the run with nothing changed.
664
+ const installingVersion = readInstallingVersion();
665
+
645
666
  console.log(
646
667
  `${LOG_PREFIX} Running upgrade${upgradeFlags.dryRun ? " (dry-run)" : ""}${upgradeFlags.nonInteractive ? " (non-interactive)" : ""}`,
647
668
  );
@@ -687,16 +708,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
687
708
 
688
709
  // Resolve the consumer's tracker so upgrade renders tracker-conditional files
689
710
  // (opencode.json, the mcp.json files) the same way install does.
690
- let upgradeTracker: IssueTracker = DEFAULT_ISSUE_TRACKER;
691
- try {
692
- const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf-8")) as {
693
- bkit?: { issueTracker?: unknown };
694
- };
695
- const stored = parseIssueTracker(pkg.bkit?.issueTracker);
696
- if (stored !== null) upgradeTracker = stored;
697
- } catch {
698
- // package.json absent/unparseable — default tracker
699
- }
711
+ const upgradeTracker: IssueTracker = readBkitConfig(process.cwd()).issueTracker;
700
712
 
701
713
  // opencode.json is provider/tracker-templated on install (renderOpencodeJson resolves the
702
714
  // `@@OPENCODE_*@@` sentinels). Upgrade renders it the same way, with the installed
@@ -902,7 +914,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
902
914
  cloudVariant: null,
903
915
  // Re-stamp every rendered agent + command at the version we are upgrading TO,
904
916
  // so a clean upgrade refreshes the managed-version marker and `bkit check` stays green.
905
- version: getInstallingVersion(),
917
+ version: installingVersion,
906
918
  // The detected host set — read by the Antigravity module for the Codex-overlap advisory.
907
919
  installedModules: renderModules,
908
920
  };
@@ -961,22 +973,17 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
961
973
  }
962
974
 
963
975
  // Network allowlist + MCP allows — OpenCode from renderOpencodeJson; Claude enrich
964
- // below; Cursor `.cursor/allowlist.json` + `.cursor/cli.json` only when cursor
965
- // module installed. Written artifacts get their canonicalHashes refreshed below.
976
+ // below; `.bkit/allowlist.json` in renderManagedOutputs above; Cursor
977
+ // `.cursor/cli.json` only when cursor module installed. Written artifacts get their
978
+ // canonicalHashes refreshed below.
966
979
  const artifactWrites: string[] = [];
967
980
  {
968
981
  const cwd = process.cwd();
969
982
  if (renderModules.has("cursor")) {
970
- for (const art of [
971
- writeNetworkAllowlistArtifact(cwd, upgradeFlags.dryRun),
972
- writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun),
973
- ]) {
974
- if (art.wrote) {
975
- artifactWrites.push(art.path);
976
- console.log(
977
- `${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`,
978
- );
979
- }
983
+ const art = writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun);
984
+ if (art.wrote) {
985
+ artifactWrites.push(art.path);
986
+ console.log(`${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`);
980
987
  }
981
988
  }
982
989
  if (renderModules.has("claude") && fs.existsSync(path.join(cwd, ".claude", "settings.json"))) {
@@ -1003,8 +1010,6 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
1003
1010
  // exit), so feed those writes into canonicalHashes — keeping install/upgrade `.bkit/version`
1004
1011
  // parity.
1005
1012
  if (!upgradeFlags.dryRun) {
1006
- const pkgVersion = JSON.parse(fs.readFileSync(path.join(getPkgRoot(), "package.json"), "utf-8"))
1007
- .version as string;
1008
1013
  const renderedDocPaths = renderWs.writes.map((w) =>
1009
1014
  path.relative(
1010
1015
  process.cwd(),
@@ -1026,7 +1031,7 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
1026
1031
  {
1027
1032
  dryRun: false,
1028
1033
  cwd: process.cwd(),
1029
- pinnedVersion: pkgVersion,
1034
+ pinnedVersion: installingVersion,
1030
1035
  claudeAllowDerived: upgradeClaudeAllowDerived,
1031
1036
  },
1032
1037
  );
@@ -3,9 +3,9 @@
3
3
  // Flag parsing, one JSON object on stdout, `[bkit-<noun>]`-tagged logs on stderr,
4
4
  // the exit-code table, `--help` rendering, and the repo facts several workflow
5
5
  // steps each re-derived by hand: repo root, UTC month, where `status.jsonl` lives,
6
- // and the skip-CI tokens. A command declares its flags, output keys and exit codes
7
- // in its spec; `--help` and the convention test both read that spec, so the help
8
- // text cannot drift from what the command accepts.
6
+ // the skip-CI tokens, and which branches are shared. A command declares its flags,
7
+ // output keys and exit codes in its spec; `--help` and the convention test both read
8
+ // that spec, so the help text cannot drift from what the command accepts.
9
9
 
10
10
  import { spawnSync } from "node:child_process";
11
11
  import * as fs from "node:fs";
@@ -331,16 +331,34 @@ export async function runCommand(
331
331
  // Repo facts
332
332
  // ---------------------------------------------------------------------------
333
333
 
334
+ /** Captured stdout / stderr cap for `runGit` / `runTool`; hook output (pre-push) counts. */
335
+ const OUTPUT_LIMIT = 1 << 26;
336
+
337
+ /** Spawn error as a stderr lead line: ENOBUFS names the limit, anything else Node's message. */
338
+ function spawnErrorText(cmd: string, args: string[], err: NodeJS.ErrnoException): string {
339
+ return err.code === "ENOBUFS"
340
+ ? `${cmd} ${args[0] ?? ""}: output passed the ${OUTPUT_LIMIT / (1 << 20)} MiB limit (ENOBUFS)`
341
+ : err.message;
342
+ }
343
+
334
344
  /** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr. */
335
345
  export function runGit(
336
346
  cwd: string,
337
347
  args: string[],
338
348
  ): { ok: boolean; stdout: string; stderr: string } {
339
- const res = spawnSync("git", args, { cwd, encoding: "utf-8", env: gitEnv() });
349
+ const res = spawnSync("git", args, {
350
+ cwd,
351
+ encoding: "utf-8",
352
+ env: gitEnv(),
353
+ maxBuffer: OUTPUT_LIMIT,
354
+ });
355
+ const stderr = (res.stderr ?? "").trim();
340
356
  return {
341
- ok: res.status === 0,
357
+ ok: !res.error && res.status === 0,
342
358
  stdout: (res.stdout ?? "").trim(),
343
- stderr: (res.stderr ?? "").trim(),
359
+ stderr: res.error
360
+ ? [spawnErrorText("git", args, res.error), stderr].filter(Boolean).join("\n")
361
+ : stderr,
344
362
  };
345
363
  }
346
364
 
@@ -355,6 +373,9 @@ export function git(cwd: string, args: string[]): string | null {
355
373
  // for the command modules that already import it from this module.
356
374
  export { parseJson } from "../shared/json.js";
357
375
 
376
+ // The shared-branch rule (`dev`, `main`) lives in shared/ so checks can read it too.
377
+ export { DEV, isSharedBranch } from "../shared/branches.js";
378
+
358
379
  export interface ToolResult {
359
380
  /** False when the binary is not on PATH (or could not be spawned). */
360
381
  found: boolean;
@@ -379,16 +400,20 @@ export function runTool(
379
400
  encoding: "utf-8",
380
401
  env: gitEnv(),
381
402
  input: opts.input,
382
- maxBuffer: 1 << 26,
403
+ maxBuffer: OUTPUT_LIMIT,
383
404
  });
384
- if (res.error) {
405
+ if (res.error && res.pid === 0) {
385
406
  return { found: false, status: 127, stdout: "", stderr: `${cmd} not found on PATH` };
386
407
  }
408
+ const status = res.status ?? 128 + signalNumber(res.signal);
387
409
  return {
388
410
  found: true,
389
- status: res.status ?? 128 + signalNumber(res.signal),
411
+ // A spawn error is never a success: the child can exit 0 before ENOBUFS kills it.
412
+ status: res.error && status === 0 ? 1 : status,
390
413
  stdout: res.stdout ?? "",
391
- stderr: res.stderr ?? "",
414
+ stderr: res.error
415
+ ? [spawnErrorText(cmd, args, res.error), res.stderr ?? ""].filter(Boolean).join("\n")
416
+ : (res.stderr ?? ""),
392
417
  };
393
418
  }
394
419