opencodekit 0.2.3 → 0.2.5

package/dist/template/.opencode/tool/memory-search.ts

@@ -0,0 +1,140 @@
+import path from "path";
+import { tool } from "@opencode-ai/plugin";
+import fs from "fs/promises";
+
+interface SearchResult {
+	file: string;
+	matches: { line: number; content: string }[];
+}
+
+async function searchDirectory(
+	dir: string,
+	pattern: RegExp,
+	results: SearchResult[],
+	baseDir: string,
+): Promise<void> {
+	try {
+		const entries = await fs.readdir(dir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+
+			if (entry.isDirectory()) {
+				// Skip hidden directories except _templates
+				if (entry.name.startsWith(".") && entry.name !== "_templates") {
+					continue;
+				}
+				await searchDirectory(fullPath, pattern, results, baseDir);
+			} else if (entry.name.endsWith(".md")) {
+				const content = await fs.readFile(fullPath, "utf-8");
+				const lines = content.split("\n");
+				const matches: { line: number; content: string }[] = [];
+
+				lines.forEach((line, index) => {
+					if (pattern.test(line)) {
+						matches.push({
+							line: index + 1,
+							content: line.trim().substring(0, 150),
+						});
+					}
+				});
+
+				if (matches.length > 0) {
+					const relativePath = path.relative(baseDir, fullPath);
+					results.push({ file: relativePath, matches });
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist or not readable
+	}
+}
+
+export default tool({
+	description:
+		"Search across all memory files using keywords or patterns. Returns matching files with line numbers and context. Useful for finding past decisions, research, or handoffs.",
+	args: {
+		query: tool.schema
+			.string()
+			.describe(
+				"Search query: keywords or regex pattern (e.g., 'authentication', 'bugfix.*session')",
+			),
+		type: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Filter by type: 'all' (default), 'handoffs', 'research', 'templates', 'observations', 'beads'",
+			),
+		limit: tool.schema
+			.number()
+			.optional()
+			.describe("Max results per file (default: 5)"),
+	},
+	execute: async (args: { query: string; type?: string; limit?: number }) => {
+		const memoryDir = path.join(process.cwd(), ".opencode/memory");
+		const beadsDir = path.join(process.cwd(), ".beads/artifacts");
+		const globalMemoryDir = path.join(
+			process.env.HOME || "",
+			".config/opencode/memory",
+		);
+
+		const limit = args.limit || 5;
+
+		// Create case-insensitive regex from query
+		let pattern: RegExp;
+		try {
+			pattern = new RegExp(args.query, "i");
+		} catch {
+			// Escape special chars if not valid regex
+			const escaped = args.query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			pattern = new RegExp(escaped, "i");
+		}
+
+		const results: SearchResult[] = [];
+
+		// Handle type filtering
+		if (args.type === "beads") {
+			// Search only bead artifacts
+			await searchDirectory(beadsDir, pattern, results, beadsDir);
+		} else if (args.type && args.type !== "all") {
+			const typeMap: Record<string, string> = {
+				handoffs: "handoffs",
+				research: "research",
+				templates: "_templates",
+				observations: "observations",
+			};
+			const subdir = typeMap[args.type];
+			if (subdir) {
+				const searchDir = path.join(memoryDir, subdir);
+				await searchDirectory(searchDir, pattern, results, memoryDir);
+			}
+		} else {
+			// Search all: memory + beads
+			await searchDirectory(memoryDir, pattern, results, memoryDir);
+			await searchDirectory(beadsDir, pattern, results, beadsDir);
+			await searchDirectory(globalMemoryDir, pattern, results, globalMemoryDir);
+		}
+
+		if (results.length === 0) {
+			return `No matches found for "${args.query}" in memory files.\n\nTip: Try broader search terms or check available types: handoffs, research, templates, observations, beads`;
+		}
+
+		// Build output
+		let output = `# Memory Search: "${args.query}"\n\n`;
+		output += `Found ${results.length} file(s) with matches.\n\n`;
+
+		for (const result of results) {
+			output += `## ${result.file}\n\n`;
+			const matchesToShow = result.matches.slice(0, limit);
+			for (const match of matchesToShow) {
+				output += `- **Line ${match.line}:** ${match.content}\n`;
+			}
+			if (result.matches.length > limit) {
+				output += `- ... and ${result.matches.length - limit} more matches\n`;
+			}
+			output += "\n";
+		}
+
+		return output;
+	},
+});

package/dist/template/.opencode/tool/observation.ts

@@ -0,0 +1,155 @@
+import path from "path";
+import { tool } from "@opencode-ai/plugin";
+import fs from "fs/promises";
+
+// Observation types following claude-mem patterns
+type ObservationType =
+	| "decision"
+	| "bugfix"
+	| "feature"
+	| "pattern"
+	| "discovery"
+	| "learning"
+	| "warning";
+
+const TYPE_ICONS: Record<ObservationType, string> = {
+	decision: "🎯",
+	bugfix: "🐛",
+	feature: "✨",
+	pattern: "🔄",
+	discovery: "💡",
+	learning: "📚",
+	warning: "⚠️",
+};
+
+export default tool({
+	description:
+		"Create a structured observation for future reference. Observations are categorized by type (decision, bugfix, feature, pattern, discovery, learning, warning) and stored in .opencode/memory/observations/.",
+	args: {
+		type: tool.schema
+			.string()
+			.describe(
+				"Observation type: decision, bugfix, feature, pattern, discovery, learning, warning",
+			),
+		title: tool.schema.string().describe("Brief title for the observation"),
+		content: tool.schema
+			.string()
+			.describe("Detailed observation content with context"),
+		concepts: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Comma-separated concept tags (e.g., 'authentication, oauth, security')",
+			),
+		files: tool.schema
+			.string()
+			.optional()
+			.describe(
+				"Comma-separated related files (e.g., 'src/auth.ts, src/login.ts')",
+			),
+		bead_id: tool.schema
+			.string()
+			.optional()
+			.describe("Related bead ID for traceability"),
+	},
+	execute: async (args: {
+		type: string;
+		title: string;
+		content: string;
+		concepts?: string;
+		files?: string;
+		bead_id?: string;
+	}) => {
+		const obsDir = path.join(process.cwd(), ".opencode/memory/observations");
+
+		// Validate type
+		const validTypes: ObservationType[] = [
+			"decision",
+			"bugfix",
+			"feature",
+			"pattern",
+			"discovery",
+			"learning",
+			"warning",
+		];
+		const obsType = args.type.toLowerCase() as ObservationType;
+		if (!validTypes.includes(obsType)) {
+			return `Error: Invalid observation type '${args.type}'.\nValid types: ${validTypes.join(", ")}`;
+		}
+
+		// Generate filename: YYYY-MM-DD-type-slug.md
+		const now = new Date();
+		const dateStr = now.toISOString().split("T")[0];
+		const slug = args.title
+			.toLowerCase()
+			.replace(/[^a-z0-9]+/g, "-")
+			.replace(/^-|-$/g, "")
+			.substring(0, 40);
+		const filename = `${dateStr}-${obsType}-${slug}.md`;
+		const filePath = path.join(obsDir, filename);
+
+		// Parse concepts and files
+		const concepts = args.concepts
+			? args.concepts.split(",").map((c) => c.trim())
+			: [];
+		const files = args.files ? args.files.split(",").map((f) => f.trim()) : [];
+
+		// Build observation content
+		const icon = TYPE_ICONS[obsType];
+		let observation = `# ${icon} ${args.title}\n\n`;
+		observation += `**Type:** ${obsType}\n`;
+		observation += `**Created:** ${now.toISOString()}\n`;
+
+		if (args.bead_id) {
+			observation += `**Bead:** ${args.bead_id}\n`;
+		}
+
+		if (concepts.length > 0) {
+			observation += `**Concepts:** ${concepts.map((c) => `\`${c}\``).join(", ")}\n`;
+		}
+
+		if (files.length > 0) {
+			observation += `**Files:** ${files.map((f) => `\`${f}\``).join(", ")}\n`;
+		}
+
+		observation += `\n---\n\n`;
+		observation += args.content;
+		observation += `\n`;
+
+		try {
+			// Ensure directory exists
+			await fs.mkdir(obsDir, { recursive: true });
+
+			// Write observation
+			await fs.writeFile(filePath, observation, "utf-8");
+
+			let beadUpdate = "";
+
+			// Update bead notes if bead_id provided
+			if (args.bead_id) {
+				try {
+					const { execSync } = await import("child_process");
+					const noteContent = `${icon} ${obsType}: ${args.title}`;
+					execSync(
+						`bd edit ${args.bead_id} --note "${noteContent.replace(/"/g, '\\"')}"`,
+						{
+							cwd: process.cwd(),
+							encoding: "utf-8",
+							timeout: 5000,
+						},
+					);
+					beadUpdate = `\nBead updated: ${args.bead_id}`;
+				} catch {
+					beadUpdate = `\nWarning: Could not update bead ${args.bead_id}`;
+				}
+			}
+
+			return `✓ Observation saved: ${filename}\n\nType: ${icon} ${obsType}\nTitle: ${args.title}\nConcepts: ${concepts.join(", ") || "none"}\nFiles: ${files.join(", ") || "none"}${beadUpdate}\n\nPath: ${filePath}`;
+		} catch (error) {
+			if (error instanceof Error) {
+				return `Error saving observation: ${error.message}`;
+			}
+			return `Unknown error saving observation`;
+		}
+	},
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.2.3",
+	"version": "0.2.5",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"type": "module",
 	"repository": {

package/dist/template/.opencode/memory/README.md

@@ -1,128 +0,0 @@
-# Memory System README
-
-## Overview
-
-The memory/ directory provides persistent cross-session context for OpenCode agents. This enables continuity and learning over time.
-
-## Structure
-
-```
-memory/
-├── _templates/                  # Document templates
-│   ├── spec.md                 # Template for task specifications
-│   ├── research.md             # Template for research documents
-│   └── session.md              # Template for session memory
-├── memory.md                    # Current project state and session learnings
-├── todo.md                      # Task tracking and progress
-├── development-guidelines.md    # Code conventions and patterns
-├── architecture-decisions.md    # Why we built it this way
-├── blockers.md                  # Known issues and workarounds
-│
-├── research/                    # Research findings and analysis
-│   ├── YYYY-MM-DD-topic.md     # Research documents
-│   └── cache-topic.md          # Research cache files
-│
-├── design-guidelines.md        # Design system and UI standards
-├── decisions/                   # Architectural decision records
-│   └── database-choice.md       # Example: Why PostgreSQL
-│
-└── plans/                       # Strategic planning documents
-    └── q4-roadmap.md            # Example: Quarterly objectives
-```
-
-**Subdirectories:** Use to organize knowledge by category and prevent flat directory bloat.
-
-## Usage
-
-### For Agents
-
-**At Session Start:**
-
-1. Read `memory.md` for current project context
-2. Check `todo.md` for active tasks
-3. Review `blockers.md` for known issues
-
-**During Session:**
-
-- Consult `development-guidelines.md` for coding standards
-- Reference `architecture-decisions.md` for design rationale
-- Reference `design-guidelines.md` for design standards
-- Update progress in `todo.md`
-- Save research to `research/YYYY-MM-DD-topic.md` (auto-created by /research command)
-- Document decisions in `decisions/choice-name.md`
-- Create specs using templates from `_templates/spec.md`
-
-**At Session End:**
-
-- Update `memory.md` with new learnings
-- Mark completed tasks in `todo.md`
-- Document new blockers or resolve existing ones
-
-### For Humans
-
-**Quick Status Check:**
-
-```bash
-# See current state
-cat memory/memory.md
-
-# Check active tasks
-cat memory/todo.md
-
-# Review blockers
-cat memory/blockers.md
-```
-
-**Update Memory:**
-Edit files directly or use memory-update tool - agents will read on next session.
-
-**Examples:**
-
-```bash
-# Read research notes
-memory-read research/opencode-sessions
-
-# Create new research note
-memory-update research/new-topic content="# Research Notes\n..."
-
-# Add decision record
-memory-update decisions/database-choice content="# Why PostgreSQL\n..."
-
-# Tools auto-create subdirectories and strip .md extension
-```
-
-## Memory Lifecycle
-
-### Compaction (When memory.md > 5000 words)
-
-1. Distill to critical facts only
-2. Archive detailed history to dated file: `memory-archive-YYYY-MM-DD.md`
-3. Keep current state lean and focused
-
-### Rotation
-
-- Archive completed tasks monthly
-- Move resolved blockers to history section
-- Keep active memory under 5000 words
-
-## Integration Points
-
-- **Plan Agent:** Reads memory.md before creating plans
-- **Build Agent:** Updates memory.md after major completions
-- **All Agents:** Consult development-guidelines.md for standards
-- **Design Agent:** Consults design-guidelines.md for design standards
-
-## Best Practices
-
-1. **Be Specific:** "Uses React 18 Server Components" vs "Uses React"
-2. **Date Decisions:** Track when and why choices were made
-3. **Keep Current:** Update after significant progress, not every trivial change
-4. **Prune Regularly:** Remove obsolete information
-5. **Link Context:** Reference related files/specs when relevant
-
-## Future Enhancements
-
-- Automatic memory compaction triggers
-- Memory-read and memory-update tools
-- Integration with task ledgers
-- Progress monitoring and re-planning triggers

package/dist/template/.opencode/memory/_templates/handoff.md

@@ -1,33 +0,0 @@
-# Handoff: [Phase Name]
-
-**Date:** YYYY-MM-DD
-**From:** [Current phase/agent]
-**To:** [Next phase/agent]
-**Task:** [Task ID if applicable]
-
-## Summary
-
-[1-2 sentences: What was accomplished in this phase]
-
-## Relevant Files
-
-- `@path/to/file1` - [Why needed]
-- `@path/to/file2` - [Why needed]
-
-## Key Decisions
-
-- [Decision 1]: [Rationale]
-- [Decision 2]: [Rationale]
-
-## Constraints
-
-- [Constraint that must be followed]
-- [Limitation to be aware of]
-
-## Next Instructions
-
-[Clear prompt for the next agent - what exactly to do next]
-
-## Open Questions
-
-- [Unresolved question for next phase]

package/dist/template/.opencode/memory/_templates/research.md

@@ -1,29 +0,0 @@
-# Research: [Topic]
-
-**Date:** YYYY-MM-DD
-**Context:** [Why this research was needed]
-
-## Question
-
-[The specific question or problem being researched]
-
-## Findings
-
-### [Finding 1]
-
-- [Key insight]
-- Source: [URL or document]
-
-### [Finding 2]
-
-- [Key insight]
-- Source: [URL or document]
-
-## Decision
-
-[Clear recommendation based on findings]
-
-## Next Steps
-
-1. [Action item]
-2. [Action item]

package/dist/template/.opencode/memory/_templates/task-design.md

@@ -1,59 +0,0 @@
-# Design Document
-
-**Bead ID:** [bead-id]
-**Created:** [date]
-**Status:** Draft | Validated
-
-## Problem Statement
-
-What we're solving and why it matters:
-
-## Approaches Considered
-
-### Option A: [Name]
-
-- **Pros:** [advantages]
-- **Cons:** [drawbacks]
-
-### Option B: [Name]
-
-- **Pros:** [advantages]
-- **Cons:** [drawbacks]
-
-### Chosen Approach
-
-[Which option and why]
-
-## Architecture
-
-High-level structure and how components fit together:
-
-### Components
-
-- [Component 1]: [purpose]
-- [Component 2]: [purpose]
-
-### Data Flow
-
-[How data moves through the system]
-
-## Error Handling
-
-How the design handles failure cases:
-
-- [Error scenario 1]: [handling approach]
-- [Error scenario 2]: [handling approach]
-
-## Testing Strategy
-
-How we'll validate this design works:
-
-- [Testing approach 1]
-- [Testing approach 2]
-
-## Open Questions
-
-Unresolved items to address during implementation:
-
-- [ ] [Question 1]
-- [ ] [Question 2]

package/dist/template/.opencode/memory/_templates/task-review.md

@@ -1,73 +0,0 @@
-# Task Review Template
-
-**Task ID:** [auto-generated]
-**Completed:** [date]
-**Status:** Done
-
-## What Changed
-
-### Files Modified:
-
-- `src/[file1.js]` - [brief description of changes]
-- `src/[file2.js]` - [brief description of changes]
-- `tests/[test.js]` - [brief description of changes]
-
-### Logic Added:
-
-- [New functionality implemented]
-- [Key algorithms or business logic]
-- [Data flow changes]
-
-### Files Created:
-
-- [List any new files created]
-
-## What Skipped
-
-### Intentionally Not Done:
-
-- [Feature X - reason: out of scope for this task]
-- [Optimization Y - reason: will be separate task]
-- [Test case Z - reason: requires additional setup]
-
-### Known Limitations:
-
-- [Limitation 1 - temporary workaround]
-- [Limitation 2 - technical debt introduced]
-- [Limitation 3 - performance considerations]
-
-## Inconsistencies with Architecture
-
-### Deviations from Spec:
-
-- [What was supposed to happen vs what actually happened]
-- [Why the deviation was necessary]
-- [Impact on overall architecture]
-
-### Unexpected Challenges:
-
-- [Problem 1 encountered and how solved]
-- [Problem 2 encountered and how solved]
-- [Problem 3 encountered and how solved]
-
-## Validation Results
-
-### Success Criteria Met:
-
-- [x] [Criteria 1 from PRD - how verified]
-- [x] [Criteria 2 from PRD - how verified]
-- [x] [Criteria 3 from PRD - how verified]
-
-### Test Results:
-
-- [Test suite results summary]
-- [Performance benchmarks]
-- [Security validations]
-
-## Next Micro-Task
-
-[Immediate next step or follow-up task needed]
-
-## Lessons Learned
-
-[What worked well, what didn't, what to improve for future tasks]

package/dist/template/.opencode/memory/_templates/task-spec.md

@@ -1,71 +0,0 @@
-# Task Spec Template
-
-**Task ID:** [auto-generated]
-**PRD:** [link to task-XXX-prd.md]
-**Created:** [date]
-
-## Architecture Plan
-
-Where this feature plugs into the repo, which layers it touches, expected file paths:
-
-### Files to Create/Modify:
-
-- `src/[path/to/file1.js]` - [purpose]
-- `src/[path/to/file2.js]` - [purpose]
-- `tests/[path/to/test.js]` - [purpose]
-
-### Integration Points:
-
-- [Existing module/service it connects to]
-- [Database schema changes needed]
-- [API endpoints affected]
-
-## Constraints
-
-### Naming Conventions:
-
-- Functions: [pattern, e.g., camelCase]
-- Files: [pattern, e.g., kebab-case]
-- Variables: [pattern, e.g., descriptive names]
-
-### Framework Requirements:
-
-- Must use: [required libraries/patterns]
-- Must NOT use: [forbidden libraries/patterns]
-- Must follow: [specific patterns, e.g., controllers → services → repository]
-
-### Code Style:
-
-- [Linting rules to follow]
-- [Testing patterns required]
-- [Documentation requirements]
-
-## Edge Cases
-
-Every scenario I know devs forget when in a rush:
-
-- [Edge case 1: what happens when X fails]
-- [Edge case 2: handling of invalid input Y]
-- [Edge case 3: performance under load Z]
-- [Edge case 4: error recovery scenarios]
-- [Edge case 5: security considerations]
-
-## Testing Notes
-
-Expected inputs/outputs, how to validate behavior, what logs/errors should look like:
-
-### Test Cases:
-
-- [Test case 1: normal flow]
-- [Test case 2: error conditions]
-- [Test case 3: edge cases]
-
-### Validation:
-
-- [How to verify it works correctly]
-- [Expected logs/messages]
-- [Performance benchmarks]
-
-### Rollback Plan:
-
-- [How to undo changes if something goes wrong]