@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
|
@@ -0,0 +1,551 @@
|
|
|
1
|
+
// install/project-docs.ts — the ten project documents bkit recommends (`docs/architecture.md` …
|
|
2
|
+
// `docs/setup.md`): the topic catalog, the legacy-starter digests, the ownership migration for a
|
|
3
|
+
// document an older release installed as a managed block, and the `Project Documents` index
|
|
4
|
+
// (`.agents/docs.md`, below the closing `bkit:end`) that lists the project's own copies.
|
|
5
|
+
//
|
|
6
|
+
// The starters ship in `.bkit/templates/docs/`; the project copies a starter to `docs/` and owns
|
|
7
|
+
// it. Nothing here creates a project document. Every write is one of two surgical edits: removing
|
|
8
|
+
// the exact ownership-wrapper lines of a legacy managed document, or inserting a table row into
|
|
9
|
+
// `Project Documents`. Anything ambiguous or unsafe is left byte-for-byte and reported.
|
|
10
|
+
import * as crypto from "node:crypto";
|
|
11
|
+
import * as fs from "node:fs";
|
|
12
|
+
import * as path from "node:path";
|
|
13
|
+
import { LOG_PREFIX } from "../shared/log-prefix.js";
|
|
14
|
+
import { findLineAnchoredMarkers, stripManagedWrapper } from "./managed-block.js";
|
|
15
|
+
// ---------------------------------------------------------------------------
|
|
16
|
+
// Topic catalog
|
|
17
|
+
// ---------------------------------------------------------------------------
|
|
18
|
+
/** The ten topics, in index order. */
|
|
19
|
+
export const PROJECT_DOC_TOPICS = [
|
|
20
|
+
"architecture",
|
|
21
|
+
"technology",
|
|
22
|
+
"security",
|
|
23
|
+
"data-schema",
|
|
24
|
+
"testing",
|
|
25
|
+
"deployments",
|
|
26
|
+
"observability",
|
|
27
|
+
"design",
|
|
28
|
+
"noise",
|
|
29
|
+
"setup",
|
|
30
|
+
];
|
|
31
|
+
const TOPIC_INFO = {
|
|
32
|
+
architecture: {
|
|
33
|
+
phases: ["●", "●", "●", "○", "○"],
|
|
34
|
+
scope: "How the system is built and where it runs: runtimes, package boundaries, file placement and environments.",
|
|
35
|
+
},
|
|
36
|
+
technology: {
|
|
37
|
+
phases: ["●", "●", "○", "○", "○"],
|
|
38
|
+
scope: "Which frameworks, libraries and styling systems the project uses, and the coding conventions a reviewer enforces. Why a choice was made goes in `decisions.jsonl`.",
|
|
39
|
+
},
|
|
40
|
+
security: {
|
|
41
|
+
phases: ["●", "●", "●", "○", "○"],
|
|
42
|
+
scope: "Authentication, authorization, input validation, rate limiting, secrets management and PII handling.",
|
|
43
|
+
},
|
|
44
|
+
"data-schema": {
|
|
45
|
+
phases: ["○", "○", "●", "○", "○"],
|
|
46
|
+
scope: "The active production schema: tables, fields, access policies, indices, functions and triggers.",
|
|
47
|
+
},
|
|
48
|
+
testing: {
|
|
49
|
+
phases: ["○", "●", "●", "●", "—"],
|
|
50
|
+
scope: "Testing strategy: tier boundaries, framework choices, naming conventions and the CI lane graph.",
|
|
51
|
+
},
|
|
52
|
+
deployments: {
|
|
53
|
+
phases: ["○", "○", "○", "●", "●"],
|
|
54
|
+
scope: "Deployment and CI/CD: environments, release path, secrets, branch protection, run-level tiers and rollback.",
|
|
55
|
+
},
|
|
56
|
+
observability: {
|
|
57
|
+
phases: ["○", "○", "●", "●", "○"],
|
|
58
|
+
scope: "Logging architecture, correlation tracing, telemetry pipelines, error tracking and alerts.",
|
|
59
|
+
},
|
|
60
|
+
design: {
|
|
61
|
+
phases: ["○", "○", "○", "—", "—"],
|
|
62
|
+
scope: "The project's design system: tokens, typography, spacing and layout, components and accessibility rules.",
|
|
63
|
+
},
|
|
64
|
+
noise: {
|
|
65
|
+
phases: ["—", "—", "○", "●", "○"],
|
|
66
|
+
scope: "Intentional signal downgrades: log levels, error-tracker archives and mutes, and alert thresholds, each with its trigger and reason.",
|
|
67
|
+
},
|
|
68
|
+
setup: {
|
|
69
|
+
phases: ["—", "—", "○", "○", "—"],
|
|
70
|
+
scope: "How a developer sets up and runs the project locally: prerequisites, first-time setup, environment variables, local services, everyday commands and troubleshooting.",
|
|
71
|
+
},
|
|
72
|
+
};
|
|
73
|
+
/** The recommended repo-relative path of a topic's project document. */
|
|
74
|
+
export function projectDocPath(topic) {
|
|
75
|
+
return `docs/${topic}.md`;
|
|
76
|
+
}
|
|
77
|
+
/** Repo-relative path of the document index that holds the `Project Documents` table. */
|
|
78
|
+
export const PROJECT_INDEX_PATH = ".agents/docs.md";
|
|
79
|
+
/** Repo-relative path of a topic's starter copy under the consumer's `.bkit/`. */
|
|
80
|
+
export function starterPath(topic) {
|
|
81
|
+
return `.bkit/templates/docs/${topic}.md`;
|
|
82
|
+
}
|
|
83
|
+
/** The topic a repo-relative path is the recommended document of, or null. */
|
|
84
|
+
export function topicOfPath(rel) {
|
|
85
|
+
return PROJECT_DOC_TOPICS.find((t) => projectDocPath(t) === rel) ?? null;
|
|
86
|
+
}
|
|
87
|
+
// ---------------------------------------------------------------------------
|
|
88
|
+
// Legacy starter digests
|
|
89
|
+
//
|
|
90
|
+
// Releases up to 6.1.x installed these ten documents as managed blocks. Digests of that shipped
|
|
91
|
+
// text let a later check tell an untouched legacy starter from a document the project wrote.
|
|
92
|
+
//
|
|
93
|
+
// Source revision : `.bkit/shared/docs/<topic>.md` as committed at 45f4254bd.
|
|
94
|
+
// Rendering rules : install rendered `{{BKIT_MANAGED_MARKER}}` into the `bkit:managed` notice
|
|
95
|
+
// line and `{{DEFAULT_BRANCH}}` into the default branch (`main` here). The
|
|
96
|
+
// other `{{...}}` text in the sources is prose and stayed literal.
|
|
97
|
+
// Normalization : see `normalizeLegacyText`. Digests cover text a project may not have
|
|
98
|
+
// touched, never the ownership lines, line endings or blank-line runs.
|
|
99
|
+
//
|
|
100
|
+
// A copy rendered with another default branch does not match, so it reads as "differs", which
|
|
101
|
+
// callers treat as a candidate for assessment, never as proof of content.
|
|
102
|
+
// ---------------------------------------------------------------------------
|
|
103
|
+
/** Commit the legacy starter text was read from. */
|
|
104
|
+
export const LEGACY_STARTER_SOURCE_REVISION = "45f4254bd";
|
|
105
|
+
const LEGACY_NOTICE_RE = /^<!-- bkit:managed v\S+ — (?:.* — )?do (?:not|NOT) edit; run `bkit upgrade` to refresh -->$/;
|
|
106
|
+
const BRANCH = "[A-Za-z0-9._/-]+";
|
|
107
|
+
/** The contexts the shipped starters render the project's default branch into. */
|
|
108
|
+
const BRANCH_CONTEXTS = [
|
|
109
|
+
[new RegExp(`(\`dev\`\\s*(?:/|or)\\s*\`)${BRANCH}(\`)`, "g"), "$1main$2"],
|
|
110
|
+
[new RegExp(`(push to \`)${BRANCH}(\`)`, "g"), "$1main$2"],
|
|
111
|
+
[new RegExp(`(refs/heads/)${BRANCH}(')`, "g"), "$1main$2"],
|
|
112
|
+
[new RegExp(`((?:On|queues on) \`)${BRANCH}(\`)`, "g"), "$1main$2"],
|
|
113
|
+
];
|
|
114
|
+
/** A rendered default branch in a starter's known contexts, replaced by `main`. */
|
|
115
|
+
function anyBranch(line) {
|
|
116
|
+
let out = line;
|
|
117
|
+
for (const [re, to] of BRANCH_CONTEXTS)
|
|
118
|
+
out = out.replace(re, to);
|
|
119
|
+
return out;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Normalize a document for comparison with a legacy starter: LF line endings, the former
|
|
123
|
+
* ownership lines (`bkit:start`, `bkit:end`, the `bkit:managed` notice and the unrendered
|
|
124
|
+
* `{{BKIT_MANAGED_MARKER}}` token) dropped, the default-branch token rendered as `main`,
|
|
125
|
+
* leading and trailing whitespace trimmed per line, runs of inner spaces and tabs collapsed to one
|
|
126
|
+
* space and runs of blank lines collapsed.
|
|
127
|
+
*/
|
|
128
|
+
export function normalizeLegacyText(text) {
|
|
129
|
+
const kept = [];
|
|
130
|
+
for (const raw of text.replace(/\r\n?/g, "\n").split("\n")) {
|
|
131
|
+
const line = anyBranch(raw.replace(/\{\{DEFAULT_BRANCH\}\}/g, "main"))
|
|
132
|
+
.replace(/[ \t]+/g, " ")
|
|
133
|
+
.trim();
|
|
134
|
+
if (line === "<!-- bkit:start -->" || line === "<!-- bkit:end -->")
|
|
135
|
+
continue;
|
|
136
|
+
if (line === "{{BKIT_MANAGED_MARKER}}" || LEGACY_NOTICE_RE.test(line))
|
|
137
|
+
continue;
|
|
138
|
+
kept.push(line);
|
|
139
|
+
}
|
|
140
|
+
return kept
|
|
141
|
+
.join("\n")
|
|
142
|
+
.replace(/\n{3,}/g, "\n\n")
|
|
143
|
+
.trim();
|
|
144
|
+
}
|
|
145
|
+
/** sha256 of the normalized text. */
|
|
146
|
+
export function legacyDigest(text) {
|
|
147
|
+
return crypto.createHash("sha256").update(normalizeLegacyText(text)).digest("hex");
|
|
148
|
+
}
|
|
149
|
+
/** Digest of each topic's normalized legacy starter. */
|
|
150
|
+
export const LEGACY_STARTER_DIGESTS = {
|
|
151
|
+
architecture: "b949b773e10f9d0a797189c942a5884a4c971805da43520883138118226ad845",
|
|
152
|
+
technology: "723fd7fa4c001c1c3d562bd9de18f9830df3beebdcd45b54afeee159ce7bf2f0",
|
|
153
|
+
security: "e125a3c7de63b5bb20a3a43b09b7381125339f8f0a5bafc597f6a146b27b04a1",
|
|
154
|
+
"data-schema": "2cd1f2eedc508af1d609ce5b53b0e1836cc33c8fd4e67fb2ad4c821f83043c5f",
|
|
155
|
+
testing: "1bfcabad6ebf8bb0a73ec0871f0d2e38ffd807fad8bb56bb3a5504ad3ffc254c",
|
|
156
|
+
deployments: "dc2c717eab87bd46b44b45ee7b2563ddd25e4a4f91326c403a6d7394ef2c5cc8",
|
|
157
|
+
observability: "bebf67757c55db829ed4c429cefadf28b31175361f40e253b014d50e73dd5a65",
|
|
158
|
+
design: "2e680b2857679af9672b1112cf06d7e1282c75c739e36428e49cf13be33bfc92",
|
|
159
|
+
noise: "64ddcda2d9ee14efbe1a210c1f5177e6cc4dfa10417d410825d8765628307773",
|
|
160
|
+
setup: "174b5a0143c96470ee5c5e2bbe7b5f38d904ec98ba4fb27892b2b5030cfcd75e",
|
|
161
|
+
};
|
|
162
|
+
/** Digests of every released shipped starter text per topic (each tag that installed .bkit/shared/docs/) plus the recorded revision. */
|
|
163
|
+
export const LEGACY_STARTER_DIGEST_HISTORY = {
|
|
164
|
+
architecture: [
|
|
165
|
+
"cba1e5a333c26b5a797c6b73aa1efd6d0d4644372482e5d8a697b34708257ac0",
|
|
166
|
+
"1e52e99285ebe88454253965fedd92efad7e2c5fbfd95062f9dfecf77ac8995b",
|
|
167
|
+
"b949b773e10f9d0a797189c942a5884a4c971805da43520883138118226ad845",
|
|
168
|
+
],
|
|
169
|
+
technology: [
|
|
170
|
+
"75446a8a702c822dfdfb24593c4807d30b0291e1e116b664ba7031f9af0530ba",
|
|
171
|
+
"d8167d2e9ce3b1ab18fdeecf5f5b9480e4cac7361a9e7ace7e135ff4ec43f3a4",
|
|
172
|
+
"723fd7fa4c001c1c3d562bd9de18f9830df3beebdcd45b54afeee159ce7bf2f0",
|
|
173
|
+
],
|
|
174
|
+
security: [
|
|
175
|
+
"be84dc3b19cc34a13cdfc58062970d00a3564eacbcf05a0336646efe84f54630",
|
|
176
|
+
"752ae21e35128e17fc3a2fd6e009bf38751f6ccaa6c76d1723c1c99aff462335",
|
|
177
|
+
"5627543777d4f0bd4b8885df23e32d9ff9cc03c8b706894943bb018ec71c8cab",
|
|
178
|
+
"38bd66f0a66c7b2f3e454132df182b31538e045141f2fd6f761c57af2890c422",
|
|
179
|
+
"040408ccd16e3872d5eced55d36172fc163dcde548e89f382eafa992282f027c",
|
|
180
|
+
"26b8927e8df45b989422b417df8f406cd8b8c594811e42919756d26e807133c0",
|
|
181
|
+
"e15f29264be7acaee091ed7c4681bb9d886782a9b7bd4f645adcbbfe0f0bc392",
|
|
182
|
+
"e125a3c7de63b5bb20a3a43b09b7381125339f8f0a5bafc597f6a146b27b04a1",
|
|
183
|
+
],
|
|
184
|
+
"data-schema": [
|
|
185
|
+
"cc8f7b971e1714b9dde60a89738495fdf30b112536a94cd45e94a2e2cc5cc155",
|
|
186
|
+
"6af1f76b57568dd1bbd9bd48dd5fe55ffb64c08f12ac2e361576131a912be32e",
|
|
187
|
+
"2cd1f2eedc508af1d609ce5b53b0e1836cc33c8fd4e67fb2ad4c821f83043c5f",
|
|
188
|
+
],
|
|
189
|
+
testing: [
|
|
190
|
+
"bd8ebf504f7368725148f94374ce9ae9e849de8f993975a3a60f935da33516e8",
|
|
191
|
+
"c4f910bd9265cb4e1c7503b8ef4b49ede5a7dccfc2ea0ae3d23df9c8ae2331b8",
|
|
192
|
+
"9b6dbbf2dfbd3c8c41726c097caccf4183f06262b97d5cf64ea2cc2d2144c593",
|
|
193
|
+
"2b91ac955b3fc9e0d606802637e3a99a98669ae6f88c20db6967e8e95b774c00",
|
|
194
|
+
"7ad2f121f6e0c5eefb30e04032c1faf8314fe8c8260ccfc96a660e71a853f931",
|
|
195
|
+
"9ae2b857908c5195b24ba7b23116367b81182189acd337293253117f6896d6ad",
|
|
196
|
+
"1bfcabad6ebf8bb0a73ec0871f0d2e38ffd807fad8bb56bb3a5504ad3ffc254c",
|
|
197
|
+
],
|
|
198
|
+
deployments: [
|
|
199
|
+
"833c637328e0deec593fa2e4376071fc9eab36f22f96718160d43797e618cbda",
|
|
200
|
+
"6210d30325754cb0cab79753d08a0f07f5c7b60eee663f47084fbd37c3be43ba",
|
|
201
|
+
"8e70e44256ca5e92afeb38a87a464859d31434f88afcbf0ff03c0f3b4826dc20",
|
|
202
|
+
"964064bd2162c776a7f5d6ae740bf43ab6cb60dd16e211470ee91f8bab462c9e",
|
|
203
|
+
"f8f23501362f12a5dc70b8823b9c15399cc0df31d2183abe197ee2c2f4065ba7",
|
|
204
|
+
"96c39c2ce3e9c29c862055611348558ad23896019503a076c89e7981964dbf83",
|
|
205
|
+
"95e2a23dd8764c98965577285d5d181c393531819c900aa3b22004ed0f0880ea",
|
|
206
|
+
"89425e45187d0e64d9c85c0451562b635531fd723d4f4dec44e85ad7a5195676",
|
|
207
|
+
"5004275925310aedcbd82f88fdddaece64e3d6019485cb631d40d384c556dd4d",
|
|
208
|
+
"1c3dc0b4139020853d2274bdd920b9f246b09ed6cec1392f084970917267a776",
|
|
209
|
+
"cf24e7566f6b8440ad56d34882825db3f47e8a77b5b8dff2abdaff6ab5d2270f",
|
|
210
|
+
"dc2c717eab87bd46b44b45ee7b2563ddd25e4a4f91326c403a6d7394ef2c5cc8",
|
|
211
|
+
],
|
|
212
|
+
observability: [
|
|
213
|
+
"3541333403d2f87f34c0846a533dbb2bd9d92af6e92937d094381bd25e3686c6",
|
|
214
|
+
"793007002a287d51f77c4df4ec78ada5a04756d2047d938b315de51a491ec7f4",
|
|
215
|
+
"bebf67757c55db829ed4c429cefadf28b31175361f40e253b014d50e73dd5a65",
|
|
216
|
+
],
|
|
217
|
+
design: [
|
|
218
|
+
"aba4ddee5522d53fa7f179d370bbab0764ee7f3976cf771f95ac008222926b34",
|
|
219
|
+
"1b170ada4eafe88488f34e7f3ed943a6582948b642ecfcd72a6ded95ceb17c46",
|
|
220
|
+
"2e680b2857679af9672b1112cf06d7e1282c75c739e36428e49cf13be33bfc92",
|
|
221
|
+
],
|
|
222
|
+
noise: [
|
|
223
|
+
"19506086100971104bb04f3a5fe7d1304f293193fa056d13d0bc1727af1f7f9f",
|
|
224
|
+
"09d861b868b413f5d58edf097892f12d855aa72bae8ec5f02ed2bffb5d0aa2cb",
|
|
225
|
+
"64ddcda2d9ee14efbe1a210c1f5177e6cc4dfa10417d410825d8765628307773",
|
|
226
|
+
],
|
|
227
|
+
setup: [
|
|
228
|
+
"b3827a1e70fcea5c9c12585a2e3f43cf895ad8eb3bf2bcf66ed8ac19783273b6",
|
|
229
|
+
"d130a83010ddfb870f21f30a8b271880101ee2d103cc361d193262a1a3147e16",
|
|
230
|
+
"a6114f7fc2a8d80460892d5892b6d9d2d59b6ed90974d094b0ddf9f68a2b26fa",
|
|
231
|
+
"174b5a0143c96470ee5c5e2bbe7b5f38d904ec98ba4fb27892b2b5030cfcd75e",
|
|
232
|
+
],
|
|
233
|
+
};
|
|
234
|
+
/** The topic whose legacy starter `text` equals once normalized, or null. */
|
|
235
|
+
export function legacyStarterTopic(text) {
|
|
236
|
+
const digest = legacyDigest(text);
|
|
237
|
+
return PROJECT_DOC_TOPICS.find((t) => LEGACY_STARTER_DIGEST_HISTORY[t].includes(digest)) ?? null;
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* Whether `rel` under `root` is a regular file bkit may read or edit. A symlink (to anywhere), a
|
|
241
|
+
* directory, anything other than a regular file, and a path whose parent directory resolves
|
|
242
|
+
* outside the repository are `unsafe` with the reason.
|
|
243
|
+
*/
|
|
244
|
+
export function inspectRepoFile(root, rel) {
|
|
245
|
+
try {
|
|
246
|
+
const abs = path.join(root, rel);
|
|
247
|
+
const stat = fs.lstatSync(abs, { throwIfNoEntry: false });
|
|
248
|
+
if (stat === undefined)
|
|
249
|
+
return "absent";
|
|
250
|
+
if (stat.isSymbolicLink())
|
|
251
|
+
return { unsafe: "it is a symbolic link" };
|
|
252
|
+
if (!stat.isFile())
|
|
253
|
+
return { unsafe: "it is not a regular file" };
|
|
254
|
+
const realRoot = fs.realpathSync(root);
|
|
255
|
+
const realParent = fs.realpathSync(path.dirname(abs));
|
|
256
|
+
if (realParent !== realRoot && !realParent.startsWith(realRoot + path.sep)) {
|
|
257
|
+
return { unsafe: "it resolves outside the repository" };
|
|
258
|
+
}
|
|
259
|
+
return "regular";
|
|
260
|
+
}
|
|
261
|
+
catch (error) {
|
|
262
|
+
return { unsafe: `it could not be inspected (${errorReason(error)})` };
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
/** A short, path-free reason for a filesystem error. */
|
|
266
|
+
function errorReason(error) {
|
|
267
|
+
const code = error?.code;
|
|
268
|
+
return typeof code === "string" ? code : "filesystem error";
|
|
269
|
+
}
|
|
270
|
+
/** True when `rel` is a repo-relative path with no parent or absolute segments. */
|
|
271
|
+
export function isInTreePath(rel) {
|
|
272
|
+
if (rel === "" || path.isAbsolute(rel) || /^[A-Za-z]:/.test(rel))
|
|
273
|
+
return false;
|
|
274
|
+
for (const ch of rel) {
|
|
275
|
+
const code = ch.charCodeAt(0);
|
|
276
|
+
if (code < 0x20 || code === 0x7f)
|
|
277
|
+
return false;
|
|
278
|
+
}
|
|
279
|
+
return !rel.split(/[\\/]/).includes("..");
|
|
280
|
+
}
|
|
281
|
+
/** Split a table row on unescaped pipes; the empty edges of a leading or trailing pipe are dropped. */
|
|
282
|
+
function splitRow(line) {
|
|
283
|
+
const cells = line.split(/(?<!\\)\|/).map((c) => c.replace(/\\\|/g, "|").trim());
|
|
284
|
+
if (cells[0] === "")
|
|
285
|
+
cells.shift();
|
|
286
|
+
if (cells.length > 0 && cells[cells.length - 1] === "")
|
|
287
|
+
cells.pop();
|
|
288
|
+
return cells;
|
|
289
|
+
}
|
|
290
|
+
/** The path a row's first cell names: backticked, a Markdown link target or a bare path; else null. */
|
|
291
|
+
function cellPath(cell) {
|
|
292
|
+
const tick = /^`([^`]+)`$/.exec(cell);
|
|
293
|
+
if (tick)
|
|
294
|
+
return tick[1].trim() || null;
|
|
295
|
+
const link = /^\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)$/.exec(cell);
|
|
296
|
+
if (link)
|
|
297
|
+
return link[1];
|
|
298
|
+
return /^[^\s`|()[\]*~]+$/.test(cell) ? cell : null;
|
|
299
|
+
}
|
|
300
|
+
/** The `Project Documents` table of the index: the heading below the last `bkit:end`, then the first table. */
|
|
301
|
+
export function readProjectIndex(root) {
|
|
302
|
+
const state = inspectRepoFile(root, PROJECT_INDEX_PATH);
|
|
303
|
+
if (state === "absent")
|
|
304
|
+
return { status: "missing" };
|
|
305
|
+
if (state !== "regular") {
|
|
306
|
+
return { status: "unreadable", reason: `${PROJECT_INDEX_PATH} is not a safe regular file` };
|
|
307
|
+
}
|
|
308
|
+
let text;
|
|
309
|
+
try {
|
|
310
|
+
text = fs.readFileSync(path.join(root, PROJECT_INDEX_PATH), "utf-8");
|
|
311
|
+
}
|
|
312
|
+
catch (error) {
|
|
313
|
+
return {
|
|
314
|
+
status: "unreadable",
|
|
315
|
+
reason: `${PROJECT_INDEX_PATH} could not be read (${errorReason(error)})`,
|
|
316
|
+
};
|
|
317
|
+
}
|
|
318
|
+
const eol = text.includes("\r\n") ? "\r\n" : "\n";
|
|
319
|
+
const ends = findLineAnchoredMarkers(text.replace(/\r/g, ""), "<!-- bkit:end -->");
|
|
320
|
+
if (ends.length === 0) {
|
|
321
|
+
return { status: "unreadable", reason: "no closing `bkit:end` marker above Project Documents" };
|
|
322
|
+
}
|
|
323
|
+
const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
|
|
324
|
+
let offset = 0;
|
|
325
|
+
let afterEnd = false;
|
|
326
|
+
let headingSeen = false;
|
|
327
|
+
let tableStart = -1;
|
|
328
|
+
let tableEnd = -1;
|
|
329
|
+
let needsEol = false;
|
|
330
|
+
const rows = [];
|
|
331
|
+
const unparsed = [];
|
|
332
|
+
for (const line of lines) {
|
|
333
|
+
const bare = line.replace(/\r?\n$/, "");
|
|
334
|
+
const lineEnd = offset + line.length;
|
|
335
|
+
if (!afterEnd) {
|
|
336
|
+
if (bare === "<!-- bkit:end -->")
|
|
337
|
+
afterEnd = true;
|
|
338
|
+
}
|
|
339
|
+
else if (!headingSeen) {
|
|
340
|
+
if (bare === "## Project Documents")
|
|
341
|
+
headingSeen = true;
|
|
342
|
+
}
|
|
343
|
+
else if (tableEnd === -1) {
|
|
344
|
+
if (bare.startsWith("|")) {
|
|
345
|
+
if (tableStart === -1)
|
|
346
|
+
tableStart = offset;
|
|
347
|
+
const cells = splitRow(bare);
|
|
348
|
+
const separator = cells.length > 0 && cells.every((c) => /^:?-+:?$/.test(c));
|
|
349
|
+
if (tableStart !== offset && !separator) {
|
|
350
|
+
const rowPath = cells.length > 0 ? cellPath(cells[0]) : null;
|
|
351
|
+
if (rowPath === null)
|
|
352
|
+
unparsed.push(bare);
|
|
353
|
+
else {
|
|
354
|
+
const rest = cells.slice(1).filter((c) => c !== "");
|
|
355
|
+
rows.push({ path: rowPath, scope: rest[rest.length - 1] ?? "" });
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
needsEol = !line.endsWith("\n");
|
|
359
|
+
// The table ends at the first non-table line, so keep scanning.
|
|
360
|
+
offset = lineEnd;
|
|
361
|
+
continue;
|
|
362
|
+
}
|
|
363
|
+
else if (tableStart !== -1) {
|
|
364
|
+
tableEnd = offset;
|
|
365
|
+
}
|
|
366
|
+
else if (bare.startsWith("## ")) {
|
|
367
|
+
break;
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
offset = lineEnd;
|
|
371
|
+
}
|
|
372
|
+
if (!headingSeen || tableStart === -1) {
|
|
373
|
+
return {
|
|
374
|
+
status: "unreadable",
|
|
375
|
+
reason: "no `## Project Documents` heading with a table below the closing `bkit:end`",
|
|
376
|
+
};
|
|
377
|
+
}
|
|
378
|
+
if (tableEnd === -1)
|
|
379
|
+
tableEnd = offset;
|
|
380
|
+
return { status: "ok", text, eol, rows, unparsed, insertAt: tableEnd, needsEol };
|
|
381
|
+
}
|
|
382
|
+
/** Row text for a project document, in the table's column order. */
|
|
383
|
+
export function projectDocRow(topic) {
|
|
384
|
+
const info = TOPIC_INFO[topic];
|
|
385
|
+
return `| \`${projectDocPath(topic)}\` | ${info.phases.join(" | ")} | ${info.scope} |`;
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* The indexed document that already covers `topic` at another path: a same-basename row, or a
|
|
389
|
+
* row whose Scope affirms the recommended path as its equivalent (`Equivalent to docs/x.md`).
|
|
390
|
+
*/
|
|
391
|
+
export function findIndexedEquivalent(rows, topic, usable = () => true) {
|
|
392
|
+
return listIndexedEquivalents(rows, topic).find(usable) ?? null;
|
|
393
|
+
}
|
|
394
|
+
/** Every indexed row that claims to cover `topic` at another path, in table order. */
|
|
395
|
+
export function listIndexedEquivalents(rows, topic) {
|
|
396
|
+
const recommended = projectDocPath(topic);
|
|
397
|
+
const base = `${topic}.md`;
|
|
398
|
+
// Affirmative only (no `not` / `non` before it), and the path ends at a non-word character,
|
|
399
|
+
// so `docs/x.mdx` and `docs/x.md.bak` name no equivalent.
|
|
400
|
+
const mentions = new RegExp(`(?<!\\b(?:not|non)[-\\s]*)equivalent\\s+to\\s+\`?${recommended.replace(".", "\\.")}(?![\\w-]|\\.\\w)`, "i");
|
|
401
|
+
const found = [];
|
|
402
|
+
for (const row of rows) {
|
|
403
|
+
if (row.path === recommended)
|
|
404
|
+
continue;
|
|
405
|
+
if (path.posix.basename(row.path) === base || mentions.test(row.scope))
|
|
406
|
+
found.push(row.path);
|
|
407
|
+
}
|
|
408
|
+
return found;
|
|
409
|
+
}
|
|
410
|
+
/**
|
|
411
|
+
* Where the project keeps its copy of `topic`'s starter: the recommended path when it is a
|
|
412
|
+
* regular file, else the indexed equivalent that is an in-tree regular file, else null. A missing
|
|
413
|
+
* or unreadable index leaves only the recommended-path check.
|
|
414
|
+
*/
|
|
415
|
+
export function adoptedProjectDocPath(root, topic) {
|
|
416
|
+
const recommended = projectDocPath(topic);
|
|
417
|
+
if (inspectRepoFile(root, recommended) === "regular")
|
|
418
|
+
return recommended;
|
|
419
|
+
const index = readProjectIndex(root);
|
|
420
|
+
if (index.status !== "ok")
|
|
421
|
+
return null;
|
|
422
|
+
return findIndexedEquivalent(index.rows, topic, (rel) => isInTreePath(rel) && inspectRepoFile(root, rel) === "regular");
|
|
423
|
+
}
|
|
424
|
+
const PROBLEM_TEXT = {
|
|
425
|
+
"missing-partner": "one of `bkit:start` / `bkit:end` is missing",
|
|
426
|
+
inverted: "`bkit:end` comes before `bkit:start`",
|
|
427
|
+
multiple: "more than one `bkit:start` / `bkit:end` marker",
|
|
428
|
+
"inside-fence": "a marker line sits inside a code fence",
|
|
429
|
+
"multiple-notices": "more than one generated `bkit:managed` notice",
|
|
430
|
+
};
|
|
431
|
+
/**
|
|
432
|
+
* Bring the project documents under the project's ownership and into its index, for install
|
|
433
|
+
* and upgrade. Per present default document:
|
|
434
|
+
* 1. a legacy `bkit:start` / `bkit:end` wrapper and its `bkit:managed` notice are removed,
|
|
435
|
+
* every other byte kept; an unclear wrapper is left as it is and reported;
|
|
436
|
+
* 2. the path gets a `Project Documents` row when no row names that exact path, unless a
|
|
437
|
+
* different indexed document already covers the topic. A document migrated in this run
|
|
438
|
+
* gets its own row either way.
|
|
439
|
+
* Missing documents stay missing. An index that cannot be read as a table is left untouched and
|
|
440
|
+
* reported. A dry run writes nothing and prints what a real run would do. Safe to repeat.
|
|
441
|
+
*/
|
|
442
|
+
export function syncProjectDocs(root, opts) {
|
|
443
|
+
const report = {
|
|
444
|
+
migrated: [],
|
|
445
|
+
ambiguous: [],
|
|
446
|
+
unsafe: [],
|
|
447
|
+
registered: [],
|
|
448
|
+
equivalent: [],
|
|
449
|
+
indexProblem: null,
|
|
450
|
+
};
|
|
451
|
+
const tag = opts.dryRun ? "[dry-run] " : "";
|
|
452
|
+
const present = [];
|
|
453
|
+
for (const topic of PROJECT_DOC_TOPICS) {
|
|
454
|
+
const rel = projectDocPath(topic);
|
|
455
|
+
const state = inspectRepoFile(root, rel);
|
|
456
|
+
if (state === "absent")
|
|
457
|
+
continue;
|
|
458
|
+
if (state !== "regular") {
|
|
459
|
+
report.unsafe.push({ path: rel, reason: state.unsafe });
|
|
460
|
+
continue;
|
|
461
|
+
}
|
|
462
|
+
const abs = path.join(root, rel);
|
|
463
|
+
try {
|
|
464
|
+
const before = fs.readFileSync(abs, "utf-8");
|
|
465
|
+
const result = stripManagedWrapper(before);
|
|
466
|
+
present.push(topic);
|
|
467
|
+
if (result.status === "ambiguous") {
|
|
468
|
+
report.ambiguous.push({ path: rel, problem: result.problem });
|
|
469
|
+
}
|
|
470
|
+
else if (result.status === "removed") {
|
|
471
|
+
if (!opts.dryRun)
|
|
472
|
+
fs.writeFileSync(abs, result.content, "utf-8");
|
|
473
|
+
report.migrated.push(rel);
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
catch (error) {
|
|
477
|
+
const at = present.indexOf(topic);
|
|
478
|
+
if (at !== -1)
|
|
479
|
+
present.splice(at, 1);
|
|
480
|
+
report.unsafe.push({
|
|
481
|
+
path: rel,
|
|
482
|
+
reason: `it could not be read or written (${errorReason(error)})`,
|
|
483
|
+
});
|
|
484
|
+
}
|
|
485
|
+
}
|
|
486
|
+
let index = readProjectIndex(root);
|
|
487
|
+
const edits = [];
|
|
488
|
+
const migrated = new Set(report.migrated);
|
|
489
|
+
for (const topic of present) {
|
|
490
|
+
const rel = projectDocPath(topic);
|
|
491
|
+
if (report.ambiguous.some((a) => a.path === rel))
|
|
492
|
+
continue;
|
|
493
|
+
if (index.status === "ok") {
|
|
494
|
+
if (index.rows.some((r) => r.path === rel))
|
|
495
|
+
continue;
|
|
496
|
+
const indexed = findIndexedEquivalent(index.rows, topic, (row) => isInTreePath(row) && inspectRepoFile(root, row) === "regular");
|
|
497
|
+
if (indexed !== null && !migrated.has(rel)) {
|
|
498
|
+
report.equivalent.push({ path: rel, indexed });
|
|
499
|
+
continue;
|
|
500
|
+
}
|
|
501
|
+
}
|
|
502
|
+
edits.push(rel);
|
|
503
|
+
}
|
|
504
|
+
if (edits.length > 0) {
|
|
505
|
+
if (index.status !== "ok") {
|
|
506
|
+
report.indexProblem =
|
|
507
|
+
index.status === "missing"
|
|
508
|
+
? `${PROJECT_INDEX_PATH} does not exist`
|
|
509
|
+
: `${PROJECT_INDEX_PATH} has no readable Project Documents table (${index.reason})`;
|
|
510
|
+
}
|
|
511
|
+
else if ((index.unparsed ?? []).length > 0) {
|
|
512
|
+
report.indexProblem = `${PROJECT_INDEX_PATH} has a Project Documents row bkit cannot read (${(index.unparsed ?? [])[0].slice(0, 80)}), so it may already list the document`;
|
|
513
|
+
}
|
|
514
|
+
else {
|
|
515
|
+
const rows = edits.map((rel) => projectDocRow(topicOfPath(rel)));
|
|
516
|
+
const insertion = (index.needsEol ? index.eol : "") + rows.join(index.eol) + index.eol;
|
|
517
|
+
const next = index.text.slice(0, index.insertAt) + insertion + index.text.slice(index.insertAt);
|
|
518
|
+
try {
|
|
519
|
+
if (!opts.dryRun)
|
|
520
|
+
fs.writeFileSync(path.join(root, PROJECT_INDEX_PATH), next, "utf-8");
|
|
521
|
+
report.registered.push(...edits);
|
|
522
|
+
index = { ...index, text: next };
|
|
523
|
+
}
|
|
524
|
+
catch (error) {
|
|
525
|
+
report.indexProblem = `${PROJECT_INDEX_PATH} could not be written (${errorReason(error)})`;
|
|
526
|
+
}
|
|
527
|
+
}
|
|
528
|
+
}
|
|
529
|
+
logReport(report, tag);
|
|
530
|
+
return report;
|
|
531
|
+
}
|
|
532
|
+
function logReport(report, tag) {
|
|
533
|
+
for (const rel of report.migrated) {
|
|
534
|
+
console.log(`${LOG_PREFIX} ${tag}migrate: ${rel} — removed the bkit ownership wrapper, now a project document (text inside and outside the wrapper kept)`);
|
|
535
|
+
}
|
|
536
|
+
for (const rel of report.registered) {
|
|
537
|
+
console.log(`${LOG_PREFIX} ${tag}register: ${rel} in ${PROJECT_INDEX_PATH} (Project Documents)`);
|
|
538
|
+
}
|
|
539
|
+
for (const e of report.equivalent) {
|
|
540
|
+
console.log(`${LOG_PREFIX} ${tag}skip: ${e.path} — ${PROJECT_INDEX_PATH} already lists ${e.indexed} for this topic, so no row was added. Add a row by hand if both documents matter.`);
|
|
541
|
+
}
|
|
542
|
+
for (const a of report.ambiguous) {
|
|
543
|
+
console.warn(`${LOG_PREFIX} ${a.path}: left as it is — ${PROBLEM_TEXT[a.problem]}, so bkit cannot tell its wrapper from your text. Delete any \`bkit:start\` / \`bkit:end\` / \`bkit:managed\` lines by hand; the file is yours.`);
|
|
544
|
+
}
|
|
545
|
+
for (const u of report.unsafe) {
|
|
546
|
+
console.warn(`${LOG_PREFIX} ${u.path}: skipped — ${u.reason}. bkit neither reads nor indexes it.`);
|
|
547
|
+
}
|
|
548
|
+
if (report.indexProblem !== null) {
|
|
549
|
+
console.warn(`${LOG_PREFIX} ${PROJECT_INDEX_PATH}: not edited — ${report.indexProblem}. Add a row for ${report.migrated.length + report.registered.length > 0 ? "each project document" : "the project documents you copied"} under a \`## Project Documents\` table below \`<!-- bkit:end -->\` by hand.`);
|
|
550
|
+
}
|
|
551
|
+
}
|
|
@@ -3,6 +3,9 @@
|
|
|
3
3
|
import * as fs from "node:fs";
|
|
4
4
|
import * as path from "node:path";
|
|
5
5
|
import { NPM_STRIP_REMAP, getPkgRoot, getTemplatesRoot, TEMPLATE_COPIES_DIR, } from "../shared/package-roots.js";
|
|
6
|
+
import { hasLintStagedConfig } from "../checks/tips/detect.js";
|
|
7
|
+
import { readDependencyNames, readPackageJson } from "../shared/package-json.js";
|
|
8
|
+
import { adoptedProjectDocPath, inspectRepoFile, PROJECT_DOC_TOPICS, } from "./project-docs.js";
|
|
6
9
|
export function listFilesRecursive(dir) {
|
|
7
10
|
if (!fs.existsSync(dir))
|
|
8
11
|
return [];
|
|
@@ -95,19 +98,39 @@ export const TEMPLATES_POINTER = "Templates (adopt, do not skip): read .bkit/tem
|
|
|
95
98
|
export const TEMPLATE_CHANGE_CONSEQUENCES = {
|
|
96
99
|
"slop-scan.config.json": "your adopted copy's guardrails exemptions are now stale; your slop gate may go red",
|
|
97
100
|
};
|
|
98
|
-
/**
|
|
99
|
-
function
|
|
101
|
+
/** Where the project keeps its copy of a changed `docs/{topic}.md` starter, or null. */
|
|
102
|
+
function adoptedDocCopy(rel, cwd) {
|
|
103
|
+
const match = /^docs\/([^/]+)\.md$/.exec(rel);
|
|
104
|
+
if (match === null)
|
|
105
|
+
return null;
|
|
106
|
+
const topic = match[1];
|
|
107
|
+
if (topic === "components")
|
|
108
|
+
return inspectRepoFile(cwd, rel) === "regular" ? rel : null;
|
|
109
|
+
return PROJECT_DOC_TOPICS.includes(topic)
|
|
110
|
+
? adoptedProjectDocPath(cwd, topic)
|
|
111
|
+
: null;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* ` changed: <dest>`, plus the consequence when that template's adopted copy backs a gate, and
|
|
115
|
+
* `adopted at <path>, review your copy` when the project keeps a copy of a changed doc starter.
|
|
116
|
+
*/
|
|
117
|
+
function formatChangedLine(rel, cwd) {
|
|
100
118
|
const line = ` changed: ${path.join(TEMPLATE_COPIES_DIR, rel)}`;
|
|
101
119
|
const note = TEMPLATE_CHANGE_CONSEQUENCES[rel];
|
|
102
|
-
|
|
120
|
+
const adopted = adoptedDocCopy(rel, cwd);
|
|
121
|
+
const parts = [
|
|
122
|
+
...(note === undefined ? [] : [note]),
|
|
123
|
+
...(adopted === null ? [] : [`adopted at ${adopted}, review your copy`]),
|
|
124
|
+
];
|
|
125
|
+
return parts.length === 0 ? line : `${line} \u2014 ${parts.join("; ")}`;
|
|
103
126
|
}
|
|
104
127
|
/**
|
|
105
128
|
* The upgrade report for a template sync: one line per changed, added or removed
|
|
106
129
|
* template, then where to read about adopting them. Empty when nothing changed.
|
|
107
130
|
*/
|
|
108
|
-
export function formatTemplateChanges(changes) {
|
|
131
|
+
export function formatTemplateChanges(changes, cwd) {
|
|
109
132
|
const lines = [
|
|
110
|
-
...changes.changed.map(formatChangedLine),
|
|
133
|
+
...changes.changed.map((rel) => formatChangedLine(rel, cwd)),
|
|
111
134
|
...changes.added.map((p) => ` added: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
|
|
112
135
|
...changes.removed.map((p) => ` removed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
|
|
113
136
|
];
|
|
@@ -119,3 +142,30 @@ export function formatTemplateChanges(changes) {
|
|
|
119
142
|
TEMPLATES_POINTER,
|
|
120
143
|
].join("\n");
|
|
121
144
|
}
|
|
145
|
+
/** The line install, check and upgrade print after their log prefix when a gating lint-staged has no config to read. */
|
|
146
|
+
export const MISSING_LINT_STAGED_CONFIG_LINE = "no root lint-staged config — commits will fail. Fix: cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json";
|
|
147
|
+
// True when `bkit:gate:format` runs `lint-staged` without a `--config` / `-c` path.
|
|
148
|
+
function formatGateRunsBareLintStaged(cwd) {
|
|
149
|
+
const pkg = readPackageJson(cwd);
|
|
150
|
+
const scripts = pkg.ok ? pkg.pkg.scripts : undefined;
|
|
151
|
+
const format = scripts?.["bkit:gate:format"];
|
|
152
|
+
if (typeof format !== "string" || !/\blint-staged\b/.test(format))
|
|
153
|
+
return false;
|
|
154
|
+
return !/(?:^|\s)(?:--config(?:[=\s]|$)|-c(?:[=\s]|$))/.test(format);
|
|
155
|
+
}
|
|
156
|
+
// bkit writes no lint-staged config into a consumer repo. When the format gate runs lint-staged
|
|
157
|
+
// bare, lint-staged is installed and no config exists, the commit hook fails: print the one-line
|
|
158
|
+
// fix after the calling command's `logPrefix`. Prints in a dry run too; writes nothing. Returns
|
|
159
|
+
// true when it printed. No-op in dogfood.
|
|
160
|
+
export function warnMissingLintStagedConfig(cwd, logPrefix) {
|
|
161
|
+
if (path.resolve(cwd) === getPkgRoot())
|
|
162
|
+
return false;
|
|
163
|
+
if (!formatGateRunsBareLintStaged(cwd))
|
|
164
|
+
return false;
|
|
165
|
+
if (!readDependencyNames(cwd).includes("lint-staged"))
|
|
166
|
+
return false;
|
|
167
|
+
if (hasLintStagedConfig(cwd))
|
|
168
|
+
return false;
|
|
169
|
+
console.log(`${logPrefix} ${MISSING_LINT_STAGED_CONFIG_LINE}`);
|
|
170
|
+
return true;
|
|
171
|
+
}
|