@cbartens/bkit 5.1.0 → 5.2.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 (194) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +90 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
  136. package/.bkit/templates/.prettierignore +1 -1
  137. package/.bkit/templates/context/bkit-expo.md +22 -13
  138. package/.bkit/templates/context/bkit-github.md +20 -6
  139. package/.bkit/templates/context/bkit-inngest.md +10 -4
  140. package/.bkit/templates/context/bkit-maestro.md +5 -5
  141. package/.bkit/templates/context/bkit-playwright.md +3 -3
  142. package/.bkit/templates/context/bkit-sentry.md +6 -5
  143. package/.bkit/templates/context/bkit-stripe.md +31 -8
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  145. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  147. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  148. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  149. package/.bkit/templates/slop-scan.config.json +7 -2
  150. package/CHANGELOG.md +42 -0
  151. package/LICENSE.md +21 -161
  152. package/README.md +58 -28
  153. package/dist/checks/after/auth.js +28 -0
  154. package/dist/checks/after/github.js +4 -4
  155. package/dist/checks/after/index.js +29 -45
  156. package/dist/checks/after/managed.js +40 -1
  157. package/dist/checks/before/index.js +5 -4
  158. package/dist/checks/before/mcp.js +53 -53
  159. package/dist/checks/status-holes.js +1 -1
  160. package/dist/checks/tips/catalogue.js +297 -0
  161. package/dist/checks/tips/detect.js +130 -0
  162. package/dist/checks/tips/index.js +146 -0
  163. package/dist/cli.js +47 -9
  164. package/dist/commands/install/doctor.js +5 -1
  165. package/dist/commands/install/install.js +27 -7
  166. package/dist/commands/install/uninstall.js +31 -16
  167. package/dist/commands/install/upgrade.js +15 -32
  168. package/dist/commands/launch.js +27 -11
  169. package/dist/commands/tips.js +10 -0
  170. package/dist/commands/workflow/runs.js +52 -16
  171. package/dist/commands/workflow/runtime.js +8 -0
  172. package/dist/commands/workflow/steps.js +1 -0
  173. package/dist/commands/workflow/tests.js +541 -4
  174. package/dist/commands/workflow/workstreams.js +4 -4
  175. package/dist/install/cloud-env.js +3 -14
  176. package/dist/install/hosts.js +22 -0
  177. package/dist/install/managed-block.js +36 -0
  178. package/dist/install/manifest.js +45 -4
  179. package/dist/install/modules/antigravity.js +8 -7
  180. package/dist/install/modules/claude.js +6 -6
  181. package/dist/install/modules/cloud.js +2 -2
  182. package/dist/install/modules/codex.js +5 -5
  183. package/dist/install/modules/core.js +14 -5
  184. package/dist/install/modules/cursor.js +6 -6
  185. package/dist/install/modules/opencode.js +4 -4
  186. package/dist/install/payload-links.js +5 -5
  187. package/dist/install/placeholders.js +1 -1
  188. package/dist/install/version-file.js +12 -3
  189. package/dist/install/write.js +61 -2
  190. package/dist/shared/package-roots.js +8 -11
  191. package/package.json +4 -6
  192. package/.bkit/core/LICENSE.md +0 -149
  193. package/.bkit/shared/LICENSE.md +0 -22
  194. package/.bkit/templates/LICENSE.md +0 -22
@@ -7,12 +7,12 @@ import { dedupeById } from "../before/index.js";
7
7
  import { detectMissingDotenv, detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, } from "../before/env.js";
8
8
  import { getPkgRoot } from "../../shared/package-roots.js";
9
9
  import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
10
- import { TEMPLATES_POINTER } from "../../install/template-copies.js";
11
- import { detectManagedStale } from "./managed.js";
12
- import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectShellGhMcpToken, hasGithubMcpServer, } from "./auth.js";
10
+ import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
11
+ import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
13
12
  import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectGithubProjectFieldIdFormat, detectMainBranchProtection, readConsumerIssueTracker, } from "./github.js";
14
13
  import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
15
14
  import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
15
+ import { dropTipSilencedAdvisories, setupTipsChecklistLines, setupTipsMarkdownLines, } from "../tips/index.js";
16
16
  // ---------------------------------------------------------------------------
17
17
  // formatChecklist — pure renderer
18
18
  // ---------------------------------------------------------------------------
@@ -48,23 +48,23 @@ export function suppressedNoteLines(suppressed) {
48
48
  }
49
49
  /**
50
50
  * Format a list of findings into the post-install console checklist.
51
- * Returns `""` when findings AND suppressed are both empty — callers can `if (banner)` to
52
- * stay silent. No console.log inside — caller logs.
51
+ * Returns `""` when findings, suppressed and tips are all empty — callers can `if (banner)`
52
+ * to stay silent. No console.log inside — caller logs.
53
53
  *
54
- * Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions
55
- * and template pointer are the shared strings; only the separators differ from
56
- * the markdown form.
54
+ * Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions and
55
+ * setup tips are the shared strings; only the separators differ from the markdown form.
57
56
  *
58
57
  * Format per finding:
59
58
  * --- i/N [severity] id ---
60
59
  * Detect: ...
61
60
  * Action: ...
62
61
  *
63
- * `suppressed` is appended as its own block (see `suppressedNoteLines`) — a dismissed
64
- * advisory stays visible even when nothing else fired.
62
+ * `tips` follow the findings as the Setup tips block; `suppressed` is appended as its own
63
+ * block (see `suppressedNoteLines`) — a dismissed advisory or tip stays visible even when
64
+ * nothing else fired.
65
65
  */
66
- export function formatChecklist(findings, suppressed = []) {
67
- if (findings.length === 0 && suppressed.length === 0)
66
+ export function formatChecklist(findings, suppressed = [], tips = []) {
67
+ if (findings.length === 0 && suppressed.length === 0 && tips.length === 0)
68
68
  return "";
69
69
  const banner = "=".repeat(58);
70
70
  const total = findings.length;
@@ -79,8 +79,6 @@ export function formatChecklist(findings, suppressed = []) {
79
79
  lines.push("");
80
80
  lines.push(ADVISORIES_AGENT_INSTRUCTIONS);
81
81
  lines.push("");
82
- lines.push(TEMPLATES_POINTER);
83
- lines.push("");
84
82
  }
85
83
  for (let i = 0; i < findings.length; i++) {
86
84
  const f = findings[i];
@@ -89,6 +87,7 @@ export function formatChecklist(findings, suppressed = []) {
89
87
  lines.push(`Action: ${f.action}`);
90
88
  lines.push("");
91
89
  }
90
+ lines.push(...setupTipsChecklistLines(tips));
92
91
  const suppressedLines = suppressedNoteLines(suppressed);
93
92
  if (suppressedLines.length > 0) {
94
93
  lines.push(...suppressedLines);
@@ -101,10 +100,10 @@ export function formatChecklist(findings, suppressed = []) {
101
100
  /**
102
101
  * Render findings as a markdown artifact suitable for `.bkit/advisories.md`.
103
102
  * Renders the SAME content as `formatChecklist` (shared title, summary, agent
104
- * instructions, template pointer and suppressed block) in markdown form, so the file can
103
+ * instructions, setup tips and suppressed block) in markdown form, so the file can
105
104
  * be referenced and revisited between installs. Overwritten on every run.
106
105
  */
107
- export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
106
+ export function renderAdvisoriesMarkdown(findings, opts, suppressed = [], tips = []) {
108
107
  const lines = [];
109
108
  // This is a generated, gitignored artifact — not authored prose. Advisory
110
109
  // strings (and reproduced config snippets like `.vale.ini`'s `write-good.So =
@@ -120,7 +119,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
120
119
  lines.push("");
121
120
  lines.push("> Auto-generated by `bkit install` / `bkit check` / `bkit doctor`. Overwritten on each run.");
122
121
  lines.push("");
123
- if (findings.length === 0 && suppressed.length === 0) {
122
+ if (findings.length === 0 && suppressed.length === 0 && tips.length === 0) {
124
123
  lines.push("**No advisories.** Last run was clean.");
125
124
  lines.push("");
126
125
  return lines.join("\n");
@@ -130,8 +129,6 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
130
129
  lines.push("");
131
130
  lines.push(`> ${ADVISORIES_AGENT_INSTRUCTIONS}`);
132
131
  lines.push("");
133
- lines.push(`> ${TEMPLATES_POINTER}`);
134
- lines.push("");
135
132
  }
136
133
  const total = findings.length;
137
134
  for (let i = 0; i < total; i++) {
@@ -143,6 +140,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
143
140
  lines.push(`**Action:** ${f.action}`);
144
141
  lines.push("");
145
142
  }
143
+ lines.push(...setupTipsMarkdownLines(tips));
146
144
  const suppressedLines = suppressedNoteLines(suppressed);
147
145
  if (suppressedLines.length > 0) {
148
146
  lines.push(...suppressedLines);
@@ -163,7 +161,7 @@ export function writeAdvisoriesArtifact(findings, opts) {
163
161
  const content = renderAdvisoriesMarkdown(findings, {
164
162
  mode: opts.mode,
165
163
  version: opts.version,
166
- }, opts.suppressed ?? []);
164
+ }, opts.suppressed ?? [], opts.tips ?? []);
167
165
  fs.writeFileSync(filePath, content);
168
166
  const n = findings.length;
169
167
  console.log(`${opts.logPrefix} Wrote .bkit/advisories.md (${n} item${n === 1 ? "" : "s"}).`);
@@ -258,29 +256,14 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
258
256
  const managedStale = detectManagedStale(cwd);
259
257
  if (managedStale)
260
258
  phase3.push(managedStale);
261
- // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server
262
- // (`Authorization: Bearer ${BKIT_GH_TOKEN}` in .mcp.json), which powers the entire
263
- // tracker + PR + Projects MCP surface. Only flags when a github MCP server is
264
- // configured, and never in CI.
265
- if (hasGithubMcpServer(cwd) && !process.env.CI) {
266
- const ghMcpTokenStatus = detectShellGhMcpToken();
267
- if (ghMcpTokenStatus === "missing") {
268
- phase3.push({
269
- id: "gh-mcp-token-unset-shell",
270
- severity: "advisory",
271
- detect: "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
272
- action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
273
- });
274
- }
275
- else if (ghMcpTokenStatus === "empty") {
276
- phase3.push({
277
- id: "gh-mcp-token-empty-shell",
278
- severity: "advisory",
279
- detect: 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
280
- action: "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
281
- });
282
- }
283
- }
259
+ // Older unmarked copy of a managed markdown block left outside its markers.
260
+ const managedDuplicate = detectManagedDuplicate(cwd);
261
+ if (managedDuplicate)
262
+ phase3.push(managedDuplicate);
263
+ // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server.
264
+ const ghMcpToken = detectGhMcpToken(cwd);
265
+ if (ghMcpToken)
266
+ phase3.push(ghMcpToken);
284
267
  // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
285
268
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
286
269
  // protection on main restricting merges to PRs from dev.
@@ -426,6 +409,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
426
409
  // appears in Phase 3, then merge Phase 3 at the front for the winning position).
427
410
  const phase3Ids = new Set(deduped.map((f) => f.id));
428
411
  const filteredPreflight = dedupedPreflight.filter((f) => !phase3Ids.has(f.id));
429
- // Final order: preflight advisories (that weren't superseded) first, then Phase 3
430
- return [...filteredPreflight, ...deduped];
412
+ // Final order: preflight advisories (that weren't superseded) first, then Phase 3.
413
+ // An advisory a setup tip reuses goes quiet with that tip (`bkit.ignoreAdvisories`).
414
+ return dropTipSilencedAdvisories([...filteredPreflight, ...deduped], cwd, onSuppressed);
431
415
  }
@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
6
6
  import { getModuleManifest } from "../../install/manifest.js";
7
7
  import { readManagedVersion } from "../../install/version-file.js";
8
8
  import { getPkgRoot } from "../../shared/package-roots.js";
9
- import { detectMarkerStyle, findLineAnchoredMarkers, selectMarkers, } from "../../install/managed-block.js";
9
+ import { detectMarkerStyle, extractManagedBlock, findLineAnchoredMarkers, findUnmarkedCopy, selectMarkers, stripManagedBlock, } from "../../install/managed-block.js";
10
10
  import { listStampedFiles } from "../../install/modules/index.js";
11
11
  // ---------------------------------------------------------------------------
12
12
  // detectManagedStale — managed-version marker gate over every stamped file
@@ -144,6 +144,45 @@ export function detectManagedStale(cwd, installingVersion = readPkgVersion(), on
144
144
  action: "Re-render every bkit-managed file at the installed version, then commit the result: run `pnpm bkit upgrade` (resyncs every host, doc and hook) or re-run `pnpm bkit install` with your host flags. To MOVE to a newer bkit, use `pnpm bkit upgrade --latest` (or `--to=<version>`) — it bumps @cbartens/bkit AND re-renders in one step; `pnpm add @cbartens/bkit` alone does NOT re-render. Never hand-edit a rendered agent/command or the content between `bkit:start` and `bkit:end`: put your own content outside the block, where install and upgrade never write.",
145
145
  };
146
146
  }
147
+ // ---------------------------------------------------------------------------
148
+ // detectManagedDuplicate — an older unmarked copy kept beside a managed markdown block
149
+ // ---------------------------------------------------------------------------
150
+ /**
151
+ * Managed markdown blocks whose file also holds an older, unmarked copy of the block outside
152
+ * the markers (findUnmarkedCopy). Install never touches content outside the markers, so that
153
+ * copy stays at the version it was left at while agents read it beside the live block.
154
+ * Advisory: the match is a heuristic. Null when no stamped file has one.
155
+ */
156
+ export function detectManagedDuplicate(cwd) {
157
+ const copies = [];
158
+ for (const { path: rel, scope } of listStampedFiles(cwd)) {
159
+ if (scope !== "block" || !rel.endsWith(".md"))
160
+ continue;
161
+ const abs = path.join(cwd, rel);
162
+ if (!fs.existsSync(abs))
163
+ continue;
164
+ const content = fs.readFileSync(abs, "utf-8");
165
+ const block = extractManagedBlock(content);
166
+ if (block === null)
167
+ continue;
168
+ const title = findUnmarkedCopy(stripManagedBlock(content), block);
169
+ if (title === null)
170
+ continue;
171
+ const lines = content.split("\n");
172
+ const start = lines.indexOf(selectMarkers("html-comment")[0]);
173
+ const end = lines.indexOf(selectMarkers("html-comment")[1]);
174
+ const line = lines.findIndex((l, i) => l === title && (i < start || i > end)) + 1;
175
+ copies.push(`${rel} (\`${title}\` at line ${line})`);
176
+ }
177
+ if (copies.length === 0)
178
+ return null;
179
+ return {
180
+ id: "bkit-managed-duplicate",
181
+ severity: "advisory",
182
+ detect: `${copies.length} bkit-managed file(s) hold an older bkit copy outside their \`bkit:start\`/\`bkit:end\` block: ${copies.join(", ")}. Install never updates text outside the markers, so agents read that stale copy beside the live block.`,
183
+ action: "In each file, delete the old copy: the run of lines starting at the named title line, up to `<!-- bkit:start -->` (or from just after `<!-- bkit:end -->` when the copy sits below). Keep any lines you wrote yourself by moving them below `<!-- bkit:end -->`. Then run `pnpm bkit check` again.",
184
+ };
185
+ }
147
186
  /** Host modules whose manifest hook files a host config runs, and the flag that installs each. */
148
187
  const HOOK_HOST_FLAGS = [
149
188
  ["claude", "--claude"],
@@ -143,15 +143,16 @@ export function runPreflight(modules, cwd = process.cwd(), installingVersion, is
143
143
  const bkitNotOnPath = detectBkitNotOnPath();
144
144
  if (bkitNotOnPath)
145
145
  advisories.push(bkitNotOnPath);
146
- // Missing MCP server advisory — one finding per missing required key, per file.
147
- // Tracker-aware: when issueTracker === "github", only github MCP server is required
148
- // (the Linear gate is a no-op on the GitHub tracker; the gate runs in workflow Step 1 via MCP).
149
- // Extra MCP server advisory — one finding per bkit-managed server that the
146
+ // Missing MCP server advisory — one finding per missing required key, per file: the
147
+ // resolved tracker's own server (none → nothing required), matching what install writes.
148
+ // Extra MCP server advisory — one finding per bkit-written tracker-only server that the
150
149
  // resolved tracker does not use (e.g. a stale `linear` entry under `github`).
150
+ // opencode.json is drift-gated, so only the extra check runs there (map key `mcp`).
151
151
  for (const relPath of [".mcp.json", ".cursor/mcp.json"]) {
152
152
  advisories.push(...detectMissingMcpServers(cwd, relPath, resolvedTracker));
153
153
  advisories.push(...detectExtraMcpServers(cwd, relPath, resolvedTracker));
154
154
  }
155
+ advisories.push(...detectExtraMcpServers(cwd, ".opencode/opencode.json", resolvedTracker, "mcp"));
155
156
  // [mcp-env] detectors run in Phase 3 (runPostInstallCheck in checks/after/index.ts),
156
157
  // not here: the .bkit/.env.example scaffold exists only after writes. Detectors are
157
158
  // exported from this file for the postinstall module.
@@ -2,24 +2,38 @@
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { parseJson } from "../../shared/json.js";
5
- // ---------------------------------------------------------------------------
6
- // Advisory: missing MCP server entries in .mcp.json / .cursor/mcp.json
7
- // ---------------------------------------------------------------------------
8
- /** Every MCP server key bkit manages; `requiredMcpServersForTracker` picks the required subset. */
9
- const REQUIRED_MCP_SERVERS = ["linear", "github"];
5
+ /** Every MCP server key bkit writes; `requiredMcpServersForTracker` picks the required subset. */
6
+ const BKIT_MCP_SERVERS = ["linear", "github"];
10
7
  /**
11
- * Return the MCP server keys required for a given issue tracker.
12
- *
13
- * - `github` → only `github` MCP server required (Linear gate is a no-op on GitHub tracker).
14
- * - `linear` → both `linear` and `github` required (Linear tracker still dispatches via GitHub PR).
15
- * - `none` → `github` only (tracker calls are no-ops; GitHub surface still needed for PR ops).
8
+ * bkit-written servers a workflow step calls under every tracker, so never flagged as extra:
9
+ * the workflows' gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls `github`.
10
+ */
11
+ const TRACKER_INDEPENDENT_MCP_SERVERS = ["github"];
12
+ /**
13
+ * Return the MCP server keys required for a given issue tracker — exactly the entry the
14
+ * install renderers write: the tracker's own server (`none` → none).
16
15
  */
17
16
  export function requiredMcpServersForTracker(tracker) {
18
- if (tracker === "github")
19
- return ["github"];
20
- if (tracker === "linear")
21
- return ["linear", "github"];
22
- return ["github"]; // none — only GitHub for PR surface
17
+ return tracker === "none" ? [] : [tracker];
18
+ }
19
+ /**
20
+ * Read the server map under `mapKey` of the JSON file at `relPath`.
21
+ * `undefined` → file absent or malformed (callers skip); `null` → file present, no map.
22
+ */
23
+ function readMcpServerMap(cwd, relPath, mapKey) {
24
+ const absPath = path.join(cwd, relPath);
25
+ if (!fs.existsSync(absPath))
26
+ return undefined;
27
+ const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
28
+ if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null)
29
+ return undefined;
30
+ const map = parsed.value[mapKey];
31
+ return map !== null && typeof map === "object" && !Array.isArray(map)
32
+ ? map
33
+ : null;
34
+ }
35
+ function advisoryPathSlug(relPath) {
36
+ return relPath.replace(/[^a-z0-9]/gi, "-");
23
37
  }
24
38
  /**
25
39
  * Advisory: one finding per missing required MCP server key in a given mcp.json file.
@@ -35,19 +49,11 @@ export function requiredMcpServersForTracker(tracker) {
35
49
  * Follows `[context] Message` advisory format.
36
50
  */
37
51
  export function detectMissingMcpServers(cwd, relPath, issueTracker) {
38
- const absPath = path.join(cwd, relPath);
39
- if (!fs.existsSync(absPath))
52
+ const mcpServers = readMcpServerMap(cwd, relPath, "mcpServers");
53
+ if (mcpServers === undefined)
40
54
  return [];
41
- const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
42
- if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null)
43
- return []; // malformed JSON — skip silently
44
- const doc = parsed.value;
45
- const mcpServers = doc.mcpServers !== null && typeof doc.mcpServers === "object" && !Array.isArray(doc.mcpServers)
46
- ? doc.mcpServers
47
- : null;
48
- const requiredServers = requiredMcpServersForTracker(issueTracker);
49
55
  const findings = [];
50
- for (const key of requiredServers) {
56
+ for (const key of requiredMcpServersForTracker(issueTracker)) {
51
57
  if (mcpServers && Object.prototype.hasOwnProperty.call(mcpServers, key))
52
58
  continue;
53
59
  const urlHint = key === "linear"
@@ -56,7 +62,7 @@ export function detectMissingMcpServers(cwd, relPath, issueTracker) {
56
62
  ? `"url": "https://api.githubcopilot.com/mcp/"`
57
63
  : `"url": "<server-url>"`;
58
64
  findings.push({
59
- id: `mcp-missing-server-${key}-${relPath.replace(/[^a-z0-9]/gi, "-")}`,
65
+ id: `mcp-missing-server-${key}-${advisoryPathSlug(relPath)}`,
60
66
  severity: "advisory",
61
67
  detect: `${relPath} is missing the ${key} MCP server in mcpServers.`,
62
68
  action: `[mcp] ${relPath} is missing the ${key} MCP server. Add it to mcpServers: {"${key}": {${urlHint}}}`,
@@ -65,46 +71,40 @@ export function detectMissingMcpServers(cwd, relPath, issueTracker) {
65
71
  return findings;
66
72
  }
67
73
  /**
68
- * Advisory: one finding per bkit-managed MCP server that is present in the file
69
- * but NOT required by the resolved tracker (the symmetric counterpart to
70
- * `detectMissingMcpServers`). Catches the stale-leftover case — e.g. a repo
71
- * switched to `--tracker=github` but still carries the `linear` entry.
74
+ * Advisory: one finding per bkit-written MCP server that is present in the file but NOT
75
+ * required by the resolved tracker (the symmetric counterpart to `detectMissingMcpServers`).
76
+ * Catches the stale-leftover case — e.g. a repo switched to `--tracker=github` but still
77
+ * carrying the `linear` entry.
78
+ *
79
+ * Only flags tracker-only servers bkit itself writes (`BKIT_MCP_SERVERS` minus
80
+ * `TRACKER_INDEPENDENT_MCP_SERVERS`). Consumer-added MCP servers (custom tooling, other
81
+ * providers) are never flagged for removal.
72
82
  *
73
- * Only flags servers bkit itself manages (`REQUIRED_MCP_SERVERS`). Consumer-added
74
- * MCP servers (custom tooling, other providers) are never flagged for removal.
83
+ * `mapKey` names the server map: `mcpServers` (`.mcp.json`, `.cursor/mcp.json`) or `mcp`
84
+ * (`.opencode/opencode.json`).
75
85
  *
76
86
  * Semantics:
77
- * - File absent / malformed / no mcpServers → return []
78
- * - bkit-managed server present but not in `requiredMcpServersForTracker(tracker)` → one advisory
87
+ * - File absent / malformed / no server map → return []
88
+ * - tracker-only server present but not in `requiredMcpServersForTracker(tracker)` → one advisory
79
89
  *
80
90
  * Follows `[context] Message` advisory format.
81
91
  */
82
- export function detectExtraMcpServers(cwd, relPath, issueTracker) {
83
- const absPath = path.join(cwd, relPath);
84
- if (!fs.existsSync(absPath))
85
- return [];
86
- const parsed = parseJson(fs.readFileSync(absPath, "utf-8"));
87
- if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null)
88
- return []; // malformed JSON — skip silently
89
- const doc = parsed.value;
90
- const mcpServers = doc.mcpServers !== null && typeof doc.mcpServers === "object" && !Array.isArray(doc.mcpServers)
91
- ? doc.mcpServers
92
- : null;
93
- if (!mcpServers)
92
+ export function detectExtraMcpServers(cwd, relPath, issueTracker, mapKey = "mcpServers") {
93
+ const servers = readMcpServerMap(cwd, relPath, mapKey);
94
+ if (!servers)
94
95
  return [];
95
96
  const allowed = requiredMcpServersForTracker(issueTracker);
96
97
  const findings = [];
97
- // Only consider servers bkit manages — never flag consumer-added MCP servers.
98
- for (const key of REQUIRED_MCP_SERVERS) {
99
- if (allowed.includes(key))
98
+ for (const key of BKIT_MCP_SERVERS) {
99
+ if (allowed.includes(key) || TRACKER_INDEPENDENT_MCP_SERVERS.includes(key))
100
100
  continue;
101
- if (!Object.prototype.hasOwnProperty.call(mcpServers, key))
101
+ if (!Object.prototype.hasOwnProperty.call(servers, key))
102
102
  continue;
103
103
  findings.push({
104
- id: `mcp-extra-server-${key}-${relPath.replace(/[^a-z0-9]/gi, "-")}`,
104
+ id: `mcp-extra-server-${key}-${advisoryPathSlug(relPath)}`,
105
105
  severity: "advisory",
106
106
  detect: `${relPath} has the ${key} MCP server but the ${issueTracker} tracker does not use it.`,
107
- action: `[mcp] ${relPath} carries the ${key} MCP server, which is not used by the ${issueTracker} tracker. Remove the "${key}" entry from mcpServers.`,
107
+ action: `[mcp] ${relPath} carries the ${key} MCP server, which is not used by the ${issueTracker} tracker. Remove the "${key}" entry from ${mapKey}.`,
108
108
  });
109
109
  }
110
110
  return findings;
@@ -2,7 +2,7 @@
2
2
  //
3
3
  // A fail-open advisory that compares the set of ship steps RECORDED in a
4
4
  // status.jsonl against the set of steps the workflow PROSE says should be
5
- // there. It derives its expected set from .bkit/workflows/bkit-ship.md at
5
+ // there. It derives its expected set from .bkit/core/workflows/bkit-ship.md at
6
6
  // runtime (headings + step:"ship-*" literals) — NEVER a hand-maintained table
7
7
  // (decision 384-tier3-promotion).
8
8
  //