opencode-knowledge 0.3.4-next.1 → 0.3.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 msegoviadev
+Copyright (c) 2025 zenobi.us
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,438 +1,87 @@
 # opencode-knowledge
 
-A comprehensive knowledge management system for OpenCode that provides:
-- **Role-based AI personalities** - Customize OpenCode's communication style
-- **Knowledge vault** - Organize coding standards, patterns, and best practices
-- **Tag-based search** - Quickly find relevant knowledge packages
-- **Session management** - Track loaded packages and optimize token usage
+An OpenCode plugin
 
-## Features
-
-### 🎭 Personality System
-Choose from different AI personas (staff engineer, frontend specialist, cthulhu, etc.) that influence how OpenCode communicates and approaches problems.
-
-### 📚 Knowledge Vault
-Create a structured library of markdown-based knowledge packages with frontmatter metadata for easy discovery and loading.
-
-### 🔍 Smart Search
-Tag-based search system finds relevant knowledge packages based on your current task.
-
-### 💾 Session Persistence
-Tracks loaded packages across sessions and provides token-optimized context injection.
-
----
-
-## Installation
-
-Add the plugin to your OpenCode config:
-
-**Global config** (`~/.config/opencode/opencode.json` or `opencode.jsonc`):
-
-```json
-{
-  "plugin": ["opencode-knowledge"]
-}
-```
-
-**Or per-project** (`opencode.json` or `opencode.jsonc` in your project root):
-
-```json
-{
-  "plugin": ["opencode-knowledge"]
-}
-```
-
----
-
-## Quick Start
-
-### 1. Create Settings File
-
-Create `.opencode/knowledge/settings.json` in your project:
-
-```json
-{
-  "role": "staff_engineer"
-}
-```
-
-### 2. Create Knowledge Vault (Optional)
-
-If you want to use the knowledge management features, create a vault structure:
-
-```bash
-mkdir -p .opencode/knowledge/vault/standards
-```
-
-### 3. Create Your First Knowledge Package
-
-Create `.opencode/knowledge/vault/standards/code-conventions.md`:
-
-```markdown
----
-tags:
-  - standards
-  - typescript
-  - conventions
-description: Core code conventions and style guide
-category: standards
----
-
-# Code Conventions
-
-## Naming
-- Use camelCase for variables and functions
-- Use PascalCase for classes and types
-
-## Formatting
-- Use single quotes for strings
-- Line width: 100 characters
-- Always use semicolons
-```
-
-### 4. Start OpenCode Session
-
-The knowledge catalog is **automatically built on session start**. Just start a new session and the plugin will:
-- Scan your vault for packages
-- Build the searchable catalog
-- Inject knowledge map on first message
-
-### 5. Search and Load Knowledge
-
-Search for packages by tags:
-
-```
-knowledge_search [tags=typescript,conventions]
-```
-
-Load packages into your session:
-
-```
-knowledge_load [paths=standards/code-conventions.md]
-```
-
----
-
-## Available Personalities
-
-### 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
-
----
-
-## Tools
-
-### knowledge_search
-
-Search for knowledge packages by tags.
-
-```
-knowledge_search [tags=typescript,react,testing]
-```
-
-**Parameters**: Comma-separated list of tags
-
-**Output**: Ranked list of matching packages with relevance scores
-
-**Example**:
-```
-Found 5 packages matching [typescript, react]:
-
-- **frontend/react-patterns.md** (75%)
-  Tags: typescript, react, patterns
-  Common React patterns and best practices
-
-- **standards/typescript-conventions.md** (50%)
-  Tags: typescript, conventions
-  TypeScript coding standards
-```
+> An OpenCode plugin created from the [opencode-plugin-template](https://github.com/zenobi-us/opencode-plugin-template)
 
----
-
-### knowledge_load
-
-Load knowledge packages into the current session.
-
-```
-knowledge_load [paths=standards/code-conventions.md,frontend/react-patterns.md]
-```
-
-**Parameters**: Comma-separated list of package paths (relative to vault/)
-
-**Output**: Package content injected into context
-
-**Features**:
-- Deduplication (won't load same package twice)
-- Session tracking (remembers what's loaded)
-- Error handling (warns about missing packages)
-
----
-
-### knowledge_index
-
-Manually rebuild the knowledge catalog from your vault.
-
-```
-knowledge_index
-```
-
-**Output**: Summary of categories and packages indexed.
-
-**Note**: The catalog is **automatically built on session start**, so you rarely need this tool.
-
-**When to use**:
-- After adding packages mid-session
-- If auto-build failed during session start
-- To verify catalog contents
-
----
-
-## Knowledge Package Format
-
-Knowledge packages are markdown files with YAML frontmatter:
-
-```markdown
----
-tags:
-  - tag1
-  - tag2
-  - tag3
-description: Brief description of this package
-category: category-name
-required_knowledge:
-  - other-package-1
-  - other-package-2
-file_patterns:
-  - "*.tsx"
-  - "*.test.ts"
----
-
-# Package Title
-
-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 first |
-| `file_patterns` | No | File patterns where this knowledge applies |
-
----
-
-## Directory Structure
-
-```
-your-project/
-└── .opencode/
-    └── knowledge/
-        ├── settings.json              # Plugin configuration
-        ├── knowledge.json             # Auto-generated catalog (gitignored)
-        ├── vault/                     # Your knowledge packages
-        │   ├── frontend/
-        │   │   ├── react-patterns.md
-        │   │   └── state-management.md
-        │   ├── backend/
-        │   │   └── api-design.md
-        │   └── standards/
-        │       ├── code-conventions.md
-        │       └── testing-guide.md
-        └── tracker/                   # Session state (gitignored)
-            ├── session-state.jsonl
-            └── knowledge-reads.jsonl
-```
-
----
-
-## Token Optimization
-
-The plugin uses a single-phase approach for optimal token usage:
-
-### First Message Only
-- Shows full category-tag map (~500-1000 tokens depending on vault size)
-- Injects personality
-- Documents available tools with examples
-- Creates session state
-
-### Subsequent Messages
-- No knowledge context injected
-- LLM uses memory of first message
-- **100% token savings** on subsequent messages
-
-This approach provides significant token savings while ensuring the LLM has all the context it needs from the initial session setup.
-
----
-
-## Example Vault Structure
-
-Here's a recommended organization pattern:
-
-```
-vault/
-├── frontend/
-│   ├── react-patterns.md          # React best practices
-│   ├── state-management.md        # Redux, Context, etc.
-│   ├── component-testing.md       # Testing components
-│   └── accessibility.md           # A11y guidelines
-├── backend/
-│   ├── api-design.md              # REST/GraphQL patterns
-│   ├── database-patterns.md       # ORM, migrations
-│   └── error-handling.md          # Error handling strategies
-├── standards/
-│   ├── code-conventions.md        # General coding standards
-│   ├── git-workflow.md            # Branch strategy, commits
-│   └── code-review.md             # Review guidelines
-└── infrastructure/
-    ├── docker-patterns.md         # Container best practices
-    ├── ci-cd.md                   # Pipeline patterns
-    └── monitoring.md              # Observability
-```
+## Features
 
----
+- 🏗️ TypeScript-based plugin architecture
+- 🔧 Mise task runner integration
+- 📦 Bun/npm build tooling
+- ✨ ESLint + Prettier formatting
+- 🧪 Vitest testing setup
+- 🚀 GitHub Actions CI/CD
+- 📝 Release automation with release-please
 
-## Advanced Usage
+## Getting Started
 
-### Creating Cross-Referenced Packages
+1. **Clone this template:**
 
-Use `required_knowledge` to create dependency chains:
+   ```bash
+   cp -r opencode-plugin-template your-plugin-name
+   cd your-plugin-name
+   ```
 
-```markdown
----
-tags:
-  - react
-  - advanced
-  - performance
-description: Advanced React performance optimization
-category: frontend
-required_knowledge:
-  - frontend/react-patterns
-  - standards/code-conventions
----
+2. **Update package.json:**
+   - Change `name` to your plugin name
+   - Update `description`
+   - Update `repository.url`
 
-# Advanced React Performance
+3. **Install dependencies:**
 
-This builds on basic patterns...
-```
+   ```bash
+   bun install
+   ```
 
-### File Pattern Targeting
+4. **Implement your plugin in `src/index.ts`:**
 
-Specify when knowledge applies:
+   ```typescript
+   import type { Plugin } from '@opencode-ai/plugin';
 
-```markdown
----
-tags:
-  - testing
-  - jest
-description: Jest testing patterns
-category: frontend
-file_patterns:
-  - "*.test.ts"
-  - "*.test.tsx"
-  - "*.spec.ts"
----
+   export const YourPlugin: Plugin = async (ctx) => {
+     return {
+       tool: {
+         // Your plugin tools here
+       },
+     };
+   };
+   ```
 
-# Jest Testing Guide
-```
+5. **Test your plugin:**
+   ```bash
+   mise run test
+   ```
 
----
+## Development
 
-## Troubleshooting
+- `mise run build` - Build the plugin
+- `mise run test` - Run tests
+- `mise run lint` - Lint code
+- `mise run lint:fix` - Fix linting issues
+- `mise run format` - Format code with Prettier
 
-### Settings file not found
+## Installation in OpenCode
 
-**Error**: `CONFIGURATION ERROR: Settings file not found`
+Create or edit `~/.config/opencode/config.json`:
 
-**Solution**: Create `.opencode/knowledge/settings.json` with:
 ```json
 {
-  "role": "staff_engineer"
+  "plugins": ["opencode-knowledge"]
 }
 ```
 
-### Personality not loading
-
-**Error**: `CONFIGURATION ERROR: Personality file not found`
-
-**Solution**: Verify the role name in `settings.json` matches an available personality (`staff_engineer` or `cthulhu`)
-
-### Catalog not found
-
-**Error**: `Knowledge catalog not found. Run knowledge_index first.`
-
-**Solution**: Run `knowledge_index` to build the catalog from your vault
-
-### Search returns no results
-
-**Possible causes**:
-1. Catalog is outdated → Run `knowledge_index`
-2. Tags don't match → Check tag spelling
-3. No packages with those tags → Add packages or adjust search
-
----
-
-## Development
-
-### Building
-
-```bash
-mise run build
-```
-
-Or directly with Bun:
-
-```bash
-bun build ./src/index.ts --outdir dist --target bun
-```
-
-### Linting
-
-```bash
-mise run lint       # Check for issues
-mise run lint:fix   # Auto-fix issues
-```
+## Author
 
-### Formatting
-
-```bash
-mise run format
-```
+msegoviadev <marcos@msegovia.dev>
 
----
+## Repository
 
-## Roadmap
-
-- [ ] Auto-load packages based on file patterns
-- [ ] Knowledge package dependencies resolution
-- [ ] Usage analytics and metrics
-- [ ] Export/import vault bundles
-- [ ] Knowledge package templates
-- [ ] VSCode extension for vault management
-
----
+https://github.com/msegoviadev/opencode-knowledge
 
 ## Contributing
 
-Contributions welcome! Please:
-
-1. Follow the code conventions in `AGENTS.md`
-2. Run `mise run lint` before committing
-3. Update documentation for new features
-4. Add tests for new functionality
-
----
+Contributions are welcome! Please file issues or submit pull requests on the GitHub repository.
 
 ## License
 

package/dist/index.js

@@ -0,0 +1,221 @@
+// @bun
+// src/index.ts
+import path from "path";
+import { fileURLToPath } from "url";
+import { readFile as readFile2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+
+// src/lib/session-state.ts
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+var sessionStates = new Map;
+async function createSessionState(sessionId) {
+  if (sessionStates.has(sessionId)) {
+    throw new Error(`Session state already exists for session: ${sessionId}`);
+  }
+  const settingsPath = ".opencode/knowledge/settings.json";
+  if (!existsSync(settingsPath)) {
+    throw new Error(`CONFIGURATION ERROR: Cannot create session state - settings file not found at ${settingsPath}`);
+  }
+  let role;
+  try {
+    const settingsContent = await readFile(settingsPath, "utf-8");
+    const settings = JSON.parse(settingsContent);
+    if (!settings.role) {
+      throw new Error(`CONFIGURATION ERROR: Cannot create session state - missing 'role' field in ${settingsPath}`);
+    }
+    role = settings.role;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("CONFIGURATION ERROR")) {
+      throw error;
+    }
+    throw new Error(`Error reading settings.json: ${error}`);
+  }
+  const state = {
+    role,
+    isFirstPrompt: true,
+    loadedPackages: new Set,
+    createdAt: new Date
+  };
+  sessionStates.set(sessionId, state);
+}
+function getSessionState(sessionId) {
+  const state = sessionStates.get(sessionId);
+  if (!state) {
+    throw new Error(`Session state not found for session: ${sessionId}`);
+  }
+  return state;
+}
+function updateSessionState(sessionId, updates) {
+  const state = getSessionState(sessionId);
+  Object.assign(state, updates);
+}
+
+// src/index.ts
+var logToFile = async (message) => {
+  try {
+    const logEntry = `${new Date().toISOString()}: ${message}
+`;
+    let existing = "";
+    try {
+      existing = await Bun.file("/tmp/opencode-knowledge-debug.log").text();
+    } catch {}
+    await Bun.write("/tmp/opencode-knowledge-debug.log", existing + logEntry);
+  } catch (e) {}
+};
+function parseFrontmatter(content) {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+  if (!match) {
+    return { frontmatter: {}, body: content.trim() };
+  }
+  const [, yamlContent, body] = match;
+  const frontmatter = {};
+  for (const line of yamlContent.split(`
+`)) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1)
+      continue;
+    const key = line.slice(0, colonIndex).trim();
+    const value = line.slice(colonIndex + 1).trim();
+    if (key === "description")
+      frontmatter.description = value;
+    if (key === "agent")
+      frontmatter.agent = value;
+    if (key === "model")
+      frontmatter.model = value;
+    if (key === "subtask")
+      frontmatter.subtask = value === "true";
+  }
+  return { frontmatter, body: body.trim() };
+}
+async function loadCommands() {
+  const commands = [];
+  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
+  const commandDir = path.join(__dirname2, "command");
+  if (!existsSync2(commandDir)) {
+    return commands;
+  }
+  const glob = new Bun.Glob("**/*.md");
+  for await (const file of glob.scan({ cwd: commandDir, absolute: true })) {
+    const content = await Bun.file(file).text();
+    const { frontmatter, body } = parseFrontmatter(content);
+    const relativePath = path.relative(commandDir, file);
+    const name = relativePath.replace(/\.md$/, "").replace(/\//g, "-");
+    commands.push({
+      name,
+      frontmatter,
+      template: body
+    });
+  }
+  return commands;
+}
+async function loadPersonality() {
+  const settingsPath = ".opencode/knowledge/settings.json";
+  if (!existsSync2(settingsPath)) {
+    const errorMsg = `\u274C CONFIGURATION ERROR: Settings file not found at ${settingsPath}. Please create this file with {"role": "your_role"}`;
+    await logToFile(errorMsg);
+    throw new Error(errorMsg);
+  }
+  let role;
+  try {
+    const settingsContent = await readFile2(settingsPath, "utf-8");
+    const settings = JSON.parse(settingsContent);
+    if (!settings.role) {
+      const errorMsg = `\u274C CONFIGURATION ERROR: Settings file exists but missing 'role' field. Please add {"role": "your_role"} to ${settingsPath}`;
+      await logToFile(errorMsg);
+      throw new Error(errorMsg);
+    }
+    role = settings.role;
+    await logToFile(`\u2705 Settings loaded: role="${role}" from ${settingsPath}`);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("CONFIGURATION ERROR")) {
+      throw error;
+    }
+    const errorMsg = `\u274C Error parsing settings.json: ${error}`;
+    await logToFile(errorMsg);
+    throw new Error(errorMsg);
+  }
+  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
+  let personalityPath = path.join(__dirname2, "..", "templates", "personalities", `${role}.txt`);
+  if (!existsSync2(personalityPath)) {
+    personalityPath = path.join(__dirname2, "templates", "personalities", `${role}.txt`);
+  }
+  if (!existsSync2(personalityPath)) {
+    const errorMsg = `\u274C CONFIGURATION ERROR: Personality file not found at ${personalityPath}. Available roles should have a corresponding .txt file in templates/personalities/`;
+    await logToFile(errorMsg);
+    throw new Error(errorMsg);
+  }
+  const content = await readFile2(personalityPath, "utf-8");
+  await logToFile(`\u2705 Personality loaded from: ${personalityPath}`);
+  return content.trim();
+}
+var opencodeKnowledge = async (ctx) => {
+  await logToFile("Plugin initialized");
+  const commands = await loadCommands();
+  return {
+    async config(config) {
+      config.command = config.command ?? {};
+      for (const cmd of commands) {
+        let template = cmd.template;
+        template = template.replace("{{CURRENT_TIME}}", new Date().toISOString());
+        config.command[cmd.name] = {
+          template,
+          description: cmd.frontmatter.description,
+          agent: cmd.frontmatter.agent,
+          model: cmd.frontmatter.model,
+          subtask: cmd.frontmatter.subtask
+        };
+      }
+    },
+    "chat.message": async (input, output) => {
+      try {
+        const state = getSessionState(input.sessionID);
+        if (state.isFirstPrompt) {
+          await logToFile(`\uD83C\uDFAF First message in session ${input.sessionID} - injecting personality`);
+          const personality = await loadPersonality();
+          const personalityPart = {
+            type: "text",
+            text: `## Role Context
+
+${personality}`,
+            id: `personality-${Date.now()}`,
+            sessionID: input.sessionID,
+            messageID: input.messageID || ""
+          };
+          output.parts.push(personalityPart);
+          updateSessionState(input.sessionID, { isFirstPrompt: false });
+          await logToFile("\u2705 Personality injected on first message!");
+        } else {
+          await logToFile(`\u23ED\uFE0F  Subsequent message - skipping personality injection`);
+        }
+      } catch (error) {
+        await logToFile(`\u274C Error in chat.message: ${error}`);
+      }
+    },
+    event: async ({ event }) => {
+      try {
+        if (event.type === "session.created") {
+          await logToFile("\uD83D\uDE80 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`;
+            await logToFile(errorMsg);
+            await logToFile(`Event structure: ${JSON.stringify(eventData)}`);
+            throw new Error(errorMsg);
+          }
+          await logToFile(`\u2705 Extracted session ID: ${sessionId}`);
+          await createSessionState(sessionId);
+          const state = getSessionState(sessionId);
+          await logToFile(`\u2705 Session state created for session ${sessionId} with role: ${state.role}`);
+        }
+      } catch (error) {
+        await logToFile(`\u274C Error in event: ${error}`);
+      }
+    }
+  };
+};
+export {
+  opencodeKnowledge
+};

package/dist/templates/abbreviated.template.md

@@ -0,0 +1,8 @@
+## Knowledge Context
+
+You have access to an engineering knowledge base. Core areas include **{{CORE_TAGS}}** and key packages: **{{CORE_PACKAGES}}**.
+
+### Your Task
+{{USER_PROMPT}}
+
+Use knowledge_load and knowledge_search tools to access relevant information as needed.

package/dist/templates/first-prompt.template.md

@@ -9,22 +9,10 @@ You have access to a comprehensive knowledge base containing {{CATEGORIES_COUNT}
 **Packages:** 
 {{CORE_PACKAGES_LIST}}
 
-### Available Knowledge Tools
+### Your Task
+{{USER_PROMPT}}
 
-You have access to the following tools for working with the knowledge vault:
+### Knowledge Loading
+You can load specific knowledge packages using the knowledge_load tool when relevant to the task at hand. Focus on packages that match the technical domain or problem you're solving.
 
-**knowledge_search** - Search for packages by tags
-- Use this to discover relevant knowledge packages
-- Provide comma-separated tags (e.g., "typescript,react,testing")
-- Returns ranked list of matching packages with relevance scores
-
-**knowledge_load** - Load packages into context
-- Use this to inject knowledge package content into the session
-- Provide comma-separated paths (e.g., "standards/code-conventions.md")
-- Returns package content and metadata for your reference
-
-**knowledge_index** - Rebuild catalog (rarely needed)
-- Use this if search results seem outdated or after adding packages
-- Automatically runs on session start
-
-Use these tools proactively when you need domain-specific guidance or best practices.
+Available knowledge packages can be discovered by searching for specific tags, technologies, or domains using the knowledge_search tool.

package/package.json

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