lore-memory 0.1.0

package/src/commands/log.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const { readIndex, writeIndex, addEntryToIndex } = require('../lib/index');
+const { requireInit } = require('../lib/guard');
+const { writeEntry, generateId } = require('../lib/entries');
+const { getRecentFiles } = require('../lib/git');
+
+async function log(options) {
+  requireInit();
+  try {
+    const index = readIndex();
+
+    let type, title, context, alternatives, tradeoffs, tags, files;
+
+    // Inline mode: all three required fields provided as flags
+    if (options.type && options.title && options.context) {
+      type = options.type;
+      title = options.title;
+      context = options.context;
+      alternatives = options.alternatives ? [options.alternatives] : [];
+      tradeoffs = options.tradeoffs || '';
+      tags = options.tags ? options.tags.split(',').map(t => t.trim()).filter(Boolean) : [];
+      files = options.files ? options.files.split(',').map(f => f.trim()).filter(Boolean) : [];
+    } else {
+      // Interactive mode
+      const recentFiles = getRecentFiles();
+
+      const prompts = [
+        {
+          type: 'list',
+          name: 'type',
+          message: 'Entry type:',
+          choices: ['decision', 'invariant', 'graveyard', 'gotcha'],
+          default: options.type || 'decision',
+        },
+        {
+          type: 'input',
+          name: 'title',
+          message: 'Title:',
+          default: options.title || '',
+          validate: v => v.trim().length > 0 || 'Title is required',
+        },
+        {
+          type: 'input',
+          name: 'context',
+          message: 'Context (why?):',
+          default: options.context || '',
+          validate: v => v.trim().length > 0 || 'Context is required',
+        },
+        {
+          type: 'input',
+          name: 'alternatives',
+          message: 'Alternatives considered (optional, press Enter to skip):',
+        },
+        {
+          type: 'input',
+          name: 'tradeoffs',
+          message: 'Tradeoffs (optional, press Enter to skip):',
+        },
+        {
+          type: 'input',
+          name: 'tags',
+          message: 'Tags (comma-separated, optional):',
+        },
+      ];
+
+      if (recentFiles.length > 0) {
+        prompts.push({
+          type: 'checkbox',
+          name: 'files',
+          message: 'Link to files (recent git changes — space to select):',
+          choices: recentFiles,
+        });
+      }
+
+      prompts.push({
+        type: 'input',
+        name: 'extraFiles',
+        message: 'Additional file paths (comma-separated, optional):',
+      });
+
+      const answers = await inquirer.prompt(prompts);
+
+      type = answers.type;
+      title = answers.title;
+      context = answers.context;
+      alternatives = answers.alternatives ? [answers.alternatives] : [];
+      tradeoffs = answers.tradeoffs || '';
+      tags = answers.tags ? answers.tags.split(',').map(t => t.trim()).filter(Boolean) : [];
+      files = answers.files ? [...answers.files] : [];
+
+      if (answers.extraFiles) {
+        const extra = answers.extraFiles.split(',').map(f => f.trim()).filter(Boolean);
+        files = [...files, ...extra];
+      }
+    }
+
+    const validTypes = ['decision', 'invariant', 'graveyard', 'gotcha'];
+    if (!validTypes.includes(type)) {
+      console.error(chalk.red(`Invalid type "${type}". Must be one of: ${validTypes.join(', ')}`));
+      process.exit(1);
+    }
+
+    const id = generateId(type, title);
+    const entry = {
+      id,
+      type,
+      title,
+      date: new Date().toISOString().split('T')[0],
+      files,
+      context,
+      alternatives: alternatives.filter(Boolean),
+      tradeoffs,
+      tags,
+    };
+
+    const entryPath = writeEntry(entry);
+    addEntryToIndex(index, entry);
+    writeIndex(index);
+
+    console.log(chalk.green(`✓ Saved to ${entryPath}`));
+
+    // Auto-embed if Ollama is available and autoEmbed is enabled
+    try {
+      const { readConfig } = require('../lib/config');
+      const config = readConfig();
+      if (config.embed && config.embed.autoEmbed) {
+        const { generateEmbedding, storeEmbedding } = require('../lib/embeddings');
+        const text = [title, context, ...alternatives.filter(Boolean), tradeoffs, ...tags].join(' ');
+        const vector = await generateEmbedding(text);
+        storeEmbedding(id, vector);
+        console.log(chalk.dim('  (embedding stored)'));
+      }
+    } catch (e) {
+      // Ollama not running — skip silently
+    }
+  } catch (e) {
+    if (e.message && e.message.includes('force closed')) {
+      console.log(chalk.yellow('\nAborted.'));
+      process.exit(0);
+    }
+    console.error(chalk.red(`Failed to log entry: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = log;

package/src/commands/mine.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs-extra');
+const { mineFile, mineDirectory } = require('../watcher/comments');
+const { requireInit } = require('../lib/guard');
+
+function mine(targetPath) {
+  requireInit();
+  const projectRoot = process.cwd();
+  const target = targetPath || '.';
+
+  try {
+    const abs = path.resolve(target);
+    const stat = fs.statSync(abs);
+    let count = 0;
+
+    if (stat.isDirectory()) {
+      console.log(chalk.cyan(`📖 Mining comments in ${target} ...`));
+      count = mineDirectory(abs, projectRoot);
+    } else {
+      console.log(chalk.cyan(`📖 Mining comments in ${target} ...`));
+      count = mineFile(abs, projectRoot).length;
+    }
+
+    if (count === 0) {
+      console.log(chalk.green('✓ No significant comments found'));
+    } else {
+      console.log(chalk.green(`📖 Found ${count} draft entr${count === 1 ? 'y' : 'ies'} — review with: lore drafts`));
+    }
+  } catch (e) {
+    console.error(chalk.red(`Failed to mine: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = mine;

package/src/commands/onboard.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { checkStaleness } = require('../lib/stale');
+const { readConfig } = require('../lib/config');
+const { getDaysSinceLastSession, updateLastSession } = require('../lib/sessions');
+const { requireInit } = require('../lib/guard');
+
+function onboard(options) {
+  requireInit();
+  try {
+    const config = readConfig();
+    const index = readIndex();
+    const minDays = parseInt(options.days, 10) || 0;
+
+    const daysSince = getDaysSinceLastSession();
+
+    // If --days is set, only show onboarding if away long enough
+    if (minDays > 0 && (daysSince === null || daysSince < minDays)) {
+      console.log(chalk.cyan(`📖 Skipping onboarding (last session ${daysSince !== null ? daysSince + ' day(s) ago' : 'recently'})`));
+      return;
+    }
+
+    // Update session tracking
+    updateLastSession();
+
+    const projectName = config.project || 'this project';
+    const byType = { decision: [], invariant: [], gotcha: [], graveyard: [] };
+    const staleItems = [];
+
+    for (const entryPath of Object.values(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+      if (byType[entry.type]) byType[entry.type].push(entry);
+      const staleFiles = checkStaleness(entry);
+      if (staleFiles.length > 0) staleItems.push({ entry, staleFiles });
+    }
+
+    const total = Object.values(byType).reduce((sum, arr) => sum + arr.length, 0);
+
+    if (daysSince !== null && daysSince >= 3) {
+      console.log(chalk.cyan(`\n📖 Welcome back to ${projectName}!`));
+      console.log(chalk.dim(`   You've been away for ${daysSince} day${daysSince === 1 ? '' : 's'}\n`));
+    } else {
+      console.log(chalk.cyan(`\n📖 Lore — ${projectName}\n`));
+    }
+
+    if (total === 0) {
+      console.log(chalk.yellow('  No lore entries yet. Run: lore log'));
+      return;
+    }
+
+    // Decisions
+    if (byType.decision.length > 0) {
+      console.log(chalk.bold(`Architectural Decisions (${byType.decision.length}):`));
+      for (const e of byType.decision.slice(0, 5)) {
+        console.log(chalk.white(`  • ${e.title}`));
+        if (e.context) {
+          const summary = e.context.split('\n')[0].slice(0, 80);
+          console.log(chalk.dim(`    ${summary}${e.context.length > 80 ? '…' : ''}`));
+        }
+      }
+      if (byType.decision.length > 5) {
+        console.log(chalk.dim(`    …and ${byType.decision.length - 5} more`));
+      }
+      console.log();
+    }
+
+    // Invariants
+    if (byType.invariant.length > 0) {
+      console.log(chalk.bold.red(`Invariants — Never Break These (${byType.invariant.length}):`));
+      for (const e of byType.invariant) {
+        console.log(chalk.white(`  • ${e.title}`));
+      }
+      console.log();
+    }
+
+    // Gotchas
+    if (byType.gotcha.length > 0) {
+      console.log(chalk.bold.yellow(`Gotchas (${byType.gotcha.length}):`));
+      for (const e of byType.gotcha.slice(0, 3)) {
+        console.log(chalk.white(`  • ${e.title}`));
+      }
+      if (byType.gotcha.length > 3) {
+        console.log(chalk.dim(`    …and ${byType.gotcha.length - 3} more`));
+      }
+      console.log();
+    }
+
+    // Stale warnings
+    if (staleItems.length > 0) {
+      console.log(chalk.bold.yellow(`⚠ Stale Entries (${staleItems.length}):`));
+      for (const { entry, staleFiles } of staleItems.slice(0, 5)) {
+        const days = staleFiles[0].daysAgo;
+        const daysText = days === 0 ? 'today' : `${days}d ago`;
+        console.log(chalk.yellow(`  • ${entry.title} — ${staleFiles[0].filepath} changed ${daysText}`));
+      }
+      console.log(chalk.cyan('  Run: lore stale  for full details'));
+      console.log();
+    }
+
+    console.log(chalk.dim(`Total: ${total} entries | lore search <query> | lore why <file>`));
+    console.log();
+  } catch (e) {
+    console.error(chalk.red(`Failed to run onboard: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = onboard;

package/src/commands/score.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const chalk = require('chalk');
+const { computeScore, saveScore, loadHistory } = require('../lib/scorer');
+const { requireInit } = require('../lib/guard');
+
+function label(score) {
+  if (score >= 90) return 'Excellent';
+  if (score >= 75) return 'Good';
+  if (score >= 60) return 'Fair';
+  if (score >= 40) return 'Needs Work';
+  return 'Low';
+}
+
+function bar(value, width = 20) {
+  const filled = Math.round((value / 100) * width);
+  return '█'.repeat(Math.max(0, filled)) + '░'.repeat(Math.max(0, width - filled));
+}
+
+function trend(history) {
+  if (history.length < 2) return '';
+  const last = history[history.length - 1].score;
+  const prev = history[history.length - 2].score;
+  if (last > prev) return ' (improving)';
+  if (last < prev) return ' (declining)';
+  return ' (stable)';
+}
+
+function score() {
+  requireInit();
+  try {
+    const result = computeScore();
+    const history = saveScore(result);
+
+    const scoreLabel = label(result.score);
+    console.log(chalk.cyan(`\n📖 Lore Score: ${chalk.bold(result.score)}/100  (${scoreLabel})`));
+    console.log(chalk.dim('────────────────────────────────'));
+    console.log();
+
+    // Coverage
+    const cColor = result.coverage >= 70 ? chalk.green : result.coverage >= 40 ? chalk.yellow : chalk.red;
+    console.log(cColor(`Coverage     ${result.coverage}/100`));
+    console.log(chalk.dim(`  ${bar(result.coverage)}  ${result.coveredModules}/${result.activeModules} active modules documented`));
+    if (result.topUnlogged.length > 0) {
+      console.log(chalk.yellow('  Highest risk unlogged modules:'));
+      for (const { module: mod, commits } of result.topUnlogged) {
+        console.log(chalk.yellow(`    ${mod}  — ${commits} commits`));
+      }
+    }
+    console.log();
+
+    // Freshness
+    const fColor = result.freshness >= 70 ? chalk.green : result.freshness >= 40 ? chalk.yellow : chalk.red;
+    console.log(fColor(`Freshness    ${result.freshness}/100`));
+    console.log(chalk.dim(`  ${bar(result.freshness)}`));
+    console.log();
+
+    // Depth
+    const dColor = result.depth >= 70 ? chalk.green : result.depth >= 40 ? chalk.yellow : chalk.red;
+    console.log(dColor(`Depth        ${result.depth}/100`));
+    console.log(chalk.dim(`  ${bar(result.depth)}`));
+    console.log();
+
+    console.log(chalk.dim('────────────────────────────────'));
+
+    // History
+    if (history.length > 1) {
+      const recent = history.slice(-3).map(h => h.score).join(' → ');
+      console.log(chalk.dim(`Score history: ${recent}${trend(history)}`));
+    }
+
+    // Tip
+    if (result.topUnlogged.length > 0) {
+      console.log(chalk.cyan(`Tip: Log memory for ${result.topUnlogged[0].module} — highest risk unlogged module`));
+    } else if (result.freshness < 60) {
+      console.log(chalk.cyan('Tip: Review stale entries — run: lore stale'));
+    } else if (result.depth < 60) {
+      console.log(chalk.cyan('Tip: Add invariants and gotchas — run: lore log --type invariant'));
+    }
+
+    console.log();
+  } catch (e) {
+    console.error(chalk.red(`Failed to compute score: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = score;

package/src/commands/search.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { printEntry } = require('../lib/format');
+const { requireInit } = require('../lib/guard');
+
+function search(query) {
+  requireInit();
+  try {
+    const index = readIndex();
+    const q = query.toLowerCase();
+    const matches = [];
+
+    for (const entryPath of Object.values(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+
+      const searchable = [
+        entry.title,
+        entry.context,
+        ...(entry.alternatives || []),
+        entry.tradeoffs || '',
+        ...(entry.tags || []),
+      ].join(' ').toLowerCase();
+
+      if (searchable.includes(q)) {
+        matches.push(entry);
+      }
+    }
+
+    if (matches.length === 0) {
+      console.log(chalk.cyan(`📖 No entries found for "${query}"`));
+      return;
+    }
+
+    console.log(chalk.cyan(`\n─── Search results for "${query}" ───\n`));
+    for (const entry of matches) {
+      printEntry(entry);
+    }
+    console.log(chalk.cyan('─── End results ───\n'));
+  } catch (e) {
+    console.error(chalk.red(`Failed to search: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = search;

package/src/commands/serve.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const chalk = require('chalk');
+const { requireInit } = require('../lib/guard');
+
+async function serve(options) {
+  requireInit();
+  try {
+    const { startServer } = require('../mcp/server');
+    if (!options.quiet) {
+      process.stderr.write(chalk.green('📖 Lore MCP server starting on stdio\n'));
+      process.stderr.write(chalk.cyan('   Add to Claude Code settings: { "command": "lore serve", "args": [] }\n'));
+    }
+    await startServer();
+  } catch (e) {
+    process.stderr.write(chalk.red(`Failed to start server: ${e.message}\n`));
+    process.exit(1);
+  }
+}
+
+module.exports = serve;

package/src/commands/stale.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { checkStaleness } = require('../lib/stale');
+const { requireInit } = require('../lib/guard');
+
+function stale() {
+  requireInit();
+  try {
+    const index = readIndex();
+    let found = false;
+
+    for (const [id, entryPath] of Object.entries(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+
+      const staleFiles = checkStaleness(entry);
+      if (staleFiles.length > 0) {
+        found = true;
+        console.log(chalk.yellow(`\n⚠ ${entry.id}`));
+        console.log(`  Title: ${entry.title}`);
+        for (const s of staleFiles) {
+          const daysText = s.daysAgo === 0 ? 'today' : `${s.daysAgo} day${s.daysAgo === 1 ? '' : 's'} ago`;
+          console.log(chalk.yellow(`  File changed: ${s.filepath} (${daysText})`));
+        }
+        console.log(chalk.cyan(`  Suggest: lore edit ${entry.id}`));
+      }
+    }
+
+    if (!found) {
+      console.log(chalk.green('✓ No stale entries found'));
+    }
+  } catch (e) {
+    console.error(chalk.red(`Failed to run stale: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = stale;

package/src/commands/status.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { readEntry } = require('../lib/entries');
+const { checkStaleness } = require('../lib/stale');
+const { getDraftCount } = require('../lib/drafts');
+const { requireInit } = require('../lib/guard');
+
+function status() {
+  requireInit();
+  try {
+    const index = readIndex();
+    const counts = { decision: 0, invariant: 0, graveyard: 0, gotcha: 0 };
+    const staleItems = [];
+
+    for (const entryPath of Object.values(index.entries)) {
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+
+      if (counts[entry.type] !== undefined) {
+        counts[entry.type]++;
+      }
+
+      for (const stale of checkStaleness(entry)) {
+        staleItems.push({ entry, ...stale });
+      }
+    }
+
+    const draftCount = getDraftCount();
+
+    console.log(chalk.cyan('\n📖 Lore Status'));
+    console.log(`  decisions:  ${counts.decision}`);
+    console.log(`  invariants: ${counts.invariant}`);
+    console.log(`  graveyard:  ${counts.graveyard}`);
+    console.log(`  gotchas:    ${counts.gotcha}`);
+    if (draftCount > 0) {
+      console.log(chalk.yellow(`  drafts:     ${draftCount} pending — run: lore drafts`));
+    }
+
+    if (staleItems.length > 0) {
+      console.log(chalk.yellow('\n⚠️  Stale entries (linked files changed since entry was written):'));
+      for (const item of staleItems) {
+        const daysText = item.daysAgo === 0 ? 'today' : `${item.daysAgo} day${item.daysAgo === 1 ? '' : 's'} ago`;
+        console.log(chalk.yellow(`  ${item.entry.id}  →  ${item.filepath} changed ${daysText}`));
+      }
+      console.log(chalk.cyan('  Run: lore stale  for details'));
+    } else {
+      console.log(chalk.green('\n✓ All entries up to date'));
+    }
+
+    console.log();
+  } catch (e) {
+    console.error(chalk.red(`Failed to run status: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = status;

package/src/commands/watch.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+const { requireInit } = require('../lib/guard');
+const { LORE_DIR } = require('../lib/index');
+
+const pidFile = () => path.join(LORE_DIR, 'watcher.pid');
+const logFile = () => path.join(LORE_DIR, 'watcher.log');
+
+function watch(options) {
+  requireInit();
+
+  // Stop daemon
+  if (options.stop) {
+    const pf = pidFile();
+    if (!fs.existsSync(pf)) {
+      console.log(chalk.yellow('No watcher running'));
+      return;
+    }
+    const pid = parseInt(fs.readFileSync(pf, 'utf8').trim(), 10);
+    try {
+      process.kill(pid, 'SIGTERM');
+      fs.removeSync(pf);
+      console.log(chalk.green(`✓ Stopped watcher (PID ${pid})`));
+    } catch (e) {
+      console.log(chalk.yellow(`Watcher process not found (PID ${pid}) — cleaning up`));
+      fs.removeSync(pf);
+    }
+    return;
+  }
+
+  // Internal worker mode (spawned as detached child)
+  if (options.daemonWorker) {
+    const { startWatcher } = require('../watcher/index');
+    startWatcher({ quiet: true, logFile: logFile() });
+    return;
+  }
+
+  // Daemon mode: spawn detached child
+  if (options.daemon) {
+    const { spawn } = require('child_process');
+    const lf = logFile();
+    fs.ensureFileSync(lf);
+    const logFd = fs.openSync(lf, 'a');
+
+    const child = spawn(process.execPath, [process.argv[1], 'watch', '--daemon-worker'], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+    });
+    child.unref();
+    fs.closeSync(logFd);
+
+    fs.writeFileSync(pidFile(), String(child.pid));
+    console.log(chalk.green(`✓ Lore watcher started (PID ${child.pid})`));
+    console.log(chalk.dim(`   Logging to: ${lf}`));
+    console.log(chalk.dim('   Stop with: lore watch --stop'));
+    return;
+  }
+
+  // Foreground mode
+  const { startWatcher } = require('../watcher/index');
+  startWatcher({});
+}
+
+module.exports = watch;

package/src/commands/why.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const { readIndex } = require('../lib/index');
+const { requireInit } = require('../lib/guard');
+const { readEntry } = require('../lib/entries');
+const { printEntry } = require('../lib/format');
+
+function why(filepath) {
+  requireInit();
+  try {
+    const index = readIndex();
+    const normalized = filepath.replace(/^\.\//, '');
+
+    const entryIds = new Set();
+
+    // Exact match (also try with trailing slash for bare directory names)
+    if (index.files[normalized]) {
+      index.files[normalized].forEach(id => entryIds.add(id));
+    }
+    if (!normalized.endsWith('/') && index.files[normalized + '/']) {
+      index.files[normalized + '/'].forEach(id => entryIds.add(id));
+    }
+
+    // Walk up parent directories
+    let dir = path.dirname(normalized.replace(/\/$/, ''));
+    while (dir && dir !== '.') {
+      const dirKey = dir + '/';
+      if (index.files[dirKey]) {
+        index.files[dirKey].forEach(id => entryIds.add(id));
+      }
+      dir = path.dirname(dir);
+    }
+
+    if (entryIds.size === 0) {
+      console.log(chalk.cyan(`📖 No Lore entries linked to ${filepath} yet. Run: lore log`));
+      return;
+    }
+
+    console.log(chalk.cyan(`\n─── Lore Context: ${filepath} ───\n`));
+
+    for (const id of entryIds) {
+      const entryPath = index.entries[id];
+      if (!entryPath) continue;
+      const entry = readEntry(entryPath);
+      if (!entry) continue;
+      printEntry(entry);
+    }
+
+    console.log(chalk.cyan('─── End Lore Context ───\n'));
+  } catch (e) {
+    console.error(chalk.red(`Failed to run why: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+module.exports = why;