@cbartens/bkit 5.5.1 → 6.0.0
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 +30 -20
- package/.bkit/core/.agents/docs.md +1 -0
- package/.bkit/core/.agents/rules.md +35 -26
- package/.bkit/core/.bkit/README.md +29 -19
- package/.bkit/core/.bkit/authoring.md +117 -0
- package/.bkit/core/.bkit/cloud.md +11 -11
- package/.bkit/core/.bkit/comparison.md +5 -5
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/jsonl.md +202 -122
- package/.bkit/core/.bkit/lite.md +1 -1
- package/.bkit/core/.bkit/pipeline.md +49 -52
- package/.bkit/core/.bkit/prompts.md +91 -167
- package/.bkit/core/.bkit/providers.md +29 -32
- package/.bkit/core/.bkit/templates.md +12 -11
- package/.bkit/core/.bkit/trackers.md +51 -28
- package/.bkit/core/.bkit/workflows.md +394 -355
- package/.bkit/core/AGENTS.md +16 -22
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
- package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
- package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
- package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
- package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
- package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
- package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
- package/.bkit/core/docs/templates/bkit-plan.md +97 -226
- package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
- package/.bkit/core/engine/checks/after/github.ts +95 -17
- package/.bkit/core/engine/checks/after/index.ts +10 -7
- package/.bkit/core/engine/checks/after/suppression.ts +8 -5
- package/.bkit/core/engine/checks/after/tools.ts +46 -91
- package/.bkit/core/engine/checks/before/env.ts +2 -2
- package/.bkit/core/engine/checks/before/files.ts +5 -4
- package/.bkit/core/engine/checks/before/index.ts +18 -1
- package/.bkit/core/engine/checks/before/repo.ts +168 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
- package/.bkit/core/engine/checks/tips/detect.ts +34 -0
- package/.bkit/core/engine/checks/tips/index.ts +6 -6
- package/.bkit/core/engine/cli.ts +20 -53
- package/.bkit/core/engine/commands/analysis.ts +171 -140
- package/.bkit/core/engine/commands/ci/ci.ts +6 -6
- package/.bkit/core/engine/commands/comply.ts +77 -103
- package/.bkit/core/engine/commands/install/doctor.ts +2 -2
- package/.bkit/core/engine/commands/install/install.ts +57 -18
- package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
- package/.bkit/core/engine/commands/land.ts +18 -12
- package/.bkit/core/engine/commands/lib.ts +79 -17
- package/.bkit/core/engine/commands/registry.ts +4 -0
- package/.bkit/core/engine/commands/setup/setup.ts +7 -7
- package/.bkit/core/engine/commands/stats.ts +204 -0
- package/.bkit/core/engine/commands/tips.ts +10 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
- package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
- package/.bkit/core/engine/commands/workflow/context.ts +853 -29
- package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
- package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
- package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
- package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
- package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
- package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
- package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
- package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
- package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
- package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
- package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
- package/.bkit/core/engine/commands/workflow/status.ts +142 -29
- package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
- package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
- package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
- package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
- package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
- package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
- package/.bkit/core/engine/install/manifest.ts +11 -9
- package/.bkit/core/engine/install/modules/cloud.ts +21 -13
- package/.bkit/core/engine/install/modules/core.ts +250 -3
- package/.bkit/core/engine/install/modules/opencode.ts +2 -2
- package/.bkit/core/engine/install/version-file.ts +6 -2
- package/.bkit/core/engine/ledgers/migrate.ts +92 -0
- package/.bkit/core/engine/ledgers/status.ts +92 -15
- package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
- package/.bkit/core/engine/render/hosts.ts +4 -0
- package/.bkit/core/engine/render/models.ts +12 -0
- package/.bkit/core/engine/shared/branches.ts +4 -1
- package/.bkit/core/engine/shared/egress.ts +7 -0
- package/.bkit/core/engine/shared/json.ts +25 -7
- package/.bkit/core/engine/shared/settings.ts +157 -20
- package/.bkit/core/engine/shared/text.ts +361 -0
- package/.bkit/core/engine/tools/grammar-density.ts +215 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
- package/.bkit/core/engine/tools/instructions.ts +1751 -0
- package/.bkit/core/hooks/gateguard-engine.js +24 -23
- package/.bkit/core/hooks/guardrails-shell.js +2 -3
- package/.bkit/core/hooks/guardrails-tiers.js +7 -1
- package/.bkit/core/hooks/readguard-engine.js +2 -2
- package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
- package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
- package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
- package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
- package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
- package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
- package/.bkit/core/prompts/bkit-design-generate.md +32 -14
- package/.bkit/core/prompts/bkit-design-organise.md +25 -12
- package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
- package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
- package/.bkit/core/prompts/bkit-design-spike.md +30 -13
- package/.bkit/core/prompts/bkit-design-update.md +33 -19
- package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
- package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
- package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
- package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
- package/.bkit/core/prompts/bkit-plan-update.md +61 -24
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
- package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
- package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
- package/.bkit/core/workflows/bkit-auto.md +54 -46
- package/.bkit/core/workflows/bkit-build.md +577 -458
- package/.bkit/core/workflows/bkit-debug.md +348 -333
- package/.bkit/core/workflows/bkit-design.md +201 -237
- package/.bkit/core/workflows/bkit-plan.md +210 -321
- package/.bkit/core/workflows/bkit-ship.md +328 -278
- package/.bkit/shared/.bkit/.env.example +2 -2
- package/.bkit/shared/.claude/settings.json +11 -0
- package/.bkit/shared/.cursor/mcp.json +1 -1
- package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
- package/.bkit/shared/.gitattributes +1 -1
- package/.bkit/shared/.mcp.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -0
- package/.bkit/shared/CLAUDE.md +2 -2
- package/.bkit/shared/GEMINI.md +2 -2
- package/.bkit/shared/docs/architecture.md +1 -1
- package/.bkit/shared/docs/data-schema.md +1 -1
- package/.bkit/shared/docs/deployments.md +11 -11
- package/.bkit/shared/docs/design.md +1 -1
- package/.bkit/shared/docs/noise.md +1 -1
- package/.bkit/shared/docs/observability.md +2 -2
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/setup.md +1 -1
- package/.bkit/shared/docs/technology.md +1 -1
- package/.bkit/shared/docs/testing.md +16 -7
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
- package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
- package/.bkit/templates/.husky/pre-push +4 -4
- package/.bkit/templates/.prettierignore +7 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
- package/CHANGELOG.md +112 -0
- package/README.md +50 -35
- package/dist/checks/after/ci-yml.js +39 -28
- package/dist/checks/after/github.js +91 -17
- package/dist/checks/after/index.js +11 -8
- package/dist/checks/after/suppression.js +8 -5
- package/dist/checks/after/tools.js +39 -82
- package/dist/checks/before/env.js +2 -2
- package/dist/checks/before/files.js +5 -3
- package/dist/checks/before/index.js +15 -2
- package/dist/checks/before/repo.js +163 -2
- package/dist/checks/tips/catalogue.js +14 -5
- package/dist/checks/tips/detect.js +32 -0
- package/dist/checks/tips/index.js +4 -4
- package/dist/cli.js +19 -47
- package/dist/commands/analysis.js +109 -100
- package/dist/commands/ci/ci.js +6 -6
- package/dist/commands/comply.js +54 -91
- package/dist/commands/install/doctor.js +2 -2
- package/dist/commands/install/install.js +50 -19
- package/dist/commands/install/uninstall.js +59 -28
- package/dist/commands/land.js +16 -12
- package/dist/commands/lib.js +51 -16
- package/dist/commands/registry.js +4 -0
- package/dist/commands/setup/setup.js +7 -7
- package/dist/commands/stats.js +136 -0
- package/dist/commands/tips.js +7 -3
- package/dist/commands/workflow/branches.js +656 -56
- package/dist/commands/workflow/challenge.js +556 -0
- package/dist/commands/workflow/context.js +709 -30
- package/dist/commands/workflow/counters.js +208 -75
- package/dist/commands/workflow/decisions.js +441 -0
- package/dist/commands/workflow/disk.js +2 -2
- package/dist/commands/workflow/fids.js +689 -33
- package/dist/commands/workflow/issues.js +343 -59
- package/dist/commands/workflow/ledgers.js +762 -27
- package/dist/commands/workflow/locks.js +24 -2
- package/dist/commands/workflow/plan-blocks.js +437 -0
- package/dist/commands/workflow/plan-versions.js +22 -0
- package/dist/commands/workflow/prs.js +142 -32
- package/dist/commands/workflow/repo.js +52 -8
- package/dist/commands/workflow/roadmap.js +9 -7
- package/dist/commands/workflow/run-facts.js +426 -0
- package/dist/commands/workflow/runs.js +144 -43
- package/dist/commands/workflow/runtime.js +12 -1
- package/dist/commands/workflow/status.js +130 -29
- package/dist/commands/workflow/step-table.js +276 -0
- package/dist/commands/workflow/steps.js +171 -80
- package/dist/commands/workflow/summary.js +275 -0
- package/dist/commands/workflow/tests.js +834 -136
- package/dist/commands/workflow/tracker.js +983 -0
- package/dist/commands/workflow/workflows.js +834 -195
- package/dist/commands/workflow/workstreams.js +11 -5
- package/dist/commands/workflow/worktrees.js +147 -9
- package/dist/install/manifest.js +11 -9
- package/dist/install/modules/cloud.js +22 -13
- package/dist/install/modules/core.js +247 -3
- package/dist/install/modules/opencode.js +2 -2
- package/dist/install/version-file.js +6 -2
- package/dist/ledgers/migrate.js +81 -0
- package/dist/ledgers/status.js +61 -8
- package/dist/ledgers/telemetry.js +905 -124
- package/dist/render/hosts.js +4 -0
- package/dist/render/models.js +12 -0
- package/dist/shared/branches.js +3 -1
- package/dist/shared/egress.js +7 -0
- package/dist/shared/json.js +20 -7
- package/dist/shared/settings.js +125 -17
- package/dist/shared/text.js +333 -0
- package/dist/tools/grammar-density.js +183 -0
- package/dist/tools/instructions-sources.js +721 -0
- package/dist/tools/instructions.js +1579 -0
- package/package.json +113 -24
- package/.bkit/core/engine/commands/harvest.ts +0 -459
- package/.bkit/core/engine/tools/wording.ts +0 -748
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
- package/.bkit/core/prompts/bkit-build-summary.md +0 -94
- package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
- package/.bkit/core/prompts/bkit-design-summary.md +0 -107
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
- package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
- package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
- package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
- package/dist/commands/harvest.js +0 -353
- package/dist/tools/wording.js +0 -680
package/dist/commands/lib.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// commands/lib.ts — what every `bkit <noun> <verb>` command shares.
|
|
2
2
|
//
|
|
3
|
-
// Flag parsing, one
|
|
3
|
+
// Flag parsing, one output object on stdout (text, or JSON with `--json`),
|
|
4
|
+
// `[bkit-<noun>]`-tagged logs on stderr,
|
|
4
5
|
// the exit-code table, `--help` rendering, and the repo facts several workflow
|
|
5
6
|
// steps each re-derived by hand: repo root, UTC month, where `status.jsonl` lives,
|
|
6
7
|
// the skip-CI tokens, and which branches are shared. A command declares its flags,
|
|
@@ -11,6 +12,7 @@ import * as fs from "node:fs";
|
|
|
11
12
|
import * as os from "node:os";
|
|
12
13
|
import * as path from "node:path";
|
|
13
14
|
import { gitEnv } from "../ledgers/telemetry.js";
|
|
15
|
+
import { renderText } from "../shared/text.js";
|
|
14
16
|
// ---------------------------------------------------------------------------
|
|
15
17
|
// Exit codes
|
|
16
18
|
// ---------------------------------------------------------------------------
|
|
@@ -178,8 +180,8 @@ export function verbHelp(cmd, verb) {
|
|
|
178
180
|
"Flags:",
|
|
179
181
|
flags.length ? table(flags) : " none",
|
|
180
182
|
"",
|
|
181
|
-
"Output (one
|
|
182
|
-
table(Object.entries(spec.output)),
|
|
183
|
+
"Output (one object on stdout: `key: value` text, JSON with --json):",
|
|
184
|
+
table(Object.entries(spec.output).map(([key, help]) => [key, help + omitNote(spec, key)])),
|
|
183
185
|
"",
|
|
184
186
|
"Exit codes:",
|
|
185
187
|
table(exitCodeRows(spec.exitCodes)),
|
|
@@ -195,6 +197,20 @@ const processIo = {
|
|
|
195
197
|
stderr: (t) => process.stderr.write(t),
|
|
196
198
|
};
|
|
197
199
|
const isHelp = (arg) => arg === "--help" || arg === "-h";
|
|
200
|
+
/** Global boolean flag every verb takes; it is removed before the verb's own flags parse. */
|
|
201
|
+
const JSON_FLAG = "--json";
|
|
202
|
+
/** `output` less the keys `spec.textOmit` leaves out of text. */
|
|
203
|
+
function textOutput(spec, output) {
|
|
204
|
+
const omit = new Set((spec.textOmit ?? []).flatMap((o) => typeof o === "string" ? [o] : o.when(output[o.key], output) ? [o.key] : []));
|
|
205
|
+
return Object.fromEntries(Object.entries(output).filter(([k]) => !omit.has(k)));
|
|
206
|
+
}
|
|
207
|
+
/** `--help`'s note on an output key text leaves out: always, or only when it does not matter. */
|
|
208
|
+
function omitNote(spec, key) {
|
|
209
|
+
const o = (spec.textOmit ?? []).find((x) => (typeof x === "string" ? x : x.key) === key);
|
|
210
|
+
if (o === undefined)
|
|
211
|
+
return "";
|
|
212
|
+
return typeof o === "string" ? " (--json only)" : " (text: only when it matters)";
|
|
213
|
+
}
|
|
198
214
|
/**
|
|
199
215
|
* Run `argv` (without the leading `bkit`) if it names a registered command.
|
|
200
216
|
* Returns the exit code, or null when `argv` is not a command, so the caller falls
|
|
@@ -231,16 +247,22 @@ export async function runCommand(argv, commands, options) {
|
|
|
231
247
|
const ctx = {
|
|
232
248
|
flags: {},
|
|
233
249
|
cwd: options.cwd ?? process.cwd(),
|
|
250
|
+
json: false,
|
|
234
251
|
log: (message) => io.stderr(`${tag} ${message}\n`),
|
|
235
252
|
emit: (output) => {
|
|
236
253
|
if (emitted)
|
|
237
|
-
throw new Error(`${tag} ${verb} emitted twice — one
|
|
254
|
+
throw new Error(`${tag} ${verb} emitted twice — one output object per run`);
|
|
238
255
|
emitted = true;
|
|
239
|
-
io.stdout(`${JSON.stringify(output)}\n`);
|
|
256
|
+
io.stdout(ctx.json ? `${JSON.stringify(output)}\n` : renderText(textOutput(spec, output)));
|
|
240
257
|
},
|
|
241
258
|
};
|
|
242
259
|
try {
|
|
243
|
-
|
|
260
|
+
const own = rest.filter((arg) => arg !== JSON_FLAG);
|
|
261
|
+
if (own.some((arg) => arg.startsWith(`${JSON_FLAG}=`))) {
|
|
262
|
+
throw new CommandError(EXIT.USAGE, `${JSON_FLAG} takes no value`);
|
|
263
|
+
}
|
|
264
|
+
ctx.json = own.length !== rest.length;
|
|
265
|
+
ctx.flags = parseFlags(own, spec.flags);
|
|
244
266
|
return await spec.run(ctx);
|
|
245
267
|
}
|
|
246
268
|
catch (err) {
|
|
@@ -253,20 +275,20 @@ export async function runCommand(argv, commands, options) {
|
|
|
253
275
|
// ---------------------------------------------------------------------------
|
|
254
276
|
// Repo facts
|
|
255
277
|
// ---------------------------------------------------------------------------
|
|
256
|
-
/** Captured stdout / stderr cap for
|
|
257
|
-
const OUTPUT_LIMIT = 1 << 26;
|
|
278
|
+
/** Captured stdout / stderr cap for every git / gh spawn; hook output (pre-push) counts. */
|
|
279
|
+
export const OUTPUT_LIMIT = 1 << 26;
|
|
258
280
|
/** Spawn error as a stderr lead line: ENOBUFS names the limit, anything else Node's message. */
|
|
259
281
|
function spawnErrorText(cmd, args, err) {
|
|
260
282
|
return err.code === "ENOBUFS"
|
|
261
283
|
? `${cmd} ${args[0] ?? ""}: output passed the ${OUTPUT_LIMIT / (1 << 20)} MiB limit (ENOBUFS)`
|
|
262
284
|
: err.message;
|
|
263
285
|
}
|
|
264
|
-
/** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr. */
|
|
265
|
-
export function runGit(cwd, args) {
|
|
286
|
+
/** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr; `env` adds vars. */
|
|
287
|
+
export function runGit(cwd, args, env = {}) {
|
|
266
288
|
const res = spawnSync("git", args, {
|
|
267
289
|
cwd,
|
|
268
290
|
encoding: "utf-8",
|
|
269
|
-
env: gitEnv(),
|
|
291
|
+
env: { ...gitEnv(), ...env },
|
|
270
292
|
maxBuffer: OUTPUT_LIMIT,
|
|
271
293
|
});
|
|
272
294
|
const stderr = (res.stderr ?? "").trim();
|
|
@@ -288,7 +310,7 @@ export function git(cwd, args) {
|
|
|
288
310
|
// for the command modules that already import it from this module.
|
|
289
311
|
export { parseJson } from "../shared/json.js";
|
|
290
312
|
// The shared-branch rule (`dev`, `main`) lives in shared/ so checks can read it too.
|
|
291
|
-
export { DEV, isSharedBranch } from "../shared/branches.js";
|
|
313
|
+
export { DEV, MAIN, isSharedBranch } from "../shared/branches.js";
|
|
292
314
|
/**
|
|
293
315
|
* Run a tool other than git, never throwing. Hook-exported GIT_* vars are scrubbed
|
|
294
316
|
* so gh and friends answer for `cwd`; `input` goes to stdin.
|
|
@@ -297,7 +319,7 @@ export function runTool(cmd, args, cwd, opts = {}) {
|
|
|
297
319
|
const res = spawnSync(cmd, args, {
|
|
298
320
|
cwd,
|
|
299
321
|
encoding: "utf-8",
|
|
300
|
-
env: gitEnv(),
|
|
322
|
+
env: { ...gitEnv(), ...opts.env },
|
|
301
323
|
input: opts.input,
|
|
302
324
|
maxBuffer: OUTPUT_LIMIT,
|
|
303
325
|
});
|
|
@@ -316,9 +338,9 @@ export function runTool(cmd, args, cwd, opts = {}) {
|
|
|
316
338
|
};
|
|
317
339
|
}
|
|
318
340
|
const signalNumber = (signal) => (signal ? os.constants.signals[signal] : undefined) ?? 1;
|
|
319
|
-
/** `gh <args>` in `cwd`, never throwing; `input` goes to stdin. */
|
|
320
|
-
export function runGh(cwd, args, input) {
|
|
321
|
-
const res = runTool("gh", args, cwd, { input });
|
|
341
|
+
/** `gh <args>` in `cwd`, never throwing; `input` goes to stdin; `env` is added to the child's. */
|
|
342
|
+
export function runGh(cwd, args, input, env) {
|
|
343
|
+
const res = runTool("gh", args, cwd, { input, env });
|
|
322
344
|
return {
|
|
323
345
|
ok: res.found && res.status === 0,
|
|
324
346
|
stdout: res.stdout.trim(),
|
|
@@ -343,6 +365,19 @@ export function repoRoot(cwd) {
|
|
|
343
365
|
throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
|
|
344
366
|
return path.dirname(common);
|
|
345
367
|
}
|
|
368
|
+
/** `<git common dir>/bkit-outbox`: per-run scratch files, never committed; null outside a git repo. */
|
|
369
|
+
export function outboxRoot(cwd) {
|
|
370
|
+
const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
|
|
371
|
+
return common ? path.join(common, "bkit-outbox") : null;
|
|
372
|
+
}
|
|
373
|
+
/** An outbox path as a committed record names it: relative to the main checkout, never a home path. */
|
|
374
|
+
export function outboxRel(cwd, file) {
|
|
375
|
+
const root = outboxRoot(cwd);
|
|
376
|
+
if (root === null)
|
|
377
|
+
return file;
|
|
378
|
+
const rel = path.relative(path.dirname(path.dirname(root)), file);
|
|
379
|
+
return rel.startsWith("..") || path.isAbsolute(rel) ? file : rel.split(path.sep).join("/");
|
|
380
|
+
}
|
|
346
381
|
/** `YYYYMM` in UTC, so every workflow picks the same month bucket at a month boundary. */
|
|
347
382
|
export function utcMonth(now = new Date()) {
|
|
348
383
|
return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
|
|
@@ -7,8 +7,10 @@
|
|
|
7
7
|
import { ciCommand } from "./ci/ci.js";
|
|
8
8
|
import { setupCommand } from "./setup/setup.js";
|
|
9
9
|
import { branchesCommand } from "./workflow/branches.js";
|
|
10
|
+
import { challengeCommand } from "./workflow/challenge.js";
|
|
10
11
|
import { contextCommand } from "./workflow/context.js";
|
|
11
12
|
import { countersCommand } from "./workflow/counters.js";
|
|
13
|
+
import { decisionsCommand } from "./workflow/decisions.js";
|
|
12
14
|
import { diskCommand } from "./workflow/disk.js";
|
|
13
15
|
import { fidsCommand } from "./workflow/fids.js";
|
|
14
16
|
import { issuesCommand } from "./workflow/issues.js";
|
|
@@ -34,6 +36,8 @@ export const COMMANDS = [
|
|
|
34
36
|
repoCommand,
|
|
35
37
|
fidsCommand,
|
|
36
38
|
testsCommand,
|
|
39
|
+
challengeCommand,
|
|
40
|
+
decisionsCommand,
|
|
37
41
|
locksCommand,
|
|
38
42
|
workflowsCommand,
|
|
39
43
|
worktreesCommand,
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// The policy also binds admins. `dev` is left unprotected — operators choose
|
|
6
6
|
// direct-push or feat/PR.
|
|
7
7
|
//
|
|
8
|
-
// The required check is `bkit.
|
|
8
|
+
// The required check is `bkit.testing.ciCapstone`, the always-on job that asserts every
|
|
9
9
|
// expected tier ran and passed, so "required check green" means validated, not
|
|
10
10
|
// merely "the tests job did not fail". Before requiring it the command checks a
|
|
11
11
|
// job by that name exists in the CI workflow: a required check no job produces
|
|
@@ -16,9 +16,9 @@ import { readBkitConfig } from "../../shared/settings.js";
|
|
|
16
16
|
import { CommandError, EXIT, parseJson, repoRoot, runGh, } from "../lib.js";
|
|
17
17
|
/** Exit code: `gh repo view` did not name the repository. */
|
|
18
18
|
export const EXIT_NO_REPO = 3;
|
|
19
|
-
/** Exit code: the CI workflow file named by `bkit.ciWorkflow` does not exist. */
|
|
19
|
+
/** Exit code: the CI workflow file named by `bkit.testing.ciWorkflow` does not exist. */
|
|
20
20
|
export const EXIT_NO_CI_WORKFLOW = 4;
|
|
21
|
-
/** Exit code: the CI workflow has no job named `bkit.
|
|
21
|
+
/** Exit code: the CI workflow has no job named `bkit.testing.ciCapstone`. */
|
|
22
22
|
export const EXIT_NO_CAPSTONE_JOB = 5;
|
|
23
23
|
/** Exit code: a `gh api` call failed. */
|
|
24
24
|
export const EXIT_GH_API_FAILED = 6;
|
|
@@ -138,8 +138,8 @@ export const setupCommand = {
|
|
|
138
138
|
output: {
|
|
139
139
|
repo: "owner/name the policy targets",
|
|
140
140
|
branch: "always main",
|
|
141
|
-
requiredCheck: "the required status check (bkit.
|
|
142
|
-
ciWorkflow: "the CI workflow checked for that job (bkit.ciWorkflow)",
|
|
141
|
+
requiredCheck: "the required status check (bkit.testing.ciCapstone)",
|
|
142
|
+
ciWorkflow: "the CI workflow checked for that job (bkit.testing.ciWorkflow)",
|
|
143
143
|
dryRun: "true with --dry-run",
|
|
144
144
|
applied: "true when the policy was written to GitHub",
|
|
145
145
|
payload: "the protection body sent (or that would be sent)",
|
|
@@ -148,8 +148,8 @@ export const setupCommand = {
|
|
|
148
148
|
},
|
|
149
149
|
exitCodes: {
|
|
150
150
|
[EXIT_NO_REPO]: "gh repo view could not name the repository",
|
|
151
|
-
[EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.ciWorkflow) does not exist",
|
|
152
|
-
[EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.
|
|
151
|
+
[EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.testing.ciWorkflow) does not exist",
|
|
152
|
+
[EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.testing.ciCapstone",
|
|
153
153
|
[EXIT_GH_API_FAILED]: "a gh api call failed",
|
|
154
154
|
},
|
|
155
155
|
run: protectMain,
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
// commands/stats.ts — `bkit stats`: this repo's stats report.
|
|
2
|
+
//
|
|
3
|
+
// Reads THIS repo's `.bkit/stats.jsonl`, `.bkit/friction.jsonl` and `docs/deferrals.jsonl`,
|
|
4
|
+
// runs the computations in commands/analysis.ts over them, writes `.bkit/stats.md` and
|
|
5
|
+
// prints it. Never reads another repo, chat history or `harvest/`: the cross-repo report is
|
|
6
|
+
// `harvest/stats.md`, written by the harvest script in bkit's own checkout.
|
|
7
|
+
//
|
|
8
|
+
// `.bkit/stats.md` is committed. It holds no timestamp, so it changes only when the ledgers do.
|
|
9
|
+
// `chat` / `run` rows left in `.bkit/stats.jsonl` (written there before they moved to
|
|
10
|
+
// `harvest/`) are not counted.
|
|
11
|
+
//
|
|
12
|
+
// Advisory + inform-only: never gates a workflow, always exits 0.
|
|
13
|
+
// See DE-34 for the shared-entrypoint + crash-isolation contract.
|
|
14
|
+
import * as fs from "node:fs";
|
|
15
|
+
import * as path from "node:path";
|
|
16
|
+
import { markdownTable } from "../shared/text.js";
|
|
17
|
+
import { runAnalysis } from "./analysis.js";
|
|
18
|
+
import { CHALLENGE_SMALL } from "./workflow/challenge.js";
|
|
19
|
+
/** The ledgers `bkit stats` reads, relative to the repo root. */
|
|
20
|
+
export const STATS_SOURCES = [
|
|
21
|
+
".bkit/stats.jsonl",
|
|
22
|
+
".bkit/friction.jsonl",
|
|
23
|
+
"docs/deferrals.jsonl",
|
|
24
|
+
];
|
|
25
|
+
/** Where `bkit stats` writes its report, relative to the repo root. */
|
|
26
|
+
export const STATS_REPORT = ".bkit/stats.md";
|
|
27
|
+
/** Kinds the harvest owns: never counted in a repo's own report. */
|
|
28
|
+
const HARVEST_KINDS = new Set(["chat", "run"]);
|
|
29
|
+
const pct = (rate) => `${(rate * 100).toFixed(1)}%`;
|
|
30
|
+
/** A markdown table under a prettier-ignore marker, or nothing when there are no rows. */
|
|
31
|
+
function table(head, rows) {
|
|
32
|
+
const lines = markdownTable(head, rows);
|
|
33
|
+
return lines.length === 0 ? [] : ["<!-- prettier-ignore -->", ...lines, ""];
|
|
34
|
+
}
|
|
35
|
+
/** Sorted `[key, count]` pairs of a count map, largest first, then by name. */
|
|
36
|
+
function ranked(counts) {
|
|
37
|
+
return Object.entries(counts).sort(([a, x], [b, y]) => y - x || a.localeCompare(b));
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The report as markdown sections under `## ` headings. `title` is the `# ` heading;
|
|
41
|
+
* `scope` the sentence under it saying which rows were read.
|
|
42
|
+
*/
|
|
43
|
+
export function renderStatsMarkdown(report, title, scope) {
|
|
44
|
+
const { counts, elapsed, regression, complianceRates, versionCompliance, deferralDiscipline } = report;
|
|
45
|
+
const out = [`# ${title}`, "", scope, ""];
|
|
46
|
+
out.push("## Rows", "");
|
|
47
|
+
if (counts.total === 0) {
|
|
48
|
+
out.push("No rows yet. Workflows append them at close.", "");
|
|
49
|
+
return out.join("\n");
|
|
50
|
+
}
|
|
51
|
+
out.push(...table(["Kind", "Rows"], ranked(counts.byKind)));
|
|
52
|
+
out.push(...table(["Workflow", "Rows"], ranked(counts.byWorkflow)));
|
|
53
|
+
if (Object.keys(counts.byRepo).length > 1) {
|
|
54
|
+
out.push(...table(["Repo", "Rows"], ranked(counts.byRepo)));
|
|
55
|
+
}
|
|
56
|
+
out.push("## Run durations", "");
|
|
57
|
+
if (elapsed.count === 0) {
|
|
58
|
+
out.push("No outcome row records a duration.", "");
|
|
59
|
+
}
|
|
60
|
+
else {
|
|
61
|
+
out.push(...table(["Runs", "Mean (min)", "Median (min)", "Min (min)", "Max (min)"], [
|
|
62
|
+
[
|
|
63
|
+
elapsed.count,
|
|
64
|
+
elapsed.meanMinutes.toFixed(1),
|
|
65
|
+
elapsed.p50Minutes.toFixed(1),
|
|
66
|
+
elapsed.minMinutes,
|
|
67
|
+
elapsed.maxMinutes,
|
|
68
|
+
],
|
|
69
|
+
]));
|
|
70
|
+
}
|
|
71
|
+
out.push("## Change size vs failures", "");
|
|
72
|
+
out.push(`A run counts as an error when it added failures. Dispatch-size threshold: ${regression.dispatchSizeThreshold} lines added.`, "");
|
|
73
|
+
out.push(...table(["Lines added", "Runs", "Errors", "Error rate"], regression.buckets
|
|
74
|
+
.filter((b) => b.count > 0)
|
|
75
|
+
.map((b) => [b.label, b.count, b.errorCount, pct(b.errorRate)])));
|
|
76
|
+
out.push(`Attempt counters: ${regression.shellBusCount} counted by the shell (trusted), ${regression.modelSelfReportCount} reported by the model (untrusted).`, "");
|
|
77
|
+
if (report.challengeGate.runs > 0) {
|
|
78
|
+
const g = report.challengeGate;
|
|
79
|
+
out.push("## Build challenge size", "");
|
|
80
|
+
out.push(`Small changes (under ${CHALLENGE_SMALL.lines} lines and ${CHALLENGE_SMALL.files} files) run the security reviewer alone.`, "");
|
|
81
|
+
out.push(...table(["Runs", "Small (challenge-1 skipped)", "Large"], [[g.runs, g.small, g.large]]));
|
|
82
|
+
}
|
|
83
|
+
const context = report.agentContext;
|
|
84
|
+
out.push("## Agent context peaks", "");
|
|
85
|
+
if (context.recorded === 0) {
|
|
86
|
+
out.push("No context data. A close records it from the Claude Code session that ran the workflow.", "");
|
|
87
|
+
}
|
|
88
|
+
else {
|
|
89
|
+
out.push(`Cap: ${context.cap} tokens per agent. ${context.recorded} of ${context.outcomes} runs recorded context.`, "");
|
|
90
|
+
out.push(...table(["Agent type", "Subagents", "Runs", "Peak (tokens)", "Runs over cap"], context.byAgent.map((a) => [a.agent, a.subagents, a.runs, a.peak, a.overCap])));
|
|
91
|
+
}
|
|
92
|
+
if (complianceRates.length > 0) {
|
|
93
|
+
out.push("## Compliance by rule", "");
|
|
94
|
+
out.push(...table(["Rule", "Pass", "Fail", "n/a", "Pass rate"], complianceRates.map((r) => [r.rule, r.passCount, r.failCount, r.naCount, pct(r.passRate)])));
|
|
95
|
+
}
|
|
96
|
+
if (versionCompliance.length > 0) {
|
|
97
|
+
out.push("## Compliance by bkit version", "");
|
|
98
|
+
out.push(...table(["Version", "Runs", "Pass rate"], versionCompliance.map((v) => [v.version, v.totalRuns, pct(v.passRate)])));
|
|
99
|
+
}
|
|
100
|
+
if (deferralDiscipline.length > 0) {
|
|
101
|
+
out.push("## Deferral discipline", "");
|
|
102
|
+
out.push("Deferrals adjudicated unjustified, by the writer that deferred.", "");
|
|
103
|
+
out.push(...table(["Writer", "Model", "Deferrals", "Unjustified", "Rate", "Reasons"], deferralDiscipline.map((d) => [
|
|
104
|
+
d.writer,
|
|
105
|
+
d.model,
|
|
106
|
+
d.total,
|
|
107
|
+
d.unjustifiedCount,
|
|
108
|
+
pct(d.unjustifiedRate),
|
|
109
|
+
Object.entries(d.byReason)
|
|
110
|
+
.sort(([a], [b]) => a.localeCompare(b))
|
|
111
|
+
.map(([reason, n]) => `${reason}=${n}`)
|
|
112
|
+
.join(" "),
|
|
113
|
+
])));
|
|
114
|
+
}
|
|
115
|
+
return out.join("\n").replace(/\n+$/, "\n");
|
|
116
|
+
}
|
|
117
|
+
/** Build this repo's report from the ledgers under `root`. */
|
|
118
|
+
export function buildRepoStats(root) {
|
|
119
|
+
const files = STATS_SOURCES.map((rel) => path.join(root, rel)).filter((p) => fs.existsSync(p));
|
|
120
|
+
return renderStatsMarkdown(runAnalysis(files, HARVEST_KINDS), "bkit stats", `This repo only: ${STATS_SOURCES.map((s) => `\`${s}\``).join(", ")}. Written by \`bkit stats\`; workflow closes append the rows.`);
|
|
121
|
+
}
|
|
122
|
+
// stats — this repo's stats report. Advisory + inform-only: exits 0.
|
|
123
|
+
// See DE-34 for the shared-entrypoint + crash-isolation contract.
|
|
124
|
+
export function runStatsCommand() {
|
|
125
|
+
try {
|
|
126
|
+
const root = process.cwd();
|
|
127
|
+
const markdown = buildRepoStats(root);
|
|
128
|
+
fs.writeFileSync(path.join(root, STATS_REPORT), markdown, "utf-8");
|
|
129
|
+
console.log(markdown);
|
|
130
|
+
console.error(`[bkit-stats] wrote ${STATS_REPORT}`);
|
|
131
|
+
}
|
|
132
|
+
catch (err) {
|
|
133
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
134
|
+
console.error(`[bkit-stats] stats error (fail-open): ${msg}`);
|
|
135
|
+
}
|
|
136
|
+
}
|
package/dist/commands/tips.js
CHANGED
|
@@ -2,16 +2,20 @@
|
|
|
2
2
|
// apply to this repo. Each workflow passes its name at its close and gets the one tip that
|
|
3
3
|
// matters most there (`audit` / `utility` for the audit agent and the ledger / roadmap
|
|
4
4
|
// updaters); bare `bkit tips` prints the top three. The star line closes bare and phase
|
|
5
|
-
// output unless `bkit-star` is in `bkit.
|
|
5
|
+
// output unless `bkit-star` is in `bkit.advisories.ignore`. Local checks only, no network; prints
|
|
6
6
|
// nothing when no tip fires and no star line shows; exits 0. What the last disk clean-up left
|
|
7
7
|
// for the person to decide (`bkit disk prune` notes) comes first, outside the tip cap.
|
|
8
8
|
import { collectTips, formatTips } from "../checks/tips/index.js";
|
|
9
9
|
import { formatNotes, readNotes } from "./workflow/disk.js";
|
|
10
|
-
|
|
10
|
+
/** What `bkit tips` prints: disk-prune notes, then the tips; "" when nothing applies. */
|
|
11
|
+
export function tipsText(all, workflow, cwd) {
|
|
11
12
|
const { tips, star } = collectTips(cwd);
|
|
12
|
-
|
|
13
|
+
return [formatNotes(readNotes(cwd)), formatTips(tips, { all, workflow, star })]
|
|
13
14
|
.filter((part) => part !== "")
|
|
14
15
|
.join("\n\n");
|
|
16
|
+
}
|
|
17
|
+
export function runTipsCommand(all, workflow, cwd = process.cwd()) {
|
|
18
|
+
const output = tipsText(all, workflow, cwd);
|
|
15
19
|
if (output)
|
|
16
20
|
console.log(output);
|
|
17
21
|
}
|