@gmickel/gno 1.43.0 → 1.44.0

package/src/cli/commands/index-cmd.ts

@@ -1,6 +1,8 @@
 /**
  * gno index command implementation.
- * Build or update the index end-to-end (update + embed).
+ * Build or update the index end-to-end as two separable, resumable stages:
+ * `lexical` (sync) then `embed`. Each stage reports its own receipt state and
+ * counts; the run exits 0 only when every attempted stage completed (fn-132).
  *
  * @module src/cli/commands/indexCmd
  */
@@ -10,11 +12,22 @@ import {
   type WriteLeaseContention,
   withCliWriteLease,
 } from "../../core/write-lease";
+import {
+  clearIndexStage,
+  findInterruptedStage,
+  formatInterruptedStage,
+  type IndexStageState,
+  type InterruptedStage,
+  markIndexStageFinished,
+  markIndexStageRunning,
+  readIndexStageState,
+} from "../../embed/stage-state";
 import {
   defaultSyncService,
   type SyncResult,
   withContentTypeRules,
 } from "../../ingestion";
+import { type EmbedResult, embedStageOutcome } from "./embed";
 import { formatSyncResultLines, initStore } from "./shared";
 
 /**
@@ -41,22 +54,118 @@ export interface IndexOptions extends CliWriteLeaseOptions {
   json?: boolean;
 }
 
+/** Receipt for the lexical (sync) stage. */
+export interface LexicalStageReceipt {
+  state: IndexStageState;
+  filesProcessed: number;
+  filesAdded: number;
+  filesUpdated: number;
+  filesErrored: number;
+  filesSkipped: number;
+  durationMs: number;
+  error?: string;
+}
+
+/** Receipt for the embed stage. */
+export interface EmbedStageReceipt {
+  state: IndexStageState;
+  embedded: number;
+  errors: number;
+  contentionErrors: number;
+  durationMs: number;
+  /** Why the stage was skipped (`--no-embed`, lexical failure). */
+  reason?: string;
+  error?: string;
+}
+
+export interface IndexStageReceipts {
+  lexical: LexicalStageReceipt;
+  embed: EmbedStageReceipt;
+}
+
+export interface IndexEmbedSummary {
+  embedded: number;
+  errors: number;
+  contentionErrors: number;
+  duration: number;
+}
+
+/** Receipt fields shared by successful and failed runs that reached a stage. */
+export interface IndexReceipt {
+  stages: IndexStageReceipts;
+  /** Stage a previous run left `running`; null when the run started clean. */
+  resumedFrom: InterruptedStage | null;
+  syncResult?: SyncResult;
+  embedSkipped: boolean;
+  embedResult?: IndexEmbedSummary;
+}
+
 /**
- * Result of index command.
+ * Result of index command. A failure that reached a stage carries the partial
+ * receipt (`stages` present); a failure before any stage (init, lease) does not.
  */
 export type IndexResult =
+  | ({ success: true; syncResult: SyncResult } & IndexReceipt)
+  | ({ success: false; error: string } & IndexReceipt)
   | {
-      success: true;
-      syncResult: SyncResult;
-      embedSkipped: boolean;
-      embedResult?: {
-        embedded: number;
-        errors: number;
-        contentionErrors: number;
-        duration: number;
-      };
-    }
-  | { success: false; error: string; contention?: WriteLeaseContention };
+      success: false;
+      error: string;
+      contention?: WriteLeaseContention;
+      stages?: undefined;
+    };
+
+const EMPTY_LEXICAL_COUNTS = {
+  filesProcessed: 0,
+  filesAdded: 0,
+  filesUpdated: 0,
+  filesErrored: 0,
+  filesSkipped: 0,
+  durationMs: 0,
+} as const;
+
+const EMPTY_EMBED_COUNTS = {
+  embedded: 0,
+  errors: 0,
+  contentionErrors: 0,
+  durationMs: 0,
+} as const;
+
+function lexicalReceipt(syncResult: SyncResult): LexicalStageReceipt {
+  return {
+    state: "completed",
+    filesProcessed: syncResult.totalFilesProcessed,
+    filesAdded: syncResult.totalFilesAdded,
+    filesUpdated: syncResult.totalFilesUpdated,
+    filesErrored: syncResult.totalFilesErrored,
+    filesSkipped: syncResult.totalFilesSkipped,
+    durationMs: syncResult.totalDurationMs,
+  };
+}
+
+function skippedEmbedReceipt(reason: string): EmbedStageReceipt {
+  return { state: "skipped", ...EMPTY_EMBED_COUNTS, reason };
+}
+
+function embedReceipt(result: EmbedResult): EmbedStageReceipt {
+  if (!result.success) {
+    return { state: "failed", ...EMPTY_EMBED_COUNTS, error: result.error };
+  }
+  const state = embedStageOutcome(result);
+  const error =
+    state === "failed"
+      ? (result.syncError ??
+        result.errorSamples?.[0] ??
+        `${result.errors} chunks failed to embed`)
+      : undefined;
+  return {
+    state,
+    embedded: result.embedded,
+    errors: result.errors,
+    contentionErrors: result.contentionErrors,
+    durationMs: Math.round(result.duration * 1000),
+    ...(error ? { error } : {}),
+  };
+}
 
 /**
  * Execute gno index command.
@@ -73,52 +182,103 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
     }
 
     const { store, collections, config } = initResult;
+    const db = store.getRawDb();
+    const embedSkipped = options.noEmbed ?? false;
 
     try {
-      // Run sync service (update phase)
-      const syncResult = await defaultSyncService.syncAll(
-        collections,
-        store,
-        withContentTypeRules(
-          {
-            gitPull: options.gitPull,
-            runUpdateCmd: true,
+      // Resume preamble (fn-132 R4): report a stage the previous run left
+      // `running` before this run overwrites its marker.
+      const resumedFrom = findInterruptedStage(readIndexStageState(db));
+      if (resumedFrom && !options.json) {
+        process.stderr.write(`${formatInterruptedStage(resumedFrom)}\n`);
+      }
+
+      // Lexical stage (sync). Per-file errors are counted, not fatal; only a
+      // sync that cannot run at all fails the stage.
+      markIndexStageRunning(db, "lexical", { collection: options.collection });
+      let syncResult: SyncResult;
+      try {
+        syncResult = await defaultSyncService.syncAll(
+          collections,
+          store,
+          withContentTypeRules(
+            { gitPull: options.gitPull, runUpdateCmd: true },
+            config
+          )
+        );
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        markIndexStageFinished(db, "lexical", "failed");
+        return {
+          success: false,
+          error: `Lexical sync failed: ${message}`,
+          stages: {
+            lexical: {
+              state: "failed",
+              ...EMPTY_LEXICAL_COUNTS,
+              error: message,
+            },
+            embed: skippedEmbedReceipt("lexical stage failed"),
           },
-          config
-        )
-      );
+          resumedFrom,
+          embedSkipped,
+        };
+      }
+      markIndexStageFinished(db, "lexical", "completed");
+      const lexical = lexicalReceipt(syncResult);
 
-      // Embedding phase
-      const embedSkipped = options.noEmbed ?? false;
-      let embedResult:
-        | {
-            embedded: number;
-            errors: number;
-            contentionErrors: number;
-            duration: number;
-          }
-        | undefined;
-
-      if (!embedSkipped) {
-        const { embed } = await import("./embed");
-        const result = await embed({
-          configPath: options.configPath,
-          indexName: options.indexName,
-          collection: options.collection,
-          verbose: options.verbose,
-          skipWriteLease: true,
-        });
-        if (result.success) {
-          embedResult = {
+      if (embedSkipped) {
+        // A stale `embed: running` marker (killed embed run) was surfaced in
+        // this run's preamble; settle it so the next run does not repeat it
+        // or mask a real lexical interruption. Embed progress stays on disk.
+        if (resumedFrom?.stage === "embed") {
+          clearIndexStage(db, "embed");
+        }
+        return {
+          success: true,
+          syncResult,
+          embedSkipped,
+          stages: { lexical, embed: skippedEmbedReceipt("--no-embed") },
+          resumedFrom,
+        };
+      }
+
+      // Embed stage. embed() owns its own persisted marker.
+      const { embed } = await import("./embed");
+      const result = await embed({
+        configPath: options.configPath,
+        indexName: options.indexName,
+        collection: options.collection,
+        verbose: options.verbose,
+        json: options.json,
+        skipWriteLease: true,
+        resumedFrom,
+      });
+      const embedStage = embedReceipt(result);
+      const embedResult: IndexEmbedSummary | undefined = result.success
+        ? {
             embedded: result.embedded,
             errors: result.errors,
             contentionErrors: result.contentionErrors,
             duration: result.duration,
-          };
-        }
-      }
+          }
+        : undefined;
+      const receipt: IndexReceipt = {
+        stages: { lexical, embed: embedStage },
+        resumedFrom,
+        syncResult,
+        embedSkipped,
+        ...(embedResult ? { embedResult } : {}),
+      };
 
-      return { success: true, syncResult, embedSkipped, embedResult };
+      if (embedStage.state !== "completed") {
+        return {
+          success: false,
+          error: `Embed stage failed: ${embedStage.error ?? "unknown error"}`,
+          ...receipt,
+        };
+      }
+      return { success: true, syncResult, ...receipt };
     } finally {
       await store.close();
     }
@@ -141,14 +301,18 @@ export function formatIndex(
     return `${mins}m ${secs.toFixed(0)}s`;
   }
 
-  if (!result.success) {
+  if (!result.success && !result.stages) {
     return `Error: ${result.error}`;
   }
 
   if (options.json) {
     return JSON.stringify(
       {
-        syncResult: result.syncResult,
+        success: result.success,
+        ...(result.success ? {} : { error: result.error }),
+        stages: result.stages,
+        resumedFrom: result.resumedFrom,
+        ...(result.syncResult ? { syncResult: result.syncResult } : {}),
         embedSkipped: result.embedSkipped,
         ...(result.embedResult ? { embedResult: result.embedResult } : {}),
       },
@@ -156,16 +320,28 @@ export function formatIndex(
       2
     );
   }
-  const { syncResult, embedSkipped } = result;
-  const lines: string[] = ["Indexing complete.", ""];
 
-  lines.push(...formatSyncResultLines(syncResult, options));
+  const { stages, embedSkipped } = result;
+  const lines: string[] = [
+    result.success ? "Indexing complete." : "Indexing failed.",
+    "",
+  ];
+
+  if (result.syncResult) {
+    lines.push(...formatSyncResultLines(result.syncResult, options));
+  } else {
+    lines.push(`Lexical stage ${stages.lexical.state}.`);
+  }
+  if (stages.lexical.error) {
+    lines.push(`Lexical error: ${stages.lexical.error}`);
+  }
 
+  lines.push("");
   if (embedSkipped) {
-    lines.push("");
     lines.push("Embedding skipped (--no-embed)");
+  } else if (stages.embed.state === "skipped") {
+    lines.push(`Embedding skipped (${stages.embed.reason ?? "not attempted"})`);
   } else if (result.embedResult) {
-    lines.push("");
     const { embedded, errors, contentionErrors, duration } = result.embedResult;
     lines.push(
       `Embedded ${embedded.toLocaleString()} chunks in ${formatDuration(duration)}`
@@ -179,6 +355,11 @@ export function formatIndex(
       );
     }
   }
+  if (stages.embed.state === "failed") {
+    lines.push(
+      `Embed stage failed: ${stages.embed.error ?? "unknown error"}. Lexical index is intact; rerun \`gno embed\` to resume from persisted progress.`
+    );
+  }
 
   return lines.join("\n");
 }

package/src/cli/program.ts

@@ -20,6 +20,11 @@ import {
 } from "../app/constants";
 import { INDEX_NAME_REQUIREMENTS, isValidIndexName } from "../app/index-name";
 import { resolveDepthPolicy } from "../core/depth-policy";
+import {
+  findingsRunStatePathForIndex,
+  formatFindingsRunStatusLine,
+  readFindingsRunStatus,
+} from "../core/findings-run-state";
 import { parseAndValidateTagFilter } from "../core/tags";
 import {
   formatWriteLeaseBusyJson,
@@ -1630,7 +1635,14 @@ function wireOnboardingCommands(program: Command): void {
 
       if (!result.success) {
         throwIfWriteLeaseBusy(result, opts.json);
-        throw new CliError("RUNTIME", result.error ?? "Index failed");
+        if (!result.stages) {
+          throw new CliError("RUNTIME", result.error ?? "Index failed");
+        }
+        // A stage failed after the run started: emit the partial per-stage
+        // receipt, then exit non-zero (fn-132 R4 - never exit 0 on a failed
+        // embed stage).
+        process.stdout.write(`${formatIndex(result, opts)}\n`);
+        throw new CliError("RUNTIME", result.error, { silent: true });
       }
       process.stdout.write(`${formatIndex(result, opts)}\n`);
       if ((result.embedResult?.contentionErrors ?? 0) > 0) {
@@ -4094,25 +4106,89 @@ function wireGraphCommand(program: Command): void {
     );
 }
 
+/**
+ * `gno changes --follow --jsonl`: the follow flags form one mode that
+ * excludes the one-shot listing flags. The cursor-expiry record is the
+ * stdout envelope, so its non-zero exit is silent on stderr.
+ */
+async function runChangesFollow(
+  cmdOpts: Record<string, unknown>,
+  format: string,
+  globals: GlobalOptions
+): Promise<void> {
+  if (!cmdOpts.follow || !cmdOpts.jsonl) {
+    throw new CliError(
+      "VALIDATION",
+      "--follow and --jsonl must be used together (--cursor requires both)"
+    );
+  }
+  if (format === "json" || cmdOpts.since !== undefined) {
+    throw new CliError(
+      "VALIDATION",
+      "--follow cannot be combined with --json or --since; use --cursor to resume"
+    );
+  }
+  if (cmdOpts.limit !== undefined) {
+    throw new CliError(
+      "VALIDATION",
+      "--follow cannot be combined with --limit"
+    );
+  }
+  const { changesFollow } = await import("./commands/changes");
+  const result = await changesFollow(
+    {
+      cursor: cmdOpts.cursor as string | undefined,
+      collection: cmdOpts.collection as string | undefined,
+    },
+    { configPath: globals.config, indexName: globals.index }
+  );
+  if (result.status === "error") {
+    throw new CliError(
+      result.isValidation ? "VALIDATION" : "RUNTIME",
+      result.error
+    );
+  }
+  if (result.status === "expired") {
+    throw new CliError(
+      "RUNTIME",
+      `Follow cursor expired; earliest retained cursor is ${result.earliestCursor}`,
+      { silent: true }
+    );
+  }
+}
+
 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("-n, --limit <num>", "maximum changes (default 100)")
     .option("--json", "JSON output")
+    .option(
+      "--follow",
+      "stream new changes as they land (requires --jsonl; SIGINT exits 0)"
+    )
+    .option("--jsonl", "one JSON object per line (only with --follow)")
+    .option(
+      "--cursor <cursor>",
+      "resume a --follow stream from a persisted postCursor"
+    )
     .action(async (cmdOpts: Record<string, unknown>) => {
       const format = getFormat(cmdOpts);
       assertFormatSupported(CMD.changes, format);
       const deltaFormat = format === "json" ? "json" : "terminal";
       const globals = getGlobals();
+      if (cmdOpts.follow || cmdOpts.jsonl || cmdOpts.cursor !== undefined) {
+        await runChangesFollow(cmdOpts, format, globals);
+        return;
+      }
       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),
+          limit: parsePositiveInt("limit", cmdOpts.limit ?? "100"),
         },
         { configPath: globals.config, indexName: globals.index }
       );
@@ -4345,6 +4421,7 @@ async function handleDaemonAction(
     await runDaemonStatus({
       paths,
       json,
+      indexName: globals.index,
       statusProcess,
       inspectForeignLive,
     });
@@ -4412,6 +4489,7 @@ async function handleDaemonAction(
 interface DaemonStatusDeps {
   paths: { pidFile: string; logFile: string };
   json: boolean;
+  indexName?: string;
   statusProcess: typeof import("./detach.js").statusProcess;
   inspectForeignLive: typeof import("./detach.js").inspectForeignLive;
 }
@@ -4426,9 +4504,16 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     kind: "daemon",
     pidFile: deps.paths.pidFile,
   });
+  // Persisted by the daemon after every scheduled findings attempt; absent
+  // (null) when the pass is not configured. Read from disk, never live.
+  const findings = await readFindingsRunStatus(
+    findingsRunStatePathForIndex(deps.indexName)
+  );
 
   if (deps.json) {
-    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify({ ...status, findings }, null, 2)}\n`
+    );
     // In JSON mode, foreign-live metadata flows into the NOT_RUNNING
     // envelope's `details` payload below so stderr stays a single JSON
     // object that machine clients can parse deterministically.
@@ -4457,6 +4542,11 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     } else {
       process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
     }
+    if (findings) {
+      process.stdout.write(
+        `  findings ${formatFindingsRunStatusLine(findings)}\n`
+      );
+    }
 
     if (foreign) {
       // Terminal mode: emit the operator-facing warning on stderr. JSON

package/src/config/types.ts

@@ -472,6 +472,51 @@ export const HttpGatewayConfigSchema = z.object({
 
 export type HttpGatewayConfig = z.infer<typeof HttpGatewayConfigSchema>;
 
+// ────────────────────────────────────────────────────────────────────────────
+// Scheduled findings pass (daemon-only, opt-in, report-only)
+// ────────────────────────────────────────────────────────────────────────────
+
+/** `<integer><unit>` with unit s|m|h|d, e.g. `30m`, `6h`, `1d`. */
+export const FINDINGS_CADENCE_PATTERN =
+  /^(?<value>[1-9]\d{0,5})(?<unit>[smhd])$/;
+export const DEFAULT_FINDINGS_CADENCE = "6h";
+export const MIN_FINDINGS_CADENCE_MS = 10_000;
+export const MAX_FINDINGS_CADENCE_MS = 30 * 24 * 60 * 60 * 1000;
+
+const CADENCE_UNIT_MS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** Parse a findings cadence into milliseconds; null when malformed or out of range. */
+export function parseFindingsCadenceMs(raw: string): number | null {
+  const match = FINDINGS_CADENCE_PATTERN.exec(raw.trim());
+  const value = match?.groups?.value;
+  const unit = match?.groups?.unit;
+  if (!value || !unit) return null;
+  const ms = Number(value) * (CADENCE_UNIT_MS[unit] ?? 0);
+  if (ms < MIN_FINDINGS_CADENCE_MS || ms > MAX_FINDINGS_CADENCE_MS) return null;
+  return ms;
+}
+
+export const FindingsConfigSchema = z.object({
+  /** Off by default; the daemon never audits on cadence unless asked. */
+  enabled: z.boolean().default(false),
+  /** Run interval (`10s`..`30d`). Evaluated only when enabled. */
+  cadence: z
+    .string()
+    .refine((value) => parseFindingsCadenceMs(value) !== null, {
+      message: "cadence must be <n>s|m|h|d between 10s and 30d (e.g. 6h)",
+    })
+    .default(DEFAULT_FINDINGS_CADENCE),
+  /** Name of an already-configured collection that receives findings records. */
+  collection: z.string().regex(COLLECTION_NAME_REGEX).optional(),
+});
+
+export type FindingsConfig = z.infer<typeof FindingsConfigSchema>;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Content Type Schema
 // ─────────────────────────────────────────────────────────────────────────────
@@ -556,6 +601,9 @@ export const ConfigSchema = z.object({
   /** Resident Streamable HTTP MCP gateway configuration */
   gateway: HttpGatewayConfigSchema.optional(),
 
+  /** Daemon-only scheduled read-only audit writing findings records. Absent means off. */
+  findings: FindingsConfigSchema.optional(),
+
   /** Private local retrieval trace recording. Absent means recording off. */
   retrievalTraces: RetrievalTraceConfigSchema.optional(),