@cbartens/bkit 5.2.3 → 5.2.4
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 +4 -2
- package/.bkit/core/.bkit/README.md +3 -1
- package/.bkit/core/.bkit/install.md +3 -3
- package/.bkit/core/.bkit/prompts.md +1 -1
- package/.bkit/core/.bkit/templates.md +19 -1
- package/.bkit/core/.bkit/workflows.md +7 -2
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-llm.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-security.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
- package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -2
- package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +10 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +9 -10
- package/.bkit/core/engine/commands/workflow/branches.ts +61 -7
- package/.bkit/core/engine/commands/workflow/repo.ts +16 -2
- package/.bkit/core/engine/commands/workflow/workflows.ts +4 -3
- package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
- package/.bkit/core/engine/shared/timeouts.ts +6 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +6 -4
- package/.bkit/core/workflows/bkit-build.md +1 -1
- package/.bkit/core/workflows/bkit-debug.md +1 -1
- package/.bkit/core/workflows/bkit-design.md +1 -1
- package/.bkit/core/workflows/bkit-plan.md +1 -1
- package/.bkit/core/workflows/bkit-ship.md +1 -1
- package/.bkit/templates/.husky/pre-push +7 -0
- package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
- package/CHANGELOG.md +17 -0
- package/dist/checks/tips/catalogue.js +9 -0
- package/dist/commands/install/upgrade.js +9 -10
- package/dist/commands/workflow/branches.js +54 -8
- package/dist/commands/workflow/repo.js +14 -2
- package/dist/commands/workflow/workflows.js +4 -3
- package/dist/shared/bkit-latest.js +150 -0
- package/dist/shared/timeouts.js +6 -0
- package/package.json +1 -1
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
// bkit-latest — is the bkit this repo rendered its workflows and audit templates
|
|
2
|
+
// from behind the newest published release?
|
|
3
|
+
//
|
|
4
|
+
// `bkit repo info` (every phase workflow's Step 1) and the anchor stamp on every
|
|
5
|
+
// audit report, design and plan report it, so a run on outdated workflow /
|
|
6
|
+
// template text says so. Advisory only: no registry answer means `latest`
|
|
7
|
+
// is null and nothing is printed, never an error. The registry answer is kept in
|
|
8
|
+
// the git common dir (shared by every worktree, never committed) so parallel runs
|
|
9
|
+
// ask npm at most once a day.
|
|
10
|
+
|
|
11
|
+
import { spawnSync } from "node:child_process";
|
|
12
|
+
import * as fs from "node:fs";
|
|
13
|
+
import * as path from "node:path";
|
|
14
|
+
|
|
15
|
+
import { readBkitVersion } from "../install/version-file.js";
|
|
16
|
+
import { parseJson } from "./json.js";
|
|
17
|
+
import { PACKAGE_RUNNER } from "./package-manager.js";
|
|
18
|
+
import { TIMEOUTS } from "./timeouts.js";
|
|
19
|
+
|
|
20
|
+
export const BKIT_PACKAGE = "@cbartens/bkit";
|
|
21
|
+
/** Cache file name inside the git common dir. */
|
|
22
|
+
export const BKIT_LATEST_CACHE = "bkit-latest-version.json";
|
|
23
|
+
/** Set to anything but `0` / empty to skip the registry lookup (air-gapped machines, CI). */
|
|
24
|
+
export const NO_UPDATE_CHECK_ENV = "BKIT_NO_UPDATE_CHECK";
|
|
25
|
+
|
|
26
|
+
const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
|
|
27
|
+
|
|
28
|
+
/** Order of two prerelease identifier lists per semver §11: numeric < alphanumeric, shorter < longer. */
|
|
29
|
+
function comparePrerelease(a: string[], b: string[]): number {
|
|
30
|
+
for (let i = 0; i < Math.max(a.length, b.length); i++) {
|
|
31
|
+
const x = a[i];
|
|
32
|
+
const y = b[i];
|
|
33
|
+
if (x === undefined) return -1;
|
|
34
|
+
if (y === undefined) return 1;
|
|
35
|
+
const xn = /^\d+$/.test(x);
|
|
36
|
+
const yn = /^\d+$/.test(y);
|
|
37
|
+
if (xn && yn) {
|
|
38
|
+
if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
|
|
39
|
+
} else if (xn !== yn) {
|
|
40
|
+
return xn ? -1 : 1;
|
|
41
|
+
} else if (x !== y) {
|
|
42
|
+
return x < y ? -1 : 1;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
return 0;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* -1 / 0 / 1 for `a` older / equal / newer than `b`, compared as numbers (so 5.10.0
|
|
50
|
+
* is newer than 5.9.0) and with a prerelease older than its release. null when
|
|
51
|
+
* either is not a semver.
|
|
52
|
+
*/
|
|
53
|
+
export function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
|
|
54
|
+
const ma = SEMVER_RE.exec(a.trim());
|
|
55
|
+
const mb = SEMVER_RE.exec(b.trim());
|
|
56
|
+
if (!ma || !mb) return null;
|
|
57
|
+
for (let i = 1; i <= 3; i++) {
|
|
58
|
+
const x = Number(ma[i]);
|
|
59
|
+
const y = Number(mb[i]);
|
|
60
|
+
if (x !== y) return x < y ? -1 : 1;
|
|
61
|
+
}
|
|
62
|
+
const pa = ma[4];
|
|
63
|
+
const pb = mb[4];
|
|
64
|
+
if (pa === undefined && pb === undefined) return 0;
|
|
65
|
+
if (pa === undefined) return 1;
|
|
66
|
+
if (pb === undefined) return -1;
|
|
67
|
+
const c = comparePrerelease(pa.split("."), pb.split("."));
|
|
68
|
+
return c === 0 ? 0 : c < 0 ? -1 : 1;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** The newest published bkit per the registry, or null on any failure (offline, timeout, no pnpm). */
|
|
72
|
+
export function lookupLatestPublished(
|
|
73
|
+
cwd: string,
|
|
74
|
+
timeoutS: number | null = TIMEOUTS.BKIT_LATEST_LOOKUP_TIMEOUT_S,
|
|
75
|
+
): string | null {
|
|
76
|
+
const res = spawnSync(PACKAGE_RUNNER, ["view", BKIT_PACKAGE, "version"], {
|
|
77
|
+
cwd,
|
|
78
|
+
encoding: "utf-8",
|
|
79
|
+
...(timeoutS === null ? {} : { timeout: timeoutS * 1000 }),
|
|
80
|
+
});
|
|
81
|
+
if (res.error || res.status !== 0) return null;
|
|
82
|
+
const version = (res.stdout ?? "").trim().replace(/^v/, "");
|
|
83
|
+
return SEMVER_RE.test(version) ? version : null;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export interface BkitVersionStatus {
|
|
87
|
+
/** `.bkit/version` `pinnedVersion`: the release this repo's bkit files were rendered from. */
|
|
88
|
+
version: string | null;
|
|
89
|
+
/** Newest published release, or null when unknown (offline, opted out, no pin to compare). */
|
|
90
|
+
latest: string | null;
|
|
91
|
+
/** true when `version` is older than `latest`; null when either is unknown. */
|
|
92
|
+
outdated: boolean | null;
|
|
93
|
+
/** One line to show the user when outdated, else null. */
|
|
94
|
+
advisory: string | null;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
export interface BkitLatestDeps {
|
|
98
|
+
now?: () => number;
|
|
99
|
+
lookup?: (cwd: string) => string | null;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The cached registry answer when still fresh: a version, or null for a remembered failure. */
|
|
103
|
+
function readCache(file: string, now: number): { latest: string | null } | undefined {
|
|
104
|
+
if (!fs.existsSync(file)) return undefined;
|
|
105
|
+
const parsed = parseJson(fs.readFileSync(file, "utf-8"));
|
|
106
|
+
if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null) return undefined;
|
|
107
|
+
const { latest, checkedAt } = parsed.value as { latest?: unknown; checkedAt?: unknown };
|
|
108
|
+
if (typeof checkedAt !== "number") return undefined;
|
|
109
|
+
const value = typeof latest === "string" && SEMVER_RE.test(latest) ? latest : null;
|
|
110
|
+
const ttl = value === null ? TIMEOUTS.BKIT_LATEST_RETRY_S : TIMEOUTS.BKIT_LATEST_CACHE_S;
|
|
111
|
+
return now - checkedAt < ttl * 1000 && now >= checkedAt ? { latest: value } : undefined;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Remember the registry answer; a cache that cannot be written only costs a lookup next run. */
|
|
115
|
+
function writeCache(file: string, latest: string | null, now: number): void {
|
|
116
|
+
const tmp = `${file}.${process.pid}.tmp`;
|
|
117
|
+
try {
|
|
118
|
+
fs.writeFileSync(tmp, `${JSON.stringify({ latest, checkedAt: now })}\n`);
|
|
119
|
+
fs.renameSync(tmp, file);
|
|
120
|
+
} catch {
|
|
121
|
+
// Read-only git dir: the next run asks the registry again, nothing else changes.
|
|
122
|
+
fs.rmSync(tmp, { force: true });
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Whether this repo's bkit is behind the newest release. `gitCommonDir` holds the
|
|
128
|
+
* once-a-day cache; null (not a git repo) skips the cache, not the check.
|
|
129
|
+
*/
|
|
130
|
+
export function bkitVersionStatus(
|
|
131
|
+
root: string,
|
|
132
|
+
gitCommonDir: string | null,
|
|
133
|
+
deps: BkitLatestDeps = {},
|
|
134
|
+
): BkitVersionStatus {
|
|
135
|
+
const version = readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || null;
|
|
136
|
+
const unknown = { version, latest: null, outdated: null, advisory: null };
|
|
137
|
+
if (version === null) return unknown;
|
|
138
|
+
const optOut = process.env[NO_UPDATE_CHECK_ENV];
|
|
139
|
+
if (optOut !== undefined && optOut !== "" && optOut !== "0") return unknown;
|
|
140
|
+
|
|
141
|
+
const now = (deps.now ?? Date.now)();
|
|
142
|
+
const cacheFile = gitCommonDir === null ? null : path.join(gitCommonDir, BKIT_LATEST_CACHE);
|
|
143
|
+
let latest: string | null;
|
|
144
|
+
const cached = cacheFile === null ? undefined : readCache(cacheFile, now);
|
|
145
|
+
if (cached !== undefined) {
|
|
146
|
+
latest = cached.latest;
|
|
147
|
+
} else {
|
|
148
|
+
latest = (deps.lookup ?? lookupLatestPublished)(root);
|
|
149
|
+
if (cacheFile !== null) writeCache(cacheFile, latest, now);
|
|
150
|
+
}
|
|
151
|
+
if (latest === null) return unknown;
|
|
152
|
+
|
|
153
|
+
const order = compareSemver(version, latest);
|
|
154
|
+
if (order === null) return { version, latest, outdated: null, advisory: null };
|
|
155
|
+
const outdated = order < 0;
|
|
156
|
+
return {
|
|
157
|
+
version,
|
|
158
|
+
latest,
|
|
159
|
+
outdated,
|
|
160
|
+
advisory: outdated
|
|
161
|
+
? `running bkit ${version}; ${latest} is out. Upgrade: ${PACKAGE_RUNNER} bkit upgrade --latest`
|
|
162
|
+
: null,
|
|
163
|
+
};
|
|
164
|
+
}
|
|
@@ -17,4 +17,10 @@ export const TIMEOUTS = {
|
|
|
17
17
|
SHIP_DEV_LOCK_STALE_S: 900,
|
|
18
18
|
/** Seconds to contend for `.dev.lock` before giving up. */
|
|
19
19
|
SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S: 600,
|
|
20
|
+
/** Seconds a registry answer for the newest published bkit is reused before asking again. */
|
|
21
|
+
BKIT_LATEST_CACHE_S: 86400,
|
|
22
|
+
/** Seconds a failed registry lookup is remembered, so an offline run does not wait on every call. */
|
|
23
|
+
BKIT_LATEST_RETRY_S: 3600,
|
|
24
|
+
/** Seconds the registry lookup may take before it counts as failed. */
|
|
25
|
+
BKIT_LATEST_LOOKUP_TIMEOUT_S: 5,
|
|
20
26
|
} as const;
|
|
@@ -45,7 +45,7 @@ maxTurns: 300
|
|
|
45
45
|
```bash
|
|
46
46
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" branches anchor-stamp --file="<Create>" --base-sha="$(git rev-parse HEAD)" --base-ref="$(git rev-parse --abbrev-ref HEAD)"
|
|
47
47
|
```
|
|
48
|
-
Never hand-write or edit the `bkit:anchor` block.
|
|
48
|
+
Never hand-write or edit the `bkit:anchor` block or the `bkit:outdated` line the stamp writes under it.
|
|
49
49
|
3. Re-read all supplied inputs once at session start; do not trust session memory.
|
|
50
50
|
4. Read `.agents/docs.md` → load docs for workflow / step / task; skip missing.
|
|
51
51
|
5. Update **Create** — replace each `PENDING` via `Edit` as content becomes available; **If** none → `None`.
|
|
@@ -53,18 +53,20 @@ maxTurns: 300
|
|
|
53
53
|
- `Project Instructions` bullets extend or override `Universal Instructions` section or `Probe Steps` with same titles; never override template `Rules`. **If** absent or empty → run `Universal Instructions` alone.
|
|
54
54
|
- Bash only for step 2 stamp and probes template or its `Project Instructions` name.
|
|
55
55
|
7. Populate `Pre-Flight / Dependencies`.
|
|
56
|
-
- **If** `Permissions` blocked any call → STOP before `Probe Steps`; output only each blocked call with its narrow allow rule and `Grant these and resume me, or resume me with: continue`. **If** resumed → re-probe those calls once; run on with remaining gaps named.
|
|
57
56
|
8. Populate `Probe Steps`:
|
|
58
57
|
- Tick steps `[x]` only once their `Done when` holds against repo.
|
|
59
58
|
- **If** surfaces absent → tick with explicit skip and evidence of absence; record where steps say, **Else** → `Checked`. Do not invent findings for absent surfaces.
|
|
60
59
|
9. Populate `Findings`; ID `{slug}-{n}`.
|
|
61
60
|
10. Populate `Report` from steps that feed each section.
|
|
61
|
+
- `Suggested Issues`: group `Findings` into issues to create; one row = one change landed in one go. Group by shared root cause, then module, then fix; never by severity alone. Every `MEDIUM`+ finding in exactly one row; `LOW` findings optional, batched into one row. `Findings` = finding IDs; `Severity` = highest of its findings; `Title` = the fix, imperative.
|
|
62
|
+
- `Next Step`, first match wins: change outside the repo (dashboard, tracker, vendor setting) → `manual`; failing test / CI / runtime, cause unknown → `/bkit-debug`; approach open (options, trade-offs, unanswered questions) → `/bkit-design`; approach settled, not broken into tasks → `/bkit-plan`; change clear → `/bkit-build`. **If** `.agents/shortcuts.md` § When to use allows a shortcut → `/bkit-build` becomes `shortcut:build`; `/bkit-debug` becomes `shortcut:debug`. `Reason` = the deciding fact, one clause.
|
|
62
63
|
11. Write ledger entries to `docs/failures.jsonl` per `.bkit/jsonl.md`; `workflow: "audit"`, `step: "audit-{slug}"`. **If** template audits `docs/failures.jsonl` or `docs/deferrals.jsonl` → skip step.
|
|
63
64
|
- Report complete first. Template read-only rules cover audited surfaces, not this append.
|
|
64
|
-
- Open rows
|
|
65
|
+
- Open rows = fold by `key`, highest `ts` wins, `status` != `CLOSED`; every `key`, whichever workflow wrote it.
|
|
66
|
+
- Same problem = same `file:line`, test title, or error signature.
|
|
65
67
|
- Per finding `MEDIUM`+: open row names same problem → reuse its `key`. **Else** → new `key` `audit-{slug}-{content-slug}`, never the finding ID.
|
|
66
68
|
- Per finding `LOW`: open row names same problem → same `key`, `severity: "LOW"`. **Else** → no row.
|
|
67
|
-
- Per open row no finding matches: surface checked this run → `CLOSED`. **Else** → leave open.
|
|
69
|
+
- Per open row with `key` prefix `audit-{slug}-` no finding matches: surface checked this run → `CLOSED`. **Else** → leave open. never close rows under other `key` prefixes.
|
|
68
70
|
- `description` names `file:line`; `references` = report path, finding ID, audited `baseSha`.
|
|
69
71
|
- Final message: per appended row `key`, `severity`, `status`. **If** none → `None`.
|
|
70
72
|
12. Refine `Project Instructions` section in place; never edit template above `<!-- bkit:end -->`. **If** heading missing → append `## Project Instructions`:
|
|
@@ -89,7 +89,7 @@ description: "Build Feature — Autonomous implementation"
|
|
|
89
89
|
```bash
|
|
90
90
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
91
91
|
```
|
|
92
|
-
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `behindDev` as `{BEHIND_DEV}`, `divergedAgo` as `{DIVERGED_AGO}`.
|
|
92
|
+
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `behindDev` as `{BEHIND_DEV}`, `divergedAgo` as `{DIVERGED_AGO}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-build] {BKIT_ADVISORY}`.
|
|
93
93
|
2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
|
|
94
94
|
<!-- bkit:tracker github start -->
|
|
95
95
|
Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
|
|
@@ -90,7 +90,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
90
90
|
```bash
|
|
91
91
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
92
92
|
```
|
|
93
|
-
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`.
|
|
93
|
+
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-debug] {BKIT_ADVISORY}`.
|
|
94
94
|
2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
|
|
95
95
|
<!-- bkit:tracker github start -->
|
|
96
96
|
Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
|
|
@@ -74,7 +74,7 @@ description: "Design Feature — Autonomous design phase"
|
|
|
74
74
|
```bash
|
|
75
75
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
76
76
|
```
|
|
77
|
-
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`.
|
|
77
|
+
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-design] {BKIT_ADVISORY}`.
|
|
78
78
|
2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
|
|
79
79
|
<!-- bkit:tracker github start -->
|
|
80
80
|
Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
|
|
@@ -74,7 +74,7 @@ description: "Plan Feature — Autonomous plan generation"
|
|
|
74
74
|
```bash
|
|
75
75
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
76
76
|
```
|
|
77
|
-
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`.
|
|
77
|
+
Hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-plan] {BKIT_ADVISORY}`.
|
|
78
78
|
2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
|
|
79
79
|
<!-- bkit:tracker github start -->
|
|
80
80
|
Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
|
|
@@ -86,7 +86,7 @@ description: "Ship Feature — Autonomous merge and archive"
|
|
|
86
86
|
```bash
|
|
87
87
|
"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit" repo info --fetch
|
|
88
88
|
```
|
|
89
|
-
→ hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`.
|
|
89
|
+
→ hold `bkit` as `{BKIT}`, `ownerRepo` as `{OWNER_REPO}`, `owner` as `{OWNER}`, `repo` as `{REPO}`, `branch` as initial `{BRANCH}`, `repoRoot` as `{REPO_ROOT}`, `outboxRoot` as `{OUTBOX_ROOT}`, `bkitAdvisory` as `{BKIT_ADVISORY}`. **If** `BKIT_ADVISORY` != null → emit advisory `[bkit-ship] {BKIT_ADVISORY}`.
|
|
90
90
|
2. **If** `ISSUE_ID` already set by AGENTS.md → skip. **Else**:
|
|
91
91
|
<!-- bkit:tracker github start -->
|
|
92
92
|
Extract from session prompt: `<id>{N}</id>`, `<github_issue>{N}</github_issue>`, `GitHub issue: #{N}`, `ISSUE-{N}`, or bare `#{N}` → numeric N → `ISSUE_ID`. **If** no `ID` found → log `No issue ID in the session prompt.` never create a tracker issue. → **STOP**, no further downstream steps.
|
|
@@ -73,6 +73,13 @@ case "$BRANCH" in
|
|
|
73
73
|
;;
|
|
74
74
|
esac
|
|
75
75
|
|
|
76
|
+
# tmp/ prune — deletes files under tmp/ untouched for 7+ days. Not a gate: a failed
|
|
77
|
+
# prune warns and the push goes on. Skipped until scripts/cleanup/ holds the script.
|
|
78
|
+
if [ -f scripts/cleanup/bkit-tmp-prune.mjs ]; then
|
|
79
|
+
node scripts/cleanup/bkit-tmp-prune.mjs --days=7 < /dev/null ||
|
|
80
|
+
echo "[pre-push] WARN: tmp/ prune failed; push continues" >&2
|
|
81
|
+
fi
|
|
82
|
+
|
|
76
83
|
# WHAT each gate runs lives in package.json, not here — the same `bkit:gate*` scripts
|
|
77
84
|
# the bkit agent workflows and prompts dispatch through. Edit the scripts, not this
|
|
78
85
|
# hook. Repo-specific extras go BELOW this block.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Example. Copy into scripts/cleanup/ and own it. bkit install does not write this file
|
|
3
|
+
// and does not overwrite a copy.
|
|
4
|
+
/**
|
|
5
|
+
* bkit-tmp-prune.mjs — deletes files under the checkout's `tmp/` last modified more than
|
|
6
|
+
* `--days` days ago, then the folders that leaves empty.
|
|
7
|
+
*
|
|
8
|
+
* Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree has its own.
|
|
9
|
+
* Symlinks are never followed: a symlinked `tmp/` is left alone; a symlink inside it is
|
|
10
|
+
* aged and removed like a file. A folder goes only when empty and either this sweep
|
|
11
|
+
* emptied it or its own last change is past the cutoff, so a fresh empty folder another
|
|
12
|
+
* process just made stays. An entry another process removes or fills mid-sweep is skipped.
|
|
13
|
+
*
|
|
14
|
+
* Usage: node scripts/cleanup/bkit-tmp-prune.mjs [--days=<n>] (default 7)
|
|
15
|
+
* Exit: 0 = swept or no `tmp/`, 1 = an entry could not be removed, 2 = bad arguments.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { spawnSync } from "node:child_process";
|
|
19
|
+
import fs from "node:fs";
|
|
20
|
+
import path from "node:path";
|
|
21
|
+
import { fileURLToPath } from "node:url";
|
|
22
|
+
|
|
23
|
+
export const DEFAULT_DAYS = 7;
|
|
24
|
+
|
|
25
|
+
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
26
|
+
|
|
27
|
+
/** Codes meaning another process changed the entry mid-sweep: skip it, not a failure. */
|
|
28
|
+
const RACE_CODES = new Set(["ENOENT", "ENOTDIR", "ENOTEMPTY", "EEXIST"]);
|
|
29
|
+
|
|
30
|
+
/** Remove one entry; true when it is gone. */
|
|
31
|
+
function remove(full, isDir, result) {
|
|
32
|
+
try {
|
|
33
|
+
if (isDir) fs.rmdirSync(full);
|
|
34
|
+
else fs.unlinkSync(full);
|
|
35
|
+
} catch (err) {
|
|
36
|
+
if (!RACE_CODES.has(err.code)) result.failed.push(`${full}: ${err.code ?? err.message}`);
|
|
37
|
+
return err.code === "ENOENT";
|
|
38
|
+
}
|
|
39
|
+
if (isDir) result.dirs++;
|
|
40
|
+
else result.files++;
|
|
41
|
+
return true;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Prune `dir`'s contents; true when `dir` itself should go. `stat` is read before the sweep. */
|
|
45
|
+
function sweep(dir, stat, cutoff, result) {
|
|
46
|
+
let names;
|
|
47
|
+
try {
|
|
48
|
+
names = fs.readdirSync(dir);
|
|
49
|
+
} catch (err) {
|
|
50
|
+
if (!RACE_CODES.has(err.code)) result.failed.push(`${dir}: ${err.code ?? err.message}`);
|
|
51
|
+
return false;
|
|
52
|
+
}
|
|
53
|
+
let kept = 0;
|
|
54
|
+
let removed = 0;
|
|
55
|
+
for (const name of names) {
|
|
56
|
+
const full = path.join(dir, name);
|
|
57
|
+
const entry = fs.lstatSync(full, { throwIfNoEntry: false });
|
|
58
|
+
if (!entry) continue;
|
|
59
|
+
const gone = entry.isDirectory()
|
|
60
|
+
? sweep(full, entry, cutoff, result) && remove(full, true, result)
|
|
61
|
+
: entry.mtimeMs < cutoff && remove(full, false, result);
|
|
62
|
+
if (gone) removed++;
|
|
63
|
+
else kept++;
|
|
64
|
+
}
|
|
65
|
+
return kept === 0 && (removed > 0 || stat.mtimeMs < cutoff);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Delete everything under `dir` older than `days` days; `dir` itself always stays.
|
|
70
|
+
* @returns {{ files: number, dirs: number, failed: string[] }}
|
|
71
|
+
*/
|
|
72
|
+
export function pruneTmp(dir, { days = DEFAULT_DAYS, now = Date.now() } = {}) {
|
|
73
|
+
const result = { files: 0, dirs: 0, failed: [] };
|
|
74
|
+
const stat = fs.lstatSync(dir, { throwIfNoEntry: false });
|
|
75
|
+
if (stat?.isDirectory()) sweep(dir, stat, now - days * DAY_MS, result);
|
|
76
|
+
return result;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Top of the checkout the cwd sits in; the cwd itself outside git. */
|
|
80
|
+
function checkoutTop(cwd) {
|
|
81
|
+
const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
|
|
82
|
+
return r.status === 0 ? r.stdout.trim() : cwd;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** `--days=<n>` with n >= 1; null on anything else. */
|
|
86
|
+
export function parseDays(argv) {
|
|
87
|
+
let days = DEFAULT_DAYS;
|
|
88
|
+
for (const arg of argv) {
|
|
89
|
+
const m = /^--days=([1-9]\d*)$/.exec(arg);
|
|
90
|
+
if (!m) return null;
|
|
91
|
+
days = Number(m[1]);
|
|
92
|
+
}
|
|
93
|
+
return days;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export function main(argv, { cwd = process.cwd(), log = console.log, err = console.error } = {}) {
|
|
97
|
+
const days = parseDays(argv);
|
|
98
|
+
if (days === null) {
|
|
99
|
+
err("usage: node scripts/cleanup/bkit-tmp-prune.mjs [--days=<n>] (n >= 1, default 7)");
|
|
100
|
+
return 2;
|
|
101
|
+
}
|
|
102
|
+
const { files, dirs, failed } = pruneTmp(path.join(checkoutTop(cwd), "tmp"), { days });
|
|
103
|
+
if (files + dirs > 0) {
|
|
104
|
+
const n = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
|
|
105
|
+
log(
|
|
106
|
+
`[tmp-prune] removed ${n(files, "file")} and ${n(dirs, "folder")} older than ${n(days, "day")} from tmp/`,
|
|
107
|
+
);
|
|
108
|
+
}
|
|
109
|
+
for (const line of failed) err(`[tmp-prune] could not remove ${line}`);
|
|
110
|
+
return failed.length > 0 ? 1 : 0;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
114
|
+
process.exit(main(process.argv.slice(2)));
|
|
115
|
+
}
|
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,23 @@ Format: `## [version] — YYYY-MM-DD`
|
|
|
8
8
|
|
|
9
9
|
## [Unreleased]
|
|
10
10
|
|
|
11
|
+
## [5.2.4] — 2026-10-17
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
|
|
15
|
+
- **`tmp/` prune on push.** New copy-and-own `scripts/cleanup/bkit-tmp-prune.mjs` deletes files under the checkout's `tmp/` untouched for 7+ days (`--days=<n>`), then the folders that leaves empty. It never follows symlinks and never removes `tmp/` itself. The `.husky/pre-push` template runs it before the gates and skips it until the script is copied; a failed prune warns and the push goes on. New `tmp-prune` setup tip. `.bkit/templates.md` § tmp/ prune.
|
|
16
|
+
- **Audit reports suggest the issues to create.** Every audit template's `Report` gains a `Suggested Issues` table, filled by `@bkit-audit-generate`. The table groups findings into issues, one row per change landed in one go (by root cause, then module, then fix), and every `MEDIUM`+ finding lands in exactly one row. Each row names its next step: `/bkit-design`, `/bkit-plan`, `/bkit-build` or `/bkit-debug`; the `.agents/shortcuts.md` lite path (`shortcut:build`, `shortcut:debug`) when its § When to use allows; or `manual` for a change outside the repo. The agent still never files issues. Gate 3 gains a `Suggested Issues` check, shared as `.bkit/wording.md` clause `audit-suggested-issues`, so the wording test fails any template missing it.
|
|
17
|
+
- **Warning when a workflow, plan, design or audit runs on an outdated bkit.** `bkit repo info` (Step 1 of every phase workflow) compares `.bkit/version` `pinnedVersion` with the newest published `@cbartens/bkit` and returns `bkitVersion` / `bkitLatest` / `bkitOutdated` / `bkitAdvisory`; Step 1 shows the advisory with the upgrade command and carries on. Every anchored doc (design, plan, sub-plan, audit report) records `bkitVersion` and `bkitLatest` in its `bkit:anchor` block, and an outdated one gets a visible `Outdated bkit` line under the block that the next stamp drops once current. Warning only, never a stop: the registry is asked at most once a day (cache in the git common dir), offline or no pin means no warning, and `BKIT_NO_UPDATE_CHECK=1` skips the lookup. `.bkit/workflows.md` § Invocation, § Anchor Block.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- **Audits never stop on a blocked call.** Pre-Flight `Permissions` still probes every tool first, but a blocked call (there or in any step) no longer pauses the run for a grant or `continue`. The agent records the call and its narrow allow rule, runs every step the remaining tools allow, and lists what it could not check under `Not Checked`. A call the owner deliberately keeps blocked no longer stalls every run.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- **Audits no longer duplicate failure rows other workflows wrote.** `@bkit-audit-generate` matches findings against every open `docs/failures.jsonl` row, not only `audit-{slug}-*` keys, and reuses the key of a row naming the same problem (same `file:line`, test title or error signature). Closing stays limited to the audit's own `audit-{slug}-*` rows. Most visible on the flakes audit, where debug runs had already recorded most flakes.
|
|
26
|
+
- **Eight audit templates no longer say the run writes no ledger rows.** Red-team, security, repo, testing, logs, annotations, cost and flakes named failure rows as a later step, contradicting the audit agent writing them itself. They now say the audit agent writes `docs/failures.jsonl` rows; issues and doc edits stay a later step.
|
|
27
|
+
|
|
11
28
|
## [5.2.3] — 2026-10-17
|
|
12
29
|
|
|
13
30
|
### Added
|
|
@@ -270,6 +270,15 @@ export const SETUP_TIPS = [
|
|
|
270
270
|
steps: "`.bkit/templates.md` § Prettier tables.",
|
|
271
271
|
fires: (cwd) => !exists(cwd, "scripts/prettier/bkit-insert-ignore.mjs"),
|
|
272
272
|
},
|
|
273
|
+
{
|
|
274
|
+
id: "tmp-prune",
|
|
275
|
+
title: "Clear out old scratch files",
|
|
276
|
+
line: "Scratch files agents leave in tmp/ are never cleared, so the folder keeps growing. Add the clean-up that runs when you push.",
|
|
277
|
+
why: "Agents leave logs and scratch files in tmp/ on every run. Each push deletes the ones untouched for a week, so the folder stays small without anyone thinking about it.",
|
|
278
|
+
ask: "Copy .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs to scripts/cleanup/, then copy the `tmp/ prune` block from .bkit/templates/.husky/pre-push into .husky/pre-push above the gates.",
|
|
279
|
+
steps: "`.bkit/templates.md` § tmp/ prune.",
|
|
280
|
+
fires: (cwd) => exists(cwd, ".husky/pre-push") && !exists(cwd, "scripts/cleanup/bkit-tmp-prune.mjs"),
|
|
281
|
+
},
|
|
273
282
|
// --- setup: only some setups -----------------------------------------------------------
|
|
274
283
|
{
|
|
275
284
|
id: "cursor-files",
|
|
@@ -28,6 +28,7 @@ import { readTemplate } from "../../render/parts.js";
|
|
|
28
28
|
import { TEMPLATE_COPIES_DIR, getCoreRoot, getSharedRoot, getBkitDocsRoot, getPkgRoot, } from "../../shared/package-roots.js";
|
|
29
29
|
import { getInstallingVersion, requireOpencodeProvider, detectOpencodeProviders, runUpgradeAdvisories, } from "./install.js";
|
|
30
30
|
import { setLogPrefix } from "../../shared/log-prefix.js";
|
|
31
|
+
import { BKIT_PACKAGE, lookupLatestPublished } from "../../shared/bkit-latest.js";
|
|
31
32
|
import { getInstallManifest, getModuleManifest, DEFAULT_ISSUE_TRACKER, parseIssueTracker, } from "../../install/manifest.js";
|
|
32
33
|
import { OPTIN_MODULES } from "../../install/manifest.js";
|
|
33
34
|
import { detectInstalledHostModules } from "../../install/hosts.js";
|
|
@@ -339,16 +340,15 @@ export function updateCanonicalHashesAfterUpgrade(result, options) {
|
|
|
339
340
|
* registry auth). Hard-exits with guidance on failure — the caller has nothing
|
|
340
341
|
* to fall back to.
|
|
341
342
|
*/
|
|
342
|
-
|
|
343
|
-
const
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
`(pnpm view exit ${r.status ?? "null"}). Check your network / registry access, ` +
|
|
343
|
+
function resolveLatestPublishedVersion(cwd) {
|
|
344
|
+
const latest = lookupLatestPublished(cwd, null);
|
|
345
|
+
if (latest === null) {
|
|
346
|
+
console.error(`${LOG_PREFIX} could not resolve the latest ${BKIT_PACKAGE} version from the registry ` +
|
|
347
|
+
`(pnpm view failed). Check your network / registry access, ` +
|
|
348
348
|
`or pin a version with --to=<version>.`);
|
|
349
349
|
process.exit(1);
|
|
350
350
|
}
|
|
351
|
-
return
|
|
351
|
+
return latest;
|
|
352
352
|
}
|
|
353
353
|
/**
|
|
354
354
|
* Atomic self-bump for `bkit upgrade --to=<v>` / `--latest`: install the target
|
|
@@ -362,9 +362,8 @@ async function resolveLatestPublishedVersion(cwd) {
|
|
|
362
362
|
*/
|
|
363
363
|
export async function runSelfBump(flags, cwd) {
|
|
364
364
|
const installed = getInstallingVersion();
|
|
365
|
-
//
|
|
366
|
-
|
|
367
|
-
const latestVersion = flags.latest ? await resolveLatestPublishedVersion(cwd) : "";
|
|
365
|
+
// Resolve the latest first (only when asked), then feed planSelfBump a constant.
|
|
366
|
+
const latestVersion = flags.latest ? resolveLatestPublishedVersion(cwd) : "";
|
|
368
367
|
const resolvedPlan = planSelfBump(installed, { toVersion: flags.toVersion, latest: flags.latest }, () => latestVersion);
|
|
369
368
|
if (resolvedPlan.kind === "invalid") {
|
|
370
369
|
console.error(`${LOG_PREFIX} ${resolvedPlan.message}`);
|
|
@@ -15,6 +15,7 @@ import * as os from "node:os";
|
|
|
15
15
|
import * as path from "node:path";
|
|
16
16
|
import { gitEnv } from "../../ledgers/telemetry.js";
|
|
17
17
|
import { bodySkipToken, CommandError, EXIT, git, parseJson, repoRoot, runGit, SKIP_CI_TOKEN, } from "../lib.js";
|
|
18
|
+
import { bkitVersionStatus } from "../../shared/bkit-latest.js";
|
|
18
19
|
import { TIMEOUTS } from "../../shared/timeouts.js";
|
|
19
20
|
import { commitBookkeeping } from "./ledgers.js";
|
|
20
21
|
import { acquireDevLock, lockRoot, releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
|
|
@@ -284,7 +285,17 @@ export function resolveRebase(top, onLog = () => undefined) {
|
|
|
284
285
|
// ---------------------------------------------------------------------------
|
|
285
286
|
const ANCHOR_OPEN = "<!-- bkit:anchor";
|
|
286
287
|
const ANCHOR_CLOSE = "-->";
|
|
287
|
-
|
|
288
|
+
/** Ends the visible line a stamp writes under the block when the doc came from an outdated bkit. */
|
|
289
|
+
const OUTDATED_MARK = "<!-- bkit:outdated -->";
|
|
290
|
+
const OUTDATED_LINE = new RegExp(`^.*${OUTDATED_MARK}\n(?:\n)?`, "gm");
|
|
291
|
+
export const ANCHOR_FIELDS = [
|
|
292
|
+
"baseSha",
|
|
293
|
+
"baseRef",
|
|
294
|
+
"designPath",
|
|
295
|
+
"designBaseSha",
|
|
296
|
+
"bkitVersion",
|
|
297
|
+
"bkitLatest",
|
|
298
|
+
];
|
|
288
299
|
/** Lines of `text` with whether each sits inside an anchor block (a `sed '/open/,/close/'` range). */
|
|
289
300
|
function anchorLines(text) {
|
|
290
301
|
const lines = text.split("\n");
|
|
@@ -319,16 +330,38 @@ export function readAnchor(text) {
|
|
|
319
330
|
}
|
|
320
331
|
return out;
|
|
321
332
|
}
|
|
322
|
-
/**
|
|
323
|
-
|
|
333
|
+
/**
|
|
334
|
+
* The bkit release a doc is being generated from, for its anchor: undefined when
|
|
335
|
+
* this repo has no `.bkit/version` pin (nothing to record). Asks the registry for
|
|
336
|
+
* the newest release at most once a day; offline leaves `latest` null.
|
|
337
|
+
*/
|
|
338
|
+
export function anchorBkitStatus(cwd) {
|
|
339
|
+
const status = bkitVersionStatus(git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd, git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
|
|
340
|
+
return status.version === null ? undefined : status;
|
|
341
|
+
}
|
|
342
|
+
/**
|
|
343
|
+
* `text` with a fresh anchor block on top and every prior one removed, so re-stamping
|
|
344
|
+
* is idempotent. With `bkit`, the block records the release the doc came from and the
|
|
345
|
+
* newest one (empty when unknown); an outdated release adds one visible warning line
|
|
346
|
+
* under the block, replaced or dropped by the next stamp like the block itself.
|
|
347
|
+
*/
|
|
348
|
+
export function stampAnchor(text, baseSha, design, baseRef = UPSTREAM, bkit) {
|
|
324
349
|
const header = [ANCHOR_OPEN, `baseSha: ${baseSha}`, `baseRef: ${baseRef}`];
|
|
325
350
|
if (design)
|
|
326
351
|
header.push(`designPath: ${design.path}`, `designBaseSha: ${design.baseSha}`);
|
|
352
|
+
if (bkit)
|
|
353
|
+
header.push(`bkitVersion: ${bkit.version ?? ""}`, `bkitLatest: ${bkit.latest ?? ""}`);
|
|
327
354
|
header.push(ANCHOR_CLOSE);
|
|
328
|
-
|
|
355
|
+
let body = anchorLines(text)
|
|
329
356
|
.filter((l) => !l.inBlock)
|
|
330
357
|
.map((l) => (l.last ? l.line : `${l.line}\n`))
|
|
331
|
-
.join("")
|
|
358
|
+
.join("")
|
|
359
|
+
.replace(OUTDATED_LINE, "");
|
|
360
|
+
if (bkit?.outdated === true) {
|
|
361
|
+
// Blank lines on both sides of the warning, as prettier writes them.
|
|
362
|
+
header.push("", `> **Outdated bkit:** generated with bkit ${bkit.version} while ${bkit.latest} was out, so its workflow and template text may be stale. Upgrade with \`pnpm bkit upgrade --latest\` and regenerate if that matters. ${OUTDATED_MARK}`);
|
|
363
|
+
body = `\n${body.replace(/^\n+/, "")}`;
|
|
364
|
+
}
|
|
332
365
|
return `${header.join("\n")}\n${body}`;
|
|
333
366
|
}
|
|
334
367
|
// ---------------------------------------------------------------------------
|
|
@@ -956,8 +989,11 @@ function anchorStampVerb(ctx) {
|
|
|
956
989
|
baseSha: readAnchor(fs.readFileSync(designFile, "utf-8")).baseSha ?? "",
|
|
957
990
|
}
|
|
958
991
|
: undefined;
|
|
992
|
+
const bkit = anchorBkitStatus(ctx.cwd);
|
|
993
|
+
if (bkit?.advisory)
|
|
994
|
+
ctx.log(bkit.advisory);
|
|
959
995
|
const before = fs.readFileSync(file, "utf-8");
|
|
960
|
-
const after = stampAnchor(before, baseSha, design, baseRef);
|
|
996
|
+
const after = stampAnchor(before, baseSha, design, baseRef, bkit);
|
|
961
997
|
// Temp file + rename: a crash mid-write never leaves a half-stamped doc.
|
|
962
998
|
const tmp = `${file}.bkit-anchor.tmp`;
|
|
963
999
|
fs.writeFileSync(tmp, after);
|
|
@@ -968,6 +1004,10 @@ function anchorStampVerb(ctx) {
|
|
|
968
1004
|
baseRef,
|
|
969
1005
|
designPath: design?.path ?? null,
|
|
970
1006
|
designBaseSha: design?.baseSha ?? null,
|
|
1007
|
+
bkitVersion: bkit?.version ?? null,
|
|
1008
|
+
bkitLatest: bkit?.latest ?? null,
|
|
1009
|
+
bkitOutdated: bkit?.outdated ?? null,
|
|
1010
|
+
bkitAdvisory: bkit?.advisory ?? null,
|
|
971
1011
|
changed: before !== after,
|
|
972
1012
|
});
|
|
973
1013
|
return EXIT.OK;
|
|
@@ -985,7 +1025,7 @@ function anchorReadVerb(ctx) {
|
|
|
985
1025
|
ctx.emit({ ...fields, value: null, skip: reason, landed: null });
|
|
986
1026
|
return EXIT_ANCHOR_SKIP;
|
|
987
1027
|
};
|
|
988
|
-
const none =
|
|
1028
|
+
const none = Object.fromEntries(ANCHOR_FIELDS.map((f) => [f, null]));
|
|
989
1029
|
if (!fs.statSync(file, { throwIfNoEntry: false })?.isFile()) {
|
|
990
1030
|
if (against !== undefined)
|
|
991
1031
|
return skip("no-file", `no ${rel} — nothing to check`, none);
|
|
@@ -1208,7 +1248,7 @@ export const branchesCommand = {
|
|
|
1208
1248
|
run: landVerb,
|
|
1209
1249
|
},
|
|
1210
1250
|
"anchor-stamp": {
|
|
1211
|
-
summary: "Put a <!-- bkit:anchor --> block recording the base commit on top of a design/plan doc or audit report (idempotent).",
|
|
1251
|
+
summary: "Put a <!-- bkit:anchor --> block recording the base commit and bkit release on top of a design/plan doc or audit report (idempotent).",
|
|
1212
1252
|
flags: [
|
|
1213
1253
|
{ name: "file", type: "string", required: true, help: "doc to stamp (must exist)" },
|
|
1214
1254
|
{
|
|
@@ -1234,6 +1274,10 @@ export const branchesCommand = {
|
|
|
1234
1274
|
baseRef: "ref stamped",
|
|
1235
1275
|
designPath: "design path stamped (null when none)",
|
|
1236
1276
|
designBaseSha: "the design doc's baseSha stamped (null when none; empty when it had no anchor)",
|
|
1277
|
+
bkitVersion: "the .bkit/version pin stamped (null when unpinned: no bkit fields are stamped then)",
|
|
1278
|
+
bkitLatest: "newest published bkit stamped (null when unknown: stamped empty)",
|
|
1279
|
+
bkitOutdated: "true when bkitVersion is older than bkitLatest: a visible warning line is stamped under the block (null when unknown)",
|
|
1280
|
+
bkitAdvisory: "one warning line when bkitOutdated, else null",
|
|
1237
1281
|
changed: "false when the doc already carried exactly this block",
|
|
1238
1282
|
},
|
|
1239
1283
|
exitCodes: { [EXIT_NO_FILE]: "--file is missing or not a file" },
|
|
@@ -1259,6 +1303,8 @@ export const branchesCommand = {
|
|
|
1259
1303
|
baseRef: "anchor baseRef (null when absent)",
|
|
1260
1304
|
designPath: "anchor designPath (null when absent)",
|
|
1261
1305
|
designBaseSha: "anchor designBaseSha (null when absent)",
|
|
1306
|
+
bkitVersion: "anchor bkitVersion (null when absent)",
|
|
1307
|
+
bkitLatest: "anchor bkitLatest (null when absent)",
|
|
1262
1308
|
value: "the --field value (null when absent or no --field)",
|
|
1263
1309
|
skip: "with --against: no-file | no-anchor | unreachable | nothing-landed (null = run the check)",
|
|
1264
1310
|
landed: "with --against: paths changed between baseSha and the ref",
|