@gmickel/gno 1.12.4 → 1.14.0

package/src/app/index-name.ts

@@ -0,0 +1,127 @@
+/** Shared index-name contract for filesystem paths and connector trust checks. */
+
+export const MAX_INDEX_NAME_LENGTH = 64;
+
+const SAFE_INDEX_NAME_REGEX = /^[\p{L}\p{N}][\p{L}\p{M}\p{N} ._-]*$/u;
+const INDEX_DB_PREFIX = "index-";
+const INDEX_DB_SUFFIX = ".sqlite";
+const MAX_PORTABLE_FILENAME_COMPONENT_LENGTH = 255;
+const MAX_INDEX_IDENTITY_STORAGE_LENGTH =
+  MAX_PORTABLE_FILENAME_COMPONENT_LENGTH -
+  INDEX_DB_PREFIX.length -
+  INDEX_DB_SUFFIX.length;
+const UTF8_ENCODER = new TextEncoder();
+
+export const INDEX_NAME_REQUIREMENTS =
+  "use 1-64 letters, marks, numbers, internal spaces, '.', '_' or '-', start with a letter or number, do not end with a space or '.', do not include '..', and fit the portable database filename limit";
+
+function hasSafeIndexNameSyntax(value: string): boolean {
+  return (
+    SAFE_INDEX_NAME_REGEX.test(value) &&
+    !/[ .]$/.test(value) &&
+    !value.includes("..")
+  );
+}
+
+function canonicalizeIndexNameUnchecked(value: string): string {
+  return value
+    .normalize("NFC")
+    .toLowerCase()
+    .toUpperCase()
+    .toLowerCase()
+    .normalize("NFC");
+}
+
+function fitsIndexIdentityStorage(value: string): boolean {
+  return (
+    value.length <= MAX_INDEX_IDENTITY_STORAGE_LENGTH &&
+    UTF8_ENCODER.encode(value).byteLength <= MAX_INDEX_IDENTITY_STORAGE_LENGTH
+  );
+}
+
+/** Return whether a value is a canonical, filesystem-safe GNO index name. */
+export function isValidIndexName(value: unknown): value is string {
+  if (
+    typeof value !== "string" ||
+    value.length > MAX_INDEX_NAME_LENGTH ||
+    !hasSafeIndexNameSyntax(value)
+  ) {
+    return false;
+  }
+  return fitsIndexIdentityStorage(canonicalizeIndexNameUnchecked(value));
+}
+
+/** Fail closed before an index name can influence a database path. */
+export function assertValidIndexName(value: unknown): asserts value is string {
+  if (!isValidIndexName(value)) {
+    throw new TypeError(`Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`);
+  }
+}
+
+/**
+ * Return the cross-platform logical identity for an index name.
+ *
+ * APFS and Windows filesystems collapse canonical Unicode and case variants,
+ * while common Linux filesystems do not. GNO applies one identity everywhere
+ * so URI routing and database selection cannot disagree by platform.
+ */
+export function canonicalizeIndexName(value: string): string {
+  assertValidIndexName(value);
+  // The lower/upper/lower closure covers multi-character folds (ß/SS),
+  // compatibility case pairs (ſ/S), and positional forms (ς/Σ) that a plain
+  // lowercase pass misses but case-insensitive APFS aliases on disk.
+  return canonicalizeIndexNameUnchecked(value);
+}
+
+/** Compare two validated names using GNO's cross-platform identity rules. */
+export function indexNamesMatch(left: string, right: string): boolean {
+  return canonicalizeIndexName(left) === canonicalizeIndexName(right);
+}
+
+function indexNameFromDbFilename(filename: string): string | null {
+  if (
+    !filename.startsWith(INDEX_DB_PREFIX) ||
+    !filename.endsWith(INDEX_DB_SUFFIX)
+  ) {
+    return null;
+  }
+  const name = filename.slice(INDEX_DB_PREFIX.length, -INDEX_DB_SUFFIX.length);
+  const isCanonicalStoredIdentity =
+    hasSafeIndexNameSyntax(name) &&
+    fitsIndexIdentityStorage(name) &&
+    canonicalizeIndexNameUnchecked(name) === name;
+  return isValidIndexName(name) || isCanonicalStoredIdentity ? name : null;
+}
+
+/**
+ * Select one database filename for a logical index identity.
+ *
+ * New indexes use the canonical filename. A single existing mixed-case or
+ * pre-normalized filename remains addressable for backward compatibility.
+ * Multiple legacy files with the same identity are unsafe on case-sensitive
+ * filesystems and fail closed instead of selecting one by directory order.
+ */
+export function resolveIndexDbFilename(
+  indexName: string,
+  existingFilenames: Iterable<string> = []
+): string {
+  const identity = canonicalizeIndexName(indexName);
+  const matches: string[] = [];
+  for (const filename of existingFilenames) {
+    const existingName = indexNameFromDbFilename(filename);
+    if (
+      existingName !== null &&
+      canonicalizeIndexNameUnchecked(existingName) === identity
+    ) {
+      matches.push(filename);
+    }
+  }
+
+  const uniqueMatches = [...new Set(matches)].sort();
+  if (uniqueMatches.length > 1) {
+    throw new TypeError(
+      `Ambiguous index name "${indexName}": multiple database files share its canonical identity (${uniqueMatches.join(", ")}).`
+    );
+  }
+  return uniqueMatches[0] ?? `${INDEX_DB_PREFIX}${identity}${INDEX_DB_SUFFIX}`;
+}

package/src/cli/commands/doctor-activation.ts

@@ -0,0 +1,151 @@
+/** Passive retrieval activation diagnostics shared by `gno doctor`. */
+
+import type { Config } from "../../config/types";
+import type { ActivationStatus } from "../../core/activation-status";
+import type { StorePort } from "../../store/types";
+import type { DoctorCheck } from "./doctor";
+
+import { getIndexDbPath, getModelsCachePath } from "../../app/constants";
+import { buildActivationStatus } from "../../core/activation-status";
+import { ModelCache } from "../../llm/cache";
+import { getActivePreset } from "../../llm/registry";
+import { getConnectorVerificationTargets } from "../../serve/connectors";
+import { SqliteAdapter } from "../../store/sqlite/adapter";
+
+export interface DoctorActivationOptions {
+  configPath?: string;
+  indexName?: string;
+}
+
+async function unavailableActivation(
+  config: Config
+): Promise<ActivationStatus> {
+  return buildActivationStatus(
+    {} as StorePort,
+    config.collections.map(({ name }) => name),
+    {
+      verifyCollection: async () => ({
+        ok: false,
+        error: { code: "QUERY_FAILED", message: "Activation unavailable" },
+      }),
+    }
+  );
+}
+
+export async function buildDoctorActivation(
+  config: Config,
+  options: DoctorActivationOptions
+): Promise<ActivationStatus> {
+  const dbPath = getIndexDbPath(options.indexName);
+  if (!(await Bun.file(dbPath).exists())) {
+    return unavailableActivation(config);
+  }
+
+  const store = new SqliteAdapter();
+  store.setConfigPath(options.configPath ?? "");
+  const opened = await store.open(dbPath, config.ftsTokenizer);
+  if (!opened.ok) {
+    return unavailableActivation(config);
+  }
+
+  try {
+    const indexStatus = await store.getStatus();
+    const embedCached = await new ModelCache(getModelsCachePath()).isCached(
+      getActivePreset(config).embed
+    );
+    return await buildActivationStatus(
+      store,
+      config.collections.map(({ name }) => name),
+      {
+        semantic: {
+          modelsCached: embedCached,
+          embeddingBacklog: indexStatus.ok
+            ? indexStatus.value.embeddingBacklog
+            : 0,
+        },
+        connectorTargets: await getConnectorVerificationTargets(),
+      }
+    );
+  } finally {
+    await store.close();
+  }
+}
+
+export function checkRetrievalActivation(
+  activation: ActivationStatus
+): DoctorCheck {
+  if (activation.healthy) {
+    const semanticStates = [
+      ...new Set(
+        activation.collections.map(
+          ({ semanticAvailability }) => semanticAvailability.code
+        )
+      ),
+    ];
+    return {
+      name: "retrieval-activation",
+      status: "ok",
+      message: `${activation.collections.length} collection${activation.collections.length === 1 ? "" : "s"} passed lexical retrieval proof`,
+      details: [
+        `Semantic retrieval remains separate (${semanticStates.join(", ")}).`,
+      ],
+    };
+  }
+
+  const failed = activation.collections.filter(({ ready }) => !ready);
+  const details = failed.flatMap(({ collection, remediation }) =>
+    remediation
+      ? [
+          `${collection}: ${remediation.stage}/${remediation.code}`,
+          `Run: ${remediation.command}`,
+        ]
+      : [`${collection}: activation unavailable`]
+  );
+  return {
+    name: "retrieval-activation",
+    status: "error",
+    message:
+      activation.collections.length === 0
+        ? "No collections configured. Run: gno collection add"
+        : activation.usable
+          ? `${failed.length} collection${failed.length === 1 ? "" : "s"} failed lexical retrieval proof`
+          : "No configured collection passed lexical retrieval proof",
+    details,
+  };
+}
+
+export function checkConnectorActivation(
+  activation: ActivationStatus
+): DoctorCheck | null {
+  const { projected, total, truncated } = activation.connectorProjection;
+  const omitted = total - projected;
+  const observed = activation.connectors.filter(
+    ({ code }) =>
+      code !== "connector_not_configured" &&
+      code !== "target_runtime_unverifiable"
+  );
+  if (observed.length === 0 && !truncated) {
+    return null;
+  }
+  const incomplete = observed.filter(({ status }) => status !== "passed");
+  const details = incomplete.map(
+    ({ collection, target, status, code, remediation }) =>
+      `${target}/${collection}: ${status}${code ? `/${code}` : ""}${remediation ? `. ${remediation}` : ""}`
+  );
+  if (truncated) {
+    details.unshift(
+      `${omitted} target/collection checks were omitted by the bounded status projection; no result is claimed for them.`
+    );
+  }
+  return {
+    name: "connector-activation",
+    status: incomplete.length > 0 || truncated ? "warn" : "ok",
+    message:
+      incomplete.length > 0
+        ? `${incomplete.length} connector proof${incomplete.length === 1 ? "" : "s"} pending or failed`
+        : truncated
+          ? `${projected} of ${total} connector target/collection checks projected`
+          : `${observed.length} connector proof${observed.length === 1 ? "" : "s"} passed`,
+    details,
+  };
+}

package/src/cli/commands/doctor.ts

@@ -11,12 +11,13 @@ import { stat } from "node:fs/promises";
 import { arch, platform } from "node:os";
 
 import type { Config } from "../../config/types";
+import type { ActivationStatus } from "../../core/activation-status";
 
 import { getIndexDbPath, getModelsCachePath } from "../../app/constants";
 import { getConfigPaths, isInitialized, loadConfig } from "../../config";
+import { isConnectorActivationComplete } from "../../core/activation-connector-health";
 import { getCodeChunkingStatus } from "../../ingestion/chunker";
 import { ModelCache } from "../../llm/cache";
-import { LlmAdapter } from "../../llm/nodeLlamaCpp/adapter";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
 import { loadFts5Snowball } from "../../store/sqlite/fts5-snowball";
@@ -26,6 +27,11 @@ import {
   getLoadAttempts,
 } from "../../store/sqlite/setup";
 import { getStoredEmbeddingFingerprint } from "../../store/vector/freshness";
+import {
+  buildDoctorActivation,
+  checkConnectorActivation,
+  checkRetrievalActivation,
+} from "./doctor-activation";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -63,6 +69,8 @@ export interface EmbeddingFingerprintHealth {
 export interface DoctorOptions {
   /** Override config path */
   configPath?: string;
+  /** Index name */
+  indexName?: string;
   /** Output as JSON */
   json?: boolean;
   /** Output as Markdown */
@@ -72,6 +80,14 @@ export interface DoctorOptions {
 export interface DoctorResult {
   healthy: boolean;
   checks: DoctorCheck[];
+  activation: ActivationStatus;
+}
+
+/** Whether doctor found a process-failing check (warnings remain exit-safe). */
+export function hasCriticalDoctorErrors(
+  checks: readonly DoctorCheck[]
+): boolean {
+  return checks.some(({ status }) => status === "error");
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -105,8 +121,8 @@ async function checkConfig(configPath?: string): Promise<DoctorCheck> {
   };
 }
 
-async function checkDatabase(): Promise<DoctorCheck> {
-  const dbPath = getIndexDbPath();
+async function checkDatabase(indexName?: string): Promise<DoctorCheck> {
+  const dbPath = getIndexDbPath(indexName);
 
   try {
     await stat(dbPath);
@@ -175,9 +191,10 @@ function describeFingerprintGroup(group: EmbeddingFingerprintGroup): string {
 }
 
 async function checkEmbeddingFingerprints(
-  config: Config
+  config: Config,
+  indexName?: string
 ): Promise<DoctorCheck> {
-  const dbPath = getIndexDbPath();
+  const dbPath = getIndexDbPath(indexName);
   try {
     await stat(dbPath);
   } catch {
@@ -312,14 +329,13 @@ async function checkEmbeddingFingerprints(
   }
 }
 
-async function checkNodeLlamaCpp(config: Config): Promise<DoctorCheck> {
-  const llm = new LlmAdapter(config);
+function checkNodeLlamaCpp(): DoctorCheck {
   try {
-    await llm.getManager().getLlama();
+    import.meta.resolve("node-llama-cpp");
     return {
       name: "node-llama-cpp",
       status: "ok",
-      message: "node-llama-cpp loaded successfully",
+      message: "node-llama-cpp package available (runtime not initialized)",
     };
   } catch (e) {
     const message = e instanceof Error ? e.message : String(e);
@@ -328,8 +344,6 @@ async function checkNodeLlamaCpp(config: Config): Promise<DoctorCheck> {
       status: "error",
       message: `node-llama-cpp failed: ${message}`,
     };
-  } finally {
-    await llm.dispose();
   }
 }
 
@@ -495,7 +509,7 @@ export async function doctor(
   checks.push(await checkConfig(options.configPath));
 
   // Database check
-  checks.push(await checkDatabase());
+  checks.push(await checkDatabase(options.indexName));
 
   // Load config for model checks (if available)
   const { createDefaultConfig } = await import("../../config");
@@ -507,7 +521,7 @@ export async function doctor(
   checks.push(...modelChecks);
 
   // node-llama-cpp check
-  checks.push(await checkNodeLlamaCpp(config));
+  checks.push(checkNodeLlamaCpp());
 
   // SQLite extension checks
   const sqliteChecks = await checkSqliteExtensions();
@@ -517,14 +531,25 @@ export async function doctor(
   checks.push(checkCodeChunking());
 
   // Embedding fingerprint freshness
-  checks.push(await checkEmbeddingFingerprints(config));
+  checks.push(await checkEmbeddingFingerprints(config, options.indexName));
+
+  const activation = await buildDoctorActivation(config, options);
+  checks.push(checkRetrievalActivation(activation));
+  const connectorActivation = checkConnectorActivation(activation);
+  if (connectorActivation) {
+    checks.push(connectorActivation);
+  }
 
   // Determine overall health
-  const hasErrors = checks.some((c) => c.status === "error");
+  const hasErrors = hasCriticalDoctorErrors(checks);
 
   return {
-    healthy: !hasErrors,
+    healthy:
+      !hasErrors &&
+      activation.healthy &&
+      isConnectorActivationComplete(activation),
     checks,
+    activation,
   };
 }
 

package/src/cli/commands/get.ts

@@ -9,6 +9,10 @@ import type { DocumentRow, StorePort, StoreResult } from "../../store/types";
 import type { ParsedRef } from "./ref-parser";
 
 import { decorateUriForIndex, parseUri } from "../../app/constants";
+import {
+  INDEX_NAME_REQUIREMENTS,
+  isValidIndexName,
+} from "../../app/index-name";
 import {
   getDocumentCapabilities,
   type DocumentCapabilities,
@@ -114,6 +118,13 @@ export async function get(
   }
   const explicitIndexName =
     parsed.type === "uri" ? parseUri(parsed.value)?.indexName : undefined;
+  if (explicitIndexName !== undefined && !isValidIndexName(explicitIndexName)) {
+    return {
+      success: false,
+      error: `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`,
+      isValidation: true,
+    };
+  }
   const indexName = explicitIndexName ?? options.indexName;
 
   const initResult = await initStore({
@@ -134,6 +145,13 @@ export async function get(
 }
 
 function validateOptions(options: GetCommandOptions): GetResult | null {
+  if (options.indexName !== undefined && !isValidIndexName(options.indexName)) {
+    return {
+      success: false,
+      error: `Invalid index name: ${INDEX_NAME_REQUIREMENTS}.`,
+      isValidation: true,
+    };
+  }
   if (options.from !== undefined && options.from <= 0) {
     return {
       success: false,

package/src/cli/commands/mcp/atomic-config-write.ts

@@ -0,0 +1,118 @@
+/**
+ * Symlink-safe atomic writes for MCP configuration files.
+ *
+ * @module src/cli/commands/mcp/atomic-config-write
+ */
+
+// node:fs/promises supplies structural and metadata operations that Bun does
+// not expose: symlink inspection/resolution, atomic rename, mode changes, and
+// best-effort temporary-file cleanup.
+import {
+  chmod,
+  lstat,
+  mkdir,
+  realpath,
+  rename,
+  stat,
+  unlink,
+} from "node:fs/promises";
+// node:path supplies path manipulation; Bun has no equivalent.
+import { basename, dirname, join } from "node:path";
+
+import { CliError } from "../../errors.js";
+
+interface ResolvedWriteTarget {
+  mode?: number;
+  path: string;
+}
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+function configPathError(configPath: string, detail: string): CliError {
+  return new CliError(
+    "RUNTIME",
+    `Cannot write MCP config ${configPath}: ${detail}`
+  );
+}
+
+async function resolveWriteTarget(
+  configPath: string
+): Promise<ResolvedWriteTarget> {
+  let pathStats: Awaited<ReturnType<typeof lstat>>;
+  try {
+    pathStats = await lstat(configPath);
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return { path: configPath };
+    }
+    throw error;
+  }
+
+  if (!pathStats.isSymbolicLink()) {
+    if (!pathStats.isFile()) {
+      throw configPathError(configPath, "path exists but is not a file");
+    }
+    return { mode: pathStats.mode & 0o7777, path: configPath };
+  }
+
+  let resolvedPath: string;
+  try {
+    resolvedPath = await realpath(configPath);
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      throw configPathError(configPath, "symbolic link target does not exist");
+    }
+    throw error;
+  }
+
+  const targetStats = await stat(resolvedPath);
+  if (!targetStats.isFile()) {
+    throw configPathError(configPath, "symbolic link target is not a file");
+  }
+
+  return { mode: targetStats.mode & 0o7777, path: resolvedPath };
+}
+
+/**
+ * Atomically replace an MCP config file with serialized JSON, YAML, or TOML.
+ *
+ * Existing file permissions survive replacement. A config-path symlink remains
+ * in place: its resolved file is replaced by a temporary sibling. Dangling
+ * symlinks fail closed instead of being replaced with regular files.
+ */
+export async function writeMcpConfigTextAtomically(
+  configPath: string,
+  content: string
+): Promise<void> {
+  await mkdir(dirname(configPath), { recursive: true });
+
+  const target = await resolveWriteTarget(configPath);
+  const targetDirectory = dirname(target.path);
+  const tempPath = join(
+    targetDirectory,
+    `.${basename(target.path)}.gno-tmp-${process.pid}-${crypto.randomUUID()}`
+  );
+
+  try {
+    await Bun.write(tempPath, content, {
+      createPath: false,
+      ...(target.mode === undefined ? {} : { mode: target.mode & 0o777 }),
+    });
+    if (target.mode !== undefined) {
+      // Bun 1.3 does not consistently apply Bun.write's mode option on macOS.
+      await chmod(tempPath, target.mode);
+    }
+    await rename(tempPath, target.path);
+  } catch (error) {
+    await unlink(tempPath).catch(() => {
+      // The write may have failed before creating the temporary file.
+    });
+    throw error;
+  }
+}

package/src/cli/commands/mcp/config-discovery.ts

@@ -0,0 +1,42 @@
+/** Resolve one unambiguous MCP client config filename. */
+
+// node:fs/promises has no Bun equivalent for lstat, including dangling links.
+import { lstat } from "node:fs/promises";
+
+import type { McpConfigPaths } from "./paths.js";
+
+import { CliError } from "../../errors.js";
+
+export async function configPathEntryExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export async function resolveMcpConfigLocation(
+  paths: McpConfigPaths
+): Promise<string> {
+  const candidates = [
+    paths.configPath,
+    ...(paths.alternativeConfigPaths ?? []),
+  ];
+  const present: string[] = [];
+  for (const candidate of candidates) {
+    if (await configPathEntryExists(candidate)) {
+      present.push(candidate);
+    }
+  }
+  if (present.length > 1) {
+    throw new CliError(
+      "RUNTIME",
+      `Ambiguous MCP config files: ${present.join(", ")}. Keep exactly one.`
+    );
+  }
+  return present[0] ?? paths.configPath;
+}