@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
@@ -16,24 +16,11 @@ import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.j
16
16
  import { TEMPLATES_POINTER } from "../../install/template-copies.js";
17
17
  import { detectManagedStale } from "./managed.js";
18
18
  import {
19
- AGENT_INLINE_SOURCE_GUIDANCE,
20
- BKIT_GH_TOKEN_INSTALL_MISSING_ACTION,
21
- BKIT_GH_TOKEN_INSTALL_UNKNOWN_ACTION,
22
19
  buildCloudDashboardsAdvisory,
23
20
  detectCiRouterSecrets,
24
- detectGhSecret,
25
- detectNpmrcAuth,
26
- detectNpmrcAuthTokenLine,
27
21
  detectShellGhMcpToken,
28
- detectShellToken,
29
22
  hasGithubMcpServer,
30
23
  } from "./auth.js";
31
- import {
32
- VERCEL_MISSING_ACTION,
33
- detectVercelEnv,
34
- detectVercelInstallCommandMissingAuth,
35
- detectVercelProject,
36
- } from "./vercel.js";
37
24
  import {
38
25
  buildCloudSetupAdvisory,
39
26
  buildGithubProjectAdvisory,
@@ -53,7 +40,6 @@ import {
53
40
  detectBkitCloudYmlAlwaysTrueGate,
54
41
  detectCiYmlCapstoneContractDrift,
55
42
  detectCiYmlMissingActionlint,
56
- detectCiYmlMissingTokenEnv,
57
43
  detectCiYmlRunInjection,
58
44
  detectGhaFloatingTags,
59
45
  detectRunLevelsNotComposed,
@@ -61,45 +47,104 @@ import {
61
47
  detectTestIntegrationEnv,
62
48
  detectTurboIntegrationInputs,
63
49
  } from "./ci-yml.js";
50
+ import { type SuppressionNote, type SuppressionReporter } from "./suppression.js";
64
51
 
65
52
  // ---------------------------------------------------------------------------
66
53
  // formatChecklist — pure renderer
67
54
  // ---------------------------------------------------------------------------
68
55
 
56
+ // ---------------------------------------------------------------------------
57
+ // Shared advisory text — the console checklist (`formatChecklist`) and the
58
+ // `.bkit/advisories.md` artifact (`renderAdvisoriesMarkdown`) render the SAME
59
+ // words; only the medium decoration differs (`#` / `**` / `>` in markdown, the
60
+ // `===` banner in the console). One source, so the two can never drift.
61
+ // ---------------------------------------------------------------------------
62
+
63
+ /** Title line, shared by both surfaces. */
64
+ export const ADVISORIES_TITLE = "bkit advisories";
65
+
66
+ /** Agent instruction line, shared by both surfaces. */
67
+ export const ADVISORIES_AGENT_INSTRUCTIONS =
68
+ "INSTRUCTIONS FOR AN AI AGENT — copy this file (or specific items) into a coding assistant to apply each item. Each ACTION is self-contained.";
69
+
70
+ /** `N finding(s) — B blocker, A advisory.` — the summary both surfaces print. */
71
+ export function advisoriesSummary(findings: PreflightFinding[]): string {
72
+ const blockerCount = findings.filter((f) => f.severity === "blocker").length;
73
+ const advisoryCount = findings.filter((f) => f.severity === "advisory").length;
74
+ return `${findings.length} finding(s) — ${blockerCount} blocker, ${advisoryCount} advisory.`;
75
+ }
76
+
77
+ /**
78
+ * The suppressed-advisory lines both surfaces print. One entry per opt-out, so a package
79
+ * that dismissed an advisory is never silently invisible. Returns `[]` when nothing was
80
+ * suppressed — callers then emit no such block.
81
+ */
82
+ export function suppressedNoteLines(suppressed: SuppressionNote[]): string[] {
83
+ if (suppressed.length === 0) return [];
84
+ const n = suppressed.length;
85
+ return [
86
+ `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.ignoreAdvisories:`,
87
+ ...suppressed.map((note) => `- ${note.id} (${note.scope})`),
88
+ ];
89
+ }
90
+
69
91
  /**
70
- * Format a list of findings into the post-install checklist banner.
71
- * Returns `""` when findings is empty — callers can `if (banner)` to stay silent.
72
- * No console.log inside — caller logs.
92
+ * Format a list of findings into the post-install console checklist.
93
+ * Returns `""` when findings AND suppressed are both empty — callers can `if (banner)` to
94
+ * stay silent. No console.log inside — caller logs.
95
+ *
96
+ * Same content as `renderAdvisoriesMarkdown`: title, summary, agent instructions
97
+ * and template pointer are the shared strings; only the separators differ from
98
+ * the markdown form.
73
99
  *
74
100
  * Format per finding:
75
101
  * --- i/N [severity] id ---
76
- * DETECT: ...
77
- * ACTION: ...
102
+ * Detect: ...
103
+ * Action: ...
104
+ *
105
+ * `suppressed` is appended as its own block (see `suppressedNoteLines`) — a dismissed
106
+ * advisory stays visible even when nothing else fired.
78
107
  */
79
- export function formatChecklist(findings: PreflightFinding[]): string {
80
- if (findings.length === 0) return "";
108
+ export function formatChecklist(
109
+ findings: PreflightFinding[],
110
+ suppressed: SuppressionNote[] = [],
111
+ ): string {
112
+ if (findings.length === 0 && suppressed.length === 0) return "";
81
113
 
82
114
  const banner = "=".repeat(58);
83
115
  const total = findings.length;
84
116
  const lines: string[] = [];
85
117
 
86
- lines.push(`\n${banner}`);
87
- lines.push(`[bkit] Post-install checklist (${total} item${total === 1 ? "" : "s"})`);
118
+ lines.push("");
88
119
  lines.push(banner);
89
- lines.push(
90
- "\nINSTRUCTIONS FOR AN AI AGENT — copy this entire block into a\n" +
91
- "coding assistant to apply each item. Each ACTION is self-contained.\n" +
92
- `\n${TEMPLATES_POINTER}\n`,
93
- );
120
+ lines.push(ADVISORIES_TITLE);
121
+ lines.push(banner);
122
+ lines.push("");
123
+ if (findings.length > 0) {
124
+ lines.push(advisoriesSummary(findings));
125
+ lines.push("");
126
+ lines.push(ADVISORIES_AGENT_INSTRUCTIONS);
127
+ lines.push("");
128
+ lines.push(TEMPLATES_POINTER);
129
+ lines.push("");
130
+ }
94
131
 
95
132
  for (let i = 0; i < findings.length; i++) {
96
133
  const f = findings[i]!;
97
- lines.push(`\n--- ${i + 1}/${total} [${f.severity}] ${f.id} ---`);
98
- lines.push(`DETECT: ${f.detect}`);
99
- lines.push(`ACTION: ${f.action}`);
134
+ lines.push(`--- ${i + 1}/${total} [${f.severity}] ${f.id} ---`);
135
+ lines.push(`Detect: ${f.detect}`);
136
+ lines.push(`Action: ${f.action}`);
137
+ lines.push("");
100
138
  }
101
139
 
102
- lines.push(`\n${banner}\n`);
140
+ const suppressedLines = suppressedNoteLines(suppressed);
141
+ if (suppressedLines.length > 0) {
142
+ lines.push(...suppressedLines);
143
+ lines.push("");
144
+ }
145
+
146
+ lines.push(banner);
147
+ lines.push("");
103
148
 
104
149
  return lines.join("\n");
105
150
  }
@@ -112,12 +157,14 @@ export type AdvisoriesMode = "install" | "check" | "doctor";
112
157
 
113
158
  /**
114
159
  * Render findings as a markdown artifact suitable for `.bkit/advisories.md`.
115
- * Mirrors `formatChecklist` content but in markdown form so the file can be
116
- * referenced and revisited between installs. Overwritten on every run.
160
+ * Renders the SAME content as `formatChecklist` (shared title, summary, agent
161
+ * instructions, template pointer and suppressed block) in markdown form, so the file can
162
+ * be referenced and revisited between installs. Overwritten on every run.
117
163
  */
118
164
  export function renderAdvisoriesMarkdown(
119
165
  findings: PreflightFinding[],
120
166
  opts: { mode: AdvisoriesMode; version: string },
167
+ suppressed: SuppressionNote[] = [],
121
168
  ): string {
122
169
  const lines: string[] = [];
123
170
  // This is a generated, gitignored artifact — not authored prose. Advisory
@@ -127,7 +174,7 @@ export function renderAdvisoriesMarkdown(
127
174
  // skip the husky hooks fail on a file the consumer cannot edit.
128
175
  lines.push("<!-- vale off -->");
129
176
  lines.push("");
130
- lines.push("# bkit advisories");
177
+ lines.push(`# ${ADVISORIES_TITLE}`);
131
178
  lines.push("");
132
179
  lines.push(`_bkit: ${opts.version}_ `);
133
180
  lines.push(`_Mode: ${opts.mode}_`);
@@ -137,22 +184,20 @@ export function renderAdvisoriesMarkdown(
137
184
  );
138
185
  lines.push("");
139
186
 
140
- if (findings.length === 0) {
187
+ if (findings.length === 0 && suppressed.length === 0) {
141
188
  lines.push("**No advisories.** Last run was clean.");
142
189
  lines.push("");
143
190
  return lines.join("\n");
144
191
  }
145
192
 
146
- const blockerCount = findings.filter((f) => f.severity === "blocker").length;
147
- const advisoryCount = findings.filter((f) => f.severity === "advisory").length;
148
- lines.push(`${findings.length} finding(s) — ${blockerCount} blocker, ${advisoryCount} advisory.`);
149
- lines.push("");
150
- lines.push(
151
- "> INSTRUCTIONS FOR AN AI AGENT — copy this file (or specific items) into a coding assistant to apply each item. Each ACTION is self-contained.",
152
- );
153
- lines.push("");
154
- lines.push(`> ${TEMPLATES_POINTER}`);
155
- lines.push("");
193
+ if (findings.length > 0) {
194
+ lines.push(advisoriesSummary(findings));
195
+ lines.push("");
196
+ lines.push(`> ${ADVISORIES_AGENT_INSTRUCTIONS}`);
197
+ lines.push("");
198
+ lines.push(`> ${TEMPLATES_POINTER}`);
199
+ lines.push("");
200
+ }
156
201
 
157
202
  const total = findings.length;
158
203
  for (let i = 0; i < total; i++) {
@@ -165,6 +210,12 @@ export function renderAdvisoriesMarkdown(
165
210
  lines.push("");
166
211
  }
167
212
 
213
+ const suppressedLines = suppressedNoteLines(suppressed);
214
+ if (suppressedLines.length > 0) {
215
+ lines.push(...suppressedLines);
216
+ lines.push("");
217
+ }
218
+
168
219
  return lines.join("\n");
169
220
  }
170
221
 
@@ -180,16 +231,21 @@ export function writeAdvisoriesArtifact(
180
231
  mode: AdvisoriesMode;
181
232
  version: string;
182
233
  logPrefix: string;
234
+ suppressed?: SuppressionNote[];
183
235
  },
184
236
  ): void {
185
237
  const dir = path.join(opts.cwd, ".bkit");
186
238
  const filePath = path.join(dir, "advisories.md");
187
239
  try {
188
240
  fs.mkdirSync(dir, { recursive: true });
189
- const content = renderAdvisoriesMarkdown(findings, {
190
- mode: opts.mode,
191
- version: opts.version,
192
- });
241
+ const content = renderAdvisoriesMarkdown(
242
+ findings,
243
+ {
244
+ mode: opts.mode,
245
+ version: opts.version,
246
+ },
247
+ opts.suppressed ?? [],
248
+ );
193
249
  fs.writeFileSync(filePath, content);
194
250
  const n = findings.length;
195
251
  console.log(`${opts.logPrefix} Wrote .bkit/advisories.md (${n} item${n === 1 ? "" : "s"}).`);
@@ -205,23 +261,54 @@ export function writeAdvisoriesArtifact(
205
261
  // ---------------------------------------------------------------------------
206
262
 
207
263
  /**
208
- * Read the bkit CHANGELOG.md (from the package root) and extract the section
209
- * header for `version`. Returns a formatted version-delta string for display
210
- * in post-install output, or null if CHANGELOG.md is absent or version not found.
264
+ * Read the bkit CHANGELOG.md (from the package root) and extract the release
265
+ * delta for `version`: the header line plus the section's lead summary (the
266
+ * prose before the first `###` sub-heading). Returns a formatted string for
267
+ * display in post-install output, or null if CHANGELOG.md is absent or the
268
+ * version is not found.
211
269
  *
212
270
  * Version header format in CHANGELOG.md: `## [X.Y.Z] — YYYY-MM-DD`
271
+ *
272
+ * Bounded on purpose: an install/check banner must not dump a whole release
273
+ * section. When a section has no lead paragraph the sub-heading names stand in,
274
+ * so the banner is never an empty header.
213
275
  */
214
276
  export function readChangelogVersionDelta(version: string): string | null {
215
277
  try {
216
278
  const changelogPath = path.join(getPkgRoot(), "CHANGELOG.md");
217
279
  if (!fs.existsSync(changelogPath)) return null;
218
280
  const content = fs.readFileSync(changelogPath, "utf-8");
219
- // Find the header for this version
281
+ const lines = content.split(/\r?\n/);
282
+ // Find the header line for this version.
220
283
  const versionEscaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
221
- const headerRe = new RegExp(`^## \\[${versionEscaped}\\][^\n]*`, "m");
222
- const match = content.match(headerRe);
223
- if (!match) return null;
224
- return `[bkit] What's new in v${version}: ${match[0].replace(/^## /, "")}`;
284
+ const headerRe = new RegExp(`^## \\[${versionEscaped}\\]`);
285
+ const start = lines.findIndex((line) => headerRe.test(line));
286
+ if (start === -1) return null;
287
+
288
+ // The section runs to the next top-level `## ` header (or EOF).
289
+ let end = lines.length;
290
+ for (let i = start + 1; i < lines.length; i++) {
291
+ if (/^## /.test(lines[i])) {
292
+ end = i;
293
+ break;
294
+ }
295
+ }
296
+ const section = lines.slice(start + 1, end);
297
+ const header = lines[start].replace(/^## /, "");
298
+
299
+ // Lead summary: the prose between the header and the first `###` sub-heading.
300
+ const firstSub = section.findIndex((line) => /^### /.test(line));
301
+ const leadEnd = firstSub === -1 ? section.length : firstSub;
302
+ let summary = section.slice(0, leadEnd).join("\n").trim();
303
+ if (!summary) {
304
+ summary = section
305
+ .filter((line) => /^### /.test(line))
306
+ .map((line) => line.replace(/^### /, "").trim())
307
+ .join(", ");
308
+ }
309
+
310
+ const headline = `[bkit] What's new in v${version}: ${header}`;
311
+ return summary ? `${headline}\n${summary}` : headline;
225
312
  } catch {
226
313
  return null;
227
314
  }
@@ -232,7 +319,7 @@ export function readChangelogVersionDelta(version: string): string | null {
232
319
  // ---------------------------------------------------------------------------
233
320
 
234
321
  /**
235
- * Re-run token-surface + bkit-ci.yml + vale-sync detectors after writes.
322
+ * Re-run credential + bkit-ci.yml + vale-sync detectors after writes.
236
323
  *
237
324
  * - Intra-phase dedup: Phase 3 findings are deduped by id (first occurrence wins).
238
325
  * - Cross-phase dedup: Phase 3 wins on id conflict (re-detection is more accurate).
@@ -242,12 +329,20 @@ export function readChangelogVersionDelta(version: string): string | null {
242
329
  * same advisory set against the same filesystem state regardless of caller.
243
330
  *
244
331
  * cwd defaults to process.cwd().
332
+ *
333
+ * Pass `suppressed` to collect the advisories a package opted out of via
334
+ * `bkit.ignoreAdvisories` (one note per id + owning package); the caller renders them with
335
+ * `suppressedNoteLines` so a dismissal stays visible. Omitted by callers that do not render.
245
336
  */
246
337
  export function runPostInstallCheck(
247
338
  preflightAdvisories: PreflightFinding[],
248
339
  cwd: string = process.cwd(),
340
+ suppressed?: SuppressionNote[],
249
341
  ): PreflightFinding[] {
250
342
  const phase3: PreflightFinding[] = [];
343
+ const onSuppressed: SuppressionReporter | undefined = suppressed
344
+ ? (note) => suppressed.push(note)
345
+ : undefined;
251
346
 
252
347
  // Managed-version marker gate — in `bkit check`, a blocker on main/dev (or a PR into
253
348
  // them) and a non-blocking advisory on feature branches when any stamped file's marker
@@ -255,29 +350,6 @@ export function runPostInstallCheck(
255
350
  const managedStale = detectManagedStale(cwd);
256
351
  if (managedStale) phase3.push(managedStale);
257
352
 
258
- // Shell token
259
- const shellStatus = detectShellToken();
260
- if (shellStatus === "missing") {
261
- phase3.push({
262
- id: "gh-bkit-token-unset-shell",
263
- severity: "advisory",
264
- detect: "BKIT_GH_TOKEN_INSTALL is not set in the shell environment (undefined).",
265
- action:
266
- "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" +
267
- AGENT_INLINE_SOURCE_GUIDANCE,
268
- });
269
- } else if (shellStatus === "empty") {
270
- phase3.push({
271
- id: "gh-bkit-token-empty-shell",
272
- severity: "advisory",
273
- detect:
274
- '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.',
275
- action:
276
- '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' +
277
- AGENT_INLINE_SOURCE_GUIDANCE,
278
- });
279
- }
280
-
281
353
  // BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server
282
354
  // (`Authorization: Bearer ${BKIT_GH_TOKEN}` in .mcp.json), which powers the entire
283
355
  // tracker + PR + Projects MCP surface. Only flags when a github MCP server is
@@ -305,100 +377,6 @@ export function runPostInstallCheck(
305
377
  }
306
378
  }
307
379
 
308
- // .npmrc auth
309
- const npmrcStatus = detectNpmrcAuth(cwd);
310
- if (npmrcStatus === "missing") {
311
- phase3.push({
312
- id: "npmrc-missing-gh-packages",
313
- severity: "advisory",
314
- detect: ".npmrc exists but is missing the required @cbartens registry mapping.",
315
- action:
316
- "Add this line to .npmrc at the repo root (the auth token is NOT stored here):\n\n" +
317
- " @cbartens:registry=https://npm.pkg.github.com\n\n" +
318
- "The token lives in pnpm's user-level config — write it once with:\n\n" +
319
- ' pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"\n\n' +
320
- "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.",
321
- });
322
- }
323
- // "unknown" (absent) → silent skip per spec
324
-
325
- // .npmrc auth-token line. The committed project .npmrc must NOT carry
326
- // `//npm.pkg.github.com/:_authToken=…`: pnpm >=10.34.3 401s on it AND it shadows the
327
- // user-level token written by `pnpm config set` (project config wins).
328
- if (detectNpmrcAuthTokenLine(cwd)) {
329
- phase3.push({
330
- id: "npmrc-authtoken-line",
331
- severity: "advisory",
332
- detect:
333
- ".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`.",
334
- action:
335
- "Remove the `//npm.pkg.github.com/:_authToken=…` line from .npmrc — keep ONLY the registry mapping:\n\n" +
336
- " @cbartens:registry=https://npm.pkg.github.com\n\n" +
337
- "Then write the token into pnpm's user-level config instead (CI does this in its install step):\n\n" +
338
- ' pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"\n\n' +
339
- "`pnpm config set` stores the shell-expanded literal token in pnpm's user-level config — version-proof across pnpm 10.x and 11.x.",
340
- });
341
- }
342
-
343
- // GH secret
344
- const ghSecretStatus = detectGhSecret();
345
- if (ghSecretStatus === "missing") {
346
- phase3.push({
347
- id: "gh-bkit-token-secret-missing",
348
- severity: "advisory",
349
- detect:
350
- "gh secret list confirms BKIT_GH_TOKEN_INSTALL secret is NOT set on this GitHub repo.",
351
- action: BKIT_GH_TOKEN_INSTALL_MISSING_ACTION,
352
- });
353
- } else if (ghSecretStatus === "unknown") {
354
- phase3.push({
355
- id: "gh-bkit-token-secret-unknown",
356
- severity: "advisory",
357
- detect:
358
- "Could not verify BKIT_GH_TOKEN_INSTALL secret (gh CLI unavailable, unauthenticated, or not a GitHub repo).",
359
- action: BKIT_GH_TOKEN_INSTALL_UNKNOWN_ACTION,
360
- });
361
- }
362
-
363
- // Vercel env (only if a Vercel project is detected)
364
- if (detectVercelProject(cwd)) {
365
- const previewStatus = detectVercelEnv("preview", cwd);
366
- if (previewStatus === "missing") {
367
- phase3.push({
368
- id: "vercel-env-missing-preview",
369
- severity: "advisory",
370
- detect:
371
- "vercel.json detected but BKIT_GH_TOKEN_INSTALL is absent from Vercel preview environment.",
372
- action: VERCEL_MISSING_ACTION,
373
- });
374
- }
375
- const productionStatus = detectVercelEnv("production", cwd);
376
- if (productionStatus === "missing") {
377
- phase3.push({
378
- id: "vercel-env-missing-production",
379
- severity: "advisory",
380
- detect:
381
- "vercel.json detected but BKIT_GH_TOKEN_INSTALL is absent from Vercel production environment.",
382
- action: VERCEL_MISSING_ACTION,
383
- });
384
- }
385
- // "unknown" → silent skip (CLI absent / unauthed)
386
-
387
- // Vercel installCommand auth. The env var alone is not enough: a registry-only .npmrc
388
- // carries no token on pnpm
389
- // >=10.34.3 and Vercel cannot run a pre-install shell step, so each vercel.json must
390
- // authenticate via its installCommand or the @cbartens/bkit download 401s.
391
- const vercelNoAuth = detectVercelInstallCommandMissingAuth(cwd);
392
- if (vercelNoAuth.length > 0) {
393
- phase3.push({
394
- id: "vercel-installcommand-missing-auth",
395
- severity: "advisory",
396
- 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.`,
397
- action: VERCEL_MISSING_ACTION,
398
- });
399
- }
400
- }
401
-
402
380
  // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
403
381
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
404
382
  // protection on main restricting merges to PRs from dev.
@@ -467,10 +445,6 @@ export function runPostInstallCheck(
467
445
  const cloudDashboardsAdvisory = buildCloudDashboardsAdvisory(cwd);
468
446
  if (cloudDashboardsAdvisory) phase3.push(cloudDashboardsAdvisory);
469
447
 
470
- // bkit-ci.yml missing token env
471
- const ciYml = detectCiYmlMissingTokenEnv(cwd);
472
- if (ciYml) phase3.push(ciYml);
473
-
474
448
  // GHA action SHA pinning (KN-3). Updater configs are consumer-owned examples.
475
449
  const gha = detectGhaFloatingTags(cwd);
476
450
  if (gha) phase3.push(gha);
@@ -500,7 +474,7 @@ export function runPostInstallCheck(
500
474
 
501
475
  // @live/@smoke-tagged tests whose owning package declares no test:live/test:smoke
502
476
  // script — "no CI home".
503
- const taggedNoHome = detectTaggedTestsWithoutCiHome(cwd);
477
+ const taggedNoHome = detectTaggedTestsWithoutCiHome(cwd, onSuppressed);
504
478
  if (taggedNoHome) phase3.push(taggedNoHome);
505
479
 
506
480
  // bkit-stub sentinels in shipped templates — one advisory per still-commented stub.
@@ -510,7 +484,7 @@ export function runPostInstallCheck(
510
484
  for (const f of detectTurboIntegrationInputs(cwd)) phase3.push(f);
511
485
 
512
486
  // test:integration runtime env (KN-23 false-confidence loop).
513
- const integrationEnv = detectTestIntegrationEnv(cwd);
487
+ const integrationEnv = detectTestIntegrationEnv(cwd, onSuppressed);
514
488
  if (integrationEnv) phase3.push(integrationEnv);
515
489
 
516
490
  // Consumer composed run-levels on bkit primitives (else docs/deployments.md matrix is doc-only).
@@ -0,0 +1,53 @@
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
+
14
+ import { readPackageJson } from "../../shared/package-json.js";
15
+
16
+ /** One advisory a package opted out of. */
17
+ export interface SuppressionNote {
18
+ /** Advisory id the package opted out of. */
19
+ id: string;
20
+ /** Repo-relative package directory the opt-out was read from (`"."` = repo root). */
21
+ scope: string;
22
+ }
23
+
24
+ /** Sink a detector calls once per suppressed finding. */
25
+ export type SuppressionReporter = (note: SuppressionNote) => void;
26
+
27
+ /**
28
+ * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` key that is
29
+ * absent or not an object, and an `ignoreAdvisories` that is absent or not an array all
30
+ * yield no ids — never a throw.
31
+ */
32
+ export function ignoredAdvisoryIds(dir: string): Set<string> {
33
+ const read = readPackageJson(dir);
34
+ if (!read.ok) return new Set();
35
+ const bkit = read.pkg.bkit;
36
+ if (typeof bkit !== "object" || bkit === null || Array.isArray(bkit)) return new Set();
37
+ const list = (bkit as { ignoreAdvisories?: unknown }).ignoreAdvisories;
38
+ if (!Array.isArray(list)) return new Set();
39
+ return new Set(list.filter((id): id is string => typeof id === "string"));
40
+ }
41
+
42
+ /**
43
+ * True when `dir/package.json` opts out of `id` AND the finding resolved to advisory
44
+ * severity. `blocker` returns false unconditionally — a blocker is not suppressible.
45
+ */
46
+ export function isAdvisorySuppressed(
47
+ dir: string,
48
+ id: string,
49
+ severity: "blocker" | "advisory",
50
+ ): boolean {
51
+ if (severity !== "advisory") return false;
52
+ return ignoredAdvisoryIds(dir).has(id);
53
+ }
@@ -27,10 +27,7 @@ export function detectMissingDotenv(
27
27
  const envPath = path.join(cwd, ".bkit", ".env");
28
28
  if (!fs.existsSync(examplePath)) return null;
29
29
  if (fs.existsSync(envPath)) return null;
30
- const tokens =
31
- tracker === "linear"
32
- ? "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL, BKIT_LINEAR_API_KEY"
33
- : "BKIT_GH_TOKEN, BKIT_GH_TOKEN_INSTALL";
30
+ const tokens = tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
34
31
  return {
35
32
  id: "mcp-env-missing-dotenv",
36
33
  severity: "advisory",
@@ -71,11 +68,6 @@ export function detectBlankDotenvKeys(
71
68
  description:
72
69
  "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write)",
73
70
  },
74
- {
75
- key: "BKIT_GH_TOKEN_INSTALL",
76
- description:
77
- "classic PAT with read:packages scope for authenticating to the GitHub Packages npm registry (@cbartens/* packages)",
78
- },
79
71
  // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
80
72
  ...(tracker === "linear"
81
73
  ? [
@@ -130,14 +122,8 @@ export function detectDirenvMissing(
130
122
  const result = spawnSync("which", ["direnv"], { encoding: "utf-8" });
131
123
  if (result.status === 0 && result.stdout.trim()) return null;
132
124
  // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
133
- const editKeys =
134
- tracker === "linear"
135
- ? "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY"
136
- : "BKIT_GH_TOKEN_INSTALL, BKIT_GH_TOKEN";
137
- const exportKeys =
138
- tracker === "linear"
139
- ? "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY"
140
- : "BKIT_GH_TOKEN_INSTALL / BKIT_GH_TOKEN";
125
+ const editKeys = tracker === "linear" ? "BKIT_GH_TOKEN, BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
126
+ const exportKeys = tracker === "linear" ? "BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
141
127
  return {
142
128
  id: "mcp-env-direnv-missing",
143
129
  severity: "advisory",
@@ -194,7 +180,7 @@ export function detectDirenvNotAllowed(
194
180
  severity: "advisory",
195
181
  detect:
196
182
  "direnv is installed but the .envrc in this repo is blocked. .bkit/.env is not being auto-loaded.",
197
- 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.`,
183
+ 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.`,
198
184
  };
199
185
  }
200
186
  return null;
@@ -33,6 +33,8 @@ const BKIT_GITIGNORE_LINES = [
33
33
  ".husky/_",
34
34
  ".bkit/advisories.md",
35
35
  ".bkit/.env",
36
+ ".bkit/core",
37
+ ".bkit/shared",
36
38
  ];
37
39
 
38
40
  export function detectGitignoreBlockDuplicates(cwd: string): PreflightFinding | null {
@@ -538,8 +538,9 @@ Usage:
538
538
  Hosts compose: --claude --cursor --codex --opencode=<provider>.
539
539
  bkit check Dry-run — drift-check everything already installed (no
540
540
  module flags). Exits 1 when a managed file needs
541
- re-rendering. Templates (.bkit/templates/) are never
542
- drift-checked once copied — the copy is yours. The CI gate.
541
+ re-rendering. Copies under .bkit/templates/ are refreshed by
542
+ install/upgrade and checked for staleness — adopt one by
543
+ copying it elsewhere; that copy is yours. The CI gate.
543
544
  bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
544
545
  Upgrade everything installed (no module flags). Diffs old
545
546
  vs new templates; conflict list emitted to stderr. Use
@@ -554,7 +555,7 @@ Usage:
554
555
  No flags = full removal — ALL modules incl. opt-in add-ons
555
556
  (cloud/opencode) + core. Consumer-owned updater configs
556
557
  (renovate.json5, dependabot.yml, bkit-renovate.yml) are left in place. Consumer-modified
557
- files, the docs/ payload, and generated artefacts
558
+ files, your own files under docs/, and generated artefacts
558
559
  (.bkit/advisories.md, .bkit/friction.jsonl) are preserved (use
559
560
  --nuke to force-remove manifest-listed files). Target with the
560
561
  same module flags as install (e.g. uninstall --claude); a
@@ -704,11 +705,6 @@ macOS GUI-isolation note (launchctl fallback):
704
705
  launchd template set (see \`.bkit/templates.md\` § Launchd GUI environment). Rotation
705
706
  then needs no re-bootstrap — prefer \`bkit cursor\` / \`bkit opencode\` for the dynamic model.
706
707
 
707
- Consumer CI auth:
708
- Set BKIT_GH_TOKEN_INSTALL in GitHub Actions secrets (classic PAT with read:packages scope —
709
- fine-grained PATs are not currently supported by GitHub Packages npm registry).
710
- See README.md ## Consumer CI auth for setup steps.
711
-
712
708
  Docs: https://github.com/cbartens/bkit/blob/main/README.md` + commandsUsage(),
713
709
  );
714
710
  }