@gmickel/gno 1.2.1 → 1.3.1

package/src/mcp/resources/index.ts

@@ -13,7 +13,12 @@ import { join as pathJoin } from "node:path";
 import type { DocumentRow, TagCount } from "../../store/types";
 import type { ToolContext } from "../server";
 
-import { buildUri, parseUri, URI_PREFIX } from "../../app/constants";
+import {
+  buildUri,
+  decorateUriForIndex,
+  parseUri,
+  URI_PREFIX,
+} from "../../app/constants";
 import { MCP_ERRORS } from "../../core/errors";
 import { normalizeTag, validateTag } from "../../core/tags";
 import { normalizeCollectionName } from "../../core/validation";
@@ -64,7 +69,8 @@ function formatResourceContent(
   const langLine = doc.languageHint
     ? `\n     language: ${doc.languageHint}`
     : "";
-  const header = `<!-- ${doc.uri}
+  const displayUri = decorateUriForIndex(doc.uri, ctx.indexName);
+  const header = `<!-- ${displayUri}
      docid: ${doc.docid}
      source: ${absPath}
      mime: ${doc.sourceMime}${langLine}
@@ -94,7 +100,7 @@ export function registerResources(server: McpServer, ctx: ToolContext): void {
 
       return {
         resources: listResult.value.map((doc) => ({
-          uri: doc.uri,
+          uri: decorateUriForIndex(doc.uri, ctx.indexName),
           name: doc.relPath,
           mimeType: doc.sourceMime || "text/markdown",
           description: doc.title ?? undefined,
@@ -160,7 +166,10 @@ export function registerResources(server: McpServer, ctx: ToolContext): void {
       const formattedContent = formatResourceContent(doc, content, ctx);
 
       // Build canonical URI
-      const canonicalUri = buildUri(collection, path);
+      const canonicalUri = decorateUriForIndex(
+        buildUri(collection, path),
+        parsed.indexName ?? ctx.indexName
+      );
 
       return {
         contents: [

package/src/mcp/server.ts

@@ -57,6 +57,7 @@ export interface ToolContext {
   config: Config;
   collections: Collection[];
   actualConfigPath: string;
+  indexName?: string;
   toolMutex: Mutex;
   jobManager: JobManager;
   serverInstanceId: string;
@@ -164,6 +165,7 @@ export async function startMcpServer(options: McpServerOptions): Promise<void> {
     config,
     collections,
     actualConfigPath,
+    indexName: options.indexName,
     toolMutex,
     jobManager,
     serverInstanceId,

package/src/mcp/tools/get.ts

@@ -9,7 +9,7 @@ import { join as pathJoin } from "node:path";
 import type { DocumentRow, StorePort } from "../../store/types";
 import type { ToolContext } from "../server";
 
-import { parseUri } from "../../app/constants";
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { parseRef } from "../../cli/commands/ref-parser";
 import {
   getDocumentCapabilities,
@@ -196,7 +196,12 @@ export function handleGet(
 
       const response: GetResponse = {
         docid: doc.docid,
-        uri: doc.uri,
+        uri: decorateUriForIndex(
+          doc.uri,
+          parsed.type === "uri"
+            ? (parseUri(parsed.value)?.indexName ?? ctx.indexName)
+            : ctx.indexName
+        ),
         title: doc.title ?? undefined,
         content,
         totalLines,

package/src/mcp/tools/multi-get.ts

@@ -9,7 +9,7 @@ import { join as pathJoin } from "node:path";
 import type { DocumentRow, StorePort } from "../../store/types";
 import type { ToolContext } from "../server";
 
-import { parseUri } from "../../app/constants";
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { parseRef } from "../../cli/commands/ref-parser";
 import { runTool, type ToolResult } from "./index";
 
@@ -232,7 +232,7 @@ export function handleMultiGet(
 
         documents.push({
           docid: doc.docid,
-          uri: doc.uri,
+          uri: decorateUriForIndex(doc.uri, ctx.indexName),
           title: doc.title ?? undefined,
           content,
           totalLines: (contentResult.value ?? "").split("\n").length,

package/src/mcp/tools/query.ts

@@ -18,7 +18,7 @@ import type {
 } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
-import { parseUri } from "../../app/constants";
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
 import { resolveDepthPolicy } from "../../core/depth-policy";
 import { normalizeStructuredQueryInput } from "../../core/structured-query";
@@ -76,6 +76,7 @@ function enrichWithAbsPath(
 
     return {
       ...r,
+      uri: decorateUriForIndex(r.uri, ctx.indexName),
       source: {
         ...r.source,
         absPath: pathJoin(collection.path, r.source.relPath),

package/src/mcp/tools/search.ts

@@ -9,7 +9,7 @@ import { join as pathJoin } from "node:path";
 import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
-import { parseUri } from "../../app/constants";
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { searchBm25 } from "../../pipeline/search";
 import { normalizeTagFilters, runTool, type ToolResult } from "./index";
 
@@ -51,6 +51,7 @@ function enrichWithAbsPath(
 
     return {
       ...r,
+      uri: decorateUriForIndex(r.uri, ctx.indexName),
       source: {
         ...r.source,
         absPath: pathJoin(collection.path, r.source.relPath),

package/src/mcp/tools/vsearch.ts

@@ -9,7 +9,7 @@ import { join as pathJoin } from "node:path";
 import type { SearchResult, SearchResults } from "../../pipeline/types";
 import type { ToolContext } from "../server";
 
-import { parseUri } from "../../app/constants";
+import { decorateUriForIndex, parseUri } from "../../app/constants";
 import { createNonTtyProgressRenderer } from "../../cli/progress";
 import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { resolveDownloadPolicy } from "../../llm/policy";
@@ -60,6 +60,7 @@ function enrichWithAbsPath(
 
     return {
       ...r,
+      uri: decorateUriForIndex(r.uri, ctx.indexName),
       source: {
         ...r.source,
         absPath: pathJoin(collection.path, r.source.relPath),

package/src/pipeline/explain.ts

@@ -122,9 +122,19 @@ export function explainBm25(count: number): ExplainLine {
   return { stage: "bm25", message: `${count} candidates` };
 }
 
-export function explainVector(count: number, available: boolean): ExplainLine {
+export function explainVector(
+  count: number,
+  available: boolean,
+  unavailableReason?: string,
+  guidance?: string
+): ExplainLine {
   if (!available) {
-    return { stage: "vector", message: "unavailable (sqlite-vec not loaded)" };
+    const detail = unavailableReason ? `: ${unavailableReason}` : "";
+    const hint = guidance ? `; ${guidance}` : "";
+    return {
+      stage: "vector",
+      message: `unavailable (sqlite-vec not loaded${detail})${hint}`,
+    };
   }
   return { stage: "vector", message: `${count} candidates` };
 }

package/src/pipeline/hybrid.ts

@@ -528,7 +528,14 @@ export async function searchHybrid(
   }
   timings.vectorMs = performance.now() - vectorStartedAt;
 
-  explainLines.push(explainVector(vecCount, vectorAvailable));
+  explainLines.push(
+    explainVector(
+      vecCount,
+      vectorAvailable,
+      vectorIndex?.loadError,
+      vectorIndex?.guidance
+    )
+  );
 
   // ─────────────────────────────────────────────────────────────────────────
   // 3. RRF Fusion
@@ -800,6 +807,7 @@ export async function searchHybrid(
       score: candidate.blendedScore,
       uri: doc.uri,
       title: doc.title ?? undefined,
+      line: snippetChunk.startLine,
       snippet,
       snippetLanguage: chunk.language ?? undefined,
       snippetRange,

package/src/pipeline/search.ts

@@ -117,6 +117,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     score: fts.score, // Raw score, normalized later as batch
     uri: fts.uri ?? "",
     title: fts.title,
+    line: chunk?.startLine,
     snippet,
     snippetLanguage: chunk?.language ?? undefined,
     snippetRange,

package/src/pipeline/types.ts

@@ -43,6 +43,8 @@ export interface SearchResult {
   score: number;
   uri: string;
   title?: string;
+  /** Best source line for editor/agent anchors (1-indexed) */
+  line?: number;
   snippet: string;
   snippetLanguage?: string;
   snippetRange?: SnippetRange;

package/src/pipeline/vsearch.ts

@@ -50,6 +50,16 @@ export interface VectorSearchDeps {
   config: Config;
 }
 
+function vectorUnavailableMessage(vectorIndex: VectorIndexPort): string {
+  const reason = vectorIndex.loadError
+    ? ` Reason: ${vectorIndex.loadError}`
+    : "";
+  const guidance = vectorIndex.guidance
+    ? ` ${vectorIndex.guidance}`
+    : " Run: gno doctor";
+  return `Vector search unavailable.${reason}${guidance}`;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Search Function (with pre-computed embedding)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -82,10 +92,7 @@ export async function searchVectorWithEmbedding(
 
   // Check if vector search is available
   if (!vectorIndex.searchAvailable) {
-    return err(
-      "VEC_SEARCH_UNAVAILABLE",
-      "Vector search requires sqlite-vec. Run: gno embed"
-    );
+    return err("VEC_SEARCH_UNAVAILABLE", vectorUnavailableMessage(vectorIndex));
   }
 
   // Search nearest neighbors
@@ -220,6 +227,7 @@ export async function searchVectorWithEmbedding(
       score,
       uri: doc.uri,
       title: doc.title ?? undefined,
+      line: chunk.startLine,
       snippet: chunk.text,
       snippetLanguage: chunk.language ?? undefined,
       snippetRange: {
@@ -273,6 +281,7 @@ export async function searchVectorWithEmbedding(
         score,
         uri: doc.uri,
         title: doc.title ?? undefined,
+        line: chunk.startLine,
         snippet: fullContent ?? chunk.text,
         snippetLanguage: chunk.language ?? undefined,
         // --full: no snippetRange (full doc content)
@@ -354,10 +363,7 @@ export async function searchVector(
 
   // Check if vector search is available
   if (!vectorIndex.searchAvailable) {
-    return err(
-      "VEC_SEARCH_UNAVAILABLE",
-      "Vector search requires sqlite-vec. Run: gno embed"
-    );
+    return err("VEC_SEARCH_UNAVAILABLE", vectorUnavailableMessage(vectorIndex));
   }
 
   // Embed query with contextual formatting

package/src/sdk/client.ts

@@ -37,7 +37,11 @@ import type {
   GnoVectorSearchOptions,
 } from "./types";
 
-import { getIndexDbPath } from "../app/constants";
+import {
+  decorateUriForIndex,
+  getIndexDbPath,
+  parseUri,
+} from "../app/constants";
 import { ConfigSchema, loadConfig } from "../config";
 import {
   atomicWrite,
@@ -88,6 +92,7 @@ interface OpenedClientState {
   store: SqliteAdapter;
   llm: LlmAdapter;
   downloadPolicy: DownloadPolicy;
+  indexName?: string;
 }
 
 interface RuntimePorts {
@@ -158,6 +163,7 @@ async function resolveClientState(
     llm: new LlmAdapter(config, options.cacheDir),
     downloadPolicy:
       options.downloadPolicy ?? resolveDownloadPolicy(process.env, {}),
+    indexName: options.indexName,
   };
 }
 
@@ -170,6 +176,7 @@ class GnoClientImpl implements GnoClient {
   private readonly store: SqliteAdapter;
   private readonly llm: LlmAdapter;
   private readonly downloadPolicy: DownloadPolicy;
+  private readonly indexName?: string;
   private closed = false;
 
   constructor(state: OpenedClientState) {
@@ -180,6 +187,7 @@ class GnoClientImpl implements GnoClient {
     this.store = state.store;
     this.llm = state.llm;
     this.downloadPolicy = state.downloadPolicy;
+    this.indexName = state.indexName;
   }
 
   isOpen(): boolean {
@@ -371,12 +379,24 @@ class GnoClientImpl implements GnoClient {
     }
   }
 
+  private decorateSearchResults(results: SearchResults): SearchResults {
+    return {
+      ...results,
+      results: results.results.map((result) => ({
+        ...result,
+        uri: decorateUriForIndex(result.uri, this.indexName),
+      })),
+    };
+  }
+
   async search(
     query: string,
     options: import("../pipeline/types").SearchOptions = {}
   ): Promise<SearchResults> {
     this.assertOpen();
-    return unwrapStore(await searchBm25(this.store, query, options));
+    return this.decorateSearchResults(
+      unwrapStore(await searchBm25(this.store, query, options))
+    );
   }
 
   async vsearch(
@@ -409,17 +429,19 @@ class GnoClientImpl implements GnoClient {
         });
       }
 
-      return unwrapStore(
-        await searchVectorWithEmbedding(
-          {
-            store: this.store,
-            vectorIndex: ports.vectorIndex,
-            embedPort: ports.embedPort,
-            config: this.config,
-          },
-          query,
-          new Float32Array(queryEmbedResult.value),
-          options
+      return this.decorateSearchResults(
+        unwrapStore(
+          await searchVectorWithEmbedding(
+            {
+              store: this.store,
+              vectorIndex: ports.vectorIndex,
+              embedPort: ports.embedPort,
+              config: this.config,
+            },
+            query,
+            new Float32Array(queryEmbedResult.value),
+            options
+          )
         )
       );
     } finally {
@@ -461,18 +483,20 @@ class GnoClientImpl implements GnoClient {
     });
 
     try {
-      return unwrapStore(
-        await searchHybrid(
-          {
-            store: this.store,
-            config: this.config,
-            vectorIndex: ports.vectorIndex,
-            embedPort: ports.embedPort,
-            expandPort: ports.expandPort,
-            rerankPort: ports.rerankPort,
-          },
-          query,
-          options
+      return this.decorateSearchResults(
+        unwrapStore(
+          await searchHybrid(
+            {
+              store: this.store,
+              config: this.config,
+              vectorIndex: ports.vectorIndex,
+              embedPort: ports.embedPort,
+              expandPort: ports.expandPort,
+              rerankPort: ports.rerankPort,
+            },
+            query,
+            options
+          )
         )
       );
     } finally {
@@ -606,17 +630,48 @@ class GnoClientImpl implements GnoClient {
 
   async get(ref: string, options: GnoGetOptions = {}) {
     this.assertOpen();
-    return getDocumentByRef(this.store, this.config, ref, options);
+    const explicitIndex = ref.startsWith("gno://")
+      ? parseUri(ref)?.indexName
+      : undefined;
+    const result = await getDocumentByRef(
+      this.store,
+      this.config,
+      ref,
+      options
+    );
+    return {
+      ...result,
+      uri: decorateUriForIndex(result.uri, explicitIndex ?? this.indexName),
+    };
   }
 
   async multiGet(refs: string[], options: GnoMultiGetOptions = {}) {
     this.assertOpen();
-    return multiGetDocuments(this.store, this.config, refs, options);
+    const result = await multiGetDocuments(
+      this.store,
+      this.config,
+      refs,
+      options
+    );
+    return {
+      ...result,
+      documents: result.documents.map((doc) => ({
+        ...doc,
+        uri: decorateUriForIndex(doc.uri, this.indexName),
+      })),
+    };
   }
 
   async list(options: GnoListOptions = {}) {
     this.assertOpen();
-    return listDocuments(this.store, options);
+    const result = await listDocuments(this.store, options);
+    return {
+      ...result,
+      documents: result.documents.map((doc) => ({
+        ...doc,
+        uri: decorateUriForIndex(doc.uri, this.indexName),
+      })),
+    };
   }
 
   async status(): Promise<IndexStatus> {

package/src/store/sqlite/adapter.ts

@@ -10,6 +10,8 @@
 // CRITICAL: Import setup FIRST to configure custom SQLite before any Database use
 import "./setup";
 import { Database } from "bun:sqlite";
+// node:path basename: no Bun path utilities.
+import { basename } from "node:path";
 
 import type { Collection, Context, FtsTokenizer } from "../../config/types";
 import type {
@@ -42,7 +44,7 @@ import type {
 } from "../types";
 import type { SqliteDbProvider } from "./types";
 
-import { buildUri, deriveDocid } from "../../app/constants";
+import { buildUri, deriveDocid, stripUriIndex } from "../../app/constants";
 import { normalizeWikiName, stripWikiMdExt } from "../../core/links";
 import { migrations, runMigrations } from "../migrations";
 import { err, ok } from "../types";
@@ -675,9 +677,10 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
   ): Promise<StoreResult<DocumentRow | null>> {
     try {
       const db = this.ensureOpen();
+      const canonicalUri = stripUriIndex(uri);
       const row = db
         .query<DbDocumentRow, [string]>("SELECT * FROM documents WHERE uri = ?")
-        .get(uri);
+        .get(canonicalUri);
 
       return ok(row ? mapDocumentRow(row) : null);
     } catch (cause) {
@@ -2750,11 +2753,9 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
 
       // Derive indexName from dbPath (basename without extension)
       const indexName =
-        this.dbPath
-          .split("/")
-          .pop()
-          ?.replace(SQLITE_EXT_REGEX, "")
-          ?.replace(INDEX_PREFIX_REGEX, "") || "default";
+        basename(this.dbPath)
+          .replace(SQLITE_EXT_REGEX, "")
+          .replace(INDEX_PREFIX_REGEX, "") || "default";
 
       // Get collection stats with chunk counts
       interface CollectionStat {

package/src/store/vector/sqlite-vec.ts

@@ -66,6 +66,14 @@ export interface VectorIndexOptions {
   distanceMetric?: "cosine" | "l2";
 }
 
+const SQLITE_VEC_GUIDANCE =
+  "Run `gno doctor` for sqlite-vec diagnostics. On macOS, verify Homebrew SQLite/sqlite-vec installation and see TROUBLESHOOTING.md.";
+
+function formatUnavailableMessage(loadError?: string): string {
+  const reason = loadError ? ` Reason: ${loadError}` : "";
+  return `Vector search requires sqlite-vec. Embeddings are stored, but KNN search is disabled.${reason} ${SQLITE_VEC_GUIDANCE}`;
+}
+
 /**
  * Create a VectorIndexPort for a specific model.
  * sqlite-vec is optional - storage works without it, search disabled.
@@ -147,6 +155,7 @@ export async function createVectorIndexPort(
     model,
     dimensions,
     loadError,
+    guidance: searchAvailable ? undefined : SQLITE_VEC_GUIDANCE,
     get vecDirty() {
       return vecDirty;
     },
@@ -235,10 +244,7 @@ export async function createVectorIndexPort(
     ): Promise<StoreResult<VectorSearchResult[]>> {
       if (!(searchAvailable && searchStmt)) {
         return Promise.resolve(
-          err(
-            "VEC_SEARCH_UNAVAILABLE",
-            "Vector search requires sqlite-vec. Embeddings stored but KNN search disabled."
-          )
+          err("VEC_SEARCH_UNAVAILABLE", formatUnavailableMessage(loadError))
         );
       }
 

package/src/store/vector/types.ts

@@ -60,6 +60,8 @@ export interface VectorIndexPort {
   readonly dimensions: number;
   /** Error message if sqlite-vec failed to load (for diagnostics) */
   readonly loadError?: string;
+  /** User-facing recovery guidance when search is unavailable */
+  readonly guidance?: string;
   /** True if vec0 inserts failed during this session (needs sync) */
   vecDirty: boolean;