@javierkaiser/opencode-indexing 0.2.0 → 0.2.3

package/install.mjs

@@ -1,17 +1,32 @@
 #!/usr/bin/env node
 /**
- * Cross-platform installer for opencode-indexing.
+ * Installer for opencode-indexing.
  *
  * Works on Windows, Linux and macOS (Node >= 22.6; Node 26 recommended).
  *
- *   node install.mjs [--skip-deps] [--no-restart]
+ *   node install.mjs [--local|--package] [spec] [--skip-deps] [--no-restart] [--with-codegraph]
+ *   npx @javierkaiser/opencode-indexing
  *
- * What it does:
- *  1. Copies the plugin into <config>/opencode/plugins/opencode-indexing
- *     (config dir honors $XDG_CONFIG_HOME, defaulting to ~/.config).
- *  2. Installs runtime dependencies (ignore + optional lancedb/tree-sitter).
- *  3. Merges tool permissions into <config>/opencode/opencode.json.
- *  4. Restarts the OpenCode service so the plugin loads.
+ * There are two ways to install, because there are two audiences.
+ *
+ *  --local    Copies the plugin into <config>/opencode/plugins/opencode-indexing
+ *             and installs its runtime dependencies there. This is the
+ *             development path: edits to the source take effect on restart,
+ *             with no publish in between.
+ *
+ *  --package  Hands the job to `opencode plugin add`, which installs the
+ *             published package into OpenCode's own cache and records it in the
+ *             global `plugins` array. This is the user-facing path: OpenCode
+ *             owns the install, so `opencode plugin check` and `plugin update`
+ *             work on it.
+ *
+ * The mode is picked from where this file runs. A checkout has `.git` or `test/`
+ * beside it and gets `--local`; anything else — the npx cache, a global install,
+ * an unpacked tarball — gets `--package`. Pass either flag to override, and the
+ * installer says which one it chose and why.
+ *
+ * Both modes write the tool permission rules and restart the service, so either
+ * one leaves a working install.
  */
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
@@ -23,112 +38,48 @@ const argv = process.argv.slice(2)
 const has = (name) => argv.some((arg) => arg.toLowerCase() === name)
 const skipDeps = has("--skip-deps")
 const noRestart = has("--no-restart")
+const withCodegraph = has("--with-codegraph")
 
 const source = dirname(fileURLToPath(import.meta.url))
+const sourcePkg = JSON.parse(readFileSync(join(source, "package.json"), "utf8"))
 const configRoot = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config")
 const configDir = join(configRoot, "opencode")
 const dest = join(configDir, "plugins", "opencode-indexing")
 const configFile = join(configDir, "opencode.json")
 
 const isWindows = process.platform === "win32"
+const opencodeBin = isWindows ? "opencode.cmd" : "opencode"
 const log = (message) => console.log(message)
 const warn = (message) => console.warn(message)
 
-log("Installing opencode-indexing")
-log(`  from: ${source}`)
-log(`  to:   ${dest}`)
-
-// ---------------------------------------------------------------------------
-// 1. Copy plugin files (keep a previously installed node_modules in place)
-// ---------------------------------------------------------------------------
 /**
- * Entries copied into the plugin directory.
+ * Whether this looks like the repository rather than an installed copy.
  *
- * An allowlist rather than a blocklist: a blocklist copied whatever local debris
- * happened to be in the working tree — a stray `test-run.log` was shipped into
- * every install. This mirrors the `files` field in package.json, minus the
- * installers, which are not needed inside an installed plugin.
+ * `.git` and `test/` are both absent from the published tarball, so their
+ * presence means someone is running the installer out of a working tree and
+ * almost certainly wants the source they are editing to be what gets loaded.
  */
-const COPY_ENTRIES = [
-  "index.ts",
-  "tui.ts",
-  "tui",
-  "src",
-  "package.json",
-  "tsconfig.json",
-  "README.md",
-  "LICENSE",
-  "THIRD_PARTY_NOTICES.md",
-]
-
-mkdirSync(dest, { recursive: true })
-for (const entry of readdirSync(dest)) {
-  if (entry === "node_modules") continue
-  rmSync(join(dest, entry), { recursive: true, force: true })
+function looksLikeCheckout() {
+  return existsSync(join(source, ".git")) || existsSync(join(source, "test"))
 }
-for (const entry of COPY_ENTRIES) {
-  const from = join(source, entry)
-  if (!existsSync(from)) {
-    warn(`  skipping missing entry: ${entry}`)
-    continue
-  }
-  cpSync(from, join(dest, entry), { recursive: true })
-}
-log("  files copied")
 
-// ---------------------------------------------------------------------------
-// 2. Minimal runtime package.json + dependency install
-// ---------------------------------------------------------------------------
-const sourcePkg = JSON.parse(readFileSync(join(source, "package.json"), "utf8"))
-const installedPkg = {
-  name: sourcePkg.name,
-  version: sourcePkg.version,
-  type: "module",
-  exports: {
-    ".": "./index.ts",
-    "./rpc": "./src/rpc.ts",
-    "./tui": "./tui.ts",
-  },
-  dependencies: {
-    ignore: ">=7.0.0",
-  },
-  optionalDependencies: {
-    "@lancedb/lancedb": "0.26.2",
-    "web-tree-sitter": "0.25.10",
-    "tree-sitter-wasms": "0.1.13",
-  },
-  // The host (OpenCode TUI) provides the renderer stack; declaring optional
-  // peers documents the contract without forcing a duplicate install.
-  peerDependencies: {
-    "@opencode/theme": ">=2.0.23",
-    "@opentui/core": ">=0.5.14",
-    "@opentui/solid": ">=0.5.14",
-    "solid-js": ">=1.9.12",
-  },
-  peerDependenciesMeta: {
-    "@opencode/theme": { optional: true },
-    "@opentui/core": { optional: true },
-    "@opentui/solid": { optional: true },
-    "solid-js": { optional: true },
-  },
-}
-writeFileSync(join(dest, "package.json"), JSON.stringify(installedPkg, null, 2) + "\n", "utf8")
+const mode = has("--local") ? "local" : has("--package") ? "package" : looksLikeCheckout() ? "local" : "package"
+const reason = has("--local") || has("--package") ? "requested" : looksLikeCheckout() ? "a checkout" : "an installed copy"
 
-if (!skipDeps) {
-  log("  installing runtime deps (ignore + optional lancedb/tree-sitter)...")
-  const npm = isWindows ? "npm.cmd" : "npm"
-  const result = spawnSync(
-    npm,
-    ["install", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund", "--loglevel=error"],
-    { cwd: dest, stdio: "inherit", shell: isWindows },
-  )
-  if (result.error || result.status !== 0) {
-    warn(`  dependency install failed (${result.error?.message ?? `exit ${result.status}`}); the plugin still runs with reduced features`)
-  }
-}
+// A positional argument is the package spec for --package. `@latest` rather than
+// the version this file was published as, because an exact version is skipped by
+// `opencode plugin check` and `plugin update`: pinning would silently opt the
+// install out of the update path OpenCode provides.
+const positional = argv.filter((arg) => !arg.startsWith("-"))
+const spec = positional[0] ?? `${sourcePkg.name}@latest`
+
+log(`Installing ${sourcePkg.name} ${sourcePkg.version}`)
+log(`  from: ${source}`)
+log(`  mode: ${mode} (${reason})`)
+if (withCodegraph) log("  + codegraph (via --with-codegraph, package mode)")
 
 // ---------------------------------------------------------------------------
-// 3. Merge tool permissions into opencode.json (JSONC tolerant)
+// Tool permissions (both modes)
 // ---------------------------------------------------------------------------
 function stripJsonc(input) {
   // Strip a UTF-8 BOM: editors on Windows may add one and JSON.parse rejects it.
@@ -189,51 +140,267 @@ const TOOLS = ["indexing_search", "indexing_status", "indexing_config", "indexin
 // Everything else only reads. This one writes the settings file, so the host
 // asks the user before it runs instead of taking it on trust.
 const ASK_BEFORE_RUN = new Set(["indexing_config_set"])
-try {
-  let cfg = {}
-  if (existsSync(configFile)) {
-    cfg = JSON.parse(stripJsonc(readFileSync(configFile, "utf8")))
-    if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) cfg = {}
-  }
 
-  // Drop the V1 entries this installer used to write. Anything else the user
-  // put there is left untouched.
-  if (cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)) {
-    for (const tool of TOOLS) delete cfg.permission[tool]
-    if (Object.keys(cfg.permission).length === 0) delete cfg.permission
-  }
+/**
+ * Add one permission rule per tool to the global config.
+ *
+ * `opencode plugin add` installs the plugin but knows nothing about its tools,
+ * so a package-mode install has to write these itself or the `ask` gate on
+ * `indexing_config_set` is lost. The read tools would be allowed by the base
+ * `{ "*": "allow" }` policy anyway; they are written out so the set is visible
+ * and can be tightened in one place.
+ */
+function writePermissions() {
+  try {
+    let cfg = {}
+    if (existsSync(configFile)) {
+      cfg = JSON.parse(stripJsonc(readFileSync(configFile, "utf8")))
+      if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg)) cfg = {}
+    }
 
-  if (!Array.isArray(cfg.permissions)) cfg.permissions = []
-  for (const tool of TOOLS) {
-    const effect = ASK_BEFORE_RUN.has(tool) ? "ask" : "allow"
-    const rule = cfg.permissions.find((entry) => entry && entry.action === tool)
-    if (rule) {
-      rule.resource = "*"
-      rule.effect = effect
-    } else {
-      cfg.permissions.push({ action: tool, resource: "*", effect })
+    // Drop the V1 entries this installer used to write. Anything else the user
+    // put there is left untouched.
+    if (cfg.permission && typeof cfg.permission === "object" && !Array.isArray(cfg.permission)) {
+      for (const tool of TOOLS) delete cfg.permission[tool]
+      if (Object.keys(cfg.permission).length === 0) delete cfg.permission
     }
-  }
 
-  mkdirSync(configDir, { recursive: true })
-  writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", "utf8")
-  log(`  permissions added to ${configFile}`)
-} catch (error) {
-  warn(`  could not update ${configFile}: ${error instanceof Error ? error.message : String(error)}`)
+    if (!Array.isArray(cfg.permissions)) cfg.permissions = []
+    for (const tool of TOOLS) {
+      const effect = ASK_BEFORE_RUN.has(tool) ? "ask" : "allow"
+      const rule = cfg.permissions.find((entry) => entry && entry.action === tool)
+      if (rule) {
+        rule.resource = "*"
+        rule.effect = effect
+      } else {
+        cfg.permissions.push({ action: tool, resource: "*", effect })
+      }
+    }
+
+    mkdirSync(configDir, { recursive: true })
+    writeFileSync(configFile, JSON.stringify(cfg, null, 2) + "\n", "utf8")
+    log(`  permissions added to ${configFile}`)
+  } catch (error) {
+    warn(`  could not update ${configFile}: ${error instanceof Error ? error.message : String(error)}`)
+  }
 }
 
 // ---------------------------------------------------------------------------
-// 4. Restart the OpenCode service so the plugin loads
+// Service restart (both modes)
 // ---------------------------------------------------------------------------
-if (!noRestart) {
+function restartService() {
+  if (noRestart) return
   log("  restarting OpenCode service...")
-  const opencode = isWindows ? "opencode.cmd" : "opencode"
-  const result = spawnSync(opencode, ["service", "restart"], { stdio: "inherit", shell: isWindows })
+  const result = spawnSync(opencodeBin, ["service", "restart"], { stdio: "inherit", shell: isWindows })
   if (result.error || result.status !== 0) {
     warn("  could not restart automatically. Run: opencode service restart")
   }
 }
 
+// ---------------------------------------------------------------------------
+// Local mode: copy the working tree into the config directory
+// ---------------------------------------------------------------------------
+/**
+ * Entries copied into the plugin directory.
+ *
+ * An allowlist rather than a blocklist: a blocklist copied whatever local debris
+ * happened to be in the working tree — a stray `test-run.log` was shipped into
+ * every install. This mirrors the `files` field in package.json, minus the
+ * installers, which are not needed inside an installed plugin.
+ */
+const COPY_ENTRIES = [
+  "index.ts",
+  "tui.ts",
+  "tui",
+  "src",
+  "package.json",
+  "tsconfig.json",
+  "README.md",
+  "LICENSE",
+  "THIRD_PARTY_NOTICES.md",
+]
+
+function installLocal() {
+  log(`  to:   ${dest}`)
+  mkdirSync(dest, { recursive: true })
+  for (const entry of readdirSync(dest)) {
+    if (entry === "node_modules") continue
+    rmSync(join(dest, entry), { recursive: true, force: true })
+  }
+  for (const entry of COPY_ENTRIES) {
+    const from = join(source, entry)
+    if (!existsSync(from)) {
+      warn(`  skipping missing entry: ${entry}`)
+      continue
+    }
+    cpSync(from, join(dest, entry), { recursive: true })
+  }
+  log("  files copied")
+
+  // The installed package.json is derived, never hand-written: the list this
+  // used to keep in parallel is how `apache-arrow` came to be declared for the
+  // installer and missing from the published package, which broke every Kilo
+  // LanceDB import for one of the two install paths and not the other.
+  const installedPkg = {
+    name: sourcePkg.name,
+    version: sourcePkg.version,
+    type: "module",
+    exports: sourcePkg.exports,
+    dependencies: sourcePkg.dependencies,
+    optionalDependencies: sourcePkg.optionalDependencies,
+    peerDependencies: sourcePkg.peerDependencies,
+    peerDependenciesMeta: sourcePkg.peerDependenciesMeta,
+  }
+  writeFileSync(join(dest, "package.json"), JSON.stringify(installedPkg, null, 2) + "\n", "utf8")
+
+  if (skipDeps) {
+    log("  skipping dependency install (--skip-deps)")
+    return
+  }
+
+  log("  installing runtime deps (ignore + optional lancedb/tree-sitter)...")
+  const npm = isWindows ? "npm.cmd" : "npm"
+  // --omit=peer is why apache-arrow has to be a real dependency above: the
+  // native LanceDB binary loads without it and throws on first use.
+  const result = spawnSync(
+    npm,
+    ["install", "--omit=dev", "--omit=peer", "--no-audit", "--no-fund", "--loglevel=error"],
+    { cwd: dest, stdio: "inherit", shell: isWindows },
+  )
+  if (result.error || result.status !== 0) {
+    warn(`  dependency install failed (${result.error?.message ?? `exit ${result.status}`}); the plugin still runs with reduced features`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Package mode: let OpenCode own the install
+// ---------------------------------------------------------------------------
+/** How many entries `opencode plugin list` reports for this plugin. */
+function registeredCount() {
+  const result = spawnSync(opencodeBin, ["plugin", "list"], { encoding: "utf8", shell: isWindows })
+  if (result.error || result.status !== 0 || typeof result.stdout !== "string") return undefined
+  // `plugin list` prints a table: `ID  VERSION  SOURCE`. Compare the first
+  // column exactly rather than by prefix, so a longer id that happens to start
+  // the same way is not counted as this plugin.
+  return result.stdout
+    .split("\n")
+    .map((line) => line.trim().split(/\s+/)[0])
+    .filter((id) => id === "opencode.indexing").length
+}
+
+function installPackage() {
+  log(`  spec: ${spec}`)
+
+  const added = spawnSync(opencodeBin, ["plugin", "add", spec], { stdio: "inherit", shell: isWindows })
+  if (added.error || added.status !== 0) {
+    // Nothing has been removed at this point, so a failure here leaves the
+    // previous install exactly as it was.
+    warn(`  \`opencode plugin add\` failed (${added.error?.message ?? `exit ${added.status}`}); the previous install was left untouched`)
+    return false
+  }
+
+  // Remove the copied plugin *after* the package is in place. Both sources
+  // define `id: "opencode.indexing"`, and the config directory is scanned
+  // automatically, so leaving the copy behind would load the plugin twice.
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true })
+    log(`  removed the copied plugin at ${dest} (it would load twice)`)
+  }
+
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// Codegraph as a companion MCP (opt-in, --with-codegraph)
+// ---------------------------------------------------------------------------
+/**
+ * Whether a `codegraph` CLI is available on PATH.
+ *
+ * A plain spawn is the cheapest, shell-independent probe and matches what
+ * the bench harness `resolveBinary()` does. It is treated as read-only here.
+ */
+function hasCodegraphBin() {
+  try {
+    const probe = spawnSync("codegraph", ["--version"], { stdio: "ignore", shell: isWindows })
+    if (probe.error) return false
+    // status is either 0 or, on some wrappers, undefined-but-no-error; treat both as present
+    return probe.status === 0 || probe.status === null
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Install codegraph and register its MCP with OpenCode.
+ *
+ * The only consent gate is the flag itself, as the user requested: this is
+ * an install step, not a recommendation. A failure in either half is reported
+ * and tolerated — the plugin is already installed and still works with
+ * semantic search only.
+ */
+function installCodegraph() {
+  log("  installing codegraph as a companion MCP server...")
+
+  if (!hasCodegraphBin()) {
+    log("  codegraph CLI missing; running npm install -g codegraph...")
+    const npm = isWindows ? "npm.cmd" : "npm"
+    // --omit=... is not needed here: codegraph stands on its own, and a global
+    // install is what its own documentation assumes.
+    const installed = spawnSync(npm, ["install", "-g", "codegraph"], {
+      stdio: "inherit",
+      shell: isWindows,
+    })
+    if (installed.error || installed.status !== 0) {
+      warn("  could not install codegraph (npm install -g codegraph failed); skipping MCP registration")
+      return
+    }
+  }
+
+  const register = spawnSync("codegraph", ["install", "--target", "opencode"], {
+    stdio: "inherit",
+    shell: isWindows,
+  })
+  if (register.error || register.status !== 0) {
+    warn("  codegraph is present but `codegraph install --target opencode` failed")
+    warn("  run it manually once to finish MCP registration: codegraph install --target opencode")
+    return
+  }
+
+  log("  codegraph installed and registered with OpenCode")
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+if (mode === "local") {
+  installLocal()
+  if (withCodegraph) warn("  --with-codegraph is ignored in --local mode; codegraph is not installed there")
+} else {
+  if (!installPackage()) {
+  warn("  not writing permissions or restarting: the install did not complete")
+  process.exit(1)
+  }
+  if (withCodegraph) installCodegraph()
+
+}
+
+writePermissions()
+// Before the count below, not after: `plugin list` asks the running service,
+// which still holds the configuration from before this install.
+restartService()
+
+if (mode === "package") {
+  const count = registeredCount()
+  if (count !== undefined && count > 1) {
+    warn(`  ${count} entries report id opencode.indexing; only one should. Check \`opencode plugin list\`.`)
+  }
+}
+
 log("Done.")
-log("Verify with: opencode api get /api/info")
-log("Then run in a session: indexing_status  (or /indexing-config in any client)")
+if (mode === "package") {
+  log("Update with: opencode plugin update")
+  log("Remove with: opencode plugin remove " + spec)
+} else {
+  log("Verify with: opencode api get /api/info")
+  log("Then run in a session: indexing_status  (or /indexing-config in any client)")
+}

package/install.ps1

@@ -3,8 +3,11 @@
 # and macOS all run the same code instead of drifting copies.
 #
 # Usage:
-#   powershell -ExecutionPolicy Bypass -File install.ps1 [-SkipDeps] [-NoRestart]
+#   powershell -ExecutionPolicy Bypass -File install.ps1 [-Local|-Package] [-Spec <spec>] [-SkipDeps] [-NoRestart]
 param(
+  [switch]$Local,
+  [switch]$Package,
+  [string]$Spec,
   [switch]$SkipDeps,
   [switch]$NoRestart
 )
@@ -12,6 +15,9 @@ param(
 $ErrorActionPreference = "Stop"
 $script = Join-Path $PSScriptRoot "install.mjs"
 $forward = @()
+if ($Local) { $forward += "--local" }
+if ($Package) { $forward += "--package" }
+if ($Spec) { $forward += $Spec }
 if ($SkipDeps) { $forward += "--skip-deps" }
 if ($NoRestart) { $forward += "--no-restart" }
 

package/install.sh

@@ -3,7 +3,7 @@
 # Thin wrapper: the cross-platform logic lives in install.mjs.
 #
 # Usage:
-#   sh install.sh [--skip-deps] [--no-restart]
+#   sh install.sh [--local|--package] [spec] [--skip-deps] [--no-restart]
 set -eu
 
 dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javierkaiser/opencode-indexing",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "description": "OpenCode plugin: semantic code search that reuses Kilo Code indexes (Qdrant/LanceDB) and maintains its own independent index",
   "license": "MIT",
   "author": "Carlos Javier Lust <javierkaiser@gmail.com>",
@@ -29,6 +29,9 @@
     "./rpc": "./src/rpc.ts",
     "./tui": "./tui.ts"
   },
+  "bin": {
+    "opencode-indexing": "./install.mjs"
+  },
   "files": [
     "index.ts",
     "tui.ts",
@@ -61,7 +64,8 @@
   "optionalDependencies": {
     "@lancedb/lancedb": "0.26.2",
     "tree-sitter-wasms": "0.1.13",
-    "web-tree-sitter": "0.25.10"
+    "web-tree-sitter": "0.25.10",
+    "apache-arrow": "18.1.0"
   },
   "devDependencies": {
     "@opencode/plugin": "2.0.23",

package/src/import.ts

@@ -6,6 +6,7 @@ import { getKiloStoreInfo, resolveKiloCollection } from "./kilo-store.ts"
 import { readLanceDbInfoAt, readLanceDbBatch, lanceDbName } from "./lancedb-store.ts"
 import { kiloLanceDbDirectory } from "./settings.ts"
 import { recordWorkspace } from "./workspaces.ts"
+import { describeError } from "./errors.ts"
 import type { EmbeddingProfile, QdrantPoint, IndexReport } from "./types.ts"
 import type { VectorStoreAdapter } from "./vector-store.ts"
 import { profileKey } from "./registry.ts"
@@ -47,9 +48,25 @@ export interface ImportReport {
 /** Read-only description of Kilo sources available for a workspace. */
 export async function discoverKiloSources(
   root: string,
-  options: { qdrant?: Qdrant; lancedbDirectory?: string; homeDir?: string; targetProfile?: EmbeddingProfile },
+  options: {
+    qdrant?: Qdrant
+    lancedbDirectory?: string
+    homeDir?: string
+    targetProfile?: EmbeddingProfile
+    /**
+     * Called when a source exists but could not be read.
+     *
+     * A backend that is down and a source that does not exist look identical
+     * once the error is swallowed, and both are reported to the user as "no Kilo
+     * index found". That is a wrong answer in the first case: the index is
+     * sitting on disk, and what is missing is a native module or a running
+     * server. The caller decides where the message surfaces.
+     */
+    onProblem?: (message: string) => void
+  },
 ): Promise<KiloSourceInfo[]> {
   const sources: KiloSourceInfo[] = []
+  const problem = options.onProblem ?? ((): void => {})
   const isCompatible = (profile?: EmbeddingProfile): boolean => {
     if (!options.targetProfile || !profile) return true
     return profileKey(profile) === profileKey(options.targetProfile)
@@ -71,15 +88,17 @@ export async function discoverKiloSources(
         compatible: isCompatible(info.profile),
       })
     }
-  } catch {
-    // Qdrant unreachable: skip silently; lancedb may still be available.
+  } catch (error) {
+    // A backend that answers with no matching collection is not a failure; a
+    // backend that never answered is.
+    problem(`Could not reach the Qdrant server to look for a Kilo index: ${describeError(error)}`)
   }
 
   // LanceDB source
-  try {
-    const directory = options.lancedbDirectory ?? kiloLanceDbDirectory(options.homeDir)
-    const dbPath = path.join(directory, lanceDbName(root))
-    if (fs.existsSync(dbPath)) {
+  const directory = options.lancedbDirectory ?? kiloLanceDbDirectory(options.homeDir)
+  const dbPath = path.join(directory, lanceDbName(root))
+  if (fs.existsSync(dbPath)) {
+    try {
       const info = await readLanceDbInfoAt(dbPath)
       if (info.vectorExists) {
         sources.push({
@@ -92,9 +111,11 @@ export async function discoverKiloSources(
           compatible: isCompatible(info.profile),
         })
       }
+    } catch (error) {
+      // The directory is there, so this is "found but unreadable", never
+      // "not indexed". Say so, with the reason.
+      problem(`A Kilo LanceDB index exists at ${dbPath} but could not be read: ${describeError(error)}`)
     }
-  } catch {
-    // LanceDB unavailable: skip.
   }
 
   return sources

package/src/indexer.ts

@@ -157,10 +157,15 @@ export async function runIndex(deps: IndexerDeps, options: IndexOptions): Promis
   if (shouldImport) {
     await deps.onProgress?.({ phase: "importing", processed: 0, total: 0 })
     try {
+      // Collected rather than thrown: discovery no longer fails on an
+      // unreadable source, and the caller has to be told why the scan below is
+      // about to re-embed the whole workspace at their expense.
+      const problems: string[] = []
       const sources = await discoverKiloSources(root, {
         qdrant,
         homeDir: undefined,
         targetProfile: profile,
+        onProblem: (message) => problems.push(message),
       })
       const source = sources.find((item) => item.compatible) ?? sources[0]
       if (source && source.compatible) {
@@ -190,6 +195,12 @@ export async function runIndex(deps: IndexerDeps, options: IndexOptions): Promis
         report.errors.push(
           `Kilo index found (${source.name}) but its embedding profile does not match ${profile.provider}:${profile.modelId}:${profile.dimension}; indexing from scratch`,
         )
+      } else if (problems.length > 0) {
+        // No usable source and a reason why. Without this the build reads as a
+        // workspace that has no Kilo index at all, and the full re-embedding
+        // that follows looks like the normal path rather than the expensive
+        // fallback it is.
+        report.errors.push(`${problems.join(" · ")} Indexing from scratch instead.`)
       }
     } catch (error) {
       report.errors.push(`import failed: ${describeError(error)}`)