@gmickel/gno 2.10.1 → 2.12.0

package/src/cli/commands/cleanup.ts

@@ -6,7 +6,7 @@
  * @module src/cli/commands/cleanup
  */
 
-import type { CleanupStats } from "../../store/types";
+import type { CleanupStats, StaleCollection } from "../../store/types";
 
 import { getIndexDbPath } from "../../app/constants";
 import { isInitialized, loadConfig } from "../../config";
@@ -20,14 +20,26 @@ export interface CleanupOptions {
   configPath?: string;
   /** Index name */
   indexName?: string;
+  /** Called with the collections about to be deleted, before deleting them. */
+  onDropping?: (collections: StaleCollection[]) => void;
 }
 
 /**
  * Result of cleanup command.
  */
 export type CleanupResult =
-  | { success: true; stats: CleanupStats }
-  | { success: false; error: string };
+  | {
+      success: true;
+      stats: CleanupStats;
+      /** Indexed collections the config omits, deleted by this cleanup. */
+      droppedCollections: StaleCollection[];
+    }
+  | {
+      success: false;
+      error: string;
+      /** Collections already deleted when a later step failed. */
+      droppedCollections?: StaleCollection[];
+    };
 
 /**
  * Execute gno cleanup command.
@@ -64,17 +76,32 @@ export async function cleanup(
   try {
     // Drop collections no longer in the config first (their documents follow
     // by cascade), so their content, chunks and vectors count as orphans.
-    const syncResult = await store.syncCollections(config.collections);
+    // This is the explicit removal path; it names what it deletes.
+    const stale = await store.listStaleCollections(
+      config.collections.map(({ name }) => name)
+    );
+    if (!stale.ok) {
+      return { success: false, error: stale.error.message };
+    }
+    const droppedCollections = stale.value;
+    if (droppedCollections.length > 0) options.onDropping?.(droppedCollections);
+    const syncResult = await store.syncCollections(config.collections, {
+      remove: "stale",
+    });
     if (!syncResult.ok) {
       return { success: false, error: syncResult.error.message };
     }
 
     const cleanupResult = await store.cleanupOrphans();
     if (!cleanupResult.ok) {
-      return { success: false, error: cleanupResult.error.message };
+      return {
+        success: false,
+        error: cleanupResult.error.message,
+        droppedCollections,
+      };
     }
 
-    return { success: true, stats: cleanupResult.value };
+    return { success: true, stats: cleanupResult.value, droppedCollections };
   } finally {
     await store.close();
   }
@@ -118,3 +145,16 @@ export function formatCleanup(result: CleanupResult): string {
 
   return lines.join("\n");
 }
+
+/** Lines naming the collections cleanup is about to delete. */
+export function formatDroppingCollections(
+  collections: readonly StaleCollection[]
+): string {
+  return [
+    "Deleting collections not in this config:",
+    ...collections.map(
+      (c) =>
+        `  ${c.name}: ${c.documents} ${c.documents === 1 ? "document" : "documents"}`
+    ),
+  ].join("\n");
+}

package/src/cli/commands/collection/remove.ts

@@ -19,6 +19,7 @@ export async function collectionRemove(
     configPath: options.configPath,
     indexName: options.indexName,
     syncConfig: false,
+    allowStaleCollections: true,
     allowEmptyCollections: true,
   });
   if (!initialized.ok) {

package/src/cli/commands/collection/rename.ts

@@ -23,6 +23,7 @@ export async function collectionRename(
     configPath: options.configPath,
     indexName: options.indexName,
     syncConfig: false,
+    allowStaleCollections: true,
     allowEmptyCollections: true,
   });
   if (!initialized.ok) {

package/src/cli/commands/daemon.ts

@@ -99,7 +99,11 @@ export function logSessionAutomationResult(
 }
 
 function formatCollectionSyncSummary(result: CollectionSyncResult): string {
-  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors`;
+  const collectionErrors = result.errors
+    .filter((error) => error.relPath === "")
+    .map((error) => `; [${error.code}] ${error.message}`)
+    .join("");
+  return `${result.collection}: ${result.filesAdded} added, ${result.filesUpdated} updated, ${result.filesUnchanged} unchanged, ${result.filesErrored} errors${collectionErrors}`;
 }
 
 export const authorizeDaemonStatus = async (

package/src/cli/commands/doctor.ts

@@ -33,6 +33,7 @@ import {
 import { formatVectorPartitionLines } from "../../core/vector-partition-status";
 import { getEmbeddingFingerprint } from "../../embed/fingerprint";
 import { getCodeChunkingStatus } from "../../ingestion/chunker";
+import { checkCollectionRoots } from "../../ingestion/source-availability/root";
 import { ModelCache } from "../../llm/cache";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
@@ -739,6 +740,37 @@ export async function checkFindingsPass(
   };
 }
 
+/** Configured collection roots that are missing or unreadable right now. */
+export async function checkCollectionRootAccess(
+  config: Config
+): Promise<DoctorCheck> {
+  const name = "collection-roots";
+  const errors = await checkCollectionRoots(config.collections);
+  const unavailable = config.collections.flatMap((collection) => {
+    const error = errors[collection.name];
+    return error ? [{ collection, error }] : [];
+  });
+  if (unavailable.length === 0) {
+    return {
+      name,
+      status: "ok",
+      message: `${config.collections.length} collection root(s) available`,
+    };
+  }
+  return {
+    name,
+    status: "warn",
+    message: `${unavailable.length} collection root(s) missing or unreadable: ${unavailable.map(({ collection }) => collection.name).join(", ")}`,
+    details: [
+      ...unavailable.map(
+        ({ collection, error }) =>
+          `${collection.name}: ${collection.path} [${error.code}] ${error.message}`
+      ),
+      "Reconnect the drive or restore the folder; if it moved, change the collection's path in the config, then run: gno update",
+    ],
+  };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Implementation
 // ─────────────────────────────────────────────────────────────────────────────
@@ -779,6 +811,10 @@ export async function doctor(
   // Code chunking capability
   checks.push(checkCodeChunking());
 
+  // Collection roots, checked now (documents stay indexed while one is away)
+  const rootsCheck = await checkCollectionRootAccess(config);
+  checks.push(rootsCheck);
+
   // Embedding fingerprint freshness
   checks.push(...(await checkEmbeddingFingerprints(config, options.indexName)));
 
@@ -801,6 +837,7 @@ export async function doctor(
   return {
     healthy:
       !hasErrors &&
+      rootsCheck.status === "ok" &&
       activation.healthy &&
       isConnectorActivationComplete(activation),
     checks,

package/src/cli/commands/get.ts

@@ -29,6 +29,7 @@ import {
   evidenceFromExactDocument,
   RetrievalTraceSession as TraceSession,
 } from "../../core/retrieval-trace-session";
+import { supersedingUri } from "../../pipeline/result-context";
 import { parseRef } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -90,6 +91,8 @@ export interface GetResponse {
     mirrorHash?: string;
   };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
   capabilities: DocumentCapabilities;
 }
 
@@ -269,7 +272,7 @@ async function fetchDocument(
     return { success: false, error: "Mirror content unavailable" };
   }
 
-  return buildResponse({
+  const response = buildResponse({
     doc,
     fullContent: contentResult.value,
     parsed,
@@ -277,6 +280,10 @@ async function fetchDocument(
     config,
     indexName,
   });
+  const successor = await supersedingUri(store, doc.uri);
+  if (response.success && successor)
+    response.data.supersededBy = decorateUriForIndex(successor, indexName);
+  return response;
 }
 
 interface BuildResponseContext {
@@ -467,6 +474,9 @@ function formatMarkdown(data: GetResponse, options: GetCommandOptions): string {
   lines.push("");
   lines.push(`- **URI**: \`${data.uri}\``);
   lines.push(`- **DocID**: \`${data.docid}\``);
+  if (data.supersededBy) {
+    lines.push(`- **Superseded by**: \`${data.supersededBy}\``);
+  }
   if (data.returnedLines) {
     lines.push(
       `- **Lines**: ${data.returnedLines.start}-${data.returnedLines.end} of ${data.totalLines}`

package/src/cli/commands/mcp/paths.ts

@@ -12,6 +12,7 @@ import type { ConnectorWorkspaceEnvironment } from "../../../core/connector-envi
 
 import { resolveDirs } from "../../../app/constants";
 import { assertValidIndexName } from "../../../app/index-name";
+import { modulePath } from "../../../core/module-path";
 import { getCurrentGnoEntrypoint } from "../../../core/runtime-entrypoint";
 import {
   DEFAULT_MCP_TOOL_PROFILE,
@@ -459,7 +460,7 @@ export function resolveLaunchPaths(): {
   entrypoint: LaunchPath;
 } {
   const entrypoint = getCurrentGnoEntrypoint();
-  if (isBunfsPath(import.meta.path)) {
+  if (isBunfsPath(modulePath(import.meta))) {
     return {
       bun: { path: process.execPath, pinned: false },
       entrypoint: { path: entrypoint, pinned: false },

package/src/cli/commands/metadata.ts

@@ -0,0 +1,79 @@
+/**
+ * gno metadata - list the typed metadata keys indexed documents carry.
+ *
+ * @module src/cli/commands/metadata
+ */
+
+import {
+  formatMetadataSummary,
+  type MetadataSummary,
+  readMetadataSummary,
+} from "../../core/metadata-discovery";
+import { initStore } from "./shared";
+
+export interface MetadataListOptions {
+  configPath?: string;
+  indexName?: string;
+  collection?: string;
+  values?: number;
+}
+
+export type MetadataListResult =
+  | { success: true; data: MetadataSummary }
+  | { success: false; error: string; isValidation?: boolean };
+
+export async function metadataList(
+  options: MetadataListOptions = {}
+): Promise<MetadataListResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+  });
+  if (!initResult.ok) return { success: false, error: initResult.error };
+  const { store } = initResult;
+  try {
+    return {
+      success: true,
+      data: await readMetadataSummary(store, {
+        collection: options.collection,
+        values: options.values,
+      }),
+    };
+  } catch (cause) {
+    return {
+      success: false,
+      error: cause instanceof Error ? cause.message : String(cause),
+      isValidation: cause instanceof RangeError,
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatMetadataList(
+  data: MetadataSummary,
+  options: { json?: boolean; md?: boolean }
+): string {
+  if (options.json) return JSON.stringify(data, null, 2);
+  if (!options.md) return formatMetadataSummary(data);
+  const lines = [
+    "# Typed metadata",
+    "",
+    `*${data.documentsWithMetadata} of ${data.documents} documents${data.collection ? ` in \`${data.collection}\`` : ""}*`,
+  ];
+  if (data.keys.length === 0) return lines.join("\n");
+  lines.push(
+    "",
+    "| Key | Types | Documents | Common values |",
+    "|---|---|---|---|"
+  );
+  for (const key of data.keys) {
+    const values = key.values
+      .map((item) => `\`${JSON.stringify(item.value)}\` (${item.documents})`)
+      .join(", ");
+    lines.push(
+      `| \`${key.key}\` | ${key.types.join(", ")} | ${key.documents} | ${values}${key.valuesTruncated ? ", ..." : ""} |`
+    );
+  }
+  return lines.join("\n");
+}

package/src/cli/commands/multi-get.ts

@@ -21,6 +21,7 @@ import {
   projectRecordEvidenceMetadata,
   type RecordEvidenceMetadata,
 } from "../../core/record-metadata";
+import { supersedingUri } from "../../pipeline/result-context";
 import { isGlobPattern, parseRef, splitRefs } from "./ref-parser";
 import { initStore } from "./shared";
 
@@ -58,6 +59,8 @@ export interface MultiGetDocument {
   totalLines?: number;
   source: { absPath?: string; relPath: string; mime: string; ext: string };
   record?: RecordEvidenceMetadata;
+  /** URI of the current fact when a newer memory fact superseded this one. */
+  supersededBy?: string;
 }
 
 export interface SkippedDoc {
@@ -236,7 +239,11 @@ async function fetchSingleDocument(
   const coll = ctx.config.collections.find((c) => c.name === doc.collection);
 
   const sourceRelPath = doc.recordSourcePath ?? doc.relPath;
+  const successor = await supersedingUri(ctx.store, doc.uri);
   ctx.documents.push({
+    ...(successor
+      ? { supersededBy: decorateUriForIndex(successor, ctx.indexName) }
+      : {}),
     docid: doc.docid,
     uri: decorateUriForIndex(doc.uri, ctx.indexName),
     title: doc.title ?? undefined,
@@ -422,6 +429,9 @@ function formatMarkdown(
   for (const doc of data.documents) {
     lines.push(`## ${doc.title || doc.source.relPath}`);
     lines.push(`- **URI**: \`${doc.uri}\``);
+    if (doc.supersededBy) {
+      lines.push(`- **Superseded by**: \`${doc.supersededBy}\``);
+    }
     if (doc.truncated) {
       lines.push(`- **Truncated**: yes (max ${data.meta.maxBytes} bytes)`);
     }
@@ -450,6 +460,9 @@ function formatTerminal(
 
   for (const doc of data.documents) {
     lines.push(`=== ${doc.uri} ===`);
+    if (doc.supersededBy) {
+      lines.push(`Superseded by: ${doc.supersededBy}`);
+    }
     lines.push(formatContent(doc.content, Boolean(options.lineNumbers)));
     lines.push("");
   }

package/src/cli/commands/setup-semantic.ts

@@ -21,6 +21,7 @@ import type { FolderSetupReceipt } from "../../core/setup-receipt";
 import { VERSION } from "../../app/constants";
 import { canonicalizeIndexName } from "../../app/index-name";
 import { withWriteLock } from "../../core/file-lock";
+import { moduleDir } from "../../core/module-path";
 import {
   setupFingerprint,
   setupRootFingerprint,
@@ -427,7 +428,11 @@ function createSemanticReceipt(
 async function defaultSpawnWorker(
   receipt: SetupSemanticReceipt
 ): Promise<SpawnedSemanticWorker> {
-  const workerPath = join(import.meta.dir, "..", "setup-semantic-worker.ts");
+  const workerPath = join(
+    moduleDir(import.meta),
+    "..",
+    "setup-semantic-worker.ts"
+  );
   const descriptor = openSync(receipt.logPath, "a", 0o600);
   try {
     const child = Bun.spawn({

package/src/cli/commands/shared.ts

@@ -11,7 +11,7 @@ import type { SearchResults } from "../../pipeline/types";
 
 import {
   DEFAULT_INDEX_NAME,
-  decorateUriForIndex,
+  decorateResultUris,
   getIndexDbPath,
 } from "../../app/constants";
 import {
@@ -22,7 +22,10 @@ import {
 } from "../../config";
 import { tracePhase } from "../../core/phase-trace";
 import { BUDGET_ERROR_CODES } from "../../ingestion/file-processor";
-import { SqliteAdapter } from "../../store/sqlite/adapter";
+import {
+  SqliteAdapter,
+  staleCollectionsMessage,
+} from "../../store/sqlite/adapter";
 import { assertCliSessionBinding } from "../session-binding";
 
 /**
@@ -53,6 +56,10 @@ export interface InitStoreOptions {
   syncConfig?: boolean;
   /** Permit management commands that only need an existing index database */
   allowEmptyCollections?: boolean;
+  /** Open without syncing even when the index holds collections the config
+   * omits: config mutations report them through their own sync, and a
+   * connector proof reads one collection through a subset config. */
+  allowStaleCollections?: boolean;
 }
 
 /**
@@ -132,7 +139,25 @@ export async function initStore(
     return { ok: false, error: openResult.error.message };
   }
 
+  if (options.syncConfig === false && options.allowStaleCollections) {
+    return { ok: true, store, config, collections, actualConfigPath };
+  }
   if (options.syncConfig === false) {
+    // Reads skip the sync but must not search collections another config
+    // indexed; they fail the same way a sync would.
+    const stale = await store.listStaleCollections(
+      config.collections.map(({ name }) => name)
+    );
+    const indexed = stale.ok ? stale.value.filter((c) => c.documents > 0) : [];
+    if (!stale.ok || indexed.length > 0) {
+      await store.close();
+      return {
+        ok: false,
+        error: stale.ok
+          ? staleCollectionsMessage(indexed)
+          : stale.error.message,
+      };
+    }
     return { ok: true, store, config, collections, actualConfigPath };
   }
 
@@ -164,10 +189,9 @@ export function decorateSearchResultsForIndex(
   }
   return {
     ...data,
-    results: data.results.map((result) => ({
-      ...result,
-      uri: decorateUriForIndex(result.uri, indexName),
-    })),
+    results: data.results.map((result) =>
+      decorateResultUris(result, indexName)
+    ),
   };
 }
 
@@ -217,10 +241,13 @@ export function formatSyncResultLines(
       lines.push(`  ${c.filesErrored} errors`);
     }
     // A file stopped at its conversion budget is always named, not only in
-    // verbose output: it stays unindexed until a later run finishes it.
+    // verbose output: it stays unindexed until a later run finishes it. So is
+    // a collection-level error such as an unavailable root.
     if (!options.verbose) {
       for (const err of c.errors) {
-        if (BUDGET_ERROR_CODES.has(err.code)) {
+        if (err.relPath === "") {
+          lines.push(`    [${err.code}] ${err.message}`);
+        } else if (BUDGET_ERROR_CODES.has(err.code)) {
           lines.push(`    [${err.code}] ${err.relPath}: ${err.message}`);
         }
       }

package/src/cli/commands/skill/paths.ts

@@ -11,6 +11,11 @@ import { existsSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
+import {
+  harnessConfigDirFromEnv,
+  type HarnessId,
+} from "../agents/harnesses.js";
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Environment Variables
 // ─────────────────────────────────────────────────────────────────────────────
@@ -84,6 +89,11 @@ interface TargetPathConfig {
   userBase: string; // e.g., ".claude" (joined with homedir) or ".config/opencode"
   skillsSubdir: string; // e.g., "skills" or "skill"
   envVar: string;
+  /**
+   * Harness whose config-dir env var (CLAUDE_CONFIG_DIR, CODEX_HOME) replaces
+   * the user base, resolved exactly as `gno agents` does.
+   */
+  configDirHarness?: HarnessId;
 }
 
 const TARGET_CONFIGS: Record<SkillTarget, TargetPathConfig> = {
@@ -92,12 +102,14 @@ const TARGET_CONFIGS: Record<SkillTarget, TargetPathConfig> = {
     userBase: ".claude",
     skillsSubdir: "skills",
     envVar: ENV_CLAUDE_SKILLS_DIR,
+    configDirHarness: "claude",
   },
   codex: {
     projectBase: ".codex",
     userBase: ".codex",
     skillsSubdir: "skills",
     envVar: ENV_CODEX_SKILLS_DIR,
+    configDirHarness: "codex",
   },
   opencode: {
     projectBase: ".opencode",
@@ -150,8 +162,14 @@ export function resolveSkillPaths(opts: SkillPathOptions): SkillPaths {
   let base: string;
 
   if (scope === "user") {
-    const home = homeDir ?? process.env[ENV_SKILLS_HOME_OVERRIDE] ?? homedir();
-    base = join(home, config.userBase);
+    // Any home override (option or env) is an isolation request and
+    // suppresses the harness config-dir env vars, as in `gno agents`.
+    const explicitHome = homeDir ?? process.env[ENV_SKILLS_HOME_OVERRIDE];
+    const configDir =
+      explicitHome === undefined && config.configDirHarness
+        ? harnessConfigDirFromEnv(config.configDirHarness)
+        : undefined;
+    base = configDir ?? join(explicitHome ?? homedir(), config.userBase);
   } else {
     const projectRoot = cwd ?? process.cwd();
     base = join(projectRoot, config.projectBase);