@hbarefoot/engram 1.0.0 → 1.2.0

package/src/import/parsers/claude.js

@@ -0,0 +1,208 @@
+import fs from 'fs';
+import path from 'path';
+import { validateContent } from '../../extract/secrets.js';
+
+const CLAUDE_LOCATIONS = [
+  '.claude',
+  'CLAUDE.md',
+  '.claude/settings.json',
+  '.claude/commands'
+];
+
+/**
+ * Detect if .claude project files exist
+ */
+export function detect(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  for (const loc of CLAUDE_LOCATIONS) {
+    const fullPath = path.resolve(cwd, loc);
+    if (fs.existsSync(fullPath)) {
+      return { found: true, path: path.resolve(cwd) };
+    }
+  }
+
+  return { found: false, path: null };
+}
+
+/**
+ * Parse .claude project files into memory candidates
+ */
+export async function parse(options = {}) {
+  const result = { source: 'claude', memories: [], skipped: [], warnings: [] };
+  const cwd = options.cwd || process.cwd();
+
+  // Parse CLAUDE.md
+  const claudeMdPath = path.resolve(cwd, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    parseClaudeMd(claudeMdPath, result);
+  }
+
+  // Parse .claude/settings.json
+  const settingsPath = path.resolve(cwd, '.claude/settings.json');
+  if (fs.existsSync(settingsPath)) {
+    parseClaudeSettings(settingsPath, result);
+  }
+
+  // Parse .claude/commands directory
+  const commandsPath = path.resolve(cwd, '.claude/commands');
+  if (fs.existsSync(commandsPath) && fs.statSync(commandsPath).isDirectory()) {
+    parseClaudeCommands(commandsPath, result);
+  }
+
+  if (result.memories.length === 0) {
+    result.warnings.push('No .claude project files found or no extractable content');
+  }
+
+  return result;
+}
+
+/**
+ * Parse CLAUDE.md into structured memories
+ */
+function parseClaudeMd(filePath, result) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  let currentSection = null;
+  let currentBlock = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    // Section headers
+    if (/^#{1,3}\s+/.test(line)) {
+      if (currentBlock.length > 0) {
+        flushClaudeBlock(currentBlock, currentSection, result);
+        currentBlock = [];
+      }
+      currentSection = line.replace(/^#{1,3}\s+/, '').trim();
+      continue;
+    }
+
+    // Skip empty lines
+    if (!line) {
+      if (currentBlock.length > 0) {
+        flushClaudeBlock(currentBlock, currentSection, result);
+        currentBlock = [];
+      }
+      continue;
+    }
+
+    // Skip code blocks (fences)
+    if (line.startsWith('```')) continue;
+
+    // Collect content
+    const cleaned = line.replace(/^[-*]\s+/, '').trim();
+    if (cleaned.length > 15) {
+      currentBlock.push(cleaned);
+    }
+  }
+
+  if (currentBlock.length > 0) {
+    flushClaudeBlock(currentBlock, currentSection, result);
+  }
+}
+
+function flushClaudeBlock(lines, section, result) {
+  // Group related lines into single memories when they're short
+  const grouped = [];
+  let current = [];
+
+  for (const line of lines) {
+    if (line.length > 100) {
+      // Long lines become individual memories
+      if (current.length > 0) {
+        grouped.push(current.join('. '));
+        current = [];
+      }
+      grouped.push(line);
+    } else {
+      current.push(line);
+      if (current.join('. ').length > 150) {
+        grouped.push(current.join('. '));
+        current = [];
+      }
+    }
+  }
+  if (current.length > 0) grouped.push(current.join('. '));
+
+  for (const text of grouped) {
+    const validation = validateContent(text, { autoRedact: false });
+    if (!validation.valid) {
+      result.skipped.push({ content: text, reason: 'Contains secrets' });
+      result.warnings.push('Skipped CLAUDE.md section containing sensitive data');
+      continue;
+    }
+
+    const content = section
+      ? `Claude project context (${section}): ${text}`
+      : `Claude project context: ${text}`;
+
+    if (content.length < 25) continue;
+
+    result.memories.push({
+      content,
+      category: 'fact',
+      entity: null,
+      confidence: 0.9,
+      tags: ['claude-project', 'project-context'],
+      source: 'import:claude'
+    });
+  }
+}
+
+/**
+ * Parse .claude/settings.json
+ */
+function parseClaudeSettings(filePath, result) {
+  try {
+    const settings = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+
+    if (settings.permissions?.allow) {
+      const content = `Claude project allows these tool permissions: ${settings.permissions.allow.join(', ')}`;
+      result.memories.push({
+        content,
+        category: 'fact',
+        entity: 'claude-code',
+        confidence: 0.9,
+        tags: ['claude-project', 'permissions'],
+        source: 'import:claude'
+      });
+    }
+  } catch {
+    result.warnings.push('Failed to parse .claude/settings.json');
+  }
+}
+
+/**
+ * Parse .claude/commands directory
+ */
+function parseClaudeCommands(dirPath, result) {
+  try {
+    const files = fs.readdirSync(dirPath).filter(f => f.endsWith('.md'));
+
+    for (const file of files) {
+      const name = path.basename(file, '.md');
+      const content = `Claude project has custom command: /${name}`;
+      result.memories.push({
+        content,
+        category: 'fact',
+        entity: 'claude-code',
+        confidence: 0.9,
+        tags: ['claude-project', 'custom-commands'],
+        source: 'import:claude'
+      });
+    }
+  } catch {
+    result.warnings.push('Failed to read .claude/commands directory');
+  }
+}
+
+export const meta = {
+  name: 'claude',
+  label: '.claude files',
+  description: 'Project context and instructions from Claude Code',
+  category: 'fact',
+  locations: CLAUDE_LOCATIONS
+};

package/src/import/parsers/cursorrules.js

@@ -0,0 +1,153 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { validateContent } from '../../extract/secrets.js';
+
+/**
+ * Known locations for .cursorrules files
+ */
+const CURSORRULES_LOCATIONS = [
+  '.cursorrules',
+  '.cursor/rules'
+];
+
+/**
+ * Detect if .cursorrules exists
+ * @param {Object} options
+ * @param {string} [options.cwd] - Working directory to scan
+ * @returns {Object} Detection result
+ */
+export function detect(options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  for (const loc of CURSORRULES_LOCATIONS) {
+    const fullPath = path.resolve(cwd, loc);
+    if (fs.existsSync(fullPath)) {
+      return { found: true, path: fullPath };
+    }
+  }
+
+  // Also check home directory
+  const homePath = path.join(os.homedir(), '.cursorrules');
+  if (fs.existsSync(homePath)) {
+    return { found: true, path: homePath };
+  }
+
+  return { found: false, path: null };
+}
+
+/**
+ * Parse .cursorrules file into memory candidates
+ * @param {Object} options
+ * @param {string} [options.cwd] - Working directory
+ * @param {string} [options.filePath] - Explicit file path
+ * @returns {Object} Parse result with memories, skipped, warnings
+ */
+export async function parse(options = {}) {
+  const result = { source: 'cursorrules', memories: [], skipped: [], warnings: [] };
+
+  const filePath = options.filePath || (() => {
+    const detected = detect(options);
+    return detected.path;
+  })();
+
+  if (!filePath || !fs.existsSync(filePath)) {
+    result.warnings.push('No .cursorrules file found');
+    return result;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8').trim();
+  if (!content) {
+    result.warnings.push('.cursorrules file is empty');
+    return result;
+  }
+
+  const lines = content.split('\n');
+  let currentSection = null;
+  let currentBlock = [];
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    // Skip empty lines between blocks
+    if (!line) {
+      if (currentBlock.length > 0) {
+        flushBlock(currentBlock, currentSection, result);
+        currentBlock = [];
+      }
+      continue;
+    }
+
+    // Detect section headers (markdown-style or YAML-style)
+    if (/^#{1,3}\s+/.test(line)) {
+      if (currentBlock.length > 0) {
+        flushBlock(currentBlock, currentSection, result);
+        currentBlock = [];
+      }
+      currentSection = line.replace(/^#{1,3}\s+/, '').trim();
+      continue;
+    }
+
+    // YAML-style top-level key
+    if (/^[a-zA-Z_-]+:\s*$/.test(line)) {
+      if (currentBlock.length > 0) {
+        flushBlock(currentBlock, currentSection, result);
+        currentBlock = [];
+      }
+      currentSection = line.replace(':', '').trim();
+      continue;
+    }
+
+    // Collect content lines (strip list markers)
+    const cleaned = line.replace(/^[-*]\s+/, '').replace(/^-\s+/, '').trim();
+    if (cleaned.length > 10) {
+      currentBlock.push(cleaned);
+    }
+  }
+
+  // Flush remaining block
+  if (currentBlock.length > 0) {
+    flushBlock(currentBlock, currentSection, result);
+  }
+
+  return result;
+}
+
+/**
+ * Convert a block of lines into memory candidates
+ */
+function flushBlock(lines, section, result) {
+  for (const line of lines) {
+    // Run secret detection
+    const validation = validateContent(line, { autoRedact: false });
+    if (!validation.valid) {
+      result.skipped.push({ content: line, reason: 'Contains secrets' });
+      result.warnings.push('Skipped rule containing sensitive data');
+      continue;
+    }
+
+    // Build memory content with section context
+    const content = section
+      ? `Cursor rule (${section}): ${line}`
+      : `Cursor rule: ${line}`;
+
+    if (content.length < 20) continue;
+
+    result.memories.push({
+      content,
+      category: 'preference',
+      entity: null,
+      confidence: 0.85,
+      tags: ['cursorrules', 'coding-style'],
+      source: 'import:cursorrules'
+    });
+  }
+}
+
+export const meta = {
+  name: 'cursorrules',
+  label: '.cursorrules',
+  description: 'Coding preferences and style rules from Cursor',
+  category: 'preference',
+  locations: CURSORRULES_LOCATIONS
+};

package/src/import/parsers/env.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Detect if .env.example exists
+ */
+export function detect(options = {}) {
+  const candidates = ['.env.example', '.env.sample', '.env.template'];
+  const baseDir = options.cwd || process.cwd();
+
+  for (const name of candidates) {
+    const filePath = path.resolve(baseDir, name);
+    if (fs.existsSync(filePath)) {
+      return { found: true, path: filePath };
+    }
+  }
+
+  return { found: false, path: null };
+}
+
+/**
+ * Parse .env.example for environment variable NAMES only.
+ * NEVER extracts actual values — only variable names and comments.
+ */
+export async function parse(options = {}) {
+  const result = { source: 'env', memories: [], skipped: [], warnings: [] };
+
+  const filePath = options.filePath || (() => {
+    const detected = detect(options);
+    return detected.path;
+  })();
+
+  if (!filePath || !fs.existsSync(filePath)) {
+    result.warnings.push('No .env.example file found');
+    return result;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  const variables = [];
+  let currentComment = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+
+    // Track comments as context
+    if (line.startsWith('#')) {
+      currentComment = line.replace(/^#+\s*/, '').trim();
+      continue;
+    }
+
+    if (!line) {
+      currentComment = null;
+      continue;
+    }
+
+    // Parse KEY=value (only extract KEY)
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=/);
+    if (match) {
+      variables.push({
+        name: match[1],
+        comment: currentComment
+      });
+      currentComment = null;
+    }
+  }
+
+  if (variables.length === 0) {
+    result.warnings.push('.env.example has no variables');
+    return result;
+  }
+
+  // Group variables by prefix for cleaner memories
+  const groups = {};
+  for (const v of variables) {
+    const prefix = v.name.split('_')[0];
+    if (!groups[prefix]) groups[prefix] = [];
+    groups[prefix].push(v);
+  }
+
+  // Create summary memory with all variable names
+  const varNames = variables.map(v => v.name);
+  result.memories.push({
+    content: `Project environment variables (names only): ${varNames.join(', ')}`,
+    category: 'fact',
+    entity: 'environment',
+    confidence: 0.9,
+    tags: ['env-example', 'configuration'],
+    source: 'import:env'
+  });
+
+  // Create grouped memories for larger variable sets
+  for (const [prefix, vars] of Object.entries(groups)) {
+    if (vars.length >= 2) {
+      const names = vars.map(v => v.name).join(', ');
+      const comments = vars
+        .filter(v => v.comment)
+        .map(v => `${v.name}: ${v.comment}`)
+        .join('; ');
+
+      const content = comments
+        ? `Environment config group "${prefix}": ${names}. ${comments}`
+        : `Environment config group "${prefix}": ${names}`;
+
+      result.memories.push({
+        content,
+        category: 'fact',
+        entity: 'environment',
+        confidence: 0.85,
+        tags: ['env-example', 'configuration'],
+        source: 'import:env'
+      });
+    }
+  }
+
+  // Security warning
+  result.warnings.push('Only variable NAMES were extracted — no values or secrets');
+
+  return result;
+}
+
+export const meta = {
+  name: 'env',
+  label: '.env.example',
+  description: 'Environment variable names only (NEVER values)',
+  category: 'fact',
+  locations: ['.env.example', '.env.sample', '.env.template']
+};

package/src/import/parsers/git.js

@@ -0,0 +1,194 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { validateContent } from '../../extract/secrets.js';
+
+const GITCONFIG_LOCATIONS = [
+  path.join(os.homedir(), '.gitconfig'),
+  path.join(os.homedir(), '.config/git/config')
+];
+
+/**
+ * Detect if git config exists
+ */
+export function detect() {
+  for (const loc of GITCONFIG_LOCATIONS) {
+    if (fs.existsSync(loc)) {
+      return { found: true, path: loc };
+    }
+  }
+  return { found: false, path: null };
+}
+
+/**
+ * Parse ~/.gitconfig into memory candidates
+ */
+export async function parse(options = {}) {
+  const result = { source: 'git', memories: [], skipped: [], warnings: [] };
+
+  const filePath = options.filePath || (() => {
+    const detected = detect();
+    return detected.path;
+  })();
+
+  if (!filePath || !fs.existsSync(filePath)) {
+    result.warnings.push('No .gitconfig found');
+    return result;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const sections = parseIniFile(content);
+
+  // Extract user info
+  if (sections.user) {
+    if (sections.user.name) {
+      result.memories.push({
+        content: `Git user name: ${sections.user.name}`,
+        category: 'fact',
+        entity: 'git',
+        confidence: 1.0,
+        tags: ['gitconfig', 'user-info'],
+        source: 'import:git'
+      });
+    }
+
+    if (sections.user.email) {
+      // Validate — email itself isn't a secret, but check anyway
+      const validation = validateContent(sections.user.email, { autoRedact: false });
+      if (validation.valid) {
+        result.memories.push({
+          content: `Git user email: ${sections.user.email}`,
+          category: 'fact',
+          entity: 'git',
+          confidence: 1.0,
+          tags: ['gitconfig', 'user-info'],
+          source: 'import:git'
+        });
+      }
+    }
+
+    if (sections.user.signingkey) {
+      // Don't extract the actual key, just note that signing is configured
+      result.memories.push({
+        content: 'Git commit signing is configured',
+        category: 'fact',
+        entity: 'git',
+        confidence: 1.0,
+        tags: ['gitconfig', 'security'],
+        source: 'import:git'
+      });
+    }
+  }
+
+  // Extract core settings
+  if (sections.core) {
+    const coreSettings = [];
+    if (sections.core.editor) coreSettings.push(`editor: ${sections.core.editor}`);
+    if (sections.core.autocrlf) coreSettings.push(`autocrlf: ${sections.core.autocrlf}`);
+    if (sections.core.pager) coreSettings.push(`pager: ${sections.core.pager}`);
+
+    if (coreSettings.length > 0) {
+      result.memories.push({
+        content: `Git core settings: ${coreSettings.join(', ')}`,
+        category: 'preference',
+        entity: 'git',
+        confidence: 0.9,
+        tags: ['gitconfig', 'preferences'],
+        source: 'import:git'
+      });
+    }
+  }
+
+  // Extract aliases
+  if (sections.alias) {
+    const aliases = Object.entries(sections.alias);
+    if (aliases.length > 0) {
+      const aliasStr = aliases
+        .slice(0, 10) // Limit to 10 most relevant
+        .map(([name, cmd]) => `${name}="${cmd}"`)
+        .join(', ');
+
+      result.memories.push({
+        content: `Git aliases: ${aliasStr}`,
+        category: 'pattern',
+        entity: 'git',
+        confidence: 0.85,
+        tags: ['gitconfig', 'aliases'],
+        source: 'import:git'
+      });
+    }
+  }
+
+  // Extract default branch
+  if (sections.init?.defaultBranch) {
+    result.memories.push({
+      content: `Git default branch: ${sections.init.defaultBranch}`,
+      category: 'preference',
+      entity: 'git',
+      confidence: 1.0,
+      tags: ['gitconfig', 'preferences'],
+      source: 'import:git'
+    });
+  }
+
+  // Extract merge/diff tool preferences
+  if (sections.merge?.tool || sections.diff?.tool) {
+    const tools = [];
+    if (sections.merge?.tool) tools.push(`merge tool: ${sections.merge.tool}`);
+    if (sections.diff?.tool) tools.push(`diff tool: ${sections.diff.tool}`);
+
+    result.memories.push({
+      content: `Git ${tools.join(', ')}`,
+      category: 'preference',
+      entity: 'git',
+      confidence: 0.9,
+      tags: ['gitconfig', 'tools'],
+      source: 'import:git'
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Simple INI file parser for git config format
+ */
+function parseIniFile(content) {
+  const sections = {};
+  let currentSection = null;
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+
+    if (!line || line.startsWith('#') || line.startsWith(';')) continue;
+
+    // Section header [section] or [section "subsection"]
+    const sectionMatch = line.match(/^\[([^\s\]]+)(?:\s+"([^"]+)")?\]$/);
+    if (sectionMatch) {
+      const sectionName = sectionMatch[2]
+        ? `${sectionMatch[1]}.${sectionMatch[2]}`
+        : sectionMatch[1];
+      currentSection = sectionName;
+      if (!sections[currentSection]) sections[currentSection] = {};
+      continue;
+    }
+
+    // Key = value
+    if (currentSection) {
+      const kvMatch = line.match(/^(\w+)\s*=\s*(.*)$/);
+      if (kvMatch) {
+        sections[currentSection][kvMatch[1]] = kvMatch[2].trim();
+      }
+    }
+  }
+
+  return sections;
+}
+
+export const meta = {
+  name: 'git',
+  label: 'git config',
+  description: 'Name, email, aliases, and preferences from git configuration',
+  category: 'fact',
+  locations: GITCONFIG_LOCATIONS.map(p => p.replace(os.homedir(), '~'))
+};