@cruxy/cli 1.0.0 → 1.0.2

package/README.md

@@ -161,7 +161,7 @@ branch on them:
 | `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                                                             |
 | `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                                                   |
 | `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`, `CRUXY_E_CHECKPOINT_FAILED`                                                                                            |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                                                      |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                            |
 | `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                                                   |
 | `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`, `CRUXY_E_ROLLBACK_APPROVAL_REQUIRED`                                                                                                  |
 

package/dist/cli/commands/usage.js

@@ -44,8 +44,15 @@ export function usageCommand() {
         logger.print(t.heading(`usage — ${scopeLabel}`));
         logger.print(renderSummary(summary, t));
         // State when NO price is configured, so an absent cost never reads as $0.
+        // Self-contained: set a number, see cost — copy-pasteable commands, no
+        // docs lookup and no jargon needed.
         if (!summary.priced) {
-            logger.print(t.muted("cost omitted — no prices configured (set usage.prices.<tier>.{input,output}, per million tokens)"));
+            logger.print(t.muted([
+                "cost omitted — no prices set. To see cost, set your per-million-token",
+                "rates for each tier (kavi, vaani, mira):",
+                "  cruxy config set usage.prices.kavi.input 0.5",
+                "  cruxy config set usage.prices.kavi.output 1.5",
+            ].join("\n")));
         }
     });
 }

package/dist/config/schema.d.ts

@@ -185,15 +185,30 @@ export declare const IndexConfigSchema: z.ZodObject<{
     /**
      * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
      * model downloads and caches on first use) is selectable — if it cannot be
-     * loaded, indexing fails loudly rather than degrading. (The deterministic
-     * hashing embedder exists for tests and is injected directly, never chosen
-     * here.)
+     * loaded, or the model cannot be downloaded/initialized, indexing fails
+     * loudly rather than degrading. (The deterministic hashing embedder exists
+     * for tests and is injected directly, never chosen here.)
+     *
+     * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+     * embedder has NO degrade path while the store's `auto` does, and that is
+     * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+     * only PERSISTENCE — search results are byte-identical, you just re-index
+     * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+     * substitute is the lexical hashing backend, whose degrade is a SILENT
+     * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+     * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+     * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+     * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+     * model to `grep_files` rather than substituting a weaker index.
      */
     embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
     /**
      * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
      * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-     * falls back to memory when the native dependency cannot be loaded.
+     * falls back to memory when the native dependency cannot be loaded — a
+     * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+     * This is why `auto` may degrade while `embedder` may not — see the
+     * asymmetry note above.
      */
     store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
     /** Hard per-file size cap, in bytes; larger files are skipped entirely. */
@@ -1184,15 +1199,30 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         /**
          * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
          * model downloads and caches on first use) is selectable — if it cannot be
-         * loaded, indexing fails loudly rather than degrading. (The deterministic
-         * hashing embedder exists for tests and is injected directly, never chosen
-         * here.)
+         * loaded, or the model cannot be downloaded/initialized, indexing fails
+         * loudly rather than degrading. (The deterministic hashing embedder exists
+         * for tests and is injected directly, never chosen here.)
+         *
+         * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+         * embedder has NO degrade path while the store's `auto` does, and that is
+         * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+         * only PERSISTENCE — search results are byte-identical, you just re-index
+         * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+         * substitute is the lexical hashing backend, whose degrade is a SILENT
+         * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+         * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+         * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+         * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+         * model to `grep_files` rather than substituting a weaker index.
          */
         embedder: z.ZodDefault<z.ZodEnum<["fastembed"]>>;
         /**
          * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
          * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-         * falls back to memory when the native dependency cannot be loaded.
+         * falls back to memory when the native dependency cannot be loaded — a
+         * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+         * This is why `auto` may degrade while `embedder` may not — see the
+         * asymmetry note above.
          */
         store: z.ZodDefault<z.ZodEnum<["auto", "sqlite", "memory"]>>;
         /** Hard per-file size cap, in bytes; larger files are skipped entirely. */

package/dist/config/schema.js

@@ -146,15 +146,30 @@ export const IndexConfigSchema = z
     /**
      * Embedding backend. Only `fastembed` (bge-small-en-v1.5, local ONNX; the
      * model downloads and caches on first use) is selectable — if it cannot be
-     * loaded, indexing fails loudly rather than degrading. (The deterministic
-     * hashing embedder exists for tests and is injected directly, never chosen
-     * here.)
+     * loaded, or the model cannot be downloaded/initialized, indexing fails
+     * loudly rather than degrading. (The deterministic hashing embedder exists
+     * for tests and is injected directly, never chosen here.)
+     *
+     * THE STORE-VS-EMBEDDER ASYMMETRY (deliberate — see `store` below). The
+     * embedder has NO degrade path while the store's `auto` does, and that is
+     * correct, not an inconsistency: a store fallback (sqlite → in-memory) loses
+     * only PERSISTENCE — search results are byte-identical, you just re-index
+     * each session, a quality-NEUTRAL trade. The embedder's only cheaper
+     * substitute is the lexical hashing backend, whose degrade is a SILENT
+     * QUALITY LOSS — semantic search quietly stops being semantic. That is the
+     * "reads like success, isn't" trap C.17 forbids, so the embedder fails loud
+     * (module-load → CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE; first-run download/init
+     * → CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED) and `search_codebase` routes the
+     * model to `grep_files` rather than substituting a weaker index.
      */
     embedder: z.enum(["fastembed"]).default("fastembed"),
     /**
      * Vector store backend. `sqlite` persists to `.cruxy/index.db` via
      * better-sqlite3; `memory` is ephemeral (tests). `auto` prefers sqlite and
-     * falls back to memory when the native dependency cannot be loaded.
+     * falls back to memory when the native dependency cannot be loaded — a
+     * quality-NEUTRAL degrade (only persistence is lost; results are identical).
+     * This is why `auto` may degrade while `embedder` may not — see the
+     * asymmetry note above.
      */
     store: z.enum(["auto", "sqlite", "memory"]).default("auto"),
     /** Hard per-file size cap, in bytes; larger files are skipped entirely. */

package/dist/errors/constructors.d.ts

@@ -41,6 +41,22 @@ export declare function budgetExhausted(underlying?: unknown): CruxyError;
 export declare function fileNotFound(path: string, underlying?: unknown): CruxyError;
 export declare function permissionDenied(path: string, underlying?: unknown): CruxyError;
 export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
+/**
+ * The fastembed module loaded, but the model could not be brought up at runtime
+ * — the first-run download/decompress of bge-small-en-v1.5, or the ONNX-runtime
+ * init, failed. This is the COMMON first-run failure (offline, the model bucket
+ * is unreachable, a corporate proxy blocks it), and it is deliberately kept
+ * distinct from both {@link indexEmbedderUnavailable} (a module *load* failure)
+ * and the generic {@link indexFailed} ("re-run --verbose") so the cause is
+ * actionable rather than a shrug.
+ *
+ * Fail-loud, not degrade: there is no fallback to the lexical hashing embedder
+ * (a silent quality loss). `cruxy index` treats this as fatal — the user
+ * explicitly asked to build the index, so a silent no-op index would be the
+ * exact "reads like success, isn't" trap C.17 forbids. The `search_codebase`
+ * tool instead surfaces it as a tool error and points the model at `grep_files`.
+ */
+export declare function indexEmbedderDownloadFailed(underlying?: unknown): CruxyError;
 export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
 export declare function indexFailed(underlying?: unknown): CruxyError;
 /**

package/dist/errors/constructors.js

@@ -266,6 +266,34 @@ export function indexEmbedderUnavailable(underlying) {
         underlying,
     });
 }
+/**
+ * The fastembed module loaded, but the model could not be brought up at runtime
+ * — the first-run download/decompress of bge-small-en-v1.5, or the ONNX-runtime
+ * init, failed. This is the COMMON first-run failure (offline, the model bucket
+ * is unreachable, a corporate proxy blocks it), and it is deliberately kept
+ * distinct from both {@link indexEmbedderUnavailable} (a module *load* failure)
+ * and the generic {@link indexFailed} ("re-run --verbose") so the cause is
+ * actionable rather than a shrug.
+ *
+ * Fail-loud, not degrade: there is no fallback to the lexical hashing embedder
+ * (a silent quality loss). `cruxy index` treats this as fatal — the user
+ * explicitly asked to build the index, so a silent no-op index would be the
+ * exact "reads like success, isn't" trap C.17 forbids. The `search_codebase`
+ * tool instead surfaces it as a tool error and points the model at `grep_files`.
+ */
+export function indexEmbedderDownloadFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexEmbedderDownloadFailed,
+        title: "the local embedding model could not be downloaded or initialized",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check your internet connection — the model (bge-small-en-v1.5) downloads once on first use",
+            "if you are behind a proxy or firewall, allow access to the model host (Hugging Face) and set HTTPS_PROXY",
+            "once the download succeeds it is cached under ~/.cruxy/models and never re-fetched",
+        ],
+        underlying,
+    });
+}
 export function indexStoreUnavailable(underlying) {
     return new CruxyError({
         code: ErrorCode.IndexStoreUnavailable,

package/dist/errors/types.d.ts

@@ -46,7 +46,18 @@ export declare const ErrorCode: {
     readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
     readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
     readonly CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED";
+    /** The fastembed native module could not be LOADED (missing/broken install,
+     * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
+     * silently degrades to the lexical hashing backend (that would be a silent
+     * quality loss). See the store-vs-embedder asymmetry note in `schema.ts`. */
     readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
+    /** The fastembed module loaded, but the model could not be brought up at
+     * RUNTIME — the first-run download/decompress, or the ONNX-runtime init,
+     * failed (offline, the model bucket is unreachable, a proxy blocks it). Kept
+     * DISTINCT from `IndexEmbedderUnavailable` (a load failure) and from the
+     * generic `IndexFailed` ("re-run --verbose") so the actual, common first-run
+     * failure carries an actionable cause instead of a shrug. */
+    readonly IndexEmbedderDownloadFailed: "CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED";
     readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
     readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
     readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";

package/dist/errors/types.js

@@ -54,7 +54,18 @@ export const ErrorCode = {
     PathEscape: "CRUXY_E_PATH_ESCAPE",
     CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED",
     // index (exit 8)
+    /** The fastembed native module could not be LOADED (missing/broken install,
+     * un-built onnxruntime-node addon). Fail-loud by design — the embedder never
+     * silently degrades to the lexical hashing backend (that would be a silent
+     * quality loss). See the store-vs-embedder asymmetry note in `schema.ts`. */
     IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE",
+    /** The fastembed module loaded, but the model could not be brought up at
+     * RUNTIME — the first-run download/decompress, or the ONNX-runtime init,
+     * failed (offline, the model bucket is unreachable, a proxy blocks it). Kept
+     * DISTINCT from `IndexEmbedderUnavailable` (a load failure) and from the
+     * generic `IndexFailed` ("re-run --verbose") so the actual, common first-run
+     * failure carries an actionable cause instead of a shrug. */
+    IndexEmbedderDownloadFailed: "CRUXY_E_INDEX_EMBEDDER_DOWNLOAD_FAILED",
     IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE",
     IndexFailed: "CRUXY_E_INDEX_FAILED",
     // skill (exit 9)
@@ -275,6 +286,7 @@ const EXIT_CODES = {
     [ErrorCode.PathEscape]: 7,
     [ErrorCode.CheckpointFailed]: 7,
     [ErrorCode.IndexEmbedderUnavailable]: 8,
+    [ErrorCode.IndexEmbedderDownloadFailed]: 8,
     [ErrorCode.IndexStoreUnavailable]: 8,
     [ErrorCode.IndexFailed]: 8,
     [ErrorCode.SkillInvalid]: 9,

package/dist/indexing/embedder.js

@@ -1,5 +1,5 @@
 import { promises as fs } from "node:fs";
-import { indexEmbedderUnavailable } from "../errors/index.js";
+import { indexEmbedderDownloadFailed, indexEmbedderUnavailable, } from "../errors/index.js";
 import { l2normalize } from "./util.js";
 /**
  * Output dimensionality of bge-small-en-v1.5, and the default size of the
@@ -84,18 +84,30 @@ export class FastEmbedEmbedder {
     getModel() {
         if (!this.model) {
             this.model = (async () => {
-                const mod = await import("fastembed");
-                // fastembed's init does a non-recursive mkdir of the cache dir, so it
-                // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
-                if (this.opts.cacheDir) {
-                    await fs.mkdir(this.opts.cacheDir, { recursive: true });
+                try {
+                    const mod = await import("fastembed");
+                    // fastembed's init does a non-recursive mkdir of the cache dir, so it
+                    // fails if an ancestor (e.g. ~/.cruxy) doesn't exist yet. Create it first.
+                    if (this.opts.cacheDir) {
+                        await fs.mkdir(this.opts.cacheDir, { recursive: true });
+                    }
+                    return (await mod.FlagEmbedding.init({
+                        model: mod.EmbeddingModel.BGESmallENV15,
+                        maxLength: this.opts.maxLength ?? 512,
+                        cacheDir: this.opts.cacheDir,
+                        showDownloadProgress: this.opts.showDownloadProgress ?? false,
+                    }));
+                }
+                catch (err) {
+                    // The heavy path: first-run model download/decompress or ONNX-runtime
+                    // init failed (offline, unreachable model bucket, proxy). Surface a
+                    // typed, actionable error instead of letting it collapse into the
+                    // generic CRUXY_E_INDEX_FAILED ("re-run --verbose"). Still fail-loud —
+                    // this never degrades to the lexical backend. (Module-*load* failure is
+                    // caught earlier and eagerly in `createEmbedder`, so what reaches here is
+                    // a runtime bring-up failure, not a missing install.)
+                    throw indexEmbedderDownloadFailed(err);
                 }
-                return (await mod.FlagEmbedding.init({
-                    model: mod.EmbeddingModel.BGESmallENV15,
-                    maxLength: this.opts.maxLength ?? 512,
-                    cacheDir: this.opts.cacheDir,
-                    showDownloadProgress: this.opts.showDownloadProgress ?? false,
-                }));
             })();
         }
         return this.model;

package/dist/tools/search-codebase.js

@@ -1,8 +1,38 @@
 import { z } from "zod";
+import { CruxyError, ErrorCode } from "../errors/index.js";
 import { getIndexService, mergeRankedHits } from "../indexing/index.js";
 import { contextWorkspace, labelName, resolveReadRoots } from "./file/paths.js";
 /** Hard cap on `k`, mirroring the retriever. */
 const MAX_K = 50;
+/**
+ * The embedder is unavailable — it failed to load, or the model failed to
+ * download/init. Fail-loud is preserved (the embedder never degrades to a
+ * lexical backend), so semantic search genuinely cannot run right now. This
+ * ROUTES THE MODEL to a working alternative: it is a hint in the error text, NOT
+ * an embedder fallback — `grep_files` is a different tool with different
+ * semantics (exact strings / symbols), and choosing it is the model's call.
+ */
+const GREP_ROUTE_HINT = "semantic search is unavailable right now — use grep_files to find code by exact string or symbol name instead";
+/** True when `err` is a semantic-search-blocking embedder unavailability. */
+function isEmbedderUnavailable(err) {
+    return (err instanceof CruxyError &&
+        (err.code === ErrorCode.IndexEmbedderUnavailable ||
+            err.code === ErrorCode.IndexEmbedderDownloadFailed));
+}
+/**
+ * The model-facing message for a failed search. For an embedder unavailability
+ * it appends the grep_files routing hint (and the actionable cause, if any) so
+ * the model has both the reason and a productive next move; every other failure
+ * passes through unchanged.
+ */
+function searchErrorMessage(err) {
+    const base = err.message;
+    if (isEmbedderUnavailable(err)) {
+        const cause = err instanceof CruxyError && err.cause ? ` (${err.cause})` : "";
+        return `${base}${cause}. ${GREP_ROUTE_HINT}.`;
+    }
+    return base;
+}
 const parameters = z.object({
     query: z
         .string()
@@ -76,7 +106,9 @@ export const searchCodebaseTool = {
                 return { ok: true, output: formatHits(hits, false) };
             }
             catch (err) {
-                return { ok: false, error: err.message };
+                // Embedder-unavailable errors carry a grep_files routing hint (a hint,
+                // NOT a fallback — the embedder still failed loud).
+                return { ok: false, error: searchErrorMessage(err) };
             }
         }
         // Multi-root fan: one independent search per root, per-root failures isolated
@@ -85,6 +117,9 @@ export const searchCodebaseTool = {
         const rawByRoot = new Map();
         const searched = [];
         const failed = [];
+        // Set if ANY root's failure was an embedder unavailability, so the fanned
+        // footer routes the model to grep_files ONCE rather than per failing root.
+        let embedderUnavailable = false;
         for (const root of roots) {
             try {
                 const service = await getIndexService(root.absPath, ctx.config, ctx.logger);
@@ -101,7 +136,11 @@ export const searchCodebaseTool = {
                 searched.push(root.name);
             }
             catch (err) {
+                // The root is NAMED (never conflated with "no matches"); the grep_files
+                // hint is added once, in the footer, not repeated per root.
                 failed.push({ name: root.name, reason: err.message });
+                if (isEmbedderUnavailable(err))
+                    embedderUnavailable = true;
             }
         }
         // Global rank + budget + cap AFTER the merge (⚖︎JC-I): a strong hit in one root
@@ -113,7 +152,12 @@ export const searchCodebaseTool = {
         });
         return {
             ok: true,
-            output: renderFanned(merged, { searched, failed, rawByRoot }),
+            output: renderFanned(merged, {
+                searched,
+                failed,
+                rawByRoot,
+                embedderUnavailable,
+            }),
         };
     },
 };
@@ -156,6 +200,11 @@ function renderFanned(merged, ctx) {
     for (const f of ctx.failed) {
         notes.push(`${f.name}: index unavailable — ${f.reason}`);
     }
+    // One routing hint for the whole fan when the embedder is the blocker (a hint,
+    // NOT a fallback — the embedder still failed loud on every affected root).
+    if (ctx.embedderUnavailable) {
+        notes.push(GREP_ROUTE_HINT);
+    }
     const scope = ctx.searched.length
         ? `searched ${ctx.searched.length} root${ctx.searched.length === 1 ? "" : "s"}: ${ctx.searched.join(", ")}`
         : "no roots could be searched";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {