@cbartens/bkit 5.2.4 → 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 (221) hide show
  1. package/.bkit/README.md +26 -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 +11 -0
  6. package/.bkit/core/.bkit/README.md +25 -10
  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 +12 -6
  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 +106 -17
  15. package/.bkit/core/.bkit/trackers.md +47 -1
  16. package/.bkit/core/.bkit/workflows.md +44 -43
  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-adoption.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -10
  22. package/.bkit/core/docs/templates/bkit-audit-llm.md +20 -14
  23. package/.bkit/core/docs/templates/bkit-audit-prompts.md +2 -2
  24. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -8
  25. package/.bkit/core/docs/templates/bkit-audit-security.md +3 -3
  26. package/.bkit/core/docs/templates/bkit-audit-testing.md +4 -3
  27. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  28. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  29. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  30. package/.bkit/core/engine/checks/after/github.ts +29 -120
  31. package/.bkit/core/engine/checks/after/index.ts +2 -2
  32. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  33. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  34. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  35. package/.bkit/core/engine/checks/before/index.ts +7 -43
  36. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  37. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  38. package/.bkit/core/engine/checks/status-holes.ts +4 -5
  39. package/.bkit/core/engine/checks/tips/catalogue.ts +60 -24
  40. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  41. package/.bkit/core/engine/checks/tips/index.ts +37 -8
  42. package/.bkit/core/engine/cli.ts +39 -16
  43. package/.bkit/core/engine/commands/analysis.ts +36 -26
  44. package/.bkit/core/engine/commands/comply.ts +17 -16
  45. package/.bkit/core/engine/commands/harvest.ts +12 -12
  46. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  47. package/.bkit/core/engine/commands/install/install.ts +62 -126
  48. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  49. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  50. package/.bkit/core/engine/commands/lib.ts +35 -10
  51. package/.bkit/core/engine/commands/tips.ts +8 -5
  52. package/.bkit/core/engine/commands/workflow/branches.ts +4 -4
  53. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  54. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  55. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  56. package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
  57. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  58. package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
  59. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  60. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  61. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  62. package/.bkit/core/engine/commands/workflow/workflows.ts +15 -14
  63. package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
  64. package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
  65. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  66. package/.bkit/core/engine/install/manifest.ts +14 -7
  67. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  68. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  69. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  70. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  71. package/.bkit/core/engine/install/modules/core.ts +91 -70
  72. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  73. package/.bkit/core/engine/install/modules/index.ts +7 -1
  74. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  75. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  76. package/.bkit/core/engine/install/placeholders.ts +3 -18
  77. package/.bkit/core/engine/install/write.ts +59 -12
  78. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  79. package/.bkit/core/engine/render/hosts.ts +47 -67
  80. package/.bkit/core/engine/render/models.ts +29 -11
  81. package/.bkit/core/engine/shared/branches.ts +13 -0
  82. package/.bkit/core/engine/shared/egress.ts +3 -3
  83. package/.bkit/core/engine/shared/json.ts +18 -1
  84. package/.bkit/core/engine/shared/package-json.ts +63 -0
  85. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  86. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  87. package/.bkit/core/engine/shared/settings.ts +36 -0
  88. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  89. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  90. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  91. package/.bkit/core/prompts/bkit-audit-generate.md +60 -7
  92. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  93. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  94. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  95. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  96. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  100. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  102. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  103. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  104. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  105. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  106. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  107. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  108. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  109. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  110. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  111. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  112. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  113. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  114. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  115. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  116. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  117. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  118. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  119. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  120. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  121. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  122. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  123. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  124. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  125. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  126. package/.bkit/core/workflows/bkit-build.md +3 -3
  127. package/.bkit/core/workflows/bkit-debug.md +69 -33
  128. package/.bkit/core/workflows/bkit-design.md +2 -2
  129. package/.bkit/core/workflows/bkit-plan.md +11 -4
  130. package/.bkit/core/workflows/bkit-ship.md +5 -5
  131. package/.bkit/shared/.claude/bkit-cloud.md +46 -13
  132. package/.bkit/shared/.claude/settings.json +18 -0
  133. package/.bkit/shared/.cursor/mcp.json +2 -1
  134. package/.bkit/shared/.opencode/opencode.json +19 -1
  135. package/.bkit/shared/docs/deployments.md +20 -4
  136. package/.bkit/shared/docs/security.md +8 -6
  137. package/.bkit/shared/docs/testing.md +9 -5
  138. package/.bkit/templates/.cursor/Dockerfile +30 -16
  139. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  140. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  141. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  142. package/.bkit/templates/.github/renovate.json5 +91 -12
  143. package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
  144. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  145. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  146. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  147. package/.bkit/templates/.husky/pre-push +8 -3
  148. package/.bkit/templates/.oxlintrc.json +21 -0
  149. package/.bkit/templates/docs/capabilities.md +1 -1
  150. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  151. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  152. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  153. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  154. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  155. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  156. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  157. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  158. package/CHANGELOG.md +50 -3
  159. package/README.md +258 -129
  160. package/dist/checks/after/auth.js +10 -11
  161. package/dist/checks/after/ci-yml.js +11 -14
  162. package/dist/checks/after/github.js +32 -125
  163. package/dist/checks/after/index.js +3 -2
  164. package/dist/checks/after/managed.js +8 -24
  165. package/dist/checks/after/tools.js +3 -16
  166. package/dist/checks/before/context-fetch.js +1 -21
  167. package/dist/checks/before/index.js +6 -42
  168. package/dist/checks/before/mcp.js +14 -9
  169. package/dist/checks/before/repo.js +8 -11
  170. package/dist/checks/status-holes.js +5 -6
  171. package/dist/checks/tips/catalogue.js +51 -18
  172. package/dist/checks/tips/detect.js +41 -2
  173. package/dist/checks/tips/index.js +25 -5
  174. package/dist/cli.js +34 -14
  175. package/dist/commands/analysis.js +21 -5
  176. package/dist/commands/comply.js +20 -18
  177. package/dist/commands/harvest.js +12 -13
  178. package/dist/commands/install/doctor.js +55 -23
  179. package/dist/commands/install/install.js +62 -118
  180. package/dist/commands/install/uninstall.js +165 -31
  181. package/dist/commands/install/upgrade.js +46 -39
  182. package/dist/commands/lib.js +32 -10
  183. package/dist/commands/tips.js +6 -3
  184. package/dist/commands/workflow/branches.js +3 -5
  185. package/dist/commands/workflow/counters.js +17 -7
  186. package/dist/commands/workflow/fids.js +39 -0
  187. package/dist/commands/workflow/ledgers.js +3 -1
  188. package/dist/commands/workflow/prs.js +3 -3
  189. package/dist/commands/workflow/repo.js +2 -2
  190. package/dist/commands/workflow/roadmap.js +4 -4
  191. package/dist/commands/workflow/runs.js +5 -5
  192. package/dist/commands/workflow/steps.js +1 -0
  193. package/dist/commands/workflow/tests.js +16 -3
  194. package/dist/commands/workflow/workflows.js +15 -15
  195. package/dist/commands/workflow/workstreams.js +2 -1
  196. package/dist/commands/workflow/worktrees.js +4 -5
  197. package/dist/install/cloud-env.js +10 -23
  198. package/dist/install/manifest.js +14 -7
  199. package/dist/install/modules/antigravity.js +15 -26
  200. package/dist/install/modules/claude.js +17 -21
  201. package/dist/install/modules/cloud.js +6 -2
  202. package/dist/install/modules/codex.js +15 -29
  203. package/dist/install/modules/core.js +82 -63
  204. package/dist/install/modules/cursor.js +6 -9
  205. package/dist/install/modules/index.js +6 -1
  206. package/dist/install/modules/opencode.js +41 -72
  207. package/dist/install/network-allowlist.js +62 -0
  208. package/dist/install/placeholders.js +3 -16
  209. package/dist/install/write.js +55 -15
  210. package/dist/ledgers/telemetry.js +5 -4
  211. package/dist/render/hosts.js +30 -55
  212. package/dist/render/models.js +20 -9
  213. package/dist/shared/branches.js +11 -0
  214. package/dist/shared/egress.js +0 -2
  215. package/dist/shared/json.js +14 -0
  216. package/dist/shared/package-json.js +61 -0
  217. package/dist/shared/package-roots.js +0 -8
  218. package/dist/shared/protected-paths.js +5 -122
  219. package/dist/shared/settings.js +18 -1
  220. package/package.json +21 -17
  221. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -2,14 +2,16 @@
2
2
  // allows, and the tracker entry in the MCP config files (`.mcp.json`, `.cursor/mcp.json`).
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
- import { writeTier1, writeTier2, writeTier2JsonContained, ensureDir, } from "../write.js";
5
+ import { writeTier1, writeTier2, writeTier2JsonContained, ensureDir, mergeTrackerEntry, trackerEntryInSync, } from "../write.js";
6
6
  import { readBkitVersion, stampManagedVersion } from "../version-file.js";
7
+ import { readJsonFile } from "../../shared/json.js";
7
8
  import { applyEffortRemap } from "../../render/hosts.js";
8
9
  import { getCoreRoot, getSharedRoot, getWorkflowsRoot, getPromptsRoot, } from "../../shared/package-roots.js";
9
10
  import { DEFAULT_ISSUE_TRACKER } from "../manifest.js";
10
11
  import { substituteWorkflow } from "../../render/trackers.js";
11
12
  import { writeClaudeCloudDoc, resolveClaudeDerivedAllows } from "../cloud-env.js";
12
- import { BKIT_PREFIX, installFile, listMdFiles, readInstallingVersion, removeOrphans, trackMirrorWrite, } from "./core.js";
13
+ import { readInstallingVersion } from "../../shared/package-json.js";
14
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
13
15
  export function renderClaudeAgentsCommands(ctx) {
14
16
  const { dryRun, logPrefix, effortMap } = ctx;
15
17
  const tag = dryRun ? "[dry-run] " : "";
@@ -192,13 +194,10 @@ export function runClaudeModule(ctx) {
192
194
  export function enrichClaudeSettingsAllows(settingsDst, cwd, dryRun, ws, advisories) {
193
195
  if (!fs.existsSync(settingsDst))
194
196
  return null;
195
- let doc;
196
- try {
197
- doc = JSON.parse(fs.readFileSync(settingsDst, "utf-8"));
198
- }
199
- catch {
197
+ const settings = readJsonFile(settingsDst);
198
+ if (!settings.ok)
200
199
  return null;
201
- }
200
+ const doc = settings.value;
202
201
  const allow = doc.permissions?.allow;
203
202
  if (!Array.isArray(allow))
204
203
  return null;
@@ -247,12 +246,14 @@ export function buildMcpJson(templatePath, tracker) {
247
246
  }
248
247
  /**
249
248
  * Reconcile bkit's tracker entry into a consumer's `.mcp.json` / `.cursor/mcp.json`. bkit
250
- * owns exactly one key, `mcpServers[<tracker>]`, and sets it to the template's entry; every
249
+ * owns exactly one key, `mcpServers[<tracker>]`, and within it only what the template sets
250
+ * (`mergeTrackerEntry`: extra keys, headers and toolsets stay the consumer's); every
251
251
  * other key and the existing key order stay the consumer's. Absent file → write the
252
252
  * `buildMcpJson` render. Malformed JSON → throw (refuse to merge; the consumer fixes it).
253
253
  * Tracker `none` owns no entry, so a present file is left alone. Writes only on change, so
254
- * dry-run and live compute the identical WriteSet. Another tracker's entry from an earlier
255
- * install is left in place (`detectExtraMcpServers` advises on it).
254
+ * dry-run and live compute the identical WriteSet. Another tracker's entry is not touched
255
+ * here: a `--tracker` switch removes an unedited one first (`removeUnusedTrackerMcpEntries`),
256
+ * and `detectExtraMcpServers` advises on an edited one.
256
257
  */
257
258
  export function reconcileMcpJson(templatePath, relDst, tracker, dryRun, ws) {
258
259
  const rendered = buildMcpJson(templatePath, tracker);
@@ -264,24 +265,19 @@ export function reconcileMcpJson(templatePath, relDst, tracker, dryRun, ws) {
264
265
  ws.writes.push({ path: relDst, action: "write" });
265
266
  return;
266
267
  }
267
- // Parse-or-sentinel idiom (see reconcileOpencodeJson): the throw stays out of the catch.
268
- let existing = null;
269
- try {
270
- existing = JSON.parse(fs.readFileSync(relDst, "utf-8"));
271
- }
272
- catch {
273
- existing = null;
274
- }
268
+ const read = readJsonFile(relDst);
269
+ const existing = read.ok ? read.value : null;
275
270
  if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
276
271
  throw new Error(`[bkit] ${relDst} is malformed JSON — fix manually before running bkit install`);
277
272
  }
278
273
  const owned = JSON.parse(rendered).mcpServers;
279
274
  const servers = existing.mcpServers;
280
275
  const serversObj = servers !== null && typeof servers === "object" && !Array.isArray(servers) ? servers : {};
281
- const inSync = Object.entries(owned).every(([k, v]) => JSON.stringify(serversObj[k]) === JSON.stringify(v));
276
+ const inSync = Object.entries(owned).every(([k, v]) => trackerEntryInSync(serversObj[k], v));
282
277
  if (inSync)
283
278
  return;
284
- const next = { ...existing, mcpServers: { ...serversObj, ...owned } };
279
+ const merged = Object.fromEntries(Object.entries(owned).map(([k, v]) => [k, mergeTrackerEntry(serversObj[k], v)]));
280
+ const next = { ...existing, mcpServers: { ...serversObj, ...merged } };
285
281
  if (!dryRun)
286
282
  fs.writeFileSync(relDst, JSON.stringify(next, null, 2) + "\n", "utf-8");
287
283
  ws.writes.push({ path: relDst, action: "update" });
@@ -4,6 +4,7 @@
4
4
  // environment) ships as a copy-and-own template.
5
5
  import * as fs from "node:fs";
6
6
  import * as path from "node:path";
7
+ import { parseJson } from "../../shared/json.js";
7
8
  // ---------------------------------------------------------------------------
8
9
  // Helpers
9
10
  // ---------------------------------------------------------------------------
@@ -23,7 +24,10 @@ function setConsumerBkitField(field, value, dryRun) {
23
24
  return;
24
25
  try {
25
26
  const raw = fs.readFileSync(pkgPath, "utf-8");
26
- const pkg = JSON.parse(raw);
27
+ const parsed = parseJson(raw);
28
+ if (!parsed.ok)
29
+ return;
30
+ const pkg = parsed.value;
27
31
  const bkit = (pkg.bkit ?? {});
28
32
  if (bkit[field] === value)
29
33
  return; // already set — avoid a no-op rewrite
@@ -88,7 +92,7 @@ export function runCloudModule(ctx) {
88
92
  " - Adopt `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` as `.claude/hooks/bkit-cloud-bootstrap.sh` and edit it freely — the baseline runs `pnpm install` / `vale sync` and the gh login on each cloud session; add your own repo-specific steps (Supabase start, turbo prebuild, etc. — examples inlined). The `.claude/settings.json` SessionStart entry runs it only when present (`test -f … || true`).\n\n" +
89
93
  "IN CLAUDE APP (claude.ai/code → environment selector → + Add environment):\n" +
90
94
  " - Name: the repo name (e.g. `acme-web`) — one environment per repo, since secrets are per-repo.\n" +
91
- " - Setup script: paste from bkit's `cloud.md` § Setup script (installs vale + gh + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
95
+ " - Setup script: paste from bkit's `cloud.md` § Setup script (installs Node 24 + vale + gh + jq + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
92
96
  " - Environment variables: `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP).\n" +
93
97
  " - Tracker env vars (GitHub): `BKIT_GH_TOKEN` above is the only tracker credential — the GitHub MCP server sends it on every call, and the bootstrap hook signs `gh` in with it.\n" +
94
98
  " - Network access: `Trusted` (default). One environment per repo (secrets differ per repo); the setup script + variable *names* are identical across repos, only the values change. See cloud.md § Sharing across repos → Claude.",
@@ -7,7 +7,8 @@ import { applyCodexAgent, parseFrontmatter } from "../../render/hosts.js";
7
7
  import { getCoreRoot, getSharedRoot, getWorkflowsRoot, getPromptsRoot, } from "../../shared/package-roots.js";
8
8
  import { DEFAULT_ISSUE_TRACKER } from "../manifest.js";
9
9
  import { substituteWorkflow } from "../../render/trackers.js";
10
- import { BKIT_PREFIX, installFile, listMdFiles, readInstallingVersion, trackMirrorWrite, } from "./core.js";
10
+ import { readInstallingVersion } from "../../shared/package-json.js";
11
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
11
12
  /**
12
13
  * Convert a workflow orchestrator (`.bkit/core/workflows/*.md`) into a Codex SKILL.md.
13
14
  *
@@ -69,8 +70,8 @@ export function renderCodexAgentsSkills(ctx) {
69
70
  if (!dryRun)
70
71
  ensureDir(dest);
71
72
  const files = listMdFiles(src, BKIT_PREFIX);
72
- // Destination basenames are .toml, so the orphan sweep has to compare on stem.
73
- const sourceStems = new Set(files.map((f) => f.replace(/\.md$/, "")));
73
+ // Destination basenames are .toml, so the orphan sweep compares on the .toml names.
74
+ const sourceNames = new Set(files.map((f) => f.replace(/\.md$/, ".toml")));
74
75
  for (const f of files) {
75
76
  const stem = f.replace(/\.md$/, "");
76
77
  const transform = (c) => `${managedVersionMarker(version, "hash")}\n` +
@@ -81,20 +82,10 @@ export function renderCodexAgentsSkills(ctx) {
81
82
  trackMirrorWrite(ctx, rel, written);
82
83
  }
83
84
  }
84
- if (fs.existsSync(dest)) {
85
- for (const f of fs.readdirSync(dest)) {
86
- if (!f.endsWith(".toml"))
87
- continue;
88
- if (!f.startsWith(BKIT_PREFIX))
89
- continue;
90
- if (!sourceStems.has(f.replace(/\.toml$/, ""))) {
91
- const rel = path.join(dest, f);
92
- if (!dryRun)
93
- fs.rmSync(path.join(dest, f));
94
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
95
- trackMirrorWrite(ctx, rel, written);
96
- }
97
- }
85
+ for (const f of removeOrphans(dest, sourceNames, dryRun, BKIT_PREFIX, { extension: ".toml" })) {
86
+ const rel = path.join(dest, f);
87
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
88
+ trackMirrorWrite(ctx, rel, written);
98
89
  }
99
90
  }
100
91
  // --- Workflow skills: one directory per workflow, each holding SKILL.md ---
@@ -120,18 +111,13 @@ export function renderCodexAgentsSkills(ctx) {
120
111
  }
121
112
  // Orphan sweep is bkit-prefix scoped: `.agents/skills/` is SHARED with third-party
122
113
  // skills installed via skills.sh, so anything not named bkit-* is off limits here.
123
- if (fs.existsSync(CODEX_SKILLS_DIR)) {
124
- for (const d of fs.readdirSync(CODEX_SKILLS_DIR)) {
125
- if (!d.startsWith(BKIT_PREFIX))
126
- continue;
127
- if (sourceStems.has(d))
128
- continue;
129
- const rel = path.join(CODEX_SKILLS_DIR, d);
130
- if (!dryRun)
131
- fs.rmSync(rel, { recursive: true, force: true });
132
- console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
133
- trackMirrorWrite(ctx, rel, written);
134
- }
114
+ const orphans = removeOrphans(CODEX_SKILLS_DIR, sourceStems, dryRun, BKIT_PREFIX, {
115
+ wholeFolders: true,
116
+ });
117
+ for (const d of orphans) {
118
+ const rel = path.join(CODEX_SKILLS_DIR, d);
119
+ console.log(`${logPrefix} ${tag}delete orphan: ${rel}`);
120
+ trackMirrorWrite(ctx, rel, written);
135
121
  }
136
122
  }
137
123
  return written;
@@ -5,9 +5,13 @@ import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { writeTier1, writeTier2, ensurePackageJsonScripts } from "../write.js";
7
7
  import { readBkitVersion, writeBkitVersion, hashFile, mergeCanonicalHashes, } from "../version-file.js";
8
+ import { extractManagedBlock, stripManagedBlock } from "../managed-block.js";
8
9
  import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
9
10
  import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
10
- import { getPkgRoot, getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
11
+ import { writeNetworkAllowlist } from "../network-allowlist.js";
12
+ import { readJsonFile } from "../../shared/json.js";
13
+ import { readInstallingVersion } from "../../shared/package-json.js";
14
+ import { getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
11
15
  import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
12
16
  export function listMdFiles(dir, prefix) {
13
17
  if (!fs.existsSync(dir))
@@ -47,36 +51,43 @@ const ORPHAN_PRUNE_DIRS = [
47
51
  ".claude/commands",
48
52
  ".cursor/agents",
49
53
  ".cursor/commands",
54
+ ".opencode/agents",
55
+ ".opencode/commands",
56
+ ".codex/agents",
57
+ ".agents/skills",
58
+ ".agents/plugins/bkit/agents",
59
+ ".agents/plugins/bkit/skills",
50
60
  ];
51
- export function removeOrphans(destDir, sourceFiles, dryRun, prefix) {
61
+ /**
62
+ * Removes entries of `destDir` that start with `prefix` and are absent from `sourceNames`
63
+ * (entry names as they appear in `destDir`). Returns the removed names; with `dryRun` it
64
+ * reports them without deleting. Throws for any `destDir` outside `ORPHAN_PRUNE_DIRS`.
65
+ */
66
+ export function removeOrphans(destDir, sourceNames, dryRun, prefix, options = {}) {
52
67
  const resolved = path.resolve(destDir);
53
68
  if (!ORPHAN_PRUNE_DIRS.some((d) => path.resolve(d) === resolved)) {
54
69
  throw new Error(`removeOrphans: refusing orphan removal outside allowlist: ${destDir}`);
55
70
  }
56
71
  if (!fs.existsSync(destDir))
57
72
  return [];
73
+ const { extension = ".md", wholeFolders = false } = options;
58
74
  const removed = [];
59
75
  for (const f of fs.readdirSync(destDir)) {
60
- if (!f.endsWith(".md"))
76
+ if (!wholeFolders && !f.endsWith(extension))
61
77
  continue;
62
78
  if (prefix && !f.startsWith(prefix))
63
79
  continue;
64
- if (!sourceFiles.has(f)) {
80
+ if (!sourceNames.has(f)) {
81
+ const target = path.join(destDir, f);
65
82
  if (!dryRun)
66
- fs.rmSync(path.join(destDir, f));
83
+ fs.rmSync(target, { recursive: wholeFolders, force: wholeFolders });
67
84
  removed.push(f);
68
85
  }
69
86
  }
70
87
  return removed;
71
88
  }
72
89
  /** The markered-text `.agents/*.md` blocks core owns. */
73
- const CORE_AGENT_FILES = [
74
- "context.md",
75
- "docs.md",
76
- "rules.md",
77
- "shortcuts.md",
78
- "skills.md",
79
- ];
90
+ const CORE_AGENT_FILES = ["context.md", "docs.md", "rules.md", "skills.md"];
80
91
  // The two shared-root files core writes: stored in `shared/`, owned by the core
81
92
  // manifest, written as html-comment managed blocks.
82
93
  const CORE_SHARED_FILES = [
@@ -171,16 +182,18 @@ function runCoreTemplates(dryRun, tokens, ws, logPrefix) {
171
182
  // mirrored into the consumer's `.bkit/` on every install so a consumer can read them
172
183
  // in-repo without spelunking node_modules. Force-overwritten (Tier 1) — bkit owns
173
184
  // them, so a consumer edit is replaced. Source of truth is the package's own
174
- // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact,
175
- // `wording.md` is repo-only tooling and `friction.md` is a consumer-owned seed —
176
- // none belongs here. `LICENSE.md` is the MIT notice that travels with the files bkit
177
- // writes: MIT requires the copyright and permission notice in every copy.)
185
+ // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact and
186
+ // `wording.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
187
+ // notice that travels with the files bkit writes: MIT requires the copyright and
188
+ // permission notice in every copy.)
178
189
  export const BKIT_CANONICAL_DOCS = [
179
190
  "cloud.md",
180
191
  "comparison.md",
181
192
  "install.md",
182
193
  "jsonl.md",
183
194
  "LICENSE.md",
195
+ "lite.md",
196
+ "pipeline.md",
184
197
  "providers.md",
185
198
  "prompts.md",
186
199
  "templates.md",
@@ -217,6 +230,43 @@ export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
217
230
  console.log(`${logPrefix} ${tag}core: ${dstPath}`);
218
231
  }
219
232
  }
233
+ migrateShortcutsToLite(dryRun, ws, logPrefix);
234
+ }
235
+ // Migration (5.1.0 – 5.2.4 installs, `docs/migrations.md`): the lite workflows lived at
236
+ // `.agents/shortcuts.md`. The consumer's own lines below `bkit:end` (minus the seeded
237
+ // heading) move under `.bkit/lite.md`'s consumer section; the old file is deleted. Runs
238
+ // after the docs loop, so `.bkit/lite.md` is already written. The delete is recorded in
239
+ // ws (as orphan-mirror deletes are) so `bkit check` fails until upgrade runs.
240
+ const RETIRED_SHORTCUTS = path.join(".agents", "shortcuts.md");
241
+ const RETIRED_SHORTCUTS_HEADING = "## Project Shortcuts";
242
+ export function migrateShortcutsToLite(dryRun, ws, logPrefix) {
243
+ if (!fs.existsSync(RETIRED_SHORTCUTS))
244
+ return;
245
+ if (!fs.existsSync(path.join(getBkitDocsRoot(), "lite.md")))
246
+ return;
247
+ const tag = dryRun ? "[dry-run] " : "";
248
+ const dst = path.join(".bkit", "lite.md");
249
+ const old = fs.readFileSync(RETIRED_SHORTCUTS, "utf-8");
250
+ if (extractManagedBlock(old, "html-comment") === null) {
251
+ console.warn(`${logPrefix} ${RETIRED_SHORTCUTS} has no single bkit managed block — left in place. Move your own lines into ${dst} below \`<!-- bkit:end -->\`, then delete it.`);
252
+ return;
253
+ }
254
+ const own = stripManagedBlock(old, "html-comment")
255
+ .split("\n")
256
+ .filter((line) => line.trim() !== RETIRED_SHORTCUTS_HEADING)
257
+ .join("\n")
258
+ .trim();
259
+ if (own.length > 0) {
260
+ if (!dryRun) {
261
+ const current = fs.readFileSync(dst, "utf-8");
262
+ fs.writeFileSync(dst, `${current.replace(/\n*$/, "\n\n")}${own}\n`, "utf-8");
263
+ }
264
+ ws.writes.push({ path: dst, action: "update" });
265
+ }
266
+ if (!dryRun)
267
+ fs.rmSync(RETIRED_SHORTCUTS);
268
+ ws.writes.push({ path: RETIRED_SHORTCUTS, action: "write" });
269
+ console.log(`${logPrefix} ${tag}core: moved ${RETIRED_SHORTCUTS} → ${dst}`);
220
270
  }
221
271
  // ---------------------------------------------------------------------------
222
272
  // Source-rendered host outputs — agents (.agents/prompts source) and commands
@@ -229,28 +279,6 @@ export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
229
279
  // (installFile does not touch ws), matching the install path exactly. Each returns
230
280
  // the consumer-relative dest paths it wrote (for the upgrade summary).
231
281
  // ---------------------------------------------------------------------------
232
- // ---------------------------------------------------------------------------
233
- // Managed-version stamping. The marker shape (stampManagedVersion + regexes) lives
234
- // in install/version-file.ts, shared by the renderer and the `bkit check` detector. Here we
235
- // only resolve WHICH version to stamp: ctx.version (set by install/upgrade) with a
236
- // package-root fallback.
237
- // ---------------------------------------------------------------------------
238
- /**
239
- * Best-effort read of the installing bkit version from the package root's
240
- * package.json. Mirrors getInstallingVersion in commands/install/install.ts; duplicated here
241
- * (not imported) to avoid a modules → install dependency cycle. Returns "0.0.0"
242
- * when unreadable — the same non-fatal fallback the install side uses.
243
- */
244
- export function readInstallingVersion() {
245
- try {
246
- const pkgPath = path.join(getPkgRoot(), "package.json");
247
- const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
248
- return pkg.version ?? "0.0.0";
249
- }
250
- catch {
251
- return "0.0.0";
252
- }
253
- }
254
282
  /** Record a host mirror would-write so `bkit check` exits 1 on content drift. */
255
283
  export function trackMirrorWrite(ctx, relPath, written) {
256
284
  written.push(relPath);
@@ -298,16 +326,13 @@ const PNPM_NOT_A_SCRIPT = new Set([
298
326
  * package.json yields none.
299
327
  */
300
328
  export function detectGateAdvisories(cwd) {
301
- let declared;
302
- try {
303
- const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
304
- declared = { ...BKIT_GATE_SCRIPTS, ...pkg.scripts };
305
- }
306
- catch {
307
- // Absent or malformed package.json — preflight's no-package-json /
308
- // malformed-package-json blockers already report it.
329
+ const read = readJsonFile(path.join(cwd, "package.json"));
330
+ // Absent or malformed package.json — preflight's no-package-json /
331
+ // malformed-package-json blockers already report it.
332
+ if (!read.ok || read.value === null)
309
333
  return [];
310
- }
334
+ const pkg = read.value;
335
+ const declared = { ...BKIT_GATE_SCRIPTS, ...pkg.scripts };
311
336
  const findings = [];
312
337
  // Every script a seeded gate default chains MUST exist, or the gate dies on the first
313
338
  // missing one and the workflow reads that as a real failure. Checked only where the
@@ -379,15 +404,12 @@ export function isNoopScript(value) {
379
404
  * every branch. Read-only; an absent or unparseable package.json yields none.
380
405
  */
381
406
  export function detectNoopGates(cwd) {
382
- let declared;
383
- try {
384
- const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
385
- declared = pkg.scripts ?? {};
386
- }
387
- catch {
388
- // Absent or malformed package.json — preflight's blockers already report it.
407
+ const read = readJsonFile(path.join(cwd, "package.json"));
408
+ // Absent or malformed package.json — preflight's blockers already report it.
409
+ if (!read.ok || read.value === null)
389
410
  return [];
390
- }
411
+ const pkg = read.value;
412
+ const declared = pkg.scripts ?? {};
391
413
  const noop = Object.entries(declared)
392
414
  .filter(([name, value]) => name.startsWith("bkit:gate:") && typeof value === "string")
393
415
  .filter(([, value]) => isNoopScript(value))
@@ -408,13 +430,7 @@ export function runCoreModule(ctx) {
408
430
  const { dryRun, ws, advisories, logPrefix, postDispatch } = ctx;
409
431
  const tag = dryRun ? "[dry-run] " : "";
410
432
  const cwd = process.cwd();
411
- const PKG_ROOT = getPkgRoot();
412
- const PKG_PACKAGE_JSON = path.join(PKG_ROOT, "package.json");
413
- if (!fs.existsSync(PKG_PACKAGE_JSON)) {
414
- console.error(`${logPrefix} package.json not found at ${PKG_PACKAGE_JSON} — package corrupt?`);
415
- process.exit(1);
416
- }
417
- const pkgVersion = JSON.parse(fs.readFileSync(PKG_PACKAGE_JSON, "utf-8")).version;
433
+ const pkgVersion = readInstallingVersion();
418
434
  // Capture first-install signal NOW (before any writes) — used for the post-install banner.
419
435
  // The .bkit/version write happens in postDispatch, so a mid-install crash in a later
420
436
  // module leaves no .bkit/version on disk.
@@ -425,7 +441,7 @@ export function runCoreModule(ctx) {
425
441
  console.log(`${logPrefix} ${tag}Running core payload pass`);
426
442
  runCoreTemplates(dryRun, ctx.tokens, ws, logPrefix);
427
443
  // 3b. bkit canonical docs pass — mirror the package's reference docs
428
- // (cloud/IDEs/prompts/trackers/workflows/README/install/comparison) into the
444
+ // (cloud/IDEs/prompts/trackers/workflows/README/install/comparison/pipeline) into the
429
445
  // consumer's `.bkit/` so they are readable in-repo. Force-overwrite (Tier 1).
430
446
  console.log(`${logPrefix} ${tag}Running bkit docs pass`);
431
447
  runBkitDocs(dryRun, ctx.tokens, ws, logPrefix);
@@ -465,6 +481,9 @@ export function runCoreModule(ctx) {
465
481
  action: `Browse-only — bkit reads its payload from the package regardless. To add the view by hand on POSIX: ln -s ../node_modules/@cbartens/bkit/${rel} ${rel}`,
466
482
  });
467
483
  }
484
+ // 3b4. `.bkit/allowlist.json` — the network allowlist every host's guardrails hook
485
+ // reads (writeNetworkAllowlist), plus the move off the retired `.cursor/` copy.
486
+ writeNetworkAllowlist(cwd, dryRun, ws, logPrefix);
468
487
  // 3c. The bkit:gate:* / bkit:deps:* package.json scripts (add-if-missing). The
469
488
  // advisories read the result.
470
489
  seedCorePackageJsonScripts(ctx);
@@ -7,8 +7,9 @@ import { applyT1, applyT2, applyT3 } from "../../render/hosts.js";
7
7
  import { getCoreRoot, getSharedRoot, getWorkflowsRoot, getPromptsRoot, } from "../../shared/package-roots.js";
8
8
  import { DEFAULT_ISSUE_TRACKER } from "../manifest.js";
9
9
  import { substituteWorkflow } from "../../render/trackers.js";
10
- import { writeCursorCloudDoc, writeNetworkAllowlistArtifact, writeCursorCliPermissionsArtifact, } from "../cloud-env.js";
11
- import { BKIT_PREFIX, installFile, listMdFiles, readInstallingVersion, removeOrphans, trackMirrorWrite, } from "./core.js";
10
+ import { writeCursorCloudDoc, writeCursorCliPermissionsArtifact } from "../cloud-env.js";
11
+ import { readInstallingVersion } from "../../shared/package-json.js";
12
+ import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
12
13
  import { reconcileMcpJson } from "./claude.js";
13
14
  export function renderCursorAgentsCommands(ctx) {
14
15
  const { dryRun, modelLookup, effortMap, logPrefix } = ctx;
@@ -143,15 +144,11 @@ export function runCursorModule(ctx) {
143
144
  }
144
145
  }
145
146
  }
146
- // Cursor-only runtime curl/wget allowlist (bkit-guardrails.cjs reads `.cursor/allowlist.json`).
147
- // Same domain set as Claude WebFetch / OpenCode bash allows — sourced from tooling
148
- // defaults ∪ consumer `allowed-domains`. Not under `.bkit/` (IDE-scoped artifact).
149
147
  // Cursor CLI / cloud-agent MCP allows (`.cursor/cli.json`) from consumer `mcp-servers` —
150
148
  // same server set as Claude `mcp__…` allows / OpenCode `<server>_*` permission rows.
151
- for (const art of [
152
- writeNetworkAllowlistArtifact(process.cwd(), dryRun),
153
- writeCursorCliPermissionsArtifact(process.cwd(), dryRun),
154
- ]) {
149
+ // The curl/wget allowlist the guardrails hook reads is core's `.bkit/allowlist.json`.
150
+ {
151
+ const art = writeCursorCliPermissionsArtifact(process.cwd(), dryRun);
155
152
  if (art.wrote) {
156
153
  ws.writes.push({ path: art.path, action: "write" });
157
154
  console.log(`${logPrefix} ${tag}cursor: ${art.path}`);
@@ -8,6 +8,7 @@ import * as fs from "node:fs";
8
8
  import * as path from "node:path";
9
9
  import { getCoreRoot, getSharedRoot } from "../../shared/package-roots.js";
10
10
  import { getInstallManifest } from "../manifest.js";
11
+ import { writeNetworkAllowlist } from "../network-allowlist.js";
11
12
  import { BKIT_PREFIX, listCoreTemplateFiles, listSharedTemplateFiles, runBkitDocs, runCoreModule, seedCorePackageJsonScripts, } from "./core.js";
12
13
  import { renderClaudeAgentsCommands, runClaudeModule } from "./claude.js";
13
14
  import { renderCursorAgentsCommands, runCursorModule } from "./cursor.js";
@@ -19,7 +20,8 @@ import { runCloudModule } from "./cloud.js";
19
20
  // renderManagedOutputs — re-render the bkit-managed OUTPUT files that the
20
21
  // `bkit upgrade` payload walk does NOT cover:
21
22
  // host agents/commands (source-rendered), the `.bkit/*.md` canonical docs
22
- // (runBkitDocs) and core's package.json scripts (seedCorePackageJsonScripts).
23
+ // (runBkitDocs), `.bkit/allowlist.json` (writeNetworkAllowlist) and core's
24
+ // package.json scripts (seedCorePackageJsonScripts).
23
25
  // `.bkit/prompts.md` is markered → runBkitDocs block-merges it (managed block
24
26
  // refreshed, consumer `## Model Overrides` below bkit:end preserved).
25
27
  //
@@ -41,6 +43,9 @@ export function renderManagedOutputs(modules, ctx) {
41
43
  for (let i = docsBefore; i < ctx.ws.writes.length; i++) {
42
44
  written.push(String(ctx.ws.writes[i].path));
43
45
  }
46
+ // `.bkit/allowlist.json` — the same pass install's core module runs (writeNetworkAllowlist
47
+ // records into ctx.ws, so the caller refreshes its canonicalHashes).
48
+ written.push(...writeNetworkAllowlist(process.cwd(), ctx.dryRun, ctx.ws, ctx.logPrefix));
44
49
  // Core package.json scripts — the same pass install runs, so `bkit check` after a
45
50
  // clean upgrade finds no missing gate name and no superseded script value.
46
51
  written.push(...seedCorePackageJsonScripts(ctx));