@gmickel/gno 1.12.2 → 1.12.4

package/README.md

@@ -197,7 +197,7 @@ Manage the detached process with `gno daemon --status` and `gno daemon --stop`.
 
 ### Install GNO
 
-Requires [Bun](https://bun.sh/) >= 1.0.0.
+Requires [Bun](https://bun.sh/) >= 1.3.0.
 
 ```bash
 bun install -g @gmickel/gno

package/assets/skill/SKILL.md

@@ -161,7 +161,7 @@ gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-ge
 When using GNO through MCP, prefer this retrieval order:
 
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.
-2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, and often `line`; pass `graph: true` only when linked context is worth the extra latency.
+2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
 3. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
 4. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
 5. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
@@ -227,7 +227,9 @@ gno graph --from gno://notes/a.md --to gno://notes/b.md
 ```
 
 Non-default index search results may include `?index=<name>` on `gno://` URIs.
-Keep that query string when passing the URI to `gno get`.
+Keep that query string when passing the URI to `gno get`, SDK `get()`, MCP
+`gno_get`, or an MCP resource read: it selects the named database. Batch reads
+must contain refs for one index; split mixed-index results before `multi-get`.
 
 ## Important: Embedding After Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.12.2",
+  "version": "1.12.4",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -71,6 +71,7 @@
     "eval:hybrid:baseline": "bun scripts/hybrid-benchmark.ts --write",
     "eval:hybrid:delta": "bun scripts/hybrid-benchmark.ts --delta",
     "bench:ast-chunking": "bun scripts/ast-chunking-benchmark.ts",
+    "smoke:serve-shutdown": "bun scripts/serve-shutdown-smoke.ts",
     "bench:code-embeddings": "bun scripts/code-embedding-benchmark.ts",
     "bench:code-embeddings:write": "bun scripts/code-embedding-benchmark.ts --write",
     "bench:general-embeddings": "bun scripts/general-embedding-benchmark.ts",

package/src/core/context-resolver.ts

@@ -0,0 +1,285 @@
+import type { ContextRow, StorePort } from "../store/types";
+
+import { parseUri } from "../app/constants";
+
+const CARRIAGE_RETURN_PATTERN = /\r\n?/g;
+const BYTE_ORDER_MARK_PATTERN = /^\uFEFF/u;
+
+export interface ContextDocumentIdentity {
+  collection: string;
+  relPath: string;
+}
+
+export interface ContextProvenance {
+  scopeType: ContextRow["scopeType"];
+  scopeKey: string;
+  normalizedScopeKey: string;
+  text: string;
+  syncedAt: string;
+}
+
+export interface ResolvedContext {
+  /** Backward-compatible context value exposed on retrieval results. */
+  text: string;
+  /** Ordered source records used to assemble `text`. */
+  provenance: ContextProvenance[];
+}
+
+interface NormalizedIdentity {
+  collection: string;
+  relPath: string;
+}
+
+interface MatchingContext extends ContextProvenance {
+  depth: number;
+}
+
+interface ContextSnapshot {
+  generation: number;
+  contexts: ContextRow[];
+}
+
+function normalizeRelativePath(path: string): string | null {
+  if (path.includes("\0")) {
+    return null;
+  }
+
+  const normalizedSeparators = path.replaceAll("\\", "/");
+  if (normalizedSeparators.startsWith("/")) {
+    return null;
+  }
+
+  const segments: string[] = [];
+  for (const segment of normalizedSeparators.split("/")) {
+    if (!segment || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      return null;
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+
+function normalizeIdentity(
+  identity: ContextDocumentIdentity
+): NormalizedIdentity | null {
+  const collection = identity.collection.trim();
+  const relPath = normalizeRelativePath(identity.relPath);
+  if (!collection || collection.includes("/") || relPath === null) {
+    return null;
+  }
+  return { collection, relPath };
+}
+
+function normalizeText(text: string): string {
+  return text
+    .replace(BYTE_ORDER_MARK_PATTERN, "")
+    .replace(CARRIAGE_RETURN_PATTERN, "\n")
+    .normalize("NFC")
+    .trim();
+}
+
+function byteKey(text: string): string {
+  return [...new TextEncoder().encode(text)].join(",");
+}
+
+function matchesPathPrefix(relPath: string, prefix: string): boolean {
+  return (
+    prefix === "" || relPath === prefix || relPath.startsWith(`${prefix}/`)
+  );
+}
+
+function normalizeContext(
+  context: ContextRow,
+  identity: NormalizedIdentity
+): MatchingContext | null {
+  const text = normalizeText(context.text);
+  if (!text) {
+    return null;
+  }
+
+  if (context.scopeType === "global") {
+    if (context.scopeKey !== "/") {
+      return null;
+    }
+    return {
+      ...context,
+      normalizedScopeKey: "/",
+      text,
+      depth: 0,
+    };
+  }
+
+  if (context.scopeType === "collection") {
+    const collection = context.scopeKey.endsWith(":")
+      ? context.scopeKey.slice(0, -1)
+      : "";
+    if (!collection || collection !== identity.collection) {
+      return null;
+    }
+    return {
+      ...context,
+      normalizedScopeKey: `${collection}:`,
+      text,
+      depth: 0,
+    };
+  }
+
+  const parsed = parseUri(context.scopeKey);
+  if (!parsed || parsed.collection !== identity.collection) {
+    return null;
+  }
+  const prefix = normalizeRelativePath(parsed.path);
+  if (prefix === null || !matchesPathPrefix(identity.relPath, prefix)) {
+    return null;
+  }
+
+  return {
+    ...context,
+    normalizedScopeKey: `gno://${parsed.collection}/${prefix}`,
+    text,
+    depth: prefix ? prefix.split("/").length : 0,
+  };
+}
+
+function compareMatchingContexts(
+  left: MatchingContext,
+  right: MatchingContext
+): number {
+  const typeOrder = { global: 0, collection: 1, prefix: 2 } as const;
+  const typeDifference = typeOrder[left.scopeType] - typeOrder[right.scopeType];
+  if (typeDifference !== 0) {
+    return typeDifference;
+  }
+  if (left.depth !== right.depth) {
+    return left.depth - right.depth;
+  }
+  const scopeDifference = left.normalizedScopeKey.localeCompare(
+    right.normalizedScopeKey
+  );
+  if (scopeDifference !== 0) {
+    return scopeDifference;
+  }
+  const sourceDifference = left.scopeKey.localeCompare(right.scopeKey);
+  return sourceDifference !== 0
+    ? sourceDifference
+    : byteKey(left.text).localeCompare(byteKey(right.text));
+}
+
+/** Resolve a context snapshot against one canonical collection-relative identity. */
+export function resolveContextSnapshot(
+  contexts: ContextRow[],
+  identity: ContextDocumentIdentity
+): ResolvedContext | undefined {
+  const normalizedIdentity = normalizeIdentity(identity);
+  if (!normalizedIdentity) {
+    return;
+  }
+
+  const matching = contexts
+    .map((context) => normalizeContext(context, normalizedIdentity))
+    .filter((context): context is MatchingContext => context !== null)
+    .sort(compareMatchingContexts);
+
+  const seenRecords = new Set<string>();
+  const seenTexts = new Set<string>();
+  const provenance: ContextProvenance[] = [];
+  const joinedTexts: string[] = [];
+
+  for (const context of matching) {
+    const textKey = byteKey(context.text);
+    const recordKey = `${context.scopeType}\0${context.normalizedScopeKey}\0${textKey}`;
+    if (seenRecords.has(recordKey)) {
+      continue;
+    }
+    seenRecords.add(recordKey);
+    provenance.push({
+      scopeType: context.scopeType,
+      scopeKey: context.scopeKey,
+      normalizedScopeKey: context.normalizedScopeKey,
+      text: context.text,
+      syncedAt: context.syncedAt,
+    });
+    if (!seenTexts.has(textKey)) {
+      seenTexts.add(textKey);
+      joinedTexts.push(context.text);
+    }
+  }
+
+  if (provenance.length === 0) {
+    return;
+  }
+  return { text: joinedTexts.join("\n\n"), provenance };
+}
+
+export function contextIdentityFromUri(
+  uri: string
+): ContextDocumentIdentity | null {
+  const parsed = parseUri(uri);
+  if (!parsed) {
+    return null;
+  }
+  const identity = normalizeIdentity({
+    collection: parsed.collection,
+    relPath: parsed.path,
+  });
+  return identity ? { ...identity } : null;
+}
+
+/**
+ * Request-local resolver backed by one store snapshot per context generation.
+ * Failed context reads degrade to no context and are retried without retaining
+ * the previous generation, so retrieval never receives stale guidance.
+ */
+export class ContextResolver {
+  private snapshot?: ContextSnapshot;
+
+  constructor(private readonly store: StorePort) {}
+
+  async resolve(
+    identity: ContextDocumentIdentity
+  ): Promise<ResolvedContext | undefined> {
+    const [resolved] = await this.resolveMany([identity]);
+    return resolved;
+  }
+
+  async resolveUri(uri: string): Promise<ResolvedContext | undefined> {
+    const identity = contextIdentityFromUri(uri);
+    return identity ? this.resolve(identity) : undefined;
+  }
+
+  async resolveMany(
+    identities: ContextDocumentIdentity[]
+  ): Promise<Array<ResolvedContext | undefined>> {
+    if (identities.length === 0) {
+      return [];
+    }
+    const contexts = await this.loadCurrentContexts();
+    return identities.map((identity) =>
+      resolveContextSnapshot(contexts, identity)
+    );
+  }
+
+  private async loadCurrentContexts(): Promise<ContextRow[]> {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const generation = this.store.getContextGeneration();
+      if (this.snapshot?.generation === generation) {
+        return this.snapshot.contexts;
+      }
+
+      this.snapshot = undefined;
+      const contextsResult = await this.store.getContexts();
+      if (!contextsResult.ok) {
+        return [];
+      }
+
+      if (this.store.getContextGeneration() === generation) {
+        this.snapshot = { generation, contexts: contextsResult.value };
+        return this.snapshot.contexts;
+      }
+    }
+    return [];
+  }
+}

package/src/core/indexed-reference.ts

@@ -0,0 +1,68 @@
+import { DEFAULT_INDEX_NAME, parseUri } from "../app/constants";
+import { parseRef } from "./ref-parser";
+
+export interface EffectiveIndexResolution {
+  indexName?: string;
+}
+
+function normalizeIndexName(indexName?: string): string {
+  const normalized = indexName?.trim();
+  return normalized || DEFAULT_INDEX_NAME;
+}
+
+export function indexesMatch(left?: string, right?: string): boolean {
+  return normalizeIndexName(left) === normalizeIndexName(right);
+}
+
+export function getExplicitRefIndex(ref: string): string | undefined {
+  const parsed = parseRef(ref);
+  if ("error" in parsed || parsed.type !== "uri") {
+    return;
+  }
+  return parseUri(parsed.value)?.indexName;
+}
+
+export function resolveEffectiveIndex(
+  refs: string[],
+  activeIndexName?: string
+):
+  | { ok: true; value: EffectiveIndexResolution }
+  | { ok: false; error: string } {
+  const explicitIndexes = new Set<string>();
+  let hasUnindexedRef = false;
+
+  for (const ref of refs) {
+    const explicitIndex = getExplicitRefIndex(ref);
+    if (explicitIndex) {
+      explicitIndexes.add(explicitIndex);
+    } else {
+      hasUnindexedRef = true;
+    }
+  }
+
+  if (explicitIndexes.size > 1) {
+    return {
+      ok: false,
+      error: `References cannot mix explicit indexes: ${[...explicitIndexes]
+        .sort()
+        .join(", ")}`,
+    };
+  }
+
+  const explicitIndex = [...explicitIndexes][0];
+  if (
+    explicitIndex &&
+    hasUnindexedRef &&
+    !indexesMatch(explicitIndex, activeIndexName)
+  ) {
+    return {
+      ok: false,
+      error: `References cannot mix indexed refs (${explicitIndex}) with unindexed refs while the active index is ${normalizeIndexName(activeIndexName)}`,
+    };
+  }
+
+  return {
+    ok: true,
+    value: { indexName: explicitIndex ?? activeIndexName },
+  };
+}

package/src/core/ref-parser.ts

@@ -141,5 +141,10 @@ export function splitRefs(refs: string[]): string[] {
  * Check if a ref contains glob characters.
  */
 export function isGlobPattern(ref: string): boolean {
-  return GLOB_PATTERN.test(ref);
+  const queryIndex = ref.indexOf("?");
+  const globCandidate =
+    ref.startsWith("gno://") && queryIndex >= 0
+      ? ref.slice(0, queryIndex)
+      : ref;
+  return GLOB_PATTERN.test(globCandidate);
 }

package/src/index.ts

@@ -20,8 +20,17 @@ async function cleanupAndExit(code: number): Promise<never> {
   process.exit(code);
 }
 
-// SIGINT handler for graceful shutdown
+let interruptExitCode: 0 | 130 = 0;
+
+// Long-running commands install their own SIGINT handler and must finish their
+// resource teardown before this bootstrap exits. Short-lived commands have no
+// owner, so retain the immediate interrupt behavior for them.
 process.on("SIGINT", () => {
+  if (process.listenerCount("SIGINT") > 1) {
+    return;
+  }
+
+  interruptExitCode = 130;
   process.stderr.write("\nInterrupted\n");
   cleanupAndExit(130).catch(() => {
     // Ignore cleanup errors on exit
@@ -30,7 +39,7 @@ process.on("SIGINT", () => {
 
 // Run CLI and exit
 runCli(process.argv)
-  .then((code) => cleanupAndExit(code))
+  .then((code) => cleanupAndExit(interruptExitCode || code))
   .catch((err) => {
     process.stderr.write(
       `Fatal error: ${err instanceof Error ? err.message : String(err)}\n`