@synth-coder/memhub 0.1.0

package/src/storage/frontmatter-parser.ts

@@ -0,0 +1,243 @@
+/**
+ * FrontMatter Parser - Handles YAML Front Matter and Markdown content
+ */
+
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import type { Memory, MemoryFrontMatter } from '../contracts/types.js';
+import { slugify } from '../utils/slugify.js';
+
+/**
+ * Result of parsing a markdown file
+ */
+export interface ParseResult {
+  frontMatter: MemoryFrontMatter;
+  title: string;
+  content: string;
+}
+
+/**
+ * Custom error for front matter parsing
+ */
+export class FrontMatterError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = 'FrontMatterError';
+  }
+}
+
+/**
+ * Parses a markdown file with YAML front matter
+ *
+ * Expected format:
+ * ---
+ * id: "uuid"
+ * created_at: "ISO8601"
+ * updated_at: "ISO8601"
+ * tags: ["tag1", "tag2"]
+ * category: "category"
+ * importance: 3
+ * ---
+ *
+ * # Title
+ *
+ * Content...
+ *
+ * @param markdown - The markdown content to parse
+ * @returns Parsed front matter, title, and content
+ * @throws FrontMatterError if parsing fails
+ */
+export function parseFrontMatter(markdown: string): ParseResult {
+  // Check for front matter delimiter
+  if (!markdown.startsWith('---')) {
+    throw new FrontMatterError('Missing front matter delimiter');
+  }
+
+  // Find the end of front matter
+  const endMatch = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+  if (!endMatch) {
+    throw new FrontMatterError('Invalid front matter format');
+  }
+
+  const frontMatterYaml = endMatch[1];
+  const restOfContent = markdown.slice(endMatch[0].length);
+
+  // Parse YAML front matter
+  let frontMatter: unknown;
+  try {
+    frontMatter = parseYaml(frontMatterYaml);
+  } catch (error) {
+    throw new FrontMatterError('Invalid YAML in front matter', error);
+  }
+
+  // Validate required fields
+  if (!isValidFrontMatter(frontMatter)) {
+    throw new FrontMatterError('Missing required fields in front matter');
+  }
+
+  // Parse title and content from markdown body
+  const { title, content } = parseMarkdownBody(restOfContent);
+
+  return {
+    frontMatter,
+    title,
+    content,
+  };
+}
+
+/**
+ * Converts front matter and content to markdown string
+ *
+ * @param frontMatter - The front matter data
+ * @param title - The title (H1 heading)
+ * @param content - The markdown content
+ * @returns Complete markdown string
+ */
+export function stringifyFrontMatter(
+  frontMatter: MemoryFrontMatter,
+  title: string,
+  content: string
+): string {
+  // Convert camelCase to snake_case for YAML
+  const yamlData = {
+    id: frontMatter.id,
+    created_at: frontMatter.created_at,
+    updated_at: frontMatter.updated_at,
+    ...(frontMatter.session_id ? { session_id: frontMatter.session_id } : {}),
+    ...(frontMatter.entry_type ? { entry_type: frontMatter.entry_type } : {}),
+    tags: frontMatter.tags.length > 0 ? frontMatter.tags : [],
+    category: frontMatter.category,
+    importance: frontMatter.importance,
+  };
+
+  // Stringify YAML with specific options for consistent formatting
+  const yamlString = stringifyYaml(yamlData, {
+    indent: 2,
+    defaultKeyType: 'PLAIN',
+    defaultStringType: 'QUOTE_DOUBLE',
+  });
+
+  // Build the complete markdown
+  const parts: string[] = ['---', yamlString.trim(), '---', ''];
+
+  // Add title if provided
+  if (title) {
+    parts.push(`# ${title}`, '');
+  }
+
+  // Add content if provided
+  if (content) {
+    parts.push(content);
+  }
+
+  // Ensure content ends with a single newline
+  let result = parts.join('\n');
+  if (!result.endsWith('\n')) {
+    result += '\n';
+  }
+
+  return result;
+}
+
+/**
+ * Parses the markdown body to extract title and content
+ *
+ * @param body - The markdown body (after front matter)
+ * @returns Title and content
+ */
+function parseMarkdownBody(body: string): { title: string; content: string } {
+  const trimmed = body.trim();
+
+  if (!trimmed) {
+    return { title: '', content: '' };
+  }
+
+  // Try to extract H1 title
+  const h1Match = trimmed.match(/^#\s+(.+)$/m);
+  if (h1Match) {
+    const title = h1Match[1].trim();
+    // Remove the H1 line from content
+    const content = trimmed.replace(/^#\s+.+$/m, '').trim();
+    return { title, content };
+  }
+
+  // No H1 found, treat entire body as content
+  return { title: '', content: trimmed };
+}
+
+/**
+ * Type guard to validate front matter structure
+ *
+ * @param value - The value to check
+ * @returns True if valid front matter
+ */
+function isValidFrontMatter(value: unknown): value is MemoryFrontMatter {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  const fm = value as Record<string, unknown>;
+
+  // Check required fields
+  if (typeof fm.id !== 'string') return false;
+  if (typeof fm.created_at !== 'string') return false;
+  if (typeof fm.updated_at !== 'string') return false;
+  if (fm.session_id !== undefined && typeof fm.session_id !== 'string') return false;
+  if (fm.entry_type !== undefined && typeof fm.entry_type !== 'string') return false;
+  if (!Array.isArray(fm.tags)) return false;
+  if (typeof fm.category !== 'string') return false;
+  if (typeof fm.importance !== 'number') return false;
+
+  return true;
+}
+
+/**
+ * Converts a Memory object to front matter format
+ *
+ * @param memory - The memory object
+ * @returns Memory in front matter format
+ */
+export function memoryToFrontMatter(memory: Memory): MemoryFrontMatter {
+  return {
+    id: memory.id,
+    created_at: memory.createdAt,
+    updated_at: memory.updatedAt,
+    session_id: memory.sessionId,
+    entry_type: memory.entryType,
+    tags: memory.tags,
+    category: memory.category,
+    importance: memory.importance,
+  };
+}
+
+/**
+ * Converts front matter format to Memory object
+ *
+ * @param frontMatter - The front matter data
+ * @param title - The memory title
+ * @param content - The memory content
+ * @returns Complete Memory object
+ */
+export function frontMatterToMemory(
+  frontMatter: MemoryFrontMatter,
+  title: string,
+  content: string
+): Memory {
+  return {
+    id: frontMatter.id,
+    createdAt: frontMatter.created_at,
+    updatedAt: frontMatter.updated_at,
+    sessionId: frontMatter.session_id,
+    entryType: frontMatter.entry_type,
+    tags: frontMatter.tags,
+    category: frontMatter.category,
+    importance: frontMatter.importance,
+    title,
+    content,
+  };
+}
+
+// Re-export slugify for convenience
+export { slugify };

package/src/storage/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Storage layer exports
+ */
+
+export * from './frontmatter-parser.js';
+export * from './markdown-storage.js';

package/src/storage/markdown-storage.ts

@@ -0,0 +1,236 @@
+/**
+ * Markdown Storage - Handles file system operations for memory storage
+ */
+
+import {
+  readFile,
+  writeFile,
+  unlink,
+  readdir,
+  stat,
+  access,
+  mkdir,
+} from 'fs/promises';
+import { join, extname } from 'path';
+import { constants } from 'fs';
+import type { Memory, MemoryFile } from '../contracts/types.js';
+import {
+  parseFrontMatter,
+  stringifyFrontMatter,
+  memoryToFrontMatter,
+  frontMatterToMemory,
+  FrontMatterError,
+} from './frontmatter-parser.js';
+import { slugify } from '../utils/slugify.js';
+
+/**
+ * Custom error for storage operations
+ */
+export class StorageError extends Error {
+  constructor(
+    message: string,
+    public readonly cause?: unknown
+  ) {
+    super(message);
+    this.name = 'StorageError';
+  }
+}
+
+/**
+ * Storage configuration
+ */
+export interface StorageConfig {
+  /** Root directory for memory storage */
+  storagePath: string;
+}
+
+/**
+ * Markdown file storage implementation
+ */
+export class MarkdownStorage {
+  private readonly storagePath: string;
+
+  constructor(config: StorageConfig) {
+    this.storagePath = config.storagePath;
+  }
+
+  /**
+   * Ensures the storage directory exists
+   */
+  async initialize(): Promise<void> {
+    try {
+      await access(this.storagePath, constants.F_OK);
+    } catch {
+      // Directory doesn't exist, create it
+      await mkdir(this.storagePath, { recursive: true });
+    }
+  }
+
+  /**
+   * Writes a memory to a markdown file
+   *
+   * @param memory - The memory to write
+   * @returns The file path where the memory was stored
+   * @throws StorageError if write fails
+   */
+  async write(memory: Memory): Promise<string> {
+    await this.initialize();
+
+    const { directoryPath, filename } = this.generatePathParts(memory);
+    const filePath = join(directoryPath, filename);
+    const frontMatter = memoryToFrontMatter(memory);
+    const content = stringifyFrontMatter(frontMatter, memory.title, memory.content);
+
+    try {
+      await mkdir(directoryPath, { recursive: true });
+      await writeFile(filePath, content, 'utf-8');
+      return filePath;
+    } catch (error) {
+      throw new StorageError(`Failed to write memory file: ${filename}`, error);
+    }
+  }
+
+  /**
+   * Reads a memory by its ID
+   *
+   * @param id - The memory ID
+   * @returns The memory object
+   * @throws StorageError if memory not found or read fails
+   */
+  async read(id: string): Promise<Memory> {
+    const filePath = await this.findById(id);
+
+    if (!filePath) {
+      throw new StorageError(`Memory not found: ${id}`);
+    }
+
+    try {
+      const content = await readFile(filePath, 'utf-8');
+      const { frontMatter, title, content: bodyContent } = parseFrontMatter(content);
+      return frontMatterToMemory(frontMatter, title, bodyContent);
+    } catch (error) {
+      if (error instanceof FrontMatterError) {
+        throw new StorageError(`Invalid memory file format: ${filePath}`, error);
+      }
+      throw new StorageError(`Failed to read memory file: ${filePath}`, error);
+    }
+  }
+
+  /**
+   * Deletes a memory by its ID
+   *
+   * @param id - The memory ID
+   * @returns The file path of the deleted memory
+   * @throws StorageError if memory not found or delete fails
+   */
+  async delete(id: string): Promise<string> {
+    const filePath = await this.findById(id);
+
+    if (!filePath) {
+      throw new StorageError(`Memory not found: ${id}`);
+    }
+
+    try {
+      await unlink(filePath);
+      return filePath;
+    } catch (error) {
+      throw new StorageError(`Failed to delete memory file: ${filePath}`, error);
+    }
+  }
+
+  /**
+   * Lists all memory files
+   *
+   * @returns Array of memory file information
+   * @throws StorageError if listing fails
+   */
+  async list(): Promise<MemoryFile[]> {
+    await this.initialize();
+
+    try {
+      const markdownPaths = await this.collectMarkdownFiles(this.storagePath);
+      const files: MemoryFile[] = [];
+
+      for (const filePath of markdownPaths) {
+        const stats = await stat(filePath);
+        const content = await readFile(filePath, 'utf-8');
+
+        files.push({
+          path: filePath,
+          filename: filePath.split(/[/\\]/).pop() ?? filePath,
+          content,
+          modifiedAt: stats.mtime.toISOString(),
+        });
+      }
+
+      return files;
+    } catch (error) {
+      throw new StorageError('Failed to list memory files', error);
+    }
+  }
+
+  /**
+   * Finds a memory file by ID
+   *
+   * @param id - The memory ID to find
+   * @returns The file path or null if not found
+   * @throws StorageError if search fails
+   */
+  async findById(id: string): Promise<string | null> {
+    await this.initialize();
+
+    try {
+      const markdownPaths = await this.collectMarkdownFiles(this.storagePath);
+
+      for (const filePath of markdownPaths) {
+        try {
+          const content = await readFile(filePath, 'utf-8');
+          const { frontMatter } = parseFrontMatter(content);
+          if (frontMatter.id === id) {
+            return filePath;
+          }
+        } catch {
+          // Skip files that can't be parsed
+          continue;
+        }
+      }
+
+      return null;
+    } catch (error) {
+      throw new StorageError('Failed to search for memory file', error);
+    }
+  }
+
+  /**
+   * Generates nested path parts for a memory
+   *
+   * Format: {storage}/{YYYY-MM-DD}/{session_uuid}/{timestamp}-{slug}.md
+   */
+  private generatePathParts(memory: Memory): { directoryPath: string; filename: string } {
+    const date = memory.createdAt.split('T')[0];
+    const sessionId = memory.sessionId ?? 'default-session';
+    const titleSlug = slugify(memory.title) || 'untitled';
+    const timestamp = memory.createdAt.replace(/[:.]/g, '-');
+    const filename = `${timestamp}-${titleSlug}.md`;
+    const directoryPath = join(this.storagePath, date, sessionId);
+
+    return { directoryPath, filename };
+  }
+
+  private async collectMarkdownFiles(rootDir: string): Promise<string[]> {
+    const entries = await readdir(rootDir, { withFileTypes: true });
+    const files: string[] = [];
+
+    for (const entry of entries) {
+      const entryPath = join(rootDir, entry.name);
+      if (entry.isDirectory()) {
+        const nested = await this.collectMarkdownFiles(entryPath);
+        files.push(...nested);
+      } else if (entry.isFile() && extname(entry.name) === '.md') {
+        files.push(entryPath);
+      }
+    }
+
+    return files;
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+
+export * from './slugify.js';

package/src/utils/slugify.ts

@@ -0,0 +1,63 @@
+/**
+ * Slugify utility - Converts strings to URL-friendly slugs
+ */
+
+/**
+ * Converts a string to a URL-friendly slug
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes special characters
+ * - Collapses multiple hyphens
+ * - Trims leading/trailing hyphens
+ *
+ * @param input - The string to convert
+ * @returns The slugified string
+ */
+export function slugify(input: string): string {
+  if (!input || input.trim().length === 0) {
+    return 'untitled';
+  }
+
+  // Convert to lowercase and replace non-alphanumeric characters with hyphens
+  const slug = input
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '') // Remove special characters
+    .replace(/\s+/g, '-') // Replace spaces with hyphens
+    .replace(/-+/g, '-') // Collapse multiple hyphens
+    .replace(/^-+|-+$/g, ''); // Trim leading/trailing hyphens
+
+  // If empty after cleaning (e.g., only special characters), return 'untitled'
+  if (slug.length === 0) {
+    return 'untitled';
+  }
+
+  // Truncate to max 100 characters
+  if (slug.length > 100) {
+    return slug.substring(0, 100).replace(/-+$/, ''); // Don't end with hyphen
+  }
+
+  return slug;
+}
+
+/**
+ * Generates a unique slug by appending a timestamp or counter if needed
+ *
+ * @param title - The title to slugify
+ * @param existingSlugs - Array of existing slugs to check against
+ * @returns A unique slug
+ */
+export function generateUniqueSlug(title: string, existingSlugs: readonly string[] = []): string {
+  const slug = slugify(title);
+  let counter = 1;
+  let uniqueSlug = slug;
+
+  while (existingSlugs.includes(uniqueSlug)) {
+    const suffix = `-${counter}`;
+    const maxBaseLength = 100 - suffix.length;
+    const baseSlug = slug.substring(0, maxBaseLength).replace(/-+$/, '');
+    uniqueSlug = `${baseSlug}${suffix}`;
+    counter++;
+  }
+
+  return uniqueSlug;
+}