@cbartens/bkit 6.1.0 → 6.2.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 +14 -12
- package/.bkit/core/.agents/docs.md +1 -11
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
- package/.bkit/core/.agents/rules.md +22 -9
- package/.bkit/core/.bkit/README.md +13 -11
- package/.bkit/core/.bkit/authoring.md +58 -13
- package/.bkit/core/.bkit/cli.md +43 -33
- package/.bkit/core/.bkit/cloud.md +93 -30
- package/.bkit/core/.bkit/install.md +55 -16
- package/.bkit/core/.bkit/jsonl.md +24 -7
- package/.bkit/core/.bkit/pipeline.md +8 -8
- package/.bkit/core/.bkit/prompts.md +160 -43
- package/.bkit/core/.bkit/providers.md +99 -36
- package/.bkit/core/.bkit/templates.md +167 -37
- package/.bkit/core/.bkit/trackers.md +39 -6
- package/.bkit/core/.bkit/workflows.md +344 -136
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
- package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
- 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 +2 -2
- package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
- package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
- 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 +1 -1
- package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
- package/.bkit/core/docs/templates/bkit-plan.md +38 -8
- package/.bkit/core/engine/checks/after/auth.ts +118 -47
- package/.bkit/core/engine/checks/after/github.ts +161 -37
- package/.bkit/core/engine/checks/after/index.ts +18 -3
- package/.bkit/core/engine/checks/after/tools.ts +245 -1
- package/.bkit/core/engine/checks/before/files.ts +59 -1
- package/.bkit/core/engine/checks/before/index.ts +8 -0
- package/.bkit/core/engine/checks/status-holes.ts +20 -26
- package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
- package/.bkit/core/engine/checks/tips/detect.ts +36 -3
- package/.bkit/core/engine/checks/tips/index.ts +1 -1
- package/.bkit/core/engine/cli.ts +13 -13
- package/.bkit/core/engine/commands/ci/ci.ts +124 -19
- package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
- package/.bkit/core/engine/commands/install/doctor.ts +5 -5
- package/.bkit/core/engine/commands/install/install.ts +28 -25
- package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
- package/.bkit/core/engine/commands/land.ts +2 -3
- package/.bkit/core/engine/commands/lib.ts +394 -39
- package/.bkit/core/engine/commands/registry.ts +1 -1
- package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
- package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
- package/.bkit/core/engine/commands/workflow/context.ts +71 -10
- package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
- package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
- package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
- package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
- package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
- package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
- package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
- package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
- package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
- package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
- package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
- package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
- package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
- package/.bkit/core/engine/commands/workflow/status.ts +324 -11
- package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
- package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
- package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
- package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
- package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
- package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
- package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
- package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
- package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
- package/.bkit/core/engine/install/cloud-env.ts +38 -10
- package/.bkit/core/engine/install/managed-block.ts +105 -0
- package/.bkit/core/engine/install/manifest.ts +7 -1
- package/.bkit/core/engine/install/modules/claude.ts +6 -2
- package/.bkit/core/engine/install/modules/cloud.ts +84 -95
- package/.bkit/core/engine/install/modules/codex.ts +10 -2
- package/.bkit/core/engine/install/modules/core.ts +202 -26
- package/.bkit/core/engine/install/modules/opencode.ts +18 -23
- package/.bkit/core/engine/install/network-allowlist.ts +8 -3
- package/.bkit/core/engine/install/project-docs.ts +650 -0
- package/.bkit/core/engine/install/template-copies.ts +58 -5
- package/.bkit/core/engine/install/write.ts +128 -7
- package/.bkit/core/engine/ledgers/journal.ts +18 -10
- package/.bkit/core/engine/ledgers/migrate.ts +20 -8
- package/.bkit/core/engine/ledgers/status.ts +604 -8
- package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
- package/.bkit/core/engine/render/trackers.ts +46 -11
- package/.bkit/core/engine/shared/package-manager.ts +7 -3
- package/.bkit/core/engine/shared/settings.ts +12 -1
- package/.bkit/core/engine/shared/text.ts +14 -0
- package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
- package/.bkit/core/engine/tools/instructions.ts +116 -20
- package/.bkit/core/hooks/antigravity-hook.js +20 -4
- package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
- package/.bkit/core/hooks/gateguard-engine.js +249 -23
- package/.bkit/core/hooks/guardrails-deny.js +167 -0
- package/.bkit/core/hooks/guardrails-read.js +3 -3
- package/.bkit/core/hooks/guardrails-shell.js +1122 -167
- package/.bkit/core/hooks/guardrails-tiers.js +247 -176
- package/.bkit/core/hooks/preflight-tracker.sh +219 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
- package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
- package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
- package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
- package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
- package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
- package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
- package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
- package/.bkit/core/prompts/bkit-design-generate.md +6 -4
- package/.bkit/core/prompts/bkit-design-organise.md +4 -3
- package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
- package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
- package/.bkit/core/prompts/bkit-design-spike.md +4 -3
- package/.bkit/core/prompts/bkit-design-update.md +6 -4
- package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
- package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
- package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
- package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
- package/.bkit/core/prompts/bkit-plan-update.md +22 -8
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
- package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
- package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
- package/.bkit/core/workflows/bkit-auto.md +23 -11
- package/.bkit/core/workflows/bkit-build.md +331 -100
- package/.bkit/core/workflows/bkit-debug.md +135 -64
- package/.bkit/core/workflows/bkit-design.md +58 -32
- package/.bkit/core/workflows/bkit-plan.md +73 -45
- package/.bkit/core/workflows/bkit-ship.md +233 -167
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
- package/.bkit/shared/.bkit/.env.example +5 -0
- package/.bkit/shared/.claude/bkit-cloud.md +7 -7
- package/.bkit/shared/.claude/settings.json +5 -1
- package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
- package/.bkit/shared/.cursor/hooks.json +1 -1
- package/.bkit/shared/.opencode/opencode.json +11 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
- package/.bkit/templates/.cursor/Dockerfile +7 -7
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
- package/.bkit/templates/.github/dependabot.yml +5 -0
- package/.bkit/templates/.github/renovate.json5 +5 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
- package/.bkit/templates/.husky/pre-push +123 -6
- package/.bkit/templates/context/bkit-serena.md +1 -1
- package/.bkit/templates/context/bkit-vercel.md +103 -59
- package/.bkit/templates/docs/architecture.md +98 -0
- package/.bkit/templates/docs/capabilities.md +33 -37
- package/.bkit/templates/docs/components.md +142 -0
- package/.bkit/templates/docs/data-schema.md +87 -0
- package/.bkit/{shared → templates}/docs/deployments.md +128 -142
- package/.bkit/templates/docs/design.md +117 -0
- package/.bkit/templates/docs/noise.md +54 -0
- package/.bkit/templates/docs/observability.md +99 -0
- package/.bkit/templates/docs/security.md +137 -0
- package/.bkit/templates/docs/setup.md +93 -0
- package/.bkit/templates/docs/technology.md +70 -0
- package/.bkit/{shared → templates}/docs/testing.md +200 -87
- package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
- package/.bkit/templates/slop-scan.config.json +2 -0
- package/CHANGELOG.md +79 -0
- package/DETAILS.md +661 -0
- package/README.md +73 -604
- package/dist/checks/after/auth.js +114 -46
- package/dist/checks/after/github.js +138 -35
- package/dist/checks/after/index.js +16 -4
- package/dist/checks/after/tools.js +224 -1
- package/dist/checks/before/files.js +59 -1
- package/dist/checks/before/index.js +7 -1
- package/dist/checks/status-holes.js +20 -21
- package/dist/checks/tips/catalogue.js +99 -10
- package/dist/checks/tips/detect.js +35 -3
- package/dist/checks/tips/index.js +1 -1
- package/dist/cli.js +13 -13
- package/dist/commands/ci/ci.js +113 -20
- package/dist/commands/ci/push-gate.js +79 -44
- package/dist/commands/install/doctor.js +5 -5
- package/dist/commands/install/install.js +23 -22
- package/dist/commands/install/uninstall.js +36 -30
- package/dist/commands/install/upgrade.js +10 -2
- package/dist/commands/land.js +2 -3
- package/dist/commands/lib.js +323 -25
- package/dist/commands/workflow/branches.js +312 -72
- package/dist/commands/workflow/challenge.js +66 -13
- package/dist/commands/workflow/context.js +46 -10
- package/dist/commands/workflow/counters.js +231 -23
- package/dist/commands/workflow/decisions.js +221 -106
- package/dist/commands/workflow/disk.js +2 -1
- package/dist/commands/workflow/feature-base.js +60 -0
- package/dist/commands/workflow/issues.js +243 -15
- package/dist/commands/workflow/junit.js +137 -0
- package/dist/commands/workflow/ledgers.js +726 -112
- package/dist/commands/workflow/locks.js +150 -29
- package/dist/commands/workflow/loops.js +67 -0
- package/dist/commands/workflow/open-decision.js +199 -0
- package/dist/commands/workflow/plan-blocks.js +6 -0
- package/dist/commands/workflow/plans.js +1 -1
- package/dist/commands/workflow/prs.js +272 -16
- package/dist/commands/workflow/repo.js +1 -1
- package/dist/commands/workflow/run-facts.js +6 -0
- package/dist/commands/workflow/runs.js +747 -155
- package/dist/commands/workflow/runtime.js +8 -4
- package/dist/commands/workflow/status.js +259 -13
- package/dist/commands/workflow/step-table.js +41 -15
- package/dist/commands/workflow/steps.js +530 -26
- package/dist/commands/workflow/summary-findings.js +1 -1
- package/dist/commands/workflow/summary.js +289 -8
- package/dist/commands/workflow/tasks.js +294 -27
- package/dist/commands/workflow/tests-base.js +266 -0
- package/dist/commands/workflow/tests-changed.js +130 -56
- package/dist/commands/workflow/tests-jump.js +77 -0
- package/dist/commands/workflow/tests.js +608 -131
- package/dist/commands/workflow/tracker.js +920 -112
- package/dist/commands/workflow/workflows.js +80 -59
- package/dist/commands/workflow/worktrees.js +387 -58
- package/dist/install/cloud-env.js +32 -10
- package/dist/install/managed-block.js +101 -0
- package/dist/install/manifest.js +7 -1
- package/dist/install/modules/claude.js +6 -2
- package/dist/install/modules/cloud.js +73 -86
- package/dist/install/modules/codex.js +9 -2
- package/dist/install/modules/core.js +190 -27
- package/dist/install/modules/opencode.js +18 -23
- package/dist/install/network-allowlist.js +8 -3
- package/dist/install/project-docs.js +551 -0
- package/dist/install/template-copies.js +55 -5
- package/dist/install/write.js +117 -5
- package/dist/ledgers/journal.js +10 -8
- package/dist/ledgers/migrate.js +20 -9
- package/dist/ledgers/status.js +461 -8
- package/dist/ledgers/telemetry.js +71 -13
- package/dist/render/trackers.js +21 -12
- package/dist/shared/package-manager.js +7 -2
- package/dist/shared/settings.js +8 -0
- package/dist/shared/text.js +13 -0
- package/dist/tools/instructions-sources.js +1 -0
- package/dist/tools/instructions.js +97 -24
- package/package.json +23 -15
- package/.bkit/core/hooks/preflight-linear.sh +0 -73
- package/.bkit/shared/docs/architecture.md +0 -16
- package/.bkit/shared/docs/data-schema.md +0 -16
- package/.bkit/shared/docs/design.md +0 -38
- package/.bkit/shared/docs/noise.md +0 -20
- package/.bkit/shared/docs/observability.md +0 -22
- package/.bkit/shared/docs/security.md +0 -62
- package/.bkit/shared/docs/setup.md +0 -52
- package/.bkit/shared/docs/technology.md +0 -15
- /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
- /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
|
@@ -6,6 +6,7 @@ import * as fs from "node:fs";
|
|
|
6
6
|
import * as path from "node:path";
|
|
7
7
|
import { execFileSync } from "node:child_process";
|
|
8
8
|
import type { PreflightFinding } from "../before/index.js";
|
|
9
|
+
import { ISSUE_TRACKERS } from "../../install/manifest.js";
|
|
9
10
|
import { MCP_TOOLSETS_HEADER, parseToolsets } from "../../install/write.js";
|
|
10
11
|
import { parseJson, readJsonFile } from "../../shared/json.js";
|
|
11
12
|
import { readBkitConfig } from "../../shared/settings.js";
|
|
@@ -72,6 +73,7 @@ export function detectActionsWritePermissions(): TokenPresence {
|
|
|
72
73
|
* - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
|
|
73
74
|
* - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
|
|
74
75
|
* - `jira` → admin switch, BKIT_JIRA_API_KEY and `bkit.tracker.jira` in package.json.
|
|
76
|
+
* - unknown → blocker naming the value and the valid names (the tracker guard fails on it too).
|
|
75
77
|
* - `none` → prompt to run `bkit install --tracker=github`, `--tracker=linear` or `--tracker=jira`.
|
|
76
78
|
*
|
|
77
79
|
* Only fires when bkit workflows are installed (.claude/ or .cursor/ present).
|
|
@@ -81,7 +83,16 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
|
|
|
81
83
|
const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
|
|
82
84
|
if (!hasClaude && !hasCursor) return null;
|
|
83
85
|
|
|
84
|
-
const { issueTracker: tracker, issueTrackerExplicit } = readBkitConfig(cwd);
|
|
86
|
+
const { issueTracker: tracker, issueTrackerExplicit, issueTrackerUnknown } = readBkitConfig(cwd);
|
|
87
|
+
|
|
88
|
+
if (issueTrackerUnknown !== null) {
|
|
89
|
+
return {
|
|
90
|
+
id: "tracker-setup-unknown",
|
|
91
|
+
severity: "blocker",
|
|
92
|
+
detect: `\`bkit.tracker.default\` in package.json is "${issueTrackerUnknown}", which names no tracker bkit knows. bkit reads it as \`none\`, and the session-start tracker guard fails in every session it checks.`,
|
|
93
|
+
action: `Set \`bkit.tracker.default\` to one of: ${ISSUE_TRACKERS.join(", ")} (lowercase), or run \`bkit install --tracker=<name>\`.`,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
85
96
|
|
|
86
97
|
if (tracker === "github") {
|
|
87
98
|
return {
|
|
@@ -238,6 +249,78 @@ function ghAsEngine(args: string[]): string {
|
|
|
238
249
|
});
|
|
239
250
|
}
|
|
240
251
|
|
|
252
|
+
const TRIVY_PROTECTION_ACTION =
|
|
253
|
+
"Before landing a check rename, save the branch-protection and applicable ruleset settings. " +
|
|
254
|
+
"Coordinate `trivy` → `bkit-trivy` with the workflow change; verify the new check on the candidate commit before requiring it. " +
|
|
255
|
+
"Change only that context, preserving strict mode, app_id / integration_id bindings, bypass policies and unrelated checks. " +
|
|
256
|
+
"Never disable protection to unblock the rename. Re-read the settings and run `bkit doctor` afterwards. This advisory changes no remote settings.";
|
|
257
|
+
|
|
258
|
+
/** Inspect existing protected branches without changing their checks or rulesets. */
|
|
259
|
+
export function buildTrivyProtectionAdvisory(cwd: string): PreflightFinding | null {
|
|
260
|
+
if (!fs.existsSync(path.join(cwd, ".github", "workflows", "bkit-trivy.yml"))) return null;
|
|
261
|
+
const stale: string[] = [];
|
|
262
|
+
let incomplete = false;
|
|
263
|
+
try {
|
|
264
|
+
const response = parseJson(
|
|
265
|
+
ghAsEngine(["api", "repos/{owner}/{repo}/branches?protected=true&per_page=11"]),
|
|
266
|
+
);
|
|
267
|
+
if (!response.ok || !Array.isArray(response.value)) throw new Error("Branch list unavailable");
|
|
268
|
+
const branches: {
|
|
269
|
+
name?: string;
|
|
270
|
+
protection?: { required_status_checks?: { contexts?: string[] } };
|
|
271
|
+
}[] = response.value;
|
|
272
|
+
incomplete = branches.length > 10;
|
|
273
|
+
for (const branch of branches.slice(0, 10)) {
|
|
274
|
+
if (typeof branch.name !== "string") {
|
|
275
|
+
incomplete = true;
|
|
276
|
+
continue;
|
|
277
|
+
}
|
|
278
|
+
const contexts = branch.protection?.required_status_checks?.contexts ?? [];
|
|
279
|
+
if (contexts.includes("trivy")) stale.push(branch.name);
|
|
280
|
+
const rules = parseJson(
|
|
281
|
+
ghAsEngine([
|
|
282
|
+
"api",
|
|
283
|
+
`repos/{owner}/{repo}/rules/branches/${encodeURIComponent(branch.name)}?per_page=100`,
|
|
284
|
+
]),
|
|
285
|
+
);
|
|
286
|
+
if (!rules.ok || !Array.isArray(rules.value)) {
|
|
287
|
+
incomplete = true;
|
|
288
|
+
continue;
|
|
289
|
+
}
|
|
290
|
+
if (rules.value.length === 100) incomplete = true;
|
|
291
|
+
for (const rule of rules.value) {
|
|
292
|
+
if (
|
|
293
|
+
rule?.type === "required_status_checks" &&
|
|
294
|
+
Array.isArray(rule.parameters?.required_status_checks) &&
|
|
295
|
+
rule.parameters.required_status_checks.some(
|
|
296
|
+
(check: { context?: string }) => check.context === "trivy",
|
|
297
|
+
)
|
|
298
|
+
)
|
|
299
|
+
stale.push(branch.name);
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
} catch {
|
|
303
|
+
incomplete = true;
|
|
304
|
+
}
|
|
305
|
+
if (stale.length > 0)
|
|
306
|
+
return {
|
|
307
|
+
id: "trivy-required-check-rename",
|
|
308
|
+
severity: "advisory",
|
|
309
|
+
detect: `Protected branches still require \`trivy\`: ${[...new Set(stale)].join(", ")}. The template emits \`bkit-trivy\`.${incomplete ? " Other protection was not fully checked." : ""}`,
|
|
310
|
+
action: TRIVY_PROTECTION_ACTION,
|
|
311
|
+
};
|
|
312
|
+
if (incomplete)
|
|
313
|
+
return {
|
|
314
|
+
id: "trivy-required-check-unchecked",
|
|
315
|
+
severity: "advisory",
|
|
316
|
+
detect:
|
|
317
|
+
"Trivy required checks are unchecked: a GitHub read failed or exceeded the scan limit (10 protected branches, 100 rules per branch).",
|
|
318
|
+
action:
|
|
319
|
+
"Inspect all affected branches and rulesets in GitHub Settings. " + TRIVY_PROTECTION_ACTION,
|
|
320
|
+
};
|
|
321
|
+
return null;
|
|
322
|
+
}
|
|
323
|
+
|
|
241
324
|
/**
|
|
242
325
|
* Whether the engine's token can move cards on the configured board: "present",
|
|
243
326
|
* "missing", or "unknown" (gh unavailable or unauthenticated). A classic token lists its
|
|
@@ -304,60 +387,101 @@ export function buildGithubProjectTokenScopeAdvisory(cwd: string): PreflightFind
|
|
|
304
387
|
/**
|
|
305
388
|
* Emit a cloud-agents setup advisory (parity with the tracker / dep-updater
|
|
306
389
|
* advisories). Post-CI auto-routing (`bkit-cloud.yml`) is opt-in via
|
|
307
|
-
* `bkit install --auto
|
|
308
|
-
* consumers to make the choice post-install.
|
|
390
|
+
* `bkit install --auto=<claude|opencode|codex|cursor>`; it does NOT ship with a default
|
|
391
|
+
* install. This nudges consumers to make the choice post-install.
|
|
309
392
|
*
|
|
310
|
-
*
|
|
311
|
-
*
|
|
312
|
-
*
|
|
313
|
-
*
|
|
393
|
+
* Resolution order (file presence is authoritative, package.json field is the opt-out):
|
|
394
|
+
* - router present, claude without `id-token: write` → `cloud-claude-missing-id-token` (blocker)
|
|
395
|
+
* - router present, linear / jira, copy says it serves GitHub only → `cloud-router-tracker-stale`
|
|
396
|
+
* - router present, `cloud.agent` codex, no `openai/codex-action` → `cloud-router-codex-missing`
|
|
397
|
+
* - router present, `cloud.agent` absent → `cloud-router-agent-unset`
|
|
398
|
+
* - router present, `cloud.agent` none / cursor → `cloud-router` (router starts nothing)
|
|
399
|
+
* - router present otherwise → `cloud-router` (informational)
|
|
400
|
+
* - `bkit.cloud.agent === "none"` (explicit) → null (opt-out — stay quiet)
|
|
401
|
+
* - otherwise (undecided) → `cloud-router-none` (nudge)
|
|
314
402
|
*
|
|
315
|
-
*
|
|
316
|
-
* opt-out):
|
|
317
|
-
* - `.github/workflows/bkit-cloud.yml` present → `cloud-router` (informational; active)
|
|
318
|
-
* - `bkit.cloud.agent === "none"` → null (opt-out — stay quiet)
|
|
319
|
-
* - `bkit.tracker.default === "jira"` → null (Jira runs locally only)
|
|
320
|
-
* - otherwise (undecided) → `cloud-router-none` (nudge to choose)
|
|
321
|
-
*
|
|
322
|
-
* Only fires when there is a `.github/workflows/` dir (the router wakes on a CI
|
|
403
|
+
* Only nudges when there is a `.github/workflows/` dir (the router wakes on a CI
|
|
323
404
|
* completion event).
|
|
324
405
|
*/
|
|
325
406
|
export function buildCloudSetupAdvisory(cwd: string): PreflightFinding | null {
|
|
326
407
|
const routerPath = path.join(cwd, ".github", "workflows", "bkit-cloud.yml");
|
|
327
408
|
|
|
328
409
|
if (fs.existsSync(routerPath)) {
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
410
|
+
const { cloudAgents, cloudAgentsExplicit, issueTracker } = readBkitConfig(cwd);
|
|
411
|
+
const content = fs.readFileSync(routerPath, "utf-8");
|
|
412
|
+
const recopy =
|
|
413
|
+
"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 and the `{{NODE_VERSION}}` value).";
|
|
414
|
+
|
|
415
|
+
if (cloudAgents === "claude" && !content.includes("id-token: write")) {
|
|
416
|
+
return {
|
|
417
|
+
id: "cloud-claude-missing-id-token",
|
|
418
|
+
severity: "blocker",
|
|
419
|
+
detect:
|
|
420
|
+
"`bkit.cloud.agent` is `claude` but `.github/workflows/bkit-cloud.yml` lacks `id-token: write`. `claude-code-action@v1` will fail at boot with an OIDC error.",
|
|
421
|
+
action: `${recopy} Also verify the Claude GitHub App is installed (\`/install-github-app\`). See bkit's \`cloud.md\` § Post-CI auto-routing.`,
|
|
422
|
+
};
|
|
423
|
+
}
|
|
424
|
+
if (
|
|
425
|
+
(issueTracker === "linear" || issueTracker === "jira") &&
|
|
426
|
+
content.includes("serves the GitHub tracker only")
|
|
427
|
+
) {
|
|
428
|
+
return {
|
|
429
|
+
id: "cloud-router-tracker-stale",
|
|
430
|
+
severity: "advisory",
|
|
431
|
+
detect: `\`bkit.tracker.default\` is \`${issueTracker}\` but the adopted \`.github/workflows/bkit-cloud.yml\` serves the GitHub tracker only: it never dispatches an agent for ${issueTracker} issues.`,
|
|
432
|
+
action: recopy,
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
if (cloudAgents === "codex" && !content.includes("openai/codex-action")) {
|
|
436
|
+
return {
|
|
437
|
+
id: "cloud-router-codex-missing",
|
|
438
|
+
severity: "advisory",
|
|
439
|
+
detect:
|
|
440
|
+
"`bkit.cloud.agent` is `codex` but the adopted `.github/workflows/bkit-cloud.yml` has no `openai/codex-action` job, so no Codex run starts.",
|
|
441
|
+
action: recopy,
|
|
442
|
+
};
|
|
443
|
+
}
|
|
444
|
+
if (!cloudAgentsExplicit) {
|
|
445
|
+
return {
|
|
446
|
+
id: "cloud-router-agent-unset",
|
|
447
|
+
severity: "advisory",
|
|
448
|
+
detect:
|
|
449
|
+
"`.github/workflows/bkit-cloud.yml` is present but `bkit.cloud.agent` is not recorded, so the router cannot tell which agent job to start.",
|
|
450
|
+
action:
|
|
451
|
+
"Record the variant: `pnpm bkit install --auto=claude`, `--auto=opencode` or `--auto=codex` (the agent whose credential you set).",
|
|
452
|
+
};
|
|
344
453
|
}
|
|
345
454
|
|
|
455
|
+
if (cloudAgents === "none" || cloudAgents === "cursor") {
|
|
456
|
+
return {
|
|
457
|
+
id: "cloud-router",
|
|
458
|
+
severity: "advisory",
|
|
459
|
+
detect: `\`.github/workflows/bkit-cloud.yml\` is present but \`bkit.cloud.agent\` is \`${cloudAgents}\`: the router starts no agent job for \`${cloudAgents}\`, so CI results dispatch nothing.`,
|
|
460
|
+
action:
|
|
461
|
+
"Record the agent whose credential you set: `pnpm bkit install --auto=claude`, `--auto=opencode` or `--auto=codex`.",
|
|
462
|
+
};
|
|
463
|
+
}
|
|
464
|
+
|
|
465
|
+
const claude = cloudAgents === "claude";
|
|
466
|
+
const secret =
|
|
467
|
+
cloudAgents === "codex"
|
|
468
|
+
? "`BKIT_OPENAI_API_KEY` repo secret"
|
|
469
|
+
: cloudAgents === "opencode"
|
|
470
|
+
? "opencode provider's `BKIT_` repo secret"
|
|
471
|
+
: "`BKIT_ANTHROPIC_API_KEY` repo secret OR the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (keyless workload identity federation)";
|
|
346
472
|
return {
|
|
347
473
|
id: "cloud-router",
|
|
348
474
|
severity: "advisory",
|
|
349
|
-
detect:
|
|
350
|
-
|
|
351
|
-
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".`,
|
|
475
|
+
detect: `Cloud agents: post-CI auto-routing is configured for \`${cloudAgents}\` (\`.github/workflows/bkit-cloud.yml\` present).${claude ? " The Claude GitHub App is required — run `/install-github-app` (Claude Code CLI) once if not already done." : ""}`,
|
|
476
|
+
action: `The workflow requires: the ${secret}${claude ? ", 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=${cloudAgents}\`) 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".`,
|
|
352
477
|
};
|
|
353
478
|
}
|
|
354
479
|
|
|
355
480
|
// No router present — distinguish opt-out from undecided.
|
|
356
|
-
const { cloudAgents, cloudAgentsExplicit
|
|
481
|
+
const { cloudAgents, cloudAgentsExplicit } = readBkitConfig(cwd);
|
|
357
482
|
if (cloudAgents === "none" && cloudAgentsExplicit) {
|
|
358
483
|
return null; // consumer explicitly chose `none` — stay quiet
|
|
359
484
|
}
|
|
360
|
-
if (issueTracker === "jira") return null; // no cloud setup exists for a Jira tracker
|
|
361
485
|
|
|
362
486
|
// Only nudge if there's a workflows dir for the router to wake on.
|
|
363
487
|
if (!fs.existsSync(path.join(cwd, ".github", "workflows"))) return null;
|
|
@@ -368,8 +492,8 @@ export function buildCloudSetupAdvisory(cwd: string): PreflightFinding | null {
|
|
|
368
492
|
detect:
|
|
369
493
|
"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.",
|
|
370
494
|
action:
|
|
371
|
-
"Optional post-install decision
|
|
372
|
-
"Prerequisites
|
|
495
|
+
"Optional post-install decision: `pnpm bkit install --auto=<claude|opencode|codex|cursor>` (any variant works with your wired tracker; `codex` also needs `--codex`).\n\n" +
|
|
496
|
+
"Prerequisites: the variant's `BKIT_` repo secret (`BKIT_ANTHROPIC_API_KEY`, `BKIT_OPENAI_API_KEY` or the opencode provider's key; claude may use the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables instead), the tracker key under Linear / Jira, the Claude GitHub App (`/install-github-app`) for claude, and GitHub Actions write permissions.\n\n" +
|
|
373
497
|
'To opt out and silence this advisory, set `bkit.cloud.agent` to `"none"` in package.json.',
|
|
374
498
|
};
|
|
375
499
|
}
|
|
@@ -21,12 +21,14 @@ import {
|
|
|
21
21
|
buildGithubProjectAdvisory,
|
|
22
22
|
buildGithubProjectTokenScopeAdvisory,
|
|
23
23
|
buildTrackerSetupAdvisory,
|
|
24
|
+
buildTrivyProtectionAdvisory,
|
|
24
25
|
detectActionsWritePermissions,
|
|
25
26
|
detectMainBranchProtection,
|
|
26
27
|
} from "./github.js";
|
|
27
28
|
import {
|
|
28
29
|
buildDepUpdaterSetupAdvisory,
|
|
29
30
|
detectBkitStubs,
|
|
31
|
+
detectProjectDocs,
|
|
30
32
|
detectValeMissing,
|
|
31
33
|
detectValePackageNotSynced,
|
|
32
34
|
detectWorkflowLintToolsMissing,
|
|
@@ -43,7 +45,11 @@ import {
|
|
|
43
45
|
detectTestIntegrationEnv,
|
|
44
46
|
detectTurboIntegrationInputs,
|
|
45
47
|
} from "./ci-yml.js";
|
|
46
|
-
import {
|
|
48
|
+
import {
|
|
49
|
+
isAdvisorySuppressed,
|
|
50
|
+
type SuppressionNote,
|
|
51
|
+
type SuppressionReporter,
|
|
52
|
+
} from "./suppression.js";
|
|
47
53
|
import {
|
|
48
54
|
dropTipSilencedAdvisories,
|
|
49
55
|
setupTipsChecklistLines,
|
|
@@ -360,14 +366,17 @@ export function runPostInstallCheck(
|
|
|
360
366
|
const managedDuplicate = detectManagedDuplicate(cwd);
|
|
361
367
|
if (managedDuplicate) phase3.push(managedDuplicate);
|
|
362
368
|
|
|
363
|
-
// BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server.
|
|
364
|
-
|
|
369
|
+
// BKIT_GH_TOKEN shell env — authenticates the GitHub MCP server. Skipped inside the pre-push
|
|
370
|
+
// hook's inner run, which unsets the .bkit/.env keys on purpose (BKIT_PRE_PUSH_LOGGED is set).
|
|
371
|
+
const ghMcpToken = process.env.BKIT_PRE_PUSH_LOGGED ? null : detectGhMcpToken(cwd);
|
|
365
372
|
if (ghMcpToken) phase3.push(ghMcpToken);
|
|
366
373
|
|
|
367
374
|
// Main branch protection — bkit's PR-base gates (build Step 16, ship Step 2)
|
|
368
375
|
// assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
|
|
369
376
|
// protection on main restricting merges to PRs from dev.
|
|
370
377
|
const protectionStatus = detectMainBranchProtection();
|
|
378
|
+
const trivyProtection = buildTrivyProtectionAdvisory(cwd);
|
|
379
|
+
if (trivyProtection) phase3.push(trivyProtection);
|
|
371
380
|
const scriptHint =
|
|
372
381
|
"\n\nQuick path: run `bkit setup protect-main --dry-run` to preview the policy, then drop `--dry-run` to apply. It requires the CI capstone job named by `package.json` `bkit.testing.ciCapstone` (default `bkit-tests-check`, so the required check means 'validated', not just 'tests job did not fail') and pre-flights that the job exists in the `bkit.testing.ciWorkflow` file before requiring it.";
|
|
373
382
|
if (protectionStatus === "missing") {
|
|
@@ -469,6 +478,12 @@ export function runPostInstallCheck(
|
|
|
469
478
|
// bkit-stub sentinels in shipped templates — one advisory per still-commented stub.
|
|
470
479
|
for (const stub of detectBkitStubs(cwd)) phase3.push(stub);
|
|
471
480
|
|
|
481
|
+
// Project documents (docs/*.md): missing, empty, starter-only or unindexed. Advisory only.
|
|
482
|
+
for (const f of detectProjectDocs(cwd)) {
|
|
483
|
+
if (!isAdvisorySuppressed(cwd, f.id, f.severity)) phase3.push(f);
|
|
484
|
+
else onSuppressed?.({ id: f.id, scope: "." });
|
|
485
|
+
}
|
|
486
|
+
|
|
472
487
|
// turbo.json inputs for cache-replay safety (KN-24).
|
|
473
488
|
for (const f of detectTurboIntegrationInputs(cwd)) phase3.push(f);
|
|
474
489
|
|
|
@@ -6,6 +6,23 @@ import * as path from "node:path";
|
|
|
6
6
|
import { spawnSync } from "node:child_process";
|
|
7
7
|
import type { PreflightFinding } from "../before/index.js";
|
|
8
8
|
import { readPackageJson } from "../../shared/package-json.js";
|
|
9
|
+
import { readTextFile } from "../../shared/json.js";
|
|
10
|
+
import { getPkgRoot } from "../../shared/package-roots.js";
|
|
11
|
+
import {
|
|
12
|
+
PROJECT_DOC_TOPICS,
|
|
13
|
+
PROJECT_INDEX_PATH,
|
|
14
|
+
type ProjectDocTopic,
|
|
15
|
+
findIndexedEquivalent,
|
|
16
|
+
listIndexedEquivalents,
|
|
17
|
+
inspectRepoFile,
|
|
18
|
+
isInTreePath,
|
|
19
|
+
legacyStarterTopic,
|
|
20
|
+
normalizeLegacyText,
|
|
21
|
+
projectDocPath,
|
|
22
|
+
readProjectIndex,
|
|
23
|
+
starterPath,
|
|
24
|
+
} from "../../install/project-docs.js";
|
|
25
|
+
import { stripManagedWrapper } from "../../install/managed-block.js";
|
|
9
26
|
import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
|
|
10
27
|
import {
|
|
11
28
|
DEP_UPDATER_NAMES,
|
|
@@ -283,7 +300,7 @@ export function detectBkitStubs(cwd: string): PreflightFinding[] {
|
|
|
283
300
|
detect: `${ciRel} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
|
|
284
301
|
action:
|
|
285
302
|
`${stub.description}\n\n` +
|
|
286
|
-
`Before enabling a CI lane, read docs/testing.md § CI test tiers and docs/deployments.md (one run per branch, push base
|
|
303
|
+
`Before enabling a CI lane, read docs/testing.md § CI test tiers and docs/deployments.md (one run per branch, push base). The FULL CI SCAFFOLD REFERENCE in ${ciRel} is the job graph: needs, if, step names. Write the job from that graph and from those docs. Uncomment only a block that is already commented YAML or shell.\n\n` +
|
|
287
304
|
`Decide with the user: (a) enable — uncomment the YAML/shell block AND delete the \`# bkit-stub:${stub.id} — ...\` header line; (b) customise — adjust paths/secrets/conditions before uncommenting; (c) dismiss — delete the entire stub block (header + commented body).\n\n` +
|
|
288
305
|
`Until the sentinel is removed, this advisory fires every install / check.`,
|
|
289
306
|
});
|
|
@@ -415,3 +432,230 @@ export function buildDepUpdaterSetupAdvisory(cwd: string): PreflightFinding | nu
|
|
|
415
432
|
'Use one updater, not both, and set `bkit.dependencies.updater` to its name (`"renovate"` or `"dependabot"`) in package.json. To silence this advisory, set it to `"none"`. See .bkit/templates.md.',
|
|
416
433
|
};
|
|
417
434
|
}
|
|
435
|
+
|
|
436
|
+
// ---------------------------------------------------------------------------
|
|
437
|
+
// Project documentation adoption and population
|
|
438
|
+
// ---------------------------------------------------------------------------
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* `docs/components.md` is checked beside the ten topics, at its own path only: an indexed
|
|
442
|
+
* equivalent does not count for it, and `bkit upgrade` adds no index row for it.
|
|
443
|
+
*/
|
|
444
|
+
const COMPONENTS_DOC = "components";
|
|
445
|
+
const COMPONENTS_DOC_PATH = `docs/${COMPONENTS_DOC}.md`;
|
|
446
|
+
|
|
447
|
+
type StarterName = ProjectDocTopic | typeof COMPONENTS_DOC;
|
|
448
|
+
|
|
449
|
+
/** How every hand-filled starter's introduction opens. A filled document no longer has it. */
|
|
450
|
+
const STARTER_OPENER = "> Starter document.";
|
|
451
|
+
|
|
452
|
+
/** Text of a starter: the package copy first, then the consumer's own copy. */
|
|
453
|
+
function readStarterText(cwd: string, name: StarterName): string | null {
|
|
454
|
+
const rel =
|
|
455
|
+
name === COMPONENTS_DOC ? `.bkit/templates/${COMPONENTS_DOC_PATH}` : starterPath(name);
|
|
456
|
+
for (const base of [getPkgRoot(), cwd]) {
|
|
457
|
+
const read = readTextFile(path.join(base, rel));
|
|
458
|
+
if (read.ok) return read.text;
|
|
459
|
+
}
|
|
460
|
+
return null;
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
type DocAssessment = "empty" | "unpopulated" | "candidate";
|
|
464
|
+
|
|
465
|
+
/**
|
|
466
|
+
* Mechanical read of a project document: empty, an untouched starter, a document that still
|
|
467
|
+
* opens with the starter's introduction, headings only, or a candidate.
|
|
468
|
+
*/
|
|
469
|
+
function assessDocText(cwd: string, name: StarterName, text: string): DocAssessment {
|
|
470
|
+
if (text.trim() === "") return "empty";
|
|
471
|
+
const normalized = normalizeLegacyText(text);
|
|
472
|
+
const legacy = legacyStarterTopic(text);
|
|
473
|
+
if (legacy === name) return "unpopulated";
|
|
474
|
+
const starter = readStarterText(cwd, name);
|
|
475
|
+
if (starter !== null && normalizeLegacyText(starter) === normalized) return "unpopulated";
|
|
476
|
+
if (normalized.startsWith(STARTER_OPENER)) return "unpopulated";
|
|
477
|
+
// Headings, comments and rules only: nothing a project wrote.
|
|
478
|
+
const meaningful = normalized
|
|
479
|
+
.split("\n")
|
|
480
|
+
.map((l) => l.trim())
|
|
481
|
+
.filter(
|
|
482
|
+
(l) => l !== "" && !l.startsWith("#") && !/^<!--.*-->$/.test(l) && !/^[-*_|: ]+$/.test(l),
|
|
483
|
+
);
|
|
484
|
+
return meaningful.length === 0 ? "unpopulated" : "candidate";
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* Report the state of the ten project documents (`docs/architecture.md` ... `docs/setup.md`):
|
|
489
|
+
* the index missing, a document absent, empty, an untouched starter, still opening with the
|
|
490
|
+
* starter's introduction, present but unindexed, or unreadable. A document the index lists at
|
|
491
|
+
* another path (same basename, or a Scope cell `Equivalent to docs/<topic>.md`) counts for its
|
|
492
|
+
* topic. `docs/components.md` is reported too when it is absent or unfilled. Findings are
|
|
493
|
+
* advisories only and read no file outside the repository. A document that differs from every
|
|
494
|
+
* starter is a candidate for the agent to assess; the mechanical read makes no claim about
|
|
495
|
+
* what it covers.
|
|
496
|
+
*/
|
|
497
|
+
export function detectProjectDocs(cwd: string): PreflightFinding[] {
|
|
498
|
+
const index = readProjectIndex(cwd);
|
|
499
|
+
const rows = index.status === "ok" ? index.rows : [];
|
|
500
|
+
const indexedPaths = new Set(rows.map((r) => r.path));
|
|
501
|
+
const missing: string[] = [];
|
|
502
|
+
const unpopulated: string[] = [];
|
|
503
|
+
const unindexed: string[] = [];
|
|
504
|
+
const unindexedWrapped: string[] = [];
|
|
505
|
+
const unindexedBlocked: string[] = [];
|
|
506
|
+
const duplicates: string[] = [];
|
|
507
|
+
const ambiguous: string[] = [];
|
|
508
|
+
const cleanup: string[] = [];
|
|
509
|
+
|
|
510
|
+
const componentsState = inspectRepoFile(cwd, COMPONENTS_DOC_PATH);
|
|
511
|
+
if (componentsState === "absent") missing.push(COMPONENTS_DOC_PATH);
|
|
512
|
+
else if (componentsState !== "regular") {
|
|
513
|
+
ambiguous.push(`${COMPONENTS_DOC_PATH} (${componentsState.unsafe})`);
|
|
514
|
+
} else {
|
|
515
|
+
const read = readTextFile(path.join(cwd, COMPONENTS_DOC_PATH));
|
|
516
|
+
if (!read.ok) ambiguous.push(`${COMPONENTS_DOC_PATH} (it could not be read)`);
|
|
517
|
+
else if (assessDocText(cwd, COMPONENTS_DOC, read.text) !== "candidate") {
|
|
518
|
+
unpopulated.push(COMPONENTS_DOC_PATH);
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
for (const topic of PROJECT_DOC_TOPICS) {
|
|
523
|
+
const recommended = projectDocPath(topic);
|
|
524
|
+
const isUsableRow = (row: string) =>
|
|
525
|
+
isInTreePath(row) && inspectRepoFile(cwd, row) === "regular";
|
|
526
|
+
// The first valid same-topic row wins; when none is valid every candidate row is named.
|
|
527
|
+
const equivalent = findIndexedEquivalent(rows, topic, isUsableRow);
|
|
528
|
+
const candidates = listIndexedEquivalents(rows, topic);
|
|
529
|
+
const defaultState = inspectRepoFile(cwd, recommended);
|
|
530
|
+
let target = recommended;
|
|
531
|
+
if (defaultState === "absent") {
|
|
532
|
+
if (equivalent === null) {
|
|
533
|
+
if (candidates.length > 0) {
|
|
534
|
+
ambiguous.push(
|
|
535
|
+
`${candidates.join(", ")} (${recommended}: every indexed row for it is unusable)`,
|
|
536
|
+
);
|
|
537
|
+
} else {
|
|
538
|
+
missing.push(recommended);
|
|
539
|
+
}
|
|
540
|
+
continue;
|
|
541
|
+
}
|
|
542
|
+
target = equivalent;
|
|
543
|
+
}
|
|
544
|
+
if (!isInTreePath(target)) {
|
|
545
|
+
ambiguous.push(`${target} (${recommended}: it resolves outside the repository)`);
|
|
546
|
+
continue;
|
|
547
|
+
}
|
|
548
|
+
const state = target === recommended ? defaultState : inspectRepoFile(cwd, target);
|
|
549
|
+
if (state === "absent") {
|
|
550
|
+
missing.push(recommended);
|
|
551
|
+
continue;
|
|
552
|
+
}
|
|
553
|
+
if (state !== "regular") {
|
|
554
|
+
ambiguous.push(`${target} (${state.unsafe})`);
|
|
555
|
+
continue;
|
|
556
|
+
}
|
|
557
|
+
const read = readTextFile(path.join(cwd, target));
|
|
558
|
+
if (!read.ok) {
|
|
559
|
+
ambiguous.push(`${target} (it could not be read)`);
|
|
560
|
+
continue;
|
|
561
|
+
}
|
|
562
|
+
const wrapper = stripManagedWrapper(read.text);
|
|
563
|
+
if (wrapper.status === "ambiguous") cleanup.push(`${target} (${wrapper.problem})`);
|
|
564
|
+
const assessed = assessDocText(cwd, topic, read.text);
|
|
565
|
+
if (assessed === "empty" || assessed === "unpopulated") unpopulated.push(target);
|
|
566
|
+
else if (index.status === "ok" && !indexedPaths.has(target)) {
|
|
567
|
+
const covering = findIndexedEquivalent(
|
|
568
|
+
rows,
|
|
569
|
+
topic,
|
|
570
|
+
(row) => isInTreePath(row) && inspectRepoFile(cwd, row) === "regular",
|
|
571
|
+
);
|
|
572
|
+
if (covering !== null && target === recommended)
|
|
573
|
+
duplicates.push(`${target} (beside ${covering})`);
|
|
574
|
+
else if (wrapper.status === "ambiguous") unindexedWrapped.push(target);
|
|
575
|
+
else if ((index.unparsed ?? []).length > 0) unindexedBlocked.push(target);
|
|
576
|
+
else unindexed.push(target);
|
|
577
|
+
}
|
|
578
|
+
}
|
|
579
|
+
|
|
580
|
+
const findings: PreflightFinding[] = [];
|
|
581
|
+
if (index.status === "missing") {
|
|
582
|
+
findings.push({
|
|
583
|
+
id: "project-docs-index-missing",
|
|
584
|
+
severity: "advisory",
|
|
585
|
+
detect: `${PROJECT_INDEX_PATH} is absent, so agents have no list of the project's own documents to consult.`,
|
|
586
|
+
action: `Run \`bkit install\` to write ${PROJECT_INDEX_PATH}, then add a row under \`## Project Documents\` for each project document you keep. Until then agents warn and fall back to repository evidence.`,
|
|
587
|
+
});
|
|
588
|
+
} else if (index.status === "unreadable") {
|
|
589
|
+
ambiguous.push(`${PROJECT_INDEX_PATH} (${index.reason})`);
|
|
590
|
+
} else {
|
|
591
|
+
for (const row of index.unparsed ?? []) {
|
|
592
|
+
ambiguous.push(`${PROJECT_INDEX_PATH} (unreadable table row: ${row.slice(0, 80)})`);
|
|
593
|
+
}
|
|
594
|
+
}
|
|
595
|
+
if (missing.length > 0) {
|
|
596
|
+
findings.push({
|
|
597
|
+
id: "project-docs-missing",
|
|
598
|
+
severity: "advisory",
|
|
599
|
+
detect: `No project document covers: ${missing.join(", ")}.`,
|
|
600
|
+
action: `Copy the starter for each topic you want from \`.bkit/templates/docs/\` into \`docs/\`, fill it in from the repository, and add its row to \`## Project Documents\` in ${PROJECT_INDEX_PATH}. A document you already keep elsewhere counts: index it with \`Equivalent to <recommended path>\` in its Scope cell. Skip topics that do not apply. Fill the docs in the order of .bkit/templates.md § Project docs — adoption order.`,
|
|
601
|
+
});
|
|
602
|
+
}
|
|
603
|
+
if (unpopulated.length > 0) {
|
|
604
|
+
findings.push({
|
|
605
|
+
id: "project-docs-unpopulated",
|
|
606
|
+
severity: "advisory",
|
|
607
|
+
detect: `These project documents are empty, still hold only the shipped starter text, or still open with the starter's introduction: ${unpopulated.join(", ")}.`,
|
|
608
|
+
action: `Replace the placeholders in ${unpopulated.join(", ")} with project facts taken from the repository, then delete the introduction above the title. Or index an equivalent document that already holds the facts (\`Equivalent to <recommended path>\` in the Scope cell of ${PROJECT_INDEX_PATH}). Agents warn about these topics until the text changes. Fill the docs in the order of .bkit/templates.md § Project docs — adoption order.`,
|
|
609
|
+
});
|
|
610
|
+
}
|
|
611
|
+
if (unindexed.length > 0) {
|
|
612
|
+
findings.push({
|
|
613
|
+
id: "project-docs-unindexed",
|
|
614
|
+
severity: "advisory",
|
|
615
|
+
detect: `These project documents exist but ${PROJECT_INDEX_PATH} does not list them: ${unindexed.join(", ")}.`,
|
|
616
|
+
action: `Add a row for each to \`## Project Documents\` in ${PROJECT_INDEX_PATH}, or run \`bkit upgrade\` to register the default paths.`,
|
|
617
|
+
});
|
|
618
|
+
}
|
|
619
|
+
if (unindexedWrapped.length > 0) {
|
|
620
|
+
findings.push({
|
|
621
|
+
id: "project-docs-unindexed",
|
|
622
|
+
severity: "advisory",
|
|
623
|
+
detect: `These project documents exist but ${PROJECT_INDEX_PATH} does not list them, and bkit will not register them while their ownership wrapper stays: ${unindexedWrapped.join(", ")}.`,
|
|
624
|
+
action: `Remove the wrapper as the cleanup advisory describes, then add a row for each to \`## Project Documents\` in ${PROJECT_INDEX_PATH} (or run \`bkit upgrade\` once the wrapper is gone).`,
|
|
625
|
+
});
|
|
626
|
+
}
|
|
627
|
+
if (unindexedBlocked.length > 0) {
|
|
628
|
+
findings.push({
|
|
629
|
+
id: "project-docs-unindexed",
|
|
630
|
+
severity: "advisory",
|
|
631
|
+
detect: `These project documents exist but ${PROJECT_INDEX_PATH} does not list them, and bkit will not register them while a row of \`## Project Documents\` is unreadable: ${unindexedBlocked.join(", ")}.`,
|
|
632
|
+
action: `Repair or remove the unreadable row named in the ambiguous advisory, then add a row for each to \`## Project Documents\` in ${PROJECT_INDEX_PATH} (or run \`bkit upgrade\` once the row is repaired).`,
|
|
633
|
+
});
|
|
634
|
+
}
|
|
635
|
+
if (duplicates.length > 0) {
|
|
636
|
+
findings.push({
|
|
637
|
+
id: "project-docs-unindexed",
|
|
638
|
+
severity: "advisory",
|
|
639
|
+
detect: `These project documents exist but ${PROJECT_INDEX_PATH} lists another document for the same topic: ${duplicates.join(", ")}.`,
|
|
640
|
+
action: `bkit does not register them while the other document is indexed. Keep one: delete the unused file, or add a row for the second one by hand under \`## Project Documents\` in ${PROJECT_INDEX_PATH}.`,
|
|
641
|
+
});
|
|
642
|
+
}
|
|
643
|
+
if (cleanup.length > 0) {
|
|
644
|
+
findings.push({
|
|
645
|
+
id: "project-docs-cleanup",
|
|
646
|
+
severity: "advisory",
|
|
647
|
+
detect: `These project documents still carry a bkit ownership wrapper (\`<!-- bkit:start -->\` / \`<!-- bkit:end -->\` lines or the \`bkit:managed\` notice) that bkit could not remove safely: ${cleanup.join("; ")}.`,
|
|
648
|
+
action: `Edit each file by hand: delete the \`<!-- bkit:start -->\` and \`<!-- bkit:end -->\` lines and the \`bkit:managed\` notice line, keeping the text between them. These documents belong to the project now; bkit changes none of them itself.`,
|
|
649
|
+
});
|
|
650
|
+
}
|
|
651
|
+
if (ambiguous.length > 0) {
|
|
652
|
+
findings.push({
|
|
653
|
+
id: "project-docs-ambiguous",
|
|
654
|
+
severity: "advisory",
|
|
655
|
+
detect: `bkit did not read these project documents or the index: ${ambiguous.join("; ")}.`,
|
|
656
|
+
action: `Replace each with a regular file inside the repository (no symbolic link, no \`..\` path), or repair the \`## Project Documents\` table in ${PROJECT_INDEX_PATH}. bkit changes none of them itself.`,
|
|
657
|
+
});
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
return findings;
|
|
661
|
+
}
|