@cbartens/bkit 5.2.1 → 5.2.3

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 (90) hide show
  1. package/.bkit/README.md +1 -1
  2. package/.bkit/core/.agents/context.md +2 -2
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +7 -1
  4. package/.bkit/core/.bkit/comparison.md +114 -45
  5. package/.bkit/core/.bkit/install.md +8 -5
  6. package/.bkit/core/.bkit/jsonl.md +3 -3
  7. package/.bkit/core/.bkit/prompts.md +6 -5
  8. package/.bkit/core/.bkit/providers.md +5 -4
  9. package/.bkit/core/.bkit/templates.md +11 -10
  10. package/.bkit/core/.bkit/workflows.md +8 -6
  11. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
  12. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
  13. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +5 -2
  14. package/.bkit/core/docs/templates/bkit-audit-adoption.md +5 -2
  15. package/.bkit/core/docs/templates/bkit-audit-agents.md +5 -2
  16. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +5 -2
  17. package/.bkit/core/docs/templates/bkit-audit-analytics.md +5 -2
  18. package/.bkit/core/docs/templates/bkit-audit-annotations.md +6 -3
  19. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +5 -2
  20. package/.bkit/core/docs/templates/bkit-audit-app-store.md +5 -2
  21. package/.bkit/core/docs/templates/bkit-audit-architecture.md +5 -2
  22. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +5 -2
  23. package/.bkit/core/docs/templates/bkit-audit-config.md +5 -2
  24. package/.bkit/core/docs/templates/bkit-audit-cost.md +5 -2
  25. package/.bkit/core/docs/templates/bkit-audit-coverage.md +5 -2
  26. package/.bkit/core/docs/templates/bkit-audit-database.md +5 -2
  27. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -2
  28. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +5 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +5 -2
  30. package/.bkit/core/docs/templates/bkit-audit-documentation.md +5 -2
  31. package/.bkit/core/docs/templates/bkit-audit-duplication.md +5 -2
  32. package/.bkit/core/docs/templates/bkit-audit-failures.md +6 -3
  33. package/.bkit/core/docs/templates/bkit-audit-flakes.md +6 -3
  34. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  35. package/.bkit/core/docs/templates/bkit-audit-issues.md +5 -2
  36. package/.bkit/core/docs/templates/bkit-audit-llm.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-logs.md +16 -12
  38. package/.bkit/core/docs/templates/bkit-audit-models.md +5 -2
  39. package/.bkit/core/docs/templates/bkit-audit-privacy.md +5 -2
  40. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -2
  41. package/.bkit/core/docs/templates/bkit-audit-red-team.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-reliability.md +6 -3
  43. package/.bkit/core/docs/templates/bkit-audit-repo.md +5 -2
  44. package/.bkit/core/docs/templates/bkit-audit-security.md +6 -3
  45. package/.bkit/core/docs/templates/bkit-audit-slop.md +5 -2
  46. package/.bkit/core/docs/templates/bkit-audit-testing.md +5 -2
  47. package/.bkit/core/docs/templates/bkit-audit-usability.md +5 -2
  48. package/.bkit/core/docs/templates/bkit-plan.md +1 -1
  49. package/.bkit/core/engine/checks/after/index.ts +2 -2
  50. package/.bkit/core/engine/commands/install/check.ts +3 -11
  51. package/.bkit/core/engine/commands/install/doctor.ts +2 -3
  52. package/.bkit/core/engine/commands/install/install.ts +44 -11
  53. package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
  54. package/.bkit/core/engine/commands/install/upgrade.ts +8 -1
  55. package/.bkit/core/engine/commands/workflow/branches.ts +13 -4
  56. package/.bkit/core/engine/install/hosts.ts +14 -4
  57. package/.bkit/core/engine/install/manifest.ts +2 -2
  58. package/.bkit/core/engine/install/modules/core.ts +9 -6
  59. package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
  60. package/.bkit/core/hooks/guardrails-read.js +4 -9
  61. package/.bkit/core/hooks/guardrails-tiers.js +312 -28
  62. package/.bkit/core/prompts/bkit-audit-generate.md +19 -5
  63. package/.bkit/shared/.claude/settings.json +19 -0
  64. package/.bkit/shared/.opencode/opencode.json +21 -1
  65. package/.bkit/shared/docs/deployments.md +14 -0
  66. package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
  67. package/.bkit/templates/context/bkit-cloudrun.md +28 -19
  68. package/.bkit/templates/context/bkit-expo.md +30 -13
  69. package/.bkit/templates/context/bkit-inngest.md +54 -17
  70. package/.bkit/templates/context/bkit-resend.md +36 -8
  71. package/.bkit/templates/context/bkit-sentry.md +11 -4
  72. package/.bkit/templates/context/bkit-stripe.md +39 -22
  73. package/.bkit/templates/context/bkit-supabase.md +45 -20
  74. package/.bkit/templates/context/bkit-vercel.md +45 -16
  75. package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
  76. package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
  77. package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
  78. package/CHANGELOG.md +45 -0
  79. package/README.md +76 -20
  80. package/dist/checks/after/index.js +1 -1
  81. package/dist/commands/install/check.js +3 -15
  82. package/dist/commands/install/doctor.js +2 -1
  83. package/dist/commands/install/install.js +42 -8
  84. package/dist/commands/install/uninstall.js +52 -45
  85. package/dist/commands/install/upgrade.js +8 -2
  86. package/dist/commands/workflow/branches.js +13 -5
  87. package/dist/install/hosts.js +11 -4
  88. package/dist/install/manifest.js +2 -2
  89. package/dist/install/modules/core.js +9 -7
  90. package/package.json +1 -1
@@ -196,13 +196,33 @@ export function refreshPreflightAfterWrites(modules, cwd, issueTracker, seedCoun
196
196
  blockers: fresh.blockers,
197
197
  };
198
198
  }
199
- /** `bkit install`, and `bkit check` (the same pipeline, dry-run). */
200
- export async function runInstall(args) {
199
+ /**
200
+ * The advisory pass that closes a real `bkit upgrade`: `bkit check`'s read-only pipeline
201
+ * under upgrade's log prefix, printing the checklist and rewriting `.bkit/advisories.md`
202
+ * (mode `upgrade`). Never exits — blockers and drift are reported, upgrade keeps its own
203
+ * exit code.
204
+ */
205
+ export function runUpgradeAdvisories() {
206
+ return runInstall({
207
+ verb: "check",
208
+ modules: new Set(),
209
+ tracker: null,
210
+ cloudVariant: null,
211
+ opencodeProvider: null,
212
+ }, true);
213
+ }
214
+ /**
215
+ * `bkit install`, and `bkit check` (the same pipeline, dry-run). `upgradeReport` runs the
216
+ * check pipeline for runUpgradeAdvisories.
217
+ */
218
+ export async function runInstall(args, upgradeReport = false) {
201
219
  const { verb, modules, tracker, cloudVariant, opencodeProvider, uninstallFlags } = args;
202
220
  const dryRun = verb === "check";
203
- if (dryRun)
221
+ if (dryRun && !upgradeReport)
204
222
  setLogPrefix("[bkit-check]");
205
- if (dryRun)
223
+ if (upgradeReport)
224
+ console.log(`${LOG_PREFIX} Checking advisories (read-only)`);
225
+ else if (dryRun)
206
226
  console.log(`${LOG_PREFIX} Running in check (dry-run) mode`);
207
227
  // `bkit check` scopes drift detection to what is INSTALLED (detected by sentinel files),
208
228
  // not to a fixed full set. `install` keeps its explicit resolved set.
@@ -247,13 +267,26 @@ export async function runInstall(args) {
247
267
  const blockerBanner = formatChecklist(blockers);
248
268
  if (blockerBanner)
249
269
  console.log(blockerBanner);
270
+ if (upgradeReport) {
271
+ writeAdvisoriesArtifact(blockers, {
272
+ cwd: process.cwd(),
273
+ mode: "upgrade",
274
+ version: getInstallingVersion(),
275
+ logPrefix: LOG_PREFIX,
276
+ });
277
+ return;
278
+ }
250
279
  process.exit(1);
251
280
  }
252
281
  // Resolve tokens once for the whole install
253
282
  const tokens = await resolveTokens(process.cwd()).catch((err) => {
254
283
  console.error(`${LOG_PREFIX} Token resolution failed: ${err.message}`);
255
- process.exit(1);
284
+ if (!upgradeReport)
285
+ process.exit(1);
286
+ return undefined;
256
287
  });
288
+ if (tokens === undefined)
289
+ return;
257
290
  // Parse model lookup (needed for cursor transforms).
258
291
  // DEFAULTS come from the PACKAGE's .bkit/prompts.md § Models (authoritative, matches the
259
292
  // prompt files about to be installed).
@@ -475,7 +508,7 @@ export async function runInstall(args) {
475
508
  console.log(banner);
476
509
  writeAdvisoriesArtifact(postFindings, {
477
510
  cwd: process.cwd(),
478
- mode: dryRun ? "check" : "install",
511
+ mode: upgradeReport ? "upgrade" : dryRun ? "check" : "install",
479
512
  version: getInstallingVersion(),
480
513
  logPrefix: LOG_PREFIX,
481
514
  suppressed,
@@ -483,7 +516,8 @@ export async function runInstall(args) {
483
516
  });
484
517
  // Check mode: exit 1 on drift (see reportCheckDrift).
485
518
  if (dryRun) {
486
- reportCheckDrift(postFindings, totalWrites, missingHooks);
519
+ if (!upgradeReport)
520
+ reportCheckDrift(postFindings, totalWrites, missingHooks);
487
521
  return;
488
522
  }
489
523
  // P2.T9: exit-1 on Phase 3 blockers + recovery action text.
@@ -495,7 +529,7 @@ export async function runInstall(args) {
495
529
  const recoveryLine = `pnpm bkit uninstall ${recoveryFlags} && <fix the issue> && pnpm bkit install ${recoveryFlags}`;
496
530
  console.error(`${LOG_PREFIX} ${phase3Blockers.length} Phase 3 blocker(s) detected. Recovery:\n ${recoveryLine}`);
497
531
  // P2.T10: --auto-revert: run uninstall in-process before exit-1
498
- if (uninstallFlags.autoRevert) {
532
+ if (uninstallFlags?.autoRevert) {
499
533
  console.log(`${LOG_PREFIX} --auto-revert: reverting install...`);
500
534
  const uninstallCtx = {
501
535
  cwd: process.cwd(),
@@ -23,7 +23,8 @@ import * as path from "node:path";
23
23
  import * as readline from "node:readline";
24
24
  import { stripManagedBlock, detectMarkerStyle } from "../../install/managed-block.js";
25
25
  import { readTemplate } from "../../render/parts.js";
26
- import { getInstallManifest, } from "../../install/manifest.js";
26
+ import { getInstallManifest, ISSUE_TRACKERS, } from "../../install/manifest.js";
27
+ import { OPENCODE_PROVIDERS } from "../../shared/egress.js";
27
28
  import { isConsumerModified, mergeCanonicalHashes, readBkitVersion, writeBkitVersion, } from "../../install/version-file.js";
28
29
  import { getPkgRoot, getSharedRoot, findTemplateSource, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
29
30
  import { PAYLOAD_LINKS } from "../../install/payload-links.js";
@@ -47,34 +48,35 @@ import { LOG_PREFIX, setLogPrefix } from "../../shared/log-prefix.js";
47
48
  // Consumer-only keys at any level are preserved byte-identical.
48
49
  // ---------------------------------------------------------------------------
49
50
  /**
50
- * Detect the tracker bkit seeded into opencode.json from its mcp keys. The template ships an
51
- * `@@OPENCODE_TRACKER_MCP@@` sentinel KEY that renders to `github` / `linear` at install, so a
52
- * strip-scope keyed on the raw template never matches — these detectors let uninstall render the
53
- * template the same way the install did before stripping. Keyed on bkit's known tracker names so
54
- * a consumer-added mcp server is never mistaken for bkit's.
51
+ * Strip bkit's scope from `.opencode/opencode.json`. The template ships `@@OPENCODE_*@@`
52
+ * sentinel KEYS that render to the consumer's tracker and provider, and install keeps every
53
+ * earlier provider block and tracker entry (install is additive), so one file can hold several.
54
+ * Render the template once per known tracker and once per supported provider, then remove each
55
+ * `mcp` entry and `provider` block identical to a rendered one; an entry the consumer added or
56
+ * edited stays whole. The rest of the template (permission sandbox, plugin list) strips leaf by
57
+ * leaf like any Tier-2 JSON file. Reads only the template.
55
58
  */
56
- function detectOpencodeTracker(doc) {
57
- const mcp = doc.mcp;
58
- if (mcp !== null && typeof mcp === "object" && !Array.isArray(mcp)) {
59
- if ("github" in mcp)
60
- return "github";
61
- if ("linear" in mcp)
62
- return "linear";
59
+ export function stripOpencodeJsonScope(consumer, templatePath, cwd) {
60
+ const render = (tracker, provider) => JSON.parse(renderOpencodeJson(templatePath, tracker, provider, cwd));
61
+ const ownedMcp = {};
62
+ for (const tracker of ISSUE_TRACKERS) {
63
+ const { mcp } = render(tracker, OPENCODE_PROVIDERS[0]);
64
+ if (isJsonObject(mcp))
65
+ Object.assign(ownedMcp, mcp);
63
66
  }
64
- return "none";
65
- }
66
- /** Detect the opencode provider key bkit seeded (the first `provider` block key). */
67
- function detectOpencodeProvider(doc) {
68
- const provider = doc.provider;
69
- if (provider !== null && typeof provider === "object" && !Array.isArray(provider)) {
70
- const keys = Object.keys(provider);
71
- if (keys.length > 0) {
72
- const first = keys[0];
73
- // Zen block is keyed `opencode` (built-in id); map back to the bkit CLI key.
74
- return first === "opencode" ? "opencode-zen" : first;
75
- }
67
+ const ownedProviders = {};
68
+ for (const provider of OPENCODE_PROVIDERS) {
69
+ const rendered = render("none", provider).provider;
70
+ if (isJsonObject(rendered))
71
+ Object.assign(ownedProviders, rendered);
76
72
  }
77
- return "opencode-zen";
73
+ const rest = render("none", OPENCODE_PROVIDERS[0]);
74
+ delete rest.mcp;
75
+ delete rest.provider;
76
+ const out = JSON.parse(JSON.stringify(consumer));
77
+ removeOwnedEntries(out, "mcp", ownedMcp);
78
+ removeOwnedEntries(out, "provider", ownedProviders);
79
+ return stripTier2JsonScope(out, rest);
78
80
  }
79
81
  export function stripTier2JsonScope(consumerDoc, templateDoc) {
80
82
  const out = JSON.parse(JSON.stringify(consumerDoc));
@@ -135,18 +137,26 @@ const MCP_JSON_RELPATHS = new Set([".mcp.json", path.join(".cursor", "mcp.json")
135
137
  */
136
138
  export function stripMcpTrackerEntries(consumer, template) {
137
139
  const out = JSON.parse(JSON.stringify(consumer));
138
- const servers = out.mcpServers;
139
140
  const owned = template.mcpServers;
140
- if (!isJsonObject(servers) || !isJsonObject(owned))
141
- return out;
142
- for (const [key, entry] of Object.entries(owned)) {
143
- if (JSON.stringify(servers[key]) === JSON.stringify(entry))
144
- delete servers[key];
145
- }
146
- if (Object.keys(servers).length === 0)
147
- delete out.mcpServers;
141
+ if (isJsonObject(owned))
142
+ removeOwnedEntries(out, "mcpServers", owned);
148
143
  return out;
149
144
  }
145
+ /**
146
+ * Delete each entry of `doc[key]` identical to the same-named entry in `owned`, then drop
147
+ * `doc[key]` once empty. Entries that differ, and names `owned` lacks, stay. Mutates `doc`.
148
+ */
149
+ function removeOwnedEntries(doc, key, owned) {
150
+ const entries = doc[key];
151
+ if (!isJsonObject(entries))
152
+ return;
153
+ for (const [name, entry] of Object.entries(owned)) {
154
+ if (JSON.stringify(entries[name]) === JSON.stringify(entry))
155
+ delete entries[name];
156
+ }
157
+ if (Object.keys(entries).length === 0)
158
+ delete doc[key];
159
+ }
150
160
  function isJsonObject(v) {
151
161
  return v !== null && typeof v === "object" && !Array.isArray(v);
152
162
  }
@@ -457,15 +467,10 @@ export async function runUninstall(modules, ctx) {
457
467
  }
458
468
  const raw = fs.readFileSync(absPath, "utf-8");
459
469
  const consumerDoc = JSON.parse(raw);
460
- let templateRaw = fs.readFileSync(templatePath, "utf-8");
461
- // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS that render to the consumer's
462
- // tracker / provider at install; strip-scope keyed on the RAW template never matches
463
- // the rendered keys, so bkit's mcp + provider blocks (a token-referencing config)
464
- // survive a full uninstall. Render the template with the consumer's OWN tracker +
465
- // provider first so the keys line up and the bkit-owned scope strips cleanly.
466
- if (templateRaw.includes("@@OPENCODE_TRACKER_MCP@@")) {
467
- templateRaw = renderOpencodeJson(templatePath, detectOpencodeTracker(consumerDoc), detectOpencodeProvider(consumerDoc));
468
- }
470
+ const templateRaw = fs.readFileSync(templatePath, "utf-8");
471
+ // opencode.json ships `@@OPENCODE_*@@` sentinel KEYS; stripOpencodeJsonScope
472
+ // renders them for every tracker and provider bkit can have written.
473
+ const isOpencodeJson = templateRaw.includes("@@OPENCODE_TRACKER_MCP@@");
469
474
  const templateDoc = JSON.parse(templateRaw);
470
475
  // `.claude/settings.json` is not written verbatim: after rendering the
471
476
  // template, install appends one `WebFetch(domain:<d>)` grant per entry in
@@ -491,7 +496,9 @@ export async function runUninstall(modules, ctx) {
491
496
  }
492
497
  const stripped = MCP_JSON_RELPATHS.has(summary.file)
493
498
  ? stripMcpTrackerEntries(consumerDoc, templateDoc)
494
- : stripTier2JsonScope(consumerDoc, templateDoc);
499
+ : isOpencodeJson
500
+ ? stripOpencodeJsonScope(consumerDoc, templatePath, ctx.cwd)
501
+ : stripTier2JsonScope(consumerDoc, templateDoc);
495
502
  const strippedJson = JSON.stringify(stripped, null, 2) + "\n";
496
503
  if (Object.keys(stripped).length === 0) {
497
504
  // All keys were bkit-owned → delete file
@@ -26,7 +26,7 @@ import { detectMarkerStyle } from "../../install/managed-block.js";
26
26
  import { applyTokens, resolveTokens } from "../../install/placeholders.js";
27
27
  import { readTemplate } from "../../render/parts.js";
28
28
  import { TEMPLATE_COPIES_DIR, getCoreRoot, getSharedRoot, getBkitDocsRoot, getPkgRoot, } from "../../shared/package-roots.js";
29
- import { getInstallingVersion, requireOpencodeProvider, detectOpencodeProviders, } from "./install.js";
29
+ import { getInstallingVersion, requireOpencodeProvider, detectOpencodeProviders, runUpgradeAdvisories, } from "./install.js";
30
30
  import { setLogPrefix } from "../../shared/log-prefix.js";
31
31
  import { getInstallManifest, getModuleManifest, DEFAULT_ISSUE_TRACKER, parseIssueTracker, } from "../../install/manifest.js";
32
32
  import { OPTIN_MODULES } from "../../install/manifest.js";
@@ -724,7 +724,8 @@ export async function runUpgradeCommand(upgradeFlags) {
724
724
  }
725
725
  // Network allowlist + MCP allows — OpenCode from renderOpencodeJson; Claude enrich
726
726
  // below; Cursor `.cursor/allowlist.json` + `.cursor/cli.json` only when cursor
727
- // module installed.
727
+ // module installed. Written artifacts get their canonicalHashes refreshed below.
728
+ const artifactWrites = [];
728
729
  {
729
730
  const cwd = process.cwd();
730
731
  if (renderModules.has("cursor")) {
@@ -733,6 +734,7 @@ export async function runUpgradeCommand(upgradeFlags) {
733
734
  writeCursorCliPermissionsArtifact(cwd, upgradeFlags.dryRun),
734
735
  ]) {
735
736
  if (art.wrote) {
737
+ artifactWrites.push(art.path);
736
738
  console.log(`${LOG_PREFIX}${upgradeFlags.dryRun ? " [dry-run]" : ""} upgrade: ${art.path}`);
737
739
  }
738
740
  }
@@ -761,6 +763,7 @@ export async function runUpgradeCommand(upgradeFlags) {
761
763
  ...result.updated,
762
764
  ...renderedDocPaths,
763
765
  ...mcpWs.writes.map((w) => path.relative(process.cwd(), w.path)),
766
+ ...artifactWrites,
764
767
  ],
765
768
  skipped: result.skipped,
766
769
  skippedSeedable: result.skippedSeedable,
@@ -773,6 +776,9 @@ export async function runUpgradeCommand(upgradeFlags) {
773
776
  });
774
777
  }
775
778
  console.log(`${LOG_PREFIX} Done. updated: ${result.updated.length}, skipped: ${result.skipped.length}, conflicts: ${result.conflicts.length}, re-rendered: ${rendered.length}`);
779
+ // `.bkit/advisories.md` describes the upgraded repo, not the last install or check.
780
+ if (!upgradeFlags.dryRun)
781
+ await runUpgradeAdvisories();
776
782
  // Non-interactive mode: exit non-zero on conflicts
777
783
  if (upgradeFlags.nonInteractive && result.conflicts.length > 0) {
778
784
  process.exit(1);
@@ -320,8 +320,8 @@ export function readAnchor(text) {
320
320
  return out;
321
321
  }
322
322
  /** `text` with a fresh anchor block on top and every prior one removed, so re-stamping is idempotent. */
323
- export function stampAnchor(text, baseSha, design) {
324
- const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${UPSTREAM}`];
323
+ export function stampAnchor(text, baseSha, design, baseRef = UPSTREAM) {
324
+ const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
325
325
  if (design)
326
326
  header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
327
327
  header.push(ANCHOR_CLOSE);
@@ -947,6 +947,7 @@ function anchorStampVerb(ctx) {
947
947
  }
948
948
  if (baseSha === "")
949
949
  throw new CommandError(EXIT.USAGE, "--base-sha must be non-empty");
950
+ const baseRef = str(ctx.flags.baseRef) ?? UPSTREAM;
950
951
  const designFlag = str(ctx.flags.design);
951
952
  const designFile = designFlag === undefined ? undefined : path.resolve(ctx.cwd, designFlag);
952
953
  const design = designFlag !== undefined && designFile !== undefined && fs.existsSync(designFile)
@@ -956,7 +957,7 @@ function anchorStampVerb(ctx) {
956
957
  }
957
958
  : undefined;
958
959
  const before = fs.readFileSync(file, "utf-8");
959
- const after = stampAnchor(before, baseSha, design);
960
+ const after = stampAnchor(before, baseSha, design, baseRef);
960
961
  // Temp file + rename: a crash mid-write never leaves a half-stamped doc.
961
962
  const tmp = `${file}.bkit-anchor.tmp`;
962
963
  fs.writeFileSync(tmp, after);
@@ -964,6 +965,7 @@ function anchorStampVerb(ctx) {
964
965
  ctx.emit({
965
966
  file: rel,
966
967
  baseSha,
968
+ baseRef,
967
969
  designPath: design?.path ?? null,
968
970
  designBaseSha: design?.baseSha ?? null,
969
971
  changed: before !== after,
@@ -1206,7 +1208,7 @@ export const branchesCommand = {
1206
1208
  run: landVerb,
1207
1209
  },
1208
1210
  "anchor-stamp": {
1209
- summary: "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc (idempotent).",
1211
+ summary: "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
1210
1212
  flags: [
1211
1213
  { name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
1212
1214
  {
@@ -1215,6 +1217,11 @@ export const branchesCommand = {
1215
1217
  required: true,
1216
1218
  help: "base commit the doc was written against (non-empty)",
1217
1219
  },
1220
+ {
1221
+ name: "base-ref",
1222
+ type: "string",
1223
+ help: `ref baseSha was taken from (default ${UPSTREAM}; audit reports pass the audited branch)`,
1224
+ },
1218
1225
  {
1219
1226
  name: "design",
1220
1227
  type: "string",
@@ -1224,6 +1231,7 @@ export const branchesCommand = {
1224
1231
  output: {
1225
1232
  file: "doc stamped",
1226
1233
  baseSha: "base commit stamped",
1234
+ baseRef: "ref stamped",
1227
1235
  designPath: "design path stamped (null when none)",
1228
1236
  designBaseSha: "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
1229
1237
  changed: "false when the doc already carried exactly this block",
@@ -1234,7 +1242,7 @@ export const branchesCommand = {
1234
1242
  "anchor-read": {
1235
1243
  summary: "Read a doc's anchor fields; with --against, decide whether anything landed since its baseSha.",
1236
1244
  flags: [
1237
- { name: "file", type: "string", required: true, help: "design/plan doc" },
1245
+ { name: "file", type: "string", required: true, help: "design/plan doc or audit report" },
1238
1246
  {
1239
1247
  name: "field",
1240
1248
  type: "string",
@@ -2,9 +2,16 @@
2
2
  import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  /**
5
- * Detect which host modules a consumer has installed, by the presence of each host's
6
- * source-rendered agents directory. `bkit upgrade` re-renders only these hosts — never
7
- * force-creating an opencode/cursor tree — and setup tips key host-specific advice on them.
5
+ * The Antigravity plugin's bkit-written paths (install/modules/antigravity.ts). Any one
6
+ * present marks the host installed, so deleting a single file (the manifest included) still
7
+ * leaves the host detected and its missing files reported as drift.
8
+ */
9
+ const ANTIGRAVITY_SENTINELS = ["plugin.json", "hooks.json", "agents", "skills", "hooks"].map((p) => path.join(".agents", "plugins", "bkit", p));
10
+ /**
11
+ * Detect which host modules a consumer has installed: each host's source-rendered agents
12
+ * directory, or for Antigravity any of its plugin files. `bkit upgrade` re-renders only these
13
+ * hosts — never force-creating an opencode/cursor tree — and setup tips key host-specific
14
+ * advice on them.
8
15
  */
9
16
  export function detectInstalledHostModules(cwd) {
10
17
  const mods = new Set();
@@ -16,7 +23,7 @@ export function detectInstalledHostModules(cwd) {
16
23
  mods.add("opencode");
17
24
  if (fs.existsSync(path.join(cwd, ".codex", "agents")))
18
25
  mods.add("codex");
19
- if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
26
+ if (ANTIGRAVITY_SENTINELS.some((rel) => fs.existsSync(path.join(cwd, rel))))
20
27
  mods.add("antigravity");
21
28
  return mods;
22
29
  }
@@ -220,8 +220,8 @@ export const BKIT_BUILD_GATES = [
220
220
  /**
221
221
  * Runs ONE test file — `pnpm bkit:test:file <repo-relative path>` — and writes a JUnit
222
222
  * report to `$BKIT_TEST_REPORT`. `/bkit-build` records each task's red and audits its
223
- * green through it. Never seeded: no default works on every stack; install advises
224
- * when it is missing (detectGateAdvisories).
223
+ * green through it. Never seeded: no default works on every stack; install, check and
224
+ * upgrade advise when it is missing (detectGateAdvisories).
225
225
  */
226
226
  export const BKIT_TEST_FILE_SCRIPT = "bkit:test:file";
227
227
  /**
@@ -291,14 +291,17 @@ const PNPM_NOT_A_SCRIPT = new Set([
291
291
  ]);
292
292
  /**
293
293
  * Advisories for the `bkit:gate:*` scripts: the scripts a still-default gate
294
- * chains that package.json does not declare, and the deeper test tiers the repo has
295
- * but no gate runs. Read-only; an absent or unparseable package.json yields none.
294
+ * chains that package.json does not declare, the deeper test tiers the repo has
295
+ * but no gate runs, and a missing `bkit:test:file`. Judges the scripts as install
296
+ * leaves them (missing gate names at their seeded defaults), so install, `bkit check`
297
+ * and `bkit upgrade` report the same set. Read-only; an absent or unparseable
298
+ * package.json yields none.
296
299
  */
297
300
  export function detectGateAdvisories(cwd) {
298
301
  let declared;
299
302
  try {
300
303
  const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf-8"));
301
- declared = pkg.scripts ?? {};
304
+ declared = { ...BKIT_GATE_SCRIPTS, ...pkg.scripts };
302
305
  }
303
306
  catch {
304
307
  // Absent or malformed package.json — preflight's no-package-json /
@@ -316,7 +319,7 @@ export function detectGateAdvisories(cwd) {
316
319
  for (const [, called] of seeded.matchAll(/\bpnpm ([\w:-]+)/g)) {
317
320
  if (PNPM_NOT_A_SCRIPT.has(called))
318
321
  continue;
319
- if (!(called in declared) && !(called in BKIT_GATE_SCRIPTS))
322
+ if (!(called in declared))
320
323
  missing.add(called);
321
324
  }
322
325
  }
@@ -372,7 +375,7 @@ export function isNoopScript(value) {
372
375
  }
373
376
  /**
374
377
  * Advisory for every `bkit:gate:*` script that is empty or a no-op: it checks nothing,
375
- * so every agent run and push passes it. Warn-only, at install and `bkit check`, on
378
+ * so every agent run and push passes it. Warn-only, at install, `bkit check` and `bkit upgrade`, on
376
379
  * every branch. Read-only; an absent or unparseable package.json yields none.
377
380
  */
378
381
  export function detectNoopGates(cwd) {
@@ -465,8 +468,7 @@ export function runCoreModule(ctx) {
465
468
  // 3c. The bkit:gate:* / bkit:deps:* package.json scripts (add-if-missing). The
466
469
  // advisories read the result.
467
470
  seedCorePackageJsonScripts(ctx);
468
- if (!dryRun)
469
- advisories.push(...detectGateAdvisories(cwd));
471
+ advisories.push(...detectGateAdvisories(cwd));
470
472
  advisories.push(...detectNoopGates(cwd));
471
473
  // 4. .bkit/version write — deferred to postDispatch so it only persists when ALL modules succeed.
472
474
  // This ensures a mid-install crash in a subsequent module does not suppress the first-install
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.2.1",
3
+ "version": "5.2.3",
4
4
  "private": false,
5
5
  "description": "From vibe coding to production code. A senior engineering team's process, ready-made: AI agents design, plan, build, review, fix and ship your features on Claude Code, Cursor, Codex, Google Antigravity and opencode.",
6
6
  "keywords": [