@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
@@ -129,16 +129,17 @@ export function buildTrackerSetupAdvisory(cwd: string): PreflightFinding | null
129
129
  }
130
130
 
131
131
  /**
132
- * Classify the `bkit.githubProject` board-sync config in package.json:
133
- * - "configured" → object with at least `owner` + `number` (the lookup keys)
132
+ * Classify the `bkit.github.project` board-sync config in package.json:
133
+ * - "configured" → a Projects v2 board URL
134
134
  * - "opted-out" → set to `false` ("no board sync" — stay quiet)
135
+ * - "invalid" → a string that is not a board URL
135
136
  * - "absent" → missing, malformed, or unreadable
136
137
  */
137
- function readGithubProjectConfig(cwd: string): "configured" | "opted-out" | "absent" {
138
- const gp = readBkitConfig(cwd).githubProject;
139
- if (gp === false) return "opted-out";
140
- if (gp !== null && gp.owner !== undefined && gp.number !== undefined) return "configured";
141
- return "absent";
138
+ function readGithubProjectConfig(cwd: string): "configured" | "opted-out" | "invalid" | "absent" {
139
+ const { project, projectUrl } = readBkitConfig(cwd).github;
140
+ if (project === false) return "opted-out";
141
+ if (project !== null) return "configured";
142
+ return projectUrl === null ? "absent" : "invalid";
142
143
  }
143
144
 
144
145
  /**
@@ -168,13 +169,13 @@ export function detectProjectsToolset(cwd: string): TokenPresence {
168
169
  /**
169
170
  * GitHub Projects v2 board-sync prerequisite advisory. Board status sync needs
170
171
  * THREE things, none of which install seeds or verifies end-to-end:
171
- * `bkit.githubProject` config, the `projects` MCP toolset, and an org-scoped
172
- * Projects R/W PAT. Absent any of the first two (the detectable ones), board
173
- * sync silently no-ops — `bkit.githubProject` alone is useless if the toolset
174
- * lacks `projects`, and vice versa. Emits one advisory naming what's missing.
172
+ * `bkit.github.project` (the board URL), the `projects` MCP toolset, and a PAT
173
+ * with Projects R/W. Absent any of the first two (the detectable ones), board
174
+ * sync silently no-ops — the URL alone is useless if the toolset lacks
175
+ * `projects`, and vice versa. Emits one advisory naming what's missing.
175
176
  *
176
177
  * Gates: workflows installed (.claude/ or .cursor/) AND tracker === "github".
177
- * Stays quiet on explicit opt-out (`bkit.githubProject: false`) or when both
178
+ * Stays quiet on explicit opt-out (`bkit.github.project: false`) or when both
178
179
  * detectable prerequisites are satisfied (PAT scope can't be checked locally).
179
180
  */
180
181
  export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null {
@@ -192,7 +193,9 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
192
193
  if (configOk && toolsetOk) return null;
193
194
 
194
195
  const missing: string[] = [];
195
- if (!configOk) missing.push("`bkit.githubProject` is absent from package.json");
196
+ if (configState === "absent") missing.push("`bkit.github.project` is absent from package.json");
197
+ if (configState === "invalid")
198
+ missing.push("`bkit.github.project` is not a GitHub Projects board URL");
196
199
  if (toolset === "missing")
197
200
  missing.push("the `projects` toolset is missing from `.mcp.json` `X-MCP-Toolsets`");
198
201
  const missingPhrase = missing.length > 0 ? `: ${missing.join("; ")}` : "";
@@ -205,70 +208,18 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
205
208
  "Board sync silently no-ops — workflows never reflect phase on the project board.",
206
209
  action:
207
210
  "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
208
- "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" +
211
+ "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" +
209
212
  ' "bkit": {\n' +
210
- ' "githubProject": {\n' +
211
- ' "owner": "<org>", "number": <project-number>,\n' +
212
- ' "statusFieldId": <numeric-field-id>, "progressOptionId": "<option-id>",\n' +
213
- ' "reviewOptionId": "<option-id>", "doneOptionId": "<option-id>"\n' +
214
- " }\n" +
213
+ ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
215
214
  " }\n\n" +
216
- " Discover the ids: `gh api /orgs/<org>/projectsV2/<number>/fields --jq '.[] | select(.name==\"Status\")'` → the Status field's " +
217
- "numeric `id` → `statusFieldId` (a JSON number, NOT quoted); each `options[].id` (e.g. `47fc9ee4`) → " +
218
- "the option ids (quoted strings). `gh project field-list`'s `id` is the GraphQL node id (`PVTSSF_…`) " +
219
- "and must NOT be used for `statusFieldId` — `projects_write` rejects it with " +
220
- "`updated_field.id: value must be a number`.\n\n" +
215
+ " Workflows set the board's Status field by option name: `In progress` when a phase starts, `In review` at hand-off. " +
216
+ 'A board whose Status options are named differently sets `"progress"` and `"review"` beside `"project"` to its own names.\n\n' +
221
217
  "2. Ensure the root `.mcp.json` github server enables the `projects` toolset:\n\n" +
222
218
  ' "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions"\n\n' +
223
- "3. The `BKIT_GH_TOKEN` PAT needs organization-scoped Projects read & write (repo scope is not enough).\n\n" +
224
- "To opt out and silence this advisory, set `bkit.githubProject` to `false` in package.json.",
225
- };
226
- }
227
-
228
- /**
229
- * Static-validate the `statusFieldId` shape on an otherwise-configured board.
230
- * Projects v2 board sync feeds `statusFieldId` straight into `projects_write`
231
- * `updated_field.id`, which requires the NUMERIC field id; a GraphQL node id
232
- * (`PVTSSF_…` — what `gh project field-list` returns) or any non-number value is
233
- * rejected with `updated_field.id: value must be a number`, and best-effort sync then
234
- * no-ops silently. Checked at install/check time, no network needed.
235
- *
236
- * Gates: workflows installed AND tracker === "github" AND `bkit.githubProject` is
237
- * an object carrying `owner` + `number` (an otherwise-usable board) AND
238
- * `statusFieldId` is present but not a JSON number. An absent `statusFieldId` is
239
- * the setup advisory's job; opt-out (`false`) and absent config never reach here.
240
- */
241
- export function detectGithubProjectFieldIdFormat(cwd: string): PreflightFinding | null {
242
- const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
243
- const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
244
- if (!hasClaude && !hasCursor) return null;
245
- const { issueTracker, githubProject: gp } = readBkitConfig(cwd);
246
- if (issueTracker !== "github") return null;
247
-
248
- // Only judge a board that is otherwise configured (owner + number present) and
249
- // has a statusFieldId set — absent statusFieldId is handled by the setup advisory.
250
- if (!gp || gp.owner === undefined || gp.number === undefined) return null;
251
- const sfid = gp.statusFieldId;
252
- if (sfid === undefined || typeof sfid === "number") return null; // absent or already correct
253
-
254
- const looksLikeNodeId = typeof sfid === "string" && /^PVT/.test(sfid);
255
- const shape = looksLikeNodeId
256
- ? "a GraphQL node id (`PVTSSF_…`)"
257
- : `a ${typeof sfid} (\`${String(sfid)}\`)`;
258
-
259
- return {
260
- id: "github-project-status-field-id-format",
261
- severity: "advisory",
262
- detect:
263
- `\`bkit.githubProject.statusFieldId\` is ${shape}, but Projects v2 board sync feeds it to ` +
264
- "`projects_write` `updated_field.id`, which requires the numeric field id and rejects anything " +
265
- "else (`updated_field.id: value must be a number`). Board sync silently no-ops — the board never reflects phase.",
266
- action:
267
- "Re-derive the numeric Status field id and store it unquoted:\n\n" +
268
- " gh api /orgs/<org>/projectsV2/<number>/fields --jq '.[] | select(.name==\"Status\")'\n\n" +
269
- "The Status field's numeric `id` (e.g. `350038178`) → `statusFieldId` (a JSON number, NOT quoted); " +
270
- "each `options[].id` (e.g. `47fc9ee4`) → the option ids (quoted strings). `gh project field-list`'s " +
271
- "`id` is the GraphQL node id (`PVTSSF_…`) and must NOT be used for `statusFieldId`.",
219
+ "3. The `BKIT_GH_TOKEN` PAT needs Projects read & write (repo scope is not enough): a fine-grained PAT gets it as an " +
220
+ "organization permission, so it reaches organization boards only; a classic PAT with the `project` scope reaches " +
221
+ "organization and personal boards.\n\n" +
222
+ "To opt out and silence this advisory, set `bkit.github.project` to `false` in package.json.",
272
223
  };
273
224
  }
274
225
 
@@ -21,7 +21,6 @@ import {
21
21
  buildGithubProjectAdvisory,
22
22
  buildTrackerSetupAdvisory,
23
23
  detectActionsWritePermissions,
24
- detectGithubProjectFieldIdFormat,
25
24
  detectMainBranchProtection,
26
25
  } from "./github.js";
27
26
  import {
@@ -395,10 +394,6 @@ export function runPostInstallCheck(
395
394
  // absent any prerequisite, sync silently no-ops.
396
395
  const githubProjectSetup = buildGithubProjectAdvisory(cwd);
397
396
  if (githubProjectSetup) phase3.push(githubProjectSetup);
398
- // A configured board can still silently no-op if statusFieldId holds the GraphQL
399
- // node id instead of the numeric field id projects_write requires.
400
- const githubProjectFieldId = detectGithubProjectFieldIdFormat(cwd);
401
- if (githubProjectFieldId) phase3.push(githubProjectFieldId);
402
397
  const depUpdaterSetup = buildDepUpdaterSetupAdvisory(cwd);
403
398
  if (depUpdaterSetup) phase3.push(depUpdaterSetup);
404
399
  const cloudSetup = buildCloudSetupAdvisory(cwd);
@@ -148,7 +148,7 @@ const BKIT_STUBS: BkitStub[] = [
148
148
  id: "coverage",
149
149
  file: ".github/workflows/bkit-ci.yml",
150
150
  description:
151
- "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.",
151
+ "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.",
152
152
  },
153
153
  {
154
154
  id: "e2e-coverage",
@@ -32,7 +32,7 @@ export function silenceLine(ids: readonly string[]): string {
32
32
  const names = ids.map((id) => `\`${id}\``);
33
33
  const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
34
34
  const what = ids.length > 1 ? "these tips" : "this tip";
35
- return `Want to silence ${what}? Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
35
+ return `**Want to silence ${what}?** Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
36
36
  }
37
37
 
38
38
  /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
@@ -49,6 +49,9 @@ export const STAR_TIP_OLD_ID = "star";
49
49
  export const STAR_TIP =
50
50
  "Do you like bkit? Then give it a star at [https://github.com/cbartens/bkit](https://github.com/cbartens/bkit)!";
51
51
 
52
+ /** `STAR_TIP` for a workflow's `## bkit Tips`, its question bold like each tip's title. */
53
+ export const STAR_TIP_PARAGRAPH = STAR_TIP.replace("Do you like bkit?", "**Do you like bkit?**");
54
+
52
55
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
53
56
  export const TIPS_SECTION_INTRO =
54
57
  "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.";
@@ -169,7 +172,7 @@ function formatWorkflowTips(
169
172
  const ids = shown.map((t) => t.id);
170
173
  const parts = shown.map(tipParagraph);
171
174
  if (star) {
172
- parts.push(STAR_TIP);
175
+ parts.push(STAR_TIP_PARAGRAPH);
173
176
  ids.push(STAR_TIP_ID);
174
177
  }
175
178
  if (ids.length === 0) return "";
@@ -239,49 +239,31 @@ function onOff(v: unknown, flag: string): boolean | undefined {
239
239
  return b;
240
240
  }
241
241
 
242
- const BOARD_OPTION: Record<string, string> = {
243
- progress: "progressOptionId",
244
- review: "reviewOptionId",
245
- };
242
+ const BOARD_STATES = new Set(["progress", "review"]);
246
243
 
247
244
  /**
248
- * The three `projects_write` / `projects_list` payloads that move an issue on the
249
- * Projects v2 board, from `bkit.githubProject`. Payload keys are the MCP tools'
250
- * own argument names. The workflow fills `item_id` on `updateItem` from the
251
- * `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.
252
248
  */
253
249
  function boardPayload(
254
250
  ctx: RunContext,
255
- status: string,
251
+ status: "progress" | "review",
256
252
  ): { board: Record<string, unknown> | null; boardSkipped: string | null } {
257
- const root = repoRoot(ctx.cwd);
258
- const tracker = readBkitConfig(root).issueTracker;
253
+ const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
259
254
  if (tracker !== "github") {
260
255
  if (tracker === "linear" || tracker === "jira")
261
256
  ctx.log("Board status carried by issue state — no separate update.");
262
257
  return { board: null, boardSkipped: `tracker-${tracker}` };
263
258
  }
264
- const gp = readBkitConfig(root).githubProject;
265
- if (gp === false) return { board: null, boardSkipped: "opted-out" };
266
- const cfg = gp ?? {};
267
- const owner = cfg.owner;
268
- const number = Number(cfg.number);
269
- if (typeof owner !== "string" || owner === "" || !Number.isInteger(number) || number <= 0) {
270
- ctx.log("GitHub project not configured in package.json");
271
- return { board: null, boardSkipped: "not-configured" };
272
- }
273
- // projects_write rejects anything but the numeric field id (a `PVTSSF_…` node id
274
- // included), so a wrong value is a skip with a reason, not a silent no-op.
275
- const raw = cfg.statusFieldId;
276
- const fieldId = typeof raw === "number" ? raw : /^[0-9]+$/.test(String(raw)) ? Number(raw) : NaN;
277
- if (!Number.isInteger(fieldId)) {
278
- ctx.log(`bkit.githubProject.statusFieldId "${String(raw)}" is not the numeric Status field id`);
279
- return { board: null, boardSkipped: "status-field-id-not-number" };
280
- }
281
- const option = cfg[BOARD_OPTION[status]!];
282
- if (typeof option !== "string" || option === "") {
283
- ctx.log(`bkit.githubProject.${BOARD_OPTION[status]!} is not set`);
284
- 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" };
285
267
  }
286
268
  const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
287
269
  const ownerRepo = String(ctx.flags.ownerRepo ?? "");
@@ -292,22 +274,17 @@ function boardPayload(
292
274
  "--board needs --issue=<number> and --owner-repo=<owner>/<repo>",
293
275
  );
294
276
  }
295
- 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) };
296
280
  return {
297
281
  board: {
298
- addItem: {
299
- method: "add_project_item",
300
- ...project,
301
- item_type: "issue",
302
- item_owner: itemOwner,
303
- item_repo: itemRepo,
304
- issue_number: Number(issue),
305
- },
306
- listItems: { method: "list_project_items", ...project, query: issue },
282
+ addItem: { method: "add_project_item", ...project, item_type: "issue", ...item },
307
283
  updateItem: {
308
284
  method: "update_project_item",
309
285
  ...project,
310
- updated_field: { id: fieldId, value: option },
286
+ ...item,
287
+ updated_field: { name: "Status", value: github[status] },
311
288
  },
312
289
  },
313
290
  boardSkipped: null,
@@ -326,7 +303,7 @@ function labelsVerb(ctx: RunContext): number {
326
303
  if (phase !== undefined && failed === true)
327
304
  throw new CommandError(EXIT.USAGE, "--phase clears bkit:failed; drop --failed=on");
328
305
  const board = str(ctx.flags.board);
329
- if (board !== undefined && BOARD_OPTION[board] === undefined) {
306
+ if (board !== undefined && !BOARD_STATES.has(board)) {
330
307
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
331
308
  }
332
309
  const t: LabelTransition = { phase, failed };
@@ -335,7 +312,9 @@ function labelsVerb(ctx: RunContext): number {
335
312
  t,
336
313
  );
337
314
  const { board: payload, boardSkipped } =
338
- board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
315
+ board === undefined
316
+ ? { board: null, boardSkipped: null }
317
+ : boardPayload(ctx, board as "progress" | "review");
339
318
  ctx.emit({
340
319
  add,
341
320
  remove,
@@ -659,9 +638,9 @@ export const issuesCommand: CommandSpec = {
659
638
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
660
639
  trackerState:
661
640
  "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
662
- board: "projects payloads {addItem, listItems, updateItem}, or null",
641
+ board: "projects_write payloads {addItem, updateItem}, or null",
663
642
  boardSkipped:
664
- "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>",
665
644
  },
666
645
  run: labelsVerb,
667
646
  },
@@ -135,6 +135,8 @@ export const repoCommand: CommandSpec = {
135
135
  trackerProject:
136
136
  "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
137
137
  trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
138
+ trackerBoard:
139
+ "{ownerType, owner, number} read from package.json bkit.github.project under github, else null",
138
140
  },
139
141
  exitCodes: {
140
142
  [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
 
13
16
  import { spawnSync } from "node:child_process";
14
17
  import * as fs from "node:fs";
@@ -116,12 +119,42 @@ function shipBranch(root: string, fid: string, named: string | undefined, sessio
116
119
  return isSharedBranch(session) || session === "" ? feat : session;
117
120
  }
118
121
 
122
+ /**
123
+ * The ref a feature branch starts from and rebases onto: local `dev` when it is
124
+ * strictly ahead of `origin/dev` (a fast-forward of it), else `origin/dev`. With
125
+ * `log`, says why when the two differ. Fetch first for a current answer.
126
+ */
127
+ export function devBase(cwd: string, log?: (m: string) => void): string {
128
+ const local = git(cwd, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
129
+ const remote = git(cwd, ["rev-parse", "-q", "--verify", `refs/remotes/${ORIGIN_DEV}`]);
130
+ if (local === null || remote === null || local === remote) return ORIGIN_DEV;
131
+ const count = (range: string) => git(cwd, ["rev-list", "--count", range]) ?? "?";
132
+ if (runGit(cwd, ["merge-base", "--is-ancestor", remote, local]).ok) {
133
+ log?.(
134
+ `local ${DEV} is ${count(`${remote}..${local}`)} commit(s) ahead of ${ORIGIN_DEV} — basing on local ${DEV}; push ${DEV} before the feature PR`,
135
+ );
136
+ return DEV;
137
+ }
138
+ if (!runGit(cwd, ["merge-base", "--is-ancestor", local, remote]).ok) {
139
+ log?.(
140
+ `local ${DEV} and ${ORIGIN_DEV} have diverged — basing on ${ORIGIN_DEV}; local ${DEV}'s ${count(`${remote}..${local}`)} commit(s) are not in this worktree`,
141
+ );
142
+ }
143
+ return ORIGIN_DEV;
144
+ }
145
+
119
146
  /**
120
147
  * `git worktree add` for `branch`: the local branch, else a tracking branch off
121
- * `origin`, else (when `mayCreate`) a new branch off a freshly fetched
122
- * `origin/dev`. Returns false when there was nothing to add and `mayCreate` is off.
148
+ * `origin`, else (when `mayCreate`) a new branch off `devBase` after a fresh
149
+ * fetch. Returns false when there was nothing to add and `mayCreate` is off.
123
150
  */
124
- function addWorktree(root: string, wt: string, branch: string, mayCreate: boolean): boolean {
151
+ function addWorktree(
152
+ root: string,
153
+ wt: string,
154
+ branch: string,
155
+ mayCreate: boolean,
156
+ log: (m: string) => void,
157
+ ): boolean {
125
158
  let args: string[];
126
159
  if (hasLocal(root, branch)) {
127
160
  args = [wt, branch];
@@ -135,7 +168,7 @@ function addWorktree(root: string, wt: string, branch: string, mayCreate: boolea
135
168
  args = [wt, "--track", "-b", branch, `origin/${branch}`];
136
169
  } else if (mayCreate) {
137
170
  fetchBranch(root, DEV);
138
- args = [wt, "-b", branch, ORIGIN_DEV];
171
+ args = [wt, "-b", branch, devBase(root, log)];
139
172
  } else {
140
173
  return false;
141
174
  }
@@ -180,6 +213,34 @@ function copyListed(root: string, wt: string, entries: string[], log: (m: string
180
213
  return { copied, copyMissing };
181
214
  }
182
215
 
216
+ /**
217
+ * `direnv allow` the worktree's `.envrc` when it matches the main checkout's
218
+ * byte for byte, so the worktree inherits the trust given there and nothing
219
+ * more; a differing file is left for a human to read. No `.envrc`, direnv
220
+ * missing or failing → false, narrated, never fatal.
221
+ */
222
+ function allowDirenv(root: string, wt: string, log: (m: string) => void): boolean {
223
+ const envrc = path.join(wt, ".envrc");
224
+ if (!fs.existsSync(envrc)) return false;
225
+ const main = path.join(root, ".envrc");
226
+ if (!fs.existsSync(main) || !fs.readFileSync(main).equals(fs.readFileSync(envrc))) {
227
+ log(
228
+ `direnv: ${envrc} differs from the main checkout's — not allowed; read it, then run direnv allow`,
229
+ );
230
+ return false;
231
+ }
232
+ const res = spawnSync("direnv", ["allow", wt], { cwd: wt, encoding: "utf-8" });
233
+ if (res.error || res.status === 127) {
234
+ log("direnv: not installed — run direnv allow in the worktree once it is");
235
+ return false;
236
+ }
237
+ if (res.status !== 0) {
238
+ log(`direnv allow failed (exit ${res.status}): ${(res.stderr ?? "").trim()}`);
239
+ return false;
240
+ }
241
+ return true;
242
+ }
243
+
183
244
  /** Run the frozen install in `wt`; the exit status, with a spawn failure read as "could not run". */
184
245
  function install(wt: string, log: (m: string) => void): number {
185
246
  const [cmd, ...args] = installCommand({ frozen: true });
@@ -331,12 +392,16 @@ export const worktreesCommand: CommandSpec = {
331
392
  mode: "created | resumed | adopted",
332
393
  owned: "the .worktree-owned marker is present (a workflow created this worktree)",
333
394
  rebaseConflict:
334
- "a resume rebase onto origin/dev stopped on a conflict and is left in progress",
395
+ "a resume rebase onto baseRef stopped on a conflict and is left in progress",
335
396
  sentinel: "the .rebase-failed sentinel written on a failed rebase, else null",
336
397
  logDir: "docs/plans/{month}/logs/{fid} under worktreePath (created)",
337
- baseSha: "git merge-base origin/dev HEAD at worktreePath, or null",
398
+ baseRef:
399
+ "dev when local dev is a fast-forward of origin/dev (unpushed commits), else origin/dev",
400
+ baseSha: "git merge-base baseRef HEAD at worktreePath, or null",
338
401
  copied: "worktree copy entries copied from the main checkout",
339
402
  copyMissing: "worktree copy entries absent from the main checkout",
403
+ direnvAllowed:
404
+ "direnv allow ran on the worktree's .envrc (present and identical to the main checkout's)",
340
405
  installed: "dependencies were installed",
341
406
  },
342
407
  exitCodes: {
@@ -415,7 +480,7 @@ export const worktreesCommand: CommandSpec = {
415
480
  mode = "resumed";
416
481
  } else if (workflow !== "debug" || session !== target) {
417
482
  // Debug adopts an existing feat/{fid}; it never mints a branch of its own.
418
- if (addWorktree(root, wtDir, target, workflow !== "debug")) mode = "created";
483
+ if (addWorktree(root, wtDir, target, workflow !== "debug", ctx.log)) mode = "created";
419
484
  }
420
485
  }
421
486
  const wt = mode === "adopted" ? root : wtDir;
@@ -451,16 +516,22 @@ export const worktreesCommand: CommandSpec = {
451
516
  // Cleared before every attempt: a sentinel left by an earlier run would
452
517
  // send this one to the Failure Path after a clean rebase.
453
518
  fs.rmSync(sentinelPath, { force: true });
454
- let failure: { conflict: boolean; detail: string } | undefined;
519
+ let failure: { conflict: boolean; detail: string; onto: string } | undefined;
455
520
  if (rebaseInProgress(wt)) {
456
- failure = { conflict: true, detail: "a rebase is already in progress" };
521
+ failure = {
522
+ conflict: true,
523
+ detail: "a rebase is already in progress",
524
+ onto: devBase(wt),
525
+ };
457
526
  } else {
458
527
  fetchBranch(wt, DEV);
459
- const rb = runGit(wt, ["rebase", "--rebase-merges", ORIGIN_DEV]);
528
+ const onto = devBase(wt, ctx.log);
529
+ const rb = runGit(wt, ["rebase", "--rebase-merges", onto]);
460
530
  if (!rb.ok) {
461
531
  failure = {
462
532
  conflict: rebaseInProgress(wt),
463
533
  detail: [rb.stdout, rb.stderr].filter(Boolean).join("\n"),
534
+ onto,
464
535
  };
465
536
  }
466
537
  }
@@ -468,10 +539,12 @@ export const worktreesCommand: CommandSpec = {
468
539
  fs.mkdirSync(logDir, { recursive: true });
469
540
  fs.appendFileSync(
470
541
  path.join(logDir, "rebase-resolve-log.md"),
471
- `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${ORIGIN_DEV} stopped\n${failure.detail}\n`,
542
+ `[bkit-worktrees] ${new Date().toISOString()} rebase onto ${failure.onto} stopped\n${failure.detail}\n`,
472
543
  );
473
544
  fs.writeFileSync(sentinelPath, "");
474
- ctx.log(`rebase onto ${ORIGIN_DEV} failed in ${wt}: ${failure.detail.split("\n")[0]}`);
545
+ ctx.log(
546
+ `rebase onto ${failure.onto} failed in ${wt}: ${failure.detail.split("\n")[0]}`,
547
+ );
475
548
  rebaseConflict = failure.conflict;
476
549
  sentinel = sentinelPath;
477
550
  }
@@ -486,9 +559,11 @@ export const worktreesCommand: CommandSpec = {
486
559
  const { copied, copyMissing } = done
487
560
  ? copyListed(root, wt, config.worktreeCopy, ctx.log)
488
561
  : { copied: [], copyMissing: [] };
562
+ const direnvAllowed = done && allowDirenv(root, wt, ctx.log);
489
563
  const wantInstall = done && config.worktreeInstall;
490
564
  const installStatus = wantInstall ? install(wt, ctx.log) : 0;
491
565
 
566
+ const baseRef = devBase(wt);
492
567
  ctx.emit({
493
568
  worktreePath: wt,
494
569
  repoRoot: root,
@@ -498,9 +573,11 @@ export const worktreesCommand: CommandSpec = {
498
573
  rebaseConflict,
499
574
  sentinel,
500
575
  logDir,
501
- baseSha: git(wt, ["merge-base", ORIGIN_DEV, "HEAD"]),
576
+ baseRef,
577
+ baseSha: git(wt, ["merge-base", baseRef, "HEAD"]),
502
578
  copied,
503
579
  copyMissing,
580
+ direnvAllowed,
504
581
  installed: wantInstall && installStatus === 0,
505
582
  });
506
583
  if (sentinel !== null)
@@ -19,6 +19,7 @@ import { writeNetworkAllowlist } from "../network-allowlist.js";
19
19
  import type { PreflightFinding } from "../../checks/before/index.js";
20
20
  import { parseJson, readJsonFile } from "../../shared/json.js";
21
21
  import { readInstallingVersion } from "../../shared/package-json.js";
22
+ import { CONFIG_DEFAULTS } from "../../shared/settings.js";
22
23
  import {
23
24
  getCoreRoot,
24
25
  getSharedRoot,
@@ -396,9 +397,84 @@ export function seedCorePackageJsonScripts(
396
397
  if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
397
398
  written.push("package.json");
398
399
  }
400
+ if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
401
+ written.push("package.json");
402
+ }
399
403
  return written;
400
404
  }
401
405
 
406
+ /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
407
+ function writePackageJsonLike(raw: string, pkg: unknown): void {
408
+ const indentMatch = raw.match(/\n([ \t]+)"/);
409
+ const indent = indentMatch ? indentMatch[1] : " ";
410
+ const trailingNewline = raw.endsWith("\n") ? "\n" : "";
411
+ fs.writeFileSync("package.json", JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
412
+ }
413
+
414
+ // Status option ids of GitHub's Kanban and Team planning board templates; every board
415
+ // made from one carries the same ids.
416
+ const TEMPLATE_STATUS_OPTIONS: Readonly<Record<string, string>> = {
417
+ "47fc9ee4": "In progress",
418
+ df73e18b: "In review",
419
+ };
420
+
421
+ // Migration (up to 5.4.x installs, `docs/migrations.md`): the board lived at
422
+ // `bkit.githubProject` as `{owner, number, statusFieldId, *OptionId}`, org boards only; it
423
+ // is `bkit.github.project`, the board URL, with Status set by option name from
424
+ // `bkit.github.progress` / `review`. An existing `bkit.github.project` wins over the old
425
+ // key. Returns true when package.json changed.
426
+ export function migrateGithubProjectKey(dryRun: boolean, ws: WriteSet, logPrefix: string): boolean {
427
+ const pkgPath = "package.json";
428
+ if (!fs.existsSync(pkgPath)) return false;
429
+ const raw = fs.readFileSync(pkgPath, "utf-8");
430
+ const parsed = parseJson(raw);
431
+ if (!parsed.ok) return false;
432
+ const pkg = parsed.value as Record<string, unknown>;
433
+ const bkit = pkg.bkit;
434
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit)) return false;
435
+ const cfg = bkit as Record<string, unknown>;
436
+ if (!Object.prototype.hasOwnProperty.call(cfg, "githubProject")) return false;
437
+ const old = cfg.githubProject;
438
+ const github =
439
+ cfg.github !== null && typeof cfg.github === "object" && !Array.isArray(cfg.github)
440
+ ? (cfg.github as Record<string, unknown>)
441
+ : {};
442
+ const unnamed: ("progress" | "review")[] = [];
443
+ if (github.project === undefined) {
444
+ if (old === false) github.project = false;
445
+ else if (old !== null && typeof old === "object" && !Array.isArray(old)) {
446
+ const board = old as Record<string, unknown>;
447
+ const owner = typeof board.owner === "string" ? board.owner.trim() : "";
448
+ const number = Number(board.number);
449
+ if (owner !== "" && Number.isInteger(number) && number > 0) {
450
+ github.project = `https://github.com/orgs/${owner}/projects/${number}`;
451
+ for (const [moment, key] of [
452
+ ["progress", "progressOptionId"],
453
+ ["review", "reviewOptionId"],
454
+ ] as const) {
455
+ const id = board[key];
456
+ if (typeof id !== "string" || id.trim() === "") continue;
457
+ const name = TEMPLATE_STATUS_OPTIONS[id.trim()];
458
+ if (name === undefined) unnamed.push(moment);
459
+ else if (github[moment] === undefined && name !== CONFIG_DEFAULTS.github[moment])
460
+ github[moment] = name;
461
+ }
462
+ }
463
+ }
464
+ }
465
+ delete cfg.githubProject;
466
+ if (Object.keys(github).length > 0) cfg.github = github;
467
+ ws.writes.push({ path: pkgPath, action: "update" });
468
+ if (!dryRun) writePackageJsonLike(raw, pkg);
469
+ const tag = dryRun ? "[dry-run] " : "";
470
+ console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
471
+ for (const moment of unnamed)
472
+ console.log(
473
+ `${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]}")`,
474
+ );
475
+ return true;
476
+ }
477
+
402
478
  // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
403
479
  // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
404
480
  // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
@@ -422,12 +498,7 @@ export function migrateLinearTeamKey(dryRun: boolean, ws: WriteSet, logPrefix: s
422
498
  delete cfg.linearTeam;
423
499
  if (Object.keys(linear).length > 0) cfg.linear = linear;
424
500
  ws.writes.push({ path: pkgPath, action: "update" });
425
- if (!dryRun) {
426
- const indentMatch = raw.match(/\n([ \t]+)"/);
427
- const indent = indentMatch ? indentMatch[1] : " ";
428
- const trailingNewline = raw.endsWith("\n") ? "\n" : "";
429
- fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
430
- }
501
+ if (!dryRun) writePackageJsonLike(raw, pkg);
431
502
  console.log(
432
503
  `${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved bkit.linearTeam to bkit.linear.team in package.json`,
433
504
  );