@cbartens/bkit 5.3.0 → 5.4.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.
Files changed (128) hide show
  1. package/.bkit/README.md +3 -2
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +8 -2
  4. package/.bkit/core/.bkit/README.md +2 -1
  5. package/.bkit/core/.bkit/cloud.md +33 -33
  6. package/.bkit/core/.bkit/comparison.md +1 -1
  7. package/.bkit/core/.bkit/install.md +6 -5
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +4 -3
  10. package/.bkit/core/.bkit/prompts.md +4 -3
  11. package/.bkit/core/.bkit/providers.md +1 -1
  12. package/.bkit/core/.bkit/templates.md +35 -5
  13. package/.bkit/core/.bkit/trackers.md +7 -8
  14. package/.bkit/core/.bkit/workflows.md +106 -86
  15. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  16. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  17. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  25. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  26. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  29. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  30. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  32. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  34. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  36. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  37. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  38. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  39. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  40. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  43. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  44. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  47. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  48. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  49. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  50. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  51. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -0
  52. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  53. package/.bkit/core/engine/cli.ts +22 -15
  54. package/.bkit/core/engine/commands/comply.ts +25 -16
  55. package/.bkit/core/engine/commands/install/install.ts +11 -4
  56. package/.bkit/core/engine/commands/land.ts +156 -0
  57. package/.bkit/core/engine/commands/lib.ts +10 -8
  58. package/.bkit/core/engine/commands/registry.ts +2 -0
  59. package/.bkit/core/engine/commands/tips.ts +7 -3
  60. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  61. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  62. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  63. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  64. package/.bkit/core/engine/commands/workflow/prs.ts +11 -2
  65. package/.bkit/core/engine/commands/workflow/roadmap.ts +48 -53
  66. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  67. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  68. package/.bkit/core/engine/commands/workflow/steps.ts +24 -15
  69. package/.bkit/core/engine/commands/workflow/workflows.ts +433 -265
  70. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  71. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  72. package/.bkit/core/engine/install/modules/core.ts +15 -0
  73. package/.bkit/core/engine/install/placeholders.ts +13 -17
  74. package/.bkit/core/engine/shared/settings.ts +8 -0
  75. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  76. package/.bkit/core/prompts/bkit-audit-generate.md +47 -4
  77. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -1
  78. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -1
  79. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  80. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -1
  81. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -1
  82. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +3 -3
  83. package/.bkit/core/workflows/bkit-auto.md +2 -2
  84. package/.bkit/core/workflows/bkit-build.md +7 -7
  85. package/.bkit/core/workflows/bkit-debug.md +11 -11
  86. package/.bkit/core/workflows/bkit-design.md +20 -11
  87. package/.bkit/core/workflows/bkit-plan.md +23 -13
  88. package/.bkit/core/workflows/bkit-ship.md +82 -93
  89. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  90. package/.bkit/shared/.claude/settings.json +1 -0
  91. package/.bkit/shared/docs/deployments.md +29 -25
  92. package/.bkit/shared/gitignore +1 -2
  93. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  94. package/.bkit/templates/.github/workflows/bkit-ci.yml +7 -2
  95. package/.bkit/templates/.husky/pre-commit +6 -0
  96. package/.bkit/templates/.husky/pre-push +7 -0
  97. package/.bkit/templates/.lintstagedrc.json +5 -1
  98. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  99. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  100. package/CHANGELOG.md +48 -0
  101. package/README.md +97 -96
  102. package/dist/checks/status-holes.js +0 -1
  103. package/dist/checks/tips/catalogue.js +14 -0
  104. package/dist/checks/tips/index.js +44 -28
  105. package/dist/cli.js +22 -16
  106. package/dist/commands/comply.js +20 -13
  107. package/dist/commands/install/install.js +10 -4
  108. package/dist/commands/land.js +129 -0
  109. package/dist/commands/lib.js +9 -6
  110. package/dist/commands/registry.js +2 -0
  111. package/dist/commands/tips.js +7 -3
  112. package/dist/commands/workflow/branches.js +300 -243
  113. package/dist/commands/workflow/disk.js +452 -0
  114. package/dist/commands/workflow/issues.js +63 -27
  115. package/dist/commands/workflow/locks.js +35 -130
  116. package/dist/commands/workflow/prs.js +5 -2
  117. package/dist/commands/workflow/roadmap.js +49 -56
  118. package/dist/commands/workflow/runtime.js +3 -2
  119. package/dist/commands/workflow/status.js +32 -12
  120. package/dist/commands/workflow/steps.js +18 -11
  121. package/dist/commands/workflow/workflows.js +388 -247
  122. package/dist/commands/workflow/workstreams.js +3 -2
  123. package/dist/commands/workflow/worktrees.js +11 -1
  124. package/dist/install/modules/core.js +13 -0
  125. package/dist/install/placeholders.js +13 -19
  126. package/dist/shared/settings.js +5 -0
  127. package/dist/shared/timeouts.js +8 -7
  128. package/package.json +1 -1
@@ -73,13 +73,14 @@ export const requiresList = (w) => `[${w.requires.join(", ")}]`;
73
73
  /** The Step 11 comment: one line per workstream, the issue-body line, then the design doc link. */
74
74
  export function commentBody(ws, opts) {
75
75
  const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
76
+ const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
76
77
  return [
77
78
  "###### bkit:generated",
78
79
  "### Step 11 — Suggested Workstreams",
79
80
  "Advisory only. NEVER auto-trigger.",
80
81
  ...ws.map((w) => `- ${w.id}: ${w.name}. Requires: ${requiresList(w)}`),
81
- `Filing one issue per workstream: put \`**Parent design:** [${opts.fid}-design.md](${doc})\` in its body, and list the issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`,
82
- `[${doc}](https://github.com/${opts.ownerRepo}/blob/dev/${doc})`,
82
+ `Filing one issue per workstream: put \`**Parent design:** [${opts.fid}-design.md](${url})\` in its body, and list the issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`,
83
+ `[${doc}](${url})`,
83
84
  ].join("\n");
84
85
  }
85
86
  const ARTIFACT_FLAG = {
@@ -16,6 +16,7 @@ import { gitEnv } from "../../ledgers/telemetry.js";
16
16
  import { readBkitConfig } from "../../shared/settings.js";
17
17
  import { COULD_NOT_RUN_EXIT_CODES, installCommand } from "../../shared/package-manager.js";
18
18
  import { CommandError, DEV, EXIT, git, isSharedBranch, repoRoot, runGit, } from "../lib.js";
19
+ import { ensureDiskSpace } from "./disk.js";
19
20
  import { detect } from "./runtime.js";
20
21
  import { WORKFLOW_FLAG } from "./status.js";
21
22
  const WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
@@ -29,6 +30,7 @@ export const EXIT_WORKTREE_ADD = 8;
29
30
  export const EXIT_REBASE_NOT_STARTED = 9;
30
31
  export const EXIT_NOT_A_WORKTREE = 10;
31
32
  export const EXIT_REMOVE = 11;
33
+ export const EXIT_DISK_FULL = 12;
32
34
  const FID_FLAG = { name: "fid", type: "string", required: true, help: "feature id" };
33
35
  function fidOf(value) {
34
36
  const fid = String(value);
@@ -302,8 +304,9 @@ export const worktreesCommand = {
302
304
  [EXIT_WORKTREE_ADD]: "git worktree add failed",
303
305
  [EXIT_REBASE_NOT_STARTED]: "resume rebase could not start (e.g. uncommitted changes)",
304
306
  [EXIT_NOT_A_WORKTREE]: ".worktrees/{fid} exists but is not a registered git worktree",
307
+ [EXIT_DISK_FULL]: "free disk under bkit.disk.minFreeGb even after your max cleanup steps (`bkit disk prune`); nothing created",
305
308
  },
306
- run: (ctx) => {
309
+ run: async (ctx) => {
307
310
  const f = ctx.flags;
308
311
  const workflow = String(f.workflow);
309
312
  if (!WORKFLOWS.includes(workflow)) {
@@ -341,6 +344,13 @@ export const worktreesCommand = {
341
344
  const wtDir = worktreeDir(root, fid);
342
345
  let mode = "adopted";
343
346
  if (mint) {
347
+ const full = await ensureDiskSpace({
348
+ cwd: root,
349
+ minFreeGb: config.diskMinFreeGb,
350
+ log: ctx.log,
351
+ });
352
+ if (full !== null)
353
+ throw new CommandError(EXIT_DISK_FULL, full);
344
354
  runGit(root, ["worktree", "prune"]);
345
355
  if (fs.existsSync(wtDir)) {
346
356
  // A plain directory there would resolve to the main checkout's repo,
@@ -231,6 +231,7 @@ export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
231
231
  }
232
232
  }
233
233
  migrateShortcutsToLite(dryRun, ws, logPrefix);
234
+ migrateRetiredDevLock(dryRun, ws, logPrefix);
234
235
  }
235
236
  // Migration (5.1.0 – 5.2.4 installs, `docs/migrations.md`): the lite workflows lived at
236
237
  // `.agents/shortcuts.md`. The consumer's own lines below `bkit:end` (minus the seeded
@@ -268,6 +269,18 @@ export function migrateShortcutsToLite(dryRun, ws, logPrefix) {
268
269
  ws.writes.push({ path: RETIRED_SHORTCUTS, action: "write" });
269
270
  console.log(`${logPrefix} ${tag}core: moved ${RETIRED_SHORTCUTS} → ${dst}`);
270
271
  }
272
+ // Migration (installs up to 5.3.x, `docs/migrations.md`): `.bkit/.dev.lock` was the
273
+ // repo-wide dev lock. Nothing reads it now, so one a crashed run left behind is deleted.
274
+ // bkit owned the name whole. Recorded in ws so `bkit check` fails until upgrade runs.
275
+ const RETIRED_DEV_LOCK = path.join(".bkit", ".dev.lock");
276
+ export function migrateRetiredDevLock(dryRun, ws, logPrefix) {
277
+ if (!fs.lstatSync(RETIRED_DEV_LOCK, { throwIfNoEntry: false })?.isFile())
278
+ return;
279
+ if (!dryRun)
280
+ fs.rmSync(RETIRED_DEV_LOCK);
281
+ ws.writes.push({ path: RETIRED_DEV_LOCK, action: "write" });
282
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: removed ${RETIRED_DEV_LOCK} (the dev lock is gone)`);
283
+ }
271
284
  // ---------------------------------------------------------------------------
272
285
  // Source-rendered host outputs — agents (.agents/prompts source) and commands
273
286
  // (.bkit/workflows source). Extracted from the host module functions so BOTH
@@ -1,28 +1,22 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { execSync } from "node:child_process";
3
+ import { spawnSync } from "node:child_process";
4
4
  import { readInstallingVersion } from "../shared/package-json.js";
5
5
  import { managedVersionMarker } from "./version-file.js";
6
6
  import { gitEnv, resolveRepoSlug } from "../ledgers/telemetry.js";
7
- // Resolve DEFAULT_BRANCH: git symbolic-ref refs/remotes/origin/HEAD → "main"
7
+ // Resolve DEFAULT_BRANCH, the production branch: refs/remotes/origin/HEAD, else "main".
8
+ // `dev` is bkit's integration branch, never production, so a remote whose default is `dev`
9
+ // also gets "main" — and renders the same bytes as a checkout with no origin/HEAD.
8
10
  function resolveDefaultBranch(cwd) {
9
- try {
10
- const raw = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
11
- cwd,
12
- encoding: "utf-8",
13
- stdio: ["ignore", "pipe", "ignore"],
14
- env: gitEnv(),
15
- }).trim();
16
- // raw is like "refs/remotes/origin/main"
17
- const parts = raw.split("/");
18
- const branch = parts[parts.length - 1];
19
- if (branch)
20
- return branch;
21
- }
22
- catch {
23
- // not a git repo or no remote HEAD configured — fall back
24
- }
25
- return "main";
11
+ const res = spawnSync("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
12
+ cwd,
13
+ encoding: "utf-8",
14
+ stdio: ["ignore", "pipe", "ignore"],
15
+ env: gitEnv(),
16
+ });
17
+ // stdout is like "refs/remotes/origin/main"; empty when not a git repo or no remote HEAD.
18
+ const branch = res.status === 0 ? res.stdout.trim().replace(/^refs\/remotes\/origin\//, "") : "";
19
+ return branch === "" || branch === "dev" ? "main" : branch;
26
20
  }
27
21
  // Read and parse package.json from cwd. Throws if absent.
28
22
  function readPackageJson(cwd) {
@@ -10,6 +10,7 @@ export const CONFIG_DEFAULTS = {
10
10
  capstoneJob: "bkit-tests-check",
11
11
  worktreeCopy: [".env", ".env.local"],
12
12
  worktreeInstall: true,
13
+ diskMinFreeGb: 40,
13
14
  issueTracker: DEFAULT_ISSUE_TRACKER,
14
15
  githubProject: null,
15
16
  shipGateRequiredLanes: [],
@@ -31,6 +32,7 @@ export function readBkitConfig(root) {
31
32
  const bkit = ((read.ok ? read.pkg.bkit : undefined) ?? {});
32
33
  const worktree = (bkit.worktree ?? {});
33
34
  const copy = worktree.copy;
35
+ const minFreeGb = (bkit.disk ?? {}).minFreeGb;
34
36
  const project = bkit.githubProject;
35
37
  const lanes = bkit.shipGateRequiredLanes;
36
38
  const provider = bkit.opencodeProvider;
@@ -42,6 +44,9 @@ export function readBkitConfig(root) {
42
44
  ? [...copy]
43
45
  : [...CONFIG_DEFAULTS.worktreeCopy],
44
46
  worktreeInstall: typeof worktree.install === "boolean" ? worktree.install : CONFIG_DEFAULTS.worktreeInstall,
47
+ diskMinFreeGb: typeof minFreeGb === "number" && Number.isFinite(minFreeGb) && minFreeGb >= 0
48
+ ? minFreeGb
49
+ : CONFIG_DEFAULTS.diskMinFreeGb,
45
50
  issueTracker: parseIssueTracker(bkit.issueTracker) ?? CONFIG_DEFAULTS.issueTracker,
46
51
  githubProject: project === false
47
52
  ? false
@@ -1,8 +1,7 @@
1
1
  // shared/timeouts.ts — bkit-owned waits, poll intervals and stale ages.
2
2
  //
3
- // One table so no command hard-codes a wait of its own: when the workflows typed
4
- // the `.dev.lock` ages 900 / 600 by hand in seven places, nothing kept the copies
5
- // equal. Units are in the name (`_S` seconds).
3
+ // One table so no command hard-codes a wait of its own. Units are in the name
4
+ // (`_S` seconds).
6
5
  export const TIMEOUTS = {
7
6
  /** Wall-clock seconds to wait for a CI run to appear and complete after a head move. */
8
7
  SHIP_CI_WAIT_TIMEOUT_S: 1800,
@@ -12,10 +11,12 @@ export const TIMEOUTS = {
12
11
  SHIP_PROBE_INTERVAL_S: 10,
13
12
  /** Re-validate presence probe: how many checks (6 x 10s = the 60s a push-triggered run needs). */
14
13
  SHIP_PROBE_ATTEMPTS: 6,
15
- /** A `.dev.lock` older than this many seconds is stale and may be reclaimed. */
16
- SHIP_DEV_LOCK_STALE_S: 900,
17
- /** Seconds to contend for `.dev.lock` before giving up. */
18
- SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S: 600,
14
+ /** Every dev landing: tries at the dev push (dev moved underneath); design / plan close: at the PR merge too. */
15
+ LAND_ATTEMPTS: 10,
16
+ /** Seconds before the first retry of a landing; doubles each retry up to LAND_BACKOFF_CAP_S. */
17
+ LAND_BACKOFF_START_S: 2,
18
+ /** Longest single wait between landing retries, in seconds. */
19
+ LAND_BACKOFF_CAP_S: 30,
19
20
  /** Seconds a registry answer for the newest published bkit is reused before asking again. */
20
21
  BKIT_LATEST_CACHE_S: 86400,
21
22
  /** Seconds a failed registry lookup is remembered, so an offline run does not wait on every call. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cbartens/bkit",
3
- "version": "5.3.0",
3
+ "version": "5.4.0",
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": [