@shykaruu/jarvis-brain 0.4.0

package/src/vault/settings.ts

@@ -0,0 +1,38 @@
+/**
+ * Key-value settings store backed by SQLite.
+ *
+ * Used for persistent configuration that can be edited from the dashboard
+ * (e.g., LLM provider/model preferences).
+ */
+
+import { getDb } from './schema.ts';
+
+export function getSetting(key: string): string | null {
+  const db = getDb();
+  const row = db.query('SELECT value FROM settings WHERE key = ?').get(key) as { value: string } | null;
+  return row?.value ?? null;
+}
+
+export function setSetting(key: string, value: string): void {
+  const db = getDb();
+  db.run(
+    `INSERT INTO settings (key, value, updated_at) VALUES (?, ?, unixepoch())
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+    [key, value],
+  );
+}
+
+export function deleteSetting(key: string): void {
+  const db = getDb();
+  db.run('DELETE FROM settings WHERE key = ?', [key]);
+}
+
+export function getSettingsByPrefix(prefix: string): Record<string, string> {
+  const db = getDb();
+  const rows = db.query('SELECT key, value FROM settings WHERE key LIKE ?').all(`${prefix}%`) as Array<{ key: string; value: string }>;
+  const result: Record<string, string> = {};
+  for (const row of rows) {
+    result[row.key] = row.value;
+  }
+  return result;
+}

package/src/vault/user-profile.test.ts

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { closeDb, initDatabase } from './schema.ts';
+import { clearUserProfile, getUserProfile, saveUserProfile } from './user-profile.ts';
+import { findEntities } from './entities.ts';
+import { findFacts } from './facts.ts';
+import { countAnsweredUserProfileQuestions, formatUserProfileForPrompt } from '../user/profile.ts';
+
+describe('Vault — User Profile', () => {
+  afterEach(() => {
+    closeDb();
+  });
+
+  test('save + load persists normalized answers', () => {
+    initDatabase(':memory:');
+
+    const saved = saveUserProfile({
+      preferred_name: '  Alex  ',
+      interests: 'AI, cars',
+      empty_field: '',
+    });
+
+    expect(saved.answers.preferred_name).toBe('Alex');
+    expect(saved.answers.interests).toBe('AI, cars');
+    expect(saved.completed_at).toBeNumber();
+
+    const loaded = getUserProfile();
+    expect(loaded?.answers.preferred_name).toBe('Alex');
+    expect(loaded?.answers.interests).toBe('AI, cars');
+  });
+
+  test('clear removes saved profile', () => {
+    initDatabase(':memory:');
+
+    saveUserProfile({ preferred_name: 'Alex' });
+    clearUserProfile();
+
+    expect(getUserProfile()).toBeNull();
+    expect(findEntities({ name: 'Alex' })).toHaveLength(0);
+    expect(findFacts({ predicate: 'preferred_name' })).toHaveLength(0);
+  });
+
+  test('save syncs profile answers into the vault knowledge base', () => {
+    initDatabase(':memory:');
+
+    saveUserProfile({
+      preferred_name: 'Alex',
+      interests: 'AI, cars',
+      location_timezone: 'Miami / America/New_York',
+    });
+
+    const entities = findEntities({ name: 'Alex' });
+    expect(entities).toHaveLength(1);
+    expect(entities[0]!.source).toBe('user_profile');
+
+    const facts = findFacts({ subject_id: entities[0]!.id });
+    const factMap = new Map(facts.map((fact) => [fact.predicate, fact.object]));
+    expect(factMap.get('preferred_name')).toBe('Alex');
+    expect(factMap.get('interests')).toBe('AI, cars');
+    expect(factMap.get('location_timezone')).toBe('Miami / America/New_York');
+    expect(factMap.get('name')).toBe('Alex');
+  });
+
+  test('save derives alias facts from free-form profile answers', () => {
+    initDatabase(':memory:');
+
+    saveUserProfile({
+      preferred_name: 'Sebastian',
+      important_people: 'im Sebastian but my common alias/username is Crayon.',
+    });
+
+    const entities = findEntities({ name: 'Sebastian' });
+    expect(entities).toHaveLength(1);
+
+    const facts = findFacts({ subject_id: entities[0]!.id });
+    const aliases = facts
+      .filter((fact) => fact.predicate === 'alias' || fact.predicate === 'username')
+      .map((fact) => fact.object);
+
+    expect(aliases).toContain('Crayon');
+  });
+
+  test('prompt formatter includes answered fields only', () => {
+    initDatabase(':memory:');
+
+    const profile = saveUserProfile({
+      preferred_name: 'Alex',
+      communication_preferences: 'Be direct and concise.',
+    });
+
+    expect(countAnsweredUserProfileQuestions(profile)).toBe(2);
+
+    const prompt = formatUserProfileForPrompt(profile);
+    expect(prompt).toContain('Preferred Name: |');
+    expect(prompt).toContain('    Alex');
+    expect(prompt).toContain('Communication Preferences: |');
+    expect(prompt).toContain('    Be direct and concise.');
+    expect(prompt).not.toContain('Pronouns');
+  });
+
+  test('prompt formatter indents multiline answers to keep them contained', () => {
+    initDatabase(':memory:');
+
+    const profile = saveUserProfile({
+      anything_else: 'Line one\n# not a heading\n- not a list item',
+    });
+
+    const prompt = formatUserProfileForPrompt(profile);
+    expect(prompt).toContain('Anything Else: |');
+    expect(prompt).toContain('    Line one');
+    expect(prompt).toContain('    # not a heading');
+    expect(prompt).toContain('    - not a list item');
+  });
+});

package/src/vault/user-profile.ts

@@ -0,0 +1,176 @@
+import { deleteSetting, getSetting, setSetting } from './settings.ts';
+import { createEntity, updateEntity } from './entities.ts';
+import { createFact } from './facts.ts';
+import { getDb } from './schema.ts';
+import {
+  USER_PROFILE_QUESTIONS,
+  USER_PROFILE_SETTING_KEY,
+  createEmptyUserProfile,
+  countAnsweredUserProfileQuestions,
+  normalizeUserProfileAnswers,
+  type UserProfileRecord,
+} from '../user/profile.ts';
+
+export const USER_PROFILE_VAULT_SOURCE = 'user_profile';
+const USER_PROFILE_FOLLOWUP_STATE_KEY = 'user.profile.followup.v1';
+
+export function getUserProfile(): UserProfileRecord | null {
+  const raw = getSetting(USER_PROFILE_SETTING_KEY);
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<UserProfileRecord>;
+    const base = createEmptyUserProfile();
+    return {
+      version: 1,
+      answers: normalizeUserProfileAnswers((parsed.answers ?? {}) as Record<string, unknown>),
+      created_at: typeof parsed.created_at === 'number' ? parsed.created_at : base.created_at,
+      updated_at: typeof parsed.updated_at === 'number' ? parsed.updated_at : base.updated_at,
+      completed_at: typeof parsed.completed_at === 'number' ? parsed.completed_at : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveUserProfile(input: Record<string, unknown>): UserProfileRecord {
+  const existing = getUserProfile();
+  const now = Date.now();
+  const answers = normalizeUserProfileAnswers(input);
+  const profile: UserProfileRecord = {
+    version: 1,
+    answers,
+    created_at: existing?.created_at ?? now,
+    updated_at: now,
+    completed_at: countAnsweredUserProfileQuestions({
+      version: 1,
+      answers,
+      created_at: existing?.created_at ?? now,
+      updated_at: now,
+      completed_at: null,
+    }) > 0 ? now : null,
+  };
+
+  setSetting(USER_PROFILE_SETTING_KEY, JSON.stringify(profile));
+  syncUserProfileKnowledge(profile);
+  return profile;
+}
+
+export function clearUserProfile(): void {
+  deleteSetting(USER_PROFILE_SETTING_KEY);
+  clearUserProfileKnowledge();
+  deleteSetting(USER_PROFILE_FOLLOWUP_STATE_KEY);
+}
+
+function syncUserProfileKnowledge(profile: UserProfileRecord): void {
+  if (countAnsweredUserProfileQuestions(profile) === 0) {
+    clearUserProfileKnowledge();
+    return;
+  }
+
+  const db = getDb();
+  const entityName = profile.answers.preferred_name?.trim() || 'User';
+  const entityProperties = {
+    is_current_user: true,
+    profile_version: profile.version,
+    profile_updated_at: profile.updated_at,
+  };
+
+  const entityRow = db.prepare(
+    'SELECT id FROM entities WHERE source = ? ORDER BY updated_at DESC LIMIT 1'
+  ).get(USER_PROFILE_VAULT_SOURCE) as { id: string } | null;
+
+  const entity = entityRow
+    ? updateEntity(entityRow.id, { name: entityName, properties: entityProperties })
+    : createEntity('person', entityName, entityProperties, USER_PROFILE_VAULT_SOURCE);
+
+  if (!entity) {
+    throw new Error('Failed to sync user profile entity to vault');
+  }
+
+  db.prepare('DELETE FROM facts WHERE subject_id = ? AND source = ?').run(entity.id, USER_PROFILE_VAULT_SOURCE);
+
+  for (const question of USER_PROFILE_QUESTIONS) {
+    const answer = profile.answers[question.id]?.trim();
+    if (!answer) continue;
+    createFact(entity.id, question.id, answer, {
+      confidence: 1,
+      source: USER_PROFILE_VAULT_SOURCE,
+    });
+  }
+
+  for (const fact of getDerivedUserProfileFacts(profile)) {
+    createFact(entity.id, fact.predicate, fact.object, {
+      confidence: 1,
+      source: USER_PROFILE_VAULT_SOURCE,
+    });
+  }
+}
+
+function clearUserProfileKnowledge(): void {
+  const db = getDb();
+  const rows = db.prepare('SELECT id FROM entities WHERE source = ?').all(USER_PROFILE_VAULT_SOURCE) as Array<{ id: string }>;
+  db.prepare('DELETE FROM facts WHERE source = ?').run(USER_PROFILE_VAULT_SOURCE);
+  for (const row of rows) {
+    db.prepare('DELETE FROM entities WHERE id = ?').run(row.id);
+  }
+}
+
+function getDerivedUserProfileFacts(profile: UserProfileRecord): Array<{ predicate: string; object: string }> {
+  const facts: Array<{ predicate: string; object: string }> = [];
+  const seen = new Set<string>();
+
+  const preferredName = profile.answers.preferred_name?.trim();
+  if (preferredName) {
+    pushFact(facts, seen, 'name', preferredName);
+  }
+
+  const aliasSources = [
+    profile.answers.important_people,
+    profile.answers.anything_else,
+    profile.answers.work_role,
+    profile.answers.communication_preferences,
+  ].filter((value): value is string => typeof value === 'string' && value.trim().length > 0);
+
+  for (const source of aliasSources) {
+    for (const alias of extractAliases(source)) {
+      pushFact(facts, seen, 'alias', alias);
+      pushFact(facts, seen, 'username', alias);
+    }
+  }
+
+  return facts;
+}
+
+function pushFact(
+  facts: Array<{ predicate: string; object: string }>,
+  seen: Set<string>,
+  predicate: string,
+  object: string,
+): void {
+  const value = object.trim();
+  if (!value) return;
+  const key = `${predicate}\u0000${value.toLowerCase()}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  facts.push({ predicate, object: value });
+}
+
+function extractAliases(text: string): string[] {
+  const aliases = new Set<string>();
+  const patterns = [
+    /\b(?:alias|username|user\s*name|handle)\s*(?:is|=|:)?\s*["']?([A-Za-z0-9._-]{2,32})["']?/gi,
+    /\bgo by\s+["']?([A-Za-z0-9._-]{2,32})["']?/gi,
+    /\bcalled\s+["']?([A-Za-z0-9._-]{2,32})["']?/gi,
+  ];
+
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(text)) !== null) {
+      const alias = match[1]?.trim().replace(/[.,!?;:]+$/g, '');
+      if (alias) aliases.add(alias);
+    }
+  }
+
+  return [...aliases];
+}

package/src/vault/vectors.ts

@@ -0,0 +1,92 @@
+import { getDb, generateId } from './schema.ts';
+
+export type VectorRecord = {
+  id: string;
+  ref_type: string;
+  ref_id: string;
+  embedding: Float32Array;
+  model: string;
+  created_at: number;
+};
+
+type VectorRow = {
+  id: string;
+  ref_type: string;
+  ref_id: string;
+  embedding: ArrayBuffer;
+  model: string;
+  created_at: number;
+};
+
+/**
+ * Parse vector row from database, converting BLOB to Float32Array
+ */
+function parseVector(row: VectorRow): VectorRecord {
+  return {
+    ...row,
+    embedding: new Float32Array(row.embedding),
+  };
+}
+
+/**
+ * Store a vector embedding for a reference entity or fact
+ */
+export function storeVector(
+  ref_type: string,
+  ref_id: string,
+  embedding: Float32Array,
+  model: string
+): VectorRecord {
+  const db = getDb();
+  const id = generateId();
+  const now = Date.now();
+
+  // Convert Float32Array to Buffer for SQLite BLOB storage
+  const buffer = Buffer.from(embedding.buffer);
+
+  const stmt = db.prepare(
+    'INSERT INTO vectors (id, ref_type, ref_id, embedding, model, created_at) VALUES (?, ?, ?, ?, ?, ?)'
+  );
+
+  stmt.run(id, ref_type, ref_id, buffer, model, now);
+
+  return {
+    id,
+    ref_type,
+    ref_id,
+    embedding,
+    model,
+    created_at: now,
+  };
+}
+
+/**
+ * Find similar vectors using cosine similarity
+ *
+ * TODO: This is a stub implementation. For production use, integrate sqlite-vec extension
+ * which provides optimized vector similarity search with HNSW indexing.
+ *
+ * See: https://github.com/asg017/sqlite-vec
+ *
+ * Example with sqlite-vec:
+ * SELECT ref_type, ref_id, vec_distance_cosine(embedding, ?) as similarity
+ * FROM vectors
+ * ORDER BY similarity DESC
+ * LIMIT ?
+ */
+export function findSimilar(
+  embedding: Float32Array,
+  limit: number = 10
+): Array<{ ref_type: string; ref_id: string; similarity: number }> {
+  // TODO: Implement vector similarity search with sqlite-vec extension
+  return [];
+}
+
+/**
+ * Delete all vectors for a given reference
+ */
+export function deleteVectors(ref_type: string, ref_id: string): void {
+  const db = getDb();
+  const stmt = db.prepare('DELETE FROM vectors WHERE ref_type = ? AND ref_id = ?');
+  stmt.run(ref_type, ref_id);
+}

package/src/vault/webapp-template-seeds.ts

@@ -0,0 +1,116 @@
+/**
+ * Webapp Template Seeds — Load templates from YAML files
+ *
+ * Scans two directories for .yaml/.yml files:
+ *   1. Built-in: webapp-templates/ in the package root (shipped with codebase)
+ *   2. User overrides: ~/.jarvis/webapp-templates/ (user-created or customized)
+ *
+ * User files override built-in files when they share the same app_name.
+ * Called once at startup — uses upsert so templates update without data loss.
+ */
+
+import { join } from 'node:path';
+import { readdirSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { parse as parseYAML } from 'yaml';
+import { upsertWebappTemplate } from './webapp-templates.ts';
+
+export type TemplateSeed = {
+  app_name: string;
+  domains: string[];
+  keywords?: string[];
+  description: string;
+  instructions: string;
+  version?: number;
+};
+
+/**
+ * Load all .yaml/.yml files from a directory into TemplateSeed objects.
+ * Returns a Map keyed by app_name (lowercase) for easy merging.
+ */
+function loadTemplatesFromDir(dir: string): Map<string, TemplateSeed> {
+  const templates = new Map<string, TemplateSeed>();
+
+  if (!existsSync(dir)) return templates;
+
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  } catch {
+    return templates;
+  }
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(dir, file), 'utf-8');
+      const parsed = parseYAML(content) as Record<string, unknown>;
+
+      if (!parsed.app_name || !parsed.domains || !parsed.instructions) {
+        console.warn(`[WebappTemplates] Skipping ${file}: missing required fields (app_name, domains, instructions)`);
+        continue;
+      }
+
+      const seed: TemplateSeed = {
+        app_name: parsed.app_name as string,
+        domains: parsed.domains as string[],
+        keywords: (parsed.keywords as string[]) || [],
+        description: (parsed.description as string) || '',
+        instructions: (parsed.instructions as string).trim(),
+        version: parsed.version as number | undefined,
+      };
+
+      templates.set(seed.app_name.toLowerCase(), seed);
+    } catch (err) {
+      console.warn(`[WebappTemplates] Failed to parse ${file}:`, err instanceof Error ? err.message : err);
+    }
+  }
+
+  return templates;
+}
+
+/**
+ * Seed webapp templates from YAML files into the database.
+ *
+ * Load order:
+ *   1. Built-in templates from webapp-templates/ (package root)
+ *   2. User overrides from ~/.jarvis/webapp-templates/
+ *   User files override built-in files with the same app_name.
+ *
+ * Safe to call multiple times — uses upsert.
+ */
+export function seedWebappTemplates(): void {
+  // Resolve built-in directory relative to this source file (works for npm + git)
+  const pkgRoot = join(import.meta.dir, '../..');
+  const builtinDir = join(pkgRoot, 'webapp-templates');
+
+  // User override directory
+  const userDir = join(homedir(), '.jarvis', 'webapp-templates');
+
+  // Ensure user directory exists
+  mkdirSync(userDir, { recursive: true });
+
+  // 1. Load built-in templates
+  const templates = loadTemplatesFromDir(builtinDir);
+  const builtinCount = templates.size;
+
+  // 2. Layer user overrides (same app_name replaces built-in)
+  const userTemplates = loadTemplatesFromDir(userDir);
+  for (const [key, seed] of userTemplates) {
+    templates.set(key, seed);
+  }
+
+  // 3. Upsert all into database
+  let count = 0;
+  for (const seed of templates.values()) {
+    try {
+      upsertWebappTemplate(seed);
+      count++;
+    } catch (err) {
+      console.error(`[WebappTemplates] Failed to seed ${seed.app_name}:`, err);
+    }
+  }
+
+  const userCount = userTemplates.size;
+  const overrideNote = userCount > 0 ? ` (${userCount} user override${userCount > 1 ? 's' : ''})` : '';
+  console.log(`[WebappTemplates] Seeded ${count} webapp templates${overrideNote}`);
+}