@gmickel/gno 1.35.0 → 1.36.0

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
+  );
+}