@hbarefoot/engram 1.1.0 → 1.3.0

package/src/import/parsers/claude.js

@@ -0,0 +1,260 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { validateContent } from '../../extract/secrets.js';
+
+const CLAUDE_LOCATIONS = [
+  '.claude',
+  'CLAUDE.md',
+  '.claude/settings.json',
+  '.claude/commands'
+];
+
+/**
+ * Detect if .claude project files exist
+ * @param {Object} [options] - Detection options
+ * @param {string} [options.cwd] - Working directory to scan
+ * @param {string[]} [options.paths] - Additional directories to scan
+ * @returns {{ found: boolean, path: string|null, paths: string[] }}
+ */
+export function detect(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const foundPaths = [];
+  const seen = new Set();
+
+  // Check cwd
+  for (const loc of CLAUDE_LOCATIONS) {
+    const fullPath = path.resolve(cwd, loc);
+    if (fs.existsSync(fullPath)) {
+      const dir = path.resolve(cwd);
+      if (!seen.has(dir)) {
+        seen.add(dir);
+        foundPaths.push(dir);
+      }
+      break;
+    }
+  }
+
+  // Always check home directory for user-level .claude
+  const homeDir = os.homedir();
+  for (const loc of CLAUDE_LOCATIONS) {
+    const fullPath = path.resolve(homeDir, loc);
+    if (fs.existsSync(fullPath)) {
+      const dir = path.resolve(homeDir);
+      if (!seen.has(dir)) {
+        seen.add(dir);
+        foundPaths.push(dir);
+      }
+      break;
+    }
+  }
+
+  // Check additional paths
+  if (options.paths && Array.isArray(options.paths)) {
+    for (const extraDir of options.paths) {
+      for (const loc of CLAUDE_LOCATIONS) {
+        const fullPath = path.resolve(extraDir, loc);
+        if (fs.existsSync(fullPath)) {
+          const dir = path.resolve(extraDir);
+          if (!seen.has(dir)) {
+            seen.add(dir);
+            foundPaths.push(dir);
+          }
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    found: foundPaths.length > 0,
+    path: foundPaths[0] || null,
+    paths: foundPaths
+  };
+}
+
+/**
+ * Parse .claude project files into memory candidates
+ * Scans cwd, home directory, and any additional paths
+ */
+export async function parse(options = {}) {
+  const result = { source: 'claude', memories: [], skipped: [], warnings: [] };
+  const detected = detect(options);
+  const dirsToScan = detected.paths.length > 0 ? detected.paths : [options.cwd || process.cwd()];
+
+  for (const dir of dirsToScan) {
+    // Parse CLAUDE.md
+    const claudeMdPath = path.resolve(dir, 'CLAUDE.md');
+    if (fs.existsSync(claudeMdPath)) {
+      parseClaudeMd(claudeMdPath, result);
+    }
+
+    // Parse .claude/settings.json
+    const settingsPath = path.resolve(dir, '.claude/settings.json');
+    if (fs.existsSync(settingsPath)) {
+      parseClaudeSettings(settingsPath, result);
+    }
+
+    // Parse .claude/commands directory
+    const commandsPath = path.resolve(dir, '.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,192 @@
+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
+ * @param {string[]} [options.paths] - Additional directories to scan
+ * @returns {{ found: boolean, path: string|null, paths: string[] }}
+ */
+export function detect(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const foundPaths = [];
+  const seen = new Set();
+
+  // Check cwd
+  for (const loc of CURSORRULES_LOCATIONS) {
+    const fullPath = path.resolve(cwd, loc);
+    if (!seen.has(fullPath) && fs.existsSync(fullPath)) {
+      seen.add(fullPath);
+      foundPaths.push(fullPath);
+    }
+  }
+
+  // Check home directory
+  const homePath = path.resolve(os.homedir(), '.cursorrules');
+  if (!seen.has(homePath) && fs.existsSync(homePath)) {
+    seen.add(homePath);
+    foundPaths.push(homePath);
+  }
+
+  // Check additional paths
+  if (options.paths && Array.isArray(options.paths)) {
+    for (const dir of options.paths) {
+      for (const loc of CURSORRULES_LOCATIONS) {
+        const fullPath = path.resolve(dir, loc);
+        if (!seen.has(fullPath) && fs.existsSync(fullPath)) {
+          seen.add(fullPath);
+          foundPaths.push(fullPath);
+        }
+      }
+    }
+  }
+
+  return {
+    found: foundPaths.length > 0,
+    path: foundPaths[0] || null,
+    paths: foundPaths
+  };
+}
+
+/**
+ * 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: [] };
+
+  // If explicit filePath, parse just that one (backward compat)
+  if (options.filePath) {
+    parseOneCursorrules(options.filePath, result);
+    return result;
+  }
+
+  const detected = detect(options);
+  if (!detected.found) {
+    result.warnings.push('No .cursorrules file found');
+    return result;
+  }
+
+  for (const filePath of detected.paths) {
+    parseOneCursorrules(filePath, result);
+  }
+
+  return result;
+}
+
+/**
+ * Parse a single .cursorrules file and accumulate results
+ */
+function parseOneCursorrules(filePath, result) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    result.warnings.push('No .cursorrules file found');
+    return;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8').trim();
+  if (!content) {
+    result.warnings.push('.cursorrules file is empty');
+    return;
+  }
+
+  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);
+  }
+}
+
+/**
+ * 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,170 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Detect if .env.example exists
+ * @param {Object} [options] - Detection options
+ * @param {string} [options.cwd] - Working directory to scan
+ * @param {string[]} [options.paths] - Additional directories to scan
+ * @returns {{ found: boolean, path: string|null, paths: string[] }}
+ */
+export function detect(options = {}) {
+  const candidates = ['.env.example', '.env.sample', '.env.template'];
+  const baseDir = options.cwd || process.cwd();
+  const foundPaths = [];
+  const seen = new Set();
+
+  // Check cwd
+  for (const name of candidates) {
+    const filePath = path.resolve(baseDir, name);
+    if (!seen.has(filePath) && fs.existsSync(filePath)) {
+      seen.add(filePath);
+      foundPaths.push(filePath);
+    }
+  }
+
+  // Check additional paths
+  if (options.paths && Array.isArray(options.paths)) {
+    for (const dir of options.paths) {
+      for (const name of candidates) {
+        const filePath = path.resolve(dir, name);
+        if (!seen.has(filePath) && fs.existsSync(filePath)) {
+          seen.add(filePath);
+          foundPaths.push(filePath);
+        }
+      }
+    }
+  }
+
+  return {
+    found: foundPaths.length > 0,
+    path: foundPaths[0] || null,
+    paths: foundPaths
+  };
+}
+
+/**
+ * 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: [] };
+
+  // If explicit filePath, parse just that one (backward compat)
+  if (options.filePath) {
+    parseOneEnv(options.filePath, result);
+    return result;
+  }
+
+  const detected = detect(options);
+  if (!detected.found) {
+    result.warnings.push('No .env.example file found');
+    return result;
+  }
+
+  for (const filePath of detected.paths) {
+    parseOneEnv(filePath, result);
+  }
+
+  return result;
+}
+
+/**
+ * Parse a single .env.example file and accumulate results
+ */
+function parseOneEnv(filePath, result) {
+  if (!fs.existsSync(filePath)) {
+    result.warnings.push(`No .env.example file found at ${filePath}`);
+    return;
+  }
+
+  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;
+  }
+
+  // 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');
+}
+
+export const meta = {
+  name: 'env',
+  label: '.env.example',
+  description: 'Environment variable names only (NEVER values)',
+  category: 'fact',
+  locations: ['.env.example', '.env.sample', '.env.template']
+};