@cbartens/bkit 5.2.3 → 5.3.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 +29 -12
- package/.bkit/core/.agents/context.md +1 -1
- package/.bkit/core/.agents/docs.md +1 -1
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.agents/rules.md +11 -0
- package/.bkit/core/.bkit/README.md +28 -11
- package/.bkit/core/.bkit/cloud.md +9 -8
- package/.bkit/core/.bkit/comparison.md +68 -345
- package/.bkit/core/.bkit/install.md +15 -9
- package/.bkit/core/.bkit/lite.md +73 -0
- package/.bkit/core/.bkit/pipeline.md +345 -0
- package/.bkit/core/.bkit/prompts.md +88 -73
- package/.bkit/core/.bkit/providers.md +41 -22
- package/.bkit/core/.bkit/templates.md +125 -18
- package/.bkit/core/.bkit/trackers.md +47 -1
- package/.bkit/core/.bkit/workflows.md +51 -45
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +22 -10
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +29 -15
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +11 -3
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +19 -9
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-security.md +13 -5
- package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +14 -5
- package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
- package/.bkit/core/docs/templates/bkit-plan.md +8 -6
- package/.bkit/core/engine/checks/after/auth.ts +9 -9
- package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
- package/.bkit/core/engine/checks/after/github.ts +29 -120
- package/.bkit/core/engine/checks/after/index.ts +2 -2
- package/.bkit/core/engine/checks/after/managed.ts +8 -28
- package/.bkit/core/engine/checks/after/tools.ts +3 -15
- package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
- package/.bkit/core/engine/checks/before/index.ts +7 -43
- package/.bkit/core/engine/checks/before/mcp.ts +17 -8
- package/.bkit/core/engine/checks/before/repo.ts +9 -12
- package/.bkit/core/engine/checks/status-holes.ts +4 -5
- package/.bkit/core/engine/checks/tips/catalogue.ts +70 -24
- package/.bkit/core/engine/checks/tips/detect.ts +45 -2
- package/.bkit/core/engine/checks/tips/index.ts +37 -8
- package/.bkit/core/engine/cli.ts +39 -16
- package/.bkit/core/engine/commands/analysis.ts +36 -26
- package/.bkit/core/engine/commands/comply.ts +17 -16
- package/.bkit/core/engine/commands/harvest.ts +12 -12
- package/.bkit/core/engine/commands/install/doctor.ts +57 -28
- package/.bkit/core/engine/commands/install/install.ts +62 -126
- package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
- package/.bkit/core/engine/commands/install/upgrade.ts +58 -53
- package/.bkit/core/engine/commands/lib.ts +35 -10
- package/.bkit/core/engine/commands/tips.ts +8 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +65 -11
- package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
- package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +4 -2
- package/.bkit/core/engine/commands/workflow/repo.ts +18 -4
- package/.bkit/core/engine/commands/workflow/roadmap.ts +4 -3
- package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
- package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
- package/.bkit/core/engine/commands/workflow/workflows.ts +19 -17
- package/.bkit/core/engine/commands/workflow/workstreams.ts +2 -1
- package/.bkit/core/engine/commands/workflow/worktrees.ts +13 -5
- package/.bkit/core/engine/install/cloud-env.ts +10 -31
- package/.bkit/core/engine/install/manifest.ts +14 -7
- package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
- package/.bkit/core/engine/install/modules/claude.ts +20 -28
- package/.bkit/core/engine/install/modules/cloud.ts +5 -2
- package/.bkit/core/engine/install/modules/codex.ts +15 -29
- package/.bkit/core/engine/install/modules/core.ts +91 -70
- package/.bkit/core/engine/install/modules/cursor.ts +6 -20
- package/.bkit/core/engine/install/modules/index.ts +7 -1
- package/.bkit/core/engine/install/modules/opencode.ts +48 -70
- package/.bkit/core/engine/install/network-allowlist.ts +73 -0
- package/.bkit/core/engine/install/placeholders.ts +3 -18
- package/.bkit/core/engine/install/write.ts +59 -12
- package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
- package/.bkit/core/engine/render/hosts.ts +47 -67
- package/.bkit/core/engine/render/models.ts +29 -11
- package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
- package/.bkit/core/engine/shared/branches.ts +13 -0
- package/.bkit/core/engine/shared/egress.ts +3 -3
- package/.bkit/core/engine/shared/json.ts +18 -1
- package/.bkit/core/engine/shared/package-json.ts +63 -0
- package/.bkit/core/engine/shared/package-roots.ts +0 -10
- package/.bkit/core/engine/shared/protected-paths.ts +5 -130
- package/.bkit/core/engine/shared/settings.ts +36 -0
- package/.bkit/core/engine/shared/timeouts.ts +6 -0
- package/.bkit/core/hooks/antigravity-hook.js +1 -0
- package/.bkit/core/hooks/guardrails-shell.js +186 -40
- package/.bkit/core/hooks/guardrails-tiers.js +5 -78
- package/.bkit/core/prompts/bkit-audit-generate.md +65 -10
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
- package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
- package/.bkit/core/prompts/bkit-design-spike.md +1 -1
- package/.bkit/core/prompts/bkit-design-summary.md +2 -2
- package/.bkit/core/prompts/bkit-design-update.md +1 -1
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
- package/.bkit/core/prompts/bkit-plan-update.md +1 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
- package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
- package/.bkit/core/workflows/bkit-build.md +4 -4
- package/.bkit/core/workflows/bkit-debug.md +70 -34
- package/.bkit/core/workflows/bkit-design.md +3 -3
- package/.bkit/core/workflows/bkit-plan.md +12 -5
- package/.bkit/core/workflows/bkit-ship.md +6 -6
- package/.bkit/shared/.claude/bkit-cloud.md +46 -13
- package/.bkit/shared/.claude/settings.json +18 -0
- package/.bkit/shared/.cursor/mcp.json +2 -1
- package/.bkit/shared/.opencode/opencode.json +19 -1
- package/.bkit/shared/docs/deployments.md +20 -4
- package/.bkit/shared/docs/security.md +8 -6
- package/.bkit/shared/docs/testing.md +9 -5
- package/.bkit/templates/.cursor/Dockerfile +30 -16
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
- package/.bkit/templates/.github/renovate.json5 +91 -12
- package/.bkit/templates/.github/workflows/bkit-ci.yml +66 -53
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
- package/.bkit/templates/.husky/pre-push +15 -3
- package/.bkit/templates/.oxlintrc.json +21 -0
- package/.bkit/templates/docs/capabilities.md +1 -1
- package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
- package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
- package/CHANGELOG.md +67 -3
- package/README.md +258 -129
- package/dist/checks/after/auth.js +10 -11
- package/dist/checks/after/ci-yml.js +11 -14
- package/dist/checks/after/github.js +32 -125
- package/dist/checks/after/index.js +3 -2
- package/dist/checks/after/managed.js +8 -24
- package/dist/checks/after/tools.js +3 -16
- package/dist/checks/before/context-fetch.js +1 -21
- package/dist/checks/before/index.js +6 -42
- package/dist/checks/before/mcp.js +14 -9
- package/dist/checks/before/repo.js +8 -11
- package/dist/checks/status-holes.js +5 -6
- package/dist/checks/tips/catalogue.js +60 -18
- package/dist/checks/tips/detect.js +41 -2
- package/dist/checks/tips/index.js +25 -5
- package/dist/cli.js +34 -14
- package/dist/commands/analysis.js +21 -5
- package/dist/commands/comply.js +20 -18
- package/dist/commands/harvest.js +12 -13
- package/dist/commands/install/doctor.js +55 -23
- package/dist/commands/install/install.js +62 -118
- package/dist/commands/install/uninstall.js +165 -31
- package/dist/commands/install/upgrade.js +55 -49
- package/dist/commands/lib.js +32 -10
- package/dist/commands/tips.js +6 -3
- package/dist/commands/workflow/branches.js +57 -13
- package/dist/commands/workflow/counters.js +17 -7
- package/dist/commands/workflow/fids.js +39 -0
- package/dist/commands/workflow/ledgers.js +3 -1
- package/dist/commands/workflow/prs.js +3 -3
- package/dist/commands/workflow/repo.js +16 -4
- package/dist/commands/workflow/roadmap.js +4 -4
- package/dist/commands/workflow/runs.js +5 -5
- package/dist/commands/workflow/steps.js +1 -0
- package/dist/commands/workflow/tests.js +16 -3
- package/dist/commands/workflow/workflows.js +19 -18
- package/dist/commands/workflow/workstreams.js +2 -1
- package/dist/commands/workflow/worktrees.js +4 -5
- package/dist/install/cloud-env.js +10 -23
- package/dist/install/manifest.js +14 -7
- package/dist/install/modules/antigravity.js +15 -26
- package/dist/install/modules/claude.js +17 -21
- package/dist/install/modules/cloud.js +6 -2
- package/dist/install/modules/codex.js +15 -29
- package/dist/install/modules/core.js +82 -63
- package/dist/install/modules/cursor.js +6 -9
- package/dist/install/modules/index.js +6 -1
- package/dist/install/modules/opencode.js +41 -72
- package/dist/install/network-allowlist.js +62 -0
- package/dist/install/placeholders.js +3 -16
- package/dist/install/write.js +55 -15
- package/dist/ledgers/telemetry.js +5 -4
- package/dist/render/hosts.js +30 -55
- package/dist/render/models.js +20 -9
- package/dist/shared/bkit-latest.js +150 -0
- package/dist/shared/branches.js +11 -0
- package/dist/shared/egress.js +0 -2
- package/dist/shared/json.js +14 -0
- package/dist/shared/package-json.js +61 -0
- package/dist/shared/package-roots.js +0 -8
- package/dist/shared/protected-paths.js +5 -122
- package/dist/shared/settings.js +18 -1
- package/dist/shared/timeouts.js +6 -0
- package/package.json +21 -17
- package/.bkit/core/.agents/shortcuts.md +0 -73
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
5
|
import { spawnSync } from "node:child_process";
|
|
6
|
+
import { readJsonFile } from "../../shared/json.js";
|
|
6
7
|
import { isCloudOrCi } from "./env.js";
|
|
7
8
|
// ---------------------------------------------------------------------------
|
|
8
9
|
// Blocker detectors
|
|
@@ -21,18 +22,14 @@ export function detectMalformedPackageJson(cwd) {
|
|
|
21
22
|
const pkgPath = path.join(cwd, "package.json");
|
|
22
23
|
if (!fs.existsSync(pkgPath))
|
|
23
24
|
return null;
|
|
24
|
-
|
|
25
|
-
JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
|
|
25
|
+
if (readJsonFile(pkgPath).ok)
|
|
26
26
|
return null;
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
|
|
34
|
-
};
|
|
35
|
-
}
|
|
27
|
+
return {
|
|
28
|
+
id: "malformed-package-json",
|
|
29
|
+
severity: "blocker",
|
|
30
|
+
detect: "package.json exists but contains invalid JSON.",
|
|
31
|
+
action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
|
|
32
|
+
};
|
|
36
33
|
}
|
|
37
34
|
export function detectNotGitRepo(cwd, modules) {
|
|
38
35
|
if (!modules.has("core"))
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
import * as fs from "node:fs";
|
|
26
26
|
import * as path from "node:path";
|
|
27
27
|
import { fileURLToPath } from "node:url";
|
|
28
|
+
import { parseJson } from "../shared/json.js";
|
|
28
29
|
import { getWorkflowsRoot } from "../shared/package-roots.js";
|
|
29
30
|
// ---------------------------------------------------------------------------
|
|
30
31
|
// Canonical ship step order (mirrors audits/workflows/ship-invariants.test.ts
|
|
@@ -274,12 +275,10 @@ export function auditStatusJsonl(statusJsonl, shipMd) {
|
|
|
274
275
|
const trimmed = line.trim();
|
|
275
276
|
if (!trimmed)
|
|
276
277
|
continue;
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
void _e; // skip unparseable lines (advisory — never throw)
|
|
282
|
-
}
|
|
278
|
+
// Unparseable lines are skipped (advisory — never throw).
|
|
279
|
+
const row = parseJson(trimmed);
|
|
280
|
+
if (row.ok)
|
|
281
|
+
rows.push(row.value);
|
|
283
282
|
}
|
|
284
283
|
// Filter to ship step-done rows + workflow-failed rows
|
|
285
284
|
const shipStepRows = rows.filter((r) => r.type === "step-done" && r.workflow === "ship" && typeof r.step === "string");
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
// checks/tips/catalogue.ts — the setup-tip catalogue: one entry per template, tool or
|
|
2
|
-
// setting a consumer has not set up yet. Each workflow
|
|
3
|
-
// (`bkit tips --workflow=<name
|
|
4
|
-
//
|
|
2
|
+
// setting a consumer has not set up yet. Each workflow, `@bkit-audit-generate` and the
|
|
3
|
+
// ledger / roadmap updaters print one tip at their close (`bkit tips --workflow=<name>`,
|
|
4
|
+
// `audit` / `utility` for the agents); `bkit tips` prints the top three;
|
|
5
|
+
// `.bkit/advisories.md` lists every firing tip under `Setup tips`.
|
|
5
6
|
//
|
|
6
7
|
// Array order is the priority: comms first (can workflows reach anything), then change
|
|
7
8
|
// quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
|
|
8
9
|
// setup-specific plumbing last. `workflows` names where a tip matters: a workflow shows
|
|
9
|
-
// its own tips first, in array order, then the rest. Comms tips name every
|
|
10
|
+
// its own tips first, in array order, then the rest. Comms tips name every context, so
|
|
10
11
|
// they lead everywhere until fixed.
|
|
11
12
|
//
|
|
12
13
|
// Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
|
|
@@ -22,19 +23,21 @@
|
|
|
22
23
|
import { detectContextFetchMissing } from "../before/context-fetch.js";
|
|
23
24
|
import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
|
|
24
25
|
import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
|
|
25
|
-
import { buildTrackerSetupAdvisory
|
|
26
|
+
import { buildTrackerSetupAdvisory } from "../after/github.js";
|
|
26
27
|
import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
|
|
27
28
|
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
28
29
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
29
|
-
import { claudeSettingsHas, codexTopLevelHas, exists, hasLintStagedConfig, hasMcpServer, unlockedMcpServers, } from "./detect.js";
|
|
30
|
+
import { anyWorkflowMentions, claudeSettingsHas, codexTopLevelHas, exists, hasJsTestRunner, hasLintStagedConfig, hasMcpServer, hasTestLinter, unlockedMcpServers, } from "./detect.js";
|
|
30
31
|
const hosts = (cwd) => detectInstalledHostModules(cwd);
|
|
31
32
|
/** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
|
|
32
33
|
export const ALL_WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
|
|
34
|
+
/** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
|
|
35
|
+
export const EVERY_CONTEXT = [...ALL_WORKFLOWS, "audit", "utility"];
|
|
33
36
|
export const SETUP_TIPS = [
|
|
34
37
|
// --- connect: can bkit talk to anything at all -------------------------------------
|
|
35
38
|
{
|
|
36
39
|
id: "tracker",
|
|
37
|
-
workflows:
|
|
40
|
+
workflows: EVERY_CONTEXT,
|
|
38
41
|
title: "Connect an issue tracker",
|
|
39
42
|
line: "bkit isn't connected to an issue tracker, so it can't read the task it's working on or record what it did. Connect GitHub or Linear, or switch this tip off if you don't want one.",
|
|
40
43
|
why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
|
|
@@ -45,19 +48,19 @@ export const SETUP_TIPS = [
|
|
|
45
48
|
},
|
|
46
49
|
{
|
|
47
50
|
id: "gh-mcp",
|
|
48
|
-
workflows:
|
|
51
|
+
workflows: EVERY_CONTEXT,
|
|
49
52
|
title: "Give bkit its GitHub token",
|
|
50
53
|
line: "You chose GitHub as your tracker, but bkit has no GitHub token, so every attempt to read an issue or open a pull request will fail. Add the token.",
|
|
51
54
|
why: "Choosing GitHub only tells bkit where your issues live. The token is what lets it actually sign in. Without it the setting looks right but nothing works, which is confusing to track down.",
|
|
52
55
|
ask: "Add my GitHub token as `BKIT_GH_TOKEN` in .bkit/.env, check .mcp.json has the `github` server, then run `direnv allow` and tell me to restart the editor.",
|
|
53
56
|
steps: "`.bkit/install.md` § Local env setup. The `github` server entry belongs in `.mcp.json` / `.cursor/mcp.json` (`.bkit/cloud.md` § MCP issue-tracker integration).",
|
|
54
57
|
advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
|
|
55
|
-
fires: (cwd) =>
|
|
58
|
+
fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" &&
|
|
56
59
|
(!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
|
|
57
60
|
},
|
|
58
61
|
{
|
|
59
62
|
id: "bkit-env",
|
|
60
|
-
workflows:
|
|
63
|
+
workflows: EVERY_CONTEXT,
|
|
61
64
|
title: "Create bkit's private settings file",
|
|
62
65
|
line: "bkit's private settings file (.bkit/.env) is missing or has blank entries, so nothing that needs to sign in can. Create it and fill it in.",
|
|
63
66
|
why: "This one file holds the sign-in tokens every bkit tool reads. It's never shared or committed. Most other tips depend on it, so do this one early.",
|
|
@@ -67,13 +70,13 @@ export const SETUP_TIPS = [
|
|
|
67
70
|
fires: (cwd) => {
|
|
68
71
|
if (isCloudOrCi())
|
|
69
72
|
return false;
|
|
70
|
-
const tracker =
|
|
73
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
71
74
|
return (detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0);
|
|
72
75
|
},
|
|
73
76
|
},
|
|
74
77
|
{
|
|
75
78
|
id: "direnv",
|
|
76
|
-
workflows:
|
|
79
|
+
workflows: EVERY_CONTEXT,
|
|
77
80
|
title: "Load your tokens automatically",
|
|
78
81
|
line: "Your sign-in tokens are saved in .bkit/.env but not being loaded, so sign-ins will fail even though the file looks right. Set up direnv so they load whenever you open the project.",
|
|
79
82
|
why: "A saved file does nothing until something reads it. This is the most frustrating kind of breakage: nothing looks wrong, but every sign-in fails. direnv (a small tool that loads settings when you open a folder) fixes it once.",
|
|
@@ -83,7 +86,7 @@ export const SETUP_TIPS = [
|
|
|
83
86
|
fires: (cwd) => {
|
|
84
87
|
if (isCloudOrCi() || !exists(cwd, ".bkit/.env"))
|
|
85
88
|
return false;
|
|
86
|
-
const tracker =
|
|
89
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
87
90
|
return (!exists(cwd, ".envrc") ||
|
|
88
91
|
detectDirenvMissing(cwd, tracker) !== null ||
|
|
89
92
|
detectDirenvNotAllowed(cwd, tracker) !== null);
|
|
@@ -92,7 +95,7 @@ export const SETUP_TIPS = [
|
|
|
92
95
|
// --- quality: is the change good -----------------------------------------------------
|
|
93
96
|
{
|
|
94
97
|
id: "serena",
|
|
95
|
-
workflows: ["design", "plan", "build"],
|
|
98
|
+
workflows: ["design", "plan", "build", "audit", "utility"],
|
|
96
99
|
title: "Let agents look code up directly",
|
|
97
100
|
line: "Agents are finding code by searching for words, which is slower, costs more, and misses things. Set up Serena so they can look code up directly.",
|
|
98
101
|
why: 'Serena lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of guessing from text search and reading whole files. That means fewer accidental changes, fewer rounds of you correcting them, and lower running costs because they read less. It can only look things up, never change your files.',
|
|
@@ -102,7 +105,7 @@ export const SETUP_TIPS = [
|
|
|
102
105
|
},
|
|
103
106
|
{
|
|
104
107
|
id: "ci-workflow",
|
|
105
|
-
workflows: ["build", "ship"],
|
|
108
|
+
workflows: ["build", "ship", "audit"],
|
|
106
109
|
title: "Automatic checks on every change",
|
|
107
110
|
line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
|
|
108
111
|
why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
|
|
@@ -140,6 +143,16 @@ export const SETUP_TIPS = [
|
|
|
140
143
|
steps: "`.bkit/templates.md` § slop-scan.",
|
|
141
144
|
fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
|
|
142
145
|
},
|
|
146
|
+
{
|
|
147
|
+
id: "test-lint",
|
|
148
|
+
workflows: ["build"],
|
|
149
|
+
title: "Catch tests that can't fail",
|
|
150
|
+
line: "Nothing checks your test files, so a test that asserts nothing, or asserts only inside an if, still passes and the suite stays green having proved nothing. Add Oxlint with bkit's test rules.",
|
|
151
|
+
why: "Oxlint (a fast code linter) fails the check on a test with no assertion, a branch inside a test, an assertion that may never run, a malformed assertion, or a promise nobody waits for. Without it those tests pass whatever the code does.",
|
|
152
|
+
ask: "Run `pnpm add -D oxlint oxlint-tsgolint`, copy .bkit/templates/.oxlintrc.json to .oxlintrc.json, and set the `lint` script in package.json to run `oxlint -c .oxlintrc.json --type-aware --deny-warnings` (add `&&` and the current lint command if the script already has one). Then fix every hit in the tests themselves.",
|
|
153
|
+
steps: "`.bkit/templates.md` § Oxlint.",
|
|
154
|
+
fires: (cwd) => hasJsTestRunner(cwd) && !hasTestLinter(cwd),
|
|
155
|
+
},
|
|
143
156
|
{
|
|
144
157
|
id: "vale",
|
|
145
158
|
workflows: ["design", "plan"],
|
|
@@ -170,7 +183,7 @@ export const SETUP_TIPS = [
|
|
|
170
183
|
ask: "Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml and .bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh to .claude/hooks/ (for Cursor: .bkit/templates/.cursor/environment.json and .bkit/templates/.cursor/Dockerfile to .cursor/), run `gh secret set ANTHROPIC_API_KEY`, then tell me which dashboard settings are left.",
|
|
171
184
|
steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
|
|
172
185
|
fires: (cwd) => {
|
|
173
|
-
const cloud =
|
|
186
|
+
const cloud = readBkitConfig(cwd).cloudAgents;
|
|
174
187
|
if (cloud === "none")
|
|
175
188
|
return false;
|
|
176
189
|
if (cloud === "cursor") {
|
|
@@ -239,9 +252,19 @@ export const SETUP_TIPS = [
|
|
|
239
252
|
fires: (cwd) => hosts(cwd).has("claude") && !claudeSettingsHas(cwd, "disableClaudeAiConnectors"),
|
|
240
253
|
},
|
|
241
254
|
// --- optional: nice to have ------------------------------------------------------------
|
|
255
|
+
{
|
|
256
|
+
id: "issue-forms",
|
|
257
|
+
workflows: ["design", "plan", "debug"],
|
|
258
|
+
title: "Issue forms",
|
|
259
|
+
line: "Optional: add issue forms so every new issue asks for what the agent reads first.",
|
|
260
|
+
why: "Each workflow starts from the issue. A form for an idea, a well-defined change or a bug asks for the problem, what done looks like, or the steps to reproduce. Without one, issues often arrive as a title and a line, and the agent has to guess.",
|
|
261
|
+
ask: "Copy .bkit/templates/.github/ISSUE_TEMPLATE/ to .github/ISSUE_TEMPLATE/ and commit it to the default branch.",
|
|
262
|
+
steps: "`.bkit/templates.md` § Issue forms.",
|
|
263
|
+
fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" && !exists(cwd, ".github/ISSUE_TEMPLATE"),
|
|
264
|
+
},
|
|
242
265
|
{
|
|
243
266
|
id: "graphify",
|
|
244
|
-
workflows: ["design", "plan"],
|
|
267
|
+
workflows: ["design", "plan", "audit"],
|
|
245
268
|
title: "A map of the code",
|
|
246
269
|
line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
|
|
247
270
|
why: "With a map, agents check what already exists before building it again. Without one, agents and reviews work out the structure from scratch each time. That's slower, and it's easy to miss how one change ripples into another part of the code.",
|
|
@@ -251,7 +274,7 @@ export const SETUP_TIPS = [
|
|
|
251
274
|
},
|
|
252
275
|
{
|
|
253
276
|
id: "dependabot-renovate",
|
|
254
|
-
workflows: ["ship"],
|
|
277
|
+
workflows: ["ship", "audit"],
|
|
255
278
|
title: "Automatic updates",
|
|
256
279
|
line: "Nothing keeps the project's libraries up to date. Add an updater so you get small, safe updates instead of one big risky one later.",
|
|
257
280
|
why: "An updater opens a small pull request whenever a library you use has a new version. Skip it and updates pile up into one large upgrade that's far more likely to break something.",
|
|
@@ -260,6 +283,16 @@ export const SETUP_TIPS = [
|
|
|
260
283
|
advisories: ["dep-updater-absent"],
|
|
261
284
|
fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
|
|
262
285
|
},
|
|
286
|
+
{
|
|
287
|
+
id: "trivy",
|
|
288
|
+
workflows: ["ship", "audit"],
|
|
289
|
+
title: "Security scan",
|
|
290
|
+
line: "Nothing stops a change that adds a known-vulnerable library, a risky container setting or a leaked password from merging. Add the scan that fails the check when it finds one.",
|
|
291
|
+
why: "An updater only offers fixes, and only once a fixed version exists. The scan checks every change, plus once a day, so a known problem fails the check before it merges and one with no fix yet still shows up.",
|
|
292
|
+
ask: "Copy .bkit/templates/.github/workflows/bkit-trivy.yml to .github/workflows/bkit-trivy.yml, replace {{DEFAULT_BRANCH}} with my default branch, and commit it.",
|
|
293
|
+
steps: "`.bkit/templates.md` § Trivy. Accept a finding in `.trivyignore.yaml` with `statement` + `expired_at`; never drop `--include-dev-deps`.",
|
|
294
|
+
fires: (cwd) => exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
|
|
295
|
+
},
|
|
263
296
|
{
|
|
264
297
|
id: "prettier-tables",
|
|
265
298
|
workflows: ["design", "plan"],
|
|
@@ -270,6 +303,15 @@ export const SETUP_TIPS = [
|
|
|
270
303
|
steps: "`.bkit/templates.md` § Prettier tables.",
|
|
271
304
|
fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
|
|
272
305
|
},
|
|
306
|
+
{
|
|
307
|
+
id: "tmp-prune",
|
|
308
|
+
title: "Clear out old scratch files",
|
|
309
|
+
line: "Scratch files agents leave in tmp/ are never cleared, so the folder keeps growing. Add the clean-up that runs when you push.",
|
|
310
|
+
why: "Agents leave logs and scratch files in tmp/ on every run. Each push deletes the ones untouched for a week, so the folder stays small without anyone thinking about it.",
|
|
311
|
+
ask: "Copy .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs to scripts/cleanup/, then copy the `tmp/ prune` block from .bkit/templates/.husky/pre-push into .husky/pre-push above the gates.",
|
|
312
|
+
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
313
|
+
fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
314
|
+
},
|
|
273
315
|
// --- setup: only some setups -----------------------------------------------------------
|
|
274
316
|
{
|
|
275
317
|
id: "cursor-files",
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
// checks/tips/detect.ts — local-only probes the setup-tip catalogue keys on: host MCP
|
|
2
|
-
// configs, host settings files, lint-staged config forms. No network.
|
|
2
|
+
// configs, host settings files, lint-staged and test-linter config forms. No network.
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
5
|
import { parseJson } from "../../shared/json.js";
|
|
6
|
-
import { readPackageJson } from "../../shared/package-json.js";
|
|
6
|
+
import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
|
|
7
7
|
/** True when `rel` exists under `cwd`. */
|
|
8
8
|
export const exists = (cwd, rel) => fs.existsSync(path.join(cwd, rel));
|
|
9
9
|
/** Parsed JSON object at `rel`, or `null` when absent, unparseable or not an object. */
|
|
@@ -121,6 +121,16 @@ const LINT_STAGED_CONFIGS = [
|
|
|
121
121
|
"lint-staged.config.cjs",
|
|
122
122
|
"lint-staged.config.js",
|
|
123
123
|
];
|
|
124
|
+
/** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
|
|
125
|
+
export function anyWorkflowMentions(cwd, needle) {
|
|
126
|
+
const dir = path.join(cwd, ".github", "workflows");
|
|
127
|
+
if (!fs.existsSync(dir))
|
|
128
|
+
return false;
|
|
129
|
+
return fs
|
|
130
|
+
.readdirSync(dir)
|
|
131
|
+
.filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
|
|
132
|
+
.some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
|
|
133
|
+
}
|
|
124
134
|
/** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
|
|
125
135
|
export function hasLintStagedConfig(cwd) {
|
|
126
136
|
if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel)))
|
|
@@ -128,3 +138,32 @@ export function hasLintStagedConfig(cwd) {
|
|
|
128
138
|
const pkg = readPackageJson(cwd);
|
|
129
139
|
return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
|
|
130
140
|
}
|
|
141
|
+
const OXLINT_CONFIGS = [
|
|
142
|
+
".oxlintrc.json",
|
|
143
|
+
...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `oxlint.config.${ext}`),
|
|
144
|
+
];
|
|
145
|
+
const ESLINT_CONFIGS = [
|
|
146
|
+
".eslintrc",
|
|
147
|
+
...["json", "js", "cjs", "yaml", "yml"].map((ext) => `.eslintrc.${ext}`),
|
|
148
|
+
...["js", "mjs", "cjs", "ts", "mts", "cts"].map((ext) => `eslint.config.${ext}`),
|
|
149
|
+
];
|
|
150
|
+
/** A test-framework or test-library name inside an ESLint config means it lints tests. */
|
|
151
|
+
const TEST_LINT_PLUGIN = /vitest|jest|playwright|testing-library/i;
|
|
152
|
+
/** True when `package.json` lists a JS / TS test runner (Vitest or Jest) as a dependency. */
|
|
153
|
+
export const hasJsTestRunner = (cwd) => readDependencyNames(cwd).some((name) => name === "vitest" || name === "jest");
|
|
154
|
+
/**
|
|
155
|
+
* True when the repo already lints its test files: an Oxlint config or `oxlint` dependency,
|
|
156
|
+
* or an ESLint config (file or `package.json` `eslintConfig`) that names a test plugin.
|
|
157
|
+
*/
|
|
158
|
+
export function hasTestLinter(cwd) {
|
|
159
|
+
if (OXLINT_CONFIGS.some((rel) => exists(cwd, rel)))
|
|
160
|
+
return true;
|
|
161
|
+
if (readDependencyNames(cwd).includes("oxlint"))
|
|
162
|
+
return true;
|
|
163
|
+
const eslintConfigs = ESLINT_CONFIGS.map((rel) => readText(cwd, rel));
|
|
164
|
+
const pkg = readPackageJson(cwd);
|
|
165
|
+
if (pkg.ok && pkg.pkg["eslintConfig"] !== undefined) {
|
|
166
|
+
eslintConfigs.push(JSON.stringify(pkg.pkg["eslintConfig"]));
|
|
167
|
+
}
|
|
168
|
+
return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
|
|
169
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
|
|
2
2
|
// console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
|
|
3
3
|
import { ignoredAdvisoryIds, } from "../after/suppression.js";
|
|
4
|
-
import { SETUP_TIPS } from "./catalogue.js";
|
|
4
|
+
import { ALL_WORKFLOWS, SETUP_TIPS } from "./catalogue.js";
|
|
5
5
|
/** Tips `bkit tips` prints without `--all` or `--workflow`. */
|
|
6
6
|
export const TIPS_CAP = 3;
|
|
7
7
|
/** Tips a workflow prints at its close (`bkit tips --workflow=<name>`). */
|
|
@@ -12,6 +12,14 @@ export const SETUP_TIPS_HEADING = "Setup tips";
|
|
|
12
12
|
export const tipsIntro = (n) => n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
|
|
13
13
|
/** Where the full tip list lives. */
|
|
14
14
|
export const TIPS_DETAILS_POINTER = "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
|
|
15
|
+
/** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
|
|
16
|
+
export const STAR_TIP_ID = "star";
|
|
17
|
+
/**
|
|
18
|
+
* Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
|
|
19
|
+
* workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
|
|
20
|
+
* gap, so never in the checklist.
|
|
21
|
+
*/
|
|
22
|
+
export const STAR_TIP = "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
|
|
15
23
|
/** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
|
|
16
24
|
export const TIPS_SECTION_INTRO = "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
|
|
17
25
|
/** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
|
|
@@ -38,7 +46,7 @@ export function collectTips(cwd, catalogue = SETUP_TIPS) {
|
|
|
38
46
|
else
|
|
39
47
|
tips.push(tip);
|
|
40
48
|
}
|
|
41
|
-
return { tips, suppressed };
|
|
49
|
+
return { tips, suppressed, star: !ignored.has(STAR_TIP_ID) };
|
|
42
50
|
}
|
|
43
51
|
/**
|
|
44
52
|
* Drop advisory findings whose tip the root package.json silenced, so one
|
|
@@ -66,7 +74,7 @@ function tipTextLines(tip, n) {
|
|
|
66
74
|
lines.push(` Caution: ${tip.caution}`);
|
|
67
75
|
return lines;
|
|
68
76
|
}
|
|
69
|
-
/** One tip as markdown paragraphs for a workflow's `##
|
|
77
|
+
/** One tip as markdown paragraphs for a workflow's `## bkit Tips` section. */
|
|
70
78
|
function tipMarkdownLines(tip) {
|
|
71
79
|
const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
|
|
72
80
|
if (tip.caution)
|
|
@@ -81,15 +89,27 @@ export function orderForWorkflow(tips, workflow) {
|
|
|
81
89
|
const own = tips.filter((t) => t.workflows?.includes(workflow));
|
|
82
90
|
return [...own, ...tips.filter((t) => !own.includes(t))];
|
|
83
91
|
}
|
|
92
|
+
/** True when `STAR_TIP` closes the output in `workflow`: bare `bkit tips` or a phase workflow. */
|
|
93
|
+
export function starShownIn(workflow) {
|
|
94
|
+
return !workflow || ALL_WORKFLOWS.includes(workflow);
|
|
95
|
+
}
|
|
84
96
|
/**
|
|
85
|
-
* `bkit tips` output, then where the rest live
|
|
97
|
+
* `bkit tips` output, then where the rest live, then `STAR_TIP` when `star` is set and
|
|
98
|
+
* `starShownIn(workflow)`. `""` when no tip fires and no star line shows.
|
|
86
99
|
* - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
|
|
87
100
|
* markdown paragraphs with no intro or numbers — the workflow appends them under its
|
|
88
|
-
* own `##
|
|
101
|
+
* own `## bkit Tips` heading.
|
|
89
102
|
* - neither: the top `TIPS_CAP` tips as a numbered terminal list.
|
|
90
103
|
* - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
|
|
91
104
|
*/
|
|
92
105
|
export function formatTips(tips, opts = {}) {
|
|
106
|
+
const body = formatSetupTips(tips, opts);
|
|
107
|
+
if (!opts.star || !starShownIn(opts.workflow))
|
|
108
|
+
return body;
|
|
109
|
+
return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
|
|
110
|
+
}
|
|
111
|
+
/** `formatTips` without `STAR_TIP`. */
|
|
112
|
+
function formatSetupTips(tips, opts) {
|
|
93
113
|
if (tips.length === 0)
|
|
94
114
|
return "";
|
|
95
115
|
const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
|
package/dist/cli.js
CHANGED
|
@@ -69,6 +69,17 @@ export function parseComplyPhase(value) {
|
|
|
69
69
|
? value
|
|
70
70
|
: null;
|
|
71
71
|
}
|
|
72
|
+
/**
|
|
73
|
+
* Where `bkit tips --workflow=<name>` runs: a phase workflow, `audit` (`@bkit-audit-generate`)
|
|
74
|
+
* or `utility` (the ledger and roadmap updaters).
|
|
75
|
+
*/
|
|
76
|
+
export const TIPS_CONTEXTS = [...COMPLY_PHASES, "audit", "utility"];
|
|
77
|
+
/** Narrow an unknown string to `TipsContext` or return null if invalid. */
|
|
78
|
+
export function parseTipsContext(value) {
|
|
79
|
+
return typeof value === "string" && TIPS_CONTEXTS.includes(value)
|
|
80
|
+
? value
|
|
81
|
+
: null;
|
|
82
|
+
}
|
|
72
83
|
// Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
|
|
73
84
|
// intercepted by a dedicated branch in parseArgs before this set is consulted; the
|
|
74
85
|
// generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
|
|
@@ -318,9 +329,9 @@ export function parseArgs(argv) {
|
|
|
318
329
|
}
|
|
319
330
|
if (flag.startsWith("workflow=") && verb === "tips") {
|
|
320
331
|
const value = flag.slice("workflow=".length);
|
|
321
|
-
tipsWorkflow =
|
|
332
|
+
tipsWorkflow = parseTipsContext(value);
|
|
322
333
|
if (tipsWorkflow === null) {
|
|
323
|
-
console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${
|
|
334
|
+
console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${TIPS_CONTEXTS.join(", ")}`);
|
|
324
335
|
process.exit(1);
|
|
325
336
|
}
|
|
326
337
|
continue;
|
|
@@ -427,6 +438,7 @@ Usage:
|
|
|
427
438
|
re-rendering. Copies under .bkit/templates/ are refreshed by
|
|
428
439
|
install/upgrade and checked for staleness — adopt one by
|
|
429
440
|
copying it elsewhere; that copy is yours. The CI gate.
|
|
441
|
+
Changes no managed file; rewrites .bkit/advisories.md.
|
|
430
442
|
bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
|
|
431
443
|
Upgrade everything installed (no module flags). Diffs old
|
|
432
444
|
vs new templates; conflict list emitted to stderr. Use
|
|
@@ -446,17 +458,22 @@ Usage:
|
|
|
446
458
|
--nuke to force-remove manifest-listed files). Target with the
|
|
447
459
|
same module flags as install (e.g. uninstall --claude); a
|
|
448
460
|
targeted uninstall leaves core untouched.
|
|
449
|
-
bkit doctor
|
|
450
|
-
|
|
461
|
+
bkit doctor Preflight + post-install advisory replay (changes no
|
|
462
|
+
managed file; rewrites .bkit/advisories.md). Diagnose
|
|
463
|
+
token surfaces and config drift. Exits 0.
|
|
451
464
|
bkit tips [--workflow=<name>] [--all]
|
|
452
465
|
Setup tips: what this repo has not set up yet, most useful
|
|
453
466
|
first, each with a sentence to ask your agent. Top three
|
|
454
467
|
by default; --workflow=design|plan|build|debug|ship puts
|
|
455
468
|
the tips that matter there first and prints one (each
|
|
456
|
-
workflow runs this at its close
|
|
457
|
-
|
|
469
|
+
workflow runs this at its close; audit and utility do the
|
|
470
|
+
same for audits and the ledger / roadmap updaters);
|
|
471
|
+
--all lists every one. Ends with a star line ("star" in
|
|
472
|
+
bkit.ignoreAdvisories silences it), except under
|
|
473
|
+
--workflow=audit|utility. Local checks only. Exits 0.
|
|
458
474
|
bkit status Read-only host/provider status. Reports current host+provider
|
|
459
|
-
(sampled from .
|
|
475
|
+
(sampled from .claude/, .cursor/, package.json, and the
|
|
476
|
+
opencode agent model pins in .opencode/agents/).
|
|
460
477
|
Writes nothing. Exits 0.
|
|
461
478
|
bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
|
|
462
479
|
macOS GUI apps launched from the Dock/Finder do not inherit
|
|
@@ -476,12 +493,13 @@ Usage:
|
|
|
476
493
|
bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
|
|
477
494
|
and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
|
|
478
495
|
for docs/deferrals.jsonl and docs/failures.jsonl).
|
|
479
|
-
Reads consumer paths from
|
|
496
|
+
Reads consumer paths from harvest/consumers.md.
|
|
480
497
|
DESTRUCTIVE: harvested friction rows are REMOVED from
|
|
481
498
|
the consumer, but only after they are fsync'd and read
|
|
482
499
|
back from harvest/. stats.jsonl is never modified.
|
|
483
|
-
harvest/ accumulates and is never cleared
|
|
484
|
-
|
|
500
|
+
harvest/ accumulates and is never cleared; it is
|
|
501
|
+
gitignored, so it is the only record of pruned rows —
|
|
502
|
+
back it up. Never commits
|
|
485
503
|
in any repo. Deduplicates by per-kind composite
|
|
486
504
|
identity. Advisory + fail-open: exits 0.
|
|
487
505
|
bkit telemetry summary [--phase=<workflow>]
|
|
@@ -505,7 +523,7 @@ Usage:
|
|
|
505
523
|
|
|
506
524
|
Core (implicit — no flag; installed/upgraded on every install):
|
|
507
525
|
AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
|
|
508
|
-
.agents/docs.md + .agents/
|
|
526
|
+
.agents/docs.md + .agents/skills.md managed blocks, .gitignore +
|
|
509
527
|
.gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
|
|
510
528
|
.bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
|
|
511
529
|
runs (added when missing, never overwritten, left by uninstall). The tool scripts those
|
|
@@ -558,7 +576,8 @@ Cross-cutting / modifiers:
|
|
|
558
576
|
--tracker=<name> Wire issue tracker integration. Values: github, linear, none
|
|
559
577
|
(default). Records bkit.issueTracker in package.json and substitutes
|
|
560
578
|
tracker snippets into command mirrors. Switching is free (re-run with
|
|
561
|
-
a new value)
|
|
579
|
+
a new value); a switch removes the old tracker's MCP entry unless you
|
|
580
|
+
edited it. Does NOT own AGENTS.md (which is tracker-agnostic).
|
|
562
581
|
|
|
563
582
|
Install flags:
|
|
564
583
|
--auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
|
|
@@ -573,8 +592,9 @@ Uninstall flags:
|
|
|
573
592
|
--opencode=<provider>
|
|
574
593
|
Surgical provider removal: removes that provider's block from
|
|
575
594
|
opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
|
|
576
|
-
agents/commands/gateguard. If the removed provider was active,
|
|
577
|
-
|
|
595
|
+
agents/commands/gateguard. If the removed provider was active, the first
|
|
596
|
+
remaining provider becomes active and the agents are re-rendered to its
|
|
597
|
+
model pins.
|
|
578
598
|
Bare --opencode (no value) tears down the entire opencode host.
|
|
579
599
|
--force Delete owned whole-file files even if consumer modified them.
|
|
580
600
|
--nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
|
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
// 2. Size↔outcome regression (logistic approximation: error ~ log(linesAdded)
|
|
6
6
|
// + filesChanged) over `kind:"outcome"` rows.
|
|
7
7
|
// 3. Dispatch-size threshold computation for plan-complexity-check / plan-split.
|
|
8
|
-
// 4. `counterSource` trust labelling
|
|
8
|
+
// 4. `counterSource` trust labelling: each outcome row is joined to its `counter` row
|
|
9
|
+
// (model-self-report pre-P3, shell-bus post-P3).
|
|
9
10
|
// 5. Per-rule compliance rate over `kind:"compliance"` rows.
|
|
10
11
|
// 6. Per-`bkitVersion`→CHANGELOG release-attributed regression.
|
|
11
12
|
//
|
|
@@ -17,7 +18,7 @@
|
|
|
17
18
|
// See DE-34 for the shared-entrypoint + crash-isolation contract.
|
|
18
19
|
import * as fs from "node:fs";
|
|
19
20
|
import * as path from "node:path";
|
|
20
|
-
import { UNJUSTIFIED_REASON, foldFrom } from "../ledgers/telemetry.js";
|
|
21
|
+
import { UNJUSTIFIED_REASON, foldFrom, } from "../ledgers/telemetry.js";
|
|
21
22
|
import { HARVEST_DEST_DIR } from "./harvest.js";
|
|
22
23
|
export function computeCounts(events) {
|
|
23
24
|
const byKind = {};
|
|
@@ -84,7 +85,17 @@ function isErrorRun(row, allRows) {
|
|
|
84
85
|
(row.reviewIterations !== undefined && row.reviewIterations > 1) ||
|
|
85
86
|
newFailuresThisRun(row, allRows) > 0);
|
|
86
87
|
}
|
|
87
|
-
|
|
88
|
+
/** Identity of one workflow run: the key the close writes on both its counter and outcome rows. */
|
|
89
|
+
function runKey(row) {
|
|
90
|
+
return row.parentSha ? JSON.stringify([row.repo, row.workflow, row.parentSha]) : undefined;
|
|
91
|
+
}
|
|
92
|
+
export function computeRegression(rows, counterRows) {
|
|
93
|
+
const shellBusRuns = new Set();
|
|
94
|
+
for (const c of counterRows) {
|
|
95
|
+
const key = runKey(c);
|
|
96
|
+
if (c.counterSource === "shell-bus" && key !== undefined)
|
|
97
|
+
shellBusRuns.add(key);
|
|
98
|
+
}
|
|
88
99
|
const buckets = SIZE_BUCKETS.map((b) => ({
|
|
89
100
|
label: b.label,
|
|
90
101
|
minLines: b.min,
|
|
@@ -97,7 +108,8 @@ export function computeRegression(rows) {
|
|
|
97
108
|
let modelSelfReportCount = 0;
|
|
98
109
|
for (const row of rows) {
|
|
99
110
|
// Trust tier labelling
|
|
100
|
-
|
|
111
|
+
const key = runKey(row);
|
|
112
|
+
if (key !== undefined && shellBusRuns.has(key)) {
|
|
101
113
|
shellBusCount++;
|
|
102
114
|
}
|
|
103
115
|
else {
|
|
@@ -214,12 +226,16 @@ export function runAnalysis(paths) {
|
|
|
214
226
|
const { state, rowCount, malformedLineCount } = foldFrom(paths);
|
|
215
227
|
const events = [...state.values()];
|
|
216
228
|
const outcomeRows = [];
|
|
229
|
+
const counterRows = [];
|
|
217
230
|
const complianceRows = [];
|
|
218
231
|
const deferralRows = [];
|
|
219
232
|
for (const ev of events) {
|
|
220
233
|
if (ev.kind === "outcome") {
|
|
221
234
|
outcomeRows.push(ev);
|
|
222
235
|
}
|
|
236
|
+
else if (ev.kind === "counter") {
|
|
237
|
+
counterRows.push(ev);
|
|
238
|
+
}
|
|
223
239
|
else if (ev.kind === "compliance") {
|
|
224
240
|
complianceRows.push(ev);
|
|
225
241
|
}
|
|
@@ -229,7 +245,7 @@ export function runAnalysis(paths) {
|
|
|
229
245
|
}
|
|
230
246
|
const counts = computeCounts(events);
|
|
231
247
|
const elapsed = computeElapsedStats(outcomeRows);
|
|
232
|
-
const regression = computeRegression(outcomeRows);
|
|
248
|
+
const regression = computeRegression(outcomeRows, counterRows);
|
|
233
249
|
const complianceRates = computeComplianceRates(complianceRows);
|
|
234
250
|
const versionCompliance = computeVersionCompliance(complianceRows);
|
|
235
251
|
const deferralDiscipline = computeDeferralDiscipline(deferralRows);
|