kibi-cursor 2.0.0 → 2.1.0

package/dist/hook-runner.js

@@ -3,12 +3,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { readGuidance, writeGuidance } from "./guidance.js";
+import { preEditGuidance, readGuidance, writeGuidance } from "./guidance.js";
 import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
 import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, recordPlanDelivered, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
 import { extractKbMcpToolCall } from "./kb-mcp-tools.js";
 import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, interfaceAdvisory, stopFollowupMessage, } from "./messages.js";
 import { extractExplicitPathFields, isDirectKbPath, isKbFreshnessRelevantPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
+import { getSourceLinkedRequirementIds } from "./source-linked-requirements.js";
 const editableTools = new Set([
     "Edit",
     "MultiEdit",
@@ -32,9 +33,14 @@ function isEditLikeTool(toolName) {
     return toolName === undefined || editableTools.has(toolName);
 }
 function isKnownEditableTool(toolName) {
+    // rationale: the undefined check narrows the type for Set<string>.has;
+    // at runtime Set.has(undefined) is false, so the result is the same.
+    // Stryker disable next-line ConditionalExpression
     return toolName !== undefined && editableTools.has(toolName);
 }
 function isPlanDeliveryTool(toolName) {
+    // rationale: same type-narrowing as isKnownEditableTool above.
+    // Stryker disable next-line ConditionalExpression
     return toolName !== undefined && planDeliveryTools.has(toolName);
 }
 function isReadLikeTool(toolName) {
@@ -81,7 +87,27 @@ export async function runHook(rawInput, environment = {}) {
                     agent_message: DIRECT_KB_EDIT_WARNING,
                 };
             }
-            return emptyResult();
+            const primaryPath = resolvePrimaryPath(input);
+            if (!primaryPath || !kibiReady || !isKnownEditableTool(input.toolName)) {
+                return emptyResult();
+            }
+            const relativePath = toRepoRelativePath(primaryPath, cwd);
+            const state = loadHookState(stateDir);
+            if (hasGuidedPath(state, "pre-edit", relativePath)) {
+                return emptyResult();
+            }
+            const guidance = preEditGuidance(primaryPath, {
+                cwd,
+                hasKibi: kibiReady,
+                mcpState: state.mcpState,
+                workspaceTrusted,
+                linkedRequirementIds: getSourceLinkedRequirementIds(cwd, primaryPath, stateDir),
+            });
+            if (!guidance) {
+                return emptyResult();
+            }
+            rememberGuidedPath(stateDir, "pre-edit", relativePath);
+            return { permission: "allow", agent_message: guidance };
         }
         case "beforeReadFile": {
             const primaryPath = resolvePrimaryPath(input);
@@ -152,9 +178,13 @@ export async function runHook(rawInput, environment = {}) {
                 return { additional_context: guidance };
             }
             if (isEditLikeTool(input.toolName)) {
+                // rationale: the runner only ever passes "read" or "write"; an empty
+                // kind selects the same write bucket.
+                // Stryker disable StringLiteral
                 if (hasGuidedPath(state, "write", relativePath)) {
                     return emptyResult();
                 }
+                // Stryker restore
                 const guidance = writeGuidance(primaryPath, {
                     cwd,
                     hasKibi: kibiReady,
@@ -164,17 +194,17 @@ export async function runHook(rawInput, environment = {}) {
                 if (!guidance) {
                     return emptyResult();
                 }
+                // rationale: same bucket equivalence as the lookup above.
+                // Stryker disable StringLiteral
                 rememberGuidedPath(stateDir, "write", relativePath);
+                // Stryker restore
                 return { additional_context: guidance };
             }
             return emptyResult();
         }
         case "stop": {
             const state = loadHookState(stateDir);
-            const shouldClearSession = state.dirtyPaths.length > 0 ||
-                state.kbMutationTools.length > 0 ||
-                state.kbCheckRun ||
-                state.planDelivered;
+            const shouldClearSession = state.dirtyPaths.length > 0 || state.kbCheckRun || state.planDelivered;
             if (input.status === "aborted" || input.status === "error") {
                 if (shouldClearSession) {
                     clearSessionHookState(stateDir);

package/dist/hook-state-storage.js

@@ -18,14 +18,23 @@ function lockPath(pluginData) {
     return path.join(pluginData, lockFileName);
 }
 function isRecord(value) {
+    // rationale: every coerced field tolerates primitives (missing -> empty
+    // lists, flags -> false), so dropping the type/null checks still yields
+    // the same coerced state for every JSON value.
+    // Stryker disable next-line ConditionalExpression, LogicalOperator
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 export function normalizePath(dirtyPath) {
     return dirtyPath.trim().replaceAll("\\", "/");
 }
+// rationale: sleepSync only paces lock retries; the lock outcome and state
+// result are identical without it.
+// Stryker disable next-line BlockStatement
 function sleepSync(milliseconds) {
     const buffer = new SharedArrayBuffer(4);
     const view = new Int32Array(buffer);
+    // rationale: the wait only paces retries; see the function rationale above.
+    // Stryker disable next-line CallExpression
     Atomics.wait(view, 0, 0, milliseconds);
 }
 function uniqueTempPath(pluginData) {
@@ -42,6 +51,7 @@ export function emptyHookState() {
         mcpState: "unknown",
         dirtyPaths: [],
         guidedReadPaths: [],
+        guidedPreEditPaths: [],
         guidedWritePaths: [],
         kbMutationTools: [],
         kbCheckRun: false,
@@ -52,17 +62,34 @@ export function emptyHookState() {
 }
 function acquireLock(pluginData) {
     const targetLockPath = lockPath(pluginData);
+    // rationale: the extra attempt only re-runs the same EEXIST handling one
+    // more time; the eventual lock outcome is unchanged.
+    // Stryker disable next-line EqualityOperator
     for (let attempt = 0; attempt < lockRetryCount; attempt++) {
         try {
             return fs.openSync(targetLockPath, "wx");
         }
         catch (error) {
-            if (error instanceof Error &&
+            // rationale: fail-fast vs re-entering the retry loop both end with the
+            // same undefined result; stale removal and sleepSync only pace it.
+            if (
+            // Stryker disable next-line ConditionalExpression, LogicalOperator
+            error instanceof Error &&
                 "code" in error &&
+                // rationale: same convergence argument as the comment above.
+                // Stryker disable next-line ConditionalExpression
                 error.code === "EEXIST") {
+                // rationale: after removal or a paced retry the lock state converges
+                // on the same acquisition outcome.
+                // Stryker disable next-line ConditionalExpression, BlockStatement
                 if (removeStaleLock(targetLockPath)) {
+                    // rationale: an immediate retry after successful removal has the
+                    // same outcome as a paced retry.
+                    // Stryker disable next-line BlockStatement
                     continue;
                 }
+                // rationale: pacing only; see the acquireLock rationale above.
+                // Stryker disable next-line CallExpression
                 sleepSync(lockRetryDelayMs);
                 continue;
             }
@@ -73,15 +100,28 @@ function acquireLock(pluginData) {
 }
 function removeStaleLock(targetLockPath) {
     let stats;
+    // rationale: removeStaleLock only runs after an EEXIST open, so a failed
+    // stat cannot change the observable lock outcome within a single thread.
+    // Stryker disable BlockStatement, BooleanLiteral
     try {
         stats = fs.statSync(targetLockPath);
     }
     catch {
         return false;
     }
+    // Stryker restore
+    // rationale: the fresh/stale boundary is a pacing decision, not a state
+    // transition; both answers converge on the same eventual update result.
+    // Stryker disable next-line EqualityOperator
     if (Date.now() - stats.mtimeMs < staleLockAgeMs) {
+        // rationale: same convergence argument as the fresh/stale comment above.
+        // Stryker disable next-line BooleanLiteral
         return false;
     }
+    // rationale: after a successful unlink the lock is gone either way, and an
+    // unlink failure leaves it in place; either answer converges on the same
+    // eventual lock outcome.
+    // Stryker disable BlockStatement, BooleanLiteral
     try {
         fs.unlinkSync(targetLockPath);
         return true;
@@ -89,6 +129,7 @@ function removeStaleLock(targetLockPath) {
     catch {
         return false;
     }
+    // Stryker restore
 }
 function releaseLock(pluginData, fileDescriptor) {
     try {
@@ -109,9 +150,13 @@ function releaseLock(pluginData, fileDescriptor) {
     }
 }
 function coerceHookState(value) {
+    // rationale: every coerced field tolerates non-records (missing -> empty
+    // lists, flags -> false), so the guard is behaviorally redundant.
+    // Stryker disable ConditionalExpression, BlockStatement
     if (!isRecord(value)) {
         return emptyHookState();
     }
+    // Stryker restore
     const strings = (candidate, normalize) => Array.isArray(candidate)
         ? candidate
             .filter((entry) => typeof entry === "string")
@@ -120,6 +165,7 @@ function coerceHookState(value) {
         : [];
     const dirtyPaths = strings(value.dirtyPaths, normalizePath);
     const guidedReadPaths = strings(value.guidedReadPaths, normalizePath);
+    const guidedPreEditPaths = strings(value.guidedPreEditPaths, normalizePath);
     const guidedWritePaths = strings(value.guidedWritePaths, normalizePath);
     const kbMutationTools = strings(value.kbMutationTools, (entry) => entry.trim());
     const impactCheckedPaths = strings(value.impactCheckedPaths, normalizePath);
@@ -127,6 +173,7 @@ function coerceHookState(value) {
         mcpState: value.mcpState === "observed" ? "observed" : "unknown",
         dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
         guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
+        guidedPreEditPaths: [...new Set(guidedPreEditPaths)].slice(-maxGuidedPaths),
         guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
         kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
         kbCheckRun: value.kbCheckRun === true,
@@ -145,11 +192,17 @@ export function resolveStateDir(pluginData, conversationId) {
     return path.join(os.tmpdir(), "kibi-cursor-hook-state", conversationId.replaceAll(/[^a-zA-Z0-9._-]/g, "_"));
 }
 export function loadHookState(stateDir) {
+    // rationale: the read below throws for a missing stateDir and the catch
+    // returns the same empty state.
+    // Stryker disable next-line ConditionalExpression, BlockStatement
     if (!stateDir) {
         return emptyHookState();
     }
     try {
-        return coerceHookState(JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
+        return coerceHookState(
+        // rationale: Bun treats the empty encoding as utf8 (verified).
+        // Stryker disable next-line StringLiteral
+        JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
     }
     catch {
         return emptyHookState();

package/dist/hook-state.d.ts

@@ -1,9 +1,11 @@
 import type { McpState } from "./kb-mcp-tools.js";
 export { loadHookState, resolveStateDir, saveHookState, updateHookState, } from "./hook-state-storage.js";
+export type GuidedPathKind = "read" | "pre-edit" | "write";
 export type HookState = {
     mcpState: McpState;
     dirtyPaths: string[];
     guidedReadPaths: string[];
+    guidedPreEditPaths: string[];
     guidedWritePaths: string[];
     kbMutationTools: string[];
     kbCheckRun: boolean;
@@ -12,8 +14,8 @@ export type HookState = {
     planDelivered: boolean;
 };
 export declare function addDirtyPaths(stateDir: string | undefined, dirtyPaths: readonly string[]): HookState;
-export declare function rememberGuidedPath(stateDir: string | undefined, kind: "read" | "write", guidedPath: string): HookState;
-export declare function hasGuidedPath(state: HookState, kind: "read" | "write", guidedPath: string): boolean;
+export declare function rememberGuidedPath(stateDir: string | undefined, kind: GuidedPathKind, guidedPath: string): HookState;
+export declare function hasGuidedPath(state: HookState, kind: GuidedPathKind, guidedPath: string): boolean;
 export declare function recordPlanDelivered(stateDir: string | undefined): HookState;
 export declare function recordKbMcpTool(stateDir: string | undefined, toolName: string, options?: {
     impactCheckRun?: boolean;

package/dist/hook-state.js

@@ -9,15 +9,20 @@ export function addDirtyPaths(stateDir, dirtyPaths) {
 export function rememberGuidedPath(stateDir, kind, guidedPath) {
     return updateHookState(stateDir, (state) => {
         const normalized = normalizePath(guidedPath);
-        if (normalized.length === 0) {
-            return state;
-        }
         if (kind === "read") {
             return {
                 ...state,
                 guidedReadPaths: mergeStringPaths(state.guidedReadPaths, [normalized]),
             };
         }
+        if (kind === "pre-edit") {
+            return {
+                ...state,
+                guidedPreEditPaths: mergeStringPaths(state.guidedPreEditPaths, [
+                    normalized,
+                ]),
+            };
+        }
         return {
             ...state,
             guidedWritePaths: mergeStringPaths(state.guidedWritePaths, [normalized]),
@@ -25,15 +30,23 @@ export function rememberGuidedPath(stateDir, kind, guidedPath) {
     });
 }
 export function hasGuidedPath(state, kind, guidedPath) {
-    const normalized = normalizePath(guidedPath);
-    const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
-    return bucket.includes(normalized);
+    return guidedBucket(state, kind).includes(normalizePath(guidedPath));
+}
+function guidedBucket(state, kind) {
+    if (kind === "read")
+        return state.guidedReadPaths;
+    if (kind === "pre-edit")
+        return state.guidedPreEditPaths;
+    return state.guidedWritePaths;
 }
 export function recordPlanDelivered(stateDir) {
     return updateHookState(stateDir, (state) => state.planDelivered ? state : { ...state, planDelivered: true });
 }
 export function recordKbMcpTool(stateDir, toolName, options = {}) {
     const normalized = toolName.trim();
+    // rationale: non-check names return the loaded state below without writing,
+    // so the blank-name early return is behaviorally redundant.
+    // Stryker disable next-line ConditionalExpression, BlockStatement
     if (normalized.length === 0) {
         return loadHookState(stateDir);
     }
@@ -44,14 +57,21 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
                 ...observedState,
                 kbCheckRun: true,
                 impactCheckRun: state.impactCheckRun || options.impactCheckRun === true,
-                impactCheckedPaths: options.impactCheckRun === true
+                impactCheckedPaths: 
+                // rationale: merging an empty list leaves the paths unchanged.
+                // Stryker disable ConditionalExpression
+                options.impactCheckRun === true
                     ? mergeStringPaths(state.impactCheckedPaths, options.sourceFiles ?? [])
                     : state.impactCheckedPaths,
+                // Stryker restore
             };
         }
         if (normalized === "kb_upsert" || normalized === "kb_delete") {
             return {
                 ...observedState,
+                // rationale: only two mutation tool names exist and the list is
+                // deduped, so the 20-entry bound can never bind.
+                // Stryker disable next-line MethodExpression
                 kbMutationTools: mergeStringPaths(state.kbMutationTools, [
                     normalized,
                 ]).slice(-maxKbMutationTools),
@@ -62,6 +82,9 @@ export function recordKbMcpTool(stateDir, toolName, options = {}) {
 }
 export function clearSessionHookState(stateDir) {
     const clearedState = emptyHookState();
+    // rationale: updating an undefined state dir already returns the updater's
+    // result computed from empty state.
+    // Stryker disable next-line ConditionalExpression, BlockStatement
     if (!stateDir) {
         return clearedState;
     }

package/dist/kb-mcp-tools.d.ts

@@ -1,10 +1,8 @@
-export type KbMcpToolCall = {
-    toolName: string;
-    impactCheckRun: boolean;
-    sourceFiles: string[];
-};
-export type McpState = "observed" | "unknown";
-export type KibiInterface = "mcp" | "cli" | "setup";
+import type { KbMcpToolCall as SharedKbMcpToolCall, KibiInterface as SharedKibiInterface, McpState as SharedMcpState } from "kibi-agent-core/kb-mcp-tools";
+export type KbMcpToolCall = SharedKbMcpToolCall;
+export type McpState = SharedMcpState;
+export type KibiInterface = SharedKibiInterface;
+export declare function canonicalKbToolName(toolName: string | undefined): string | undefined;
 export declare function resolveKibiInterface(mcpState: McpState, workspaceTrusted: boolean): KibiInterface;
 export declare function extractKbMcpToolCall(toolName: string | undefined, toolInput: unknown): KbMcpToolCall | undefined;
 export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -1,134 +1,14 @@
 // implements REQ-cursor-kibi-plugin-v1
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function readString(record, keys) {
-    for (const key of keys) {
-        const value = record[key];
-        if (typeof value === "string") {
-            return value;
-        }
-    }
-    return undefined;
-}
-function readBoolean(record, keys) {
-    for (const key of keys) {
-        const value = record[key];
-        if (typeof value === "boolean") {
-            return value;
-        }
-    }
-    return undefined;
-}
-function readStringArray(record, keys) {
-    for (const key of keys) {
-        const value = record[key];
-        if (!Array.isArray(value)) {
-            continue;
-        }
-        return value.filter((item) => typeof item === "string" && item.length > 0);
-    }
-    return [];
-}
-function readRecord(record, keys) {
-    for (const key of keys) {
-        const value = record[key];
-        if (isRecord(value)) {
-            return value;
-        }
-    }
-    return undefined;
+import { canonicalKbToolName as canonicalSharedKbToolName, extractKbMcpToolCall as extractSharedKbMcpToolCall, extractKbMcpToolName as extractSharedKbMcpToolName, resolveKibiInterface as resolveSharedKibiInterface, } from "kibi-agent-core/kb-mcp-tools";
+export function canonicalKbToolName(toolName) {
+    return canonicalSharedKbToolName(toolName);
 }
 export function resolveKibiInterface(mcpState, workspaceTrusted) {
-    if (mcpState === "observed") {
-        return "mcp";
-    }
-    return workspaceTrusted ? "cli" : "setup";
+    return resolveSharedKibiInterface(mcpState, workspaceTrusted);
 }
 export function extractKbMcpToolCall(toolName, toolInput) {
-    const directToolName = toolName?.trim();
-    let normalizedToolName = directToolName?.startsWith("kb_")
-        ? directToolName
-        : undefined;
-    if (isRecord(toolInput)) {
-        normalizedToolName ??= readString(toolInput, [
-            "toolName",
-            "tool_name",
-            "name",
-        ]);
-        const args = readRecord(toolInput, ["arguments", "args"]);
-        const payload = args ?? toolInput;
-        const includeImpactDiagnostics = readBoolean(payload, [
-            "includeImpactDiagnostics",
-            "include_impact_diagnostics",
-        ]);
-        const includeWorkingTreeDiff = readBoolean(payload, [
-            "includeWorkingTreeDiff",
-            "include_working_tree_diff",
-        ]);
-        const sourceFiles = readStringArray(payload, [
-            "sourceFiles",
-            "source_files",
-        ]);
-        if (normalizedToolName?.startsWith("kb_")) {
-            return {
-                toolName: normalizedToolName,
-                impactCheckRun: normalizedToolName === "kb_check" &&
-                    includeImpactDiagnostics === true &&
-                    includeWorkingTreeDiff === true &&
-                    sourceFiles.length > 0,
-                sourceFiles,
-            };
-        }
-        const nestedArgs = toolInput.arguments ?? toolInput.args;
-        if (isRecord(nestedArgs)) {
-            const nestedTool = readString(nestedArgs, [
-                "toolName",
-                "tool_name",
-                "name",
-            ]);
-            if (nestedTool?.startsWith("kb_")) {
-                return { toolName: nestedTool, impactCheckRun: false, sourceFiles: [] };
-            }
-        }
-    }
-    if (normalizedToolName?.startsWith("kb_")) {
-        return {
-            toolName: normalizedToolName,
-            impactCheckRun: false,
-            sourceFiles: [],
-        };
-    }
-    return undefined;
+    return extractSharedKbMcpToolCall(toolName, toolInput);
 }
 export function extractKbMcpToolName(toolName, toolInput) {
-    const toolCall = extractKbMcpToolCall(toolName, toolInput);
-    if (toolCall) {
-        return toolCall.toolName;
-    }
-    if (toolName) {
-        const normalized = toolName.trim();
-        if (normalized.startsWith("kb_")) {
-            return normalized;
-        }
-    }
-    if (!isRecord(toolInput)) {
-        return undefined;
-    }
-    const directTool = readString(toolInput, ["toolName", "tool_name", "name"]);
-    if (directTool?.startsWith("kb_")) {
-        return directTool;
-    }
-    const nestedArgs = toolInput.arguments ?? toolInput.args;
-    if (isRecord(nestedArgs)) {
-        const nestedTool = readString(nestedArgs, [
-            "toolName",
-            "tool_name",
-            "name",
-        ]);
-        if (nestedTool?.startsWith("kb_")) {
-            return nestedTool;
-        }
-    }
-    return undefined;
+    return extractSharedKbMcpToolName(toolName, toolInput);
 }

package/dist/messages.js

@@ -5,6 +5,9 @@ export const DIRECT_KB_EDIT_WARNING = "Do not read or edit `.kb/` files directly
 export function interfaceAdvisory(mcpState, workspaceTrusted) {
     const selectedInterface = resolveKibiInterface(mcpState, workspaceTrusted);
     switch (selectedInterface) {
+        // rationale: an unmatched switch case already returns undefined, so the
+        // mcp case is behaviorally redundant.
+        // Stryker disable next-line ConditionalExpression, StringLiteral
         case "mcp":
             return undefined;
         case "cli":
@@ -21,14 +24,6 @@ export function stopFollowupMessage(state) {
     const sourceImpactPaths = state.dirtyPaths.filter(isSourceImpactRelevantPath);
     const uncheckedSourcePaths = sourceImpactPaths.filter((sourcePath) => !state.impactCheckedPaths.includes(sourcePath));
     const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
-    const hasFollowupWork = uncheckedSourcePaths.length > 0 ||
-        (freshnessPaths.length > 0 && !state.kbCheckRun);
-    if (state.planDelivered && !hasFollowupWork) {
-        return undefined;
-    }
-    if (uncheckedSourcePaths.length > 0 && !state.impactCheckRun) {
-        return impactCheckFollowup(uncheckedSourcePaths);
-    }
     if (uncheckedSourcePaths.length > 0) {
         return impactCheckFollowup(uncheckedSourcePaths);
     }