@javierkaiser/opencode-indexing 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -5,7 +5,84 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.3] - 2026-10-16
+
+### Added
+- `install.mjs` accepts `--with-codegraph`. It is **off by default** and only
+  has effect in `--package` mode, as consent comes from passing the flag. When
+  active it detects an existing `codegraph` CLI, installs it globally (`npm install
+  -g codegraph`) if it is missing, and registers its MCP with OpenCode via
+  `codegraph install --target opencode`. A failure in either step is reported and
+  does not cancel this plugin's own install.
+- The README now names `npx` (not `opencode plugin add`) as the recommended
+  install method, and shows the companion install in the recommended command:
+  `npx @javierkaiser/opencode-indexing --with-codegraph`.
+
+## [0.2.1] - 2026-10-15
+
+### Added
+
+- **`opencode plugin add @javierkaiser/opencode-indexing` is now the documented
+  install.** It was already possible — the package was published and exported
+  `./tui` — but the README told people to run `npm install` and edit
+  `opencode.json` by hand, which puts the package in whatever directory they were
+  standing in and never tells OpenCode about it. The CLI command installs into
+  OpenCode's own cache, records the entry, and brings the update and removal path
+  (`plugin check`, `plugin update`, `plugin remove`) with it.
+- **The installer has a package mode**, and picks between the two from where it
+  runs: a checkout installs the working tree, an installed copy installs the
+  published package. `npx @javierkaiser/opencode-indexing` therefore does the
+  right thing with no flags, including the permission rules and the restart that
+  `plugin add` alone does not do.
+- `bin` in `package.json`, so `npx` has something to run.
+- The plugin options and `ignoreKiloConfig` are documented in the README. The
+  option existed in the code and had tests, but appeared in no documentation.
+
+### Fixed
+
+- **"No Kilo index found" for a workspace that has one.** The server plugin is
+  instantiated for the directory the service runs in, so every RPC that omitted a
+  `directory` described *that* project. `kilo.discover` took no directory at all,
+  which is why opening the palette in one project and importing reported nothing
+  while the footer, using the same client and passing the directory, looked
+  correct. `kilo.discover` and `settings.test` now accept a directory, and the
+  palette, the settings page and the index actions all send the caller's. The
+  directory is injected once by `bindWorkspace` rather than passed at each call
+  site, so a new workspace-scoped RPC is correct by default instead of correct by
+  remembering.
+- **The tools read and indexed the service's directory.** All seven were pinned to
+  the plugin instance's root, so `indexing_search` in a session answered from
+  another codebase — results from the wrong project read as plausible — and
+  `indexing_import` refused an index that was sitting right there. They now use
+  `context.directory`, with the instance root as the fallback for hosts that do
+  not report one.
+- **`@lancedb/lancedb` could never load, so no Kilo index was ever importable
+  from LanceDB.** `apache-arrow` is that package's *peerDependency*, and the
+  installer runs `npm install --omit=peer`, which drops peers from the tree: the
+  native binary loaded and then threw `Cannot find module 'apache-arrow'` on first
+  use. It is now declared explicitly. This also broke `vectorStore: lancedb`
+  outright.
+- **An unreadable index was reported as a missing one.** Discovery swallowed
+  backend failures, so "Kilo is not running here" and "Kilo is not installed here"
+  both surfaced as *No Kilo index found*. It now names the path it found and the
+  reason it could not be read, in `indexing_status`, `indexing_build`,
+  `indexing_config`, `settings test kilo`, the import tool and the empty-state
+  toast. `indexing_build` is the one that matters most: with nothing reported, a
+  build in a workspace whose Kilo index could not be read re-embedded everything
+  without saying why.
+- **`apache-arrow` is declared in `package.json`, not only in the installer.**
+  It is a *peer* of `@lancedb/lancedb`, and the two install paths disagreed about
+  peers: `install.mjs` runs `npm install --omit=peer`, which drops them, while
+  the npm-based install OpenCode performs keeps them. Declaring it makes the
+  dependency true for both instead of true for whichever path happened to be
+  tested.
+- The installer no longer keeps its own copy of the dependency list; it derives
+  the installed `package.json` from the published one. That duplication is how
+  `apache-arrow` came to be declared for one install path and missing from the
+  other.
+- `--package` deletes a previously copied plugin. Both sources define
+  `id: "opencode.indexing"` and the config directory is scanned automatically, so
+  leaving both would load the plugin twice.
 
 ## [0.2.0] - 2026-10-14
 

package/README.md

@@ -26,44 +26,82 @@ index is still installed.
 
 ## Install
 
-### From npm (recommended)
+### With npx (recommended)
 
 ```bash
-npm install @javierkaiser/opencode-indexing
+npx @javierkaiser/opencode-indexing
 ```
 
-Then reference it from `opencode.json`:
+This is the whole install: the installer runs `opencode plugin add`, writes the
+permission rules, restarts the service, and, when you ask for it, also installs
+and registers the companion `codegraph`
+MCP. It picks its strategy from where it runs — from an npx cache or an
+unpacked tarball it installs the published package, from a checkout it
+installs your working tree instead — so edits take effect on restart with no
+publish in between. It prints which one it chose.
 
-```jsonc
-{
-  "plugins": [
-    { "package": "@javierkaiser/opencode-indexing" }
-  ]
-}
+Add `--with-codegraph` to install and register codegraph as part of the same run
+(the flag is opt-in and only has effect in the published-package mode):
+
+```bash
+npx @javierkaiser/opencode-indexing --with-codegraph
 ```
 
-### Global installer (alternative)
+| Flag | Effect |
+| --- | --- |
+| `--package [spec]` | Install the published package (default spec `@latest`) |
+| `--local` | Copy this directory into the config dir (development) |
+| `--skip-deps` | `--local` only: copy the files, install no dependencies |
+| `--no-restart` | Do not restart the service |
+| `--with-codegraph` | Install and register codegraph as a companion MCP (opt-in, `--package` only) |
 
-The installer is cross-platform; it only needs Node >= 22.6.
+### With the OpenCode CLI
 
 ```bash
-# Linux / macOS
-./install.sh
+opencode plugin add @javierkaiser/opencode-indexing
+```
 
-# Windows
-powershell -ExecutionPolicy Bypass -File .\install.ps1
+OpenCode downloads the package into its own cache and records it in the global
+`plugins` array, and it loads both halves of the plugin: the server side
+(`index.ts`, which registers the tools) and the terminal UI (`tui.ts`, which
+adds the prompt-footer indicator and the `/indexing` page). It brings `plugin
+check`, `plugin update` and `plugin remove` with it, but it cannot write
+permission rules — add this one to `opencode.json` to keep the host asking
+before the only tool that writes your settings file:
 
-# Any platform (the wrappers just call this)
-node install.mjs
+```jsonc
+{
+  "permissions": [
+    { "action": "indexing_config_set", "resource": "*", "effect": "ask" }
+  ]
+}
 ```
 
-It copies the plugin to the global config directory (`$XDG_CONFIG_HOME/opencode` or `~/.config/opencode`, same path used on Windows), installs runtime deps (`ignore`, plus optional `@lancedb/lancedb@0.26.2` and the tree-sitter WASM packages), adds one `permissions` rule per tool to `opencode.json` (read tools `allow`, `indexing_config_set` `ask`), and restarts the OpenCode service.
+The other six tools only read. OpenCode's base policy already allows everything
+(`{ "action": "*", "resource": "*", "effect": "allow" }`), so they need no rule;
+write them out only if you want to tighten the set.
+
+`install.sh` and `install.ps1` are thin wrappers over it; PowerShell also accepts
+`-Local`, `-Package`, `-Spec`, `-SkipDeps` and `-NoRestart`.
 
-Those are V2 rules — `{ "action": "indexing_search", "resource": "*", "effect": "allow" }` inside the `permissions` array. The older `permission` action map is a V1 shape that V2 ignores, so the installer removes any of its own entries from that map rather than leaving something that looks configured but grants nothing.
+`--package` deletes any copied plugin it finds: both sources define the same
+plugin id and the config directory is scanned automatically, so leaving both
+would load the plugin twice.
 
-Options: `--skip-deps` (copy files only), `--no-restart`. PowerShell accepts `-SkipDeps` / `-NoRestart` too.
+If no package manager is available, a `--local` install still copies the files
+and the plugin runs with reduced features (line chunker instead of tree-sitter,
+no LanceDB).
 
-If no package manager is available the copy still happens and the plugin runs with reduced features (line chunker instead of tree-sitter, no LanceDB).
+### Manual
+
+To manage the directory yourself, point `opencode.json` at it. Relative paths
+resolve from the config file containing the entry:
+
+```jsonc
+{
+  "plugins": ["./plugins/opencode-indexing"]
+}
+```
 
 ## How it works
 
@@ -302,16 +340,36 @@ Settings are stored in `~/.config/opencode/indexing.json` (plugin options → `i
 ```jsonc
 {
   "plugins": [
-    { "package": "./plugins/opencode-indexing", "options": {
+    { "package": "@javierkaiser/opencode-indexing", "options": {
       "vectorStore": "qdrant",
       "qdrantUrl": "http://localhost:6333",
       "importFromKilo": true,
-      "autoRefresh": false
+      "autoRefresh": false,
+      "ignoreKiloConfig": false
     }}
   ]
 }
 ```
 
+| Option | Meaning |
+| --- | --- |
+| `vectorStore` | `qdrant` or `lancedb` for the **own** index. Does not affect where an import reads from. |
+| `qdrantUrl` / `qdrantApiKey` | Qdrant connection |
+| `provider` / `model` / `dimension` | Embedding profile, overriding the resolved one |
+| `importFromKilo` | Import a compatible Kilo index on build instead of re-embedding |
+| `autoRefresh` | Refresh inline on search when few files changed |
+| `enabled` | Master switch: when false the own index is neither written nor refreshed |
+| `ignoreKiloConfig` | Stop reading `~/.config/kilo/kilo.jsonc` entirely |
+
+`~/.config/kilo/kilo.jsonc` is read as a fallback for the embedding provider,
+model, dimensions **and API keys**, which is what makes a free import possible:
+the same model has to be used to reuse Kilo's vectors. Set `ignoreKiloConfig` to
+`true` to cut that off, or override any single value with the options above, an
+environment variable, or `~/.config/opencode/indexing.json` — in that order of
+precedence, with plugin options winning.
+
+### Environment variables
+
 | Variable | Meaning |
 | --- | --- |
 | `KILO_INDEX_VECTOR_STORE` | `lancedb` (default) or `qdrant` for the own index |
@@ -423,7 +481,7 @@ This plugin deliberately stays on the semantic side and coexists with grep/read
 (see the tool descriptions and the bundled skill). A code-graph mode (tree-sitter
 symbol/edge extraction into SQLite, exposed as `indexing_graph_*` tools that
 chain after `indexing_search`) is a candidate for a future major version; the
-tree-sitter infrastructure is already in place.
+tree-sitter infrastructure is already in place. Independently, the installer can itself install and register codegraph as a companion MCP (`--with-codegraph`, opt-in, published-package mode only).
 
 ## Development
 

package/index.ts

@@ -217,6 +217,19 @@ const plugin = {
       const directory = (input as { directory?: string } | undefined)?.directory
       return typeof directory === "string" && directory.trim() !== "" ? directory : root
     }
+
+    /**
+     * Directory of the session a command was typed in.
+     *
+     * The plugin instance belongs to the directory the service runs in, which is
+     * usually a different one entirely, so a command issued from a session has to
+     * ask the host where that session is rather than assume its own.
+     */
+    const sessionDirectory = async (sessionID: string): Promise<string | undefined> =>
+      ctx.session
+        .get({ sessionID } as never)
+        .then((info: { location?: { directory?: string } }) => info?.location?.directory)
+        .catch(() => undefined)
     const options = (ctx.options ?? {}) as unknown as PluginOptionsInput
     const kv: KVStore = createPluginStorage(ctx.storage as never)
     const getSettings = (): Promise<IndexingSettings> => Promise.resolve(resolveSettings(options))
@@ -357,7 +370,7 @@ Behavior:
      * Extracted so the `settings.test` RPC and the `/indexing-config test`
      * subcommand answer identically instead of drifting apart.
      */
-    async function testTarget(target: string): Promise<{ ok: boolean; message: string }> {
+    async function testTarget(target: string, workspace: string): Promise<{ ok: boolean; message: string }> {
       const settings = await getSettings()
       try {
         if (target === "qdrant") {
@@ -379,15 +392,23 @@ Behavior:
           return { ok: true, message: `${settings.provider}/${settings.modelId} OK (${vector?.length ?? 0} dimensions)` }
         }
         if (target === "kilo") {
-          const sources = await discoverKiloSources(root, {
+          const problems: string[] = []
+          const sources = await discoverKiloSources(workspace, {
             qdrant: createSettingsQdrant(settings),
             homeDir: undefined,
             targetProfile: profileFor(settings),
+            onProblem: (message) => problems.push(message),
           })
           const list = sources.map((s) => `${s.kind} ${s.name} (${s.pointsCount ?? "?"} pts, ${s.compatible ? "compatible" : "INCOMPATIBLE"})`)
+          // A readable source does not make an unreadable one irrelevant: a
+          // partial answer ("Qdrant works, LanceDB does not") is the one that
+          // explains why an import picked the source it did.
+          const found = sources.length > 0 ? list.join(" · ") : `No importable Kilo index for ${workspace}`
           return {
             ok: sources.length > 0,
-            message: sources.length > 0 ? list.join(" · ") : "No Kilo index found for this workspace",
+            // With nothing found, a reason beats a bare "not found": the two
+            // need completely different actions from the user.
+            message: problems.length > 0 ? `${found}. ${problems.join(" · ")}` : found,
           }
         }
         return { ok: false, message: `Unknown test target: ${target}` }
@@ -412,11 +433,24 @@ Behavior:
       const dimension = settings.dimension || (await store.info()).profile?.dimension || 0
       if (!dimension) throw new Error("Embedding dimension unknown")
       const targetProfile = { provider: settings.provider, modelId: settings.modelId, dimension }
-      const sources = await discoverKiloSources(workspace, { qdrant: createSettingsQdrant(settings), targetProfile })
+      const problems: string[] = []
+      const sources = await discoverKiloSources(workspace, {
+        qdrant: createSettingsQdrant(settings),
+        targetProfile,
+        onProblem: (message) => problems.push(message),
+      })
       const source = wanted
         ? sources.find((item) => item.name === wanted)
         : (sources.find((item) => item.compatible) ?? sources[0])
-      if (!source) throw new Error("No Kilo source found for this workspace")
+      if (!source) {
+        // Naming the cause turns "nothing here" into something actionable when
+        // the index is present but unreadable.
+        throw new Error(
+          problems.length > 0
+            ? `No Kilo source found for ${workspace}. ${problems.join(" · ")}`
+            : "No Kilo source found for this workspace",
+        )
+      }
       if (!source.compatible) throw new Error(`Source ${source.name} has an incompatible embedding profile`)
       await store.ensure(dimension, targetProfile)
       const report = await importFromKilo({
@@ -548,6 +582,7 @@ class ForgetRefusedError extends Error {}
         }
         lines.push("")
       }
+      const problems: string[] = []
       const sources = await discoverKiloSources(root, {
         qdrant: createSettingsQdrant(settings),
         homeDir: undefined,
@@ -556,6 +591,7 @@ class ForgetRefusedError extends Error {}
         // compare against, so the report claimed an import would work when it
         // would be refused a moment later.
         targetProfile: profileFor(settings),
+        onProblem: (message) => problems.push(message),
       }).catch(() => [])
       lines.push(
         "",
@@ -563,6 +599,9 @@ class ForgetRefusedError extends Error {}
           ? `**Kilo sources detected:** ${sources.map((source) => `${source.kind} ${source.name} (${source.pointsCount ?? "?"} pts, ${source.compatible ? "compatible" : "INCOMPATIBLE"})`).join("; ")}`
           : "**Kilo sources detected:** none for this workspace",
       )
+      // "None" and "none I could read" are different answers, and only one of
+      // them is fixed by indexing from scratch.
+      if (problems.length > 0) lines.push("", `**Kilo sources unreadable:** ${problems.join(" · ")}`)
       lines.push(
         "",
         "To change settings:",
@@ -622,11 +661,15 @@ class ForgetRefusedError extends Error {}
                   return
                 }
                 case "test": {
+                  // Like `import` below, this has to name the session's directory:
+                  // `test kilo` asks whether an index exists *for a workspace*, and
+                  // answering about the service's own directory is always wrong.
                   const targets =
                     parsed.target === "all" ? ["qdrant", "lancedb", "provider", "kilo"] : [parsed.target]
+                  const workspace = (await sessionDirectory(sessionID)) ?? root
                   const results: string[] = []
                   for (const target of targets) {
-                    const result = await testTarget(target)
+                    const result = await testTarget(target, workspace)
                     results.push(`${target}: ${result.ok ? "OK" : "FAIL"} — ${result.message}`)
                   }
                   await reply(results.join("\n"))
@@ -636,11 +679,7 @@ class ForgetRefusedError extends Error {}
                   // The session knows which workspace the user is in; the plugin
                   // instance directory is the one the service runs in, which is
                   // usually a different directory entirely.
-                  const sessionDirectory = await ctx.session
-                    .get({ sessionID } as never)
-                    .then((info: { location?: { directory?: string } }) => info?.location?.directory)
-                    .catch(() => undefined)
-                  await reply(await runImport(sessionDirectory, parsed.source))
+                  await reply(await runImport(await sessionDirectory(sessionID), parsed.source))
                   return
                 }
               }
@@ -678,17 +717,19 @@ class ForgetRefusedError extends Error {}
         },
 
         "settings.test": async (input: unknown) => {
-          return testTarget((input as { target: string }).target)
+          return testTarget((input as { target: string }).target, rootFor(input))
         },
 
-        "kilo.discover": async () => {
+        "kilo.discover": async (input: unknown) => {
           const settings = await getSettings()
           const targetProfile =
             settings.dimension > 0 ? { provider: settings.provider, modelId: settings.modelId, dimension: settings.dimension } : undefined
-          const sources = await discoverKiloSources(root, {
+          const problems: string[] = []
+          const sources = await discoverKiloSources(rootFor(input), {
             qdrant: createSettingsQdrant(settings),
             homeDir: undefined,
             targetProfile,
+            onProblem: (message) => problems.push(message),
           })
           return {
             sources: sources.map((source) => ({
@@ -701,6 +742,7 @@ class ForgetRefusedError extends Error {}
                 : null,
               compatible: source.compatible,
             })),
+            problems,
           }
         },