@cbartens/bkit 5.2.1 → 5.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +1 -1
- package/.bkit/core/.agents/context.md +2 -2
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +7 -1
- package/.bkit/core/.bkit/comparison.md +114 -45
- package/.bkit/core/.bkit/install.md +8 -5
- package/.bkit/core/.bkit/jsonl.md +3 -3
- package/.bkit/core/.bkit/prompts.md +6 -5
- package/.bkit/core/.bkit/providers.md +5 -4
- package/.bkit/core/.bkit/templates.md +11 -10
- package/.bkit/core/.bkit/workflows.md +8 -6
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +5 -1
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +6 -3
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-database.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +6 -3
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +6 -3
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +16 -12
- package/.bkit/core/docs/templates/bkit-audit-models.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +6 -3
- package/.bkit/core/docs/templates/bkit-audit-repo.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-security.md +6 -3
- package/.bkit/core/docs/templates/bkit-audit-slop.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-testing.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +5 -2
- package/.bkit/core/docs/templates/bkit-plan.md +1 -1
- package/.bkit/core/engine/checks/after/index.ts +2 -2
- package/.bkit/core/engine/commands/install/check.ts +3 -11
- package/.bkit/core/engine/commands/install/doctor.ts +2 -3
- package/.bkit/core/engine/commands/install/install.ts +44 -11
- package/.bkit/core/engine/commands/install/uninstall.ts +60 -44
- package/.bkit/core/engine/commands/install/upgrade.ts +8 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +13 -4
- package/.bkit/core/engine/install/hosts.ts +14 -4
- package/.bkit/core/engine/install/manifest.ts +2 -2
- package/.bkit/core/engine/install/modules/core.ts +9 -6
- package/.bkit/core/engine/ledgers/telemetry.ts +3 -4
- package/.bkit/core/hooks/guardrails-read.js +4 -9
- package/.bkit/core/hooks/guardrails-tiers.js +312 -28
- package/.bkit/core/prompts/bkit-audit-generate.md +19 -5
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.opencode/opencode.json +21 -1
- package/.bkit/shared/docs/deployments.md +14 -0
- package/.bkit/templates/.github/workflows/bkit-ci.yml +9 -0
- package/.bkit/templates/context/bkit-cloudrun.md +28 -19
- package/.bkit/templates/context/bkit-expo.md +30 -13
- package/.bkit/templates/context/bkit-inngest.md +54 -17
- package/.bkit/templates/context/bkit-resend.md +36 -8
- package/.bkit/templates/context/bkit-sentry.md +11 -4
- package/.bkit/templates/context/bkit-stripe.md +39 -22
- package/.bkit/templates/context/bkit-supabase.md +45 -20
- package/.bkit/templates/context/bkit-vercel.md +45 -16
- package/.bkit/templates/scripts/ci/accepted-advisories.json +7 -0
- package/.bkit/templates/scripts/ci/check-dependency-audit.mjs +200 -0
- package/.bkit/templates/scripts/ci/check-dependency-audit.test.mjs +127 -0
- package/CHANGELOG.md +45 -0
- package/README.md +76 -20
- package/dist/checks/after/index.js +1 -1
- package/dist/commands/install/check.js +3 -15
- package/dist/commands/install/doctor.js +2 -1
- package/dist/commands/install/install.js +42 -8
- package/dist/commands/install/uninstall.js +52 -45
- package/dist/commands/install/upgrade.js +8 -2
- package/dist/commands/workflow/branches.js +13 -5
- package/dist/install/hosts.js +11 -4
- package/dist/install/manifest.js +2 -2
- package/dist/install/modules/core.js +9 -7
- package/package.json +1 -1
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Example. Copy into scripts/ci/ and own it. bkit install does not write this file
|
|
3
|
+
// and does not overwrite a copy.
|
|
4
|
+
/**
|
|
5
|
+
* check-dependency-audit.mjs — the dependency-audit gate.
|
|
6
|
+
*
|
|
7
|
+
* Runs `pnpm audit --json` and reds when a blocking advisory (by default high or critical)
|
|
8
|
+
* reaches the lockfile without an acceptance in the registry. An acceptance is a row naming
|
|
9
|
+
* the advisory, a reason and an expiry date. The guard reds when:
|
|
10
|
+
* - a blocking advisory has no acceptance (a new advisory),
|
|
11
|
+
* - an acceptance has expired, or runs longer than its severity allows (`blocking` days),
|
|
12
|
+
* - an acceptance names an advisory the audit no longer reports (a stale row),
|
|
13
|
+
* - a row carries no advisory, no reason, or no `YYYY-MM-DD` expiry, or repeats one,
|
|
14
|
+
* - the audit cannot run or prints no report (fails closed; never green on no answer).
|
|
15
|
+
*
|
|
16
|
+
* pnpm's own `auditConfig.ignoreGhsas` ignores an advisory forever and records no reason;
|
|
17
|
+
* the registry makes every exception say why and come back for review.
|
|
18
|
+
*
|
|
19
|
+
* Reads pnpm's report shape (`advisories`: id → { github_advisory_id, severity, module_name,
|
|
20
|
+
* patched_versions, findings }). Another package manager → adapt `blockingFindings()`.
|
|
21
|
+
*
|
|
22
|
+
* Usage: node scripts/ci/check-dependency-audit.mjs [--registry=<file>] [--report=<file>]
|
|
23
|
+
* --report reads a saved `pnpm audit --json` instead of running the audit.
|
|
24
|
+
* Exit: 0 = every blocking advisory accepted and every row live, 1 = drift or no report.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
import { spawnSync } from "node:child_process";
|
|
28
|
+
import fs from "node:fs";
|
|
29
|
+
import path from "node:path";
|
|
30
|
+
import { fileURLToPath } from "node:url";
|
|
31
|
+
import { parseArgs } from "node:util";
|
|
32
|
+
|
|
33
|
+
/** Severity → the most days an acceptance may run. Severities not listed never block. */
|
|
34
|
+
export const DEFAULT_BLOCKING = { critical: 7, high: 30 };
|
|
35
|
+
|
|
36
|
+
const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
37
|
+
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
38
|
+
|
|
39
|
+
/** `YYYY-MM-DD` of a Date, in UTC. */
|
|
40
|
+
export function isoDay(date) {
|
|
41
|
+
return date.toISOString().slice(0, 10);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Whole days from `from` to `to`, both `YYYY-MM-DD`. */
|
|
45
|
+
function daysBetween(from, to) {
|
|
46
|
+
return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / DAY_MS);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* The blocking advisories in a pnpm audit report, one per advisory id.
|
|
51
|
+
* @returns {Array<{advisory: string, severity: string, module: string, patched: string, versions: string[]}>}
|
|
52
|
+
*/
|
|
53
|
+
export function blockingFindings(report, blocking = DEFAULT_BLOCKING) {
|
|
54
|
+
const found = new Map();
|
|
55
|
+
for (const a of Object.values(report.advisories ?? {})) {
|
|
56
|
+
if (!(a.severity in blocking)) continue;
|
|
57
|
+
const advisory = a.github_advisory_id || String(a.id);
|
|
58
|
+
const prior = found.get(advisory);
|
|
59
|
+
const versions = (a.findings ?? []).map((f) => f.version);
|
|
60
|
+
if (prior) prior.versions.push(...versions);
|
|
61
|
+
else
|
|
62
|
+
found.set(advisory, {
|
|
63
|
+
advisory,
|
|
64
|
+
severity: a.severity,
|
|
65
|
+
module: a.module_name,
|
|
66
|
+
patched: a.patched_versions ?? "none",
|
|
67
|
+
versions,
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
return [...found.values()].sort((x, y) => x.advisory.localeCompare(y.advisory));
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Compare the blocking findings with the registry's acceptances on `today` (`YYYY-MM-DD`).
|
|
75
|
+
* An acceptance is valid through its `expires` day.
|
|
76
|
+
*/
|
|
77
|
+
export function checkAcceptances(findings, registry, today) {
|
|
78
|
+
const blocking = registry.blocking ?? DEFAULT_BLOCKING;
|
|
79
|
+
const rows = registry.accepted ?? [];
|
|
80
|
+
const byAdvisory = new Map(findings.map((f) => [f.advisory, f]));
|
|
81
|
+
const invalid = [];
|
|
82
|
+
const expired = [];
|
|
83
|
+
const tooLong = [];
|
|
84
|
+
const stale = [];
|
|
85
|
+
const accepted = new Set();
|
|
86
|
+
|
|
87
|
+
for (const row of rows) {
|
|
88
|
+
if (!row.advisory || !row.reason || !DATE_RE.test(row.expires ?? "")) {
|
|
89
|
+
invalid.push({ row, why: "needs advisory, reason and a YYYY-MM-DD expires" });
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
if (accepted.has(row.advisory)) {
|
|
93
|
+
invalid.push({ row, why: "listed twice" });
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
accepted.add(row.advisory);
|
|
97
|
+
const finding = byAdvisory.get(row.advisory);
|
|
98
|
+
if (!finding) {
|
|
99
|
+
stale.push({ row });
|
|
100
|
+
continue;
|
|
101
|
+
}
|
|
102
|
+
if (row.expires < today) {
|
|
103
|
+
expired.push({ row, finding });
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
const limit = blocking[finding.severity];
|
|
107
|
+
if (daysBetween(today, row.expires) > limit) tooLong.push({ row, finding, limit });
|
|
108
|
+
}
|
|
109
|
+
const missing = findings.filter((f) => !accepted.has(f.advisory));
|
|
110
|
+
return { missing, invalid, expired, tooLong, stale };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Run `pnpm audit --json`, retrying when it prints no report (a registry blip).
|
|
115
|
+
* pnpm exits 1 whenever it finds an advisory, so the exit code is not the signal; the report is.
|
|
116
|
+
* @returns {object | null} the parsed report, or null after three attempts.
|
|
117
|
+
*/
|
|
118
|
+
function runAudit() {
|
|
119
|
+
for (let attempt = 1; attempt <= 3; attempt++) {
|
|
120
|
+
const res = spawnSync("pnpm", ["audit", "--json"], {
|
|
121
|
+
encoding: "utf-8",
|
|
122
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
123
|
+
});
|
|
124
|
+
let parseError = "";
|
|
125
|
+
try {
|
|
126
|
+
const report = JSON.parse(res.stdout);
|
|
127
|
+
if (report && typeof report.advisories === "object") return report;
|
|
128
|
+
} catch (err) {
|
|
129
|
+
parseError = `not JSON (${err.message}): `;
|
|
130
|
+
}
|
|
131
|
+
const tail = (res.stderr || res.stdout || "").trim().split("\n").slice(-3).join(" | ");
|
|
132
|
+
const detail = parseError + tail;
|
|
133
|
+
console.error(`::warning::dependency-audit: attempt ${attempt} printed no report — ${detail}`);
|
|
134
|
+
}
|
|
135
|
+
return null;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function main(argv) {
|
|
139
|
+
const { values } = parseArgs({
|
|
140
|
+
args: argv,
|
|
141
|
+
options: { registry: { type: "string" }, report: { type: "string" } },
|
|
142
|
+
strict: false,
|
|
143
|
+
});
|
|
144
|
+
const registryPath = values.registry ?? path.join("scripts", "ci", "accepted-advisories.json");
|
|
145
|
+
const reportPath = values.report ?? null;
|
|
146
|
+
|
|
147
|
+
const registry = fs.existsSync(registryPath)
|
|
148
|
+
? JSON.parse(fs.readFileSync(registryPath, "utf-8"))
|
|
149
|
+
: { accepted: [] };
|
|
150
|
+
const report = reportPath ? JSON.parse(fs.readFileSync(reportPath, "utf-8")) : runAudit();
|
|
151
|
+
if (!report || typeof report.advisories !== "object") {
|
|
152
|
+
console.error("::error::dependency-audit: the audit printed no report — failing closed");
|
|
153
|
+
process.exit(1);
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const findings = blockingFindings(report, registry.blocking ?? DEFAULT_BLOCKING);
|
|
157
|
+
const today = isoDay(new Date());
|
|
158
|
+
const { missing, invalid, expired, tooLong, stale } = checkAcceptances(findings, registry, today);
|
|
159
|
+
|
|
160
|
+
const fmt = (f) =>
|
|
161
|
+
` ${f.advisory} ${f.severity} ${f.module} ${f.versions.join(", ")} (patched: ${f.patched})`;
|
|
162
|
+
let failed = 0;
|
|
163
|
+
const fail = (rows, title, line) => {
|
|
164
|
+
if (!rows.length) return;
|
|
165
|
+
failed = 1;
|
|
166
|
+
console.error(`::error::dependency-audit: ${rows.length} ${title}:`);
|
|
167
|
+
for (const r of rows) console.error(line(r));
|
|
168
|
+
};
|
|
169
|
+
fail(
|
|
170
|
+
missing,
|
|
171
|
+
"blocking advisory(ies) with no acceptance — upgrade, or accept with a reason and expiry",
|
|
172
|
+
fmt,
|
|
173
|
+
);
|
|
174
|
+
fail(
|
|
175
|
+
expired,
|
|
176
|
+
"acceptance(s) expired — upgrade, or re-review and renew",
|
|
177
|
+
(r) => `${fmt(r.finding)} expired ${r.row.expires}`,
|
|
178
|
+
);
|
|
179
|
+
fail(
|
|
180
|
+
tooLong,
|
|
181
|
+
"acceptance(s) run past their severity's limit",
|
|
182
|
+
(r) => `${fmt(r.finding)} expires ${r.row.expires}, limit ${r.limit} days`,
|
|
183
|
+
);
|
|
184
|
+
fail(
|
|
185
|
+
stale,
|
|
186
|
+
"acceptance(s) for advisories the audit no longer reports — delete the row",
|
|
187
|
+
(r) => ` ${r.row.advisory} ${r.row.module ?? ""}`,
|
|
188
|
+
);
|
|
189
|
+
fail(invalid, "invalid row(s)", (r) => ` ${JSON.stringify(r.row)} — ${r.why}`);
|
|
190
|
+
if (!failed) {
|
|
191
|
+
console.error(
|
|
192
|
+
`[dependency-audit] ${findings.length} blocking advisory(ies), all accepted and in date`,
|
|
193
|
+
);
|
|
194
|
+
}
|
|
195
|
+
process.exit(failed);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
199
|
+
main(process.argv.slice(2));
|
|
200
|
+
}
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Example. Copy into scripts/ci/ and own it. bkit install does not write this file
|
|
3
|
+
// and does not overwrite a copy.
|
|
4
|
+
/**
|
|
5
|
+
* check-dependency-audit.test.mjs — unit tests for the dependency-audit gate.
|
|
6
|
+
*
|
|
7
|
+
* Pure Node, no runner: `node scripts/ci/check-dependency-audit.test.mjs`.
|
|
8
|
+
* Exit: 0 = all tests passed, 1 = at least one test failed.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import { blockingFindings, checkAcceptances } from "./check-dependency-audit.mjs";
|
|
12
|
+
|
|
13
|
+
let passed = 0;
|
|
14
|
+
let failed = 0;
|
|
15
|
+
|
|
16
|
+
function test(name, fn) {
|
|
17
|
+
try {
|
|
18
|
+
fn();
|
|
19
|
+
passed++;
|
|
20
|
+
console.log(` ok ${name}`);
|
|
21
|
+
} catch (err) {
|
|
22
|
+
failed++;
|
|
23
|
+
console.log(` FAIL ${name} — ${err.message}`);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function assert(cond, message) {
|
|
28
|
+
if (!cond) throw new Error(message);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const REPORT = {
|
|
32
|
+
advisories: {
|
|
33
|
+
1: {
|
|
34
|
+
id: 1,
|
|
35
|
+
github_advisory_id: "GHSA-crit",
|
|
36
|
+
severity: "critical",
|
|
37
|
+
module_name: "proxy-addr",
|
|
38
|
+
patched_versions: ">=2.0.8",
|
|
39
|
+
findings: [{ version: "2.0.7" }],
|
|
40
|
+
},
|
|
41
|
+
2: {
|
|
42
|
+
id: 2,
|
|
43
|
+
github_advisory_id: "GHSA-high",
|
|
44
|
+
severity: "high",
|
|
45
|
+
module_name: "braces",
|
|
46
|
+
patched_versions: "<0.0.0",
|
|
47
|
+
findings: [{ version: "3.0.3" }],
|
|
48
|
+
},
|
|
49
|
+
3: {
|
|
50
|
+
id: 3,
|
|
51
|
+
github_advisory_id: "GHSA-mod",
|
|
52
|
+
severity: "moderate",
|
|
53
|
+
module_name: "nanoid",
|
|
54
|
+
findings: [{ version: "3.3.7" }],
|
|
55
|
+
},
|
|
56
|
+
},
|
|
57
|
+
};
|
|
58
|
+
const TODAY = "2026-10-17";
|
|
59
|
+
const accept = (advisory, expires, extra = {}) => ({
|
|
60
|
+
advisory,
|
|
61
|
+
reason: "no patched release",
|
|
62
|
+
expires,
|
|
63
|
+
...extra,
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
test("keeps high and critical, drops moderate", () => {
|
|
67
|
+
const ids = blockingFindings(REPORT).map((f) => f.advisory);
|
|
68
|
+
assert(ids.join() === "GHSA-crit,GHSA-high", `got ${ids}`);
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
test("a custom blocking table changes what blocks", () => {
|
|
72
|
+
const ids = blockingFindings(REPORT, { critical: 7 }).map((f) => f.advisory);
|
|
73
|
+
assert(ids.join() === "GHSA-crit", `got ${ids}`);
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
test("an advisory with no acceptance is missing", () => {
|
|
77
|
+
const r = checkAcceptances(blockingFindings(REPORT), { accepted: [] }, TODAY);
|
|
78
|
+
assert(r.missing.length === 2, `missing ${r.missing.length}`);
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
test("accepted, in-date advisories pass", () => {
|
|
82
|
+
const registry = {
|
|
83
|
+
accepted: [accept("GHSA-crit", "2026-10-24"), accept("GHSA-high", "2026-11-16")],
|
|
84
|
+
};
|
|
85
|
+
const r = checkAcceptances(blockingFindings(REPORT), registry, TODAY);
|
|
86
|
+
const total = Object.values(r).reduce((n, rows) => n + rows.length, 0);
|
|
87
|
+
assert(total === 0, JSON.stringify(r));
|
|
88
|
+
});
|
|
89
|
+
|
|
90
|
+
test("an acceptance is valid through its expiry day, expired the day after", () => {
|
|
91
|
+
const registry = { accepted: [accept("GHSA-high", TODAY)] };
|
|
92
|
+
const findings = blockingFindings(REPORT, { high: 30 });
|
|
93
|
+
assert(checkAcceptances(findings, registry, TODAY).expired.length === 0, "expired on its day");
|
|
94
|
+
assert(checkAcceptances(findings, registry, "2026-10-18").expired.length === 1, "not expired");
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
test("an acceptance past its severity's limit is too long", () => {
|
|
98
|
+
const registry = { accepted: [accept("GHSA-crit", "2026-10-25")] };
|
|
99
|
+
const r = checkAcceptances(blockingFindings(REPORT, { critical: 7 }), registry, TODAY);
|
|
100
|
+
assert(r.tooLong.length === 1 && r.tooLong[0].limit === 7, JSON.stringify(r.tooLong));
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
test("an acceptance for an advisory no longer reported is stale", () => {
|
|
104
|
+
const registry = { accepted: [accept("GHSA-gone", "2026-10-20")] };
|
|
105
|
+
const r = checkAcceptances(blockingFindings(REPORT), registry, TODAY);
|
|
106
|
+
assert(r.stale.length === 1, `stale ${r.stale.length}`);
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
test("a row with no reason, a bad date, or a repeat is invalid", () => {
|
|
110
|
+
const registry = {
|
|
111
|
+
accepted: [
|
|
112
|
+
{ advisory: "GHSA-crit", expires: "2026-10-20" },
|
|
113
|
+
accept("GHSA-high", "next month"),
|
|
114
|
+
accept("GHSA-crit", "2026-10-20"),
|
|
115
|
+
accept("GHSA-crit", "2026-10-20"),
|
|
116
|
+
],
|
|
117
|
+
};
|
|
118
|
+
const r = checkAcceptances(blockingFindings(REPORT), registry, TODAY);
|
|
119
|
+
assert(r.invalid.length === 3, `invalid ${r.invalid.length}`);
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
test("a report with no advisories has nothing to block", () => {
|
|
123
|
+
assert(blockingFindings({ advisories: {} }).length === 0, "found something");
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
console.log(`\n${passed} passed, ${failed} failed`);
|
|
127
|
+
process.exit(failed ? 1 : 0);
|
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,51 @@ Format: `## [version] — YYYY-MM-DD`
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [5.2.3] — 2026-10-17
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **Dependency-audit CI gate.** New copy-and-own `scripts/ci/check-dependency-audit.mjs` (+ `.test.mjs`, `accepted-advisories.json`) runs `pnpm audit --json` and fails on any high / critical advisory the registry does not accept. Each acceptance needs a reason and an expiry (at most 7 days for critical, 30 for high); expired, over-long and stale rows fail; no report = fail. The CI template gains a `Check Dependency Audit` step in `bkit-tests-static`, a no-op until the script is copied. `docs/deployments.md` § Dependency updaters. Upgrade hint is `pnpm update -r <pkg>` (works on pnpm 10 and 12).
|
|
16
|
+
- **Audit findings reach `docs/failures.jsonl`.** `@bkit-audit-generate` writes one failure row per `MEDIUM`+ finding once the report is complete (`workflow: "audit"`, `step: "audit-{slug}"`). A rerun reuses an open row's `key` for the same problem, downgrades it to `LOW` when the finding drops, and closes rows it no longer finds in surfaces it checked. The failures and deferrals audits write no rows. Plan and design already read the ledger, so findings feed them without a hand link.
|
|
17
|
+
- **Audit reports carry a `bkit:anchor` block.** The audit agent runs `bkit branches anchor-stamp` right after creating the report, so the audited commit sits at the top of the file like design and plan docs. Step 1 of every template reads this and the previous report's commit from it. `anchor-stamp` gains `--base-ref` (default `origin/dev`).
|
|
18
|
+
- **Audit Pre-Flight checks permissions first.** Every template opens with one read-only call per tool; a blocked call stops the run before `Probe Steps` and hands back narrow allow rules to grant, or `continue`. Blocked calls persist in `Project Instructions` `Permissions`.
|
|
19
|
+
|
|
20
|
+
### Changed
|
|
21
|
+
|
|
22
|
+
- **Logs audit template checks three things it skipped** (#575). Step 3: fixed `Board` figure per platform re-reporting to the tracker, platform failures beside tracker events (ratio < 1 = lost reports). Step 9: every `docs/noise.md` archive / mute row against its recorded trigger. Step 12: scheduled-job runs started and never finished. "warnings-doc" → `docs/noise.md`.
|
|
23
|
+
- **Audit agent turn cap 150 → 300** (new `XL` tier). One agent runs every template; the longest run ~20 probe steps.
|
|
24
|
+
- **Audit templates probe direnv before calling a credential missing** and run credentialed CLIs through `direnv exec .`. The logs, failures, reliability, flakes and annotations audits point at the `.agents/context.md` readers for their time window.
|
|
25
|
+
|
|
26
|
+
### Fixed
|
|
27
|
+
|
|
28
|
+
- **Context-fetch templates print `skipped` instead of empty output on an API error** (#575). A consumer's log audit found seven of nine readers returning nothing while real failures existed. Every runtime block now checks HTTP status / CLI exit and body shape, pages the whole window, prints `TRUNCATED` when its page cap stops it, and suggests a positive control in `# Customise:`. Per vendor:
|
|
29
|
+
- `supabase.md`: removed `logs.all` → `analytics/endpoints/logs`, one call per day, counts per SQLSTATE.
|
|
30
|
+
- `vercel.md`: `--no-branch`; pages past the 50-line cap; filters `.level`. `VERCEL_N` → `VERCEL_MAX_PAGES`.
|
|
31
|
+
- `inngest.md`: cursor paging; refuses a branch key with `INNGEST_ENV` unset; error class only, never error text. Adds `UNTIL_ISO`, `INNGEST_MAX_PAGES`.
|
|
32
|
+
- `cloudrun.md`: gcloud login only when `gcloud auth print-access-token` works, else service account in a throwaway `CLOUDSDK_CONFIG`; failed `logging read` → `skipped`. Adds `GCP_FILTER`.
|
|
33
|
+
- `stripe.md`: `starting_after` paging; `delivery_success=false` pass. `STRIPE_N` → `STRIPE_MAX_PAGES`.
|
|
34
|
+
- `resend.md`: `after` paging back to `SINCE_ISO`. `RESEND_N` → `SINCE_ISO`, `RESEND_MAX_PAGES`.
|
|
35
|
+
- `expo.md`: `EAS_N` default 10 → 50. `expo-workflows`: `startedAt` (was `null` via `createdAt`), `--limit` ≤ 100, FAILURE list (`EAS_WF_FAIL_N`), `workflow:status` judged by its JSON.
|
|
36
|
+
- `sentry.md`: status and array-shape checks; detector configs carry uptime-check headers.
|
|
37
|
+
|
|
38
|
+
Templates are copy-and-own: a copy below `bkit:end` changes only when re-copied.
|
|
39
|
+
|
|
40
|
+
- **`.agents/context.md` authoring rules** (#575): API / auth error = self-skip; check status before jq; page the window or print `TRUNCATED`; suggest a positive control.
|
|
41
|
+
- **Destructive-git guardrails catch reordered flags.** The Cursor, Codex and Antigravity hooks parse each command (every `&&` / `;` / `|` part, `bash -c`, `$(...)`) into subcommand and flags in any order, with combined short flags (`-fdx`) and global options (`-C dir`, `-q`). `git reset -q --hard`, `git clean -df`, `git checkout -q -- .` and `git restore --worktree .` now ask. Claude and opencode gain glob rows for the common reordered forms in the same tiers.
|
|
42
|
+
- **Force-push denied in any position on every host.** `git push origin dev --force`, `-f` after other args and `+refspec` are denied on Claude and opencode as on the hook hosts; `--force-with-lease` stays allowed.
|
|
43
|
+
- **`--no-verify` asks on every host** (`git commit -n` too).
|
|
44
|
+
- **Shell reads of secret files ask on Cursor and Antigravity** (advisory on Codex): `.env*` except `.env.example`, `*.pem`, `*.p12`, `id_rsa`. Copy destinations, renames and grep patterns don't count as reads. Claude and opencode don't gate shell reads, because their tables match command text and would stall unattended runs on mentions; `.bkit/providers.md` says so.
|
|
45
|
+
- **`bkit check` and `bkit status` see an Antigravity install with `plugin.json` deleted.** Any of `.agents/plugins/bkit/{plugin.json,hooks.json,agents,skills,hooks}` marks the host installed, so a missing manifest or hook file is drift (exit 1), not `antigravity: absent`. `check`, `status` and install share one detector.
|
|
46
|
+
- **Full `bkit uninstall` removes every bkit-written `.opencode/opencode.json` entry.** Every supported provider block and tracker `mcp` entry that still matches bkit's template is stripped, not just the first one found; an edited block is kept whole.
|
|
47
|
+
- **`bkit upgrade` refreshes the recorded hashes of `.cursor/allowlist.json` and `.cursor/cli.json`** after regenerating them, so a later uninstall no longer keeps them as consumer-modified.
|
|
48
|
+
- **`.bkit/install.md` states that `bkit check` does not verify `.bkit/version` `canonicalHashes`**; a bad entry makes uninstall keep that file (`--force` removes it).
|
|
49
|
+
|
|
50
|
+
## [5.2.2] — 2026-10-15
|
|
51
|
+
|
|
52
|
+
### Fixed
|
|
53
|
+
|
|
54
|
+
- **`bkit check` and `bkit upgrade` report the gate advisories install reports** (#524). `test-file-script-missing`, `gate-missing-called-scripts` and `gate-tier-not-wired` ran only on a real install, so an upgraded repo never saw them. They now judge `package.json` as install leaves it and run in every mode. A real `bkit upgrade` ends with `bkit check`'s read-only pass: prints the checklist and rewrites `.bkit/advisories.md` (`Mode: upgrade`), so the upgrade paste block's "read `.bkit/advisories.md`" step reads current findings. Upgrade's exit code is unchanged.
|
|
55
|
+
|
|
11
56
|
## [5.2.1] — 2026-10-15
|
|
12
57
|
|
|
13
58
|
### Changed
|
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
<p align="center">
|
|
17
17
|
<a href="#quick-start">Quick start</a> ·
|
|
18
18
|
<a href="#a-ready-made-workflow-for-every-job">Workflows</a> ·
|
|
19
|
-
<a href="#
|
|
19
|
+
<a href="#agents-and-ci-built-to-work-together">Agents and CI</a> ·
|
|
20
20
|
<a href="#right-context-at-the-right-step">Context</a> ·
|
|
21
21
|
<a href="#faq">FAQ</a> ·
|
|
22
22
|
<a href=".bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks">Comparison</a> ·
|
|
@@ -46,11 +46,11 @@ Everything a senior team would otherwise write down over years, in files you can
|
|
|
46
46
|
<!-- prettier-ignore -->
|
|
47
47
|
| What | How many | What it does for you |
|
|
48
48
|
| --- | --- | --- |
|
|
49
|
-
| Agents | >40 | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
|
|
49
|
+
| [Agents](.bkit/comparison.md#part-1--the-five-phase-pipeline-in-order) | >40 | Single-job specialists, each with its own model, thinking depth and tool list. A reviewer can read code but can't change it. |
|
|
50
50
|
| Workflows | 6 | The five phases plus a cloud router. Every step ends in a checklist and a mechanical check before the next one starts. |
|
|
51
51
|
| Agent rules | >70 | One shared rulebook every agent follows: read before editing, never defer silently, report honestly, never rewrite history. |
|
|
52
52
|
| Guardrails | >10 hook files | Block dangerous commands and make agents investigate before they edit, on all five AI tools. |
|
|
53
|
-
| Audits | >30 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
53
|
+
| [Audits](.bkit/comparison.md#audits) | >30 | Security, privacy, accessibility, performance, reliability, database, LLM usage, cost and more. Findings feed straight into a plan. |
|
|
54
54
|
| Project docs | 10 + index | Architecture, data schema, deployments, testing, security, monitoring, design system, tech stack, setup, and an index telling each agent what to read at each step. |
|
|
55
55
|
| Templates | >60 | A full CI pipeline, cloud agents, git hooks, linters, dependency updates, secrets sync, code search, and >10 ready-made connectors for your platforms. |
|
|
56
56
|
|
|
@@ -61,12 +61,12 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
61
61
|
<!-- prettier-ignore -->
|
|
62
62
|
| Job | Command | What happens |
|
|
63
63
|
| --- | --- | --- |
|
|
64
|
-
| Work out how to build it | `/bkit-design` | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
|
|
65
|
-
| Plan the work | `/bkit-plan` | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
|
|
66
|
-
| Build it | `/bkit-build` | Checks the plan still matches the code, writes each task's tests before its code, verifies every task, hunts for bugs and security holes, adds edge-case tests, and opens a pull request. |
|
|
67
|
-
| Fix what broke | `/bkit-debug` | Pulls evidence from CI and your platforms, finds the root cause, fixes it, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
|
|
68
|
-
| Ship it | `/bkit-ship` | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
|
|
69
|
-
| Health check | >30 audits | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
64
|
+
| Work out how to build it | [`/bkit-design`](.bkit/comparison.md#phase-1--bkit-design) | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
|
|
65
|
+
| Plan the work | [`/bkit-plan`](.bkit/comparison.md#phase-2--bkit-plan) | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
|
|
66
|
+
| Build it | [`/bkit-build`](.bkit/comparison.md#phase-3--bkit-build) | Checks the plan still matches the code, writes each task's tests before its code, verifies every task, hunts for bugs and security holes, adds edge-case tests, and opens a pull request. |
|
|
67
|
+
| Fix what broke | [`/bkit-debug`](.bkit/comparison.md#phase-4--bkit-debug) | Pulls evidence from CI and your platforms, finds the root cause, fixes it, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
|
|
68
|
+
| Ship it | [`/bkit-ship`](.bkit/comparison.md#phase-5--bkit-ship) | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
|
|
69
|
+
| Health check | [>30 audits](.bkit/comparison.md#audits) | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
|
|
70
70
|
| Housekeeping | 7 utility agents | Keep docs, decisions, lessons and known bugs current, and rank what to work on next. |
|
|
71
71
|
|
|
72
72
|
## How it works
|
|
@@ -78,6 +78,8 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
78
78
|
</picture>
|
|
79
79
|
</p>
|
|
80
80
|
|
|
81
|
+
Every agent in each phase, in the order it runs and what it checks: [pipeline reference](.bkit/comparison.md#pipeline-map-key-steps-only).
|
|
82
|
+
|
|
81
83
|
## Why it's different
|
|
82
84
|
|
|
83
85
|
<p align="center">
|
|
@@ -89,15 +91,36 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
|
|
|
89
91
|
|
|
90
92
|
Most AI development frameworks are prompts: they describe good work and trust the agent to deliver it. But an agent can be talked into calling something done, and a prompt can't stop it. bkit builds fences instead. Reviewer agents that didn't write the work fence in the design and the plan. From the first line of code, automated checks join them, and those can't be argued with.
|
|
91
93
|
|
|
92
|
-
##
|
|
94
|
+
## Agents and CI, built to work together
|
|
95
|
+
|
|
96
|
+
<p align="center">
|
|
97
|
+
<picture>
|
|
98
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-fences-details-dark.svg">
|
|
99
|
+
<img alt="Every change hits the same fences. They never argue, and they grow. On the left, the agents. Every agent in every workflow looks up every definition and caller with code search before a change, is nudged by the agent hooks on every edit, has every workflow step checked by the step gates, and has its code formatted by the pre-commit hook on every commit. /bkit-plan decides the tests each feature adds to the fences (unit, integration or end-to-end). /bkit-build writes each test first, sees it fail, then hits every fence; the pre-push hook sends problems back before they leave your laptop. When a CI lane goes red, its logs give /bkit-debug the context to fix it. When CI is green, the change passes through and /bkit-ship merges it, re-checked on the merge commit. On the right, the fences, nearest and lightest first: code search on every lookup, agent hooks on every edit, step gates on every step, the pre-commit hook on every commit, the pre-push hook on every push, and CI, the strongest, on every push and pull request. The step gates are scripts, not prompts: a step missing its verdict or files can't finish, whatever the agent says. The pre-commit hook formats only the files being committed, so it takes seconds, and your own quick checks can go there too. CI runs integration, end-to-end and live-site tests, and one check fails if any lane failed, was skipped or ran no tests. Hooks, agents and CI run the same commands, and in cloud mode CI's answer starts debug or ship by itself." src=".github/assets/bkit-fences-details-light.svg" width="100%">
|
|
100
|
+
</picture>
|
|
101
|
+
</p>
|
|
102
|
+
|
|
103
|
+
The strongest fence is CI (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges. Most AI development frameworks stop at a pull request and leave CI to you. bkit's workflows are built around it, and around the checks that run before it. Every change has to get past the same fences, from the nearest and lightest out to CI:
|
|
104
|
+
|
|
105
|
+
- **Every agent**, in every workflow, looks code up before changing it, is nudged by the agent hooks on each edit, can't finish a step until the step gates (scripts, not prompts) find its verdict and files, and has its code formatted on each commit.
|
|
106
|
+
- **`/bkit-plan`** decides which tests each feature needs and where each one runs: unit, integration or end-to-end.
|
|
107
|
+
- **`/bkit-build`** writes each test before its code and runs it to prove it fails, so a test that can't fail is never added. It runs the quick checks on your machine, where the pre-push hook sends back anything that fails, then opens a pull request, which starts CI.
|
|
108
|
+
- **`/bkit-debug`** uses what was sent back as context: the logs of the lanes that failed, the diff since the last green run, end-to-end reports. It fixes the root cause and pushes, and CI runs again.
|
|
109
|
+
- **`/bkit-ship`** checks nothing planned was quietly dropped, then merges into `dev` only when CI's final check is green on the exact commit being merged.
|
|
110
|
+
- **On autopilot**, nobody has to press go: for issues labelled `bkit:auto`, CI's result starts ship (green) or debug (red) in a cloud session, with no laptop open.
|
|
111
|
+
|
|
112
|
+
What that gets you:
|
|
93
113
|
|
|
94
|
-
The
|
|
114
|
+
- **The fences grow with every feature.** Each build adds tests that every later change has to pass. A prompt-only framework is as strict on your fiftieth feature as on your first; bkit gets stricter.
|
|
115
|
+
- **What's sent back is evidence, not a verdict.** A red lane hands debug the failing logs and what changed since the last green run, so the fix starts from the actual error instead of a guess.
|
|
116
|
+
- **Agents look before they change anything.** Code search ([Serena](https://github.com/oraios/serena)) shows an agent every definition and caller of the code it's about to change, not just lines with matching words, and [graphify](https://github.com/Graphify-Labs/graphify)'s code map shows what already exists before it writes more. Fewer bad changes reach the fences at all.
|
|
117
|
+
- **Problems are caught at the nearest fence.** Agent hooks nudge on every edit: read a file before changing it, and fix the code rather than loosen a check. The pre-commit hook formats in seconds. The pre-push hook runs type checks, unit tests, the prose checker and the junk-code scanner before anything leaves your laptop. CI is left with what genuinely can't run there: integration, end-to-end and live-site tests. Your hooks and the agents call the same `bkit:gate:*` scripts, and CI's quick-checks lane runs the same commands, so most failures show up on your machine first.
|
|
95
118
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
119
|
+
The agent hooks come with install. Serena, graphify and the git hooks are [templates](#templates-ready-to-adopt) you adopt. How this compares with other frameworks: [agents and CI](.bkit/comparison.md#agents-and-ci).
|
|
120
|
+
|
|
121
|
+
### The CI pipeline
|
|
122
|
+
|
|
123
|
+
None of the AI development frameworks in our [comparison](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks) ships a full test pipeline for your project. bkit ships one ready to adopt:
|
|
101
124
|
|
|
102
125
|
<p align="center">
|
|
103
126
|
<picture>
|
|
@@ -112,6 +135,8 @@ The strongest fence is CI (continuous integration): the robot that runs every ch
|
|
|
112
135
|
- **Safe by default.** Every third-party action is pinned to an exact commit, the downloaded prose checker is checksum-verified, and pull-request titles never reach a script unescaped.
|
|
113
136
|
- **Doesn't waste minutes.** A commit that already passed isn't re-tested, and a newer push cancels the older run, except on your production branch, where a deploy must never be cut off halfway.
|
|
114
137
|
|
|
138
|
+
How the lanes join into the one final check, and what happens on green or red: [CI test scaffold](.bkit/comparison.md#ci-test-scaffold-runs-on-every-pr--push).
|
|
139
|
+
|
|
115
140
|
## Right context at the right step
|
|
116
141
|
|
|
117
142
|
<p align="center">
|
|
@@ -143,7 +168,6 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
143
168
|
- **It tests ideas before you commit to them.** When reviewers flag an unknown a design depends on, design writes throwaway probe code to settle it before you approve, and a design reviewer checks failure modes and monitoring, not just whether it can be built.
|
|
144
169
|
- **Big features are split up.** A plan too big for one build becomes a sequence of smaller plans, and each is re-checked against the current code right before it's built.
|
|
145
170
|
- **Numbers on your own work.** Every run records its time, size of change and retries in `.bkit/stats.jsonl`, and posts them to the issue next to the median of your last five runs.
|
|
146
|
-
- **Health checks on demand.** >30 audit checklists act like hiring a specialist for a day.
|
|
147
171
|
|
|
148
172
|
### It fits how you work
|
|
149
173
|
|
|
@@ -159,16 +183,48 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
|
|
|
159
183
|
- **Three sign-offs, and production stays yours.** bkit stops after the design, after the plan and before merging. It merges into your `dev` branch and never touches `main`: promoting to production is always your call. Cloud mode can ship on green without you, but only for issues you've labelled `bkit:auto`, and removing the label stops it.
|
|
160
184
|
- **Guardrails on the AI itself.** Dangerous commands like force-pushing or rewriting history are blocked. Each agent only gets the tools its job needs.
|
|
161
185
|
|
|
186
|
+
## Audits find what green tests miss
|
|
187
|
+
|
|
188
|
+
<p align="center">
|
|
189
|
+
<picture>
|
|
190
|
+
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-audits-dark.svg">
|
|
191
|
+
<img alt="The tests were green. The bugs were still there. A map of an app that adopted bkit, in four columns: screens (web and phone), API, services and outside services, with thin lines for the calls between them. Red circles mark what bkit's audit templates found, bigger for bigger problems. Testing audit: tests that could never fail, about 100 of which read the code as text instead of running it; a security hole, where a sign-in link could send people to another website; no test made a request fail, so a failed save could still show “Saved”; a fix in dead code, while the live screen next to it stayed broken; phone tests that weren't, with 23 of 33 actually running as web pages. Duplication audit: one rule written 8 times, whose copies drifted so some billed accounts users had left; one database read in 4 copies, word for word, one inside the API itself. This map used 2 of the more than 30 audit templates bkit ships." src=".github/assets/bkit-audits-light.svg" width="100%">
|
|
192
|
+
</picture>
|
|
193
|
+
</p>
|
|
194
|
+
|
|
195
|
+
A green tick proves the tests passed, not that they test the right things. Every finding on this map sat in an app whose tests were passing, and only two of bkit's audit templates found them all.
|
|
196
|
+
|
|
197
|
+
Each template is a specialist's checklist for one area: what to check, how, and what counts as a problem. Ten to start with:
|
|
198
|
+
|
|
199
|
+
<!-- prettier-ignore -->
|
|
200
|
+
| Audit | What it checks | For example |
|
|
201
|
+
| --- | --- | --- |
|
|
202
|
+
| **Testing** | Whether tests can fail, actually run, and cover what the product must and must never do | Tests that read the code as text instead of running it |
|
|
203
|
+
| **Duplication** | Rules and logic built more than once | A billing rule in eight copies that have drifted apart |
|
|
204
|
+
| **Security** | Sign-in, permissions, secrets, input checks, and protections the docs promise | A sign-in link that can send people to another website |
|
|
205
|
+
| **Red team** | Real attacks on a test copy of your app, never production, one request at a time | One signed-in user reading another user's data |
|
|
206
|
+
| **Reliability** | What happens when a service is slow, down or answers twice | A payment retried with no guard against charging twice |
|
|
207
|
+
| **Privacy** | Where personal data goes, how long it stays, and whether deletion works | A deleted account still sitting in the logs |
|
|
208
|
+
| **Dead code** | Code, settings and routes that look live but never run | A fix made in a file nothing calls |
|
|
209
|
+
| **LLM** | Every AI model call, and what stops it when the input is hostile | A pasted document that talks the model into calling a tool |
|
|
210
|
+
| **Accessibility** | What automated accessibility checks miss, against WCAG 2.2 AA | A form a screen reader can't get through |
|
|
211
|
+
| **Cost** | Vendor plans against what you actually use | A plan two tiers above your usage |
|
|
212
|
+
|
|
213
|
+
All 35, grouped by area, with what each one finds: [the full audit list](.bkit/comparison.md#audits).
|
|
214
|
+
|
|
215
|
+
- **Run one whenever you want.** Name a template to `@bkit-audit-generate` and it writes a report to `docs/audits/{YYYYMM}/`. It reads your code and, where you've connected them, your live platforms, and lists anything it couldn't check rather than calling it clean.
|
|
216
|
+
- **Findings turn into work.** Hand the report to `/bkit-plan` and the fixes are planned, built, tested and shipped like any other feature.
|
|
217
|
+
|
|
162
218
|
## Templates ready to adopt
|
|
163
219
|
|
|
164
|
-
bkit installs only what its workflows run. Everything else, the things you or another tool run, ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. Copy in what you want and own it; bkit never writes over your copy. The install prompt asks your AI to adopt what fits, and each workflow ends with a tip on the next one worth adding.
|
|
220
|
+
bkit installs only what its workflows run. Everything else, the things you or another tool run, ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. Copy in what you want and own it; bkit never writes over your copy. The install prompt asks your AI to adopt what fits, and each workflow ends with a tip on the next one worth adding. Audits aren't among them: they come installed, so there's nothing to copy ([above](#audits-find-what-green-tests-miss)).
|
|
165
221
|
|
|
166
222
|
The ones that matter most, in the order to adopt them:
|
|
167
223
|
|
|
168
224
|
<!-- prettier-ignore -->
|
|
169
225
|
| Template | What it's for |
|
|
170
226
|
| --- | --- |
|
|
171
|
-
| **CI pipeline** | Runs every check on GitHub on every change, and `/bkit-ship` waits for it before merging. Without it, "shipped" only means merged, not checked. Two lanes ready to go and >20 building blocks for the rest ([above](#
|
|
227
|
+
| **CI pipeline** | Runs every check on GitHub on every change, and `/bkit-ship` waits for it before merging. Without it, "shipped" only means merged, not checked. Two lanes ready to go and >20 building blocks for the rest ([above](#the-ci-pipeline)). |
|
|
172
228
|
| **Quality checks** | Catches problems on your own machine in seconds, before they reach GitHub: type checking, formatting, a prose checker and a scanner for junk code AI tends to write, wired into git hooks and CI. Your `bkit:gate:*` scripts in `package.json` define what "the checks" are. |
|
|
173
229
|
| **Serena** | Lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of searching for words and reading whole files. Fewer accidental changes, and lower running costs because agents read less. Read-only. |
|
|
174
230
|
| **Context connectors** | Let `/bkit-debug` read the real errors instead of guessing from the code: >10 ready-made connectors for CI, error trackers, hosting, databases, payments, email, queues and the web. |
|
|
@@ -237,7 +293,7 @@ We measured both on 456 real Claude Code transcripts. They saved about 1–3% of
|
|
|
237
293
|
- **One source, every host.** `.bkit/` renders `.claude/`, `.cursor/`, `.codex/`, `.agents/` (Antigravity) and `.opencode/`. `bkit check` is the CI drift gate.
|
|
238
294
|
- **Reviewer independence.** Parallel reviewers can't read sibling output. Design brainstorm, design review and plan scope-check groups also cross models (Opus + Sonnet on Claude; Grok + Composer on Cursor); depth-sensitive lenses (plan review, build challenge) stay on the top tier.
|
|
239
295
|
- **Per-agent pins.** Model and effort per agent, per provider ([`.bkit/prompts.md`](.bkit/prompts.md) § Models), immune to the session default.
|
|
240
|
-
- **Against the literature.** bkit fully implements 13 of the 22 patterns in Antonio Gulli's _Agentic Design Patterns_, partly implements 7 (scoped to shipping code), leaves 2 out by design, and goes beyond the book in 8 places. Full mapping and
|
|
296
|
+
- **Against the literature.** bkit fully implements 13 of the 22 patterns in Antonio Gulli's _Agentic Design Patterns_, partly implements 7 (scoped to shipping code), leaves 2 out by design, and goes beyond the book in 8 places. Full mapping: [patterns comparison](.bkit/comparison.md#part-2--comparison-to-agentic-design-patterns), with [where bkit goes beyond the book](.bkit/comparison.md#where-bkit-goes-beyond-the-catalogue) and its [known gaps](.bkit/comparison.md#known-gaps-scoped-as-opportunities). Every agent in execution order: [pipeline reference](.bkit/comparison.md#part-1--the-five-phase-pipeline-in-order).
|
|
241
297
|
|
|
242
298
|
</details>
|
|
243
299
|
|
|
@@ -117,7 +117,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = [], tips =
|
|
|
117
117
|
lines.push(`_bkit: ${opts.version}_ `);
|
|
118
118
|
lines.push(`_Mode: ${opts.mode}_`);
|
|
119
119
|
lines.push("");
|
|
120
|
-
lines.push("> Auto-generated by `bkit install` / `bkit check` / `bkit doctor`. Overwritten on each run.");
|
|
120
|
+
lines.push("> Auto-generated by `bkit install` / `bkit check` / `bkit upgrade` / `bkit doctor`. Overwritten on each run.");
|
|
121
121
|
lines.push("");
|
|
122
122
|
if (findings.length === 0 && suppressed.length === 0 && tips.length === 0) {
|
|
123
123
|
lines.push("**No advisories.** Last run was clean.");
|
|
@@ -1,13 +1,12 @@
|
|
|
1
1
|
// commands/install/check.ts — `bkit check`: the parts only check runs. Check is install in
|
|
2
2
|
// dry-run mode (commands/install/install.ts runInstall); this file holds the installed-module
|
|
3
3
|
// detection that scopes its drift gate and the drift verdict.
|
|
4
|
-
import
|
|
5
|
-
import * as path from "node:path";
|
|
4
|
+
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
6
5
|
import { describeMissingOwnedHook } from "../../checks/after/managed.js";
|
|
7
6
|
import { LOG_PREFIX } from "../../shared/log-prefix.js";
|
|
8
7
|
/**
|
|
9
8
|
* Installed-module set, detected by sentinel-file presence. Always core, plus the installed
|
|
10
|
-
*
|
|
9
|
+
* hosts (detectInstalledHostModules). Two callers:
|
|
11
10
|
* - `bkit check` — scopes the drift gate, so a `--cursor`-only repo does not
|
|
12
11
|
* report `.claude/**` as drift.
|
|
13
12
|
* - `bkit upgrade` — scopes the template walk, so upgrade does NOT force-create files for a
|
|
@@ -21,18 +20,7 @@ import { LOG_PREFIX } from "../../shared/log-prefix.js";
|
|
|
21
20
|
* Dependency-updater files are not modules: bkit never drift-checks them.
|
|
22
21
|
*/
|
|
23
22
|
export function detectInstalledModules(cwd) {
|
|
24
|
-
|
|
25
|
-
if (fs.existsSync(path.join(cwd, ".claude", "agents")))
|
|
26
|
-
mods.add("claude");
|
|
27
|
-
if (fs.existsSync(path.join(cwd, ".cursor", "agents")))
|
|
28
|
-
mods.add("cursor");
|
|
29
|
-
if (fs.existsSync(path.join(cwd, ".opencode", "agents")))
|
|
30
|
-
mods.add("opencode");
|
|
31
|
-
if (fs.existsSync(path.join(cwd, ".codex", "agents")))
|
|
32
|
-
mods.add("codex");
|
|
33
|
-
if (fs.existsSync(path.join(cwd, ".agents", "plugins", "bkit", "plugin.json")))
|
|
34
|
-
mods.add("antigravity");
|
|
35
|
-
return mods;
|
|
23
|
+
return new Set(["core", ...detectInstalledHostModules(cwd)]);
|
|
36
24
|
}
|
|
37
25
|
// Check mode: exit-1 on drift (totalWrites > 0). runInstall emits the banner first.
|
|
38
26
|
// Host agent/command mirrors push would-writes into ws.writes (content drift OR
|
|
@@ -10,6 +10,7 @@ import { runPreflight } from "../../checks/before/index.js";
|
|
|
10
10
|
import { runPostInstallCheck, formatChecklist, writeAdvisoriesArtifact, } from "../../checks/after/index.js";
|
|
11
11
|
import { collectTips } from "../../checks/tips/index.js";
|
|
12
12
|
import { parseDotenv } from "../../install/cloud-env.js";
|
|
13
|
+
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
13
14
|
/**
|
|
14
15
|
* `bkit status` — read-only host/provider status.
|
|
15
16
|
* Reports current host+provider sampled from .opencode/opencode.json,
|
|
@@ -82,7 +83,7 @@ export function runStatus(cwd, logPrefix) {
|
|
|
82
83
|
const codexDir = path.join(cwd, ".codex");
|
|
83
84
|
const codexPresent = fs.existsSync(codexDir);
|
|
84
85
|
// --- antigravity host ---
|
|
85
|
-
const antigravityPresent =
|
|
86
|
+
const antigravityPresent = detectInstalledHostModules(cwd).has("antigravity");
|
|
86
87
|
const opencodeStatus = opencodePresent
|
|
87
88
|
? `INSTALLED (${providerLabel}: ${opencodeProviderDisplay} / model: ${opencodeModel})`
|
|
88
89
|
: "absent (run: bkit install --opencode=<provider>)";
|