@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.
Files changed (65) hide show
  1. package/.bkit/README.md +4 -2
  2. package/.bkit/core/.bkit/README.md +3 -1
  3. package/.bkit/core/.bkit/install.md +3 -3
  4. package/.bkit/core/.bkit/prompts.md +1 -1
  5. package/.bkit/core/.bkit/templates.md +19 -1
  6. package/.bkit/core/.bkit/workflows.md +7 -2
  7. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +9 -1
  8. package/.bkit/core/docs/templates/bkit-audit-adoption.md +9 -1
  9. package/.bkit/core/docs/templates/bkit-audit-agents.md +9 -1
  10. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +9 -1
  11. package/.bkit/core/docs/templates/bkit-audit-analytics.md +9 -1
  12. package/.bkit/core/docs/templates/bkit-audit-annotations.md +10 -2
  13. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +9 -1
  14. package/.bkit/core/docs/templates/bkit-audit-app-store.md +9 -1
  15. package/.bkit/core/docs/templates/bkit-audit-architecture.md +9 -1
  16. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +9 -1
  17. package/.bkit/core/docs/templates/bkit-audit-config.md +9 -1
  18. package/.bkit/core/docs/templates/bkit-audit-cost.md +10 -2
  19. package/.bkit/core/docs/templates/bkit-audit-coverage.md +9 -1
  20. package/.bkit/core/docs/templates/bkit-audit-database.md +9 -1
  21. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +9 -1
  22. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +9 -1
  23. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +9 -1
  24. package/.bkit/core/docs/templates/bkit-audit-documentation.md +9 -1
  25. package/.bkit/core/docs/templates/bkit-audit-duplication.md +9 -1
  26. package/.bkit/core/docs/templates/bkit-audit-failures.md +9 -1
  27. package/.bkit/core/docs/templates/bkit-audit-flakes.md +10 -2
  28. package/.bkit/core/docs/templates/bkit-audit-gates.md +9 -1
  29. package/.bkit/core/docs/templates/bkit-audit-issues.md +9 -1
  30. package/.bkit/core/docs/templates/bkit-audit-llm.md +9 -1
  31. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -2
  32. package/.bkit/core/docs/templates/bkit-audit-models.md +9 -1
  33. package/.bkit/core/docs/templates/bkit-audit-privacy.md +9 -1
  34. package/.bkit/core/docs/templates/bkit-audit-prompts.md +9 -1
  35. package/.bkit/core/docs/templates/bkit-audit-red-team.md +10 -2
  36. package/.bkit/core/docs/templates/bkit-audit-reliability.md +9 -1
  37. package/.bkit/core/docs/templates/bkit-audit-repo.md +10 -2
  38. package/.bkit/core/docs/templates/bkit-audit-security.md +10 -2
  39. package/.bkit/core/docs/templates/bkit-audit-slop.md +9 -1
  40. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -2
  41. package/.bkit/core/docs/templates/bkit-audit-usability.md +9 -1
  42. package/.bkit/core/engine/checks/tips/catalogue.ts +10 -0
  43. package/.bkit/core/engine/commands/install/upgrade.ts +9 -10
  44. package/.bkit/core/engine/commands/workflow/branches.ts +61 -7
  45. package/.bkit/core/engine/commands/workflow/repo.ts +16 -2
  46. package/.bkit/core/engine/commands/workflow/workflows.ts +4 -3
  47. package/.bkit/core/engine/shared/bkit-latest.ts +164 -0
  48. package/.bkit/core/engine/shared/timeouts.ts +6 -0
  49. package/.bkit/core/prompts/bkit-audit-generate.md +6 -4
  50. package/.bkit/core/workflows/bkit-build.md +1 -1
  51. package/.bkit/core/workflows/bkit-debug.md +1 -1
  52. package/.bkit/core/workflows/bkit-design.md +1 -1
  53. package/.bkit/core/workflows/bkit-plan.md +1 -1
  54. package/.bkit/core/workflows/bkit-ship.md +1 -1
  55. package/.bkit/templates/.husky/pre-push +7 -0
  56. package/.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs +115 -0
  57. package/CHANGELOG.md +17 -0
  58. package/dist/checks/tips/catalogue.js +9 -0
  59. package/dist/commands/install/upgrade.js +9 -10
  60. package/dist/commands/workflow/branches.js +54 -8
  61. package/dist/commands/workflow/repo.js +14 -2
  62. package/dist/commands/workflow/workflows.js +4 -3
  63. package/dist/shared/bkit-latest.js +150 -0
  64. package/dist/shared/timeouts.js +6 -0
  65. package/package.json +1 -1
@@ -4,12 +4,13 @@
4
4
  // `owner/repo` comes from `gh repo view`; when gh is missing, unauthed, or
5
5
  // answers nothing, from the `origin` remote URL instead (the MCP fallback the
6
6
  // workflows already describe: "parse git remote"). The current branch, how far it
7
- // trails `origin/dev`, the main checkout, and the bkit binary every later block
8
- // calls ride along so Step 1 is one call.
7
+ // trails `origin/dev`, the main checkout, the bkit binary every later block calls,
8
+ // and whether that bkit is behind the newest release ride along so Step 1 is one call.
9
9
  import * as fs from "node:fs";
10
10
  import * as path from "node:path";
11
11
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
12
12
  import { EXIT, git, repoRoot, runGit, runTool } from "../lib.js";
13
+ import { bkitVersionStatus } from "../../shared/bkit-latest.js";
13
14
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
14
15
  export const EXIT_NO_REPO = 3;
15
16
  /** Exit code: HEAD is detached, so there is no current branch (and --allow-detached was not given). */
@@ -107,6 +108,10 @@ export const repoCommand = {
107
108
  repoRoot: "the main checkout (the same from any worktree)",
108
109
  bkit: "the bkit binary the workflow blocks call: <repoRoot>/node_modules/.bin/bkit, else `bkit` on PATH",
109
110
  outboxRoot: "<git common dir>/bkit-outbox: per-run scratch files, never committed",
111
+ bkitVersion: ".bkit/version pinnedVersion: the release this repo's bkit files came from (null when unpinned)",
112
+ bkitLatest: "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
113
+ bkitOutdated: "true when bkitVersion is older than bkitLatest (null when either is unknown)",
114
+ bkitAdvisory: "one line to show the user when bkitOutdated, else null",
110
115
  },
111
116
  exitCodes: {
112
117
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -136,6 +141,9 @@ export const repoCommand = {
136
141
  }
137
142
  const root = repoRoot(ctx.cwd);
138
143
  const common = git(ctx.cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
144
+ const latest = bkitVersionStatus(root, common);
145
+ if (latest.advisory !== null)
146
+ ctx.log(latest.advisory);
139
147
  ctx.emit({
140
148
  ...resolved,
141
149
  owner,
@@ -145,6 +153,10 @@ export const repoCommand = {
145
153
  repoRoot: root,
146
154
  bkit: resolveBkitBinary(root),
147
155
  outboxRoot: path.join(common ?? path.join(root, ".git"), "bkit-outbox"),
156
+ bkitVersion: latest.version,
157
+ bkitLatest: latest.latest,
158
+ bkitOutdated: latest.outdated,
159
+ bkitAdvisory: latest.advisory,
148
160
  });
149
161
  if (branch === null && ctx.flags.allowDetached !== true) {
150
162
  ctx.log("HEAD is detached — no current branch");
@@ -25,7 +25,7 @@ import { readBkitVersion } from "../../install/version-file.js";
25
25
  import { TIMEOUTS } from "../../shared/timeouts.js";
26
26
  import { gradeCompliance } from "../comply.js";
27
27
  import { CommandError, EXIT, git, parseJson, repoRoot, runGh, runGit, statusLocation, statusRelPath, } from "../lib.js";
28
- import { pushBranch, readAnchor, stampAnchor } from "./branches.js";
28
+ import { anchorBkitStatus, pushBranch, readAnchor, stampAnchor } from "./branches.js";
29
29
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX, buildComment, linearState, transitionLabels, } from "./issues.js";
30
30
  import { EXIT_EMPTY, commitBookkeeping, unionLedgers } from "./ledgers.js";
31
31
  import { EXIT_REMOVE_FAILED, EXIT_SPLIT_BUCKET, acquireDevLock, acquireWorkflowLock, lockRoot, owns, readHolder, releaseLock, resolveMonth, workflowLockPath, } from "./locks.js";
@@ -807,7 +807,7 @@ export function highestVersion(dir, workflow) {
807
807
  }
808
808
  return best;
809
809
  }
810
- /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor). */
810
+ /** Stamp `file`'s anchor when a base commit is known (plan: with its design's own anchor; both: the bkit release). */
811
811
  function stamp(cwd, file, baseSha, design) {
812
812
  if (baseSha === "")
813
813
  return;
@@ -817,7 +817,8 @@ function stamp(cwd, file, baseSha, design) {
817
817
  ? { path: design, baseSha: readAnchor(fs.readFileSync(designAbs, "utf-8")).baseSha ?? "" }
818
818
  : undefined;
819
819
  const tmp = `${abs}.bkit-anchor.tmp`;
820
- fs.writeFileSync(tmp, stampAnchor(fs.readFileSync(abs, "utf-8"), baseSha, d));
820
+ const text = fs.readFileSync(abs, "utf-8");
821
+ fs.writeFileSync(tmp, stampAnchor(text, baseSha, d, undefined, anchorBkitStatus(cwd)));
821
822
  fs.renameSync(tmp, abs);
822
823
  }
823
824
  function promoteVerb(ctx) {
@@ -0,0 +1,150 @@
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
+ import { spawnSync } from "node:child_process";
11
+ import * as fs from "node:fs";
12
+ import * as path from "node:path";
13
+ import { readBkitVersion } from "../install/version-file.js";
14
+ import { parseJson } from "./json.js";
15
+ import { PACKAGE_RUNNER } from "./package-manager.js";
16
+ import { TIMEOUTS } from "./timeouts.js";
17
+ export const BKIT_PACKAGE = "@cbartens/bkit";
18
+ /** Cache file name inside the git common dir. */
19
+ export const BKIT_LATEST_CACHE = "bkit-latest-version.json";
20
+ /** Set to anything but `0` / empty to skip the registry lookup (air-gapped machines, CI). */
21
+ export const NO_UPDATE_CHECK_ENV = "BKIT_NO_UPDATE_CHECK";
22
+ const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
23
+ /** Order of two prerelease identifier lists per semver §11: numeric < alphanumeric, shorter < longer. */
24
+ function comparePrerelease(a, b) {
25
+ for (let i = 0; i < Math.max(a.length, b.length); i++) {
26
+ const x = a[i];
27
+ const y = b[i];
28
+ if (x === undefined)
29
+ return -1;
30
+ if (y === undefined)
31
+ return 1;
32
+ const xn = /^\d+$/.test(x);
33
+ const yn = /^\d+$/.test(y);
34
+ if (xn && yn) {
35
+ if (Number(x) !== Number(y))
36
+ return Number(x) < Number(y) ? -1 : 1;
37
+ }
38
+ else if (xn !== yn) {
39
+ return xn ? -1 : 1;
40
+ }
41
+ else if (x !== y) {
42
+ return x < y ? -1 : 1;
43
+ }
44
+ }
45
+ return 0;
46
+ }
47
+ /**
48
+ * -1 / 0 / 1 for `a` older / equal / newer than `b`, compared as numbers (so 5.10.0
49
+ * is newer than 5.9.0) and with a prerelease older than its release. null when
50
+ * either is not a semver.
51
+ */
52
+ export function compareSemver(a, b) {
53
+ const ma = SEMVER_RE.exec(a.trim());
54
+ const mb = SEMVER_RE.exec(b.trim());
55
+ if (!ma || !mb)
56
+ 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)
61
+ return x < y ? -1 : 1;
62
+ }
63
+ const pa = ma[4];
64
+ const pb = mb[4];
65
+ if (pa === undefined && pb === undefined)
66
+ return 0;
67
+ if (pa === undefined)
68
+ return 1;
69
+ if (pb === undefined)
70
+ return -1;
71
+ const c = comparePrerelease(pa.split("."), pb.split("."));
72
+ return c === 0 ? 0 : c < 0 ? -1 : 1;
73
+ }
74
+ /** The newest published bkit per the registry, or null on any failure (offline, timeout, no pnpm). */
75
+ export function lookupLatestPublished(cwd, timeoutS = TIMEOUTS.BKIT_LATEST_LOOKUP_TIMEOUT_S) {
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)
82
+ return null;
83
+ const version = (res.stdout ?? "").trim().replace(/^v/, "");
84
+ return SEMVER_RE.test(version) ? version : null;
85
+ }
86
+ /** The cached registry answer when still fresh: a version, or null for a remembered failure. */
87
+ function readCache(file, now) {
88
+ if (!fs.existsSync(file))
89
+ return undefined;
90
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
91
+ if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null)
92
+ return undefined;
93
+ const { latest, checkedAt } = parsed.value;
94
+ if (typeof checkedAt !== "number")
95
+ return undefined;
96
+ const value = typeof latest === "string" && SEMVER_RE.test(latest) ? latest : null;
97
+ const ttl = value === null ? TIMEOUTS.BKIT_LATEST_RETRY_S : TIMEOUTS.BKIT_LATEST_CACHE_S;
98
+ return now - checkedAt < ttl * 1000 && now >= checkedAt ? { latest: value } : undefined;
99
+ }
100
+ /** Remember the registry answer; a cache that cannot be written only costs a lookup next run. */
101
+ function writeCache(file, latest, now) {
102
+ const tmp = `${file}.${process.pid}.tmp`;
103
+ try {
104
+ fs.writeFileSync(tmp, `${JSON.stringify({ latest, checkedAt: now })}\n`);
105
+ fs.renameSync(tmp, file);
106
+ }
107
+ catch {
108
+ // Read-only git dir: the next run asks the registry again, nothing else changes.
109
+ fs.rmSync(tmp, { force: true });
110
+ }
111
+ }
112
+ /**
113
+ * Whether this repo's bkit is behind the newest release. `gitCommonDir` holds the
114
+ * once-a-day cache; null (not a git repo) skips the cache, not the check.
115
+ */
116
+ export function bkitVersionStatus(root, gitCommonDir, deps = {}) {
117
+ const version = readBkitVersion(path.join(root, ".bkit", "version"))?.pinnedVersion || null;
118
+ const unknown = { version, latest: null, outdated: null, advisory: null };
119
+ if (version === null)
120
+ return unknown;
121
+ const optOut = process.env[NO_UPDATE_CHECK_ENV];
122
+ if (optOut !== undefined && optOut !== "" && optOut !== "0")
123
+ return unknown;
124
+ const now = (deps.now ?? Date.now)();
125
+ const cacheFile = gitCommonDir === null ? null : path.join(gitCommonDir, BKIT_LATEST_CACHE);
126
+ let latest;
127
+ const cached = cacheFile === null ? undefined : readCache(cacheFile, now);
128
+ if (cached !== undefined) {
129
+ latest = cached.latest;
130
+ }
131
+ else {
132
+ latest = (deps.lookup ?? lookupLatestPublished)(root);
133
+ if (cacheFile !== null)
134
+ writeCache(cacheFile, latest, now);
135
+ }
136
+ if (latest === null)
137
+ return unknown;
138
+ const order = compareSemver(version, latest);
139
+ if (order === null)
140
+ return { version, latest, outdated: null, advisory: null };
141
+ const outdated = order < 0;
142
+ return {
143
+ version,
144
+ latest,
145
+ outdated,
146
+ advisory: outdated
147
+ ? `running bkit ${version}; ${latest} is out. Upgrade: ${PACKAGE_RUNNER} bkit upgrade --latest`
148
+ : null,
149
+ };
150
+ }
@@ -16,4 +16,10 @@ export const TIMEOUTS = {
16
16
  SHIP_DEV_LOCK_STALE_S: 900,
17
17
  /** Seconds to contend for `.dev.lock` before giving up. */
18
18
  SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S: 600,
19
+ /** Seconds a registry answer for the newest published bkit is reused before asking again. */
20
+ BKIT_LATEST_CACHE_S: 86400,
21
+ /** Seconds a failed registry lookup is remembered, so an offline run does not wait on every call. */
22
+ BKIT_LATEST_RETRY_S: 3600,
23
+ /** Seconds the registry lookup may take before it counts as failed. */
24
+ BKIT_LATEST_LOOKUP_TIMEOUT_S: 5,
19
25
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.2.3",
3
+ "version": "5.2.4",
4
4
  "private": false,
5
5
  "description": "From vibe coding to production code. A senior engineering team's process, ready-made: AI agents design, plan, build, review, fix and ship your features on Claude Code, Cursor, Codex, Google Antigravity and opencode.",
6
6
  "keywords": [