memorylink 1.0.0

package/src/utils.ts

@@ -0,0 +1,885 @@
+/**
+ * MemoryLink - Utility Functions
+ * 
+ * v1.0 UPDATE: Added JSONL utilities, file locking, secret detection,
+ * and duration parsing for robust, concurrent-safe operations.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { v4 as uuidv4 } from 'uuid';
+import lockfile from 'proper-lockfile';
+import { 
+  MEMORYLINK_DIR, 
+  FILES, 
+  DEFAULT_IGNORE_PATTERNS,
+  SECRET_PATTERNS,
+  DURATION_MS,
+  type DurationUnit,
+  type BaseEntry,
+  type MemoryEntry,
+  type LearningEntry,
+  type ChangeEntry,
+  type MemoryStatus,
+  type Sensitivity,
+  type TrustLevel,
+  type SourceType,
+  type Provenance,
+  JSONL_SCHEMA_VERSION,
+} from './types.js';
+import type { MemoryLinkConfig } from './types.js';
+
+// ANSI color codes (for environments where chalk might not work)
+export const colors = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+};
+
+export function colorize(text: string, color: keyof typeof colors): string {
+  return `${colors[color]}${text}${colors.reset}`;
+}
+
+// Find the root directory containing .memorylink
+export function findRoot(startDir: string = process.cwd()): string | null {
+  let currentDir = startDir;
+  
+  while (currentDir !== path.parse(currentDir).root) {
+    if (fs.existsSync(path.join(currentDir, MEMORYLINK_DIR))) {
+      return currentDir;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+  
+  return null;
+}
+
+// Get the .memorylink directory path
+export function getMemoryLinkDir(root?: string): string {
+  const rootDir = root || findRoot() || process.cwd();
+  return path.join(rootDir, MEMORYLINK_DIR);
+}
+
+// Get a specific file path
+export function getFilePath(file: keyof typeof FILES, root?: string): string {
+  return path.join(getMemoryLinkDir(root), FILES[file]);
+}
+
+/**
+ * Normalize path to use forward slashes (Git-compatible)
+ * Windows backslashes are converted to forward slashes
+ * This ensures paths are consistent across platforms for storage
+ */
+export function normalizePath(filePath: string): string {
+  return filePath.replace(/\\/g, '/');
+}
+
+/**
+ * Normalize path for storage (always forward slashes, relative to root)
+ * For file operations, use platform-specific paths
+ * For storage in JSONL, use normalized forward-slash paths
+ */
+export function normalizePathForStorage(filePath: string, root: string): string {
+  // Normalize to forward slashes
+  let normalized = normalizePath(filePath);
+  
+  // If absolute path, make relative to root
+  if (path.isAbsolute(normalized)) {
+    normalized = path.relative(root, normalized);
+    // Normalize again after making relative
+    normalized = normalizePath(normalized);
+  }
+  
+  // Remove leading ./ if present
+  normalized = normalized.replace(/^\.\//, '');
+  
+  return normalized;
+}
+
+/**
+ * Convert normalized path to platform-specific path for file operations
+ */
+export function denormalizePath(normalizedPath: string, root: string): string {
+  const fullPath = path.isAbsolute(normalizedPath) 
+    ? normalizedPath 
+    : path.join(root, normalizedPath);
+  return path.normalize(fullPath);
+}
+
+// Check if MemoryLink is initialized
+export function isInitialized(root?: string): boolean {
+  const dir = getMemoryLinkDir(root);
+  return fs.existsSync(dir) && fs.existsSync(path.join(dir, FILES.CONFIG));
+}
+
+// Get current timestamp in ISO format
+export function getTimestamp(): string {
+  return new Date().toISOString();
+}
+
+/**
+ * Validate project scope name (v1.5 Phase 2)
+ * Rules: max 50 chars, alphanumeric, dash, underscore
+ */
+export function validateScope(scope: string): { valid: boolean; error?: string } {
+  if (!scope || scope.trim().length === 0) {
+    return { valid: false, error: 'Scope cannot be empty' };
+  }
+
+  if (scope.length > 50) {
+    return { valid: false, error: 'Scope must be 50 characters or less' };
+  }
+
+  // Allow: alphanumeric, dash, underscore, forward slash (for hierarchical)
+  const validPattern = /^[a-zA-Z0-9_/-]+$/;
+  if (!validPattern.test(scope)) {
+    return { valid: false, error: 'Scope can only contain letters, numbers, dashes, underscores, and slashes' };
+  }
+
+  return { valid: true };
+}
+
+// Format timestamp for display
+export function formatTimestamp(iso: string): string {
+  const date = new Date(iso);
+  return date.toLocaleString();
+}
+
+// Read a file safely
+export function readFileSafe(filePath: string): string {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+// Append to a file
+export function appendToFile(filePath: string, content: string): void {
+  fs.appendFileSync(filePath, content + '\n');
+}
+
+// Read lines from a file (non-empty)
+export function readLines(filePath: string): string[] {
+  const content = readFileSafe(filePath);
+  return content.split('\n').filter(line => line.trim() !== '');
+}
+
+// Count lines in a file
+export function countLines(filePath: string): number {
+  return readLines(filePath).length;
+}
+
+// Read the config file
+export function readConfig(root?: string): MemoryLinkConfig | null {
+  const configPath = getFilePath('CONFIG', root);
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+// Write the config file
+export function writeConfig(config: MemoryLinkConfig, root?: string): void {
+  const configPath = getFilePath('CONFIG', root);
+  writeFileAtomic(configPath, JSON.stringify(config, null, 2));
+}
+
+// Read ignore patterns
+export function readIgnorePatterns(root?: string): string[] {
+  const ignorePath = path.join(root || findRoot() || process.cwd(), FILES.IGNORE);
+  if (fs.existsSync(ignorePath)) {
+    const content = fs.readFileSync(ignorePath, 'utf-8');
+    const patterns = content.split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#'));
+    return [...DEFAULT_IGNORE_PATTERNS, ...patterns];
+  }
+  return DEFAULT_IGNORE_PATTERNS;
+}
+
+// Log with optional verbose mode
+export function log(message: string, verbose: boolean = false): void {
+  if (verbose) {
+    console.log(colorize(`[DEBUG] ${getTimestamp()}`, 'gray'), message);
+  }
+}
+
+// Print success message
+export function success(message: string): void {
+  console.log(colorize('✓', 'green'), message);
+}
+
+// Print error message
+export function error(message: string): void {
+  console.error(colorize('✗', 'red'), message);
+  // Reference troubleshooting guide for common errors
+  if (message.includes('not initialized') || 
+      message.includes('Failed to read') || 
+      message.includes('locked') ||
+      message.includes('parse error')) {
+    console.error(colorize('💡', 'cyan'), 'Run `memorylink doctor` for diagnosis, or see TROUBLESHOOTING.md');
+  }
+}
+
+// Print warning message
+export function warn(message: string): void {
+  console.log(colorize('⚠', 'yellow'), message);
+}
+
+/**
+ * Safe console.log that handles EPIPE errors gracefully
+ * Used when output might be piped to /dev/null or closed streams
+ */
+export function safeLog(...args: any[]): void {
+  try {
+    console.log(...args);
+  } catch (err: any) {
+    // Ignore EPIPE errors (broken pipe) - happens when stdout is closed
+    if (err.code !== 'EPIPE' && err.errno !== -32) {
+      // Re-throw if it's not an EPIPE error
+      throw err;
+    }
+    // Silently ignore EPIPE - this is expected when output is suppressed
+  }
+}
+
+/**
+ * Safe console.error that handles EPIPE errors gracefully
+ */
+export function safeError(...args: any[]): void {
+  try {
+    console.error(...args);
+  } catch (err: any) {
+    // Ignore EPIPE errors (broken pipe)
+    if (err.code !== 'EPIPE' && err.errno !== -32) {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Check if stdout is writable before writing
+ * Returns true if safe to write, false otherwise
+ */
+export function isStdoutWritable(): boolean {
+  try {
+    return process.stdout.writable && !process.stdout.destroyed;
+  } catch {
+    return false;
+  }
+}
+
+// Print info message
+export function info(message: string): void {
+  console.log(colorize('ℹ', 'blue'), message);
+}
+
+/**
+ * Normalize a single tag (lowercase, hyphenate spaces)
+ * Examples: "TypeScript" → "typescript", "Type Script" → "type-script"
+ */
+export function normalizeTag(tag: string): string {
+  return tag
+    .toLowerCase()                    // "TypeScript" → "typescript"
+    .trim()                           // Remove whitespace
+    .replace(/\s+/g, '-')             // "Type Script" → "type-script"
+    .replace(/[^a-z0-9-]/g, '')       // Remove special chars (keep alphanumeric and hyphens)
+    .replace(/-+/g, '-')              // Multiple hyphens → single hyphen
+    .replace(/^-|-$/g, '');           // Remove leading/trailing hyphens
+}
+
+/**
+ * Parse and normalize tags from comma-separated string
+ * Tags are automatically normalized (lowercase, hyphenated)
+ */
+export function parseTags(tagString?: string): string[] {
+  if (!tagString) return [];
+  return tagString
+    .split(',')
+    .map(t => normalizeTag(t))
+    .filter(t => t.length > 0); // Filter out empty tags after normalization
+}
+
+// Format tags for storage
+export function formatTags(tags: string[]): string {
+  return tags.length > 0 ? ` [${tags.join(', ')}]` : '';
+}
+
+// Ensure directory exists
+export function ensureDir(dirPath: string): void {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+// Atomic write helper (write temp then rename)
+export function writeFileAtomic(filePath: string, content: string): void {
+  const dir = path.dirname(filePath);
+  ensureDir(dir);
+  const tempPath = path.join(dir, `.tmp-${path.basename(filePath)}-${Date.now()}`);
+  fs.writeFileSync(tempPath, content);
+  fs.renameSync(tempPath, filePath);
+}
+
+// Relative path from root
+export function relativePath(fullPath: string, root?: string): string {
+  const rootDir = root || findRoot() || process.cwd();
+  return path.relative(rootDir, fullPath);
+}
+
+// ============================================
+// UUID GENERATION
+// ============================================
+
+/**
+ * Generate a unique ID for log entries
+ */
+export function generateId(): string {
+  return uuidv4();
+}
+
+/**
+ * Generate a short ID prefix for display (first 8 chars)
+ */
+export function shortId(id: string): string {
+  return id.substring(0, 8);
+}
+
+// ============================================
+// FILE LOCKING (Concurrent Write Protection)
+// ============================================
+
+/**
+ * Append a JSONL entry to a log file with file locking
+ * Prevents concurrent write corruption
+ */
+export async function appendJsonlEntry<T extends BaseEntry>(
+  filePath: string, 
+  entry: T
+): Promise<void> {
+  // Ensure file exists
+  if (!fs.existsSync(filePath)) {
+    fs.writeFileSync(filePath, '');
+  }
+
+  // Acquire lock with retries
+  let release: (() => Promise<void>) | null = null;
+  
+  try {
+    release = await lockfile.lock(filePath, {
+      retries: {
+        retries: 5,
+        minTimeout: 100,
+        maxTimeout: 1000,
+      },
+    });
+
+    // Append JSONL entry
+    const line = JSON.stringify(entry) + '\n';
+    // Guard against oversized entries
+    if (line.length > 10000) {
+      throw new Error('Entry too large to store. Please shorten the message.');
+    }
+    fs.appendFileSync(filePath, line);
+  } finally {
+    // Release lock
+    if (release) {
+      await release();
+    }
+  }
+}
+
+/**
+ * Normalize v1.3 MemoryEntry to v1.4 format with defaults
+ * Maintains backward compatibility while adding v1.4 fields
+ */
+function normalizeMemoryEntryToV14(entry: MemoryEntry, root: string): MemoryEntry {
+  // If already v1.4, return as-is
+  if (entry.schemaVersion === '1.4.0') {
+    return entry;
+  }
+
+  // Determine source type from agent field
+  const sourceType: SourceType = 
+    entry.agent === 'user' || !entry.agent || entry.agent === 'migrated' 
+      ? 'human' 
+      : ['cursor', 'claude', 'chatgpt', 'copilot', 'windsurf'].includes(entry.agent.toLowerCase())
+      ? 'agent'
+      : 'code';
+
+  // Determine memory status: VERIFIED for human, DRAFT for agent
+  const memoryStatus: MemoryStatus = sourceType === 'human' ? 'VERIFIED' : 'DRAFT';
+
+  // Build provenance from existing fields
+  const provenance: Provenance = {
+    createdAt: entry.ts,
+    createdBy: entry.agent || 'unknown',
+    tool: entry.agent || undefined,
+    kind: sourceType === 'human' ? 'user' : 'app',
+  };
+
+  // Get project path (relative to root)
+  const projectPath = root || process.cwd();
+
+  // Add v1.4 fields with defaults
+  return {
+    ...entry,
+    schemaVersion: '1.4.0',
+    recordVersion: 1,
+    projectPath,
+    sensitivity: 'internal' as Sensitivity,
+    trustLevel: 'medium' as TrustLevel,
+    memoryStatus,
+    sourceType,
+    provenance,
+  };
+}
+
+/**
+ * Detect schema version from an entry
+ */
+function detectSchemaVersion(entry: any): string {
+  if (entry.schemaVersion) {
+    return entry.schemaVersion;
+  }
+  // v1.3 and earlier don't have schemaVersion
+  return '1.3.0';
+}
+
+/**
+ * Read all JSONL entries from a log file
+ * v1.4: Automatically normalizes v1.3 entries to v1.4 format
+ */
+export function readJsonlEntries<T>(filePath: string): T[] {
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n').filter(line => line.trim() !== '');
+  const entries: T[] = [];
+  const root = findRoot() || process.cwd();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    
+    // Skip comments (legacy format)
+    if (line.startsWith('#')) {
+      continue;
+    }
+
+    try {
+      const entry = JSON.parse(line) as T;
+      
+      // Normalize MemoryEntry from v1.3 to v1.4 if needed
+      if (filePath.includes('memory.log') && typeof entry === 'object' && entry !== null && 'type' in entry && 'details' in entry) {
+        const memEntry = entry as unknown as MemoryEntry;
+        const schemaVersion = detectSchemaVersion(memEntry);
+        
+        if (schemaVersion < '1.4.0') {
+          const normalized = normalizeMemoryEntryToV14(memEntry, root);
+          entries.push(normalized as T);
+          continue;
+        }
+      }
+      
+      entries.push(entry);
+    } catch (err) {
+      // Skip invalid JSON lines (might be legacy format)
+      warn(`Line ${i + 1}: Invalid JSON, skipping`);
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Read JSONL entries with streaming (memory-efficient for large files)
+ * Use this for files with 10K+ entries
+ */
+export async function readJsonlEntriesStreaming<T>(
+  filePath: string,
+  options: {
+    page?: number;
+    perPage?: number;
+    filter?: (entry: T) => boolean;
+  } = {}
+): Promise<T[]> {
+  const { streamJsonlEntries } = await import('./utils/streaming.js');
+  const entries: T[] = [];
+  
+  for await (const entry of streamJsonlEntries<T>(filePath, options)) {
+    entries.push(entry);
+  }
+  
+  return entries;
+}
+
+/**
+ * Check if a log file is in JSONL format
+ */
+export function isJsonlFormat(filePath: string): boolean {
+  if (!fs.existsSync(filePath)) {
+    return true; // New files will be JSONL
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n').filter(line => line.trim() !== '' && !line.startsWith('#'));
+  
+  if (lines.length === 0) {
+    return true; // Empty file
+  }
+
+  // Check first non-comment line
+  const firstLine = lines[0].trim();
+  return firstLine.startsWith('{');
+}
+
+// ============================================
+// SECRET DETECTION
+// ============================================
+
+export interface SecretDetectionResult {
+  detected: boolean;
+  patterns: string[];
+}
+
+/**
+ * Check content for potential secrets
+ */
+export function detectSecrets(content: string): SecretDetectionResult {
+  const detectedPatterns: string[] = [];
+
+  for (const secretPattern of SECRET_PATTERNS) {
+    if (secretPattern.pattern.test(content)) {
+      detectedPatterns.push(secretPattern.name);
+    }
+  }
+
+  return {
+    detected: detectedPatterns.length > 0,
+    patterns: detectedPatterns,
+  };
+}
+
+/**
+ * Check for prompt injection patterns (system prompts, instruction overrides)
+ */
+function detectPromptInjection(content: string): boolean {
+  const promptInjectionPatterns = [
+    /ignore\s+(previous|all|above)\s+(instructions|rules|context)/i,
+    /forget\s+(everything|all|previous)/i,
+    /you\s+are\s+now\s+(a|an)\s+/i,
+    /system\s*:\s*(you|ignore|forget)/i,
+    /\[SYSTEM\]|\[INST\]|\[PROMPT\]/i,
+    /override\s+(previous|all|system)\s+(instructions|rules)/i,
+    /new\s+(instructions|rules|system)\s*:/i,
+    /disregard\s+(previous|all|above)/i,
+  ];
+  
+  return promptInjectionPatterns.some(pattern => pattern.test(content));
+}
+
+/**
+ * Check content for secrets and prompt injection, handle based on force flag
+ * Returns true if write should proceed, false if blocked
+ */
+export function checkSecretsBeforeWrite(
+  content: string, 
+  force: boolean = false
+): boolean {
+  // Check for prompt injection first
+  if (detectPromptInjection(content) && !force) {
+    console.error('');
+    console.error(colorize('❌ PROMPT INJECTION DETECTED - Command blocked', 'red'));
+    console.error('');
+    console.error('Detected suspicious patterns that could override AI behavior.');
+    console.error('');
+    console.error(colorize('Why this is dangerous:', 'yellow'));
+    console.error('  1. Could inject malicious instructions into AI context');
+    console.error('  2. Could override safety rules and preferences');
+    console.error('  3. Could compromise AI behavior in team environments');
+    console.error('');
+    console.error(colorize('Recommended actions:', 'cyan'));
+    console.error('  1. Rephrase without instruction-override language');
+    console.error('  2. Use clear, declarative statements instead');
+    console.error('     Example: "Project uses TypeScript" (not "Forget previous, use TypeScript")');
+    console.error('');
+    console.error(colorize('If you\'re CERTAIN this is safe:', 'yellow'));
+    console.error('  Add --force flag to proceed');
+    console.error('');
+    return false; // Block write
+  }
+  
+  const result = detectSecrets(content);
+
+  if (!result.detected) {
+    return true; // No secrets, proceed
+  }
+
+  if (!force) {
+    // Block write and show warning
+    console.error('');
+    console.error(colorize('❌ SECRET DETECTED - Command blocked', 'red'));
+    console.error('');
+    console.error('Detected patterns:');
+    for (const pattern of result.patterns) {
+      console.error(`  - ${pattern}`);
+    }
+    console.error('');
+    console.error(colorize('Why this is dangerous:', 'yellow'));
+    console.error('  1. Secrets will be committed to Git');
+    console.error('  2. Secrets will be in Git history forever');
+    console.error('  3. Team members will see secrets');
+    console.error('  4. Secrets may be pushed to remote repos');
+    console.error('');
+    console.error(colorize('Recommended actions:', 'cyan'));
+    console.error('  1. Use environment variables instead');
+    console.error('  2. Reference secrets, don\'t include them');
+    console.error('     Example: "API key stored in .env file"');
+    console.error('');
+    console.error(colorize('If you\'re CERTAIN this is not a secret:', 'yellow'));
+    console.error('  Add --force flag to proceed');
+    console.error('');
+    
+    return false; // Block write
+  }
+
+  // Force flag used - warn but allow
+  console.warn('');
+  console.warn(colorize('⚠️  WARNING: Secret pattern detected but proceeding (--force)', 'yellow'));
+  console.warn('You are responsible for this secret in version control.');
+  console.warn('');
+  
+  return true; // Allow write with warning
+}
+
+// ============================================
+// DURATION PARSING
+// ============================================
+
+/**
+ * Parse a duration string like "7d", "2w", "1m" to a Date
+ * Returns date that is `duration` ago from now
+ */
+export function parseDuration(duration: string): Date | null {
+  const match = duration.match(/^(\d+)([dwmy])$/);
+  
+  if (!match) {
+    return null;
+  }
+
+  const [, numStr, unit] = match;
+  const num = parseInt(numStr, 10);
+  const ms = DURATION_MS[unit as DurationUnit];
+  
+  if (!ms) {
+    return null;
+  }
+
+  return new Date(Date.now() - num * ms);
+}
+
+/**
+ * Format a duration for display
+ */
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ago`;
+  if (hours > 0) return `${hours}h ago`;
+  if (minutes > 0) return `${minutes}m ago`;
+  return `${seconds}s ago`;
+}
+
+// ============================================
+// ENTRY FILTERING
+// ============================================
+
+/**
+ * Filter entries by tag
+ */
+export function filterByTag<T extends BaseEntry>(entries: T[], tag: string): T[] {
+  const lowerTag = tag.toLowerCase();
+  return entries.filter(e => 
+    e.tags?.some(t => t.toLowerCase() === lowerTag)
+  );
+}
+
+/**
+ * Filter entries by date (since duration)
+ */
+export function filterBySince<T extends BaseEntry>(entries: T[], since: string): T[] {
+  const cutoff = parseDuration(since);
+  if (!cutoff) return entries;
+  
+  return entries.filter(e => new Date(e.ts) > cutoff);
+}
+
+/**
+ * Filter entries by status
+ */
+export function filterByStatus<T extends BaseEntry>(
+  entries: T[], 
+  status: string
+): T[] {
+  return entries.filter(e => e.status === status);
+}
+
+/**
+ * Search entries by keyword (in details, problem, solution, or tags)
+ */
+export function searchEntries<T extends BaseEntry>(
+  entries: T[], 
+  keyword: string
+): T[] {
+  const kw = keyword.toLowerCase();
+  
+  return entries.filter(e => {
+    // Check tags
+    if (e.tags?.some(t => t.toLowerCase().includes(kw))) {
+      return true;
+    }
+    
+    // Check memory-specific fields
+    const memEntry = e as unknown as MemoryEntry;
+    if (memEntry.details?.toLowerCase().includes(kw)) {
+      return true;
+    }
+    
+    // Check learning-specific fields
+    const learnEntry = e as unknown as LearningEntry;
+    if (learnEntry.problem?.toLowerCase().includes(kw)) {
+      return true;
+    }
+    if (learnEntry.solution?.toLowerCase().includes(kw)) {
+      return true;
+    }
+    
+    // Check change-specific fields
+    const changeEntry = e as unknown as ChangeEntry;
+    if (changeEntry.file?.toLowerCase().includes(kw)) {
+      return true;
+    }
+    if (changeEntry.reason?.toLowerCase().includes(kw)) {
+      return true;
+    }
+    
+    // Check code snippet-specific fields
+    if (memEntry.type === 'code_snippet') {
+      if (memEntry.code?.toLowerCase().includes(kw)) {
+        return true;
+      }
+      if (memEntry.language?.toLowerCase().includes(kw)) {
+        return true;
+      }
+      if (memEntry.context?.toLowerCase().includes(kw)) {
+        return true;
+      }
+    }
+    
+    return false;
+  });
+}
+
+// ============================================
+// LEGACY FORMAT DETECTION & PARSING
+// ============================================
+
+/**
+ * Check if any log files are in legacy (text) format
+ */
+export function hasLegacyFormat(root?: string): boolean {
+  const logFiles = ['MEMORY', 'LEARNINGS', 'CHANGES'] as const;
+  
+  for (const fileKey of logFiles) {
+    const filePath = getFilePath(fileKey, root);
+    if (fs.existsSync(filePath) && !isJsonlFormat(filePath)) {
+      return true;
+    }
+  }
+  
+  return false;
+}
+
+/**
+ * Parse legacy memory entry: [TIMESTAMP] MESSAGE [tags]
+ */
+export function parseLegacyMemoryLine(line: string): MemoryEntry | null {
+  const match = line.match(/\[(.*?)\]\s*(.+?)(\s*\[.*\])?$/);
+  if (!match) return null;
+
+  const [, timestamp, message, tagsStr] = match;
+  const tags = tagsStr 
+    ? tagsStr.slice(2, -1).split(',').map(t => t.trim()).filter(Boolean)
+    : [];
+
+  return {
+    id: generateId(),
+    ts: timestamp,
+    agent: 'migrated',
+    type: 'note',
+    details: message.trim(),
+    tags,
+    status: 'ACTIVE',
+  };
+}
+
+/**
+ * Parse legacy learning entry: [TIMESTAMP] [STATUS] PROBLEM -> SOLUTION [tags]
+ */
+export function parseLegacyLearningLine(line: string): LearningEntry | null {
+  const match = line.match(/\[(.*?)\]\s*\[(.*?)\]\s*(.+?)\s*->\s*(.+?)(\s*\[.*\])?$/);
+  if (!match) return null;
+
+  const [, timestamp, statusPart, problem, solution, tagsStr] = match;
+  const outcome = statusPart.includes('SUCCESS') ? 'SUCCESS' : 'FAILED';
+  const tags = tagsStr 
+    ? tagsStr.slice(2, -1).split(',').map(t => t.trim()).filter(Boolean)
+    : [];
+
+  return {
+    id: generateId(),
+    ts: timestamp,
+    agent: 'migrated',
+    problem: problem.trim(),
+    solution: solution.trim(),
+    outcome,
+    tags,
+    status: 'ACTIVE',
+  };
+}
+
+/**
+ * Parse legacy change entry: [TIMESTAMP] FILE: REASON (agent)
+ */
+export function parseLegacyChangeLine(line: string): ChangeEntry | null {
+  const match = line.match(/\[(.*?)\]\s*(.+?):\s*(.+?)(\s*\(.*\))?$/);
+  if (!match) return null;
+
+  const [, timestamp, file, reason, agentStr] = match;
+  const agent = agentStr ? agentStr.slice(2, -1) : 'migrated';
+
+  return {
+    id: generateId(),
+    ts: timestamp,
+    agent,
+    file: file.trim(),
+    action: 'edited',
+    reason: reason.trim(),
+    status: 'ACTIVE',
+  };
+}
+