@cbartens/bkit 5.4.0 → 5.5.1

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 (125) hide show
  1. package/.bkit/README.md +19 -7
  2. package/.bkit/core/.agents/rules.md +24 -9
  3. package/.bkit/core/.bkit/README.md +18 -6
  4. package/.bkit/core/.bkit/cloud.md +46 -15
  5. package/.bkit/core/.bkit/comparison.md +2 -2
  6. package/.bkit/core/.bkit/install.md +19 -18
  7. package/.bkit/core/.bkit/pipeline.md +3 -1
  8. package/.bkit/core/.bkit/prompts.md +38 -20
  9. package/.bkit/core/.bkit/providers.md +6 -6
  10. package/.bkit/core/.bkit/templates.md +44 -13
  11. package/.bkit/core/.bkit/trackers.md +99 -35
  12. package/.bkit/core/.bkit/workflows.md +50 -45
  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/ci-yml.ts +0 -1
  18. package/.bkit/core/engine/checks/after/github.ts +42 -78
  19. package/.bkit/core/engine/checks/after/index.ts +1 -6
  20. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  21. package/.bkit/core/engine/checks/before/env.ts +28 -18
  22. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  23. package/.bkit/core/engine/checks/tips/catalogue.ts +15 -2
  24. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  25. package/.bkit/core/engine/cli.ts +7 -5
  26. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  27. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  28. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  29. package/.bkit/core/engine/commands/workflow/issues.ts +61 -63
  30. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  31. package/.bkit/core/engine/commands/workflow/prs.ts +3 -1
  32. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  33. package/.bkit/core/engine/commands/workflow/roadmap.ts +5 -1
  34. package/.bkit/core/engine/commands/workflow/steps.ts +2 -2
  35. package/.bkit/core/engine/commands/workflow/workflows.ts +9 -4
  36. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  37. package/.bkit/core/engine/install/manifest.ts +31 -10
  38. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  39. package/.bkit/core/engine/install/modules/core.ts +153 -4
  40. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  41. package/.bkit/core/engine/install/write.ts +37 -1
  42. package/.bkit/core/engine/render/trackers.ts +35 -23
  43. package/.bkit/core/engine/shared/egress.ts +6 -0
  44. package/.bkit/core/engine/shared/settings.ts +130 -11
  45. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  46. package/.bkit/core/prompts/bkit-audit-generate.md +42 -12
  47. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  48. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  49. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  50. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  51. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  52. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  53. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  54. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  55. package/.bkit/core/prompts/bkit-design-generate.md +4 -1
  56. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  57. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  58. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  59. package/.bkit/core/prompts/bkit-utility-update-decisions.md +3 -1
  60. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +3 -1
  61. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  62. package/.bkit/core/prompts/bkit-utility-update-failures.md +3 -1
  63. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +3 -1
  64. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +9 -2
  65. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  66. package/.bkit/core/workflows/bkit-auto.md +19 -6
  67. package/.bkit/core/workflows/bkit-build.md +59 -17
  68. package/.bkit/core/workflows/bkit-debug.md +64 -20
  69. package/.bkit/core/workflows/bkit-design.md +83 -28
  70. package/.bkit/core/workflows/bkit-plan.md +61 -20
  71. package/.bkit/core/workflows/bkit-ship.md +48 -18
  72. package/.bkit/shared/.bkit/.env.example +8 -0
  73. package/.bkit/shared/.claude/settings.json +3 -1
  74. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  75. package/.bkit/shared/.cursor/mcp.json +11 -4
  76. package/.bkit/shared/.mcp.json +11 -4
  77. package/.bkit/shared/.opencode/opencode.json +2 -0
  78. package/.bkit/shared/docs/deployments.md +6 -7
  79. package/.bkit/shared/docs/security.md +1 -1
  80. package/.bkit/shared/docs/testing.md +13 -5
  81. package/.bkit/templates/.github/renovate.json5 +1 -1
  82. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -115
  83. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  84. package/.bkit/templates/.husky/pre-commit +4 -4
  85. package/.bkit/templates/.husky/pre-push +107 -18
  86. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  87. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  88. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  89. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  90. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  91. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  92. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  93. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  94. package/CHANGELOG.md +67 -1
  95. package/README.md +16 -6
  96. package/dist/checks/after/auth.js +81 -45
  97. package/dist/checks/after/ci-yml.js +0 -1
  98. package/dist/checks/after/github.js +41 -76
  99. package/dist/checks/after/index.js +2 -7
  100. package/dist/checks/after/tools.js +1 -1
  101. package/dist/checks/before/env.js +24 -17
  102. package/dist/checks/before/mcp.js +4 -2
  103. package/dist/checks/tips/catalogue.js +14 -2
  104. package/dist/checks/tips/index.js +4 -2
  105. package/dist/cli.js +7 -5
  106. package/dist/commands/ci/ci.js +100 -0
  107. package/dist/commands/install/uninstall.js +42 -0
  108. package/dist/commands/workflow/fids.js +22 -15
  109. package/dist/commands/workflow/issues.js +53 -61
  110. package/dist/commands/workflow/ledgers.js +26 -11
  111. package/dist/commands/workflow/prs.js +3 -1
  112. package/dist/commands/workflow/repo.js +6 -0
  113. package/dist/commands/workflow/roadmap.js +3 -1
  114. package/dist/commands/workflow/steps.js +2 -2
  115. package/dist/commands/workflow/workflows.js +9 -4
  116. package/dist/commands/workflow/worktrees.js +74 -13
  117. package/dist/install/manifest.js +30 -10
  118. package/dist/install/modules/cloud.js +3 -1
  119. package/dist/install/modules/core.js +157 -5
  120. package/dist/install/modules/opencode.js +6 -0
  121. package/dist/install/write.js +26 -2
  122. package/dist/render/trackers.js +34 -20
  123. package/dist/shared/egress.js +6 -0
  124. package/dist/shared/settings.js +59 -7
  125. package/package.json +14 -3
package/dist/cli.js CHANGED
@@ -230,7 +230,7 @@ export function parseArgs(argv) {
230
230
  }
231
231
  if (arg.startsWith("--")) {
232
232
  const flag = arg.slice(2);
233
- // Value-bearing flag: --tracker=<github|linear|none>
233
+ // Value-bearing flag: --tracker=<github|linear|jira|none>
234
234
  if (flag.startsWith("tracker=")) {
235
235
  const value = flag.slice("tracker=".length);
236
236
  const parsed = parseIssueTracker(value);
@@ -570,18 +570,20 @@ Dependency updaters (copy an example and own it):
570
570
 
571
571
  --auto=<claude|cursor|opencode>
572
572
  Cloud-agent (auto-dispatch) integration (opt-in). --auto=claude needs
573
- tracker=github + the ANTHROPIC_API_KEY repo secret + the Claude GitHub App; --auto=cursor
573
+ tracker=github + the ANTHROPIC_API_KEY repo secret (or the
574
+ ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID repo variables
575
+ for keyless federation) + the Claude GitHub App; --auto=cursor
574
576
  needs tracker=linear; --auto=opencode needs tracker=github + a remote
575
577
  opencode provider (OPENCODE_PROVIDER_KEY). Bare --auto is accepted on
576
578
  uninstall only.
577
579
 
578
580
  Cross-cutting / modifiers:
579
- --tracker=<name> Wire issue tracker integration. Values: github, linear, none
581
+ --tracker=<name> Wire issue tracker integration. Values: github, linear, jira, none
580
582
  (default). Records bkit.issueTracker in package.json and substitutes
581
583
  tracker snippets into command mirrors. Re-renders every installed
582
584
  host, and works alone (bkit install --tracker=github). Switching is
583
- free; a switch removes the old linear MCP entry unless you edited it
584
- (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
585
+ free; a switch removes the old linear or jira MCP entry unless you
586
+ edited it (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
585
587
 
586
588
  Install flags:
587
589
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -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 };
@@ -194,46 +207,28 @@ function onOff(v, flag) {
194
207
  throw new CommandError(EXIT.USAGE, `--${flag} must be on or off`);
195
208
  return b;
196
209
  }
197
- const BOARD_OPTION = {
198
- progress: "progressOptionId",
199
- review: "reviewOptionId",
200
- };
210
+ const BOARD_STATES = new Set(["progress", "review"]);
201
211
  /**
202
- * The three `projects_write` / `projects_list` payloads that move an issue on the
203
- * Projects v2 board, from `bkit.githubProject`. Payload keys are the MCP tools'
204
- * own argument names. The workflow fills `item_id` on `updateItem` from the
205
- * `listItems` entry whose issue number matches.
212
+ * The two `projects_write` payloads that move an issue on the Projects v2 board,
213
+ * from `bkit.github`. Payload keys are the MCP tool's own argument names: the
214
+ * board item is found by its issue, and Status is set by option name.
206
215
  */
207
216
  function boardPayload(ctx, status) {
208
- const root = repoRoot(ctx.cwd);
209
- const tracker = readBkitConfig(root).issueTracker;
217
+ const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
210
218
  if (tracker !== "github") {
211
- if (tracker === "linear")
219
+ if (tracker === "linear" || tracker === "jira")
212
220
  ctx.log("Board status carried by issue state — no separate update.");
213
221
  return { board: null, boardSkipped: `tracker-${tracker}` };
214
222
  }
215
- const gp = readBkitConfig(root).githubProject;
216
- if (gp === false)
223
+ if (github.project === false)
217
224
  return { board: null, boardSkipped: "opted-out" };
218
- const cfg = gp ?? {};
219
- const owner = cfg.owner;
220
- const number = Number(cfg.number);
221
- if (typeof owner !== "string" || owner === "" || !Number.isInteger(number) || number <= 0) {
222
- ctx.log("GitHub project not configured in package.json");
223
- return { board: null, boardSkipped: "not-configured" };
224
- }
225
- // projects_write rejects anything but the numeric field id (a `PVTSSF_…` node id
226
- // included), so a wrong value is a skip with a reason, not a silent no-op.
227
- const raw = cfg.statusFieldId;
228
- const fieldId = typeof raw === "number" ? raw : /^[0-9]+$/.test(String(raw)) ? Number(raw) : NaN;
229
- if (!Number.isInteger(fieldId)) {
230
- ctx.log(`bkit.githubProject.statusFieldId "${String(raw)}" is not the numeric Status field id`);
231
- return { board: null, boardSkipped: "status-field-id-not-number" };
232
- }
233
- const option = cfg[BOARD_OPTION[status]];
234
- if (typeof option !== "string" || option === "") {
235
- ctx.log(`bkit.githubProject.${BOARD_OPTION[status]} is not set`);
236
- return { board: null, boardSkipped: "option-id-missing" };
225
+ if (github.project === null) {
226
+ if (github.projectUrl === null) {
227
+ ctx.log("GitHub project not configured in package.json");
228
+ return { board: null, boardSkipped: "not-configured" };
229
+ }
230
+ ctx.log(`bkit.github.project "${github.projectUrl}" is not a GitHub Projects board URL`);
231
+ return { board: null, boardSkipped: "project-url-invalid" };
237
232
  }
238
233
  const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
239
234
  const ownerRepo = String(ctx.flags.ownerRepo ?? "");
@@ -241,22 +236,17 @@ function boardPayload(ctx, status) {
241
236
  if (!/^[0-9]+$/.test(issue) || !itemOwner || !itemRepo || extra !== undefined) {
242
237
  throw new CommandError(EXIT.USAGE, "--board needs --issue=<number> and --owner-repo=<owner>/<repo>");
243
238
  }
244
- const project = { owner, owner_type: "org", project_number: number };
239
+ const { owner, ownerType, number } = github.project;
240
+ const project = { owner, owner_type: ownerType, project_number: number };
241
+ const item = { item_owner: itemOwner, item_repo: itemRepo, issue_number: Number(issue) };
245
242
  return {
246
243
  board: {
247
- addItem: {
248
- method: "add_project_item",
249
- ...project,
250
- item_type: "issue",
251
- item_owner: itemOwner,
252
- item_repo: itemRepo,
253
- issue_number: Number(issue),
254
- },
255
- listItems: { method: "list_project_items", ...project, query: issue },
244
+ addItem: { method: "add_project_item", ...project, item_type: "issue", ...item },
256
245
  updateItem: {
257
246
  method: "update_project_item",
258
247
  ...project,
259
- updated_field: { id: fieldId, value: option },
248
+ ...item,
249
+ updated_field: { name: "Status", value: github[status] },
260
250
  },
261
251
  },
262
252
  boardSkipped: null,
@@ -271,19 +261,21 @@ function labelsVerb(ctx) {
271
261
  if (phase !== undefined && failed === true)
272
262
  throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
273
263
  const board = str(ctx.flags.board);
274
- if (board !== undefined && BOARD_OPTION[board] === undefined) {
264
+ if (board !== undefined && !BOARD_STATES.has(board)) {
275
265
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
276
266
  }
277
267
  const t = { phase, failed };
278
268
  const { add, remove, labels } = transitionLabels(ctx.flags.label ?? [], t);
279
- const { board: payload, boardSkipped } = board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
269
+ const { board: payload, boardSkipped } = board === undefined
270
+ ? { board: null, boardSkipped: null }
271
+ : boardPayload(ctx, board);
280
272
  ctx.emit({
281
273
  add,
282
274
  remove,
283
275
  labels,
284
276
  changed: add.length + remove.length > 0,
285
277
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
286
- linearState: linearState(t, board),
278
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
287
279
  board: payload,
288
280
  boardSkipped,
289
281
  });
@@ -520,7 +512,7 @@ export const issuesCommand = {
520
512
  run: textVerb,
521
513
  },
522
514
  labels: {
523
- summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
515
+ summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
524
516
  flags: [
525
517
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
526
518
  {
@@ -543,9 +535,9 @@ export const issuesCommand = {
543
535
  labels: "the full label set to write",
544
536
  changed: "whether add or remove is non-empty",
545
537
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
546
- linearState: "Linear issue state for this transition, or null",
547
- board: "projects payloads {addItem, listItems, updateItem}, or null",
548
- boardSkipped: "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
538
+ trackerState: "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
539
+ board: "projects_write payloads {addItem, updateItem}, or null",
540
+ boardSkipped: "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name>",
549
541
  },
550
542
  run: labelsVerb,
551
543
  },
@@ -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,10 @@ 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",
119
+ trackerBoard: "{ownerType, owner, number} read from package.json bkit.github.project under github, else null",
115
120
  },
116
121
  exitCodes: {
117
122
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -157,6 +162,7 @@ export const repoCommand = {
157
162
  bkitLatest: latest.latest,
158
163
  bkitOutdated: latest.outdated,
159
164
  bkitAdvisory: latest.advisory,
165
+ ...trackerScope(readBkitConfig(root)),
160
166
  });
161
167
  if (branch === null && ctx.flags.allowDetached !== true) {
162
168
  ctx.log("HEAD is detached — no current branch");