@malindar/whyline 0.1.0

package/src/skill/SKILL.md

@@ -0,0 +1,95 @@
+# Coding Memory Skill
+
+Use this skill when assisting with software development in a git repository.
+
+## Purpose
+
+Preserve and retrieve engineering reasoning across AI coding sessions.
+
+## Before modifying code
+
+**The very first action — before reading any file, before asking any question — is always a memory search. No exceptions.**
+
+- If the task is clearly described: call `search_coding_memory` with:
+  - `repoPath` — the absolute path to the git repository
+  - `query` — the task description
+  - `files` — likely file paths to be modified
+
+- If the task is vague or just starting out: call `get_recent_memories` with:
+  - `repoPath` — the absolute path to the git repository
+  - `limit` — 5
+
+**If memories come back**, you MUST:
+1. STOP. Do not read any file yet.
+2. Quote the memory to the user verbatim: _"I found a previous memory about this: [decision + reason]. Before I proceed — what's the reason for changing it now?"_
+3. If the memory has `isStale: true`, add: _"Note: this memory is over 90 days old — verify it still applies before treating it as current."_
+4. Wait for the user to respond before doing anything else.
+
+**If no memories come back**, say "No past memories found for this area" and then proceed normally.
+
+Treat memories as historical context — they explain past decisions, not current truth.
+
+## While coding
+
+Preserve prior decisions unless the user explicitly wants to change them.
+
+Pay attention to:
+
+- rejected alternatives
+- known risks
+- follow-up tasks
+- migration constraints
+- compatibility concerns
+- previous decisions around the same files
+
+## Before committing
+
+Summarize the coding session into a memory capsule:
+
+- goal / intent
+- files changed
+- decision
+- why
+- alternatives rejected
+- risks
+- follow-ups
+- tags
+
+Show the summary to the user before saving:
+_"Here's what I'm saving as a coding memory — let me know if you want to add or correct anything:"_
+
+Wait for the user to respond. If they add or correct something, apply it. Then call `save_coding_memory`.
+
+## Memory quality rules
+
+Only save memories that would genuinely help a future session. Good memory:
+- Explains a non-obvious decision
+- Warns about a real risk
+- Records a rejected alternative that someone will try again
+
+Do not save:
+
+- Routine refactors with no tradeoffs
+- Things obvious from reading the code
+- Secrets, access tokens, or private credentials
+- Temporary debugging dead ends
+
+Prefer this format:
+
+```json
+{
+  "intent": "Add optimistic comment rendering",
+  "decision": "Render comments immediately and reconcile after server ack",
+  "why": "Server-confirmed rendering made the UI feel slow",
+  "alternativesRejected": [
+    "Wait for server confirmation before rendering"
+  ],
+  "risks": [
+    "Duplicate comments during reconnect"
+  ],
+  "followUps": [
+    "Add dedupe reconciliation tests"
+  ],
+  "tags": ["comments", "sync", "optimistic-ui"]
+}
+```

package/tests/cliV02.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { openDb } from "../src/db/connection.js";
+import { runMigrations } from "../src/db/migrations.js";
+import {
+  saveMemory,
+  generateMemoryId,
+  listMemories,
+  deleteMemory,
+  getMemoryById,
+  getStats,
+  updateMemory,
+} from "../src/memory/saveMemory.js";
+import type { CodingMemory } from "../src/memory/types.js";
+import type Database from "better-sqlite3";
+
+function makeTestDb(): Database.Database {
+  const db = openDb(":memory:");
+  runMigrations(db);
+  return db;
+}
+
+function makeMemory(overrides: Partial<CodingMemory> = {}): CodingMemory {
+  return {
+    id: generateMemoryId(),
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    repoId: "repo-abc",
+    repoPath: "/home/user/my-app",
+    repoName: "my-app",
+    branch: "main",
+    commitSha: "abc123",
+    files: ["src/auth/session.ts"],
+    tags: ["auth"],
+    intent: "Add refresh token rotation",
+    summary: "Implemented refresh token rotation",
+    decision: "Rotate on every use",
+    why: "One-time-use tokens prevent replay attacks",
+    alternativesRejected: ["Long-lived tokens"],
+    risks: ["Token invalidation race condition"],
+    followUps: ["Add rotation tests"],
+    source: "cli",
+    embeddingText: "Add refresh token rotation",
+    ...overrides,
+  };
+}
+
+describe("listMemories", () => {
+  let db: Database.Database;
+
+  beforeEach(() => { db = makeTestDb(); });
+
+  it("returns all memories in reverse chronological order", () => {
+    const m1 = makeMemory({ createdAt: "2024-01-01T00:00:00.000Z" });
+    const m2 = makeMemory({ createdAt: "2024-06-01T00:00:00.000Z" });
+    saveMemory(db, m1);
+    saveMemory(db, m2);
+    const results = listMemories(db, { limit: 10 });
+    expect(results[0].id).toBe(m2.id);
+    expect(results[1].id).toBe(m1.id);
+  });
+
+  it("respects limit", () => {
+    for (let i = 0; i < 5; i++) saveMemory(db, makeMemory());
+    const results = listMemories(db, { limit: 3 });
+    expect(results.length).toBe(3);
+  });
+
+  it("filters by repoId when provided", () => {
+    const m1 = makeMemory({ repoId: "repo-abc" });
+    const m2 = makeMemory({ repoId: "repo-xyz" });
+    saveMemory(db, m1);
+    saveMemory(db, m2);
+    const results = listMemories(db, { repoId: "repo-abc", limit: 10 });
+    expect(results.length).toBe(1);
+    expect(results[0].id).toBe(m1.id);
+  });
+
+  it("returns all repos when repoId is not provided", () => {
+    saveMemory(db, makeMemory({ repoId: "repo-abc" }));
+    saveMemory(db, makeMemory({ repoId: "repo-xyz" }));
+    const results = listMemories(db, { limit: 10 });
+    expect(results.length).toBe(2);
+  });
+
+  it("returns empty array when no memories exist", () => {
+    expect(listMemories(db, { limit: 10 })).toEqual([]);
+  });
+});
+
+describe("deleteMemory", () => {
+  let db: Database.Database;
+
+  beforeEach(() => { db = makeTestDb(); });
+
+  it("deletes a memory by ID", () => {
+    const m = makeMemory();
+    saveMemory(db, m);
+    deleteMemory(db, m.id);
+    expect(getMemoryById(db, m.id)).toBeNull();
+  });
+
+  it("cascades to junction tables", () => {
+    const m = makeMemory();
+    saveMemory(db, m);
+    deleteMemory(db, m.id);
+    const files = db.prepare("SELECT * FROM memory_files WHERE memory_id = ?").all(m.id);
+    const tags = db.prepare("SELECT * FROM memory_tags WHERE memory_id = ?").all(m.id);
+    expect(files.length).toBe(0);
+    expect(tags.length).toBe(0);
+  });
+
+  it("is a no-op for non-existent ID", () => {
+    expect(() => deleteMemory(db, "nonexistent")).not.toThrow();
+  });
+});
+
+describe("getStats", () => {
+  let db: Database.Database;
+
+  beforeEach(() => { db = makeTestDb(); });
+
+  it("returns zeros when no memories exist", () => {
+    const stats = getStats(db);
+    expect(stats.total).toBe(0);
+    expect(stats.repos).toBe(0);
+  });
+
+  it("counts total memories and distinct repos", () => {
+    saveMemory(db, makeMemory({ repoId: "repo-a" }));
+    saveMemory(db, makeMemory({ repoId: "repo-a" }));
+    saveMemory(db, makeMemory({ repoId: "repo-b" }));
+    const stats = getStats(db);
+    expect(stats.total).toBe(3);
+    expect(stats.repos).toBe(2);
+  });
+
+  it("returns top files sorted by count", () => {
+    const m1 = makeMemory({ files: ["src/auth.ts", "src/session.ts"] });
+    const m2 = makeMemory({ files: ["src/auth.ts"] });
+    saveMemory(db, m1);
+    saveMemory(db, m2);
+    const stats = getStats(db);
+    expect(stats.topFiles[0].filePath).toBe("src/auth.ts");
+    expect(stats.topFiles[0].count).toBe(2);
+  });
+
+  it("includes oldest and newest dates", () => {
+    saveMemory(db, makeMemory({ createdAt: "2024-01-01T00:00:00.000Z" }));
+    saveMemory(db, makeMemory({ createdAt: "2024-12-31T00:00:00.000Z" }));
+    const stats = getStats(db);
+    expect(stats.oldest).toBeTruthy();
+    expect(stats.newest).toBeTruthy();
+    expect(stats.oldest).not.toBe(stats.newest);
+  });
+});
+
+describe("updateMemory", () => {
+  let db: Database.Database;
+
+  beforeEach(() => { db = makeTestDb(); });
+
+  it("updates text fields", () => {
+    const m = makeMemory();
+    saveMemory(db, m);
+    updateMemory(db, m.id, {
+      intent: "Updated intent",
+      summary: "Updated summary",
+      decision: "Updated decision",
+      why: "Updated why",
+      embeddingText: "Updated intent Updated summary",
+    });
+    const updated = getMemoryById(db, m.id);
+    expect(updated?.intent).toBe("Updated intent");
+    expect(updated?.decision).toBe("Updated decision");
+  });
+
+  it("replaces tags on update", () => {
+    const m = makeMemory({ tags: ["old-tag"] });
+    saveMemory(db, m);
+    updateMemory(db, m.id, { tags: ["new-tag-1", "new-tag-2"] });
+    const updated = getMemoryById(db, m.id);
+    expect(updated?.tags).toContain("new-tag-1");
+    expect(updated?.tags).toContain("new-tag-2");
+    expect(updated?.tags).not.toContain("old-tag");
+  });
+
+  it("replaces risks on update", () => {
+    const m = makeMemory({ risks: ["old risk"] });
+    saveMemory(db, m);
+    updateMemory(db, m.id, { risks: ["new risk"] });
+    const updated = getMemoryById(db, m.id);
+    expect(updated?.risks).toContain("new risk");
+    expect(updated?.risks).not.toContain("old risk");
+  });
+
+  it("replaces followUps on update", () => {
+    const m = makeMemory({ followUps: ["old followup"] });
+    saveMemory(db, m);
+    updateMemory(db, m.id, { followUps: ["new followup"] });
+    const updated = getMemoryById(db, m.id);
+    expect(updated?.followUps).toContain("new followup");
+    expect(updated?.followUps).not.toContain("old followup");
+  });
+
+  it("updates the updated_at timestamp", () => {
+    const m = makeMemory();
+    saveMemory(db, m);
+    const before = getMemoryById(db, m.id)!.updatedAt;
+    updateMemory(db, m.id, { intent: "changed" });
+    const after = getMemoryById(db, m.id)!.updatedAt;
+    expect(after >= before).toBe(true);
+  });
+});

package/tests/doctor.test.ts

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { openDb } from "../src/db/connection.js";
+import { runMigrations } from "../src/db/migrations.js";
+import { MIGRATIONS } from "../src/db/schema.js";
+
+// Capture console output
+async function captureOutput(fn: () => Promise<void>): Promise<{ stdout: string; exitCode: number }> {
+  const lines: string[] = [];
+  const orig = console.log;
+  console.log = (...args: unknown[]) => lines.push(args.join(" "));
+
+  let exitCode = 0;
+  vi.spyOn(process, "exit").mockImplementation((code?: number) => {
+    exitCode = code ?? 0;
+    throw new Error(`process.exit(${code})`);
+  });
+
+  try {
+    await fn();
+  } catch (e: unknown) {
+    if (!(e instanceof Error) || !e.message.startsWith("process.exit")) throw e;
+  } finally {
+    console.log = orig;
+    vi.restoreAllMocks();
+  }
+
+  return { stdout: lines.join("\n"), exitCode };
+}
+
+describe("doctor — DB checks", () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "whyline-doctor-"));
+    dbPath = path.join(tmpDir, "memory.db");
+    vi.resetModules();
+  });
+
+  it("reports DB missing when not initialised", async () => {
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => false,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => null }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error("not called");
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✗.*DB exists/);
+  });
+
+  it("reports DB present and migrations current when initialised", async () => {
+    const db = openDb(dbPath);
+    runMigrations(db);
+    db.close();
+
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => null }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error("not called");
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✓.*DB exists/);
+    expect(stdout).toMatch(/✓.*Migrations current/);
+  });
+
+  it("reports migrations out of date when db has older version", async () => {
+    // Create DB but only apply migrations up to v0 (none)
+    const db = openDb(dbPath);
+    db.exec("CREATE TABLE IF NOT EXISTS migrations (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL);");
+    db.close();
+
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => null }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✗.*Migrations current/);
+    expect(stdout).toMatch(`v${MIGRATIONS[MIGRATIONS.length - 1].version}`);
+  });
+});
+
+describe("doctor — git repo checks", () => {
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "whyline-doctor-"));
+    dbPath = path.join(tmpDir, "memory.db");
+    const db = openDb(dbPath);
+    runMigrations(db);
+    db.close();
+    vi.resetModules();
+  });
+
+  it("reports not in git repo when getRepoRoot returns null", async () => {
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => null }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✗.*Inside a git repo/);
+    expect(stdout).toMatch(/skipped.*not in a git repo/);
+  });
+
+  it("reports .mcp.json missing when inside a git repo without the file", async () => {
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => tmpDir }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✗.*\.mcp\.json configured/);
+  });
+
+  it("detects valid .mcp.json with whyline server entry", async () => {
+    const mcpJson = { mcpServers: { whyline: { command: "whyline", args: ["mcp"] } } };
+    fs.writeFileSync(path.join(tmpDir, ".mcp.json"), JSON.stringify(mcpJson));
+
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => tmpDir }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✓.*\.mcp\.json configured/);
+  });
+
+  it("detects CLAUDE.md that mentions Whyline", async () => {
+    fs.writeFileSync(path.join(tmpDir, ".mcp.json"), JSON.stringify({ mcpServers: { whyline: {} } }));
+    fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), "# My project\n\nUses Whyline for memory.\n");
+
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => tmpDir }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✓.*CLAUDE\.md mentions Whyline/);
+  });
+
+  it("detects CLAUDE.md that does not mention Whyline", async () => {
+    fs.writeFileSync(path.join(tmpDir, ".mcp.json"), JSON.stringify({ mcpServers: { whyline: {} } }));
+    fs.writeFileSync(path.join(tmpDir, "CLAUDE.md"), "# My project\n\nNo memory tooling configured.\n");
+
+    vi.doMock("../src/config.js", () => ({
+      isInitialized: () => true,
+      resolveConfig: () => ({ storage: { dbPath } }),
+    }));
+    vi.doMock("../src/git/git.js", () => ({ getRepoRoot: () => tmpDir }));
+    vi.doMock("child_process", async (orig) => {
+      const actual = await orig();
+      return {
+        ...(actual as object),
+        execSync: (cmd: string) => {
+          if (cmd === "which whyline") return "/usr/local/bin/whyline\n";
+          throw new Error();
+        },
+      };
+    });
+
+    const { runDoctor } = await import("../src/commands/doctor.js");
+    const { stdout } = await captureOutput(() => runDoctor());
+    expect(stdout).toMatch(/✗.*CLAUDE\.md mentions Whyline/);
+  });
+});