kibi-opencode 0.5.2 → 0.5.4

package/README.md

@@ -150,6 +150,19 @@ Config files (project overrides global):
 
 Per ADR-016, prompt text injection uses only `experimental.chat.system.transform`. The `chat.params` hook is reserved for model option enrichment (temperature, topP, etc.) and never carries prompt text.
 
+### Logging Policy
+
+The plugin follows a **silent-except-errors** policy for terminal output:
+
+| Channel | Terminal | Structured log |
+|---------|----------|---------------|
+| Normal operation (sync success, guidance injection, session summaries) | No | Yes, via `client.app.log()` |
+| Error-class events (bootstrap-needed, sync/check failure, hook/init failure) | Yes, via `console.error` | Yes, via `client.app.log()` |
+
+Routine diagnostics route through [`client.app.log()`](https://opencode.ai/docs/plugins/) and never appear in the terminal. Only error-class events break terminal silence. This keeps the developer's workspace clean while preserving full visibility in structured logs for debugging.
+
+The `experimental.chat.system.transform` hook handles prompt injection (see [Hook Policy](#hook-policy)). The `chat.params` hook is compatibility-only and never carries prompt text.
+
 ### Hook Modes
 
 - `auto`: Use `experimental.chat.system.transform` (primary); `chat.params` is a no-op registration for host compatibility
@@ -190,6 +203,22 @@ Disable specific features while keeping others:
 
 This repository's OpenCode setup dogfoods local built artifacts. `opencode.json` starts the local `kibi-mcp` server, `.opencode/plugins/kibi.ts` re-exports `packages/opencode/dist/index.js`, and the published npm package (`kibi-opencode`) remains the distribution artifact for external consumers. See [DEV.md](DEV.md) for the repo-local workflow and rebuild rule.
 
+## Troubleshooting
+
+If you see a false "workspace needs Kibi bootstrap" warning even though your workspace is already initialized with `.kb/config.json` pointing at relocated `kibi-docs/*` paths, this indicates a stale plugin cache. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
+
+## Architecture
+
+This is a thin bridge layer per ADR-016:
+
+XY|This repository's OpenCode setup dogfoods local built artifacts. `opencode.json` starts the local `kibi-mcp` server, `.opencode/plugins/kibi.ts` re-exports `packages/opencode/dist/index.js`, and the published npm package (`kibi-opencode`) remains the distribution artifact for external consumers. See [DEV.md](DEV.md) for the repo-local workflow and rebuild rule.
+
+## Troubleshooting
+
+If you see a false "workspace needs Kibi bootstrap" warning even though your workspace is already initialized with `.kb/config.json` pointing at relocated `kibi-docs/*` paths, this indicates a stale plugin cache. See [the main troubleshooting docs](../../docs/troubleshooting.md#opencode-shows-workspace-needs-kibi-bootstrap-before-the-tui) for recovery steps.
+
+## Architecture
+
 ## Architecture
 
 This is a thin bridge layer per ADR-016:

package/dist/file-filter.d.ts

@@ -8,5 +8,15 @@ export declare function loadKbSyncPaths(cwd?: string): {
     facts: string;
     symbols: string;
 };
+export interface KbExistenceTarget {
+    key: string;
+    relativePath: string;
+    kind: "dir" | "file";
+}
+export declare function getKbExistenceTargets(cwd?: string): KbExistenceTarget[];
+/** Strip the first path segment containing a glob character and everything
+ *  after it, returning the directory root to check with existsSync.
+ */
+export declare function stripToRoot(p: string): string;
 export declare function shouldHandleFile(filePath: string, cwd?: string): boolean;
 export default shouldHandleFile;

package/dist/file-filter.js

@@ -22,16 +22,17 @@ catch {
         },
     };
 }
-// Local copy of DEFAULT_SYNC_PATHS to avoid cross-package TS rootDir issues
+// Local copy of DEFAULT_CONFIG.paths to avoid cross-package TS rootDir issues.
+// Must stay in sync with DEFAULT_CONFIG.paths in packages/cli/src/utils/config.ts.
 const DEFAULT_SYNC_PATHS = {
-    requirements: "requirements/**/*.md",
-    scenarios: "scenarios/**/*.md",
-    tests: "tests/**/*.md",
-    adr: "adr/**/*.md",
-    flags: "flags/**/*.md",
-    events: "events/**/*.md",
-    facts: "facts/**/*.md",
-    symbols: "symbols.yaml",
+    requirements: "documentation/requirements/**/*.md",
+    scenarios: "documentation/scenarios/**/*.md",
+    tests: "documentation/tests/**/*.md",
+    adr: "documentation/adr/**/*.md",
+    flags: "documentation/flags/**/*.md",
+    events: "documentation/events/**/*.md",
+    facts: "documentation/facts/**/*.md",
+    symbols: "documentation/symbols.yaml",
 };
 function loadSyncConfigLocal(cwd = process.cwd()) {
     const configPath = path.join(cwd, ".kb/config.json");
@@ -56,6 +57,53 @@ export function loadKbSyncPaths(cwd = process.cwd()) {
     const cfg = loadSyncConfigLocal(cwd);
     return cfg.paths ?? DEFAULT_SYNC_PATHS;
 }
+// implements REQ-opencode-kibi-plugin-v1
+export function getKbExistenceTargets(cwd = process.cwd()) {
+    const paths = loadKbSyncPaths(cwd);
+    const keys = [
+        "requirements",
+        "scenarios",
+        "tests",
+        "adr",
+        "flags",
+        "events",
+        "facts",
+        "symbols",
+    ];
+    const targets = [];
+    for (const key of keys) {
+        const raw = paths[key];
+        if (!raw)
+            continue;
+        const isFile = raw.endsWith(".yaml") || raw.endsWith(".yml");
+        if (isFile) {
+            targets.push({ key, relativePath: raw, kind: "file" });
+        }
+        else {
+            // Contract: trim trailing slashes → normalizePattern → strip first glob segment
+            const trimmed = raw.replace(/\/+$/, "");
+            const normalized = normalizePattern(trimmed);
+            const relativePath = normalized ? stripToRoot(normalized) : ".";
+            targets.push({ key, relativePath, kind: "dir" });
+        }
+    }
+    return targets;
+}
+// implements REQ-opencode-kibi-plugin-v1
+/** Strip the first path segment containing a glob character and everything
+ *  after it, returning the directory root to check with existsSync.
+ */
+export function stripToRoot(p) {
+    const segments = p.split("/");
+    const rootSegments = [];
+    for (const seg of segments) {
+        if (seg.includes("*") || seg.includes("?") || seg.includes("["))
+            break;
+        rootSegments.push(seg);
+    }
+    const result = rootSegments.join("/");
+    return result || ".";
+}
 function normalizePattern(p) {
     if (!p)
         return null;

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 export interface PluginInput {
     worktree: string;
     directory: string;
+    client?: {
+        app: {
+            log: (payload: Record<string, unknown>) => Promise<void>;
+        };
+    };
 }
 interface OpencodeEventPayload {
     type: string;

package/dist/index.js

@@ -4,7 +4,7 @@ import * as config from "./config.js";
 import * as fileFilter from "./file-filter.js";
 import * as logger from "./logger.js";
 import { analyzePath } from "./path-kind.js";
-import { injectPrompt } from "./prompt.js";
+import { buildPrompt, SENTINEL } from "./prompt.js";
 import { isMustPriorityRequirement } from "./requirement-doc.js";
 import { createSyncScheduler } from "./scheduler.js";
 import { getSessionTracker } from "./session-tracker.js";
@@ -56,9 +56,15 @@ const kibiOpencodePlugin = async (input) => {
         return {};
     }
     // Check workspace health for bootstrap nudges
+    // Reset the logger client first to avoid leaking a previous invocation's
+    // client into this instance, then set the new one if provided.
+    logger.resetClient();
+    if (input.client) {
+        logger.setClient(input.client);
+    }
     const workspaceHealth = checkWorkspaceHealth(input.worktree);
     if (workspaceHealth.needsBootstrap) {
-        logger.warn("kibi-opencode: workspace needs Kibi bootstrap");
+        logger.error("kibi-opencode: workspace needs Kibi bootstrap");
         getSessionTracker().recordWarning("bootstrap-needed", input.worktree, "Workspace missing Kibi bootstrap");
     }
     // Log session summary periodically (gated on config)
@@ -131,7 +137,7 @@ const kibiOpencodePlugin = async (input) => {
                         : suggestion.suggestionType === "adr"
                             ? "long-comment-missed-adr"
                             : "missing-traceability";
-                    logger.info(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${filePath}`);
+                    logger.warn(`kibi-opencode: detected durable ${suggestion.suggestionType} knowledge in ${filePath}`);
                     getSessionTracker().recordWarning(warningCategory, filePath, `Consider routing this ${suggestion.suggestionType} knowledge to Kibi instead of inline comments: ${suggestion.reasoning}`);
                 }
             }
@@ -172,15 +178,23 @@ const kibiOpencodePlugin = async (input) => {
         const hookMode = cfg.prompt.hookMode;
         if (hookMode === "system-transform" || hookMode === "auto") {
             hooks["experimental.chat.system.transform"] = async (_input, output) => {
-                const currentSystem = output.system.join("\n");
-                const injected = injectPrompt(currentSystem, cfg, {
+                // Skip if sentinel already present in any existing entry
+                if (output.system.some((entry) => entry.includes(SENTINEL))) {
+                    return;
+                }
+                // Build only the guidance block and append it; existing entries are preserved
+                const guidance = buildPrompt({
                     recentEdits,
                     workspaceHealth,
                     hasRecentKbEdit,
                     recentCommentSuggestion,
                 });
-                output.system.length = 0;
-                output.system.push(injected);
+                const last = output.system.length > 0
+                    ? output.system[output.system.length - 1]
+                    : undefined;
+                if (last !== guidance) {
+                    output.system.push(guidance);
+                }
             };
         }
         if (hookMode === "chat-params" || hookMode === "auto") {

package/dist/logger.d.ts

@@ -1,3 +1,10 @@
+export interface PluginClient {
+    app: {
+        log: (payload: Record<string, unknown>) => Promise<void>;
+    };
+}
+export declare function setClient(c: PluginClient): void;
+export declare function resetClient(): void;
 export declare function info(msg: string): void;
 export declare function warn(msg: string): void;
 export declare function error(msg: string): void;

package/dist/logger.js

@@ -1,11 +1,59 @@
 // implements REQ-opencode-kibi-plugin-v1
+let client = null;
+// implements REQ-opencode-kibi-plugin-v1
+export function setClient(c) {
+    client = c;
+}
+// implements REQ-opencode-kibi-plugin-v1
+export function resetClient() {
+    client = null;
+}
+// implements REQ-opencode-kibi-plugin-v1
 export function info(msg) {
-    console.log("[kibi-opencode]", msg);
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "info",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+        return;
+    }
+    // Fallback when no client is available (e.g. during tests or early init)
 }
+// implements REQ-opencode-kibi-plugin-v1
 export function warn(msg) {
-    console.warn("[kibi-opencode]", msg);
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "warn",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+        return;
+    }
+    // Fallback when no client is available
 }
 // implements REQ-opencode-kibi-plugin-v1
 export function error(msg) {
+    // Always emit to console for user visibility
     console.error("[kibi-opencode]", msg);
+    // Also emit to structured logs if client is available
+    if (client) {
+        void client.app
+            .log({
+            body: {
+                service: "kibi-opencode",
+                level: "error",
+                message: msg,
+            },
+        })
+            .catch(console.error);
+    }
 }

package/dist/scheduler.js

@@ -114,7 +114,7 @@ class WorktreeSyncScheduler {
                 const checkResult = await this.runCheck(this.worktree, checkRules);
                 checkExitCode = checkResult.exitCode;
                 if (checkExitCode !== 0) {
-                    logger.warn(`check.failed ${JSON.stringify({ rules: checkRules, exitCode: checkExitCode })}`);
+                    logger.error(`check.failed ${JSON.stringify({ rules: checkRules, exitCode: checkExitCode })}`);
                 }
                 else {
                     logger.info(`check.succeeded ${JSON.stringify({ rules: checkRules })}`);
@@ -157,7 +157,7 @@ class WorktreeSyncScheduler {
             logger.info(`sync.succeeded ${JSON.stringify(meta)}`);
         }
         else {
-            logger.warn(`sync.failed ${JSON.stringify(meta)}`);
+            logger.error(`sync.failed ${JSON.stringify(meta)}`);
         }
         this.onRunComplete?.(meta);
     }

package/dist/workspace-health.js

@@ -1,7 +1,9 @@
 import fs from "node:fs";
 // implements REQ-opencode-kibi-plugin-v1
 import path from "node:path";
+import { getKbExistenceTargets } from "./file-filter.js";
 const KB_CONFIG_FILE = ".kb/config.json";
+// Fallback defaults used when .kb/config.json does not exist
 const KIBI_DOC_DIRS = [
     "documentation/requirements",
     "documentation/scenarios",
@@ -12,6 +14,7 @@ const KIBI_DOC_DIRS = [
     "documentation/facts",
     "documentation/symbols.yaml",
 ];
+// implements REQ-opencode-kibi-plugin-v1
 /**
  * Analyze workspace health for Kibi bootstrap and initialization.
  */
@@ -19,10 +22,43 @@ export function checkWorkspaceHealth(cwd) {
     const configPath = path.join(cwd, KB_CONFIG_FILE);
     const missingConfig = !fs.existsSync(configPath);
     const missingDocDirs = [];
-    for (const docDir of KIBI_DOC_DIRS) {
-        const fullPath = path.join(cwd, docDir);
-        if (!fs.existsSync(fullPath)) {
-            missingDocDirs.push(docDir);
+    if (missingConfig) {
+        // No config file: fall back to hardcoded defaults
+        for (const docDir of KIBI_DOC_DIRS) {
+            const fullPath = path.join(cwd, docDir);
+            if (!fs.existsSync(fullPath)) {
+                missingDocDirs.push(docDir);
+            }
+        }
+    }
+    else {
+        // Config exists: check if user specified custom paths
+        let hasUserPaths = false;
+        try {
+            const raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+            hasUserPaths = Boolean(raw && raw.paths);
+        }
+        catch {
+            hasUserPaths = false;
+        }
+        if (hasUserPaths) {
+            // User has custom paths: resolve targets dynamically
+            const targets = getKbExistenceTargets(cwd);
+            for (const target of targets) {
+                const fullPath = path.join(cwd, target.relativePath);
+                if (!fs.existsSync(fullPath)) {
+                    missingDocDirs.push(target.relativePath);
+                }
+            }
+        }
+        else {
+            // Config exists but no custom paths: use hardcoded defaults
+            for (const docDir of KIBI_DOC_DIRS) {
+                const fullPath = path.join(cwd, docDir);
+                if (!fs.existsSync(fullPath)) {
+                    missingDocDirs.push(docDir);
+                }
+            }
         }
     }
     // Check for any evidence of Kibi usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-opencode",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Kibi OpenCode plugin - thin adapter to integrate Kibi with OpenCode sessions",
   "type": "module",
   "main": "dist/index.js",