@cbartens/bkit 5.5.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 (56) hide show
  1. package/.bkit/README.md +2 -2
  2. package/.bkit/core/.agents/rules.md +17 -1
  3. package/.bkit/core/.bkit/README.md +1 -1
  4. package/.bkit/core/.bkit/cloud.md +2 -2
  5. package/.bkit/core/.bkit/install.md +3 -4
  6. package/.bkit/core/.bkit/prompts.md +29 -14
  7. package/.bkit/core/.bkit/templates.md +34 -9
  8. package/.bkit/core/.bkit/trackers.md +10 -1
  9. package/.bkit/core/.bkit/workflows.md +10 -9
  10. package/.bkit/core/engine/checks/after/ci-yml.ts +0 -1
  11. package/.bkit/core/engine/checks/after/github.ts +24 -73
  12. package/.bkit/core/engine/checks/after/index.ts +0 -5
  13. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  14. package/.bkit/core/engine/checks/tips/index.ts +5 -2
  15. package/.bkit/core/engine/commands/workflow/issues.ts +26 -47
  16. package/.bkit/core/engine/commands/workflow/repo.ts +2 -0
  17. package/.bkit/core/engine/commands/workflow/worktrees.ts +91 -14
  18. package/.bkit/core/engine/install/modules/core.ts +77 -6
  19. package/.bkit/core/engine/shared/settings.ts +46 -14
  20. package/.bkit/core/prompts/bkit-debug-abort-handover.md +2 -0
  21. package/.bkit/core/prompts/bkit-design-generate.md +2 -0
  22. package/.bkit/core/prompts/bkit-plan-generate.md +5 -3
  23. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  24. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -1
  25. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  26. package/.bkit/core/workflows/bkit-build.md +3 -3
  27. package/.bkit/core/workflows/bkit-debug.md +3 -3
  28. package/.bkit/core/workflows/bkit-design.md +3 -3
  29. package/.bkit/core/workflows/bkit-plan.md +3 -3
  30. package/.bkit/core/workflows/bkit-ship.md +3 -3
  31. package/.bkit/shared/docs/deployments.md +5 -17
  32. package/.bkit/shared/docs/testing.md +11 -3
  33. package/.bkit/templates/.github/workflows/bkit-ci.yml +21 -83
  34. package/.bkit/templates/.husky/pre-push +48 -9
  35. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  36. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  37. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  38. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  39. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  40. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  41. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  42. package/CHANGELOG.md +30 -0
  43. package/README.md +9 -0
  44. package/dist/checks/after/ci-yml.js +0 -1
  45. package/dist/checks/after/github.js +24 -71
  46. package/dist/checks/after/index.js +1 -6
  47. package/dist/checks/after/tools.js +1 -1
  48. package/dist/checks/tips/index.js +4 -2
  49. package/dist/commands/workflow/issues.js +25 -46
  50. package/dist/commands/workflow/repo.js +1 -0
  51. package/dist/commands/workflow/worktrees.js +74 -13
  52. package/dist/install/modules/core.js +81 -6
  53. package/dist/shared/settings.js +23 -10
  54. package/package.json +4 -2
  55. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  56. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
@@ -112,18 +112,19 @@ export function buildTrackerSetupAdvisory(cwd) {
112
112
  };
113
113
  }
114
114
  /**
115
- * Classify the `bkit.githubProject` board-sync config in package.json:
116
- * - "configured" → object with at least `owner` + `number` (the lookup keys)
115
+ * Classify the `bkit.github.project` board-sync config in package.json:
116
+ * - "configured" → a Projects v2 board URL
117
117
  * - "opted-out" → set to `false` ("no board sync" — stay quiet)
118
+ * - "invalid" → a string that is not a board URL
118
119
  * - "absent" → missing, malformed, or unreadable
119
120
  */
120
121
  function readGithubProjectConfig(cwd) {
121
- const gp = readBkitConfig(cwd).githubProject;
122
- if (gp === false)
122
+ const { project, projectUrl } = readBkitConfig(cwd).github;
123
+ if (project === false)
123
124
  return "opted-out";
124
- if (gp !== null && gp.owner !== undefined && gp.number !== undefined)
125
+ if (project !== null)
125
126
  return "configured";
126
- return "absent";
127
+ return projectUrl === null ? "absent" : "invalid";
127
128
  }
128
129
  /**
129
130
  * Inspect the root `.mcp.json` github server's `X-MCP-Toolsets` header for the
@@ -153,13 +154,13 @@ export function detectProjectsToolset(cwd) {
153
154
  /**
154
155
  * GitHub Projects v2 board-sync prerequisite advisory. Board status sync needs
155
156
  * THREE things, none of which install seeds or verifies end-to-end:
156
- * `bkit.githubProject` config, the `projects` MCP toolset, and an org-scoped
157
- * Projects R/W PAT. Absent any of the first two (the detectable ones), board
158
- * sync silently no-ops — `bkit.githubProject` alone is useless if the toolset
159
- * lacks `projects`, and vice versa. Emits one advisory naming what's missing.
157
+ * `bkit.github.project` (the board URL), the `projects` MCP toolset, and a PAT
158
+ * with Projects R/W. Absent any of the first two (the detectable ones), board
159
+ * sync silently no-ops — the URL alone is useless if the toolset lacks
160
+ * `projects`, and vice versa. Emits one advisory naming what's missing.
160
161
  *
161
162
  * Gates: workflows installed (.claude/ or .cursor/) AND tracker === "github".
162
- * Stays quiet on explicit opt-out (`bkit.githubProject: false`) or when both
163
+ * Stays quiet on explicit opt-out (`bkit.github.project: false`) or when both
163
164
  * detectable prerequisites are satisfied (PAT scope can't be checked locally).
164
165
  */
165
166
  export function buildGithubProjectAdvisory(cwd) {
@@ -178,8 +179,10 @@ export function buildGithubProjectAdvisory(cwd) {
178
179
  if (configOk && toolsetOk)
179
180
  return null;
180
181
  const missing = [];
181
- if (!configOk)
182
- missing.push("`bkit.githubProject` is absent from package.json");
182
+ if (configState === "absent")
183
+ missing.push("`bkit.github.project` is absent from package.json");
184
+ if (configState === "invalid")
185
+ missing.push("`bkit.github.project` is not a GitHub Projects board URL");
183
186
  if (toolset === "missing")
184
187
  missing.push("the `projects` toolset is missing from `.mcp.json` `X-MCP-Toolsets`");
185
188
  const missingPhrase = missing.length > 0 ? `: ${missing.join("; ")}` : "";
@@ -189,68 +192,18 @@ export function buildGithubProjectAdvisory(cwd) {
189
192
  detect: `GitHub tracker is active but Projects v2 board status sync is not fully configured${missingPhrase}. ` +
190
193
  "Board sync silently no-ops — workflows never reflect phase on the project board.",
191
194
  action: "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
192
- "1. Add `bkit.githubProject` to package.json (org-owned board only — fine-grained PATs cannot reach user-owned projects, nor span orgs; use a classic PAT with `project` to cover more than one owner):\n\n" +
195
+ "1. Add the board's URL to package.json, as the browser shows it on the board (`/orgs/<org>/…` for an organization board, `/users/<login>/…` for a personal one; a trailing `/views/<n>` is fine):\n\n" +
193
196
  ' "bkit": {\n' +
194
- ' "githubProject": {\n' +
195
- ' "owner": "<org>", "number": <project-number>,\n' +
196
- ' "statusFieldId": <numeric-field-id>, "progressOptionId": "<option-id>",\n' +
197
- ' "reviewOptionId": "<option-id>", "doneOptionId": "<option-id>"\n' +
198
- " }\n" +
197
+ ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
199
198
  " }\n\n" +
200
- " Discover the ids: `gh api /orgs/<org>/projectsV2/<number>/fields --jq '.[] | select(.name==\"Status\")'` → the Status field's " +
201
- "numeric `id` → `statusFieldId` (a JSON number, NOT quoted); each `options[].id` (e.g. `47fc9ee4`) → " +
202
- "the option ids (quoted strings). `gh project field-list`'s `id` is the GraphQL node id (`PVTSSF_…`) " +
203
- "and must NOT be used for `statusFieldId` — `projects_write` rejects it with " +
204
- "`updated_field.id: value must be a number`.\n\n" +
199
+ " Workflows set the board's Status field by option name: `In progress` when a phase starts, `In review` at hand-off. " +
200
+ 'A board whose Status options are named differently sets `"progress"` and `"review"` beside `"project"` to its own names.\n\n' +
205
201
  "2. Ensure the root `.mcp.json` github server enables the `projects` toolset:\n\n" +
206
202
  ' "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"\n\n' +
207
- "3. The `BKIT_GH_TOKEN` PAT needs organization-scoped Projects read & write (repo scope is not enough).\n\n" +
208
- "To opt out and silence this advisory, set `bkit.githubProject` to `false` in package.json.",
209
- };
210
- }
211
- /**
212
- * Static-validate the `statusFieldId` shape on an otherwise-configured board.
213
- * Projects v2 board sync feeds `statusFieldId` straight into `projects_write`
214
- * `updated_field.id`, which requires the NUMERIC field id; a GraphQL node id
215
- * (`PVTSSF_…` — what `gh project field-list` returns) or any non-number value is
216
- * rejected with `updated_field.id: value must be a number`, and best-effort sync then
217
- * no-ops silently. Checked at install/check time, no network needed.
218
- *
219
- * Gates: workflows installed AND tracker === "github" AND `bkit.githubProject` is
220
- * an object carrying `owner` + `number` (an otherwise-usable board) AND
221
- * `statusFieldId` is present but not a JSON number. An absent `statusFieldId` is
222
- * the setup advisory's job; opt-out (`false`) and absent config never reach here.
223
- */
224
- export function detectGithubProjectFieldIdFormat(cwd) {
225
- const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
226
- const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
227
- if (!hasClaude && !hasCursor)
228
- return null;
229
- const { issueTracker, githubProject: gp } = readBkitConfig(cwd);
230
- if (issueTracker !== "github")
231
- return null;
232
- // Only judge a board that is otherwise configured (owner + number present) and
233
- // has a statusFieldId set — absent statusFieldId is handled by the setup advisory.
234
- if (!gp || gp.owner === undefined || gp.number === undefined)
235
- return null;
236
- const sfid = gp.statusFieldId;
237
- if (sfid === undefined || typeof sfid === "number")
238
- return null; // absent or already correct
239
- const looksLikeNodeId = typeof sfid === "string" && /^PVT/.test(sfid);
240
- const shape = looksLikeNodeId
241
- ? "a GraphQL node id (`PVTSSF_…`)"
242
- : `a ${typeof sfid} (\`${String(sfid)}\`)`;
243
- return {
244
- id: "github-project-status-field-id-format",
245
- severity: "advisory",
246
- detect: `\`bkit.githubProject.statusFieldId\` is ${shape}, but Projects v2 board sync feeds it to ` +
247
- "`projects_write` `updated_field.id`, which requires the numeric field id and rejects anything " +
248
- "else (`updated_field.id: value must be a number`). Board sync silently no-ops — the board never reflects phase.",
249
- action: "Re-derive the numeric Status field id and store it unquoted:\n\n" +
250
- " gh api /orgs/<org>/projectsV2/<number>/fields --jq '.[] | select(.name==\"Status\")'\n\n" +
251
- "The Status field's numeric `id` (e.g. `350038178`) → `statusFieldId` (a JSON number, NOT quoted); " +
252
- "each `options[].id` (e.g. `47fc9ee4`) → the option ids (quoted strings). `gh project field-list`'s " +
253
- "`id` is the GraphQL node id (`PVTSSF_…`) and must NOT be used for `statusFieldId`.",
203
+ "3. The `BKIT_GH_TOKEN` PAT needs Projects read & write (repo scope is not enough): a fine-grained PAT gets it as an " +
204
+ "organization permission, so it reaches organization boards only; a classic PAT with the `project` scope reaches " +
205
+ "organization and personal boards.\n\n" +
206
+ "To opt out and silence this advisory, set `bkit.github.project` to `false` in package.json.",
254
207
  };
255
208
  }
256
209
  /**
@@ -10,7 +10,7 @@ import { readBkitConfig } from "../../shared/settings.js";
10
10
  import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
11
11
  import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
12
12
  import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
13
- import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectGithubProjectFieldIdFormat, detectMainBranchProtection, } from "./github.js";
13
+ import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectMainBranchProtection, } from "./github.js";
14
14
  import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
15
15
  import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
16
16
  import { dropTipSilencedAdvisories, setupTipsChecklistLines, setupTipsMarkdownLines, } from "../tips/index.js";
@@ -297,11 +297,6 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
297
297
  const githubProjectSetup = buildGithubProjectAdvisory(cwd);
298
298
  if (githubProjectSetup)
299
299
  phase3.push(githubProjectSetup);
300
- // A configured board can still silently no-op if statusFieldId holds the GraphQL
301
- // node id instead of the numeric field id projects_write requires.
302
- const githubProjectFieldId = detectGithubProjectFieldIdFormat(cwd);
303
- if (githubProjectFieldId)
304
- phase3.push(githubProjectFieldId);
305
300
  const depUpdaterSetup = buildDepUpdaterSetupAdvisory(cwd);
306
301
  if (depUpdaterSetup)
307
302
  phase3.push(depUpdaterSetup);
@@ -106,7 +106,7 @@ const BKIT_STUBS = [
106
106
  {
107
107
  id: "coverage",
108
108
  file: ".github/workflows/bkit-ci.yml",
109
- description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `actions: read` + `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive) and the Check Tree Cache step needs `actions: read`, so omitting it breaks the cache step; (4) two report steps with distinct `name:` (unit / integration) pointing at each dir's coverage-summary.json + coverage-final.json; the unit step runs on every event (`if: !cancelled()` plus a `hashFiles` guard on its summary), sets `vite-config-path: vitest.unit.config.ts` so the job summary and PR comment show the floor as the target, and comments only on same-repo PRs (`comment-on: pr`, else `none`). SEPARATE LANES (one job per tier): put the integration run + report + its OWN pull-requests: write block in bkit-tests-integration, not bkit-tests-unit — each lane posts its own comment. Thresholds are opt-in and PER TIER: UNIT is the gate — put `coverage.thresholds.branches` in a `vitest.unit.config.ts` (`mergeConfig` over vitest.config) that ONLY the unit run loads via `-c` (vitest coverage is per-RUN/root config, NOT per-project — `projects` does not scope it and a `thresholds` block in vitest.config reds BOTH runs; the report action reads the same file as raw text, so keep the floor on one unquoted `branches: <n>` line and no other metric name + colon + number in it; branches is the meaningful floor, set to current and ratchet up). INTEGRATION is REPORT-ONLY — gate it on EXECUTION (the capstone's integration_ran > 0), not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic). For a real integration %, add `--coverage.include=src/server/**` on the integration run (same CLI-flag idiom as --exclude) then set a floor, or ratchet from current — never a picked number. Fork PRs: GITHUB_TOKEN is read-only, so the unit step sets `comment-on: none` there (its job summary still lands) and the integration step keeps the `head.repo == repo` guard (or use the action's workflow_run two-workflow pattern). Guard the integration report on `hashFiles('coverage/integration/coverage-summary.json') != ''` so a repo with no integration tier skips it cleanly.",
109
+ description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive), so omitting `contents: read` breaks the checkout; (4) two report steps with distinct `name:` (unit / integration) pointing at each dir's coverage-summary.json + coverage-final.json; the unit step runs on every event (`if: !cancelled()` plus a `hashFiles` guard on its summary), sets `vite-config-path: vitest.unit.config.ts` so the job summary and PR comment show the floor as the target, and comments only on same-repo PRs (`comment-on: pr`, else `none`). SEPARATE LANES (one job per tier): put the integration run + report + its OWN pull-requests: write block in bkit-tests-integration, not bkit-tests-unit — each lane posts its own comment. Thresholds are opt-in and PER TIER: UNIT is the gate — put `coverage.thresholds.branches` in a `vitest.unit.config.ts` (`mergeConfig` over vitest.config) that ONLY the unit run loads via `-c` (vitest coverage is per-RUN/root config, NOT per-project — `projects` does not scope it and a `thresholds` block in vitest.config reds BOTH runs; the report action reads the same file as raw text, so keep the floor on one unquoted `branches: <n>` line and no other metric name + colon + number in it; branches is the meaningful floor, set to current and ratchet up). INTEGRATION is REPORT-ONLY — gate it on EXECUTION (the capstone's integration_ran > 0), not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic). For a real integration %, add `--coverage.include=src/server/**` on the integration run (same CLI-flag idiom as --exclude) then set a floor, or ratchet from current — never a picked number. Fork PRs: GITHUB_TOKEN is read-only, so the unit step sets `comment-on: none` there (its job summary still lands) and the integration step keeps the `head.repo == repo` guard (or use the action's workflow_run two-workflow pattern). Guard the integration report on `hashFiles('coverage/integration/coverage-summary.json') != ''` so a repo with no integration tier skips it cleanly.",
110
110
  },
111
111
  {
112
112
  id: "e2e-coverage",
@@ -17,7 +17,7 @@ export function silenceLine(ids) {
17
17
  const names = ids.map((id) => `\`${id}\``);
18
18
  const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
19
19
  const what = ids.length > 1 ? "these tips" : "this tip";
20
- return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
20
+ return `**Want to silence ${what}?** Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
21
21
  }
22
22
  /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
23
23
  export const STAR_TIP_ID = "bkit-star";
@@ -29,6 +29,8 @@ export const STAR_TIP_OLD_ID = "star";
29
29
  * gap, so never in the checklist.
30
30
  */
31
31
  export const STAR_TIP = "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
32
+ /** `STAR_TIP` for a workflow's `## bkit Tips`, its question bold like each tip's title. */
33
+ export const STAR_TIP_PARAGRAPH = STAR_TIP.replace("Do you like bkit?", "**Do you like bkit?**");
32
34
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
33
35
  export const TIPS_SECTION_INTRO = "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
34
36
  /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
@@ -126,7 +128,7 @@ function formatWorkflowTips(tips, workflow, star) {
126
128
  const ids = shown.map((t) => t.id);
127
129
  const parts = shown.map(tipParagraph);
128
130
  if (star) {
129
- parts.push(STAR_TIP);
131
+ parts.push(STAR_TIP_PARAGRAPH);
130
132
  ids.push(STAR_TIP_ID);
131
133
  }
132
134
  if (ids.length === 0)
@@ -207,46 +207,28 @@ function onOff(v, flag) {
207
207
  throw new CommandError(EXIT.USAGE, `--${flag} must be on or off`);
208
208
  return b;
209
209
  }
210
- const BOARD_OPTION = {
211
- progress: "progressOptionId",
212
- review: "reviewOptionId",
213
- };
210
+ const BOARD_STATES = new Set(["progress", "review"]);
214
211
  /**
215
- * The three `projects_write` / `projects_list` payloads that move an issue on the
216
- * Projects v2 board, from `bkit.githubProject`. Payload keys are the MCP tools'
217
- * own argument names. The workflow fills `item_id` on `updateItem` from the
218
- * `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.
219
215
  */
220
216
  function boardPayload(ctx, status) {
221
- const root = repoRoot(ctx.cwd);
222
- const tracker = readBkitConfig(root).issueTracker;
217
+ const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
223
218
  if (tracker !== "github") {
224
219
  if (tracker === "linear" || tracker === "jira")
225
220
  ctx.log("Board status carried by issue state — no separate update.");
226
221
  return { board: null, boardSkipped: `tracker-${tracker}` };
227
222
  }
228
- const gp = readBkitConfig(root).githubProject;
229
- if (gp === false)
223
+ if (github.project === false)
230
224
  return { board: null, boardSkipped: "opted-out" };
231
- const cfg = gp ?? {};
232
- const owner = cfg.owner;
233
- const number = Number(cfg.number);
234
- if (typeof owner !== "string" || owner === "" || !Number.isInteger(number) || number <= 0) {
235
- ctx.log("GitHub project not configured in package.json");
236
- return { board: null, boardSkipped: "not-configured" };
237
- }
238
- // projects_write rejects anything but the numeric field id (a `PVTSSF_…` node id
239
- // included), so a wrong value is a skip with a reason, not a silent no-op.
240
- const raw = cfg.statusFieldId;
241
- const fieldId = typeof raw === "number" ? raw : /^[0-9]+$/.test(String(raw)) ? Number(raw) : NaN;
242
- if (!Number.isInteger(fieldId)) {
243
- ctx.log(`bkit.githubProject.statusFieldId "${String(raw)}" is not the numeric Status field id`);
244
- return { board: null, boardSkipped: "status-field-id-not-number" };
245
- }
246
- const option = cfg[BOARD_OPTION[status]];
247
- if (typeof option !== "string" || option === "") {
248
- ctx.log(`bkit.githubProject.${BOARD_OPTION[status]} is not set`);
249
- 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" };
250
232
  }
251
233
  const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
252
234
  const ownerRepo = String(ctx.flags.ownerRepo ?? "");
@@ -254,22 +236,17 @@ function boardPayload(ctx, status) {
254
236
  if (!/^[0-9]+$/.test(issue) || !itemOwner || !itemRepo || extra !== undefined) {
255
237
  throw new CommandError(EXIT.USAGE, "--board needs --issue=<number> and --owner-repo=<owner>/<repo>");
256
238
  }
257
- 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) };
258
242
  return {
259
243
  board: {
260
- addItem: {
261
- method: "add_project_item",
262
- ...project,
263
- item_type: "issue",
264
- item_owner: itemOwner,
265
- item_repo: itemRepo,
266
- issue_number: Number(issue),
267
- },
268
- listItems: { method: "list_project_items", ...project, query: issue },
244
+ addItem: { method: "add_project_item", ...project, item_type: "issue", ...item },
269
245
  updateItem: {
270
246
  method: "update_project_item",
271
247
  ...project,
272
- updated_field: { id: fieldId, value: option },
248
+ ...item,
249
+ updated_field: { name: "Status", value: github[status] },
273
250
  },
274
251
  },
275
252
  boardSkipped: null,
@@ -284,12 +261,14 @@ function labelsVerb(ctx) {
284
261
  if (phase !== undefined && failed === true)
285
262
  throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
286
263
  const board = str(ctx.flags.board);
287
- if (board !== undefined && BOARD_OPTION[board] === undefined) {
264
+ if (board !== undefined && !BOARD_STATES.has(board)) {
288
265
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
289
266
  }
290
267
  const t = { phase, failed };
291
268
  const { add, remove, labels } = transitionLabels(ctx.flags.label ?? [], t);
292
- 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);
293
272
  ctx.emit({
294
273
  add,
295
274
  remove,
@@ -557,8 +536,8 @@ export const issuesCommand = {
557
536
  changed: "whether add or remove is non-empty",
558
537
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
559
538
  trackerState: "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
560
- board: "projects payloads {addItem, listItems, updateItem}, or null",
561
- boardSkipped: "why board is null with --board: opted-out | not-configured | tracker-<name> | …",
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>",
562
541
  },
563
542
  run: labelsVerb,
564
543
  },
@@ -116,6 +116,7 @@ export const repoCommand = {
116
116
  trackerTeam: "package.json bkit.linear.team under linear, else null",
117
117
  trackerProject: "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
118
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",
119
120
  },
120
121
  exitCodes: {
121
122
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -8,7 +8,10 @@
8
8
  // reports it. `remove` is the close / cleanup half: it removes only a worktree a
9
9
  // workflow created, marked in the git common dir's outbox so the marker outlives
10
10
  // the worktree it describes, and with `--branch` deletes the feature branch
11
- // unless another worktree still holds it.
11
+ // unless another worktree still holds it. A new branch, and a resume rebase,
12
+ // use local `dev` when it is a fast-forward of `origin/dev`: dev pushes wait for
13
+ // a human, so local dev is routinely ahead, and a worktree without those commits
14
+ // builds against superseded work.
12
15
  import { spawnSync } from "node:child_process";
13
16
  import * as fs from "node:fs";
14
17
  import * as path from "node:path";
@@ -93,12 +96,32 @@ function shipBranch(root, fid, named, session) {
93
96
  return feat;
94
97
  return isSharedBranch(session) || session === "" ? feat : session;
95
98
  }
99
+ /**
100
+ * The ref a feature branch starts from and rebases onto: local `dev` when it is
101
+ * strictly ahead of `origin/dev` (a fast-forward of it), else `origin/dev`. With
102
+ * `log`, says why when the two differ. Fetch first for a current answer.
103
+ */
104
+ export function devBase(cwd, log) {
105
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
106
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
107
+ if (local === null || remote === null || local === remote)
108
+ return ORIGIN_DEV;
109
+ const count = (range) => git(cwd, ["rev-list", "--count", range]) ?? "?";
110
+ if (runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
111
+ log?.(`local ${DEV} is ${count(`${remote}..${local}`)} commit(s) ahead of ${ORIGIN_DEV} — basing on local ${DEV}; push ${DEV} before the feature PR`);
112
+ return DEV;
113
+ }
114
+ if (!runGit(cwd, ["merge-base", "--is-ancestor", local, remote]).ok) {
115
+ log?.(`local ${DEV} and ${ORIGIN_DEV} have diverged — basing on ${ORIGIN_DEV}; local ${DEV}'s ${count(`${remote}..${local}`)} commit(s) are not in this worktree`);
116
+ }
117
+ return ORIGIN_DEV;
118
+ }
96
119
  /**
97
120
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
98
- * `origin`, else (when `mayCreate`) a new branch off a freshly fetched
99
- * `origin/dev`. Returns false when there was nothing to add and `mayCreate` is off.
121
+ * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
122
+ * fetch. Returns false when there was nothing to add and `mayCreate` is off.
100
123
  */
101
- function addWorktree(root, wt, branch, mayCreate) {
124
+ function addWorktree(root, wt, branch, mayCreate, log) {
102
125
  let args;
103
126
  if (hasLocal(root, branch)) {
104
127
  args = [wt, branch];
@@ -114,7 +137,7 @@ function addWorktree(root, wt, branch, mayCreate) {
114
137
  }
115
138
  else if (mayCreate) {
116
139
  fetchBranch(root, DEV);
117
- args = [wt, "-b", branch, ORIGIN_DEV];
140
+ args = [wt, "-b", branch, devBase(root, log)];
118
141
  }
119
142
  else {
120
143
  return false;
@@ -157,6 +180,32 @@ function copyListed(root, wt, entries, log) {
157
180
  }
158
181
  return { copied, copyMissing };
159
182
  }
183
+ /**
184
+ * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
185
+ * byte for byte, so the worktree inherits the trust given there and nothing
186
+ * more; a differing file is left for a human to read. No `.envrc`, direnv
187
+ * missing or failing → false, narrated, never fatal.
188
+ */
189
+ function allowDirenv(root, wt, log) {
190
+ const envrc = path.join(wt, ".envrc");
191
+ if (!fs.existsSync(envrc))
192
+ return false;
193
+ const main = path.join(root, ".envrc");
194
+ if (!fs.existsSync(main) || !fs.readFileSync(main).equals(fs.readFileSync(envrc))) {
195
+ log(`direnv: ${envrc} differs from the main checkout's — not allowed; read it, then run direnv allow`);
196
+ return false;
197
+ }
198
+ const res = spawnSync("direnv", ["allow", wt], { cwd: wt, encoding: "utf-8" });
199
+ if (res.error || res.status === 127) {
200
+ log("direnv: not installed — run direnv allow in the worktree once it is");
201
+ return false;
202
+ }
203
+ if (res.status !== 0) {
204
+ log(`direnv allow failed (exit ${res.status}): ${(res.stderr ?? "").trim()}`);
205
+ return false;
206
+ }
207
+ return true;
208
+ }
160
209
  /** Run the frozen install in `wt`; the exit status, with a spawn failure read as "could not run". */
161
210
  function install(wt, log) {
162
211
  const [cmd, ...args] = installCommand({ frozen: true });
@@ -287,12 +336,14 @@ export const worktreesCommand = {
287
336
  branch: "branch checked out at worktreePath",
288
337
  mode: "created | resumed | adopted",
289
338
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
290
- rebaseConflict: "a resume rebase onto origin/dev stopped on a conflict and is left in progress",
339
+ rebaseConflict: "a resume rebase onto baseRef stopped on a conflict and is left in progress",
291
340
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
292
341
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
293
- baseSha: "git merge-base origin/dev HEAD at worktreePath, or null",
342
+ baseRef: "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
343
+ baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
294
344
  copied: "worktree copy entries copied from the main checkout",
295
345
  copyMissing: "worktree copy entries absent from the main checkout",
346
+ direnvAllowed: "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
296
347
  installed: "dependencies were installed",
297
348
  },
298
349
  exitCodes: {
@@ -362,7 +413,7 @@ export const worktreesCommand = {
362
413
  }
363
414
  else if (workflow !== "debug" || session !== target) {
364
415
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
365
- if (addWorktree(root, wtDir, target, workflow !== "debug"))
416
+ if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log))
366
417
  mode = "created";
367
418
  }
368
419
  }
@@ -393,23 +444,29 @@ export const worktreesCommand = {
393
444
  fs.rmSync(sentinelPath, { force: true });
394
445
  let failure;
395
446
  if (rebaseInProgress(wt)) {
396
- failure = { conflict: true, detail: "a rebase is already in progress" };
447
+ failure = {
448
+ conflict: true,
449
+ detail: "a rebase is already in progress",
450
+ onto: devBase(wt),
451
+ };
397
452
  }
398
453
  else {
399
454
  fetchBranch(wt, DEV);
400
- const rb = runGit(wt, ["rebase", "--rebase-merges", ORIGIN_DEV]);
455
+ const onto = devBase(wt, ctx.log);
456
+ const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
401
457
  if (!rb.ok) {
402
458
  failure = {
403
459
  conflict: rebaseInProgress(wt),
404
460
  detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
461
+ onto,
405
462
  };
406
463
  }
407
464
  }
408
465
  if (failure) {
409
466
  fs.mkdirSync(logDir, { recursive: true });
410
- fs.appendFileSync(path.join(logDir, "rebase-resolve-log.md"), `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${ORIGIN_DEV} stopped\n${failure.detail}\n`);
467
+ fs.appendFileSync(path.join(logDir, "rebase-resolve-log.md"), `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${failure.onto} stopped\n${failure.detail}\n`);
411
468
  fs.writeFileSync(sentinelPath, "");
412
- ctx.log(`rebase onto ${ORIGIN_DEV} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
469
+ ctx.log(`rebase onto ${failure.onto} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
413
470
  rebaseConflict = failure.conflict;
414
471
  sentinel = sentinelPath;
415
472
  }
@@ -423,8 +480,10 @@ export const worktreesCommand = {
423
480
  const { copied, copyMissing } = done
424
481
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
425
482
  : { copied: [], copyMissing: [] };
483
+ const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
426
484
  const wantInstall = done && config.worktreeInstall;
427
485
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
486
+ const baseRef = devBase(wt);
428
487
  ctx.emit({
429
488
  worktreePath: wt,
430
489
  repoRoot: root,
@@ -434,9 +493,11 @@ export const worktreesCommand = {
434
493
  rebaseConflict,
435
494
  sentinel,
436
495
  logDir,
437
- baseSha: git(wt, ["merge-base", ORIGIN_DEV, "HEAD"]),
496
+ baseRef,
497
+ baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
438
498
  copied,
439
499
  copyMissing,
500
+ direnvAllowed,
440
501
  installed: wantInstall && installStatus === 0,
441
502
  });
442
503
  if (sentinel !== null)
@@ -11,6 +11,7 @@ import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
11
11
  import { writeNetworkAllowlist } from "../network-allowlist.js";
12
12
  import { parseJson, readJsonFile } from "../../shared/json.js";
13
13
  import { readInstallingVersion } from "../../shared/package-json.js";
14
+ import { CONFIG_DEFAULTS } from "../../shared/settings.js";
14
15
  import { getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
15
16
  import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_PUSH_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
16
17
  export function listMdFiles(dir, prefix) {
@@ -318,8 +319,86 @@ export function seedCorePackageJsonScripts(ctx) {
318
319
  if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
319
320
  written.push("package.json");
320
321
  }
322
+ if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
323
+ written.push("package.json");
324
+ }
321
325
  return written;
322
326
  }
327
+ /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
328
+ function writePackageJsonLike(raw, pkg) {
329
+ const indentMatch = raw.match(/\n([ \t]+)"/);
330
+ const indent = indentMatch ? indentMatch[1] : " ";
331
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
332
+ fs.writeFileSync("package.json", JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
333
+ }
334
+ // Status option ids of GitHub's Kanban and Team planning board templates; every board
335
+ // made from one carries the same ids.
336
+ const TEMPLATE_STATUS_OPTIONS = {
337
+ "47fc9ee4": "In progress",
338
+ df73e18b: "In review",
339
+ };
340
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the board lived at
341
+ // `bkit.githubProject` as `{owner, number, statusFieldId, *OptionId}`, org boards only; it
342
+ // is `bkit.github.project`, the board URL, with Status set by option name from
343
+ // `bkit.github.progress` / `review`. An existing `bkit.github.project` wins over the old
344
+ // key. Returns true when package.json changed.
345
+ export function migrateGithubProjectKey(dryRun, ws, logPrefix) {
346
+ const pkgPath = "package.json";
347
+ if (!fs.existsSync(pkgPath))
348
+ return false;
349
+ const raw = fs.readFileSync(pkgPath, "utf-8");
350
+ const parsed = parseJson(raw);
351
+ if (!parsed.ok)
352
+ return false;
353
+ const pkg = parsed.value;
354
+ const bkit = pkg.bkit;
355
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit))
356
+ return false;
357
+ const cfg = bkit;
358
+ if (!Object.prototype.hasOwnProperty.call(cfg, "githubProject"))
359
+ return false;
360
+ const old = cfg.githubProject;
361
+ const github = cfg.github !== null && typeof cfg.github === "object" && !Array.isArray(cfg.github)
362
+ ? cfg.github
363
+ : {};
364
+ const unnamed = [];
365
+ if (github.project === undefined) {
366
+ if (old === false)
367
+ github.project = false;
368
+ else if (old !== null && typeof old === "object" && !Array.isArray(old)) {
369
+ const board = old;
370
+ const owner = typeof board.owner === "string" ? board.owner.trim() : "";
371
+ const number = Number(board.number);
372
+ if (owner !== "" && Number.isInteger(number) && number > 0) {
373
+ github.project = `https://github.com/orgs/${owner}/projects/${number}`;
374
+ for (const [moment, key] of [
375
+ ["progress", "progressOptionId"],
376
+ ["review", "reviewOptionId"],
377
+ ]) {
378
+ const id = board[key];
379
+ if (typeof id !== "string" || id.trim() === "")
380
+ continue;
381
+ const name = TEMPLATE_STATUS_OPTIONS[id.trim()];
382
+ if (name === undefined)
383
+ unnamed.push(moment);
384
+ else if (github[moment] === undefined && name !== CONFIG_DEFAULTS.github[moment])
385
+ github[moment] = name;
386
+ }
387
+ }
388
+ }
389
+ }
390
+ delete cfg.githubProject;
391
+ if (Object.keys(github).length > 0)
392
+ cfg.github = github;
393
+ ws.writes.push({ path: pkgPath, action: "update" });
394
+ if (!dryRun)
395
+ writePackageJsonLike(raw, pkg);
396
+ const tag = dryRun ? "[dry-run] " : "";
397
+ console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
398
+ for (const moment of unnamed)
399
+ console.log(`${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`);
400
+ return true;
401
+ }
323
402
  // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
324
403
  // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
325
404
  // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
@@ -348,12 +427,8 @@ export function migrateLinearTeamKey(dryRun, ws, logPrefix) {
348
427
  if (Object.keys(linear).length > 0)
349
428
  cfg.linear = linear;
350
429
  ws.writes.push({ path: pkgPath, action: "update" });
351
- if (!dryRun) {
352
- const indentMatch = raw.match(/\n([ \t]+)"/);
353
- const indent = indentMatch ? indentMatch[1] : " ";
354
- const trailingNewline = raw.endsWith("\n") ? "\n" : "";
355
- fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
356
- }
430
+ if (!dryRun)
431
+ writePackageJsonLike(raw, pkg);
357
432
  console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`);
358
433
  return true;
359
434
  }