gyrus 0.1.0

package/src/services/knowledge.ts

@@ -0,0 +1,516 @@
+/**
+ * Knowledge service for file operations
+ * Handles reading, writing, searching, and listing knowledge notes
+ */
+
+import { readdir, readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { existsSync } from "node:fs";
+import type {
+  KnowledgeNote,
+  KnowledgeCategory,
+  CreateNoteInput,
+  UpdateNoteInput,
+  SearchOptions,
+  ListOptions,
+  OperationResult,
+} from "../types/index.ts";
+import {
+  parseMarkdown,
+  serializeMarkdown,
+  createMarkdownContent,
+  getCategoryFolder,
+  getTodayDate,
+} from "./markdown.ts";
+
+/**
+ * Knowledge service class
+ * Manages all operations on the knowledge notes system
+ */
+export class KnowledgeService {
+  private knowledgePath: string;
+  private cache: Map<string, KnowledgeNote> = new Map();
+  private cacheInitialized = false;
+
+  constructor(knowledgePath: string) {
+    this.knowledgePath = knowledgePath;
+  }
+
+  /**
+   * Get the knowledge path
+   */
+  getPath(): string {
+    return this.knowledgePath;
+  }
+
+  /**
+   * Initialize the cache by reading all notes
+   */
+  async initialize(): Promise<void> {
+    if (this.cacheInitialized) return;
+    await this.refreshCache();
+    this.cacheInitialized = true;
+  }
+
+  /**
+   * Refresh the cache by re-reading all notes from disk
+   */
+  async refreshCache(): Promise<void> {
+    this.cache.clear();
+    const notes = await this.readAllNotes();
+    for (const note of notes) {
+      this.cache.set(note.id, note);
+    }
+  }
+
+  /**
+   * Read all markdown files from the knowledge directory
+   */
+  private async readAllNotes(): Promise<KnowledgeNote[]> {
+    const notes: KnowledgeNote[] = [];
+    const categories: KnowledgeCategory[] = [
+      "projects",
+      "patterns",
+      "tools",
+      "gotchas",
+      "decisions",
+    ];
+
+    for (const category of categories) {
+      const categoryPath = join(this.knowledgePath, category);
+      if (!existsSync(categoryPath)) continue;
+
+      const files = await readdir(categoryPath);
+      for (const file of files) {
+        if (!file.endsWith(".md")) continue;
+
+        const filePath = join(categoryPath, file);
+        const content = await readFile(filePath, "utf-8");
+        const relativePath = relative(this.knowledgePath, filePath);
+        const note = parseMarkdown(content, relativePath);
+
+        if (note) {
+          notes.push(note);
+        }
+      }
+    }
+
+    return notes;
+  }
+
+  /**
+   * Get a note by ID
+   */
+  async getNote(id: string): Promise<KnowledgeNote | null> {
+    await this.initialize();
+    return this.cache.get(id) ?? null;
+  }
+
+  /**
+   * Get a note by path (relative to knowledge folder)
+   */
+  async getNoteByPath(path: string): Promise<KnowledgeNote | null> {
+    await this.initialize();
+
+    for (const note of this.cache.values()) {
+      if (note.path === path) {
+        return note;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * List all notes with optional filtering
+   */
+  async listNotes(options?: ListOptions): Promise<KnowledgeNote[]> {
+    await this.initialize();
+
+    let notes = Array.from(this.cache.values());
+
+    if (options?.category) {
+      notes = notes.filter((note) => note.category === options.category);
+    }
+
+    if (options?.tags && options.tags.length > 0) {
+      notes = notes.filter((note) =>
+        options.tags!.some((tag) => note.tags.includes(tag))
+      );
+    }
+
+    // Sort by updated date (most recent first)
+    notes.sort((a, b) => b.updated.localeCompare(a.updated));
+
+    return notes;
+  }
+
+  /**
+   * Search notes by query, tags, or category
+   */
+  async searchNotes(options: SearchOptions): Promise<KnowledgeNote[]> {
+    await this.initialize();
+
+    let notes = Array.from(this.cache.values());
+
+    // Filter by category
+    if (options.category) {
+      notes = notes.filter((note) => note.category === options.category);
+    }
+
+    // Filter by tags (match any)
+    if (options.tags && options.tags.length > 0) {
+      notes = notes.filter((note) =>
+        options.tags!.some((tag) =>
+          note.tags.some((noteTag) =>
+            noteTag.toLowerCase().includes(tag.toLowerCase())
+          )
+        )
+      );
+    }
+
+    // Filter by text query (searches title and content)
+    if (options.query) {
+      const queryLower = options.query.toLowerCase();
+      notes = notes.filter(
+        (note) =>
+          note.title.toLowerCase().includes(queryLower) ||
+          note.content.toLowerCase().includes(queryLower) ||
+          note.id.toLowerCase().includes(queryLower) ||
+          (note.description?.toLowerCase().includes(queryLower) ?? false)
+      );
+    }
+
+    // Sort by relevance (title matches first, then by updated date)
+    if (options.query) {
+      const queryLower = options.query.toLowerCase();
+      notes.sort((a, b) => {
+        const aInTitle = a.title.toLowerCase().includes(queryLower) ? 1 : 0;
+        const bInTitle = b.title.toLowerCase().includes(queryLower) ? 1 : 0;
+        if (aInTitle !== bInTitle) return bInTitle - aInTitle;
+        return b.updated.localeCompare(a.updated);
+      });
+    } else {
+      notes.sort((a, b) => b.updated.localeCompare(a.updated));
+    }
+
+    return notes;
+  }
+
+  /**
+   * Create a new knowledge note
+   */
+  async createNote(input: CreateNoteInput): Promise<OperationResult> {
+    await this.initialize();
+
+    // Check if ID already exists
+    if (this.cache.has(input.id)) {
+      return {
+        success: false,
+        message: `Note with ID "${input.id}" already exists`,
+      };
+    }
+
+    // Validate ID format (kebab-case)
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(input.id)) {
+      return {
+        success: false,
+        message: "ID must be in kebab-case format (e.g., my-note-id)",
+      };
+    }
+
+    const today = getTodayDate();
+    const categoryFolder = getCategoryFolder(input.category);
+    const fileName = `${input.id}.md`;
+    const relativePath = join(categoryFolder, fileName);
+    const absolutePath = join(this.knowledgePath, relativePath);
+
+    // Ensure category directory exists
+    const categoryPath = join(this.knowledgePath, categoryFolder);
+    if (!existsSync(categoryPath)) {
+      await mkdir(categoryPath, { recursive: true });
+    }
+
+    // Create markdown content
+    const markdownContent = createMarkdownContent({
+      id: input.id,
+      title: input.title,
+      content: input.content,
+      created: today,
+      updated: today,
+      tags: input.tags,
+      related: input.related,
+      description: input.description,
+    });
+
+    // Write file
+    await writeFile(absolutePath, markdownContent, "utf-8");
+
+    // Create note object and add to cache
+    const note: KnowledgeNote = {
+      id: input.id,
+      title: input.title,
+      created: today,
+      updated: today,
+      tags: input.tags ?? [],
+      related: input.related ?? [],
+      description: input.description,
+      content: input.content,
+      path: relativePath,
+      category: input.category,
+    };
+
+    this.cache.set(input.id, note);
+
+    // Update index.md
+    await this.updateIndex();
+
+    return {
+      success: true,
+      message: `Created note "${input.title}" at ${relativePath}`,
+      note,
+    };
+  }
+
+  /**
+   * Update an existing knowledge note
+   */
+  async updateNote(input: UpdateNoteInput): Promise<OperationResult> {
+    await this.initialize();
+
+    const existingNote = this.cache.get(input.id);
+    if (!existingNote) {
+      return {
+        success: false,
+        message: `Note with ID "${input.id}" not found`,
+      };
+    }
+
+    const today = getTodayDate();
+
+    // Merge updates with existing note
+    const updatedNote: KnowledgeNote = {
+      ...existingNote,
+      title: input.title ?? existingNote.title,
+      content: input.content ?? existingNote.content,
+      tags: input.tags ?? existingNote.tags,
+      related: input.related ?? existingNote.related,
+      description: input.description ?? existingNote.description,
+      updated: today,
+    };
+
+    // Serialize and write
+    const markdownContent = serializeMarkdown(updatedNote);
+    const absolutePath = join(this.knowledgePath, existingNote.path);
+    await writeFile(absolutePath, markdownContent, "utf-8");
+
+    // Update cache
+    this.cache.set(input.id, updatedNote);
+
+    // Update index.md if title or tags changed
+    if (input.title || input.tags) {
+      await this.updateIndex();
+    }
+
+    return {
+      success: true,
+      message: `Updated note "${updatedNote.title}"`,
+      note: updatedNote,
+    };
+  }
+
+  /**
+   * Update the index.md file to reflect current notes
+   */
+  private async updateIndex(): Promise<void> {
+    const notes = Array.from(this.cache.values());
+
+    // Group notes by category
+    const byCategory: Record<string, KnowledgeNote[]> = {
+      projects: [],
+      patterns: [],
+      tools: [],
+      gotchas: [],
+      decisions: [],
+    };
+
+    for (const note of notes) {
+      if (note.category !== "root" && byCategory[note.category]) {
+        byCategory[note.category]!.push(note);
+      }
+    }
+
+    // Sort each category alphabetically by ID
+    for (const category of Object.keys(byCategory)) {
+      byCategory[category]!.sort((a, b) => a.id.localeCompare(b.id));
+    }
+
+    // Collect all tags
+    const tagCounts: Record<string, number> = {};
+    for (const note of notes) {
+      for (const tag of note.tags) {
+        tagCounts[tag] = (tagCounts[tag] ?? 0) + 1;
+      }
+    }
+
+    const today = getTodayDate();
+    const totalNotes = notes.length;
+
+    // Generate index content
+    const indexContent = `---
+id: knowledge-index
+title: Knowledge Index
+created: ${today}
+updated: ${today}
+---
+
+# Knowledge Index
+
+Master index of all knowledge notes. **Keep this file updated when adding or removing notes.**
+
+## Quick Stats
+
+- Total Notes: ${totalNotes}
+- Last Updated: ${today}
+
+## System Files
+
+| File | Description |
+|------|-------------|
+| [README.md](README.md) | Purpose, guidelines, and templates |
+| [index.md](index.md) | This file - master index |
+| [instructions.md](instructions.md) | AI agent workflow instructions |
+
+---
+
+## Projects
+
+Project-specific knowledge and insights.
+
+| ID | Title | Tags | Updated |
+|----|-------|------|---------|
+${this.formatCategoryTable(byCategory["projects"]!)}
+
+---
+
+## Patterns
+
+Reusable patterns and solutions.
+
+| ID | Title | Tags | Updated |
+|----|-------|------|---------|
+${this.formatCategoryTable(byCategory["patterns"]!)}
+
+---
+
+## Tools
+
+Tool and technology notes.
+
+| ID | Title | Tags | Updated |
+|----|-------|------|---------|
+${this.formatCategoryTable(byCategory["tools"]!)}
+
+---
+
+## Gotchas
+
+Common pitfalls and their solutions.
+
+| ID | Title | Tags | Updated |
+|----|-------|------|---------|
+${this.formatCategoryTable(byCategory["gotchas"]!)}
+
+---
+
+## Decisions
+
+Key decisions and their rationale.
+
+| ID | Title | Tags | Updated |
+|----|-------|------|---------|
+${this.formatCategoryTable(byCategory["decisions"]!)}
+
+---
+
+## Tags Index
+
+Quick reference of all tags in use:
+
+${this.formatTagsIndex(tagCounts)}`;
+
+    const indexPath = join(this.knowledgePath, "index.md");
+    await writeFile(indexPath, indexContent, "utf-8");
+  }
+
+  /**
+   * Format a category's notes as a markdown table
+   */
+  private formatCategoryTable(notes: KnowledgeNote[]): string {
+    if (notes.length === 0) {
+      return "| - | No notes yet | - | - |";
+    }
+
+    return notes
+      .map((note) => {
+        const tags = note.tags.join(", ") || "-";
+        return `| [${note.id}](${note.path}) | ${note.title} | ${tags} | ${note.updated} |`;
+      })
+      .join("\n");
+  }
+
+  /**
+   * Format the tags index section
+   */
+  private formatTagsIndex(tagCounts: Record<string, number>): string {
+    const sortedTags = Object.entries(tagCounts).sort(([a], [b]) =>
+      a.localeCompare(b)
+    );
+
+    if (sortedTags.length === 0) {
+      return "No tags yet.";
+    }
+
+    return sortedTags
+      .map(([tag, count]) => `- \`${tag}\` (${count} note${count > 1 ? "s" : ""})`)
+      .join("\n");
+  }
+
+  /**
+   * Get all unique tags across all notes
+   */
+  async getAllTags(): Promise<string[]> {
+    await this.initialize();
+
+    const tags = new Set<string>();
+    for (const note of this.cache.values()) {
+      for (const tag of note.tags) {
+        tags.add(tag);
+      }
+    }
+
+    return Array.from(tags).sort();
+  }
+
+  /**
+   * Get all categories with note counts
+   */
+  async getCategoryCounts(): Promise<Record<KnowledgeCategory, number>> {
+    await this.initialize();
+
+    const counts: Record<KnowledgeCategory, number> = {
+      projects: 0,
+      patterns: 0,
+      tools: 0,
+      gotchas: 0,
+      decisions: 0,
+      root: 0,
+    };
+
+    for (const note of this.cache.values()) {
+      counts[note.category]++;
+    }
+
+    return counts;
+  }
+}

package/src/services/markdown.ts

@@ -0,0 +1,155 @@
+/**
+ * Markdown parsing utilities for Gyrus
+ * Handles frontmatter extraction and serialization
+ */
+
+import matter from "gray-matter";
+import type {
+  KnowledgeNote,
+  KnowledgeFrontmatter,
+  KnowledgeCategory,
+} from "../types/index.ts";
+
+/**
+ * Get today's date in YYYY-MM-DD format
+ */
+export function getTodayDate(): string {
+  const now = new Date();
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Get category folder name
+ */
+export function getCategoryFolder(
+  category: Exclude<KnowledgeCategory, "root">
+): string {
+  return category;
+}
+
+/**
+ * Determine category from file path
+ */
+export function getCategoryFromPath(path: string): KnowledgeCategory {
+  const parts = path.split("/");
+  if (parts.length < 2) {
+    return "root";
+  }
+
+  const folder = parts[0];
+  const validCategories: KnowledgeCategory[] = [
+    "projects",
+    "patterns",
+    "tools",
+    "gotchas",
+    "decisions",
+  ];
+
+  if (validCategories.includes(folder as KnowledgeCategory)) {
+    return folder as KnowledgeCategory;
+  }
+
+  return "root";
+}
+
+/**
+ * Parse a markdown file with YAML frontmatter into a KnowledgeNote
+ * Returns null if parsing fails or required fields are missing
+ */
+export function parseMarkdown(
+  content: string,
+  relativePath: string
+): KnowledgeNote | null {
+  try {
+    const { data, content: markdownContent } = matter(content);
+    const frontmatter = data as Partial<KnowledgeFrontmatter>;
+
+    // Validate required fields
+    if (
+      !frontmatter.id ||
+      !frontmatter.title ||
+      !frontmatter.created ||
+      !frontmatter.updated
+    ) {
+      return null;
+    }
+
+    const category = getCategoryFromPath(relativePath);
+
+    return {
+      id: frontmatter.id,
+      title: frontmatter.title,
+      created: String(frontmatter.created),
+      updated: String(frontmatter.updated),
+      tags: frontmatter.tags ?? [],
+      related: frontmatter.related ?? [],
+      description: frontmatter.description,
+      content: markdownContent.trim(),
+      path: relativePath,
+      category,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Serialize a KnowledgeNote back to markdown with frontmatter
+ */
+export function serializeMarkdown(note: KnowledgeNote): string {
+  const frontmatter: KnowledgeFrontmatter = {
+    id: note.id,
+    title: note.title,
+    created: note.created,
+    updated: note.updated,
+  };
+
+  // Only include optional fields if they have values
+  if (note.tags.length > 0) {
+    frontmatter.tags = note.tags;
+  }
+  if (note.related.length > 0) {
+    frontmatter.related = note.related;
+  }
+  if (note.description) {
+    frontmatter.description = note.description;
+  }
+
+  return matter.stringify(note.content, frontmatter);
+}
+
+/**
+ * Create markdown content for a new note
+ */
+export function createMarkdownContent(options: {
+  id: string;
+  title: string;
+  content: string;
+  created: string;
+  updated: string;
+  tags?: string[];
+  related?: string[];
+  description?: string;
+}): string {
+  const frontmatter: Record<string, unknown> = {
+    id: options.id,
+    title: options.title,
+    created: options.created,
+    updated: options.updated,
+  };
+
+  if (options.tags && options.tags.length > 0) {
+    frontmatter.tags = options.tags;
+  }
+  if (options.related && options.related.length > 0) {
+    frontmatter.related = options.related;
+  }
+  if (options.description) {
+    frontmatter.description = options.description;
+  }
+
+  return matter.stringify(options.content, frontmatter);
+}