@drewpayment/mink 0.1.0

package/src/core/action-log.ts

@@ -0,0 +1,341 @@
+import { readFileSync } from "fs";
+import { safeAppendText, atomicWriteText } from "./fs-utils";
+import type { SessionSummary } from "../types/session";
+import type {
+  ActionLogEntry,
+  ConsolidationConfig,
+  ParsedSession,
+} from "../types/action-log";
+
+// ── Path Truncation ─────────────────────────────────────────────────────────
+
+export function truncatePath(filePath: string, maxLen: number = 60): string {
+  if (filePath.length <= maxLen) return filePath;
+  return "..." + filePath.slice(-(maxLen - 3));
+}
+
+// ── Formatting (pure, no I/O) ───────────────────────────────────────────────
+
+export function formatTime(isoTimestamp: string): string {
+  const d = new Date(isoTimestamp);
+  const hh = String(d.getUTCHours()).padStart(2, "0");
+  const mm = String(d.getUTCMinutes()).padStart(2, "0");
+  return `${hh}:${mm}`;
+}
+
+function escapeCell(text: string): string {
+  return text.replace(/\|/g, "\\|");
+}
+
+export function formatRow(entry: ActionLogEntry): string {
+  return `| ${entry.time} | ${entry.action} | ${escapeCell(entry.files)} | ${escapeCell(entry.outcome)} | ${entry.tokens} |\n`;
+}
+
+export function formatSessionHeader(isoTimestamp: string): string {
+  const d = new Date(isoTimestamp);
+  const date = d.toISOString().slice(0, 10);
+  const time = formatTime(isoTimestamp);
+  const startRow = formatRow({
+    time,
+    action: "Session start",
+    files: "\u2014",
+    outcome: "\u2014",
+    tokens: "\u2014",
+  });
+  return (
+    `\n### Session \u2014 ${date} ${time}\n\n` +
+    `| Time | Action | File(s) | Outcome | ~Tokens |\n` +
+    `| --- | --- | --- | --- | --- |\n` +
+    startRow
+  );
+}
+
+export function formatReadRow(
+  isoTimestamp: string,
+  filePath: string,
+  indexHit: boolean,
+  estimatedTokens: number
+): string {
+  return formatRow({
+    time: formatTime(isoTimestamp),
+    action: "Read",
+    files: truncatePath(filePath),
+    outcome: indexHit ? "index hit" : "index miss",
+    tokens: `~${estimatedTokens}`,
+  });
+}
+
+export function formatWriteRow(
+  isoTimestamp: string,
+  filePath: string,
+  action: "create" | "edit",
+  description: string,
+  estimatedTokens: number
+): string {
+  return formatRow({
+    time: formatTime(isoTimestamp),
+    action: action === "create" ? "Create" : "Edit",
+    files: truncatePath(filePath),
+    outcome: description || "\u2014",
+    tokens: `~${estimatedTokens}`,
+  });
+}
+
+export function formatSessionEndRow(summary: SessionSummary): string {
+  const filesSet = new Set<string>();
+  for (const r of summary.reads) filesSet.add(r.filePath);
+  for (const w of summary.writes) filesSet.add(w.filePath);
+
+  return formatRow({
+    time: formatTime(summary.endTimestamp),
+    action: "Session end",
+    files: "\u2014",
+    outcome: `${summary.totals.writeCount} writes across ${filesSet.size} files | ~${summary.totals.estimatedTokens} tok total`,
+    tokens: "\u2014",
+  });
+}
+
+export function formatConsolidatedLine(
+  date: string,
+  readCount: number,
+  writeCount: number,
+  estimatedTokens: number,
+  keyFiles: string[]
+): string {
+  const files = keyFiles.slice(0, 5).join(", ");
+  return `> **${date}** \u2014 ${readCount} reads | ${writeCount} writes | ~${estimatedTokens} tokens | key files: ${files}\n`;
+}
+
+// ── I/O Operations ──────────────────────────────────────────────────────────
+
+export function appendToLog(logPath: string, text: string): void {
+  try {
+    safeAppendText(logPath, text);
+  } catch {
+    // Retry once
+    try {
+      safeAppendText(logPath, text);
+    } catch {
+      console.warn(
+        `[mink] Warning: failed to append to action log at ${logPath}`
+      );
+    }
+  }
+}
+
+export function safeReadLog(logPath: string): string {
+  try {
+    return readFileSync(logPath, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+// ── Consolidation ───────────────────────────────────────────────────────────
+
+const SESSION_HEADER_RE = /^### Session \u2014 (\d{4}-\d{2}-\d{2}) \d{2}:\d{2}$/gm;
+
+export function parseLogSessions(content: string): ParsedSession[] {
+  const sessions: ParsedSession[] = [];
+  const headerMatches: Array<{ index: number; date: string }> = [];
+
+  let match: RegExpExecArray | null;
+  SESSION_HEADER_RE.lastIndex = 0;
+  while ((match = SESSION_HEADER_RE.exec(content)) !== null) {
+    headerMatches.push({ index: match.index, date: match[1] });
+  }
+
+  for (let i = 0; i < headerMatches.length; i++) {
+    const startIndex = headerMatches[i].index;
+    const endIndex =
+      i + 1 < headerMatches.length ? headerMatches[i + 1].index : content.length;
+    const sessionContent = content.slice(startIndex, endIndex);
+
+    // Count data rows: lines starting with "| " that are not header or separator
+    const lines = sessionContent.split("\n");
+    let entryCount = 0;
+    for (const line of lines) {
+      if (
+        line.startsWith("| ") &&
+        !line.startsWith("| Time") &&
+        !line.startsWith("| ---")
+      ) {
+        entryCount++;
+      }
+    }
+
+    sessions.push({
+      startIndex,
+      endIndex,
+      date: headerMatches[i].date,
+      entryCount,
+      content: sessionContent,
+    });
+  }
+
+  return sessions;
+}
+
+export function identifySessionsToConsolidate(
+  sessions: ParsedSession[],
+  config: ConsolidationConfig,
+  now: Date = new Date()
+): number[] {
+  // Check total entry count
+  let totalEntries = 0;
+  for (const s of sessions) totalEntries += s.entryCount;
+
+  if (totalEntries <= config.maxEntries) return [];
+
+  const cutoff = new Date(now);
+  cutoff.setDate(cutoff.getDate() - config.retentionDays);
+  const cutoffStr = cutoff.toISOString().slice(0, 10);
+
+  const indices: number[] = [];
+  for (let i = 0; i < sessions.length; i++) {
+    if (sessions[i].date < cutoffStr) {
+      indices.push(i);
+    }
+  }
+
+  return indices;
+}
+
+function extractSessionStats(
+  session: ParsedSession
+): { readCount: number; writeCount: number; estimatedTokens: number; keyFiles: string[] } {
+  let readCount = 0;
+  let writeCount = 0;
+  let estimatedTokens = 0;
+  const fileSet = new Set<string>();
+
+  const lines = session.content.split("\n");
+  for (const line of lines) {
+    if (
+      !line.startsWith("| ") ||
+      line.startsWith("| Time") ||
+      line.startsWith("| ---")
+    ) {
+      continue;
+    }
+
+    // Parse table row: | time | action | file | outcome | ~tokens |
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((c) => c.trim());
+    if (cells.length < 5) continue;
+
+    const action = cells[1];
+    const file = cells[2];
+    const tokenStr = cells[4];
+
+    if (action === "Read") {
+      readCount++;
+      if (file !== "\u2014") fileSet.add(file);
+    } else if (action === "Create" || action === "Edit") {
+      writeCount++;
+      if (file !== "\u2014") fileSet.add(file);
+    }
+
+    if (tokenStr.startsWith("~")) {
+      const n = parseInt(tokenStr.slice(1), 10);
+      if (!isNaN(n)) estimatedTokens += n;
+    }
+  }
+
+  return {
+    readCount,
+    writeCount,
+    estimatedTokens,
+    keyFiles: [...fileSet].slice(0, 5),
+  };
+}
+
+export function consolidateLog(
+  logPath: string,
+  config: ConsolidationConfig = { maxEntries: 200, retentionDays: 7 },
+  now?: Date
+): void {
+  const content = safeReadLog(logPath);
+  if (!content) return;
+
+  const sessions = parseLogSessions(content);
+  if (sessions.length === 0) return;
+
+  const toConsolidate = identifySessionsToConsolidate(sessions, config, now);
+  if (toConsolidate.length === 0) return;
+
+  const consolidateSet = new Set(toConsolidate);
+  const parts: string[] = [];
+
+  for (let i = 0; i < sessions.length; i++) {
+    if (consolidateSet.has(i)) {
+      const stats = extractSessionStats(sessions[i]);
+      parts.push(
+        formatConsolidatedLine(
+          sessions[i].date,
+          stats.readCount,
+          stats.writeCount,
+          stats.estimatedTokens,
+          stats.keyFiles
+        )
+      );
+    } else {
+      parts.push(sessions[i].content);
+    }
+  }
+
+  atomicWriteText(logPath, parts.join(""));
+}
+
+// ── Factory ─────────────────────────────────────────────────────────────────
+
+export interface ActionLogWriter {
+  appendSessionHeader(isoTimestamp: string): void;
+  appendReadEntry(
+    isoTimestamp: string,
+    filePath: string,
+    indexHit: boolean,
+    estimatedTokens: number
+  ): void;
+  appendWriteEntry(
+    isoTimestamp: string,
+    filePath: string,
+    action: "create" | "edit",
+    description: string,
+    estimatedTokens: number
+  ): void;
+  appendSessionEnd(summary: SessionSummary): void;
+}
+
+export function createActionLogWriter(logPath: string): ActionLogWriter {
+  return {
+    appendSessionHeader(isoTimestamp: string): void {
+      appendToLog(logPath, formatSessionHeader(isoTimestamp));
+    },
+
+    appendReadEntry(
+      isoTimestamp: string,
+      filePath: string,
+      indexHit: boolean,
+      estimatedTokens: number
+    ): void {
+      appendToLog(logPath, formatReadRow(isoTimestamp, filePath, indexHit, estimatedTokens));
+    },
+
+    appendWriteEntry(
+      isoTimestamp: string,
+      filePath: string,
+      action: "create" | "edit",
+      description: string,
+      estimatedTokens: number
+    ): void {
+      appendToLog(logPath, formatWriteRow(isoTimestamp, filePath, action, description, estimatedTokens));
+    },
+
+    appendSessionEnd(summary: SessionSummary): void {
+      appendToLog(logPath, formatSessionEndRow(summary));
+    },
+  };
+}

package/src/core/backup.ts

@@ -0,0 +1,122 @@
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  statSync,
+} from "fs";
+import { join } from "path";
+import { projectDir, backupDirPath } from "./paths";
+import type { BackupInfo } from "../types/backup";
+
+function formatTimestamp(date: Date): string {
+  const y = date.getFullYear();
+  const mo = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  const h = String(date.getHours()).padStart(2, "0");
+  const mi = String(date.getMinutes()).padStart(2, "0");
+  const s = String(date.getSeconds()).padStart(2, "0");
+  const ms = String(date.getMilliseconds()).padStart(3, "0");
+  return `${y}${mo}${d}-${h}${mi}${s}${ms}`;
+}
+
+function copyDirectoryFiles(
+  srcDir: string,
+  destDir: string,
+  excludeDirs: string[]
+): void {
+  mkdirSync(destDir, { recursive: true });
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (excludeDirs.includes(entry.name)) continue;
+      copyDirectoryFiles(
+        join(srcDir, entry.name),
+        join(destDir, entry.name),
+        excludeDirs
+      );
+    } else if (entry.isFile()) {
+      writeFileSync(
+        join(destDir, entry.name),
+        readFileSync(join(srcDir, entry.name))
+      );
+    }
+  }
+}
+
+export function createBackup(cwd: string): string {
+  const base = `backup-${formatTimestamp(new Date())}`;
+  const dir = backupDirPath(cwd);
+  let name = base;
+  let suffix = 1;
+  while (existsSync(join(dir, name))) {
+    name = `${base}-${suffix}`;
+    suffix++;
+  }
+  const src = projectDir(cwd);
+  const dest = join(dir, name);
+  copyDirectoryFiles(src, dest, ["backups"]);
+  return name;
+}
+
+export function listBackups(cwd: string): BackupInfo[] {
+  const dir = backupDirPath(cwd);
+  if (!existsSync(dir)) return [];
+
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const backups: BackupInfo[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith("backup-")) continue;
+
+    const backupPath = join(dir, entry.name);
+    const match = entry.name.match(
+      /^backup-(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})(\d{3})?(?:-\d+)?$/
+    );
+    let timestamp: Date;
+    if (match) {
+      timestamp = new Date(
+        parseInt(match[1]),
+        parseInt(match[2]) - 1,
+        parseInt(match[3]),
+        parseInt(match[4]),
+        parseInt(match[5]),
+        parseInt(match[6]),
+        match[7] ? parseInt(match[7]) : 0
+      );
+    } else {
+      timestamp = statSync(backupPath).mtime;
+    }
+
+    let fileCount = 0;
+    try {
+      fileCount = readdirSync(backupPath).length;
+    } catch {
+      // ignore
+    }
+
+    backups.push({ name: entry.name, timestamp, path: backupPath, fileCount });
+  }
+
+  backups.sort((a, b) => {
+    const timeDiff = b.timestamp.getTime() - a.timestamp.getTime();
+    if (timeDiff !== 0) return timeDiff;
+    // Same timestamp — sort by name descending so suffixed names come first
+    return b.name.localeCompare(a.name);
+  });
+  return backups;
+}
+
+export function restoreBackup(cwd: string, backupName: string): void {
+  const backupPath = join(backupDirPath(cwd), backupName);
+  if (!existsSync(backupPath)) {
+    throw new Error(`backup not found: ${backupName}`);
+  }
+
+  // Create a safety backup before restoring
+  createBackup(cwd);
+
+  // Copy files from backup to project dir, excluding backups/
+  copyDirectoryFiles(backupPath, projectDir(cwd), ["backups"]);
+}

package/src/core/bug-memory.ts

@@ -0,0 +1,223 @@
+import { safeReadJson, atomicWriteJson } from "./fs-utils";
+import type { BugEntry, BugMemory, SimilarityMatch } from "../types/bug-memory";
+
+export function createEmptyBugMemory(): BugMemory {
+  return { entries: [], nextId: 1 };
+}
+
+export function loadBugMemory(path: string): BugMemory {
+  const raw = safeReadJson(path);
+  if (raw !== null && isBugMemory(raw)) return raw;
+  return createEmptyBugMemory();
+}
+
+export function saveBugMemory(path: string, memory: BugMemory): void {
+  atomicWriteJson(path, memory);
+}
+
+export function isBugMemory(value: unknown): value is BugMemory {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return Array.isArray(obj.entries) && typeof obj.nextId === "number";
+}
+
+export function generateBugId(nextId: number): string {
+  return `bug-${String(nextId).padStart(3, "0")}`;
+}
+
+export function findDuplicate(
+  memory: BugMemory,
+  errorMessage: string,
+  filePath: string
+): BugEntry | null {
+  return (
+    memory.entries.find(
+      (e) => e.errorMessage === errorMessage && e.filePath === filePath
+    ) ?? null
+  );
+}
+
+export function addBugEntry(
+  memory: BugMemory,
+  fields: Omit<BugEntry, "id" | "createdAt" | "lastSeenAt" | "occurrenceCount">
+): BugMemory {
+  const existing = findDuplicate(memory, fields.errorMessage, fields.filePath);
+  if (existing) {
+    return updateOccurrence(memory, existing.id);
+  }
+
+  const now = new Date().toISOString();
+  const entry: BugEntry = {
+    id: generateBugId(memory.nextId),
+    createdAt: now,
+    lastSeenAt: now,
+    occurrenceCount: 1,
+    ...fields,
+  };
+
+  return {
+    entries: [...memory.entries, entry],
+    nextId: memory.nextId + 1,
+  };
+}
+
+export function updateOccurrence(memory: BugMemory, id: string): BugMemory {
+  const now = new Date().toISOString();
+  return {
+    ...memory,
+    entries: memory.entries.map((e) =>
+      e.id === id
+        ? { ...e, occurrenceCount: e.occurrenceCount + 1, lastSeenAt: now }
+        : e
+    ),
+  };
+}
+
+// --- Similarity scoring ---
+
+function tokenize(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((w) => w.length > 0)
+  );
+}
+
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const word of a) {
+    if (b.has(word)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+export function computeSimilarity(
+  query: string,
+  entry: BugEntry
+): SimilarityMatch {
+  const matchReasons: string[] = [];
+  let score = 0;
+
+  // 1. Exact substring match on error message
+  if (
+    entry.errorMessage.length > 0 &&
+    entry.errorMessage.includes(query)
+  ) {
+    score += 1.0;
+    matchReasons.push("exact_error_match");
+  }
+
+  // 2. Word overlap (Jaccard) across searchable fields
+  const queryTokens = tokenize(query);
+
+  const fields: [string, string][] = [
+    ["error_message", entry.errorMessage],
+    ["root_cause", entry.rootCause],
+    ["fix", entry.fixDescription],
+    ["tags", entry.tags.join(" ")],
+  ];
+
+  for (const [fieldName, fieldValue] of fields) {
+    const fieldTokens = tokenize(fieldValue);
+    const j = jaccard(queryTokens, fieldTokens);
+    if (j > 0) {
+      score += j * 0.5;
+      matchReasons.push(fieldName);
+    }
+  }
+
+  return { entry, score, matchReasons };
+}
+
+function hasFilePathMatch(entry: BugEntry, filePath?: string): boolean {
+  if (!filePath) return false;
+  return entry.filePath === filePath;
+}
+
+function hasTagOverlap(entry: BugEntry, query: string): boolean {
+  const queryTokens = tokenize(query);
+  return entry.tags.some((tag) => queryTokens.has(tag.toLowerCase()));
+}
+
+export function searchBugs(
+  memory: BugMemory,
+  query: string,
+  options?: { filePath?: string }
+): SimilarityMatch[] {
+  if (memory.entries.length === 0 || query.trim().length === 0) return [];
+
+  const results: SimilarityMatch[] = [];
+
+  for (const entry of memory.entries) {
+    const match = computeSimilarity(query, entry);
+
+    // False positive guard: require file-path match OR tag overlap
+    const fileMatch = hasFilePathMatch(entry, options?.filePath);
+    const tagMatch = hasTagOverlap(entry, query);
+    if (!fileMatch && !tagMatch && match.score <= 0.3) continue;
+
+    // Boost same-file matches
+    if (fileMatch) {
+      match.score += 0.2;
+      if (!match.matchReasons.includes("file_path")) {
+        match.matchReasons.push("file_path");
+      }
+    }
+
+    if (match.score > 0.3) {
+      results.push(match);
+    }
+  }
+
+  return results.sort((a, b) => b.score - a.score);
+}
+
+export function lookupBugsForFile(
+  memory: BugMemory,
+  filePath: string
+): BugEntry[] {
+  return memory.entries
+    .filter((e) => e.filePath === filePath)
+    .sort(
+      (a, b) =>
+        new Date(b.lastSeenAt).getTime() - new Date(a.lastSeenAt).getTime()
+    );
+}
+
+export function formatBugSummary(entries: BugEntry[]): string | null {
+  if (entries.length === 0) return null;
+
+  const lines: string[] = ["[mink] Known bugs for this file:"];
+  const shown = entries.slice(0, 3);
+
+  for (const e of shown) {
+    lines.push(`  ${e.id}: ${e.errorMessage}`);
+    lines.push(`    Root cause: ${e.rootCause}`);
+    lines.push(`    Fix: ${e.fixDescription}`);
+    if (e.occurrenceCount > 1) {
+      lines.push(`    Seen ${e.occurrenceCount} times (last: ${e.lastSeenAt})`);
+    }
+  }
+
+  if (entries.length > 3) {
+    lines.push(`  ... and ${entries.length - 3} more`);
+  }
+
+  return lines.join("\n");
+}
+
+export function hasBugForFileInSession(
+  memory: BugMemory,
+  filePath: string,
+  sessionStartTimestamp: string
+): boolean {
+  const sessionStart = new Date(sessionStartTimestamp).getTime();
+  return memory.entries.some(
+    (e) =>
+      e.filePath === filePath &&
+      new Date(e.createdAt).getTime() >= sessionStart
+  );
+}