diff --git a/README.md b/README.md index 8573fd5..a730f25 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ **LanceDB-backed long-term memory provider for OpenCode** [![npm version](https://img.shields.io/npm/v/lancedb-opencode-pro)](https://www.npmjs.com/package/lancedb-opencode-pro) -[![OpenCode](https://img.shields.io/badge/OpenCode-1.2.27+-blue)](https://opencode.ai) +[![OpenCode](https://img.shields.io/badge/OpenCode-1.2.27--1.3.7-blue)](https://opencode.ai) ⚠️ [1.3.8+ known issue](docs/OPENCODE_COMPATIBILITY.md) Welcome to **lancedb-opencode-pro**! This plugin empowers OpenCode with a durable, long-term memory system powered by LanceDB. @@ -11,6 +11,13 @@ To help you find what you need quickly, please select the guide that best fits y ## πŸ—ΊοΈ Choose Your Path +### ⚠️ Experiencing Issues? +*You see "Memory store unavailable" error or plugin not loading on OpenCode v1.3.8+* +πŸ‘‰ **[Read the Compatibility Guide (10 min)](docs/OPENCODE_COMPATIBILITY.md)** +- Known OpenCode v1.3.8+ NAPI bug (Issue #20623) +- Diagnosis checklist and solutions +- Downgrade instructions & alternatives + ### πŸš€ First-Time Users *You are new to this project and want to get it running quickly.* πŸ‘‰ **[Read the Quick Start Guide (15 min)](docs/QUICK_START.md)** diff --git a/docs/OPENCODE_COMPATIBILITY.md b/docs/OPENCODE_COMPATIBILITY.md new file mode 100644 index 0000000..6c4a51c --- /dev/null +++ b/docs/OPENCODE_COMPATIBILITY.md @@ -0,0 +1,298 @@ +# OpenCode Compatibility & Troubleshooting Guide + +**Last Updated**: April 3, 2026 +**Status**: Active +**Scope**: OpenCode version compatibility, plugin loading, NAPI native addon issues + +--- + +## πŸ”΄ Critical Issue: OpenCode v1.3.8+ Native NAPI Addon Bug + +### Overview + +If you see this error when using memory tools: +``` +Memory store unavailable (ollama embedding may be offline). Will retry automatically. +``` + +And embedding is confirmed working but memory tools persistently fail, **you likely have a native NAPI addon loading issue with OpenCode v1.3.8+**. + +--- + +## πŸ“‹ Affected Versions & Status + +| OpenCode Version | Status | LanceDB Native Support | Notes | +|------------------|--------|----------------------|-------| +| **v1.3.7 and earlier** | βœ… **Stable** | βœ… **Working** | Recommended | +| **v1.3.8 - v1.3.13** | ❌ **Broken** | ❌ **Broken** | Known bug (Issue #20623) | +| **v1.4.0+** | ⏳ **Unknown** | ⏳ **TBD** | Monitor releases | + +### Root Cause (Issue #20623) + +**Title**: `[Bug]: Plugins with native NAPI dependencies return empty module ({}) since v1.3.8 plugin loader refactor` + +**Root cause**: Plugin loader refactor in v1.3.8 (PR #20112) breaks external NAPI addon resolution. + +``` +v1.3.8+ Plugin Loader: + resolvePackagePath() + pathToFileURL() + β†’ @lancedb/lancedb resolves to empty object {} + β†’ import("@lancedb/lancedb") returns {} + β†’ store.init() fails silently in catch block + β†’ state.initialized stays false + β†’ All memory tools return "unavailable" error +``` + +**Affected plugins** (all native NAPI users): +- βœ… `lancedb-opencode-pro` (this plugin) +- βœ… Any plugin using: `sharp`, `better-sqlite3`, `@libsql/client`, etc. + +--- + +## πŸ”§ Solutions + +### Solution 1: Downgrade to OpenCode v1.3.7 (RECOMMENDED - Fastest) + +**Status**: βœ… Proven to work + +**Steps**: +```bash +# Check current version +opencode --version +# Output should be: 1.3.7 or earlier + +# If you have v1.3.8+, downgrade +opencode upgrade 1.3.7 + +# Verify +opencode --version +# Restart OpenCode +``` + +**Pros**: +- Immediate fix, no code changes needed +- lancedb-opencode-pro works perfectly + +**Cons**: +- You cannot use OpenCode 1.3.8+ features +- Will be prompted to upgrade again + +**Timeframe**: Immediate (5 minutes) + +--- + +### Solution 2: Improve Error Messaging (INTERIM - Helps Debugging) + +**Status**: πŸ”„ Proposed patch for lancedb-opencode-pro + +Add clear error handling to `src/store.ts` to help users diagnose the issue: + +**File**: `/home/devuser/workspace/lancedb-opencode-pro/src/store.ts` + +**Current code** (line 93): +```typescript +async init(vectorDim: number): Promise { + await mkdir(this.dbPath, { recursive: true }); + await mkdir(dirname(this.dbPath), { recursive: true }); + this.lancedb = await import("@lancedb/lancedb"); + this.connection = (await this.lancedb.connect(this.dbPath)); + // ... rest of init +} +``` + +**Proposed change**: +```typescript +async init(vectorDim: number): Promise { + await mkdir(this.dbPath, { recursive: true }); + await mkdir(dirname(this.dbPath), { recursive: true }); + + try { + this.lancedb = await import("@lancedb/lancedb"); + if (!this.lancedb || typeof this.lancedb.connect !== "function") { + throw new Error( + "LanceDB module loaded but is invalid/empty. " + + "This is a known issue in OpenCode v1.3.8+. " + + "Please downgrade to v1.3.7 or wait for OpenCode fix." + ); + } + this.connection = (await this.lancedb.connect(this.dbPath)); + } catch (error) { + const errorMsg = (error as Error).message; + throw new Error( + `[lancedb-opencode-pro] Failed to initialize memory store. ` + + `Error: ${errorMsg} ` + + `(For OpenCode v1.3.8+, this is Issue #20623. Downgrade to v1.3.7)` + ); + } + // ... rest of init +} +``` + +**Pros**: +- Clear error messages guide users to solution +- Easy to implement +- No functional changes + +**Cons**: +- Doesn't fix the actual issue +- Still needs downgrade or OpenCode fix + +**Timeframe**: Short-term (1-2 PRs) + +--- + +### Solution 3: Long-Term - Migrate to Pure JS Backend (COMPLEX) + +**Status**: πŸ”„ Requires significant refactoring + +If you need to support OpenCode 1.3.8+ permanently, consider: + +**Option A**: Use LanceDB HTTP API (remote database) +```typescript +// Instead of local @lancedb/lancedb native binding +// Use HTTP client to connect to remote LanceDB server +this.lancedb = await fetch("http://lancedb-server:8000/api/..."); +``` + +**Option B**: Use alternative pure-JS vector database +- `usearch` (pure JS, no native bindings) +- `milvus-sdk-node` (with pure JS mode) +- `chroma` (HTTP API) + +**Pros**: +- Works with OpenCode 1.3.8+ +- Potentially more scalable +- No native dependency issues + +**Cons**: +- Major refactoring (50+ files) +- Adds network dependency (latency) +- Requires separate database server +- Loses local-first architecture advantage + +**Timeframe**: Long-term (3-6 months, major effort) + +--- + +## πŸ› Diagnosis Checklist + +Use this to confirm if you have the v1.3.8+ NAPI bug: + +**Step 1: Check OpenCode version** +```bash +opencode --version +# If output is v1.3.8 - v1.3.13, you have the issue +``` + +**Step 2: Verify Ollama is working** +```bash +curl http://ollama:11434/api/tags +curl http://ollama:11434/api/embeddings -d '{"model":"nomic-embed-text","prompt":"test"}' +# Both should return valid JSON +``` + +**Step 3: Check plugin installation** +```bash +ls ~/.cache/opencode/node_modules/lancedb-opencode-pro/dist/ +# Should list: index.js, store.js, embedder.js, etc. +``` + +**Step 4: Try memory_stats** +``` +# In OpenCode chat, use: memory_stats +# If you see "Memory store unavailable" despite Ollama working β†’ Issue #20623 +``` + +**Step 5: Check for NAPI loading error** (advanced) +```bash +cd ~/.cache/opencode +bun -e " +import { MemoryStore } from './node_modules/lancedb-opencode-pro/dist/store.js'; +import { createEmbedder } from './node_modules/lancedb-opencode-pro/dist/embedder.js'; + +const e = createEmbedder({provider:'ollama',model:'nomic-embed-text',baseUrl:'http://ollama:11434',timeoutMs:6000}); +const s = new MemoryStore(process.env.HOME + '/.opencode/memory/lancedb'); +await s.init(await e.dim()); +console.log('SUCCESS: Store initialized'); +" 2>&1 +# If this succeeds but OpenCode fails β†’ Confirmed Issue #20623 +``` + +--- + +## πŸ“ž Support & Escalation + +### If Downgrade Works +- βœ… You're good! Stay on v1.3.7 +- Monitor [OpenCode Issue #20623](https://github.com/anomalyco/opencode/issues/20623) +- When OpenCode releases fix, upgrade to new version + +### If Downgrade Doesn't Work +- ❌ Different issue (not v1.3.8+ NAPI bug) +- Check [QUICK_START.md](QUICK_START.md) prerequisites +- Verify Ollama is accessible from OpenCode host +- Check logs: `~/.local/share/opencode/log/` + +### Report Issues +1. **This plugin**: https://github.com/tryweb/lancedb-opencode-pro/issues +2. **OpenCode native addon support**: https://github.com/anomalyco/opencode/issues/20623 + +Include: +- OpenCode version (`opencode --version`) +- Plugin version (`npm list lancedb-opencode-pro` or check `package.json`) +- Steps to reproduce +- Ollama verification output + +--- + +## πŸ” Related Issues + +| Issue | Component | Status | Impact | +|-------|-----------|--------|--------| +| [#20623](https://github.com/anomalyco/opencode/issues/20623) | OpenCode plugin loader | Open | πŸ”΄ Blocks all NAPI plugins | +| [#20112](https://github.com/anomalyco/opencode/pull/20112) | Plugin loader refactor | Merged | πŸ”΄ Introduced bug | +| [#20139](https://github.com/anomalyco/opencode/issues/20139) | npm plugin loading | Open | 🟑 Related | +| [#20149](https://github.com/anomalyco/opencode/issues/20149) | Package main entries | Open | 🟑 Related | + +--- + +## πŸ“Š Troubleshooting Decision Tree + +``` +β”Œβ”€ OpenCode v1.3.8+? +β”‚ β”œβ”€ YES β†’ Issue #20623 (this page) +β”‚ β”‚ β”œβ”€ Try downgrade to v1.3.7 β†’ Works? βœ… Done +β”‚ β”‚ └─ Doesn't work? β†’ Different issue +β”‚ └─ NO (v1.3.7 or earlier) β†’ Skip this section +β”‚ +└─ Ollama accessible? + β”œβ”€ curl http://ollama:11434/api/tags β†’ Returns JSON? βœ… + β”œβ”€ NO β†’ Fix Ollama access first + └─ YES β†’ Check prerequisites in QUICK_START.md +``` + +--- + +## πŸ“š Related Documentation + +- **[QUICK_START.md](QUICK_START.md)** β€” Prerequisites & setup (check version requirement) +- **[DEVELOPMENT_WORKFLOW.md](DEVELOPMENT_WORKFLOW.md)** β€” For developers working on fixes +- **[ADVANCED_CONFIG.md](ADVANCED_CONFIG.md)** β€” Configuration validation + +--- + +## 🎯 Summary + +| Aspect | Status | Action | +|--------|--------|--------| +| **Current state** | ❌ OpenCode v1.3.8+ broke NAPI addons | Check your OpenCode version | +| **This plugin** | βœ… Code is correct, works on v1.3.7 | No code changes needed | +| **Fix timeline** | ⏳ OpenCode team aware but no ETA | Monitor Issue #20623 | +| **Workaround** | βœ… Downgrade to v1.3.7 | Recommended now | +| **Long-term** | πŸ”„ Wait for OpenCode fix or refactor | 1-3 months | + +--- + +**Last Verified**: April 3, 2026 +**Tested On**: OpenCode v1.3.13, lancedb-opencode-pro v0.6.0 +**Status**: Active Issue diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index 7942262..59bcce9 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -8,7 +8,7 @@ Complete the following steps to start using the long-term memory feature within ## Prerequisites -- [ ] OpenCode 1.2.27+ installed +- [ ] OpenCode **1.2.27 - 1.3.7** installed *(⚠️ 1.3.8+ has known NAPI bug, see [OPENCODE_COMPATIBILITY.md](OPENCODE_COMPATIBILITY.md))* - [ ] Ollama installed and accessible - [ ] Embedding model downloaded (`nomic-embed-text`) @@ -142,6 +142,8 @@ If you see `.lance` files, it means the memory has been successfully persisted. ## Troubleshooting +> **⚠️ Critical Issue**: If you see "Memory store unavailable" error on OpenCode v1.3.8 or later, see [OPENCODE_COMPATIBILITY.md](OPENCODE_COMPATIBILITY.md). This is a known platform bug. + ### Issue 1: Plugin Not Loaded **Symptom**: OpenCode does not recognize `memory_*` tools diff --git a/docs/README.md b/docs/README.md index 2050dda..b00e2b3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,17 @@ This directory contains comprehensive analysis of OpenCode extensibility options ## Documents -### 0. **github-migration.md** +### 0. **OPENCODE_COMPATIBILITY.md** ⚠️ **NEW** +OpenCode version compatibility & troubleshooting with: +- Critical Issue: OpenCode v1.3.8+ native NAPI addon bug +- Affected versions (v1.3.8 - v1.3.13) +- Solutions: Downgrade, improve error messaging, long-term alternatives +- Diagnosis checklist & decision tree + +**Read time**: 10-15 minutes +**Priority**: **HIGH** if you see "Memory store unavailable" error + +### 1. **github-migration.md** Post-migration GitHub runbook with: - Branch protection bootstrap - Optional secrets setup @@ -13,7 +23,7 @@ Post-migration GitHub runbook with: **Read time**: 5-10 minutes -### 1. **FINDINGS_SUMMARY.txt** (START HERE) +### 2. **FINDINGS_SUMMARY.txt** (START HERE) Quick executive summary with: - Key findings - 4 practical options (A, B, C, D) @@ -23,7 +33,7 @@ Quick executive summary with: **Read time**: 5-10 minutes -### 2. **QUICK_REFERENCE.md** +### 3. **QUICK_REFERENCE.md** One-page decision guide with: - Current state overview - Option comparison table @@ -33,7 +43,7 @@ One-page decision guide with: **Read time**: 2-3 minutes -### 3. **EXTENSIBILITY_ANALYSIS.md** (COMPREHENSIVE) +### 4. **EXTENSIBILITY_ANALYSIS.md** (COMPREHENSIVE) Full 20KB analysis with: - 9 detailed sections - Evidence-based findings @@ -44,7 +54,7 @@ Full 20KB analysis with: **Read time**: 20-30 minutes -### 4. **embedding-migration.md** (OPERATIONS) +### 5. **embedding-migration.md** (OPERATIONS) Embedding model switching guide with: - Vector dimension compatibility table - System protection mechanisms @@ -60,6 +70,9 @@ Embedding model switching guide with: **I need to...** +- **Fix "Memory store unavailable" error** β†’ Read OPENCODE_COMPATIBILITY.md +- **Troubleshoot plugin loading issues** β†’ Read OPENCODE_COMPATIBILITY.md +- **Check OpenCode version compatibility** β†’ Read OPENCODE_COMPATIBILITY.md - **Make a decision quickly** β†’ Read FINDINGS_SUMMARY.txt - **See all options at a glance** β†’ Read QUICK_REFERENCE.md - **Understand the full context** β†’ Read EXTENSIBILITY_ANALYSIS.md