@gmickel/gno 0.6.0 → 0.7.0

package/README.md

@@ -36,6 +36,8 @@ gno query "auth best practices"  # Hybrid search
 gno ask "summarize the API" --answer  # AI answer with citations
 ```
 
+![GNO CLI](./assets/screenshots/cli.jpg)
+
 ---
 
 ## Installation
@@ -127,6 +129,8 @@ gno serve                    # Start on port 3000
 gno serve --port 8080        # Custom port
 ```
 
+![GNO Web UI](./assets/screenshots/webui-home.jpg)
+
 Open `http://localhost:3000` to:
 
 - **Search** — BM25, vector, or hybrid modes with visual results
@@ -181,6 +185,8 @@ No authentication. No rate limits. Build custom tools, automate workflows, integ
 
 ### MCP Server
 
+![GNO MCP](./assets/screenshots/mcp.jpg)
+
 GNO exposes 6 tools via [Model Context Protocol](https://modelcontextprotocol.io):
 
 | Tool | Description |
@@ -202,6 +208,8 @@ Skills add GNO search to Claude Code/Codex without MCP protocol overhead:
 gno skill install --scope user
 ```
 
+![GNO Skill in Claude Code](./assets/screenshots/claudecodeskill.jpg)
+
 Then ask your agent: *"Search my notes for the auth discussion"*
 
 > **Detailed docs**: [MCP Integration](https://gno.sh/docs/MCP/) · [Use Cases](https://gno.sh/docs/USE-CASES/)
@@ -280,7 +288,7 @@ Models auto-download on first use to `~/.cache/gno/models/`.
 
 ```bash
 gno models use balanced
-gno models pull --all
+gno models pull --all  # Optional: pre-download models (auto-downloads on first use)
 ```
 
 > **Configuration**: [Model Setup](https://gno.sh/docs/CONFIGURATION/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "search",
@@ -33,7 +33,7 @@
     "vendor"
   ],
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.3.0"
   },
   "publishConfig": {
     "access": "public"
@@ -113,11 +113,11 @@
     "evalite": "^1.0.0-beta.15",
     "exceljs": "^4.4.0",
     "lefthook": "^2.0.13",
-    "oxlint-tsgolint": "^0.10.0",
+    "oxlint-tsgolint": "^0.10.1",
     "pdf-lib": "^1.17.1",
     "pptxgenjs": "^4.0.1",
     "tailwindcss": "^4.1.18",
-    "ultracite": "6.5.0"
+    "ultracite": "7.0.4"
   },
   "peerDependencies": {
     "typescript": "^5"

package/src/cli/commands/ask.ts

@@ -6,6 +6,7 @@
  */
 
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type {
   EmbeddingPort,
@@ -22,6 +23,11 @@ import {
   createVectorIndexPort,
   type VectorIndexPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 import { initStore } from './shared';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -82,9 +88,26 @@ export async function ask(
     const preset = getActivePreset(config);
     const llm = new LlmAdapter(config);
 
+    // Resolve download policy from env/flags
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model downloads (throttled)
+    const showProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     // Create embedding port
     const embedUri = options.embedModel ?? preset.embed;
-    const embedResult = await llm.createEmbeddingPort(embedUri);
+    const embedResult = await llm.createEmbeddingPort(embedUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (embedResult.ok) {
       embedPort = embedResult.value;
     }
@@ -94,7 +117,12 @@ export async function ask(
     const needsGen = !options.noExpand || options.answer;
     if (needsGen) {
       const genUri = options.genModel ?? preset.gen;
-      const genResult = await llm.createGenerationPort(genUri);
+      const genResult = await llm.createGenerationPort(genUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('gen', progress)
+          : undefined,
+      });
       if (genResult.ok) {
         genPort = genResult.value;
       }
@@ -103,12 +131,22 @@ export async function ask(
     // Create rerank port (unless --fast or --no-rerank)
     if (!options.noRerank) {
       const rerankUri = options.rerankModel ?? preset.rerank;
-      const rerankResult = await llm.createRerankPort(rerankUri);
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('rerank', progress)
+          : undefined,
+      });
       if (rerankResult.ok) {
         rerankPort = rerankResult.value;
       }
     }
 
+    // Clear progress line if shown
+    if (showProgress && downloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Create vector index
     let vectorIndex: VectorIndexPort | null = null;
     if (embedPort) {

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

@@ -2,11 +2,8 @@
  * gno collection add - Add a new collection
  */
 
+import { addCollection } from '../../../collection';
 import {
-  type Collection,
-  CollectionSchema,
-  DEFAULT_EXCLUDES,
-  DEFAULT_PATTERN,
   loadConfig,
   pathExists,
   saveConfig,
@@ -31,83 +28,45 @@ export async function collectionAdd(
     throw new CliError('VALIDATION', '--name is required');
   }
 
-  const collectionName = options.name.toLowerCase();
-
-  // Expand and validate path
+  // Validate path exists BEFORE loading config (user-friendly error ordering)
   const absolutePath = toAbsolutePath(path);
-
-  // Check if path exists
   const exists = await pathExists(absolutePath);
   if (!exists) {
     throw new CliError('VALIDATION', `Path does not exist: ${absolutePath}`);
   }
 
   // Load config
-  const result = await loadConfig();
-  if (!result.ok) {
+  const configResult = await loadConfig();
+  if (!configResult.ok) {
     throw new CliError(
       'RUNTIME',
-      `Failed to load config: ${result.error.message}`
+      `Failed to load config: ${configResult.error.message}`
     );
   }
 
-  const config = result.value;
-
-  // Check for duplicate name
-  const existing = config.collections.find((c) => c.name === collectionName);
-  if (existing) {
-    throw new CliError(
-      'VALIDATION',
-      `Collection "${collectionName}" already exists`
-    );
-  }
-
-  // Parse options - filter empty, dedupe
-  const includeList = options.include
-    ? [
-        ...new Set(
-          options.include
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean)
-        ),
-      ]
-    : [];
-  const excludeList = options.exclude
-    ? [
-        ...new Set(
-          options.exclude
-            .split(',')
-            .map((s) => s.trim())
-            .filter(Boolean)
-        ),
-      ]
-    : [...DEFAULT_EXCLUDES];
-
-  // Build collection
-  const collection: Collection = {
-    name: collectionName,
-    path: absolutePath,
-    pattern: options.pattern ?? DEFAULT_PATTERN,
-    include: includeList,
-    exclude: excludeList,
+  // Add collection using shared module
+  const result = await addCollection(configResult.value, {
+    path,
+    name: options.name,
+    pattern: options.pattern,
+    include: options.include,
+    exclude: options.exclude,
     updateCmd: options.update,
-  };
+  });
 
-  // Validate collection
-  const validation = CollectionSchema.safeParse(collection);
-  if (!validation.success) {
-    throw new CliError(
-      'VALIDATION',
-      `Invalid collection: ${validation.error.issues[0]?.message ?? 'unknown error'}`
-    );
+  if (!result.ok) {
+    // Map collection error codes to CLI error codes
+    const cliCode =
+      result.code === 'VALIDATION' ||
+      result.code === 'PATH_NOT_FOUND' ||
+      result.code === 'DUPLICATE'
+        ? 'VALIDATION'
+        : 'RUNTIME';
+    throw new CliError(cliCode, result.message);
   }
 
-  // Add to config
-  config.collections.push(validation.data);
-
   // Save config
-  const saveResult = await saveConfig(config);
+  const saveResult = await saveConfig(result.config);
   if (!saveResult.ok) {
     throw new CliError(
       'RUNTIME',
@@ -115,6 +74,8 @@ export async function collectionAdd(
     );
   }
 
-  process.stdout.write(`Collection "${collectionName}" added successfully\n`);
-  process.stdout.write(`Path: ${absolutePath}\n`);
+  process.stdout.write(
+    `Collection "${result.collection.name}" added successfully\n`
+  );
+  process.stdout.write(`Path: ${result.collection.path}\n`);
 }

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

@@ -2,57 +2,36 @@
  * gno collection remove - Remove a collection
  */
 
-import {
-  getCollectionFromScope,
-  loadConfig,
-  saveConfig,
-} from '../../../config';
+import { removeCollection } from '../../../collection';
+import { loadConfig, saveConfig } from '../../../config';
 import { CliError } from '../../errors';
 
 export async function collectionRemove(name: string): Promise<void> {
-  const collectionName = name.toLowerCase();
-
   // Load config
-  const result = await loadConfig();
-  if (!result.ok) {
+  const configResult = await loadConfig();
+  if (!configResult.ok) {
     throw new CliError(
       'RUNTIME',
-      `Failed to load config: ${result.error.message}`
+      `Failed to load config: ${configResult.error.message}`
     );
   }
 
-  const config = result.value;
-
-  // Find collection
-  const collectionIndex = config.collections.findIndex(
-    (c) => c.name === collectionName
-  );
-  if (collectionIndex === -1) {
-    throw new CliError(
-      'VALIDATION',
-      `Collection "${collectionName}" not found`
-    );
-  }
+  // Remove collection using shared module
+  const result = removeCollection(configResult.value, { name });
 
-  // Check if any contexts reference this collection
-  const referencingContexts = config.contexts.filter((ctx) => {
-    const collFromScope = getCollectionFromScope(ctx.scopeKey);
-    return collFromScope === collectionName;
-  });
-
-  if (referencingContexts.length > 0) {
-    const scopes = referencingContexts.map((ctx) => ctx.scopeKey).join(', ');
-    throw new CliError(
-      'VALIDATION',
-      `Collection "${collectionName}" is referenced by contexts: ${scopes}. Remove the contexts first or rename the collection.`
-    );
+  if (!result.ok) {
+    // Map collection error codes to CLI error codes
+    const cliCode =
+      result.code === 'VALIDATION' ||
+      result.code === 'NOT_FOUND' ||
+      result.code === 'HAS_REFERENCES'
+        ? 'VALIDATION'
+        : 'RUNTIME';
+    throw new CliError(cliCode, result.message);
   }
 
-  // Remove collection
-  config.collections.splice(collectionIndex, 1);
-
   // Save config
-  const saveResult = await saveConfig(config);
+  const saveResult = await saveConfig(result.config);
   if (!saveResult.ok) {
     throw new CliError(
       'RUNTIME',
@@ -60,5 +39,7 @@ export async function collectionRemove(name: string): Promise<void> {
     );
   }
 
-  process.stdout.write(`Collection "${collectionName}" removed successfully\n`);
+  process.stdout.write(
+    `Collection "${result.collection.name}" removed successfully\n`
+  );
 }

package/src/cli/commands/embed.ts

@@ -7,8 +7,14 @@
 
 import type { Database } from 'bun:sqlite';
 import { getIndexDbPath } from '../../app/constants';
-import { getConfigPaths, isInitialized, loadConfig } from '../../config';
+import {
+  type Config,
+  getConfigPaths,
+  isInitialized,
+  loadConfig,
+} from '../../config';
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type { EmbeddingPort } from '../../llm/types';
 import { formatDocForEmbedding } from '../../pipeline/contextual';
@@ -23,6 +29,11 @@ import {
   type VectorRow,
   type VectorStatsPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -191,35 +202,36 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Main Command
+// Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 
+interface EmbedContext {
+  config: Config;
+  modelUri: string;
+  store: SqliteAdapter;
+}
+
 /**
- * Execute gno embed command.
+ * Initialize embed context: check init, load config, open store.
  */
-export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
-  const batchSize = options.batchSize ?? 32;
-  const force = options.force ?? false;
-  const dryRun = options.dryRun ?? false;
-
-  // Check initialization
-  const initialized = await isInitialized(options.configPath);
+async function initEmbedContext(
+  configPath?: string,
+  model?: string
+): Promise<({ ok: true } & EmbedContext) | { ok: false; error: string }> {
+  const initialized = await isInitialized(configPath);
   if (!initialized) {
-    return { success: false, error: 'GNO not initialized. Run: gno init' };
+    return { ok: false, error: 'GNO not initialized. Run: gno init' };
   }
 
-  // Load config
-  const configResult = await loadConfig(options.configPath);
+  const configResult = await loadConfig(configPath);
   if (!configResult.ok) {
-    return { success: false, error: configResult.error.message };
+    return { ok: false, error: configResult.error.message };
   }
   const config = configResult.value;
 
-  // Get model URI
   const preset = getActivePreset(config);
-  const modelUri = options.model ?? preset.embed;
+  const modelUri = model ?? preset.embed;
 
-  // Open store
   const store = new SqliteAdapter();
   const dbPath = getIndexDbPath();
   const paths = getConfigPaths();
@@ -227,9 +239,31 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
 
   const openResult = await store.open(dbPath, config.ftsTokenizer);
   if (!openResult.ok) {
-    return { success: false, error: openResult.error.message };
+    return { ok: false, error: openResult.error.message };
   }
 
+  return { ok: true, config, modelUri, store };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Command
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute gno embed command.
+ */
+export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
+  const batchSize = options.batchSize ?? 32;
+  const force = options.force ?? false;
+  const dryRun = options.dryRun ?? false;
+
+  // Initialize config and store
+  const initResult = await initEmbedContext(options.configPath, options.model);
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+  const { config, modelUri, store } = initResult;
+
   // Get raw DB for vector ops (SqliteAdapter always implements SqliteDbProvider)
   const db = store.getRawDb();
   let embedPort: EmbeddingPort | null = null;
@@ -274,14 +308,35 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       };
     }
 
-    // Create LLM adapter and embedding port
+    // Create LLM adapter and embedding port with auto-download
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model download (throttled to avoid spam)
+    const showDownloadProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showDownloadProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     const llm = new LlmAdapter(config);
-    const embedResult = await llm.createEmbeddingPort(modelUri);
+    const embedResult = await llm.createEmbeddingPort(modelUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (!embedResult.ok) {
       return { success: false, error: embedResult.error.message };
     }
     embedPort = embedResult.value;
 
+    // Clear download progress line if shown
+    if (showDownloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Discover dimensions via probe embedding
     const probeResult = await embedPort.embed('dimension probe');
     if (!probeResult.ok) {

package/src/cli/commands/models/index.ts

@@ -4,6 +4,7 @@
  * @module src/cli/commands/models
  */
 
+export { createProgressRenderer } from '../../progress';
 export {
   formatModelsClear,
   type ModelsClearOptions,
@@ -23,7 +24,6 @@ export {
   modelsPath,
 } from './path';
 export {
-  createProgressRenderer,
   formatModelsPull,
   type ModelPullResult,
   type ModelsPullOptions,

package/src/cli/commands/models/pull.ts

@@ -185,20 +185,3 @@ export function formatModelsPull(result: ModelsPullResult): string {
 
   return lines.join('\n');
 }
-
-/**
- * Create a terminal progress renderer.
- */
-export function createProgressRenderer(): (
-  type: ModelType,
-  progress: DownloadProgress
-) => void {
-  return (type, progress) => {
-    const percent = progress.percent.toFixed(1);
-    const downloaded = (progress.downloadedBytes / 1024 / 1024).toFixed(1);
-    const total = (progress.totalBytes / 1024 / 1024).toFixed(1);
-    process.stderr.write(
-      `\r${type}: ${percent}% (${downloaded}/${total} MB)    `
-    );
-  };
-}

package/src/cli/commands/query.ts

@@ -6,6 +6,7 @@
  */
 
 import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { resolveDownloadPolicy } from '../../llm/policy';
 import { getActivePreset } from '../../llm/registry';
 import type {
   EmbeddingPort,
@@ -18,6 +19,11 @@ import {
   createVectorIndexPort,
   type VectorIndexPort,
 } from '../../store/vector';
+import { getGlobals } from '../program';
+import {
+  createProgressRenderer,
+  createThrottledProgressRenderer,
+} from '../progress';
 import { initStore } from './shared';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -90,9 +96,26 @@ export async function query(
     const preset = getActivePreset(config);
     const llm = new LlmAdapter(config);
 
+    // Resolve download policy from env/flags
+    const globals = getGlobals();
+    const policy = resolveDownloadPolicy(process.env, {
+      offline: globals.offline,
+    });
+
+    // Create progress renderer for model downloads (throttled)
+    const showProgress = !options.json && process.stderr.isTTY;
+    const downloadProgress = showProgress
+      ? createThrottledProgressRenderer(createProgressRenderer())
+      : undefined;
+
     // Create embedding port (for vector search)
     const embedUri = options.embedModel ?? preset.embed;
-    const embedResult = await llm.createEmbeddingPort(embedUri);
+    const embedResult = await llm.createEmbeddingPort(embedUri, {
+      policy,
+      onProgress: downloadProgress
+        ? (progress) => downloadProgress('embed', progress)
+        : undefined,
+    });
     if (embedResult.ok) {
       embedPort = embedResult.value;
     }
@@ -100,7 +123,12 @@ export async function query(
     // Create generation port (for expansion) - optional
     if (!options.noExpand) {
       const genUri = options.genModel ?? preset.gen;
-      const genResult = await llm.createGenerationPort(genUri);
+      const genResult = await llm.createGenerationPort(genUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('gen', progress)
+          : undefined,
+      });
       if (genResult.ok) {
         genPort = genResult.value;
       }
@@ -109,12 +137,22 @@ export async function query(
     // Create rerank port - optional
     if (!options.noRerank) {
       const rerankUri = options.rerankModel ?? preset.rerank;
-      const rerankResult = await llm.createRerankPort(rerankUri);
+      const rerankResult = await llm.createRerankPort(rerankUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress('rerank', progress)
+          : undefined,
+      });
       if (rerankResult.ok) {
         rerankPort = rerankResult.value;
       }
     }
 
+    // Clear progress line if shown
+    if (showProgress && downloadProgress) {
+      process.stderr.write('\n');
+    }
+
     // Create vector index (optional)
     let vectorIndex: VectorIndexPort | null = null;
     if (embedPort) {