@cbartens/bkit 5.0.0 → 5.0.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.
- package/.bkit/README.md +10 -14
- package/.bkit/core/.bkit/README.md +9 -13
- package/.bkit/core/.bkit/cloud.md +15 -24
- package/.bkit/core/.bkit/comparison.md +4 -1
- package/.bkit/core/.bkit/install.md +54 -149
- package/.bkit/core/.bkit/jsonl.md +5 -5
- package/.bkit/core/.bkit/templates.md +2 -3
- package/.bkit/core/.bkit/workflows.md +7 -3
- package/.bkit/core/engine/checks/after/auth.ts +16 -114
- package/.bkit/core/engine/checks/after/ci-yml.ts +36 -74
- package/.bkit/core/engine/checks/after/index.ts +156 -182
- package/.bkit/core/engine/checks/after/suppression.ts +53 -0
- package/.bkit/core/engine/checks/before/env.ts +4 -18
- package/.bkit/core/engine/checks/before/files.ts +2 -0
- package/.bkit/core/engine/cli.ts +4 -8
- package/.bkit/core/engine/commands/install/doctor.ts +9 -2
- package/.bkit/core/engine/commands/install/install.ts +24 -2
- package/.bkit/core/engine/commands/install/uninstall.ts +23 -0
- package/.bkit/core/engine/commands/install/upgrade.ts +14 -3
- package/.bkit/core/engine/commands/lib.ts +4 -3
- package/.bkit/core/engine/install/cloud-env.ts +0 -1
- package/.bkit/core/engine/install/modules/cloud.ts +2 -3
- package/.bkit/core/engine/install/modules/core.ts +33 -13
- package/.bkit/core/engine/install/payload-links.ts +150 -0
- package/.bkit/core/engine/install/template-copies.ts +1 -1
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/workflows/bkit-debug.md +19 -12
- package/.bkit/shared/.bkit/.env.example +2 -24
- package/.bkit/shared/docs/deployments.md +2 -7
- package/.bkit/shared/docs/security.md +1 -1
- package/.bkit/shared/gitignore +5 -0
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +0 -5
- package/.bkit/templates/.cursor/Dockerfile +1 -1
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/renovate.json5 +0 -15
- package/.bkit/templates/.github/workflows/bkit-ci.yml +2 -22
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +0 -2
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +0 -5
- package/CHANGELOG.md +17 -0
- package/README.md +5 -6
- package/dist/checks/after/auth.js +16 -108
- package/dist/checks/after/ci-yml.js +30 -67
- package/dist/checks/after/index.js +136 -152
- package/dist/checks/after/suppression.js +39 -0
- package/dist/checks/before/env.js +4 -14
- package/dist/checks/before/files.js +2 -0
- package/dist/cli.js +4 -8
- package/dist/commands/install/doctor.js +4 -2
- package/dist/commands/install/install.js +16 -2
- package/dist/commands/install/uninstall.js +24 -0
- package/dist/commands/install/upgrade.js +14 -3
- package/dist/commands/lib.js +4 -3
- package/dist/install/cloud-env.js +0 -1
- package/dist/install/modules/cloud.js +2 -3
- package/dist/install/modules/core.js +33 -13
- package/dist/install/payload-links.js +119 -0
- package/dist/install/template-copies.js +1 -1
- package/dist/shared/egress.js +1 -1
- package/package.json +2 -2
- package/.bkit/core/engine/checks/after/vercel.ts +0 -101
- package/dist/checks/after/vercel.js +0 -102
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
formatChecklist,
|
|
19
19
|
writeAdvisoriesArtifact,
|
|
20
20
|
} from "../../checks/after/index.js";
|
|
21
|
+
import type { SuppressionNote } from "../../checks/after/suppression.js";
|
|
21
22
|
import { parseDotenv } from "../../install/cloud-env.js";
|
|
22
23
|
|
|
23
24
|
/**
|
|
@@ -126,7 +127,12 @@ export async function runDoctor(
|
|
|
126
127
|
`${LOG_PREFIX} Payload roots: core=${getCoreRoot()} shared=${getSharedRoot()} templates=${getTemplatesRoot()}`,
|
|
127
128
|
);
|
|
128
129
|
const { blockers, advisories: preflightAdvisories } = runPreflight(modules, process.cwd());
|
|
129
|
-
const
|
|
130
|
+
const suppressed: SuppressionNote[] = [];
|
|
131
|
+
const allFindings = runPostInstallCheck(
|
|
132
|
+
[...preflightAdvisories, ...blockers],
|
|
133
|
+
process.cwd(),
|
|
134
|
+
suppressed,
|
|
135
|
+
);
|
|
130
136
|
// Broken install: the opencode host is on disk but neither provider signal survives.
|
|
131
137
|
// `bkit check` and `bkit upgrade` exit 1 with the fix; doctor reports it here and does
|
|
132
138
|
// not enforce.
|
|
@@ -142,7 +148,7 @@ export async function runDoctor(
|
|
|
142
148
|
}
|
|
143
149
|
}
|
|
144
150
|
|
|
145
|
-
const banner = formatChecklist(allFindings);
|
|
151
|
+
const banner = formatChecklist(allFindings, suppressed);
|
|
146
152
|
if (banner) {
|
|
147
153
|
console.log(banner);
|
|
148
154
|
} else {
|
|
@@ -153,6 +159,7 @@ export async function runDoctor(
|
|
|
153
159
|
mode: "doctor",
|
|
154
160
|
version: getInstallingVersion(),
|
|
155
161
|
logPrefix: LOG_PREFIX,
|
|
162
|
+
suppressed,
|
|
156
163
|
});
|
|
157
164
|
|
|
158
165
|
// opencode host diagnostics: report required tools and cred presence per provider.
|
|
@@ -23,6 +23,7 @@ import {
|
|
|
23
23
|
runPostInstallCheck,
|
|
24
24
|
writeAdvisoriesArtifact,
|
|
25
25
|
} from "../../checks/after/index.js";
|
|
26
|
+
import type { SuppressionNote } from "../../checks/after/suppression.js";
|
|
26
27
|
import { findMissingOwnedHooks, detectOwnedHookMissing } from "../../checks/after/managed.js";
|
|
27
28
|
import { resolveTokens } from "../../install/placeholders.js";
|
|
28
29
|
import {
|
|
@@ -339,6 +340,7 @@ export async function runInstall(
|
|
|
339
340
|
const advisories: import("../../checks/before/index.js").PreflightFinding[] = [
|
|
340
341
|
...preflightAdvisories,
|
|
341
342
|
];
|
|
343
|
+
|
|
342
344
|
const ws: WriteSet = { writes: [] };
|
|
343
345
|
const postDispatch: Array<() => void> = [];
|
|
344
346
|
|
|
@@ -461,6 +463,24 @@ export async function runInstall(
|
|
|
461
463
|
console.log(`${LOG_PREFIX} Done. ${totalWrites} write(s).`);
|
|
462
464
|
}
|
|
463
465
|
|
|
466
|
+
// Phase 2 has completed its writes. Re-run Phase 1 detection and use its result for the
|
|
467
|
+
// post-install checklist, so the banner reflects the state on disk AFTER the writes.
|
|
468
|
+
// Otherwise a drift finding Phase 2 just resolved (tier2-json-drift, tier2-text-drift,
|
|
469
|
+
// bkit-version-pin-stale) is still reported as unresolved, contradicting the "Done"
|
|
470
|
+
// banner above. `check` (dryRun) wrote nothing, so its Phase 1 findings already describe
|
|
471
|
+
// the current state and are kept as-is. Module-accumulated advisories (pushed during
|
|
472
|
+
// dispatch) are preserved; only the Phase 1 seeds are replaced, in their original order.
|
|
473
|
+
if (!dryRun) {
|
|
474
|
+
const moduleAdvisories = advisories.slice(preflightAdvisories.length);
|
|
475
|
+
const { advisories: freshPreflightAdvisories } = runPreflight(
|
|
476
|
+
effectiveModules,
|
|
477
|
+
process.cwd(),
|
|
478
|
+
undefined,
|
|
479
|
+
issueTracker,
|
|
480
|
+
);
|
|
481
|
+
ctx.advisories = [...freshPreflightAdvisories, ...moduleAdvisories];
|
|
482
|
+
}
|
|
483
|
+
|
|
464
484
|
// --- Phase 3: Post-install checks (re-detect + unified output) ---
|
|
465
485
|
// Runs for both install AND check — detectors are read-only, so check produces
|
|
466
486
|
// the same advisory set as install would emit against the same filesystem state.
|
|
@@ -475,19 +495,21 @@ export async function runInstall(
|
|
|
475
495
|
} catch (err) {
|
|
476
496
|
void err; // Non-fatal — changelog header is informational
|
|
477
497
|
}
|
|
478
|
-
const
|
|
498
|
+
const suppressed: SuppressionNote[] = [];
|
|
499
|
+
const postFindings = runPostInstallCheck(ctx.advisories, process.cwd(), suppressed);
|
|
479
500
|
// check only: install has just written every hook file of the modules it dispatched, and a
|
|
480
501
|
// missing bkit-cloud-bootstrap.sh after `install --claude` is not that run's fault.
|
|
481
502
|
const missingHooks = dryRun ? findMissingOwnedHooks(process.cwd(), effectiveModules) : [];
|
|
482
503
|
const missingHooksFinding = detectOwnedHookMissing(missingHooks);
|
|
483
504
|
if (missingHooksFinding) postFindings.push(missingHooksFinding);
|
|
484
|
-
const banner = formatChecklist(postFindings);
|
|
505
|
+
const banner = formatChecklist(postFindings, suppressed);
|
|
485
506
|
if (banner) console.log(banner);
|
|
486
507
|
writeAdvisoriesArtifact(postFindings, {
|
|
487
508
|
cwd: process.cwd(),
|
|
488
509
|
mode: dryRun ? "check" : "install",
|
|
489
510
|
version: getInstallingVersion(),
|
|
490
511
|
logPrefix: LOG_PREFIX,
|
|
512
|
+
suppressed,
|
|
491
513
|
});
|
|
492
514
|
|
|
493
515
|
// Check mode: exit 1 on drift (see reportCheckDrift).
|
|
@@ -38,6 +38,7 @@ import {
|
|
|
38
38
|
findTemplateSource,
|
|
39
39
|
TEMPLATE_COPIES_DIR,
|
|
40
40
|
} from "../../shared/package-roots.js";
|
|
41
|
+
import { PAYLOAD_LINKS } from "../../install/payload-links.js";
|
|
41
42
|
import { removeOpencodeProviderBlock, renderOpencodeJson } from "../../install/modules/opencode.js";
|
|
42
43
|
import {
|
|
43
44
|
CLAUDE_CLOUD_RELPATH,
|
|
@@ -793,6 +794,28 @@ export async function runUninstall(
|
|
|
793
794
|
}
|
|
794
795
|
}
|
|
795
796
|
|
|
797
|
+
// Full/core uninstall: the payload view links (`.bkit/core`, `.bkit/shared`) are
|
|
798
|
+
// bkit-created symlinks into the package and go with it. Symlinks ONLY — a real
|
|
799
|
+
// directory or file at that path is consumer content (install's no-clobber guard)
|
|
800
|
+
// and stays. Never in dogfood, where `.bkit/core` is bkit's own source.
|
|
801
|
+
if (moduleList.includes("core") && path.resolve(ctx.cwd) !== getPkgRoot()) {
|
|
802
|
+
for (const { relPath } of PAYLOAD_LINKS) {
|
|
803
|
+
const linkAbs = path.join(ctx.cwd, relPath);
|
|
804
|
+
let st: fs.Stats | null = null;
|
|
805
|
+
try {
|
|
806
|
+
st = fs.lstatSync(linkAbs);
|
|
807
|
+
} catch {
|
|
808
|
+
st = null; // absent
|
|
809
|
+
}
|
|
810
|
+
if (st?.isSymbolicLink() !== true) continue;
|
|
811
|
+
result.deleted.push(relPath);
|
|
812
|
+
if (!ctx.dryRun) {
|
|
813
|
+
fs.rmSync(linkAbs, { force: true });
|
|
814
|
+
console.log(`${ctx.logPrefix} delete: ${relPath} (payload view link)`);
|
|
815
|
+
}
|
|
816
|
+
}
|
|
817
|
+
}
|
|
818
|
+
|
|
796
819
|
// Prune bkit-authored dirs left empty by the deletions above (e.g. .claude/agents,
|
|
797
820
|
// .claude/hooks). Candidates are the parent
|
|
798
821
|
// dirs of everything deleted, plus their ancestors; each is removed ONLY when it is actually
|
|
@@ -68,6 +68,7 @@ import {
|
|
|
68
68
|
writeCursorCliPermissionsArtifact,
|
|
69
69
|
} from "../../install/cloud-env.js";
|
|
70
70
|
import { syncTemplateCopies, formatTemplateChanges } from "../../install/template-copies.js";
|
|
71
|
+
import { formatPayloadLinkChanges, syncPayloadLinks } from "../../install/payload-links.js";
|
|
71
72
|
import { renderOpencodeJson, reconcileOpencodeJson } from "../../install/modules/opencode.js";
|
|
72
73
|
import { type ModuleContext, renderManagedOutputs } from "../../install/modules/index.js";
|
|
73
74
|
import { reconcileMcpJson, enrichClaudeSettingsAllows } from "../../install/modules/claude.js";
|
|
@@ -552,8 +553,8 @@ async function resolveLatestPublishedVersion(cwd: string): Promise<string> {
|
|
|
552
553
|
if (r.status !== 0 || !r.stdout || !r.stdout.trim()) {
|
|
553
554
|
console.error(
|
|
554
555
|
`${LOG_PREFIX} could not resolve the latest @cbartens/bkit version from the registry ` +
|
|
555
|
-
`(pnpm view exit ${r.status ?? "null"}).
|
|
556
|
-
`
|
|
556
|
+
`(pnpm view exit ${r.status ?? "null"}). Check your network / registry access, ` +
|
|
557
|
+
`or pin a version with --to=<version>.`,
|
|
557
558
|
);
|
|
558
559
|
process.exit(1);
|
|
559
560
|
}
|
|
@@ -626,7 +627,7 @@ export async function runSelfBump(flags: UpgradeFlags, cwd: string): Promise<boo
|
|
|
626
627
|
if (add.status !== 0) {
|
|
627
628
|
console.error(
|
|
628
629
|
`${LOG_PREFIX} \`${addCmd}\` failed (exit ${add.status ?? "null"}). ` +
|
|
629
|
-
`
|
|
630
|
+
`Check your network / registry access. Nothing re-rendered.`,
|
|
630
631
|
);
|
|
631
632
|
process.exit(1);
|
|
632
633
|
}
|
|
@@ -799,6 +800,16 @@ export async function runUpgradeCommand(upgradeFlags: UpgradeFlags): Promise<voi
|
|
|
799
800
|
const templateReport = formatTemplateChanges(templateChanges);
|
|
800
801
|
if (templateReport) console.log(`${LOG_PREFIX} ${templateReport}`);
|
|
801
802
|
|
|
803
|
+
// Payload view links — the same sync install runs (`.bkit/core` + `.bkit/shared`
|
|
804
|
+
// point into the installed package). Never clobbers a real directory; a platform
|
|
805
|
+
// refusal is reported, never fatal. Throwaway WriteSet: links carry no hash.
|
|
806
|
+
const linkChanges = syncPayloadLinks(process.cwd(), {
|
|
807
|
+
dryRun: upgradeFlags.dryRun,
|
|
808
|
+
ws: { writes: [] },
|
|
809
|
+
});
|
|
810
|
+
const linkReport = formatPayloadLinkChanges(linkChanges);
|
|
811
|
+
if (linkReport) console.log(`${LOG_PREFIX} ${linkReport}`);
|
|
812
|
+
|
|
802
813
|
// Re-render all installed provider blocks for upgrade.
|
|
803
814
|
// The candidates walk above handles the ACTIVE provider's block via renderOpencodeJson.
|
|
804
815
|
// For each ADDITIONAL installed provider, reconcile their template block into opencode.json
|
|
@@ -274,8 +274,9 @@ const isHelp = (arg: string | undefined) => arg === "--help" || arg === "-h";
|
|
|
274
274
|
* Run `argv` (without the leading `bkit`) if it names a registered command.
|
|
275
275
|
* Returns the exit code, or null when `argv` is not a command, so the caller falls
|
|
276
276
|
* through to the classic verbs. A noun that is also a classic verb (`status`)
|
|
277
|
-
* routes only when the second word is one of its verbs
|
|
278
|
-
* its classic meaning
|
|
277
|
+
* routes only when the second word is one of its verbs or a help flag, so
|
|
278
|
+
* `bkit status` keeps its classic meaning while `bkit status --help` still lists
|
|
279
|
+
* the noun's own verbs.
|
|
279
280
|
*/
|
|
280
281
|
export async function runCommand(
|
|
281
282
|
argv: string[],
|
|
@@ -287,7 +288,7 @@ export async function runCommand(
|
|
|
287
288
|
if (!cmd) return null;
|
|
288
289
|
const verb = argv[1];
|
|
289
290
|
const isVerb = verb !== undefined && Object.hasOwn(cmd.verbs, verb);
|
|
290
|
-
if (!isVerb && options.classicVerbs.has(cmd.noun)) return null;
|
|
291
|
+
if (!isVerb && options.classicVerbs.has(cmd.noun) && !isHelp(verb)) return null;
|
|
291
292
|
|
|
292
293
|
const tag = logTag(cmd.noun);
|
|
293
294
|
if (!isVerb) {
|
|
@@ -40,7 +40,6 @@ export const SESSION_HIJACK_KEYS = [
|
|
|
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
42
|
["BKIT_GH_TOKEN", "<fine-grained PAT — see .bkit/cloud.md § BKIT_GH_TOKEN permissions>"],
|
|
43
|
-
["BKIT_GH_TOKEN_INSTALL", "<classic PAT with read:packages>"],
|
|
44
43
|
];
|
|
45
44
|
|
|
46
45
|
// Earlier-compaction override — a bkit constant, not a secret. Appended to the
|
|
@@ -84,7 +84,6 @@ export function runCloudModule(ctx: ModuleContext): void {
|
|
|
84
84
|
" - Run `/install-github-app` (Claude Code CLI) to install the Claude GitHub App on your repo. This is required — `claude-code-action@v1` authenticates as the App via OIDC (`id-token: write`); without the App it fails at boot with an OIDC error.\n" +
|
|
85
85
|
" - GitHub Actions permissions — flip BOTH org AND repo: Settings → Actions → General → Workflow permissions = **Read and write permissions** + tick **Allow GitHub Actions to create and approve pull requests**.\n" +
|
|
86
86
|
" - Add `ANTHROPIC_API_KEY` to repo secrets (Settings → Secrets and variables → Actions). Used by `claude-code-action@v1` (job env keeps this vendor name; local `.bkit/.env` stores it as `BKIT_ANTHROPIC_API_KEY`).\n" +
|
|
87
|
-
" - Do NOT add `BKIT_GH_TOKEN_INSTALL` to this workflow — it is package-install scoped and has no access to the consumer repo. Repo git/gh ops use the auto-provided `github.token` via the workflow's `permissions:` block.\n" +
|
|
88
87
|
" - Label the issue `bkit:auto` before pushing the build commit — without the label the CI auto-route exits no-op.\n\n" +
|
|
89
88
|
"OPTIONAL (manual phase launch): after `/install-github-app`, comment `@claude /bkit-plan` (or any phase) on a GitHub issue/PR to launch it from the tracker UI. The App's generated `claude.yml` triggers on mention events; `bkit-cloud.yml` triggers on CI completion + `workflow_dispatch` — the two coexist.\n\n" +
|
|
90
89
|
"Both the CI-driven path and the `@claude` mention path invoke the same `/bkit-auto` orchestrator (mirrored to `.claude/commands/bkit-auto.md` on each `pnpm bkit install`).",
|
|
@@ -103,7 +102,7 @@ export function runCloudModule(ctx: ModuleContext): void {
|
|
|
103
102
|
"IN CLAUDE APP (claude.ai/code → environment selector → + Add environment):\n" +
|
|
104
103
|
" - Name: the repo name (e.g. `acme-web`) — one environment per repo, since secrets are per-repo.\n" +
|
|
105
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" +
|
|
106
|
-
" - Environment variables: `BKIT_GH_TOKEN` (fine-grained PAT for GitHub MCP), `
|
|
105
|
+
" - Environment variables: `BKIT_GH_TOKEN` (fine-grained PAT for GitHub MCP), `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=70`.\n" +
|
|
107
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" +
|
|
108
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.",
|
|
109
108
|
});
|
|
@@ -165,7 +164,7 @@ export function runCloudModule(ctx: ModuleContext): void {
|
|
|
165
164
|
action:
|
|
166
165
|
"Copy-paste-ready values (resolved from your `.envrc`) are written to `.cursor/bkit-cloud.md` (gitignored) on every install.\n\n" +
|
|
167
166
|
"IN THE CLOUD AGENTS DASHBOARD (https://cursor.com/dashboard/cloud-agents → your environment → Secrets tab) — add each as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript):\n" +
|
|
168
|
-
" - `BKIT_GH_TOKEN
|
|
167
|
+
" - `BKIT_GH_TOKEN`.\n" +
|
|
169
168
|
" - Tracker secret (Linear): `BKIT_LINEAR_API_KEY` (generate at https://linear.app/settings/api). `LINEAR_ISSUE_ID` is injected per-session — don't hardcode.\n" +
|
|
170
169
|
" - First session after Dockerfile changes rebuilds the image; subsequent sessions reuse cached layers.\n\n" +
|
|
171
170
|
"Full recipe in bkit's `cloud.md`; the paste-ready block is in `.cursor/bkit-cloud.md`.",
|
|
@@ -13,6 +13,7 @@ import {
|
|
|
13
13
|
} from "../version-file.js";
|
|
14
14
|
import type { TokenMap } from "../placeholders.js";
|
|
15
15
|
import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
|
|
16
|
+
import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
|
|
16
17
|
import type { PreflightFinding } from "../../checks/before/index.js";
|
|
17
18
|
import {
|
|
18
19
|
getPkgRoot,
|
|
@@ -498,6 +499,34 @@ export function runCoreModule(ctx: ModuleContext): void {
|
|
|
498
499
|
}
|
|
499
500
|
}
|
|
500
501
|
|
|
502
|
+
// 3b3. Payload view links — `.bkit/core` + `.bkit/shared` symlinks into the
|
|
503
|
+
// installed package (browse-only, gitignored; no-op in dogfood). A real
|
|
504
|
+
// directory or file at either path is never clobbered (advisory); a platform
|
|
505
|
+
// refusal is an advisory, never a failure.
|
|
506
|
+
const linkChanges = syncPayloadLinks(cwd, { dryRun, ws });
|
|
507
|
+
for (const rel of linkChanges.created) {
|
|
508
|
+
console.log(`${logPrefix} ${tag}payload link: ${rel}`);
|
|
509
|
+
}
|
|
510
|
+
for (const rel of linkChanges.repaired) {
|
|
511
|
+
console.log(`${logPrefix} ${tag}payload link repaired: ${rel}`);
|
|
512
|
+
}
|
|
513
|
+
for (const rel of linkChanges.skippedRealDir) {
|
|
514
|
+
advisories.push({
|
|
515
|
+
id: "payload-link-real-dir",
|
|
516
|
+
severity: "advisory",
|
|
517
|
+
detect: `${rel} is a real directory or file, not a view symlink into the installed package — left untouched.`,
|
|
518
|
+
action: `bkit never overwrites consumer content. The ${rel} view is a symlink into node_modules/@cbartens/bkit; if you want it, remove your own ${rel} by hand and re-run \`bkit install\`.`,
|
|
519
|
+
});
|
|
520
|
+
}
|
|
521
|
+
for (const rel of linkChanges.failed) {
|
|
522
|
+
advisories.push({
|
|
523
|
+
id: "payload-link-failed",
|
|
524
|
+
severity: "advisory",
|
|
525
|
+
detect: `could not create the ${rel} view symlink into the installed package (the platform refused).`,
|
|
526
|
+
action: `Browse-only — bkit reads its payload from the package regardless. To add the view by hand on POSIX: ln -s ../node_modules/@cbartens/bkit/${rel} ${rel}`,
|
|
527
|
+
});
|
|
528
|
+
}
|
|
529
|
+
|
|
501
530
|
// 3c. The bkit:gate:* / bkit:deps:* package.json scripts (add-if-missing). The
|
|
502
531
|
// advisories read the result.
|
|
503
532
|
seedCorePackageJsonScripts(ctx);
|
|
@@ -526,6 +555,8 @@ export function runCoreModule(ctx: ModuleContext): void {
|
|
|
526
555
|
if (relPath.startsWith(".agents" + path.sep)) continue;
|
|
527
556
|
// Template copies carry no hash.
|
|
528
557
|
if (relPath.startsWith(TEMPLATE_COPIES_DIR + path.sep)) continue;
|
|
558
|
+
// Payload view links carry no hash either — a symlink's bytes are the package's.
|
|
559
|
+
if (PAYLOAD_LINK_RELPATHS.has(relPath)) continue;
|
|
529
560
|
if (!fs.existsSync(absPath)) continue;
|
|
530
561
|
const hash = hashFile(absPath);
|
|
531
562
|
if (hash) newCanonicalEntries[relPath] = hash;
|
|
@@ -572,19 +603,8 @@ export function runCoreModule(ctx: ModuleContext): void {
|
|
|
572
603
|
detect: "First install detected (.bkit/version was absent).",
|
|
573
604
|
action:
|
|
574
605
|
"Post-install steps:\n\n" +
|
|
575
|
-
"1.
|
|
576
|
-
"
|
|
577
|
-
" not currently supported by GitHub Packages npm registry).\n" +
|
|
578
|
-
" - GitHub Settings → Secrets and variables → Actions → New repository secret\n" +
|
|
579
|
-
" - Name: BKIT_GH_TOKEN_INSTALL\n" +
|
|
580
|
-
" - See README.md ## Consumer CI auth for full setup.\n\n" +
|
|
581
|
-
"2. Add a `.npmrc` at your repo root with the @cbartens registry mapping (the\n" +
|
|
582
|
-
" auth token is NOT stored here — it goes in pnpm's user-level config):\n" +
|
|
583
|
-
" @cbartens:registry=https://npm.pkg.github.com\n\n" +
|
|
584
|
-
"3. Write the token into pnpm's user-level config (run once; CI does this in its\n" +
|
|
585
|
-
" install step). pnpm >=10.34.3 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} ref:\n" +
|
|
586
|
-
' pnpm config set "//npm.pkg.github.com/:_authToken=$BKIT_GH_TOKEN_INSTALL"\n\n' +
|
|
587
|
-
"4. Run `pnpm install` to refresh the lockfile, then commit.\n\n" +
|
|
606
|
+
"1. Run `pnpm install` to refresh the lockfile, then commit.\n\n" +
|
|
607
|
+
"2. See `.bkit/install.md` for consumer setup and `.bkit/README.md` for ongoing ops.\n\n" +
|
|
588
608
|
"Note: bkit seeded the bkit:gate:* / bkit:deps:* package.json scripts every workflow\n" +
|
|
589
609
|
"runs (existing values are never touched). The tool scripts they chain (typecheck,\n" +
|
|
590
610
|
"lint, format:check, lint:prose, slop:delta) and the devDeps those need are yours to\n" +
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
// install/payload-links.ts — the consumer's `.bkit/core` and `.bkit/shared` view
|
|
2
|
+
// links: relative symlinks into the installed package payload (#525), so the
|
|
3
|
+
// workflow / prompt / hook sources are browsable from the consumer repo without
|
|
4
|
+
// copying. Views, not copies — always the installed version, never hashed.
|
|
5
|
+
|
|
6
|
+
import * as fs from "node:fs";
|
|
7
|
+
import * as path from "node:path";
|
|
8
|
+
import { getCoreRoot, getPkgRoot, getSharedRoot } from "../shared/package-roots.js";
|
|
9
|
+
import type { WriteSet } from "./write.js";
|
|
10
|
+
|
|
11
|
+
// The two view links: a symlink at the consumer-relative `relPath` pointing at the
|
|
12
|
+
// package payload dir `target()` resolves to. Relative targets, so the link keeps
|
|
13
|
+
// working when the repo moves; both dangle on a fresh clone or in CI (no
|
|
14
|
+
// node_modules), which is why the managed `.gitignore` block carries both paths
|
|
15
|
+
// and checks/before/files.ts BKIT_GITIGNORE_LINES lists them.
|
|
16
|
+
export const PAYLOAD_LINKS: ReadonlyArray<{ relPath: string; target: () => string }> = [
|
|
17
|
+
{ relPath: path.join(".bkit", "core"), target: getCoreRoot },
|
|
18
|
+
{ relPath: path.join(".bkit", "shared"), target: getSharedRoot },
|
|
19
|
+
];
|
|
20
|
+
|
|
21
|
+
/** The consumer-relative paths above, as a lookup set (version-hash exclusion). */
|
|
22
|
+
export const PAYLOAD_LINK_RELPATHS: ReadonlySet<string> = new Set(
|
|
23
|
+
PAYLOAD_LINKS.map((l) => l.relPath),
|
|
24
|
+
);
|
|
25
|
+
|
|
26
|
+
/** What a sync did, per link path. */
|
|
27
|
+
export interface PayloadLinkChanges {
|
|
28
|
+
created: string[];
|
|
29
|
+
repaired: string[];
|
|
30
|
+
kept: string[];
|
|
31
|
+
/** Real directory or file at the link path — never clobbered; advisory-worthy. */
|
|
32
|
+
skippedRealDir: string[];
|
|
33
|
+
/** Platform refused the symlink (e.g. Windows without Developer Mode). Advisory, never fatal. */
|
|
34
|
+
failed: string[];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Create the view link at `linkAbs` pointing at `targetAbs`: a relative `dir`
|
|
39
|
+
* symlink first; where the platform refuses it (Windows without Developer Mode or
|
|
40
|
+
* elevation) fall back to an absolute `junction`, which needs no privilege.
|
|
41
|
+
* `symlinkFn` is injectable so the platform branch is testable off-Windows.
|
|
42
|
+
*/
|
|
43
|
+
export function createPayloadLink(
|
|
44
|
+
targetAbs: string,
|
|
45
|
+
linkAbs: string,
|
|
46
|
+
symlinkFn: (target: string, link: string, type?: "dir" | "junction") => void = fs.symlinkSync,
|
|
47
|
+
): "relative" | "junction" {
|
|
48
|
+
const relTarget = path.relative(path.dirname(linkAbs), targetAbs);
|
|
49
|
+
try {
|
|
50
|
+
symlinkFn(relTarget, linkAbs, "dir");
|
|
51
|
+
return "relative";
|
|
52
|
+
} catch {
|
|
53
|
+
symlinkFn(targetAbs, linkAbs, "junction");
|
|
54
|
+
return "junction";
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// Create or refresh the consumer's `.bkit/core` + `.bkit/shared` view links into
|
|
59
|
+
// the package payload. Idempotent: a correct link is kept, a dangling or
|
|
60
|
+
// mis-pointed symlink is re-pointed, a real directory or file is NEVER clobbered
|
|
61
|
+
// (skippedRealDir) and a platform refusal is only recorded (failed). Every create
|
|
62
|
+
// or repair pushes a ws write in dry-run and live alike, so `bkit check` flags a
|
|
63
|
+
// missing or broken link as drift. No-op in dogfood: there `.bkit/core` IS the
|
|
64
|
+
// package source, never a view onto it.
|
|
65
|
+
export function syncPayloadLinks(
|
|
66
|
+
cwd: string,
|
|
67
|
+
opts: { dryRun: boolean; ws: WriteSet },
|
|
68
|
+
): PayloadLinkChanges {
|
|
69
|
+
const changes: PayloadLinkChanges = {
|
|
70
|
+
created: [],
|
|
71
|
+
repaired: [],
|
|
72
|
+
kept: [],
|
|
73
|
+
skippedRealDir: [],
|
|
74
|
+
failed: [],
|
|
75
|
+
};
|
|
76
|
+
if (path.resolve(cwd) === getPkgRoot()) return changes;
|
|
77
|
+
|
|
78
|
+
for (const { relPath, target } of PAYLOAD_LINKS) {
|
|
79
|
+
const linkAbs = path.join(cwd, relPath);
|
|
80
|
+
const targetAbs = target();
|
|
81
|
+
if (!fs.existsSync(targetAbs)) {
|
|
82
|
+
changes.failed.push(relPath); // package payload missing — package corrupt?
|
|
83
|
+
continue;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// lstat, not stat: the symlink itself is what matters, never its target.
|
|
87
|
+
let st: fs.Stats | null = null;
|
|
88
|
+
try {
|
|
89
|
+
st = fs.lstatSync(linkAbs);
|
|
90
|
+
} catch {
|
|
91
|
+
st = null; // absent
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
if (st !== null && !st.isSymbolicLink()) {
|
|
95
|
+
changes.skippedRealDir.push(relPath); // consumer content — never clobber
|
|
96
|
+
continue;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if (st !== null) {
|
|
100
|
+
// A symlink: keep when it already resolves to the payload, re-point otherwise
|
|
101
|
+
// (dangling — realpathSync throws — or pointing somewhere else).
|
|
102
|
+
let resolves = false;
|
|
103
|
+
try {
|
|
104
|
+
resolves = fs.realpathSync(linkAbs) === fs.realpathSync(targetAbs);
|
|
105
|
+
} catch {
|
|
106
|
+
resolves = false;
|
|
107
|
+
}
|
|
108
|
+
if (resolves) {
|
|
109
|
+
changes.kept.push(relPath);
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
if (!opts.dryRun) fs.rmSync(linkAbs);
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
if (!opts.dryRun) {
|
|
116
|
+
fs.mkdirSync(path.dirname(linkAbs), { recursive: true });
|
|
117
|
+
try {
|
|
118
|
+
createPayloadLink(targetAbs, linkAbs);
|
|
119
|
+
} catch {
|
|
120
|
+
changes.failed.push(relPath);
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
(st !== null ? changes.repaired : changes.created).push(relPath);
|
|
125
|
+
opts.ws.writes.push({ path: relPath, action: "write" });
|
|
126
|
+
}
|
|
127
|
+
return changes;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// The upgrade report for a link sync: one line per created, repaired, skipped or
|
|
131
|
+
// failed link. Empty when every link was already correct.
|
|
132
|
+
export function formatPayloadLinkChanges(changes: PayloadLinkChanges): string {
|
|
133
|
+
const lines = [
|
|
134
|
+
...changes.created.map((p) => ` linked: ${p}`),
|
|
135
|
+
...changes.repaired.map((p) => ` repaired: ${p}`),
|
|
136
|
+
...changes.skippedRealDir.map(
|
|
137
|
+
(p) =>
|
|
138
|
+
` skipped: ${p} — a real directory or file, never overwritten; remove it yourself to get the view link`,
|
|
139
|
+
),
|
|
140
|
+
...changes.failed.map(
|
|
141
|
+
(p) =>
|
|
142
|
+
` failed: ${p} — platform refused the symlink (browse-only; bkit reads its payload from the package regardless)`,
|
|
143
|
+
),
|
|
144
|
+
];
|
|
145
|
+
if (lines.length === 0) return "";
|
|
146
|
+
return [
|
|
147
|
+
"Payload view links — `.bkit/core` + `.bkit/shared` point into the installed package (gitignored, browse-only):",
|
|
148
|
+
...lines,
|
|
149
|
+
].join("\n");
|
|
150
|
+
}
|
|
@@ -98,7 +98,7 @@ function pruneEmptyDirs(root: string): void {
|
|
|
98
98
|
|
|
99
99
|
/** One-line pointer to the template docs, shared by the install and upgrade messages. */
|
|
100
100
|
export const TEMPLATES_POINTER =
|
|
101
|
-
"Templates:
|
|
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
103
|
/**
|
|
104
104
|
* The upgrade report for a template sync: one line per changed, added or removed
|
|
@@ -173,7 +173,7 @@ export const BKIT_EGRESS_SOURCES: readonly EgressSource[] = [
|
|
|
173
173
|
{
|
|
174
174
|
id: "pkg-github",
|
|
175
175
|
kind: "package-registry",
|
|
176
|
-
hosts: ["
|
|
176
|
+
hosts: ["raw.githubusercontent.com"],
|
|
177
177
|
bases: ["github.com", "githubusercontent.com"],
|
|
178
178
|
},
|
|
179
179
|
{ id: "skills-sh", kind: "skills", hosts: ["skills.sh"], bases: ["skills.sh"] },
|
|
@@ -546,22 +546,29 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
546
546
|
"{BKIT}" branches push --mode=feature --require-ci >/dev/null
|
|
547
547
|
```
|
|
548
548
|
Hold the close's `parentSha` as `{CLOSE_PARENT}`.
|
|
549
|
-
3.
|
|
549
|
+
3. Probe live PR state (`{PR_OPEN}` = 0 with no probe when `BRANCH` = `dev` **or** `main`):
|
|
550
550
|
```bash
|
|
551
|
-
"{BKIT}"
|
|
552
|
-
"{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
|
|
551
|
+
"{BKIT}" prs probe --head="{BRANCH}" --base=dev
|
|
553
552
|
```
|
|
553
|
+
- **If** exit 0 → `{PR_OPEN}` = 1; hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}`.
|
|
554
|
+
- **If** exit 1 → `{PR_OPEN}` = 0.
|
|
555
|
+
- **If** exit 80 → `list_pull_requests` (head `{BRANCH}`, base `dev`, state open) → found → `{PR_OPEN}` = 1 with its `number` / `url`; none → `{PR_OPEN}` = 0; record via `"{BKIT}" prs transport-row --file="{STATUS}" --kind=fallback --asserted-by=<re-read>`.
|
|
556
|
+
- **Else** → **Failure Path**.
|
|
557
|
+
- **If** `{PR_OPEN}` = 0 → record the close row and audit the landed commit; `{LIVE_SKIPPED}` = `--field="testsLiveSkipped=No live tests ran, runtime-only defects not gated (not declared or opted out)."` when `TEST_SCOPE` lacks `live`, else empty:
|
|
558
|
+
```bash
|
|
559
|
+
"{BKIT}" steps done --file="{STATUS}" --workflow=debug --step=debug-close-workflow --parent-sha={CLOSE_PARENT} {LIVE_SKIPPED} --commit=none >/dev/null || exit 1
|
|
560
|
+
"{BKIT}" prs transport-row --file="{STATUS}" --kind=close --shape=push --sha={CLOSE_PARENT} --scan --cross-check=gh
|
|
561
|
+
```
|
|
554
562
|
4. Set `TRIGGER_PR`:
|
|
555
563
|
- **If** `BRANCH` = `dev` **or** `main` → push to trigger branch (CI fires) → `TRIGGER_PR` = 0.
|
|
556
|
-
- **If** `
|
|
557
|
-
- **
|
|
558
|
-
|
|
559
|
-
5. **If** `TRIGGER_PR` = 1 → create PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present):
|
|
564
|
+
- **If** `{PR_OPEN}` = 1 → the close push fires `pull_request` → `TRIGGER_PR` = 0.
|
|
565
|
+
- **Else** → `TRIGGER_PR` = 1.
|
|
566
|
+
5. **If** `TRIGGER_PR` = 1 → create or adopt the PR (body names `docs/plans/{YYYYMM}/{FID}-plan.md` if present); `--existing=reuse` adopts a PR that appeared since sub-step 3:
|
|
560
567
|
```bash
|
|
561
|
-
"{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --plan=docs/plans/{YYYYMM}/{FID}-plan.md
|
|
568
|
+
"{BKIT}" prs open --fid={FID} --title="feat({FID}): debug-remediated" --issue="{ISSUE_ID}" --existing=reuse --plan=docs/plans/{YYYYMM}/{FID}-plan.md
|
|
562
569
|
```
|
|
563
570
|
Route:
|
|
564
|
-
- **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}
|
|
571
|
+
- **If** exit 0 → hold `number` as `{PR_NUMBER}`, `url` as `{PR_URL}` (created, or the adopted PR).
|
|
565
572
|
- **If** exit 80 → `create_pull_request` with the printed `title` / `body` / `base` / `head` → its number as `{PR_NUMBER}`, URL as `{PR_URL}`.
|
|
566
573
|
- **Else** → **Failure Path**.
|
|
567
574
|
6. **If** `TRIGGER_PR` = 1 → commit and push the CI-triggering head (`{LABEL_FLAGS}` = one `--label=<name>` per re-read `LABELS` entry):
|
|
@@ -570,7 +577,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
570
577
|
git add -A && git commit --allow-empty -m "chore({FID}): create-pr bkit [verbose ci]${AUTO_ROUTE_SUFFIX}" || exit 1
|
|
571
578
|
"{BKIT}" branches push --mode=feature --require-ci
|
|
572
579
|
```
|
|
573
|
-
7. **Run only if** `
|
|
580
|
+
7. **Run only if** `{PR_OPEN}` = 1 **or** `TRIGGER_PR` = 1 — CI-Dispatch Gate on the pushed head; it records `{DISPATCH_ROW}`, cross-checks the transport and records the close transport. `{DISPATCH_ROW}` = `--step=debug-close-workflow {LIVE_SKIPPED}` when `{PR_OPEN}` = 1, `--step=debug-create-pr --artifact={PR_URL}` after a created PR; `{LABEL_FLAGS}` as in sub-step 6:
|
|
574
581
|
```bash
|
|
575
582
|
"{BKIT}" runs dispatch --pr={PR_NUMBER} --fid={FID} {LABEL_FLAGS} --file="{STATUS}" --workflow=debug {DISPATCH_ROW} {CI_REENTRY}
|
|
576
583
|
```
|
|
@@ -617,7 +624,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
617
624
|
"{BKIT}" steps gate --file="{STATUS}" --workflow=debug --step=debug-close-workflow
|
|
618
625
|
```
|
|
619
626
|
|
|
620
|
-
- [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch`
|
|
627
|
+
- [ ] Mechanical checks passed (`steps gate` exit 0: `debug-close-workflow` row, with `testsLiveSkipped` if no live test, `ciDispatch` on every feature-branch close)
|
|
621
628
|
- [ ] PR title `[verbose ci]` stripped (if `PUSH_MODE` = PR)
|
|
622
629
|
|
|
623
630
|
<!-- bkit:tracker true start -->
|
|
@@ -628,7 +635,7 @@ description: "Debug Feature — Autonomous diagnosis and remediation"
|
|
|
628
635
|
|
|
629
636
|
- [ ] No-leak Assertion passed (no `[DEBUG-OBSERVE]` lines survive)
|
|
630
637
|
- [ ] Close committed and pushed (`workflows close` committed telemetry on `feat/{FID}`; `branches push --require-ci` exit 0)
|
|
631
|
-
- [ ]
|
|
638
|
+
- [ ] `TRIGGER_PR` set from the live `prs probe` (`{PR_OPEN}`), not Step-1 `PUSH_MODE`; if a PR was created or adopted: `PR_URL`, `PR_NUMBER` held, step `debug-create-pr` recorded with the PR URL and `ciDispatch`, changes pushed
|
|
632
639
|
- [ ] CI-Dispatch gate ran (`runs dispatch` exit 0, close transport recorded)
|
|
633
640
|
- [ ] Final return displayed (`debug-summary.md` content verbatim)
|
|
634
641
|
|
|
@@ -8,26 +8,6 @@
|
|
|
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
10
|
|
|
11
|
-
# BKIT_NPM_TOKEN — npm granular access token with read + write access to the
|
|
12
|
-
# @cbartens scope. The Release workflow publishes @cbartens/bkit to npmjs.org
|
|
13
|
-
# with it (same name as the repo secret, Actions → Secrets), and local
|
|
14
|
-
# maintenance uses it too (`npm whoami`, manual publishes). npm is restricting
|
|
15
|
-
# tokens that bypass 2FA (account changes Aug 2026, direct publishing Jan 2027)
|
|
16
|
-
# — create a granular token and keep 2FA enrolled.
|
|
17
|
-
# Generate at: https://www.npmjs.com/settings/cbartens/tokens
|
|
18
|
-
BKIT_NPM_TOKEN=
|
|
19
|
-
|
|
20
|
-
# BKIT_GH_TOKEN_INSTALL — GitHub classic PAT with `read:packages` scope. Used by pnpm
|
|
21
|
-
# to authenticate to the GitHub Packages npm registry (npm.pkg.github.com) for
|
|
22
|
-
# @cbartens/* packages. Fine-grained PATs are rejected by GitHub Packages
|
|
23
|
-
# (HTTP 403) — must be classic.
|
|
24
|
-
# Generate at: https://github.com/settings/tokens (Tokens (classic) → Generate)
|
|
25
|
-
# The project .npmrc carries ONLY the @cbartens registry mapping; the auth token
|
|
26
|
-
# is written into pnpm's user-level config via `pnpm config set` (CI step, local
|
|
27
|
-
# once, Vercel installCommand) — version-proof across pnpm 10.x/11.x. pnpm >=10.34.3
|
|
28
|
-
# 401s on a project-.npmrc ${BKIT_GH_TOKEN_INSTALL} env-substitution. See KN-CORE-7.
|
|
29
|
-
BKIT_GH_TOKEN_INSTALL=
|
|
30
|
-
|
|
31
11
|
# Optional examples — not required bkit tooling. Listed so direnv has a name to
|
|
32
12
|
# load if you use that surface; leave blank otherwise.
|
|
33
13
|
|
|
@@ -51,10 +31,8 @@ BKIT_GH_TOKEN_INSTALL=
|
|
|
51
31
|
# permission "Email addresses: Read" so commits use your verified email. ORG-owned tokens
|
|
52
32
|
# have NO Email-addresses permission — instead set the repo variable RENOVATE_GIT_AUTHOR
|
|
53
33
|
# (Settings -> Secrets and variables -> Actions -> Variables), e.g. `Renovate Bot <renovate@your-domain>`.
|
|
54
|
-
# This is a WRITE token —
|
|
55
|
-
#
|
|
56
|
-
# GitHub Packages (fine-grained PATs get 403 there) — registry/lockfile auth stays on
|
|
57
|
-
# the classic BKIT_GH_TOKEN_INSTALL above (that is why Renovate's hostRules use _INSTALL).
|
|
34
|
+
# This is a WRITE token — do NOT put it on read-only surfaces (Vercel env / project
|
|
35
|
+
# .npmrc).
|
|
58
36
|
# Generate at: https://github.com/settings/personal-access-tokens
|
|
59
37
|
BKIT_GH_TOKEN=
|
|
60
38
|
|
|
@@ -267,7 +267,7 @@ Undocumented, and invisible to the toolchain, because the file stays valid YAML,
|
|
|
267
267
|
|
|
268
268
|
**Docs-only-diff precondition:** the `dev`-trigger path routes every post-merge CI failure to `/bkit-debug`. This is only correct for docs-only diffs if the consumer's `bkit-ci.yml` deploy-await step treats a host-cancelled build as skip, not red (skip e2e, stay green; e.g. Vercel `CANCELED`), but if a consumer reds on a host-cancelled build, every docs-only squash-merge to `dev` false-dispatches `/bkit-debug` and burns loop-cap budget. Verify this per consumer before relying on the `dev` trigger.
|
|
269
269
|
|
|
270
|
-
**Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see
|
|
270
|
+
**Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) is only exercisable on consumer repos with `bkit-cloud.yml` installed and its dispatch secrets wired (see the cloud-agent auth surfaces in `docs/security.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on, so the feature degrades to a silent no-op, not a failure.
|
|
271
271
|
|
|
272
272
|
## Ship gate + bookkeeping
|
|
273
273
|
|
|
@@ -400,12 +400,7 @@ Platform auth is a repo secret `BKIT_GH_TOKEN`, never `GITHUB_TOKEN` (those PRs
|
|
|
400
400
|
| Dependabot alerts | Read |
|
|
401
401
|
| Metadata | Read-only |
|
|
402
402
|
|
|
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.
|
|
404
|
-
|
|
405
|
-
**Private package.** `@cbartens/bkit` is on `npm.pkg.github.com`. Lockfile regen resolves it for every bump. Without a read token, regen 401s and CI fails `pnpm install --frozen-lockfile`.
|
|
406
|
-
|
|
407
|
-
- Mend: add `BKIT_GH_TOKEN_INSTALL` as a Mend repository secret and tick "used during the scan as an environment variable". Uncomment the `hostRules` `token` line in `renovate.json5`.
|
|
408
|
-
- Self-hosted: leave that line commented. The example workflow sets `RENOVATE_HOST_RULES` from the Actions secret. An uncommented Mend-style line adds an empty-token rule and 401s.
|
|
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>`).
|
|
409
404
|
|
|
410
405
|
**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.
|
|
411
406
|
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
|
|
18
18
|
## Supply-Chain (GitHub Actions)
|
|
19
19
|
|
|
20
|
-
Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot,
|
|
20
|
+
Action SHA-pinning and the dependency-update pipeline (Renovate / Dependabot, CVE handling) are CI/CD pipeline rules → canonical home `deployments.md` § Dependency updaters; this section keeps only the security invariant.
|
|
21
21
|
|
|
22
22
|
**Token isolation:** Renovate PRs use a restricted `GITHUB_TOKEN` with no access to the cloud lane's model-auth secrets (`secrets.ANTHROPIC_API_KEY` / `secrets.OPENCODE_PROVIDER_KEY`) — `bkit-cloud.yml` will not dispatch on them by design. A compromised dependency PR cannot reach agent API credentials.
|
|
23
23
|
|