@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.
- package/.bkit/README.md +10 -14
- package/.bkit/core/.bkit/README.md +9 -13
- package/.bkit/core/.bkit/cloud.md +15 -24
- package/.bkit/core/.bkit/comparison.md +4 -1
- package/.bkit/core/.bkit/install.md +54 -149
- package/.bkit/core/.bkit/jsonl.md +5 -5
- package/.bkit/core/.bkit/templates.md +2 -3
- package/.bkit/core/.bkit/workflows.md +7 -3
- package/.bkit/core/engine/checks/after/auth.ts +16 -114
- package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
- package/.bkit/core/engine/checks/after/index.ts +156 -182
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/before/env.ts +4 -18
- package/.bkit/core/engine/checks/before/files.ts +2 -0
- package/.bkit/core/engine/cli.ts +4 -8
- package/.bkit/core/engine/commands/install/doctor.ts +9 -2
- package/.bkit/core/engine/commands/install/install.ts +24 -2
- package/.bkit/core/engine/commands/install/uninstall.ts +23 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
- package/.bkit/core/engine/commands/lib.ts +4 -3
- package/.bkit/core/engine/install/cloud-env.ts +0 -1
- package/.bkit/core/engine/install/modules/cloud.ts +2 -3
- package/.bkit/core/engine/install/modules/core.ts +33 -13
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/template-copies.ts +1 -1
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/workflows/bkit-debug.md +19 -12
- package/.bkit/shared/.bkit/.env.example +2 -24
- package/.bkit/shared/docs/deployments.md +2 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/gitignore +5 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
- package/.bkit/templates/.cursor/Dockerfile +1 -1
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/renovate.json5 +0 -15
- package/.bkit/templates/.github/workflows/bkit-ci.yml +2 -22
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +0 -5
- package/CHANGELOG.md +17 -0
- package/README.md +5 -6
- package/dist/checks/after/auth.js +16 -108
- package/dist/checks/after/ci-yml.js +30 -67
- package/dist/checks/after/index.js +136 -152
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/before/env.js +4 -14
- package/dist/checks/before/files.js +2 -0
- package/dist/cli.js +4 -8
- package/dist/commands/install/doctor.js +4 -2
- package/dist/commands/install/install.js +16 -2
- package/dist/commands/install/uninstall.js +24 -0
- package/dist/commands/install/upgrade.js +14 -3
- package/dist/commands/lib.js +4 -3
- package/dist/install/cloud-env.js +0 -1
- package/dist/install/modules/cloud.js +2 -3
- package/dist/install/modules/core.js +33 -13
- package/dist/install/payload-links.js +119 -0
- package/dist/install/template-copies.js +1 -1
- package/dist/shared/egress.js +1 -1
- package/package.json +2 -2
- package/.bkit/core/engine/checks/after/vercel.ts +0 -101
- 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
|
|
71
|
-
* Returns `""` when findings
|
|
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
|
-
*
|
|
77
|
-
*
|
|
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(
|
|
80
|
-
|
|
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(
|
|
87
|
-
lines.push(`[bkit] Post-install checklist (${total} item${total === 1 ? "" : "s"})`);
|
|
118
|
+
lines.push("");
|
|
88
119
|
lines.push(banner);
|
|
89
|
-
lines.push(
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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(
|
|
98
|
-
lines.push(`
|
|
99
|
-
lines.push(`
|
|
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
|
-
|
|
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
|
-
*
|
|
116
|
-
*
|
|
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(
|
|
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
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
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(
|
|
190
|
-
|
|
191
|
-
|
|
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
|
|
209
|
-
*
|
|
210
|
-
*
|
|
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
|
-
|
|
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}\\]
|
|
222
|
-
const
|
|
223
|
-
if (
|
|
224
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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;
|
package/.bkit/core/engine/cli.ts
CHANGED
|
@@ -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.
|
|
542
|
-
|
|
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,
|
|
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
|
}
|