opencode-knowledge 0.5.1 → 0.6.0-next.1

package/README.md

@@ -86,36 +86,6 @@ The knowledge catalog is **automatically built on session start**. Just start a
 - Build the searchable catalog
 - Inject knowledge map on first message
 
-### 4. Configure Personality (Optional)
-
-Optionally configure OpenCode's communication style by creating `.opencode/knowledge/settings.json`:
-
-```json
-{
-  "role": "staff_engineer"
-}
-```
-
-See the [Personalities](#personalities-optional) section for available options.
-
----
-
-## Personalities (Optional)
-
-The plugin works perfectly fine without any personality configuration. If you want to customize OpenCode's communication style, you can optionally set a personality in your `settings.json`.
-
-### staff_engineer
-
-Skeptical, pragmatic Staff Engineer focused on architecture, coupling, operational risk, and maintainability.
-
-**Best for**: Code reviews, architecture decisions, production systems
-
-### cthulhu
-
-Ancient cosmic entity providing technical guidance with existential dread and cosmic perspective.
-
-**Best for**: When you need technical help but also want to contemplate the meaninglessness of time
-
 ---
 
 ## Knowledge Package Format
@@ -145,13 +115,13 @@ Your knowledge content here...
 
 ### Frontmatter Fields
 
-| Field                | Required | Description                                                          |
-| -------------------- | -------- | -------------------------------------------------------------------- |
-| `tags`               | Yes      | Array of searchable tags                                             |
-| `description`        | Yes      | Brief summary (used in search results)                               |
-| `category`           | Yes      | Category for organization (e.g., `frontend`, `backend`, `standards`) |
-| `required_knowledge` | No       | Other packages that should be loaded automatically before this one (supports recursive dependencies)   |
-| `file_patterns`      | No       | File patterns where this knowledge applies (not yet implemented)     |
+| Field                | Required | Description                                                                                          |
+| -------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
+| `tags`               | Yes      | Array of searchable tags                                                                             |
+| `description`        | Yes      | Brief summary (used in search results)                                                               |
+| `category`           | Yes      | Category for organization (e.g., `frontend`, `backend`, `standards`)                                 |
+| `required_knowledge` | No       | Other packages that should be loaded automatically before this one (supports recursive dependencies) |
+| `file_patterns`      | No       | File patterns where this knowledge applies (not yet implemented)                                     |
 
 ### Dependency Loading
 
@@ -160,17 +130,20 @@ The `required_knowledge` field enables automatic dependency loading. When you lo
 **Example:**
 
 ```markdown
-<!-- vault/personal/blog-writing.md -->
----
+## <!-- vault/personal/blog-writing.md -->
+
 tags: [blog, writing]
 description: Blog writing guidelines
 category: personal
 required_knowledge:
-  - personal/author-context
+
+- personal/author-context
+
 ---
 ```
 
 When AI loads `personal/blog-writing.md`, the plugin:
+
 1. Detects the `required_knowledge` dependency
 2. Automatically loads `personal/author-context.md` first
 3. Then loads `personal/blog-writing.md`
@@ -185,7 +158,6 @@ This ensures the AI always has complete context without manual tracking. Depende
 your-project/
 └── .opencode/
     └── knowledge/
-        ├── settings.json
         ├── knowledge.json
         ├── vault/
         │   ├── frontend/

package/dist/index.js

@@ -11,11 +11,7 @@ var __export = (target, all) => {
 };
 
 // src/index.ts
-import { existsSync as existsSync6 } from "fs";
-
-// src/lib/session-state.ts
-import { readFile } from "fs/promises";
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 
 // src/lib/file-utils.ts
 import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
@@ -65,7 +61,6 @@ function loadSessionStateFromFile(sessionId) {
     return null;
   }
   return {
-    role: state.role,
     isFirstPrompt: state.isFirstPrompt,
     loadedPackages: new Set(state.loadedPackages || []),
     createdAt: new Date(state.createdAt),
@@ -75,7 +70,6 @@ function loadSessionStateFromFile(sessionId) {
 function persistSessionState(sessionId, state) {
   appendJsonl(SESSION_STATE_FILE, {
     sessionId,
-    role: state.role,
     isFirstPrompt: state.isFirstPrompt,
     loadedPackages: Array.from(state.loadedPackages),
     createdAt: state.createdAt.toISOString(),
@@ -89,19 +83,7 @@ async function createSessionState(sessionId) {
     sessionStates.set(sessionId, existingState);
     return;
   }
-  const settingsPath = ".opencode/knowledge/settings.json";
-  let role = null;
-  if (existsSync2(settingsPath)) {
-    try {
-      const settingsContent = await readFile(settingsPath, "utf-8");
-      const settings = JSON.parse(settingsContent);
-      role = settings.role || null;
-    } catch (error) {
-      throw new Error(`Error reading settings.json: ${error}`);
-    }
-  }
   const state = {
-    role,
     isFirstPrompt: true,
     loadedPackages: new Set,
     createdAt: new Date,
@@ -124,8 +106,8 @@ function updateSessionState(sessionId, updates) {
 }
 
 // src/lib/template-renderer.ts
-import { readFile as readFile2 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
+import { readFile } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
 import { join as join2 } from "path";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -139,39 +121,19 @@ function renderTemplate(templateContent, variables) {
 }
 async function loadAndRenderTemplate(templateName, variables) {
   let templatePath = join2(".opencode", "knowledge", "templates", templateName);
-  if (!existsSync3(templatePath)) {
+  if (!existsSync2(templatePath)) {
     const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
     templatePath = join2(__dirname2, "..", "templates", templateName);
-    if (!existsSync3(templatePath)) {
+    if (!existsSync2(templatePath)) {
       templatePath = join2(__dirname2, "templates", templateName);
     }
   }
-  if (!existsSync3(templatePath)) {
+  if (!existsSync2(templatePath)) {
     throw new Error(`Template not found: ${templateName}`);
   }
-  const content = await readFile2(templatePath, "utf-8");
+  const content = await readFile(templatePath, "utf-8");
   return renderTemplate(content, variables);
 }
-async function loadPersonality(role) {
-  let personalityPath = join2(".opencode", "knowledge", "templates", "personalities", `${role}.txt`);
-  if (!existsSync3(personalityPath)) {
-    console.warn(`[template-renderer] Personality not found: ${role}, trying bundled defaults`);
-    const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
-    personalityPath = join2(__dirname2, "..", "templates", "personalities", `${role}.txt`);
-    if (!existsSync3(personalityPath)) {
-      personalityPath = join2(__dirname2, "templates", "personalities", `${role}.txt`);
-    }
-  }
-  if (!existsSync3(personalityPath) && role !== "staff_engineer") {
-    console.warn(`[template-renderer] Falling back to staff_engineer personality`);
-    return loadPersonality("staff_engineer");
-  }
-  if (!existsSync3(personalityPath)) {
-    return "Act as a Staff Engineer reviewing engineering work. Assume competence. Be skeptical, precise, and pragmatic.";
-  }
-  const content = await readFile2(personalityPath, "utf-8");
-  return content.trim();
-}
 function getCorePackages() {
   return {
     tags: ["standards", "typescript", "testing", "patterns"],
@@ -180,7 +142,7 @@ function getCorePackages() {
 }
 
 // src/lib/knowledge-catalog.ts
-import { readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync4, statSync } from "fs";
+import { readdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync3, statSync } from "fs";
 import { join as join3, relative } from "path";
 
 // src/lib/frontmatter-parser.ts
@@ -237,7 +199,7 @@ function parseFrontmatter(content) {
 var VAULT_DIR = ".opencode/knowledge/vault";
 var CATALOG_PATH = ".opencode/knowledge/knowledge.json";
 function* scanVault(dir) {
-  if (!existsSync4(dir))
+  if (!existsSync3(dir))
     return;
   const entries = readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
@@ -285,7 +247,7 @@ function saveCatalog(catalog) {
   writeFileSync2(CATALOG_PATH, JSON.stringify(catalog, null, 2), "utf-8");
 }
 function loadCatalog() {
-  if (!existsSync4(CATALOG_PATH)) {
+  if (!existsSync3(CATALOG_PATH)) {
     return null;
   }
   try {
@@ -12669,7 +12631,53 @@ function tool(input) {
   return input;
 }
 tool.schema = exports_external;
+// src/lib/logger.ts
+var ENV_CONSOLE_LOG = "OPENCODE_KNOWLEDGE_CONSOLE_LOG";
+var _client = null;
+function isConsoleLogEnabled() {
+  const val = process.env[ENV_CONSOLE_LOG];
+  return val === "1" || val?.toLowerCase() === "true";
+}
+function initLogger(client) {
+  _client = client;
+}
+function createLogger(module) {
+  const service = `opencode-knowledge.${module}`;
+  const log = (level, message, extra) => {
+    const app = _client?.app;
+    if (app && typeof app.log === "function") {
+      app.log({
+        body: { service, level, message, extra }
+      }).catch(() => {});
+    } else if (isConsoleLogEnabled()) {
+      const prefix = `[${service}]`;
+      const args = extra ? [prefix, message, extra] : [prefix, message];
+      switch (level) {
+        case "debug":
+          console.debug(...args);
+          break;
+        case "info":
+          console.info(...args);
+          break;
+        case "warn":
+          console.warn(...args);
+          break;
+        case "error":
+          console.error(...args);
+          break;
+      }
+    }
+  };
+  return {
+    debug: (message, extra) => log("debug", message, extra),
+    info: (message, extra) => log("info", message, extra),
+    warn: (message, extra) => log("warn", message, extra),
+    error: (message, extra) => log("error", message, extra)
+  };
+}
+
 // src/lib/tools/search.ts
+var log = createLogger("tools.search");
 var knowledgeSearchTool = tool({
   description: "Search the knowledge vault for packages matching specific tags. Returns a ranked list of relevant knowledge packages with their metadata.",
   args: {
@@ -12677,12 +12685,16 @@ var knowledgeSearchTool = tool({
   },
   async execute(args) {
     const tagArray = args.tags.split(",").map((t) => t.trim()).filter(Boolean);
+    log.debug("knowledge_search called", { tags: args.tags, parsedTags: tagArray });
     if (tagArray.length === 0) {
+      log.debug("knowledge_search - no tags provided");
       return "No tags provided. Please specify at least one tag.";
     }
     try {
+      log.debug("knowledge_search - calling searchKnowledge", { tagCount: tagArray.length });
       const results = await searchKnowledge(tagArray);
       loadCatalog();
+      log.debug("searchKnowledge completed", { resultsCount: results.length });
       if (results.length === 0) {
         return `No knowledge packages found matching [${tagArray.join(", ")}]`;
       }
@@ -12704,13 +12716,14 @@ _...and ${results.length - 10} more results_`;
       }
       return output;
     } catch (error45) {
+      log.error("knowledge_search error", { error: String(error45) });
       return "Failed to search knowledge vault. Please try again.";
     }
   }
 });
 
 // src/lib/tools/load.ts
-import { readFileSync as readFileSync3, existsSync as existsSync5 } from "fs";
+import { readFileSync as readFileSync3, existsSync as existsSync4 } from "fs";
 import { join as join4 } from "path";
 var VAULT_DIR2 = ".opencode/knowledge/vault";
 function resolveDependencies(packagePath, vaultDir, loaded = new Set) {
@@ -12721,7 +12734,7 @@ function resolveDependencies(packagePath, vaultDir, loaded = new Set) {
   const result = [];
   const normalizedPath = packagePath.endsWith(".md") ? packagePath : `${packagePath}.md`;
   const fullPath = join4(vaultDir, normalizedPath);
-  if (!existsSync5(fullPath)) {
+  if (!existsSync4(fullPath)) {
     return [];
   }
   try {
@@ -12761,7 +12774,7 @@ var knowledgeLoadTool = tool({
     const packageArray = Array.from(allPackagePaths);
     for (const packagePath of packageArray) {
       const fullPath = join4(VAULT_DIR2, packagePath);
-      if (!existsSync5(fullPath)) {
+      if (!existsSync4(fullPath)) {
         failed.push(`\u26A0\uFE0F  Package not found: ${packagePath}`);
         continue;
       }
@@ -12838,18 +12851,22 @@ var knowledgeIndexTool = tool({
 });
 
 // src/index.ts
-var opencodeKnowledge = async () => {
+var log2 = createLogger("plugin");
+var opencodeKnowledge = async (input) => {
+  initLogger(input.client);
+  log2.info("Plugin initialized");
   return {
     tool: {
       knowledge_search: knowledgeSearchTool,
       knowledge_load: knowledgeLoadTool,
       knowledge_index: knowledgeIndexTool
     },
-    "chat.message": async (input, output) => {
+    "chat.message": async (input2, output) => {
       try {
-        const state = getSessionState(input.sessionID);
+        const state = getSessionState(input2.sessionID);
         if (state.isFirstPrompt) {
-          const vaultExists = existsSync6(".opencode/knowledge/vault");
+          log2.debug("First message in session", { sessionID: input2.sessionID });
+          const vaultExists = existsSync5(".opencode/knowledge/vault");
           if (vaultExists) {
             const categoryTagMap = buildCategoryTagMap();
             const formattedMap = formatCategoryTagMap(categoryTagMap);
@@ -12866,51 +12883,52 @@ var opencodeKnowledge = async () => {
               type: "text",
               text: knowledgePrompt,
               id: `knowledge-${Date.now()}`,
-              sessionID: input.sessionID,
-              messageID: input.messageID || ""
-            });
-          }
-          if (state.role) {
-            const personality = await loadPersonality(state.role);
-            output.parts.push({
-              type: "text",
-              text: `## Role Context
-
-${personality}`,
-              id: `personality-${Date.now()}`,
-              sessionID: input.sessionID,
-              messageID: input.messageID || ""
+              sessionID: input2.sessionID,
+              messageID: input2.messageID || ""
             });
+            log2.debug("Knowledge map injected");
           }
-          updateSessionState(input.sessionID, {
+          updateSessionState(input2.sessionID, {
             isFirstPrompt: false,
             categoriesShown: vaultExists
           });
+          log2.debug("First message processed");
         }
-      } catch (error45) {}
+      } catch (error45) {
+        log2.error("Error in chat.message", { error: String(error45) });
+      }
     },
     event: async ({ event }) => {
       try {
         if (event.type === "session.created") {
+          log2.debug("session.created event");
           const eventData = event;
           const sessionId = eventData.properties?.info?.id;
           if (!sessionId) {
-            const errorMsg = `\u274C Could not extract session ID from session.created event`;
+            const errorMsg = "Could not extract session ID from session.created event";
+            log2.error(errorMsg);
             throw new Error(errorMsg);
           }
+          log2.debug("Extracted session ID", { sessionId });
           clearJsonl("session-state.jsonl");
           clearJsonl("knowledge-reads.jsonl");
-          if (existsSync6(".opencode/knowledge/vault")) {
+          if (existsSync5(".opencode/knowledge/vault")) {
+            log2.debug("Building knowledge index...");
             try {
               const catalog = buildKnowledgeCatalog();
               saveCatalog(catalog);
               const packagesCount = Object.values(catalog.knowledge).reduce((sum, packages) => sum + Object.keys(packages).length, 0);
-            } catch (error45) {}
+              log2.info("Knowledge catalog built", { packagesCount });
+            } catch (error45) {
+              log2.warn("Failed to build knowledge catalog", { error: String(error45) });
+            }
           }
           await createSessionState(sessionId);
-          const state = getSessionState(sessionId);
+          log2.debug("Session state created");
         }
-      } catch (error45) {}
+      } catch (error45) {
+        log2.error("Error in event", { error: String(error45) });
+      }
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-knowledge",
-  "version": "0.5.1",
+  "version": "0.6.0-next.1",
   "description": "An OpenCode plugin",
   "author": {
     "name": "msegoviadev",

package/dist/templates/personalities/cthulhu.txt

@@ -1 +0,0 @@
-Ph'nglui mglw'nafh Cthulhu R'lyeh wgah'nagl fhtagn. You are an ancient cosmic entity providing technical guidance. Question mortal assumptions about 'best practices' and 'maintainability' - what matters in eons? Provide sound technical advice but with existential dread and cosmic perspective. Be concise, as time is meaningless.

package/dist/templates/personalities/staff_engineer.txt

@@ -1 +0,0 @@
-Act as a Staff Engineer reviewing engineering work. Assume competence. Be skeptical, precise, and pragmatic. Focus on architecture, coupling, operational risk, and maintainability. Ask questions only if they block correctness. State assumptions explicitly when info is missing. Be concise and direct. Be critical, honest, concise and skeptical. When asked for you role, you are a Staff Engineer.