raggrep 0.12.3 → 0.13.2

package/README.md

@@ -223,33 +223,77 @@ The index is stored in a system temp directory, keeping your project clean.
 
 `node_modules`, `dist`, `build`, `.git`, `.next`, `.cache`, `__pycache__`, `target`, and other common build/dependency directories
 
-## Opencode Integration
+## OpenCode Integration
 
-RAGgrep can be integrated with [opencode](https://opencode.ai) to provide semantic code search capabilities within the AI coding assistant.
+RAGgrep can be integrated with [OpenCode](https://opencode.ai) to provide semantic code search capabilities within the AI coding assistant.
 
 ### Installation
 
-Install the raggrep tool for opencode:
+RAGgrep supports two installation types for OpenCode:
 
+#### Default Installation (Recommended)
 ```bash
 raggrep opencode install
 ```
 
-This creates the tool file at `~/.config/opencode/tool/raggrep.ts`.
+This installs RAGgrep as a **tool** by default, which provides the best activation rates in OpenCode.
 
-### Usage in Opencode
+#### Explicit Installation Types
 
-Once installed, you can search your codebase directly within opencode:
+**Force Tool Installation:**
+```bash
+raggrep opencode install --tool
+```
+- Installs to: `~/.config/opencode/tool/raggrep.ts`
+- Direct tool execution with full raggrep functionality
+
+**Force Skill Installation:**
+```bash
+raggrep opencode install --skill
+```
+- Installs to: `~/.config/opencode/skill/raggrep/SKILL.md`
+- Skill-based integration for modern OpenCode versions
+
+#### Mutual Exclusivity
+
+Installing one type will prompt to remove the other (default: yes):
+
+```bash
+# Installing skill will prompt to remove existing tool
+raggrep opencode install --skill
+
+# Installing tool will prompt to remove existing skill  
+raggrep opencode install --tool
+```
+
+### Usage in OpenCode
+
+#### Tool Usage
+Once installed as a tool, RAGgrep provides direct search functionality:
+- Natural language queries: "user authentication flow"
+- All CLI options: `--top`, `--min-score`, `--type`, `--filter`
+- Context-aware results with scores and file locations
+
+#### Skill Usage
+Load the skill in your OpenCode conversation:
+```bash
+skill({ name: "raggrep" })
+```
+
+Then follow the skill's guidance to:
+1. Install RAGgrep: `npm install -g raggrep`
+2. Index your codebase: `raggrep index`
+3. Use semantic search: `raggrep query "your search term"`
+
+### Why Tool by Default?
 
-- Search for code using natural language: "user authentication flow"
-- Filter by file types and paths
-- Get context-aware results with scores and locations
+The tool installation is the default because it:
+- Has higher activation rates in OpenCode agents
+- Provides immediate search capabilities
+- Works consistently across all OpenCode versions
+- Offers direct integration without skill loading steps
 
-The tool supports all the same search options as the CLI:
-- Number of results (`top`)
-- Minimum similarity score (`minScore`)
-- File type filtering (`type`)
-- Path filtering (`filter`)
+The skill installation is available for users who prefer the modern skill-based approach or need specific skill integration features.
 
 ## Documentation
 

package/dist/app/cli/opencode/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OpenCode Integration Module
+ *
+ * This module provides version-aware installation of raggrep for OpenCode,
+ * supporting both legacy tool-based installation (OpenCode < v1.0.186) and
+ * modern skill-based installation (OpenCode >= v1.0.186).
+ */
+export * from "./version-check";
+export * from "./install-tool";
+export * from "./install-skill";

package/dist/app/cli/opencode/install-skill.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OpenCode Skill Installation (Modern)
+ *
+ * Version Compatibility: OpenCode versions >= v1.0.186
+ *
+ * This module installs raggrep as an OpenCode skill for newer versions of OpenCode
+ * that support the skill system. Skills are markdown files with YAML frontmatter
+ * placed in ~/.opencode/skill/ that provide reusable behavior definitions.
+ *
+ * Benefits of Skills over Tools:
+ * - Better integration with OpenCode's agent system
+ * - More flexible and educational for agents
+ * - Follows OpenCode's modern architecture patterns
+ * - Provides comprehensive usage documentation
+ */
+import type { Logger } from "../../../domain/ports";
+export interface SkillInstallOptions {
+    logger?: Logger;
+    checkForOldTool?: boolean;
+}
+export interface SkillInstallResult {
+    success: boolean;
+    skillPath?: string;
+    message: string;
+    removedOldTool?: boolean;
+}
+/**
+ * Install raggrep as an OpenCode skill for modern versions
+ */
+export declare function installSkill(options?: SkillInstallOptions): Promise<SkillInstallResult>;

package/dist/app/cli/opencode/install-tool.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenCode Tool Installation (Legacy)
+ *
+ * Version Compatibility: OpenCode versions < v1.0.186
+ *
+ * This module installs raggrep as an OpenCode tool for older versions of OpenCode
+ * that do not support the skill system. Tools are TypeScript files placed in
+ * ~/.config/opencode/tool/ that provide direct execution capabilities.
+ *
+ * Migration Note:
+ * - Users should upgrade to OpenCode v1.0.186+ to use the newer skill-based approach
+ * - This tool-based approach will be deprecated in future versions
+ */
+import type { Logger } from "../../../domain/ports";
+export interface ToolInstallOptions {
+    logger?: Logger;
+    checkForOldSkill?: boolean;
+}
+export interface ToolInstallResult {
+    success: boolean;
+    toolPath?: string;
+    message: string;
+    removedOldSkill?: boolean;
+}
+/**
+ * Install raggrep as an OpenCode tool for older versions
+ */
+export declare function installTool(options?: ToolInstallOptions): Promise<ToolInstallResult>;

package/dist/app/cli/opencode/version-check.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OpenCode Version Checker
+ *
+ * Determines whether to use tool or skill installation based on OpenCode version.
+ *
+ * Version Compatibility:
+ * - OpenCode versions < v1.0.186: Use tool-based installation
+ * - OpenCode versions >= v1.0.186: Use skill-based installation
+ */
+export interface OpenCodeVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+/**
+ * Parse OpenCode version string into comparable components
+ */
+export declare function parseOpenCodeVersion(version: string): OpenCodeVersion | null;
+/**
+ * Check if OpenCode version supports skills (v1.0.186+)
+ */
+export declare function supportsSkills(version: string): boolean;
+/**
+ * Get installation method recommendation based on OpenCode version
+ */
+export declare function getInstallationMethod(openCodeVersion?: string): 'tool' | 'skill';
+/**
+ * Detect OpenCode version by checking common installation locations
+ */
+export declare function detectOpenCodeVersion(): Promise<string | null>;