@cbartens/bkit 5.1.0 → 5.2.0
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 +11 -7
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
- package/.bkit/core/.agents/rules.md +8 -4
- package/.bkit/core/.agents/shortcuts.md +1 -1
- package/.bkit/core/.bkit/LICENSE.md +18 -140
- package/.bkit/core/.bkit/README.md +10 -6
- package/.bkit/core/.bkit/cloud.md +12 -15
- package/.bkit/core/.bkit/comparison.md +66 -14
- package/.bkit/core/.bkit/install.md +31 -8
- package/.bkit/core/.bkit/jsonl.md +0 -1
- package/.bkit/core/.bkit/prompts.md +14 -13
- package/.bkit/core/.bkit/providers.md +90 -26
- package/.bkit/core/.bkit/templates.md +38 -11
- package/.bkit/core/.bkit/workflows.md +63 -41
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
- package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
- package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
- package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
- package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
- package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
- package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
- package/.bkit/core/docs/templates/bkit-plan.md +6 -3
- package/.bkit/core/engine/checks/after/auth.ts +32 -0
- package/.bkit/core/engine/checks/after/github.ts +4 -4
- package/.bkit/core/engine/checks/after/index.ts +36 -50
- package/.bkit/core/engine/checks/after/managed.ts +40 -0
- package/.bkit/core/engine/checks/before/index.ts +5 -4
- package/.bkit/core/engine/checks/before/mcp.ts +60 -54
- package/.bkit/core/engine/checks/status-holes.ts +1 -1
- package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
- package/.bkit/core/engine/checks/tips/detect.ts +144 -0
- package/.bkit/core/engine/checks/tips/index.ts +174 -0
- package/.bkit/core/engine/cli.ts +57 -9
- package/.bkit/core/engine/commands/install/doctor.ts +5 -1
- package/.bkit/core/engine/commands/install/install.ts +39 -9
- package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
- package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
- package/.bkit/core/engine/commands/launch.ts +33 -11
- package/.bkit/core/engine/commands/tips.ts +16 -0
- package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
- package/.bkit/core/engine/commands/workflow/runtime.ts +12 -0
- package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
- package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
- package/.bkit/core/engine/install/cloud-env.ts +7 -21
- package/.bkit/core/engine/install/hosts.ts +21 -0
- package/.bkit/core/engine/install/managed-block.ts +36 -0
- package/.bkit/core/engine/install/manifest.ts +46 -4
- package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
- package/.bkit/core/engine/install/modules/claude.ts +6 -6
- package/.bkit/core/engine/install/modules/cloud.ts +2 -2
- package/.bkit/core/engine/install/modules/codex.ts +5 -5
- package/.bkit/core/engine/install/modules/core.ts +23 -9
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +4 -4
- package/.bkit/core/engine/install/payload-links.ts +6 -10
- package/.bkit/core/engine/install/placeholders.ts +1 -1
- package/.bkit/core/engine/install/version-file.ts +17 -9
- package/.bkit/core/engine/install/write.ts +68 -1
- package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
- package/.bkit/core/engine/shared/package-roots.ts +8 -10
- package/.bkit/core/hooks/antigravity-hook.js +67 -0
- package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
- package/.bkit/core/hooks/gateguard-engine.js +16 -6
- package/.bkit/core/hooks/guardrails-read.js +23 -0
- package/.bkit/core/hooks/readguard-engine.js +259 -0
- package/.bkit/core/hooks/readguard-payload.js +67 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
- package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
- package/.bkit/core/prompts/bkit-build-summary.md +1 -0
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
- package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
- package/.bkit/core/prompts/bkit-design-generate.md +9 -4
- package/.bkit/core/prompts/bkit-design-organise.md +1 -0
- package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
- package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
- package/.bkit/core/prompts/bkit-design-spike.md +1 -0
- package/.bkit/core/prompts/bkit-design-summary.md +1 -0
- package/.bkit/core/prompts/bkit-design-update.md +1 -0
- package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
- package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
- package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
- package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
- package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
- package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
- package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
- package/.bkit/core/prompts/bkit-plan-update.md +2 -1
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
- package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
- package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
- package/.bkit/core/workflows/bkit-build.md +33 -21
- package/.bkit/core/workflows/bkit-debug.md +29 -22
- package/.bkit/core/workflows/bkit-design.md +81 -38
- package/.bkit/core/workflows/bkit-plan.md +8 -2
- package/.bkit/core/workflows/bkit-ship.md +8 -2
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
- package/.bkit/shared/.claude/settings.json +19 -0
- package/.bkit/shared/.codex/hooks.json +21 -0
- package/.bkit/shared/.cursor/hooks.json +6 -1
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/docs/deployments.md +1 -1
- package/.bkit/shared/docs/testing.md +12 -1
- package/.bkit/templates/.github/dependabot.yml +6 -0
- package/.bkit/templates/.github/renovate.json5 +3 -3
- package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +5 -5
- package/.bkit/templates/.prettierignore +1 -1
- package/.bkit/templates/context/bkit-expo.md +22 -13
- package/.bkit/templates/context/bkit-github.md +20 -6
- package/.bkit/templates/context/bkit-inngest.md +10 -4
- package/.bkit/templates/context/bkit-maestro.md +5 -5
- package/.bkit/templates/context/bkit-playwright.md +3 -3
- package/.bkit/templates/context/bkit-sentry.md +6 -5
- package/.bkit/templates/context/bkit-stripe.md +31 -8
- package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
- package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
- package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
- package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
- package/.bkit/templates/slop-scan.config.json +7 -2
- package/CHANGELOG.md +42 -0
- package/LICENSE.md +21 -161
- package/README.md +58 -28
- package/dist/checks/after/auth.js +28 -0
- package/dist/checks/after/github.js +4 -4
- package/dist/checks/after/index.js +29 -45
- package/dist/checks/after/managed.js +40 -1
- package/dist/checks/before/index.js +5 -4
- package/dist/checks/before/mcp.js +53 -53
- package/dist/checks/status-holes.js +1 -1
- package/dist/checks/tips/catalogue.js +297 -0
- package/dist/checks/tips/detect.js +130 -0
- package/dist/checks/tips/index.js +146 -0
- package/dist/cli.js +47 -9
- package/dist/commands/install/doctor.js +5 -1
- package/dist/commands/install/install.js +27 -7
- package/dist/commands/install/uninstall.js +31 -16
- package/dist/commands/install/upgrade.js +15 -32
- package/dist/commands/launch.js +27 -11
- package/dist/commands/tips.js +10 -0
- package/dist/commands/workflow/runs.js +52 -16
- package/dist/commands/workflow/runtime.js +8 -0
- package/dist/commands/workflow/steps.js +1 -0
- package/dist/commands/workflow/tests.js +541 -4
- package/dist/commands/workflow/workstreams.js +4 -4
- package/dist/install/cloud-env.js +3 -14
- package/dist/install/hosts.js +22 -0
- package/dist/install/managed-block.js +36 -0
- package/dist/install/manifest.js +45 -4
- package/dist/install/modules/antigravity.js +8 -7
- package/dist/install/modules/claude.js +6 -6
- package/dist/install/modules/cloud.js +2 -2
- package/dist/install/modules/codex.js +5 -5
- package/dist/install/modules/core.js +14 -5
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +4 -4
- package/dist/install/payload-links.js +5 -5
- package/dist/install/placeholders.js +1 -1
- package/dist/install/version-file.js +12 -3
- package/dist/install/write.js +61 -2
- package/dist/shared/package-roots.js +8 -11
- package/package.json +4 -6
- package/.bkit/core/LICENSE.md +0 -149
- package/.bkit/shared/LICENSE.md +0 -22
- package/.bkit/templates/LICENSE.md +0 -22
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// bkit-readguard.cjs — bkit ReadGuard advisory hook (Claude Code).
|
|
3
|
+
//
|
|
4
|
+
// Fires before Read and Bash. When an agent reads a line range of a file it already
|
|
5
|
+
// read in this conversation, and the file has not changed since (same mtime and size),
|
|
6
|
+
// it injects a note so the agent uses the earlier output instead of paying for the
|
|
7
|
+
// same lines again. Shell reads are recognised in their plain forms only: `cat FILE`,
|
|
8
|
+
// `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count. Pipes, globs, lists and
|
|
9
|
+
// substitutions are not tracked. On PreCompact it forgets the session's reads: the
|
|
10
|
+
// summary drops the earlier output, so re-reading is right again.
|
|
11
|
+
//
|
|
12
|
+
// CONTRACT — do not regress:
|
|
13
|
+
// - ADVISORY ONLY: emits `additionalContext`, never blocks.
|
|
14
|
+
// - FAIL OPEN: a single top-level catch swallows every error (exit 0, nothing emitted).
|
|
15
|
+
// - PER AGENT: the log is keyed by (session_id, agent_id). A subagent shares its
|
|
16
|
+
// parent's session_id and has its own agent_id, so it never inherits the parent's
|
|
17
|
+
// reads.
|
|
18
|
+
// - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
|
|
19
|
+
//
|
|
20
|
+
// MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
|
|
21
|
+
//
|
|
22
|
+
// Host note: one engine, five hosts. bkit generates this hook at install from bkit's
|
|
23
|
+
// `core/hooks/readguard-engine.js` and `readguard-payload.js`. See .bkit/providers.md
|
|
24
|
+
// § ReadGuard.
|
|
25
|
+
//
|
|
26
|
+
// OWNERSHIP: everything between the markers below is bkit-managed and is
|
|
27
|
+
// overwritten on every `bkit install` / `bkit upgrade`. It is a pure advisory
|
|
28
|
+
// engine only — no stdin read, no stdout write, no top-level invocation. Add your
|
|
29
|
+
// own logic in the driver that follows the managed block: call
|
|
30
|
+
// `bkitReadguard(payload)`, fold in your own checks, and call `emit()` once.
|
|
31
|
+
|
|
32
|
+
"use strict";
|
|
33
|
+
|
|
34
|
+
// bkit:start
|
|
35
|
+
|
|
36
|
+
// {{BKIT_MANAGED_MARKER}}
|
|
37
|
+
|
|
38
|
+
const fs = require("node:fs");
|
|
39
|
+
const os = require("node:os");
|
|
40
|
+
const path = require("node:path");
|
|
41
|
+
|
|
42
|
+
// {{BKIT_PART readguard-engine.js}}
|
|
43
|
+
|
|
44
|
+
// {{BKIT_PART readguard-payload.js}}
|
|
45
|
+
|
|
46
|
+
// bkit:end
|
|
47
|
+
|
|
48
|
+
function emit(payload) {
|
|
49
|
+
process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
try {
|
|
53
|
+
const raw = fs.readFileSync(0, "utf-8");
|
|
54
|
+
if (raw.trim()) {
|
|
55
|
+
const context = bkitReadguard(JSON.parse(raw));
|
|
56
|
+
if (context) emit({ hookEventName: "PreToolUse", additionalContext: context });
|
|
57
|
+
}
|
|
58
|
+
} catch {
|
|
59
|
+
process.exitCode = 0; // fail open — never block, never error out
|
|
60
|
+
}
|
|
@@ -21,7 +21,8 @@
|
|
|
21
21
|
// - ADVISORY BY DEFAULT: emits `additionalContext` only, never blocks. BKIT_GATEGUARD=deny
|
|
22
22
|
// flips it to a deny ramp; that is a config change, NOT a code change.
|
|
23
23
|
// - FAIL OPEN: one top-level catch swallows every error and exits 0.
|
|
24
|
-
// - SUBAGENTS INCLUDED: a subagent edit is an edit
|
|
24
|
+
// - SUBAGENTS INCLUDED: a subagent edit is an edit. Codex reports the parent's
|
|
25
|
+
// session_id inside a subagent and no agent id, so dedup cannot separate them.
|
|
25
26
|
// - DEDUP: warns once per (session, file), state in the OS temp dir, GC'd after 24h.
|
|
26
27
|
//
|
|
27
28
|
// MODES (BKIT_GATEGUARD): unset → advisory [DEFAULT] | "off" → no-op | "deny" → block first
|
|
@@ -49,13 +50,14 @@ const EDIT_TOOLS = new Set(["apply_patch", "Edit", "Write"]);
|
|
|
49
50
|
// Codex does NOT send a file path: `apply_patch` puts a V4A patch envelope in
|
|
50
51
|
// `tool_input.command`. Pull the touched paths out of it. Grammar (codex-rs/apply-patch):
|
|
51
52
|
// *** Add File: <path> | *** Update File: <path> | *** Delete File: <path>
|
|
53
|
+
// (an Update may be followed by *** Move to: <path>, a target too)
|
|
52
54
|
// Paths are always repo-relative, so they are resolved against the payload cwd.
|
|
53
55
|
// Returns [{ file, isNew }] in patch order; [] when nothing parses.
|
|
54
56
|
function parseApplyPatchTargets(command, cwd) {
|
|
55
57
|
if (typeof command !== "string") return [];
|
|
56
58
|
const out = [];
|
|
57
59
|
for (const line of command.split("\n")) {
|
|
58
|
-
const m = /^\*\*\* (Add|Update|Delete) File: (.+?)\s*$/.exec(line);
|
|
60
|
+
const m = /^\*\*\* (?:(Add|Update|Delete) File|Move to): (.+?)\s*$/.exec(line);
|
|
59
61
|
if (!m) continue;
|
|
60
62
|
const rel = m[2];
|
|
61
63
|
out.push({ file: cwd ? path.resolve(cwd, rel) : rel, isNew: m[1] === "Add" });
|
|
@@ -67,16 +69,16 @@ function parseApplyPatchTargets(command, cwd) {
|
|
|
67
69
|
|
|
68
70
|
// Pure: takes the already-parsed hook payload, returns the advisory to emit or
|
|
69
71
|
// null. Never touches process.stdin / process.stdout — the driver below owns both.
|
|
70
|
-
// Subagents are NOT exempt: dedup is per (session, file)
|
|
71
|
-
//
|
|
72
|
-
//
|
|
72
|
+
// Subagents are NOT exempt: dedup is per (session, agent, file). Codex tool payloads
|
|
73
|
+
// carry the parent's session_id inside a subagent and no agent id, so a Codex subagent
|
|
74
|
+
// is not told apart from its parent.
|
|
73
75
|
function bkitGateguard(payload) {
|
|
74
76
|
if (process.env.BKIT_GATEGUARD === "off") return null;
|
|
75
77
|
if (!EDIT_TOOLS.has(payload.tool_name)) return null;
|
|
76
78
|
|
|
77
79
|
const input = payload.tool_input || {};
|
|
78
80
|
const cwd = typeof payload.cwd === "string" ? payload.cwd : "";
|
|
79
|
-
const sessionId =
|
|
81
|
+
const sessionId = dedupKey(payload.session_id, payload.agent_id);
|
|
80
82
|
// One patch can touch several files. Advises on the first not-yet-warned target, so a
|
|
81
83
|
// new file after an already-warned one still gets its advisory.
|
|
82
84
|
const target = parseApplyPatchTargets(input.command, cwd).find(
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// bkit-readguard.cjs — bkit ReadGuard advisory hook (Codex CLI).
|
|
3
|
+
//
|
|
4
|
+
// Twin of `.claude/hooks/bkit-readguard.cjs`, same stdin envelope and stdout shape.
|
|
5
|
+
// Codex has no file-read tool, so every read arrives as a shell command (`Bash`, argv
|
|
6
|
+
// `["bash", "-lc", "<cmd>"]` unwrapped). When an agent re-reads a line range of a file
|
|
7
|
+
// it already read in this conversation, and the file has not changed since, it injects
|
|
8
|
+
// a note so the agent uses the earlier output. Plain forms only: `cat FILE`,
|
|
9
|
+
// `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count. On PreCompact it forgets the
|
|
10
|
+
// session's reads.
|
|
11
|
+
//
|
|
12
|
+
// REGISTRATION: `.codex/hooks.json`, PreToolUse matcher `Bash` plus PreCompact. Codex
|
|
13
|
+
// loads project-local hooks only once the project `.codex/` layer is TRUSTED.
|
|
14
|
+
// See .bkit/providers.md § ReadGuard.
|
|
15
|
+
//
|
|
16
|
+
// CONTRACT — do not regress:
|
|
17
|
+
// - ADVISORY ONLY: emits `additionalContext`, never blocks.
|
|
18
|
+
// - FAIL OPEN: one top-level catch swallows every error and exits 0.
|
|
19
|
+
// - PER AGENT: keyed by (session_id, agent_id when present). Codex tool payloads
|
|
20
|
+
// carry the parent's session_id inside subagents and no agent id, so a subagent can
|
|
21
|
+
// see the parent's reads; the note tells the agent to re-read when the earlier
|
|
22
|
+
// output is not in its context.
|
|
23
|
+
// - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
|
|
24
|
+
//
|
|
25
|
+
// MODES (BKIT_READGUARD): unset → advisory [DEFAULT] | "off" → no-op.
|
|
26
|
+
//
|
|
27
|
+
// OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
|
|
28
|
+
// `bkit install` / `bkit upgrade`. Add your own logic in the driver below the block.
|
|
29
|
+
|
|
30
|
+
"use strict";
|
|
31
|
+
|
|
32
|
+
// bkit:start
|
|
33
|
+
|
|
34
|
+
// {{BKIT_MANAGED_MARKER}}
|
|
35
|
+
|
|
36
|
+
const fs = require("node:fs");
|
|
37
|
+
const os = require("node:os");
|
|
38
|
+
const path = require("node:path");
|
|
39
|
+
|
|
40
|
+
// {{BKIT_PART readguard-engine.js}}
|
|
41
|
+
|
|
42
|
+
// {{BKIT_PART readguard-payload.js}}
|
|
43
|
+
|
|
44
|
+
// bkit:end
|
|
45
|
+
|
|
46
|
+
function emit(payload) {
|
|
47
|
+
process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
try {
|
|
51
|
+
const raw = fs.readFileSync(0, "utf-8");
|
|
52
|
+
if (raw.trim()) {
|
|
53
|
+
const context = bkitReadguard(JSON.parse(raw));
|
|
54
|
+
if (context) emit({ hookEventName: "PreToolUse", additionalContext: context });
|
|
55
|
+
}
|
|
56
|
+
} catch {
|
|
57
|
+
process.exitCode = 0; // fail open — never block, never error out
|
|
58
|
+
}
|
|
@@ -11,8 +11,8 @@
|
|
|
11
11
|
// Fail-open: a single top-level catch allows on unexpected errors (same shape as gateguard).
|
|
12
12
|
//
|
|
13
13
|
// bkit generates the managed block at install: the shell detection and the deny / ask
|
|
14
|
-
// tiers are shared with the Claude and Codex hooks
|
|
15
|
-
//
|
|
14
|
+
// tiers are shared with the Claude and Codex hooks, the read tiers with the Antigravity
|
|
15
|
+
// hook (bkit's `core/hooks/`); the output shape is Cursor's own.
|
|
16
16
|
//
|
|
17
17
|
// OWNERSHIP: everything between the markers below is bkit-managed and is
|
|
18
18
|
// overwritten on every `bkit install` / `bkit upgrade`. It is a pure decision
|
|
@@ -33,6 +33,8 @@ const path = require("node:path");
|
|
|
33
33
|
|
|
34
34
|
// {{BKIT_PART guardrails-tiers.js}}
|
|
35
35
|
|
|
36
|
+
// {{BKIT_PART guardrails-read.js}}
|
|
37
|
+
|
|
36
38
|
function allow() {
|
|
37
39
|
return { permission: "allow" };
|
|
38
40
|
}
|
|
@@ -80,27 +82,18 @@ function decideShell(cmd) {
|
|
|
80
82
|
|
|
81
83
|
/** @param {string} filePath */
|
|
82
84
|
function decideRead(filePath) {
|
|
83
|
-
const
|
|
84
|
-
if (!
|
|
85
|
-
|
|
86
|
-
// Deny private-key material
|
|
87
|
-
if (/\.pem$/i.test(p) || /\.p12$/i.test(p) || /(^|\/)id_rsa$/i.test(p)) {
|
|
85
|
+
const v = classifyRead(filePath);
|
|
86
|
+
if (!v) return allow();
|
|
87
|
+
if (v.tier === "deny") {
|
|
88
88
|
return deny(
|
|
89
89
|
"Blocked: reading private-key material is denied by bkit Cursor guardrails.",
|
|
90
|
-
`Do not read ${
|
|
90
|
+
`Do not read ${v.path}. Ask the user to supply needed material out-of-band.`,
|
|
91
91
|
);
|
|
92
92
|
}
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
return ask(
|
|
98
|
-
"bkit Cursor guardrails: confirm reading an env/secrets file.",
|
|
99
|
-
`Reading ${p} may expose secrets. Prefer direnv / documented non-secret examples.`,
|
|
100
|
-
);
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
return allow();
|
|
93
|
+
return ask(
|
|
94
|
+
"bkit Cursor guardrails: confirm reading an env/secrets file.",
|
|
95
|
+
`Reading ${v.path} may expose secrets. Prefer direnv / documented non-secret examples.`,
|
|
96
|
+
);
|
|
104
97
|
}
|
|
105
98
|
|
|
106
99
|
/**
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// bkit-readguard.cjs — bkit ReadGuard advisory hook for Cursor.
|
|
3
|
+
//
|
|
4
|
+
// Fires on preToolUse for `Read` and `Shell`. When an agent re-reads a line range of a
|
|
5
|
+
// file it already read in this conversation, and the file has not changed since (same
|
|
6
|
+
// mtime and size), it adds a note so the agent uses the earlier output instead. Shell
|
|
7
|
+
// reads are recognised in their plain forms only: `cat FILE`, `sed -n 'A,Bp' FILE`,
|
|
8
|
+
// `head` / `tail` with a line count. On preCompact it forgets the conversation's reads.
|
|
9
|
+
//
|
|
10
|
+
// CONTRACT — do not regress:
|
|
11
|
+
// - ADVISORY ONLY: returns `permission: "allow"` with `additional_context` (the same
|
|
12
|
+
// channel GateGuard uses on Cursor), never denies.
|
|
13
|
+
// - FAIL OPEN: top-level try/catch emits a bare allow on any error.
|
|
14
|
+
// - PER CONVERSATION: keyed by `conversation_id`; Cursor's tool payload carries no
|
|
15
|
+
// subagent marker. The note tells the agent to re-read when the earlier output is
|
|
16
|
+
// not in its context.
|
|
17
|
+
// - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
|
|
18
|
+
//
|
|
19
|
+
// MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
|
|
20
|
+
//
|
|
21
|
+
// Wired from `.cursor/hooks.json` → preToolUse (matcher "Read|Shell") and preCompact,
|
|
22
|
+
// without failClosed. bkit generates the managed block from the same shared parts as
|
|
23
|
+
// `.claude/hooks/bkit-readguard.cjs`, so the two are byte-identical between the markers.
|
|
24
|
+
// See .bkit/providers.md § ReadGuard.
|
|
25
|
+
//
|
|
26
|
+
// OWNERSHIP: everything between the markers below is bkit-managed and is
|
|
27
|
+
// overwritten on every `bkit install` / `bkit upgrade`. Add your own logic in the
|
|
28
|
+
// driver that follows the managed block, and emit EXACTLY ONE JSON document.
|
|
29
|
+
|
|
30
|
+
"use strict";
|
|
31
|
+
|
|
32
|
+
// bkit:start
|
|
33
|
+
|
|
34
|
+
// {{BKIT_MANAGED_MARKER}}
|
|
35
|
+
|
|
36
|
+
const fs = require("node:fs");
|
|
37
|
+
const os = require("node:os");
|
|
38
|
+
const path = require("node:path");
|
|
39
|
+
|
|
40
|
+
// {{BKIT_PART readguard-engine.js}}
|
|
41
|
+
|
|
42
|
+
// {{BKIT_PART readguard-payload.js}}
|
|
43
|
+
|
|
44
|
+
// bkit:end
|
|
45
|
+
|
|
46
|
+
function emit(decision) {
|
|
47
|
+
process.stdout.write(JSON.stringify(decision));
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
try {
|
|
51
|
+
const raw = fs.readFileSync(0, "utf-8");
|
|
52
|
+
const payload = raw.trim() ? JSON.parse(raw) : {};
|
|
53
|
+
const context = bkitReadguard(payload);
|
|
54
|
+
if (payload.hook_event_name === "preCompact") emit({});
|
|
55
|
+
else emit(context ? { permission: "allow", additional_context: context } : { permission: "allow" });
|
|
56
|
+
} catch {
|
|
57
|
+
// Fail open — any error emits a bare allow.
|
|
58
|
+
emit({ permission: "allow" });
|
|
59
|
+
}
|
|
@@ -30,8 +30,10 @@
|
|
|
30
30
|
//
|
|
31
31
|
// BKIT_ALLOW_CONFIG_EDIT=1 → suppress the gate-config advisory (sanctioned edit).
|
|
32
32
|
//
|
|
33
|
-
// opencode tool names: the edit surface is `write`, `edit` and `patch
|
|
34
|
-
//
|
|
33
|
+
// opencode tool names: the edit surface is `write`, `edit` and `patch` (`apply_patch`
|
|
34
|
+
// on 1.x model-specific tool sets). `patch` carries a multi-file patch in `patchText`,
|
|
35
|
+
// so one call can touch several files. The terminal tool (`shell` in v2, `bash` before
|
|
36
|
+
// v2) is NOT guarded.
|
|
35
37
|
//
|
|
36
38
|
// The engine inside the managed block is generated at install from bkit's
|
|
37
39
|
// `core/hooks/gateguard-engine.js`, the same source as the Claude, Cursor and Codex hooks.
|
|
@@ -52,19 +54,21 @@ import * as path from "node:path";
|
|
|
52
54
|
|
|
53
55
|
// opencode edit-like tool names, lowercase in opencode's plugin API.
|
|
54
56
|
// The terminal tool (`shell` in v2, `bash` before v2) is NOT in this list.
|
|
55
|
-
const EDIT_TOOLS = new Set(["write", "edit", "patch"]);
|
|
57
|
+
const EDIT_TOOLS = new Set(["write", "edit", "patch", "apply_patch"]);
|
|
56
58
|
|
|
57
59
|
// {{BKIT_PART gateguard-engine.js}}
|
|
58
60
|
|
|
59
|
-
// Pure: takes the tool name, the already-extracted file path, and the session id
|
|
61
|
+
// Pure: takes the tool name, the already-extracted file path, and the session id
|
|
62
|
+
// (plus an optional new-file override for patch `*** Add File:` targets);
|
|
60
63
|
// returns the advisory to emit or null. Never touches opencode's client, stderr,
|
|
61
64
|
// or the throw path — the driver below owns all three, so it can fold in its own
|
|
62
65
|
// checks without bkit's block needing to change.
|
|
63
|
-
function bkitGateguard(toolName, filePath, sessionId) {
|
|
66
|
+
function bkitGateguard(toolName, filePath, sessionId, isNewOverride) {
|
|
64
67
|
if (!EDIT_TOOLS.has(toolName)) return null;
|
|
65
68
|
// A write to a not-yet-existing path is a NEW file and gets the reuse checklist.
|
|
66
69
|
const isNewFile =
|
|
67
|
-
|
|
70
|
+
isNewOverride ??
|
|
71
|
+
(toolName === "write" && typeof filePath === "string" && !fs.existsSync(filePath));
|
|
68
72
|
return firstTouchAdvice(filePath, sessionId, isNewFile);
|
|
69
73
|
}
|
|
70
74
|
|
|
@@ -92,6 +96,8 @@ function bkitGateguard(toolName, filePath, sessionId) {
|
|
|
92
96
|
// plugin, or hand-port this driver to the function shape.
|
|
93
97
|
// ---------------------------------------------------------------------------
|
|
94
98
|
|
|
99
|
+
const PATCH_TOOLS = new Set(["patch", "apply_patch"]);
|
|
100
|
+
|
|
95
101
|
/** Edit-tool args → the target file path, across 1.x and 2.0 argument keys. */
|
|
96
102
|
function gateGuardFilePath(input) {
|
|
97
103
|
return input && typeof input === "object"
|
|
@@ -99,6 +105,30 @@ function gateGuardFilePath(input) {
|
|
|
99
105
|
: undefined;
|
|
100
106
|
}
|
|
101
107
|
|
|
108
|
+
// `patch` takes one `patchText` argument: a multi-file envelope of
|
|
109
|
+
// *** Add File: <path> | *** Update File: <path> (optional *** Move to: <path>) | *** Delete File: <path>
|
|
110
|
+
// Returns [{ file, isNew }] in patch order; [] for a missing, non-string or unparseable patch.
|
|
111
|
+
function parsePatchTargets(patchText) {
|
|
112
|
+
if (typeof patchText !== "string") return [];
|
|
113
|
+
const out = [];
|
|
114
|
+
for (const line of patchText.split("\n")) {
|
|
115
|
+
const m = /^\*\*\* (Add File|Update File|Delete File|Move to):\s*(.+?)\s*$/.exec(line);
|
|
116
|
+
if (m) out.push({ file: m[2], isNew: m[1] === "Add File" });
|
|
117
|
+
}
|
|
118
|
+
return out;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** Every file one edit-tool call touches: all patch targets, or the single path. */
|
|
122
|
+
function gateGuardTargets(tool, input) {
|
|
123
|
+
if (PATCH_TOOLS.has(tool)) {
|
|
124
|
+
const patchText =
|
|
125
|
+
input && typeof input === "object" ? (input.patchText ?? input.patch_text) : undefined;
|
|
126
|
+
return parsePatchTargets(patchText);
|
|
127
|
+
}
|
|
128
|
+
const file = gateGuardFilePath(input);
|
|
129
|
+
return typeof file === "string" ? [{ file, isNew: undefined }] : [];
|
|
130
|
+
}
|
|
131
|
+
|
|
102
132
|
/** True only for this plugin's deny-mode throw, so fail-open swallows nothing else. */
|
|
103
133
|
function isDenyThrow(err) {
|
|
104
134
|
return (
|
|
@@ -130,24 +160,35 @@ function takeNewFile(callID) {
|
|
|
130
160
|
* DENY MODE (execute.before — the only hook that can block). First touch of a file
|
|
131
161
|
* per session throws the checklist as the reason; the dedup lets the retry through.
|
|
132
162
|
* The before hook sees the file before a write creates it, so existence is accurate.
|
|
163
|
+
* A multi-file patch checks every target (each is marked warned) and throws once with
|
|
164
|
+
* all their checklists, so the retry is not blocked again file by file.
|
|
133
165
|
*/
|
|
134
|
-
function denyFirstTouch(tool,
|
|
166
|
+
function denyFirstTouch(tool, targets, sessionID) {
|
|
135
167
|
if (process.env.BKIT_GATEGUARD !== "deny") return;
|
|
136
|
-
const
|
|
137
|
-
|
|
168
|
+
const contexts = [];
|
|
169
|
+
for (const { file, isNew } of targets) {
|
|
170
|
+
const result = bkitGateguard(tool, file, sessionID, isNew);
|
|
171
|
+
if (result && result.mode === "deny") contexts.push(result.context);
|
|
172
|
+
}
|
|
173
|
+
if (contexts.length > 0) throw new Error(contexts.join("\n\n"));
|
|
138
174
|
}
|
|
139
175
|
|
|
140
176
|
/**
|
|
141
177
|
* ADVISORY MODE (execute.after). Returns the checklist to append to the tool result,
|
|
142
|
-
* or null when off / deny / already warned / no advice for
|
|
143
|
-
* the pre-write snapshot (see NEW_FILE_BY_CALL), not the post-write filesystem
|
|
178
|
+
* or null when off / deny / already warned / no advice for any target. `isNewFile` is
|
|
179
|
+
* the pre-write snapshot (see NEW_FILE_BY_CALL), not the post-write filesystem; a patch
|
|
180
|
+
* target carries its own new-file flag from its `*** Add File:` header.
|
|
144
181
|
*/
|
|
145
|
-
function advisoryFor(tool,
|
|
182
|
+
function advisoryFor(tool, targets, sessionID, isNewFile) {
|
|
146
183
|
const mode = process.env.BKIT_GATEGUARD;
|
|
147
184
|
if (mode === "off" || mode === "deny") return null;
|
|
148
185
|
if (!EDIT_TOOLS.has(tool)) return null;
|
|
149
|
-
const
|
|
150
|
-
|
|
186
|
+
const contexts = [];
|
|
187
|
+
for (const target of targets) {
|
|
188
|
+
const result = firstTouchAdvice(target.file, sessionID, target.isNew ?? isNewFile);
|
|
189
|
+
if (result) contexts.push(result.context);
|
|
190
|
+
}
|
|
191
|
+
return contexts.length > 0 ? contexts.join("\n\n") : null;
|
|
151
192
|
}
|
|
152
193
|
|
|
153
194
|
/** OpenCode 1.x before hook: `(input, output)`, tool args on `output.args`. */
|
|
@@ -155,9 +196,9 @@ async function bkitGateGuardBeforeV1(hookInput, output) {
|
|
|
155
196
|
try {
|
|
156
197
|
const { tool, sessionID, callID } = hookInput ?? {};
|
|
157
198
|
if (!EDIT_TOOLS.has(tool)) return;
|
|
158
|
-
const
|
|
159
|
-
snapshotNewFile(callID, tool,
|
|
160
|
-
denyFirstTouch(tool,
|
|
199
|
+
const targets = gateGuardTargets(tool, output?.args);
|
|
200
|
+
snapshotNewFile(callID, tool, targets[0]?.file);
|
|
201
|
+
denyFirstTouch(tool, targets, sessionID);
|
|
161
202
|
} catch (err) {
|
|
162
203
|
if (isDenyThrow(err)) throw err;
|
|
163
204
|
}
|
|
@@ -170,7 +211,12 @@ async function bkitGateGuardAfterV1(hookInput, output) {
|
|
|
170
211
|
const isNewFile = takeNewFile(callID);
|
|
171
212
|
if (!EDIT_TOOLS.has(tool)) return;
|
|
172
213
|
if (!output || typeof output !== "object") return;
|
|
173
|
-
const context = advisoryFor(
|
|
214
|
+
const context = advisoryFor(
|
|
215
|
+
tool,
|
|
216
|
+
gateGuardTargets(tool, args ?? output.args),
|
|
217
|
+
sessionID,
|
|
218
|
+
isNewFile,
|
|
219
|
+
);
|
|
174
220
|
if (!context) return;
|
|
175
221
|
const existing = typeof output.output === "string" ? output.output : "";
|
|
176
222
|
output.output = existing.length > 0 ? `${existing}\n\n${context}` : context;
|
|
@@ -184,9 +230,9 @@ async function bkitGateGuardBeforeV2(event) {
|
|
|
184
230
|
try {
|
|
185
231
|
const tool = event?.tool;
|
|
186
232
|
if (!EDIT_TOOLS.has(tool)) return;
|
|
187
|
-
const
|
|
188
|
-
snapshotNewFile(event?.id, tool,
|
|
189
|
-
denyFirstTouch(tool,
|
|
233
|
+
const targets = gateGuardTargets(tool, event?.input);
|
|
234
|
+
snapshotNewFile(event?.id, tool, targets[0]?.file);
|
|
235
|
+
denyFirstTouch(tool, targets, event?.sessionID);
|
|
190
236
|
} catch (err) {
|
|
191
237
|
if (isDenyThrow(err)) throw err;
|
|
192
238
|
}
|
|
@@ -199,7 +245,12 @@ async function bkitGateGuardAfterV2(event) {
|
|
|
199
245
|
const isNewFile = takeNewFile(event?.id);
|
|
200
246
|
if (!EDIT_TOOLS.has(tool)) return;
|
|
201
247
|
if (event?.status !== "completed" || !event.result) return;
|
|
202
|
-
const context = advisoryFor(
|
|
248
|
+
const context = advisoryFor(
|
|
249
|
+
tool,
|
|
250
|
+
gateGuardTargets(tool, event?.input),
|
|
251
|
+
event?.sessionID,
|
|
252
|
+
isNewFile,
|
|
253
|
+
);
|
|
203
254
|
if (!context) return;
|
|
204
255
|
const content = Array.isArray(event.result.content) ? event.result.content : [];
|
|
205
256
|
event.result.content = [...content, { type: "text", text: context }];
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// bkit-readguard.js — bkit ReadGuard plugin for opencode.
|
|
2
|
+
//
|
|
3
|
+
// When an agent re-reads a line range of a file it already read in this session, and
|
|
4
|
+
// the file has not changed since (same mtime and size), it appends a note to the tool
|
|
5
|
+
// result so the next read uses the earlier output instead. Covers the `read` tool and
|
|
6
|
+
// plain shell reads (`cat FILE`, `sed -n 'A,Bp' FILE`, `head` / `tail` with a line
|
|
7
|
+
// count) through the terminal tool (`shell` in v2, `bash` before v2).
|
|
8
|
+
//
|
|
9
|
+
// CONTRACT — do not regress:
|
|
10
|
+
// - ADVISORY ONLY: appends the note to the tool RESULT in the after-execute hook.
|
|
11
|
+
// The before-execute hook can only allow or block, so ReadGuard does not use it;
|
|
12
|
+
// the note arrives with the repeated read, not before it.
|
|
13
|
+
// - FAIL OPEN: every hook swallows its own errors.
|
|
14
|
+
// - PER SESSION: keyed by sessionID. A subagent runs in its own session, so it never
|
|
15
|
+
// inherits its parent's reads.
|
|
16
|
+
// - COMPACTION: 1.x forgets a session's reads on `session.compacted`. 2.0 exposes no
|
|
17
|
+
// event subscription to this plugin, so its log is not cleared on a summary; the
|
|
18
|
+
// note tells the agent to re-read when the earlier output is no longer in context.
|
|
19
|
+
// - STATE: OS temp dir, GC'd after 24h. Never writes into the consumer repo.
|
|
20
|
+
//
|
|
21
|
+
// MODES (BKIT_READGUARD env var): unset → advisory [DEFAULT] | "off" → no-op.
|
|
22
|
+
//
|
|
23
|
+
// The engine inside the managed block is generated at install from bkit's
|
|
24
|
+
// `core/hooks/readguard-engine.js`, the same source as the Claude, Cursor, Codex and
|
|
25
|
+
// Antigravity hooks. See .bkit/providers.md § ReadGuard.
|
|
26
|
+
//
|
|
27
|
+
// OWNERSHIP: everything between the markers below is bkit-managed and is
|
|
28
|
+
// overwritten on every `bkit install` / `bkit upgrade`. It is a pure advisory
|
|
29
|
+
// engine only — no client calls, no stderr write, no throw — so it composes
|
|
30
|
+
// with your own checks in the exported plugin that follows the managed block.
|
|
31
|
+
|
|
32
|
+
// bkit:start
|
|
33
|
+
|
|
34
|
+
// {{BKIT_MANAGED_MARKER}}
|
|
35
|
+
|
|
36
|
+
import * as fs from "node:fs";
|
|
37
|
+
import * as os from "node:os";
|
|
38
|
+
import * as path from "node:path";
|
|
39
|
+
|
|
40
|
+
// opencode tool names, lowercase in opencode's plugin API.
|
|
41
|
+
const READ_TOOLS = new Set(["read"]);
|
|
42
|
+
const SHELL_TOOLS = new Set(["shell", "bash"]);
|
|
43
|
+
|
|
44
|
+
// {{BKIT_PART readguard-engine.js}}
|
|
45
|
+
|
|
46
|
+
// Pure: takes the tool name, its arguments and the session id; returns the note to
|
|
47
|
+
// append or null. `read` takes `path` (2.0) or `filePath` (1.x); 1-based `offset` plus
|
|
48
|
+
// `limit`, the whole file when neither is given. The terminal tool takes `command` and
|
|
49
|
+
// an optional `workdir`.
|
|
50
|
+
function bkitReadguard(tool, args, sessionID) {
|
|
51
|
+
const input = args && typeof args === "object" ? args : {};
|
|
52
|
+
const cwd = typeof input.workdir === "string" ? input.workdir : process.cwd();
|
|
53
|
+
let targets = [];
|
|
54
|
+
if (READ_TOOLS.has(tool)) {
|
|
55
|
+
const paged = input.offset !== undefined || input.limit !== undefined;
|
|
56
|
+
targets = toolReadTarget(
|
|
57
|
+
input.path ?? input.filePath,
|
|
58
|
+
cwd,
|
|
59
|
+
input.offset,
|
|
60
|
+
input.limit,
|
|
61
|
+
paged ? undefined : OPEN_END,
|
|
62
|
+
);
|
|
63
|
+
} else if (SHELL_TOOLS.has(tool)) {
|
|
64
|
+
targets = shellReadTargets(typeof input.command === "string" ? input.command : "", cwd);
|
|
65
|
+
}
|
|
66
|
+
return repeatReadAdvice(targets, sessionID, undefined, cwd);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// bkit:end
|
|
70
|
+
|
|
71
|
+
// ---------------------------------------------------------------------------
|
|
72
|
+
// Driver — the one export shape OpenCode 1.x and 2.0 both load (same as
|
|
73
|
+
// `bkit-gateguard.js`): 2.0 calls `setup(ctx)` and registers `execute.after`; 1.18.29+
|
|
74
|
+
// calls `server()` and uses `"tool.execute.after"` plus the `event` hook.
|
|
75
|
+
// ---------------------------------------------------------------------------
|
|
76
|
+
|
|
77
|
+
/** OpenCode 1.x after hook: append the note to `output.output`, the result text. */
|
|
78
|
+
async function bkitReadGuardAfterV1(hookInput, output) {
|
|
79
|
+
try {
|
|
80
|
+
const { tool, sessionID, args } = hookInput ?? {};
|
|
81
|
+
if (!output || typeof output !== "object") return;
|
|
82
|
+
const context = bkitReadguard(tool, args ?? output.args, sessionID);
|
|
83
|
+
if (!context) return;
|
|
84
|
+
const existing = typeof output.output === "string" ? output.output : "";
|
|
85
|
+
output.output = existing.length > 0 ? `${existing}\n\n${context}` : context;
|
|
86
|
+
} catch {
|
|
87
|
+
// fail-open: never let an advisory error reach the host
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** OpenCode 1.x event hook: forget a session's reads once it is compacted. */
|
|
92
|
+
async function bkitReadGuardEventV1({ event } = {}) {
|
|
93
|
+
try {
|
|
94
|
+
if (event?.type === "session.compacted") resetReadLog(event.properties?.sessionID);
|
|
95
|
+
} catch {
|
|
96
|
+
// fail-open: never let an advisory error reach the host
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** OpenCode 2.0 after hook: append the note to `event.result.content`. */
|
|
101
|
+
async function bkitReadGuardAfterV2(event) {
|
|
102
|
+
try {
|
|
103
|
+
if (event?.status !== "completed" || !event.result) return;
|
|
104
|
+
const context = bkitReadguard(event.tool, event.input, event.sessionID);
|
|
105
|
+
if (!context) return;
|
|
106
|
+
const content = Array.isArray(event.result.content) ? event.result.content : [];
|
|
107
|
+
event.result.content = [...content, { type: "text", text: context }];
|
|
108
|
+
} catch {
|
|
109
|
+
// fail-open: never let an advisory error reach the host
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
const bkitReadGuardPlugin = {
|
|
114
|
+
id: "bkit-readguard",
|
|
115
|
+
async setup(ctx) {
|
|
116
|
+
await ctx.tool.hook("execute.after", bkitReadGuardAfterV2);
|
|
117
|
+
},
|
|
118
|
+
async server() {
|
|
119
|
+
return {
|
|
120
|
+
"tool.execute.after": bkitReadGuardAfterV1,
|
|
121
|
+
event: bkitReadGuardEventV1,
|
|
122
|
+
};
|
|
123
|
+
},
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
export default bkitReadGuardPlugin;
|
|
@@ -33,7 +33,7 @@ bkit ships three folders. Path inside a folder = path it lands at in the repo.
|
|
|
33
33
|
<!-- prettier-ignore -->
|
|
34
34
|
| Package folder | Install does | Repo gets |
|
|
35
35
|
| --- | --- | --- |
|
|
36
|
-
| `.bkit/core/` | Writes, keeps current; `engine/`, `workflows/`, `prompts
|
|
36
|
+
| `.bkit/core/` | Writes, keeps current; `engine/`, `workflows/`, `prompts/` never written as-is (workflows + prompts render to host agent and command copies) | Whole files, managed blocks, hooks, reference docs in `.bkit/`, audit and plan templates |
|
|
37
37
|
| `.bkit/shared/` | Writes, keeps current | bkit blocks and keys inside files you also edit (`docs/*.md`, `.gitignore`, settings, tool-server config) |
|
|
38
38
|
| `.bkit/templates/` | Never writes into the repo; raw copy at `.bkit/templates/`, `bkit upgrade` lists changed paths | Nothing until you copy one and own it |
|
|
39
39
|
|
|
@@ -103,7 +103,7 @@ Verify only when applicable.
|
|
|
103
103
|
### Probe Steps
|
|
104
104
|
|
|
105
105
|
- [ ] **Step 1 — Previous Run:** Record `git rev-parse HEAD`. Read newest prior report for this slug under `docs/audits/`. Count findings fixed / still open; age of oldest open. Open after 2 runs → re-raise with age. Carry each `Adoption` verdict forward with its age. **Done when:** closure rate in `Previous Run`, or run marked baseline.
|
|
106
|
-
- [ ] **Step 2 — Inventory:** List every file in the package's `core/`, `shared/`, `templates/`. Landing path = path inside the folder; `core/engine/`, `core/workflows/`, `core/prompts
|
|
106
|
+
- [ ] **Step 2 — Inventory:** List every file in the package's `core/`, `shared/`, `templates/`. Landing path = path inside the folder; `core/engine/`, `core/workflows/`, `core/prompts/` → no landing (workflows + prompts → Step 5 host copies). Join: package file · landing path present · in `canonicalHashes` · repo `.bkit/templates/` copy matches package `templates/`. Kind per file: whole file / managed block / owned keys / template. Findings: `core/` or `shared/` file with landing path absent; `canonicalHashes` entry the package no longer ships; repo `.bkit/templates/` differing from package. Group a folder into one row only when every file shares one verdict. **Done when:** `Inventory` row per shipped file or uniform folder: folder · landing path · kind · present · recorded.
|
|
107
107
|
- [ ] **Step 3 — Version:** `pinnedVersion` vs installed package vs registry latest; pinned ≠ installed = package bumped without `bkit upgrade`. Behind → release count; release-note changes touching this repo; template paths changed since pinned version. **Done when:** `Version` names all three versions and every relevant release-note change.
|
|
108
108
|
- [ ] **Step 4 — Check and Doctor:** `bkit check`: exit code, each drift line → cause. `bkit doctor`: each advisory → adopt / reject (why) / not applicable; previous report's reject carried forward, re-raised only when the advisory text changed. **Done when:** `Check and Doctor` row per drift line and advisory.
|
|
109
109
|
- [ ] **Step 5 — Hosts:** Agent hosts in use (repo config dirs, team use; newest `bkit-audit-agents` `Hosts` as cross-check, not source) vs bkit hosts installed. Per installed host: one agent copy per `core/prompts/` source, one command copy per `core/workflows/` source, every `core/` hook file present, executable, and wired in that host's settings. Findings: host in use with no bkit install (agents there run without bkit gates); missing or extra copy; hook file present but unwired, or wired but absent. Whether hooks fire and agree across hosts → `bkit-audit-agents`. **Done when:** `Hosts` row per host: in use · installed · agent copies · command copies · hooks wired.
|
|
@@ -404,16 +404,19 @@ _No DB changes: "Code-only — `git revert` sufficient."_
|
|
|
404
404
|
> **Tests ship with their task.** Task adding / changing logic → names its own unit tests in `Done when`, matrix row or not; tests it breaks → fixed in same task. never defer task tests to later tasks to avoid splits that leave untested code and drop coverage gates.
|
|
405
405
|
>
|
|
406
406
|
> **Build order and test source.** Order tasks by build dependency (schema → API → UI). Behaviour tests only from `Derived Test Matrix` rows — do not invent. Boundary-crossing tasks (DB / API / model / network / migration) carry paired non-mock `Done when` tests; pure-function tasks exempt from pairing, not from unit tests.
|
|
407
|
+
>
|
|
408
|
+
> **Test first.** Every task MUST include `**Test first:**` after `Done when`. Behaviour change at unit / integration tier → one or more tests, `;`-separated, each `` `{test file}` `` `` `{test name}` `` fails on {assertion} — repo-relative test files, test names as the runner reports them or their last segments, no `;` in assertion text; build sees each fail against stubs before writing the task's code. No behaviour change (docs, config, pure refactor) or E2E / `@live` tier only → `n/a — {reason naming which}`.
|
|
407
409
|
|
|
408
|
-
- [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly].
|
|
409
|
-
- [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes].
|
|
410
|
-
- [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state].
|
|
410
|
+
- [ ] **Task 1:** [e.g., Create DB migration (`npx supabase db diff`)]. **Done when:** [e.g., `supabase/migrations/{timestamp}_add_items_status.sql` exists; `npx supabase db push --local` applies cleanly]. **Test first:** [e.g., n/a — migration; fresh-DB replay tier].
|
|
411
|
+
- [ ] **Task 2:** [e.g., Implement backend API action `action.ts`]. **Done when:** [e.g., `packages/api/src/items/setStatus.ts` exports `setStatus` with Zod-validated input; unit test `packages/api/src/items/setStatus.test.ts` covers each status transition; integration test in `packages/api/items.integration.test.ts` passes]. **Test first:** [e.g., `packages/api/src/items/setStatus.test.ts` `rejects an unknown status` fails on the thrown validation error — stub accepts any status; `packages/api/items.integration.test.ts` `persists the new status` fails on the stored row — stub writes nothing].
|
|
412
|
+
- [ ] **Task 3:** [e.g., Update React component `page.tsx`]. **Done when:** [e.g., `apps/web/app/items/page.tsx` renders status badge; Playwright spec `apps/web/e2e/items.spec.ts` confirms user-visible state]. **Test first:** [e.g., n/a — E2E tier only; runs in CI].
|
|
411
413
|
|
|
412
414
|
### 🔒 Gate 2: Code Implementation Check
|
|
413
415
|
|
|
414
416
|
**CRITICAL AI AGENT INSTRUCTION:** 🛑 CHECKPOINT — `[x]` all boxes below. **do not stop for user permission.** Proceed to `Testing & Documentation`.
|
|
415
417
|
|
|
416
418
|
- [ ] **No bolt-on / no gate-weakening:** every `[NEW]` traces to a `Reuse Inventory` `NEW` row and its search still holds — reusable artifact found mid-build → add a row, fold code into it; every `EXTEND` landed as a modification of the named artifact, not a parallel file. No type-system escapes (e.g. TS `as any` / `as unknown as` / `@ts-ignore`, Python `# type: ignore`), linter disables (e.g. `eslint-disable`, `//nolint`), test skips (e.g. `.skip`, `xfail`), empty `catch` / error-swallowing introduced to make a gate pass.
|
|
419
|
+
- [ ] **Test first:** every task naming `Test first` tests recorded a red per test before its code; tests unchanged since except added tests / formatting.
|
|
417
420
|
- [ ] **Gate 2 - Verified:** Every checkbox above independently verified and checked off against the plan.
|
|
418
421
|
|
|
419
422
|
> [!IMPORTANT]
|