@gmickel/gno 1.19.0 → 1.21.0

package/src/cli/commands/ask.ts

@@ -14,6 +14,7 @@ import type {
 } from "../../llm/types";
 import type { AskOptions, AskResult, Citation } from "../../pipeline/types";
 
+import { buildVerifiedAsk } from "../../app/verified-ask";
 import {
   finishRetrievalTraceAfterError,
   retrievalTraceFilters,
@@ -39,6 +40,8 @@ import {
 } from "../progress";
 import { initStore } from "./shared";
 
+export { formatAsk } from "./ask-format";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
 // ─────────────────────────────────────────────────────────────────────────────
@@ -83,9 +86,11 @@ export async function ask(
   options: AskCommandOptions = {}
 ): Promise<AskCommandResult> {
   const limit = options.limit ?? 5;
+  const globals = getGlobals();
 
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: globals.index,
     collection: options.collection,
     syncConfig: false,
   });
@@ -103,7 +108,9 @@ export async function ask(
   let traceSession: RetrievalTraceSession | undefined;
 
   try {
-    const answerRequested = Boolean(options.answer && !options.noAnswer);
+    const verificationRequested = options.verify === true;
+    const answerRequested =
+      verificationRequested || Boolean(options.answer && !options.noAnswer);
     const embedUri = resolveModelUri(
       config,
       "embed",
@@ -111,7 +118,7 @@ export async function ask(
       options.collection
     );
     const expandUri =
-      !options.noExpand && !options.queryModes?.length
+      !verificationRequested && !options.noExpand && !options.queryModes?.length
         ? resolveModelUri(
             config,
             "expand",
@@ -136,6 +143,7 @@ export async function ask(
       query,
       filters: retrievalTraceFilters({ ...options, limit }),
       pipeline: "ask",
+      indexName: globals.index,
       modelUris: [embedUri, expandUri, answerUri, rerankUri].filter(
         (value): value is string => Boolean(value)
       ),
@@ -147,7 +155,6 @@ export async function ask(
     const llm = new LlmAdapter(config);
 
     // Resolve download policy from env/flags
-    const globals = getGlobals();
     const policy = resolveDownloadPolicy(process.env, {
       offline: globals.offline,
     });
@@ -254,6 +261,34 @@ export async function ask(
       };
     }
 
+    if (verificationRequested && answerPort) {
+      const verified = await buildVerifiedAsk(
+        query,
+        { ...options, limit },
+        {
+          store,
+          config,
+          indexName: globals.index,
+          vectorIndex,
+          embedPort,
+          rerankPort,
+          genPort: answerPort,
+          traceSession,
+        }
+      );
+      const finalized = await traceSession?.finish(
+        answerTraceTerminalStatus(verified.citations)
+      );
+      if (finalized && !finalized.ok) {
+        return { success: false, error: finalized.error.message };
+      }
+      return {
+        success: true,
+        data: verified,
+        metadata: traceSession?.metadata(),
+      };
+    }
+
     // Run hybrid search
     const searchResult = await searchHybrid(deps, query, {
       limit,
@@ -267,6 +302,8 @@ export async function ask(
       tagsAll: options.tagsAll,
       tagsAny: options.tagsAny,
       exclude: options.exclude,
+      minScore: options.minScore,
+      graph: options.graph,
       queryModes: options.queryModes,
       noExpand: options.noExpand,
       noRerank: options.noRerank,
@@ -394,149 +431,3 @@ export async function ask(
     await store.close();
   }
 }
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Formatters
-// ─────────────────────────────────────────────────────────────────────────────
-
-interface FormatOptions {
-  showSources?: boolean;
-}
-
-// oxlint-disable-next-line max-lines-per-function -- terminal formatting with conditional sections
-function formatTerminal(data: AskResult, opts: FormatOptions = {}): string {
-  const lines: string[] = [];
-  const hasAnswer = Boolean(data.answer);
-
-  // Show answer if present
-  if (data.answer) {
-    lines.push("Answer:");
-    lines.push(data.answer);
-    lines.push("");
-  }
-
-  // Show cited sources (only sources actually referenced in answer)
-  if (data.citations && data.citations.length > 0) {
-    lines.push("Cited Sources:");
-    for (let i = 0; i < data.citations.length; i++) {
-      const c = data.citations[i];
-      if (c) {
-        lines.push(`  [${i + 1}] ${c.uri}`);
-      }
-    }
-    lines.push("");
-  }
-
-  // Show all retrieved sources if:
-  // - No answer was generated (retrieval-only mode)
-  // - User explicitly requested with --show-sources
-  const showAllSources = !hasAnswer || opts.showSources;
-  if (showAllSources && data.results.length > 0) {
-    lines.push(hasAnswer ? "All Retrieved Sources:" : "Sources:");
-    for (const r of data.results) {
-      lines.push(`  [${r.docid}] ${r.uri}`);
-      if (r.title) {
-        lines.push(`    ${r.title}`);
-      }
-    }
-  } else if (hasAnswer && data.results.length > 0) {
-    // Hint about --show-sources when we have more sources
-    const citedCount = data.citations?.length ?? 0;
-    if (data.results.length > citedCount) {
-      lines.push(
-        `(${data.results.length} sources retrieved, use --show-sources to list all)`
-      );
-    }
-  }
-
-  if (!data.answer && data.results.length === 0) {
-    lines.push("No relevant sources found.");
-  }
-
-  return lines.join("\n");
-}
-
-function formatMarkdown(data: AskResult, opts: FormatOptions = {}): string {
-  const lines: string[] = [];
-  const hasAnswer = Boolean(data.answer);
-
-  lines.push(`# Question: ${data.query}`);
-  lines.push("");
-
-  if (data.answer) {
-    lines.push("## Answer");
-    lines.push("");
-    lines.push(data.answer);
-    lines.push("");
-  }
-
-  // Show cited sources (only sources actually referenced in answer)
-  if (data.citations && data.citations.length > 0) {
-    lines.push("## Cited Sources");
-    lines.push("");
-    for (let i = 0; i < data.citations.length; i++) {
-      const c = data.citations[i];
-      if (c) {
-        lines.push(`**[${i + 1}]** \`${c.uri}\``);
-      }
-    }
-    lines.push("");
-  }
-
-  // Show all retrieved sources if no answer or --show-sources
-  const showAllSources = !hasAnswer || opts.showSources;
-  if (showAllSources) {
-    lines.push(hasAnswer ? "## All Retrieved Sources" : "## Sources");
-    lines.push("");
-
-    for (let i = 0; i < data.results.length; i++) {
-      const r = data.results[i];
-      if (!r) {
-        continue;
-      }
-      lines.push(`${i + 1}. **${r.title || r.source.relPath}**`);
-      lines.push(`   - URI: \`${r.uri}\``);
-      lines.push(`   - Score: ${r.score.toFixed(2)}`);
-    }
-
-    if (data.results.length === 0) {
-      lines.push("*No relevant sources found.*");
-    }
-  }
-
-  lines.push("");
-  lines.push("---");
-  lines.push(
-    `*Mode: ${data.mode} | Expanded: ${data.meta.expanded} | Reranked: ${data.meta.reranked}*`
-  );
-
-  return lines.join("\n");
-}
-
-/**
- * Format ask result for output.
- */
-export function formatAsk(
-  result: AskCommandResult,
-  options: AskCommandOptions
-): string {
-  if (!result.success) {
-    return options.json
-      ? JSON.stringify({
-          error: { code: "ASK_FAILED", message: result.error },
-        })
-      : `Error: ${result.error}`;
-  }
-
-  const formatOpts: FormatOptions = { showSources: options.showSources };
-
-  if (options.json) {
-    return JSON.stringify(result.data, null, 2);
-  }
-
-  if (options.md) {
-    return formatMarkdown(result.data, formatOpts);
-  }
-
-  return formatTerminal(result.data, formatOpts);
-}

package/src/cli/commands/changes.ts

@@ -0,0 +1,160 @@
+/** CLI adapters and readable formatters for knowledge delta read services. */
+
+import type {
+  KnowledgeChangesResult,
+  KnowledgeDeltaServiceResult,
+  KnowledgeDiffResult,
+  KnowledgeImpactInput,
+  KnowledgeImpactResult,
+  ListKnowledgeChangesInput,
+} from "../../core/knowledge-delta";
+import type { StorePort } from "../../store/types";
+
+import {
+  analyzeKnowledgeImpact,
+  getKnowledgeDiff,
+  listKnowledgeChanges,
+} from "../../core/knowledge-delta";
+import { initStore } from "./shared";
+
+export interface KnowledgeDeltaCliContext {
+  configPath?: string;
+  indexName?: string;
+}
+
+export const changesRead = (
+  store: StorePort,
+  input: ListKnowledgeChangesInput = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeChangesResult>> =>
+  listKnowledgeChanges(store, input);
+
+export const diffRead = (
+  store: StorePort,
+  ref: string,
+  changeId?: string
+): Promise<KnowledgeDeltaServiceResult<KnowledgeDiffResult>> =>
+  getKnowledgeDiff(store, ref, changeId);
+
+export const impactRead = (
+  store: StorePort,
+  ref: string,
+  input: KnowledgeImpactInput = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> =>
+  analyzeKnowledgeImpact(store, ref, input);
+
+const withStore = async <T>(
+  context: KnowledgeDeltaCliContext,
+  operation: (store: StorePort) => Promise<KnowledgeDeltaServiceResult<T>>
+): Promise<KnowledgeDeltaServiceResult<T>> => {
+  const initialized = await initStore({
+    configPath: context.configPath,
+    indexName: context.indexName,
+    syncConfig: false,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) {
+    return { success: false, error: initialized.error };
+  }
+  try {
+    return await operation(initialized.store);
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+export const changes = (
+  input: ListKnowledgeChangesInput,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeChangesResult>> =>
+  withStore(context, (store) => changesRead(store, input));
+
+export const diff = (
+  ref: string,
+  changeId: string | undefined,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeDiffResult>> =>
+  withStore(context, (store) => diffRead(store, ref, changeId));
+
+export const impact = (
+  ref: string,
+  input: KnowledgeImpactInput,
+  context: KnowledgeDeltaCliContext = {}
+): Promise<KnowledgeDeltaServiceResult<KnowledgeImpactResult>> =>
+  withStore(context, (store) => impactRead(store, ref, input));
+
+const json = (value: unknown): string => JSON.stringify(value, null, 2);
+
+export function formatChanges(
+  result: KnowledgeChangesResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [`${result.changes.length} retained changes`];
+  for (const change of result.changes) {
+    const uri = change.current?.uri ?? change.previous?.uri ?? "(unknown)";
+    lines.push(
+      `${change.observedAt}  ${change.kind.padEnd(10)}  ${uri}  ${change.id}`
+    );
+  }
+  if (result.page.cursorExpired) {
+    lines.push(`Cursor expired; earliest: ${result.page.earliestCursor}`);
+  } else if (result.page.nextCursor) {
+    lines.push(`Next cursor: ${result.page.nextCursor}`);
+  }
+  for (const warning of result.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatDiff(
+  result: KnowledgeDiffResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [
+    `Structural diff for ${result.document.uri}`,
+    `Status: ${result.status}`,
+    `History: ${result.history.status}${result.history.reason ? ` (${result.history.reason})` : ""}`,
+    "Content: not retained (metadata-only journal)",
+  ];
+  if (result.change) {
+    const delta = result.change.structureDelta;
+    lines.push(
+      `Change: ${result.change.kind} at ${result.change.observedAt} (${result.change.id})`,
+      `Headings: +${delta.headings.added.length} -${delta.headings.removed.length}`,
+      `Links: +${delta.links.added.length} -${delta.links.removed.length}`,
+      `Typed edges: +${delta.typedEdges.added.length} -${delta.typedEdges.removed.length}`,
+      `Dates: +${delta.dates.added.length} -${delta.dates.removed.length} ~${delta.dates.changed.length}`
+    );
+  }
+  for (const warning of result.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatImpact(
+  result: KnowledgeImpactResult,
+  format: "terminal" | "json"
+): string {
+  if (format === "json") return json(result);
+  const lines = [
+    `${result.impacted.length} documents depend on ${result.root.uri}`,
+  ];
+  for (const item of result.impacted) {
+    const path = item.evidencePath
+      .map(
+        (step) => `${step.source.uri} -[${step.edgeType}]-> ${step.target.uri}`
+      )
+      .join(" -> ");
+    lines.push(`depth ${item.depth}  ${item.document.uri}`, `  ${path}`);
+  }
+  if (result.meta.truncated) {
+    lines.push("Traversal truncated by configured caps");
+  }
+  for (const warning of result.meta.warnings) {
+    lines.push(`Warning: ${warning}`);
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/context-saved.ts

@@ -0,0 +1,189 @@
+/** CLI lifecycle for explicitly saved Context Capsules. */
+
+import type { Config } from "../../config/types";
+import type { SqliteAdapter } from "../../store/sqlite/adapter";
+import type { SavedCapsuleRegistrationRecord } from "../../store/types";
+
+import { DEFAULT_INDEX_NAME } from "../../app/constants";
+import { canonicalizeIndexName } from "../../app/index-name";
+import {
+  canonicalSavedCapsuleRegistryJson,
+  listSavedCapsules,
+  loadSavedCapsuleFile,
+  registerSavedCapsule,
+  unregisterSavedCapsule,
+} from "../../core/capsule-registry";
+import { reverifySavedCapsuleManually } from "../../core/capsule-reverification";
+import { CliError } from "../errors";
+import { contextCliError } from "./context-build";
+import { initStore } from "./shared";
+
+export interface SavedCapsuleCommandOptions {
+  configPath?: string;
+  indexName?: string;
+  format: "terminal" | "json";
+}
+
+export interface WatchSavedCapsuleCommandOptions extends SavedCapsuleCommandOptions {
+  explicitIndexName?: string;
+  question?: string;
+  label?: string;
+  notify?: boolean;
+}
+
+export interface ReverifySavedCapsuleCommandResult {
+  output: string;
+  operationStatus: "completed" | "failed";
+  errorMessage: string | null;
+}
+
+const withStore = async <T>(
+  options: SavedCapsuleCommandOptions,
+  operation: (input: {
+    store: SqliteAdapter;
+    config: Config;
+    indexName: string;
+  }) => Promise<T>
+): Promise<T> => {
+  const indexName = canonicalizeIndexName(
+    options.indexName ?? DEFAULT_INDEX_NAME
+  );
+  const initialized = await initStore({
+    configPath: options.configPath,
+    indexName,
+    syncConfig: true,
+    allowEmptyCollections: true,
+  });
+  if (!initialized.ok) throw new CliError("RUNTIME", initialized.error);
+  try {
+    return await operation({
+      store: initialized.store,
+      config: initialized.config,
+      indexName,
+    });
+  } finally {
+    await initialized.store.close();
+  }
+};
+
+const formatRegistration = (
+  registration: SavedCapsuleRegistrationRecord
+): string =>
+  [
+    `${registration.registrationId}  ${registration.label ?? registration.capsuleId}`,
+    `  file: ${registration.filePath}`,
+    `  index: ${registration.indexName}`,
+    `  evidence: ${registration.evidence.length}`,
+    `  notify: ${registration.notificationPreference}`,
+    `  state: ${registration.verification?.affectedQuestionState ?? "not_verified"}`,
+  ].join("\n");
+
+export const watchSavedCapsule = async (
+  filePath: string,
+  options: WatchSavedCapsuleCommandOptions
+): Promise<string> => {
+  try {
+    const loaded = await loadSavedCapsuleFile(filePath);
+    const explicit = options.explicitIndexName
+      ? canonicalizeIndexName(options.explicitIndexName)
+      : undefined;
+    if (explicit && explicit !== loaded.capsule.scope.indexName) {
+      throw Object.assign(
+        new Error(
+          `Context Capsule index ${loaded.capsule.scope.indexName} does not match --index ${explicit}`
+        ),
+        { code: "invalid_filter" }
+      );
+    }
+    return await withStore(
+      { ...options, indexName: loaded.capsule.scope.indexName },
+      async ({ store, indexName }) => {
+        const registration = await registerSavedCapsule(store, indexName, {
+          filePath,
+          question: options.question,
+          label: options.label,
+          notificationPreference: options.notify ? "local" : "none",
+        });
+        return options.format === "json"
+          ? canonicalSavedCapsuleRegistryJson(registration)
+          : formatRegistration(registration);
+      }
+    );
+  } catch (error) {
+    throw contextCliError(error);
+  }
+};
+
+export const listWatchedCapsules = async (
+  options: SavedCapsuleCommandOptions
+): Promise<string> =>
+  withStore(options, async ({ store }) => {
+    const registrations = await listSavedCapsules(store);
+    if (options.format === "json") {
+      return canonicalSavedCapsuleRegistryJson({
+        schemaVersion: "1.0",
+        registrations,
+      });
+    }
+    return registrations.length === 0
+      ? "No saved Context Capsules are watched."
+      : registrations.map(formatRegistration).join("\n\n");
+  }).catch((error) => {
+    throw contextCliError(error);
+  });
+
+export const unwatchSavedCapsule = async (
+  registrationId: string,
+  options: SavedCapsuleCommandOptions
+): Promise<string> =>
+  withStore(options, async ({ store }) => {
+    await unregisterSavedCapsule(store, registrationId);
+    return options.format === "json"
+      ? canonicalSavedCapsuleRegistryJson({
+          schemaVersion: "1.0",
+          registrationId,
+          removed: true,
+        })
+      : `Stopped watching ${registrationId}.`;
+  }).catch((error) => {
+    throw contextCliError(error);
+  });
+
+export const reverifyWatchedCapsule = async (
+  registrationId: string,
+  options: SavedCapsuleCommandOptions
+): Promise<ReverifySavedCapsuleCommandResult> =>
+  withStore(options, async ({ store, config, indexName }) => {
+    const outcome = await reverifySavedCapsuleManually(registrationId, {
+      store,
+      config,
+      indexName,
+    });
+    const errorMessage =
+      outcome.verification.operationStatus === "failed"
+        ? `${outcome.verification.errorCode ?? "verification_failed"}: ${
+            outcome.verification.errorMessage ??
+            "Saved Context Capsule verification failed"
+          }`
+        : null;
+    const output =
+      options.format === "json"
+        ? canonicalSavedCapsuleRegistryJson({
+            schemaVersion: "1.0",
+            registration: outcome.registration,
+            verification: outcome.verification,
+            receipt: outcome.receipt,
+          })
+        : [
+            formatRegistration(outcome.registration),
+            `  operation: ${outcome.verification.operationStatus}`,
+            ...(errorMessage ? [`  error: ${errorMessage}`] : []),
+          ].join("\n");
+    return {
+      output,
+      operationStatus: outcome.verification.operationStatus,
+      errorMessage,
+    };
+  }).catch((error) => {
+    throw contextCliError(error);
+  });

package/src/cli/options.ts

@@ -35,6 +35,7 @@ export const CMD = {
   contextCheck: "context.check",
   contextBuild: "context.build",
   contextVerify: "context.verify",
+  contextSaved: "context.saved",
   modelsList: "models.list",
   tagsList: "tags.list",
   linksList: "links.list",
@@ -42,6 +43,9 @@ export const CMD = {
   similar: "similar",
   graph: "graph",
   graphQuery: "graph.query",
+  changes: "changes",
+  diff: "diff",
+  impact: "impact",
   capture: "capture",
 } as const;
 
@@ -64,6 +68,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.contextCheck]: ["terminal", "json", "md"],
   [CMD.contextBuild]: ["terminal", "json", "md"],
   [CMD.contextVerify]: ["terminal", "json", "md"],
+  [CMD.contextSaved]: ["terminal", "json"],
   [CMD.modelsList]: ["terminal", "json"],
   [CMD.tagsList]: ["terminal", "json", "md"],
   [CMD.linksList]: ["terminal", "json", "md"],
@@ -72,6 +77,9 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   // graph uses custom --dot/--mermaid flags (not OutputFormat) and writes via terminal output
   [CMD.graph]: ["json", "terminal"],
   [CMD.graphQuery]: ["terminal", "json"],
+  [CMD.changes]: ["terminal", "json"],
+  [CMD.diff]: ["terminal", "json"],
+  [CMD.impact]: ["terminal", "json"],
   [CMD.capture]: ["terminal", "json"],
 };