@gmickel/gno 1.35.0 → 1.36.1

package/src/core/peek.ts

@@ -0,0 +1,202 @@
+/**
+ * Shared peek snapshot builder for CLI and later MCP.
+ * Metadata-only: never opens the model cache, resolves model URIs, or activates.
+ *
+ * @module src/core/peek
+ */
+
+// node:path — no Bun path utils
+import { join as pathJoin } from "node:path";
+
+import type { DocumentRow, IndexStatus } from "../store/types";
+
+import { DEFAULT_INDEX_NAME, VERSION, getIndexDbPath } from "../app/constants";
+import {
+  isProcessAlive,
+  readPidFile,
+  resolveProcessPaths,
+} from "../cli/detach";
+import { CliError } from "../cli/errors";
+import { isInitialized, loadConfig } from "../config";
+import { SqliteAdapter } from "../store/sqlite/adapter";
+
+export const PEEK_SCHEMA_VERSION = "peek@1.0" as const;
+export const PEEK_RECENT_LIMIT = 10;
+
+export interface PeekCounts {
+  documents: number;
+  collections: number;
+}
+
+export interface PeekBacklog {
+  pending: number;
+  failed: number;
+}
+
+export interface PeekRecentItem {
+  docid: string;
+  uri: string;
+  title: string | null;
+  collection: string;
+  absPath: string;
+  modifiedAt: string;
+}
+
+export interface PeekServe {
+  running: boolean;
+  url: string | null;
+}
+
+export interface PeekSnapshot {
+  schemaVersion: typeof PEEK_SCHEMA_VERSION;
+  gnoVersion: string;
+  generatedAt: string;
+  initialized: boolean;
+  indexName: string;
+  counts: PeekCounts | null;
+  backlog: PeekBacklog | null;
+  lastIndexedAt: string | null;
+  recent: PeekRecentItem[];
+  serve: PeekServe;
+}
+
+export interface BuildPeekOptions {
+  configPath?: string;
+  indexName?: string;
+}
+
+function asRuntimeError(error: unknown, fallback: string): CliError {
+  if (error instanceof CliError) {
+    return error;
+  }
+  return new CliError(
+    "RUNTIME",
+    error instanceof Error ? error.message : fallback
+  );
+}
+
+async function readServeLiveness(): Promise<PeekServe> {
+  try {
+    const { pidFile } = resolveProcessPaths("serve");
+    const payload = await readPidFile(pidFile);
+    if (!payload || !isProcessAlive(payload.pid) || payload.port == null) {
+      return { running: false, url: null };
+    }
+    return {
+      running: true,
+      url: `http://localhost:${payload.port}`,
+    };
+  } catch (error) {
+    throw asRuntimeError(error, "Failed to read serve process state");
+  }
+}
+
+function mapRecent(
+  documents: DocumentRow[],
+  status: IndexStatus
+): PeekRecentItem[] {
+  const collectionPaths = new Map(
+    status.collections.map((collection) => [collection.name, collection.path])
+  );
+  return documents.slice(0, PEEK_RECENT_LIMIT).map((doc) => {
+    const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+    const collectionPath = collectionPaths.get(doc.collection) ?? "";
+    return {
+      docid: doc.docid,
+      uri: doc.uri,
+      title: doc.title,
+      collection: doc.collection,
+      absPath: pathJoin(collectionPath, sourceRelPath),
+      modifiedAt: doc.sourceMtime,
+    };
+  });
+}
+
+function emptySnapshot(
+  indexName: string,
+  generatedAt: string,
+  serve: PeekServe
+): PeekSnapshot {
+  return {
+    schemaVersion: PEEK_SCHEMA_VERSION,
+    gnoVersion: VERSION,
+    generatedAt,
+    initialized: false,
+    indexName,
+    counts: null,
+    backlog: null,
+    lastIndexedAt: null,
+    recent: [],
+    serve,
+  };
+}
+
+/**
+ * Build a peek@1.0 snapshot. Throws CliError("RUNTIME") on any subquery
+ * failure so callers never emit a half-filled payload.
+ */
+export async function buildPeekSnapshot(
+  options: BuildPeekOptions = {}
+): Promise<PeekSnapshot> {
+  const generatedAt = new Date().toISOString();
+  const requestedIndex = options.indexName ?? DEFAULT_INDEX_NAME;
+  const serve = await readServeLiveness();
+
+  const initialized = await isInitialized(options.configPath);
+  if (!initialized) {
+    return emptySnapshot(requestedIndex, generatedAt, serve);
+  }
+
+  const configResult = await loadConfig(options.configPath);
+  if (!configResult.ok) {
+    throw new CliError("RUNTIME", configResult.error.message);
+  }
+
+  const store = new SqliteAdapter();
+  const openResult = await store.open(
+    getIndexDbPath(options.indexName),
+    configResult.value.ftsTokenizer
+  );
+  if (!openResult.ok) {
+    throw new CliError("RUNTIME", openResult.error.message);
+  }
+
+  try {
+    const statusResult = await store.getStatus();
+    if (!statusResult.ok) {
+      throw new CliError("RUNTIME", statusResult.error.message);
+    }
+
+    const recentResult = await store.listDocumentsPaginated({
+      limit: PEEK_RECENT_LIMIT,
+      offset: 0,
+    });
+    if (!recentResult.ok) {
+      throw new CliError("RUNTIME", recentResult.error.message);
+    }
+
+    const status = statusResult.value;
+    return {
+      schemaVersion: PEEK_SCHEMA_VERSION,
+      gnoVersion: VERSION,
+      generatedAt,
+      initialized: true,
+      indexName: status.indexName,
+      counts: {
+        documents: status.activeDocuments,
+        collections: status.collections.length,
+      },
+      backlog: {
+        pending: status.embeddingBacklog,
+        failed: status.recentErrors,
+      },
+      lastIndexedAt: status.lastUpdatedAt,
+      recent: mapRecent(recentResult.value.documents, status),
+      serve,
+    };
+  } catch (error) {
+    throw asRuntimeError(error, "Failed to build peek snapshot");
+  } finally {
+    await store.close();
+  }
+}

package/src/mcp/http-egress.ts

@@ -56,6 +56,7 @@ export const MCP_HTTP_EGRESS_TOOLS = {
   gno_search: "snippet",
   gno_section: "metadata",
   gno_similar: "snippet",
+  gno_peek: "metadata",
   gno_status: "metadata",
   gno_sync: "metadata",
   gno_trace_delete: "retrieval_trace",

package/src/mcp/tools/index.ts

@@ -65,6 +65,7 @@ import {
 import { handleListJobs } from "./list-jobs";
 import { handleListTags } from "./list-tags";
 import { handleMultiGet } from "./multi-get";
+import { handlePeek, PEEK_MCP_ANNOTATIONS } from "./peek";
 import { handleQuery, handleQueryDiagnose } from "./query";
 import { handleRemoveCollection } from "./remove-collection";
 import { handleSearch } from "./search";
@@ -129,6 +130,7 @@ export const MCP_TOOL_DESCRIPTIONS = {
     "Retrieve multiple documents by refs array or glob pattern. Use after gno_search/gno_query to batch top result URIs/docids; set maxBytes and lineNumbers to control context size.",
   section:
     "Create or resolve a durable SectionTargetV1 against one indexed document. action=create needs ref plus exactly one of anchor|line; action=resolve needs ref plus target. Exact/recovered include citation (uri, anchor, title, inclusive lines, fingerprint); ambiguous/stale/missing omit citation and are not safe to navigate or cite. Read-only — does not write or persist targets. Follow navigable ranges with gno_get fromLine/lineCount.",
+  peek: "Cheap peek@1.0 snapshot: initialized flag, document/collection counts, embedding backlog, recent files, and serve liveness. Model-free — never initializes embeddings or models. Use for counts/backlog/recent/serve questions; use gno_status for full health and activation.",
   status:
     "Get index health: collection count, document count, chunk count, embedding backlog, and per-collection stats. Check first when vector/hybrid results look stale or unavailable.",
   audit:
@@ -664,6 +666,8 @@ const multiGetInputSchema = z.object({
     .describe("Include line numbers in output"),
 });
 
+const peekInputSchema = z.object({});
+
 const statusInputSchema = z.object({});
 
 const jobStatusInputSchema = z.object({
@@ -1086,6 +1090,16 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleMultiGet(args, ctx)
   );
 
+  server.registerTool(
+    "gno_peek",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.peek,
+      inputSchema: peekInputSchema,
+      annotations: PEEK_MCP_ANNOTATIONS,
+    },
+    (args) => handlePeek(args, ctx)
+  );
+
   server.tool(
     "gno_status",
     MCP_TOOL_DESCRIPTIONS.status,

package/src/mcp/tools/peek.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP gno_peek tool — cheap peek@1.0 snapshot, model-free.
+ *
+ * @module src/mcp/tools/peek
+ */
+
+import type { PeekSnapshot } from "../../core/peek";
+import type { ToolContext } from "../server";
+
+import { buildPeekSnapshot } from "../../core/peek";
+import { runTool, type ToolResult } from "./index";
+
+type PeekInput = Record<string, never>;
+
+export const PEEK_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+function formatPeek(snapshot: PeekSnapshot): string {
+  const lines = [
+    `schema: ${snapshot.schemaVersion}`,
+    `gno: ${snapshot.gnoVersion}`,
+    `index: ${snapshot.indexName}`,
+    `initialized: ${snapshot.initialized ? "yes" : "no"}`,
+  ];
+  if (snapshot.counts) {
+    lines.push(
+      `documents: ${snapshot.counts.documents}`,
+      `collections: ${snapshot.counts.collections}`
+    );
+  }
+  if (snapshot.backlog) {
+    lines.push(
+      `backlog: ${snapshot.backlog.pending} pending, ${snapshot.backlog.failed} failed`
+    );
+  }
+  if (snapshot.lastIndexedAt) {
+    lines.push(`lastIndexedAt: ${snapshot.lastIndexedAt}`);
+  }
+  lines.push(
+    snapshot.serve.running && snapshot.serve.url
+      ? `serve: ${snapshot.serve.url}`
+      : "serve: down"
+  );
+  if (snapshot.recent.length > 0) {
+    lines.push("recent:");
+    for (const item of snapshot.recent) {
+      const label = item.title ?? item.uri;
+      lines.push(`  ${item.docid} ${label}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Handle gno_peek tool call.
+ *
+ * Uninitialized (no config / no store) is a success payload, not an error.
+ * Never probes serve over HTTP; the shared builder uses pid-file liveness.
+ */
+export function handlePeek(
+  _args: PeekInput,
+  ctx: ToolContext
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_peek",
+    async () =>
+      buildPeekSnapshot({
+        configPath: ctx.actualConfigPath,
+        indexName: ctx.indexName,
+      }),
+    formatPeek
+  );
+}

package/src/pipeline/hybrid.ts

@@ -58,6 +58,7 @@ import {
 } from "./query-modes";
 import { rerankCandidates } from "./rerank";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   isWithinTemporalRange,
   resolveRecencyTimestamp,
@@ -1003,6 +1004,7 @@ export async function searchHybrid(
           ) ?? chunk);
 
     let snippet = snippetChunk.text;
+    let snippetStartLine = snippetChunk.startLine;
     let snippetRange: { startLine: number; endLine: number } | undefined = {
       startLine: snippetChunk.startLine,
       endLine: snippetChunk.endLine,
@@ -1021,6 +1023,18 @@ export async function searchHybrid(
         snippetRange = undefined; // Full content has no range
       }
       // Fallback to chunk text if content unavailable
+    } else {
+      const cleanedSnippet = cleanDisplaySnippet(
+        snippetChunk.text,
+        snippetChunk.text
+      );
+      snippet = cleanedSnippet.text;
+      snippetStartLine =
+        snippetChunk.startLine + cleanedSnippet.startLineOffset;
+      snippetRange = {
+        startLine: snippetStartLine,
+        endLine: snippetChunk.endLine,
+      };
     }
 
     for (const doc of candidateDocs) {
@@ -1050,7 +1064,7 @@ export async function searchHybrid(
         title: doc.title ?? undefined,
         contentType: doc.contentType ?? undefined,
         categories: doc.categories ?? undefined,
-        line: snippetChunk.startLine,
+        line: snippetStartLine,
         snippet,
         snippetLanguage: chunk.language ?? undefined,
         snippetRange,

package/src/pipeline/search.ts

@@ -30,6 +30,7 @@ import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
   resolveTemporalRange,
@@ -107,6 +108,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
   // Determine snippet content and range
   let snippet: string;
   let snippetRange: { startLine: number; endLine: number } | undefined;
+  let line = chunk?.startLine;
 
   if (options?.full && fullContent) {
     // --full: use full content, no range (full doc)
@@ -117,11 +119,18 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     snippet = chunk.text;
     snippetRange = { startLine: chunk.startLine, endLine: chunk.endLine };
   } else {
-    // Default: use FTS snippet or chunk text
-    snippet = fts.snippet ?? chunk?.text ?? "";
-    snippetRange = chunk
-      ? { startLine: chunk.startLine, endLine: chunk.endLine }
-      : undefined;
+    // Default: FTS snippet or chunk text, with leading frontmatter stripped
+    const cleaned = cleanDisplaySnippet(
+      fts.snippet ?? chunk?.text ?? "",
+      chunk?.text
+    );
+    snippet = cleaned.text;
+    if (chunk) {
+      line = chunk.startLine + cleaned.startLineOffset;
+      snippetRange = { startLine: line, endLine: chunk.endLine };
+    } else {
+      snippetRange = undefined;
+    }
   }
 
   const result: SearchResult = {
@@ -131,7 +140,7 @@ function buildSearchResult(ctx: BuildResultContext): SearchResult {
     title: fts.title,
     contentType: fts.contentType,
     categories: fts.categories,
-    line: chunk?.startLine,
+    line,
     snippet,
     snippetLanguage: chunk?.language ?? undefined,
     snippetRange,

package/src/pipeline/snippet.ts

@@ -0,0 +1,203 @@
+/**
+ * Display-layer snippet cleaning for search/query results.
+ * Strips leading YAML frontmatter so snippets prefer prose. Does not change
+ * indexed text, `--full` content, or `--line-numbers` raw chunks.
+ *
+ * @module src/pipeline/snippet
+ */
+
+import { stripFrontmatter } from "../ingestion/frontmatter";
+
+/** FTS5 highlight markers from snippet(documents_fts, ..., '<mark>', '</mark>', '...', 32). */
+const MARK_TAG_REGEX = /<\/?mark>/g;
+
+/** Leading blank lines after a closed frontmatter fence. */
+const LEADING_BLANK_LINES_REGEX = /^(?:[ \t]*\r?\n)+/;
+
+/** YAML mapping line (`key: value` or `key:`). */
+const YAML_MAPPING_LINE_REGEX = /^[\w./-]+\s*:/;
+
+/** YAML sequence item. */
+const YAML_SEQUENCE_LINE_REGEX = /^- /;
+
+export interface DisplaySnippet {
+  text: string;
+  /**
+   * Lines to add to the chunk's startLine when the emitted text is derived
+   * from stripped chunk prose (not a kept FTS window).
+   */
+  startLineOffset: number;
+  /** True when a frontmatter-dominated FTS snippet was replaced by chunk prose. */
+  usedChunkFallback: boolean;
+}
+
+/**
+ * Clean a default-path snippet: strip a leading closed YAML fence, or replace
+ * an FTS window that is only frontmatter with stripped chunk prose.
+ * Never returns an empty string when the original text had content.
+ */
+export function cleanDisplaySnippet(
+  snippet: string,
+  chunkText?: string
+): DisplaySnippet {
+  const strippedSnippet = stripLeadingFrontmatterBlock(snippet);
+  if (strippedSnippet.didStrip) {
+    return {
+      text: strippedSnippet.text,
+      startLineOffset: strippedSnippet.lineCount,
+      usedChunkFallback: false,
+    };
+  }
+
+  const afterEmbeddedFence = proseAfterEmbeddedFrontmatterFence(snippet);
+  if (afterEmbeddedFence !== undefined) {
+    const cleanedChunk =
+      chunkText === undefined
+        ? undefined
+        : stripLeadingFrontmatterBlock(chunkText);
+    return {
+      text: afterEmbeddedFence,
+      startLineOffset: cleanedChunk?.didStrip ? cleanedChunk.lineCount : 0,
+      usedChunkFallback: false,
+    };
+  }
+
+  const canFallback =
+    chunkText !== undefined &&
+    chunkText !== snippet &&
+    isFrontmatterDominatedSnippet(snippet);
+  if (canFallback) {
+    const cleanedChunk = stripLeadingFrontmatterBlock(chunkText);
+    if (cleanedChunk.text.length > 0) {
+      return {
+        text: cleanedChunk.text,
+        startLineOffset: cleanedChunk.didStrip ? cleanedChunk.lineCount : 0,
+        usedChunkFallback: true,
+      };
+    }
+  }
+
+  return {
+    text: snippet,
+    startLineOffset: 0,
+    usedChunkFallback: false,
+  };
+}
+
+/** True for FTS-style snippets that are only (or start as) YAML frontmatter. */
+export function isFrontmatterDominatedSnippet(text: string): boolean {
+  const unmarked = text.replace(MARK_TAG_REGEX, "");
+  const trimmed = unmarked.trimStart();
+  const withoutLeadingEllipsis = trimmed.startsWith("...")
+    ? trimmed.slice(3).trimStart()
+    : trimmed;
+  if (withoutLeadingEllipsis.startsWith("---")) {
+    return true;
+  }
+
+  const contentLines = unmarked.split(/\r?\n/).filter((line) => {
+    const trimmedLine = line.trim();
+    return trimmedLine.length > 0 && trimmedLine !== "...";
+  });
+  if (contentLines.length === 0) {
+    return false;
+  }
+  if (contentLines.every(isYamlFrontmatterLine)) {
+    return true;
+  }
+  return proseAfterEmbeddedFrontmatterFence(text) !== undefined;
+}
+
+/**
+ * FTS windows often straddle the closing fence (`...yaml\n---\n# Heading`).
+ * Keep the prose after that fence when the prefix looks like YAML.
+ */
+function proseAfterEmbeddedFrontmatterFence(text: string): string | undefined {
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) {
+      continue;
+    }
+    if (line.replace(MARK_TAG_REGEX, "").trim() !== "---") {
+      continue;
+    }
+    const prefixLines = lines.slice(0, i);
+    if (!prefixLooksLikeFrontmatter(prefixLines)) {
+      continue;
+    }
+    const after = lines
+      .slice(i + 1)
+      .join("\n")
+      .replace(LEADING_BLANK_LINES_REGEX, "");
+    if (after.trim().length === 0) {
+      continue;
+    }
+    return after;
+  }
+  return undefined;
+}
+
+function prefixLooksLikeFrontmatter(lines: string[]): boolean {
+  const content = lines.filter((line) => {
+    const trimmed = line.replace(MARK_TAG_REGEX, "").trim();
+    return trimmed.length > 0 && trimmed !== "...";
+  });
+  if (content.length === 0) {
+    return true;
+  }
+  return content.every((line, index) => {
+    const trimmed = line.replace(MARK_TAG_REGEX, "").trim();
+    if (index === 0 && trimmed.startsWith("...")) {
+      return true;
+    }
+    return isYamlFrontmatterLine(trimmed);
+  });
+}
+
+function stripLeadingFrontmatterBlock(text: string): {
+  text: string;
+  didStrip: boolean;
+  lineCount: number;
+} {
+  const afterFence = stripFrontmatter(text);
+  if (afterFence === text) {
+    return { text, didStrip: false, lineCount: 0 };
+  }
+
+  const withoutBlanks = afterFence.replace(LEADING_BLANK_LINES_REGEX, "");
+  if (withoutBlanks.trim().length === 0) {
+    return { text, didStrip: false, lineCount: 0 };
+  }
+
+  const prefix = text.slice(0, text.length - withoutBlanks.length);
+  return {
+    text: withoutBlanks,
+    didStrip: true,
+    lineCount: countConsumedLines(prefix),
+  };
+}
+
+function isYamlFrontmatterLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (trimmed === "---") {
+    return true;
+  }
+  if (YAML_SEQUENCE_LINE_REGEX.test(trimmed)) {
+    return true;
+  }
+  return YAML_MAPPING_LINE_REGEX.test(trimmed);
+}
+
+function countConsumedLines(prefix: string): number {
+  if (prefix.length === 0) {
+    return 0;
+  }
+  let newlineCount = 0;
+  for (const char of prefix) {
+    if (char === "\n") {
+      newlineCount += 1;
+    }
+  }
+  return prefix.endsWith("\n") ? newlineCount : newlineCount + 1;
+}

package/src/pipeline/vsearch.ts

@@ -28,6 +28,7 @@ import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
 import { detectQueryLanguage } from "./query-language";
 import { attachSearchResultContexts } from "./result-context";
+import { cleanDisplaySnippet } from "./snippet";
 import {
   resolveRecencyTimestamp,
   isWithinTemporalRange,
@@ -236,6 +237,8 @@ export async function searchVectorWithEmbedding(
         continue;
       }
 
+      const cleanedSnippet = cleanDisplaySnippet(chunk.text, chunk.text);
+      const snippetStartLine = chunk.startLine + cleanedSnippet.startLineOffset;
       const scoredResult = applyContentTypeBoost(
         {
           docid: doc.docid,
@@ -244,11 +247,11 @@ export async function searchVectorWithEmbedding(
           title: doc.title ?? undefined,
           contentType: doc.contentType ?? undefined,
           categories: doc.categories ?? undefined,
-          line: chunk.startLine,
-          snippet: chunk.text,
+          line: snippetStartLine,
+          snippet: cleanedSnippet.text,
           snippetLanguage: chunk.language ?? undefined,
           snippetRange: {
-            startLine: chunk.startLine,
+            startLine: snippetStartLine,
             endLine: chunk.endLine,
           },
           source: {
@@ -338,6 +341,12 @@ export async function searchVectorWithEmbedding(
 
       const collectionPath = collectionPaths.get(doc.collection);
       const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+      const cleanedChunk = fullContent
+        ? undefined
+        : cleanDisplaySnippet(chunk.text, chunk.text);
+      const snippetStartLine = cleanedChunk
+        ? chunk.startLine + cleanedChunk.startLineOffset
+        : chunk.startLine;
 
       const result = applyContentTypeBoost(
         {
@@ -347,13 +356,13 @@ export async function searchVectorWithEmbedding(
           title: doc.title ?? undefined,
           contentType: doc.contentType ?? undefined,
           categories: doc.categories ?? undefined,
-          line: chunk.startLine,
-          snippet: fullContent ?? chunk.text,
+          line: snippetStartLine,
+          snippet: fullContent ?? cleanedChunk?.text ?? chunk.text,
           snippetLanguage: chunk.language ?? undefined,
           // --full: no snippetRange (full doc content)
           snippetRange: fullContent
             ? undefined
-            : { startLine: chunk.startLine, endLine: chunk.endLine },
+            : { startLine: snippetStartLine, endLine: chunk.endLine },
           source: {
             relPath: sourceRelPath,
             absPath: collectionPath