coding-friend-cli 1.16.0 → 1.17.0

package/lib/cf-memory/src/backends/markdown.ts

@@ -0,0 +1,318 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import type { MemoryBackend } from "../lib/backend.js";
+import {
+  CATEGORY_TO_TYPE,
+  MEMORY_CATEGORIES,
+  makeExcerpt,
+  type ListInput,
+  type Memory,
+  type MemoryFrontmatter,
+  type MemoryMeta,
+  type MemoryStats,
+  type MemoryType,
+  type SearchInput,
+  type SearchResult,
+  type StoreInput,
+  type UpdateInput,
+} from "../lib/types.js";
+
+/**
+ * Validate that a resolved path stays within docsDir to prevent path traversal.
+ */
+function safePath(docsDir: string, ...segments: string[]): string | null {
+  const resolved = path.resolve(docsDir, ...segments);
+  if (
+    !resolved.startsWith(path.resolve(docsDir) + path.sep) &&
+    resolved !== path.resolve(docsDir)
+  ) {
+    return null;
+  }
+  return resolved;
+}
+
+function slugify(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+function parseFrontmatter(
+  raw: matter.GrayMatterFile<string>,
+  category: string,
+): MemoryFrontmatter {
+  const d = raw.data;
+  return {
+    title: String(d.title ?? "Untitled"),
+    description: String(d.description ?? ""),
+    type: (d.type as MemoryType) ?? CATEGORY_TO_TYPE[category] ?? "fact",
+    tags: Array.isArray(d.tags) ? d.tags.map(String) : [],
+    importance: Number(d.importance ?? 3),
+    created: String(d.created ?? ""),
+    updated: String(d.updated ?? ""),
+    source: String(d.source ?? "conversation"),
+  };
+}
+
+function today(): string {
+  return new Date().toISOString().split("T")[0];
+}
+
+export class MarkdownBackend implements MemoryBackend {
+  constructor(private docsDir: string) {}
+
+  private getCategories(): string[] {
+    if (!fs.existsSync(this.docsDir)) return [];
+    return fs
+      .readdirSync(this.docsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+      .map((d) => d.name);
+  }
+
+  getAllMeta(): MemoryMeta[] {
+    const metas: MemoryMeta[] = [];
+
+    for (const category of this.getCategories()) {
+      const catPath = path.join(this.docsDir, category);
+      const files = fs
+        .readdirSync(catPath)
+        .filter((f) => f.endsWith(".md") && f !== "README.md");
+
+      for (const file of files) {
+        const filePath = path.join(catPath, file);
+        const raw = matter(fs.readFileSync(filePath, "utf-8"));
+        const frontmatter = parseFrontmatter(raw, category);
+        const slug = path.basename(file, ".md");
+
+        metas.push({
+          id: `${category}/${slug}`,
+          slug,
+          category,
+          frontmatter,
+          excerpt: makeExcerpt(raw.content),
+        });
+      }
+    }
+
+    return metas.sort(
+      (a, b) =>
+        new Date(b.frontmatter.updated || b.frontmatter.created).getTime() -
+        new Date(a.frontmatter.updated || a.frontmatter.created).getTime(),
+    );
+  }
+
+  async store(input: StoreInput): Promise<Memory> {
+    const category = MEMORY_CATEGORIES[input.type];
+    const catDir = path.join(this.docsDir, category);
+    if (!fs.existsSync(catDir)) {
+      fs.mkdirSync(catDir, { recursive: true });
+    }
+
+    let slug = slugify(input.title);
+    const filePath = path.join(catDir, `${slug}.md`);
+
+    // Handle duplicate slugs
+    if (fs.existsSync(filePath)) {
+      slug = `${slug}-${Date.now()}`;
+    }
+
+    const finalPath = path.join(catDir, `${slug}.md`);
+    const now = today();
+
+    const frontmatter: MemoryFrontmatter = {
+      title: input.title,
+      description: input.description,
+      type: input.type,
+      tags: input.tags,
+      importance: input.importance ?? 3,
+      created: now,
+      updated: now,
+      source: input.source ?? "conversation",
+    };
+
+    const doc = matter.stringify(
+      input.content,
+      frontmatter as unknown as Record<string, unknown>,
+    );
+    fs.writeFileSync(finalPath, doc, "utf-8");
+
+    return {
+      id: `${category}/${slug}`,
+      slug,
+      category,
+      frontmatter,
+      content: input.content,
+    };
+  }
+
+  async search(input: SearchInput): Promise<SearchResult[]> {
+    const query = input.query.toLowerCase();
+    let metas = this.getAllMeta();
+
+    if (input.type) {
+      metas = metas.filter((m) => m.frontmatter.type === input.type);
+    }
+
+    if (input.tags && input.tags.length > 0) {
+      const lowerTags = input.tags.map((t) => t.toLowerCase());
+      metas = metas.filter((m) =>
+        lowerTags.some((lt) =>
+          m.frontmatter.tags.some((t) => t.toLowerCase() === lt),
+        ),
+      );
+    }
+
+    const results: SearchResult[] = [];
+
+    for (const meta of metas) {
+      const matchedOn: string[] = [];
+      let score = 0;
+
+      // Title match (highest weight)
+      if (meta.frontmatter.title.toLowerCase().includes(query)) {
+        matchedOn.push("title");
+        score += 10;
+      }
+
+      // Description match
+      if (meta.frontmatter.description.toLowerCase().includes(query)) {
+        matchedOn.push("description");
+        score += 8;
+      }
+
+      // Tag match
+      if (meta.frontmatter.tags.some((t) => t.toLowerCase().includes(query))) {
+        matchedOn.push("tags");
+        score += 6;
+      }
+
+      // Content match (full file read — heavier)
+      if (matchedOn.length === 0) {
+        const full = await this.retrieve(meta.id);
+        if (full && full.content.toLowerCase().includes(query)) {
+          matchedOn.push("content");
+          score += 2;
+        }
+      }
+
+      if (matchedOn.length > 0) {
+        results.push({ memory: meta, score, matchedOn });
+      }
+    }
+
+    results.sort((a, b) => b.score - a.score);
+
+    const limit = input.limit ?? 10;
+    return results.slice(0, limit);
+  }
+
+  retrieveSync(id: string): Memory | null {
+    const [category, slug] = id.split("/");
+    if (!category || !slug) return null;
+
+    const filePath = safePath(this.docsDir, category, `${slug}.md`);
+    if (!filePath || !fs.existsSync(filePath)) return null;
+
+    const raw = matter(fs.readFileSync(filePath, "utf-8"));
+    const frontmatter = parseFrontmatter(raw, category);
+
+    return {
+      id,
+      slug,
+      category,
+      frontmatter,
+      content: raw.content,
+    };
+  }
+
+  async retrieve(id: string): Promise<Memory | null> {
+    return this.retrieveSync(id);
+  }
+
+  async list(input: ListInput): Promise<MemoryMeta[]> {
+    let metas = this.getAllMeta();
+
+    if (input.type) {
+      metas = metas.filter((m) => m.frontmatter.type === input.type);
+    }
+
+    if (input.category) {
+      metas = metas.filter((m) => m.category === input.category);
+    }
+
+    const limit = input.limit ?? 50;
+    return metas.slice(0, limit);
+  }
+
+  async update(input: UpdateInput): Promise<Memory | null> {
+    const [category, slug] = input.id.split("/");
+    if (!category || !slug) return null;
+
+    const filePath = safePath(this.docsDir, category, `${slug}.md`);
+    if (!filePath || !fs.existsSync(filePath)) return null;
+
+    const raw = matter(fs.readFileSync(filePath, "utf-8"));
+    const now = today();
+
+    if (input.title) raw.data.title = input.title;
+    if (input.description) raw.data.description = input.description;
+    if (input.tags) {
+      raw.data.tags = [...new Set([...(raw.data.tags || []), ...input.tags])];
+    }
+    if (input.importance !== undefined) raw.data.importance = input.importance;
+    raw.data.updated = now;
+
+    const newContent = input.content
+      ? raw.content + "\n\n" + input.content
+      : raw.content;
+
+    fs.writeFileSync(filePath, matter.stringify(newContent, raw.data), "utf-8");
+
+    const frontmatter = parseFrontmatter(
+      matter(fs.readFileSync(filePath, "utf-8")),
+      category,
+    );
+
+    return {
+      id: input.id,
+      slug,
+      category,
+      frontmatter,
+      content: newContent,
+    };
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const [category, slug] = id.split("/");
+    if (!category || !slug) return false;
+
+    const filePath = safePath(this.docsDir, category, `${slug}.md`);
+    if (!filePath || !fs.existsSync(filePath)) return false;
+
+    fs.unlinkSync(filePath);
+    return true;
+  }
+
+  async stats(): Promise<MemoryStats> {
+    const metas = this.getAllMeta();
+    const byCategory: Record<string, number> = {};
+    const byType: Record<string, number> = {};
+
+    for (const meta of metas) {
+      byCategory[meta.category] = (byCategory[meta.category] ?? 0) + 1;
+      byType[meta.frontmatter.type] = (byType[meta.frontmatter.type] ?? 0) + 1;
+    }
+
+    return {
+      total: metas.length,
+      byCategory,
+      byType,
+    };
+  }
+
+  async close(): Promise<void> {
+    // No-op for markdown backend
+  }
+}

package/lib/cf-memory/src/backends/minisearch.ts

@@ -0,0 +1,203 @@
+import MiniSearch from "minisearch";
+import { MarkdownBackend } from "./markdown.js";
+import type { MemoryBackend } from "../lib/backend.js";
+import type {
+  ListInput,
+  Memory,
+  MemoryMeta,
+  MemoryStats,
+  SearchInput,
+  SearchResult,
+  StoreInput,
+  UpdateInput,
+} from "../lib/types.js";
+
+interface IndexedDoc {
+  id: string;
+  title: string;
+  description: string;
+  tags: string;
+  content: string;
+  type: string;
+  category: string;
+  importance: number;
+}
+
+export class MiniSearchBackend implements MemoryBackend {
+  private markdown: MarkdownBackend;
+  private index: MiniSearch<IndexedDoc>;
+
+  constructor(docsDir: string) {
+    this.markdown = new MarkdownBackend(docsDir);
+    this.index = this.createIndex();
+    this.buildIndex();
+  }
+
+  private createIndex(): MiniSearch<IndexedDoc> {
+    return new MiniSearch<IndexedDoc>({
+      fields: ["title", "description", "tags", "content"],
+      storeFields: [
+        "id",
+        "title",
+        "description",
+        "tags",
+        "type",
+        "category",
+        "importance",
+      ],
+      searchOptions: {
+        boost: { title: 10, tags: 6, description: 4, content: 1 },
+        fuzzy: 0.2,
+        prefix: true,
+      },
+    });
+  }
+
+  private buildIndex(): void {
+    this.index.removeAll();
+    const metas = this.markdown.getAllMeta();
+    for (const meta of metas) {
+      const full = this.markdown.retrieveSync(meta.id);
+      this.index.add({
+        id: meta.id,
+        title: meta.frontmatter.title,
+        description: meta.frontmatter.description,
+        tags: meta.frontmatter.tags.join(" "),
+        content: full?.content ?? "",
+        type: meta.frontmatter.type,
+        category: meta.category,
+        importance: meta.frontmatter.importance,
+      });
+    }
+  }
+
+  /**
+   * Rebuild the in-memory index from markdown files.
+   */
+  async rebuild(): Promise<void> {
+    this.index = this.createIndex();
+    this.buildIndex();
+  }
+
+  async store(input: StoreInput): Promise<Memory> {
+    const memory = await this.markdown.store(input);
+    // Add to index
+    this.index.add({
+      id: memory.id,
+      title: memory.frontmatter.title,
+      description: memory.frontmatter.description,
+      tags: memory.frontmatter.tags.join(" "),
+      content: memory.content,
+      type: memory.frontmatter.type,
+      category: memory.category,
+      importance: memory.frontmatter.importance,
+    });
+    return memory;
+  }
+
+  async search(input: SearchInput): Promise<SearchResult[]> {
+    const limit = input.limit ?? 10;
+    const query = input.query;
+
+    if (!query.trim()) {
+      // Empty query — fall back to list
+      const metas = await this.list({
+        type: input.type,
+        limit,
+      });
+      return metas.map((m) => ({
+        memory: m,
+        score: 0,
+        matchedOn: [],
+      }));
+    }
+
+    let results = this.index.search(query);
+
+    // Filter by type
+    if (input.type) {
+      results = results.filter((r) => {
+        const stored = r as unknown as { type: string };
+        return stored.type === input.type;
+      });
+    }
+
+    // Filter by tags
+    if (input.tags && input.tags.length > 0) {
+      const lowerTags = input.tags.map((t) => t.toLowerCase());
+      results = results.filter((r) => {
+        const stored = r as unknown as { tags: string };
+        const docTags = stored.tags.toLowerCase().split(" ");
+        return lowerTags.some((lt) => docTags.some((dt) => dt.includes(lt)));
+      });
+    }
+
+    const limited = results.slice(0, limit);
+
+    // Convert to SearchResult format
+    const output: SearchResult[] = [];
+    for (const r of limited) {
+      const memory = await this.markdown.retrieve(r.id);
+      if (!memory) continue;
+
+      const matchedOn = Object.keys(r.match);
+      const meta: MemoryMeta = {
+        id: memory.id,
+        slug: memory.slug,
+        category: memory.category,
+        frontmatter: memory.frontmatter,
+        excerpt: memory.content.slice(0, 160),
+      };
+      output.push({
+        memory: meta,
+        score: r.score,
+        matchedOn,
+      });
+    }
+
+    return output;
+  }
+
+  async retrieve(id: string): Promise<Memory | null> {
+    return this.markdown.retrieve(id);
+  }
+
+  async list(input: ListInput): Promise<MemoryMeta[]> {
+    return this.markdown.list(input);
+  }
+
+  async update(input: UpdateInput): Promise<Memory | null> {
+    const memory = await this.markdown.update(input);
+    if (memory) {
+      // Re-index: remove old, add new
+      this.index.discard(input.id);
+      this.index.add({
+        id: memory.id,
+        title: memory.frontmatter.title,
+        description: memory.frontmatter.description,
+        tags: memory.frontmatter.tags.join(" "),
+        content: memory.content,
+        type: memory.frontmatter.type,
+        category: memory.category,
+        importance: memory.frontmatter.importance,
+      });
+    }
+    return memory;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const deleted = await this.markdown.delete(id);
+    if (deleted) {
+      this.index.discard(id);
+    }
+    return deleted;
+  }
+
+  async stats(): Promise<MemoryStats> {
+    return this.markdown.stats();
+  }
+
+  async close(): Promise<void> {
+    await this.markdown.close();
+  }
+}