@cbartens/bkit 5.0.0 → 5.0.1

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 (61) hide show
  1. package/.bkit/README.md +10 -14
  2. package/.bkit/core/.bkit/README.md +9 -13
  3. package/.bkit/core/.bkit/cloud.md +15 -24
  4. package/.bkit/core/.bkit/comparison.md +4 -1
  5. package/.bkit/core/.bkit/install.md +54 -149
  6. package/.bkit/core/.bkit/jsonl.md +5 -5
  7. package/.bkit/core/.bkit/templates.md +2 -3
  8. package/.bkit/core/.bkit/workflows.md +7 -3
  9. package/.bkit/core/engine/checks/after/auth.ts +16 -114
  10. package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
  11. package/.bkit/core/engine/checks/after/index.ts +156 -182
  12. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  13. package/.bkit/core/engine/checks/before/env.ts +4 -18
  14. package/.bkit/core/engine/checks/before/files.ts +2 -0
  15. package/.bkit/core/engine/cli.ts +4 -8
  16. package/.bkit/core/engine/commands/install/doctor.ts +9 -2
  17. package/.bkit/core/engine/commands/install/install.ts +24 -2
  18. package/.bkit/core/engine/commands/install/uninstall.ts +23 -0
  19. package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
  20. package/.bkit/core/engine/commands/lib.ts +4 -3
  21. package/.bkit/core/engine/install/cloud-env.ts +0 -1
  22. package/.bkit/core/engine/install/modules/cloud.ts +2 -3
  23. package/.bkit/core/engine/install/modules/core.ts +33 -13
  24. package/.bkit/core/engine/install/payload-links.ts +150 -0
  25. package/.bkit/core/engine/install/template-copies.ts +1 -1
  26. package/.bkit/core/engine/shared/egress.ts +1 -1
  27. package/.bkit/core/workflows/bkit-debug.md +19 -12
  28. package/.bkit/shared/.bkit/.env.example +2 -24
  29. package/.bkit/shared/docs/deployments.md +2 -7
  30. package/.bkit/shared/docs/security.md +1 -1
  31. package/.bkit/shared/gitignore +5 -0
  32. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
  33. package/.bkit/templates/.cursor/Dockerfile +1 -1
  34. package/.bkit/templates/.cursor/environment.json +1 -1
  35. package/.bkit/templates/.github/renovate.json5 +0 -15
  36. package/.bkit/templates/.github/workflows/bkit-ci.yml +2 -22
  37. package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
  38. package/.bkit/templates/.github/workflows/bkit-renovate.yml +0 -5
  39. package/CHANGELOG.md +17 -0
  40. package/README.md +5 -6
  41. package/dist/checks/after/auth.js +16 -108
  42. package/dist/checks/after/ci-yml.js +30 -67
  43. package/dist/checks/after/index.js +136 -152
  44. package/dist/checks/after/suppression.js +39 -0
  45. package/dist/checks/before/env.js +4 -14
  46. package/dist/checks/before/files.js +2 -0
  47. package/dist/cli.js +4 -8
  48. package/dist/commands/install/doctor.js +4 -2
  49. package/dist/commands/install/install.js +16 -2
  50. package/dist/commands/install/uninstall.js +24 -0
  51. package/dist/commands/install/upgrade.js +14 -3
  52. package/dist/commands/lib.js +4 -3
  53. package/dist/install/cloud-env.js +0 -1
  54. package/dist/install/modules/cloud.js +2 -3
  55. package/dist/install/modules/core.js +33 -13
  56. package/dist/install/payload-links.js +119 -0
  57. package/dist/install/template-copies.js +1 -1
  58. package/dist/shared/egress.js +1 -1
  59. package/package.json +2 -2
  60. package/.bkit/core/engine/checks/after/vercel.ts +0 -101
  61. package/dist/checks/after/vercel.js +0 -102
@@ -9,51 +9,102 @@ import { getPkgRoot } from "../../shared/package-roots.js";
9
9
  import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
10
10
  import { TEMPLATES_POINTER } from "../../install/template-copies.js";
11
11
  import { detectManagedStale } from "./managed.js";
12
- import { AGENT_INLINE_SOURCE_GUIDANCE, BKIT_GH_TOKEN_INSTALL_MISSING_ACTION, BKIT_GH_TOKEN_INSTALL_UNKNOWN_ACTION, buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhSecret, detectNpmrcAuth, detectNpmrcAuthTokenLine, detectShellGhMcpToken, detectShellToken, hasGithubMcpServer, } from "./auth.js";
13
- import { VERCEL_MISSING_ACTION, detectVercelEnv, detectVercelInstallCommandMissingAuth, detectVercelProject, } from "./vercel.js";
12
+ import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectShellGhMcpToken, hasGithubMcpServer, } from "./auth.js";
14
13
  import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectGithubProjectFieldIdFormat, detectMainBranchProtection, readConsumerIssueTracker, } from "./github.js";
15
14
  import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
16
- import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlMissingTokenEnv, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
15
+ import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
17
16
  // ---------------------------------------------------------------------------
18
17
  // formatChecklist — pure renderer
19
18
  // ---------------------------------------------------------------------------
19
+ // ---------------------------------------------------------------------------
20
+ // Shared advisory text — the console checklist (`formatChecklist`) and the
21
+ // `.bkit/advisories.md` artifact (`renderAdvisoriesMarkdown`) render the SAME
22
+ // words; only the medium decoration differs (`#` / `**` / `>` in markdown, the
23
+ // `===` banner in the console). One source, so the two can never drift.
24
+ // ---------------------------------------------------------------------------
25
+ /** Title line, shared by both surfaces. */
26
+ export const ADVISORIES_TITLE = "bkit advisories";
27
+ /** Agent instruction line, shared by both surfaces. */
28
+ export const ADVISORIES_AGENT_INSTRUCTIONS = "INSTRUCTIONS FOR AN AI AGENT — copy this file (or specific items) into a coding assistant to apply each item. Each ACTION is self-contained.";
29
+ /** `N finding(s) — B blocker, A advisory.` — the summary both surfaces print. */
30
+ export function advisoriesSummary(findings) {
31
+ const blockerCount = findings.filter((f) => f.severity === "blocker").length;
32
+ const advisoryCount = findings.filter((f) => f.severity === "advisory").length;
33
+ return `${findings.length} finding(s) — ${blockerCount} blocker, ${advisoryCount} advisory.`;
34
+ }
20
35
  /**
21
- * Format a list of findings into the post-install checklist banner.
22
- * Returns `""` when findings is empty — callers can `if (banner)` to stay silent.
23
- * No console.log inside — caller logs.
36
+ * The suppressed-advisory lines both surfaces print. One entry per opt-out, so a package
37
+ * that dismissed an advisory is never silently invisible. Returns `[]` when nothing was
38
+ * suppressed — callers then emit no such block.
39
+ */
40
+ export function suppressedNoteLines(suppressed) {
41
+ if (suppressed.length === 0)
42
+ return [];
43
+ const n = suppressed.length;
44
+ return [
45
+ `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.ignoreAdvisories:`,
46
+ ...suppressed.map((note) => `- ${note.id} (${note.scope})`),
47
+ ];
48
+ }
49
+ /**
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.
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.
24
57
  *
25
58
  * Format per finding:
26
59
  * --- i/N [severity] id ---
27
- * DETECT: ...
28
- * ACTION: ...
60
+ * Detect: ...
61
+ * Action: ...
62
+ *
63
+ * `suppressed` is appended as its own block (see `suppressedNoteLines`) — a dismissed
64
+ * advisory stays visible even when nothing else fired.
29
65
  */
30
- export function formatChecklist(findings) {
31
- if (findings.length === 0)
66
+ export function formatChecklist(findings, suppressed = []) {
67
+ if (findings.length === 0 && suppressed.length === 0)
32
68
  return "";
33
69
  const banner = "=".repeat(58);
34
70
  const total = findings.length;
35
71
  const lines = [];
36
- lines.push(`\n${banner}`);
37
- lines.push(`[bkit] Post-install checklist (${total} item${total === 1 ? "" : "s"})`);
72
+ lines.push("");
73
+ lines.push(banner);
74
+ lines.push(ADVISORIES_TITLE);
38
75
  lines.push(banner);
39
- lines.push("\nINSTRUCTIONS FOR AN AI AGENT — copy this entire block into a\n" +
40
- "coding assistant to apply each item. Each ACTION is self-contained.\n" +
41
- `\n${TEMPLATES_POINTER}\n`);
76
+ lines.push("");
77
+ if (findings.length > 0) {
78
+ lines.push(advisoriesSummary(findings));
79
+ lines.push("");
80
+ lines.push(ADVISORIES_AGENT_INSTRUCTIONS);
81
+ lines.push("");
82
+ lines.push(TEMPLATES_POINTER);
83
+ lines.push("");
84
+ }
42
85
  for (let i = 0; i < findings.length; i++) {
43
86
  const f = findings[i];
44
- lines.push(`\n--- ${i + 1}/${total} [${f.severity}] ${f.id} ---`);
45
- lines.push(`DETECT: ${f.detect}`);
46
- lines.push(`ACTION: ${f.action}`);
87
+ lines.push(`--- ${i + 1}/${total} [${f.severity}] ${f.id} ---`);
88
+ lines.push(`Detect: ${f.detect}`);
89
+ lines.push(`Action: ${f.action}`);
90
+ lines.push("");
91
+ }
92
+ const suppressedLines = suppressedNoteLines(suppressed);
93
+ if (suppressedLines.length > 0) {
94
+ lines.push(...suppressedLines);
95
+ lines.push("");
47
96
  }
48
- lines.push(`\n${banner}\n`);
97
+ lines.push(banner);
98
+ lines.push("");
49
99
  return lines.join("\n");
50
100
  }
51
101
  /**
52
102
  * Render findings as a markdown artifact suitable for `.bkit/advisories.md`.
53
- * Mirrors `formatChecklist` content but in markdown form so the file can be
54
- * referenced and revisited between installs. Overwritten on every run.
103
+ * Renders the SAME content as `formatChecklist` (shared title, summary, agent
104
+ * instructions, template pointer and suppressed block) in markdown form, so the file can
105
+ * be referenced and revisited between installs. Overwritten on every run.
55
106
  */
56
- export function renderAdvisoriesMarkdown(findings, opts) {
107
+ export function renderAdvisoriesMarkdown(findings, opts, suppressed = []) {
57
108
  const lines = [];
58
109
  // This is a generated, gitignored artifact — not authored prose. Advisory
59
110
  // strings (and reproduced config snippets like `.vale.ini`'s `write-good.So =
@@ -62,26 +113,26 @@ export function renderAdvisoriesMarkdown(findings, opts) {
62
113
  // skip the husky hooks fail on a file the consumer cannot edit.
63
114
  lines.push("<!-- vale off -->");
64
115
  lines.push("");
65
- lines.push("# bkit advisories");
116
+ lines.push(`# ${ADVISORIES_TITLE}`);
66
117
  lines.push("");
67
118
  lines.push(`_bkit: ${opts.version}_ `);
68
119
  lines.push(`_Mode: ${opts.mode}_`);
69
120
  lines.push("");
70
121
  lines.push("> Auto-generated by `bkit install` / `bkit check` / `bkit doctor`. Overwritten on each run.");
71
122
  lines.push("");
72
- if (findings.length === 0) {
123
+ if (findings.length === 0 && suppressed.length === 0) {
73
124
  lines.push("**No advisories.** Last run was clean.");
74
125
  lines.push("");
75
126
  return lines.join("\n");
76
127
  }
77
- const blockerCount = findings.filter((f) => f.severity === "blocker").length;
78
- const advisoryCount = findings.filter((f) => f.severity === "advisory").length;
79
- lines.push(`${findings.length} finding(s) — ${blockerCount} blocker, ${advisoryCount} advisory.`);
80
- lines.push("");
81
- lines.push("> INSTRUCTIONS FOR AN AI AGENT — copy this file (or specific items) into a coding assistant to apply each item. Each ACTION is self-contained.");
82
- lines.push("");
83
- lines.push(`> ${TEMPLATES_POINTER}`);
84
- lines.push("");
128
+ if (findings.length > 0) {
129
+ lines.push(advisoriesSummary(findings));
130
+ lines.push("");
131
+ lines.push(`> ${ADVISORIES_AGENT_INSTRUCTIONS}`);
132
+ lines.push("");
133
+ lines.push(`> ${TEMPLATES_POINTER}`);
134
+ lines.push("");
135
+ }
85
136
  const total = findings.length;
86
137
  for (let i = 0; i < total; i++) {
87
138
  const f = findings[i];
@@ -92,6 +143,11 @@ export function renderAdvisoriesMarkdown(findings, opts) {
92
143
  lines.push(`**Action:** ${f.action}`);
93
144
  lines.push("");
94
145
  }
146
+ const suppressedLines = suppressedNoteLines(suppressed);
147
+ if (suppressedLines.length > 0) {
148
+ lines.push(...suppressedLines);
149
+ lines.push("");
150
+ }
95
151
  return lines.join("\n");
96
152
  }
97
153
  /**
@@ -107,7 +163,7 @@ export function writeAdvisoriesArtifact(findings, opts) {
107
163
  const content = renderAdvisoriesMarkdown(findings, {
108
164
  mode: opts.mode,
109
165
  version: opts.version,
110
- });
166
+ }, opts.suppressed ?? []);
111
167
  fs.writeFileSync(filePath, content);
112
168
  const n = findings.length;
113
169
  console.log(`${opts.logPrefix} Wrote .bkit/advisories.md (${n} item${n === 1 ? "" : "s"}).`);
@@ -120,11 +176,17 @@ export function writeAdvisoriesArtifact(findings, opts) {
120
176
  // Changelog version-delta header (A7)
121
177
  // ---------------------------------------------------------------------------
122
178
  /**
123
- * Read the bkit CHANGELOG.md (from the package root) and extract the section
124
- * header for `version`. Returns a formatted version-delta string for display
125
- * in post-install output, or null if CHANGELOG.md is absent or version not found.
179
+ * Read the bkit CHANGELOG.md (from the package root) and extract the release
180
+ * delta for `version`: the header line plus the section's lead summary (the
181
+ * prose before the first `###` sub-heading). Returns a formatted string for
182
+ * display in post-install output, or null if CHANGELOG.md is absent or the
183
+ * version is not found.
126
184
  *
127
185
  * Version header format in CHANGELOG.md: `## [X.Y.Z] — YYYY-MM-DD`
186
+ *
187
+ * Bounded on purpose: an install/check banner must not dump a whole release
188
+ * section. When a section has no lead paragraph the sub-heading names stand in,
189
+ * so the banner is never an empty header.
128
190
  */
129
191
  export function readChangelogVersionDelta(version) {
130
192
  try {
@@ -132,13 +194,35 @@ export function readChangelogVersionDelta(version) {
132
194
  if (!fs.existsSync(changelogPath))
133
195
  return null;
134
196
  const content = fs.readFileSync(changelogPath, "utf-8");
135
- // Find the header for this version
197
+ const lines = content.split(/\r?\n/);
198
+ // Find the header line for this version.
136
199
  const versionEscaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
137
- const headerRe = new RegExp(`^## \\[${versionEscaped}\\][^\n]*`, "m");
138
- const match = content.match(headerRe);
139
- if (!match)
200
+ const headerRe = new RegExp(`^## \\[${versionEscaped}\\]`);
201
+ const start = lines.findIndex((line) => headerRe.test(line));
202
+ if (start === -1)
140
203
  return null;
141
- return `[bkit] What's new in v${version}: ${match[0].replace(/^## /, "")}`;
204
+ // The section runs to the next top-level `## ` header (or EOF).
205
+ let end = lines.length;
206
+ for (let i = start + 1; i < lines.length; i++) {
207
+ if (/^## /.test(lines[i])) {
208
+ end = i;
209
+ break;
210
+ }
211
+ }
212
+ const section = lines.slice(start + 1, end);
213
+ const header = lines[start].replace(/^## /, "");
214
+ // Lead summary: the prose between the header and the first `###` sub-heading.
215
+ const firstSub = section.findIndex((line) => /^### /.test(line));
216
+ const leadEnd = firstSub === -1 ? section.length : firstSub;
217
+ let summary = section.slice(0, leadEnd).join("\n").trim();
218
+ if (!summary) {
219
+ summary = section
220
+ .filter((line) => /^### /.test(line))
221
+ .map((line) => line.replace(/^### /, "").trim())
222
+ .join(", ");
223
+ }
224
+ const headline = `[bkit] What's new in v${version}: ${header}`;
225
+ return summary ? `${headline}\n${summary}` : headline;
142
226
  }
143
227
  catch {
144
228
  return null;
@@ -148,7 +232,7 @@ export function readChangelogVersionDelta(version) {
148
232
  // runPostInstallCheck — main Phase 3 entry point
149
233
  // ---------------------------------------------------------------------------
150
234
  /**
151
- * Re-run token-surface + bkit-ci.yml + vale-sync detectors after writes.
235
+ * Re-run credential + bkit-ci.yml + vale-sync detectors after writes.
152
236
  *
153
237
  * - Intra-phase dedup: Phase 3 findings are deduped by id (first occurrence wins).
154
238
  * - Cross-phase dedup: Phase 3 wins on id conflict (re-detection is more accurate).
@@ -158,35 +242,22 @@ export function readChangelogVersionDelta(version) {
158
242
  * same advisory set against the same filesystem state regardless of caller.
159
243
  *
160
244
  * cwd defaults to process.cwd().
245
+ *
246
+ * Pass `suppressed` to collect the advisories a package opted out of via
247
+ * `bkit.ignoreAdvisories` (one note per id + owning package); the caller renders them with
248
+ * `suppressedNoteLines` so a dismissal stays visible. Omitted by callers that do not render.
161
249
  */
162
- export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd()) {
250
+ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), suppressed) {
163
251
  const phase3 = [];
252
+ const onSuppressed = suppressed
253
+ ? (note) => suppressed.push(note)
254
+ : undefined;
164
255
  // Managed-version marker gate — in `bkit check`, a blocker on main/dev (or a PR into
165
256
  // them) and a non-blocking advisory on feature branches when any stamped file's marker
166
257
  // drifts from the installed version. No-op in real install/upgrade (re-stamped Phase 2).
167
258
  const managedStale = detectManagedStale(cwd);
168
259
  if (managedStale)
169
260
  phase3.push(managedStale);
170
- // Shell token
171
- const shellStatus = detectShellToken();
172
- if (shellStatus === "missing") {
173
- phase3.push({
174
- id: "gh-bkit-token-unset-shell",
175
- severity: "advisory",
176
- detect: "BKIT_GH_TOKEN_INSTALL is not set in the shell environment (undefined).",
177
- action: "Set BKIT_GH_TOKEN_INSTALL in .bkit/.env (canonical local-secrets file, gitignored), then have direnv auto-load it on cd:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN_INSTALL=<classic PAT, read:packages scope>\n direnv allow # one-time per repo; requires `brew install direnv` + shell hook\n\nThen restart your editor (Claude Code / Cursor) so the new env reaches MCP servers. Generate the PAT at: https://github.com/settings/tokens (Tokens (classic)). Fine-grained PATs are rejected by GitHub Packages with HTTP 403 — must be classic.\n\nFallback (if direnv unavailable): export BKIT_GH_TOKEN_INSTALL=<your-pat> in ~/.zshrc / ~/.bashrc.\n\n" +
178
- AGENT_INLINE_SOURCE_GUIDANCE,
179
- });
180
- }
181
- else if (shellStatus === "empty") {
182
- phase3.push({
183
- id: "gh-bkit-token-empty-shell",
184
- severity: "advisory",
185
- detect: 'BKIT_GH_TOKEN_INSTALL is set to an empty string (BKIT_GH_TOKEN_INSTALL=""). `pnpm config set` will write an empty auth token, producing a 401 on the next install.',
186
- action: 'Set a non-empty BKIT_GH_TOKEN_INSTALL in .bkit/.env (canonical local-secrets file), then `direnv allow` and restart your shell so the new value loads. An empty string is distinct from unset, but both make `pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"` store an empty token, so pnpm sends no auth header and the GH Packages registry returns 401 on download. Safest fix: set a real token in .bkit/.env, then re-run the `pnpm config set` line.\n\n' +
187
- AGENT_INLINE_SOURCE_GUIDANCE,
188
- });
189
- }
190
261
  // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server
191
262
  // (`Authorization: Bearer ${BKIT_GH_TOKEN}` in .mcp.json), which powers the entire
192
263
  // tracker + PR + Projects MCP surface. Only flags when a github MCP server is
@@ -210,89 +281,6 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd()) {
210
281
  });
211
282
  }
212
283
  }
213
- // .npmrc auth
214
- const npmrcStatus = detectNpmrcAuth(cwd);
215
- if (npmrcStatus === "missing") {
216
- phase3.push({
217
- id: "npmrc-missing-gh-packages",
218
- severity: "advisory",
219
- detect: ".npmrc exists but is missing the required @cbartens registry mapping.",
220
- action: "Add this line to .npmrc at the repo root (the auth token is NOT stored here):\n\n" +
221
- " @cbartens:registry=https://npm.pkg.github.com\n\n" +
222
- "The token lives in pnpm's user-level config — write it once with:\n\n" +
223
- ' pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"\n\n' +
224
- "pnpm >=10.34.3 does not authenticate a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution (it 401s on download), which is why the token must NOT go in .npmrc.",
225
- });
226
- }
227
- // "unknown" (absent) → silent skip per spec
228
- // .npmrc auth-token line. The committed project .npmrc must NOT carry
229
- // `//npm.pkg.github.com/:_authToken=…`: pnpm >=10.34.3 401s on it AND it shadows the
230
- // user-level token written by `pnpm config set` (project config wins).
231
- if (detectNpmrcAuthTokenLine(cwd)) {
232
- phase3.push({
233
- id: "npmrc-authtoken-line",
234
- severity: "advisory",
235
- detect: ".npmrc carries a `//npm.pkg.github.com/:_authToken=…` line. pnpm >=10.34.3 401s on a project-.npmrc auth token (ERR_PNPM_FETCH_401), and via config precedence (project > user) it shadows the token written by `pnpm config set`.",
236
- action: "Remove the `//npm.pkg.github.com/:_authToken=…` line from .npmrc — keep ONLY the registry mapping:\n\n" +
237
- " @cbartens:registry=https://npm.pkg.github.com\n\n" +
238
- "Then write the token into pnpm's user-level config instead (CI does this in its install step):\n\n" +
239
- ' pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"\n\n' +
240
- "`pnpm config set` stores the shell-expanded literal token in pnpm's user-level config — version-proof across pnpm 10.x and 11.x.",
241
- });
242
- }
243
- // GH secret
244
- const ghSecretStatus = detectGhSecret();
245
- if (ghSecretStatus === "missing") {
246
- phase3.push({
247
- id: "gh-bkit-token-secret-missing",
248
- severity: "advisory",
249
- detect: "gh secret list confirms BKIT_GH_TOKEN_INSTALL secret is NOT set on this GitHub repo.",
250
- action: BKIT_GH_TOKEN_INSTALL_MISSING_ACTION,
251
- });
252
- }
253
- else if (ghSecretStatus === "unknown") {
254
- phase3.push({
255
- id: "gh-bkit-token-secret-unknown",
256
- severity: "advisory",
257
- detect: "Could not verify BKIT_GH_TOKEN_INSTALL secret (gh CLI unavailable, unauthenticated, or not a GitHub repo).",
258
- action: BKIT_GH_TOKEN_INSTALL_UNKNOWN_ACTION,
259
- });
260
- }
261
- // Vercel env (only if a Vercel project is detected)
262
- if (detectVercelProject(cwd)) {
263
- const previewStatus = detectVercelEnv("preview", cwd);
264
- if (previewStatus === "missing") {
265
- phase3.push({
266
- id: "vercel-env-missing-preview",
267
- severity: "advisory",
268
- detect: "vercel.json detected but BKIT_GH_TOKEN_INSTALL is absent from Vercel preview environment.",
269
- action: VERCEL_MISSING_ACTION,
270
- });
271
- }
272
- const productionStatus = detectVercelEnv("production", cwd);
273
- if (productionStatus === "missing") {
274
- phase3.push({
275
- id: "vercel-env-missing-production",
276
- severity: "advisory",
277
- detect: "vercel.json detected but BKIT_GH_TOKEN_INSTALL is absent from Vercel production environment.",
278
- action: VERCEL_MISSING_ACTION,
279
- });
280
- }
281
- // "unknown" → silent skip (CLI absent / unauthed)
282
- // Vercel installCommand auth. The env var alone is not enough: a registry-only .npmrc
283
- // carries no token on pnpm
284
- // >=10.34.3 and Vercel cannot run a pre-install shell step, so each vercel.json must
285
- // authenticate via its installCommand or the @cbartens/bkit download 401s.
286
- const vercelNoAuth = detectVercelInstallCommandMissingAuth(cwd);
287
- if (vercelNoAuth.length > 0) {
288
- phase3.push({
289
- id: "vercel-installcommand-missing-auth",
290
- severity: "advisory",
291
- detect: `${vercelNoAuth.join(", ")} ${vercelNoAuth.length === 1 ? "has" : "have"} no installCommand that authenticates to the GitHub Packages registry. Vercel runs pnpm install with no pre-install shell step, so the @cbartens/bkit download 401s on pnpm >=10.34.3 even when BKIT_GH_TOKEN_INSTALL is set in the Vercel env.`,
292
- action: VERCEL_MISSING_ACTION,
293
- });
294
- }
295
- }
296
284
  // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
297
285
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
298
286
  // protection on main restricting merges to PRs from dev.
@@ -359,10 +347,6 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd()) {
359
347
  const cloudDashboardsAdvisory = buildCloudDashboardsAdvisory(cwd);
360
348
  if (cloudDashboardsAdvisory)
361
349
  phase3.push(cloudDashboardsAdvisory);
362
- // bkit-ci.yml missing token env
363
- const ciYml = detectCiYmlMissingTokenEnv(cwd);
364
- if (ciYml)
365
- phase3.push(ciYml);
366
350
  // GHA action SHA pinning (KN-3). Updater configs are consumer-owned examples.
367
351
  const gha = detectGhaFloatingTags(cwd);
368
352
  if (gha)
@@ -392,7 +376,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd()) {
392
376
  phase3.push(capstoneDrift);
393
377
  // @live/@smoke-tagged tests whose owning package declares no test:live/test:smoke
394
378
  // script — "no CI home".
395
- const taggedNoHome = detectTaggedTestsWithoutCiHome(cwd);
379
+ const taggedNoHome = detectTaggedTestsWithoutCiHome(cwd, onSuppressed);
396
380
  if (taggedNoHome)
397
381
  phase3.push(taggedNoHome);
398
382
  // bkit-stub sentinels in shipped templates — one advisory per still-commented stub.
@@ -402,7 +386,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd()) {
402
386
  for (const f of detectTurboIntegrationInputs(cwd))
403
387
  phase3.push(f);
404
388
  // test:integration runtime env (KN-23 false-confidence loop).
405
- const integrationEnv = detectTestIntegrationEnv(cwd);
389
+ const integrationEnv = detectTestIntegrationEnv(cwd, onSuppressed);
406
390
  if (integrationEnv)
407
391
  phase3.push(integrationEnv);
408
392
  // Consumer composed run-levels on bkit primitives (else docs/deployments.md matrix is doc-only).
@@ -0,0 +1,39 @@
1
+ // checks/after/suppression.ts — per-package advisory opt-out (`package.json`
2
+ // `bkit.ignoreAdvisories`).
3
+ //
4
+ // A detector can be right in general and still fire on a package where the condition is
5
+ // deliberately not applicable (a rule-linter whose test titles mention `@live`, an
6
+ // integration lane mocked by design). package.json is comment-free, so the opt-out is a
7
+ // JSON key, not a comment.
8
+ //
9
+ // Each detector reads the OWNING package's list and drops only that package — never the
10
+ // whole advisory, which would hide a real finding in a sibling package (detector findings
11
+ // aggregate every affected package into one entry). Advisory-only: a blocker is never
12
+ // suppressible whatever the manifest says.
13
+ import { readPackageJson } from "../../shared/package-json.js";
14
+ /**
15
+ * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` key that is
16
+ * absent or not an object, and an `ignoreAdvisories` that is absent or not an array all
17
+ * yield no ids — never a throw.
18
+ */
19
+ export function ignoredAdvisoryIds(dir) {
20
+ const read = readPackageJson(dir);
21
+ if (!read.ok)
22
+ return new Set();
23
+ const bkit = read.pkg.bkit;
24
+ if (typeof bkit !== "object" || bkit === null || Array.isArray(bkit))
25
+ return new Set();
26
+ const list = bkit.ignoreAdvisories;
27
+ if (!Array.isArray(list))
28
+ return new Set();
29
+ return new Set(list.filter((id) => typeof id === "string"));
30
+ }
31
+ /**
32
+ * True when `dir/package.json` opts out of `id` AND the finding resolved to advisory
33
+ * severity. `blocker` returns false unconditionally — a blocker is not suppressible.
34
+ */
35
+ export function isAdvisorySuppressed(dir, id, severity) {
36
+ if (severity !== "advisory")
37
+ return false;
38
+ return ignoredAdvisoryIds(dir).has(id);
39
+ }
@@ -21,9 +21,7 @@ export function detectMissingDotenv(cwd, tracker = "linear") {
21
21
  return null;
22
22
  if (fs.existsSync(envPath))
23
23
  return null;
24
- const tokens = tracker === "linear"
25
- ? "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, BKIT_LINEAR_API_KEY"
26
- : "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL";
24
+ const tokens = tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
27
25
  return {
28
26
  id: "mcp-env-missing-dotenv",
29
27
  severity: "advisory",
@@ -59,10 +57,6 @@ export function detectBlankDotenvKeys(cwd, tracker = "linear") {
59
57
  key: "BKIT_GH_TOKEN",
60
58
  description: "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write)",
61
59
  },
62
- {
63
- key: "BKIT_GH_TOKEN_INSTALL",
64
- description: "classic PAT with read:packages scope for authenticating to the GitHub Packages npm registry (@cbartens/* packages)",
65
- },
66
60
  // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
67
61
  ...(tracker === "linear"
68
62
  ? [
@@ -112,12 +106,8 @@ export function detectDirenvMissing(cwd, tracker = "linear") {
112
106
  if (result.status === 0 && result.stdout.trim())
113
107
  return null;
114
108
  // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
115
- const editKeys = tracker === "linear"
116
- ? "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY"
117
- : "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN";
118
- const exportKeys = tracker === "linear"
119
- ? "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY"
120
- : "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN";
109
+ const editKeys = tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
110
+ const exportKeys = tracker === "linear" ? "BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
121
111
  return {
122
112
  id: "mcp-env-direnv-missing",
123
113
  severity: "advisory",
@@ -166,7 +156,7 @@ export function detectDirenvNotAllowed(cwd, tracker = "linear") {
166
156
  id: "mcp-env-direnv-not-allowed",
167
157
  severity: "advisory",
168
158
  detect: "direnv is installed but the .envrc in this repo is blocked. .bkit/.env is not being auto-loaded.",
169
- action: `[mcp-env] Run \`direnv allow\` in this repo to trust the .envrc and enable auto-load of .bkit/.env. direnv will then export ${tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, and BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN and BKIT_GH_TOKEN_INSTALL"} into your shell whenever you cd into the repo.`,
159
+ action: `[mcp-env] Run \`direnv allow\` in this repo to trust the .envrc and enable auto-load of .bkit/.env. direnv will then export ${tracker === "linear" ? "BKIT_GH_TOKEN and BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN"} into your shell whenever you cd into the repo.`,
170
160
  };
171
161
  }
172
162
  return null;
@@ -29,6 +29,8 @@ const BKIT_GITIGNORE_LINES = [
29
29
  ".husky/_",
30
30
  ".bkit/advisories.md",
31
31
  ".bkit/.env",
32
+ ".bkit/core",
33
+ ".bkit/shared",
32
34
  ];
33
35
  export function detectGitignoreBlockDuplicates(cwd) {
34
36
  const gitignorePath = path.join(cwd, ".gitignore");
package/dist/cli.js CHANGED
@@ -394,8 +394,9 @@ Usage:
394
394
  Hosts compose: --claude --cursor --codex --opencode=<provider>.
395
395
  bkit check Dry-run — drift-check everything already installed (no
396
396
  module flags). Exits 1 when a managed file needs
397
- re-rendering. Templates (.bkit/templates/) are never
398
- drift-checked once copied — the copy is yours. The CI gate.
397
+ re-rendering. Copies under .bkit/templates/ are refreshed by
398
+ install/upgrade and checked for staleness — adopt one by
399
+ copying it elsewhere; that copy is yours. The CI gate.
399
400
  bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
400
401
  Upgrade everything installed (no module flags). Diffs old
401
402
  vs new templates; conflict list emitted to stderr. Use
@@ -410,7 +411,7 @@ Usage:
410
411
  No flags = full removal — ALL modules incl. opt-in add-ons
411
412
  (cloud/opencode) + core. Consumer-owned updater configs
412
413
  (renovate.json5, dependabot.yml, bkit-renovate.yml) are left in place. Consumer-modified
413
- files, the docs/ payload, and generated artefacts
414
+ files, your own files under docs/, and generated artefacts
414
415
  (.bkit/advisories.md, .bkit/friction.jsonl) are preserved (use
415
416
  --nuke to force-remove manifest-listed files). Target with the
416
417
  same module flags as install (e.g. uninstall --claude); a
@@ -560,11 +561,6 @@ macOS GUI-isolation note (launchctl fallback):
560
561
  launchd template set (see \`.bkit/templates.md\` § Launchd GUI environment). Rotation
561
562
  then needs no re-bootstrap — prefer \`bkit cursor\` / \`bkit opencode\` for the dynamic model.
562
563
 
563
- Consumer CI auth:
564
- Set BKIT_GH_TOKEN_INSTALL in GitHub Actions secrets (classic PAT with read:packages scope —
565
- fine-grained PATs are not currently supported by GitHub Packages npm registry).
566
- See README.md ## Consumer CI auth for setup steps.
567
-
568
564
  Docs: https://github.com/cbartens/bkit/blob/main/README.md` + commandsUsage());
569
565
  }
570
566
  /** The `bkit <noun> <verb>` section of the usage text; empty while no command is registered. */
@@ -99,7 +99,8 @@ export async function runDoctor(modules, opencodeProvider) {
99
99
  console.log(`${LOG_PREFIX} Running advisory scan (no managed-file writes)`);
100
100
  console.log(`${LOG_PREFIX} Payload roots: core=${getCoreRoot()} shared=${getSharedRoot()} templates=${getTemplatesRoot()}`);
101
101
  const { blockers, advisories: preflightAdvisories } = runPreflight(modules, process.cwd());
102
- const allFindings = runPostInstallCheck([...preflightAdvisories, ...blockers], process.cwd());
102
+ const suppressed = [];
103
+ const allFindings = runPostInstallCheck([...preflightAdvisories, ...blockers], process.cwd(), suppressed);
103
104
  // Broken install: the opencode host is on disk but neither provider signal survives.
104
105
  // `bkit check` and `bkit upgrade` exit 1 with the fix; doctor reports it here and does
105
106
  // not enforce.
@@ -113,7 +114,7 @@ export async function runDoctor(modules, opencodeProvider) {
113
114
  });
114
115
  }
115
116
  }
116
- const banner = formatChecklist(allFindings);
117
+ const banner = formatChecklist(allFindings, suppressed);
117
118
  if (banner) {
118
119
  console.log(banner);
119
120
  }
@@ -125,6 +126,7 @@ export async function runDoctor(modules, opencodeProvider) {
125
126
  mode: "doctor",
126
127
  version: getInstallingVersion(),
127
128
  logPrefix: LOG_PREFIX,
129
+ suppressed,
128
130
  });
129
131
  // opencode host diagnostics: report required tools and cred presence per provider.
130
132
  // Never echoes key values — only reports present/absent.
@@ -394,6 +394,18 @@ export async function runInstall(args) {
394
394
  else {
395
395
  console.log(`${LOG_PREFIX} Done. ${totalWrites} write(s).`);
396
396
  }
397
+ // Phase 2 has completed its writes. Re-run Phase 1 detection and use its result for the
398
+ // post-install checklist, so the banner reflects the state on disk AFTER the writes.
399
+ // Otherwise a drift finding Phase 2 just resolved (tier2-json-drift, tier2-text-drift,
400
+ // bkit-version-pin-stale) is still reported as unresolved, contradicting the "Done"
401
+ // banner above. `check` (dryRun) wrote nothing, so its Phase 1 findings already describe
402
+ // the current state and are kept as-is. Module-accumulated advisories (pushed during
403
+ // dispatch) are preserved; only the Phase 1 seeds are replaced, in their original order.
404
+ if (!dryRun) {
405
+ const moduleAdvisories = advisories.slice(preflightAdvisories.length);
406
+ const { advisories: freshPreflightAdvisories } = runPreflight(effectiveModules, process.cwd(), undefined, issueTracker);
407
+ ctx.advisories = [...freshPreflightAdvisories, ...moduleAdvisories];
408
+ }
397
409
  // --- Phase 3: Post-install checks (re-detect + unified output) ---
398
410
  // Runs for both install AND check — detectors are read-only, so check produces
399
411
  // the same advisory set as install would emit against the same filesystem state.
@@ -410,14 +422,15 @@ export async function runInstall(args) {
410
422
  catch (err) {
411
423
  void err; // Non-fatal — changelog header is informational
412
424
  }
413
- const postFindings = runPostInstallCheck(ctx.advisories, process.cwd());
425
+ const suppressed = [];
426
+ const postFindings = runPostInstallCheck(ctx.advisories, process.cwd(), suppressed);
414
427
  // check only: install has just written every hook file of the modules it dispatched, and a
415
428
  // missing bkit-cloud-bootstrap.sh after `install --claude` is not that run's fault.
416
429
  const missingHooks = dryRun ? findMissingOwnedHooks(process.cwd(), effectiveModules) : [];
417
430
  const missingHooksFinding = detectOwnedHookMissing(missingHooks);
418
431
  if (missingHooksFinding)
419
432
  postFindings.push(missingHooksFinding);
420
- const banner = formatChecklist(postFindings);
433
+ const banner = formatChecklist(postFindings, suppressed);
421
434
  if (banner)
422
435
  console.log(banner);
423
436
  writeAdvisoriesArtifact(postFindings, {
@@ -425,6 +438,7 @@ export async function runInstall(args) {
425
438
  mode: dryRun ? "check" : "install",
426
439
  version: getInstallingVersion(),
427
440
  logPrefix: LOG_PREFIX,
441
+ suppressed,
428
442
  });
429
443
  // Check mode: exit 1 on drift (see reportCheckDrift).
430
444
  if (dryRun) {