@cbartens/bkit 5.4.0 → 5.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.bkit/README.md +19 -7
- package/.bkit/core/.agents/rules.md +24 -9
- package/.bkit/core/.bkit/README.md +18 -6
- package/.bkit/core/.bkit/cloud.md +46 -15
- package/.bkit/core/.bkit/comparison.md +2 -2
- package/.bkit/core/.bkit/install.md +19 -18
- package/.bkit/core/.bkit/pipeline.md +3 -1
- package/.bkit/core/.bkit/prompts.md +38 -20
- package/.bkit/core/.bkit/providers.md +6 -6
- package/.bkit/core/.bkit/templates.md +44 -13
- package/.bkit/core/.bkit/trackers.md +99 -35
- package/.bkit/core/.bkit/workflows.md +50 -45
- package/.bkit/core/AGENTS.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
- package/.bkit/core/engine/checks/after/auth.ts +88 -45
- package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
- package/.bkit/core/engine/checks/after/github.ts +42 -78
- package/.bkit/core/engine/checks/after/index.ts +1 -6
- package/.bkit/core/engine/checks/after/tools.ts +1 -1
- package/.bkit/core/engine/checks/before/env.ts +28 -18
- package/.bkit/core/engine/checks/before/mcp.ts +4 -2
- package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
- package/.bkit/core/engine/checks/tips/index.ts +5 -2
- package/.bkit/core/engine/cli.ts +7 -5
- package/.bkit/core/engine/commands/ci/ci.ts +107 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
- package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
- package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
- package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
- package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
- package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
- package/.bkit/core/engine/install/manifest.ts +31 -10
- package/.bkit/core/engine/install/modules/cloud.ts +3 -1
- package/.bkit/core/engine/install/modules/core.ts +153 -4
- package/.bkit/core/engine/install/modules/opencode.ts +5 -0
- package/.bkit/core/engine/install/write.ts +37 -1
- package/.bkit/core/engine/render/trackers.ts +35 -23
- package/.bkit/core/engine/shared/egress.ts +6 -0
- package/.bkit/core/engine/shared/settings.ts +130 -11
- package/.bkit/core/hooks/guardrails-tiers.js +1 -1
- package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
- 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-plan-execute.md +1 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
- package/.bkit/core/prompts/bkit-design-generate.md +4 -1
- package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
- package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
- package/.bkit/core/workflows/bkit-auto.md +19 -6
- package/.bkit/core/workflows/bkit-build.md +59 -17
- package/.bkit/core/workflows/bkit-debug.md +64 -20
- package/.bkit/core/workflows/bkit-design.md +83 -28
- package/.bkit/core/workflows/bkit-plan.md +61 -20
- package/.bkit/core/workflows/bkit-ship.md +48 -18
- package/.bkit/shared/.bkit/.env.example +8 -0
- package/.bkit/shared/.claude/settings.json +3 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
- package/.bkit/shared/.cursor/mcp.json +11 -4
- package/.bkit/shared/.mcp.json +11 -4
- package/.bkit/shared/.opencode/opencode.json +2 -0
- package/.bkit/shared/docs/deployments.md +6 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/docs/testing.md +13 -5
- package/.bkit/templates/.github/renovate.json5 +1 -1
- package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
- package/.bkit/templates/.husky/pre-commit +4 -4
- package/.bkit/templates/.husky/pre-push +107 -18
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
- package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
- package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
- package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
- package/CHANGELOG.md +67 -1
- package/README.md +16 -6
- package/dist/checks/after/auth.js +81 -45
- package/dist/checks/after/ci-yml.js +0 -1
- package/dist/checks/after/github.js +41 -76
- package/dist/checks/after/index.js +2 -7
- package/dist/checks/after/tools.js +1 -1
- package/dist/checks/before/env.js +24 -17
- package/dist/checks/before/mcp.js +4 -2
- package/dist/checks/tips/catalogue.js +14 -2
- package/dist/checks/tips/index.js +4 -2
- package/dist/cli.js +7 -5
- package/dist/commands/ci/ci.js +100 -0
- package/dist/commands/install/uninstall.js +42 -0
- package/dist/commands/workflow/fids.js +22 -15
- package/dist/commands/workflow/issues.js +53 -61
- package/dist/commands/workflow/ledgers.js +26 -11
- package/dist/commands/workflow/prs.js +3 -1
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +3 -1
- package/dist/commands/workflow/steps.js +2 -2
- package/dist/commands/workflow/workflows.js +9 -4
- package/dist/commands/workflow/worktrees.js +74 -13
- package/dist/install/manifest.js +30 -10
- package/dist/install/modules/cloud.js +3 -1
- package/dist/install/modules/core.js +157 -5
- package/dist/install/modules/opencode.js +6 -0
- package/dist/install/write.js +26 -2
- package/dist/render/trackers.js +34 -20
- package/dist/shared/egress.js +6 -0
- package/dist/shared/settings.js +59 -7
- package/package.json +14 -3
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// the cloud router's), and the cloud-dashboard secrets checklist.
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
|
-
import {
|
|
5
|
+
import { spawnSync } from "node:child_process";
|
|
6
6
|
import { readJsonFile } from "../../shared/json.js";
|
|
7
7
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
8
8
|
/**
|
|
@@ -68,27 +68,33 @@ export function detectGhMcpToken(cwd) {
|
|
|
68
68
|
}
|
|
69
69
|
return null;
|
|
70
70
|
}
|
|
71
|
+
/**
|
|
72
|
+
* Names of the consumer repo's GitHub Actions secrets or variables (repo level only).
|
|
73
|
+
* `null` if gh CLI unavailable, unauthenticated, or not a GitHub repo.
|
|
74
|
+
*/
|
|
75
|
+
function listGhNames(kind) {
|
|
76
|
+
const res = spawnSync("gh", [kind, "list", "--json", "name", "-q", ".[].name"], {
|
|
77
|
+
encoding: "utf-8",
|
|
78
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
79
|
+
timeout: 5000,
|
|
80
|
+
});
|
|
81
|
+
if (res.status !== 0 || typeof res.stdout !== "string")
|
|
82
|
+
return null;
|
|
83
|
+
return res.stdout
|
|
84
|
+
.split("\n")
|
|
85
|
+
.map((s) => s.trim())
|
|
86
|
+
.filter(Boolean);
|
|
87
|
+
}
|
|
71
88
|
/**
|
|
72
89
|
* Detect whether a named secret is set on the consumer's GitHub repo.
|
|
73
90
|
* Returns "present" | "missing" | "unknown".
|
|
74
91
|
* "unknown" if gh CLI unavailable, unauthenticated, or not a GitHub repo.
|
|
75
92
|
*/
|
|
76
93
|
export function detectGhSecret(secretName) {
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
encoding: "utf-8",
|
|
80
|
-
stdio: ["ignore", "pipe", "ignore"],
|
|
81
|
-
timeout: 5000,
|
|
82
|
-
});
|
|
83
|
-
const names = out
|
|
84
|
-
.split("\n")
|
|
85
|
-
.map((s) => s.trim())
|
|
86
|
-
.filter(Boolean);
|
|
87
|
-
return names.includes(secretName) ? "present" : "missing";
|
|
88
|
-
}
|
|
89
|
-
catch {
|
|
94
|
+
const names = listGhNames("secret");
|
|
95
|
+
if (names === null)
|
|
90
96
|
return "unknown";
|
|
91
|
-
|
|
97
|
+
return names.includes(secretName) ? "present" : "missing";
|
|
92
98
|
}
|
|
93
99
|
/**
|
|
94
100
|
* Build the consolidated "three locations to sync secrets" advisory. Fires when
|
|
@@ -105,17 +111,19 @@ export function buildCloudDashboardsAdvisory(cwd) {
|
|
|
105
111
|
const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
|
|
106
112
|
if (!hasRouter && !hasClaude && !hasCursor)
|
|
107
113
|
return null;
|
|
108
|
-
// cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY
|
|
109
|
-
// cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard.
|
|
110
|
-
// Distinguish by recorded variant; fall back to presence-based detection.
|
|
111
|
-
const
|
|
112
|
-
const isCursorCloud =
|
|
114
|
+
// cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY or federation.
|
|
115
|
+
// cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard; Linear-tracker only.
|
|
116
|
+
// Distinguish by recorded variant; fall back to presence-based detection under linear.
|
|
117
|
+
const config = readBkitConfig(cwd);
|
|
118
|
+
const isCursorCloud = config.cloudAgents === "cursor" ||
|
|
119
|
+
(!hasRouter && hasCursor && config.issueTracker === "linear");
|
|
113
120
|
const secretList = isCursorCloud ? "`BKIT_LINEAR_API_KEY`" : "`ANTHROPIC_API_KEY`";
|
|
114
121
|
const ghSetLines = isCursorCloud
|
|
115
122
|
? " gh secret set BKIT_LINEAR_API_KEY --body='<value>'\n\n" +
|
|
116
123
|
" Verify: `gh secret list | grep -E 'BKIT_LINEAR_API_KEY'`\n\n"
|
|
117
124
|
: " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
|
|
118
|
-
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n"
|
|
125
|
+
" Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
|
|
126
|
+
" Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n";
|
|
119
127
|
const vendorNote = isCursorCloud
|
|
120
128
|
? "BKIT_LINEAR_API_KEY is read from the Linear dashboard (https://linear.app/settings/api)."
|
|
121
129
|
: "ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.";
|
|
@@ -133,35 +141,63 @@ export function buildCloudDashboardsAdvisory(cwd) {
|
|
|
133
141
|
vendorNote,
|
|
134
142
|
};
|
|
135
143
|
}
|
|
144
|
+
/** Repo variables that, both set, switch bkit-cloud.yml's claude job to workload identity federation. */
|
|
145
|
+
const FEDERATION_VARIABLES = ["ANTHROPIC_FEDERATION_RULE_ID", "ANTHROPIC_ORGANIZATION_ID"];
|
|
136
146
|
/**
|
|
137
|
-
* Detect whether
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
* GitHub-tracker only — no
|
|
141
|
-
*
|
|
147
|
+
* Detect whether `bkit-cloud.yml`'s claude job has a credential. Only fires when
|
|
148
|
+
* `.github/workflows/bkit-cloud.yml` exists. The claude job (claude-code-action) takes the
|
|
149
|
+
* `ANTHROPIC_API_KEY` repo secret OR workload identity federation (both
|
|
150
|
+
* `FEDERATION_VARIABLES` repo variables). The workflow is GitHub-tracker only — no
|
|
151
|
+
* `BKIT_LINEAR_API_KEY` dependency. Silent when gh cannot list secrets; when only the
|
|
152
|
+
* variables are unlistable, a missing key still raises the missing-credential finding.
|
|
142
153
|
*/
|
|
143
154
|
export function detectCiRouterSecrets(cwd) {
|
|
144
|
-
const findings = [];
|
|
145
155
|
const routerPath = path.join(cwd, ".github", "workflows", "bkit-cloud.yml");
|
|
146
156
|
if (!fs.existsSync(routerPath))
|
|
147
|
-
return
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
const
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
id:
|
|
157
|
+
return [];
|
|
158
|
+
const key = detectGhSecret("ANTHROPIC_API_KEY");
|
|
159
|
+
if (key === "unknown")
|
|
160
|
+
return [];
|
|
161
|
+
const variables = listGhNames("variable");
|
|
162
|
+
const federated = variables !== null && FEDERATION_VARIABLES.every((v) => variables.includes(v));
|
|
163
|
+
if (key === "present" && federated) {
|
|
164
|
+
return [
|
|
165
|
+
{
|
|
166
|
+
id: "anthropic-api-key-shadows-federation",
|
|
167
|
+
severity: "advisory",
|
|
168
|
+
detect: "The `ANTHROPIC_API_KEY` repo secret and the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are all set. claude-code-action uses the key and skips workload identity federation.",
|
|
169
|
+
action: "To run keyless, delete the secret: `gh secret delete ANTHROPIC_API_KEY`. To stay on the key, delete the variables: `gh variable delete ANTHROPIC_FEDERATION_RULE_ID` and `gh variable delete ANTHROPIC_ORGANIZATION_ID`.",
|
|
170
|
+
},
|
|
171
|
+
];
|
|
172
|
+
}
|
|
173
|
+
if (key === "present")
|
|
174
|
+
return [];
|
|
175
|
+
if (federated) {
|
|
176
|
+
if (fs.readFileSync(routerPath, "utf-8").includes("anthropic_federation_rule_id:"))
|
|
177
|
+
return [];
|
|
178
|
+
return [
|
|
179
|
+
{
|
|
180
|
+
id: "anthropic-federation-template-stale",
|
|
157
181
|
severity: "advisory",
|
|
158
|
-
detect: `
|
|
159
|
-
action:
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
});
|
|
163
|
-
}
|
|
164
|
-
// "unknown" → silent skip (CLI absent / unauthenticated).
|
|
182
|
+
detect: "The `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are set, but `.github/workflows/bkit-cloud.yml` does not pass `anthropic_federation_rule_id` to claude-code-action — the claude job exits no-op.",
|
|
183
|
+
action: "Re-copy the template: `cp .bkit/templates/.github/workflows/bkit-cloud.yml .github/workflows/bkit-cloud.yml`, then re-apply your own edits (the `runs-on` runner at minimum).",
|
|
184
|
+
},
|
|
185
|
+
];
|
|
165
186
|
}
|
|
166
|
-
return
|
|
187
|
+
return [
|
|
188
|
+
{
|
|
189
|
+
id: "anthropic-api-key-secret-missing",
|
|
190
|
+
severity: "advisory",
|
|
191
|
+
detect: variables === null
|
|
192
|
+
? "gh confirms the `ANTHROPIC_API_KEY` repo secret is not set on this GitHub repo, and could not list repo variables to check for the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` federation variables."
|
|
193
|
+
: "gh confirms neither the `ANTHROPIC_API_KEY` repo secret nor both `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables are set on this GitHub repo.",
|
|
194
|
+
action: "`.github/workflows/bkit-cloud.yml`'s claude job needs one claude credential; without it, the job exits no-op. Set ONE of:\n\n" +
|
|
195
|
+
"- API key:\n\n gh secret set ANTHROPIC_API_KEY --body='<paste-value-here>'\n\n" +
|
|
196
|
+
"- Workload identity federation (keyless): Claude Console → Settings → Workload identity → Connect workload → GitHub Actions creates the issuer, service account and federation rule. Then:\n\n" +
|
|
197
|
+
" gh variable set ANTHROPIC_FEDERATION_RULE_ID --body='fdrl_...'\n" +
|
|
198
|
+
" gh variable set ANTHROPIC_ORGANIZATION_ID --body='<organization-uuid>'\n\n" +
|
|
199
|
+
" Optional: `ANTHROPIC_SERVICE_ACCOUNT_ID` (`svac_...`) and `ANTHROPIC_WORKSPACE_ID` (`wrkspc_...`, needed when the rule covers more than one workspace).\n\n" +
|
|
200
|
+
"Then verify: `gh secret list` / `gh variable list`. The workflow itself does not need redeploying — both are read at run time.",
|
|
201
|
+
},
|
|
202
|
+
];
|
|
167
203
|
}
|
|
@@ -73,7 +73,6 @@ export function detectCiYmlMissingActionlint(cwd) {
|
|
|
73
73
|
detect: ".github/workflows/bkit-ci.yml (adopted from bkit's template) has no actionlint step. yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
|
|
74
74
|
action: "Add an actionlint step among the static checks in .github/workflows/bkit-ci.yml (before the test/build group):\n\n" +
|
|
75
75
|
" - name: Run actionlint\n" +
|
|
76
|
-
" if: steps.cache.outputs.skip != 'true'\n" +
|
|
77
76
|
" run: |\n" +
|
|
78
77
|
' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
|
|
79
78
|
' bash "$RUNNER_TEMP/download-actionlint.bash" 1.7.12 "$RUNNER_TEMP"\n' +
|
|
@@ -64,7 +64,8 @@ export function detectActionsWritePermissions() {
|
|
|
64
64
|
*
|
|
65
65
|
* - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
|
|
66
66
|
* - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
|
|
67
|
-
* - `
|
|
67
|
+
* - `jira` → admin switch, BKIT_JIRA_API_TOKEN and `bkit.jira` in package.json.
|
|
68
|
+
* - `none` → prompt to run `bkit install --tracker=github`, `--tracker=linear` or `--tracker=jira`.
|
|
68
69
|
*
|
|
69
70
|
* Only fires when bkit workflows are installed (.claude/ or .cursor/ present).
|
|
70
71
|
*/
|
|
@@ -90,6 +91,14 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
90
91
|
action: "Linear tracker: set `BKIT_LINEAR_API_KEY` in `.bkit/.env` (generate at https://linear.app/settings/api). `LINEAR_ISSUE_ID` is injected per-session by the Linear integration — do not hardcode. Run `direnv allow` after setting the key so MCP servers and the preflight hook can authenticate.",
|
|
91
92
|
};
|
|
92
93
|
}
|
|
94
|
+
if (tracker === "jira") {
|
|
95
|
+
return {
|
|
96
|
+
id: "tracker-setup-jira",
|
|
97
|
+
severity: "advisory",
|
|
98
|
+
detect: "bkit tracker is configured as `jira`. Jira Cloud is the active tracker.",
|
|
99
|
+
action: 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_TOKEN` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
|
|
100
|
+
};
|
|
101
|
+
}
|
|
93
102
|
// tracker === "none". Distinguish opt-out (explicit `bkit.issueTracker: "none"`)
|
|
94
103
|
// from undecided (field absent). An explicit `none` silences the nudge, as with the
|
|
95
104
|
// dep-updater advisory.
|
|
@@ -99,22 +108,23 @@ export function buildTrackerSetupAdvisory(cwd) {
|
|
|
99
108
|
id: "tracker-setup-none",
|
|
100
109
|
severity: "advisory",
|
|
101
110
|
detect: "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
|
|
102
|
-
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended)
|
|
111
|
+
action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_TOKEN` in `.bkit/.env` and `bkit.jira` in package.json. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
|
|
103
112
|
};
|
|
104
113
|
}
|
|
105
114
|
/**
|
|
106
|
-
* Classify the `bkit.
|
|
107
|
-
* - "configured" →
|
|
115
|
+
* Classify the `bkit.github.project` board-sync config in package.json:
|
|
116
|
+
* - "configured" → a Projects v2 board URL
|
|
108
117
|
* - "opted-out" → set to `false` ("no board sync" — stay quiet)
|
|
118
|
+
* - "invalid" → a string that is not a board URL
|
|
109
119
|
* - "absent" → missing, malformed, or unreadable
|
|
110
120
|
*/
|
|
111
121
|
function readGithubProjectConfig(cwd) {
|
|
112
|
-
const
|
|
113
|
-
if (
|
|
122
|
+
const { project, projectUrl } = readBkitConfig(cwd).github;
|
|
123
|
+
if (project === false)
|
|
114
124
|
return "opted-out";
|
|
115
|
-
if (
|
|
125
|
+
if (project !== null)
|
|
116
126
|
return "configured";
|
|
117
|
-
return "absent";
|
|
127
|
+
return projectUrl === null ? "absent" : "invalid";
|
|
118
128
|
}
|
|
119
129
|
/**
|
|
120
130
|
* Inspect the root `.mcp.json` github server's `X-MCP-Toolsets` header for the
|
|
@@ -144,13 +154,13 @@ export function detectProjectsToolset(cwd) {
|
|
|
144
154
|
/**
|
|
145
155
|
* GitHub Projects v2 board-sync prerequisite advisory. Board status sync needs
|
|
146
156
|
* THREE things, none of which install seeds or verifies end-to-end:
|
|
147
|
-
* `bkit.
|
|
148
|
-
* Projects R/W
|
|
149
|
-
* sync silently no-ops —
|
|
150
|
-
*
|
|
157
|
+
* `bkit.github.project` (the board URL), the `projects` MCP toolset, and a PAT
|
|
158
|
+
* with Projects R/W. Absent any of the first two (the detectable ones), board
|
|
159
|
+
* sync silently no-ops — the URL alone is useless if the toolset lacks
|
|
160
|
+
* `projects`, and vice versa. Emits one advisory naming what's missing.
|
|
151
161
|
*
|
|
152
162
|
* Gates: workflows installed (.claude/ or .cursor/) AND tracker === "github".
|
|
153
|
-
* Stays quiet on explicit opt-out (`bkit.
|
|
163
|
+
* Stays quiet on explicit opt-out (`bkit.github.project: false`) or when both
|
|
154
164
|
* detectable prerequisites are satisfied (PAT scope can't be checked locally).
|
|
155
165
|
*/
|
|
156
166
|
export function buildGithubProjectAdvisory(cwd) {
|
|
@@ -169,8 +179,10 @@ export function buildGithubProjectAdvisory(cwd) {
|
|
|
169
179
|
if (configOk && toolsetOk)
|
|
170
180
|
return null;
|
|
171
181
|
const missing = [];
|
|
172
|
-
if (
|
|
173
|
-
missing.push("`bkit.
|
|
182
|
+
if (configState === "absent")
|
|
183
|
+
missing.push("`bkit.github.project` is absent from package.json");
|
|
184
|
+
if (configState === "invalid")
|
|
185
|
+
missing.push("`bkit.github.project` is not a GitHub Projects board URL");
|
|
174
186
|
if (toolset === "missing")
|
|
175
187
|
missing.push("the `projects` toolset is missing from `.mcp.json` `X-MCP-Toolsets`");
|
|
176
188
|
const missingPhrase = missing.length > 0 ? `: ${missing.join("; ")}` : "";
|
|
@@ -180,68 +192,18 @@ export function buildGithubProjectAdvisory(cwd) {
|
|
|
180
192
|
detect: `GitHub tracker is active but Projects v2 board status sync is not fully configured${missingPhrase}. ` +
|
|
181
193
|
"Board sync silently no-ops — workflows never reflect phase on the project board.",
|
|
182
194
|
action: "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
|
|
183
|
-
"1. Add
|
|
195
|
+
"1. Add the board's URL to package.json, as the browser shows it on the board (`/orgs/<org>/…` for an organization board, `/users/<login>/…` for a personal one; a trailing `/views/<n>` is fine):\n\n" +
|
|
184
196
|
' "bkit": {\n' +
|
|
185
|
-
' "
|
|
186
|
-
' "owner": "<org>", "number": <project-number>,\n' +
|
|
187
|
-
' "statusFieldId": <numeric-field-id>, "progressOptionId": "<option-id>",\n' +
|
|
188
|
-
' "reviewOptionId": "<option-id>", "doneOptionId": "<option-id>"\n' +
|
|
189
|
-
" }\n" +
|
|
197
|
+
' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
|
|
190
198
|
" }\n\n" +
|
|
191
|
-
"
|
|
192
|
-
|
|
193
|
-
"the option ids (quoted strings). `gh project field-list`'s `id` is the GraphQL node id (`PVTSSF_…`) " +
|
|
194
|
-
"and must NOT be used for `statusFieldId` — `projects_write` rejects it with " +
|
|
195
|
-
"`updated_field.id: value must be a number`.\n\n" +
|
|
199
|
+
" Workflows set the board's Status field by option name: `In progress` when a phase starts, `In review` at hand-off. " +
|
|
200
|
+
'A board whose Status options are named differently sets `"progress"` and `"review"` beside `"project"` to its own names.\n\n' +
|
|
196
201
|
"2. Ensure the root `.mcp.json` github server enables the `projects` toolset:\n\n" +
|
|
197
202
|
' "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"\n\n' +
|
|
198
|
-
"3. The `BKIT_GH_TOKEN` PAT needs
|
|
199
|
-
"
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
/**
|
|
203
|
-
* Static-validate the `statusFieldId` shape on an otherwise-configured board.
|
|
204
|
-
* Projects v2 board sync feeds `statusFieldId` straight into `projects_write`
|
|
205
|
-
* `updated_field.id`, which requires the NUMERIC field id; a GraphQL node id
|
|
206
|
-
* (`PVTSSF_…` — what `gh project field-list` returns) or any non-number value is
|
|
207
|
-
* rejected with `updated_field.id: value must be a number`, and best-effort sync then
|
|
208
|
-
* no-ops silently. Checked at install/check time, no network needed.
|
|
209
|
-
*
|
|
210
|
-
* Gates: workflows installed AND tracker === "github" AND `bkit.githubProject` is
|
|
211
|
-
* an object carrying `owner` + `number` (an otherwise-usable board) AND
|
|
212
|
-
* `statusFieldId` is present but not a JSON number. An absent `statusFieldId` is
|
|
213
|
-
* the setup advisory's job; opt-out (`false`) and absent config never reach here.
|
|
214
|
-
*/
|
|
215
|
-
export function detectGithubProjectFieldIdFormat(cwd) {
|
|
216
|
-
const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
|
|
217
|
-
const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
|
|
218
|
-
if (!hasClaude && !hasCursor)
|
|
219
|
-
return null;
|
|
220
|
-
const { issueTracker, githubProject: gp } = readBkitConfig(cwd);
|
|
221
|
-
if (issueTracker !== "github")
|
|
222
|
-
return null;
|
|
223
|
-
// Only judge a board that is otherwise configured (owner + number present) and
|
|
224
|
-
// has a statusFieldId set — absent statusFieldId is handled by the setup advisory.
|
|
225
|
-
if (!gp || gp.owner === undefined || gp.number === undefined)
|
|
226
|
-
return null;
|
|
227
|
-
const sfid = gp.statusFieldId;
|
|
228
|
-
if (sfid === undefined || typeof sfid === "number")
|
|
229
|
-
return null; // absent or already correct
|
|
230
|
-
const looksLikeNodeId = typeof sfid === "string" && /^PVT/.test(sfid);
|
|
231
|
-
const shape = looksLikeNodeId
|
|
232
|
-
? "a GraphQL node id (`PVTSSF_…`)"
|
|
233
|
-
: `a ${typeof sfid} (\`${String(sfid)}\`)`;
|
|
234
|
-
return {
|
|
235
|
-
id: "github-project-status-field-id-format",
|
|
236
|
-
severity: "advisory",
|
|
237
|
-
detect: `\`bkit.githubProject.statusFieldId\` is ${shape}, but Projects v2 board sync feeds it to ` +
|
|
238
|
-
"`projects_write` `updated_field.id`, which requires the numeric field id and rejects anything " +
|
|
239
|
-
"else (`updated_field.id: value must be a number`). Board sync silently no-ops — the board never reflects phase.",
|
|
240
|
-
action: "Re-derive the numeric Status field id and store it unquoted:\n\n" +
|
|
241
|
-
" gh api /orgs/<org>/projectsV2/<number>/fields --jq '.[] | select(.name==\"Status\")'\n\n" +
|
|
242
|
-
"The Status field's numeric `id` (e.g. `350038178`) → `statusFieldId` (a JSON number, NOT quoted); " +
|
|
243
|
-
"each `options[].id` (e.g. `47fc9ee4`) → the option ids (quoted strings). `gh project field-list`'s " +
|
|
244
|
-
"`id` is the GraphQL node id (`PVTSSF_…`) and must NOT be used for `statusFieldId`.",
|
|
203
|
+
"3. The `BKIT_GH_TOKEN` PAT needs Projects read & write (repo scope is not enough): a fine-grained PAT gets it as an " +
|
|
204
|
+
"organization permission, so it reaches organization boards only; a classic PAT with the `project` scope reaches " +
|
|
205
|
+
"organization and personal boards.\n\n" +
|
|
206
|
+
"To opt out and silence this advisory, set `bkit.github.project` to `false` in package.json.",
|
|
245
207
|
};
|
|
246
208
|
}
|
|
247
209
|
/**
|
|
@@ -259,6 +221,7 @@ export function detectGithubProjectFieldIdFormat(cwd) {
|
|
|
259
221
|
* opt-out):
|
|
260
222
|
* - `.github/workflows/bkit-cloud.yml` present → `cloud-router` (informational; active)
|
|
261
223
|
* - `bkit.cloudAgents === "none"` → null (opt-out — stay quiet)
|
|
224
|
+
* - `bkit.issueTracker === "jira"` → null (Jira runs locally only)
|
|
262
225
|
* - otherwise (undecided) → `cloud-router-none` (nudge to choose)
|
|
263
226
|
*
|
|
264
227
|
* Only fires when there is a `.github/workflows/` dir (the router wakes on a CI
|
|
@@ -285,14 +248,16 @@ export function buildCloudSetupAdvisory(cwd) {
|
|
|
285
248
|
id: "cloud-router",
|
|
286
249
|
severity: "advisory",
|
|
287
250
|
detect: "Cloud agents: post-CI auto-routing is active (`.github/workflows/bkit-cloud.yml` present). The Claude GitHub App is required — run `/install-github-app` (Claude Code CLI) once if not already done.",
|
|
288
|
-
action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
|
|
251
|
+
action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret OR the \`ANTHROPIC_FEDERATION_RULE_ID\` + \`ANTHROPIC_ORGANIZATION_ID\` repo variables (keyless workload identity federation), the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
|
|
289
252
|
};
|
|
290
253
|
}
|
|
291
254
|
// No router present — distinguish opt-out from undecided.
|
|
292
|
-
const { cloudAgents, cloudAgentsExplicit } = readBkitConfig(cwd);
|
|
255
|
+
const { cloudAgents, cloudAgentsExplicit, issueTracker } = readBkitConfig(cwd);
|
|
293
256
|
if (cloudAgents === "none" && cloudAgentsExplicit) {
|
|
294
257
|
return null; // consumer explicitly chose `none` — stay quiet
|
|
295
258
|
}
|
|
259
|
+
if (issueTracker === "jira")
|
|
260
|
+
return null; // no cloud setup exists for a Jira tracker
|
|
296
261
|
// Only nudge if there's a workflows dir for the router to wake on.
|
|
297
262
|
if (!fs.existsSync(path.join(cwd, ".github", "workflows")))
|
|
298
263
|
return null;
|
|
@@ -301,7 +266,7 @@ export function buildCloudSetupAdvisory(cwd) {
|
|
|
301
266
|
severity: "advisory",
|
|
302
267
|
detect: "Cloud agents: post-CI auto-routing is not configured. `.github/workflows/` exists but no `bkit-cloud.yml` — CI pass/fail does not auto-dispatch bkit-ship / bkit-debug.",
|
|
303
268
|
action: "Optional post-install decision. For a GitHub-tracker repo: `pnpm bkit install --auto=claude --tracker=github`. For a Linear-tracker repo: `pnpm bkit install --auto=cursor --tracker=linear`.\n\n" +
|
|
304
|
-
"Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
|
|
269
|
+
"Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret (or the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables for keyless workload identity federation) + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
|
|
305
270
|
'To opt out and silence this advisory, set `bkit.cloudAgents` to `"none"` in package.json.',
|
|
306
271
|
};
|
|
307
272
|
}
|
|
@@ -10,7 +10,7 @@ import { readBkitConfig } from "../../shared/settings.js";
|
|
|
10
10
|
import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
|
|
11
11
|
import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
|
|
12
12
|
import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
|
|
13
|
-
import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions,
|
|
13
|
+
import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectMainBranchProtection, } from "./github.js";
|
|
14
14
|
import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
|
|
15
15
|
import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
|
|
16
16
|
import { dropTipSilencedAdvisories, setupTipsChecklistLines, setupTipsMarkdownLines, } from "../tips/index.js";
|
|
@@ -297,18 +297,13 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
|
|
|
297
297
|
const githubProjectSetup = buildGithubProjectAdvisory(cwd);
|
|
298
298
|
if (githubProjectSetup)
|
|
299
299
|
phase3.push(githubProjectSetup);
|
|
300
|
-
// A configured board can still silently no-op if statusFieldId holds the GraphQL
|
|
301
|
-
// node id instead of the numeric field id projects_write requires.
|
|
302
|
-
const githubProjectFieldId = detectGithubProjectFieldIdFormat(cwd);
|
|
303
|
-
if (githubProjectFieldId)
|
|
304
|
-
phase3.push(githubProjectFieldId);
|
|
305
300
|
const depUpdaterSetup = buildDepUpdaterSetupAdvisory(cwd);
|
|
306
301
|
if (depUpdaterSetup)
|
|
307
302
|
phase3.push(depUpdaterSetup);
|
|
308
303
|
const cloudSetup = buildCloudSetupAdvisory(cwd);
|
|
309
304
|
if (cloudSetup)
|
|
310
305
|
phase3.push(cloudSetup);
|
|
311
|
-
// bkit-cloud.yml needs the ANTHROPIC_API_KEY repo secret.
|
|
306
|
+
// bkit-cloud.yml's claude job needs the ANTHROPIC_API_KEY repo secret or federation variables.
|
|
312
307
|
for (const f of detectCiRouterSecrets(cwd))
|
|
313
308
|
phase3.push(f);
|
|
314
309
|
// bkit-cloud.yml also needs repo Actions write permissions + PR-creation
|
|
@@ -106,7 +106,7 @@ const BKIT_STUBS = [
|
|
|
106
106
|
{
|
|
107
107
|
id: "coverage",
|
|
108
108
|
file: ".github/workflows/bkit-ci.yml",
|
|
109
|
-
description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `
|
|
109
|
+
description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive), so omitting `contents: read` breaks the checkout; (4) two report steps with distinct `name:` (unit / integration) pointing at each dir's coverage-summary.json + coverage-final.json; the unit step runs on every event (`if: !cancelled()` plus a `hashFiles` guard on its summary), sets `vite-config-path: vitest.unit.config.ts` so the job summary and PR comment show the floor as the target, and comments only on same-repo PRs (`comment-on: pr`, else `none`). SEPARATE LANES (one job per tier): put the integration run + report + its OWN pull-requests: write block in bkit-tests-integration, not bkit-tests-unit — each lane posts its own comment. Thresholds are opt-in and PER TIER: UNIT is the gate — put `coverage.thresholds.branches` in a `vitest.unit.config.ts` (`mergeConfig` over vitest.config) that ONLY the unit run loads via `-c` (vitest coverage is per-RUN/root config, NOT per-project — `projects` does not scope it and a `thresholds` block in vitest.config reds BOTH runs; the report action reads the same file as raw text, so keep the floor on one unquoted `branches: <n>` line and no other metric name + colon + number in it; branches is the meaningful floor, set to current and ratchet up). INTEGRATION is REPORT-ONLY — gate it on EXECUTION (the capstone's integration_ran > 0), not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic). For a real integration %, add `--coverage.include=src/server/**` on the integration run (same CLI-flag idiom as --exclude) then set a floor, or ratchet from current — never a picked number. Fork PRs: GITHUB_TOKEN is read-only, so the unit step sets `comment-on: none` there (its job summary still lands) and the integration step keeps the `head.repo == repo` guard (or use the action's workflow_run two-workflow pattern). Guard the integration report on `hashFiles('coverage/integration/coverage-summary.json') != ''` so a repo with no integration tier skips it cleanly.",
|
|
110
110
|
},
|
|
111
111
|
{
|
|
112
112
|
id: "e2e-coverage",
|
|
@@ -6,14 +6,29 @@ import { spawnSync } from "node:child_process";
|
|
|
6
6
|
// ---------------------------------------------------------------------------
|
|
7
7
|
// [mcp-env] advisories — direnv + .bkit/.env setup (BAR-260)
|
|
8
8
|
// ---------------------------------------------------------------------------
|
|
9
|
+
/** The token a tracker's MCP server reads from `.bkit/.env`, beside `BKIT_GH_TOKEN`. */
|
|
10
|
+
const TRACKER_TOKENS = {
|
|
11
|
+
linear: {
|
|
12
|
+
key: "BKIT_LINEAR_API_KEY",
|
|
13
|
+
description: "Linear personal API key for the Linear MCP server and the Linear preflight hook (generate at https://linear.app/settings/api)",
|
|
14
|
+
},
|
|
15
|
+
jira: {
|
|
16
|
+
key: "BKIT_JIRA_API_TOKEN",
|
|
17
|
+
description: 'Atlassian API token with scopes for the app "Atlassian MCP V2", sent as Bearer to the Jira MCP server (create at https://id.atlassian.com/manage-profile/security/api-tokens; see .bkit/trackers.md § jira)',
|
|
18
|
+
},
|
|
19
|
+
};
|
|
20
|
+
/** The token names `tracker` needs, `BKIT_GH_TOKEN` first. */
|
|
21
|
+
function tokenKeys(tracker) {
|
|
22
|
+
const own = TRACKER_TOKENS[tracker];
|
|
23
|
+
return own ? ["BKIT_GH_TOKEN", own.key] : ["BKIT_GH_TOKEN"];
|
|
24
|
+
}
|
|
9
25
|
/**
|
|
10
26
|
* Advisory: .bkit/.env.example exists but .bkit/.env does not.
|
|
11
27
|
* Consumer ran `bkit install` (which seeds .env.example) but has not yet
|
|
12
28
|
* copied it to .bkit/.env and filled in their tokens.
|
|
13
29
|
*/
|
|
14
|
-
// `tracker`
|
|
15
|
-
//
|
|
16
|
-
// caller passes the consumer's resolved `bkit.issueTracker`.
|
|
30
|
+
// `tracker` adds its own token to the token prose (`TRACKER_TOKENS`). Defaults to
|
|
31
|
+
// `linear`; the real Phase-3 caller passes the consumer's resolved `bkit.issueTracker`.
|
|
17
32
|
export function detectMissingDotenv(cwd, tracker = "linear") {
|
|
18
33
|
const examplePath = path.join(cwd, ".bkit", ".env.example");
|
|
19
34
|
const envPath = path.join(cwd, ".bkit", ".env");
|
|
@@ -21,7 +36,7 @@ export function detectMissingDotenv(cwd, tracker = "linear") {
|
|
|
21
36
|
return null;
|
|
22
37
|
if (fs.existsSync(envPath))
|
|
23
38
|
return null;
|
|
24
|
-
const tokens = tracker
|
|
39
|
+
const tokens = tokenKeys(tracker).join(", ");
|
|
25
40
|
return {
|
|
26
41
|
id: "mcp-env-missing-dotenv",
|
|
27
42
|
severity: "advisory",
|
|
@@ -57,15 +72,8 @@ export function detectBlankDotenvKeys(cwd, tracker = "linear") {
|
|
|
57
72
|
key: "BKIT_GH_TOKEN",
|
|
58
73
|
description: "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write), or a classic PAT when one token must span owners",
|
|
59
74
|
},
|
|
60
|
-
//
|
|
61
|
-
...(tracker
|
|
62
|
-
? [
|
|
63
|
-
{
|
|
64
|
-
key: "BKIT_LINEAR_API_KEY",
|
|
65
|
-
description: "Linear personal API key for the Linear MCP server and the Linear preflight hook (generate at https://linear.app/settings/api)",
|
|
66
|
-
},
|
|
67
|
-
]
|
|
68
|
-
: []),
|
|
75
|
+
// A tracker token is required only under its tracker.
|
|
76
|
+
...(TRACKER_TOKENS[tracker] ? [TRACKER_TOKENS[tracker]] : []),
|
|
69
77
|
];
|
|
70
78
|
const findings = [];
|
|
71
79
|
for (const { key, description } of REQUIRED_KEYS) {
|
|
@@ -105,9 +113,8 @@ export function detectDirenvMissing(cwd, tracker = "linear") {
|
|
|
105
113
|
const result = spawnSync("which", ["direnv"], { encoding: "utf-8" });
|
|
106
114
|
if (result.status === 0 && result.stdout.trim())
|
|
107
115
|
return null;
|
|
108
|
-
|
|
109
|
-
const
|
|
110
|
-
const exportKeys = tracker === "linear" ? "BKIT_GH_TOKEN / BKIT_LINEAR_API_KEY" : "BKIT_GH_TOKEN";
|
|
116
|
+
const editKeys = tokenKeys(tracker).join(", ");
|
|
117
|
+
const exportKeys = tokenKeys(tracker).join(" / ");
|
|
111
118
|
return {
|
|
112
119
|
id: "mcp-env-direnv-missing",
|
|
113
120
|
severity: "advisory",
|
|
@@ -156,7 +163,7 @@ export function detectDirenvNotAllowed(cwd, tracker = "linear") {
|
|
|
156
163
|
id: "mcp-env-direnv-not-allowed",
|
|
157
164
|
severity: "advisory",
|
|
158
165
|
detect: "direnv is installed but the .envrc in this repo is blocked. .bkit/.env is not being auto-loaded.",
|
|
159
|
-
action: `[mcp-env] Run \`direnv allow\` in this repo to trust the .envrc and enable auto-load of .bkit/.env. direnv will then export ${tracker
|
|
166
|
+
action: `[mcp-env] Run \`direnv allow\` in this repo to trust the .envrc and enable auto-load of .bkit/.env. direnv will then export ${tokenKeys(tracker).join(" and ")} into your shell whenever you cd into the repo.`,
|
|
160
167
|
};
|
|
161
168
|
}
|
|
162
169
|
return null;
|
|
@@ -3,7 +3,7 @@ import * as fs from "node:fs";
|
|
|
3
3
|
import * as path from "node:path";
|
|
4
4
|
import { parseJson } from "../../shared/json.js";
|
|
5
5
|
/** Every MCP server key bkit writes; `requiredMcpServersForTracker` picks the required subset. */
|
|
6
|
-
const BKIT_MCP_SERVERS = ["linear", "github"];
|
|
6
|
+
const BKIT_MCP_SERVERS = ["linear", "github", "jira"];
|
|
7
7
|
/**
|
|
8
8
|
* bkit-written servers a workflow step calls under every tracker, so never flagged as extra:
|
|
9
9
|
* the workflows' gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls `github`.
|
|
@@ -60,7 +60,9 @@ export function detectMissingMcpServers(cwd, relPath, issueTracker) {
|
|
|
60
60
|
? `"url": "https://mcp.linear.app/mcp"`
|
|
61
61
|
: key === "github"
|
|
62
62
|
? `"url": "https://api.githubcopilot.com/mcp/"`
|
|
63
|
-
:
|
|
63
|
+
: key === "jira"
|
|
64
|
+
? `"url": "https://mcp.atlassian.com/v2/mcp"`
|
|
65
|
+
: `"url": "<server-url>"`;
|
|
64
66
|
findings.push({
|
|
65
67
|
id: `mcp-missing-server-${key}-${advisoryPathSlug(relPath)}`,
|
|
66
68
|
severity: "advisory",
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
// names its ids, so the tip and the advisory can never disagree and one
|
|
22
22
|
// `bkit.ignoreAdvisories` entry silences both.
|
|
23
23
|
import * as fs from "node:fs";
|
|
24
|
+
import * as path from "node:path";
|
|
24
25
|
import { machineStepsPath, REPO_STEPS } from "../../commands/workflow/disk.js";
|
|
25
26
|
import { detectContextFetchMissing } from "../before/context-fetch.js";
|
|
26
27
|
import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
|
|
@@ -41,7 +42,7 @@ export const SETUP_TIPS = [
|
|
|
41
42
|
id: "tracker",
|
|
42
43
|
workflows: EVERY_CONTEXT,
|
|
43
44
|
title: "Connect an issue tracker",
|
|
44
|
-
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
|
|
45
|
+
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, Linear or Jira, or switch this tip off if you don't want one.",
|
|
45
46
|
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.",
|
|
46
47
|
ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.issueTracker` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
|
|
47
48
|
steps: '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "issueTracker": "none" }` in `package.json`.',
|
|
@@ -182,7 +183,7 @@ export const SETUP_TIPS = [
|
|
|
182
183
|
title: "Finish cloud setup",
|
|
183
184
|
line: "You've turned on cloud agents, but setup isn't finished, so cloud runs will stop partway. Finish the remaining steps.",
|
|
184
185
|
why: "With cloud agents, bkit runs on its own: a change that passes its checks gets shipped and one that fails gets investigated, with nobody at the keyboard. That only works once every piece is in place.",
|
|
185
|
-
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
|
|
186
|
+
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` (or, keyless, `gh variable set` ANTHROPIC_FEDERATION_RULE_ID and ANTHROPIC_ORGANIZATION_ID from a Claude Console federation rule), then tell me which dashboard settings are left.",
|
|
186
187
|
steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
|
|
187
188
|
fires: (cwd) => {
|
|
188
189
|
const cloud = readBkitConfig(cwd).cloudAgents;
|
|
@@ -314,6 +315,17 @@ export const SETUP_TIPS = [
|
|
|
314
315
|
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
315
316
|
fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
316
317
|
},
|
|
318
|
+
{
|
|
319
|
+
id: "min-push",
|
|
320
|
+
workflows: ["plan", "ship"],
|
|
321
|
+
title: "Quick pushes for logs and records",
|
|
322
|
+
line: "Pushing only plan logs and records still runs every test. Add the quick path for those pushes.",
|
|
323
|
+
why: "A workflow's last push is often just its logs and records. The quick path checks only formatting and wording on such a push, so it takes seconds and never waits on anything another session is using. Any other file still runs everything.",
|
|
324
|
+
ask: 'Copy the min-push parts of .bkit/templates/.husky/pre-push into .husky/pre-push: PUSH_SHAS / PUSH_SHARED_SHAS in the stdin loop, the `Min push` and `CI-suppressor guard on dev / main` blocks, and the `bkit:gate:min` branch. Wrap slow checks below the gates in `if [ "$MIN_PUSH" != "1" ]`.',
|
|
325
|
+
steps: "`.bkit/templates.md` § Git hooks.",
|
|
326
|
+
fires: (cwd) => exists(cwd, ".husky/pre-push") &&
|
|
327
|
+
!fs.readFileSync(path.join(cwd, ".husky/pre-push"), "utf-8").includes("bkit ci min-push"),
|
|
328
|
+
},
|
|
317
329
|
{
|
|
318
330
|
id: "disk-prune",
|
|
319
331
|
workflows: ALL_WORKFLOWS,
|
|
@@ -17,7 +17,7 @@ export function silenceLine(ids) {
|
|
|
17
17
|
const names = ids.map((id) => `\`${id}\``);
|
|
18
18
|
const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
|
|
19
19
|
const what = ids.length > 1 ? "these tips" : "this tip";
|
|
20
|
-
return
|
|
20
|
+
return `**Want to silence ${what}?** Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
|
|
21
21
|
}
|
|
22
22
|
/** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
|
|
23
23
|
export const STAR_TIP_ID = "bkit-star";
|
|
@@ -29,6 +29,8 @@ export const STAR_TIP_OLD_ID = "star";
|
|
|
29
29
|
* gap, so never in the checklist.
|
|
30
30
|
*/
|
|
31
31
|
export const STAR_TIP = "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
|
|
32
|
+
/** `STAR_TIP` for a workflow's `## bkit Tips`, its question bold like each tip's title. */
|
|
33
|
+
export const STAR_TIP_PARAGRAPH = STAR_TIP.replace("Do you like bkit?", "**Do you like bkit?**");
|
|
32
34
|
/** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
|
|
33
35
|
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.";
|
|
34
36
|
/** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
|
|
@@ -126,7 +128,7 @@ function formatWorkflowTips(tips, workflow, star) {
|
|
|
126
128
|
const ids = shown.map((t) => t.id);
|
|
127
129
|
const parts = shown.map(tipParagraph);
|
|
128
130
|
if (star) {
|
|
129
|
-
parts.push(
|
|
131
|
+
parts.push(STAR_TIP_PARAGRAPH);
|
|
130
132
|
ids.push(STAR_TIP_ID);
|
|
131
133
|
}
|
|
132
134
|
if (ids.length === 0)
|