kibi-cursor 0.2.0

package/dist/hook-state.js

@@ -0,0 +1,250 @@
+// implements REQ-cursor-kibi-plugin-v1
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const stateFileName = "hook-state.json";
+const lockFileName = "hook-state.lock";
+const maxDirtyPaths = 50;
+const maxGuidedPaths = 100;
+const lockRetryCount = 100;
+const lockRetryDelayMs = 5;
+const staleLockAgeMs = 30_000;
+function statePath(pluginData) {
+    return path.join(pluginData, stateFileName);
+}
+function lockPath(pluginData) {
+    return path.join(pluginData, lockFileName);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePath(dirtyPath) {
+    return dirtyPath.trim().replaceAll("\\", "/");
+}
+function sleepSync(milliseconds) {
+    const buffer = new SharedArrayBuffer(4);
+    const view = new Int32Array(buffer);
+    Atomics.wait(view, 0, 0, milliseconds);
+}
+function uniqueTempPath(pluginData) {
+    return path.join(pluginData, `${stateFileName}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+}
+function mergeStringPaths(existingPaths, nextPaths) {
+    const merged = [...existingPaths, ...nextPaths]
+        .map(normalizePath)
+        .filter((dirtyPath) => dirtyPath.length > 0);
+    return [...new Set(merged)].slice(-maxGuidedPaths);
+}
+const maxKbMutationTools = 20;
+function emptyHookState() {
+    return {
+        dirtyPaths: [],
+        guidedReadPaths: [],
+        guidedWritePaths: [],
+        kbMutationTools: [],
+        kbCheckRun: false,
+    };
+}
+function acquireLock(pluginData) {
+    const targetLockPath = lockPath(pluginData);
+    for (let attempt = 0; attempt < lockRetryCount; attempt++) {
+        try {
+            return fs.openSync(targetLockPath, "wx");
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                error.code === "EEXIST") {
+                if (removeStaleLock(targetLockPath)) {
+                    continue;
+                }
+                sleepSync(lockRetryDelayMs);
+                continue;
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function removeStaleLock(targetLockPath) {
+    let stats;
+    try {
+        stats = fs.statSync(targetLockPath);
+    }
+    catch {
+        return false;
+    }
+    if (Date.now() - stats.mtimeMs < staleLockAgeMs) {
+        return false;
+    }
+    try {
+        fs.unlinkSync(targetLockPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseLock(pluginData, fileDescriptor) {
+    try {
+        fs.closeSync(fileDescriptor);
+    }
+    catch {
+        // Ignore close failures; unlink still gives future hook runs a chance.
+    }
+    try {
+        fs.unlinkSync(lockPath(pluginData));
+    }
+    catch {
+        // A missing lock file is safe: bounded retries prevent permanent blocking.
+    }
+}
+function coerceHookState(value) {
+    if (!isRecord(value)) {
+        return emptyHookState();
+    }
+    const dirtyPaths = Array.isArray(value.dirtyPaths)
+        ? value.dirtyPaths
+            .filter((dirtyPath) => typeof dirtyPath === "string")
+            .map(normalizePath)
+            .filter((dirtyPath) => dirtyPath.length > 0)
+        : [];
+    const guidedReadPaths = Array.isArray(value.guidedReadPaths)
+        ? value.guidedReadPaths
+            .filter((entry) => typeof entry === "string")
+            .map(normalizePath)
+            .filter((entry) => entry.length > 0)
+        : [];
+    const guidedWritePaths = Array.isArray(value.guidedWritePaths)
+        ? value.guidedWritePaths
+            .filter((entry) => typeof entry === "string")
+            .map(normalizePath)
+            .filter((entry) => entry.length > 0)
+        : [];
+    const kbMutationTools = Array.isArray(value.kbMutationTools)
+        ? value.kbMutationTools
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)
+        : [];
+    const kbCheckRun = value.kbCheckRun === true;
+    return {
+        dirtyPaths: [...new Set(dirtyPaths)].slice(-maxDirtyPaths),
+        guidedReadPaths: [...new Set(guidedReadPaths)].slice(-maxGuidedPaths),
+        guidedWritePaths: [...new Set(guidedWritePaths)].slice(-maxGuidedPaths),
+        kbMutationTools: [...new Set(kbMutationTools)].slice(-maxKbMutationTools),
+        kbCheckRun,
+    };
+}
+export function resolveStateDir(pluginData, conversationId) {
+    if (pluginData) {
+        return pluginData;
+    }
+    if (!conversationId) {
+        return undefined;
+    }
+    return path.join(os.tmpdir(), "kibi-cursor-hook-state", conversationId.replaceAll(/[^a-zA-Z0-9._-]/g, "_"));
+}
+export function loadHookState(stateDir) {
+    if (!stateDir) {
+        return emptyHookState();
+    }
+    try {
+        return coerceHookState(JSON.parse(fs.readFileSync(statePath(stateDir), "utf8")));
+    }
+    catch {
+        return emptyHookState();
+    }
+}
+export function saveHookState(stateDir, state) {
+    if (!stateDir) {
+        return;
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const boundedState = coerceHookState(state);
+    const tempPath = uniqueTempPath(stateDir);
+    fs.writeFileSync(tempPath, `${JSON.stringify(boundedState)}\n`);
+    fs.renameSync(tempPath, statePath(stateDir));
+}
+export function updateHookState(stateDir, updater) {
+    const initialState = loadHookState(stateDir);
+    if (!stateDir) {
+        return updater(initialState);
+    }
+    fs.mkdirSync(stateDir, { recursive: true });
+    const lockFileDescriptor = acquireLock(stateDir);
+    if (lockFileDescriptor === undefined) {
+        return updater(initialState);
+    }
+    try {
+        const lockedState = loadHookState(stateDir);
+        const nextState = updater(lockedState);
+        saveHookState(stateDir, nextState);
+        return nextState;
+    }
+    catch {
+        return updater(initialState);
+    }
+    finally {
+        releaseLock(stateDir, lockFileDescriptor);
+    }
+}
+export function addDirtyPaths(stateDir, dirtyPaths) {
+    return updateHookState(stateDir, (state) => ({
+        ...state,
+        dirtyPaths: mergeStringPaths(state.dirtyPaths, dirtyPaths).slice(-maxDirtyPaths),
+    }));
+}
+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]),
+            };
+        }
+        return {
+            ...state,
+            guidedWritePaths: mergeStringPaths(state.guidedWritePaths, [normalized]),
+        };
+    });
+}
+export function hasGuidedPath(state, kind, guidedPath) {
+    const normalized = normalizePath(guidedPath);
+    const bucket = kind === "read" ? state.guidedReadPaths : state.guidedWritePaths;
+    return bucket.includes(normalized);
+}
+export function recordKbMcpTool(stateDir, toolName) {
+    const normalized = toolName.trim();
+    if (normalized.length === 0) {
+        return loadHookState(stateDir);
+    }
+    return updateHookState(stateDir, (state) => {
+        if (normalized === "kb_check") {
+            return { ...state, kbCheckRun: true };
+        }
+        if (normalized === "kb_upsert" || normalized === "kb_delete") {
+            return {
+                ...state,
+                kbMutationTools: mergeStringPaths(state.kbMutationTools, [normalized]).slice(-maxKbMutationTools),
+            };
+        }
+        return state;
+    });
+}
+export function clearSessionHookState(stateDir) {
+    const clearedState = emptyHookState();
+    if (!stateDir) {
+        return clearedState;
+    }
+    return updateHookState(stateDir, () => clearedState);
+}
+/** @deprecated Use clearSessionHookState */
+export function clearDirtyPaths(stateDir) {
+    return clearSessionHookState(stateDir);
+}

package/dist/hooks/hooks.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node dist/hook-runner.js"
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": "node dist/hook-runner.js"
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "node dist/hook-runner.js"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "node dist/hook-runner.js"
+      }
+    ],
+    "stop": [
+      {
+        "command": "node dist/hook-runner.js",
+        "loop_limit": 1
+      }
+    ]
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export declare const packageName = "kibi-cursor";
+export declare const adapterKind = "cursor-plugin";
+declare const cursorPlugin: {
+    name: string;
+    adapterKind: string;
+};
+export default cursorPlugin;

package/dist/index.js

@@ -0,0 +1,8 @@
+// implements REQ-cursor-kibi-plugin-v1
+export const packageName = "kibi-cursor";
+export const adapterKind = "cursor-plugin";
+const cursorPlugin = {
+    name: packageName,
+    adapterKind,
+};
+export default cursorPlugin;

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

@@ -0,0 +1 @@
+export declare function extractKbMcpToolName(toolName: string | undefined, toolInput: unknown): string | undefined;

package/dist/kb-mcp-tools.js

@@ -0,0 +1,36 @@
+// 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;
+}
+export function extractKbMcpToolName(toolName, toolInput) {
+    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;
+}

package/dist/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "kibi": {
+      "command": "npx",
+      "args": ["--no-install", "kibi-mcp"]
+    }
+  }
+}

package/dist/messages.d.ts

@@ -0,0 +1,6 @@
+import type { HookState } from "./hook-state.js";
+export declare const BOOTSTRAP_REMINDER = "Kibi is not initialized for this workspace. Use the Kibi MCP workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
+export declare const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+export declare function stopFollowupMessage(state: HookState): string | undefined;
+/** @deprecated Use stopFollowupMessage */
+export declare function freshnessReminder(dirtyPaths: readonly string[]): string;

package/dist/messages.js

@@ -0,0 +1,22 @@
+import { isKbFreshnessRelevantPath } from "./path-policy.js";
+export const BOOTSTRAP_REMINDER = "Kibi is not initialized for this workspace. Use the Kibi MCP workflow to bootstrap project memory before relying on KB lookups; do not edit .kb/ files directly.";
+export const DIRECT_KB_EDIT_WARNING = "Avoid direct edits to .kb/. Use Kibi MCP tools for KB discovery and mutations so project memory stays valid.";
+export function stopFollowupMessage(state) {
+    if (state.kbMutationTools.length > 0) {
+        const tools = [...new Set(state.kbMutationTools)];
+        return `Kibi KB updated (${tools.join(", ")}).`;
+    }
+    const freshnessPaths = state.dirtyPaths.filter(isKbFreshnessRelevantPath);
+    if (freshnessPaths.length === 0 || state.kbCheckRun) {
+        return undefined;
+    }
+    const fileCount = freshnessPaths.length;
+    const noun = fileCount === 1 ? "file" : "files";
+    return `Kibi: sync or record no-impact after ${fileCount} edited ${noun}.`;
+}
+/** @deprecated Use stopFollowupMessage */
+export function freshnessReminder(dirtyPaths) {
+    const fileCount = dirtyPaths.length;
+    const noun = fileCount === 1 ? "file" : "files";
+    return `Kibi: sync or record no-impact after ${fileCount} edited ${noun}.`;
+}

package/dist/path-policy.d.ts

@@ -0,0 +1,7 @@
+export declare function extractExplicitPathFields(input: unknown): string[];
+export declare function isDirectKbPath(candidate: string): boolean;
+export declare function isMeaningfulTrackedPath(candidate: string): boolean;
+/** Paths whose edits should trigger a KB freshness stop follow-up. */
+export declare function isKbFreshnessRelevantPath(candidate: string): boolean;
+export declare function isDocumentationTrackedPath(candidate: string): boolean;
+export declare function toRepoRelativePath(candidate: string, cwd: string | undefined): string;

package/dist/path-policy.js

@@ -0,0 +1,146 @@
+// implements REQ-cursor-kibi-plugin-v1
+const explicitPathKeys = new Set([
+    "absolute_path",
+    "file",
+    "file_path",
+    "filepath",
+    "new_path",
+    "old_path",
+    "path",
+    "paths",
+    "relative_path",
+    "target_path",
+]);
+const sourceExtensions = new Set([
+    ".c",
+    ".cc",
+    ".cpp",
+    ".cs",
+    ".css",
+    ".go",
+    ".h",
+    ".hpp",
+    ".html",
+    ".java",
+    ".js",
+    ".jsx",
+    ".kt",
+    ".lua",
+    ".mjs",
+    ".mts",
+    ".php",
+    ".py",
+    ".rb",
+    ".rs",
+    ".scala",
+    ".sh",
+    ".swift",
+    ".ts",
+    ".tsx",
+    ".vue",
+]);
+const documentationExtensions = new Set([".md", ".mdx", ".rst", ".txt"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizePath(candidate) {
+    return candidate.trim().replaceAll("\\", "/");
+}
+function pathSegments(candidate) {
+    return normalizePath(candidate).split("/").filter(Boolean);
+}
+function collectPathValues(value, output) {
+    if (typeof value === "string") {
+        const normalized = normalizePath(value);
+        if (normalized.length > 0) {
+            output.push(normalized);
+        }
+        return;
+    }
+    if (!Array.isArray(value)) {
+        return;
+    }
+    for (const item of value) {
+        collectPathValues(item, output);
+    }
+}
+function visitExplicitPathFields(value, output) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            visitExplicitPathFields(item, output);
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (explicitPathKeys.has(key.toLowerCase())) {
+            collectPathValues(child, output);
+        }
+        visitExplicitPathFields(child, output);
+    }
+}
+export function extractExplicitPathFields(input) {
+    const paths = [];
+    visitExplicitPathFields(input, paths);
+    return [...new Set(paths)];
+}
+export function isDirectKbPath(candidate) {
+    return pathSegments(candidate).includes(".kb");
+}
+export function isMeaningfulTrackedPath(candidate) {
+    const normalized = normalizePath(candidate);
+    const segments = pathSegments(normalized);
+    if (segments.includes(".kb") || segments.includes("dist")) {
+        return false;
+    }
+    const basename = segments.at(-1) ?? "";
+    const extension = basename.includes(".")
+        ? `.${basename.split(".").at(-1) ?? ""}`
+        : "";
+    if (segments.includes("docs") || segments.includes("documentation")) {
+        return documentationExtensions.has(extension);
+    }
+    if (basename === "README.md") {
+        return true;
+    }
+    if (segments.includes("src") ||
+        segments.includes("tests") ||
+        segments.includes("test")) {
+        return (sourceExtensions.has(extension) || documentationExtensions.has(extension));
+    }
+    return false;
+}
+/** Paths whose edits should trigger a KB freshness stop follow-up. */
+export function isKbFreshnessRelevantPath(candidate) {
+    const segments = pathSegments(normalizePath(candidate));
+    if (segments.includes("documentation")) {
+        return true;
+    }
+    return (segments[0] === "packages" &&
+        segments[1] === "core" &&
+        segments[2] === "src");
+}
+export function isDocumentationTrackedPath(candidate) {
+    const normalized = normalizePath(candidate);
+    const segments = pathSegments(normalized);
+    const basename = segments.at(-1) ?? "";
+    const extension = basename.includes(".")
+        ? `.${basename.split(".").at(-1) ?? ""}`
+        : "";
+    return (segments.includes("docs") ||
+        segments.includes("documentation") ||
+        documentationExtensions.has(extension));
+}
+export function toRepoRelativePath(candidate, cwd) {
+    const normalized = normalizePath(candidate);
+    if (!cwd) {
+        return normalized;
+    }
+    const cwdPrefix = `${normalizePath(cwd)}/`;
+    if (normalized.startsWith(cwdPrefix)) {
+        return normalized.slice(cwdPrefix.length);
+    }
+    return normalized;
+}

package/dist/rules/kibi-traceability.mdc

@@ -0,0 +1,14 @@
+---
+description: Requirement traceability and symbol linking through Kibi
+globs:
+  - "**/*.{ts,tsx,js,jsx,py,go,rs,java}"
+alwaysApply: false
+---
+
+Before changing production code, discover linked requirements with `kb_search` and `kb_query(sourceFile=...)`.
+
+Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when modeling behavior.
+
+Prefer symbol manifest + `executable_for` for test/e2e code. Inline `// implements REQ-xxx` remains acceptable for quick code-only changes.
+
+Route durable domain facts to strict `fact` entities. Use `fact_kind: observation` or `meta` for bugs and workarounds, not `flag`.

package/dist/rules/kibi-workflow.mdc

@@ -0,0 +1,19 @@
+---
+description: Kibi MCP discovery-first workflow and KB mutation discipline
+alwaysApply: true
+---
+
+Use Kibi via MCP tools only. Do not manually read or edit `.kb/` files.
+
+Discovery workflow:
+- Start with `kb_search` for broad discovery.
+- Follow with `kb_query` for exact entities, filters, and source-linked lookups.
+- Use `kb_status`, `kb_find_gaps`, `kb_coverage`, and `kb_graph` when reporting questions need them.
+
+Mutation workflow:
+- Query before mutate.
+- Create relationship endpoints before linking.
+- Use `kb_upsert` sequentially, then `kb_check`.
+- Use `kb_delete` only for intentional removals with dependency awareness.
+
+Completion must state KB freshness outcome: updated, no-impact with rationale, or deferred/failed.

package/dist/skills/init-kibi/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: init-kibi
+description: Bootstrap and model knowledge safely using approved Kibi MCP initialization and mutation workflow.
+---
+
+## Goal
+
+Set up or refresh Kibi knowledge for the current branch without manual filesystem edits.
+
+## MCP workflow
+
+- Run `kb_autopilot_generate` for suggested initial facts and claims.
+- Show the generated preview and get explicit approval before writes.
+- Use `kb_upsert` for reviewed entity creation or updates.
+- If cleanup is needed, use `kb_delete` only after checking dependencies.
+- Finish with `kb_check` to validate the branch snapshot.
+
+## Guidance
+
+- Keep mutation requests explicit and small.
+- Use source-linked entities where possible so future `kb_query` lookups can verify context.
+- Do not edit `.kb/**` files directly; all changes go through MCP calls.
+- Ask at most four bounded context questions, and only when repository evidence is insufficient.

package/dist/skills/kibi-freshness/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: kibi-freshness
+description: Check branch freshness and source linkage quality before decisions or risky writes.
+---
+
+## Goal
+
+Help agents decide whether KB context is current enough to support safe changes.
+
+## MCP workflow
+
+- Use `kb_status` first to confirm branch attachment and freshness state.
+- Use `kb_query` with `sourceFile`/text refs for source-linked discovery.
+- Re-run `kb_search` after sync gaps are detected.
+- If knowledge must change, update it with `kb_upsert` or `kb_delete` and finish with `kb_check`.
+
+## Guidance
+
+- Never proceed with broad changes when freshness is stale and unresolved.
+- If entities look stale, prefer refreshing context via MCP flows and then re-query.
+- Avoid direct `.kb` editing; use `kb_status` and other MCP checks instead.
+- Completion must state one freshness outcome: KB updated, no KB impact with rationale, or deferred/failed.

package/dist/skills/kibi-traceability/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: kibi-traceability
+description: Maintain requirement, scenario, and test traceability through Kibi MCP tools.
+---
+
+## Goal
+
+Validate and strengthen traceability before and after code changes.
+
+## MCP workflow
+
+- Locate requirements with `kb_search` and inspect exact details with `kb_query`.
+- Apply updates with `kb_upsert` for requirements, scenarios, tests, or facts.
+- Validate constraints and consistency with `kb_check`.
+
+## Guidance
+
+- Prefer source-linked relationships so symbols and files can be traced back cleanly.
+- Include `kb_query` and `kb_delete` only when explicit cleanups are required.
+- Never directly edit `.kb/**`; all modeling and cleanup goes through MCP tools.
+- Preserve the canonical chain `REQ-* -> SCEN-* -> TEST-*` when adding or changing requirements.
+- Production symbols should implement requirements; test symbols should remain executable evidence for tests.

package/dist/skills/kibi-usage/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: kibi-usage
+description: Use Kibi MCP discovery tools to find relevant requirements and context before editing code.
+---
+
+## Goal
+
+Help an agent discover existing knowledge in Kibi before making changes.
+
+## MCP workflow
+
+- Start with `kb_search` using domain keywords and requirement intent.
+- Move to `kb_query` for exact entity retrieval by `id` or `type`.
+- Use `kb_status` when context is stale or branch linkage is unclear.
+- Use curated reports only when the question needs them: `kb_find_gaps`, `kb_coverage`, or `kb_graph`.
+- Mutate only through `kb_upsert` or `kb_delete`, then validate with `kb_check`.
+
+## Guidance
+
+- Prefer source-linked lookups and traceability-aware retrieval via `kb_query` filters.
+- Never open or patch files under `.kb/` directly.
+- When unsure about scope, re-run `kb_search` with tighter terms, then validate with `kb_query`.
+- Report the KB outcome before completion: updated, no-impact with rationale, or deferred/failed.