@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
|
@@ -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
|
|
@@ -29,29 +30,28 @@ import {
|
|
|
29
30
|
isCloudOrCi,
|
|
30
31
|
} from "../before/env.js";
|
|
31
32
|
import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
|
|
32
|
-
import {
|
|
33
|
-
buildTrackerSetupAdvisory,
|
|
34
|
-
readConsumerCloudAgents,
|
|
35
|
-
readConsumerIssueTracker,
|
|
36
|
-
} from "../after/github.js";
|
|
33
|
+
import { buildTrackerSetupAdvisory } from "../after/github.js";
|
|
37
34
|
import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
|
|
38
35
|
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
39
36
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
40
|
-
import type { ComplyPhase } from "../../cli.js";
|
|
37
|
+
import type { ComplyPhase, TipsContext } from "../../cli.js";
|
|
41
38
|
import {
|
|
39
|
+
anyWorkflowMentions,
|
|
42
40
|
claudeSettingsHas,
|
|
43
41
|
codexTopLevelHas,
|
|
44
42
|
exists,
|
|
43
|
+
hasJsTestRunner,
|
|
45
44
|
hasLintStagedConfig,
|
|
46
45
|
hasMcpServer,
|
|
46
|
+
hasTestLinter,
|
|
47
47
|
unlockedMcpServers,
|
|
48
48
|
} from "./detect.js";
|
|
49
49
|
|
|
50
50
|
export interface SetupTip {
|
|
51
51
|
/** `bkit.ignoreAdvisories` key; never an advisory id (those go in `advisories`). */
|
|
52
52
|
id: string;
|
|
53
|
-
/**
|
|
54
|
-
workflows?: readonly
|
|
53
|
+
/** Contexts the tip matters in; absent = shown only after every context's own tips. */
|
|
54
|
+
workflows?: readonly TipsContext[];
|
|
55
55
|
/** Short label. */
|
|
56
56
|
title: string;
|
|
57
57
|
/** What `bkit tips` prints: what goes wrong today, then what to do. */
|
|
@@ -75,11 +75,14 @@ const hosts = (cwd: string) => detectInstalledHostModules(cwd);
|
|
|
75
75
|
/** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
|
|
76
76
|
export const ALL_WORKFLOWS: readonly ComplyPhase[] = ["design", "plan", "build", "debug", "ship"];
|
|
77
77
|
|
|
78
|
+
/** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
|
|
79
|
+
export const EVERY_CONTEXT: readonly TipsContext[] = [...ALL_WORKFLOWS, "audit", "utility"];
|
|
80
|
+
|
|
78
81
|
export const SETUP_TIPS: readonly SetupTip[] = [
|
|
79
82
|
// --- connect: can bkit talk to anything at all -------------------------------------
|
|
80
83
|
{
|
|
81
84
|
id: "tracker",
|
|
82
|
-
workflows:
|
|
85
|
+
workflows: EVERY_CONTEXT,
|
|
83
86
|
title: "Connect an issue tracker",
|
|
84
87
|
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.",
|
|
85
88
|
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.",
|
|
@@ -91,7 +94,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
91
94
|
},
|
|
92
95
|
{
|
|
93
96
|
id: "gh-mcp",
|
|
94
|
-
workflows:
|
|
97
|
+
workflows: EVERY_CONTEXT,
|
|
95
98
|
title: "Give bkit its GitHub token",
|
|
96
99
|
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.",
|
|
97
100
|
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.",
|
|
@@ -100,12 +103,12 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
100
103
|
"`.bkit/install.md` § Local env setup. The `github` server entry belongs in `.mcp.json` / `.cursor/mcp.json` (`.bkit/cloud.md` § MCP issue-tracker integration).",
|
|
101
104
|
advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
|
|
102
105
|
fires: (cwd) =>
|
|
103
|
-
|
|
106
|
+
readBkitConfig(cwd).issueTracker === "github" &&
|
|
104
107
|
(!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
|
|
105
108
|
},
|
|
106
109
|
{
|
|
107
110
|
id: "bkit-env",
|
|
108
|
-
workflows:
|
|
111
|
+
workflows: EVERY_CONTEXT,
|
|
109
112
|
title: "Create bkit's private settings file",
|
|
110
113
|
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.",
|
|
111
114
|
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.",
|
|
@@ -114,7 +117,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
114
117
|
advisories: ["mcp-env-missing-dotenv", "mcp-env-blank-key-*"],
|
|
115
118
|
fires: (cwd) => {
|
|
116
119
|
if (isCloudOrCi()) return false;
|
|
117
|
-
const tracker =
|
|
120
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
118
121
|
return (
|
|
119
122
|
detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0
|
|
120
123
|
);
|
|
@@ -122,7 +125,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
122
125
|
},
|
|
123
126
|
{
|
|
124
127
|
id: "direnv",
|
|
125
|
-
workflows:
|
|
128
|
+
workflows: EVERY_CONTEXT,
|
|
126
129
|
title: "Load your tokens automatically",
|
|
127
130
|
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.",
|
|
128
131
|
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.",
|
|
@@ -131,7 +134,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
131
134
|
advisories: ["mcp-env-direnv-missing", "mcp-env-direnv-not-allowed"],
|
|
132
135
|
fires: (cwd) => {
|
|
133
136
|
if (isCloudOrCi() || !exists(cwd, ".bkit/.env")) return false;
|
|
134
|
-
const tracker =
|
|
137
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
135
138
|
return (
|
|
136
139
|
!exists(cwd, ".envrc") ||
|
|
137
140
|
detectDirenvMissing(cwd, tracker) !== null ||
|
|
@@ -143,7 +146,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
143
146
|
// --- quality: is the change good -----------------------------------------------------
|
|
144
147
|
{
|
|
145
148
|
id: "serena",
|
|
146
|
-
workflows: ["design", "plan", "build"],
|
|
149
|
+
workflows: ["design", "plan", "build", "audit", "utility"],
|
|
147
150
|
title: "Let agents look code up directly",
|
|
148
151
|
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.",
|
|
149
152
|
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.',
|
|
@@ -153,7 +156,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
153
156
|
},
|
|
154
157
|
{
|
|
155
158
|
id: "ci-workflow",
|
|
156
|
-
workflows: ["build", "ship"],
|
|
159
|
+
workflows: ["build", "ship", "audit"],
|
|
157
160
|
title: "Automatic checks on every change",
|
|
158
161
|
line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
|
|
159
162
|
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".',
|
|
@@ -191,6 +194,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
191
194
|
steps: "`.bkit/templates.md` § slop-scan.",
|
|
192
195
|
fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
|
|
193
196
|
},
|
|
197
|
+
{
|
|
198
|
+
id: "test-lint",
|
|
199
|
+
workflows: ["build"],
|
|
200
|
+
title: "Catch tests that can't fail",
|
|
201
|
+
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.",
|
|
202
|
+
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.",
|
|
203
|
+
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.",
|
|
204
|
+
steps: "`.bkit/templates.md` § Oxlint.",
|
|
205
|
+
fires: (cwd) => hasJsTestRunner(cwd) && !hasTestLinter(cwd),
|
|
206
|
+
},
|
|
194
207
|
{
|
|
195
208
|
id: "vale",
|
|
196
209
|
workflows: ["design", "plan"],
|
|
@@ -222,7 +235,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
222
235
|
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.",
|
|
223
236
|
steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
|
|
224
237
|
fires: (cwd) => {
|
|
225
|
-
const cloud =
|
|
238
|
+
const cloud = readBkitConfig(cwd).cloudAgents;
|
|
226
239
|
if (cloud === "none") return false;
|
|
227
240
|
if (cloud === "cursor") {
|
|
228
241
|
return !exists(cwd, ".cursor/environment.json") || !exists(cwd, ".cursor/Dockerfile");
|
|
@@ -298,9 +311,20 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
298
311
|
},
|
|
299
312
|
|
|
300
313
|
// --- optional: nice to have ------------------------------------------------------------
|
|
314
|
+
{
|
|
315
|
+
id: "issue-forms",
|
|
316
|
+
workflows: ["design", "plan", "debug"],
|
|
317
|
+
title: "Issue forms",
|
|
318
|
+
line: "Optional: add issue forms so every new issue asks for what the agent reads first.",
|
|
319
|
+
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.",
|
|
320
|
+
ask: "Copy .bkit/templates/.github/ISSUE_TEMPLATE/ to .github/ISSUE_TEMPLATE/ and commit it to the default branch.",
|
|
321
|
+
steps: "`.bkit/templates.md` § Issue forms.",
|
|
322
|
+
fires: (cwd) =>
|
|
323
|
+
readBkitConfig(cwd).issueTracker === "github" && !exists(cwd, ".github/ISSUE_TEMPLATE"),
|
|
324
|
+
},
|
|
301
325
|
{
|
|
302
326
|
id: "graphify",
|
|
303
|
-
workflows: ["design", "plan"],
|
|
327
|
+
workflows: ["design", "plan", "audit"],
|
|
304
328
|
title: "A map of the code",
|
|
305
329
|
line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
|
|
306
330
|
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.",
|
|
@@ -310,7 +334,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
310
334
|
},
|
|
311
335
|
{
|
|
312
336
|
id: "dependabot-renovate",
|
|
313
|
-
workflows: ["ship"],
|
|
337
|
+
workflows: ["ship", "audit"],
|
|
314
338
|
title: "Automatic updates",
|
|
315
339
|
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.",
|
|
316
340
|
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.",
|
|
@@ -319,6 +343,18 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
319
343
|
advisories: ["dep-updater-absent"],
|
|
320
344
|
fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
|
|
321
345
|
},
|
|
346
|
+
{
|
|
347
|
+
id: "trivy",
|
|
348
|
+
workflows: ["ship", "audit"],
|
|
349
|
+
title: "Security scan",
|
|
350
|
+
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.",
|
|
351
|
+
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.",
|
|
352
|
+
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.",
|
|
353
|
+
steps:
|
|
354
|
+
"`.bkit/templates.md` § Trivy. Accept a finding in `.trivyignore.yaml` with `statement` + `expired_at`; never drop `--include-dev-deps`.",
|
|
355
|
+
fires: (cwd) =>
|
|
356
|
+
exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
|
|
357
|
+
},
|
|
322
358
|
{
|
|
323
359
|
id: "prettier-tables",
|
|
324
360
|
workflows: ["design", "plan"],
|
|
@@ -329,6 +365,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
|
|
|
329
365
|
steps: "`.bkit/templates.md` § Prettier tables.",
|
|
330
366
|
fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
|
|
331
367
|
},
|
|
368
|
+
{
|
|
369
|
+
id: "tmp-prune",
|
|
370
|
+
title: "Clear out old scratch files",
|
|
371
|
+
line: "Scratch files agents leave in tmp/ are never cleared, so the folder keeps growing. Add the clean-up that runs when you push.",
|
|
372
|
+
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.",
|
|
373
|
+
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.",
|
|
374
|
+
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
375
|
+
fires: (cwd) =>
|
|
376
|
+
exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
377
|
+
},
|
|
332
378
|
|
|
333
379
|
// --- setup: only some setups -----------------------------------------------------------
|
|
334
380
|
{
|
|
@@ -1,10 +1,10 @@
|
|
|
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
|
|
|
4
4
|
import * as fs from "node:fs";
|
|
5
5
|
import * as path from "node:path";
|
|
6
6
|
import { parseJson } from "../../shared/json.js";
|
|
7
|
-
import { readPackageJson } from "../../shared/package-json.js";
|
|
7
|
+
import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
|
|
8
8
|
|
|
9
9
|
/** True when `rel` exists under `cwd`. */
|
|
10
10
|
export const exists = (cwd: string, rel: string): boolean => fs.existsSync(path.join(cwd, rel));
|
|
@@ -136,9 +136,52 @@ const LINT_STAGED_CONFIGS = [
|
|
|
136
136
|
"lint-staged.config.js",
|
|
137
137
|
];
|
|
138
138
|
|
|
139
|
+
/** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
|
|
140
|
+
export function anyWorkflowMentions(cwd: string, needle: string): boolean {
|
|
141
|
+
const dir = path.join(cwd, ".github", "workflows");
|
|
142
|
+
if (!fs.existsSync(dir)) return false;
|
|
143
|
+
return fs
|
|
144
|
+
.readdirSync(dir)
|
|
145
|
+
.filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
|
|
146
|
+
.some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
|
|
147
|
+
}
|
|
148
|
+
|
|
139
149
|
/** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
|
|
140
150
|
export function hasLintStagedConfig(cwd: string): boolean {
|
|
141
151
|
if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel))) return true;
|
|
142
152
|
const pkg = readPackageJson(cwd);
|
|
143
153
|
return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
|
|
144
154
|
}
|
|
155
|
+
|
|
156
|
+
const OXLINT_CONFIGS = [
|
|
157
|
+
".oxlintrc.json",
|
|
158
|
+
...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `oxlint.config.${ext}`),
|
|
159
|
+
];
|
|
160
|
+
|
|
161
|
+
const ESLINT_CONFIGS = [
|
|
162
|
+
".eslintrc",
|
|
163
|
+
...["json", "js", "cjs", "yaml", "yml"].map((ext) => `.eslintrc.${ext}`),
|
|
164
|
+
...["js", "mjs", "cjs", "ts", "mts", "cts"].map((ext) => `eslint.config.${ext}`),
|
|
165
|
+
];
|
|
166
|
+
|
|
167
|
+
/** A test-framework or test-library name inside an ESLint config means it lints tests. */
|
|
168
|
+
const TEST_LINT_PLUGIN = /vitest|jest|playwright|testing-library/i;
|
|
169
|
+
|
|
170
|
+
/** True when `package.json` lists a JS / TS test runner (Vitest or Jest) as a dependency. */
|
|
171
|
+
export const hasJsTestRunner = (cwd: string): boolean =>
|
|
172
|
+
readDependencyNames(cwd).some((name) => name === "vitest" || name === "jest");
|
|
173
|
+
|
|
174
|
+
/**
|
|
175
|
+
* True when the repo already lints its test files: an Oxlint config or `oxlint` dependency,
|
|
176
|
+
* or an ESLint config (file or `package.json` `eslintConfig`) that names a test plugin.
|
|
177
|
+
*/
|
|
178
|
+
export function hasTestLinter(cwd: string): boolean {
|
|
179
|
+
if (OXLINT_CONFIGS.some((rel) => exists(cwd, rel))) return true;
|
|
180
|
+
if (readDependencyNames(cwd).includes("oxlint")) return true;
|
|
181
|
+
const eslintConfigs = ESLINT_CONFIGS.map((rel) => readText(cwd, rel));
|
|
182
|
+
const pkg = readPackageJson(cwd);
|
|
183
|
+
if (pkg.ok && pkg.pkg["eslintConfig"] !== undefined) {
|
|
184
|
+
eslintConfigs.push(JSON.stringify(pkg.pkg["eslintConfig"]));
|
|
185
|
+
}
|
|
186
|
+
return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
|
|
187
|
+
}
|
|
@@ -7,8 +7,8 @@ import {
|
|
|
7
7
|
type SuppressionNote,
|
|
8
8
|
type SuppressionReporter,
|
|
9
9
|
} from "../after/suppression.js";
|
|
10
|
-
import type {
|
|
11
|
-
import { SETUP_TIPS, type SetupTip } from "./catalogue.js";
|
|
10
|
+
import type { TipsContext } from "../../cli.js";
|
|
11
|
+
import { ALL_WORKFLOWS, SETUP_TIPS, type SetupTip } from "./catalogue.js";
|
|
12
12
|
|
|
13
13
|
/** Tips `bkit tips` prints without `--all` or `--workflow`. */
|
|
14
14
|
export const TIPS_CAP = 3;
|
|
@@ -27,6 +27,17 @@ export const tipsIntro = (n: number) =>
|
|
|
27
27
|
export const TIPS_DETAILS_POINTER =
|
|
28
28
|
"Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
|
|
29
29
|
|
|
30
|
+
/** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
|
|
31
|
+
export const STAR_TIP_ID = "star";
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
|
|
35
|
+
* workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
|
|
36
|
+
* gap, so never in the checklist.
|
|
37
|
+
*/
|
|
38
|
+
export const STAR_TIP =
|
|
39
|
+
"Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
|
|
40
|
+
|
|
30
41
|
/** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
|
|
31
42
|
export const TIPS_SECTION_INTRO =
|
|
32
43
|
"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.";
|
|
@@ -48,6 +59,8 @@ export interface TipsResult {
|
|
|
48
59
|
tips: SetupTip[];
|
|
49
60
|
/** Firing tips the root `bkit.ignoreAdvisories` silenced. */
|
|
50
61
|
suppressed: SuppressionNote[];
|
|
62
|
+
/** False when the root `bkit.ignoreAdvisories` names `STAR_TIP_ID`. */
|
|
63
|
+
star: boolean;
|
|
51
64
|
}
|
|
52
65
|
|
|
53
66
|
/** Every firing tip in priority order, minus the ones the root package.json silences. */
|
|
@@ -60,7 +73,7 @@ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_
|
|
|
60
73
|
if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
|
|
61
74
|
else tips.push(tip);
|
|
62
75
|
}
|
|
63
|
-
return { tips, suppressed };
|
|
76
|
+
return { tips, suppressed, star: !ignored.has(STAR_TIP_ID) };
|
|
64
77
|
}
|
|
65
78
|
|
|
66
79
|
/**
|
|
@@ -93,7 +106,7 @@ function tipTextLines(tip: SetupTip, n: number): string[] {
|
|
|
93
106
|
return lines;
|
|
94
107
|
}
|
|
95
108
|
|
|
96
|
-
/** One tip as markdown paragraphs for a workflow's `##
|
|
109
|
+
/** One tip as markdown paragraphs for a workflow's `## bkit Tips` section. */
|
|
97
110
|
function tipMarkdownLines(tip: SetupTip): string[] {
|
|
98
111
|
const lines = [`**${tip.title}.** ${tip.line}`, "", `Ask your agent: "${tip.ask}"`];
|
|
99
112
|
if (tip.caution) lines.push("", `Caution: ${tip.caution}`);
|
|
@@ -104,22 +117,38 @@ function tipMarkdownLines(tip: SetupTip): string[] {
|
|
|
104
117
|
* `tips` with the ones that matter in `workflow` first, each group in catalogue order.
|
|
105
118
|
* Comms tips name every workflow, so they stay first everywhere.
|
|
106
119
|
*/
|
|
107
|
-
export function orderForWorkflow(tips: readonly SetupTip[], workflow:
|
|
120
|
+
export function orderForWorkflow(tips: readonly SetupTip[], workflow: TipsContext): SetupTip[] {
|
|
108
121
|
const own = tips.filter((t) => t.workflows?.includes(workflow));
|
|
109
122
|
return [...own, ...tips.filter((t) => !own.includes(t))];
|
|
110
123
|
}
|
|
111
124
|
|
|
125
|
+
/** True when `STAR_TIP` closes the output in `workflow`: bare `bkit tips` or a phase workflow. */
|
|
126
|
+
export function starShownIn(workflow: TipsContext | null | undefined): boolean {
|
|
127
|
+
return !workflow || (ALL_WORKFLOWS as readonly string[]).includes(workflow);
|
|
128
|
+
}
|
|
129
|
+
|
|
112
130
|
/**
|
|
113
|
-
* `bkit tips` output, then where the rest live
|
|
131
|
+
* `bkit tips` output, then where the rest live, then `STAR_TIP` when `star` is set and
|
|
132
|
+
* `starShownIn(workflow)`. `""` when no tip fires and no star line shows.
|
|
114
133
|
* - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow, as
|
|
115
134
|
* markdown paragraphs with no intro or numbers — the workflow appends them under its
|
|
116
|
-
* own `##
|
|
135
|
+
* own `## bkit Tips` heading.
|
|
117
136
|
* - neither: the top `TIPS_CAP` tips as a numbered terminal list.
|
|
118
137
|
* - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
|
|
119
138
|
*/
|
|
120
139
|
export function formatTips(
|
|
121
140
|
tips: readonly SetupTip[],
|
|
122
|
-
opts: { all?: boolean; workflow?:
|
|
141
|
+
opts: { all?: boolean; workflow?: TipsContext | null; star?: boolean } = {},
|
|
142
|
+
): string {
|
|
143
|
+
const body = formatSetupTips(tips, opts);
|
|
144
|
+
if (!opts.star || !starShownIn(opts.workflow)) return body;
|
|
145
|
+
return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** `formatTips` without `STAR_TIP`. */
|
|
149
|
+
function formatSetupTips(
|
|
150
|
+
tips: readonly SetupTip[],
|
|
151
|
+
opts: { all?: boolean; workflow?: TipsContext | null },
|
|
123
152
|
): string {
|
|
124
153
|
if (tips.length === 0) return "";
|
|
125
154
|
const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
|
package/.bkit/core/engine/cli.ts
CHANGED
|
@@ -102,6 +102,20 @@ export function parseComplyPhase(value: unknown): ComplyPhase | null {
|
|
|
102
102
|
: null;
|
|
103
103
|
}
|
|
104
104
|
|
|
105
|
+
/**
|
|
106
|
+
* Where `bkit tips --workflow=<name>` runs: a phase workflow, `audit` (`@bkit-audit-generate`)
|
|
107
|
+
* or `utility` (the ledger and roadmap updaters).
|
|
108
|
+
*/
|
|
109
|
+
export const TIPS_CONTEXTS = [...COMPLY_PHASES, "audit", "utility"] as const;
|
|
110
|
+
export type TipsContext = (typeof TIPS_CONTEXTS)[number];
|
|
111
|
+
|
|
112
|
+
/** Narrow an unknown string to `TipsContext` or return null if invalid. */
|
|
113
|
+
export function parseTipsContext(value: unknown): TipsContext | null {
|
|
114
|
+
return typeof value === "string" && (TIPS_CONTEXTS as readonly string[]).includes(value)
|
|
115
|
+
? (value as TipsContext)
|
|
116
|
+
: null;
|
|
117
|
+
}
|
|
118
|
+
|
|
105
119
|
export interface ParsedArgs {
|
|
106
120
|
verb: Verb;
|
|
107
121
|
/**
|
|
@@ -145,7 +159,7 @@ export interface ParsedArgs {
|
|
|
145
159
|
/** `bkit tips --all`: print every firing tip, not just the top three. */
|
|
146
160
|
tipsAll: boolean;
|
|
147
161
|
/** `bkit tips --workflow=<name>`: the workflow whose tips go first; it prints one. */
|
|
148
|
-
tipsWorkflow:
|
|
162
|
+
tipsWorkflow: TipsContext | null;
|
|
149
163
|
}
|
|
150
164
|
|
|
151
165
|
export interface UninstallFlags {
|
|
@@ -300,7 +314,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
|
|
|
300
314
|
let complyPhase: ComplyPhase | null = null;
|
|
301
315
|
let telemetrySubverb: TelemetrySubverb | null = null;
|
|
302
316
|
let tipsAll = false;
|
|
303
|
-
let tipsWorkflow:
|
|
317
|
+
let tipsWorkflow: TipsContext | null = null;
|
|
304
318
|
|
|
305
319
|
// For `telemetry` verb: extract the sub-verb from the first remaining positional arg
|
|
306
320
|
if (verb === "telemetry") {
|
|
@@ -457,10 +471,10 @@ export function parseArgs(argv: string[]): ParsedArgs {
|
|
|
457
471
|
}
|
|
458
472
|
if (flag.startsWith("workflow=") && verb === "tips") {
|
|
459
473
|
const value = flag.slice("workflow=".length);
|
|
460
|
-
tipsWorkflow =
|
|
474
|
+
tipsWorkflow = parseTipsContext(value);
|
|
461
475
|
if (tipsWorkflow === null) {
|
|
462
476
|
console.error(
|
|
463
|
-
`[bkit] Unknown workflow: "${value}". Valid values: ${
|
|
477
|
+
`[bkit] Unknown workflow: "${value}". Valid values: ${TIPS_CONTEXTS.join(", ")}`,
|
|
464
478
|
);
|
|
465
479
|
process.exit(1);
|
|
466
480
|
}
|
|
@@ -581,6 +595,7 @@ Usage:
|
|
|
581
595
|
re-rendering. Copies under .bkit/templates/ are refreshed by
|
|
582
596
|
install/upgrade and checked for staleness — adopt one by
|
|
583
597
|
copying it elsewhere; that copy is yours. The CI gate.
|
|
598
|
+
Changes no managed file; rewrites .bkit/advisories.md.
|
|
584
599
|
bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
|
|
585
600
|
Upgrade everything installed (no module flags). Diffs old
|
|
586
601
|
vs new templates; conflict list emitted to stderr. Use
|
|
@@ -600,17 +615,22 @@ Usage:
|
|
|
600
615
|
--nuke to force-remove manifest-listed files). Target with the
|
|
601
616
|
same module flags as install (e.g. uninstall --claude); a
|
|
602
617
|
targeted uninstall leaves core untouched.
|
|
603
|
-
bkit doctor
|
|
604
|
-
|
|
618
|
+
bkit doctor Preflight + post-install advisory replay (changes no
|
|
619
|
+
managed file; rewrites .bkit/advisories.md). Diagnose
|
|
620
|
+
token surfaces and config drift. Exits 0.
|
|
605
621
|
bkit tips [--workflow=<name>] [--all]
|
|
606
622
|
Setup tips: what this repo has not set up yet, most useful
|
|
607
623
|
first, each with a sentence to ask your agent. Top three
|
|
608
624
|
by default; --workflow=design|plan|build|debug|ship puts
|
|
609
625
|
the tips that matter there first and prints one (each
|
|
610
|
-
workflow runs this at its close
|
|
611
|
-
|
|
626
|
+
workflow runs this at its close; audit and utility do the
|
|
627
|
+
same for audits and the ledger / roadmap updaters);
|
|
628
|
+
--all lists every one. Ends with a star line ("star" in
|
|
629
|
+
bkit.ignoreAdvisories silences it), except under
|
|
630
|
+
--workflow=audit|utility. Local checks only. Exits 0.
|
|
612
631
|
bkit status Read-only host/provider status. Reports current host+provider
|
|
613
|
-
(sampled from .
|
|
632
|
+
(sampled from .claude/, .cursor/, package.json, and the
|
|
633
|
+
opencode agent model pins in .opencode/agents/).
|
|
614
634
|
Writes nothing. Exits 0.
|
|
615
635
|
bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
|
|
616
636
|
macOS GUI apps launched from the Dock/Finder do not inherit
|
|
@@ -630,12 +650,13 @@ Usage:
|
|
|
630
650
|
bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
|
|
631
651
|
and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
|
|
632
652
|
for docs/deferrals.jsonl and docs/failures.jsonl).
|
|
633
|
-
Reads consumer paths from
|
|
653
|
+
Reads consumer paths from harvest/consumers.md.
|
|
634
654
|
DESTRUCTIVE: harvested friction rows are REMOVED from
|
|
635
655
|
the consumer, but only after they are fsync'd and read
|
|
636
656
|
back from harvest/. stats.jsonl is never modified.
|
|
637
|
-
harvest/ accumulates and is never cleared
|
|
638
|
-
|
|
657
|
+
harvest/ accumulates and is never cleared; it is
|
|
658
|
+
gitignored, so it is the only record of pruned rows —
|
|
659
|
+
back it up. Never commits
|
|
639
660
|
in any repo. Deduplicates by per-kind composite
|
|
640
661
|
identity. Advisory + fail-open: exits 0.
|
|
641
662
|
bkit telemetry summary [--phase=<workflow>]
|
|
@@ -659,7 +680,7 @@ Usage:
|
|
|
659
680
|
|
|
660
681
|
Core (implicit — no flag; installed/upgraded on every install):
|
|
661
682
|
AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
|
|
662
|
-
.agents/docs.md + .agents/
|
|
683
|
+
.agents/docs.md + .agents/skills.md managed blocks, .gitignore +
|
|
663
684
|
.gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
|
|
664
685
|
.bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
|
|
665
686
|
runs (added when missing, never overwritten, left by uninstall). The tool scripts those
|
|
@@ -712,7 +733,8 @@ Cross-cutting / modifiers:
|
|
|
712
733
|
--tracker=<name> Wire issue tracker integration. Values: github, linear, none
|
|
713
734
|
(default). Records bkit.issueTracker in package.json and substitutes
|
|
714
735
|
tracker snippets into command mirrors. Switching is free (re-run with
|
|
715
|
-
a new value)
|
|
736
|
+
a new value); a switch removes the old tracker's MCP entry unless you
|
|
737
|
+
edited it. Does NOT own AGENTS.md (which is tracker-agnostic).
|
|
716
738
|
|
|
717
739
|
Install flags:
|
|
718
740
|
--auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
|
|
@@ -727,8 +749,9 @@ Uninstall flags:
|
|
|
727
749
|
--opencode=<provider>
|
|
728
750
|
Surgical provider removal: removes that provider's block from
|
|
729
751
|
opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
|
|
730
|
-
agents/commands/gateguard. If the removed provider was active,
|
|
731
|
-
|
|
752
|
+
agents/commands/gateguard. If the removed provider was active, the first
|
|
753
|
+
remaining provider becomes active and the agents are re-rendered to its
|
|
754
|
+
model pins.
|
|
732
755
|
Bare --opencode (no value) tears down the entire opencode host.
|
|
733
756
|
--force Delete owned whole-file files even if consumer modified them.
|
|
734
757
|
--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
|
//
|
|
@@ -18,32 +19,25 @@
|
|
|
18
19
|
|
|
19
20
|
import * as fs from "node:fs";
|
|
20
21
|
import * as path from "node:path";
|
|
21
|
-
import {
|
|
22
|
+
import {
|
|
23
|
+
UNJUSTIFIED_REASON,
|
|
24
|
+
foldFrom,
|
|
25
|
+
type CounterPayload,
|
|
26
|
+
type OutcomePayload,
|
|
27
|
+
type TelemetryEnvelope,
|
|
28
|
+
type TelemetryEvent,
|
|
29
|
+
} from "../ledgers/telemetry.js";
|
|
22
30
|
import { HARVEST_DEST_DIR } from "./harvest.js";
|
|
23
31
|
|
|
24
32
|
// ---------------------------------------------------------------------------
|
|
25
33
|
// Types
|
|
26
34
|
// ---------------------------------------------------------------------------
|
|
27
35
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
prNumber?: number;
|
|
34
|
-
linesAdded: number;
|
|
35
|
-
linesDeleted: number;
|
|
36
|
-
linesChanged: number;
|
|
37
|
-
filesChanged: number;
|
|
38
|
-
taskCount: number;
|
|
39
|
-
durationSeconds: number;
|
|
40
|
-
ciTrySuccess?: number;
|
|
41
|
-
correctiveCommits?: number;
|
|
42
|
-
reviewIterations?: number;
|
|
43
|
-
deferrals: number;
|
|
44
|
-
failures: number;
|
|
45
|
-
counterSource?: string;
|
|
46
|
-
}
|
|
36
|
+
/** A `kind:"outcome"` ledger row: the shared envelope plus the outcome payload. */
|
|
37
|
+
export type OutcomeRow = TelemetryEnvelope & OutcomePayload;
|
|
38
|
+
|
|
39
|
+
/** A `kind:"counter"` ledger row; `counterSource` lives here, never on the outcome row. */
|
|
40
|
+
export type CounterRow = TelemetryEnvelope & CounterPayload;
|
|
47
41
|
|
|
48
42
|
export interface ComplianceRow {
|
|
49
43
|
ts: number;
|
|
@@ -142,8 +136,9 @@ export interface RegressionResult {
|
|
|
142
136
|
*/
|
|
143
137
|
dispatchSizeThreshold: number;
|
|
144
138
|
/**
|
|
145
|
-
* Trust tier split:
|
|
146
|
-
*
|
|
139
|
+
* Trust tier split: an outcome row is shell-bus when a `counter` row with the same
|
|
140
|
+
* repo + workflow + parentSha carries `counterSource: "shell-bus"` (post-P3
|
|
141
|
+
* deterministic); every other outcome row is model-self-report (pre-P3 untrusted).
|
|
147
142
|
*/
|
|
148
143
|
shellBusCount: number;
|
|
149
144
|
modelSelfReportCount: number;
|
|
@@ -185,7 +180,18 @@ function isErrorRun(row: OutcomeRow, allRows: OutcomeRow[]): boolean {
|
|
|
185
180
|
);
|
|
186
181
|
}
|
|
187
182
|
|
|
188
|
-
|
|
183
|
+
/** Identity of one workflow run: the key the close writes on both its counter and outcome rows. */
|
|
184
|
+
function runKey(row: { repo: string; workflow: string; parentSha?: string }): string | undefined {
|
|
185
|
+
return row.parentSha ? JSON.stringify([row.repo, row.workflow, row.parentSha]) : undefined;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export function computeRegression(rows: OutcomeRow[], counterRows: CounterRow[]): RegressionResult {
|
|
189
|
+
const shellBusRuns = new Set<string>();
|
|
190
|
+
for (const c of counterRows) {
|
|
191
|
+
const key = runKey(c);
|
|
192
|
+
if (c.counterSource === "shell-bus" && key !== undefined) shellBusRuns.add(key);
|
|
193
|
+
}
|
|
194
|
+
|
|
189
195
|
const buckets: SizeBucket[] = SIZE_BUCKETS.map((b) => ({
|
|
190
196
|
label: b.label,
|
|
191
197
|
minLines: b.min,
|
|
@@ -200,7 +206,8 @@ export function computeRegression(rows: OutcomeRow[]): RegressionResult {
|
|
|
200
206
|
|
|
201
207
|
for (const row of rows) {
|
|
202
208
|
// Trust tier labelling
|
|
203
|
-
|
|
209
|
+
const key = runKey(row);
|
|
210
|
+
if (key !== undefined && shellBusRuns.has(key)) {
|
|
204
211
|
shellBusCount++;
|
|
205
212
|
} else {
|
|
206
213
|
modelSelfReportCount++;
|
|
@@ -411,12 +418,15 @@ export function runAnalysis(paths: string[]): AnalysisReport {
|
|
|
411
418
|
const events = [...state.values()];
|
|
412
419
|
|
|
413
420
|
const outcomeRows: OutcomeRow[] = [];
|
|
421
|
+
const counterRows: CounterRow[] = [];
|
|
414
422
|
const complianceRows: ComplianceRow[] = [];
|
|
415
423
|
const deferralRows: DeferralRow[] = [];
|
|
416
424
|
|
|
417
425
|
for (const ev of events) {
|
|
418
426
|
if (ev.kind === "outcome") {
|
|
419
427
|
outcomeRows.push(ev);
|
|
428
|
+
} else if (ev.kind === "counter") {
|
|
429
|
+
counterRows.push(ev);
|
|
420
430
|
} else if (ev.kind === "compliance") {
|
|
421
431
|
complianceRows.push(ev);
|
|
422
432
|
} else if (ev.kind === "deferral") {
|
|
@@ -426,7 +436,7 @@ export function runAnalysis(paths: string[]): AnalysisReport {
|
|
|
426
436
|
|
|
427
437
|
const counts = computeCounts(events);
|
|
428
438
|
const elapsed = computeElapsedStats(outcomeRows);
|
|
429
|
-
const regression = computeRegression(outcomeRows);
|
|
439
|
+
const regression = computeRegression(outcomeRows, counterRows);
|
|
430
440
|
const complianceRates = computeComplianceRates(complianceRows);
|
|
431
441
|
const versionCompliance = computeVersionCompliance(complianceRows);
|
|
432
442
|
const deferralDiscipline = computeDeferralDiscipline(deferralRows);
|