@aprimediet/codewalker 1.2.0 → 1.4.0

package/src/notes-cards.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from 'vitest';
+import { renderNoteCard, parseNoteCard } from './notes-cards.ts';
+import type { Note } from './types.ts';
+
+function makeNote(overrides: Partial<Note> = {}): Note {
+  return {
+    note_kind: 'glossary',
+    title: 'Idempotency Key',
+    body: 'A client-supplied key that makes a retried POST safe to replay.',
+    tags: 'api, payments',
+    related: 'createCharge, charge.ts:88-140',
+    card_path: '',
+    ...overrides,
+  };
+}
+
+describe('renderNoteCard', () => {
+  it('renders a glossary note with frontmatter head', () => {
+    const note = makeNote();
+    const md = renderNoteCard(note);
+
+    expect(md).toContain('---');
+    expect(md).toContain('note_kind: glossary');
+    expect(md).toContain('title: Idempotency Key');
+    expect(md).toContain('tags: api, payments');
+    expect(md).toContain('related: createCharge, charge.ts:88-140');
+    expect(md).toContain('summary: A client-supplied key that makes a retried POST safe to replay.');
+
+    // Body
+    expect(md).toContain('# Idempotency Key');
+    expect(md).toContain(note.body);
+  });
+
+  it('renders a decision note', () => {
+    const note = makeNote({
+      note_kind: 'decision',
+      title: 'Use SQLite over ChromaDB',
+      body: 'We chose SQLite+FTS5 because the agent can expand queries itself.',
+      tags: 'tech-decision, database',
+      related: 'docs/tech-decision.md',
+    });
+    const md = renderNoteCard(note);
+    expect(md).toContain('note_kind: decision');
+    expect(md).toContain('title: Use SQLite over ChromaDB');
+    expect(md).toContain('tags: tech-decision, database');
+    expect(md).toContain('related: docs/tech-decision.md');
+    expect(md).toContain('# Use SQLite over ChromaDB');
+    expect(md).toContain(note.body);
+  });
+
+  it('sanitizes newlines in head fields', () => {
+    const note = makeNote({
+      title: 'Multi\nline',
+    });
+
+    const md = renderNoteCard(note);
+    // title should not have raw newlines in frontmatter
+    const fmMatch = md.match(/^title: (.+)$/m);
+    expect(fmMatch).not.toBeNull();
+    expect(fmMatch![1]!).not.toContain('\n');
+  });
+
+  it('uses body first line as summary', () => {
+    const note = makeNote();
+    const md = renderNoteCard(note);
+    // The first line of body should appear as summary
+    expect(md).toContain('summary: A client-supplied key that makes a retried POST safe to replay.');
+  });
+});
+
+describe('parseNoteCard', () => {
+  it('round-trips renderNoteCard -> parseNoteCard preserving head fields', () => {
+    const note = makeNote();
+    const md = renderNoteCard(note);
+    const parsed = parseNoteCard(md);
+    expect(parsed).not.toBeNull();
+    expect(parsed!.note_kind).toBe('glossary');
+    expect(parsed!.title).toBe('Idempotency Key');
+    expect(parsed!.tags).toBe('api, payments');
+    expect(parsed!.related).toBe('createCharge, charge.ts:88-140');
+    // summary from body first line
+    expect(parsed!.summary).toBeTruthy();
+  });
+
+  it('returns null for invalid markdown', () => {
+    expect(parseNoteCard('no frontmatter')).toBeNull();
+    expect(parseNoteCard('')).toBeNull();
+  });
+
+  it('returns null for card without note_kind in frontmatter', () => {
+    const md = `---
+name: foo
+kind: function
+---
+# foo
+`;
+    expect(parseNoteCard(md)).toBeNull();
+  });
+});

package/src/notes-cards.ts

@@ -0,0 +1,92 @@
+/**
+ * Note (glossary/decision) card rendering and parsing for codewalker v1.3.
+ *
+ * PURE module — no I/O. Renders a Note into a markdown card
+ * with frontmatter head (note_kind, title, tags, related, summary) and body.
+ *
+ * Cards live at entries/glossary/<slug>.md and entries/decisions/<slug>.md.
+ */
+
+import type { Note, NoteKind } from "./types.ts";
+
+/**
+ * Render a Note (glossary term or decision) into a markdown card string.
+ *
+ * Frontmatter head includes note_kind, title, tags, related, summary.
+ * Body starts with `# <title>` and contains the full body text.
+ * Summary is the first line of the body.
+ */
+export function renderNoteCard(note: Note): string {
+  const lines: string[] = ["---"];
+
+  addNoteHeadField(lines, "note_kind", note.note_kind);
+  addNoteHeadField(lines, "title", note.title);
+  if (note.tags) addNoteHeadField(lines, "tags", note.tags);
+  if (note.related) addNoteHeadField(lines, "related", note.related);
+
+  // Summary = first line of body
+  const summary = note.body.split("\n")[0]?.trim() || note.title;
+  addNoteHeadField(lines, "summary", summary);
+
+  lines.push("---");
+  lines.push("");
+
+  // Body
+  lines.push(`# ${note.title}`);
+  lines.push("");
+
+  if (note.body) {
+    lines.push(note.body);
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Parse a note card from a markdown string.
+ * Returns null if the card is invalid or not a note card.
+ */
+export function parseNoteCard(text: string): {
+  note_kind: NoteKind;
+  title: string;
+  tags: string;
+  related: string;
+  summary: string;
+} | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("---")) return null;
+
+  const endOfFm = trimmed.indexOf("\n---", 3);
+  if (endOfFm === -1) return null;
+
+  const fmRaw = trimmed.slice(3, endOfFm).trim();
+
+  // Parse frontmatter lines into a record
+  const fm: Record<string, string> = {};
+  for (const line of fmRaw.split("\n")) {
+    const sep = line.indexOf(":");
+    if (sep > 0) {
+      const key = line.slice(0, sep).trim();
+      const value = line.slice(sep + 1).trim();
+      fm[key] = value;
+    }
+  }
+
+  const noteKind = fm["note_kind"];
+  if (noteKind !== "glossary" && noteKind !== "decision" && noteKind !== "convention") return null;
+  if (!fm["title"]) return null;
+
+  return {
+    note_kind: noteKind as NoteKind,
+    title: fm["title"] ?? "",
+    tags: fm["tags"] ?? "",
+    related: fm["related"] ?? "",
+    summary: fm["summary"] ?? "",
+  };
+}
+
+/** Add a key:value line to the frontmatter, sanitizing newlines. */
+function addNoteHeadField(lines: string[], key: string, value: string): void {
+  const safe = value.replace(/\n/g, " ").trim();
+  lines.push(`${key}: ${safe}`);
+}

package/src/notes.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { openDb, searchNotes } from './db.ts';
+import { addNote, rebuildNotesDbFromCards } from './notes.ts';
+
+describe('notes.ts', () => {
+  let tmpDir: string;
+  let glossaryDir: string;
+  let decisionsDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cw-notes-'));
+    glossaryDir = path.join(tmpDir, 'glossary');
+    decisionsDir = path.join(tmpDir, 'decisions');
+    dbPath = path.join(tmpDir, 'test.db');
+    fs.mkdirSync(glossaryDir, { recursive: true });
+    fs.mkdirSync(decisionsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('addNote', () => {
+    it('writes a glossary card and inserts a DB row', () => {
+      addNote(dbPath, {
+        note_kind: 'glossary',
+        title: 'Idempotency Key',
+        body: 'A client-supplied key that makes retries safe.',
+        tags: 'api,payments',
+        related: 'createCharge',
+        card_path: '',
+      }, glossaryDir);
+
+      // Card file exists under glossary dir
+      const files = fs.readdirSync(glossaryDir);
+      expect(files.length).toBeGreaterThan(0);
+      const cardFile = files.find((f) => f.endsWith('.md'));
+      expect(cardFile).toBeDefined();
+
+      // Card content has frontmatter
+      const cardContent = fs.readFileSync(path.join(glossaryDir, cardFile!), 'utf-8');
+      expect(cardContent).toContain('note_kind: glossary');
+      expect(cardContent).toContain('title: Idempotency Key');
+
+      // DB row exists
+      const db = openDb(dbPath);
+      const results = searchNotes(db, 'Idempotency');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.name).toBe('Idempotency Key');
+      expect(results[0]!.note_kind).toBe('glossary');
+      db.close();
+    });
+
+    it('writes a decision card under decisions dir', () => {
+      addNote(dbPath, {
+        note_kind: 'decision',
+        title: 'Use SQLite over ChromaDB',
+        body: 'Chosen for zero-infra approach.',
+        tags: 'tech-decision',
+        related: '',
+        card_path: '',
+      }, decisionsDir);
+
+      const files = fs.readdirSync(decisionsDir);
+      const cardFile = files.find((f) => f.endsWith('.md'));
+      expect(cardFile).toBeDefined();
+
+      const cardContent = fs.readFileSync(path.join(decisionsDir, cardFile!), 'utf-8');
+      expect(cardContent).toContain('note_kind: decision');
+      expect(cardContent).toContain('title: Use SQLite over ChromaDB');
+    });
+
+    it('is idempotent — re-adding same note updates in place', () => {
+      addNote(dbPath, {
+        note_kind: 'glossary', title: 'Term',
+        body: 'Version 1', tags: '', related: '',
+        card_path: '',
+      }, glossaryDir);
+
+      addNote(dbPath, {
+        note_kind: 'glossary', title: 'Term',
+        body: 'Version 2 updated', tags: 'v2', related: '',
+        card_path: '',
+      }, glossaryDir);
+
+      // Single card file
+      const files = fs.readdirSync(glossaryDir).filter((f) => f.endsWith('.md'));
+      expect(files).toHaveLength(1);
+
+      // DB has single row with updated body
+      const db = openDb(dbPath);
+      const results = searchNotes(db, '');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.summary).toContain('updated');
+      db.close();
+    });
+  });
+
+  describe('rebuildNotesDbFromCards', () => {
+    it('reconstructs DB rows from glossary + decisions cards alone', () => {
+      // Add two notes
+      addNote(dbPath, {
+        note_kind: 'glossary', title: 'Cache Stampede',
+        body: 'When many requests miss cache simultaneously.', tags: 'cache',
+        related: 'getOrCreate',
+        card_path: '',
+      }, glossaryDir);
+      addNote(dbPath, {
+        note_kind: 'decision', title: 'Use triggers for FTS',
+        body: 'FTS triggers prevent index corruption.', tags: 'sqlite',
+        related: 'db.ts',
+        card_path: '',
+      }, decisionsDir);
+
+      // Delete the DB to simulate disposable-index property
+      fs.rmSync(dbPath, { force: true });
+
+      // Rebuild from cards
+      rebuildNotesDbFromCards(dbPath, glossaryDir, decisionsDir);
+
+      // Query should find both
+      const db = openDb(dbPath);
+      const results = searchNotes(db, '');
+      expect(results).toHaveLength(2);
+
+      const glossaryHits = results.filter((r) => r.note_kind === 'glossary');
+      const decisionHits = results.filter((r) => r.note_kind === 'decision');
+      expect(glossaryHits).toHaveLength(1);
+      expect(decisionHits).toHaveLength(1);
+      expect(glossaryHits[0]!.name).toBe('Cache Stampede');
+      expect(decisionHits[0]!.name).toBe('Use triggers for FTS');
+
+      db.close();
+    });
+
+    it('handles empty directories gracefully', () => {
+      // No cards added — should not throw
+      fs.rmSync(dbPath, { force: true });
+      rebuildNotesDbFromCards(dbPath, glossaryDir, decisionsDir);
+      const db = openDb(dbPath);
+      const results = searchNotes(db, '');
+      expect(results).toHaveLength(0);
+      db.close();
+    });
+
+    it('preserves card_path in rebuilt rows', () => {
+      addNote(dbPath, {
+        note_kind: 'glossary', title: 'Idempotency Key',
+        body: 'Retry-safe POST key.', tags: '', related: '',
+        card_path: '',
+      }, glossaryDir);
+
+      // Get the card path
+      const files = fs.readdirSync(glossaryDir).filter((f) => f.endsWith('.md'));
+      const cardPath = path.join(glossaryDir, files[0]!);
+
+      fs.rmSync(dbPath, { force: true });
+      rebuildNotesDbFromCards(dbPath, glossaryDir, decisionsDir);
+
+      const db = openDb(dbPath);
+      const row = db.prepare("SELECT card_path FROM notes WHERE title = ?").get('Idempotency Key') as any;
+      expect(row).not.toBeUndefined();
+      // card_path might be absolute or relative depending on how we stored it
+      expect(row.card_path).toBeTruthy();
+      db.close();
+    });
+  });
+});

package/src/notes.ts

@@ -0,0 +1,151 @@
+/**
+ * Note orchestration for codewalker v1.3.
+ *
+ * Provides:
+ * - `addNote()`: render card → atomic write → upsertNote
+ * - `rebuildNotesDbFromCards()`: disposable-index rebuild from card files
+ *
+ * Mirrors the style of src/libs/indexer.ts (atomic write, tmp + rename, mode 0o600).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { openDb, upsertNote } from "./db.ts";
+import { renderNoteCard, parseNoteCard } from "./notes-cards.ts";
+import type { Note, NoteKind } from "./types.ts";
+
+/**
+ * Write a note: render card → atomic write → upsert DB row.
+ *
+ * The note's note_kind determines which directory to use.
+ * When `notesDir` is provided, it is used directly (backward compat).
+ * When both `glossaryDir` and `decisionsDir` are available, pass them via an options bag.
+ */
+export function addNote(
+  dbPath: string,
+  note: Note,
+  notesDir?: string,
+): void {
+  const dir = notesDir;
+  if (!dir) throw new Error("notesDir is required");
+
+  // Ensure directory exists
+  fs.mkdirSync(dir, { recursive: true });
+
+  // Generate slug from title
+  const slug = slugifyNoteTitle(note.title);
+  const cardPath = path.join(dir, `${slug}.md`);
+
+  // Render card
+  const card = renderNoteCard(note);
+
+  // Atomic write
+  const tmpPath = cardPath + ".tmp";
+  fs.writeFileSync(tmpPath, card, { encoding: "utf-8", mode: 0o600 });
+  fs.renameSync(tmpPath, cardPath);
+
+  // Upsert DB row with the actual card_path
+  const db = openDb(dbPath);
+  try {
+    upsertNote(db, {
+      ...note,
+      card_path: cardPath,
+    });
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Rebuild the notes DB tables from glossary + decisions cards alone.
+ * Demonstrates the disposable-index property: cards are the source of truth.
+ */
+export function rebuildNotesDbFromCards(
+  dbPath: string,
+  glossaryDir: string,
+  decisionsDir: string,
+  conventionsDir?: string,
+): void {
+  const db = openDb(dbPath);
+
+  try {
+    db.exec("BEGIN TRANSACTION");
+
+    // Clear existing notes
+    db.prepare("DELETE FROM notes").run();
+
+    // Process glossary cards
+    if (fs.existsSync(glossaryDir)) {
+      processCardsInDir(db, glossaryDir, "glossary");
+    }
+
+    // Process decisions cards
+    if (fs.existsSync(decisionsDir)) {
+      processCardsInDir(db, decisionsDir, "decision");
+    }
+
+    // Process conventions cards (v1.4)
+    if (conventionsDir && fs.existsSync(conventionsDir)) {
+      processCardsInDir(db, conventionsDir, "convention");
+    }
+
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  } finally {
+    db.close();
+  }
+}
+
+// ── Internal helpers ───────────────────────────────────────────
+
+function processCardsInDir(
+  db: ReturnType<typeof openDb>,
+  dir: string,
+  expectedKind: NoteKind,
+): void {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+
+    const cardPath = path.join(dir, entry.name);
+    const cardText = fs.readFileSync(cardPath, "utf-8");
+    const parsed = parseNoteCard(cardText);
+    if (!parsed) continue;
+    if (parsed.note_kind !== expectedKind) continue;
+
+    // Extract body from card
+    const body = extractNoteBody(cardText);
+
+    upsertNote(db, {
+      note_kind: parsed.note_kind,
+      title: parsed.title,
+      body,
+      tags: parsed.tags,
+      related: parsed.related,
+      card_path: cardPath,
+    });
+  }
+}
+
+/** Extract the body (after frontmatter) from a note card, stripping the # title header. */
+function extractNoteBody(cardText: string): string {
+  const trimmed = cardText.trim();
+  if (!trimmed.startsWith("---")) return "";
+
+  const endOfFm = trimmed.indexOf("\n---", 3);
+  if (endOfFm === -1) return "";
+
+  return trimmed.slice(endOfFm + 4).trim();
+}
+
+function slugifyNoteTitle(title: string): string {
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "untitled";
+}
+
+// Re-export for convenience
+export { slugifyNoteTitle };

package/src/project.test.ts

@@ -80,6 +80,21 @@ describe('project.ts', () => {
       expect(p.metaFile).toBe(path.join(p.codewalkerDir, 'meta.json'));
       expect(p.entriesDir).toBe(path.join(p.codewalkerDir, 'entries'));
       expect(p.symbolsDir).toBe(path.join(p.codewalkerDir, 'entries', 'symbols'));
+      expect(p.libsDir).toBe(path.join(p.codewalkerDir, 'entries', 'libs'));
+    });
+
+    it('exposes glossaryDir and decisionsDir paths', async () => {
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      expect(p.glossaryDir).toBe(path.join(p.codewalkerDir, 'entries', 'glossary'));
+      expect(p.decisionsDir).toBe(path.join(p.codewalkerDir, 'entries', 'decisions'));
+    });
+
+    it('exposes analysisDir and conventionsDir paths', async () => {
+      const mod = await import('./project.ts');
+      const p = mod.resolveProject(tmpDir);
+      expect(p.analysisDir).toBe(path.join(p.codewalkerDir, 'entries', 'analysis'));
+      expect(p.conventionsDir).toBe(path.join(p.codewalkerDir, 'entries', 'conventions'));
     });
   });
 
@@ -89,10 +104,15 @@ describe('project.ts', () => {
       const p = await mod.ensureProject(tmpDir);
       // marker file exists
       expect(fs.existsSync(p.markerPath)).toBe(true);
-      // codewalker dir is created
+      // codewalker dir + subdirs are created
       expect(fs.existsSync(p.codewalkerDir)).toBe(true);
       expect(fs.existsSync(p.entriesDir)).toBe(true);
       expect(fs.existsSync(p.symbolsDir)).toBe(true);
+      expect(fs.existsSync(p.libsDir)).toBe(true);
+      expect(fs.existsSync(p.glossaryDir)).toBe(true);
+      expect(fs.existsSync(p.decisionsDir)).toBe(true);
+      expect(fs.existsSync(p.analysisDir)).toBe(true);
+      expect(fs.existsSync(p.conventionsDir)).toBe(true);
       // meta.json written
       expect(fs.existsSync(p.metaFile)).toBe(true);
       // meta.json has correct shape

package/src/project.ts

@@ -31,6 +31,10 @@ export interface ProjectPaths {
   entriesDir: string;
   symbolsDir: string;
   libsDir: string;
+  glossaryDir: string;
+  decisionsDir: string;
+  analysisDir: string;
+  conventionsDir: string;
 }
 
 function piHome(): string {
@@ -125,6 +129,10 @@ function pathsForId(id: string, root: string, configDir: string, markerPath: str
     entriesDir: path.join(globalDir, "codewalker", "entries"),
     symbolsDir: path.join(globalDir, "codewalker", "entries", "symbols"),
     libsDir: path.join(globalDir, "codewalker", "entries", "libs"),
+    glossaryDir: path.join(globalDir, "codewalker", "entries", "glossary"),
+    decisionsDir: path.join(globalDir, "codewalker", "entries", "decisions"),
+    analysisDir: path.join(globalDir, "codewalker", "entries", "analysis"),
+    conventionsDir: path.join(globalDir, "codewalker", "entries", "conventions"),
   };
 }
 
@@ -166,7 +174,7 @@ export async function ensureProject(cwd: string): Promise<ProjectPaths> {
   const p = resolveProject(cwd);
   const nowISO = new Date().toISOString();
 
-  for (const dir of [p.codewalkerDir, p.entriesDir, p.symbolsDir, p.libsDir]) {
+  for (const dir of [p.codewalkerDir, p.entriesDir, p.symbolsDir, p.libsDir, p.glossaryDir, p.decisionsDir, p.analysisDir, p.conventionsDir]) {
     fs.mkdirSync(dir, { recursive: true });
   }