kibi-cursor 0.2.0

package/.cursor-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "kibi-cursor",
+  "displayName": "Kibi",
+  "version": "0.2.0",
+  "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
+  "license": "AGPL-3.0-or-later",
+  "author": {
+    "name": "Kibi"
+  },
+  "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",
+  "repository": "https://github.com/Looted/kibi",
+  "keywords": ["kibi", "mcp", "knowledge-base", "traceability", "swi-prolog"],
+  "skills": "./skills/",
+  "rules": "./rules/",
+  "commands": "./commands/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./mcp.json"
+}

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# kibi-cursor
+
+## 0.2.0
+
+### Minor Changes
+
+- Cursor users can now install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on the existing `kibi-cli` and `kibi-mcp` foundation without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
+
+  - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, rules, skills, commands, hook declarations, and MCP config.
+  - Add advisory hooks for bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and session freshness follow-ups.
+  - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.
+
+## 0.1.0
+
+### Minor Changes
+
+- Cursor users can install an optional Kibi adapter plugin that bundles MCP configuration, workflow rules, skills, slash commands, and advisory editor hooks. The plugin builds on `kibi-core`, `kibi-cli`, and `kibi-mcp` without replacing them, and teams that prefer manual setup can continue configuring the local `kibi-mcp` server directly.
+
+  - Add the publishable `kibi-cursor` package with Cursor plugin manifest assets, bundled skills, rules, commands, hook declarations, and MCP config.
+  - Add a conservative hook runner with bounded session state, bootstrap reminders, direct `.kb` edit warnings, read/write guidance, and freshness follow-ups.
+  - Wire `kibi-cursor` into workspace build, pack, release-state, publish, CI unit coverage, docs, and marketplace verification.

package/README.md

@@ -0,0 +1,120 @@
+# kibi-cursor
+
+Cursor plugin for Kibi — repo-local, per-branch, queryable knowledge base.
+
+`kibi-cursor` is optional. It provides Cursor-specific rules, skills, commands, MCP wiring, and advisory editor hooks, but it does not ship a replacement `kibi` CLI or `kibi-mcp` server binary.
+
+## Prerequisites
+
+Install these **before** enabling the plugin MCP server:
+
+| Requirement | Why |
+| --- | --- |
+| **SWI-Prolog 9+** (`swipl` on `PATH`) | Powers Kibi inference and validation |
+| **`kibi-cli`** | Project CLI (`kibi` command) |
+| **`kibi-mcp`** | MCP server the plugin's `mcp.json` invokes via `npx --no-install kibi-mcp` |
+| **`kibi-core`** | Shared graph/runtime dependency |
+
+```bash
+npm install --save-dev kibi-cli kibi-mcp kibi-core
+swipl --version
+npm exec -- kibi doctor
+```
+
+Full setup: [docs/install.md](https://github.com/Looted/kibi/blob/develop/docs/install.md).
+
+Add this plugin only after the base packages work in your project.
+
+## Installation
+
+### Cursor Marketplace (recommended)
+
+Submit or install from the Kibi repository marketplace at `.cursor-plugin/marketplace.json`, which points at `./plugins/kibi-cursor`.
+
+For local testing before marketplace publication, copy a real directory tree into Cursor's user-plugins folder. Symlinks are rejected when the target lives outside `plugins/local` (common on WSL):
+
+```bash
+./scripts/sync-cursor-plugin-local.sh
+```
+
+On WSL workspaces, Cursor reads `~/.cursor/plugins/local` in your Linux home, not the Windows profile path. Reload Cursor (**Developer: Reload Window**) and check **Plugins → User**.
+
+### npm package
+
+```bash
+npm install --save-dev kibi-cursor
+```
+
+Copy the installed package into Cursor's local plugin directory (do not symlink):
+
+```bash
+cp -r "$(npm root)/kibi-cursor" ~/.cursor/plugins/local/kibi-cursor
+```
+
+## MCP configuration
+
+The plugin bundles `mcp.json` pointing at the project-local `kibi-mcp` binary:
+
+```json
+{
+  "mcpServers": {
+    "kibi": {
+      "command": "npx",
+      "args": ["--no-install", "kibi-mcp"]
+    }
+  }
+}
+```
+
+Toggle the bundled MCP server from **Settings → Features → Model Context Protocol** after installing the plugin.
+
+Manual MCP fallback (no plugin install required):
+
+```json
+{
+  "mcpServers": {
+    "kibi": {
+      "command": "npx",
+      "args": ["--no-install", "kibi-mcp"]
+    }
+  }
+}
+```
+
+## Features
+
+### Discovery-first rules and skills
+
+- **Rules**: always-on MCP workflow guidance plus optional traceability rules for source files.
+- **Skills**: `kibi-usage`, `init-kibi`, `kibi-freshness`, and `kibi-traceability`.
+- **Commands**: `/init-kibi` documents the `kb_autopilot_generate` bootstrap workflow.
+
+### Advisory editor hooks
+
+Hooks are warning-only and never replace MCP/CLI behavior:
+
+- **sessionStart**: bootstrap reminder when `.kb/config.json` is missing.
+- **preToolUse**: warns on explicit direct `.kb/**` edits without blocking.
+- **beforeReadFile** and **postToolUse (Read)**: inject source-linked lookup guidance once per path per session.
+- **postToolUse (Write/Edit)**: inject traceability and freshness guidance once per path per session.
+- **stop**: emits a single freshness follow-up when meaningful paths changed during the session.
+
+### What the plugin does not do
+
+Per the thin-adapter architecture, `kibi-cursor` does not:
+
+- Own KB storage, parsing, or validation
+- Run background `kibi sync` or `kibi check` (use git hooks and MCP tools)
+- Block agent actions in advisory mode
+
+## Architecture
+
+`kibi-cursor` is a thin bridge layer:
+
+- **Agent-visible guidance**: public MCP tools (`kb_search`, `kb_query`, `kb_upsert`, `kb_check`, etc.) and the `/init-kibi` command
+- **Editor-specific value**: Cursor hooks for read/write reminders and session freshness follow-ups
+- **Foundation**: `kibi-core`, `kibi-cli`, and `kibi-mcp` remain required for project-local operations
+
+## License
+
+AGPL-3.0-or-later

package/commands/init-kibi.md

@@ -0,0 +1,21 @@
+---
+name: init-kibi
+description: Bootstrap Kibi knowledge for the current branch using the MCP autopilot workflow
+---
+
+# Initialize Kibi
+
+Bootstrap repo-local Kibi memory without editing `.kb/` files directly.
+
+## Workflow
+
+1. Run `kb_autopilot_generate` for read-only synthesis.
+2. Show the preview and get explicit approval before writes.
+3. Apply approved entities with sequential `kb_upsert`.
+4. Finish with `kb_check`.
+
+## Guidance
+
+- Ask at most four bounded context questions when repository evidence is insufficient.
+- Prefer source-linked entities so future `kb_query` lookups can verify context.
+- Keep mutation batches small and reviewable.

package/dist/.cursor-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "kibi-cursor",
+  "displayName": "Kibi",
+  "version": "0.2.0",
+  "description": "Optional Cursor adapter for Kibi. Requires SWI-Prolog 9+ and project-local kibi-cli, kibi-mcp, and kibi-core before the bundled MCP server can start.",
+  "license": "AGPL-3.0-or-later",
+  "author": {
+    "name": "Kibi"
+  },
+  "homepage": "https://github.com/Looted/kibi/blob/develop/docs/install.md",
+  "repository": "https://github.com/Looted/kibi",
+  "keywords": ["kibi", "mcp", "knowledge-base", "traceability", "swi-prolog"],
+  "skills": "./skills/",
+  "rules": "./rules/",
+  "commands": "./commands/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./mcp.json"
+}

package/dist/commands/init-kibi.md

@@ -0,0 +1,21 @@
+---
+name: init-kibi
+description: Bootstrap Kibi knowledge for the current branch using the MCP autopilot workflow
+---
+
+# Initialize Kibi
+
+Bootstrap repo-local Kibi memory without editing `.kb/` files directly.
+
+## Workflow
+
+1. Run `kb_autopilot_generate` for read-only synthesis.
+2. Show the preview and get explicit approval before writes.
+3. Apply approved entities with sequential `kb_upsert`.
+4. Finish with `kb_check`.
+
+## Guidance
+
+- Ask at most four bounded context questions when repository evidence is insufficient.
+- Prefer source-linked entities so future `kb_query` lookups can verify context.
+- Keep mutation batches small and reviewable.

package/dist/guidance.d.ts

@@ -0,0 +1,2 @@
+export declare function readGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;
+export declare function writeGuidance(filePath: string, cwd: string | undefined, hasKibi: boolean): string | undefined;

package/dist/guidance.js

@@ -0,0 +1,37 @@
+// implements REQ-cursor-kibi-plugin-v1
+import { isDocumentationTrackedPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
+export function readGuidance(filePath, cwd, hasKibi) {
+    if (!hasKibi) {
+        return undefined;
+    }
+    const relativePath = toRepoRelativePath(filePath, cwd);
+    if (!isMeaningfulTrackedPath(relativePath)) {
+        return undefined;
+    }
+    return [
+        "Kibi read guidance: before changing this file, discover linked knowledge with Kibi MCP.",
+        `Start with kb_search, then kb_query with sourceFile="${relativePath}".`,
+        "Prefer Kibi facts and requirements over long inline comments for durable knowledge.",
+    ].join("\n");
+}
+export function writeGuidance(filePath, cwd, hasKibi) {
+    if (!hasKibi) {
+        return undefined;
+    }
+    const relativePath = toRepoRelativePath(filePath, cwd);
+    if (!isMeaningfulTrackedPath(relativePath)) {
+        return undefined;
+    }
+    if (isDocumentationTrackedPath(relativePath)) {
+        return [
+            "Kibi write guidance: keep REQ, SCEN, and TEST artifacts separate.",
+            "Update KB entities through kb_upsert and finish with kb_check.",
+            "Do not edit .kb/ files directly.",
+        ].join("\n");
+    }
+    return [
+        "Kibi write guidance: link production symbols to requirements.",
+        `After editing, resolve freshness with kb_search/kb_query for sourceFile="${relativePath}".`,
+        "Prefer symbol manifest + executable_for or // implements REQ-xxx for traceability.",
+    ].join("\n");
+}

package/dist/hook-input.d.ts

@@ -0,0 +1,12 @@
+export type HookEvent = "sessionStart" | "preToolUse" | "postToolUse" | "beforeReadFile" | "stop";
+export type HookInput = {
+    event: string;
+    cwd?: string;
+    toolName?: string;
+    toolInput?: unknown;
+    conversationId?: string;
+    filePath?: string;
+};
+export declare function parseHookInput(input: unknown): HookInput;
+export declare function readStdin(): Promise<string>;
+export declare function parseStdinJson(rawInput: string): unknown;

package/dist/hook-input.js

@@ -0,0 +1,75 @@
+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 normalizeEventName(event) {
+    const trimmed = event.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    return trimmed.charAt(0).toLowerCase() + trimmed.slice(1);
+}
+export function parseHookInput(input) {
+    if (!isRecord(input)) {
+        return { event: "" };
+    }
+    const rawEvent = readString(input, [
+        "event",
+        "hook_event",
+        "hookEvent",
+        "hook_event_name",
+        "name",
+    ]) ?? "";
+    const event = normalizeEventName(rawEvent);
+    const cwd = readString(input, [
+        "cwd",
+        "current_working_directory",
+        "workspace",
+    ]);
+    const toolName = readString(input, ["toolName", "tool_name", "tool"]);
+    const toolInput = input.toolInput ?? input.tool_input ?? input.input;
+    const conversationId = readString(input, [
+        "conversation_id",
+        "conversationId",
+    ]);
+    const filePath = readString(input, ["file_path", "filePath", "path"]);
+    const parsed = { event };
+    if (cwd !== undefined) {
+        parsed.cwd = cwd;
+    }
+    if (toolName !== undefined) {
+        parsed.toolName = toolName;
+    }
+    if (toolInput !== undefined) {
+        parsed.toolInput = toolInput;
+    }
+    if (conversationId !== undefined) {
+        parsed.conversationId = conversationId;
+    }
+    if (filePath !== undefined) {
+        parsed.filePath = filePath;
+    }
+    return parsed;
+}
+export async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export function parseStdinJson(rawInput) {
+    const trimmed = rawInput.trim();
+    if (trimmed.length === 0) {
+        return {};
+    }
+    return JSON.parse(trimmed);
+}

package/dist/hook-runner.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+export type CursorHookResult = {
+    additional_context?: string;
+    permission?: "allow" | "deny";
+    user_message?: string;
+    agent_message?: string;
+    followup_message?: string;
+};
+export type HookEnvironment = {
+    pluginData?: string;
+};
+export declare function runHook(rawInput: unknown, environment?: HookEnvironment): Promise<CursorHookResult>;
+export declare const hookRunnerPath: string;

package/dist/hook-runner.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// implements REQ-cursor-kibi-plugin-v1
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { readGuidance, writeGuidance } from "./guidance.js";
+import { parseHookInput, parseStdinJson, readStdin } from "./hook-input.js";
+import { extractKbMcpToolName } from "./kb-mcp-tools.js";
+import { addDirtyPaths, clearSessionHookState, hasGuidedPath, loadHookState, recordKbMcpTool, rememberGuidedPath, resolveStateDir, } from "./hook-state.js";
+import { BOOTSTRAP_REMINDER, DIRECT_KB_EDIT_WARNING, stopFollowupMessage, } from "./messages.js";
+import { extractExplicitPathFields, isDirectKbPath, isMeaningfulTrackedPath, toRepoRelativePath, } from "./path-policy.js";
+const editableTools = new Set([
+    "Edit",
+    "MultiEdit",
+    "Write",
+    "StrReplace",
+    "apply_patch",
+]);
+const readTools = new Set(["Read", "TabRead"]);
+function emptyResult() {
+    return {};
+}
+function hasKibiConfig(cwd) {
+    if (!cwd) {
+        return false;
+    }
+    return fs.existsSync(path.join(cwd, ".kb", "config.json"));
+}
+function isEditLikeTool(toolName) {
+    return toolName === undefined || editableTools.has(toolName);
+}
+function isReadLikeTool(toolName) {
+    return toolName === undefined || readTools.has(toolName);
+}
+function resolveWorkspaceRoot(input) {
+    return input.cwd ?? process.cwd();
+}
+function resolvePrimaryPath(input) {
+    if (input.filePath) {
+        return input.filePath;
+    }
+    const explicitPaths = extractExplicitPathFields(input.toolInput);
+    return explicitPaths[0];
+}
+export async function runHook(rawInput, environment = {}) {
+    const input = parseHookInput(rawInput);
+    const pluginData = environment.pluginData ?? process.env.PLUGIN_DATA;
+    const stateDir = resolveStateDir(pluginData, input.conversationId);
+    const cwd = resolveWorkspaceRoot(input);
+    const kibiReady = hasKibiConfig(cwd);
+    switch (input.event) {
+        case "sessionStart":
+            if (!kibiReady) {
+                return { additional_context: BOOTSTRAP_REMINDER };
+            }
+            return emptyResult();
+        case "preToolUse": {
+            const explicitPaths = extractExplicitPathFields(input.toolInput);
+            const hasDirectKbEdit = isEditLikeTool(input.toolName) && explicitPaths.some(isDirectKbPath);
+            if (hasDirectKbEdit) {
+                return {
+                    permission: "allow",
+                    agent_message: DIRECT_KB_EDIT_WARNING,
+                };
+            }
+            return emptyResult();
+        }
+        case "beforeReadFile": {
+            const primaryPath = resolvePrimaryPath(input);
+            if (!primaryPath || !kibiReady) {
+                return { permission: "allow" };
+            }
+            const relativePath = toRepoRelativePath(primaryPath, cwd);
+            const state = loadHookState(stateDir);
+            if (hasGuidedPath(state, "read", relativePath)) {
+                return { permission: "allow" };
+            }
+            const guidance = readGuidance(primaryPath, cwd, kibiReady);
+            if (!guidance) {
+                return { permission: "allow" };
+            }
+            rememberGuidedPath(stateDir, "read", relativePath);
+            return {
+                permission: "allow",
+                agent_message: guidance,
+            };
+        }
+        case "postToolUse": {
+            const kbToolName = extractKbMcpToolName(input.toolName, input.toolInput);
+            if (kbToolName) {
+                recordKbMcpTool(stateDir, kbToolName);
+            }
+            const explicitPaths = extractExplicitPathFields(input.toolInput);
+            const dirtyPaths = explicitPaths
+                .map((candidate) => toRepoRelativePath(candidate, cwd))
+                .filter(isMeaningfulTrackedPath);
+            if (dirtyPaths.length > 0) {
+                addDirtyPaths(stateDir, dirtyPaths);
+            }
+            const primaryPath = resolvePrimaryPath(input);
+            if (!primaryPath || !kibiReady) {
+                return emptyResult();
+            }
+            const relativePath = toRepoRelativePath(primaryPath, cwd);
+            const state = loadHookState(stateDir);
+            if (isReadLikeTool(input.toolName)) {
+                if (hasGuidedPath(state, "read", relativePath)) {
+                    return emptyResult();
+                }
+                const guidance = readGuidance(primaryPath, cwd, kibiReady);
+                if (!guidance) {
+                    return emptyResult();
+                }
+                rememberGuidedPath(stateDir, "read", relativePath);
+                return { additional_context: guidance };
+            }
+            if (isEditLikeTool(input.toolName)) {
+                if (hasGuidedPath(state, "write", relativePath)) {
+                    return emptyResult();
+                }
+                const guidance = writeGuidance(primaryPath, cwd, kibiReady);
+                if (!guidance) {
+                    return emptyResult();
+                }
+                rememberGuidedPath(stateDir, "write", relativePath);
+                return { additional_context: guidance };
+            }
+            return emptyResult();
+        }
+        case "stop": {
+            const state = loadHookState(stateDir);
+            const followupMessage = stopFollowupMessage(state);
+            if (followupMessage) {
+                clearSessionHookState(stateDir);
+                return { followup_message: followupMessage };
+            }
+            if (state.dirtyPaths.length > 0 ||
+                state.kbMutationTools.length > 0 ||
+                state.kbCheckRun) {
+                clearSessionHookState(stateDir);
+            }
+            return emptyResult();
+        }
+        default:
+            return emptyResult();
+    }
+}
+async function main() {
+    const result = await runHook(parseStdinJson(await readStdin()));
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+const invokedPath = process.argv[1]
+    ? pathToFileURL(path.resolve(process.argv[1])).href
+    : "";
+if (import.meta.url === invokedPath) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.message : "Unknown hook error";
+        process.stdout.write(`${JSON.stringify({
+            additional_context: `Kibi hook runner error: ${message}`,
+        })}\n`);
+    });
+}
+export const hookRunnerPath = fileURLToPath(import.meta.url);

package/dist/hook-state.d.ts

@@ -0,0 +1,18 @@
+export type HookState = {
+    dirtyPaths: string[];
+    guidedReadPaths: string[];
+    guidedWritePaths: string[];
+    kbMutationTools: string[];
+    kbCheckRun: boolean;
+};
+export declare function resolveStateDir(pluginData: string | undefined, conversationId: string | undefined): string | undefined;
+export declare function loadHookState(stateDir: string | undefined): HookState;
+export declare function saveHookState(stateDir: string | undefined, state: HookState): void;
+export declare function updateHookState(stateDir: string | undefined, updater: (state: HookState) => HookState): HookState;
+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 recordKbMcpTool(stateDir: string | undefined, toolName: string): HookState;
+export declare function clearSessionHookState(stateDir: string | undefined): HookState;
+/** @deprecated Use clearSessionHookState */
+export declare function clearDirtyPaths(stateDir: string | undefined): HookState;