@cbartens/bkit 5.2.4 → 5.4.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 +27 -11
- 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 +18 -1
- package/.bkit/core/.bkit/README.md +26 -10
- package/.bkit/core/.bkit/cloud.md +40 -39
- package/.bkit/core/.bkit/comparison.md +68 -345
- package/.bkit/core/.bkit/install.md +16 -9
- package/.bkit/core/.bkit/lite.md +73 -0
- package/.bkit/core/.bkit/pipeline.md +346 -0
- package/.bkit/core/.bkit/prompts.md +90 -74
- package/.bkit/core/.bkit/providers.md +42 -23
- package/.bkit/core/.bkit/templates.md +138 -19
- package/.bkit/core/.bkit/trackers.md +49 -4
- package/.bkit/core/.bkit/workflows.md +144 -123
- 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 +3 -2
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
- package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
- package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -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 -6
- package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
- package/.bkit/core/engine/checks/tips/detect.ts +45 -2
- package/.bkit/core/engine/checks/tips/index.ts +77 -26
- package/.bkit/core/engine/cli.ts +57 -27
- package/.bkit/core/engine/commands/analysis.ts +36 -26
- package/.bkit/core/engine/commands/comply.ts +42 -32
- 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 +73 -130
- package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
- package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
- package/.bkit/core/engine/commands/land.ts +156 -0
- package/.bkit/core/engine/commands/lib.ts +45 -18
- package/.bkit/core/engine/commands/registry.ts +2 -0
- package/.bkit/core/engine/commands/tips.ts +12 -5
- package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
- package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
- package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
- package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
- package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
- package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
- package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
- package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
- package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
- package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
- package/.bkit/core/engine/commands/workflow/status.ts +33 -11
- package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
- package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
- package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
- package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
- 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 +106 -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 +16 -35
- 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/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 +44 -0
- package/.bkit/core/engine/shared/timeouts.ts +8 -7
- 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 +103 -7
- 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-auto.md +2 -2
- package/.bkit/core/workflows/bkit-build.md +10 -10
- package/.bkit/core/workflows/bkit-debug.md +80 -44
- package/.bkit/core/workflows/bkit-design.md +22 -13
- package/.bkit/core/workflows/bkit-plan.md +33 -16
- package/.bkit/core/workflows/bkit-ship.md +87 -98
- package/.bkit/shared/.claude/bkit-cloud.md +58 -25
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.cursor/mcp.json +2 -1
- package/.bkit/shared/.opencode/opencode.json +19 -1
- package/.bkit/shared/docs/deployments.md +49 -29
- package/.bkit/shared/docs/security.md +8 -6
- package/.bkit/shared/docs/testing.md +9 -5
- package/.bkit/shared/gitignore +1 -2
- 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 +73 -55
- 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-commit +6 -0
- package/.bkit/templates/.husky/pre-push +15 -3
- package/.bkit/templates/.lintstagedrc.json +5 -1
- 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-disk-prune.machine.mjs +197 -0
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -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 +98 -3
- package/README.md +252 -122
- 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 -7
- package/dist/checks/tips/catalogue.js +65 -18
- package/dist/checks/tips/detect.js +41 -2
- package/dist/checks/tips/index.js +61 -25
- package/dist/cli.js +52 -26
- package/dist/commands/analysis.js +21 -5
- package/dist/commands/comply.js +40 -31
- package/dist/commands/harvest.js +12 -13
- package/dist/commands/install/doctor.js +55 -23
- package/dist/commands/install/install.js +72 -122
- package/dist/commands/install/uninstall.js +165 -31
- package/dist/commands/install/upgrade.js +46 -39
- package/dist/commands/land.js +129 -0
- package/dist/commands/lib.js +41 -16
- package/dist/commands/registry.js +2 -0
- package/dist/commands/tips.js +10 -3
- package/dist/commands/workflow/branches.js +303 -248
- package/dist/commands/workflow/counters.js +17 -7
- package/dist/commands/workflow/disk.js +452 -0
- package/dist/commands/workflow/fids.js +39 -0
- package/dist/commands/workflow/issues.js +63 -27
- package/dist/commands/workflow/ledgers.js +3 -1
- package/dist/commands/workflow/locks.js +35 -130
- package/dist/commands/workflow/prs.js +8 -5
- package/dist/commands/workflow/repo.js +2 -2
- package/dist/commands/workflow/roadmap.js +50 -57
- package/dist/commands/workflow/runs.js +5 -5
- package/dist/commands/workflow/runtime.js +3 -2
- package/dist/commands/workflow/status.js +32 -12
- package/dist/commands/workflow/steps.js +19 -11
- package/dist/commands/workflow/tests.js +16 -3
- package/dist/commands/workflow/workflows.js +390 -249
- package/dist/commands/workflow/workstreams.js +4 -2
- package/dist/commands/workflow/worktrees.js +15 -6
- 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 +95 -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 +16 -35
- 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/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 +23 -1
- package/dist/shared/timeouts.js +8 -7
- package/package.json +21 -17
- package/.bkit/core/.agents/shortcuts.md +0 -73
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
5
|
import { spawnSync } from "node:child_process";
|
|
6
|
+
import { readJsonFile } from "../../shared/json.js";
|
|
6
7
|
import { isCloudOrCi } from "./env.js";
|
|
7
8
|
// ---------------------------------------------------------------------------
|
|
8
9
|
// Blocker detectors
|
|
@@ -21,18 +22,14 @@ export function detectMalformedPackageJson(cwd) {
|
|
|
21
22
|
const pkgPath = path.join(cwd, "package.json");
|
|
22
23
|
if (!fs.existsSync(pkgPath))
|
|
23
24
|
return null;
|
|
24
|
-
|
|
25
|
-
JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
|
|
25
|
+
if (readJsonFile(pkgPath).ok)
|
|
26
26
|
return null;
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
|
|
34
|
-
};
|
|
35
|
-
}
|
|
27
|
+
return {
|
|
28
|
+
id: "malformed-package-json",
|
|
29
|
+
severity: "blocker",
|
|
30
|
+
detect: "package.json exists but contains invalid JSON.",
|
|
31
|
+
action: "Fix the JSON syntax error in package.json (run `node -e \"JSON.parse(require('fs').readFileSync('package.json','utf8'))\"` to locate the error), then re-run `pnpm bkit install`.",
|
|
32
|
+
};
|
|
36
33
|
}
|
|
37
34
|
export function detectNotGitRepo(cwd, modules) {
|
|
38
35
|
if (!modules.has("core"))
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
import * as fs from "node:fs";
|
|
26
26
|
import * as path from "node:path";
|
|
27
27
|
import { fileURLToPath } from "node:url";
|
|
28
|
+
import { parseJson } from "../shared/json.js";
|
|
28
29
|
import { getWorkflowsRoot } from "../shared/package-roots.js";
|
|
29
30
|
// ---------------------------------------------------------------------------
|
|
30
31
|
// Canonical ship step order (mirrors audits/workflows/ship-invariants.test.ts
|
|
@@ -46,7 +47,6 @@ export const SHIP_STEP_ORDER = [
|
|
|
46
47
|
"ship-failure-diagnose",
|
|
47
48
|
"ship-failure-remediate",
|
|
48
49
|
"ship-switch-to-dev",
|
|
49
|
-
"ship-worktree-cleanup",
|
|
50
50
|
"ship-close-workflow",
|
|
51
51
|
];
|
|
52
52
|
/** Steps that appear only in the merge-retry loop — never mandatory, never holes. */
|
|
@@ -274,12 +274,10 @@ export function auditStatusJsonl(statusJsonl, shipMd) {
|
|
|
274
274
|
const trimmed = line.trim();
|
|
275
275
|
if (!trimmed)
|
|
276
276
|
continue;
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
void _e; // skip unparseable lines (advisory — never throw)
|
|
282
|
-
}
|
|
277
|
+
// Unparseable lines are skipped (advisory — never throw).
|
|
278
|
+
const row = parseJson(trimmed);
|
|
279
|
+
if (row.ok)
|
|
280
|
+
rows.push(row.value);
|
|
283
281
|
}
|
|
284
282
|
// Filter to ship step-done rows + workflow-failed rows
|
|
285
283
|
const shipStepRows = rows.filter((r) => r.type === "step-done" && r.workflow === "ship" && typeof r.step === "string");
|
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
// checks/tips/catalogue.ts — the setup-tip catalogue: one entry per template, tool or
|
|
2
|
-
// setting a consumer has not set up yet. Each workflow
|
|
3
|
-
// (`bkit tips --workflow=<name
|
|
4
|
-
//
|
|
2
|
+
// setting a consumer has not set up yet. Each workflow, `@bkit-audit-generate` and the
|
|
3
|
+
// ledger / roadmap updaters print one tip at their close (`bkit tips --workflow=<name>`,
|
|
4
|
+
// `audit` / `utility` for the agents); `bkit tips` prints the top three;
|
|
5
|
+
// `.bkit/advisories.md` lists every firing tip under `Setup tips`.
|
|
5
6
|
//
|
|
6
7
|
// Array order is the priority: comms first (can workflows reach anything), then change
|
|
7
8
|
// quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
|
|
8
9
|
// setup-specific plumbing last. `workflows` names where a tip matters: a workflow shows
|
|
9
|
-
// its own tips first, in array order, then the rest. Comms tips name every
|
|
10
|
+
// its own tips first, in array order, then the rest. Comms tips name every context, so
|
|
10
11
|
// they lead everywhere until fixed.
|
|
11
12
|
//
|
|
12
13
|
// Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
|
|
@@ -19,22 +20,26 @@
|
|
|
19
20
|
// Where an advisory already detects the gap, `fires` calls that detector and `advisories`
|
|
20
21
|
// names its ids, so the tip and the advisory can never disagree and one
|
|
21
22
|
// `bkit.ignoreAdvisories` entry silences both.
|
|
23
|
+
import * as fs from "node:fs";
|
|
24
|
+
import { machineStepsPath, REPO_STEPS } from "../../commands/workflow/disk.js";
|
|
22
25
|
import { detectContextFetchMissing } from "../before/context-fetch.js";
|
|
23
26
|
import { detectBlankDotenvKeys, detectDirenvMissing, detectDirenvNotAllowed, detectMissingDotenv, isCloudOrCi, } from "../before/env.js";
|
|
24
27
|
import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
|
|
25
|
-
import { buildTrackerSetupAdvisory
|
|
28
|
+
import { buildTrackerSetupAdvisory } from "../after/github.js";
|
|
26
29
|
import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
|
|
27
30
|
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
28
31
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
29
|
-
import { claudeSettingsHas, codexTopLevelHas, exists, hasLintStagedConfig, hasMcpServer, unlockedMcpServers, } from "./detect.js";
|
|
32
|
+
import { anyWorkflowMentions, claudeSettingsHas, codexTopLevelHas, exists, hasJsTestRunner, hasLintStagedConfig, hasMcpServer, hasTestLinter, unlockedMcpServers, } from "./detect.js";
|
|
30
33
|
const hosts = (cwd) => detectInstalledHostModules(cwd);
|
|
31
34
|
/** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
|
|
32
35
|
export const ALL_WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
|
|
36
|
+
/** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
|
|
37
|
+
export const EVERY_CONTEXT = [...ALL_WORKFLOWS, "audit", "utility"];
|
|
33
38
|
export const SETUP_TIPS = [
|
|
34
39
|
// --- connect: can bkit talk to anything at all -------------------------------------
|
|
35
40
|
{
|
|
36
41
|
id: "tracker",
|
|
37
|
-
workflows:
|
|
42
|
+
workflows: EVERY_CONTEXT,
|
|
38
43
|
title: "Connect an issue tracker",
|
|
39
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 Linear, or switch this tip off if you don't want one.",
|
|
40
45
|
why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
|
|
@@ -45,19 +50,19 @@ export const SETUP_TIPS = [
|
|
|
45
50
|
},
|
|
46
51
|
{
|
|
47
52
|
id: "gh-mcp",
|
|
48
|
-
workflows:
|
|
53
|
+
workflows: EVERY_CONTEXT,
|
|
49
54
|
title: "Give bkit its GitHub token",
|
|
50
55
|
line: "You chose GitHub as your tracker, but bkit has no GitHub token, so every attempt to read an issue or open a pull request will fail. Add the token.",
|
|
51
56
|
why: "Choosing GitHub only tells bkit where your issues live. The token is what lets it actually sign in. Without it the setting looks right but nothing works, which is confusing to track down.",
|
|
52
57
|
ask: "Add my GitHub token as `BKIT_GH_TOKEN` in .bkit/.env, check .mcp.json has the `github` server, then run `direnv allow` and tell me to restart the editor.",
|
|
53
58
|
steps: "`.bkit/install.md` § Local env setup. The `github` server entry belongs in `.mcp.json` / `.cursor/mcp.json` (`.bkit/cloud.md` § MCP issue-tracker integration).",
|
|
54
59
|
advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
|
|
55
|
-
fires: (cwd) =>
|
|
60
|
+
fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" &&
|
|
56
61
|
(!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
|
|
57
62
|
},
|
|
58
63
|
{
|
|
59
64
|
id: "bkit-env",
|
|
60
|
-
workflows:
|
|
65
|
+
workflows: EVERY_CONTEXT,
|
|
61
66
|
title: "Create bkit's private settings file",
|
|
62
67
|
line: "bkit's private settings file (.bkit/.env) is missing or has blank entries, so nothing that needs to sign in can. Create it and fill it in.",
|
|
63
68
|
why: "This one file holds the sign-in tokens every bkit tool reads. It's never shared or committed. Most other tips depend on it, so do this one early.",
|
|
@@ -67,13 +72,13 @@ export const SETUP_TIPS = [
|
|
|
67
72
|
fires: (cwd) => {
|
|
68
73
|
if (isCloudOrCi())
|
|
69
74
|
return false;
|
|
70
|
-
const tracker =
|
|
75
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
71
76
|
return (detectMissingDotenv(cwd, tracker) !== null || detectBlankDotenvKeys(cwd, tracker).length > 0);
|
|
72
77
|
},
|
|
73
78
|
},
|
|
74
79
|
{
|
|
75
80
|
id: "direnv",
|
|
76
|
-
workflows:
|
|
81
|
+
workflows: EVERY_CONTEXT,
|
|
77
82
|
title: "Load your tokens automatically",
|
|
78
83
|
line: "Your sign-in tokens are saved in .bkit/.env but not being loaded, so sign-ins will fail even though the file looks right. Set up direnv so they load whenever you open the project.",
|
|
79
84
|
why: "A saved file does nothing until something reads it. This is the most frustrating kind of breakage: nothing looks wrong, but every sign-in fails. direnv (a small tool that loads settings when you open a folder) fixes it once.",
|
|
@@ -83,7 +88,7 @@ export const SETUP_TIPS = [
|
|
|
83
88
|
fires: (cwd) => {
|
|
84
89
|
if (isCloudOrCi() || !exists(cwd, ".bkit/.env"))
|
|
85
90
|
return false;
|
|
86
|
-
const tracker =
|
|
91
|
+
const tracker = readBkitConfig(cwd).issueTracker;
|
|
87
92
|
return (!exists(cwd, ".envrc") ||
|
|
88
93
|
detectDirenvMissing(cwd, tracker) !== null ||
|
|
89
94
|
detectDirenvNotAllowed(cwd, tracker) !== null);
|
|
@@ -92,7 +97,7 @@ export const SETUP_TIPS = [
|
|
|
92
97
|
// --- quality: is the change good -----------------------------------------------------
|
|
93
98
|
{
|
|
94
99
|
id: "serena",
|
|
95
|
-
workflows: ["design", "plan", "build"],
|
|
100
|
+
workflows: ["design", "plan", "build", "audit", "utility"],
|
|
96
101
|
title: "Let agents look code up directly",
|
|
97
102
|
line: "Agents are finding code by searching for words, which is slower, costs more, and misses things. Set up Serena so they can look code up directly.",
|
|
98
103
|
why: 'Serena lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of guessing from text search and reading whole files. That means fewer accidental changes, fewer rounds of you correcting them, and lower running costs because they read less. It can only look things up, never change your files.',
|
|
@@ -102,7 +107,7 @@ export const SETUP_TIPS = [
|
|
|
102
107
|
},
|
|
103
108
|
{
|
|
104
109
|
id: "ci-workflow",
|
|
105
|
-
workflows: ["build", "ship"],
|
|
110
|
+
workflows: ["build", "ship", "audit"],
|
|
106
111
|
title: "Automatic checks on every change",
|
|
107
112
|
line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
|
|
108
113
|
why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
|
|
@@ -140,6 +145,16 @@ export const SETUP_TIPS = [
|
|
|
140
145
|
steps: "`.bkit/templates.md` § slop-scan.",
|
|
141
146
|
fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
|
|
142
147
|
},
|
|
148
|
+
{
|
|
149
|
+
id: "test-lint",
|
|
150
|
+
workflows: ["build"],
|
|
151
|
+
title: "Catch tests that can't fail",
|
|
152
|
+
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.",
|
|
153
|
+
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.",
|
|
154
|
+
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.",
|
|
155
|
+
steps: "`.bkit/templates.md` § Oxlint.",
|
|
156
|
+
fires: (cwd) => hasJsTestRunner(cwd) && !hasTestLinter(cwd),
|
|
157
|
+
},
|
|
143
158
|
{
|
|
144
159
|
id: "vale",
|
|
145
160
|
workflows: ["design", "plan"],
|
|
@@ -170,7 +185,7 @@ export const SETUP_TIPS = [
|
|
|
170
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`, then tell me which dashboard settings are left.",
|
|
171
186
|
steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
|
|
172
187
|
fires: (cwd) => {
|
|
173
|
-
const cloud =
|
|
188
|
+
const cloud = readBkitConfig(cwd).cloudAgents;
|
|
174
189
|
if (cloud === "none")
|
|
175
190
|
return false;
|
|
176
191
|
if (cloud === "cursor") {
|
|
@@ -239,9 +254,19 @@ export const SETUP_TIPS = [
|
|
|
239
254
|
fires: (cwd) => hosts(cwd).has("claude") && !claudeSettingsHas(cwd, "disableClaudeAiConnectors"),
|
|
240
255
|
},
|
|
241
256
|
// --- optional: nice to have ------------------------------------------------------------
|
|
257
|
+
{
|
|
258
|
+
id: "issue-forms",
|
|
259
|
+
workflows: ["design", "plan", "debug"],
|
|
260
|
+
title: "Issue forms",
|
|
261
|
+
line: "Optional: add issue forms so every new issue asks for what the agent reads first.",
|
|
262
|
+
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.",
|
|
263
|
+
ask: "Copy .bkit/templates/.github/ISSUE_TEMPLATE/ to .github/ISSUE_TEMPLATE/ and commit it to the default branch.",
|
|
264
|
+
steps: "`.bkit/templates.md` § Issue forms.",
|
|
265
|
+
fires: (cwd) => readBkitConfig(cwd).issueTracker === "github" && !exists(cwd, ".github/ISSUE_TEMPLATE"),
|
|
266
|
+
},
|
|
242
267
|
{
|
|
243
268
|
id: "graphify",
|
|
244
|
-
workflows: ["design", "plan"],
|
|
269
|
+
workflows: ["design", "plan", "audit"],
|
|
245
270
|
title: "A map of the code",
|
|
246
271
|
line: "Optional: add graphify to keep an up-to-date map of how your code fits together.",
|
|
247
272
|
why: "With a map, agents check what already exists before building it again. Without one, agents and reviews work out the structure from scratch each time. That's slower, and it's easy to miss how one change ripples into another part of the code.",
|
|
@@ -251,7 +276,7 @@ export const SETUP_TIPS = [
|
|
|
251
276
|
},
|
|
252
277
|
{
|
|
253
278
|
id: "dependabot-renovate",
|
|
254
|
-
workflows: ["ship"],
|
|
279
|
+
workflows: ["ship", "audit"],
|
|
255
280
|
title: "Automatic updates",
|
|
256
281
|
line: "Nothing keeps the project's libraries up to date. Add an updater so you get small, safe updates instead of one big risky one later.",
|
|
257
282
|
why: "An updater opens a small pull request whenever a library you use has a new version. Skip it and updates pile up into one large upgrade that's far more likely to break something.",
|
|
@@ -260,6 +285,16 @@ export const SETUP_TIPS = [
|
|
|
260
285
|
advisories: ["dep-updater-absent"],
|
|
261
286
|
fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
|
|
262
287
|
},
|
|
288
|
+
{
|
|
289
|
+
id: "trivy",
|
|
290
|
+
workflows: ["ship", "audit"],
|
|
291
|
+
title: "Security scan",
|
|
292
|
+
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.",
|
|
293
|
+
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.",
|
|
294
|
+
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.",
|
|
295
|
+
steps: "`.bkit/templates.md` § Trivy. Accept a finding in `.trivyignore.yaml` with `statement` + `expired_at`; never drop `--include-dev-deps`.",
|
|
296
|
+
fires: (cwd) => exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
|
|
297
|
+
},
|
|
263
298
|
{
|
|
264
299
|
id: "prettier-tables",
|
|
265
300
|
workflows: ["design", "plan"],
|
|
@@ -279,6 +314,18 @@ export const SETUP_TIPS = [
|
|
|
279
314
|
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
280
315
|
fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
281
316
|
},
|
|
317
|
+
{
|
|
318
|
+
id: "disk-prune",
|
|
319
|
+
workflows: ALL_WORKFLOWS,
|
|
320
|
+
title: "Keep enough disk free for new worktrees",
|
|
321
|
+
line: "Build caches, Docker images and simulators fill the disk until a workflow cannot make its worktree. Add your own clean-up steps, run after commits and pushes.",
|
|
322
|
+
why: "bkit deletes nothing on its own: you choose the steps, starting from examples that only delete what comes back by itself. Commits run the cheap steps, pushes run the rest, and a workflow runs them before making a worktree on a nearly full disk.",
|
|
323
|
+
ask: "Copy .bkit/templates/scripts/cleanup/bkit-disk-prune.mjs to scripts/cleanup/ and/or .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs to ~/.config/bkit/disk-prune.mjs, edit the steps, then paste the `disk prune` block from the end of each .bkit/templates/.husky hook at the end of yours.",
|
|
324
|
+
steps: "`.bkit/templates.md` § Disk prune.",
|
|
325
|
+
fires: (cwd) => exists(cwd, ".husky/pre-push") &&
|
|
326
|
+
!exists(cwd, REPO_STEPS) &&
|
|
327
|
+
!fs.existsSync(machineStepsPath()),
|
|
328
|
+
},
|
|
282
329
|
// --- setup: only some setups -----------------------------------------------------------
|
|
283
330
|
{
|
|
284
331
|
id: "cursor-files",
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
// checks/tips/detect.ts — local-only probes the setup-tip catalogue keys on: host MCP
|
|
2
|
-
// configs, host settings files, lint-staged config forms. No network.
|
|
2
|
+
// configs, host settings files, lint-staged and test-linter config forms. No network.
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
5
|
import { parseJson } from "../../shared/json.js";
|
|
6
|
-
import { readPackageJson } from "../../shared/package-json.js";
|
|
6
|
+
import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
|
|
7
7
|
/** True when `rel` exists under `cwd`. */
|
|
8
8
|
export const exists = (cwd, rel) => fs.existsSync(path.join(cwd, rel));
|
|
9
9
|
/** Parsed JSON object at `rel`, or `null` when absent, unparseable or not an object. */
|
|
@@ -121,6 +121,16 @@ const LINT_STAGED_CONFIGS = [
|
|
|
121
121
|
"lint-staged.config.cjs",
|
|
122
122
|
"lint-staged.config.js",
|
|
123
123
|
];
|
|
124
|
+
/** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
|
|
125
|
+
export function anyWorkflowMentions(cwd, needle) {
|
|
126
|
+
const dir = path.join(cwd, ".github", "workflows");
|
|
127
|
+
if (!fs.existsSync(dir))
|
|
128
|
+
return false;
|
|
129
|
+
return fs
|
|
130
|
+
.readdirSync(dir)
|
|
131
|
+
.filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"))
|
|
132
|
+
.some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
|
|
133
|
+
}
|
|
124
134
|
/** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
|
|
125
135
|
export function hasLintStagedConfig(cwd) {
|
|
126
136
|
if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel)))
|
|
@@ -128,3 +138,32 @@ export function hasLintStagedConfig(cwd) {
|
|
|
128
138
|
const pkg = readPackageJson(cwd);
|
|
129
139
|
return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
|
|
130
140
|
}
|
|
141
|
+
const OXLINT_CONFIGS = [
|
|
142
|
+
".oxlintrc.json",
|
|
143
|
+
...["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `oxlint.config.${ext}`),
|
|
144
|
+
];
|
|
145
|
+
const ESLINT_CONFIGS = [
|
|
146
|
+
".eslintrc",
|
|
147
|
+
...["json", "js", "cjs", "yaml", "yml"].map((ext) => `.eslintrc.${ext}`),
|
|
148
|
+
...["js", "mjs", "cjs", "ts", "mts", "cts"].map((ext) => `eslint.config.${ext}`),
|
|
149
|
+
];
|
|
150
|
+
/** A test-framework or test-library name inside an ESLint config means it lints tests. */
|
|
151
|
+
const TEST_LINT_PLUGIN = /vitest|jest|playwright|testing-library/i;
|
|
152
|
+
/** True when `package.json` lists a JS / TS test runner (Vitest or Jest) as a dependency. */
|
|
153
|
+
export const hasJsTestRunner = (cwd) => readDependencyNames(cwd).some((name) => name === "vitest" || name === "jest");
|
|
154
|
+
/**
|
|
155
|
+
* True when the repo already lints its test files: an Oxlint config or `oxlint` dependency,
|
|
156
|
+
* or an ESLint config (file or `package.json` `eslintConfig`) that names a test plugin.
|
|
157
|
+
*/
|
|
158
|
+
export function hasTestLinter(cwd) {
|
|
159
|
+
if (OXLINT_CONFIGS.some((rel) => exists(cwd, rel)))
|
|
160
|
+
return true;
|
|
161
|
+
if (readDependencyNames(cwd).includes("oxlint"))
|
|
162
|
+
return true;
|
|
163
|
+
const eslintConfigs = ESLINT_CONFIGS.map((rel) => readText(cwd, rel));
|
|
164
|
+
const pkg = readPackageJson(cwd);
|
|
165
|
+
if (pkg.ok && pkg.pkg["eslintConfig"] !== undefined) {
|
|
166
|
+
eslintConfigs.push(JSON.stringify(pkg.pkg["eslintConfig"]));
|
|
167
|
+
}
|
|
168
|
+
return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
|
|
169
|
+
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
|
|
2
2
|
// console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
|
|
3
3
|
import { ignoredAdvisoryIds, } from "../after/suppression.js";
|
|
4
|
-
import { SETUP_TIPS } from "./catalogue.js";
|
|
4
|
+
import { ALL_WORKFLOWS, SETUP_TIPS } from "./catalogue.js";
|
|
5
5
|
/** Tips `bkit tips` prints without `--all` or `--workflow`. */
|
|
6
6
|
export const TIPS_CAP = 3;
|
|
7
7
|
/** Tips a workflow prints at its close (`bkit tips --workflow=<name>`). */
|
|
@@ -12,6 +12,23 @@ export const SETUP_TIPS_HEADING = "Setup tips";
|
|
|
12
12
|
export const tipsIntro = (n) => n === 1 ? "Setup tip for a smoother next run:" : "Setup tips for a smoother next run:";
|
|
13
13
|
/** Where the full tip list lives. */
|
|
14
14
|
export const TIPS_DETAILS_POINTER = "Details for every tip: .bkit/advisories.md § Setup tips (refreshed by `bkit check`).";
|
|
15
|
+
/** Last line of a workflow's `## bkit Tips`: how to silence what it shows, by id. */
|
|
16
|
+
export function silenceLine(ids) {
|
|
17
|
+
const names = ids.map((id) => `\`${id}\``);
|
|
18
|
+
const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
|
|
19
|
+
const what = ids.length > 1 ? "these tips" : "this tip";
|
|
20
|
+
return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
|
|
21
|
+
}
|
|
22
|
+
/** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
|
|
23
|
+
export const STAR_TIP_ID = "bkit-star";
|
|
24
|
+
/** Older key that also silences `STAR_TIP`, so repos that set it keep the line off. */
|
|
25
|
+
export const STAR_TIP_OLD_ID = "star";
|
|
26
|
+
/**
|
|
27
|
+
* Last line of `bkit tips` output while not silenced, in bare `bkit tips` and the phase
|
|
28
|
+
* workflows only — audits and the ledger / roadmap updaters often run back to back. Not a
|
|
29
|
+
* gap, so never in the checklist.
|
|
30
|
+
*/
|
|
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)!";
|
|
15
32
|
/** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
|
|
16
33
|
export const TIPS_SECTION_INTRO = "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
|
|
17
34
|
/** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
|
|
@@ -38,7 +55,8 @@ export function collectTips(cwd, catalogue = SETUP_TIPS) {
|
|
|
38
55
|
else
|
|
39
56
|
tips.push(tip);
|
|
40
57
|
}
|
|
41
|
-
|
|
58
|
+
const star = !ignored.has(STAR_TIP_ID) && !ignored.has(STAR_TIP_OLD_ID);
|
|
59
|
+
return { tips, suppressed, star };
|
|
42
60
|
}
|
|
43
61
|
/**
|
|
44
62
|
* Drop advisory findings whose tip the root package.json silenced, so one
|
|
@@ -66,12 +84,10 @@ function tipTextLines(tip, n) {
|
|
|
66
84
|
lines.push(` Caution: ${tip.caution}`);
|
|
67
85
|
return lines;
|
|
68
86
|
}
|
|
69
|
-
/** One tip as markdown
|
|
70
|
-
function
|
|
71
|
-
const
|
|
72
|
-
|
|
73
|
-
lines.push("", `Caution: ${tip.caution}`);
|
|
74
|
-
return lines;
|
|
87
|
+
/** One tip as one markdown paragraph for a workflow's `## bkit Tips` section. */
|
|
88
|
+
function tipParagraph(tip) {
|
|
89
|
+
const caution = tip.caution ? ` Caution: ${tip.caution}` : "";
|
|
90
|
+
return `**${tip.title}.** ${tip.line} Ask your agent: "${tip.ask}"${caution}`;
|
|
75
91
|
}
|
|
76
92
|
/**
|
|
77
93
|
* `tips` with the ones that matter in `workflow` first, each group in catalogue order.
|
|
@@ -81,33 +97,53 @@ export function orderForWorkflow(tips, workflow) {
|
|
|
81
97
|
const own = tips.filter((t) => t.workflows?.includes(workflow));
|
|
82
98
|
return [...own, ...tips.filter((t) => !own.includes(t))];
|
|
83
99
|
}
|
|
100
|
+
/** True when `STAR_TIP` closes the output in `workflow`: bare `bkit tips` or a phase workflow. */
|
|
101
|
+
export function starShownIn(workflow) {
|
|
102
|
+
return !workflow || ALL_WORKFLOWS.includes(workflow);
|
|
103
|
+
}
|
|
84
104
|
/**
|
|
85
|
-
* `bkit tips` output
|
|
86
|
-
* - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow
|
|
87
|
-
* markdown
|
|
88
|
-
* own `##
|
|
89
|
-
* - neither: the top `TIPS_CAP` tips as a numbered terminal list
|
|
105
|
+
* `bkit tips` output. `""` when no tip fires and no star line shows.
|
|
106
|
+
* - `workflow`: the `WORKFLOW_TIPS_CAP` tips that matter most in that workflow as
|
|
107
|
+
* one markdown paragraph each, then `STAR_TIP` when shown, then `silenceLine` naming both — the
|
|
108
|
+
* workflow appends them under its own `## bkit Tips` heading.
|
|
109
|
+
* - neither: the top `TIPS_CAP` tips as a numbered terminal list, where the rest live,
|
|
110
|
+
* then `STAR_TIP` when shown.
|
|
90
111
|
* - `all`: every tip as a numbered list (in the workflow's order when `workflow` is set).
|
|
112
|
+
* `STAR_TIP` shows when `opts.star` is set and `starShownIn(workflow)`.
|
|
91
113
|
*/
|
|
92
114
|
export function formatTips(tips, opts = {}) {
|
|
115
|
+
const star = !!opts.star && starShownIn(opts.workflow);
|
|
116
|
+
if (opts.workflow && !opts.all)
|
|
117
|
+
return formatWorkflowTips(tips, opts.workflow, star);
|
|
118
|
+
const body = formatSetupTips(tips, opts);
|
|
119
|
+
if (!star)
|
|
120
|
+
return body;
|
|
121
|
+
return body ? `${body}\n\n${STAR_TIP}` : STAR_TIP;
|
|
122
|
+
}
|
|
123
|
+
/** `formatTips` for a workflow's `## bkit Tips`: tips, star line, how to silence both. */
|
|
124
|
+
function formatWorkflowTips(tips, workflow, star) {
|
|
125
|
+
const shown = orderForWorkflow(tips, workflow).slice(0, WORKFLOW_TIPS_CAP);
|
|
126
|
+
const ids = shown.map((t) => t.id);
|
|
127
|
+
const parts = shown.map(tipParagraph);
|
|
128
|
+
if (star) {
|
|
129
|
+
parts.push(STAR_TIP);
|
|
130
|
+
ids.push(STAR_TIP_ID);
|
|
131
|
+
}
|
|
132
|
+
if (ids.length === 0)
|
|
133
|
+
return "";
|
|
134
|
+
return [...parts, silenceLine(ids)].join("\n\n");
|
|
135
|
+
}
|
|
136
|
+
/** `formatTips` as a terminal list, without `STAR_TIP`. */
|
|
137
|
+
function formatSetupTips(tips, opts) {
|
|
93
138
|
if (tips.length === 0)
|
|
94
139
|
return "";
|
|
95
140
|
const ordered = opts.workflow ? orderForWorkflow(tips, opts.workflow) : [...tips];
|
|
96
|
-
const
|
|
97
|
-
const shown = opts.all ? ordered : ordered.slice(0, cap);
|
|
141
|
+
const shown = opts.all ? ordered : ordered.slice(0, TIPS_CAP);
|
|
98
142
|
const rest = tips.length - shown.length;
|
|
99
|
-
const more = rest > 0 ? `${rest} more: \`bkit tips --all\`. ` : "";
|
|
100
|
-
if (opts.workflow && !opts.all) {
|
|
101
|
-
const lines = [];
|
|
102
|
-
for (const tip of shown)
|
|
103
|
-
lines.push(...tipMarkdownLines(tip), "");
|
|
104
|
-
lines.push(`${more}${TIPS_DETAILS_POINTER}`);
|
|
105
|
-
return lines.join("\n");
|
|
106
|
-
}
|
|
107
143
|
const lines = [tipsIntro(shown.length), ""];
|
|
108
144
|
shown.forEach((tip, i) => lines.push(...tipTextLines(tip, i + 1), ""));
|
|
109
|
-
if (
|
|
110
|
-
lines.push(more
|
|
145
|
+
if (rest > 0)
|
|
146
|
+
lines.push(`${rest} more: \`bkit tips --all\`.`);
|
|
111
147
|
lines.push(TIPS_DETAILS_POINTER);
|
|
112
148
|
return lines.join("\n");
|
|
113
149
|
}
|
package/dist/cli.js
CHANGED
|
@@ -69,6 +69,17 @@ export function parseComplyPhase(value) {
|
|
|
69
69
|
? value
|
|
70
70
|
: null;
|
|
71
71
|
}
|
|
72
|
+
/**
|
|
73
|
+
* Where `bkit tips --workflow=<name>` runs: a phase workflow, `audit` (`@bkit-audit-generate`)
|
|
74
|
+
* or `utility` (the ledger and roadmap updaters).
|
|
75
|
+
*/
|
|
76
|
+
export const TIPS_CONTEXTS = [...COMPLY_PHASES, "audit", "utility"];
|
|
77
|
+
/** Narrow an unknown string to `TipsContext` or return null if invalid. */
|
|
78
|
+
export function parseTipsContext(value) {
|
|
79
|
+
return typeof value === "string" && TIPS_CONTEXTS.includes(value)
|
|
80
|
+
? value
|
|
81
|
+
: null;
|
|
82
|
+
}
|
|
72
83
|
// Bare module-flag tokens accepted on the CLI. `opencode` (value-bearing) is
|
|
73
84
|
// intercepted by a dedicated branch in parseArgs before this set is consulted; the
|
|
74
85
|
// generic check only ever validates claude/cursor/codex. `full`, `core` and `cloud`
|
|
@@ -318,9 +329,9 @@ export function parseArgs(argv) {
|
|
|
318
329
|
}
|
|
319
330
|
if (flag.startsWith("workflow=") && verb === "tips") {
|
|
320
331
|
const value = flag.slice("workflow=".length);
|
|
321
|
-
tipsWorkflow =
|
|
332
|
+
tipsWorkflow = parseTipsContext(value);
|
|
322
333
|
if (tipsWorkflow === null) {
|
|
323
|
-
console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${
|
|
334
|
+
console.error(`[bkit] Unknown workflow: "${value}". Valid values: ${TIPS_CONTEXTS.join(", ")}`);
|
|
324
335
|
process.exit(1);
|
|
325
336
|
}
|
|
326
337
|
continue;
|
|
@@ -427,11 +438,15 @@ Usage:
|
|
|
427
438
|
re-rendering. Copies under .bkit/templates/ are refreshed by
|
|
428
439
|
install/upgrade and checked for staleness — adopt one by
|
|
429
440
|
copying it elsewhere; that copy is yours. The CI gate.
|
|
441
|
+
Changes no managed file; rewrites .bkit/advisories.md.
|
|
430
442
|
bkit upgrade [--to=<version>|--latest] [--auto-apply] [--dry-run]
|
|
431
443
|
Upgrade everything installed (no module flags). Diffs old
|
|
432
444
|
vs new templates; conflict list emitted to stderr. Use
|
|
433
445
|
--auto-apply for CI (apply non-conflicting; exit non-zero
|
|
434
|
-
on any conflict).
|
|
446
|
+
on any conflict). Only a whole file you edited since bkit
|
|
447
|
+
wrote it conflicts; rendered files (agents, commands,
|
|
448
|
+
skills, .bkit/*.md) are always re-rendered — bkit check
|
|
449
|
+
flags an edit to one.
|
|
435
450
|
--to=<version> / --latest atomically BUMP @cbartens/bkit
|
|
436
451
|
(pnpm add), then re-render + re-pin in one step — so a
|
|
437
452
|
version bump can never drift from its rendered mirrors.
|
|
@@ -446,17 +461,22 @@ Usage:
|
|
|
446
461
|
--nuke to force-remove manifest-listed files). Target with the
|
|
447
462
|
same module flags as install (e.g. uninstall --claude); a
|
|
448
463
|
targeted uninstall leaves core untouched.
|
|
449
|
-
bkit doctor
|
|
450
|
-
|
|
464
|
+
bkit doctor Preflight + post-install advisory replay (changes no
|
|
465
|
+
managed file; rewrites .bkit/advisories.md). Diagnose
|
|
466
|
+
token surfaces and config drift. Exits 0.
|
|
451
467
|
bkit tips [--workflow=<name>] [--all]
|
|
452
468
|
Setup tips: what this repo has not set up yet, most useful
|
|
453
469
|
first, each with a sentence to ask your agent. Top three
|
|
454
470
|
by default; --workflow=design|plan|build|debug|ship puts
|
|
455
471
|
the tips that matter there first and prints one (each
|
|
456
|
-
workflow runs this at its close
|
|
457
|
-
|
|
472
|
+
workflow runs this at its close; audit and utility do the
|
|
473
|
+
same for audits and the ledger / roadmap updaters);
|
|
474
|
+
--all lists every one. Ends with a star line ("bkit-star"
|
|
475
|
+
in bkit.ignoreAdvisories silences it), except under
|
|
476
|
+
--workflow=audit|utility. Local checks only. Exits 0.
|
|
458
477
|
bkit status Read-only host/provider status. Reports current host+provider
|
|
459
|
-
(sampled from .
|
|
478
|
+
(sampled from .claude/, .cursor/, package.json, and the
|
|
479
|
+
opencode agent model pins in .opencode/agents/).
|
|
460
480
|
Writes nothing. Exits 0.
|
|
461
481
|
bkit cursor Launch Cursor with .bkit/.env loaded into its environment.
|
|
462
482
|
macOS GUI apps launched from the Dock/Finder do not inherit
|
|
@@ -476,12 +496,13 @@ Usage:
|
|
|
476
496
|
bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
|
|
477
497
|
and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
|
|
478
498
|
for docs/deferrals.jsonl and docs/failures.jsonl).
|
|
479
|
-
Reads consumer paths from
|
|
499
|
+
Reads consumer paths from harvest/consumers.md.
|
|
480
500
|
DESTRUCTIVE: harvested friction rows are REMOVED from
|
|
481
501
|
the consumer, but only after they are fsync'd and read
|
|
482
502
|
back from harvest/. stats.jsonl is never modified.
|
|
483
|
-
harvest/ accumulates and is never cleared
|
|
484
|
-
|
|
503
|
+
harvest/ accumulates and is never cleared; it is
|
|
504
|
+
gitignored, so it is the only record of pruned rows —
|
|
505
|
+
back it up. Never commits
|
|
485
506
|
in any repo. Deduplicates by per-kind composite
|
|
486
507
|
identity. Advisory + fail-open: exits 0.
|
|
487
508
|
bkit telemetry summary [--phase=<workflow>]
|
|
@@ -494,7 +515,7 @@ Usage:
|
|
|
494
515
|
(design|plan|build|debug|ship). Without it, prints the
|
|
495
516
|
ledger-health line only. Read-only: exits 0.
|
|
496
517
|
bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
|
|
497
|
-
|
|
518
|
+
change-size vs outcome regression, dispatch-size threshold,
|
|
498
519
|
counterSource trust labelling, per-rule compliance
|
|
499
520
|
rate over kind:"compliance" rows, and the
|
|
500
521
|
unjustified-deferral rate per (subagent, model)
|
|
@@ -505,7 +526,7 @@ Usage:
|
|
|
505
526
|
|
|
506
527
|
Core (implicit — no flag; installed/upgraded on every install):
|
|
507
528
|
AGENTS.md (cross-host dispatch router), .agents/rules.md + .agents/context.md +
|
|
508
|
-
.agents/docs.md + .agents/
|
|
529
|
+
.agents/docs.md + .agents/skills.md managed blocks, .gitignore +
|
|
509
530
|
.gitattributes managed blocks, docs/, .bkit/*.md, .bkit/version, the template copies in
|
|
510
531
|
.bkit/templates/, and the bkit:gate:* / bkit:deps:* package.json scripts every workflow
|
|
511
532
|
runs (added when missing, never overwritten, left by uninstall). The tool scripts those
|
|
@@ -557,8 +578,10 @@ Dependency updaters (copy an example and own it):
|
|
|
557
578
|
Cross-cutting / modifiers:
|
|
558
579
|
--tracker=<name> Wire issue tracker integration. Values: github, linear, none
|
|
559
580
|
(default). Records bkit.issueTracker in package.json and substitutes
|
|
560
|
-
tracker snippets into command mirrors.
|
|
561
|
-
|
|
581
|
+
tracker snippets into command mirrors. Re-renders every installed
|
|
582
|
+
host, and works alone (bkit install --tracker=github). Switching is
|
|
583
|
+
free; a switch removes the old linear MCP entry unless you edited it
|
|
584
|
+
(github always stays). Does NOT own AGENTS.md (tracker-agnostic).
|
|
562
585
|
|
|
563
586
|
Install flags:
|
|
564
587
|
--auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
|
|
@@ -573,8 +596,9 @@ Uninstall flags:
|
|
|
573
596
|
--opencode=<provider>
|
|
574
597
|
Surgical provider removal: removes that provider's block from
|
|
575
598
|
opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
|
|
576
|
-
agents/commands/gateguard. If the removed provider was active,
|
|
577
|
-
|
|
599
|
+
agents/commands/gateguard. If the removed provider was active, the first
|
|
600
|
+
remaining provider becomes active and the agents are re-rendered to its
|
|
601
|
+
model pins.
|
|
578
602
|
Bare --opencode (no value) tears down the entire opencode host.
|
|
579
603
|
--force Delete owned whole-file files even if consumer modified them.
|
|
580
604
|
--nuke Delete ALL bkit-managed files regardless of tier/hash (requires confirm).
|
|
@@ -624,17 +648,18 @@ function commandsUsage() {
|
|
|
624
648
|
}
|
|
625
649
|
/**
|
|
626
650
|
* Validate the verb/module-flag combination before any dispatch
|
|
627
|
-
* work runs. `install` requires >=1 module flag (
|
|
628
|
-
* `check` / `upgrade` take NO module
|
|
629
|
-
* operate on everything already installed, so a stray flag is a hard
|
|
630
|
-
* pointing at the no-flag form. Returns the error message to print, or `null`
|
|
651
|
+
* work runs. `install` requires >=1 module flag or `--tracker=` (which re-renders
|
|
652
|
+
* every installed host); a bare install errors. `check` / `upgrade` take NO module
|
|
653
|
+
* flags — they operate on everything already installed, so a stray flag is a hard
|
|
654
|
+
* error pointing at the no-flag form. Returns the error message to print, or `null`
|
|
631
655
|
* when the combination is valid.
|
|
632
656
|
*/
|
|
633
|
-
export function validateModuleFlagsForVerb(verb, moduleFlags) {
|
|
634
|
-
if (verb === "install" && moduleFlags.size === 0) {
|
|
657
|
+
export function validateModuleFlagsForVerb(verb, moduleFlags, tracker = null) {
|
|
658
|
+
if (verb === "install" && moduleFlags.size === 0 && tracker === null) {
|
|
635
659
|
return ("[bkit] `bkit install` requires at least one module flag. Name what to install: " +
|
|
636
660
|
"--claude, --cursor, --codex, --antigravity, --opencode=<provider> (plus opt-in " +
|
|
637
|
-
`--auto=<${CLOUD_VARIANTS.join("|")}>)
|
|
661
|
+
`--auto=<${CLOUD_VARIANTS.join("|")}>), or --tracker=<name> alone to switch the ` +
|
|
662
|
+
"tracker on what is installed. Run `bkit help` for usage.");
|
|
638
663
|
}
|
|
639
664
|
if ((verb === "check" || verb === "upgrade") && moduleFlags.size > 0) {
|
|
640
665
|
return (`[bkit] \`bkit ${verb}\` takes no module flags — it operates on everything already ` +
|
|
@@ -694,8 +719,9 @@ export async function main() {
|
|
|
694
719
|
await launchApp(verb, process.cwd());
|
|
695
720
|
return;
|
|
696
721
|
}
|
|
697
|
-
// install requires >=1 module flag
|
|
698
|
-
|
|
722
|
+
// install requires >=1 module flag or --tracker=; check/upgrade take NONE
|
|
723
|
+
// (validateModuleFlagsForVerb).
|
|
724
|
+
const moduleFlagsError = validateModuleFlagsForVerb(verb, moduleFlags, tracker);
|
|
699
725
|
if (moduleFlagsError) {
|
|
700
726
|
console.error(moduleFlagsError);
|
|
701
727
|
process.exit(1);
|