ex-brain 0.1.0 → 0.1.1

package/src/settings.ts

@@ -0,0 +1,214 @@
+import { homedir } from "node:os";
+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_PATH = join(SETTINGS_DIR, "settings.json");
+export const DEFAULT_DB_PATH = resolve(SETTINGS_DIR, "data", "ebrain.db");
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const RemoteDbSchema = z.object({
+  host: z.string().optional(),
+  port: z.number().optional(),
+  user: z.string().optional(),
+  password: z.string().optional(),
+  database: z.string().optional(),
+  tenant: z.string().optional(),
+});
+
+const EmbedSchema = z.object({
+  provider: z.enum(["hash", "openai_compatible"]).optional(),
+  baseURL: z.string().optional(),
+  model: z.string().optional(),
+  dimensions: z.number().optional(),
+  apiKey: z.string().optional(),
+  apiKeyEnv: z.string().optional(),
+});
+
+const LLMSchema = z.object({
+  baseURL: z.string().optional(),
+  model: z.string().optional(),
+  apiKey: z.string().optional(),
+  apiKeyEnv: z.string().optional(),
+});
+
+const SettingsSchema = z.object({
+  db: z
+    .object({
+      path: z.string().optional(),
+      remote: RemoteDbSchema.optional(),
+    })
+    .optional(),
+  embed: EmbedSchema.optional(),
+  llm: LLMSchema.optional(),
+});
+
+// ---------------------------------------------------------------------------
+// Resolved types (all values present after defaults + env merge)
+// ---------------------------------------------------------------------------
+
+export interface ResolvedSettings {
+  dbPath: string;
+  remote: ResolvedRemoteDb | null;
+  embed: ResolvedEmbed;
+  llm: ResolvedLLM;
+}
+
+export interface ResolvedRemoteDb {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  tenant: string;
+}
+
+export interface ResolvedEmbed {
+  provider: "hash" | "openai_compatible";
+  baseURL: string;
+  model: string;
+  dimensions: number;
+  apiKey: string;
+  apiKeyEnv: string;
+}
+
+export interface ResolvedLLM {
+  baseURL: string;
+  model: string;
+  apiKey: string;
+  apiKeyEnv: string;
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_REMOTE = {
+  port: 3306,
+  user: "root",
+  password: "",
+  database: "ebrain",
+  tenant: "",
+};
+
+const DEFAULT_EMBED = {
+  provider: "hash" as const,
+  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+  model: "text-embedding-v4",
+  dimensions: 1024,
+  apiKey: "",
+  apiKeyEnv: "DASHSCOPE_API_KEY",
+};
+
+const DEFAULT_LLM = {
+  baseURL: "",
+  model: "qwen-plus",
+  apiKey: "",
+  apiKeyEnv: "DASHSCOPE_API_KEY",
+};
+
+// ---------------------------------------------------------------------------
+// Load & resolve
+// ---------------------------------------------------------------------------
+
+export async function loadSettings(): Promise<ResolvedSettings> {
+  const raw = await readSettingsFile();
+  const parsed = SettingsSchema.parse(raw ?? {});
+  return resolveSettings(parsed);
+}
+
+export async function readSettingsFile(): Promise<unknown | null> {
+  if (!(await fileExists(SETTINGS_PATH))) {
+    return null;
+  }
+  const text = await readTextFile(SETTINGS_PATH);
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    console.warn(
+      `[ebrain] Failed to parse ${SETTINGS_PATH}, using defaults.`,
+    );
+    return null;
+  }
+}
+
+export function resolveSettings(parsed: z.infer<typeof SettingsSchema>): ResolvedSettings {
+  const dbConf = parsed.db ?? {};
+  const remoteConf = dbConf.remote ?? {};
+  const embedConf = parsed.embed ?? {};
+
+  // Remote: settings → env → defaults
+  const host = remoteConf.host ?? process.env.EBRAIN_SEEKDB_HOST ?? "";
+  if (host) {
+    const remote: ResolvedRemoteDb = {
+      host: host.trim(),
+      port: numOr(remoteConf.port ?? process.env.EBRAIN_SEEKDB_PORT, DEFAULT_REMOTE.port),
+      user: nonEmpty(remoteConf.user ?? process.env.EBRAIN_SEEKDB_USER, DEFAULT_REMOTE.user),
+      password: nonEmpty(
+        remoteConf.password ?? process.env.EBRAIN_SEEKDB_PASSWORD,
+        DEFAULT_REMOTE.password,
+      ),
+      database: nonEmpty(
+        remoteConf.database ?? process.env.EBRAIN_SEEKDB_DATABASE,
+        DEFAULT_REMOTE.database,
+      ),
+      tenant: nonEmpty(remoteConf.tenant ?? process.env.EBRAIN_SEEKDB_TENANT, ""),
+    };
+    return { dbPath: dbConf.path ?? DEFAULT_DB_PATH, remote, embed: resolveEmbed(embedConf), llm: resolveLLM(parsed.llm ?? {}) };
+  }
+
+  // Local mode
+  const dbPath = dbConf.path
+    ? resolvePath(dbConf.path)
+    : DEFAULT_DB_PATH;
+  return { dbPath, remote: null, embed: resolveEmbed(embedConf), llm: resolveLLM(parsed.llm ?? {}) };
+}
+
+function resolveEmbed(conf: z.infer<typeof EmbedSchema>): ResolvedEmbed {
+  const provider = nonEmpty(
+    conf.provider ?? process.env.EBRAIN_EMBED_PROVIDER,
+    DEFAULT_EMBED.provider,
+  ).trim().toLowerCase() as "hash" | "openai_compatible";
+  const baseURL = nonEmpty(conf.baseURL ?? process.env.EBRAIN_EMBED_BASE_URL, DEFAULT_EMBED.baseURL);
+  const model = nonEmpty(conf.model ?? process.env.EBRAIN_EMBED_MODEL, DEFAULT_EMBED.model);
+  const dimensions = numOr(conf.dimensions ?? process.env.EBRAIN_EMBED_DIMENSIONS, DEFAULT_EMBED.dimensions);
+  const apiKey = nonEmpty(conf.apiKey ?? process.env.EBRAIN_EMBED_API_KEY, "");
+  const apiKeyEnv = nonEmpty(conf.apiKeyEnv ?? process.env.EBRAIN_EMBED_API_KEY_ENV, DEFAULT_EMBED.apiKeyEnv);
+  return { provider, baseURL, model, dimensions, apiKey, apiKeyEnv };
+}
+
+function resolveLLM(conf: z.infer<typeof LLMSchema>): ResolvedLLM {
+  const baseURL = nonEmpty(conf.baseURL, DEFAULT_LLM.baseURL);
+  const model = nonEmpty(conf.model, DEFAULT_LLM.model);
+  const apiKey = nonEmpty(conf.apiKey, DEFAULT_LLM.apiKey);
+  const apiKeyEnv = nonEmpty(conf.apiKeyEnv, DEFAULT_LLM.apiKeyEnv);
+  return { baseURL, model, apiKey, apiKeyEnv };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function nonEmpty(val: string | undefined, fallback: string): string {
+  return val?.trim() ?? fallback;
+}
+
+function numOr(val: number | string | undefined, fallback: number): number {
+  if (typeof val === "number") return val;
+  if (typeof val === "string") {
+    const n = Number(val.trim());
+    if (Number.isFinite(n)) return n;
+  }
+  return fallback;
+}
+
+function resolvePath(p: string): string {
+  if (p.startsWith("~")) {
+    return join(homedir(), p.slice(1));
+  }
+  return resolve(p);
+}

package/src/types/index.ts

@@ -0,0 +1,55 @@
+export type PageType =
+  | "person"
+  | "company"
+  | "deal"
+  | "yc"
+  | "civic"
+  | "project"
+  | "note"
+  | "other";
+
+export interface PageRecord {
+  slug: string;
+  type: PageType | string;
+  title: string;
+  compiledTruth: string;
+  timeline: string;
+  frontmatter: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TimelineEntry {
+  id?: number;
+  pageSlug: string;
+  date: string;
+  source: string;
+  summary: string;
+  detail: string;
+}
+
+export interface SearchHit {
+  slug: string;
+  title: string;
+  type: string;
+  score: number;
+  excerpt?: string;
+  updatedAt?: string;
+}
+
+export interface BrainStats {
+  pages: number;
+  links: number;
+  tags: number;
+  timelineEntries: number;
+  rawRows: number;
+}
+
+export interface PutPageInput {
+  slug: string;
+  type: string;
+  title: string;
+  compiledTruth: string;
+  timeline?: string;
+  frontmatter?: Record<string, unknown>;
+}

package/src/utils/progress.ts

@@ -0,0 +1,171 @@
+/**
+ * Progress indicator with spinner animation for long-running operations.
+ */
+
+export interface ProgressIndicator {
+  start(message: string): void;
+  update(message: string): void;
+  succeed(message?: string): void;
+  fail(message?: string): void;
+  stop(): void;
+}
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_INTERVAL = 80;
+
+/**
+ * Create a progress indicator with spinner animation.
+ * @param stream Output stream (default: process.stderr)
+ */
+export function createProgress(stream: NodeJS.WritableStream = process.stderr): ProgressIndicator {
+  let frameIndex = 0;
+  let interval: Timer | null = null;
+  let currentMessage = '';
+  let isRunning = false;
+
+  function clearLine() {
+    stream.write('\r\x1b[K');
+  }
+
+  function render() {
+    if (!isRunning) return;
+    const frame = SPINNER_FRAMES[frameIndex];
+    clearLine();
+    stream.write(`\x1b[36m${frame}\x1b[0m ${currentMessage}`);
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+  }
+
+  function start(message: string) {
+    if (isRunning) stop();
+    currentMessage = message;
+    isRunning = true;
+    frameIndex = 0;
+    render();
+    interval = setInterval(render, SPINNER_INTERVAL);
+  }
+
+  function update(message: string) {
+    currentMessage = message;
+    if (!isRunning) {
+      start(message);
+    }
+  }
+
+  function stop() {
+    if (interval) {
+      clearInterval(interval);
+      interval = null;
+    }
+    if (isRunning) {
+      clearLine();
+      isRunning = false;
+    }
+  }
+
+  function succeed(message?: string) {
+    stop();
+    const text = message || currentMessage;
+    stream.write(`\x1b[32m✓\x1b[0m ${text}\n`);
+  }
+
+  function fail(message?: string) {
+    stop();
+    const text = message || currentMessage;
+    stream.write(`\x1b[31m✗\x1b[0m ${text}\n`);
+  }
+
+  return { start, update, succeed, fail, stop };
+}
+
+/**
+ * Simple spinner for async operations.
+ * Usage: const done = spinner.start('Processing...'); await task(); done('Done');
+ */
+export function spinner(stream: NodeJS.WritableStream = process.stderr) {
+  const progress = createProgress(stream);
+  
+  return {
+    start(message: string) {
+      progress.start(message);
+      return (finalMessage?: string) => {
+        progress.succeed(finalMessage);
+      };
+    },
+    fail(message: string) {
+      progress.fail(message);
+    },
+  };
+}
+
+/**
+ * Progress bar for batch operations.
+ */
+export function progressBar(total: number, stream: NodeJS.WritableStream = process.stderr) {
+  let current = 0;
+  let lastPercent = -1;
+
+  function render(label: string) {
+    const percent = Math.floor((current / total) * 100);
+    if (percent === lastPercent) return;
+    lastPercent = percent;
+
+    const barWidth = 30;
+    const filled = Math.floor((current / total) * barWidth);
+    const empty = barWidth - filled;
+    const bar = '█'.repeat(filled) + '░'.repeat(empty);
+
+    stream.write(`\r\x1b[K${label} [${bar}] ${percent}% (${current}/${total})`);
+  }
+
+  return {
+    start(label: string) {
+      current = 0;
+      lastPercent = -1;
+      render(label);
+    },
+    increment(label: string) {
+      current++;
+      render(label);
+    },
+    done(label: string) {
+      current = total;
+      render(label);
+      stream.write('\n');
+    },
+  };
+}
+
+/**
+ * Format duration in human-readable form.
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const minutes = Math.floor(ms / 60000);
+  const seconds = Math.floor((ms % 60000) / 1000);
+  return `${minutes}m ${seconds}s`;
+}
+
+/**
+ * Measure and report operation duration.
+ */
+export async function withProgress<T>(
+  message: string,
+  fn: () => Promise<T>,
+  stream: NodeJS.WritableStream = process.stderr
+): Promise<T> {
+  const progress = createProgress(stream);
+  const start = Date.now();
+  
+  progress.start(message);
+  
+  try {
+    const result = await fn();
+    const duration = formatDuration(Date.now() - start);
+    progress.succeed(`${message} (${duration})`);
+    return result;
+  } catch (error) {
+    progress.fail(`${message} - failed`);
+    throw error;
+  }
+}