@cbartens/bkit 5.0.1 → 5.0.3

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 (37) hide show
  1. package/.bkit/README.md +3 -3
  2. package/.bkit/core/.agents/rules.md +57 -57
  3. package/.bkit/core/.bkit/README.md +2 -2
  4. package/.bkit/core/.bkit/cloud.md +7 -6
  5. package/.bkit/core/.bkit/comparison.md +32 -27
  6. package/.bkit/core/.bkit/install.md +3 -3
  7. package/.bkit/core/.bkit/providers.md +6 -3
  8. package/.bkit/core/.bkit/templates.md +8 -5
  9. package/.bkit/core/.bkit/trackers.md +1 -1
  10. package/.bkit/core/engine/checks/after/github.ts +1 -1
  11. package/.bkit/core/engine/checks/after/index.ts +2 -2
  12. package/.bkit/core/engine/checks/before/env.ts +1 -1
  13. package/.bkit/core/engine/commands/install/uninstall.ts +33 -1
  14. package/.bkit/core/engine/install/cloud-env.ts +4 -1
  15. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  16. package/.bkit/core/engine/install/modules/opencode.ts +34 -13
  17. package/.bkit/core/engine/install/template-copies.ts +19 -1
  18. package/.bkit/shared/.bkit/.env.example +41 -12
  19. package/.bkit/shared/.claude/bkit-cloud.md +1 -1
  20. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  21. package/.bkit/shared/.opencode/opencode.json +3 -1
  22. package/.bkit/shared/docs/deployments.md +6 -4
  23. package/.bkit/shared/docs/setup.md +11 -0
  24. package/.bkit/templates/.github/workflows/bkit-ci.yml +18 -2
  25. package/.bkit/templates/.github/workflows/bkit-renovate.yml +7 -5
  26. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +125 -12
  27. package/CHANGELOG.md +34 -0
  28. package/README.md +94 -35
  29. package/dist/checks/after/github.js +1 -1
  30. package/dist/checks/after/index.js +2 -2
  31. package/dist/checks/before/env.js +1 -1
  32. package/dist/commands/install/uninstall.js +21 -1
  33. package/dist/install/cloud-env.js +4 -1
  34. package/dist/install/modules/cloud.js +2 -2
  35. package/dist/install/modules/opencode.js +34 -14
  36. package/dist/install/template-copies.js +16 -1
  37. package/package.json +24 -2
@@ -88,7 +88,7 @@ Phase-label set + additive-label semantics: `.bkit/workflows.md` § Tracker Inte
88
88
 
89
89
  ## github — Projects v2 board (optional)
90
90
 
91
- `issue-update-status` reads `package.json` `bkit.githubProject` = `{ owner (org login), number, statusFieldId, progressOptionId, reviewOptionId, doneOptionId }` (non-secret, committed). Absent → board sync skipped (best-effort, never gates). Discover ids once: `gh api /orgs/{owner}/projectsV2/{number}/fields --jq '.[] | select(.name=="Status")'` (Status field numeric `id` → `statusFieldId`; each option raw `id` → option id, e.g. `47fc9ee4`; `PVTSSF_…` node id from `gh project field-list` is not field id — `projects_write` rejects it). Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` org Projects R/W. Org-owned boards only — fine-grained PATs cannot reach user-owned projects. `value` = single-select **option id**, not option name. Failure → retry once after 5s, then continue. `doneOptionId` is **reserved and never written** — ship terminal sets `reviewOptionId`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
91
+ `issue-update-status` reads `package.json` `bkit.githubProject` = `{ owner (org login), number, statusFieldId, progressOptionId, reviewOptionId, doneOptionId }` (non-secret, committed). Absent → board sync skipped (best-effort, never gates). Discover ids once: `gh api /orgs/{owner}/projectsV2/{number}/fields --jq '.[] | select(.name=="Status")'` (Status field numeric `id` → `statusFieldId`; each option raw `id` → option id, e.g. `47fc9ee4`; `PVTSSF_…` node id from `gh project field-list` is not field id — `projects_write` rejects it). Requires `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) + `BKIT_GH_TOKEN` org Projects R/W. Org-owned boards only — fine-grained PATs cannot reach user-owned projects, nor span orgs; use a classic PAT with `project` when the token must cover more than one owner. `value` = single-select **option id**, not option name. Failure → retry once after 5s, then continue. `doneOptionId` is **reserved and never written** — ship terminal sets `reviewOptionId`, and a human moves the item to Done on acceptance (§ `issue-update-merged` in `.bkit/workflows.md`).
92
92
 
93
93
  ## linear — notes
94
94
 
@@ -245,7 +245,7 @@ export function buildGithubProjectAdvisory(cwd: string): PreflightFinding | null
245
245
  "Board sync silently no-ops — workflows never reflect phase on the project board.",
246
246
  action:
247
247
  "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
248
- "1. Add `bkit.githubProject` to package.json (org-owned board only — fine-grained PATs cannot reach user-owned projects):\n\n" +
248
+ "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" +
249
249
  ' "bkit": {\n' +
250
250
  ' "githubProject": {\n' +
251
251
  ' "owner": "<org>", "number": <project-number>,\n' +
@@ -363,7 +363,7 @@ export function runPostInstallCheck(
363
363
  detect:
364
364
  "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
365
365
  action:
366
- "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<fine-grained PAT>\n direnv allow\n\nThe PAT needs Contents, Pull requests, Issues, and Actions read & write (plus organization-scoped Projects read & write if you use board sync). Generate at: https://github.com/settings/tokens. In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
366
+ "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
367
367
  });
368
368
  } else if (ghMcpTokenStatus === "empty") {
369
369
  phase3.push({
@@ -372,7 +372,7 @@ export function runPostInstallCheck(
372
372
  detect:
373
373
  'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
374
374
  action:
375
- "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT with Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
375
+ "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
376
376
  });
377
377
  }
378
378
  }
@@ -66,7 +66,7 @@ export function detectBlankDotenvKeys(
66
66
  {
67
67
  key: "BKIT_GH_TOKEN",
68
68
  description:
69
- "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write)",
69
+ "fine-grained PAT for the GitHub MCP server (Contents, Pull requests, Issues, Actions, Workflows, Metadata — read/write), or a classic PAT when one token must span owners",
70
70
  },
71
71
  // BKIT_LINEAR_API_KEY is required only under the Linear tracker.
72
72
  ...(tracker === "linear"
@@ -31,7 +31,12 @@ import {
31
31
  type ModuleName,
32
32
  type IssueTracker,
33
33
  } from "../../install/manifest.js";
34
- import { isConsumerModified, readBkitVersion } from "../../install/version-file.js";
34
+ import {
35
+ isConsumerModified,
36
+ mergeCanonicalHashes,
37
+ readBkitVersion,
38
+ writeBkitVersion,
39
+ } from "../../install/version-file.js";
35
40
  import {
36
41
  getPkgRoot,
37
42
  getSharedRoot,
@@ -845,6 +850,33 @@ export async function runUninstall(
845
850
  }
846
851
  }
847
852
 
853
+ // Targeted (non-core) uninstall: `.bkit/version` stays (the modules that remain read it),
854
+ // but its canonicalHashes still list every path this run deleted — absent entries that
855
+ // `mergeCanonicalHashes` prunes. Left in place, the very next `bkit check` (a dry-run
856
+ // install whose core postDispatch prunes the same absent paths) reports write-drift on
857
+ // `.bkit/version` and fails the CI gate. Recompute and rewrite here so the on-disk manifest
858
+ // already matches what the next check would produce. A full/core uninstall deletes the file
859
+ // earlier instead (zero footprint) and never reaches this branch.
860
+ if (!moduleList.includes("core")) {
861
+ const versionFile = path.join(ctx.cwd, ".bkit", "version");
862
+ const existing = readBkitVersion(versionFile);
863
+ if (existing) {
864
+ const { canonicalHashes, pruned } = mergeCanonicalHashes(
865
+ ctx.cwd,
866
+ existing.canonicalHashes,
867
+ {},
868
+ );
869
+ if (pruned > 0) {
870
+ console.log(
871
+ `${ctx.logPrefix}${ctx.dryRun ? " [dry-run]" : ""} update version pin: .bkit/version (pruned ${pruned})`,
872
+ );
873
+ if (!ctx.dryRun) {
874
+ writeBkitVersion(versionFile, { ...existing, canonicalHashes });
875
+ }
876
+ }
877
+ }
878
+ }
879
+
848
880
  return result;
849
881
  }
850
882
 
@@ -39,7 +39,10 @@ export const SESSION_HIJACK_KEYS = [
39
39
  // placeholder ONLY when absent from the resolved `.envrc` set — a present value
40
40
  // (e.g. BKIT_GH_TOKEN already in `.bkit/.env`) keeps its real resolved value.
41
41
  const BASELINE_TOKEN_PLACEHOLDERS: ReadonlyArray<readonly [string, string]> = [
42
- ["BKIT_GH_TOKEN", "<fine-grained PAT — see .bkit/cloud.md § BKIT_GH_TOKEN permissions>"],
42
+ [
43
+ "BKIT_GH_TOKEN",
44
+ "<PAT — fine-grained one owner / classic across owners; see .bkit/cloud.md § BKIT_GH_TOKEN token permissions>",
45
+ ],
43
46
  ];
44
47
 
45
48
  // Earlier-compaction override — a bkit constant, not a secret. Appended to the
@@ -102,8 +102,8 @@ export function runCloudModule(ctx: ModuleContext): void {
102
102
  "IN CLAUDE APP (claude.ai/code → environment selector → + Add environment):\n" +
103
103
  " - Name: the repo name (e.g. `acme-web`) — one environment per repo, since secrets are per-repo.\n" +
104
104
  " - Setup script: paste from bkit's `cloud.md` § Setup script (installs vale + gh + corepack-pinned pnpm — exact versions live in cloud.md, not duplicated here).\n" +
105
- " - Environment variables: `BKIT_GH_TOKEN` (fine-grained PAT for GitHub MCP), `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`.\n" +
106
- " - Tracker env vars (GitHub): No tracker PAT needed. Run `gh auth login` once for CLI surface. MCP auth is browser OAuth (automatic on first tool call). Set `BKIT_GH_TOKEN` (fine-grained PAT for GitHub MCP server).\n" +
105
+ " - Environment variables: `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP), `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`.\n" +
106
+ " - Tracker env vars (GitHub): No tracker PAT needed. Run `gh auth login` once for CLI surface. MCP auth is browser OAuth (automatic on first tool call). Set `BKIT_GH_TOKEN` (fine-grained for one owner, classic across owners — GitHub MCP server).\n" +
107
107
  " - Network access: `Trusted` (default). One environment per repo (secrets differ per repo); the setup script + variable *names* are identical across repos, only the values change. See cloud.md § Sharing across repos → Claude.",
108
108
  });
109
109
  } else if (variant === "opencode") {
@@ -251,10 +251,11 @@ const OPENCODE_PROVIDER_BASE_URL_SENTINEL = "@@OPENCODE_PROVIDER_BASE_URL@@";
251
251
  * Resolves the @@OPENCODE_TRACKER_MCP@@ sentinel into the correct mcpServers entry
252
252
  * and fills in provider-specific fields.
253
253
  *
254
- * Also injects `curl *{domain}*` / `wget *{domain}*` **allow** rules (after the
255
- * template's `curl *` / `wget *` ask) for {@link resolveNetworkAllowlist} so
256
- * context-fetch / provider hosts do not prompt (OpenCode bash is last-match-wins), and
257
- * `<server>_*` allows for the consumer's `mcp-servers` block.
254
+ * Also injects derived **allow** rules for {@link resolveNetworkAllowlist} so
255
+ * context-fetch / provider hosts do not prompt on either fetch surface: `curl *{domain}*` /
256
+ * `wget *{domain}*` after the template's `curl *` / `wget *` ask (OpenCode bash is
257
+ * last-match-wins), and `*{domain}*` into the `permission.webfetch` URL map (after its
258
+ * `"*": "ask"`). Adds `<server>_*` allows for the consumer's `mcp-servers` block.
258
259
  */
259
260
  export function renderOpencodeJson(
260
261
  templatePath: string,
@@ -274,10 +275,14 @@ export function renderOpencodeJson(
274
275
  // opencode's MCP schema differs from Claude/Cursor: remote servers use type "remote"
275
276
  // (NOT "http" — not in opencode's enum, which makes the whole config invalid) and read
276
277
  // secrets via {env:VAR} (NOT shell ${VAR}). See https://opencode.ai/config.json.
278
+ // github: "oauth": false disables opencode's automatic OAuth. api.githubcopilot.com/mcp/
279
+ // authenticates via the Authorization header and has no OAuth DCR, so a stale/empty
280
+ // {env:BKIT_GH_TOKEN} would otherwise surface as a "sign in" prompt whose flow fails with
281
+ // "dynamic auth not supported" instead of a clear 401. See opencode.ai/docs/mcp-servers.
277
282
  let mcpEntry: string;
278
283
  if (tracker === "github") {
279
284
  mcpEntry =
280
- '"github": { "type": "remote", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer {env:BKIT_GH_TOKEN}", "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects" } }';
285
+ '"github": { "type": "remote", "url": "https://api.githubcopilot.com/mcp/", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_GH_TOKEN}", "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects" } }';
281
286
  } else if (tracker === "linear") {
282
287
  mcpEntry = '"linear": { "type": "remote", "url": "https://mcp.linear.app/mcp" }';
283
288
  } else {
@@ -332,9 +337,16 @@ export function renderOpencodeJson(
332
337
  }
333
338
 
334
339
  /**
335
- * Append curl/wget domain allows after template ask rules (OpenCode last-match-wins),
336
- * and one `<server>_*` allow per declared MCP server — opencode names MCP tools
337
- * `<server>_<tool>` and matches permission keys as globs against the tool name.
340
+ * Append derived allows for the consumer's resolved network allowlist (OpenCode
341
+ * last-match-wins), and one `<server>_*` allow per declared MCP server — opencode names
342
+ * MCP tools `<server>_<tool>` and matches permission keys as globs against the tool name.
343
+ *
344
+ * The allowlist is applied to BOTH fetch surfaces, so an allowlisted host does not prompt
345
+ * whichever path the agent takes:
346
+ * - fetch tool — `permission.webfetch` is a URL-keyed map (`{ "*": "ask" }` from the
347
+ * template); opencode matches the resource against the URL, so `*{base}*` allows it;
348
+ * - shell fetch — `permission.bash` gains `curl *{base}*` / `wget *{base}*` after the
349
+ * template's `curl *` / `wget *` ask.
338
350
  */
339
351
  function injectOpencodeDerivedAllows(parsed: Record<string, unknown>, cwd: string): void {
340
352
  const permission = parsed.permission as Record<string, unknown> | undefined;
@@ -342,11 +354,20 @@ function injectOpencodeDerivedAllows(parsed: Record<string, unknown>, cwd: strin
342
354
  for (const server of extractMcpServers(cwd)) {
343
355
  permission[`${server}_*`] = "allow";
344
356
  }
345
- if (typeof permission.bash !== "object" || permission.bash === null) return;
346
- const bash = permission.bash as Record<string, string>;
347
- for (const base of networkAllowlistBases(resolveNetworkAllowlist(cwd))) {
348
- bash[`curl *${base}*`] = "allow";
349
- bash[`wget *${base}*`] = "allow";
357
+ const bases = networkAllowlistBases(resolveNetworkAllowlist(cwd));
358
+ if (typeof permission.bash === "object" && permission.bash !== null) {
359
+ const bash = permission.bash as Record<string, string>;
360
+ for (const base of bases) {
361
+ bash[`curl *${base}*`] = "allow";
362
+ bash[`wget *${base}*`] = "allow";
363
+ }
364
+ }
365
+ // Fetch tool — opencode matches the webfetch resource against the requested URL.
366
+ if (typeof permission.webfetch === "object" && permission.webfetch !== null) {
367
+ const webfetch = permission.webfetch as Record<string, string>;
368
+ for (const base of bases) {
369
+ webfetch[`*${base}*`] = "allow";
370
+ }
350
371
  }
351
372
  }
352
373
 
@@ -100,13 +100,31 @@ function pruneEmptyDirs(root: string): void {
100
100
  export const TEMPLATES_POINTER =
101
101
  "Templates (adopt, do not skip): read .bkit/templates.md; bkit never applies templates, so adopt each copy in .bkit/templates/ unless adoption would break existing functionality — state which you did not adopt and why. (If your own gates scan the repo, ignore .bkit/templates/.)";
102
102
 
103
+ /**
104
+ * Changed templates whose ADOPTED copy also backs a gate: the consequence of leaving it
105
+ * stale, keyed by template rel path. The upgrade line names it so the consequence reaches
106
+ * the same run that changed the copy — a stale adopted copy can redden a gate that a
107
+ * bkit-installed file trips, and the agent at that gate never sees this report.
108
+ */
109
+ export const TEMPLATE_CHANGE_CONSEQUENCES: Readonly<Record<string, string>> = {
110
+ "slop-scan.config.json":
111
+ "your adopted copy's guardrails exemptions are now stale; your slop gate may go red",
112
+ };
113
+
114
+ /** ` changed: <dest>`, plus the consequence when that template's adopted copy backs a gate. */
115
+ function formatChangedLine(rel: string): string {
116
+ const line = ` changed: ${path.join(TEMPLATE_COPIES_DIR, rel)}`;
117
+ const note = TEMPLATE_CHANGE_CONSEQUENCES[rel];
118
+ return note === undefined ? line : `${line} — ${note}`;
119
+ }
120
+
103
121
  /**
104
122
  * The upgrade report for a template sync: one line per changed, added or removed
105
123
  * template, then where to read about adopting them. Empty when nothing changed.
106
124
  */
107
125
  export function formatTemplateChanges(changes: TemplateCopyChanges): string {
108
126
  const lines = [
109
- ...changes.changed.map((p) => ` changed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
127
+ ...changes.changed.map(formatChangedLine),
110
128
  ...changes.added.map((p) => ` added: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
111
129
  ...changes.removed.map((p) => ` removed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
112
130
  ];
@@ -7,33 +7,62 @@
7
7
  #
8
8
  # Cloud sessions (Claude on the web, Cursor Background Agents) set the SAME
9
9
  # variable names in their respective dashboards — never in this file.
10
+ #
11
+ # Keep ~/.config/bkit/launchd.env in sync. GUI/daemon apps (the opencode desktop
12
+ # app, Cursor launched from the Dock, and opencode's background service) do not
13
+ # inherit direnv's exports — they read what `ai.bkit.launchd` publishes to launchd
14
+ # from that file (see .bkit/providers.md § macOS GUI-isolation). It DUPLICATES
15
+ # these tokens and does not track this file, so after ROTATING a value here you
16
+ # must re-sync launchd.env or the app keeps the stale one — e.g. a revoked
17
+ # BKIT_GH_TOKEN makes the GitHub MCP 401 and opencode offers an OAuth "sign in"
18
+ # that then fails with "dynamic auth not supported". Then restart long-lived
19
+ # consumers: opencode snapshots its env at launch, so `opencode service restart`.
10
20
 
11
21
  # Optional examples — not required bkit tooling. Listed so direnv has a name to
12
22
  # load if you use that surface; leave blank otherwise.
13
23
 
14
- # BKIT_GH_TOKEN — the general-purpose bkit GitHub token (fine-grained PAT). One token
15
- # for every GitHub *API* operation bkit tooling performs:
24
+ # BKIT_GH_TOKEN — the general-purpose bkit GitHub token. One token for every GitHub
25
+ # *API* operation bkit tooling performs:
16
26
  # - the GitHub MCP server (api.githubcopilot.com/mcp/) via the Authorization header
17
- # in .mcp.json / .cursor/mcp.json;
27
+ # in .mcp.json / .cursor/mcp.json / .opencode/opencode.json;
18
28
  # - self-hosted Renovate's PLATFORM auth (repo Actions secret) when you copy
19
29
  # the example `.github/workflows/bkit-renovate.yml` — opens PRs,
20
30
  # pushes renovate/* branches, edits workflow SHAs, maintains the dashboard issue.
21
- # Required Repository permissions (as labelled in the fine-grained-PAT UI; scope to the
31
+ #
32
+ # Token TYPE — choose by how many repos / owners bkit touches:
33
+ # - ONE repo, or every repo under ONE owner (a single user, or a single org) →
34
+ # FINE-GRAINED PAT (resource owner = that user or org). Preferred — repo-scoped
35
+ # blast radius + mandatory expiry. Permissions below.
36
+ # - MORE THAN ONE repo across DIFFERENT owners (two or more orgs, or a user + an org) →
37
+ # CLASSIC PAT. A fine-grained PAT is limited to a SINGLE resource owner and cannot
38
+ # span organizations, so it cannot cover this case. Classic reaches every repo your
39
+ # user can access — keep the expiry short; an org may block classic PATs (403), and
40
+ # SAML SSO orgs need the token authorized per org (authorization expires; re-authorize).
41
+ #
42
+ # FINE-GRAINED PAT — Repository permissions (as labelled in the token UI; scope to the
22
43
  # repos you work on): Contents: Read and write · Pull requests: Read and write · Issues:
23
44
  # Read and write · Workflows: Read and write · Commit statuses: Read and write (Renovate
24
45
  # reads a commit's CI state to open the PR + posts its own stability checks; without it it
25
46
  # creates the renovate/* branch but 403s on /commits/{sha}/statuses and never opens the PR)
26
47
  # · Dependabot alerts: Read (GitHub's vulnerability feed, for security-fix PRs) · Metadata:
27
- # Read-only. (Actions: Read for the MCP server's run-status queries.) There is NO "Checks"
28
- # permission on fine-grained PATs — check-run writes are App-only, so a PAT-based Renovate
29
- # uses commit statuses instead.
30
- # Self-hosted Renovate commit authorship: on a PERSONAL-account token also add the Account
31
- # permission "Email addresses: Read" so commits use your verified email. ORG-owned tokens
32
- # have NO Email-addresses permission — instead set the repo variable RENOVATE_GIT_AUTHOR
33
- # (Settings -> Secrets and variables -> Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`.
48
+ # Read-only. (Actions: Read for the MCP server's run-status queries.) Add Organization
49
+ # Projects: Read and write only for board sync (org-owned boards; shown under the token's
50
+ # Organizations tab, not Repository permissions). There is NO "Checks" permission on
51
+ # fine-grained PATs — check-run writes are App-only, so a PAT-based Renovate uses commit
52
+ # statuses instead.
53
+ # CLASSIC PAT — scopes: `repo` (issues / PRs / contents / commit statuses) · `workflow`
54
+ # · `read:org` · `project` (board sync) · `security_events` (Dependabot / code-scanning
55
+ # feed) · optional `user:email` (Renovate commit authorship on a personal account). There
56
+ # is no separate Checks scope on classic either — commit statuses come via `repo`.
57
+ # Self-hosted Renovate commit authorship: on a PERSONAL-account fine-grained token also add
58
+ # the Account permission "Email addresses: Read" so commits use your verified email.
59
+ # ORG-owned tokens have NO Email-addresses permission — instead set the repo variable
60
+ # RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables -> Actions -> Variables), e.g.
61
+ # `Renovate Bot <renovate@your-domain>` (classic equivalent: the `user:email` scope).
34
62
  # This is a WRITE token — do NOT put it on read-only surfaces (Vercel env / project
35
63
  # .npmrc).
36
- # Generate at: https://github.com/settings/personal-access-tokens
64
+ # Generate at: https://github.com/settings/personal-access-tokens (fine-grained)
65
+ # https://github.com/settings/tokens (classic)
37
66
  BKIT_GH_TOKEN=
38
67
 
39
68
  # BKIT_LINEAR_API_KEY — Linear personal API key. Used by the Linear MCP server
@@ -112,6 +112,6 @@ Your `/bkit-*` skills and bkit subagents load automatically from the committed
112
112
 
113
113
  ---
114
114
 
115
- `BKIT_GH_TOKEN` fine-grained PAT permissions, the `gh auth login --with-token`
115
+ `BKIT_GH_TOKEN` PAT permissions (fine-grained vs classic), the `gh auth login --with-token`
116
116
  step, MCP OAuth flow, and the one-environment-per-repo rationale all live in
117
117
  `.bkit/cloud.md` § Claude Code on the web.
@@ -43,8 +43,8 @@ Add **each** line below as a secret (Name = the key, Value = the value). Set the
43
43
 
44
44
  - `LINEAR_ISSUE_ID` (Linear tracker) / `GITHUB_ISSUE_ID` (GitHub tracker) are injected
45
45
  **per session** by the Cursor integration — do **not** add them here.
46
- - `BKIT_GH_TOKEN` fine-grained PAT permissions are documented in `.bkit/cloud.md`
47
- § BKIT_GH_TOKEN permissions (identical scope to the Claude side).
46
+ - `BKIT_GH_TOKEN` PAT permissions (fine-grained for one owner, classic across owners) are documented in `.bkit/cloud.md`
47
+ § `BKIT_GH_TOKEN` — token permissions (identical scope to the Claude side).
48
48
  - Secrets are encrypted at rest and in transit and scoped to the environment.
49
49
 
50
50
  ## 3 · Toolchain (in-repo — nothing to paste)
@@ -15,7 +15,9 @@
15
15
  "glob": "allow",
16
16
  "task": "allow",
17
17
  "websearch": "allow",
18
- "webfetch": "ask",
18
+ "webfetch": {
19
+ "*": "ask"
20
+ },
19
21
  "bash": {
20
22
  "*": "allow",
21
23
  "sudo *": "ask",
@@ -212,11 +212,13 @@ Ships in the `bkit-ci.yml` template as the `Check Default Branch Lags Dev` step;
212
212
 
213
213
  ### One CI run per dev commit (release PR mirrors the `dev` push run)
214
214
 
215
- Optional. A same-repo `dev` → `main` PR's head is the `dev` tip the `dev` push run already tests, because a full PR run repeats the slowest run in the repo. Mirror mode runs it once.
215
+ Optional. A same-repo promotion PR into the default branch — head `dev`, or a `release/*` branch cut at the `dev` tip — has the same head the `dev` push run already tests, so a full PR run repeats the slowest run in the repo. Mirror mode runs it once.
216
216
 
217
- - **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo + `head_ref == dev` + base == default branch → `mirror_push_run=true`, `run_level=none`, `run_e2e` / `run_live` / `run_migration` / `web_affected=false`. Every lane skips. Field is required in the plan (`false` otherwise). Fork PRs and every other head / base pair keep the normal plan.
217
+ - **Planner** (`Decide Release Mirror`, `bkit-tests-scope`): `pull_request` + head repo == this repo + base == default branch + `head_ref` is a promotion branch (`dev`, or `release/*`) → `mirror_push_run=true`, `run_level=none`, `run_e2e` / `run_live` / `run_migration` / `web_affected=false`. Every lane skips. Field is required in the plan (`false` otherwise). Fork PRs and every other head / base pair keep the normal plan.
218
218
  - **Capstone** (`Mirror Push Run`, `bkit-tests-check`, before `Assert Test Plan Followed`): `bkit runs mirror --head <PR head sha> --branch dev --max-minutes 170`. Waits for the `dev` push run at that SHA (each poll is `bkit runs gate --event push`) and passes only when its capstone passed. The step runs bkit, so the job needs a checkout and installed dependencies, both ungated. Neither step `continue-on-error`.
219
219
  - **Never skip the PR's required check instead.** A skipped required check can read as passed on the PR while the push run is red.
220
+ - **`release/*` resolves the push run by SHA.** A `release/*` head with no green `dev` push run (extra commits past the `dev` tip) fails the mirror red (exit `3`) — safe, not silent.
221
+ - **bkit's own CI adopts this.** `Decide Release Mirror` accepts `dev` and `release/*`; `Decide Run Level` has no merged-PR → `light` arm, so every `dev` push resolves `full` (precondition 1); the capstone's `Mirror Push Run` runs `bkit runs mirror --head="$PR_HEAD_SHA" --branch=dev --max-minutes=170`.
220
222
 
221
223
  <!-- prettier-ignore -->
222
224
  | Push run at PR head | PR `bkit-tests-check` | `bkit runs mirror` exit |
@@ -387,7 +389,7 @@ Use one. Both open PRs for the same packages. `bkit.depUpdater: "none"` skips th
387
389
 
388
390
  **Renovate, self-hosted.** Copy the workflow example. Suspend the Mend App for this repo (Settings → Applications → Renovate → Configure → remove this repo) or both open `renovate/*` PRs. The cron wakes the bot daily; `renovate.json5` `schedule` still gates normal PRs. Do not narrow the cron to weekly, because `osvVulnerabilityAlerts` PRs need the daily wake.
389
391
 
390
- Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire). Fine-grained PAT, this repo:
392
+ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs do not trigger CI, so required checks and automerge never fire). Use a **fine-grained** PAT when this repo is the only owner-scope bkit touches; use a **classic** PAT when the same token must cover more than one owner — fine-grained PATs cannot span organizations. Fine-grained permissions for this repo:
391
393
 
392
394
  <!-- prettier-ignore -->
393
395
  | Repository permission | Access |
@@ -400,7 +402,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
400
402
  | Dependabot alerts | Read |
401
403
  | Metadata | Read-only |
402
404
 
403
- `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
405
+ `Commit statuses: Read and write` is what opens the PR. Without it Renovate creates the branch and 403s on commit status. There is no separate Checks permission on a fine-grained PAT. Classic equivalent: scopes `repo`, `workflow`, `security_events` (plus `user:email` for commit authorship). Org-owned tokens cannot read the owner email; set the Actions variable `RENOVATE_GIT_AUTHOR` (for example `Renovate Bot <renovate@your-domain>`).
404
406
 
405
407
  **pnpm 11 on Mend's runner.** A large graph can OOM during `pnpm update --lockfile-only`. The example sets `minimumReleaseAge: "1 day"` and caps `PNPM_WORKERS`. To clear the per-install gate, set `minimumReleaseAge: 0` in `pnpm-workspace.yaml`. Deleting the key does not: pnpm 11 defaults it to 1440. Self-hosted on `ubuntu-latest` has the memory; the freshness setting is still yours to keep or drop.
406
408
 
@@ -27,4 +27,15 @@ Run each host (`claude`, `opencode`, `codex`) in its own terminal window — not
27
27
  - Terminal sessions inherit the direnv-loaded `.bkit/.env`; GUI-launched apps do not (`.bkit/providers.md` § macOS GUI-isolation).
28
28
  - macOS: [Ghostty](https://ghostty.org).
29
29
 
30
+ ## Remote access
31
+
32
+ Mostly relevant to the `opencode` host — `claude` / `cursor` / `codex` ship their own mobile / desktop clients. Reach an OpenCode host terminal from another device over a private mesh VPN. Suggested services: [Tailscale](https://tailscale.com/) (mesh VPN; free Personal plan covers device-to-device access), [OpenLens](https://apps.apple.com/us/app/openlens-opencode-client/id6759910797) (OpenCode iOS client).
33
+
34
+ - Bind: `opencode service set hostname 0.0.0.0` (all interfaces) or the tailnet IP (tailnet only); `opencode service set port <port>`; `opencode service start` to apply. Loopback-only default keeps the service off the LAN; tailnet ACLs still apply.
35
+ - HTTPS proxy: `tailscale serve --bg <port>` → `https://<host>.<tailnet>.ts.net`. Requires tailnet HTTPS certificates enabled (DNS page); publishes machine names to the certificate-transparency log (free).
36
+ - Auth: HTTP Basic, username `opencode`, password in `~/.config/opencode/service.json` (mirror `~/.local/state/opencode/service.json`); persists across restarts; `opencode service set password <value>` to rotate. NEVER commit it.
37
+ - Client CLI: `OPENCODE_PASSWORD=<password> opencode --server https://<host>.<tailnet>.ts.net`.
38
+ - Browser / app pairing: `opencode pair --url https://<host>.<tailnet>.ts.net` → one-time link, 5-minute expiry.
39
+ - Pin the port: the service port is dynamic; `serve` targets a fixed port, so pin it or the proxy breaks on restart.
40
+
30
41
  <!-- bkit:end -->
@@ -282,6 +282,19 @@ jobs:
282
282
  done
283
283
  "$RUNNER_TEMP/actionlint" -color
284
284
 
285
+ # bkit >= 5.0.1 gitignores `.bkit/core` + `.bkit/shared` (browse-only symlinks into
286
+ # node_modules/@cbartens/bkit) yet `bkit check` counts a missing link as drift, so a
287
+ # fresh checkout that never runs `bkit install` can never pass the gate below.
288
+ # Recreate them exactly as install/upgrade does: relative targets, never clobber.
289
+ - name: Materialize bkit Payload View Links
290
+ if: steps.cache.outputs.skip != 'true'
291
+ run: |
292
+ for rel in core shared; do
293
+ if [ ! -L ".bkit/$rel" ] && [ ! -e ".bkit/$rel" ]; then
294
+ ln -s "../node_modules/@cbartens/bkit/.bkit/$rel" ".bkit/$rel"
295
+ fi
296
+ done
297
+
285
298
  - name: Run bkit Check
286
299
  if: steps.cache.outputs.skip != 'true'
287
300
  run: pnpm bkit check
@@ -797,8 +810,11 @@ jobs:
797
810
  # # run_e2e = run_level==full && web_affected_eff. run_live = push dev/main && web_affected_eff (@live stays PUSH-ONLY — real LLM/email side effects; a docs-only/empty [force full] push reaches it via web_affected_eff, NOT off a PR/dispatch).
798
811
  # # run_migration: true when migration/seed/seed-generator paths changed (or workflow_dispatch / no-usable-base → run-to-be-safe). Orthogonal to run_level — a run_level=none run can still need replay. Emits into the plan so migration-lane heavy steps gate per-step (job stays always-on).
799
812
  # - name: Decide Release Mirror # [U] OPTIONAL — one CI run per dev commit. mirror_push_run = pull_request
800
- # # && head.repo.full_name == github.repository && head_ref == 'dev' && base_ref == the default branch
801
- # # (head_ref via env:, injection-safe). True → LAST word in the plan: run_level=none, run_e2e/run_live/
813
+ # # && head.repo.full_name == github.repository && base_ref == the default branch && head_ref is a
814
+ # # promotion branch — 'dev', or 'release/*' when the repo promotes via a release branch (bkit's own
815
+ # # does: main only moves via a release/* → main PR). head_ref via env:, injection-safe. The capstone's
816
+ # # bkit runs mirror resolves the push run BY SHA, so a release/* head with no green dev push run fails
817
+ # # red (exit 3), never silently passes. True → LAST word in the plan: run_level=none, run_e2e/run_live/
802
818
  # # run_migration/web_affected=false, so every lane skips (migration lane included — it is always-on, so
803
819
  # # its replay steps must read run_migration) and the capstone copies the dev push run's verdict (JOB 4).
804
820
  # # The release PR head IS the dev tip that push run is testing; re-testing it doubles the slowest run.
@@ -36,7 +36,7 @@ on:
36
36
  - cron: "17 6 * * *"
37
37
 
38
38
  # Least privilege: Renovate authenticates EVERY GitHub operation with BKIT_GH_TOKEN
39
- # below (a fine-grained PAT or App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
39
+ # below (a fine-grained or classic PAT, or an App token — NOT GITHUB_TOKEN). The job GITHUB_TOKEN
40
40
  # needs no write scope.
41
41
  permissions:
42
42
  contents: read
@@ -67,13 +67,15 @@ jobs:
67
67
  # then set `token: ${{ steps.app-token.outputs.token }}` below.
68
68
  - uses: renovatebot/github-action@dd5302ec17783b2fc721b19ae7209b57b1587765 # v46.1.17
69
69
  with:
70
- # Fine-grained PAT secret (default). Repository permissions (this repo):
70
+ # PAT secret (default). FINE-GRAINED repository permissions (this repo):
71
71
  # Contents: Read and write · Pull requests: Read and write ·
72
72
  # Workflows: Read and write (the github-actions manager edits
73
73
  # .github/workflows/* SHAs) · Issues: Read and write (Dependency Dashboard) ·
74
74
  # Dependabot alerts: Read (GitHub's vulnerability feed) · Metadata: Read-only.
75
- # (Personal-account tokens only: Account permission "Email addresses: Read" lets
76
- # Renovate use your verified email as the git author — org-owned tokens have no
75
+ # CLASSIC alternative — when one token must span owners (fine-grained PATs cannot):
76
+ # scopes `repo` · `workflow` · `security_events` (+ `user:email` for authorship).
77
+ # (Personal-account fine-grained tokens only: Account permission "Email addresses: Read"
78
+ # lets Renovate use your verified email as the git author — org-owned tokens have no
77
79
  # such permission, so set RENOVATE_GIT_AUTHOR below instead.)
78
80
  token: ${{ secrets.BKIT_GH_TOKEN }}
79
81
  env:
@@ -82,7 +84,7 @@ jobs:
82
84
  RENOVATE_AUTODISCOVER: "false"
83
85
  RENOVATE_PLATFORM: github
84
86
  # Commit author for Renovate's branches. Optional but recommended on ORG repos:
85
- # org-owned fine-grained PATs cannot grant "Email addresses", so Renovate can't
87
+ # org-owned tokens cannot grant "Email addresses", so Renovate can't
86
88
  # read your email and falls back to the Mend bot author (Unverified commits).
87
89
  # Set the repo variable RENOVATE_GIT_AUTHOR (Settings -> Secrets and variables ->
88
90
  # Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`. Leave the