@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
@@ -346,7 +346,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
346
346
  if (arg.startsWith("--")) {
347
347
  const flag = arg.slice(2);
348
348
 
349
- // Value-bearing flag: --tracker=<github|linear|none>
349
+ // Value-bearing flag: --tracker=<github|linear|jira|none>
350
350
  if (flag.startsWith("tracker=")) {
351
351
  const value = flag.slice("tracker=".length);
352
352
  const parsed = parseIssueTracker(value);
@@ -727,18 +727,20 @@ Dependency updaters (copy an example and own it):
727
727
 
728
728
  --auto=<claude|cursor|opencode>
729
729
  Cloud-agent (auto-dispatch) integration (opt-in). --auto=claude needs
730
- tracker=github + the ANTHROPIC_API_KEY repo secret + the Claude GitHub App; --auto=cursor
730
+ tracker=github + the ANTHROPIC_API_KEY repo secret (or the
731
+ ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID repo variables
732
+ for keyless federation) + the Claude GitHub App; --auto=cursor
731
733
  needs tracker=linear; --auto=opencode needs tracker=github + a remote
732
734
  opencode provider (OPENCODE_PROVIDER_KEY). Bare --auto is accepted on
733
735
  uninstall only.
734
736
 
735
737
  Cross-cutting / modifiers:
736
- --tracker=<name> Wire issue tracker integration. Values: github, linear, none
738
+ --tracker=<name> Wire issue tracker integration. Values: github, linear, jira, none
737
739
  (default). Records bkit.issueTracker in package.json and substitutes
738
740
  tracker snippets into command mirrors. Re-renders every installed
739
741
  host, and works alone (bkit install --tracker=github). Switching is
740
- free; a switch removes the old linear MCP entry unless you edited it
741
- (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
742
+ free; a switch removes the old linear or jira MCP entry unless you
743
+ edited it (github always stays). Does NOT own AGENTS.md (tracker-agnostic).
742
744
 
743
745
  Install flags:
744
746
  --auto-revert On a Phase 3 blocker, automatically run uninstall and exit 1.
@@ -14,12 +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
 
18
22
  import { spawnSync, type SpawnSyncReturns } from "node:child_process";
19
23
  import * as fs from "node:fs";
20
24
  import * as os from "node:os";
21
25
  import * as path from "node:path";
22
26
 
27
+ import { readBkitConfig } from "../../shared/settings.js";
23
28
  import {
24
29
  CommandError,
25
30
  commitMessage,
@@ -31,6 +36,7 @@ import {
31
36
  type CommandSpec,
32
37
  type RunContext,
33
38
  } from "../lib.js";
39
+ import { changedOutside } from "../workflow/ledgers.js";
34
40
 
35
41
  /** Exit code: slop-scan could not be started (not installed, not executable). */
36
42
  export const EXIT_SLOP_UNAVAILABLE = 3;
@@ -40,6 +46,8 @@ export const EXIT_SLOP_FAILED = 4;
40
46
  export const EXIT_NO_WORKTREE = 5;
41
47
  /** Exit code: vale could not run, or ended with a runtime error (its exit 2). */
42
48
  export const EXIT_VALE_FAILED = 6;
49
+ /** Exit code: a pushed commit, its base, or its `git diff` could not be read. */
50
+ export const EXIT_RANGE_UNKNOWN = 7;
43
51
 
44
52
  /** Branches whose merge-base with HEAD is the default base, in order. */
45
53
  const BASE_CANDIDATES = ["origin/dev", "origin/main"];
@@ -416,6 +424,81 @@ function skipToken(ctx: RunContext): number {
416
424
  return token === null ? EXIT.NO : EXIT.OK;
417
425
  }
418
426
 
427
+ // ---------------------------------------------------------------------------
428
+ // min-push
429
+ // ---------------------------------------------------------------------------
430
+
431
+ /** `bkit.minPushPaths` as git pathspecs: `:(glob)` unless an entry carries its own magic. */
432
+ export const minPushPathspecs = (paths: readonly string[]): string[] =>
433
+ paths.map((p) => (p.startsWith(":") ? p : `:(glob)${p}`));
434
+
435
+ /** Where a pushed commit's range starts: its merge-base with origin/dev, else origin/main. */
436
+ export function pushBase(cwd: string, sha: string): string | null {
437
+ for (const cand of BASE_CANDIDATES) {
438
+ if (!runGit(cwd, ["rev-parse", "--verify", "--quiet", cand]).ok) continue;
439
+ const mb = runGit(cwd, ["merge-base", sha, cand]);
440
+ if (mb.ok && mb.stdout) return mb.stdout;
441
+ }
442
+ return null;
443
+ }
444
+
445
+ function minPush(ctx: RunContext): number {
446
+ const top = runGit(ctx.cwd, ["rev-parse", "--show-toplevel"]);
447
+ if (!top.ok) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${ctx.cwd}`);
448
+ const given = ctx.flags.ref;
449
+ const refs = Array.isArray(given) && given.length > 0 ? given.map(String) : ["HEAD"];
450
+ const baseFlag = typeof ctx.flags.base === "string" && ctx.flags.base ? ctx.flags.base : null;
451
+ const paths = readBkitConfig(top.stdout).minPushPaths;
452
+ const specs = minPushPathspecs(paths);
453
+
454
+ const changed = new Set<string>();
455
+ const outside = new Set<string>();
456
+ for (const ref of refs) {
457
+ const sha = git(ctx.cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
458
+ const base = sha ? (baseFlag ?? pushBase(ctx.cwd, sha)) : null;
459
+ const diff = sha && base ? changedOutside(top.stdout, base, sha, specs) : null;
460
+ if (!diff?.ok) {
461
+ const why = !sha
462
+ ? `cannot read commit '${ref}'`
463
+ : !base
464
+ ? `no base for ${ref} (neither origin/dev nor origin/main resolves)`
465
+ : `'git diff' failed for ${base}..${ref}: ${diff && !diff.ok ? diff.stderr : ""}`;
466
+ ctx.log(`${why} — not proven a min push`);
467
+ ctx.emit({ minPush: false, reason: "unknown", changed: 0, outside: [], paths });
468
+ return EXIT_RANGE_UNKNOWN;
469
+ }
470
+ for (const p of diff.changed) changed.add(p);
471
+ for (const p of diff.outside) outside.add(p);
472
+ }
473
+
474
+ const result = (reason: string | null, code: number, message: string) => {
475
+ ctx.log(message);
476
+ ctx.emit({
477
+ minPush: reason === null,
478
+ reason,
479
+ changed: changed.size,
480
+ outside: [...outside].sort(),
481
+ paths,
482
+ });
483
+ return code;
484
+ };
485
+ if (paths.length === 0) {
486
+ return result("no-paths", EXIT.NO, "bkit.minPushPaths is empty — not a min push");
487
+ }
488
+ if (changed.size === 0) {
489
+ return result("no-changes", EXIT.NO, "the push changes no files — not proven a min push");
490
+ }
491
+ if (outside.size > 0) {
492
+ const first = [...outside].sort()[0];
493
+ return result(
494
+ "outside",
495
+ EXIT.NO,
496
+ `${outside.size} of ${changed.size} changed files match no min-push path (first: ${first})`,
497
+ );
498
+ }
499
+ return result(null, EXIT.OK, `all ${changed.size} changed files match min-push paths`);
500
+ }
501
+
419
502
  export const ciCommand: CommandSpec = {
420
503
  noun: "ci",
421
504
  summary: "Gates CI and the git hooks run.",
@@ -479,5 +562,29 @@ export const ciCommand: CommandSpec = {
479
562
  },
480
563
  run: skipToken,
481
564
  },
565
+ "min-push": {
566
+ summary:
567
+ "Exit 0 when every file a push changes matches bkit.minPushPaths (the pre-push light gate).",
568
+ flags: [
569
+ {
570
+ name: "ref",
571
+ type: "string",
572
+ repeatable: true,
573
+ help: "a pushed commit (default HEAD); its range starts at its merge-base with origin/dev, else origin/main",
574
+ },
575
+ { name: "base", type: "string", help: "start every range here instead" },
576
+ ],
577
+ output: {
578
+ minPush: "true when every changed file matches bkit.minPushPaths",
579
+ reason: "null when a min push; else no-paths | no-changes | outside | unknown",
580
+ changed: "files the push changes, across every ref",
581
+ outside: "the changed files no min-push path matches",
582
+ paths: "bkit.minPushPaths as read",
583
+ },
584
+ exitCodes: {
585
+ [EXIT_RANGE_UNKNOWN]: "a pushed commit, its base, or its git diff could not be read",
586
+ },
587
+ run: minPush,
588
+ },
482
589
  },
483
590
  };
@@ -834,6 +834,12 @@ export async function runUninstall(
834
834
  }
835
835
  }
836
836
 
837
+ // Targeted uninstall: drop the `bkit.*` keys the removed module records, so its advisories
838
+ // stop firing. Core keeps every other key.
839
+ if (!moduleList.includes("core")) {
840
+ stripModuleBkitKeys(moduleList, ctx, result);
841
+ }
842
+
837
843
  // Clean up .agents/ bkit-prefix mirror files
838
844
  // (.claude/commands/bkit-*.md, .claude/agents/bkit-*.md, .opencode/agents/bkit-*.md, etc.)
839
845
  // A dry run lists the same paths in result.deleted and removes nothing.
@@ -1029,6 +1035,46 @@ export async function runUninstall(
1029
1035
  return result;
1030
1036
  }
1031
1037
 
1038
+ /** `package.json` `bkit.*` keys each module records on install. */
1039
+ const MODULE_BKIT_KEYS: Partial<Record<ModuleName, readonly string[]>> = {
1040
+ cloud: ["cloudAgents"],
1041
+ opencode: ["opencodeProvider", "opencodeProviders"],
1042
+ };
1043
+
1044
+ /**
1045
+ * Remove the `bkit.*` keys recorded by the modules in `moduleList` from the consumer's
1046
+ * package.json, keeping its indent. Lists each removed key in `result.stripped`; a dry run
1047
+ * lists without writing.
1048
+ */
1049
+ function stripModuleBkitKeys(
1050
+ moduleList: ModuleName[],
1051
+ ctx: UninstallContext,
1052
+ result: UninstallResult,
1053
+ ): void {
1054
+ const keys = moduleList.flatMap((m) => MODULE_BKIT_KEYS[m] ?? []);
1055
+ if (keys.length === 0) return;
1056
+ const pkgPath = path.join(ctx.cwd, "package.json");
1057
+ if (!fs.existsSync(pkgPath)) return;
1058
+ const raw = fs.readFileSync(pkgPath, "utf-8");
1059
+ const parsed = parseJson(raw);
1060
+ const pkg = parsed.ok ? (parsed.value as Record<string, unknown> | null) : null;
1061
+ if (pkg === null || !isJsonObject(pkg.bkit as JsonValue)) return;
1062
+ const bkit = pkg.bkit as Record<string, unknown>;
1063
+ const present = keys.filter((k) => k in bkit);
1064
+ if (present.length === 0) return;
1065
+ for (const k of present) {
1066
+ delete bkit[k];
1067
+ result.stripped.push(`package.json#bkit.${k}`);
1068
+ }
1069
+ console.log(
1070
+ `${ctx.logPrefix}${ctx.dryRun ? " [dry-run]" : ""} package.json: removed bkit.${present.join(", bkit.")}`,
1071
+ );
1072
+ if (ctx.dryRun) return;
1073
+ const indentMatch = raw.match(/\n([ \t]+)"/);
1074
+ const indent = indentMatch ? indentMatch[1] : " ";
1075
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + "\n", "utf-8");
1076
+ }
1077
+
1032
1078
  // ---------------------------------------------------------------------------
1033
1079
  // runSurgicalOpencodeUninstall — remove exactly ONE provider block
1034
1080
  // ---------------------------------------------------------------------------
@@ -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
 
12
13
  import * as fs from "node:fs";
13
14
  import * as path from "node:path";
@@ -22,10 +23,16 @@ export type FidTracker = IssueTracker | "any";
22
23
  export const FID_PATTERNS: Readonly<Record<FidTracker, RegExp>> = {
23
24
  github: /^[0-9]+-[a-z0-9-]+$/,
24
25
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
26
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
25
27
  none: /^[a-z0-9][a-z0-9-]*$/,
26
- any: /^([0-9]+|[a-z]+-[0-9]+)-[a-z0-9-]+$/,
28
+ any: /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)-[a-z0-9-]+$/,
27
29
  };
28
30
 
31
+ /** Trackers whose issue id is a `{KEY}-{N}` key, carried lowercased in the FID. */
32
+ const KEYED: ReadonlySet<FidTracker> = new Set(["linear", "jira"]);
33
+ /** The uppercase issue key each keyed tracker mints. */
34
+ const ISSUE_KEY = { linear: /^[A-Z]+-[0-9]+$/, jira: /^[A-Z][A-Z0-9]+-[0-9]+$/ } as const;
35
+
29
36
  /** The slug every recovered FID must pass before it touches a path (auto's branch fallback). */
30
37
  const SLUG = FID_PATTERNS.none;
31
38
 
@@ -36,7 +43,7 @@ export const EXIT_SEVERAL = 4;
36
43
 
37
44
  /**
38
45
  * Features already logged for an issue: every `docs/plans/{YYYYMM}/logs/{issue}-*`
39
- * folder, the issue id lowercased (a Linear FID carries it lowercased). Sorted, unique.
46
+ * folder, the issue id lowercased (a Linear or Jira FID carries it lowercased). Sorted, unique.
40
47
  */
41
48
  export function logged(root: string, issue: string): string[] {
42
49
  const key = `${issue.replace(/^#/, "").toLowerCase()}-`;
@@ -87,29 +94,29 @@ function trackerFlag(value: string | undefined, cwd: string, allowAny: boolean):
87
94
  if (!t) {
88
95
  throw new CommandError(
89
96
  EXIT.USAGE,
90
- `--tracker must be github, linear, none${allowAny ? ", any" : ""}; got "${value}"`,
97
+ `--tracker must be github, linear, jira, none${allowAny ? ", any" : ""}; got "${value}"`,
91
98
  );
92
99
  }
93
100
  return t;
94
101
  }
95
102
 
96
- /** Linear issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
103
+ /** Linear and Jira issue ids arrive uppercase (`ABC-123`); the FID carries them lowercased. */
97
104
  export const normaliseFid = (fid: string, tracker: FidTracker) =>
98
- tracker === "linear" ? fid.toLowerCase() : fid;
105
+ KEYED.has(tracker) ? fid.toLowerCase() : fid;
99
106
 
100
107
  /**
101
108
  * The tracker issue id a FID embeds, or null when it embeds none:
102
- * github the leading numeric segment, linear the first two segments uppercased.
109
+ * github the leading numeric segment, linear and jira the first two segments uppercased.
103
110
  */
104
111
  export function issueIdOf(fid: string, tracker: FidTracker): string | null {
105
112
  const [first = "", second = ""] = fid.split("-");
106
113
  if (tracker === "github") return /^[0-9]+$/.test(first) ? first : null;
107
- if (tracker === "linear") {
114
+ if (KEYED.has(tracker)) {
108
115
  const id = `${first}-${second}`.toUpperCase();
109
- return /^[A-Z]+-[0-9]+$/.test(id) ? id : null;
116
+ return ISSUE_KEY[tracker as "linear" | "jira"].test(id) ? id : null;
110
117
  }
111
118
  if (tracker === "any") {
112
- const m = /^([0-9]+|[a-z]+-[0-9]+)(?=-)/.exec(fid);
119
+ const m = /^([0-9]+|[a-z][a-z0-9]*-[0-9]+)(?=-)/.exec(fid);
113
120
  return m ? m[1]!.toUpperCase() : null;
114
121
  }
115
122
  return null;
@@ -119,6 +126,7 @@ export function issueIdOf(fid: string, tracker: FidTracker): string | null {
119
126
  const MARKERS: Readonly<Record<IssueTracker, RegExp>> = {
120
127
  github: /<!-- bkit:issue=#([0-9]+) bkit:fid=(\S+) -->/,
121
128
  linear: /<!-- bkit:issue=([A-Za-z]+-[0-9]+) bkit:fid=(\S+) -->/,
129
+ jira: /<!-- bkit:issue=([A-Za-z][A-Za-z0-9]+-[0-9]+) bkit:fid=(\S+) -->/,
122
130
  none: /<!-- bkit:fid=(\S+) -->/,
123
131
  };
124
132
 
@@ -134,7 +142,7 @@ export function fromMarker(text: string, tracker: IssueTracker): ParsedFid | nul
134
142
  if (!m) return null;
135
143
  const fid = normaliseFid(m[m.length - 1]!, tracker);
136
144
  if (!FID_PATTERNS[tracker].test(fid)) return null;
137
- const issueId = tracker === "none" ? null : tracker === "linear" ? m[1]!.toUpperCase() : m[1]!;
145
+ const issueId = tracker === "none" ? null : KEYED.has(tracker) ? m[1]!.toUpperCase() : m[1]!;
138
146
  return { fid, issueId, source: "marker" };
139
147
  }
140
148
 
@@ -157,7 +165,7 @@ export function fromBranch(
157
165
  const TRACKER_FLAG: FlagSpec = {
158
166
  name: "tracker",
159
167
  type: "string",
160
- help: "github | linear | none (default: package.json bkit.issueTracker, else none)",
168
+ help: "github | linear | jira | none (default: package.json bkit.issueTracker, else none)",
161
169
  };
162
170
 
163
171
  export const fidsCommand: CommandSpec = {
@@ -168,10 +176,10 @@ export const fidsCommand: CommandSpec = {
168
176
  summary: "Validate a FID for the tracker: exit 0 valid, exit 1 not.",
169
177
  flags: [
170
178
  { name: "fid", type: "string", required: true, help: "feature id to check" },
171
- { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = github or linear shape (CI_DEV)` },
179
+ { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = any tracker's shape (CI_DEV)` },
172
180
  ],
173
181
  output: {
174
- fid: "the FID as checked (linear: lowercased)",
182
+ fid: "the FID as checked (linear, jira: lowercased)",
175
183
  tracker: "tracker the shape came from",
176
184
  valid: "true when the FID matches",
177
185
  pattern: "the regex checked",
@@ -267,7 +275,7 @@ export const fidsCommand: CommandSpec = {
267
275
  name: "issue",
268
276
  type: "string",
269
277
  required: true,
270
- help: "tracker issue id (github: 123 or #123; linear: ABC-123)",
278
+ help: "tracker issue id (github: 123 or #123; linear / jira: ABC-123)",
271
279
  },
272
280
  ],
273
281
  output: {
@@ -17,7 +17,7 @@ import {
17
17
  type CommandSpec,
18
18
  type RunContext,
19
19
  } from "../lib.js";
20
- import { readBkitConfig } from "../../shared/settings.js";
20
+ import { readBkitConfig, type BkitConfig } from "../../shared/settings.js";
21
21
  import { str } from "./status.js";
22
22
 
23
23
  /** Exit code: an input file is missing or not in the expected shape. */
@@ -68,10 +68,17 @@ export function cutEarlier(text: string): { text: string; cut: boolean } {
68
68
 
69
69
  /**
70
70
  * Comments as an MCP read returns them: a bare array, or one wrapped under
71
- * `comments` / `nodes`; each a string or an object with `body` and an optional
72
- * `created_at` (GitHub) / `createdAt` (Linear).
71
+ * `comments` / `nodes` (Jira's adds a `data` envelope); each a string or an object
72
+ * with `body` and an optional `created_at` (GitHub) / `createdAt` (Linear) /
73
+ * `created` (Jira).
73
74
  */
74
75
  export function parseComments(raw: unknown): IssueComment[] | null {
76
+ const outer = raw as { data?: unknown } | null;
77
+ const inner =
78
+ outer !== null && typeof outer === "object" && !Array.isArray(outer) && "data" in outer
79
+ ? outer.data
80
+ : raw;
81
+ if (inner !== raw) return parseComments(inner);
75
82
  const wrapped = raw as { comments?: unknown; nodes?: unknown } | null;
76
83
  const list = Array.isArray(raw)
77
84
  ? raw
@@ -89,7 +96,7 @@ export function parseComments(raw: unknown): IssueComment[] | null {
89
96
  }
90
97
  const obj = (item ?? {}) as Record<string, unknown>;
91
98
  if (typeof obj.body !== "string") return null;
92
- const at = obj.created_at ?? obj.createdAt;
99
+ const at = obj.created_at ?? obj.createdAt ?? obj.created;
93
100
  out.push({ body: obj.body, createdAt: typeof at === "string" ? at : undefined });
94
101
  }
95
102
  return out;
@@ -201,15 +208,25 @@ export function transitionLabels(current: string[], t: LabelTransition) {
201
208
  }
202
209
 
203
210
  /**
204
- * Linear's issue state for the same transition, as the workflows set it: a
205
- * shipped or failed issue waits on a human ("In Review"); a phase
206
- * starting is "In Progress". Null when the transition sets no state.
211
+ * The issue state the workflows set for the same transition, on a tracker whose
212
+ * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
213
+ * or failed issue waits on a human (`review`); a phase starting is `progress`.
214
+ * The workflows write it alone, so a name the team or project lacks leaves the
215
+ * labels landed. Null under github (the Projects v2 board moves instead) and
216
+ * none, or when the transition sets no state.
207
217
  */
208
- export function linearState(t: LabelTransition, board: string | undefined): string | null {
209
- if (t.phase === "merged" || t.failed === true) return "In Review";
210
- if (t.phase !== undefined) return "In Progress";
211
- if (board === "review") return "In Review";
212
- if (board === "progress") return "In Progress";
218
+ export function trackerState(
219
+ t: LabelTransition,
220
+ board: string | undefined,
221
+ cfg: Pick<BkitConfig, "issueTracker" | "linear" | "jira">,
222
+ ): string | null {
223
+ const states =
224
+ cfg.issueTracker === "linear" ? cfg.linear : cfg.issueTracker === "jira" ? cfg.jira : null;
225
+ if (states === null) return null;
226
+ if (t.phase === "merged" || t.failed === true) return states.review;
227
+ if (t.phase !== undefined) return states.progress;
228
+ if (board === "review") return states.review;
229
+ if (board === "progress") return states.progress;
213
230
  return null;
214
231
  }
215
232
 
@@ -222,48 +239,31 @@ function onOff(v: unknown, flag: string): boolean | undefined {
222
239
  return b;
223
240
  }
224
241
 
225
- const BOARD_OPTION: Record<string, string> = {
226
- progress: "progressOptionId",
227
- review: "reviewOptionId",
228
- };
242
+ const BOARD_STATES = new Set(["progress", "review"]);
229
243
 
230
244
  /**
231
- * The three `projects_write` / `projects_list` payloads that move an issue on the
232
- * Projects v2 board, from `bkit.githubProject`. Payload keys are the MCP tools'
233
- * own argument names. The workflow fills `item_id` on `updateItem` from the
234
- * `listItems` entry whose issue number matches.
245
+ * The two `projects_write` payloads that move an issue on the Projects v2 board,
246
+ * from `bkit.github`. Payload keys are the MCP tool's own argument names: the
247
+ * board item is found by its issue, and Status is set by option name.
235
248
  */
236
249
  function boardPayload(
237
250
  ctx: RunContext,
238
- status: string,
251
+ status: "progress" | "review",
239
252
  ): { board: Record<string, unknown> | null; boardSkipped: string | null } {
240
- const root = repoRoot(ctx.cwd);
241
- const tracker = readBkitConfig(root).issueTracker;
253
+ const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
242
254
  if (tracker !== "github") {
243
- if (tracker === "linear") ctx.log("Board status carried by issue state — no separate update.");
255
+ if (tracker === "linear" || tracker === "jira")
256
+ ctx.log("Board status carried by issue state — no separate update.");
244
257
  return { board: null, boardSkipped: `tracker-${tracker}` };
245
258
  }
246
- const gp = readBkitConfig(root).githubProject;
247
- if (gp === false) return { board: null, boardSkipped: "opted-out" };
248
- const cfg = gp ?? {};
249
- const owner = cfg.owner;
250
- const number = Number(cfg.number);
251
- if (typeof owner !== "string" || owner === "" || !Number.isInteger(number) || number <= 0) {
252
- ctx.log("GitHub project not configured in package.json");
253
- return { board: null, boardSkipped: "not-configured" };
254
- }
255
- // projects_write rejects anything but the numeric field id (a `PVTSSF_…` node id
256
- // included), so a wrong value is a skip with a reason, not a silent no-op.
257
- const raw = cfg.statusFieldId;
258
- const fieldId = typeof raw === "number" ? raw : /^[0-9]+$/.test(String(raw)) ? Number(raw) : NaN;
259
- if (!Number.isInteger(fieldId)) {
260
- ctx.log(`bkit.githubProject.statusFieldId "${String(raw)}" is not the numeric Status field id`);
261
- return { board: null, boardSkipped: "status-field-id-not-number" };
262
- }
263
- const option = cfg[BOARD_OPTION[status]!];
264
- if (typeof option !== "string" || option === "") {
265
- ctx.log(`bkit.githubProject.${BOARD_OPTION[status]!} is not set`);
266
- return { board: null, boardSkipped: "option-id-missing" };
259
+ if (github.project === false) return { board: null, boardSkipped: "opted-out" };
260
+ if (github.project === null) {
261
+ if (github.projectUrl === null) {
262
+ ctx.log("GitHub project not configured in package.json");
263
+ return { board: null, boardSkipped: "not-configured" };
264
+ }
265
+ ctx.log(`bkit.github.project "${github.projectUrl}" is not a GitHub Projects board URL`);
266
+ return { board: null, boardSkipped: "project-url-invalid" };
267
267
  }
268
268
  const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
269
269
  const ownerRepo = String(ctx.flags.ownerRepo ?? "");
@@ -274,22 +274,17 @@ function boardPayload(
274
274
  "--board needs --issue=<number> and --owner-repo=<owner>/<repo>",
275
275
  );
276
276
  }
277
- const project = { owner, owner_type: "org", project_number: number };
277
+ const { owner, ownerType, number } = github.project;
278
+ const project = { owner, owner_type: ownerType, project_number: number };
279
+ const item = { item_owner: itemOwner, item_repo: itemRepo, issue_number: Number(issue) };
278
280
  return {
279
281
  board: {
280
- addItem: {
281
- method: "add_project_item",
282
- ...project,
283
- item_type: "issue",
284
- item_owner: itemOwner,
285
- item_repo: itemRepo,
286
- issue_number: Number(issue),
287
- },
288
- listItems: { method: "list_project_items", ...project, query: issue },
282
+ addItem: { method: "add_project_item", ...project, item_type: "issue", ...item },
289
283
  updateItem: {
290
284
  method: "update_project_item",
291
285
  ...project,
292
- updated_field: { id: fieldId, value: option },
286
+ ...item,
287
+ updated_field: { name: "Status", value: github[status] },
293
288
  },
294
289
  },
295
290
  boardSkipped: null,
@@ -308,7 +303,7 @@ function labelsVerb(ctx: RunContext): number {
308
303
  if (phase !== undefined && failed === true)
309
304
  throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
310
305
  const board = str(ctx.flags.board);
311
- if (board !== undefined && BOARD_OPTION[board] === undefined) {
306
+ if (board !== undefined && !BOARD_STATES.has(board)) {
312
307
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
313
308
  }
314
309
  const t: LabelTransition = { phase, failed };
@@ -317,14 +312,16 @@ function labelsVerb(ctx: RunContext): number {
317
312
  t,
318
313
  );
319
314
  const { board: payload, boardSkipped } =
320
- board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
315
+ board === undefined
316
+ ? { board: null, boardSkipped: null }
317
+ : boardPayload(ctx, board as "progress" | "review");
321
318
  ctx.emit({
322
319
  add,
323
320
  remove,
324
321
  labels,
325
322
  changed: add.length + remove.length > 0,
326
323
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
327
- linearState: linearState(t, board),
324
+ trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
328
325
  board: payload,
329
326
  boardSkipped,
330
327
  });
@@ -616,7 +613,7 @@ export const issuesCommand: CommandSpec = {
616
613
  run: textVerb,
617
614
  },
618
615
  labels: {
619
- summary: "Label arithmetic for a transition, the Linear state, and the board payload.",
616
+ summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
620
617
  flags: [
621
618
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
622
619
  {
@@ -639,10 +636,11 @@ export const issuesCommand: CommandSpec = {
639
636
  labels: "the full label set to write",
640
637
  changed: "whether add or remove is non-empty",
641
638
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
642
- linearState: "Linear issue state for this transition, or null",
643
- board: "projects payloads {addItem, listItems, updateItem}, or null",
639
+ trackerState:
640
+ "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
641
+ board: "projects_write payloads {addItem, updateItem}, or null",
644
642
  boardSkipped:
645
- "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
643
+ "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name>",
646
644
  },
647
645
  run: labelsVerb,
648
646
  },
@@ -527,24 +527,41 @@ export function checkOnlyBookkeeping(
527
527
  if (gitRaw(root, ["merge-base", "--is-ancestor", o.from, o.to]).status !== 0) {
528
528
  return { kind: "not-ancestor" };
529
529
  }
530
- const changed = (specs: string[]) =>
530
+ const diff = changedOutside(root, o.from, o.to, bookPathspecs(o.month, o.fid, "pr"));
531
+ if (!diff.ok) return { kind: "diff-failed", stderr: diff.stderr };
532
+ return diff.outside.length ? { kind: "outside", outside: diff.outside } : { kind: "ok" };
533
+ }
534
+
535
+ /**
536
+ * Every path changed in `from..to`, and the ones no pathspec in `specs` matches, both
537
+ * sorted. Git does the matching, so `specs` take pathspec magic (`:(glob)`). Renames
538
+ * count as a delete plus an add, so both paths must match.
539
+ */
540
+ export function changedOutside(
541
+ root: string,
542
+ from: string,
543
+ to: string,
544
+ specs: readonly string[],
545
+ ): { ok: true; changed: string[]; outside: string[] } | { ok: false; stderr: string } {
546
+ const diff = (only: readonly string[]) =>
531
547
  gitRaw(root, [
532
548
  "diff",
533
549
  "--name-only",
534
550
  "-z",
535
551
  "--no-renames",
536
- o.from,
537
- o.to,
538
- ...(specs.length ? ["--", ...specs] : []),
552
+ from,
553
+ to,
554
+ ...(only.length ? ["--", ...only] : []),
539
555
  ]);
540
- const all = changed([]);
541
- const book = changed(bookPathspecs(o.month, o.fid, "pr"));
542
- if (all.status !== 0 || book.status !== 0) {
543
- return { kind: "diff-failed", stderr: all.status !== 0 ? all.stderr : book.stderr };
544
- }
556
+ const all = diff([]);
557
+ if (all.status !== 0) return { ok: false, stderr: all.stderr };
558
+ const changed = [...new Set(nulList(all.stdout))].sort();
559
+ // No specs = nothing allowed: `git diff` with no pathspec would match every path.
560
+ if (specs.length === 0) return { ok: true, changed, outside: changed };
561
+ const book = diff(specs);
562
+ if (book.status !== 0) return { ok: false, stderr: book.stderr };
545
563
  const allowed = new Set(nulList(book.stdout));
546
- const outside = [...new Set(nulList(all.stdout).filter((p) => !allowed.has(p)))].sort();
547
- return outside.length ? { kind: "outside", outside } : { kind: "ok" };
564
+ return { ok: true, changed, outside: changed.filter((p) => !allowed.has(p)) };
548
565
  }
549
566
 
550
567
  function onlyBookkeeping(ctx: RunContext): number {
@@ -169,11 +169,13 @@ function refFlag(value: FlagValue, flag: string): string {
169
169
  const FID_FORMAT: Record<IssueTracker, RegExp> = {
170
170
  github: /^[0-9]+-[a-z0-9-]+$/,
171
171
  linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
172
+ jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
172
173
  none: /^[a-z0-9][a-z0-9-]*$/,
173
174
  };
174
175
  const ISSUE_FORMAT: Record<Exclude<IssueTracker, "none">, RegExp> = {
175
176
  github: /^[0-9]+$/,
176
177
  linear: /^[A-Z]+-[0-9]+$/,
178
+ jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
177
179
  };
178
180
 
179
181
  /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
@@ -787,7 +789,7 @@ export const prsCommand: CommandSpec = {
787
789
  {
788
790
  name: "issue",
789
791
  type: "string",
790
- help: "issue id for the marker (github: 123 or #123; linear: ABC-123)",
792
+ help: "issue id for the marker (github: 123 or #123; linear / jira: ABC-123)",
791
793
  },
792
794
  BASE_FLAG,
793
795
  HEAD_FLAG,