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