@gmickel/gno 1.20.0 → 1.22.0

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"],
 };
 

package/src/cli/program.ts

@@ -308,6 +308,7 @@ export function createProgram(): Command {
   wireTagsCommands(program);
   wireLinksCommands(program);
   wireGraphCommand(program);
+  wireKnowledgeDeltaCommands(program);
   wireMcpCommand(program);
   wireSkillCommands(program);
   wireDaemonCommand(program);
@@ -2088,6 +2089,106 @@ function wireManagementCommands(program: Command): void {
       }
     );
 
+  contextCmd
+    .command("watch <file>")
+    .description("Watch a saved Context Capsule for evidence changes")
+    .option("--question <text>", "question associated with this Capsule")
+    .option("--label <text>", "short local label")
+    .option("--notify", "emit metadata-only local reverification events")
+    .option("--json", "JSON output")
+    .action(
+      async (
+        file: string,
+        cmdOpts: Record<string, unknown>,
+        command: Command
+      ) => {
+        const format = getFormat(cmdOpts);
+        assertFormatSupported(CMD.contextSaved, format);
+        const globals = getGlobals();
+        const explicitIndexName =
+          command.getOptionValueSourceWithGlobals("index") === "cli"
+            ? globals.index
+            : undefined;
+        const { watchSavedCapsule } = await import("./commands/context-saved");
+        await writeOutput(
+          await watchSavedCapsule(file, {
+            configPath: globals.config,
+            indexName: globals.index,
+            explicitIndexName,
+            question: cmdOpts.question as string | undefined,
+            label: cmdOpts.label as string | undefined,
+            notify: Boolean(cmdOpts.notify),
+            format: format === "json" ? "json" : "terminal",
+          }),
+          format === "json" ? "json" : "terminal"
+        );
+      }
+    );
+
+  contextCmd
+    .command("watches")
+    .description("List watched saved Context Capsules")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.contextSaved, format);
+      const globals = getGlobals();
+      const { listWatchedCapsules } = await import("./commands/context-saved");
+      await writeOutput(
+        await listWatchedCapsules({
+          configPath: globals.config,
+          indexName: globals.index,
+          format: format === "json" ? "json" : "terminal",
+        }),
+        format === "json" ? "json" : "terminal"
+      );
+    });
+
+  contextCmd
+    .command("unwatch <registration>")
+    .description("Stop watching a saved Context Capsule")
+    .option("--json", "JSON output")
+    .action(async (registration: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.contextSaved, format);
+      const globals = getGlobals();
+      const { unwatchSavedCapsule } = await import("./commands/context-saved");
+      await writeOutput(
+        await unwatchSavedCapsule(registration, {
+          configPath: globals.config,
+          indexName: globals.index,
+          format: format === "json" ? "json" : "terminal",
+        }),
+        format === "json" ? "json" : "terminal"
+      );
+    });
+
+  contextCmd
+    .command("reverify <registration>")
+    .description("Reverify one watched saved Context Capsule")
+    .option("--json", "JSON output")
+    .action(async (registration: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.contextSaved, format);
+      const globals = getGlobals();
+      const { reverifyWatchedCapsule } =
+        await import("./commands/context-saved");
+      const result = await reverifyWatchedCapsule(registration, {
+        configPath: globals.config,
+        indexName: globals.index,
+        format: format === "json" ? "json" : "terminal",
+      });
+      await writeOutput(result.output, format === "json" ? "json" : "terminal");
+      if (result.operationStatus === "failed") {
+        throw new CliError(
+          "RUNTIME",
+          result.errorMessage ??
+            "Saved Context Capsule verification operation failed",
+          { operationStatus: "failed" }
+        );
+      }
+    });
+
   contextCmd
     .command("rm <uri>")
     .description("Remove context item")
@@ -3088,6 +3189,100 @@ function wireGraphCommand(program: Command): void {
     );
 }
 
+function wireKnowledgeDeltaCommands(program: Command): void {
+  program
+    .command("changes")
+    .description("List retained metadata-only document changes")
+    .option("--since <time-or-cursor>", "ISO-8601 time or opaque cursor")
+    .option("-c, --collection <name>", "filter by collection")
+    .option("-n, --limit <num>", "maximum changes", "100")
+    .option("--json", "JSON output")
+    .action(async (cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.changes, format);
+      const deltaFormat = format === "json" ? "json" : "terminal";
+      const globals = getGlobals();
+      const { changes, formatChanges } = await import("./commands/changes");
+      const result = await changes(
+        {
+          since: cmdOpts.since as string | undefined,
+          collection: cmdOpts.collection as string | undefined,
+          limit: parsePositiveInt("limit", cmdOpts.limit),
+        },
+        { configPath: globals.config, indexName: globals.index }
+      );
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
+      }
+      await writeOutput(formatChanges(result.data, deltaFormat), deltaFormat);
+    });
+
+  program
+    .command("diff <doc>")
+    .description("Show one retained metadata-only structural change")
+    .option("--change <id>", "opaque change ID")
+    .option("--json", "JSON output")
+    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.diff, format);
+      const deltaFormat = format === "json" ? "json" : "terminal";
+      const globals = getGlobals();
+      const { diff, formatDiff } = await import("./commands/changes");
+      const result = await diff(doc, cmdOpts.change as string | undefined, {
+        configPath: globals.config,
+        indexName: globals.index,
+      });
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
+      }
+      await writeOutput(formatDiff(result.data, deltaFormat), deltaFormat);
+    });
+
+  program
+    .command("impact <doc>")
+    .description("Find bounded inbound knowledge dependencies")
+    .option("--max-depth <n>", "maximum dependency depth", "3")
+    .option("--max-nodes <n>", "maximum returned nodes", "100")
+    .option("--max-edges <n>", "maximum traversed evidence edges", "250")
+    .option("--frontier-limit <n>", "maximum frontier width", "100")
+    .option("--visited-limit <n>", "maximum visited rows", "500")
+    .option("--json", "JSON output")
+    .action(async (doc: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.impact, format);
+      const deltaFormat = format === "json" ? "json" : "terminal";
+      const globals = getGlobals();
+      const { impact, formatImpact } = await import("./commands/changes");
+      const result = await impact(
+        doc,
+        {
+          maxDepth: parsePositiveInt("max-depth", cmdOpts.maxDepth),
+          maxNodes: parsePositiveInt("max-nodes", cmdOpts.maxNodes),
+          maxEdges: parsePositiveInt("max-edges", cmdOpts.maxEdges),
+          frontierLimit: parsePositiveInt(
+            "frontier-limit",
+            cmdOpts.frontierLimit
+          ),
+          visitedLimit: parsePositiveInt("visited-limit", cmdOpts.visitedLimit),
+        },
+        { configPath: globals.config, indexName: globals.index }
+      );
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
+      }
+      await writeOutput(formatImpact(result.data, deltaFormat), deltaFormat);
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Serve Command (web UI)
 // ─────────────────────────────────────────────────────────────────────────────