ex-brain 0.2.5 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ex-brain",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "CLI personal knowledge base powered by seekdb",
   "module": "src/cli.ts",
   "type": "module",

package/src/commands/index.ts

@@ -34,6 +34,7 @@ import {
   subItem,
   keyValue,
   header,
+  separator,
   createSpinner,
   formatCount,
   type ProgressSpinner,
@@ -1483,27 +1484,106 @@ Examples:
 
   program
     .command("init")
-    .description("initialize the ebrain database")
+    .description("initialize ebrain: create config, database, and show setup guide")
     .addHelpText(
       "after",
       `
 Examples:
   ebrain init
+  ebrain init --db ./my.db
 `,
     )
     .action(async () => {
-      await withRepo(program, async () => {
-        const settings = await loadSettings();
-        const dbPath = program.opts().db ?? settings.dbPath;
-        
-        success(`Database initialized`);
-        keyValue("Path", dbPath);
-        
-        print(program, {
-          ok: true,
-          dbPath,
-        });
+      const jsonOut = isJson(program);
+      const settings = await loadSettings();
+      const cliDb = program.opts().db;
+      const dbPath = cliDb ?? settings.dbPath;
+
+      if (!jsonOut) {
+        header("ebrain init");
+      }
+
+      // Step 1: Create settings.json if it doesn't exist
+      const { createDefaultSettings } = await import("../settings");
+      const settingsCreated = await createDefaultSettings();
+
+      if (!jsonOut) {
+        if (settingsCreated) {
+          success(`Created config: ${SETTINGS_PATH}`);
+        } else {
+          success(`Config already exists: ${SETTINGS_PATH}`);
+        }
+      }
+
+      // Step 2: Check or initialize database
+      const dbExists = await fileExists(dbPath);
+      let dbInitialized = false;
+
+      if (dbExists) {
+        // Database already exists, skip connection attempt to avoid
+        // noisy errors (e.g. embedding function key mismatch)
+        if (!jsonOut) {
+          success(`Database already exists: ${dbPath}`);
+        }
+        dbInitialized = true;
+      } else {
+        // Try to create it without collection — embedding config may not be ready
+        try {
+          const db = await BrainDb.connect(dbPath, settings, { skipCollection: true });
+          await db.close();
+          await new Promise((r) => setTimeout(r, 200));
+          dbInitialized = true;
+          if (!jsonOut) {
+            success(`Database initialized: ${dbPath}`);
+          }
+        } catch {
+          if (!jsonOut) {
+            warning(`Database will be auto-created on first use`);
+          }
+        }
+      }
+
+      // Step 3: Show setup guide
+      if (!jsonOut) {
+        console.log("");
+        separator();
+        info("Quick Start Guide");
+        console.log("");
+
+        subItem("1. Configure LLM (for AI queries):", 0);
+        subItem(`   Edit ${SETTINGS_PATH}`, 4);
+        subItem(`   Set llm.baseURL to your OpenAI-compatible API endpoint`, 4);
+        subItem(`   Set llm.apiKey or export DASHSCOPE_API_KEY`, 4);
+        console.log("");
+
+        subItem("2. Add your first page:", 0);
+        subItem("   echo '# Hello' | ebrain put hello --stdin", 4);
+        console.log("");
+
+        subItem("3. Import a directory of markdown files:", 0);
+        subItem("   ebrain import ./docs", 4);
+        console.log("");
+
+        subItem("4. Query with AI:", 0);
+        subItem('   ebrain query "What did we ship in Q4?" --llm', 4);
+        console.log("");
+
+        subItem("5. Visualize your knowledge graph:", 0);
+        subItem("   ebrain graph", 4);
+        console.log("");
+
+        separator();
+      }
+
+      print(program, {
+        ok: true,
+        settingsPath: SETTINGS_PATH,
+        settingsCreated,
+        dbPath,
+        dbInitialized,
       });
+
+      process.exit(0);
     });
 
   program

package/src/db/client.ts

@@ -107,7 +107,11 @@ export class BrainDb {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
-  static async connect(dbPath: string, settings?: ResolvedSettings): Promise<BrainDb> {
+  static async connect(
+    dbPath: string,
+    settings?: ResolvedSettings,
+    options?: { skipCollection?: boolean },
+  ): Promise<BrainDb> {
     try {
       const client = settings?.remote
         ? await BrainDb.openRemoteClient(settings.remote)
@@ -122,6 +126,15 @@ export class BrainDb {
         await client.execute(sql);
       }
 
+      // Skip collection creation for init (embedding config may not be ready)
+      if (options?.skipCollection) {
+        const db = new BrainDb(dbPath, client, null as unknown as Collection);
+        db._isConnected = true;
+        db._lastConnectedAt = new Date();
+        console.error("\x1b[32m[DB] Connected successfully\x1b[0m");
+        return db;
+      }
+
       const pagesCollection = await client.getOrCreateCollection({
         name: PAGES_COLLECTION,
         embeddingFunction: createBrainEmbeddingFunction(settings?.embed),

package/src/repositories/brain-repo.ts

@@ -347,8 +347,13 @@ export class BrainRepository {
         metadatas: [meta],
       });
     } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      // Dimension mismatch means the collection was created with a different
+      // embedding model. This is non-critical — pages still work, just no search.
+      if (msg.includes("Dimension mismatch")) {
+        return;
+      }
       const dbError = wrapDbError(error, "syncPageToSearch", { slug });
-      logDbError(dbError);
       // Don't throw - sync failure shouldn't break the main flow
       console.warn(`[BrainRepo] syncPageToSearch failed for ${slug}: ${dbError.message}`);
     }
@@ -384,8 +389,11 @@ export class BrainRepository {
         metadatas: metas,
       });
     } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (msg.includes("Dimension mismatch")) {
+        return;
+      }
       const dbError = wrapDbError(error, "syncPagesToSearch", { count: slugs.length });
-      logDbError(dbError);
       // Don't throw - sync failure shouldn't break the main flow
       console.warn(`[BrainRepo] syncPagesToSearch failed: ${dbError.message}`);
     }

package/src/settings.ts

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { z } from "zod";
 import { fileExists, readTextFile } from "./markdown/io";
 
-const SETTINGS_DIR = join(homedir(), ".ebrain");
+export const SETTINGS_DIR = join(homedir(), ".ebrain");
 export const SETTINGS_PATH = join(SETTINGS_DIR, "settings.json");
 export const DEFAULT_DB_PATH = resolve(SETTINGS_DIR, "data", "ebrain.db");
 
@@ -150,6 +150,54 @@ export async function readSettingsFile(): Promise<unknown | null> {
   }
 }
 
+/**
+ * Generate a minimal settings.json if it doesn't already exist.
+ * Returns true if a new file was created.
+ */
+export async function createDefaultSettings(): Promise<boolean> {
+  if (await fileExists(SETTINGS_PATH)) {
+    return false;
+  }
+
+  const { mkdirSync, writeFileSync } = await import("node:fs");
+  mkdirSync(SETTINGS_DIR, { recursive: true });
+
+  // All fields present but empty — user fills in their values
+  const defaults = {
+    db: {
+      path: "",
+      remote: {
+        host: "",
+        port: 0,
+        user: "",
+        password: "",
+        database: "",
+        tenant: "",
+      },
+    },
+    embed: {
+      provider: "hash",
+      baseURL: "",
+      model: "",
+      dimensions: 0,
+      apiKey: "",
+      apiKeyEnv: "",
+    },
+    llm: {
+      baseURL: "",
+      model: "",
+      apiKey: "",
+      apiKeyEnv: "",
+    },
+    extraction: {
+      confidenceThreshold: 0.7,
+    },
+  };
+
+  writeFileSync(SETTINGS_PATH, JSON.stringify(defaults, null, 2) + "\n", "utf-8");
+  return true;
+}
+
 export function resolveSettings(parsed: z.infer<typeof SettingsSchema>): ResolvedSettings {
   const dbConf = parsed.db ?? {};
   const remoteConf = dbConf.remote ?? {};
@@ -215,7 +263,8 @@ function resolveExtraction(conf: { confidenceThreshold?: number }): ResolvedExtr
 // ---------------------------------------------------------------------------
 
 function nonEmpty(val: string | undefined, fallback: string): string {
-  return val?.trim() ?? fallback;
+  const trimmed = val?.trim();
+  return trimmed || fallback;
 }
 
 function numOr(val: number | string | undefined, fallback: number): number {