@cbartens/bkit 5.4.0 → 5.5.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 (111) hide show
  1. package/.bkit/README.md +18 -6
  2. package/.bkit/core/.agents/rules.md +7 -8
  3. package/.bkit/core/.bkit/README.md +17 -5
  4. package/.bkit/core/.bkit/cloud.md +44 -13
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +16 -14
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +12 -9
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +12 -6
  11. package/.bkit/core/.bkit/trackers.md +89 -34
  12. package/.bkit/core/.bkit/workflows.md +42 -38
  13. package/.bkit/core/AGENTS.md +2 -2
  14. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  15. package/.bkit/core/docs/templates/bkit-audit-issues.md +22 -6
  16. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  17. package/.bkit/core/engine/checks/after/github.ts +18 -5
  18. package/.bkit/core/engine/checks/after/index.ts +1 -1
  19. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  20. package/.bkit/core/engine/checks/before/env.ts +28 -18
  21. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  22. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  23. package/.bkit/core/engine/cli.ts +7 -5
  24. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  25. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  26. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  27. package/.bkit/core/engine/commands/workflow/issues.ts +35 -16
  28. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  29. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  30. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  31. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  32. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  33. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  34. package/.bkit/core/engine/install/manifest.ts +31 -10
  35. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  36. package/.bkit/core/engine/install/modules/core.ts +82 -4
  37. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  38. package/.bkit/core/engine/install/write.ts +37 -1
  39. package/.bkit/core/engine/render/trackers.ts +35 -23
  40. package/.bkit/core/engine/shared/egress.ts +6 -0
  41. package/.bkit/core/engine/shared/settings.ts +88 -1
  42. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  43. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  44. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  45. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  46. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  47. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  49. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  50. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  51. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  52. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  53. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  54. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  55. package/.bkit/core/prompts/bkit-utility-update-documentation.md +11 -1
  56. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  57. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  58. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  59. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  60. package/.bkit/core/workflows/bkit-auto.md +19 -6
  61. package/.bkit/core/workflows/bkit-build.md +59 -17
  62. package/.bkit/core/workflows/bkit-debug.md +64 -20
  63. package/.bkit/core/workflows/bkit-design.md +83 -28
  64. package/.bkit/core/workflows/bkit-plan.md +61 -20
  65. package/.bkit/core/workflows/bkit-ship.md +48 -18
  66. package/.bkit/shared/.bkit/.env.example +8 -0
  67. package/.bkit/shared/.claude/settings.json +3 -1
  68. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  69. package/.bkit/shared/.cursor/mcp.json +11 -4
  70. package/.bkit/shared/.mcp.json +11 -4
  71. package/.bkit/shared/.opencode/opencode.json +2 -0
  72. package/.bkit/shared/docs/deployments.md +15 -4
  73. package/.bkit/shared/docs/security.md +1 -1
  74. package/.bkit/shared/docs/testing.md +3 -3
  75. package/.bkit/templates/.github/renovate.json5 +1 -1
  76. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -54
  77. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  78. package/.bkit/templates/.husky/pre-commit +4 -4
  79. package/.bkit/templates/.husky/pre-push +62 -12
  80. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  81. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  82. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  83. package/CHANGELOG.md +37 -1
  84. package/README.md +7 -6
  85. package/dist/checks/after/auth.js +81 -45
  86. package/dist/checks/after/github.js +17 -5
  87. package/dist/checks/after/index.js +1 -1
  88. package/dist/checks/after/tools.js +1 -1
  89. package/dist/checks/before/env.js +24 -17
  90. package/dist/checks/before/mcp.js +4 -2
  91. package/dist/checks/tips/catalogue.js +14 -2
  92. package/dist/cli.js +7 -5
  93. package/dist/commands/ci/ci.js +100 -0
  94. package/dist/commands/install/uninstall.js +42 -0
  95. package/dist/commands/workflow/fids.js +22 -15
  96. package/dist/commands/workflow/issues.js +28 -15
  97. package/dist/commands/workflow/ledgers.js +26 -11
  98. package/dist/commands/workflow/prs.js +3 -1
  99. package/dist/commands/workflow/repo.js +5 -0
  100. package/dist/commands/workflow/roadmap.js +3 -1
  101. package/dist/commands/workflow/steps.js +2 -2
  102. package/dist/commands/workflow/workflows.js +9 -4
  103. package/dist/install/manifest.js +30 -10
  104. package/dist/install/modules/cloud.js +3 -1
  105. package/dist/install/modules/core.js +82 -5
  106. package/dist/install/modules/opencode.js +6 -0
  107. package/dist/install/write.js +26 -2
  108. package/dist/render/trackers.js +34 -20
  109. package/dist/shared/egress.js +6 -0
  110. package/dist/shared/settings.js +39 -0
  111. package/package.json +11 -2
@@ -14,11 +14,17 @@
14
14
  //
15
15
  // `skip-token` — whether a commit message carries a GitHub skip-CI token
16
16
  // (`SKIP_CI_TOKEN`), for the `.husky/pre-push` CI-suppressor guard.
17
+ //
18
+ // `min-push` — whether every file a push changes matches `bkit.minPushPaths`, so
19
+ // `.husky/pre-push` runs `bkit:gate:min`. Files decide, never `[skip ci]` (a typed label
20
+ // GitHub reads off the last commit only).
17
21
  import { spawnSync } from "node:child_process";
18
22
  import * as fs from "node:fs";
19
23
  import * as os from "node:os";
20
24
  import * as path from "node:path";
25
+ import { readBkitConfig } from "../../shared/settings.js";
21
26
  import { CommandError, commitMessage, EXIT, git, parseJson, runGit, SKIP_CI_TOKEN, } from "../lib.js";
27
+ import { changedOutside } from "../workflow/ledgers.js";
22
28
  /** Exit code: slop-scan could not be started (not installed, not executable). */
23
29
  export const EXIT_SLOP_UNAVAILABLE = 3;
24
30
  /** Exit code: slop-scan ran but failed, or its JSON lacks the fields the gate reads. */
@@ -27,6 +33,8 @@ export const EXIT_SLOP_FAILED = 4;
27
33
  export const EXIT_NO_WORKTREE = 5;
28
34
  /** Exit code: vale could not run, or ended with a runtime error (its exit 2). */
29
35
  export const EXIT_VALE_FAILED = 6;
36
+ /** Exit code: a pushed commit, its base, or its `git diff` could not be read. */
37
+ export const EXIT_RANGE_UNKNOWN = 7;
30
38
  /** Branches whose merge-base with HEAD is the default base, in order. */
31
39
  const BASE_CANDIDATES = ["origin/dev", "origin/main"];
32
40
  /** A net score at or below this is float noise, not worsening. */
@@ -372,6 +380,75 @@ function skipToken(ctx) {
372
380
  ctx.emit({ ref, sha, token });
373
381
  return token === null ? EXIT.NO : EXIT.OK;
374
382
  }
383
+ // ---------------------------------------------------------------------------
384
+ // min-push
385
+ // ---------------------------------------------------------------------------
386
+ /** `bkit.minPushPaths` as git pathspecs: `:(glob)` unless an entry carries its own magic. */
387
+ export const minPushPathspecs = (paths) => paths.map((p) => (p.startsWith(":") ? p : `:(glob)${p}`));
388
+ /** Where a pushed commit's range starts: its merge-base with origin/dev, else origin/main. */
389
+ export function pushBase(cwd, sha) {
390
+ for (const cand of BASE_CANDIDATES) {
391
+ if (!runGit(cwd, ["rev-parse", "--verify", "--quiet", cand]).ok)
392
+ continue;
393
+ const mb = runGit(cwd, ["merge-base", sha, cand]);
394
+ if (mb.ok && mb.stdout)
395
+ return mb.stdout;
396
+ }
397
+ return null;
398
+ }
399
+ function minPush(ctx) {
400
+ const top = runGit(ctx.cwd, ["rev-parse", "--show-toplevel"]);
401
+ if (!top.ok)
402
+ throw new CommandError(EXIT.USAGE, `not inside a git repository: ${ctx.cwd}`);
403
+ const given = ctx.flags.ref;
404
+ const refs = Array.isArray(given) && given.length > 0 ? given.map(String) : ["HEAD"];
405
+ const baseFlag = typeof ctx.flags.base === "string" && ctx.flags.base ? ctx.flags.base : null;
406
+ const paths = readBkitConfig(top.stdout).minPushPaths;
407
+ const specs = minPushPathspecs(paths);
408
+ const changed = new Set();
409
+ const outside = new Set();
410
+ for (const ref of refs) {
411
+ const sha = git(ctx.cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
412
+ const base = sha ? (baseFlag ?? pushBase(ctx.cwd, sha)) : null;
413
+ const diff = sha && base ? changedOutside(top.stdout, base, sha, specs) : null;
414
+ if (!diff?.ok) {
415
+ const why = !sha
416
+ ? `cannot read commit '${ref}'`
417
+ : !base
418
+ ? `no base for ${ref} (neither origin/dev nor origin/main resolves)`
419
+ : `'git diff' failed for ${base}..${ref}: ${diff && !diff.ok ? diff.stderr : ""}`;
420
+ ctx.log(`${why} — not proven a min push`);
421
+ ctx.emit({ minPush: false, reason: "unknown", changed: 0, outside: [], paths });
422
+ return EXIT_RANGE_UNKNOWN;
423
+ }
424
+ for (const p of diff.changed)
425
+ changed.add(p);
426
+ for (const p of diff.outside)
427
+ outside.add(p);
428
+ }
429
+ const result = (reason, code, message) => {
430
+ ctx.log(message);
431
+ ctx.emit({
432
+ minPush: reason === null,
433
+ reason,
434
+ changed: changed.size,
435
+ outside: [...outside].sort(),
436
+ paths,
437
+ });
438
+ return code;
439
+ };
440
+ if (paths.length === 0) {
441
+ return result("no-paths", EXIT.NO, "bkit.minPushPaths is empty — not a min push");
442
+ }
443
+ if (changed.size === 0) {
444
+ return result("no-changes", EXIT.NO, "the push changes no files — not proven a min push");
445
+ }
446
+ if (outside.size > 0) {
447
+ const first = [...outside].sort()[0];
448
+ return result("outside", EXIT.NO, `${outside.size} of ${changed.size} changed files match no min-push path (first: ${first})`);
449
+ }
450
+ return result(null, EXIT.OK, `all ${changed.size} changed files match min-push paths`);
451
+ }
375
452
  export const ciCommand = {
376
453
  noun: "ci",
377
454
  summary: "Gates CI and the git hooks run.",
@@ -434,5 +511,28 @@ export const ciCommand = {
434
511
  },
435
512
  run: skipToken,
436
513
  },
514
+ "min-push": {
515
+ summary: "Exit 0 when every file a push changes matches bkit.minPushPaths (the pre-push light gate).",
516
+ flags: [
517
+ {
518
+ name: "ref",
519
+ type: "string",
520
+ repeatable: true,
521
+ help: "a pushed commit (default HEAD); its range starts at its merge-base with origin/dev, else origin/main",
522
+ },
523
+ { name: "base", type: "string", help: "start every range here instead" },
524
+ ],
525
+ output: {
526
+ minPush: "true when every changed file matches bkit.minPushPaths",
527
+ reason: "null when a min push; else no-paths | no-changes | outside | unknown",
528
+ changed: "files the push changes, across every ref",
529
+ outside: "the changed files no min-push path matches",
530
+ paths: "bkit.minPushPaths as read",
531
+ },
532
+ exitCodes: {
533
+ [EXIT_RANGE_UNKNOWN]: "a pushed commit, its base, or its git diff could not be read",
534
+ },
535
+ run: minPush,
536
+ },
437
537
  },
438
538
  };
@@ -669,6 +669,11 @@ export async function runUninstall(modules, ctx) {
669
669
  }
670
670
  }
671
671
  }
672
+ // Targeted uninstall: drop the `bkit.*` keys the removed module records, so its advisories
673
+ // stop firing. Core keeps every other key.
674
+ if (!moduleList.includes("core")) {
675
+ stripModuleBkitKeys(moduleList, ctx, result);
676
+ }
672
677
  // Clean up .agents/ bkit-prefix mirror files
673
678
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
674
679
  // A dry run lists the same paths in result.deleted and removes nothing.
@@ -858,6 +863,43 @@ export async function runUninstall(modules, ctx) {
858
863
  }
859
864
  return result;
860
865
  }
866
+ /** `package.json` `bkit.*` keys each module records on install. */
867
+ const MODULE_BKIT_KEYS = {
868
+ cloud: ["cloudAgents"],
869
+ opencode: ["opencodeProvider", "opencodeProviders"],
870
+ };
871
+ /**
872
+ * Remove the `bkit.*` keys recorded by the modules in `moduleList` from the consumer's
873
+ * package.json, keeping its indent. Lists each removed key in `result.stripped`; a dry run
874
+ * lists without writing.
875
+ */
876
+ function stripModuleBkitKeys(moduleList, ctx, result) {
877
+ const keys = moduleList.flatMap((m) => MODULE_BKIT_KEYS[m] ?? []);
878
+ if (keys.length === 0)
879
+ return;
880
+ const pkgPath = path.join(ctx.cwd, "package.json");
881
+ if (!fs.existsSync(pkgPath))
882
+ return;
883
+ const raw = fs.readFileSync(pkgPath, "utf-8");
884
+ const parsed = parseJson(raw);
885
+ const pkg = parsed.ok ? parsed.value : null;
886
+ if (pkg === null || !isJsonObject(pkg.bkit))
887
+ return;
888
+ const bkit = pkg.bkit;
889
+ const present = keys.filter((k) => k in bkit);
890
+ if (present.length === 0)
891
+ return;
892
+ for (const k of present) {
893
+ delete bkit[k];
894
+ result.stripped.push(`package.json#bkit.${k}`);
895
+ }
896
+ console.log(`${ctx.logPrefix}${ctx.dryRun ? " [dry-run]" : ""} package.json: removed bkit.${present.join(", bkit.")}`);
897
+ if (ctx.dryRun)
898
+ return;
899
+ const indentMatch = raw.match(/\n([ \t]+)"/);
900
+ const indent = indentMatch ? indentMatch[1] : " ";
901
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + "\n", "utf-8");
902
+ }
861
903
  // ---------------------------------------------------------------------------
862
904
  // runSurgicalOpencodeUninstall — remove exactly ONE provider block
863
905
  // ---------------------------------------------------------------------------
@@ -6,8 +6,9 @@
6
6
  // it is checked before first use. Its shape follows the tracker that minted it:
7
7
  // github {N}-{slug} ^[0-9]+-[a-z0-9-]+$
8
8
  // linear {team}-{N}-{slug} ^[a-z]+-[0-9]+-[a-z0-9-]+$ (issue id lowercased first)
9
+ // jira {project}-{N}-{slug} ^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$ (issue key lowercased first)
9
10
  // none any slug ^[a-z0-9][a-z0-9-]*$ (no tracker shape; still path-safe)
10
- // any github or linear ^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$ (auto's CI_DEV allowlist)
11
+ // any any tracker's shape ^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$ (auto's CI_DEV allowlist)
11
12
  import * as fs from "node:fs";
12
13
  import * as path from "node:path";
13
14
  import { parseIssueTracker } from "../../install/manifest.js";
@@ -17,9 +18,14 @@ import { str } from "./status.js";
17
18
  export const FID_PATTERNS = {
18
19
  github: /^[0-9]+-[a-z0-9-]+$/,
19
20
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
21
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
20
22
  none: /^[a-z0-9][a-z0-9-]*$/,
21
- any: /^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$/,
23
+ any: /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$/,
22
24
  };
25
+ /** Trackers whose issue id is a `{KEY}-{N}` key, carried lowercased in the FID. */
26
+ const KEYED = new Set(["linear", "jira"]);
27
+ /** The uppercase issue key each keyed tracker mints. */
28
+ const ISSUE_KEY = { linear: /^[A-Z]+-[0-9]+$/, jira: /^[A-Z][A-Z0-9]+-[0-9]+$/ };
23
29
  /** The slug every recovered FID must pass before it touches a path (auto's branch fallback). */
24
30
  const SLUG = FID_PATTERNS.none;
25
31
  /** Exit code: no FID could be recovered from the marker or the branch. */
@@ -28,7 +34,7 @@ export const EXIT_NO_FID = 3;
28
34
  export const EXIT_SEVERAL = 4;
29
35
  /**
30
36
  * Features already logged for an issue: every `docs/plans/{YYYYMM}/logs/{issue}-*`
31
- * folder, the issue id lowercased (a Linear FID carries it lowercased). Sorted, unique.
37
+ * folder, the issue id lowercased (a Linear or Jira FID carries it lowercased). Sorted, unique.
32
38
  */
33
39
  export function logged(root, issue) {
34
40
  const key = `${issue.replace(/^#/, "").toLowerCase()}-`;
@@ -76,26 +82,26 @@ function trackerFlag(value, cwd, allowAny) {
76
82
  return "any";
77
83
  const t = parseIssueTracker(value);
78
84
  if (!t) {
79
- throw new CommandError(EXIT.USAGE, `--tracker must be github, linear, none${allowAny ? ", any" : ""}; got "${value}"`);
85
+ throw new CommandError(EXIT.USAGE, `--tracker must be github, linear, jira, none${allowAny ? ", any" : ""}; got "${value}"`);
80
86
  }
81
87
  return t;
82
88
  }
83
- /** Linear issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
84
- export const normaliseFid = (fid, tracker) => tracker === "linear" ? fid.toLowerCase() : fid;
89
+ /** Linear and Jira issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
90
+ export const normaliseFid = (fid, tracker) => KEYED.has(tracker) ? fid.toLowerCase() : fid;
85
91
  /**
86
92
  * The tracker issue id a FID embeds, or null when it embeds none:
87
- * github the leading numeric segment, linear the first two segments uppercased.
93
+ * github the leading numeric segment, linear and jira the first two segments uppercased.
88
94
  */
89
95
  export function issueIdOf(fid, tracker) {
90
96
  const [first = "", second = ""] = fid.split("-");
91
97
  if (tracker === "github")
92
98
  return /^[0-9]+$/.test(first) ? first : null;
93
- if (tracker === "linear") {
99
+ if (KEYED.has(tracker)) {
94
100
  const id = `${first}-${second}`.toUpperCase();
95
- return /^[A-Z]+-[0-9]+$/.test(id) ? id : null;
101
+ return ISSUE_KEY[tracker].test(id) ? id : null;
96
102
  }
97
103
  if (tracker === "any") {
98
- const m = /^([0-9]+|[a-z]+-[0-9]+)(?=-)/.exec(fid);
104
+ const m = /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)(?=-)/.exec(fid);
99
105
  return m ? m[1].toUpperCase() : null;
100
106
  }
101
107
  return null;
@@ -104,6 +110,7 @@ export function issueIdOf(fid, tracker) {
104
110
  const MARKERS = {
105
111
  github: /<!-- bkit:issue=#([0-9]+) bkit:fid=(\S+) -->/,
106
112
  linear: /<!-- bkit:issue=([A-Za-z]+-[0-9]+) bkit:fid=(\S+) -->/,
113
+ jira: /<!-- bkit:issue=([A-Za-z][A-Za-z0-9]+-[0-9]+) bkit:fid=(\S+) -->/,
107
114
  none: /<!-- bkit:fid=(\S+) -->/,
108
115
  };
109
116
  /** FID from the marker, when present and well-formed for the tracker. */
@@ -114,7 +121,7 @@ export function fromMarker(text, tracker) {
114
121
  const fid = normaliseFid(m[m.length - 1], tracker);
115
122
  if (!FID_PATTERNS[tracker].test(fid))
116
123
  return null;
117
- const issueId = tracker === "none" ? null : tracker === "linear" ? m[1].toUpperCase() : m[1];
124
+ const issueId = tracker === "none" ? null : KEYED.has(tracker) ? m[1].toUpperCase() : m[1];
118
125
  return { fid, issueId, source: "marker" };
119
126
  }
120
127
  /** FID from `feat/{FID}`; the slug check, then the issue id the tracker needs. */
@@ -133,7 +140,7 @@ export function fromBranch(branch, tracker) {
133
140
  const TRACKER_FLAG = {
134
141
  name: "tracker",
135
142
  type: "string",
136
- help: "github | linear | none (default: package.json bkit.issueTracker, else none)",
143
+ help: "github | linear | jira | none (default: package.json bkit.issueTracker, else none)",
137
144
  };
138
145
  export const fidsCommand = {
139
146
  noun: "fids",
@@ -143,10 +150,10 @@ export const fidsCommand = {
143
150
  summary: "Validate a FID for the tracker: exit 0 valid, exit 1 not.",
144
151
  flags: [
145
152
  { name: "fid", type: "string", required: true, help: "feature id to check" },
146
- { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = github or linear shape (CI_DEV)` },
153
+ { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = any tracker's shape (CI_DEV)` },
147
154
  ],
148
155
  output: {
149
- fid: "the FID as checked (linear: lowercased)",
156
+ fid: "the FID as checked (linear, jira: lowercased)",
150
157
  tracker: "tracker the shape came from",
151
158
  valid: "true when the FID matches",
152
159
  pattern: "the regex checked",
@@ -241,7 +248,7 @@ export const fidsCommand = {
241
248
  name: "issue",
242
249
  type: "string",
243
250
  required: true,
244
- help: "tracker issue id (github: 123 or #123; linear: ABC-123)",
251
+ help: "tracker issue id (github: 123 or #123; linear / jira: ABC-123)",
245
252
  },
246
253
  ],
247
254
  output: {
@@ -48,10 +48,17 @@ export function cutEarlier(text) {
48
48
  }
49
49
  /**
50
50
  * Comments as an MCP read returns them: a bare array, or one wrapped under
51
- * `comments` / `nodes`; each a string or an object with `body` and an optional
52
- * `created_at` (GitHub) / `createdAt` (Linear).
51
+ * `comments` / `nodes` (Jira's adds a `data` envelope); each a string or an object
52
+ * with `body` and an optional `created_at` (GitHub) / `createdAt` (Linear) /
53
+ * `created` (Jira).
53
54
  */
54
55
  export function parseComments(raw) {
56
+ const outer = raw;
57
+ const inner = outer !== null && typeof outer === "object" && !Array.isArray(outer) && "data" in outer
58
+ ? outer.data
59
+ : raw;
60
+ if (inner !== raw)
61
+ return parseComments(inner);
55
62
  const wrapped = raw;
56
63
  const list = Array.isArray(raw)
57
64
  ? raw
@@ -71,7 +78,7 @@ export function parseComments(raw) {
71
78
  const obj = (item ?? {});
72
79
  if (typeof obj.body !== "string")
73
80
  return null;
74
- const at = obj.created_at ?? obj.createdAt;
81
+ const at = obj.created_at ?? obj.createdAt ?? obj.created;
75
82
  out.push({ body: obj.body, createdAt: typeof at === "string" ? at : undefined });
76
83
  }
77
84
  return out;
@@ -170,19 +177,25 @@ export function transitionLabels(current, t) {
170
177
  };
171
178
  }
172
179
  /**
173
- * Linear's issue state for the same transition, as the workflows set it: a
174
- * shipped or failed issue waits on a human ("In Review"); a phase
175
- * starting is "In Progress". Null when the transition sets no state.
180
+ * The issue state the workflows set for the same transition, on a tracker whose
181
+ * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
182
+ * or failed issue waits on a human (`review`); a phase starting is `progress`.
183
+ * The workflows write it alone, so a name the team or project lacks leaves the
184
+ * labels landed. Null under github (the Projects v2 board moves instead) and
185
+ * none, or when the transition sets no state.
176
186
  */
177
- export function linearState(t, board) {
187
+ export function trackerState(t, board, cfg) {
188
+ const states = cfg.issueTracker === "linear" ? cfg.linear : cfg.issueTracker === "jira" ? cfg.jira : null;
189
+ if (states === null)
190
+ return null;
178
191
  if (t.phase === "merged" || t.failed === true)
179
- return "In Review";
192
+ return states.review;
180
193
  if (t.phase !== undefined)
181
- return "In Progress";
194
+ return states.progress;
182
195
  if (board === "review")
183
- return "In Review";
196
+ return states.review;
184
197
  if (board === "progress")
185
- return "In Progress";
198
+ return states.progress;
186
199
  return null;
187
200
  }
188
201
  const ON_OFF = { on: true, off: false };
@@ -208,7 +221,7 @@ function boardPayload(ctx, status) {
208
221
  const root = repoRoot(ctx.cwd);
209
222
  const tracker = readBkitConfig(root).issueTracker;
210
223
  if (tracker !== "github") {
211
- if (tracker === "linear")
224
+ if (tracker === "linear" || tracker === "jira")
212
225
  ctx.log("Board status carried by issue state — no separate update.");
213
226
  return { board: null, boardSkipped: `tracker-${tracker}` };
214
227
  }
@@ -283,7 +296,7 @@ function labelsVerb(ctx) {
283
296
  labels,
284
297
  changed: add.length + remove.length > 0,
285
298
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
286
- linearState: linearState(t, board),
299
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
287
300
  board: payload,
288
301
  boardSkipped,
289
302
  });
@@ -520,7 +533,7 @@ export const issuesCommand = {
520
533
  run: textVerb,
521
534
  },
522
535
  labels: {
523
- summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
536
+ summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
524
537
  flags: [
525
538
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
526
539
  {
@@ -543,7 +556,7 @@ export const issuesCommand = {
543
556
  labels: "the full label set to write",
544
557
  changed: "whether add or remove is non-empty",
545
558
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
546
- linearState: "Linear issue state for this transition, or null",
559
+ trackerState: "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
547
560
  board: "projects payloads {addItem, listItems, updateItem}, or null",
548
561
  boardSkipped: "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
549
562
  },
@@ -425,23 +425,38 @@ export function checkOnlyBookkeeping(root, o) {
425
425
  if (gitRaw(root, ["merge-base", "--is-ancestor", o.from, o.to]).status !== 0) {
426
426
  return { kind: "not-ancestor" };
427
427
  }
428
- const changed = (specs) => gitRaw(root, [
428
+ const diff = changedOutside(root, o.from, o.to, bookPathspecs(o.month, o.fid, "pr"));
429
+ if (!diff.ok)
430
+ return { kind: "diff-failed", stderr: diff.stderr };
431
+ return diff.outside.length ? { kind: "outside", outside: diff.outside } : { kind: "ok" };
432
+ }
433
+ /**
434
+ * Every path changed in `from..to`, and the ones no pathspec in `specs` matches, both
435
+ * sorted. Git does the matching, so `specs` take pathspec magic (`:(glob)`). Renames
436
+ * count as a delete plus an add, so both paths must match.
437
+ */
438
+ export function changedOutside(root, from, to, specs) {
439
+ const diff = (only) => gitRaw(root, [
429
440
  "diff",
430
441
  "--name-only",
431
442
  "-z",
432
443
  "--no-renames",
433
- o.from,
434
- o.to,
435
- ...(specs.length ? ["--", ...specs] : []),
444
+ from,
445
+ to,
446
+ ...(only.length ? ["--", ...only] : []),
436
447
  ]);
437
- const all = changed([]);
438
- const book = changed(bookPathspecs(o.month, o.fid, "pr"));
439
- if (all.status !== 0 || book.status !== 0) {
440
- return { kind: "diff-failed", stderr: all.status !== 0 ? all.stderr : book.stderr };
441
- }
448
+ const all = diff([]);
449
+ if (all.status !== 0)
450
+ return { ok: false, stderr: all.stderr };
451
+ const changed = [...new Set(nulList(all.stdout))].sort();
452
+ // No specs = nothing allowed: `git diff` with no pathspec would match every path.
453
+ if (specs.length === 0)
454
+ return { ok: true, changed, outside: changed };
455
+ const book = diff(specs);
456
+ if (book.status !== 0)
457
+ return { ok: false, stderr: book.stderr };
442
458
  const allowed = new Set(nulList(book.stdout));
443
- const outside = [...new Set(nulList(all.stdout).filter((p) => !allowed.has(p)))].sort();
444
- return outside.length ? { kind: "outside", outside } : { kind: "ok" };
459
+ return { ok: true, changed, outside: changed.filter((p) => !allowed.has(p)) };
445
460
  }
446
461
  function onlyBookkeeping(ctx) {
447
462
  const month = required(ctx, "month");
@@ -115,11 +115,13 @@ function refFlag(value, flag) {
115
115
  const FID_FORMAT = {
116
116
  github: /^[0-9]+-[a-z0-9-]+$/,
117
117
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
118
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
118
119
  none: /^[a-z0-9][a-z0-9-]*$/,
119
120
  };
120
121
  const ISSUE_FORMAT = {
121
122
  github: /^[0-9]+$/,
122
123
  linear: /^[A-Z]+-[0-9]+$/,
124
+ jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
123
125
  };
124
126
  /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
125
127
  export function prMarker(tracker, fid, issue) {
@@ -597,7 +599,7 @@ export const prsCommand = {
597
599
  {
598
600
  name: "issue",
599
601
  type: "string",
600
- help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
602
+ help: "issue id for the marker (github: 123 or #123; linear / jira: ABC-123)",
601
603
  },
602
604
  BASE_FLAG,
603
605
  HEAD_FLAG,
@@ -11,6 +11,7 @@ import * as path from "node:path";
11
11
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
12
12
  import { DEV, EXIT, git, repoRoot, runGit, runTool } from "../lib.js";
13
13
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
14
+ import { readBkitConfig, trackerScope } from "../../shared/settings.js";
14
15
  /** Exit code: neither gh nor the origin remote named an owner/repo. */
15
16
  export const EXIT_NO_REPO = 3;
16
17
  /** Exit code: HEAD is detached, so there is no current branch (and --allow-detached was not given). */
@@ -112,6 +113,9 @@ export const repoCommand = {
112
113
  bkitLatest: "newest published @cbartens/bkit, asked at most once a day (null when offline, opted out via BKIT_NO_UPDATE_CHECK, or unpinned)",
113
114
  bkitOutdated: "true when bkitVersion is older than bkitLatest (null when either is unknown)",
114
115
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
116
+ trackerTeam: "package.json bkit.linear.team under linear, else null",
117
+ trackerProject: "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
118
+ trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
115
119
  },
116
120
  exitCodes: {
117
121
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -157,6 +161,7 @@ export const repoCommand = {
157
161
  bkitLatest: latest.latest,
158
162
  bkitOutdated: latest.outdated,
159
163
  bkitAdvisory: latest.advisory,
164
+ ...trackerScope(readBkitConfig(root)),
160
165
  });
161
166
  if (branch === null && ctx.flags.allowDetached !== true) {
162
167
  ctx.log("HEAD is detached — no current branch");
@@ -43,6 +43,8 @@ const ANALYSIS_PLACEHOLDER = "_(no analysis yet; run @bkit-utility-update-roadma
43
43
  const NOTES_PRE_PLACEHOLDER = "## Notes\n\n_(above the bkit list — yours, never overwritten)_";
44
44
  const NOTES_POST_PLACEHOLDER = "## Notes\n\n_(end of the board — yours, never overwritten)_";
45
45
  const BANNER = "> Generated tables — do not hand-edit the `bkit` tables; append to `.bkit/issues.jsonl` instead (an `ABANDONED` row hides a FID from every section). `## Notes` blocks are yours and are never overwritten. Everything above the first marker is also yours. notes-post is last. Analysis list length: `package.json` key `bkit.roadmapNext` (positive integer; absent or invalid → 25).";
46
+ /** Fixed related-utilities line; `@bkit-audit-generate` ends every run with the same text. */
47
+ export const RELATED_UTILITIES = "> Related utilities, run on demand: `@bkit-utility-update-roadmap` ranks the next best items in `docs/roadmap.md`; `@bkit-utility-update-tracker` brings tracker issues in line with the tracker rules; `@bkit-utility-update-deferrals` and `@bkit-utility-update-failures` close ledger rows the code already resolved; `@bkit-utility-update-decisions`, `@bkit-utility-update-knowledge` and `@bkit-utility-update-documentation` correct ledgers and docs the code has since contradicted.";
46
48
  /** Newest SHIPPED rows on the board; older ones stay in the ledger. */
47
49
  export const SHIPPED_ON_BOARD = 10;
48
50
  const SECTIONS = [
@@ -100,7 +102,7 @@ function table(rows) {
100
102
  ];
101
103
  }
102
104
  export function statusBlock(p, now) {
103
- const out = [BANNER, "", "## bkit", "", `_(refreshed ${now})_`];
105
+ const out = [BANNER, "", RELATED_UTILITIES, "", "## bkit", "", `_(refreshed ${now})_`];
104
106
  for (const [bucket, , heading] of SECTIONS)
105
107
  out.push("", heading, "", ...table(p[bucket]));
106
108
  return out.join("\n");
@@ -16,7 +16,7 @@ import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
16
16
  import { resolveRepoSlug } from "../../ledgers/telemetry.js";
17
17
  import { getPromptsRoot } from "../../shared/package-roots.js";
18
18
  import { CommandError, EXIT, repoRoot, runGit, } from "../lib.js";
19
- import { FID_PATTERNS, readIssueTracker } from "./fids.js";
19
+ import { FID_PATTERNS, normaliseFid, readIssueTracker } from "./fids.js";
20
20
  import { buildComment } from "./issues.js";
21
21
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
22
  import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readRunsAt, statusFile, str, } from "./status.js";
@@ -324,7 +324,7 @@ function gateChecks(cwd, o) {
324
324
  }
325
325
  if (o.fid !== undefined) {
326
326
  const tracker = readIssueTracker(cwd);
327
- const fid = tracker === "linear" ? o.fid.toLowerCase() : o.fid;
327
+ const fid = normaliseFid(o.fid, tracker);
328
328
  add(`fid ${fid}`, FID_PATTERNS[tracker].test(fid)
329
329
  ? undefined
330
330
  : `does not match the ${tracker} shape ${FID_PATTERNS[tracker].source}`, `${tracker} shape`);
@@ -22,11 +22,12 @@ import * as path from "node:path";
22
22
  import { appendLine, fold, runNumber, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
23
23
  import { appendLine as telemetryLine, foldFrom, resolveRepoSlug, validate, workflowTelemetry, } from "../../ledgers/telemetry.js";
24
24
  import { readBkitVersion } from "../../install/version-file.js";
25
+ import { readBkitConfig } from "../../shared/settings.js";
25
26
  import { gradeCompliance } from "../comply.js";
26
27
  import { landDir, pushToDev } from "../land.js";
27
28
  import { CommandError, DEV, EXIT, git, isSharedBranch, parseJson, repoRoot, runGh, runGit, statusLocation, statusRelPath, } from "../lib.js";
28
29
  import { anchorBkitStatus, pushBranch, readAnchor, stampAnchor } from "./branches.js";
29
- import { AUTO_LABEL, AUTO_ROUTE_SUFFIX, buildComment, linearState, transitionLabels, } from "./issues.js";
30
+ import { AUTO_LABEL, AUTO_ROUTE_SUFFIX, buildComment, trackerState, transitionLabels, } from "./issues.js";
30
31
  import { EXIT_EMPTY, commitBookkeeping, unionLedgers } from "./ledgers.js";
31
32
  import { EXIT_REMOVE_FAILED, EXIT_SPLIT_BUCKET, acquireWorkflowLock, owns, readHolder, releaseLock, resolveMonth, workflowLockPath, } from "./locks.js";
32
33
  import { mergePr, probePr } from "./prs.js";
@@ -172,9 +173,11 @@ function failVerb(ctx) {
172
173
  }
173
174
  const merged = prState === "MERGED";
174
175
  const transition = merged ? { phase: "merged" } : { failed: true };
175
- const labels = transitionLabels(list(ctx.flags.label), transition).labels;
176
+ const current = list(ctx.flags.label);
177
+ const labels = transitionLabels(current, transition).labels;
176
178
  if (merged && !labels.includes("bkit:failed"))
177
179
  labels.push("bkit:failed");
180
+ const add = labels.filter((l) => !current.includes(l));
178
181
  // The failure comment, when the step is named.
179
182
  let comment = null;
180
183
  const stepNumber = str(ctx.flags.stepNumber);
@@ -197,8 +200,9 @@ function failVerb(ctx) {
197
200
  sentinels: state.sentinels,
198
201
  handoverNeeded: token !== undefined &&
199
202
  (ctx.flags.maxExceeded === true || state.sentinels.length > 0 || state.soak),
203
+ add,
200
204
  labels,
201
- linearState: linearState(transition, undefined),
205
+ trackerState: trackerState(transition, undefined, readBkitConfig(repoRoot(ctx.cwd))),
202
206
  prState,
203
207
  comment,
204
208
  });
@@ -1223,8 +1227,9 @@ export const workflowsCommand = {
1223
1227
  lock: "{path, existed, released, heldBy}: heldBy is another owner's lock line, left in place; null without --token",
1224
1228
  sentinels: "[{name, path}] sentinels that existed before this call removed them",
1225
1229
  handoverNeeded: "--max-exceeded, a sentinel existed, or a debug run in SOAK mode: write the abort handover",
1230
+ add: "labels in the set that the issue does not carry yet",
1226
1231
  labels: "the label set to write: the current labels plus bkit:failed (and bkit:merged for a merged ship PR)",
1227
- linearState: "the Linear state for the failed issue",
1232
+ trackerState: "the Linear or Jira state for the failed issue (null under github, none)",
1228
1233
  prState: "the --pr PR's state, or null",
1229
1234
  comment: "the failure comment body (with --step-number), else null",
1230
1235
  },