@nusoft/nuos-build-catalogue 0.20.0 → 0.20.1

package/dist/commands/init.js

@@ -296,16 +296,13 @@ export async function cmdInstallProtocols(prompt, options = {}) {
     prompt.print('');
     prompt.print('Checking local semantic search (Ollama + qwen3-embedding:0.6b):');
     await reportLlmStatus((msg) => prompt.print(`  ${msg}`));
-    // Auto-build the search index when the LLM is ready but the index
-    // isn't present yet (typical upgrade-path state: pre-0.19 install +
-    // someone just added docs/build/ content). When the index already
-    // exists this is a no-op; when the LLM isn't ready the helper skips
-    // with a hint that's already printed by reportLlmStatus.
+    // Auto-build/refresh the search index when the LLM is ready. The
+    // indexer is incremental via per-file SHA hashes: a no-change project
+    // takes ~1s, a project with N changed files takes O(N) embed calls.
+    // When the LLM stack isn't ready the helper skips silently — the
+    // status was already reported above by reportLlmStatus.
     const { ensureIndexBuilt } = await import('../setup/auto-index.js');
-    const indexResult = await ensureIndexBuilt({ cwd });
-    if (indexResult.kind === 'just_built') {
-        prompt.print(`  ✓ Built search index (${indexResult.indexed} files, ${indexResult.chunks} chunks).`);
-    }
+    await ensureIndexBuilt({ cwd });
     return { output: '', exitCode: 0 };
 }
 /**

package/dist/setup/auto-index.d.ts

@@ -15,13 +15,17 @@
  * @module setup/auto-index
  */
 /** Outcome of an auto-index attempt. */
-export type AutoIndexResult = {
-    kind: 'already_built';
-    indexPath: string;
-} | {
-    kind: 'just_built';
+export type AutoIndexResult = 
+/**
+ * The indexer ran. `indexed` includes both freshly-embedded files and
+ * re-embedded changed ones. `unchanged` is non-zero on subsequent
+ * runs — those files were SHA-matched and skipped without embedding.
+ */
+{
+    kind: 'ran';
     indexPath: string;
     indexed: number;
+    unchanged: number;
     chunks: number;
     durationMs: number;
 } | {
@@ -43,10 +47,11 @@ export interface AutoIndexOptions {
     force?: boolean;
 }
 /**
- * Build the first search index when conditions allow. Idempotent: returns
- * `already_built` and prints nothing when the index file exists (unless
- * `force` is set). Returns `skipped_llm_not_ready` with a hint when the
- * Ollama probe fails — the caller prints the hint and the user runs
+ * Run the indexer when conditions allow. Always runs (the indexer is
+ * incremental — unchanged files are SHA-skipped without embedding work),
+ * so this both *creates* the index on first call and *refreshes* it on
+ * subsequent calls. Returns `skipped_llm_not_ready` with a hint when
+ * the Ollama probe fails — the caller prints the hint and the user runs
  * `setup-llm` to fix things.
  *
  * Never throws on user-facing failures.

package/dist/setup/auto-index.js

@@ -19,10 +19,11 @@ import { resolveBuildRoot, resolveCatalogueRoot, resolveHashPath, resolveIndexPa
 import { DEFAULT_OLLAMA_HOST, detectModelPresent, detectOllamaApi } from './ollama-detect.js';
 import { DEFAULT_EMBEDDING_MODEL } from './run-llm-setup.js';
 /**
- * Build the first search index when conditions allow. Idempotent: returns
- * `already_built` and prints nothing when the index file exists (unless
- * `force` is set). Returns `skipped_llm_not_ready` with a hint when the
- * Ollama probe fails — the caller prints the hint and the user runs
+ * Run the indexer when conditions allow. Always runs (the indexer is
+ * incremental — unchanged files are SHA-skipped without embedding work),
+ * so this both *creates* the index on first call and *refreshes* it on
+ * subsequent calls. Returns `skipped_llm_not_ready` with a hint when
+ * the Ollama probe fails — the caller prints the hint and the user runs
  * `setup-llm` to fix things.
  *
  * Never throws on user-facing failures.
@@ -49,10 +50,13 @@ export async function ensureIndexBuilt(opts = {}) {
     catch {
         return { kind: 'skipped_no_catalogue' };
     }
-    // Fast path: index file already exists and we're not forcing a rebuild.
-    if (existsSync(indexPath) && !opts.force) {
-        return { kind: 'already_built', indexPath };
-    }
+    // We do not short-circuit on `existsSync(indexPath)` — the indexer is
+    // already incremental via the per-file SHA hash store, so running it
+    // when the index is up-to-date is cheap (~1s on a 270-file catalogue
+    // with no changes). Short-circuiting here would leave newer files
+    // un-embedded until the user ran `nuos-catalogue index` manually,
+    // which is exactly the discoverability gap the auto-index is meant to
+    // close.
     // Probe the LLM stack — index requires Ollama + the model. If either
     // is missing, skip with a hint pointing at setup-llm.
     const apiHost = process.env.NUOS_CATALOGUE_OLLAMA_HOST ?? DEFAULT_OLLAMA_HOST;
@@ -73,10 +77,17 @@ export async function ensureIndexBuilt(opts = {}) {
             hint: 'Run `nuos-catalogue setup-llm` to pull the embedding model (~600 MB), then re-run `nuos-catalogue index`.',
         };
     }
-    // LLM is ready. Build the index. We import lazily so the cold-start
-    // path of `install-protocols` (where the index usually already exists)
-    // doesn't pay the embedder-loading cost.
-    out('Building search index for docs/build/ … (first run may take ~30 seconds)\n');
+    // LLM is ready. Run the indexer. The first run on a fresh project is
+    // ~30s of starter-kit content; subsequent runs are fast — the
+    // per-file SHA hashes mean unchanged files are skipped without
+    // embedding.
+    const isFirstRun = !existsSync(indexPath);
+    if (isFirstRun) {
+        out('Building search index for docs/build/ … (first run may take ~30 seconds)\n');
+    }
+    else {
+        out('Refreshing search index (incremental — only changed files are re-embedded)…\n');
+    }
     try {
         const { selectEmbedderFromEnv } = await import('../embedder/select.js');
         const { openStore } = await import('../store/open.js');
@@ -92,12 +103,23 @@ export async function ensureIndexBuilt(opts = {}) {
                 force: Boolean(opts.force),
                 dryRun: false,
             });
-            out(`✓ Indexed ${report.indexed} file(s), ${report.chunks} chunks embedded in ` +
-                `${(report.durationMs / 1000).toFixed(1)}s\n`);
+            const changed = report.indexed + report.updated;
+            const secs = (report.durationMs / 1000).toFixed(1);
+            if (isFirstRun) {
+                out(`✓ Indexed ${report.indexed} file(s), ${report.chunks} chunks embedded in ${secs}s\n`);
+            }
+            else if (changed === 0) {
+                out(`✓ Index up-to-date (${report.unchanged} files checked, none changed) in ${secs}s\n`);
+            }
+            else {
+                out(`✓ Re-indexed ${changed} changed file(s) (${report.unchanged} unchanged), ` +
+                    `${report.chunks} chunks embedded in ${secs}s\n`);
+            }
             return {
-                kind: 'just_built',
+                kind: 'ran',
                 indexPath,
-                indexed: report.indexed,
+                indexed: changed,
+                unchanged: report.unchanged,
                 chunks: report.chunks,
                 durationMs: report.durationMs,
             };
@@ -109,7 +131,7 @@ export async function ensureIndexBuilt(opts = {}) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        out(`\n✗ Index build failed: ${message}\n`);
+        out(`\n✗ Index refresh failed: ${message}\n`);
         out('Re-run `nuos-catalogue index` manually to retry.\n');
         return { kind: 'failed', error: message };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nusoft/nuos-build-catalogue",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "NuOS build-catalogue tooling: semantic search (WU 110) + migration runner that lifts markdown artefacts into JSON-backed workflow records (WU 111, Phase G).",
   "type": "module",
   "bin": {